Name: Claude Code 고급 활용
Author: reopt

Claude Code 사용자를 위한 멀티세션, 자동화, 확장 운영 패턴을 정리한 가이드

2026-09-12 최신 변경

Claude Code v2.1.263~v2.1.269(9월 6~11일)을 반영했습니다. 2026-09-12 KST npm 기준은 latest/next=2.1.269, stable=2.1.236입니다. 최신 기능 검증과 팀의 stable 채널 선택을 구분하세요.

플러그인: claude plugin eval은 JSON·HTML 평가 보고서를 만들고, install·uninstall·update·enable·disable은 --json을 지원합니다. --plugin-dir에는 여러 plugin의 상위 폴더도 지정할 수 있습니다.
명령·설정: /output-style [name]이 Remote Control·cloud·headless에도 적용됩니다. maxEffortLevel은 전체 또는 modelSettings의 모델별 effort 상한을 정합니다. bashEditDiffEnabled로 Bash 파일 편집 diff를 결과에 표시할 수 있습니다.
복구·호환성: 2.1.266은 gateway 강제 로그인 회귀, 2.1.268은 2.1.265 이후 Anthropic 호환 endpoint의 HTTP 400을 수정합니다. /goal은 API·네트워크·사용량 한도 오류 뒤 backoff 재시도 또는 이유를 밝힌 일시정지로 처리됩니다.
권한·운영: symlink 경로의 deny/ask, Bash tee의 쓰기 경계, MCP·plugin 오류의 비밀값 노출이 수정됐습니다. WebFetch는 기본 300초 deadline을 갖고, /ultrareview --post는 결과 도착 시 PR 댓글을 바로 게시합니다.

근거: 공식 Changelog, npm dist-tags.

이전 검증 기록 (2026-09-05)

Claude Code는 터미널 기반 AI 코딩 에이전트입니다. 이 핸드북은 고급 사용자가 멀티세션과 자동화로 생산성을 끌어올리는 방법을 다룹니다.

대상 독자

Claude Code를 이미 쓰고 있고, 멀티세션·확장·자동화에 관심 있는 개발자. 기본 사용법은 생략하고 고급 패턴 위주로 구성했습니다.

최근 업데이트 하이라이트

기준일

2026년 9월 5일 재검증 기준, 공식 Claude Code Changelog v2.1.261, npm latest=2.1.261, next=2.1.261, stable=2.1.236과 Claude Fable 5.1 모델 문서를 반영했습니다.

Fable 5.1 출시(2026-09-01): Claude Fable 5.1(claude-fable-5-1)이 Claude Code v2.1.257부터 기본 Fable 모델입니다. 요구 버전은 v2.1.255 이상이고 fable·best alias가 Fable 5.1로 해석되며, Fable 5는 /model claude-fable-5로만 선택합니다. 단가( $10/$ 50 per MTok)·1M context·128K output·상시 adaptive thinking은 Fable 5와 같고 prompt cache read만 $0.25/MTok로 1/4입니다. 어떤 플랜·provider에서도 기본 모델은 아닙니다.
Fable 5.1 분류기 fallback: Fable 5.1·5 요청이 생물학 분류기에 걸리면 Opus 5로, 사이버보안 분류기에 걸리면 Opus 4.8로 자동 재실행됩니다. Opus 5는 사이버보안 플래그만 Opus 4.8로 fallback하고 생물학 플래그는 거절됩니다. switchModelsOnFlag: false로 끌 수 있고 third-party provider는 ANTHROPIC_DEFAULT_OPUS_MODEL이 있어야 fallback이 동작합니다.
Fable 5.1 API 차이: 커스텀 하네스가 claude-fable-5-1로 옮길 때 forced tool_choice(any·tool) 400, thinking block의 생성 모델 귀속, 이전 턴 편집 시 thinking 무효화(2026-08-31 이후 생성 계정은 400 강제) 세 가지가 breaking change입니다. per-message effort·turn-scoped system message·display: "updates"·content provenance는 additive입니다. Claude Code 자체는 대화를 append-only로 유지하므로 영향이 없습니다.
v2.1.252~v2.1.261 운영 변경: Claude apps gateway 세션의 fable/best는 gateway 호환을 위해 Fable 5로 남습니다(v2.1.257). /effort picker의 s 세션 한정 적용, CLAUDE_CODE_SUBAGENT_MODEL_FORCE, timeFormat·timeZone, --permission-prompts none, managedMcpServers, /diff 패널, /skill-doctor, bashOutputMaxChars·taskOutputMaxChars가 추가됐습니다. v2.1.260은 Fable 5.1의 picker 노출·tool result 후 prompt caching·[1m] 태그를 수정하고 Opus·Fable 1M 세션의 auto-compact를 1M 한도 직전으로 옮겼으며, Fable 5.1에서 세션 중 effort 변경이 prompt cache를 무효화하지 않게 했습니다.
v2.1.239~v2.1.247 운영 변경: /usage의 loop별 사용량, v2.1.242+ user/managed modelPicker, 메인/서브에이전트별 prompt-cache TTL, /permissions의 Auto 모드 규칙 탭이 추가됐습니다. modelPricing은 Changelog에 있으나 현재 Settings reference에는 schema가 없고, /claude-api cost-optimize도 v2.1.247 release note가 현재 Commands signature보다 앞서므로 설치본에서 확인합니다.
세션·에이전트 안정성: /cd 직후 새 디렉터리의 설정·hook·.mcp.json·skill·agent가 즉시 반영됩니다. maxTurns에 도달한 서브에이전트는 partial 결과로 표시되고, 첫 호출의 모델 404는 세션 fallback chain을 사용합니다. 비대화형 응답은 전송 중단·연결 손실·stall 뒤 자동 continuation을 시도합니다.
컨텍스트·보안 기준: Sonnet 5의 1M 세션은 약 967K 토큰에서 auto-compact하고, untrusted marketplace 텍스트·terminal link·Bash wildcard allow rule·gateway credential 경계가 강화됐습니다. feedbackDrafts는 user/managed scope에서 notify·quiet·off를 허용하며, off는 SendFeedback 도구를 제거합니다.
v2.1.221~v2.1.237 운영 변경: interactive 세션에서는 inherited-context fork mode와 subagent background spawn이 기본값이 됐습니다. 세션 누적 200개 제한은 제거됐고 동시 20개·기본 3단계 제한만 유지됩니다. @로 다른 Claude 세션을 멘션하고 cross-session SendMessage/ListAgents를 사용할 수 있으며, GitLab MR·self-hosted runner·Remote Control과 sandbox/permission 경계가 크게 보강됐습니다.
모델·출력 기본값: v2.1.236의 ANTHROPIC_DEFAULT_MODEL은 명시적 --model, ANTHROPIC_MODEL, settings model, 조직 기본값이 없을 때 새 세션의 기본 모델을 정합니다. v2.1.237에는 내장 Concise output style이 추가됐습니다.
자동화·도구 변화: v2.1.233부터 Opus 4.8·Sonnet 5·Fable 5·Mythos 5 이상에서는 legacy Task/Todo 도구가 기본 비활성화되며, 호환성이 필요하면 CLAUDE_CODE_ENABLE_TODO_TOOLS=1로 복원합니다. claude self-hosted-runner, claude remote-control --continue, plugin command source와 archive+SHA pinning도 운영 표면에 추가됐습니다.
보안·안정성: worktree/symlink, MCP OAuth, cross-session messaging, credential masking, repository trust, /commit-push-pr 위험 플래그 승인, Remote Control 경계가 누적 강화됐습니다. v2.1.237은 gateway/custom base URL의 prompt caching도 수정합니다.
v2.1.206~v2.1.220 운영 변경: Opus 5가 기본 Opus 경로가 됐고, /fork는 별도 background session 복사로 바뀌며 기존 대화-상속 서브에이전트는 /subtask로 분리됐습니다. 세션당 subagent 200개·동시 20개 기본 상한, 기본 3단계 중첩, sandbox.network.strictAllowlist, sandbox.filesystem.disabled, DirectoryAdded hook, headless mcp_server_errors·nested subagent forwarding을 반영했습니다.
Opus 5 기본화: Claude Code v2.1.219부터 opus는 Anthropic API·Claude Platform on AWS·Bedrock·Google Cloud Agent Platform에서 Opus 5로 해석됩니다. Microsoft Foundry는 Opus 4.6이므로 재현 작업은 claude-opus-5 같은 full model name으로 고정합니다. Opus 5는 native 1M context와 fast mode를 지원합니다.
v2.1.202~v2.1.205 운영 변경: dynamic workflow 크기 설정과 workflow OTel 속성, /review의 빠른 단일 패스 복귀, background/Agent View 대규모 안정화, MCP roots/list 확장, headless SessionStart hook 스트리밍 수정, /doctor의 전체 setup checkup 확장, Auto 모드의 transcript 변조·불명확한 rm -rf 차단, --json-schema 검증 수정을 반영했습니다.
v2.1.198~v2.1.201 운영 변경: v2.1.198부터 서브에이전트가 기본적으로 백그라운드에서 실행되고 Claude in Chrome이 GA됐으며 /dataviz 스킬이 추가됐습니다. v2.1.199에서는 SSL·스트리밍·서브에이전트 오류 처리가 수정됐습니다. v2.1.200에서는 기본 permission mode가 Manual로 바뀌었고, v2.1.201에서는 Sonnet 5 세션의 mid-conversation system role 사용이 제거됐습니다.
Sonnet 5 기본화: Claude Code v2.1.197부터 Sonnet 5가 Claude Code의 기본 Sonnet 경로입니다. Anthropic API에서 sonnet alias는 Sonnet 5로 해석되고, Sonnet 5는 native 1M context와 low~max effort를 지원합니다. Pro·Team Standard·Enterprise subscription seat의 default도 Sonnet 5로 바뀝니다.
v2.1.191~v2.1.196 운영 보강: 조직 기본 모델(Org default/Role default), 클릭 가능한 파일 첨부, .mcp.json self-approval 보안 보강, background job transcript 보존, PowerShell git diff/grep exit-code 처리, Remote mid-turn crash recovery, background agent/permission/plugin 검증 수정까지 반영합니다.
이전 v2.1.181~v2.1.190 운영 보강: 보안·샌드박스·MCP·background/subagent 안정화가 중심입니다. sandbox.credentials, destructive command sandbox auto-approval, Windows PowerShell sandbox, MCP login/logout, MCP idle timeout, Korean paste mojibake fix, non-interactive fallback 안정화, app/schema 관련 버그 수정을 반영합니다.
모델 제한과 deprecation warning: v2.1.184부터 main model restriction은 Opus/Sonnet/Haiku/Fable 계열만 허용하는 방향으로 강화됐고, Haiku는 main model로는 사용할 수 없지만 subagent에는 허용됩니다. v2.1.187부터 deprecated model 사용 시 경고가 강화됩니다.
서브에이전트 경계 강화: v2.1.237 기준 중첩 기본값은 메인 대화 아래 3단계이며 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1로 끌 수 있습니다. 동시 20개 기본 상한은 유지되지만 v2.1.224에서 세션 누적 200개 제한은 제거됐습니다. fork mode는 interactive에서 기본 활성화되고 -p/SDK에서는 기본 비활성화됩니다.
Fable 5 추가(이력): Claude Code v2.1.170부터 Claude Fable 5를 사용할 수 있었고, 2026-09-01부터는 Fable 5.1이 그 자리를 이어받았습니다. Fable 계열은 기본 모델이 아니므로 장시간 자율 작업·모호한 원인 분석·대규모 설계 판단처럼 비용을 정당화할 수 있는 작업에 배정합니다. Fable 5는 공식 models overview에서 "legacy, still available"로 분류되며 은퇴 공지는 없습니다.
best alias 변경: best는 Fable 접근 권한이 있으면 최신 Fable(현재 Fable 5.1)을, 아니면 최신 Opus를 선택합니다. Anthropic API 기준 opus는 Opus 5, sonnet은 Sonnet 5입니다.
Fable fallback 운영: Fable 요청이 안전 분류기에 걸리면 Claude Code가 카테고리별 Opus 경로(생물학 → Opus 5, 사이버보안 → Opus 4.8)로 자동 재실행하고 알림을 표시합니다. 프롬프트가 평범한데도 fallback이 발생하면 repo 컨텍스트나 설정을 의심하고 claude --safe-mode로 확인합니다.
Fable 5 재배포(2026-07): Fable 5·Mythos 5는 2026-06-12 미국 수출통제로 약 19일간 전 사용자 접근이 중단됐다가, 6-30 통제 해제로 2026-07-01 Claude Code를 포함한 전 표면에 전역 복원됐습니다. 재배포 시 취약점 탐지 행위를 겨냥한 개선된 안전 분류기가 적용됐고, Fable 5.1은 같은 stop_details 카테고리를 커버하는 분류기를 갖습니다. Pro·Max·Team·일부 Enterprise는 7-07까지 주간 한도의 최대 50%까지 Fable 5를 포함하고 이후 usage credits로 사용합니다. Mythos 5(안전 분류기 없음)와 후속 Mythos 5.1(Fable 5.1과 안전장치 수준만 다른 동일 모델)은 Project Glasswing 승인 고객 전용이라 /model로 선택할 수 없습니다.
Fallback chain 명시: 장기 세션은 fallbackModel 또는 --fallback-model로 availability failure 대응 경로를 미리 지정합니다.
Opus 5 기준 모델 정책: Fable을 사용할 수 없거나 비용이 맞지 않을 때의 최신 고성능 Opus 경로는 Opus 5입니다. Claude Code v2.1.219 이상이 필요하고, 이전 Opus 4.8 pin은 호환성·회귀 비교 용도로만 유지합니다.
Provider별 alias 차이 명시: Anthropic API·Claude Platform on AWS·Bedrock·Google Cloud Agent Platform은 opus → Opus 5입니다. Microsoft Foundry는 Opus 4.6, Sonnet은 provider에 따라 4.5~5이므로 최신 모델을 재현하려면 full model name 또는 ANTHROPIC_DEFAULT_*_MODEL pinning을 확인해야 합니다.
Fast mode 재평가: /fast는 Opus 5와 Opus 4.8에 적용됩니다. Opus 4.7은 v2.1.219부터 fast mode 대상에서 빠졌고(2026-07-24 API에서 제거), Fable 5.1·Fable 5는 지원 대상이 아니므로 신규 운영 기준은 Opus 5로 옮깁니다.
Agent View와 background sessions: claude agents, /bg//background, claude --bg, claude --bg --exec를 기준으로 병렬 세션을 관리합니다. Agent View는 상태/디렉토리 그룹, PR 필터, ! <command> background job, isolated worktree 정책까지 포함합니다.
Dynamic workflows와 /workflows: v2.1.154에서 Claude가 workflow를 만들고 수십~수백 개 agent를 백그라운드에서 오케스트레이션하는 dynamic workflows가 도입되었습니다. /workflows에서 실행 상태를 보고 pause/resume/save 흐름을 관리합니다.
목표 기반 장기 작업: /goal은 완료 조건을 두고 Claude가 여러 턴에 걸쳐 계속 작업하도록 만드는 명령입니다. interactive, -p, Remote Control 흐름에서 동작하며 background shell/subagent가 남아 있을 때 evaluator가 성급히 종료되지 않도록 보강되었습니다.
명령 표면 업데이트: /usage-credits, /reload-skills, /run, /verify, /run-skill-generator, /code-review, /workflows, /goal, /background를 현재 명령 표면에 추가했습니다. /extra-usage는 /usage-credits로 대체되는 흐름입니다.
보안/운영 보강: Auto mode classifier가 repository bulk transfer 같은 data exfiltration 탐지를 강화했고, sandbox/worktree/PowerShell permission parser 관련 수정이 누적되었습니다. --safe-mode, --session-id, --log-level, autoUpdates, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, CLAUDE_CODE_DISABLE_TERMINAL_TITLE도 운영 기준에 반영했습니다.

이전 중요 변화

Opus 4.7 + xhigh 추론: /effort, --effort, 모델 피커에서 xhigh를 사용할 수 있고, 인수 없이 /effort를 실행하면 인터랙티브 슬라이더가 열립니다. Opus 4.8 이후에는 high 기본값 + xhigh 선택 경로로 이해하는 편이 정확합니다. (v2.1.111, v2.1.154)
신규 고급 명령: /ultrareview, /fewer-permission-prompts, /focus, /recap, /tui, /team-onboarding이 추가되어 코드 리뷰, 프롬프트 감소, 세션 복귀, 렌더러 전환, 팀 온보딩 문서화가 강화되었습니다. (v2.1.101~v2.1.111, 현재 commands docs 명칭 반영)
세션 복귀 UX 강화: compact 또는 resume 뒤에 session recap이 기본 활성화되고, 필요하면 /recap으로 수동 생성할 수 있습니다. (v2.1.108~v2.1.110)
설치/업데이트 경로 정리: 공식 설치 문서는 네이티브 인스톨러와 Homebrew/WinGet을 우선 경로로 안내하고, npm 설치는 deprecated로 명시합니다. (v2.1.111)
퍼미션 피로 감소: 읽기 전용 glob Bash(ls *.ts)와 cd <project-dir> && ... 패턴이 더 이상 권한 프롬프트를 트리거하지 않고, /fewer-permission-prompts가 공통 allowlist 제안을 생성합니다. cd <current-directory> && git ... 같은 no-op 패턴도 추가로 정리되었습니다. (v2.1.111~v2.1.113)
훅/워크트리 운영 보강: PreCompact 훅이 compaction 자체를 block할 수 있고, EnterWorktree 도구에 기존 worktree 경로를 직접 넘길 수 있습니다. (v2.1.105)
헤드리스/플러그인 신호 개선: --output-format stream-json의 init 이벤트에 plugin_errors가 포함되고, models가 Skill tool을 통해 내장 슬래시 명령도 호출할 수 있습니다. (v2.1.108~v2.1.111)
운영/보안 경계 보강: CLI 실행 경로가 플랫폼별 네이티브 Claude Code binary 중심으로 정리되고, sandbox.network.deniedDomains로 넓은 allowlist 안에서도 민감 도메인을 예외 차단할 수 있게 되었습니다. (v2.1.113)
서브에이전트/원격 안정성 보강: 중간에 멈춘 subagent는 10분 후 명시적으로 실패 처리되고, Remote Control 세션의 subagent transcript 스트리밍/아카이브 누락 문제가 보정되었습니다. (v2.1.113)
Auto 모드: AI 분류기가 도구 호출 위험도를 판단, 안전한 작업 자동 진행 + 위험 작업 차단 (2026-03-24)
Computer Use: macOS 화면을 보고 마우스/키보드를 제어하는 연구 프리뷰 (2026-03-24)
Dispatch: iPhone에서 작업 전송 → 데스크탑에서 자동 실행 → 완료 알림 (2026-03-17)
PowerShell 도구: Windows에서 네이티브 PowerShell 실행 (v2.1.84 프리뷰)
훅 확장: PermissionDenied, CwdChanged, FileChanged, TaskCreated 이벤트 + 조건부 if 필드
운영 제어 강화: forceRemoteSettingsRefresh fail-closed 정책, Auto 모드 Recent 재시도, Remote Control hostname prefix (v2.1.89-92)
에이전트 UX 강화: /agents의 ● N running, Running/Library 탭, Run agent/View running instance (v2.1.97-98)
--bare 경량 실행: 스크립트용 -p 호출에서 hooks/LSP/플러그인을 건너뛰는 최소 실행 모드 (v2.1.81)
--channels 연구 프리뷰: MCP 서버가 세션에 메시지를 푸시하고, 폰으로 도구 승인 릴레이 (v2.1.80-81)
1M 컨텍스트 기본화: Opus 4.6가 Max/Team/Enterprise에서 1M 컨텍스트 윈도우 기본 적용 (v2.1.75)
MCP 고도화: elicitation, Channels, CIMD/RFC 9728 OAuth, 서버 중복 제거, maxResultSizeChars, nonblocking 연결
모델: Sonnet 4.6 출시(2026-02-17), Opus 4.6 64k 기본 출력, thinking summaries 기본 비활성화
Worktree 격리: --worktree 플래그, worktree.sparsePaths sparse-checkout, 세션 재개 시 자동 전환
추론 제어: /effort (low ○ / medium ◐ / high ●), "ultrathink", 스킬/커맨드 effort frontmatter
서브에이전트: initialPrompt 자동 시작, @ 멘션 타입어헤드, named 서브에이전트, background partial-progress 보고, dynamic MCP 상속, isolated worktree 접근 안정화
스킬/플러그인: paths: glob 필터, 스킬 listing cap 1,536자와 토큰 수 정렬, disableSkillShellExecution, 플러그인 bin//monitors, /claude-api의 Managed Agents 가이드 확장
명령 UX: /powerup, 인터랙티브 /release-notes, /cost 모델별·cache-hit breakdown, /tag//vim 제거
성능 개선: --resume 45% 빠르게, 시작 시 ~80MB 메모리 절감, Read 도구 압축 포맷
VS Code 강화: /remote-control 브릿지, AI 세션 제목, 트랜스크립트 검색, Desktop 앱
Code Review: 멀티에이전트 PR 리뷰 (연구 프리뷰, Team/Enterprise)
Remote Control & Dispatch: 모든 플랜에서 로컬 세션을 모바일/브라우저로 접속

핸드북 구조

참고 문서

Claude Code 개요/설치: https://code.claude.com/docs/ko/setup (한국어)
요금제: https://claude.com/ko-kr/pricing (한국어)
Changelog: https://code.claude.com/docs/en/changelog (영어)
모델 설정: https://code.claude.com/docs/en/model-config (영어)
Agent View: https://code.claude.com/docs/en/agent-view (영어)

2026-09-12 최신 변경

플러그인: claude plugin eval은 JSON·HTML 평가 보고서를 만들고, install·uninstall·update·enable·disable은 --json을 지원합니다. --plugin-dir에는 여러 plugin의 상위 폴더도 지정할 수 있습니다.
명령·설정: /output-style [name]이 Remote Control·cloud·headless에도 적용됩니다. maxEffortLevel은 전체 또는 modelSettings의 모델별 effort 상한을 정합니다. bashEditDiffEnabled로 Bash 파일 편집 diff를 결과에 표시할 수 있습니다.
복구·호환성: 2.1.266은 gateway 강제 로그인 회귀, 2.1.268은 2.1.265 이후 Anthropic 호환 endpoint의 HTTP 400을 수정합니다. /goal은 API·네트워크·사용량 한도 오류 뒤 backoff 재시도 또는 이유를 밝힌 일시정지로 처리됩니다.
권한·운영: symlink 경로의 deny/ask, Bash tee의 쓰기 경계, MCP·plugin 오류의 비밀값 노출이 수정됐습니다. WebFetch는 기본 300초 deadline을 갖고, /ultrareview --post는 결과 도착 시 PR 댓글을 바로 게시합니다.

근거: 공식 Changelog, npm dist-tags.

이전 검증 기록 (2026-09-05)

Claude Code는 터미널 기반 AI 코딩 에이전트입니다. 이 핸드북은 고급 사용자가 멀티세션과 자동화로 생산성을 끌어올리는 방법을 다룹니다.

대상 독자

Claude Code를 이미 쓰고 있고, 멀티세션·확장·자동화에 관심 있는 개발자. 기본 사용법은 생략하고 고급 패턴 위주로 구성했습니다.

최근 업데이트 하이라이트

기준일

2026년 9월 5일 재검증 기준, 공식 Claude Code Changelog v2.1.261, npm latest=2.1.261, next=2.1.261, stable=2.1.236과 Claude Fable 5.1 모델 문서를 반영했습니다.

Fable 5.1 출시(2026-09-01): Claude Fable 5.1(claude-fable-5-1)이 Claude Code v2.1.257부터 기본 Fable 모델입니다. 요구 버전은 v2.1.255 이상이고 fable·best alias가 Fable 5.1로 해석되며, Fable 5는 /model claude-fable-5로만 선택합니다. 단가( $10/$ 50 per MTok)·1M context·128K output·상시 adaptive thinking은 Fable 5와 같고 prompt cache read만 $0.25/MTok로 1/4입니다. 어떤 플랜·provider에서도 기본 모델은 아닙니다.
Fable 5.1 분류기 fallback: Fable 5.1·5 요청이 생물학 분류기에 걸리면 Opus 5로, 사이버보안 분류기에 걸리면 Opus 4.8로 자동 재실행됩니다. Opus 5는 사이버보안 플래그만 Opus 4.8로 fallback하고 생물학 플래그는 거절됩니다. switchModelsOnFlag: false로 끌 수 있고 third-party provider는 ANTHROPIC_DEFAULT_OPUS_MODEL이 있어야 fallback이 동작합니다.
Fable 5.1 API 차이: 커스텀 하네스가 claude-fable-5-1로 옮길 때 forced tool_choice(any·tool) 400, thinking block의 생성 모델 귀속, 이전 턴 편집 시 thinking 무효화(2026-08-31 이후 생성 계정은 400 강제) 세 가지가 breaking change입니다. per-message effort·turn-scoped system message·display: "updates"·content provenance는 additive입니다. Claude Code 자체는 대화를 append-only로 유지하므로 영향이 없습니다.
v2.1.252~v2.1.261 운영 변경: Claude apps gateway 세션의 fable/best는 gateway 호환을 위해 Fable 5로 남습니다(v2.1.257). /effort picker의 s 세션 한정 적용, CLAUDE_CODE_SUBAGENT_MODEL_FORCE, timeFormat·timeZone, --permission-prompts none, managedMcpServers, /diff 패널, /skill-doctor, bashOutputMaxChars·taskOutputMaxChars가 추가됐습니다. v2.1.260은 Fable 5.1의 picker 노출·tool result 후 prompt caching·[1m] 태그를 수정하고 Opus·Fable 1M 세션의 auto-compact를 1M 한도 직전으로 옮겼으며, Fable 5.1에서 세션 중 effort 변경이 prompt cache를 무효화하지 않게 했습니다.
v2.1.239~v2.1.247 운영 변경: /usage의 loop별 사용량, v2.1.242+ user/managed modelPicker, 메인/서브에이전트별 prompt-cache TTL, /permissions의 Auto 모드 규칙 탭이 추가됐습니다. modelPricing은 Changelog에 있으나 현재 Settings reference에는 schema가 없고, /claude-api cost-optimize도 v2.1.247 release note가 현재 Commands signature보다 앞서므로 설치본에서 확인합니다.
세션·에이전트 안정성: /cd 직후 새 디렉터리의 설정·hook·.mcp.json·skill·agent가 즉시 반영됩니다. maxTurns에 도달한 서브에이전트는 partial 결과로 표시되고, 첫 호출의 모델 404는 세션 fallback chain을 사용합니다. 비대화형 응답은 전송 중단·연결 손실·stall 뒤 자동 continuation을 시도합니다.
컨텍스트·보안 기준: Sonnet 5의 1M 세션은 약 967K 토큰에서 auto-compact하고, untrusted marketplace 텍스트·terminal link·Bash wildcard allow rule·gateway credential 경계가 강화됐습니다. feedbackDrafts는 user/managed scope에서 notify·quiet·off를 허용하며, off는 SendFeedback 도구를 제거합니다.
v2.1.221~v2.1.237 운영 변경: interactive 세션에서는 inherited-context fork mode와 subagent background spawn이 기본값이 됐습니다. 세션 누적 200개 제한은 제거됐고 동시 20개·기본 3단계 제한만 유지됩니다. @로 다른 Claude 세션을 멘션하고 cross-session SendMessage/ListAgents를 사용할 수 있으며, GitLab MR·self-hosted runner·Remote Control과 sandbox/permission 경계가 크게 보강됐습니다.
모델·출력 기본값: v2.1.236의 ANTHROPIC_DEFAULT_MODEL은 명시적 --model, ANTHROPIC_MODEL, settings model, 조직 기본값이 없을 때 새 세션의 기본 모델을 정합니다. v2.1.237에는 내장 Concise output style이 추가됐습니다.
자동화·도구 변화: v2.1.233부터 Opus 4.8·Sonnet 5·Fable 5·Mythos 5 이상에서는 legacy Task/Todo 도구가 기본 비활성화되며, 호환성이 필요하면 CLAUDE_CODE_ENABLE_TODO_TOOLS=1로 복원합니다. claude self-hosted-runner, claude remote-control --continue, plugin command source와 archive+SHA pinning도 운영 표면에 추가됐습니다.
보안·안정성: worktree/symlink, MCP OAuth, cross-session messaging, credential masking, repository trust, /commit-push-pr 위험 플래그 승인, Remote Control 경계가 누적 강화됐습니다. v2.1.237은 gateway/custom base URL의 prompt caching도 수정합니다.
v2.1.206~v2.1.220 운영 변경: Opus 5가 기본 Opus 경로가 됐고, /fork는 별도 background session 복사로 바뀌며 기존 대화-상속 서브에이전트는 /subtask로 분리됐습니다. 세션당 subagent 200개·동시 20개 기본 상한, 기본 3단계 중첩, sandbox.network.strictAllowlist, sandbox.filesystem.disabled, DirectoryAdded hook, headless mcp_server_errors·nested subagent forwarding을 반영했습니다.
Opus 5 기본화: Claude Code v2.1.219부터 opus는 Anthropic API·Claude Platform on AWS·Bedrock·Google Cloud Agent Platform에서 Opus 5로 해석됩니다. Microsoft Foundry는 Opus 4.6이므로 재현 작업은 claude-opus-5 같은 full model name으로 고정합니다. Opus 5는 native 1M context와 fast mode를 지원합니다.
v2.1.202~v2.1.205 운영 변경: dynamic workflow 크기 설정과 workflow OTel 속성, /review의 빠른 단일 패스 복귀, background/Agent View 대규모 안정화, MCP roots/list 확장, headless SessionStart hook 스트리밍 수정, /doctor의 전체 setup checkup 확장, Auto 모드의 transcript 변조·불명확한 rm -rf 차단, --json-schema 검증 수정을 반영했습니다.
v2.1.198~v2.1.201 운영 변경: v2.1.198부터 서브에이전트가 기본적으로 백그라운드에서 실행되고 Claude in Chrome이 GA됐으며 /dataviz 스킬이 추가됐습니다. v2.1.199에서는 SSL·스트리밍·서브에이전트 오류 처리가 수정됐습니다. v2.1.200에서는 기본 permission mode가 Manual로 바뀌었고, v2.1.201에서는 Sonnet 5 세션의 mid-conversation system role 사용이 제거됐습니다.
Sonnet 5 기본화: Claude Code v2.1.197부터 Sonnet 5가 Claude Code의 기본 Sonnet 경로입니다. Anthropic API에서 sonnet alias는 Sonnet 5로 해석되고, Sonnet 5는 native 1M context와 low~max effort를 지원합니다. Pro·Team Standard·Enterprise subscription seat의 default도 Sonnet 5로 바뀝니다.
v2.1.191~v2.1.196 운영 보강: 조직 기본 모델(Org default/Role default), 클릭 가능한 파일 첨부, .mcp.json self-approval 보안 보강, background job transcript 보존, PowerShell git diff/grep exit-code 처리, Remote mid-turn crash recovery, background agent/permission/plugin 검증 수정까지 반영합니다.
이전 v2.1.181~v2.1.190 운영 보강: 보안·샌드박스·MCP·background/subagent 안정화가 중심입니다. sandbox.credentials, destructive command sandbox auto-approval, Windows PowerShell sandbox, MCP login/logout, MCP idle timeout, Korean paste mojibake fix, non-interactive fallback 안정화, app/schema 관련 버그 수정을 반영합니다.
모델 제한과 deprecation warning: v2.1.184부터 main model restriction은 Opus/Sonnet/Haiku/Fable 계열만 허용하는 방향으로 강화됐고, Haiku는 main model로는 사용할 수 없지만 subagent에는 허용됩니다. v2.1.187부터 deprecated model 사용 시 경고가 강화됩니다.
서브에이전트 경계 강화: v2.1.237 기준 중첩 기본값은 메인 대화 아래 3단계이며 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1로 끌 수 있습니다. 동시 20개 기본 상한은 유지되지만 v2.1.224에서 세션 누적 200개 제한은 제거됐습니다. fork mode는 interactive에서 기본 활성화되고 -p/SDK에서는 기본 비활성화됩니다.
Fable 5 추가(이력): Claude Code v2.1.170부터 Claude Fable 5를 사용할 수 있었고, 2026-09-01부터는 Fable 5.1이 그 자리를 이어받았습니다. Fable 계열은 기본 모델이 아니므로 장시간 자율 작업·모호한 원인 분석·대규모 설계 판단처럼 비용을 정당화할 수 있는 작업에 배정합니다. Fable 5는 공식 models overview에서 "legacy, still available"로 분류되며 은퇴 공지는 없습니다.
best alias 변경: best는 Fable 접근 권한이 있으면 최신 Fable(현재 Fable 5.1)을, 아니면 최신 Opus를 선택합니다. Anthropic API 기준 opus는 Opus 5, sonnet은 Sonnet 5입니다.
Fable fallback 운영: Fable 요청이 안전 분류기에 걸리면 Claude Code가 카테고리별 Opus 경로(생물학 → Opus 5, 사이버보안 → Opus 4.8)로 자동 재실행하고 알림을 표시합니다. 프롬프트가 평범한데도 fallback이 발생하면 repo 컨텍스트나 설정을 의심하고 claude --safe-mode로 확인합니다.
Fable 5 재배포(2026-07): Fable 5·Mythos 5는 2026-06-12 미국 수출통제로 약 19일간 전 사용자 접근이 중단됐다가, 6-30 통제 해제로 2026-07-01 Claude Code를 포함한 전 표면에 전역 복원됐습니다. 재배포 시 취약점 탐지 행위를 겨냥한 개선된 안전 분류기가 적용됐고, Fable 5.1은 같은 stop_details 카테고리를 커버하는 분류기를 갖습니다. Pro·Max·Team·일부 Enterprise는 7-07까지 주간 한도의 최대 50%까지 Fable 5를 포함하고 이후 usage credits로 사용합니다. Mythos 5(안전 분류기 없음)와 후속 Mythos 5.1(Fable 5.1과 안전장치 수준만 다른 동일 모델)은 Project Glasswing 승인 고객 전용이라 /model로 선택할 수 없습니다.
Fallback chain 명시: 장기 세션은 fallbackModel 또는 --fallback-model로 availability failure 대응 경로를 미리 지정합니다.
Opus 5 기준 모델 정책: Fable을 사용할 수 없거나 비용이 맞지 않을 때의 최신 고성능 Opus 경로는 Opus 5입니다. Claude Code v2.1.219 이상이 필요하고, 이전 Opus 4.8 pin은 호환성·회귀 비교 용도로만 유지합니다.
Provider별 alias 차이 명시: Anthropic API·Claude Platform on AWS·Bedrock·Google Cloud Agent Platform은 opus → Opus 5입니다. Microsoft Foundry는 Opus 4.6, Sonnet은 provider에 따라 4.5~5이므로 최신 모델을 재현하려면 full model name 또는 ANTHROPIC_DEFAULT_*_MODEL pinning을 확인해야 합니다.
Fast mode 재평가: /fast는 Opus 5와 Opus 4.8에 적용됩니다. Opus 4.7은 v2.1.219부터 fast mode 대상에서 빠졌고(2026-07-24 API에서 제거), Fable 5.1·Fable 5는 지원 대상이 아니므로 신규 운영 기준은 Opus 5로 옮깁니다.
Agent View와 background sessions: claude agents, /bg//background, claude --bg, claude --bg --exec를 기준으로 병렬 세션을 관리합니다. Agent View는 상태/디렉토리 그룹, PR 필터, ! <command> background job, isolated worktree 정책까지 포함합니다.
Dynamic workflows와 /workflows: v2.1.154에서 Claude가 workflow를 만들고 수십~수백 개 agent를 백그라운드에서 오케스트레이션하는 dynamic workflows가 도입되었습니다. /workflows에서 실행 상태를 보고 pause/resume/save 흐름을 관리합니다.
목표 기반 장기 작업: /goal은 완료 조건을 두고 Claude가 여러 턴에 걸쳐 계속 작업하도록 만드는 명령입니다. interactive, -p, Remote Control 흐름에서 동작하며 background shell/subagent가 남아 있을 때 evaluator가 성급히 종료되지 않도록 보강되었습니다.
명령 표면 업데이트: /usage-credits, /reload-skills, /run, /verify, /run-skill-generator, /code-review, /workflows, /goal, /background를 현재 명령 표면에 추가했습니다. /extra-usage는 /usage-credits로 대체되는 흐름입니다.
보안/운영 보강: Auto mode classifier가 repository bulk transfer 같은 data exfiltration 탐지를 강화했고, sandbox/worktree/PowerShell permission parser 관련 수정이 누적되었습니다. --safe-mode, --session-id, --log-level, autoUpdates, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, CLAUDE_CODE_DISABLE_TERMINAL_TITLE도 운영 기준에 반영했습니다.

이전 중요 변화

Opus 4.7 + xhigh 추론: /effort, --effort, 모델 피커에서 xhigh를 사용할 수 있고, 인수 없이 /effort를 실행하면 인터랙티브 슬라이더가 열립니다. Opus 4.8 이후에는 high 기본값 + xhigh 선택 경로로 이해하는 편이 정확합니다. (v2.1.111, v2.1.154)
신규 고급 명령: /ultrareview, /fewer-permission-prompts, /focus, /recap, /tui, /team-onboarding이 추가되어 코드 리뷰, 프롬프트 감소, 세션 복귀, 렌더러 전환, 팀 온보딩 문서화가 강화되었습니다. (v2.1.101~v2.1.111, 현재 commands docs 명칭 반영)
세션 복귀 UX 강화: compact 또는 resume 뒤에 session recap이 기본 활성화되고, 필요하면 /recap으로 수동 생성할 수 있습니다. (v2.1.108~v2.1.110)
설치/업데이트 경로 정리: 공식 설치 문서는 네이티브 인스톨러와 Homebrew/WinGet을 우선 경로로 안내하고, npm 설치는 deprecated로 명시합니다. (v2.1.111)
퍼미션 피로 감소: 읽기 전용 glob Bash(ls *.ts)와 cd <project-dir> && ... 패턴이 더 이상 권한 프롬프트를 트리거하지 않고, /fewer-permission-prompts가 공통 allowlist 제안을 생성합니다. cd <current-directory> && git ... 같은 no-op 패턴도 추가로 정리되었습니다. (v2.1.111~v2.1.113)
훅/워크트리 운영 보강: PreCompact 훅이 compaction 자체를 block할 수 있고, EnterWorktree 도구에 기존 worktree 경로를 직접 넘길 수 있습니다. (v2.1.105)
헤드리스/플러그인 신호 개선: --output-format stream-json의 init 이벤트에 plugin_errors가 포함되고, models가 Skill tool을 통해 내장 슬래시 명령도 호출할 수 있습니다. (v2.1.108~v2.1.111)
운영/보안 경계 보강: CLI 실행 경로가 플랫폼별 네이티브 Claude Code binary 중심으로 정리되고, sandbox.network.deniedDomains로 넓은 allowlist 안에서도 민감 도메인을 예외 차단할 수 있게 되었습니다. (v2.1.113)
서브에이전트/원격 안정성 보강: 중간에 멈춘 subagent는 10분 후 명시적으로 실패 처리되고, Remote Control 세션의 subagent transcript 스트리밍/아카이브 누락 문제가 보정되었습니다. (v2.1.113)
Auto 모드: AI 분류기가 도구 호출 위험도를 판단, 안전한 작업 자동 진행 + 위험 작업 차단 (2026-03-24)
Computer Use: macOS 화면을 보고 마우스/키보드를 제어하는 연구 프리뷰 (2026-03-24)
Dispatch: iPhone에서 작업 전송 → 데스크탑에서 자동 실행 → 완료 알림 (2026-03-17)
PowerShell 도구: Windows에서 네이티브 PowerShell 실행 (v2.1.84 프리뷰)
훅 확장: PermissionDenied, CwdChanged, FileChanged, TaskCreated 이벤트 + 조건부 if 필드
운영 제어 강화: forceRemoteSettingsRefresh fail-closed 정책, Auto 모드 Recent 재시도, Remote Control hostname prefix (v2.1.89-92)
에이전트 UX 강화: /agents의 ● N running, Running/Library 탭, Run agent/View running instance (v2.1.97-98)
--bare 경량 실행: 스크립트용 -p 호출에서 hooks/LSP/플러그인을 건너뛰는 최소 실행 모드 (v2.1.81)
--channels 연구 프리뷰: MCP 서버가 세션에 메시지를 푸시하고, 폰으로 도구 승인 릴레이 (v2.1.80-81)
1M 컨텍스트 기본화: Opus 4.6가 Max/Team/Enterprise에서 1M 컨텍스트 윈도우 기본 적용 (v2.1.75)
MCP 고도화: elicitation, Channels, CIMD/RFC 9728 OAuth, 서버 중복 제거, maxResultSizeChars, nonblocking 연결
모델: Sonnet 4.6 출시(2026-02-17), Opus 4.6 64k 기본 출력, thinking summaries 기본 비활성화
Worktree 격리: --worktree 플래그, worktree.sparsePaths sparse-checkout, 세션 재개 시 자동 전환
추론 제어: /effort (low ○ / medium ◐ / high ●), "ultrathink", 스킬/커맨드 effort frontmatter
서브에이전트: initialPrompt 자동 시작, @ 멘션 타입어헤드, named 서브에이전트, background partial-progress 보고, dynamic MCP 상속, isolated worktree 접근 안정화
스킬/플러그인: paths: glob 필터, 스킬 listing cap 1,536자와 토큰 수 정렬, disableSkillShellExecution, 플러그인 bin//monitors, /claude-api의 Managed Agents 가이드 확장
명령 UX: /powerup, 인터랙티브 /release-notes, /cost 모델별·cache-hit breakdown, /tag//vim 제거
성능 개선: --resume 45% 빠르게, 시작 시 ~80MB 메모리 절감, Read 도구 압축 포맷
VS Code 강화: /remote-control 브릿지, AI 세션 제목, 트랜스크립트 검색, Desktop 앱
Code Review: 멀티에이전트 PR 리뷰 (연구 프리뷰, Team/Enterprise)
Remote Control & Dispatch: 모든 플랜에서 로컬 세션을 모바일/브라우저로 접속

핸드북 구조

참고 문서

Claude Code 개요/설치: https://code.claude.com/docs/ko/setup (한국어)
요금제: https://claude.com/ko-kr/pricing (한국어)
Changelog: https://code.claude.com/docs/en/changelog (영어)
모델 설정: https://code.claude.com/docs/en/model-config (영어)
Agent View: https://code.claude.com/docs/en/agent-view (영어)

Claude Code 고급 활용

최근 수정된 챕터

Ch1. 플랜 & 환경 설정

Ch2. CLAUDE.md 마스터하기

Ch3. 멀티세션 워크플로우

Ch4. 서브에이전트 활용

Ch5. Hooks 시스템

Ch6. MCP 서버 연동

Ch7. Skills & 슬래시 커맨드

Ch8. Plan 모드 활용

Ch9. 컨텍스트 관리

Ch10. IDE 통합

Ch11. 헤드리스 & CI/CD

Ch12. 바이브코딩 실전 패턴

검증 리포트

업데이트 내역

On this page