> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Claude가 한 단계에서 여러 도구 호출을 수행하는 JavaScript를 작성하는 실험적 기능인 Code Mode를 사용해 봅니다.

Code Mode는 Claude가 [도구](https://code.claude.com/docs/ko/tools-reference.md)를 사용하는 방식을 바꿉니다. Code Mode가 없으면 Claude는 Bash, Read, Edit 같은 도구 호출을 직접 요청하고, 다음에 무엇을 할지 결정하기 전에 각 결과를 읽습니다. Code Mode에서는 Claude가 도구 호출을 수행하는 JavaScript 코드를 작성하고, Claude Code가 세션에서 해당 코드를 실행합니다.

> [!NOTE]
>
> Code Mode는 실험적 기능이며 기본적으로 꺼져 있습니다. 어떤 릴리스에서든 변경되거나 제거될 수 있습니다. 피드백을 공유하려면 `/feedback`을 실행하십시오.

## Code Mode의 작동 방식

Code Mode 세션에서도 작업은 프롬프트로 설명하며, Claude는 이를 수행할 JavaScript를 작성합니다. 하나의 코드로 명령을 병렬로 실행하고, 한 결과를 다음 호출에 사용하고, 출력 중 Claude가 읽어야 하는 부분을 반환할 수 있습니다.

예를 들어 재시도 한도를 높여 달라고 요청하면, Claude는 파일을 찾고, 편집하고, 테스트를 실행하기 위해 다음과 같은 코드를 작성할 수 있습니다. 마지막 줄은 파일 경로와 테스트 출력을 Claude에게 반환합니다.

```javascript theme={null}
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() });
```

대화에는 코드가 아니라 편집의 diff 같은 도구 호출이 표시됩니다. 코드를 읽으려면 `Ctrl+O`를 눌러 [트랜스크립트 뷰어](https://code.claude.com/docs/ko/interactive-mode.md#transcript-viewer)를 엽니다. 각 코드는 그곳에 접힌 **Code** 행으로 표시되며, 펼치는 방법에 대한 안내가 함께 나타납니다.

### Code Mode를 사용할 때

서로 관련된 도구 호출이 많이 필요한 작업에서 Code Mode를 사용해 보십시오. 예를 들면 다음과 같습니다.

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

### Code Mode의 제한 사항

Code Mode를 켜기 전에 다음 제한 사항을 수용할 수 있는지 확인하십시오.

* **재개**: Code Mode 세션은 터미널에서 Code Mode를 켠 상태로만 재개할 수 있습니다
* **자동 모드**: 자동 모드의 분류기는 [각 도구 호출이 아니라 코드를 검토합니다](#permission-checks)
* **장시간 실행되는 코드**: [코드를 백그라운드에서 실행할 수 있는](#long-running-code) 경우를 제외하고, 코드가 끝날 때까지 기다려야 하며 코드는 10분 후 중지됩니다
* **훅**: `PreToolUse` 훅을 실행할 수 없거나 시간 초과되면 [도구 호출이 거부](#tool-call-refused-by-a-hook)될 수 있고, `UserPromptSubmit` 훅에 의해 [코드 출력이 차단](#code-output-withheld-by-a-hook)될 수 있습니다
* **사용할 수 없는 기능**: [Remote Control](https://code.claude.com/docs/ko/remote-control.md), [Claude in Chrome](https://code.claude.com/docs/ko/chrome.md), [컴퓨터 사용](https://code.claude.com/docs/ko/computer-use.md)을 사용할 수 없습니다
* **세션 이동**: 세션을 Desktop 앱으로 옮기거나 [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md)으로 전환할 수 없으며, `/fork`로 백그라운드 사본을 시작할 수 없습니다

## 요구 사항

* **버전**: 어느 [릴리스 채널](https://code.claude.com/docs/ko/setup.md#configure-release-channel)이든 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 구성](https://code.claude.com/docs/ko/hipaa-setup.md)과 [zero data retention](https://code.claude.com/docs/ko/zero-data-retention.md)을 모두 사용하지 않아야 합니다
* **모델**: Claude Opus 5.5, Sonnet 5.5, Haiku 5.5 또는 Fable 5.2
* **사용 환경**: 터미널의 대화형 `claude` 세션. Code Mode는 `-p`, Agent SDK, VS Code 패널, Desktop 앱, 클라우드 세션에서는 작동하지 않습니다
* **설치**: Claude Code의 [네이티브 빌드](https://code.claude.com/docs/ko/setup.md)
* **Windows**: [Git for Windows](https://git-scm.com/downloads/win)가 설치되어 있어야 합니다

또한 API 키 헬퍼, 에이전트 팀, OpenTelemetry 내보내기, `DISABLE_TELEMETRY` 같은 일부 설정이 켜져 있으면 Code Mode를 시작할 수 없습니다. 각 항목의 해결 방법은 [Code Mode가 시작되지 않음](#code-mode-doesnt-start)을 참조하십시오.

## Code Mode 사용해 보기

Code Mode를 켜고 Claude에게 작업을 맡긴 다음, Claude가 작성한 코드를 살펴봅니다.

**1. 버전 확인하기**

`claude --version`을 실행합니다. 버전이 v2.1.323보다 이전이면 `claude update`를 실행합니다. `stable` 채널을 사용 중이고 업데이트 후에도 v2.1.323에 도달하지 않으면, `stable`이 따라잡을 때까지 기다리거나 [`latest`로 전환](https://code.claude.com/docs/ko/setup#configure-release-channel)하십시오.

**2. Code Mode를 켜고 Claude Code 시작하기**

[`CLAUDE_CODE_EXPERIMENTAL_CODE_MODE`](https://code.claude.com/docs/ko/env-vars#variables) 환경 변수를 `1`로 설정합니다. Code Mode를 시험해 보려면 셸에서 설정합니다. 모든 새 세션에서 Code Mode를 켜려면 사용자 설정에서 설정합니다.

> [tab] macOS, Linux, WSL
>
> ```bash theme={null}
> CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> $env:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE = "1"
> claude
> ```

> [tab] settings.json
>
> 다음 `env` 블록을 `~/.claude/settings.json`에 저장하고 `claude`를 시작합니다.
>
> ```json theme={null}
> {
>   "env": {
>     "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
>   }
> }
> ```
>
> Claude Code는 [프로젝트의 설정 파일에 있는 이 변수를 무시](https://code.claude.com/docs/ko/settings-reference.md#variables-claude-code-ignores-in-env)하므로, 복제한 저장소가 사용자 대신 Code Mode를 켤 수는 없습니다.

**3. Code Mode 사용 확인하기**

Claude Code는 첫 Code Mode 세션 전에 확인을 요청합니다. **Yes, turn on Code Mode**를 선택합니다. Claude Code가 다시 시작되고 세션 상단 근처에 다음 줄이 표시됩니다.

```text theme={null}
Code Mode (experimental) is on · this session can be resumed only with Code Mode on
```

다른 줄이 표시되거나 아무것도 표시되지 않으면 [Code Mode가 시작되지 않음](#code-mode-doesnt-start)을 참조하십시오.

**4. 도구 호출이 많은 작업을 Claude에게 맡기기**

잘 알고 있는 프로젝트에서 다음과 같은 프롬프트를 보냅니다.

```text theme={null}
Read every Markdown file in this project and list the links that point to local files that don't exist.
```

**5. Claude가 작성한 코드 읽기**

`Ctrl+O`를 누르고 **Code** 행을 펼쳐 도구 호출 뒤에 있는 JavaScript를 확인합니다. 대화로 돌아가려면 `Ctrl+O`를 다시 누릅니다.

> [!WARNING]
>
> 나중에 Code Mode 세션을 재개하려면 `claude --continue` 또는 `claude --resume`을 실행할 때 `CLAUDE_CODE_EXPERIMENTAL_CODE_MODE`를 `1`로 유지하십시오. Code Mode가 꺼져 있으면 Claude Code는 세션 재개를 거부합니다. Code Mode 없이 시작한 세션은 변수가 설정되어 있더라도 Code Mode 없이 재개됩니다.

### Code Mode 끄기

셸과 `~/.claude/settings.json`에서 `CLAUDE_CODE_EXPERIMENTAL_CODE_MODE`를 제거한 다음 새 세션을 시작합니다. 변수를 유지하고 두 위치 중 어느 곳에서든 값을 `0`으로 변경할 수도 있습니다. 한 곳에 `0`이 있으면 다른 곳에 `1`을 설정하더라도 Code Mode는 꺼진 상태로 유지됩니다.

### 조직에서 Code Mode 차단하기

조직의 누구도 Code Mode를 사용할 수 없도록 [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)에 값이 `0`인 `CLAUDE_CODE_EXPERIMENTAL_CODE_MODE`를 추가합니다.

```json theme={null}
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "0"
  }
}
```

Code Mode 세션에 있는 사용자는 Claude Code를 종료하거나 다시 시작할 때까지 해당 세션에 머무릅니다. 그 이후에는 사용자가 Code Mode 없이 시작하며, `0`이 적용되어 있는 동안에는 Code Mode 세션을 재개할 수 없습니다. 관리형 설정에서 사용자에게 Code Mode를 켜 줄 수는 없습니다.

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

권한 모드에 따라 Claude의 코드가 검사되는 방식과, 코드가 실행되는 동안 Claude와 대화할 수 있는지가 결정됩니다.

### 권한 검사

Claude의 코드가 수행하는 각 도구 호출은 `deny` 및 `ask` [권한 규칙](https://code.claude.com/docs/ko/permissions.md)과 [`PreToolUse` 훅](https://code.claude.com/docs/ko/hooks#pretooluse)을 거칩니다. `Bash` 같은 도구에 대한 규칙이나 matcher를 변경할 필요는 없습니다. 규칙과 훅 외에도, 자동 모드에서는 분류기가 코드를 검토하고, 확인을 요청하는 모드에서는 사용자가 프롬프트에 응답합니다.

* **[자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode)**: 분류기는 각 도구 호출이 아니라 각 코드를 실행 전에 검토합니다. 검색 출력에서 가져온 경로처럼 실행 시점에 계산되는 값은 보지 못하므로, 반드시 제어해야 하는 호출에 대해서는 규칙이나 훅을 유지하십시오. [이전 코드가 실행되는 동안 새 코드가 시작되면 확인 요청](#permission-prompt-with-a-countdown)을 받을 수도 있습니다
* **기타 [권한 모드](https://code.claude.com/docs/ko/permission-modes.md)**: 코드는 검토 없이 시작되며, 해당 모드에서 확인을 요청했을 각 도구 호출에 대해 확인 요청을 받습니다

코드 자체를 검사하려면 Claude의 코드를 실행하는 도구인 `REPL`과 일치하는 `PreToolUse` 훅을 작성하고 `tool_input.code`에서 JavaScript를 읽으십시오.

> [!WARNING]
>
> Bash 규칙은 명령 텍스트와 일치시키므로, Code Mode 사용 여부와 관계없이 Claude는 거부된 명령을 [규칙과 일치하지 않는 형태로](https://code.claude.com/docs/ko/permissions.md#bash-rule-limits) 실행할 수 있습니다. 명령 텍스트에 의존하지 않는 제한은 [샌드박싱](https://code.claude.com/docs/ko/sandboxing.md)을 참조하십시오.

### 장시간 실행되는 코드

코드가 긴 빌드나 테스트를 실행하는 동안 Claude는 이를 기다리거나 백그라운드에서 계속 실행되도록 합니다.

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

백그라운드 코드를 사용하려면 자동 모드 또는 `bypassPermissions` 모드로 세션을 시작하십시오. 그래도 Claude가 기다린다면 현재 모드와 세션을 시작한 방법을 확인하십시오.

* **다른 모드로 전환한 경우**: 시작했던 모드로 돌아올 때까지 `Shift+Tab`을 누릅니다
* **다른 모드로 시작했거나 `claude --resume` 목록에서 세션을 선택한 경우**: [자동 모드를 사용할 수 있다면](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode) 종료한 다음, Code Mode를 켠 상태로 `claude --continue --permission-mode auto`를 실행합니다
* **`--tools`에 도구 이름을 전달한 경우**: 해당 플래그 없이 자동 모드로 다시 시작합니다

## 문제 해결

### Code Mode가 시작되지 않음

세션 상단 근처에 `Code Mode (experimental) isn't available`이 표시되면 Claude Code가 Code Mode 없이 시작되었다는 의미입니다. 사유는 같은 줄에 이어서 표시되며, `/status`에도 표시됩니다. 다음 표에서 사유를 찾아 변경한 다음 새 세션을 시작하십시오. 표에 없는 사유라면 [요구 사항](#requirements)을 확인하십시오.

| 사유에 포함된 내용 | 해결 방법 |
| :- | :- |
| `it isn't open to your account yet` | 버전이 v2.1.323보다 이전이면 [업데이트](#try-code-mode)합니다. 그렇지 않으면 네트워크 연결을 확인하고 다시 시작합니다. 사유가 계속 표시되면 다른 날 다시 시도하십시오 |
| `it only works with the Anthropic API` | 클라우드 제공업체, 게이트웨이 또는 사용자 지정 `ANTHROPIC_BASE_URL`을 통해 요청을 라우팅하는 설정을 제거합니다 |
| `it doesn't work with an API key helper` | `apiKeyHelper`, `ANTHROPIC_AUTH_TOKEN`, 그리고 `ANTHROPIC_CUSTOM_HEADERS`에 있는 모든 `Authorization` 또는 `X-Api-Key` 헤더를 제거합니다. 그런 다음 로그인하거나 `ANTHROPIC_API_KEY`를 설정합니다 |
| `it only works with Opus 5.5, Sonnet 5.5 and later models` | 예를 들어 `--model opus`를 사용해 [지원되는 모델](#requirements)로 시작합니다. Haiku 5.5와 Fable 5.2도 작동합니다 |
| `it doesn't work in background jobs` | `--remote-control` 없이 포그라운드에서 시작합니다 |
| `it needs settings that Claude Code downloads from Anthropic` | `DISABLE_TELEMETRY`처럼 [기능 플래그 가져오기를 끄는](https://code.claude.com/docs/ko/env-vars.md#features-that-need-feature-flag-fetching) 변수를 해제합니다 |
| `OpenTelemetry is on` | [OpenTelemetry 내보내기](https://code.claude.com/docs/ko/monitoring-usage.md) 없이 작업할 수 있다면 `CLAUDE_CODE_ENABLE_TELEMETRY`와 `ENABLE_BETA_TRACING_DETAILED`를 해제합니다 |
| `it doesn't yet work with an installed mod` | 도구 호출을 검사하는 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)를 끕니다 |
| `it can't be used together with agent teams yet` | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`를 해제합니다 |
| `this launch's tool options` | `--restricted` 없이 시작하고, `--tools`에 `REPL`을 추가하고, `--disallowedTools`와 `deny` 규칙에서 `REPL`을 제거합니다 |
| `couldn't save your answer` | `~/.claude.json`을 쓰기 가능하게 만듭니다 |
| `your organization's settings don't allow it` | 관리자에게 [관리형 설정](#block-code-mode-for-your-organization)에 대해 문의합니다 |

Code Mode에 관한 줄이 전혀 표시되지 않으면 `claude --version`을 실행하십시오. 버전이 v2.1.323보다 이전이면 업데이트합니다. 그런 다음 셸 또는 사용자 설정에서 `CLAUDE_CODE_EXPERIMENTAL_CODE_MODE`가 `1`인지 확인하고, 해당 위치와 모든 `--settings` 파일에서 `0`을 제거하십시오.

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

자동 모드에서 이전 코드가 아직 실행 중일 때 Claude가 코드를 추가로 시작하면, 이전 코드는 분류기 검토를 받지 못하게 됩니다. 그러면 Claude Code는 이전 코드의 남은 호출 중 검토가 필요했을 호출에 대해 사용자에게 묻습니다. IDE가 연결되어 있지 않으면 프롬프트에 카운트다운이 표시됩니다.

```text theme={null}
Claude Code will automatically block this request in 1:59, to avoid holding up an unattended session
```

카운트다운이 끝나기 전에 응답하십시오. 그렇지 않으면 해당 호출이 거부되고, 이후 카운트다운이 표시될 호출은 프롬프트 없이 거부됩니다. 프롬프트를 다시 보려면 Claude에게 메시지를 보내십시오.

### 훅에 의해 거부된 도구 호출

Claude가 거부된 도구 호출을 보고하면 오류 텍스트를 요청하십시오. 다음 오류는 `PreToolUse` 훅이 결정을 내리지 않았다는 의미이며, 이 경우 [`onFailure`](https://code.claude.com/docs/ko/hooks#block-the-action-when-a-hook-fails)가 설정되지 않았더라도 호출이 거부됩니다.

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

`command` 또는 `http` 훅이 실패하거나 시간 초과될 때 호출이 진행되도록 하려면 해당 훅에 `"onFailure": "continue"`를 설정하십시오. `command` 훅이 1과 같은 일반 코드로 종료되면, `"onFailure": "block"`을 설정한 경우를 제외하고 호출이 진행됩니다.

### 훅에 의해 보류된 코드 출력

Claude의 코드 출력이 나와야 할 곳에서 Claude가 훅의 차단 사유를 보고하면 [`UserPromptSubmit`](https://code.claude.com/docs/ko/hooks#userpromptsubmit) 훅을 확인하십시오. [코드를 백그라운드에서 실행할 수 있는](#long-running-code) 경우, 해당 이벤트의 `command`, `http`, `mcp_tool` 훅은 코드 출력에 대해서도 실행됩니다. 출력을 통과시키려면 입력의 `source`가 `poll_event`일 때 차단하지 않도록 훅을 변경하십시오.

## 관련 리소스

* [권한 모드](https://code.claude.com/docs/ko/permission-modes.md): 자동 모드와 확인을 요청하는 모드 비교
* [훅 레퍼런스](https://code.claude.com/docs/ko/hooks.md): `PreToolUse` 및 `UserPromptSubmit` 훅 작성
* [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md): 조직 전체에 하나의 구성 적용