Claude Code 치트시트

/subtask는 현재 대화 안에서 즉시 하위 작업을 실행하는 명령어다.
v2.1.212부터 /fork가 대화를 백그라운드 세션으로 분기하는 역할을 맡으면서, 기존 /fork의 인라인 서브에이전트 기능이 /subtask로 분리됐다. 현재 대화 컨텍스트를 공유한 채 하위 작업을 완료하고 결과를 바로 돌려받는다.

/fork는 이제 대화 전체를 복사해 claude agents에 새 행으로 추가하고, 원래 대화는 그대로 유지한다.

활용

• 현재 대화 컨텍스트를 공유하며 집중 분석을 위임할 때 → /subtask 이 파일의 SQL 인젝션 위험을 점검해
• 대화를 유지하면서 완전히 독립적인 병렬 작업이 필요할 때 → /fork로 백그라운드 세션 생성

주의

• /subtask는 인라인 실행이므로 결과가 올 때까지 현재 대화는 대기 상태다. 완전히 독립적인 병렬 실행이 필요하면 /fork를 사용한다.

--forward-subagent-text 플래그(또는 CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1 환경변수)를 사용하면 stream-json 출력에 서브에이전트의 텍스트와 사고 과정이 포함된다.
SDK·파이프라인 환경에서 서브에이전트가 무엇을 생각하고 출력했는지 실시간으로 볼 수 있다.

기본적으로 stream-json은 루트 에이전트 출력만 포함하고 서브에이전트 내용은 생략된다.

활용

• CI/CD 파이프라인에서 멀티에이전트 작업의 전체 로그를 수집할 때:

  claude -p "리포를 분석하고 팀원에게 위임해" \
    --forward-subagent-text \
    --output-format stream-json

  복사
• 환경변수로 항상 활성화:

  export CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1

  복사

하나의 메시지가 백그라운드 에이전트를 무한정 생성하는 팬아웃을 막기 위해 동시 실행 서브에이전트 수를 제한한다.
기본값은 20이며, CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS로 조정할 수 있다. 한도에 도달하면 새 생성이 거부된다.

활용

• 대규모 멀티에이전트 파이프라인에서 상한을 늘릴 때:

  CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=50 claude

  복사
• 리소스를 아끼고 싶을 때 → 더 낮은 값으로 제한:

  CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=5 claude

  복사

v2.1.217부터 서브에이전트는 기본적으로 중첩 서브에이전트를 생성하지 않는다.
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH로 허용 깊이를 지정할 수 있으며, 기본값 0은 "서브에이전트가 서브에이전트를 생성할 수 없음"을 의미한다.

활용

• 에이전트가 에이전트를 재귀적으로 위임해야 하는 파이프라인에서 2단계 중첩 허용:

  CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=2 claude

  복사
• 중첩 없이 단순 위임만 허용할 때 → 기본값(0) 유지

주의

• 깊이를 높이면 에이전트 루프나 예상치 못한 비용 폭증이 발생할 수 있다. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS와 함께 설정해 동시 실행 수도 제한한다.

MCP 도구 호출이 2분(기본값) 이상 걸리면 자동으로 백그라운드로 이동해 세션을 계속 사용할 수 있다.
오래 걸리는 MCP 작업 때문에 Claude Code가 멈춰 보이는 문제를 해결한다. CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS로 임계값(밀리초)을 조정하거나 0으로 비활성화할 수 있다.

활용

• 기본 2분보다 빠르게 백그라운드로 전환하고 싶을 때:

  CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=60000 claude  # 1분으로 설정

  복사
• 자동 백그라운드를 끄고 항상 대기할 때 → CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0
• 5분짜리 MCP 작업도 포그라운드 유지하고 싶을 때:

  CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=600000 claude  # 10분으로 설정

  복사

프롬프트 입력창에서 :heart:처럼 이모지 단축코드를 입력하면 ❤️로 변환된다.
단축코드 앞부분만 입력해도(예: :hea) 후보 목록이 나타난다.
별도 키 조합 없이 단축코드만으로 이모지를 삽입할 수 있다.

끄려면 settings에서 emojiCompletionEnabled: false로 설정한다.

활용

• 프롬프트에 이모지를 넣을 때 → :tada: 입력 후 Enter로 🎉 삽입
• 자동완성을 비활성화할 때:

  { "emojiCompletionEnabled": false }

  복사

sandbox.filesystem.disabled: true로 설정하면 파일시스템 격리만 끄고 네트워크 송신 제어는 유지한다.
sandbox.network와 조합하면 네트워크 화이트리스트는 살리면서 파일 접근 제한을 해제하는 하이브리드 샌드박스가 가능하다.

파일시스템 격리가 로컬 빌드 도구·에디터와 충돌할 때 파일 쪽만 풀어주는 용도로 쓴다.

활용

• 파일 접근은 허용하되 외부 네트워크만 차단할 때:

  {
    "sandbox": {
      "filesystem": { "disabled": true },
      "network": { "allowedDomains": ["api.example.com"] }
    }
  }

  복사
• 로컬 파일 빌드 도구와 Claude Code를 함께 실행해야 할 때 → sandbox.filesystem.disabled: true로 파일 충돌 방지

주의

• 파일시스템 격리를 끄면 Claude가 프로젝트 외부 경로에도 쓸 수 있다. deny 권한 규칙으로 민감 경로를 명시적으로 보호한다.

Vim 삽입 모드에서 두 키 조합을 원하는 키에 매핑할 수 있다.
jj를 Escape로 매핑하는 Vim 사용자의 관용적 워크플로우를 Claude Code 프롬프트 입력창에서도 그대로 쓸 수 있다. settings.json의 vimInsertModeRemaps 필드에 정의한다.

활용

• jj를 Escape로 설정해 삽입 모드에서 빠져나오기:

  {
    "vimInsertModeRemaps": {
      "jj": "Escape"
    }
  }

  복사
• jj와 jk를 함께 설정:

  {
    "vimInsertModeRemaps": {
      "jj": "Escape",
      "jk": "Escape"
    }
  }

  복사

주의

• 삽입 모드에서만 적용된다. Vim 모드 자체를 활성화하려면 settings에서 "vimMode": true로 설정해야 한다.

VoiceOver·NVDA 같은 스크린 리더로 Claude Code를 쓰기 위한 모드다.
기본은 꺼져 있고 직접 켠다.
켜면 박스 문자·진행 애니메이션·화면 다시 그리기를 전부 끄고, 라벨이 붙은 평문을 줄 단위로 출력한다.
화살표 키로 고르던 메뉴까지 번호 목록으로 바뀌어, 대화·권한 승인·출력 확인을 처음부터 끝까지 스크린 리더만으로 진행할 수 있다. 메시지마다 you:·claude:·tool: 같은 라벨이 붙어, 스크롤백 검색으로 원하는 턴을 바로 찾는다.
응답 완료·권한 프롬프트·5초 넘게 걸린 툴 종료 때는 터미널 벨이 울린다.

활용

• 한 세션만 켜기 → claude --ax-screen-reader
• 지금 쉘에서 시작하는 세션 전부 → export CLAUDE_AX_SCREEN_READER=1 (PowerShell은 $env:CLAUDE_AX_SCREEN_READER = "1")
• 이 머신의 모든 세션에 적용 (VS Code 통합 터미널 포함) → 사용자 설정 파일 ~/.claude/settings.json에:

  {
    "axScreenReader": true
  }

  복사
• 설정으로 켜둔 머신에서 이 세션만 끄기 → CLAUDE_AX_SCREEN_READER=0 — 우선순위는 플래그 > 환경변수 > 설정 순
• 권한 프롬프트 같은 메뉴 → 번호 목록으로 출력된다. 번호를 입력하고 Enter로 선택. 예/아니오 질문은 y 또는 n 입력
• 스크린 리더 없이 화면 확대기·모션 축소만 필요할 때 → CLAUDE_CODE_ACCESSIBILITY=1(터미널 커서를 유지해 확대기가 따라감), prefersReducedMotion 설정(애니메이션 축소)

주의

• 모드 자체는 (v2.1.181~) — 그 이전 버전은 --ax-screen-reader를 unknown option 오류로 거부한다. 릴리스 노트 공식 발표는 v2.1.208.
• 모드가 켜지면 tui 설정(fullscreen 렌더링)은 무시된다. 단 attach한 백그라운드 세션은 여전히 fullscreen으로 렌더링된다.
• 스크린 리더 실행을 자동으로 감지하지 않는다 — 항상 직접 켜야 한다.
• SSH로 쓸 때는 Claude Code가 실제로 도는 원격 머신 쪽에 환경변수나 설정을 넣는다.
• claude -p(비대화형) 출력은 이 모드와 무관하다 — 원래부터 평문이다.

CLAUDE_CODE_PROCESS_WRAPPER에 실행파일 경로를 지정하면 에이전트 뷰와 백그라운드 서비스가 Claude Code를 자체 생성할 때마다 해당 래퍼를 거친다.
기업 환경에서 보안 정책·감사 로그·인증 계층을 통과해야 하는 런처가 있을 때 모든 하위 프로세스에 일관되게 적용할 수 있다.

활용

• 기업 런처 /usr/local/bin/corp-launcher를 통해 모든 Claude Code 자생성 실행:

  export CLAUDE_CODE_PROCESS_WRAPPER=/usr/local/bin/corp-launcher
  claude

  복사
• 환경변수·인증 토큰을 주입하는 셸 스크립트를 래퍼로 지정해 백그라운드 에이전트에도 자동 전파

주의

• 래퍼는 Claude Code 바이너리와 인수를 그대로 전달해야 한다. 인수를 변경하면 서브에이전트·백그라운드 세션이 예기치 않게 실패할 수 있다.