AI 코딩 지원을 사용하면서, 이런 경험을 해본 적 없으신가요?

"이 버그 좀 고쳐줘"라고 리포지토리(Repository)째로 넘겼는데, 전혀 상관없는 파일을 건드린다.

"이 기능은 어디에 구현되어 있어?"라고 물었더니, 그럴싸하지만 미묘하게 어긋난 답변이 돌아온다.

작은 Toy 프로젝트에서는 천재인데, 실무의 진짜 코드베이스(Codebase)가 되는 순간 갑자기 의지할 수 없게 된다.

그 느낌... 다들 있으시죠?

솔직히 말씀드리겠습니다. 그건 AI가 똑똑하지 않아서가 아닙.

우리가 지도를 건네주지 않았기 때문입니다.

이 기사에서는 "코드베이스를 AI에게 통째로 넘기는 것"을 그만두고, 코드베이스를 '지도'로 변환한 뒤에 맡기는 발상과 그 구체적인 절차를 적겠습니다. 내일 당장 자신의 리포지토리에서 바로 테스트해 볼 수 있는 코드와 프롬프트(Prompt)를 풍부하게 담았습니다. AI 개발에 아직 익숙하지 않은 분들도 읽어나갈 수 있도록 전문 용어는 나올 때마다 풀어서 설명하겠습니다.

목표는 하나입니다. "거대한 코드가 두렵지 않게 되는 것". 그것뿐입니다.

먼저, 흔히 발생하는 실패 사례를 떠올려 봅시다.

당신은 처음 접하는 5,000개 정도의 파일로 구성된 중규모 리포지토리에 배정되었습니다. "결제 관련 버그를 고치고 싶다". 일단 이렇게 합니다.

grep -rn "checkout" .
# → 217건 히트. controller, service, util, test, 설정 파일… 어떤 것이 핵심인지 모르겠다

200건 이상의 히트. 어떤 것이 본체이고 어떤 것이 단순한 명명 중복인지, 얼핏 봐서는 알 수 없습니다. 이것은 인간도 길을 잃는 "grep 지옥"이죠.

그래서 생각하게 됩니다. "AI에게 전부 읽히면 한 번에 해결되지 않을까?"라고.

하지만 5,000개 파일을 전부 채팅창에 붙여넣을 수는 없습니다. 설령 붙여넣을 수 있다 하더라도, AI는 어디가 중요하고 어디가 옆길인지를 전달받지 못했기 때문에 결국 당신과 똑같이 길을 잃게 됩니다.

여기서 중요한 깨달음이 하나 있습니다.

정보를 찾는 것과 이해하는 것은 전혀 다릅니다.

grep은 "정보를 찾는 것"은 잘합니다. 하지만 "이 코드베이스가 어떻게 구성되어 있는가"를 이해하는 것은 또 다른 이야기입니다. 그리고 지금의 AI에게 부족한 것은 대개 후자입니다.

AI가 큰 코드 앞에서 약해지는 이유는 비교적 단순합니다. 3가지 장벽으로 요약할 수 있습니다.

① 창의 장벽 (컨텍스트 길이(Context Length)는 유한하다)

AI가 한 번에 읽을 수 있는 문장의 양(이를 "컨텍스트 윈도우(Context Window) = AI의 작업대 넓이"라고 생각하세요)에는 상한선이 있습니다. 작업대가 아무리 넓어진다 해도 수천 개의 파일을 통째로 펼쳐 놓을 수는 없습니다.

② 구조의 장벽 (의존 관계는 행간에 적혀 있지 않다)

설령 전부 읽을 수 있다 하더라도, 파일 A의 함수가 파일 B를 호출하고 그 설정은 파일 C에 있다...와 같은 "연결 고리"는 파일 하나를 훑어보는 것만으로는 보이지 않습니다. 아키텍처(Architecture, 전체 구조)는 코드의 "행간"에 숨어 있습니다.

③ 암묵지의 장벽 (코드에 적혀 있지 않은 사정)

"이 처리가 여기에 있는 이유는 3년 전 장애 대응의 흔적이다"와 같이, 코드 어디에도 적혀 있지 않은 지식. 팀의 머릿속에만 있는 "암묵지(Tribal Knowledge)"입니다. AI는 이 부분에 가장 접근하기 어렵습니다.

비유하자면 이런 느낌일 것입니다.

처음 온 마을에 온 관광객에게,

두꺼운 전화번호부를 쥐여준다고 해서 목적지에 도착할 수는 없습니다.

필요한 것은 노선도와 "관광 안내소는 여기"라고 적힌 지도 한 장입니다.

AI에게 "전화번호부(=전체 코드)"를 줘도 헤매는 것은 당연한 일입니다. 건네주어야 할 것은 지도입니다.

최근 몇 년간 AI 주변은 "컨텍스트 윈도우를 크게 만드는 경쟁"으로 뜨거웠습니다. 작업대를 점점 넓히는 방향이죠. 하지만 현장의 체감으로는, 그 방향이 아닌 것 같다는 생각이 듭니다.

실제로 2026년의 AI 코딩 흐름은 확실히 변하고 있습니다. "더 큰 창에 통째로 맡기기"에서, "영구적이고 구조화된 '코드베이스 지도(Repo Map)'를 AI가 참조하게 하기" 방향으로. 몇 가지 실재하는 도구를 예로 들어 두겠습니다 (모두 사고방식의 참고가 됩니다).

• Aider(오픈소스 CLI 에이전트)의 repo map: Tree-sitter(=코드를 문법적으로 분석하여 함수나 클래스와 같은 "부품"을 추출하는 도구)를 사용하여 리포지토리 전체에서 심볼(클래스명, 함수명, 호출 형태)을 추출하고, 현재 태스크와 관련이 높은 순서로 정렬하여 컴팩트하게 AI에게 전달합니다. 모든 파일을 읽지 않고도 다중 파일 편집에 강점이 있습니다.
• Repomix: 리포지토리 전체를 AI가 읽기 쉬운 구조화된 텍스트(한 장으로 정리된 팩)로 변환하는 도구.
• ctags / Tree-sitter: "어디에 무엇이 정의되어 있는가"에 대한 심볼 인덱스를 만드는, 오래전부터 사용되어 온 정석적인 방법.

공통점은 **"코드를 그대로 전달하는" 것이 아니라, "코드에서 '색인과 지도'를 만들어 전달한다"**는 발상입니다. 대형 개발 조직에서도 거대한 파이프라인의 암묵지(Tacit Knowledge)를 AI를 위한 내비게이션 가이드로 작성하게 하는 등의 시도가 나오고 있습니다.

저는 이것을 한마디로 "정지(整地, 지반 다지기)"라고 부릅니다.

빈 땅인 정글에 AI를 던져 넣는 것이 아니라, 먼저 길을 낸 다음에 걷게 하는 것입니다. 지반을 다지는 작업은 조금 지루한 작업입니다. 하지만 이 과정을 하느냐 안 하느냐에 따라 AI의 퍼포먼스는 완전히 달라진다고 생각합니다.

그렇다면 지도는 어떻게 만들까요? 어려워 보일 수 있지만, 대략 3개의 층으로 나누면 한결 만들기 쉬워집니다.

• 부감 맵(Overview Map): 상공에서 내려다본 전체도(디렉토리 구성, 규모, 진입점)
• 라우터 테이블(Router Table): "○○을 하고 싶다면 여기를 봐라"라는 길 안내 표
• 플로우 추적(Flow Tracing): 특정 기능 하나를 입구부터 출구까지 한 줄로 따라간 도표

순서대로 코드와 프롬프트를 통해 만들어 봅시다.

갑자기 코드를 읽게 하기 전에, 기계적으로 수집할 수 있는 사실을 한 장으로 정리합니다. 이 단계는 AI가 아니라 일반적인 명령어(Command)의 역할입니다.

#!/usr/bin/env bash
# repo-overview.sh — 코드베이스의 "항공 사진"을 한 장으로 출력
set -euo pipefail
...

이를 통해 "디렉토리 구성, 언어별 규모, 진입점으로 보이는 파일, 주요 함수의 정의 위치"가 한 장의 텍스트로 정리됩니다. 전체 코드가 아니라, 이 "목차"만을 AI에게 전달하는 것이 포인트입니다.

그다음, 첫 번째 요약을 요청합니다.

▼ 프롬프트 예시 ①: 부감 요약 만들기

당신은 이 코드베이스에 오늘 처음 참여한 시니어 엔지니어입니다. 
첨부된 repo-overview.txt(디렉토리 구성, 규모, 엔트리 포인트, 심볼 인덱스)만을 근거로, 
처음 보는 개발자를 위해 다음 내용을 일본어로(한국어로) 요약해 주세요. 추측한 부분은 "추측"이라고 명시할 것. 
...

포인트는 마지막의 "모르는 점을 질문하기" 부분입니다. AI에게 "모르는 것을 모른다고 말하게 함"으로써, 다음에 무엇을 전달해야 할지가 명확해집니다.

부감 다음은 길 안내 표입니다. 영어권에서는 "where to look for X" (X를 찾으려면 어디를 봐야 하는가)라고 불리기도 합니다. 이것이 지도의 가장 실용적인 부분이라고 생각합니다.

▼ 프롬프트 예시 ②: 라우터 테이블을 Markdown으로 작성하기

앞서 작성한 부감 내용과, 제가 추가로 첨부할 파일(라우팅 정의, 디렉토리 목록)을 근거로, 
"하고 싶은 작업 → 가장 먼저 봐야 할 곳"의 대응표를 Markdown 표 형식으로 만들어 주세요. 
- 열 구성: 하고 싶은 작업 / 관련 디렉토리·파일 / 진입점 함수 또는 루트 / 보충 설명 
...

나온 표는 그 자리에서 끝내지 말고 파일로 저장하여 자산화합니다. 예를 들어 docs/atlas/repo-map.md와 같은 위치에 두고 Git에 커밋해 둡니다. 이렇게 하면 다음에 오는 사람도, 다음에 움직일 AI도 같은 지도를 재사용할 수 있습니다. AI가 매번 제로 베이스에서 탐색할 필요가 없으므로, 은근히 토큰과 시간도 절약할 수 있습니다.

마지막은 특정 기능 하나를 입구부터 출구까지 한 줄로 따라가는 지도입니다. 버그 수정이나 기능 추가 전에 이것이 가장 효과적입니다.

다만, 여기서 AI에게 "결제 플로우를 전부 읽어줘"라고 통째로 맡기면 다시 미아가 되고 맙니다. 따라서 따라갈 재료를 기계적으로 수집한 다음에 전달합니다.

#!/usr/bin/env bash
# trace-symbol.sh — 특정 함수의 "호출자(Caller)·피호출자(Callee)" 후보를 수집
# 사용법: ./trace-symbol.sh createCheckout
...

이 출력(즉, "이 함수는 어디에 정의되어 있고, 어디에서 호출되며, 어떤 import와 함께 있는가")을 AI에게 전달하며 다음과 같이 요청합니다.

▼ 프롬프트 예시 ③: 기능 흐름을 한 줄로 따라가게 하기

첨부된 내용은 함수 createCheckout에 관한 grep 결과(정의·호출처·인접 import)입니다.
이 자료만을 근거로, "사용자가 결제 버튼을 누른 시점부터 결제가 확정될 때까지"의
처리 흐름(Flow)을 호출 순서대로 나열해 주세요.
...

이 단계에 이르면, AI는 "전체의 어느 부분을, 어떤 순서로 수정해야 하는지"를 근거를 바탕으로 대답할 수 있게 됩니다. 처음의 grep 지옥과는 이제 완전히 다른 세상이죠.

여기서 가장 중요한 부분입니다. 목소리 높여 강조하고 싶습니다.

AI가 만든 지도를 검수 없이 믿지 마세요.

이유는 세 가지입니다.

할루시네이션 (Hallucination, 환각): AI는 존재하지 않는 의존 관계나, 그럴듯해 보이지만 실제로는 존재하지 않는 함수를 아무렇지 않게 "그럴싸하게" 작성할 수 있습니다. 지도가 틀리면 그 위의 작업이 전부 어긋나게 됩니다.

지도의 노후화: 한 번 만든 지도는 코드가 변경되면 낡은 것이 됩니다. 반년 전 노선도를 보고 길을 찾으면 폐선된 역에 도착하는 것과 같은 일이 벌어집니다.

기밀 유출: 사내 코드를 안일하게 외부 서비스에 붙여넣는 것은 규약 및 보안 관점에서 문제가 될 수 있습니다. 무엇을 외부에 노출해도 되는지는 반드시 인간이 선을 그어야 합니다.

지도를 검수하기 위한 프롬프트를 하나 더 추가해 두면 안전합니다.

▼ 프롬프트 예시 ④ (검수용): 모든 근거를 제시하게 하기

당신이 작성한 라우터 표(Router table) 및 플로우 차트(Flow chart)에 대해,
각 행과 각 단계마다 "근거가 되는 파일:행"을 다시 붙여주세요.
- 실제 grep 결과나 첨부된 코드에 근거가 있는 항목만 "확인됨"으로 표시할 것
...

그리고 인간이 할 일은 간단합니다. 라우터 표의 상위 5개 항목만 실제 코드와 대조해 보는 것입니다. 전부를 검증할 필요는 없습니다. 자주 사용하는 입구만 정확하다면, 지도는 충분히 "사용 가능한" 것이 됩니다.

여기서 역할을 명확히 구분해 두겠습니다. AI 시대의 엔지니어는 "구현하는 사람"에서 "코드베이스의 지도를 설계하고 그 정확성을 보장하는 사람"으로 조금씩 무게 중심이 이동하고 있다는 느낌을 받습니다.

그리고 가장 효과적인 방법은, 만든 지도를 "그때뿐"으로 만들지 않는 것입니다. docs/atlas/repo-map.md나 CONTRIBUTING.md에 커밋하여 팀의 자산으로 만드세요. 다음에 들어올 신입 사원도, 다음에 움직일 AI 에이전트도 같은 지도 위를 걸을 수 있습니다. 암묵지가 조금씩 "기록된 지식"으로 변해갑니다. 이것은 꽤나 가치 있는 변화라고 생각합니다.

길게 써왔지만, 내일 아침 가장 먼저 해야 할 일은 이것만으로도 충분합니다.

README와 디렉터리 목록만 AI에게 전달하여, "하고 싶은 일 → 어디를 보면 되는가"의 표를 만들게 하는 것.

단지 이것뿐입니다. git ls-files | head -100의 결과와 README를 붙여넣고 프롬프트 예시 ②를 던지기만 하면 됩니다. 5분이면 당신의 코드베이스에 작은 지도 한 장이 만들어집니다.

그다음부터 규모에 따라 조감도(Overview map), 흐름 추적(Flow tracking), 검수(Verification)를 추가해 나가면 됩니다. 처음부터 완벽한 지도는 필요 없습니다. 단 한 장의 길 안내표부터 시작하면 됩니다.

마지막으로 다시 한번 말씀드립니다.

AI가 방대한 코드에서 갈피를 못 잡는 것은 AI의 잘못이 아닙니다. 지도를 주지 않았을 뿐입니다.

그리고 그 지도를 설계하고 정확성을 보장하는 것은——당분간은 여전히 우리 인간의 몫입니다.

오늘도, 즐거운 정비 되시길 바랍니다.