Documentation 2026-11-13 23:02 UTC to 2026-11-14 03:01 UTC

14 14 

15## 체크포인팅 작동 방식15## 체크포인팅 작동 방식

16 16 

17파일 체크포인팅을 활성화하면 SDK는 Write, Edit 또는 NotebookEdit 도구를 통해 파일을 수정하기 전에 파일의 백업을 생성합니다. 응답 스트림의 사용자 메시지에는 복원 지점으로 사용할 수 있는 체크포인트 UUID가 포함됩니다.17파일 체크포인트를 활성화하면 SDK는 Write, Edit 또는 NotebookEdit 도구를 통해 파일을 수정하기 전에 파일의 백업을 생성합니다. 턴을 시작하는 각 프롬프트가 체크포인트이며, 해당 사용자 메시지의 UUID가 복원 지점입니다.

18 18 

19> [!NOTE]19> [!NOTE]

20>20>

147 147 

148**2. 체크포인트 UUID 및 세션 ID 캡처**148**2. 체크포인트 UUID 및 세션 ID 캡처**

149 149 

150`replay-user-messages` 옵션이 설정되면, 응답 스트림의 각 사용자 메시지에는 체크포인트로 사용되는 UUID가 있습니다.150`replay-user-messages` 옵션이 설정되면, 턴을 시작하는 각 프롬프트의 사용자 메시지에는 체크포인트로 사용되는 UUID가 있습니다. 도구 결과를 담은 사용자 메시지에도 UUID가 있지만, 이는 체크포인트가 아닙니다.

151 151 

152대부분의 사용 사례에서 첫 번째 사용자 메시지 UUID(`message.uuid`)를 캡처합니다. 이로 되돌리면 추적된 파일이 원본 상태로 복원됩니다. 여러 체크포인트를 저장하고 중간 상태로 되돌리려면 [여러 복원 지점](#multiple-restore-points)을 참조하세요.152대부분의 사용 사례에서 첫 번째 사용자 메시지 UUID(`message.uuid`)를 캡처합니다. 이로 되돌리면 추적된 파일이 원본 상태로 복원됩니다. 여러 체크포인트를 저장하고 중간 상태로 되돌리려면 [여러 복원 지점](#multiple-restore-points)을 참조하세요.

153 153 

171 171 

172### 위험한 작업 전에 체크포인트172### 위험한 작업 전에 체크포인트

173 173 

174이 패턴은 가장 최근의 체크포인트 UUID만 유지하며, 각 에이전트 턴 전에 업데이트합니다. 처리 중에 문제가 발생하면 마지막 안전한 상태로 즉시 되돌리고 루프를 벗어날 수 있습니다.174이 패턴은 가장 최근의 체크포인트 UUID만 유지하며, 턴을 시작하는 각 프롬프트에서 이를 업데이트합니다. 처리 중에 문제가 발생하면 마지막 안전한 상태로 즉시 되돌리고 루프를 벗어날 수 있습니다.

175 175 

176이 예제를 실행하기 전에 `your_revert_condition`(Python) 또는 `yourRevertCondition`(TypeScript)을 오류 감지 또는 유효성 검사 실패와 같은 자신의 확인으로 바꾸십시오. 플레이스홀더는 예제에서 정의되지 않습니다.176이 예제를 실행하기 전에 `your_revert_condition`(Python) 또는 `yourRevertCondition`(TypeScript)을 오류 감지 또는 유효성 검사 실패와 같은 자신의 확인으로 바꾸십시오. 플레이스홀더는 예제에서 정의되지 않습니다.

177 177 

193 await client.query("Refactor the authentication module")193 await client.query("Refactor the authentication module")

194 194 

195 async for message in client.receive_response():195 async for message in client.receive_response():

196 # Update checkpoint before each agent turn starts196 # Update checkpoint at each prompt you send; a tool result isn't one

197 # This overwrites the previous checkpoint. Only keep the latest197 # This overwrites the previous checkpoint. Only keep the latest

198 if isinstance(message, UserMessage) and message.uuid:198 if (

199 isinstance(message, UserMessage)

200 and message.uuid

201 and message.tool_use_result is None

202 and message.parent_tool_use_id is None

203 ):

199 safe_checkpoint = message.uuid204 safe_checkpoint = message.uuid

200 205 

201 # Decide when to revert based on your own logic206 # Decide when to revert based on your own logic

225 let safeCheckpoint: string | undefined;230 let safeCheckpoint: string | undefined;

226 231 

227 for await (const message of response) {232 for await (const message of response) {

228 // Update checkpoint before each agent turn starts233 // Update checkpoint at each prompt you send; a tool result isn't one

229 // This overwrites the previous checkpoint. Only keep the latest234 // This overwrites the previous checkpoint. Only keep the latest

230 if (message.type === "user" && message.uuid) {235 if (message.type === "user" && "isReplay" in message && message.isReplay && message.uuid) {

231 safeCheckpoint = message.uuid;236 safeCheckpoint = message.uuid;

232 }237 }

233 238 

246 251 

247### 여러 복원 지점252### 여러 복원 지점

248 253 

249Claude가 여러 턴에 걸쳐 변경을 수행하는 경우, 맨 처음으로 되돌리기보다는 특정 지점으로 되돌리고 싶을 수 있습니다. 예를 들어, Claude가 첫 번째 턴에서 파일을 리팩토링하고 두 번째 턴에서 테스트를 추가하는 경우, 리팩토링은 유지하되 테스트는 실행 취소하고 싶을 수 있습니다.254Claude가 여러 프롬프트에 걸쳐 변경을 수행하는 경우, 맨 처음으로 되돌리기보다는 특정 지점으로 되돌리고 싶을 수 있습니다. 예를 들어, 첫 번째 프롬프트에서 파일을 리팩토링하고 두 번째 프롬프트에서 테스트를 추가했다면, 두 번째 프롬프트의 체크포인트로 되돌려 리팩토링은 유지하고 테스트는 실행 취소할 수 있습니다.

250 255 

251이 패턴은 모든 체크포인트 UUID를 메타데이터와 함께 배열에 저장합니다. 세션이 완료된 후 이전의 어느 체크포인트로든 되돌릴 수 있습니다:256이 패턴은 각 체크포인트 UUID를 메타데이터와 함께 배열에 저장합니다. 세션이 완료된 후 이전의 어느 체크포인트로든 되돌릴 수 있습니다:

252 257 

253```python Python theme={null}258```python Python theme={null}

254import asyncio259import asyncio

284 await client.query("Refactor the authentication module")289 await client.query("Refactor the authentication module")

285 290 

286 async for message in client.receive_response():291 async for message in client.receive_response():

287 if isinstance(message, UserMessage) and message.uuid:292 if (

293 isinstance(message, UserMessage)

294 and message.uuid

295 and message.tool_use_result is None

296 and message.parent_tool_use_id is None

297 ):

288 checkpoints.append(298 checkpoints.append(

289 Checkpoint(299 Checkpoint(

290 id=message.uuid,300 id=message.uuid,

338 348 

339 try {349 try {

340 for await (const message of response) {350 for await (const message of response) {

341 if (message.type === "user" && message.uuid) {351 if (message.type === "user" && "isReplay" in message && message.isReplay && message.uuid) {

342 checkpoints.push({352 checkpoints.push({

343 id: message.uuid,353 id: message.uuid,

344 description: `After turn ${checkpoints.length + 1}`,354 description: `After turn ${checkpoints.length + 1}`,

638 648 

639* 원본 세션에서 파일 체크포인팅이 활성화되지 않았습니다(`enable_file_checkpointing` 또는 `enableFileCheckpointing`이 `true`로 설정되지 않음)649* 원본 세션에서 파일 체크포인팅이 활성화되지 않았습니다(`enable_file_checkpointing` 또는 `enableFileCheckpointing`이 `true`로 설정되지 않음)

640* 재개 및 되돌리기를 시도하기 전에 세션이 제대로 완료되지 않았습니다650* 재개 및 되돌리기를 시도하기 전에 세션이 제대로 완료되지 않았습니다

651* UUID가 도구 결과를 담고 있는 사용자 메시지에서 가져온 것이며, 이러한 메시지는 체크포인트가 아닙니다

641 652 

642**해결책**: 원본 세션에서 `enable_file_checkpointing=True`(Python) 또는 `enableFileCheckpointing: true`(TypeScript)가 설정되었는지 확인한 다음, 예제에 표시된 패턴을 사용합니다: 첫 번째 사용자 메시지 UUID를 캡처하고, 세션을 완전히 완료한 다음, 빈 프롬프트로 재개하고 `rewindFiles()`를 한 번 호출합니다.653**해결책**: 원본 세션에서 `enable_file_checkpointing=True`(Python) 또는 `enableFileCheckpointing: true`(TypeScript)가 설정되었는지 확인한 다음, 예제에 표시된 패턴을 사용합니다: 첫 번째 사용자 메시지 UUID를 캡처하고, 세션을 완전히 완료한 다음, 빈 프롬프트로 재개하고 `rewindFiles()`를 한 번 호출합니다.

643 654 

496| **지속성** | 프로젝트별 파일 | 파일로 저장 | 세션만 | 세션만 |496| **지속성** | 프로젝트별 파일 | 파일로 저장 | 세션만 | 세션만 |

497| **재사용성** | 프로젝트별 | 프로젝트 전체 | 코드 중복 | 코드 중복 |497| **재사용성** | 프로젝트별 | 프로젝트 전체 | 코드 중복 | 코드 중복 |

498| **관리** | 파일 시스템 | CLI + 파일 | 코드에서 | 코드에서 |498| **관리** | 파일 시스템 | CLI + 파일 | 코드에서 | 코드에서 |

499| **기본 도구** | 유지됨 | 유지됨 | 유지됨 | 손실됨(포함되지 않은 경우) |499| **도구 지침** | 유지됨 | 유지됨 | 유지됨 | 손실됨(포함되지 않은 경우) |

500| **기본 제공 안전** | 유지됨 | 유지됨 | 유지됨 | 추가해야 함 |500| **기본 제공 안전** | 유지됨 | 유지됨 | 유지됨 | 추가해야 함 |

501| **사용자 정의 수준** | 추가만 | 추가, 코딩 지침 생략 가능 | 추가만 | 완전 제어 |501| **사용자 정의 수준** | 추가만 | 추가, 코딩 지침 생략 가능 | 추가만 | 완전 제어 |

502| **버전 제어** | 프로젝트와 함께 | 예 | 코드와 함께 | 코드와 함께 |502| **버전 제어** | 프로젝트와 함께 | 예 | 코드와 함께 | 코드와 함께 |

875| `allowed_tools` | `list[str]` | `[]` | 프롬프트 없이 자동 승인할 도구. 단, [네트워크 경로](https://code.claude.com/docs/ko/permissions.md#network-paths)에서의 읽기는 제외됩니다. 이것은 Claude를 이 도구로만 제한하지 않습니다. [작업 추적 도구](https://code.claude.com/docs/ko/agent-sdk/todo-tracking.md#model-availability) 중 하나를 여기에 지정하면 Claude Code는 해당 세션에서 작업 추적 도구도 활성화합니다. 나열되지 않은 도구는 `permission_mode` 및 `can_use_tool`로 넘어갑니다. `disallowed_tools`를 사용하여 도구를 차단합니다. [권한](https://code.claude.com/docs/ko/agent-sdk/permissions.md#allow-and-deny-rules) 참조 |875| `allowed_tools` | `list[str]` | `[]` | 프롬프트 없이 자동 승인할 도구. 단, [네트워크 경로](https://code.claude.com/docs/ko/permissions.md#network-paths)에서의 읽기는 제외됩니다. 이것은 Claude를 이 도구로만 제한하지 않습니다. [작업 추적 도구](https://code.claude.com/docs/ko/agent-sdk/todo-tracking.md#model-availability) 중 하나를 여기에 지정하면 Claude Code는 해당 세션에서 작업 추적 도구도 활성화합니다. 나열되지 않은 도구는 `permission_mode` 및 `can_use_tool`로 넘어갑니다. `disallowed_tools`를 사용하여 도구를 차단합니다. [권한](https://code.claude.com/docs/ko/agent-sdk/permissions.md#allow-and-deny-rules) 참조 |

876| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptCustom \| SystemPromptFile \| None` | `None` | 시스템 프롬프트 구성. 사용자 정의 프롬프트의 경우 문자열을 전달하거나, Claude Code의 시스템 프롬프트를 위해 선택적 `"append"`와 함께 `{"type": "preset", "preset": "claude_code"}`를 사용하거나, 사용자 정의 프롬프트를 위해 `{"type": "custom", "prompt": "..."}` 형식으로 `"snapshot"`도 설정할 수 있거나, 디스크에서 큰 프롬프트를 로드하기 위해 `{"type": "file", "path": "..."}` 형식을 사용합니다. [`SystemPromptPreset`](#systempromptpreset), [`SystemPromptCustom`](#systempromptcustom) 및 [`SystemPromptFile`](#systempromptfile) 참조 |876| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptCustom \| SystemPromptFile \| None` | `None` | 시스템 프롬프트 구성. 사용자 정의 프롬프트의 경우 문자열을 전달하거나, Claude Code의 시스템 프롬프트를 위해 선택적 `"append"`와 함께 `{"type": "preset", "preset": "claude_code"}`를 사용하거나, 사용자 정의 프롬프트를 위해 `{"type": "custom", "prompt": "..."}` 형식으로 `"snapshot"`도 설정할 수 있거나, 디스크에서 큰 프롬프트를 로드하기 위해 `{"type": "file", "path": "..."}` 형식을 사용합니다. [`SystemPromptPreset`](#systempromptpreset), [`SystemPromptCustom`](#systempromptcustom) 및 [`SystemPromptFile`](#systempromptfile) 참조 |

877| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP 서버 구성 또는 설정 파일 경로 |877| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP 서버 구성 또는 설정 파일 경로 |

878| `strict_mcp_config` | `bool` | `False` | `True`일 때, `mcp_servers`에 전달된 서버만 사용하고 프로젝트 `.mcp.json`, 사용자 설정, 플러그인 제공 MCP 서버 및 [claude.ai 커넥터](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai)를 무시합니다. CLI `--strict-mcp-config` 플래그에 매핑됩니다 |878| `strict_mcp_config` | `bool` | `False` | `True`이면 `mcp_servers`에 전달된 서버를 사용하고 프로젝트 `.mcp.json`, 사용자 설정, 플러그인이 제공하는 MCP 서버, [claude.ai 커넥터](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai)를 무시합니다. CLI `--strict-mcp-config` 플래그에 대응합니다 |

879| `permission_mode` | `PermissionMode \| None` | `None` | 도구 사용을 위한 권한 모드 |879| `permission_mode` | `PermissionMode \| None` | `None` | 도구 사용을 위한 권한 모드 |

880| `continue_conversation` | `bool` | `False` | 가장 최신 대화 계속하기 |880| `continue_conversation` | `bool` | `False` | 가장 최신 대화 계속하기 |

881| `resume` | `str \| None` | `None` | 재개할 세션 ID |881| `resume` | `str \| None` | `None` | 재개할 세션 ID |

340| `Read`, `Edit`, `Glob` | 코드 분석 및 수정 |340| `Read`, `Edit`, `Glob` | 코드 분석 및 수정 |

341| `Read`, `Edit`, `Bash`, `Glob`, `Grep` | 완전 자동화 |341| `Read`, `Edit`, `Bash`, `Glob`, `Grep` | 완전 자동화 |

342 342 

343에이전트의 기본 제공 도구를 이러한 세트 중 하나로 제한하려면 해당 세트를 `tools`로 전달합니다. 대신 `allowedTools`에 세트를 나열하면 [해당 도구를 사전 승인](https://code.claude.com/docs/ko/agent-sdk/custom-tools.md#configure-allowed-tools)하게 되며, 에이전트는 권한 모드에 따라 여전히 다른 도구도 호출할 수 있습니다.

344 

343**권한 모드**는 원하는 인간 감독의 양을 제어합니다. SDK는 활성 모드를 [권한이 평가되는 방식](https://code.claude.com/docs/ko/agent-sdk/permissions.md#how-permissions-are-evaluated)에 설명된 고정된 순서로 허용 및 거부 규칙과 함께 평가합니다. 모드의 전체 목록, 동작 및 각각을 사용할 시기에 대해서는 [에이전트 루프 작동 방식의 권한 모드](https://code.claude.com/docs/ko/agent-sdk/agent-loop.md#permission-mode)를 참조합니다.345**권한 모드**는 원하는 인간 감독의 양을 제어합니다. SDK는 활성 모드를 [권한이 평가되는 방식](https://code.claude.com/docs/ko/agent-sdk/permissions.md#how-permissions-are-evaluated)에 설명된 고정된 순서로 허용 및 거부 규칙과 함께 평가합니다. 모드의 전체 목록, 동작 및 각각을 사용할 시기에 대해서는 [에이전트 루프 작동 방식의 권한 모드](https://code.claude.com/docs/ko/agent-sdk/agent-loop.md#permission-mode)를 참조합니다.

344 346 

345## 다음 단계347## 다음 단계

146| `prompt` | `string` | 예 | 에이전트의 역할과 동작을 정의하는 시스템 프롬프트 |146| `prompt` | `string` | 예 | 에이전트의 역할과 동작을 정의하는 시스템 프롬프트 |

147| `tools` | `string[]` | 아니오 | 허용된 도구 이름의 배열입니다. 생략하면 [서브에이전트에서 사용 가능한 모든 도구](https://code.claude.com/docs/ko/sub-agents.md#available-tools)를 상속합니다 |147| `tools` | `string[]` | 아니오 | 허용된 도구 이름의 배열입니다. 생략하면 [서브에이전트에서 사용 가능한 모든 도구](https://code.claude.com/docs/ko/sub-agents.md#available-tools)를 상속합니다 |

148| `disallowedTools` | `string[]` | 아니오 | 에이전트의 도구 집합에서 제거할 도구 이름의 배열입니다. MCP 서버 수준 패턴도 허용됩니다: `mcp__server` 또는 `mcp__server__*`는 해당 서버의 모든 도구를 제거하고, `mcp__*`는 모든 서버의 모든 MCP 도구를 제거합니다 |148| `disallowedTools` | `string[]` | 아니오 | 에이전트의 도구 집합에서 제거할 도구 이름의 배열입니다. MCP 서버 수준 패턴도 허용됩니다: `mcp__server` 또는 `mcp__server__*`는 해당 서버의 모든 도구를 제거하고, `mcp__*`는 모든 서버의 모든 MCP 도구를 제거합니다 |

149| `model` | `string` | 아니오 | 이 에이전트의 모델 재정의입니다. `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'` 같은 별칭 또는 전체 모델 ID를 허용합니다. `'inherit'`는 주 모델을 사용합니다. 생략하면 Claude Code는 [서브에이전트 모델 순서](https://code.claude.com/docs/ko/sub-agents.md#choose-a-model)에서 모델을 선택합니다 |149| `model` | `string` | 아니오 | 이 에이전트의 모델 재정의입니다. `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'` 같은 별칭 또는 전체 모델 ID를 허용합니다. `'inherit'`는 이 에이전트를 생성한 에이전트의 모델을 사용합니다. `model`을 생략하면 Claude Code는 [서브에이전트 모델 순서](https://code.claude.com/docs/ko/sub-agents.md#choose-a-model)에서 모델을 선택합니다 |

150| `skills` | `string[]` | 아니오 | 시작 시 에이전트의 컨텍스트에 미리 로드할 스킬 이름 목록입니다. 목록에서 최대 [처음 32개의 고유 이름](https://code.claude.com/docs/ko/sub-agents.md#preload-skills-into-subagents)까지만 미리 로드됩니다. 나열되지 않은 스킬은 Skill 도구를 통해 호출 가능합니다 |150| `skills` | `string[]` | 아니오 | 시작 시 에이전트의 컨텍스트에 미리 로드할 스킬 이름 목록입니다. 목록에서 최대 [처음 32개의 고유 이름](https://code.claude.com/docs/ko/sub-agents.md#preload-skills-into-subagents)까지만 미리 로드됩니다. 나열되지 않은 스킬은 Skill 도구를 통해 호출 가능합니다 |

151| `memory` | `'user' \| 'project' \| 'local'` | 아니오 | 이 에이전트의 메모리 소스 |151| `memory` | `'user' \| 'project' \| 'local'` | 아니오 | 이 에이전트의 메모리 소스 |

152| `mcpServers` | `(string \| object)[]` | 아니오 | 이 에이전트에서 사용 가능한 MCP 서버(이름 또는 인라인 구성으로) |152| `mcpServers` | `(string \| object)[]` | 아니오 | 이 에이전트에서 사용 가능한 MCP 서버(이름 또는 인라인 구성으로) |

589| `skills` | `string[] \| 'all'` | `undefined` | 세션에서 사용할 수 있는 스킬입니다. 발견된 모든 스킬을 활성화하려면 `'all'`을 전달하고, 그렇지 않으면 스킬 이름 목록을 전달하세요. 정확한 이름만 전달하세요. Agent SDK v0.3.221 이상에서는 SDK가 Claude Code 프로세스를 시작하기 전에 잘못된 형식 및 와일드카드 형식의 이름을 오류와 함께 거부합니다. 설정하면 SDK가 Skill 도구를 `allowedTools`에 자동으로 추가합니다. `tools`도 전달하는 경우 해당 목록에 `'Skill'`을 포함하세요. [스킬](https://code.claude.com/docs/ko/agent-sdk/skills.md)을 참조하세요 |589| `skills` | `string[] \| 'all'` | `undefined` | 세션에서 사용할 수 있는 스킬입니다. 발견된 모든 스킬을 활성화하려면 `'all'`을 전달하고, 그렇지 않으면 스킬 이름 목록을 전달하세요. 정확한 이름만 전달하세요. Agent SDK v0.3.221 이상에서는 SDK가 Claude Code 프로세스를 시작하기 전에 잘못된 형식 및 와일드카드 형식의 이름을 오류와 함께 거부합니다. 설정하면 SDK가 Skill 도구를 `allowedTools`에 자동으로 추가합니다. `tools`도 전달하는 경우 해당 목록에 `'Skill'`을 포함하세요. [스킬](https://code.claude.com/docs/ko/agent-sdk/skills.md)을 참조하세요 |

590| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Claude Code 프로세스를 생성하는 사용자 지정 함수입니다. VM, 컨테이너 또는 원격 환경에서 Claude Code를 실행할 때 사용합니다 |590| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Claude Code 프로세스를 생성하는 사용자 지정 함수입니다. VM, 컨테이너 또는 원격 환경에서 Claude Code를 실행할 때 사용합니다 |

591| `stderr` | `(data: string) => void` | `undefined` | stderr 출력용 콜백입니다 |591| `stderr` | `(data: string) => void` | `undefined` | stderr 출력용 콜백입니다 |

592| `strictMcpConfig` | `boolean` | `false` | `mcpServers`로 전달된 서버만 사용하고 프로젝트 `.mcp.json`, 사용자 설정, 플러그인이 제공하는 MCP 서버, [claude.ai 커넥터](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai)를 무시합니다 |592| `strictMcpConfig` | `boolean` | `false` | `mcpServers`로 전달된 서버를 사용하고 프로젝트 `.mcp.json`, 사용자 설정, 플러그인이 제공하는 MCP 서버, [claude.ai 커넥터](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai)를 무시합니다 |

593| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined` (최소 프롬프트) | 시스템 프롬프트 구성입니다. 사용자 지정 프롬프트에는 문자열을 전달하고, Claude Code의 시스템 프롬프트를 사용하려면 `{ type: 'preset', preset: 'claude_code' }`를 전달하세요. [사용자 지정 프롬프트의 정적 부분을 캐시하려면](https://code.claude.com/docs/ko/agent-sdk/modifying-system-prompts.md#cache-the-static-part-of-a-custom-prompt) 정적 부분과 요청별 부분 사이에 내보낸 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 상수를 둔 문자열 배열을 전달하세요. 프리셋 객체 형식을 사용할 때는 `append`를 추가하여 추가 지침으로 확장할 수 있으며, `excludeDynamicSections: true`를 설정하면 세션별 컨텍스트를 첫 번째 사용자 메시지로 옮겨 [머신 간 프롬프트 캐시 재사용을 개선](https://code.claude.com/docs/ko/agent-sdk/modifying-system-prompts.md#improve-prompt-caching-across-users-and-machines)할 수 있습니다. [세션이 첫 요청에서 기록한 프롬프트를 재사용하는](https://code.claude.com/docs/ko/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session) 대신 모든 요청에서 프롬프트를 다시 빌드하려면 `snapshot: false`를 설정하세요. 사용자 지정 프롬프트에 `snapshot`을 설정하려면 `{ type: 'custom', prompt }` 형식을 전달하세요. `{ type: 'custom' }` 형식과 `snapshot` 필드에는 TypeScript Agent SDK v0.3.257 이상이 필요합니다 |593| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined` (최소 프롬프트) | 시스템 프롬프트 구성입니다. 사용자 지정 프롬프트에는 문자열을 전달하고, Claude Code의 시스템 프롬프트를 사용하려면 `{ type: 'preset', preset: 'claude_code' }`를 전달하세요. [사용자 지정 프롬프트의 정적 부분을 캐시하려면](https://code.claude.com/docs/ko/agent-sdk/modifying-system-prompts.md#cache-the-static-part-of-a-custom-prompt) 정적 부분과 요청별 부분 사이에 내보낸 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 상수를 둔 문자열 배열을 전달하세요. 프리셋 객체 형식을 사용할 때는 `append`를 추가하여 추가 지침으로 확장할 수 있으며, `excludeDynamicSections: true`를 설정하면 세션별 컨텍스트를 첫 번째 사용자 메시지로 옮겨 [머신 간 프롬프트 캐시 재사용을 개선](https://code.claude.com/docs/ko/agent-sdk/modifying-system-prompts.md#improve-prompt-caching-across-users-and-machines)할 수 있습니다. [세션이 첫 요청에서 기록한 프롬프트를 재사용하는](https://code.claude.com/docs/ko/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session) 대신 모든 요청에서 프롬프트를 다시 빌드하려면 `snapshot: false`를 설정하세요. 사용자 지정 프롬프트에 `snapshot`을 설정하려면 `{ type: 'custom', prompt }` 형식을 전달하세요. `{ type: 'custom' }` 형식과 `snapshot` 필드에는 TypeScript Agent SDK v0.3.257 이상이 필요합니다 |

594| `taskBudget` | `{ total: number }` | `undefined` | *알파.* 토큰 단위의 API 측 작업 예산입니다. 설정하면 모델에 남은 토큰 예산이 전달되어, 모델이 도구 사용 속도를 조절하고 한도에 도달하기 전에 작업을 마무리할 수 있습니다 |594| `taskBudget` | `{ total: number }` | `undefined` | *알파.* 토큰 단위의 API 측 작업 예산입니다. 설정하면 모델에 남은 토큰 예산이 전달되어, 모델이 도구 사용 속도를 조절하고 한도에 도달하기 전에 작업을 마무리할 수 있습니다 |

595| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 지원되는 모델의 경우 `{ type: 'adaptive' }` | Claude의 사고/추론 동작을 제어합니다. 옵션은 [`ThinkingConfig`](#thinkingconfig)를 참조하세요 |595| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 지원되는 모델의 경우 `{ type: 'adaptive' }` | Claude의 사고/추론 동작을 제어합니다. 옵션은 [`ThinkingConfig`](#thinkingconfig)를 참조하세요 |

1285| `tools` | 아니요 | 허용되는 도구 이름의 배열입니다. 생략하면 [서브에이전트가 사용할 수 있는 모든 도구](https://code.claude.com/docs/ko/sub-agents.md#available-tools)를 상속합니다. 에이전트의 컨텍스트에 스킬을 미리 로드하려면 여기에 `'Skill'`을 나열하지 말고 `skills` 필드를 사용하세요 |1285| `tools` | 아니요 | 허용되는 도구 이름의 배열입니다. 생략하면 [서브에이전트가 사용할 수 있는 모든 도구](https://code.claude.com/docs/ko/sub-agents.md#available-tools)를 상속합니다. 에이전트의 컨텍스트에 스킬을 미리 로드하려면 여기에 `'Skill'`을 나열하지 말고 `skills` 필드를 사용하세요 |

1286| `disallowedTools` | 아니요 | 이 에이전트에 대해 명시적으로 허용하지 않을 도구 이름의 배열입니다. MCP 서버 수준 패턴도 허용됩니다. `mcp__server` 또는 `mcp__server__*`는 해당 서버의 모든 도구를 제거하고, `mcp__*`는 모든 서버의 모든 MCP 도구를 제거합니다 |1286| `disallowedTools` | 아니요 | 이 에이전트에 대해 명시적으로 허용하지 않을 도구 이름의 배열입니다. MCP 서버 수준 패턴도 허용됩니다. `mcp__server` 또는 `mcp__server__*`는 해당 서버의 모든 도구를 제거하고, `mcp__*`는 모든 서버의 모든 MCP 도구를 제거합니다 |

1287| `prompt` | 예 | 에이전트의 시스템 프롬프트입니다 |1287| `prompt` | 예 | 에이전트의 시스템 프롬프트입니다 |

1288| `model` | 아니요 | 이 에이전트의 모델 재정의입니다. `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`와 같은 별칭 또는 전체 모델 ID를 허용합니다. `'inherit'`는 메인 모델을 사용합니다. 생략하면 Claude Code는 [서브에이전트 모델 순서](https://code.claude.com/docs/ko/sub-agents.md#choose-a-model)에 따라 모델을 선택합니다 |1288| `model` | 아니요 | 이 에이전트의 모델 재정의입니다. `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`와 같은 별칭 또는 전체 모델 ID를 허용합니다. `'inherit'`는 이 에이전트를 생성한 에이전트의 모델을 사용합니다. `model`을 생략하면 Claude Code는 [서브에이전트 모델 순서](https://code.claude.com/docs/ko/sub-agents.md#choose-a-model)에 따라 모델을 선택합니다 |

1289| `mcpServers` | 아니요 | 이 에이전트의 MCP 서버 사양입니다 |1289| `mcpServers` | 아니요 | 이 에이전트의 MCP 서버 사양입니다 |

1290| `skills` | 아니요 | 에이전트 컨텍스트에 미리 로드할 스킬 이름의 배열입니다 |1290| `skills` | 아니요 | 에이전트 컨텍스트에 미리 로드할 스킬 이름의 배열입니다 |

1291| `initialPrompt` | 아니요 | 이 에이전트가 메인 스레드 에이전트로 실행될 때 첫 번째 사용자 턴으로 자동 제출됩니다 |1291| `initialPrompt` | 아니요 | 이 에이전트가 메인 스레드 에이전트로 실행될 때 첫 번째 사용자 턴으로 자동 제출됩니다 |

102>102>

103> `tmux`는 특정 운영 체제에서 알려진 제한 사항이 있으며 전통적으로 macOS에서 가장 잘 작동합니다. iTerm2에서 `tmux -CC`를 사용하는 것이 `tmux`로의 권장 진입점입니다.103> `tmux`는 특정 운영 체제에서 알려진 제한 사항이 있으며 전통적으로 macOS에서 가장 잘 작동합니다. iTerm2에서 `tmux -CC`를 사용하는 것이 `tmux`로의 권장 진입점입니다.

104 104 

105기본값은 `"in-process"`입니다. `"auto"`를 설정하여 이미 tmux 세션 내에서 실행 중이거나 터미널이 `it2` CLI가 설치된 iTerm2인 경우 분할 창을 활성화하고, 그렇지 않으면 in-process로 폴백합니다. `"tmux"` 설정은 분할 창 모드를 활성화하고 터미널에 따라 tmux 또는 iTerm2를 사용할지 자동으로 감지합니다.105에이전트 팀을 [활성화](#enable-agent-teams)한 상태에서 다음 단계에 따라 각 팀원에게 자체 창을 제공합니다:

106 106 

107`"iterm2"`를 설정하여 iTerm2 네이티브 분할 창을 명시적으로 사용합니다. 이 모드는 [`it2` CLI](https://github.com/mkusaka/it2)가 필요하며 `it2`가 누락된 경우 설치 명령과 함께 오류를 표시합니다. 터미널이 iTerm2이고 tmux를 폴백으로 사용할 수 있을 때 `"auto"` 또는 `"tmux"` 아래에 `it2`를 설치하거나 tmux로 전환할 것을 제안하는 설정 프롬프트가 나타납니다.107**1. tmux 설치 또는 iTerm2 설정**

108 108 

109기본값을 재정의하려면 `~/.claude/settings.json`에서 [`teammateMode`](https://code.claude.com/docs/ko/settings-reference#teammatemode)를 설정합니다:109분할 창 모드는 [tmux](https://github.com/tmux/tmux/wiki) 또는 [`it2` CLI](https://github.com/mkusaka/it2)가 있는 iTerm2가 필요합니다. Claude Code를 실행할 환경을 설정합니다:

110 

111* **tmux**: 시스템의 패키지 관리자를 통해 설치합니다. 플랫폼별 지침은 [tmux wiki](https://github.com/tmux/tmux/wiki/Installing)를 참조합니다.

112* **iTerm2**: [`it2` CLI](https://github.com/mkusaka/it2)를 설치한 후, **iTerm2 > Settings > General > Magic > Enable Python API**에서 Python API를 활성화합니다.

113 

114**2. 분할 창 켜기**

115 

116[`teammateMode`](https://code.claude.com/docs/ko/settings-reference#teammatemode) 설정을 변경하기 전까지 팀원은 in-process로 실행됩니다.

117 

118`~/.claude/settings.json`에서 `"auto"`로 설정합니다:

110 119 

111```json theme={null}120```json theme={null}

112{121{

114}123}

115```124```

116 125 

126`"auto"`를 사용하면 tmux 또는 iTerm2 내에서 Claude Code를 실행할 때 팀원이 분할 창에서 열리고, 다른 터미널에서는 in-process로 실행됩니다.

127 

128**3. Claude Code 시작 및 팀원 생성**

129 

130tmux 내부 또는 iTerm2에서 `claude`를 실행한 후 Claude에게 팀원 생성을 요청합니다.

131 

132iTerm2에서 `it2`에 대한 설정 프롬프트가 나타나면 **Install it2 now**를 선택하여 iTerm2 창에서 분할 창을 엽니다.

133 

134tmux와 iTerm2 외부에서 Claude Code를 실행하거나 iTerm2 창에서 분할 창이 열리지 않으면 `teammateMode`를 다시 변경합니다:

135 

136* **tmux와 iTerm2 외부**: tmux가 설치되어 있으면 `teammateMode`를 `"tmux"`로 설정합니다. 분할 창은 별도의 tmux 세션에서 열립니다. 이를 보려면 Claude Code 프롬프트의 `View teammates` 줄에서 명령을 복사하여 두 번째 터미널에서 해당 명령을 실행합니다.

137* **iTerm2 창에서 분할 창이 열리지 않는 경우**: `teammateMode`를 `"iterm2"`로 설정하여 iTerm2 자체 분할 창을 사용합니다. 그러면 `it2`가 설정된 iTerm2에서 Claude Code를 실행할 때만 팀원이 시작됩니다.

138 

117단일 세션에 대해 모드를 설정하려면 플래그로 전달합니다:139단일 세션에 대해 모드를 설정하려면 플래그로 전달합니다:

118 140 

119```bash theme={null}141```bash theme={null}

122 144 

123`--teammate-mode` 플래그는 실험적이며 `claude --help`에 나타나지 않습니다.145`--teammate-mode` 플래그는 실험적이며 `claude --help`에 나타나지 않습니다.

124 146 

125분할 창 모드는 [tmux](https://github.com/tmux/tmux/wiki) 또는 [`it2` CLI](https://github.com/mkusaka/it2)가 있는 iTerm2가 필요합니다. 수동으로 설치하려면:

126 

127* **tmux**: 시스템의 패키지 관리자를 통해 설치합니다. 플랫폼별 지침은 [tmux wiki](https://github.com/tmux/tmux/wiki/Installing)를 참조합니다.

128* **iTerm2**: [`it2` CLI](https://github.com/mkusaka/it2)를 설치한 후, **iTerm2 → Settings → General → Magic → Enable Python API**에서 Python API를 활성화합니다.

129 

130### 팀원 및 모델 지정147### 팀원 및 모델 지정

131 148 

132Claude는 작업에 따라 생성할 팀원의 수를 결정하거나, 정확히 원하는 것을 지정할 수 있습니다:149Claude는 작업에 따라 생성할 팀원의 수를 결정하거나, 정확히 원하는 것을 지정할 수 있습니다:

497* **In-process 팀원의 백그라운드 서브에이전트 없음**: in-process 팀원의 자체 서브에이전트는 포그라운드에서 실행됩니다. 팀원의 백그라운드 작업은 리더의 프로세스보다 오래 지속될 수 없기 때문입니다. Claude Code는 팀원이 정의에 `background: true`가 설정된 서브에이전트를 생성할 때 오류를 반환합니다. 팀원의 `run_in_background: true` 요청도 실패하며, 오류가 발생하거나 포그라운드에서 자동으로 실행됩니다. 주 대화에서 시작된 서브에이전트는 [백그라운드 기본값](https://code.claude.com/docs/ko/sub-agents.md#run-subagents-in-foreground-or-background)을 따릅니다.514* **In-process 팀원의 백그라운드 서브에이전트 없음**: in-process 팀원의 자체 서브에이전트는 포그라운드에서 실행됩니다. 팀원의 백그라운드 작업은 리더의 프로세스보다 오래 지속될 수 없기 때문입니다. Claude Code는 팀원이 정의에 `background: true`가 설정된 서브에이전트를 생성할 때 오류를 반환합니다. 팀원의 `run_in_background: true` 요청도 실패하며, 오류가 발생하거나 포그라운드에서 자동으로 실행됩니다. 주 대화에서 시작된 서브에이전트는 [백그라운드 기본값](https://code.claude.com/docs/ko/sub-agents.md#run-subagents-in-foreground-or-background)을 따릅니다.

498* **리더가 고정됨**: 주 세션은 수명 동안 리더입니다. 팀원을 리더로 승격하거나 리더십을 이전할 수 없습니다.515* **리더가 고정됨**: 주 세션은 수명 동안 리더입니다. 팀원을 리더로 승격하거나 리더십을 이전할 수 없습니다.

499* **생성 시 팀원별 권한 모드 없음**: 팀원들은 [권한](#permissions) 아래에 설명된 권한 모드로 시작합니다.516* **생성 시 팀원별 권한 모드 없음**: 팀원들은 [권한](#permissions) 아래에 설명된 권한 모드로 시작합니다.

500* **분할 창은 tmux 또는 iTerm2 필요**: 기본 in-process 모드는 모든 터미널에서 작동합니다. 분할 창 모드는 VS Code의 통합 터미널, Windows Terminal, Ghostty에서 지원되지 않습니다.517* **분할 창은 tmux 또는 iTerm2 필요**: 기본 in-process 모드는 모든 터미널에서 작동합니다.

501 518 

502## 다음 단계519## 다음 단계

503 520 

144| 모양 | 의미 |144| 모양 | 의미 |

145| :- | :- |145| :- | :- |

146| `✻` 또는 애니메이션 `✽` | 세션 프로세스가 실행 중이거나, 세션이 사용자의 입력을 필요로 함 |146| `✻` 또는 애니메이션 `✽` | 세션 프로세스가 실행 중이거나, 세션이 사용자의 입력을 필요로 함 |

147| `∙` | 프로세스가 종료됨. 여전히 행을 엿볼 수 있으며, 답변하거나 연결하면 Claude가 저장된 대화에서 프로세스를 다시 시작 |147| `∙` | 프로세스가 종료됨. 여전히 행을 엿볼 수 있으며, 답변하거나 `Enter`를 누르면 Claude가 저장된 대화에서 프로세스를 다시 시작 |

148| `✢` | [`/loop`](https://code.claude.com/docs/ko/scheduled-tasks) 세션이 반복 사이에 절전 중. 행은 실행 횟수와 카운트다운을 표시 |148| `✢` | [`/loop`](https://code.claude.com/docs/ko/scheduled-tasks) 세션이 반복 사이에 절전 중. 행은 실행 횟수와 카운트다운을 표시 |

149 149 

150행의 오른쪽 가장자리에 나타날 수 있는 `#N` 또는 `!N` 레이블은 세션의 [풀 리퀘스트 또는 병합 요청](#pull-request-status)에 대한 링크이며, 상태 아이콘의 일부가 아닙니다.150행의 오른쪽 가장자리에 나타날 수 있는 `#N` 또는 `!N` 레이블은 세션의 [풀 리퀘스트 또는 병합 요청](#pull-request-status)에 대한 링크이며, 상태 아이콘의 일부가 아닙니다.

316* 그룹 헤더에서 `Enter`를 눌러 축소. 단, [필터](#filter-sessions)가 활성화된 동안에는 모든 그룹이 펼쳐진 상태로 유지됩니다316* 그룹 헤더에서 `Enter`를 눌러 축소. 단, [필터](#filter-sessions)가 활성화된 동안에는 모든 그룹이 펼쳐진 상태로 유지됩니다

317* `Ctrl+X`를 눌러 세션을 중지하고 2초 이내에 `Ctrl+X`를 다시 눌러 목록에서 삭제하거나, `Esc`를 눌러 삭제하지 않고 확인을 닫습니다. 두 번째 누름은 예를 들어 [백그라운드 서비스가 응답하지 않아](#agent-view-says-the-background-service-did-not-respond) 중지 시도가 실패할 때도 세션을 삭제합니다. 이 경우 확인은 2초 더 활성 상태로 유지되고, 삭제는 세션의 프로세스를 직접 종료합니다317* `Ctrl+X`를 눌러 세션을 중지하고 2초 이내에 `Ctrl+X`를 다시 눌러 목록에서 삭제하거나, `Esc`를 눌러 삭제하지 않고 확인을 닫습니다. 두 번째 누름은 예를 들어 [백그라운드 서비스가 응답하지 않아](#agent-view-says-the-background-service-did-not-respond) 중지 시도가 실패할 때도 세션을 삭제합니다. 이 경우 확인은 2초 더 활성 상태로 유지되고, 삭제는 세션의 프로세스를 직접 종료합니다

318 318 

319그룹 헤더에서 `Ctrl+X`를 누르면 확인 후 해당 그룹의 모든 세션이 삭제됩니다. [세션 삭제가 제거하는 것](#what-deleting-a-session-removes)에서 다루는 유지되는 경우를 제외하고, 삭제하면 세션이 목록에서 제거됩니다. Claude가 세션을 위해 생성한 worktree는 삭제 방법과 worktree가 보유한 내용에 따라 제거, 유지 또는 제자리에 남겨집니다. 대화 트랜스크립트는 로컬 머신에 남아 있으며 `claude --resume`을 통해 사용할 수 있습니다.319그룹 헤더에서 `Ctrl+X`를 누르면 확인 후 해당 그룹의 모든 세션이 삭제됩니다. 단, Claude Code가 [삭제를 거부하는](#delete-a-session-after-claude-code-refuses) 세션은 제외됩니다. 각 세션의 워크트리가 어떻게 되는지는 [세션 삭제가 제거하는 것](#what-deleting-a-session-removes)을 참조하세요. 대화 트랜스크립트는 로컬 머신에 남아 있으며 `claude --resume`을 통해 사용할 수 있습니다.

320 320 

321화면에 맞지 않는 완료된 세션은 `… N more` 행으로 접힙니다. `Completed` 그룹은 라이브 그룹 이후 남은 수직 공간을 채웁니다. 짧은 터미널에서는 헤더가 단일 요약 줄로 압축되므로 작업 중이거나 입력이 필요한 세션이 계속 표시됩니다.321화면에 맞지 않는 완료된 세션은 `… N more` 행으로 접힙니다. `Completed` 그룹은 라이브 그룹 이후 남은 수직 공간을 채웁니다. 짧은 터미널에서는 헤더가 단일 요약 줄로 압축되므로 작업 중이거나 입력이 필요한 세션이 계속 표시됩니다.

322 322 

622 622 

623#### 세션 삭제 시 제거되는 것623#### 세션 삭제 시 제거되는 것

624 624 

625[에이전트 뷰](#organize-the-list)에서 `Ctrl+X`를 두 번 누르거나 [`claude rm`](#manage-sessions-from-the-shell)으로 세션을 삭제합니다. 아래에서 유지되는 경우를 제외하면 세션은 목록에서 사라집니다. 트랜스크립트는 `claude --resume`을 통해 사용할 수 있도록 머신에 남아 있으며, 제거 상태는 감독자가 재시작되어도 유지됩니다.625[에이전트 뷰](#organize-the-list)에서 `Ctrl+X`를 두 번 누르거나 [`claude rm`](#manage-sessions-from-the-shell)으로 세션을 삭제합니다. Claude Code가 [삭제를 거부](#delete-a-session-after-claude-code-refuses)하는 경우를 제외하면 세션은 목록에서 사라집니다. 트랜스크립트는 `claude --resume`을 통해 사용할 수 있도록 머신에 남아 있습니다.

626 626 

627Claude가 세션을 위해 생성한 워크트리는 다음과 같이 처리됩니다:627Claude가 세션을 위해 생성한 워크트리는 다음과 같이 처리됩니다:

628 628 

629* 에이전트 뷰는 커밋되지 않은 변경 사항을 포함하여 워크트리를 제거하므로, 유지하려는 내용은 먼저 커밋합니다.629* 에이전트 뷰는 커밋되지 않은 변경 사항을 포함하여 워크트리를 제거하므로, 유지하려는 내용은 먼저 커밋합니다.

630* `claude rm`은 커밋되지 않은 변경 사항이 있으면 세션 행과 함께 워크트리를 유지합니다.630* `claude rm`은 커밋되지 않은 변경 사항이 있으면 세션 행과 함께 워크트리를 유지합니다.

631* 에이전트 뷰와 `claude rm` 모두 실행 중인 다른 세션이 사용 중이거나 잠근 워크트리는 제거하지 않으며, 다시 삭제해도 달라지지 않습니다. Claude Code는 워크트리와 세션을 유지하고, 유지한 디렉터리와 이유를 알립니다. 에이전트 뷰에서는 세션의 행에 `not removed`가 표시됩니다. 다른 세션을 닫은 다음 다시 삭제합니다.

632* 다른 곳에 저장되었는지 Claude Code가 확인할 수 없는 커밋이 워크트리에 있는 세션을 삭제하면, Claude Code는 워크트리와 세션을 유지하고, 메시지에 워크트리의 브랜치와 푸시되지 않은 커밋 수를 표시합니다. 메시지는 두 가지 방법도 제시합니다. 커밋을 푸시하거나, 다시 삭제하여 커밋을 버리는 것입니다.

633 631 

634 원격에 있는 커밋은 삭제를 막지 않습니다. `origin` 원격의 기본 브랜치의 로컬 복사본에 있는 커밋도 마찬가지이며, 단 해당 브랜치가 워크트리가 아닌 저장소 디렉터리 자체인 메인 체크아웃에 체크아웃되어 있어야 합니다.632Claude Code가 세션 삭제를 거부하는 이유 중 하나는 [워크트리에 푸시되지 않은 커밋](https://code.claude.com/docs/ko/errors.md#worktree-has-commits-that-are-not-pushed-anywhere)이 있는 경우입니다. 해당 커밋을 유지하려면 세션을 삭제하기 전에 푸시합니다.

635 633 

636 이렇게 거부된 후 다음 중에서 선택합니다:634에이전트 뷰를 사용하든 `claude rm`을 사용하든 일부 워크트리는 디스크에 남습니다:

637 635 

638 * 커밋을 유지하려면 푸시하거나 해당 기본 브랜치에 병합한 다음 세션을 다시 삭제합니다.636* 사용자가 직접 워크트리를 생성하고 그 안에서 세션을 시작한 경우, 워크트리는 유지하거나 제거할 수 있도록 디스크에 남습니다.

639 * 커밋을 버리려면 푸시하지 않고 세션을 다시 삭제합니다. 에이전트 뷰에서 해당 행에 `Ctrl+X`를 두 번 누르거나, 거부 메시지에 출력된 `claude rm <id> --discard-unpushed` 명령을 실행합니다. 이렇게 하면 세션과 워크트리, 그리고 워크트리의 브랜치가 제거되며, 푸시되지 않은 커밋과 커밋되지 않은 변경 사항이 모두 버려집니다.637* Claude가 저장소 안에 생성한 워크트리 디렉터리에 더 이상 `.git` 파일이 없으면, 해당 디렉터리는 사용자가 제거할 수 있도록 디스크에 남습니다. 워크트리의 브랜치는 저장소에 남으므로 해당 브랜치의 커밋은 유지됩니다.

640 638 

641 다시 삭제할 때 Claude Code는 거부 시 표시한 것만 버립니다. 그 이후 워크트리에 커밋이 추가되었으면 Claude Code는 다시 유지하고 업데이트된 상태를 표시합니다.639##### Claude Code가 거부한 후 세션 삭제

642 640 

643 완료된 다른 세션의 기록에도 해당 워크트리가 지정되어 있으면, 다시 삭제해도 워크트리가 유지됩니다. 커밋을 푸시한 다음 다시 삭제합니다.641Claude Code가 워크트리 때문에 세션 삭제를 거부하면, 표시되는 메시지를 따릅니다. 메시지에 푸시되지 않은 커밋이 언급되어 있으면 [Worktree has commits that are not pushed anywhere](https://code.claude.com/docs/ko/errors.md#worktree-has-commits-that-are-not-pushed-anywhere)를 참조하세요.

644* 예를 들어 `git worktree prune` 이후처럼 git이 더 이상 인식하지 않는 워크트리는 삭제를 막지 않습니다. Claude Code는 세션을 삭제하고 디렉터리는 디스크에 남겨 둡니다.

645* git이나 [`WorktreeRemove` 훅](https://code.claude.com/docs/ko/hooks#worktreeremove)이 워크트리를 제거하지 못하면, Claude Code는 워크트리와 세션을 유지하고 메시지에 원인을 표시합니다. 훅의 경우 메시지는 `exited 1`처럼 훅이 어떻게 종료되었는지 알리고 stderr의 앞부분을 인용합니다. 메시지는 다음으로 할 수 있는 작업도 알려줍니다:

646 642 

647 * 세션을 다시 삭제하여 어쨌든 디렉터리를 제거합니다. 에이전트 뷰에서 해당 행에 `Ctrl+X`를 두 번 누르거나, `claude rm` 거부 메시지에 출력된 `claude rm <id> --force-remove-worktree <worktree-id>` 명령을 실행합니다. 워크트리의 브랜치는 저장소에 남습니다.643##### `Worktree not removed` 메시지 해결

648 644 

649 Claude Code는 다음을 모두 확인할 수 있을 때만 이 방법을 제시합니다:645`Worktree not removed` 메시지는 Claude Code 또는 [`WorktreeRemove` 훅](https://code.claude.com/docs/ko/hooks#worktreeremove)이 세션의 워크트리 제거를 완료하지 못했음을 의미합니다. 커밋을 푸시하고 유지하려는 파일을 복사해 둔 다음, 메시지를 따릅니다.

650 646 

651 * 디렉터리가 `.claude/worktrees/` 아래에 있는 저장소의 연결된 워크트리 중 하나입니다647##### `files that weren't checked against a repository` 메시지 해결

652 * 워크트리와 체크아웃된 서브모듈 모두 추적 파일에 커밋되지 않은 변경 사항이 없습니다

653 * 다른 세션의 기록에 해당 워크트리가 지정되어 있지 않습니다

654 648 

655 별도의 git 저장소로 대체된 서브모듈 체크아웃처럼 Claude Code가 서브모듈 체크아웃의 상태를 확인할 수 없는 경우에도 이 방법을 제시하지 않습니다.649`claude rm`의 이 메시지는 어떤 git 저장소에도 속하지 않거나 [`WorktreeCreate` 훅](https://code.claude.com/docs/ko/hooks#worktreecreate)이 관리하는 워크트리 디렉터리에 파일이 남아 있음을 의미합니다. 유지하려는 파일을 복사해 둔 다음, 해당하는 경우의 단계를 따릅니다:

656 * 커밋되지 않은 변경 사항을 커밋하거나 스태시하기, 별도의 git 저장소를 워크트리 밖으로 옮기기, 디렉터리를 사용 중인 것을 닫기, 훅 수정하기 등 방해 요인을 해결한 다음 세션을 다시 삭제합니다.

657 * 디렉터리를 직접 제거한 다음 세션을 다시 삭제합니다.

658 650 

659사용자가 직접 생성하고 그 안에서 세션을 시작한 워크트리는 어느 경우든 그대로 남습니다.651| 경우 | 수행할 작업 |

660 652| :- | :- |

661저장소가 삭제되었거나 [`WorktreeCreate` 훅](https://code.claude.com/docs/ko/hooks#worktreecreate)이 디렉터리를 다른 곳에 생성했기 때문에 워크트리 디렉터리가 어떤 git 저장소에도 속하지 않는 세션도 삭제할 수 있습니다. 디렉터리에 파일이 남아 있는 동안에는 다음과 같습니다:653| 디렉터리를 관리하는 `WorktreeCreate` 훅이 없음 | 파일을 버리려면 에이전트 뷰에서 세션의 행에 `Ctrl+X`를 두 번 누릅니다. 또는 디렉터리를 직접 제거한 다음 `claude rm <id>`를 다시 실행합니다 |

662 654| `WorktreeCreate` 훅이 디렉터리를 관리하고, [`WorktreeRemove` 훅](https://code.claude.com/docs/ko/hooks#worktreeremove)이 있음 | 훅으로 디렉터리 제거를 시도하려면 에이전트 뷰에서 세션의 행에 `Ctrl+X`를 두 번 누릅니다. 또는 디렉터리를 직접 제거한 다음 `claude rm <id>`를 다시 실행합니다 |

663* 에이전트 뷰는 파일을 버리기 전에 동일하게 `Ctrl+X`를 두 번 누르도록 요청합니다. 훅으로 생성된 디렉터리의 경우 대신 [`WorktreeRemove` 훅](https://code.claude.com/docs/ko/hooks#worktreeremove)을 실행하며, 훅이 없으면 삭제를 거부하고 세션을 유지합니다.655| `WorktreeCreate` 훅이 디렉터리를 관리하고, `WorktreeRemove` 훅이 없음 | 디렉터리를 직접 제거한 다음 `claude rm <id>`를 다시 실행합니다 |

664* `claude rm`은 세션과 워크트리를 유지하고 이유를 알립니다.

665 

666어느 방법이든 완료된 다른 세션의 기록에 지정된 디렉터리는 유지됩니다.

667 656 

668### 모델, effort, 빠른 모드 설정657### 모델, effort, 빠른 모드 설정

669 658 

774| [`--add-dir <path>`](https://code.claude.com/docs/ko/permissions#additional-directories-grant-file-access-not-configuration) | 추가 디렉터리에 파일 액세스 권한 부여 |763| [`--add-dir <path>`](https://code.claude.com/docs/ko/permissions#additional-directories-grant-file-access-not-configuration) | 추가 디렉터리에 파일 액세스 권한 부여 |

775| [`--plugin-dir <path>`](https://code.claude.com/docs/ko/plugins/create#load-a-directory-or-archive-for-one-session) | 로컬 디렉터리에서 플러그인 로드 |764| [`--plugin-dir <path>`](https://code.claude.com/docs/ko/plugins/create#load-a-directory-or-archive-for-one-session) | 로컬 디렉터리에서 플러그인 로드 |

776| [`--mcp-config <file-or-json>`](https://code.claude.com/docs/ko/mcp) | 설정 파일 또는 JSON 문자열에서 MCP 서버 로드 |765| [`--mcp-config <file-or-json>`](https://code.claude.com/docs/ko/mcp) | 설정 파일 또는 JSON 문자열에서 MCP 서버 로드 |

777| `--strict-mcp-config` | `--mcp-config`의 MCP 서버만 사용하고 다른 MCP 구성은 무시합니다. 관리형 MCP 파일이 있을 때 이 플래그의 동작은 [managed-mcp.json을 통한 배타적 제어](https://code.claude.com/docs/ko/managed-mcp.md#exclusive-control-with-managed-mcp-json)를 참조하세요 |766| `--strict-mcp-config` | `.mcp.json` 등에 구성된 MCP 서버를 건너뛰고 `--mcp-config`로 전달한 MCP 서버를 로드합니다. 관리형 MCP 파일이 있을 때 이 플래그의 동작은 [managed-mcp.json을 통한 배타적 제어](https://code.claude.com/docs/ko/managed-mcp.md#exclusive-control-with-managed-mcp-json)를 참조하세요 |

778 767 

779`--add-dir`, `--plugin-dir`, `--mcp-config`는 값마다 한 번씩 반복합니다. `claude agents`는 `--add-dir a b c`와 같은 공백으로 구분된 형식을 지원하지 않습니다.768`--add-dir`, `--plugin-dir`, `--mcp-config`는 값마다 한 번씩 반복합니다. `claude agents`는 `--add-dir a b c`와 같은 공백으로 구분된 형식을 지원하지 않습니다.

780 769 

802| `claude stop <id>` | 세션 중지. `claude kill`도 허용 |791| `claude stop <id>` | 세션 중지. `claude kill`도 허용 |

803| `claude respawn <id>` | 실행 중이거나 중지된 세션을 다시 시작합니다. 예를 들어 업데이트된 Claude Code 바이너리를 적용하기 위해 사용합니다. 저장된 대화가 있는 세션은 해당 대화를 재개합니다 |792| `claude respawn <id>` | 실행 중이거나 중지된 세션을 다시 시작합니다. 예를 들어 업데이트된 Claude Code 바이너리를 적용하기 위해 사용합니다. 저장된 대화가 있는 세션은 해당 대화를 재개합니다 |

804| `claude respawn --all` | 모든 실행 중인 세션을 다시 시작합니다. 예를 들어 모든 세션을 한 번에 업데이트된 Claude Code 바이너리로 이동하기 위해 |793| `claude respawn --all` | 모든 실행 중인 세션을 다시 시작합니다. 예를 들어 모든 세션을 한 번에 업데이트된 Claude Code 바이너리로 이동하기 위해 |

805| `claude rm <id>` | 세션을 목록에서 제거하고, 안전하게 삭제할 수 있을 때 Claude가 생성한 worktree를 함께 제거합니다. [세션 삭제 시 제거되는 항목](#what-deleting-a-session-removes) 참조. 대화 트랜스크립트는 로컬 머신에 남아 있으며 `claude --resume`을 통해 계속 사용할 수 있습니다 |794| `claude rm <id>` | 세션을 목록에서 제거하고, 안전하게 삭제할 수 있을 때 Claude가 생성한 worktree를 함께 제거합니다. Claude Code가 worktree 때문에 세션 삭제를 거부하는 경우 [Claude Code가 거부한 후 세션 삭제](#delete-a-session-after-claude-code-refuses)를 참조하십시오. 대화 트랜스크립트는 로컬 머신에 남아 있으며 `claude --resume`을 통해 계속 사용할 수 있습니다 |

806| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | 푸시되지 않은 커밋으로 인해 삭제가 거부된 세션을 삭제하고, worktree와 해당 브랜치 및 커밋을 함께 삭제합니다. 거부 시 출력된 정확한 값을 전달합니다. [세션 삭제 시 제거되는 항목](#what-deleting-a-session-removes) 참조. v2.1.260 이상 필요 |795| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | 푸시되지 않은 커밋 때문에 Claude Code가 삭제를 거부한 후, 세션 삭제를 다시 시도하고 해당 worktree를 폐기합니다. 이 명령을 제시하는 `claude rm` 메시지에서 명령을 복사하십시오. [Worktree has commits that are not pushed anywhere](https://code.claude.com/docs/ko/errors.md#worktree-has-commits-that-are-not-pushed-anywhere) 참조. v2.1.260 이상 필요 |

807| `claude rm <id> --force-remove-worktree <worktree-id>` | git 또는 `WorktreeRemove` 훅이 worktree를 제거할 수 없어 삭제가 거부된 세션을 삭제하고, worktree 디렉터리를 어쨌든 삭제하며 해당 브랜치는 저장소에 남겨둡니다. 거부 시 출력된 정확한 값을 전달합니다. [세션 삭제 시 제거되는 항목](#what-deleting-a-session-removes) 참조. v2.1.268 이상 필요 |796| `claude rm <id> --force-remove-worktree <worktree-id>` | Claude Code가 worktree를 제거할 수 없어 삭제를 거부한 후, 세션 삭제를 다시 시도하고 worktree 디렉터리를 어쨌든 제거합니다. 이 명령을 제시하는 `claude rm` 메시지에서 명령을 복사하십시오. [`Worktree not removed` 메시지 해결](#resolve-a-worktree-not-removed-message) 참조. v2.1.268 이상 필요 |

808| `claude daemon status` | [감독자](#the-supervisor-process)의 상태, 버전, 소켓 디렉터리 및 워커 수 인쇄 |797| `claude daemon status` | [감독자](#the-supervisor-process)의 상태, 버전, 소켓 디렉터리 및 워커 수 인쇄 |

809| `claude daemon logs` | 감독자의 로그 파일 [`~/.claude/daemon.log`](#where-state-is-stored)를 팔로우하며, `Ctrl+C`를 누를 때까지 새 줄이 도착하는 대로 인쇄 |798| `claude daemon logs` | 감독자의 로그 파일 [`~/.claude/daemon.log`](#where-state-is-stored)를 팔로우하며, `Ctrl+C`를 누를 때까지 새 줄이 도착하는 대로 인쇄 |

810| `claude daemon stop --any` | 감독자 프로세스와 감독자가 호스팅하는 백그라운드 세션을 중지합니다. 백그라운드 세션을 실행 상태로 유지하여 [다음 감독자](#the-supervisor-process)가 다시 연결하도록 하려면 `--keep-workers`를 전달합니다. 다음 `claude agents` 또는 `claude --bg`는 새로운 감독자를 시작합니다 |799| `claude daemon stop --any` | 감독자 프로세스와 감독자가 호스팅하는 백그라운드 세션을 중지합니다. 백그라운드 세션을 실행 상태로 유지하여 [다음 감독자](#the-supervisor-process)가 다시 연결하도록 하려면 `--keep-workers`를 전달합니다. 다음 `claude agents` 또는 `claude --bg`는 새로운 감독자를 시작합니다 |

939 928 

940 행에서 `Enter`를 누르면 바닥글에 `Press enter again to resume this session (it ended while the background service was off), or ctrl+x to remove it.`이 표시됩니다. 같은 행에서 `Enter`를 다시 누르면 저장된 대화를 다시 시작합니다. 답변 또는 `claude attach <id>`는 바닥글 프롬프트 없이 다시 시작합니다.929 행에서 `Enter`를 누르면 바닥글에 `Press enter again to resume this session (it ended while the background service was off), or ctrl+x to remove it.`이 표시됩니다. 같은 행에서 `Enter`를 다시 누르면 저장된 대화를 다시 시작합니다. 답변 또는 `claude attach <id>`는 바닥글 프롬프트 없이 다시 시작합니다.

941 930 

942[트랜스크립트 정리](https://code.claude.com/docs/ko/settings-reference.md#cleanupperioddays)가 중지된 세션의 저장된 대화를 제거한 경우, Claude Code는 행을 열기를 거부합니다: 메시지는 다시 시작할 것이 없음을 나타냅니다. `claude rm <id>`는 행을 삭제합니다. 단, [유지되는 경우](#what-deleting-a-session-removes)에서 설명한 경우는 제외되며, `claude respawn <id>`는 원래 프롬프트를 다시 실행합니다. [이 세션의 저장된 대화는 더 이상 디스크에 없습니다](https://code.claude.com/docs/ko/errors.md#this-sessions-saved-conversation-is-no-longer-on-disk)를 참조합니다.931[트랜스크립트 정리](https://code.claude.com/docs/ko/settings-reference.md#cleanupperioddays)가 중지된 세션의 저장된 대화를 제거한 경우, Claude Code는 행을 열기를 거부합니다: 메시지는 다시 시작할 것이 없음을 나타냅니다. `claude rm <id>`는 행을 삭제하며([Claude Code가 거부하는 경우](#what-deleting-a-session-removes)는 제외), `claude respawn <id>`는 원래 프롬프트를 다시 실행합니다. [이 세션의 저장된 대화는 더 이상 디스크에 없습니다](https://code.claude.com/docs/ko/errors.md#this-sessions-saved-conversation-is-no-longer-on-disk)를 참조합니다.

943 932 

944절전 상태만으로는 세션이 중지되지 않습니다. 세션은 절전 상태에서 보존되며 감독자는 깨어날 때 이들에 다시 연결됩니다.933절전 상태만으로는 세션이 중지되지 않습니다. 세션은 절전 상태에서 보존되며 감독자는 깨어날 때 이들에 다시 연결됩니다.

945 934 

973 962 

974백그라운드 세션의 프로세스가 시작을 완료하기 전에 종료되고 호스트의 메모리가 부족하면, 행의 상태는 종료를 이름 지정하고 `possibly low memory — free some up and retry`를 추가합니다.963백그라운드 세션의 프로세스가 시작을 완료하기 전에 종료되고 호스트의 메모리가 부족하면, 행의 상태는 종료를 이름 지정하고 `possibly low memory — free some up and retry`를 추가합니다.

975 964 

976메모는 가설이지 확인된 원인이 아닙니다. Claude Code는 프로세스가 오류를 작성하지 않고 신호로 중지되지 않고 자동으로 종료되었으며 호스트가 그 순간 메모리 부족을 보고한 경우에만 추가합니다. 프로세스가 종료되기 전에 오류를 작성한 경우, 행은 대신 해당 오류를 표시합니다.965> [!NOTE]

966>

967> 메모는 가설이지 확인된 원인이 아닙니다. Claude Code는 프로세스가 오류를 작성하지 않고 신호로 중지되지도 않은 채 아무 출력 없이 종료되었으며 호스트가 그 순간 메모리 부족을 보고한 경우에만 이 메모를 추가합니다. 프로세스가 종료되기 전에 오류를 작성한 경우, 행은 대신 해당 오류를 표시합니다.

977 968 

978머신의 메모리를 확보한 후 행에 연결하거나 답변하면 감독자가 세션을 위한 새로운 프로세스를 시작합니다. 메모리가 계속 부족하면 감독자는 [유휴 세션을 중지](#the-supervisor-process)하여 자체적으로 리소스를 확보하고, 다른 세션을 중지해도 아무것도 확보되지 않으면 유휴 고정 세션도 중지합니다.969호스트의 메모리를 확보한 후 행에서 `Enter`를 누르고, [바닥글이 요청하면](#opening-a-session-says-it-has-no-saved-transcript) 한 번 더 누릅니다. [감독자](#the-supervisor-process)가 세션을 위한 새로운 프로세스를 시작합니다. 메모리가 계속 부족하면 감독자는 [유휴 세션을 중지](#the-supervisor-process)하여 자체적으로 리소스를 확보하고, 다른 세션을 중지해도 아무것도 확보되지 않으면 유휴 고정 세션도 중지합니다.

979 970 

980### 에이전트 뷰에서 백그라운드 서비스가 응답하지 않음971### 에이전트 뷰에서 백그라운드 서비스가 응답하지 않음

981 972 

1036 1027 

1037### `.claude/worktrees/`가 채워지고 있음1028### `.claude/worktrees/`가 채워지고 있음

1038 1029 

1039에이전트 뷰에서 세션을 삭제하면 Claude가 생성한 워크트리가 제거됩니다. 하지만 [일부 삭제는 워크트리를 유지하거나 디스크에 디렉토리를 남겨두므로](#what-deleting-a-session-removes) 남은 디렉토리가 누적될 수 있습니다. Git이 더 이상 인식하지 않는 디렉토리는 `git worktree list`에 나타나지 않으므로 이들을 직접 제거합니다.1030에이전트 뷰에서 세션을 삭제하면 Claude가 해당 세션을 위해 생성한 워크트리가 제거되지만, [일부 워크트리 디렉토리는 디스크에 남습니다](#what-deleting-a-session-removes). Git이 더 이상 인식하지 않는 디렉토리는 `git worktree list`에 나타나지 않으므로 이들을 직접 제거합니다.

1040 1031 

1041프로젝트 디렉토리에서 `git worktree list`로 남은 항목을 나열하고 각각을 `git worktree remove <path>`로 제거합니다. [워크트리 정리](https://code.claude.com/docs/ko/worktrees.md#clean-up-worktrees)를 참조합니다.1032프로젝트 디렉토리에서 `git worktree list`로 남은 항목을 나열하고 각각을 `git worktree remove <path>`로 제거합니다. Git이 거부하면 [서브에이전트 및 백그라운드 세션 워크트리 정리](https://code.claude.com/docs/ko/worktrees.md#clean-up-subagent-and-background-session-worktrees)를 참조합니다.

1042 1033 

1043## 제한 사항1034## 제한 사항

1044 1035 

1046 1037 

1047* **속도 제한 적용**: 백그라운드 세션은 대화형 세션과 동일하게 구독 사용량을 소모하므로 10개의 에이전트를 병렬로 실행하면 할당량을 약 10배 빠르게 소모합니다.1038* **속도 제한 적용**: 백그라운드 세션은 대화형 세션과 동일하게 구독 사용량을 소모하므로 10개의 에이전트를 병렬로 실행하면 할당량을 약 10배 빠르게 소모합니다.

1048* **세션은 로컬입니다**: 백그라운드 세션은 사용자의 머신에서 실행되며 머신이 절전 모드로 전환되어도 유지되지만 머신이 종료되면 중지됩니다.1039* **세션은 로컬입니다**: 백그라운드 세션은 사용자의 머신에서 실행되며 머신이 절전 모드로 전환되어도 유지되지만 머신이 종료되면 중지됩니다.

1049* **Claude에서 생성한 워크트리는 에이전트 뷰의 세션과 함께 삭제됩니다**: 자체 워크트리에서 파일을 편집한 세션을 삭제하기 전에 변경 사항을 커밋합니다. [일부 삭제는 워크트리를 대신 유지합니다](#what-deleting-a-session-removes).1040* **Claude에서 생성한 워크트리는 에이전트 뷰의 세션과 함께 삭제됩니다**: 자체 워크트리에서 파일을 편집한 세션을 삭제하기 전에 변경 사항을 커밋합니다. [일부 워크트리는 디스크에 남습니다](#what-deleting-a-session-removes).

1050 1041 

1051## 관련 리소스1042## 관련 리소스

1052 1043 

432 432 

433아티팩트가 자동 삭제 전에 유지되는 기간을 설정하려면 [**조직 설정 > 데이터 및 개인정보 보호**](https://claude.ai/admin-settings/data-privacy-controls)로 이동하십시오. 작성자에게만 비공개인 아티팩트와 공유된 아티팩트에 대해 별도의 보존 기간을 설정할 수 있습니다.433아티팩트가 자동 삭제 전에 유지되는 기간을 설정하려면 [**조직 설정 > 데이터 및 개인정보 보호**](https://claude.ai/admin-settings/data-privacy-controls)로 이동하십시오. 작성자에게만 비공개인 아티팩트와 공유된 아티팩트에 대해 별도의 보존 기간을 설정할 수 있습니다.

434 434 

435### 감사 로그 검토435### Compliance API로 아티팩트 활동 감사

436 436 

437아티팩트 게시, 공유 및 삭제는 각각 조직의 감사 로그에 `claude_artifact_*` 이벤트 유형 아래에 나타나며, 이는 claude.ai 대화에서 생성된 아티팩트에 사용되는 동일한 제품군입니다.437Enterprise 플랜에서는 Compliance API의 [Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed)를 쿼리하여 누가 아티팩트를 게시, 공유 또는 삭제했는지 확인할 수 있습니다. 필터링에 사용할 활동 유형을 찾으려면 [Activity Feed 참조](https://platform.claude.com/docs/en/api/compliance/activities/list)에서 `activity_types`를 펼치고 `artifact`가 포함된 이름을 찾으십시오.

438 438 

439### 뷰어 도메인 허용 목록439### 뷰어 도메인 허용 목록

440 440 

163Claude는 대화에서 보내는 각 메시지가 어디로 갈지 결정합니다.163Claude는 대화에서 보내는 각 메시지가 어디로 갈지 결정합니다.

164 164 

165* 빠른 질문은 보통 대화에서 답변을 받습니다.165* 빠른 질문은 보통 대화에서 답변을 받습니다.

166* 새 작업은 새 스레드로 가거나 이미 해당 영역에서 작업 중인 스레드로 가며, Claude가 어느 것인지 알려줍니다. 각 새 스레드는 메시지 아래에 카드로 표시됩니다. 카드는 스레드의 제목과 상태를 보여주는 상자이며, 클릭하여 스레드를 열 수 있습니다.166* 새 작업은 새 스레드로 가거나 이미 해당 영역에서 작업 중인 스레드로 가며, Claude가 어느 것인지 알려줍니다. 각 새 스레드는 대화에 표시되며, 클릭하여 스레드를 열 수 있습니다.

167* 한 메시지에 여러 관련 없는 작업이 있으면 별도의 스레드가 됩니다.167* 한 메시지에 여러 관련 없는 작업이 있으면 별도의 스레드가 됩니다.

168 168 

169Claude가 원하는 것과 다르게 라우팅하면 그렇게 말합니다. [Claude가 프로젝트를 실행하는 방식 조정](#tune-how-claude-runs-a-project)에는 기존 스레드를 후속 작업에 재사용하거나 스레드를 시작하는 대신 제자리에서 답변하도록 하는 등 알려줄 수 있는 사항이 나열되어 있습니다.169Claude가 원하는 것과 다르게 라우팅하면 그렇게 말합니다. [Claude가 프로젝트를 실행하는 방식 조정](#tune-how-claude-runs-a-project)에는 기존 스레드를 후속 작업에 재사용하거나 스레드를 시작하는 대신 제자리에서 답변하도록 하는 등 알려줄 수 있는 사항이 나열되어 있습니다.

170 170 

171스레드의 전체 결과는 스레드에 남아 있으며, 대화에서 카드를 열어 읽습니다. 스레드가 생성한 파일은 프로젝트의 [**라이브러리**](#see-what-needs-you-in-overview)에도 있습니다.171스레드의 전체 결과는 스레드에 남아 있으므로, 스레드를 열어 읽습니다. 스레드가 생성한 파일은 프로젝트의 [**라이브러리**](#see-what-needs-you-in-overview)에도 있습니다.

172 172 

173때로 Claude는 스레드를 시작하는 대신 **제안된 스레드** 목록에서 스레드를 제안합니다. 제안의 화살표를 클릭하여 해당 스레드를 시작합니다. 여러 개가 나열되면, 목록 아래의 버튼이 모두 시작합니다.173때로 Claude는 스레드를 시작하는 대신 **제안된 스레드** 목록에서 스레드를 제안합니다. 제안의 화살표를 클릭하여 해당 스레드를 시작합니다. 여러 개가 나열되면, 목록 아래의 버튼이 모두 시작합니다.

174 174 

180* **풀 요청**: 요청할 때 열고, 버그 수정이나 다른 구체적인 변경을 위해 자체적으로 열 수 있습니다.180* **풀 요청**: 요청할 때 열고, 버그 수정이나 다른 구체적인 변경을 위해 자체적으로 열 수 있습니다.

181* **열린 후**: [자동 수정](https://code.claude.com/docs/ko/claude-code-on-the-web.md#auto-fix-pull-requests)을 켜서 풀 요청을 감시합니다. 다른 클라우드 세션에서 자동 수정이 켜져 있는지 여부와 관계없이 켜져 있습니다. CI가 실패하면 수정을 푸시하고, 검토 의견을 처리하며, 검사가 통과하고 풀 요청이 사용자를 위해 준비되면 스레드에서 회신합니다.181* **열린 후**: [자동 수정](https://code.claude.com/docs/ko/claude-code-on-the-web.md#auto-fix-pull-requests)을 켜서 풀 요청을 감시합니다. 다른 클라우드 세션에서 자동 수정이 켜져 있는지 여부와 관계없이 켜져 있습니다. CI가 실패하면 수정을 푸시하고, 검토 의견을 처리하며, 검사가 통과하고 풀 요청이 사용자를 위해 준비되면 스레드에서 회신합니다.

182 182 

183스레드가 브랜치를 푸시했거나 풀 요청을 열었을 때, 대화의 카드는 다음 단계에 대한 버튼을 표시할 수 있습니다.

184 

185* **충돌 해결**, **CI 수정**, **의견 처리**, **병합**은 해당 지침을 사용자의 메시지로 스레드에 보내므로, 풀 요청에 반응할 때까지 기다리는 대신 스레드에 직접 메시지를 보낼 수 있습니다.

186* **PR 검토**는 GitHub에서 풀 요청을 엽니다.

187* **PR 생성**은 유휴 스레드가 브랜치를 푸시했지만 풀 요청을 열지 않았을 때 나타납니다. 클릭하면 스레드에 풀 요청을 열도록 지시하는 대신 해당 브랜치에서 직접 풀 요청을 생성합니다.

188 

189스레드가 풀 요청을 열 때를 변경하려면, 예를 들어 요청할 때만 또는 어느 브랜치에서 시작할지, 작업에서 또는 [프로젝트 지침](#write-project-instructions)에서 그렇게 말합니다.183스레드가 풀 요청을 열 때를 변경하려면, 예를 들어 요청할 때만 또는 어느 브랜치에서 시작할지, 작업에서 또는 [프로젝트 지침](#write-project-instructions)에서 그렇게 말합니다.

190 184 

191### 개요에서 필요한 것 확인185### 개요에서 필요한 것 확인

212 206 

213### 제어가 필요할 때 스레드 열기207### 제어가 필요할 때 스레드 열기

214 208 

215대화의 스레드 카드 또는 개요의 행을 클릭하여 개요 창에서 스레드의 트랜스크립트를 엽니다. 거기서 다음을 할 수 있습니다.209대화의 스레드 또는 개요의 해당 행을 클릭하여 개요 창에서 스레드를 엽니다. 거기서 다음을 할 수 있습니다.

216 210 

217* Claude가 한 일을 단계별로 읽습니다.211* Claude가 한 일을 단계별로 읽습니다.

218* 스레드의 자체 메시지 상자에 작성하여 작업을 조정합니다. 거기의 메시지는 해당 스레드로 직접 가고, 프로젝트 대화의 후속은 Claude가 후속을 해당 스레드와 일치시킬 때만 도달합니다.212* 스레드의 자체 메시지 상자에 작성하여 작업을 조정합니다. 거기의 메시지는 해당 스레드로 직접 가고, 프로젝트 대화의 후속은 Claude가 후속을 해당 스레드와 일치시킬 때만 도달합니다.

128| `--session-id` | 대화에 특정 세션 ID를 사용합니다(유효한 UUID여야 함) | `claude --session-id "550e8400-e29b-41d4-a716-446655440000"` |128| `--session-id` | 대화에 특정 세션 ID를 사용합니다(유효한 UUID여야 함) | `claude --session-id "550e8400-e29b-41d4-a716-446655440000"` |

129| `--setting-sources` | 로드할 설정 소스의 쉼표로 구분된 목록(`user`, `project`, `local`). [에이전트 뷰](https://code.claude.com/docs/ko/agent-view.md#what-carries-over-when-you-background) 및 [에이전트 팀](https://code.claude.com/docs/ko/agent-teams.md#context-and-communication)을 참조하여 이 세션에서 시작하는 세션이 목록을 상속하는 경우를 확인하세요 | `claude --setting-sources user,project` |129| `--setting-sources` | 로드할 설정 소스의 쉼표로 구분된 목록(`user`, `project`, `local`). [에이전트 뷰](https://code.claude.com/docs/ko/agent-view.md#what-carries-over-when-you-background) 및 [에이전트 팀](https://code.claude.com/docs/ko/agent-teams.md#context-and-communication)을 참조하여 이 세션에서 시작하는 세션이 목록을 상속하는 경우를 확인하세요 | `claude --setting-sources user,project` |

130| `--settings` | 설정 JSON 파일 또는 인라인 JSON 문자열의 경로입니다. 여기서 설정한 값은 이 세션에 대해 `settings.json` 파일의 동일한 키를 재정의합니다. 생략한 키는 파일 기반 값을 유지합니다. 파일은 2 MiB 이하의 일반 파일이어야 합니다. [설정 우선 순위](https://code.claude.com/docs/ko/settings.md#settings-precedence)를 참조하세요 | `claude --settings ./settings.json` |130| `--settings` | 설정 JSON 파일 또는 인라인 JSON 문자열의 경로입니다. 여기서 설정한 값은 이 세션에 대해 `settings.json` 파일의 동일한 키를 재정의합니다. 생략한 키는 파일 기반 값을 유지합니다. 파일은 2 MiB 이하의 일반 파일이어야 합니다. [설정 우선 순위](https://code.claude.com/docs/ko/settings.md#settings-precedence)를 참조하세요 | `claude --settings ./settings.json` |

131| `--strict-mcp-config` | `--mcp-config`의 MCP 서버만 사용하고 다른 모든 MCP 구성을 무시합니다. 관리되는 MCP 파일에서 플래그가 수행하는 작업에 대해 [managed-mcp.json으로 독점 제어](https://code.claude.com/docs/ko/managed-mcp.md#exclusive-control-with-managed-mcp-json)를 참조하세요 | `claude --strict-mcp-config --mcp-config ./mcp.json` |131| `--strict-mcp-config` | `.mcp.json`, `~/.claude.json` 또는 플러그인과 같은 위치에 구성된 MCP 서버를 건너뛰고 `--mcp-config`로 전달한 서버를 로드합니다. 관리형 MCP 파일에서 이 플래그가 수행하는 작업에 대해 [managed-mcp.json으로 독점 제어](https://code.claude.com/docs/ko/managed-mcp.md#exclusive-control-with-managed-mcp-json)를 참조하세요 | `claude --strict-mcp-config --mcp-config ./mcp.json` |

132| `--system-prompt` | 전체 시스템 프롬프트를 사용자 정의 텍스트로 바꿉니다 | `claude --system-prompt "You are a Python expert"` |132| `--system-prompt` | 전체 시스템 프롬프트를 사용자 정의 텍스트로 바꿉니다 | `claude --system-prompt "You are a Python expert"` |

133| `--system-prompt-file` | 파일에서 시스템 프롬프트를 로드하여 기본 프롬프트를 바꿉니다 | `claude --system-prompt-file ./custom-prompt.txt` |133| `--system-prompt-file` | 파일에서 시스템 프롬프트를 로드하여 기본 프롬프트를 바꿉니다 | `claude --system-prompt-file ./custom-prompt.txt` |

134| `--system-prompt-snapshot` | `off`를 전달하여 [대화의 첫 번째 요청에 기록된 프롬프트](#system-prompt-flags-in-resumed-conversations)를 재사용하는 대신 모든 요청에서 시스템 프롬프트를 다시 빌드합니다. 예를 들어 `--continue` 실행 간에 `--append-system-prompt` 텍스트를 반복할 때입니다. Claude Code v2.1.257 이상이 필요합니다 | `claude --system-prompt-snapshot off` |134| `--system-prompt-snapshot` | `off`를 전달하여 [대화의 첫 번째 요청에 기록된 프롬프트](#system-prompt-flags-in-resumed-conversations)를 재사용하는 대신 모든 요청에서 시스템 프롬프트를 다시 빌드합니다. 예를 들어 `--continue` 실행 간에 `--append-system-prompt` 텍스트를 반복할 때입니다. Claude Code v2.1.257 이상이 필요합니다 | `claude --system-prompt-snapshot off` |

2127 2127 

2128이를 막으려면 Claude Desktop 정책(Windows에서는 `HKLM`)에도 claude.ai 조직 ID로 `forceLoginOrgUUID`를 배포하십시오. 정책 자체에서 [Claude API를 선택](https://claude.com/docs/third-party/claude-desktop/claude-api#choose-an-authentication-approach)하는 경우를 제외하고, Claude Desktop은 앱을 다음에 실행할 때부터 사용자 자신의 API 키나 Console 계정을 더 이상 사용하지 않습니다.2128이를 막으려면 Claude Desktop 정책(Windows에서는 `HKLM`)에도 claude.ai 조직 ID로 `forceLoginOrgUUID`를 배포하십시오. 정책 자체에서 [Claude API를 선택](https://claude.com/docs/third-party/claude-desktop/claude-api#choose-an-authentication-approach)하는 경우를 제외하고, Claude Desktop은 앱을 다음에 실행할 때부터 사용자 자신의 API 키나 Console 계정을 더 이상 사용하지 않습니다.

2129 2129 

2130배포하기 전에 다음 두 가지 경우를 확인하십시오.2130배포하기 전에 다음 세 가지 경우를 확인하십시오.

2131 2131 

2132* **Claude Console 조직**: Claude Console 조직의 ID로 `forceLoginOrgUUID`만 단독으로 배포하지 마십시오. 그러면 조직 구성원이 Claude Desktop을 사용할 수 없게 됩니다. 대신 [Claude API 계정 로그인을 제공하는 기기](https://claude.com/docs/third-party/claude-desktop/claude-api#which-devices-offer-the-claude-api-account-sign-in)를 참조하십시오.2132* **Claude Console 조직**: Claude Console 조직의 ID로 `forceLoginOrgUUID`만 단독으로 배포하지 마십시오. 그러면 조직 구성원이 Claude Desktop을 사용할 수 없게 됩니다. 대신 [Claude API 계정 로그인을 제공하는 기기](https://claude.com/docs/third-party/claude-desktop/claude-api#which-devices-offer-the-claude-api-account-sign-in)를 참조하십시오.

2133* **Enterprise Admin Console**: Enterprise Admin Console에서 컴퓨터의 Claude Desktop 구성을 전달하는 경우, 먼저 해당 컴퓨터를 Claude Desktop v2.37337.0 이상으로 업데이트하십시오. 이전 버전은 이 키가 설정되면 해당 구성을 무시하기 때문입니다. [기기를 관리 프로필에 유지](https://claude.com/docs/third-party/claude-desktop/admin-console#keep-a-device-on-its-managed-profile)를 참조하십시오.2133* **Enterprise Admin Console**: Enterprise Admin Console에서 컴퓨터의 Claude Desktop 구성을 전달하는 경우, 먼저 해당 컴퓨터를 Claude Desktop v2.37337.0 이상으로 업데이트하십시오. 이전 버전은 이 키가 설정되면 해당 구성을 무시하기 때문입니다. [기기를 관리 프로필에 유지](https://claude.com/docs/third-party/claude-desktop/admin-console#keep-a-device-on-its-managed-profile)를 참조하십시오.

2134* **서드파티 제공업체**: 사용자가 앱에서 자체 [서드파티 추론 구성](https://claude.com/docs/third-party/claude-desktop/in-app-configuration)을 설정한 경우, 이 키를 배포한 후 다음 실행부터 Claude Desktop은 해당 구성을 무시합니다. 사용자가 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 LLM 게이트웨이를 계속 사용하도록 하려면 동일한 Claude Desktop 정책에서 사용자의 컴퓨터에 [구성을 배포](https://claude.com/docs/third-party/claude-desktop/configuration)하십시오.

2134 2135 

2135### 네트워크 액세스 요구 사항2136### 네트워크 액세스 요구 사항

2136 2137 

182* **Review allowed permissions**: **Always allowed** 패널에서 이 작업에 대해 저장된 도구 승인을 확인하고 취소합니다.182* **Review allowed permissions**: **Always allowed** 패널에서 이 작업에 대해 저장된 도구 승인을 확인하고 취소합니다.

183* **Delete**: 작업을 제거합니다. 작업이 생성한 세션은 삭제되지 않고 [보관](https://code.claude.com/docs/ko/desktop.md#organize-and-find-sessions)됩니다. 작업의 `SKILL.md` 파일이 들어 있는 폴더는 디스크의 `~/.claude/scheduled-tasks/<task-name>/`에, 또는 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/ko/env-vars) 변수를 설정한 경우 그 아래의 `scheduled-tasks/<task-name>/`에 그대로 남습니다. 해당 폴더를 제거하려면 직접 삭제해야 합니다.183* **Delete**: 작업을 제거합니다. 작업이 생성한 세션은 삭제되지 않고 [보관](https://code.claude.com/docs/ko/desktop.md#organize-and-find-sessions)됩니다. 작업의 `SKILL.md` 파일이 들어 있는 폴더는 디스크의 `~/.claude/scheduled-tasks/<task-name>/`에, 또는 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/ko/env-vars) 변수를 설정한 경우 그 아래의 `scheduled-tasks/<task-name>/`에 그대로 남습니다. 해당 폴더를 제거하려면 직접 삭제해야 합니다.

184 184 

185Desktop의 모든 세션에서 Claude에게 요청하여 작업을 나열, 만들, 편집 및 일시 중지할 수도 있습니다. 예를 들어, "내 dependency-audit 작업을 일시 중지해 줘" 또는 "내 예약된 작업을 보여 줘"입니다. 작업을 삭제하려면 세부 정보 페이지의 **Delete** 버튼을 사용합니다.185Claude에게 요청하거나, 작업이 스스로 업데이트하도록 하거나, 디스크에서 작업의 프롬프트를 편집하여 작업을 관리할 수도 있습니다:

186 186 

187작업이 `update_scheduled_task` MCP 도구로 자신의 일정이나 프롬프트를 변경하도록 허용하려면 **Run now**를 클릭하고 매번 호출을 승인합니다.187* **Claude에게 요청**: Desktop의 모든 세션에서 Claude에게 요청하여 작업을 나열, 생성, 편집 및 일시 중지합니다. 예를 들어, "내 dependency-audit 작업을 일시 중지해 줘" 또는 "내 예약된 작업을 보여 줘"와 같이 요청합니다. 작업을 삭제하려면 세부 정보 페이지의 **Delete** 버튼을 사용합니다.

188 188* **작업이 스스로 업데이트하도록 허용**: 작업이 `update_scheduled_task` MCP 도구로 자신의 일정이나 프롬프트를 변경하도록 하려면 **Run now**를 클릭하고 매번 호출을 승인합니다.

189디스크에서 작업의 프롬프트를 편집하려면 `~/.claude/scheduled-tasks/<task-name>/SKILL.md`를 엽니다 (설정된 경우 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/ko/env-vars) 아래). 파일은 `name` 및 `description`에 대해 YAML frontmatter를 사용하며, 프롬프트는 본문입니다. 변경 사항은 다음 실행에 적용됩니다. Schedule, folder 및 enabled state는 이 파일에 없습니다: Edit 양식을 통해 변경하거나 Claude에게 요청합니다.189* **디스크에서 프롬프트 편집**: `~/.claude/scheduled-tasks/<task-name>/SKILL.md`를 열거나, [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/ko/env-vars) 변수를 설정한 경우 그 아래의 `scheduled-tasks/<task-name>/SKILL.md`를 엽니다. 파일은 `name` 및 `description`에 대해 YAML frontmatter를 사용하며, 프롬프트는 본문입니다. 변경 사항은 다음 실행에 적용됩니다. Schedule, folder 및 enabled state는 이 파일에 없습니다: Edit 양식을 통해 변경하거나 Claude에게 요청합니다.

190 190 

191## 관련 리소스191## 관련 리소스

192 192 

356| `CLAUDE_CODE_PERFORCE_MODE` | Perforce 인식 쓰기 보호를 활성화하려면 `1`로 설정합니다. 설정하면 대상 파일에 소유자 쓰기 비트가 없을 때 Edit, Write, NotebookEdit이 `p4 edit <file>` 힌트와 함께 실패합니다. Perforce는 동기화된 파일에서 `p4 edit`으로 열기 전까지 이 비트를 해제합니다. 이를 통해 Claude Code가 Perforce 변경 추적을 우회하는 것을 방지합니다 |356| `CLAUDE_CODE_PERFORCE_MODE` | Perforce 인식 쓰기 보호를 활성화하려면 `1`로 설정합니다. 설정하면 대상 파일에 소유자 쓰기 비트가 없을 때 Edit, Write, NotebookEdit이 `p4 edit <file>` 힌트와 함께 실패합니다. Perforce는 동기화된 파일에서 `p4 edit`으로 열기 전까지 이 비트를 해제합니다. 이를 통해 Claude Code가 Perforce 변경 추적을 우회하는 것을 방지합니다 |

357| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | 플러그인 루트 디렉터리를 재정의합니다. 이름과 달리 캐시 자체가 아닌 상위 디렉터리를 설정하며, 마켓플레이스와 플러그인 캐시는 이 경로 아래의 하위 디렉터리에 위치합니다. 기본값은 `~/.claude/plugins`입니다 |357| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | 플러그인 루트 디렉터리를 재정의합니다. 이름과 달리 캐시 자체가 아닌 상위 디렉터리를 설정하며, 마켓플레이스와 플러그인 캐시는 이 경로 아래의 하위 디렉터리에 위치합니다. 기본값은 `~/.claude/plugins`입니다 |

358| `CLAUDE_CODE_PLUGIN_DIRS` | 세션에 로드할 플러그인 디렉터리로, 각각 [`--plugin-dir`](https://code.claude.com/docs/ko/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 플래그와 같은 방식으로 로드됩니다. 여러 경로는 Unix에서는 `:`, Windows에서는 `;`로 구분합니다. Claude Code는 상대 경로를 건너뛰므로 각 경로를 절대 경로로 지정하거나 `~`로 시작합니다. Claude Code v2.1.280 이상이 필요합니다. [한 세션에 플러그인 로드](https://code.claude.com/docs/ko/plugins/create.md#load-a-directory-or-archive-for-one-session)를 참조하세요 |358| `CLAUDE_CODE_PLUGIN_DIRS` | 세션에 로드할 플러그인 디렉터리로, 각각 [`--plugin-dir`](https://code.claude.com/docs/ko/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 플래그와 같은 방식으로 로드됩니다. 여러 경로는 Unix에서는 `:`, Windows에서는 `;`로 구분합니다. Claude Code는 상대 경로를 건너뛰므로 각 경로를 절대 경로로 지정하거나 `~`로 시작합니다. Claude Code v2.1.280 이상이 필요합니다. [한 세션에 플러그인 로드](https://code.claude.com/docs/ko/plugins/create.md#load-a-directory-or-archive-for-one-session)를 참조하세요 |

359| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)의 파일이 변경될 때 Claude Code가 해당 mod를 다시 로드할지 여부를 제어합니다. 다시 로드는 `--plugin-dir`로 디렉터리에서 로드한 mod에 적용되며, 대화형 세션에서는 기본적으로 켜져 있습니다. 비대화형 세션에서도 켜려면 `1`로, 모든 세션에서 끄려면 `0`으로 설정합니다. Claude Code v2.1.287 이상이 필요합니다. [mod 설정 및 환경 변수](https://code.claude.com/docs/ko/plugins/mods/reference.md#settings-and-environment-variables)를 참조하세요 |359| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)의 파일이 변경될 때 다시 로드할지 여부를 제어합니다. 기본적으로 [스킬 디렉터리](https://code.claude.com/docs/ko/plugins/org.md#keep-skills-directory-plugins-loading)의 mod는 [비대화형](https://code.claude.com/docs/ko/headless.md)을 포함해 프롬프트가 두 개 이상인 모든 세션에서 다시 로드됩니다. `--plugin-dir` 디렉터리의 mod는 대화형 터미널 세션에서만 다시 로드됩니다. `1`로 설정하면 스킬 디렉터리 mod처럼 다시 로드하고, `0`으로 설정하면 모든 곳에서 다시 로드를 끕니다. Claude Code v2.1.287 이상이 필요합니다 |

360| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 플러그인 마켓플레이스를 복제하거나 새로 고치는 타임아웃(밀리초)입니다(기본값: 120000). 큰 저장소나 느린 네트워크 연결에서는 이 값을 늘립니다. [Git clone timed out](https://code.claude.com/docs/ko/plugins/troubleshooting.md#git-clone-timed-out-after-120s)을 참조하세요 |360| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 플러그인 마켓플레이스를 복제하거나 새로 고치는 타임아웃(밀리초)입니다(기본값: 120000). 큰 저장소나 느린 네트워크 연결에서는 이 값을 늘립니다. [Git clone timed out](https://code.claude.com/docs/ko/plugins/troubleshooting.md#git-clone-timed-out-after-120s)을 참조하세요 |

361| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 마켓플레이스 새로 고침이 원격에 연결하거나 인증할 수 없을 때 재복제 시도를 건너뛰고 기존 마켓플레이스 체크아웃을 계속 사용하려면 `1`로 설정합니다. 재복제가 같은 방식으로 실패할 오프라인 또는 에어갭 환경에서 유용합니다. [오프라인 환경에서 마켓플레이스 업데이트 실패](https://code.claude.com/docs/ko/plugins/troubleshooting.md#marketplace-updates-keep-failing-offline)를 참조하세요 |361| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 마켓플레이스 새로 고침이 원격에 연결하거나 인증할 수 없을 때 재복제 시도를 건너뛰고 기존 마켓플레이스 체크아웃을 계속 사용하려면 `1`로 설정합니다. 재복제가 같은 방식으로 실패할 오프라인 또는 에어갭 환경에서 유용합니다. [오프라인 환경에서 마켓플레이스 업데이트 실패](https://code.claude.com/docs/ko/plugins/troubleshooting.md#marketplace-updates-keep-failing-offline)를 참조하세요 |

362| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | GitHub `owner/repo` 약식 소스를 SSH 대신 HTTPS로 복제하려면 `1`로 설정합니다. 플러그인 설치 및 업데이트와 `/plugin marketplace add` 및 `update`에 적용됩니다. CI 러너, 컨테이너 또는 `github.com`용 SSH 키가 구성되지 않은 환경에서 유용합니다 |362| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | GitHub `owner/repo` 약식 소스를 SSH 대신 HTTPS로 복제하려면 `1`로 설정합니다. 플러그인 설치 및 업데이트와 `/plugin marketplace add` 및 `update`에 적용됩니다. CI 러너, 컨테이너 또는 `github.com`용 SSH 키가 구성되지 않은 환경에서 유용합니다 |

35이 중 일부는 제공자별 차이가 있습니다:35이 중 일부는 제공자별 차이가 있습니다:

36 36 

37* **MCP 서버**: [claude.ai의 커넥터](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai)는 claude.ai 구독이 활성 인증 방법일 때만 로드됩니다. [도구 검색](https://code.claude.com/docs/ko/mcp.md#configure-tool-search)은 Microsoft Foundry [Azure에서 호스팅되는 배포](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)에서는 지원되지 않습니다. Google Cloud의 Agent Platform에서는 Claude Opus 4.5, Claude Sonnet 4.5, Claude Haiku 4.5보다 이전 모델에서 도구 검색이 지원되지 않습니다.37* **MCP 서버**: [claude.ai의 커넥터](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai)는 claude.ai 구독이 활성 인증 방법일 때만 로드됩니다. [도구 검색](https://code.claude.com/docs/ko/mcp.md#configure-tool-search)은 Microsoft Foundry [Azure에서 호스팅되는 배포](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)에서는 지원되지 않습니다. Google Cloud의 Agent Platform에서는 Claude Opus 4.5, Claude Sonnet 4.5, Claude Haiku 4.5보다 이전 모델에서 도구 검색이 지원되지 않습니다.

38* **서브에이전트**: 주 대화가 Fable로 실행될 때, 기본 제공 [Explore 서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#built-in-subagents)는 Claude 구독, Anthropic Console 계정 또는 `ANTHROPIC_BASE_URL`을 통해 연결되는 [LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway)에서는 Opus로 실행됩니다. AWS의 Claude Platform을 포함한 다른 제공자에서는 Fable로 실행됩니다.38* **서브에이전트**: 상위 대화가 Fable을 실행하는 경우, 기본 제공 [Explore 서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#built-in-subagents)는 Claude 구독, Anthropic Console 계정 또는 `ANTHROPIC_BASE_URL`을 통해 연결되는 [LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway)를 사용할 때 Opus에서 실행됩니다. Claude Platform on AWS를 포함한 다른 제공업체에서는 Fable에서 실행됩니다

39* **[Commands](https://code.claude.com/docs/ko/commands.md#all-commands)**:39* **[Commands](https://code.claude.com/docs/ko/commands.md#all-commands)**:

40 * `/design-sync` 및 `/import`와 그 `claude import` 서브명령 형식은 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, AWS의 Claude Platform에서 사용할 수 없으며, [Claude apps gateway](https://code.claude.com/docs/ko/claude-apps-gateway#availability-and-limitations)를 통해서도 사용할 수 없습니다.40 * `/design-sync` 및 `/import`와 그 `claude import` 서브명령 형식은 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, AWS의 Claude Platform에서 사용할 수 없으며, [Claude apps gateway](https://code.claude.com/docs/ko/claude-apps-gateway#availability-and-limitations)를 통해서도 사용할 수 없습니다.

41 * `/voice`는 claude.ai 계정이 필요합니다.41 * `/voice`는 claude.ai 계정이 필요합니다.

188>188>

189> **Hook에 가드레일을 넣으세요.** CLAUDE.md나 skill의 "`.env`를 편집하지 마세요"와 같은 지침은 요청이지 보장이 아닙니다. 편집을 차단하는 `PreToolUse` hook은 강제입니다. 규칙이 매번 유지되어야 하면, 프롬프트 지침이 아닌 hook으로 만드세요.189> **Hook에 가드레일을 넣으세요.** CLAUDE.md나 skill의 "`.env`를 편집하지 마세요"와 같은 지침은 요청이지 보장이 아닙니다. 편집을 차단하는 `PreToolUse` hook은 강제입니다. 규칙이 매번 유지되어야 하면, 프롬프트 지침이 아닌 hook으로 만드세요.

190>190>

191> **Hook 출력은 컨텍스트에 들어갑니다.** 린터를 실행하는 `PostToolUse` hook은 결과를 Claude가 읽는 텍스트로 피드백합니다. `/fix-lint` skill은 Claude에게 이를 해결하는 방법을 알려줍니다.191> **훅과 스킬을 함께 사용하세요.** `PostToolUse` 훅을 사용하여 린터를 실행하고 [오류를 Claude에게 전달](https://code.claude.com/docs/ko/hooks.md#exit-code-2-behavior-per-event)하세요. 오류 수정에 관한 자체 규칙을 Claude에게 제공하려면 `/fix-lint` 같은 스킬을 작성하세요.

192 192 

193### 기능이 어떻게 계층화되는지 이해하기193### 기능이 어떻게 계층화되는지 이해하기

194 194 

283 283 

284### Sandboxing284### Sandboxing

285 285 

286Bash 도구에 대한 OS 수준 파일 시스템 및 네트워크 격리입니다. 명령은 미리 정의한 경계 내에서 실행되므로 Claude는 명령별 승인 프롬프트 없이 그 안에서 자유롭게 작업할 수 있습니다. 샌드박싱은 [권한 규칙](#permission-rule)과 별개의 계층입니다.286Bash 도구에 대한 OS 수준 파일 시스템 및 네트워크 격리입니다. 명령은 미리 정의한 경계 내에서 실행됩니다. 샌드박싱은 [권한 규칙](#permission-rule)과 별개의 계층입니다.

287 287 

288자세히 알아보기: [샌드박싱](https://code.claude.com/docs/ko/sandboxing.md)288자세히 알아보기: [샌드박싱](https://code.claude.com/docs/ko/sandboxing.md)

289 289 

242 242 

243### 보호된 파일에 대한 편집 차단243### 보호된 파일에 대한 편집 차단

244 244 

245Claude가 `.env`, `package-lock.json` 또는 `.git/` 내의 모든 항목과 같은 민감한 파일을 수정하지 못하도록 방지합니다. Claude는 편집이 차단된 이유를 설명하는 피드백을 받으므로 접근 방식을 조정할 수 있습니다.245Claude의 `Edit` 및 `Write` 도구가 `.env`, `package-lock.json` 또는 `.git/` 내의 모든 항목과 같은 민감한 파일을 수정하지 못하도록 방지합니다. Claude는 편집이 차단된 이유를 설명하는 피드백을 받으므로 접근 방식을 조정할 수 있습니다.

246 246 

247이 예시는 훅이 호출하는 별도의 스크립트 파일을 사용합니다. 스크립트는 대상 파일 경로를 보호된 패턴 목록과 비교하고, 종료 코드 2로 종료하여 편집을 차단합니다.247이 예시는 훅이 호출하는 별도의 스크립트 파일을 사용합니다. 스크립트는 대상 파일 경로를 보호된 패턴 목록과 비교하고, 종료 코드 2로 종료하여 편집을 차단합니다.

248 248 

306 306 

307Claude에게 `.env` 파일에 주석을 추가하도록 요청하십시오. Claude Code는 편집이 실행되기 전에 이를 차단하고 스크립트의 `Blocked:` 메시지를 피드백으로 Claude에 전달합니다.307Claude에게 `.env` 파일에 주석을 추가하도록 요청하십시오. Claude Code는 편집이 실행되기 전에 이를 차단하고 스크립트의 `Blocked:` 메시지를 피드백으로 Claude에 전달합니다.

308 308 

309Claude는 여전히 셸 명령으로 보호된 파일을 변경할 수 있습니다. 이러한 명령 중 일부를 차단하려면 `.claude/settings.json`의 `permissions.deny` 아래에 경로별로 [`Edit` 거부 규칙](https://code.claude.com/docs/ko/permissions#what-read-and-edit-rules-cover)을 추가하십시오. 예를 들어 프로젝트 루트의 `.env`에는 `Edit(/.env)`를 추가합니다.

310 

311이러한 규칙이 있더라도 Claude는 다른 방식으로 `.env`를 변경할 수 있습니다. 명령이 쓸 수 있는 파일을 제한하려면 [샌드박싱 구성](https://code.claude.com/docs/ko/sandboxing.md#configure-sandboxing)을 참조하십시오.

312 

309### 컨텍스트 압축 후 컨텍스트 재주입313### 컨텍스트 압축 후 컨텍스트 재주입

310 314 

311Claude의 컨텍스트 윈도우가 가득 차면 압축이 대화를 요약하여 공간을 확보합니다. 이 과정에서 중요한 세부 정보가 손실될 수 있습니다. `compact` matcher와 함께 `SessionStart` 훅을 사용하여 압축이 일어날 때마다 중요한 컨텍스트를 다시 주입하십시오.315Claude의 컨텍스트 윈도우가 가득 차면 압축이 대화를 요약하여 공간을 확보합니다. 이 과정에서 중요한 세부 정보가 손실될 수 있습니다. `compact` matcher와 함께 `SessionStart` 훅을 사용하여 압축이 일어날 때마다 중요한 컨텍스트를 다시 주입하십시오.

296* 최상위 `output_config.effort` 필드. 이를 거부하는 업스트림은 [자동 재시도 및 오류 전달](#automatic-retry-and-error-forwarding)에서 다룹니다.296* 최상위 `output_config.effort` 필드. 이를 거부하는 업스트림은 [자동 재시도 및 오류 전달](#automatic-retry-and-error-forwarding)에서 다룹니다.

297* 베타 헤더가 없는 적응형 추론 `thinking` 필드297* 베타 헤더가 없는 적응형 추론 `thinking` 필드

298* [대화 중간 시스템 메시지](#feature-pass-through)를 전달하는 `role: "system"` 항목298* [대화 중간 시스템 메시지](#feature-pass-through)를 전달하는 `role: "system"` 항목

299* 자동 모드의 [서버 측 분류기 검토](https://code.claude.com/docs/ko/permission-modes.md#server-side-classifier-review)를 위한 `anthropic-beta` 값과 `safeguards` 필드. `/status`에서 **Auto mode server**가 `Enabled`로 표시되는 경우처럼 해당 검토가 켜져 있는 세션에 해당합니다. 검토를 끄려면 세션을 시작하기 전에 `CLAUDE_CODE_AUTO_MODE_SERVER=0`을 설정합니다. 그러면 터미널에서 `/status`에 **Auto mode server**가 `Disabled`로 표시됩니다.

299* 구독 인증이 요구하는 OAuth `anthropic-beta` 값300* 구독 인증이 요구하는 OAuth `anthropic-beta` 값

300* 개발자가 [`ANTHROPIC_BETAS`](https://code.claude.com/docs/ko/env-vars) 또는 [`CLAUDE_CODE_EXTRA_BODY`](https://code.claude.com/docs/ko/env-vars)를 통해 직접 추가하는 헤더 값 및 본문 필드301* 개발자가 [`ANTHROPIC_BETAS`](https://code.claude.com/docs/ko/env-vars) 또는 [`CLAUDE_CODE_EXTRA_BODY`](https://code.claude.com/docs/ko/env-vars)를 통해 직접 추가하는 헤더 값 및 본문 필드

301 302 

30| 패턴 | 기능 | 구성 |30| 패턴 | 기능 | 구성 |

31| :- | :- | :- |31| :- | :- | :- |

32| **MCP 비활성화** | [배타적 제어](#exclusive-control-with-managed-mcp-json)에서 로드되는 몇 가지를 제외한 서버가 로드되지 않음 | 빈 서버 맵이 있는 `managed-mcp.json` |32| **MCP 비활성화** | [배타적 제어](#exclusive-control-with-managed-mcp-json)에서 로드되는 몇 가지를 제외한 서버가 로드되지 않음 | 빈 서버 맵이 있는 `managed-mcp.json` |

33| **고정 배포** | 모든 사용자가 동일한 서버를 받으며 다른 서버를 추가할 수 없음 | 원하는 서버가 있는 `managed-mcp.json` |33| **고정 배포** | 모든 사용자가 나열한 서버를 받으며, 사용자가 구성한 서버는 로드되지 않음 | 원하는 서버가 있는 `managed-mcp.json` |

34| **제공된 서버** | 모든 사용자가 나열한 원격 서버를 받고 자신의 서버를 유지함 | 관리 설정의 `managedMcpServers` |34| **제공된 서버** | 모든 사용자가 나열한 원격 서버를 받고 자신의 서버를 유지함 | 관리 설정의 `managedMcpServers` |

35| **승인된 카탈로그** | 승인된 서버 목록을 게시하고, 사용자가 원하는 서버를 추가하며, 다른 모든 것은 차단됨 | `allowedMcpServers` + `allowManagedMcpServersOnly: true` |35| **승인된 카탈로그** | 승인된 서버 목록을 게시하고, 사용자가 원하는 서버를 추가하며, 다른 모든 것은 차단됨 | `allowedMcpServers` + `allowManagedMcpServersOnly: true` |

36| **플러그인 서버만** | 사용자가 `~/.claude.json` 또는 `.mcp.json`을 통해 서버를 추가할 수 없으며, [스킬 디렉터리 플러그인](https://code.claude.com/docs/ko/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings)은 더 이상 플러그인으로 로드되지 않고, 다른 플러그인의 서버는 여전히 로드됨 | [`strictPluginOnlyCustomization`](https://code.claude.com/docs/ko/settings-reference#strictpluginonlycustomization)과 목록의 `mcp` |36| **플러그인 서버만** | 사용자가 `~/.claude.json` 또는 `.mcp.json`을 통해 서버를 추가할 수 없으며, [스킬 디렉터리 플러그인](https://code.claude.com/docs/ko/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings)은 더 이상 플러그인으로 로드되지 않고, 다른 플러그인의 서버는 여전히 로드됨 | [`strictPluginOnlyCustomization`](https://code.claude.com/docs/ko/settings-reference#strictpluginonlycustomization)과 목록의 `mcp` |

49* 파일에서 정의한 서버49* 파일에서 정의한 서버

50* [`managedMcpServers`를 통해 제공하는](#provide-servers-through-managed-settings) 서버50* [`managedMcpServers`를 통해 제공하는](#provide-servers-through-managed-settings) 서버

51* 세션을 시작한 앱이 등록하는 인프로세스 서버(예: VS Code 확장 프로그램의 자체 서버 또는 [데스크톱 앱이 제공하는 커넥터](https://code.claude.com/docs/ko/mcp.md#how-connectors-reach-claude-code))51* 세션을 시작한 앱이 등록하는 인프로세스 서버(예: VS Code 확장 프로그램의 자체 서버 또는 [데스크톱 앱이 제공하는 커넥터](https://code.claude.com/docs/ko/mcp.md#how-connectors-reach-claude-code))

52* [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)가 [도구를 추가](https://code.claude.com/docs/ko/plugins/mods/api.md#add-a-tool)할 때 Claude Code가 생성하는 서버. 사용자의 mod가 추가하는 도구를 차단하려면 [사용자가 설치한 mod가 로드되지 않도록 하세요](https://code.claude.com/docs/ko/plugins/mods/admin.md#stop-user-installed-mods-from-loading).

52* [Claude in Chrome](https://code.claude.com/docs/ko/chrome.md) 서버(내장), [관리되는 집합과 함께 허용](#allow-claude-in-chrome-alongside-the-managed-set)하는 경우53* [Claude in Chrome](https://code.claude.com/docs/ko/chrome.md) 서버(내장), [관리되는 집합과 함께 허용](#allow-claude-in-chrome-alongside-the-managed-set)하는 경우

53 54 

54사용자는 플러그인 제공 서버 및 [`--mcp-config` CLI 플래그](https://code.claude.com/docs/ko/cli-reference#cli-flags)로 전달된 서버를 포함하여 다른 MCP 서버를 추가, 수정 또는 사용할 수 없습니다. 또한 이 파일은 [관리되는 집합과 함께 허용](#allow-claude-ai-connectors-alongside-the-managed-set)하지 않는 한 Claude Code가 자체적으로 가져오는 claude.ai 커넥터를 억제합니다.55사용자는 플러그인 제공 서버 및 [`--mcp-config` CLI 플래그](https://code.claude.com/docs/ko/cli-reference#cli-flags)로 전달된 서버를 포함하여 다른 MCP 서버를 추가, 수정 또는 사용할 수 없습니다. 또한 이 파일은 [관리되는 집합과 함께 허용](#allow-claude-ai-connectors-alongside-the-managed-set)하지 않는 한 Claude Code가 자체적으로 가져오는 claude.ai 커넥터를 억제합니다.

137}138}

138```139```

139 140 

140`claude mcp add`는 위의 엔터프라이즈 정책 오류로 실패합니다. 사용자가 이전에 구성한 서버는 다음 번에 세션을 시작할 때 로드를 중지합니다. 정책이 이유라는 경고는 없습니다. `managedMcpServers`를 통해 제공하는 서버와 관리되는 집합과 함께 허용하는 다른 모든 것은 빈 맵 아래에서도 로드되므로 MCP를 완전히 비활성화하려면 해당 키를 설정하지 않은 상태로 두세요.141`claude mcp add`는 위의 엔터프라이즈 정책 오류로 실패합니다. 사용자가 이전에 구성한 서버는 다음 번에 세션을 시작할 때 로드를 중지합니다. 정책이 이유라는 경고는 없습니다. `managedMcpServers`를 통해 제공하는 서버와 관리되는 집합과 함께 허용하는 다른 모든 것은 빈 맵 아래에서도 [여전히 로드](#exclusive-control-with-managed-mcp-json)되므로 해당 키를 설정하지 않은 상태로 두세요.

141 142 

142### 관리되는 집합과 함께 claude.ai 커넥터 허용143### 관리되는 집합과 함께 claude.ai 커넥터 허용

143 144 

806 806 

807* 서버를 [`disabledMcpjsonServers`](https://code.claude.com/docs/ko/settings-reference#disabledmcpjsonservers)에 추가합니다. 이렇게 하면 모든 권한 모드에서 해당 서버가 차단됩니다.807* 서버를 [`disabledMcpjsonServers`](https://code.claude.com/docs/ko/settings-reference#disabledmcpjsonservers)에 추가합니다. 이렇게 하면 모든 권한 모드에서 해당 서버가 차단됩니다.

808* [`--setting-sources`](https://code.claude.com/docs/ko/cli-reference#cli-flags) 또는 SDK의 `settingSources` 옵션으로 프로젝트 설정을 완전히 제외합니다.808* [`--setting-sources`](https://code.claude.com/docs/ko/cli-reference#cli-flags) 또는 SDK의 `settingSources` 옵션으로 프로젝트 설정을 완전히 제외합니다.

809* [`--strict-mcp-config`](https://code.claude.com/docs/ko/cli-reference#cli-flags)로 세션을 시작합니다. 그러면 Claude Code는 `--mcp-config`로 전달한 MCP 서버만 사용합니다. Claude Code가 로드하지 않는 프로젝트 범위 서버에 대해 승인 프롬프트를 건너뛰려면 Claude Code v2.1.246 이상이 필요합니다. v2.1.246 이전에는 strict 세션에서도 해당 서버에 대한 승인을 기다렸기 때문에 백그라운드 세션이 시작 시 대기 상태로 남았습니다. 관리형 MCP 파일이 있을 때 이 플래그가 어떻게 동작하는지는 [managed-mcp.json을 통한 독점 제어](https://code.claude.com/docs/ko/managed-mcp.md#exclusive-control-with-managed-mcp-json)를 참조하세요.809* [`--strict-mcp-config`](https://code.claude.com/docs/ko/cli-reference#cli-flags)로 세션을 시작합니다. 그러면 Claude Code는 `--mcp-config`로 전달한 서버를 로드하고 `.mcp.json` 등의 위치에 구성된 서버는 건너뜁니다. Claude Code가 로드하지 않는 프로젝트 범위 서버에 대해 승인 프롬프트를 건너뛰려면 Claude Code v2.1.246 이상이 필요합니다. 관리형 MCP 파일이 있을 때 이 플래그가 어떻게 동작하는지는 [managed-mcp.json을 통한 독점 제어](https://code.claude.com/docs/ko/managed-mcp.md#exclusive-control-with-managed-mcp-json)를 참조하세요.

810 810 

811저장소에 커밋된 승인이 워크스페이스 신뢰와 어떻게 상호 작용하는지는 [프로젝트 서버 승인과 워크스페이스 신뢰](#project-server-approvals-and-workspace-trust)에서 다룹니다.811저장소에 커밋된 승인이 워크스페이스 신뢰와 어떻게 상호 작용하는지는 [프로젝트 서버 승인과 워크스페이스 신뢰](#project-server-approvals-and-workspace-trust)에서 다룹니다.

812 812 

273* **`/model`**: Claude Code는 스위치를 오류로 거부합니다273* **`/model`**: Claude Code는 스위치를 오류로 거부합니다

274* **`--model` 플래그, `ANTHROPIC_MODEL`, 또는 `model` 설정**: Claude Code는 시작 시 값을 요청된 모델과 대체된 모델을 모두 이름 지정하는 경고와 함께 대체하고, 세션은 기본 모델에서 시작됩니다274* **`--model` 플래그, `ANTHROPIC_MODEL`, 또는 `model` 설정**: Claude Code는 시작 시 값을 요청된 모델과 대체된 모델을 모두 이름 지정하는 경고와 함께 대체하고, 세션은 기본 모델에서 시작됩니다

275* **[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions)**: Claude Code는 변수를 무시합니다275* **[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions)**: Claude Code는 변수를 무시합니다

276* **서브에이전트 또는 팀원 재정의**: Claude Code는 요청을 실패하지 않고 서브에이전트 또는 팀원을 폴백 모델에서 실행합니다. 서브에이전트 폴백은 [모델 선택](https://code.claude.com/docs/ko/sub-agents.md#choose-a-model)을 참조하고 팀원 폴백은 [팀원 및 모델 지정](https://code.claude.com/docs/ko/agent-teams.md#specify-teammates-and-models)을 참조하세요.276* **서브에이전트 또는 팀원 재정의**: Claude Code는 요청을 실패하지 않고 서브에이전트 또는 팀원을 폴백 모델에서 실행합니다. 서브에이전트 폴백은 [허용 목록이 서브에이전트 모델을 차단하는 경우](https://code.claude.com/docs/ko/sub-agents.md#when-an-allowlist-blocks-a-subagent-model)를 참조하고 팀원 폴백은 [팀원 및 모델 지정](https://code.claude.com/docs/ko/agent-teams.md#specify-teammates-and-models)을 참조하세요.

277 277 

278 대화형 세션에서, Claude Code는 이 폴백 또는 위의 최신 허용 버전 대체로 서브에이전트의 모델을 대체할 때 요청된 모델과 대체된 모델을 이름 지정하여 경고합니다. 팀원의 폴백은 보고하지 않습니다.278 대화형 세션에서, Claude Code는 최상위 서브에이전트의 모델을 대체할 때 경고합니다. 팀원의 폴백은 보고하지 않습니다.

279 279 

280 위의 최신 허용 버전 대체가 작동하는 경우, 차단된 패밀리 별칭은 대신 이를 따릅니다. v2.1.222 이전에는 별칭이 모든 제공자에서 다른 차단된 값처럼 폴백했습니다280 위의 최신 허용 버전 대체가 작동하는 경우, 차단된 패밀리 별칭은 대신 이를 따릅니다. v2.1.222 이전에는 별칭이 모든 제공자에서 다른 차단된 값처럼 폴백했습니다

281* **스킬 또는 명령 재정의**: Claude Code는 차단된 패밀리 별칭을 포함한 재정의를 무시하고, 스킬 또는 명령은 세션 모델에서 실행됩니다. [서브에이전트에서 실행되는](https://code.claude.com/docs/ko/skills.md#run-skills-in-a-subagent) 스킬 또는 명령은 대신 위의 서브에이전트 동작을 따릅니다281* **스킬 또는 명령 재정의**: Claude Code는 차단된 패밀리 별칭을 포함한 재정의를 무시하고, 스킬 또는 명령은 세션 모델에서 실행됩니다. [서브에이전트에서 실행되는](https://code.claude.com/docs/ko/skills.md#run-skills-in-a-subagent) 스킬 또는 명령은 대신 위의 서브에이전트 동작을 따릅니다

351 351 

352* **`availableModels`**: 사용자가 전환할 수 있는 명명된 모델을 제한합니다352* **`availableModels`**: 사용자가 전환할 수 있는 명명된 모델을 제한합니다

353* **`enforceAvailableModels`**: `availableModels` 허용 목록을 Default 옵션으로 확장하므로 Default는 목록 외부의 모델로 해석될 수 없습니다353* **`enforceAvailableModels`**: `availableModels` 허용 목록을 Default 옵션으로 확장하므로 Default는 목록 외부의 모델로 해석될 수 없습니다

354* **`deniedModels`** 및 **`availableModelsMatch`**: [특정 버전을 차단](#block-specific-models-or-versions)하여 `availableModels` 항목이 허용할 수 있습니다354* **`deniedModels`** 및 **`availableModelsMatch`**: 이 키가 없다면 `availableModels` 항목이 허용했을 [특정 버전을 차단](#block-specific-models-or-versions)합니다

355* **`model`**: 세션이 시작될 때 초기 모델 선택을 설정합니다355* **`model`**: 세션이 시작될 때 초기 모델 선택을 설정합니다

356* **`ANTHROPIC_DEFAULT_SONNET_MODEL`** / **`ANTHROPIC_DEFAULT_OPUS_MODEL`** / **`ANTHROPIC_DEFAULT_HAIKU_MODEL`** / **`ANTHROPIC_DEFAULT_FABLE_MODEL`**: `sonnet`, `opus`, `haiku`, 그리고 `fable` 별칭이 해석되는 것을 제어하고, [계정 유형 기본값](#default-model-setting)이 사용하는 버전을 제어합니다356* **`ANTHROPIC_DEFAULT_SONNET_MODEL`** / **`ANTHROPIC_DEFAULT_OPUS_MODEL`** / **`ANTHROPIC_DEFAULT_HAIKU_MODEL`** / **`ANTHROPIC_DEFAULT_FABLE_MODEL`**: `sonnet`, `opus`, `haiku`, 그리고 `fable` 별칭이 해석되는 것을 제어하고, [계정 유형 기본값](#default-model-setting)이 사용하는 버전을 제어합니다

357 357 

50| 원하는 것 | 시작 | 필요한 격리 | 참고 |50| 원하는 것 | 시작 | 필요한 격리 | 참고 |

51| :- | :- | :- | :- |51| :- | :- | :- | :- |

52| 모든 작업을 직접 검토 | Manual 모드: `claude --permission-mode default` | 없음 | 민감한 작업, 낯선 코드 |52| 모든 작업을 직접 검토 | Manual 모드: `claude --permission-mode default` | 없음 | 민감한 작업, 낯선 코드 |

53| 분류기 없이 더 적은 프롬프트로 로컬에서 반복 | Manual 모드 + [auto-allow mode](https://code.claude.com/docs/ko/sandboxing.md#sandbox-modes)의 Bash sandbox: `claude --permission-mode default`, 그 다음 `/sandbox` 실행 및 auto-allow 선택 | 기본 제공 Bash sandbox, macOS, Linux, WSL2 | Deny 규칙은 여전히 적용되고, `Bash(git push *)`와 같이 명령을 지정하는 ask 규칙은 여전히 프롬프트합니다. 확인을 요청할 수 있는 그 밖의 명령은 [Auto-allow mode](https://code.claude.com/docs/ko/sandboxing.md#auto-allow-mode)에서 다룹니다. 설정 파일에서 대신 sandbox를 켜려면 [`sandbox.enabled`](https://code.claude.com/docs/ko/settings-reference#sandbox-enabled)를 `true`로 설정합니다. |53| 분류기 없이 더 적은 프롬프트로 로컬에서 반복 | Manual 모드 + [auto-allow mode](https://code.claude.com/docs/ko/sandboxing.md#sandbox-modes)의 Bash sandbox: `claude --permission-mode default`, 그 다음 `/sandbox` 실행 및 auto-allow 선택 | 기본 제공 Bash sandbox, macOS, Linux, WSL2 | Deny 규칙은 여전히 적용되고, `Bash(git push *)`와 같이 명령을 지정하는 ask 규칙은 여전히 프롬프트합니다. 확인을 요청할 수 있는 그 밖의 명령은 [Auto-allow mode](https://code.claude.com/docs/ko/sandboxing.md#auto-allow-mode)에서 다룹니다. 설정 파일에서 대신 sandbox를 켜려면 [`sandbox.enabled`](https://code.claude.com/docs/ko/settings-reference#sandbox-enabled)와 [`sandbox.autoAllowBashIfSandboxed`](https://code.claude.com/docs/ko/settings-reference#sandbox-autoallowbashifsandboxed)를 `true`로 설정합니다. |

54| 변경 전에 탐색 | `claude --permission-mode plan` | 없음 | Claude Code는 [계획을 승인](#review-and-approve-a-plan)할 때까지 편집을 차단합니다. |54| 변경 전에 탐색 | `claude --permission-mode plan` | 없음 | Claude Code는 [계획을 승인](#review-and-approve-a-plan)할 때까지 편집을 차단합니다. |

55| auto mode에서 자동 실행 | `claude --permission-mode auto`, [기본 제공 시작 권한 모드](#which-mode-a-session-starts-in) v2.1.283 이상 | 없음; sandbox 또는 컨테이너는 심층 방어를 추가합니다. | [지원되는 모델](#eliminate-prompts-with-auto-mode)이 필요하고, 조직이 [auto mode를 끌 수 있습니다](#eliminate-prompts-with-auto-mode). |55| auto mode에서 자동 실행 | `claude --permission-mode auto`, [기본 제공 시작 권한 모드](#which-mode-a-session-starts-in) v2.1.283 이상 | 없음; sandbox 또는 컨테이너는 심층 방어를 추가합니다. | [지원되는 모델](#eliminate-prompts-with-auto-mode)이 필요하고, 조직이 [auto mode를 끌 수 있습니다](#eliminate-prompts-with-auto-mode). |

56| 정확한 allowlist로 CI에서 실행 | `claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"` | CI 러너가 제공하는 것 이상 없음 | [Cloud sessions](https://code.claude.com/docs/ko/claude-code-on-the-web.md)는 설정 파일의 `dontAsk`를 무시합니다. |56| 정확한 allowlist로 CI에서 실행 | `claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"` | CI 러너가 제공하는 것 이상 없음 | [Cloud sessions](https://code.claude.com/docs/ko/claude-code-on-the-web.md)는 설정 파일의 `dontAsk`를 무시합니다. |

743 743 

744심층 방어를 위해 둘 다 사용합니다. 샌드박스 제한은 프롬프트 주입이 Claude의 의사 결정을 우회하더라도 여전히 적용됩니다. 샌드박스 설정과 권한 규칙의 경로 및 도메인은 [최종 샌드박스 구성으로 병합됩니다](https://code.claude.com/docs/ko/sandboxing.md#permission-rules).744심층 방어를 위해 둘 다 사용합니다. 샌드박스 제한은 프롬프트 주입이 Claude의 의사 결정을 우회하더라도 여전히 적용됩니다. 샌드박스 설정과 권한 규칙의 경로 및 도메인은 [최종 샌드박스 구성으로 병합됩니다](https://code.claude.com/docs/ko/sandboxing.md#permission-rules).

745 745 

746샌드박싱을 활성화하고 `autoAllowBashIfSandboxed`를 기본값인 `true`로 유지하면, 권한에 bare `Bash` ask 규칙이 포함되어 있거나 [동등한 `Bash(*)` 형식](#match-all-uses-of-a-tool)이 포함되어 있어도 샌드박스된 Bash 명령은 프롬프트 없이 실행됩니다. 샌드박스 경계는 전체 도구 프롬프트를 대체합니다.746샌드박싱을 활성화하고 [`sandbox.autoAllowBashIfSandboxed`](https://code.claude.com/docs/ko/settings-reference#sandbox-autoallowbashifsandboxed)를 `true`로 설정하면, 샌드박스된 Bash 명령은 프롬프트 없이 실행됩니다. 이는 bare `Bash` ask 규칙이나 [동등한 `Bash(*)` 형식](#match-all-uses-of-a-tool)이 있는 경우에도 마찬가지입니다. 샌드박스 경계가 해당 전체 도구 프롬프트를 대체합니다.

747 747 

748[플랜 모드](https://code.claude.com/docs/ko/permission-modes.md#analyze-before-you-edit-with-plan-mode)에서 Claude Code는 이 대체를 건너뜁니다. ask 규칙이 없으면 [기본 제공 읽기 전용 명령](#read-only-commands)은 여전히 프롬프트 없이 실행되고, 다른 모든 셸 명령은 계획 중일 때 일반 권한 흐름을 거칩니다. Claude Code가 거기서 명령을 제어하는 방식은 [플랜 모드](https://code.claude.com/docs/ko/permission-modes.md#analyze-before-you-edit-with-plan-mode)를 참조하십시오. bare `Bash` ask 규칙이 있으면 샌드박스된 읽기 전용 명령을 포함한 모든 Bash 명령이 확인을 요청하며, 이는 샌드박싱 외부와 동일합니다.748[플랜 모드](https://code.claude.com/docs/ko/permission-modes.md#analyze-before-you-edit-with-plan-mode)에서 Claude Code는 이 대체를 건너뜁니다. ask 규칙이 없으면 [기본 제공 읽기 전용 명령](#read-only-commands)은 여전히 프롬프트 없이 실행되고, 다른 모든 셸 명령은 계획 중일 때 일반 권한 흐름을 거칩니다. Claude Code가 거기서 명령을 제어하는 방식은 [플랜 모드](https://code.claude.com/docs/ko/permission-modes.md#analyze-before-you-edit-with-plan-mode)를 참조하십시오. bare `Bash` ask 규칙이 있으면 샌드박스된 읽기 전용 명령을 포함한 모든 Bash 명령이 확인을 요청하며, 이는 샌드박싱 외부와 동일합니다.

749 749 

438 438 

439* **`backdrop` 필드**: `scene`은 훅이 그리는 배경에 대해 직접 정하는 [이름](https://code.claude.com/docs/ko/plugins/mods/reference.md#limits)입니다. 다른 필드와 `overrideColorScheme`에 대해서는 [빌드에 맞는 타입](https://code.claude.com/docs/ko/plugins/mods/create.md#get-the-types-for-your-build)을 참조하십시오.439* **`backdrop` 필드**: `scene`은 훅이 그리는 배경에 대해 직접 정하는 [이름](https://code.claude.com/docs/ko/plugins/mods/reference.md#limits)입니다. 다른 필드와 `overrideColorScheme`에 대해서는 [빌드에 맞는 타입](https://code.claude.com/docs/ko/plugins/mods/create.md#get-the-types-for-your-build)을 참조하십시오.

440* **배경이 그려지는지 여부**: 세션에 연결된 Desktop 또는 모바일 앱이 배경을 그린다고 응답하면 `$.theme.set`은 `isDrawn: true`로 resolve됩니다. 그렇지 않으면 `isDrawn`은 `false`이고 `reason`은 그 이유를 설명합니다.440* **배경이 그려지는지 여부**: 세션에 연결된 Desktop 또는 모바일 앱이 배경을 그린다고 응답하면 `$.theme.set`은 `isDrawn: true`로 resolve됩니다. 그렇지 않으면 `isDrawn`은 `false`이고 `reason`은 그 이유를 설명합니다.

441* **세션당 하나의 배경**: `$.theme.set` 호출은 어느 mod가 설정했든 세션의 배경을 대체하고, `$.theme.clear()`는 그 배경을 제거합니다. `$.theme.clear()`는 사용자가 요청할 때만 호출하십시오.441* **세션당 하나의 테마**: `$.theme.set`을 호출하는 mod는 세션의 배경과 [색상](#change-the-colors-of-the-desktop-app)을 대체하고, `$.theme.clear()`를 호출하는 mod는 어느 mod가 설정했든 이를 제거합니다. `$.theme.clear()`는 사용자가 요청할 때만 호출하십시오.

442 

443### Desktop 앱의 색상 변경하기

444 

445mod로 Desktop 앱의 Code 탭 색상을 변경하려면 [Claude에게 mod를 요청](#ask-claude-for-a-colors-mod)하거나 [직접 작성](#write-a-colors-mod-yourself)합니다. 두 방법 모두 Code 탭에서 Claude Code v2.1.324 이상이 필요하므로 먼저 [그곳에서 버전을 확인](https://code.claude.com/docs/ko/desktop.md#claude-code-version-in-the-code-tab)하십시오. 터미널의 Claude Code는 자체 색상을 유지합니다.

446 

447#### Claude에게 색상 mod 요청하기

448 

449**1. 색상 설명하기**

450 

451Code 탭에서 로컬 세션을 시작하고 원하는 색상을 Claude에게 알려 줍니다. 예를 들어 `make a mod that makes the app cream in light mode and dark brown in dark mode`를 입력합니다. Claude가 mod의 파일을 작성합니다.

452 

453**2. mod 승인하기**

454 

455mod의 파일과 핫 리로드에 대해 Claude Code가 묻는 질문에 답합니다. 각 답변의 동작은 [Claude에게 mod 요청하기](https://code.claude.com/docs/ko/plugins/mods/create.md#ask-claude-for-a-mod)를 참조하십시오.

456 

457**3. 색상 확인하기**

458 

459mod가 로드되면 Code 탭의 색상이 바뀝니다. 색상을 조정하려면 변경할 내용을 Claude에게 알려 줍니다. 아무것도 바뀌지 않으면 [누락된 mod 색상 문제 해결하기](#fix-missing-mod-colors-in-the-desktop-app)를 참조하십시오.

460 

461#### 색상 mod 직접 작성하기

462 

463`makeColors`는 몇 가지 16진수 색상으로 테마를 만드는 함수입니다. 다음 단계에서는 이 함수를 사용하는 `paper`라는 mod를 만듭니다.

464 

465**1. Claude에게 makeColors 복사 요청하기**

466 

467Code 탭에서 로컬 세션을 시작하고 `copy make-colors.js and make-colors.d.ts from your plugin-authoring skill into ~/.claude/skills/paper/hooks/`를 입력합니다. 두 파일이 해당 디렉터리에 있는지 확인합니다.

468 

469**2. 매니페스트와 hooks.json 저장하기**

470 

471[직접 mod 작성하기](https://code.claude.com/docs/ko/plugins/mods/create.md#write-a-mod-yourself)에 나온 `.claude-plugin/plugin.json`과 `hooks/hooks.json`을 `~/.claude/skills/paper/`에 저장하고, 두 파일에서 `first-mod`를 `paper`로 변경합니다. [`~/.claude/skills/` 아래에 있는](https://code.claude.com/docs/ko/plugins/create#scaffold-a-plugin-that-loads-every-session) mod는 세션을 시작할 때 로드됩니다.

472 

473**3. 코드 작성하기**

474 

475다음 파일을 `~/.claude/skills/paper/hooks/register.js`로 저장합니다. 세션이 시작되면 이 코드는 라이트 모드와 다크 모드의 색상으로 `$.theme.set`을 호출합니다.

476 

477```javascript theme={null}

478import { makeColors } from './make-colors.js'

479 

480const { theme } = makeColors({

481 label: 'Paper',

482 // surface-0 is the background, text-primary is the main text, and text-muted is the faint text

483 light: {

484 gray: { anchors: { 'surface-0': '#efe6d3', 'text-primary': '#2a241d', 'text-muted': '#6a5f50' } },

485 },

486 dark: {

487 gray: { anchors: { 'surface-0': '#1f1a15', 'text-primary': '#f0e7d7', 'text-muted': '#aca08d' } },

488 },

489})

490 

491export function register(on) {

492 on('session.start', async ($, e, next) => {

493 await $.theme.set({ colors: theme })

494 return next(e)

495 })

496}

497```

498 

499원하는 색상을 사용하려면 16진수 값을 다른 6자리 16진수 색상으로 바꾸십시오.

500 

501**4. 색상 확인하기**

502 

503Code 탭에서 새 로컬 세션을 시작합니다. 예제의 값을 사용하면 배경이 라이트 모드에서는 크림색, 다크 모드에서는 짙은 갈색으로 표시됩니다. 아무것도 바뀌지 않으면 [누락된 mod 색상 문제 해결하기](#fix-missing-mod-colors-in-the-desktop-app)를 참조하십시오.

504 

505### Desktop 앱에서 누락된 mod 색상 문제 해결하기

506 

507[Claude Desktop v5.11492.5 이하](https://code.claude.com/docs/ko/desktop.md#check-your-version)에서 Claude 계정 대신 [서드 파티 제공업체](https://code.claude.com/docs/ko/third-party-integrations.md)를 사용하는 경우 Code 탭은 자체 색상을 유지하므로 다음 확인 사항을 건너뛰십시오. 그 외의 경우 mod의 색상이 Code 탭에 나타나지 않거나 사라지면 다음 원인을 확인하십시오.

508 

509* **이전 버전**: [Desktop 앱을 업데이트](https://code.claude.com/docs/ko/desktop.md#claude-code-version-in-the-code-tab)하고 다시 시작한 다음 Code 탭에서 새 로컬 세션을 시작합니다. Claude가 mod를 작성했다면 그 세션에서 다시 요청하십시오.

510* **mod가 로드되지 않음**: Claude가 mod를 작성했다면 [Claude에게 mod 요청하기](https://code.claude.com/docs/ko/plugins/mods/create.md#ask-claude-for-a-mod)에서 mod가 로드되는 시점을 확인하십시오. 직접 작성했다면 파일과 경로를 [색상 mod 직접 작성하기](#write-a-colors-mod-yourself)와 비교하십시오.

511* **거부된 테마**: Claude에게 mod의 [`makeColors`](#write-a-colors-mod-yourself) 호출을 실행해 달라고 요청하십시오. 호출에서 오류가 발생하거나 `problems` 목록에 `Desktop won't paint this theme`로 시작하는 항목이 있으면 Claude가 테마를 수정하도록 하십시오. mod를 설치한 경우에는 Claude가 찾은 내용을 mod 작성자에게 보내십시오.

512* **다른 `$.theme` 호출**: 세션의 어떤 mod든 `$.theme.set` 또는 `$.theme.clear()`를 호출하면 이전 호출의 색상과 [배경](#put-a-backdrop-behind-the-conversation)이 사라집니다. 직접 작성한 mod에서는 `colors`와 `backdrop`을 같은 `$.theme.set` 호출에 전달하십시오. 테마를 설정하는 mod는 한 번에 하나만 사용하십시오.

513 

514### Desktop 앱에서 mod 색상 제거하기

515 

516Code 탭에서 mod의 색상을 없애려면 먼저 mod를 끄십시오. 켜져 있는 mod는 색상을 다시 설정할 수 있습니다.

517 

518**1. mod 끄기**

519 

520* **Claude가 mod를 작성한 경우**: Claude가 mod를 작성한 세션의 [mod 폴더](https://code.claude.com/docs/ko/plugins/mods/create.md#ask-claude-for-a-mod) 밖으로 mod의 디렉터리를 옮깁니다.

521* **mod를 `~/.claude/skills/` 아래에 둔 경우**: `~/.claude/skills/paper/`와 같은 mod의 디렉터리를 `~/.claude/skills/` 밖의 위치로 옮깁니다.

522* **mod를 설치한 경우**: Desktop 앱의 **Manage plugins**에서 [해당 플러그인을 비활성화하거나 제거](https://code.claude.com/docs/ko/desktop.md#install-plugins)합니다. **Manage plugins**가 보이지 않고 [CLI](https://code.claude.com/docs/ko/quickstart.md)가 있다면 [셸에서 마켓플레이스 플러그인을 비활성화하거나 제거](https://code.claude.com/docs/ko/plugins/install.md#manage-plugins-from-your-shell)할 수 있습니다.

523 

524**2. 새 세션 시작하기**

525 

526Code 탭에서 새 로컬 세션을 시작합니다.

527 

528**3. 남아 있는 색상 제거하기**

529 

530색상이 여전히 남아 있으면 Code 탭에서 **Settings**를 열고 그곳에서 `code appearance`를 검색합니다. 결과를 열고 **Remove colors**를 선택합니다.

442 531 

443## 요소로 트리 만들기532## 요소로 트리 만들기

444 533 

677 766 

678같은 키를 누르거나, 전체 화면 렌더링에서 이 행을 클릭하면 밴드가 다시 펼쳐집니다. 그때까지는 밴드 안의 버튼을 누르는 방법이 없습니다. 단축키, 빈 프롬프트에 입력한 숫자, 버튼의 [`action`](https://code.claude.com/docs/ko/plugins/mods/reference#elements)에 대한 키보드 단축키 모두 동작하지 않습니다. 사용자가 밴드를 접을 때 밴드에 키보드 포커스가 있었다면 포커스는 프롬프트로 돌아가며, 밴드가 접혀 있는 동안 Ctrl+X 다음 Tab은 밴드를 건너뜁니다.767같은 키를 누르거나, 전체 화면 렌더링에서 이 행을 클릭하면 밴드가 다시 펼쳐집니다. 그때까지는 밴드 안의 버튼을 누르는 방법이 없습니다. 단축키, 빈 프롬프트에 입력한 숫자, 버튼의 [`action`](https://code.claude.com/docs/ko/plugins/mods/reference#elements)에 대한 키보드 단축키 모두 동작하지 않습니다. 사용자가 밴드를 접을 때 밴드에 키보드 포커스가 있었다면 포커스는 프롬프트로 돌아가며, 밴드가 접혀 있는 동안 Ctrl+X 다음 Tab은 밴드를 건너뜁니다.

679 768 

680밴드는 사용자가 펼칠 때까지 `/clear` 이후에도 접힌 상태로 유지되며, 다음에 Claude Code가 시작될 때 다시 펼쳐집니다. mod는 밴드를 펼칠 수 없고 밴드가 접혀 있는지도 알 수 없습니다. `ui.render` 훅은 계속 실행되며, `e.props`에는 이를 나타내는 내용이 없습니다. 사용자가 응답해야 하는 내용을 mod가 표시하는 유일한 위치로 밴드를 사용하지 마십시오.769밴드는 사용자가 펼칠 때까지 `/clear` 이후에도 접힌 상태로 유지되며, 다음에 Claude Code가 시작될 때 다시 펼쳐집니다. mod는 밴드를 펼칠 수 없습니다. 사용자가 응답해야 하는 내용을 mod가 표시하는 유일한 위치로 밴드를 사용하지 마십시오. 밴드가 접혀 있는 동안에만 그 내용을 다른 곳에 표시하려면, 계속 실행되는 `ui.render` 훅에서 `e.props.isCollapsed`를 읽습니다. `isCollapsed`에는 Claude Code v2.1.321 이상이 필요합니다.

681 770 

682### 입력을 받고 항목마다 행 그리기771### 입력을 받고 항목마다 행 그리기

683 772 

212 212 

213이 이벤트 중 일부는 Claude Code 자체의 동작에 대해서도 발생하므로, 이벤트를 거부하기 전에 `next.origin.plugin`이 `engine`인지 확인하세요.213이 이벤트 중 일부는 Claude Code 자체의 동작에 대해서도 발생하므로, 이벤트를 거부하기 전에 `next.origin.plugin`이 `engine`인지 확인하세요.

214 214 

215#### Claude Code 자체 `http.fetch` 요청의 필드

216 

217`http.fetch` 훅에서 `{ plugin: 'engine', tier: 'core' }`인 [`next.origin`](#the-hook-function)은 mod의 `$.http.fetch` 호출이 아니라 모델 요청과 같은 Claude Code 자체 요청임을 나타냅니다. [기본 제공 가드](https://code.claude.com/docs/ko/plugins/mods/admin.md#know-what-happens-by-default)가 로드된 환경에서는 mod가 [조직의 mod로 간주되는](https://code.claude.com/docs/ko/plugins/mods/admin.md#install-your-organizations-mods) 경우를 제외하고 훅이 이러한 이벤트를 받지 않습니다.

218 

219이러한 이벤트에서 `e.init`과 `next(e)`가 확정하는 `value`에는 특히 다음 필드가 포함될 수 있습니다.

220 

221| 필드 | 의미 |

222| :- | :- |

223| `e.init.compress` | Claude Code가 훅 이후에 본문을 압축할 때 설정됩니다. `e.init.body`에는 압축되지 않은 본문이 담깁니다. 본문을 압축하지 않고 전송하려면 `next({ ...e, init: { ...e.init, compress: undefined } })`를 호출합니다. |

224| `value.isStreaming` | Claude Code가 응답 본문을 직접 읽기 때문에 `true`로 설정되며, 따라서 `value.text`는 비어 있습니다. 대신 `value.status`와 `value.headers`를 읽으세요. 직접 작성한 `text`로 응답하려면 `isStreaming` 없이 `value`를 반환합니다. |

225 

226이러한 이벤트와 필드를 사용하려면 Claude Code v2.1.321 이상이 필요합니다.

227 

215## Mods API 메서드228## Mods API 메서드

216 229 

217mods API는 모든 훅이 받는 `$` 인수입니다. 이 API의 메서드는 `$.ui`와 같은 네임스페이스로 그룹화되어 있습니다. 이 표는 각 네임스페이스의 메서드를 이름별로 나열하므로, `$.ui` 행의 `open`은 `$.ui.open(...)` 호출을 의미합니다. 가이드에서는 자주 쓰이는 메서드의 사용 예를 보여 주며, [사용 중인 빌드의 타입](https://code.claude.com/docs/ko/plugins/mods/create.md#get-the-types-for-your-build)에는 모든 메서드가 예제와 함께 문서화되어 있습니다.230mods API는 모든 훅이 받는 `$` 인수입니다. 이 API의 메서드는 `$.ui`와 같은 네임스페이스로 그룹화되어 있습니다. 이 표는 각 네임스페이스의 메서드를 이름별로 나열하므로, `$.ui` 행의 `open`은 `$.ui.open(...)` 호출을 의미합니다. 가이드에서는 자주 쓰이는 메서드의 사용 예를 보여 주며, [사용 중인 빌드의 타입](https://code.claude.com/docs/ko/plugins/mods/create.md#get-the-types-for-your-build)에는 모든 메서드가 예제와 함께 문서화되어 있습니다.

222| [`$.ui`](https://code.claude.com/docs/ko/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, [`place`](https://code.claude.com/docs/ko/plugins/mods/interface#place-a-row-in-the-transcript), `focus`, `scroll`, `toast`, `notify`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit`, `view`. `view`에는 Claude Code v2.1.300 이상이, `place`에는 v2.1.314 이상이 필요합니다. |235| [`$.ui`](https://code.claude.com/docs/ko/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, [`place`](https://code.claude.com/docs/ko/plugins/mods/interface#place-a-row-in-the-transcript), `focus`, `scroll`, `toast`, `notify`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit`, `view`. `view`에는 Claude Code v2.1.300 이상이, `place`에는 v2.1.314 이상이 필요합니다. |

223| [`$.theme`](https://code.claude.com/docs/ko/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `set`, `clear`: Desktop 또는 모바일 앱이 그릴 배경을 설정하고, 배경을 제거합니다. Claude Code v2.1.319 이상이 필요합니다. |236| [`$.theme`](https://code.claude.com/docs/ko/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `set`, `clear`: Desktop 또는 모바일 앱이 그릴 배경을 설정하고, 배경을 제거합니다. Claude Code v2.1.319 이상이 필요합니다. |

224| [`$.command`](https://code.claude.com/docs/ko/plugins/mods/api#add-a-command) | `register`, `run`, `list` |237| [`$.command`](https://code.claude.com/docs/ko/plugins/mods/api#add-a-command) | `register`, `run`, `list` |

225| [`$.tool`](https://code.claude.com/docs/ko/plugins/mods/api#add-a-tool) | `register`, `call`, `check`, `list` |238| [`$.tool`](https://code.claude.com/docs/ko/plugins/mods/api#add-a-tool) | `register`, `call`, `check`, `list`. 훅이나 조직이 `ask`로 응답하는 호출처럼 `call`에 사람의 승인이 필요한 경우, `{ deny: "<tool> wasn't run: this call needs a person's approval, and a mod's own call can't ask for it." }`로 resolve되며, 여기서 `<tool>`은 도구의 이름입니다. |

226| `$.agent` | `register`, `spawn`, `list`. `list()`는 이 세션의 서브에이전트와 팀원을 반환하며, 각 항목의 `status`는 `pending`, `running`, `waiting`, `idle`, `completed`, `failed`, `killed` 중 하나입니다. 이 중 `idle`과 `waiting`에는 Claude Code v2.1.289 이상이 필요합니다. |239| `$.agent` | `register`, `spawn`, `list`. `list()`는 이 세션의 서브에이전트와 팀원을 반환하며, 각 항목의 `status`는 `pending`, `running`, `waiting`, `idle`, `completed`, `failed`, `killed` 중 하나입니다. 이 중 `idle`과 `waiting`에는 Claude Code v2.1.289 이상이 필요합니다. |

227| [`$.model`](https://code.claude.com/docs/ko/plugins/mods/api#call-a-model) | `complete`, `fork`, `classify` |240| [`$.model`](https://code.claude.com/docs/ko/plugins/mods/api#call-a-model) | `complete`, `fork`, `classify` |

228| [`$.prompt`](https://code.claude.com/docs/ko/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`, `read`, `fill`, `suggest`, `compose`. Claude는 해당 mod를 발신자로 명시하는 문장 뒤에 오는 `submit({ text })`의 텍스트를 읽습니다. `submit({ text, asUser: true })`는 그 문장 없이 텍스트를 사용자 본인의 말로 보냅니다. |241| [`$.prompt`](https://code.claude.com/docs/ko/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`, `read`, `fill`, `suggest`, `compose`. Claude는 해당 mod를 발신자로 명시하는 문장 뒤에 오는 `submit({ text })`의 텍스트를 읽습니다. `submit({ text, asUser: true })`는 그 문장 없이 텍스트를 사용자 본인의 말로 보냅니다. |

250| 지점 | `e.props` | `e.requestId` | 렌더링 위치 |263| 지점 | `e.props` | `e.requestId` | 렌더링 위치 |

251| :- | :- | :- | :- |264| :- | :- | :- | :- |

252| [`Pane`](https://code.claude.com/docs/ko/plugins/mods/interface#pick-where-to-draw) | `title`, `isFocused`, `bodyColumns`, `placement`, `scroll`, `view` | 창의 `id` | 터미널, Desktop, VS Code |265| [`Pane`](https://code.claude.com/docs/ko/plugins/mods/interface#pick-where-to-draw) | `title`, `isFocused`, `bodyColumns`, `placement`, `scroll`, `view` | 창의 `id` | 터미널, Desktop, VS Code |

253| [`AbovePrompt`](https://code.claude.com/docs/ko/plugins/mods/interface#pick-where-to-draw) | `hasSurvey`, `isWorking`, `maxRows`, `bodyColumns`, `scroll`, `view` | 단일 인스턴스 | 터미널, Desktop |266| [`AbovePrompt`](https://code.claude.com/docs/ko/plugins/mods/interface#pick-where-to-draw) | `hasSurvey`, [`isCollapsed`](https://code.claude.com/docs/ko/plugins/mods/interface#when-the-user-collapses-the-band), `isWorking`, `maxRows`, `bodyColumns`, `scroll`, `view` | 단일 인스턴스 | 터미널, Desktop |

254| `AbovePromptList`, 즉 `AbovePrompt` 행의 스택 | 각 mod의 행마다 `{ plugin, tree }` 하나씩을 담은 목록인 `rows`, 그리고 `AbovePrompt` prop | 단일 인스턴스 | 터미널, Desktop. Claude Code v2.1.323 이상이 필요합니다. |267| `AbovePromptList`, 즉 `AbovePrompt` 행의 스택 | 각 mod의 행마다 `{ plugin, tree }` 하나씩을 담은 목록인 `rows`, 그리고 `AbovePrompt` prop | 단일 인스턴스 | 터미널, Desktop. Claude Code v2.1.323 이상이 필요합니다. |

255| [`Placed`](https://code.claude.com/docs/ko/plugins/mods/interface#place-a-row-in-the-transcript) | `id`, `plugin`, `onScreen` | `$.ui.place`가 반환한 `requestId` | 터미널 |268| [`Placed`](https://code.claude.com/docs/ko/plugins/mods/interface#place-a-row-in-the-transcript) | `id`, `plugin`, `onScreen` | `$.ui.place`가 반환한 `requestId` | 터미널 |

256| [`Backdrop`](https://code.claude.com/docs/ko/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `scene`, `plugin`, `glass`, `overrideColorScheme`. v2.1.323 이전에는 `scene`이 `id`였고 `overrideColorScheme`이 `colorScheme`이었습니다. | `backdrop` | `desktop` 및 `mobile` 사용 환경. Desktop 또는 모바일 앱이 배경 그리기를 요청할 때 훅이 실행됩니다. |269| [`Backdrop`](https://code.claude.com/docs/ko/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `scene`, `plugin`, `glass`, `overrideColorScheme`. v2.1.323 이전에는 `scene`이 `id`였고 `overrideColorScheme`이 `colorScheme`이었습니다. | `backdrop` | `desktop` 및 `mobile` 사용 환경. Desktop 또는 모바일 앱이 배경 그리기를 요청할 때 훅이 실행됩니다. |

426| 이름 | 위치 | 기능 |439| 이름 | 위치 | 기능 |

427| :- | :- | :- |440| :- | :- | :- |

428| `CLAUDE_CODE_PLUGIN_DIRS` | 환경, 또는 `~/.claude/settings.json`의 `env` | 플래그를 전달할 수 없는 앱을 위해 `--plugin-dir`와 같은 방식으로 로드할 플러그인 디렉터리입니다. 절대 경로를 `:`로 구분하며, Windows에서는 `;`로 구분합니다. |441| `CLAUDE_CODE_PLUGIN_DIRS` | 환경, 또는 `~/.claude/settings.json`의 `env` | 플래그를 전달할 수 없는 앱을 위해 `--plugin-dir`와 같은 방식으로 로드할 플러그인 디렉터리입니다. 절대 경로를 `:`로 구분하며, Windows에서는 `;`로 구분합니다. |

429| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 환경 | `1`로 설정하면 장시간 실행되는 비대화형 세션이 저장 시 `--plugin-dir` mod를 다시 로드합니다 |442| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 환경 | 저장 시 mod를 다시 로드할지 여부입니다. 기본값과 값은 [환경 변수 참조](https://code.claude.com/docs/ko/env-vars.md)를 참조하세요 |

430| `prependPlugins`, `appendPlugins` | 관리형 설정. 관리형 설정 또는 [`managed-mcp.json`](https://code.claude.com/docs/ko/managed-mcp#deploy-managed-mcp-json) 파일이 없는 머신에서, 자격 증명이 Team 또는 Enterprise `/login`이 아닌 세션에서만 사용자 설정. | `acme-guard@acme-tools`와 같은 플러그인 ID 목록입니다. `prependPlugins`의 mod는 사용자가 설치한 모든 mod보다 먼저 실행되고, `appendPlugins`의 mod는 그 후에 나열된 순서대로 실행됩니다. [mod 실행 순서](https://code.claude.com/docs/ko/plugins/mods/events.md#the-order-mods-run-in)를 참조하세요. |443| `prependPlugins`, `appendPlugins` | 관리형 설정. 관리형 설정 또는 [`managed-mcp.json`](https://code.claude.com/docs/ko/managed-mcp#deploy-managed-mcp-json) 파일이 없는 머신에서, 자격 증명이 Team 또는 Enterprise `/login`이 아닌 세션에서만 사용자 설정. | `acme-guard@acme-tools`와 같은 플러그인 ID 목록입니다. `prependPlugins`의 mod는 사용자가 설치한 모든 mod보다 먼저 실행되고, `appendPlugins`의 mod는 그 후에 나열된 순서대로 실행됩니다. [mod 실행 순서](https://code.claude.com/docs/ko/plugins/mods/events.md#the-order-mods-run-in)를 참조하세요. |

431| `allowManagedModsOnly` | 관리형 설정, [기본 제공 가드의 옵션](https://code.claude.com/docs/ko/plugins/mods/admin.md#set-options-on-the-built-in-guard)으로 설정 | [조직의 mod로 간주되는](https://code.claude.com/docs/ko/plugins/mods/admin.md#install-your-organizations-mods) mod와 Claude Code에 기본 제공되는 mod만 훅을 실행합니다. 사용자의 설정 훅은 계속 실행됩니다. |444| `allowManagedModsOnly` | 관리형 설정, [기본 제공 가드의 옵션](https://code.claude.com/docs/ko/plugins/mods/admin.md#set-options-on-the-built-in-guard)으로 설정 | [조직의 mod로 간주되는](https://code.claude.com/docs/ko/plugins/mods/admin.md#install-your-organizations-mods) mod와 Claude Code에 기본 제공되는 mod만 훅을 실행합니다. 사용자의 설정 훅은 계속 실행됩니다. |

432| `allowModsToOverrideDenyRules` | 관리형 설정, [기본 제공 가드의 옵션](https://code.claude.com/docs/ko/plugins/mods/admin.md#set-options-on-the-built-in-guard)으로 설정 | 사용자가 설치한 mod가 `deny` 규칙을 포함하여 [기본적으로 유지되는 결과](https://code.claude.com/docs/ko/permissions.md#precedence-among-rules-hooks-and-mods) 대부분을 무시하고 도구 호출을 승인할 수 있도록 합니다 |445| `allowModsToOverrideDenyRules` | 관리형 설정, [기본 제공 가드의 옵션](https://code.claude.com/docs/ko/plugins/mods/admin.md#set-options-on-the-built-in-guard)으로 설정 | 사용자가 설치한 mod가 `deny` 규칙을 포함하여 [기본적으로 유지되는 결과](https://code.claude.com/docs/ko/permissions.md#precedence-among-rules-hooks-and-mods) 대부분을 무시하고 도구 호출을 승인할 수 있도록 합니다 |

115 115 

116### 테스트 키트의 규칙 따르기116### 테스트 키트의 규칙 따르기

117 117 

118테스트 키트에는 자체 규칙이 몇 가지 있으며, 이를 어기면 테스트를 처음 작성하는 사용자가 가장 먼저 마주치는 오류가 발생합니다.

119 

120* **테스트에서 `$`를 처음 호출하기 전에 모든 스텁을 등록합니다.** 그 이후에 `on`을 호출하면 `on("ui.render") after the test first called $` 같은 오류가 발생합니다.118* **테스트에서 `$`를 처음 호출하기 전에 모든 스텁을 등록합니다.** 그 이후에 `on`을 호출하면 `on("ui.render") after the test first called $` 같은 오류가 발생합니다.

121 119 

122* **[`session.start`](https://code.claude.com/docs/ko/plugins/mods/reference#session)는 자동으로 실행되지 않습니다.** 각 테스트는 모듈이 새로 로드되고 어떤 훅도 호출되지 않은 상태로 시작하므로, 모듈 수준 변수는 초기값을 유지합니다. 훅이 `session.start`에서 설정하는 내용에 의존한다면 먼저 이 이벤트를 발생시킵니다.120* **[`session.start`](https://code.claude.com/docs/ko/plugins/mods/reference#session)는 자동으로 실행되지 않습니다.** 각 테스트는 모듈이 새로 로드되고 어떤 훅도 호출되지 않은 상태로 시작하므로, 모듈 수준 변수는 초기값을 유지합니다. 훅이 `session.start`에서 설정하는 내용에 의존한다면 먼저 이 이벤트를 발생시킵니다.

132 130 

133 두 번째 스텁은 [튜토리얼의](https://code.claude.com/docs/ko/plugins/mods/create.md#write-a-mod-yourself) 훅 같은 `session.start` 훅이 하는 `$.command.register` 호출에 응답합니다. 이 스텁이 없으면 해당 호출이 `no implementation for command.register`로 reject되고 키트가 훅을 건너뛰므로, 훅에서 그 호출 이후의 내용은 실행되지 않습니다. 이 시점에 테스트가 실패하지는 않습니다. 건너뛴 훅은 이후의 검사가 실패할 때만 `the engine reported:` 아래에 표시됩니다.131 두 번째 스텁은 [튜토리얼의](https://code.claude.com/docs/ko/plugins/mods/create.md#write-a-mod-yourself) 훅 같은 `session.start` 훅이 하는 `$.command.register` 호출에 응답합니다. 이 스텁이 없으면 해당 호출이 `no implementation for command.register`로 reject되고 키트가 훅을 건너뛰므로, 훅에서 그 호출 이후의 내용은 실행되지 않습니다. 이 시점에 테스트가 실패하지는 않습니다. 건너뛴 훅은 이후의 검사가 실패할 때만 `the engine reported:` 아래에 표시됩니다.

134 132 

135* **`next(e)`를 반환하는 훅에는 응답할 스텁이 필요합니다.** 예를 들어 Claude가 유휴 상태일 때 아무것도 그리지 않도록 [`ui.render`](https://code.claude.com/docs/ko/plugins/mods/reference#interface) 훅이 `next(e)`를 반환하면, [마운트](#test-a-drawing)가 `no implementation for ui.render`로 실패합니다. 요소를 일반 데이터로 반환하는 스텁을 등록합니다.133* **`next(e)`가 반환할 값을 선택하려면 `ui.render` 스텁을 등록합니다.** 예를 들어 Claude가 유휴 상태일 때 아무것도 그리지 않도록 [`ui.render`](https://code.claude.com/docs/ko/plugins/mods/reference#interface) 훅이 `next(e)`를 반환하는 경우, 스텁이 없어도 [마운트](#test-a-drawing)는 성공합니다. `next(e)`가 직접 고른 요소를 반환하게 하려면, 그 요소를 일반 데이터로 반환하는 스텁을 등록합니다.

136 134 

137 ```typescript theme={null}135 ```typescript theme={null}

138 // Stands for what Claude Code would draw at the site136 // Stands for what Claude Code would draw at the site

139 on('ui.render', () => ({ type: 'Text', props: {}, children: ['drawn by Claude Code'] }))137 on('ui.render', () => ({ type: 'Text', props: {}, children: ['drawn by Claude Code'] }))

140 ```138 ```

141 139 

142 스텁을 등록하면 마운트가 성공하며, 훅이 `next(e)`를 반환할 때마다 `ui.find({ type: 'Text' })`가 그 요소를 반환합니다. v2.1.323 이상에서 밴드의 경우, `{ plugin: 'my-mod' }`처럼 mod 이름을 `on`의 두 번째 인수로 전달합니다. 이 인수가 없으면 스텁이 `next(e)`에 응답하지 않습니다.140 해당 사이트가 [그 요소를 그릴 수 있는](https://code.claude.com/docs/ko/plugins/mods/interface.md#change-what-claude-code-already-draws) 경우, 훅이 `next(e)`를 반환했다면 `ui.find({ type: 'Text' })`가 그 요소를 반환합니다. v2.1.323 이상에서 밴드의 경우, `{ plugin: 'my-mod' }`처럼 mod 이름을 `on`의 두 번째 인수로 전달합니다. 이 인수가 없으면 스텁이 `next(e)`에 응답하지 않습니다. v2.1.321 이전에는 스텁을 등록하지 않으면 마운트가 `no implementation for ui.render`로 실패합니다.

143 141 

144* **`turn.step`에 대한 스텁은 비동기 제너레이터**이며, 테스트는 결과를 얻기 위해 스트림을 끝까지 읽습니다.142* **`turn.step`에 대한 스텁은 비동기 제너레이터**이며, 테스트는 결과를 얻기 위해 스트림을 끝까지 읽습니다.

145 143 

316| `press({ key: 'more' })` | 해당 키를 가진 `Button`을 누릅니다 |314| `press({ key: 'more' })` | 해당 키를 가진 `Button`을 누릅니다 |

317| `input({ key: 'new-note', text: 'buy milk' })` | 해당 키를 가진 `Input`에 텍스트를 입력하고 Enter를 누릅니다. 제출하지 않고 입력만 하려면 `kind: 'change'`를 추가합니다. `rows`가 있는 필드의 경우 텍스트에 `\n`을 포함할 수 있습니다. |315| `input({ key: 'new-note', text: 'buy milk' })` | 해당 키를 가진 `Input`에 텍스트를 입력하고 Enter를 누릅니다. 제출하지 않고 입력만 하려면 `kind: 'change'`를 추가합니다. `rows`가 있는 필드의 경우 텍스트에 `\n`을 포함할 수 있습니다. |

318| `select({ key: 'size', value: 'large' })` | 해당 키를 가진 `Select`에서 해당 값을 가진 옵션을 선택합니다 |316| `select({ key: 'size', value: 'large' })` | 해당 키를 가진 `Select`에서 해당 값을 가진 옵션을 선택합니다 |

317| `keepsBeneath()` | `ui.render` 스텁이 없는 테스트에서는 그린 내용에 `next(e)`가 반환한 내용이 포함되어 있으면 `true`로, 훅이 이를 제외했으면 `false`로 resolve됩니다. 스텁을 등록하는 테스트에서는 `find`를 사용해 스텁이 그린 내용을 찾습니다. Claude Code v2.1.321 이상이 필요합니다. |

319| `find({ key: 'more' })` 또는 `find({ type: 'Text', text: 'Count: 2' })` | 처음으로 일치하는 요소를 `{ type, props, children }` 형태로 반환하거나, `undefined`를 반환합니다. `text`는 문자열 또는 정규 표현식일 수 있습니다. |318| `find({ key: 'more' })` 또는 `find({ type: 'Text', text: 'Count: 2' })` | 처음으로 일치하는 요소를 `{ type, props, children }` 형태로 반환하거나, `undefined`를 반환합니다. `text`는 문자열 또는 정규 표현식일 수 있습니다. |

320| `unmount()` | 그린 내용을 제거합니다 |319| `unmount()` | 그린 내용을 제거합니다 |

321 320 

41 41 

42| 원하는 작업 | 시작 위치 |42| 원하는 작업 | 시작 위치 |

43| :- | :- |43| :- | :- |

44| 자신의 머신에서 일상 작업 중 권한 프롬프트 감소 | [샌드박스 Bash 도구](https://code.claude.com/docs/ko/sandboxing.md), `/sandbox`로 구성 |44| 자신의 머신에서 일상 작업 중 권한 프롬프트 감소 | 자동 허용 모드의 [샌드박스 Bash 도구](https://code.claude.com/docs/ko/sandboxing.md), `/sandbox`로 구성 |

45| Claude가 `--dangerously-skip-permissions` 또는 자동 모드로 무인 작동 | 사전 구성된 [개발 컨테이너](https://code.claude.com/docs/ko/devcontainer.md), 모든 컨테이너 또는 VM, 또는 [샌드박스 런타임](#sandbox-runtime) |45| Claude가 `--dangerously-skip-permissions` 또는 자동 모드로 무인 작동 | 사전 구성된 [개발 컨테이너](https://code.claude.com/docs/ko/devcontainer.md), 모든 컨테이너 또는 VM, 또는 [샌드박스 런타임](#sandbox-runtime) |

46| Docker 없이 MCP 서버 및 훅과 Bash 격리 | 샌드박스 런타임 |46| Docker 없이 MCP 서버 및 훅과 Bash 격리 | 샌드박스 런타임 |

47| 팀 전체에서 샌드박스 환경 표준화 | 사전 구성된 [개발 컨테이너](https://code.claude.com/docs/ko/devcontainer.md), 저장소에 복사됨 |47| 팀 전체에서 샌드박스 환경 표준화 | 사전 구성된 [개발 컨테이너](https://code.claude.com/docs/ko/devcontainer.md), 저장소에 복사됨 |

6 6 

7> 기본 제공 샌드박스로 Claude Code의 셸 명령이 접근할 수 있는 파일과 네트워크 호스트를 제한합니다. 샌드박스를 켜고, 경계를 설정하고, 샌드박스로 인해 발생하는 문제를 해결합니다.7> 기본 제공 샌드박스로 Claude Code의 셸 명령이 접근할 수 있는 파일과 네트워크 호스트를 제한합니다. 샌드박스를 켜고, 경계를 설정하고, 샌드박스로 인해 발생하는 문제를 해결합니다.

8 8 

9Bash 샌드박스는 Claude가 사용자의 머신에서 실행하는 셸 명령 주위에 운영 체제가 적용하는 경계입니다. 이러한 명령이 접근할 수 있는 파일과 네트워크 도메인을 설정할 수 있으며, 이 제한은 Bash, PowerShell, Monitor 명령과 이들이 시작하는 프로세스에 적용됩니다. 명령이 실행되는 동안 운영 체제가 제한을 적용하므로, Claude Code는 각 명령마다 승인을 요청하지 않고 [샌드박스 명령을 실행](#sandbox-modes)할 수 있습니다.9Bash 샌드박스는 Claude가 사용자의 머신에서 실행하는 셸 명령 주위에 운영 체제가 적용하는 경계입니다. 이러한 명령이 접근할 수 있는 파일과 네트워크 도메인을 설정할 수 있으며, 이 제한은 Bash, PowerShell, Monitor 명령과 이들이 시작하는 프로세스에 적용됩니다. 샌드박스 명령도 일반 권한 흐름을 거칩니다. 단, 확인을 요청하지 않고 명령을 실행할 수 있는 [자동 허용 모드](#sandbox-modes)를 선택한 경우는 예외입니다.

10 10 

11샌드박스는 셸 명령에만 적용됩니다. Claude의 파일 도구, MCP 서버, 훅은 [샌드박스 외부에서 실행됩니다](#what-runs-outside-the-sandbox).11샌드박스는 셸 명령에만 적용됩니다. Claude의 파일 도구, MCP 서버, 훅은 [샌드박스 외부에서 실행됩니다](#what-runs-outside-the-sandbox).

12 12 

340 340 

341* [읽기 전용 명령](https://code.claude.com/docs/ko/permissions.md#read-only-commands)과 허용 규칙에 포함된 명령은 프롬프트 없이 실행됩니다341* [읽기 전용 명령](https://code.claude.com/docs/ko/permissions.md#read-only-commands)과 허용 규칙에 포함된 명령은 프롬프트 없이 실행됩니다

342* 자동 모드에서는 분류기가 그 외의 제외된 명령을 검토합니다342* 자동 모드에서는 분류기가 그 외의 제외된 명령을 검토합니다

343* `bypassPermissions` 모드에서는 확인 규칙이 일치하지 않는 한 제외된 명령이 프롬프트 없이 실행됩니다343* `bypassPermissions` 모드에서는 제외된 명령이 프롬프트 없이 실행되며, 확인 규칙이 해당 명령과 일치하는 경우는 예외입니다

344 344 

345항목이 일치하는지 확인하려면 Manual 모드로 전환한 뒤 Claude에게 `docker compose up -d`처럼 무언가를 변경하는 일치 명령을 실행하도록 요청합니다. 권한 프롬프트의 제목은 "Bash command (unsandboxed)"입니다.345항목이 일치하는지 확인하려면 Manual 모드로 전환한 뒤 Claude에게 `docker compose up -d`처럼 무언가를 변경하는 일치 명령을 실행하도록 요청합니다. 권한 프롬프트의 제목은 "Bash command (unsandboxed)"입니다.

346 346 

394| `credentials.envVars` `deny` 및 `mask` 항목 | 적용됩니다. 환경 변수 제거는 파일 시스템 계층과 독립적입니다 |394| `credentials.envVars` `deny` 및 `mask` 항목 | 적용됩니다. 환경 변수 제거는 파일 시스템 계층과 독립적입니다 |

395| 마스크로 적용된 [`credentials.files` `mask` 항목](#mask-credential-files) | 적용됩니다: 마스킹은 파일 시스템 계층과 독립적입니다. [`deny`로 폴백된](#mask-credential-files) 항목은 다른 `deny` 항목과 마찬가지로 적용되지 않습니다 |395| 마스크로 적용된 [`credentials.files` `mask` 항목](#mask-credential-files) | 적용됩니다: 마스킹은 파일 시스템 계층과 독립적입니다. [`deny`로 폴백된](#mask-credential-files) 항목은 다른 `deny` 항목과 마찬가지로 적용되지 않습니다 |

396 396 

397다른 두 가지도 달라집니다:397또한 모든 임시 디렉터리에 쓸 수 있게 되어 Claude Code가 더 이상 명령을 사용자별 임시 디렉터리로 리디렉션하지 않으므로, 샌드박스 처리된 명령은 사용자별 임시 디렉터리 대신 셸의 `$TMPDIR`을 상속합니다.

398 398 

399* 모든 임시 디렉터리에 쓸 수 있게 되어 Claude Code가 더 이상 명령을 사용자별 임시 디렉터리로 리디렉션하지 않으므로, 샌드박스 처리된 명령은 사용자별 임시 디렉터리 대신 셸의 `$TMPDIR`을 상속합니다.399Linux에서는 상위 셸에 이 변수가 설정되지 않은 경우가 많습니다. Bash 도구 지침은 Claude에게 `$TMPDIR`에 의존하는 대신 `mktemp -d`로 임시 작업 디렉터리를 만들도록 안내합니다.

400 

401 Linux에서는 상위 셸에 이 변수가 설정되지 않은 경우가 많습니다. Bash 도구 지침은 Claude에게 `$TMPDIR`에 의존하는 대신 `mktemp -d`로 임시 작업 디렉터리를 만들도록 안내합니다.

402* [`autoAllowBashIfSandboxed`](https://code.claude.com/docs/ko/settings-reference#sandbox-autoallowbashifsandboxed)는 여전히 기본값이 `true`이므로 샌드박스 처리된 명령은 계속 프롬프트 없이 실행됩니다. 샌드박스 처리된 명령에 대해 확인을 요청하려면 `false`로 설정합니다.

403 400 

404### 자격 증명 보호401### 자격 증명 보호

405 402 

1095}1092}

1096```1093```

1097 1094 

1098이렇게 하면 [자동 허용 모드](#sandbox-modes)가 켜집니다. 일반 권한 모드를 사용하려면 [`sandbox.autoAllowBashIfSandboxed`](https://code.claude.com/docs/ko/settings-reference#sandbox-autoallowbashifsandboxed)도 `false`로 설정합니다. 변경 사항은 실행 중인 세션에서 Claude가 다음 셸 명령을 실행할 때 적용되며, 이후 `/sandbox`의 **Mode** 탭에 적용 중인 모드가 표시됩니다.1095이렇게 하면 [일반 권한 모드](#sandbox-modes)가 켜집니다. 자동 허용 모드를 사용하려면 [`sandbox.autoAllowBashIfSandboxed`](https://code.claude.com/docs/ko/settings-reference#sandbox-autoallowbashifsandboxed)도 `true`로 설정합니다. 변경 사항은 실행 중인 세션에서 Claude가 다음 셸 명령을 실행할 때 적용되며, 이후 `/sandbox`의 **Mode** 탭에 적용 중인 모드가 표시됩니다.

1099 1096 

1100## 제한 사항1097## 제한 사항

1101 1098 

25 25 

26에이전트 시스템의 위험을 완화하기 위해:26에이전트 시스템의 위험을 완화하기 위해:

27 27 

28* **샌드박스 bash 도구**: [Sandbox](https://code.claude.com/docs/ko/sandboxing.md) bash 명령을 파일 시스템 및 네트워크 격리로 실행하여 권한 프롬프트를 줄이면서 보안을 유지합니다. `/sandbox`를 사용하여 Claude Code가 자율적으로 작업할 수 있는 경계를 정의하도록 구성합니다.28* **샌드박스 Bash 도구**: 파일 시스템 및 네트워크 격리를 통해 Bash 명령을 [샌드박스](https://code.claude.com/docs/ko/sandboxing.md)에서 실행합니다. `/sandbox`로 구성합니다

29* **작업 디렉터리 경계**: Manual 모드에서 Claude Code는 파일 도구가 시작된 폴더와 그 하위 폴더 외부를 읽거나 쓰기 전에 사용자에게 묻습니다. 이 경계는 권한 프롬프트이므로, 사용자가 승인한 Bash 명령은 여전히 사용자 계정이 쓸 수 있는 모든 위치에 쓸 수 있습니다29* **작업 디렉터리 경계**: Manual 모드에서 Claude Code는 파일 도구가 시작된 폴더와 그 하위 폴더 외부를 읽거나 쓰기 전에 사용자에게 묻습니다. 이 경계는 권한 프롬프트이므로, 사용자가 승인한 Bash 명령은 여전히 사용자 계정이 쓸 수 있는 모든 위치에 쓸 수 있습니다

30 * 프롬프트 없이 폴더를 읽으려면 [추가 디렉터리](https://code.claude.com/docs/ko/permissions.md#working-directories)로 추가합니다30 * 프롬프트 없이 폴더를 읽으려면 [추가 디렉터리](https://code.claude.com/docs/ko/permissions.md#working-directories)로 추가합니다

31 * 운영 체제 수준에서 Bash 명령을 제한하려면 [샌드박싱](https://code.claude.com/docs/ko/sandboxing.md#filesystem-isolation)을 켭니다31 * 운영 체제 수준에서 Bash 명령을 제한하려면 [샌드박싱](https://code.claude.com/docs/ko/sandboxing.md#filesystem-isolation)을 켭니다

62* **신뢰 확인**: 대화형 세션에서 Claude Code는 신뢰하지 않은 폴더에서 시작할 때 워크스페이스 신뢰 대화 상자를 표시합니다. 프로젝트의 `.mcp.json`에 있는 서버에는 별도의 승인 프롬프트가 있으며, [프로젝트 범위](https://code.claude.com/docs/ko/mcp.md#project-scope)에 이를 건너뛰는 세션이 나와 있습니다.62* **신뢰 확인**: 대화형 세션에서 Claude Code는 신뢰하지 않은 폴더에서 시작할 때 워크스페이스 신뢰 대화 상자를 표시합니다. 프로젝트의 `.mcp.json`에 있는 서버에는 별도의 승인 프롬프트가 있으며, [프로젝트 범위](https://code.claude.com/docs/ko/mcp.md#project-scope)에 이를 건너뛰는 세션이 나와 있습니다.

63 * 참고: `-p` 세션에서는 두 프롬프트 모두 표시되지 않습니다. [폴더를 신뢰하기 전에 실행되는 항목](https://code.claude.com/docs/ko/permissions.md#what-runs-before-you-trust-a-folder)에 해당 환경에서 저장소의 파일이 실행할 수 있는 항목이 나와 있습니다.63 * 참고: `-p` 세션에서는 두 프롬프트 모두 표시되지 않습니다. [폴더를 신뢰하기 전에 실행되는 항목](https://code.claude.com/docs/ko/permissions.md#what-runs-before-you-trust-a-folder)에 해당 환경에서 저장소의 파일이 실행할 수 있는 항목이 나와 있습니다.

64 * 참고: Claude Code를 홈 디렉터리에서 직접 시작할 때 신뢰 수락은 현재 세션에만 유지되며 디스크에 기록되지 않으므로 각 시작 시 프롬프트가 다시 나타납니다. 이를 유지하는 설정은 없습니다. 신뢰 수락이 디렉터리별로 저장되는 프로젝트 하위 디렉터리에서 Claude Code를 시작하십시오.64 * 참고: Claude Code를 홈 디렉터리에서 직접 시작할 때 신뢰 수락은 현재 세션에만 유지되며 디스크에 기록되지 않으므로 각 시작 시 프롬프트가 다시 나타납니다. 이를 유지하는 설정은 없습니다. 신뢰 수락이 디렉터리별로 저장되는 프로젝트 하위 디렉터리에서 Claude Code를 시작하십시오.

65* **명령 인젝션 감지**: Manual 모드에서 Claude Code는 완전히 분석할 수 없는 Bash 명령을 실행하기 전에 확인을 요청합니다. `Bash(git *)`와 같이 명령의 일부에 대한 허용 규칙으로는 이 프롬프트를 건너뛸 수 없습니다. [샌드박스된 명령](https://code.claude.com/docs/ko/permissions.md#how-permissions-interact-with-sandboxing)은 이 프롬프트 없이 실행될 수 있습니다.65* **명령 인젝션 감지**: Manual 모드에서 Claude Code는 완전히 분석할 수 없는 Bash 명령을 실행하기 전에 확인을 요청합니다. `Bash(git *)`와 같이 명령의 일부에 대한 허용 규칙으로는 이 프롬프트를 건너뛸 수 없습니다. [자동 허용 모드](https://code.claude.com/docs/ko/sandboxing.md#auto-allow-mode)의 [샌드박스된 명령](https://code.claude.com/docs/ko/permissions.md#how-permissions-interact-with-sandboxing)은 이 프롬프트 없이 실행될 수 있습니다.

66* **폐쇄형 매칭 실패**: Manual 모드에서는 일치하지 않는 명령은 기본적으로 수동 승인이 필요합니다.66* **폐쇄형 매칭 실패**: Manual 모드에서는 일치하지 않는 명령은 기본적으로 수동 승인이 필요합니다.

67* **안전한 자격 증명 저장**: API 키와 토큰은 사용 가능한 경우 macOS Keychain에 저장됩니다. Linux에서는 모드 `0600`의 파일에 저장되며, Windows에서는 사용자 프로필 디렉터리의 액세스 제어를 상속하는 파일에 저장됩니다. [자격 증명 관리](https://code.claude.com/docs/ko/authentication.md#credential-management)를 참조하십시오.67* **안전한 자격 증명 저장**: API 키와 토큰은 사용 가능한 경우 macOS Keychain에 저장됩니다. Linux에서는 모드 `0600`의 파일에 저장되며, Windows에서는 사용자 프로필 디렉터리의 액세스 제어를 상속하는 파일에 저장됩니다. [자격 증명 관리](https://code.claude.com/docs/ko/authentication.md#credential-management)를 참조하십시오.

68 68 

1355 1355 

1356### `sandbox.autoAllowBashIfSandboxed`1356### `sandbox.autoAllowBashIfSandboxed`

1357 1357 

1358Claude Code가 권한 프롬프트 없이 샌드박스된 Bash 명령을 실행하도록 합니다. 샌드박스에서 실행할 수 없는 명령은 여전히 일반 권한 흐름을 거치며, `deny` 규칙 및 `Bash(git push *)`와 같은 콘텐츠 범위 `ask` 규칙은 여전히 적용됩니다. 단순 `Bash` ask 규칙은 샌드박스된 명령에 대해 건너뜁니다. 이를 `false`로 설정하여 샌드박스된 명령도 일반 권한 흐름을 거치도록 하면, `/sandbox` **모드** 탭에서 이를 일반 권한 모드라고 부릅니다.1358Claude Code가 권한 프롬프트 없이 샌드박스된 Bash 명령을 실행하도록 합니다. 샌드박스에서 실행할 수 없는 명령은 여전히 일반 권한 흐름을 거칩니다. `deny` 규칙과 `Bash(git push *)` 같은 콘텐츠 범위 `ask` 규칙은 여전히 적용되지만, 단독 `Bash` 확인 규칙은 샌드박스된 명령에 대해 건너뜁니다. 관리형 설정에서 `true`로 설정하려면 [우선순위가 가장 높은 관리형 소스](https://code.claude.com/docs/ko/managed-settings.md#how-claude-code-combines-managed-sources)의 `sandbox` 블록에 추가하세요.

1359 1359 

1360* **범위**: [`Any file`](#scopes)1360* **범위**: [`Any file`](#scopes)

1361* **유형**: Boolean1361* **유형**: Boolean

1362 * `true`: Claude Code는 [자동 허용 모드](https://code.claude.com/docs/ko/sandboxing.md#auto-allow-mode)에서 설명하는 경우를 제외하고 권한 프롬프트 없이 샌드박스된 Bash 명령을 실행합니다. `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`는 자동 허용을 끕니다.1362 * `true`: Claude Code는 [자동 허용 모드](https://code.claude.com/docs/ko/sandboxing.md#auto-allow-mode)에서 설명하는 경우를 제외하고 권한 프롬프트 없이 샌드박스된 Bash 명령을 실행합니다. `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`는 자동 허용을 끕니다.

1363 * `false`: 샌드박스된 명령은 일반 권한 흐름을 거치므로, 허용 규칙 및 권한 모드가 결정합니다. `/sandbox` **모드** 탭에서 이를 일반 권한 모드라고 부릅니다.1363 * `false`: 샌드박스된 명령은 일반 권한 흐름을 거치므로, 허용 규칙 및 권한 모드가 결정합니다. `/sandbox` **모드** 탭에서 이를 일반 권한 모드라고 부릅니다.

1364* **기본값**: `true`1364* **기본값**: `false`. v2.1.324 이전에는 기본값이 `true`였습니다

1365 1365 

1366다음은 샌드박스를 켜고 샌드박스된 명령을 일반 권한 흐름을 거치도록 합니다:1366샌드박스를 켠 상태로 유지하면서 권한 프롬프트 없이 샌드박스된 명령을 실행하려면 `sandbox` 블록에 두 키를 모두 설정하세요:

1367 1367 

1368```json settings.json theme={null}1368```json settings.json theme={null}

1369{1369{

1370 "sandbox": {1370 "sandbox": {

1371 "enabled": true,1371 "enabled": true,

1372 "autoAllowBashIfSandboxed": false1372 "autoAllowBashIfSandboxed": true

1373 }1373 }

1374}1374}

1375```1375```

1653}1653}

1654```1654```

1655 1655 

1656이 계층이 꺼지면 Claude Code는 `denyRead`나 `credentials.files`의 `deny` 항목을 적용하지 않지만, `credentials.envVars` 항목과 적용된 `mask` 항목은 계속 작동합니다. [`autoAllowBashIfSandboxed`](#sandbox-autoallowbashifsandboxed)는 여전히 기본값이 `true`이므로, 계속 확인을 요청하게 하려면 `false`로 설정하세요. 이 키를 설정할 수 있는 소스의 전체 목록과 격리가 꺼졌을 때 달라지는 점은 [파일 시스템 격리 비활성화하기](https://code.claude.com/docs/ko/sandboxing.md#disable-filesystem-isolation)를 참조하세요.1656이 계층이 꺼져 있으면 Claude Code는 `denyRead`나 `credentials.files`의 `deny` 항목을 적용하지 않지만, `credentials.envVars` 항목과 적용된 `mask` 항목은 계속 작동합니다. 이 키를 설정할 수 있는 소스의 전체 목록과 격리가 꺼졌을 때 달라지는 점은 [파일 시스템 격리 비활성화](https://code.claude.com/docs/ko/sandboxing.md#disable-filesystem-isolation)를 참조하세요.

1657 1657 

1658### `sandbox.ignoreViolations`1658### `sandbox.ignoreViolations`

1659 1659 

4870 4870 

4871### `agentPushNotifEnabled`4871### `agentPushNotifEnabled`

4872 4872 

4873긴 작업이 끝났을 때처럼 Claude가 보낼 가치가 있다고 판단하면 휴대폰으로 푸시 알림을 보낼 수 있도록 허용합니다. 로컬 세션에서는 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)이 연결되어 있는 동안 Claude가 알림을 보낼 수 있습니다. `/config`에는 **Push when Claude decides**로 표시됩니다. 그곳에서 값을 변경하면 Claude Code는 해당 값을 사용자의 계정에도 저장합니다.4873긴 작업이 끝났을 때처럼 Claude가 보낼 가치가 있다고 판단하면 휴대폰으로 푸시 알림을 보낼 수 있도록 허용합니다. 로컬 세션에서는 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)이 연결되어 있는 동안 Claude가 알림을 보낼 수 있습니다. `/config`에는 **Push when Claude decides**로 표시됩니다.

4874 4874 

4875* **범위**: [`Any file`](#scopes). Claude Code는 이전 버전이 `~/.claude.json`에 남긴 값도 읽습니다.4875* **범위**: [`Any file`](#scopes). Claude Code는 이전 버전이 `~/.claude.json`에 남긴 값도 읽습니다.

4876* **유형**: Boolean4876* **유형**: Boolean

4884}4884}

4885```4885```

4886 4886 

4887[`claude remote-control`](https://code.claude.com/docs/ko/remote-control#start-a-remote-control-session) 서버에서 세션을 실행하는 경우, 해당 세션은 이 키가 아니라 계정에 저장된 값을 따릅니다. 그 값을 변경하려면 터미널의 Claude Code 세션에서 `/config`를 실행하고 **Push when Claude decides**를 켜거나 끕니다. 토글이 이미 원하는 값을 표시하고 있다면, 값을 한 번 바꿨다가 다시 되돌려 Claude Code가 해당 값을 계정에 저장하도록 합니다.4887이 키만으로는 알림을 받을 수 없습니다. 알림을 설정하려면 [모바일 푸시 알림](https://code.claude.com/docs/ko/remote-control.md#mobile-push-notifications)의 단계를 따르십시오.

4888 4888 

4889[모바일 푸시 알림](https://code.claude.com/docs/ko/remote-control.md#mobile-push-notifications)을 참조하십시오.4889[`claude remote-control`](https://code.claude.com/docs/ko/remote-control#start-a-remote-control-session) 서버에서 세션을 실행하는 경우, 해당 세션은 이 키가 아니라 계정에 저장된 값을 따릅니다. 그 값을 변경하려면 터미널의 Claude Code 세션에서 `/config`를 실행하고 **Push when Claude decides**를 켜거나 끕니다. 토글이 이미 원하는 값을 표시하고 있다면, 값을 한 번 바꿨다가 다시 되돌려 Claude Code가 해당 값을 계정에 저장하도록 합니다.

4890 4890 

4891### `awaySummaryEnabled`4891### `awaySummaryEnabled`

4892 4892 

5043}5043}

5044```5044```

5045 5045 

5046[모바일 푸시 알림](https://code.claude.com/docs/ko/remote-control.md#mobile-push-notifications)을 참조하십시오.5046이 키만으로는 알림을 받을 수 없습니다. 알림을 설정하려면 [모바일 푸시 알림](https://code.claude.com/docs/ko/remote-control.md#mobile-push-notifications)의 단계를 따르십시오.

5047 5047 

5048### `preferredNotifChannel`5048### `preferredNotifChannel`

5049 5049 

5421 5421 

5422### `minimumVersion`5422### `minimumVersion`

5423 5423 

5424백그라운드 자동 업데이트 및 `claude update`가 이 버전 아래의 버전을 설치하지 않도록 하여, `"stable"` 채널로 이동해도 최신 `"latest"` 빌드에서 다운그레이드되지 않습니다. Claude Code는 `/config`에서 채널을 전환하면서 현재 버전에 머물기를 선택할 때 이 키를 기록하고, `"latest"`로 다시 전환할 때 지웁니다.5424백그라운드 자동 업데이트 및 `claude update`가 설정한 버전 아래의 버전을 설치하지 않도록 합니다. Claude Code는 `/config`에서 채널을 전환하면서 현재 버전에 머물기를 선택할 때 이 키를 자동으로 기록합니다. Claude Code는 `/config`에서 `"latest"`로 다시 전환할 때 이 키를 지웁니다.

5425 5425 

5426* **범위**: [`모든 파일`](#scopes). 조직 전체 최소값을 고정하려면 관리 설정에서 설정하여 사용자 및 프로젝트 설정이 낮출 수 없도록 합니다.5426* **범위**: [`모든 파일`](#scopes). 사용자 및 프로젝트 설정이 재정의할 수 없는 조직 전체 최소값을 고정하려면 관리형 설정에서 이 키를 설정합니다.

5427* **유형**: 문자열, `"2.1.100"`과 같은 버전 번호; 유효한 버전이 아닌 값은 무시됩니다5427* **유형**: 문자열, `"2.1.323"`과 같은 버전 번호; 유효한 버전이 아닌 값은 무시됩니다

5428* **기본값**: 설정되지 않음, 업데이트는 채널이 제공하는 모든 버전을 설치할 수 있습니다5428* **기본값**: 설정되지 않음, 업데이트는 채널이 제공하는 모든 버전을 설치할 수 있습니다

5429 5429 

5430이 예제는 stable 채널을 따르고 2.1.100 아래의 버전 설치를 거부합니다:5430이 예제는 stable 채널을 따르고 2.1.323 아래의 버전 설치를 거부합니다:

5431 5431 

5432```json settings.json theme={null}5432```json settings.json theme={null}

5433{5433{

5434 "autoUpdatesChannel": "stable",5434 "autoUpdatesChannel": "stable",

5435 "minimumVersion": "2.1.100"5435 "minimumVersion": "2.1.323"

5436}5436}

5437```5437```

5438 5438 

40>40>

41> **macOS, Linux, WSL:**41> **macOS, Linux, WSL:**

42>42>

43> ```bash theme={null}43> ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

44> curl -fsSL https://claude.ai/install.sh | bash44> curl -fsSL https://claude.ai/install.sh | bash

45> ```45> ```

46>46>

48>48>

49> **Windows PowerShell:**49> **Windows PowerShell:**

50>50>

51> ```powershell theme={null}51> ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

52> irm https://claude.ai/install.ps1 | iex52> irm https://claude.ai/install.ps1 | iex

53> ```53> ```

54>54>

55> **Windows CMD:**55> **Windows CMD:**

56>56>

57> ```batch theme={null}57> ```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

58> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd58> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

59> ```59> ```

60>60>

72 72 

73> [tab] Homebrew73> [tab] Homebrew

74>74>

75> ```bash theme={null}75> ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

76> brew install --cask claude-code76> brew install --cask claude-code

77> ```77> ```

78>78>

84 84 

85> [tab] WinGet85> [tab] WinGet

86>86>

87> ```powershell theme={null}87> ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

88> winget install Anthropic.ClaudeCode88> winget install Anthropic.ClaudeCode

89> ```89> ```

90>90>

220}220}

221```221```

222 222 

223이 설정을 사용하면 네이티브 설치는 stable 버전이 현재 버전보다 오래된 경우에도 해당 버전으로 업데이트됩니다. 다운그레이드를 피하려면 [최소 버전도 고정](#pin-a-minimum-version)하세요.

224 

223새로 출시된 모델은 stable 채널이 제공하는 버전보다 새로운 Claude Code 버전을 요구할 수 있습니다. 해당 모델을 바로 실행하려면 latest 채널로 전환하세요.225새로 출시된 모델은 stable 채널이 제공하는 버전보다 새로운 Claude Code 버전을 요구할 수 있습니다. 해당 모델을 바로 실행하려면 latest 채널로 전환하세요.

224 226 

225엔터프라이즈 배포의 경우 [관리 설정](https://code.claude.com/docs/ko/managed-settings.md)을 사용하여 조직 전체에서 일관된 릴리스 채널을 적용할 수 있습니다.227엔터프라이즈 배포의 경우 [관리 설정](https://code.claude.com/docs/ko/managed-settings.md)을 사용하여 조직 전체에서 일관된 릴리스 채널을 적용할 수 있습니다.

230 232 

231### 최소 버전 고정233### 최소 버전 고정

232 234 

233`minimumVersion` 설정은 하한을 설정합니다. 백그라운드 자동 업데이트 및 `claude update`는 이 값 이하의 버전 설치를 거부하므로 `"stable"` 채널로 이동해도 이미 최신 `"latest"` 빌드에 있는 경우 다운그레이드되지 않습니다.235다운그레이드 없이 네이티브 설치를 `"stable"` [릴리스 채널](#configure-release-channel)로 이동하려면 [`minimumVersion`](https://code.claude.com/docs/ko/settings-reference#minimumversion)을 현재 실행 중인 버전으로 설정하세요. 백그라운드 자동 업데이트 및 `claude update`는 최소값 미만의 버전 설치를 거부합니다.

236 

237Claude Code가 현재 버전을 자동으로 입력하도록 하려면 `/config`에서, 번호를 직접 입력하려면 설정 파일에서 최소값을 설정하세요:

234 238 

235`/config`를 통해 `"latest"`에서 `"stable"`로 전환하면 현재 버전을 유지하거나 다운그레이드를 허용하라는 메시지가 표시됩니다. 현재 버전을 유지하도록 선택하면 `minimumVersion`이 해당 버전으로 설정됩니다. `"latest"`로 다시 전환하면 이를 지웁니다.239* **`/config`에서**: **자동 업데이트 채널**을 stable로 전환한 다음 **현재 버전 유지**를 선택하세요. `/config`에서 다시 latest로 전환하면 Claude Code가 최소값을 지웁니다.

240* **[설정 파일](https://code.claude.com/docs/ko/settings.md)에서**: 셸에서 `claude --version`을 실행하고 `minimumVersion`을 출력 시작 부분의 번호로 설정하세요. 같은 편집에서 `autoUpdatesChannel`을 `"stable"`로 설정하세요.

236 241 

237[settings.json 파일](https://code.claude.com/docs/ko/settings.md)에 추가하여 하한을 명시적으로 고정하세요:242다음 `~/.claude/settings.json`은 버전 2.1.323의 설치를 stable로 전환합니다:

238 243 

239```json theme={null}244```json theme={null}

240{245{

241 "autoUpdatesChannel": "stable",246 "autoUpdatesChannel": "stable",

242 "minimumVersion": "2.1.100"247 "minimumVersion": "2.1.323"

243}248}

244```249```

245 250 

246[관리 설정](https://code.claude.com/docs/ko/managed-settings.md)에서 이는 사용자 및 프로젝트 설정이 재정의할 수 없는 조직 전체 최소값을 적용합니다.251설치는 stable 채널이 더 새로운 버전을 제공할 때까지 2.1.323에 머뭅니다.

252 

253#### 조직의 버전 제한 설정

254 

255[관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)에서 `minimumVersion`은 사용자 및 프로젝트 설정이 재정의할 수 없는 조직 전체 최소값을 적용합니다.

247 256 

248`minimumVersion` 핀은 업데이트만 제한합니다. Claude Code가 버전 범위 외에서 시작되지 않도록 하려면 관리 설정 `requiredMinimumVersion` 및 `requiredMaximumVersion`을 대신 사용하세요. 업데이트는 또한 `requiredMaximumVersion` 상한을 준수합니다. [`requiredMinimumVersion`](https://code.claude.com/docs/ko/settings-reference#requiredminimumversion) 및 [`requiredMaximumVersion`](https://code.claude.com/docs/ko/settings-reference#requiredmaximumversion)을 참조하세요.257`minimumVersion` 핀은 업데이트만 제한합니다. Claude Code가 버전 범위 외에서 시작되지 않도록 하려면 관리 설정 `requiredMinimumVersion` 및 `requiredMaximumVersion`을 대신 사용하세요. 업데이트는 또한 `requiredMaximumVersion` 상한을 준수합니다. [`requiredMinimumVersion`](https://code.claude.com/docs/ko/settings-reference#requiredminimumversion) 및 [`requiredMaximumVersion`](https://code.claude.com/docs/ko/settings-reference#requiredmaximumversion)을 참조하세요.

249 258 

22 22 

23Claude Code에는 `/doctor`, `/code-review`, `/batch`, `/debug`, `/loop`, `/claude-api` 등의 번들 스킬 세트가 포함되어 있습니다. 번들 스킬은 프롬프트 기반입니다. 즉, Claude에 상세한 지침을 제공하고 도구를 사용하여 작업을 조율하도록 합니다. 대부분의 기본 제공 명령은 대신 고정된 로직을 직접 실행합니다.23Claude Code에는 `/doctor`, `/code-review`, `/batch`, `/debug`, `/loop`, `/claude-api` 등의 번들 스킬 세트가 포함되어 있습니다. 번들 스킬은 프롬프트 기반입니다. 즉, Claude에 상세한 지침을 제공하고 도구를 사용하여 작업을 조율하도록 합니다. 대부분의 기본 제공 명령은 대신 고정된 로직을 직접 실행합니다.

24 24 

25번들 스킬은 `/` 다음에 스킬 이름을 입력하여 호출합니다. Claude는 관련성이 있을 때 일부 번들 스킬을 자동으로 호출하며, [`/verify`](#run-and-verify-your-app)를 포함한 다른 스킬은 사용자가 호출할 때만 실행됩니다.25번들 스킬은 `/` 다음에 스킬 이름을 입력하여 호출합니다. Claude는 관련성이 있을 때 일부 번들 스킬을 자동으로 호출합니다.

26 26 

27대부분의 번들 스킬은 모든 세션에서 사용 가능합니다. 일부는 특정 기능에 따라 달라집니다. 예를 들어 `/workflow-authoring`은 [동적 워크플로](https://code.claude.com/docs/ko/workflows.md)가 활성화된 경우에만 사용 가능합니다.27대부분의 번들 스킬은 모든 세션에서 사용 가능합니다. 일부는 특정 기능에 따라 달라집니다. 예를 들어 `/workflow-authoring`은 [동적 워크플로](https://code.claude.com/docs/ko/workflows.md)가 활성화된 경우에만 사용 가능합니다.

28 28 

320 320 

321세션이 시작될 때 존재하지 않았던 최상위 스킬 디렉터리를 만든 경우 [`/reload-skills`](https://code.claude.com/docs/ko/commands#all-commands)를 실행하여 그곳에 넣은 스킬을 가져오세요. Claude Code는 아직 해당 디렉터리를 감시하지 않으므로 이후 그곳에서 변경할 때마다 `/reload-skills`를 다시 실행하세요.321세션이 시작될 때 존재하지 않았던 최상위 스킬 디렉터리를 만든 경우 [`/reload-skills`](https://code.claude.com/docs/ko/commands#all-commands)를 실행하여 그곳에 넣은 스킬을 가져오세요. Claude Code는 아직 해당 디렉터리를 감시하지 않으므로 이후 그곳에서 변경할 때마다 `/reload-skills`를 다시 실행하세요.

322 322 

323라이브 변경 감지는 `SKILL.md` 텍스트만 다룹니다. 스킬 폴더가 [플러그인](https://code.claude.com/docs/ko/plugins/loading.md#plugins-shared-through-a-repository)이기도 한 경우 `hooks/`, `.mcp.json`, `agents/` 및 `output-styles/`의 변경 사항을 적용하려면 `/reload-plugins`가 필요합니다.323> [!NOTE]

324>

325> 라이브 변경 감지는 `SKILL.md` 텍스트를 다룹니다. 스킬 폴더가 [플러그인](https://code.claude.com/docs/ko/plugins/loading.md#plugins-shared-through-a-repository)이기도 한 경우 `.mcp.json`, `agents/` 및 `output-styles/`의 변경 사항을 적용하려면 `/reload-plugins`가 필요합니다. `hooks/`의 변경 사항에도 필요하지만, [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)의 모듈 파일이 [자체적으로 다시 로드되는](https://code.claude.com/docs/ko/env-vars.md) 경우는 예외입니다.

324 326 

325### 스킬 제거327### 스킬 제거

326 328 

36>36>

37> 코드베이스 검색 및 분석에 최적화된 빠른 읽기 전용 에이전트입니다.37> 코드베이스 검색 및 분석에 최적화된 빠른 읽기 전용 에이전트입니다.

38>38>

39> * **모델**: 주 대화의 모델입니다. 주 대화가 Fable에서 실행되는 경우 Explore의 모델은 연결 방식에 따라 달라집니다.39> * **모델**: [부모 대화](#which-model-a-nested-subagent-runs-on)의 모델입니다. 부모 대화가 Fable에서 실행되는 경우 Explore는 연결 방식에 따라 Opus에서 실행되거나 Fable을 그대로 사용합니다.

40> * Claude 구독, Anthropic Console 계정 또는 `ANTHROPIC_BASE_URL`을 통해 연결하는 [LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway)를 사용하는 경우 Explore는 [`opus` 별칭](https://code.claude.com/docs/ko/model-config#model-aliases)이 가리키는 Opus 모델에서 실행됩니다.40> * Claude 구독, Anthropic Console 계정 또는 `ANTHROPIC_BASE_URL`을 통해 연결하는 [LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway)를 사용하는 경우 Explore는 [`opus` 별칭](https://code.claude.com/docs/ko/model-config#model-aliases)이 가리키는 Opus 모델에서 실행됩니다.

41> * Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, [Claude Platform on AWS](https://code.claude.com/docs/ko/claude-platform-on-aws.md) 또는 [Claude apps 게이트웨이](https://code.claude.com/docs/ko/claude-apps-gateway)에서는 Explore가 주 대화의 모델을 그대로 사용합니다.41> * Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, [Claude Platform on AWS](https://code.claude.com/docs/ko/claude-platform-on-aws.md) 또는 [Claude apps 게이트웨이](https://code.claude.com/docs/ko/claude-apps-gateway)에서는 Explore가 Fable을 그대로 사용합니다.

42> * **도구**: 읽기 전용 도구; Write 및 Edit은 거부됩니다.42> * **도구**: 읽기 전용 도구; Write 및 Edit은 거부됩니다.

43> * **목적**: 파일 검색, 코드 검색, 코드베이스 탐색43> * **목적**: 파일 검색, 코드 검색, 코드베이스 탐색

44>44>

52>52>

53> [plan mode](https://code.claude.com/docs/ko/permission-modes.md#analyze-before-you-edit-with-plan-mode) 중에 계획을 제시하기 전에 컨텍스트를 수집하는 데 사용되는 연구 에이전트입니다.53> [plan mode](https://code.claude.com/docs/ko/permission-modes.md#analyze-before-you-edit-with-plan-mode) 중에 계획을 제시하기 전에 컨텍스트를 수집하는 데 사용되는 연구 에이전트입니다.

54>54>

55> * **모델**: 주 대화에서 상속되며, `CLAUDE_CODE_SUBAGENT_MODEL`을 설정하고 [모든 subagent를 하나의 모델에서 실행](#run-every-subagent-on-one-model)하도록 강제하지 않는 한 그렇습니다.55> * **모델**: [부모 대화](#which-model-a-nested-subagent-runs-on)에서 상속됩니다. 단, `CLAUDE_CODE_SUBAGENT_MODEL`을 설정하여 [모든 서브에이전트에 강제로 적용](#run-every-subagent-on-one-model)한 경우는 제외합니다.

56> * **도구**: 읽기 전용 도구; Write 및 Edit은 거부됩니다.56> * **도구**: 읽기 전용 도구; Write 및 Edit은 거부됩니다.

57> * **목적**: 계획을 위한 코드베이스 연구57> * **목적**: 계획을 위한 코드베이스 연구

58>58>

62>62>

63> 탐색과 작업 모두를 필요로 하는 복잡한 다단계 작업을 위한 유능한 에이전트입니다.63> 탐색과 작업 모두를 필요로 하는 복잡한 다단계 작업을 위한 유능한 에이전트입니다.

64>64>

65> * **모델**: [`CLAUDE_CODE_SUBAGENT_MODEL`](#choose-a-model) 모델(설정한 경우 및 다른 것이 모델을 다른 방식으로 할당하지 않는 경우), 그렇지 않으면 주 대화의 모델; [모델 선택](#choose-a-model)은 전체 순서를 나타내고, [모든 subagent를 하나의 모델에서 실행](#run-every-subagent-on-one-model)은 변수가 이러한 소스를 재정의하는 방법을 보여줍니다.65> * **모델**: 기본적으로 부모 대화의 모델이며, [모델 순서](#choose-a-model)를 따릅니다.

66> * **도구**: subagent에 [사용 가능한](#available-tools) 모든 도구66> * **도구**: 서브에이전트에 [사용 가능한](#available-tools) 모든 도구

67> * **목적**: 복잡한 연구, 다단계 작업, 코드 수정67> * **목적**: 복잡한 연구, 다단계 작업, 코드 수정

68>68>

69> Claude는 작업이 탐색과 수정 모두를 필요로 하거나, 결과를 해석하기 위한 복잡한 추론이 필요하거나, 여러 종속 단계가 필요할 때 general-purpose에 위임합니다.69> Claude는 작업이 탐색과 수정 모두를 필요로 하거나, 결과를 해석하기 위한 복잡한 추론이 필요하거나, 여러 종속 단계가 필요할 때 general-purpose에 위임합니다.

346 346 

347### 모델 선택347### 모델 선택

348 348 

349`model` 필드는 서브에이전트가 사용할 모델을 제어합니다.349기본적으로 직접 정의한 서브에이전트는 해당 서브에이전트를 시작한 대화와 동일한 모델에서 실행됩니다. 모델을 직접 선택하려면 정의의 [`model`](#supported-frontmatter-fields) 필드를 다음 값 중 하나로 설정하세요.

350 350 

351* **모델 별칭**: 사용 가능한 별칭 중 하나를 사용합니다: `sonnet`, `opus`, `haiku` 또는 `fable`351* **모델 별칭**: `sonnet`, `opus`, `haiku` 또는 `fable`

352* **전체 모델 ID**: `claude-opus-5-5` 또는 `claude-sonnet-5`와 같은 전체 모델 ID를 사용합니다. `--model` 플래그와 동일한 값을 허용합니다352* **전체 모델 ID**: `claude-opus-5-5` 또는 `claude-sonnet-5`처럼 [`--model`](https://code.claude.com/docs/ko/cli-reference#cli-flags) 플래그가 허용하는 값

353* **inherit**: 메인 대화와 동일한 모델을 사용합니다353* **`inherit`**: 메인 대화의 모델, 또는 [중첩된 서브에이전트](#which-model-a-nested-subagent-runs-on)의 경우 해당 서브에이전트를 생성한 서브에이전트의 모델

354 354 

355Claude가 서브에이전트를 호출할 때 해당 호출에 대해 `model` 매개변수를 전달할 수도 있습니다. Agent 도구 호출에서 이 매개변수는 모델 별칭 `sonnet`, `opus`, `haiku` 또는 `fable`을 받습니다. Claude는 해당 호출에서 전체 모델 ID나 `inherit`를 전달할 수 없습니다. Claude Code는 다음 순서로 서브에이전트의 모델을 결정합니다.355둘 이상의 소스가 모델을 설정하는 경우 Claude Code는 다음 순서에서 가장 먼저 오는 것을 사용합니다.

356 356 

3571. 호출별 `model` 매개변수3571. Claude가 서브에이전트를 시작할 때 전달할 수 있는 호출별 `model` 매개변수. Agent 도구 호출에서 이 매개변수는 전체 모델 ID나 `inherit`가 아니라 모델 별칭을 받습니다.

3582. 서브에이전트 정의의 `model` frontmatter. 여기서 `inherit`는 메인 대화의 모델을 선택합니다3582. `inherit`를 포함한 서브에이전트 정의의 `model` 필드

3593. 모델 별칭이나 모델 ID로 설정한 경우 [`CLAUDE_CODE_SUBAGENT_MODEL`](https://code.claude.com/docs/ko/model-config#environment-variables) 환경 변수3593. [`CLAUDE_CODE_SUBAGENT_MODEL`](https://code.claude.com/docs/ko/model-config#environment-variables) 환경 변수

3604. 메인 대화의 모델3604. 메인 대화의 모델, 또는 중첩된 서브에이전트의 경우 해당 서브에이전트를 생성한 서브에이전트의 모델

361 361 

362설치된 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)가 [`agent.spawn`](https://code.claude.com/docs/ko/plugins/mods/reference#subagents) 훅에서 모델을 설정하면 Claude Code는 호출별 매개변수 대신 해당 모델을 사용합니다.362Claude가 별칭을 전달한 경우, 서브에이전트는 [재개되거나 후속 메시지를 받을](#resume-subagents) 때도 해당 별칭을 유지합니다. 설치된 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)가 [`agent.spawn`](https://code.claude.com/docs/ko/plugins/mods/reference#subagents) 훅에서 모델을 설정하면 Claude Code는 호출별 매개변수 대신 해당 모델을 사용합니다.

363 

364다음 두 경우에는 호출별 매개변수나 frontmatter의 `opus`와 같은 계열 별칭이 [별칭이 가리키는 버전](https://code.claude.com/docs/ko/model-config.md#model-aliases) 대신 메인 대화의 모델로 해석됩니다.

365 

366* **메인 대화의 모델이 해당 계열에 속하는 경우**: 서브에이전트는 `[1m]` 접미사를 포함하여 메인 대화와 정확히 동일한 모델에서 실행되므로 메인 대화와 동일한 [확장 컨텍스트](https://code.claude.com/docs/ko/model-config.md#extended-context) 윈도우를 얻습니다.

367* **[Anthropic API 이외의 제공자](https://code.claude.com/docs/ko/third-party-integrations.md)에서 Claude Code가 메인 대화의 모델 계열을 알 수 없는 경우**: Claude Code가 기반 모델로 해석하지 못한 Amazon Bedrock의 [애플리케이션 추론 프로필 ARN](https://code.claude.com/docs/ko/amazon-bedrock.md#iam-configuration)에서 이런 일이 발생할 수 있습니다. 이 경우는 `opus` 별칭에만 해당하며, [`ANTHROPIC_DEFAULT_OPUS_MODEL`](https://code.claude.com/docs/ko/model-config#environment-variables)을 설정한 경우에는 `opus`가 설정한 모델로 해석되므로 적용되지 않습니다.

368 

369`CLAUDE_CODE_SUBAGENT_MODEL`의 별칭은 메인 대화의 계열을 가리키더라도 항상 별칭이 가리키는 버전으로 해석됩니다. 이 변수를 `inherit`로 설정하는 것은 설정하지 않은 것과 같습니다.

370 363 

371`CLAUDE_CODE_SUBAGENT_MODEL`만 설정해서는 기본 제공 Explore 및 Plan 서브에이전트가 실행되는 모델이 바뀌지 않습니다. 이를 바꾸려면 [모든 서브에이전트를 하나의 모델에서 실행](#run-every-subagent-on-one-model)을 참조하세요.364`CLAUDE_CODE_SUBAGENT_MODEL`만 설정해서는 기본 제공 Explore 및 Plan 서브에이전트가 실행되는 모델이 바뀌지 않습니다. 이를 바꾸려면 [모든 서브에이전트를 하나의 모델에서 실행](#run-every-subagent-on-one-model)을 참조하세요.

372 365 

373v2.1.251 이전에는 `CLAUDE_CODE_SUBAGENT_MODEL`이 이 순서에서 가장 먼저 왔으며, `model: inherit`를 포함하여 호출별 매개변수와 frontmatter를 모두 재정의했습니다.366#### 중첩된 서브에이전트가 실행되는 모델

374 367 

375Claude Code는 호출별 매개변수, frontmatter, 환경 변수 값을 조직의 [`availableModels`](https://code.claude.com/docs/ko/model-config#restrict-model-selection) 허용 목록과 대조하여 확인합니다. 차단된 값에 대해서는 다른 모델로 대체합니다.368기본적으로 직접 정의한 [중첩된 서브에이전트](#let-subagents-spawn-their-own-subagents)는 부모, 즉 해당 서브에이전트를 생성한 서브에이전트의 모델에서 실행됩니다. 중첩된 서브에이전트를 다른 모델에서 실행하려면 해당 서브에이전트의 `model` 필드를 그 모델로 설정하세요.

376 369 

377* 차단된 값이 `opus`와 같은 계열 별칭인 경우, Claude Code는 `/model`과 동일한 [대체 규칙 및 제공자 범위](https://code.claude.com/docs/ko/model-config.md#restrict-model-selection)에 따라 허용 목록이 허용하는 해당 계열의 최신 버전에서 서브에이전트를 실행합니다. v2.1.222 이전에는 차단된 계열 별칭에 대해서도 Claude Code가 상속된 모델에서 서브에이전트를 실행했습니다.370예를 들어 메인 대화가 Opus에서 실행되고 Haiku에서 리뷰어 서브에이전트를 시작한다고 가정해 보겠습니다. 리뷰어가 다음 서브에이전트를 생성하면, 기본적으로 이들은 Opus가 아니라 Haiku에서 실행됩니다.

378* 그 밖의 차단된 값이거나, 해당 대체가 작동하지 않는 제공자이거나, 허용 목록이 해당 계열의 어떤 버전도 허용하지 않는 경우, Claude Code는 대신 상속된 모델에서 서브에이전트를 실행합니다. `CLAUDE_CODE_SUBAGENT_MODEL`을 설정한 경우 Claude Code는 동일한 규칙에 따라 해당 모델을 먼저 시도합니다.

379 371 

380대화형 세션에서 Claude Code는 두 가지 대체 모두에 대해 요청된 모델과 서브에이전트가 실행되는 모델을 명시한 경고를 표시합니다.372* `model: inherit`가 설정되었거나 `model` 필드가 없는 서브에이전트

373* 기본 제공 Explore, Plan, general-purpose 서브에이전트

374* [포크](#fork-the-current-conversation)

381 375 

382서브에이전트가 어떤 모델에서 실행 중인지 확인하려면 [`/tasks`](https://code.claude.com/docs/ko/commands)를 실행하세요. Claude Code는 서브에이전트 행에 모델을 표시하고, 해당 서브에이전트에 설정된 [effort 수준](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level)이 있으면 함께 표시합니다. Claude Code v2.1.242 이상이 필요합니다.376플랜 모드에서는 세션의 모델을 [`opusplan`](https://code.claude.com/docs/ko/model-config#opusplan-model-setting)으로 설정한 경우 이러한 서브에이전트가 Opus에서 실행되고, `haiku`로 설정한 경우 Sonnet에서 실행됩니다.