Code Mode로 코드에서 도구 호출 실행하기

Code Mode의 작동 방식

const files = await $`rg -l "function retryPolicy" src`.text();
const target = files.trim().split("\n")[0];
await edit(target, "maxAttempts: 3", "maxAttempts: 5");
({ edited: target, tests: $`npm test -- retryPolicy`.nothrow() });

Code Mode를 사용할 때

• 여러 파일에 걸쳐 반복되는 변경
• Claude가 읽기 전에 결과를 필터링해야 하는 검색
• 동시에 실행할 수 있는 여러 독립적인 명령

Code Mode의 제한 사항

• 재개: Code Mode 세션은 터미널에서 Code Mode를 켠 상태로만 재개할 수 있습니다
• 자동 모드: 자동 모드의 분류기는 각 도구 호출이 아니라 코드를 검토합니다
• 장시간 실행되는 코드: 코드를 백그라운드에서 실행할 수 있는 경우를 제외하고, 코드가 끝날 때까지 기다려야 하며 코드는 10분 후 중지됩니다
• 훅: PreToolUse 훅을 실행할 수 없거나 시간 초과되면 도구 호출이 거부될 수 있고, UserPromptSubmit 훅에 의해 코드 출력이 차단될 수 있습니다
• 사용할 수 없는 기능: Remote Control, Claude in Chrome, 컴퓨터 사용을 사용할 수 없습니다
• 세션 이동: 세션을 Desktop 앱으로 옮기거나 백그라운드 세션으로 전환할 수 없으며, /fork로 백그라운드 사본을 시작할 수 없습니다

요구 사항

• 버전: 어느 릴리스 채널이든 Claude Code v2.1.323 이상. 이전 버전은 it isn't open to your account yet 사유 표시 여부와 관계없이 Code Mode 없이 시작됩니다
• 계정: Claude 구독 또는 Console 계정. 게이트웨이, Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform, Microsoft Foundry를 통해서는 Code Mode를 사용할 수 없습니다
• 조직: 조직이 HIPAA 구성과 zero data retention을 모두 사용하지 않아야 합니다
• 모델: Claude Opus 5.5, Sonnet 5.5, Haiku 5.5 또는 Fable 5.2
• 사용 환경: 터미널의 대화형 claude 세션. Code Mode는 -p, Agent SDK, VS Code 패널, Desktop 앱, 클라우드 세션에서는 작동하지 않습니다
• 설치: Claude Code의 네이티브 빌드
• Windows: Git for Windows가 설치되어 있어야 합니다

Code Mode 사용해 보기

CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude

$env:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE = "1"
claude

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
  }
}

Code Mode (experimental) is on · this session can be resumed only with Code Mode on

Read every Markdown file in this project and list the links that point to local files that don't exist.

Code Mode 끄기

조직에서 Code Mode 차단하기

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "0"
  }
}

권한과 장시간 실행되는 코드

권한 검사

• 자동 모드: 분류기는 각 도구 호출이 아니라 각 코드를 실행 전에 검토합니다. 검색 출력에서 가져온 경로처럼 실행 시점에 계산되는 값은 보지 못하므로, 반드시 제어해야 하는 호출에 대해서는 규칙이나 훅을 유지하십시오. 이전 코드가 실행되는 동안 새 코드가 시작되면 확인 요청을 받을 수도 있습니다
• 기타 권한 모드: 코드는 검토 없이 시작되며, 해당 모드에서 확인을 요청했을 각 도구 호출에 대해 확인 요청을 받습니다

장시간 실행되는 코드

• 대기: Claude는 코드가 끝난 후 응답하며, 코드는 권한 프롬프트에서 보낸 시간을 포함해 10분 후 중지됩니다
• 백그라운드: Claude와 계속 대화할 수 있으며, 코드는 최대 2시간 동안 실행될 수 있습니다

• 다른 모드로 전환한 경우: 시작했던 모드로 돌아올 때까지 Shift+Tab을 누릅니다
• 다른 모드로 시작했거나 claude --resume 목록에서 세션을 선택한 경우: 자동 모드를 사용할 수 있다면 종료한 다음, Code Mode를 켠 상태로 claude --continue --permission-mode auto를 실행합니다
• --tools에 도구 이름을 전달한 경우: 해당 플래그 없이 자동 모드로 다시 시작합니다

문제 해결

Code Mode가 시작되지 않음

카운트다운이 있는 권한 프롬프트

Claude Code will automatically block this request in 1:59, to avoid holding up an unattended session

훅에 의해 거부된 도구 호출

• the hook failed: Claude의 코드에서 온 호출에 대해 훅을 시작할 수 없었거나, 훅이 종료(kill)되었거나, 126, 127 또는 128보다 큰 코드로 종료되었거나, HTTP 오류 또는 잘못된 출력을 반환했습니다. 훅을 수정하십시오
• the hook did not finish: Claude의 코드에서 온 호출, 또는 Claude가 세션에서 코드를 실행한 이후의 다른 모든 도구 호출에서 훅이 시간 초과되었습니다. 훅의 timeout을 늘리십시오

훅에 의해 보류된 코드 출력

관련 리소스

• 권한 모드: 자동 모드와 확인을 요청하는 모드 비교
• 훅 레퍼런스: PreToolUse 및 UserPromptSubmit 훅 작성
• 관리형 설정: 조직 전체에 하나의 구성 적용