Claude Code CLI 가이드: 설치, 설정, 명령어, 환경 변수

요약: Claude Code는 코드베이스를 읽고, 명령을 실행하며, 권한, hooks, MCP 통합, subagents로 이루어진 계층형 시스템을 통해 파일을 수정하는 agentic CLI입니다. 5가지 핵심 시스템(설정, 권한, hooks, MCP, subagents)을 익히면 생산성을 크게 끌어올릴 수 있습니다. 각 작업에 맞는 모델 티어를 선택하세요. 복잡한 추론에는 Opus, 일반 작업에는 Sonnet, 빠른 탐색에는 Haiku를 사용하면 됩니다. 품질만이 유일한 기준이라면 Opus로 표준화하세요. 항상 실행되어야 하는 작업에는 prompts가 아니라 hooks를 사용하세요. v2.1.174–176(2026년 6월 12일)부터 availableModels 허용 목록은 이제 새 enforceAvailableModels 관리 설정을 통해 Default 모델도 제한할 수 있습니다. 사용자/프로젝트 설정은 관리형 목록을 확장할 수 없으며, 세션 제목은 대화 언어로 생성됩니다(language 설정으로 하나를 고정할 수 있습니다). 또한 새 footerLinksRegexes 및 wheelScrollAccelerationEnabled 설정, VSCode /usage 귀속 대화상자, hook if 조건이 Read/Edit/Write 경로 패턴과 일치하도록 하는 수정이 이번 릴리스를 마무리합니다.¹⁷² v2.1.173(2026년 6월 11일)부터는 [1m] 접미사가 붙은 Fable 5 모델 이름이 자동으로 정규화/제거됩니다. Fable 5는 기본적으로 이미 1M 컨텍스트를 포함하므로 접미사가 필요 없습니다. 이 접미사는 원래 Opus/Sonnet에서만 의미가 있었습니다. v2.1.172(2026년 6월 10일)부터는 sub-agents가 최대 5단계 깊이까지 자기 자신의 sub-agents를 재귀적으로 생성할 수 있고, AWS_REGION이 설정되어 있지 않으면 Bedrock은 ~/.aws에서 리전을 읽으며(/status가 출처를 표시합니다), /plugin에는 marketplace 검색창이 추가되고, claude_code.lines_of_code.count OTEL metric에는 model 속성이 추가됩니다. v2.1.170(2026년 6월 9일)부터는 Opus보다 높은 새 모델 티어인 Claude Fable 5를 claude update 후 /model fable로 Claude Code에서 선택할 수 있습니다. 이 모델은 전체 low–max effort 범위를 지원하지만 thinking을 비활성화할 수는 없습니다. Opus 4.8은 계속 agentic 기본값입니다. v2.1.169(2026년 6월 8일)부터 --safe-mode 및 CLAUDE_CODE_SAFE_MODE는 문제 해결을 위해 모든 사용자 지정을 비활성화한 깨끗한 세션을 시작하고, /cd는 prompt cache를 깨뜨리지 않고 세션을 새 작업 디렉터리로 이동하며, disableBundledSkills는 기본 제공 skills와 slash commands를 모델에서 숨깁니다. v2.1.166(2026년 6월 6일)부터 fallbackModel 설정은 기본 모델이 과부하일 때 최대 3개의 백업 모델을 연결하고, glob "*"는 MCP deny 규칙에서 작동하며, MAX_THINKING_TOKENS=0 / --thinking disabled는 기본적으로 think하는 모델에서 thinking을 완전히 끕니다. v2.1.154(2026년 5월 28일)부터는 Opus 4.8이 기본적으로 high effort를 사용하는 새 기본값이 되었고 /effort xhigh 레벨이 추가되었으며, dynamic workflows는 /workflows를 통해 백그라운드에서 수십에서 수백 개의 agents를 오케스트레이션합니다. Opus 4.8의 Fast mode는 2.5배 속도에 표준 요금의 2배 비용이 들고, lean system prompt는 이제 Haiku/Sonnet/Opus 4.7 이하를 제외한 모든 모델의 기본값입니다. /simplify는 /code-review --fix와 별개인 cleanup 전용 review로 되돌아갔고, claude agents는 ! <command>를 받아 백그라운드 shell 세션을 생성합니다. plugins는 defaultEnabled: false를 선언할 수 있고, streaming tool execution은 항상 활성화되며, stdio MCP 서버는 env에서 CLAUDE_CODE_SESSION_ID와 CLAUDECODE=1을 받습니다. v2.1.153은 plugin marketplaces에 skipLfs를 추가하고, /model이 기본값으로 저장되도록 했으며(세션 전용은 s를 누르세요), status-line env에 COLUMNS/LINES를 넣었습니다. v2.1.152는 /code-review --fix(발견 사항을 working tree에 적용), skill frontmatter의 disallowed-tools, /reload-skills, 새 MessageDisplay hook event, SessionStart hook의 reloadSkills/sessionTitle 출력, pluginSuggestionMarketplaces 관리 설정, 세션 중 --fallback-model 전환을 도입했고, auto-mode opt-in을 제거했습니다.^{162 163 164 165 166 167 168 169 170 180 171}

Claude Code는 프로그래밍 지식을 갖춘 chat 인터페이스가 아니라 agentic system으로 작동합니다. CLI는 코드베이스를 읽고, 명령을 실행하며, 파일을 수정하고, git workflow를 관리하고, MCP를 통해 외부 서비스에 연결하며, 복잡한 작업을 전문 subagents에 위임합니다. 이 모든 것은 개발자가 실제로 일하는 방식에 통합되는 command-line interface를 통해 흐릅니다. 2026년 2월 기준, 공개 GitHub commits의 4%(하루 약 135,000건)가 Claude Code로 작성되었습니다. 이는 research preview 이후 13개월 만에 42,896배 성장한 수치이며, Anthropic 자체 코드의 90%는 AI가 작성했습니다.¹⁰³

Claude Code를 가볍게 쓰는 것과 효과적으로 쓰는 것의 차이는 5가지 핵심 시스템에서 갈립니다. 이 시스템들을 익히면 Claude Code는 생산성을 크게 높이는 도구가 됩니다.

1. 설정 계층: 동작을 제어합니다
2. 권한 시스템: 작업을 제한합니다
3. Hook 시스템: 결정적 자동화를 가능하게 합니다
4. MCP protocol: 기능을 확장합니다
5. Subagent 시스템: 복잡한 다단계 작업을 처리합니다

핵심 요약

• 5가지 시스템이 효과를 좌우합니다: 설정 계층, 권한, hooks, MCP, subagents는 동작부터 자동화까지 모든 것을 제어합니다.
• 작업을 Delegation Layer로 넘기세요: subagents는 탐색을 깨끗한 컨텍스트 창에 격리하고 요약만 반환해 컨텍스트 비대를 막습니다.
• Hooks는 실행을 보장하지만 prompts는 그렇지 않습니다: 모델 동작과 관계없이 매번 실행되어야 하는 linting, formatting, security checks에는 hooks를 사용하세요.
• 모델 티어링은 품질을 희생하지 않고 비용을 줄입니다: subagent 탐색은 더 저렴한 모델로 보내고, 진짜 아키텍처 추론에는 Opus를 남겨두세요. 품질만이 유일한 기준이라면 Opus로 표준화하세요.
• MCP는 Claude를 toolchain에 연결합니다: databases, GitHub, Sentry, 3,000개 이상의 통합은 Claude를 파일 읽기와 bash commands 너머로 확장합니다.

저는 프로덕션 코드베이스, CI/CD pipelines, enterprise 배포 전반에서 몇 달 동안 Claude Code를 한계까지 밀어붙였습니다. 이 가이드는 제가 시작할 때 있었으면 했던 완전한 reference로 그 경험을 압축한 것입니다. 모든 기능에는 실제 syntax, 실제 설정 예시, 숙련된 사용자도 걸려 넘어지는 edge cases가 포함되어 있습니다.

경로 선택하기

이 가이드 사용법

이 문서는 5,000줄이 넘는 reference입니다. 처음부터 끝까지 다 읽을 필요는 없습니다. 자신의 경험 수준에 맞는 곳에서 시작하세요.

특정 flags, commands, 설정 키를 찾으려면 브라우저의 Ctrl+F / Cmd+F를 사용하세요. 끝부분의 Quick Reference Card는 모든 주요 commands를 훑어보기 쉬운 요약으로 제공합니다.

관련 Deep Dives

다음 blog posts는 Claude Code의 특정 측면을 깊이 있게 다룹니다.

60초 빠른 시작

Claude Code을 실행하고 출력만 확인하고 싶다면, 다음 순서대로 진행하세요.

# 1. Install (pick one)
npm install -g @anthropic-ai/claude-code          # npm users
brew install anthropic/claude/claude              # macOS + Homebrew
curl -sL claude.ai/install.sh | sh                # native installer

# 2. Launch in any project directory
cd ~/your-project && claude

# 3. Authenticate (browser opens automatically on first run)
/login

# 4. Ask your first question
> What does this repo do? Read the key files and summarize.

이것으로 끝입니다. 아래의 모든 내용은 설치 옵션을 자세히 설명하고, 권한과 hooks를 설정하며, MCP 서버를 연결하고, 엔터프라이즈 배포까지 다룹니다. 하지만 시작하는 데 반드시 필요한 내용은 아닙니다.

사전 요구 사항: Node 18+는 기존 npm 경로에서만 필요합니다. 권장되는 네이티브 설치 프로그램은 Node 의존성이 없습니다. macOS / Linux / Windows 10+가 지원됩니다. Claude Pro, Max, Team, Enterprise 구독 또는 토큰별 과금 방식의 Anthropic API 키로 사용할 수 있습니다. 플랫폼별 세부 사항, 문제 해결, 네이티브 바이너리 경로(v2.1.113부터 기본값)는 Claude Code은 어떻게 설치하나요?를 참고하세요. 이 가이드의 최신 릴리스 근거는 v2.1.154를 기준으로 확인했습니다.¹⁸⁰

Claude Code의 작동 방식: 핵심 모델

기능을 자세히 살펴보기 전에, Claude Code의 아키텍처가 사용 방식 전반을 어떻게 결정하는지 이해해야 합니다. 이 시스템은 3개 계층으로 작동합니다.

┌─────────────────────────────────────────────────────────┐
│                    CLAUDE CODE LAYERS                    │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  External tools, deterministic automation, domain       │
│  expertise, packaged extensions                          │
├─────────────────────────────────────────────────────────┤
│  DELEGATION LAYER                                        │
│  ┌─────────────────────────────────────────────────┐    │
│  │              Subagents (up to 10 parallel)       │    │
│  │   Explore | Plan | General-purpose | Custom      │    │
│  └─────────────────────────────────────────────────┘    │
│  Isolated contexts for focused work, returns summaries  │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         Main Conversation Context                │    │
│  │   Tools: Read, Edit, Bash, Glob, Grep, etc.     │    │
│  └─────────────────────────────────────────────────┘    │
│  Your primary interaction; limited context; costs money │
└─────────────────────────────────────────────────────────┘

Core Layer: 기본 대화입니다. 모든 메시지, 파일 읽기, 도구 출력은 공유 창의 컨텍스트를 소비합니다(표준 200K 토큰⁹¹, Opus 4.6 또는 확장 컨텍스트 모델 사용 시 1M 토큰). 컨텍스트가 가득 차면 Claude은 이전 결정을 놓치기 시작하고 품질이 저하됩니다. 이 계층은 토큰당 비용이 발생합니다.

Delegation Layer: Subagents는 깨끗한 컨텍스트로 시작해 집중된 작업을 수행하고 요약을 반환합니다. 탐색 결과가 기본 대화를 비대하게 만들지 않으며, 결론만 돌아옵니다. 탐색에는 더 저렴한 모델 티어로 subagents를 라우팅하거나, 비용보다 품질이 더 중요하다면 기본 모델을 계속 사용할 수 있습니다.

Extension Layer: MCP는 외부 서비스(데이터베이스, GitHub, Sentry)를 연결합니다. Hooks는 모델 동작과 관계없이 shell 명령 실행을 보장합니다. Skills는 Claude이 자동으로 적용하는 도메인 전문 지식을 인코딩합니다. Plugins는 이 모든 것을 배포 가능한 형태로 패키징합니다.

핵심 통찰: 대부분의 사용자는 Core Layer 안에서만 작업하며 컨텍스트가 비대해지고 비용이 올라가는 것을 지켜봅니다. 숙련된 사용자는 탐색과 전문 작업을 Delegation Layer로 넘기고, Extension Layer를 자신의 workflow에 맞게 설정해 두며, Core Layer는 오케스트레이션과 최종 결정에만 사용합니다.

목차

1. Claude Code은 어떻게 설치하나요?
2. 빠른 시작: 첫 세션
3. 핵심 상호작용 모드
4. 설정 시스템 심층 분석
5. 어떤 모델을 선택해야 하나요?
6. Claude Code 비용은 얼마인가요?
7. 의사결정 프레임워크
8. 권한 시스템은 어떻게 작동하나요?
9. Hooks는 어떻게 작동하나요?
10. MCP(Model Context Protocol)이란 무엇인가요?
11. Subagents란 무엇인가요?
12. Extended Thinking Mode란 무엇인가요?
13. 출력 스타일
14. Slash Commands
15. Skills는 어떻게 작동하나요?
16. Plugin System
17. 메모리는 어떻게 작동하나요?
18. 이미지 및 멀티모달 입력
19. Voice Mode
20. Git 통합은 어떻게 작동하나요?
21. 내 IDE에서 Claude Code을 어떻게 사용하나요?
22. 고급 사용 패턴
23. Remote & Background Agents [RESEARCH PREVIEW]
24. Chrome의 Claude
25. Slack의 Claude Code [RESEARCH PREVIEW]
26. 웹의 Claude Code [RESEARCH PREVIEW]
27. 성능 최적화
28. 문제는 어떻게 디버그하나요?
29. 엔터프라이즈 배포
30. 키보드 단축키 참조
31. 모범 사례
32. Workflow Recipes
33. Migration Guide
34. 대상별 가이드
35. 빠른 참조 카드
36. Changelog
37. References

Claude Code는 어떻게 설치하나요?

시스템 요구 사항

Claude Code는 macOS 13+, Ubuntu 20.04+/Debian 10+, Windows 10+(네이티브 또는 WSL)에서 실행됩니다. 시스템에는 최소 4GB RAM과 활성 인터넷 연결이 필요합니다.⁹² Shell 호환성은 Bash, Zsh 또는 Fish에서 가장 잘 작동합니다.

Windows의 경우 WSL 1과 WSL 2 모두 작동합니다. 네이티브 Windows를 선호한다면 Git Bash도 작동합니다. Alpine Linux 및 기타 musl 기반 시스템은 추가 패키지가 필요합니다:

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

플랫폼 지원 매트릭스

설치, 업데이트, 제거 한눈에 보기

스캔 가능한 조회 — 모든 방법, 모든 명령어, 버전 확인을 한 화면에서. 아래 하위 섹션에서는 각 방법별 세부 사항과 문제 해결을 다룹니다.

v2.1.113부터 정식 CLI는 번들된 JavaScript 대신 플랫폼별 옵션 의존성을 통해 네이티브 Claude Code 바이너리를 생성합니다 — 테스트된 배포판에서는 네이티브 설치 프로그램을 사용하세요. npm 경로는 여전히 작동하지만 v2.1.15에서 처음 추가된 사용 중단 안내가 표시됩니다.

설치 방법

네이티브 설치(권장)

네이티브 바이너리는 Node.js 의존성 없이 가장 깔끔한 환경을 제공합니다:

# macOS and Linux
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew alternative
brew install --cask claude-code

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

특정 버전 설치:

# Install specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

# Install latest explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Windows PowerShell - specific version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

NPM 설치(사용 중단)

참고: v2.1.15부터 npm 설치 시 사용 중단 안내가 표시됩니다. 네이티브 바이너리가 이제 권장 설치 방법입니다. claude install로 마이그레이션하세요.

npm이 여전히 필요한 레거시 환경의 경우:

npm install -g @anthropic-ai/claude-code

npm 설치 시 절대 sudo를 사용하지 마세요. 이후 모든 작업을 복잡하게 만드는 권한 문제가 발생합니다.

기존 설치에서 마이그레이션

이전 npm 기반 설치가 있다면 네이티브 바이너리로 마이그레이션하세요:

claude install

인증 옵션

Claude Code는 각각 다른 트레이드오프를 가진 세 가지 인증 경로를 지원합니다:

Claude Console(API 청구)

platform.claude.com(이전의 console.anthropic.com)을 통해 Anthropic의 API에 직접 연결합니다. 계정을 만들고, 청구를 설정한 후 CLI를 통해 인증합니다. Console은 전체 API 액세스가 포함된 사용량 기반 청구를 제공합니다. 전용 “Claude Code” 워크스페이스가 자동으로 생성되며, 이 워크스페이스용 API 키를 만들 수는 없지만 사용량을 모니터링할 수 있습니다.

Claude Pro 또는 Max 구독

claude.ai 계정 자격 증명을 사용합니다. 구독은 단일 월간 요금제로 웹 인터페이스와 CLI 사용을 모두 포함합니다. 이 구독은 예측 가능한 비용을 원하는 개인 사용자에게 청구를 단순화합니다.

엔터프라이즈 플랫폼

AWS Bedrock, Google Vertex AI, Microsoft Foundry는 각각 기존 클라우드 청구 관계를 통해 엔터프라이즈급 액세스를 제공합니다. Bedrock 설정 마법사(v2.1.92+): 로그인 화면의 대화형 마법사가 AWS 인증, 리전 선택, 자격 증명 확인, 모델 고정 과정을 안내합니다.¹³⁷ Vertex AI 설정 마법사(v2.1.98+): Google Cloud용 매칭 마법사로 GCP 인증, 프로젝트 및 리전 구성, 자격 증명 확인, 모델 고정을 안내합니다.¹⁴² Vertex AI mTLS Workload Identity Federation(v2.1.121+): Vertex AI는 이제 X.509 인증서 기반 Workload Identity Federation(mTLS Application Default Credentials)을 허용합니다 — 클라이언트 인증서로부터 발행되는 단기 GCP 토큰이며 서비스 계정 JSON가 필요하지 않습니다.¹⁵⁴ OS CA 인증서 신뢰(v2.1.101+): 엔터프라이즈 TLS 프록시가 이제 기본적으로 작동합니다 — Claude Code는 OS 인증서 저장소를 신뢰합니다. 번들된 CA만 사용하려면 CLAUDE_CODE_CERT_STORE=bundled로 설정하세요.¹⁴³

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-profile

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project

# Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
# Optional: API key auth (otherwise uses Entra ID)
export ANTHROPIC_FOUNDRY_API_KEY=your-key

# Amazon Bedrock via Mantle (v2.1.94+)
export CLAUDE_CODE_USE_MANTLE=1

프록시 뒤에 있거나 LLM 게이트웨이를 통한 엔터프라이즈 배포의 경우:

# Corporate proxy
export HTTPS_PROXY='https://proxy.example.com:8080'

# LLM gateway (skip native auth)
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

검증

claude doctor

이 명령은 설치 유형, 버전, 시스템 구성 및 감지된 모든 문제를 보고합니다.

인증 관리(v2.1.41+)

REPL에 들어가지 않고 인증을 관리합니다:⁹⁰

claude auth login          # Log in or switch accounts
claude auth status         # Check current auth state (account, plan, expiry)
claude auth logout         # Clear stored credentials

계정 또는 조직 간 전환을 위한 일반적인 워크플로우:

claude auth logout && claude auth login

다음도 참조하세요: 인증 실패 문제 해결을 위한 문제 디버깅은 어떻게 하나요?

업데이트

Claude Code는 기본적으로 자동 업데이트되며, 시작 시 그리고 세션 중에 주기적으로 확인합니다. 업데이트는 백그라운드에서 다운로드되어 다음 실행 시 적용됩니다.

자동 업데이트 비활성화:

export DISABLE_AUTOUPDATER=1

또는 settings.json에서:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

수동 업데이트:

claude update

제거

네이티브 설치(macOS/Linux/WSL):

rm -f ~/.local/bin/claude
rm -rf ~/.claude-code

네이티브 설치(Windows PowerShell):

Remove-Item -Path "$env:LOCALAPPDATA\Programs\claude-code" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\Microsoft\WindowsApps\claude.exe" -Force

구성 정리(모든 설정 제거):

rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json

빠른 시작: 첫 번째 세션

1. 설치 및 실행:

claude                           # Launch in current directory

2. 프로젝트로 이동:

cd ~/my-project && claude        # Or launch from any git repo

3. Claude에게 작업 요청하기:

> "Explain the architecture of this project"
> "Find all TODO comments and create a summary"
> "Add input validation to the signup form"

4. 세션 중에 핵심 단축키 사용하기:

/cost                            # Check token usage and cost
/compact                         # Free up context when it gets large
Alt+T                            # Toggle extended thinking for hard problems
Ctrl+C                           # Cancel current response

5. 나중에 계속하기:

claude -c                        # Resume your most recent session
claude --resume                  # Pick from session list

전문가 팁: 프로젝트 루트에 빌드 명령어, 코딩 규칙, 아키텍처 노트를 담은 CLAUDE.md 파일을 만드세요. Claude는 매 세션마다 이 파일을 읽습니다. 품질 향상을 위해 할 수 있는 가장 효과적인 한 가지 작업입니다.

핵심 상호작용 모드

대화형 REPL

인수 없이 Claude Code를 실행하면 대화형 read-eval-print 루프로 진입합니다:

cd your-project
claude

REPL은 여러 차례에 걸쳐 대화 컨텍스트를 유지합니다. 쿼리를 직접 입력하고 응답을 받으며, /exit 또는 Ctrl+D로 종료할 때까지 계속 진행할 수 있습니다.

세션의 초점을 맞추기 위해 초기 프롬프트로 시작하세요:

claude "explain the authentication flow in this project"

전문가 팁: REPL은 압축(compaction) 이벤트가 발생해도 상태를 유지합니다. 컨텍스트가 너무 커지면 Claude는 핵심 결정 사항과 코드 스니펫을 보존하면서 이전 대화를 자동으로 요약합니다. /compact로 수동 트리거하거나 보존할 내용에 대한 사용자 정의 지침을 추가할 수도 있습니다.

비대화형 모드

Print 모드(-p)는 단일 쿼리를 실행하고 종료합니다:

# Direct query
claude -p "list all TODO comments in this project"

# Process piped input
cat error.log | claude -p "identify the root cause of these failures"

# Chain with other tools
claude -p "generate a README" > README.md

스크립트에서 파싱하기에 적합한 구조화된 출력을 위해:

claude -p "count lines by file type" --output-format json

JSON 출력에는 자동화에 필요한 모든 정보가 포함됩니다:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.0034,
  "is_error": false,
  "duration_ms": 2847,
  "duration_api_ms": 1923,
  "num_turns": 4,
  "result": "Response text here...",
  "session_id": "abc-123-def"
}

스트리밍 출력의 실시간 처리를 위해:

claude -p "build the application" --output-format stream-json | while read line; do
  echo "$line" | jq -r 'select(.result) | .result'
done

출력 형식 옵션:

종료 코드:

-p 모드에서 에이전트 동작 제어하기:

# Limit autonomous turns (prevents runaway loops)
claude -p "refactor the auth module" --max-turns 10

# Allow specific tools without prompting
claude -p "fix lint errors" --allowedTools "Edit,Bash(npm run lint)"

# Use with a specific model
claude -p "explain this code" --model claude-sonnet-4-5-20250929

# Bare mode: skip hooks, LSP, plugin sync, skill walks (v2.1.81+)
claude -p "count files" --bare

# Channel permission relay: send approval prompts to Telegram/Discord (v2.1.81+)
claude --channels

CI/CD 통합 패턴:

# In a GitHub Action or CI pipeline
result=$(claude -p "review this diff for security issues" --output-format json 2>/dev/null)
is_error=$(echo "$result" | jq -r '.is_error')
if [ "$is_error" = "true" ]; then
  echo "Review failed"
  exit 1
fi
echo "$result" | jq -r '.result'

세션 관리

세션은 연속성을 위해 대화 기록을 유지합니다. 복잡한 다중 세션 작업에는 세션 지속성이 필수적입니다:

# Continue most recent session
claude -c

# Continue with additional prompt
claude -c -p "now add error handling"

# Resume specific session by ID
claude -r "abc123" "implement the remaining tests"

# Fork a session for parallel exploration
claude -r "base-session" --fork-session "try a different approach"

PR 연결 세션 (v2.1.27+, v2.1.119+에서 확장): 특정 풀 또는 머지 요청에 연결된 세션을 시작하세요. v2.1.119부터 --from-pr은 github.com 외에도 GitLab MR, Bitbucket PR, GitHub Enterprise PR URL을 지원합니다:⁷⁴¹⁵²

claude --from-pr 123                                                # GitHub PR number (assumes current repo's remote)
claude --from-pr https://github.com/org/repo/pull/123               # GitHub URL
claude --from-pr https://gitlab.com/org/repo/-/merge_requests/45    # GitLab MR (v2.1.119+)
claude --from-pr https://bitbucket.org/org/repo/pull-requests/67    # Bitbucket PR (v2.1.119+)
claude --from-pr https://ghe.example.com/org/repo/pull/89           # GitHub Enterprise (v2.1.119+)

세션 중에 gh pr create로 PR을 생성하면 세션이 자동으로 PR에 연결됩니다. 이를 통해 나중에 특정 PR 작업을 쉽게 재개할 수 있습니다. 푸터의 PR 배지는 prUrlTemplate 설정(v2.1.119+)을 통해 사용자 정의 코드 리뷰 URL을 가리킬 수 있습니다. 팀이 PR에서 별도의 리뷰 도구로 연결하는 경우 유용합니다.¹⁵²

/resume은 PR URL을 지원합니다 (v2.1.122+). 이제 /resume 검색 상자에 PR URL을 붙여넣으면 해당 PR을 처음 생성한 세션을 찾을 수 있습니다. github.com, GitHub Enterprise, gitlab.com (및 자체 호스팅 GitLab), bitbucket.org에서 모두 작동합니다.¹⁵⁴

이름이 지정된 세션: 시작 시 또는 세션 중에 세션 이름을 지정하세요:

# Name session at startup (v2.1.76+)
claude -n "auth-refactor"                  # --name flag sets display name[^125]

# Name current session
> /rename auth-refactor

# Resume by name or number
> /resume 1                    # Resume first session
> /resume auth-refactor        # Resume by name
claude --resume auth-refactor  # Resume from terminal
claude -r 3                    # Resume by number from terminal

# Fork for parallel exploration
claude --resume auth-refactor --fork-session

참고: --session-id는 유효한 UUID(예: 550e8400-e29b-41d4-a716-446655440000)를 요구합니다. 사람이 읽을 수 있는 세션 이름 지정에는 /rename과 --resume을 사용하세요.

Claude Code는 세션을 JSONL 트랜스크립트로 저장합니다. 에이전트 실행 시 고유한 agentId 값이 할당되며 트랜스크립트는 agent-{agentId}.jsonl로 저장됩니다. 재개 시 이전 대화의 전체 컨텍스트가 보존됩니다.

Plan 모드

Plan 모드는 Claude를 읽기 전용 탐색으로 제한합니다. 파일 편집, bash 실행, 파괴적 작업이 모두 차단됩니다. Claude는 구현 방식을 설계하고 이를 plan 파일에 기록한 뒤, 어떤 작업을 실행하기 전에 사용자의 승인을 기다립니다.

Plan 모드 진입:

# Cycle through modes during a session
Shift+Tab           # Cycles: normal → plan → auto-accept

# Or use the /plan command with an optional description (v2.1.72+)
/plan                                     # Enter plan mode
/plan refactor the auth module            # Enter plan mode with a description

# Or ask Claude directly
"Plan how to refactor the auth module"   # Claude may enter plan mode automatically

작동 방식:

1. Claude가 plan 모드에 진입합니다 (복잡한 작업의 경우 자동으로, 또는 Shift+Tab을 통해)
2. 읽기 전용 도구를 사용하여 코드베이스를 탐색합니다: Read, Glob, Grep, WebSearch, WebFetch
3. .claude/plans/{session-slug}.md에 plan을 작성합니다
4. ExitPlanMode로 plan 모드를 종료하고 검토를 위해 plan을 제시합니다
5. 사용자가 승인, 변경 요청 또는 거부합니다

Plan 모드에서 사용 가능한 도구: Read, Glob, Grep, LS, WebSearch, WebFetch, AskUserQuestion. 편집 도구(Edit, Write, Bash, NotebookEdit)는 차단됩니다.

Plan 승인 후 (v2.1.32+): Claude는 세 가지 옵션을 제공합니다: - “Yes, clear context and auto-accept edits” (Shift+Tab) — plan을 위한 전체 컨텍스트로 새로 시작 - “Yes, and manually approve edits” — 컨텍스트 보존, 각 변경사항을 수동으로 승인 - “Yes, auto-accept edits” — 컨텍스트 보존, Claude가 편집별 승인 없이 실행

승인 시 컨텍스트 자동 정리가 권장되는 워크플로입니다. plan에 새로운 컨텍스트 창을 제공하므로 plan 준수도가 크게 향상됩니다. 이전 대화의 간섭 없이 Claude가 더 오랫동안 궤도를 유지합니다.

Plan 모드를 사용해야 하는 경우: - 아키텍처 결정이 필요한 새로운 기능 구현 - 접근 방식을 먼저 검토하고 싶은 다중 파일 리팩토링 - 수정 전에 탐색이 선행되어야 하는 익숙하지 않은 코드베이스 - 여러 가지 유효한 접근 방식이 존재하고 사용자의 의견을 받고 싶은 모든 작업

전문가 팁: Plan 모드에서 시간을 더 많이 보낼수록 Claude가 구현에 성공할 가능성이 높아집니다. Plan 모드는 사실상 비용 없는 탐색입니다. 위험한 도구 호출도, 낭비되는 편집도 없습니다. 적극적으로 활용하세요.

Configuration System 심층 분석

Claude Code은 계층형 설정 시스템을 사용합니다. 상위 수준이 하위 수준을 덮어쓰며, enterprise 설정은 전혀 우회할 수 없기 때문에 이 계층 구조를 이해하는 것이 중요합니다.

설정 계층 구조

전문가 팁: 공유 project에서 개인 환경 설정은 .claude/settings.local.json을 사용하세요(.gitignore에 추가하세요). version control에 체크인되는 팀 전체 설정에는 .claude/settings.json을 사용하세요.

전체 settings.json Reference

주요 옵션을 모두 보여주는 전체 설정 예시입니다.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-5-20250929",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)",
      "Bash(make:*)",
      "Edit(src/**)",
      "Write(src/**)",
      "mcp__github"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(package-lock.json)",
      "Edit(.git/**)"
    ],
    "ask": [
      "WebFetch",
      "Bash(curl:*)",
      "Bash(docker:*)"
    ],
    "additionalDirectories": [
      "../shared-lib",
      "../docs"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory",
  "language": "en",
  "respectGitignore": true,
  "showTurnDuration": true,
  "plansDirectory": ".claude/plans",
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"],
  "spinnerTipsOverride": {
    "tips": ["Custom tip 1", "Custom tip 2"],
    "excludeDefault": true
  },
  "skillOverrides": {
    "legacy-skill": "off",
    "manual-only-skill": "user-invocable-only",
    "compact-skill": "name-only"
  },
  "includeGitInstructions": false,
  "modelOverrides": {
    "bedrock": "us.anthropic.claude-opus-4-6-20260312-v1:0",
    "vertex": "claude-opus-4-6@20260312",
    "foundry": "anthropic.claude-opus-4-6"
  },
  "autoMemoryDirectory": ".claude/memory",
  "sandbox": {
    "enableWeakerNetworkIsolation": true
  }
}

skillOverrides는 팀에 큰 skill library가 있지만 runtime 노출 범위를 더 엄격하게 관리하고 싶을 때 유용합니다. off를 사용하면 model과 slash picker 모두에서 skill을 숨길 수 있고, user-invocable-only를 사용하면 model 선택에서는 제거하되 이름으로 호출할 수 있게 유지할 수 있으며, name-only를 사용하면 전체 설명 없이 skill 이름만 표시할 수 있습니다.¹⁵⁶

새로운 설정(v2.1.174–176):

• availableModels / enforceAvailableModels (managed, v2.1.175+): availableModels allowlist는 session에서 선택할 수 있는 model을 제한합니다. enforceAvailableModels: true를 설정하면 allowlist가 Default model에도 적용됩니다. 허용되지 않은 model로 해석되는 Default는 첫 번째 허용 model로 fallback되며, 사용자/project 설정으로 managed availableModels 목록을 더 넓힐 수 없습니다. 관련 수정(v2.1.176)으로 alias 선택이 ANTHROPIC_DEFAULT_*_MODEL을 통해 차단된 model로 redirect될 수 있던 빈틈도 닫혔고, 이제 /fast는 allowlist 밖의 model로 전환하려는 toggle을 거부합니다.¹⁷²
• language (v2.1.176 개선): 응답 언어 설정에 더해, 이제 session 제목도 기본적으로 대화 언어로 생성됩니다. 제목에 특정 언어를 고정하려면 language를 설정하세요.¹⁷²
• footerLinksRegexes (v2.1.176): footer row의 regex 일치 link badge이며, 사용자 또는 managed 설정으로 구성할 수 있습니다.¹⁷²
• wheelScrollAccelerationEnabled (v2.1.174): fullscreen mode에서 mouse-wheel scroll acceleration을 비활성화하려면 false로 설정하세요.¹⁷²

Environment Variables Reference

Authentication 및 API:

ANTHROPIC_API_KEY=sk-ant-...                    # Direct API authentication
ANTHROPIC_AUTH_TOKEN=token                      # Custom authorization header
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Additional request headers

Model 설정:

ANTHROPIC_MODEL=claude-opus-4-7                 # Override default model (Apr 16, 2026)
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7    # Opus 4.7 (Max/Team Premium default)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Model for subagents
CLAUDE_CODE_WORKFLOWS=1                         # Enable Workflow tool for deterministic multi-agent orchestration (v2.1.147+)
MAX_THINKING_TOKENS=10000                       # (Opus 4.6 and Sonnet 4.6 only — removed in Opus 4.7)
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # Limit output length
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1          # Enable agent teams (v2.1.32+)

Cloud provider 설정:

CLAUDE_CODE_USE_BEDROCK=1                       # Use AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1                        # Use Google Vertex AI
CLAUDE_CODE_USE_FOUNDRY=1                       # Use Microsoft Foundry
ANTHROPIC_BEDROCK_BASE_URL=https://...          # Custom Bedrock endpoint
ANTHROPIC_BEDROCK_SERVICE_TIER=priority         # Bedrock service tier (v2.1.122+): 'default', 'flex', or 'priority'; sent as X-Amzn-Bedrock-Service-Tier header[^162]
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # Skip Bedrock auth (for gateways)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # Skip Vertex auth
AWS_BEARER_TOKEN_BEDROCK=token                  # Bedrock bearer token
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # Override Vertex region
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1    # Opt in gateway /v1/models discovery for /model picker (v2.1.129+)[^164]

동작 제어:

DISABLE_AUTOUPDATER=1                           # Prevent automatic background updates
DISABLE_UPDATES=1                               # Block ALL update paths including manual `claude update` (v2.1.118+, stricter than DISABLE_AUTOUPDATER)[^160]
CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1       # Homebrew/WinGet installs run package-manager upgrade in background, then prompt restart (v2.1.129+)[^164]
DISABLE_TELEMETRY=1                             # Opt out of usage telemetry
DISABLE_ERROR_REPORTING=1                       # Disable Sentry
DISABLE_BUG_COMMAND=1                           # Disable /bug command
DISABLE_COST_WARNINGS=1                         # Hide cost warnings
DISABLE_PROMPT_CACHING=1                        # Disable prompt caching globally
DISABLE_PROMPT_CACHING_SONNET=1                 # Disable for Sonnet only
DISABLE_PROMPT_CACHING_OPUS=1                   # Disable for Opus only
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # Skip non-critical API calls
ENABLE_PROMPT_CACHING_1H=1                      # Opt into 1-hour prompt cache TTL (v2.1.108+, API/Bedrock/Vertex/Foundry)
ENABLE_PROMPT_CACHING_1H_BEDROCK=1              # Deprecated alias for the above; v2.1.108+ still honors it on Bedrock but logs a deprecation notice
FORCE_PROMPT_CACHING_5M=1                       # Force 5-minute cache TTL (v2.1.108+)
ENABLE_TOOL_SEARCH=true                         # Re-enable tool search on Vertex AI (disabled by default v2.1.119+ to avoid unsupported beta header). Valid values: true, false, auto, auto:N[^160]
CLAUDE_CODE_HIDE_CWD=1                          # Hide the working directory in the startup logo (v2.1.119+)[^160]
CLAUDE_CODE_FORK_SUBAGENT=1                     # Enable forked subagents on external builds (v2.1.117+)[^160]
CLAUDE_CODE_FORCE_SYNC_OUTPUT=1                 # Force synchronized terminal output when auto-detection misses it, such as Emacs eat (v2.1.129+)[^164]
CLAUDE_CODE_SESSION_ID=...                      # Read-only: present in the Bash tool subprocess; matches the session_id passed to hooks (v2.1.132+)[^168]
CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1          # Skip the fullscreen alternate-screen renderer; keep the conversation in the terminal's native scrollback (v2.1.132+)[^168]
CLAUDE_EFFORT=...                               # Read-only: current effort level inside hooks and Bash tool subprocess (v2.1.133+)[^169]

Tool 설정:

BASH_DEFAULT_TIMEOUT_MS=30000                   # Bash command timeout (30s)
BASH_MAX_TIMEOUT_MS=600000                      # Maximum bash timeout (10min)
BASH_MAX_OUTPUT_LENGTH=50000                    # Bash output limit
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # Reset CWD after each bash
MCP_TIMEOUT=5000                                # MCP server startup timeout
MCP_TOOL_TIMEOUT=30000                          # MCP tool execution timeout
MAX_MCP_OUTPUT_TOKENS=25000                     # MCP output limit
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Slash command context limit

Network 및 proxy:

HTTP_PROXY=http://proxy:8080                    # HTTP proxy
HTTPS_PROXY=https://proxy:8080                  # HTTPS proxy
NO_PROXY=localhost,example.com                  # Bypass proxy for domains
CLAUDE_CODE_CLIENT_CERT=/path/to/cert           # mTLS certificate
CLAUDE_CODE_CLIENT_KEY=/path/to/key             # mTLS private key
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE=pass          # mTLS passphrase

UI 및 terminal:

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Don't update terminal title
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Skip IDE extension install
CLAUDE_CODE_SHELL=/bin/zsh                      # Override shell detection
USE_BUILTIN_RIPGREP=1                           # Use included ripgrep (default)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Custom config directory
IS_DEMO=1                                       # Hide sensitive UI elements[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Disable background tasks and Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # Override temp directory[^50]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Disable 1M context window (use standard 200K)[^103]
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000       # Plugin marketplace git timeout (default 120s, was 30s)[^105]
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1        # Remove built-in commit/PR instructions[^117]
CLAUDE_CODE_DISABLE_CRON=1                    # Stop scheduled cron jobs mid-session[^121]
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=30000 # SessionEnd hooks timeout (default varies)[^123]
CLAUDE_CODE_USE_POWERSHELL_TOOL=1             # Enable Windows PowerShell tool on Linux/macOS (requires pwsh on PATH; v2.1.111+)[^153]
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1             # Force Session Recap when telemetry disabled (v2.1.108+)[^153]
OTEL_LOG_RAW_API_BODIES=1                     # Emit full API request/response bodies as OTel log events (v2.1.111+)[^153]
TRACEPARENT=00-...                            # W3C Trace Context parent (v2.1.110+, SDK/headless)[^153]
TRACESTATE=vendor=value                       # W3C Trace Context state (v2.1.110+, SDK/headless)[^153]

OpenTelemetry exporters + 민감한 field gating:¹⁸¹

OTEL_LOGS_EXPORTER=none                       # OTel logs exporter (supports 'none' for disable; v2.1.85 fixed crash)
OTEL_METRICS_EXPORTER=none                    # OTel metrics exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_TRACES_EXPORTER=none                     # OTel traces exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_LOG_TOOL_CONTENT=1                       # Opt in to emitting tool content in OTel spans (v2.1.101+, sensitive by default)
OTEL_LOG_TOOL_DETAILS=1                       # Opt in to tool_parameters in OTel tool_result events (v2.1.85+)
OTEL_LOG_USER_PROMPTS=1                       # Opt in to emitting user prompts in OTel traces (v2.1.101+, sensitive by default)
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1    # Disable release-notes fetch (v2.0.17+); v2.1.110 also stopped the auto-title Haiku request in headless/SDK when set

v2.1.121+ LLM-request span attributes: 이제 stop_reason, gen_ai.response.finish_reasons, user_system_prompt가 LLM-request span에 emit됩니다. user_system_prompt는 PII를 포함할 수 있으므로 OTEL_LOG_USER_PROMPTS=1 뒤에서 gating됩니다.¹⁵⁴

v2.1.122+ event 수준 변경: api_request와 api_error log event의 숫자 attributes가 이제 숫자로 emit됩니다(이전에는 문자열). schema를 strict type으로 처리하던 downstream OTel collectors 문제가 수정됩니다. Claude Code이 @-mention을 resolve할 때 새 claude_code.at_mention log event가 발생합니다.¹⁵⁴

API / Model 제어:¹⁸¹

CLAUDE_CODE_EXTRA_BODY='{...}'                # Inject extra body fields into API calls; v2.1.113 fixed 400 errors with output_config.effort on Vertex/subagent calls
CLAUDE_CODE_MAX_CONTEXT_TOKENS=200000         # Override max context tokens (pre-existing var; v2.1.98 fixed handling of DISABLE_COMPACT when both are set)
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS=25000 # Override default token limit for file read operations (v2.1.0+)
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1   # Do not fall back to non-streaming API on streaming failures (v2.1.83+)
ANTHROPIC_BETAS=beta1,beta2                   # Enable beta API headers; v2.1.78 fixed silent ignore on Haiku models
ANTHROPIC_SMALL_FAST_MODEL=arn:...            # Fast model ID (Bedrock ARN supported; v0.2.125 stopped escaping slashes in ARN)

Plugins / MCP:¹⁸¹

CLAUDE_CODE_PLUGIN_CACHE_DIR=~/.claude/plugins # Plugin cache directory (v2.1.72 fixed literal '~' dir on some shells)
CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 # Preserve plugin marketplace cache when git pull fails (offline-friendly; v2.1.90+)
CLAUDE_CODE_MCP_SERVER_NAME=server1           # Passed to MCP headersHelper scripts so one helper can serve multiple servers (v2.1.85+)
CLAUDE_CODE_MCP_SERVER_URL=https://...        # Passed to MCP headersHelper scripts alongside the name (v2.1.85+)

Shell / IDE:¹⁸¹

CLAUDE_CODE_SHELL_PREFIX="time "              # Wrap every Claude-invoked shell command with a prefix (v1.0.61+)
CLAUDE_CODE_GIT_BASH_PATH=C:\Program\ Files\Git\bin\bash.exe  # Custom Git Bash path on Windows (v2.1.98+)
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY=60000       # SDK: exit after N ms idle (v2.0.35+)
CLAUDE_CODE_AUTO_CONNECT_IDE=false            # Disable IDE auto-connection (v1.0.61+)

Enterprise / auth:¹⁸¹

CLAUDE_CODE_PROXY_RESOLVES_HOSTS=1            # Opt into proxy-side DNS resolution (v2.0.55 moved this from default-on to opt-in)
CLAUDE_CODE_API_KEY_HELPER_TTL_MS=300000      # TTL for dynamically generated API keys via apiKeyHelper (apiKeyHelper refresh added v0.2.74 with 5-min default; env var added v0.2.117)

Skill variables (v2.1.69+):

${CLAUDE_SKILL_DIR}                            # Self-reference for skills to locate their own directory[^117]

SDK caller identity (v2.1.51+):

CLAUDE_CODE_ACCOUNT_UUID=uuid                  # Provide account UUID synchronously for SDK callers
CLAUDE_CODE_USER_EMAIL=[email protected]        # Provide user email for SDK callers
CLAUDE_CODE_ORGANIZATION_UUID=uuid             # Provide organization UUID for SDK callers

Debugging:

ANTHROPIC_LOG=debug                             # Enable API request logging

어떤 Model을 선택해야 하나요?

각 작업에 맞는 Model을 선택하면 비용과 품질 모두에 큰 영향을 줍니다. Claude Code은 여러 수준에서 유연한 Model 전환을 제공합니다.

사용 가능한 Model

Claude Fable 5(2026년 6월 9일): Opus 위의 새로운 Model tier입니다. Anthropic의 가장 강력하고 지능적인 Model이며, 테스트된 거의 모든 benchmark에서 최첨단 성능을 보이고, 수백만 token의 context에서도 일관성을 유지하도록 만들어졌습니다. Fable 5는 일반 사용에 맞게 안전하게 제공되는 “Mythos-class” frontier model입니다. cyber, bio-chem, model-distillation query에서는 Opus 4.8로 fallback하는 safety classifier가 함께 제공됩니다(Claude Mythos 5는 승인된 연구자를 위해 이러한 보호 장치를 해제한 동일 Model입니다). Fable 5는 v2.1.170(2026년 6월 9일)부터 Claude Code에서 선택할 수 있게 되었습니다. claude update를 실행한 뒤 /model fable을 사용하세요(short alias이며, /model claude-fable-5와 best alias도 이 Model을 선택합니다). subscription plan에는 2026년 6월 22일까지 순차적으로 배포됩니다. Model ID: claude-fable-5. Fable 5는 기본적으로 1M context window를 포함하므로 [1m] suffix가 필요 없습니다. 또한 v2.1.173(2026년 6월 11일)부터 claude-fable-5[1m] Model 이름은 자동으로 claude-fable-5로 정규화되어 suffix가 제거됩니다(이 suffix는 1M을 [1m] 뒤에 두는 Opus/Sonnet에서만 의미가 있었습니다). 최대 output은 128K입니다. 가격은 input $10/MTok, output $50/MTok으로 Opus 4.8의 약 2배이므로, 일상적인 edit가 아니라 정말 어려운 추론에만 사용하세요. request surface는 Opus 4.8과 같습니다(adaptive thinking만 지원, temperature/top_p/top_k와 budget_tokens 제거). 단 한 가지 차이가 있습니다. 명시적으로 thinking: {type: "disabled"}를 보내면 400을 반환하므로, thinking 없이 실행하려면 thinking parameter를 아예 생략하세요.¹⁷⁴

Claude Code에서만 보면 Fable 5는 Opus 4.8과 마찬가지로 전체 effort scale(low/medium/high/xhigh/max, 기본값은 high)을 지원합니다. Fable 5에서는 thinking을 끌 수 없습니다. session thinking toggle, alwaysThinkingEnabled 설정, MAX_THINKING_TOKENS=0은 모두 효과가 없습니다. 항상 adaptively reasoning합니다. 전체 fable 계열 config surface는 Opus knob을 그대로 반영합니다. ANTHROPIC_DEFAULT_FABLE_MODEL은 fable alias가 해석되는 Model을 고정하며(Bedrock/Vertex/Foundry에서 유용), DISABLE_PROMPT_CACHING_FABLE은 Fable을 prompt caching에서 제외하고, enterprise gateway에서는 content 기반 automatic fallback이 적용됩니다. Opus 4.8은 여전히 Claude Code의 agentic 기본값입니다(기본 high effort, 가장 어려운 작업에는 /effort xhigh). 절대적인 상한이 필요할 때만 /model fable로 Fable 5를 의도적으로 선택하세요.¹⁷⁴

Opus 4.7(2026년 4월 16일): 이전 세대 flagship이며, 여전히 완전히 사용할 수 있습니다. 1M token context window를 standard pricing으로 제공합니다. long-context premium은 없습니다. 128K max output, adaptive thinking만 지원(extended thinking 제거), coding과 agentic workload의 시작점으로 권장되는 새로운 xhigh effort level을 제공합니다.¹⁴⁵ 신뢰 가능한 knowledge cutoff: 2026년 1월. training data cutoff: 2026년 1월. Model ID: claude-opus-4-7. 가격은 Opus 4.6과 동일하게 MTok당 $5/$25이며, 5분 cache write는 $6.25, 1시간 cache write는 $10, cache read는 MTok당 $0.50입니다.¹⁴⁴ Opus 4.7은 SWE-Bench에서 Opus 4.6보다 production task를 3배 더 많이 해결하고, CursorBench에서 70%(4.6은 58%)를 기록하며, Anthropic의 93-task internal coding benchmark에서 resolution을 13% 높입니다.¹⁴⁴ 새로운 tokenizer를 사용하므로 같은 text에서도 token count가 대략 1×-1.35×가 될 수 있습니다. max_tokens 여유와 compaction trigger를 늘려두세요.¹⁴⁵ Vision은 1:1 pixel coordinate로 최대 2,576 px / 3.75 MP image를 지원합니다.¹⁴⁵

Opus 4.7 coding benchmark(2026년 4월):¹⁵¹

Opus 4.7은 널리 인용되는 GPT-5-Codex baseline보다 SWE-bench Verified에서 12.7 앞서고, GPT-5.4(57.7%)보다 SWE-bench Pro에서 6.6 앞섭니다. Terminal-Bench 2.0에서는 GPT-5.3-Codex가 여전히 GPT-5.4보다 약간 앞서며(77.3% vs 75.1%), 둘 다 Opus 4.7(69.4%)보다 높습니다. benchmark 선두는 계속 바뀝니다. 여러 분기 동안의 선택을 확정하기 전에 vendor page를 확인하세요.

Plan별 기본 Model(Claude Code):¹⁴⁷

Opus 4.7은 Claude Code v2.1.111 이상이 필요합니다. upgrade하려면 claude update를 실행하세요.¹⁴⁷ Bedrock, Vertex, Foundry는 기본적으로 opus alias가 아니라 명시적 전체 Model 이름이나 ANTHROPIC_DEFAULT_OPUS_MODEL pin을 통해 Opus 4.7을 노출합니다.¹⁴⁷

Opus 4.7의 Messages API breaking change(caller에게 보임):¹⁴⁵

• Extended thinking budget_tokens가 제거되었습니다. 대신 thinking: {type: "adaptive"}를 사용하세요. Adaptive thinking은 기본적으로 꺼져 있습니다. thinking field가 없는 request는 thinking 없이 실행됩니다.
• temperature, top_p, top_k를 기본값이 아닌 값으로 설정하면 HTTP 400을 반환합니다. 이 parameter는 생략하고 prompting으로 Model을 조정하세요.
• Thinking content는 기본적으로 response에서 생략됩니다. 보이는 reasoning을 복원하려면 thinking.display: "summarized"를 설정하세요(product가 thinking을 사용자에게 stream하는 경우 필요).

Task budget(beta header task-budgets-2026-03-13)을 사용하면 output_config.task_budget으로 전체 agentic loop에 걸친 token target을 Model에 알려줄 수 있습니다. 최소값은 20K token입니다.¹⁴⁵

Opus 4.6(legacy): claude-opus-4-6에서 1M context와 128K max output으로 여전히 사용할 수 있습니다. 더 나은 agentic coding을 위해 Opus 4.7로 migration하는 것을 고려하세요. Opus 4.6은 원래 2026년 2월 5일에 출시되었습니다.⁷⁹¹⁴⁴ v2.1.117(2026년 4월 22일)부터 Pro 및 Max subscriber는 Opus 4.6과 Sonnet 4.6에서 기본값이 high effort입니다(이전에는 medium). Opus 4.7은 xhigh를 유지합니다. 이 변경은 4월 23일 postmortem에 문서화된 3월 4일 → 4월 7일 effort downgrade 이후 intelligence를 복원한 것입니다.¹⁵²¹⁵³

Sonnet 4.6(2026년 2월 17일): 균형 잡힌 Model입니다. claude.ai와 Claude Cowork 전반에서 Sonnet 4.5를 기본값으로 대체했습니다.⁹³ 가격은 Sonnet 4.5와 동일합니다(MTok당 $3/$15). 더 적은 token을 사용하면서 agentic search 성능이 개선되었습니다. extended thinking, adaptive thinking, 1M token context window(beta)를 지원합니다. 64K max output(v2.1.77에서는 상한 128K).¹¹⁹ Knowledge cutoff: 2025년 8월(신뢰 가능), 2026년 1월(training data). Model ID: claude-sonnet-4-6.

Claude Mythos Preview(2026년 4월 7일): Project Glasswing에서 제공되는 defensive cybersecurity 작업용 research-preview frontier model입니다.¹³⁹ 초대 전용이며 일반적으로 사용할 수 없습니다. Anthropic은 Opus 4.7을 cyber 측면에서 Mythos보다 의도적으로 덜 capable하게 설계했다고 설명합니다. 이는 safety tradeoff입니다. 더 높은 access가 필요한 합법적인 security researcher를 위해 https://claude.com/form/cyber-use-case에서 Cyber Verification Program을 열었습니다.¹⁴⁶

이 가격 차이가 중요한 이유: 일반적인 coding session은 input token 50K-200K, output token 10K-50K를 소비합니다. Haiku를 사용하면 session당 $0.10-$0.45입니다. Opus를 사용하면 같은 session이 $0.50-$2.25로 5배 더 비쌉니다. Opus는 정말 어려운 문제에만 사용하세요.¹

각 Model을 사용할 때

Haiku: 탐색, 간단한 파일 검색, 빠른 질문을 수행하는 subagent에 사용하세요. Opus보다 약 5배 저렴하고 더 빠르게 응답합니다. 깊은 추론이 필요 없는 background task에 적합합니다.

Sonnet: 비용이 중요할 때 일상적인 개발에 쓰는 주력 Model입니다. feature 구현, bug 수정, test 작성, code review 등 대부분의 coding task를 처리합니다. Sonnet 4.6은 Sonnet 4.5보다 개선된 agentic search와 더 나은 token efficiency를 제공하며, adaptive thinking 지원과 1M context window를 standard pricing으로 제공합니다.⁹³ Opus 4.7(2026년 4월 16일) 기준으로 Claude Code은 Max와 Team Premium plan에서만 Opus를 기본값으로 사용합니다. Pro, Team Standard, Enterprise, API account는 Enterprise와 API이 2026년 4월 23일 Opus 4.7로 전환될 때까지 Sonnet 4.6을 기본값으로 유지합니다.¹⁴⁷ 더 저렴한 token, 더 빠른 latency, subagent economics가 필요할 때 Sonnet을 사용하세요.

Opus: 2026년 4월 16일 기준 flagship tier이며, Max와 Team Premium plan의 기본값입니다.¹⁴⁴¹⁴⁷ 높은 비용의 reasoning은 효과가 분명한 곳에만 사용하세요. architecture decision, 까다로운 debugging, 복잡한 system 이해, security analysis, 장기 agentic work가 여기에 해당합니다. Opus 4.7은 SWE-Bench에서 Opus 4.6보다 production task를 3배 더 많이 해결하고, CursorBench에서 70%(58% 대비)를 기록하며, 93-task internal coding benchmark에서 resolution을 13% 높입니다.¹⁴⁴ Claude Code은 Opus 4.7에서 기본적으로 xhigh effort를 사용하며, /effort로 조정할 수 있습니다(v2.1.111+).¹⁴⁶¹⁴⁷ Auto Mode는 Anthropic API를 통해 Max subscriber가 Opus 4.7에서 사용할 수 있으며 --enable-auto-mode가 필요 없습니다. 다른 plan/provider는 plan별 및 admin 제어 availability를 따릅니다.¹⁴⁶ 1M context는 standard pricing입니다. long-context premium은 없습니다. 알아둘 만한 behavior change: Opus 4.7은 instruction을 더 문자 그대로 따르고, task complexity에 맞춰 response length를 조절하며, 기본적으로 subagent를 더 적게 실행하고, validation 중심 표현이 줄어든 더 직접적인 tone을 사용합니다. prompt에 중간 progress message나 double-check behavior를 강제하는 scaffolding이 있다면 제거해 보세요.¹⁴⁵

Opusplan: planning에는 Opus를 사용하고(reasoning quality가 가장 중요한 곳), execution에는 Sonnet을 사용하는 hybrid mode입니다(speed가 중요한 곳). 최상의 plan은 원하지만 각 individual edit에 Opus 수준의 reasoning이 필요하지 않은 복잡한 refactoring에 매우 좋습니다.

Model 전환

Session 중:

> /model opus
> /model sonnet
> /model haiku

Startup에서:

claude --model opus

Environment로:

export ANTHROPIC_MODEL=opus

settings.json에서:

{
  "model": "claude-sonnet-4-5-20250929"
}

Subagent 전용:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

Fallback model chain(v2.1.166+): fallbackModel 설정은 primary Model이 overloaded되었거나 unavailable일 때 순서대로 시도할 최대 3개의 fallback Model을 구성합니다. --fallback-model flag(이전에는 mid-session switch 전용)도 이제 startup부터 interactive session에 적용됩니다.¹⁷⁶

{
  "model": "claude-opus-4-8",
  "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]
}

API가 예상치 못한 non-retryable error를 반환하면, Claude Code은 failure를 표시하기 전에 fallback Model에서 해당 turn을 한 번 더 retry합니다. 따라서 일시적인 primary-model 문제는 turn을 잃는 대신 graceful하게 degrade됩니다.¹⁷⁶

v2.1.178부터 compaction도 fallback chain을 따릅니다. primary Model이 compaction 중 overloaded되었거나 unavailable이면, compaction step은 turn을 fail시키는 대신 구성된 fallbackModel/--fallback-model chain으로 fallback합니다. 긴 autonomous run에서는 이 변경으로, 원래 복구 가능했던 compaction이 일시적인 Model error 때문에 session을 중단하던 gap을 닫을 수 있습니다.¹⁷³

Extended Context

대규모 codebase나 긴 session에서는 1M token context를 활성화하세요.

claude --model sonnet[1m]
claude --model opus[1m]           # Opus 4.7 with 1M context

또는 session 안에서:

> /model sonnet[1m]
> /model opus[1m]

Opus 4.7, Opus 4.6, Sonnet 4.6은 모두 full 1M token context window를 standard pricing으로 포함합니다. long-context premium은 없습니다.¹⁴⁸ 900K-token request는 9K-token request와 동일한 per-token rate로 과금됩니다. Prompt caching과 batch processing discount는 전체 context window에서 standard rate로 적용됩니다.

Max, Team, Enterprise subscription에서는 1M context가 있는 Opus가 자동으로 포함됩니다. [1m] suffix가 필요 없습니다(2026년 3월 13일 v2.1.75부터 기본 enabled).¹¹⁷¹⁴⁷ Pro에서는 extra usage를 통해 1M context에 접근할 수 있습니다. API 및 pay-as-you-go 사용자는 standard per-token rate로 full 1M access를 사용할 수 있습니다.¹⁴⁷

Model picker에서 1M context variant를 비활성화하려면 CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정하세요.

현재 Model 확인

> /status

이 command는 현재 Model, account info, 적용된 설정, 기타 session state를 보여줍니다.

Model picker label(v2.1.51+): 이제 /model picker는 pinned version에 대해 raw model ID 대신 사람이 읽기 쉬운 label(예: “Sonnet 4.6”)을 보여주며, 더 새로운 version이 있을 때 upgrade hint도 표시합니다.⁹⁸

Fast Mode(v2.1.36+)

Fast mode는 같은 Model에서 훨씬 빠른 output을 제공합니다. 더 저렴한 Model로 전환하지 않습니다. session 중 /fast로 toggle하세요.⁸⁶

> /fast            # Toggle fast mode on/off

Pricing(Opus 4.6 fast mode):

Fast mode는 research preview이며, Opus 4.6 전용이고, 기본 가격의 6×로 약 2.5× 더 빠른 output을 제공합니다.¹⁴⁹ /fast를 enable하면 다른 Model을 사용 중이었더라도 session이 자동으로 Opus 4.6으로 전환됩니다. /fast를 disable해도 /model로 전환하기 전까지는 Opus 4.6에 남아 있습니다. Fast mode는 Opus 4.7, Sonnet, Haiku, Bedrock/Vertex/Foundry에서는 사용할 수 없습니다. extra usage가 enabled되어 있어야 하며, Team/Enterprise에서는 admin enablement가 필요합니다.

Fast mode를 사용할 때: - latency가 bottleneck인 작은 변경을 빠르게 반복할 때 - speed가 cost보다 중요한 test, boilerplate, 반복 code 생성 - 비슷한 task 목록을 순차적으로 처리할 때

Fast mode를 사용하지 말아야 할 때: - 오래 실행되는 agentic task(6x rate에서는 비용이 빠르게 쌓입니다) - background subagent work(output을 기다리는 사람이 없습니다) - budget-conscious session

Opus 4.6 fast mode는 full 1M context window를 포함합니다(v2.1.50+). Fast mode pricing은 1M context 전체에서 flat합니다. 추가 long-context surcharge는 없습니다.⁹⁶¹⁴⁹

Expert tip: Fast mode는 opusplan과 함께 쓰는 조합이 아닙니다(opusplan은 이미 Opus와 Sonnet을 섞고, fast mode는 Opus 4.6에만 영향을 줍니다). latency가 cost보다 중요할 때 fast mode를 직접 사용하고, autonomous 또는 batch work에서는 disable하세요. /fast에는 extra usage가 필요합니다. Team/Enterprise admin이 먼저 enable해야 할 수 있습니다(v2.1.37 fix).⁸⁶¹⁴⁹

Effort Control(v2.1.111+, Opus 4.7)

Opus 4.7은 speed/intelligence tradeoff를 조정하는 새로운 effort dial을 도입합니다. session 중 /effort를 사용하세요.

> /effort              # opens an interactive slider (arrow keys + Enter)
> /effort xhigh        # set directly

Claude Code은 이제 Opus 4.7에서 기본적으로 xhigh effort를 사용합니다. xhigh는 Opus 4.7 전용입니다. 다른 Model은 high로 fallback합니다. Claude Managed Agents는 effort를 자동으로 처리합니다. effort parameter는 Messages API 개념입니다.¹⁴⁵¹⁴⁶

Max의 Auto Mode(v2.1.111+)

Auto Mode는 --dangerously-skip-permissions를 대체하는 더 안전한 기능입니다. Max subscriber는 Anthropic API를 통해 Opus 4.7에서 --enable-auto-mode 없이 사용할 수 있습니다.¹⁴⁶ Sonnet-4.6 classifier가 execution 전에 각 action을 review하여 intent match와 safety를 확인합니다. 참고(v2.1.111+): --enable-auto-mode flag는 제거되었습니다. Auto Mode로 session을 시작하려면 대신 --permission-mode auto를 사용하세요. Auto Mode는 Pro에서 사용할 수 없습니다. Anthropic의 permission modes docs에 따르면 Anthropic API에서는 기본적으로 직접 사용할 수 있습니다. Bedrock/Vertex/Foundry(v2.1.158+): 이제 해당 gateway의 Opus 4.7 및 Opus 4.8에서 CLAUDE_CODE_ENABLE_AUTO_MODE=1로 Auto Mode를 opt-in할 수 있습니다.¹⁷⁹

기본값을 잃지 않는 custom rule(v2.1.118+). 이전 version에서는 autoMode.allow, autoMode.soft_deny, autoMode.environment가 양자택일이었습니다. 직접 list를 정의하면 built-in safety rule을 잃었습니다. $defaults sentinel이 이를 해결합니다. 배치한 정확한 위치에서 built-in list로 inline expand되므로, 그 주변에 custom rule을 layer할 수 있습니다.¹⁵²

// .claude/settings.json
{
  "autoMode": {
    "allow": [
      "Bash(npm test:*)",        // your additions, prepended
      "$defaults",                // built-in allow list inserted here
      "Bash(git push:origin/feature/*)"  // appended after
    ]
  }
}

“Don’t ask again” opt-in(v2.1.118+). Auto Mode opt-in prompt는 이제 “Don’t ask again” option을 제공합니다. 자주 사용하는 사용자는 flag를 script하지 않고도 explainer를 숨길 수 있습니다.¹⁵²

v2.1.105-v2.1.114의 새로운 Command¹⁴⁶¹⁵⁰

Session Recap(v2.1.108+)

paused session으로 돌아왔을 때 context를 보여주는 새로운 session-level 기능입니다. 기본적으로 enabled이며, /config 또는 CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0으로 opt-out할 수 있습니다. Model은 Skill tool을 통해 built-in slash command(/init, /review, /security-review)도 호출할 수 있습니다. 이는 subagent/skill pattern을 확장합니다.¹⁴⁶

Push Notifications(v2.1.110+)

Remote Control이 “Push when Claude decides” enabled로 구성되어 있으면, Claude이 새 push-notification tool을 통해 자체 판단으로 mobile push notification을 보낼 수 있습니다. 기존 Remote Control mobile/web surface와 함께 작동합니다.¹⁴⁶ /context, /exit, /reload-plugins도 이제 Remote Control client에서 작동합니다.

Windows PowerShell Tool(v2.1.111+, rollout)

Claude Code은 native Windows PowerShell tool을 rollout하고 있습니다. Linux/macOS에서는 CLAUDE_CODE_USE_POWERSHELL_TOOL=1로 enable하세요(PATH에 pwsh가 필요). Windows에서는 같은 변수가 rollout 중 opt-in/opt-out을 제어합니다.¹⁴⁶

Permission-mode auto-approval(v2.1.119+). 이제 PowerShell tool command도 Bash command와 같은 방식으로 permission mode에서 auto-approval을 받을 수 있습니다. PowerShell(Get-*:*) 같은 allow rule과 기존 pattern syntax는 이제 read-only operation의 prompt를 우회하여, team이 Linux/macOS에서 이미 얻던 operator ergonomics와 맞춥니다.¹⁵²

Permission Reduction: Read-Only Bash(v2.1.111+)

glob argument가 있는 read-only Bash pattern(예: ls *.ts, cat src/*.md)과 cd <project-dir> &&로 시작하는 command는 더 이상 permission prompt를 trigger하지 않습니다.¹⁴⁶ /less-permission-prompts와 함께 사용하면 일상적인 workflow에서 interruption이 크게 줄어듭니다.

Distributed Tracing(v2.1.110+)

SDK 및 headless session은 이제 environment에서 TRACEPARENT와 TRACESTATE를 읽어 Claude Code run을 distributed trace에 연결합니다. debugging을 위해 전체 API request/response body를 OpenTelemetry log event로 내보내려면 OTEL_LOG_RAW_API_BODIES=1(v2.1.111+)과 함께 사용하세요.¹⁴⁶

Native Binary Distribution(v2.1.113+)¹⁵⁰

v2.1.113은 CLI launch 방식을 바꿉니다. 이제 claude는 bundled JavaScript를 실행하는 대신 platform별 optional dependency를 통해 native Claude Code binary를 spawn합니다. installation 및 update command는 그대로이며, team은 rollout script를 변경할 필요가 없습니다.

Prompt Editor Shortcuts(v2.1.113+)¹⁵⁰

Prompt editor는 multiline input에서 readline-style navigation과 fullscreen viewport scrolling을 지원합니다.

기본적으로 enabled되어 있습니다. keybinding config는 필요 없습니다.

Subagent Stall Timeout(v2.1.113+)¹⁵⁰

mid-stream에서 stall된 subagent는 이제 조용히 멈춰 있는 대신 10분 후 명확한 error로 fail합니다. streaming API에서 stuck process를 더 넓게 cover하려면 CLAUDE_STREAM_IDLE_TIMEOUT_MS(v2.1.84+)와 함께 사용하세요.

v2.1.114 Stability Fix¹⁵⁰

v2.1.114(2026년 4월 18일)는 단일 fix를 제공합니다. agent-teams teammate가 tool permission을 요청할 때 permission dialog가 crash할 수 있었습니다. Agent Teams를 사용한다면 upgrade하세요.

Claude Code의 비용은 얼마입니까?

지속 가능한 Claude Code 사용을 위해서는 비용을 이해하고 관리하는 것이 필수입니다. 모델 기능에 대해서는 모델 선택을, 작업별 적합한 모델 선택에 대해서는 의사 결정 프레임워크를 참고하세요.

비용 확인

> /cost

출력:

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    247 lines added, 89 lines removed

구독 사용자는 /cost에서 모델별 및 캐시 적중 분석을 확인할 수 있으며, 어떤 모델이 토큰을 소비했고 캐시에서 얼마나 제공되었는지 정확히 표시됩니다 (v2.1.92+).¹³⁷

구독 플랜

사용량 제한 (2025년 8월): Anthropic가 유료 구독자에게 주간 사용량 제한을 도입했습니다. Max 구독자는 표준 API 요금으로 사용량 제한을 초과하는 추가 사용량을 구매할 수 있습니다.¹⁴

사용량 제한 2배 인상 (2026년 5월 6일): Code with Claude SF 이벤트 기간 동안, Anthropic는 Pro, Max, Team 및 좌석 기반 Enterprise 플랜 전반에 걸쳐 Claude Code 5시간 사용량 제한을 2배로 인상했고, Pro 및 Max 계정의 피크 시간대 감축을 제거했으며, Claude Opus 모델의 API 사용량 제한을 “상당히” 상향 조정했습니다. 용량 백스톱은 SpaceX Colossus 1 거래입니다: “한 달 내에 300메가와트 이상의 신규 용량 (220,000개 이상의 NVIDIA GPU).”¹⁵⁷

API 토큰 가격 (2026년 4월)¹¹⁴⁴

API 청구 사용자의 100만 토큰당 가격:

1M 컨텍스트 가격 (2026년 4월): Opus 4.7, Opus 4.6, Sonnet 4.6 및 Mythos Preview 모두 표준 MTok당 요금으로 1M을 포함합니다 — 장문 컨텍스트 프리미엄이 없습니다.¹⁴⁸ 이는 최근의 통합으로, 200K 입력 토큰을 초과할 때 Opus 4.6이나 Sonnet 4.6이 입력 2배 / 출력 1.5배를 지불한다는 이전 안내는 더 이상 유효하지 않습니다. 레거시 Opus 4.5 및 그 이전 모델은 원래의 가격 구조를 유지합니다.

데이터 레지던시 가격: inference_geo를 통해 미국 전용 추론을 지정하면 캐시 읽기 및 쓰기를 포함한 모든 토큰 가격에 1.1배 승수가 추가됩니다 (Opus 4.6+ 모델).¹⁴⁸

프롬프트 캐싱은 반복 입력 비용을 크게 줄여줍니다: 캐시 쓰기는 기본 요금의 1.25배 (5분 캐시) 또는 2배 (1시간 캐시)이지만, 캐시 읽기는 단 0.1배로 90% 절감됩니다. 반복 컨텍스트가 있는 RAG 시스템 및 코드 어시스턴트의 경우, 캐싱으로 비용을 88-95% 줄일 수 있습니다.

배치 API는 야간 테스트 스위트와 같은 긴급하지 않은 작업에 24시간 처리 시간으로 50% 할인을 제공합니다.

다중 계정 정책⁵²

여러 개의 Claude 계정을 가질 수 있습니까? 네, 정당한 사용 사례라면 가능합니다. Anthropic는 별개의 목적을 수행하는 경우 다중 계정을 명시적으로 허용합니다.

허용되는 사례:

기술적 제한: - 동일한 전화번호로 최대 3개 계정 인증 가능 - 동일한 IP/네트워크의 다중 유료 구독은 명시적으로 지원됨 - 계정은 완전히 분리되어 있으며, 계정 간 채팅이나 프로젝트 전송은 불가능

금지되는 사례 (사용 정책 참조): - 차단 후 차단 회피를 위한 계정 생성 - 탐지 회피를 위한 계정 간 악의적 활동 조율 - 다중 계정을 사용한 사용량 제한 또는 무료 티어 크레딧 우회

실제 사례: 2026년 1월, 파워 유저 Jeffrey Emanuel (@doodlestein)은 22개의 Max 계정이 자동으로 플래그 처리되어 일시적으로 차단되었습니다. Anthropic 직원 Thariq (@trq212)이 정당한 사용을 확인한 후 4시간 이내에 해결했습니다. 업무와 개인 프로젝트 모두에 여러 계정으로 Claude Code를 광범위하게 사용하고 있다면, 이는 정확히 서비스가 설계된 용도이지만, 시스템을 악용하려고 시도해서는 안 됩니다.

의심스러울 때: Anthropic Support에 문의하여 특정 설정을 서면으로 확인하세요.

비용 요인

실제 비용 예시

비용 절감 인사이트: 탐색 서브에이전트에 Haiku를 사용하고 구현에 Sonnet을 사용하면 모든 작업에 Sonnet을 사용하는 경우에 비해 일반적으로 비용을 40-50% 절감할 수 있습니다.

팀 비용 관리

팀 규모별 권장 TPM/RPM:

숨겨진 도구 요금

토큰당 가격 외에도 일부 도구는 별도 요금이 부과됩니다:⁹

이는 에이전트 루프에서 누적됩니다. Bash를 사용한 100회 반복 디버그 사이클은 오버헤드만으로 약 24,500개의 추가 입력 토큰이 듭니다.

비용 절감 전략

1. 서브에이전트에 Haiku 사용: 대부분의 탐색에는 Sonnet이 필요하지 않습니다
2. 프롬프트 캐싱 활성화: 기본값이지만, 비활성화되지 않았는지 확인하세요
3. 최대 턴 설정: claude --max-turns 5로 폭주하는 대화를 방지합니다
4. 탐색에 plan 모드 사용: 실행 없음 = 우발적인 고비용 작업 없음
5. 선제적으로 압축: 컨텍스트가 작을수록 = 토큰이 적습니다
6. 출력 제한: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
7. 긴급하지 않은 작업에 배치 API: 입력과 출력 토큰 모두 50% 할인

사용량 모니터링

• Claude Console: platform.claude.com (Admin 또는 Billing 역할 필요)
• 워크스페이스 한도: 워크스페이스별 지출 한도 설정
• Bedrock/Vertex: 네이티브 클라우드 비용 모니터링 사용
• LiteLLM: 타사 제공자를 통한 사용자별 상세 추적용

백그라운드 토큰 사용량

일부 작업은 백그라운드에서 토큰을 소비합니다: - /resume을 위한 대화 요약 - /cost 및 /status 명령 - 자동 압축

일반적으로 세션당 $0.04 미만입니다.

Claude Code Analytics API (Team/Enterprise)⁴⁶

Admin API를 통해 조직의 Claude Code 사용량 분석 및 생산성 지표에 프로그래밍 방식으로 액세스하세요.

엔드포인트: GET /v1/organizations/usage_report/claude_code

요구 사항: - Admin API 키 (sk-ant-admin...) - Team 또는 Enterprise 플랜 - Admin, Billing 또는 Developer 역할

사용 가능한 지표:

요청 예시:

curl "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2026-01-15" \
  -H "x-api-key: sk-ant-admin..." \
  -H "anthropic-version: 2023-06-01"

사용 사례: - 개발자 생산성 분석 (세션, 커밋, PR) - 도구 사용량 지표 (Edit, Write 등의 수락/거부 비율) - 팀 간 비용 추적 및 할당 - AI 코딩 도구의 ROI 정당화

참고: 데이터는 활동 완료 후 1시간 이내에 표시됩니다. 일관성을 위해 응답에는 1시간 이상 경과한 데이터만 포함됩니다.

의사 결정 프레임워크

기능이 존재한다는 사실을 아는 것만으로는 충분하지 않습니다. 각 기능을 언제 사용해야 하는지 알아야 합니다. 이러한 의사 결정 트리는 지식을 실행으로 전환해 줍니다.

어떤 모델을 사용해야 할까요?

START → Is the task simple? (file search, quick question, formatting)
         │
         ├── YES → Use Haiku
         │         Cost: ~$0.03/task
         │         Speed: Fastest
         │
         └── NO → Does it require deep reasoning?
                  (architecture, complex debugging, security analysis)
                  │
                  ├── YES → Use Opus 4.7 (xhigh effort default)
                  │         Cost: ~$2.00/task
                  │         Quality: Highest (1M context at standard price, adaptive reasoning)
                  │
                  └── NO → Use Sonnet
                           Cost: ~$0.75/task
                           Balance: Best overall when cost matters

일반적인 기준: Opus 4.7은 Max 및 Team Premium의 기본값입니다. Pro/Team Standard/Enterprise/API에서는 Sonnet 4.6이 기본값입니다 (Enterprise + Anthropic API는 2026년 4월 23일에 Opus 4.7로 전환됩니다).¹⁴⁷ 서브에이전트의 경우 Haiku로 낮추세요. Sonnet의 답변이 얕게 느껴지면 Opus로 격상하세요. 에이전트 팀 (v2.1.32+)을 사용하면 Opus가 서로 다른 하위 작업에서 병렬로 작업하는 여러 에이전트를 조율할 수 있습니다.⁷⁹

Command, Skill, Subagent, Agent Team 중 무엇을 사용해야 할까요?

Do you want explicit control over when it runs?
│
├── YES → Use Slash Command
│         Example: /deploy, /test, /security-review
│         You invoke it. You control timing.
│
└── NO → Should the expertise apply automatically based on context?
         │
         ├── YES → Use Skill
         │         Example: Security patterns, domain rules, code standards
         │         Claude recognizes context and applies expertise.
         │
         └── NO → Does the work need isolated context?
                  │
                  ├── YES → Is there one subtask or many parallel subtasks?
                  │         │
                  │         ├── ONE → Use Subagent (Task tool)
                  │         │         Example: Deep exploration, parallel analysis
                  │         │         Prevents context bloat in main conversation.
                  │         │
                  │         └── MANY → Use Agent Team (v2.1.32+)
                  │                   Example: 5 agents reviewing different modules simultaneously
                  │                   Opus coordinates; each agent works independently.
                  │
                  └── NO → Just prompt directly
                           Not everything needs abstraction.

Hook 또는 Prompt?

Must the action ALWAYS happen, regardless of Claude's judgment?
│
├── YES → Use Hook (deterministic)
│         Examples:
│         - Format code after every edit
│         - Log all bash commands
│         - Block access to .env files
│         Claude cannot skip, forget, or decide otherwise.
│
└── NO → Use Prompt (probabilistic)
         Examples:
         - "Consider adding tests"
         - "Think about edge cases"
         - "Review for security if relevant"
         Claude decides based on context.

Extended Thinking은 언제 사용해야 할까요?

Is this a genuinely hard problem?
│
├── Architectural decision with many tradeoffs → YES, use thinking
├── Complex debugging with unclear root cause → YES, use thinking
├── Security analysis requiring careful reasoning → YES, use thinking
├── Understanding unfamiliar codebase → YES, use thinking
│
├── Routine bug fix → NO, skip thinking
├── Simple refactoring → NO, skip thinking
├── Code formatting → NO, skip thinking
└── Quick questions → NO, skip thinking

세션 중에 Alt+T로 전환할 수 있습니다. 더 높은 thinking 예산은 비용이 더 많이 듭니다. 최솟값으로 시작하여 응답이 성급하게 느껴지는 경우에만 늘리세요.

Opus 4.6 적응형 thinking: Opus 4.6은 문제 복잡도에 따라 thinking 깊이를 자동으로 조정합니다. 대부분의 작업에서는 명시적인 thinking 예산 제어가 필요하지 않습니다 — Opus는 어려운 문제에서는 확장되고 간단한 문제에서는 빠르게 유지됩니다. 수동 thinking 토글은 Sonnet에서 더 깊이 있는 분석을 강제하고 싶을 때 가장 유용합니다.

어떤 실행 환경을 선택해야 할까요?

Where should this work happen?
│
├── Requires YOUR local files and tools
│   │
│   ├── Interactive, iterative work → Main REPL session
│   ├── One-shot scripted task → claude -p "prompt" (print mode)
│   ├── CI/CD automation → claude -p --json (non-interactive + structured output)
│   └── Parallel isolated tasks → Subagents via Task tool
│
├── Requires SOMEONE ELSE'S environment
│   │
│   └── Remote codebase or server → Background agent (cloud)
│
└── Doesn't require any environment
    │
    ├── Research or analysis → Subagent with Explore type
    └── Web content extraction → WebFetch / WebSearch tools

Agent Team, Subagent, 병렬 세션 비교

Do you need multiple agents working on related subtasks?
│
├── YES → Are the subtasks independent (no shared state)?
│         │
│         ├── YES → Can they share the same codebase?
│         │         │
│         │         ├── YES → Use Agent Team (v2.1.32+)
│         │         │         Opus coordinates. Agents share repo access.
│         │         │         Example: "Review auth, API, and DB modules in parallel"
│         │         │
│         │         └── NO → Use Parallel Sessions (separate terminals)
│         │                  Each has its own working directory.
│         │                  Example: "Fix repo-A and repo-B simultaneously"
│         │
│         └── NO → Use Sequential Subagents
│                  Results from one feed into the next.
│                  Example: "Explore → Plan → Implement"
│
└── NO → Use Single Subagent or Main REPL

어떤 Hook 유형을 사용해야 할까요?

What kind of automation do you need?
│
├── Run a shell command at a specific event?
│   │
│   └── Use Command Hook
│       Trigger: PreToolUse, PostToolUse, Notification, Stop, SubagentStop
│       Example: "Run prettier after every file edit"
│       Config: hooks.PostToolUse[].command = "prettier --write $FILE"
│
├── Modify Claude's system prompt based on context?
│   │
│   └── Use Prompt Hook (v2.1.35+)
│       Trigger: Same events
│       Example: "Inject project rules when working in /src/auth/"
│       Config: hooks.PreToolUse[].prompt = "When editing auth files..."
│
└── Have Claude make a judgment call before proceeding?
    │
    └── Use Agent Hook (v2.1.35+)
        Trigger: Same events
        Example: "Evaluate if this bash command is safe before running"
        Config: hooks.PreToolUse[].agent = { prompt: "Is this safe?" }

/fast는 언제 사용해야 할까요?

Is response speed more important than depth right now?
│
├── YES → Use /fast
│         Same Opus 4.6 model, faster output
│         Good for: quick questions, simple edits, code explanations,
│                   file searches, formatting tasks
│
└── NO → Stay in normal mode
         Good for: architecture decisions, complex debugging,
                   security reviews, multi-file refactors,
                   anything requiring deep reasoning

/fast는 현재 세션에서 fast mode를 전환합니다. 동일한 모델 (Opus 4.6)을 사용하며 출력 속도가 최적화됩니다 — 더 저렴한 모델로 전환되지 않습니다.

Permission System은 어떻게 작동하나요?

Claude Code의 Permission System은 어떤 작업을 실행할 수 있는지 세밀하게 제어합니다. 이를 이해하면 보안과 workflow 효율성을 모두 높일 수 있습니다. 조직 전체에 permissions를 강제하는 관리형 설정은 Enterprise Deployment도 참고하세요.

Permission 단계

읽기 전용 tools(자동 승인): - Read - 파일 내용 읽기 - Glob - 패턴으로 파일 찾기 - Grep - 파일 내용 검색 - WebSearch - 웹 검색 - LSP - 코드 인텔리전스(go-to-definition, find references, hover docs)¹⁸

LSP Tool 기능(v2.0.74+): LSP tool은 IDE와 비슷한 코드 인텔리전스를 제공합니다. - Go-to-definition: 심볼이 정의된 위치로 이동합니다 - Find references: codebase 전체에서 심볼이 사용된 모든 위치를 나열합니다 - Hover docs: 모든 심볼의 타입 정보와 문서를 가져옵니다 - LSP를 지원하는 TypeScript, Python, Go, Rust 및 기타 언어에서 작동합니다 - language server가 사용 가능해야 합니다. 일반적으로 toolchain과 함께 설치됩니다

수정 tools(승인 필요): - Edit - 기존 파일 수정 - Write - 새 파일 생성 - Bash - shell commands 실행 - WebFetch - URL 콘텐츠 가져오기 - NotebookEdit - Jupyter notebooks 수정

수정 tool이 처음 실행될 때 Claude Code이 승인을 요청합니다. 명시적으로 다르게 설정하지 않는 한 승인은 해당 session 동안 유지됩니다.

Permission Modes

이제 acceptEdits에서도 code-execution config files는 prompt가 표시됩니다(v2.1.160). acceptEdits는 일반 edits를 자동 승인하지만, v2.1.160부터는 조용한 command execution 권한을 줄 수 있는 파일을 쓰기 전에 멈추고 prompt를 표시합니다. 여기에는 shell startup files(.zshenv, .zlogin, .bash_login), ~/.config/git/, build-tool configs(.npmrc, .yarnrc*, bunfig.toml, .bazelrc, .pre-commit-config.yaml, .devcontainer/ 등)가 포함됩니다. 이런 파일을 edit하면 다음 shell, install, commit이 execution vector가 될 수 있기 때문에, trusted-project mode에서 다른 edits는 통과시키더라도 별도의 명시적 gate를 둡니다. 이는 기존 .claude/, .git/, .vscode/ write protections와 같은 threat model을 더 넓은 “edit-becomes-execution” 파일 범주로 확장한 것입니다.¹⁷⁸

Auto Mode(v2.1.85+): --dangerously-skip-permissions를 더 안전하게 대체하는 mode입니다. 별도의 classifier model(Sonnet 4.6)이 실행 전에 각 action을 검토해 사용자 의도와 일치하는지, 안전한지 확인합니다.¹²⁴

작동 방식: - 읽기 전용 actions와 working directory 안의 file edits는 자동 승인됩니다 - Custom allow/deny rules가 먼저 적용됩니다 - 그 외 모든 것은 평가를 위해 classifier로 전달됩니다 - 차단되면 Claude이 자동으로 다른 접근 방식을 시도합니다

기본적으로 자동 차단되는 항목: curl | bash, main으로 force-push, production deploys/migrations, 대량 cloud deletions, IAM/permission changes, 민감한 데이터를 외부로 전송하는 행위.¹²⁵

Circuit breaker: session에서 3회 연속 차단되거나 총 20회 차단되면 manual prompting으로 일시 전환됩니다.¹²⁵

# Enable at startup
claude --enable-auto-mode

# Or cycle into it during a session
Shift+Tab  # Cycles through: default → acceptEdits → auto → plan

사용 가능 여부: Team plan users가 먼저 사용할 수 있으며, Enterprise와 API은 이후 지원됩니다. Sonnet 4.6 또는 Opus 4.6이 필요합니다.¹²⁴

YOLO Mode(v2.0.68+): safety classifier 없이 완전 자율 실행을 하려면 --dangerously-skip-permissions flag를 사용하세요. 이 flag는 file edits, bash commands, 모든 tool calls에 전부 yes라고 답합니다. “dangerous”라는 단어는 의도적으로 붙었습니다. 대부분의 사용 사례에는 Auto Mode가 권장 대안입니다.⁵⁴

claude --dangerously-skip-permissions

CLI로 mode 설정:

claude --permission-mode auto  # or acceptEdits, plan, bypassPermissions

session 중 전환:

Shift+Tab  # Cycles through modes

settings.json에서:

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Permission Rules 문법

세밀한 rules로 특정 작업을 제어합니다. rules는 순서대로 평가되며, 첫 번째 match가 적용됩니다.

Bash command patterns:

{
  "allow": [
    "Bash(npm run build)",
    "Bash(npm run test:*)",
    "Bash(git commit:*)",
    "Bash(make:*)"
  ],
  "deny": [
    "Bash(rm -rf:*)",
    "Bash(sudo:*)",
    "Bash(curl|wget:*)"
  ]
}

asterisk는 prefix matching을 제공합니다. Bash(npm run test:*)는 npm run test, npm run test:unit, npm run test:integration을 허용합니다.

중요한 제한: Bash patterns는 regex가 아니라 prefix만 match합니다. Bash(curl http:*) 같은 pattern은 options가 URL보다 먼저 오기 때문에 curl -X GET http://...와 match되지 않습니다. 안정적으로 차단하려면 command 전체를 deny하세요: Bash(curl:*).

File operation patterns:

{
  "allow": [
    "Edit(src/**)",
    "Write(src/**)",
    "Read(docs/**)"
  ],
  "deny": [
    "Read(.env*)",
    "Read(secrets/**)",
    "Edit(.git/**)",
    "Edit(node_modules/**)"
  ]
}

Path syntax: - Relative paths: Edit(src/**) - working directory 기준 상대 경로 - Absolute from settings file: Edit(/build/**) - settings file 위치 기준 상대 경로 - True absolute: Edit(//tmp/**) - //로 시작 - Home directory: Read(~/.zshrc)

MCP tool patterns:

{
  "allow": [
    "mcp__github",
    "mcp__database__query",
    "mcp__myserver__*"
  ],
  "deny": [
    "mcp__dangerous_server",
    "mcp__untrusted__*"
  ]
}

특정 MCP 서버의 모든 tools를 allow 또는 deny하려면 wildcard syntax mcp__server__*를 사용하세요.³² wildcard syntax는 신뢰할 수 있는 서버의 모든 tools를 빠르게 활성화하거나 신뢰할 수 없는 source의 전체 서버를 차단할 때 유용합니다.

v2.1.166부터 deny rules는 tool-name 위치에도 glob을 허용합니다. tool-name slot에 bare "*"를 넣으면 모든 tools를 deny할 수 있으므로, 전부 차단한 뒤 좁은 범위만 다시 allow할 수 있습니다. 반대로 allow rules는 non-MCP globs를 거부합니다. 같은 방식으로 광범위한 allow-all은 할 수 없으며, 이로써 기본 posture를 제한적으로 유지합니다.¹⁷⁶

Parameter-level matching — Tool(param:value)(v2.1.178):

tool name을 넘어서, rule은 tool의 input parameters도 match할 수 있으며 value에는 wildcard로 *를 사용할 수 있습니다.

{
  "deny": [
    "Agent(model:opus)"
  ]
}

Agent(model:opus)는 Opus tier에서 생성되는 모든 subagent를 차단합니다. 이는 단순히 prompt에서 피하라고 요청하는 것이 아니라 spawn 자체가 거부되는 방식입니다. 이렇게 permission control은 “어떤 tool인가”에서 “어떻게 호출되는가”까지 확장되며, prompt-level 요청이 아닌 결정론적 rule로 적용됩니다. 이는 관리형 enforceAvailableModels 설정과 함께 작동합니다. allowlist는 session에 존재하는 model tiers를 정의하고, Tool(model:...) rules는 subagents가 그중 무엇을 사용할 수 있는지 제한합니다.¹⁷³

WebFetch patterns:

{
  "allow": [
    "WebFetch(domain:github.com)",
    "WebFetch(domain:api.example.com)"
  ]
}

Additional Directories

현재 project 밖으로 Claude의 access를 확장합니다.

{
  "permissions": {
    "additionalDirectories": [
      "../shared-lib",
      "../docs",
      "~/reference-projects/design-system"
    ]
  }
}

Additional directories는 monorepos에서 필수적이거나, Claude이 sibling directories의 코드를 참조해야 할 때 필요합니다.

Sandbox Mode

filesystem 및 network isolation을 활성화합니다.

> /sandbox

또는 settings에서 설정합니다.

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true,
      "deniedDomains": ["pastebin.com", "transfer.sh", "0x0.st"]
    }
  }
}

sandboxed 상태에서는: - Filesystem access가 project directory로 제한됩니다 - Network access가 제어됩니다 - 특정 commands는 sandbox restrictions에서 제외됩니다 - autoAllowBashIfSandboxed가 true이면 Bash commands가 자동 허용됩니다

전문가 팁: Sandbox mode는 신뢰할 수 없는 codebase에서 Claude을 실행할 때 매우 유용합니다. 익숙하지 않은 projects를 살펴보거나 보호 계층을 하나 더 두고 싶을 때 활성화하세요. 내부 Anthropic testing에 따르면 sandboxing은 permission prompts를 84% 줄였습니다.³⁸ sandbox는 filesystem과 network isolation에 OS-level primitives(macOS seatbelt, Linux bubblewrap)를 사용하므로, prompt injection이 성공하더라도 완전히 격리됩니다. Anthropic는 자체 agents를 구축하는 teams를 위해 sandbox runtime을 open-source로 공개했습니다.⁸²

Security notes(v2.1.34+): sandbox.excludedCommands 또는 dangerouslyDisableSandbox로 sandboxing에서 제외된 commands는 이전에 autoAllowBashIfSandboxed가 활성화되었을 때 Bash ask permission rule을 우회할 수 있었지만, 이는 v2.1.34에서 수정되었습니다.⁸⁷ v2.1.38부터는 sandbox mode에서 .claude/skills에 대한 writes가 차단되어 prompt injection이 skill definitions를 수정하지 못하게 합니다.⁸⁸ v2.1.77은 denyRead regions 안에서 read access를 다시 허용하는 allowRead sandbox filesystem setting을 추가합니다. directory tree 대부분은 차단하되 특정 subdirectories만 whitelist하고 싶을 때 유용합니다.¹¹⁹

.claude/ agent-config exemption(v2.1.121+): --dangerously-skip-permissions는 더 이상 .claude/skills/, .claude/agents/, .claude/commands/에 대한 writes에서 prompt를 표시하지 않습니다.¹⁵⁴

Nested .claude/ resolution(v2.1.178): 이제 nested .claude/skills directories의 skills는 repo root에서만이 아니라 해당 directory 아래의 files에서 작업할 때 자동으로 load됩니다. name clash가 발생하면 nested skill은 <dir>:<name>으로 지정할 수 있어 둘 다 계속 사용할 수 있습니다. project surface의 나머지 부분도 같은 방식으로 resolve됩니다. nested .claude/ directories 사이에서 agent, workflow, output-style name이 충돌하면 working directory에 가장 가까운 항목이 우선하며, project-scope workflow save는 가장 가까운 기존 .claude/workflows/를 대상으로 합니다. monorepo 또는 repo-of-repos에서는 하나의 평평한 global surface 대신, context에 맞춰 활성화되는 package별 tooling을 제공할 수 있습니다.¹⁷³

Custom bubblewrap and socat paths(v2.1.133+): sandbox.bwrapPath와 sandbox.socatPath managed settings를 사용하면 admins가 Linux/WSL deployments에서 비표준 bubblewrap 및 socat binary locations를 지정할 수 있습니다. distributions가 이러한 tools를 $PATH 밖에 설치하거나 조직이 hardened builds를 자체 제공할 때 유용합니다.¹⁶⁰

v2.1.113의 security hardening:¹⁵⁰

• sandbox.network.deniedDomains는 더 넓은 allowedDomains wildcard가 허용하더라도 특정 hosts를 차단합니다. 전체 allow policy를 다시 작성하지 않고 pastebins, file drops, 알려진 bad hosts를 끊고 싶을 때 blocklist를 사용하세요.
• Wrapper-command deny rules. 이제 Bash deny rules는 env, sudo, watch, ionice, setsid 및 유사한 exec wrappers로 감싼 commands도 match합니다. Bash(rm:*) 같은 rules는 이제 env rm -rf, sudo rm -rf, sibling bypass patterns도 잡아냅니다.
• Bash(find:*) allow rules는 더 이상 find -exec 또는 find -delete를 자동 승인하지 않습니다. 해당 flags는 commands를 실행하고 files를 삭제하므로, Claude Code은 이를 일반 permission path로 라우팅합니다.
• macOS removal protection. 이제 Bash(rm:*) allow rules는 /private/etc, /private/var, /private/tmp, /private/home을 위험한 removal targets로 취급합니다. /var, /etc, /tmp는 /private/로 이어지는 symlinks이므로, 이전 rule 형태는 canonical targets를 놓쳤습니다.

Hooks는 어떻게 작동하나요?

Hooks는 Claude Code의 워크플로에서 특정 지점에 결정론적 shell command를 실행합니다. Claude에게 작업을 수행하라고 prompt하는 방식과 달리, hooks는 model 동작과 관계없이 실행을 보장합니다. 팀 표준을 강제하고 반복 작업을 자동화하는 데 꼭 필요합니다. command, prompt, agent hooks를 다루는 “어떤 Hook Type을 선택할까?” decision tree는 Decision Frameworks를 참고하세요.

prompt 대신 hooks를 쓰는 이유: Claude에게 “파일을 편집한 뒤 항상 Prettier를 실행해”라고 말하면 때로는 작동합니다. 하지만 Claude는 잊어버리거나, 속도를 우선시하거나, 변경이 “너무 작다”고 판단할 수 있습니다. Hooks는 실행을 보장합니다. 모든 Edit 또는 Write가 formatter를 매번, 예외 없이 트리거합니다. compliance, security, 팀 표준에서는 probabilistic보다 deterministic이 더 낫습니다.⁴

사용 가능한 Events

Hook Configuration

settings.json 또는 전용 hooks.json에 hooks를 정의하세요.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/inject-context.sh"
          }
        ]
      }
    ]
  }
}

Matchers

matcher field는 어떤 tools가 hook을 트리거할지 결정합니다.

{"matcher": "*"}              // Match all tools
{"matcher": "Bash"}           // Match Bash only
{"matcher": "Edit|Write"}     // Match Edit or Write
{"matcher": "mcp__github"}    // Match MCP server tools
{"matcher": ""}               // Match for events without tools (like UserPromptSubmit)

Hook Input/Output Protocol

Hooks는 stdin으로 JSON를 받습니다.

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123"
}

Hook event enrichment(v2.1.69+): 이제 모든 hook events는 subagent 또는 --agent session에서 트리거될 때 agent_id와 agent_type fields를 포함하며, status line hook commands에는 worktree field도 포함됩니다.¹¹⁰

Stop/SubagentStop hooks(v2.1.47+)는 Claude의 final response text가 들어 있는 추가 last_assistant_message field를 받습니다. 그래서 hooks가 transcript files를 parse하지 않고도 output을 검사할 수 있습니다.

{
  "session_id": "abc-123",
  "last_assistant_message": "I've completed the refactoring. Here's what changed..."
}

block 없는 soft feedback(v2.1.163+): Stop 및 SubagentStop hooks는 JSON output에서 hookSpecificOutput.additionalContext를 반환해 Claude에게 feedback을 전달하고 turn을 계속 진행할 수 있으며, response가 hook error로 표시되지 않습니다. 이전에는 Stop hook의 실질적인 수단이 exit-2 block뿐이었고, 이는 error처럼 읽히며 consecutive-block cap에 포함되었습니다. additionalContext는 loop와 충돌하지 않으면서 “놓친 부분은 이것이니 계속 진행해”라는 안내를 제공하는 steering channel을 추가합니다.¹⁷⁷

Exit codes는 동작을 제어합니다. - 0: Success: 작업이 계속됩니다. Stdout은 verbose mode(Ctrl+O)에 표시됩니다. UserPromptSubmit 및 SessionStart의 경우 stdout이 context에 추가됩니다. - 2: Blocking error: 작업이 중단됩니다. Stderr가 Claude에게 다시 전달되는 error message가 됩니다. - 1, 3 등: Non-blocking error: 작업이 계속됩니다. Stderr는 verbose mode에서 warning으로 표시됩니다.

고급 제어를 위해 hooks는 JSON를 output할 수 있습니다.

{
  "decision": "allow",
  "message": "Command validated and modified",
  "modifications": {
    "tool_input": {
      "command": "npm test -- --coverage"
    }
  }
}

PreToolUse decision control(권장 형식): PreToolUse hooks는 더 풍부한 제어를 위해 hookSpecificOutput을 사용합니다. 세 가지 결과(allow/deny/ask), tool input 수정, context 주입을 지원합니다.⁸⁹

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

참고: PreToolUse에서는 top-level decision 및 reason fields가 deprecated되었습니다. 대신 hookSpecificOutput.permissionDecision와 hookSpecificOutput.permissionDecisionReason을 사용하세요. 다른 events(PostToolUse, Stop 등)는 여전히 top-level decision을 사용합니다.⁸⁹

UserPromptSubmit session title(v2.1.94+): UserPromptSubmit hooks는 hookSpecificOutput.sessionTitle을 통해 session title을 설정할 수 있습니다.¹⁴⁰

Async Hooks(2026년 1월)

이제 hooks는 Claude Code 실행을 차단하지 않고 background에서 실행될 수 있습니다. hook configuration에 async: true를 추가하세요.⁸¹

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/notify-slack.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

async hooks를 사용할 때: - session을 느리게 만들면 안 되는 notifications(Slack, email, Pushover) - background에서 실행되어도 되는 logging 및 telemetry - 중요도가 낮은 post-processing(analytics, backups)

async hooks를 사용하지 말아야 할 때: - Formatting(다음 edit 전에 완료되어야 함) - Validation(실패 시 반드시 차단해야 함) - tool input/output을 수정해야 하는 hook

Prompt-Based 및 Agent-Based Hooks(v2.1.32+)

shell command hooks(type: "command") 외에도 Claude Code는 scripts가 아니라 AI reasoning을 사용해 조건을 평가하는 두 가지 LLM 기반 hook types를 지원합니다.⁸⁹

Prompt hooks(type: "prompt")는 빠른 Claude model에 single-turn prompt를 보냅니다. model은 허용하려면 { "ok": true }, 차단하려면 { "ok": false, "reason": "..." }를 반환합니다.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all requested tasks are complete and tests pass.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

HTTP hooks(type: "http")는 event의 JSON input을 URL에 POST request로 보내고 JSON를 다시 받습니다. webhooks, external notification services 또는 API 기반 validation에 사용하세요(v2.1.63+).¹⁰⁴

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "http",
            "url": "https://api.example.com/notify",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

HTTP hooks는 command hooks와 동일한 decision format을 사용합니다(decision과 reason이 있는 JSON 반환). sandboxing이 활성화된 경우 sandbox network proxy를 통해 routing됩니다. SessionStart/Setup events에서는 지원되지 않습니다.

Agent hooks(type: "agent")는 multi-turn verification을 위해 tool access(Read, Grep, Glob)가 있는 subagent를 생성합니다. 실제 files 또는 test output을 검사해야 할 때 사용하세요.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

hook의 JSON input placeholder로 $ARGUMENTS를 사용하세요. 두 types 모두 model(기본값은 fast model)과 timeout fields를 지원합니다. 지원되는 events: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Stop, SubagentStop, TaskCompleted. TeammateIdle은 prompt/agent hooks를 지원하지 않습니다.

MCP Tool Hooks(v2.1.118+)

이제 hooks는 type: "mcp_tool"을 통해 MCP tool을 직접 호출할 수 있어, server를 호출하는 Bash subprocess로 감쌀 필요가 없습니다.¹⁵²

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "linear",
            "tool": "create_comment",
            "input": {"issue_id": "ENG-123", "body": "Auto-updated by Claude Code"}
          }
        ]
      }
    ]
  }
}

이는 사용자가 이미 설정해 둔 MCP servers와 잘 맞습니다. /mcp에서 접근 가능한 모든 tool은 hook에서 호출할 수 있습니다.

PostToolUse Hooks의 duration_ms(v2.1.119+)

이제 PostToolUse 및 PostToolUseFailure hook inputs에는 permission prompts와 PreToolUse hooks를 제외한 tool 실행 시간인 duration_ms가 포함됩니다.¹⁵² slow-tool detection, audit logs, tool별 latency metrics에 유용합니다.

# Stderr-flagged warning when an Edit takes more than 10 seconds
DUR=$(jq -r '.duration_ms')
if [ "$DUR" -gt 10000 ]; then
  echo "[slow-edit] ${DUR}ms — investigate $TOOL_INPUT_FILE_PATH" >&2
fi

모든 Tools를 위한 updatedToolOutput(v2.1.121+)

v2.1.118에서 MCP Tool Hooks는 hookSpecificOutput.updatedToolOutput을 통해 tool output을 대체할 수 있게 되었습니다. v2.1.121부터는 동일한 field가 모든 PostToolUse hook에서 작동합니다. built-in tools(Bash, Read, Edit, Glob, Grep 등), subagent tools, MCP tools 모두에 적용됩니다. 사용 사례: 모든 tool output에서 민감한 content redaction, downstream consumers를 위한 structure normalization, agent가 result를 읽기 전에 metadata 주입.¹⁵⁴

Hook Environment Variables

Hooks는 paths를 resolve하기 위한 environment variables에 접근할 수 있습니다.⁸⁹

SessionStart에서 environment variables persist하기:

#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
fi
exit 0

HTTP hook security(v2.1.51+): headers에 environment variables를 interpolate하는 HTTP hooks는 이제 명시적인 allowedEnvVars list가 필요합니다. 이를 통해 header values를 통한 임의 environment variable exfiltration을 방지합니다. 또한 sandboxing이 활성화된 경우 HTTP hooks는 sandbox network proxy를 통해 routing되어 domain allowlist가 강제됩니다. HTTP hooks는 SessionStart/Setup events에서 지원되지 않습니다.⁹⁸

{
  "hooks": {
    "PostToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "curl -H 'Authorization: Bearer $MY_TOKEN' https://api.example.com/notify",
        "allowedEnvVars": ["MY_TOKEN"]
      }]
    }]
  }
}

Hook workspace trust(v2.1.51+): 이제 statusLine 및 fileSuggestion hook commands는 interactive mode에서 실행되기 전에 workspace trust acceptance가 필요하며, 잠재적인 security vector를 차단합니다.⁹⁸

실용적인 Hook 예시

편집 후 TypeScript files 자동 formatting:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.ts ]] && npx prettier --write \"$FILE_PATH\" || true'"
          }
        ]
      }
    ]
  }
}

모든 bash commands 기록:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-history.log"
          }
        ]
      }
    ]
  }
}

민감한 files 접근 차단:

#!/bin/bash
# .claude/hooks/protect-files.sh
data=$(cat)
path=$(echo "$data" | jq -r '.tool_input.file_path // empty')

if [[ "$path" == *".env"* ]] || [[ "$path" == *"secrets/"* ]] || [[ "$path" == *".pem"* ]]; then
  echo "Blocked: Cannot access sensitive file $path" >&2
  exit 2  # Exit 2 = block the tool call. Exit 1 = non-blocking error (hook failure only).
fi
exit 0

code changes 후 tests 실행:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.test.ts ]] || npm run test:affected'"
          }
        ]
      }
    ]
  }
}

Custom notification system:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Waiting for your input'"
          }
        ]
      }
    ]
  }
}

prompts에 dynamic context 주입:

#!/bin/bash
# .claude/hooks/inject-context.sh
# Add current git branch and recent commits to every prompt

branch=$(git branch --show-current 2>/dev/null)
commits=$(git log --oneline -3 2>/dev/null | tr '\n' ' ')

if [ -n "$branch" ]; then
  echo "[Context: Branch '$branch', Recent: $commits]"
fi
exit 0

Hook Debugging

hooks 문제를 해결하려면 debug mode를 활성화하세요.

claude --debug

Debug mode는 다음을 기록합니다. - Hook execution times - Input/output data - Error messages 및 stack traces - Decision results(allow/reject/ask)

Hook source display(v2.1.75+): hook에 user confirmation이 필요할 때, 이제 permission prompt에 hook의 source(settings, plugin 또는 skill)가 표시되어 어떤 component가 access를 요청하는지 더 쉽게 파악할 수 있습니다.¹¹⁷

Component-Scoped Hooks(v2.1.0+)

Hooks는 frontmatter를 사용해 Skills, subagents, slash commands에 직접 정의할 수 있습니다. 이러한 hooks는 component의 lifecycle 범위로 제한되며 해당 component가 active일 때만 실행됩니다.³⁴

embedded hooks가 있는 Skill:

---
name: secure-deployment
description: Deployment skill with security validation
hooks:
  PreToolUse:
    - matcher: Bash
      command: ".claude/hooks/validate-deploy.sh"
  PostToolUse:
    - matcher: Bash
      command: ".claude/hooks/log-deploy.sh"
  Stop:
    - command: ".claude/hooks/cleanup.sh"
      once: true  # Run only once per session
---

지원되는 events: PreToolUse, PostToolUse, Stop

once option(skills 및 slash commands only)은 hook이 session당 한 번만 실행되도록 보장하며, cleanup 또는 finalization tasks에 유용합니다.

Long-Running Sessions Strategy

밤새 실행되거나 무인으로 실행되는 Claude Code sessions의 경우, 수동 개입 없이 Claude가 올바른 방향을 유지하도록 hooks를 설정하세요. 핵심은 linting 및 testing hooks를 guardrails로 사용해 Claude가 계속 진행하기 전에 issues를 수정하도록 강제하는 것입니다.⁵⁷

“Tests가 통과할 때까지 멈추지 않기” Pattern:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint && npm run typecheck",
            "timeout": 60000
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm test || echo 'Tests failing - Claude should fix before stopping'"
          }
        ]
      }
    ]
  }
}

overnight sessions를 위한 strategy:

1. Pre-flight check: Setup hook을 사용해 environment가 준비되었는지 확인하세요
2. Continuous validation: PostToolUse hooks가 각 change 후 tests를 실행합니다
3. Gate completion: Stop hooks가 Claude가 “done”이라고 선언하기 전에 모든 acceptance criteria를 확인합니다
4. Notification: Stop hooks는 Claude가 완료하거나 막혔을 때 Slack/Pushover로 알릴 수 있습니다

완전 자율 overnight runs를 위해 sandboxed container에서 --dangerously-skip-permissions와 함께 사용하세요. Claude는 tests가 통과하거나 선택지가 소진될 때까지 계속 iterating합니다.

MCP (Model Context Protocol)이란?

MCP는 표준화된 프로토콜을 통해 Claude Code가 외부 도구, 데이터베이스, API, 서비스에 접근할 수 있도록 확장합니다. 생태계는 폭발적으로 성장했습니다. MCP는 현재 월간 1억 다운로드와 MCP.so에 인덱싱된 3,000개 이상의 서버(2026년 1월 기준)를 보유하고 있으며, AI를 도구 및 데이터에 연결하는 업계 표준으로서의 입지를 굳혔습니다.³⁴⁷ MCP를 이해하는 것은 Claude를 기존 도구 체인에 통합하는 데 필수적입니다.

MCP가 개발자에게 중요한 이유: MCP가 없으면 Claude Code는 파일을 읽고 bash 명령을 실행할 수만 있습니다. MCP를 사용하면 Claude가 프로덕션 데이터베이스를 쿼리하고, Jira 티켓을 만들고, GitHub PR을 검토하고, Sentry 오류를 확인하며, 팀이 사용하는 모든 API와 자연어 요청만으로 상호 작용할 수 있습니다. 이 프로토콜은 AI 도구가 외부 서비스에 연결되는 방식을 표준화하여 벤더 종속을 방지합니다. MCP를 다른 확장 메커니즘 대신 사용해야 하는 시점에 대한 안내는 Decision Frameworks를 참조하세요.

원격 MCP 지원 (2025년 6월)

Claude Code는 이제 네이티브 OAuth 인증과 함께 원격 MCP 서버를 지원합니다.²¹ 로컬 서버를 관리하지 않고도 도구와 데이터 소스에 연결할 수 있습니다. 한 번만 인증하면 Claude Code가 토큰 갱신을 자동으로 처리합니다.

# Connect to remote MCP server with OAuth
claude mcp add --transport http linear https://mcp.linear.app/sse
# Browser opens for OAuth flow, tokens stored securely

SDK mcp_authenticate redirectUri (v2.1.121+): Agent SDK의 mcp_authenticate는 사용자 정의 URI 스킴에서 OAuth를 완료하기 위한 redirectUri 매개변수를 받습니다. 기본 루프백 리다이렉트를 사용할 수 없는 데스크톱 앱과 claude.ai 커넥터 흐름에 필요합니다.¹⁵⁴

claude.ai MCP 커넥터 (v2.1.46+)

Claude Code는 이제 claude.ai 계정에 구성된 MCP 커넥터를 사용할 수 있습니다. 이는 웹과 CLI 사이의 격차를 메웁니다. claude.ai 인터페이스를 통해 설정한 MCP 서버는 로컬에서 다시 구성하지 않아도 Claude Code에서 자동으로 사용할 수 있습니다.⁹⁵

옵트아웃: 환경 변수나 settings.json의 env 블록에 ENABLE_CLAUDEAI_MCP_SERVERS=false를 설정하면 claude.ai MCP 서버가 로드되지 않도록 할 수 있습니다.¹⁰⁴

MCP Tool Search (v2.1.7+)

MCP 서버의 기능이 늘어나면서(일부는 50개 이상의 도구를 노출) 도구 설명이 컨텍스트를 과도하게 소비하기 시작했습니다. MCP Tool Search는 필요할 때만 도구 설명을 동적으로 로드하는 방식, 즉 AI 도구를 위한 일종의 지연 로딩으로 이 문제를 해결합니다.⁴⁷

성능 영향: 내부 벤치마크에서 정확도가 극적으로 향상되었습니다. - Opus 4: MCP 평가에서 49% → 74% - Opus 4.5: MCP 평가에서 79.5% → 88.1% - 토큰 오버헤드 감소: 85%

작동 방식: MCP 도구 설명이 컨텍스트 윈도우의 10%(기본 임계값)를 초과하면 Claude Code는 실제로 필요할 때까지 전체 설명 로딩을 미룹니다. Claude는 도구 이름은 보지만 설명은 필요할 때 가져옵니다.

구성:

{
  "mcpToolSearchAutoEnable": "auto:15"  // Enable when tools exceed 15% of context
}

값: - true - 항상 도구 검색 활성화 - false - 항상 비활성화(모든 도구 설명을 미리 로드) - auto:N - 도구가 컨텍스트의 N%(0-100)를 초과할 때 활성화

전문가 팁: Tool Search를 활성화하면 컨텍스트 한도를 걱정하지 않고 훨씬 더 많은 MCP 서버에 연결할 수 있습니다. 95%의 컨텍스트 감소 덕분에 이전에는 컨텍스트를 두고 경쟁하던 서버들이 이제 평화롭게 공존합니다.

MCP Always-Load 오버라이드 (v2.1.121+)

Tool Search는 도구가 필요해질 때까지 전체 설명 로딩을 미룹니다(임계값: mcpToolSearchAutoEnable, 기본값 auto:10). 매번 사용할 것으로 예상되는 신뢰할 수 있는 서버의 경우, alwaysLoad: true로 서버별 옵트아웃이 가능합니다. 해당 서버의 모든 도구가 세션 시작 시 프롬프트에 로드되며 ToolSearch 왕복은 없습니다.¹⁵⁴

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "alwaysLoad": true
    }
  }
}

MCP 시작 자동 재시도 (v2.1.121+): 시작 중 오류가 발생한 서버는 이제 연결 끊김으로 표시되기 전에 최대 3번까지 재시도됩니다. 느린 부모 프로세스와 경쟁하는 stdio 서버나 콜드 스타트 백엔드 뒤에 있는 HTTP 서버에 유용합니다.¹⁵⁴

MCP Elicitation (v2.1.76+)

MCP 서버는 이제 작업 중간에 대화형 다이얼로그를 통해 사용자로부터 구조화된 입력을 요청할 수 있습니다.¹¹⁸ MCP 서버에 추가 정보(예: 브랜치 선택, 프로젝트 이름 입력, 작업 확인)가 필요하면 Claude Code가 폼 필드나 브라우저 URL로 렌더링하는 elicitation 요청을 보냅니다.

Hook 통합: 두 가지 새로운 hook 이벤트인 Elicitation(다이얼로그가 나타나기 전)과 ElicitationResult(사용자가 응답한 후)를 통해 elicitation 응답을 프로그래밍 방식으로 가로채거나 검증하거나 재정의할 수 있습니다. 이를 통해 MCP 서버 프롬프트를 미리 채우거나 정책에 따라 제한하는 엔터프라이즈 워크플로가 가능합니다.

MCP 결과 크기 오버라이드 (v2.1.91+)

MCP 도구 결과는 기본적으로 잘립니다. 서버는 _meta["anthropic/maxResultSizeChars"] 어노테이션을 사용해 결과별로 이를 재정의할 수 있으며 최대 500K 문자까지 허용됩니다.¹³⁶ 데이터베이스 스키마, API 응답, 파일 내용과 같은 큰 페이로드를 잘림 없이 반환할 때 유용합니다.

대화형 MCP 설정 마법사

claude mcp add를 인수 없이 실행하면 MCP 서버를 추가하는 단계별 인터페이스가 시작됩니다. 마법사는 전송 유형 선택, 인증, 구성을 안내합니다.⁸

전송 유형

HTTP (원격 서버에 권장):

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# With authentication
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer $API_TOKEN"

SSE (사용 중단되었지만 작동):

claude mcp add --transport sse asana https://mcp.asana.com/sse \
  --header "X-API-Key: your-key"

Stdio (로컬 서버):

# PostgreSQL
claude mcp add --transport stdio postgres \
  --env "DATABASE_URL=postgresql://user:pass@localhost/db" \
  -- npx -y @anthropic-ai/mcp-server-postgres

# Custom server
claude mcp add --transport stdio custom -- python /path/to/server.py --port 8000

Windows에서는 stdio용 cmd 래퍼가 필요합니다.

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

범위 관리

MCP 서버는 명확한 우선순위를 가진 세 가지 범위로 존재합니다(local이 project를 재정의하고 project가 user를 재정의함).

설치 시 범위 지정:

claude mcp add --scope project --transport http github https://...
claude mcp add --scope user --transport stdio personal-tool -- ./my-tool

구성 파일 형식

.mcp.json 파일은 프로젝트 수준 서버를 정의합니다.

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SENTRY_API_KEY}"
      }
    },
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "X-API-Key": "${INTERNAL_API_KEY}"
      }
    }
  }
}