# Codemaps - 바이브 코딩 전에 코드를 이해하세요 > Clean Markdown view of GeekNews topic #24175. Use the original source for factual precision when an external source URL is present. ## Metadata - GeekNews HTML: [https://news.hada.io/topic?id=24175](https://news.hada.io/topic?id=24175) - GeekNews Markdown: [https://news.hada.io/topic/24175.md](https://news.hada.io/topic/24175.md) - Type: GN+ - Author: [xguru](https://news.hada.io/@xguru) - Published: 2025-11-06T10:44:47+09:00 - Updated: 2025-11-06T10:44:47+09:00 - Original source: [cognition.ai](https://cognition.ai/blog/codemaps) - Points: 22 - Comments: 3 ## Summary AI가 코드를 대신 써주는 시대지만, 진짜 문제는 **“코드를 얼마나 이해하느냐”**에 있습니다. **Windsurf Codemaps**는 SWE‑1.5와 Claude Sonnet 4.5를 기반으로 코드베이스를 **시각적 맵과 AI 주석**으로 구조화해, 복잡한 프로젝트의 흐름을 한눈에 파악하고 **정확한 코드 위치로 즉시 이동**할 수 있게 합니다. 단순 자동화가 아닌 **이해 중심의 엔지니어링**을 지향하며, `@{codemap}` 참조를 통해 에이전트의 맥락 이해력까지 높입니다. “두뇌를 끄는 AI”가 아니라 “두뇌를 켜는 AI”라는 표현이 딱 어울리는 도구로, 코드와 진짜로 대화하고 싶은 개발자에게 특히 흥미로운 시도입니다. ## Topic Body - **Windsurf Codemaps**는 AI가 주석을 단 구조적 코드 맵으로, 개발자가 코드베이스를 빠르고 정확히 이해하도록 지원하는 **새로운 코드 탐색 도구** - 기존 AI 코딩 도구들이 코드 작성 자동화에 집중한 반면, Codemaps는 **이해 중심의 엔지니어링**을 목표로 하며 SWE‑1.5와 Claude Sonnet 4.5 모델을 기반으로 작동 - 코드베이스 내 기능 흐름을 시각적으로 표시하고, **정확한 코드 위치로 즉시 이동**하거나 “trace guide”를 통해 관련 코드 그룹의 설명을 확인 가능 - Cascade 등 기존 채팅형 에이전트보다 **맥락 연결성과 탐색 효율**이 높으며, `@{codemap}` 참조 기능으로 에이전트의 작업 성능 향상 - AI가 단순 대체가 아닌 **엔지니어의 이해력과 책임성을 강화하는 협업 도구**로 자리매김함 --- ### 코드 이해의 중요성과 Codemaps의 등장 - 소프트웨어 개발은 단순한 코딩이 아니라 **문제에 대한 이해**에서 출발 - AI가 코드를 대신 작성하는 도구는 생산성을 높이지만, 개발자와 코드 간의 **이해 단절**을 초래 - 고난도·고가치 작업에서는 이러한 분리가 **치명적 비효율**로 이어짐 - Cognition은 “두뇌를 끄는 AI가 아니라 **두뇌를 켜는 AI**”가 필요하다고 강조 - Codemaps는 SWE‑1.5와 Claude Sonnet 4.5 기반의 **AI 주석형 코드 맵**으로, DeepWiki와 Ask Devin의 기술을 확장한 형태 ### 왜 Codemaps인가 - 모든 엔지니어링 작업은 **코드 이해**에서 시작되며, 대규모 코드베이스는 탐색과 기억에 많은 시간을 소모 - 신규 엔지니어는 완전한 숙련까지 **3~9개월**, 시니어는 주당 **5시간 이상** 온보딩에 사용 - Stripe 조사에 따르면 **레거시 유지보수**가 생산성 저하의 주요 원인 - 기존 AI 코딩 도구들은 일반적 질의응답 중심으로, **집중적 온보딩과 정밀 탐색**을 지원하지 못함 - Codemaps는 이러한 한계를 해결하기 위한 **정확한 코드 기반 맵핑 도구**로 설계 ### 실시간 문제 중심 맵핑 기능 - Windsurf 내에서 **Cmd + Shift + C**로 실행하며, 작업 목표를 입력하거나 자동 제안을 선택 - **Fast(SWE‑1.5)** 또는 **Smart(Sonnet 4.5)** 모드 중 선택 가능 - 각 Codemap은 코드 스냅샷을 기반으로 하며 **ZDR 원칙**을 준수 - 시각적 노드 맵을 통해 코드 구조를 탐색하고, 클릭 시 **정확한 코드 위치로 이동** - “See more” 옵션을 통해 **trace guide**를 열면 코드 그룹의 설명을 상세히 확인 가능 - Cascade 내에서 `@{codemap}`을 호출해 특정 섹션을 참조하면 **에이전트의 맥락 이해와 성능**이 향상 ### ‘Vibeslop’에 맞서는 접근 - “Vibe coding”이 무분별한 AI 코드 생성으로 변질되며, **이해 없는 코드 유지보수**가 문제로 지적 - Codemaps는 인간과 AI가 **시스템 구조·데이터 흐름·의존성**을 공유하도록 하여 이해 격차를 해소 - 엔지니어의 역할은 작성자에서 **책임자(accountability)** 로 이동하며, 이해를 통해 품질을 보장 - 목표는 속도뿐 아니라 **엔지니어가 흐름을 유지하며 복잡한 문제를 자신 있게 해결**하도록 돕는 것 - AI는 단순 대체가 아니라 **고가치 작업을 강화하고 저가치 작업을 경감**하는 협력 수단으로 제시 ### 향후 계획 - Codemaps는 내부 에이전트의 **인덱싱·분석 결과를 인간에게 시각화**한 첫 단계 - 현재 팀 간 공유 및 학습용으로 활용 가능 - 향후 Devin·Cascade 등 에이전트의 문제 해결력 향상 효과를 **벤치마크 예정** - Codemap 간 연결·주석 기능과 **오픈 `.codemap` 프로토콜** 정의를 검토 중 - Fast Context 기능과 결합해 **자동 맥락 엔지니어링**을 인간이 읽을 수 있는 형태로 발전시키는 목표 - 최신 Windsurf 및 DeepWiki 버전에서 Codemaps 사용 가능 ## Comments ### Comment 46015 - Author: galadbran - Created: 2025-11-07T09:26:38+09:00 - Points: 1 deepwiki 를 사용할 때마다 감탄하는데, 그래서 이 기능도 기대됩니다! ### Comment 45980 - Author: tested - Created: 2025-11-06T12:38:52+09:00 - Points: 1 VS Code에도 나왔으면 ### Comment 45963 - Author: neo - Created: 2025-11-06T10:44:48+09:00 - Points: 1 ###### [Hacker News 의견](https://news.ycombinator.com/item?id=45813767) - 이 글을 읽고 생각해보니 몇 가지 짚을 점이 있음 이건 또 하나의 **Fortune 500 대상 AI 제품**으로 보임. 중소 규모 팀에는 잘 맞지 않을 수도 있음 사실 이런 **정적 분석 기반 다이어그램 도구**는 오래전부터 있었고, LLM이 대신 그려준다는 점 외엔 새로움이 크지 않음 온보딩은 단순히 플로우차트 보여주는 게 아니라, 팀이 가진 **문제 맥락**을 공유하는 게 핵심임. CRUD나 MVC 같은 보일러플레이트보단, 우리 팀만의 특이한 패턴과 제약을 설명하는 게 더 중요함 - 정적 분석만으로 시각화하면 **무엇을 보여줄지 판단하는 유연성**이 부족함 LLM이 만든 시각화의 장점은 이런 판단력과 상식이 들어가서 더 **직관적**이라는 점임 - 나도 오늘 xkcd의 “Lucky 10,000” 중 한 명이 된 기분임 혹시 이런 정적 분석 도구 추천해줄 사람 있음? 가능하면 오픈소스면 좋겠고, Python, Java, JavaScript(특히 Angular) 지원이면 더 좋음 - Windsurf를 오랜만에 켜서 “Upgrade Available”을 눌렀더니 [이 페이지](https://windsurf.com/editor/update-linux)로 이동했음 안내된 명령어 `sudo apt-get upgrade windsurf`는 사실상 시스템 전체 패키지를 업그레이드하는 위험한 명령어임 다행히 직접 `sudo apt-get install --only-upgrade windsurf`로 해결했음 어쨌든 새로 추가된 **Codemaps 기능**은 꽤 멋지고 시도해볼 가치가 있음 - `apt-get upgrade $PACKAGE`의 **비직관적인 문법**은 정말 이상함. 실제 올바른 구문이 매뉴얼에도 없음 - 팀이 이 피드백을 보고 바로 수정했다고 함 ```diff - sudo apt-get upgrade windsurf + sudo apt-get install windsurf ``` - 그 문법의 장점이 뭔지 여전히 모르겠음. 정말 헷갈림 - 더 많은 사람들이 Windsurf를 써봤으면 좋겠음 나는 시니어 엔지니어로서 **에이전트형 코딩**과 일반 코딩을 병행하는데, Windsurf는 과소평가된 툴임 Codemaps 기능이 처음 나왔을 때 정말 반가웠음 - 나도 비슷한 입장임. 회사에서 Windsurf를 쓰고 있고 UX가 진짜 강점임 Codemaps는 몇 주째 쓰는 중인데 훌륭함. 코드 변경이 많아지면 유지보수가 번거로울 수도 있지만 해결 가능해 보임 - 나는 **로그인 강제**나 생태계 종속이 없는 Zed 같은 IDE를 선호함 - 이 글 보고 나도 한번 써볼 생각임. abacus.ai IDE, claude CLI 등 여러 툴을 써봤지만 아직 완벽한 워크플로우를 못 찾았음 - 왜 아직도 **VSCode 내장 Copilot** 얘기가 안 나오는지 의문임 나는 Sonnet 4, Sequential Thinking, Tavily MCP 서버 조합으로 SaaS 프로토타입을 빠르게 만들었음. 가격도 합리적임 - Windsurf 팬이지만 요즘은 **Codex**로 완전히 옮겼음. 클라우드 환경이 너무 편리함 Windsurf도 좋지만 가격 정책 때문에 회사 전체 도입은 포기했음 - 흥미로운 아이디어이긴 하지만, 생성된 다이어그램이 **정확하지 않다면 오히려 오해를 낳을 위험**이 있음 결국 사람이 다시 검증해야 한다면 도구의 목적이 무색해짐 - 사실 “코드를 진짜로 이해하려는 사람”이 아니라면, 다이어그램은 그냥 상사에게 보여줄 **형식적인 산출물**일 뿐일 수도 있음 - 이런 기능은 **비즈니스 맥락이 빠진 코드 연결도**만 보여주기 때문에 실용성이 떨어짐 AI는 아키텍처의 “왜”를 이해하지 못함. 결국 설계 문서와 코드 읽기가 더 낫다고 생각함 - 게다가 많은 **비즈니스 맥락은 사람 머릿속**에 있음. 진짜 엔지니어 수준이 되려면 AI가 사람에게 직접 질문해야 함 - 하지만 맥락을 **명시적으로 제공**하면 LLM의 출력 품질은 확실히 좋아짐 - 미래에는 프롬프트에 비즈니스 맥락이 포함되면 AI도 그 “왜”를 이해하게 될 것임 - 사실 코드 안에도 꽤 많은 **업무 맥락이 스며 있음** [deepwiki 예시](https://deepwiki.com/search/vimfnfnname-lets-you-call-neov_e07b9c0f-9760-48c6-821c-70913d9a30f9)나 [Codemap 링크](https://windsurf.com/codemaps/87532afd-092d-401d-aa3f-0121c7c630f6-9c31d1b423ebcd21)만 봐도 알 수 있음 디버깅할 때는 사실 그 정도 정보면 충분함 - 코딩이 언제부터 이렇게 “비즈니스 맥락” 중심이 됐는지 모르겠음. 기술적 이해만으로도 충분히 가치 있음 - 이런 접근이 문제 해결의 **올바른 방향**이라고 생각함 반쯤 작동하는 AI 제품을 만드는 대신, 코드베이스를 **사람과 LLM이 이해하기 쉽게 만드는 것**이 더 중요함 이런 **자기 문서화 시스템**은 대기업의 개발 피로도를 줄일 수 있음 - 나도 두 가지 접근을 병행함. 새 코드베이스를 이해할 때는 시각화가 유용하지만, 이후에는 결국 생산성이 중요함 - (공동저자) 질문 환영함! 1분짜리 [데모 영상](https://x.com/cognition/status/1985755284527010167) 참고 가능 이건 Cognition CTO **Steven**의 아이디어임. 그는 스포트라이트를 싫어하지만 이번엔 정말 잘했음 [그의 트윗](https://x.com/stevenkplus1/status/1985767277376241827)도 참고 바람 - 대규모 코드베이스에서도 잘 작동하는 예시가 있는지 궁금함. 작은 프로젝트는 LLM으로도 괜찮지만, **복잡한 코드**가 진짜 시험대임 - 제안 하나 있음 — Codemaps를 **사이드바가 아닌 메인 패널**에서도 볼 수 있게 해줬으면 함. 지금은 너무 좁음 - 3년 전 비슷한 아이디어로 사이드 프로젝트를 만든 적 있음 LLM이 뜨기 전이라 직접 **AST 파서**를 만들어 Go와 Java 코드의 관계를 추출하고 Graphviz로 시각화했음 정규식 기반 필터도 추가했는데, 낯선 코드베이스를 이해할 때 정말 유용했음 지금은 [packagemap.co](https://packagemap.co)에 남아 있지만 많이 낡았음 - 나도 비슷한 걸 했는데, **Go 언어용 3D 시각화**였음 개발자가 코드 구조를 공간적으로 파악하고, **VR 환경**에서 맥락을 보며 작업하는 게 목표였음 관련 글은 [여기](https://divan.dev/posts/visual_programming_go/)에 있음 - 기능 제안: **Github Action**으로 리포지토리의 Codemap을 자동 생성해 README에 포함하고, 주요 PR 시 자동 업데이트되면 좋겠음 - 코드 시각화 아이디어는 멋지지만, 종종 **“나쁜 아이디어에 빠져드는” 위험**이 있음 대부분의 다이어그램은 의도한 의미를 잘 전달하지 못하고, 오히려 해석에 시간이 듦 사람들은 실제로는 코드나 수학을 읽으며 머릿속에 **자신만의 시각화 모델**을 만듦 예를 들어 Flutter 앱을 시각화했는데 위젯 트리 구조가 드러나지 않는다면, 내 **정신적 모델**과 충돌함 결국 이런 시각화는 소설을 읽을 때 머릿속에 장면이 그려지는 것과 비슷함. LLM이 “보고 싶은 코드 영화”를 만들어줄 기술인지는 아직 확신이 없음