도구 시스템 아키텍처

도구 시스템 개요

Claude Code의 도구 시스템은 모델이 실제 세계와 상호작용하는 인터페이스입니다. 모델은 자연어로 의도를 표현하고, 도구 시스템이 그 의도를 실제 파일 조작, 셸 실행, 네트워크 요청으로 변환합니다.

모든 도구는 공통 인터페이스를 구현하며, 이 인터페이스를 통해 등록·실행·권한 평가가 일관되게 처리됩니다.

도구 카테고리 (~40개 도구)

소스 코드 분석에 의하면 Claude Code는 약 40개 도구 를 내장하고 있습니다.

#	카테고리	도구	설명
1	파일 I/O	Read, Edit, Write, Glob, NotebookEdit	로컬 파일 시스템 접근
2	셸 실행	Bash	터미널 명령 실행
3	검색	Grep, LS, LSP	파일·내용·심볼 탐색
4	웹 접근	WebFetch, WebSearch	인터넷 정보 조회
5	에이전트·태스크	Agent, SendMessage, Task, TodoWrite	서브에이전트 스폰·통신·작업 관리
6	상태·제어	PlanMode, Worktree, Sleep, Cron, Skill, MCP	모드 전환·격리·스케줄링·확장

각 카테고리는 서로 다른 권한 프로필을 가집니다. 파일 읽기와 Glob은 기본적으로 자동 승인되지만, 셸 실행과 웹 접근은 사용자 확인이 필요합니다.

도구 인터페이스

모든 도구는 다음 인터페이스를 구현합니다.

interface Tool<TInput, TOutput> {
  // 도구 식별 정보
  name: string
  description: string
  parameters: JSONSchema  // 입력 파라미터 스키마

  // 핵심 실행 메서드
  execute(input: TInput): Promise<TOutput>

  // 권한 평가 (실행 전 호출)
  checkPermissions(input: TInput): Promise<'allow' | 'ask' | 'deny'>

  // 도구 활성화 여부 (환경 조건 기반)
  isEnabled(): boolean

  // 결과 크기 제한 (초과 시 임시 파일로 저장)
  maxResultSizeChars?: number
}

checkPermissions 메서드

권한 평가의 핵심 메서드입니다. 세 가지 값을 반환합니다.

반환값	의미	사용자 경험
`allow`	자동 승인	즉시 실행, 사용자에게 묻지 않음
`ask`	확인 필요	승인/거부 다이얼로그 표시
`deny`	항상 차단	오류 반환, 실행 불가

// Bash 도구의 checkPermissions 예시 (단순화)
async checkPermissions(input: BashInput): Promise<Permission> {
  // 명시적 deny 규칙 확인
  if (matchesDenyRules(input.command)) return 'deny'

  // 읽기 전용 명령어는 자동 허가
  if (isReadOnlyCommand(input.command)) return 'allow'

  // 명시적 allow 규칙 확인
  if (matchesAllowRules(input.command)) return 'allow'

  // 그 외는 사용자 확인
  return 'ask'
}

isEnabled 메서드

도구가 현재 환경에서 사용 가능한지 자체 검사합니다. 등록 시 호출되어 불필요한 도구를 목록에서 제외합니다.

// WebSearch 도구의 isEnabled 예시
isEnabled(): boolean {
  // 미국 이외 지역에서는 비활성화
  return process.env.CLAUDE_CODE_REGION === 'US'
}

도구 등록 메커니즘

애플리케이션 시작 시 모든 도구가 레지스트리에 등록됩니다.

// 도구 등록 흐름 (단순화)
const registry = new ToolRegistry()

// 내장 도구 등록
for (const Tool of BUILTIN_TOOLS) {
  const instance = new Tool()
  if (instance.isEnabled()) {
    registry.register(instance)
  }
}

// MCP 도구 등록 (서버별 네임스페이스)
for (const [serverName, tools] of mcpTools) {
  for (const tool of tools) {
    registry.register(tool, `mcp__${serverName}__${tool.name}`)
  }
}

도구 비활성화 방법

1. 설정 파일의 deny 규칙

{
  "permissions": {
    "deny": [
      "WebFetch(*)",      // 모든 웹 접근 차단
      "Bash(npm publish)" // 특정 명령만 차단
    ]
  }
}

2. CLAUDE_CODE_SIMPLE 모드

CLAUDE_CODE_SIMPLE=1 환경 변수를 설정하면 최소 도구 세트만 활성화됩니다.

모드	사용 가능한 도구
기본 모드	모든 내장 도구 + MCP 도구
SIMPLE 모드	Bash, Read, Edit 만 사용 가능

SIMPLE 모드는 CI 파이프라인이나 제한된 환경에서 도구 범위를 최소화할 때 유용합니다.

3. isEnabled 자체 검사

도구 구현 내부에서 환경 조건에 따라 스스로 비활성화합니다. 예를 들어 특정 OS에서만 동작하는 도구나 특정 API 키가 필요한 도구에 활용됩니다.

도구 목록 확인

현재 활성화된 도구를 REPL에서 확인할 수 있습니다.

# REPL 명령어로 사용 가능한 도구 확인
/tools

# 출력 예시
Available tools (12):
  Read         - Read file contents
  Edit         - Edit file with string replacement
  Write        - Write file contents
  Glob         - Find files by pattern
  Bash         - Execute shell commands
  Grep         - Search file contents
  LS           - List directory contents
  WebFetch     - Fetch web content
  WebSearch    - Search the web
  Task         - Spawn a subagent
  TodoWrite    - Manage task list
  NotebookEdit - Edit Jupyter notebooks

maxResultSizeChars

도구 결과가 지나치게 크면 컨텍스트 윈도우를 낭비합니다. 각 도구는 maxResultSizeChars 로 결과 크기를 제한합니다.

도구	기본 제한	초과 시 동작
Read	200,000자	지정 범위만 읽도록 안내
Bash	100,000자	임시 파일에 저장 후 경로 반환
Grep	50,000자	결과 잘림 안내
WebFetch	50,000자	보조 모델로 요약 처리