Claude Code 치트시트

/scroll-speed는 마우스 휠 스크롤 속도를 다이얼로그 안에서 실시간 미리보며 조정한다 — 다이얼로그가 열린 상태에서 룰러 영역을 휠로 굴려 변화를 즉시 비교 가능.
휠이 너무 빠르거나 답답할 때 매번 설정 파일 만지지 않고 한 번에 잡는다.
fullscreen 렌더링 전용.

활용

• 다이얼로그 열기:

  /scroll-speed

  복사
• VS Code / Cursor / Windows Terminal에서 휠 가속이 과도할 때 — 한 번 맞추면 영구 저장
• fullscreen이 꺼져 있으면 명령이 노출되지 않으므로 → /tui fullscreen 먼저
• 트랙패드 동작은 별도 — 이 다이얼로그는 휠 한정

주의

• JetBrains IDE 터미널에서는 휠 이벤트가 IDE 쪽에서 처리돼 명령이 뜨지 않음.

/goal로 완료 조건을 걸어 두면 사용자가 매 턴 프롬프트하지 않아도 조건이 충족될 때까지 Claude가 알아서 다음 턴을 시작한다.
매 턴이 끝날 때 빠른 모델(기본 Haiku)이 그동안의 대화만으로 yes/no와 짧은 사유를 반환하고, no면 그 사유가 다음 턴 가이드로 넘어간다.
조건 충족 시 자동 해제.

활용

• 마이그레이션 완주:

  /goal src/ 전체가 새 API로 옮겨지고 npm test가 통과

  복사
• 백로그 처리 (턴 상한 포함):

  /goal P2 라벨 이슈를 우선순위 순으로 처리, 큐가 비면 종료. 최대 20턴.

  복사
• 비대화형 한 번에 돌리기 → claude -p "/goal CHANGELOG.md에 이번 주 머지된 PR 항목 추가" — Ctrl+C로 중단
• 현재 상태 확인 → 인자 없이 /goal (조건·경과·턴·토큰·평가자 사유)
• 조기 종료 → /goal clear (별칭 stop, off, reset, none, cancel)

주의

• 평가자는 도구를 실행하지 않으니 Claude 출력으로 증명 가능한 조건으로 써라 — "npm test exits 0", "git status clean" 식.
• 세션당 활성 1개. 새 /goal은 이전 목표 대체.
• disableAllHooks나 allowManagedHooksOnly에서는 사용 불가 — 평가자가 hooks 시스템 위에 돈다.
• --resume/--continue로 세션 복귀 시 조건은 살아나지만 턴 카운트·타이머·토큰 baseline은 초기화.

--plugin-dir <경로>는 세션 시작 시 마켓플레이스 없이 로컬 플러그인을 바로 로드하는 CLI 플래그다.
경로로 디렉토리를 지정하거나, v2.1.128부터는 .zip 아카이브를 그대로 넘길 수 있다.
개발 중인 플러그인을 설치 없이 즉시 테스트하거나, .zip으로 묶어 배포할 때 압축 해제 단계 없이 바로 쓸 수 있다.

활용

• 로컬 디렉토리 플러그인 바로 로드 → claude --plugin-dir ./my-plugin
• .zip으로 패키징한 플러그인 로드 (v2.1.128~) → claude --plugin-dir ./plugin-release.zip
• 여러 로컬 플러그인 동시에 → 플래그 반복: claude --plugin-dir ./plugin-a --plugin-dir ./plugin-b
• /plugin Components 패널에서 --plugin-dir 로드 플러그인 확인 → 패널에 별도 항목으로 표시됨

주의

마켓플레이스를 거치지 않으므로 서명 검증·의존성 자동 설치가 없다.
개발·테스트 용도로 쓰고, 의존성이 있는 플러그인은 마켓플레이스 설치를 권장한다.

--plugin-url <url> 플래그를 사용하면 원격 .zip 아카이브에서 플러그인을 받아 현재 세션에만 로드할 수 있다.
로컬에 파일을 설치하지 않고 URL 하나로 플러그인을 공유·배포하거나 임시로 시험할 때 유용하다.

기존 --plugin-dir도 v2.1.128부터 .zip 아카이브를 직접 받아 디렉토리와 동일하게 처리한다 — 압축 해제 없이 zip 파일 경로를 넘기면 된다.

활용

• URL에서 플러그인을 받아 현재 세션에서 실행:

  claude --plugin-url https://example.com/my-plugin.zip

  복사
• 로컬 zip 파일을 --plugin-dir로 직접 로드 (v2.1.128~):

  claude --plugin-dir ./my-plugin.zip

  복사
• 팀 내 플러그인 배포 → 서버에 zip 올리고 URL 공유, 팀원들이 --plugin-url로 즉시 사용
• CI 파이프라인에서 임시 플러그인 로드 → 영구 설치 없이 세션 범위로만 동작

주의

• --plugin-url로 로드한 플러그인은 해당 세션에서만 유효하다. 영구 설치는 /plugin install 명령 사용.
• URL이 접근 가능하고 유효한 .zip 플러그인 아카이브여야 한다.

command hook 항목에 args: string[]을 두면 shell을 거치지 않고 executable을 직접 spawn한다.
배열의 각 원소는 단일 인자로 그대로 전달되니, ${CLAUDE_PROJECT_DIR}처럼 공백을 포함할 수 있는 경로 자리표시자도 따옴표·이스케이프 없이 그냥 쓸 수 있다 — shell 토큰화가 일으키던 잠재적 인젝션·따옴표 누락 버그가 사라진다.

활용

• 플러그인 스크립트를 안전하게 호출:

  {
    "hooks": {
      "PostToolUse": [
        {
          "matcher": "Write|Edit",
          "hooks": [
            {
              "type": "command",
              "command": "node",
              "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/format.js", "--fix"]
            }
          ]
        }
      ]
    }
  }

  복사
• 공백이 있을 수 있는 프로젝트 경로 전달 → "args": ["lint", "${CLAUDE_PROJECT_DIR}"] (shell form이라면 "$CLAUDE_PROJECT_DIR" 따옴표를 직접 챙겨야 함)

주의

• args를 지정한 순간 command는 executable 이름으로 해석된다 — 파이프(|), 리다이렉트(>), $VAR 확장 같은 shell 기능은 동작하지 않음.
• shell 기능이 필요하면 args를 빼고 기존처럼 단일 문자열 command를 쓰거나 명시적 shell 실행으로 감싼다.

hook이 받는 JSON 입력에 effort.level 필드가 추가되고, command hook과 Bash 도구는 같은 값을 $CLAUDE_EFFORT 환경변수로 읽는다.
모델이 요청 effort를 지원하지 못해 다운그레이드된 경우 실제 적용된 레벨이 들어가므로, hook이 "이 턴이 어느 깊이로 돌고 있나"를 정확히 판단해 동작을 분기할 수 있다.
값: low, medium, high, xhigh, max.

활용

• bash 명령에서 effort에 따라 분기:

  if [ "$CLAUDE_EFFORT" = "max" ]; then
    npm test -- --runInBand
  else
    npm test
  fi

  복사
• hook 스크립트가 JSON 입력에서 읽기:

  level=$(jq -r '.effort.level')

  복사
• 로깅 hook에 effort를 같이 기록 → 사후 분석 시 "이 동작이 high에서 났나" 추적 가능

주의

• 값은 실제 적용 레벨 — 사용자가 요청한 레벨과 다를 수 있음.
• effort를 지원하지 않는 provider/모델에서는 값이 비어 있을 수 있으니 [ -z "$CLAUDE_EFFORT" ] 가드 권장.

훅 스크립트와 Bash 도구 서브프로세스에서 현재 노력(effort) 수준을 읽을 수 있다.
훅 JSON 입력의 effort.level 필드와 $CLAUDE_EFFORT 환경변수 두 가지 방법을 모두 제공하므로, 노력 수준에 따라 로그 상세도를 달리하거나 무거운 검증 단계를 선택적으로 실행하는 스크립트를 작성할 수 있다.

활용

• Bash 도구 명령에서 노력 수준 읽기 → 상세 로그 선택 실행:

  if [ "$CLAUDE_EFFORT" = "high" ]; then
    npm run test:full -- --coverage
  else
    npm run test:fast
  fi

  복사
• PreToolUse 훅 스크립트에서 JSON 필드로 읽기:

  #!/usr/bin/env bash
  # hooks/pre-tool-use.sh — effort.level 기반 검증 수위 조절
  EFFORT=$(echo "$HOOK_INPUT" | jq -r '.effort.level')
  if [ "$EFFORT" = "high" ]; then
    # 엄격한 타입 검사 실행
    npx tsc --noEmit
  fi

  복사
• 낮은 effort(low)일 땐 무거운 린트·타입 검사 건너뜀 → high일 때만 전체 CI 파이프라인 사전 실행

주의

• 모든 훅 이벤트(PreToolUse, PostToolUse, SessionStart 등)와 Bash 서브프로세스에서 동일하게 사용 가능.
• effort 수준은 /effort 명령 또는 CLAUDE_CODE_EFFORT_LEVEL 환경변수로 설정한다. 기본값은 normal.

Auto 모드의 autoMode 설정에 hard_deny 키가 추가됐다.
기존 soft_deny와 달리 사용자 의도나 허용 예외(allow exception) 여부와 관계없이 무조건 차단하는 규칙을 지정할 수 있다.
팀·조직 정책으로 특정 명령이나 패턴을 절대 실행하지 않도록 강제해야 할 때 사용한다.

활용

• 프로덕션 배포 명령을 절대 차단 — 사용자 승인도 불가:

  {
    "autoMode": {
      "hard_deny": ["Bash(kubectl apply --namespace=prod *)"]
    }
  }

  복사
• hard_deny + soft_deny 조합으로 규칙 계층화:

  {
    "autoMode": {
      "hard_deny": ["Bash(rm -rf /*)"],
      "soft_deny": ["$defaults", "Bash(git push origin main)"],
      "allow": ["$defaults", "Bash(npm run *)"]
    }
  }

  복사
• 관리형 settings(admin tier)에서 hard_deny를 설정하면 하위 사용자 규칙으로 덮어쓸 수 없다

주의

• soft_deny는 분류기가 "사용자 의도가 명확하다"고 판단하면 통과할 수 있지만, hard_deny는 그런 예외 없이 항상 차단된다.
• 기존 allow 규칙이 있어도 hard_deny가 우선한다.

Bash 도구가 실행하는 서브프로세스 환경에 CLAUDE_CODE_SESSION_ID가 자동으로 추가된다.
값은 훅의 session_id 필드와 동일해, Bash 도구 출력과 훅 로그를 같은 세션 키로 묶어 추적할 수 있다.

별도 상태 파일이나 임시 ID 없이도 스크립트 실행 로그와 훅 감사 로그를 동일 세션으로 연결하는 구조를 만들 수 있다.

활용

• Bash 도구 명령 안에서 세션 ID를 파일 로그에 기록:

  echo "[$CLAUDE_CODE_SESSION_ID] $(date -u +%FT%TZ) build started" >> ~/claude-audit.log

  복사
• 훅 스크립트와 Bash 도구 출력을 같은 세션으로 조인해 감사 로그 구성:

  # PreToolUse 훅: session_id를 파일에 저장
  echo "$HOOK_INPUT" | jq -r '.session_id' > /tmp/current-session-id
  
  # 이후 Bash 도구 실행 중 → $CLAUDE_CODE_SESSION_ID 로 동일 세션 확인

  복사
• CI 환경에서 여러 병렬 세션 실행 시 로그 분리 → 각 Bash 명령이 자기 세션 ID를 포함

주의

• CLAUDE_CODE_SESSION_ID는 Bash 도구 서브프로세스에만 주입된다. 사용자 터미널 셸에서는 사용 불가.
• 훅의 session_id와 동일한 값이므로 별도 파싱 없이 직접 매핑 가능.

claude agents 한 줄로 모든 백그라운드 세션을 한 화면에 모은다 (Research Preview). 세션은 Needs input / Working / Completed 등 상태별로 묶이고, 한 줄 요약은 Haiku급 모델이 최대 15초마다 갱신한다.
터미널을 닫아도 supervisor 프로세스가 세션을 살려 두므로, 버그 픽스·PR 리뷰·플레이키 테스트 조사를 셋 띄워 두고 신경 가는 행에만 들어가면 된다.

활용

• 진입 → claude agents (빈 입력에서 Esc로 빠져나가도 세션은 계속 진행)
• 새 세션 dispatch (agent view 입력란):

  fix the flaky SettingsChangeDetector test

  복사
• 터미널에서 곧장 백그라운드로 → claude --bg "investigate the flaky test" (짧은 ID 출력 후 분리)
• 진행 중인 세션을 백그라운드로 보내기 → /background (별칭 /bg) 또는 빈 입력에서 ←
• 키보드 — Space peek / Enter·→ attach / Ctrl+X 두 번 = 삭제 / Ctrl+S 디렉토리별 그룹 / Ctrl+T 핀 / Ctrl+R 이름 변경
• 모든 단축키 보기 → ?

주의

• 사용량은 세션별 별도 카운트 — 10개를 병렬로 띄우면 쿼터를 약 10배 소비.
• 머신이 sleep/shutdown되면 백그라운드 세션도 멈춤. 깨어난 뒤 claude respawn --all로 일괄 복구.
• 파일 편집은 자동으로 .claude/worktrees/<id>/에 격리되고 세션 삭제 시 worktree도 같이 사라진다 — 머지·푸시 전에 삭제 금지.
• 비활성화: disableAgentView: true 설정 또는 CLAUDE_CODE_DISABLE_AGENT_VIEW 환경변수.