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

요약: Claude Code은 코드베이스를 읽고, 명령을 실행하며, 권한, hooks, MCP 통합, subagents로 구성된 계층형 시스템을 통해 파일을 수정하는 에이전트형 CLI입니다. 5가지 핵심 시스템인 설정, 권한, hooks, MCP, subagents를 숙달하면 생산성을 크게 높일 수 있습니다. 각 작업에 맞는 모델 등급을 선택하세요. 복잡한 추론에는 Opus, 일반 작업에는 Sonnet, 빠른 탐색에는 Haiku를 사용하거나, 품질만 중요하다면 Opus로 통일하세요. 반드시 실행해야 하는 작업에는 프롬프트가 아닌 hooks를 사용하세요. 2026년 8월 14일부터 Pro, Max, Team의 새 세션에서는 auto mode가 기본 권한 모드입니다. 8월 7일에 발표되었고 전환일에 실제 동작이 확인되었습니다. 분류기가 자율 작업을 검토하며, 사용자가 설정한 defaultMode는 일회성 전환 안내를 수락하지 않는 한 유지됩니다. Shift+Tab으로 모든 세션의 모드를 전환할 수 있고, disableAutoMode로 조직 전체에서 비활성화할 수 있습니다.²⁰³ 기본 모델은 요금제에 따라 다릅니다. Max, Team Premium, Enterprise(v2.1.251부터 좌석 기반), Anthropic API에서는 Claude Opus 5가 기본이고, Pro와 Team Standard에서는 Sonnet 5가 기본입니다. 기본 정가 기준으로 네이티브 1M 컨텍스트와 MTok당 $2/$10의 가격이 적용됩니다. 출시 당시의 할인 가격이 영구 가격으로 확정되어 예정되었던 9월 1일 인상은 시행되지 않습니다.²²⁸²⁰⁷ 2026년 6월 30일에 나온 v2.1.197의 모든 환경 Sonnet 5 기본 설정은 이제 과거가 되었으며, v2.1.219부터 opus 별칭은 Claude Opus 5를 가리킵니다. 7월 1일에 나온 v2.1.198부터 subagents는 기본적으로 백그라운드에서 실행되고, Chrome용 Claude이 정식 출시되었으며, 백그라운드 agents는 worktree 코드 작업을 마치면 커밋하고, 푸시하고, 초안 PR을 열 수 있습니다. 백그라운드 세션에서는 Notification hook(agent_needs_input/agent_completed)도 실행됩니다. 7월 2일에 나온 v2.1.199는 최대 5개의 중첩된 slash-skill 호출을 불러오며 구독자의 일시적인 429 오류를 자동으로 재시도합니다. 7월 3일에 나온 v2.1.200은 default 권한 모드의 이름을 “Manual”로 변경했습니다. 이 변경은 CLI, --help, VS Code, JetBrains 전체에 적용되지만 설정값은 바뀌지 않았고 manual도 별칭으로 사용할 수 있습니다. 또한 AskUserQuestion 대화 상자는 더 이상 기본적으로 자동 진행되지 않습니다. 7월 6일에 나온 v2.1.202는 “Dynamic workflow size” /config 제어 항목을 추가하고 /review <pr>의 빠른 단일 검토와 /code-review <level> <pr#>을 분리했습니다. 그러나 v2.1.223에서 이 분리가 취소되어 /review는 다시 /code-review의 별칭이 되었고, 인자 없는 /code-review는 마지막으로 사용한 effort 수준을 재사용합니다. 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 분류기가 담당합니다. 신뢰하지 않는 폴더에서는 agent frontmatter hooks가 실행되지 않습니다.¹⁹⁵ 7월 24일에 나온 v2.1.219는 Claude Opus 5(claude-opus-5)를 기본 Opus 모델로 지정했습니다. 1M 컨텍스트, 최대 128K 출력, Opus 4.8과 동일한 MTok당 $5/$25의 가격, 기본 활성화된 thinking, 기본값이 high인 effort, 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개 미만의 agents를 목표로 합니다. stream-json에서는 중첩 subagent 전달도 지원합니다. 7월 25일에 나온 v2.1.220에는 버그 수정과 안정성 개선만 포함됩니다. 8월 4일부터 7일까지 나온 v2.1.221–226에는 세션 간 메시징, 즉 macOS와 Linux에서 세션 사이에 사용하는 SendMessage/ListAgents, 클라우드 세션용 자체 호스팅 runners(Team/Enterprise), SHA-256 고정 기능이 있는 archive plugin 소스, JWT/SigV4를 인식하는 sandbox 자격 증명 마스킹, VSCode Focus 보기, 자체 worktree를 갖는 /fork 복사본이 추가되었습니다. 또한 세션당 subagents 200개 제한과 ultraplan이 제거되었습니다.^{199200201202196197198} 8월 10일부터 12일까지 나온 v2.1.227–229는 수정 사항이 중심이지만 편의 기능도 추가되었습니다. plugin marketplaces에서 command 소스를 지원합니다. 로컬 프로그램이 plugin 디렉터리를 출력하고 세션마다 다시 해석하며, mode: "link"는 해당 디렉터리를 직접 사용합니다. claude remote-control --continue는 가장 최근 Remote Control 세션을 재개합니다. ListAgents는 연결이 끊긴 Remote Control 피어를 offline, 클라우드 세션을 cloud로 표시합니다. /commit-push-pr은 위험한 git 플래그인 --force, --amend, --no-verify를 더 이상 자동 승인하지 않습니다. 최신 모델에서 Write 도구는 Edit와 같은 규칙을 따르므로, 읽지 않은 파일을 덮어쓸 때 같은 세션에서 먼저 읽을 필요가 없습니다.^235233234 8월 13일에 나온 v2.1.232에서는 subagent 분기가 기본값이 되었습니다. subagent_type: "fork"는 전체 대화와 프롬프트 캐시를 상속하며, 대화형 세션에서 팀원이 아닌 대상이 생성되면 백그라운드에서 실행됩니다. 프롬프트에서 다른 활성 세션의 이름을 @로 언급할 수도 있습니다. Claude은 이를 SendMessage로 전달하며, 정확히 하나의 활성 세션과 일치하는 이름만 입력해도 이제 참조 확인 없이 전달됩니다. 대화형 세션 이름은 컴퓨터별로 고유한 name-word-word 형태로 유지됩니다. 세션 간 수신 제어 항목은 /config 행으로 표시됩니다. 또한 GitLab 기능 동등성을 제공합니다. sandbox에서 9가지 GitLab 토큰 계열을 가리고, glab CLI 자격 증명을 보호하며, 중첩 하위 그룹을 포함한 기본 gitlab.com marketplace URL을 GitHub URL처럼 복제합니다.²³² 8월 14일에 나온 v2.1.233은 GitLab 기능 동등성을 --worktree까지 확장했습니다. MR URL을 지원하며 claude agents에서는 !N으로 표시합니다. Bash 명령을 위한 Linux 메모리 제한(CLAUDE_CODE_TOOL_MEMORY_LIMIT)과 WebFetch 캐시 TTL 조절 항목도 추가했습니다. 또한 Opus 4.8, Sonnet 5, Fable 5 및 이후 모델에서 할 일 및 작업 추적 도구를 기본적으로 비활성화했습니다. CLAUDE_CODE_ENABLE_TODO_TOOLS=1로 복원할 수 있습니다. auto mode 회귀 문제 때문에 v2.1.232에 포함되었던 Windows Bash 권한 변경 사항 일부도 되돌렸습니다.²³¹ 8월 17일에 나온 v2.1.234부터 Claude Code은 claude.ai 사용량 제한이 초기화되면 세션을 자동으로 계속 진행합니다. /config의 “Continue automatically at usage limit”에서 비활성화할 수 있습니다. /permissions와 /add-dir을 작업 도중 열 수 있고, CLAUDE_CODE_PROJECT_DIR_NAME과 백그라운드 작업 확인 기능인 /goal(CLAUDE_CODE_GOAL_CHECKIN_MINUTES)이 추가되었습니다. 인증된 glab CLI가 있는 저장소의 바닥글에는 GitLab MR 배지(!N)가 표시됩니다. 기본 제공 claude-api skill은 참조 문서를 필요할 때만 불러와 컨텍스트 비용을 약 200k 토큰에서 약 25k 토큰으로 줄였습니다.²³⁰ 8월 18일부터 20일까지 나온 v2.1.235–238에는 기본 제공 “Concise” 출력 스타일이 추가되었습니다. 결과를 먼저 제시하고 서문이나 작업 설명을 생략하는 방식이며 /config의 Output style에서 선택할 수 있습니다. ANTHROPIC_DEFAULT_MODEL 환경 변수는 새 세션이 시작할 모델을 설정합니다. /model에서 선택한 값은 계속 우선 적용되고 저장되며, 이 점이 ANTHROPIC_MODEL과 다릅니다. 선택적 spellcheck 설정은 설치된 aspell, hunspell, ispell을 사용해 프롬프트의 철자가 틀린 단어에 밑줄을 표시합니다. keybindingFlavor 설정에서 "readline"을 사용하면 Bash처럼 Ctrl+W가 이전 공백까지 삭제합니다. 이 설정은 v2.1.261에서 폐지되었으며, 이제 readline 방식만 사용합니다. plugin marketplaces와 프로젝트 .mcp.json에서는 headersHelper를 지원합니다. 이는 명령을 실행해 유효 기간이 짧은 HTTP 헤더를 발급합니다. 카탈로그 항목의 helper는 명령을 표시한 뒤 설치하거나 업데이트할 때만 실행됩니다. 프로젝트, plugin, agent 범위의 helper는 폴더 신뢰 대화 상자를 거친 뒤 상속된 자격 증명 환경 변수 없이 실행됩니다. 세션 간 SendMessage에는 notify_when_idle이 추가되어 다른 로컬 세션이 다음에 유휴 상태가 될 때 한 번 알림을 보냅니다. 권한 동작도 2가지 변경되었습니다. auto mode는 이제 Monitor 허용 규칙을 별도로 처리하여 Monitor 명령도 Bash와 같은 분류기 검토를 받습니다. 또한 macOS sandbox의 와일드카드 읽기 거부 규칙(**/.env)은 허용된 읽기 영역 안에서도 우선 적용되며, 거부된 파일의 이름을 바꿔 우회할 수 없습니다. auto mode 분류기는 Bedrock, Vertex AI, Foundry와 원격 측정이 꺼진 환경에서 Claude API 기본값을 사용합니다.²²³ v2.1.273부터 해당 게이트웨이는 “당분간” 로컬 분류기를 기본으로 사용하며, CLAUDE_CODE_AUTO_MODE_SERVER=1로 플랫폼의 서버 측 분류기를 선택할 수 있습니다.²¹⁷ 8월 21일에 나온 v2.1.239는 /claude-api upgrade를 추가했습니다. 이 명령은 Python 프로젝트를 anthropic 0.x에서 1.x로 이전합니다. 데이터 상주 workspace에 적용되는 미국 내 추론 전용 1.1배 할증료를 비용 추정치에 반영합니다. /cost, 상태 표시줄, --max-budget-usd에 적용됩니다. 세션 간 메시징을 Windows에서도 지원하고, claude.ai와 동기화된 plugins를 name@synced로 표시합니다. 동기화된 plugins는 claude plugin enable/disable로 관리할 수 있지만, 같은 이름의 로컬 설치를 덮어쓰지는 않습니다. ListAgents는 세션 자체 이름과 활성 teammates를 표시합니다. "readline"은 Bash 단어 단위 키 조작까지 지원합니다. /goal 확인 간격은 30분에서 1시간, 다시 2시간으로 늘어났습니다. Bedrock, Vertex, Foundry에서도 전체 화면 renderer를 사용할 수 있습니다. 8월 22일부터 23일까지 나온 v2.1.240–241은 버그 수정 릴리스입니다. 같은 주의 문서 요약에는 2가지 상태 변경이 기록되었습니다. /design은 artifacts를 통해 편집 가능한 UI artboards의 canvas를 게시하는 연구 미리 보기 skill입니다. Pro, Max, Team, Enterprise에서 사용할 수 있으며 v2.1.233 이상이 필요합니다. Remote Control은 연구 미리 보기 단계를 벗어났으며, claude remote-control을 실행하는 컴퓨터가 Claude 앱에 장치 카드로 표시됩니다.²⁰⁵ 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는 최대 5단계까지 자체 sub-agents를 재귀적으로 생성할 수 있었습니다. 이 기본값은 v2.1.216까지 유지되다가 위에서 설명한 대로 v2.1.217에서 비활성화되었습니다. AWS_REGION이 설정되지 않은 경우 Bedrock은 ~/.aws에서 리전을 읽으며 /status에 출처가 표시됩니다. /plugin에는 marketplace 검색창이 추가되었고, claude_code.lines_of_code.count OTEL 지표에는 model 속성이 추가되었습니다. 2026년 6월 9일에 나온 v2.1.170부터 Opus보다 높은 새 모델 등급인 Claude Fable 5를 claude update 후 /model fable을 사용해 Claude Code에서 선택할 수 있습니다. 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를 통해 수십 개에서 수백 개의 agents를 백그라운드에서 조율합니다. Opus 4.8의 Fast mode는 2.5배 빠른 속도에 표준 요금의 2배가 적용됩니다. 간소화된 시스템 프롬프트는 Haiku, Sonnet, Opus 4.7 및 이전 모델을 제외한 모든 모델의 기본값이 되었습니다. /simplify는 다시 정리 작업만 수행하는 검토 기능이 되어 /code-review --fix와 분리되었습니다. claude agents에서 ! <command>를 사용해 백그라운드 shell 세션을 생성할 수 있습니다. plugins는 defaultEnabled: false를 선언할 수 있고, 스트리밍 도구 실행은 항상 활성화됩니다. stdio MCP 서버는 환경 변수로 CLAUDE_CODE_SESSION_ID와 CLAUDECODE=1을 받습니다. v2.1.153은 plugin marketplaces에 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 244 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는 실행을 보장하지만 프롬프트는 그렇지 않습니다: 모델의 동작과 관계없이 매번 실행해야 하는 linting, 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 서버를 연결하고, 엔터프라이즈 배포까지 다뤄요. 하지만 시작하는 데는 이 내용이 필요하지 않아요.

사전 요구 사항: 기존 npm 방식에만 Node 22 이상이 필요해요(v2.1.198부터 18에서 상향되었으며, 현재 설치 문서에는 “Node.js 22 or later”라고 명시되어 있어요. 2026년 8월 7일 확인). 권장되는 네이티브 설치 프로그램은 Node에 의존하지 않아요. macOS / Linux / Windows 10 이상을 지원해요. Claude Pro, Max, Team, Enterprise 구독이나 토큰 사용량에 따라 요금을 지불하는 Anthropic API 키로 사용할 수 있어요. 플랫폼별 세부 정보, 문제 해결 방법, 네이티브 바이너리 방식(v2.1.113부터 기본값)은 Claude Code을 어떻게 설치하나요?를 참고하세요. 이 가이드의 최신 릴리스 근거는 릴리스마다 갱신돼요. 현재 확인 일자는 변경 로그의 최신 행을 참고하세요.²⁴⁴

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 (20 concurrent default)      │    │
│  │   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 │
└─────────────────────────────────────────────────────────┘

핵심 계층: 기본 대화가 이루어지는 곳이에요. 모든 메시지, 파일 읽기, 도구 출력은 공유 창의 컨텍스트를 사용해요(표준 200K 토큰⁹¹, Opus 4.6 또는 확장 컨텍스트 모델 사용 시 1M 토큰). 컨텍스트가 가득 차면 Claude는 이전 결정을 놓치기 시작하고 결과물의 품질도 떨어져요. 이 계층에서는 토큰마다 비용이 발생해요.

위임 계층: Subagents는 새로운 컨텍스트로 생성되어 특정 작업에 집중한 뒤 요약을 반환해요. 탐색 결과 전체가 기본 대화의 컨텍스트를 부풀리지 않고 결론만 돌아와요. 탐색 작업에는 더 저렴한 모델 등급을 사용하거나, 비용보다 품질이 더 중요하다면 모든 작업에 기본 모델을 사용할 수 있어요.

확장 계층: MCP는 외부 서비스(데이터베이스, GitHub, Sentry)를 연결해요. Hooks는 모델의 동작과 관계없이 셸 명령이 반드시 실행되도록 보장해요. Skills는 Claude가 자동으로 적용하는 분야별 전문 지식을 담아요. Plugins는 이 모든 요소를 배포할 수 있도록 하나로 묶어요.

핵심 요점: 대부분의 사용자는 핵심 계층에서만 작업하면서 컨텍스트와 비용이 계속 늘어나는 상황을 지켜봐요. 숙련된 사용자는 탐색과 전문 작업을 위임 계층으로 보내고, 자신의 작업 흐름에 맞게 확장 계층을 설정한 다음, 핵심 계층은 조율과 최종 결정에만 사용해요.

목차

1. Claude Code을 어떻게 설치하나요?
2. 빠른 시작: 첫 번째 세션
3. 핵심 상호작용 모드
4. 설정 시스템 자세히 알아보기
5. 어떤 모델을 선택해야 하나요?
6. Claude Code의 비용은 얼마인가요?
7. 의사 결정 프레임워크
8. 권한 시스템은 어떻게 작동하나요?
9. Hooks는 어떻게 작동하나요?
10. MCP(Model Context Protocol)란 무엇인가요?
11. Subagents란 무엇인가요?
12. 확장 사고 모드란 무엇인가요?
13. 출력 스타일
14. Slash Commands
15. Skills는 어떻게 작동하나요?
16. Plugin 시스템
17. 메모리는 어떻게 작동하나요?
18. 이미지 및 멀티모달 입력
19. 음성 모드
20. Git 연동은 어떻게 작동하나요?
21. IDE에서 Claude Code을 어떻게 사용하나요?
22. 고급 사용 패턴
23. 원격 및 백그라운드 에이전트 [연구 프리뷰]
24. Chrome의 Claude
25. Slack의 Claude Code [연구 프리뷰]
26. 웹의 Claude Code [연구 프리뷰]
27. Microsoft 365의 Claude(2026년 5월)
28. 성능 최적화
29. 문제를 어떻게 디버깅하나요?
30. 엔터프라이즈 배포
31. 키보드 단축키 참고 자료
32. 모범 사례
33. 작업 흐름 예시
34. 마이그레이션 가이드
35. 대상별 안내
36. 빠른 참조 카드
37. 변경 로그
38. 참고 자료

Claude Code는 어떻게 설치합니까?

시스템 요구 사항

Claude Code는 macOS 13 이상, Ubuntu 20.04 이상/Debian 10 이상, Windows 10 이상(네이티브 또는 WSL)에서 실행됩니다. 시스템에는 최소 4 GB RAM과 활성 인터넷 연결이 필요합니다.⁹² 셸은 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는 각각 장단점이 다른 3가지 인증 방식을 지원합니다:

Claude Console (API 결제)

platform.claude.com(이전 console.anthropic.com)을 통해 Anthropic의 API에 직접 연결합니다. 계정을 만들고 결제를 설정한 다음 CLI를 통해 인증합니다. Console에서는 전체 API 접근 권한과 사용량 기반 결제를 제공합니다. 전용 “Claude Code” 작업 공간이 자동으로 생성됩니다. 이 작업 공간에서는 API 키를 만들 수 없지만 사용량은 모니터링할 수 있습니다. v2.1.243부터 /login → Anthropic Console에서는 API 키 생성 방식과 함께 키가 필요 없는 “Console 계정으로 로그인” 방식(권장)을 제공합니다. 따라서 API 키를 허용하지 않는 조직도 Console 자격 증명으로 로그인할 수 있습니다.²²⁷

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

게이트웨이 힌트 헤더(v2.1.273, 선택적 사용): CLAUDE_CODE_GATEWAY_HINT_HEADERS=1을 설정하면 Claude Code가 LLM 게이트웨이에서 라우팅하고 관찰할 수 있는 5개의 요청 헤더인 x-claude-code-request-class, x-claude-code-agent-type, x-claude-code-prev-tool-durations, x-claude-code-compaction, x-claude-code-context-compacted를 추가합니다.²¹⁷

확인

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

v2.1.268부터 claude auth status --json에는 CLI가 실제로 읽는 구성 디렉터리인 configDirectory가 포함됩니다. CLAUDE_CONFIG_DIR 간접 지정으로 실제 디렉터리가 불분명할 때 유용합니다.²¹⁶

v2.1.273부터 Claude 계정으로 로그인할 때 claude.ai plugins에 대한 접근 권한도 요청합니다.²¹⁷

계정이나 조직을 전환할 때 흔히 사용하는 작업 흐름은 다음과 같습니다:

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

중첩된 subagents도 이제 전달됩니다(v2.1.219). 처음에는 깊이 1의 subagents만 표시되었습니다. 이제 깊이 2 이상에서 생성된 subagents도 전달된 스트림에 나타나며, 각 항목에는 해당 subagent를 생성한 Agent 호출의 tool_use 아이디가 키로 지정됩니다. 따라서 파이프라인은 평면적인 텍스트 목록만 보는 대신 위임 트리를 재구성할 수 있습니다. 이 기능은 같은 릴리스에서 기본 중첩 생성 깊이를 3으로 복원한 변경과 직접 연결됩니다. 이 전달 기능이 없었다면 3개 깊이 중 2개가 보이지 않았을 것입니다.¹⁹⁶

백그라운드로 전환된 subagents의 출력도 더 이상 사라지지 않습니다(v2.1.273): subagent가 실행 도중 백그라운드로 전환된 후에도(예: CLAUDE_AUTO_BACKGROUND_TASKS 사용 시) SDK 및 stream-json 출력에서 해당 subagent의 남은 메시지와 최종 보고서가 누락되지 않습니다.²¹⁷

종료 코드:

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

# 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

# Restricted mode for eval harnesses and shared machines (v2.1.248+)
claude --restricted -p "query" --tools "Read,Grep,Glob"

# Unattended hosts: deny anything that would prompt (v2.1.259+)
claude -p "run the nightly checks" --permission-prompts none

제한 모드(v2.1.248+): --restricted 또는 CLAUDE_CODE_RESTRICTED=1은 공유 머신에서 claude를 구동하는 평가 하네스를 위해 설계되었습니다. 명령이나 코드를 실행하는 내장 도구와 WebFetch를 제거하며, 이를 사용하려면 --tools에 개별적으로 지정해야 합니다. default 프리셋은 인정되지 않습니다. 또한 내장 파일 도구의 접근 범위를 작업 디렉터리로 제한하고, 관리형 설정과 --settings만 불러오며 사용자, 프로젝트 및 로컬 설정 파일은 무시합니다. bypassPermissions와 클라우드 세션 생성도 허용하지 않습니다.²⁰⁶²⁰⁹

--permission-prompts none(v2.1.259): 무인 호스트를 위한 보조 옵션입니다. 권한 프롬프트를 표시해야 하는 모든 작업은 자동으로 거부되지만, 자동 모드를 포함한 활성 권한 모드는 사용자의 개입 없이 내릴 수 있는 모든 결정을 계속 처리합니다. 프롬프트를 거부하는 대신 MCP 도구에 위임하는 --permission-prompt-tool과 혼동하지 마세요. CLI 참조 문서에는 아직 새 플래그가 기재되지 않았으며, CHANGELOG가 출처입니다.²¹¹

비대화형 세션에서 cd가 여러 턴에 걸쳐 유지됩니다(v2.1.265): stream-json 입력을 받는 -p 세션, Agent SDK 세션 및 클라우드 세션은 이제 새 사용자 메시지가 입력될 때마다 셸 작업 디렉터리를 초기화하지 않습니다. 한 턴에서 실행한 cd가 다음 턴에도 유지됩니다.²¹⁵

--system-prompt-snapshot off(v2.1.267): 기본적으로 대화는 모든 요청에서 기록된 시스템 프롬프트를 재사용합니다. 이 플래그를 사용하면 요청할 때마다 시스템 프롬프트를 새로 렌더링합니다. 프롬프트 텍스트를 반복해서 수정할 때 각 실행이 스냅샷 대신 최신 변경 사항을 반영하도록 전환하는 옵션이지만, 스냅샷이 보호하도록 설계된 프롬프트 캐시 안정성은 낮아집니다.²¹⁶

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"

실행 중인 세션을 /cd로 이동하기(v2.1.169+; v2.1.246부터 설정 즉시 적용): /cd path는 프롬프트 캐시를 깨뜨리지 않고 작업 디렉터리를 변경합니다. v2.1.246부터는 새 디렉터리의 프로젝트 설정, hooks, .mcp.json 서버(일반적인 승인 프롬프트 적용), skills 및 에이전트가 --resume을 기다리지 않고 이동 직후 적용됩니다.²³⁹²²⁶

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 아이디를 표시하는 한 줄로 간소화되었습니다.¹⁹² v2.1.221부터 포크된 세션은 원래 세션의 체크아웃에서 작업하지 않고 자체 worktree를 생성합니다. 따라서 대안을 탐색하는 포크가 기본 세션의 커밋되지 않은 파일과 더 이상 충돌하지 않으며, 복사본을 보내 실험할 때 발생하던 위험 요소가 사라졌습니다.¹⁹⁹ v2.1.232에서는 subagents에도 포크가 기본 동작으로 적용됩니다. subagent_type: "fork" subagent는 전체 대화와 프롬프트 캐시를 상속하며, 대화형 세션에서 팀원이 아닌 에이전트를 생성하면 이제 기본적으로 백그라운드에서 실행됩니다.²³²

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

계획 모드

계획 모드에서는 Claude이 읽기 전용 탐색만 수행하도록 제한되며, 파일 편집, bash 실행 및 파괴적인 작업은 허용되지 않습니다. Claude은 구현 방식을 설계하고 계획 파일에 작성한 후, 작업을 실행하기 전에 사용자의 승인을 기다립니다.

계획 모드 시작하기:

# 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이 계획 모드로 전환됩니다(복잡한 작업에서는 자동으로 전환되거나 Shift+Tab으로 직접 전환)
2. 읽기 전용 도구인 Read, Glob, Grep, WebSearch, WebFetch를 사용하여 코드베이스를 탐색합니다
3. 계획을 .claude/plans/{session-slug}.md에 작성합니다
4. ExitPlanMode로 계획 모드를 종료하고 검토할 계획을 제시합니다
5. 사용자는 계획을 승인하거나, 변경을 요청하거나, 거부합니다

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

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

승인할 때 맥락을 자동으로 지우는 방식을 권장합니다. 계획에 새로운 맥락 창을 온전히 제공하므로 계획 준수 능력이 크게 향상되며, 이전 대화의 방해 없이 Claude이 더 오래 계획에 집중할 수 있습니다.

계획 모드를 사용할 때: - 아키텍처 결정이 필요한 새 기능 구현 - 먼저 접근 방식을 검토하려는 여러 파일에 걸친 리팩터링 - 수정에 앞서 탐색이 필요한 익숙하지 않은 코드베이스 - 유효한 접근 방식이 여러 개이고 사용자가 선택에 관여하려는 모든 작업

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

화면 읽기 프로그램 모드(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는 계층형 구성 시스템을 사용합니다. 상위 수준은 하위 수준의 설정을 재정의하며 엔터프라이즈 설정은 어떤 방법으로도 우회할 수 없으므로, 이 계층 구조를 이해해야 합니다.

구성 계층 구조

프롬프트에서 구성 설정하기: /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-5",
  "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": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  },
  "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": {
    "label": "Team tips",
    "tips": [
      "Custom tip 1",
      {"id": "tip-2", "text": "Custom tip 2", "cooldownSessions": 5, "priority": 1}
    ],
    "tipsFile": "~/.claude/team-tips.json",
    "excludeDefault": true
  },
  "skillOverrides": {
    "legacy-skill": "off",
    "manual-only-skill": "user-invocable-only",
    "compact-skill": "name-only"
  },
  "includeGitInstructions": false,
  "modelOverrides": {
    "bedrock": "us.anthropic.claude-opus-5",
    "vertex": "claude-opus-5",
    "foundry": "claude-opus-4-8"
  },
  "autoMemoryDirectory": ".claude/memory",
  "sandbox": {
    "enableWeakerNetworkIsolation": true
  }
}

skillOverrides는 팀에 대규모 skill 라이브러리가 있지만 런타임에 노출되는 범위를 더 엄격하게 제한하려는 경우 유용합니다. skill을 모델과 슬래시 선택기 모두에서 숨기려면 off, 이름으로 호출할 수 있게 유지하면서 모델 선택 대상에서는 제외하려면 user-invocable-only, 전체 설명 없이 skill 이름만 표시하려면 name-only를 사용하세요.¹⁵⁶

최신 설정(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): 권한 대화 상자를 표시하는 대신 허용 목록에 없는 호스트에 대한 샌드박스 명령의 접근을 묻지 않고 거부합니다. 샌드박스 모드를 참조하세요.¹⁹⁶
• workflowSizeGuideline(v2.1.219): 권고용 Dynamic 워크플로 크기 지침을 /config뿐만 아니라 사용자, 프로젝트 또는 관리형 설정 파일에서도 지정할 수 있습니다. Dynamic 워크플로는 기본적으로 medium 지침(“에이전트 수를 15개 미만으로 유지”)을 사용합니다. 설정 파일에서 값을 제공하면 /config의 해당 행은 숨겨집니다. 강제되는 한도가 아닌 권고 사항입니다. Subagents를 참조하세요.¹⁹⁶

최신 설정(v2.1.242–243):

• modelPicker(사용자 또는 관리형, v2.1.242 이상): 순서와 레이블이 지정된 모델 목록으로 /model 선택기를 구성합니다. options 배열을 포함하는 객체이며, 각 행에는 필수 model과 선택 사항인 label 및 description이 들어갑니다. model 값은 그대로 사용되므로 별칭, Anthropic ID, Bedrock/Vertex/Foundry/게이트웨이 ID를 모두 사용할 수 있습니다. 선택 사항인 replaceBuiltInOptions 불리언도 지정할 수 있습니다. 기본값인 false는 기본 제공 목록 뒤에 행을 추가하고, true는 사용자가 지정한 행, Default, 그리고 세션에서 이미 실행 중인 모델만 표시합니다. Claude Code는 관리형 설정, --settings, 사용자 설정에서 이 키를 읽고 프로젝트 및 로컬 설정에서는 무시하므로, 복제한 저장소가 선택기의 레이블을 바꿀 수 없습니다. 이 키를 설정한 소스 중 우선순위가 가장 높은 소스의 전체 목록이 적용됩니다. availableModels 허용 목록은 여전히 모든 행에 적용되며, 레이블은 선택기에 표시되는 이름만 바꿀 뿐 실제로 실행되는 모델은 바꾸지 않습니다.²²⁷²²⁵
• promptCacheTtl / subagentPromptCacheTtl(모든 파일, v2.1.242 이상): 요청 버킷별로 "5m" 또는 "1h"를 지정할 수 있으므로, API 키 및 클라우드 제공업체 사용자는 기본 대화의 캐시를 1시간으로 유지하면서 subagents의 캐시는 5분으로 설정할 수 있습니다. 캐싱 전략을 참조하세요.²²⁷²²⁵
• modelPricing(관리형, v2.1.243 이상): 조직이 계약한 모델별 요금과 할인 배율입니다. /cost, 상태 표시줄, 원격 측정 비용 수치에서 정가 대신 사용됩니다. 비용 확인을 참조하세요.²²⁷

최신 설정(v2.1.247): - feedbackDrafts (v2.1.247): 새로운 SendFeedback tool을 제어합니다. 세션에서 문제가 발생하면 Claude가 피드백 보고서 초안을 작성하며, 사용자는 /feedback에서 검토한 후 전송할 수 있습니다. 이 설정으로 초안 작성을 끌 수 있습니다. Slash Commands의 /feedback 항목을 참조하세요.²²² - spinnerTipsOverride 형식 확장 (v2.1.247): 이제 팁 항목에는 일반 문자열뿐 아니라 {id, text, cooldownSessions, priority} 객체도 사용할 수 있으며, 객체에 tipsFile 및 label 키가 추가되어 조직에서 기본 제공 팁과 자체 팁을 함께 순환 표시할 수 있습니다(위 예시는 확장된 형식을 보여 줍니다). 설정 문서에는 아직 새 키가 나와 있지 않으며, CHANGELOG가 유일한 출처입니다.²²²

새로운 설정 (v2.1.248–251):

• desktopSessionCleanupPeriodDays (v2.1.248): 데스크톱에서 작성된 세션이 대화 기록 정리 대상에서 제외되는 기간의 상한을 지정합니다. 이 설정값보다 함께 적용된 수정 사항이 더 중요합니다. 이전에는 Claude Desktop 및 Cowork 세션이 cleanupPeriodDays(기본값 30일)가 지나면 사라졌지만, 이제 조직 정책에서 보존 기간을 관리하지 않는 한 앱에 있는 동안에는 정리되지 않습니다.²⁰⁶
• 프로젝트 env 제한 (v2.1.251): 이제 프로젝트 수준의 .claude/settings.json에 있는 env 블록에서는 CLAUDE_CONFIG_DIR, CLAUDE_CODE_TMPDIR 또는 TMPDIR/TMP/TEMP를 설정할 수 없습니다. 대신 셸, 사용자 또는 관리형 설정에서 지정해야 합니다. 따라서 복제한 저장소가 Claude Code의 설정 및 임시 파일 기록 위치를 다른 곳으로 바꿀 수 없습니다.²⁰⁶

새로운 설정 (v2.1.257-259):

• timeFormat / timeZone (v2.1.257): Claude Code가 시간, 즉 작업 완료 시 표시되는 시각과 대화 기록의 타임스탬프를 표시하는 방식을 제어합니다. timeFormat에는 12시간제, 24시간제, 24시간제 UTC 또는 명시적인 strftime 패턴을 사용할 수 있으며, timeZone에는 시간대 이름을 지정합니다. 설정 문서에는 아직 이 항목이 나와 있지 않으며, CHANGELOG가 출처입니다.²¹¹
• permissions.blockReadsOutsideWorkingDirectories (v2.1.257): 세션의 작업 디렉터리 외부에 있는 파일을 읽는 작업을 전면 차단합니다. 이 설정을 사용하지 않으면 이제 auto mode가 세션에서 이러한 읽기 작업을 처음 시도할 때 한 번 확인합니다(Auto Mode 참조).²¹¹ v2.1.273에서는 2가지 허점도 막았습니다. 검사기가 완전히 분석할 수 없는 Bash 명령은 검사를 건너뛰는 대신 확인을 요청하며, 이 설정에서는 저장소 설정이 선택한 메모리 디렉터리를 불러오거나 회상하거나 색인하지 않습니다.²¹⁷
• managedMcpServers / managedSourcesBehavior: 관리형 범위의 키이며 Enterprise Deployment에서 다룹니다. 조직이 모든 사용자에게 MCP 서버를 제공하는 기능(v2.1.259)과 관리형 소스 간 선택적 병합 기능(v2.1.257에서 개선됨)에 사용됩니다.²¹¹²²¹

새로운 설정 (v2.1.261):

• bashOutputMaxChars / taskOutputMaxChars (v2.1.261): 나머지 내용을 파일에 저장하기 전에 Claude가 인라인으로 받는 명령 출력과 백그라운드 작업 출력의 최대 크기를 각각 128K자까지 늘립니다. 이는 명령의 작업 출력 파일을 다시 읽는 범위(기본값 30,000자, 최대 150,000자)를 설정하는 BASH_MAX_OUTPUT_LENGTH 환경 변수와는 다른 방식으로 작동합니다. 이 키는 인라인 출력과 영구 파일 저장을 구분하는 임계값을 제어하며, 임계값을 넘은 출력은 잘리는 대신 Claude가 필요할 때 읽을 수 있는 파일에 저장됩니다.²¹⁴ v2.1.265부터는 영구 저장에도 상한이 생겼습니다. 디스크에 저장되는 tool 결과는 1 GB로 제한되며, 저장된 파일이 잘리면 대화에 표시되는 미리 보기에서 이를 알려 줍니다.²¹⁵

새로운 설정 (v2.1.267-269):

• maxEffortLevel (v2.1.267): 사용자가 선택할 수 있는 effort level의 상한을 지정합니다. 최상위 수준이나 modelSettings 아래의 모델별 설정에 지정할 수 있으며, Bedrock, Vertex, Foundry를 포함한 모든 provider에 적용됩니다. 사용자는 상한보다 낮은 level을 계속 선택할 수 있으며, 관리자 측에서 /effort를 보완하는 설정입니다.²¹⁶
• bashEditDiffEnabled (v2.1.269): Bash tool이 파일 편집을 처리하면 명령으로 변경된 파일의 diff가 tool 결과에 포함되므로, sed 방식의 편집이 실제로 무엇을 변경했는지 대화에서 확인할 수 있습니다.²¹⁶

설정 찾아보기: 가장 많이 검색되는 플래그

특정 설정을 이름으로 찾다가 이곳에 왔다면 아래의 짧은 색인을 활용하세요. 각 항목에는 해당 설정이 도입된 릴리스와 특정 범위에 속하는 경우 그 범위가 나와 있습니다.

ANTHROPIC_API_KEY=sk-ant-...                    # Direct API authentication
ANTHROPIC_AUTH_TOKEN=token                      # Custom authorization header
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Additional request headers; credential/org/routing/API-behavior headers set from managed or project settings require approval (v2.1.251)[^238]

모델 설정:

ANTHROPIC_MODEL=claude-opus-4-7                 # Override default model (Apr 16, 2026)
ANTHROPIC_DEFAULT_MODEL=claude-opus-5           # Model new sessions START on; a /model pick overrides + persists (v2.1.236)
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5      # What the `opus` alias resolves to (Opus 5 since v2.1.219)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Default model for subagents; an agent's model: field and per-spawn picks win (v2.1.251 demoted it from override to default)[^238]
CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1              # Force every subagent onto CLAUDE_CODE_SUBAGENT_MODEL (or the main model), ignoring agent-definition and per-spawn overrides -- the pre-v2.1.251 behavior, opt-in (v2.1.257)[^243]
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]
CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS=3000  # Extend the LLM gateway /v1/models discovery timeout (default 3s; v2.1.269+)[^252]
CLAUDE_CODE_GATEWAY_HINT_HEADERS=1              # Send five x-claude-code-* hint headers (request-class, agent-type, prev-tool-durations, compaction, context-compacted) for LLM gateways (opt-in; v2.1.273+)[^253]
CLAUDE_CODE_AUTO_MODE_SERVER=1                  # Use the platform's server-side auto-mode classifier on Bedrock/Vertex/Foundry; since v2.1.273 the local classifier is the default there "for now"[^253]

동작 제어:

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
CLAUDE_CODE_RESTRICTED=1                        # Restricted mode: no command/code tools or WebFetch unless named in --tools; only managed settings load (v2.1.248+)[^238]
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+)
CLAUDE_CODE_PROMPT_CACHE_TTL=1h                 # Main-conversation cache TTL, 5m or 1h; beats the promptCacheTtl setting (v2.1.242+)[^234]
CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL=5m        # TTL for subagents, workflows, forks, compaction, titles; beats subagentPromptCacheTtl (v2.1.242+)[^234]
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_WEBFETCH_CACHE_TTL_MS=900000        # WebFetch per-URL session cache TTL (default 15 min; v2.1.233+)[^226]
CLAUDE_CODE_WEBFETCH_DEADLINE_MS=300000         # WebFetch hard deadline: a server that never finishes its response fails the fetch after 300s by default; 0 disables (v2.1.268+)[^252]
CLAUDE_CODE_PROJECT_DIR_NAME=myproj             # Short name for the per-project transcript directory, for hosts that give each session its own config dir (v2.1.234+)[^227]
CLAUDE_CODE_GOAL_CHECKIN_MINUTES=30             # How long background tasks may keep a /goal waiting before Claude checks in on them; 0 disables (v2.1.234+)[^227]
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=200       # Per-session subagent-spawn cap (default 200 in v2.1.212–223; the default cap was REMOVED in v2.1.224 — set this to reimpose one)[^206][^218]
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_WORKFLOW_PREFIX_STAGGER_MS=0        # Disable the v2.1.229 workflow fan-out stagger (same-prefix sibling agents launch staggered so they read the cached prompt prefix instead of re-paying it)[^224]
CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS=64   # Raise the Workflow tool's per-run concurrent agent limit, 1-256, for inference-bound fan-outs (v2.1.269+)[^252]
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                    # Read-back window from the Bash working output file (default 30,000 chars, hard ceiling 150,000)
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]
CLAUDE_CODE_TOOL_MEMORY_LIMIT=4096              # Opt-in Linux memory cgroup (MB) for Bash tool commands — a runaway build can't stall the session (v2.1.233+)[^226]
CLAUDE_CODE_ENABLE_TODO_TOOLS=1                 # Offer the TodoWrite/TaskCreate-family tools on models outside v2.1.268's allowlist (Claude 3.x, Opus 4.0-4.7, Sonnet 4.0-4.6, Haiku 4.5); elsewhere they are off unless set (first turned off on newer models in v2.1.233)[^226][^252]
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; not settable from project-settings env (v2.1.251)[^238]
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; not settable from project-settings env, nor are TMPDIR/TMP/TEMP (v2.1.251)[^50][^238]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Hold ALL native-1M models to 200K via auto-compaction (v2.1.223 widened scope)[^103][^217]
CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1  # Let unrecognized model IDs exceed the assumed context window (v2.1.223)[^217]
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_CODE_BG_TASKS_REPORT_RUNNING=0         # Restore pre-v2.1.269 behavior: remote/headless sessions may report "waiting for your input" while background agents still run[^252]
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+); as of v2.1.273 also puts real agent, skill, plugin, and MCP server names on cost and token metrics[^253]
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+)
OTEL_METRICS_INCLUDE_REPOSITORY=1             # Tag OTel metrics and events with vcs.* repository attributes; with OTEL_LOG_TOOL_DETAILS, commit events carry vcs.ref.head.* (v2.1.269+)[^252]
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 잘림 제한을 설정할 수 있습니다.¹⁹⁰

v2.1.265 게이트웨이 텔레메트리: 이제 Claude apps 게이트웨이 세션은 게이트웨이의 관리형 설정에서 OTEL_EXPORTER_OTLP_ENDPOINT로 수집기를 지정한 경우 게이트웨이의 릴레이를 거치지 않고 OpenTelemetry를 수집기로 직접 내보냅니다. 수집기를 지정하지 않은 세션은 계속 릴레이를 사용합니다. 같은 릴리스에서는 터미널 세션과 동일하게 Claude Desktop 및 Cowork가 Claude apps 게이트웨이를 통해 전송하는 텔레메트리에 user.email과 user.groups도 추가됩니다.²¹⁵

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

셸 / 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 호출자 ID(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 기본값은 Claude API와 마찬가지로 high이며, low, medium, high, xhigh, max의 전체 단계를 사용할 수 있습니다. 토큰 비용보다 성능이 더 중요한 경우 max 작업 강도를 테스트하라는 것이 Anthropic의 공식 이전 지침입니다. Fast mode는 MTok당 $10/$50의 가격으로 Opus 5를 지원합니다(Fast Mode 참조).¹⁹⁷¹⁹⁸

Claude Fable 5.1(2026년 9월 1일): Fable 등급의 새로운 최상위 모델이며, v2.1.257부터 fable 별칭이 가리키는 모델입니다(ANTHROPIC_DEFAULT_FABLE_MODEL이 다른 모델로 고정되지 않은 경우). 이제 best는 “사용할 수 있는 최신 Fable 모델”을 의미합니다. 최소 버전 조건에는 설명이 필요합니다. 모델 설정 문서에는 별칭이 v2.1.255에서 변경되었다고 나오고 모델 페이지에는 Fable 5.1이 “Claude Code v2.1.255 이상을 요구”한다고 나오지만, 2.1.253부터 2.1.256까지는 npm에 게시되지 않았습니다. 따라서 이를 포함하면서 실제로 설치할 수 있는 첫 릴리스는 v2.1.257(9월 1일)입니다. 모델 ID는 claude-fable-5-1이며 Bedrock에서는 anthropic.claude-fable-5-1입니다. Fable 5와 동일한 등급 및 토큰당 가격으로 입력 $10/MTok, 출력 $50/MTok이며, 1M 컨텍스트, 최대 출력 128K, 항상 활성화되는 적응형 사고, 기본값이 high인 effort를 제공합니다. 다만 장시간 실행되는 에이전트형 세션에서 중요한 가격 변경 사항이 하나 있습니다. 캐시 읽기 비용은 입력 가격의 0.025배인 $0.25/MTok(2.5%)로, 표준 10%보다 저렴합니다. 이 요율은 Fable 5.1과 Mythos 5.1에만 적용되며, 캐시 쓰기는 표준 가격인 5분 $12.50, 1시간 $20으로 유지됩니다. 신뢰할 수 있는 지식 기준 시점은 2026년 6월이며 학습 데이터도 2026년 6월까지로, 현재 Claude 모델 중 가장 최신입니다. 지원 종료는 2027년 9월 1일 이전에는 이루어지지 않습니다. Fable 5와 비교해 호환성을 깨뜨리는 변경 사항은 3가지입니다. 도구 사용을 강제하면 오류가 반환되고, 이전 모델은 이 모델의 사고 블록을 읽을 수 없으며, 이전 턴을 편집하면 사고 블록이 무효화됩니다. 추가된 변경 사항은 5가지입니다. 메시지별 작업 강도(베타), 턴 범위 시스템 메시지(베타), 도구 호출 사이의 진행 상황 업데이트(display: "updates", 베타), 더 저렴한 캐시 읽기, 콘텐츠 출처 정보입니다. Claude Mythos 5.1은 사양이 같은 동일한 모델이며 Project Glasswing의 초대 전용으로 제공됩니다. 출시와 함께 Fable 5는 Opus 4.8/4.7/4.6/4.5 및 Sonnet 4.6/4.5와 함께 문서의 레거시 모델 표로 이동했습니다. 릴리스 노트에는 게이트웨이와 관련된 한 가지 주의 사항이 있습니다. Claude 앱 게이트웨이 세션에서는 현재 fable과 best가 계속 Fable 5를 가리킵니다. 아직 5.1용으로 설정되지 않은 게이트웨이는 이를 거부하므로, 해당 환경에서는 /model을 통해 Fable 5.1을 명시적으로 선택하세요. v2.1.260 이전에는 /model 선택기에 Fable 5.1이 표시되지 않았으므로, 명시적으로 선택하려면 전체 명령인 /model claude-fable-5-1을 입력해야 했습니다. 아래의 출시 직후 수정 사항을 참조하세요. 요금제별 기본값은 변경되지 않았습니다. 프리미엄 요금제에서는 Opus 5, Pro 및 Team Standard에서는 Sonnet 5입니다.^211218219

Fable 5.1 출시 직후 수정 사항(v2.1.260, 9월 3일): 출시 후 첫 릴리스에서 4가지 미비점이 수정되었습니다. 이제 Fable 5.1을 사용할 수 있는 조직의 /model 선택기에 해당 모델이 표시됩니다. 수정 전에는 /model claude-fable-5-1처럼 전체 명령을 입력해야만 모델이 인식되었습니다. 이제 Fable 5.1의 프롬프트 캐싱에는 도구 결과 뒤에 첨부된 컨텍스트도 포함됩니다. 이전에는 이 컨텍스트가 모든 도구 호출 턴에서 캐시되지 않은 입력으로 다시 전송되어, 0.025배라는 캐시 읽기 비용의 장점을 가장 필요한 장기 에이전트형 세션에서 조용히 약화했습니다. 세션 도중 /effort를 변경해도 더 이상 프롬프트 캐시가 무효화되지 않습니다. 또한 이제 model: fable 에이전트는 ANTHROPIC_DEFAULT_FABLE_MODEL 고정값의 [1m] 태그를 따르며, 200K 컨텍스트 창으로 조용히 실행되지 않습니다.²¹²

Claude Fable 5(2026년 6월 9일, 2026년 9월 1일부터 레거시): Opus보다 상위에 위치한 새로운 모델 등급입니다. Anthropic에서 가장 강력하고 지능적인 모델로, 테스트한 거의 모든 벤치마크에서 최첨단 성능을 보이며 수백만 토큰의 컨텍스트에서도 일관성을 유지하도록 설계되었습니다. Fable 5는 일반 사용에 안전하도록 만든 “Mythos급” 최전선 모델입니다. 사이버, 생명 화학 및 모델 증류 관련 질의에서는 Opus 4.8로 전환하는 안전 분류기를 탑재했습니다. Claude Mythos 5는 같은 모델이지만 승인된 연구자를 위해 이러한 보호 장치를 해제한 버전입니다. v2.1.170(2026년 6월 9일)부터 Claude Code에서 선택할 수 있게 되었습니다. claude update를 실행한 다음 /model fable을 사용하세요. 이 짧은 별칭은 v2.1.257부터 Fable 5.1을 가리키므로, 현재 Fable 5를 선택하려면 /model claude-fable-5를 사용해야 합니다. 구독 요금제에는 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와 마찬가지로 전체 effort 단계(low/medium/high/xhigh/max, 기본값은 high)를 지원합니다. Fable 5에서는 thinking을 끌 수 없습니다. 세션 thinking 토글, alwaysThinkingEnabled 설정, MAX_THINKING_TOKENS=0 모두 아무런 효과가 없으며 항상 적응형으로 추론합니다. 전체 fable 계열 설정 항목은 Opus의 설정과 대응합니다. ANTHROPIC_DEFAULT_FABLE_MODEL은 fable 별칭이 가리키는 모델을 고정하고(Bedrock/Vertex/Foundry에서 유용), DISABLE_PROMPT_CACHING_FABLE은 Fable을 prompt caching에서 제외하며, 기업용 게이트웨이에는 콘텐츠 기반 자동 대체가 적용됩니다. 이제 /model opus는 Opus 5를 선택합니다(기본 effort는 high, 가장 어려운 작업에는 /effort xhigh). 별도 설정 없이 적용되는 기본 모델은 사용 중인 요금제를 따릅니다. 프리미엄 요금제에서는 Opus 5, Pro/Team Standard에서는 Sonnet 5가 기본입니다. 최고 성능이 필요할 때는 /model fable로 Fable 등급을 명시적으로 선택하세요. v2.1.257 기준으로는 Fable 5.1이 선택됩니다.^238197207219

Opus 4.7(2026년 4월 16일): 이전 세대의 최상위 모델이며, 지금도 제한 없이 사용할 수 있습니다. 표준 가격으로 1M 토큰 컨텍스트 창을 제공하며 긴 컨텍스트 추가 요금은 없습니다. 최대 출력은 128K이고 적응형 thinking만 지원하며(extended thinking은 제거됨), 코딩 및 에이전트형 작업의 시작점으로 권장되는 새로운 xhigh effort 단계가 추가되었습니다.¹⁴⁵ 신뢰할 수 있는 지식 기준일은 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% 높습니다.¹⁴⁴ 새로운 tokenizer를 사용하므로 같은 텍스트에서도 토큰 수가 약 1배에서 1.35배로 늘어날 수 있습니다. max_tokens 여유분과 compaction 실행 기준을 높이세요.¹⁴⁵ Vision은 최대 2,576 px / 3.75 MP 이미지와 1:1 픽셀 좌표를 지원합니다.¹⁴⁵

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

요금제별 기본 모델(Claude Code):²⁰⁷

Opus 4.7에서 호출자에게 영향을 주는 Messages API 호환성 변경 사항:¹⁴⁵

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

작업 예산(베타 헤더 task-budgets-2026-03-13)을 사용하면 output_config.task_budget을 통해 전체 에이전트형 루프의 목표 토큰 수를 모델에 알려줄 수 있습니다. 최솟값은 20K 토큰입니다.¹⁴⁵

Opus 4.6(레거시): claude-opus-4-6에서 계속 사용할 수 있으며 1M 컨텍스트와 최대 128K 출력을 지원합니다. 에이전트형 코딩 성능을 높이려면 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), 적응형 thinking만 지원합니다. 신뢰할 수 있는 지식 기준일은 2026년 1월입니다. 가격은 입력/출력 MTok당 $2/$10이며, 이제 표준 정가입니다. Anthropic은 출시 당시 2026년 8월 31일까지 적용되는 도입 가격으로 $2/$10을 발표했지만, 이후 이 가격을 유지했습니다. 가격 페이지에는 예정되었던 9월 1일의 $3/$15 인상이 “시행되지 않을 것”이라고 명시되어 있으며, v2.1.243에서는 /model 선택기와 기본 제공되는 claude-api skill이 $2/$10을 기간 한정 할인 가격이 아닌 정가로 표시하도록 갱신되었습니다.²²⁸ 이는 Opus 5의 $5/$25보다 60% 저렴합니다. Claude Code에서 Sonnet 5의 effort 매개변수 기본값은 high입니다. 변경하려면 값을 명시적으로 설정하세요. /model sonnet 또는 /model claude-sonnet-5로 선택할 수 있습니다.¹⁸⁰ v2.1.197(2026년 6월 30일)에서는 당시 새 세션의 Claude Code 기본 모델이 Sonnet 5로 변경되었습니다. 현재는 표준 등급(Pro, Team Standard)에서만 기본 모델로 유지되며, 프리미엄 요금제와 Anthropic API에서는 Opus 5가 기본입니다. 위의 요금제 표를 참조하세요.¹⁸¹²⁰⁷

Sonnet 4.6(2026년 2월 17일, 현재 Sonnet 5로 대체됨): 균형 잡힌 모델로, claude.ai와 Claude Cowork 전반에서 Sonnet 4.5를 대신해 기본 모델이 되었습니다.⁹³ 가격은 Sonnet 4.5와 동일하게 MTok당 $3/$15입니다. 에이전트형 검색 성능을 높이면서 토큰 사용량은 줄였습니다. Extended thinking, 적응형 thinking, 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에서는 같은 세션에 $0.50-$2.25가 들어 5배 더 비쌉니다. Opus는 실제로 어려운 문제에만 사용하세요.¹

각 모델을 사용해야 하는 경우

Haiku: 탐색, 간단한 파일 검색, 짧은 질문을 수행하는 subagents에 사용하세요. Opus보다 약 5배 저렴하고 응답도 빠릅니다. 깊이 있는 추론이 필요하지 않은 백그라운드 작업에 적합합니다. Sonnet: 비용이 중요한 일상적인 개발 작업에 적합한 주력 모델이며, standard tier, Pro, Team Standard의 기본 모델입니다(기본 1M 컨텍스트, 표준 정가 기준 MTok당 $2/$10, 예정되었던 9월 1일 가격 인상은 취소되었습니다).^181228207 기능 구현, 버그 수정, 테스트 작성, 코드 리뷰 등 대부분의 코딩 작업을 처리합니다. 변경 이력: v2.1.197(2026년 6월 30일)은 오랫동안 이 가이드를 포함한 여러 곳에서 Sonnet 5를 모든 환경의 기본 모델로 설정한 버전으로 소개되었습니다. 그러나 요금제별 동작을 설명하는 모델 설정 문서에 따르면 premium/API의 기본 모델은 v2.1.154부터 Opus 4.8로, v2.1.219부터 Opus 5로 결정되므로, 여기서 “모든 환경”은 실제로 standard tier를 의미했습니다. Sonnet 4.6은 2026년 6월까지 Sonnet의 역할을 담당했습니다.^93147207 더 저렴한 토큰 비용, 짧은 지연 시간 또는 경제적인 subagents 운용이 필요할 때는 Sonnet을 사용하세요.

Opus: 심층 추론을 위한 등급입니다. v2.1.219부터 opus 별칭은 Claude Opus 5를 선택합니다(MTok당 $5/$25, 1M 컨텍스트, effort 기본값은 high).¹⁹⁷ 아래 문단은 2026년 4월 16일 출시 당시의 Opus 4.7을 설명하며, 변경 이력으로 보존되어 있습니다.¹⁴⁴¹⁴⁷ 더 높은 비용의 추론은 아키텍처 결정, 까다로운 디버깅, 복잡한 시스템 이해, 보안 분석, 장기적인 에이전트 작업처럼 효과가 큰 곳에 사용하세요. Opus 4.7은 Opus 4.6보다 SWE-Bench의 실제 운영 작업을 3배 더 많이 해결하며, CursorBench에서 70%의 점수(Opus 4.6은 58%)를 기록하고, 93개 작업으로 구성된 내부 코딩 벤치마크의 해결률을 13% 높입니다.¹⁴⁴ Opus 4.7에서 Claude Code의 effort 기본값은 xhigh이며, /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 opus
> /model sonnet
> /model haiku

시작할 때:

claude --model opus

환경을 통해:

export ANTHROPIC_MODEL=opus

settings.json에서:

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

모델 선택기 자체 구성하기(modelPicker, v2.1.242 이상): 내장 모델 목록만 메뉴로 사용하지 않고, 사용자 또는 관리형 설정 파일에서 /model이 제공할 모델을 원하는 순서와 레이블로 나열할 수 있습니다. 각 행에는 --model이 허용하는 모든 표기법(Vertex 및 Bedrock ID 포함)을 사용할 수 있는 model과 선택 사항인 label, description을 지정합니다. replaceBuiltInOptions를 true로 설정하면 해당 행들과 Default, 현재 세션의 모델만 표시됩니다. 이 키에서는 프로젝트 및 로컬 설정이 무시되며, availableModels 허용 목록은 여전히 행을 필터링합니다. Claude Code은 제공할 수 없는 행을 제거하고, 아직 선택할 수 없는 행은 그 이유와 함께 회색으로 표시하며, 남는 행이 없으면 내장 모델 목록으로 돌아갑니다.²²⁷²²⁵

{
  "modelPicker": {
    "options": [
      { "model": "us.anthropic.claude-opus-4-8", "label": "Opus (production)" },
      {
        "model": "us.anthropic.claude-sonnet-4-6",
        "label": "Sonnet (production)",
        "description": "Day-to-day work"
      }
    ]
  }
}

subagents 전용 설정:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

v2.1.251부터 CLAUDE_CODE_SUBAGENT_MODEL은 모든 설정을 덮어쓰는 대신 subagent의 기본 모델을 설정합니다. 에이전트 정의의 model:과 생성 시 명시적으로 지정한 모델이 이 값보다 우선합니다.²⁰⁶ v2.1.257부터 CLAUDE_CODE_SUBAGENT_MODEL_FORCE를 사용하면 이전 동작을 선택적으로 복원할 수 있습니다. 이 변수를 사용하면 CLAUDE_CODE_SUBAGENT_MODEL을 모든 subagent에 적용하며, 해당 값이 설정되지 않은 경우에는 기본 대화의 모델을 적용합니다. 생성 시 지정한 모델과 에이전트 정의의 model:은 무시됩니다.²¹¹

대체 모델 체인(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을 설정하세요. v2.1.223부터 이 변수의 적용 범위가 변경되었습니다. 이제 알려진 변형의 고정 목록에만 적용되는 것이 아니라, 기본 1M 창을 갖춘 모든 모델을 자동 압축을 통해 200K로 제한합니다. 자동 압축이 실제로 세션을 200K로 제한하지 못하면 시작 시 경고가 표시됩니다. 특정 모델 계열의 비용 예측 가능성을 위해 이 값을 설정하면 새 1M 모델이 출시되는 날부터 자동으로 적용되므로, 더 이상 새 모델에서 제한이 아무런 안내 없이 해제되지 않습니다. 같은 릴리스에서는 자동 압축이 인식되지 않는 모델 ID의 세션도 추정 컨텍스트 창 안에 유지하여 제한을 넘어서지 않도록 합니다. 실제로 더 큰 창을 사용하는 사용자 지정 ID를 등록하는 게이트웨이에서는 CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1을 설정해 이전 동작을 복원할 수 있습니다.²⁰⁰

v2.1.247부터 Sonnet 5의 기본 자동 압축 창은 전체 1M 컨텍스트를 사용합니다. 이제 1M 창을 사용하는 세션은 약 934K가 아닌 약 967K 토큰에서 자동으로 압축됩니다.²²² v2.1.260에서는 제한 근처의 자동 압축이 나머지 1M 등급으로 확대됩니다. 이제 Opus 및 Fable 세션도 1M 토큰 제한에 도달하기 직전에 압축되며, 매우 큰 컨텍스트에서 실행되는 복구 압축도 더 이상 10분 후 시간 초과되지 않습니다.²¹²

v2.1.271부터 --resume은 [1m] 창을 유지합니다. 세션의 모델 계열이 구성된 기본 모델과 다르더라도 세션을 재개할 때 [1m] 접미사가 더 이상 제거되지 않습니다.²¹⁶

v2.1.273에서는 컨텍스트 측정기와 자동 압축이 advisor-tool 작업을 실제 컨텍스트 크기의 약 2배로 계산하던 문제를 해결했습니다. 이 문제로 인해 실제 창의 절반 정도에서 자동 압축이 실행되고 있었습니다.²¹⁷

현재 모델 확인

> /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에서는 fast mode 지원 대상에서 Opus 4.7이 제외되었으며, Sonnet, Haiku 또는 Fable에서는 처음부터 이 기능을 사용할 수 없었습니다. 이 기능은 Claude API(Claude Managed Agents 포함)에서만 제공되는 연구 미리보기로, Amazon Bedrock, Google Cloud, Microsoft Foundry 또는 AWS의 Claude Platform에서는 사용할 수 없습니다. 사용하려면 승인이 필요하므로 계정 관리자에게 문의하거나 대기자 명단에 등록하세요.¹⁹⁶¹⁹⁸

Remote 세션(v2.1.271): 이제 fast mode가 클라우드 세션과 자체 호스팅 러너를 포함한 Claude Code Remote 세션에도 적용됩니다. 호스트의 fast mode 설정을 따르거나 세션에서 직접 /fast를 입력할 수 있으며, 두 방식 모두 조직에서 fast mode를 허용한 경우에만 작동합니다. 같은 릴리스에서는 /fast off 문제도 수정되었습니다. 이제 조직에서 fast mode를 비활성화했을 때 “Fast mode unavailable”이라고 응답하지 않고 fast mode를 정상적으로 끕니다.²¹⁶

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

Opus 4.7의 함정(v2.1.219). 지원되지 않는 모델이 모두 같은 방식으로 작동하는 것은 아닙니다. 이제 speed: "fast"를 지정해 claude-opus-4-7에 요청하면 표준 속도로 조용히 대체되지 않고 오류를 반환합니다. 이 차이를 알아 두어야 하는 이유는 예외인 Opus 4.6 때문입니다. 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 제어(v2.1.111 이상, Opus 4.7)

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

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

모델별 저장(v2.1.251 이상): 이제 /effort는 기본 effort 수준을 모델별로 저장하므로 모델을 전환해도 각 모델의 설정이 유지됩니다. Opus에서 사용하던 xhigh 설정이 더 이상 Haiku까지 따라가지 않습니다(CHANGELOG: “/effort가 모델별 기본 effort 수준을 저장하도록 변경되어 모델을 전환할 때 각 모델이 자체 설정을 유지함”). max가 세션에만 적용되는 예외는 그대로 유지됩니다.²⁰⁶ v2.1.257에서는 두 다이얼이 모두 개선되었습니다. /effort는 /model의 규칙과 마찬가지로 세션에만 적용되는 선택을 위한 s를 지원하며, --effort 플래그도 이제 세션 범위로 제한됩니다. 새 모델의 기본 effort 고정을 해당 세션에서만 해제하며 영구적으로 변경하지 않습니다(CLI 참고 문서에서는 기본값을 “이 세션에 대해 재정의하며 유지되지 않음”이라고 설명합니다).²¹¹²²⁰

Max의 Auto Mode(v2.1.111 이상)

Auto Mode는 2026년 8월 14일부터 Pro, Max 및 Team 요금제의 기본 권한 모드입니다(8월 7일 발표). 발표에 포함된 연구 수치, 사용 거부 방법 및 여전히 사용자가 직접 활성화해야 하는 요금제와 게이트웨이는 권한 모드를 참조하세요.²⁰³ 처음에는 --dangerously-skip-permissions를 대체하는 더 안전한 기능으로 등장했으며, Anthropic API를 통해 Opus 4.7을 사용하는 Max 구독자에게 먼저 제공되었습니다.¹⁴⁶ 별도의 분류기 모델이 실행 전에 각 작업을 검토하여 의도와 일치하는지, 안전한지 확인합니다. v2.1.210 기준으로 이 모델은 Claude Sonnet 5입니다.¹⁸⁷ 참고(v2.1.111 이상): --enable-auto-mode 플래그는 제거되었습니다. 대신 --permission-mode auto를 사용하여 Auto Mode로 세션을 시작하세요. Pro는 Auto Mode가 제공된 기간 대부분 동안 지원 대상에서 제외되었지만, 8월 14일 기본 적용으로 이 제한이 종료되었습니다. Bedrock/Vertex/Foundry(v2.1.158 이상): 해당 게이트웨이에서는 CLAUDE_CODE_ENABLE_AUTO_MODE=1을 설정하면 Opus 4.7 및 Opus 4.8에서 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.247부터 Bash 권한 프롬프트에는 Auto Mode를 안내하는 팁과 키 한 번으로 선택할 수 있는 “예, Auto Mode로 전환” 옵션이 표시됩니다.²²² v2.1.273부터 Bedrock, Vertex AI 및 Foundry의 Auto Mode는 “현재로서는” 로컬 분류기를 기본으로 사용합니다. 플랫폼의 서버 측 분류기를 사용하려면 CLAUDE_CODE_AUTO_MODE_SERVER=1을 설정하세요. 이는 v2.1.236의 분류기 기본값 참고 사항과는 다른 축에서 이루어진 상태 변경입니다. 로컬 방식과 서버 측 방식의 구분은 이전 릴리스에서 드러나지 않았던 작동 방식의 차이입니다.²¹⁷ Auto Mode이 아닌 것: 보안 경계. 아래에서 다루는 내용은 대부분 분류기를 강화하는 방법이며, 분류기는 sandbox가 아닙니다. 2026년 8월 26일, prompt injection 연구원 Johann Rehberger는 auto mode의 Claude Code Opus 5를 상대로 작동하는 공격 체인을 공개했습니다. 그는 소규모 표본에서 공격 성공률이 60~80%였다고 보고했습니다. 격리된 python3 자식 프로세스를 생성하는 기본 체인은 5회 중 3회, headless claude -p 인스턴스를 생성하는 payload를 사용하는 변형 체인의 두 구성은 각각 5회 중 3회와 5회 중 4회 성공했습니다. 다만 Rehberger도 이 수치가 보편적인 공격 성공률 측정치가 아니라 소규모 표본의 결과임을 명시했습니다.²¹⁰ 이 체인을 이해해야 하는 이유는 각 단계만 보면 모두 합리적으로 보이기 때문입니다. 서버가 WebFetch 요청에 HTTP 415로 응답하면 agent는 curl로 전환합니다. 다운로드한 archive는 scratch directory에 압축 해제되며, 그 안에는 manifest, Base85/zlib으로 인코딩된 data record 7개, native binary, struct.py가 들어 있습니다. Claude은 신뢰할 수 없는 binary의 실행을 거부한 다음, 직접 Python decoder를 작성하여 그 directory 안에서 실행합니다. decoder가 base64를 import하고, base64가 struct를 import하면, Python은 공격자의 struct.py를 먼저 찾습니다. 이 과정에는 명백히 악의적인 지시가 하나도 없습니다. injection은 손상된 경로가 작업을 완료하는 가장 합리적인 방법처럼 보이게 만들기만 하면 됩니다. Rehberger는 또한 몇 차례의 실행에서 Claude이 침해 사실을 감지한 뒤 malware process를 종료하려 했지만, auto mode가 cleanup command를 거부했다고 보고했습니다.²¹⁰ 그는 Anthropic이 홍보해 온 수치와 대비하여 이 결과를 설명합니다. 의뢰를 받은 third-party evaluation에서는 72개 시나리오를 각각 10회 실행한 결과, auto mode의 Opus 5가 prompt injection 공격 성공률 0.00%를 기록했다고 보고했습니다. 그의 체인은 이 평가 대상에 포함되지 않았으므로, 0.00%라는 benchmark 결과와 실제로 작동하는 code execution 체인이 동시에 참일 수 있습니다. Rehberger는 이 두 메시지가 서로 들어맞지 않는다고 봅니다.²¹⁰ 공격의 분류에도 주목해야 합니다. Simon Willison은 8월 30일 업데이트에서 이것이 전형적인 prompt injection이 아니라는 독자의 지적에 동의했습니다. model이 공격자의 지시를 읽고 따르는 과정이 없으므로, 이는 confused environment attack에 해당합니다.²¹⁰

Anthropic은 이 보고서를 Informative, 즉 의도한 대로 작동하는 동작으로 종결했습니다. Rehberger가 전달한 입장은 설계의 기준으로 삼아야 할 핵심입니다. auto mode는 보안을 보장하는 장치가 아니라 최선을 다하는 분류기입니다. 개별적으로는 무해한 단계들을 조합하여 구성한 치밀한 injection 체인은 분류기가 탐지해야 할 범위를 벗어나며, 실질적인 containment 경계는 OS 수준의 격리와 network egress 제어입니다.²¹⁰ 이는 아래의 강화 방법과 모순되지 않으며, 오히려 이를 이해하는 올바른 관점입니다. Auto mode는 사용자가 응답해야 하는 prompt 수를 줄이고 문서에 명시된 파괴적 작업 목록을 차단하지만, 신뢰할 수 없는 입력을 다루는 session을 안전하게 만들지는 않습니다. session이 가져온 page, 다운로드한 archive, issue text, third-party MCP server처럼 공격자의 영향을 받을 수 있는 content를 다룬다면, 실제로 피해 범위를 제한하는 것은 model 외부의 제어 수단입니다. container나 VM, 제한된 network egress, agent가 실제로 수행하는 작업에 대한 monitoring, 그리고 잃어도 곤란하지 않을 정도로 SSH key와 cloud credential을 보관하지 않는 home directory가 필요합니다. Auto-mode 승인은 작업이 안전했다는 증거가 아닙니다.

기본값을 유지하면서 사용자 지정 규칙 추가하기(v2.1.118+). 이전 버전에서는 autoMode.allow, autoMode.soft_deny, autoMode.environment를 둘 중 하나만 선택할 수 있었습니다. 사용자 지정 목록을 정의하면 기본 제공 안전 규칙이 사라졌습니다. $defaults sentinel은 이 문제를 해결합니다. 사용자가 배치한 정확한 위치에서 기본 제공 목록으로 inline 확장되므로, 그 전후에 사용자 지정 규칙을 추가할 수 있습니다.¹⁵²

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

/permissions에서 분류기 규칙 편집하기(v2.1.246). /permissions를 실행하고 Auto mode tab을 여세요. 이 tab은 session에서 auto mode를 사용할 수 있을 때만 나타납니다. 분류기가 읽는 모든 scope의 allow, soft_deny, hard_deny, environment entry를 나열하고, 각 section에 기본 제공 규칙이 적용되는지도 보여 줍니다. managed settings나 --settings의 entry는 읽기 전용이며, 모든 변경 사항은 ~/.claude/settings.json에 저장됩니다. section에 첫 번째 규칙을 추가하면 기본 제공 규칙이 계속 적용되도록 "$defaults"도 함께 삽입됩니다. section별로 기본 제공 규칙을 켜거나 끌 수 있지만, 이를 끄려면 먼저 해당 section에 사용자 규칙이 하나 이상 있어야 합니다. environment는 editor에서 하나의 document로 열립니다.²²⁶²²⁴

“Don’t ask again” 선택 기능(v2.1.118+). 이제 Auto Mode 활성화 prompt에 “Don’t ask again” option이 표시되므로, 자주 사용하는 사용자는 flag를 script로 지정하지 않고도 안내를 숨길 수 있습니다.¹⁵²

파괴적 command 보호 장치(v2.1.183). 이제 auto mode는 session에서 사용자가 명시적으로 요청하지 않은 비가역적 command를 강제로 차단합니다. local work를 폐기하라고 요청하지 않은 상태에서 실행되는 파괴적인 git 작업(git reset --hard, git checkout -- ., git clean -fd, git stash drop), 현재 session에서 agent가 만들지 않은 commit에 대한 git commit --amend, 특정 stack을 지정하지 않은 infrastructure 제거 작업(terraform destroy, pulumi destroy, cdk destroy)이 이에 해당합니다. 이 변경은 아무런 경고 없이 작업을 잃게 하거나 environment를 제거하는 작업에 대해 분류기의 blast radius를 줄입니다. agent가 이러한 command를 실행할 수는 있지만, 스스로 판단하여 실행할 수는 없으며 사용자의 명시적인 지시가 있어야 합니다.¹⁷⁴

모든 shell command 분류하기(v2.1.193). 기본적으로 auto-mode 분류기는 임의 code execution pattern과 일치하는 shell command만 검토하며, 일반적인 command는 검토하지 않습니다. 새로운 autoMode.classifyAllShell 설정은 대신 모든 Bash/PowerShell command를 분류기로 전달합니다. 모든 shell 호출을 검증하는 더 촘촘한 안전망이 필요할 때 약간의 latency를 감수하는 방식입니다. 같은 release부터 transcript, 거부 알림, /permissions의 최근 거부 항목에도 auto-mode 거부 사유가 표시되므로, 이제 차단된 command가 차단된 이유를 설명합니다.¹⁷⁹

3가지 추가 강화 규칙(v2.1.205). 이제 auto mode는 session transcript file 변조를 차단하여 audit trail 자체에 agent가 접근하지 못하게 합니다. 또한 context에서 해석할 수 없는 변수를 대상으로 rm -rf를 실행하기 전에 확인하여 알 수 없는 $DIR을 사용하는 rm -rf $DIR 유형의 사고를 방지합니다. 아울러 background-task notification은 사람이 입력한 내용이 없었다는 사실을 명확히 표시하므로, transcript 안에 조작된 “user approved” 문구를 삽입해 실제 승인처럼 처리되도록 만들 수 없습니다.¹⁸³ 세 번째 규칙은 반드시 이해해 두어야 할 prompt injection 방어입니다. 승인은 approval channel을 통해 전달되어야 하며, 이제 harness는 이 전제를 명시적으로 드러냅니다.

Command substitution으로 치명적인 작업을 숨길 수 없습니다(v2.1.208). 이제 rm -rf ~ 같은 치명적인 제거 작업은 $(...), backtick, process substitution(<(...)) 안에 숨겨져 있어도 확인 prompt를 표시합니다. 이 prompt는 --dangerously-skip-permissions와 auto mode에서도 표시됩니다. 파괴적 command를 substitution으로 감싸도 더 이상 안전망을 우회할 수 없습니다.¹⁸⁶

Auto-mode 상태 초기화: claude auto-mode reset(v2.1.212). 새로운 subcommand를 사용하면 terminal에서 auto-mode 상태를 초기화할 수 있습니다. 확인 prompt를 건너뛰려면 --yes를 전달하세요.¹⁸⁹

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

확인 dialog는 줄이고 검토 수준은 그대로 유지하기(v2.1.218). 이전에는 위험한 rm, background &, 의심스러운 Windows path에 대한 3가지 검사에서 permission dialog를 표시하여 auto mode를 중단했습니다. 이제는 dialog를 표시하지 않고 auto-mode 분류기가 이를 판정하므로, 각 탐지 때마다 사용자를 개입시키지 않으면서도 안전 검토를 계속 수행합니다. 같은 release에서는 이 동작이 auto를 사용하는 plan mode에도 적용됩니다. static analyzer가 읽기 전용임을 입증하지 못한 Bash command에도 더 이상 prompt를 표시하지 않으며, dialog로 되돌아가는 대신 분류기가 판정합니다.¹⁹⁵

Containment escape 규칙(v2.1.257). 분류기의 자동 승인이 절대 허용되지 않는 목록에 “Containment Escape” 규칙이 추가되었습니다. 이제 cloud metadata credential 가져오기, network egress 회피, tenant 간 접근은 environment에서 예상된 동작으로 표시하지 않는 한 자동 승인되지 않습니다. 앞서 설명한 주의 사항의 관점에서 이를 이해해야 합니다. 이는 분류기를 계속 강화하여 문서에 명시된 또 하나의 거부 유형을 추가한 것이며, auto mode의 본질이 바뀐 것은 아닙니다.²¹¹ 작업 디렉터리 외부의 파일을 읽을 때 한 번만 표시되는 프롬프트(v2.1.257). 이제 자동 모드는 세션에서 작업 디렉터리 외부의 파일을 처음 읽기 전에 한 번만 확인합니다. 함께 제공되는 permissions.blockReadsOutsideWorkingDirectories 설정을 사용하면 확인 대신 읽기가 즉시 차단됩니다.²¹¹ v2.1.273에서는 검사기가 확인할 수 없는 작업에도 두 동작이 적용됩니다. 완전히 분석할 수 없는 Bash 명령은 검사를 건너뛰지 않고 사용자에게 확인하며, 저장소 설정에서 지정한 메모리 디렉터리는 차단 설정이 활성화된 경우 프롬프트에 불러오거나, 회상하거나, 색인하거나, 메모리 추출에 사용하지 않습니다.²¹⁷

다이어그램 렌더러 URL도 업로드로 간주됩니다(v2.1.261). mermaid.live 방식처럼 콘텐츠 자체를 URL에 인코딩하여 공개 다이어그램 렌더러로 전달하는 링크는 사용자가 요청하지 않는 한 더 이상 자동 승인되지 않습니다. 분류기는 이러한 링크를 업로드로 처리합니다. 인코딩된 데이터가 URL 자체를 통해 이동하며, 페이지가 열리면 렌더러 사이트의 스크립트가 해당 데이터를 읽을 수 있기 때문입니다. mermaid.live 방식의 링크는 페이로드를 URL 프래그먼트에 담으며, 브라우저는 이를 네트워크 요청과 함께 전송하지 않고 페이지의 JavaScript에 전달합니다. 앞서 설명한 주의 사항과 같은 맥락입니다. 강화된 분류기에서 또 하나의 데이터 유출 경로를 차단한 것이며, 새로운 경계를 추가한 것은 아닙니다.²¹⁴

인라인 ! 셸은 분류기에서 제외되고, subagent의 결과 전달은 분류기에 포함됩니다(v2.1.271). 새로운 거부 범주가 아니라 두 가지 작동 방식이 변경되었습니다. 이제 skill 또는 슬래시 명령의 인라인 ! 셸 명령은 분류기 대신 기본 모드의 권한 규칙을 따릅니다. 어떤 규칙으로도 결정되지 않는 명령은 검토를 거치는 도구 호출로 실행됩니다. 또한 이제 subagent는 전용 결과 전달 호출을 통해 호출자에게 결과를 보고하며, 안전 분류기는 이 호출을 검토합니다. 이전에는 마지막 메시지가 전달된 뒤 검토되었지만, 이제 검사 지점이 결과 전달 이후에서 결과 전달 자체로 옮겨졌습니다.²¹⁶

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

푸시 알림(v2.1.110+)

Remote Control에서 “Claude의 판단에 따라 푸시”가 활성화되어 있으면, 이제 Claude가 새로운 푸시 알림 도구를 통해 자체 판단으로 모바일 푸시 알림을 보낼 수 있습니다. 기존 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+)

글로브 인수를 사용하는 읽기 전용 Bash 패턴(예: ls *.ts, cat src/*.md)과 cd <project-dir> &&로 시작하는 명령은 더 이상 권한 프롬프트를 표시하지 않습니다.¹⁴⁶ /less-permission-prompts와 함께 사용하면 일상적인 작업 흐름의 중단을 크게 줄일 수 있습니다.

분산 추적(v2.1.110+)

이제 SDK 및 헤드리스 세션은 환경에서 TRACEPARENT와 TRACESTATE를 읽어 Claude Code 실행을 분산 추적에 연결합니다. 디버깅을 위해 OTEL_LOG_RAW_API_BODIES=1(v2.1.111+)과 함께 사용하면 전체 API 요청 및 응답 본문을 OpenTelemetry 로그 이벤트로 내보낼 수 있습니다.¹⁴⁶

네이티브 바이너리 배포(v2.1.113+)¹⁵⁰

v2.1.113에서는 CLI의 시작 방식이 변경되었습니다. 이제 claude는 번들로 제공되는 JavaScript를 실행하는 대신 플랫폼별 선택적 종속성을 통해 네이티브 Claude Code 바이너리를 생성합니다. 설치 및 업데이트 명령은 그대로 유지되므로 팀에서 배포 스크립트를 변경할 필요는 없습니다.

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

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

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

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

v2.1.114 안정성 수정¹⁵⁰

v2.1.114(2026년 4월 18일)에는 한 가지 수정 사항이 포함되었습니다. 에이전트 팀의 팀원이 도구 권한을 요청할 때 권한 대화 상자가 충돌할 수 있던 문제가 수정되었습니다. Agent Teams를 사용한다면 업그레이드하세요.

콘텐츠 표시: 텍스트 워터마크 및 C2PA 파일 메타데이터(2026년 8월)

Anthropic는 유럽연합 인공지능법 제50조에 따라 Claude가 생성한 콘텐츠에 기계 판독 가능한 표시를 적용한다고 발표했습니다. 이 조항은 새로 출시되는 인공지능 시스템을 대상으로 2026년 8월 2일부터 시행됩니다. 시스템은 두 가지 구성 요소로 이루어집니다. 생성된 텍스트에는 보이지 않는 통계적 워터마크가 적용되고, .svg, .png, .jpg 같은 생성 파일에는 C2PA 공개 표준에 따른 서명된 출처 메타데이터가 추가됩니다.²²⁹²⁰⁴ 주요 보도에서 흐릿하게 다뤄진 핵심은 두 구성 요소 모두 같은 모델 출시 일정에 따라 적용된다는 점입니다. 지원 페이지에 따르면 “2026년 8월 2일 이후 출시되는 Claude 모델은 출시 시점부터 기계 판독 가능한 표시를 지원합니다.” 해당 날짜 이전에 출시된 모델, 즉 현재 전체 제품군(Fable 5, Opus 5, Sonnet 5, Haiku 4.5)은 유럽연합 법률의 전환 기간 적용 대상이며, Anthropic는 “이러한 모델에도 표시 기능을 추가하기 위해 노력하고 있습니다.”²⁰⁴ 현재 Claude Code를 통해 생성하는 어떤 결과물에도 텍스트와 파일을 불문하고 표시가 적용되지 않습니다. 향후 모델의 결과물에는 모든 환경에서 표시가 적용됩니다. 여기에는 Claude Platform(API), claude.ai, Claude Code, Claude Cowork, Claude Tag 및 클라우드 게이트웨이가 포함됩니다. 표시 기능이 모델 수준에서 적용되기 때문입니다. 널리 퍼진 한 게시물이 이를 반대로 설명했기 때문에 덧붙일 만한 결론이 있습니다. 현재 모델에서 느껴지는 스타일이나 동작의 변화는 워터마크 때문일 수 없습니다. 현재 어떤 모델에도 아직 적용되지 않았습니다.

작동 방식은 Google DeepMind의 SynthID-Text 변형입니다. Claude가 의미상 동등한 선택지 중에서 단어를 고를 때 워터마크가 “단어를 선택하는 데 사용되는 무작위성의 원천”을 변경합니다. 문자를 추가하거나 후처리하는 방식이 아니며, Anthropic의 내부 테스트에 따르면 “워터마크는 콘텐츠, 창의성 수준 또는 가독성에 영향을 주지 않습니다.”²²⁹ Claude Code 사용자들이 주목할 점은 다음과 같습니다. 코드에는 희소한 워터마크가 포함됩니다. 작동하는 코드에는 임의로 선택할 여지가 거의 없으므로, 워터마크는 주석이나 이름처럼 자유롭게 선택할 수 있는 부분에 집중되며, 실제로 생성되는 코드에는 Anthropic의 표현대로 “무시해도 될 정도의 영향”만 미칩니다.²²⁹ 워터마크가 유지될 가능성은 구성 요소에 따라 다릅니다. 텍스트의 경우 가볍게 편집하면 “워터마크가 완전히 제거되지는 않을 가능성이 높지만”, 전면적으로 다시 작성하면 제거되며, Claude이 생성한 번역에는 새로운 워터마크가 적용됩니다. 파일 메타데이터의 경우 형식 변환, 다시 저장, 스크린샷 촬영으로 C2PA 서명이 제거될 수 있습니다.²⁰⁴ 이를 감지하는 API도 출시될 예정입니다. 양성 결과는 “Claude이 어느 시점에 해당 콘텐츠에 관여했을 가능성이 높다”는 사실만 입증하며, “Claude이 이 콘텐츠를 작성했다”와 “Claude이 이 콘텐츠를 대폭 편집했다”를 명시적으로 구분할 수 없습니다. 지원 페이지에 따르면 워터마크가 없더라도 아무것도 입증되지 않습니다. 어떤 고객 등급에도 적용 제외 옵션이 있다는 언급은 없습니다.²²⁹²⁰⁴

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+).¹³⁷

정가 대신 계약 요금 적용(modelPricing, 관리형 설정, v2.1.243+): 모델별 협상 요금이나 할인 배수가 있는 조직은 이를 modelPricing 관리형 설정으로 배포할 수 있습니다. 그러면 /cost, 상태 표시줄, 원격 측정 비용 수치에 정가 대신 해당 요금이 적용되므로 개발자가 확인하는 금액과 조직이 실제로 지불하는 금액이 일치합니다.²²⁷ v2.1.271부터는 내부 팀에 할증 요금을 부과하는 조직을 위해 배수를 1보다 크게, 최대 10까지 설정할 수도 있습니다.²¹⁶

세션별 프롬프트 캐시 항목(v2.1.251+): /cost에는 세션의 프롬프트 캐시 항목이 추가됩니다. 적중률, 미스, 다시 캐시된 토큰 수, 캐시의 웜 또는 콜드 상태를 보여 주며, 상태 표시줄 스크립트에도 이에 대응하는 prompt_cache 객체가 제공됩니다. 이 객체는 기본 대화에서 첫 번째 API 응답이 나온 후 표시되고 subagent 요청은 집계하지 않으며, API 응답의 캐시 토큰 수를 바탕으로 계산되므로 모든 제공업체에서 작동합니다. /usage도 Prompt cache (main) 항목에 같은 통계를 표시합니다.²⁰⁶²⁰⁹ v2.1.260부터는 /cost 항목과 상태 표시줄의 prompt_cache 객체에 캐시 미스의 추정 원인도 표시됩니다. 예를 들어 도구 정의나 시스템 프롬프트가 변경되었거나, 세션이 캐시 TTL보다 오래 유휴 상태였을 수 있습니다.²¹²

에이전트 트래픽이 더 이상 자체 캐시 접두사를 손상시키지 않음(v2.1.265): 위임된 작업에서 발생하던 프롬프트 캐시 누수를 2가지 수정으로 막았습니다. 포그라운드에서 생성한 subagent를 재개해도 더 이상 도구 목록과 시스템 프롬프트 접두사가 변경되지 않습니다. 또한 에이전트 팀원과 재개된 subagents의 이후 턴에서도 SubagentStart hook 컨텍스트와 미리 로드된 skills가 프롬프트 접두사 밖으로 이동하지 않습니다. 두 버그 모두 접두사를 변경해 그 뒤의 모든 내용을 캐시되지 않은 입력으로 다시 전송하게 만들었으며, 캐시 비용 효율이 가장 중요한 장기 에이전트 세션에서 특히 문제가 되었습니다. 이는 v2.1.260에서 Fable 5.1의 도구 호출 턴에 대해 수정한 것과 같은 장애 유형입니다.²¹⁵

v2.1.267 캐시 안정성 수정 묶음: 한 번의 릴리스에 약 10개의 수정이 포함되었으며 모두 같은 장애 유형을 다룹니다. 대화 도중 무언가가 프롬프트 접두사를 다시 작성해 그 뒤의 모든 내용을 캐시되지 않은 입력으로 재전송하는 문제입니다. 이제 재개된 세션은 도구 목록을 다시 작성하거나 도구 설명을 다시 렌더링하지 않으며, 커넥터가 다시 연결되기 전에 이전 MCP 도구 알림을 다시 작성하지도 않습니다. /model로 모델을 전환해도 모든 도구 정의를 다시 전송하지 않습니다. 이제 커밋 및 PR 출처 표시는 모델 변경 시 갱신되는 대화 메모로 전달됩니다. --system-prompt 또는 --append-system-prompt로 시작한 subagents와 세션은 시스템 프롬프트와 도구 정의를 한 번만 기록합니다. 또한 세션 도중 추가된 MCP 및 plugin 도구는 ToolSearch가 없는 세션에 다시 작성된 도구 목록이 아닌 지연 정의로 전달됩니다. 이 수정 묶음은 v2.1.260과 v2.1.265의 개선 범위를 세션 재개, 모델 전환, MCP 재연결 영역까지 확장합니다.²¹⁶

v2.1.273에서도 대화 흐름 유지: /login, /upgrade, /extra-usage가 대화의 이전 사고 내용을 삭제해 다음 요청에서 프롬프트 캐시 전체를 다시 작성하도록 만들던 문제가 있었습니다.²¹⁷

구독 요금제

사용량 제한(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개 이상)”을 확보합니다.¹⁵⁷

2026년 9월 14일부터 적용되는 주간 제한(8월 29일 발표): 5월 확대 이후 적용된 임시 주간 제한 50% 증가는 9월 14일에 종료되며, Pro, Max, Team, 사용자 단위 Enterprise 요금제에는 확대 전 기준보다 25% 높은 제한이 영구적으로 적용됩니다. 이 변경에 대한 Anthropic의 계산은 다음과 같습니다. “현재와 비교하면 Claude Code의 주간 제한이 17% 줄어드는 셈입니다.” 현재 주간 상한이 150단위라면 9월 14일부터 125단위가 됩니다. 5시간 제한은 이번 발표에 포함되지 않으므로 5월에 적용된 2배 확대가 유지됩니다. 장시간 무인 세션을 실행한다면 지금부터 낮아질 상한에 대비하세요. 재설정 시 자동 계속 토글(v2.1.234)과 /usage가 핵심 관리 수단입니다.²¹³

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

API 사용량에 따라 요금을 지불하는 사용자의 100만 토큰당 가격은 다음과 같습니다.

1M 컨텍스트 가격(2026년 4월): Opus 4.7, Opus 4.6, Sonnet 4.6, Mythos Preview는 모두 표준 100만 토큰당 요금으로 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% 절감됩니다. Claude Fable 5.1과 Mythos 5.1에서는 읽기 비용이 0.025배(Fable 5.1은 $0.25/MTok)까지 낮아져 97.5% 절감됩니다.²¹⁸ 컨텍스트를 반복해서 사용하는 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에도 적용됩니다. 상한에 도달하면 새 에이전트 생성이 거부되고 실행 중인 백그라운드 에이전트도 중단됩니다. 이전에는 백그라운드 에이전트가 예산 제한을 벗어났습니다¹⁹⁴
5. 탐색에 plan mode 사용: 실행하지 않으므로 의도치 않은 고비용 작업을 방지할 수 있습니다
6. 선제적으로 압축: 컨텍스트가 작을수록 토큰 수가 줄어듭니다
7. 출력 제한: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
8. 긴급하지 않은 작업에 Batch API 사용: 입력 및 출력 토큰 모두 50% 할인됩니다
9. 프로젝트의 Claude API 지출 분석: /claude-api cost-optimize(v2.1.247+)는 기존 프로젝트의 Claude API 지출을 분석하고 캐싱, 토큰 관리, batch, effort, 모델 선택 같은 비용 조정 수단을 측정 가능한 변경 단위로 하나씩 적용합니다. 이는 Claude Code 세션 자체가 아니라 API으로 구축하는 앱을 위한 기능입니다²²²

사용량 모니터링

• Claude Console: platform.claude.com(Admin 또는 Billing 역할 필요)
• Workspace 제한: Workspace별 지출 한도를 설정합니다
• 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 5 (high effort default; /effort xhigh for harder)
                  │         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

경험 법칙: 기본 모델은 사용 중인 플랜에 따라 달라져요. 프리미엄 플랜과 Anthropic API에서는 Opus 5를, Pro와 Team Standard에서는 Sonnet 5를 사용해요. /model opus를 사용하면 Sonnet 세션을 Opus 5로 전환할 수 있어요.^181197207 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을 늘리고 간단한 문제에서는 빠르게 응답해요. 더 깊이 분석하도록 강제하려는 경우, 수동 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   (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와 유사한 코드 인텔리전스를 제공합니다. - 정의로 이동: 심볼이 정의된 위치로 이동합니다 - 참조 찾기: 코드베이스 전체에서 심볼이 사용된 모든 위치를 나열합니다 - 마우스 오버 문서: 모든 심볼의 타입 정보와 문서를 확인합니다 - TypeScript, Python, Go, Rust 및 LSP를 지원하는 기타 언어에서 작동합니다 - 언어 서버를 사용할 수 있어야 합니다(일반적으로 도구 체인과 함께 설치됨)

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

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

EndConversation 도구(v2.1.214). 이제 Claude Code에는 Claude가 2025년부터 claude.ai에서 제공해 온 것과 같은 대화 종료 기능이 있습니다. 악의성이 매우 높은 입력이나 지속적인 탈옥 시도가 발생하는 드문 경우, Claude는 내장 EndConversation 도구를 통해 세션을 즉시 종료할 수 있습니다. 이는 악용 방지와 모델 복지를 위한 조치이지 워크플로 기능이 아니므로, 일반적인 개발 세션에서는 작동하지 않습니다.¹⁹⁰¹⁹³

권한 모드

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

2026년 8월 14일부터 Auto 모드는 Pro, Max, Team의 기본 제공 모드입니다. 8월 7일에 발표되었으며 전환 당일 공식 권한 모드 문서에서 실제 적용이 확인되었습니다. 현재 문구에는 알아 두어야 할 2가지 범위 세부 사항도 추가되었습니다. 기본값은 새 세션에 적용되며, “직접 지정한 기본값은 일회성 전환 요청을 수락하지 않는 한 유지되고, 조직에서 관리하는 기본값은 변경되지 않습니다.” 해당 플랜의 새 세션은 auto 모드로 시작하며, 이 모드는 “각 도구 호출을 분류기로 전달하여 되돌릴 수 없거나 파괴적이거나 환경 외부를 대상으로 하는 작업을 차단합니다.” Anthropic가 전환의 근거로 제시한 내용은 다음과 같습니다. 1,053명을 대상으로 한 테스트에서 auto 모드는 위험한 명령의 89%를 포착한 반면 사람의 검토는 13.6%만 포착했습니다. 사용자가 권한 요청의 97%를 승인한다는 점도 실제로 수동 검토가 취약한 이유입니다. 분류기로 인한 토큰 오버헤드는 발표 시점부터 Pro/Max/Team에 더 이상 청구되지 않습니다. Shift+Tab을 한 번 누르거나 데스크톱 모드 드롭다운을 사용하면 이전 모드로 돌아갈 수 있습니다. 다른 기본값을 고정하려면 설정에서 defaultMode를 사용하세요. 조직 관리자는 disableAutoMode 관리형 설정으로 auto 모드를 완전히 비활성화할 수 있습니다. Enterprise, Claude API, AWS의 Claude Platform, Bedrock, Google Cloud의 Agent Platform 및 Foundry에서는 현재 선택적으로 사용해야 합니다. Anthropic는 “다음 달 안에” 기본 적용 대상을 이들로 확대할 계획입니다.²⁰³ auto 모드가 보장하지 않는 사항과 연구자가 입증하여 Anthropic가 이를 명시하게 된 우회 방법은 Max의 Auto 모드를 참조하세요.

이제 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를 대체하는 더 안전한 기능입니다. 별도의 분류기 모델인 Claude Sonnet 5(v2.1.210부터 사용, 원래는 Sonnet 4.6)가 실행 전 각 작업을 검토하여 사용자의 의도와 일치하고 안전한지 확인합니다.¹²⁴¹⁸⁷

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

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

회로 차단기: 연속으로 3번 또는 한 세션에서 총 20번 차단되면 수동 승인 요청 모드로 일시 전환됩니다.¹²⁵

# Enable at startup
claude --permission-mode auto

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

Auto 모드는 더 이상 별도 동의가 필요하지 않고(v2.1.152), 환경 변수 플래그 없이 Bedrock/Vertex/Foundry에서 작동하며(v2.1.207), 2026년 8월 14일부터 Pro/Max/Team의 기본 제공 모드입니다.^244185203

YOLO Mode(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"
  }
}

defaultMode의 범위 제한(v2.1.257): 이제 프로젝트의 .claude/settings.json 또는 .claude/settings.local.json에서는 defaultMode: "bypassPermissions"를 설정할 수 없습니다. 이미 "auto"에 적용되던 것처럼 해당 값은 무시됩니다. 이제 문서에는 permissions.defaultMode의 auto와 bypassPermissions 값이 “프로젝트 또는 로컬 설정에서는 적용되지 않는다”고 명시되어 있습니다. 사용자 또는 관리형 설정에서 지정하거나, 세션별로 --permission-mode를 사용하세요. 따라서 복제한 저장소가 권한을 우회한 상태로 세션을 시작하는 설정 파일을 포함할 수 없습니다. 위 예시는 모든 범위에서 설정할 수 있는 acceptEdits를 사용합니다. 이 가이드에서는 기존의 auto 제한도 기록하지 않았지만, 이제 두 제한을 모두 명시합니다.²¹¹²²⁰

권한 규칙 구문

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

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:*)처럼 명령 전체를 거부하세요.

*는 하위 명령 뒤에 배치하세요. Claude Code는 첫 번째 * 앞의 모든 내용을 작성된 그대로 일치시키므로, 그 앞의 단어가 규칙의 범위를 제한합니다. Bash(git log *)는 git log 명령만 허용하지만, Bash(git * main)에서는 *가 하위 명령과 그 앞의 모든 옵션을 대신합니다. 여기에는 git이 사용자가 지정한 프로그램을 실행하게 만드는 -c도 포함되므로, Bash(git * main)은 git -c core.fsmonitor=<script> diff main도 승인합니다. v2.1.246부터 Claude Code는 설정 파일, 관리형 설정, --allowedTools 또는 --settings 값에 관계없이 하위 명령 앞에 와일드카드가 있는 허용 규칙을 발견하면 시작 시 경고합니다. 해결하려면 Bash(git * main) 대신 Bash(git checkout main)처럼 의도한 값을 정확히 지정하세요.²²⁶²²⁴

파일 거부 규칙은 리디렉션에도 적용되며, 인수까지 확장되었던 기능은 하루 만에 되돌려졌습니다(v2.1.257-260). Bash 명령에 적용된 Read(...)와 Edit(...) 거부 규칙은 입력 리디렉션(< file)과 tac, egrep 같은 읽기 명령도 검사합니다(v2.1.257). 이는 v2.1.232의 입력 리디렉션 검사가 v2.1.233에서 되돌려질 때 예고된 더 좁은 구현이며, 이 부분은 그대로 유지됩니다. v2.1.259에서는 옵션 값과 피연산자에 숨겨진 파일 경로까지 같은 검사가 확장되었습니다. 예를 들면 --ignore-revs-file=.env, -f.env, @file 인수, git diff와 git grep의 피연산자, cd DIR && cat FILE 복합 명령이 포함되며, 거부된 파일이 들어 있는 디렉터리에 grep -r 또는 cp -r을 사용하면 먼저 승인을 요청했습니다. 그러나 v2.1.260에서는 다음 날 이 확장이 되돌려졌습니다. 모든 모드에서 Read(./**/build/**) 규칙이 있을 때 npm run build를 거부했고, auto 모드에서도 cd ... && grep가 승인을 요청하는 문제가 있었기 때문입니다. 인수 수준 검사 범위가 변경된 것은 이번이 세 번째입니다. v2.1.232에서 도입되고, v2.1.233에서 되돌려졌으며, v2.1.257에서 현재 유지되는 리디렉션 및 읽기 명령의 일부 범위가 적용되었고, v2.1.259에서 인수까지 확장되었다가 v2.1.260에서 그 확장이 되돌려졌습니다. 따라서 v2.1.260 기준으로 거부 규칙은 리디렉션과 읽기 명령을 포착하지만 임의의 명령 인수에 숨겨진 경로는 포착하지 않습니다. 이 상태는 v2.1.260에서 정해진 뒤 계속 유지되고 있으며, 이후 변경 사항은 특정 우회 방법에 대한 개별 수정이지 네 번째 범위 변경은 아닙니다(다음 단락 참조).²¹¹²¹²

되돌리기 이후의 개별 수정과 두 번째 제한적 되돌리기(v2.1.268-273). 인수 관련 되돌리기는 유지됩니다. 다음 변경 사항은 특정 우회 방법을 차단하며, 그중 하나는 다시 되돌려졌습니다. v2.1.268: 심볼릭 링크로 연결된 시스템 디렉터리(macOS의 /etc, /tmp, /var, Linux의 /bin)에 적용한 거부 및 승인 요청 규칙은 이제 실제 위치로 경로를 작성해도 적용되며, Bash 명령도 심볼릭 링크 경로에 작성된 거부 규칙을 더 이상 무시하지 않습니다. 두 변경 사항 모두 유지됩니다. 같은 릴리스에서는 권한 검사기가 분석할 수 없는 env -C, eval 또는 유사한 명령이 같은 줄에 있어도 Read 또는 Edit 거부 규칙을 우회하지 못하도록 했습니다. 그러나 v2.1.273에서는 바로 이 검사만 되돌렸습니다. 이에 따라 “time -p make build 같은 명령은 거부되는 대신 다시 승인을 요청합니다.” v2.1.269: 이제 Edit() 거부 규칙과 쓰기 경로 검사가 Bash tee 명령이 쓰는 파일에도 적용되고, Bash(tee:*) 허용 규칙은 작업 디렉터리 밖의 대상을 더 이상 허용하지 않으며, !로 시작하는 거부 또는 승인 요청 규칙은 해당 규칙을 작성한 설정 소스 안에서만 적용됩니다. 단독 ! 부정은 무시됩니다. v2.1.271에서는 검사기 자체를 수정했습니다. fmt, column 및 유사한 명령이 읽는 파일은 검사기가 인식하지 못하는 옵션 뒤에 나오더라도 검사됩니다. 와일드카드가 패턴이나 옵션 값에 있는 경우 해당 와일드카드로 확장되는 파일도 검사됩니다(예: grep -v dir/* file). 셸 변수 선언 플래그로 실제 실행 명령을 잘못 나타낼 수 없게 되었습니다. 또한 디렉터리를 2번 변경하는 명령, 서브셸 또는 cd와 git을 연결한 명령이 bypass 및 auto 모드에서 permissions.blockReadsOutsideWorkingDirectories의 승인 요청을 더 이상 건너뛰지 않습니다. v2.1.273에서는 되돌리기와 함께 3가지 개별 수정도 적용했습니다. 분석할 수 없는 Bash 명령은 permissions.blockReadsOutsideWorkingDirectories에서 승인 요청을 더 이상 건너뛰지 않으며, 위험한 rm을 숨긴 서브셸은 bypass 모드에서 확인을 더 이상 건너뛰지 않고, 저장소 설정에서 선택한 메모리 디렉터리는 해당 설정에 따라 더 이상 로드되거나 회상되거나 인덱싱되지 않습니다. 검사기가 분석할 수 없는 Bash 줄의 최종 규칙을 간단히 정리하면 다음과 같습니다. 거부 규칙은 거부하지 않고 승인을 요청하며, blockReadsOutsideWorkingDirectories는 건너뛰지 않고 승인을 요청합니다.²¹⁶²¹⁷

파일 작업 패턴:

{
  "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: 조건에도 이 릴리스에서 동일한 cwd 범위가 적용되었습니다(매처 참조).¹⁹⁰

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

“항상 허용” 규칙은 저장소 루트에 저장됩니다(v2.1.211). 이제 “항상 허용” 요청 옵션으로 생성한 권한 규칙은 현재 worktree가 아니라 저장소 루트에 작성됩니다. 따라서 한 worktree에서 부여한 승인은 여러 세션은 물론 해당 저장소의 모든 worktree에서도 유지됩니다. 더 이상 각 병렬 체크아웃에서 같은 명령을 다시 승인할 필요가 없습니다.¹⁸⁸

괄호가 포함된 경로와 잘못된 패턴은 안전하게 실패합니다(v2.1.260). 파일 권한 규칙의 구문 분석 문제 3개가 수정되었으며, 첫 번째는 보안 수정입니다. 경로에 괄호가 포함된 Edit/Write/Read 규칙은 잘못된 규칙으로 폐기되거나 Bash sandbox에서 무시되었습니다. 예를 들어 Next.js 라우트 그룹인 Edit(src/app/(admin)/**)가 무시되면 관리자가 읽기 전용이라고 믿었던 폴더에 쓸 수 있었습니다. 이제 이러한 규칙도 적용됩니다. 닫히지 않은 [처럼 컴파일할 수 없는 패턴이 포함된 파일 거부 규칙은 이전에 모든 파일 편집을 Invalid regular expression 오류로 실패하게 했습니다. 이제 이러한 규칙은 작성된 그대로의 리터럴 경로를 보호합니다. 또한 \(가 경로 구분자가 아니라 이스케이프된 괄호로 해석되는 Edit(C:\dir\(name)\**) 같은 규칙의 설정 오류는 이제 모호하지 않은 표기법을 제안합니다. 같은 릴리스부터 닫는 괄호 뒤에 텍스트가 있는 규칙도 더 이상 조용히 무시되지 않습니다. 아무것에도 일치하지 않던 Bash(ls) x 같은 규칙은 이제 잘못된 설정으로 보고됩니다.²¹²

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:...) 규칙은 subagents가 그중 어떤 모델을 사용하는지 제한합니다.¹⁷³

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)"
  ]
}

v2.1.268부터 일반 WebFetch 거부 및 승인 요청 규칙은 Artifact 도구의 읽기와 업데이트에 더 이상 적용되지 않습니다. 이를 차단하거나 제어하려면 Artifact 규칙 또는 WebFetch(domain:claude.ai)를 작성하세요.²¹⁶

추가 디렉터리

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.221부터 자격 증명 파일에는 허용과 거부 외에 세 번째 모드인 mode: "mask"가 추가됩니다(Linux 및 WSL). sandbox 명령이 파일을 읽으면 전체 파일 또는 extract 정규식으로 포착한 범위만 sentinel로 바꾼 복사본을 받으며, sandbox 프록시는 외부로 전송할 때 이를 실제 값으로 치환합니다. 명령은 프록시를 통해 인증할 수 있어 정상적으로 작동하지만 비밀이 환경에 존재하는 일은 없습니다. 이는 프롬프트 인젝션을 받은 명령이 토큰을 찾으려 할 때 정확히 필요한 특성입니다. 프록시 치환 장치를 사용할 수 없는 macOS에서는 mask가 deny로 대체됩니다. 따라서 Linux CI용으로 작성한 설정은 파일을 조용히 노출하지 않고 안전하게 기능이 제한됩니다.¹⁹⁹

v2.1.224에서는 마스킹이 정적 파일 콘텐츠 이외의 영역까지 확장됩니다. extract와 onExtractNoMatch는 구조화된 환경 변수 값을 처리합니다. decode: "jwt"와 maskClaims를 사용하면 JWT 전체가 아니라 선택한 claim만 마스킹하므로, 명령이 토큰의 라우팅 메타데이터를 읽는 동안 민감한 claim은 sentinel로 유지할 수 있습니다. awsPairs/sigv4는 프록시에서 AWS SigV4 요청에 다시 서명합니다. 마스킹된 키는 원래대로라면 서명 검증에 실패하므로 AWS CLI에서 마스킹을 사용하려면 이 기능이 필요합니다. 이 기능들은 모두 network.tlsTerminate가 필요하며 사용자, 관리형 또는 --settings 범위에서만 적용됩니다. 저장소가 자격 증명을 몰래 다른 경로로 전달하는 마스킹 설정을 포함할 수 없습니다.²⁰¹

v2.1.216부터 sandbox.filesystem.disabled 설정을 사용하면 네트워크 송신 제어를 유지하면서 파일 시스템 격리를 건너뛸 수 있습니다. 파일 시스템 격리 환경 때문에 빌드 도구가 작동하지 않지만 외부 트래픽에는 도메인 허용 목록을 계속 적용하려 할 때 유용합니다.¹⁹²

v2.1.219부터 sandbox.network.strictAllowlist 설정은 허용 목록에 없는 호스트를 승인 요청 없이 즉시 거부합니다. 기본적으로 sandbox 명령이 allowedDomains에 없는 호스트에 연결하면 권한 요청이 표시됩니다. strictAllowlist를 활성화하면 연결이 바로 거부됩니다. 아무도 요청에 응답하지 않아 작업이 멈출 수 있고 “예상하지 못한 외부 연결은 나에게 물어본다”는 정책도 적절하지 않은 CI, 백그라운드 agents, 야간 루프 같은 무인 실행에 사용할 설정입니다. 이로써 네트워크 설정의 3가지 요소가 완성됩니다. allowedDomains는 허용 대상을 지정하고, 아래의 deniedDomains는 넓은 허용 범위에서 예외를 제외하며, strictAllowlist는 그 밖의 대상에 대해 승인을 요청할지 실패할지를 결정합니다.¹⁹⁶ v2.1.229에서는 도메인 목록 구문도 강화되었습니다. IPv6 리터럴은 대괄호로 묶어야 하며([::1]:443), 모호한 표기법은 안전하게 실패하도록 적용되고 /doctor가 이를 표시합니다.²³⁴ v2.1.236에서는 2가지 보안 강화가 더 추가되었습니다. macOS에서 와일드카드 읽기 거부 규칙(예: **/.env)은 이제 허용된 읽기 영역 안에서도 우선 적용되고, 일치한 디렉터리의 콘텐츠까지 포함하며, 거부된 파일의 이름을 바꾸는 방식으로 우회할 수 없습니다. 또한 auto 모드가 활성화된 동안에는 Monitor 허용 규칙이 적용되지 않습니다. Monitor 명령은 Bash 명령과 같은 분류기 검토를 거칩니다. 이제 auto 모드 분류기 자체도 Bedrock, Vertex AI, Foundry 및 텔레메트리가 비활성화된 환경에서 Claude API와 동일한 기본값으로 실행되며, 여기에는 심각도 점수가 포함된 분류도 포함됩니다.²²³ v2.1.273에서는 해당 게이트웨이의 기본 작동 방식이 변경되었습니다. 현재 auto 모드는 로컬 분류기를 기본값으로 사용하며, CLAUDE_CODE_AUTO_MODE_SERVER=1을 설정하면 플랫폼의 서버 측 분류기를 사용합니다.²¹⁷

Auto 모드의 명령별 allowed_domains(v2.1.271): sandbox를 활성화하면 auto 모드의 Bash, PowerShell, Monitor 명령이 자체 allowed_domains를 포함할 수 있습니다. 명령에 필요한 호스트는 명령과 함께 검토되고 해당 명령에 대해서만 열리며, 다른 호스트는 거부됩니다. 외부 연결 권한은 더 이상 세션 전체에 부여되지 않습니다. 각 명령이 대상을 직접 지정하며, 정확히 그 명령과 대상의 조합이 검토됩니다.²¹⁶

엄격한 sandbox 모드와 ! 예외(sandbox.allowUnsandboxedCommands, v2.1.260). 이 가이드에서 이전까지 다루지 않았던 설정입니다. 기본적으로 sandbox에서 실패한 명령은 일반 권한 절차를 거쳐 dangerouslyDisableSandbox 탈출구를 사용하여 sandbox 밖에서 다시 시도할 수 있습니다. /sandbox의 Overrides 탭에 Strict sandbox mode로 표시되는 sandbox.allowUnsandboxedCommands: false를 설정하면 이 탈출구가 비활성화됩니다. 해당 매개변수는 무시되며 모든 명령은 sandbox에서 실행되거나 excludedCommands에 등록되어야 합니다. v2.1.260부터는 ! bash 모드 프롬프트에서 직접 입력한 명령이 엄격한 sandbox 모드에서도 sandbox 밖에서 실행됩니다. 이는 “자신의 터미널에 직접 입력하는 것과 같은” 동작입니다. 엄격성은 Claude가 실행하는 명령에 적용되며 사용자가 직접 입력하는 명령에는 적용되지 않습니다. 위협 모델에서 ! 명령도 격리 환경을 따르는 것으로 간주했다면 이제는 그렇지 않습니다.²¹²

Sandbox에서 실행할 때: - 파일 시스템 접근이 프로젝트 디렉터리로 제한됩니다 - 네트워크 접근이 제어됩니다 - 특정 명령은 sandbox 제한에서 제외됩니다 - autoAllowBashIfSandboxed가 true이면 Bash 명령이 자동 허용됩니다

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

보안 참고 사항(v2.1.34+): 이전에는 autoAllowBashIfSandboxed가 활성화된 경우 sandbox.excludedCommands 또는 dangerouslyDisableSandbox를 통해 sandbox에서 제외된 명령이 Bash 승인 요청 권한 규칙을 우회할 수 있었으며, 이 문제는 v2.1.34에서 수정되었습니다.⁸⁷ v2.1.38부터 sandbox 모드에서는 .claude/skills에 대한 쓰기가 차단되어 프롬프트 인젝션으로 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가 실행될 때마다 포매터가 작동합니다. 규정 준수, 보안, 팀 표준에서는 확률적인 방식보다 결정론적인 방식이 더 적합합니다.⁴

사용 가능한 이벤트