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

요약: Claude Code은 권한, hooks, MCP 연동, subagents로 구성된 다층 시스템을 통해 코드베이스를 읽고, 명령을 실행하고, 파일을 수정하는 에이전트형 CLI예요. 핵심 시스템 5가지인 설정, 권한, hooks, MCP, subagents를 익히면 생산성을 크게 높일 수 있어요. 작업마다 적합한 모델 등급을 선택하세요. 복잡한 추론에는 Opus, 일반 작업에는 Sonnet, 빠른 탐색에는 Haiku를 사용하면 돼요. 품질만 중요하다면 Opus로 통일해도 좋아요. 반드시 실행해야 하는 작업에는 프롬프트가 아니라 hooks를 사용하세요. 2026년 6월 30일에 출시된 v2.1.197부터 Claude Sonnet 5가 Claude Code의 기본 모델이에요. 기본으로 1M 컨텍스트를 제공하며, 8월 31일까지 $2/$10 프로모션 요금이 적용돼요. Opus는 /model opus 한 번이면 선택할 수 있고, v2.1.219부터 이 별칭은 Claude Opus 5를 지정해요. 7월 1일에 출시된 v2.1.198부터는 subagents가 기본적으로 백그라운드에서 실행되고, Chrome용 Claude이 정식 출시됐어요. 백그라운드 에이전트는 worktree의 코드 작업을 마치면 commit과 push를 수행하고 초안 PR을 열 수 있으며, 백그라운드 세션에서는 Notification hook이 agent_needs_input 또는 agent_completed와 함께 실행돼요. 7월 2일에 출시된 v2.1.199는 중첩된 slash-skill 호출을 최대 5개까지 불러오고, 구독자에게 발생한 일시적인 429 오류를 자동으로 다시 시도해요. 7월 3일에 출시된 v2.1.200은 CLI, --help, VS Code, JetBrains 전반에서 default 권한 모드의 이름을 “Manual”로 변경했어요. 설정값은 바뀌지 않았고 manual도 별칭으로 사용할 수 있어요. 또한 AskUserQuestion 대화 상자는 기본적으로 자동 진행되지 않아요. 7월 6일에 출시된 v2.1.202는 “Dynamic workflow size” /config 제어 기능을 추가하고, /review <pr>을 빠른 단일 패스 검토 방식으로 되돌렸어요. 여러 에이전트가 참여하는 검토는 /code-review <level> <pr#>로 옮겨졌어요. 7월 7일부터 9일까지 출시된 v2.1.203~205는 auto mode의 안전성을 강화했어요. 대화 기록 파일의 변조를 차단하고, 값을 확인할 수 없는 변수를 대상으로 rm -rf를 실행할 때 먼저 사용자에게 묻고, 백그라운드 작업 알림에는 사람이 입력하지 않았다는 사실을 표시해요. 따라서 대화 기록 안에 조작된 승인이 있어도 이를 근거로 작업을 실행할 수 없어요. 또한 /doctor는 진단과 수정을 모두 수행하는 종합 점검 기능이 됐으며 /checkup을 별칭으로 사용할 수 있어요.^181182183 7월 21일에 출시된 v2.1.217은 중첩 subagents에 관한 방침을 뒤집었어요. subagents는 기본적으로 자체 subagents를 생성하지 않게 됐어요. 하지만 불과 3일 뒤 v2.1.219에서 이 기본값이 다시 뒤집혀 깊이 3까지 허용됐어요. 자세한 내용은 아래를 참고하세요. 기본 동시 실행 한도는 subagents 20개이며 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS로 조정할 수 있어요. 이제 --max-budget-usd는 한도에 도달하면 백그라운드 subagents를 실제로 중단해요.¹⁹⁴ 7월 22일에 출시된 v2.1.218은 /code-review를 백그라운드 subagent로 옮겼어요. 검토 작업이 더 이상 현재 대화의 컨텍스트를 채우지 않아요. context: fork skills도 기본적으로 백그라운드에서 실행되며, 각 skill에 background: false를 지정하면 이를 끌 수 있어요. /deep-research는 명시적으로 호출할 때만 시작돼요. 위험한 rm, 백그라운드 &, 의심스러운 Windows 경로에 관한 검사는 권한 대화 상자 대신 auto-mode 분류기가 처리해요. 또한 신뢰할 수 없는 폴더에서는 에이전트 frontmatter hooks가 실행되지 않아요.¹⁹⁵ 7월 24일에 출시된 v2.1.219부터 Claude Opus 5(claude-opus-5)가 기본 Opus 모델이에요. 1M 컨텍스트와 최대 128K 출력을 지원하고, MTok당 요금은 $5/$25로 Opus 4.8과 같아요. thinking은 기본으로 켜져 있고 effort 기본값은 high이며, 지식 기준 시점은 2026년 5월이에요. 또한 이전 릴리스에서 바뀌었던 2가지를 바로잡았어요. 이제 fast mode는 Opus 5와 Opus 4.8에 MTok당 $10/$50로 적용돼요. 기본 요금의 2배이며, Opus 4.7은 fast mode에서 완전히 제외됐어요. 중첩 subagents도 다시 기본으로 켜졌으며 깊이는 3이에요. CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1로 중첩을 끌 수 있어요. 같은 릴리스에는 DirectoryAdded hook 이벤트, sandbox.network.strictAllowlist 설정, workflowSizeGuideline 설정 키가 추가됐어요. dynamic workflows에는 이제 중간 크기 지침이 기본으로 적용되며 에이전트를 15개 미만으로 유지하는 것을 목표로 해요. stream-json에서는 중첩 subagent 전달도 지원해요. 7월 25일에 출시된 v2.1.220에는 버그 수정과 안정성 개선만 포함됐어요.^196197198 2026년 6월 12일에 출시된 v2.1.174~176부터는 새로운 enforceAvailableModels 관리형 설정을 통해 availableModels 허용 목록으로 Default 모델까지 제한할 수 있어요. 사용자 또는 프로젝트 설정으로 관리형 목록을 확장할 수는 없어요. 세션 제목은 대화에 사용된 언어로 생성되며, language 설정으로 언어를 고정할 수 있어요. 새로운 footerLinksRegexes와 wheelScrollAccelerationEnabled 설정, VSCode /usage 출처 표시 대화 상자, hook의 if 조건이 Read, Edit, Write 경로 패턴과 올바르게 일치하도록 한 수정도 이 릴리스에 포함됐어요.¹⁷² 2026년 6월 11일에 출시된 v2.1.173부터는 이름 끝에 [1m]이 붙은 Fable 5 모델 이름을 자동으로 정규화해 해당 접미사를 제거해요. Fable 5는 이미 기본으로 1M 컨텍스트를 제공하므로 이 접미사가 필요하지 않아요. 이 접미사는 Opus와 Sonnet에서만 의미가 있었어요. 2026년 6월 10일에 출시된 v2.1.172부터는 sub-agents가 자체 sub-agents를 최대 5단계까지 재귀적으로 생성할 수 있었어요. 이 기본값은 v2.1.216까지 유지되다가 앞서 설명한 것처럼 v2.1.217에서 꺼졌어요. AWS_REGION을 설정하지 않으면 Bedrock이 ~/.aws에서 리전을 읽고 /status에 출처를 표시해요. /plugin에는 마켓플레이스 검색창이 추가됐으며, claude_code.lines_of_code.count OTEL 지표에는 model 속성이 추가됐어요. 2026년 6월 9일에 출시된 v2.1.170부터는 Opus보다 높은 새로운 모델 등급인 Claude Fable 5를 claude update 후 Claude Code의 /model fable로 선택할 수 있어요. low부터 max까지 모든 effort 단계를 지원하지만 thinking을 끌 수는 없어요. 에이전트형 작업의 기본 모델은 계속 Opus 4.8이었어요. 2026년 6월 8일에 출시된 v2.1.169부터는 --safe-mode와 CLAUDE_CODE_SAFE_MODE로 문제 해결을 위해 모든 사용자 지정 기능을 끈 깨끗한 세션을 시작할 수 있어요. /cd를 사용하면 프롬프트 캐시를 깨뜨리지 않고 세션을 새 작업 디렉터리로 옮길 수 있으며, disableBundledSkills는 기본 제공 skills와 slash commands를 모델에서 숨겨요. 2026년 6월 6일에 출시된 v2.1.166부터는 fallbackModel 설정으로 기본 모델이 과부하 상태일 때 최대 3개의 예비 모델을 순서대로 사용할 수 있어요. MCP 거부 규칙에서는 glob "*"가 작동하며, MAX_THINKING_TOKENS=0 또는 --thinking disabled로 thinking이 기본 활성화된 모델에서도 thinking을 완전히 끌 수 있어요. 2026년 5월 28일에 출시된 v2.1.154부터는 Opus 4.8이 새로운 기본 모델이 됐고 effort 기본값은 high이며 /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는 발견된 문제를 working tree에 적용하는 /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 206 171}

Claude Code은 프로그래밍 지식을 갖춘 채팅 인터페이스가 아니라 에이전트형 시스템으로 작동해요. CLI는 코드베이스를 읽고, 명령을 실행하고, 파일을 수정하고, git 작업 흐름을 관리하고, MCP를 통해 외부 서비스에 연결하고, 복잡한 작업을 전문 subagents에 위임해요. 이 모든 작업은 개발자의 실제 업무 방식에 통합되는 명령줄 인터페이스를 통해 이뤄져요. 2026년 2월 기준으로 공개 GitHub commit의 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는 실행을 보장하지만 프롬프트는 그렇지 않아요: 모델의 동작과 상관없이 매번 실행해야 하는 lint 검사, formatting, 보안 검사에는 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의 텍스트와 사고 과정 출력도 스트림으로 전달되므로, 하네스와 로그 파이프라인은 최종 보고서만 보는 대신 위임된 작업이 진행되는 과정을 실시간으로 확인할 수 있어요.¹⁸⁸

중첩된 subagents도 이제 전달돼요(v2.1.219). 원래는 깊이 1의 subagents만 표시됐어요. 이제 깊이 2 이상에서 생성된 subagents도 전달된 스트림에 나타나며, 각 항목은 해당 subagent를 생성한 Agent 호출의 tool_use 아이디를 키로 사용해요. 따라서 파이프라인은 평면적인 텍스트 목록만 보는 대신 위임 트리를 재구성할 수 있어요. 이 기능은 같은 릴리스에서 기본 중첩 생성 깊이가 3으로 복원된 것과 직접 맞물려요. 이 기능이 없었다면 3개 단계 중 2개 단계가 보이지 않았을 거예요.¹⁹⁶

종료 코드:

-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로 계속 제공돼요.¹⁸⁹ v2.1.214부터 분기로 시작한 세션은 SessionStart hook 소스를 이전의 "resume" 대신 "fork"로 보고하므로, 소스를 기준으로 일치 여부를 판단하는 hooks에서 두 경우를 구분할 수 있어요.¹⁹⁰ v2.1.216에서는 /fork 확인 메시지가 새 세션의 이름과 claude attach 아이디를 보여주는 한 줄로 간결해졌어요.¹⁹²

Claude Code은 세션을 JSONL 트랜스크립트로 저장해요. Agent 실행에는 고유한 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은 3가지 옵션을 제시해요: - “예, 맥락을 지우고 편집을 자동 승인”(Shift+Tab) — Plan을 위한 새 맥락으로 시작해요 - “예, 편집을 수동으로 승인” — 맥락을 유지하고 각 변경 사항을 사용자가 승인해요 - “예, 편집을 자동 승인” — 맥락을 유지하고 Claude이 변경마다 승인을 받지 않고 실행해요

승인 시 맥락 자동 초기화를 권장해요. Plan에 새로운 맥락 창을 제공하므로 Plan 준수율이 크게 향상돼요. 이전 대화의 방해를 받지 않아 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
  }
}

팀에 대규모 skills 라이브러리가 있지만 런타임에 노출되는 범위를 더 엄격하게 제한하고 싶을 때 skillOverrides가 유용해요. off를 사용하면 모델과 슬래시 선택기 모두에서 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 선택기, --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가 자체적으로 실행하는 모든 프로세스를 래퍼 실행 파일을 통해 실행해요. 기업용 실행 프로그램을 위해 만들어진 기능이에요(기업용 실행 프로그램 참고).¹⁸⁶
• autoMode 소스 제한(v2.1.207): 이제 저장소의 .claude/settings.local.json에서는 autoMode 설정을 읽지 않아요. 대신 ~/.claude/settings.json에서 구성하세요. 복제한 저장소가 자동 모드 설정을 함께 제공할 수 있었던 경로를 차단하는 변경 사항이에요.¹⁸⁵

새로운 설정(v2.1.217):

• emojiCompletionEnabled(v2.1.217): 프롬프트 입력에서 이모지 단축 코드 자동 완성을 사용할 수 있어요. :heart:를 입력하면 ❤️가 삽입되며, :hea처럼 일부만 입력하면 추천 항목이 표시돼요. 기본적으로 켜져 있으며, 끄려면 false로 설정하세요.¹⁹⁴

새로운 설정(v2.1.219):

• sandbox.network.strictAllowlist(v2.1.219): 권한 대화 상자를 표시하는 대신, sandbox에서 실행되는 명령이 허용 목록에 없는 호스트에 접근하면 묻지 않고 차단해요. Sandbox 모드를 참고하세요.¹⁹⁶
• workflowSizeGuideline(v2.1.219): /config에서만 지정하지 않아도 사용자, 프로젝트, 관리형 설정 등 어떤 설정 파일에서든 권장 Dynamic workflow 크기 지침을 설정할 수 있어요. Dynamic workflows는 기본적으로 medium 지침(“에이전트를 15개 미만으로 사용하세요”)을 사용해요. 설정 파일에서 값을 제공하면 /config의 해당 행은 숨겨져요. 이는 권장 사항이며 강제 제한은 아니에요. subagents를 참고하세요.¹⁹⁶

환경 변수 참고 자료

인증 및 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+). Covers depth-2+ nested subagents as of v2.1.219[^205][^213]
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]
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=20         # Cap on concurrently-RUNNING subagents (default 20; distinct from the per-session total above; v2.1.217+)[^211]
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=3          # Nested subagent spawn depth. Default 3 as of v2.1.219; set 1 to disable nesting. Default history: 5 (v2.1.172–v2.1.216) → 1 (v2.1.217) → 3 (v2.1.219). Set it explicitly[^211][^213]

도구 설정:

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 내보내기 도구 및 민감한 필드 제어:²⁰⁷

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_OTEL_CONTENT_MAX_LENGTH=60000     # Truncation limit for OTel content attributes (default 60 KB; v2.1.214+)[^207]
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 수집기에서 발생하던 문제가 해결됐어요. Claude Code가 @ 멘션을 확인하면 새로운 claude_code.at_mention 로그 이벤트가 발생해요.¹⁵⁴

v2.1.193+ claude_code.assistant_response 로그 이벤트: Claude Code는 모델의 전체 응답 텍스트를 OTel 로그 이벤트로 내보낼 수 있으며, OTEL_LOG_ASSISTANT_RESPONSES로 이를 제어해요. 업그레이드할 때 알아 두어야 할 주의 사항이 있어요. OTEL_LOG_ASSISTANT_RESPONSES가 설정되지 않으면 OTEL_LOG_USER_PROMPTS 값을 따라가므로, 이미 프롬프트 내용을 기록하던 환경은 업그레이드 후 어시스턴트 응답 내용도 받기 시작해요. 프롬프트만 원격 측정에 포함하려면 OTEL_LOG_ASSISTANT_RESPONSES=0을 설정하세요.¹⁷⁹

v2.1.214 원격 측정 추가 사항: 이제 OTel 로그 이벤트에 메시지 수준의 연관 관계와 도구 출처를 파악할 수 있도록 message.uuid, client_request_id, tool_source 속성이 포함돼요. subagentStatusLine 페이로드에는 subagent의 추론 수준이 포함되므로 사용자 지정 상태 표시줄 행에서 모델과 추론 수준을 함께 표시할 수 있어요. 새로운 CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH 환경 변수로 OTel 콘텐츠 속성의 60 KB 잘림 제한도 설정할 수 있어요.¹⁹⁰

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=user@example.com        # Provide user email for SDK callers
CLAUDE_CODE_ORGANIZATION_UUID=uuid             # Provide organization UUID for SDK callers

디버깅:

ANTHROPIC_LOG=debug                             # Enable API request logging

어떤 모델을 선택해야 하나요?

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

사용 가능한 모델

하네스를 Opus 4.8에서 Opus 5로 이전할 때 발생하는 호환성을 깨뜨리는 2가지 변경 사항:¹⁹⁷

1. 사고가 기본적으로 켜집니다. Opus 4.8에서는 thinking 필드가 없는 요청이 사고 없이 실행되었지만, Opus 5에서는 같은 요청이 적응형 사고를 사용해 실행돼요. max_tokens는 사고와 응답 텍스트를 합친 전체 출력의 엄격한 한도로 계속 적용되므로, 이전에 사고 없이 실행했던 모든 작업에서 여유분을 다시 확인하세요. 이전 동작을 복원하려면 thinking: {type: "disabled"}를 전달하세요. 단, 다음 항목의 제한이 적용됩니다.
2. 사고를 끄면 노력 수준이 high로 제한됩니다. thinking: {type: "disabled"}를 노력 수준 xhigh 또는 max와 함께 사용하면 400이 반환돼요. 이 검사는 요청마다 적용되므로, 같은 대화의 이전 턴이 허용되었더라도 사고가 비활성화된 상태에서 노력 수준을 xhigh로 높이면 요청이 거부됩니다.

Claude Code에서는 Opus 5의 effort 기본값이 high이며 Claude API에서도 동일해요. low, medium, high, xhigh, max의 전체 단계가 제공됩니다. Anthropic의 마이그레이션 가이드에서는 토큰 비용보다 성능이 중요한 경우 max 노력 수준을 테스트하도록 권장해요. 빠른 모드에서는 Opus 5를 MTok당 $10/$50에 사용할 수 있습니다(빠른 모드 참고).¹⁹⁷¹⁹⁸

Claude Fable 5(2026년 6월 9일): Opus보다 상위인 새로운 모델 등급으로, Anthropic에서 가장 강력하고 지능적인 모델이에요. 테스트한 거의 모든 벤치마크에서 최고 수준을 기록했으며 수백만 토큰의 컨텍스트에서도 일관성을 유지하도록 설계되었습니다. Fable 5는 일반 사용에 안전하도록 만든 “Mythos급” 최첨단 모델이에요. 사이버, 생명화학, 모델 증류 관련 질의가 들어오면 Opus 4.8로 대체하는 안전 분류기가 포함되어 있습니다. Claude Mythos 5는 승인된 연구자를 위해 이러한 보호 조치를 해제한 동일한 모델이에요. v2.1.170(2026년 6월 9일)부터 Claude Code에서 선택할 수 있게 되었으며, claude update를 실행한 다음 /model fable을 사용하세요. 이는 짧은 별칭이며 /model claude-fable-5와 best 별칭으로도 선택할 수 있습니다. 구독 플랜에는 2026년 6월 22일까지 순차적으로 제공되었어요. 모델 ID는 claude-fable-5입니다. Fable 5는 기본적으로 1M 컨텍스트 창을 제공하므로 [1m] 접미사가 필요하지 않아요. 또한 v2.1.173(2026년 6월 11일)부터 claude-fable-5[1m] 모델 이름은 자동으로 정규화되어 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 5와 마찬가지로 전체 노력 수준(low/medium/high/xhigh/max, 기본값은 high)을 지원해요. Fable 5에서는 사고를 끌 수 없습니다. 세션 사고 토글, alwaysThinkingEnabled 설정, MAX_THINKING_TOKENS=0 모두 효과가 없으며 항상 적응형으로 추론해요. 전체 fable 계열 설정은 Opus 설정과 같은 구조입니다. ANTHROPIC_DEFAULT_FABLE_MODEL은 fable 별칭이 가리킬 모델을 고정하며 Bedrock/Vertex/Foundry에서 유용하고, DISABLE_PROMPT_CACHING_FABLE은 Fable의 프롬프트 캐싱을 비활성화하며, 엔터프라이즈 게이트웨이에서는 콘텐츠 기반 자동 대체가 적용돼요. 이제 /model opus는 Opus 5를 선택하며 기본 노력 수준은 high이고 가장 어려운 작업에는 /effort xhigh를 사용할 수 있습니다. Sonnet 5는 v2.1.197부터 초기 기본 모델로 제공돼요. 최고의 성능이 필요할 때는 /model fable을 사용해 Fable 5를 의도적으로 선택하세요.²⁰⁰¹⁹⁷

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

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

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

Opus 4.7의 Messages API 호환성을 깨뜨리는 변경 사항(호출자에게 표시됨):¹⁴⁵ - 확장 사고의 budget_tokens는 삭제됐어요. 대신 thinking: {type: "adaptive"}를 사용하세요. 적응형 사고는 기본적으로 꺼져 있으며, thinking 필드가 없는 요청은 사고 과정 없이 실행돼요. - temperature, top_p, top_k를 기본값이 아닌 값으로 설정하면 HTTP 400이 반환돼요. 이러한 매개변수는 생략하고 프롬프트로 모델의 동작을 조정하세요. - 사고 내용은 기본적으로 응답에서 제외돼요. 추론을 다시 표시하려면 thinking.display: "summarized"를 설정하세요. 제품에서 사용자에게 사고 과정을 스트리밍한다면 반드시 설정해야 해요.

작업 예산(베타 헤더 task-budgets-2026-03-13)을 사용하면 output_config.task_budget을 통해 전체 에이전트 루프의 목표 토큰 수를 모델에 알려줄 수 있으며, 최솟값은 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 모델보다 훨씬 약해요. 이러한 안전성 절충 덕분에 수출 통제 제한 없이 출시될 수 있었어요. 모델 ID: claude-sonnet-5(날짜가 없는 고정 스냅샷). 1M 토큰 컨텍스트 창과 최대 128K 출력을 지원하며, output-300k-2026-03-24 베타 헤더를 사용하면 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 기본 모델이에요. 별도 설정 없이 사용하는 기본 모델이 Opus 4.8에서 Sonnet 5로 바뀌었지만, Opus도 계속 자유롭게 선택할 수 있어요.¹⁸¹

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

Claude Mythos Preview(2026년 4월 7일): Project Glasswing에서 제공하는 방어적 사이버 보안 업무용 연구 미리 보기 최첨단 모델이에요.¹³⁹ 초대받은 사용자만 이용할 수 있으며, 일반에는 제공되지 않아요. 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는 정말 어려운 문제를 해결할 때만 사용하세요.¹

각 모델을 사용해야 할 때

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

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

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

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

모델 전환

세션 도중:

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

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

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

API에서 재시도할 수 없는 예기치 않은 오류가 반환되면, 이제 Claude Code은 실패를 표시하기 전에 대체 모델에서 해당 턴을 한 번 더 시도해요. 따라서 기본 모델의 일시적인 문제로 턴이 사라지는 대신 자연스럽게 성능을 낮춰 계속 진행해요.²⁰²

v2.1.178부터는 압축에도 대체 체인이 적용돼요. 압축 도중 기본 모델이 과부하 상태이거나 사용할 수 없으면 턴을 실패 처리하지 않고 설정된 fallbackModel/--fallback-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 토큰 요청과 동일한 토큰당 요율이 적용돼요. 전체 컨텍스트 창에서 프롬프트 캐싱과 일괄 처리 할인도 표준 요율로 적용돼요.

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

모델 선택기에서 1M 컨텍스트 변형을 비활성화하려면 CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정하세요.

현재 모델 확인

> /status

이 명령은 현재 모델, 계정 정보, 적용된 설정, 기타 세션 상태를 보여줘요. 모델 선택기 레이블 (v2.1.51+): 이제 /model 선택기는 고정된 버전에 원시 모델 ID 대신 사람이 읽기 쉬운 레이블(예: “Sonnet 4.6”)을 표시하며, 더 최신 버전이 있으면 업그레이드 안내도 보여 줘요.⁹⁸ v2.1.219에서는 통합된 Opus 행이 “Opus (1M context)”가 아닌 일반 “Opus”로 표시되도록 수정했고, 새 릴리스 강조 표시가 최신 모델의 이름에만 적용되도록 범위를 좁혔어요. 이제 목록의 임의 영역이 아니라 실제로 출시된 모델이 강조돼요.¹⁹⁶

Fast Mode (v2.1.36+)

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

> /fast            # Toggle fast mode on/off

지원 모델 (v2.1.219 기준): fast mode는 Claude Opus 5와 Claude Opus 4.8에 적용돼요. v2.1.219부터 Opus 4.7은 fast mode에서 제외됐으며, 이 기능은 Sonnet, Haiku, Fable에서 제공된 적이 없어요. 이 기능은 Claude API(Claude Managed Agents 포함)에서만 제공되는 연구용 미리보기로 유지돼요. Amazon Bedrock, Google Cloud, Microsoft Foundry 또는 AWS의 Claude Platform에서는 사용할 수 없어요. 접근 권한이 제한되어 있으므로 계정 관리자에게 문의하거나 대기자 명단에 등록하세요.¹⁹⁶¹⁹⁸

가격 (Opus 5 / Opus 4.8 fast mode):¹⁹⁸

Opus 4.7의 함정 (v2.1.219). 지원되지 않는 모델이 모두 같은 방식으로 동작하지는 않아요. speed: "fast"를 지정해 claude-opus-4-7에 요청하면 이제 오류가 반환되며, 표준 속도로 조용히 전환되지 않아요. 알아 둘 만한 예외는 Opus 4.6이에요. 이 모델은 speed: "fast"를 허용하지만 실제로는 표준 속도로 실행되고, 표준 요금이 청구되며, usage.speed: "standard"를 보고해요. 하네스가 4.7에 고정되어 있고 fast-mode 요청이 별다른 알림 없이 느린 속도로 전환되는 동작에 의존했다면 이제 요청이 완전히 실패해요. 고정 버전을 Opus 5 또는 4.8로 옮기세요.¹⁹⁸

Fast mode를 사용하기 좋은 경우: - 지연 시간이 병목일 때 작은 변경 사항을 빠르게 반복하는 경우 - 비용보다 속도가 중요한 테스트, 보일러플레이트 또는 반복 코드 생성 - 비슷한 작업 목록을 순차적으로 처리하는 경우

Fast mode를 사용하지 말아야 하는 경우: - 장시간 실행되는 에이전트 작업(전체 실행 구간에서 비용이 여전히 2배로 늘어나요) - 백그라운드 subagent 작업(결과를 기다리는 사람이 없어요) - 예산을 중시하는 세션

Fast mode에는 전체 1M 컨텍스트 창이 포함돼요(v2.1.50+). 입력 토큰이 200K를 넘는 요청을 포함해 전체 컨텍스트에 고정 배수가 적용되며, 장문 컨텍스트 추가 요금은 없어요. 프롬프트 캐싱 및 데이터 상주 지역 배수와는 중첩 적용돼요.⁹⁶¹⁹⁸

운영 참고 사항. Fast mode에는 표준 Opus 제한과 별개인 자체 속도 제한이 있어요. 이를 초과하면 retry-after와 함께 429가 반환돼요(anthropic-fast-*-tokens-* 응답 헤더에서 남은 용량을 확인할 수 있어요). Fast와 표준 사이를 전환하면 프롬프트 캐시가 무효화돼요. 속도가 다른 요청끼리는 캐시된 접두사를 공유하지 않으므로 세션 도중 /fast를 전환하면 캐시 누락이 발생해요. Fast mode는 Batch API 또는 Priority Tier 약정과 함께 사용할 수 없어요.¹⁹⁸

전문가 팁: Fast mode는 opusplan과 함께 사용할 수 없어요(opusplan은 이미 Opus와 Sonnet을 혼합하며, fast mode는 Opus 구간에만 영향을 줘요). 비용보다 지연 시간이 중요할 때 사용하고, 자율 작업이나 일괄 작업에서는 끄세요. /fast를 사용하려면 추가 사용량이 필요해요. Team/Enterprise 관리자는 먼저 이 기능을 활성화해야 할 수 있어요(v2.1.37 수정 사항). CLAUDE_CODE_DISABLE_FAST_MODE=1로 기능을 완전히 비활성화할 수 있어요. v2.1.218부터는 /config model=<x> 또는 Remote Control을 통한 모델 전환으로 fast-mode 상태가 변경되면 Claude Code이 이를 알려 줘요. v2.1.219에서는 전환, 재연결 또는 실패한 조직 확인 후 Remote Control 클라이언트에 오래된 fast-mode 상태가 남는 문제를 수정했어요.^86149195196

Effort Control (v2.1.111+, Opus 4.7)

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

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

Max의 Auto Mode (v2.1.111+)

--dangerously-skip-permissions를 더 안전하게 대체하는 Auto Mode는 --enable-auto-mode 없이도 Anthropic API를 통해 Opus 4.7을 사용하는 Max 구독자에게 제공돼요.¹⁴⁶ 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부터는 별도 활성화가 필요하지 않아요. Auto Mode는 CLAUDE_CODE_ENABLE_AUTO_MODE 없이 AWS Bedrock, Google Vertex AI, Microsoft Foundry에서 작동하며, 이 기능을 끄려는 관리자는 disableAutoMode 관리형 설정을 사용하면 돼요. 같은 릴리스부터 Bedrock, Vertex AI, AWS의 Claude Platform은 기본적으로 Claude Opus 4.8을 사용하며, 저장소의 .claude/settings.local.json에서 autoMode 설정을 더 이상 읽지 않아요. 대신 ~/.claude/settings.json에서 auto-mode 규칙을 설정하세요.¹⁸⁵

기본값을 유지하면서 맞춤 규칙 사용하기 (v2.1.118+). 이전 버전에서는 autoMode.allow, autoMode.soft_deny, autoMode.environment가 양자택일 방식이었어요. 직접 목록을 정의하면 내장 안전 규칙을 잃었어요. $defaults 센티널을 사용하면 이 문제를 해결할 수 있어요. 이 센티널은 배치한 정확한 위치에서 내장 목록으로 인라인 확장되므로 그 전후에 맞춤 규칙을 추가할 수 있어요.¹⁵²

// .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 활성화 안내에 “다시 묻지 않기” 옵션이 표시되므로 자주 사용하는 사용자는 플래그를 스크립트로 지정하지 않고도 설명을 숨길 수 있어요.¹⁵²

파괴적인 명령에 대한 안전장치 (v2.1.183). 이제 Auto mode는 세션에서 사용자가 명시적으로 요청하지 않은 비가역적 명령을 엄격히 차단해요. 로컬 작업을 삭제해 달라고 요청하지 않았을 때의 파괴적인 git 작업(git reset --hard, git checkout -- ., git clean -fd, git stash drop), 이번 세션에서 에이전트가 만들지 않은 커밋에 대한 git commit --amend, 특정 스택을 명시하지 않은 인프라 해체 작업(terraform destroy, pulumi destroy, cdk destroy)이 여기에 포함돼요. 작업을 조용히 잃게 하거나 환경을 철거하는 작업을 정확히 겨냥해 분류기가 끼칠 수 있는 피해 범위를 줄여 줘요. 에이전트는 여전히 이러한 명령을 실행할 수 있지만, 스스로 판단해서가 아니라 사용자가 명시적으로 지시했을 때만 가능해요.¹⁷⁴

모든 셸 명령 분류하기 (v2.1.193). 기본적으로 auto-mode 분류기는 임의 코드 실행 패턴과 일치하는 셸 명령만 검토하며, 일상적인 명령은 건너뛰어요. 새로운 autoMode.classifyAllShell 설정을 사용하면 모든 Bash/PowerShell 명령이 분류기를 거치게 할 수 있어요. 모든 셸 호출을 검토하려는 경우 약간의 지연 시간을 감수하고 더 촘촘한 안전망을 적용하는 방식이에요. 같은 릴리스부터 auto-mode 거부 사유가 기록, 거부 알림, /permissions의 최근 거부 항목에도 표시되므로 차단된 명령이 차단된 이유를 확인할 수 있어요.¹⁷⁹ 보안 강화 규칙 3가지 추가(v2.1.205). 이제 auto mode는 세션 transcript 파일 변조를 차단합니다. 감사 기록 자체에는 에이전트가 접근할 수 없습니다. 또한 컨텍스트에서 확인할 수 없는 변수를 대상으로 rm -rf를 실행하기 전에 사용자에게 확인합니다. 이를 통해 $DIR을 알 수 없는 상태에서 rm -rf $DIR을 실행해 발생하는 유형의 사고를 방지합니다. 그리고 이제 background-task 알림에는 사람의 입력이 없었다는 사실이 명시됩니다. 따라서 transcript 안에 조작된 “사용자가 승인함” 문구를 넣어 실제 승인처럼 처리되도록 만들 수 없습니다.¹⁸³ 세 번째 규칙은 꼭 알아 두어야 할 prompt injection 방어책입니다. 승인은 반드시 승인 채널을 통해 전달되어야 하며, 이제 harness에도 이 전제가 명시되어 있습니다.

명령어 치환으로 치명적인 작업을 숨길 수 없습니다(v2.1.208). 이제 rm -rf ~ 같은 치명적인 삭제 작업이 $(...), backticks 또는 프로세스 치환(<(...)) 안에 들어 있어도 확인 메시지가 표시됩니다. 이 확인은 --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.218). 이전에는 dangerous-rm, background-&, 의심스러운 Windows 경로라는 3가지 검사에서 권한 대화 상자가 표시되어 auto mode가 중단되었습니다. 이제는 auto mode 분류기가 직접 판단하므로, 항목이 감지될 때마다 사용자를 개입시키지 않으면서도 안전 검토는 그대로 진행됩니다. 같은 릴리스에서 이 방식은 auto가 활성화된 plan mode에도 적용됩니다. 정적 분석기가 읽기 전용이라고 입증하지 못한 Bash 명령어도 더 이상 확인 메시지를 표시하지 않으며, 대화 상자로 넘기는 대신 분류기가 판단합니다.¹⁹⁵

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

Push 알림(v2.1.110+)

Remote Control에서 “Claude이 결정할 때 Push”가 활성화되어 있으면, 이제 Claude은 새로운 push-notification 도구를 사용해 자체 판단에 따라 모바일 Push 알림을 보낼 수 있습니다. 기존 Remote Control 모바일/웹 화면과 함께 사용할 수 있습니다.¹⁴⁶ 이제 /context, /exit, /reload-plugins도 Remote Control 클라이언트에서 작동합니다.

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 실행을 분산 추적에 연결합니다. 디버깅을 위해 전체 API 요청 및 응답 본문을 OpenTelemetry 로그 이벤트로 내보내려면 OTEL_LOG_RAW_API_BODIES=1(v2.1.111+)과 함께 사용하세요.¹⁴⁶

기본 바이너리 배포(v2.1.113+)¹⁵⁰

v2.1.113에서는 CLI의 실행 방식이 변경되었습니다. 이제 claude는 번들로 제공되는 JavaScript를 실행하는 대신, 플랫폼별 선택적 의존성을 통해 기본 Claude Code 바이너리를 생성합니다. 설치 및 업데이트 명령어는 그대로이며, 팀에서 배포 스크립트를 변경할 필요도 없습니다.

프롬프트 편집기 단축키(v2.1.113+)¹⁵⁰

프롬프트 편집기에 여러 줄 입력을 위한 readline 방식 탐색과 fullscreen 화면 스크롤 기능이 추가되었습니다.

Subagent 중단 시간 제한(v2.1.113+)¹⁵⁰

이제 처리 도중 멈춘 subagents는 아무런 안내 없이 계속 대기하는 대신 10분 후 명확한 오류와 함께 실패합니다. 스트리밍 API에서 멈춘 프로세스를 더 폭넓게 감지하려면 CLAUDE_STREAM_IDLE_TIMEOUT_MS(v2.1.84+)와 함께 사용하세요.

v2.1.114 안정성 수정¹⁵⁰

v2.1.114(2026년 4월 18일)에는 1가지 수정 사항이 포함되어 있습니다. agent-teams의 팀원이 도구 권한을 요청할 때 권한 대화 상자가 충돌할 수 있던 문제가 수정되었습니다. 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는 모두 표준 MTok당 요금으로 1M 컨텍스트를 제공하며 긴 컨텍스트 추가 요금이 없어요.¹⁴⁸ 이는 최근에 통합된 정책입니다. Opus 4.6 또는 Sonnet 4.6에서 입력 토큰이 200K를 넘으면 입력은 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. 비용 상한 설정: claude --max-budget-usd 5를 사용하면 지출이 상한에 도달하는 즉시 세션이 중단돼요. v2.1.217부터 이 상한은 백그라운드 subagents에도 적용됩니다. 상한에 도달하면 새 subagents 생성이 거부되고 실행 중인 백그라운드 에이전트도 중단돼요. 이전에는 백그라운드 에이전트가 예산 제한을 적용받지 않았습니다.¹⁹⁴
5. 탐색에 계획 모드 사용: 실행하지 않으므로 의도치 않은 고비용 작업을 피할 수 있어요
6. 미리 압축: 컨텍스트가 작을수록 토큰 사용량도 줄어들어요
7. 출력 제한: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
8. 긴급하지 않은 작업에 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가 서로 다른 하위 작업을 병렬로 수행하는 여러 agents를 조율할 수 있어요.⁷⁹

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 전환은 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, Parallel Sessions 중 무엇을 사용해야 하나요?

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   (Opus 5 or Opus 4.8 only, v2.1.219+)
│         Same model, ~2.5× output speed at 2× price
│         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를 전환해요. 동일한 모델을 사용하며, v2.1.219 기준 fast mode를 지원하는 유일한 두 모델인 Opus 5 또는 Opus 4.8의 출력 속도를 최적화해요. 더 저렴한 모델로 전환하는 기능이 아니며, MTok당 $10/$50이므로 비용도 더 저렴하지 않아요.¹⁹⁶¹⁹⁸

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

Claude Code의 권한 시스템은 실행할 수 있는 작업을 세밀하게 제어해요. 보안과 작업 효율을 모두 높이려면 이 시스템을 이해해야 해요. 조직 전체에 권한을 강제하는 관리형 설정은 엔터프라이즈 배포도 참고하세요.

권한 등급

읽기 전용 도구(자동 승인): - 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가 승인을 요청해요. 별도로 설정하지 않는 한 승인은 세션이 끝날 때까지 유지돼요.

EndConversation 도구(v2.1.214). 이제 Claude Code에는 Claude가 2025년부터 claude.ai에서 제공해 온 것과 같은 대화 종료 기능이 있어요. 심각하게 모욕적인 입력이나 지속적인 jailbreak 시도가 드물게 발생하면 Claude는 내장 EndConversation 도구를 사용해 세션을 즉시 종료할 수 있어요. 이는 악용 방지와 모델 보호를 위한 조치이지 작업 흐름 기능이 아니므로, 일반적인 개발 세션에서는 실행되지 않아요.¹⁹⁰¹⁹³

권한 모드

v2.1.200부터 default 모드는 “Manual”로 표시돼요. 이 명칭 변경은 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/ 쓰기 보호와 같은 위협 모델을 “편집이 실행으로 이어지는” 더 넓은 범위의 파일로 확장한 거예요.²⁰⁴

Auto Mode(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 명령, 모든 도구 호출을 전부 승인해요. “dangerous”라는 표현은 의도적으로 사용됐어요. 대부분의 사용 사례에는 Auto Mode를 권장해요.⁵⁴

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)

이제 단일 세그먼트 dir/** 허용 규칙은 <cwd>/dir에만 일치해요(v2.1.214). 기존 규칙을 점검하세요. v2.1.214 이전에는 Edit(src/**) 같은 허용 규칙이 트리 어디에 있든 이름이 src인 모든 디렉터리의 쓰기를 자동 승인했어요. vendor/src/, packages/foo/src/ 등이 모두 해당됐어요. 이제는 작업 디렉터리 바로 아래의 src 디렉터리에만 일치해요. 기존의 모든 깊이 일치 동작이 필요하다면 규칙을 Edit(**/src/**)로 바꾸세요. deny와 ask 규칙은 모든 깊이에서 일치하는 기존 동작을 유지해요. 이번 변경은 자동 승인 범위만 좁히며 차단 범위는 줄이지 않아요. 업그레이드 후 조용히 일치하지 않게 된 규칙은 오류 대신 새로운 권한 확인으로 나타나므로, 단일 세그먼트 형식으로 작성된 허용 규칙을 확인하세요. 같은 릴리스에서 hook의 if: 조건에도 동일한 현재 작업 디렉터리 범위가 적용됐어요(매처 참고).¹⁹⁰

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을 포함한 파일 읽기 도구에 적용돼요. 기존 규칙을 이전해 경고를 없애고 의도를 명확히 유지하세요.¹⁸⁷

“Always allow”는 저장소 루트에 저장돼요(v2.1.211). 이제 “Always allow” 확인 옵션으로 만든 권한 규칙은 현재 worktree가 아닌 저장소 루트에 기록돼요. 따라서 한 worktree에서 부여한 승인은 여러 세션은 물론 해당 저장소의 모든 worktree에서도 유지돼요. 더 이상 병렬 checkout마다 같은 명령을 다시 승인할 필요가 없어요.¹⁸⁸

MCP 도구 패턴:

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

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

v2.1.166부터 거부 규칙은 도구 이름 위치에 glob도 사용할 수 있어요. 도구 이름 자리에 단독 "*"를 지정하면 모든 도구를 거부하므로, 먼저 전부 차단한 다음 제한된 일부만 다시 허용할 수 있어요. 반면 허용 규칙은 MCP 이외의 glob을 거부해요. 같은 방식으로 모든 도구를 광범위하게 허용할 수 없으므로 기본 정책이 제한적으로 유지돼요.²⁰²

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

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

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

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

v2.1.186부터 이러한 Agent(...) 규칙은 이름이 지정된 subagent 생성에도 적용돼요. 이제 Agent(agent_type) 거부 규칙과 Agent(x,y) 허용 타입 제한은 익명의 Task 방식 생성뿐 아니라 workflow, --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"
    ]
  }
}

추가 디렉터리는 monorepo에서 작업하거나 Claude가 인접 디렉터리의 코드를 참조해야 할 때 꼭 필요해요.

Sandbox 모드

파일 시스템과 네트워크 격리를 활성화하세요.

> /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 설정은 sandbox 안에서 실행되는 명령이 자격 증명 파일과 비밀 환경 변수를 읽지 못하게 차단해요. sandbox 안의 명령이 비밀 정보를 유출하지 못하도록 다층 방어를 제공해요.¹⁷⁶

v2.1.216부터 sandbox.filesystem.disabled 설정은 네트워크 외부 전송 제어를 유지하면서 파일 시스템 격리를 건너뛰어요. 파일 시스템 격리 환경 때문에 빌드 도구가 작동하지 않지만 외부 트래픽에는 도메인 허용 목록을 계속 적용하고 싶을 때 유용해요.¹⁹²

v2.1.219부터 sandbox.network.strictAllowlist 설정은 허용 목록에 없는 호스트를 확인 없이 즉시 거부해요. 기본적으로 sandbox 안의 명령이 allowedDomains에 없는 호스트에 연결하면 권한 확인이 표시돼요. strictAllowlist를 켜면 연결이 바로 거부돼요. 아무도 확인에 응답하지 않아 작업이 멈출 수 있는 무인 실행 환경에 적합한 설정이에요. CI, 백그라운드 agent, 야간 반복 작업처럼 “예상하지 못한 외부 연결을 확인해 달라”는 정책 자체가 적합하지 않은 환경에서 사용하세요. 이 설정으로 네트워크 제어의 세 요소가 완성돼요. allowedDomains는 허용 대상을 지정하고, 아래의 deniedDomains는 광범위한 허용 범위에서 예외를 제외하며, strictAllowlist는 그 밖의 대상을 확인할지 바로 실패 처리할지 결정해요.¹⁹⁶

sandbox가 적용되면: - 파일 시스템 접근이 프로젝트 디렉터리로 제한돼요 - 네트워크 접근이 제어돼요 - 특정 명령은 sandbox 제한에서 제외돼요 - autoAllowBashIfSandboxed가 true이면 Bash 명령이 자동으로 허용돼요

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

보안 참고 사항(v2.1.34+): 이전에는 sandbox.excludedCommands나 dangerouslyDisableSandbox를 통해 sandbox 적용에서 제외된 명령이 autoAllowBashIfSandboxed가 활성화된 경우 Bash 확인 권한 규칙을 우회할 수 있었어요. 이 문제는 v2.1.34에서 수정됐어요.⁸⁷ v2.1.38부터 sandbox 모드에서는 .claude/skills 쓰기가 차단되므로 prompt injection으로 skill 정의를 수정할 수 없어요.⁸⁸ v2.1.77에는 denyRead 영역 안에서 읽기 접근을 다시 허용하는 allowRead sandbox 파일 시스템 설정이 추가됐어요. 디렉터리 트리 대부분을 차단하면서 특정 하위 디렉터리만 허용 목록에 넣고 싶을 때 유용해요.¹¹⁹

.claude/ agent 설정 예외(v2.1.121+): 이제 --dangerously-skip-permissions는 .claude/skills/, .claude/agents/, .claude/commands/ 쓰기에 대한 승인을 요청하지 않아요.¹⁵⁴

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

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

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

• sandbox.network.deniedDomains는 더 넓은 allowedDomains 와일드카드가 허용하는 호스트도 개별적으로 차단해요. 전체 허용 정책을 다시 작성하지 않고 pastebin, 파일 공유 서비스 또는 악성으로 알려진 호스트를 차단하려면 차단 목록을 사용하세요. 허용 목록 밖의 모든 연결을 확인 없이 거부하려면 위에서 설명한 sandbox.network.strictAllowlist(v2.1.219)와 함께 사용하세요.
• 래퍼 명령 거부 규칙. 이제 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/를 가리키는 심볼릭 링크이므로, 이전 규칙 형태로는 실제 경로를 감지하지 못했어요.

v2.1.214의 권한 기본 차단 강화:¹⁹⁰

한 릴리스에서 여러 권한 검사 허점이 수정됐으며, 분석기가 확신할 수 없으면 확인을 요청하는 기본 차단 원칙이 일관되게 적용됐어요.

• Windows PowerShell 5.1 우회 문제가 수정됐어요. 이전에는 PowerShell 5.1 세션에서 실행한 명령이 권한 검사를 빠져나갈 수 있었어요.
• Bash 파일 서술자 리디렉션은 판단할 수 없으면 차단해요. bash와 권한 분석기가 서로 다르게 해석하는 리디렉션 형식은 이제 바로 실행되지 않고 확인을 요청해요.
• 10,000자를 넘는 명령은 항상 확인을 요청해요. 이전에는 매우 긴 명령을 잘못 판단할 수 있었지만, 이제는 자동으로 실행하지 않아요.
• [[ ]] 안의 zsh 첨자와 수정자는 확인을 요청해요. [[ ]] 비교 안의 변수 첨자와 수정자는 실행되지 않는 텍스트로 취급됐지만 코드를 실행할 수 있으므로 이제 승인이 필요해요.
• 안전하지 않은 help/man 변형은 더 이상 자동 승인되지 않아요. 일부 호출은 문서를 읽는 것처럼 보이면서도 안전하지 않은 옵션, 명령 치환 또는 백슬래시 경로를 실행할 수 있었어요.
• 원격 세션 확인 순서. 이제 원격 세션의 권한 확인은 로컬 확인 대화 상자보다 먼저 진행될 수 없어요.
• docker 데몬 리디렉션 플래그는 확인을 요청해요. 이전에는 --url, --connection, --identity 또는 Podman의 원격 모드가 포함된 docker 명령(Podman의 docker 호환 명령 포함)이 확인 없이 실행됐어요. 이러한 플래그는 명령의 대상을 완전히 다른 데몬으로 바꿔요.
• 쓰기를 수행하도록 지정하면 file은 읽기 전용 자동 승인을 받지 않아요. 이제 file -m/--magic-file과 -f/--files-from은 읽기 전용으로 자동 승인되지 않고 권한이 필요해요.

Hooks는 어떻게 작동하나요?

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

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

사용할 수 있는 이벤트

SessionStart source 값. SessionStart hook 입력에는 세션이 어떻게 시작되었는지를 알려주는 source 필드가 포함돼요. 값은 "startup", "resume", "clear", "compact" 중 하나예요. v2.1.214부터 fork로 시작된 세션은 "resume" 대신 source: "fork"를 보고해요. 이는 v2.1.212에서 /fork가 백그라운드 방식으로 변경된 것에 대응하는 hook 측 변경 사항이에요. SessionStart hook이 source에 따라 분기한다면(예: "resume"일 때만 컨텍스트를 다시 주입하는 경우), 일치 목록에 "fork"도 포함되도록 업데이트하세요.¹⁹⁰

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가 조용히 누락되어 쉼표가 포함된 matcher의 hook이 전혀 실행되지 않았어요.¹⁷⁸ v2.1.195부터 하이픈이 포함된 식별자를 사용하는 matchers(예: code-reviewer, mcp__brave-search)는 실수로 부분 문자열을 일치시키지 않고 정확히 일치해요. 따라서 단순히 해당 문자열을 포함한다는 이유만으로 의도하지 않은 도구에서 matcher가 실행되지 않아요. 하이픈이 포함된 MCP 서버의 모든 도구를 일치시키려면 mcp__brave-search__.*처럼 명시적인 패턴을 사용하세요.¹⁷⁹

v2.1.214부터 Hook if: 경로 조건은 cwd 범위로 제한돼요. 권한 허용 규칙에 적용된 것과 같은 단일 세그먼트 범위 변경 사항(권한 규칙 구문 참고)이 hook if: 조건에도 적용돼요. 이제 dir/** 같은 조건은 트리의 모든 dir/이 아니라 <cwd>/dir에만 일치해요. 다시 모든 깊이에서 일치시키려면 **/dir/**를 사용하세요.¹⁹⁰

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는 루프와 충돌하지 않으면서 “놓친 내용은 이것이니 계속 진행하세요”라고 안내할 수 있는 조정 채널을 제공해요.²⁰³

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

더 세밀하게 제어하려면 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."
  }
}

참고: 최상위 decision 및 reason 필드는 PreToolUse에서 더 이상 권장되지 않아요. 대신 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, 이메일, Pushover) - 백그라운드에서 실행할 수 있는 기록 및 원격 측정 - 중요하지 않은 후처리(분석, 백업)

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

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

셸 command hooks(type: "command") 외에도 Claude Code은 스크립트 대신 인공 지능 추론을 사용해 조건을 평가하는 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 네트워크 프록시를 통해 라우팅돼요. 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 입력을 나타내는 자리 표시자로 $ARGUMENTS를 사용하세요. 두 유형 모두 model(기본값은 빠른 모델)과 timeout 필드를 지원해요. 지원되는 이벤트는 PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Stop, SubagentStop, TaskCompleted예요. TeammateIdle은 prompt/agent hooks를 지원하지 않아요.

MCP Tool Hooks(v2.1.118+)

이제 hooks는 Bash 하위 프로세스로 서버를 호출하는 래퍼를 만들지 않고도 type: "mcp_tool"을 통해 MCP 도구를 직접 호출할 수 있어요.¹⁵²

{
  "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 Tool Hooks에 hookSpecificOutput.updatedToolOutput을 통해 도구 출력을 대체하는 기능이 추가됐어요. v2.1.121부터는 동일한 필드를 모든 PostToolUse hook에서 사용할 수 있어요. 여기에는 기본 제공 도구(Bash, Read, Edit, Glob, Grep 등), subagent 도구, MCP 도구가 모두 포함돼요. 모든 도구의 출력에서 민감한 콘텐츠를 가리거나, 이후 처리 작업을 위해 구조를 정규화하거나, agent가 결과를 읽기 전에 메타데이터를 주입할 때 사용할 수 있어요.¹⁵⁴

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 네트워크 프록시를 통해 라우팅되어 도메인 허용 목록이 적용돼요. 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 작업 공간 신뢰(v2.1.51+): 이제 statusLine 및 fileSuggestion hook 명령을 대화형 모드에서 실행하려면 작업 공간 신뢰를 수락해야 해요. 이를 통해 잠재적인 보안 위험을 차단해요.⁹⁸

실용적인 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