Claude Code 고급 활용

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

최근 업데이트 하이라이트

• 8월 3일 명령 재검증: v2.1.220 이후 신규 정식 릴리스나 명령 추가·삭제·이름 변경은 없습니다. 8월 1일에 반영한 /fork·/subtask, /verify·/code-review, Opus 5, subagent·sandbox·headless 기준을 유지합니다.

• 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.219 기준 중첩 기본값은 메인 대화 아래 3단계이며 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1로 끌 수 있습니다. 세션당 200개, 동시 20개 기본 상한과 background agent permission prompt를 long-running agent runbook에 반영합니다.

• Fable 5 추가: Claude Code v2.1.170부터 Claude Fable 5를 사용할 수 있습니다. /model fable로 선택하며, 기본 모델은 아니므로 장시간 자율 작업·모호한 원인 분석·대규모 설계 판단처럼 비용을 정당화할 수 있는 작업에 배정합니다.

• best alias 변경: best는 Fable 5 접근 권한이 있으면 Fable을, 아니면 최신 Opus를 선택합니다. Anthropic API 기준 opus는 Opus 5, sonnet은 Sonnet 5입니다.

• Fable fallback 운영: Fable 5 요청이 안전 분류기에 걸리면 Claude Code가 기본 Opus 경로로 자동 재실행하고 알림을 표시합니다. 프롬프트가 평범한데도 fallback이 발생하면 repo 컨텍스트나 설정을 의심하고 claude --safe-mode로 확인합니다.

• Fable 5 재배포(2026-07): Fable 5·Mythos 5는 2026-06-12 미국 수출통제로 약 19일간 전 사용자 접근이 중단됐다가, 6-30 통제 해제로 2026-07-01 Claude Code를 포함한 전 표면에 전역 복원됐습니다. 재배포 시 취약점 탐지 행위를 겨냥한 개선된 안전 분류기가 적용됐으므로 위 자동 fallback도 이 기준을 따릅니다. Pro·Max·Team·일부 Enterprise는 7-07까지 주간 한도의 최대 50%까지 Fable 5를 포함하고 이후 usage credits로 사용합니다. Mythos 5(안전 분류기 없음)는 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 대상에서 빠졌으므로 신규 운영 기준은 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 (영어)