Documentation — Spybara

agent-sdk/claude-code-features.md +16 −14

Details

14 14

15## settingSources로 파일시스템 설정 제어하기15## settingSources로 파일시스템 설정 제어하기

16 16

17설정 소스 옵션(Python의 [`setting_sources`](/ko/agent-sdk/python#claude-agent-options), TypeScript의 [`settingSources`](/ko/agent-sdk/typescript#setting-source))은 SDK가 로드하는 파일시스템 기반 설정을 제어합니다. 특정 소스를 선택하려면 명시적 목록을 전달하거나, 사용자, 프로젝트 및 로컬 설정을 비활성화하려면 빈 배열을 전달합니다.17설정 소스 옵션(Python의 [`setting_sources`](/ko/agent-sdk/python#claudeagentoptions), TypeScript의 [`settingSources`](/ko/agent-sdk/typescript#settingsource))은 SDK가 로드하는 파일시스템 기반 설정을 제어합니다. 특정 소스를 선택하려면 명시적 목록을 전달하거나, 사용자, 프로젝트 및 로컬 설정을 비활성화하려면 빈 배열을 전달합니다.

18 18

19이 예제는 `settingSources`를 `["user", "project"]`로 설정하여 사용자 수준 및 프로젝트 수준 설정을 모두 로드합니다:19이 예제는 `settingSources`를 `["user", "project"]`로 설정하여 사용자 수준 및 프로젝트 수준 설정을 모두 로드합니다:

20 20

65 ```65 ```

66</CodeGroup>66</CodeGroup>

67 67

68각 소스는 특정 위치에서 설정을 로드합니다. 여기서 `<cwd>`는 `cwd` 옵션을 통해 전달하는 작업 디렉토리입니다(설정되지 않은 경우 프로세스의 현재 디렉토리). 전체 타입 정의는 [`SettingSource`](/ko/agent-sdk/typescript#setting-source)(TypeScript) 또는 [`SettingSource`](/ko/agent-sdk/python#setting-source)(Python)을 참조하세요.68각 소스는 특정 위치에서 설정을 로드합니다. 여기서 `<cwd>`는 `cwd` 옵션을 통해 전달하는 작업 디렉토리이거나, 설정되지 않은 경우 프로세스의 현재 디렉토리입니다. 전체 타입 정의는 [`SettingSource`](/ko/agent-sdk/typescript#settingsource)(TypeScript) 또는 [`SettingSource`](/ko/agent-sdk/python#settingsource)(Python)을 참조하세요.

69 69

70| 소스 | 로드되는 항목 | 위치 |70| 소스 | 로드되는 항목 | 위치 |

71| :---------- | :-------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |71| :---------- | :-------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |

119 119

120스킬은 에이전트에 전문 지식과 호출 가능한 워크플로우를 제공하는 마크다운 파일입니다. `CLAUDE.md`(모든 세션에서 로드)와 달리 스킬은 필요에 따라 로드됩니다. 에이전트는 시작 시 스킬 설명을 받고 관련이 있을 때 전체 콘텐츠를 로드합니다.120스킬은 에이전트에 전문 지식과 호출 가능한 워크플로우를 제공하는 마크다운 파일입니다. `CLAUDE.md`(모든 세션에서 로드)와 달리 스킬은 필요에 따라 로드됩니다. 에이전트는 시작 시 스킬 설명을 받고 관련이 있을 때 전체 콘텐츠를 로드합니다.

121 121

122스킬은 `settingSources`를 통해 파일시스템에서 발견됩니다. 기본 옵션을 사용하면 사용자 및 프로젝트 스킬이 자동으로 로드됩니다. `allowedTools`를 지정하지 않으면 `Skill` 도구가 기본적으로 활성화됩니다. `allowedTools` 허용 목록을 사용하는 경우 `"Skill"`을 명시적으로 포함합니다.122스킬은 `settingSources`를 통해 파일시스템에서 발견됩니다. `query()`에서 `skills` 옵션을 생략하면 발견된 사용자 및 프로젝트 스킬이 활성화되고 Skill 도구를 사용할 수 있으며, CLI 동작과 일치합니다. 활성화된 스킬을 제어하려면 `skills`를 `"all"`, 스킬 이름 목록 또는 모두 비활성화하려면 `[]`로 전달합니다. SDK는 `skills`가 설정되면 Skill 도구를 자동으로 활성화하므로 `allowedTools`에 추가할 필요가 없습니다.

123 123

124<CodeGroup>124<CodeGroup>

125 ```python Python theme={null}125 ```python Python theme={null}

131 prompt="Review this PR using our code review checklist",131 prompt="Review this PR using our code review checklist",

132 options=ClaudeAgentOptions(132 options=ClaudeAgentOptions(

133 setting_sources=["user", "project"],133 setting_sources=["user", "project"],

134 allowed_tools=["Skill", "Read", "Grep", "Glob"],134 skills="all",

135 allowed_tools=["Read", "Grep", "Glob"],

135 ),136 ),

136 ):137 ):

137 if isinstance(message, ResultMessage) and message.subtype == "success":138 if isinstance(message, ResultMessage) and message.subtype == "success":

147 prompt: "Review this PR using our code review checklist",148 prompt: "Review this PR using our code review checklist",

148 options: {149 options: {

149 settingSources: ["user", "project"],150 settingSources: ["user", "project"],

150 allowedTools: ["Skill", "Read", "Grep", "Glob"]151 skills: "all",

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

151 }153 }

152 })) {154 })) {

153 if (message.type === "result" && message.subtype === "success") {155 if (message.type === "result" && message.subtype === "success") {

258Agent SDK는 에이전트의 동작을 확장하는 여러 방법에 접근할 수 있게 합니다. 어느 것을 사용할지 확실하지 않으면 이 표는 일반적인 목표를 올바른 접근 방식에 매핑합니다.260Agent SDK는 에이전트의 동작을 확장하는 여러 방법에 접근할 수 있게 합니다. 어느 것을 사용할지 확실하지 않으면 이 표는 일반적인 목표를 올바른 접근 방식에 매핑합니다.

259 261

260| 원하는 것 | 사용 | SDK 표면 |262| 원하는 것 | 사용 | SDK 표면 |

261| :------------------------------------------------ | :----------------------------------- | :------------------------------------------------------------------------------ |263| :------------------------------------------------ | :-------------------------------------------- | :------------------------------------------------------------------------------ |

269 271

270<Tip>272<Tip>

271 **하위 에이전트 대 에이전트 팀:** 하위 에이전트는 임시적이고 격리됩니다: 새로운 대화, 한 가지 작업, 부모에게 반환된 요약. 에이전트 팀은 공유 작업 목록을 공유하고 직접 메시지를 주고받는 여러 독립적인 Claude Code 인스턴스를 조정합니다. 에이전트 팀은 CLI 기능입니다. [하위 에이전트가 상속하는 것](/ko/agent-sdk/subagents#what-subagents-inherit) 및 [에이전트 팀 비교](/ko/agent-teams#compare-with-subagents)를 참조하세요.273 **Subagents 대 agent teams:** Subagents는 임시적이고 격리됩니다: 새로운 대화, 한 가지 작업, 부모에게 반환된 요약. Agent teams는 공유 작업 목록을 공유하고 직접 메시지를 주고받는 여러 독립적인 Claude Code 인스턴스를 조정합니다. Agent teams는 CLI 기능입니다. [What subagents inherit](/ko/agent-sdk/subagents#what-subagents-inherit) 및 [agent teams 비교](/ko/agent-teams#compare-with-subagents)를 참조하세요.

272</Tip>274</Tip>

273 275

274활성화하는 모든 기능은 에이전트의 컨텍스트 윈도우에 추가됩니다. 기능별 비용 및 이 기능들이 함께 계층화되는 방식은 [Claude Code 확장](/ko/features-overview#understand-context-costs)을 참조하세요.276활성화하는 모든 기능은 에이전트의 컨텍스트 윈도우에 추가됩니다. 기능별 비용 및 이 기능들이 함께 계층화되는 방식은 [Extend Claude Code](/ko/features-overview#understand-context-costs)를 참조하세요.

275 277

276## 관련 리소스278## 관련 리소스

277 279

agent-sdk/mcp.md +772 −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# 외부 도구와 MCP로 연결하기

7> MCP 서버를 구성하여 에이전트를 외부 도구로 확장합니다. 전송 유형, 대규모 도구 세트를 위한 도구 검색, 인증 및 오류 처리를 다룹니다.

9[Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro)는 AI 에이전트를 외부 도구 및 데이터 소스에 연결하기 위한 개방형 표준입니다. MCP를 사용하면 에이전트가 데이터베이스를 쿼리하고, Slack 및 GitHub와 같은 API와 통합하며, 사용자 정의 도구 구현을 작성하지 않고도 다른 서비스에 연결할 수 있습니다.

11MCP 서버는 로컬 프로세스로 실행되거나, HTTP를 통해 연결되거나, SDK 애플리케이션 내에서 직접 실행될 수 있습니다.

13<Note>

14 이 페이지는 Agent SDK에 대한 MCP 구성을 다룹니다. Claude Code CLI에 MCP 서버를 추가하여 모든 프로젝트에서 로드되도록 하려면 [MCP 설치 범위](/ko/mcp#mcp-installation-scopes)를 참조하세요.

15</Note>

17## 빠른 시작

19이 예제는 [HTTP 전송](#httpsse-servers)을 사용하여 [Claude Code 문서](https://code.claude.com/docs) MCP 서버에 연결하고 [`allowedTools`](#allow-mcp-tools)를 와일드카드와 함께 사용하여 서버의 모든 도구를 허용합니다.

21<CodeGroup>

22 ```typescript TypeScript theme={null}

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

25 for await (const message of query({

26 prompt: "Use the docs MCP server to explain what hooks are in Claude Code",

27 options: {

28 mcpServers: {

29 "claude-code-docs": {

30 type: "http",

31 url: "https://code.claude.com/docs/mcp"

32 }

33 },

34 allowedTools: ["mcp__claude-code-docs__*"]

35 }

36 })) {

37 if (message.type === "result" && message.subtype === "success") {

38 console.log(message.result);

39 }

40 }

41 ```

43 ```python Python theme={null}

44 import asyncio

45 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

48 async def main():

49 options = ClaudeAgentOptions(

50 mcp_servers={

51 "claude-code-docs": {

52 "type": "http",

53 "url": "https://code.claude.com/docs/mcp",

54 }

55 },

56 allowed_tools=["mcp__claude-code-docs__*"],

57 )

59 async for message in query(

60 prompt="Use the docs MCP server to explain what hooks are in Claude Code",

61 options=options,

62 ):

63 if isinstance(message, ResultMessage) and message.subtype == "success":

64 print(message.result)

67 asyncio.run(main())

68 ```

69</CodeGroup>

71에이전트는 문서 서버에 연결하고, hooks에 대한 정보를 검색하며, 결과를 반환합니다.

73## MCP 서버 추가

75`query()`를 호출할 때 코드에서 MCP 서버를 구성하거나 [`settingSources`](#from-a-config-file)를 통해 로드되는 `.mcp.json` 파일에서 구성할 수 있습니다.

77### 코드에서

79`mcpServers` 옵션에서 MCP 서버를 직접 전달합니다:

81<CodeGroup>

82 ```typescript TypeScript theme={null}

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

85 for await (const message of query({

86 prompt: "List files in my project",

87 options: {

88 mcpServers: {

89 filesystem: {

90 command: "npx",

91 args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]

92 }

93 },

94 allowedTools: ["mcp__filesystem__*"]

95 }

96 })) {

97 if (message.type === "result" && message.subtype === "success") {

98 console.log(message.result);

99 }

100 }

101 ```

102

103 ```python Python theme={null}

104 import asyncio

105 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

106

107

108 async def main():

109 options = ClaudeAgentOptions(

110 mcp_servers={

111 "filesystem": {

112 "command": "npx",

113 "args": [

114 "-y",

115 "@modelcontextprotocol/server-filesystem",

116 "/Users/me/projects",

117 ],

118 }

119 },

120 allowed_tools=["mcp__filesystem__*"],

121 )

122

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

124 if isinstance(message, ResultMessage) and message.subtype == "success":

125 print(message.result)

126

127

128 asyncio.run(main())

129 ```

130</CodeGroup>

131

132### 구성 파일에서

133

134프로젝트 루트에 `.mcp.json` 파일을 만듭니다. `project` 설정 소스가 활성화되면 파일이 선택되며, 기본 `query()` 옵션에서는 활성화됩니다. `settingSources`를 명시적으로 설정하는 경우 이 파일이 로드되도록 `"project"`를 포함합니다:

135

136```json theme={null}

137{

138 "mcpServers": {

139 "filesystem": {

140 "command": "npx",

141 "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]

142 }

143 }

144}

145```

146

147## MCP 도구 허용

148

149MCP 도구는 Claude가 사용하기 전에 명시적 권한이 필요합니다. 권한이 없으면 Claude는 도구를 사용할 수 있음을 알 수 있지만 호출할 수 없습니다.

150

151### 도구 명명 규칙

152

153MCP 도구는 `mcp__<server-name>__<tool-name>` 명명 패턴을 따릅니다. 예를 들어, `"github"`라는 이름의 GitHub 서버와 `list_issues` 도구는 `mcp__github__list_issues`가 됩니다.

154

155### allowedTools로 액세스 권한 부여

156

157`allowedTools`를 사용하여 Claude가 사용할 수 있는 MCP 도구를 지정합니다:

158

159```typescript hidelines={1,-1} theme={null}

160const _ = {

161 options: {

162 mcpServers: {

163 // your servers

164 },

165 allowedTools: [

166 "mcp__github__*", // All tools from the github server

167 "mcp__db__query", // Only the query tool from db server

168 "mcp__slack__send_message" // Only send_message from slack server

169 ]

170 }

171};

172```

173

174와일드카드(`*`)를 사용하면 각 도구를 개별적으로 나열하지 않고도 서버의 모든 도구를 허용할 수 있습니다.

175

176<Note>

177 **MCP 액세스를 위해 권한 모드보다 `allowedTools`를 선호합니다.** `permissionMode: "acceptEdits"`는 MCP 도구를 자동으로 승인하지 않습니다(파일 편집 및 파일 시스템 Bash 명령만). `permissionMode: "bypassPermissions"`는 MCP 도구를 자동으로 승인하지만 다른 모든 안전 프롬프트도 비활성화하므로 필요한 것보다 더 광범위합니다. `allowedTools`의 와일드카드는 원하는 MCP 서버만 정확히 부여하고 다른 것은 부여하지 않습니다. 전체 비교는 [권한 모드](/ko/agent-sdk/permissions#permission-modes)를 참조하세요.

178</Note>

179

180### 사용 가능한 도구 검색

181

182MCP 서버가 제공하는 도구를 확인하려면 서버의 문서를 확인하거나 서버에 연결하고 `system` init 메시지를 검사합니다:

183

184```typescript theme={null}

185for await (const message of query({ prompt: "...", options })) {

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

187 console.log("Available MCP tools:", message.mcp_servers);

188 }

189}

190```

191

192## 전송 유형

193

194MCP 서버는 다양한 전송 프로토콜을 사용하여 에이전트와 통신합니다. 서버의 문서를 확인하여 지원하는 전송을 확인합니다:

195

196* 문서에 **실행할 명령**이 있으면(예: `npx @modelcontextprotocol/server-github`), stdio를 사용합니다

197* 문서에 **URL**이 있으면 HTTP 또는 SSE를 사용합니다

198* 코드에서 자신의 도구를 구축하는 경우 SDK MCP 서버를 사용합니다

199

200### stdio 서버

201

202stdin/stdout을 통해 통신하는 로컬 프로세스입니다. 같은 머신에서 실행하는 MCP 서버에 이를 사용합니다:

203

204<Tabs>

205 <Tab title="코드에서">

206 <CodeGroup>

207 ```typescript TypeScript hidelines={1,-1} theme={null}

208 const _ = {

209 options: {

210 mcpServers: {

211 github: {

212 command: "npx",

213 args: ["-y", "@modelcontextprotocol/server-github"],

214 env: {

215 GITHUB_TOKEN: process.env.GITHUB_TOKEN

216 }

217 }

218 },

219 allowedTools: ["mcp__github__list_issues", "mcp__github__search_issues"]

220 }

221 };

222 ```

223

224 ```python Python theme={null}

225 options = ClaudeAgentOptions(

226 mcp_servers={

227 "github": {

228 "command": "npx",

229 "args": ["-y", "@modelcontextprotocol/server-github"],

230 "env": {"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]},

231 }

232 },

233 allowed_tools=["mcp__github__list_issues", "mcp__github__search_issues"],

234 )

235 ```

236 </CodeGroup>

237 </Tab>

238

239 <Tab title=".mcp.json">

240 ```json theme={null}

241 {

242 "mcpServers": {

243 "github": {

244 "command": "npx",

245 "args": ["-y", "@modelcontextprotocol/server-github"],

246 "env": {

247 "GITHUB_TOKEN": "${GITHUB_TOKEN}"

248 }

249 }

250 }

251 }

252 ```

253 </Tab>

254</Tabs>

255

256### HTTP/SSE 서버

257

258클라우드 호스팅 MCP 서버 및 원격 API에 HTTP 또는 SSE를 사용합니다:

259

260<Tabs>

261 <Tab title="코드에서">

262 <CodeGroup>

263 ```typescript TypeScript hidelines={1,-1} theme={null}

264 const _ = {

265 options: {

266 mcpServers: {

267 "remote-api": {

268 type: "sse",

269 url: "https://api.example.com/mcp/sse",

270 headers: {

271 Authorization: `Bearer ${process.env.API_TOKEN}`

272 }

273 }

274 },

275 allowedTools: ["mcp__remote-api__*"]

276 }

277 };

278 ```

279

280 ```python Python theme={null}

281 options = ClaudeAgentOptions(

282 mcp_servers={

283 "remote-api": {

284 "type": "sse",

285 "url": "https://api.example.com/mcp/sse",

286 "headers": {"Authorization": f"Bearer {os.environ['API_TOKEN']}"},

287 }

288 },

289 allowed_tools=["mcp__remote-api__*"],

290 )

291 ```

292 </CodeGroup>

293 </Tab>

294

295 <Tab title=".mcp.json">

296 ```json theme={null}

297 {

298 "mcpServers": {

299 "remote-api": {

300 "type": "sse",

301 "url": "https://api.example.com/mcp/sse",

302 "headers": {

303 "Authorization": "Bearer ${API_TOKEN}"

304 }

305 }

306 }

307 }

308 ```

309 </Tab>

310</Tabs>

311

312HTTP(비스트리밍)의 경우 `"type": "http"` 대신 사용합니다.

313

314### SDK MCP 서버

315

316별도의 서버 프로세스를 실행하는 대신 애플리케이션 코드에서 직접 사용자 정의 도구를 정의합니다. 구현 세부 사항은 [사용자 정의 도구 가이드](/ko/agent-sdk/custom-tools)를 참조하세요.

317

318## MCP 도구 검색

319

320많은 MCP 도구를 구성한 경우 도구 정의가 컨텍스트 윈도우의 상당 부분을 소비할 수 있습니다. 도구 검색은 컨텍스트에서 도구 정의를 보류하고 각 턴에 Claude가 필요로 하는 도구만 로드하여 이를 해결합니다.

321

322도구 검색은 기본적으로 활성화됩니다. 구성 옵션 및 세부 사항은 [도구 검색](/ko/agent-sdk/tool-search)을 참조하세요.

323

324사용자 정의 SDK 도구와 함께 도구 검색을 사용하는 방법을 포함한 자세한 내용은 [도구 검색 가이드](/ko/agent-sdk/tool-search)를 참조하세요.

325

326## 인증

327

328대부분의 MCP 서버는 외부 서비스에 액세스하기 위해 인증이 필요합니다. 서버 구성에서 환경 변수를 통해 자격 증명을 전달합니다.

329

330### 환경 변수를 통해 자격 증명 전달

331

332`env` 필드를 사용하여 API 키, 토큰 및 기타 자격 증명을 MCP 서버에 전달합니다:

333

334<Tabs>

335 <Tab title="코드에서">

336 <CodeGroup>

337 ```typescript TypeScript hidelines={1,-1} theme={null}

338 const _ = {

339 options: {

340 mcpServers: {

341 github: {

342 command: "npx",

343 args: ["-y", "@modelcontextprotocol/server-github"],

344 env: {

345 GITHUB_TOKEN: process.env.GITHUB_TOKEN

346 }

347 }

348 },

349 allowedTools: ["mcp__github__list_issues"]

350 }

351 };

352 ```

353

354 ```python Python theme={null}

355 options = ClaudeAgentOptions(

356 mcp_servers={

357 "github": {

358 "command": "npx",

359 "args": ["-y", "@modelcontextprotocol/server-github"],

360 "env": {"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]},

361 }

362 },

363 allowed_tools=["mcp__github__list_issues"],

364 )

365 ```

366 </CodeGroup>

367 </Tab>

368

369 <Tab title=".mcp.json">

370 ```json theme={null}

371 {

372 "mcpServers": {

373 "github": {

374 "command": "npx",

375 "args": ["-y", "@modelcontextprotocol/server-github"],

376 "env": {

377 "GITHUB_TOKEN": "${GITHUB_TOKEN}"

378 }

379 }

380 }

381 }

382 ```

383

384 `${GITHUB_TOKEN}` 구문은 런타임에 환경 변수를 확장합니다.

385 </Tab>

386</Tabs>

387

388디버그 로깅이 포함된 완전한 작동 예제는 [저장소에서 문제 나열](#list-issues-from-a-repository)을 참조하세요.

389

390### 원격 서버용 HTTP 헤더

391

392HTTP 및 SSE 서버의 경우 서버 구성에서 직접 인증 헤더를 전달합니다:

393

394<Tabs>

395 <Tab title="코드에서">

396 <CodeGroup>

397 ```typescript TypeScript hidelines={1,-1} theme={null}

398 const _ = {

399 options: {

400 mcpServers: {

401 "secure-api": {

402 type: "http",

403 url: "https://api.example.com/mcp",

404 headers: {

405 Authorization: `Bearer ${process.env.API_TOKEN}`

406 }

407 }

408 },

409 allowedTools: ["mcp__secure-api__*"]

410 }

411 };

412 ```

413

414 ```python Python theme={null}

415 options = ClaudeAgentOptions(

416 mcp_servers={

417 "secure-api": {

418 "type": "http",

419 "url": "https://api.example.com/mcp",

420 "headers": {"Authorization": f"Bearer {os.environ['API_TOKEN']}"},

421 }

422 },

423 allowed_tools=["mcp__secure-api__*"],

424 )

425 ```

426 </CodeGroup>

427 </Tab>

428

429 <Tab title=".mcp.json">

430 ```json theme={null}

431 {

432 "mcpServers": {

433 "secure-api": {

434 "type": "http",

435 "url": "https://api.example.com/mcp",

436 "headers": {

437 "Authorization": "Bearer ${API_TOKEN}"

438 }

439 }

440 }

441 }

442 ```

443

444 `${API_TOKEN}` 구문은 런타임에 환경 변수를 확장합니다.

445 </Tab>

446</Tabs>

447

448### OAuth2 인증

449

450[MCP 사양은 OAuth 2.1을 지원합니다](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). SDK는 OAuth 흐름을 자동으로 처리하지 않지만 애플리케이션에서 OAuth 흐름을 완료한 후 헤더를 통해 액세스 토큰을 전달할 수 있습니다:

451

452<CodeGroup>

453 ```typescript TypeScript theme={null}

454 // After completing OAuth flow in your app

455 const accessToken = await getAccessTokenFromOAuthFlow();

456

457 const options = {

458 mcpServers: {

459 "oauth-api": {

460 type: "http",

461 url: "https://api.example.com/mcp",

462 headers: {

463 Authorization: `Bearer ${accessToken}`

464 }

465 }

466 },

467 allowedTools: ["mcp__oauth-api__*"]

468 };

469 ```

470

471 ```python Python theme={null}

472 # After completing OAuth flow in your app

473 access_token = await get_access_token_from_oauth_flow()

474

475 options = ClaudeAgentOptions(

476 mcp_servers={

477 "oauth-api": {

478 "type": "http",

479 "url": "https://api.example.com/mcp",

480 "headers": {"Authorization": f"Bearer {access_token}"},

481 }

482 },

483 allowed_tools=["mcp__oauth-api__*"],

484 )

485 ```

486</CodeGroup>

487

488## 예제

489

490### 저장소에서 문제 나열

491

492이 예제는 [GitHub MCP 서버](https://github.com/modelcontextprotocol/servers/tree/main/src/github)에 연결하여 최근 문제를 나열합니다. 이 예제에는 MCP 연결 및 도구 호출을 확인하기 위한 디버그 로깅이 포함됩니다.

493

494실행하기 전에 `repo` 범위로 [GitHub 개인 액세스 토큰](https://github.com/settings/tokens)을 만들고 환경 변수로 설정합니다:

495

496```bash theme={null}

497export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

498```

499

500<CodeGroup>

501 ```typescript TypeScript theme={null}

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

503

504 for await (const message of query({

505 prompt: "List the 3 most recent issues in anthropics/claude-code",

506 options: {

507 mcpServers: {

508 github: {

509 command: "npx",

510 args: ["-y", "@modelcontextprotocol/server-github"],

511 env: {

512 GITHUB_TOKEN: process.env.GITHUB_TOKEN

513 }

514 }

515 },

516 allowedTools: ["mcp__github__list_issues"]

517 }

518 })) {

519 // Verify MCP server connected successfully

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

521 console.log("MCP servers:", message.mcp_servers);

522 }

523

524 // Log when Claude calls an MCP tool

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

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

527 if (block.type === "tool_use" && block.name.startsWith("mcp__")) {

528 console.log("MCP tool called:", block.name);

529 }

530 }

531 }

532

533 // Print the final result

534 if (message.type === "result" && message.subtype === "success") {

535 console.log(message.result);

536 }

537 }

538 ```

539

540 ```python Python theme={null}

541 import asyncio

542 import os

543 from claude_agent_sdk import (

544 query,

545 ClaudeAgentOptions,

546 ResultMessage,

547 SystemMessage,

548 AssistantMessage,

549 )

550

551

552 async def main():

553 options = ClaudeAgentOptions(

554 mcp_servers={

555 "github": {

556 "command": "npx",

557 "args": ["-y", "@modelcontextprotocol/server-github"],

558 "env": {"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]},

559 }

560 },

561 allowed_tools=["mcp__github__list_issues"],

562 )

563

564 async for message in query(

565 prompt="List the 3 most recent issues in anthropics/claude-code",

566 options=options,

567 ):

568 # Verify MCP server connected successfully

569 if isinstance(message, SystemMessage) and message.subtype == "init":

570 print("MCP servers:", message.data.get("mcp_servers"))

571

572 # Log when Claude calls an MCP tool

573 if isinstance(message, AssistantMessage):

574 for block in message.content:

575 if hasattr(block, "name") and block.name.startswith("mcp__"):

576 print("MCP tool called:", block.name)

577

578 # Print the final result

579 if isinstance(message, ResultMessage) and message.subtype == "success":

580 print(message.result)

581

582

583 asyncio.run(main())

584 ```

585</CodeGroup>

586

587### 데이터베이스 쿼리

588

589이 예제는 [Postgres MCP 서버](https://github.com/modelcontextprotocol/servers/tree/main/src/postgres)를 사용하여 데이터베이스를 쿼리합니다. 연결 문자열은 서버에 대한 인수로 전달됩니다. 에이전트는 자동으로 데이터베이스 스키마를 검색하고, SQL 쿼리를 작성하며, 결과를 반환합니다:

590

591<CodeGroup>

592 ```typescript TypeScript theme={null}

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

594

595 // Connection string from environment variable

596 const connectionString = process.env.DATABASE_URL;

597

598 for await (const message of query({

599 // Natural language query - Claude writes the SQL

600 prompt: "How many users signed up last week? Break it down by day.",

601 options: {

602 mcpServers: {

603 postgres: {

604 command: "npx",

605 // Pass connection string as argument to the server

606 args: ["-y", "@modelcontextprotocol/server-postgres", connectionString]

607 }

608 },

609 // Allow only read queries, not writes

610 allowedTools: ["mcp__postgres__query"]

611 }

612 })) {

613 if (message.type === "result" && message.subtype === "success") {

614 console.log(message.result);

615 }

616 }

617 ```

618

619 ```python Python theme={null}

620 import asyncio

621 import os

622 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

623

624

625 async def main():

626 # Connection string from environment variable

627 connection_string = os.environ["DATABASE_URL"]

628

629 options = ClaudeAgentOptions(

630 mcp_servers={

631 "postgres": {

632 "command": "npx",

633 # Pass connection string as argument to the server

634 "args": [

635 "-y",

636 "@modelcontextprotocol/server-postgres",

637 connection_string,

638 ],

639 }

640 },

641 # Allow only read queries, not writes

642 allowed_tools=["mcp__postgres__query"],

643 )

644

645 # Natural language query - Claude writes the SQL

646 async for message in query(

647 prompt="How many users signed up last week? Break it down by day.",

648 options=options,

649 ):

650 if isinstance(message, ResultMessage) and message.subtype == "success":

651 print(message.result)

652

653

654 asyncio.run(main())

655 ```

656</CodeGroup>

657

658## 오류 처리

659

660MCP 서버는 여러 이유로 연결에 실패할 수 있습니다: 서버 프로세스가 설치되지 않았을 수 있고, 자격 증명이 유효하지 않을 수 있으며, 원격 서버에 도달할 수 없을 수 있습니다.

661

662SDK는 각 쿼리의 시작 부분에서 subtype `init`이 있는 `system` 메시지를 내보냅니다. 이 메시지에는 각 MCP 서버의 연결 상태가 포함됩니다. `status` 필드를 확인하여 에이전트가 작업을 시작하기 전에 연결 실패를 감지합니다:

663

664<CodeGroup>

665 ```typescript TypeScript theme={null}

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

667

668 for await (const message of query({

669 prompt: "Process data",

670 options: {

671 mcpServers: {

672 "data-processor": dataServer

673 }

674 }

675 })) {

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

677 const failedServers = message.mcp_servers.filter((s) => s.status !== "connected");

678

679 if (failedServers.length > 0) {

680 console.warn("Failed to connect:", failedServers);

681 }

682 }

683

684 if (message.type === "result" && message.subtype === "error_during_execution") {

685 console.error("Execution failed");

686 }

687 }

688 ```

689

690 ```python Python theme={null}

691 import asyncio

692 from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage

693

694

695 async def main():

696 options = ClaudeAgentOptions(mcp_servers={"data-processor": data_server})

697

698 async for message in query(prompt="Process data", options=options):

699 if isinstance(message, SystemMessage) and message.subtype == "init":

700 failed_servers = [

701 s

702 for s in message.data.get("mcp_servers", [])

703 if s.get("status") != "connected"

704 ]

705

706 if failed_servers:

707 print(f"Failed to connect: {failed_servers}")

708

709 if (

710 isinstance(message, ResultMessage)

711 and message.subtype == "error_during_execution"

712 ):

713 print("Execution failed")

714

715

716 asyncio.run(main())

717 ```

718</CodeGroup>

719

720## 문제 해결

721

722### 서버가 "failed" 상태를 표시합니다

723

724init 메시지를 확인하여 연결에 실패한 서버를 확인합니다:

725

726```typescript theme={null}

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

728 for (const server of message.mcp_servers) {

729 if (server.status === "failed") {

730 console.error(`Server ${server.name} failed to connect`);

731 }

732 }

733}

734```

735

736일반적인 원인:

737

738* **누락된 환경 변수**: 필수 토큰 및 자격 증명이 설정되어 있는지 확인합니다. stdio 서버의 경우 `env` 필드가 서버가 예상하는 것과 일치하는지 확인합니다.

739* **서버가 설치되지 않음**: `npx` 명령의 경우 패키지가 존재하고 Node.js가 PATH에 있는지 확인합니다.

740* **잘못된 연결 문자열**: 데이터베이스 서버의 경우 연결 문자열 형식을 확인하고 데이터베이스에 액세스할 수 있는지 확인합니다.

741* **네트워크 문제**: 원격 HTTP/SSE 서버의 경우 URL에 도달할 수 있고 방화벽이 연결을 허용하는지 확인합니다.

742

743### 도구가 호출되지 않음

744

745Claude가 도구를 보지만 사용하지 않는 경우 `allowedTools`로 권한을 부여했는지 확인합니다:

746

747```typescript hidelines={1,-1} theme={null}

748const _ = {

749 options: {

750 mcpServers: {

751 // your servers

752 },

753 allowedTools: ["mcp__servername__*"] // Required for Claude to use the tools

754 }

755};

756```

757

758### 연결 시간 초과

759

760MCP SDK는 서버 연결에 대해 기본 60초 시간 초과를 가집니다. 서버가 더 오래 시작되는 경우 연결이 실패합니다. 더 많은 시작 시간이 필요한 서버의 경우 다음을 고려합니다:

761

762* 사용 가능한 경우 더 가벼운 서버 사용

763* 에이전트를 시작하기 전에 서버 사전 준비

764* 느린 초기화 원인에 대한 서버 로그 확인

765

766## 관련 리소스

767

768* **[사용자 정의 도구 가이드](/ko/agent-sdk/custom-tools)**: SDK 애플리케이션과 함께 프로세스 내에서 실행되는 자신의 MCP 서버를 구축합니다

769* **[권한](/ko/agent-sdk/permissions)**: `allowedTools` 및 `disallowedTools`로 에이전트가 사용할 수 있는 MCP 도구를 제어합니다

770* **[TypeScript SDK 참조](/ko/agent-sdk/typescript)**: MCP 구성 옵션을 포함한 전체 API 참조

771* **[Python SDK 참조](/ko/agent-sdk/python)**: MCP 구성 옵션을 포함한 전체 API 참조

772* **[MCP 서버 디렉토리](https://github.com/modelcontextprotocol/servers)**: 데이터베이스, API 등을 위한 사용 가능한 MCP 서버를 찾아봅니다

agent-sdk/python.md +1 −0

Details

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

agent-sdk/sessions.md +324 −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> 세션이 에이전트 대화 기록을 어떻게 유지하는지, 그리고 이전 실행으로 돌아가기 위해 continue, resume, fork를 언제 사용할지에 대해 알아봅니다.

9세션은 에이전트가 작업하는 동안 SDK가 누적하는 대화 기록입니다. 여기에는 프롬프트, 에이전트가 수행한 모든 도구 호출, 모든 도구 결과, 그리고 모든 응답이 포함됩니다. SDK는 이를 자동으로 디스크에 기록하므로 나중에 돌아올 수 있습니다.

11세션으로 돌아간다는 것은 에이전트가 이전의 전체 컨텍스트를 가지고 있다는 의미입니다. 이미 읽은 파일, 이미 수행한 분석, 이미 내린 결정들이 모두 있습니다. 후속 질문을 할 수 있고, 중단에서 복구할 수 있으며, 다른 접근 방식을 시도하기 위해 분기할 수 있습니다.

13<Note>

14 세션은 **대화**를 유지하며, 파일 시스템은 유지하지 않습니다. 에이전트가 수행한 파일 변경 사항을 스냅샷하고 되돌리려면 [파일 체크포인팅](/ko/agent-sdk/file-checkpointing)을 사용하세요.

15</Note>

17이 가이드에서는 앱에 맞는 올바른 접근 방식을 선택하는 방법, 세션을 자동으로 추적하는 SDK 인터페이스, 세션 ID를 캡처하고 `resume` 및 `fork`를 수동으로 사용하는 방법, 그리고 호스트 간에 세션을 재개할 때 알아야 할 사항을 다룹니다.

19## 접근 방식 선택하기

21필요한 세션 처리의 양은 애플리케이션의 형태에 따라 다릅니다. 세션 관리는 컨텍스트를 공유해야 하는 여러 프롬프트를 보낼 때 중요합니다. 단일 `query()` 호출 내에서 에이전트는 이미 필요한 만큼 많은 턴을 수행하며, 권한 프롬프트와 `AskUserQuestion`은 [루프 내에서 처리됩니다](/ko/agent-sdk/user-input) (호출을 종료하지 않습니다).

23| 구축 중인 것 | 사용할 것 |

24| :----------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- |

25| 일회성 작업: 단일 프롬프트, 후속 없음 | 추가 작업 없음. 단일 `query()` 호출로 처리됩니다. |

26| 한 프로세스 내에서 다중 턴 채팅 | [`ClaudeSDKClient` (Python) 또는 `continue: true` (TypeScript)](#automatic-session-management). SDK가 ID 처리 없이 세션을 추적합니다. |

27| 프로세스 재시작 후 중단한 지점에서 계속하기 | `continue_conversation=True` (Python) / `continue: true` (TypeScript). 디렉토리의 가장 최근 세션을 재개하며, ID가 필요하지 않습니다. |

28| 특정 과거 세션 재개하기 (가장 최근이 아닌) | 세션 ID를 캡처하고 `resume`에 전달합니다. |

29| 원본을 잃지 않고 대체 접근 방식 시도하기 | 세션을 포크합니다. |

30| 상태 비저장 작업, 디스크에 아무것도 기록하고 싶지 않음 (TypeScript만 해당) | [`persistSession: false`](/ko/agent-sdk/typescript#options)를 설정합니다. 세션은 호출 기간 동안만 메모리에 존재합니다. Python은 항상 디스크에 유지합니다. |

32### Continue, resume, fork

34Continue, resume, fork는 `query()`에 설정하는 옵션 필드입니다 (Python의 [`ClaudeAgentOptions`](/ko/agent-sdk/python#claudeagentoptions), TypeScript의 [`Options`](/ko/agent-sdk/typescript#options)).

36**Continue**와 **resume**은 모두 기존 세션을 선택하고 여기에 추가합니다. 차이점은 해당 세션을 찾는 방식입니다:

38* **Continue**는 현재 디렉토리의 가장 최근 세션을 찾습니다. 아무것도 추적할 필요가 없습니다. 앱이 한 번에 하나의 대화를 실행할 때 잘 작동합니다.

39* **Resume**은 특정 세션 ID를 사용합니다. ID를 추적합니다. 여러 세션이 있을 때 (예: 다중 사용자 앱의 사용자당 하나) 또는 가장 최근이 아닌 세션으로 돌아가고 싶을 때 필요합니다.

41**Fork**는 다릅니다: 원본의 기록 복사본으로 시작하는 새 세션을 만듭니다. 원본은 변경되지 않습니다. 다른 방향을 시도하면서 돌아갈 수 있는 옵션을 유지하려면 fork를 사용합니다.

43## 자동 세션 관리

45두 SDK 모두 호출 간에 세션 상태를 추적하는 인터페이스를 제공하므로 ID를 수동으로 전달할 필요가 없습니다. 단일 프로세스 내에서 다중 턴 대화에 이를 사용합니다.

47### Python: `ClaudeSDKClient`

49[`ClaudeSDKClient`](/ko/agent-sdk/python#claudesdkclient)는 세션 ID를 내부적으로 처리합니다. `client.query()`에 대한 각 호출은 자동으로 동일한 세션을 계속합니다. [`client.receive_response()`](/ko/agent-sdk/python#claudesdkclient)를 호출하여 현재 쿼리의 메시지를 반복합니다. 클라이언트는 비동기 컨텍스트 관리자로 사용해야 합니다.

51이 예제는 동일한 `client`에 대해 두 개의 쿼리를 실행합니다. 첫 번째는 에이전트에게 모듈을 분석하도록 요청하고, 두 번째는 해당 모듈을 리팩토링하도록 요청합니다. 두 호출 모두 동일한 클라이언트 인스턴스를 통과하므로 두 번째 쿼리는 명시적인 `resume` 또는 세션 ID 없이 첫 번째의 전체 컨텍스트를 가집니다:

53```python Python theme={null}

54import asyncio

55from claude_agent_sdk import (

56 ClaudeSDKClient,

57 ClaudeAgentOptions,

58 AssistantMessage,

59 ResultMessage,

60 TextBlock,

61)

64def print_response(message):

65 """Print only the human-readable parts of a message."""

66 if isinstance(message, AssistantMessage):

67 for block in message.content:

68 if isinstance(block, TextBlock):

69 print(block.text)

70 elif isinstance(message, ResultMessage):

71 cost = (

72 f"${message.total_cost_usd:.4f}"

73 if message.total_cost_usd is not None

74 else "N/A"

75 )

76 print(f"[done: {message.subtype}, cost: {cost}]")

79async def main():

80 options = ClaudeAgentOptions(

81 allowed_tools=["Read", "Edit", "Glob", "Grep"],

82 )

84 async with ClaudeSDKClient(options=options) as client:

85 # First query: client captures the session ID internally

86 await client.query("Analyze the auth module")

87 async for message in client.receive_response():

88 print_response(message)

90 # Second query: automatically continues the same session

91 await client.query("Now refactor it to use JWT")

92 async for message in client.receive_response():

93 print_response(message)

96asyncio.run(main())

97```

99Python SDK 참조에서 [`ClaudeSDKClient`와 독립형 `query()` 함수를 언제 사용할지](/ko/agent-sdk/python#choosing-between-query-and-claudesdkclient)에 대한 세부 정보를 확인하세요.

100

101### TypeScript: `continue: true`

102

103안정적인 TypeScript SDK (이 문서 전체에서 사용되는 `query()` 함수, 때때로 V1이라고 불림)는 Python의 `ClaudeSDKClient`와 같은 세션 보유 클라이언트 객체가 없습니다. 대신 각 후속 `query()` 호출에서 `continue: true`를 전달하면 SDK가 현재 디렉토리의 가장 최근 세션을 찾아 재개합니다. ID 추적이 필요하지 않습니다.

104

105이 예제는 두 개의 별도 `query()` 호출을 수행합니다. 첫 번째는 새 세션을 만들고, 두 번째는 `continue: true`를 설정하여 SDK가 디스크의 가장 최근 세션을 찾아 재개하도록 지시합니다. 에이전트는 첫 번째 호출의 전체 컨텍스트를 가집니다:

106

107```typescript TypeScript theme={null}

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

109

110// First query: creates a new session

111for await (const message of query({

112 prompt: "Analyze the auth module",

113 options: { allowedTools: ["Read", "Glob", "Grep"] }

114})) {

115 if (message.type === "result" && message.subtype === "success") {

116 console.log(message.result);

117 }

118}

119

120// Second query: continue: true resumes the most recent session

121for await (const message of query({

122 prompt: "Now refactor it to use JWT",

123 options: {

124 continue: true,

125 allowedTools: ["Read", "Edit", "Write", "Glob", "Grep"]

126 }

127})) {

128 if (message.type === "result" && message.subtype === "success") {

129 console.log(message.result);

130 }

131}

132```

133

134<Note>

135 `createSession()`을 제공한 실험적 [V2 세션 API](/ko/agent-sdk/typescript-v2-preview)는 `send` / `stream` 패턴으로 더 이상 사용되지 않습니다. V1 `query()` 함수와 이 페이지에 설명된 세션 옵션을 사용하세요.

136</Note>

137

138## `query()`와 함께 세션 옵션 사용하기

139

140### 세션 ID 캡처하기

141

142Resume과 fork에는 세션 ID가 필요합니다. 결과 메시지의 `session_id` 필드에서 읽습니다 (Python의 [`ResultMessage`](/ko/agent-sdk/python#resultmessage), TypeScript의 [`SDKResultMessage`](/ko/agent-sdk/typescript#sdkresultmessage)). 이는 성공 또는 오류와 관계없이 모든 결과에 존재합니다. TypeScript에서 ID는 초기 `SystemMessage`의 직접 필드로도 더 일찍 사용 가능합니다. Python에서는 `SystemMessage.data` 내에 중첩되어 있습니다.

143

144<CodeGroup>

145 ```python Python theme={null}

146 import asyncio

147 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

148

149

150 async def main():

151 session_id = None

152

153 async for message in query(

154 prompt="Analyze the auth module and suggest improvements",

155 options=ClaudeAgentOptions(

156 allowed_tools=["Read", "Glob", "Grep"],

157 ),

158 ):

159 if isinstance(message, ResultMessage):

160 session_id = message.session_id

161 if message.subtype == "success":

162 print(message.result)

163

164 print(f"Session ID: {session_id}")

165 return session_id

166

167

168 session_id = asyncio.run(main())

169 ```

170

171 ```typescript TypeScript theme={null}

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

173

174 let sessionId: string | undefined;

175

176 for await (const message of query({

177 prompt: "Analyze the auth module and suggest improvements",

178 options: { allowedTools: ["Read", "Glob", "Grep"] }

179 })) {

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

181 sessionId = message.session_id;

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

183 console.log(message.result);

184 }

185 }

186 }

187

188 console.log(`Session ID: ${sessionId}`);

189 ```

190</CodeGroup>

191

192### ID로 재개하기

193

194세션 ID를 `resume`에 전달하여 특정 세션으로 돌아갑니다. 에이전트는 세션이 중단된 곳에서 전체 컨텍스트로 선택합니다. 재개하는 일반적인 이유:

195

196* **완료된 작업에 대해 후속 조치하기.** 에이전트가 이미 무언가를 분석했습니다. 이제 파일을 다시 읽지 않고 해당 분석에 따라 조치하기를 원합니다.

197* **제한에서 복구하기.** 첫 번째 실행이 `error_max_turns` 또는 `error_max_budget_usd`로 끝났습니다 ([결과 처리](/ko/agent-sdk/agent-loop#handle-the-result) 참조). 더 높은 제한으로 재개합니다.

198* **프로세스 재시작하기.** 종료 전에 ID를 캡처했으며 대화를 복원하고 싶습니다.

199

200이 예제는 [세션 ID 캡처하기](#capture-the-session-id)의 세션을 후속 프롬프트로 재개합니다. 재개하고 있으므로 에이전트는 이미 이전 분석을 컨텍스트에 가지고 있습니다:

201

202<CodeGroup>

203 ```python Python theme={null}

204 # Earlier session analyzed the code; now build on that analysis

205 async for message in query(

206 prompt="Now implement the refactoring you suggested",

207 options=ClaudeAgentOptions(

208 resume=session_id,

209 allowed_tools=["Read", "Edit", "Write", "Glob", "Grep"],

210 ),

211 ):

212 if isinstance(message, ResultMessage) and message.subtype == "success":

213 print(message.result)

214 ```

215

216 ```typescript TypeScript theme={null}

217 // Earlier session analyzed the code; now build on that analysis

218 for await (const message of query({

219 prompt: "Now implement the refactoring you suggested",

220 options: {

221 resume: sessionId,

222 allowedTools: ["Read", "Edit", "Write", "Glob", "Grep"]

223 }

224 })) {

225 if (message.type === "result" && message.subtype === "success") {

226 console.log(message.result);

227 }

228 }

229 ```

230</CodeGroup>

231

232<Tip>

233 `resume` 호출이 예상된 기록 대신 새 세션을 반환하면 가장 일반적인 원인은 일치하지 않는 `cwd`입니다. 세션은 `~/.claude/projects/<encoded-cwd>/*.jsonl` 아래에 저장되며, 여기서 `<encoded-cwd>`는 모든 영숫자가 아닌 문자가 `-`로 바뀐 절대 작업 디렉토리입니다 (따라서 `/Users/me/proj`는 `-Users-me-proj`가 됩니다). resume 호출이 다른 디렉토리에서 실행되면 SDK가 잘못된 위치를 찾습니다. 세션 파일도 현재 머신에 존재해야 합니다.

234</Tip>

235

236머신 간 또는 서버리스 환경에서 세션을 재개하려면 [`SessionStore` 어댑터](/ko/agent-sdk/session-storage)를 사용하여 트랜스크립트를 공유 스토리지로 미러링합니다.

237

238### 대체 방안을 탐색하기 위해 포크하기

239

240포킹은 원본의 기록 복사본으로 시작하지만 그 지점에서 분기하는 새 세션을 만듭니다. 포크는 자신의 세션 ID를 가집니다. 원본의 ID와 기록은 변경되지 않습니다. 두 개의 독립적인 세션을 별도로 재개할 수 있는 두 개의 세션 ID로 끝납니다.

241

242<Note>

243 포킹은 대화 기록을 분기하며, 파일 시스템은 분기하지 않습니다. 포크된 에이전트가 파일을 편집하면 해당 변경 사항은 실제이며 동일한 디렉토리에서 작업하는 모든 세션에 표시됩니다. 파일 변경 사항을 분기하고 되돌리려면 [파일 체크포인팅](/ko/agent-sdk/file-checkpointing)을 사용합니다.

244</Note>

245

246이 예제는 [세션 ID 캡처하기](#capture-the-session-id)를 기반으로 합니다: `session_id`에서 인증 모듈을 이미 분석했으며 JWT 중심 스레드를 잃지 않고 OAuth2를 탐색하고 싶습니다. 첫 번째 블록은 세션을 포크하고 포크의 ID (`forked_id`)를 캡처합니다. 두 번째 블록은 원본 `session_id`를 재개하여 JWT 경로를 계속합니다. 이제 두 개의 세션 ID가 두 개의 별도 기록을 가리킵니다:

247

248<CodeGroup>

249 ```python Python theme={null}

250 # Fork: branch from session_id into a new session

251 forked_id = None

252 async for message in query(

253 prompt="Instead of JWT, implement OAuth2 for the auth module",

254 options=ClaudeAgentOptions(

255 resume=session_id,

256 fork_session=True,

257 ),

258 ):

259 if isinstance(message, ResultMessage):

260 forked_id = message.session_id # The fork's ID, distinct from session_id

261 if message.subtype == "success":

262 print(message.result)

263

264 print(f"Forked session: {forked_id}")

265

266 # Original session is untouched; resuming it continues the JWT thread

267 async for message in query(

268 prompt="Continue with the JWT approach",

269 options=ClaudeAgentOptions(resume=session_id),

270 ):

271 if isinstance(message, ResultMessage) and message.subtype == "success":

272 print(message.result)

273 ```

274

275 ```typescript TypeScript theme={null}

276 // Fork: branch from sessionId into a new session

277 let forkedId: string | undefined;

278

279 for await (const message of query({

280 prompt: "Instead of JWT, implement OAuth2 for the auth module",

281 options: {

282 resume: sessionId,

283 forkSession: true

284 }

285 })) {

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

287 forkedId = message.session_id; // The fork's ID, distinct from sessionId

288 }

289 if (message.type === "result" && message.subtype === "success") {

290 console.log(message.result);

291 }

292 }

293

294 console.log(`Forked session: ${forkedId}`);

295

296 // Original session is untouched; resuming it continues the JWT thread

297 for await (const message of query({

298 prompt: "Continue with the JWT approach",

299 options: { resume: sessionId }

300 })) {

301 if (message.type === "result" && message.subtype === "success") {

302 console.log(message.result);

303 }

304 }

305 ```

306</CodeGroup>

307

308## 호스트 간에 재개하기

309

310세션 파일은 이를 만든 머신에 로컬입니다. 다른 호스트 (CI 워커, 임시 컨테이너, 서버리스)에서 세션을 재개하려면 두 가지 옵션이 있습니다:

311

312* **세션 파일 이동하기.** 첫 번째 실행에서 `~/.claude/projects/<encoded-cwd>/<session-id>.jsonl`을 유지하고 `resume`을 호출하기 전에 새 호스트의 동일한 경로로 복원합니다. `cwd`가 일치해야 합니다.

313* **세션 재개에 의존하지 않기.** 필요한 결과 (분석 출력, 결정, 파일 diff)를 애플리케이션 상태로 캡처하고 새 세션의 프롬프트에 전달합니다. 이는 종종 트랜스크립트 파일을 주변에 배송하는 것보다 더 견고합니다.

314

315두 SDK 모두 디스크의 세션을 열거하고 메시지를 읽기 위한 함수를 노출합니다: TypeScript의 [`listSessions()`](/ko/agent-sdk/typescript#listsessions) 및 [`getSessionMessages()`](/ko/agent-sdk/typescript#getsessionmessages), Python의 [`list_sessions()`](/ko/agent-sdk/python#list_sessions) 및 [`get_session_messages()`](/ko/agent-sdk/python#get_session_messages). 이를 사용하여 사용자 정의 세션 선택기, 정리 로직 또는 트랜스크립트 뷰어를 구축합니다.

316

317두 SDK 모두 개별 세션을 조회하고 변경하기 위한 함수도 노출합니다: Python의 [`get_session_info()`](/ko/agent-sdk/python#get_session_info), [`rename_session()`](/ko/agent-sdk/python#rename_session), [`tag_session()`](/ko/agent-sdk/python#tag_session), 그리고 TypeScript의 [`getSessionInfo()`](/ko/agent-sdk/typescript#getsessioninfo), [`renameSession()`](/ko/agent-sdk/typescript#renamesession), [`tagSession()`](/ko/agent-sdk/typescript#tagsession). 이를 사용하여 태그별로 세션을 구성하거나 인간이 읽을 수 있는 제목을 제공합니다.

318

319## 관련 리소스

320

321* [에이전트 루프 작동 방식](/ko/agent-sdk/agent-loop): 세션 내에서 턴, 메시지, 컨텍스트 누적을 이해합니다

322* [파일 체크포인팅](/ko/agent-sdk/file-checkpointing): 세션 간 파일 변경 사항 추적 및 되돌리기

323* [Python `ClaudeAgentOptions`](/ko/agent-sdk/python#claudeagentoptions): Python의 전체 세션 옵션 참조

324* [TypeScript `Options`](/ko/agent-sdk/typescript#options): TypeScript의 전체 세션 옵션 참조

agent-sdk/skills.md +315 −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# SDK의 Agent Skills

7> Claude Agent SDK를 사용하여 전문화된 기능으로 Claude를 확장하기

9## 개요

11Agent Skills는 Claude가 관련성이 있을 때 자율적으로 호출하는 전문화된 기능으로 Claude를 확장합니다. Skills는 지침, 설명 및 선택적 지원 리소스를 포함하는 `SKILL.md` 파일로 패키징됩니다.

13Skills의 이점, 아키텍처 및 작성 지침을 포함한 포괄적인 정보는 [Agent Skills 개요](https://platform.claude.com/docs/ko/agents-and-tools/agent-skills/overview)를 참조하십시오.

15## SDK와 Skills의 작동 방식

17Claude Agent SDK를 사용할 때 Skills는 다음과 같이 작동합니다:

191. **파일 시스템 아티팩트로 정의됨**: `.claude/skills/` 디렉토리의 `SKILL.md` 파일로 생성됨

202. **파일 시스템에서 로드됨**: Skills는 `settingSources`(TypeScript) 또는 `setting_sources`(Python)에 의해 관리되는 파일 시스템 위치에서 로드됨

213. **자동으로 발견됨**: 파일 시스템 설정이 로드되면 Skill 메타데이터가 시작 시 사용자 및 프로젝트 디렉토리에서 발견되고, 트리거될 때 전체 콘텐츠가 로드됨

224. **모델에 의해 호출됨**: Claude는 컨텍스트를 기반으로 사용할 시기를 자율적으로 선택함

235. **`skills` 옵션을 통해 필터링됨**: 발견된 Skills는 기본적으로 활성화됩니다. 세션에서 사용 가능한 Skills를 제어하려면 Skill 이름 목록, `"all"` 또는 `[]`를 전달하십시오.

25프로그래밍 방식으로 정의할 수 있는 subagents와 달리 Skills는 파일 시스템 아티팩트로 생성되어야 합니다. SDK는 Skills를 등록하기 위한 프로그래밍 API를 제공하지 않습니다.

27<Note>

28 Skills는 파일 시스템 설정 소스를 통해 발견됩니다. 기본 `query()` 옵션을 사용하면 SDK는 사용자 및 프로젝트 소스를 로드하므로 `~/.claude/skills/` 및 `<cwd>/.claude/skills/`의 Skills를 사용할 수 있습니다. `settingSources`를 명시적으로 설정하는 경우 Skill 발견을 유지하려면 `'user'` 또는 `'project'`를 포함하거나, [`plugins` 옵션](/ko/agent-sdk/plugins)을 사용하여 특정 경로에서 Skills를 로드하십시오.

29</Note>

31## SDK와 함께 Skills 사용하기

33`query()`의 `skills` 옵션을 설정하여 세션에서 사용 가능한 Skills를 제어합니다. 생략하면 발견된 Skills가 활성화되고 Skill 도구를 사용할 수 있으며, 이는 CLI 동작과 일치합니다. 모든 발견된 Skill을 활성화하려면 `"all"`을 전달하고, 특정 Skill만 활성화하려면 Skill 이름 목록을 전달하거나, 모두 비활성화하려면 `[]`를 전달하십시오. `skills`를 설정하면 SDK가 Skill 도구를 자동으로 활성화하므로 `allowedTools`에 나열할 필요가 없습니다.

35구성되면 Claude는 파일 시스템에서 Skills를 자동으로 발견하고 사용자의 요청과 관련이 있을 때 호출합니다.

37<CodeGroup>

38 ```python Python theme={null}

39 import asyncio

40 from claude_agent_sdk import query, ClaudeAgentOptions

43 async def main():

44 options = ClaudeAgentOptions(

45 cwd="/path/to/project", # Project with .claude/skills/

46 setting_sources=["user", "project"], # Load Skills from filesystem

47 skills="all", # Enable every discovered Skill

48 allowed_tools=["Read", "Write", "Bash"],

49 )

51 async for message in query(

52 prompt="Help me process this PDF document", options=options

53 ):

54 print(message)

57 asyncio.run(main())

58 ```

60 ```typescript TypeScript theme={null}

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

63 for await (const message of query({

64 prompt: "Help me process this PDF document",

65 options: {

66 cwd: "/path/to/project", // Project with .claude/skills/

67 settingSources: ["user", "project"], // Load Skills from filesystem

68 skills: "all", // Enable every discovered Skill

69 allowedTools: ["Read", "Write", "Bash"]

70 }

71 })) {

72 console.log(message);

73 }

74 ```

75</CodeGroup>

77특정 Skills만 활성화하려면 해당 이름을 전달합니다. 이름은 `SKILL.md`의 `name` 필드 또는 Skill의 디렉토리 이름과 일치합니다. 플러그인에서 제공하는 Skills의 경우 `plugin:skill`을 사용합니다.

79<CodeGroup>

80 ```python Python theme={null}

81 options = ClaudeAgentOptions(skills=["pdf", "docx"])

82 ```

84 ```typescript TypeScript theme={null}

85 const options = { skills: ["pdf", "docx"] };

86 ```

87</CodeGroup>

89`skills` 옵션은 컨텍스트 필터이지 샌드박스가 아닙니다. 나열되지 않은 Skills는 모델에서 숨겨지고 Skill 도구에 의해 거부되지만, 해당 파일은 디스크에 남아 있으며 Read 및 Bash를 통해 접근할 수 있습니다.

91## Skill 위치

93Skills는 `settingSources`/`setting_sources` 구성을 기반으로 파일 시스템 디렉토리에서 로드됩니다:

95* **프로젝트 Skills** (`.claude/skills/`): git을 통해 팀과 공유 - `setting_sources`에 `"project"`가 포함될 때 로드됨

96* **사용자 Skills** (`~/.claude/skills/`): 모든 프로젝트에 걸친 개인 Skills - `setting_sources`에 `"user"`가 포함될 때 로드됨

97* **플러그인 Skills**: 설치된 Claude Code 플러그인과 함께 번들됨

99## Skills 생성하기

100

101Skills는 YAML frontmatter 및 Markdown 콘텐츠가 포함된 `SKILL.md` 파일을 포함하는 디렉토리로 정의됩니다. `description` 필드는 Claude가 Skill을 호출하는 시기를 결정합니다.

102

103**예제 디렉토리 구조**:

104

105```bash theme={null}

106.claude/skills/processing-pdfs/

107└── SKILL.md

108```

109

110SKILL.md 구조, 다중 파일 Skills 및 예제를 포함한 Skills 생성에 대한 완전한 지침은 다음을 참조하십시오:

111

112* [Claude Code의 Agent Skills](/ko/skills): 생성, 예제 및 문제 해결을 포함한 완전한 가이드

113* [Agent Skills 모범 사례](https://platform.claude.com/docs/ko/agents-and-tools/agent-skills/best-practices): 작성 지침 및 명명 규칙

114* [Agent Skills 쿡북](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction): 예제 Skills 및 템플릿

115

116## 도구 제한

117

118<Note>

119 SKILL.md의 `allowed-tools` frontmatter 필드는 Claude Code CLI를 직접 사용할 때만 지원됩니다. **SDK를 통해 Skills를 사용할 때는 적용되지 않습니다**.

120

121 SDK를 사용할 때는 쿼리 구성의 주 `allowedTools` 옵션을 통해 도구 접근을 제어합니다.

122</Note>

123

124SDK 애플리케이션에서 Skills의 도구 접근을 제어하려면 `allowedTools`를 사용하여 특정 도구를 사전 승인합니다. `canUseTool` 콜백이 없으면 목록에 없는 모든 것이 거부됩니다:

125

126<Note>

127 첫 번째 예제의 import 문이 다음 코드 스니펫에서 가정됩니다.

128</Note>

129

130<CodeGroup>

131 ```python Python theme={null}

132 options = ClaudeAgentOptions(

133 setting_sources=["user", "project"], # Load Skills from filesystem

134 skills="all",

135 allowed_tools=["Read", "Grep", "Glob"],

136 )

137

138 async for message in query(prompt="Analyze the codebase structure", options=options):

139 print(message)

140 ```

141

142 ```typescript TypeScript theme={null}

143 for await (const message of query({

144 prompt: "Analyze the codebase structure",

145 options: {

146 settingSources: ["user", "project"], // Load Skills from filesystem

147 skills: "all",

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

149 permissionMode: "dontAsk" // Deny anything not in allowedTools

150 }

151 })) {

152 console.log(message);

153 }

154 ```

155</CodeGroup>

156

157## 사용 가능한 Skills 발견하기

158

159SDK 애플리케이션에서 사용 가능한 Skills를 확인하려면 Claude에게 간단히 물어보십시오:

160

161<CodeGroup>

162 ```python Python theme={null}

163 options = ClaudeAgentOptions(

164 setting_sources=["user", "project"], # Load Skills from filesystem

165 skills="all",

166 )

167

168 async for message in query(prompt="What Skills are available?", options=options):

169 print(message)

170 ```

171

172 ```typescript TypeScript theme={null}

173 for await (const message of query({

174 prompt: "What Skills are available?",

175 options: {

176 settingSources: ["user", "project"], // Load Skills from filesystem

177 skills: "all"

178 }

179 })) {

180 console.log(message);

181 }

182 ```

183</CodeGroup>

184

185Claude는 현재 작업 디렉토리 및 설치된 플러그인을 기반으로 사용 가능한 Skills를 나열합니다.

186

187## Skills 테스트하기

188

189설명과 일치하는 질문을 하여 Skills를 테스트합니다:

190

191<CodeGroup>

192 ```python Python theme={null}

193 options = ClaudeAgentOptions(

194 cwd="/path/to/project",

195 setting_sources=["user", "project"], # Load Skills from filesystem

196 skills="all",

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

198 )

199

200 async for message in query(prompt="Extract text from invoice.pdf", options=options):

201 print(message)

202 ```

203

204 ```typescript TypeScript theme={null}

205 for await (const message of query({

206 prompt: "Extract text from invoice.pdf",

207 options: {

208 cwd: "/path/to/project",

209 settingSources: ["user", "project"], // Load Skills from filesystem

210 skills: "all",

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

212 }

213 })) {

214 console.log(message);

215 }

216 ```

217</CodeGroup>

218

219Claude는 설명이 요청과 일치하면 관련 Skill을 자동으로 호출합니다.

220

221## 문제 해결

222

223### Skills를 찾을 수 없음

224

225**settingSources 구성 확인**: Skills는 `user` 및 `project` 설정 소스를 통해 발견됩니다. `settingSources`/`setting_sources`를 명시적으로 설정하고 해당 소스를 생략하면 Skills가 로드되지 않습니다:

226

227<CodeGroup>

228 ```python Python theme={null}

229 # Skills not loaded: setting_sources excludes user and project

230 options = ClaudeAgentOptions(setting_sources=[], skills="all")

231

232 # Skills loaded: user and project sources included

233 options = ClaudeAgentOptions(

234 setting_sources=["user", "project"],

235 skills="all",

236 )

237 ```

238

239 ```typescript TypeScript theme={null}

240 // Skills not loaded: settingSources excludes user and project

241 const options = {

242 settingSources: [],

243 skills: "all"

244 };

245

246 // Skills loaded: user and project sources included

247 const options = {

248 settingSources: ["user", "project"],

249 skills: "all"

250 };

251 ```

252</CodeGroup>

253

254`settingSources`/`setting_sources`에 대한 자세한 내용은 [TypeScript SDK 참조](/ko/agent-sdk/typescript#settingsource) 또는 [Python SDK 참조](/ko/agent-sdk/python#settingsource)를 참조하십시오.

255

256**작업 디렉토리 확인**: SDK는 `cwd` 옵션을 기준으로 Skills를 로드합니다. `.claude/skills/`를 포함하는 디렉토리를 가리키는지 확인하십시오:

257

258<CodeGroup>

259 ```python Python theme={null}

260 # Ensure your cwd points to the directory containing .claude/skills/

261 options = ClaudeAgentOptions(

262 cwd="/path/to/project", # Must contain .claude/skills/

263 setting_sources=["user", "project"], # Loads skills from these sources

264 skills="all",

265 )

266 ```

267

268 ```typescript TypeScript theme={null}

269 // Ensure your cwd points to the directory containing .claude/skills/

270 const options = {

271 cwd: "/path/to/project", // Must contain .claude/skills/

272 settingSources: ["user", "project"], // Loads skills from these sources

273 skills: "all"

274 };

275 ```

276</CodeGroup>

277

278위의 "SDK와 함께 Skills 사용하기" 섹션을 참조하여 완전한 패턴을 확인하십시오.

279

280**파일 시스템 위치 확인**:

281

282```bash theme={null}

283# Check project Skills

284ls .claude/skills/*/SKILL.md

285

286# Check personal Skills

287ls ~/.claude/skills/*/SKILL.md

288```

289

290### Skill이 사용되지 않음

291

292**`skills` 옵션 확인**: `skills` 목록을 전달한 경우 Skill의 이름이 포함되어 있는지 확인하십시오. `[]`를 전달하면 모든 Skills가 비활성화됩니다.

293

294**설명 확인**: 구체적이고 관련 키워드를 포함하는지 확인하십시오. 효과적인 설명 작성에 대한 지침은 [Agent Skills 모범 사례](https://platform.claude.com/docs/ko/agents-and-tools/agent-skills/best-practices#writing-effective-descriptions)를 참조하십시오.

295

296### 추가 문제 해결

297

298일반적인 Skills 문제 해결(YAML 구문, 디버깅 등)은 [Claude Code Skills 문제 해결 섹션](/ko/skills#troubleshooting)을 참조하십시오.

299

300## 관련 문서

301

302### Skills 가이드

303

304* [Claude Code의 Agent Skills](/ko/skills): 생성, 예제 및 문제 해결을 포함한 완전한 Skills 가이드

305* [Agent Skills 개요](https://platform.claude.com/docs/ko/agents-and-tools/agent-skills/overview): 개념적 개요, 이점 및 아키텍처

306* [Agent Skills 모범 사례](https://platform.claude.com/docs/ko/agents-and-tools/agent-skills/best-practices): 효과적인 Skills를 위한 작성 지침

307* [Agent Skills 쿡북](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction): 예제 Skills 및 템플릿

308

309### SDK 리소스

310

311* [SDK의 Subagents](/ko/agent-sdk/subagents): 프로그래밍 옵션이 있는 유사한 파일 시스템 기반 에이전트

312* [SDK의 Slash Commands](/ko/agent-sdk/slash-commands): 사용자 호출 명령

313* [SDK 개요](/ko/agent-sdk/overview): 일반 SDK 개념

314* [TypeScript SDK 참조](/ko/agent-sdk/typescript): 완전한 API 문서

315* [Python SDK 참조](/ko/agent-sdk/python): 완전한 API 문서

agent-sdk/subagents.md +601 −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# SDK의 서브에이전트

7> 서브에이전트를 정의하고 호출하여 컨텍스트를 격리하고, 작업을 병렬로 실행하며, Claude Agent SDK 애플리케이션에서 특화된 지침을 적용합니다.

9서브에이전트는 메인 에이전트가 집중된 부작업을 처리하기 위해 생성할 수 있는 별도의 에이전트 인스턴스입니다.

10서브에이전트를 사용하여 집중된 부작업의 컨텍스트를 격리하고, 여러 분석을 병렬로 실행하며, 메인 에이전트의 프롬프트를 비대하게 만들지 않으면서 특화된 지침을 적용합니다.

12이 가이드에서는 `agents` 매개변수를 사용하여 SDK에서 서브에이전트를 정의하고 사용하는 방법을 설명합니다.

14## 개요

16서브에이전트를 세 가지 방법으로 생성할 수 있습니다.

18* **프로그래밍 방식**: `query()` 옵션에서 `agents` 매개변수 사용 ([TypeScript](/ko/agent-sdk/typescript#agentdefinition), [Python](/ko/agent-sdk/python#agentdefinition))

19* **파일 시스템 기반**: `.claude/agents/` 디렉토리에 마크다운 파일로 에이전트 정의 ([서브에이전트를 파일로 정의](/ko/sub-agents) 참조)

20* **기본 제공 범용**: Claude는 언제든지 Agent 도구를 통해 기본 제공 `general-purpose` 서브에이전트를 호출할 수 있습니다.

22이 가이드는 SDK 애플리케이션에 권장되는 프로그래밍 방식에 중점을 둡니다.

24서브에이전트를 정의할 때, Claude는 각 서브에이전트의 `description` 필드를 기반으로 호출할지 여부를 결정합니다. 서브에이전트를 사용해야 할 때를 설명하는 명확한 설명을 작성하면, Claude가 자동으로 적절한 작업을 위임합니다. 프롬프트에서 서브에이전트를 이름으로 명시적으로 요청할 수도 있습니다(예: "code-reviewer 에이전트를 사용하여...").

26## 서브에이전트 사용의 이점

28### 컨텍스트 격리

30각 서브에이전트는 자체 새로운 대화에서 실행됩니다. 중간 도구 호출 및 결과는 서브에이전트 내부에 유지되며, 최종 메시지만 부모에게 반환됩니다. [서브에이전트가 상속하는 것](#what-subagents-inherit)을 참조하여 서브에이전트의 컨텍스트에 정확히 무엇이 있는지 확인하세요.

32**예시:** `research-assistant` 서브에이전트는 수십 개의 파일을 탐색할 수 있으며, 그 콘텐츠 중 어느 것도 메인 대화에 누적되지 않습니다. 부모는 서브에이전트가 읽은 모든 파일이 아닌 간결한 요약을 받습니다.

34### 병렬화

36여러 서브에이전트를 동시에 실행하여 복잡한 워크플로우의 속도를 대폭 향상시킬 수 있습니다.

38**예시:** 코드 리뷰 중에 `style-checker`, `security-scanner`, `test-coverage` 서브에이전트를 동시에 실행하여 리뷰 시간을 분 단위에서 초 단위로 단축할 수 있습니다.

40### 특화된 지침 및 지식

42각 서브에이전트는 특정 전문 지식, 모범 사례 및 제약 조건이 있는 맞춤형 시스템 프롬프트를 가질 수 있습니다.

44**예시:** `database-migration` 서브에이전트는 SQL 모범 사례, 롤백 전략 및 데이터 무결성 검사에 대한 상세한 지식을 가질 수 있으며, 이는 메인 에이전트의 지침에서는 불필요한 노이즈입니다.

46### 도구 제한

48서브에이전트는 특정 도구로 제한되어 의도하지 않은 작업의 위험을 줄입니다.

50**예시:** `doc-reviewer` 서브에이전트는 Read 및 Grep 도구에만 액세스할 수 있으므로, 문서 파일을 분석할 수 있지만 실수로 수정할 수 없습니다.

52## 서브에이전트 생성

54### 프로그래밍 방식 정의 (권장)

56`agents` 매개변수를 사용하여 코드에서 직접 서브에이전트를 정의합니다. 이 예시는 읽기 전용 액세스가 있는 코드 리뷰어와 명령을 실행할 수 있는 테스트 러너라는 두 개의 서브에이전트를 생성합니다. Claude가 Agent 도구를 통해 서브에이전트를 호출하므로 `allowedTools`에 `Agent` 도구를 포함해야 합니다.

58<CodeGroup>

59 ```python Python theme={null}

60 import asyncio

61 from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

64 async def main():

65 async for message in query(

66 prompt="Review the authentication module for security issues",

67 options=ClaudeAgentOptions(

68 # Agent tool is required for subagent invocation

69 allowed_tools=["Read", "Grep", "Glob", "Agent"],

70 agents={

71 "code-reviewer": AgentDefinition(

72 # description tells Claude when to use this subagent

73 description="Expert code review specialist. Use for quality, security, and maintainability reviews.",

74 # prompt defines the subagent's behavior and expertise

75 prompt="""You are a code review specialist with expertise in security, performance, and best practices.

77 When reviewing code:

78 - Identify security vulnerabilities

79 - Check for performance issues

80 - Verify adherence to coding standards

81 - Suggest specific improvements

83 Be thorough but concise in your feedback.""",

84 # tools restricts what the subagent can do (read-only here)

85 tools=["Read", "Grep", "Glob"],

86 # model overrides the default model for this subagent

87 model="sonnet",

88 ),

89 "test-runner": AgentDefinition(

90 description="Runs and analyzes test suites. Use for test execution and coverage analysis.",

91 prompt="""You are a test execution specialist. Run tests and provide clear analysis of results.

93 Focus on:

94 - Running test commands

95 - Analyzing test output

96 - Identifying failing tests

97 - Suggesting fixes for failures""",

98 # Bash access lets this subagent run test commands

99 tools=["Bash", "Read", "Grep"],

100 ),

101 },

102 ),

103 ):

104 if hasattr(message, "result"):

105 print(message.result)

106

107

108 asyncio.run(main())

109 ```

110

111 ```typescript TypeScript theme={null}

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

113

114 for await (const message of query({

115 prompt: "Review the authentication module for security issues",

116 options: {

117 // Agent tool is required for subagent invocation

118 allowedTools: ["Read", "Grep", "Glob", "Agent"],

119 agents: {

120 "code-reviewer": {

121 // description tells Claude when to use this subagent

122 description:

123 "Expert code review specialist. Use for quality, security, and maintainability reviews.",

124 // prompt defines the subagent's behavior and expertise

125 prompt: `You are a code review specialist with expertise in security, performance, and best practices.

126

127 When reviewing code:

128 - Identify security vulnerabilities

129 - Check for performance issues

130 - Verify adherence to coding standards

131 - Suggest specific improvements

132

133 Be thorough but concise in your feedback.`,

134 // tools restricts what the subagent can do (read-only here)

135 tools: ["Read", "Grep", "Glob"],

136 // model overrides the default model for this subagent

137 model: "sonnet"

138 },

139 "test-runner": {

140 description:

141 "Runs and analyzes test suites. Use for test execution and coverage analysis.",

142 prompt: `You are a test execution specialist. Run tests and provide clear analysis of results.

143

144 Focus on:

145 - Running test commands

146 - Analyzing test output

147 - Identifying failing tests

148 - Suggesting fixes for failures`,

149 // Bash access lets this subagent run test commands

150 tools: ["Bash", "Read", "Grep"]

151 }

152 }

153 }

154 })) {

155 if ("result" in message) console.log(message.result);

156 }

157 ```

158</CodeGroup>

159

160### AgentDefinition 구성

161

162| 필드 | 유형 | 필수 | 설명 |

163| :---------------- | :---------------------------------------------------------- | :-- | :--------------------------------------------------------------------------------------------------------------- |

176

177Python SDK에서 이러한 필드 이름은 와이어 형식과 일치하도록 camelCase를 사용합니다. 자세한 내용은 [`AgentDefinition` 참조](/ko/agent-sdk/python#agentdefinition)를 참조하세요.

178

179<Note>

180 서브에이전트는 자신의 서브에이전트를 생성할 수 없습니다. 서브에이전트의 `tools` 배열에 `Agent`를 포함하지 마세요.

181</Note>

182

183### 파일 시스템 기반 정의 (대안)

184

185`.claude/agents/` 디렉토리에 마크다운 파일로 서브에이전트를 정의할 수도 있습니다. 이 방식에 대한 자세한 내용은 [Claude Code 서브에이전트 문서](/ko/sub-agents)를 참조하세요. 프로그래밍 방식으로 정의된 에이전트는 같은 이름의 파일 시스템 기반 에이전트보다 우선합니다.

186

187<Note>

188 사용자 정의 서브에이전트를 정의하지 않더라도, `Agent`가 `allowedTools`에 있으면 Claude는 기본 제공 `general-purpose` 서브에이전트를 생성할 수 있습니다. 이는 특화된 에이전트를 만들지 않고도 연구 또는 탐색 작업을 위임하는 데 유용합니다.

189</Note>

190

191## 서브에이전트가 상속하는 것

192

193서브에이전트의 컨텍스트 윈도우는 새로 시작되지만(부모 대화 없음) 비어 있지 않습니다. 부모에서 서브에이전트로의 유일한 채널은 Agent 도구의 프롬프트 문자열이므로, 서브에이전트가 필요한 파일 경로, 오류 메시지 또는 결정을 해당 프롬프트에 직접 포함하세요.

194

195| 서브에이전트가 받는 것 | 서브에이전트가 받지 않는 것 |

196| :----------------------------------------------------- | :------------------------------------------------- |

197| 자신의 시스템 프롬프트(`AgentDefinition.prompt`)와 Agent 도구의 프롬프트 | 부모의 대화 기록 또는 도구 결과 |

198| 프로젝트 CLAUDE.md (`settingSources`를 통해 로드됨) | 미리 로드된 스킬 콘텐츠(`AgentDefinition.skills`에 나열된 경우 제외) |

199| 도구 정의 (부모에서 상속되거나 `tools`의 부분 집합) | 부모의 시스템 프롬프트 |

200

201<Note>

202 부모는 서브에이전트의 최종 메시지를 Agent 도구 결과로 그대로 받지만, 자신의 응답에서 요약할 수 있습니다. 서브에이전트 출력을 사용자 대면 응답에서 그대로 유지하려면, **메인** `query()` 호출에 전달하는 프롬프트 또는 `systemPrompt` 옵션에 그렇게 하도록 지시하는 지침을 포함하세요.

203</Note>

204

205## 서브에이전트 호출

206

207### 자동 호출

208

209Claude는 작업과 각 서브에이전트의 `description`을 기반으로 서브에이전트를 호출할 시기를 자동으로 결정합니다. 예를 들어, "쿼리 튜닝을 위한 성능 최적화 전문가"라는 설명이 있는 `performance-optimizer` 서브에이전트를 정의하면, Claude는 프롬프트에서 쿼리 최적화를 언급할 때 이를 호출합니다.

210

211Claude가 작업을 올바른 서브에이전트와 일치시킬 수 있도록 명확하고 구체적인 설명을 작성하세요.

212

213### 명시적 호출

214

215Claude가 특정 서브에이전트를 사용하도록 보장하려면, 프롬프트에서 이름으로 언급하세요.

216

217```text theme={null}

218"Use the code-reviewer agent to check the authentication module"

219```

220

221이는 자동 일치를 우회하고 명명된 서브에이전트를 직접 호출합니다.

222

223### 동적 에이전트 구성

224

225런타임 조건에 따라 에이전트 정의를 동적으로 생성할 수 있습니다. 이 예시는 다양한 엄격함 수준의 보안 리뷰어를 생성하며, 엄격한 리뷰에는 더 강력한 모델을 사용합니다.

226

227<CodeGroup>

228 ```python Python theme={null}

229 import asyncio

230 from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

231

232

233 # Factory function that returns an AgentDefinition

234 # This pattern lets you customize agents based on runtime conditions

235 def create_security_agent(security_level: str) -> AgentDefinition:

236 is_strict = security_level == "strict"

237 return AgentDefinition(

238 description="Security code reviewer",

239 # Customize the prompt based on strictness level

240 prompt=f"You are a {'strict' if is_strict else 'balanced'} security reviewer...",

241 tools=["Read", "Grep", "Glob"],

242 # Key insight: use a more capable model for high-stakes reviews

243 model="opus" if is_strict else "sonnet",

244 )

245

246

247 async def main():

248 # The agent is created at query time, so each request can use different settings

249 async for message in query(

250 prompt="Review this PR for security issues",

251 options=ClaudeAgentOptions(

252 allowed_tools=["Read", "Grep", "Glob", "Agent"],

253 agents={

254 # Call the factory with your desired configuration

255 "security-reviewer": create_security_agent("strict")

256 },

257 ),

258 ):

259 if hasattr(message, "result"):

260 print(message.result)

261

262

263 asyncio.run(main())

264 ```

265

266 ```typescript TypeScript theme={null}

267 import { query, type AgentDefinition } from "@anthropic-ai/claude-agent-sdk";

268

269 // Factory function that returns an AgentDefinition

270 // This pattern lets you customize agents based on runtime conditions

271 function createSecurityAgent(securityLevel: "basic" | "strict"): AgentDefinition {

272 const isStrict = securityLevel === "strict";

273 return {

274 description: "Security code reviewer",

275 // Customize the prompt based on strictness level

276 prompt: `You are a ${isStrict ? "strict" : "balanced"} security reviewer...`,

277 tools: ["Read", "Grep", "Glob"],

278 // Key insight: use a more capable model for high-stakes reviews

279 model: isStrict ? "opus" : "sonnet"

280 };

281 }

282

283 // The agent is created at query time, so each request can use different settings

284 for await (const message of query({

285 prompt: "Review this PR for security issues",

286 options: {

287 allowedTools: ["Read", "Grep", "Glob", "Agent"],

288 agents: {

289 // Call the factory with your desired configuration

290 "security-reviewer": createSecurityAgent("strict")

291 }

292 }

293 })) {

294 if ("result" in message) console.log(message.result);

295 }

296 ```

297</CodeGroup>

298

299## 서브에이전트 호출 감지

300

301서브에이전트는 Agent 도구를 통해 호출됩니다. 서브에이전트가 호출될 때를 감지하려면, `name`이 `"Agent"`인 `tool_use` 블록을 확인하세요. 서브에이전트의 컨텍스트 내에서의 메시지에는 `parent_tool_use_id` 필드가 포함됩니다.

302

303<Note>

304 도구 이름은 Claude Code v2.1.63에서 `"Task"`에서 `"Agent"`로 변경되었습니다. 현재 SDK 릴리스는 `tool_use` 블록에서 `"Agent"`를 내보내지만 여전히 `system:init` 도구 목록과 `result.permission_denials[].tool_name`에서 `"Task"`를 사용합니다. `block.name`에서 두 값을 모두 확인하면 SDK 버전 간 호환성이 보장됩니다.

305</Note>

306

307이 예시는 스트리밍된 메시지를 반복하여 서브에이전트가 호출될 때와 후속 메시지가 해당 서브에이전트의 실행 컨텍스트 내에서 시작될 때를 기록합니다.

308

309<Note>

310 메시지 구조는 SDK 간에 다릅니다. Python에서는 콘텐츠 블록이 `message.content`를 통해 직접 액세스됩니다. TypeScript에서는 `SDKAssistantMessage`가 Claude API 메시지를 래핑하므로 콘텐츠는 `message.message.content`를 통해 액세스됩니다.

311</Note>

312

313<CodeGroup>

314 ```python Python theme={null}

315 import asyncio

316 from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

317

318

319 async def main():

320 async for message in query(

321 prompt="Use the code-reviewer agent to review this codebase",

322 options=ClaudeAgentOptions(

323 allowed_tools=["Read", "Glob", "Grep", "Agent"],

324 agents={

325 "code-reviewer": AgentDefinition(

326 description="Expert code reviewer.",

327 prompt="Analyze code quality and suggest improvements.",

328 tools=["Read", "Glob", "Grep"],

329 )

330 },

331 ),

332 ):

333 # Check for subagent invocation. Match both names: older SDK

334 # versions emitted "Task", current versions emit "Agent".

335 if hasattr(message, "content") and message.content:

336 for block in message.content:

337 if getattr(block, "type", None) == "tool_use" and block.name in (

338 "Task",

339 "Agent",

340 ):

341 print(f"Subagent invoked: {block.input.get('subagent_type')}")

342

343 # Check if this message is from within a subagent's context

344 if hasattr(message, "parent_tool_use_id") and message.parent_tool_use_id:

345 print(" (running inside subagent)")

346

347 if hasattr(message, "result"):

348 print(message.result)

349

350

351 asyncio.run(main())

352 ```

353

354 ```typescript TypeScript theme={null}

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

356

357 for await (const message of query({

358 prompt: "Use the code-reviewer agent to review this codebase",

359 options: {

360 allowedTools: ["Read", "Glob", "Grep", "Agent"],

361 agents: {

362 "code-reviewer": {

363 description: "Expert code reviewer.",

364 prompt: "Analyze code quality and suggest improvements.",

365 tools: ["Read", "Glob", "Grep"]

366 }

367 }

368 }

369 })) {

370 const msg = message as any;

371

372 // Check for subagent invocation. Match both names: older SDK versions

373 // emitted "Task", current versions emit "Agent".

374 for (const block of msg.message?.content ?? []) {

375 if (block.type === "tool_use" && (block.name === "Task" || block.name === "Agent")) {

376 console.log(`Subagent invoked: ${block.input.subagent_type}`);

377 }

378 }

379

380 // Check if this message is from within a subagent's context

381 if (msg.parent_tool_use_id) {

382 console.log(" (running inside subagent)");

383 }

384

385 if ("result" in message) {

386 console.log(message.result);

387 }

388 }

389 ```

390</CodeGroup>

391

392## 서브에이전트 재개

393

394서브에이전트를 재개하여 중단한 지점에서 계속할 수 있습니다. 재개된 서브에이전트는 이전의 모든 도구 호출, 결과 및 추론을 포함한 전체 대화 기록을 유지합니다. 서브에이전트는 새로 시작하는 대신 정확히 중단한 지점에서 계속됩니다.

395

396서브에이전트가 완료되면, Claude는 Agent 도구 결과에서 에이전트 ID를 받습니다. 서브에이전트를 프로그래밍 방식으로 재개하려면:

397

3981. **세션 ID 캡처**: 첫 번째 쿼리 중에 메시지에서 `session_id` 추출

3992. **에이전트 ID 추출**: 메시지 콘텐츠에서 `agentId` 파싱

4003. **세션 재개**: 두 번째 쿼리의 옵션에서 `resume: sessionId`를 전달하고, 프롬프트에 에이전트 ID 포함

401

402<Note>

403 서브에이전트의 트랜스크립트에 액세스하려면 같은 세션을 재개해야 합니다. 각 `query()` 호출은 기본적으로 새 세션을 시작하므로, 같은 세션에서 계속하려면 `resume: sessionId`를 전달하세요.

404

405 기본 제공 에이전트가 아닌 사용자 정의 에이전트를 사용하는 경우, 두 쿼리 모두에서 `agents` 매개변수에 같은 에이전트 정의를 전달해야 합니다.

406</Note>

407

408아래 예시는 이 흐름을 보여줍니다. 첫 번째 쿼리는 서브에이전트를 실행하고 세션 ID와 에이전트 ID를 캡처하고, 두 번째 쿼리는 세션을 재개하여 첫 번째 분석의 컨텍스트가 필요한 후속 질문을 합니다.

409

410<CodeGroup>

411 ```typescript TypeScript theme={null}

412 import { query, type SDKMessage } from "@anthropic-ai/claude-agent-sdk";

413

414 // Helper to extract agentId from message content

415 // Stringify to avoid traversing different block types (TextBlock, ToolResultBlock, etc.)

416 function extractAgentId(message: SDKMessage): string | undefined {

417 if (!("message" in message)) return undefined;

418 // Stringify the content so we can search it without traversing nested blocks

419 const content = JSON.stringify(message.message.content);

420 const match = content.match(/agentId:\s*([a-f0-9-]+)/);

421 return match?.[1];

422 }

423

424 let agentId: string | undefined;

425 let sessionId: string | undefined;

426

427 // First invocation - use the Explore agent to find API endpoints

428 for await (const message of query({

429 prompt: "Use the Explore agent to find all API endpoints in this codebase",

430 options: { allowedTools: ["Read", "Grep", "Glob", "Agent"] }

431 })) {

432 // Capture session_id from ResultMessage (needed to resume this session)

433 if ("session_id" in message) sessionId = message.session_id;

434 // Search message content for the agentId (appears in Agent tool results)

435 const extractedId = extractAgentId(message);

436 if (extractedId) agentId = extractedId;

437 // Print the final result

438 if ("result" in message) console.log(message.result);

439 }

440

441 // Second invocation - resume and ask follow-up

442 if (agentId && sessionId) {

443 for await (const message of query({

444 prompt: `Resume agent ${agentId} and list the top 3 most complex endpoints`,

445 options: { allowedTools: ["Read", "Grep", "Glob", "Agent"], resume: sessionId }

446 })) {

447 if ("result" in message) console.log(message.result);

448 }

449 }

450 ```

451

452 ```python Python theme={null}

453 import asyncio

454 import json

455 import re

456 from claude_agent_sdk import query, ClaudeAgentOptions

457

458

459 def extract_agent_id(text: str) -> str | None:

460 """Extract agentId from Agent tool result text."""

461 match = re.search(r"agentId:\s*([a-f0-9-]+)", text)

462 return match.group(1) if match else None

463

464

465 async def main():

466 agent_id = None

467 session_id = None

468

469 # First invocation - use the Explore agent to find API endpoints

470 async for message in query(

471 prompt="Use the Explore agent to find all API endpoints in this codebase",

472 options=ClaudeAgentOptions(allowed_tools=["Read", "Grep", "Glob", "Agent"]),

473 ):

474 # Capture session_id from ResultMessage (needed to resume this session)

475 if hasattr(message, "session_id"):

476 session_id = message.session_id

477 # Search message content for the agentId (appears in Agent tool results)

478 if hasattr(message, "content"):

479 # Stringify the content so we can search it without traversing nested blocks

480 content_str = json.dumps(message.content, default=str)

481 extracted = extract_agent_id(content_str)

482 if extracted:

483 agent_id = extracted

484 # Print the final result

485 if hasattr(message, "result"):

486 print(message.result)

487

488 # Second invocation - resume and ask follow-up

489 if agent_id and session_id:

490 async for message in query(

491 prompt=f"Resume agent {agent_id} and list the top 3 most complex endpoints",

492 options=ClaudeAgentOptions(

493 allowed_tools=["Read", "Grep", "Glob", "Agent"], resume=session_id

494 ),

495 ):

496 if hasattr(message, "result"):

497 print(message.result)

498

499

500 asyncio.run(main())

501 ```

502</CodeGroup>

503

504서브에이전트 트랜스크립트는 메인 대화와 독립적으로 유지됩니다.

505

506* **메인 대화 압축**: 메인 대화가 압축될 때, 서브에이전트 트랜스크립트는 영향을 받지 않습니다. 이들은 별도의 파일에 저장됩니다.

507* **세션 지속성**: 서브에이전트 트랜스크립트는 해당 세션 내에서 유지됩니다. 같은 세션을 재개하여 Claude Code를 다시 시작한 후 서브에이전트를 재개할 수 있습니다.

508* **자동 정리**: 트랜스크립트는 `cleanupPeriodDays` 설정(기본값: 30일)에 따라 정리됩니다.

509

510## 도구 제한

511

512서브에이전트는 `tools` 필드를 통해 제한된 도구 액세스를 가질 수 있습니다.

513

514* **필드 생략**: 에이전트는 사용 가능한 모든 도구를 상속합니다(기본값).

515* **도구 지정**: 에이전트는 나열된 도구만 사용할 수 있습니다.

516

517이 예시는 코드를 검토할 수 있지만 파일을 수정하거나 명령을 실행할 수 없는 읽기 전용 분석 에이전트를 생성합니다.

518

519<CodeGroup>

520 ```python Python theme={null}

521 import asyncio

522 from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

523

524

525 async def main():

526 async for message in query(

527 prompt="Analyze the architecture of this codebase",

528 options=ClaudeAgentOptions(

529 allowed_tools=["Read", "Grep", "Glob", "Agent"],

530 agents={

531 "code-analyzer": AgentDefinition(

532 description="Static code analysis and architecture review",

533 prompt="""You are a code architecture analyst. Analyze code structure,

534 identify patterns, and suggest improvements without making changes.""",

535 # Read-only tools: no Edit, Write, or Bash access

536 tools=["Read", "Grep", "Glob"],

537 )

538 },

539 ),

540 ):

541 if hasattr(message, "result"):

542 print(message.result)

543

544

545 asyncio.run(main())

546 ```

547

548 ```typescript TypeScript theme={null}

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

550

551 for await (const message of query({

552 prompt: "Analyze the architecture of this codebase",

553 options: {

554 allowedTools: ["Read", "Grep", "Glob", "Agent"],

555 agents: {

556 "code-analyzer": {

557 description: "Static code analysis and architecture review",

558 prompt: `You are a code architecture analyst. Analyze code structure,

559 identify patterns, and suggest improvements without making changes.`,

560 // Read-only tools: no Edit, Write, or Bash access

561 tools: ["Read", "Grep", "Glob"]

562 }

563 }

564 }

565 })) {

566 if ("result" in message) console.log(message.result);

567 }

568 ```

569</CodeGroup>

570

571### 일반적인 도구 조합

572

573| 사용 사례 | 도구 | 설명 |

574| :------- | :-------------------------------------- | :------------------------------- |

575| 읽기 전용 분석 | `Read`, `Grep`, `Glob` | 코드를 검토할 수 있지만 수정하거나 실행할 수 없습니다. |

576| 테스트 실행 | `Bash`, `Read`, `Grep` | 명령을 실행하고 출력을 분석할 수 있습니다. |

577| 코드 수정 | `Read`, `Edit`, `Write`, `Grep`, `Glob` | 명령 실행 없이 전체 읽기/쓰기 액세스 |

578| 전체 액세스 | 모든 도구 | 부모의 모든 도구를 상속합니다(`tools` 필드 생략). |

579

580## 문제 해결

581

582### Claude가 서브에이전트에 위임하지 않음

583

584Claude가 서브에이전트에 위임하는 대신 작업을 직접 완료하는 경우:

585

5861. **Agent 도구 포함**: 서브에이전트는 Agent 도구를 통해 호출되므로 `allowedTools`에 포함되어야 합니다.

5872. **명시적 프롬프팅 사용**: 프롬프트에서 서브에이전트를 이름으로 언급하세요(예: "code-reviewer 에이전트를 사용하여...").

5883. **명확한 설명 작성**: Claude가 작업을 적절히 일치시킬 수 있도록 서브에이전트를 사용해야 할 때를 정확히 설명하세요.

589

590### 파일 시스템 기반 에이전트가 로드되지 않음

591

592`.claude/agents/`에 정의된 에이전트는 시작 시에만 로드됩니다. Claude Code가 실행 중인 동안 새 에이전트 파일을 생성하면, 세션을 다시 시작하여 로드하세요.

593

594### Windows: 긴 프롬프트 실패

595

596Windows에서는 매우 긴 프롬프트가 있는 서브에이전트가 명령줄 길이 제한(8191자)으로 인해 실패할 수 있습니다. 프롬프트를 간결하게 유지하거나 복잡한 지침에는 파일 시스템 기반 에이전트를 사용하세요.

597

598## 관련 문서

599

600* [Claude Code 서브에이전트](/ko/sub-agents): 파일 시스템 기반 정의를 포함한 포괄적인 서브에이전트 문서

601* [SDK 개요](/ko/agent-sdk/overview): Claude Agent SDK 시작하기

agent-sdk/typescript.md +4 −2

Details

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

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

530| 필드 | 필수 | 설명 |531| 필드 | 필수 | 설명 |

531| :------------------------------------ | :-- | :------------------------------------------------------------------------------------------------------------------------- |532| :------------------------------------ | :-- | :------------------------------------------------------------------------------------------------------------------------- |

532| `description` | 예 | 이 에이전트를 사용할 시기에 대한 자연어 설명 |533| `description` | 예 | 이 에이전트를 사용할 시기에 대한 자연어 설명 |

533| `tools` | 아니오 | 허용된 도구 이름의 배열입니다. 생략하면 부모의 모든 도구를 상속합니다 |534| `tools` | 아니오 | 허용된 도구 이름의 배열입니다. 생략하면 부모의 모든 도구를 상속합니다. 에이전트의 컨텍스트에 스킬을 미리 로드하려면 `'Skill'`을 여기에 나열하는 대신 `skills` 필드를 사용합니다 |

534| `disallowedTools` | 아니오 | 이 에이전트에 대해 명시적으로 허용하지 않을 도구 이름의 배열 |535| `disallowedTools` | 아니오 | 이 에이전트에 대해 명시적으로 허용하지 않을 도구 이름의 배열 |

535| `prompt` | 예 | 에이전트의 시스템 프롬프트 |536| `prompt` | 예 | 에이전트의 시스템 프롬프트 |

536| `model` | 아니오 | 이 에이전트의 모델 재정의입니다. `'sonnet'`, `'opus'`, `'haiku'`, `'inherit'` 같은 별칭 또는 전체 모델 ID를 허용합니다. 생략하거나 `'inherit'`이면 메인 모델을 사용합니다 |537| `model` | 아니오 | 이 에이전트의 모델 재정의입니다. `'sonnet'`, `'opus'`, `'haiku'`, `'inherit'` 같은 별칭 또는 전체 모델 ID를 허용합니다. 생략하거나 `'inherit'`이면 메인 모델을 사용합니다 |

1176 transcript_path: string;1177 transcript_path: string;

1177 cwd: string;1178 cwd: string;

1178 permission_mode?: string;1179 permission_mode?: string;

1180 effort?: { level: string };

1179 agent_id?: string;1181 agent_id?: string;

1180 agent_type?: string;1182 agent_type?: string;

1181};1183};

agent-sdk/typescript-v2-preview.md +5 −9

Details

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> 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.3> Use this file to discover all available pages before exploring further.

4 4

~~5# TypeScript SDK V2 인터페이스 (미리보기)~~5# TypeScript SDK V2 세션 API (지원 중단됨)

6 6

~~7> 세션 기반 send/stream 패턴을 사용한 간소화된 V2 TypeScript Agent SDK의 미리보기로, 다중 턴 대화를 지원합니다.~~7> 다중 턴 대화를 위한 세션 기반 send/stream 패턴을 사용하는 지원 중단된 V2 TypeScript Agent SDK 세션 API 참조입니다.

8 8

9<Warning>9<Warning>

10 V2 인터페이스는 **불안정한 미리보기**입니다. API는 안정화되기 전에 피드백에 따라 변경될 수 있습니다. 세션 포킹과 같은 일부 기능은 [V1 SDK](/ko/agent-sdk/typescript)에서만 사용 가능합니다.10 V2 세션 API 함수 `unstable_v2_createSession`, `unstable_v2_resumeSession`, `unstable_v2_prompt`는 지원 중단되었으며 향후 릴리스에서 제거될 예정입니다. 대신 [V1 `query()` API](/ko/agent-sdk/typescript)를 사용하십시오.

11</Warning>11</Warning>

12 12

13V2 Claude Agent TypeScript SDK는 비동기 생성기와 yield 조정의 필요성을 제거합니다. 이를 통해 다중 턴 대화가 더 간단해지며, 턴 전체에서 생성기 상태를 관리하는 대신 각 턴은 별도의 `send()`/`stream()` 사이클입니다. API 표면은 세 가지 개념으로 축소됩니다:13V2는 비동기 생성기와 yield 조정의 필요성을 제거한 실험적 세션 API였습니다. 턴 전체에서 생성기 상태를 관리하는 대신 각 턴은 별도의 `send()`/`stream()` 사이클이었습니다. API 표면은 세 가지 개념으로 축소되었습니다:

14 14

15* `createSession()` / `resumeSession()`: 대화 시작 또는 계속15* `createSession()` / `resumeSession()`: 대화 시작 또는 계속

16* `session.send()`: 메시지 전송16* `session.send()`: 메시지 전송

380 380

381## 기능 가용성381## 기능 가용성

382 382

383모든 V1 기능이 V2에서 아직 사용 가능한 것은 아닙니다. 다음은 [V1 SDK](/ko/agent-sdk/typescript)를 사용해야 합니다:383V2 세션 API는 모든 V1 기능을 지원하지 않습니다. 다음은 [V1 SDK](/ko/agent-sdk/typescript)가 필요합니다:

384 384

385* 세션 포킹 (`forkSession` 옵션)385* 세션 포킹 (`forkSession` 옵션)

386* 일부 고급 스트리밍 입력 패턴386* 일부 고급 스트리밍 입력 패턴

387 387

388## 피드백

~~389~~

390V2 인터페이스가 안정화되기 전에 피드백을 공유합니다. [GitHub Issues](https://github.com/anthropics/claude-code/issues)를 통해 문제와 제안을 보고합니다.

~~391~~

392## 참고 항목388## 참고 항목

393 389

394* [TypeScript SDK 참조 (V1)](/ko/agent-sdk/typescript) - 전체 V1 SDK 문서390* [TypeScript SDK 참조 (V1)](/ko/agent-sdk/typescript) - 전체 V1 SDK 문서

agent-teams.md +1 −1

Details

420병렬 작업 및 위임을 위한 관련 접근 방식을 탐색합니다:420병렬 작업 및 위임을 위한 관련 접근 방식을 탐색합니다:

421 421

422* **경량 위임**: [subagents](/ko/sub-agents)는 세션 내에서 연구 또는 검증을 위해 도우미 에이전트를 생성하며, 에이전트 간 조율이 필요하지 않은 작업에 더 좋습니다422* **경량 위임**: [subagents](/ko/sub-agents)는 세션 내에서 연구 또는 검증을 위해 도우미 에이전트를 생성하며, 에이전트 간 조율이 필요하지 않은 작업에 더 좋습니다

423* **수동 병렬 세션**: [Git worktrees](/ko/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees)를 사용하면 자동화된 팀 조율 없이 여러 Claude Code 세션을 직접 실행할 수 있습니다423* **수동 병렬 세션**: [Git worktrees](/ko/worktrees)를 사용하면 자동화된 팀 조율 없이 여러 Claude Code 세션을 직접 실행할 수 있습니다

424* **접근 방식 비교**: [subagent vs 에이전트 팀](/ko/features-overview#compare-similar-features) 비교를 참조하여 나란히 비교합니다424* **접근 방식 비교**: [subagent vs 에이전트 팀](/ko/features-overview#compare-similar-features) 비교를 참조하여 나란히 비교합니다

amazon-bedrock.md +1 −111

Details

76 </div>;76 </div>;

77};77};

78 78

~~79export const Experiment = ({flag, treatment, children}) => {~~79<ContactSalesCard surface="bedrock" />

~~80 const VID_KEY = 'exp_vid';~~

81 const CONSENT_COUNTRIES = new Set(['AT', 'BE', 'BG', 'HR', 'CY', 'CZ', 'DK', 'EE', 'FI', 'FR', 'DE', 'GR', 'HU', 'IE', 'IT', 'LV', 'LT', 'LU', 'MT', 'NL', 'PL', 'PT', 'RO', 'SK', 'SI', 'ES', 'SE', 'RE', 'GP', 'MQ', 'GF', 'YT', 'BL', 'MF', 'PM', 'WF', 'PF', 'NC', 'AW', 'CW', 'SX', 'FO', 'GL', 'AX', 'GB', 'UK', 'AI', 'BM', 'IO', 'VG', 'KY', 'FK', 'GI', 'MS', 'PN', 'SH', 'TC', 'GG', 'JE', 'IM', 'CA', 'BR', 'IN']);

~~82 const fnv1a = s => {~~

~~83 let h = 0x811c9dc5;~~

~~84 for (let i = 0; i < s.length; i++) {~~

~~85 h ^= s.charCodeAt(i);~~

~~86 h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24);~~

~~87 }~~

~~88 return h >>> 0;~~

~~89 };~~

~~90 const bucket = (seed, vid) => fnv1a(fnv1a(seed + vid) + '') % 10000 < 5000 ? 'control' : 'treatment';~~

~~91 const [decision] = useState(() => {~~

~~92 const params = new URLSearchParams(location.search);~~

~~93 const preBucketed = document.documentElement.dataset['gb_' + flag.replace(/-/g, '_')];~~

~~94 const force = params.get('gb-force');~~

~~95 if (force) {~~

~~96 for (const p of force.split(',')) {~~

~~97 const [k, v] = p.split(':');~~

~~98 if (k === flag) return {~~

~~99 variant: v || 'treatment',~~

100 track: false

101 };

102 }

103 }

104 if (navigator.globalPrivacyControl) {

105 return {

106 variant: 'control',

107 track: false

108 };

109 }

110 const prefsMatch = document.cookie.match(/(?:^|; )anthropic-consent-preferences=([^;]+)/);

111 if (prefsMatch) {

112 try {

113 if (JSON.parse(decodeURIComponent(prefsMatch[1])).analytics !== true) {

114 return {

115 variant: 'control',

116 track: false

117 };

118 }

119 } catch {

120 return {

121 variant: 'control',

122 track: false

123 };

124 }

125 } else {

126 const country = params.get('country')?.toUpperCase() || (document.cookie.match(/(?:^|; )cf_geo=([A-Z]{2})/) || [])[1];

127 if (!country || CONSENT_COUNTRIES.has(country)) {

128 return {

129 variant: 'control',

130 track: false

131 };

132 }

133 }

134 let vid;

135 try {

136 const ajsMatch = document.cookie.match(/(?:^|; )ajs_anonymous_id=([^;]+)/);

137 if (ajsMatch) {

138 vid = decodeURIComponent(ajsMatch[1]).replace(/^"|"$/g, '');

139 } else {

140 vid = localStorage.getItem(VID_KEY);

141 if (!vid) {

142 vid = crypto.randomUUID();

143 }

144 document.cookie = `ajs_anonymous_id=${vid}; domain=.claude.com; path=/; Secure; SameSite=Lax; max-age=31536000`;

145 }

146 try {

147 localStorage.setItem(VID_KEY, vid);

148 } catch {}

149 } catch {

150 return {

151 variant: 'control',

152 track: false

153 };

154 }

155 const variant = preBucketed === '1' ? 'treatment' : preBucketed === '0' ? 'control' : bucket(flag, vid);

156 return {

157 variant,

158 track: true,

159 vid

160 };

161 });

162 useEffect(() => {

163 if (!decision.track) return;

164 fetch('https://api.anthropic.com/api/event_logging/v2/batch', {

165 method: 'POST',

166 headers: {

167 'Content-Type': 'application/json',

168 'x-service-name': 'claude_code_docs'

169 },

170 body: JSON.stringify({

171 events: [{

172 event_type: 'GrowthbookExperimentEvent',

173 event_data: {

174 device_id: decision.vid,

175 anonymous_id: decision.vid,

176 timestamp: new Date().toISOString(),

177 experiment_id: flag,

178 variation_id: decision.variant === 'treatment' ? 1 : 0,

179 environment: 'production'

180 }

181 }]

182 }),

183 keepalive: true

184 }).catch(() => {});

185 }, []);

186 return decision.variant === 'treatment' ? treatment : children;

187};

~~188~~

189<Experiment flag="docs-contact-sales-cta" treatment={<ContactSalesCard surface="bedrock" />} />

190 80

191## 필수 조건81## 필수 조건

192 82

cli-reference.md +2 −2

Details

84| `--permission-mode` | 지정된 [권한 모드](/ko/permission-modes)에서 시작합니다. `default`, `acceptEdits`, `plan`, `auto`, `dontAsk` 또는 `bypassPermissions`를 허용합니다. 설정 파일의 `defaultMode`를 재정의합니다 | `claude --permission-mode plan` |84| `--permission-mode` | 지정된 [권한 모드](/ko/permission-modes)에서 시작합니다. `default`, `acceptEdits`, `plan`, `auto`, `dontAsk` 또는 `bypassPermissions`를 허용합니다. 설정 파일의 `defaultMode`를 재정의합니다 | `claude --permission-mode plan` |

86| `--plugin-dir` | 이 세션에만 디렉토리 또는 `.zip` 아카이브에서 plugin을 로드합니다. 각 플래그는 하나의 경로를 사용합니다. 여러 plugins의 경우 플래그를 반복합니다: `--plugin-dir A --plugin-dir B.zip` | `claude --plugin-dir ./my-plugin` |86| `--plugin-dir` | 이 세션에만 디렉토리 또는 `.zip` 아카이브에서 plugin을 로드합니다. 각 플래그는 하나의 경로를 사용합니다. 여러 plugins의 경우 플래그를 반복합니다: `--plugin-dir A --plugin-dir B.zip` | `claude --plugin-dir ./my-plugin` |

90| `--remote-control`, `--rc` | claude.ai 또는 Claude 앱에서도 제어할 수 있도록 [Remote Control](/ko/remote-control#start-a-remote-control-session)이 활성화된 대화형 세션을 시작합니다. 선택적으로 세션의 이름을 전달할 수 있습니다 | `claude --remote-control "My Project"` |90| `--remote-control`, `--rc` | claude.ai 또는 Claude 앱에서도 제어할 수 있도록 [Remote Control](/ko/remote-control#start-a-remote-control-session)이 활성화된 대화형 세션을 시작합니다. 선택적으로 세션의 이름을 전달할 수 있습니다 | `claude --remote-control "My Project"` |

103| `--tools` | Claude가 사용할 수 있는 기본 제공 도구를 제한합니다. 모두 비활성화하려면 `""`를 사용하고, 모두 사용하려면 `"default"`를 사용하거나, `"Bash,Edit,Read"`와 같은 도구 이름을 사용합니다 | `claude --tools "Bash,Edit,Read"` |103| `--tools` | Claude가 사용할 수 있는 기본 제공 도구를 제한합니다. 모두 비활성화하려면 `""`를 사용하고, 모두 사용하려면 `"default"`를 사용하거나, `"Bash,Edit,Read"`와 같은 도구 이름을 사용합니다 | `claude --tools "Bash,Edit,Read"` |

106| `--worktree`, `-w` | Claude를 `<repo>/.claude/worktrees/<name>`의 격리된 [git worktree](/ko/worktrees)에서 시작합니다. 이름이 지정되지 않으면 자동으로 생성됩니다 | `claude -w feature-auth` |106| `--worktree`, `-w` | Claude를 `<repo>/.claude/worktrees/<name>`의 격리된 [git worktree](/ko/worktrees)에서 시작합니다. 이름이 지정되지 않으면 자동으로 생성됩니다. `#<number>` 또는 GitHub pull request URL을 전달하여 `origin`에서 해당 PR을 가져오고 worktree를 분기합니다 | `claude -w feature-auth` |

107 107

108### 시스템 프롬프트 플래그108### 시스템 프롬프트 플래그

109 109

commands.md +20 −2

Details

12 12

13명령어는 메시지의 시작 부분에서만 인식됩니다. 명령어 이름 다음에 오는 텍스트는 인수로 전달됩니다.13명령어는 메시지의 시작 부분에서만 인식됩니다. 명령어 이름 다음에 오는 텍스트는 인수로 전달됩니다.

14 14

15아래 표는 Claude Code에 포함된 모든 명령어를 나열합니다. \*\*[Skill](/ko/skills#bundled-skills)\*\*로 표시된 항목은 번들 skills입니다. 이들은 직접 작성하는 skills와 동일한 메커니즘을 사용합니다. Claude에 전달되는 프롬프트이며, Claude는 관련이 있을 때 자동으로 호출할 수도 있습니다. 그 외의 모든 것은 CLI에 코딩된 동작을 가진 기본 제공 명령어입니다. 자신만의 명령어를 추가하려면 [skills](/ko/skills)를 참조하세요.15## 일반적인 워크플로우 전반의 명령어

17대부분의 명령어는 프로젝트 설정부터 변경 사항 배포까지 세션의 특정 지점에서 유용합니다.

19**리포지토리의 첫 번째 세션.** `/init`을 실행하여 시작 `CLAUDE.md`를 생성한 다음, `/memory`를 실행하여 이를 개선합니다. `/mcp` 및 `/agents`를 사용하여 프로젝트에 필요한 모든 서버 또는 subagent를 설정하고, `/permissions`을 사용하여 원하는 승인 규칙을 설정합니다.

21**작업 중.** `/plan`은 큰 변경 전에 plan mode로 전환합니다. `/model` 및 `/effort`는 소비하는 추론의 양을 조정합니다. 대화가 길어지면 `/context`는 윈도우가 어디로 가는지 보여주고 `/compact`는 이를 요약합니다. `/btw`를 사용하여 기록을 부풀리지 않아야 하는 빠른 여담을 남깁니다.

23**배포 전.** `/diff`는 변경된 내용을 표시하고, `/simplify`는 최근 파일을 검토하고 품질 및 효율성 수정 사항을 적용하며, `/review` 또는 `/security-review`는 더 깊은 읽기 전용 검토를 제공합니다.

16 24

17모든 명령어가 모든 사용자에게 표시되는 것은 아닙니다. 가용성은 플랫폼, 요금제 및 환경에 따라 달라집니다. 예를 들어, `/desktop`은 macOS 및 Windows에서만 표시되고, `/upgrade`는 Pro 및 Max 요금제에서만 표시됩니다.25**세션 간.** `/clear`는 프로젝트 메모리를 유지하면서 새 작업을 새로 시작합니다. `/resume` 및 `/branch`를 사용하면 이전 대화로 돌아가거나 분기할 수 있습니다. `/teleport`는 웹 세션을 이 터미널로 가져오고, `/remote-control`을 사용하면 다른 기기에서 이 로컬 세션을 계속할 수 있습니다.

27**문제가 발생했을 때.** `/rewind`는 코드와 대화를 checkpoint로 되돌립니다. `/doctor` 및 `/debug`는 설치 및 런타임 문제를 진단하고, `/feedback`은 세션 컨텍스트가 첨부된 버그를 보고합니다.

29## 모든 명령어

31아래 표는 Claude Code에 포함된 모든 명령어를 나열합니다. \*\*[Skill](/ko/skills#bundled-skills)\*\*로 표시된 항목은 번들 skills입니다. 이들은 직접 작성하는 skills와 동일한 메커니즘을 사용합니다. Claude에 전달되는 프롬프트이며, Claude는 관련이 있을 때 자동으로 호출할 수도 있습니다. 그 외의 모든 것은 CLI에 코딩된 동작을 가진 기본 제공 명령어입니다. 자신만의 명령어를 추가하려면 [skills](/ko/skills)를 참조하세요.

18 32

19아래 표에서 `<arg>`는 필수 인수를 나타내고 `[arg]`는 선택적 인수를 나타냅니다.33아래 표에서 `<arg>`는 필수 인수를 나타내고 `[arg]`는 선택적 인수를 나타냅니다.

20 34

35<Note>

36 모든 명령어가 모든 사용자에게 표시되는 것은 아닙니다. 가용성은 플랫폼, 요금제 및 환경에 따라 달라집니다. 예를 들어, `/desktop`은 macOS 및 Windows에서만 표시되고, `/upgrade`는 Pro 및 Max 요금제에서만 표시됩니다.

37</Note>

21| 명령어 | 목적 |39| 명령어 | 목적 |

22| :---------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |40| :---------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

23| `/add-dir <path>` | 현재 세션 중에 파일 액세스를 위한 작업 디렉토리를 추가합니다. 대부분의 `.claude/` 구성은 추가된 디렉토리에서 [발견되지 않습니다](/ko/permissions#additional-directories-grant-file-access-not-configuration). 나중에 `--continue` 또는 `--resume`을 사용하여 추가된 디렉토리에서 세션을 재개할 수 있습니다 |41| `/add-dir <path>` | 현재 세션 중에 파일 액세스를 위한 작업 디렉토리를 추가합니다. 대부분의 `.claude/` 구성은 추가된 디렉토리에서 [발견되지 않습니다](/ko/permissions#additional-directories-grant-file-access-not-configuration). 나중에 `--continue` 또는 `--resume`을 사용하여 추가된 디렉토리에서 세션을 재개할 수 있습니다 |

desktop.md +17 −0

Details

564 564

565각 항목에는 `id`, `name`, `sshHost`가 필요합니다. `sshPort`, `sshIdentityFile`, `startDirectory` 필드는 선택 사항입니다. 사용자는 자신의 `~/.claude/settings.json`에 `sshConfigs`를 추가할 수도 있습니다. 이는 대화 상자를 통해 추가된 연결이 저장되는 위치입니다.565각 항목에는 `id`, `name`, `sshHost`가 필요합니다. `sshPort`, `sshIdentityFile`, `startDirectory` 필드는 선택 사항입니다. 사용자는 자신의 `~/.claude/settings.json`에 `sshConfigs`를 추가할 수도 있습니다. 이는 대화 상자를 통해 추가된 연결이 저장되는 위치입니다.

566 566

567#### SSH 호스트 연결을 제한하여 사용자가 연결할 수 있는 호스트를 제한합니다

568

569관리자는 [관리되는 설정](/ko/settings#settings-precedence) 파일에 `sshHostAllowlist`를 추가하여 Desktop의 SSH 세션을 승인된 호스트 집합으로 제한할 수 있습니다. 설정되면 사용자는 확인된 호스트명이 패턴 중 하나와 일치하는 호스트에만 연결할 수 있습니다. SSH 세션을 완전히 비활성화하려면 빈 배열로 설정합니다.

570

571다음 예제는 `devboxes.example.com` 아래의 모든 호스트 및 단일 명명된 bastion 호스트에 대한 연결을 허용합니다:

572

573```json theme={null}

574{

575 "sshHostAllowlist": ["*.devboxes.example.com", "bastion.example.com"]

576}

577```

578

579패턴은 대소문자를 구분하지 않습니다. `*`는 모든 호스트와 일치하고, `*.example.com`은 `example.com` 및 모든 하위 도메인과 일치합니다. 다른 모든 것은 정확한 일치입니다. 검사는 `ssh -G`를 통한 `~/.ssh/config` 확인 후 호스트명에 대해 실행되므로 `Host` 별칭 및 `ProxyCommand`/`ProxyJump` 항목은 확인된 `HostName`이 일치하는 한 허용됩니다.

580

581`sshHostAllowlist`는 관리되는 설정에서만 읽혀집니다. 사용자 또는 프로젝트 설정의 값은 무시됩니다. Claude Desktop 앱만 이 설정을 인식합니다. Claude Code CLI 및 IDE 확장은 이를 읽지 않으며, Bash 도구를 통해 실행되는 `ssh` 명령을 제한하지 않습니다. 이는 Desktop 앱이 연결하는 호스트를 제어하며, 네트워크 송신을 제어하지 않으므로 하드 경계가 필요한 경우 조직의 네트워크 또는 제로 트러스트 제어와 함께 사용합니다.

582

567## 엔터프라이즈 구성583## 엔터프라이즈 구성

568 584

569Team 또는 Enterprise 계획의 조직은 관리 콘솔 컨트롤, 관리 설정 파일, 장치 관리 정책을 통해 데스크톱 앱 동작을 관리할 수 있습니다.585Team 또는 Enterprise 계획의 조직은 관리 콘솔 컨트롤, 관리 설정 파일, 장치 관리 정책을 통해 데스크톱 앱 동작을 관리할 수 있습니다.

587| `disableAutoMode` | 사용자가 [Auto](/ko/permission-modes#eliminate-prompts-with-auto-mode) 모드를 활성화하지 못하도록 하려면 `"disable"`로 설정합니다. 모드 선택기에서 Auto를 제거합니다. `permissions` 아래에서도 허용됩니다. |603| `disableAutoMode` | 사용자가 [Auto](/ko/permission-modes#eliminate-prompts-with-auto-mode) 모드를 활성화하지 못하도록 하려면 `"disable"`로 설정합니다. 모드 선택기에서 Auto를 제거합니다. `permissions` 아래에서도 허용됩니다. |

589| `sshConfigs` | 환경 드롭다운에 나타나는 [SSH 연결](#pre-configure-ssh-connections-for-your-team)을 사전 구성합니다. 사용자는 관리 연결을 편집하거나 삭제할 수 없습니다. |605| `sshConfigs` | 환경 드롭다운에 나타나는 [SSH 연결](#pre-configure-ssh-connections-for-your-team)을 사전 구성합니다. 사용자는 관리 연결을 편집하거나 삭제할 수 없습니다. |

606| `sshHostAllowlist` | [SSH 세션](#restrict-which-ssh-hosts-users-can-connect-to)을 확인된 호스트명이 이러한 패턴 중 하나와 일치하는 호스트로 제한합니다. 빈 배열은 SSH 세션을 비활성화합니다. 관리 설정에서만 읽습니다. |

590 607

591각 머신의 디스크에 배포된 관리 설정 파일은 Desktop 세션에 적용됩니다. 관리 콘솔을 통해 원격으로 푸시된 관리 설정은 현재 CLI 및 IDE 세션에만 도달하므로, Desktop 배포의 경우 MDM을 통해 파일을 배포하거나 위의 [관리 콘솔 컨트롤](#admin-console-controls)을 사용합니다.608각 머신의 디스크에 배포된 관리 설정 파일은 Desktop 세션에 적용됩니다. 관리 콘솔을 통해 원격으로 푸시된 관리 설정은 현재 CLI 및 IDE 세션에만 도달하므로, Desktop 배포의 경우 MDM을 통해 파일을 배포하거나 위의 [관리 콘솔 컨트롤](#admin-console-controls)을 사용합니다.

592 609

env-vars.md +4 −2

Details

92| `CLAUDE_CODE_EFFORT_LEVEL` | 지원되는 모델의 노력 수준을 설정합니다. 값: `low`, `medium`, `high`, `xhigh`, `max`, 또는 `auto`(모델 기본값 사용). 사용 가능한 수준은 모델에 따라 다릅니다. `/effort` 및 `effortLevel` 설정보다 우선합니다. [노력 수준 조정](/ko/model-config#adjust-effort-level) 참조 |92| `CLAUDE_CODE_EFFORT_LEVEL` | 지원되는 모델의 노력 수준을 설정합니다. 값: `low`, `medium`, `high`, `xhigh`, `max`, 또는 `auto`(모델 기본값 사용). 사용 가능한 수준은 모델에 따라 다릅니다. `/effort` 및 `effortLevel` 설정보다 우선합니다. [노력 수준 조정](/ko/model-config#adjust-effort-level) 참조 |

93| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | [세션 요약](/ko/interactive-mode#session-recap) 가용성을 재정의합니다. 재개를 강제로 끄려면 `0`으로 설정합니다. [`awaySummaryEnabled`](/ko/settings#available-settings)가 `false`일 때 재개를 강제로 켜려면 `1`로 설정합니다. 설정 및 `/config` 토글보다 우선합니다. |93| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | [세션 요약](/ko/interactive-mode#session-recap) 가용성을 재정의합니다. 재개를 강제로 끄려면 `0`으로 설정합니다. [`awaySummaryEnabled`](/ko/settings#available-settings)가 `false`일 때 재개를 강제로 켜려면 `1`로 설정합니다. 설정 및 `/config` 토글보다 우선합니다. |

94| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | [비대화형 모드](/ko/headless)에서 백그라운드 설치가 완료된 후 턴 경계에서 플러그인 상태를 새로 고치려면 `1`로 설정합니다. 새로 고침이 세션 중간에 시스템 프롬프트를 변경하여 해당 턴의 [프롬프트 캐싱](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)을 무효화하므로 기본적으로 꺼져 있습니다. |94| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | [비대화형 모드](/ko/headless)에서 백그라운드 설치가 완료된 후 턴 경계에서 플러그인 상태를 새로 고치려면 `1`로 설정합니다. 새로 고침이 세션 중간에 시스템 프롬프트를 변경하여 해당 턴의 [프롬프트 캐싱](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)을 무효화하므로 기본적으로 꺼져 있습니다. |

95| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 도구 호출 입력이 Claude가 생성할 때 API에서 스트리밍되는지 여부를 제어합니다. 이 없으면 파일 쓰기와 같은 큰 도구 입력이 Claude가 생성을 완료한 후에만 도착하므로 중단된 것처럼 보일 수 있습니다. 직접 Anthropic API 연결에 대해 기본적으로 활성화됩니다. 옵트아웃하려면 `0`으로 설정합니다. 서버 측 기본값이 꺼져 있을 때에도 강제로 활성화하려면 `1`로 설정합니다. Bedrock, Vertex, Foundry 또는 [게이트웨이](/ko/llm-gateway) 연결에는 효과가 없습니다. |95| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 도구 호출 입력이 Claude가 생성할 때 API에서 스트리밍되는지 여부를 제어합니다. 이 없으면 파일 쓰기와 같은 큰 도구 입력이 Claude가 생성을 완료한 후에만 도착하므로 중단된 것처럼 보일 수 있습니다. Anthropic API에 대해 기본적으로 활성화됩니다. Bedrock 및 Vertex에서는 배포된 컨테이너가 지원하는 모델별로 활성화됩니다. 옵트아웃하려면 `0`으로 설정합니다. `ANTHROPIC_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL` 또는 `ANTHROPIC_BEDROCK_BASE_URL`을 통해 프록시로 라우팅할 때 강제로 활성화하려면 `1`로 설정합니다. Foundry 및 [게이트웨이](/ko/llm-gateway) 연결에는 기본적으로 꺼져 있습니다. |

96| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `ANTHROPIC_BASE_URL`이 LiteLLM, Kong 또는 내부 프록시와 같은 Anthropic 호환 게이트웨이를 가리킬 때 게이트웨이의 `/v1/models` 엔드포인트에서 `/model` 선택기를 채우려면 `1`로 설정합니다. 공유 API 키로 지원되는 게이트웨이는 그렇지 않으면 모든 사용자에게 키가 액세스할 수 있는 모든 모델을 표시하므로 기본적으로 꺼져 있습니다. 검색된 모델은 여전히 [`availableModels`](/ko/settings#available-settings) 허용 목록으로 필터링됩니다. |96| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `ANTHROPIC_BASE_URL`이 LiteLLM, Kong 또는 내부 프록시와 같은 Anthropic 호환 게이트웨이를 가리킬 때 게이트웨이의 `/v1/models` 엔드포인트에서 `/model` 선택기를 채우려면 `1`로 설정합니다. 공유 API 키로 지원되는 게이트웨이는 그렇지 않으면 모든 사용자에게 키가 액세스할 수 있는 모든 모델을 표시하므로 기본적으로 꺼져 있습니다. 검색된 모델은 여전히 [`availableModels`](/ko/settings#available-settings) 허용 목록으로 필터링됩니다. |

97| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 프롬프트 제안을 비활성화하려면 `false`로 설정합니다(`/config`의 "프롬프트 제안" 토글). 이는 Claude가 응답한 후 프롬프트 입력에 나타나는 회색으로 표시된 예측입니다. [프롬프트 제안](/ko/interactive-mode#prompt-suggestions) 참조 |97| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 프롬프트 제안을 비활성화하려면 `false`로 설정합니다(`/config`의 "프롬프트 제안" 토글). 이는 Claude가 응답한 후 프롬프트 입력에 나타나는 회색으로 표시된 예측입니다. [프롬프트 제안](/ko/interactive-mode#prompt-suggestions) 참조 |

98| `CLAUDE_CODE_ENABLE_TASKS` | 비대화형 모드(`-p` 플래그)에서 작업 추적 시스템을 활성화하려면 `1`로 설정합니다. 작업은 대화형 모드에서 기본적으로 켜져 있습니다. [작업 목록](/ko/interactive-mode#task-list) 참조 |98| `CLAUDE_CODE_ENABLE_TASKS` | 비대화형 모드(`-p` 플래그)에서 작업 추적 시스템을 활성화하려면 `1`로 설정합니다. 작업은 대화형 모드에서 기본적으로 켜져 있습니다. [작업 목록](/ko/interactive-mode#task-list) 참조 |

164| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | PowerShell 도구를 제어합니다. Windows에서 Git Bash가 없으면 도구가 자동으로 활성화됩니다. `0`으로 설정하여 비활성화합니다. Windows에 Git Bash가 설치되어 있으면 도구가 점진적으로 롤아웃됩니다: 옵트인하려면 `1`로 설정하거나 옵트아웃하려면 `0`으로 설정합니다. Linux, macOS, WSL에서는 `1`로 설정하여 활성화합니다. PATH에 `pwsh`가 필요합니다. Windows에서 활성화되면 Claude는 Git Bash를 통해 라우팅하는 대신 PowerShell 명령을 기본적으로 실행할 수 있습니다. [PowerShell 도구](/ko/tools-reference#powershell-tool) 참조 |164| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | PowerShell 도구를 제어합니다. Windows에서 Git Bash가 없으면 도구가 자동으로 활성화됩니다. `0`으로 설정하여 비활성화합니다. Windows에 Git Bash가 설치되어 있으면 도구가 점진적으로 롤아웃됩니다: 옵트인하려면 `1`로 설정하거나 옵트아웃하려면 `0`으로 설정합니다. Linux, macOS, WSL에서는 `1`로 설정하여 활성화합니다. PATH에 `pwsh`가 필요합니다. Windows에서 활성화되면 Claude는 Git Bash를 통해 라우팅하는 대신 PowerShell 명령을 기본적으로 실행할 수 있습니다. [PowerShell 도구](/ko/tools-reference#powershell-tool) 참조 |

166| `CLAUDE_CONFIG_DIR` | 구성 디렉토리를 재정의합니다(기본값: `~/.claude`). 모든 설정, 자격 증명, 세션 기록 및 플러그인이 이 경로 아래에 저장됩니다. 여러 계정을 나란히 실행하는 데 유용합니다: 예를 들어 `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |166| `CLAUDE_CONFIG_DIR` | 구성 디렉토리를 재정의합니다(기본값: `~/.claude`). 모든 설정, 자격 증명, 세션 기록 및 플러그인이 이 경로 아래에 저장됩니다. 여러 계정을 나란히 실행하는 데 유용합니다: 예를 들어 `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |

167| `CLAUDE_EFFORT` | Bash 도구 subprocess 및 훅 명령에서 활성 [노력 수준](/ko/model-config#adjust-effort-level)으로 자동으로 설정됩니다: `low`, `medium`, `high`, `xhigh`, 또는 `max`. [훅](/ko/hooks)에 전달된 `effort.level` 필드와 일치합니다. 현재 모델이 노력 매개변수를 지원할 때만 설정됩니다. |

167| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 바이트 수준 스트리밍 유휴 감시견을 강제로 활성화하려면 `1`로 설정하거나, 강제로 비활성화하려면 `0`으로 설정합니다. 설정하지 않으면 감시견은 Anthropic API 연결에 대해 기본적으로 활성화됩니다. 바이트 감시견은 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 설정된 기간 동안 와이어에 바이트가 도착하지 않으면 연결을 중단합니다. 최소 5분이며 이벤트 수준 감시견과 독립적입니다. |168| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 바이트 수준 스트리밍 유휴 감시견을 강제로 활성화하려면 `1`로 설정하거나, 강제로 비활성화하려면 `0`으로 설정합니다. 설정하지 않으면 감시견은 Anthropic API 연결에 대해 기본적으로 활성화됩니다. 바이트 감시견은 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 설정된 기간 동안 와이어에 바이트가 도착하지 않으면 연결을 중단합니다. 최소 5분이며 이벤트 수준 감시견과 독립적입니다. |

168| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 이벤트 수준 스트리밍 유휴 감시견을 활성화하려면 `1`로 설정합니다. 기본적으로 꺼져 있습니다. Bedrock, Vertex, Foundry의 경우 이것이 유일한 유휴 감시견입니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 타임아웃을 구성합니다. |169| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 이벤트 수준 스트리밍 유휴 감시견을 활성화하려면 `1`로 설정합니다. 기본적으로 꺼져 있습니다. Bedrock, Vertex, Foundry의 경우 이것이 유일한 유휴 감시견입니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 타임아웃을 구성합니다. |

169| `CLAUDE_ENV_FILE` | Claude Code가 각 Bash 명령 전에 같은 셸 프로세스에서 실행하는 셸 스크립트의 경로이므로 파일의 내보내기가 명령에 표시됩니다. virtualenv 또는 conda 활성화를 명령 간에 유지하는 데 사용합니다. [SessionStart](/ko/hooks#persist-environment-variables), [Setup](/ko/hooks#setup), [CwdChanged](/ko/hooks#cwdchanged), [FileChanged](/ko/hooks#filechanged) 훅으로도 동적으로 채워집니다. |170| `CLAUDE_ENV_FILE` | Claude Code가 각 Bash 명령 전에 같은 셸 프로세스에서 실행하는 셸 스크립트의 경로이므로 파일의 내보내기가 명령에 표시됩니다. virtualenv 또는 conda 활성화를 명령 간에 유지하는 데 사용합니다. [SessionStart](/ko/hooks#persist-environment-variables), [Setup](/ko/hooks#setup), [CwdChanged](/ko/hooks#cwdchanged), [FileChanged](/ko/hooks#filechanged) 훅으로도 동적으로 채워집니다. |

204| `MAX_STRUCTURED_OUTPUT_RETRIES` | 비대화형 모드(`-p` 플래그)에서 모델의 응답이 [`--json-schema`](/ko/cli-reference#cli-flags)에 대한 유효성 검사에 실패할 때 재시도할 횟수입니다. 기본값은 5입니다. |205| `MAX_STRUCTURED_OUTPUT_RETRIES` | 비대화형 모드(`-p` 플래그)에서 모델의 응답이 [`--json-schema`](/ko/cli-reference#cli-flags)에 대한 유효성 검사에 실패할 때 재시도할 횟수입니다. 기본값은 5입니다. |

205| `MAX_THINKING_TOKENS` | [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) 토큰 예산을 재정의합니다. 상한은 모델의 [최대 출력 토큰](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)에서 1을 뺀 값입니다. 사고를 완전히 비활성화하려면 `0`으로 설정합니다. [적응형 추론](/ko/model-config#adjust-effort-level)이 있는 모델에서는 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`을 통해 적응형 추론이 비활성화되지 않으면 예산이 무시됩니다. |206| `MAX_THINKING_TOKENS` | [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) 토큰 예산을 재정의합니다. 상한은 모델의 [최대 출력 토큰](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)에서 1을 뺀 값입니다. 사고를 완전히 비활성화하려면 `0`으로 설정합니다. [적응형 추론](/ko/model-config#adjust-effort-level)이 있는 모델에서는 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`을 통해 적응형 추론이 비활성화되지 않으면 예산이 무시됩니다. |

206| `MCP_CLIENT_SECRET` | [사전 구성된 자격 증명](/ko/mcp#use-pre-configured-oauth-credentials)이 필요한 MCP 서버의 OAuth 클라이언트 시크릿입니다. `--client-secret`으로 서버를 추가할 때 대화형 프롬프트를 방지합니다. |207| `MCP_CLIENT_SECRET` | [사전 구성된 자격 증명](/ko/mcp#use-pre-configured-oauth-credentials)이 필요한 MCP 서버의 OAuth 클라이언트 시크릿입니다. `--client-secret`으로 서버를 추가할 때 대화형 프롬프트를 방지합니다. |

207| `MCP_CONNECTION_NONBLOCKING` | 비대화형 모드(`-p`)에서 MCP 연결 대기를 완전히 건너뛰려면 `true`로 설정합니다. MCP 도구가 필요하지 않은 스크립트 파이프라인에 유용합니다. 이 변수가 없으면 첫 번째 쿼리는 `--mcp-config` 서버 연결을 위해 최대 5초 동안 대기합니다. |208| `MCP_CONNECTION_NONBLOCKING` | 비대화형 모드(`-p`)에서 MCP 연결 대기를 완전히 건너뛰려면 `true`로 설정합니다. MCP 도구가 필요하지 않은 스크립트 파이프라인에 유용합니다. 이 변수가 없으면 첫 번째 쿼리는 `--mcp-config` 서버 연결을 위해 최대 5초 동안 대기합니다. [`alwaysLoad: true`](/ko/mcp#exempt-a-server-from-deferral)로 구성된 서버는 도구가 첫 번째 프롬프트를 빌드할 때 존재해야 하므로 이 변수와 관계없이 항상 시작을 차단합니다. |

209| `MCP_CONNECT_TIMEOUT_MS` | 첫 번째 쿼리가 MCP 연결 배치를 기다리는 시간(밀리초)을 설정하고 도구 목록을 스냅샷하기 전입니다(기본값: 5000). 마감 시점에 여전히 보류 중인 서버는 백그라운드에서 계속 연결되지만 다음 쿼리까지 나타나지 않습니다. `MCP_TIMEOUT`과 다르며, 이는 개별 서버의 연결 시도를 제한합니다. 단일 쿼리를 발급하고 느리게 연결되는 서버가 표시되어야 하는 비대화형 세션과 가장 관련이 있습니다. |

208| `MCP_OAUTH_CALLBACK_PORT` | [사전 구성된 자격 증명](/ko/mcp#use-pre-configured-oauth-credentials)으로 MCP 서버를 추가할 때 `--callback-port`의 대안으로 OAuth 리디렉션 콜백의 고정 포트입니다. |210| `MCP_OAUTH_CALLBACK_PORT` | [사전 구성된 자격 증명](/ko/mcp#use-pre-configured-oauth-credentials)으로 MCP 서버를 추가할 때 `--callback-port`의 대안으로 OAuth 리디렉션 콜백의 고정 포트입니다. |

features-overview.md +2 −2

Details

249 249

250 **컨텍스트 비용:** 사용할 때까지 낮음. 사용자 전용 skill은 호출할 때까지 0 비용입니다.250 **컨텍스트 비용:** 사용할 때까지 낮음. 사용자 전용 skill은 호출할 때까지 0 비용입니다.

251 251

252 **Subagent에서:** Skill은 subagent에서 다르게 작동합니다. 온디맨드 로딩 대신, subagent에 전달된 skill은 시작 시 컨텍스트에 완전히 미리 로드됩니다. Subagent는 주 세션에서 skill을 상속하지 않습니다. 명시적으로 지정해야 합니다.252 **Subagent에서:** Skill은 subagent에서 다르게 작동합니다. 온디맨드 로딩 대신, subagent의 `skills` 필드에 나열된 skill은 시작 시 컨텍스트에 완전히 미리 로드됩니다. Subagent는 여전히 Skill 도구를 통해 나열되지 않은 프로젝트, 사용자 및 플러그인 skill을 검색하고 호출할 수 있습니다.

253 253

254 <Tip>부작용이 있는 skill에 `disable-model-invocation: true`를 사용하세요. 이는 컨텍스트를 절약하고 오직 사용자만 트리거하도록 보장합니다.</Tip>254 <Tip>부작용이 있는 skill에 `disable-model-invocation: true`를 사용하세요. 이는 컨텍스트를 절약하고 오직 사용자만 트리거하도록 보장합니다.</Tip>

255 </Tab>255 </Tab>

284 <Tab title="Hooks">284 <Tab title="Hooks">

285 **시기:** 트리거 시. Hook은 도구 실행, 세션 경계, 프롬프트 제출, 권한 요청 및 압축과 같은 특정 라이프사이클 이벤트에서 실행됩니다. 전체 목록은 [Hooks](/ko/hooks)를 참조하세요.285 **시기:** 트리거 시. Hook은 도구 실행, 세션 경계, 프롬프트 제출, 권한 요청 및 압축과 같은 특정 라이프사이클 이벤트에서 실행됩니다. 전체 목록은 [Hooks](/ko/hooks)를 참조하세요.

286 286

287 **로드되는 내용:** 기본적으로 없음. Hook은 외부 스크립트로 실행됩니다.287 **로드되는 내용:** 기본적으로 없음. Hook은 외부에서 실행됩니다.

288 288

289 **컨텍스트 비용:** 0, hook이 대화에 메시지로 추가되는 출력을 반환하지 않는 한.289 **컨텍스트 비용:** 0, hook이 대화에 메시지로 추가되는 출력을 반환하지 않는 한.

290 290

google-vertex-ai.md +1 −111

Details

76 </div>;76 </div>;

77};77};

78 78

~~79export const Experiment = ({flag, treatment, children}) => {~~79<ContactSalesCard surface="vertex" />

~~80 const VID_KEY = 'exp_vid';~~

~~82 const fnv1a = s => {~~

~~83 let h = 0x811c9dc5;~~

~~84 for (let i = 0; i < s.length; i++) {~~

~~85 h ^= s.charCodeAt(i);~~

~~86 h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24);~~

~~87 }~~

~~88 return h >>> 0;~~

~~89 };~~

~~90 const bucket = (seed, vid) => fnv1a(fnv1a(seed + vid) + '') % 10000 < 5000 ? 'control' : 'treatment';~~

~~91 const [decision] = useState(() => {~~

~~92 const params = new URLSearchParams(location.search);~~

~~93 const preBucketed = document.documentElement.dataset['gb_' + flag.replace(/-/g, '_')];~~

~~94 const force = params.get('gb-force');~~

~~95 if (force) {~~

~~96 for (const p of force.split(',')) {~~

~~97 const [k, v] = p.split(':');~~

~~98 if (k === flag) return {~~

~~99 variant: v || 'treatment',~~

100 track: false

101 };

102 }

103 }

104 if (navigator.globalPrivacyControl) {

105 return {

106 variant: 'control',

107 track: false

108 };

109 }

110 const prefsMatch = document.cookie.match(/(?:^|; )anthropic-consent-preferences=([^;]+)/);

111 if (prefsMatch) {

112 try {

113 if (JSON.parse(decodeURIComponent(prefsMatch[1])).analytics !== true) {

114 return {

115 variant: 'control',

116 track: false

117 };

118 }

119 } catch {

120 return {

121 variant: 'control',

122 track: false

123 };

124 }

125 } else {

126 const country = params.get('country')?.toUpperCase() || (document.cookie.match(/(?:^|; )cf_geo=([A-Z]{2})/) || [])[1];

127 if (!country || CONSENT_COUNTRIES.has(country)) {

128 return {

129 variant: 'control',

130 track: false

131 };

132 }

133 }

134 let vid;

135 try {

136 const ajsMatch = document.cookie.match(/(?:^|; )ajs_anonymous_id=([^;]+)/);

137 if (ajsMatch) {

138 vid = decodeURIComponent(ajsMatch[1]).replace(/^"|"$/g, '');

139 } else {

140 vid = localStorage.getItem(VID_KEY);

141 if (!vid) {

142 vid = crypto.randomUUID();

143 }

144 document.cookie = `ajs_anonymous_id=${vid}; domain=.claude.com; path=/; Secure; SameSite=Lax; max-age=31536000`;

145 }

146 try {

147 localStorage.setItem(VID_KEY, vid);

148 } catch {}

149 } catch {

150 return {

151 variant: 'control',

152 track: false

153 };

154 }

155 const variant = preBucketed === '1' ? 'treatment' : preBucketed === '0' ? 'control' : bucket(flag, vid);

156 return {

157 variant,

158 track: true,

159 vid

160 };

161 });

162 useEffect(() => {

163 if (!decision.track) return;

164 fetch('https://api.anthropic.com/api/event_logging/v2/batch', {

165 method: 'POST',

166 headers: {

167 'Content-Type': 'application/json',

168 'x-service-name': 'claude_code_docs'

169 },

170 body: JSON.stringify({

171 events: [{

172 event_type: 'GrowthbookExperimentEvent',

173 event_data: {

174 device_id: decision.vid,

175 anonymous_id: decision.vid,

176 timestamp: new Date().toISOString(),

177 experiment_id: flag,

178 variation_id: decision.variant === 'treatment' ? 1 : 0,

179 environment: 'production'

180 }

181 }]

182 }),

183 keepalive: true

184 }).catch(() => {});

185 }, []);

186 return decision.variant === 'treatment' ? treatment : children;

187};

~~188~~

189<Experiment flag="docs-contact-sales-cta" treatment={<ContactSalesCard surface="vertex" />} />

190 80

191## 필수 요구사항81## 필수 요구사항

192 82

hooks.md +5 −4

Details

518Hook 이벤트는 각 [hook 이벤트](#hook-events) 섹션에서 문서화된 이벤트 특정 필드 외에 이러한 필드를 JSON으로 받습니다. 명령 hook의 경우 이 JSON은 stdin을 통해 도착합니다. HTTP hook의 경우 POST 요청 본문으로 도착합니다.518Hook 이벤트는 각 [hook 이벤트](#hook-events) 섹션에서 문서화된 이벤트 특정 필드 외에 이러한 필드를 JSON으로 받습니다. 명령 hook의 경우 이 JSON은 stdin을 통해 도착합니다. HTTP hook의 경우 POST 요청 본문으로 도착합니다.

519 519

520| 필드 | 설명 |520| 필드 | 설명 |

521| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |521| :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

524| `cwd` | hook이 호출될 때의 현재 작업 디렉토리 |524| `cwd` | hook이 호출될 때의 현재 작업 디렉토리 |

525| `permission_mode` | 현재 [권한 모드](/ko/permissions#permission-modes): `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` 또는 `"bypassPermissions"`. 모든 이벤트가 이 필드를 받는 것은 아닙니다: 각 이벤트의 JSON 예제를 확인하세요 |525| `permission_mode` | 현재 [권한 모드](/ko/permissions#permission-modes): `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` 또는 `"bypassPermissions"`. 모든 이벤트가 이 필드를 받는 것은 아닙니다: 각 이벤트의 JSON 예제를 확인하세요 |

526| `effort` | 활성 [노력 수준](/ko/model-config#adjust-effort-level)을 보유하는 `level` 필드가 있는 객체: `"low"`, `"medium"`, `"high"`, `"xhigh"` 또는 `"max"`. 요청된 노력이 현재 모델이 지원하는 것을 초과하면 이는 모델이 실제로 사용한 다운그레이드된 수준이며 요청한 수준이 아닙니다. 객체는 [상태 줄](/ko/statusline#available-data) `effort` 필드와 일치합니다. `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStop`과 같은 도구 사용 컨텍스트 내에서 발생하는 이벤트에 대해 현재 모델이 노력 매개변수를 지원할 때 존재합니다. 수준은 `$CLAUDE_EFFORT` 환경 변수로 hook 명령 및 Bash 도구에서도 사용 가능합니다. |

527 528

528`--agent`로 실행하거나 subagent 내부에서 실행할 때 두 개의 추가 필드가 포함됩니다:529`--agent`로 실행하거나 subagent 내부에서 실행할 때 두 개의 추가 필드가 포함됩니다:

1225 1226

1226연기된 도구가 재개할 때 더 이상 사용 가능하지 않으면 프로세스는 `stop_reason: "tool_deferred_unavailable"`과 `is_error: true`로 종료되고 hook이 발생하기 전에 종료됩니다. 이는 도구를 제공한 MCP 서버가 재개된 세션에 연결되지 않을 때 발생합니다. `deferred_tool_use` 페이로드는 여전히 포함되므로 어느 도구가 누락되었는지 식별할 수 있습니다.1227연기된 도구가 재개할 때 더 이상 사용 가능하지 않으면 프로세스는 `stop_reason: "tool_deferred_unavailable"`과 `is_error: true`로 종료되고 hook이 발생하기 전에 종료됩니다. 이는 도구를 제공한 MCP 서버가 재개된 세션에 연결되지 않을 때 발생합니다. `deferred_tool_use` 페이로드는 여전히 포함되므로 어느 도구가 누락되었는지 식별할 수 있습니다.

1227 1228

1228<Warning>1229<Note>

1229 `--resume`은 이전 세션의 권한 모드를 복원하지 않습니다. 도구가 연기되었을 때 활성화된 것과 동일한 `--permission-mode` 플래그를 재개할 때 전달합니다. Claude Code는 모드가 다르면 경고를 기록합니다.1230 `--resume`은 도구가 연기되었을 때 활성화된 권한 모드를 복원하므로 재개할 때 `--permission-mode`를 다시 전달할 필요가 없습니다. 예외는 `plan` 및 `bypassPermissions`이며, 이들은 절대 이월되지 않습니다. 재개할 때 `--permission-mode`를 명시적으로 전달하면 복원된 값을 재정의합니다.

1230</Warning>1231</Note>

1231 1232

1232### PermissionRequest1233### PermissionRequest

1233 1234

memory.md +8 −0

Details

132`src/billing/` 아래의 변경 사항에 대해 Plan Mode를 사용합니다.132`src/billing/` 아래의 변경 사항에 대해 Plan Mode를 사용합니다.

133```133```

134 134

135Windows에서 심볼릭 링크를 만들려면 관리자 권한 또는 개발자 모드가 필요하므로 대신 `@AGENTS.md` 가져오기를 사용합니다.

136

137```bash theme={null}

138ln -s AGENTS.md CLAUDE.md

139```

140

141이미 `AGENTS.md`가 있는 저장소에서 [`/init`](/ko/commands)을 실행하면 이를 읽고 관련 부분을 생성된 `CLAUDE.md`에 통합합니다. 또한 `.cursorrules` 및 `.windsurfrules`과 같은 다른 도구 구성을 읽습니다.

142

135### CLAUDE.md 파일이 로드되는 방식143### CLAUDE.md 파일이 로드되는 방식

136 144

137Claude Code는 현재 작업 디렉토리에서 디렉토리 트리를 따라 올라가며 CLAUDE.md 파일을 읽고 각 디렉토리를 확인합니다. 즉, `foo/bar/`에서 Claude Code를 실행하면 `foo/bar/CLAUDE.md`, `foo/CLAUDE.md` 및 그 옆의 모든 `CLAUDE.local.md` 파일에서 지침을 로드합니다.145Claude Code는 현재 작업 디렉토리에서 디렉토리 트리를 따라 올라가며 CLAUDE.md 파일을 읽고 각 디렉토리를 확인합니다. 즉, `foo/bar/`에서 Claude Code를 실행하면 `foo/bar/CLAUDE.md`, `foo/CLAUDE.md` 및 그 옆의 모든 `CLAUDE.local.md` 파일에서 지침을 로드합니다.

microsoft-foundry.md +1 −111

Details

76 </div>;76 </div>;

77};77};

78 78

~~79export const Experiment = ({flag, treatment, children}) => {~~79<ContactSalesCard surface="foundry" />

~~80 const VID_KEY = 'exp_vid';~~

~~82 const fnv1a = s => {~~

~~83 let h = 0x811c9dc5;~~

~~84 for (let i = 0; i < s.length; i++) {~~

~~85 h ^= s.charCodeAt(i);~~

~~86 h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24);~~

~~87 }~~

~~88 return h >>> 0;~~

~~89 };~~

~~90 const bucket = (seed, vid) => fnv1a(fnv1a(seed + vid) + '') % 10000 < 5000 ? 'control' : 'treatment';~~

~~91 const [decision] = useState(() => {~~

~~92 const params = new URLSearchParams(location.search);~~

~~93 const preBucketed = document.documentElement.dataset['gb_' + flag.replace(/-/g, '_')];~~

~~94 const force = params.get('gb-force');~~

~~95 if (force) {~~

~~96 for (const p of force.split(',')) {~~

~~97 const [k, v] = p.split(':');~~

~~98 if (k === flag) return {~~

~~99 variant: v || 'treatment',~~

100 track: false

101 };

102 }

103 }

104 if (navigator.globalPrivacyControl) {

105 return {

106 variant: 'control',

107 track: false

108 };

109 }

110 const prefsMatch = document.cookie.match(/(?:^|; )anthropic-consent-preferences=([^;]+)/);

111 if (prefsMatch) {

112 try {

113 if (JSON.parse(decodeURIComponent(prefsMatch[1])).analytics !== true) {

114 return {

115 variant: 'control',

116 track: false

117 };

118 }

119 } catch {

120 return {

121 variant: 'control',

122 track: false

123 };

124 }

125 } else {

126 const country = params.get('country')?.toUpperCase() || (document.cookie.match(/(?:^|; )cf_geo=([A-Z]{2})/) || [])[1];

127 if (!country || CONSENT_COUNTRIES.has(country)) {

128 return {

129 variant: 'control',

130 track: false

131 };

132 }

133 }

134 let vid;

135 try {

136 const ajsMatch = document.cookie.match(/(?:^|; )ajs_anonymous_id=([^;]+)/);

137 if (ajsMatch) {

138 vid = decodeURIComponent(ajsMatch[1]).replace(/^"|"$/g, '');

139 } else {

140 vid = localStorage.getItem(VID_KEY);

141 if (!vid) {

142 vid = crypto.randomUUID();

143 }

144 document.cookie = `ajs_anonymous_id=${vid}; domain=.claude.com; path=/; Secure; SameSite=Lax; max-age=31536000`;

145 }

146 try {

147 localStorage.setItem(VID_KEY, vid);

148 } catch {}

149 } catch {

150 return {

151 variant: 'control',

152 track: false

153 };

154 }

155 const variant = preBucketed === '1' ? 'treatment' : preBucketed === '0' ? 'control' : bucket(flag, vid);

156 return {

157 variant,

158 track: true,

159 vid

160 };

161 });

162 useEffect(() => {

163 if (!decision.track) return;

164 fetch('https://api.anthropic.com/api/event_logging/v2/batch', {

165 method: 'POST',

166 headers: {

167 'Content-Type': 'application/json',

168 'x-service-name': 'claude_code_docs'

169 },

170 body: JSON.stringify({

171 events: [{

172 event_type: 'GrowthbookExperimentEvent',

173 event_data: {

174 device_id: decision.vid,

175 anonymous_id: decision.vid,

176 timestamp: new Date().toISOString(),

177 experiment_id: flag,

178 variation_id: decision.variant === 'treatment' ? 1 : 0,

179 environment: 'production'

180 }

181 }]

182 }),

183 keepalive: true

184 }).catch(() => {});

185 }, []);

186 return decision.variant === 'treatment' ? treatment : children;

187};

~~188~~

189<Experiment flag="docs-contact-sales-cta" treatment={<ContactSalesCard surface="foundry" />} />

190 80

191## 필수 조건81## 필수 조건

192 82

model-config.md +13 −9

Details

17 * Foundry: 배포 이름17 * Foundry: 배포 이름

18 * Vertex: 버전 이름18 * Vertex: 버전 이름

19 19

20<Note>

21 `ANTHROPIC_BASE_URL`은 요청이 전송되는 위치를 변경하며, 어느 모델이 응답하는지는 변경하지 않습니다. Claude를 LLM 게이트웨이를 통해 라우팅하려면 [LLM 게이트웨이 구성](/ko/llm-gateway)을 참조하세요.

22</Note>

20### 모델 별칭24### 모델 별칭

21 25

22모델 별칭은 정확한 버전 번호를 기억할 필요 없이 모델 설정을 선택하는 편리한 방법을 제공합니다:26모델 별칭은 정확한 버전 번호를 기억할 필요 없이 모델 설정을 선택하는 편리한 방법을 제공합니다:

23 27

24| 모델 별칭 | 동작 |28| 모델 별칭 | 동작 |

~~25| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |~~29| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |

31| **`sonnet[1m]`** | 긴 세션을 위해 [100만 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/ko/build-with-claude/context-windows#1m-token-context-window)를 사용하는 Sonnet 사용 |35| **`sonnet[1m]`** | 긴 세션을 위해 [100만 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/ko/build-with-claude/context-windows#1m-token-context-window)를 사용하는 Sonnet을 사용합니다 |

32| **`opus[1m]`** | 긴 세션을 위해 [100만 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/ko/build-with-claude/context-windows#1m-token-context-window)를 사용하는 Opus 사용 |36| **`opus[1m]`** | 긴 세션을 위해 [100만 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/ko/build-with-claude/context-windows#1m-token-context-window)를 사용하는 Opus를 사용합니다 |

34 38

35Anthropic API에서 `opus`는 Opus 4.7로, `sonnet`은 Sonnet 4.6으로 확인됩니다. Bedrock, Vertex 및 Foundry에서 `opus`는 Opus 4.6으로, `sonnet`은 Sonnet 4.5로 확인됩니다. 더 새로운 모델은 전체 모델 이름을 명시적으로 선택하거나 `ANTHROPIC_DEFAULT_OPUS_MODEL` 또는 `ANTHROPIC_DEFAULT_SONNET_MODEL`을 설정하여 해당 제공자에서 사용할 수 있습니다.39Anthropic API에서 `opus`는 Opus 4.7로, `sonnet`은 Sonnet 4.6으로 확인됩니다. Bedrock, Vertex 및 Foundry에서 `opus`는 Opus 4.6으로, `sonnet`은 Sonnet 4.5로 확인됩니다. 더 새로운 모델은 전체 모델 이름을 명시적으로 선택하거나 `ANTHROPIC_DEFAULT_OPUS_MODEL` 또는 `ANTHROPIC_DEFAULT_SONNET_MODEL`을 설정하여 해당 제공자에서 사용할 수 있습니다.

36 40

45다음과 같은 여러 방법으로 모델을 구성할 수 있으며, 우선순위 순서대로 나열되어 있습니다:49다음과 같은 여러 방법으로 모델을 구성할 수 있으며, 우선순위 순서대로 나열되어 있습니다:

46 50

471. **세션 중** - `/model <alias|name>`을 사용하여 즉시 전환하거나, 인수 없이 `/model`을 실행하여 선택기를 엽니다. 선택기는 대화에 이전 출력이 있을 때 확인을 요청합니다. 다음 응답이 캐시된 컨텍스트 없이 전체 기록을 다시 읽기 때문입니다.511. **세션 중** - `/model <alias|name>`을 사용하여 즉시 전환하거나, 인수 없이 `/model`을 실행하여 선택기를 엽니다. 선택기는 대화에 이전 출력이 있을 때 확인을 요청합니다. 다음 응답이 캐시된 컨텍스트 없이 전체 기록을 다시 읽기 때문입니다.

~~482. **시작 시** - `claude --model <alias|name>`으로 실행~~522. **시작 시** - `claude --model <alias|name>`으로 실행합니다.

~~493. **환경 변수** - `ANTHROPIC_MODEL=<alias|name>` 설정~~533. **환경 변수** - `ANTHROPIC_MODEL=<alias|name>`을 설정합니다.

504. **설정** - `model` 필드를 사용하여 설정 파일에서 영구적으로 구성합니다.544. **설정** - `model` 필드를 사용하여 설정 파일에서 영구적으로 구성합니다.

51 55

52`/model` 선택은 사용자 설정에 저장되며 재시작 후에도 유지됩니다. v2.1.117부터 프로젝트의 `.claude/settings.json`이 다른 모델을 고정하는 경우, Claude Code는 선택 항목을 `.claude/settings.local.json`에도 작성하므로 재시작 후 해당 프로젝트에서 계속 적용됩니다. 관리되는 설정이 우선순위를 가지며 다음 실행 시 다시 적용됩니다.56`/model` 선택은 사용자 설정에 저장되며 재시작 후에도 유지됩니다. v2.1.117부터 프로젝트의 `.claude/settings.json`이 다른 모델을 고정하는 경우, Claude Code는 선택 항목을 `.claude/settings.local.json`에도 작성하므로 재시작 후 해당 프로젝트에서 계속 적용됩니다. 관리되는 설정이 우선순위를 가지며 다음 실행 시 다시 적용됩니다.

overview.md +1 −635

Details

6 6

7> Claude Code는 코드베이스를 읽고, 파일을 편집하고, 명령을 실행하고, 개발 도구와 통합하는 에이전트 코딩 도구입니다. 터미널, IDE, 데스크톱 앱 및 브라우저에서 사용할 수 있습니다.7> Claude Code는 코드베이스를 읽고, 파일을 편집하고, 명령을 실행하고, 개발 도구와 통합하는 에이전트 코딩 도구입니다. 터미널, IDE, 데스크톱 앱 및 브라우저에서 사용할 수 있습니다.

8 8

~~9export const InstallConfigurator = ({defaultSurface = 'terminal'}) => {~~

~~10 const TERM = {~~

~~11 mac: {~~

~~12 label: 'macOS / Linux',~~

~~13 cmd: 'curl -fsSL https://claude.ai/install.sh | bash'~~

~~14 },~~

~~15 win: {~~

~~16 label: 'Windows'~~

~~17 },~~

~~18 brew: {~~

~~19 label: 'Homebrew',~~

~~20 cmd: 'brew install --cask claude-code'~~

~~21 },~~

~~22 winget: {~~

~~23 label: 'WinGet',~~

~~24 cmd: 'winget install Anthropic.ClaudeCode'~~

~~25 }~~

~~26 };~~

~~27 const WIN_VARIANTS = {~~

~~28 ps: 'irm https://claude.ai/install.ps1 | iex',~~

~~29 cmd: 'curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd'~~

~~30 };~~

~~31 const TABS = [{~~

~~32 key: 'terminal',~~

~~33 label: 'Terminal'~~

~~34 }, {~~

~~35 key: 'desktop',~~

~~36 label: 'Desktop'~~

~~37 }, {~~

~~38 key: 'vscode',~~

~~39 label: 'VS Code'~~

~~40 }, {~~

~~41 key: 'jetbrains',~~

~~42 label: 'JetBrains'~~

~~43 }];~~

~~44 const ALT_TARGETS = {~~

~~45 desktop: {~~

~~46 name: 'Desktop',~~

~~47 tagline: 'The full agent in a native app for macOS and Windows.',~~

~~48 installLabel: 'Download the app',~~

~~49 installHref: 'https://claude.com/download?utm_source=claude_code&utm_medium=docs&utm_content=configurator_desktop_download',~~

~~50 guideHref: '/en/desktop-quickstart'~~

~~51 },~~

~~52 vscode: {~~

~~53 name: 'VS Code',~~

~~54 tagline: 'Review diffs, manage context, and chat without leaving your editor.',~~

~~55 installLabel: 'Install from Marketplace',~~

~~56 installHref: 'https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code',~~

~~57 altCmd: 'code --install-extension anthropic.claude-code',~~

~~58 guideHref: '/en/vs-code'~~

~~59 },~~

~~60 jetbrains: {~~

~~61 name: 'JetBrains',~~

~~62 tagline: 'Native plugin for IntelliJ, PyCharm, WebStorm, and other JetBrains IDEs.',~~

~~63 installLabel: 'Install from Marketplace',~~

~~64 installHref: 'https://plugins.jetbrains.com/plugin/27310-claude-code-beta-',~~

~~65 guideHref: '/en/jetbrains'~~

~~66 }~~

~~67 };~~

~~68 const PROVIDERS = [{~~

~~69 key: 'anthropic',~~

~~70 label: 'Anthropic'~~

~~71 }, {~~

~~72 key: 'bedrock',~~

~~73 label: 'Amazon Bedrock'~~

~~74 }, {~~

~~75 key: 'foundry',~~

~~76 label: 'Microsoft Foundry'~~

~~77 }, {~~

~~78 key: 'vertex',~~

~~79 label: 'Google Vertex AI'~~

~~80 }];~~

~~81 const PROVIDER_NOTICE = {~~

~~82 bedrock: <>~~

~~83 <strong>Configure your AWS account first.</strong> Running on Bedrock~~

~~84 requires model access enabled in the AWS console and IAM credentials.{' '}~~

~~85 <a href="/en/amazon-bedrock">Bedrock setup guide →</a>~~

~~86 </>,~~

~~87 vertex: <>~~

~~88 <strong>Configure your GCP project first.</strong> Running on Vertex AI~~

~~89 requires the Vertex API enabled and a service account with the right~~

~~90 permissions.{' '}~~

~~91 <a href="/en/google-vertex-ai">Vertex setup guide →</a>~~

~~92 </>,~~

~~93 foundry: <>~~

~~94 <strong>Configure your Azure resources first.</strong> Running on~~

~~95 Microsoft Foundry requires an Azure subscription with a Foundry resource~~

~~96 and model deployments provisioned.{' '}~~

~~97 <a href="/en/microsoft-foundry">Foundry setup guide →</a>~~

~~98 </>~~

~~99 };~~

100 const iconCheck = (size = 14) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="3" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

101 <polyline points="20 6 9 17 4 12" />

102 </svg>;

103 const iconCopy = (size = 14) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

104 <rect x="9" y="9" width="13" height="13" rx="2" />

105 <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />

106 </svg>;

107 const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

108 <line x1="5" y1="12" x2="19" y2="12" />

109 <polyline points="12 5 19 12 12 19" />

110 </svg>;

111 const iconArrowUpRight = (size = 14) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

112 <line x1="7" y1="17" x2="17" y2="7" />

113 <polyline points="7 7 17 7 17 17" />

114 </svg>;

115 const iconInfo = (size = 16) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

116 <circle cx="12" cy="12" r="10" />

117 <line x1="12" y1="16" x2="12" y2="12" />

118 <line x1="12" y1="8" x2="12.01" y2="8" />

119 </svg>;

120 const [target, setTarget] = useState(defaultSurface);

121 const [team, setTeam] = useState(false);

122 const [provider, setProvider] = useState('anthropic');

123 const [pkg, setPkg] = useState(() => (/Win/).test(navigator.userAgent) ? 'win' : 'mac');

124 const [winCmd, setWinCmd] = useState(false);

125 const [copied, setCopied] = useState(null);

126 const copyTimer = useRef(null);

127 const handleCopy = async (text, key) => {

128 try {

129 await navigator.clipboard.writeText(text);

130 } catch {

131 const ta = document.createElement('textarea');

132 ta.value = text;

133 document.body.appendChild(ta);

134 ta.select();

135 document.execCommand('copy');

136 document.body.removeChild(ta);

137 }

138 clearTimeout(copyTimer.current);

139 setCopied(key);

140 copyTimer.current = setTimeout(() => setCopied(null), 1800);

141 };

142 const cardBodyCmd = (cmd, prompt) => {

143 const on = copied === 'term';

144 return <div className="cc-ic-card-body">

145 <span className="cc-ic-prompt">{prompt || '$'}</span>

146 <div className="cc-ic-cmd">{cmd}</div>

147 <button type="button" className={'cc-ic-copy' + (on ? ' cc-ic-copied' : '')} onClick={() => handleCopy(cmd, 'term')}>

148 {on ? iconCheck(13) : iconCopy(13)}

149 <span>{on ? 'Copied' : 'Copy'}</span>

150 </button>

151 </div>;

152 };

153 const isWinInstaller = pkg === 'win';

154 const isWinPrompt = pkg === 'win' || pkg === 'winget';

155 const terminalCmd = isWinInstaller ? WIN_VARIANTS[winCmd ? 'cmd' : 'ps'] : TERM[pkg].cmd;

156 const alt = ALT_TARGETS[target];

157 const showNotice = team && provider !== 'anthropic';

158 const STYLES = `

159.cc-ic {

160 --ic-slate: #141413;

161 --ic-clay: #d97757;

162 --ic-clay-deep: #c6613f;

163 --ic-gray-000: #ffffff;

164 --ic-gray-150: #f0eee6;

165 --ic-gray-550: #73726c;

166 --ic-gray-700: #3d3d3a;

167 --ic-border-subtle: rgba(31, 30, 29, 0.08);

168 --ic-border-default: rgba(31, 30, 29, 0.15);

169 --ic-border-strong: rgba(31, 30, 29, 0.3);

170 --ic-font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, 'Courier New', monospace;

171 font-family: 'Anthropic Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;

172 font-size: 14px; line-height: 1.5; color: var(--ic-slate);

173 margin: 8px 0 32px;

174}

175.dark .cc-ic {

176 --ic-slate: #f0eee6;

177 --ic-gray-000: #262624;

178 --ic-gray-150: #1f1e1d;

179 --ic-gray-550: #91908a;

180 --ic-gray-700: #bfbdb4;

181 --ic-border-subtle: rgba(240, 238, 230, 0.08);

182 --ic-border-default: rgba(240, 238, 230, 0.14);

183 --ic-border-strong: rgba(240, 238, 230, 0.28);

184}

185.dark .cc-ic-check { background: transparent; }

186.dark .cc-ic-card { border: 0.5px solid var(--ic-border-subtle); }

187.dark .cc-ic-p-pill.cc-ic-active { box-shadow: 0 1px 2px rgba(0, 0, 0, 0.3); }

188.cc-ic *, .cc-ic *::before, .cc-ic *::after { box-sizing: border-box; }

189.cc-ic a { text-decoration: none; }

190.cc-ic a:not([class]) { color: inherit; }

191.cc-ic button { font-family: inherit; cursor: pointer; }

~~192~~

193.cc-ic-tab-strip {

194 display: inline-flex; gap: 2px;

195 padding: 4px; background: var(--ic-gray-150);

196 border-radius: 10px; overflow-x: auto;

197 max-width: 100%;

198}

199.cc-ic-tab {

200 appearance: none; background: none; border: none;

201 padding: 10px 18px; font-size: 15px; font-weight: 430;

202 color: var(--ic-gray-550); border-radius: 7px;

203 white-space: nowrap;

204 transition: color 0.12s, background-color 0.12s;

205}

206.cc-ic-tab:hover { color: var(--ic-gray-700); }

207.cc-ic-tab.cc-ic-active {

208 color: var(--ic-slate); font-weight: 500;

209 background: var(--ic-gray-000);

210 box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);

211}

212.dark .cc-ic-tab.cc-ic-active { box-shadow: 0 1px 3px rgba(0, 0, 0, 0.4); }

~~213~~

214.cc-ic-team-wrap { padding: 16px 0 20px; }

215.cc-ic-team-toggle {

216 display: flex; align-items: center; gap: 12px; font-family: inherit;

217 padding: 12px 16px; font-size: 14px; font-weight: 430;

218 color: var(--ic-gray-700); cursor: pointer; user-select: none;

219 width: fit-content; background: var(--ic-gray-150);

220 border: 0.5px solid var(--ic-border-subtle); border-radius: 8px;

221 transition: border-color 0.15s;

222}

223.cc-ic-team-toggle:hover { border-color: var(--ic-border-default); }

224.cc-ic-team-toggle.cc-ic-checked {

225 background: rgba(217, 119, 87, 0.08);

226 border-color: rgba(217, 119, 87, 0.25);

227}

228.cc-ic-check {

229 width: 16px; height: 16px;

230 border: 1px solid var(--ic-border-strong); border-radius: 4px;

231 background: var(--ic-gray-000);

232 display: flex; align-items: center; justify-content: center;

233 flex-shrink: 0;

234}

235.cc-ic-check svg { color: #fff; display: none; }

236.cc-ic-team-toggle.cc-ic-checked .cc-ic-check { background: var(--ic-clay-deep); border-color: var(--ic-clay-deep); }

237.cc-ic-team-toggle.cc-ic-checked .cc-ic-check svg { display: block; }

~~238~~

239.cc-ic-team-reveal { display: flex; flex-direction: column; gap: 12px; margin-bottom: 16px; }

240.cc-ic-sales {

241 display: flex; align-items: center; justify-content: space-between;

242 gap: 16px; padding: 14px 16px;

243 background: var(--ic-gray-000); border: 0.5px solid var(--ic-border-default);

244 border-radius: 8px; flex-wrap: wrap;

245}

246.cc-ic-sales-text { font-size: 13px; color: var(--ic-gray-700); line-height: 1.5; flex: 1; min-width: 200px; }

247.cc-ic-sales-text strong { font-weight: 550; color: var(--ic-slate); }

248.cc-ic-sales-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }

249.cc-ic-btn-clay {

250 display: inline-flex; align-items: center; gap: 8px;

251 background: var(--ic-clay-deep); color: #fff; border: none;

252 border-radius: 8px; padding: 8px 14px;

253 font-size: 13px; font-weight: 500;

254 transition: background-color 0.15s; white-space: nowrap;

255}

256.cc-ic-btn-clay:hover { background: var(--ic-clay); }

257.cc-ic-btn-ghost {

258 display: inline-flex; align-items: center; gap: 8px;

259 background: transparent; color: var(--ic-gray-700);

260 border: 0.5px solid var(--ic-border-default);

261 border-radius: 8px; padding: 8px 14px;

262 font-size: 13px; font-weight: 500;

263}

264.cc-ic-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }

~~265~~

266.cc-ic-provider-bar {

267 display: flex; align-items: center; gap: 12px;

268 padding: 14px 16px; background: var(--ic-gray-150);

269 border-radius: 8px; font-size: 13px; flex-wrap: wrap;

270}

271.cc-ic-provider-bar .cc-ic-label { color: var(--ic-gray-550); flex-shrink: 0; }

272.cc-ic-provider-pills { display: flex; gap: 4px; flex-wrap: wrap; }

273.cc-ic-p-pill {

274 appearance: none; border: none; background: transparent;

275 padding: 6px 12px; border-radius: 6px;

276 font-size: 13px; font-weight: 430; color: var(--ic-gray-700);

277 white-space: nowrap;

278}

279.cc-ic-p-pill:hover { background: rgba(0, 0, 0, 0.04); }

280.cc-ic-p-pill.cc-ic-active {

281 background: var(--ic-gray-000); color: var(--ic-slate);

282 font-weight: 500; box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);

283}

284.cc-ic-provider-notice {

285 display: flex; padding: 16px 18px;

286 background: var(--ic-gray-000); border: 0.5px solid var(--ic-border-default);

287 border-radius: 8px; gap: 14px; align-items: flex-start;

288}

289.cc-ic-provider-notice > svg { color: var(--ic-gray-550); margin-top: 2px; flex-shrink: 0; }

290.cc-ic-provider-notice-body { font-size: 14px; line-height: 1.55; color: var(--ic-gray-700); }

291.cc-ic-provider-notice-body strong { font-weight: 550; color: var(--ic-slate); }

292.cc-ic-provider-notice-body a { color: var(--ic-clay-deep); font-weight: 500; }

293.cc-ic-provider-notice-body a:hover { text-decoration: underline; }

~~294~~

295.cc-ic-card { background: #141413; border-radius: 12px; overflow: hidden; }

296.cc-ic-subtabs {

297 display: flex; align-items: center;

298 background: #1a1918;

299 border-bottom: 0.5px solid rgba(255, 255, 255, 0.08);

300 padding: 0 8px; overflow-x: auto;

301}

302.cc-ic-subtab {

303 appearance: none; background: none; border: none;

304 padding: 12px 16px; font-size: 12px;

305 color: rgba(255, 255, 255, 0.5);

306 position: relative; white-space: nowrap;

307}

308.cc-ic-subtab:hover { color: rgba(255, 255, 255, 0.75); }

309.cc-ic-subtab.cc-ic-active { color: #fff; }

310.cc-ic-subtab.cc-ic-active::after {

311 content: ''; position: absolute;

312 left: 12px; right: 12px; bottom: -0.5px;

313 height: 2px; background: var(--ic-clay);

314}

315.cc-ic-shell-switch {

316 display: inline-flex; gap: 2px;

317 margin: 14px 26px 0; padding: 3px;

318 background: rgba(255, 255, 255, 0.06);

319 border: 0.5px solid rgba(255, 255, 255, 0.08);

320 border-radius: 8px;

321 font-family: inherit;

322}

323.cc-ic-shell-option {

324 font: inherit; font-size: 12px; font-weight: 500;

325 padding: 5px 12px; border-radius: 6px;

326 background: transparent; border: none;

327 color: rgba(255, 255, 255, 0.55);

328 cursor: pointer; user-select: none; white-space: nowrap;

329 transition: color 120ms ease, background-color 120ms ease;

330}

331.cc-ic-shell-option:hover { color: rgba(255, 255, 255, 0.85); }

332.cc-ic-shell-option.cc-ic-active {

333 background: rgba(255, 255, 255, 0.12);

334 color: #fff;

335 box-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);

336}

~~337~~

338.cc-ic-card-body { padding: 24px 26px; display: flex; align-items: flex-start; gap: 14px; }

339.cc-ic-prompt {

340 color: var(--ic-clay); font-family: var(--ic-font-mono);

341 font-size: 17px; user-select: none; padding-top: 2px;

342}

343.cc-ic-cmd {

344 flex: 1; font-family: var(--ic-font-mono);

345 font-size: 17px; color: #f0eee6;

346 line-height: 1.55; white-space: pre-wrap; word-break: break-word;

347}

348.cc-ic-copy {

349 display: inline-flex; align-items: center; gap: 6px;

350 background: rgba(255, 255, 255, 0.08);

351 border: 0.5px solid rgba(255, 255, 255, 0.12);

352 color: rgba(255, 255, 255, 0.85);

353 padding: 7px 13px; border-radius: 8px;

354 font-size: 13px; font-weight: 500; flex-shrink: 0;

355}

356.cc-ic-copy:hover { background: rgba(255, 255, 255, 0.14); }

357.cc-ic-copy.cc-ic-copied { background: var(--ic-clay-deep); border-color: var(--ic-clay-deep); color: #fff; }

~~358~~

359.cc-ic-below {

360 margin-top: 12px; font-size: 13px; color: var(--ic-gray-550);

361 display: flex; gap: 16px; flex-wrap: wrap; align-items: baseline;

362}

363.cc-ic-below a { color: var(--ic-gray-700); border-bottom: 0.5px solid var(--ic-border-default); }

364.cc-ic-below a:hover { color: var(--ic-clay-deep); border-bottom-color: var(--ic-clay-deep); }

365.cc-ic-handoff {

366 padding: 22px 24px;

367 background: linear-gradient(180deg, #faf9f4 0%, #f3f1e9 100%);

368 border: 0.5px solid var(--ic-border-default);

369 border-radius: 12px;

370 box-shadow: 0 1px 2px rgba(31, 30, 29, 0.04), 0 6px 16px -4px rgba(31, 30, 29, 0.06);

371}

372.dark .cc-ic-handoff {

373 background: linear-gradient(180deg, #262624 0%, #1f1e1d 100%);

374 box-shadow: 0 1px 2px rgba(0, 0, 0, 0.3), 0 6px 16px -4px rgba(0, 0, 0, 0.4);

375}

376.cc-ic-handoff-title {

377 font-size: 16px; font-weight: 550; color: var(--ic-slate);

378 letter-spacing: -0.01em; margin-bottom: 4px;

379}

380.cc-ic-handoff-sub {

381 font-size: 14px; line-height: 1.5; color: var(--ic-gray-700);

382 margin-bottom: 18px;

383}

384.cc-ic-handoff-actions { display: flex; gap: 10px; flex-wrap: wrap; }

385.cc-ic-handoff-alt {

386 margin-top: 12px; font-size: 12px; color: var(--ic-gray-550);

387}

388.cc-ic-handoff-alt code {

389 font-family: var(--ic-font-mono); font-size: 11px;

390 background: var(--ic-gray-150); padding: 2px 6px;

391 border-radius: 4px; color: var(--ic-gray-700);

392}

393.cc-ic-copy-sm {

394 appearance: none; border: none;

395 display: inline-flex; align-items: center; justify-content: center;

396 width: 22px; height: 22px;

397 margin-left: 4px; vertical-align: middle;

398 background: var(--ic-gray-150); color: var(--ic-gray-550);

399 border-radius: 4px;

400 transition: color 0.1s, background-color 0.1s;

401}

402.cc-ic-copy-sm:hover { color: var(--ic-gray-700); background: var(--ic-border-default); }

403.cc-ic-copy-sm.cc-ic-copied { background: var(--ic-clay-deep); color: #fff; }

~~404~~

405@media (max-width: 720px) {

406 .cc-ic-tab { padding: 12px 14px; font-size: 14px; }

407 .cc-ic-sales-actions { width: 100%; }

408 .cc-ic-card-body { padding: 20px; }

409 .cc-ic-cmd { font-size: 15px; }

410}

411`;

412 return <div className="cc-ic not-prose">

413 <style>{STYLES}</style>

~~414~~

415 {}

416 <div className="cc-ic-tab-strip" role="tablist">

417 {TABS.map(t => <button key={t.key} type="button" role="tab" aria-selected={target === t.key} className={'cc-ic-tab' + (target === t.key ? ' cc-ic-active' : '')} onClick={() => setTarget(t.key)}>

418 {t.label}

419 </button>)}

420 </div>

~~421~~

422 {}

423 <div className="cc-ic-team-wrap">

424 <button type="button" role="switch" aria-checked={team} className={'cc-ic-team-toggle' + (team ? ' cc-ic-checked' : '')} onClick={() => setTeam(!team)}>

425 <span className="cc-ic-check">{iconCheck(11)}</span>

426 <span>

427 I’m buying for a team or company (SSO, AWS/Azure/GCP, central billing)

428 </span>

429 </button>

430 </div>

~~431~~

432 {}

433 {team && <div className="cc-ic-team-reveal">

434 <div className="cc-ic-sales">

435 <div className="cc-ic-sales-text">

436 <strong>Set up your team:</strong> self-serve or talk to sales.

437 </div>

438 <div className="cc-ic-sales-actions">

439 <a href="https://claude.ai/upgrade?initialPlanType=team&utm_source=claude_code&utm_medium=docs&utm_content=configurator_team_get_started" className="cc-ic-btn-ghost">

440 Get started

441 </a>

442 <a href="https://www.anthropic.com/contact-sales?utm_source=claude_code&utm_medium=docs&utm_content=configurator_team_contact_sales" className="cc-ic-btn-clay">

443 Contact sales {iconArrowRight()}

444 </a>

445 </div>

446 </div>

~~447~~

448 <div className="cc-ic-provider-bar">

449 <span className="cc-ic-label">Run on</span>

450 <div className="cc-ic-provider-pills" role="radiogroup" aria-label="Provider">

451 {PROVIDERS.map(p => <button key={p.key} type="button" role="radio" aria-checked={provider === p.key} className={'cc-ic-p-pill' + (provider === p.key ? ' cc-ic-active' : '')} onClick={() => setProvider(p.key)}>

452 {p.label}

453 </button>)}

454 </div>

455 </div>

~~456~~

457 {showNotice && <div className="cc-ic-provider-notice">

458 {iconInfo()}

459 <div className="cc-ic-provider-notice-body">

460 {PROVIDER_NOTICE[provider]}

461 </div>

462 </div>}

463 </div>}

~~464~~

465 {}

466 {target === 'terminal' && <div className="cc-ic-card">

467 <div className="cc-ic-subtabs" role="tablist" aria-label="Install method">

468 {Object.keys(TERM).map(k => <button key={k} type="button" role="tab" aria-selected={pkg === k} className={'cc-ic-subtab' + (pkg === k ? ' cc-ic-active' : '')} onClick={() => setPkg(k)}>

469 {TERM[k].label}

470 </button>)}

471 </div>

472 {isWinInstaller && <div className="cc-ic-shell-switch" role="tablist" aria-label="Shell">

473 {[{

474 k: 'ps',

475 label: 'PowerShell'

476 }, {

477 k: 'cmd',

478 label: 'CMD'

479 }].map(({k, label}) => {

480 const active = k === 'cmd' === winCmd;

481 return <button key={k} type="button" role="tab" aria-selected={active} className={'cc-ic-shell-option' + (active ? ' cc-ic-active' : '')} onClick={() => setWinCmd(k === 'cmd')}>

482 {label}

483 </button>;

484 })}

485 </div>}

486 {cardBodyCmd(terminalCmd, isWinPrompt ? '>' : '$')}

487 </div>}

~~488~~

489 {}

490 {target === 'terminal' && <div className="cc-ic-below">

491 {isWinInstaller && <span>

492 <a href="https://git-scm.com/downloads/win" target="_blank" rel="noopener">

493 Git for Windows

494 </a>{' '}

495 recommended. PowerShell is used if Git Bash is absent.

496 </span>}

497 {(pkg === 'brew' || pkg === 'winget') && <span>

498 Does not auto-update. Run{' '}

499 <code>{pkg === 'brew' ? 'brew upgrade claude-code' : 'winget upgrade Anthropic.ClaudeCode'}</code>{' '}

500 periodically.

501 </span>}

502 <a href="/en/troubleshoot-install">Installation troubleshooting</a>

503 </div>}

~~504~~

505 {alt && <div className="cc-ic-handoff">

506 <div className="cc-ic-handoff-title">Claude Code for {alt.name}</div>

507 <div className="cc-ic-handoff-sub">{alt.tagline}</div>

508 <div className="cc-ic-handoff-actions">

509 <a href={alt.installHref} className="cc-ic-btn-clay" {...alt.installHref.startsWith('http') ? {

510 target: '_blank',

511 rel: 'noopener'

512 } : {}}>

513 {alt.installLabel} {iconArrowUpRight(13)}

514 </a>

515 <a href={alt.guideHref} className="cc-ic-btn-ghost">

516 {alt.name} guide {iconArrowRight(12)}

517 </a>

518 </div>

519 {alt.altCmd && <div className="cc-ic-handoff-alt">

520 or run <code>{alt.altCmd}</code>

521 <button type="button" className={'cc-ic-copy-sm' + (copied === 'alt' ? ' cc-ic-copied' : '')} onClick={() => handleCopy(alt.altCmd, 'alt')} aria-label="Copy command">

522 {copied === 'alt' ? iconCheck(11) : iconCopy(11)}

523 </button>

524 </div>}

525 </div>}

526 </div>;

527};

~~528~~

529export const Experiment = ({flag, treatment, children}) => {

530 const VID_KEY = 'exp_vid';

531 const CONSENT_COUNTRIES = new Set(['AT', 'BE', 'BG', 'HR', 'CY', 'CZ', 'DK', 'EE', 'FI', 'FR', 'DE', 'GR', 'HU', 'IE', 'IT', 'LV', 'LT', 'LU', 'MT', 'NL', 'PL', 'PT', 'RO', 'SK', 'SI', 'ES', 'SE', 'RE', 'GP', 'MQ', 'GF', 'YT', 'BL', 'MF', 'PM', 'WF', 'PF', 'NC', 'AW', 'CW', 'SX', 'FO', 'GL', 'AX', 'GB', 'UK', 'AI', 'BM', 'IO', 'VG', 'KY', 'FK', 'GI', 'MS', 'PN', 'SH', 'TC', 'GG', 'JE', 'IM', 'CA', 'BR', 'IN']);

532 const fnv1a = s => {

533 let h = 0x811c9dc5;

534 for (let i = 0; i < s.length; i++) {

535 h ^= s.charCodeAt(i);

536 h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24);

537 }

538 return h >>> 0;

539 };

540 const bucket = (seed, vid) => fnv1a(fnv1a(seed + vid) + '') % 10000 < 5000 ? 'control' : 'treatment';

541 const [decision] = useState(() => {

542 const params = new URLSearchParams(location.search);

543 const preBucketed = document.documentElement.dataset['gb_' + flag.replace(/-/g, '_')];

544 const force = params.get('gb-force');

545 if (force) {

546 for (const p of force.split(',')) {

547 const [k, v] = p.split(':');

548 if (k === flag) return {

549 variant: v || 'treatment',

550 track: false

551 };

552 }

553 }

554 if (navigator.globalPrivacyControl) {

555 return {

556 variant: 'control',

557 track: false

558 };

559 }

560 const prefsMatch = document.cookie.match(/(?:^|; )anthropic-consent-preferences=([^;]+)/);

561 if (prefsMatch) {

562 try {

563 if (JSON.parse(decodeURIComponent(prefsMatch[1])).analytics !== true) {

564 return {

565 variant: 'control',

566 track: false

567 };

568 }

569 } catch {

570 return {

571 variant: 'control',

572 track: false

573 };

574 }

575 } else {

576 const country = params.get('country')?.toUpperCase() || (document.cookie.match(/(?:^|; )cf_geo=([A-Z]{2})/) || [])[1];

577 if (!country || CONSENT_COUNTRIES.has(country)) {

578 return {

579 variant: 'control',

580 track: false

581 };

582 }

583 }

584 let vid;

585 try {

586 const ajsMatch = document.cookie.match(/(?:^|; )ajs_anonymous_id=([^;]+)/);

587 if (ajsMatch) {

588 vid = decodeURIComponent(ajsMatch[1]).replace(/^"|"$/g, '');

589 } else {

590 vid = localStorage.getItem(VID_KEY);

591 if (!vid) {

592 vid = crypto.randomUUID();

593 }

594 document.cookie = `ajs_anonymous_id=${vid}; domain=.claude.com; path=/; Secure; SameSite=Lax; max-age=31536000`;

595 }

596 try {

597 localStorage.setItem(VID_KEY, vid);

598 } catch {}

599 } catch {

600 return {

601 variant: 'control',

602 track: false

603 };

604 }

605 const variant = preBucketed === '1' ? 'treatment' : preBucketed === '0' ? 'control' : bucket(flag, vid);

606 return {

607 variant,

608 track: true,

609 vid

610 };

611 });

612 useEffect(() => {

613 if (!decision.track) return;

614 fetch('https://api.anthropic.com/api/event_logging/v2/batch', {

615 method: 'POST',

616 headers: {

617 'Content-Type': 'application/json',

618 'x-service-name': 'claude_code_docs'

619 },

620 body: JSON.stringify({

621 events: [{

622 event_type: 'GrowthbookExperimentEvent',

623 event_data: {

624 device_id: decision.vid,

625 anonymous_id: decision.vid,

626 timestamp: new Date().toISOString(),

627 experiment_id: flag,

628 variation_id: decision.variant === 'treatment' ? 1 : 0,

629 environment: 'production'

630 }

631 }]

632 }),

633 keepalive: true

634 }).catch(() => {});

635 }, []);

636 return decision.variant === 'treatment' ? treatment : children;

637};

~~638~~

639Claude Code는 기능을 구축하고, 버그를 수정하고, 개발 작업을 자동화하는 데 도움이 되는 AI 기반 코딩 어시스턴트입니다. 전체 코드베이스를 이해하고 여러 파일과 도구에 걸쳐 작업할 수 있습니다.9Claude Code는 기능을 구축하고, 버그를 수정하고, 개발 작업을 자동화하는 데 도움이 되는 AI 기반 코딩 어시스턴트입니다. 전체 코드베이스를 이해하고 여러 파일과 도구에 걸쳐 작업할 수 있습니다.

640 10

641<div data-gb-slot="overview-install-configurator">

642 <Experiment flag="overview-install-configurator" treatment={<InstallConfigurator />} />

643</div>

~~644~~

645## 시작하기11## 시작하기

646 12

647환경을 선택하여 시작하세요. 대부분의 환경에는 [Claude 구독](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=overview_pricing) 또는 [Anthropic Console](https://console.anthropic.com/) 계정이 필요합니다. Terminal CLI 및 VS Code는 [타사 제공자](/ko/third-party-integrations)도 지원합니다.13환경을 선택하여 시작하세요. 대부분의 환경에는 [Claude 구독](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=overview_pricing) 또는 [Anthropic Console](https://console.anthropic.com/) 계정이 필요합니다. Terminal CLI 및 VS Code는 [타사 제공자](/ko/third-party-integrations)도 지원합니다.

798 <Accordion title="지침, skills 및 hooks로 사용자 정의" icon="sliders">164 <Accordion title="지침, skills 및 hooks로 사용자 정의" icon="sliders">

799 [`CLAUDE.md`](/ko/memory)는 프로젝트 루트에 추가하는 마크다운 파일로 Claude Code가 모든 세션의 시작 부분에서 읽습니다. 이를 사용하여 코딩 표준, 아키텍처 결정, 선호하는 라이브러리 및 검토 체크리스트를 설정합니다. Claude는 또한 작업할 때 [자동 메모리](/ko/memory#auto-memory)를 구축하여 빌드 명령 및 디버깅 인사이트와 같은 학습 내용을 저장하므로 아무것도 작성할 필요가 없습니다.165 [`CLAUDE.md`](/ko/memory)는 프로젝트 루트에 추가하는 마크다운 파일로 Claude Code가 모든 세션의 시작 부분에서 읽습니다. 이를 사용하여 코딩 표준, 아키텍처 결정, 선호하는 라이브러리 및 검토 체크리스트를 설정합니다. Claude는 또한 작업할 때 [자동 메모리](/ko/memory#auto-memory)를 구축하여 빌드 명령 및 디버깅 인사이트와 같은 학습 내용을 저장하므로 아무것도 작성할 필요가 없습니다.

800 166

801 [커스텀 명령](/ko/skills)을 생성하여 팀이 공유할 수 있는 반복 가능한 워크플로우를 패키징합니다(예: `/review-pr` 또는 `/deploy-staging`).167 [skills](/ko/skills)를 생성하여 팀이 공유할 수 있는 반복 가능한 워크플로우를 패키징합니다(예: `/review-pr` 또는 `/deploy-staging`).

802 168

803 [Hooks](/ko/hooks)를 사용하면 Claude Code 작업 전후에 셸 명령을 실행할 수 있습니다(예: 모든 파일 편집 후 자동 포맷팅 또는 커밋 전 lint 실행).169 [Hooks](/ko/hooks)를 사용하면 Claude Code 작업 전후에 셸 명령을 실행할 수 있습니다(예: 모든 파일 편집 후 자동 포맷팅 또는 커밋 전 lint 실행).

804 </Accordion>170 </Accordion>

plugins.md +9 −1

Details

317 317

318URL에서 호스팅되는 `.zip` 아카이브로 이미 패키징된 플러그인을 테스트하려면(예: CI 빌드 아티팩트) 대신 `--plugin-url`을 사용하세요. Claude Code는 시작 시 아카이브를 가져오고 해당 세션에만 로드합니다. 가져오기가 실패하거나 아카이브가 유효하지 않으면 Claude Code는 플러그인 로드 오류를 보고하고 이를 제외하고 시작합니다. 모든 플러그인 소스에 대해 동일한 [신뢰 고려 사항](/ko/discover-plugins#security)이 적용됩니다: 이 플래그를 제어하거나 신뢰하는 아카이브에만 지정하세요.318URL에서 호스팅되는 `.zip` 아카이브로 이미 패키징된 플러그인을 테스트하려면(예: CI 빌드 아티팩트) 대신 `--plugin-url`을 사용하세요. Claude Code는 시작 시 아카이브를 가져오고 해당 세션에만 로드합니다. 가져오기가 실패하거나 아카이브가 유효하지 않으면 Claude Code는 플러그인 로드 오류를 보고하고 이를 제외하고 시작합니다. 모든 플러그인 소스에 대해 동일한 [신뢰 고려 사항](/ko/discover-plugins#security)이 적용됩니다: 이 플래그를 제어하거나 신뢰하는 아카이브에만 지정하세요.

319 319

320여러 플러그인을 로드하려면 각 URL에 대해 플래그를 반복합니다:

321

322```bash theme={null}

323claude --plugin-url https://example.com/my-plugin.zip --plugin-url https://example.com/other.zip

324```

325

326또는 공백으로 구분된 URL을 하나의 따옴표로 묶인 인수로 전달합니다:

327

320```bash theme={null}328```bash theme={null}

321claude --plugin-url https://example.com/my-plugin.zip329claude --plugin-url "https://example.com/my-plugin.zip https://example.com/other.zip"

322```330```

323 331

324### 플러그인 문제 디버깅332### 플러그인 문제 디버깅

quickstart.md +3 −636

Details

6 6

7> Claude Code에 오신 것을 환영합니다!7> Claude Code에 오신 것을 환영합니다!

8 8

~~9export const InstallConfigurator = ({defaultSurface = 'terminal'}) => {~~

~~10 const TERM = {~~

~~11 mac: {~~

~~12 label: 'macOS / Linux',~~

~~13 cmd: 'curl -fsSL https://claude.ai/install.sh | bash'~~

~~14 },~~

~~15 win: {~~

~~16 label: 'Windows'~~

~~17 },~~

~~18 brew: {~~

~~19 label: 'Homebrew',~~

~~20 cmd: 'brew install --cask claude-code'~~

~~21 },~~

~~22 winget: {~~

~~23 label: 'WinGet',~~

~~24 cmd: 'winget install Anthropic.ClaudeCode'~~

~~25 }~~

~~26 };~~

~~27 const WIN_VARIANTS = {~~

~~28 ps: 'irm https://claude.ai/install.ps1 | iex',~~

~~29 cmd: 'curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd'~~

~~30 };~~

~~31 const TABS = [{~~

~~32 key: 'terminal',~~

~~33 label: 'Terminal'~~

~~34 }, {~~

~~35 key: 'desktop',~~

~~36 label: 'Desktop'~~

~~37 }, {~~

~~38 key: 'vscode',~~

~~39 label: 'VS Code'~~

~~40 }, {~~

~~41 key: 'jetbrains',~~

~~42 label: 'JetBrains'~~

~~43 }];~~

~~44 const ALT_TARGETS = {~~

~~45 desktop: {~~

~~46 name: 'Desktop',~~

~~47 tagline: 'The full agent in a native app for macOS and Windows.',~~

~~48 installLabel: 'Download the app',~~

~~49 installHref: 'https://claude.com/download?utm_source=claude_code&utm_medium=docs&utm_content=configurator_desktop_download',~~

~~50 guideHref: '/en/desktop-quickstart'~~

~~51 },~~

~~52 vscode: {~~

~~53 name: 'VS Code',~~

~~54 tagline: 'Review diffs, manage context, and chat without leaving your editor.',~~

~~55 installLabel: 'Install from Marketplace',~~

~~56 installHref: 'https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code',~~

~~57 altCmd: 'code --install-extension anthropic.claude-code',~~

~~58 guideHref: '/en/vs-code'~~

~~59 },~~

~~60 jetbrains: {~~

~~61 name: 'JetBrains',~~

~~62 tagline: 'Native plugin for IntelliJ, PyCharm, WebStorm, and other JetBrains IDEs.',~~

~~63 installLabel: 'Install from Marketplace',~~

~~64 installHref: 'https://plugins.jetbrains.com/plugin/27310-claude-code-beta-',~~

~~65 guideHref: '/en/jetbrains'~~

~~66 }~~

~~67 };~~

~~68 const PROVIDERS = [{~~

~~69 key: 'anthropic',~~

~~70 label: 'Anthropic'~~

~~71 }, {~~

~~72 key: 'bedrock',~~

~~73 label: 'Amazon Bedrock'~~

~~74 }, {~~

~~75 key: 'foundry',~~

~~76 label: 'Microsoft Foundry'~~

~~77 }, {~~

~~78 key: 'vertex',~~

~~79 label: 'Google Vertex AI'~~

~~80 }];~~

~~81 const PROVIDER_NOTICE = {~~

~~82 bedrock: <>~~

~~83 <strong>Configure your AWS account first.</strong> Running on Bedrock~~

~~84 requires model access enabled in the AWS console and IAM credentials.{' '}~~

~~85 <a href="/en/amazon-bedrock">Bedrock setup guide →</a>~~

~~86 </>,~~

~~87 vertex: <>~~

~~88 <strong>Configure your GCP project first.</strong> Running on Vertex AI~~

~~89 requires the Vertex API enabled and a service account with the right~~

~~90 permissions.{' '}~~

~~91 <a href="/en/google-vertex-ai">Vertex setup guide →</a>~~

~~92 </>,~~

~~93 foundry: <>~~

~~94 <strong>Configure your Azure resources first.</strong> Running on~~

~~95 Microsoft Foundry requires an Azure subscription with a Foundry resource~~

~~96 and model deployments provisioned.{' '}~~

~~97 <a href="/en/microsoft-foundry">Foundry setup guide →</a>~~

~~98 </>~~

~~99 };~~

101 <polyline points="20 6 9 17 4 12" />

102 </svg>;

104 <rect x="9" y="9" width="13" height="13" rx="2" />

105 <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />

106 </svg>;

108 <line x1="5" y1="12" x2="19" y2="12" />

109 <polyline points="12 5 19 12 12 19" />

110 </svg>;

112 <line x1="7" y1="17" x2="17" y2="7" />

113 <polyline points="7 7 17 7 17 17" />

114 </svg>;

116 <circle cx="12" cy="12" r="10" />

117 <line x1="12" y1="16" x2="12" y2="12" />

118 <line x1="12" y1="8" x2="12.01" y2="8" />

119 </svg>;

120 const [target, setTarget] = useState(defaultSurface);

121 const [team, setTeam] = useState(false);

122 const [provider, setProvider] = useState('anthropic');

123 const [pkg, setPkg] = useState(() => (/Win/).test(navigator.userAgent) ? 'win' : 'mac');

124 const [winCmd, setWinCmd] = useState(false);

125 const [copied, setCopied] = useState(null);

126 const copyTimer = useRef(null);

127 const handleCopy = async (text, key) => {

128 try {

129 await navigator.clipboard.writeText(text);

130 } catch {

131 const ta = document.createElement('textarea');

132 ta.value = text;

133 document.body.appendChild(ta);

134 ta.select();

135 document.execCommand('copy');

136 document.body.removeChild(ta);

137 }

138 clearTimeout(copyTimer.current);

139 setCopied(key);

140 copyTimer.current = setTimeout(() => setCopied(null), 1800);

141 };

142 const cardBodyCmd = (cmd, prompt) => {

143 const on = copied === 'term';

144 return <div className="cc-ic-card-body">

145 <span className="cc-ic-prompt">{prompt || '$'}</span>

146 <div className="cc-ic-cmd">{cmd}</div>

147 <button type="button" className={'cc-ic-copy' + (on ? ' cc-ic-copied' : '')} onClick={() => handleCopy(cmd, 'term')}>

148 {on ? iconCheck(13) : iconCopy(13)}

149 <span>{on ? 'Copied' : 'Copy'}</span>

150 </button>

151 </div>;

152 };

153 const isWinInstaller = pkg === 'win';

154 const isWinPrompt = pkg === 'win' || pkg === 'winget';

155 const terminalCmd = isWinInstaller ? WIN_VARIANTS[winCmd ? 'cmd' : 'ps'] : TERM[pkg].cmd;

156 const alt = ALT_TARGETS[target];

157 const showNotice = team && provider !== 'anthropic';

158 const STYLES = `

159.cc-ic {

160 --ic-slate: #141413;

161 --ic-clay: #d97757;

162 --ic-clay-deep: #c6613f;

163 --ic-gray-000: #ffffff;

164 --ic-gray-150: #f0eee6;

165 --ic-gray-550: #73726c;

166 --ic-gray-700: #3d3d3a;

167 --ic-border-subtle: rgba(31, 30, 29, 0.08);

168 --ic-border-default: rgba(31, 30, 29, 0.15);

169 --ic-border-strong: rgba(31, 30, 29, 0.3);

170 --ic-font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, 'Courier New', monospace;

171 font-family: 'Anthropic Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;

172 font-size: 14px; line-height: 1.5; color: var(--ic-slate);

173 margin: 8px 0 32px;

174}

175.dark .cc-ic {

176 --ic-slate: #f0eee6;

177 --ic-gray-000: #262624;

178 --ic-gray-150: #1f1e1d;

179 --ic-gray-550: #91908a;

180 --ic-gray-700: #bfbdb4;

181 --ic-border-subtle: rgba(240, 238, 230, 0.08);

182 --ic-border-default: rgba(240, 238, 230, 0.14);

183 --ic-border-strong: rgba(240, 238, 230, 0.28);

184}

185.dark .cc-ic-check { background: transparent; }

186.dark .cc-ic-card { border: 0.5px solid var(--ic-border-subtle); }

187.dark .cc-ic-p-pill.cc-ic-active { box-shadow: 0 1px 2px rgba(0, 0, 0, 0.3); }

188.cc-ic *, .cc-ic *::before, .cc-ic *::after { box-sizing: border-box; }

189.cc-ic a { text-decoration: none; }

190.cc-ic a:not([class]) { color: inherit; }

191.cc-ic button { font-family: inherit; cursor: pointer; }

~~192~~

193.cc-ic-tab-strip {

194 display: inline-flex; gap: 2px;

195 padding: 4px; background: var(--ic-gray-150);

196 border-radius: 10px; overflow-x: auto;

197 max-width: 100%;

198}

199.cc-ic-tab {

200 appearance: none; background: none; border: none;

201 padding: 10px 18px; font-size: 15px; font-weight: 430;

202 color: var(--ic-gray-550); border-radius: 7px;

203 white-space: nowrap;

204 transition: color 0.12s, background-color 0.12s;

205}

206.cc-ic-tab:hover { color: var(--ic-gray-700); }

207.cc-ic-tab.cc-ic-active {

208 color: var(--ic-slate); font-weight: 500;

209 background: var(--ic-gray-000);

210 box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);

211}

212.dark .cc-ic-tab.cc-ic-active { box-shadow: 0 1px 3px rgba(0, 0, 0, 0.4); }

~~213~~

214.cc-ic-team-wrap { padding: 16px 0 20px; }

215.cc-ic-team-toggle {

216 display: flex; align-items: center; gap: 12px; font-family: inherit;

217 padding: 12px 16px; font-size: 14px; font-weight: 430;

218 color: var(--ic-gray-700); cursor: pointer; user-select: none;

219 width: fit-content; background: var(--ic-gray-150);

220 border: 0.5px solid var(--ic-border-subtle); border-radius: 8px;

221 transition: border-color 0.15s;

222}

223.cc-ic-team-toggle:hover { border-color: var(--ic-border-default); }

224.cc-ic-team-toggle.cc-ic-checked {

225 background: rgba(217, 119, 87, 0.08);

226 border-color: rgba(217, 119, 87, 0.25);

227}

228.cc-ic-check {

229 width: 16px; height: 16px;

230 border: 1px solid var(--ic-border-strong); border-radius: 4px;

231 background: var(--ic-gray-000);

232 display: flex; align-items: center; justify-content: center;

233 flex-shrink: 0;

234}

235.cc-ic-check svg { color: #fff; display: none; }

236.cc-ic-team-toggle.cc-ic-checked .cc-ic-check { background: var(--ic-clay-deep); border-color: var(--ic-clay-deep); }

237.cc-ic-team-toggle.cc-ic-checked .cc-ic-check svg { display: block; }

~~238~~

239.cc-ic-team-reveal { display: flex; flex-direction: column; gap: 12px; margin-bottom: 16px; }

240.cc-ic-sales {

241 display: flex; align-items: center; justify-content: space-between;

242 gap: 16px; padding: 14px 16px;

243 background: var(--ic-gray-000); border: 0.5px solid var(--ic-border-default);

244 border-radius: 8px; flex-wrap: wrap;

245}

246.cc-ic-sales-text { font-size: 13px; color: var(--ic-gray-700); line-height: 1.5; flex: 1; min-width: 200px; }

247.cc-ic-sales-text strong { font-weight: 550; color: var(--ic-slate); }

248.cc-ic-sales-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }

249.cc-ic-btn-clay {

250 display: inline-flex; align-items: center; gap: 8px;

251 background: var(--ic-clay-deep); color: #fff; border: none;

252 border-radius: 8px; padding: 8px 14px;

253 font-size: 13px; font-weight: 500;

254 transition: background-color 0.15s; white-space: nowrap;

255}

256.cc-ic-btn-clay:hover { background: var(--ic-clay); }

257.cc-ic-btn-ghost {

258 display: inline-flex; align-items: center; gap: 8px;

259 background: transparent; color: var(--ic-gray-700);

260 border: 0.5px solid var(--ic-border-default);

261 border-radius: 8px; padding: 8px 14px;

262 font-size: 13px; font-weight: 500;

263}

264.cc-ic-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }

~~265~~

266.cc-ic-provider-bar {

267 display: flex; align-items: center; gap: 12px;

268 padding: 14px 16px; background: var(--ic-gray-150);

269 border-radius: 8px; font-size: 13px; flex-wrap: wrap;

270}

271.cc-ic-provider-bar .cc-ic-label { color: var(--ic-gray-550); flex-shrink: 0; }

272.cc-ic-provider-pills { display: flex; gap: 4px; flex-wrap: wrap; }

273.cc-ic-p-pill {

274 appearance: none; border: none; background: transparent;

275 padding: 6px 12px; border-radius: 6px;

276 font-size: 13px; font-weight: 430; color: var(--ic-gray-700);

277 white-space: nowrap;

278}

279.cc-ic-p-pill:hover { background: rgba(0, 0, 0, 0.04); }

280.cc-ic-p-pill.cc-ic-active {

281 background: var(--ic-gray-000); color: var(--ic-slate);

282 font-weight: 500; box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);

283}

284.cc-ic-provider-notice {

285 display: flex; padding: 16px 18px;

286 background: var(--ic-gray-000); border: 0.5px solid var(--ic-border-default);

287 border-radius: 8px; gap: 14px; align-items: flex-start;

288}

289.cc-ic-provider-notice > svg { color: var(--ic-gray-550); margin-top: 2px; flex-shrink: 0; }

290.cc-ic-provider-notice-body { font-size: 14px; line-height: 1.55; color: var(--ic-gray-700); }

291.cc-ic-provider-notice-body strong { font-weight: 550; color: var(--ic-slate); }

292.cc-ic-provider-notice-body a { color: var(--ic-clay-deep); font-weight: 500; }

293.cc-ic-provider-notice-body a:hover { text-decoration: underline; }

~~294~~

295.cc-ic-card { background: #141413; border-radius: 12px; overflow: hidden; }

296.cc-ic-subtabs {

297 display: flex; align-items: center;

298 background: #1a1918;

299 border-bottom: 0.5px solid rgba(255, 255, 255, 0.08);

300 padding: 0 8px; overflow-x: auto;

301}

302.cc-ic-subtab {

303 appearance: none; background: none; border: none;

304 padding: 12px 16px; font-size: 12px;

305 color: rgba(255, 255, 255, 0.5);

306 position: relative; white-space: nowrap;

307}

308.cc-ic-subtab:hover { color: rgba(255, 255, 255, 0.75); }

309.cc-ic-subtab.cc-ic-active { color: #fff; }

310.cc-ic-subtab.cc-ic-active::after {

311 content: ''; position: absolute;

312 left: 12px; right: 12px; bottom: -0.5px;

313 height: 2px; background: var(--ic-clay);

314}

315.cc-ic-shell-switch {

316 display: inline-flex; gap: 2px;

317 margin: 14px 26px 0; padding: 3px;

318 background: rgba(255, 255, 255, 0.06);

319 border: 0.5px solid rgba(255, 255, 255, 0.08);

320 border-radius: 8px;

321 font-family: inherit;

322}

323.cc-ic-shell-option {

324 font: inherit; font-size: 12px; font-weight: 500;

325 padding: 5px 12px; border-radius: 6px;

326 background: transparent; border: none;

327 color: rgba(255, 255, 255, 0.55);

328 cursor: pointer; user-select: none; white-space: nowrap;

329 transition: color 120ms ease, background-color 120ms ease;

330}

331.cc-ic-shell-option:hover { color: rgba(255, 255, 255, 0.85); }

332.cc-ic-shell-option.cc-ic-active {

333 background: rgba(255, 255, 255, 0.12);

334 color: #fff;

335 box-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);

336}

~~337~~

338.cc-ic-card-body { padding: 24px 26px; display: flex; align-items: flex-start; gap: 14px; }

339.cc-ic-prompt {

340 color: var(--ic-clay); font-family: var(--ic-font-mono);

341 font-size: 17px; user-select: none; padding-top: 2px;

342}

343.cc-ic-cmd {

344 flex: 1; font-family: var(--ic-font-mono);

345 font-size: 17px; color: #f0eee6;

346 line-height: 1.55; white-space: pre-wrap; word-break: break-word;

347}

348.cc-ic-copy {

349 display: inline-flex; align-items: center; gap: 6px;

350 background: rgba(255, 255, 255, 0.08);

351 border: 0.5px solid rgba(255, 255, 255, 0.12);

352 color: rgba(255, 255, 255, 0.85);

353 padding: 7px 13px; border-radius: 8px;

354 font-size: 13px; font-weight: 500; flex-shrink: 0;

355}

356.cc-ic-copy:hover { background: rgba(255, 255, 255, 0.14); }

357.cc-ic-copy.cc-ic-copied { background: var(--ic-clay-deep); border-color: var(--ic-clay-deep); color: #fff; }

~~358~~

359.cc-ic-below {

360 margin-top: 12px; font-size: 13px; color: var(--ic-gray-550);

361 display: flex; gap: 16px; flex-wrap: wrap; align-items: baseline;

362}

363.cc-ic-below a { color: var(--ic-gray-700); border-bottom: 0.5px solid var(--ic-border-default); }

364.cc-ic-below a:hover { color: var(--ic-clay-deep); border-bottom-color: var(--ic-clay-deep); }

365.cc-ic-handoff {

366 padding: 22px 24px;

367 background: linear-gradient(180deg, #faf9f4 0%, #f3f1e9 100%);

368 border: 0.5px solid var(--ic-border-default);

369 border-radius: 12px;

370 box-shadow: 0 1px 2px rgba(31, 30, 29, 0.04), 0 6px 16px -4px rgba(31, 30, 29, 0.06);

371}

372.dark .cc-ic-handoff {

373 background: linear-gradient(180deg, #262624 0%, #1f1e1d 100%);

374 box-shadow: 0 1px 2px rgba(0, 0, 0, 0.3), 0 6px 16px -4px rgba(0, 0, 0, 0.4);

375}

376.cc-ic-handoff-title {

377 font-size: 16px; font-weight: 550; color: var(--ic-slate);

378 letter-spacing: -0.01em; margin-bottom: 4px;

379}

380.cc-ic-handoff-sub {

381 font-size: 14px; line-height: 1.5; color: var(--ic-gray-700);

382 margin-bottom: 18px;

383}

384.cc-ic-handoff-actions { display: flex; gap: 10px; flex-wrap: wrap; }

385.cc-ic-handoff-alt {

386 margin-top: 12px; font-size: 12px; color: var(--ic-gray-550);

387}

388.cc-ic-handoff-alt code {

389 font-family: var(--ic-font-mono); font-size: 11px;

390 background: var(--ic-gray-150); padding: 2px 6px;

391 border-radius: 4px; color: var(--ic-gray-700);

392}

393.cc-ic-copy-sm {

394 appearance: none; border: none;

395 display: inline-flex; align-items: center; justify-content: center;

396 width: 22px; height: 22px;

397 margin-left: 4px; vertical-align: middle;

398 background: var(--ic-gray-150); color: var(--ic-gray-550);

399 border-radius: 4px;

400 transition: color 0.1s, background-color 0.1s;

401}

402.cc-ic-copy-sm:hover { color: var(--ic-gray-700); background: var(--ic-border-default); }

403.cc-ic-copy-sm.cc-ic-copied { background: var(--ic-clay-deep); color: #fff; }

~~404~~

405@media (max-width: 720px) {

406 .cc-ic-tab { padding: 12px 14px; font-size: 14px; }

407 .cc-ic-sales-actions { width: 100%; }

408 .cc-ic-card-body { padding: 20px; }

409 .cc-ic-cmd { font-size: 15px; }

410}

411`;

412 return <div className="cc-ic not-prose">

413 <style>{STYLES}</style>

~~414~~

415 {}

416 <div className="cc-ic-tab-strip" role="tablist">

418 {t.label}

419 </button>)}

420 </div>

~~421~~

422 {}

423 <div className="cc-ic-team-wrap">

424 <button type="button" role="switch" aria-checked={team} className={'cc-ic-team-toggle' + (team ? ' cc-ic-checked' : '')} onClick={() => setTeam(!team)}>

425 <span className="cc-ic-check">{iconCheck(11)}</span>

426 <span>

427 I’m buying for a team or company (SSO, AWS/Azure/GCP, central billing)

428 </span>

429 </button>

430 </div>

~~431~~

432 {}

433 {team && <div className="cc-ic-team-reveal">

434 <div className="cc-ic-sales">

435 <div className="cc-ic-sales-text">

436 <strong>Set up your team:</strong> self-serve or talk to sales.

437 </div>

438 <div className="cc-ic-sales-actions">

439 <a href="https://claude.ai/upgrade?initialPlanType=team&utm_source=claude_code&utm_medium=docs&utm_content=configurator_team_get_started" className="cc-ic-btn-ghost">

440 Get started

441 </a>

442 <a href="https://www.anthropic.com/contact-sales?utm_source=claude_code&utm_medium=docs&utm_content=configurator_team_contact_sales" className="cc-ic-btn-clay">

443 Contact sales {iconArrowRight()}

444 </a>

445 </div>

446 </div>

~~447~~

448 <div className="cc-ic-provider-bar">

449 <span className="cc-ic-label">Run on</span>

450 <div className="cc-ic-provider-pills" role="radiogroup" aria-label="Provider">

452 {p.label}

453 </button>)}

454 </div>

455 </div>

~~456~~

457 {showNotice && <div className="cc-ic-provider-notice">

458 {iconInfo()}

459 <div className="cc-ic-provider-notice-body">

460 {PROVIDER_NOTICE[provider]}

461 </div>

462 </div>}

463 </div>}

~~464~~

465 {}

466 {target === 'terminal' && <div className="cc-ic-card">

467 <div className="cc-ic-subtabs" role="tablist" aria-label="Install method">

468 {Object.keys(TERM).map(k => <button key={k} type="button" role="tab" aria-selected={pkg === k} className={'cc-ic-subtab' + (pkg === k ? ' cc-ic-active' : '')} onClick={() => setPkg(k)}>

469 {TERM[k].label}

470 </button>)}

471 </div>

472 {isWinInstaller && <div className="cc-ic-shell-switch" role="tablist" aria-label="Shell">

473 {[{

474 k: 'ps',

475 label: 'PowerShell'

476 }, {

477 k: 'cmd',

478 label: 'CMD'

479 }].map(({k, label}) => {

480 const active = k === 'cmd' === winCmd;

481 return <button key={k} type="button" role="tab" aria-selected={active} className={'cc-ic-shell-option' + (active ? ' cc-ic-active' : '')} onClick={() => setWinCmd(k === 'cmd')}>

482 {label}

483 </button>;

484 })}

485 </div>}

486 {cardBodyCmd(terminalCmd, isWinPrompt ? '>' : '$')}

487 </div>}

~~488~~

489 {}

490 {target === 'terminal' && <div className="cc-ic-below">

491 {isWinInstaller && <span>

492 <a href="https://git-scm.com/downloads/win" target="_blank" rel="noopener">

493 Git for Windows

494 </a>{' '}

495 recommended. PowerShell is used if Git Bash is absent.

496 </span>}

497 {(pkg === 'brew' || pkg === 'winget') && <span>

498 Does not auto-update. Run{' '}

499 <code>{pkg === 'brew' ? 'brew upgrade claude-code' : 'winget upgrade Anthropic.ClaudeCode'}</code>{' '}

500 periodically.

501 </span>}

502 <a href="/en/troubleshoot-install">Installation troubleshooting</a>

503 </div>}

~~504~~

505 {alt && <div className="cc-ic-handoff">

506 <div className="cc-ic-handoff-title">Claude Code for {alt.name}</div>

507 <div className="cc-ic-handoff-sub">{alt.tagline}</div>

508 <div className="cc-ic-handoff-actions">

509 <a href={alt.installHref} className="cc-ic-btn-clay" {...alt.installHref.startsWith('http') ? {

510 target: '_blank',

511 rel: 'noopener'

512 } : {}}>

513 {alt.installLabel} {iconArrowUpRight(13)}

514 </a>

515 <a href={alt.guideHref} className="cc-ic-btn-ghost">

516 {alt.name} guide {iconArrowRight(12)}

517 </a>

518 </div>

519 {alt.altCmd && <div className="cc-ic-handoff-alt">

520 or run <code>{alt.altCmd}</code>

521 <button type="button" className={'cc-ic-copy-sm' + (copied === 'alt' ? ' cc-ic-copied' : '')} onClick={() => handleCopy(alt.altCmd, 'alt')} aria-label="Copy command">

522 {copied === 'alt' ? iconCheck(11) : iconCopy(11)}

523 </button>

524 </div>}

525 </div>}

526 </div>;

527};

~~528~~

529export const Experiment = ({flag, treatment, children}) => {

530 const VID_KEY = 'exp_vid';

532 const fnv1a = s => {

533 let h = 0x811c9dc5;

534 for (let i = 0; i < s.length; i++) {

535 h ^= s.charCodeAt(i);

536 h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24);

537 }

538 return h >>> 0;

539 };

540 const bucket = (seed, vid) => fnv1a(fnv1a(seed + vid) + '') % 10000 < 5000 ? 'control' : 'treatment';

541 const [decision] = useState(() => {

542 const params = new URLSearchParams(location.search);

543 const preBucketed = document.documentElement.dataset['gb_' + flag.replace(/-/g, '_')];

544 const force = params.get('gb-force');

545 if (force) {

546 for (const p of force.split(',')) {

547 const [k, v] = p.split(':');

548 if (k === flag) return {

549 variant: v || 'treatment',

550 track: false

551 };

552 }

553 }

554 if (navigator.globalPrivacyControl) {

555 return {

556 variant: 'control',

557 track: false

558 };

559 }

560 const prefsMatch = document.cookie.match(/(?:^|; )anthropic-consent-preferences=([^;]+)/);

561 if (prefsMatch) {

562 try {

563 if (JSON.parse(decodeURIComponent(prefsMatch[1])).analytics !== true) {

564 return {

565 variant: 'control',

566 track: false

567 };

568 }

569 } catch {

570 return {

571 variant: 'control',

572 track: false

573 };

574 }

575 } else {

576 const country = params.get('country')?.toUpperCase() || (document.cookie.match(/(?:^|; )cf_geo=([A-Z]{2})/) || [])[1];

577 if (!country || CONSENT_COUNTRIES.has(country)) {

578 return {

579 variant: 'control',

580 track: false

581 };

582 }

583 }

584 let vid;

585 try {

586 const ajsMatch = document.cookie.match(/(?:^|; )ajs_anonymous_id=([^;]+)/);

587 if (ajsMatch) {

588 vid = decodeURIComponent(ajsMatch[1]).replace(/^"|"$/g, '');

589 } else {

590 vid = localStorage.getItem(VID_KEY);

591 if (!vid) {

592 vid = crypto.randomUUID();

593 }

594 document.cookie = `ajs_anonymous_id=${vid}; domain=.claude.com; path=/; Secure; SameSite=Lax; max-age=31536000`;

595 }

596 try {

597 localStorage.setItem(VID_KEY, vid);

598 } catch {}

599 } catch {

600 return {

601 variant: 'control',

602 track: false

603 };

604 }

605 const variant = preBucketed === '1' ? 'treatment' : preBucketed === '0' ? 'control' : bucket(flag, vid);

606 return {

607 variant,

608 track: true,

609 vid

610 };

611 });

612 useEffect(() => {

613 if (!decision.track) return;

614 fetch('https://api.anthropic.com/api/event_logging/v2/batch', {

615 method: 'POST',

616 headers: {

617 'Content-Type': 'application/json',

618 'x-service-name': 'claude_code_docs'

619 },

620 body: JSON.stringify({

621 events: [{

622 event_type: 'GrowthbookExperimentEvent',

623 event_data: {

624 device_id: decision.vid,

625 anonymous_id: decision.vid,

626 timestamp: new Date().toISOString(),

627 experiment_id: flag,

628 variation_id: decision.variant === 'treatment' ? 1 : 0,

629 environment: 'production'

630 }

631 }]

632 }),

633 keepalive: true

634 }).catch(() => {});

635 }, []);

636 return decision.variant === 'treatment' ? treatment : children;

637};

~~638~~

639이 빠른 시작 가이드를 통해 몇 분 안에 AI 기반 코딩 지원을 사용할 수 있습니다. 이 가이드를 마치면 일반적인 개발 작업에 Claude Code를 사용하는 방법을 이해하게 됩니다.9이 빠른 시작 가이드를 통해 몇 분 안에 AI 기반 코딩 지원을 사용할 수 있습니다. 이 가이드를 마치면 일반적인 개발 작업에 Claude Code를 사용하는 방법을 이해하게 됩니다.

640 10

641<Experiment flag="quickstart-install-configurator" treatment={<InstallConfigurator />} />

~~642~~

643## 시작하기 전에11## 시작하기 전에

644 12

645다음을 확인하십시오:13다음을 확인하십시오:

647* 열려 있는 터미널 또는 명령 프롬프트15* 열려 있는 터미널 또는 명령 프롬프트

648 * 터미널을 처음 사용하는 경우 [터미널 가이드](/ko/terminal-guide)를 확인하십시오16 * 터미널을 처음 사용하는 경우 [터미널 가이드](/ko/terminal-guide)를 확인하십시오

649* 작업할 코드 프로젝트17* 작업할 코드 프로젝트

650* [Claude 구독](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_prereq) (Pro, Max, Teams 또는 Enterprise), [Claude Console](https://console.anthropic.com/) 계정 또는 [지원되는 클라우드 제공자](/ko/third-party-integrations)를 통한 액세스18* [Claude 구독](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_prereq) (Pro, Max, Team 또는 Enterprise), [Claude Console](https://console.anthropic.com/) 계정 또는 [지원되는 클라우드 제공자](/ko/third-party-integrations)를 통한 액세스

651 19

652<Note>20<Note>

653 이 가이드는 터미널 CLI를 다룹니다. Claude Code는 [웹](https://claude.ai/code), [데스크톱 앱](/ko/desktop), [VS Code](/ko/vs-code) 및 [JetBrains IDE](/ko/jetbrains), [Slack](/ko/slack), [GitHub Actions](/ko/github-actions) 및 [GitLab](/ko/gitlab-ci-cd)의 CI/CD에서도 사용할 수 있습니다. [모든 인터페이스](/ko/overview#use-claude-code-everywhere)를 참조하십시오.21 이 가이드는 터미널 CLI를 다룹니다. Claude Code는 [웹](https://claude.ai/code), [데스크톱 앱](/ko/desktop), [VS Code](/ko/vs-code) 및 [JetBrains IDE](/ko/jetbrains), [Slack](/ko/slack), [GitHub Actions](/ko/github-actions) 및 [GitLab](/ko/gitlab-ci-cd)의 CI/CD에서도 사용할 수 있습니다. [모든 인터페이스](/ko/overview#use-claude-code-everywhere)를 참조하십시오.

727 95

728다음 계정 유형 중 하나를 사용하여 로그인할 수 있습니다:96다음 계정 유형 중 하나를 사용하여 로그인할 수 있습니다:

729 97

730* [Claude Pro, Max, Teams 또는 Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login) (권장)98* [Claude Pro, Max, Team 또는 Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login) (권장)

731* [Claude Console](https://console.anthropic.com/) (선불 크레딧이 있는 API 액세스). 처음 로그인할 때 비용 추적을 위해 Console에서 "Claude Code" 워크스페이스가 자동으로 생성됩니다.99* [Claude Console](https://console.anthropic.com/) (선불 크레딧이 있는 API 액세스). 처음 로그인할 때 비용 추적을 위해 Console에서 "Claude Code" 워크스페이스가 자동으로 생성됩니다.

732* [Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry](/ko/third-party-integrations) (엔터프라이즈 클라우드 제공자)100* [Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry](/ko/third-party-integrations) (엔터프라이즈 클라우드 제공자)

733 101

902| `claude commit` | Git 커밋 생성 | `claude commit` |

906 273

907전체 명령 목록은 [CLI 참조](/ko/cli-reference)를 참조하십시오.274전체 명령 목록은 [CLI 참조](/ko/cli-reference)를 참조하십시오.

908 275

settings.md +7 −3

Details

211| `modelOverrides` | Anthropic 모델 ID를 Bedrock 추론 프로필 ARN과 같은 공급자 특정 모델 ID로 매핑합니다. 각 모델 선택기 항목은 공급자 API를 호출할 때 매핑된 값을 사용합니다. [버전별 모델 ID 재정의](/ko/model-config#override-model-ids-per-version)를 참조하세요 | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |211| `modelOverrides` | Anthropic 모델 ID를 Bedrock 추론 프로필 ARN과 같은 공급자 특정 모델 ID로 매핑합니다. 각 모델 선택기 항목은 공급자 API를 호출할 때 매핑된 값을 사용합니다. [버전별 모델 ID 재정의](/ko/model-config#override-model-ids-per-version)를 참조하세요 | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |

212| `otelHeadersHelper` | 동적 OpenTelemetry 헤더를 생성하는 스크립트입니다. 시작 시 및 주기적으로 실행됩니다. [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/ko/env-vars)로 새로고침 간격을 설정합니다. [동적 헤더](/ko/monitoring-usage#dynamic-headers)를 참조하세요 | `/bin/generate_otel_headers.sh` |212| `otelHeadersHelper` | 동적 OpenTelemetry 헤더를 생성하는 스크립트입니다. 시작 시 및 주기적으로 실행됩니다. [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/ko/env-vars)로 새로고침 간격을 설정합니다. [동적 헤더](/ko/monitoring-usage#dynamic-headers)를 참조하세요 | `/bin/generate_otel_headers.sh` |

214| `parentSettingsBehavior` | {/* min-version: 2.1.133 */}(Managed 설정만) Agent SDK 또는 IDE 확장과 같은 embedding host 프로세스에 의해 프로그래밍 방식으로 제공되는 managed 설정이 관리자 배포 managed 계층도 있을 때 적용되는지 여부를 제어합니다. `"first-wins"`: 부모 제공 설정이 삭제되고 관리자 계층만 적용됩니다. `"merge"`: 부모 제공 설정이 관리자 계층 아래에 적용되며, 정책을 강화할 수 있지만 완화할 수 없도록 필터링됩니다. 관리자 계층이 배포되지 않으면 영향을 주지 않습니다. 기본값: `"first-wins"`. Claude Code v2.1.133 이상이 필요합니다 | `"merge"` |

216| `pluginTrustMessage` | (Managed 설정만) 설치 전에 표시되는 플러그인 신뢰 경고에 추가될 사용자 정의 메시지입니다. 이를 사용하여 조직 특정 컨텍스트를 추가합니다. 예를 들어 내부 마켓플레이스의 플러그인이 검증되었음을 확인합니다. | `"All plugins from our marketplace are approved by IT"` |217| `pluginTrustMessage` | (Managed 설정만) 설치 전에 표시되는 플러그인 신뢰 경고에 추가될 사용자 정의 메시지입니다. 이를 사용하여 조직 특정 컨텍스트를 추가합니다. 예를 들어 내부 마켓플레이스의 플러그인이 검증되었음을 확인합니다. | `"All plugins from our marketplace are approved by IT"` |

255 256

256### Worktree 설정257### Worktree 설정

257 258

258`--worktree`가 git worktrees를 생성하고 관리하는 방식을 구성합니다. 이러한 설정을 사용하여 대규모 monorepos에서 디스크 사용량 및 시작 시간을 줄입니다.259`--worktree`가 git worktrees를 생성하고 관리하는 방식을 구성합니다.

259 260

260| 키 | 설명 | 예제 |261| 키 | 설명 | 예제 |

261| :---------------------------- | :-------------------------------------------------------------------------------------------------------- | :------------------------------------ |262| :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |

263| `worktree.baseRef` | 새 worktrees가 분기하는 ref입니다. `"fresh"` (기본값)은 깨끗한 트리와 일치하는 원격에 대해 `origin/<default-branch>`에서 분기합니다. `"head"`는 현재 local `HEAD`에서 분기하므로 푸시되지 않은 커밋 및 feature-branch 상태가 worktree에 있습니다. `--worktree`, `EnterWorktree` 도구 및 subagent 격리에 적용됩니다 | `"head"` |

263| `worktree.sparsePaths` | git sparse-checkout (cone mode)을 통해 각 worktree에서 체크아웃할 디렉토리입니다. 나열된 경로만 디스크에 작성되므로 대규모 monorepos에서 더 빠릅니다 | `["packages/my-app", "shared/utils"]` |265| `worktree.sparsePaths` | git sparse-checkout (cone mode)을 통해 각 worktree에서 체크아웃할 디렉토리입니다. 나열된 경로만 디스크에 작성되므로 대규모 monorepos에서 더 빠릅니다 | `["packages/my-app", "shared/utils"]` |

264 266

318| `network.socksProxyPort` | 자신의 프록시를 가져오려는 경우 사용되는 SOCKS5 프록시 포트입니다. 지정되지 않으면 Claude가 자신의 프록시를 실행합니다. | `8081` |320| `network.socksProxyPort` | 자신의 프록시를 가져오려는 경우 사용되는 SOCKS5 프록시 포트입니다. 지정되지 않으면 Claude가 자신의 프록시를 실행합니다. | `8081` |

320| `enableWeakerNetworkIsolation` | (macOS만) 샌드박스에서 시스템 TLS 신뢰 서비스 (`com.apple.trustd.agent`)에 대한 액세스를 허용합니다. MITM 프록시 및 사용자 정의 CA를 사용하는 `httpProxyPort`를 사용할 때 `gh`, `gcloud` 및 `terraform`과 같은 Go 기반 도구가 TLS 인증서를 확인하는 데 필요합니다. **보안을 감소시킵니다** 잠재적 데이터 유출 경로를 열어서. 기본값: false | `true` |322| `enableWeakerNetworkIsolation` | (macOS만) 샌드박스에서 시스템 TLS 신뢰 서비스 (`com.apple.trustd.agent`)에 대한 액세스를 허용합니다. MITM 프록시 및 사용자 정의 CA를 사용하는 `httpProxyPort`를 사용할 때 `gh`, `gcloud` 및 `terraform`과 같은 Go 기반 도구가 TLS 인증서를 확인하는 데 필요합니다. **보안을 감소시킵니다** 잠재적 데이터 유출 경로를 열어서. 기본값: false | `true` |

323| `bwrapPath` | (Managed 설정만, Linux/WSL2) bubblewrap (`bwrap`) 바이너리의 절대 경로입니다. `PATH`를 통한 자동 감지를 재정의합니다. [managed 설정](/ko/settings#settings-files)에서만 적용되며 사용자 또는 프로젝트 설정에서는 적용되지 않습니다. `bwrap`이 managed 환경에서 비표준 위치에 설치된 경우 유용합니다. | `/opt/admin/bwrap` |

324| `socatPath` | (Managed 설정만, Linux/WSL2) 샌드박스 네트워크 프록시에 사용되는 `socat` 바이너리의 절대 경로입니다. `PATH`를 통한 자동 감지를 재정의합니다. Managed 설정에서만 적용됩니다. | `/opt/admin/socat` |

321 325

322#### Sandbox 경로 접두사326#### Sandbox 경로 접두사

323 327

448 452

449**HTTP hook URL 제한:**453**HTTP hook URL 제한:**

450 454

451HTTP hooks가 대상으로 할 수 있는 URL을 제한합니다. 일치를 위해 `*`를 와일드카드로 지원합니다. 배열이 정의되면 일치하지 않는 URL을 대상으로 하는 HTTP hooks는 자동으로 차단됩니다.455HTTP hooks가 대상으로 할 수 있는 URL을 제한합니다. 일치를 위해 `*`를 와일드카드로 지원합니다. 배열이 정의되면 일치하지 않는 URL을 대상으로 하는 HTTP hooks는 자동으로 차단됩니다. 호스트명 일치는 대소문자를 구분하지 않으며 후행 FQDN 점을 무시하여 DNS 의미론과 일치합니다.

452 456

453```json theme={null}457```json theme={null}

454{458{

setup.md +2 −0

Details

398 398

399지원되는 npm 설치 플랫폼은 `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64` 및 `win32-arm64`입니다. 패키지 관리자는 선택적 종속성을 허용해야 합니다. 설치 후 바이너리가 누락된 경우 [문제 해결](/ko/troubleshoot-install#native-binary-not-found-after-npm-install)을 참조하세요.399지원되는 npm 설치 플랫폼은 `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64` 및 `win32-arm64`입니다. 패키지 관리자는 선택적 종속성을 허용해야 합니다. 설치 후 바이너리가 누락된 경우 [문제 해결](/ko/troubleshoot-install#native-binary-not-found-after-npm-install)을 참조하세요.

400 400

401npm 설치를 업그레이드하려면 `npm install -g @anthropic-ai/claude-code@latest`를 실행하세요. `npm update -g`는 원래 설치의 semver 범위를 존중하며 최신 릴리스로 이동하지 않을 수 있으므로 피하세요.

402

401<Warning>403<Warning>

402 `sudo npm install -g`를 사용하지 마세요. 이는 권한 문제 및 보안 위험으로 이어질 수 있습니다. 권한 오류가 발생하면 [설치 중 권한 오류 문제 해결](/ko/troubleshoot-install#permission-errors-during-installation)을 참조하세요.404 `sudo npm install -g`를 사용하지 마세요. 이는 권한 문제 및 보안 위험으로 이어질 수 있습니다. 권한 오류가 발생하면 [설치 중 권한 오류 문제 해결](/ko/troubleshoot-install#permission-errors-during-installation)을 참조하세요.

403</Warning>405</Warning>

sub-agents.md +3 −3

Details

262| :---------------- | :-- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |262| :---------------- | :-- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

263| `name` | 예 | 소문자 및 하이픈을 사용한 고유 식별자 |263| `name` | 예 | 소문자 및 하이픈을 사용한 고유 식별자 |

264| `description` | 예 | Claude가 이 subagent에 위임해야 할 때 |264| `description` | 예 | Claude가 이 subagent에 위임해야 할 때 |

265| `tools` | 아니오 | Subagent가 사용할 수 있는 [도구](#available-tools). 생략하면 모든 도구 상속 |265| `tools` | 아니오 | Subagent가 사용할 수 있는 [도구](#available-tools). 생략하면 모든 도구 상속. Skills를 컨텍스트에 미리 로드하려면 여기에 `Skill`을 나열하는 대신 `skills` 필드를 사용합니다 |

266| `disallowedTools` | 아니오 | 거부할 도구, 상속되거나 지정된 목록에서 제거됨 |266| `disallowedTools` | 아니오 | 거부할 도구, 상속되거나 지정된 목록에서 제거됨 |

267| `model` | 아니오 | 사용할 [모델](#choose-a-model): `sonnet`, `opus`, `haiku`, 전체 모델 ID (예: `claude-opus-4-7`), 또는 `inherit`. 기본값: `inherit` |267| `model` | 아니오 | 사용할 [모델](#choose-a-model): `sonnet`, `opus`, `haiku`, 전체 모델 ID (예: `claude-opus-4-7`), 또는 `inherit`. 기본값: `inherit` |

268| `permissionMode` | 아니오 | [권한 모드](#permission-modes): `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, 또는 `plan`. [플러그인 subagent](#choose-the-subagent-scope)에서는 무시됨 |268| `permissionMode` | 아니오 | [권한 모드](#permission-modes): `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, 또는 `plan`. [플러그인 subagent](#choose-the-subagent-scope)에서는 무시됨 |

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

270| `skills` | 아니오 | 시작 시 subagent의 컨텍스트에 로드할 [Skills](/ko/skills). 호출 가능하게 만들어지는 것이 아니라 전체 skill 콘텐츠가 주입됩니다. Subagent는 부모 대화에서 skills를 상속하지 않습니다 |270| `skills` | 아니오 | 시작 시 subagent의 컨텍스트에 로드할 [Skills](/ko/skills). 전체 skill 콘텐츠가 주입되며, 호출 가능하게 만들어지는 것이 아닙니다. Subagent는 여전히 Skill 도구를 통해 나열되지 않은 프로젝트, 사용자, 플러그인 skills를 호출할 수 있습니다 |

271| `mcpServers` | 아니오 | 이 subagent에서 사용 가능한 [MCP servers](/ko/mcp). 각 항목은 이미 구성된 서버를 참조하는 서버 이름 (예: `"slack"`) 또는 서버 이름을 키로 하고 전체 [MCP server config](/ko/mcp#installing-mcp-servers)를 값으로 하는 인라인 정의입니다. [플러그인 subagent](#choose-the-subagent-scope)에서는 무시됨 |271| `mcpServers` | 아니오 | 이 subagent에서 사용 가능한 [MCP servers](/ko/mcp). 각 항목은 이미 구성된 서버를 참조하는 서버 이름 (예: `"slack"`) 또는 서버 이름을 키로 하고 전체 [MCP server config](/ko/mcp#installing-mcp-servers)를 값으로 하는 인라인 정의입니다. [플러그인 subagent](#choose-the-subagent-scope)에서는 무시됨 |

272| `hooks` | 아니오 | 이 subagent로 범위가 지정된 [라이프사이클 hooks](#define-hooks-for-subagents). [플러그인 subagent](#choose-the-subagent-scope)에서는 무시됨 |272| `hooks` | 아니오 | 이 subagent로 범위가 지정된 [라이프사이클 hooks](#define-hooks-for-subagents). [플러그인 subagent](#choose-the-subagent-scope)에서는 무시됨 |

273| `memory` | 아니오 | [지속적 메모리 범위](#enable-persistent-memory): `user`, `project`, 또는 `local`. 교차 세션 학습 활성화 |273| `memory` | 아니오 | [지속적 메모리 범위](#enable-persistent-memory): `user`, `project`, 또는 `local`. 교차 세션 학습 활성화 |

418Implement API endpoints. Follow the conventions and patterns from the preloaded skills.418Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

419```419```

420 420

421각 skill의 전체 콘텐츠가 subagent의 컨텍스트에 주입되며, 호출 가능하게 만들어지는 것이 아닙니다. Subagent는 부모 대화에서 skills를 상속하지 않으므로 명시적으로 나열해야 합니다.421각 skill의 전체 콘텐츠가 subagent의 컨텍스트에 주입됩니다. 이 필드는 어떤 skills를 미리 로드할지 제어하며, subagent가 액세스할 수 있는 skills를 제어하지 않습니다: 이 필드가 없으면 subagent는 여전히 실행 중에 Skill 도구를 통해 프로젝트, 사용자, 플러그인 skills를 검색하고 호출할 수 있습니다. Subagent가 skills를 완전히 호출하지 못하도록 방지하려면 [`tools`](#available-tools) 목록에서 `Skill`을 생략하거나 `disallowedTools`에 추가합니다.

422 422

423`disable-model-invocation: true`를 설정하는 skills는 미리 로드할 수 없습니다. 미리 로드는 Claude가 호출할 수 있는 동일한 skills 세트에서 가져오기 때문입니다. 나열된 skill이 누락되었거나 비활성화된 경우 Claude Code는 이를 건너뛰고 디버그 로그에 경고를 기록합니다.423`disable-model-invocation: true`를 설정하는 skills는 미리 로드할 수 없습니다. 미리 로드는 Claude가 호출할 수 있는 동일한 skills 세트에서 가져오기 때문입니다. 나열된 skill이 누락되었거나 비활성화된 경우 Claude Code는 이를 건너뛰고 디버그 로그에 경고를 기록합니다.

424 424

terminal-config.md +1 −1

Details

107set -as terminal-features 'xterm*:extkeys'107set -as terminal-features 'xterm*:extkeys'

108```108```

109 109

110`allow-passthrough` 줄은 알림 및 진행률 업데이트가 tmux에 의해 삼켜지는 대신 iTerm2, Ghostty 또는 Kitty에 도달하도록 합니다. `extended-keys` 줄은 tmux가 Shift+Enter를 일반 Enter와 구별하도록 하여 줄 바꿈 단축키가 작동하도록 합니다.110`allow-passthrough` 줄은 알림 및 진행률 업데이트가 tmux에 의해 삼켜지는 대신 외부 터미널에 도달하도록 합니다. `extended-keys` 줄은 tmux가 Shift+Enter를 일반 Enter와 구별하도록 하여 줄 바꿈 단축키가 작동하도록 합니다.

111 111

112## 색상 테마 일치112## 색상 테마 일치

113 113

third-party-integrations.md +73 −1

Details

6 6

7> Claude Code가 다양한 타사 서비스 및 인프라와 통합되어 엔터프라이즈 배포 요구사항을 충족하는 방법을 알아봅니다.7> Claude Code가 다양한 타사 서비스 및 인프라와 통합되어 엔터프라이즈 배포 요구사항을 충족하는 방법을 알아봅니다.

8 8

9export const ContactSalesCard = ({surface}) => {

10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;

11 const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

12 <line x1="5" y1="12" x2="19" y2="12" />

13 <polyline points="12 5 19 12 12 19" />

14 </svg>;

15 const STYLES = `

16.cc-cs {

17 --cs-slate: #141413;

18 --cs-clay: #d97757;

19 --cs-clay-deep: #c6613f;

20 --cs-gray-000: #ffffff;

21 --cs-gray-700: #3d3d3a;

22 --cs-border-default: rgba(31, 30, 29, 0.15);

23 font-family: inherit;

24}

25.dark .cc-cs {

26 --cs-slate: #f0eee6;

27 --cs-gray-000: #262624;

28 --cs-gray-700: #bfbdb4;

29 --cs-border-default: rgba(240, 238, 230, 0.14);

30}

31.cc-cs-card {

32 display: flex; align-items: center; justify-content: space-between;

33 gap: 16px; padding: 14px 16px; margin: 0;

34 background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default);

35 border-radius: 8px; flex-wrap: wrap;

36}

37.cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; }

38.cc-cs-text strong { font-weight: 550; color: var(--cs-slate); }

39.cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }

40.cc-cs-btn-clay {

41 display: inline-flex; align-items: center; gap: 8px;

42 background: var(--cs-clay-deep); color: #fff; border: none;

43 border-radius: 8px; padding: 8px 14px;

44 font-size: 13px; font-weight: 500;

45 transition: background-color 0.15s; white-space: nowrap;

46}

47.cc-cs-btn-clay:hover { background: var(--cs-clay); }

48.cc-cs-btn-ghost {

49 display: inline-flex; align-items: center; gap: 8px;

50 background: transparent; color: var(--cs-gray-700);

51 border: 0.5px solid var(--cs-border-default);

52 border-radius: 8px; padding: 8px 14px;

53 font-size: 13px; font-weight: 500;

54}

55.cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }

56.dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); }

57@media (max-width: 720px) {

58 .cc-cs-actions { width: 100%; }

59}

60`;

61 return <div className="cc-cs not-prose">

62 <style>{STYLES}</style>

63 <div className="cc-cs-card">

64 <div className="cc-cs-text">

65 <strong>Deploying Claude Code across your organization?</strong> Talk to sales about enterprise plans, SSO, and centralized billing.

66 </div>

67 <div className="cc-cs-actions">

68 <a href={`https://claude.com/pricing?${utm('view_plans')}#plans-business`} className="cc-cs-btn-ghost">

69 View plans

70 </a>

71 <a href={`https://claude.com/contact-sales?${utm('contact_sales')}`} className="cc-cs-btn-clay">

72 Contact sales {iconArrowRight()}

73 </a>

74 </div>

75 </div>

76 </div>;

77};

9조직은 Anthropic을 통해 직접 또는 클라우드 제공자를 통해 Claude Code를 배포할 수 있습니다. 이 페이지는 올바른 구성을 선택하는 데 도움을 줍니다.79조직은 Anthropic을 통해 직접 또는 클라우드 제공자를 통해 Claude Code를 배포할 수 있습니다. 이 페이지는 올바른 구성을 선택하는 데 도움을 줍니다.

10 80

81<ContactSalesCard surface="third_party_overview" />

11## 배포 옵션 비교83## 배포 옵션 비교

12 84

13대부분의 조직에서는 Claude for Teams 또는 Claude for Enterprise가 최고의 경험을 제공합니다. 팀 멤버는 단일 구독으로 Claude Code와 웹의 Claude에 모두 액세스할 수 있으며, 중앙 집중식 청구 및 인프라 설정이 필요하지 않습니다.85대부분의 조직에서는 Claude for Teams 또는 Claude for Enterprise가 최고의 경험을 제공합니다. 팀 멤버는 단일 구독으로 Claude Code와 웹의 Claude에 모두 액세스할 수 있으며, 중앙 집중식 청구 및 인프라 설정이 필요하지 않습니다.

241 313

242### 클라우드 제공자를 위한 모델 버전 고정314### 클라우드 제공자를 위한 모델 버전 고정

243 315

244[Bedrock](/ko/amazon-bedrock), [Vertex AI](/ko/google-vertex-ai) 또는 [Foundry](/ko/microsoft-foundry)를 통해 배포하는 경우 `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL` 및 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 사용하여 특정 모델 버전을 고정합니다. 고정하지 않으면 Claude Code 별칭이 최신 버전으로 확인되어 Anthropic이 아직 계정에서 활성화되지 않은 새 모델을 출시할 때 사용자가 손상될 수 있습니다. 자세한 내용은 [모델 구성](/ko/model-config#pin-models-for-third-party-deployments)을 참조하십시오.316[Bedrock](/ko/amazon-bedrock), [Vertex AI](/ko/google-vertex-ai) 또는 [Foundry](/ko/microsoft-foundry)를 통해 배포하는 경우 `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL` 및 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 사용하여 특정 모델 버전을 고정합니다. 고정하지 않으면 모델 별칭이 최신 버전으로 확인되어 Anthropic이 아직 계정에서 활성화되지 않은 새 모델을 출시할 때 사용자가 손상될 수 있습니다. 각 제공자가 최신 버전을 사용할 수 없을 때 수행하는 작업에 대해서는 [모델 구성](/ko/model-config#pin-models-for-third-party-deployments)을 참조하십시오.

245 317

246### 보안 정책 구성318### 보안 정책 구성

247 319

vs-code.md +3 −1

Details

32 32

33또는 VS Code에서 `Cmd+Shift+X`(Mac) 또는 `Ctrl+Shift+X`(Windows/Linux)를 눌러 확장 프로그램 보기를 열고, "Claude Code"를 검색한 후 **설치**를 클릭합니다.33또는 VS Code에서 `Cmd+Shift+X`(Mac) 또는 `Ctrl+Shift+X`(Windows/Linux)를 눌러 확장 프로그램 보기를 열고, "Claude Code"를 검색한 후 **설치**를 클릭합니다.

34 34

35확장 프로그램은 Windsurf 또는 Kiro와 같은 다른 VS Code 포크에도 설치됩니다. 편집기의 확장 프로그램 보기에서 "Claude Code"를 검색하거나 [Open VSX 레지스트리](https://open-vsx.org/extension/Anthropic/claude-code)에서 설치합니다. 편집기에서 확장 프로그램을 설치할 수 없는 경우 통합 터미널에서 `claude`를 실행합니다. [CLI](/ko/quickstart)는 모든 터미널에서 작동합니다.

35<Note>설치 후 확장 프로그램이 나타나지 않으면 VS Code를 다시 시작하거나 명령 팔레트에서 "Developer: Reload Window"를 실행합니다.</Note>37<Note>설치 후 확장 프로그램이 나타나지 않으면 VS Code를 다시 시작하거나 명령 팔레트에서 "Developer: Reload Window"를 실행합니다.</Note>

36 38

37## 시작하기39## 시작하기

318| `environmentVariables` | `[]` | Claude 프로세스에 대한 환경 변수 설정. 공유 구성을 위해 Claude Code 설정을 대신 사용합니다. |320| `environmentVariables` | `[]` | Claude 프로세스에 대한 환경 변수 설정. 공유 구성을 위해 Claude Code 설정을 대신 사용합니다. |

320| `allowDangerouslySkipPermissions` | `false` | [Auto mode](/ko/permission-modes#eliminate-prompts-with-auto-mode) 및 Bypass 권한을 모드 선택기에 추가합니다. Auto mode는 [계획, 관리자, 모델 및 공급자 요구 사항](/ko/permission-modes#eliminate-prompts-with-auto-mode)이 있으므로 이 토글이 켜져 있어도 사용 불가능할 수 있습니다. Bypass 권한은 인터넷 액세스가 없는 샌드박스에서만 사용합니다. |322| `allowDangerouslySkipPermissions` | `false` | [Auto mode](/ko/permission-modes#eliminate-prompts-with-auto-mode) 및 Bypass 권한을 모드 선택기에 추가합니다. Auto mode는 [계획, 관리자, 모델 및 공급자 요구 사항](/ko/permission-modes#eliminate-prompts-with-auto-mode)이 있으므로 이 토글이 켜져 있어도 사용 불가능할 수 있습니다. Bypass 권한은 인터넷 액세스가 없는 샌드박스에서만 사용합니다. |

321| `claudeProcessWrapper` | - | Claude 프로세스를 시작하는 데 사용되는 실행 파일 경로 |323| `claudeProcessWrapper` | - | Claude 프로세스를 시작하는 데 사용되는 실행 파일입니다. 번들된 바이너리 경로는 존재할 때 인수로 전달됩니다. 확장 프로그램 빌드에 플랫폼용 바이너리가 포함되지 않은 경우 별도로 설치된 `claude` 바이너리로 설정합니다. |

322 324

323## VS Code 확장 프로그램 vs. Claude Code CLI325## VS Code 확장 프로그램 vs. Claude Code CLI

324 326

Documentation 2026-05-07 22:59 UTC to 2026-05-08 22:00 UTC