Claude Code 치트시트

/skill-doctor는 현재 세션의 각 skill이 매 turn의 컨텍스트에서 차지하는 비용과 실제 사용 빈도를 보여준다 (v2.1.261~). 대화형 세션에서는 /plugin 관리자의 Stats 탭을 열고, -p 비대화형 실행에서는 텍스트 보고서를 출력한다.

보고서는 한 번도 호출되지 않은 skill과 최근 쓰지 않은 plugin을 찾아 정리 위치까지 안내한다.
항상 컨텍스트를 차지하지만 쓰이지 않는 항목을 근거 있게 끌 수 있어, 필요한 skill에 쓸 공간을 되찾기 좋다.

활용

• 설치한 skill 중 실제로 안 쓰는 항목 찾기 → 터미널 세션에서 /skill-doctor 실행
• 자동화에서 텍스트 보고서 받기 → 셸에서 claude -p "/skill-doctor" 실행
• 대화형 보고서에서 정리 대상 끄기 → /plugin 관리자의 Stats 탭에서 미사용 항목과 비활성화 위치 확인

주의

• bundled skill과 enterprise skill은 보고서 대상에서 빠진다.
• feature flag 가져오기를 생략한 세션에서는 사용할 수 없다. Remote Control로 연결한 휴대폰·브라우저에서도 보고서를 열 수 없으므로 세션이 실행 중인 머신의 터미널에서 실행한다.

/advisor는 주 모델이 계획을 정하거나 반복 오류를 만났거나 완료를 선언하기 전처럼 중요한 지점에서 두 번째 모델의 조언을 받게 한다.
/advisor, /advisor <model>, /advisor off 텍스트 형식을 Claude Code Desktop·Remote Control·-p/Agent SDK 같은 headless 세션에서도 사용할 수 있다.
(v2.1.260~)

선택한 advisor는 전체 대화와 툴 결과를 읽고, Claude가 필요하다고 판단할 때 호출된다.
주 모델을 매 턴 더 강한 모델로 바꾸지 않고도 결정 지점에만 별도 검토를 붙일 수 있다.

활용

• Claude Code Desktop이나 Remote Control 입력창에서 Opus 조언 켜기 → /advisor opus
• 모델 선택기를 열어 가능한 advisor 고르기 → /advisor
• 현재 설정을 끄고 저장된 기본값도 지우기 → /advisor off
• 세션 시작 때만 advisor를 지정하고 사용자 기본값은 유지하기 → claude --advisor opus

주의

Advisor Tool은 실험적이며 Anthropic API에서만 동작한다.
Bedrock·Claude Platform on AWS·Google Cloud Agent Platform·Foundry에서는 사용할 수 없고, advisor 호출은 선택한 모델의 토큰을 추가로 소비한다.
조직의 availableModels에 없는 모델이나 주 모델보다 덜 강한 모델은 advisor로 적용되지 않는다.

claude -p에 --append-subagent-system-prompt-file <경로>를 붙이면 파일의 내용을 모든 subagent 시스템 프롬프트 끝에 추가한다 (v2.1.261~). 중첩 subagent에도 적용되므로, 명령줄에 담기 어려운 긴 정책·출력 규칙을 한 파일로 전체 위임에 일관되게 전달할 수 있다.

활용

• CI의 모든 subagent에 긴 리뷰 규칙 적용:

  claude -p \
    --append-subagent-system-prompt-file ./subagent-rules.txt \
    "Review this pull request"

  복사
• 짧은 일회성 지침만 전달 → claude -p --append-subagent-system-prompt "Cite file paths" "Review this change"
• 중첩 위임에도 같은 파일 지침 적용 → 최상위 claude -p 호출에 파일 플래그 한 번 지정

주의

• 두 append 플래그는 함께 쓸 수 없다. 파일을 쓰면 --append-subagent-system-prompt는 빼야 한다.
• -p 비대화형 모드에서만 동작하며, 현재 대화를 복사하는 forked subagent에는 적용되지 않는다.

백그라운드 서브에이전트가 Bash·PowerShell을 run_in_background: true로 시작하면 자기 턴이 끝난 뒤에도 프로세스가 계속 돈다.
이전의 1시간 상한도 없어져 명령이 끝나거나 사용자가 중지할 때까지 메인 대화의 백그라운드 명령과 같은 수명 규칙을 따른다.
(v2.1.260~)

명령이 끝나면 서브에이전트가 알림을 받고, 실행 중인 작업은 /tasks에서 확인하거나 중지할 수 있다.
watch build나 개발 서버처럼 한 시간을 넘길 수 있는 프로세스를 별도 재시작 로직 없이 맡길 수 있다.

활용

• 백그라운드 서브에이전트에게 장시간 watch build를 맡기기 → 명령 호출에 run_in_background: true를 사용하고 /tasks에서 상태 확인
• 더 이상 필요 없는 서버나 watcher 중지 → /tasks에서 해당 background task 선택 후 중지
• 서브에이전트 응답과 동시에 프로세스도 끝나야 할 때 → 작업을 foreground subagent가 시작하게 해 final response 시 함께 종료

주의

foreground subagent가 시작한 백그라운드 명령은 그 subagent의 final response와 함께 종료된다.
-p 비대화형 실행에서도 최종 결과가 나온 직후 background task가 종료되므로, 계속 살아 있어야 하는 프로세스는 백그라운드 서브에이전트나 메인 대화에서 시작해야 한다.

CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1은 subagent·agent team teammate·workflow agent가 정의나 spawn 요청에서 지정한 모델 대신 CLAUDE_CODE_SUBAGENT_MODEL을 사용하게 한다 (v2.1.257~). 여러 곳에 흩어진 subagent·team·workflow 모델 지정을 고치지 않고도 한 번에 통일할 수 있다.

활용

• agent 정의의 model: 값과 무관하게 subagent·team·workflow를 Sonnet으로 실행 → 두 환경변수를 셸에서 함께 지정:

  CLAUDE_CODE_SUBAGENT_MODEL=sonnet \
  CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 \
  claude

  복사
• 팀·workflow 정의의 모델도 한꺼번에 덮어쓰기 → 셸에서 haiku를 강제 모델로 지정:

  CLAUDE_CODE_SUBAGENT_MODEL=haiku \
  CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 \
  claude

  복사

주의

CLAUDE_CODE_SUBAGENT_MODEL_FORCE 없이 CLAUDE_CODE_SUBAGENT_MODEL만 설정하면 spawn 요청이나 agent 정의의 model:이 환경변수보다 우선한다.
강제 모드에서도 현재 대화를 복사하는 fork와 model: inherit인 subagent 실행 skill은 메인 대화 모델을 사용한다.

bashOutputMaxChars는 성공한 Bash·PowerShell 명령의 출력을 Claude가 인라인으로 받는 한도를, taskOutputMaxChars는 완료된 백그라운드 태스크를 TaskOutput으로 읽을 때 받는 한도를 정한다 (v2.1.261~). 기본값은 각각 30,000자와 32,000자이며, 두 값 모두 4,000~128,000자 범위로 제한된다.

한도를 넘은 명령 출력은 미리보기와 저장 파일 경로로 바뀌고, 백그라운드 태스크 출력은 가장 최근 부분만 전달된다.
긴 빌드·테스트 로그를 Claude가 별도 파일 읽기 없이 바로 분석하게 해 후속 도구 호출을 줄일 수 있다.

활용

• 전체 테스트 로그가 30,000자를 자주 넘을 때 → settings.json에서 bashOutputMaxChars만 높이기
• 백그라운드 빌드의 마지막 로그가 32,000자를 넘을 때 → taskOutputMaxChars도 함께 높이기:

  {
    "bashOutputMaxChars": 100000,
    "taskOutputMaxChars": 100000
  }

  복사

주의

• 두 설정을 생략하면 기본 한도가 적용된다. 4,000보다 작은 값은 4,000으로, 128,000보다 큰 값은 128,000으로 제한된다.
• bashOutputMaxChars는 성공한 명령의 인라인 한도를 바꾼다. 실패한 명령 출력에는 별도 제한이 적용된다.

permissions.blockReadsOutsideWorkingDirectories를 true로 두면 Read·Grep·Glob·LSP가 세션의 working directory 밖을 읽지 못한다.
인식 가능한 파일 읽기 Bash 명령도 경계 밖 경로에서는 승인을 요구하며, 이 제한은 bypassPermissions를 포함한 모든 permission mode에 적용된다.
(v2.1.257~)

어느 settings scope에서든 한 번 true가 되면 다른 scope의 false로 풀 수 없다.
프로젝트가 홈 디렉토리나 다른 체크아웃의 파일을 뜻하지 않게 읽는 일을 전역 경계 하나로 막을 수 있다. 필요한 외부 경로는 /add-dir로 working directory에 포함하거나 sandbox의 allowRead로 명시한다.

활용

• 모든 세션에서 작업 디렉토리 밖 읽기를 막기 → 사용자 settings.json에 설정:

  {
    "permissions": {
      "blockReadsOutsideWorkingDirectories": true
    }
  }

  복사
• 모노레포 밖 공용 문서만 읽게 하기 → 먼저 /add-dir ../shared-docs로 working directory에 포함
• sandboxed git이 ~/.gitconfig를 읽어야 할 때 → sandbox.filesystem.allowRead에 필요한 경로만 다시 허용

주의

설정을 켜면 ~/.gitconfig 같은 홈 디렉토리 파일도 차단된다.
Claude Code 자체가 로드하는 ~/.claude/ 아래 skills·plugins·rules·agents·commands·CLAUDE.md는 계속 읽을 수 있다.

timeFormat은 turn 종료 시각과 transcript viewer의 타임스탬프를 12-hour·24-hour·24-hour-utc 또는 strftime 패턴으로 표시한다.
timeZone에는 IANA 시간대 이름을 지정한다 (v2.1.257~). 팀이 서로 다른 지역에서 작업해도 같은 형식과 시간대를 기준으로 세션 시각을 읽을 수 있다.

활용

• 로컬에서 24시간제로 바꾸기 → /config의 Time format에서 24-hour 선택
• 프로젝트 구성원이 같은 시간대를 기준으로 보기 → 프로젝트 settings에 형식과 시간대 지정:

  {
    "timeFormat": "24-hour",
    "timeZone": "Asia/Seoul"
  }

  복사
• transcript viewer에 날짜까지 함께 표시하기 → settings 파일에 strftime 패턴 지정:

  {
    "timeFormat": "%Y-%m-%d %H:%M"
  }

  복사

주의

24-hour-utc는 항상 UTC로 표시하므로 timeZone을 무시한다.
/config에서는 미리 정해진 형식만 고를 수 있으며, strftime 패턴과 timeZone은 settings 파일에서 직접 설정한다.
인식하지 못한 시간대 이름은 시스템 시간대로 대체된다.

PreModelSwitch는 사용자가 요청한 모델 전환 전에 실행되어 전환을 차단하거나 확인을 요구할 수 있고, PostModelSwitch는 세션 모델이 바뀐 뒤 실행되어 모델별 지침을 추가한다 (v2.1.251~). matcher는 전환 대상 모델의 canonical name과 비교하며, 두 이벤트를 쓰면 모델 선택 정책과 전환 후 안내를 CLAUDE.md에 흩어 쓰지 않고 훅으로 일관되게 관리할 수 있다.

활용

• 특정 모델로의 수동 전환을 막기 → PreModelSwitch에서 to_model을 검사하고 종료 코드 2로 차단
• 모델이 바뀔 때마다 모델별 지침을 적용하기 → PostModelSwitch에 모델 matcher와 안내를 출력하는 command 훅 설정
• 자동 fallback·resume 복원까지 감시하기 → PostModelSwitch를 사용; PreModelSwitch는 사용자가 요청한 전환에만 실행

{
  "hooks": {
    "PreModelSwitch": [{
      "matcher": "claude-opus-4-6",
      "hooks": [{
        "type": "command",
        "command": "jq -e '.to_model | test(\"opus-4-6\")' >/dev/null && { echo '이 프로젝트에서는 이 모델을 사용할 수 없습니다.' >&2; exit 2; }; exit 0"
      }]
    }],
    "PostModelSwitch": [{
      "matcher": ".*opus.*",
      "hooks": [{
        "type": "command",
        "command": "echo 'Opus 모델 전용 지침을 확인하세요.'"
      }]
    }]
  }
}

주의

PreModelSwitch는 --model 변경, /model과 picker, /config의 Model 설정, fast mode 전환, SDK·Remote Control 요청에 실행된다.
자동 fallback이나 resume 시 모델 복원에는 실행되지 않는다.
PostModelSwitch는 모델이 이미 바뀐 뒤라 전환을 차단할 수 없으며, fallback chain이 한 턴만 모델을 대체하는 경우에는 실행되지 않는다.

상태줄 스크립트의 stdin JSON에 메인 대화의 프롬프트 캐시 통계와 Claude apps gateway의 지출 한도 사용량이 들어온다 (v2.1.251~). prompt_cache로 hit ratio·misses·warm 상태를, rate_limits.spend_limit으로 사용률과 리셋 시각을 읽을 수 있어 긴 세션의 캐시 상태와 조직 지출 한도를 터미널에서 바로 확인할 수 있다.

두 객체는 첫 API 응답 뒤에만 나타나며, spend_limit은 해당 gateway가 지출 한도를 설정한 경우에만 제공된다.
캐시 통계는 메인 대화만 집계하고 subagent 요청은 포함하지 않는다.

prompt_cache.last_miss_cause로 가장 최근 miss의 원인을, prompt_cache.miss_causes로 세션 중 진단된 원인별 횟수를 읽는다 (v2.1.260~). 원인은 tools_changed·system_prompt_changed·ttl_expired_5m·likely_server_side처럼 표시돼 캐시가 깨진 시점뿐 아니라 무엇을 먼저 고칠지도 상태줄에서 바로 판단할 수 있다.

활용

• 캐시가 식었거나 miss가 늘어난 세션을 표시 → echo "$JSON" | jq -r '"cache \(.prompt_cache.hit_ratio // 0) warm=\(.prompt_cache.warm // false)"'
• 최근 miss 원인을 한 줄로 표시 → echo "$JSON" | jq -r '.prompt_cache.last_miss_cause.causes // [] | join(",")'
• 반복되는 원인을 집계해 캐시 설정 점검 → echo "$JSON" | jq -c '.prompt_cache.miss_causes // {}'
• Claude apps gateway의 지출 한도에 가까워질 때 경고 → echo "$JSON" | jq -r '.rate_limits.spend_limit.used_percentage // empty'를 읽어 임계값 비교
• 캐시·지출 데이터가 아직 없을 때 → // empty 또는 기본값으로 조건부 필드를 처리:

  JSON=$(cat)  # Claude Code가 상태줄 스크립트 stdin으로 JSON 주입
  CACHE=$(echo "$JSON" | jq -r '.prompt_cache.hit_ratio // empty')
  SPEND=$(echo "$JSON" | jq -r '.rate_limits.spend_limit.used_percentage // empty')
  printf 'cache=%s spend=%s%%\n' "${CACHE:-n/a}" "${SPEND:-n/a}"

  복사

주의

prompt_cache와 rate_limits는 첫 API 응답 전에는 없을 수 있고, last_miss_cause는 원인을 식별하지 못했을 때 null이다.
spend_limit도 gateway가 제공하는 경우에만 존재하므로 누락 필드를 전제로 처리해야 한다.