클로드 코드 내장 도구 총정리

클로드 코드를 쓰다 보면 파일을 읽거나 코드를 수정하는 것은 사실 Claude가 직접 하는 게 아니라 도구(Tool)를 호출해서 처리한다는 걸 알게 됩니다. 코딩 에이전트의 작동 원리에서 다뤘듯이, 언어 모델 자체는 텍스트를 생성하는 것밖에 못 하고 실제 작업은 도구가 대신하는 거죠.

그런데 이 도구 이름을 알아야 하는 이유가 있습니다. 권한 설정에서 Bash(npm run *), Read(./.env) 같은 규칙을 쓸 때 도구 이름이 필요하고, Hooks에서 PreToolUse 매처를 작성할 때도, 서브 에이전트에 허용할 도구를 지정할 때도 마찬가지입니다. 이 글에서는 클로드 코드의 30개 내장 도구를 카테고리별로 정리해 보겠습니다.

전체 도구 목록

먼저 전체 그림을 보겠습니다.

도구	설명	권한 필요
Read	파일 내용 읽기	아니오
Glob	파일 패턴 검색	아니오
Grep	파일 내용에서 패턴 검색	아니오
LSP	언어 서버 기반 코드 인텔리전스	아니오
Edit	파일 부분 수정	예
Write	파일 생성 또는 덮어쓰기	예
NotebookEdit	Jupyter 노트북 셀 수정	예
Bash	셸 명령어 실행	예
Monitor	백그라운드 실행 출력을 실시간 전달	예
PowerShell	PowerShell 명령어 실행 (opt-in)	예
WebFetch	URL에서 콘텐츠 가져오기	예
WebSearch	웹 검색	예
Agent	서브 에이전트 생성	아니오
Skill	스킬 실행	예
EnterPlanMode	계획 모드 진입	아니오
ExitPlanMode	계획 모드 종료 및 계획 제출	예
EnterWorktree	Git worktree 격리 환경 생성	아니오
ExitWorktree	Worktree에서 원래 디렉토리로 복귀	아니오
TaskCreate	작업 생성	아니오
TaskGet	작업 상세 조회	아니오
TaskList	전체 작업 목록 조회	아니오
TaskUpdate	작업 상태 업데이트	아니오
TaskOutput	백그라운드 작업 출력 조회 (deprecated)	아니오
TaskStop	실행 중인 백그라운드 작업 중단	아니오
TodoWrite	비대화형 모드 작업 체크리스트 관리	아니오
CronCreate	예약 작업 생성	아니오
CronDelete	예약 작업 취소	아니오
CronList	예약 작업 목록 조회	아니오
AskUserQuestion	사용자에게 질문	아니오
ListMcpResourcesTool	MCP 서버 리소스 목록 조회	아니오
ReadMcpResourceTool	MCP 리소스 읽기	아니오
ToolSearch	지연 로딩 도구 검색	아니오

30개 도구 중 권한이 필요한 건 8개뿐이고, 나머지 22개는 자유롭게 사용됩니다. 권한이 필요한 도구들을 보면 패턴이 보이는데요. 파일을 변경하거나, 명령어를 실행하거나, 외부에 접근하는 도구만 권한을 요구합니다. 읽기만 하는 도구는 권한 없이 동작하죠.

공식 문서의 Tools Reference에서 각 도구의 상세 스펙을 확인할 수 있습니다.

이제 카테고리별로 살펴보겠습니다.

코드 읽기 도구

코딩 에이전트가 가장 많이 쓰는 도구들입니다. 코드를 고치려면 먼저 이해해야 하니까요.

Read는 파일 내용을 읽어옵니다. 소스 코드는 물론이고 설정 파일, 이미지, PDF도 읽을 수 있어요. 파일이 크면 줄 번호 범위를 지정해서 필요한 부분만 가져오기도 하죠.

Glob은 파일 이름 패턴으로 검색합니다. **/*.tsx로 TSX 파일을 전부 찾거나 src/components/**/*.test.ts로 테스트 파일만 골라내는 식입니다. 코드베이스 구조를 파악할 때 유용해요.

Grep은 파일 내용에서 텍스트 패턴을 찾습니다. 정규식을 지원하고 파일 타입이나 glob 패턴으로 범위를 좁힐 수 있어서 “이 함수를 어디서 호출하고 있지?” 같은 질문에 빠르게 답해 줍니다.

LSP는 좀 특별한 도구입니다. 언어 서버 프로토콜을 통해 IDE 수준의 코드 인텔리전스를 제공하는데요. 정의로 이동하거나 참조를 찾고 타입 정보를 조회하는 것은 물론 파일 수정 후 타입 에러나 경고를 자동으로 보고합니다. 다만 코드 인텔리전스 플러그인과 해당 언어 서버 바이너리를 별도로 설치해야 해요.

네 도구 전부 권한 없이 동작합니다. 코드를 이해하는 건 언제든 자유롭게 할 수 있어야 하니까요.

코드 수정 도구

코드를 이해했으면 이제 고칠 차례입니다.

Edit는 파일의 특정 부분만 수정합니다. 기존 텍스트를 찾아서 새 텍스트로 바꾸는 방식이라 파일 전체를 다시 쓸 필요가 없어요. 대부분의 코드 변경이 이 도구로 이뤄집니다.

Write는 파일을 통째로 생성하거나 덮어쓰는 도구입니다. 기존 파일 수정에는 Edit가 훨씬 효율적이라 Write는 주로 새 파일을 만들 때 씁니다.

NotebookEdit는 Jupyter 노트북(.ipynb)의 셀을 수정해 줍니다. 노트북 특유의 JSON 구조를 직접 건드리지 않아도 셀 단위로 편집할 수 있죠.

세 도구 모두 권한이 필요합니다. 파일 변경은 되돌리기 어려울 수 있으니까요. 권한 설정의 acceptEdits 모드를 쓰면 파일 편집 승인 팝업을 건너뛸 수 있습니다.

명령어 실행 도구

Bash는 셸 명령어를 실행합니다. 테스트 실행, 빌드, Git 작업, 패키지 설치 등 터미널에서 할 수 있는 모든 걸 이 도구로 처리해요.

알아두면 좋은 동작 특성이 있습니다. 작업 디렉토리는 명령어 사이에 유지됩니다. 한 번 cd src를 하면 다음 명령어에서도 src 디렉토리에서 실행되죠. 반면 환경 변수는 유지되지 않습니다. 한 명령어에서 export FOO=bar를 해도 다음 명령어에서 $FOO를 쓸 수 없어요. 각 명령어가 별도의 프로세스에서 실행되기 때문입니다.

환경 변수를 유지하고 싶으면 CLAUDE_ENV_FILE 환경 변수에 셸 스크립트 경로를 지정하거나, Hooks의 SessionStart 이벤트로 동적으로 설정할 수 있습니다. virtualenv나 conda 같은 가상 환경은 클로드 코드를 시작하기 전에 미리 활성화해두세요.

개발 서버처럼 오래 실행되는 명령어는 run_in_background 옵션으로 백그라운드에서 돌릴 수 있습니다. 실행 중인 명령어를 Ctrl+B로 백그라운드로 전환하는 것도 가능하고요. 자세한 활용법은 백그라운드 프로세스 가이드를 참고하세요.

Bash는 당연히 권한이 필요합니다. Bash(npm run test *)처럼 특정 명령어 패턴만 허용하거나, Bash(rm -rf *)처럼 위험한 패턴은 차단하는 세밀한 제어가 가능합니다. 자세한 패턴 문법은 권한 설정 가이드를 참고하세요.

웹 접근 도구

WebFetch는 지정한 URL에서 콘텐츠를 가져옵니다. 공식 문서나 API 레퍼런스를 참고할 때 주로 쓰이고, HTML을 마크다운으로 변환해서 돌려줍니다.

WebSearch는 웹 검색입니다. 최신 라이브러리 사용법이나 에러 해결 방법을 찾아야 할 때 유용하죠.

두 도구 모두 권한이 필요하고 WebFetch(domain:docs.anthropic.com)처럼 도메인 단위로 세밀하게 제어할 수 있습니다.

작업 관리 도구

복잡한 작업을 체계적으로 진행하기 위한 도구들입니다.

TaskCreate, TaskGet, TaskList, TaskUpdate, TaskOutput, TaskStop은 작업(Task) 관리 도구 세트예요. Claude가 큰 작업을 여러 단계로 쪼개서 진행 상황을 추적하는 데 사용합니다. 백그라운드 작업의 출력을 확인하거나 필요하면 중단할 수도 있죠.

TodoWrite는 비대화형 모드(CI/CD나 Agent SDK)에서 작업 체크리스트를 관리합니다. 대화형 세션에서는 위의 Task* 도구들이 대신 쓰여요.

CronCreate, CronDelete, CronList는 세션 내에서 반복 작업을 예약합니다. 5분마다 빌드 상태를 확인하거나 주기적으로 로그를 체크하는 식이에요. 세션이 종료되면 예약도 함께 사라집니다.

작업 관리 도구는 전부 권한 없이 동작합니다. 계획하고 추적하는 건 외부에 영향을 주지 않으니까요.

에이전트와 모드 도구

Agent는 독립된 컨텍스트 윈도우를 가진 서브 에이전트를 생성합니다. 복잡한 작업을 병렬로 분배하거나 대량의 검색 결과가 메인 컨텍스트를 오염시키지 않도록 격리할 때 쓰이죠. 서브 에이전트가 사용할 수 있는 도구를 제한할 수 있는데 여기서도 도구 이름이 필요합니다.

Skill은 사용자가 정의한 스킬을 실행하는 도구입니다. /commit이나 /review-pr 같은 슬래시 커맨드가 내부적으로 이 도구를 통해 호출돼요.

EnterPlanMode와 ExitPlanMode는 계획 모드 전환을 담당합니다. 계획 모드에서는 Read, Glob, Grep 같은 읽기 도구만 쓸 수 있고 파일 수정이나 명령어 실행은 막혀요. 권한 모드에서 defaultMode를 plan으로 지정해서 세션을 계획 모드로 시작할 수도 있습니다. 재미있는 점은 ExitPlanMode만 권한이 필요하다는 건데, 계획을 확정하고 실행 모드로 넘어가는 건 사용자가 승인하는 게 안전하기 때문입니다.

EnterWorktree와 ExitWorktree는 Git worktree 기반의 격리 작업 환경을 관리합니다. 원본 코드를 건드리지 않고 실험적인 변경을 시도할 때 유용해요.

MCP 연동 도구

ListMcpResourcesTool과 ReadMcpResourceTool은 연결된 MCP 서버의 리소스를 탐색하고 읽는 도구입니다.

ToolSearch는 MCP 서버에서 도구 검색이 활성화돼 있을 때 지연 로딩된 도구를 찾아서 불러옵니다. MCP 서버가 수백 개의 도구를 제공할 때 전부 한 번에 로딩하면 비효율적이니까 필요한 도구만 검색해서 로딩하는 거죠.

MCP를 통해 추가되는 도구들은 mcp__서버이름__도구이름 형식의 이름을 갖습니다. 이 이름은 권한 규칙에서 그대로 사용할 수 있어요. 예를 들어 mcp__github__create_issue를 allow에 넣으면 GitHub 이슈 생성을 자동 허용합니다.

사용자 상호작용 도구

AskUserQuestion은 Claude가 사용자에게 질문을 던질 때 쓰는 도구입니다. 요구사항이 모호하거나 여러 선택지가 있을 때 객관식으로 물어봐요. 덕분에 Claude가 추측으로 밀고 나가는 대신 사용자에게 확인하고 넘어갈 수 있죠.

도구 이름이 쓰이는 곳

도구의 기능을 아는 것도 중요하지만 실무에서 도구 이름을 직접 써야 하는 곳이 세 군데 있습니다.

첫째, 권한 규칙입니다. settings.json의 allow, deny, ask 배열에 도구 이름을 써서 접근을 제어합니다.

{
  "permissions": {
    "allow": ["Bash(npm run *)"],
    "deny": ["Bash(rm -rf *)", "Read(./.env)"]
  }
}

둘째, Hooks 매처입니다. PreToolUse나 PostToolUse 이벤트의 matcher 필드에 도구 이름을 써서 특정 도구 호출 전후에 커스텀 명령을 실행합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "prettier --write $CLAUDE_FILE_PATH" }
        ]
      }
    ]
  }
}

셋째, 서브 에이전트 도구 제한입니다. 서브 에이전트 정의에서 tools 필드에 허용할 도구를 나열합니다.

---
tools: Read, Grep, Glob, Bash
---

이 세 곳에서 사용하는 도구 이름은 전부 이 글의 표에 있는 이름과 정확히 일치해야 합니다. 대소문자도 구분하니까 bash가 아니라 Bash, read가 아니라 Read로 써야 해요.

마치며

클로드 코드의 30개 내장 도구는 크게 읽기(Read, Glob, Grep, LSP), 쓰기(Edit, Write, Bash), 외부 접근(WebFetch, WebSearch), 작업 관리(Task, Cron), 에이전트(Agent, Plan, Worktree, Skill), 확장(MCP 관련) 도구로 나뉩니다.

권한이 필요한 8개 도구는 전부 파일을 변경하거나 명령어를 실행하거나 외부에 접근하는 것들이에요. 나머지 22개는 읽기와 계획, 관리에 쓰이는 도구로 자유롭게 사용됩니다.

도구 이름을 알아두면 권한 설정으로 특정 도구를 정밀하게 제어하고 Hooks로 도구 전후에 커스텀 로직을 끼워넣고 서브 에이전트에 꼭 필요한 도구만 허용할 수 있습니다. 클로드 코드를 더 안전하고 효율적으로 쓰기 위한 기초 지식이라고 할 수 있겠습니다.