개발 AI 에이전트인 Claude Code가 어떻게 코드베이스를 탐색하고 작업하는지 내부 메커니즘을 알아보자
코딩 AI Agent를 만들고 있는데 내가 도구가 뭐뭐 있냐고 물어보자 대답을 너무 잘해주길래 Claude Code에게 똑같이 물어봤다.
도구 정의 방식
Claude Code는 시스템 프롬프트에 모든 도구가 JSONSchema 형식으로 정의되어 있다.
예를 들어 Grep 도구는 이렇게 정의된다.
{
"name": "Grep",
"description": "A powerful search tool built on ripgrep...",
"parameters": {
"pattern": { "type": "string", "description": "검색할 정규식 패턴" },
"path": { "type": "string", "description": "검색 경로" },
"output_mode": {
"enum": ["content", "files_with_matches", "count"],
"description": "출력 모드"
},
"-i": { "type": "boolean", "description": "대소문자 무시" },
"-A": { "type": "number", "description": "매치 이후 N줄" },
// ...
},
"required": ["pattern"]
}
실제 호출은 XML 형식으로 이루어진다.
<invoke name="Grep">
<parameter name="pattern">SessionId</parameter>
<parameter name="type">java</parameter>
<parameter name="output_mode">content</parameter>
<parameter name="-n">true</parameter>
</invoke>
프롬프트 구조
Claude Code의 시스템 프롬프트는 크게 세 부분으로 구성된다.
1. 함수 정의 섹션
프롬프트 맨 앞에 모든 도구가 JSONSchema 형식으로 정의되어 있다.
<functions>
<function>{
"name": "Grep",
"description": "A powerful search tool built on ripgrep...",
"parameters": { ... }
}</function>
<function>{
"name": "Read",
"description": "Reads a file from the local filesystem...",
"parameters": { ... }
}</function>
<function>{
"name": "Bash",
"description": "Run a bash command...",
"parameters": { ... }
}</function>
</functions>
2. 도구 사용 가이드라인
도구 선택과 사용 방법에 대한 정책이 명시되어 있다.
도구 사용 정책
- 파일 검색 시 컨텍스트 사용량을 줄이기 위해 Task 도구를 우선 사용하라.
- 작업이 특정 에이전트의 설명과 일치하면
Task 도구로 전문 에이전트를 적극 활용하라.
- 가능하면 bash 명령어 대신 전문 도구를 사용하라:
* cat/head/tail 대신 Read
* sed/awk 대신 Edit
* cat with heredoc 대신 Write
- 코드베이스 탐색 시에는 검색 명령을 직접 실행하지 말고
반드시 Task 도구의 Explore 서브에이전트를 사용하라.
- 한 번의 응답에서 여러 도구를 호출할 수 있다.
의존성이 없다면 독립적인 도구 호출을 병렬로 실행하라.
3. 호출 방법 지침
프롬프트 마지막에 도구 호출에 대한 구체적인 instruction이 있다.
사용자의 요청에 대해 관련 도구를 사용하여 답변하라.
각 도구 호출에 필요한 모든 필수 파라미터가 제공되었거나
컨텍스트에서 합리적으로 추론 가능한지 확인하라.
사용자가 특정 값을 제공했다면 (예: 따옴표로 감싼 값),
해당 값을 정확히 그대로 사용하라.
선택적 파라미터에 대해 임의로 값을 만들어내거나 물어보지 마라.
여러 도구를 호출할 때 의존성이 없다면,
모든 독립적인 호출을 동일한 응답에서 실행하라.
프롬프트 예시
프롬프트에는 구체적인 사용 예시도 포함되어 있다.
<example>
user: "Where are errors from the client handled?"
assistant: [Uses the Task tool with subagent_type=Explore
to find the files that handle client errors
instead of using Glob or Grep directly]
</example>
<example>
user: "What is the codebase structure?"
assistant: [Uses the Task tool with subagent_type=Explore]
</example>
이러한 프롬프트 구조를 통해 Claude Code는:
- 도구의 명확한 스펙을 이해하고
- 상황에 맞는 최적의 도구를 선택하며
- 컨텍스트를 효율적으로 관리한다
주요 도구 카테고리
파일 작업
- Read: 파일 읽기 (이미지, PDF, Jupyter 노트북 지원)
- Write: 파일 생성/덮어쓰기
- Edit: 정확한 문자열 치환
- Glob: 파일 패턴 검색 (
**/*.java) - Grep: 내용 검색 (정규식, 파일 타입 필터 지원)
실행
- Bash: 쉘 명령 실행 (백그라운드 실행, 타임아웃 설정 가능)
- NotebookEdit: Jupyter 노트북 편집
웹
- WebFetch: URL 컨텐츠 가져오기 (HTML → 마크다운 변환)
- WebSearch: 웹 검색
개발 도구
- LSP: 언어 서버 프로토콜
- goToDefinition, findReferences, hover
- documentSymbol, workspaceSymbol
- 호출 계층 분석
출력 길이 제어 전략
Grep 같은 도구는 결과가 방대할 수 있어 여러 제한 장치가 있다. 다른 도구도 마찬가지일것이다.
1. output_mode로 제어
<!-- 파일 경로만 반환 -->
<invoke name="Grep">
<parameter name="pattern">test</parameter>
<parameter name="output_mode">files_with_matches</parameter>
</invoke>
<!-- 실제 내용 표시 -->
<invoke name="Grep">
<parameter name="pattern">test</parameter>
<parameter name="output_mode">content</parameter>
</invoke>
2. head_limit으로 출력 제한
<invoke name="Grep">
<parameter name="pattern">public</parameter>
<parameter name="output_mode">content</parameter>
<parameter name="head_limit">50</parameter>
</invoke>
3. offset + head_limit으로 페이징
<!-- 51~100번째 줄 보기 -->
<invoke name="Grep">
<parameter name="pattern">public</parameter>
<parameter name="output_mode">content</parameter>
<parameter name="offset">50</parameter>
<parameter name="head_limit">50</parameter>
</invoke>
4. 자동 truncation
30,000자를 초과하면 자동으로 잘린다.
서브에이전트 시스템
가장 흥미로운 부분은 Task 도구를 통한 전문 서브에이전트 시스템이다.
Explore 에이전트 - 코드베이스 탐색 전문
<invoke name="Task">
<parameter name="subagent_type">Explore</parameter>
<parameter name="prompt">Where is error handling done in this codebase?</parameter>
<parameter name="description">Find error handling code</parameter>
</invoke>
왜 필요한가?
- 직접 Grep을 여러 번 실행하면 컨텍스트가 빠르게 소진됨
- Explore 에이전트는 독립적인 컨텍스트에서 여러 검색 수행
- 결과를 요약해서 반환
thoroughness 레벨: "quick", "medium", "very thorough"
다른 서브에이전트들
Plan 에이전트 - 구현 계획 수립
<invoke name="Task">
<parameter name="subagent_type">Plan</parameter>
<parameter name="prompt">Plan how to add dark mode feature</parameter>
</invoke>
general-purpose 에이전트 - 복잡한 멀티스텝 작업
<invoke name="Task">
<parameter name="subagent_type">general-purpose</parameter>
<parameter name="prompt">Find all usages of deprecated API</parameter>
</invoke>
claude-code-guide 에이전트 - Claude Code 문서 조회
실전 전략
프롬프트에는 다음과 같은 지침이 포함되어 있다:
"When exploring the codebase to gather context, it is CRITICAL that you use the Task tool with subagent_type=Explore instead of running search commands directly."
도구 선택 기준
| 상황 | 사용 도구 |
특정 클래스명 찾기 (class Foo) |
Glob 직접 |
| 특정 파일 읽기 | Read 직접 |
| "에러 처리가 어디서 돼?" | Explore 에이전트 |
| "프로젝트 구조가 어떻게 돼?" | Explore 에이전트 |
| 아키텍처 설계 필요 | Plan 에이전트 |
도구 사용 우선순위
- 전문 도구 우선:
cat대신Read,sed대신Edit - 병렬 호출: 의존성이 없는 도구는 동시에 호출
- 서브에이전트 활용: 복잡한 탐색은 Explore에게 위임
- 컨텍스트 절약: 광범위한 검색은 서브에이전트에게
마무리
Claude Code의 도구 시스템은 단순히 명령어를 실행하는 것을 넘어서:
- JSONSchema로 명확한 인터페이스 정의
- XML 기반의 구조화된 호출
- 출력 길이 제어 메커니즘
- 전문 서브에이전트를 통한 작업 위임
이러한 설계를 통해 효율적인 컨텍스트 관리와 작업 분산이 가능하다.
