# 도구 목록

> Claude Code가 사용할 수 있는 모든 내장 도구 레퍼런스 — 파일 작업, 셸 실행, 웹 접근, 서브에이전트 생성 포함.

## 파일 도구

**Read — 파일 읽기**
로컬 파일시스템에서 파일을 읽습니다. 기본적으로 최대 2,000줄 읽기. 대용량 파일의 타겟 읽기를 위한 `offset`과 `limit` 지원. `cat -n` 형식으로 줄 번호와 함께 내용 반환. 이미지(PNG, JPG 등), PDF(한 번에 최대 20페이지), Jupyter 노트북(`.ipynb`) 읽기도 지원. 읽기 전용, 항상 자동 승인.

**Edit — 파일 편집**
파일에서 정확한 문자열 교체를 수행합니다. 같은 대화에서 해당 파일을 먼저 `Read`해야 합니다. `old_string`을 `new_string`으로 교체 — 파일에서 유일하게 일치해야 합니다. 파일 전체에서 이름을 변경하려면 `replace_all: true` 사용. `old_string`이 두 번 이상 나타나면 실패합니다(replace_all이 설정되지 않은 경우).

**Write — 파일 생성/덮어쓰기**
새 파일을 만들거나 기존 파일을 완전히 덮어씁니다. 기존 파일은 같은 대화에서 먼저 `Read`가 필요합니다. 기존 파일 수정에는 `Edit`를 선호하세요 — `Write`는 전체 파일 내용을 전송하며 새 파일이나 전체 재작성에 더 적합합니다.

**Glob — 파일 패턴 검색**
이름 패턴으로 파일을 찾습니다. 어떤 코드베이스 크기에서도 작동하는 빠른 패턴 매칭. 수정 시간 기준으로 정렬된 매칭 파일 경로 반환. `**/*.ts`, `src/**/*.test.js`, `**/CLAUDE.md` 같은 패턴 지원. 읽기 전용, 항상 자동 승인.

## 셸 도구

**Bash — 셸 커맨드 실행**
대화 내에서 지속되는 셸 세션에서 커맨드를 실행합니다. 도구 호출 간에 환경 변수와 작업 디렉토리 변경이 유지됩니다. `timeout` 파라미터 지원.

주요 동작:
- **복합 커맨드** (`&&`, `||`, `;`, `|`) — 파싱되어 각 서브커맨드가 독립적으로 권한 검사됨
- **백그라운드 실행** — `run_in_background: true`를 전달해 블로킹 없이 장시간 실행 커맨드 실행
- **출력 제한** — stdout/stderr이 도구 결과 크기 예산을 초과하면 미리보기와 파일 경로가 반환됨
- **검색 커맨드** — 콘텐츠 검색에는 최적화된 권한과 접근을 가진 전용 `Grep` 도구를 선호하세요

## 검색 도구

**Grep — 파일 내용 검색**
정규식을 사용해 파일 내용을 검색합니다. ripgrep 기반. 전체 regex 구문, 파일 타입 필터링(`*.ts`, `**/*.py`), 세 가지 출력 모드 지원:
- `files_with_matches` (기본) — 파일 경로만 반환
- `content` — 컨텍스트와 함께 매칭된 줄 반환
- `count` — 파일당 매칭 수 반환

`multiline: true`로 멀티라인 패턴 지원. 읽기 전용, 항상 자동 승인.

**LS — 디렉토리 내용 나열**
구조화된 형식으로 파일과 서브디렉토리를 반환합니다. 파일을 읽거나 편집하기 전에 프로젝트 구조를 탐색하는 데 유용합니다. 읽기 전용, 항상 자동 승인.

## 웹 도구

**WebFetch — URL 가져오기**
URL에서 정보를 가져와 추출합니다. HTML을 마크다운으로 변환한 후 보조 모델을 통해 집중된 답변을 생성합니다.
- HTTP URL은 자동으로 HTTPS로 업그레이드됨
- 15분 자가 정리 캐시 포함
- URL이 다른 호스트로 리다이렉트되면 후속 요청을 위한 리다이렉트 URL 반환
- GitHub URL의 경우 `gh` CLI를 통한 Bash 사용 권장

`default` 모드에서 승인 요청.

**WebSearch — 웹 검색**
웹을 검색하고 결과를 반환합니다. 제목, 스니펫, URL을 마크다운 링크로 형식화해서 반환. 모델의 훈련 컷오프 이후 정보에 접근하는 데 유용합니다. 응답 후 Claude가 자동으로 참조된 모든 URL을 나열하는 `Sources:` 섹션을 추가합니다. 현재 미국에서만 이용 가능. `default` 모드에서 승인 요청.

## 에이전트 및 작업 도구

**Task (Agent) — 서브에이전트 생성**
별도의 컨텍스트에서 서브에이전트를 시작합니다. 서브에이전트는 자체 대화 기록, 도구 집합(선택적으로 제한됨)을 가지고 완료될 때까지 실행한 후 부모 에이전트에 결과를 반환합니다.

서브에이전트 실행 방식:
- **로컬** — 인프로세스, 부모의 파일시스템과 셸 공유
- **원격** — 원격 에이전트 자격 기준이 충족될 때 별도 컴퓨팅에서 실행

개방형 다단계 검색, 병렬 워크스트림, 또는 독립된 서브 문제를 격리된 에이전트에 위임할 때 사용하세요.

**TodoWrite — 작업 목록 관리**
구조화된 할 일 항목(`pending`, `in_progress`, `completed` 상태)을 터미널 UI의 영구 패널에 씁니다. Claude가 복잡한 다단계 작업의 진행 상황을 추적하는 데 도움이 됩니다. 3개 이상의 별개 단계가 있는 작업에 적극적으로 사용하세요.

## MCP 도구

MCP(Model Context Protocol) 서버가 Claude Code에 추가 도구를 노출할 수 있습니다. 연결된 도구는 내장 도구와 함께 도구 목록에 나타나며 동일한 권한 시스템을 따릅니다.

MCP 도구 이름 형식:
```
mcp__<server-name>__<tool-name>
```

예: `mydb` 서버의 `query` 도구 → `mcp__mydb__query`

일반적인 MCP 도구 범주:
- 데이터베이스 쿼리 및 관리 도구
- 브라우저 및 웹 자동화 도구
- 클라우드 제공업체 API (AWS, GCP, Azure)
- 이슈 트래커 통합 (GitHub, Linear, Jira)
- 내부 회사 도구 및 API

## 노트북 도구

**NotebookEdit — Jupyter 노트북 편집**
`.ipynb` 파일의 셀을 줄 단위 정밀도로 삽입, 교체, 삭제합니다. 노트북 읽기는 표준 `Read` 도구를 사용합니다(모든 셀과 출력 반환).

## 도구 가용성

모든 도구가 모든 컨텍스트에서 이용 가능한 것은 아닙니다:
- `CLAUDE_CODE_SIMPLE=1` — `Bash`, `Read`, `Edit`만으로 제한
- 권한 차단 규칙 — 규칙으로 포괄 차단된 도구는 모델이 보기 전에 목록에서 제거됨
- `isEnabled()` 검사 — 각 도구는 환경 조건에 따라 자가 비활성화 가능
- MCP 서버 연결 상태 — MCP 도구는 서버가 실행 중이고 연결된 경우에만 이용 가능

REPL에서 `/tools` 커맨드로 활성 도구 집합을 확인할 수 있습니다.
