06. 코드베이스 탐색과 파일 작업

🎯 이 장의 목표

Claude Code의 내장 도구(Read·Write·Edit·Grep·Glob·Bash 등)가 각각 무엇을 하는지 안다
Claude가 왜 어떤 도구를 고르는지 이해하고, 잘못된 선택을 프롬프트로 교정한다
큰 탐색은 왜 서브에이전트(Agent)에 맡기는 게 좋은지 안다
도구 이름을 아는 것이 왜 권한·훅·스킬 설정의 기초인지 이해한다

왜 도구를 알아야 하나

"파일 읽어줘"라고 했을 때 Claude가 어떨 땐 Read를, 어떨 땐 Glob+Grep을, 가끔은 Bash의 cat을 쓰는 걸 본 적이 있을 겁니다. Claude는 나름의 도구 선택 로직을 갖고 있고, 이를 이해하면 두 가지 이득이 있습니다.

Claude가 엉뚱한 도구로 헤맬 때, 프롬프트의 어디가 불명확했는지 역추적해 고칠 수 있다.
Hook·Skill의 allowed-tools·권한 deny 규칙은 모두 도구 이름 기반이라, 도구를 모르면 고급 설정을 쓸 수 없다(→ 8장, 12장, 15장).

핵심 내장 도구

Claude Code에는 20개가 넘는 내장 도구가 있지만, 일상에서 보게 되는 핵심은 한 줌입니다.

도구	하는 일	비유
Read	절대 경로를 받아 파일 내용을 줄 번호와 함께 반환. 이미지·PDF·노트북도 읽음	책의 특정 페이지를 펴서 보기
Glob	파일명 패턴 매칭 (`src/*/.ts`). 이름으로 파일 찾기	서가에서 제목으로 책 찾기
Grep	ripgrep 기반 내용 검색. 코드 안의 문자열·패턴 찾기	책 안의 특정 단어 찾기
Edit	기존 파일의 특정 부분을 정확히 교체	페이지의 한 단락 고쳐 쓰기
Write	새 파일 작성 / 전체 덮어쓰기	새 페이지 쓰기
Bash	셸 명령 실행 (git·npm·docker·테스트 등)	작업대에서 도구 쓰기
Agent	서브에이전트를 띄워 독립적·다단계 탐색 수행	조사를 다른 사람에게 위임
TodoWrite	작업을 할 일 목록으로 쪼개 추적	체크리스트 관리

📌 핵심

Read의 줄 번호는 장식이 아닙니다. Edit이 나중에 정확한 교체를 하려면 그 줄 번호·내용에 의존합니다. 그래서 보통 "읽고 → 고친다"의 순서로 동작합니다.

왜 전용 도구를 쓰나 (Bash 대신)

Claude Code는 find·grep·cat·sed 같은 raw 셸 명령보다 전용 도구(Glob·Grep·Read·Edit)를 쓰도록 설계되어 있습니다. 이유는 두 가지입니다.

사용자 경험: 전용 도구는 권한 UI·diff 표시와 통합되어 당신이 작업을 검토하기 쉽습니다.
일관성: 어떤 코드베이스 크기에서도 동작하도록 최적화돼 있습니다.

하고 싶은 일	권장 도구	피할 것
파일 찾기	Glob	`find`, `ls`
내용 검색	Grep	`grep`, `rg`
파일 읽기	Read	`cat`, `head`, `tail`
파일 수정	Edit	`sed`, `awk`
파일 작성	Write	`echo >`, `cat <<EOF`

💡 팁

빈도 × 정확도 트레이드오프: 자주 하는 작업은 전용 도구(Grep·Glob)가 빠르고 안전합니다. 어쩌다 한 번 하는 특수 작업은 Bash가 유연합니다.

⚠️ Bash 명령에 대한 권한 deny 규칙은 전용 도구만 막고 Bash 하위 프로세스는 못 막을 수 있습니다. OS 수준에서 차단하려면 샌드박싱을 쓰세요(→ 23장).

Glob vs Grep: 헷갈리면 Claude가 헤맨다

이 둘을 섞으면 Claude가 잘못된 도구를 고릅니다.

Glob = 파일명 패턴으로 찾기 (예: **/*.test.ts)
Grep = 파일 내용 안에서 찾기 (예: function login)

예를 들어 "로그인 로직 좀 봐줘"라고 하면, Claude가 login이라는 파일명을 Glob으로 여러 번 찾다 실패하고서야 Grep으로 내용을 뒤져 답을 찾을 수 있습니다. 파일명에 login이 없을 수 있으니까요. 이럴 땐 경로를 직접 짚어주면(src/auth/) 즉시 빨라집니다.

큰 탐색은 Agent에게

Read·Glob·Grep으로 직접 찾는 게 빠를 때가 많지만, "config는 어느 파일에?"처럼 열린 탐색이나 여러 라운드의 검색이 필요한 경우엔 Agent(서브에이전트) 가 더 낫습니다.

flowchart TB
    Q{탐색 성격}:::agent
    Q -->|특정 파일·2~3개 파일| Direct[Read / Glob / Grep 직접]:::tool
    Q -->|열린·다단계 탐색| AgentT[Agent 서브에이전트<br/>Explore]:::sub

    Direct --> R1[빠름]:::result
    AgentT --> R2[메인 컨텍스트 보호<br/>요약만 돌려받음]:::result

    classDef agent fill:#80DEEA,stroke:#00ACC1,color:#000
    classDef tool fill:#90CAF9,stroke:#1E88E5,color:#000
    classDef sub fill:#80DEEA,stroke:#00ACC1,color:#000
    classDef result fill:#A5D6A7,stroke:#43A047,color:#000

서브에이전트는 검색하며 생기는 잡다한 출력(파일 목록·로그)을 자기 컨텍스트에 가둬두고, 메인 대화에는 요약만 돌려줍니다. 그래서 큰 코드베이스 탐색으로 메인 세션의 컨텍스트가 터지는 걸 막아줍니다. 읽기 전용 탐색에 특화된 내장 Explore 서브에이전트가 가장 비용 효율적입니다. (서브에이전트는 13장에서 깊이 다룹니다.)

💡 팁

독립적인 읽기 작업(여러 파일 Read, 여러 Grep)은 병렬로 한꺼번에 호출하는 게 효율적입니다. 순차적으로 "Read → 기다림 → Read"를 반복하면 느립니다.

전형적 작업 흐름 예시

버그 수정의 전형적 도구 사용 순서:

CODE

1. TodoWrite  : 디버깅 할 일 목록 작성
2. Grep       : 에러 메시지·패턴 검색
3. Read       : 문제 파일들 읽기 (여러 개 한 번에)
4. Bash       : 실패하는 테스트 실행해 재현
5. Edit       : 수정 적용
6. Bash       : 테스트 재실행으로 검증
7. TodoWrite  : 완료 표시

📌 핵심

Claude는 작업이 끝나면 보통 린트·타입체크(예: npm run lint, ruff)를 실행해 코드가 올바른지 확인하도록 동작합니다. CLAUDE.md에 검증 명령을 적어두면 더 잘 따릅니다(→ 9장).

이 장에서 배운 것

핵심 내장 도구는 Read·Glob·Grep·Edit·Write·Bash·Agent·TodoWrite다.
Claude는 raw 셸 명령보다 전용 도구를 선호하도록 설계됐다(검토 용이·일관성).
Glob은 파일명, Grep은 내용 — 이걸 구분해주면 Claude가 안 헤맨다. 경로를 직접 짚으면 빨라진다.
열린·다단계 탐색은 Agent 서브에이전트(특히 Explore)에 맡겨 메인 컨텍스트를 보호한다.
독립적 읽기는 병렬로 호출하는 게 효율적이다.

✍️ 확인 문제

Glob과 Grep의 차이는 무엇이며, 이를 모르면 어떤 비효율이 생기나요?
Claude가 cat·grep 같은 raw 셸 명령보다 전용 도구를 쓰도록 설계된 두 가지 이유는?
큰 코드베이스에서 "인증이 어디서 처리되는지" 같은 열린 탐색을 시킬 때, 메인 컨텍스트를 보호하려면 어떤 도구가 좋은가요?

다음 장: 07. 계획(Plan)과 실행 — 코드를 건드리기 전에 먼저 생각하게 만드는 Plan Mode.

← 이전05. 프롬프트로 작업 지시하기다음 →07. 계획(Plan)과 실행