도구 레퍼런스 (Tools Reference)

읽는 시간: 15분 | 난이도: 중급자

Claude Code가 사용하는 모든 도구의 완전한 참조 가이드입니다. 권한 설정, 서브에이전트 도구 목록, 훅 매처에서 사용하는 정확한 도구명을 확인할 수 있습니다.

(출처: 공식 문서)

개요

Claude Code는 코드베이스를 이해하고 수정하는 데 도움이 되는 도구 세트에 접근할 수 있습니다. 아래의 도구명은 권한 규칙, 서브에이전트 도구 목록, 훅 매처에서 사용하는 정확한 문자열입니다.

1. 전체 도구 목록

1.1 파일 작업 도구

파일을 읽고, 쓰고, 수정하는 데 사용하는 도구입니다.

사용 예시:

# 권한 규칙에서 특정 도구 허용
/permissions allow Read
/permissions allow Edit src/**
/permissions deny Write /etc/**

1.2 검색 도구

파일이나 코드 내용을 검색하는 데 사용하는 도구입니다.

1.3 실행 도구

명령어나 웹 요청을 실행하는 도구입니다.

1.4 코드 인텔리전스 도구 (LSP)

언어 서버를 통한 코드 인텔리전스 도구입니다.

1.5 스케줄링 도구

세션 내에서 작업을 예약하는 도구입니다.

주의: CronCreate로 생성된 예약 작업은 Claude Code 세션이 종료되면 함께 사라집니다. 영구적인 스케줄링이 필요하다면 시스템 cron이나 별도 스케줄러를 사용하세요.

1.6 작업 관리 도구

태스크와 백그라운드 작업을 관리하는 도구입니다.

1.7 에이전트 및 계획 도구

서브에이전트를 생성하거나 계획 모드를 사용하는 도구입니다.

1.8 MCP 도구

MCP(Model Context Protocol) 서버와 상호작용하는 도구입니다.

1.9 기타 도구

2. Bash 도구 동작 방식 {#bash-tool-behavior}

Bash 도구는 각 명령어를 별도의 프로세스에서 실행하며, 다음과 같은 지속성 동작을 따릅니다.

2.1 작업 디렉토리 지속성

작업 디렉토리는 명령어 간에 유지됩니다.

# 첫 번째 Bash 호출
cd /my/project

# 두 번째 Bash 호출 - /my/project에서 시작됨
pwd  # /my/project 출력

매 명령어 후 프로젝트 디렉토리로 초기화하려면 환경 변수를 설정하세요:

export CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1

2.2 환경 변수 비지속성

환경 변수는 명령어 간에 유지되지 않습니다. 한 명령어에서의 export는 다음 명령어에서 사용할 수 없습니다.

# 이렇게 하면 안 됨 - 다음 Bash 호출에서 MY_VAR를 사용할 수 없음
export MY_VAR=hello

# 다음 호출에서
echo $MY_VAR  # 빈 문자열 출력

환경 변수를 Bash 명령어 간에 유지하려면 다음 방법을 사용하세요:

방법 1: CLAUDE_ENV_FILE 설정

Claude Code를 시작하기 전에 셸 스크립트 경로를 설정합니다:

export CLAUDE_ENV_FILE=/path/to/my-env.sh
claude

my-env.sh 파일 예시:

export DATABASE_URL=postgres://localhost/mydb
export NODE_ENV=development
export API_KEY=my-api-key

방법 2: SessionStart 훅 사용

훅을 사용하여 동적으로 환경 변수를 설정합니다:

{
  "hooks": {
    "SessionStart": [
      {
        "command": "echo 'export MY_VAR=hello' >> $CLAUDE_ENV_FILE"
      }
    ]
  }
}

2.3 가상 환경 사용

가상 환경이나 conda 환경은 Claude Code를 시작하기 전에 활성화해야 합니다:

# Python 가상 환경
source .venv/bin/activate
claude

# conda 환경
conda activate myenv
claude

3. 권한 요구 도구 요약

권한이 필요한 도구 목록을 한눈에 확인하세요.

권한 설정 방법:

# 대화형으로 설정
/permissions

# 특정 도구 허용
/permissions allow Bash

# 패턴으로 제한
/permissions allow Edit src/**
/permissions deny Bash rm -rf

권한 시스템에 대한 자세한 내용은 권한 가이드를 참조하세요.

4. 도구 카테고리별 활용 시나리오

4.1 코드 수정 워크플로우

Glob → 파일 검색
Read → 파일 내용 확인
Grep → 특정 패턴 검색
Edit → 대상 수정 적용
LSP → 타입 에러 확인
Bash → 테스트 실행

4.2 멀티 에이전트 워크플로우

Agent → 서브에이전트 생성
TaskCreate → 작업 등록
TaskList → 작업 상태 확인
TaskOutput → 백그라운드 작업 결과 수집
TaskUpdate → 작업 상태 업데이트

4.3 계획 기반 워크플로우

AskUserQuestion → 요구사항 수집
EnterPlanMode → 계획 모드 전환
(계획 수립)
ExitPlanMode → 계획 승인 요청
(승인 후 구현 시작)

4.4 MCP 통합 워크플로우

ListMcpResourcesTool → 사용 가능한 MCP 리소스 확인
ReadMcpResourceTool → 특정 리소스 읽기

5. 훅과 서브에이전트에서 도구명 사용

도구명은 훅 매처와 서브에이전트 도구 목록에서 정확한 문자열로 사용해야 합니다.

5.1 훅 매처 예시

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo 'Bash 도구 실행 전'"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "prettier --write $TOOL_INPUT_FILE_PATH"
      }
    ]
  }
}

5.2 서브에이전트 도구 목록 예시

{
  "subagent": {
    "allowed_tools": ["Read", "Glob", "Grep", "Bash"]
  }
}

서브에이전트 설정에 대한 자세한 내용은 서브에이전트 가이드를 참조하세요.

6. 도구별 참고 사항

TodoWrite vs 작업 관리 도구

Agent 도구 활용

Agent 도구는 독립적인 컨텍스트 윈도우를 가진 서브에이전트를 생성합니다. 대규모 코드베이스에서 병렬 작업이 필요하거나, 메인 컨텍스트를 오염시키지 않고 독립적인 작업을 수행할 때 유용합니다.

LSP 도구 요구 사항

LSP 도구를 사용하려면 다음이 필요합니다:

• 코드 인텔리전스 플러그인 설치
• 해당 언어 서버 바이너리 설치 (예: TypeScript용 typescript-language-server, Python용 pylsp)

EnterWorktree / ExitWorktree

git 워크트리를 통해 격리된 환경에서 작업할 수 있습니다. 브랜치 전환 없이 여러 작업을 병렬로 수행할 때 유용합니다.

참고 자료

• 공식 도구 레퍼런스
• 권한 시스템 가이드
• 서브에이전트 설정
• 훅 설정 가이드