Documentation — Spybara

agent-sdk/agent-loop.md +395 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# 에이전트 루프의 작동 원리

7> 메시지 생명주기, 도구 실행, 컨텍스트 윈도우, 그리고 SDK 에이전트를 구동하는 아키텍처를 이해합니다.

9Agent SDK를 사용하면 Claude Code의 자율 에이전트 루프를 자신의 애플리케이션에 임베드할 수 있습니다. SDK는 도구, 권한, 비용 제한, 출력에 대한 프로그래밍 방식의 제어를 제공하는 독립형 패키지입니다. 이를 사용하기 위해 Claude Code CLI를 설치할 필요가 없습니다.

11에이전트를 시작하면 SDK는 [Claude Code를 구동하는 동일한 실행 루프](/ko/how-claude-code-works#the-agentic-loop)를 실행합니다: Claude가 프롬프트를 평가하고, 도구를 호출하여 조치를 취하고, 결과를 받고, 작업이 완료될 때까지 반복합니다. 이 페이지에서는 해당 루프 내에서 무엇이 일어나는지 설명하므로 에이전트를 효과적으로 구축, 디버그 및 최적화할 수 있습니다.

13## 루프 한눈에 보기

15모든 에이전트 세션은 동일한 주기를 따릅니다:

17<img src="https://mintcdn.com/claude-code/gvy2DIUELtNA8qD3/images/agent-loop-diagram.svg?fit=max&auto=format&n=gvy2DIUELtNA8qD3&q=85&s=192e1bd6c8a2950a16e5ee0b94e27e26" alt="에이전트 루프: 프롬프트 입력, Claude 평가, 도구 호출 또는 최종 답변으로 분기" width="680" height="150" data-path="images/agent-loop-diagram.svg" />

191. **프롬프트 수신.** Claude가 프롬프트, 시스템 프롬프트, 도구 정의, 대화 기록과 함께 프롬프트를 받습니다. SDK는 세션 메타데이터를 포함하는 서브타입 `"init"`이 있는 [`SystemMessage`](#message-types)를 생성합니다.

202. **평가 및 응답.** Claude가 현재 상태를 평가하고 진행 방법을 결정합니다. 텍스트로 응답하거나, 하나 이상의 도구 호출을 요청하거나, 둘 다 할 수 있습니다. SDK는 텍스트와 도구 호출 요청을 포함하는 [`AssistantMessage`](#message-types)를 생성합니다.

213. **도구 실행.** SDK가 요청된 각 도구를 실행하고 결과를 수집합니다. 각 도구 결과 세트가 다음 결정을 위해 Claude에게 다시 피드백됩니다. [hooks](/ko/agent-sdk/hooks)를 사용하여 도구 호출을 실행 전에 가로채고, 수정하거나, 차단할 수 있습니다.

224. **반복.** 2단계와 3단계가 주기로 반복됩니다. 각 전체 주기는 한 턴입니다. Claude는 도구 호출이 없는 응답을 생성할 때까지 도구를 계속 호출하고 결과를 처리합니다.

235. **결과 반환.** SDK는 텍스트 응답(도구 호출 없음)이 있는 최종 [`AssistantMessage`](#message-types)를 생성한 후, 최종 텍스트, 토큰 사용량, 비용, 세션 ID가 있는 [`ResultMessage`](#message-types)를 생성합니다.

25간단한 질문("여기 어떤 파일이 있나요?")은 `Glob`을 호출하고 결과로 응답하는 한두 턴이 걸릴 수 있습니다. 복잡한 작업("auth 모듈을 리팩토링하고 테스트를 업데이트하세요")은 많은 턴에 걸쳐 수십 개의 도구 호출을 연결할 수 있으며, 파일을 읽고, 코드를 편집하고, 테스트를 실행하며, Claude가 각 결과에 따라 접근 방식을 조정합니다.

27## 턴과 메시지

29턴은 루프 내의 한 왕복입니다: Claude가 도구 호출을 포함하는 출력을 생성하고, SDK가 해당 도구를 실행하고, 결과가 자동으로 Claude에게 다시 피드백됩니다. 이는 코드에 제어를 반환하지 않고 발생합니다. Claude가 도구 호출이 없는 출력을 생성할 때까지 턴이 계속되며, 이 시점에서 루프가 끝나고 최종 결과가 전달됩니다.

31프롬프트 "auth.ts의 실패한 테스트 수정"에 대한 전체 세션이 어떻게 보일 수 있는지 생각해 봅시다.

33먼저 SDK가 프롬프트를 Claude에게 보내고 세션 메타데이터가 있는 [`SystemMessage`](#message-types)를 생성합니다. 그러면 루프가 시작됩니다:

351. **턴 1:** Claude가 `Bash`를 호출하여 `npm test`를 실행합니다. SDK는 도구 호출이 있는 [`AssistantMessage`](#message-types)를 생성하고, 명령을 실행한 후, 출력(3개 실패)이 있는 [`UserMessage`](#message-types)를 생성합니다.

362. **턴 2:** Claude가 `auth.ts`와 `auth.test.ts`에서 `Read`를 호출합니다. SDK가 파일 내용을 반환하고 `AssistantMessage`를 생성합니다.

373. **턴 3:** Claude가 `Edit`를 호출하여 `auth.ts`를 수정한 후, `Bash`를 호출하여 `npm test`를 다시 실행합니다. 3개 테스트 모두 통과합니다. SDK는 `AssistantMessage`를 생성합니다.

384. **최종 턴:** Claude가 도구 호출이 없는 텍스트 전용 응답을 생성합니다: "auth 버그를 수정했고, 3개 테스트 모두 통과합니다." SDK는 이 텍스트가 있는 최종 `AssistantMessage`를 생성한 후, 비용 및 사용량이 있는 [`ResultMessage`](#message-types)를 생성합니다.

40이는 4턴이었습니다: 도구 호출이 있는 3턴, 최종 텍스트 전용 응답 1턴.

42`max_turns` / `maxTurns`로 루프를 제한할 수 있으며, 이는 도구 사용 턴만 계산합니다. 예를 들어, 위의 루프에서 `max_turns=2`는 편집 단계 전에 중지했을 것입니다. `max_budget_usd` / `maxBudgetUsd`를 사용하여 지출 임계값에 따라 턴을 제한할 수도 있습니다.

44제한이 없으면 Claude가 자체적으로 완료될 때까지 루프가 실행되며, 이는 잘 정의된 작업에는 괜찮지만 개방형 프롬프트("이 코드베이스를 개선하세요")에서는 오래 실행될 수 있습니다. 예산을 설정하는 것은 프로덕션 에이전트에 좋은 기본값입니다. 옵션 참조는 아래의 [턴과 예산](#turns-and-budget)을 참조하세요.

46## 메시지 타입

48루프가 실행되면 SDK는 메시지 스트림을 생성합니다. 각 메시지는 루프의 어느 단계에서 왔는지 알려주는 타입을 전달합니다. 5가지 핵심 타입은:

50* **`SystemMessage`:** 세션 생명주기 이벤트. `subtype` 필드가 이를 구분합니다: `"init"`은 첫 번째 메시지(세션 메타데이터)이고, `"compact_boundary"`는 [압축](#automatic-compaction) 후에 발생합니다. TypeScript에서 압축 경계는 `SDKSystemMessage`의 서브타입이 아니라 자체 [`SDKCompactBoundaryMessage`](/ko/agent-sdk/typescript#sdkcompactboundarymessage) 타입입니다.

51* **`AssistantMessage`:** 최종 텍스트 전용 응답을 포함하여 각 Claude 응답 후에 생성됩니다. 해당 턴의 텍스트 콘텐츠 블록과 도구 호출 블록을 포함합니다.

52* **`UserMessage`:** 각 도구 실행 후 Claude에게 다시 전송되는 도구 결과 콘텐츠와 함께 생성됩니다. 루프 중간에 스트리밍하는 모든 사용자 입력에 대해서도 생성됩니다.

53* **`StreamEvent`:** 부분 메시지가 활성화된 경우에만 생성됩니다. 원본 API 스트리밍 이벤트(텍스트 델타, 도구 입력 청크)를 포함합니다. [스트림 응답](/ko/agent-sdk/streaming-output)을 참조하세요.

54* **`ResultMessage`:** 에이전트 루프의 끝을 표시합니다. 최종 텍스트 결과, 토큰 사용량, 비용, 세션 ID를 포함합니다. `subtype` 필드를 확인하여 작업이 성공했는지 또는 제한에 도달했는지 확인합니다. `prompt_suggestion`과 같은 소수의 후행 시스템 이벤트가 이후에 도착할 수 있으므로 결과에서 중단하지 말고 스트림을 완료까지 반복합니다. [결과 처리](#handle-the-result)를 참조하세요.

56이 5가지 타입은 두 SDK 모두에서 전체 에이전트 루프 생명주기를 다룹니다. TypeScript SDK는 또한 추가 관찰성 이벤트(hook 이벤트, 도구 진행, 속도 제한, 작업 알림)를 생성하여 추가 세부 정보를 제공하지만 루프를 구동하는 데 필요하지 않습니다. [Python 메시지 타입 참조](/ko/agent-sdk/python#message-types)와 [TypeScript 메시지 타입 참조](/ko/agent-sdk/typescript#message-types)에서 전체 목록을 참조하세요.

58### 메시지 처리

60처리하는 메시지는 구축하는 것에 따라 다릅니다:

62* **최종 결과만:** `ResultMessage`를 처리하여 출력, 비용, 작업이 성공했는지 또는 제한에 도달했는지 확인합니다.

63* **진행 상황 업데이트:** `AssistantMessage`를 처리하여 Claude가 각 턴에서 무엇을 하고 있는지, 어떤 도구를 호출했는지 확인합니다.

64* **라이브 스트리밍:** 부분 메시지를 활성화하여(`include_partial_messages` Python, `includePartialMessages` TypeScript) 실시간으로 `StreamEvent` 메시지를 받습니다. [실시간 스트림 응답](/ko/agent-sdk/streaming-output)을 참조하세요.

66메시지 타입을 확인하는 방법은 SDK에 따라 다릅니다:

68* **Python:** `claude_agent_sdk`에서 가져온 클래스에 대해 `isinstance()`로 메시지 타입을 확인합니다(예: `isinstance(message, ResultMessage)`).

69* **TypeScript:** `type` 문자열 필드를 확인합니다(예: `message.type === "result"`). `AssistantMessage`와 `UserMessage`는 원본 API 메시지를 `.message` 필드에 래핑하므로 콘텐츠 블록은 `message.content`가 아니라 `message.message.content`에 있습니다.

71<Accordion title="예제: 메시지 타입 확인 및 결과 처리">

72 <CodeGroup>

73 ```python Python theme={null}

74 from claude_agent_sdk import query, AssistantMessage, ResultMessage

76 async for message in query(prompt="Summarize this project"):

77 if isinstance(message, AssistantMessage):

78 print(f"Turn completed: {len(message.content)} content blocks")

79 if isinstance(message, ResultMessage):

80 if message.subtype == "success":

81 print(message.result)

82 else:

83 print(f"Stopped: {message.subtype}")

84 ```

86 ```typescript TypeScript theme={null}

87 import { query } from "@anthropic-ai/claude-agent-sdk";

89 for await (const message of query({ prompt: "Summarize this project" })) {

90 if (message.type === "assistant") {

91 console.log(`Turn completed: ${message.message.content.length} content blocks`);

92 }

93 if (message.type === "result") {

94 if (message.subtype === "success") {

95 console.log(message.result);

96 } else {

97 console.log(`Stopped: ${message.subtype}`);

98 }

99 }

100 }

101 ```

102 </CodeGroup>

103</Accordion>

104

105## 도구 실행

106

107도구는 에이전트에게 조치를 취할 수 있는 능력을 제공합니다. 도구가 없으면 Claude는 텍스트로만 응답할 수 있습니다. 도구를 사용하면 Claude는 파일을 읽고, 명령을 실행하고, 코드를 검색하고, 외부 서비스와 상호작용할 수 있습니다.

108

109### 내장 도구

110

111SDK는 Claude Code를 구동하는 동일한 도구를 포함합니다:

112

113| 카테고리 | 도구 | 기능 |

114| :---------- | :----------------------------------------------- | :-------------------------------------- |

115| **파일 작업** | `Read`, `Edit`, `Write` | 파일 읽기, 수정, 생성 |

116| **검색** | `Glob`, `Grep` | 패턴으로 파일 찾기, 정규식으로 콘텐츠 검색 |

117| **실행** | `Bash` | 셸 명령, 스크립트, git 작업 실행 |

118| **웹** | `WebSearch`, `WebFetch` | 웹 검색, 페이지 가져오기 및 파싱 |

119| **검색** | `ToolSearch` | 모든 도구를 미리 로드하는 대신 필요에 따라 도구를 동적으로 찾고 로드 |

120| **오케스트레이션** | `Agent`, `Skill`, `AskUserQuestion`, `TodoWrite` | 서브에이전트 생성, 스킬 호출, 사용자에게 질문, 작업 추적 |

121

122내장 도구 외에도 다음을 수행할 수 있습니다:

123

124* **[MCP 서버](/ko/agent-sdk/mcp)로 외부 서비스 연결**(데이터베이스, 브라우저, API)

125* **[사용자 정의 도구 핸들러](/ko/agent-sdk/custom-tools)로 사용자 정의 도구 정의**

126* **[설정 소스](/ko/agent-sdk/claude-code-features)를 통해 프로젝트 스킬 로드** 재사용 가능한 워크플로우

127

128### 도구 권한

129

130Claude는 작업에 따라 호출할 도구를 결정하지만, 해당 호출이 실행되도록 허용할지 여부를 제어합니다. 특정 도구를 자동 승인하거나, 다른 도구를 완전히 차단하거나, 모든 것에 대해 승인을 요구할 수 있습니다. 3가지 옵션이 함께 작동하여 실행되는 것을 결정합니다:

131

132* **`allowed_tools` / `allowedTools`** 나열된 도구를 자동 승인합니다. `["Read", "Glob", "Grep"]`이 허용된 도구 목록에 있는 읽기 전용 에이전트는 프롬프트 없이 해당 도구를 실행합니다. 나열되지 않은 도구는 여전히 사용 가능하지만 권한이 필요합니다.

133* **`disallowed_tools` / `disallowedTools`** 다른 설정에 관계없이 나열된 도구를 차단합니다. 도구가 실행되기 전에 규칙이 확인되는 순서는 [권한](/ko/agent-sdk/permissions)을 참조하세요.

134* **`permission_mode` / `permissionMode`** 허용 또는 거부 규칙으로 다루지 않는 도구에 어떤 일이 발생하는지 제어합니다. 사용 가능한 모드는 [권한 모드](#permission-mode)를 참조하세요.

135

136`"Bash(npm *)"` 같은 규칙으로 개별 도구의 범위를 지정할 수도 있습니다. 전체 규칙 구문은 [권한](/ko/agent-sdk/permissions)을 참조하세요.

137

138도구가 거부되면 Claude는 도구 결과로 거부 메시지를 받고 일반적으로 다른 접근 방식을 시도하거나 진행할 수 없다고 보고합니다.

139

140### 병렬 도구 실행

141

142Claude가 단일 턴에서 여러 도구 호출을 요청하면 두 SDK 모두 도구에 따라 동시 또는 순차적으로 실행할 수 있습니다. 읽기 전용 도구(`Read`, `Glob`, `Grep`, 읽기 전용으로 표시된 MCP 도구)는 동시에 실행할 수 있습니다. 상태를 수정하는 도구(`Edit`, `Write`, `Bash`)는 충돌을 피하기 위해 순차적으로 실행됩니다.

143

144사용자 정의 도구는 기본적으로 순차 실행됩니다. 사용자 정의 도구에 대해 병렬 실행을 활성화하려면 주석에서 `readOnlyHint`를 설정합니다. [TypeScript](/ko/agent-sdk/typescript#tool)와 [Python](/ko/agent-sdk/python#tool) SDK 모두 MCP SDK의 이 필드 이름을 사용합니다.

145

146## 루프 실행 방식 제어

147

148루프가 취하는 턴 수, 비용, Claude가 추론하는 깊이, 도구가 실행 전에 승인을 요구하는지 여부를 제한할 수 있습니다. 이 모든 것은 [`ClaudeAgentOptions`](/ko/agent-sdk/python#claudeagentoptions)(Python) / [`Options`](/ko/agent-sdk/typescript#options)(TypeScript)의 필드입니다.

149

150### 턴과 예산

151

152| 옵션 | 제어 대상 | 기본값 |

153| :--------------------------------------- | :---------- | :---- |

154| 최대 턴(`max_turns` / `maxTurns`) | 최대 도구 사용 왕복 | 제한 없음 |

155| 최대 예산(`max_budget_usd` / `maxBudgetUsd`) | 중지 전 최대 비용 | 제한 없음 |

156

157제한 중 하나에 도달하면 SDK는 해당 오류 서브타입(`error_max_turns` 또는 `error_max_budget_usd`)이 있는 `ResultMessage`를 반환합니다. 이러한 서브타입을 확인하는 방법은 [결과 처리](#handle-the-result)를 참조하고, 구문은 [`ClaudeAgentOptions`](/ko/agent-sdk/python#claudeagentoptions) / [`Options`](/ko/agent-sdk/typescript#options)를 참조하세요.

158

159### 노력 수준

160

161`effort` 옵션은 Claude가 적용하는 추론의 양을 제어합니다. 낮은 노력 수준은 턴당 더 적은 토큰을 사용하고 비용을 줄입니다. 모든 모델이 노력 매개변수를 지원하는 것은 아닙니다. 어떤 모델이 지원하는지는 [노력](https://platform.claude.com/docs/en/build-with-claude/effort)을 참조하세요.

162

163| 수준 | 동작 | 적합한 경우 |

164| :--------- | :----------- | :-------------------------- |

165| `"low"` | 최소 추론, 빠른 응답 | 파일 조회, 디렉토리 나열 |

166| `"medium"` | 균형 잡힌 추론 | 일상적인 편집, 표준 작업 |

167| `"high"` | 철저한 분석 | 리팩토링, 디버깅 |

168| `"xhigh"` | 확장된 추론 깊이 | 코딩 및 에이전트 작업; Opus 4.7에서 권장 |

169| `"max"` | 최대 추론 깊이 | 깊은 분석이 필요한 다단계 문제 |

170

171`effort`를 설정하지 않으면 Python SDK는 매개변수를 설정하지 않은 상태로 두고 모델의 기본 동작으로 미룹니다. TypeScript SDK는 기본값으로 `"high"`를 사용합니다.

172

173<Note>

174 `effort`는 각 응답 내에서 추론 깊이에 대한 지연 시간과 토큰 비용을 교환합니다. [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)는 출력에서 보이는 사고의 연쇄 블록을 생성하는 별도의 기능입니다. 이들은 독립적입니다: `effort: "low"`를 확장 사고 활성화로 설정하거나, `effort: "max"`를 비활성화로 설정할 수 있습니다.

175</Note>

176

177간단하고 잘 정의된 작업(파일 나열 또는 단일 grep 실행)을 수행하는 에이전트의 경우 비용과 지연 시간을 줄이기 위해 낮은 노력을 사용합니다. 전체 세션에 대해 최상위 `query()` 옵션에서 `effort`를 설정하거나, [`AgentDefinition`](/ko/agent-sdk/subagents#agentdefinition-configuration)의 `effort` 필드로 서브에이전트당 설정하여 세션 수준을 재정의합니다.

178

179### 권한 모드

180

181권한 모드 옵션(Python의 `permission_mode`, TypeScript의 `permissionMode`)은 에이전트가 도구를 사용하기 전에 승인을 요청하는지 여부를 제어합니다:

182

183| 모드 | 동작 |

184| :-------------------- | :----------------------------------------------------------------------------------------------------------------- |

185| `"default"` | 허용 규칙으로 다루지 않는 도구는 승인 콜백을 트리거합니다; 콜백이 없으면 거부 |

186| `"acceptEdits"` | 파일 편집 및 일반적인 파일시스템 명령(`mkdir`, `touch`, `mv`, `cp` 등)을 자동 승인합니다; 다른 Bash 명령은 기본 규칙을 따릅니다 |

187| `"plan"` | 읽기 전용 도구 실행; Claude는 소스 파일을 편집하지 않고 탐색하고 계획을 생성합니다 |

188| `"dontAsk"` | 절대 프롬프트하지 않습니다. [권한 규칙](/ko/settings#permission-settings)으로 사전 승인된 도구가 실행되고, 나머지는 거부됩니다 |

189| `"auto"`(TypeScript만) | 모델 분류기를 사용하여 각 도구 호출을 승인하거나 거부합니다. 가용성 및 동작은 [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)를 참조하세요 |

190| `"bypassPermissions"` | 요청하지 않고 모든 허용된 도구를 실행합니다. Unix에서 루트로 실행할 때는 사용할 수 없습니다. 에이전트의 조치가 관심 있는 시스템에 영향을 미칠 수 없는 격리된 환경에서만 사용합니다 |

191

192대화형 애플리케이션의 경우 `"default"`를 도구 승인 콜백과 함께 사용하여 승인 프롬프트를 표시합니다. 개발 머신의 자율 에이전트의 경우 `"acceptEdits"`는 파일 편집 및 일반적인 파일시스템 명령(`mkdir`, `touch`, `mv`, `cp` 등)을 자동 승인하면서 다른 `Bash` 명령을 허용 규칙 뒤에 유지합니다. CI, 컨테이너 또는 기타 격리된 환경에 대해 `"bypassPermissions"`를 예약합니다. 전체 세부 정보는 [권한](/ko/agent-sdk/permissions)을 참조하세요.

193

194### 모델

195

196`model`을 설정하지 않으면 SDK는 Claude Code의 기본값을 사용하며, 이는 인증 방법 및 구독에 따라 다릅니다. 특정 모델을 고정하거나 더 빠르고 저렴한 에이전트를 위해 더 작은 모델을 사용하려면 명시적으로 설정합니다(예: `model="claude-sonnet-4-6"`). 사용 가능한 ID는 [모델](https://platform.claude.com/docs/en/about-claude/models)을 참조하세요.

197

198## 컨텍스트 윈도우

199

200컨텍스트 윈도우는 세션 중에 Claude가 사용할 수 있는 총 정보량입니다. 세션 내의 턴 사이에 재설정되지 않습니다. 모든 것이 누적됩니다: 시스템 프롬프트, 도구 정의, 대화 기록, 도구 입력, 도구 출력. 턴 전체에서 동일하게 유지되는 콘텐츠(시스템 프롬프트, 도구 정의, CLAUDE.md)는 자동으로 [프롬프트 캐시됩니다](https://platform.claude.com/docs/en/build-with-claude/prompt-caching). 이는 반복된 접두사에 대한 비용과 지연 시간을 줄입니다.

201

202### 컨텍스트를 소비하는 것

203

204SDK에서 각 구성 요소가 컨텍스트에 어떻게 영향을 미치는지는 다음과 같습니다:

205

206| 소스 | 로드 시기 | 영향 |

207| :--------------- | :---------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------ |

208| **시스템 프롬프트** | 모든 요청 | 작은 고정 비용, 항상 존재 |

209| **CLAUDE.md 파일** | 세션 시작, [`settingSources`](/ko/agent-sdk/claude-code-features)를 통해 | 모든 요청에서 전체 콘텐츠(프롬프트 캐시되므로 첫 번째 요청만 전체 비용 지불) |

210| **도구 정의** | 모든 요청 | 각 도구가 스키마를 추가합니다; 모든 도구를 한 번에 로드하는 대신 [MCP 도구 검색](/ko/agent-sdk/mcp#mcp-tool-search)을 사용하여 필요에 따라 도구 로드 |

211| **대화 기록** | 턴에 걸쳐 누적 | 각 턴으로 증가: 프롬프트, 응답, 도구 입력, 도구 출력 |

212| **스킬 설명** | 세션 시작, 설정 소스를 통해 | 짧은 요약; 전체 콘텐츠는 호출될 때만 로드 |

213

214큰 도구 출력은 상당한 컨텍스트를 소비합니다. 큰 파일을 읽거나 자세한 출력이 있는 명령을 실행하면 단일 턴에서 수천 개의 토큰을 사용할 수 있습니다. 컨텍스트는 턴에 걸쳐 누적되므로 많은 도구 호출이 있는 더 긴 세션은 짧은 세션보다 훨씬 더 많은 컨텍스트를 구축합니다.

215

216### 자동 압축

217

218컨텍스트 윈도우가 제한에 가까워지면 SDK는 자동으로 대화를 압축합니다: 더 오래된 기록을 요약하여 공간을 확보하고, 가장 최근의 교환과 주요 결정을 유지합니다. SDK는 이것이 발생할 때 스트림에서 `type: "system"`과 `subtype: "compact_boundary"`가 있는 메시지를 생성합니다(Python에서는 `SystemMessage`; TypeScript에서는 별도의 `SDKCompactBoundaryMessage` 타입).

219

220압축은 더 오래된 메시지를 요약으로 바꾸므로 대화 초기의 특정 지침이 보존되지 않을 수 있습니다. 지속적인 규칙은 초기 프롬프트가 아니라 CLAUDE.md에 속합니다([`settingSources`](/ko/agent-sdk/claude-code-features)를 통해 로드됨). CLAUDE.md 콘텐츠는 모든 요청에서 다시 주입되기 때문입니다.

221

222압축 동작을 여러 가지 방법으로 사용자 정의할 수 있습니다:

223

224* **CLAUDE.md의 요약 지침:** 압축기는 다른 컨텍스트처럼 CLAUDE.md를 읽으므로 요약할 때 보존할 내용을 알려주는 섹션을 포함할 수 있습니다. 섹션 헤더는 자유 형식입니다(매직 문자열이 아님); 압축기는 의도와 일치합니다.

225* **`PreCompact` hook:** 압축 전에 사용자 정의 로직을 실행합니다(예: 전체 기록을 보관). hook은 `trigger` 필드(`manual` 또는 `auto`)를 받습니다. [hooks](/ko/agent-sdk/hooks)를 참조하세요.

226* **수동 압축:** `/compact`를 프롬프트 문자열로 보내 필요에 따라 압축을 트리거합니다. (이 방식으로 전송된 슬래시 명령은 CLI 전용 바로 가기가 아니라 SDK 입력입니다. [SDK의 슬래시 명령](/ko/agent-sdk/slash-commands)을 참조하세요.)

227

228<Accordion title="예제: CLAUDE.md의 요약 지침">

229 프로젝트의 CLAUDE.md에 섹션을 추가하여 압축기에 보존할 내용을 알립니다. 헤더 이름은 특별하지 않습니다; 명확한 레이블을 사용합니다.

230

231 ```markdown CLAUDE.md theme={null}

232 # 요약 지침

233

234 이 대화를 요약할 때 항상 보존합니다:

235 - 현재 작업 목표 및 수용 기준

236 - 읽거나 수정한 파일 경로

237 - 테스트 결과 및 오류 메시지

238 - 결정 및 그 뒤의 추론

239 ```

240</Accordion>

241

242### 컨텍스트 효율성 유지

243

244장기 실행 에이전트를 위한 몇 가지 전략:

245

246* **서브작업에 서브에이전트 사용.** 각 서브에이전트는 새로운 대화로 시작합니다(이전 메시지 기록 없음, 자신의 시스템 프롬프트 및 CLAUDE.md 같은 프로젝트 수준 컨텍스트는 로드함). 부모의 턴을 보지 않으며, 최종 응답만 도구 결과로 부모에게 반환됩니다. 주 에이전트의 컨텍스트는 전체 서브작업 기록이 아니라 해당 요약으로 증가합니다. [서브에이전트가 상속하는 것](/ko/agent-sdk/subagents#what-subagents-inherit)을 참조하세요.

247* **도구를 선택적으로 사용합니다.** 모든 도구 정의는 컨텍스트 공간을 차지합니다. [`AgentDefinition`](/ko/agent-sdk/subagents#agentdefinition-configuration)의 `tools` 필드를 사용하여 서브에이전트를 필요한 최소 세트로 범위를 지정하고, [MCP 도구 검색](/ko/agent-sdk/mcp#mcp-tool-search)을 사용하여 모든 도구를 미리 로드하는 대신 필요에 따라 도구를 로드합니다.

248* **MCP 서버 비용을 주시합니다.** 각 MCP 서버는 모든 도구 스키마를 모든 요청에 추가합니다. 많은 도구가 있는 몇 개의 서버는 에이전트가 작업을 수행하기 전에 상당한 컨텍스트를 소비할 수 있습니다. `ToolSearch` 도구는 모든 도구를 미리 로드하는 대신 필요에 따라 도구를 로드하여 도움이 될 수 있습니다. [MCP 도구 검색](/ko/agent-sdk/mcp#mcp-tool-search)을 참조하세요.

249* **일상적인 작업에 낮은 노력을 사용합니다.** 파일을 읽거나 디렉토리를 나열하기만 하면 되는 에이전트의 경우 [노력](#effort-level)을 `"low"`로 설정합니다. 이는 토큰 사용량과 비용을 줄입니다.

250

251기능별 컨텍스트 비용의 자세한 분석은 [컨텍스트 비용 이해](/ko/features-overview#understand-context-costs)를 참조하세요.

252

253## 세션 및 연속성

254

255SDK와의 각 상호작용은 세션을 생성하거나 계속합니다. `ResultMessage.session_id`에서 세션 ID를 캡처합니다(두 SDK 모두에서 사용 가능). TypeScript SDK는 또한 init `SystemMessage`의 직접 필드로 노출합니다; Python에서는 `SystemMessage.data`에 중첩됩니다.

256

257재개할 때 이전 턴의 전체 컨텍스트가 복원됩니다: 읽은 파일, 수행된 분석, 취한 조치. 원본을 수정하지 않고 다른 접근 방식으로 분기하기 위해 세션을 포크할 수도 있습니다.

258

259재개, 계속, 포크 패턴의 전체 가이드는 [세션 관리](/ko/agent-sdk/sessions)를 참조하세요.

260

261<Note>

262 Python에서 `ClaudeSDKClient`는 여러 호출에 걸쳐 세션 ID를 자동으로 처리합니다. 세부 정보는 [Python SDK 참조](/ko/agent-sdk/python#choosing-between-query-and-claudesdkclient)를 참조하세요.

263</Note>

264

265## 결과 처리

266

267루프가 끝나면 `ResultMessage`는 무엇이 일어났는지 알려주고 출력을 제공합니다. `subtype` 필드(두 SDK 모두에서 사용 가능)는 종료 상태를 확인하는 주요 방법입니다.

268

269| 결과 서브타입 | 무엇이 일어났는가 | `result` 필드 사용 가능? |

270| :------------------------------------ | :---------------------------------- | :----------------: |

271| `success` | Claude가 정상적으로 작업을 완료했습니다 | 예 |

272| `error_max_turns` | 완료 전에 `maxTurns` 제한에 도달했습니다 | 아니오 |

273| `error_max_budget_usd` | 완료 전에 `maxBudgetUsd` 제한에 도달했습니다 | 아니오 |

274| `error_during_execution` | 오류가 루프를 중단했습니다(예: API 실패 또는 취소된 요청) | 아니오 |

275| `error_max_structured_output_retries` | 구조화된 출력 검증이 구성된 재시도 제한 후 실패했습니다 | 아니오 |

276

277`result` 필드(최종 텍스트 출력)는 `success` 변형에만 존재하므로 항상 읽기 전에 서브타입을 확인합니다. 모든 결과 서브타입은 `total_cost_usd`, `usage`, `num_turns`, `session_id`를 전달하므로 비용을 추적하고 오류 후에도 재개할 수 있습니다. Python에서 `total_cost_usd`와 `usage`는 선택적으로 입력되며 일부 오류 경로에서 `None`일 수 있으므로 형식을 지정하기 전에 보호합니다. `usage` 필드 해석에 대한 세부 정보는 [비용 및 사용량 추적](/ko/agent-sdk/cost-tracking)을 참조하세요.

278

279결과는 또한 모델이 최종 턴에서 생성을 중지한 이유를 나타내는 `stop_reason` 필드(`TypeScript에서 string | null`, Python에서 `str | None`)를 포함합니다. 일반적인 값은 `end_turn`(모델이 정상적으로 완료됨), `max_tokens`(출력 토큰 제한에 도달함), `refusal`(모델이 요청을 거부함)입니다. 오류 결과 서브타입에서 `stop_reason`은 루프가 끝나기 전의 마지막 어시스턴트 응답의 값을 전달합니다. 거부를 감지하려면 `stop_reason === "refusal"`(TypeScript) 또는 `stop_reason == "refusal"`(Python)을 확인합니다. 전체 타입은 [`SDKResultMessage`](/ko/agent-sdk/typescript#sdkresultmessage)(TypeScript) 또는 [`ResultMessage`](/ko/agent-sdk/python#resultmessage)(Python)을 참조하세요.

280

281## Hooks

282

283[Hooks](/ko/agent-sdk/hooks)는 루프의 특정 지점에서 발생하는 콜백입니다: 도구가 실행되기 전, 반환된 후, 에이전트가 완료될 때 등. 일반적으로 사용되는 일부 hooks는:

284

285| Hook | 발생 시기 | 일반적인 사용 |

286| :------------------------------- | :------------------ | :--------------- |

287| `PreToolUse` | 도구가 실행되기 전 | 입력 검증, 위험한 명령 차단 |

288| `PostToolUse` | 도구가 반환된 후 | 출력 감사, 부작용 트리거 |

289| `UserPromptSubmit` | 프롬프트가 전송될 때 | 프롬프트에 추가 컨텍스트 주입 |

290| `Stop` | 에이전트가 완료될 때 | 결과 검증, 세션 상태 저장 |

291| `SubagentStart` / `SubagentStop` | 서브에이전트가 생성되거나 완료될 때 | 병렬 작업 결과 추적 및 집계 |

292| `PreCompact` | 컨텍스트 압축 전 | 요약 전에 전체 기록 보관 |

293

294Hooks는 에이전트의 컨텍스트 윈도우 내가 아니라 애플리케이션 프로세스에서 실행되므로 컨텍스트를 소비하지 않습니다. Hooks는 또한 루프를 단락시킬 수 있습니다: 도구 호출을 거부하는 `PreToolUse` hook은 실행을 방지하고 Claude는 거부 메시지를 대신 받습니다.

295

296두 SDK 모두 위의 모든 이벤트를 지원합니다. TypeScript SDK는 Python이 아직 지원하지 않는 추가 이벤트를 포함합니다. 전체 이벤트 목록, SDK별 가용성, 전체 콜백 API는 [hooks로 실행 제어](/ko/agent-sdk/hooks)를 참조하세요.

297

298## 모두 함께 사용

299

300이 예제는 이 페이지의 주요 개념을 실패한 테스트를 수정하는 단일 에이전트로 결합합니다. 허용된 도구(자동 승인되므로 에이전트가 자율적으로 실행됨), 프로젝트 설정, 턴 및 추론 노력에 대한 안전 제한으로 에이전트를 구성합니다. 루프가 실행되면 잠재적 재개를 위해 세션 ID를 캡처하고, 최종 결과를 처리하고, 총 비용을 인쇄합니다.

301

302<CodeGroup>

303 ```python Python theme={null}

304 import asyncio

305 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

306

307

308 async def run_agent():

309 session_id = None

310

311 async for message in query(

312 prompt="Find and fix the bug causing test failures in the auth module",

313 options=ClaudeAgentOptions(

314 allowed_tools=[

315 "Read",

316 "Edit",

317 "Bash",

318 "Glob",

319 "Grep",

320 ], # Listing tools here auto-approves them (no prompting)

321 setting_sources=[

322 "project"

323 ], # Load CLAUDE.md, skills, hooks from current directory

324 max_turns=30, # Prevent runaway sessions

325 effort="high", # Thorough reasoning for complex debugging

326 ),

327 ):

328 # Handle the final result

329 if isinstance(message, ResultMessage):

330 session_id = message.session_id # Save for potential resumption

331

332 if message.subtype == "success":

333 print(f"Done: {message.result}")

334 elif message.subtype == "error_max_turns":

335 # Agent ran out of turns. Resume with a higher limit.

336 print(f"Hit turn limit. Resume session {session_id} to continue.")

337 elif message.subtype == "error_max_budget_usd":

338 print("Hit budget limit.")

339 else:

340 print(f"Stopped: {message.subtype}")

341 if message.total_cost_usd is not None:

342 print(f"Cost: ${message.total_cost_usd:.4f}")

343

344

345 asyncio.run(run_agent())

346 ```

347

348 ```typescript TypeScript theme={null}

349 import { query } from "@anthropic-ai/claude-agent-sdk";

350

351 let sessionId: string | undefined;

352

353 for await (const message of query({

354 prompt: "Find and fix the bug causing test failures in the auth module",

355 options: {

356 allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"], // Listing tools here auto-approves them (no prompting)

357 settingSources: ["project"], // Load CLAUDE.md, skills, hooks from current directory

358 maxTurns: 30, // Prevent runaway sessions

359 effort: "high" // Thorough reasoning for complex debugging

360 }

361 })) {

362 // Save the session ID to resume later if needed

363 if (message.type === "system" && message.subtype === "init") {

364 sessionId = message.session_id;

365 }

366

367 // Handle the final result

368 if (message.type === "result") {

369 if (message.subtype === "success") {

370 console.log(`Done: ${message.result}`);

371 } else if (message.subtype === "error_max_turns") {

372 // Agent ran out of turns. Resume with a higher limit.

373 console.log(`Hit turn limit. Resume session ${sessionId} to continue.`);

374 } else if (message.subtype === "error_max_budget_usd") {

375 console.log("Hit budget limit.");

376 } else {

377 console.log(`Stopped: ${message.subtype}`);

378 }

379 console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);

380 }

381 }

382 ```

383</CodeGroup>

384

385## 다음 단계

386

387이제 루프를 이해했으므로 구축하는 것에 따라 다음 위치로 이동합니다:

388

389* **아직 에이전트를 실행하지 않았나요?** [빠른 시작](/ko/agent-sdk/quickstart)으로 시작하여 SDK를 설치하고 끝에서 끝까지 실행되는 전체 예제를 확인합니다.

390* **프로젝트에 연결할 준비가 되었나요?** [CLAUDE.md, 스킬, 파일시스템 hooks 로드](/ko/agent-sdk/claude-code-features)하여 에이전트가 프로젝트 규칙을 자동으로 따르도록 합니다.

391* **대화형 UI를 구축하고 있나요?** [스트리밍](/ko/agent-sdk/streaming-output)을 활성화하여 루프가 실행되면서 라이브 텍스트 및 도구 호출을 표시합니다.

392* **에이전트가 할 수 있는 것에 대해 더 엄격한 제어가 필요하신가요?** [권한](/ko/agent-sdk/permissions)으로 도구 접근을 잠그고, [hooks](/ko/agent-sdk/hooks)를 사용하여 실행 전에 도구 호출을 감사, 차단 또는 변환합니다.

393* **장기 또는 비용이 많이 드는 작업을 실행하고 있나요?** 격리된 작업을 [서브에이전트](/ko/agent-sdk/subagents)로 오프로드하여 주 컨텍스트를 깔끔하게 유지합니다.

394

395에이전트 루프의 더 광범위한 개념적 그림(SDK 특정이 아님)은 [Claude Code의 작동 원리](/ko/how-claude-code-works)를 참조하세요.

agent-sdk/hooks.md +11 −11

Details

236콜백은 두 가지 필드 범주를 포함하는 객체를 반환합니다.236콜백은 두 가지 필드 범주를 포함하는 객체를 반환합니다.

237 237

238* **최상위 필드**는 대화를 제어합니다. `systemMessage`는 모델에 표시되는 메시지를 대화에 주입하고, `continue`(Python에서는 `continue_`)는 이 훅 후에 에이전트가 계속 실행되는지 여부를 결정합니다.238* **최상위 필드**는 대화를 제어합니다. `systemMessage`는 모델에 표시되는 메시지를 대화에 주입하고, `continue`(Python에서는 `continue_`)는 이 훅 후에 에이전트가 계속 실행되는지 여부를 결정합니다.

239* \*\*`hookSpecificOutput`\*\*은 현재 작업을 제어합니다. 내부의 필드는 훅 이벤트 유형에 따라 다릅니다. `PreToolUse` 훅의 경우 `permissionDecision`(`"allow"`, `"deny"`, 또는 `"ask"`), `permissionDecisionReason`, `updatedInput`을 설정하는 곳입니다. TypeScript SDK에서 `permissionDecision`은 또한 `"defer"`를 수락하여 쿼리를 종료하고 [나중에 재개](/ko/hooks#defer-a-tool-call-for-later)합니다. 이 값은 Python SDK에서 사용할 수 없습니다. `PostToolUse` 훅의 경우 `additionalContext`를 설정하여 도구 결과에 정보를 추가할 수 있습니다.239* \*\*`hookSpecificOutput`\*\*은 현재 작업을 제어합니다. 내부의 필드는 훅 이벤트 유형에 따라 다릅니다. `PreToolUse` 훅의 경우 `permissionDecision`(`"allow"`, `"deny"`, 또는 `"ask"`), `permissionDecisionReason`, `updatedInput`을 설정하는 곳입니다. TypeScript SDK에서 `permissionDecision`은 또한 `"defer"`를 수락하여 쿼리를 종료하고 [나중에 재개](/ko/hooks#defer-a-tool-call-for-later)합니다. 이 값은 Python SDK에서 사용할 수 없습니다. `PostToolUse` 훅의 경우 `additionalContext`를 설정하여 도구 결과에 정보를 추가하거나 `updatedToolOutput`을 설정하여 Claude가 보기 전에 도구의 출력을 완전히 바꿀 수 있습니다.

240 240

241변경 없이 작업을 허용하려면 `{}`를 반환합니다. SDK 콜백 훅은 [Claude Code 셸 명령 훅](/ko/hooks#json-output)과 동일한 JSON 출력 형식을 사용하며, 이는 모든 필드와 이벤트별 옵션을 문서화합니다. SDK 타입 정의는 [TypeScript](/ko/agent-sdk/typescript#sync-hook-json-output) 및 [Python](/ko/agent-sdk/python#sync-hook-json-output) SDK 참조를 참조하세요.241변경 없이 작업을 허용하려면 `{}`를 반환합니다. SDK 콜백 훅은 [Claude Code 셸 명령 훅](/ko/hooks#json-output)과 동일한 JSON 출력 형식을 사용하며, 이는 모든 필드와 이벤트별 옵션을 문서화합니다. SDK 타입 정의는 [TypeScript](/ko/agent-sdk/typescript#sync-hook-json-output) 및 [Python](/ko/agent-sdk/python#sync-hook-json-output) SDK 참조를 참조하세요.

242 242

417 ```417 ```

418</CodeGroup>418</CodeGroup>

419 419

420### 여러 훅 연결420### 여러 훅 등록

421 421

422훅은 배열에 나타나는 순서대로 실행됩니다. 각 훅을 단일 책임에 집중하고 복잡한 로직을 위해 여러 훅을 연결합니다.422이벤트가 발생하면 일치하는 모든 훅이 병렬로 실행됩니다. 권한 결정의 경우 가장 제한적인 결과가 우선합니다. 단일 `deny`는 다른 훅이 반환하는 것에 관계없이 도구 호출을 차단합니다. 완료 순서가 비결정적이므로 다른 훅이 먼저 실행되었다고 가정하지 않고 각 훅이 독립적으로 작동하도록 작성합니다.

423

424아래 예제는 모든 도구 호출에 대해 세 가지 독립적인 확인을 등록합니다.

423 425

424<CodeGroup>426<CodeGroup>

425 ```python Python theme={null}427 ```python Python theme={null}

426 options = ClaudeAgentOptions(428 options = ClaudeAgentOptions(

427 hooks={429 hooks={

428 "PreToolUse": [430 "PreToolUse": [

429 HookMatcher(hooks=[rate_limiter]), # 첫 번째: 속도 제한 확인431 HookMatcher(hooks=[authorization_check]),

430 HookMatcher(hooks=[authorization_check]), # 두 번째: 권한 확인432 HookMatcher(hooks=[input_validator]),

431 HookMatcher(hooks=[input_sanitizer]), # 세 번째: 입력 정제433 HookMatcher(hooks=[audit_logger]),

432 HookMatcher(hooks=[audit_logger]), # 마지막: 작업 기록

433 ]434 ]

434 }435 }

435 )436 )

439 const options = {440 const options = {

440 hooks: {441 hooks: {

441 PreToolUse: [442 PreToolUse: [

442 { hooks: [rateLimiter] }, // 첫 번째: 속도 제한 확인443 { hooks: [authorizationCheck] },

443 { hooks: [authorizationCheck] }, // 두 번째: 권한 확인444 { hooks: [inputValidator] },

444 { hooks: [inputSanitizer] }, // 세 번째: 입력 정제445 { hooks: [auditLogger] }

445 { hooks: [auditLogger] } // 마지막: 작업 기록

446 ]446 ]

447 }447 }

448 };448 };

agent-sdk/migration-guide.md +289 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Claude Agent SDK로 마이그레이션

7> Claude Code TypeScript 및 Python SDK를 Claude Agent SDK로 마이그레이션하기 위한 가이드

9## 개요

11Claude Code SDK의 이름이 **Claude Agent SDK**로 변경되었으며 설명서가 재구성되었습니다. 이 변경은 코딩 작업을 넘어 AI 에이전트를 구축하기 위한 SDK의 광범위한 기능을 반영합니다.

13## 변경 사항

15| 항목 | 이전 | 새로운 |

16| :----------------- | :-------------------------- | :------------------------------- |

17| **패키지 이름 (TS/JS)** | `@anthropic-ai/claude-code` | `@anthropic-ai/claude-agent-sdk` |

18| **Python 패키지** | `claude-code-sdk` | `claude-agent-sdk` |

19| **설명서 위치** | Claude Code 문서 | API 가이드 → Agent SDK 섹션 |

21<Note>

22 **설명서 변경 사항:** Agent SDK 설명서가 Claude Code 문서에서 API 가이드의 전용 [Agent SDK](/ko/agent-sdk/overview) 섹션으로 이동되었습니다. Claude Code 문서는 이제 CLI 도구 및 자동화 기능에 중점을 두고 있습니다.

23</Note>

25## 마이그레이션 단계

27### TypeScript/JavaScript 프로젝트의 경우

29**1. 이전 패키지 제거:**

31```bash theme={null}

32npm uninstall @anthropic-ai/claude-code

33```

35**2. 새 패키지 설치:**

37```bash theme={null}

38npm install @anthropic-ai/claude-agent-sdk

39```

41**3. 임포트 업데이트:**

43`@anthropic-ai/claude-code`에서 `@anthropic-ai/claude-agent-sdk`로 모든 임포트를 변경합니다:

45```typescript theme={null}

46// 이전

47import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";

49// 이후

50import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

51```

53**4. package.json 의존성 업데이트:**

55`package.json`에 패키지가 나열되어 있으면 업데이트합니다:

57이전:

59```json theme={null}

60{

61 "dependencies": {

62 "@anthropic-ai/claude-code": "^0.0.42"

63 }

64}

65```

67이후:

69```json theme={null}

70{

71 "dependencies": {

72 "@anthropic-ai/claude-agent-sdk": "^0.2.0"

73 }

74}

75```

77완료되었습니다! 다른 코드 변경은 필요하지 않습니다.

79### Python 프로젝트의 경우

81**1. 이전 패키지 제거:**

83```bash theme={null}

84pip uninstall claude-code-sdk

85```

87**2. 새 패키지 설치:**

89```bash theme={null}

90pip install claude-agent-sdk

91```

93**3. 임포트 업데이트:**

95`claude_code_sdk`에서 `claude_agent_sdk`로 모든 임포트를 변경합니다:

97```python theme={null}

98# 이전

99from claude_code_sdk import query, ClaudeCodeOptions

100

101# 이후

102from claude_agent_sdk import query, ClaudeAgentOptions

103```

104

105**4. 타입 이름 업데이트:**

106

107`ClaudeCodeOptions`를 `ClaudeAgentOptions`로 변경합니다:

108

109```python theme={null}

110# 이전

111from claude_code_sdk import query, ClaudeCodeOptions

112

113options = ClaudeCodeOptions(model="claude-opus-4-7")

114

115# 이후

116from claude_agent_sdk import query, ClaudeAgentOptions

117

118options = ClaudeAgentOptions(model="claude-opus-4-7")

119```

120

121**5. [주요 변경 사항](#breaking-changes) 검토**

122

123마이그레이션을 완료하는 데 필요한 코드 변경을 수행합니다.

124

125## 주요 변경 사항

126

127<Warning>

128 격리 및 명시적 구성을 개선하기 위해 Claude Agent SDK v0.1.0은 Claude Code SDK에서 마이그레이션하는 사용자를 위한 주요 변경 사항을 도입합니다. 마이그레이션하기 전에 이 섹션을 주의 깊게 검토하십시오.

129</Warning>

130

131### Python: ClaudeCodeOptions를 ClaudeAgentOptions로 이름 변경

132

133**변경 사항:** Python SDK 타입 `ClaudeCodeOptions`의 이름이 `ClaudeAgentOptions`로 변경되었습니다.

134

135**마이그레이션:**

136

137```python theme={null}

138# 이전 (claude-code-sdk)

139from claude_code_sdk import query, ClaudeCodeOptions

140

141options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

142

143# 이후 (claude-agent-sdk)

144from claude_agent_sdk import query, ClaudeAgentOptions

145

146options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

147```

148

149**변경 이유:** 타입 이름이 이제 "Claude Agent SDK" 브랜딩과 일치하며 SDK의 명명 규칙 전체에서 일관성을 제공합니다.

150

151### 시스템 프롬프트가 더 이상 기본값이 아님

152

153**변경 사항:** SDK는 더 이상 기본적으로 Claude Code의 시스템 프롬프트를 사용하지 않습니다.

154

155**마이그레이션:**

156

157<CodeGroup>

158 ```typescript TypeScript theme={null}

159 // 이전 (v0.0.x) - 기본적으로 Claude Code의 시스템 프롬프트 사용

160 const result = query({ prompt: "Hello" });

161

162 // 이후 (v0.1.0) - 기본적으로 최소 시스템 프롬프트 사용

163 // 이전 동작을 얻으려면 Claude Code의 프리셋을 명시적으로 요청합니다:

164 const result = query({

165 prompt: "Hello",

166 options: {

167 systemPrompt: { type: "preset", preset: "claude_code" }

168 }

169 });

170

171 // 또는 사용자 정의 시스템 프롬프트를 사용합니다:

172 const result = query({

173 prompt: "Hello",

174 options: {

175 systemPrompt: "You are a helpful coding assistant"

176 }

177 });

178 ```

179

180 ```python Python theme={null}

181 # 이전 (v0.0.x) - 기본적으로 Claude Code의 시스템 프롬프트 사용

182 async for message in query(prompt="Hello"):

183 print(message)

184

185 # 이후 (v0.1.0) - 기본적으로 최소 시스템 프롬프트 사용

186 # 이전 동작을 얻으려면 Claude Code의 프리셋을 명시적으로 요청합니다:

187 from claude_agent_sdk import query, ClaudeAgentOptions

188

189 async for message in query(

190 prompt="Hello",

191 options=ClaudeAgentOptions(

192 system_prompt={"type": "preset", "preset": "claude_code"} # 프리셋 사용

193 ),

194 ):

195 print(message)

196

197 # 또는 사용자 정의 시스템 프롬프트를 사용합니다:

198 async for message in query(

199 prompt="Hello",

200 options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),

201 ):

202 print(message)

203 ```

204</CodeGroup>

205

206**변경 이유:** SDK 애플리케이션에 더 나은 제어 및 격리를 제공합니다. 이제 Claude Code의 CLI 중심 지침을 상속하지 않고 사용자 정의 동작으로 에이전트를 구축할 수 있습니다.

207

208### 설정 소스 기본값

209

210이 기본값은 v0.1.0에서 잠시 변경되었다가 되돌려졌으므로 마이그레이션 조치가 필요하지 않습니다.

211

212**현재 동작:** `query()`에서 `settingSources`를 생략하면 CLI와 일치하는 사용자, 프로젝트 및 로컬 파일 시스템 설정이 로드됩니다. 여기에는 `~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, CLAUDE.md 파일 및 사용자 정의 명령이 포함됩니다.

213

214파일 시스템 설정에서 격리되어 실행하려면 빈 배열을 전달합니다:

215

216<CodeGroup>

217 ```typescript TypeScript theme={null}

218 const result = query({

219 prompt: "Hello",

220 options: {

221 settingSources: [] // 파일 시스템 설정이 로드되지 않음

222 }

223 });

224

225 // 또는 특정 소스만 로드합니다:

226 const result = query({

227 prompt: "Hello",

228 options: {

229 settingSources: ["project"] // 프로젝트 설정만

230 }

231 });

232 ```

233

234 ```python Python theme={null}

235 from claude_agent_sdk import query, ClaudeAgentOptions

236

237 async for message in query(

238 prompt="Hello",

239 options=ClaudeAgentOptions(setting_sources=[]), # 파일 시스템 설정이 로드되지 않음

240 ):

241 print(message)

242

243 # 또는 특정 소스만 로드합니다:

244 async for message in query(

245 prompt="Hello",

246 options=ClaudeAgentOptions(

247 setting_sources=["project"] # 프로젝트 설정만

248 ),

249 ):

250 print(message)

251 ```

252</CodeGroup>

253

254격리는 특히 CI/CD 파이프라인, 배포된 애플리케이션, 테스트 환경 및 로컬 사용자 정의가 유입되지 않아야 하는 다중 테넌트 시스템에 중요합니다.

255

256<Note>

257 SDK v0.1.0은 잠시 설정이 로드되지 않는 것으로 기본값을 설정했으나 이후 릴리스에서 되돌려졌습니다. Python SDK 0.1.59 이하는 빈 목록을 옵션 생략과 동일하게 처리했으므로 `setting_sources=[]`에 의존하기 전에 업그레이드하십시오. `settingSources`가 `[]`일 때 읽히는 입력에 대해서는 [settingSources가 제어하지 않는 것](/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control)을 참조하십시오.

258</Note>

259

260## 이름 변경 이유

261

262Claude Code SDK는 원래 코딩 작업을 위해 설계되었지만 모든 유형의 AI 에이전트를 구축하기 위한 강력한 프레임워크로 진화했습니다. 새로운 이름 "Claude Agent SDK"는 그 기능을 더 잘 반영합니다:

263

264* 비즈니스 에이전트 구축 (법률 보조원, 재무 고문, 고객 지원)

265* 전문화된 코딩 에이전트 생성 (SRE 봇, 보안 검토자, 코드 검토 에이전트)

266* 도구 사용, MCP 통합 등으로 모든 도메인에 대한 사용자 정의 에이전트 개발

267

268## 도움말 받기

269

270마이그레이션 중에 문제가 발생하면:

271

272**TypeScript/JavaScript의 경우:**

273

2741. 모든 임포트가 `@anthropic-ai/claude-agent-sdk`를 사용하도록 업데이트되었는지 확인합니다

2752. package.json에 새 패키지 이름이 있는지 확인합니다

2763. `npm install`을 실행하여 의존성이 업데이트되었는지 확인합니다

277

278**Python의 경우:**

279

2801. 모든 임포트가 `claude_agent_sdk`를 사용하도록 업데이트되었는지 확인합니다

2812. requirements.txt 또는 pyproject.toml에 새 패키지 이름이 있는지 확인합니다

2823. `pip install claude-agent-sdk`를 실행하여 패키지가 설치되었는지 확인합니다

283

284## 다음 단계

285

286* [Agent SDK 개요](/ko/agent-sdk/overview)를 탐색하여 사용 가능한 기능에 대해 알아봅니다

287* [TypeScript SDK 참조](/ko/agent-sdk/typescript)를 확인하여 자세한 API 설명서를 봅니다

288* [Python SDK 참조](/ko/agent-sdk/python)를 검토하여 Python 관련 설명서를 봅니다

289* [사용자 정의 도구](/ko/agent-sdk/custom-tools) 및 [MCP 통합](/ko/agent-sdk/mcp)에 대해 알아봅니다

agent-sdk/permissions.md +242 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# 권한 구성

7> 권한 모드, 훅, 선언적 허용/거부 규칙을 사용하여 에이전트가 도구를 사용하는 방식을 제어합니다.

9Claude Agent SDK는 Claude가 도구를 사용하는 방식을 관리하기 위한 권한 제어를 제공합니다. 권한 모드와 규칙을 사용하여 자동으로 허용되는 항목을 정의하고, [`canUseTool` 콜백](/ko/agent-sdk/user-input)을 사용하여 런타임에 나머지 모든 항목을 처리합니다.

11<Note>

12 이 페이지는 권한 모드와 규칙을 다룹니다. 사용자가 런타임에 도구 요청을 승인하거나 거부하는 대화형 승인 흐름을 구축하려면 [승인 및 사용자 입력 처리](/ko/agent-sdk/user-input)를 참조하세요.

13</Note>

15## 권한 평가 방식

17Claude가 도구를 요청할 때 SDK는 다음 순서로 권한을 확인합니다:

19<Steps>

20 <Step title="훅">

21 먼저 [훅](/ko/agent-sdk/hooks)을 실행합니다. 훅은 호출을 완전히 거부하거나 통과시킬 수 있습니다. `allow`를 반환하는 훅은 아래의 거부 및 요청 규칙을 건너뛰지 않습니다. 훅 결과와 관계없이 이러한 규칙들이 평가됩니다.

22 </Step>

24 <Step title="거부 규칙">

25 `deny` 규칙(`disallowed_tools` 및 [settings.json](/ko/settings#permission-settings)에서)을 확인합니다. 거부 규칙이 일치하면 `bypassPermissions` 모드에서도 도구가 차단됩니다.

26 </Step>

28 <Step title="권한 모드">

29 활성 [권한 모드](#permission-modes)를 적용합니다. `bypassPermissions`는 이 단계에 도달한 모든 항목을 승인합니다. `acceptEdits`는 파일 작업을 승인합니다. 다른 모드는 통과합니다.

30 </Step>

32 <Step title="허용 규칙">

33 `allow` 규칙(`allowed_tools` 및 settings.json에서)을 확인합니다. 규칙이 일치하면 도구가 승인됩니다.

34 </Step>

36 <Step title="canUseTool 콜백">

37 위의 어느 것으로도 해결되지 않으면 결정을 위해 [`canUseTool` 콜백](/ko/agent-sdk/user-input)을 호출합니다. `dontAsk` 모드에서는 이 단계를 건너뛰고 도구가 거부됩니다.

38 </Step>

39</Steps>

41<img src="https://mintcdn.com/claude-code/FEspvVUyRuaWjm0s/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=FEspvVUyRuaWjm0s&q=85&s=a1759b0cf4541281a9fdd8f5348228e8" alt="권한 평가 흐름 다이어그램" width="920" height="260" data-path="images/agent-sdk/permissions-flow.svg" />

43이 페이지는 **허용 및 거부 규칙**과 **권한 모드**에 중점을 둡니다. 다른 단계의 경우:

45* **훅:** 도구 요청을 허용, 거부 또는 수정하는 사용자 정의 코드를 실행합니다. [훅으로 실행 제어](/ko/agent-sdk/hooks)를 참조하세요.

46* **canUseTool 콜백:** 런타임에 사용자에게 승인을 요청합니다. [승인 및 사용자 입력 처리](/ko/agent-sdk/user-input)를 참조하세요.

48## 허용 및 거부 규칙

50`allowed_tools` 및 `disallowed_tools`(TypeScript: `allowedTools` / `disallowedTools`)는 위의 평가 흐름에서 허용 및 거부 규칙 목록에 항목을 추가합니다. 도구가 Claude에서 사용 가능한지 여부가 아니라 도구 호출이 승인되는지 여부를 제어합니다.

52| 옵션 | 효과 |

53| :------------------------------- | :--------------------------------------------------------------------------------- |

54| `allowed_tools=["Read", "Grep"]` | `Read` 및 `Grep`은 자동으로 승인됩니다. 여기에 나열되지 않은 도구는 여전히 존재하며 권한 모드 및 `canUseTool`로 통과합니다. |

55| `disallowed_tools=["Bash"]` | `Bash`는 항상 거부됩니다. 거부 규칙은 먼저 확인되며 `bypassPermissions`를 포함한 모든 권한 모드에서 유지됩니다. |

57잠금된 에이전트의 경우 `allowedTools`를 `permissionMode: "dontAsk"`와 쌍으로 사용합니다. 나열된 도구는 승인되고 다른 모든 항목은 프롬프트 대신 완전히 거부됩니다:

59```typescript theme={null}

60const options = {

61 allowedTools: ["Read", "Glob", "Grep"],

62 permissionMode: "dontAsk"

63};

64```

66<Warning>

67 **`allowed_tools`는 `bypassPermissions`를 제한하지 않습니다.** `allowed_tools`는 나열한 도구만 사전 승인합니다. 나열되지 않은 도구는 허용 규칙과 일치하지 않으며 권한 모드로 통과하며, 여기서 `bypassPermissions`는 이를 승인합니다. `allowed_tools=["Read"]`를 `permission_mode="bypassPermissions"`와 함께 설정하면 `Bash`, `Write`, `Edit`을 포함한 모든 도구가 여전히 승인됩니다. `bypassPermissions`가 필요하지만 특정 도구를 차단하려면 `disallowed_tools`를 사용합니다.

68</Warning>

70`.claude/settings.json`에서 허용, 거부 및 요청 규칙을 선언적으로 구성할 수도 있습니다. 이러한 규칙은 `project` 설정 소스가 활성화될 때 읽혀지며, 기본 `query()` 옵션에 대해 활성화됩니다. `setting_sources`(TypeScript: `settingSources`)를 명시적으로 설정하면 적용되도록 `"project"`를 포함합니다. 규칙 구문은 [권한 설정](/ko/settings#permission-settings)을 참조하세요.

72## 권한 모드

74권한 모드는 Claude가 도구를 사용하는 방식에 대한 전역 제어를 제공합니다. `query()`를 호출할 때 권한 모드를 설정하거나 스트리밍 세션 중에 동적으로 변경할 수 있습니다.

76### 사용 가능한 모드

78SDK는 다음 권한 모드를 지원합니다:

80| 모드 | 설명 | 도구 동작 |

81| :--------------------- | :---------- | :------------------------------------------------------------------------------------------------------- |

82| `default` | 표준 권한 동작 | 자동 승인 없음; 일치하지 않는 도구는 `canUseTool` 콜백을 트리거합니다 |

83| `dontAsk` | 프롬프트 대신 거부 | `allowed_tools` 또는 규칙으로 사전 승인되지 않은 항목은 거부됩니다; `canUseTool`은 호출되지 않습니다 |

84| `acceptEdits` | 파일 편집 자동 수락 | 파일 편집 및 [파일 시스템 작업](#accept-edits-mode-acceptedits)(`mkdir`, `rm`, `mv` 등)이 자동으로 승인됩니다 |

85| `bypassPermissions` | 모든 권한 확인 무시 | 모든 도구는 권한 프롬프트 없이 실행됩니다(주의해서 사용) |

86| `plan` | 계획 모드 | 읽기 전용 도구가 실행되고 Claude는 소스 파일을 편집하지 않고 분석 및 계획합니다 |

87| `auto`(TypeScript만 해당) | 모델 분류 승인 | 모델 분류기가 각 도구 호출을 승인하거나 거부합니다. 가용성은 [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)를 참조하세요 |

89<Warning>

90 **하위 에이전트 상속:** 부모가 `bypassPermissions`, `acceptEdits` 또는 `auto`를 사용할 때 모든 하위 에이전트는 해당 모드를 상속하며 하위 에이전트별로 재정의할 수 없습니다. 하위 에이전트는 주 에이전트와 다른 시스템 프롬프트와 덜 제한된 동작을 가질 수 있으므로 `bypassPermissions`를 상속하면 승인 프롬프트 없이 전체 자율 시스템 액세스 권한이 부여됩니다.

91</Warning>

93### 권한 모드 설정

95쿼리를 시작할 때 권한 모드를 한 번 설정하거나 세션이 활성화된 동안 동적으로 변경할 수 있습니다.

97<Tabs>

98 <Tab title="쿼리 시간에">

99 쿼리를 생성할 때 `permission_mode`(Python) 또는 `permissionMode`(TypeScript)를 전달합니다. 이 모드는 동적으로 변경되지 않는 한 전체 세션에 적용됩니다.

100

101 <CodeGroup>

102 ```python Python theme={null}

103 import asyncio

104 from claude_agent_sdk import query, ClaudeAgentOptions

105

106

107 async def main():

108 async for message in query(

109 prompt="Help me refactor this code",

110 options=ClaudeAgentOptions(

111 permission_mode="default", # Set the mode here

112 ),

113 ):

114 if hasattr(message, "result"):

115 print(message.result)

116

117

118 asyncio.run(main())

119 ```

120

121 ```typescript TypeScript theme={null}

122 import { query } from "@anthropic-ai/claude-agent-sdk";

123

124 async function main() {

125 for await (const message of query({

126 prompt: "Help me refactor this code",

127 options: {

128 permissionMode: "default" // Set the mode here

129 }

130 })) {

131 if ("result" in message) {

132 console.log(message.result);

133 }

134 }

135 }

136

137 main();

138 ```

139 </CodeGroup>

140 </Tab>

141

142 <Tab title="스트리밍 중">

143 `set_permission_mode()`(Python) 또는 `setPermissionMode()`(TypeScript)를 호출하여 세션 중간에 모드를 변경합니다. 새 모드는 모든 후속 도구 요청에 즉시 적용됩니다. 이를 통해 제한적으로 시작하여 신뢰가 구축됨에 따라 권한을 완화할 수 있습니다. 예를 들어 Claude의 초기 접근 방식을 검토한 후 `acceptEdits`로 전환할 수 있습니다.

144

145 <CodeGroup>

146 ```python Python theme={null}

147 import asyncio

148 from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

149

150

151 async def main():

152 async with ClaudeSDKClient(

153 options=ClaudeAgentOptions(

154 permission_mode="default", # Start in default mode

155 )

156 ) as client:

157 await client.query("Help me refactor this code")

158

159 # Change mode dynamically mid-session

160 await client.set_permission_mode("acceptEdits")

161

162 # Process messages with the new permission mode

163 async for message in client.receive_response():

164 if hasattr(message, "result"):

165 print(message.result)

166

167

168 asyncio.run(main())

169 ```

170

171 ```typescript TypeScript theme={null}

172 import { query } from "@anthropic-ai/claude-agent-sdk";

173

174 async function main() {

175 const q = query({

176 prompt: "Help me refactor this code",

177 options: {

178 permissionMode: "default" // Start in default mode

179 }

180 });

181

182 // Change mode dynamically mid-session

183 await q.setPermissionMode("acceptEdits");

184

185 // Process messages with the new permission mode

186 for await (const message of q) {

187 if ("result" in message) {

188 console.log(message.result);

189 }

190 }

191 }

192

193 main();

194 ```

195 </CodeGroup>

196 </Tab>

197</Tabs>

198

199### 모드 세부 정보

200

201#### 편집 수락 모드(`acceptEdits`)

202

203Claude가 프롬프트 없이 코드를 편집할 수 있도록 파일 작업을 자동으로 승인합니다. 다른 도구(예: 파일 시스템 작업이 아닌 Bash 명령)는 여전히 일반 권한이 필요합니다.

204

205**자동 승인 작업:**

206

207* 파일 편집(Edit, Write 도구)

208* 파일 시스템 명령: `mkdir`, `touch`, `rm`, `rmdir`, `mv`, `cp`, `sed`

209

210둘 다 작업 디렉토리 또는 `additionalDirectories` 내의 경로에만 적용됩니다. 해당 범위 외의 경로 및 보호된 경로에 대한 쓰기는 여전히 프롬프트합니다.

211

212**사용 시기:** Claude의 편집을 신뢰하고 프로토타이핑 중이거나 격리된 디렉토리에서 작업할 때와 같이 더 빠른 반복을 원할 때입니다.

213

214#### 요청 안 함 모드(`dontAsk`)

215

216모든 권한 프롬프트를 거부로 변환합니다. `allowed_tools`, `settings.json` 허용 규칙 또는 훅으로 사전 승인된 도구는 정상적으로 실행됩니다. 다른 모든 항목은 `canUseTool`을 호출하지 않고 거부됩니다.

217

218**사용 시기:** 헤드리스 에이전트에 대해 고정된 명시적 도구 표면을 원하고 `canUseTool`이 없을 때의 자동 거부보다 하드 거부를 선호할 때입니다.

219

220#### 권한 무시 모드(`bypassPermissions`)

221

222프롬프트 없이 모든 도구 사용을 자동으로 승인합니다. 훅은 여전히 실행되며 필요한 경우 작업을 차단할 수 있습니다.

223

224<Warning>

225 극도의 주의를 기울여 사용하세요. Claude는 이 모드에서 전체 시스템 액세스 권한을 가집니다. 모든 가능한 작업을 신뢰하는 제어된 환경에서만 사용하세요.

226

227 `allowed_tools`는 이 모드를 제한하지 않습니다. 나열한 도구뿐만 아니라 모든 도구가 승인됩니다. 거부 규칙(`disallowed_tools`), 명시적 `ask` 규칙 및 훅은 모드 확인 전에 평가되며 여전히 도구를 차단할 수 있습니다.

228</Warning>

229

230#### 계획 모드(`plan`)

231

232Claude를 읽기 전용 도구로 제한합니다. Claude는 파일을 읽고 읽기 전용 셸 명령을 실행하여 코드베이스를 탐색할 수 있지만 소스 파일을 편집하지 않습니다. Claude는 계획을 최종화하기 전에 요구 사항을 명확히 하기 위해 `AskUserQuestion`을 사용할 수 있습니다. 이러한 프롬프트 처리는 [승인 및 사용자 입력 처리](/ko/agent-sdk/user-input#handle-clarifying-questions)를 참조하세요.

233

234**사용 시기:** Claude가 변경 사항을 실행하지 않고 제안하기를 원할 때, 예를 들어 코드 검토 중이거나 변경 사항이 적용되기 전에 승인해야 할 때입니다.

235

236## 관련 리소스

237

238권한 평가 흐름의 다른 단계의 경우:

239

240* [승인 및 사용자 입력 처리](/ko/agent-sdk/user-input): 대화형 승인 프롬프트 및 명확히 하는 질문

241* [훅 가이드](/ko/agent-sdk/hooks): 에이전트 수명 주기의 주요 지점에서 사용자 정의 코드 실행

242* [권한 규칙](/ko/settings#permission-settings): `settings.json`의 선언적 허용/거부 규칙

agent-sdk/python.md +93 −91

Details

113#### 매개변수113#### 매개변수

114 114

115| 매개변수 | 타입 | 설명 |115| 매개변수 | 타입 | 설명 |

116| :------------- | :----------------------------------------------- | :------------------------------- |116| :------------- | :---------------------------------------------- | :------------------------------- |

117| `name` | `str` | 도구의 고유 식별자 |117| `name` | `str` | 도구의 고유 식별자 |

118| `description` | `str` | 도구가 수행하는 작업에 대한 인간이 읽을 수 있는 설명 |118| `description` | `str` | 도구가 수행하는 작업에 대한 인간이 읽을 수 있는 설명 |

121 121

122#### 입력 스키마 옵션122#### 입력 스키마 옵션

123 123

269| `cwd` | `str \| None` | 세션의 작업 디렉토리 |269| `cwd` | `str \| None` | 세션의 작업 디렉토리 |

270| `tag` | `str \| None` | 사용자가 설정한 세션 태그 ([`tag_session()`](#tag-session) 참조) |270| `tag` | `str \| None` | 사용자가 설정한 세션 태그 ([`tag_session()`](#tag_session) 참조) |

272 272

273#### 예제273#### 예제

343| `session_id` | `str` | 필수 | 조회할 세션의 UUID |343| `session_id` | `str` | 필수 | 조회할 세션의 UUID |

345 345

346[`SDKSessionInfo`](#return-type-sdk-session-info)를 반환하거나, 세션을 찾을 수 없으면 `None`을 반환합니다.346[`SDKSessionInfo`](#return-type-sdksessioninfo)를 반환하거나, 세션을 찾을 수 없으면 `None`을 반환합니다.

347 347

348#### 예제348#### 예제

349 349

381 381

382#### 예제382#### 예제

383 383

384가장 최신 세션의 이름을 바꿔서 나중에 찾기 쉽게 합니다. 새 제목은 이후 읽기에서 [`SDKSessionInfo.custom_title`](#return-type-sdk-session-info)에 나타납니다.384가장 최신 세션의 이름을 바꿔서 나중에 찾기 쉽게 합니다. 새 제목은 이후 읽기에서 [`SDKSessionInfo.custom_title`](#return-type-sdksessioninfo)에 나타납니다.

385 385

386```python theme={null}386```python theme={null}

387from claude_agent_sdk import list_sessions, rename_session387from claude_agent_sdk import list_sessions, rename_session

478| `rewind_files(user_message_id)` | 지정된 사용자 메시지의 상태로 파일 복원. `enable_file_checkpointing=True` 필요. [파일 체크포인팅](/ko/agent-sdk/file-checkpointing) 참조 |478| `rewind_files(user_message_id)` | 지정된 사용자 메시지의 상태로 파일 복원. `enable_file_checkpointing=True` 필요. [파일 체크포인팅](/ko/agent-sdk/file-checkpointing) 참조 |

482| `stop_task(task_id)` | 실행 중인 백그라운드 작업 중지. 상태 `"stopped"`인 [`TaskNotificationMessage`](#task-notification-message)가 메시지 스트림에서 따릅니다 |482| `stop_task(task_id)` | 실행 중인 백그라운드 작업 중지. 상태 `"stopped"`인 [`TaskNotificationMessage`](#tasknotificationmessage)가 메시지 스트림에서 따릅니다 |

485 485

791 effort: Literal["low", "medium", "high", "max"] | None = None791 effort: Literal["low", "medium", "high", "max"] | None = None

792 enable_file_checkpointing: bool = False792 enable_file_checkpointing: bool = False

793 session_store: SessionStore | None = None793 session_store: SessionStore | None = None

794 session_store_flush: SessionStoreFlushMode = "batched"

794```795```

795 796

796| 속성 | 타입 | 기본값 | 설명 |797| 속성 | 타입 | 기본값 | 설명 |

797| :---------------------------- | :------------------------------------------------------------------------------------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |798| :---------------------------- | :------------------------------------------------------------------------------------ | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

798| `tools` | `list[str] \| ToolsPreset \| None` | `None` | 도구 구성. Claude Code의 기본 도구를 위해 `{"type": "preset", "preset": "claude_code"}` 사용 |799| `tools` | `list[str] \| ToolsPreset \| None` | `None` | 도구 구성. Claude Code의 기본 도구를 위해 `{"type": "preset", "preset": "claude_code"}` 사용 |

799| `allowed_tools` | `list[str]` | `[]` | 프롬프트 없이 자동 승인할 도구. 이것은 Claude를 이 도구로만 제한하지 않습니다. 나열되지 않은 도구는 `permission_mode` 및 `can_use_tool`로 넘어갑니다. `disallowed_tools`를 사용하여 도구를 차단합니다. [권한](/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |800| `allowed_tools` | `list[str]` | `[]` | 프롬프트 없이 자동 승인할 도구. 이것은 Claude를 이 도구로만 제한하지 않습니다. 나열되지 않은 도구는 `permission_mode` 및 `can_use_tool`로 넘어갑니다. `disallowed_tools`를 사용하여 도구를 차단합니다. [권한](/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |

800| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | 시스템 프롬프트 구성. 사용자 정의 프롬프트의 경우 문자열을 전달하거나, Claude Code의 시스템 프롬프트를 위해 `{"type": "preset", "preset": "claude_code"}` 사용. 프리셋을 확장하려면 `"append"` 추가 |801| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | 시스템 프롬프트 구성. 사용자 정의 프롬프트의 경우 문자열을 전달하거나, Claude Code의 시스템 프롬프트를 위해 `{"type": "preset", "preset": "claude_code"}` 사용. 프리셋을 확장하려면 `"append"` 추가 |

812| `output_format` | `dict[str, Any] \| None` | `None` | 구조화된 응답을 위한 출력 형식 (예: `{"type": "json_schema", "schema": {...}}`). 자세한 내용은 [구조화된 출력](/ko/agent-sdk/structured-outputs) 참조 |813| `output_format` | `dict[str, Any] \| None` | `None` | 구조화된 응답을 위한 출력 형식 (예: `{"type": "json_schema", "schema": {...}}`). 자세한 내용은 [구조화된 출력](/ko/agent-sdk/structured-outputs) 참조 |

814| `cwd` | `str \| Path \| None` | `None` | 현재 작업 디렉토리 |815| `cwd` | `str \| Path \| None` | `None` | 현재 작업 디렉토리 |

831| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI 기본값: 모든 소스) | 로드할 파일 시스템 설정을 제어합니다. 사용자, 프로젝트 및 로컬 설정을 비활성화하려면 `[]`를 전달합니다. 관리형 정책 설정은 어쨌든 로드됩니다. [Claude Code 기능 사용](/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control)에서 이것이 제어하지 않는 입력 및 비활성화 방법 참조 |832| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI 기본값: 모든 소스) | 로드할 파일 시스템 설정을 제어합니다. 사용자, 프로젝트 및 로컬 설정을 비활성화하려면 `[]`를 전달합니다. 관리형 정책 설정은 어쨌든 로드됩니다. [Claude Code 기능 사용](/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control)에서 이것이 제어하지 않는 입력 및 비활성화 방법 참조 |

837| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | `session_store`에 미러링된 기록 항목을 플러시할 시기. `"batched"`는 턴당 한 번 또는 버퍼가 가득 찰 때 플러시합니다. `"eager"`는 모든 프레임 후에 백그라운드 플러시를 트리거합니다. `session_store`가 `None`일 때 무시됩니다 |

836 838

837### `OutputFormat`839### `OutputFormat`

838 840

1031| `maxTurns` | 아니오 | 에이전트가 중지되기 전의 최대 에이전트 턴 수 |1033| `maxTurns` | 아니오 | 에이전트가 중지되기 전의 최대 에이전트 턴 수 |

1032| `background` | 아니오 | 호출될 때 이 에이전트를 비차단 백그라운드 작업으로 실행합니다 |1034| `background` | 아니오 | 호출될 때 이 에이전트를 비차단 백그라운드 작업으로 실행합니다 |

1033| `effort` | 아니오 | 이 에이전트의 추론 노력 수준. 명명된 수준 또는 정수를 허용합니다 |1035| `effort` | 아니오 | 이 에이전트의 추론 노력 수준. 명명된 수준 또는 정수를 허용합니다 |

1034| `permissionMode` | 아니오 | 이 에이전트 내의 도구 실행을 위한 권한 모드. [`PermissionMode`](#permission-mode) 참조 |1036| `permissionMode` | 아니오 | 이 에이전트 내의 도구 실행을 위한 권한 모드. [`PermissionMode`](#permissionmode) 참조 |

1035 1037

1036<Note>1038<Note>

1037 `AgentDefinition` 필드 이름은 `disallowedTools`, `permissionMode`, `maxTurns`와 같은 camelCase를 사용합니다. 이 이름은 TypeScript SDK와 공유되는 와이어 형식에 직접 매핑됩니다. 이는 `disallowed_tools` 및 `permission_mode`와 같은 동등한 최상위 필드에 Python snake\_case를 사용하는 `ClaudeAgentOptions`와 다릅니다. `AgentDefinition`은 dataclass이므로, snake\_case 키워드를 전달하면 구성 시 `TypeError`를 발생시킵니다.1039 `AgentDefinition` 필드 이름은 `disallowedTools`, `permissionMode`, `maxTurns`와 같은 camelCase를 사용합니다. 이 이름은 TypeScript SDK와 공유되는 와이어 형식에 직접 매핑됩니다. 이는 `disallowed_tools` 및 `permission_mode`와 같은 동등한 최상위 필드에 Python snake\_case를 사용하는 `ClaudeAgentOptions`와 다릅니다. `AgentDefinition`은 dataclass이므로, snake\_case 키워드를 전달하면 구성 시 `TypeError`를 발생시킵니다.

1045PermissionMode = Literal[1047PermissionMode = Literal[

1046 "default", # Standard permission behavior1048 "default", # Standard permission behavior

1047 "acceptEdits", # Auto-accept file edits1049 "acceptEdits", # Auto-accept file edits

1048 "plan", # Planning mode - no execution1050 "plan", # Planning mode - read-only tools only

1049 "dontAsk", # Deny anything not pre-approved instead of prompting1051 "dontAsk", # Deny anything not pre-approved instead of prompting

1050 "bypassPermissions", # Bypass all permission checks (use with caution)1052 "bypassPermissions", # Bypass all permission checks (use with caution)

1051]1053]

1081```1083```

1082 1084

1083| 필드 | 타입 | 설명 |1085| 필드 | 타입 | 설명 |

1084| :------------ | :----------------------- | :------------------ |1086| :------------ | :----------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |

1087 1089

1088### `PermissionResult`1090### `PermissionResult`

1089 1091

1212 1214

1213이들은 `TypedDict` 클래스이므로 런타임에 일반 dict입니다. dict 리터럴로 구성하거나 클래스를 생성자처럼 호출합니다. 둘 다 `dict`를 생성합니다. `config.budget_tokens`가 아닌 `config["budget_tokens"]`로 필드에 접근합니다.1215이들은 `TypedDict` 클래스이므로 런타임에 일반 dict입니다. dict 리터럴로 구성하거나 클래스를 생성자처럼 호출합니다. 둘 다 `dict`를 생성합니다. `config.budget_tokens`가 아닌 `config["budget_tokens"]`로 필드에 접근합니다:

1214 1216

1215```python theme={null}1217```python theme={null}

1216from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled1218from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled

1289 1291

1290### `McpServerStatusConfig`1292### `McpServerStatusConfig`

1291 1293

1292[`get_mcp_status()`](#methods)에서 보고한 MCP 서버의 구성입니다. 이것은 모든 [`McpServerConfig`](#mcp-server-config) 전송 변형의 합집합에 claude.ai를 통해 프록시된 서버를 위한 출력 전용 `claudeai-proxy` 변형을 더한 것입니다.1294[`get_mcp_status()`](#methods)에서 보고한 MCP 서버의 구성입니다. 이것은 모든 [`McpServerConfig`](#mcpserverconfig) 전송 변형의 합집합에 claude.ai를 통해 프록시된 서버를 위한 출력 전용 `claudeai-proxy` 변형을 더한 것입니다.

1293 1295

1294```python theme={null}1296```python theme={null}

1295McpServerStatusConfig = (1297McpServerStatusConfig = (

1301)1303)

1302```1304```

1303 1305

1304`McpSdkServerConfigStatus`는 [`McpSdkServerConfig`](#mcp-sdk-server-config)의 직렬화 가능한 형식이며 `type` (`"sdk"`) 및 `name` (`str`) 필드만 있습니다. 인프로세스 `instance`는 생략됩니다. `McpClaudeAIProxyServerConfig`는 `type` (`"claudeai-proxy"`), `url` (`str`) 및 `id` (`str`) 필드를 가집니다.1306`McpSdkServerConfigStatus`는 [`McpSdkServerConfig`](#mcpsdkserverconfig)의 직렬화 가능한 형식이며 `type` (`"sdk"`) 및 `name` (`str`) 필드만 있습니다. 인프로세스 `instance`는 생략됩니다. `McpClaudeAIProxyServerConfig`는 `type` (`"claudeai-proxy"`), `url` (`str`) 및 `id` (`str`) 필드를 가집니다.

1305 1307

1306### `McpStatusResponse`1308### `McpStatusResponse`

1307 1309

1314 1316

1315### `McpServerStatus`1317### `McpServerStatus`

1316 1318

1317[`McpStatusResponse`](#mcp-status-response)에 포함된 연결된 MCP 서버의 상태입니다.1319[`McpStatusResponse`](#mcpstatusresponse)에 포함된 연결된 MCP 서버의 상태입니다.

1318 1320

1319```python theme={null}1321```python theme={null}

1320class McpServerStatus(TypedDict):1322class McpServerStatus(TypedDict):

1328```1330```

1329 1331

1330| 필드 | 타입 | 설명 |1332| 필드 | 타입 | 설명 |

1331| :----------- | :---------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |1333| :----------- | :------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------- |

1332| `name` | `str` | 서버 이름 |1334| `name` | `str` | 서버 이름 |

1333| `status` | `str` | `"connected"`, `"failed"`, `"needs-auth"`, `"pending"` 또는 `"disabled"` 중 하나 |1335| `status` | `str` | `"connected"`, `"failed"`, `"needs-auth"`, `"pending"` 또는 `"disabled"` 중 하나 |

1334| `serverInfo` | `dict` (선택사항) | 서버 이름 및 버전 (`{"name": str, "version": str}`) |1336| `serverInfo` | `dict` (선택사항) | 서버 이름 및 버전 (`{"name": str, "version": str}`) |

1336| `config` | [`McpServerStatusConfig`](#mcp-server-status-config) (선택사항) | 서버 구성. [`McpServerConfig`](#mcp-server-config)와 동일한 형태 (stdio, SSE, HTTP 또는 SDK), 더하기 claude.ai를 통해 연결된 서버를 위한 `claudeai-proxy` 변형 |1338| `config` | [`McpServerStatusConfig`](#mcpserverstatusconfig) (선택사항) | 서버 구성. [`McpServerConfig`](#mcpserverconfig)와 동일한 형태 (stdio, SSE, HTTP 또는 SDK), 더하기 claude.ai를 통해 연결된 서버를 위한 `claudeai-proxy` 변형 |

1339 1341

1416```1418```

1417 1419

1418| 필드 | 타입 | 설명 |1420| 필드 | 타입 | 설명 |

1419| :------------------- | :------------------------------------------------------------- | :------------------------------------------------------------ |1421| :------------------- | :----------------------------------------------------------- | :----------------------------------------------------------- |

1421| `model` | `str` | 응답을 생성한 모델 |1423| `model` | `str` | 응답을 생성한 모델 |

1426 1428

1427### `AssistantMessageError`1429### `AssistantMessageError`

1475`usage` dict는 존재할 때 다음 키를 포함합니다.1477`usage` dict는 존재할 때 다음 키를 포함합니다.

1476 1478

1477| 키 | 타입 | 설명 |1479| 키 | 타입 | 설명 |

1478| ----------------------------- | ----- | ----------------------- |1480| ----------------------------- | ----- | -------------------------- |

1479| `input_tokens` | `int` | 소비된 총 입력 토큰. |1481| `input_tokens` | `int` | 소비된 총 입력 토큰입니다. |

1480| `output_tokens` | `int` | 생성된 총 출력 토큰. |1482| `output_tokens` | `int` | 생성된 총 출력 토큰입니다. |

1481| `cache_creation_input_tokens` | `int` | 새 캐시 항목을 생성하는 데 사용된 토큰. |1483| `cache_creation_input_tokens` | `int` | 새 캐시 항목을 생성하는 데 사용된 토큰입니다. |

1482| `cache_read_input_tokens` | `int` | 기존 캐시 항목에서 읽은 토큰. |1484| `cache_read_input_tokens` | `int` | 기존 캐시 항목에서 읽은 토큰입니다. |

1483 1485

1484`model_usage` dict는 모델 이름을 모델별 사용량에 매핑합니다. 내부 dict 키는 camelCase를 사용합니다. 기본 CLI 프로세스에서 수정되지 않은 상태로 전달되므로 TypeScript [`ModelUsage`](/ko/agent-sdk/typescript#model-usage) 타입과 일치합니다.1486`model_usage` dict는 모델 이름을 모델별 사용량에 매핑합니다. 내부 dict 키는 camelCase를 사용합니다. 기본 CLI 프로세스에서 수정되지 않은 상태로 전달되므로 TypeScript [`ModelUsage`](/ko/agent-sdk/typescript#modelusage) 타입과 일치합니다.

1485 1487

1486| 키 | 타입 | 설명 |1488| 키 | 타입 | 설명 |

1487| -------------------------- | ------- | --------------------------------------------------------------------------------------- |1489| -------------------------- | ------- | ---------------------------------------------------------------------------------------------- |

1488| `inputTokens` | `int` | 이 모델의 입력 토큰. |1490| `inputTokens` | `int` | 이 모델의 입력 토큰입니다. |

1489| `outputTokens` | `int` | 이 모델의 출력 토큰. |1491| `outputTokens` | `int` | 이 모델의 출력 토큰입니다. |

1490| `cacheReadInputTokens` | `int` | 이 모델의 캐시 읽기 토큰. |1492| `cacheReadInputTokens` | `int` | 이 모델의 캐시 읽기 토큰입니다. |

1491| `cacheCreationInputTokens` | `int` | 이 모델의 캐시 생성 토큰. |1493| `cacheCreationInputTokens` | `int` | 이 모델의 캐시 생성 토큰입니다. |

1492| `webSearchRequests` | `int` | 이 모델이 수행한 웹 검색 요청. |1494| `webSearchRequests` | `int` | 이 모델이 수행한 웹 검색 요청입니다. |

1494| `contextWindow` | `int` | 이 모델의 컨텍스트 윈도우 크기. |1496| `contextWindow` | `int` | 이 모델의 컨텍스트 윈도우 크기입니다. |

1495| `maxOutputTokens` | `int` | 이 모델의 최대 출력 토큰 제한. |1497| `maxOutputTokens` | `int` | 이 모델의 최대 출력 토큰 제한입니다. |

1496 1498

1497### `StreamEvent`1499### `StreamEvent`

1498 1500

1508```1510```

1509 1511

1510| 필드 | 타입 | 설명 |1512| 필드 | 타입 | 설명 |

1511| :------------------- | :--------------- | :------------------------------- |1513| :------------------- | :--------------- | :---------------------------------- |

1512| `uuid` | `str` | 이 이벤트의 고유 식별자 |1514| `uuid` | `str` | 이 이벤트의 고유 식별자입니다 |

1513| `session_id` | `str` | 세션 식별자 |1515| `session_id` | `str` | 세션 식별자입니다 |

1516 1518

1517### `RateLimitEvent`1519### `RateLimitEvent`

1518 1520

1527```1529```

1528 1530

1529| 필드 | 타입 | 설명 |1531| 필드 | 타입 | 설명 |

1530| :---------------- | :---------------------------------- | :---------- |1532| :---------------- | :-------------------------------- | :------------- |

1532| `uuid` | `str` | 고유 이벤트 식별자 |1534| `uuid` | `str` | 고유 이벤트 식별자입니다 |

1533| `session_id` | `str` | 세션 식별자 |1535| `session_id` | `str` | 세션 식별자입니다 |

1534 1536

1535### `RateLimitInfo`1537### `RateLimitInfo`

1536 1538

1537[`RateLimitEvent`](#rate-limit-event)에 의해 전달되는 속도 제한 상태입니다.1539[`RateLimitEvent`](#ratelimitevent)에 의해 전달되는 속도 제한 상태입니다.

1538 1540

1539```python theme={null}1541```python theme={null}

1540RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]1542RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]

1556```1558```

1557 1559

1558| 필드 | 타입 | 설명 |1560| 필드 | 타입 | 설명 |

1559| :------------------------ | :------------------------ | :------------------------------------------------------------------------- |1561| :------------------------ | :------------------------ | :---------------------------------------------------------------------------- |

1567| `raw` | `dict[str, Any]` | 위에서 모델링되지 않은 필드를 포함한 CLI의 전체 원본 dict |1569| `raw` | `dict[str, Any]` | 위에서 모델링되지 않은 필드를 포함한 CLI의 전체 원본 dict입니다 |

1568 1570

1569### `TaskStartedMessage`1571### `TaskStartedMessage`

1570 1572

1571백그라운드 작업이 시작될 때 발생합니다. 백그라운드 작업은 주 턴 외부에서 추적되는 모든 것입니다: 백그라운드 Bash 명령, [Monitor](#monitor) 감시, Agent 도구를 통해 생성된 서브에이전트 또는 원격 에이전트. `task_type` 필드가 어느 것인지 알려줍니다. 이 명명은 `Task`-to-`Agent` 도구 이름 변경과 무관합니다.1573백그라운드 작업이 시작될 때 발생합니다. 백그라운드 작업은 주 턴 외부에서 추적되는 모든 것입니다: 백그라운드 Bash 명령, [Monitor](#monitor) 감시, Agent 도구를 통해 생성된 서브에이전트 또는 원격 에이전트입니다. `task_type` 필드가 어느 것인지 알려줍니다. 이 명명은 `Task`-to-`Agent` 도구 이름 변경과 무관합니다.

1572 1574

1573```python theme={null}1575```python theme={null}

1574@dataclass1576@dataclass

1582```1584```

1583 1585

1584| 필드 | 타입 | 설명 |1586| 필드 | 타입 | 설명 |

1585| :------------ | :------------ | :-------------------------------------------------------------------------------------------- |1587| :------------ | :------------ | :----------------------------------------------------------------------------------------------- |

1586| `task_id` | `str` | 작업의 고유 식별자 |1588| `task_id` | `str` | 작업의 고유 식별자입니다 |

1587| `description` | `str` | 작업의 설명 |1589| `description` | `str` | 작업의 설명입니다 |

1588| `uuid` | `str` | 고유 메시지 식별자 |1590| `uuid` | `str` | 고유 메시지 식별자입니다 |

1589| `session_id` | `str` | 세션 식별자 |1591| `session_id` | `str` | 세션 식별자입니다 |

1592 1594

1593### `TaskUsage`1595### `TaskUsage`

1594 1596

1618```1620```

1619 1621

1620| 필드 | 타입 | 설명 |1622| 필드 | 타입 | 설명 |

1621| :--------------- | :------------ | :------------------- |1623| :--------------- | :------------ | :---------------------- |

1622| `task_id` | `str` | 작업의 고유 식별자 |1624| `task_id` | `str` | 작업의 고유 식별자입니다 |

1623| `description` | `str` | 현재 상태 설명 |1625| `description` | `str` | 현재 상태 설명입니다 |

1625| `uuid` | `str` | 고유 메시지 식별자 |1627| `uuid` | `str` | 고유 메시지 식별자입니다 |

1626| `session_id` | `str` | 세션 식별자 |1628| `session_id` | `str` | 세션 식별자입니다 |

1629 1631

1630### `TaskNotificationMessage`1632### `TaskNotificationMessage`

1631 1633

1645```1647```

1646 1648

1647| 필드 | 타입 | 설명 |1649| 필드 | 타입 | 설명 |

1648| :------------ | :----------------------- | :-------------------------------------------- |1650| :------------ | :----------------------- | :----------------------------------------------- |

1649| `task_id` | `str` | 작업의 고유 식별자 |1651| `task_id` | `str` | 작업의 고유 식별자입니다 |

1651| `output_file` | `str` | 작업 출력 파일의 경로 |1653| `output_file` | `str` | 작업 출력 파일의 경로입니다 |

1652| `summary` | `str` | 작업 결과의 요약 |1654| `summary` | `str` | 작업 결과의 요약입니다 |

1653| `uuid` | `str` | 고유 메시지 식별자 |1655| `uuid` | `str` | 고유 메시지 식별자입니다 |

1654| `session_id` | `str` | 세션 식별자 |1656| `session_id` | `str` | 세션 식별자입니다 |

1657 1659

1658## 콘텐츠 블록 타입1660## 콘텐츠 블록 타입

1659 1661

1812 1814

1813매개변수:1815매개변수:

1814 1816

1815* `input`: `hook_event_name`을 기반으로 한 판별된 합집합이 있는 강타입 hook 입력 ([`HookInput`](#hook-input) 참조)1817* `input`: `hook_event_name`을 기반으로 한 판별된 합집합이 있는 강타입 hook 입력 ([`HookInput`](#hookinput) 참조)

1816* `tool_use_id`: 선택적 도구 사용 식별자 (도구 관련 hooks의 경우)1818* `tool_use_id`: 선택적 도구 사용 식별자 (도구 관련 hooks의 경우)

1817* `context`: 추가 정보가 있는 hook 컨텍스트1819* `context`: 추가 정보가 있는 hook 컨텍스트

1818 1820

1819다음을 포함할 수 있는 [`HookJSONOutput`](#hook-json-output)을 반환합니다.1821다음을 포함할 수 있는 [`HookJSONOutput`](#hookjsonoutput)을 반환합니다.

1820 1822

1821* `decision`: 작업을 차단하려면 `"block"`1823* `decision`: 작업을 차단하려면 `"block"`

1822* `systemMessage`: 기록에 추가할 시스템 메시지1824* `systemMessage`: 기록에 추가할 시스템 메시지

3109```3111```

3110 3112

3111| 속성 | 타입 | 기본값 | 설명 |3113| 속성 | 타입 | 기본값 | 설명 |

3112| :-------------------------- | :------------------------------------------------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3114| :-------------------------- | :---------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

3116| `allowUnsandboxedCommands` | `bool` | `True` | 모델이 샌드박스 외부에서 명령 실행을 요청하도록 허용합니다. `True`일 때, 모델은 도구 입력에서 `dangerouslyDisableSandbox`를 설정할 수 있으며, 이는 [권한 시스템](#permissions-fallback-for-unsandboxed-commands)으로 폴백됩니다 |3118| `allowUnsandboxedCommands` | `bool` | `True` | 모델이 샌드박스 외부에서 명령 실행을 요청하도록 허용합니다. `True`일 때, 모델은 도구 입력에서 `dangerouslyDisableSandbox`를 설정할 수 있으며, 이는 [권한 시스템](#permissions-fallback-for-unsandboxed-commands)으로 폴백됩니다 |

3120 3122

3121#### 사용 예제3123#### 사용 예제

agent-sdk/streaming-output.md +396 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# 실시간으로 응답 스트리밍하기

7> 텍스트와 도구 호출이 스트리밍될 때 Agent SDK에서 실시간 응답 받기

9기본적으로 Agent SDK는 Claude가 각 응답 생성을 완료한 후 완전한 `AssistantMessage` 객체를 생성합니다. 텍스트와 도구 호출이 생성될 때 증분 업데이트를 받으려면 옵션에서 `include_partial_messages`(Python) 또는 `includePartialMessages`(TypeScript)를 `true`로 설정하여 부분 메시지 스트리밍을 활성화하십시오.

11<Tip>

12 이 페이지는 출력 스트리밍(실시간으로 토큰 수신)을 다룹니다. 입력 모드(메시지 전송 방법)는 [에이전트에 메시지 전송하기](/ko/agent-sdk/streaming-vs-single-mode)를 참조하십시오. [CLI를 통해 Agent SDK를 사용하여 응답 스트리밍하기](/ko/headless)도 가능합니다.

13</Tip>

15## 스트리밍 출력 활성화

17스트리밍을 활성화하려면 옵션에서 `include_partial_messages`(Python) 또는 `includePartialMessages`(TypeScript)를 `true`로 설정하십시오. 이렇게 하면 SDK가 도착하는 대로 원본 API 이벤트를 포함하는 `StreamEvent` 메시지를 생성하며, 일반적인 `AssistantMessage` 및 `ResultMessage`도 함께 생성합니다.

19코드는 다음을 수행해야 합니다:

211. 각 메시지의 유형을 확인하여 `StreamEvent`를 다른 메시지 유형과 구분합니다

222. `StreamEvent`의 경우 `event` 필드를 추출하고 해당 `type`을 확인합니다

233. `delta.type`이 `text_delta`인 `content_block_delta` 이벤트를 찾습니다. 이 이벤트에는 실제 텍스트 청크가 포함됩니다

25아래 예제는 스트리밍을 활성화하고 도착하는 텍스트 청크를 인쇄합니다. 중첩된 유형 확인에 주목하십시오: 먼저 `StreamEvent`, 그 다음 `content_block_delta`, 그 다음 `text_delta`:

27<CodeGroup>

28 ```python Python theme={null}

29 from claude_agent_sdk import query, ClaudeAgentOptions

30 from claude_agent_sdk.types import StreamEvent

31 import asyncio

34 async def stream_response():

35 options = ClaudeAgentOptions(

36 include_partial_messages=True,

37 allowed_tools=["Bash", "Read"],

38 )

40 async for message in query(prompt="List the files in my project", options=options):

41 if isinstance(message, StreamEvent):

42 event = message.event

43 if event.get("type") == "content_block_delta":

44 delta = event.get("delta", {})

45 if delta.get("type") == "text_delta":

46 print(delta.get("text", ""), end="", flush=True)

49 asyncio.run(stream_response())

50 ```

52 ```typescript TypeScript theme={null}

53 import { query } from "@anthropic-ai/claude-agent-sdk";

55 for await (const message of query({

56 prompt: "List the files in my project",

57 options: {

58 includePartialMessages: true,

59 allowedTools: ["Bash", "Read"]

60 }

61 })) {

62 if (message.type === "stream_event") {

63 const event = message.event;

64 if (event.type === "content_block_delta") {

65 if (event.delta.type === "text_delta") {

66 process.stdout.write(event.delta.text);

67 }

68 }

69 }

70 }

71 ```

72</CodeGroup>

74## StreamEvent 참조

76부분 메시지가 활성화되면 객체로 래핑된 원본 Claude API 스트리밍 이벤트를 받습니다. 유형은 각 SDK에서 다른 이름을 가집니다:

78* **Python**: `StreamEvent` (`claude_agent_sdk.types`에서 가져오기)

79* **TypeScript**: `type: 'stream_event'`를 가진 `SDKPartialAssistantMessage`

81둘 다 누적된 텍스트가 아닌 원본 Claude API 이벤트를 포함합니다. 텍스트 델타를 직접 추출하고 누적해야 합니다. 각 유형의 구조는 다음과 같습니다:

83<CodeGroup>

84 ```python Python theme={null}

85 @dataclass

86 class StreamEvent:

87 uuid: str # Unique identifier for this event

88 session_id: str # Session identifier

89 event: dict[str, Any] # The raw Claude API stream event

90 parent_tool_use_id: str | None # Parent tool ID if from a subagent

91 ```

93 ```typescript TypeScript theme={null}

94 type SDKPartialAssistantMessage = {

95 type: "stream_event";

96 event: BetaRawMessageStreamEvent; // From Anthropic SDK

97 parent_tool_use_id: string | null;

98 uuid: UUID;

99 session_id: string;

100 };

101 ```

102</CodeGroup>

103

104`event` 필드는 [Claude API](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types)의 원본 스트리밍 이벤트를 포함합니다. 일반적인 이벤트 유형은 다음과 같습니다:

105

106| 이벤트 유형 | 설명 |

107| :-------------------- | :------------------------- |

108| `message_start` | 새 메시지의 시작 |

109| `content_block_start` | 새 콘텐츠 블록의 시작(텍스트 또는 도구 사용) |

110| `content_block_delta` | 콘텐츠에 대한 증분 업데이트 |

111| `content_block_stop` | 콘텐츠 블록의 끝 |

112| `message_delta` | 메시지 수준 업데이트(중지 이유, 사용량) |

113| `message_stop` | 메시지의 끝 |

114

115## 메시지 흐름

116

117부분 메시지가 활성화되면 다음 순서로 메시지를 받습니다:

118

119```text theme={null}

120StreamEvent (message_start)

121StreamEvent (content_block_start) - text block

122StreamEvent (content_block_delta) - text chunks...

123StreamEvent (content_block_stop)

124StreamEvent (content_block_start) - tool_use block

125StreamEvent (content_block_delta) - tool input chunks...

126StreamEvent (content_block_stop)

127StreamEvent (message_delta)

128StreamEvent (message_stop)

129AssistantMessage - complete message with all content

130... tool executes ...

131... more streaming events for next turn ...

132ResultMessage - final result

133```

134

135부분 메시지가 활성화되지 않은 경우(Python의 `include_partial_messages`, TypeScript의 `includePartialMessages`), `StreamEvent`를 제외한 모든 메시지 유형을 받습니다. 일반적인 유형에는 `SystemMessage`(세션 초기화), `AssistantMessage`(완전한 응답), `ResultMessage`(최종 결과) 및 대화 기록이 압축된 시점을 나타내는 컴팩트 경계 메시지(TypeScript의 `SDKCompactBoundaryMessage`; Python의 서브타입 `"compact_boundary"`를 가진 `SystemMessage`)가 포함됩니다.

136

137## 텍스트 응답 스트리밍

138

139생성되는 텍스트를 표시하려면 `delta.type`이 `text_delta`인 `content_block_delta` 이벤트를 찾습니다. 이 이벤트에는 증분 텍스트 청크가 포함됩니다. 아래 예제는 도착하는 각 청크를 인쇄합니다:

140

141<CodeGroup>

142 ```python Python theme={null}

143 from claude_agent_sdk import query, ClaudeAgentOptions

144 from claude_agent_sdk.types import StreamEvent

145 import asyncio

146

147

148 async def stream_text():

149 options = ClaudeAgentOptions(include_partial_messages=True)

150

151 async for message in query(prompt="Explain how databases work", options=options):

152 if isinstance(message, StreamEvent):

153 event = message.event

154 if event.get("type") == "content_block_delta":

155 delta = event.get("delta", {})

156 if delta.get("type") == "text_delta":

157 # Print each text chunk as it arrives

158 print(delta.get("text", ""), end="", flush=True)

159

160 print() # Final newline

161

162

163 asyncio.run(stream_text())

164 ```

165

166 ```typescript TypeScript theme={null}

167 import { query } from "@anthropic-ai/claude-agent-sdk";

168

169 for await (const message of query({

170 prompt: "Explain how databases work",

171 options: { includePartialMessages: true }

172 })) {

173 if (message.type === "stream_event") {

174 const event = message.event;

175 if (event.type === "content_block_delta" && event.delta.type === "text_delta") {

176 process.stdout.write(event.delta.text);

177 }

178 }

179 }

180

181 console.log(); // Final newline

182 ```

183</CodeGroup>

184

185## 도구 호출 스트리밍

186

187도구 호출도 증분적으로 스트리밍됩니다. 도구가 시작될 때를 추적하고, 생성되는 입력을 받고, 완료될 때를 볼 수 있습니다. 아래 예제는 현재 호출되는 도구를 추적하고 스트리밍되는 JSON 입력을 누적합니다. 세 가지 이벤트 유형을 사용합니다:

188

189* `content_block_start`: 도구 시작

190* `content_block_delta` with `input_json_delta`: 입력 청크 도착

191* `content_block_stop`: 도구 호출 완료

192

193<CodeGroup>

194 ```python Python theme={null}

195 from claude_agent_sdk import query, ClaudeAgentOptions

196 from claude_agent_sdk.types import StreamEvent

197 import asyncio

198

199

200 async def stream_tool_calls():

201 options = ClaudeAgentOptions(

202 include_partial_messages=True,

203 allowed_tools=["Read", "Bash"],

204 )

205

206 # Track the current tool and accumulate its input JSON

207 current_tool = None

208 tool_input = ""

209

210 async for message in query(prompt="Read the README.md file", options=options):

211 if isinstance(message, StreamEvent):

212 event = message.event

213 event_type = event.get("type")

214

215 if event_type == "content_block_start":

216 # New tool call is starting

217 content_block = event.get("content_block", {})

218 if content_block.get("type") == "tool_use":

219 current_tool = content_block.get("name")

220 tool_input = ""

221 print(f"Starting tool: {current_tool}")

222

223 elif event_type == "content_block_delta":

224 delta = event.get("delta", {})

225 if delta.get("type") == "input_json_delta":

226 # Accumulate JSON input as it streams in

227 chunk = delta.get("partial_json", "")

228 tool_input += chunk

229 print(f" Input chunk: {chunk}")

230

231 elif event_type == "content_block_stop":

232 # Tool call complete - show final input

233 if current_tool:

234 print(f"Tool {current_tool} called with: {tool_input}")

235 current_tool = None

236

237

238 asyncio.run(stream_tool_calls())

239 ```

240

241 ```typescript TypeScript theme={null}

242 import { query } from "@anthropic-ai/claude-agent-sdk";

243

244 // Track the current tool and accumulate its input JSON

245 let currentTool: string | null = null;

246 let toolInput = "";

247

248 for await (const message of query({

249 prompt: "Read the README.md file",

250 options: {

251 includePartialMessages: true,

252 allowedTools: ["Read", "Bash"]

253 }

254 })) {

255 if (message.type === "stream_event") {

256 const event = message.event;

257

258 if (event.type === "content_block_start") {

259 // New tool call is starting

260 if (event.content_block.type === "tool_use") {

261 currentTool = event.content_block.name;

262 toolInput = "";

263 console.log(`Starting tool: ${currentTool}`);

264 }

265 } else if (event.type === "content_block_delta") {

266 if (event.delta.type === "input_json_delta") {

267 // Accumulate JSON input as it streams in

268 const chunk = event.delta.partial_json;

269 toolInput += chunk;

270 console.log(` Input chunk: ${chunk}`);

271 }

272 } else if (event.type === "content_block_stop") {

273 // Tool call complete - show final input

274 if (currentTool) {

275 console.log(`Tool ${currentTool} called with: ${toolInput}`);

276 currentTool = null;

277 }

278 }

279 }

280 }

281 ```

282</CodeGroup>

283

284## 스트리밍 UI 구축

285

286이 예제는 텍스트와 도구 스트리밍을 응집력 있는 UI로 결합합니다. 에이전트가 현재 도구를 실행 중인지 추적하기 위해 `in_tool` 플래그를 사용하여 도구가 실행되는 동안 `[Using Read...]`와 같은 상태 표시기를 표시합니다. 도구에 없을 때 텍스트가 정상적으로 스트리밍되고, 도구 완료가 "done" 메시지를 트리거합니다. 이 패턴은 다단계 에이전트 작업 중에 진행 상황을 표시해야 하는 채팅 인터페이스에 유용합니다.

287

288<CodeGroup>

289 ```python Python theme={null}

290 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

291 from claude_agent_sdk.types import StreamEvent

292 import asyncio

293 import sys

294

295

296 async def streaming_ui():

297 options = ClaudeAgentOptions(

298 include_partial_messages=True,

299 allowed_tools=["Read", "Bash", "Grep"],

300 )

301

302 # Track whether we're currently in a tool call

303 in_tool = False

304

305 async for message in query(

306 prompt="Find all TODO comments in the codebase", options=options

307 ):

308 if isinstance(message, StreamEvent):

309 event = message.event

310 event_type = event.get("type")

311

312 if event_type == "content_block_start":

313 content_block = event.get("content_block", {})

314 if content_block.get("type") == "tool_use":

315 # Tool call is starting - show status indicator

316 tool_name = content_block.get("name")

317 print(f"\n[Using {tool_name}...]", end="", flush=True)

318 in_tool = True

319

320 elif event_type == "content_block_delta":

321 delta = event.get("delta", {})

322 # Only stream text when not executing a tool

323 if delta.get("type") == "text_delta" and not in_tool:

324 sys.stdout.write(delta.get("text", ""))

325 sys.stdout.flush()

326

327 elif event_type == "content_block_stop":

328 if in_tool:

329 # Tool call finished

330 print(" done", flush=True)

331 in_tool = False

332

333 elif isinstance(message, ResultMessage):

334 # Agent finished all work

335 print(f"\n\n--- Complete ---")

336

337

338 asyncio.run(streaming_ui())

339 ```

340

341 ```typescript TypeScript theme={null}

342 import { query } from "@anthropic-ai/claude-agent-sdk";

343

344 // Track whether we're currently in a tool call

345 let inTool = false;

346

347 for await (const message of query({

348 prompt: "Find all TODO comments in the codebase",

349 options: {

350 includePartialMessages: true,

351 allowedTools: ["Read", "Bash", "Grep"]

352 }

353 })) {

354 if (message.type === "stream_event") {

355 const event = message.event;

356

357 if (event.type === "content_block_start") {

358 if (event.content_block.type === "tool_use") {

359 // Tool call is starting - show status indicator

360 process.stdout.write(`\n[Using ${event.content_block.name}...]`);

361 inTool = true;

362 }

363 } else if (event.type === "content_block_delta") {

364 // Only stream text when not executing a tool

365 if (event.delta.type === "text_delta" && !inTool) {

366 process.stdout.write(event.delta.text);

367 }

368 } else if (event.type === "content_block_stop") {

369 if (inTool) {

370 // Tool call finished

371 console.log(" done");

372 inTool = false;

373 }

374 }

375 } else if (message.type === "result") {

376 // Agent finished all work

377 console.log("\n\n--- Complete ---");

378 }

379 }

380 ```

381</CodeGroup>

382

383## 알려진 제한 사항

384

385일부 SDK 기능은 스트리밍과 호환되지 않습니다:

386

387* **확장 사고**: `max_thinking_tokens`(Python) 또는 `maxThinkingTokens`(TypeScript)를 명시적으로 설정하면 `StreamEvent` 메시지가 생성되지 않습니다. 각 턴 후에만 완전한 메시지를 받습니다. 사고는 기본적으로 SDK에서 비활성화되므로 활성화하지 않으면 스트리밍이 작동합니다.

388* **구조화된 출력**: JSON 결과는 스트리밍 델타가 아닌 최종 `ResultMessage.structured_output`에만 나타납니다. 자세한 내용은 [구조화된 출력](/ko/agent-sdk/structured-outputs)을 참조하십시오.

389

390## 다음 단계

391

392이제 실시간으로 텍스트와 도구 호출을 스트리밍할 수 있으므로 다음 관련 항목을 살펴보십시오:

393

394* [대화형 vs 일회성 쿼리](/ko/agent-sdk/streaming-vs-single-mode): 사용 사례에 맞는 입력 모드 선택

395* [구조화된 출력](/ko/agent-sdk/structured-outputs): 에이전트에서 입력된 JSON 응답 받기

396* [권한](/ko/agent-sdk/permissions): 에이전트가 사용할 수 있는 도구 제어

agent-sdk/todo-tracking.md +189 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# 할일 목록

7> Claude Agent SDK를 사용하여 할일을 추적하고 표시하여 체계적인 작업 관리를 수행합니다

9할일 추적은 작업을 관리하고 사용자에게 진행 상황을 표시하는 구조화된 방법을 제공합니다. Claude Agent SDK에는 복잡한 워크플로우를 구성하고 사용자에게 작업 진행 상황을 알리는 데 도움이 되는 기본 제공 할일 기능이 포함되어 있습니다.

11### 할일 생명주기

13할일은 예측 가능한 생명주기를 따릅니다:

151. **생성됨** - 작업이 식별될 때 `pending`으로 생성됨

162. **활성화됨** - 작업이 시작될 때 `in_progress`로 활성화됨

173. **완료됨** - 작업이 성공적으로 완료될 때

184. **제거됨** - 그룹의 모든 작업이 완료될 때

20### 할일이 사용되는 경우

22SDK는 다음의 경우에 자동으로 할일을 생성합니다:

24* **복잡한 다단계 작업** - 3개 이상의 서로 다른 작업이 필요한 경우

25* **사용자 제공 작업 목록** - 여러 항목이 언급될 때

26* **중요한 작업** - 진행 상황 추적이 도움이 되는 경우

27* **명시적 요청** - 사용자가 할일 구성을 요청할 때

29## 예제

31### 할일 변경 모니터링

33<CodeGroup>

34 ```typescript TypeScript theme={null}

35 import { query } from "@anthropic-ai/claude-agent-sdk";

37 for await (const message of query({

38 prompt: "Optimize my React app performance and track progress with todos",

39 options: { maxTurns: 15 }

40 })) {

41 // Todo updates are reflected in the message stream

42 if (message.type === "assistant") {

43 for (const block of message.message.content) {

44 if (block.type === "tool_use" && block.name === "TodoWrite") {

45 const todos = block.input.todos;

47 console.log("Todo Status Update:");

48 todos.forEach((todo, index) => {

49 const status =

50 todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";

51 console.log(`${index + 1}. ${status} ${todo.content}`);

52 });

53 }

54 }

55 }

56 }

57 ```

59 ```python Python theme={null}

60 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

62 async for message in query(

63 prompt="Optimize my React app performance and track progress with todos",

64 options=ClaudeAgentOptions(max_turns=15),

65 ):

66 # Todo updates are reflected in the message stream

67 if isinstance(message, AssistantMessage):

68 for block in message.content:

69 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":

70 todos = block.input["todos"]

72 print("Todo Status Update:")

73 for i, todo in enumerate(todos):

74 status = (

75 "✅"

76 if todo["status"] == "completed"

77 else "🔧"

78 if todo["status"] == "in_progress"

79 else "❌"

80 )

81 print(f"{i + 1}. {status} {todo['content']}")

82 ```

83</CodeGroup>

85### 실시간 진행 상황 표시

87<CodeGroup>

88 ```typescript TypeScript theme={null}

89 import { query } from "@anthropic-ai/claude-agent-sdk";

91 class TodoTracker {

92 private todos: any[] = [];

94 displayProgress() {

95 if (this.todos.length === 0) return;

97 const completed = this.todos.filter((t) => t.status === "completed").length;

98 const inProgress = this.todos.filter((t) => t.status === "in_progress").length;

99 const total = this.todos.length;

100

101 console.log(`\nProgress: ${completed}/${total} completed`);

102 console.log(`Currently working on: ${inProgress} task(s)\n`);

103

104 this.todos.forEach((todo, index) => {

105 const icon =

106 todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";

107 const text = todo.status === "in_progress" ? todo.activeForm : todo.content;

108 console.log(`${index + 1}. ${icon} ${text}`);

109 });

110 }

111

112 async trackQuery(prompt: string) {

113 for await (const message of query({

114 prompt,

115 options: { maxTurns: 20 }

116 })) {

117 if (message.type === "assistant") {

118 for (const block of message.message.content) {

119 if (block.type === "tool_use" && block.name === "TodoWrite") {

120 this.todos = block.input.todos;

121 this.displayProgress();

122 }

123 }

124 }

125 }

126 }

127 }

128

129 // Usage

130 const tracker = new TodoTracker();

131 await tracker.trackQuery("Build a complete authentication system with todos");

132 ```

133

134 ```python Python theme={null}

135 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

136 from typing import List, Dict

137

138

139 class TodoTracker:

140 def __init__(self):

141 self.todos: List[Dict] = []

142

143 def display_progress(self):

144 if not self.todos:

145 return

146

147 completed = len([t for t in self.todos if t["status"] == "completed"])

148 in_progress = len([t for t in self.todos if t["status"] == "in_progress"])

149 total = len(self.todos)

150

151 print(f"\nProgress: {completed}/{total} completed")

152 print(f"Currently working on: {in_progress} task(s)\n")

153

154 for i, todo in enumerate(self.todos):

155 icon = (

156 "✅"

157 if todo["status"] == "completed"

158 else "🔧"

159 if todo["status"] == "in_progress"

160 else "❌"

161 )

162 text = (

163 todo["activeForm"]

164 if todo["status"] == "in_progress"

165 else todo["content"]

166 )

167 print(f"{i + 1}. {icon} {text}")

168

169 async def track_query(self, prompt: str):

170 async for message in query(prompt=prompt, options=ClaudeAgentOptions(max_turns=20)):

171 if isinstance(message, AssistantMessage):

172 for block in message.content:

173 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":

174 self.todos = block.input["todos"]

175 self.display_progress()

176

177

178 # Usage

179 tracker = TodoTracker()

180 await tracker.track_query("Build a complete authentication system with todos")

181 ```

182</CodeGroup>

183

184## 관련 문서

185

186* [TypeScript SDK 참고](/ko/agent-sdk/typescript)

187* [Python SDK 참고](/ko/agent-sdk/python)

188* [스트리밍 vs 단일 모드](/ko/agent-sdk/streaming-vs-single-mode)

189* [사용자 정의 도구](/ko/agent-sdk/custom-tools)

agent-sdk/typescript.md +35 −35

Details

41#### 매개변수41#### 매개변수

42 42

43| 매개변수 | 타입 | 설명 |43| 매개변수 | 타입 | 설명 |

~~44| :-------- | :---------------------------------------------------------------- | :-------------------------------------- |~~44| :-------- | :--------------------------------------------------------------- | :-------------------------------------- |

47 47

48#### 반환값48#### 반환값

49 49

~~50[`Query`](#query-object) 객체를 반환하며, 이는 추가 메서드를 포함하는 `AsyncGenerator<`[`SDKMessage`](#sdk-message)`, void>`를 확장합니다.~~50[`Query`](#query-object) 객체를 반환하며, 이는 추가 메서드를 포함하는 `AsyncGenerator<`[`SDKMessage`](#sdkmessage)`, void>`를 확장합니다.

51 51

52### `startup()`52### `startup()`

53 53

54프롬프트를 사용할 수 있기 전에 CLI 서브프로세스를 생성하고 초기화 핸드셰이크를 완료하여 미리 준비합니다. 반환된 [`WarmQuery`](#warm-query) 핸들은 나중에 프롬프트를 수락하고 이미 준비된 프로세스에 작성하므로, 첫 번째 `query()` 호출은 서브프로세스 생성 및 초기화 비용을 지불하지 않고 해결됩니다.54프롬프트를 사용할 수 있기 전에 CLI 서브프로세스를 생성하고 초기화 핸드셰이크를 완료하여 미리 준비합니다. 반환된 [`WarmQuery`](#warmquery) 핸들은 나중에 프롬프트를 수락하고 이미 준비된 프로세스에 작성하므로, 첫 번째 `query()` 호출은 서브프로세스 생성 및 초기화 비용을 지불하지 않고 해결됩니다.

55 55

56```typescript theme={null}56```typescript theme={null}

57function startup(params?: {57function startup(params?: {

69 69

70#### 반환값70#### 반환값

71 71

~~72서브프로세스가 생성되고 초기화 핸드셰이크를 완료하면 해결되는 `Promise<`[`WarmQuery`](#warm-query)`>`를 반환합니다.~~72서브프로세스가 생성되고 초기화 핸드셰이크를 완료하면 해결되는 `Promise<`[`WarmQuery`](#warmquery)`>`를 반환합니다.

73 73

74#### 예제74#### 예제

75 75

104#### 매개변수104#### 매개변수

105 105

106| 매개변수 | 타입 | 설명 |106| 매개변수 | 타입 | 설명 |

107| :------------ | :------------------------------------------------------------------ | :---------------------------------------------- |107| :------------ | :---------------------------------------------------------------- | :---------------------------------------------- |

112| `extras` | `{ annotations?: `[`ToolAnnotations`](#tool-annotations)` }` | 클라이언트에 동작 힌트를 제공하는 선택적 MCP 도구 주석 |112| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)` }` | 클라이언트에 동작 힌트를 제공하는 선택적 MCP 도구 주석 |

113 113

114#### `ToolAnnotations`114#### `ToolAnnotations`

115 115

177#### 반환 타입: `SDKSessionInfo`177#### 반환 타입: `SDKSessionInfo`

178 178

179| 속성 | 타입 | 설명 |179| 속성 | 타입 | 설명 |

180| :------------- | :-------------------- | :------------------------------------------------- |180| :------------- | :-------------------- | :------------------------------------------------ |

191 191

192#### 예제192#### 예제

217#### 매개변수217#### 매개변수

218 218

219| 매개변수 | 타입 | 기본값 | 설명 |219| 매개변수 | 타입 | 기본값 | 설명 |

220| :--------------- | :------- | :---------- | :------------------------------------------------- |220| :--------------- | :------- | :---------- | :------------------------------------------------ |

272 272

273[`SDKSessionInfo`](#return-type-sdk-session-info)를 반환하거나, 세션을 찾을 수 없으면 `undefined`를 반환합니다.273[`SDKSessionInfo`](#return-type-sdksessioninfo)를 반환하거나, 세션을 찾을 수 없으면 `undefined`를 반환합니다.

274 274

275### `renameSession()`275### `renameSession()`

276 276

328| `allowedTools` | `string[]` | `[]` | 프롬프트 없이 자동 승인할 도구입니다. 이것은 Claude를 이 도구들로만 제한하지 않습니다. 나열되지 않은 도구는 `permissionMode` 및 `canUseTool`로 넘어갑니다. `disallowedTools`를 사용하여 도구를 차단합니다. [권한](/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |328| `allowedTools` | `string[]` | `[]` | 프롬프트 없이 자동 승인할 도구입니다. 이것은 Claude를 이 도구들로만 제한하지 않습니다. 나열되지 않은 도구는 `permissionMode` 및 `canUseTool`로 넘어갑니다. `disallowedTools`를 사용하여 도구를 차단합니다. [권한](/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |

341| `extraArgs` | `Record<string, string \| null>` | `{}` | 추가 인수 |341| `extraArgs` | `Record<string, string \| null>` | `{}` | 추가 인수 |

344| `hooks` | `Partial<Record<`[`HookEvent`](#hook-event)`, `[`HookCallbackMatcher`](#hook-callback-matcher)`[]>>` | `{}` | 이벤트에 대한 훅 콜백 |344| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | 이벤트에 대한 훅 콜백 |

349| `mcpServers` | `Record<string, [`McpServerConfig`](#mcp-server-config)>` | `{}` | MCP 서버 구성 |349| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 서버 구성 |

351| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 에이전트 결과의 출력 형식을 정의합니다. [구조화된 출력](/ko/agent-sdk/structured-outputs) 참조 |351| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 에이전트 결과의 출력 형식을 정의합니다. [구조화된 출력](/ko/agent-sdk/structured-outputs) 참조 |

363| `settingSources` | [`SettingSource`](#setting-source)`[]` | CLI 기본값 (모든 소스) | 로드할 파일 시스템 설정을 제어합니다. 사용자, 프로젝트 및 로컬 설정을 비활성화하려면 `[]`을 전달합니다. 관리되는 정책 설정은 어쨌든 로드됩니다. [Claude Code 기능 사용](/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control) 참조 |363| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 기본값 (모든 소스) | 로드할 파일 시스템 설정을 제어합니다. 사용자, 프로젝트 및 로컬 설정을 비활성화하려면 `[]`을 전달합니다. 관리되는 정책 설정은 어쨌든 로드됩니다. [Claude Code 기능 사용](/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control) 참조 |

367| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (최소 프롬프트) | 시스템 프롬프트 구성입니다. 사용자 정의 프롬프트의 경우 문자열을 전달하거나, Claude Code의 시스템 프롬프트를 사용하려면 `{ type: 'preset', preset: 'claude_code' }`를 전달합니다. 프리셋 객체 형식을 사용할 때 `append`를 추가하여 추가 지침으로 확장하고, `excludeDynamicSections: true`를 설정하여 세션별 컨텍스트를 첫 번째 사용자 메시지로 이동하여 [머신 간 프롬프트 캐시 재사용 개선](/ko/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |367| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (최소 프롬프트) | 시스템 프롬프트 구성입니다. 사용자 정의 프롬프트의 경우 문자열을 전달하거나, Claude Code의 시스템 프롬프트를 사용하려면 `{ type: 'preset', preset: 'claude_code' }`를 전달합니다. 프리셋 객체 형식을 사용할 때 `append`를 추가하여 추가 지침으로 확장하고, `excludeDynamicSections: true`를 설정하여 세션별 컨텍스트를 첫 번째 사용자 메시지로 이동하여 [머신 간 프롬프트 캐시 재사용 개선](/ko/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

368| `thinking` | [`ThinkingConfig`](#thinking-config) | 지원되는 모델의 경우 `{ type: 'adaptive' }` | Claude의 사고/추론 동작을 제어합니다. [`ThinkingConfig`](#thinking-config) 참조 |368| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 지원되는 모델의 경우 `{ type: 'adaptive' }` | Claude의 사고/추론 동작을 제어합니다. [`ThinkingConfig`](#thinkingconfig) 참조 |

370| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | 도구 구성입니다. 도구 이름의 배열을 전달하거나 프리셋을 사용하여 Claude Code의 기본 도구를 가져옵니다 |370| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | 도구 구성입니다. 도구 이름의 배열을 전달하거나 프리셋을 사용하여 Claude Code의 기본 도구를 가져옵니다 |

371 371

372### `Query` 객체372### `Query` 객체

493| `background` | 아니오 | 호출될 때 이 에이전트를 비차단 백그라운드 작업으로 실행 |493| `background` | 아니오 | 호출될 때 이 에이전트를 비차단 백그라운드 작업으로 실행 |

494| `memory` | 아니오 | 이 에이전트의 메모리 소스: `'user'`, `'project'` 또는 `'local'` |494| `memory` | 아니오 | 이 에이전트의 메모리 소스: `'user'`, `'project'` 또는 `'local'` |

495| `effort` | 아니오 | 이 에이전트의 추론 노력 수준입니다. 명명된 수준 또는 정수를 허용합니다 |495| `effort` | 아니오 | 이 에이전트의 추론 노력 수준입니다. 명명된 수준 또는 정수를 허용합니다 |

496| `permissionMode` | 아니오 | 이 에이전트 내 도구 실행을 위한 권한 모드입니다. [`PermissionMode`](#permission-mode) 참조 |496| `permissionMode` | 아니오 | 이 에이전트 내 도구 실행을 위한 권한 모드입니다. [`PermissionMode`](#permissionmode) 참조 |

497| `criticalSystemReminder_EXPERIMENTAL` | 아니오 | 실험적: 시스템 프롬프트에 추가된 중요한 알림 |497| `criticalSystemReminder_EXPERIMENTAL` | 아니오 | 실험적: 시스템 프롬프트에 추가된 중요한 알림 |

498 498

499### `AgentMcpServerSpec`499### `AgentMcpServerSpec`

626 | "default" // 표준 권한 동작626 | "default" // 표준 권한 동작

627 | "acceptEdits" // 파일 편집 자동 수락627 | "acceptEdits" // 파일 편집 자동 수락

628 | "bypassPermissions" // 모든 권한 확인 무시628 | "bypassPermissions" // 모든 권한 확인 무시

629 | "plan" // 계획 모드 - 실행 없음629 | "plan" // 계획 모드 - 읽기 전용 도구만

630 | "dontAsk" // 권한에 대해 프롬프트하지 않음, 미리 승인되지 않으면 거부630 | "dontAsk" // 권한에 대해 프롬프트하지 않음, 미리 승인되지 않으면 거부

631 | "auto"; // 모델 분류기를 사용하여 각 도구 호출을 승인 또는 거부631 | "auto"; // 모델 분류기를 사용하여 각 도구 호출을 승인 또는 거부

632```632```

651```651```

652 652

653| 옵션 | 타입 | 설명 |653| 옵션 | 타입 | 설명 |

654| :--------------- | :------------------------------------------- | :-------------------------------------- |654| :--------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

656| `suggestions` | [`PermissionUpdate`](#permission-update)`[]` | 사용자가 이 도구에 대해 다시 프롬프트되지 않도록 제안된 권한 업데이트 |656| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | 사용자가 이 도구에 대해 다시 프롬프트되지 않도록 제안된 권한 업데이트입니다. Bash 프롬프트는 `localSettings` [대상](#permissionupdatedestination)을 포함하는 제안을 포함하므로 `updatedPermissions`에서 반환하면 규칙을 `.claude/settings.local.json`에 작성하고 세션 간에 유지합니다. |

2379 | McpClaudeAIProxyServerConfig;2379 | McpClaudeAIProxyServerConfig;

2380```2380```

2381 2381

2382각 전송 타입의 세부 정보는 [`McpServerConfig`](#mcp-server-config)를 참조하세요.2382각 전송 타입의 세부 정보는 [`McpServerConfig`](#mcpserverconfig)를 참조하세요.

2383 2383

2384### `AccountInfo`2384### `AccountInfo`

2385 2385

2825```2825```

2826 2826

2827| 속성 | 타입 | 기본값 | 설명 |2827| 속성 | 타입 | 기본값 | 설명 |

2828| :-------------------------- | :------------------------------------------------------ | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2828| :-------------------------- | :---------------------------------------------------- | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

2832| `allowUnsandboxedCommands` | `boolean` | `true` | 모델이 샌드박스 외부에서 명령을 실행하도록 요청하도록 허용합니다. `true`일 때 모델은 도구 입력에서 `dangerouslyDisableSandbox`를 설정할 수 있으며, 이는 [권한 시스템](#permissions-fallback-for-unsandboxed-commands)으로 폴백됩니다 |2832| `allowUnsandboxedCommands` | `boolean` | `true` | 모델이 샌드박스 외부에서 명령을 실행하도록 요청하도록 허용합니다. `true`일 때 모델은 도구 입력에서 `dangerouslyDisableSandbox`를 설정할 수 있으며, 이는 [권한 시스템](#permissions-fallback-for-unsandboxed-commands)으로 폴백됩니다 |

2835| `ignoreViolations` | `Record<string, string[]>` | `undefined` | 무시할 위반 카테고리를 패턴에 매핑합니다 (예: `{ file: ['/tmp/*'], network: ['localhost'] }`) |2835| `ignoreViolations` | `Record<string, string[]>` | `undefined` | 무시할 위반 카테고리를 패턴에 매핑합니다 (예: `{ file: ['/tmp/*'], network: ['localhost'] }`) |

2837| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | 샌드박스 환경을 위한 사용자 정의 ripgrep 바이너리 구성 |2837| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | 샌드박스 환경을 위한 사용자 정의 ripgrep 바이너리 구성 |

data-usage.md +1 −1

Details

67 67

68아래 다이어그램은 설치 및 정상 작동 중에 Claude Code가 외부 서비스에 어떻게 연결되는지 보여줍니다. 실선은 필수 연결을 나타내고, 점선은 선택적 또는 사용자가 시작한 데이터 흐름을 나타냅니다.68아래 다이어그램은 설치 및 정상 작동 중에 Claude Code가 외부 서비스에 어떻게 연결되는지 보여줍니다. 실선은 필수 연결을 나타내고, 점선은 선택적 또는 사용자가 시작한 데이터 흐름을 나타냅니다.

69 69

70<img src="https://mintcdn.com/claude-code/YcBW2H7CArGcduPb/images/claude-code-data-flow.svg?fit=max&auto=format&n=YcBW2H7CArGcduPb&q=85&s=b600a89f84fc86f9ff7be00a466c0635" alt="Claude Code의 외부 연결을 보여주는 다이어그램: 설치/업데이트는 배포 서버에 연결되고, 사용자 요청은 Console auth, public-api, 그리고 선택적으로 Statsig, Sentry, 버그 보고를 포함한 Anthropic 서비스에 연결됩니다" width="720" height="520" data-path="images/claude-code-data-flow.svg" />70<img src="https://mintcdn.com/claude-code/RcOyXc06Ja8cuvMZ/images/claude-code-data-flow.svg?fit=max&auto=format&n=RcOyXc06Ja8cuvMZ&q=85&s=b5be40abf333defe984993af89546c19" alt="Claude Code의 외부 연결을 보여주는 다이어그램: 설치/업데이트는 배포 서버에 연결되고, 사용자 요청은 Console auth, public-api, 그리고 선택적으로 Statsig, Sentry, 버그 보고를 포함한 Anthropic 서비스에 연결됩니다" width="720" height="520" data-path="images/claude-code-data-flow.svg" />

71 71

72Claude Code는 로컬에서 실행됩니다. LLM과 상호작용하기 위해 Claude Code는 네트워크를 통해 데이터를 전송합니다. 이 데이터에는 모든 사용자 프롬프트 및 모델 출력이 포함되며, TLS 1.2+ 이상을 통해 전송 중에 암호화됩니다. Claude Code는 대부분의 인기 있는 VPN 및 LLM 프록시와 호환됩니다.72Claude Code는 로컬에서 실행됩니다. LLM과 상호작용하기 위해 Claude Code는 네트워크를 통해 데이터를 전송합니다. 이 데이터에는 모든 사용자 프롬프트 및 모델 출력이 포함되며, TLS 1.2+ 이상을 통해 전송 중에 암호화됩니다. Claude Code는 대부분의 인기 있는 VPN 및 LLM 프록시와 호환됩니다.

73 73

desktop.md +7 −10

Details

282 282

283### 세션으로 병렬 작업하기283### 세션으로 병렬 작업하기

284 284

285사이드바에서 **+ New session**을 클릭하거나 macOS에서 **Cmd+N**을 누르거나 Windows에서 **Ctrl+N**을 눌러 여러 작업을 병렬로 작업합니다. **Ctrl+Tab** 및 **Ctrl+Shift+Tab**을 눌러 사이드바의 세션을 순환합니다. Git 저장소의 경우 각 세션은 [Git worktrees](/ko/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees)를 사용하여 프로젝트의 자신의 격리된 복사본을 가져오므로 한 세션의 변경 사항이 커밋할 때까지 다른 세션에 영향을 주지 않습니다.285사이드바에서 **+ New session**을 클릭하거나 macOS에서 **Cmd+N**을 누르거나 Windows에서 **Ctrl+N**을 눌러 여러 작업을 병렬로 작업합니다. **Ctrl+Tab** 및 **Ctrl+Shift+Tab**을 눌러 사이드바의 세션을 순환합니다. Git 저장소의 경우 각 세션은 [Git worktrees](/ko/worktrees)를 사용하여 프로젝트의 자신의 격리된 복사본을 가져오므로 한 세션의 변경 사항이 커밋할 때까지 다른 세션에 영향을 주지 않습니다.

286

287두 세션을 동시에 보려면 macOS에서 **Cmd**를 누르거나 Windows에서 **Ctrl**을 누르고 사이드바의 세션을 클릭합니다. 세션이 이미 열려 있는 창 옆에 두 번째 창에서 열립니다. 분할이 활성화되어 있는 동안 다른 사이드바 세션을 클릭하면 포커스가 있는 창을 바꿉니다. macOS에서 \*\*Cmd+\\\*\*를 누르거나 Windows에서 \*\*Ctrl+\\\*\*를 눌러 포커스된 창을 닫고 단일 세션으로 돌아갑니다.

286 288

287Worktrees는 기본적으로 `<project-root>/.claude/worktrees/`에 저장됩니다. Settings → Claude Code의 "Worktree location"에서 사용자 정의 디렉토리로 변경할 수 있습니다. 또한 모든 worktree 브랜치 이름 앞에 추가되는 브랜치 접두사를 설정할 수 있으며, 이는 Claude가 만든 브랜치를 정리하는 데 유용합니다. 완료되면 사이드바의 세션 위에 마우스를 올리고 아카이브 아이콘을 클릭하여 worktree를 제거합니다. PR이 병합되거나 닫힌 후 세션이 자동으로 아카이브되도록 하려면 Settings → Claude Code에서 **Auto-archive after PR merge or close**를 켭니다. 자동 아카이브는 실행을 완료한 로컬 세션에만 적용됩니다.289Worktrees는 기본적으로 `<project-root>/.claude/worktrees/`에 저장됩니다. Settings → Claude Code의 "Worktree location"에서 사용자 정의 디렉토리로 변경할 수 있습니다. 또한 모든 worktree 브랜치 이름 앞에 추가되는 브랜치 접두사를 설정할 수 있으며, 이는 Claude가 만든 브랜치를 정리하는 데 유용합니다. 완료되면 사이드바의 세션 위에 마우스를 올리고 아카이브 아이콘을 클릭하여 worktree를 제거합니다. PR이 병합되거나 닫힌 후 세션이 자동으로 아카이브되도록 하려면 Settings → Claude Code에서 **Auto-archive after PR merge or close**를 켭니다. 자동 아카이브는 실행을 완료한 로컬 세션에만 적용됩니다.

288 290

289gitignored 파일 (예: `.env`)을 새 worktrees에 포함하려면 프로젝트 루트에 [`.worktreeinclude` 파일](/ko/common-workflows#copy-gitignored-files-to-worktrees)을 만듭니다.291gitignored 파일 (예: `.env`)을 새 worktrees에 포함하려면 프로젝트 루트에 [`.worktreeinclude` 파일](/ko/worktrees#copy-gitignored-files-into-worktrees)을 만듭니다.

290 292

291<Note>293<Note>

292 세션 격리에는 [Git](https://git-scm.com/downloads)이 필요합니다. 대부분의 Mac에는 기본적으로 Git이 포함되어 있습니다. Terminal에서 `git --version`을 실행하여 확인합니다. Windows에서는 Code 탭이 작동하려면 Git이 필요합니다: [Windows용 Git 다운로드](https://git-scm.com/downloads/win), 설치 및 앱 재시작. Git 오류가 발생하면 [Cowork 탭](https://claude.com/product/cowork)에서 Claude에게 설정을 문제 해결하도록 요청하세요.294 세션 격리에는 [Git](https://git-scm.com/downloads)이 필요합니다. 대부분의 Mac에는 기본적으로 Git이 포함되어 있습니다. Terminal에서 `git --version`을 실행하여 확인합니다. Windows에서는 Code 탭이 작동하려면 Git이 필요합니다: [Windows용 Git 다운로드](https://git-scm.com/downloads/win), 설치 및 앱 재시작. Git 오류가 발생하면 [Cowork 탭](https://claude.com/product/cowork)에서 Claude에게 설정을 문제 해결하도록 요청하세요.

335 337

336Dispatch는 터미널에서 멀리 떨어져 있을 때 Claude와 작업하는 여러 방법 중 하나입니다. [플랫폼 및 통합](/ko/platforms#work-when-you-are-away-from-your-terminal)을 참조하여 Remote Control, Channels, Slack, 예약된 작업과 비교하세요.338Dispatch는 터미널에서 멀리 떨어져 있을 때 Claude와 작업하는 여러 방법 중 하나입니다. [플랫폼 및 통합](/ko/platforms#work-when-you-are-away-from-your-terminal)을 참조하여 Remote Control, Channels, Slack, 예약된 작업과 비교하세요.

337 339

338***

~~339~~

340title: "Claude Code 확장하기"

341description: "외부 서비스를 연결하고, 재사용 가능한 워크플로우를 추가하고, Claude의 동작을 사용자 정의하고, 미리보기 서버를 구성합니다."

~~342~~

343## Claude Code 확장하기340## Claude Code 확장하기

344 341

345외부 서비스를 연결하고, 재사용 가능한 워크플로우를 추가하고, Claude의 동작을 사용자 정의하고, 미리보기 서버를 구성합니다. 한 곳에서 커넥터, skills, 플러그인을 관리하려면 사이드바에서 **Customize**를 클릭합니다.342외부 서비스를 연결하고, 재사용 가능한 워크플로우를 추가하고, Claude의 동작을 사용자 정의하고, 미리보기 서버를 구성합니다. 한 곳에서 커넥터, skills, 플러그인을 관리하려면 사이드바에서 **Customize**를 클릭합니다.

514 510

515* **Local**: 머신에서 실행되며 파일에 직접 액세스합니다511* **Local**: 머신에서 실행되며 파일에 직접 액세스합니다

516* **Remote**: Anthropic의 클라우드 인프라에서 실행됩니다. 앱을 닫아도 세션이 계속됩니다.512* **Remote**: Anthropic의 클라우드 인프라에서 실행됩니다. 앱을 닫아도 세션이 계속됩니다.

517* **SSH**: SSH를 통해 연결하는 원격 머신 (예: 자신의 서버, 클라우드 VM 또는 개발 컨테이너)에서 실행됩니다513* **SSH**: SSH를 통해 연결하는 원격 머신(예: 자신의 서버, 클라우드 VM 또는 개발 컨테이너)에서 실행됩니다

518 514

519### 로컬 세션515### 로컬 세션

520 516

521데스크톱 앱이 항상 전체 셸 환경을 상속하지는 않습니다. macOS에서 Dock 또는 Finder에서 앱을 실행하면 `~/.zshrc` 또는 `~/.bashrc`와 같은 셸 프로필을 읽어 `PATH` 및 고정된 Claude Code 변수 집합을 추출하지만 거기에 내보낸 다른 변수는 선택되지 않습니다. Windows에서 앱은 사용자 및 시스템 환경 변수를 상속하지만 PowerShell 프로필을 읽지 않습니다.517데스크톱 앱이 항상 전체 셸 환경을 상속하지는 않습니다. macOS에서 Dock 또는 Finder에서 앱을 실행하면 `~/.zshrc` 또는 `~/.bashrc`와 같은 셸 프로필을 읽어 `PATH` 및 고정된 Claude Code 변수 집합을 추출하지만, 거기에 내보낸 다른 변수는 선택되지 않습니다. Windows에서 앱은 사용자 및 시스템 환경 변수를 상속하지만 PowerShell 프로필을 읽지 않습니다.

522 518

523로컬 세션 및 개발 서버에 대한 환경 변수를 설정하려면 프롬프트 상자의 환경 드롭다운을 열고 **Local** 위에 마우스를 올린 다음 기어 아이콘을 클릭하여 로컬 환경 편집기를 엽니다. 여기에 저장한 변수는 머신에 암호화되어 저장되며 시작하는 모든 로컬 세션 및 미리보기 서버에 적용됩니다. `~/.claude/settings.json` 파일의 `env` 키에 변수를 추가할 수도 있습니다. 단, 이는 Claude 세션에만 도달하고 개발 서버에는 도달하지 않습니다. 지원되는 변수의 전체 목록은 [환경 변수](/ko/env-vars)를 참조하세요.519로컬 세션 및 개발 서버에 대한 환경 변수를 설정하려면 프롬프트 상자의 환경 드롭다운을 열고 **Local** 위에 마우스를 올린 다음 기어 아이콘을 클릭하여 로컬 환경 편집기를 엽니다. 여기에 저장한 변수는 머신에 암호화되어 저장되며 시작하는 모든 로컬 세션 및 미리보기 서버에 적용됩니다. `~/.claude/settings.json` 파일의 `env` 키에 변수를 추가할 수도 있습니다. 단, 이는 Claude 세션에만 도달하고 개발 서버에는 도달하지 않습니다. 지원되는 변수의 전체 목록은 [환경 변수](/ko/env-vars)를 참조하세요.

524 520

525[Extended thinking](/ko/common-workflows#use-extended-thinking-thinking-mode)은 기본적으로 활성화되어 있으며, 복잡한 추론 작업의 성능을 향상시키지만 추가 토큰을 사용합니다. 생각을 완전히 비활성화하려면 로컬 환경 편집기에서 `MAX_THINKING_TOKENS`을 `0`으로 설정합니다. [적응형 추론](/ko/model-config#adjust-effort-level)이 있는 모델에서는 적응형 추론이 생각 깊이를 제어하기 때문에 다른 `MAX_THINKING_TOKENS` 값은 무시됩니다. Opus 4.6 및 Sonnet 4.6에서는 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`을 `1`로 설정하여 고정 생각 예산을 사용합니다. Opus 4.7은 항상 적응형 추론을 사용하며 고정 예산 모드가 없습니다.521[Extended thinking](/ko/model-config#extended-thinking)은 기본적으로 활성화되어 있으며, 복잡한 추론 작업의 성능을 향상시키지만 추가 토큰을 사용합니다. 생각을 완전히 비활성화하려면 로컬 환경 편집기에서 `MAX_THINKING_TOKENS`을 `0`으로 설정합니다. [적응형 추론](/ko/model-config#adjust-effort-level)이 있는 모델에서는 적응형 추론이 생각 깊이를 제어하기 때문에 다른 `MAX_THINKING_TOKENS` 값은 무시됩니다. Opus 4.6 및 Sonnet 4.6에서는 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`을 `1`로 설정하여 고정 생각 예산을 사용합니다. Opus 4.7은 항상 적응형 추론을 사용하며 고정 예산 모드가 없습니다.

526 522

527### 원격 세션523### 원격 세션

528 524

features-overview.md +49 −12

Details

23* \*\*[MCP](/ko/mcp)\*\*는 Claude를 외부 서비스 및 도구에 연결합니다.23* \*\*[MCP](/ko/mcp)\*\*는 Claude를 외부 서비스 및 도구에 연결합니다.

24* \*\*[Subagents](/ko/sub-agents)\*\*는 격리된 컨텍스트에서 자신의 루프를 실행하고 요약을 반환합니다.24* \*\*[Subagents](/ko/sub-agents)\*\*는 격리된 컨텍스트에서 자신의 루프를 실행하고 요약을 반환합니다.

25* \*\*[Agent teams](/ko/agent-teams)\*\*는 공유 작업 및 피어 투 피어 메시징으로 여러 독립적인 세션을 조정합니다.25* \*\*[Agent teams](/ko/agent-teams)\*\*는 공유 작업 및 피어 투 피어 메시징으로 여러 독립적인 세션을 조정합니다.

~~26* \*\*[Hooks](/ko/hooks)\*\*는 결정론적 스크립트로 루프 외부에서 완전히 실행됩니다.~~26* \*\*[Hooks](/ko/hooks-guide)\*\*는 라이프사이클 이벤트에서 실행되며 스크립트, HTTP 요청, 프롬프트 또는 subagent를 실행할 수 있습니다.

27* **[Plugins](/ko/plugins)** 및 \*\*[marketplaces](/ko/plugin-marketplaces)\*\*는 이러한 기능을 패키징하고 배포합니다.27* **[Plugins](/ko/plugins)** 및 \*\*[marketplaces](/ko/plugin-marketplaces)\*\*는 이러한 기능을 패키징하고 배포합니다.

28 28

29[Skills](/ko/skills)는 가장 유연한 확장입니다. Skill은 지식, 워크플로우 또는 지침을 포함하는 마크다운 파일입니다. `/deploy`와 같은 명령으로 skill을 호출하거나, Claude가 관련이 있을 때 자동으로 로드할 수 있습니다. Skill은 현재 대화에서 실행되거나 subagents를 통해 격리된 컨텍스트에서 실행될 수 있습니다.29[Skills](/ko/skills)는 가장 유연한 확장입니다. Skill은 지식, 워크플로우 또는 지침을 포함하는 마크다운 파일입니다. `/deploy`와 같은 명령으로 skill을 호출하거나, Claude가 관련이 있을 때 자동으로 로드할 수 있습니다. Skill은 현재 대화에서 실행되거나 subagents를 통해 격리된 컨텍스트에서 실행될 수 있습니다.

33기능은 Claude가 모든 세션에서 보는 항상 켜진 컨텍스트부터 사용자나 Claude가 호출할 수 있는 온디맨드 기능, 특정 이벤트에서 실행되는 백그라운드 자동화까지 다양합니다. 아래 표는 사용 가능한 기능과 각 기능이 언제 적절한지 보여줍니다.33기능은 Claude가 모든 세션에서 보는 항상 켜진 컨텍스트부터 사용자나 Claude가 호출할 수 있는 온디맨드 기능, 특정 이벤트에서 실행되는 백그라운드 자동화까지 다양합니다. 아래 표는 사용 가능한 기능과 각 기능이 언제 적절한지 보여줍니다.

34 34

35| 기능 | 수행 작업 | 사용 시기 | 예시 |35| 기능 | 수행 작업 | 사용 시기 | 예시 |

~~36| ---------------------------------- | ------------------------------- | ------------------------------ | ----------------------------------------------------- |~~36| ---------------------------------- | ------------------------------------------ | ------------------------------ | ----------------------------------------------------- |

41| **MCP** | 외부 서비스에 연결 | 외부 데이터 또는 작업 | 데이터베이스 쿼리, Slack에 게시, 브라우저 제어 |41| **MCP** | 외부 서비스에 연결 | 외부 데이터 또는 작업 | 데이터베이스 쿼리, Slack에 게시, 브라우저 제어 |

43 43

44\*\*[Plugins](/ko/plugins)\*\*는 패키징 계층입니다. 플러그인은 skill, hook, subagent 및 MCP 서버를 단일 설치 가능한 단위로 번들합니다. 플러그인 skill은 네임스페이스됩니다(예: `/my-plugin:review`). 따라서 여러 플러그인이 공존할 수 있습니다. 여러 저장소에서 동일한 설정을 재사용하거나 \*\*[marketplace](/ko/plugin-marketplaces)\*\*를 통해 다른 사용자에게 배포하려는 경우 플러그인을 사용하세요.44\*\*[Plugins](/ko/plugins)\*\*는 패키징 계층입니다. 플러그인은 skill, hook, subagent 및 MCP 서버를 단일 설치 가능한 단위로 번들합니다. 플러그인 skill은 네임스페이스됩니다(예: `/my-plugin:review`). 따라서 여러 플러그인이 공존할 수 있습니다. 여러 저장소에서 동일한 설정을 재사용하거나 \*\*[marketplace](/ko/plugin-marketplaces)\*\*를 통해 다른 사용자에게 배포하려는 경우 플러그인을 사용하세요.

45 45

46### 시간이 지남에 따라 설정 구축하기

48모든 것을 미리 구성할 필요는 없습니다. 각 기능에는 인식 가능한 트리거가 있으며, 대부분의 팀은 대략 이 순서로 추가합니다.

50| 트리거 | 추가 |

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

52| Claude가 규칙이나 명령을 두 번 잘못 수행 | [CLAUDE.md](/ko/memory)에 추가 |

53| 작업을 시작하기 위해 동일한 프롬프트를 계속 입력 | 사용자 호출 가능 [skill](/ko/skills)로 저장 |

54| 동일한 플레이북이나 다단계 절차를 세 번째로 채팅에 붙여넣기 | [skill](/ko/skills)로 캡처 |

55| Claude가 볼 수 없는 브라우저 탭에서 계속 데이터 복사 | 해당 시스템을 [MCP 서버](/ko/mcp)로 연결 |

56| 부작용 작업이 다시 참조하지 않을 출력으로 대화 범람 | [subagent](/ko/sub-agents)를 통해 라우팅 |

57| 요청하지 않고 매번 무언가가 발생하기를 원함 | [hook](/ko/hooks-guide) 작성 |

58| 두 번째 저장소가 동일한 설정 필요 | [plugin](/ko/plugins)으로 패키징 |

60동일한 트리거는 이미 가진 것을 업데이트할 시기를 알려줍니다. 반복된 실수나 반복되는 검토 의견은 채팅의 일회성 수정이 아니라 CLAUDE.md 편집입니다. 계속 손으로 조정하는 워크플로우는 다른 수정이 필요한 skill입니다.

46### 유사한 기능 비교62### 유사한 기능 비교

47 63

48일부 기능은 유사해 보일 수 있습니다. 구별하는 방법은 다음과 같습니다.64일부 기능은 유사해 보일 수 있습니다. 구별하는 방법은 다음과 같습니다.

55 * **Subagents**는 주 대화와 별도로 실행되는 격리된 워커입니다.71 * **Subagents**는 주 대화와 별도로 실행되는 격리된 워커입니다.

56 72

57 | 측면 | Skill | Subagent |73 | 측면 | Skill | Subagent |

~~58 | --------- | ----------------------- | -------------------------------- |~~74 | ------------------------------------- | ----------------------- | -------------------------------- |

59 | **정의** | 재사용 가능한 지침, 지식 또는 워크플로우 | 자신의 컨텍스트를 가진 격리된 워커 |75 | **정의** | 재사용 가능한 지침, 지식 또는 워크플로우 | 자신의 컨텍스트를 가진 격리된 워커 |

77 | **[컨텍스트 윈도우](/ko/context-window) 영향** | 주 윈도우에 추가 | 자신의 입력 및 출력 토큰이 있는 별도의 윈도우 사용 |

62 79

63 **Skill은 참조 또는 작업일 수 있습니다.** 참조 skill은 Claude가 세션 전체에서 사용하는 지식을 제공합니다(API 스타일 가이드처럼). 작업 skill은 Claude에게 특정 작업을 수행하도록 지시합니다(배포 워크플로우를 실행하는 `/deploy`처럼).80 **Skill은 참조 또는 작업일 수 있습니다.** 참조 skill은 Claude가 세션 전체에서 사용하는 지식을 제공합니다(API 스타일 가이드처럼). 작업 skill은 Claude에게 특정 작업을 수행하도록 지시합니다(배포 워크플로우를 실행하는 `/deploy`처럼).

142 159

143 예: MCP 서버는 Claude를 데이터베이스에 연결합니다. Skill은 Claude에게 데이터 모델, 일반적인 쿼리 패턴, 다양한 작업에 사용할 테이블을 가르칩니다.160 예: MCP 서버는 Claude를 데이터베이스에 연결합니다. Skill은 Claude에게 데이터 모델, 일반적인 쿼리 패턴, 다양한 작업에 사용할 테이블을 가르칩니다.

144 </Tab>161 </Tab>

162

163 <Tab title="Hook vs Skill">

164 Hook은 라이프사이클 이벤트에서 실행됩니다. Skill은 Claude의 컨텍스트에 로드됩니다.

165

166 | 측면 | Hook | Skill |

167 | ----------- | ---------------------------------------------------------------------- | -------------------------------------------- |

168 | **실행** | 셸 명령, HTTP 요청, LLM 프롬프트 또는 subagent | Claude가 읽고 따르는 지침 |

169 | **트리거** | [라이프사이클 이벤트](/ko/hooks#hook-events) 예: `PostToolUse` 또는 `SessionStart` | `/<name>`을 입력하거나, Claude가 설명을 작업과 일치시킬 때 |

170 | **결정론성** | 이벤트에서 항상 실행; 트리거가 보장됨 | Claude가 지침을 해석; 결과는 다양할 수 있음 |

171 | **컨텍스트 비용** | 0, hook이 출력을 반환하지 않는 한 | 설명은 모든 세션에 로드; 전체 콘텐츠는 사용 시 로드 |

172 | **최적 용도** | 매번 동일한 방식으로 실행되고 Claude가 생각할 필요가 없는 작업 | Claude가 단계를 적용하는 방법을 결정해야 하거나 콘텐츠가 지식인 워크플로우 |

173

174 **작업이 매번 동일한 방식으로 실행되고 Claude가 생각할 필요가 없을 때 hook을 사용하세요.** 예: 저장 시 형식 지정, `rm -rf /` 거부, 세션 종료 시 Slack 메시지 게시.

175

176 **Claude가 단계를 적용하는 방법을 결정해야 하거나 콘텐츠가 지식일 때 skill을 사용하세요.** 예: `/release` 체크리스트, API 스타일 가이드, 디버깅 플레이북.

177

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

179

180 **Hook 출력이 컨텍스트에 들어갑니다.** `PostToolUse` hook이 린터를 실행하면 결과가 Claude가 읽는 텍스트로 피드백됩니다. `/fix-lint` skill은 Claude에게 해결 방법을 알려줍니다.

181 </Tab>

145</Tabs>182</Tabs>

146 183

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

168 205

169## 컨텍스트 비용 이해하기206## 컨텍스트 비용 이해하기

170 207

171추가하는 모든 기능은 Claude의 컨텍스트를 소비합니다. 너무 많으면 컨텍스트 윈도우를 채울 수 있지만, 노이즈를 추가하여 Claude를 덜 효과적으로 만들 수도 있습니다. Skill이 올바르게 트리거되지 않거나 Claude가 규칙을 잃을 수 있습니다. 이러한 트레이드오프를 이해하면 효과적인 설정을 구축하는 데 도움이 됩니다.208추가하는 모든 기능은 Claude의 컨텍스트를 소비합니다. 너무 많으면 컨텍스트 윈도우를 채울 수 있지만, 노이즈를 추가하여 Claude를 덜 효과적으로 만들 수도 있습니다. Skill이 올바르게 트리거되지 않거나 Claude가 규칙을 잃을 수 있습니다. 이러한 트레이드오프를 이해하면 효과적인 설정을 구축하는 데 도움이 됩니다. 실행 중인 세션에서 이러한 기능이 어떻게 결합되는지 대화형으로 보려면 [컨텍스트 윈도우 탐색](/ko/context-window)을 참조하세요.

172 209

173### 기능별 컨텍스트 비용210### 기능별 컨텍스트 비용

174 211

177| 기능 | 로드 시기 | 로드되는 내용 | 컨텍스트 비용 |214| 기능 | 로드 시기 | 로드되는 내용 | 컨텍스트 비용 |

178| ------------- | ------------ | ---------------------- | --------------------------- |215| ------------- | ------------ | ---------------------- | --------------------------- |

182| **Subagent** | 생성 시 | 지정된 skill이 있는 신선한 컨텍스트 | 주 세션에서 격리됨 |219| **Subagents** | 생성 시 | 지정된 skill이 있는 신선한 컨텍스트 | 주 세션에서 격리됨 |

184 221

185\*기본적으로 skill 설명은 세션 시작 시 로드되므로 Claude가 사용할 시기를 결정할 수 있습니다. Skill의 frontmatter에서 `disable-model-invocation: true`를 설정하여 수동으로 호출할 때까지 Claude에서 완전히 숨깁니다. 이는 skill의 컨텍스트 비용을 0으로 줄입니다.222\*기본적으로 skill 설명은 세션 시작 시 로드되므로 Claude가 사용할 시기를 결정할 수 있습니다. Skill의 frontmatter에서 `disable-model-invocation: true`를 설정하여 수동으로 호출할 때까지 Claude에서 완전히 숨깁니다. 이는 skill의 컨텍스트 비용을 0으로 줄입니다.

188 225

189각 기능은 세션의 다양한 지점에서 로드됩니다. 아래 탭은 각 기능이 언제 로드되고 무엇이 컨텍스트에 들어가는지 설명합니다.226각 기능은 세션의 다양한 지점에서 로드됩니다. 아래 탭은 각 기능이 언제 로드되고 무엇이 컨텍스트에 들어가는지 설명합니다.

190 227

191<img src="https://mintcdn.com/claude-code/6yTCYq1p37ZB8-CQ/images/context-loading.svg?fit=max&auto=format&n=6yTCYq1p37ZB8-CQ&q=85&s=5a58ce953a35a2412892015e2ad6cb67" alt="컨텍스트 로딩: CLAUDE.md와 MCP는 세션 시작 시 로드되고 모든 요청에 유지됩니다. Skill은 시작 시 설명을 로드하고 호출 시 전체 콘텐츠를 로드합니다. Subagent는 격리된 컨텍스트를 받습니다. Hook은 외부에서 실행됩니다." width="720" height="410" data-path="images/context-loading.svg" />228<img src="https://mintcdn.com/claude-code/6yTCYq1p37ZB8-CQ/images/context-loading.svg?fit=max&auto=format&n=6yTCYq1p37ZB8-CQ&q=85&s=5a58ce953a35a2412892015e2ad6cb67" alt="컨텍스트 로딩: CLAUDE.md는 세션 시작 시 로드되고 모든 요청에 유지됩니다. MCP 도구 이름은 시작 시 로드되고 전체 스키마는 사용 시까지 연기됩니다. Skill은 시작 시 설명을 로드하고 호출 시 전체 콘텐츠를 로드합니다. Subagent는 격리된 컨텍스트를 받습니다. Hook은 외부에서 실행됩니다." width="720" height="410" data-path="images/context-loading.svg" />

192 229

193<Tabs>230<Tabs>

194 <Tab title="CLAUDE.md">231 <Tab title="CLAUDE.md">

202 </Tab>239 </Tab>

203 240

204 <Tab title="Skills">241 <Tab title="Skills">

205 Skill은 Claude의 도구 키트에 있는 추가 기능입니다. 참조 자료(API 스타일 가이드처럼) 또는 `/<name>`으로 트리거하는 호출 가능한 워크플로우(배포처럼)일 수 있습니다. Claude Code는 기본적으로 작동하는 `/simplify`, `/batch`, `/debug`와 같은 [번들 skill](/ko/skills#bundled-skills)과 함께 제공됩니다. 자신의 것을 만들 수도 있습니다. Claude는 적절할 때 skill을 사용하거나 직접 호출할 수 있습니다.242 Skill은 Claude의 도구 키트에 있는 추가 기능입니다. 참조 자료(API 스타일 가이드처럼) 또는 `/<name>`으로 트리거하는 호출 가능한 워크플로우(배포처럼)일 수 있습니다. Claude Code는 기본적으로 작동하는 `/simplify`, `/batch`, `/debug`와 같은 [번들 skill](/ko/commands)과 함께 제공됩니다. 자신의 것을 만들 수도 있습니다. Claude는 적절할 때 skill을 사용하거나 직접 호출할 수 있습니다.

206 243

207 **시기:** Skill의 구성에 따라 다릅니다. 기본적으로 설명은 세션 시작 시 로드되고 전체 콘텐츠는 사용 시 로드됩니다. 사용자 전용 skill(`disable-model-invocation: true`)의 경우, 호출할 때까지 아무것도 로드되지 않습니다.244 **시기:** Skill의 구성에 따라 다릅니다. 기본적으로 설명은 세션 시작 시 로드되고 전체 콘텐츠는 사용 시 로드됩니다. 사용자 전용 skill(`disable-model-invocation: true`)의 경우, 호출할 때까지 아무것도 로드되지 않습니다.

208 245

220 <Tab title="MCP servers">257 <Tab title="MCP servers">

221 **시기:** 세션 시작.258 **시기:** 세션 시작.

222 259

223 **로드되는 내용:** 연결된 서버의 모든 도구 정의 및 JSON 스키마.260 **로드되는 내용:** 연결된 서버의 도구 이름. 전체 JSON 스키마는 Claude가 특정 도구가 필요할 때까지 연기됩니다.

224 261

225 **컨텍스트 비용:** [도구 검색](/ko/mcp#scale-with-mcp-tool-search)(기본적으로 활성화)은 MCP 도구를 컨텍스트의 최대 10%까지 로드하고 나머지는 필요할 때까지 연기합니다.262 **컨텍스트 비용:** [도구 검색](/ko/mcp#scale-with-mcp-tool-search)은 기본적으로 활성화되므로, 유휴 MCP 도구는 최소한의 컨텍스트를 소비합니다.

226 263

227 **신뢰성 참고:** MCP 연결은 세션 중간에 조용히 실패할 수 있습니다. 서버가 연결 해제되면 도구가 경고 없이 사라집니다. Claude가 이전에 접근할 수 있었던 MCP 도구를 사용하지 못하는 경우, `/mcp`로 연결을 확인하세요.264 **신뢰성 참고:** MCP 연결은 세션 중간에 조용히 실패할 수 있습니다. 서버가 연결 해제되면 도구가 경고 없이 사라집니다. Claude가 이전에 접근할 수 있었던 MCP 도구를 사용하지 못하는 경우, `/mcp`로 연결을 확인하세요.

228 265

hooks.md +4 −4

Details

978 978

979```json theme={null}979```json theme={null}

980{980{

2405```2405```

2406 2406

2407| 필드 | 설명 |2407| 필드 | 설명 |

2408| :------- | :-------------------------------- |2408| :------- | :-------------------------------------------------- |

2409| `ok` | `true`는 작업을 허용하고 `false`는 방지합니다 |2409| `ok` | `true`는 작업을 허용하고 `false`는 방지합니다. 아래의 이벤트별 동작을 참조하세요 |

2411 2411

2412`ok: false`에서 발생하는 상황은 이벤트에 따라 다릅니다:2412`ok: false`에서 발생하는 상황은 이벤트에 따라 다릅니다:

2413 2413

permissions.md +6 −6

Details

36| :------------------ | :------------------------------------------------------------------------------------------------------------ |36| :------------------ | :------------------------------------------------------------------------------------------------------------ |

37| `default` | 표준 동작: 각 도구를 처음 사용할 때 권한을 요청합니다 |37| `default` | 표준 동작: 각 도구를 처음 사용할 때 권한을 요청합니다 |

38| `acceptEdits` | 작업 디렉토리 또는 `additionalDirectories`의 경로에 대해 파일 편집 및 일반적인 파일 시스템 명령(`mkdir`, `touch`, `mv`, `cp` 등)을 자동으로 수락합니다 |38| `acceptEdits` | 작업 디렉토리 또는 `additionalDirectories`의 경로에 대해 파일 편집 및 일반적인 파일 시스템 명령(`mkdir`, `touch`, `mv`, `cp` 등)을 자동으로 수락합니다 |

41| `dontAsk` | `/permissions` 또는 `permissions.allow` 규칙을 통해 사전 승인되지 않은 한 도구를 자동으로 거부합니다 |41| `dontAsk` | `/permissions` 또는 `permissions.allow` 규칙을 통해 사전 승인되지 않은 한 도구를 자동으로 거부합니다 |

296 296

297* 권한 deny 규칙은 Claude가 제한된 리소스에 액세스하려고 시도하는 것을 차단합니다297* 권한 deny 규칙은 Claude가 제한된 리소스에 액세스하려고 시도하는 것을 차단합니다

298* 샌드박스 제한은 프롬프트 주입이 Claude의 의사 결정을 우회하더라도 Bash 명령이 정의된 경계 외부의 리소스에 도달하는 것을 방지합니다298* 샌드박스 제한은 프롬프트 주입이 Claude의 의사 결정을 우회하더라도 Bash 명령이 정의된 경계 외부의 리소스에 도달하는 것을 방지합니다

299* 샌드박스의 파일 시스템 제한은 Read 및 Edit deny 규칙을 사용하며, 별도의 샌드박스 구성은 사용하지 않습니다299* 샌드박스의 파일 시스템 제한은 [`sandbox.filesystem`](/ko/sandboxing) 설정을 Read 및 Edit deny 규칙과 결합합니다. 둘 다 최종 샌드박스 경계로 병합됩니다

300* 네트워크 제한은 WebFetch 권한 규칙과 샌드박스의 `allowedDomains` 및 `deniedDomains` 목록을 결합합니다300* 네트워크 제한은 WebFetch 권한 규칙을 샌드박스의 `allowedDomains` 및 `deniedDomains` 목록과 결합합니다

301 301

302샌드박싱이 `autoAllowBashIfSandboxed: true`로 활성화되면(기본값), 권한에 `ask: Bash(*)`가 포함되어 있어도 샌드박스된 Bash 명령은 프롬프트 없이 실행됩니다. 샌드박스 경계는 명령별 프롬프트를 대체합니다. 명시적 deny 규칙은 여전히 적용되며, `/`, 홈 디렉터리 또는 기타 중요한 시스템 경로를 대상으로 하는 `rm` 또는 `rmdir` 명령은 여전히 프롬프트를 트리거합니다. [샌드박스 모드](/ko/sandboxing#sandbox-modes)를 참조하여 이 동작을 변경합니다.302샌드박싱이 `autoAllowBashIfSandboxed: true`로 활성화되면(기본값), 권한에 `ask: Bash(*)`가 포함되어 있어도 샌드박스된 Bash 명령은 프롬프트 없이 실행됩니다. 샌드박스 경계는 명령별 프롬프트를 대체합니다. 명시적 deny 규칙은 여전히 적용되며, `/`, 홈 디렉터리 또는 기타 중요한 시스템 경로를 대상으로 하는 `rm` 또는 `rmdir` 명령은 여전히 프롬프트를 트리거합니다. [샌드박스 모드](/ko/sandboxing#sandbox-modes)를 참조하여 이 동작을 변경합니다.

303 303

316| `allowManagedMcpServersOnly` | `true`일 때, 관리형 설정의 `allowedMcpServers`만 존중됩니다. `deniedMcpServers`는 여전히 모든 소스에서 병합됩니다. [관리형 MCP 구성](/ko/mcp#managed-mcp-configuration) 참조 |316| `allowManagedMcpServersOnly` | `true`일 때, 관리형 설정의 `allowedMcpServers`만 존중됩니다. `deniedMcpServers`는 여전히 모든 소스에서 병합됩니다. [관리형 MCP 구성](/ko/mcp#managed-mcp-configuration) 참조 |

317| `allowManagedPermissionRulesOnly` | `true`일 때, 사용자 및 프로젝트 설정이 `allow`, `ask` 또는 `deny` 권한 규칙을 정의하는 것을 방지합니다. 관리형 설정의 규칙만 적용됩니다 |317| `allowManagedPermissionRulesOnly` | `true`일 때, 사용자 및 프로젝트 설정이 `allow`, `ask` 또는 `deny` 권한 규칙을 정의하는 것을 방지합니다. 관리형 설정의 규칙만 적용됩니다 |

318| `blockedMarketplaces` | 마켓플레이스 소스의 차단 목록입니다. 차단된 소스는 다운로드 전에 확인되므로 파일 시스템에 닿지 않습니다. [관리형 마켓플레이스 제한](/ko/plugin-marketplaces#managed-marketplace-restrictions) 참조 |318| `blockedMarketplaces` | 마켓플레이스 소스의 차단 목록입니다. 차단된 소스는 다운로드 전에 확인되므로 파일 시스템에 닿지 않습니다. [관리형 마켓플레이스 제한](/ko/plugin-marketplaces#managed-marketplace-restrictions) 참조 |

319| `channelsEnabled` | Team 및 Enterprise 사용자를 위한 [채널](/ko/channels)을 허용합니다. 설정되지 않거나 `false`이면 사용자가 `--channels`에 전달하는 것과 관계없이 채널 메시지 전달을 차단합니다 |319| `channelsEnabled` | 조직을 위한 [채널](/ko/channels)을 허용합니다. 각 플랜의 기본값은 [엔터프라이즈 제어](/ko/channels#enterprise-controls)를 참조합니다 |

320| `forceRemoteSettingsRefresh` | `true`일 때, 원격 관리형 설정이 새로 가져올 때까지 CLI 시작을 차단하고 가져오기에 실패하면 종료합니다. [실패 폐쇄 적용](/ko/server-managed-settings#enforce-fail-closed-startup) 참조 |320| `forceRemoteSettingsRefresh` | `true`일 때, 원격 관리형 설정이 새로 가져올 때까지 CLI 시작을 차단하고 가져오기에 실패하면 종료합니다. [실패 폐쇄 적용](/ko/server-managed-settings#enforce-fail-closed-startup) 참조 |

322| `sandbox.filesystem.allowManagedReadPathsOnly` | `true`일 때, 관리형 설정의 `filesystem.allowRead` 경로만 존중됩니다. `denyRead`는 여전히 모든 소스에서 병합됩니다 |322| `sandbox.filesystem.allowManagedReadPathsOnly` | `true`일 때, 관리형 설정의 `filesystem.allowRead` 경로만 존중됩니다. `denyRead`는 여전히 모든 소스에서 병합됩니다 |

323| `sandbox.network.allowManagedDomainsOnly` | `true`일 때, 관리형 설정의 `allowedDomains` 및 `WebFetch(domain:...)` allow 규칙만 존중됩니다. 허용되지 않은 도메인은 사용자에게 프롬프트하지 않고 자동으로 차단됩니다. 거부된 도메인은 여전히 모든 소스에서 병합됩니다 |323| `sandbox.network.allowManagedDomainsOnly` | `true`일 때, 관리형 설정의 `allowedDomains` 및 `WebFetch(domain:...)` allow 규칙만 존중됩니다. 허용되지 않은 도메인은 사용자에게 프롬프트하지 않고 자동으로 차단됩니다. 거부된 도메인은 여전히 모든 소스에서 병합됩니다 |

324| `strictKnownMarketplaces` | 사용자가 추가할 수 있는 플러그인 마켓플레이스를 제어합니다. [관리형 마켓플레이스 제한](/ko/plugin-marketplaces#managed-marketplace-restrictions) 참조 |324| `strictKnownMarketplaces` | 사용자가 추가하고 플러그인을 설치할 수 있는 플러그인 마켓플레이스 소스를 제어합니다. [관리형 마켓플레이스 제한](/ko/plugin-marketplaces#managed-marketplace-restrictions) 참조 |

325| `wslInheritsWindowsSettings` | Windows HKLM 레지스트리 키 또는 `C:\Program Files\ClaudeCode\managed-settings.json`에서 `true`일 때, WSL은 `/etc/claude-code`에 추가로 Windows 정책 체인에서 관리형 설정을 읽습니다. [설정 파일](/ko/settings#settings-files) 참조 |325| `wslInheritsWindowsSettings` | Windows HKLM 레지스트리 키 또는 `C:\Program Files\ClaudeCode\managed-settings.json`에서 `true`일 때, WSL은 `/etc/claude-code`에 추가로 Windows 정책 체인에서 관리형 설정을 읽습니다. [설정 파일](/ko/settings#settings-files) 참조 |

326 326

327`disableBypassPermissionsMode`는 일반적으로 조직 정책을 적용하기 위해 관리형 설정에 배치되지만 모든 범위에서 작동합니다. 사용자는 자신의 설정에서 이를 설정하여 자신을 우회 모드에서 잠글 수 있습니다.327`disableBypassPermissionsMode`는 일반적으로 조직 정책을 적용하기 위해 관리형 설정에 배치되지만 모든 범위에서 작동합니다. 사용자는 자신의 설정에서 이를 설정하여 자신을 우회 모드에서 잠글 수 있습니다.

328 328

329<Note>329<Note>

330 [Remote Control](/ko/remote-control) 및 [웹 세션](/ko/claude-code-on-the-web)에 대한 액세스는 관리형 설정 키로 제어되지 않습니다. Team 및 Enterprise 플랜에서 관리자는 [Claude Code 관리자 설정](https://claude.ai/admin-settings/claude-code)에서 이러한 기능을 활성화하거나 비활성화합니다.330 Team 및 Enterprise 플랜에서 관리자는 [Claude Code 관리자 설정](https://claude.ai/admin-settings/claude-code)에서 [Remote Control](/ko/remote-control) 및 [웹 세션](/ko/claude-code-on-the-web)을 조직 전체에서 활성화하거나 비활성화합니다. Remote Control은 [`disableRemoteControl`](/ko/settings#available-settings) 관리형 설정으로 장치별로 추가로 비활성화할 수 있습니다. 웹 세션에는 장치별 관리형 설정 키가 없습니다.

331</Note>331</Note>

332 332

333## 설정 우선순위333## 설정 우선순위

platforms.md +6 −3

Details

13프로젝트가 있는 위치와 작업 방식에 따라 플랫폼을 선택합니다.13프로젝트가 있는 위치와 작업 방식에 따라 플랫폼을 선택합니다.

14 14

15| 플랫폼 | 최적 용도 | 제공 기능 |15| 플랫폼 | 최적 용도 | 제공 기능 |

16| :-------------------------------- | :----------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |16| :-------------------------------- | :----------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |

22| Mobile | 컴퓨터에서 멀리 떨어져 있을 때 작업 시작 및 모니터링 | iOS 및 Android용 Claude 앱의 클라우드 세션, 로컬 세션용 [Remote Control](/ko/remote-control), Pro 및 Max의 Desktop으로 [Dispatch](/ko/desktop#sessions-from-dispatch) |

22 23

23CLI는 터미널 기반 작업을 위한 가장 완전한 플랫폼입니다. 스크립팅, 타사 제공자, Agent SDK는 CLI 전용입니다. Desktop과 IDE 확장 프로그램은 일부 CLI 전용 기능을 포기하는 대신 시각적 검토와 더 긴밀한 편집기 통합을 제공합니다. 웹은 Anthropic의 클라우드에서 실행되므로 연결을 해제한 후에도 작업이 계속됩니다.24CLI는 터미널 기반 작업을 위한 가장 완전한 플랫폼입니다. 스크립팅 및 Agent SDK는 CLI 전용입니다. 타사 제공자는 [VS Code](/ko/vs-code#use-third-party-providers)에서도 작동합니다. Enterprise [Desktop](/ko/desktop) 배포는 Vertex AI 및 게이트웨이 제공자를 지원합니다. Bedrock 또는 Foundry의 경우 Desktop 대신 CLI 또는 VS Code를 사용합니다. Desktop과 IDE 확장 프로그램은 일부 CLI 전용 기능을 포기하는 대신 시각적 검토와 더 긴밀한 편집기 통합을 제공합니다. 웹은 Anthropic의 클라우드에서 실행되므로 연결을 해제한 후에도 작업이 계속됩니다. Mobile은 동일한 클라우드 세션으로의 씬 클라이언트이거나 Remote Control을 통한 로컬 세션으로의 씬 클라이언트이며, Dispatch를 통해 Desktop으로 작업을 보낼 수 있습니다.

24 25

25동일한 프로젝트에서 여러 플랫폼을 혼합하여 사용할 수 있습니다. 구성, 프로젝트 메모리 및 MCP 서버는 로컬 플랫폼 간에 공유됩니다.26동일한 프로젝트에서 여러 플랫폼을 혼합하여 사용할 수 있습니다. 구성, 프로젝트 메모리 및 MCP 서버는 로컬 플랫폼 간에 공유됩니다.

26 27

61* [VS Code](/ko/vs-code): 편집기 내 Claude Code 확장 프로그램62* [VS Code](/ko/vs-code): 편집기 내 Claude Code 확장 프로그램

62* [JetBrains](/ko/jetbrains): IntelliJ, PyCharm 및 기타 JetBrains IDE용 확장 프로그램63* [JetBrains](/ko/jetbrains): IntelliJ, PyCharm 및 기타 JetBrains IDE용 확장 프로그램

63* [웹의 Claude Code](/ko/claude-code-on-the-web): 연결 해제 후에도 계속 실행되는 클라우드 세션64* [웹의 Claude Code](/ko/claude-code-on-the-web): 연결 해제 후에도 계속 실행되는 클라우드 세션

65* Mobile: [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) 및 [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude)용 Claude 앱으로 컴퓨터에서 멀리 떨어져 있을 때 작업 시작 및 모니터링

64 66

65### 통합67### 통합

66 68

67* [Chrome](/ko/chrome): 로그인된 세션으로 브라우저 작업 자동화69* [Chrome](/ko/chrome): 로그인된 세션으로 브라우저 작업 자동화

70* [컴퓨터 사용](/ko/computer-use): Claude가 macOS에서 앱을 열고 화면을 제어하도록 허용

68* [GitHub Actions](/ko/github-actions): CI 파이프라인에서 Claude 실행71* [GitHub Actions](/ko/github-actions): CI 파이프라인에서 Claude 실행

69* [GitLab CI/CD](/ko/gitlab-ci-cd): GitLab용 동일한 기능72* [GitLab CI/CD](/ko/gitlab-ci-cd): GitLab용 동일한 기능

70* [Code Review](/ko/code-review): 모든 풀 요청에 대한 자동 검토73* [Code Review](/ko/code-review): 모든 풀 요청에 대한 자동 검토

plugin-marketplaces.md +8 −6

Details

23 23

24## 연습: 로컬 마켓플레이스 생성24## 연습: 로컬 마켓플레이스 생성

25 25

26이 예제에서는 하나의 플러그인으로 마켓플레이스를 생성합니다: 코드 리뷰를 위한 `/quality-review` skill입니다. 디렉터리 구조를 생성하고, skill을 추가하고, 플러그인 매니페스트와 마켓플레이스 카탈로그를 생성한 다음, 설치하고 테스트합니다.26이 예제에서는 하나의 플러그인으로 마켓플레이스를 생성합니다: 코드 리뷰를 위한 `quality-review` skill입니다. 디렉터리 구조를 생성하고, skill을 추가하고, 플러그인 매니페스트와 마켓플레이스 카탈로그를 생성한 다음, 설치하고 테스트합니다.

27 27

28<Steps>28<Steps>

29 <Step title="디렉터리 구조 생성">29 <Step title="디렉터리 구조 생성">

35 </Step>35 </Step>

36 36

37 <Step title="skill 생성">37 <Step title="skill 생성">

~~38 `/quality-review` skill이 수행하는 작업을 정의하는 `SKILL.md` 파일을 생성합니다.~~38 `quality-review` skill이 수행하는 작업을 정의하는 `SKILL.md` 파일을 생성합니다.

39 39

40 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}40 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}

41 ---41 ---

59 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}59 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}

60 {60 {

61 "name": "quality-review-plugin",61 "name": "quality-review-plugin",

~~62 "description": "빠른 코드 리뷰를 위한 /quality-review skill 추가",~~62 "description": "빠른 코드 리뷰를 위한 quality-review skill 추가",

63 "version": "1.0.0"63 "version": "1.0.0"

64 }64 }

65 ```65 ```

82 {82 {

83 "name": "quality-review-plugin",83 "name": "quality-review-plugin",

84 "source": "./plugins/quality-review-plugin",84 "source": "./plugins/quality-review-plugin",

~~85 "description": "빠른 코드 리뷰를 위한 /quality-review skill 추가"~~85 "description": "빠른 코드 리뷰를 위한 quality-review skill 추가"

86 }86 }

87 ]87 ]

88 }88 }

99 </Step>99 </Step>

100 100

101 <Step title="시도해보기">101 <Step title="시도해보기">

102 편집기에서 일부 코드를 선택하고 새 skill을 실행합니다.102 편집기에서 일부 코드를 선택하고 새 skill을 실행합니다. 플러그인 skill은 플러그인 이름으로 네임스페이스됩니다.

103 103

104 ```shell theme={null}104 ```shell theme={null}

105 /quality-review105 /quality-review-plugin:quality-review

106 ```106 ```

107 </Step>107 </Step>

108</Steps>108</Steps>

693* `hostPattern` 소스의 경우: 마켓플레이스 호스트가 정규식 패턴과 일치합니다693* `hostPattern` 소스의 경우: 마켓플레이스 호스트가 정규식 패턴과 일치합니다

694* `pathPattern` 소스의 경우: 마켓플레이스의 파일 시스템 경로가 정규식 패턴과 일치합니다694* `pathPattern` 소스의 경우: 마켓플레이스의 파일 시스템 경로가 정규식 패턴과 일치합니다

695 695

696정확한 일치는 URL을 정규화하지 않습니다. 후행 슬래시, `.git` 접미사 또는 `ssh://` 대 `https://` 형식은 다른 값으로 취급됩니다. 조직의 마켓플레이스를 둘 이상의 URL 형식으로 복제할 수 있는 경우 모든 형식이 일치하도록 리터럴 URL보다 `hostPattern` 항목을 선호합니다.

697

696`strictKnownMarketplaces`는 [관리되는 설정](/ko/settings#settings-files)에서 설정되므로 개별 사용자 및 프로젝트 구성은 이러한 제한을 재정의할 수 없습니다.698`strictKnownMarketplaces`는 [관리되는 설정](/ko/settings#settings-files)에서 설정되므로 개별 사용자 및 프로젝트 구성은 이러한 제한을 재정의할 수 없습니다.

697 699

698전체 구성 세부 정보(지원되는 모든 소스 유형 및 `extraKnownMarketplaces`와의 비교 포함)는 [strictKnownMarketplaces 참조](/ko/settings#strictknownmarketplaces)를 참조하세요.700전체 구성 세부 정보(지원되는 모든 소스 유형 및 `extraKnownMarketplaces`와의 비교 포함)는 [strictKnownMarketplaces 참조](/ko/settings#strictknownmarketplaces)를 참조하세요.

plugins-reference.md +7 −3

Details

262**사용 가능한 LSP 플러그인:**262**사용 가능한 LSP 플러그인:**

263 263

265| :--------------- | :------------------------- | :------------------------------------------------------------------------------ |265| :------------------ | :------------------------- | :------------------------------------------------------------------------------ |

269 269

270먼저 언어 서버를 설치한 다음 마켓플레이스에서 플러그인을 설치하세요.270먼저 언어 서버를 설치한 다음 마켓플레이스에서 플러그인을 설치하세요.

271 271

531 531

532Claude Code는 플러그인 경로를 참조하기 위한 두 가지 변수를 제공합니다. 둘 다 skill 콘텐츠, agent 콘텐츠, hook 명령어, monitor 명령어 및 MCP 또는 LSP 서버 구성에 나타나는 모든 곳에서 인라인으로 대체됩니다. 둘 다 hook 프로세스 및 MCP 또는 LSP 서버 서브프로세스에 환경 변수로 내보내집니다.532Claude Code는 플러그인 경로를 참조하기 위한 두 가지 변수를 제공합니다. 둘 다 skill 콘텐츠, agent 콘텐츠, hook 명령어, monitor 명령어 및 MCP 또는 LSP 서버 구성에 나타나는 모든 곳에서 인라인으로 대체됩니다. 둘 다 hook 프로세스 및 MCP 또는 LSP 서버 서브프로세스에 환경 변수로 내보내집니다.

533 533

534**`${CLAUDE_PLUGIN_ROOT}`**: 플러그인 설치 디렉토리의 절대 경로입니다. 플러그인과 함께 번들로 제공되는 스크립트, 바이너리 및 구성 파일을 참조하는 데 사용하세요. 이 경로는 플러그인이 업데이트될 때 변경되므로 여기에 작성하는 파일은 업데이트 후 유지되지 않습니다.534**`${CLAUDE_PLUGIN_ROOT}`**: 플러그인 설치 디렉토리의 절대 경로입니다. 플러그인과 함께 번들로 제공되는 스크립트, 바이너리 및 구성 파일을 참조하는 데 사용하세요. 이 경로는 플러그인이 업데이트될 때 변경됩니다. 이전 버전의 디렉토리는 업데이트 후 약 7일 동안 디스크에 남아 있지만 이를 임시로 취급하고 여기에 상태를 작성하지 마세요.

535

536플러그인이 세션 중에 업데이트될 때 hook 명령어, monitors, MCP 서버 및 LSP 서버는 이전 버전의 경로를 계속 사용합니다. `/reload-plugins`를 실행하여 hook, MCP 서버 및 LSP 서버를 새 경로로 전환하세요. monitors는 세션 재시작이 필요합니다.

535 537

536**`${CLAUDE_PLUGIN_DATA}`**: 업데이트 후에도 유지되는 플러그인 상태를 위한 영구 디렉토리입니다. `node_modules` 또는 Python 가상 환경과 같은 설치된 종속성, 생성된 코드, 캐시 및 플러그인 버전 전체에서 유지되어야 하는 기타 파일에 사용하세요. 이 변수가 처음 참조될 때 디렉토리가 자동으로 생성됩니다.538**`${CLAUDE_PLUGIN_DATA}`**: 업데이트 후에도 유지되는 플러그인 상태를 위한 영구 디렉토리입니다. `node_modules` 또는 Python 가상 환경과 같은 설치된 종속성, 생성된 코드, 캐시 및 플러그인 버전 전체에서 유지되어야 하는 기타 파일에 사용하세요. 이 변수가 처음 참조될 때 디렉토리가 자동으로 생성됩니다.

537 539

677 `.claude-plugin/` 디렉토리는 `plugin.json` 파일을 포함합니다. 다른 모든 디렉토리 (commands/, agents/, skills/, output-styles/, themes/, monitors/, hooks/)는 `.claude-plugin/` 내부가 아닌 플러그인 루트에 있어야 합니다.679 `.claude-plugin/` 디렉토리는 `plugin.json` 파일을 포함합니다. 다른 모든 디렉토리 (commands/, agents/, skills/, output-styles/, themes/, monitors/, hooks/)는 `.claude-plugin/` 내부가 아닌 플러그인 루트에 있어야 합니다.

678</Warning>680</Warning>

679 681

682`CLAUDE.md` 파일이 플러그인 루트에 있어도 프로젝트 컨텍스트로 로드되지 않습니다. 플러그인은 `CLAUDE.md`가 아닌 skills, agents, hooks를 통해 컨텍스트를 제공합니다. Claude의 컨텍스트에 로드되는 지침을 제공하려면 [skill](#skills)에 배치하십시오.

683

680### 파일 위치 참조684### 파일 위치 참조

681 685

682| 컴포넌트 | 기본 위치 | 목적 |686| 컴포넌트 | 기본 위치 | 목적 |

security.md +1 −1

Details

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

28* **쓰기 액세스 제한**: Claude Code는 시작된 폴더와 그 하위 폴더에만 쓸 수 있으며, 명시적 권한 없이 상위 디렉토리의 파일을 수정할 수 없습니다. Claude Code는 작업 디렉토리 외부의 파일을 읽을 수 있지만(시스템 라이브러리 및 종속성에 액세스하는 데 유용함), 쓰기 작업은 프로젝트 범위로 엄격히 제한되어 명확한 보안 경계를 만듭니다.28* **쓰기 액세스 제한**: Claude Code는 시작된 폴더와 그 하위 폴더에만 쓸 수 있으며, 명시적 권한 없이 상위 디렉토리의 파일을 수정할 수 없습니다. Claude Code는 작업 디렉토리 외부의 파일을 읽을 수 있지만(시스템 라이브러리 및 종속성에 액세스하는 데 유용함), 쓰기 작업은 프로젝트 범위로 엄격히 제한되어 명확한 보안 경계를 만듭니다.

29* **프롬프트 피로 완화**: 사용자별, 코드베이스별 또는 조직별로 자주 사용되는 안전한 명령을 허용 목록에 추가하는 지원29* **프롬프트 피로 완화**: 사용자별, 코드베이스별 또는 조직별로 자주 사용되는 안전한 명령을 허용 목록에 추가하는 지원

~~30* **Accept Edits 모드**: 여러 편집을 일괄 수락하면서 부작용이 있는 명령에 대한 권한 프롬프트를 유지합니다.~~30* **Accept Edits 모드**: 파일 편집을 자동으로 승인하고 작업 디렉토리의 경로에 대해 `mkdir`, `touch`, `rm`, `mv`, `cp`, `sed`와 같은 고정된 파일 시스템 Bash 명령 집합을 자동으로 승인합니다. 다른 Bash 명령과 범위를 벗어난 경로는 여전히 프롬프트를 표시합니다.

31 31

32### 사용자 책임32### 사용자 책임

33 33

settings.md +27 −4

Details

73 73

74Windows에서 `~/.claude`로 표시된 경로는 `%USERPROFILE%\.claude`로 확인됩니다.

74***76***

75 77

76## 설정 파일78## 설정 파일

167| `attribution` | git 커밋 및 pull request에 대한 attribution을 사용자 정의합니다. [Attribution 설정](#attribution-settings)을 참조하세요 | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |169| `attribution` | git 커밋 및 pull request에 대한 attribution을 사용자 정의합니다. [Attribution 설정](#attribution-settings)을 참조하세요 | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |

168| `autoMemoryDirectory` | [자동 메모리](/ko/memory#storage-location) 저장소를 위한 사용자 정의 디렉토리입니다. 절대 경로 또는 `~/` 접두사 경로를 허용합니다. 정책 및 사용자 설정과 `--settings` 플래그에서 허용됩니다. 복제된 저장소가 메모리 쓰기를 민감한 위치로 리디렉션할 수 있으므로 프로젝트 또는 local 설정에서는 허용되지 않습니다 | `"~/my-memory-dir"` |170| `autoMemoryDirectory` | [자동 메모리](/ko/memory#storage-location) 저장소를 위한 사용자 정의 디렉토리입니다. 절대 경로 또는 `~/` 접두사 경로를 허용합니다. 정책 및 사용자 설정과 `--settings` 플래그에서 허용됩니다. 복제된 저장소가 메모리 쓰기를 민감한 위치로 리디렉션할 수 있으므로 프로젝트 또는 local 설정에서는 허용되지 않습니다 | `"~/my-memory-dir"` |

171| `autoMemoryEnabled` | [자동 메모리](/ko/memory#enable-or-disable-auto-memory)를 활성화합니다. `false`일 때 Claude는 자동 메모리 디렉토리에서 읽거나 쓰지 않습니다. 기본값: `true`. 세션 중에 `/memory`로도 전환할 수 있습니다 | `false` |

169| `autoMode` | [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기가 차단하고 허용하는 것을 사용자 정의합니다. `environment`, `allow` 및 `soft_deny` 배열의 산문 규칙을 포함합니다. 배열에 리터럴 문자열 `"$defaults"`를 포함하여 해당 위치에서 기본 제공 규칙을 상속합니다. [자동 모드 구성](/ko/auto-mode-config)을 참조하세요. 공유 프로젝트 설정에서는 읽지 않음 | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |172| `autoMode` | [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기가 차단하고 허용하는 것을 사용자 정의합니다. `environment`, `allow` 및 `soft_deny` 배열의 산문 규칙을 포함합니다. 배열에 리터럴 문자열 `"$defaults"`를 포함하여 해당 위치에서 기본 제공 규칙을 상속합니다. [자동 모드 구성](/ko/auto-mode-config)을 참조하세요. 공유 프로젝트 설정에서는 읽지 않음 | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |

170| `autoScrollEnabled` | [fullscreen 렌더링](/ko/fullscreen)에서 새 출력을 대화의 맨 아래로 따릅니다. 기본값: `true`. `/config`에 **자동 스크롤**로 표시됩니다. 이것이 꺼져 있을 때도 권한 프롬프트는 여전히 보기로 스크롤됩니다 | `false` |173| `autoScrollEnabled` | [fullscreen 렌더링](/ko/fullscreen)에서 새 출력을 대화의 맨 아래로 따릅니다. 기본값: `true`. `/config`에 **자동 스크롤**로 표시됩니다. 이것이 꺼져 있을 때도 권한 프롬프트는 여전히 보기로 스크롤됩니다 | `false` |

175| `awsCredentialExport` | AWS 자격 증명이 포함된 JSON을 출력하는 사용자 정의 스크립트 ([고급 자격 증명 구성](/ko/amazon-bedrock#advanced-credential-configuration) 참조) | `/bin/generate_aws_grant.sh` |178| `awsCredentialExport` | AWS 자격 증명이 포함된 JSON을 출력하는 사용자 정의 스크립트 ([고급 자격 증명 구성](/ko/amazon-bedrock#advanced-credential-configuration) 참조) | `/bin/generate_aws_grant.sh` |

176| `blockedMarketplaces` | (Managed 설정만) 마켓플레이스 소스의 차단 목록입니다. 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로고침 및 자동 업데이트에 적용되므로 정책이 설정되기 전에 추가된 마켓플레이스는 플러그인을 가져오는 데 사용할 수 없습니다. 차단된 소스는 다운로드 전에 확인되므로 파일 시스템에 닿지 않습니다. [Managed 마켓플레이스 제한](/ko/plugin-marketplaces#managed-marketplace-restrictions)을 참조하세요 | `[{ "source": "github", "repo": "untrusted/plugins" }]` |179| `blockedMarketplaces` | (Managed 설정만) 마켓플레이스 소스의 차단 목록입니다. 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로고침 및 자동 업데이트에 적용되므로 정책이 설정되기 전에 추가된 마켓플레이스는 플러그인을 가져오는 데 사용할 수 없습니다. 차단된 소스는 다운로드 전에 확인되므로 파일 시스템에 닿지 않습니다. [Managed 마켓플레이스 제한](/ko/plugin-marketplaces#managed-marketplace-restrictions)을 참조하세요 | `[{ "source": "github", "repo": "untrusted/plugins" }]` |

177| `channelsEnabled` | (Managed 설정만) Team 및 Enterprise 사용자를 위해 [channels](/ko/channels)를 허용합니다. 설정되지 않거나 `false`이면 사용자가 `--channels`에 전달하는 것과 관계없이 채널 메시지 전달을 차단합니다 | `true` |180| `channelsEnabled` | (Managed 설정만) 조직을 위해 [channels](/ko/channels)를 허용합니다. Claude.ai Team 및 Enterprise 플랜에서 설정되지 않거나 `false`이면 채널이 차단됩니다. [Anthropic Console](/ko/authentication#claude-console-authentication) 계정이 API 키 인증을 사용하는 경우 조직이 managed 설정을 배포하지 않으면 기본적으로 채널이 허용되며, 이 경우 이 키를 `true`로 설정해야 합니다 | `true` |

178| `cleanupPeriodDays` | 이 기간보다 오래 비활성 상태인 세션 파일은 시작 시 삭제됩니다 (기본값: 30일, 최소 1). `0`으로 설정하면 검증 오류가 발생합니다. 또한 시작 시 [고아 subagent worktrees](/ko/worktrees#clean-up-worktrees)의 자동 제거에 대한 나이 기준을 제어합니다. 트랜스크립트 쓰기를 완전히 비활성화하려면 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/ko/env-vars) 환경 변수를 설정하거나 비대화형 모드 (`-p`)에서 `--no-session-persistence` 플래그 또는 `persistSession: false` SDK 옵션을 사용합니다. | `20` |181| `cleanupPeriodDays` | 이 기간보다 오래된 세션 파일은 시작 시 삭제됩니다 (기본값: 30일, 최소 1). `0`으로 설정하면 검증 오류가 발생합니다. 또한 시작 시 [고아 subagent worktrees](/ko/worktrees#clean-up-worktrees)의 자동 제거에 대한 나이 기준을 제어합니다. 트랜스크립트 쓰기를 완전히 비활성화하려면 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/ko/env-vars) 환경 변수를 설정하거나 비대화형 모드 (`-p`)에서 `--no-session-persistence` 플래그 또는 `persistSession: false` SDK 옵션을 사용합니다. | `20` |

180| `defaultShell` | 입력 상자 `!` 명령의 기본 셸입니다. `"bash"` (기본값) 또는 `"powershell"`을 허용합니다. `"powershell"`을 설정하면 Windows에서 대화형 `!` 명령을 PowerShell을 통해 라우팅합니다. `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`이 필요합니다. [PowerShell 도구](/ko/tools-reference#powershell-tool)를 참조하세요 | `"powershell"` |183| `defaultShell` | 입력 상자 `!` 명령의 기본 셸입니다. `"bash"` (기본값) 또는 `"powershell"`을 허용합니다. `"powershell"`을 설정하면 Windows에서 대화형 `!` 명령을 PowerShell을 통해 라우팅합니다. `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`이 필요합니다. [PowerShell 도구](/ko/tools-reference#powershell-tool)를 참조하세요 | `"powershell"` |

181| `deniedMcpServers` | Managed 설정에서 설정되면 명시적으로 차단된 MCP 서버의 거부 목록입니다. Managed 서버를 포함한 모든 범위에 적용됩니다. 거부 목록이 허용 목록보다 우선합니다. [Managed MCP 구성](/ko/mcp#managed-mcp-configuration)을 참조하세요 | `[{ "serverName": "filesystem" }]` |184| `deniedMcpServers` | Managed 설정에서 설정되면 명시적으로 차단된 MCP 서버의 거부 목록입니다. Managed 서버를 포함한 모든 범위에 적용됩니다. 거부 목록이 허용 목록보다 우선합니다. [Managed MCP 구성](/ko/mcp#managed-mcp-configuration)을 참조하세요 | `[{ "serverName": "filesystem" }]` |

183| `disableAutoMode` | [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)가 활성화되는 것을 방지하려면 `"disable"`로 설정합니다. `Shift+Tab` 순환에서 `auto`를 제거하고 시작 시 `--permission-mode auto`를 거부합니다. [managed 설정](/ko/permissions#managed-settings)에서 사용자가 재정의할 수 없을 때 가장 유용합니다 | `"disable"` |186| `disableAutoMode` | [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)가 활성화되는 것을 방지하려면 `"disable"`로 설정합니다. `Shift+Tab` 순환에서 `auto`를 제거하고 시작 시 `--permission-mode auto`를 거부합니다. [managed 설정](/ko/permissions#managed-settings)에서 사용자가 재정의할 수 없을 때 가장 유용합니다 | `"disable"` |

184| `disableDeepLinkRegistration` | Claude Code가 시작 시 운영 체제에 `claude-cli://` 프로토콜 핸들러를 등록하는 것을 방지하려면 `"disable"`로 설정합니다. [Deep links](/ko/deep-links)를 사용하면 외부 도구가 사전 채워진 프롬프트로 Claude Code 세션을 열 수 있습니다. 프로토콜 핸들러 등록이 제한되거나 별도로 관리되는 환경에서 유용합니다 | `"disable"` |187| `disableDeepLinkRegistration` | Claude Code가 시작 시 운영 체제에 `claude-cli://` 프로토콜 핸들러를 등록하는 것을 방지하려면 `"disable"`로 설정합니다. [Deep links](/ko/deep-links)를 사용하면 외부 도구가 사전 채워진 프롬프트로 Claude Code 세션을 열 수 있습니다. 프로토콜 핸들러 등록이 제한되거나 별도로 관리되는 환경에서 유용합니다 | `"disable"` |

189| `disableRemoteControl` | {/* min-version: 2.1.128 */}[Remote Control](/ko/remote-control) 비활성화: `claude remote-control`, `--remote-control` 플래그, 자동 시작 및 세션 내 전환을 차단합니다. 일반적으로 장치별 MDM 적용을 위해 [managed 설정](/ko/permissions#managed-settings)에 배치되지만 모든 범위에서 작동합니다. Claude Code v2.1.128 이상이 필요합니다 | `true` |

186| `disableSkillShellExecution` | [skills](/ko/skills) 및 사용자, 프로젝트, 플러그인 또는 추가 디렉토리 소스의 사용자 정의 명령에서 `` !`...` `` 및 ` ```! ` 블록에 대한 인라인 셸 실행을 비활성화합니다. 명령은 실행되는 대신 `[shell command execution disabled by policy]`로 대체됩니다. 번들 및 managed skills는 영향을 받지 않습니다. [managed 설정](/ko/permissions#managed-settings)에서 사용자가 재정의할 수 없을 때 가장 유용합니다 | `true` |190| `disableSkillShellExecution` | [skills](/ko/skills) 및 사용자, 프로젝트, 플러그인 또는 추가 디렉토리 소스의 사용자 정의 명령에서 `` !`...` `` 및 ` ```! ` 블록에 대한 인라인 셸 실행을 비활성화합니다. 명령은 실행되는 대신 `[shell command execution disabled by policy]`로 대체됩니다. 번들 및 managed skills는 영향을 받지 않습니다. [managed 설정](/ko/permissions#managed-settings)에서 사용자가 재정의할 수 없을 때 가장 유용합니다 | `true` |

187| `editorMode` | 입력 프롬프트의 키 바인딩 모드: `"normal"` 또는 `"vim"`. 기본값: `"normal"`. `/config`에 **편집기 모드**로 표시됩니다 | `"vim"` |191| `editorMode` | 입력 프롬프트의 키 바인딩 모드: `"normal"` 또는 `"vim"`. 기본값: `"normal"`. `/config`에 **편집기 모드**로 표시됩니다 | `"vim"` |

188| `effortLevel` | [노력 수준](/ko/model-config#adjust-effort-level)을 세션 간에 유지합니다. `"low"`, `"medium"`, `"high"` 또는 `"xhigh"`를 허용합니다. `/effort`를 이러한 값 중 하나로 실행할 때 자동으로 작성됩니다. [노력 수준 조정](/ko/model-config#adjust-effort-level)에서 지원되는 모델을 참조하세요 | `"xhigh"` |192| `effortLevel` | [노력 수준](/ko/model-config#adjust-effort-level)을 세션 간에 유지합니다. `"low"`, `"medium"`, `"high"` 또는 `"xhigh"`를 허용합니다. `/effort`를 이러한 값 중 하나로 실행할 때 자동으로 작성됩니다. [노력 수준 조정](/ko/model-config#adjust-effort-level)에서 지원되는 모델을 참조하세요 | `"xhigh"` |

550 },554 },

551 "extraKnownMarketplaces": {555 "extraKnownMarketplaces": {

552 "acme-tools": {556 "acme-tools": {

557 "source": {

553 "source": "github",558 "source": "github",

554 "repo": "acme-corp/claude-plugins"559 "repo": "acme-corp/claude-plugins"

555 }560 }

556 }561 }

562 }

557}563}

558```564```

559 565

568* **Local 설정** (`.claude/settings.local.json`): 머신별 재정의 (커밋되지 않음)574* **Local 설정** (`.claude/settings.local.json`): 머신별 재정의 (커밋되지 않음)

569* **Managed 설정** (`managed-settings.json`): 모든 범위에서 설치를 차단하고 마켓플레이스에서 플러그인을 숨기는 조직 전체 정책 재정의575* **Managed 설정** (`managed-settings.json`): 모든 범위에서 설치를 차단하고 마켓플레이스에서 플러그인을 숨기는 조직 전체 정책 재정의

570 576

577<Note>

578 프로젝트 설정은 사용자 설정보다 우선순위가 높으므로 `~/.claude/settings.json`에서 플러그인을 `false`로 설정해도 프로젝트의 `.claude/settings.json`이 활성화하는 플러그인은 비활성화되지 않습니다. 머신에서 프로젝트 활성화 플러그인을 거부하려면 대신 `.claude/settings.local.json`에서 `false`로 설정합니다.

579

580 Managed 설정으로 강제 활성화된 플러그인은 managed 설정이 local 설정을 재정의하므로 이 방식으로 비활성화할 수 없습니다.

581</Note>

582

571**예제**:583**예제**:

572 584

573```json theme={null}585```json theme={null}

659* Managed 설정 (`managed-settings.json`)에서만 사용 가능671* Managed 설정 (`managed-settings.json`)에서만 사용 가능

660* 사용자 또는 프로젝트 설정으로 재정의할 수 없음 (최고 우선순위)672* 사용자 또는 프로젝트 설정으로 재정의할 수 없음 (최고 우선순위)

661* 네트워크/파일 시스템 작업 전에 적용됨 (차단된 소스는 실행되지 않음)673* 네트워크/파일 시스템 작업 전에 적용됨 (차단된 소스는 실행되지 않음)

662* `hostPattern`을 제외한 소스 사양에 대해 정확한 일치를 사용합니다. `hostPattern`은 정규식 일치를 사용합니다674* `hostPattern` 및 `pathPattern`을 제외한 소스 사양에 대해 정확한 일치를 사용합니다. `hostPattern` 및 `pathPattern`은 정규식 일치를 사용합니다

663 675

664**허용 목록 동작**:676**허용 목록 동작**:

665 677

669 681

670**지원되는 모든 소스 유형**:682**지원되는 모든 소스 유형**:

671 683

672허용 목록은 여러 마켓플레이스 소스 유형을 지원합니다. 대부분의 소스는 정확한 일치를 사용하는 반면 `hostPattern`은 마켓플레이스 호스트에 대한 정규식 일치를 사용합니다.684허용 목록은 여러 마켓플레이스 소스 유형을 지원합니다. 대부분의 소스는 정확한 일치를 사용하는 반면 `hostPattern` 및 `pathPattern`은 마켓플레이스 호스트 및 파일 시스템 경로에 대한 정규식 일치를 각각 사용합니다.

673 685

6741. **GitHub 저장소**:6861. **GitHub 저장소**:

675 687

749* `url`: URL에서 호스트 이름 추출761* `url`: URL에서 호스트 이름 추출

750* `npm`, `file`, `directory`: 호스트 패턴 일치에 지원되지 않음762* `npm`, `file`, `directory`: 호스트 패턴 일치에 지원되지 않음

751 763

7648. **경로 패턴 일치**:

765

766```json theme={null}

767{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }

768{ "source": "pathPattern", "pathPattern": ".*" }

769```

770

771필드: `pathPattern` (필수: `file` 및 `directory` 소스의 `path` 필드와 일치하는 정규식 패턴)

772

773네트워크 소스에 대한 `hostPattern` 제한과 함께 파일 시스템 기반 마켓플레이스를 허용하려면 경로 패턴 일치를 사용합니다. 모든 로컬 경로를 허용하려면 `".*"`를 설정하거나 특정 디렉토리로 제한하려면 더 좁은 패턴을 설정합니다.

774

752**구성 예제**:775**구성 예제**:

753 776

754예제: 특정 마켓플레이스만 허용:777예제: 특정 마켓플레이스만 허용:

sub-agents.md +38 −13

Details

51 </Tab>51 </Tab>

52 52

53 <Tab title="Plan">53 <Tab title="Plan">

~~54 [plan mode](/ko/common-workflows#use-plan-mode-for-safe-code-analysis) 중에 계획을 제시하기 전에 컨텍스트를 수집하는 데 사용되는 연구 에이전트입니다.~~54 [plan mode](/ko/permission-modes#analyze-before-you-edit-with-plan-mode) 중에 계획을 제시하기 전에 컨텍스트를 수집하는 데 사용되는 연구 에이전트입니다.

55 55

56 * **모델**: 주 대화에서 상속56 * **모델**: 주 대화에서 상속

57 * **도구**: 읽기 전용 도구 (Write 및 Edit 도구에 대한 액세스 거부)57 * **도구**: 읽기 전용 도구 (Write 및 Edit 도구에 대한 액세스 거부)

76 | 에이전트 | 모델 | Claude가 사용하는 경우 |76 | 에이전트 | 모델 | Claude가 사용하는 경우 |

77 | :---------------- | :----- | :-------------------------------- |77 | :---------------- | :----- | :-------------------------------- |

80 </Tab>80 </Tab>

81</Tabs>81</Tabs>

82 82

180 180

181**CLI 정의 subagent**는 Claude Code를 시작할 때 JSON으로 전달됩니다. 해당 세션에만 존재하며 디스크에 저장되지 않으므로 빠른 테스트 또는 자동화 스크립트에 유용합니다. 단일 `--agents` 호출에서 여러 subagent를 정의할 수 있습니다:181**CLI 정의 subagent**는 Claude Code를 시작할 때 JSON으로 전달됩니다. 해당 세션에만 존재하며 디스크에 저장되지 않으므로 빠른 테스트 또는 자동화 스크립트에 유용합니다. 단일 `--agents` 호출에서 여러 subagent를 정의할 수 있습니다:

182 182

183```bash theme={null}183<Tabs>

184claude --agents '{184 <Tab title="macOS, Linux, WSL">

185 ```bash theme={null}

186 claude --agents '{

185 "code-reviewer": {187 "code-reviewer": {

186 "description": "Expert code reviewer. Use proactively after code changes.",188 "description": "Expert code reviewer. Use proactively after code changes.",

187 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",189 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",

192 "description": "Debugging specialist for errors and test failures.",194 "description": "Debugging specialist for errors and test failures.",

193 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."195 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."

194 }196 }

195}'197 }'

196```198 ```

199 </Tab>

200

201 <Tab title="Windows PowerShell">

202 ```powershell theme={null}

203 claude --agents @'

204 {

205 "code-reviewer": {

206 "description": "Expert code reviewer. Use proactively after code changes.",

207 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",

208 "tools": ["Read", "Grep", "Glob", "Bash"],

209 "model": "sonnet"

210 },

211 "debugger": {

212 "description": "Debugging specialist for errors and test failures.",

213 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."

214 }

215 }

216 '@

217 ```

218 </Tab>

219</Tabs>

197 220

198`--agents` 플래그는 파일 기반 subagent와 동일한 [frontmatter](#supported-frontmatter-fields) 필드를 가진 JSON을 허용합니다: `description`, `prompt`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, `isolation`, `color`. 시스템 프롬프트에는 `prompt`를 사용하며, 이는 파일 기반 subagent의 markdown 본문과 동등합니다.221`--agents` 플래그는 파일 기반 subagent와 동일한 [frontmatter](#supported-frontmatter-fields) 필드를 가진 JSON을 허용합니다: `description`, `prompt`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, `isolation`, `color`. 시스템 프롬프트에는 `prompt`를 사용하며, 이는 파일 기반 subagent의 markdown 본문과 동등합니다.

199 222

212Subagent 파일은 구성을 위한 YAML frontmatter를 사용하고 그 뒤에 Markdown의 시스템 프롬프트가 옵니다:235Subagent 파일은 구성을 위한 YAML frontmatter를 사용하고 그 뒤에 Markdown의 시스템 프롬프트가 옵니다:

213 236

214<Note>237<Note>

215 Subagent는 세션 시작 시 로드됩니다. 파일을 수동으로 추가하여 subagent를 만드는 경우 세션을 다시 시작하거나 `/agents`를 사용하여 즉시 로드합니다.238 Subagent는 세션 시작 시 로드됩니다. 디스크에서 subagent 파일을 직접 추가하거나 편집하면 세션을 다시 시작하여 로드합니다. `/agents` 인터페이스를 통해 생성된 subagent는 다시 시작하지 않고도 즉시 적용됩니다.

216</Note>239</Note>

217 240

218```markdown theme={null}241```markdown theme={null}

250| `memory` | 아니오 | [지속적 메모리 범위](#enable-persistent-memory): `user`, `project`, 또는 `local`. 교차 세션 학습 활성화 |273| `memory` | 아니오 | [지속적 메모리 범위](#enable-persistent-memory): `user`, `project`, 또는 `local`. 교차 세션 학습 활성화 |

251| `background` | 아니오 | 이 subagent를 항상 [background task](#run-subagents-in-foreground-or-background)로 실행하려면 `true`로 설정합니다. 기본값: `false` |274| `background` | 아니오 | 이 subagent를 항상 [background task](#run-subagents-in-foreground-or-background)로 실행하려면 `true`로 설정합니다. 기본값: `false` |

252| `effort` | 아니오 | 이 subagent가 활성화될 때의 노력 수준. 세션 노력 수준을 재정의합니다. 기본값: 세션에서 상속. 옵션: `low`, `medium`, `high`, `xhigh`, `max` (사용 가능한 수준은 모델에 따라 다름) |275| `effort` | 아니오 | 이 subagent가 활성화될 때의 노력 수준. 세션 노력 수준을 재정의합니다. 기본값: 세션에서 상속. 옵션: `low`, `medium`, `high`, `xhigh`, `max` (사용 가능한 수준은 모델에 따라 다름) |

253| `isolation` | 아니오 | Subagent를 임시 [git worktree](/ko/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees)에서 실행하려면 `worktree`로 설정하여 저장소의 격리된 복사본을 제공합니다. Subagent가 변경 사항을 만들지 않으면 worktree가 자동으로 정리됩니다 |276| `isolation` | 아니오 | Subagent를 임시 [git worktree](/ko/worktrees)에서 실행하려면 `worktree`로 설정하여 저장소의 격리된 복사본을 제공합니다. Subagent가 변경 사항을 만들지 않으면 worktree가 자동으로 정리됩니다 |

254| `color` | 아니오 | 작업 목록 및 트랜스크립트에서 subagent의 표시 색상입니다. `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, 또는 `cyan`을 허용합니다 |277| `color` | 아니오 | 작업 목록 및 트랜스크립트에서 subagent의 표시 색상입니다. `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, 또는 `cyan`을 허용합니다 |

255| `initialPrompt` | 아니오 | 이 에이전트가 주 세션 에이전트로 실행될 때 (`--agent` 또는 `agent` 설정을 통해) 첫 번째 사용자 턴으로 자동 제출됩니다. [Commands](/ko/commands) 및 [Skills](/ko/skills)가 처리됩니다. 사용자 제공 프롬프트에 앞에 붙습니다 |278| `initialPrompt` | 아니오 | 이 에이전트가 주 세션 에이전트로 실행될 때 (`--agent` 또는 `agent` 설정을 통해) 첫 번째 사용자 턴으로 자동 제출됩니다. [Commands](/ko/commands) 및 [Skills](/ko/skills)가 처리됩니다. 사용자 제공 프롬프트에 앞에 붙습니다 |

256 279

484exit 0507exit 0

485```508```

486 509

487전체 입력 스키마는 [Hook input](/ko/hooks#pretooluse-input)을 참조하고 종료 코드가 동작에 미치는 영향은 [exit codes](/ko/hooks#exit-code-output)를 참조하세요.510전체 입력 스키마는 [Hook input](/ko/hooks#pretooluse-input)을 참조하고 종료 코드가 동작에 미치는 영향은 [exit codes](/ko/hooks#exit-code-output)를 참조하세요. Windows에서는 PowerShell로 hook 스크립트를 작성하고 [PowerShell에서 hook 실행](/ko/hooks#windows-powershell-tool)에 표시된 대로 hook 항목에 `shell: powershell`을 추가합니다.

488 511

489#### 특정 subagent 비활성화512#### 특정 subagent 비활성화

490 513

829 852

830### 코드 검토자853### 코드 검토자

831 854

832수정하지 않고 코드를 검토하는 읽기 전용 subagent입니다. 이 예제는 제한된 도구 액세스 (Edit 또는 Write 없음)와 정확히 무엇을 찾을지 및 출력 형식을 지정하는 자세한 프롬프트를 사용하여 집중된 subagent를 설계하는 방법을 보여줍니다.855수정하지 않고 코드를 검토하는 읽기 전용 subagent입니다. 이 예제는 제한된 도구 액세스(Edit 또는 Write 없음)와 정확히 무엇을 찾을지 및 출력 형식을 지정하는 자세한 프롬프트를 사용하여 집중된 subagent를 설계하는 방법을 보여줍니다.

833 856

834```markdown theme={null}857```markdown theme={null}

835---858---

903 926

904### 데이터 과학자927### 데이터 과학자

905 928

906데이터 분석 작업을 위한 도메인별 subagent입니다. 이 예제는 일반적인 코딩 작업 외에 특화된 워크플로우를 위해 subagent를 만드는 방법을 보여줍니다. 명시적으로 `model: sonnet`을 설정하여 더 유능한 분석을 수행합니다.929데이터 분석 작업을 위한 도메인별 subagent입니다. 이 예제는 일반적인 코딩 작업 외에 특화된 워크플로우를 위해 subagent를 만드는 방법을 보여줍니다. 더 유능한 분석을 위해 명시적으로 `model: sonnet`을 설정합니다.

907 930

908```markdown theme={null}931```markdown theme={null}

909---932---

992exit 01015exit 0

993```1016```

994 1017

995스크립트를 실행 가능하게 만듭니다:1018macOS 및 Linux에서 스크립트를 실행 가능하게 만듭니다:

996 1019

997```bash theme={null}1020```bash theme={null}

998chmod +x ./scripts/validate-readonly-query.sh1021chmod +x ./scripts/validate-readonly-query.sh

999```1022```

1000 1023

1001Hook은 stdin을 통해 JSON을 받으며 Bash 명령은 `tool_input.command`에 있습니다. 종료 코드 2는 작업을 차단하고 오류 메시지를 Claude에 피드백합니다. 종료 코드 및 [Hook input](/ko/hooks#pretooluse-input)에 대한 자세한 내용은 [Hooks](/ko/hooks#exit-code-output)를 참조하세요.1024Windows에서는 검증 스크립트를 PowerShell로 작성하고 hook 항목에 `shell: powershell`을 추가합니다. [PowerShell에서 hook 실행](/ko/hooks#windows-powershell-tool)을 참조하세요.

1025

1026Hook은 stdin을 통해 JSON을 받으며 Bash 명령은 `tool_input.command`에 있습니다. 종료 코드 2는 작업을 차단하고 오류 메시지를 Claude에 피드백합니다. 종료 코드 및 출력에 대한 자세한 내용은 [Hooks](/ko/hooks#exit-code-output)를 참조하고 [Hook input](/ko/hooks#pretooluse-input)에서 전체 입력 스키마를 확인하세요.

1002 1027

1003## 다음 단계1028## 다음 단계

1004 1029

vs-code.md +13 −3

Details

95* **권한 모드**: 프롬프트 상자 하단의 모드 표시기를 클릭하여 모드를 전환합니다. 일반 모드에서 Claude는 각 작업 전에 권한을 요청합니다. Plan Mode에서 Claude는 수행할 작업을 설명하고 변경을 수행하기 전에 승인을 기다립니다. VS Code는 자동으로 계획을 전체 markdown 문서로 열어서 Claude가 시작하기 전에 피드백을 제공하기 위해 인라인 주석을 추가할 수 있습니다. 자동 수락 모드에서 Claude는 요청 없이 편집을 수행합니다. VS Code 설정의 `claudeCode.initialPermissionMode`에서 기본값을 설정합니다.95* **권한 모드**: 프롬프트 상자 하단의 모드 표시기를 클릭하여 모드를 전환합니다. 일반 모드에서 Claude는 각 작업 전에 권한을 요청합니다. Plan Mode에서 Claude는 수행할 작업을 설명하고 변경을 수행하기 전에 승인을 기다립니다. VS Code는 자동으로 계획을 전체 markdown 문서로 열어서 Claude가 시작하기 전에 피드백을 제공하기 위해 인라인 주석을 추가할 수 있습니다. 자동 수락 모드에서 Claude는 요청 없이 편집을 수행합니다. VS Code 설정의 `claudeCode.initialPermissionMode`에서 기본값을 설정합니다.

96* **명령 메뉴**: `/`를 클릭하거나 입력하여 명령 메뉴를 엽니다. 옵션에는 파일 첨부, 모델 전환, 확장 사고 토글, 계획 사용량 보기(`/usage`) 및 [Remote Control](/ko/remote-control) 세션 시작(`/remote-control`)이 포함됩니다. 사용자 정의 섹션은 MCP 서버, hooks, 메모리, 권한 및 플러그인에 대한 액세스를 제공합니다. 터미널 아이콘이 있는 항목은 통합 터미널에서 열립니다.96* **명령 메뉴**: `/`를 클릭하거나 입력하여 명령 메뉴를 엽니다. 옵션에는 파일 첨부, 모델 전환, 확장 사고 토글, 계획 사용량 보기(`/usage`) 및 [Remote Control](/ko/remote-control) 세션 시작(`/remote-control`)이 포함됩니다. 사용자 정의 섹션은 MCP 서버, hooks, 메모리, 권한 및 플러그인에 대한 액세스를 제공합니다. 터미널 아이콘이 있는 항목은 통합 터미널에서 열립니다.

97* **컨텍스트 표시기**: 프롬프트 상자는 Claude의 context window를 얼마나 사용하고 있는지 표시합니다. Claude는 필요할 때 자동으로 압축하거나 `/compact`를 수동으로 실행할 수 있습니다.97* **컨텍스트 표시기**: 프롬프트 상자는 Claude의 context window를 얼마나 사용하고 있는지 표시합니다. Claude는 필요할 때 자동으로 압축하거나 `/compact`를 수동으로 실행할 수 있습니다.

98* **확장 사고**: Claude가 복잡한 문제를 추론하는 데 더 많은 시간을 소비할 수 있습니다. 명령 메뉴(`/`)를 통해 켭니다. Claude의 추론은 대화에 축소된 블록으로 나타납니다: 블록을 클릭하여 읽거나 `Ctrl+O`를 눌러 세션의 모든 사고 블록을 확장하거나 축소합니다. 자세한 내용은 [확장 사고](/ko/common-workflows#use-extended-thinking-thinking-mode)를 참조하십시오.98* **확장 사고**: Claude가 복잡한 문제를 추론하는 데 더 많은 시간을 소비할 수 있습니다. 명령 메뉴(`/`)를 통해 켭니다. Claude의 추론은 대화에 축소된 블록으로 나타납니다: 블록을 클릭하여 읽거나 `Ctrl+O`를 눌러 세션의 모든 사고 블록을 확장하거나 축소합니다. 자세한 내용은 [확장 사고](/ko/model-config#extended-thinking)를 참조하십시오.

99* **여러 줄 입력**: `Shift+Enter`를 눌러 보내지 않고 새 줄을 추가합니다. 이것은 질문 대화의 "기타" 자유 텍스트 입력에서도 작동합니다.99* **여러 줄 입력**: `Shift+Enter`를 눌러 보내지 않고 새 줄을 추가합니다. 이것은 질문 대화의 "기타" 자유 텍스트 입력에서도 작동합니다.

100 100

101### 파일 및 폴더 참조101### 파일 및 폴더 참조

115 115

116### 과거 대화 재개116### 과거 대화 재개

117 117

118Claude Code 패널 상단의 **세션 기록** 버튼을 클릭하여 대화 기록에 액세스합니다. 키워드로 검색하거나 시간별로 찾아볼 수 있습니다(오늘, 어제, 지난 7일 등). 대화를 클릭하여 전체 메시지 기록으로 재개합니다. 새 세션은 첫 번째 메시지를 기반으로 AI가 생성한 제목을 받습니다. 세션 위에 마우스를 올려 이름 바꾸기 및 제거 작업을 표시합니다: 설명적인 제목으로 이름을 바꾸거나 목록에서 삭제하려면 제거합니다. 세션 재개에 대한 자세한 내용은 [일반적인 워크플로우](/ko/common-workflows#resume-previous-conversations)를 참조하십시오.118Claude Code 패널 상단의 **세션 기록** 버튼을 클릭하여 대화 기록에 액세스합니다. 키워드로 검색하거나 시간별로 찾아볼 수 있습니다(오늘, 어제, 지난 7일 등). 대화를 클릭하여 전체 메시지 기록으로 재개합니다. 새 세션은 첫 번째 메시지를 기반으로 AI가 생성한 제목을 받습니다. 세션 위에 마우스를 올려 이름 바꾸기 및 제거 작업을 표시합니다: 설명적인 제목으로 이름을 바꾸거나 목록에서 삭제하려면 제거합니다. 세션 재개에 대한 자세한 내용은 [세션 관리](/ko/sessions)를 참조하십시오.

119 119

120### Claude.ai에서 원격 세션 재개120### Claude.ai에서 원격 세션 재개

121 121

399claude --worktree feature-auth399claude --worktree feature-auth

400```400```

401 401

402각 worktree는 git 기록을 공유하면서 독립적인 파일 상태를 유지합니다. 이렇게 하면 Claude 인스턴스가 다양한 작업을 수행할 때 서로 간섭하지 않습니다. 자세한 내용은 [Git worktrees를 사용하여 병렬 Claude Code 세션 실행](/ko/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees)을 참조하십시오.402각 worktree는 git 기록을 공유하면서 독립적인 파일 상태를 유지합니다. 이렇게 하면 Claude 인스턴스가 다양한 작업을 수행할 때 서로 간섭하지 않습니다. 자세한 내용은 [Git worktrees를 사용하여 병렬 세션 실행](/ko/worktrees)을 참조하십시오.

403 403

404## 타사 공급자 사용404## 타사 공급자 사용

405 405

476 476

477또는 **상태 표시줄**(오른쪽 아래 모서리)에서 "✱ Claude Code"를 클릭합니다. 파일을 열지 않았을 때도 작동합니다. **명령 팔레트**(`Cmd+Shift+P` / `Ctrl+Shift+P`)를 사용하고 "Claude Code"를 입력할 수도 있습니다.477또는 **상태 표시줄**(오른쪽 아래 모서리)에서 "✱ Claude Code"를 클릭합니다. 파일을 열지 않았을 때도 작동합니다. **명령 팔레트**(`Cmd+Shift+P` / `Ctrl+Shift+P`)를 사용하고 "Claude Code"를 입력할 수도 있습니다.

478 478

479### macOS에서 Cmd+Esc가 작동하지 않음

480

481macOS Tahoe 이상에서는 시스템 Game Overlay 단축키가 기본적으로 `Cmd+Esc`에 바인딩되어 있으며 VS Code에 도달하기 전에 키 입력을 가로챕니다. 단축키를 해제하려면:

482

4831. 시스템 설정 열기

4842. 키보드로 이동한 후 키보드 단축키, 그 다음 게임 컨트롤러로 이동

4853. Game Overlay 체크박스 선택 해제

486

487또는 확장 프로그램을 다른 키로 다시 바인딩합니다. VS Code [키보드 단축키 편집기](https://code.visualstudio.com/docs/configure/keybindings)(`Cmd+K Cmd+S`)를 열고 `Claude Code: Focus input`을 검색한 후 새 바인딩을 할당합니다.

488

479### Claude Code가 응답하지 않음489### Claude Code가 응답하지 않음

480 490

481Claude Code가 프롬프트에 응답하지 않으면:491Claude Code가 프롬프트에 응답하지 않으면:

Documentation 2026-05-04 22:58 UTC to 2026-05-05 23:00 UTC