5.4코드베이스 탐색

코드베이스에 대한 질문에 답하는 방식은 크게 둘입니다. 임베딩 기반 검색(RAG)처럼 사전 인덱스를 만들어 조회하는 방식과, grep·glob·파일 읽기를 반복하며 필요할 때 탐색하는 에이전틱 검색 방식입니다. Claude Code는 후자를 택했습니다.

에이전틱 검색의 동작은 숙련된 개발자가 낯선 코드베이스를 파악하는 과정과 같습니다.

1. 지형 파악: 디렉터리 구조, 설정 파일(package.json, pyproject.toml)로 프로젝트 성격을 파악합니다.
2. 키워드 검색: 기능명·오류 메시지·API명으로 grep 하여 후보 파일을 좁힙니다.
3. 선택적 정독: 후보 중 핵심 파일만 읽되, 큰 파일은 필요한 부분만 읽습니다.
4. 참조 추적: 찾은 심볼의 정의·호출처를 따라가며 그림을 완성합니다.

[전형적 탐색 시퀀스]
glob "**/*.ts" → 구조 파악
grep "processPayment" → 후보 3개 파일
read src/payment/service.ts (일부) → 핵심 로직 확인
grep "PaymentService" → 호출처 확인

에이전틱 검색의 장점은 인덱스 관리가 필요 없고(항상 최신 코드 기준), 검색 과정 자체가 추론이므로 "이 함수와 비슷한 역할을 하는 다른 구현"처럼 의미적 연결이 필요한 질문에도 대응한다는 점입니다. 단점은 탐색마다 토큰과 시간이 든다는 것이며, 그래서 다음 섹션의 컨텍스트 절약 전략이 중요해집니다.

시험에서는 "대규모 코드베이스에는 반드시 임베딩 인덱스가 필요하다"는 선택지가 함정으로 나옵니다. 에이전틱 검색은 인덱스 없이 동작하며, 오히려 인덱스의 최신성 문제를 피합니다.

**점진적 공개(progressive disclosure)**는 에이전트가 정보를 한 번에 모두 로드하지 않고, 얕은 정보에서 시작해 필요할 때 깊이 들어가는 전략입니다. Anthropic의 컨텍스트 엔지니어링 가이드가 강조하는 핵심 패턴입니다.

실무 규칙으로 옮기면 다음과 같습니다.

• 파일 전체보다 개요 먼저: 2,000줄 파일이라면 먼저 심볼 목록이나 grep 매치 주변만 보고, 수정 대상 함수를 특정한 뒤 해당 범위만 읽습니다.
• 넓은 검색 → 좁은 검색: 파일명 패턴(glob)으로 범위를 좁히고, 내용 검색(grep)으로 후보를 추리고, 마지막에 정독합니다. 처음부터 정독하면 컨텍스트가 무관한 코드로 채워집니다.
• 메타데이터를 신호로 활용: 파일 크기, 수정 시각, 디렉터리 관습(tests/, legacy/)은 읽지 않고도 얻는 정보입니다.
• CLAUDE.md를 지도로 사용: 프로젝트의 구조·규칙·자주 쓰는 명령을 CLAUDE.md에 기록해 두면, 에이전트가 매 세션 같은 탐색을 반복하지 않습니다. 탐색 결과를 이런 지속 문서로 승격시키는 것은 팀 차원의 컨텍스트 절약입니다.

# CLAUDE.md (발췌)
## 구조
- src/payment/ — 결제. 진입점은 service.ts
- src/legacy/ — 수정 금지, 참조만
## 관습
- 테스트: npm test -- --filter <이름>
- 모든 금액은 정수 원 단위 (부동소수점 금지)

반대 극단도 함정입니다. 너무 적게 읽고 추측으로 수정하면 소프트 오류(5.3)를 만듭니다. 기준은 "수정할 코드와 그 계약(호출처·테스트)은 원문을 확인하고, 배경 지식은 요약 수준으로"입니다.

넓은 탐색은 필연적으로 많은 파일 내용을 컨텍스트에 쌓습니다. 문제는 탐색이 끝난 뒤입니다. 결론에 도달하는 데 쓰인 중간 자료(읽었지만 무관했던 파일들)가 메인 컨텍스트에 남아 이후 작업의 신호 대비 잡음비를 떨어뜨립니다.

해결책은 탐색을 서브에이전트(subagent)로 위임하는 것입니다. 서브에이전트는 자신만의 컨텍스트 윈도우에서 수십 개 파일을 읽고, 부모에게는 결론만 요약해 반환합니다. 부모 컨텍스트에는 파일 덤프 대신 몇 문단의 답이 남습니다.

[부모 → 탐색 서브에이전트]
"결제 재시도 로직이 구현된 위치와 호출 경로를 찾아라.
 파일 경로와 핵심 함수 시그니처, 관련 테스트 위치만 보고하라."

[서브에이전트 → 부모] (파일 40개를 읽었지만 반환은 요약만)
"재시도는 src/payment/retry.ts의 withRetry()가 담당.
 호출처는 service.ts:88과 webhook.ts:45.
 테스트는 test/payment/retry.test.ts. 백오프 상수는 config.ts에 정의."

이 패턴이 효과적인 조건은 두 가지입니다.

1. 읽기 전용 탐색일 것 — 여러 서브에이전트가 병렬로 탐색해도 충돌하지 않습니다. 반면 쓰기 작업의 병렬화는 조정 비용이 커서 신중해야 합니다.
2. 반환 형식을 지시할 것 — "경로와 시그니처만"처럼 요약 형식을 정하지 않으면 서브에이전트가 파일 내용을 길게 인용해 격리 효과가 사라집니다.

Anthropic의 멀티 에이전트 리서치 시스템도 같은 구조입니다. 오케스트레이터가 검색을 워커에게 맡기고 압축된 결과만 수집해, 단일 컨텍스트로는 불가능한 넓이를 확보합니다. 시험에서는 "메인 에이전트가 모든 파일을 직접 읽어야 정확하다"가 전형적 오답, "탐색은 위임하고 결론만 회수한다"가 정답 패턴입니다.