Official Docs Analysis — 9 Reference Pages

세 개의 실행 모드,
아홉 개의 레퍼런스 축

code.claude.com 공식 레퍼런스 전 페이지 — CLI · Commands · Env vars · Tools · Interactive mode · Checkpointing · Hooks · Plugins · Channels — 를 실행 모드 축으로 재구성했다. 첫 발견부터 정정이다: Claude Code의 실행 모드는 2개가 아니라 3개다.

Three Modes
모드는 2개가 아니라 3개다

CLI reference를 정독하면 claude(대화형)와 claude -p(헤드리스) 사이에 네이티브 백그라운드 세션 계층(--bg · claude agents · attach/logs/respawn)이 따로 있다. 하네스들이 nohup·tmux·lock으로 손수 짓는 것의 공식 등가물이며, --bg와 -p는 결합이 금지된 별개 모드다.

9레퍼런스 페이지
3실행 모드
30+hook events
43built-in tools
세 실행 모드 — 전용 플래그와 결합 제약 claude 대화형 세션 · Shift+Tab 권한 사이클 · /rewind 체크포인트 · ! 셸 모드 · Ctrl+B 백그라운딩 · 채널(외부 이벤트 인입) · API 키 사용 전 승인 프롬프트 사람이 상시 조향 claude -p 헤드리스 (단발 프롬프트) · --max-turns / --max-budget-usd · --json-schema · stream-json · --no-session-persistence · Setup hook (--init/--maintenance) · bg 태스크는 종료 시 함께 소멸 스크립트가 소비 (SDK) claude --bg 백그라운드 세션 · claude agents 관제 뷰 · attach / logs / stop / respawn · supervisor가 생명주기 관리 · bypass 설정 재시작에도 지속 · nohup/tmux 수제 루프의 공식판 데몬이 관리 --bg ✕ -p 결합 금지 (v2.1.198+) = 서로 다른 모드라는 공식 선언 종료된 세션을 -p로 resume → exit 1 (스크립트가 죽은 런을 성공으로 오독하지 못하게 하는 계약)
세 모드는 전용 플래그 집합이 다르고, --bg와 -p는 결합이 명시적으로 금지된다 — 공식 CLI reference 실측.
CLI Reference · Commands
플래그와 슬래시 명령의 모드 경계

커스텀 명령은 이제 스킬로 통합됐고(한 메시지에 최대 6개 체이닝), 슬래시 명령의 헤드리스 지원은 v2.1.205+에서 "인자 직접 지정 + 픽커 없음" 형태만 열렸다.

축 대화형에서만 헤드리스(-p)에서도
슬래시 명령 픽커·다이얼로그형 전부 — /rewind /resume /diff /plan /permissions /config key=value · /model <인자> · /effort · /mcp(텍스트 요약) · /color · /fast
권한 처리 프롬프트 UI + Shift+Tab 모드 사이클 --permission-prompt-tool(MCP 위임, 30s 대기) 또는 bypass — 블랭킷 우회가 유일한 길이 아니다
상한 없음 (사람이 중단) --max-turns · --max-budget-usd — 프로세스 내부 상한 공식 지원
세션 영속 항상 저장 + 체크포인트 동반 --no-session-persistence로 무흔적 실행 선택 가능
구조화 출력 — --json-schema · --output-format stream-json · --include-hook-events
공식 권장이 답이었던 것

--exclude-dynamic-system-prompt-sections는 문서에 "-p 스크립트·멀티유저 워크로드에 권장"으로 명시돼 있다. 이 세션에서 실측된 스폰 실패("Prompt is too long" — 대형 동적 주입 상속)의 공식 완화 수단이 이미 존재했다는 뜻이다.

Env Vars · Tools Reference
프로세스 신원, 우선순위, 도구 수명
CLAUDECODE=1

"Claude Code 아래에 있다"

"모든 하위 프로세스에 설정 — IDE 터미널 포함"

  • Bash · 훅 · statusline · stdio MCP 전부에 주입
  • IDE 통합 터미널도 설정함 → 중첩 판별로는 부정확
  • 용도: "지금 Claude Code 환경인가" 감지
CLAUDE_CODE_CHILD_SESSION=1

"Claude Code가 나를 스폰했다"

"중첩 세션의 공식 판별자"

  • Claude Code 자신이 띄운 세션에만 설정 (IDE·MCP 서버 제외)
  • 훅 재귀 가드(fork bomb 방지)의 공식 마커
  • 수제 env 마커·lock 대신 이걸 검사하면 된다
사실 대화형 헤드리스(-p)
API 키 사용 ANTHROPIC_API_KEY 사용 전 1회 승인 프롬프트 무언 사용 — 구독을 조용히 덮어씀
백그라운드 태스크 턴을 넘어 지속 (Ctrl+B·/tasks) 최종 결과 직후 종료 — 데몬을 남길 수 없는 구조
MCP 자동 백그라운딩 미적용 CLAUDE_AUTO_BACKGROUND_TASKS — 비대화형 전용 (v2.1.212+)
env 우선순위 settings env 블록이 셸 env를 덮어씀 · scope 간 managed > local > project > user — 워커가 launchd 최소 env로 떠도 settings env는 동일 적용
도구 권한 (43종) 프롬프트 요구 13종(Bash·Edit·Write·WebFetch·Skill·Workflow 등) — bypass가 제거하는 것은 이 프롬프트 계층뿐, exit-2 훅 게이트는 전 모드 동일
Interactive Mode · Checkpointing
되돌리기의 두 구현

Interactive mode 페이지 전체가 사실상 "사람이 조향하는 표면"의 목록이다 — Shift+Tab, Ctrl+B 백그라운딩, ! 셸 모드, Esc Esc 되감기, /btw, vim 모드. 전부 헤드리스 등가물이 없다. 그리고 Checkpointing의 한계 목록이 두 모드의 "되돌리기" 구현 차이를 정확히 보여준다.

되돌리기(undo)의 두 구현 — 세션 내부 vs 구조 외부 대화형 — 체크포인트 (세션 내부) 사용자 프롬프트마다 자동 체크포인트 최근 100개 유지 · 세션과 함께 30일 보존 /rewind = 코드·대화 개별 복원 + 구간 요약 추적하지 못하는 것 (공식 한계 4) · bash가 바꾼 파일 (rm·mv·cp) · 서브에이전트의 편집 (복원 불가) · 동시 세션·외부 수정 · 심링크·하드링크 경로 (스킵 경고) 헤드리스 워커 — git worktree (구조 외부) 단발 프롬프트 = 체크포인트 사실상 1개 /rewind 할 사람도, 픽커 UI도 없음 되돌리기 = git reset · worktree 폐기 git이 전부 커버 · bash 변경 포함 워킹트리 전체 추적 · 서브에이전트 편집도 diff에 잡힘 · 워크트리 격리 → 동시 세션 간섭 없음 · 폐기(discard) = 브랜치 삭제 한 번 공식 문서도 명시: "체크포인트는 로컬 undo, Git은 영구 히스토리 — 대체가 아니라 보완"
체크포인트가 못 잡는 네 가지(bash·서브에이전트·동시 세션·링크)는 정확히 워커 구조에서 git이 잡는 것들이다.
Hooks Reference · Plugins Reference
이벤트 30여 종, 출처 6곳, 병합 규칙 하나

훅은 user·project·local·managed·플러그인·스킬/에이전트 frontmatter 6개 출처에서 병합(대체 아님)되고, 동일 핸들러는 dedup, 매칭된 훅은 병렬 실행된다. disableAllHooks로도 managed 훅은 못 끈다.

이벤트 공간

30+ 종 (등록은 별개)

세션 생명주기·턴·도구 호출·서브에이전트·압축·MCP·환경 변화·표시까지. Setup은 헤드리스 전용(--init-only, -p+--init/--maintenance) — CI 준비용 이벤트가 따로 있다.

30+
공식 이벤트
16
내 하네스 등록
판정 계약

차단은 exit 2뿐

exit 1은 차단이 아니다(WorktreeCreate만 예외) — 비차단 에러로 계속 진행된다. exit 2의 stderr만 Claude에게 전달. SessionEnd 훅은 1.5초 공유 예산.

2
유일한 차단 코드
1.5s
SessionEnd 예산
서브에이전트

훅은 안까지 따라간다

settings·managed·플러그인 훅이 서브에이전트 안에서도 발화하고 agent_id/agent_type이 입력에 추가된다. agent frontmatter의 Stop은 SubagentStop으로 자동 변환.

6
훅 출처 (병합)
Plugins — 컴포넌트 7종과 신뢰 게이트

플러그인은 skills·agents·hooks·MCP에 더해 LSP 서버·모니터·테마까지 7종을 제공한다. 설치 스코프는 user(~/.claude/settings.json)·project(.claude/settings.json, 커밋 공유)·managed. project 스코프는 신뢰 게이트 뒤에서만 로드되고 코드 실행 컴포넌트는 추가 제한 — "repo 유래 구성은 검증 후 로드"가 설계 원칙이며, enabledPlugins는 한 번 기록되면 업데이트를 넘어 지속된다.

Channels Reference · Verdict
세 번째 통신 계층, 그리고 종합

채널(research preview)은 세션 안으로 이벤트를 밀어 넣는 MCP 서버다 — 단방향(웹훅/알림)·양방향(reply tool)에 더해 permission relay로 도구 승인 프롬프트를 폰으로 중계해 yes <id>/no <id>로 원격 승인까지 한다. 발신자 allowlist 게이팅이 명문 요구사항이다(인젝션 벡터라서).

1
외부 시스템 → 로컬 채널 MCP 서버
CI·모니터링·챗봇이 로컬 포트로 POST 또는 플랫폼 API 폴링
↓
2
발신자 allowlist 게이트 (필수)
message.from.id 기준 — room 기준 금지(그룹에서 우회됨)
↓
3
<channel> 태그로 세션 컨텍스트 인입
stdio 전송 · 권한 프롬프트는 로컬 다이얼로그와 병렬, 먼저 온 답이 적용
Verdict — 하네스에 바로 적용 가능한 공식 대체 6

손수 구현 중인 것들의 네이티브 대체가 문서에 이미 있었다. 블랭킷 bypass → --permission-prompt-tool · 자체 재귀 가드 → CLAUDE_CODE_CHILD_SESSION=1 · 2h 외부 kill → --max-turns/--max-budget-usd · 주입 과중(스폰 실패) → --exclude-dynamic-system-prompt-sections · nohup/tmux 수제 백그라운드 → --bg+claude agents · telegram rc 브릿지 → Channels permission relay(preview, allowlist 제약). 그리고 네 번째 분기: 대화형과 워커는 "되돌리기·조향"을 각각 세션 내부 장치(체크포인트·Shift+Tab·채널)와 세션 외부 장치(worktree·타임아웃·보드)로 푼다.