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

요약: Claude Code은 계층형 권한, hooks, MCP 통합, subagents 시스템을 통해 코드베이스를 읽고 명령을 실행하며 파일을 수정하는 에이전트형 CLI입니다. 5가지 핵심 시스템인 설정, 권한, hooks, MCP, subagents를 익히면 생산성을 크게 높일 수 있습니다. 작업에 맞는 모델 등급을 선택하세요. 복잡한 추론에는 Opus, 일반 작업에는 Sonnet, 빠른 탐색에는 Haiku가 적합하며, 품질만 중요하다면 Opus로 통일해도 됩니다. 항상 실행해야 하는 작업에는 프롬프트가 아닌 hooks를 사용하세요. v2.1.197(2026년 6월 30일)부터 Claude Sonnet 5가 Claude Code의 기본 모델입니다. 기본으로 1M 컨텍스트를 지원하며 8월 31일까지 $2/$10 프로모션 요금이 적용되고, /model opus만 실행하면 여전히 Opus 4.8을 사용할 수 있습니다. v2.1.198(7월 1일)부터 subagents가 기본적으로 백그라운드에서 실행되고, Chrome용 Claude이 정식 출시되었으며, 백그라운드 에이전트가 worktree 코드 작업을 마치면 커밋하고 푸시한 뒤 초안 PR을 열 수 있습니다. 또한 백그라운드 세션에 Notification hook(agent_needs_input/agent_completed)이 실행됩니다. v2.1.199(7월 2일)는 중첩된 slash-skill 호출을 최대 5개까지 불러오고 구독자에게 발생한 일시적인 429 오류를 자동으로 재시도합니다. v2.1.200(7월 3일)은 CLI, --help, VS Code, JetBrains 전반에서 default 권한 모드의 이름을 “Manual”로 변경했으며 설정값은 바뀌지 않고 manual도 별칭으로 사용할 수 있습니다. 또한 AskUserQuestion 대화 상자가 기본적으로 자동 진행되지 않도록 변경했습니다. v2.1.202(7월 6일)는 “Dynamic workflow size” /config 제어 기능을 추가하고 /review <pr>을 빠른 단일 패스 리뷰로 되돌렸으며, 멀티 에이전트 패스는 /code-review <level> <pr#>로 이동했습니다. v2.1.203–205(7월 7~9일)는 auto mode의 보안을 강화했습니다. 대화 기록 파일의 변조를 차단하고, 확인할 수 없는 변수를 대상으로 rm -rf를 실행할 때 먼저 사용자에게 묻고, 백그라운드 작업 알림에 사람이 입력하지 않았다는 사실을 명시해 대화 기록 안에 조작된 승인을 실행하지 못하게 합니다. 또한 /doctor를 진단과 수정을 모두 수행하는 종합 점검 기능으로 개편하고 /checkup 별칭을 추가했습니다.^181182183 v2.1.174–176(2026년 6월 12일)부터 새로운 enforceAvailableModels 관리형 설정을 통해 availableModels 허용 목록으로 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에는 마켓플레이스 검색창이 추가되고, claude_code.lines_of_code.count OTEL 메트릭에는 model 속성이 추가됩니다. v2.1.170(2026년 6월 9일)부터 Opus보다 상위 등급인 새로운 모델 Claude Fable 5를 claude update 후 /model fable을 사용해 Claude Code에서 선택할 수 있습니다. low부터 max까지 전체 effort 범위를 지원하지만 thinking을 비활성화할 수는 없습니다. 에이전트형 작업의 기본 모델은 계속 Opus 4.8입니다. v2.1.169(2026년 6월 8일)부터 --safe-mode 및 CLAUDE_CODE_SAFE_MODE를 사용하면 문제 해결을 위해 모든 사용자 지정 기능을 비활성화한 깨끗한 세션을 시작할 수 있고, /cd를 사용하면 프롬프트 캐시를 깨뜨리지 않고 세션을 새 작업 디렉터리로 옮길 수 있으며, disableBundledSkills를 사용하면 모델에서 기본 제공 skills와 slash commands를 숨길 수 있습니다. v2.1.166(2026년 6월 6일)부터 fallbackModel 설정을 사용하면 기본 모델에 과부하가 발생했을 때 최대 3개의 예비 모델을 연속으로 사용할 수 있고, 글로브 "*"가 MCP 거부 규칙에서 작동하며, MAX_THINKING_TOKENS=0 또는 --thinking disabled를 사용하면 기본적으로 thinking을 사용하는 모델에서도 thinking을 완전히 끌 수 있습니다. v2.1.154(2026년 5월 28일)부터 Opus 4.8이 high effort를 기본값으로 사용하는 새로운 기본 모델이 되었고 /effort xhigh 수준이 추가되었습니다. dynamic workflows는 /workflows를 통해 수십 개에서 수백 개의 에이전트를 백그라운드에서 조정합니다. Opus 4.8의 Fast mode는 표준 요금의 2배로 2.5배 빠른 속도를 제공하며, 간결한 시스템 프롬프트가 Haiku/Sonnet/Opus 4.7 이하 모델을 제외한 모든 모델의 기본값이 되었습니다. /simplify는 /code-review --fix와 분리된 정리 전용 리뷰로 돌아갔고, claude agents는 백그라운드 셸 세션을 생성하는 ! <command>를 지원하며, plugins는 defaultEnabled: false를 선언할 수 있습니다. 스트리밍 도구 실행은 항상 활성화되고, stdio MCP 서버는 환경 변수로 CLAUDE_CODE_SESSION_ID와 CLAUDECODE=1을 받습니다. v2.1.153은 plugin 마켓플레이스에 skipLfs를 추가하고, /model에서 선택한 모델이 기본값으로 저장되도록 변경했으며 세션에만 적용하려면 s를 누를 수 있습니다. 또한 상태 표시줄 환경에 COLUMNS/LINES를 추가했습니다. v2.1.152는 작업 트리에 발견된 문제의 수정 사항을 적용하는 /code-review --fix, skill frontmatter의 disallowed-tools, /reload-skills, 새로운 MessageDisplay hook 이벤트, SessionStart hook의 reloadSkills/sessionTitle 출력, pluginSuggestionMarketplaces 관리형 설정, 세션 도중 --fallback-model 전환 기능을 도입했으며 auto-mode 옵트인을 제거했습니다.^{162 163 164 165 166 167 168 169 170 197 171}

Claude Code은 프로그래밍 지식을 갖춘 채팅 인터페이스가 아니라 에이전트형 시스템으로 작동합니다. CLI는 코드베이스를 읽고, 명령을 실행하고, 파일을 수정하고, git 워크플로를 관리하고, MCP를 통해 외부 서비스에 연결하고, 복잡한 작업을 전문 subagents에 위임합니다. 모든 작업은 개발자의 실제 업무 방식에 통합되는 명령줄 인터페이스를 통해 이루어집니다. 2026년 2월 기준으로 공개 GitHub 커밋의 4%인 하루 약 135,000개가 Claude Code으로 작성되고 있습니다. 이는 연구 프리뷰 이후 13개월 만에 42,896배 증가한 수치이며, Anthropic 자체 코드의 90%도 AI가 작성합니다.¹⁰³

Claude Code을 가볍게 사용하는 경우와 효과적으로 사용하는 경우의 차이는 5가지 핵심 시스템에서 결정됩니다. 이 시스템들을 익히면 Claude Code을 강력한 생산성 도구로 활용할 수 있습니다.

1. 설정 계층 구조: 동작을 제어합니다
2. 권한 시스템: 작업 실행 여부를 통제합니다
3. Hook 시스템: 결정론적 자동화를 지원합니다
4. MCP 프로토콜: 기능을 확장합니다
5. Subagent 시스템: 복잡한 다단계 작업을 처리합니다

핵심 요점

• 5가지 시스템이 작업 효율을 결정합니다: 설정 계층 구조, 권한, hooks, MCP, subagents가 동작부터 자동화까지 모든 요소를 제어합니다.
• 작업을 위임 계층으로 보내세요: subagents는 별도의 깨끗한 컨텍스트 창에서 탐색을 수행하고 요약만 반환하므로 컨텍스트가 불필요하게 커지는 것을 방지합니다.
• Hooks는 실행을 보장하지만 프롬프트는 그렇지 않습니다: 모델의 동작과 관계없이 매번 실행해야 하는 린팅, 포매팅, 보안 검사에는 hooks를 사용하세요.
• 모델을 작업별로 구분하면 품질을 유지하면서 비용을 절감할 수 있습니다: subagent의 탐색 작업은 저렴한 모델에 맡기고 실제 아키텍처 추론에만 Opus를 사용하세요. 품질만 중요하다면 Opus로 통일해도 됩니다.
• MCP는 Claude을 도구 체인과 연결합니다: 데이터베이스, GitHub, Sentry를 비롯한 3,000개 이상의 통합 기능으로 Claude의 역량을 파일 읽기와 bash 명령 너머로 확장할 수 있습니다.

저는 프로덕션 코드베이스, CI/CD 파이프라인, 엔터프라이즈 배포 환경에서 수개월 동안 Claude Code의 한계를 시험했습니다. 이 가이드는 제가 처음 시작할 때 있었으면 했던 완전한 참고 자료로 그 경험을 정리한 것입니다. 모든 기능에는 실제 구문, 실전 설정 예시, 숙련된 사용자도 놓치기 쉬운 예외 상황이 포함되어 있습니다.

필요한 경로를 선택하세요

이 가이드를 활용하는 방법

이 문서는 5,000줄이 넘는 참고 자료이므로 처음부터 끝까지 모두 읽을 필요는 없습니다. 자신의 경험 수준에 맞는 부분부터 시작하세요.

특정 플래그, 명령, 설정 키를 찾으려면 브라우저에서 Ctrl+F / Cmd+F를 사용하세요. 문서 끝에 있는 빠른 참조 카드에서는 모든 주요 명령을 훑어보기 쉬운 형태로 확인할 수 있습니다.

관련 심층 분석

다음 블로그 게시물에서는 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을 실행하면 대화형 읽기-평가-출력 루프로 진입해요.

cd your-project
claude

REPL은 여러 차례 대화를 주고받는 동안 대화 맥락을 유지해요. 질문을 직접 입력하고 응답을 받은 뒤, /exit 또는 Ctrl+D로 종료할 때까지 대화를 계속할 수 있어요.

초기 프롬프트와 함께 시작하면 세션의 초점을 정할 수 있어요.

claude "explain the authentication flow in this project"

전문가 팁: REPL은 압축이 발생해도 상태를 유지해요. 맥락이 너무 길어지면 Claude이 주요 결정 사항과 코드 조각을 보존하면서 이전 대화를 자동으로 요약해요. /compact로 직접 실행하거나 보존할 내용을 지정하는 맞춤 지침을 추가할 수도 있어요.

비대화형 모드

출력 모드(-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

출력 형식 옵션:

stream-json의 subagents 텍스트(v2.1.211+): 기본적으로 stream-json 출력에는 기본 세션의 이벤트만 포함되며, subagents 내부에서 수행한 작업은 요약으로 표시돼요. --forward-subagent-text 플래그 또는 CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1을 사용하면 subagents의 텍스트와 사고 과정 출력도 스트림으로 전달돼요. 따라서 하네스와 로그 파이프라인은 최종 보고서만 확인하는 대신 위임된 작업이 진행되는 과정을 실시간으로 관찰할 수 있어요.¹⁸⁸

종료 코드:

-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 작업을 쉽게 재개할 수 있어요. prUrlTemplate 설정(v2.1.119+)을 사용하면 하단의 PR 배지가 맞춤 코드 리뷰 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을 사용하세요.

/fork는 백그라운드 세션을 생성하고, /subtask는 현재 세션 내부에서 분기해요(v2.1.212). 이제 /fork 명령은 현재 대화를 새 백그라운드 세션으로 복사해요. 복사된 세션은 claude agents에 별도의 행으로 표시되므로, 기본 세션을 계속 진행하면서 다른 접근 방식을 탐색하도록 보낼 수 있어요. 현재 세션 내부에서 분기하던 기존 동작은 새로운 이름인 /subtask로 이용할 수 있어요.¹⁸⁹

Claude Code은 세션을 JSONL 트랜스크립트로 저장해요. 에이전트가 실행되면 고유한 agentId 값이 할당되고, 트랜스크립트는 agent-{agentId}.jsonl 형식으로 저장돼요. 세션을 재개하면 이전 대화의 전체 맥락이 유지돼요.

Plan 모드

Plan 모드에서는 Claude이 읽기 전용 탐색만 수행할 수 있어요. 파일 편집, bash 실행, 파괴적인 작업은 허용되지 않아요. Claude은 구현 방식을 설계해 계획 파일에 작성하고, 작업을 실행하기 전에 사용자의 승인을 기다려요.

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에 작성해요.
4. ExitPlanMode로 Plan 모드를 종료하고 검토할 계획을 제시해요.
5. 사용자는 승인하거나, 변경을 요청하거나, 거부할 수 있어요.

Plan 모드에서 사용할 수 있는 도구: Read, Glob, Grep, LS, WebSearch, WebFetch, AskUserQuestion. 편집 도구(Edit, Write, Bash, NotebookEdit)는 차단돼요.

계획 승인 후(v2.1.32+): Claude은 다음 3가지 옵션을 제공해요. - “네, 맥락을 지우고 편집을 자동 승인합니다”(Shift+Tab) — 계획을 위한 전체 맥락을 새로 확보해 시작해요. - “네, 편집을 직접 승인합니다” — 맥락을 유지하고 사용자가 각 변경 사항을 승인해요. - “네, 편집을 자동 승인합니다” — 맥락을 유지하고 Claude이 각 편집에 대한 승인 없이 실행해요.

승인할 때 맥락 자동 지우기가 권장되는 작업 흐름이에요. 계획에 새로운 맥락 창을 제공하므로 계획 준수율이 크게 향상돼요. 이전 대화가 방해하지 않아 Claude이 더 오랫동안 계획에서 벗어나지 않아요.

Plan 모드를 사용하기 좋은 경우: - 아키텍처 결정이 필요한 새로운 기능을 구현할 때 - 접근 방식을 먼저 검토하고 싶은 여러 파일에 걸친 리팩터링을 수행할 때 - 수정 전에 탐색이 필요한 익숙하지 않은 코드베이스에서 작업할 때 - 유효한 접근 방식이 여러 개이며 사용자의 의견을 반영하고 싶을 때

전문가 팁: Plan 모드에 더 많은 시간을 들일수록 Claude이 구현에 성공할 가능성이 높아져요. Plan 모드는 위험한 도구 호출이나 불필요한 편집 없이 자유롭게 탐색할 수 있는 단계예요. 적극적으로 활용하세요.

화면 읽기 프로그램 모드(v2.1.208)

Claude Code에는 보조 기술에 맞게 터미널 UI를 조정하는 전용 화면 읽기 프로그램 모드가 포함돼요. 다음 3가지 방법 중 하나로 활성화할 수 있어요.¹⁸⁶

# Flag at launch
claude --ax-screen-reader

# Environment variable
export CLAUDE_AX_SCREEN_READER=1

# Or persistently in settings.json
{ "axScreenReader": true }

Anthropic의 공식 문서에 새로 추가된 접근성 페이지에서는 이 모드와 상호작용 패턴을 설명해요.¹⁸⁶

설정 시스템 자세히 알아보기

Claude Code는 계층형 설정 시스템을 사용해요. 상위 수준의 설정이 하위 수준의 설정을 덮어쓰며 엔터프라이즈 설정은 우회할 수 없으므로, 이 계층 구조를 이해해야 해요.

설정 계층 구조

전문가 팁: 공유 프로젝트의 개인 설정에는 .claude/settings.local.json을 사용하세요(.gitignore에 추가하세요). 버전 관리에 포함할 팀 공통 설정에는 .claude/settings.json을 사용하세요.

프롬프트에서 설정 구성하기: /config key=value (v2.1.181)

v2.1.181부터는 대화형 /config UI를 열지 않고도 /config key=value로 프롬프트에서 원하는 설정을 바로 지정할 수 있어요. 예를 들면 /config thinking=false처럼 사용할 수 있으며, 대화형 세션과 -p, Remote Control 세션에서 모두 작동해요. /config --help(v2.1.183)는 사용할 수 있는 단축 키를 보여줘요. 또한 v2.1.183에서는 대화형 /config UI가 변경되어 Enter와 Space 모두 선택한 설정을 전환하고, Esc는 저장한 뒤 닫아요. 이전에는 변경 사항을 되돌렸어요.¹⁷⁴

전체 settings.json 레퍼런스

주요 옵션을 모두 보여주는 전체 설정 예시는 다음과 같아요.

{
  "$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/**)",
      "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 라이브러리가 있지만 런타임에 노출되는 범위를 더 엄격하게 제한하려는 경우 유용해요. off를 사용하면 모델과 slash picker 모두에서 skill을 숨길 수 있고, user-invocable-only를 사용하면 모델의 선택 대상에서는 제외하면서 이름으로 호출할 수 있어요. name-only를 사용하면 전체 설명 없이 skill 이름만 표시할 수 있어요.¹⁵⁶

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

• availableModels / enforceAvailableModels (관리형, v2.1.175+): availableModels 허용 목록은 세션에서 선택할 수 있는 모델을 제한해요. enforceAvailableModels: true를 사용하면 허용 목록이 Default 모델에도 적용돼요. Default가 허용되지 않은 모델로 결정되면 허용된 첫 번째 모델로 대체되며, 사용자 또는 프로젝트 설정으로 관리형 availableModels 목록을 더 이상 확장할 수 없어요. 함께 제공된 수정 사항(v2.1.176)은 별칭을 선택했을 때 ANTHROPIC_DEFAULT_*_MODEL을 통해 차단된 모델로 리디렉션할 수 있었던 허점을 막았으며, 이제 /fast는 허용 목록에 없는 모델로 전환되지 않아요.¹⁷² v2.1.187부터는 조직이 /model picker, --model, /model, ANTHROPIC_MODEL 전반에 모델 제한을 직접 적용할 수 있어요. 제한된 모델을 선택하면 “조직 설정에 의해 제한됨”이라는 메시지가 표시돼요.¹⁷⁶
• language (v2.1.176 개선): 응답 언어를 설정하는 기능 외에도 이제 세션 제목이 기본적으로 대화 언어에 맞춰 생성돼요. 제목 언어를 고정하려면 language에 원하는 언어를 설정하세요.¹⁷²
• footerLinksRegexes (v2.1.176): 바닥글 행에 정규식과 일치하는 링크 배지를 표시하며, 사용자 또는 관리형 설정에서 구성할 수 있어요.¹⁷²
• wheelScrollAccelerationEnabled (v2.1.174): 전체 화면 모드에서 마우스 휠 스크롤 가속을 비활성화하려면 false로 설정하세요.¹⁷²

새로운 설정(v2.1.207–v2.1.212):

• vimInsertModeRemaps (v2.1.208): vim 삽입 모드의 사용자 지정 키 재매핑이에요. 대표적인 예는 jj를 Escape에 매핑하는 방식이에요(Vim 모드 참조).¹⁸⁶
• axScreenReader (v2.1.208): 화면 읽기 모드를 계속 활성화해요(화면 읽기 모드 참조).¹⁸⁶
• processWrapper (v2.1.208): Claude Code가 자체적으로 생성하는 모든 프로세스를 래퍼 실행 파일을 통해 실행해요. 기업용 launcher를 위해 만들어졌어요(기업용 Launcher 참조).¹⁸⁶
• autoMode 소스 제한(v2.1.207): 이제 저장소의 .claude/settings.local.json에서는 autoMode 설정을 읽지 않아요. 대신 ~/.claude/settings.json에서 구성하세요. 이 변경으로 복제한 저장소가 auto-mode 설정을 포함해 배포할 수 있었던 경로를 차단했어요.¹⁸⁵

환경 변수 레퍼런스

인증 및 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

모델 설정:

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+)

클라우드 공급자 설정:

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]
CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1             # Include subagent text + thinking in stream-json output; pairs with --forward-subagent-text (v2.1.211+)[^205]
CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION=200    # Per-session WebSearch cap (default 200; v2.1.212+)[^206]
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=200       # Per-session subagent-spawn cap (default 200; /clear resets the budget; v2.1.212+)[^206]

도구 설정:

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
CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=120000       # Threshold before a long MCP tool call moves to the background (default 2 min; v2.1.212+)[^206]
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Slash command context limit

네트워크 및 프록시:

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 및 터미널:

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_DISABLE_MOUSE_CLICKS=1           # Disable mouse click/drag/hover in fullscreen mode; wheel scroll still works (v2.1.195+)[^196]
CLAUDE_ENABLE_STREAM_WATCHDOG=0              # Disable the streaming idle watchdog (on by default for all providers since v2.1.196: aborts+retries after 5 min of silence)[^198]
CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP=1 # Turn off automatic memory-pressure reaping of idle background shell commands (v2.1.193+)[^196]
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1             # Force Session Recap when telemetry disabled (v2.1.108+)[^153]
CLAUDE_AX_SCREEN_READER=1                     # Enable screen reader mode; same as --ax-screen-reader or "axScreenReader": true (v2.1.208+)[^203]
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 exporter 및 민감한 필드 제어:¹⁹⁸

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)
OTEL_LOG_ASSISTANT_RESPONSES=0                # Gate the claude_code.assistant_response log event holding the model's response text (v2.1.193+)
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 요청 span 속성: 이제 LLM 요청 span에서 stop_reason, gen_ai.response.finish_reasons, user_system_prompt를 내보내요. user_system_prompt에는 개인 식별 정보가 포함될 수 있으므로 OTEL_LOG_USER_PROMPTS=1로 활성화해야 해요.¹⁵⁴

v2.1.122+ 이벤트 수준 변경 사항: 이제 api_request 및 api_error 로그 이벤트의 숫자 속성을 문자열이 아닌 숫자로 내보내요. 이 변경은 스키마에 엄격한 타입을 적용하던 하위 OTel collector의 문제를 해결해요. Claude Code가 @-mention을 확인하면 새로운 claude_code.at_mention 로그 이벤트가 발생해요.¹⁵⁴

v2.1.193+ claude_code.assistant_response 로그 이벤트: Claude Code는 OTEL_LOG_ASSISTANT_RESPONSES로 활성화할 경우 모델의 전체 응답 텍스트를 OTel 로그 이벤트로 내보낼 수 있어요. 이 활성화 방식에는 업그레이드할 때 알아야 할 주의점이 있어요. OTEL_LOG_ASSISTANT_RESPONSES를 설정하지 않으면 OTEL_LOG_USER_PROMPTS 설정을 따라가므로, 이미 프롬프트 콘텐츠를 기록하는 배포 환경에서는 업그레이드 후 assistant 응답 콘텐츠도 수신하기 시작해요. 원격 측정에서 프롬프트만 계속 수집하려면 OTEL_LOG_ASSISTANT_RESPONSES=0으로 설정하세요.¹⁷⁹

API / 모델 제어:¹⁹⁸

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+)

엔터프라이즈 / 인증:¹⁹⁸

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)
CLAUDE_CODE_PROCESS_WRAPPER=/path/to/wrapper  # Route all Claude Code self-spawned processes through a wrapper executable; same as the processWrapper setting (v2.1.208+)[^203]

Skill 변수(v2.1.69+):

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

SDK 호출자 식별 정보(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

디버깅:

ANTHROPIC_LOG=debug                             # Enable API request logging

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

작업마다 적합한 model을 선택하면 비용과 품질 모두에 큰 영향을 미쳐요. Claude Code에서는 여러 수준에서 model을 유연하게 전환할 수 있어요.

사용 가능한 Model

Claude Fable 5(2026년 6월 9일): Opus 상위에 새로 추가된 model 등급으로, Anthropic에서 가장 강력하고 지능적인 model이에요. 테스트한 거의 모든 벤치마크에서 최첨단 성능을 보이며 수백만 토큰의 컨텍스트에서도 일관성을 유지하도록 설계됐어요. Fable 5는 일반 사용에 안전하도록 만든 “Mythos급” 최첨단 model이에요. 사이버, 생화학, model 증류 관련 요청에는 Opus 4.8로 대체 처리하는 안전 분류기가 포함돼요(Claude Mythos 5는 승인된 연구자를 위해 이러한 안전장치를 해제한 동일한 model이에요). v2.1.170(2026년 6월 9일)부터 Claude Code에서 선택할 수 있어요. claude update를 실행한 다음 /model fable을 사용하세요. 짧은 별칭이며 /model claude-fable-5와 best 별칭으로도 선택할 수 있어요. 구독 플랜에는 2026년 6월 22일까지 순차적으로 제공돼요. Model ID는 claude-fable-5예요. Fable 5에는 기본으로 1M 컨텍스트 창이 포함되므로 [1m] 접미사가 필요하지 않아요. v2.1.173(2026년 6월 11일)부터 claude-fable-5[1m] model 이름은 자동으로 claude-fable-5로 정규화되며 접미사가 제거돼요. 이 접미사는 1M 사용 시 [1m]이 필요한 Opus와 Sonnet에서만 의미가 있었어요. 최대 출력은 128K예요. 가격은 입력 $10/MTok, 출력 $50/MTok으로 Opus 4.8의 약 2배이므로 일상적인 편집이 아니라 정말 어려운 추론에만 사용하세요. 요청 인터페이스는 Opus 4.8과 같지만 적응형 사고만 지원하고 temperature/top_p/top_k와 budget_tokens는 제거됐어요. 한 가지 차이점은 명시적으로 thinking: {type: "disabled"}를 지정하면 400 응답이 반환된다는 점이에요. 사고 없이 실행하려면 thinking 매개변수를 아예 생략하세요.¹⁹¹

특히 Claude Code에서 Fable 5는 Opus 4.8과 마찬가지로 전체 effort 범위(low/medium/high/xhigh/max, 기본값 high)를 지원해요. Fable 5에서는 사고 기능을 끌 수 없어요. 세션 사고 토글, alwaysThinkingEnabled 설정, MAX_THINKING_TOKENS=0 모두 영향을 주지 않으며 항상 적응형으로 추론해요. 전체 fable 계열 설정 인터페이스는 Opus 설정 항목과 대응해요. ANTHROPIC_DEFAULT_FABLE_MODEL은 fable 별칭이 가리킬 model을 고정하고 Bedrock/Vertex/Foundry에서 유용해요. DISABLE_PROMPT_CACHING_FABLE은 Fable의 프롬프트 캐싱을 끄며, 콘텐츠 기반 자동 대체 처리는 엔터프라이즈 게이트웨이에 적용돼요. Opus 4.8은 여전히 Claude Code의 에이전트형 기본 model이에요(기본 effort는 high이며 가장 어려운 작업에는 /effort xhigh 사용). 최고의 성능이 필요할 때 /model fable로 Fable 5를 의도적으로 선택하세요.¹⁹¹

Opus 4.7(2026년 4월 16일): 이전 세대의 대표 model로 여전히 완전히 사용할 수 있어요. 표준 가격으로 1M 토큰 컨텍스트 창을 제공하며 긴 컨텍스트 할증이 없어요. 최대 출력은 128K이고 적응형 사고만 지원하며 확장 사고는 제거됐어요. 코딩 및 에이전트형 작업의 시작점으로 권장되는 새로운 xhigh effort 수준도 제공해요.¹⁴⁵ 신뢰할 수 있는 지식 기준일은 2026년 1월이며 학습 데이터 기준일도 2026년 1월이에요. Model ID는 claude-opus-4-7이에요. 가격은 Opus 4.6과 같은 MTok당 $5/$25이며, 5분 캐시 쓰기는 $6.25, 1시간 캐시 쓰기는 $10, 캐시 읽기는 $0.50예요.¹⁴⁴ Opus 4.7은 SWE-Bench에서 Opus 4.6보다 실제 운영 작업을 3배 더 많이 해결하고, CursorBench에서 70%를 기록하며(4.6은 58%), Anthropic의 93개 작업 내부 코딩 벤치마크에서 해결률을 13% 높여요.¹⁴⁴ 새로운 tokenizer를 사용하므로 같은 텍스트라도 토큰 수가 약 1배에서 1.35배로 늘어날 수 있어요. max_tokens 여유와 압축 실행 기준을 높이세요.¹⁴⁵ Vision은 최대 2,576 px / 3.75 MP 이미지와 1:1 픽셀 좌표를 지원해요.¹⁴⁵

Opus 4.7 코딩 벤치마크(2026년 4월):¹⁵¹

Opus 4.7은 널리 인용되는 GPT-5-Codex 기준치보다 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% 대 75.1%), 둘 다 Opus 4.7(69.4%)보다 높아요. 벤치마크 선두는 계속 바뀌므로 여러 분기에 걸친 결정을 내리기 전에 공급업체 페이지를 확인하세요.

플랜별 기본 model(Claude Code):¹⁴⁷

Opus 4.7에는 Claude Code v2.1.111 이상이 필요해요. claude update를 실행해 업그레이드하세요.¹⁴⁷ Bedrock, Vertex, Foundry에서는 기본적으로 opus 별칭이 아니라 명시적인 전체 model 이름이나 ANTHROPIC_DEFAULT_OPUS_MODEL 고정을 통해 Opus 4.7을 제공해요.¹⁴⁷

Opus 4.7의 Messages API 주요 변경 사항(호출자에게 노출):¹⁴⁵

• 확장 사고의 budget_tokens가 제거됐어요. 대신 thinking: {type: "adaptive"}를 사용하세요. 적응형 사고는 기본적으로 꺼져 있으며 thinking 필드가 없는 요청은 사고 없이 실행돼요.
• temperature, top_p, top_k를 기본값이 아닌 값으로 설정하면 HTTP 400이 반환돼요. 이 매개변수는 생략하고 프롬프트로 model의 동작을 유도하세요.
• 사고 콘텐츠는 기본적으로 응답에서 생략돼요. 표시되는 추론을 복원하려면 thinking.display: "summarized"를 설정하세요. 제품에서 사고 과정을 사용자에게 스트리밍한다면 이 설정이 필요해요.

작업 예산(beta header task-budgets-2026-03-13)을 사용하면 output_config.task_budget을 통해 전체 에이전트형 루프의 목표 토큰 수를 model에 안내할 수 있어요. 최솟값은 20K 토큰이에요.¹⁴⁵

Opus 4.6(레거시): 1M 컨텍스트와 최대 128K 출력으로 claude-opus-4-6에서 계속 사용할 수 있어요. 더 나은 에이전트형 코딩을 위해 Opus 4.7로 이전하는 방안을 고려하세요. Opus 4.6은 2026년 2월 5일에 처음 출시됐어요.⁷⁹¹⁴⁴ v2.1.117(2026년 4월 22일)부터 Pro 및 Max 구독자의 Opus 4.6과 Sonnet 4.6 기본 effort가 high로 변경됐어요(이전에는 medium). Opus 4.7은 계속 xhigh를 사용해요. 이 변경으로 4월 23일 사후 분석에 기록된 3월 4일에서 4월 7일 사이의 effort 하향 이후 지능 수준이 복원됐어요.¹⁵²¹⁵³

Sonnet 5(2026년 6월 30일): 현재 Sonnet 등급으로, “속도와 지능의 최상의 조합”을 제공해요. Anthropic에 따르면 성능은 Opus 4.8에 가깝지만 가격은 더 낮고, 에이전트형 추론, 도구 사용, 코딩, 지식 작업에서 Sonnet 4.6보다 크게 향상됐어요. 바람직하지 않은 행동의 전체 비율도 낮아요. 다만 사이버 보안 능력은 Opus model보다 훨씬 약하며, 이러한 안전성 절충 덕분에 수출 통제 제한 없이 출시할 수 있었어요. Model ID는 claude-sonnet-5이며 날짜가 없는 고정 snapshot이에요. 1M 토큰 컨텍스트 창과 최대 128K 출력을 지원하고, output-300k-2026-03-24 beta header를 사용하면 Batches API에서 최대 300K까지 출력할 수 있어요. 적응형 사고만 지원해요. 신뢰할 수 있는 지식 기준일은 2026년 1월이에요. 가격은 입력/출력 MTok당 $3/$15이며 2026년 8월 31일까지 출시 특가인 $2/$10가 적용돼요. Opus 4.8의 $5/$25보다 약 40% 저렴해요. Claude Code에서 Sonnet 5의 effort 매개변수 기본값은 high예요. 변경하려면 값을 명시적으로 설정하세요. /model sonnet 또는 /model claude-sonnet-5로 선택할 수 있어요.¹⁸⁰ v2.1.197(2026년 6월 30일)부터 Sonnet 5는 Claude Code의 새 세션 기본 model이에요. 별도 설정 없이 사용하는 기본 선택지로서 Opus 4.8을 대체했지만 Opus도 계속 자유롭게 선택할 수 있어요.¹⁸¹

Sonnet 4.6(2026년 2월 17일, 현재 Sonnet 5로 대체됨): 균형 잡힌 model로, claude.ai와 Claude Cowork 전반에서 Sonnet 4.5를 기본 model로 대체했어요.⁹³ 가격은 Sonnet 4.5와 같은 MTok당 $3/$15예요. 더 적은 토큰을 사용하면서 에이전트형 검색 성능이 향상됐어요. 확장 사고와 적응형 사고, 1M 토큰 컨텍스트 창(beta)을 지원해요. 최대 출력은 64K이며 v2.1.77의 상한은 128K예요.¹¹⁹ 지식 기준일은 2025년 8월(신뢰 가능), 학습 데이터 기준일은 2026년 1월이에요. Model ID는 claude-sonnet-4-6이에요.

Claude Mythos Preview(2026년 4월 7일): Project Glasswing을 통해 제공되는 방어적 사이버 보안 작업용 연구 preview 최첨단 model이에요.¹³⁹ 초대받은 사용자만 이용할 수 있으며 일반적으로 제공되지 않아요. Anthropic는 사이버 분야에서 Opus 4.7의 성능을 Mythos보다 의도적으로 낮게 제한했다고 설명해요. 이는 안전성을 위한 절충이에요. 더 높은 수준의 접근 권한이 필요한 합법적인 보안 연구자를 위해 https://claude.com/form/cyber-use-case에서 Cyber Verification Program도 운영하고 있어요.¹⁴⁶

이러한 가격 차이가 중요한 이유: 일반적인 코딩 세션에서는 입력 토큰 50K~200K와 출력 토큰 10K~50K를 사용해요. Haiku를 사용하면 세션당 $0.10~$0.45예요. 같은 세션을 Opus로 실행하면 5배 높은 $0.50~$2.25가 들어요. Opus는 정말 어려운 문제를 위해 남겨 두세요.¹

각 Model을 사용해야 할 때

Haiku: 탐색, 간단한 파일 검색, 짧은 질문을 수행하는 subagents에 사용하세요. Opus보다 약 5배 저렴하고 응답도 빨라요. 깊은 추론이 필요하지 않은 백그라운드 작업에 적합해요.

Sonnet: 비용이 중요한 일상적인 개발 작업의 주력 model이에요. 기능 구현, 버그 수정, 테스트 작성, 코드 리뷰 등 대부분의 코딩 작업을 처리해요. Sonnet 4.6은 Sonnet 4.5보다 에이전트형 검색과 토큰 효율이 향상됐으며, 적응형 사고와 표준 가격의 1M 컨텍스트 창을 지원해요.⁹³ Opus 4.7이 출시된 2026년 4월 16일 기준으로 Claude Code은 Max와 Team Premium 플랜에서만 Opus를 기본값으로 사용해요. Pro, Team Standard, Enterprise, API 계정은 Sonnet 4.6을 기본값으로 유지하다가 2026년 4월 23일에 Enterprise와 API가 Opus 4.7로 전환돼요.¹⁴⁷ 더 저렴한 토큰, 짧은 지연 시간, 경제적인 subagent 운영이 필요할 때 Sonnet을 사용하세요.

Opus: 2026년 4월 16일 기준 대표 등급이며 Max와 Team Premium 플랜의 기본 model이에요.¹⁴⁴¹⁴⁷ 높은 비용의 추론은 효과가 큰 작업에만 사용하세요. 아키텍처 결정, 까다로운 디버깅, 복잡한 시스템 이해, 보안 분석, 장기 에이전트형 작업에 적합해요. Opus 4.7은 SWE-Bench에서 Opus 4.6보다 실제 운영 작업을 3배 더 많이 해결하고, CursorBench에서 70%(4.6은 58%)를 기록하며, 93개 작업으로 구성된 내부 코딩 벤치마크에서 해결률을 13% 높여요.¹⁴⁴ Claude Code은 Opus 4.7에서 기본적으로 xhigh effort를 사용하며 /effort로 조정할 수 있어요(v2.1.111 이상).¹⁴⁶¹⁴⁷ Max 구독자는 --enable-auto-mode 없이 Anthropic API를 통해 Opus 4.7의 Auto Mode를 사용할 수 있어요. 다른 플랜과 공급자는 플랜별 및 관리자 제어 방식에 따라 제공 여부가 달라요.¹⁴⁶ 표준 가격으로 1M 컨텍스트를 제공하며 긴 컨텍스트 할증은 없어요. 알아 둘 만한 동작 변경 사항: Opus 4.7은 지시를 더 문자 그대로 따르고, 작업의 복잡도에 맞춰 응답 길이를 조정하며, 기본적으로 더 적은 subagents를 실행해요. 또한 동조적인 표현을 줄이고 더 직접적인 어조를 사용해요. 중간 진행 상황 메시지나 재확인 동작을 강제하는 보조 문구가 프롬프트에 있다면 이를 제거해 보세요.¹⁴⁵

Opusplan: 추론 품질이 가장 중요한 계획에는 Opus를 사용하고, 속도가 중요한 실행에는 Sonnet을 사용하는 혼합 모드예요. 최상의 계획이 필요하지만 개별 편집마다 Opus 수준의 추론이 필요하지 않은 복잡한 리팩터링에 적합해요.

Model 전환

세션 중:

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

시작할 때:

claude --model opus

환경을 통해:

export ANTHROPIC_MODEL=opus

settings.json에서:

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

특정 subagents에:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

대체 model 체인(v2.1.166 이상): fallbackModel 설정에는 기본 model이 과부하 상태이거나 사용할 수 없을 때 순서대로 시도할 대체 model을 최대 3개까지 지정할 수 있어요. 이전에는 세션 중간 전환에만 사용되던 --fallback-model 플래그가 이제 시작 시점부터 대화형 세션에도 적용돼요.¹⁹³

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

API에서 재시도할 수 없는 예기치 않은 오류를 반환하면 Claude Code은 실패를 표시하기 전에 대체 model에서 해당 turn을 한 번 더 시도해요. 따라서 기본 model의 일시적인 문제로 turn이 사라지지 않고 자연스럽게 성능을 낮춰 계속 진행할 수 있어요.¹⁹³

v2.1.178부터는 압축도 대체 체인을 따라요. 압축 도중 기본 model이 과부하 상태이거나 사용할 수 없으면 turn을 실패 처리하지 않고 설정된 fallbackModel/--fallback-model 체인으로 압축 단계를 대체 실행해요. 따라서 장시간 자율 실행 중 복구 가능한 압축 작업이 일시적인 model 오류 때문에 세션을 중단시키던 문제가 해결돼요.¹⁷³

확장 컨텍스트

대규모 코드베이스나 긴 세션에는 1M 토큰 컨텍스트를 활성화하세요.

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

또는 세션 내에서:

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

Opus 4.7, Opus 4.6, Sonnet 4.6은 모두 표준 가격으로 전체 1M 토큰 컨텍스트 창을 제공하며 긴 컨텍스트 할증이 없어요.¹⁴⁸ 900K 토큰 요청에도 9K 토큰 요청과 동일한 토큰당 요금이 적용돼요. 프롬프트 캐싱 및 batch 처리 할인도 전체 컨텍스트 창에 표준 요율로 적용돼요.

Max, Team, Enterprise 구독에서는 Opus의 1M 컨텍스트가 자동으로 포함되므로 [1m] 접미사가 필요하지 않아요. v2.1.75(2026년 3월 13일)부터 기본적으로 활성화됐어요.¹¹⁷¹⁴⁷ Pro에서는 추가 사용량을 통해 1M 컨텍스트를 이용할 수 있어요. API 및 사용량 기반 결제 사용자는 표준 토큰당 요금으로 전체 1M 컨텍스트를 이용할 수 있어요.¹⁴⁷

Model 선택기에서 1M 컨텍스트 변형을 숨기려면 CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정하세요.

현재 Model 확인

> /status

이 명령은 현재 model, 계정 정보, 적용된 설정, 기타 세션 상태를 표시해요.

Model 선택기 레이블(v2.1.51 이상): 이제 /model 선택기는 고정된 버전에 원시 model ID 대신 사람이 읽기 쉬운 레이블(예: “Sonnet 4.6”)을 표시하며 최신 버전을 사용할 수 있을 때 업그레이드 안내도 제공해요.⁹⁸

Fast Mode(v2.1.36 이상)

Fast mode는 동일한 model에서 훨씬 빠르게 출력해요. 더 저렴한 model로 전환하는 기능이 아니에요. 세션 중 /fast로 켜거나 끌 수 있어요.⁸⁶

> /fast            # Toggle fast mode on/off

가격(Opus 4.6 fast mode):

Fast mode는 research preview이며 Opus 4.6에서만 사용할 수 있어요. 기본 요금의 6배로 약 2.5배 빠른 출력을 제공해요.¹⁴⁹ 다른 model을 사용 중이었다면 /fast를 활성화할 때 세션이 자동으로 Opus 4.6으로 전환돼요. /fast를 비활성화해도 /model로 전환할 때까지 Opus 4.6이 유지돼요. Fast mode는 Opus 4.7, Sonnet, Haiku 또는 Bedrock/Vertex/Foundry에서 사용할 수 없어요. 추가 사용량을 활성화해야 하며 Team/Enterprise에서는 관리자가 활성화해야 해요.

Fast mode를 사용해야 할 때: - 지연 시간이 병목인 소규모 변경을 빠르게 반복할 때 - 비용보다 속도가 중요한 테스트, boilerplate, 반복 코드를 생성할 때 - 비슷한 작업 목록을 순차적으로 처리할 때

Fast mode를 사용하지 말아야 할 때: - 장시간 실행되는 에이전트형 작업(6배 요금이 빠르게 누적돼요) - 백그라운드 subagent 작업(출력을 기다리는 사람이 없어요) - 예산이 중요한 세션

Opus 4.6 fast mode에는 전체 1M 컨텍스트 창이 포함돼요(v2.1.50 이상). 전체 1M 컨텍스트에 동일한 Fast mode 요금이 적용되며 추가적인 긴 컨텍스트 할증은 없어요.⁹⁶¹⁴⁹

전문가 팁: Fast mode는 opusplan과 함께 사용할 수 없어요. opusplan은 이미 Opus와 Sonnet을 혼합하고 Fast mode는 Opus 4.6에만 영향을 주기 때문이에요. 비용보다 지연 시간이 중요할 때 Fast mode를 직접 사용하고, 자율 작업이나 batch 작업에서는 비활성화하세요. /fast에는 추가 사용량이 필요하며 Team/Enterprise 관리자는 먼저 활성화해야 할 수 있어요(v2.1.37 수정 사항).⁸⁶¹⁴⁹

Effort 제어(v2.1.111 이상, Opus 4.7)

Opus 4.7에는 속도와 지능의 균형을 조정하는 새로운 effort 조절 기능이 도입됐어요. 세션 중 /effort를 사용하세요.

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

이제 Claude Code은 Opus 4.7의 effort 기본값으로 xhigh를 사용해요. xhigh는 Opus 4.7에서만 사용할 수 있으며 다른 model은 high로 대체돼요. Claude Managed Agents는 effort를 자동으로 처리하며 effort 매개변수는 Messages API의 개념이에요.¹⁴⁵¹⁴⁶

Max의 Auto Mode(v2.1.111 이상)

--dangerously-skip-permissions를 더 안전하게 대체하는 Auto Mode는 Max 구독자가 --enable-auto-mode 없이 Anthropic API를 통해 Opus 4.7에서 사용할 수 있어요.¹⁴⁶ Sonnet 4.6 분류기가 각 작업을 실행 전에 검토하여 의도와 일치하는지, 안전한지 확인해요. 참고(v2.1.111 이상): --enable-auto-mode 플래그는 제거됐어요. 대신 --permission-mode auto를 사용해 Auto Mode로 세션을 시작하세요. Auto Mode는 Pro에서 사용할 수 없어요. Anthropic의 권한 모드 문서에 따르면 Anthropic API에서는 기본적으로 바로 사용할 수 있어요. Bedrock/Vertex/Foundry(v2.1.158 이상): 해당 게이트웨이의 Opus 4.7 및 Opus 4.8에서는 CLAUDE_CODE_ENABLE_AUTO_MODE=1을 설정해 Auto Mode를 선택적으로 활성화할 수 있게 됐어요.¹⁹⁶ v2.1.207부터는 이 선택적 활성화 절차가 사라졌어요. 이제 CLAUDE_CODE_ENABLE_AUTO_MODE 없이도 AWS Bedrock, Google Vertex AI, Microsoft Foundry에서 Auto Mode가 작동해요. 비활성화하려는 관리자는 관리형 설정 disableAutoMode를 사용하면 돼요. 같은 릴리스부터 Bedrock, Vertex AI, AWS의 Claude Platform은 기본적으로 Claude Opus 4.8을 사용해요. 또한 저장소의 .claude/settings.local.json에서 autoMode 설정을 더 이상 읽지 않으므로 auto-mode 규칙은 ~/.claude/settings.json에서 설정하세요.¹⁸⁵

기본값을 유지하면서 규칙 맞춤 설정하기(v2.1.118 이상). 이전 버전에서는 autoMode.allow, autoMode.soft_deny, autoMode.environment가 양자택일 방식으로 작동했어요. 자체 목록을 정의하면 기본 안전 규칙을 잃었어요. $defaults sentinel이 이 문제를 해결해요. 지정한 정확한 위치에서 기본 제공 목록으로 확장되므로 기본 규칙 전후에 맞춤 규칙을 추가할 수 있어요.¹⁵²

// .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
    ]
  }
}

“다시 묻지 않기” 선택 사항(v2.1.118 이상). 이제 Auto Mode 활성화 안내에 “다시 묻지 않기” 옵션이 표시돼요. 자주 사용하는 사용자는 플래그를 scripting하지 않고도 설명 안내를 숨길 수 있어요.¹⁵²

파괴적 명령 보호 장치(v2.1.183). 이제 Auto mode는 사용자가 세션에서 명시적으로 요청하지 않은 복구 불가능한 명령을 강제로 차단해요. 로컬 작업 폐기를 요청하지 않은 상태에서의 파괴적인 git 작업(git reset --hard, git checkout -- ., git clean -fd, git stash drop), 해당 세션에서 agent가 만들지 않은 commit에 대한 git commit --amend, 특정 stack을 지목하지 않은 인프라 해체(terraform destroy, pulumi destroy, cdk destroy)가 여기에 해당해요. 이 기능은 작업을 조용히 잃거나 환경을 해체하는 명령에 대해 분류기가 미칠 수 있는 피해 범위를 줄여요. agent는 이런 명령을 계속 실행할 수 있지만 스스로 판단해서가 아니라 사용자가 명시적으로 지시했을 때만 가능해요.¹⁷⁴

모든 shell 명령 분류하기(v2.1.193). 기본적으로 auto-mode 분류기는 임의 코드 실행 패턴과 일치하는 shell 명령만 검토하며 일상적인 명령은 건너뛰어요. 새로운 autoMode.classifyAllShell 설정은 모든 Bash/PowerShell 명령을 분류기로 전달해요. 모든 shell 호출을 검토하고 싶을 때 약간의 지연 시간을 감수하고 더 촘촘한 안전망을 얻을 수 있어요. 같은 릴리스에서는 transcript, 거부 알림, /permissions의 최근 거부 내역에 auto-mode 거부 사유도 표시해요. 이제 명령이 차단되면 차단된 이유를 알 수 있어요.¹⁷⁹

추가된 3가지 강화 규칙(v2.1.205). 이제 Auto mode는 세션 transcript 파일 변조를 차단해요. 감사 기록 자체는 agent가 건드릴 수 없어요. 또한 컨텍스트에서 확인할 수 없는 변수를 대상으로 rm -rf를 실행하기 전에 사용자에게 확인해요. 이를 통해 알 수 없는 $DIR에 rm -rf $DIR을 실행하는 유형의 사고를 방지해요. 백그라운드 작업 알림에는 사람의 입력이 없었다는 사실도 명시돼요. 따라서 transcript 안에 조작된 “사용자가 승인함” 문구가 있더라도 실제 승인으로 둔갑해 실행될 수 없어요.¹⁸³ 세 번째 규칙은 꼭 이해해야 할 프롬프트 주입 방어예요. 승인은 승인 채널을 통해 들어와야 하며 이제 harness가 이 전제를 명시해요.

명령 치환으로도 재앙을 숨길 수 없음(v2.1.208). 이제 rm -rf ~와 같은 치명적인 삭제 명령을 $(...), backticks, process substitution(<(...)) 안에 숨겨도 확인 메시지가 표시돼요. --dangerously-skip-permissions 및 auto mode에서도 확인해요. 파괴적인 명령을 치환 구문으로 감싸도 더 이상 안전망을 우회할 수 없어요.¹⁸⁶

Auto-mode 상태 초기화: claude auto-mode reset(v2.1.212). 터미널에서 auto-mode 상태를 초기화하는 새로운 하위 명령이 추가됐어요. 확인 메시지를 건너뛰려면 --yes를 전달하세요.¹⁸⁹

claude auto-mode reset          # Confirmation prompt
claude auto-mode reset --yes    # Skip confirmation (scripts)

v2.1.105~v2.1.114의 새로운 명령¹⁴⁶¹⁵⁰

세션 요약(v2.1.108 이상)

일시 중지한 세션으로 돌아왔을 때 컨텍스트를 보여 주는 새로운 세션 수준 기능이에요. 기본적으로 활성화되며 /config 또는 CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0을 통해 비활성화할 수 있어요. Model은 Skill 도구를 통해 기본 slash commands(/init, /review, /security-review)도 호출할 수 있어요. 이를 통해 subagent/skill 패턴이 확장돼요.¹⁴⁶

Push 알림(v2.1.110 이상)

Remote Control에서 “Claude가 결정할 때 Push”를 활성화하면 Claude가 새로운 push 알림 도구를 통해 자체 판단으로 mobile push 알림을 보낼 수 있어요. 기존 Remote Control mobile/web 인터페이스와 함께 작동해요.¹⁴⁶ 이제 /context, /exit, /reload-plugins도 Remote Control client에서 작동해요.

Windows PowerShell 도구(v2.1.111 이상, 순차 출시)

Claude Code은 Windows용 기본 PowerShell 도구를 순차적으로 출시하고 있어요. Linux/macOS에서는 CLAUDE_CODE_USE_POWERSHELL_TOOL=1로 활성화하세요(PATH에 pwsh가 있어야 해요). Windows에서는 출시 기간에 같은 변수를 사용해 기능 사용 여부를 선택할 수 있어요.¹⁴⁶

권한 모드 자동 승인(v2.1.119 이상). 이제 PowerShell 도구 명령도 Bash 명령과 같은 방식으로 권한 모드에서 자동 승인을 받을 수 있어요. PowerShell(Get-*:*) 같은 허용 규칙과 기존 패턴 문법을 사용하면 읽기 전용 작업의 확인 메시지를 건너뛸 수 있어 Linux/macOS에서 제공되던 운영 편의성을 팀에서 동일하게 누릴 수 있어요.¹⁵²

권한 요청 감소: 읽기 전용 Bash(v2.1.111 이상)

glob 인수가 있는 읽기 전용 Bash 패턴(예: ls *.ts, cat src/*.md)과 cd <project-dir> &&로 시작하는 명령은 더 이상 권한 확인 메시지를 표시하지 않아요.¹⁴⁶ /less-permission-prompts와 함께 사용하면 일상적인 작업 흐름에서 중단되는 횟수를 크게 줄일 수 있어요.

분산 추적(v2.1.110 이상)

이제 SDK 및 headless 세션은 환경에서 TRACEPARENT와 TRACESTATE를 읽어 Claude Code 실행을 분산 trace에 연결해요. 디버깅을 위해 전체 API 요청 및 응답 본문을 OpenTelemetry log event로 내보내려면 OTEL_LOG_RAW_API_BODIES=1(v2.1.111 이상)과 함께 사용하세요.¹⁴⁶

기본 Binary 배포(v2.1.113 이상)¹⁵⁰

v2.1.113에서는 CLI의 실행 방식이 변경됐어요. 이제 claude는 함께 포함된 JavaScript를 실행하는 대신 플랫폼별 선택적 dependency를 통해 기본 Claude Code binary를 생성해요. 설치 및 업데이트 명령은 동일하게 유지되며 팀에서 배포 script를 변경할 필요가 없어요.

프롬프트 Editor 단축키(v2.1.113 이상)¹⁵⁰

프롬프트 editor에는 여러 줄 입력을 위한 readline 방식 탐색과 fullscreen viewport 스크롤 기능이 추가됐어요.

이 기능은 기본적으로 활성화돼요. keybinding 설정은 필요하지 않아요.

Subagent 정지 Timeout(v2.1.113 이상)¹⁵⁰

이제 stream 도중 멈춘 subagents는 조용히 무한정 대기하는 대신 10분 후 명확한 오류와 함께 실패해요. Streaming API의 멈춘 process를 더 폭넓게 감지하려면 CLAUDE_STREAM_IDLE_TIMEOUT_MS(v2.1.84 이상)와 함께 사용하세요.

v2.1.114 안정성 수정¹⁵⁰

v2.1.114(2026년 4월 18일)에는 단일 수정 사항이 포함돼요. agent-teams의 teammate가 도구 권한을 요청할 때 권한 대화 상자가 비정상 종료될 수 있던 문제를 해결했어요. Agent Teams를 사용한다면 업그레이드하세요.

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메가와트가 넘는 새로운 처리 용량(NVIDIA GPU 220,000개 이상)”을 확보하는 계약이에요.¹⁵⁷

API 토큰 요금(2026년 4월)¹¹⁴⁴

API 기준으로 요금이 청구되는 사용자의 토큰 100만 개당 가격은 다음과 같아요.

1M 컨텍스트 요금(2026년 4월): Opus 4.7, Opus 4.6, Sonnet 4.6, Mythos Preview는 모두 표준 토큰 100만 개당 요금으로 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% 줄일 수 있어요.

Batch API는 야간 테스트 모음처럼 긴급하지 않은 작업을 24시간 이내에 처리하며 50% 할인을 제공해요.

여러 계정 정책⁵²

Claude 계정을 여러 개 보유할 수 있나요? 네, 정당한 사용 목적이라면 가능해요. Anthropic은 서로 다른 목적으로 사용하는 여러 계정을 명시적으로 허용해요.

허용되는 경우:

기술적 제한: - 동일한 전화번호로 최대 3개 계정을 인증할 수 있어요 - 동일한 IP 또는 네트워크에서 여러 유료 구독을 이용하는 기능을 명시적으로 지원해요 - 각 계정은 완전히 분리되며 계정 간 채팅이나 프로젝트 이전은 지원하지 않아요

금지되는 행위(이용 정책 기준): - 이용 정지 후 정지를 회피하려고 계정을 만드는 행위 - 적발을 피하려고 여러 계정에서 악의적인 활동을 조직하는 행위 - 여러 계정을 이용해 사용량 제한이나 무료 요금제 크레딧을 우회하는 행위

실제 사례: 2026년 1월, 고급 사용자 Jeffrey Emanuel(@doodlestein)이 보유한 Max 계정 22개가 자동으로 표시되어 일시적으로 이용 정지되었어요. Anthropic 직원 Thariq(@trq212)은 정당한 사용임을 확인한 뒤 4시간 안에 문제를 해결했어요. 업무와 개인 프로젝트 모두에서 여러 계정으로 Claude Code을 폭넓게 사용한다면 서비스의 설계 목적에 정확히 부합해요. 다만 시스템을 악용하려고 해서는 안 돼요.

확실하지 않다면: Anthropic 지원팀에 문의해 사용 중인 구성이 허용되는지 서면으로 확인하세요.

비용에 영향을 주는 요소

실제 비용 예시

비용 절감 요령: 탐색용 subagents에는 Haiku를, 구현에는 Sonnet을 사용하면 모든 작업에 Sonnet을 사용할 때보다 일반적으로 비용을 40~50% 줄일 수 있어요.

팀 비용 관리

팀 규모별 권장 TPM/RPM:

숨겨진 도구 비용

토큰별 요금 외에도 일부 도구에는 별도 비용이 부과돼요.⁹

에이전트 반복 작업에서는 이런 비용이 누적돼요. Bash를 사용하는 100회 반복 디버깅 과정에서는 추가 사용량만으로 입력 토큰이 약 24,500개 더 들어요.

비용 절감 전략

1. subagents에 Haiku 사용: 대부분의 탐색에는 Sonnet이 필요하지 않아요
2. 프롬프트 캐싱 활성화: 기본적으로 활성화되지만 비활성화되지 않았는지 확인하세요
3. 최대 턴 수 설정: claude --max-turns 5로 대화가 끝없이 이어지는 일을 방지하세요
4. 탐색에는 계획 모드 사용: 실행하지 않으므로 의도치 않은 고비용 작업을 피할 수 있어요
5. 미리 압축: 컨텍스트가 작을수록 토큰이 적게 들어요
6. 출력 제한: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
7. 긴급하지 않은 작업에는 Batch API 사용: 입력 및 출력 토큰 모두 50% 할인돼요

사용량 모니터링

• Claude Console: platform.claude.com(Admin 또는 Billing 역할 필요)
• 워크스페이스 제한: 워크스페이스별 지출 한도를 설정하세요
• Bedrock/Vertex: 각 클라우드의 비용 모니터링 기능을 사용하세요
• LiteLLM: 타사 제공업체를 이용하면서 사용자별 사용량을 자세히 추적할 때 사용하세요

백그라운드 토큰 사용량

일부 작업은 백그라운드에서 토큰을 사용해요. - /resume을 위한 대화 요약 - /cost 및 /status 명령 - 자동 압축

일반적으로 세션당 $0.04 미만이에요.

Claude Code 분석 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

경험 법칙: Max와 Team Premium에서는 Opus 4.7이 기본이에요. Pro/Team Standard/Enterprise/API에서는 Sonnet 4.6이 기본이에요(Enterprise + Anthropic API는 2026년 4월 23일에 Opus 4.7로 전환돼요).¹⁴⁷ subagents에는 Haiku를 사용하세요. Sonnet의 답변이 피상적으로 느껴지면 Opus로 전환하세요. Agent teams(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 adaptive thinking: Opus 4.6은 문제의 복잡도에 따라 thinking 깊이를 자동으로 조절해요. 대부분의 작업에서는 thinking 예산을 명시적으로 제어할 필요가 없어요. Opus는 어려운 문제에서는 thinking을 늘리고 간단한 문제에서는 빠르게 응답해요. 더 깊이 분석하도록 강제하려는 경우, 수동 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 Teams, Subagents, 병렬 세션 중 무엇을 사용해야 하나요?

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)을 사용하며, 더 저렴한 모델로 전환하지 않아요.

권한 시스템은 어떻게 작동하나요?

Claude Code의 권한 시스템은 실행할 수 있는 작업을 세밀하게 제어합니다. 보안과 효율적인 워크플로를 위해 반드시 이해해야 하는 시스템입니다. 조직 전체에 권한을 적용하는 관리형 설정은 Enterprise 배포도 참고하세요.

권한 단계

읽기 전용 도구(자동 승인): - Read - 파일 내용 읽기 - Glob - 패턴으로 파일 찾기 - Grep - 파일 내용 검색하기 - WebSearch - 웹 검색하기 - LSP - 코드 인텔리전스(정의로 이동, 참조 찾기, 마우스로 가리켜 문서 보기)¹⁸

LSP 도구 기능(v2.0.74 이상): LSP 도구는 IDE와 유사한 코드 인텔리전스를 제공합니다. - 정의로 이동: 기호가 정의된 위치로 이동합니다 - 참조 찾기: 코드베이스 전체에서 기호가 사용된 모든 위치를 나열합니다 - 마우스로 가리켜 문서 보기: 모든 기호의 타입 정보와 문서를 확인합니다 - LSP를 지원하는 TypeScript, Python, Go, Rust 등의 언어에서 작동합니다 - 언어 서버를 사용할 수 있어야 합니다(일반적으로 도구 체인과 함께 설치됨)

수정 도구(승인 필요): - Edit - 기존 파일 수정하기 - Write - 새 파일 만들기 - Bash - 셸 명령 실행하기 - WebFetch - URL 콘텐츠 가져오기 - NotebookEdit - Jupyter 노트북 수정하기

수정 도구를 처음 실행하면 Claude Code가 승인을 요청합니다. 별도로 설정하지 않는 한 승인 상태는 세션이 끝날 때까지 유지됩니다.

권한 모드

v2.1.200부터 default 모드는 “수동”으로 표시됩니다. CLI, --help, VS Code, JetBrains에서 이름이 변경되었지만 설정값은 바뀌지 않았으므로 "defaultMode": "default"는 계속 작동하며, 이제 --permission-mode manual / "defaultMode": "manual"도 별칭으로 사용할 수 있습니다. 각 도구를 처음 사용할 때 승인을 요청하는 동작은 동일합니다. 실제로는 수동 승인 모드인데도 “기본적으로 선택되는 모드”처럼 읽히던 이름만 바로잡은 것입니다. 같은 릴리스부터 AskUserQuestion 대화 상자는 더 이상 기본적으로 자동 진행되지 않습니다. 이제 질문을 한 subagent는 제한 시간이 지나면 계속 진행하지 않고 사용자의 답변을 기다리며, 유휴 제한 시간을 다시 사용하려면 /config에서 설정해야 합니다.

이제 acceptEdits에서도 코드 실행 설정 파일은 승인을 요청합니다(v2.1.160). acceptEdits는 일반적인 편집을 자동 승인하지만, v2.1.160부터는 명령이 사용자 모르게 실행되도록 만들 수 있는 파일을 쓰기 전에 멈추고 승인을 요청합니다. 여기에는 셸 시작 파일(.zshenv, .zlogin, .bash_login), ~/.config/git/, 빌드 도구 설정(.npmrc, .yarnrc*, bunfig.toml, .bazelrc, .pre-commit-config.yaml, .devcontainer/ 등)이 포함됩니다. 이런 파일을 편집하면 다음 셸 실행, 설치 또는 커밋이 코드 실행 경로로 바뀔 수 있기 때문입니다. 따라서 다른 편집은 그대로 허용하는 신뢰할 수 있는 프로젝트 모드에서도 이 파일에는 명시적인 승인 절차가 적용됩니다. 이는 기존 .claude/, .git/, .vscode/ 쓰기 보호와 같은 위협 모델을 “편집이 실행으로 이어지는” 더 넓은 범위의 파일로 확장한 것입니다.¹⁹⁵

자동 모드(v2.1.85 이상): --dangerously-skip-permissions를 대신하는 더 안전한 옵션입니다. 별도의 분류기 모델(Sonnet 4.6)이 실행 전에 각 작업을 검토하여 사용자의 의도와 일치하고 안전한지 확인합니다.¹²⁴

작동 방식: - 작업 디렉터리에서 이루어지는 읽기 전용 작업과 파일 편집은 자동 승인됩니다 - 사용자 지정 허용 및 거부 규칙이 먼저 적용됩니다 - 나머지는 모두 분류기가 평가합니다 - 차단되면 Claude이 자동으로 다른 방법을 시도합니다

기본적으로 자동 차단되는 작업: curl | bash, main으로 강제 푸시, 프로덕션 배포 및 마이그레이션, 대규모 클라우드 삭제, IAM 및 권한 변경, 민감한 데이터의 외부 전송.¹²⁵

회로 차단기: 작업이 연속 3회 또는 한 세션에서 총 20회 차단되면 일시 중지하고 수동 승인 방식으로 돌아갑니다.¹²⁵

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

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

제공 대상: Team 플랜 사용자에게 먼저 제공되며 이후 Enterprise와 API에도 제공됩니다. Sonnet 4.6 또는 Opus 4.6이 필요합니다.¹²⁴

YOLO 모드(v2.0.68 이상): 안전성 분류기 없이 완전히 자율적으로 실행하려면 --dangerously-skip-permissions 플래그를 사용하세요. 이 플래그는 파일 편집, bash 명령, 모든 도구 호출을 전부 승인합니다. “위험”이라는 표현은 의도적으로 사용되었습니다. 대부분의 사용 사례에는 자동 모드가 권장됩니다.⁵⁴

claude --dangerously-skip-permissions

CLI에서 모드 설정:

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

세션 중 전환:

Shift+Tab  # Cycles through modes

settings.json에서 설정:

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

권한 규칙 문법

세분화된 규칙으로 특정 작업을 제어할 수 있습니다. 규칙은 순서대로 평가되며 처음 일치하는 규칙이 적용됩니다.

Bash 명령 패턴:

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

별표는 접두사 일치를 제공합니다. Bash(npm run test:*)는 npm run test, npm run test:unit, npm run test:integration을 허용합니다.

중요한 제한 사항: Bash 패턴은 정규 표현식이 아닌 접두사만 일치시킵니다. Bash(curl http:*) 같은 패턴은 옵션이 URL보다 먼저 나오므로 curl -X GET http://...과 일치하지 않습니다. 확실하게 차단하려면 Bash(curl:*)처럼 명령 전체를 거부하세요.

파일 작업 패턴:

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

경로 문법: - 상대 경로: Edit(src/**) - 작업 디렉터리 기준 - 설정 파일 기준 절대 경로: Edit(/build/**) - 설정 파일 위치 기준 - 실제 절대 경로: Edit(//tmp/**) - //로 시작 - 홈 디렉터리: Read(~/.zshrc)

Write(path)/NotebookEdit(path)/Glob(path) 대신 Edit(path)/Read(path)를 사용하세요(v2.1.210). 이제 Claude Code는 Write(path), NotebookEdit(path), Glob(path)을 대상으로 작성한 권한 규칙이 있으면 시작할 때 경고를 표시합니다. 표준 형식은 실제로 파일 접근을 제어하는 두 가지 규칙 계열입니다. Edit(path)는 모든 파일 쓰기 도구(Write와 NotebookEdit 포함)를 포괄하고, Read(path)는 모든 파일 읽기 도구(Glob 포함)를 포괄합니다. 경고를 없애고 의도를 명확히 유지하려면 기존 규칙을 새 형식으로 이전하세요.¹⁸⁷

“항상 허용” 규칙은 저장소 루트에 저장됩니다(v2.1.211). 이제 “항상 허용” 승인 옵션으로 만든 권한 규칙은 현재 worktree가 아닌 저장소 루트에 기록됩니다. 따라서 한 worktree에서 승인한 규칙은 세션이 바뀌어도 해당 저장소의 모든 worktree에서 유지되므로 병렬 체크아웃마다 같은 명령을 다시 승인할 필요가 없습니다.¹⁸⁸

MCP 도구 패턴:

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

특정 MCP 서버의 모든 도구를 허용하거나 거부하려면 와일드카드 문법 mcp__server__*를 사용하세요.³² 와일드카드 문법은 신뢰할 수 있는 서버의 모든 도구를 빠르게 활성화하거나 신뢰할 수 없는 출처의 서버 전체를 차단할 때 유용합니다.

v2.1.166부터 거부 규칙은 도구 이름 위치에도 glob을 허용합니다. 도구 이름 자리에 "*"만 지정하면 모든 도구를 거부하므로, 전체를 차단한 다음 제한된 일부 도구만 다시 허용할 수 있습니다. 반면 허용 규칙은 MCP 이외의 glob을 거부하므로 같은 방식으로 모든 도구를 폭넓게 허용할 수 없습니다. 이를 통해 기본 정책이 제한적으로 유지됩니다.¹⁹³

매개변수 수준 일치 — Tool(param:value)(v2.1.178):

도구 이름뿐 아니라 도구의 입력 매개변수도 규칙으로 일치시킬 수 있으며, 값에는 *를 와일드카드로 사용할 수 있습니다.

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

Agent(model:opus)는 Opus 등급으로 생성되는 모든 subagent를 차단합니다. 해당 모델을 사용하지 말라는 요청을 프롬프트에 추가하는 수준이 아니라 생성 자체를 거부합니다. 이를 통해 권한 제어 범위가 “어떤 도구인지”에서 “어떤 방식으로 호출하는지”까지 확장되며, 프롬프트 수준 요청이 아닌 결정론적 규칙으로 작동합니다. 이 규칙은 관리형 enforceAvailableModels 설정과 함께 사용할 수 있습니다. 허용 목록은 세션에서 제공되는 모델 등급을 정의하고, Tool(model:...) 규칙은 subagents가 해당 모델을 사용하는 방식을 제한합니다.¹⁷³

v2.1.186부터 이러한 Agent(...) 규칙은 이름이 지정된 subagent 생성에도 적용됩니다. 이제 Agent(agent_type) 거부 규칙과 Agent(x,y) 허용 타입 제한은 익명의 Task 방식 생성뿐 아니라 워크플로, --agents 또는 agent team을 통해 특정 이름의 agent를 실행할 때도 적용됩니다. 생성 시점에 실행이 차단되므로 이름이 지정된 agent가 자신을 제한하기 위한 규칙을 우회하던 허점이 해소되었습니다.¹⁷⁵

WebFetch 패턴:

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

추가 디렉터리

Claude의 접근 범위를 현재 프로젝트 외부로 확장합니다.

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

모노레포를 사용하거나 Claude이 같은 상위 디렉터리에 있는 다른 디렉터리의 코드를 참조해야 한다면 추가 디렉터리 설정이 필수입니다.

샌드박스 모드

파일 시스템과 네트워크 격리를 활성화합니다.

> /sandbox

또는 설정에서 구성합니다.

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

v2.1.187부터 sandbox.credentials 설정은 샌드박스에서 실행되는 명령이 자격 증명 파일과 비밀 환경 변수를 읽지 못하도록 차단합니다. 샌드박스 명령을 통한 비밀 정보 유출을 막는 다층 방어 기능입니다.¹⁷⁶

샌드박스를 사용하면: - 파일 시스템 접근이 프로젝트 디렉터리로 제한됩니다 - 네트워크 접근이 제어됩니다 - 일부 명령은 샌드박스 제한에서 제외됩니다 - autoAllowBashIfSandboxed가 true이면 Bash 명령이 자동으로 허용됩니다

전문가 팁: 샌드박스 모드는 신뢰할 수 없는 코드베이스에서 Claude을 실행할 때 매우 유용합니다. 익숙하지 않은 프로젝트를 살펴보거나 보호 계층을 하나 더 추가하고 싶을 때 활성화하세요. Anthropic의 내부 테스트에서는 샌드박스를 사용하면 권한 요청이 84% 감소하는 것으로 나타났습니다.³⁸ 샌드박스는 파일 시스템과 네트워크를 격리하기 위해 운영 체제 수준의 기본 기능(macOS seatbelt, Linux bubblewrap)을 사용하므로 프롬프트 주입에 성공하더라도 영향이 샌드박스 안으로 완전히 제한됩니다. Anthropic는 자체 agents를 만드는 팀을 위해 샌드박스 런타임을 오픈 소스로 공개했습니다.⁸²

보안 참고 사항(v2.1.34 이상): 이전에는 autoAllowBashIfSandboxed가 활성화된 경우 sandbox.excludedCommands 또는 dangerouslyDisableSandbox를 통해 샌드박스에서 제외된 명령이 Bash 승인 요청 규칙을 우회할 수 있었지만, v2.1.34에서 수정되었습니다.⁸⁷ v2.1.38부터 샌드박스 모드에서는 .claude/skills에 쓸 수 없으므로 프롬프트 주입을 통한 skill 정의 수정이 차단됩니다.⁸⁸ v2.1.77에서는 denyRead 영역 안에서 읽기 접근을 다시 허용할 수 있는 allowRead 샌드박스 파일 시스템 설정이 추가되었습니다. 디렉터리 트리 대부분은 차단하면서 특정 하위 디렉터리만 허용 목록에 추가하고 싶을 때 유용합니다.¹¹⁹

.claude/ agent 설정 예외(v2.1.121 이상): --dangerously-skip-permissions는 더 이상 .claude/skills/, .claude/agents/, .claude/commands/에 쓸 때 승인을 요청하지 않습니다.¹⁵⁴

중첩된 .claude/ 확인 방식(v2.1.178): 이제 저장소 루트뿐 아니라 중첩된 .claude/skills 디렉터리의 skills도 해당 디렉터리 아래의 파일에서 작업할 때 자동으로 로드됩니다. 이름이 겹치면 중첩된 skill을 <dir>:<name>으로 지정할 수 있어 두 skill을 모두 사용할 수 있습니다. 프로젝트의 나머지 요소도 같은 방식으로 확인됩니다. 중첩된 .claude/ 디렉터리 사이에서 agent, 워크플로 또는 출력 스타일의 이름이 충돌하면 작업 디렉터리와 가장 가까운 항목이 우선하며, 프로젝트 범위 워크플로는 가장 가까운 기존 .claude/workflows/에 저장됩니다. 모노레포나 저장소를 포함한 저장소에서는 하나의 평면적인 전역 구성 대신 상황에 맞게 활성화되는 패키지별 도구를 사용할 수 있습니다.¹⁷³

사용자 지정 bubblewrap 및 socat 경로(v2.1.133 이상): 관리자는 sandbox.bwrapPath와 sandbox.socatPath 관리형 설정을 사용하여 Linux/WSL 배포 환경에서 표준 위치가 아닌 bubblewrap과 socat 바이너리 경로를 지정할 수 있습니다. 배포판이 이러한 도구를 $PATH 외부에 설치하거나 조직에서 보안을 강화한 자체 빌드를 제공할 때 유용합니다.¹⁶⁰

v2.1.113의 보안 강화 사항:¹⁵⁰

• sandbox.network.deniedDomains는 더 넓은 allowedDomains 와일드카드에서 허용하는 호스트라도 개별적으로 차단합니다. 전체 허용 정책을 다시 작성하지 않고도 pastebin, 파일 공유 사이트 또는 악성으로 알려진 호스트를 차단 목록으로 막을 수 있습니다.
• 래퍼 명령 거부 규칙. 이제 Bash 거부 규칙은 env, sudo, watch, ionice, setsid 및 이와 유사한 실행 래퍼로 감싼 명령에도 일치합니다. 이제 Bash(rm:*) 같은 규칙은 env rm -rf, sudo rm -rf 및 이와 유사한 우회 패턴도 감지합니다.
• Bash(find:*) 허용 규칙은 더 이상 find -exec 또는 find -delete를 자동 승인하지 않습니다. 이 플래그들은 명령을 실행하거나 파일을 삭제하므로 Claude Code는 일반 권한 승인 절차를 적용합니다.
• macOS 삭제 보호. 이제 Bash(rm:*) 허용 규칙은 /private/etc, /private/var, /private/tmp, /private/home을 위험한 삭제 대상으로 취급합니다. /var, /etc, /tmp는 /private/ 내부를 가리키는 심볼릭 링크이므로 기존 규칙 형태로는 실제 대상 경로를 감지하지 못했습니다.

Hooks는 어떻게 작동하나요?

Hooks는 Claude Code의 워크플로에서 특정 시점에 결정론적인 셸 명령을 실행해요. Claude에게 작업을 수행하라고 프롬프트로 요청하는 방식과 달리, hooks는 모델의 동작과 관계없이 실행을 보장해요. 팀 표준을 적용하고 반복 작업을 자동화하는 데 꼭 필요해요. command, prompt, agent hooks를 다루는 “어떤 Hook 유형을 선택해야 하나요?” 결정 트리는 결정 프레임워크를 참고하세요.

프롬프트 대신 hooks를 사용하는 이유: Claude에게 “파일을 편집한 후에는 항상 Prettier를 실행해”라고 말하면 때로는 제대로 작동해요. 하지만 Claude이 잊어버리거나 속도를 우선하거나 변경 사항이 “너무 작다”고 판단할 수도 있어요. Hooks는 실행을 보장해요. Edit나 Write가 발생할 때마다 예외 없이 formatter가 실행돼요. 규정 준수, 보안, 팀 표준에서는 확률적인 방식보다 결정론적인 방식이 더 나아요.⁴

사용할 수 있는 이벤트

Hook 설정

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 필드는 어떤 도구가 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)

여러 도구를 일치시키려면 |를 사용하세요(Edit|Write). v2.1.191부터 쉼표로 구분한 matchers(예: Bash,PowerShell)도 올바르게 실행돼요. 이전 버전에서는 쉼표가 포함된 matchers가 아무런 안내 없이 누락되어 해당 hook이 전혀 실행되지 않았어요.¹⁷⁸ v2.1.195부터 하이픈이 포함된 식별자를 사용하는 matchers(예: code-reviewer, mcp__brave-search)는 실수로 부분 문자열을 일치시키는 대신 정확히 일치해요. 이제 문자열을 포함하기만 한 의도하지 않은 도구에서는 matcher가 실행되지 않아요. 하이픈이 포함된 MCP 서버의 모든 도구를 일치시키려면 mcp__brave-search__.*와 같은 명시적인 패턴을 사용하세요.¹⁷⁹

Hook 입력/출력 프로토콜

Hooks는 stdin을 통해 JSON을 받아요.

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

Hook 이벤트 정보 확장(v2.1.69+): 이제 subagent 또는 --agent 세션에서 발생한 모든 hook 이벤트에는 agent_id와 agent_type 필드가 포함되며, 상태 표시줄 hook 명령에는 worktree 필드도 포함돼요.¹¹⁰

Stop/SubagentStop hooks(v2.1.47+)는 Claude의 최종 응답 텍스트가 담긴 last_assistant_message 필드를 추가로 받아요. 따라서 hooks는 대화 기록 파일을 파싱하지 않고도 출력을 검사할 수 있어요.

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

차단하지 않는 부드러운 피드백(v2.1.163+): Stop과 SubagentStop hooks는 JSON 출력에서 hookSpecificOutput.additionalContext를 반환해 Claude에게 피드백을 전달하고 응답이 hook 오류로 표시되지 않은 상태로 작업을 계속할 수 있어요. 이전에는 Stop hook이 실질적으로 사용할 수 있는 수단이 exit-2 차단뿐이었어요. 이 방식은 오류로 표시되고 연속 차단 한도에도 포함됐어요. additionalContext는 루프를 방해하지 않으면서 “놓친 내용은 이것이니 계속 진행하세요”라는 안내를 제공하는 방향 조정 채널을 추가해요.¹⁹⁴

Exit codes는 동작을 제어해요. - 0: 성공: 작업을 계속 진행해요. Stdout은 verbose 모드(Ctrl+O)에서 표시돼요. UserPromptSubmit과 SessionStart에서는 stdout이 컨텍스트에 추가돼요. - 2: 차단 오류: 작업을 중단해요. Stderr가 Claude에게 전달되는 오류 메시지가 돼요. - 1, 3 등: 비차단 오류: 작업을 계속 진행해요. Stderr는 verbose 모드에서 경고로 표시돼요.

고급 제어가 필요하면 hooks가 JSON을 출력하도록 설정할 수 있어요.

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

PreToolUse 결정 제어(권장 형식): PreToolUse hooks는 더 세밀한 제어를 위해 hookSpecificOutput을 사용해요. 3가지 결과(allow/deny/ask)를 지원하며 도구 입력을 수정하고 컨텍스트를 삽입할 수도 있어요.⁸⁹

{
  "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에서는 최상위 decision과 reason 필드가 더 이상 권장되지 않아요. 대신 hookSpecificOutput.permissionDecision과 hookSpecificOutput.permissionDecisionReason을 사용하세요. 다른 이벤트(PostToolUse, Stop 등)는 여전히 최상위 decision을 사용해요.⁸⁹

UserPromptSubmit 세션 제목(v2.1.94+): UserPromptSubmit hooks는 hookSpecificOutput.sessionTitle을 통해 세션 제목을 설정할 수 있어요.¹⁴⁰

비동기 Hooks(2026년 1월)

이제 Hooks는 Claude Code의 실행을 차단하지 않고 백그라운드에서 실행될 수 있어요. Hook 설정에 async: true를 추가하세요.⁸¹

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

비동기 hooks를 사용하기 좋은 경우: - 세션 속도를 늦추면 안 되는 알림(Slack, email, Pushover) - 백그라운드에서 실행할 수 있는 기록 및 telemetry - 중요하지 않은 후처리(analytics, backups)

비동기 hooks를 사용하면 안 되는 경우: - 형식 정리(다음 편집 전에 완료되어야 함) - 검증(실패하면 차단해야 함) - 도구의 입력/출력을 수정해야 하는 모든 hook

Prompt 기반 및 Agent 기반 Hooks(v2.1.32+)

Claude Code은 셸 명령 hooks(type: "command") 외에도 스크립트 대신 AI 추론으로 조건을 평가하는 2가지 LLM 기반 hook 유형을 지원해요.⁸⁹

Prompt hooks(type: "prompt")는 빠른 Claude 모델에 단일 차례 프롬프트를 보내요. 모델은 허용하려면 { "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")는 이벤트의 JSON 입력을 URL에 POST 요청으로 보내고 JSON을 돌려받아요. webhooks, 외부 알림 서비스 또는 API 기반 검증에 사용하세요(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과 reason이 포함된 JSON 반환). sandboxing이 활성화되어 있으면 sandbox 네트워크 proxy를 통해 라우팅돼요. SessionStart/Setup 이벤트에서는 지원되지 않아요.

Agent hooks(type: "agent")는 여러 차례에 걸친 검증을 위해 도구(Read, Grep, Glob)에 접근할 수 있는 subagent를 생성해요. 실제 파일이나 테스트 출력을 검사해야 할 때 사용하세요.

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

Hook의 JSON 입력을 나타내는 placeholder로 $ARGUMENTS를 사용하세요. 두 유형 모두 model(기본값은 빠른 모델)과 timeout 필드를 지원해요. 지원되는 이벤트는 PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Stop, SubagentStop, TaskCompleted예요. TeammateIdle은 prompt/agent hooks를 지원하지 않아요.

MCP 도구 Hooks(v2.1.118+)

이제 Hooks는 type: "mcp_tool"을 통해 MCP 도구를 직접 호출할 수 있어요. 서버를 호출하는 Bash 하위 프로세스로 감쌀 필요가 없어요.¹⁵²

{
  "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 서버와 잘 어울려요. /mcp에서 접근할 수 있는 모든 도구를 hook에서 호출할 수 있어요.

PostToolUse Hooks의 duration_ms(v2.1.119+)

이제 PostToolUse와 PostToolUseFailure hook 입력에는 권한 프롬프트와 PreToolUse hooks를 제외한 도구 실행 시간인 duration_ms가 포함돼요.¹⁵² 느린 도구 감지, 감사 기록, 도구별 지연 시간 지표에 유용해요.

# 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

모든 도구의 updatedToolOutput(v2.1.121+)

v2.1.118에서는 MCP 도구 Hooks에 hookSpecificOutput.updatedToolOutput을 통해 도구 출력을 교체하는 기능이 추가됐어요. v2.1.121부터는 모든 PostToolUse hook에서 같은 필드를 사용할 수 있어요. 여기에는 기본 제공 도구(Bash, Read, Edit, Glob, Grep 등), subagent 도구, MCP 도구가 모두 포함돼요. 모든 도구의 출력에서 민감한 내용을 가리거나, 후속 처리자가 사용할 수 있도록 구조를 정규화하거나, agent가 결과를 읽기 전에 metadata를 삽입할 때 활용할 수 있어요.¹⁵⁴

Hook 환경 변수

Hooks는 경로를 확인하는 데 사용할 수 있는 환경 변수에 접근할 수 있어요.⁸⁹

SessionStart에서 환경 변수 유지하기:

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

HTTP hook 보안(v2.1.51+): 이제 headers에 환경 변수를 삽입하는 HTTP hooks에는 명시적인 allowedEnvVars 목록이 필요해요. 이를 통해 header 값을 이용해 임의의 환경 변수가 유출되는 일을 방지해요. sandboxing이 활성화되어 있으면 HTTP hooks도 sandbox 네트워크 proxy를 통해 라우팅되므로 domain allowlist가 적용돼요. HTTP hooks는 SessionStart/Setup 이벤트에서 지원되지 않아요.⁹⁸

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

Hook workspace 신뢰(v2.1.51+): 이제 statusLine과 fileSuggestion hook 명령을 대화형 모드에서 실행하려면 workspace 신뢰를 승인해야 해요. 이를 통해 잠재적인 보안 경로를 차단했어요.⁹⁸

실용적인 Hook 예시

편집 후 TypeScript 파일 자동 형식 정리:

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

모든 bash 명령 기록:

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

민감한 파일에 대한 접근 차단:

#!/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

코드 변경 후 테스트 실행:

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

사용자 지정 알림 시스템:

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

프롬프트에 동적 컨텍스트 삽입:

#!/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 디버깅

Hooks의 문제를 해결하려면 debug 모드를 활성화하세요.

claude --debug

Debug 모드에서 기록되는 항목: - Hook 실행 시간 - 입력/출력 데이터 - 오류 메시지와 stack traces - 결정 결과(allow/reject/ask)

Hook 출처 표시(v2.1.75+): Hook에 사용자 확인이 필요할 때 이제 권한 프롬프트에 hook의 출처(settings, plugin 또는 skill)가 표시돼요. 따라서 어떤 구성 요소가 접근을 요청하는지 더 쉽게 파악할 수 있어요.¹¹⁷

구성 요소 범위 Hooks(v2.1.0+)

Hooks는 frontmatter를 사용해 Skills, subagents, slash commands에 직접 정의할 수 있어요. 이러한 hooks는 해당 구성 요소의 수명 주기에만 적용되며, 구성 요소가 활성화된 동안에만 실행돼요.³⁴

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
---

지원되는 이벤트: PreToolUse, PostToolUse, Stop

once 옵션(skills와 slash commands에서만 지원)을 사용하면 세션당 hook이 1번만 실행돼요. 정리나 마무리 작업에 유용해요.

장시간 실행되는 세션 전략

밤새 실행하거나 사람이 지켜보지 않는 Claude Code 세션에서는 수동으로 개입하지 않아도 Claude이 올바른 방향을 유지하도록 hooks를 설정하세요. 핵심은 linting 및 testing hooks를 guardrails로 사용해 Claude이 계속 진행하기 전에 문제를 수정하도록 강제하는 거예요.⁵⁷

“테스트가 통과할 때까지 멈추지 않기” 패턴:

{
  "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'"
          }
        ]
      }
    ]
  }
}