AI에게 코드를 쓰게 하면 정말 빠르다. 태스크는 척척 끝난다. 테스트도 통과한다.

하지만 문득 멈춰 섰을 때, 이런 생각이 들 때가 있지 않은가.

「돌아가고는 있다. …그런데, 왜 돌아가는 건지 솔직히 잘 모르겠다.」

솔직히 말하면, 저도 자주 그렇습니다. 그리고 이것은 기분 탓도, 당신의 능력 문제도 아닙니다. 제대로 연구를 통해 관측된 현상입니다.

2026년에 발표된 연구(arXiv:2511.02922 「Comprehension-Performance Gap in GenAI-Assisted Brownfield Programming」)가 이를 깔끔하게 측정해 주었습니다. 대학원생 15명에게 AI 코딩 지원(GitHub Copilot)이 있는 경우와 없는 경우 모두 기능 구현을 시켜본 실험입니다. 결과는 다음과 같았습니다.

• AI 지원이 있으면,
  작업은 빨라졌고 정확해졌다.
• 하지만,
  코드 이해도는 특별히 높아지지 않았다 (통계적으로 유의미한 차이 없음, p=0.59).
• 오히려,
  「빨리 끝낸 사람일수록 기존 코드의 이해도는 오히려 낮다」는 부의 상관관계가 나타났다 (ρ=-0.57, p=0.026).
• 한편,
  생성된 코드를 능동적으로 확인하는 「검증 루프 (Verification Loop)」를 돌린 사람은 이해도가 차원이 다르게 높았다 (p<0.001). 실제로 이해도가 높은 사람은 낮은 사람보다 4.7배나 더 많이 코드를 확인하고 있었습니다.

저자의 결론이 굉장히 가슴에 와닿습니다.

「GenAI가 이해를 빼앗는 것이 아니다. "수동적으로 소비하는" 태도가 빼앗는 것이다.」

즉, 이런 뜻입니다. AI에게 「이 코드 설명해줘」라고 묻고, 돌아온 요약을 읽으며 「음음, 알겠어」라고 끝내는 것. 이 "수동적인 요약 소비"가 가장 위험합니다. 속도는 빨라집니다. 하지만 이해는 뒤처집니다. 그리고 이해하지 못한 채 기존 코드에 손을 대면, 다른 곳이 조용히 망가집니다.

이 기사는 그 상태를 벗어나기 위한 실전 가이드입니다. 테마는 바로, 「AI와 함께 모르는 코드·레거시(Legacy) 코드를 "해독하고 이해하는" 기술」. 개발 플로우로 치면 가장 첫 단계인 「조사」 단계입니다.

대상은 AI 코딩을 접하기 시작했지만, 타인의 코드나 오래된 코드를 읽는 것이 서툰 사람입니다. 전문 용어는 나올 때마다 풀어서 설명하므로, 「무지의 무지」――애초에 무엇을 모르는지도 모르는 단계인 분들도 읽어 나갈 수 있도록 작성했습니다.

끝까지 읽으면 다음과 같은 상태가 될 수 있습니다.

• 모르는 리포지토리(Repository)에 던져져도,
  어디서부터 읽어야 할지 알 수 있다
• AI로부터 「쓸모 있는 답」을 끌어내는
  **질문의 유형 (Prompt Pattern)**을 얻는다
• AI의 설명을
  곧이곧대로 믿지 않고 확인(Cross-check)하는 습관이 생긴다
• 2026년 시점의
  코드 검색 도구의 지형을 대략적으로 파악한다

그럼 시작해 봅시다.

결론부터 말씀드리겠습니다. AI로 "쓰는 것"이 빨라진 시대일수록, 병목 현상(Bottleneck)은 "읽기·이해하기"로 옮겨갑니다. 그렇기에 여기에 투자하는 사람이 조용히 강해집니다.

이유는 단순합니다. 원래 엔지니어의 시간은 "쓰는 것"보다 "읽는 것"에 압도적으로 치우쳐 있기 때문입니다. 몇몇 조사에 따르면 개발자는 작업 시간의 52~70%를 기존 코드의 이해에 사용하고 있다고 합니다. 읽는 시간과 쓰는 시간의 비율은 넉넉히 10 대 1을 넘습니다 (프로젝트에 따라 7 대 1 ~ 200 대 1이기도 함). 『Clean Code』의 로버트 C. 마틴(Robert C. Martin)도 예전부터 "읽는 시간 대 쓰는 시간의 비율은 10 대 1을 넉넉히 넘는다"라고 말했었죠.

여기서 용어 하나를 짚고 넘어가겠습니다. **브라운필드 개발 (Brownfield Development)**이라는 말이 있습니다.

브라운필드 (Brownfield) 개발… 이미 존재하는 코드베이스를 수정하는 개발을 말합니다. 「갈색(이미 건물이 지어져 있는) 땅」의 이미지입니다. 반대로, 제로 베이스에서 신규로 만드는 것이 그린필드 (Greenfield) (빈 땅)입니다.

그리고 현실의 업무 대부분은 브라운필드입니다. 신규 프로젝트를 처음부터 쓰는 순간보다, 누군가가 작성한 기존 코드를 읽고, 이해하고, 그 위에 덧붙이는 시간이 훨씬 깁니다. 그래서 「읽는 능력」은 수수해 보이지만 평생 유효한 투자입니다.

그리고 또 하나 주의해야 할 함정이 있습니다.

「이해했다는 착각 (Illusion of Understanding)」… 설명을 술술 읽을 수 있으면 뇌는 「이해했다」고 착각합니다. 하지만 "읽을 수 있는 것"과 "설명할 수 있는·예측할 수 있는 것"은 별개입니다.

AI의 요약은 정말 읽기 편합니다. 그렇기 때문에 바로 이 「이해했다는 착각」을 양산하기 쉽습니다. 정보를 찾는 것과 이해하는 것은 전혀 다릅니다. 이 점을 먼저 명확히 짚고 넘어가면, 이후의 이야기가 모두 납득될 것입니다.

모르는 코드를 열고, 일단 AI에게 전부 붙여넣으며 "설명해줘". …이것, 저도 합니다. 간편하니까요. 하지만 통째로 맡겨버리는 방식에는 세 가지 함정이 있습니다.

돌아오는 답변은 대개 "이 함수는 사용자 주문을 집계하여 합계 금액을 반환합니다"와 같은 What(무엇을 하는가)에 대한 요약입니다. 하지만 우리가 정말 알고 싶은 것은 오히려 Why(왜 이렇게 되어 있는가)일 때가 많습니다. "왜 여기서 부가세 포함과 제외를 나누는 거지?", "왜 이런 분기(branch)가 있는 거지?" —— 이런 코드의 "배경"은 What의 요약만으로는 나오지 않습니다.

이것이 가장 무서운 점입니다. AI는 코드에 대해 자신만만하게 틀립니다. 존재하지 않는 함수, 있지도 않은 인자(argument), 통과할 수 없는 분기를 마치 당연한 것처럼 이야기합니다.

구체적인 숫자로 살펴보겠습니다. LLM(대규모 언어 모델)에게 코드를 작성하게 하면, 실재하지 않는 라이브러리(패키지) 이름을 생성하는 현상이 알려져 있습니다. USENIX Security '25의 연구(16개 모델, 57만 6천 개 샘플)에 따르면, 존재하지 않는 패키지 이름을 생성하는 비율은 **상용 모델에서 5.2%, 오픈 소스 모델에서 21.7%**였습니다. 게다가 그 내역을 살펴보면, **51%가 완전한 날조, 38%가 다른 것들의 합성(예: express-mongoose처럼 두 실재물을 섞음), 13%가 오타(typo)**였습니다. 2026년의 최신 모델군에서도 이 비율은 낮아졌으나 여전히 남아 있으며, 대략 4.6~6.1%라고 보고되었습니다 (모델 및 시점에 따라 변동).

이것은 "존재하지 않는 패키지를 추천한다"는 형태로 유명해졌지만 (공격자가 그 이름을 악용하는 slopsquatting이라는 수법도 있을 정도입니다), 코드를 "읽게 했을" 때도 본질은 같습니다. AI는 절반만 읽었거나 추측으로 채운 내용을 단정적인 말투로 내놓습니다. AI를 비난하려는 게 아닙니다. 그냥 그런 성질을 가지고 있을 뿐입니다. 그러니 교차 검증(cross-check)을 전제로 대하는 것이 성숙한 태도라고 할 수 있습니다.

그리고 서두의 연구 이야기로 돌아가겠습니다. 요약을 받아서 읽기만 하는 것, 즉 수동적인 소비는 작업은 진행되지만 이해는 쌓이지 않는다는 결과가 나왔습니다. 검증 루프(verification loop)를 돌린 사람만이 이해할 수 있었다는 결과였죠.

요약하자면 이렇습니다.

「요약을 받는 것」 ≠ 「이해하는 것」

이 점을 오해하면, AI를 아무리 많이 사용해도 영원히 코드를 읽을 수 있게 되지 않습니다.

그렇다면 어떻게 해야 할까요? 발상을 하나 뒤집어 보겠습니다.

AI는 코드를 "읽어주는 대신"의 존재가 아닙니다. "읽기를 도와주는 내비게이션(안내인)"입니다.

비유하자면, 낯선 도시에 던져진 상황을 상상해 보세요. 지도도 없고 지리도 모릅니다. 그때 그 지역을 잘 아는 안내인이 있다면 정말 도움이 되겠죠. "역은 저쪽입니다", "이 길은 막다른 길입니다", "여기가 상가입니다". 하지만 실제로 걷는 것은 자신입니다. 안내인에게 "도시를 이해해 둬"라고 통째로 맡길 수는 없습니다.

코드도 마찬가지입니다. AI는 "넓고 빠르게 안내하는 것"에 능숙합니다. 그래서 탐색 속도는 폭발적으로 빨라집니다. 하지만 최종적으로 "아는 것"은 자신입니다. 이 둘을 혼동하지 않는 것이 모든 출발점입니다.

이를 위해, 「이해한다」는 것을 측정 가능한 형태로 다시 정의해 둡시다.

이해하고 있다 = 그 코드에 대한 "구체적인 질문"에 근거를 가지고 답할 수 있는 상태.

(예: "이 함수가 에러를 반환하는 경우는 어떤 입력이 들어올 때인가?"라는 질문에, 코드의 행을 가리키며 답할 수 있음)

요약을 읽을 수 있는 것이 아니라, 질문에 답할 수 있는 것. 이것이 목표입니다. 그리고 이를 위해 돌려야 하는 것이 바로 ——

검증 루프 (verification loop) … AI의 답변을 그대로 믿지 않고, ① 실제 코드로 확인하고, ② 작게 실행하여 관찰하며, ③ 차이가 있다면 다시 질문하는 과정을 반복하는 것. 연구에서 「이해한 사람」이 했던 것이 바로 이것입니다.

여기서부터는 이 검증 루프를 구체적으로 어떻게 돌릴 것인가에 대한 이야기입니다.

모르는 코드를 앞에 두고 얼어붙는 이유는 대개 "어디서부터 읽어야 할지" 정해지지 않았기 때문입니다. 순서만 있다면 길을 잃지 않습니다. 저는 이 5단계로 지도를 만듭니다.

포인트는, ①→⑤로 향할수록 "변경"에 가까워진다는 것입니다. 처음에는 넓고 얕게 지도를 그리고, 점차 깊고 좁게 파고듭니다. 처음부터 ⑤(영향 범위)를 갑자기 물어봐도, 지도가 없으면 답변의 정확성을 판단할 수 없습니다.

여기서 용어 하나를 짚고 넘어가겠습니다. ④나 ⑤에서 등장하는 개념으로서—

불변 조건 (Invariant)… "여기서는 반드시 이래야 한다"라는 전제. 예: "이 시점에서 order.items는 반드시 1개 이상 존재한다". 코드를 변경할 때는 이 불변 조건을 깨뜨리지 않는지를 가장 신경 써야 합니다.

"이 함수가 전제로 하는 불변 조건은 뭐야?"라고 AI에게 물으면, 숨겨진 전제가 드러나 지뢰를 밟을 확률을 낮춰줍니다.

같은 AI라도 질문 하나에 따라 돌아오는 답변의 질이 완전히 달라집니다. "나쁜 질문"을 "좋은 질문"으로 바꾸는 것만으로도 이해도는 비약적으로 향상됩니다.

그리고 어떤 질문에도 반드시 이 문장을 덧붙이는 것이 요령입니다.

"각 주장에는 코드상의 근거(file:line)를 붙여줘. 코드에서 확인할 수 없는 내용은 '추측' 또는 '불명'이라고 명시해줘."

이것은 그라운딩 (Grounding: 근거 제시) 지시입니다. AI가 그냥 "말만 내뱉게" 두지 않고, 반드시 실제 코드에 발을 붙이게 만드는 것입니다. 이렇게 해두면 나중에 스스로 확인(Verification)하는 작업도 순식간에 끝납니다.

당신은 이 리포지토리에 오늘 처음 들어온 나의 "안내인"입니다.
내가 이해하고 싶은 목표: "주문 총액이 어디서 어떻게 계산되는가"
다음 순서로 간결하게 알려주세요.
...

함수 `calc_total` (파일: services/billing/total.ts)의 동작을
다음 형식으로 설명해 주세요.
- 입력: 인자와 그 타입·전제 (불변 조건이 있다면 포함)
...

질문 마지막에 "놓치기 쉬운 점을 한 가지만 알려줘"라고 덧붙이면, AI가 자신의 사각지대를 알려줄 때가 있는데, 이게 은근히 효과적입니다.

검증 루프의 핵심입니다. AI가 무언가 말하면, 그대로 믿지 말고 반드시 실물로 확인하세요. 해야 할 일은 딱 세 가지뿐입니다.

• 인용된 file:line을 실제로 열기… 해당 라인에 정말 그 코드가 있는지 확인합니다.
• grep / 타입으로 확인하기… 함수의 정의, 호출부, 인자를 문자열 검색이나 타입으로 확인합니다.
• 작게 움직여서 관찰하기… print, 로그, 테스트, 디버거를 통해 "실제 동작"을 확인합니다.

이제 도구들을 차례대로 살펴보겠습니다. 전부 복사해서 바로 실행할 수 있는 형태로 준비했습니다.

처음 10분 동안 이것을 실행하면, AI에게 질문하기 전의 "자신만의 지형 감각"을 가질 수 있습니다.

#!/usr/bin/env bash
# repo-orient.sh — 모르는 리포지토리의 전체상을 빠르게 파악하기
# 사용법: ./repo-orient.sh (리포지토리 루트에서 실행)
...

「최근 자주 변경된 파일」은 해당 프로젝트의 "현재 중심지"를 알려줍니다. AI에게 "어디가 중요해?"라고 묻기 전에, 이것으로 자신만의 가설을 가지고 있으면 AI 답변의 정답 여부를 판단할 수 있습니다.

AI가 "이 함수는 여기서 호출되고 있습니다"라고 말하면, 자신의 눈으로 직접 확인합니다. rg (ripgrep)와 git만 있으면 충분합니다.

# ① 함수·심볼의 "정의"를 찾기 (TS/JS 예시)
rg -n "function calc_total|const calc_total|calc_total\s*=" --type ts
# ② 해당 함수의 "호출부"를 전부 찾기 (영향 범위 파악)
...

git log -L과 git blame은 ④Why(왜 이렇게 되어 있는가)를 파고들 때의 파트너입니다. 코멘트에 남아 있지 않은 배경이 커밋 메시지에 잠들어 있는 경우가 정말 많거든요.

AI의 답변이 나온 후, 다시 한번 AI 스스로 증거를 제시하게 하면 수상한 주장을 가려낼 수 있습니다.

방금 당신의 답변에 대해 검증하겠습니다.
각 주장을 한 줄씩 분해하여 다음 3열의 표로 만들어 주세요.
| 주장 | 근거(file:line) | 확신도(확인됨/추측/미확인) |
...

AI에게 근거를 JSON으로 출력하게 하면, 해당 file:line이 실제로 존재하는지 스크립트로 일괄 체크할 수 있습니다. 할루시네이션 (Hallucination, 환각) 탐지의 자동화인 셈입니다.

먼저 AI에게 다음과 같이 출력하게 합니다.

[
{ "claim": "calc_total은 items가 비어 있으면 0을 반환한다", "file": "services/billing/total.ts", "line": 42 },
{ "claim": "calc_total은 세율을 applyTax로 곱한다", "file": "services/billing/tax.ts", "line": 88 }
...
]

이 JSON을 다음 스크립트에 입력합니다.

#!/usr/bin/env python3
# verify_claims.py — AI가 출력한 {claim, file, line} 근거를 실제 파일과 대조함
# 사용법: python3 verify_claims.py claims.json
...

중요한 점은, 이 스크립트가 "거짓을 자동으로 판정하는" 것이 아니라는 사실입니다. "파일이나 행이 존재하지 않음 = 확실히 수상함"을 걸러내고, 남은 것은 인간이 눈으로 보고 판단하는 것입니다. 마지막 판단은 역시 자기 자신이어야 합니다.

"결국 어떤 도구를 사용해야 하는가?"라는 질문에 대해, 2026년 6월 시점에서 코드 검색에는 크게 두 가지 계통이 있습니다. 이 부분은 깔끔하게 정리해 둘 가치가 있습니다.

① 에이전트형 탐색 (Agentic Search)

대표적인 예는 Claude Code입니다. 사전에 만들어진 인덱스 (Index, 색인)를 갖지 않고, Read (읽기) · Grep (문자열 검색) · Glob (파일명 검색) · Bash (셸 명령)와 같은 도구들을 그 자리에서 조합하여 실시간으로 코드를 돌아다니는 방식입니다. 인간이 grep을 하며 코드를 읽는 방식과 유사합니다.

② 시맨틱 인덱스형 (Semantic Index)

대표적인 예는 Cursor입니다. 사전에 리포지토리 전체를 분석하여 인덱스를 만듭니다. 구체적으로는 파일의 변경 사항을 Merkle tree (머클 트리)로 관리하고, 코드를 tree-sitter라는 구문 분석기로 의미 있는 단위 (AST: 추상 구문 트리 덩어리)로 나누어, 이를 embedding (임베딩: 의미를 수치 벡터로 변환한 것) 하여 벡터 DB에 저장합니다. 대략 5분마다 재동기화하여 최신 상태를 유지합니다.

여기서 용어 두 가지를 정리하겠습니다.

• grep (문자열 검색): "calc_total이라는 문자열을 포함하는 행"과 같이 글자 그대로를 찾습니다. 빠르고 정확하지만, 이름을 모르면 찾을 수 없습니다.
• 시맨틱 검색 (Semantic Search, 의미 검색): "합계 금액을 계산하는 곳"과 같이 의미로 찾습니다. 이름을 몰라도 도달할 수 있지만, 엉뚱한 결과를 내놓을 수도 있습니다.

그리고 흥미로운 점은 Cursor가 공개한 벤치마크 (Cursor Context Bench) 결과입니다. 시맨틱 검색을 grep에 "더했을 때", grep 단독 사용 시보다 코드 관련 질문에 대한 정답률이 평균 12.5%, 최대 23.5% 향상되었습니다 (모델에 따라 6.5~23.5%). 그리고 결론은――

「의미 검색 (Semantic Search) × grep의 하이브리드가 가장 성적이 좋다.」

이 말은 정말 시사하는 바가 크다고 생각합니다. 어느 한쪽으로 치우치는 것이 아니라, 양쪽을 모두 사용하는 것. 이름을 알고 있다면 grep으로 단번에 찾아내고, 이름도 모르는 막연한 것을 찾을 때는 의미 검색으로 범위를 좁히는 식입니다. 인간이 코드를 읽는 방식과 똑같죠.

참고로, Claude Code와 같이 인덱스를 갖지 않는 도구에도 MCP (Model Context Protocol, 외부 도구 연결 메커니즘)를 통해 의미 검색 기능을 추가할 수 있습니다 (claude-context나 Augment Context Engine 등의 MCP 서버 활용).

「내 에이전트에게 의미 검색이라는 눈을 달아주고 싶다」고 생각한다면 선택지는 있습니다.

⑤ Risk 단계에서 사용하는 질문입니다. 변경하기 전에 반드시 거쳐야 합니다.

함수 `calc_total` (services/billing/total.ts)를 변경하려고 합니다.
파손될 수 있는 부분을 나열해 주세요.
1. 직접적인 호출부를 file:line 형식으로 전부
...

여기까지를 한 장으로 정리하면 다음과 같습니다. 쥐어야 할 부분과 맡겨야 할 부분을 나누는 것이 요령입니다.

한마디로 요약하자면, What과 Why는 인간, How (탐색의 수단)는 AI입니다. 이는 Code & Capital의 발상과도 일치합니다. "너는 What과 Why를 생각해라, How는 내가 하겠다"라고 AI가 말해주는 것과 같죠.

마지막으로, 빠지기 쉬운 함정들을 나열해 두겠습니다. 미리 알고 있는 것만으로도 사고를 상당히 피할 수 있습니다.

그리고 가장 중요한 경계선을 굵게 표시하겠습니다.

이해하지 못한 코드를 "변경"하는 것에 대해서는 인간이 게이트(Gate) 역할을 해야 합니다. 특히 불가역적인 작업(운영 DB 업데이트, 결제, 삭제, 공개, 배포)은 AI의 제안이 아무리 자신만만하더라도, 인간이 최종 확인한 후 실행해야 합니다. "이해했다"고 착각한 채로 불가역적인 작업으로 넘어가는 것이 가장 무서운 사고입니다.

또 하나, 안전을 위해 강력히 권고하고 싶은 점이 있습니다. AI에게 전달하는 프롬프트나 코드에 비밀 정보(API 키, 비밀번호, 토큰), 개인 정보, 사내 고유 ID나 URL을 그대로 붙여넣지 마세요. 문맥상 꼭 필요하다면 더미(Dummy) 값으로 교체한 뒤 전달하십시오. 이 글의 샘플이 전부 calc_total이나 services/billing/total.ts 같은 가상의 이름인 것도 같은 이유입니다.

철수(Retreat) 라인도 단순합니다. **「AI에게 3번 물어봐도 납득이 가지 않는다면, 그것은 'AI로 이해할 수 있는 범위'를 넘어섰다는 신호」**일 수 있습니다. 그럴 때는 설계자에게 직접 묻거나, 문서를 찾아보거나, 스스로 시간을 들여 읽는 방식으로 전환하세요. AI에 집착하지 않는 것도 훌륭한 판단입니다.

내용이 길어졌으니, 내일부터 실천할 구체적인 4단계로 요약하겠습니다.

• 다음에 모르는 코드를 열 때, 갑자기 "설명해줘"라고 묻지 마세요. 먼저 repo-orient.sh를 실행하여 자신만의 지도를 만드세요.
• AI에게 질문할 때마다 매번 "file:line 근거를 붙여줘. 추측은 추측이라고 적어줘"를 추가하세요. 이것만으로도 답변의 질이 달라집니다.
• AI가 지목한 행은 반드시 최소 하나는 직접 눈으로 확인하세요. 검증 루프의 첫걸음입니다.
• 이해하지 못한 코드를 변경하려 한다면 일단 멈추세요. 불가역적인 작업은 인간이 최종 버튼을 누릅니다.

마지막으로, 조금 더 큰 이야기를 해보겠습니다.

코드를 읽는 일은 지루합니다. 쓰는 것이 더 화려하고 즐겁죠. 하지만 오늘 제대로 이해해 두는 것은 내일의 나에게 남기는 쪽지와 같다고 생각합니다. 다음 주에 내가 같은 코드로 돌아왔을 때, "그때 이해해 둬서 정말 고마워"라고 말할 수 있도록 말이죠. 다음 AI 세션으로 작업을 넘길 때도, 내가 이해하고 있어야 정확하게 문맥을 전달할 수 있습니다.

이것은 자신을 채찍질하는 축(읽어야만 해)이 아니라, 미래의 나를 배려하는 축으로 지속하고 싶은 일입니다. 100점이 아니어도 좋습니다. 오늘 파일 하나, AI의 주장을 하나 검증했다. 그것만으로도 내일의 나는 "고마워"라고 말해줄 것입니다.

그리고 이렇게 쌓아 올린 「해독하는 능력 (reading power)」은 누구도 빼앗아 갈 수 없습니다. AI로 작성하는 속도가 빨라질수록, 자신이 정말로 이해하고 있는가가 차이를 만듭니다. How(방법)는 맡기더라도, What(무엇을)과 Why(왜)를 쥐고 있어야 합니다. 읽는 능력은 소모품이 아니라, 계속해서 쌓여가는 자산입니다.

AI는 최고의 안내자입니다. 하지만 거리를 걷고, 자신의 발로 지도를 그리는 것은 결국 우리 자신입니다. …그렇게 생각하면, 코드를 읽는 시간도 조금은 즐거워지지 않을까요?

그럼, 다음에 또 뵙겠습니다.