Initial commit to new repository

docs/claude-code-docs-main/07_도구목록.md

@@ -0,0 +1,102 @@
+# 도구 목록
+
+> 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` 커맨드로 활성 도구 집합을 확인할 수 있습니다.