Documentation 2026-10-15 23:58 UTC to 2026-10-16 22:59 UTC

9훅은 도구가 호출되거나 세션이 시작되거나 실행이 중지되는 등 에이전트 이벤트에 응답하여 코드를 실행하는 콜백 함수입니다. 훅을 사용하면 다음을 수행할 수 있습니다.9훅은 도구가 호출되거나 세션이 시작되거나 실행이 중지되는 등 에이전트 이벤트에 응답하여 코드를 실행하는 콜백 함수입니다. 훅을 사용하면 다음을 수행할 수 있습니다.

10 10 

11* **위험한 작업 차단** 실행 전에 파괴적인 셸 명령이나 무단 파일 액세스 같은 위험한 작업을 차단합니다11* **위험한 작업 차단** 실행 전에 파괴적인 셸 명령이나 무단 파일 액세스 같은 위험한 작업을 차단합니다

12* **로깅 및 감사** 규정 준수, 디버깅 또는 분석을 위해 모든 도구 호출을 기록합니다12* **로깅 및 감사** 규정 준수, 디버깅 또는 분석을 위해 도구 호출을 기록합니다

13* **입력 및 출력 변환** 데이터를 정제하거나 자격 증명을 주입하거나 파일 경로를 리디렉션합니다13* **입력 및 출력 변환** 데이터를 정제하거나 자격 증명을 주입하거나 파일 경로를 리디렉션합니다

14* **인간 승인 요구** 데이터베이스 쓰기 또는 API 호출 같은 민감한 작업에 대해 승인을 요구합니다14* **인간 승인 요구** 데이터베이스 쓰기 또는 API 호출 같은 민감한 작업에 대해 승인을 요구합니다

15* **세션 수명 주기 추적** 상태를 관리하거나 리소스를 정리하거나 알림을 보냅니다15* **세션 수명 주기 추적** 상태를 관리하거나 리소스를 정리하거나 알림을 보냅니다

40 </Step>40 </Step>

41</Steps>41</Steps>

42 42 

43다음 예제는 이러한 단계를 함께 보여줍니다. `PreToolUse` 훅(단계 1)을 `"Write|Edit"` 매처(단계 3)로 등록하므로 콜백은 파일 쓰기 도구에만 발생합니다. 트리거되면 콜백은 도구의 입력(단계 4)을 받고 파일 경로가 `.env` 파일을 대상으로 하는지 확인한 후 `permissionDecision: "deny"`를 반환하여 작업을 차단합니다(단계 5):43다음 예제는 `PreToolUse` 훅(단계 1)을 `"Write|Edit"` matcher(단계 3)로 등록하므로 콜백은 Write 및 Edit 도구에 대해 발생합니다. 트리거되면 콜백은 도구의 입력(단계 4)을 받고 파일 경로가 `.env` 파일을 대상으로 하는지 확인한 후 `permissionDecision: "deny"`를 반환하여 작업을 차단합니다(단계 5):

44 44 

45<CodeGroup>45<CodeGroup>

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

61 file_name = file_path.split("/")[-1]61 file_name = file_path.split("/")[-1]

62 62 

63 # .env 파일을 대상으로 하는 경우 작업을 차단합니다63 # .env 파일을 대상으로 하는 경우 작업을 차단합니다

64 if file_name == ".env":64 if file_name.lower() == ".env":

65 return {65 return {

66 "hookSpecificOutput": {66 "hookSpecificOutput": {

67 "hookEventName": input_data["hook_event_name"],67 "hookEventName": input_data["hook_event_name"],

108 const fileName = filePath?.split("/").pop();108 const fileName = filePath?.split("/").pop();

109 109 

110 // .env 파일을 대상으로 하는 경우 작업을 차단합니다110 // .env 파일을 대상으로 하는 경우 작업을 차단합니다

111 if (fileName === ".env") {111 if (fileName?.toLowerCase() === ".env") {

112 return {112 return {

113 hookSpecificOutput: {113 hookSpecificOutput: {

114 hookEventName: preInput.hook_event_name,114 hookEventName: preInput.hook_event_name,

140 ```140 ```

141</CodeGroup>141</CodeGroup>

142 142 

143두 스크립트 중 어느 것을 실행하든 Claude가 `.env` 파일을 생성하려고 시도하고 훅이 도구 호출을 거부합니다.143이 훅은 `file_path`가 대소문자에 관계없이 `/.env`로 끝나는 Write 또는 Edit 호출을 거부합니다. Windows에서는 `file_path`가 `C:\project\.env`와 같이 백슬래시를 사용하므로, 이 훅은 `C:\project\.env`에 대한 Write 또는 Edit 호출을 허용합니다.

144 

145<Warning>

146 `Write|Edit` matcher는 이 훅을 Write 및 Edit 도구로 제한합니다. Claude가 Bash 명령으로 `.env`를 작성하면 훅이 실행되지 않습니다. [샌드박스가 실행되는](/docs/ko/sandboxing) 환경에서 파일에 대한 Bash 쓰기를 차단하려면 [Python](/docs/ko/agent-sdk/python#sandbox-configuration) 또는 [TypeScript](/docs/ko/agent-sdk/typescript#sandbox-configuration)의 샌드박스 구성을 참조하세요.

147</Warning>

144 148 

145<h2 id="available-hooks">149<h2 id="available-hooks">

146 사용 가능한 훅150 사용 가능한 훅

151| 훅 이벤트 | Python SDK | TypeScript SDK | 트리거되는 조건 | 사용 사례 예 |155| 훅 이벤트 | Python SDK | TypeScript SDK | 트리거되는 조건 | 사용 사례 예 |

152| - | - | - | - | - |156| - | - | - | - | - |

153| `PreToolUse` | 예 | 예 | 도구 호출 요청(차단 또는 수정 가능) | 위험한 셸 명령 차단 |157| `PreToolUse` | 예 | 예 | 도구 호출 요청(차단 또는 수정 가능) | 위험한 셸 명령 차단 |

154| `PostToolUse` | 예 | 예 | 도구 실행 결과 | 모든 파일 변경 사항을 감사 추적에 기록 |158| `PostToolUse` | 예 | 예 | 도구 실행 결과 | 파일 변경 사항을 감사 추적에 기록 |

155| `PostToolUseFailure` | 예 | 예 | 도구 실행 실패 | 도구 오류 처리 또는 기록 |159| `PostToolUseFailure` | 예 | 예 | 도구 실행 실패 | 도구 오류 처리 또는 기록 |

156| `PostToolBatch` | 아니오 | 예 | 전체 도구 호출 배치가 해결되며, 다음 모델 호출 전에 배치당 한 번 | 전체 배치에 대해 한 번 규칙 주입 |160| `PostToolBatch` | 아니오 | 예 | 전체 도구 호출 배치가 해결되며, 다음 모델 호출 전에 배치당 한 번 | 전체 배치에 대해 한 번 규칙 주입 |

157| [`UserPromptSubmit`](/docs/ko/hooks#userpromptsubmit) | 예 | 예 | Claude Code가 스스로 시작하는 턴을 포함하여 프롬프트가 제출됨 | 프롬프트에 추가 컨텍스트 주입 |161| [`UserPromptSubmit`](/docs/ko/hooks#userpromptsubmit) | 예 | 예 | Claude Code가 스스로 시작하는 턴을 포함하여 프롬프트가 제출됨 | 프롬프트에 추가 컨텍스트 주입 |

235| `hooks` | `HookCallback[]` | - | 필수입니다. 패턴이 일치할 때 실행할 콜백 함수의 배열 |239| `hooks` | `HookCallback[]` | - | 필수입니다. 패턴이 일치할 때 실행할 콜백 함수의 배열 |

236| `timeout` | `number` | `undefined` | 초 단위의 타임아웃입니다. 생략하면 Claude Code는 [이벤트의 기본 타임아웃](#hook-timeout)을 적용합니다. SDK 콜백은 `command` 훅 기본값을 따릅니다. |240| `timeout` | `number` | `undefined` | 초 단위의 타임아웃입니다. 생략하면 Claude Code는 [이벤트의 기본 타임아웃](#hook-timeout)을 적용합니다. SDK 콜백은 `command` 훅 기본값을 따릅니다. |

237 241 

238가능할 때마다 `matcher` 패턴을 사용하여 특정 도구를 대상으로 합니다. `'Bash'` 매처는 Bash 명령에만 실행되지만 패턴을 생략하면 콜백이 이벤트의 모든 발생에 대해 실행됩니다. 의도적으로 생략하여 세션이 수행하는 모든 도구 호출을 기록합니다.242가능할 때마다 `matcher` 패턴을 사용하여 특정 도구를 대상으로 합니다. `'Bash'` 매처는 Bash 명령에만 실행되지만 패턴을 생략하면 콜백이 이벤트의 모든 발생에 대해 실행됩니다.

239 243 

240<h3 id="callback-functions">244<h3 id="callback-functions">

241 콜백 함수245 콜백 함수

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

269 273 

270<Note>274<Note>

271 여러 훅 또는 권한 규칙이 적용되는 경우 `deny`는 `defer`보다 우선하고, `defer`는 `ask`보다 우선하고, `ask`는 `allow`보다 우선합니다. 훅이 `deny`를 반환하면 다른 훅에 관계없이 작업이 차단됩니다.275 여러 `PreToolUse` 훅이 서로 다른 [결정](/docs/ko/hooks#pretooluse-decision-control)을 반환하는 경우 `deny`는 `defer`보다 우선하고, `defer`는 `ask`보다 우선하고, `ask`는 `allow`보다 우선합니다.

272</Note>276</Note>

273 277 

274<h4 id="asynchronous-output">278<h4 id="asynchronous-output">

307 예제311 예제

308</h2>312</h2>

309 313 

310이 섹션의 여러 예제는 콜백 함수만 보여줍니다. 실행하려면 [훅 구성](#configure-hooks)에 표시된 대로 옵션의 `hooks` 필드에서 일치하는 이벤트 아래에 콜백을 등록합니다.314이 섹션의 여러 예제는 콜백 함수만 보여 줍니다. 예제를 실행하려면 [훅 구성](#configure-hooks)에 나온 것처럼 옵션의 `hooks` 필드에서 해당 이벤트 아래에 콜백을 등록합니다.

311 315 

312<h3 id="modify-tool-input">316<h3 id="modify-tool-input">

313 도구 입력 수정317 도구 입력 수정

314</h3>318</h3>

315 319 

316이 예제는 Write 도구 호출을 가로채고 `file_path` 인수를 다시 작성하여 `/sandbox`를 앞에 붙여 모든 파일 쓰기를 샌드박스 디렉토리로 리디렉션합니다. 콜백은 수정된 경로와 함께 `updatedInput`을 반환하고 `permissionDecision: 'allow'`를 반환하여 다시 작성된 작업을 자동 승인합니다:320이 예제는 Write 도구 호출을 가로채 `file_path` 인수 앞에 `/sandbox`를 붙이도록 다시 작성합니다. 콜백은 수정된 경로가 담긴 `updatedInput`과 함께, 다시 작성된 작업을 자동 승인하는 `permissionDecision: 'allow'`를 반환합니다.

317 321 

318<CodeGroup>322<CodeGroup>

319 ```python Python theme={null}323 ```python Python theme={null}

361</CodeGroup>365</CodeGroup>

362 366 

363<Note>367<Note>

364 `updatedInput`을 `permissionDecision: 'allow'`와 함께 사용하여 수정된 입력을 자동 승인하거나, `permissionDecision: 'ask'`와 함께 사용하여 사용자에게 표시합니다. `permissionDecision`을 생략하면 수정된 입력이 여전히 적용되고 일반 권한 평가를 통해 흐릅니다. `'defer'`를 사용하면 `updatedInput`은 무시됩니다. 항상 원본 `tool_input`을 변경하지 않고 새 객체를 반환합니다.368 수정된 입력을 자동 승인하려면 `updatedInput`을 `permissionDecision: 'allow'`와 함께 사용하고, 사용자에게 보여 주려면 `permissionDecision: 'ask'`와 함께 사용합니다. `permissionDecision`을 생략해도 수정된 입력은 그대로 적용되며 일반적인 권한 평가를 거칩니다. `'defer'`를 사용하면 `updatedInput`은 무시됩니다. 원래의 `tool_input`을 변경하지 말고 항상 새 객체를 반환하십시오.

365</Note>369</Note>

366 370 

367리디렉션을 확인하려면 접두사를 `./sandbox` 또는 `/tmp/sandbox`와 같이 쓸 수 있는 경로로 설정합니다(macOS는 루트 수준의 `/sandbox` 디렉토리 생성을 허용하지 않음). 그런 다음 에이전트에 파일을 쓰도록 요청합니다. 메시지 스트림의 Write 도구 결과는 Claude가 요청한 경로가 아닌 샌드박스 접두사가 있는 경로를 표시합니다.371리디렉션을 확인하려면 접두사를 `./sandbox`나 `/tmp/sandbox`처럼 쓰기 가능한 경로로 설정한 다음(macOS에서는 루트 수준의 `/sandbox` 디렉터리를 만들 수 없습니다) 에이전트에게 파일을 작성하도록 요청합니다. 메시지 스트림의 Write 도구 결과에는 Claude가 요청한 경로가 아니라 샌드박스 접두사가 붙은 경로가 표시됩니다.

368 372 

369<h3 id="add-context-and-block-a-tool">373<h3 id="add-context-and-block-a-tool">

370 컨텍스트 추가 및 도구 차단374 컨텍스트 추가 및 도구 차단

371</h3>375</h3>

372 376 

373이 예제는 `/etc` 디렉토리에 쓰려는 시도를 차단하고 모델과 사용자 모두에게 이유를 설명합니다:377이 예제는 `file_path`가 `/etc`로 시작하는 도구 호출을 거부하고, 그 이유를 모델과 사용자 모두에게 설명합니다.

374 378 

375* `permissionDecision: 'deny'`는 도구 호출을 중지합니다.379* `permissionDecision: 'deny'`는 도구 호출을 중단합니다.

376* `permissionDecisionReason`은 모델에 이유를 알려주므로 재시도를 피합니다.380* `permissionDecisionReason`은 모델에게 이유를 알려 줍니다.

377* `systemMessage`는 사용자에게 발생한 상황을 보여줍니다.381* `systemMessage`는 사용자에게 무슨 일이 있었는지 보여 줍니다.

378 382 

379<CodeGroup>383<CodeGroup>

380 ```python Python theme={null}384 ```python Python theme={null}

383 387 

384 if file_path.startswith("/etc"):388 if file_path.startswith("/etc"):

385 return {389 return {

386 # 최상위 필드: 사용자에게 표시되는 메시지390 # Top-level field: message shown to the user

387 "systemMessage": "Remember: system directories like /etc are protected.",391 "systemMessage": "Remember: system directories like /etc are protected.",

388 # hookSpecificOutput: 작업을 차단합니다392 # hookSpecificOutput: block the operation

389 "hookSpecificOutput": {393 "hookSpecificOutput": {

390 "hookEventName": input_data["hook_event_name"],394 "hookEventName": input_data["hook_event_name"],

391 "permissionDecision": "deny",395 "permissionDecision": "deny",

403 407 

404 if (filePath?.startsWith("/etc")) {408 if (filePath?.startsWith("/etc")) {

405 return {409 return {

406 // 최상위 필드: 사용자에게 표시되는 메시지410 // Top-level field: message shown to the user

407 systemMessage: "Remember: system directories like /etc are protected.",411 systemMessage: "Remember: system directories like /etc are protected.",

408 // hookSpecificOutput: 작업을 차단합니다412 // hookSpecificOutput: block the operation

409 hookSpecificOutput: {413 hookSpecificOutput: {

410 hookEventName: preInput.hook_event_name,414 hookEventName: preInput.hook_event_name,

411 permissionDecision: "deny",415 permissionDecision: "deny",

418 ```422 ```

419</CodeGroup>423</CodeGroup>

420 424 

421차단을 확인하려면 `PreToolUse`에서 콜백을 `Write|Edit` 매처로 등록하고 에이전트에 `/etc` 아래에 파일을 생성하도록 요청합니다. 메시지 스트림의 Write 도구 결과에는 `Writing to /etc is not allowed`가 포함되며 파일이 생성되지 않습니다.425차단을 확인하려면 `Write|Edit` matcher와 함께 `PreToolUse` 아래에 콜백을 등록하고 에이전트에게 `/etc` 아래에 파일을 만들도록 요청합니다. 메시지 스트림의 Write 도구 결과에 `Writing to /etc is not allowed`가 포함되며, 파일은 생성되지 않습니다.

422 426 

423<h3 id="auto-approve-specific-tools">427<h3 id="auto-approve-specific-tools">

424 특정 도구 자동 승인428 특정 도구 자동 승인

425</h3>429</h3>

426 430 

427기본적으로 에이전트는 특정 도구를 사용하기 전에 권한을 요청할 수 있습니다. 이 예제는 `permissionDecision: 'allow'`를 반환하여 읽기 전용 파일 시스템 도구(Read, Glob, Grep)를 자동 승인하여 [네트워크 경로](/docs/ko/permissions#network-paths)에서의 읽기를 제외하고 사용자 확인 없이 실행되도록 하면서 다른 모든 도구는 일반 권한 확인을 받습니다:431기본적으로 에이전트는 특정 도구를 사용하기 전에 권한 확인을 요청할 수 있습니다. 이 예제는 `permissionDecision: 'allow'`를 반환하여 읽기 전용 파일 시스템 도구(Read, Glob, Grep)를 자동 승인합니다. 이를 통해 [네트워크 경로](/docs/ko/permissions#network-paths)에서의 읽기를 제외하고는 사용자 확인 없이 이 도구들을 실행할 수 있으며, 다른 모든 도구는 일반적인 권한 검사를 그대로 거칩니다.

428 432 

429<CodeGroup>433<CodeGroup>

430 ```python Python theme={null}434 ```python Python theme={null}

468 여러 훅 등록472 여러 훅 등록

469</h3>473</h3>

470 474 

471이벤트가 발생하면 일치하는 모든 훅이 병렬로 실행됩니다. 권한 결정의 경우 가장 제한적인 결과가 우선합니다. 단일 `deny`는 다른 훅이 반환하는 것에 관계없이 도구 호출을 차단합니다. 완료 순서가 비결정적이므로 다른 훅이 먼저 실행되었다고 가정하지 않고 각 훅이 독립적으로 작동하도록 작성합니다.475이벤트가 발생하면 일치하는 훅이 병렬로 실행됩니다. 권한 결정의 경우 가장 제한적인 결과가 적용됩니다. 하나의 훅이 `deny`를 반환하면 도구 호출이 차단됩니다. 완료 순서는 비결정적이므로, 다른 훅이 먼저 실행되었다고 가정하지 말고 각 훅이 독립적으로 동작하도록 작성하십시오.

472 476 

473아래 예제는 모든 도구 호출에 대해 세 가지 독립적인 확인을 등록합니다. 예제의 훅 이름(예: Python의 `audit_logger` 또는 TypeScript의 `auditLogger`)은 사용자가 정의하는 콜백을 나타냅니다:477아래 예제는 각각 [matcher를 생략한](/docs/ko/hooks#matcher-patterns) 세 개의 독립적인 검사를 등록합니다. 여기에 나오는 Python의 `audit_logger`나 TypeScript의 `auditLogger` 같은 훅 이름은 사용자가 정의하는 콜백을 나타냅니다.

474 478 

475<CodeGroup>479<CodeGroup>

476 ```python Python theme={null}480 ```python Python theme={null}

499</CodeGroup>503</CodeGroup>

500 504 

501<h3 id="filter-with-multi-tool-matchers">505<h3 id="filter-with-multi-tool-matchers">

502 다중 도구 매처로 필터링506 다중 도구 matcher로 필터링

503</h3>507</h3>

504 508 

505다중 도구 매처를 사용하여 관련 도구 간에 하나의 콜백을 공유합니다. 이 예제는 서로 다른 범위의 세 가지 매처를 등록하며, 예제의 각 훅 이름은 사용자가 정의하는 콜백을 나타냅니다:509다중 도구 matcher를 사용하면 관련 도구들 사이에서 하나의 콜백을 공유할 수 있습니다. 이 예제는 범위가 서로 다른 세 개의 matcher를 등록하며, 여기에 나오는 각 훅 이름은 사용자가 정의하는 콜백을 나타냅니다.

506 510 

507* 파이프로 구분된 정확한 목록(`Write|Edit|NotebookEdit`)은 파일 수정 도구에만 `file_security_hook`을 트리거합니다.511* 파이프로 구분된 정확한 목록(`Write|Edit|NotebookEdit`)은 Write, Edit, NotebookEdit 도구에 대해 `file_security_hook`을 트리거합니다.

508* 정규식(`^mcp__`)은 이름이 `mcp__`로 시작하는 모든 MCP 도구에 대해 `mcp_audit_hook`을 트리거합니다.512* 정규식(`^mcp__`)은 이름이 `mcp__`로 시작하는 모든 MCP 도구에 대해 `mcp_audit_hook`을 트리거합니다.

509* 생략된 매처는 이름에 관계없이 모든 도구 호출에 대해 `global_logger`를 트리거합니다.513* matcher를 생략하면 도구 이름으로 필터링하지 않고 `global_logger`를 트리거합니다.

510 514 

511<CodeGroup>515<CodeGroup>

512 ```python Python theme={null}516 ```python Python theme={null}

513 options = ClaudeAgentOptions(517 options = ClaudeAgentOptions(

514 hooks={518 hooks={

515 "PreToolUse": [519 "PreToolUse": [

516 # 파일 수정 도구 일치520 # Match file modification tools

517 HookMatcher(matcher="Write|Edit|NotebookEdit", hooks=[file_security_hook]),521 HookMatcher(matcher="Write|Edit|NotebookEdit", hooks=[file_security_hook]),

518 # 모든 MCP 도구 일치522 # Match all MCP tools

519 HookMatcher(matcher="^mcp__", hooks=[mcp_audit_hook]),523 HookMatcher(matcher="^mcp__", hooks=[mcp_audit_hook]),

520 # 모든 것 일치(매처 없음)524 # Match everything (no matcher)

521 HookMatcher(hooks=[global_logger]),525 HookMatcher(hooks=[global_logger]),

522 ]526 ]

523 }527 }

528 const options = {532 const options = {

529 hooks: {533 hooks: {

530 PreToolUse: [534 PreToolUse: [

531 // 파일 수정 도구 일치535 // Match file modification tools

532 { matcher: "Write|Edit|NotebookEdit", hooks: [fileSecurityHook] },536 { matcher: "Write|Edit|NotebookEdit", hooks: [fileSecurityHook] },

533 537 

534 // 모든 MCP 도구 일치538 // Match all MCP tools

535 { matcher: "^mcp__", hooks: [mcpAuditHook] },539 { matcher: "^mcp__", hooks: [mcpAuditHook] },

536 540 

537 // 모든 것 일치(매처 없음)541 // Match everything (no matcher)

538 { hooks: [globalLogger] }542 { hooks: [globalLogger] }

539 ]543 ]

540 }544 }

546 서브에이전트 활동 추적550 서브에이전트 활동 추적

547</h3>551</h3>

548 552 

549`SubagentStop` 훅을 사용하여 서브에이전트가 작업을 완료할 때를 모니터링합니다. [TypeScript](/docs/ko/agent-sdk/typescript#hookinput) 및 [Python](/docs/ko/agent-sdk/python#hookinput) SDK 참조에서 전체 입력 타입을 참조하세요. 이 예제는 서브에이전트가 완료될 때마다 요약을 기록합니다:553`SubagentStop` 훅을 사용하여 서브에이전트가 작업을 마치는 시점을 모니터링합니다. 전체 입력 타입은 [TypeScript](/docs/ko/agent-sdk/typescript#hookinput) 및 [Python](/docs/ko/agent-sdk/python#hookinput) SDK 레퍼런스를 참조하십시오. 이 예제는 서브에이전트가 완료될 때마다 요약을 로그에 기록합니다.

550 554 

551<CodeGroup>555<CodeGroup>

552 ```python Python theme={null}556 ```python Python theme={null}

553 async def subagent_tracker(input_data, tool_use_id, context):557 async def subagent_tracker(input_data, tool_use_id, context):

554 # 서브에이전트가 완료될 때 세부 정보를 기록합니다558 # Log subagent details when it finishes

555 print(f"[SUBAGENT] Completed: {input_data['agent_id']}")559 print(f"[SUBAGENT] Completed: {input_data['agent_id']}")

556 print(f" Transcript: {input_data['agent_transcript_path']}")560 print(f" Transcript: {input_data['agent_transcript_path']}")

557 print(f" Tool use ID: {tool_use_id}")561 print(f" Tool use ID: {tool_use_id}")

568 import { HookCallback, SubagentStopHookInput } from "@anthropic-ai/claude-agent-sdk";572 import { HookCallback, SubagentStopHookInput } from "@anthropic-ai/claude-agent-sdk";

569 573 

570 const subagentTracker: HookCallback = async (input, toolUseID, { signal }) => {574 const subagentTracker: HookCallback = async (input, toolUseID, { signal }) => {

571 // SubagentStopHookInput으로 캐스팅하여 서브에이전트별 필드에 액세스합니다575 // Cast to SubagentStopHookInput to access subagent-specific fields

572 const subInput = input as SubagentStopHookInput;576 const subInput = input as SubagentStopHookInput;

573 577 

574 // 서브에이전트가 완료될 때 세부 정보를 기록합니다578 // Log subagent details when it finishes

575 console.log(`[SUBAGENT] Completed: ${subInput.agent_id}`);579 console.log(`[SUBAGENT] Completed: ${subInput.agent_id}`);

576 console.log(` Transcript: ${subInput.agent_transcript_path}`);580 console.log(` Transcript: ${subInput.agent_transcript_path}`);

577 console.log(` Tool use ID: ${toolUseID}`);581 console.log(` Tool use ID: ${toolUseID}`);

587 ```591 ```

588</CodeGroup>592</CodeGroup>

589 593 

590훅이 발생하는지 확인하려면 콜백을 등록하고 에이전트에 현재 디렉토리의 파일을 나열하는 등 작은 작업을 서브에이전트에 위임하도록 요청합니다. 서브에이전트가 완료되면 콜백은 서브에이전트의 ID와 트랜스크립트 경로와 함께 `[SUBAGENT] Completed:` 줄을 출력합니다.594훅이 실행되는지 확인하려면 콜백을 등록하고 에이전트에게 현재 디렉터리의 파일 나열과 같은 작은 작업을 서브에이전트에 위임하도록 요청합니다. 서브에이전트가 완료되면 콜백이 서브에이전트의 ID와 트랜스크립트 경로가 담긴 `[SUBAGENT] Completed:` 줄을 출력합니다.

591 595 

592<h3 id="make-http-requests-from-hooks">596<h3 id="make-http-requests-from-hooks">

593 훅에서 HTTP 요청 만들기597 훅에서 HTTP 요청 보내기

594</h3>598</h3>

595 599 

596훅은 HTTP 요청 같은 비동기 작업을 수행할 수 있습니다. 훅 내에서 오류를 포착하고 전파하지 않습니다.600훅은 HTTP 요청과 같은 비동기 작업을 수행할 수 있습니다. 오류가 전파되도록 두지 말고 훅 내부에서 오류를 포착하십시오.

597 601 

598이 예제는 각 도구가 완료된 후 웹훅을 전송하여 어떤 도구가 실행되었는지와 언제 실행되었는지를 기록합니다. 훅은 실패한 웹훅이 에이전트를 중단하지 않도록 오류를 포착합니다:602이 예제는 각 도구가 완료된 후 웹훅을 전송하여 어떤 도구가 언제 실행되었는지 로그에 기록합니다. 훅은 실패한 웹훅에서 발생한 오류를 포착합니다.

599 603 

600<CodeGroup>604<CodeGroup>

601 ```python Python theme={null}605 ```python Python theme={null}

606 610 

607 611 

608 def _send_webhook(tool_name):612 def _send_webhook(tool_name):

609 """도구 사용 데이터를 외부 웹훅에 POST하는 동기 헬퍼입니다."""613 """Synchronous helper that POSTs tool usage data to an external webhook."""

610 data = json.dumps(614 data = json.dumps(

611 {615 {

612 "tool": tool_name,616 "tool": tool_name,

623 627 

624 628 

625 async def webhook_notifier(input_data, tool_use_id, context):629 async def webhook_notifier(input_data, tool_use_id, context):

626 # 도구가 완료된 후(PostToolUse)에만 발생하고, 전에는 아닙니다630 # Only fire after a tool completes (PostToolUse), not before

627 if input_data["hook_event_name"] != "PostToolUse":631 if input_data["hook_event_name"] != "PostToolUse":

628 return {}632 return {}

629 633 

630 try:634 try:

631 # 이벤트 루프를 차단하지 않도록 스레드에서 차단 HTTP 호출을 실행합니다635 # Run the blocking HTTP call in a thread to avoid blocking the event loop

632 await asyncio.to_thread(_send_webhook, input_data["tool_name"])636 await asyncio.to_thread(_send_webhook, input_data["tool_name"])

633 except Exception as e:637 except Exception as e:

634 # 오류를 기록하지만 발생시키지 않습니다638 # Log the error but don't raise

635 print(f"Webhook request failed: {e}")639 print(f"Webhook request failed: {e}")

636 640 

637 return {}641 return {}

641 import { query, HookCallback, PostToolUseHookInput } from "@anthropic-ai/claude-agent-sdk";645 import { query, HookCallback, PostToolUseHookInput } from "@anthropic-ai/claude-agent-sdk";

642 646 

643 const webhookNotifier: HookCallback = async (input, toolUseID, { signal }) => {647 const webhookNotifier: HookCallback = async (input, toolUseID, { signal }) => {

644 // 도구가 완료된 후(PostToolUse)에만 발생하고, 전에는 아닙니다648 // Only fire after a tool completes (PostToolUse), not before

645 if (input.hook_event_name !== "PostToolUse") return {};649 if (input.hook_event_name !== "PostToolUse") return {};

646 650 

647 try {651 try {

652 tool: (input as PostToolUseHookInput).tool_name,656 tool: (input as PostToolUseHookInput).tool_name,

653 timestamp: new Date().toISOString()657 timestamp: new Date().toISOString()

654 }),658 }),

655 // 훅이 타임아웃되면 요청이 취소되도록 신호를 전달합니다659 // Pass signal so the request cancels if the hook times out

656 signal660 signal

657 });661 });

658 } catch (error) {662 } catch (error) {

659 // 다른 오류와 별도로 취소를 처리합니다663 // Handle cancellation separately from other errors

660 if (error instanceof Error && error.name === "AbortError") {664 if (error instanceof Error && error.name === "AbortError") {

661 console.log("Webhook request cancelled");665 console.log("Webhook request cancelled");

662 }666 }

663 // 다시 발생시키지 않습니다667 // Don't re-throw

664 }668 }

665 669 

666 return {};670 return {};

667 };671 };

668 672 

669 // PostToolUse 훅으로 등록합니다673 // Register as a PostToolUse hook

670 for await (const message of query({674 for await (const message of query({

671 prompt: "Refactor the auth module",675 prompt: "Refactor the auth module",

672 options: {676 options: {

680 ```684 ```

681</CodeGroup>685</CodeGroup>

682 686 

683웹훅이 발생하는지 확인하려면 웹훅 URL을 감시할 수 있는 엔드포인트로 지정하고 도구를 사용하는 프롬프트를 전송합니다. 훅은 각 도구가 완료된 후 도구 이름과 타임스탬프가 포함된 POST를 전송합니다.687훅이 실행되는지 확인하려면 웹훅 URL을 모니터링할 수 있는 엔드포인트로 지정하고 도구를 사용하는 프롬프트를 보냅니다. 각 도구가 완료된 후 훅이 도구 이름과 타임스탬프가 담긴 POST 요청을 보냅니다.

684 688 

685<h3 id="forward-notifications-to-slack">689<h3 id="forward-notifications-to-slack">

686 Slack으로 알림 전달690 Slack으로 알림 전달

687</h3>691</h3>

688 692 

689`Notification` 훅을 사용하여 에이전트에서 시스템 알림을 받고 외부 서비스로 전달합니다. SDK 세션에서 Claude Code는 다음 알림 유형에 대해 이 훅을 실행합니다:693`Notification` 훅을 사용하여 에이전트로부터 시스템 알림을 받고 외부 서비스로 전달합니다. SDK 세션에서 Claude Code는 다음 알림 유형에 대해 이 훅을 실행합니다.

690 694 

691* [`permission_prompt`](/docs/ko/hooks#notification) 권한 요청이 [`canUseTool` 콜백](/docs/ko/agent-sdk/user-input)에서 약 6초 동안 대기한 후. TypeScript Agent SDK v0.3.233 이상 또는 Python Agent SDK v0.2.139 이상이 필요합니다695* [`permission_prompt`](/docs/ko/hooks#notification): 권한 요청이 [`canUseTool` 콜백](/docs/ko/agent-sdk/user-input)에서 약 6초 동안 대기한 경우. TypeScript Agent SDK v0.3.233 이상 또는 Python Agent SDK v0.2.139 이상이 필요합니다

692* `elicitation_complete` 및 `elicitation_response` 사용자 프롬프트 유도 흐름의 경우696* `elicitation_complete` 및 `elicitation_response`: 사용자 프롬프트 elicitation 흐름용

693 697 

694Claude Code는 `idle_prompt`, `auth_success`, `elicitation_dialog` 같은 다른 유형을 SDK 세션이 실행하지 않는 대화형 UI에서 내보냅니다.698`idle_prompt`, `auth_success`, `elicitation_dialog`와 같은 다른 유형은 Claude Code가 SDK 세션에서 실행되지 않는 대화형 UI에서 발생시킵니다.

695 699 

696각 알림에는 인간이 읽을 수 있는 설명이 있는 `message` 필드와 선택적으로 `title`이 포함됩니다.700각 알림에는 사람이 읽을 수 있는 설명이 담긴 `message` 필드가 포함되며, 선택적으로 `title`이 포함됩니다.

697 701 

698이 예제는 모든 알림을 Slack 채널로 전달합니다. [Slack 수신 웹훅 URL](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks/)이 필요하며, 이는 Slack 작업 공간에 앱을 추가하고 수신 웹훅을 활성화하여 생성합니다:702이 예제는 모든 알림을 Slack 채널로 전달합니다. [Slack incoming webhook URL](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks/)이 필요하며, 이 URL은 Slack 워크스페이스에 앱을 추가하고 incoming webhook을 활성화하여 생성합니다.

699 703 

700<CodeGroup>704<CodeGroup>

701 ```python Python theme={null}705 ```python Python theme={null}

707 711 

708 712 

709 def _send_slack_notification(message):713 def _send_slack_notification(message):

710 """수신 웹훅을 통해 Slack에 메시지를 보내는 동기 헬퍼입니다."""714 """Synchronous helper that sends a message to Slack via incoming webhook."""

711 data = json.dumps({"text": f"Agent status: {message}"}).encode()715 data = json.dumps({"text": f"Agent status: {message}"}).encode()

712 req = urllib.request.Request(716 req = urllib.request.Request(

713 "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",717 "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",

720 724 

721 async def notification_handler(input_data, tool_use_id, context):725 async def notification_handler(input_data, tool_use_id, context):

722 try:726 try:

723 # 이벤트 루프를 차단하지 않도록 스레드에서 차단 HTTP 호출을 실행합니다727 # Run the blocking HTTP call in a thread to avoid blocking the event loop

724 await asyncio.to_thread(_send_slack_notification, input_data.get("message", ""))728 await asyncio.to_thread(_send_slack_notification, input_data.get("message", ""))

725 except Exception as e:729 except Exception as e:

726 print(f"Failed to send notification: {e}")730 print(f"Failed to send notification: {e}")

727 731 

728 # 빈 객체를 반환합니다. 알림 훅은 에이전트 동작을 수정하지 않습니다732 # Return empty object. Notification hooks don't modify agent behavior

729 return {}733 return {}

730 734 

731 735 

732 async def main():736 async def main():

733 options = ClaudeAgentOptions(737 options = ClaudeAgentOptions(

734 hooks={738 hooks={

735 # 알림 이벤트에 대한 훅을 등록합니다(매처 필요 없음)739 # Register the hook for Notification events (no matcher needed)

736 "Notification": [HookMatcher(hooks=[notification_handler])],740 "Notification": [HookMatcher(hooks=[notification_handler])],

737 },741 },

738 )742 )

749 ```typescript TypeScript theme={null}753 ```typescript TypeScript theme={null}

750 import { query, HookCallback, NotificationHookInput } from "@anthropic-ai/claude-agent-sdk";754 import { query, HookCallback, NotificationHookInput } from "@anthropic-ai/claude-agent-sdk";

751 755 

752 // Slack으로 알림을 보내는 훅 콜백을 정의합니다756 // Define a hook callback that sends notifications to Slack

753 const notificationHandler: HookCallback = async (input, toolUseID, { signal }) => {757 const notificationHandler: HookCallback = async (input, toolUseID, { signal }) => {

754 // NotificationHookInput으로 캐스팅하여 메시지 필드에 액세스합니다758 // Cast to NotificationHookInput to access the message field

755 const notification = input as NotificationHookInput;759 const notification = input as NotificationHookInput;

756 760 

757 try {761 try {

758 // 알림 메시지를 Slack 수신 웹훅에 POST합니다762 // POST the notification message to a Slack incoming webhook

759 await fetch("https://hooks.slack.com/services/YOUR/WEBHOOK/URL", {763 await fetch("https://hooks.slack.com/services/YOUR/WEBHOOK/URL", {

760 method: "POST",764 method: "POST",

761 headers: { "Content-Type": "application/json" },765 headers: { "Content-Type": "application/json" },

762 body: JSON.stringify({766 body: JSON.stringify({

763 text: `Agent status: ${notification.message}`767 text: `Agent status: ${notification.message}`

764 }),768 }),

765 // 훅이 타임아웃되면 요청이 취소되도록 신호를 전달합니다769 // Pass signal so the request cancels if the hook times out

766 signal770 signal

767 });771 });

768 } catch (error) {772 } catch (error) {

773 }777 }

774 }778 }

775 779 

776 // 빈 객체를 반환합니다. 알림 훅은 에이전트 동작을 수정하지 않습니다780 // Return empty object. Notification hooks don't modify agent behavior

777 return {};781 return {};

778 };782 };

779 783 

780 // 알림 이벤트에 대한 훅을 등록합니다(매처 필요 없음)784 // Register the hook for Notification events (no matcher needed)

781 for await (const message of query({785 for await (const message of query({

782 prompt: "Analyze this codebase",786 prompt: "Analyze this codebase",

783 options: {787 options: {

791 ```795 ```

792</CodeGroup>796</CodeGroup>

793 797 

794`Notification` 이벤트가 발생하면 훅은 알림의 `message`를 `Agent status:` 접두사와 함께 웹훅이 대상으로 하는 채널에 게시합니다.798`Notification` 이벤트가 발생하면 훅은 알림의 `message` 앞에 `Agent status:`를 붙여 웹훅이 대상으로 하는 채널에 게시합니다.

795 799 

796<h2 id="fix-common-issues">800<h2 id="fix-common-issues">

797 일반적인 문제 해결801 일반적인 문제 해결

832 836 

833콜백이 타임아웃을 초과하면 Claude Code는 이를 취소하고 출력을 버리며, 세션은 중단되지 않고 계속됩니다. 다음에 일어나는 일은 이벤트에 따라 다릅니다:837콜백이 타임아웃을 초과하면 Claude Code는 이를 취소하고 출력을 버리며, 세션은 중단되지 않고 계속됩니다. 다음에 일어나는 일은 이벤트에 따라 다릅니다:

834 838 

835* `PreToolUse`: Claude Code는 도구 호출을 실행하지 않으며, Claude는 훅이 타임아웃 전에 응답하지 않았다는 도구 결과를 받고 턴이 계속됩니다. 다른 `PreToolUse` 훅이 명시적 거부를 반환한 경우 Claude는 타임아웃 오류 대신 그 거부를 받습니다. v2.1.210 이전에는 Claude Code가 타임아웃을 Claude에 사용자 거부로 보고했으며, 이는 무인 세션을 중지하고 입력을 기다리게 했습니다.839* `PreToolUse`: Claude Code는 도구 호출을 차단합니다. 그 대신 Claude는 훅이 타임아웃 전에 응답하지 않았다는 도구 결과를 받고 턴이 계속됩니다. v2.1.210 이전에는 Claude Code가 타임아웃을 Claude에 사용자 거부로 보고했으며, 이는 무인 세션을 중지하고 입력을 기다리게 했습니다.

836* `PostToolUse` 및 `PostToolUseFailure`: Claude Code는 도구 결과를 유지하고 턴이 계속됩니다.840* `PostToolUse` 및 `PostToolUseFailure`: Claude Code는 도구 결과를 유지하고 턴이 계속됩니다.

837* `UserPromptSubmit` 및 [`UserPromptExpansion`](/docs/ko/hooks#userpromptexpansion): Claude Code는 훅과 타임아웃을 명시하는 메시지로 프롬프트를 차단하고 세션은 계속됩니다. 이러한 이벤트의 콜백이 정책 게이트로 작동할 수 있으므로 Claude Code는 타임아웃된 프롬프트를 검사 없이 통과시키지 않습니다. v2.1.208 이전에는 Claude Code가 이러한 이벤트의 콜백 타임아웃 시 `error_during_execution`으로 쿼리를 종료했습니다.841* `UserPromptSubmit` 및 [`UserPromptExpansion`](/docs/ko/hooks#userpromptexpansion): Claude Code는 훅과 타임아웃을 명시하는 메시지로 프롬프트를 차단하고 세션은 계속됩니다. v2.1.208 이전에는 Claude Code가 이러한 이벤트의 콜백 타임아웃 시 `error_during_execution`으로 쿼리를 종료했습니다.

838* `Stop` 및 `SubagentStop`: 타임아웃된 콜백은 결정을 반환하지 않은 것으로 계산됩니다. 에이전트 또는 서브에이전트는 해당 콜백이 이를 허용한 것처럼 중지되며, 이벤트의 다른 훅의 결정은 여전히 적용됩니다. Claude Code v2.1.273 이전에는 타임아웃된 `Stop` 또는 `SubagentStop` 콜백이 실패한 훅 실행으로 계산되었으며, Claude Code는 이벤트의 다른 훅의 결정을 버렸습니다.842* `Stop` 및 `SubagentStop`: 타임아웃된 콜백은 결정을 반환하지 않은 것으로 계산됩니다. 에이전트 또는 서브에이전트는 해당 콜백이 이를 허용한 것처럼 중지되며, 이벤트의 다른 훅의 결정은 여전히 적용됩니다. Claude Code v2.1.273 이전에는 타임아웃된 `Stop` 또는 `SubagentStop` 콜백이 실패한 훅 실행으로 계산되었으며, Claude Code는 이벤트의 다른 훅의 결정을 버렸습니다.

839* `SessionStart`: 타임아웃된 콜백은 출력을 반환하지 않은 것으로 계산되며, 세션은 다른 `SessionStart` 훅의 출력으로 계속됩니다.843* `SessionStart`: 타임아웃된 콜백은 출력을 반환하지 않은 것으로 계산되며, 세션은 다른 `SessionStart` 훅의 출력으로 계속됩니다.

840* `PreModelSwitch`: Claude Code는 모델 전환을 차단합니다. 응답하지 않는 훅은 전환을 승인하지 않았습니다.844* `PreModelSwitch`: Claude Code는 모델 전환을 차단합니다. 응답하지 않는 훅은 전환을 승인하지 않았습니다.

3881<Note>3881<Note>

3882 샌드박스는 플랫폼 지원에 따라 달라지며, Linux에서는 `bubblewrap` 및 `socat`과 같은 도구가 필요합니다. 기본적으로 `enabled`가 `True`이지만 샌드박스를 시작할 수 없을 때, 명령은 stderr에 경고와 함께 샌드박스되지 않은 상태로 실행됩니다. 이 기본값은 `failIfUnavailable`이 `true`로 기본 설정되는 TypeScript SDK와 다릅니다.3882 샌드박스는 플랫폼 지원에 따라 달라지며, Linux에서는 `bubblewrap` 및 `socat`과 같은 도구가 필요합니다. 기본적으로 `enabled`가 `True`이지만 샌드박스를 시작할 수 없을 때, 명령은 stderr에 경고와 함께 샌드박스되지 않은 상태로 실행됩니다. 이 기본값은 `failIfUnavailable`이 `true`로 기본 설정되는 TypeScript SDK와 다릅니다.

3883 3883 

3884 대신 중지하려면 샌드박스 설정에서 `"failIfUnavailable": True`를 설정하십시오. 이 키는 아직 `SandboxSettings`에 선언되지 않았지만, SDK는 이를 Claude Code로 전달하며, Claude Code는 이를 준수합니다. 그러면 `query()`는 `subtype="error_during_execution"`과 `errors`의 이유를 포함한 `ResultMessage`를 보고합니다. 이것이 단일 샷 `query()` 호출이므로, SDK는 해당 오류 결과를 생성한 후 발생시키므로, 루프를 try 블록으로 감싸서 이를 지나 계속 진행하십시오. [결과 처리](/docs/ko/agent-sdk/agent-loop#handle-the-result)에서 오류 계약을 참조하십시오.3884 대신 중지하려면 샌드박스 설정에서 `"failIfUnavailable": True`를 설정하십시오. SDK는 선언된 `SandboxSettings` 필드와 함께 `failIfUnavailable`을 Claude Code로 전달합니다. 그러면 `query()`는 `subtype="error_during_execution"`과 `errors`의 이유를 포함한 `ResultMessage`를 보고합니다. 이것이 단일 샷 `query()` 호출이므로, SDK는 해당 오류 결과를 생성한 후 발생시키므로, 루프를 try 블록으로 감싸서 이를 지나 계속 진행하십시오. [결과 처리](/docs/ko/agent-sdk/agent-loop#handle-the-result)에서 오류 계약을 참조하십시오.

3885</Note>3885</Note>

3886 3886 

3887샌드박스된 명령이 파일에 쓰지 못하도록 하려면, 샌드박스 설정의 [`denyWrite`](/docs/ko/settings-reference#sandbox-filesystem-denywrite) 아래에 해당 파일의 절대 경로를 나열하십시오(예: `"filesystem": {"denyWrite": ["/home/user/project/.env"]}`). SDK는 선언된 `SandboxSettings` 필드와 함께 `filesystem`을 Claude Code로 전달합니다. 샌드박스가 시작되면 나열된 각 경로에 대한 쓰기를 차단합니다. `.env` 또는 `./.env`를 나열하면, 샌드박스된 명령은 세션의 작업 디렉터리에 있는 `.env` 파일에 쓸 수 있습니다.

3888 

3887<h4 id="example-usage">3889<h4 id="example-usage">

3888 사용 예제3890 사용 예제

3889</h4>3891</h4>

557[Claude Code Skills 가이드](/docs/ko/skills)는 심층적인 작성을 다룹니다. 해당 지침은 SDK 세션에 적용됩니다. 다음 섹션부터 시작하십시오:557[Claude Code Skills 가이드](/docs/ko/skills)는 심층적인 작성을 다룹니다. 해당 지침은 SDK 세션에 적용됩니다. 다음 섹션부터 시작하십시오:

558 558 

559* [Frontmatter 참조](/docs/ko/skills#frontmatter-reference): 지원되는 모든 필드559* [Frontmatter 참조](/docs/ko/skills#frontmatter-reference): 지원되는 모든 필드

560* [Skills에 인수 전달하기](/docs/ko/skills#pass-arguments-to-skills): `$ARGUMENTS`, `$0`, `$1` 및 Skill 스택. [전체 대체 테이블](/docs/ko/skills#available-string-substitutions)은 명명된 인수 및 `${CLAUDE_*}` 변수를 추가합니다560* [스킬에 인수 전달하기](/docs/ko/skills#pass-arguments-to-skills): `$ARGUMENTS`, `$0`, `$1`. [전체 대체 테이블](/docs/ko/skills#available-string-substitutions)은 명명된 인수 및 `${CLAUDE_*}` 변수를 추가합니다

561* [동적 컨텍스트 주입하기](/docs/ko/skills#inject-dynamic-context): Claude가 Skill 콘텐츠를 보기 전에 실행되는 `` !`command` `` 라인561* [동적 컨텍스트 주입하기](/docs/ko/skills#inject-dynamic-context): Claude가 Skill 콘텐츠를 보기 전에 실행되는 `` !`command` `` 라인

562* [Skills가 로드되는 위치 선택하기](/docs/ko/skills#where-skills-live): 모든 Skill 위치, 플러그인 네임스페이싱 및 두 개가 이름을 공유할 때 어느 것이 실행되는지562* [Skills가 로드되는 위치 선택하기](/docs/ko/skills#where-skills-live): 모든 Skill 위치, 플러그인 네임스페이싱 및 두 개가 이름을 공유할 때 어느 것이 실행되는지

563 563 

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

6367| :- | :- | :- | :- |6367| :- | :- | :- | :- |

6368| `allowWrite` | `string[]` | `[]` | 쓰기 액세스를 허용할 파일 경로 패턴 |6368| `allowWrite` | `string[]` | `[]` | 쓰기 액세스를 허용할 파일 경로 패턴 |

6369| `denyWrite` | `string[]` | `[]` | 쓰기 액세스를 거부할 파일 경로 패턴 |6369| `denyWrite` | `string[]` | `[]` | 쓰기 액세스를 거부할 파일 경로 패턴입니다. 세션의 작업 디렉터리에 있는 파일에 대한 샌드박스된 쓰기를 차단하려면 해당 파일의 절대 경로를 나열합니다. `.env` 또는 `./.env`를 나열하면 샌드박스된 명령이 세션의 작업 디렉터리에 있는 `.env` 파일에 쓸 수 있습니다 |

6370| `denyRead` | `string[]` | `[]` | 읽기 액세스를 거부할 파일 경로 패턴 |6370| `denyRead` | `string[]` | `[]` | 읽기 액세스를 거부할 파일 경로 패턴 |

6371 6371 

6372<h3 id="permissions-fallback-for-unsandboxed-commands">6372<h3 id="permissions-fallback-for-unsandboxed-commands">

231 231 

232리더는 종료 요청을 보냅니다. 팀원은 승인하여 우아하게 종료하거나 설명과 함께 거부할 수 있습니다.232리더는 종료 요청을 보냅니다. 팀원은 승인하여 우아하게 종료하거나 설명과 함께 거부할 수 있습니다.

233 233 

234팀의 공유 디렉토리는 세션이 끝날 때 자동으로 정리되므로, 별도의 정리 단계가 없습니다. 어떤 디렉토리가 제거되고 어떤 디렉토리가 재개된 세션을 위해 유지되는지는 [아키텍처](#architecture)를 참조합니다.234팀의 공유 디렉토리는 세션이 끝날 때 자동으로 정리되므로, 별도의 정리 단계가 없습니다. 어떤 디렉토리가 제거되고 어떤 디렉토리가 디스크에 유지되는지는 [아키텍처](#architecture)를 참조합니다.

235 235 

236<h3 id="enforce-quality-gates-with-hooks">236<h3 id="enforce-quality-gates-with-hooks">

237 hooks로 품질 게이트 적용237 hooks로 품질 게이트 적용

278 278 

279팀과 작업은 세션 파생 이름으로 로컬에 저장됩니다. 이름은 `session-` 뒤에 세션 ID의 처음 8자가 붙습니다:279팀과 작업은 세션 파생 이름으로 로컬에 저장됩니다. 이름은 `session-` 뒤에 세션 ID의 처음 8자가 붙습니다:

280 280 

281* **팀 구성**: `~/.claude/teams/{team-name}/config.json`281* **팀 구성**: `~/.claude/teams/{team-name}/config.json`. Claude Code는 세션이 끝날 때 팀 구성 디렉토리를 제거합니다.

282* **작업 목록**: `~/.claude/tasks/{team-name}/`282* **작업 목록**: `~/.claude/tasks/{team-name}/`. 이 디렉토리는 세션이 끝난 후에도 디스크에 남아 있습니다. [Claude Code가 이를 보관하는 기간](/docs/ko/claude-directory#cleaned-up-automatically)을 변경하려면 [`cleanupPeriodDays`](/docs/ko/settings-reference#cleanupperioddays)를 설정합니다.

283 283 

284Claude Code는 세션 시작 시 이 둘을 자동으로 생성하고 팀원들이 참여하거나, 유휴 상태가 되거나, 떠날 때 업데이트합니다. 팀 구성 디렉토리는 세션이 끝날 때 제거됩니다. 작업 목록 디렉토리는 로컬에 유지되며 절대 업로드되지 않으므로, 재개된 세션은 작업을 유지합니다. 보존은 세션 트랜스크립트에 대해 이미 제어하는 것과 동일한 [`cleanupPeriodDays`](/docs/ko/settings-reference#cleanupperioddays)에 의해 관리되며, [보존 정리 규칙](/docs/ko/claude-directory#cleaned-up-automatically)을 따릅니다.284Claude Code는 세션 시작 시 이 둘을 자동으로 생성하고 팀원들이 참여하거나, 유휴 상태가 되거나, 떠날 때 업데이트합니다.

285 285 

286팀 구성은 세션 ID 및 tmux 창 ID와 같은 런타임 상태를 보유하므로, 수동으로 편집하거나 사전 작성하지 마십시오: 다음 상태 업데이트에서 변경 사항이 덮어씌워집니다.286팀 구성은 세션 ID 및 tmux 창 ID와 같은 런타임 상태를 보유하므로, 수동으로 편집하거나 사전 작성하지 마십시오: 다음 상태 업데이트에서 변경 사항이 덮어씌워집니다.

287 287 

325 325 

326두 번째 누름은 예를 들어 [백그라운드 서비스가 응답하지 않아](#agent-view-says-the-background-service-did-not-respond) 중지 시도가 실패할 때도 세션을 삭제합니다: 확인은 2초 더 활성 상태로 유지되고, 삭제는 세션의 프로세스를 직접 종료합니다. 삭제하지 않고 확인을 닫으려면 `Esc`를 누릅니다.326두 번째 누름은 예를 들어 [백그라운드 서비스가 응답하지 않아](#agent-view-says-the-background-service-did-not-respond) 중지 시도가 실패할 때도 세션을 삭제합니다: 확인은 2초 더 활성 상태로 유지되고, 삭제는 세션의 프로세스를 직접 종료합니다. 삭제하지 않고 확인을 닫으려면 `Esc`를 누릅니다.

327 327 

328[세션 삭제가 제거하는 것](#what-deleting-a-session-removes)에서 다루는 유지되는 경우를 제외하고, 삭제하면 세션이 목록에서 제거되고, Claude가 생성한 worktree는 삭제 방법과 worktree가 보유한 내용에 따라 제거, 유지 또는 제자리에 남겨집니다. 대화 트랜스크립트는 항상 로컬 머신에 남아 있으며 `claude --resume`을 통해 사용할 수 있습니다.328[세션 삭제가 제거하는 것](#what-deleting-a-session-removes)에서 다루는 유지되는 경우를 제외하고, 삭제하면 세션이 목록에서 제거되고, Claude가 생성한 worktree는 삭제 방법과 worktree가 보유한 내용에 따라 제거, 유지 또는 제자리에 남겨집니다. 대화 트랜스크립트는 로컬 머신에 남아 있으며 `claude --resume`을 통해 사용할 수 있습니다.

329 329 

330Claude Code v2.1.212 이상에서 세션을 다시 가져오려면 디스패치 입력에 `/resume`을 입력합니다. 피커가 열리며 에이전트 뷰를 연 저장소의 과거 세션이 최신순으로 표시되며, 목록에서 삭제한 세션을 포함합니다. 이미 행이 있는 세션은 나열되지 않습니다. `↑`/`↓`는 선택을 이동하고, `Enter`는 선택된 세션을 백그라운드 세션으로 재개하여 목록에 행으로 다시 추가하고, `Esc`는 피커를 닫습니다.330Claude Code v2.1.212 이상에서 세션을 다시 가져오려면 디스패치 입력에 `/resume`을 입력합니다. 피커가 열리며 에이전트 뷰를 연 저장소의 과거 세션이 최신순으로 표시되며, 목록에서 삭제한 세션을 포함합니다. 이미 행이 있는 세션은 나열되지 않습니다. `↑`/`↓`는 선택을 이동하고, `Enter`는 선택된 세션을 백그라운드 세션으로 재개하여 목록에 행으로 다시 추가하고, `Esc`는 피커를 닫습니다.

331 331 

12We're changing auto mode to no longer charge for classifier requests in Claude Code. However, this session isn't eligible.12We're changing auto mode to no longer charge for classifier requests in Claude Code. However, this session isn't eligible.

13```13```

14 14 

15프롬프트에서 Claude Code는 이러한 방식으로 검사할 첫 번째 작업을 답변할 때까지 보류합니다. 아무것도 손상되지 않습니다: 자동 모드는 계속 작동하며, 분류기 요청은 이전과 같이 청구됩니다. 가장 일반적인 원인은 Claude Code와 API 사이의 LLM 게이트웨이 또는 프록시이며, Claude Code가 하나를 식별할 수 있을 때 공지는 이를 명시합니다. **Enter**를 눌러 계속하거나, [세션을 적합하게 만들기](#make-the-session-eligible)를 참조하여 새 세션에서 나타나지 않도록 합니다.15프롬프트에서 Claude Code는 이러한 방식으로 검사할 첫 번째 작업을 답변할 때까지 보류합니다. 자동 모드는 계속 작동하며, 분류기 요청은 이전과 같이 청구됩니다.

16 

17가장 일반적인 원인은 Claude Code와 API 사이의 LLM 게이트웨이 또는 프록시이며, Claude Code가 하나를 식별할 수 있을 때 공지는 이를 명시합니다. **Enter**를 눌러 계속하거나, [세션을 적합하게 만들기](#make-the-session-eligible)를 참조하여 새 세션에서 나타나지 않도록 합니다.

16 18 

17<h2 id="respond-to-the-notice">19<h2 id="respond-to-the-notice">

18 공지에 응답하기20 공지에 응답하기

45 설치가 실패하면 Claude Code가 보고하는 메시지와 일치시킵니다:45 설치가 실패하면 Claude Code가 보고하는 메시지와 일치시킵니다:

46 46 

47 * `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 다음 설치를 다시 시도합니다.47 * `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 다음 설치를 다시 시도합니다.

48 * 플러그인이 [마켓플레이스에서 찾을 수 없음](/docs/ko/plugins/install#install-a-plugin): 플러그인 이름을 확인합니다.48 * `Plugin "<name>" not found in marketplace "claude-plugins-official"`: 로컬에 있는 마켓플레이스 카탈로그 사본이 오래되었을 수 있습니다. `/plugin marketplace update claude-plugins-official`로 새로 고친 다음 설치를 다시 시도합니다. 재시도 후에도 같은 메시지가 출력되면 [마켓플레이스에서 플러그인을 찾을 수 없음](/docs/ko/plugins/troubleshooting#plugin-not-found-in-marketplace)을 참조하세요.

49 49 

50 설치에서 설치 범위를 요청할 때 사용자 범위 옵션을 선택하여 플러그인이 모든 프로젝트에서 사용 가능하도록 합니다. 설치 요약을 확인합니다. `Run /reload-plugins to apply.`를 보고하면 [플러그인 변경 사항을 다시 시작하지 않고 적용](/docs/ko/plugins/cli-reference#reload-plugins)을 참조하여 플러그인의 구성 명령을 사용 가능하게 합니다.50 설치에서 설치 범위를 요청할 때 사용자 범위 옵션을 선택하여 플러그인이 모든 프로젝트에서 사용 가능하도록 합니다. 설치 요약을 확인합니다. `Run /reload-plugins to apply.`를 보고하면 [플러그인 변경 사항을 다시 시작하지 않고 적용](/docs/ko/plugins/cli-reference#reload-plugins)을 참조하여 플러그인의 구성 명령을 사용 가능하게 합니다.

51 </Step>51 </Step>

123 설치가 실패하면 Claude Code가 보고하는 메시지와 일치시킵니다:123 설치가 실패하면 Claude Code가 보고하는 메시지와 일치시킵니다:

124 124 

125 * `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 다음 설치를 다시 시도합니다.125 * `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 다음 설치를 다시 시도합니다.

126 * 플러그인이 [마켓플레이스에서 찾을 수 없음](/docs/ko/plugins/install#install-a-plugin): 플러그인 이름을 확인합니다.126 * `Plugin "<name>" not found in marketplace "claude-plugins-official"`: 로컬에 있는 마켓플레이스 카탈로그 사본이 오래되었을 수 있습니다. `/plugin marketplace update claude-plugins-official`로 새로 고친 다음 설치를 다시 시도합니다. 재시도 후에도 같은 메시지가 출력되면 [마켓플레이스에서 플러그인을 찾을 수 없음](/docs/ko/plugins/troubleshooting#plugin-not-found-in-marketplace)을 참조하세요.

127 127 

128 설치에서 설치 범위를 요청할 때 사용자 범위 옵션을 선택하여 플러그인이 모든 프로젝트에서 사용 가능하도록 합니다. 설치 요약을 확인합니다. `Run /reload-plugins to apply.`를 보고하면 [플러그인 변경 사항을 다시 시작하지 않고 적용](/docs/ko/plugins/cli-reference#reload-plugins)을 참조하여 플러그인의 구성 명령을 사용 가능하게 합니다.128 설치에서 설치 범위를 요청할 때 사용자 범위 옵션을 선택하여 플러그인이 모든 프로젝트에서 사용 가능하도록 합니다. 설치 요약을 확인합니다. `Run /reload-plugins to apply.`를 보고하면 [플러그인 변경 사항을 다시 시작하지 않고 적용](/docs/ko/plugins/cli-reference#reload-plugins)을 참조하여 플러그인의 구성 명령을 사용 가능하게 합니다.

129 </Step>129 </Step>

188 설치가 실패하면 Claude Code가 보고하는 메시지와 일치시킵니다:188 설치가 실패하면 Claude Code가 보고하는 메시지와 일치시킵니다:

189 189 

190 * `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 다음 설치를 다시 시도합니다.190 * `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 다음 설치를 다시 시도합니다.

191 * 플러그인이 [마켓플레이스에서 찾을 수 없음](/docs/ko/plugins/install#install-a-plugin): 플러그인 이름을 확인합니다.191 * `Plugin "<name>" not found in marketplace "claude-plugins-official"`: 로컬에 있는 마켓플레이스 카탈로그 사본이 오래되었을 수 있습니다. `/plugin marketplace update claude-plugins-official`로 새로 고친 다음 설치를 다시 시도합니다. 재시도 후에도 같은 메시지가 출력되면 [마켓플레이스에서 플러그인을 찾을 수 없음](/docs/ko/plugins/troubleshooting#plugin-not-found-in-marketplace)을 참조하세요.

192 192 

193 설치에서 설치 범위를 요청할 때 사용자 범위 옵션을 선택하여 플러그인이 모든 프로젝트에서 사용 가능하도록 합니다.193 설치에서 설치 범위를 요청할 때 사용자 범위 옵션을 선택하여 플러그인이 모든 프로젝트에서 사용 가능하도록 합니다.

194 194 

226 빠른 시작226 빠른 시작

227</h2>227</h2>

228 228 

229Fakechat은 localhost에서 채팅 UI를 실행하는 공식적으로 지원되는 데모 채널이며 인증할 것도 없고 구성할 외부 서비스도 없습니다.229Fakechat은 공식적으로 지원되는 데모 채널로, localhost에서 채팅 UI를 실행하며 인증할 항목이나 구성할 외부 서비스가 없습니다.

230 230 

231fakechat을 설치하고 활성화한 후 브라우저에서 입력하면 메시지가 Claude Code 세션에 도착합니다. Claude가 회신하면 회신이 브라우저로 돌아옵니다. fakechat 인터페이스를 테스트한 후 [Telegram](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram), [Discord](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/discord) 또는 [iMessage](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/imessage)를 시도해 보세요.231fakechat을 설치하고 활성화하면 브라우저에 입력한 메시지가 Claude Code 세션에 도착합니다. Claude가 응답하면 그 응답이 다시 브라우저에 표시됩니다. fakechat 인터페이스를 테스트한 후에는 [Telegram](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram), [Discord](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/discord) 또는 [iMessage](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/imessage)를 사용해 보십시오.

232 232 

233fakechat 데모를 시도하려면 다음이 필요합니다:233fakechat 데모를 사용해 보려면 다음이 필요합니다.

234 234 

235* Claude Code [설치 및 인증](/docs/ko/quickstart#step-1-install-claude-code): claude.ai 계정 또는 Claude Console API 키 사용235* claude.ai 계정 또는 Claude Console API 키로 [설치 및 인증](/docs/ko/quickstart#step-1-install-claude-code)된 Claude Code

236* [Bun](https://bun.sh) 설치됨. 사전 구축된 채널 플러그인은 Bun 스크립트입니다. `bun --version`으로 확인하세요. 실패하면 [Bun 설치](https://bun.sh/docs/installation)하세요.236* [Bun](https://bun.sh) 설치. 사전 빌드된 채널 플러그인은 Bun 스크립트입니다. `bun --version`으로 확인하고, 실패하면 [Bun을 설치](https://bun.sh/docs/installation)하십시오.

237* **Team, Enterprise 또는 관리 Console 조직**: 조직 관리자가 관리 설정에서 [채널을 활성화](#enterprise-controls)해야 합니다.237* **Team, Enterprise 또는 관리형 Console 조직**: 관리자가 관리형 설정에서 [채널을 활성화](#enterprise-controls)해야 합니다

238 238 

239<Steps>239<Steps>

240 <Step title="fakechat 채널 플러그인 설치">240 <Step title="fakechat 채널 플러그인 설치">

241 터미널에서 `claude`를 실행하여 Claude Code를 시작한 다음 프롬프트에 설치 명령을 입력합니다:241 터미널에서 `claude`를 실행하여 Claude Code를 시작한 다음, 프롬프트에 설치 명령을 입력합니다.

242 242 

243 ```text theme={null}243 ```text theme={null}

244 /plugin install fakechat@claude-plugins-official244 /plugin install fakechat@claude-plugins-official

245 ```245 ```

246 246 

247 설치가 실패하면 Claude Code가 보고하는 메시지와 일치시킵니다:247 설치에 실패하면 Claude Code가 보고하는 메시지에 맞게 조치합니다.

248 248 

249 * `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 다음 설치를 다시 시도합니다.249 * `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 다음 설치를 재시도합니다.

250 * 플러그인이 [마켓플레이스에서 찾을 수 없음](/docs/ko/plugins/install#install-a-plugin): 플러그인 이름을 확인합니다.250 * `Plugin "<name>" not found in marketplace "claude-plugins-official"`: 마켓플레이스 카탈로그의 로컬 사본이 오래되었을 수 있습니다. `/plugin marketplace update claude-plugins-official`로 새로 고친 다음 설치를 재시도합니다. 재시도 후에도 같은 메시지가 출력되면 [Plugin not found in marketplace](/docs/ko/plugins/troubleshooting#plugin-not-found-in-marketplace)를 참조하십시오.

251 251 

252 설치에서 설치 범위를 요청할 때 사용자 범위 옵션을 선택하여 플러그인이 모든 프로젝트에서 사용 가능하도록 합니다.252 설치 과정에서 설치 범위를 묻는 경우, 모든 프로젝트에서 플러그인을 사용할 수 있도록 사용자 범위 옵션을 선택합니다.

253 253 

254 설치 요약에서 `Run /reload-plugins to apply.`를 보고하면 다음 단계에서 다시 시작할 때 플러그인을 선택하므로 여기서는 조치할 필요가 없습니다.254 설치 요약에 `Run /reload-plugins to apply.`가 표시되더라도 여기서는 조치할 필요가 없습니다. 다음 단계에서 재시작하면 플러그인이 로드되기 때문입니다.

255 </Step>255 </Step>

256 256 

257 <Step title="채널이 활성화된 상태로 다시 시작">257 <Step title="채널을 활성화하여 재시작">

258 Claude Code를 종료한 다음 `--channels`로 다시 시작하고 설치한 fakechat 플러그인을 전달합니다:258 Claude Code를 종료한 다음, `--channels`와 함께 설치한 fakechat 플러그인을 전달하여 재시작합니다.

259 259 

260 ```bash theme={null}260 ```bash theme={null}

261 claude --channels plugin:fakechat@claude-plugins-official261 claude --channels plugin:fakechat@claude-plugins-official

262 ```262 ```

263 263 

264 fakechat 서버가 자동으로 시작됩니다. 시작 화면에는 `plugin:fakechat@claude-plugins-official`의 메시지가 이 세션에 직접 주입된다는 채널 공지가 표시됩니다. 플러그인이 설치되지 않았거나 승인된 허용 목록에 없으면 문제를 명시하는 경고 줄이 해당 공지 아래에 나타납니다.264 fakechat 서버가 자동으로 시작됩니다. 시작 화면에는 `plugin:fakechat@claude-plugins-official`의 메시지가 이 세션에 직접 주입된다는 채널 안내가 표시됩니다. 플러그인이 설치되지 않았거나 승인된 허용 목록에 없으면, 해당 안내 아래에 문제를 명시한 경고 줄이 나타납니다.

265 265 

266 <Tip>266 <Tip>

267 `--channels`에 여러 플러그인을 공백으로 구분하여 전달할 수 있습니다.267 `--channels`에 여러 플러그인을 공백으로 구분하여 전달할 수 있습니다.

268 </Tip>268 </Tip>

269 </Step>269 </Step>

270 270 

271 <Step title="메시지 푸시">271 <Step title="메시지 보내기">

272 [http://localhost:8787](http://localhost:8787)에서 fakechat UI를 열고 메시지를 입력합니다:272 [http://localhost:8787](http://localhost:8787)에서 fakechat UI를 열고 메시지를 입력합니다.

273 273 

274 ```text theme={null}274 ```text theme={null}

275 what's in my working directory?275 what's in my working directory?

276 ```276 ```

277 277 

278 메시지가 Claude Code 세션에 도착합니다. 터미널에는 `← fakechat · web: what's in my working directory?`와 같은 인바운드 채널 줄로 표시되며, 모델은 플러그인의 범위가 지정된 서버 이름을 사용하여 `<channel source="plugin:fakechat:fakechat">` 이벤트로 수신합니다. Claude가 읽고 작업을 수행한 다음 fakechat의 `reply` 도구를 호출합니다. Claude Code가 첫 번째 회신에 대한 권한을 요청하면 승인합니다. 답변이 채팅 UI에 나타납니다.278 메시지가 Claude Code 세션에 도착합니다. 터미널에는 `← fakechat · web: what's in my working directory?`와 같은 수신 채널 줄로 표시되며, 모델은 플러그인의 범위가 지정된 서버 이름을 사용하는 `<channel source="plugin:fakechat:fakechat">` 이벤트로 이를 수신합니다. Claude는 메시지를 읽고 작업을 수행한 뒤 fakechat의 `reply` 도구를 호출합니다. Claude Code가 첫 번째 응답에 대한 권한을 요청하면 승인하십시오. 답변이 채팅 UI에 표시됩니다.

279 </Step>279 </Step>

280</Steps>280</Steps>

281 281 

282Claude가 터미널에서 멀리 있을 때 권한 프롬프트에 도달하면 세션이 응답할 때까지 일시 중지됩니다. [권한 릴레이 기능](/docs/ko/channels-reference#relay-permission-prompts)을 선언하는 채널 서버는 이러한 프롬프트를 사용자에게 전달하여 원격으로 승인하거나 거부할 수 있습니다. 무인 사용의 경우 [`--dangerously-skip-permissions`](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)는 대부분의 프롬프트를 우회하지만 신뢰하는 환경에서만 사용하세요. 그렇더라도 [actions no 모드 자동 승인](/docs/ko/permission-modes#actions-no-mode-auto-approves)은 여전히 적용됩니다.282사용자가 터미널을 비운 사이 Claude가 권한 프롬프트를 만나면, 사용자가 응답할 때까지 세션이 일시 중지됩니다. [권한 릴레이 기능](/docs/ko/channels-reference#relay-permission-prompts)을 선언한 채널 서버는 이러한 프롬프트를 사용자에게 전달하여 원격으로 승인하거나 거부할 수 있게 합니다. 무인 사용의 경우 [`--dangerously-skip-permissions`](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)를 사용하면 대부분의 프롬프트를 건너뛸 수 있지만, 신뢰할 수 있는 환경에서만 사용하십시오. 그렇더라도 [어떤 모드에서도 자동 승인되지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves)은 여전히 적용됩니다.

283 283 

284비대화형 모드에서 `-p`로 채널을 실행할 때 여러 선택지 질문 및 계획 모드 승인과 같이 터미널 입력이 필요한 도구는 비활성화되므로 세션이 입력을 기다리며 멈추지 않습니다.284`-p`를 사용하여 비대화형 모드로 채널을 실행하면, 객관식 질문이나 플랜 모드 승인처럼 터미널 입력이 필요한 도구는 비활성화되므로 세션이 입력을 기다리며 멈추는 일이 없습니다.

285 285 

286<h2 id="security">286<h2 id="security">

287 보안287 보안

290 note: commandsNote,290 note: commandsNote,

291 when: <>User types <C>/command-name</C></>,291 when: <>User types <C>/command-name</C></>,

292 description: <>A file at <C>commands/deploy.md</C> creates <C>/deploy</C> the same way a skill at <C>skills/deploy/SKILL.md</C> does, and both can be auto-invoked by Claude. Skills use a directory with SKILL.md, letting you bundle reference docs, templates, or scripts alongside the prompt.</>,292 description: <>A file at <C>commands/deploy.md</C> creates <C>/deploy</C> the same way a skill at <C>skills/deploy/SKILL.md</C> does, and both can be auto-invoked by Claude. Skills use a directory with SKILL.md, letting you bundle reference docs, templates, or scripts alongside the prompt.</>,

293 tips: [<>Use <C>$ARGUMENTS</C> in the file to accept parameters: <C>/fix-issue 123</C></>, 'If a skill and command share a name, the skill takes precedence', 'New commands should usually be skills instead; commands remain supported'],293 tips: [<>Use <C>$ARGUMENTS</C> in the file to accept parameters: <C>/fix-issue 123</C></>, 'If a skill and command share a name, the skill takes precedence', 'New commands should usually be skills instead; command files still work'],

294 docsLink: '/en/skills',294 docsLink: '/en/skills',

295 children: [{295 children: [{

296 id: 'cmd-example',296 id: 'cmd-example',

48 48 

49명령은 플러그인의 세부 정보를 열며, 여기서 [설치 범위](/docs/ko/plugins/install#install-a-plugin)를 선택하여 설치를 시작합니다.49명령은 플러그인의 세부 정보를 열며, 여기서 [설치 범위](/docs/ko/plugins/install#install-a-plugin)를 선택하여 설치를 시작합니다.

50 50 

51설치가 실패하면 Claude Code가 보고하는 메시지에 따라 수정 방법이 달라집니다:51설치가 실패하면 Claude Code가 보고하는 메시지에 맞는 방법을 따르세요:

52 52 

53* `Marketplace "claude-plugins-official" not found`를 보고하면 `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 후 설치를 다시 시도하세요.53* `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 후 설치를 다시 시도하세요.

54* [마켓플레이스에서 플러그인을 찾을 수 없다](/docs/ko/plugins/install#install-a-plugin)고 보고하면 플러그인 이름에 오타가 없는지 확인하세요.54* `Plugin "claude-security" not found in marketplace "claude-plugins-official"`: 로컬에 있는 마켓플레이스 카탈로그 사본이 오래되었을 수 있습니다. `/plugin marketplace update claude-plugins-official`로 카탈로그를 새로 고친 후 설치를 다시 시도하세요. 재시도 시에도 같은 메시지가 출력되면 [Plugin not found in marketplace](/docs/ko/plugins/troubleshooting#plugin-not-found-in-marketplace)를 참조하세요.

55 55 

56설치 요약을 확인하세요. `Run /reload-plugins to apply.`를 보고하면 [재시작 없이 플러그인 변경 사항 적용](/docs/ko/plugins/cli-reference#reload-plugins)을 참조하여 현재 세션에서 플러그인을 활성화하세요.56설치 요약을 확인하세요. `Run /reload-plugins to apply.`를 보고하면 [재시작 없이 플러그인 변경 사항 적용](/docs/ko/plugins/cli-reference#reload-plugins)을 참조하여 현재 세션에서 플러그인을 활성화하세요.

57 57 

118effort 수준과 플래그 뒤에서 Claude Code는 줄의 나머지 부분을 리뷰 대상으로 읽습니다. `ultra` 인수는 이 해석 방식을 변경합니다.118effort 수준과 플래그 뒤에서 Claude Code는 줄의 나머지 부분을 리뷰 대상으로 읽습니다. `ultra` 인수는 이 해석 방식을 변경합니다.

119 119 

120* **`ultra` 사용 시**: Claude Code는 단일 단어를 기본 브랜치 또는 PR 번호로 읽습니다. 브랜치나 PR을 지정하지 않는 더 긴 텍스트는 [리뷰에 첨부되는 메모](/docs/ko/ultrareview#pass-a-request-in-plain-words)가 됩니다. `/code-review ultra check my auth changes`는 현재 브랜치를 리뷰하며, Claude는 발견 사항을 메모와 연관 지어 설명합니다.120* **`ultra` 사용 시**: Claude Code는 단일 단어를 기본 브랜치 또는 PR 번호로 읽습니다. 브랜치나 PR을 지정하지 않는 더 긴 텍스트는 [리뷰에 첨부되는 메모](/docs/ko/ultrareview#pass-a-request-in-plain-words)가 됩니다. `/code-review ultra check my auth changes`는 현재 브랜치를 리뷰하며, Claude는 발견 사항을 메모와 연관 지어 설명합니다.

121* **`ultra` 미사용 시**: 남은 모든 내용은 다른 명령 이름으로 시작하더라도 리뷰 대상이 됩니다. `/code-review /fix-issue 123`은 `/fix-issue`를 두 번째 [스택 스킬](/docs/ko/skills#pass-arguments-to-skills)로 로드하는 대신 `/fix-issue 123`을 대상 텍스트로 하여 리뷰합니다. v2.1.218 이전에는 `/code-review` 뒤에 스택된 명령이 자체 스킬로 확장되었습니다.121* **`ultra` 미사용 시**: 남은 모든 내용은 다른 명령 이름으로 시작하더라도 리뷰 대상이 됩니다. `/code-review /fix-issue 123`은 `/fix-issue`를 두 번째 [스택 스킬](/docs/ko/skills#stack-several-skills-in-one-message)로 로드하는 대신 `/fix-issue 123`을 대상 텍스트로 하여 리뷰합니다. v2.1.218 이전에는 `/code-review` 뒤에 스택된 명령이 자체 스킬로 확장되었습니다.

122 122 

123<h2 id="run-in-the-foreground">123<h2 id="run-in-the-foreground">

124 포그라운드에서 실행124 포그라운드에서 실행

10 10 

11`/`를 입력하면 사용 가능한 명령을 볼 수 있으며, `/` 뒤에 글자를 입력하면 목록을 필터링할 수 있습니다. [명령 메뉴가 입력 내용과 일치하는 항목을 찾는 방식](#how-the-command-menu-matches-what-you-type)에서는 강조 표시, 오타 처리, 그리고 Claude Code가 전체 이름을 입력하기 전까지 메뉴에서 숨기는 몇 가지 명령에 대해 설명합니다.11`/`를 입력하면 사용 가능한 명령을 볼 수 있으며, `/` 뒤에 글자를 입력하면 목록을 필터링할 수 있습니다. [명령 메뉴가 입력 내용과 일치하는 항목을 찾는 방식](#how-the-command-menu-matches-what-you-type)에서는 강조 표시, 오타 처리, 그리고 Claude Code가 전체 이름을 입력하기 전까지 메뉴에서 숨기는 몇 가지 명령에 대해 설명합니다.

12 12 

13명령은 메시지의 시작 부분에 있을 때만 인식됩니다. 명령 이름 뒤에 오는 텍스트는 해당 명령의 인수가 됩니다. [스킬](/docs/ko/skills#pass-arguments-to-skills)은 예외입니다. `/skill-a /skill-b do XYZ`처럼 스킬 호출 뒤에 다른 스킬이 이어지면, 시작 부분에 지정된 스킬을 로드하고 뒤따르는 텍스트를 각 스킬에 인수로 전달합니다. 최대 6개의 스킬을 연결할 수 있습니다.13명령은 메시지의 시작 부분에 있을 때만 인식됩니다. 명령 이름 뒤에 오는 텍스트는 해당 명령의 인수가 됩니다. 터미널 프롬프트에서는 하나의 메시지를 여러 [스킬](/docs/ko/skills#stack-several-skills-in-one-message)로 시작할 수 있습니다. `/skill-a /skill-b do XYZ`를 입력하면 두 스킬을 모두 로드하고 뒤따르는 텍스트를 각 스킬에 인수로 전달합니다. 최대 6개의 스킬을 연결할 수 있습니다.

14 14 

15Claude가 응답하는 중에 명령을 보내면 Claude Code는 해당 명령을 대기열에 추가하고 현재 턴이 끝난 후 실행합니다. `/status`, `/tasks`, `/usage`와 같은 일부 명령은 응답을 중단하지 않고 즉시 실행됩니다. [전체 화면 렌더링](/docs/ko/fullscreen)에서는 `/theme`, `/help`와 같은 대화 상자 명령도 즉시 열립니다. v2.1.234 이전에는 Claude Code가 이러한 대화 상자를 턴이 끝날 때까지 대기열에 보관했습니다.15Claude가 응답하는 중에 명령을 보내면 Claude Code는 해당 명령을 대기열에 추가하고 현재 턴이 끝난 후 실행합니다. `/status`, `/tasks`, `/usage`와 같은 일부 명령은 응답을 중단하지 않고 즉시 실행됩니다. [전체 화면 렌더링](/docs/ko/fullscreen)에서는 `/theme`, `/help`와 같은 대화 상자 명령도 즉시 열립니다. v2.1.234 이전에는 Claude Code가 이러한 대화 상자를 턴이 끝날 때까지 대기열에 보관했습니다.

16 16 

1137</Warning>1137</Warning>

1138 1138 

1139* **절전 또는 네트워크 끊김 후**: 프로세스가 [여전히 실행 중](#limits-while-desktop-is-disconnected)이고 Desktop이 프롬프트 없이 로그인할 수 있으면 실행 중인 작업을 되찾을 수 있습니다. 그렇지 않으면 [메시지를 보내세요](#reconnect-after-sleep-or-a-network-loss).1139* **절전 또는 네트워크 끊김 후**: 프로세스가 [여전히 실행 중](#limits-while-desktop-is-disconnected)이고 Desktop이 프롬프트 없이 로그인할 수 있으면 실행 중인 작업을 되찾을 수 있습니다. 그렇지 않으면 [메시지를 보내세요](#reconnect-after-sleep-or-a-network-loss).

1140* **종료 후, macOS 또는 Linux의 Desktop과 Claude 계정을 사용하는 경우**: Desktop이 [프로세스에 다시 합류](#reopen-a-session-after-you-quit-desktop)할 수 있으면 실행 중인 작업을 되찾을 수 있습니다. 그렇지 않으면 작업이 중지됩니다. 계속 중지된 상태라면 메시지를 보내세요.1140* **종료 후**: 작업은 계속 실행되지만, Desktop이 해당 프로세스에 다시 연결할 수 없으면 세션이 다시 열릴 때 작업을 잃습니다. 종료하기 전에 [Desktop이 다시 연결할 수 있는 경우](#reopen-a-session-after-you-quit-desktop)를 확인합니다. 작업을 잃었다면 메시지를 보내 계속합니다.

1141* **종료 후, Windows의 Desktop 또는 [타사 제공업체](/docs/ko/third-party-integrations)를 사용하는 경우**: 세션이 열릴 때 Desktop이 프로세스를 종료하므로 실행 중인 작업을 잃게 됩니다. 계속하려면 메시지를 보내세요.

1142 1141 

1143돌아왔을 때 작업이 완료되지 않았다면 Desktop이 다시 연결할 수 없다는 안내, 인증 오류 또는 대기 중인 요청이 있는지 확인하세요:1142돌아왔을 때 작업이 완료되지 않았다면 Desktop이 다시 연결할 수 없다는 안내, 인증 오류 또는 대기 중인 요청이 있는지 확인하세요:

1144 1143 

1154</h5>1153</h5>

1155 1154 

1156* **먼저 업데이트**: 긴 작업을 시작하기 전에 Desktop을 업데이트하세요. macOS와 Windows에서 Desktop은 다운로드한 업데이트를 설치하기 위해 자동으로 재시작할 수 있습니다. 이 재시작은 Claude가 SSH 작업을 수행하는 동안 대기합니다. Claude 계정을 사용하는 macOS에서는 기본적으로 업데이트가 72시간 동안 대기한 후에는 재시작이 그대로 진행될 수 있습니다.1155* **먼저 업데이트**: 긴 작업을 시작하기 전에 Desktop을 업데이트하세요. macOS와 Windows에서 Desktop은 다운로드한 업데이트를 설치하기 위해 자동으로 재시작할 수 있습니다. 이 재시작은 Claude가 SSH 작업을 수행하는 동안 대기합니다. Claude 계정을 사용하는 macOS에서는 기본적으로 업데이트가 72시간 동안 대기한 후에는 재시작이 그대로 진행될 수 있습니다.

1157* **Desktop을 종료하지 않기**: Desktop이 Windows에서 실행되거나 타사 제공업체를 사용하는 경우 긴 작업이 실행되는 동안 열어 두세요. 종료한 후에는 세션이 열릴 때 Desktop이 [실행 중인 작업을 종료](#reopen-a-session-after-you-quit-desktop)합니다. 열어 두더라도 [사용자를 기다리는](#handle-requests-that-arrive-while-you-are-away) 요청은 보호되지 않습니다.1156* **Windows에서, 또는 서드파티 제공업체로 v2.42304.0 이전 버전을 사용하는 경우 종료하지 않기**: 이 경우 종료하면 실행 중인 작업을 잃으므로, 작업 중에는 Desktop을 열어 둡니다. 그 외의 경우에는 종료하기 전에 [다시 가져올 수 있는 것](#reopen-a-session-after-you-quit-desktop)을 확인합니다.

1158* **요청 줄이기**: [작업이 사용자를 기다리는 빈도를 줄이는](#handle-requests-that-arrive-while-you-are-away) 권한 모드, 규칙 또는 훅을 선택하세요1157* **요청 줄이기**: [작업이 사용자를 기다리는 빈도를 줄이는](#handle-requests-that-arrive-while-you-are-away) 권한 모드, 규칙 또는 훅을 선택하세요

1159* **점프 호스트 확인**: 점프 호스트가 휴대폰 푸시와 같은 로그인을 요구하는 경우 프롬프트 없이 작동하는 로그인으로 전환하세요. 그렇지 않으면 Desktop이 다시 연결을 시도할 때마다 푸시를 다시 보낼 수 있습니다.1158* **점프 호스트 확인**: 점프 호스트가 휴대폰 푸시와 같은 로그인을 요구하는 경우 프롬프트 없이 작동하는 로그인으로 전환하세요. 그렇지 않으면 Desktop이 다시 연결을 시도할 때마다 푸시를 다시 보낼 수 있습니다.

1160* **원격 머신 테스트**: 짧은 작업을 시작하고, 작업이 아직 실행 중일 때 Desktop을 종료한 다음, 작업이 완료되었어야 할 시점이 충분히 지난 후 세션을 다시 엽니다. 작업이 완료되지 않았고 세션에 인증 오류가 표시되지 않으면 원격 머신에서 [작업을 종료시킬 수 있는 요인](#limits-while-desktop-is-disconnected)을 확인하세요.1159* **원격 머신 테스트**: 짧은 작업을 시작하고, 작업이 아직 실행 중일 때 Desktop을 종료한 다음, 작업이 완료되었어야 할 시점이 충분히 지난 후 세션을 다시 엽니다. 작업이 완료되지 않았고 세션에 인증 오류가 표시되지 않으면 원격 머신에서 [작업을 종료시킬 수 있는 요인](#limits-while-desktop-is-disconnected)을 확인하세요.

1206 1205 

1207Desktop 연결이 끊긴 동안 Claude가 승인을 필요로 하거나 질문을 하면 Claude는 원격 머신에서 대기합니다. 대기 자체에는 시간 제한이 없습니다. Desktop이 프로세스에 다시 합류하면 요청을 표시합니다. 대신 Desktop이 새 프로세스를 시작하면 요청을 잃게 됩니다.1206Desktop 연결이 끊긴 동안 Claude가 승인을 필요로 하거나 질문을 하면 Claude는 원격 머신에서 대기합니다. 대기 자체에는 시간 제한이 없습니다. Desktop이 프로세스에 다시 합류하면 요청을 표시합니다. 대신 Desktop이 새 프로세스를 시작하면 요청을 잃게 됩니다.

1208 1207 

1209작업이 사용자를 기다리는 동안 Desktop은 업데이트 설치 등을 위해 자동으로 재시작할 수 있습니다. Desktop이 Windows에서 실행되거나 타사 제공업체를 사용하는 경우 재시작 후 요청을 잃게 됩니다.1208돌아왔을 때 대기 중이던 요청이 사라졌다면, 한 가지 원인은 업데이트 설치 등을 위해 Desktop이 자동으로 다시 시작된 것입니다. 재시작 후에도 요청이 유지되는 것은 Desktop이 프로세스에 다시 연결할 수 있는 경우뿐이므로, 작업을 실행 상태로 두기 전에 [Desktop이 다시 연결할 수 있는 경우](#reopen-a-session-after-you-quit-desktop)를 확인합니다.

1210 1209 

1211요청을 잃은 경우 메시지를 보내 계속하세요.1210요청을 잃은 경우 메시지를 보내 계속하세요.

1212 1211 

1238 - **점프 호스트, 푸시가 계속 옴**: Windows의 Desktop처럼 아무도 응답하지 않는다는 것을 Desktop이 알 수 없는 경우, 다시 합류할 프로세스가 있는 동안에는 해당 프로세스가 여전히 실행 중인지와 관계없이 계속 시도합니다. 시도할 때마다 푸시를 다시 받을 수 있습니다. 시도를 끝내려면 Desktop을 종료하세요. 단, 이로 인해 [실행 중인 작업을 잃을 수 있습니다](#reopen-a-session-after-you-quit-desktop).1237 - **점프 호스트, 푸시가 계속 옴**: Windows의 Desktop처럼 아무도 응답하지 않는다는 것을 Desktop이 알 수 없는 경우, 다시 합류할 프로세스가 있는 동안에는 해당 프로세스가 여전히 실행 중인지와 관계없이 계속 시도합니다. 시도할 때마다 푸시를 다시 받을 수 있습니다. 시도를 끝내려면 Desktop을 종료하세요. 단, 이로 인해 [실행 중인 작업을 잃을 수 있습니다](#reopen-a-session-after-you-quit-desktop).

1239 - **긴 중단**: Desktop은 약 5분마다 한 번 시도하도록 속도를 늦춥니다. 더 빨리 다시 연결하려면 세션에서 재시도하거나 메시지를 보내세요. 메시지는 Desktop이 연결되면 전달됩니다.1238 - **긴 중단**: Desktop은 약 5분마다 한 번 시도하도록 속도를 늦춥니다. 더 빨리 다시 연결하려면 세션에서 재시도하거나 메시지를 보내세요. 메시지는 Desktop이 연결되면 전달됩니다.

1240 - **누락된 출력**: Desktop 연결이 끊긴 동안 도우미는 각 세션의 가장 최근 Claude Code 출력을 16 MiB 버퍼에 보관하고 오래된 출력은 삭제합니다. Desktop이 다시 연결된 후 세션에 `Loading recent output from <host>…`가 표시될 수 있습니다. Desktop이 모든 출력을 불러올 수 없으면 `Some output produced while you were disconnected may be missing here.` 행이 표시됩니다. 이 행은 작업이 중지되었다는 의미가 아닙니다.1239 - **누락된 출력**: Desktop 연결이 끊긴 동안 도우미는 각 세션의 가장 최근 Claude Code 출력을 16 MiB 버퍼에 보관하고 오래된 출력은 삭제합니다. Desktop이 다시 연결된 후 세션에 `Loading recent output from <host>…`가 표시될 수 있습니다. Desktop이 모든 출력을 불러올 수 없으면 `Some output produced while you were disconnected may be missing here.` 행이 표시됩니다. 이 행은 작업이 중지되었다는 의미가 아닙니다.

1241 - **사라진 프로세스**: Desktop이 다시 연결될 때 프로세스가 사라졌다면, Desktop은 대화의 저장된 기록에서 새 프로세스를 시작하고 Claude에게 작업을 계속하도록 지시할 수 있습니다. 프로세스가 계속 종료되거나 Desktop이 타사 제공업체를 사용하는 경우 Desktop은 작업을 자동으로 계속하지 않습니다. 메시지를 보내 계속하세요.1240 - **프로세스 사라짐**: 원격 머신이 다시 시작되는 경우처럼 Desktop 연결이 끊긴 동안 프로세스가 끝난 것입니다. 그러면 Desktop은 대화의 저장된 기록에서 새 프로세스를 시작하고 Claude에게 작업을 계속하도록 지시할 수 있습니다. 작업이 계속 중지된 상태이면 메시지를 보냅니다. 서드파티 제공업체를 사용하는 경우 Claude Desktop v2.42304.0 이상으로 업데이트합니다. 이전 버전은 작업을 자동으로 계속하지 않기 때문입니다.

1242</Accordion>1241</Accordion>

1243 1242 

1244<a id="reopen-a-session-after-you-quit-desktop" />1243<a id="reopen-a-session-after-you-quit-desktop" />

1247 Desktop 종료 후 세션 다시 열기1246 Desktop 종료 후 세션 다시 열기

1248</h5>1247</h5>

1249 1248 

1250Desktop을 종료한 후에도 작업은 완료되거나, 사용자의 입력이 필요하거나, [제한](#limits-while-desktop-is-disconnected) 중 하나에 도달할 때까지 원격 머신에서 계속 실행됩니다.1249Desktop을 종료한 후에도 작업은 원격 머신에서 계속 실행되지만, Desktop이 해당 프로세스에 다시 연결할 수 없으면 세션이 다시 열릴 때 중지됩니다. Desktop이 닫혀 있는 동안 작업은 완료되거나, 사용자의 응답이 필요하거나, [제한](#limits-while-desktop-is-disconnected) 중 하나에 도달할 때까지 실행됩니다.

1251 1250 

1252* **macOS 또는 Linux의 Desktop, Claude 계정 사용**: Desktop을 시작하고 세션을 엽니다. Desktop이 프로세스에 다시 합류할 수 있으면 실행 중인 작업을 되찾을 수 있습니다. 예를 들어 일부 Desktop 업데이트 후나 조직이 관리형 설정을 변경한 후에는 항상 다시 합류할 수 있는 것은 아닙니다.1251* **Windows의 Desktop**: Desktop은 종료 후 다시 연결하지 않으므로 실행 중인 작업을 다시 가져올 수 없습니다. Desktop이 시작될 때 세션이 열릴 수 있으므로, 작업이 완료되었을 것으로 예상될 때만 Desktop을 다시 시작합니다.

1253* **macOS 또는 Linux에서 Desktop이 다시 합류할 수 없는 경우**: Desktop은 프로세스를 종료하고 대화의 저장된 기록에서 새 프로세스를 시작합니다. 실행 중인 작업은 중지되고, 대기 중이던 승인이나 질문도 잃게 됩니다. 업데이트 후에는 Desktop이 Claude에게 계속하도록 지시할 수 있습니다. 작업이 계속 중지된 상태라면 메시지를 보내세요.1252* **서드파티 제공업체, 이전 버전에서 시작한 작업**: v2.42304.0 이전 Desktop 버전에서 작업을 시작한 경우 macOS나 Linux에서도 작업을 다시 가져올 수 없습니다. 작업이 완료되었을 것으로 예상될 때만 Desktop을 다시 시작합니다.

1254* **Windows의 Desktop, 또는 모든 플랫폼에서 타사 제공업체 사용**: 작업이 완료되었을 것으로 예상될 때만 Desktop을 다시 시작하세요. Desktop은 종료 후 절대 다시 합류하지 않으므로 실행 중인 작업을 되찾을 수 없습니다. 세션이 열릴 때 프로세스를 종료하며, 이는 Desktop이 시작될 때 발생할 수 있습니다. 메시지를 보내 계속하세요.1253* **그 외 작업, macOS 또는 Linux의 Desktop**: Desktop을 시작하고 세션을 열면, Desktop이 다시 연결되는 경우 작업이 계속됩니다. 일부 Desktop 업데이트 후처럼 항상 다시 연결할 수 있는 것은 아니므로 [긴 작업 전에 업데이트](#prepare-a-long-task)합니다.

1254 

1255Desktop이 다시 연결할 수 없으면 대기 중이던 승인이나 질문도 잃습니다. 작업이 자동으로 계속되지 않으면 메시지를 보내세요. 그러면 Claude가 대화의 저장된 기록에서 이어서 진행합니다.

1255 1256 

1256타사 배포의 경우 [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions)를 참조하세요.1257타사 배포의 경우 [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions)를 참조하세요.

1257 1258 

186 | - | - | - |186 | - | - | - |

187 | **실행** | 셸 명령, HTTP 요청, MCP 도구 호출, LLM 프롬프트 또는 subagent | Claude가 읽고 따르는 지침 |187 | **실행** | 셸 명령, HTTP 요청, MCP 도구 호출, LLM 프롬프트 또는 subagent | Claude가 읽고 따르는 지침 |

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

189 | **결정론** | 항상 이벤트에서 실행됩니다. 트리거가 보장됩니다 | Claude가 지침을 해석합니다. 결과는 다를 수 있습니다 |189 | **결정론** | Claude의 판단 없이 해당 이벤트에서 실행됩니다 | Claude가 지침을 해석합니다. 결과는 다를 수 있습니다 |

190 | **컨텍스트 비용** | Hook이 출력을 반환하지 않으면 0 | 설명은 매 세션마다 로드됩니다. 전체 콘텐츠는 사용할 때 로드됩니다 |190 | **컨텍스트 비용** | Hook이 출력을 반환하지 않으면 0 | 설명은 매 세션마다 로드됩니다. 전체 콘텐츠는 사용할 때 로드됩니다 |

191 | **최적 용도** | 편집 후 린팅, 안전하지 않은 명령 차단, 로깅, 알림 | 추론이 필요한 워크플로우, 참고 자료, 다단계 작업 |191 | **최적 용도** | 편집 후 린팅, 안전하지 않은 명령 차단, 로깅, 알림 | 추론이 필요한 워크플로우, 참고 자료, 다단계 작업 |

192 192 

1832 1832 

1833[PreToolUse 결정 제어](#pretooluse-decision-control)를 사용해 도구 호출을 허용, 거부, 확인 요청 또는 지연할 수 있습니다.1833[PreToolUse 결정 제어](#pretooluse-decision-control)를 사용해 도구 호출을 허용, 거부, 확인 요청 또는 지연할 수 있습니다.

1834 1834 

1835`PreToolUse`의 [Agent SDK 콜백 훅](/docs/ko/agent-sdk/hooks)이 타임아웃을 초과하면 도구 호출이 차단되고, Claude는 타임아웃을 명시한 오류 결과를 받습니다. 다른 훅이 반환한 명시적 거부는 여전히 우선합니다.1835`PreToolUse`의 [Agent SDK 콜백 훅](/docs/ko/agent-sdk/hooks)이 타임아웃을 초과하면 도구 호출을 차단하며, Claude는 타임아웃을 명시한 오류 결과를 받습니다.

1836 1836 

1837<h4 id="pretooluse-input">1837<h4 id="pretooluse-input">

1838 PreToolUse 입력1838 PreToolUse 입력

213설치가 실패하면 Claude Code가 보고하는 메시지와 일치하는지 확인합니다:213설치가 실패하면 Claude Code가 보고하는 메시지와 일치하는지 확인합니다:

214 214 

215* `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 후 설치를 다시 시도합니다.215* `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 후 설치를 다시 시도합니다.

216* 플러그인이 [마켓플레이스에서 찾을 수 없음](/docs/ko/plugins/install#install-a-plugin): 플러그인 이름을 확인합니다.216* `Plugin "<name>" not found in marketplace "claude-plugins-official"`: 로컬에 있는 마켓플레이스 카탈로그 사본이 오래되었을 수 있습니다. `/plugin marketplace update claude-plugins-official`로 카탈로그를 새로 고친 후 설치를 다시 시도합니다. 재시도 시에도 같은 메시지가 출력되면 [Plugin not found in marketplace](/docs/ko/plugins/troubleshooting#plugin-not-found-in-marketplace)를 참조하세요.

217 217 

218본인만 설치하는 대신 저장소의 모든 사람을 위해 플러그인을 활성화하려면, [`enabledPlugins` 프로젝트 설정](/docs/ko/settings-reference#plugin-settings)에 추가합니다.218본인만 설치하는 대신 저장소의 모든 사람을 위해 플러그인을 활성화하려면, [`enabledPlugins` 프로젝트 설정](/docs/ko/settings-reference#plugin-settings)에 추가합니다.

219 219 

50 설치가 실패하면 Claude Code가 보고하는 메시지와 일치하는지 확인하세요:50 설치가 실패하면 Claude Code가 보고하는 메시지와 일치하는지 확인하세요:

51 51 

52 * `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 다음 설치를 다시 시도하세요.52 * `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 다음 설치를 다시 시도하세요.

53 * 플러그인이 [마켓플레이스에서 찾을 수 없음](/docs/ko/plugins/install#install-a-plugin): 플러그인 이름을 확인하세요.53 * `Plugin "<name>" not found in marketplace "claude-plugins-official"`: 로컬에 있는 마켓플레이스 카탈로그 사본이 오래되었을 수 있습니다. `/plugin marketplace update claude-plugins-official`로 카탈로그를 새로 고친 다음 설치를 다시 시도하세요. 재시도 후에도 같은 메시지가 출력되면 [Plugin not found in marketplace](/docs/ko/plugins/troubleshooting#plugin-not-found-in-marketplace)를 참조하세요.

54 54 

55 설치 요약에서 `Run /reload-plugins to apply.`를 보고하면 Claude Code가 해당 리로드를 실행합니다. 리로드에서 다음 메시지가 대화를 다시 읽을 것이라고 경고하면 `/reload-plugins --force`를 실행하세요.55 설치 요약에서 `Run /reload-plugins to apply.`를 보고하면 Claude Code가 해당 리로드를 실행합니다. 리로드에서 다음 메시지가 대화를 다시 읽을 것이라고 경고하면 `/reload-plugins --force`를 실행하세요.

56 </Step>56 </Step>

772**속성**:772**속성**:

773 773 

774* 모든 [표준 속성](#standard-attributes)774* 모든 [표준 속성](#standard-attributes)

775* `type`: (`"input"`, `"output"`, `"cacheRead"`, `"cacheCreation"`). `"input"` 유형은 프롬프트 캐시에서 읽거나 캐시에 쓴 토큰을 제외하며, 이러한 토큰은 `"cacheRead"` 및 `"cacheCreation"`으로 집계됩니다775* `type`: (`"input"`, `"output"`, `"cacheRead"`, `"cacheCreation"`). `"input"` 유형은 프롬프트 캐시에서 읽거나 프롬프트 캐시에 쓴 토큰을 제외하며, 해당 토큰은 `"cacheRead"` 및 `"cacheCreation"`으로 집계됩니다. `"cacheCreation"` 유형은 5분 및 1시간 [캐시 수명](/docs/ko/prompt-caching#cache-lifetime)의 캐시 쓰기를 합산하여 집계합니다.

776* `model`: 모델 식별자 (예: "claude-sonnet-5")776* `model`: 모델 식별자 (예: "claude-sonnet-5")

777* `query_source`: 요청을 발급한 하위 시스템의 범주. `"main"`, `"subagent"`, 또는 `"auxiliary"` 중 하나777* `query_source`: 요청을 발급한 하위 시스템의 범주. `"main"`, `"subagent"`, 또는 `"auxiliary"` 중 하나

778* `speed`: 요청이 빠른 모드를 사용했을 때 `"fast"`. 그 외의 경우 없음778* `speed`: 요청이 빠른 모드를 사용했을 때 `"fast"`. 그 외의 경우 없음

749이러한 검사는 여전히 적용됩니다:749이러한 검사는 여전히 적용됩니다:

750 750 

751* `Bash(git push *)`와 같은 콘텐츠 범위 ask 규칙은 여전히 프롬프트를 강제합니다751* `Bash(git push *)`와 같은 콘텐츠 범위 ask 규칙은 여전히 프롬프트를 강제합니다

752* 명시적 deny 규칙은 여전히 적용됩니다

753* [중요 경로](/docs/ko/permission-modes#critical-paths)를 대상으로 하는 `rm` 또는 `rmdir` 명령은 여전히 일반 권한 흐름을 거칩니다

754* [자동 허용 모드](/docs/ko/sandboxing#auto-allow-mode)에서 설명하는 것처럼 다른 샌드박스된 명령도 일반 권한 흐름을 거칠 수 있습니다752* [자동 허용 모드](/docs/ko/sandboxing#auto-allow-mode)에서 설명하는 것처럼 다른 샌드박스된 명령도 일반 권한 흐름을 거칠 수 있습니다

755 753 

756제외된 명령과 같이 샌드박스에서 실행되지 않는 명령은 bare `Bash` ask 규칙을 일반적으로 따릅니다. 이 동작을 변경하려면 [샌드박스 모드](/docs/ko/sandboxing#sandbox-modes)를 참조하십시오.754제외된 명령과 같이 샌드박스에서 실행되지 않는 명령은 bare `Bash` ask 규칙을 일반적으로 따릅니다. 이 동작을 변경하려면 [샌드박스 모드](/docs/ko/sandboxing#sandbox-modes)를 참조하십시오.

78 78 

79mod는 기존 제어를 대체하지 않습니다.79mod는 기존 제어를 대체하지 않습니다.

80 80 

81* **설정 훅은 계속 작동합니다.** 설정 파일과 플러그인의 `hooks/hooks.json`에 있는 command, HTTP, prompt, agent 훅은 mod와 함께 이전과 같이 실행됩니다. 이들 중 deprecated된 것은 없습니다.81* **설정 훅은 계속 작동합니다.** 설정 파일과 플러그인의 `hooks/hooks.json`에 있는 command, HTTP, prompt, agent 훅은 mod와 함께 이전과 같이 실행됩니다.

82* **가드가 로드된 환경에서는 deny 규칙이 우선합니다.** [`allowModsToOverrideDenyRules`](#set-options-on-the-built-in-guard)를 설정하지 않는 한, 사용자의 mod는 `deny` 규칙이 거부하는 호출을 승인할 수 없습니다.82* **가드가 로드된 환경에서는 deny 규칙이 우선합니다.** [`allowModsToOverrideDenyRules`](#set-options-on-the-built-in-guard)를 설정하지 않는 한, 사용자의 mod는 `deny` 규칙이 거부하는 호출을 승인할 수 없습니다.

83* **관리형 훅이 먼저 실행됩니다.** 관리형 설정의 `PreToolUse` 훅은 어떤 mod보다도 먼저 도구 호출을 확인하며, 그 차단은 최종적입니다. 이후 mod가 호출을 다시 작성하면 관리형 훅이 다시 작성된 호출에 대해 다시 실행되므로 차단은 여전히 적용됩니다. 다른 설정 파일과 플러그인의 `PreToolUse` 훅은 마지막 mod 이후에 실행되므로, 도구를 실행하는 대신 자체 결과를 반환하는 mod는 해당 훅이 실행되지 않도록 합니다. [mod 실행 순서](/docs/ko/plugins/mods/events#the-order-mods-run-in)를 참조하십시오.83* **관리형 훅이 먼저 실행됩니다.** 관리형 설정의 `PreToolUse` 훅은 어떤 mod보다도 먼저 도구 호출을 확인하며, 그 차단은 최종적입니다. 이후 mod가 호출을 다시 작성하면 관리형 훅이 다시 작성된 호출에 대해 다시 실행되므로 차단은 여전히 적용됩니다. 다른 설정 파일과 플러그인의 `PreToolUse` 훅은 마지막 mod 이후에 실행되므로, 도구를 실행하는 대신 자체 결과를 반환하는 mod는 해당 훅이 실행되지 않도록 합니다. [mod 실행 순서](/docs/ko/plugins/mods/events#the-order-mods-run-in)를 참조하십시오.

84* **네트워크 정책은 `$.http.fetch`에 적용됩니다.**84* **네트워크 정책은 `$.http.fetch`에 적용됩니다.**

114 `Text`114 `Text`

115</h3>115</h3>

116 116 

117`Text`는 지정한 스타일로 문자열을 그립니다. 다음 예시는 스타일마다 한 줄씩 표시합니다.117`Text`는 지정한 스타일로 문자열을 그립니다. 다음 예시는 일반 텍스트와 여덟 가지 스타일을 한 줄에 하나씩 표시합니다.

118 118 

119```javascript theme={null}119```javascript theme={null}

120Box({120Box({

455 455 

456| 요소 | 그리는 내용 | 사용 위치 |456| 요소 | 그리는 내용 | 사용 위치 |

457| :- | :- | :- |457| :- | :- | :- |

458| `Box` | flex 컨테이너입니다. `flexDirection`, `columnGap`, `padding`, [`borderStyle`](/docs/ko/plugins/mods/reference#box-border-styles), `width` 같은 레이아웃 prop을 받습니다. | 모든 곳 |458| `Box` | flex 컨테이너입니다. `flexDirection`, [`borderStyle`](/docs/ko/plugins/mods/reference#box-border-styles), `width` 같은 레이아웃 prop을 받습니다. `columnGap`, `padding` 같은 간격 prop은 숫자 또는 `'xs'`부터 `'xl'`까지의 [단계 이름](/docs/ko/plugins/mods/reference#box-spacing-steps)을 받습니다. | 모든 곳 |

459| `Text` | 스타일이 적용된 텍스트입니다. `color`, `bold`, `dimColor`, `italic`, `wrap`을 받습니다. `color`는 테마 키 또는 `'red'` 같은 색상입니다. `wrap`은 `'wrap'`, `'truncate'`, `'truncate-start'`, `'truncate-middle'`, `'truncate-end'` 중 하나입니다. | 모든 곳 |459| `Text` | 스타일이 적용된 텍스트입니다. `color`, `bold`, `dimColor`, `italic`, `wrap`과 [`weight`](/docs/ko/plugins/mods/reference#text-typography) 같은 기타 prop을 받습니다. `color`는 테마 키 또는 `'red'` 같은 색상입니다. `wrap`은 `'wrap'`, `'truncate'`, `'truncate-start'`, `'truncate-middle'`, `'truncate-end'` 중 하나입니다. | 모든 곳 |

460| `Button` | `onPress`를 호출하는 컨트롤 | 모든 곳 |460| `Button` | `onPress`를 호출하는 컨트롤 | 모든 곳 |

461| `Link`, `Code`, `Markdown` | `href`와 선택적 `label`을 갖는 링크, 코드 블록, 그리고 Claude의 응답과 같은 방식으로 서식이 지정된 텍스트입니다. `Markdown`은 내용을 `children`이 아닌 `text` prop으로 받으며, `onLinkPress`를 전달할 때는 `key`가 필요합니다. | 모든 곳 |461| `Link`, `Code`, `Markdown` | `href`와 선택적 `label`을 갖는 링크, 코드 블록, 그리고 Claude의 응답과 같은 방식으로 서식이 지정된 텍스트입니다. `Markdown`은 내용을 `children`이 아닌 `text` prop으로 받으며, `onLinkPress`를 전달할 때는 `key`가 필요합니다. | 모든 곳 |

462| `Input`, `Select` | 텍스트 필드와 드롭다운 | 터미널, Desktop, VS Code |462| `Input`, `Select` | 텍스트 필드와 드롭다운 | 터미널, Desktop, VS Code |

293 293 

294| 요소 | 주요 prop | 터미널 | 데스크톱 | VS Code |294| 요소 | 주요 prop | 터미널 | 데스크톱 | VS Code |

295| :- | :- | :-: | :-: | :-: |295| :- | :- | :-: | :-: | :-: |

296| [`Box`](/docs/ko/plugins/mods/interface#build-a-tree-from-elements) | `key`, flex 레이아웃, `gap`, `padding`, `margin`, `width`, `height`, [`borderStyle`](#box-border-styles), `backgroundColor`, `position`, `hover` | ✓ | ✓ | ✓ |296| [`Box`](/docs/ko/plugins/mods/interface#build-a-tree-from-elements) | `key`, flex 레이아웃, [`gap`, `padding`, `margin`](#box-spacing-steps), `width`, `height`, [`borderStyle`](#box-border-styles), `backgroundColor`, `position`, `hover` | ✓ | ✓ | ✓ |

297| [`Text`](/docs/ko/plugins/mods/interface#build-a-tree-from-elements) | `color`, `backgroundColor`, `bold`, `italic`, `underline`, `dimColor`, `inverse`, `wrap` | ✓ | ✓ | ✓ |297| [`Text`](/docs/ko/plugins/mods/interface#build-a-tree-from-elements) | `color`, `backgroundColor`, [`bold`](#text-bold), `italic`, `underline`, `dimColor`, `inverse`, `wrap`, [`size`, `weight`, `mono`, `tabular`](#text-typography) | ✓ | ✓ | ✓ |

298| [`Button`](/docs/ko/plugins/mods/interface#respond-to-presses-and-typing) | `key`, `label`, `onPress`, `hotkey`, `plain`, `dimColor`, `autoFocus`, `action` | ✓ | ✓ | ✓ |298| [`Button`](/docs/ko/plugins/mods/interface#respond-to-presses-and-typing) | `key`, `label`, `onPress`, `hotkey`, `plain`, `dimColor`, `autoFocus`, `action` | ✓ | ✓ | ✓ |

299| [`Link`](/docs/ko/plugins/mods/interface#link-in-the-desktop-app) | `href`, `label`. [제한 사항](#limits)을 참조하십시오. | ✓ | ✓ | ✓ |299| [`Link`](/docs/ko/plugins/mods/interface#link-in-the-desktop-app) | `href`, `label`. [제한 사항](#limits)을 참조하십시오. | ✓ | ✓ | ✓ |

300| [`Code`](/docs/ko/plugins/mods/gallery#show-code-and-changes) | `source`, `language`, `path`, `startLine`, `format`, `wrap` | ✓ | ✓ | ✓ |300| [`Code`](/docs/ko/plugins/mods/gallery#show-code-and-changes) | `source`, `language`, `path`, `startLine`, `format`, `wrap` | ✓ | ✓ | ✓ |

311VS Code 확장은 일부 요소 prop을 무시하고, 해당 prop을 생략한 것처럼 요소를 그립니다.311VS Code 확장은 일부 요소 prop을 무시하고, 해당 prop을 생략한 것처럼 요소를 그립니다.

312 312 

313* **`Box`**: `position` 및 `hover`313* **`Box`**: `position` 및 `hover`

314* **`Text`**: `size`, `mono`, `tabular`

314* **`Button`**: `hotkey`, `plain`, `autoFocus`, `action`. 따라서 VS Code에서는 버튼을 클릭하거나, 버튼에 포커스가 있을 때 Enter를 눌러 버튼을 누릅니다315* **`Button`**: `hotkey`, `plain`, `autoFocus`, `action`. 따라서 VS Code에서는 버튼을 클릭하거나, 버튼에 포커스가 있을 때 Enter를 눌러 버튼을 누릅니다

315* **`Code`**: `language`, `path`, `startLine`, `format`, `wrap`. 따라서 코드는 색상이나 줄 번호 없이 그려지며, `format: 'diff'` 블록은 diff의 원시 텍스트를 표시합니다316* **`Code`**: `language`, `path`, `startLine`, `format`, `wrap`. 따라서 코드는 색상이나 줄 번호 없이 그려지며, `format: 'diff'` 블록은 diff의 원시 텍스트를 표시합니다

316* **`Input` 및 `Select`**: `autoFocus`317* **`Input` 및 `Select`**: `autoFocus`

336 337 

337`borderStyle`에 `'rounded'`처럼 그 밖의 이름을 지정한 `Box`는 테두리 없이 그려집니다.338`borderStyle`에 `'rounded'`처럼 그 밖의 이름을 지정한 `Box`는 테두리 없이 그려집니다.

338 339 

340<h3 id="box-spacing-steps">

341 `Box` 간격 단계

342</h3>

343 

344`Box` 간격 prop은 `gap`, `columnGap`, `rowGap`, `padding`, `margin`, 그리고 `paddingX`, `marginTop`처럼 `padding`과 `margin`의 한쪽 면 및 한 축 형태입니다. 각 prop은 `gap: 1`처럼 터미널 셀 수를 받거나, `gap: 'md'`처럼 단계 이름을 받습니다. 터미널과 VS Code 확장에서 각 단계는 다음 셀 수에 해당합니다.

345 

346| 단계 | 가로 셀 수 | 세로 셀 수 |

347| :- | :- | :- |

348| `'xs'` | 1 | 0 |

349| `'sm'` | 1 | 0 |

350| `'md'` | 2 | 1 |

351| `'lg'` | 3 | 1 |

352| `'xl'` | 4 | 2 |

353 

354`gap`, `padding` 또는 `margin`을 단계로 설정하면 해당 단계가 가로와 세로에 동시에 적용됩니다. 예를 들어 터미널과 VS Code 확장에서 `padding: 'md'`는 양옆 각각 두 셀, 위아래 각각 한 행입니다.

355 

356단계 이름을 사용하려면 Claude Code v2.1.299 이상이 필요합니다. 이전 릴리스에서는 단계 이름을 사용하는 트리 대신 Claude Code가 [사이트의 자체 버전을 그립니다](/docs/ko/plugins/mods/interface#build-a-tree-from-elements).

357 

358<h3 id="text-typography">

359 `Text` 타이포그래피 prop

360</h3>

361 

362`Text`에 `size`, `weight`, `mono` 또는 `tabular`를 설정하면 트리를 그리는 앱에 텍스트 크기, 굵기, 고정폭 서체 또는 너비가 동일한 숫자를 요청할 수 있습니다. prop에 의존하기 전에 터미널과 VS Code 확장이 해당 prop을 어떻게 처리하는지 확인하십시오. 앱이 설정한 prop을 무시하더라도 트리는 여전히 그려지며, 텍스트는 해당 prop을 생략한 것처럼 표시됩니다.

363 

364| Prop | 값 | 터미널에서 | VS Code 확장에서 |

365| :- | :- | :- | :- |

366| `size` | `'caption'`, `'footnote'`, `'body'`, `'heading'` 또는 `'title'` | 무시됨: 터미널에는 텍스트 크기가 하나뿐입니다 | 무시됨 |

367| `weight` | `'regular'`, `'medium'`, `'semibold'` 또는 `'bold'` | `semibold`와 `bold`는 굵은 텍스트로 그려집니다 | `semibold`와 `bold`는 굵은 텍스트로 그려집니다 |

368| `mono` | 앱의 고정폭 서체를 요청하려면 `true` | 무시됨: 터미널은 항상 고정폭입니다 | 무시되므로 텍스트는 확장 자체의 서체를 유지합니다 |

369| `tabular` | 제자리에서 업데이트되는 숫자나 숫자 열이 정렬된 상태를 유지하도록 너비가 동일한 숫자를 요청하려면 `true` | 무시됨: 터미널의 숫자는 이미 한 셀 너비입니다 | 무시됨 |

370 

371이 네 가지 prop을 사용하려면 Claude Code v2.1.299 이상이 필요합니다. 이전 릴리스에서는 `size`, `weight`, `mono` 또는 `tabular`를 설정한 트리 대신 Claude Code가 [사이트의 자체 버전을 그립니다](/docs/ko/plugins/mods/interface#build-a-tree-from-elements).

372 

373<h4 id="text-bold">

374 `bold`를 `weight`로 대체하기

375</h4>

376 

377`Text`의 `bold`는 `weight`로 대체되어 deprecated되었지만 여전히 작동합니다. `weight`가 없는 `Text`에서 이를 대체하려면 `bold: true`를 `weight: 'semibold'`로 변경하십시오. Claude Code v2.1.299 이상에서 동일한 결과를 얻을 수 있습니다.

378 

379v2.1.299 이전 릴리스에서는 `weight`를 설정한 트리가 그려지지 않으며, 대신 Claude Code가 [사이트의 자체 버전을 그립니다](/docs/ko/plugins/mods/interface#build-a-tree-from-elements). `Text`에 `bold`와 `weight`를 모두 설정하면 `bold`는 효과가 없습니다.

380 

339<h2 id="limits">381<h2 id="limits">

340 제한382 제한

341</h2>383</h2>

235 235 

236mod는 로드되었지만 해당 pane, band, toast 또는 컨트롤이 예상대로 동작하지 않습니다.236mod는 로드되었지만 해당 pane, band, toast 또는 컨트롤이 예상대로 동작하지 않습니다.

237 237 

238<h3 id="another-mods-band-shows-and-yours-doesnt">

239 다른 mod의 band는 표시되지만 사용자의 mod band는 표시되지 않음

240</h3>

241 

242프롬프트 위에는 band가 하나만 있으며 모든 mod가 이를 공유합니다. [사용자의 mod보다 먼저](/docs/ko/plugins/mods/events#the-order-mods-run-in) 실행되는 mod가 `next(e)`의 결과를 포함하지 않은 트리를 반환하면 사용자의 band를 대체합니다. 두 band를 모두 표시하려면 해당 mod의 훅을 변경하거나 작성자에게 변경을 요청합니다.

243 

244* **뒤에 오는 band 유지**: [그릴 위치 선택](/docs/ko/plugins/mods/interface#pick-where-to-draw)의 Band above the prompt 탭처럼, `await next(e)`의 결과를 트리 안 `Box`의 자식 중 하나로 넣습니다

245* **트리를 유효하게 유지**: 해당 `Box` 또는 이를 감싸는 어떤 `Box`에도 `width`, `height`, `minWidth`, `minHeight`, `position`, `top`, `left`, `right`, `bottom`, `display`, `overflow` prop을 지정하지 않습니다

246 

247해당 mod를 찾으려면 [디버그 로그를 작성](#read-the-debug-log)하고 로그에서 `answered ui.render without next()`를 검색합니다. `other-mod (user) answered ui.render without next()` 같은 줄은 `next(e)`를 호출하지 않고 트리를 반환한 mod를 나타냅니다. 이 줄은 [렌더링 지점](/docs/ko/plugins/mods/reference#render-sites)을 명시하지 않으므로 pane 전용 mod도 나타날 수 있습니다. `next(e)`를 호출한 뒤 그 결과를 버리는 mod에 대해서는 줄이 기록되지 않으므로, 사용자의 mod보다 앞선 훅도 확인합니다.

248 

249변경 후에는 mod 중 하나라도 유효성 검사를 통과하지 못하는 트리를 반환하면 band에 아무것도 표시되지 않습니다. 이유를 확인하려면 `--plugin-dir` 세션의 트랜스크립트에서 `ui.render (AbovePrompt) refused:` 줄을 찾거나 디버그 로그에서 `does not validate`를 검색합니다. band에 여러 mod가 있으면 어느 줄에도 mod 이름이 표시되지 않으므로 각 mod의 트리를 확인합니다.

250 

238<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">251<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">

239 pane 또는 band가 비어 있거나 Claude Code의 일반 콘텐츠를 표시함252 pane 또는 band가 비어 있거나 Claude Code의 일반 콘텐츠를 표시함

240</h3>253</h3>

199 199 

200auto-allow 모드에서도 다음은 계속 적용됩니다.200auto-allow 모드에서도 다음은 계속 적용됩니다.

201 201 

202* 명시적 [거부 규칙](/docs/ko/permissions)은 항상 준수됩니다202* [`Bash` 거부 규칙이 일치하는 형식](/docs/ko/permissions#bash-rule-limits)의 명령은 여전히 차단됩니다

203* [중요 경로](/docs/ko/permission-modes#critical-paths)를 대상으로 하는 `rm` 또는 `rmdir` 명령은 여전히 일반 권한 흐름을 거칩니다203* [중요 경로](/docs/ko/permission-modes#which-paths-are-critical)를 대상으로 하는 것으로 인식된 `rm` 또는 `rmdir` 명령은 여전히 일반 권한 흐름을 거칩니다

204* `Bash(git push *)` 같은 내용 범위 [ask 규칙](/docs/ko/permissions)은 샌드박스 처리된 명령에도 여전히 확인을 요청합니다204* `Bash(git push *)` 같은 내용 범위 [ask 규칙](/docs/ko/permissions)은 샌드박스 처리된 명령에도 여전히 확인을 요청합니다

205* 단순 `Bash` ask 규칙 또는 이와 동일한 `Bash(*)` 형식은 샌드박스에서 실행되는 명령에는 건너뛰지만, 샌드박스 밖에서 실행되는 명령에는 여전히 적용됩니다. [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에서는 이 규칙을 건너뛰지 않으며, 읽기 전용 명령을 포함해 샌드박스 처리된 명령에도 확인을 요청합니다205* 단순 `Bash` ask 규칙 또는 이와 동일한 `Bash(*)` 형식은 샌드박스에서 실행되는 명령에는 건너뛰지만, 샌드박스 밖에서 실행되는 명령에는 여전히 적용됩니다. [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에서는 이 규칙을 건너뛰지 않으며, 읽기 전용 명령을 포함해 샌드박스 처리된 명령에도 확인을 요청합니다

206* [Monitor 도구](/docs/ko/tools-reference#monitor-tool) 명령은 샌드박스에서 실행되기는 하지만 자동으로 승인되지 않습니다. 확인 요청을 건너뛰려면 `Bash(npm run *)`처럼 명령과 일치하는 [allow 규칙](/docs/ko/permissions#bash)을 추가합니다206* [Monitor 도구](/docs/ko/tools-reference#monitor-tool) 명령은 샌드박스에서 실행되기는 하지만 자동으로 승인되지 않습니다. 확인 요청을 건너뛰려면 `Bash(npm run *)`처럼 명령과 일치하는 [allow 규칙](/docs/ko/permissions#bash)을 추가합니다

112 IDE 보안112 IDE 보안

113</h2>113</h2>

114 114 

115IDE에서 Claude Code를 실행하는 방법에 대한 자세한 내용은 [VS Code 보안 및 개인정보 보호](/docs/ko/vs-code#security-and-privacy)를 참조하십시오.115IDE에서 Claude Code를 실행하는 방법에 대한 자세한 내용은 [기본 제공 IDE MCP 서버](/docs/ko/vs-code#the-built-in-ide-mcp-server)를 참조하십시오.

116 116 

117<h2 id="cloud-execution-security">117<h2 id="cloud-execution-security">

118 클라우드 실행 보안118 클라우드 실행 보안

42설치가 실패하면 Claude Code가 보고하는 메시지와 일치시킵니다:42설치가 실패하면 Claude Code가 보고하는 메시지와 일치시킵니다:

43 43 

44* `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 후 설치를 다시 시도합니다.44* `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 후 설치를 다시 시도합니다.

45* 플러그인이 [마켓플레이스에서 찾을 수 없음](/docs/ko/plugins/install#install-a-plugin): 플러그인 이름을 확인합니다.45* `Plugin "<name>" not found in marketplace "claude-plugins-official"`: 로컬에 있는 마켓플레이스 카탈로그 사본이 오래되었을 수 있습니다. `/plugin marketplace update claude-plugins-official`로 새로 고친 후 설치를 재시도합니다. 재시도 시 동일한 메시지가 출력되면 [마켓플레이스에서 플러그인을 찾을 수 없음](/docs/ko/plugins/troubleshooting#plugin-not-found-in-marketplace)을 참조하세요.

46 46 

47설치 요약을 확인합니다. `Run /reload-plugins to apply.`를 보고하면 [재시작 없이 플러그인 변경 사항 적용](/docs/ko/plugins/cli-reference#reload-plugins)을 참조하여 현재 세션에서 플러그인을 활성화합니다.47설치 요약을 확인합니다. `Run /reload-plugins to apply.`를 보고하면 [재시작 없이 플러그인 변경 사항 적용](/docs/ko/plugins/cli-reference#reload-plugins)을 참조하여 현재 세션에서 플러그인을 활성화합니다.

48 48 

718 718 

719인수와 함께 스킬을 호출했지만 스킬의 콘텐츠에서 인수를 받는 플레이스홀더가 없으면 Claude Code는 `ARGUMENTS: <your input>`을 스킬 콘텐츠 끝에 추가하므로 Claude는 여전히 입력한 내용을 봅니다. 플레이스홀더는 `$ARGUMENTS`, `$1`과 같은 인덱싱된 형식 또는 명명된 인수입니다. 위치에 인수가 없는 인덱싱된 플레이스홀더는 리터럴 텍스트로 유지되며 인수를 받은 것으로 계산되지 않습니다. 명명된 플레이스홀더는 위치에 인수가 없어도 계산됩니다. 빈 문자열로 확장되기 때문입니다.719인수와 함께 스킬을 호출했지만 스킬의 콘텐츠에서 인수를 받는 플레이스홀더가 없으면 Claude Code는 `ARGUMENTS: <your input>`을 스킬 콘텐츠 끝에 추가하므로 Claude는 여전히 입력한 내용을 봅니다. 플레이스홀더는 `$ARGUMENTS`, `$1`과 같은 인덱싱된 형식 또는 명명된 인수입니다. 위치에 인수가 없는 인덱싱된 플레이스홀더는 리터럴 텍스트로 유지되며 인수를 받은 것으로 계산되지 않습니다. 명명된 플레이스홀더는 위치에 인수가 없어도 계산됩니다. 빈 문자열로 확장되기 때문입니다.

720 720 

721한 메시지의 시작 부분에 여러 스킬을 스택할 수도 있습니다. `/write-tests /fix-issue 123`을 입력하면 두 스킬이 모두 로드되고 후행 텍스트 `123`이 각각에 `$ARGUMENTS`로 전달됩니다.

722 

723Claude Code는 첫 번째 스킬과 그 뒤에 스택된 최대 5개를 확장합니다. 확장은 인라인 사용자 호출 가능 스킬이 아닌 첫 번째 토큰에서 중지되므로 [포크된 서브에이전트](#run-skills-in-a-subagent)로 실행되는 스킬(예: [`/code-review`](/docs/ko/code-review-local)) 또는 인수 자체가 슬래시 명령으로 시작할 수 있는 스킬(예: `/loop`)도 거기서 끝납니다. 해당 토큰 및 그 뒤의 모든 것이 확장된 모든 스킬의 인수 텍스트가 됩니다. v2.1.218부터 `/code-review`는 포크된 서브에이전트로 실행됩니다. 이전 버전에서는 인라인으로 실행되고 스택되었습니다.

724 

725위치별로 개별 인수에 액세스하려면 `$ARGUMENTS[N]` 또는 더 짧은 `$N`을 사용합니다.721위치별로 개별 인수에 액세스하려면 `$ARGUMENTS[N]` 또는 더 짧은 `$N`을 사용합니다.

726 722 

727```yaml theme={null}723```yaml theme={null}

746Preserve all existing behavior and tests.742Preserve all existing behavior and tests.

747```743```

748 744 

745<h4 id="stack-several-skills-in-one-message">

746 한 메시지에 여러 스킬 스택

747</h4>

748 

749터미널의 Claude Code 프롬프트에 입력할 때는 한 메시지의 시작 부분에 여러 스킬을 스택할 수 있습니다. Agent SDK 또는 `claude -p`를 통해서는 Claude Code가 첫 번째 스킬만 로드하고 줄의 나머지 부분을 해당 스킬의 인수로 사용합니다. 터미널 프롬프트에서 `/write-tests /fix-issue 123`을 입력하면 두 스킬이 모두 로드되고 후행 텍스트 `123`이 각각에 `$ARGUMENTS`로 전달됩니다.

750 

751Claude Code는 첫 번째 스킬과 그 뒤에 스택된 최대 5개를 확장합니다. 확장은 인라인 사용자 호출 가능 스킬이 아닌 첫 번째 토큰에서 중지됩니다. [`/code-review`](/docs/ko/code-review-local)처럼 [포크된 서브에이전트](#run-skills-in-a-subagent)로 실행되는 스킬이나 `/loop`처럼 인수가 다른 명령으로 시작할 수 있는 스킬을 스택하면 확장은 거기서 끝납니다. 해당 토큰 및 그 뒤의 모든 것이 확장된 모든 스킬의 인수 텍스트가 됩니다.

752 

749<h2 id="advanced-patterns">753<h2 id="advanced-patterns">

750 고급 패턴754 고급 패턴

751</h2>755</h2>

1044설치가 실패하면 Claude Code가 보고한 메시지와 일치시킵니다:1048설치가 실패하면 Claude Code가 보고한 메시지와 일치시킵니다:

1045 1049 

1046* `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 후 설치를 다시 시도합니다.1050* `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 후 설치를 다시 시도합니다.

1047* 플러그인이 [마켓플레이스에서 찾을 수 없음](/docs/ko/plugins/install#install-a-plugin): 플러그인 이름을 확인합니다.1051* `Plugin "<name>" not found in marketplace "claude-plugins-official"`: 로컬에 있는 마켓플레이스 카탈로그 사본이 오래되었을 수 있습니다. `/plugin marketplace update claude-plugins-official`로 카탈로그를 새로 고친 후 설치를 다시 시도합니다. 재시도 시에도 동일한 메시지가 출력되면 [Plugin not found in marketplace](/docs/ko/plugins/troubleshooting#plugin-not-found-in-marketplace)를 참조합니다.

1048 1052 

1049설치 요약에서 `Run /reload-plugins to apply.`를 보고하면 Claude Code가 해당 재로드를 실행합니다. 재로드 시 다음 메시지가 대화를 다시 읽을 것이라는 경고가 표시되면 `/reload-plugins --force`를 실행하여 현재 세션에서 플러그인의 스킬을 사용할 수 있게 합니다. 그런 다음 Claude에게 기존 스킬을 평가하도록 요청합니다. 예를 들어 `evaluate my summarize-changes skill with skill-creator`입니다. 플러그인은 테스트 케이스 작성을 안내하고 루프를 실행합니다:1053설치 요약에서 `Run /reload-plugins to apply.`를 보고하면 Claude Code가 해당 재로드를 실행합니다. 재로드 시 다음 메시지가 대화를 다시 읽을 것이라는 경고가 표시되면 `/reload-plugins --force`를 실행하여 현재 세션에서 플러그인의 스킬을 사용할 수 있게 합니다. 그런 다음 Claude에게 기존 스킬을 평가하도록 요청합니다. 예를 들어 `evaluate my summarize-changes skill with skill-creator`입니다. 플러그인은 테스트 케이스 작성을 안내하고 루프를 실행합니다:

1050 1054 

281 전체 화면 모드281 전체 화면 모드

282 </h4>282 </h4>

283 283 

284 Claude Code는 기본 및 전체 화면 렌더러 모두에서 `userMessageBackground`, `bashMessageBackgroundColor` 및 `memoryBackgroundColor`를 칠합니다. [전체 화면 렌더링 모드](/docs/ko/fullscreen)에서만 `userMessageBackgroundHover` 및 `selectionBg`를 사용합니다.284 Claude Code는 [전체 화면 렌더링 모드](/docs/ko/fullscreen)에서만 `userMessageBackgroundHover`, `selectionBg` 및 `composerSidebarBackground`를 사용합니다. `userMessageBackground`, `bashMessageBackgroundColor` 및 `memoryBackgroundColor`는 기본 및 전체 화면 렌더러 모두에서 칠합니다.

285 285 

286 | 토큰 | 제어 대상 |286 | 토큰 | 제어 대상 |

287 | :- | :- |287 | :- | :- |

290 | `bashMessageBackgroundColor` | 트랜스크립트의 `!` 셸 명령 항목 뒤 배경 |290 | `bashMessageBackgroundColor` | 트랜스크립트의 `!` 셸 명령 항목 뒤 배경 |

291 | `memoryBackgroundColor` | 트랜스크립트의 `#` 메모리 항목 뒤 배경 |291 | `memoryBackgroundColor` | 트랜스크립트의 `#` 메모리 항목 뒤 배경 |

292 | `selectionBg` | 마우스로 선택한 텍스트의 배경 |292 | `selectionBg` | 마우스로 선택한 텍스트의 배경 |

293 | `composerSidebarBackground` | [diff 패널](/docs/ko/fullscreen#watch-your-changes-in-the-diff-panel)이나 [mod의 창](/docs/ko/plugins/mods/interface)과 같이 대화 옆에 있는 패널의 배경 |

293 294 

294 <h4 id="usage-meter-and-speaker-labels">295 <h4 id="usage-meter-and-speaker-labels">

295 사용량 미터 및 스피커 레이블296 사용량 미터 및 스피커 레이블

10 10 

11VS Code 확장 프로그램은 Claude Code를 위한 기본 그래픽 인터페이스를 제공하며, IDE에 직접 통합됩니다. 이것이 VS Code에서 Claude Code를 사용하는 권장 방법입니다.11VS Code 확장 프로그램은 Claude Code를 위한 기본 그래픽 인터페이스를 제공하며, IDE에 직접 통합됩니다. 이것이 VS Code에서 Claude Code를 사용하는 권장 방법입니다.

12 12 

13확장 프로그램을 사용하면 Claude의 계획을 수락하기 전에 검토하고 편집할 수 있으며, 편집이 이루어질 때 자동으로 수락하고, 선택 항목에서 특정 줄 범위가 있는 파일을 @-멘션으로 표시하고, 대화 기록에 액세스하고, 별도의 탭이나 창에서 여러 대화를 열 수 있습니다.13확장 프로그램을 사용하면 다음을 수행할 수 있습니다.

14 

15* Claude의 계획을 수락하기 전에 검토하고 편집

16* 편집이 이루어질 때 자동으로 수락

17* 선택 항목에서 특정 줄 범위가 있는 파일을 @-멘션

18* 대화 기록에 액세스

19* 별도의 탭이나 창에서 여러 대화 열기

14 20 

15<h2 id="prerequisites">21<h2 id="prerequisites">

16 필수 조건22 필수 조건

29 확장 프로그램 설치35 확장 프로그램 설치

30</h2>36</h2>

31 37 

32IDE에 대한 링크를 클릭하여 직접 설치합니다:38사용 중인 IDE의 링크를 클릭하여 바로 설치합니다:

33 39 

34* [VS Code용 설치](vscode:extension/anthropic.claude-code)40* [VS Code용 설치](vscode:extension/anthropic.claude-code)

35* [Cursor용 설치](cursor:extension/anthropic.claude-code)41* [Cursor용 설치](cursor:extension/anthropic.claude-code)

36 42 

37또는 VS Code에서 `Cmd+Shift+X`(Mac) 또는 `Ctrl+Shift+X`(Windows/Linux)를 눌러 확장 프로그램 보기를 열고, "Claude Code"를 검색한 후 **설치**를 클릭합니다.43또는 VS Code에서 `Cmd+Shift+X`(Mac) 또는 `Ctrl+Shift+X`(Windows/Linux)를 눌러 Extensions 보기를 열고, "Claude Code"를 검색한 다음 **Install**을 클릭합니다.

38 44 

39확장 프로그램의 버전 번호는 함께 번들된 Claude Code 버전입니다. 예를 들어 Claude Code v2.1.286 이상이 필요한 기능을 사용하려면 확장 프로그램 버전 2.1.286 이상이 필요하며, 이 버전은 확장 프로그램 보기에서 확인할 수 있습니다.45확장 프로그램의 버전 번호는 확장 프로그램에 번들로 포함된 Claude Code 버전입니다. 예를 들어 Claude Code v2.1.286 이상이 필요한 기능을 사용하려면 확장 프로그램 버전 2.1.286 이상이 필요하며, 이 버전은 Extensions 보기에서 확인할 수 있습니다.

40 46 

41확장 프로그램은 Devin Desktop 또는 Kiro와 같은 다른 VS Code 포크에도 설치됩니다. 편집기의 확장 프로그램 보기에서 "Claude Code"를 검색하거나 [Open VSX 레지스트리](https://open-vsx.org/extension/Anthropic/claude-code)에서 설치합니다. 편집기에서 확장 프로그램을 설치할 수 없는 경우 [CLI](/docs/ko/quickstart)를 설치하고 통합 터미널에서 `claude`를 실행합니다. CLI는 모든 터미널에서 작동합니다.47Claude Code는 다른 편집기와 컨테이너에서도 실행됩니다:

42 48 

43dev 컨테이너 내에서 Claude Code를 실행하려면 [개발 컨테이너](/docs/ko/devcontainer)를 참조하세요.49* **기타 VS Code 포크**: 확장 프로그램은 Devin Desktop이나 Kiro 같은 포크에도 설치됩니다. 편집기의 Extensions 보기에서 "Claude Code"를 검색하거나 [Open VSX 레지스트리](https://open-vsx.org/extension/Anthropic/claude-code)에서 설치합니다.

50* **확장 프로그램을 설치할 수 없는 편집기**: 대신 [CLI를 설치](/docs/ko/quickstart)하고 편집기의 통합 터미널에서 `claude`를 실행합니다. CLI는 모든 터미널에서 작동합니다.

51* **개발 컨테이너**: 개발 컨테이너 내부에서 Claude Code를 실행하려면 [개발 컨테이너](/docs/ko/devcontainer)를 참조하세요.

44 52 

45<Note>설치 후 확장 프로그램이 나타나지 않으면 VS Code를 다시 시작하거나 명령 팔레트에서 "Developer: Reload Window"를 실행합니다.</Note>53<Note>설치 후 확장 프로그램이 나타나지 않으면 VS Code를 다시 시작하거나 Command Palette에서 "Developer: Reload Window"를 실행합니다.</Note>

46 54 

47<h2 id="get-started">55<h2 id="get-started">

48 시작하기56 시작하기

49</h2>57</h2>

50 58 

51설치 후 VS Code 인터페이스를 통해 Claude Code를 사용할 수 있습니다.59설치가 완료되면 VS Code 인터페이스를 통해 Claude Code를 사용할 수 있습니다.

52 60 

53<Steps>61<Steps>

54 <Step title="Claude Code 패널 열기">62 <Step title="Claude Code 패널 열기">

55 VS Code 전체에서 Spark 아이콘은 Claude Code를 나타냅니다. <img src="https://mintcdn.com/claude-code/c5r9_6tjPMzFdDDT/images/vs-code-spark-icon.svg?fit=max&auto=format&n=c5r9_6tjPMzFdDDT&q=85&s=3ca45e00deadec8c8f4b4f807da94505" alt="Spark icon" style={{display: "inline", height: "0.85em", verticalAlign: "middle"}} width="16" height="16" data-path="images/vs-code-spark-icon.svg" />63 VS Code 전반에서 Spark 아이콘은 Claude Code를 나타냅니다: <img src="https://mintcdn.com/claude-code/c5r9_6tjPMzFdDDT/images/vs-code-spark-icon.svg?fit=max&auto=format&n=c5r9_6tjPMzFdDDT&q=85&s=3ca45e00deadec8c8f4b4f807da94505" alt="Spark 아이콘" style={{display: "inline", height: "0.85em", verticalAlign: "middle"}} width="16" height="16" data-path="images/vs-code-spark-icon.svg" />

56 64 

57 Claude를 여는 가장 빠른 방법은 **편집기 도구 모음**(편집기의 오른쪽 상단 모서리)에서 Spark 아이콘을 클릭하는 것입니다. 파일을 열었을 때만 아이콘이 나타납니다.65 Claude를 가장 빠르게 여는 방법은 **Editor Toolbar**(에디터 오른쪽 상단 모서리)에서 Spark 아이콘을 클릭하는 것입니다. 이 아이콘은 파일이 열려 있을 때만 표시됩니다.

58 66 

59 <img src="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=eb4540325d94664c51776dbbfec4cf02" alt="편집기 도구 모음에서 Spark 아이콘을 보여주는 VS Code 편집기" width="2796" height="734" data-path="images/vs-code-editor-icon.png" />67 <img src="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=eb4540325d94664c51776dbbfec4cf02" alt="Editor Toolbar에 Spark 아이콘이 표시된 VS Code 에디터" width="2796" height="734" data-path="images/vs-code-editor-icon.png" />

60 68 

61 Claude Code를 여는 다른 방법:69 Claude Code를 여는 다른 방법은 다음과 같습니다.

62 70 

63 * **활동 표시줄**: 왼쪽 사이드바의 Spark 아이콘을 클릭하여 세션 목록을 엽니다. 세션을 클릭하여 [선호하는 위치](#extension-settings)에서 열거나 새 세션을 시작합니다. 이 아이콘은 항상 활동 표시줄에 표시됩니다.71 * **Activity Bar**: 왼쪽 사이드바에서 Spark 아이콘을 클릭하면 세션 목록이 열립니다. 세션을 클릭하면 [선호하는 위치](#extension-settings)에서 열리며, 새 세션을 시작할 수도 있습니다. 이 아이콘은 Activity Bar에 항상 표시됩니다.

64 * **명령 팔레트**: `Cmd+Shift+P`(Mac) 또는 `Ctrl+Shift+P`(Windows/Linux)를 누르고 "Claude Code"를 입력한 후 "새 탭에서 열기"와 같은 옵션을 선택합니다.72 * **Command Palette**: `Cmd+Shift+P`(Mac) 또는 `Ctrl+Shift+P`(Windows/Linux)를 누르고 "Claude Code"를 입력한 다음 "Open in New Tab"과 같은 옵션을 선택합니다.

65 * **상태 표시줄**: 창의 오른쪽 아래 모서리에서 **✻ Claude Code**를 클릭합니다. 파일을 열지 않았을 때도 작동합니다.73 * **Status Bar**: 창 오른쪽 하단 모서리의 **✻ Claude Code**를 클릭합니다. 파일이 열려 있지 않아도 작동합니다.

66 74 

67 Claude 패널을 드래그하여 VS Code의 어느 곳으로든 재배치할 수 있습니다. 자세한 내용은 [워크플로우 사용자 정의](#customize-your-workflow)를 참조하십시오.75 Claude 패널을 드래그하여 VS Code 내 원하는 위치로 옮길 수 있습니다. 자세한 내용은 [워크플로 사용자 지정](#customize-your-workflow)을 참조하세요.

68 </Step>76 </Step>

69 77 

70 <Step title="로그인">78 <Step title="로그인">

71 처음 패널을 열면 로그인 화면이 나타납니다. **로그인**을 클릭하고 브라우저에서 인증을 완료합니다.79 패널을 처음 열면 로그인 화면이 나타납니다. **Sign in**을 클릭하고 브라우저에서 인증을 완료합니다.

72 80 

73 나중에 **로그인하지 않음 · /login을 실행하십시오**가 표시되면 확장 프로그램이 자동으로 로그인 화면을 다시 엽니다. 표시되지 않으면 명령 팔레트에서 **개발자: 창 다시 로드**를 사용하여 창을 다시 로드합니다.81 이후 **Not logged in · Please run /login**이 표시되면 확장 프로그램이 자동으로 로그인 화면을 다시 엽니다. 로그인 화면이 나타나지 않으면 Command Palette에서 **Developer: Reload Window**로 창을 다시 로드합니다.

74 82 

75 셸에 `ANTHROPIC_API_KEY`가 설정되어 있지만 여전히 로그인 프롬프트가 표시되면 VS Code가 셸 환경을 상속하지 못했을 수 있습니다. 터미널에서 `code .`로 VS Code를 시작하여 환경 변수를 상속하거나 대신 Claude 계정으로 로그인합니다.83 셸에 `ANTHROPIC_API_KEY`를 설정했는데도 로그인 프롬프트가 표시된다면 VS Code가 셸 환경을 상속하지 못했을 수 있습니다. 환경 변수를 상속하도록 터미널에서 `code .`로 VS Code를 실행하거나, 대신 Claude 계정으로 로그인합니다.

76 84 

77 로그인한 후 **Claude Code 배우기** 체크리스트가 나타납니다. **보여주기**를 클릭하여 각 항목을 진행하거나 X로 닫습니다. 나중에 다시 열려면 VS Code 설정의 확장 프로그램 → Claude Code에서 **온보딩 숨기기**를 선택 해제합니다.85 로그인하면 **Learn Claude Code** 체크리스트가 나타납니다. **Show me**를 클릭하여 각 항목을 진행하거나 X를 눌러 닫을 수 있습니다. 나중에 다시 열려면 VS Code 설정의 **Extensions > Claude Code**에서 **Hide Onboarding**의 체크를 해제합니다.

78 </Step>86 </Step>

79 87 

80 <Step title="프롬프트 전송">88 <Step title="프롬프트 보내기">

81 코드나 파일을 도와달라고 Claude에 요청합니다. 작동 방식 설명, 문제 디버깅 또는 변경 사항 만들기 등이 있습니다.89 무언가의 작동 방식 설명, 문제 디버깅, 변경 작업 등 코드나 파일과 관련된 도움을 Claude에게 요청합니다.

82 90 

83 <Tip>Claude는 자동으로 선택한 텍스트를 봅니다. `Option+K`(Mac) / `Alt+K`(Windows/Linux)를 눌러 프롬프트에 @-멘션 참조(예: `@file.ts#5-10`)를 삽입할 수도 있습니다.</Tip>91 <Tip>Claude는 선택한 텍스트를 자동으로 인식합니다. `Option+K`(Mac) / `Alt+K`(Windows/Linux)를 누르면 @-멘션 참조(예: `@file.ts#5-10`)도 프롬프트에 삽입됩니다.</Tip>

84 92 

85 파일의 특정 줄에 대해 묻는 예시입니다.93 다음은 파일의 특정 줄에 대해 질문하는 예시입니다.

86 94 

87 <img src="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=ede3ed8d8d5f940e01c5de636d009cfd" alt="Python 파일에서 2-3줄이 선택되고 Claude Code 패널에 @-멘션 참조가 있는 해당 줄에 대한 질문이 표시되는 VS Code 편집기" width="3288" height="1876" data-path="images/vs-code-send-prompt.png" />95 <img src="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=ede3ed8d8d5f940e01c5de636d009cfd" alt="Python 파일에서 2-3번째 줄이 선택된 VS Code 에디터와, 해당 줄에 대한 질문을 @-멘션 참조와 함께 보여주는 Claude Code 패널" width="3288" height="1876" data-path="images/vs-code-send-prompt.png" />