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로 적용되지 않는다.

/feedback는 Claude Code 세션에서 발생한 문제를 세션 맥락과 함께 제품 피드백으로 보내는 명령이다.
Claude가 작성해 둔 피드백 초안이 있으면 이 명령으로 초안 목록을 열어 검토하고 전송할 수 있다.
문제 상황을 다시 정리해 복사하지 않고, 필요한 내용만 확인한 뒤 보고할 수 있다. (v2.1.247~)

활용

• Claude가 만든 피드백 초안 검토 → /feedback → 초안 선택 후 내용 확인
• 초안 생성을 끄고 싶을 때 → ~/.claude/settings.json에 {"feedbackDrafts":"off"} 설정

주의

• /feedback는 제품 피드백을 보내는 명령이며, 사용량 확인은 /usage, 설정 진단은 /doctor를 사용한다.

/claude-api cost-optimize는 기존 Claude API 프로젝트의 지출이 어디에서 발생하는지 프로파일링하고, 프롬프트 캐싱·불필요한 입력·출력 토큰·배치·effort·모델 선택 같은 절감 지점을 제안한다.
한 번에 한 가지 변경을 측정하며 진행하므로 감으로 설정을 바꾸지 않고 실제 비용 변화가 확인되는 최적화 순서를 잡을 수 있다. (v2.1.247~)

활용

• 비용이 큰 API 프로젝트의 원인부터 찾기 → 프로젝트에서 /claude-api cost-optimize 실행 후 프로파일 확인
• 절감안을 적용할 때 → 제안된 변경을 한 번에 하나씩 적용하고 비용 변화를 측정

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 파일에서 직접 설정한다.
인식하지 못한 시간대 이름은 시스템 시간대로 대체된다.