Documentation 2026-10-05 23:58 UTC to 2026-10-06 12:01 UTC

174| 주제 | 알아야 할 사항 | 시작 위치 |174| 주제 | 알아야 할 사항 | 시작 위치 |

175| :- | :- | :- |175| :- | :- | :- |

176| Data usage policy | Anthropic이 수집하는 항목, 보존 기간, 학습에 사용되지 않는 항목 | [Data usage](/docs/ko/data-usage) |176| Data usage policy | Anthropic이 수집하는 항목, 보존 기간, 학습에 사용되지 않는 항목 | [Data usage](/docs/ko/data-usage) |

177| Zero Data Retention (ZDR) | 요청 완료 후 저장되지 않음. Claude for Enterprise에서 사용 가능 | [Zero data retention](/docs/ko/zero-data-retention) |177| Zero Data Retention (ZDR) | 요청 완료 후 저장되지 않음. Claude for Enterprise의 자격을 갖춘 계정에서 사용 가능 | [Zero data retention](/docs/ko/zero-data-retention) |

178| HIPAA 구성 | HIPAA가 활성화된 Claude for Enterprise 조직용. 일부 Claude Code(로컬 모드) 기능은 꺼져 있으며 다른 기능은 기본적으로 꺼져 있음 | [HIPAA 대응 조직을 위한 Claude Code(로컬 모드) 설정](/docs/ko/hipaa-setup) |

178| Security architecture | 네트워크 모델, 암호화, 인증, 감사 추적 | [Security](/docs/ko/security) |179| Security architecture | 네트워크 모델, 암호화, 인증, 감사 추적 | [Security](/docs/ko/security) |

179 180 

180요청 수준 감사 로깅이 필요하거나 데이터 민감도별로 트래픽을 라우팅하려면 개발자와 제공자 사이에 게이트웨이를 배치하세요. 자체 호스팅된 [Claude apps gateway](/docs/ko/claude-apps-gateway)는 IdP 신원을 포함한 요청별 감사 로그를 기록하거나 다른 [LLM gateway](/docs/ko/llm-gateway)를 사용하세요. 규제 요구사항 및 인증은 [Legal and compliance](/docs/ko/legal-and-compliance)를 참조하세요.181요청 수준 감사 로깅이 필요하거나 데이터 민감도별로 트래픽을 라우팅하려면 개발자와 제공자 사이에 게이트웨이를 배치하는 것이 좋습니다. 자체 호스팅된 [Claude apps gateway](/docs/ko/claude-apps-gateway)는 IdP 신원을 포함한 요청별 감사 로그를 기록하며, 다른 [LLM gateway](/docs/ko/llm-gateway)를 사용할 수도 있습니다. 게이트웨이를 거치는 세션은 HIPAA 구성의 대상이 되지 않습니다. 대상이 되는 연결 목록은 [개발자의 로그인 및 연결 방식 확인](/docs/ko/hipaa-setup#check-how-developers-sign-in-and-connect)에서 확인할 수 있습니다. 규제 요구사항 및 인증은 [Legal and compliance](/docs/ko/legal-and-compliance)를 참조하세요.

181 182 

182<h2 id="verify-and-onboard">183<h2 id="verify-and-onboard">

183 확인 및 온보딩184 확인 및 온보딩

118| 프로젝트(루트) | `<cwd>/CLAUDE.md` 또는 `<cwd>/.claude/CLAUDE.md` | `settingSources`에 `"project"` 포함 |118| 프로젝트(루트) | `<cwd>/CLAUDE.md` 또는 `<cwd>/.claude/CLAUDE.md` | `settingSources`에 `"project"` 포함 |

119| 프로젝트 규칙 | `<cwd>/.claude/rules/*.md` 및 모든 상위 디렉토리의 `.claude/rules/*.md` | `settingSources`에 `"project"` 포함 |119| 프로젝트 규칙 | `<cwd>/.claude/rules/*.md` 및 모든 상위 디렉토리의 `.claude/rules/*.md` | `settingSources`에 `"project"` 포함 |

120| 프로젝트(상위 디렉토리) | `cwd` 위의 디렉토리에 있는 `CLAUDE.md` 파일 | `settingSources`에 `"project"` 포함, 세션 시작 시 로드 |120| 프로젝트(상위 디렉토리) | `cwd` 위의 디렉토리에 있는 `CLAUDE.md` 파일 | `settingSources`에 `"project"` 포함, 세션 시작 시 로드 |

121| 프로젝트(하위 디렉토리) | `cwd`의 하위 디렉토리에 있는 `CLAUDE.md` 파일 | `settingSources`에 `"project"` 포함, 에이전트가 해당 서브트리의 파일을 읽을 때 필요에 따라 로드 |121| 프로젝트(하위 디렉토리) | `cwd`의 하위 디렉토리에 있는 `CLAUDE.md` 파일 | `settingSources`에 `"project"` 포함, [필요에 따라](/docs/ko/memory#how-claude-md-files-load) 로드 |

122| 로컬 | `<cwd>/CLAUDE.local.md` 및 모든 상위 디렉토리의 `CLAUDE.local.md` | `settingSources`에 `"local"` 포함 |122| 로컬 | `<cwd>/CLAUDE.local.md` 및 모든 상위 디렉토리의 `CLAUDE.local.md` | `settingSources`에 `"local"` 포함 |

123| 사용자 | `~/.claude/CLAUDE.md` | `settingSources`에 `"user"` 포함 |123| 사용자 | `~/.claude/CLAUDE.md` | `settingSources`에 `"user"` 포함 |

124| 사용자 규칙 | `~/.claude/rules/*.md` | `settingSources`에 `"user"` 포함 |124| 사용자 규칙 | `~/.claude/rules/*.md` | `settingSources`에 `"user"` 포함 |

10 10 

11완전한 API 문서는 [TypeScript SDK 참조](/docs/ko/agent-sdk/typescript) 및 [Python SDK 참조](/docs/ko/agent-sdk/python)를 참조하십시오.11완전한 API 문서는 [TypeScript SDK 참조](/docs/ko/agent-sdk/typescript) 및 [Python SDK 참조](/docs/ko/agent-sdk/python)를 참조하십시오.

12 12 

13<span id="estimates-not-billing" />

14 

13<Warning>15<Warning>

14 `total_cost_usd` 및 `costUSD` 필드는 클라이언트 측 추정값이며, 권위 있는 청구 데이터가 아닙니다. SDK는 빌드 시간에 번들로 제공되는 가격 표에서 로컬로 계산하거나, [`modelPricing`](/docs/ko/settings-reference#modelpricing) 표가 적용 중인 경우를 제외하고 계산합니다. 다음의 경우에 실제 청구 금액과 차이가 날 수 있습니다:16 `total_cost_usd` 및 `costUSD` 필드는 클라이언트 측 추정값이며, 권위 있는 청구 데이터가 아닙니다. SDK는 빌드 시간에 번들로 제공되는 가격 표에서 로컬로 계산하거나, [`modelPricing`](/docs/ko/settings-reference#modelpricing) 표가 적용 중인 경우를 제외하고 계산합니다. 다음의 경우에 실제 청구 금액과 차이가 날 수 있습니다:

15 17 

242* **독립적인 호출, `resume` 또는 `continue` 옵션 없음**: 각 결과는 자체 호출만 포함하므로, 아래 예제처럼 총합을 직접 더해야 합니다.244* **독립적인 호출, `resume` 또는 `continue` 옵션 없음**: 각 결과는 자체 호출만 포함하므로, 아래 예제처럼 총합을 직접 더해야 합니다.

243* **동일한 세션을 재개하는 호출**: Claude Code는 프로세스가 정상적으로 종료될 때 세션의 총합을 [트랜스크립트](/docs/ko/sessions#where-transcripts-are-stored)에 저장하고, 나중에 호출이 세션을 재개하거나 포크할 때 복구합니다. 각 결과는 이미 세션의 이전 지출을 포함합니다. 세션 총합을 위해 최신 결과를 읽으십시오. 결과를 합산하면 복구된 지출이 중복 계산됩니다. v2.1.277 이전에는 SDK 또는 `claude -p`를 통해 재개한 세션이 총합을 0에서 시작했으므로, 각 호출의 결과는 해당 호출만 포함했습니다.245* **동일한 세션을 재개하는 호출**: Claude Code는 프로세스가 정상적으로 종료될 때 세션의 총합을 [트랜스크립트](/docs/ko/sessions#where-transcripts-are-stored)에 저장하고, 나중에 호출이 세션을 재개하거나 포크할 때 복구합니다. 각 결과는 이미 세션의 이전 지출을 포함합니다. 세션 총합을 위해 최신 결과를 읽으십시오. 결과를 합산하면 복구된 지출이 중복 계산됩니다. v2.1.277 이전에는 SDK 또는 `claude -p`를 통해 재개한 세션이 총합을 0에서 시작했으므로, 각 호출의 결과는 해당 호출만 포함했습니다.

244 246 

247어느 경우든 결합된 수치는 여전히 [클라이언트 측 추정치](#estimates-not-billing)입니다.

248 

245스트리밍 입력 모드에서는 [스트리밍 입력 모드에서 비용 추적하기](#track-costs-in-streaming-input-mode)에 설명된 대로 각 호출의 총합을 읽으십시오. 충돌로 끝난 호출의 경우 [세션 충돌 후 총합 복구하기](#recover-totals-after-a-session-crash)를 참조하십시오.249스트리밍 입력 모드에서는 [스트리밍 입력 모드에서 비용 추적하기](#track-costs-in-streaming-input-mode)에 설명된 대로 각 호출의 총합을 읽으십시오. 충돌로 끝난 호출의 경우 [세션 충돌 후 총합 복구하기](#recover-totals-after-a-session-crash)를 참조하십시오.

246 250 

247다음 예제는 두 개의 `query()` 호출을 순차적으로 실행하고, 각 호출의 `total_cost_usd`를 누적 총합에 더하며, 호출별 비용과 결합된 비용을 모두 출력합니다:251다음 예제는 두 개의 `query()` 호출을 순차적으로 실행하고, 각 호출의 `total_cost_usd`를 누적 총합에 더하며, 호출별 비용과 결합된 비용을 모두 출력합니다:

15| 원하는 작업 | 수행 방법 |15| 원하는 작업 | 수행 방법 |

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

17| 도구 정의 | 이름, 설명, 스키마 및 핸들러를 사용하여 [`@tool`](/docs/ko/agent-sdk/python#tool) (Python) 또는 [`tool()`](/docs/ko/agent-sdk/typescript#tool) (TypeScript)을 사용합니다. [사용자 정의 도구 만들기](#create-a-custom-tool)를 참조하세요. |17| 도구 정의 | 이름, 설명, 스키마 및 핸들러를 사용하여 [`@tool`](/docs/ko/agent-sdk/python#tool) (Python) 또는 [`tool()`](/docs/ko/agent-sdk/typescript#tool) (TypeScript)을 사용합니다. [사용자 정의 도구 만들기](#create-a-custom-tool)를 참조하세요. |

18| 매개변수를 선택 사항으로 만들기 | 스키마에서 선택 사항으로 선언하고 핸들러에서 기본값을 적용합니다. [매개변수를 선택 사항으로 만들기](#make-a-parameter-optional)를 참조하세요. |

18| Claude에 도구 등록 | `create_sdk_mcp_server` / `createSdkMcpServer`로 래핑하고 `query()`의 `mcpServers`에 전달합니다. [사용자 정의 도구 호출](#call-a-custom-tool)을 참조하세요. |19| Claude에 도구 등록 | `create_sdk_mcp_server` / `createSdkMcpServer`로 래핑하고 `query()`의 `mcpServers`에 전달합니다. [사용자 정의 도구 호출](#call-a-custom-tool)을 참조하세요. |

19| 도구 사전 승인 | 허용된 도구에 추가합니다. [허용된 도구 구성](#configure-allowed-tools)을 참조하세요. |20| 도구 사전 승인 | 허용된 도구에 추가합니다. [허용된 도구 구성](#configure-allowed-tools)을 참조하세요. |

20| Claude의 컨텍스트에서 기본 제공 도구 제거 | 원하는 기본 제공 도구만 나열하는 `tools` 배열을 전달합니다. [허용된 도구 구성](#configure-allowed-tools)을 참조하세요. |21| Claude의 컨텍스트에서 기본 제공 도구 제거 | 원하는 기본 제공 도구만 나열하는 `tools` 배열을 전달합니다. [허용된 도구 구성](#configure-allowed-tools)을 참조하세요. |

32 33 

33* **이름:** Claude가 도구를 호출할 때 사용하는 고유 식별자입니다.34* **이름:** Claude가 도구를 호출할 때 사용하는 고유 식별자입니다.

34* **설명:** 도구가 수행하는 작업입니다. Claude는 이를 읽고 도구를 호출할 시기를 결정합니다.35* **설명:** 도구가 수행하는 작업입니다. Claude는 이를 읽고 도구를 호출할 시기를 결정합니다.

35* **입력 스키마:** Claude가 제공해야 하는 인수입니다. TypeScript에서는 항상 [Zod 스키마](https://zod.dev/)이며, 핸들러의 `args`는 자동으로 입력됩니다. Python에서는 `{"latitude": float}`와 같이 이름을 타입에 매핑하는 딕셔너리이며, SDK가 JSON 스키마로 변환합니다. Python 데코레이터는 열거형, 범위, 선택적 필드 또는 중첩된 객체가 필요할 때 전체 [JSON 스키마](https://json-schema.org/understanding-json-schema/about) 딕셔너리도 허용합니다.36* **입력 스키마:** 도구가 받는 인수이며, 언어별로 다음과 같이 선언합니다:

37 * **TypeScript**: [Zod 스키마](https://zod.dev/)입니다. 핸들러의 `args`는 이 스키마에서 타입을 가져옵니다. 필드에 `.describe()`를 호출하면 Claude가 보는 설명을 필드에 부여할 수 있습니다.

38 * **Python**: `{"latitude": float}`와 같이 이름을 타입에 매핑하는 딕셔너리이며, SDK가 이를 JSON 스키마로 변환합니다. `{"latitude": Annotated[float, "Latitude coordinate"]}`와 같이 타입을 `Annotated`로 감싸면 Claude가 보는 설명을 필드에 부여할 수 있습니다. 열거형, 범위, 선택적 필드 또는 중첩된 객체가 필요할 때는 데코레이터에 전체 [JSON 스키마](https://json-schema.org/understanding-json-schema/about) 딕셔너리를 직접 전달할 수도 있습니다.

36* **핸들러:** Claude가 도구를 호출할 때 실행되는 비동기 함수입니다. 검증된 인수를 받으며 다음을 포함하는 객체를 반환해야 합니다:39* **핸들러:** Claude가 도구를 호출할 때 실행되는 비동기 함수입니다. 검증된 인수를 받으며 다음을 포함하는 객체를 반환해야 합니다:

37 * `content` (필수): 각각 `"text"`, `"image"`, `"audio"`, `"resource"` 또는 `"resource_link"`의 `type`을 가진 결과 블록의 배열입니다. 텍스트가 아닌 블록은 [이미지 및 리소스 반환](#return-images-and-resources)을 참조하세요.40 * `content` (필수): 각각 `"text"`, `"image"`, `"audio"`, `"resource"` 또는 `"resource_link"`의 `type`을 가진 결과 블록의 배열입니다. 텍스트가 아닌 블록은 [이미지 및 리소스 반환](#return-images-and-resources)을 참조하세요.

38 * `structuredContent` (선택사항): 결과를 기계 판독 가능한 데이터로 보유하는 JSON 객체이며, `content`와 함께 반환됩니다. [구조화된 데이터 반환](#return-structured-data)을 참조하세요.41 * `structuredContent` (선택사항): 결과를 기계 판독 가능한 데이터로 보유하는 JSON 객체이며, `content`와 함께 반환됩니다. [구조화된 데이터 반환](#return-structured-data)을 참조하세요.

40 43 

41도구를 정의한 후 [`createSdkMcpServer`](/docs/ko/agent-sdk/typescript#createsdkmcpserver) (TypeScript) 또는 [`create_sdk_mcp_server`](/docs/ko/agent-sdk/python#create_sdk_mcp_server) (Python)를 사용하여 서버에 래핑합니다. 서버는 별도의 프로세스가 아닌 애플리케이션 내에서 인프로세스로 실행됩니다.44도구를 정의한 후 [`createSdkMcpServer`](/docs/ko/agent-sdk/typescript#createsdkmcpserver) (TypeScript) 또는 [`create_sdk_mcp_server`](/docs/ko/agent-sdk/python#create_sdk_mcp_server) (Python)를 사용하여 서버에 래핑합니다. 서버는 별도의 프로세스가 아닌 애플리케이션 내에서 인프로세스로 실행됩니다.

42 45 

46이 페이지에서 HTTP 요청을 수행하는 Python 예제는 [httpx](https://www.python-httpx.org/)를 사용합니다. 프로젝트에서 사용하는 패키지 관리자로 추가하세요:

47 

48<Tabs>

49 <Tab title="Python (uv)">

50 ```bash theme={null}

51 uv add httpx

52 ```

53 </Tab>

54 

55 <Tab title="Python (pip)">

56 ```bash theme={null}

57 pip install httpx

58 ```

59 </Tab>

60</Tabs>

61 

43<h3 id="weather-tool-example">62<h3 id="weather-tool-example">

44 날씨 도구 예제63 날씨 도구 예제

45</h3>64</h3>

46 65 

47이 예제는 `get_temperature` 도구를 정의하고 MCP 서버에 래핑합니다. 도구만 설정합니다. `query`에 전달하고 실행하려면 아래의 [사용자 정의 도구 호출](#call-a-custom-tool)을 참조하세요.66이 예제는 `get_temperature` 도구를 정의하고 MCP 서버에 래핑하며, 서버를 `query`에 전달하지는 않습니다. 도구를 실행하려면 아래의 [사용자 정의 도구 호출](#call-a-custom-tool)을 참조하세요.

48 67 

49<CodeGroup>68<CodeGroup>

50 ```python Python theme={null}69 ```python Python theme={null}

51 from typing import Any70 from typing import Annotated, Any

52 import httpx71 import httpx

53 from claude_agent_sdk import tool, create_sdk_mcp_server72 from claude_agent_sdk import tool, create_sdk_mcp_server

54 73 

57 @tool(76 @tool(

58 "get_temperature",77 "get_temperature",

59 "Get the current temperature at a location",78 "Get the current temperature at a location",

60 {"latitude": float, "longitude": float},79 {

80 "latitude": Annotated[float, "Latitude coordinate"],

81 "longitude": Annotated[float, "Longitude coordinate"],

82 },

61 )83 )

62 async def get_temperature(args: dict[str, Any]) -> dict[str, Any]:84 async def get_temperature(args: dict[str, Any]) -> dict[str, Any]:

63 async with httpx.AsyncClient() as client:85 async with httpx.AsyncClient() as client:

128 150 

129전체 매개변수 세부 정보(JSON 스키마 입력 형식 및 반환 값 구조 포함)는 [`tool()`](/docs/ko/agent-sdk/typescript#tool) TypeScript 참조 또는 [`@tool`](/docs/ko/agent-sdk/python#tool) Python 참조를 참조하세요.151전체 매개변수 세부 정보(JSON 스키마 입력 형식 및 반환 값 구조 포함)는 [`tool()`](/docs/ko/agent-sdk/typescript#tool) TypeScript 참조 또는 [`@tool`](/docs/ko/agent-sdk/python#tool) Python 참조를 참조하세요.

130 152 

131<Tip>153<h3 id="make-a-parameter-optional">

132 매개변수를 선택사항으로 만들려면: TypeScript에서 Zod 필드에 `.optional()`을 추가하고 핸들러에서 기본값을 적용합니다. Python에서는 딕셔너리 스키마가 모든 키를 필수로 취급하므로 스키마에서 매개변수를 생략하고, 설명 문자열에서 언급하고, 핸들러에서 `args.get()`으로 읽습니다. 아래의 [`get_precipitation_chance` 도구](#add-more-tools)는 두 패턴을 모두 보여줍니다.154 매개변수를 선택사항으로 만들기

133</Tip>155</h3>

156 

157매개변수를 선택사항으로 만들려면 스키마에서 선택사항으로 선언하고 핸들러에서 기본값을 적용합니다:

158 

159* **TypeScript**: Zod 필드에 `.optional()`을 추가합니다.

160* **Python**: 딕셔너리 스키마는 모든 키를 필수로 요구합니다. JSON 스키마 형식을 사용하고, 매개변수를 `required`에서 제외한 뒤 `args.get()`으로 읽습니다. 선택적 키가 있는 타입 지정 스키마는 [TypedDict 클래스](/docs/ko/agent-sdk/python#input-schema-options)를 참조하세요.

161 

162[아래의 `get_precipitation_chance` 도구](#add-more-tools)는 두 패턴을 모두 보여줍니다.

134 163 

135<h3 id="call-a-custom-tool">164<h3 id="call-a-custom-tool">

136 사용자 정의 도구 호출165 사용자 정의 도구 호출

182 ```211 ```

183</CodeGroup>212</CodeGroup>

184 213 

185이 스니펫을 [날씨 도구 예제](#weather-tool-example)의 도구 및 서버 정의와 함께 한 파일에 결합한 후 Python의 경우 `python weather.py`로, TypeScript의 경우 `npx tsx weather.ts`로 실행합니다. Claude는 `get_temperature`를 호출하고 스크립트는 샌프란시스코의 현재 온도를 포함한 한 줄 답변을 출력합니다.214이 스니펫을 [날씨 도구 예제](#weather-tool-example)의 도구 및 서버 정의와 함께 `weather.py` 또는 `weather.ts` 한 파일에 결합한 후 터미널에서 실행합니다:

215 

216<Tabs>

217 <Tab title="TypeScript">

218 ```bash theme={null}

219 npx tsx weather.ts

220 ```

221 </Tab>

222 

223 <Tab title="Python (uv)">

224 ```bash theme={null}

225 uv run weather.py

226 ```

227 </Tab>

228 

229 <Tab title="Python (pip)">

230 SDK를 설치한 가상 환경을 활성화한 후 다음을 실행합니다:

231 

232 ```bash theme={null}

233 python weather.py

234 ```

235 </Tab>

236</Tabs>

237 

238Claude는 `get_temperature`를 호출하고 스크립트는 샌프란시스코의 현재 온도를 포함한 한 줄 답변을 출력합니다.

186 239 

187<h3 id="add-more-tools">240<h3 id="add-more-tools">

188 더 많은 도구 추가241 더 많은 도구 추가

197 # Define a second tool for the same server250 # Define a second tool for the same server

198 @tool(251 @tool(

199 "get_precipitation_chance",252 "get_precipitation_chance",

200 "Get the hourly precipitation probability for a location. "253 "Get the hourly precipitation probability for a location",

201 "Optionally pass 'hours' (1-24) to control how many hours to return.",254 {

202 {"latitude": float, "longitude": float},255 "type": "object",

256 "properties": {

257 "latitude": {"type": "number"},

258 "longitude": {"type": "number"},

259 "hours": {

260 "type": "integer",

261 "minimum": 1,

262 "maximum": 24,

263 "description": "How many hours of forecast to return",

264 },

265 },

266 # 'hours' is left out of required, so Claude can omit it

267 "required": ["latitude", "longitude"],

268 },

203 )269 )

204 async def get_precipitation_chance(args: dict[str, Any]) -> dict[str, Any]:270 async def get_precipitation_chance(args: dict[str, Any]) -> dict[str, Any]:

205 # 'hours' isn't in the schema - read it with .get() to make it optional271 # 'hours' isn't in required - read it with .get() to fall back to a default

206 hours = args.get("hours", 12)272 hours = args.get("hours", 12)

207 async with httpx.AsyncClient() as client:273 async with httpx.AsyncClient() as client:

208 response = await client.get(274 response = await client.get(

147 }147 }

148 ```148 ```

149 149 

1503. **TypedDict 클래스**: `NotRequired` 키가 `required`에서 제외되는 타입 지정 스키마입니다.

151 

152 * **Python 3.11 이상**: `typing`에서 `TypedDict`와 `NotRequired`를 가져옵니다.

153 * **Python 3.10**: `typing`에는 `NotRequired`가 없습니다. SDK가 Python 3.10에 설치하는 `typing_extensions`에서 `TypedDict`와 `NotRequired`를 가져옵니다.

154 

155 ```python theme={null}

156 from typing import Annotated, Any, NotRequired, TypedDict

157 from claude_agent_sdk import tool

158 

159 

160 class ForecastArgs(TypedDict):

161 latitude: Annotated[float, "Latitude coordinate"]

162 hours: NotRequired[Annotated[int, "How many hours of forecast to return"]]

163 

164 

165 @tool("get_forecast", "Get the hourly forecast for a location", ForecastArgs)

166 async def get_forecast(args: dict[str, Any]) -> dict[str, Any]:

167 hours = args.get("hours", 12)

168 return {"content": [{"type": "text", "text": f"{hours}-hour forecast for {args['latitude']}"}]}

169 ```

170 

171간단한 매핑 및 TypedDict 형식에서는 타입을 `Annotated[type, "description"]`으로 감싸 필드의 설명을 설정합니다.

172 

150<h4 id="returns-2">173<h4 id="returns-2">

151 반환값174 반환값

152</h4>175</h4>

1781 data: dict[str, Any]1804 data: dict[str, Any]

1782```1805```

1783 1806 

1807자체 데이터클래스가 없는 서브타입은 `SystemMessage`로 도착합니다. 턴 사이의 세션 상태를 추적하려면 [`CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1`](/docs/ko/env-vars#variables)을 설정하고 `subtype`이 `session_state_changed`인 각 메시지에서 `message.data["state"]`를 읽으십시오. [`SDKSessionStateChangedMessage`](/docs/ko/agent-sdk/typescript#sdksessionstatechangedmessage)에 전달될 수 있는 상태가 나열되어 있습니다. 이를 읽으려면 `receive_messages()`로 반복하십시오. `receive_response()`는 `ResultMessage`에서 중지되며, `session_state_changed` 메시지는 해당 결과 뒤에 올 수 있습니다.

1808 

1784<h3 id="resultmessage">1809<h3 id="resultmessage">

1785 `ResultMessage`1810 `ResultMessage`

1786</h3>1811</h3>

2267 2292 

2268매개변수:2293매개변수:

2269 2294 

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

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

2272* `context`: 추가 정보가 있는 hook 컨텍스트2297* `context`: 추가 정보가 있는 hook 컨텍스트

2273 2298 

317 317 

318이 접근 방식은 사용자 정의 도구를 작성하지 않고 모든 HTTP 기반 서비스를 처리하지만, 인증서 관리 주변의 복잡성을 추가합니다.318이 접근 방식은 사용자 정의 도구를 작성하지 않고 모든 HTTP 기반 서비스를 처리하지만, 인증서 관리 주변의 복잡성을 추가합니다.

319 319 

320모든 프로그램이 `HTTP_PROXY`/`HTTPS_PROXY`를 존중하는 것은 아닙니다. 대부분의 도구(curl, pip, npm, git)는 존중하지만, 일부는 이러한 변수를 무시하고 직접 연결할 수 있습니다. 예를 들어, Node.js `fetch()`는 기본적으로 이러한 변수를 무시합니다. Node 24+에서는 `NODE_USE_ENV_PROXY=1`을 설정하여 지원을 활성화할 수 있습니다. 포괄적인 범위를 위해 [proxychains](https://github.com/haad/proxychains)를 사용하여 네트워크 호출을 가로채거나, iptables를 구성하여 아웃바운드 트래픽을 투명 프록시로 리디렉션할 수 있습니다.320모든 프로그램이 `HTTP_PROXY`/`HTTPS_PROXY`를 존중하는 것은 아닙니다. 대부분의 도구(curl, pip, npm, git)는 존중하지만, 일부는 이러한 변수를 무시하고 직접 연결할 수 있습니다. 예를 들어, Node.js `fetch()`는 기본적으로 이러한 변수를 무시합니다. Node 24+에서는 `NODE_USE_ENV_PROXY=1`을 설정하여 지원을 활성화할 수 있습니다. 이러한 변수를 무시하는 도구까지 처리하려면 [proxychains](https://github.com/haad/proxychains)를 사용하여 네트워크 호출을 가로채거나, iptables를 구성하여 아웃바운드 트래픽을 투명 프록시로 리디렉션할 수 있습니다.

321 321 

322<Info>322<Info>

323 **투명 프록시**는 네트워크 수준에서 트래픽을 가로채므로 클라이언트가 이를 사용하도록 구성할 필요가 없습니다. 일반 프록시는 클라이언트가 명시적으로 연결하고 HTTP CONNECT 또는 SOCKS를 말해야 합니다. 투명 프록시(Squid 또는 투명 모드의 mitmproxy와 같은)는 리디렉션된 원본 TCP 연결을 처리할 수 있습니다.323 **투명 프록시**는 네트워크 수준에서 트래픽을 가로채므로 클라이언트가 이를 사용하도록 구성할 필요가 없습니다. 일반 프록시는 클라이언트가 명시적으로 연결하고 HTTP CONNECT 또는 SOCKS를 말해야 합니다. 투명 프록시(Squid 또는 투명 모드의 mitmproxy와 같은)는 리디렉션된 원본 TCP 연결을 처리할 수 있습니다.

8 8 

9Agent Skills는 Claude가 관련성이 있을 때 호출하는 전문화된 기능으로 Claude를 확장합니다. Skills는 지침, 설명 및 선택적 지원 리소스를 포함하는 `SKILL.md` 파일로 패키징됩니다. 이 페이지는 또한 [Agent SDK 세션의 명령](#commands-in-agent-sdk-sessions)을 다룹니다.9Agent Skills는 Claude가 관련성이 있을 때 호출하는 전문화된 기능으로 Claude를 확장합니다. Skills는 지침, 설명 및 선택적 지원 리소스를 포함하는 `SKILL.md` 파일로 패키징됩니다. 이 페이지는 또한 [Agent SDK 세션의 명령](#commands-in-agent-sdk-sessions)을 다룹니다.

10 10 

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

12 12 

13<h2 id="how-skills-work-with-the-agent-sdk">13<h2 id="how-skills-work-with-the-agent-sdk">

14 Agent SDK와 Skills의 작동 방식14 Agent SDK와 Skills의 작동 방식

768 관련 문서768 관련 문서

769</h2>769</h2>

770 770 

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

772* [동적 워크플로우](/docs/ko/workflows): 한 대화에 너무 큰 작업을 위해 스크립트에서 많은 서브에이전트를 오케스트레이션합니다772* [동적 워크플로우](/docs/ko/workflows): 한 대화에 너무 큰 작업을 위해 스크립트에서 많은 서브에이전트를 오케스트레이션합니다

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

2299 훅 타입2299 훅 타입

2300</h2>2300</h2>

2301 2301 

2302훅 사용에 대한 포괄적인 가이드, 예제 및 일반적인 패턴은 [훅 가이드](/docs/ko/agent-sdk/hooks)를 참조하세요.2302예제 및 일반적인 패턴을 포함한 훅 사용 가이드는 [훅 가이드](/docs/ko/agent-sdk/hooks)를 참조하세요.

2303 2303 

2304<h3 id="hookevent">2304<h3 id="hookevent">

2305 `HookEvent`2305 `HookEvent`

5879};5879};

5880```5880```

5881 5881 

5882<h3 id="sdksessionstatechangedmessage">

5883 `SDKSessionStateChangedMessage`

5884</h3>

5885 

5886Claude Code가 세션의 상태를 보고할 때 내보내집니다. 이러한 메시지를 받으려면 [`CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1`](/docs/ko/env-vars#variables)을 설정하세요. Claude Code는 동일한 상태를 두 번 이상 보고할 수 있으므로, 메시지를 전환이 아니라 세션의 현재 상태로 해석하세요.

5887 

5888`state` 필드는 다음 값 중 하나를 전달합니다:

5889 

5890* `running`: 세션이 작업 중입니다.

5891* `idle`: Claude Code가 다음 프롬프트를 기다리고 있습니다.

5892* `requires_action`: 세션이 호스트에 보낸 요청(예: 권한 프롬프트)에 대한 응답을 기다리며 차단되어 있습니다.

5893 

5894턴의 `idle` 메시지와 `result` 메시지는 어느 순서로든 도착할 수 있습니다. 백그라운드 서브에이전트나 [워크플로](/docs/ko/workflows) 실행 같은 백그라운드 작업을 `idle`이 기다릴지 여부를 변경하려면 [`CLAUDE_CODE_BG_TASKS_REPORT_RUNNING`](/docs/ko/env-vars#variables)을 참조하세요.

5895 

5896```typescript theme={null}

5897type SDKSessionStateChangedMessage = {

5898 type: "system";

5899 subtype: "session_state_changed";

5900 state: "idle" | "running" | "requires_action";

5901 uuid: UUID;

5902 session_id: string;

5903};

5904```

5905 

5882<h3 id="sdkfilespersistedevent">5906<h3 id="sdkfilespersistedevent">

5883 `SDKFilesPersistedEvent`5907 `SDKFilesPersistedEvent`

5884</h3>5908</h3>

102 102 

103이름은 해당 세션에서 [`/color`](/docs/ko/commands)로 설정된 색상으로 표시됩니다. `←` 또는 `/background`로 [세션을 백그라운드로 보낼](#from-inside-a-session) 때를 포함합니다.103이름은 해당 세션에서 [`/color`](/docs/ko/commands)로 설정된 색상으로 표시됩니다. `←` 또는 `/background`로 [세션을 백그라운드로 보낼](#from-inside-a-session) 때를 포함합니다.

104 104 

105기본적으로 목록은 모든 프로젝트에 걸쳐 시작한 모든 백그라운드 세션을 표시합니다. 한 저장소에서 작업하는 세션과 다른 worktree에서 작업하는 세션은 모두 여기에 나타나며, 에이전트 뷰를 연 디렉토리와 관계없이 표시됩니다. 목록을 한 프로젝트로 범위를 지정하려면 `--cwd`를 전달합니다:105기본적으로 목록은 모든 프로젝트에 걸쳐 시작한 모든 백그라운드 세션을 표시합니다. 한 저장소에서 작업하는 세션과 다른 worktree에서 작업하는 세션은 모두 여기에 나타나며, 에이전트 뷰를 연 디렉토리와 관계없이 표시됩니다. 목록을 한 프로젝트로 좁히려면 `--cwd`를 전달합니다:

106 106 

107```bash theme={null}107```bash theme={null}

108claude agents --cwd ~/projects/my-app108claude agents --cwd ~/projects/my-app

110 110 

111이는 해당 디렉토리 아래에서 시작된 세션만 표시합니다. `~/projects/my-app/.claude/worktrees/` 아래의 [worktree로 이동한](#how-file-edits-are-isolated) 세션은 여전히 나열됩니다.111이는 해당 디렉토리 아래에서 시작된 세션만 표시합니다. `~/projects/my-app/.claude/worktrees/` 아래의 [worktree로 이동한](#how-file-edits-are-isolated) 세션은 여전히 나열됩니다.

112 112 

113다른 터미널에서 열려 있는 대화형 세션은 [백그라운드로 보낼](#from-inside-a-session) 때까지 나타나지 않습니다. [서브에이전트](/docs/ko/sub-agents)와 [팀원](/docs/ko/agent-teams)은 세션이 생성하는 별도의 행으로 나열되지 않습니다.113다른 터미널에서 열려 있는 대화형 세션은 [백그라운드로 보낼](#from-inside-a-session) 때까지 나타나지 않습니다. 세션이 생성하는 [서브에이전트](/docs/ko/sub-agents)와 [팀원](/docs/ko/agent-teams)은 별도의 행으로 나열되지 않습니다.

114 114 

115```text theme={null}115```text theme={null}

116고정됨116Pinned

117 ✽ clawd walk cycle 걷기 사이클 스프라이트 프레임 그리기 3m117 ✽ clawd walk cycle Drawing the walk-cycle sprite frames 3m

118 118 

119검토 준비 완료119Ready for review

120 ∙ jump physics 충돌 수정으로 PR 열기 #2048 2h120 ∙ jump physics Opened PR with collision fix #2048 2h

121 121 

122입력 필요122Needs input

123 ✻ power-up design 이중 점프 또는 벽 타기? 1m123 ✻ power-up design double jump or wall climb? 1m

124 124 

125작업 중125Working

126 ✽ collision detection CollisionSystem에 swept-AABB 검사 추가 2m126 ✽ collision detection Adding swept-AABB checks to CollisionSystem 2m

127 ✢ playtest level 3 실행 12 · 모든 체크포인트 통과 4m 후127 ✢ playtest level 3 all checkpoints cleared ×12 in 4m

128 128 

129완료됨129Completed

130 ✻ title screen 결과: 메뉴, 옵션 및 크레딧 완료 9m130 ✻ title screen menu, options, and credits done 9m

131 ∙ sound effects 결과: 14개 SFX를 assets/audio로 내보냄 4h131 ∙ sound effects 14 SFX exported to assets/audio 4h

132 … 6 more132 … 6 more

133```133```

134 134 

141| 상태 | 아이콘 표시 | 의미 |141| 상태 | 아이콘 표시 | 의미 |

142| :- | :- | :- |142| :- | :- | :- |

143| 작업 중 | 애니메이션 | Claude가 적극적으로 도구를 실행하거나 응답을 생성 중 |143| 작업 중 | 애니메이션 | Claude가 적극적으로 도구를 실행하거나 응답을 생성 중 |

144| 입력 필요 | 노란색 | Claude가 특정 질문이나 권한 결정을 기다리는 중입니다. 또는 [샌드박스](/docs/ko/sandboxing) 프롬프트로 네트워크 호스트를 허용하거나 MCP 서버의 [입력 요청](/docs/ko/mcp#respond-to-mcp-elicitation-requests)에 응답하는 것과 같이 사용자만 답변할 수 있는 다른 프롬프트입니다. 연결된 터미널이 필요한 명령(예: `/install-github-app` 또는 `/mcp` 설정 목록)은 [여기에 미처리 세션을 보유](#attach-to-a-session)합니다 |144| 입력 필요 | 노란색 | Claude가 사용자만 제공할 수 있는 것을 기다리는 중입니다: 질문에 대한 답변, 권한 결정, 또는 네트워크 호스트를 허용하는 [샌드박스](/docs/ko/sandboxing) 프롬프트나 MCP 서버의 [입력 요청](/docs/ko/mcp#respond-to-mcp-elicitation-requests)과 같이 사용자만 답변할 수 있는 다른 프롬프트입니다. 연결된 터미널이 필요한 명령(예: `/install-github-app` 또는 `/mcp` 설정 목록)도 [무인 세션을 이 상태로 둡니다](#attach-to-a-session) |

145| 유휴 | 흐릿함 | 세션이 할 일이 없으며 다음 프롬프트를 기다리는 중 |145| 유휴 | 흐릿함 | 세션이 할 일이 없으며 다음 프롬프트를 기다리는 중 |

146| 완료됨 | 녹색 | 작업이 성공적으로 완료됨 |146| 완료됨 | 녹색 | 작업이 성공적으로 완료됨 |

147| 실패 | 빨간색 | 작업이 오류로 종료됨 |147| 실패 | 빨간색 | 작업이 오류로 종료됨 |

148| 중지됨 | 회색 | `Ctrl+X` 또는 `claude stop`으로 세션을 중지했거나, [프로세스가 Claude Code 외부에서 종료되었거나](#the-supervisor-process), [백그라운드 서비스가 꺼져 있는 동안 종료됨](#sessions-show-as-failed-after-shutdown) |148| 중지됨 | 회색 | `Ctrl+X` 또는 `claude stop`으로 세션을 중지했거나, [프로세스가 Claude Code 외부에서 종료되었거나](#the-supervisor-process), [백그라운드 서비스가 꺼져 있는 동안 종료됨](#sessions-show-as-failed-after-shutdown) |

149 149 

150별도로, 아이콘의 모양은 기본 프로세스가 실행 중인지 여부를 나타냅니다:150별도로, 아이콘의 모양은 그 자체의 의미를 가집니다:

151 151 

152| 모양 | 의미 |152| 모양 | 의미 |

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

154| `✻` 또는 애니메이션 `✽` | 세션 프로세스가 활성 상태이며 즉시 응답 |154| `✻` 또는 애니메이션 `✽` | 세션 프로세스가 실행 중이거나, 세션이 사용자의 입력을 필요로 함 |

155| `∙` | 프로세스가 종료됨. 여전히 행을 엿보기, 답변 또는 연결할 수 있으며, Claude는 중단된 위치에서 다시 시작 |155| `∙` | 프로세스가 종료됨. 여전히 행을 엿볼 수 있으며, 답변하거나 연결하면 Claude가 중단된 위치에서 다시 시작 |

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

157 157 

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

161 161 

162스크립트 또는 다른 프로그램에서 세션 상태를 읽으려면 `~/.claude/jobs/` 아래의 파일 대신 [`claude agents --json`](#read-session-state-from-a-script)을 사용합니다.162스크립트 또는 다른 프로그램에서 세션 상태를 읽으려면 `~/.claude/jobs/` 아래의 파일 대신 [`claude agents --json`](#read-session-state-from-a-script)을 사용합니다.

163 163 

164에이전트 뷰가 열려 있는 동안 Claude Code는 로컬 백그라운드 세션이 입력이 필요하거나, 완료되거나, 실패할 때 구성된 [터미널 알림 채널](/docs/ko/terminal-config#get-a-terminal-bell-or-notification)을 통해 알림을 보냅니다. [`/loop`](/docs/ko/scheduled-tasks) 세션과 같이 일정에 따라 실행되는 세션은 입력이 필요할 때만 알립니다. 알림은 Claude Code의 나머지 부분과 동일한 [`preferredNotifChannel` 설정](/docs/ko/settings-reference#preferrednotifchannel)을 사용하며 `agent_needs_input` 또는 `agent_completed` 유형으로 [`Notification` 훅](/docs/ko/hooks#notification)을 실행합니다.164에이전트 뷰가 열려 있는 동안 Claude Code는 로컬 백그라운드 세션이 입력이 필요해지거나, 완료되거나, 실패할 때 구성된 [터미널 알림 채널](/docs/ko/terminal-config#get-a-terminal-bell-or-notification)을 통해 알림을 보냅니다. [`/loop`](/docs/ko/scheduled-tasks) 세션과 같이 일정에 따라 실행되는 세션은 입력이 필요할 때만 알립니다. 알림은 Claude Code의 나머지 부분과 동일한 [`preferredNotifChannel` 설정](/docs/ko/settings-reference#preferrednotifchannel)을 사용하며 `agent_needs_input` 또는 `agent_completed` 유형으로 [`Notification` 훅](/docs/ko/hooks#notification)을 실행합니다.

165 165 

166백그라운드 세션은 계속 작동하기 위해 열린 터미널이 필요하지 않습니다. 별도의 [감독자 프로세스](#the-supervisor-process)가 실행하므로 에이전트 뷰를 닫거나, 셸을 닫거나, 새로운 대화형 세션을 시작해도 디스패치된 작업은 계속됩니다.166백그라운드 세션은 계속 작동하기 위해 열린 터미널이 필요하지 않습니다. 별도의 [감독자 프로세스](#the-supervisor-process)가 실행하므로 에이전트 뷰를 닫거나, 셸을 닫거나, 새로운 대화형 세션을 시작해도 디스패치된 작업은 계속됩니다.

167 167 

173 행 요약173 행 요약

174</h3>174</h3>

175 175 

176각 행의 한 줄 요약은 [Haiku 클래스 모델](/docs/ko/model-config)에 의해 생성되므로 행은 세션이 무엇을 하고 있는지, 무엇이 필요한지, 또는 트랜스크립트를 열지 않고도 무엇을 생성했는지 알려줄 수 있습니다. 세션이 적극적으로 작동하는 동안 행 텍스트는 최대 15초마다 한 번, 세션의 최근 출력에서 모델 요청을 보내지 않고 업데이트되며, 각 턴이 끝날 때 모델이 새로운 요약을 작성합니다.176각 행의 한 줄 요약은 [Haiku 클래스 모델](/docs/ko/model-config)에 의해 생성되므로 행은 트랜스크립트를 열지 않고도 세션이 무엇을 하고 있는지, 무엇이 필요한지, 또는 무엇을 생성했는지 알려줄 수 있습니다. 세션이 적극적으로 작동하는 동안 행 텍스트는 최대 15초마다 한 번, 세션의 최근 출력에서 모델 요청을 보내지 않고 업데이트되며, 각 턴이 끝날 때 모델이 새로운 요약을 작성합니다.

177 177 

178작업 중인 행은 세션이 수행 중인 작업을 표시하고, 차단된 행은 요청하는 질문을 표시합니다. 긴 턴 동안 모델은 몇 분마다 요약을 다시 작성하므로 바쁜 행이 오래된 요약을 계속 표시하지 않습니다. 요약 텍스트는 행의 남은 너비를 채우고 터미널의 오른쪽 가장자리에서만 잘립니다. [엿보기 패널](#peek-and-reply)을 열어 가장자리가 자르는 문장을 읽습니다.178작업 중인 행은 세션이 수행 중이라고 말하는 작업을 표시하고, 차단된 행은 요청하는 질문을 표시합니다. 긴 턴 동안 모델은 몇 분마다 요약을 다시 작성하므로 바쁜 행이 오래된 요약을 계속 표시하지 않습니다. 요약 텍스트는 행의 남은 너비를 채웁니다. 터미널 가장자리에서 잘리는 문장을 읽으려면 [엿보기 패널](#peek-and-reply)을 엽니다.

179 179 

180목록이 [디렉토리별로 그룹화](#organize-the-list)될 때 요약은 `입력 필요 · 이중 점프 또는 벽 타기?`와 같은 색상이 지정된 단어로 세션의 상태로 시작합니다. 기본 상태 그룹화에서 그룹 헤더가 이미 상태를 명명하므로 행은 요약만 표시합니다.180목록이 [디렉토리별로 그룹화](#organize-the-list)될 때 요약은 `Needs input · double jump or wall climb?`와 같이 색상이 지정된 단어로 된 세션의 상태로 시작합니다. 기본 상태 그룹화에서는 그룹 헤더가 이미 상태를 명명하므로 행은 요약만 표시합니다.

181 181 

182턴 끝 요약 및 각 중간 다시 작성은 일반 제공자를 통한 하나의 짧은 Haiku 클래스 요청이며, 세션 자체와 동일한 [데이터 사용 약관](/docs/ko/data-usage)에 따라 청구되고 처리됩니다. 모델 다시 작성 사이의 15초 업데이트는 세션의 자체 출력을 재사용하며 요청을 보내지 않습니다. Haiku 클래스 모델이 구성되지 않은 타사 제공자 또는 게이트웨이에서는 요청이 세션의 주 모델로 폴백됩니다. [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/docs/ko/model-config#environment-variables)을 설정하여 선택합니다.182턴 끝 요약 및 각 중간 다시 작성은 일반 제공자를 통한 하나의 짧은 Haiku 클래스 요청이며, 세션 자체와 동일한 [데이터 사용 약관](/docs/ko/data-usage)에 따라 청구되고 처리됩니다. 모델 다시 작성 사이의 15초 업데이트는 세션의 자체 출력을 재사용하며 요청을 보내지 않습니다. Haiku 클래스 모델이 구성되지 않은 타사 제공자 또는 게이트웨이에서는 요청이 대신 세션의 주 모델을 사용합니다. 모델을 선택하려면 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/docs/ko/model-config#environment-variables)을 설정합니다.

183 183 

184<h3 id="pull-request-status">184<h3 id="pull-request-status">

185 풀 리퀘스트 상태185 풀 리퀘스트 상태

189 189 

190* Claude Code는 풀 리퀘스트의 경우 `#1234`로, GitLab 병합 요청의 경우 `!1234`로 레이블을 작성합니다.190* Claude Code는 풀 리퀘스트의 경우 `#1234`로, GitLab 병합 요청의 경우 `!1234`로 레이블을 작성합니다.

191* Claude Code는 SSH 또는 tmux를 통한 경우와 같이 하이퍼링크 지원을 감지할 수 없을 때도 링크를 내보냅니다. [`FORCE_HYPERLINK=0`](/docs/ko/env-vars)을 설정하여 레이블을 일반 텍스트로 렌더링합니다.191* Claude Code는 SSH 또는 tmux를 통한 경우와 같이 하이퍼링크 지원을 감지할 수 없을 때도 링크를 내보냅니다. [`FORCE_HYPERLINK=0`](/docs/ko/env-vars)을 설정하여 레이블을 일반 텍스트로 렌더링합니다.

192* 세션에 후속 조치를 보낸 후 Claude Code는 행이 라이브 진행 상황으로 돌아가는 동안 레이블을 유지합니다.192* 세션에 후속 메시지를 보낸 후 Claude Code는 행이 라이브 진행 상황으로 돌아가는 동안 레이블을 유지합니다.

193 193 

194기존 풀 리퀘스트에서 작업하는 세션은 동일한 방식으로 연결됩니다. Claude Code는 Claude가 실행하는 명령에 따라 풀 리퀘스트를 다르게 찾습니다:194기존 풀 리퀘스트에서 작업하는 세션은 동일한 방식으로 연결됩니다. Claude Code는 Claude가 실행하는 명령에 따라 풀 리퀘스트를 다르게 찾습니다:

195 195 

220* 완료된 세션: 결과220* 완료된 세션: 결과

221* 작업 중인 세션: 전체 상태 문장221* 작업 중인 세션: 전체 상태 문장

222 222 

223세션에 연결된 모든 풀 리퀘스트가 다음에 나열됩니다. 입력을 기다리는 세션의 경우 `waiting 3m`과 같은 줄이 기다린 시간을 표시하며, 패널에 표시되는 유일한 시간입니다. 행의 오른쪽 가장자리의 나이는 다른 숫자입니다: 세션이 시작된 시점부터 계산됩니다.223세션에 연결된 모든 풀 리퀘스트가 다음에 나열됩니다. 입력을 기다리는 세션의 경우 그 아래에 `waiting 3m`과 같은 줄이 기다린 시간을 표시하며, 패널에 표시되는 유일한 시간입니다. 행의 오른쪽 가장자리의 나이는 다른 숫자입니다: 세션이 시작된 시점부터 계산됩니다.

224 224 

225대부분의 경우 엿보기 패널로 충분하며 전체 트랜스크립트를 열 필요가 없습니다.225대부분의 경우 엿보기 패널로 충분하며 전체 트랜스크립트를 열 필요가 없습니다.

226 226 

238 238 

239[`PermissionRequest`](/docs/ko/hooks#permissionrequest) 또는 [`PreToolUse`](/docs/ko/hooks#pretooluse) 훅이 Claude Code가 세션이 요청하는 호출에 대해 검증할 수 없는 출력을 반환하면 행은 훅 이벤트와 `hook output invalid:`를 보류 중인 요청의 텍스트 앞에 검증 오류와 함께 표시합니다. 다른 방식으로 실패하는 훅의 경우 행은 훅이 실패했다고 표시합니다. 세션은 여전히 동일한 요청을 기다립니다.239[`PermissionRequest`](/docs/ko/hooks#permissionrequest) 또는 [`PreToolUse`](/docs/ko/hooks#pretooluse) 훅이 Claude Code가 세션이 요청하는 호출에 대해 검증할 수 없는 출력을 반환하면 행은 훅 이벤트와 `hook output invalid:`를 보류 중인 요청의 텍스트 앞에 검증 오류와 함께 표시합니다. 다른 방식으로 실패하는 훅의 경우 행은 훅이 실패했다고 표시합니다. 세션은 여전히 동일한 요청을 기다립니다.

240 240 

241전달할 수 없는 답변(백그라운드 서비스에 연결할 수 없거나 전송이 실패하는 경우)은 저장되고 프로세스가 다시 시작될 때 다음 프롬프트로 세션에 전송되며, 오류 메시지는 답변이 저장되었음을 나타냅니다. `!`로 접두사가 붙은 답변은 저장되지 않습니다. 저장된 텍스트가 일반 프롬프트로 세션에 도달하기 때문입니다.241전달할 수 없는 답변(백그라운드 서비스에 연결할 수 없거나 전송이 실패하는 경우)은 저장되고 프로세스가 다시 시작될 때 다음 프롬프트로 세션에 전송되며, 오류 메시지는 답변이 저장되었음을 나타냅니다. `!`로 접두사가 붙은 답변은 저장되지 않습니다. 저장된 텍스트가 Bash 명령으로 실행되지 않고 일반 프롬프트로 세션에 도달하기 때문입니다.

242 242 

243[음성 받아쓰기](/docs/ko/voice-dictation)가 활성화된 경우, 답변 입력에 포커스가 있는 동안 푸시-투-톡 키를 누르거나 탭하여 입력하는 대신 답변을 받아쓸 수 있습니다. 에이전트 뷰 하단의 디스패치 입력에서도 동일하게 작동합니다.243[음성 받아쓰기](/docs/ko/voice-dictation)가 [누르고 있기 모드](/docs/ko/voice-dictation#hold-to-record)로 활성화된 경우, 답변 입력에 포커스가 있는 동안 푸시-투-톡 키를 누르고 있으면 입력하는 대신 답변을 받아쓸 수 있습니다. 에이전트 뷰 하단의 디스패치 입력에서도 동일하게 작동합니다.

244 244 

245`↑` 및 `↓`를 사용하여 패널을 닫지 않고 인접한 세션을 엿보거나 `→`를 눌러 연결합니다.245`↑` 및 `↓`를 사용하여 패널을 닫지 않고 인접한 세션을 엿보거나 `→`를 눌러 연결합니다.

246 246 

252 252 

253연결된 동안 세션은 다른 Claude Code 세션처럼 작동합니다: [명령](/docs/ko/commands), 키보드 단축키 및 기능 모두 작동하며, 아래의 예외가 있습니다.253연결된 동안 세션은 다른 Claude Code 세션처럼 작동합니다: [명령](/docs/ko/commands), 키보드 단축키 및 기능 모두 작동하며, 아래의 예외가 있습니다.

254 254 

255연결된 동안 `/install-github-app`과 [`/mcp`](/docs/ko/mcp) 설정 목록은 정상적으로 작동하며, 인간이 터미널에서 대화를 완료할 수 있습니다. 아무도 연결되지 않으면 이 명령은 대화를 열 수 없으므로 세션은 에이전트 뷰의 `입력 필요` 아래에 나타나며 `open this session to manage MCP servers`와 같은 행이 표시되고, 트랜스크립트 답변도 동일하게 표시됩니다. 연결하고 명령을 다시 실행하여 계속합니다. 입력 필요 행은 연결할 때 지워집니다. `/mcp reconnect <server>`, `/mcp enable` 및 `/mcp disable`은 연결 여부와 관계없이 작동합니다.255연결된 동안 `/install-github-app`과 [`/mcp`](/docs/ko/mcp) 설정 목록은 정상적으로 작동합니다. 터미널 앞의 사람이 대화 상자를 완료할 수 있기 때문입니다. 아무도 연결되지 않으면 이 명령은 대화 상자를 열 수 없으므로 세션은 에이전트 뷰의 `Needs input` 아래에 `open this session to manage MCP servers`와 같은 행으로 나타나며, 트랜스크립트 답변도 동일하게 표시됩니다. 연결하고 명령을 다시 실행하여 계속합니다. 입력 필요 행은 연결할 때 지워집니다. `/mcp reconnect <server>`, `/mcp enable` 및 `/mcp disable`은 연결 여부와 관계없이 작동합니다.

256 256 

257연결된 세션은 `tui` 설정과 관계없이 항상 [전체 화면 모드](/docs/ko/fullscreen)로 렌더링됩니다. 백그라운드 세션에는 추가할 터미널 스크롤백이 없기 때문입니다. `PgUp`, `PgDn` 또는 마우스 휠로 스크롤하고, `Ctrl+O`를 눌러 트랜스크립트 모드로 전환합니다. 터미널의 기본 스크롤 및 tmux 복사 모드는 현재 뷰포트만 표시하며, 이는 전체 화면 애플리케이션을 실행할 때와 동일합니다.257연결된 세션은 `tui` 설정과 관계없이 항상 [전체 화면 모드](/docs/ko/fullscreen)로 렌더링됩니다. 백그라운드 세션에는 추가할 터미널 스크롤백이 없기 때문입니다. `PgUp`, `PgDn` 또는 마우스 휠로 스크롤하고, `Ctrl+O`를 눌러 트랜스크립트 모드로 전환합니다. 터미널의 기본 스크롤 및 tmux 복사 모드는 현재 뷰포트만 표시하며, 이는 전체 화면 애플리케이션을 실행할 때와 동일합니다.

258 258 

259빈 프롬프트에서 `←`를 누르거나 `/exit`를 실행하여 분리하고 에이전트 뷰로 돌아갑니다. 에이전트 뷰에서 세션을 열었는지 또는 셸에서 `claude attach <id>`로 실행했는지 여부와 관계없이 동일하게 작동합니다.259빈 프롬프트에서 `←`를 누르거나 `/exit`를 실행하여 분리하고 에이전트 뷰로 돌아갑니다. 에이전트 뷰에서 세션을 열었는지 또는 셸에서 `claude attach <id>`로 실행했는지 여부와 관계없이 동일하게 작동합니다.

260 260 

261`←`는 [`/btw` 오버레이](/docs/ko/interactive-mode#side-questions-with-%2Fbtw)가 열려 있을 때도 분리됩니다. Claude Code v2.1.257 이상이 필요합니다. 여전히 답변 중인 부가 질문은 떠나 있는 동안 계속 실행됩니다. 다음에 연결할 때 오버레이는 이를 다시 열거나 답변과 함께 다시 열립니다.261`←`는 [`/btw` 오버레이](/docs/ko/interactive-mode#side-questions-with-%2Fbtw)가 열려 있을 때도 분리됩니다. Claude Code v2.1.257 이상이 필요합니다. 여전히 답변 중인 부가 질문은 떠나 있는 동안 계속 실행됩니다. 다음에 연결할 때 오버레이는 해당 질문 또는 그 답변과 함께 다시 열립니다.

262 262 

263Windows에서 연결 후 약 0.5초 이내에 `←`를 누르면 Claude Code는 `Ambiguous ←, press again to detach`를 표시합니다. 이 기간 동안 터미널이 연결 전의 누름을 다시 전달할 수 있기 때문입니다. 분리하려면 `←`를 다시 누릅니다.263Windows에서 연결 후 약 0.5초 이내에 `←`를 누르면 Claude Code는 `Ambiguous ←, press again to detach`를 표시합니다. 이 기간 동안 터미널이 연결 전의 누름을 다시 전달할 수 있기 때문입니다. 분리하려면 `←`를 다시 누릅니다.

264 264 

282* `Esc`를 눌러 전환을 취소하고 대화로 돌아갑니다. `Esc`가 `Still starting — try again in a moment`를 표시하면 백그라운드 세션이 아직 준비되지 않았으므로 잠시 후 `Esc`를 다시 누릅니다.282* `Esc`를 눌러 전환을 취소하고 대화로 돌아갑니다. `Esc`가 `Still starting — try again in a moment`를 표시하면 백그라운드 세션이 아직 준비되지 않았으므로 잠시 후 `Esc`를 다시 누릅니다.

283* `Ctrl+C`를 두 번 눌러 셸로 종료합니다.283* `Ctrl+C`를 두 번 눌러 셸로 종료합니다.

284 284 

285Claude Code가 대화를 다시 열 수 없으면 종료하고 `claude --resume` 명령을 인쇄하여 이를 재개합니다.285Claude Code가 대화를 다시 열 수 없으면 종료하고 대화를 재개하는 `claude --resume` 명령을 인쇄합니다.

286 286 

287[Claude의 작업 목록](/docs/ko/interactive-mode#task-list)은 대화와 함께 백그라운드 세션으로 이동하므로 해당 행으로 돌아갈 때 체크리스트가 그대로 유지됩니다.287[Claude의 작업 목록](/docs/ko/interactive-mode#task-list)은 대화와 함께 백그라운드 세션으로 이동하므로 해당 행으로 돌아갈 때 체크리스트가 그대로 유지됩니다.

288 288 

289`←`를 누른 행은 화살표 키 또는 마우스로 선택을 이동한 후에도 굵고 흐릿하지 않은 이름을 유지하므로 어느 세션에서 왔는지 알 수 있습니다.289`←`를 누른 행은 화살표 키 또는 마우스로 선택을 이동한 후에도 굵고 흐릿하지 않은 이름을 유지하므로 어느 세션에서 왔는지 알 수 있습니다.

290 290 

291도구가 실행 중일 때 `←`를 누르면 Claude Code는 완료될 때까지 약 10초를 기다린 후 백그라운드로 보내며, 응답은 백그라운드 세션에서 계속됩니다. 대신 즉시 백그라운드로 보내려면 `←`를 다시 누릅니다. 진행 중인 작업을 백그라운드 세션으로 이월할 수 없으면 Claude Code는 `Background this session?` 대화가 먼저 나타나며, [`/background`](#from-inside-a-session)와 동일합니다.291도구가 실행 중일 때 `←`를 누르면 Claude Code는 완료될 때까지 최대 약 10초를 기다린 후 백그라운드로 보내며, Claude는 백그라운드 세션에서 응답을 계속합니다. 대신 기다리지 않고 즉시 백그라운드로 보내려면 `←`를 다시 누릅니다. 진행 중인 작업을 백그라운드 세션으로 이월할 수 없으면 Claude Code는 [`/background`](#from-inside-a-session)와 마찬가지로 `Background this session?` 대화 상자를 먼저 표시합니다.

292 292 

29310초 제한은 [포그라운드 서브에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background) Claude가 대화에서 시작한 것이 여전히 실행 중일 때 적용되지 않습니다. Claude Code는 계속 기다려서 작업이 이월되고, 기다리는 동안 `Still backgrounding after the current tool` 알림을 표시합니다. `←`를 다시 눌러 대기 없이 백그라운드로 보내면 서브에이전트가 처음부터 다시 시작됩니다. Claude Code는 [동적 워크플로우](/docs/ko/workflows)가 실행 중인 서브에이전트를 기다리지 않습니다. 워크플로우에 서브에이전트가 실행 중이면 Claude Code는 `Background this session?` 대화를 대신 표시합니다.293Claude가 대화에서 시작한 [포그라운드 서브에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)가 여전히 실행 중인 동안에는 10초 제한이 적용되지 않습니다. Claude Code는 작업이 이월되도록 계속 기다리며, 기다리는 동안 `Still backgrounding after the current tool` 알림을 표시합니다. `←`를 다시 눌러 대기 없이 백그라운드로 보내면 해당 서브에이전트가 처음부터 다시 시작됩니다. Claude Code는 [동적 워크플로](/docs/ko/workflows)가 실행 중인 서브에이전트를 기다리지 않습니다. 워크플로에 서브에이전트가 실행 중이면 Claude Code는 대신 `Background this session?` 대화 상자를 표시합니다.

294 294 

295Claude Code는 프롬프트 입력에 미전송 텍스트가 있는 동안 세션을 백그라운드로 보내지 않습니다. 텍스트가 터미널의 입력 상자에 남아 있고 백그라운드 세션으로 이동하지 않기 때문입니다. Claude Code가 세션을 백그라운드로 보내기를 기다리는 동안 입력에 입력하면 `Backgrounding cancelled — you have unsent text in the input. Send it or clear it, then press ← again.`으로 전환을 취소합니다.295Claude Code는 프롬프트 입력에 미전송 텍스트가 있는 동안 세션을 백그라운드로 보내지 않습니다. 텍스트가 터미널의 입력 상자에 남아 있고 백그라운드 세션으로 이동하지 않기 때문입니다. Claude Code가 세션을 백그라운드로 보내기를 기다리는 동안 입력에 텍스트를 입력하면 `Backgrounding cancelled — you have unsent text in the input. Send it or clear it, then press ← again.`으로 전환을 취소합니다.

296 296 

297`←`를 누르면 대화에 메시지가 없을 때도 세션의 행이 생성되므로 `→`는 여전히 이를 반환합니다.297`←`를 누르면 대화에 메시지가 아직 없을 때도 세션의 행이 생성되므로 `→`로 여전히 해당 세션으로 돌아갈 수 있습니다.

298 298 

299`/config`에서 [`leftArrowOpensAgents`](/docs/ko/settings-reference#leftarrowopensagents) 설정으로 이 단축키를 끌 수 있습니다.299`/config`에서 [`leftArrowOpensAgents`](/docs/ko/settings-reference#leftarrowopensagents) 설정으로 포그라운드 세션의 이 단축키를 끌 수 있습니다.

300 300 

301<h3 id="organize-the-list">301<h3 id="organize-the-list">

302 목록 구성302 목록 구성

303</h3>303</h3>

304 304 

305에이전트 뷰는 세션을 그룹화하여 입력이 필요한 세션이 맨 위에 있고, `검토 준비 완료`와 `입력 필요`가 `작업 중`과 `완료됨` 위에 있습니다. 이 그룹 이름은 [상태](#read-session-state) 위의 일대일 매핑이 아닙니다: 세션이 열린 풀 리퀘스트를 가지면 `검토 준비 완료`로 이동하고, `완료됨`은 완료되고, 실패하고, 중지된 세션을 함께 수집합니다.305에이전트 뷰는 입력이 필요한 세션이 맨 위에 오도록 세션을 그룹화하며, `Ready for review`와 `Needs input`이 `Working`과 `Completed` 위에 있습니다. 이 그룹 이름은 위의 [상태](#read-session-state)와 일대일로 대응하지 않습니다: 세션에 검토가 필요하거나 검사가 실패한 열린 풀 리퀘스트가 있으면 `Ready for review`로 이동하고, `Completed`는 완료된 세션, 실패한 세션, 중지된 세션을 함께 모읍니다.

306 306 

307`Ctrl+S`를 눌러 대신 디렉토리별로 그룹화로 전환합니다. 선택 사항은 실행 간에 저장됩니다.307`Ctrl+S`를 눌러 대신 디렉토리별로 그룹화합니다. 선택 사항은 실행 간에 유지됩니다.

308 308 

309그룹 내에서:309그룹 내에서:

310 310 

315 315 

316세션을 목록에서 제거하려면 `Ctrl+X`를 눌러 중지하고 2초 이내에 `Ctrl+X`를 다시 눌러 삭제합니다. 그룹 헤더에서 `Ctrl+X`를 누르면 확인 후 해당 그룹의 모든 세션이 삭제됩니다.316세션을 목록에서 제거하려면 `Ctrl+X`를 눌러 중지하고 2초 이내에 `Ctrl+X`를 다시 눌러 삭제합니다. 그룹 헤더에서 `Ctrl+X`를 누르면 확인 후 해당 그룹의 모든 세션이 삭제됩니다.

317 317 

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

319 319 

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

321 321 

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

323 323 

324피커는 베어 `/resume`에만 열립니다. 대상, 범위 또는 제한된 재개는 피커로 제공될 수 없으므로 에이전트 뷰는 다음과 같은 경우 `attach to a session to run it` 힌트를 표시합니다:324피커는 인수 없는 `/resume`에만 열립니다. 대상이 지정되거나, 범위가 지정되거나, 제한된 재개는 피커로 처리할 수 없으므로 에이전트 뷰는 다음과 같은 경우 대신 `attach to a session to run it` 힌트를 표시합니다:

325 325 

326* `/resume`이 id 또는 검색 용어를 명명합니다326* `/resume`이 id 또는 검색어를 지정하는 경우

327* 뷰가 `--cwd`로 범위가 지정됩니다327* 뷰가 `--cwd`로 범위가 지정된 경우

328* 뷰가 [`--safe-mode`](/docs/ko/cli-reference#cli-flags)로 시작되었습니다328* 뷰가 [`--safe-mode`](/docs/ko/cli-reference#cli-flags)로 시작된 경우

329* 뷰가 `--permission-mode` 또는 `--settings`와 같은 플래그로 열렸습니다329* 뷰가 `--permission-mode` 또는 `--settings`와 같은 플래그로 열린 경우

330 330 

331화면에 맞지 않는 완료된 세션은 `… N more` 행으로 접힙니다. 실패 및 열린 풀 리퀘스트가 있는 세션은 항상 표시됩니다. `완료됨` 그룹은 라이브 그룹 이후 남은 수직 공간을 채우며, 짧은 터미널에서 헤더는 단일 요약 라인으로 압축되므로 작업 중이거나 입력이 필요한 세션이 표시된 상태로 유지됩니다.331화면에 맞지 않는 완료된 세션은 `… N more` 행으로 접힙니다. `Completed` 그룹은 라이브 그룹 이후 남은 수직 공간을 채우며, 짧은 터미널에서는 헤더가 단일 요약 줄로 압축되므로 작업 중이거나 입력이 필요한 세션이 계속 표시됩니다.

332 332 

333<h3 id="filter-sessions">333<h3 id="filter-sessions">

334 세션 필터링334 세션 필터링

353 키보드 단축키353 키보드 단축키

354</h3>354</h3>

355 355 

356에이전트 뷰에서 `?`를 눌러 모든 단축키를 확인합니다. 아래 표는 이를 요약합니다.356에이전트 뷰에서 `?`를 눌러 단축키를 상황에 맞게 확인합니다. 아래 표는 이를 요약합니다.

357 357 

358| 단축키 | 작업 |358| 단축키 | 작업 |

359| :- | :- |359| :- | :- |

366| `Ctrl+Enter` | 디스패치하고 즉시 연결, `?` 오버레이가 `ctrl+enter to start and open`을 나열하는 터미널에서 |366| `Ctrl+Enter` | 디스패치하고 즉시 연결, `?` 오버레이가 `ctrl+enter to start and open`을 나열하는 터미널에서 |

367| `→` | 선택된 세션에 연결 |367| `→` | 선택된 세션에 연결 |

368| `Alt+1`..`Alt+9` | 포커스된 세션의 디렉토리에서 세션 1–9에 연결 |368| `Alt+1`..`Alt+9` | 포커스된 세션의 디렉토리에서 세션 1–9에 연결 |

369| `Tab` | 빈 입력에서 모든 서브에이전트 검색. 그 외에는 강조된 제안 적용 |369| `Tab` | 빈 입력에서 모든 서브에이전트 탐색. 그 외에는 강조된 제안 적용 |

370| `Ctrl+S` | 상태와 디렉토리 간 그룹화 전환 |370| `Ctrl+S` | 상태와 디렉토리 간 그룹화 전환 |

371| `Ctrl+T` | 선택된 세션 고정 또는 고정 해제 |371| `Ctrl+T` | 선택된 세션 고정 또는 고정 해제 |

372| `Ctrl+F` | [`n:` 필터](#filter-sessions)로 이름으로 세션 찾기 |372| `Ctrl+F` | [`n:` 필터](#filter-sessions)로 이름으로 세션 찾기 |

376| `Ctrl+J` | 디스패치 입력에 줄 바꿈 삽입 |376| `Ctrl+J` | 디스패치 입력에 줄 바꿈 삽입 |

377| `Ctrl+X` | 세션 중지; 2초 이내에 다시 눌러 삭제 |377| `Ctrl+X` | 세션 중지; 2초 이내에 다시 눌러 삭제 |

378| `Shift+↑` / `Shift+↓` | 선택된 세션 순서 변경 |378| `Shift+↑` / `Shift+↓` | 선택된 세션 순서 변경 |

379| `Esc` | 엿보기 패널 닫기, 입력 지우기 또는 종료. `←`로 세션을 백그라운드로 보내 에이전트 뷰를 연 경우 최종 `Esc`는 종료 대신 해당 대화로 돌아갑니다. [vim 편집기 모드](/docs/ko/interactive-mode#vim-editor-mode)가 켜져 있으면 입력에서 `Esc`를 누르면 INSERT에서 NORMAL 모드로 전환되고 메인 프롬프트처럼 텍스트를 유지합니다 |379| `Esc` | 엿보기 패널 닫기, 입력 지우기 또는 종료. `←`로 세션을 백그라운드로 보내 에이전트 뷰를 연 경우 최종 `Esc`는 종료 대신 해당 대화로 돌아갑니다. [vim 편집기 모드](/docs/ko/interactive-mode#vim-editor-mode)가 켜져 있으면 입력에서 `Esc`를 누르면 메인 프롬프트처럼 INSERT에서 NORMAL 모드로 전환되고 텍스트가 유지됩니다 |

380| `Ctrl+C` | 입력 지우기; 두 번 눌러 종료 |380| `Ctrl+C` | 입력 지우기; 두 번 눌러 종료 |

381| `?` | 모든 단축키 표시 |381| `?` | 단축키 표시 |

382 382 

383[`Agents` 컨텍스트](/docs/ko/keybindings#agents-actions)에 작업이 있는 단축키는 [`keybindings.json`](/docs/ko/keybindings)을 따릅니다. `Ctrl+G`도 `Chat` 컨텍스트의 `chat:externalEditor` 바인딩을 통해 마찬가지로 따릅니다.383[`Agents` 컨텍스트](/docs/ko/keybindings#agents-actions)에 작업이 있는 단축키는 [`keybindings.json`](/docs/ko/keybindings)을 따릅니다. `Ctrl+G`도 `Chat` 컨텍스트의 `chat:externalEditor` 바인딩을 통해 마찬가지로 따릅니다.

384 384 

386 새로운 에이전트 디스패치386 새로운 에이전트 디스패치

387</h2>387</h2>

388 388 

389에이전트 뷰에서 새로운 백그라운드 세션을 디스패치하거나, 기존 대화형 세션을 백그라운드로 보내거나, 셸에서 직접 시작할 수 있습니다.389에이전트 뷰에서 새로운 백그라운드 세션을 디스패치하거나, 기존 대화형 세션을 백그라운드로 보내거나 복사하거나, 셸에서 직접 시작할 수 있습니다.

390 390 

391<h3 id="from-agent-view">391<h3 id="from-agent-view">

392 에이전트 뷰에서392 에이전트 뷰에서

398 398 

399이미지를 프롬프트에 붙여넣어 작업과 함께 스크린샷이나 다이어그램을 포함할 수 있습니다.399이미지를 프롬프트에 붙여넣어 작업과 함께 스크린샷이나 다이어그램을 포함할 수 있습니다.

400 400 

401800자를 초과하거나 3줄 이상인 붙여넣은 텍스트는 입력이 한 줄로 유지되도록 `[Pasted text #N]` 플레이스홀더로 축소됩니다. 전체 텍스트는 디스패치할 때 전송됩니다. 디스패치하기 전에 축소된 텍스트를 검토하거나 편집하려면 동일한 텍스트를 다시 붙여넣으면 플레이스홀더가 입력으로 다시 확장됩니다.401800자를 초과하거나 3줄을 넘는 붙여넣은 텍스트는 입력이 한 줄로 유지되도록 `[Pasted text #N]` 플레이스홀더로 축소됩니다. 전체 텍스트는 디스패치할 때 전송됩니다. 디스패치하기 전에 축소된 텍스트를 검토하거나 편집하려면 동일한 텍스트를 다시 붙여넣으면 플레이스홀더가 입력으로 다시 확장됩니다.

402 402 

403프롬프트의 일부를 접두사로 붙이거나 언급하여 세션이 시작되는 방식을 제어합니다:403프롬프트의 일부를 접두사로 붙이거나 언급하여 세션이 시작되는 방식을 제어합니다:

404 404 

405| 입력 | 효과 |405| 입력 | 효과 |

406| :- | :- |406| :- | :- |

407| `<agent-name> <prompt>` | 첫 번째 단어가 사용자 정의 [서브에이전트](/docs/ko/sub-agents) 이름과 일치하면, 해당 서브에이전트가 프론트매터의 구성으로 세션의 주 에이전트로 실행됩니다 |407| `<agent-name> <prompt>` | 첫 번째 단어가 사용자 정의 [서브에이전트](/docs/ko/sub-agents) 이름과 일치하면, 해당 서브에이전트가 frontmatter의 구성으로 세션의 주 에이전트로 실행됩니다 |

408| `@<agent-name>` | 프롬프트의 어디든지 사용자 정의 서브에이전트를 언급하여 주 에이전트로 실행합니다 |408| `@<agent-name>` | 프롬프트의 어디든지 사용자 정의 서브에이전트를 언급하여 주 에이전트로 실행합니다 |

409| `@<repo>` | 저장소를 언급하여 해당 위치에서 세션을 실행합니다. 어떤 저장소가 나열되는지는 [특정 디렉토리로 디스패치](#dispatch-to-a-specific-directory)를 참조하세요 |409| `@<repo>` | 저장소를 언급하여 해당 위치에서 세션을 실행합니다. 어떤 저장소가 나열되는지는 [특정 디렉터리로 디스패치](#dispatch-to-a-specific-directory)를 참조하세요 |

410| `/<command>` | [스킬](/docs/ko/skills) 및 [명령어](/docs/ko/commands)를 제안하여 프롬프트로 디스패치합니다 |410| `/<command>` | [스킬](/docs/ko/skills) 및 [명령](/docs/ko/commands)을 제안하여 프롬프트로 디스패치합니다 |

411| `! <command>` | Claude 세션을 시작하는 대신 셸 명령어를 백그라운드 작업으로 실행합니다. 작업은 연결하고, 감시하고, 분리할 수 있는 행으로 나타납니다 |411| `! <command>` | Claude 세션을 시작하는 대신 셸 명령을 백그라운드 작업으로 실행합니다. 작업은 연결하고, 감시하고, 분리할 수 있는 행으로 나타납니다 |

412| `#<number>` 또는 풀 또는 병합 요청 URL | 세션이 이미 해당 풀 요청 또는 병합 요청에서 작업 중이면, Claude Code는 새 세션을 디스패치하는 대신 해당 행을 선택합니다 |412| `#<number>` 또는 풀 리퀘스트나 병합 요청 URL | 세션이 이미 해당 풀 리퀘스트 또는 병합 요청에서 작업 중이면, Claude Code는 새 세션을 디스패치하는 대신 해당 행을 선택합니다 |

413 413 

414작은 명령어 집합은 디스패치하는 대신 에이전트 뷰 자체에서 실행됩니다:414일부 명령은 디스패치하는 대신 에이전트 뷰 자체에서 실행됩니다:

415 415 

416* `/exit` 및 `/quit`는 에이전트 뷰를 닫습니다416* `/exit` 및 `/quit`는 에이전트 뷰를 닫습니다

417* `/logout`은 로그아웃합니다417* `/logout`은 로그아웃합니다

418* `/model`은 [디스패치 모델](#set-the-model)을 설정합니다418* `/model`은 [디스패치 모델](#set-the-model)을 설정합니다

419* `/login`은 세션에 연결하지 않고 다시 로그인할 수 있도록 로그인 대화를 엽니다419* `/login`은 세션에 연결하지 않고 다시 로그인할 수 있도록 로그인 대화 상자를 엽니다

420* 단순 `/resume` 또는 그 별칭 `/continue`는 저장소의 과거 세션 선택기를 열어 [하나를 다시 가져옵니다](#organize-the-list) 백그라운드 세션으로. Claude Code v2.1.212 이상이 필요합니다420* 인수 없는 `/resume` 또는 그 별칭 `/continue`는 저장소의 과거 세션 선택기를 열어 하나를 백그라운드 세션으로 [다시 가져옵니다](#organize-the-list). Claude Code v2.1.212 이상이 필요합니다

421 421 

422스킬, 사용자 정의 명령어, 그리고 `/init`과 같은 프롬프트 확장 기본 제공 명령어는 새로운 백그라운드 세션으로 첫 번째 프롬프트로 전송됩니다. 다른 기본 제공 명령어는 `attach to a session to run it` 힌트를 대신 표시합니다. 입력한 모든 것이 힌트 옆의 입력에 남아 있으므로 편집할 수 있습니다.422스킬, 사용자 정의 명령, 그리고 `/init`과 같은 프롬프트 확장 기본 제공 명령은 새로운 백그라운드 세션에 첫 번째 프롬프트로 전송됩니다. 다른 기본 제공 명령은 대신 `attach to a session to run it` 힌트를 표시합니다. 입력한 모든 내용이 힌트 옆의 입력에 남아 있으므로 편집할 수 있습니다.

423 423 

424반복되는 작업을 [스킬](/docs/ko/skills)로 패키징하면 프롬프트를 다시 입력하지 않고도 에이전트 뷰에서 동일한 워크플로우를 반복적으로 시작할 수 있습니다.424반복되는 작업을 [스킬](/docs/ko/skills)로 패키징하면 프롬프트를 다시 입력하지 않고도 에이전트 뷰에서 동일한 워크플로를 반복적으로 시작할 수 있습니다.

425 425 

426동일한 `@name`이 서브에이전트와 형제 저장소 모두와 일치하면 서브에이전트가 우선합니다. 단순 첫 단어 일치도 적용되므로, 서브에이전트 이름 중 하나로 시작하는 프롬프트는 단어를 일반 텍스트로 취급하는 대신 해당 서브에이전트를 디스패치합니다. 명시적으로 하려면 `@` 형식을 사용하거나, 일치를 피하려면 프롬프트를 다른 단어로 시작합니다.426동일한 `@name`이 서브에이전트와 형제 저장소 모두와 일치하면 서브에이전트가 우선합니다. 단순 첫 단어 일치도 적용되므로, 서브에이전트 이름 중 하나로 시작하는 프롬프트는 단어를 일반 텍스트로 취급하는 대신 해당 서브에이전트를 디스패치합니다. 명시적으로 하려면 `@` 형식을 사용하거나, 일치를 피하려면 프롬프트를 다른 단어로 시작합니다.

427 427 

428<h4 id="dispatch-to-a-specific-directory">428<h4 id="dispatch-to-a-specific-directory">

429 특정 디렉토리로 디스패치429 특정 디렉터리로 디스패치

430</h4>430</h4>

431 431 

432새로운 세션은 에이전트 뷰를 연 디렉토리에서 실행됩니다. 다른 디렉토리를 대상으로 하려면 다음 중 하나를 사용합니다:432새로운 세션은 에이전트 뷰를 연 디렉터리에서 실행됩니다. 다른 디렉터리를 대상으로 하려면 다음 중 하나를 사용합니다:

433 433 

434* 해당 디렉토리에서 `claude agents`를 엽니다.434* 해당 디렉터리에서 `claude agents`를 엽니다.

435* 상위 디렉토리에서 `claude agents`를 열고 프롬프트에서 `@<repo>`로 자식 저장소를 언급합니다. `@`를 입력하면 다음 대상이 나열됩니다:435* 상위 디렉터리에서 `claude agents`를 열고 프롬프트에서 `@<repo>`로 하위 저장소를 언급합니다. `@`를 입력하면 다음 대상이 나열됩니다:

436 436 

437 * 시작 디렉토리 아래 한 수준의 Git 저장소437 * 시작 디렉터리 한 수준 아래의 Git 저장소

438 * 시작한 저장소의 등록된 [git 워크트리](/docs/ko/worktrees)로, 디렉토리 트리 내에 있는 것들(예: Claude가 `.claude/worktrees/` 아래에 생성한 것들)이며, 체크아웃된 브랜치로 레이블이 지정됩니다. `git worktree add ../feature`와 같이 저장소 외부에 추가된 워크트리는 나열되지 않습니다438 * 시작한 저장소의 등록된 [git worktree](/docs/ko/worktrees) 중 해당 디렉터리 트리 안에 있는 것(예: Claude가 `.claude/worktrees/` 아래에 생성한 것)이며, 체크아웃된 브랜치로 레이블이 지정됩니다. `git worktree add ../feature`와 같이 저장소 외부에 추가된 워크트리는 나열되지 않습니다

439 * 이미 목록에 세션이 있는 모든 디렉토리439 * 이미 목록에 세션이 있는 모든 디렉터리

440 440 

441 이름에 공백이 포함된 디렉토리는 나열되지 않습니다.441 이름에 공백이 포함된 디렉터리는 나열되지 않습니다.

442* 셸에서 `cd`로 디렉토리로 이동하고 `claude --bg "<prompt>"`를 실행합니다.442* 셸에서 `cd`로 디렉터리로 이동하고 `claude --bg "<prompt>"`를 실행합니다.

443 443 

444에이전트 뷰가 디렉토리별로 그룹화되면, 디스패치는 선택한 행의 디렉토리로 프롬프트를 보내므로, 경로를 다시 입력하지 않고도 그룹을 선택하고 그 안으로 디스패치할 수 있습니다.444에이전트 뷰가 디렉터리별로 그룹화되면, 디스패치는 선택한 행의 디렉터리로 프롬프트를 보내므로, 경로를 다시 입력하지 않고도 그룹을 선택하고 그 안으로 디스패치할 수 있습니다.

445 445 

446<h3 id="from-inside-a-session">446<h3 id="from-inside-a-session">

447 세션 내부에서447 세션 내부에서

448</h3>448</h3>

449 449 

450두 명령어는 작업을 현재 세션에서 백그라운드로 이동합니다: `/background`는 현재 대화를 백그라운드로 보내고 터미널을 해제하며, `/fork`는 복사본을 보내면서 현재 위치에서 계속 작업합니다.450두 명령은 현재 세션의 작업을 백그라운드로 이동합니다. `/background`는 현재 대화를 백그라운드로 보내고 터미널을 해제하며, `/fork`는 복사본을 보내고 사용자는 현재 위치에서 계속 작업합니다.

451 451 

452<h4 id="send-the-session-to-the-background">452<h4 id="send-the-session-to-the-background">

453 세션을 백그라운드로 보내기453 세션을 백그라운드로 보내기

454</h4>454</h4>

455 455 

456`/background` 또는 그 별칭 `/bg`를 실행하여 현재 대화를 백그라운드 세션으로 이동합니다. `/bg run the test suite and fix any failures`와 같은 프롬프트를 전달하여 먼저 하나의 추가 지시사항을 제공합니다. Claude가 `/bg`를 실행할 때 응답 중이면, 응답은 백그라운드 세션에서 계속됩니다.456`/background` 또는 그 별칭 `/bg`를 실행하여 현재 대화를 백그라운드 세션으로 이동합니다. `/bg run the test suite and fix any failures`와 같은 프롬프트를 전달하면 먼저 지시사항을 하나 더 제공할 수 있습니다. `/bg`를 실행할 때 Claude가 응답 중이면, 응답은 백그라운드 세션에서 계속됩니다.

457 457 

458서브에이전트, 백그라운드 셸 명령어, 워크플로우, 또는 [모니터](/docs/ko/tools-reference#monitor-tool)와 같은 백그라운드 작업이 여전히 실행 중인 세션을 종료하면, 즉시 종료하는 대신 `Background work is running` 대화가 표시됩니다. 세션을 `/background`와 동일한 방식으로 백그라운드로 이동하고 셸로 돌아가려면 `Move to background and exit`를 선택합니다. 에이전트 뷰가 [꺼져 있으면](#turn-off-agent-view) 옵션이 표시되지 않습니다.458서브에이전트, 백그라운드 셸 명령, 워크플로, 또는 [모니터](/docs/ko/tools-reference#monitor-tool)와 같은 백그라운드 작업이 여전히 실행 중인 세션을 종료하면, 즉시 종료하는 대신 `Background work is running` 대화 상자가 표시됩니다. `/background`와 동일한 방식으로 세션을 백그라운드로 이동하고 셸로 돌아가려면 `Move to background and exit`를 선택합니다. 에이전트 뷰가 [꺼져 있으면](#turn-off-agent-view) 이 옵션은 표시되지 않습니다.

459 459 

460목록의 백그라운드 세션이 이미 대화의 이름을 가지고 있으면, Claude Code는 새 행의 이름을 `my-session (2)`와 같이 번호를 매기고 기존 행의 이름은 그대로 둡니다. 새 행의 이름을 바꾸려면 에이전트 뷰에서 선택하고 `Ctrl+R`을 누릅니다.460목록의 백그라운드 세션이 이미 대화의 이름을 가지고 있으면, Claude Code는 새 행의 이름에 `my-session (2)`와 같이 번호를 매기고 기존 행의 이름은 그대로 둡니다. 새 행의 이름을 바꾸려면 에이전트 뷰에서 선택하고 `Ctrl+R`을 누릅니다.

461 461 

462<h4 id="copy-the-session-with-/fork">462<h4 id="copy-the-session-with-/fork">

463 /fork로 세션 복사463 /fork로 세션 복사

464</h4>464</h4>

465 465 

466`/fork`를 실행하여 현재 대화를 새로운 백그라운드 세션으로 복사하면서 원본은 계속 실행됩니다. 복사본은 그 시점까지의 대화의 모든 것으로 시작합니다. 복사본이 실행되는 위치는 아래 글머리 기호를 참조하세요. 또한 모델, 권한 모드, 노력 수준, 그리고 세션 중에 추가한 모든 디렉토리 또는 "다시 묻지 않기" 권한 부여를 이월합니다. 복사본은 에이전트 뷰에서 자신의 행으로 나타납니다.466`/fork`를 실행하면 원본이 계속 실행되는 동안 현재 대화를 새로운 백그라운드 세션으로 복사합니다. 복사본은 그 시점까지의 대화 내용을 모두 가지고 시작합니다. 복사본이 실행되는 위치는 아래 목록을 참조하세요. 또한 모델, 권한 모드, effort 수준, 그리고 세션 중에 추가한 모든 디렉터리 또는 "다시 묻지 않기" 권한 부여도 이어받습니다. 복사본은 에이전트 뷰에서 별도의 행으로 나타납니다.

467 467 

468포크 후, 두 대화는 독립적입니다: 복사본이 하는 것은 자동으로 원본 대화에 들어가지 않습니다. 다만 [교차 세션 메시징](/docs/ko/cross-session-messaging)이 활성화된 세션에서는 어느 세션의 Claude든 명시적으로 다른 세션에 메시지를 보낼 수 있습니다.468분기 후 두 대화는 독립적입니다. 복사본이 하는 일은 자동으로 원본 대화에 들어가지 않습니다. 다만 [교차 세션 메시징](/docs/ko/cross-session-messaging)이 활성화된 세션에서는 어느 세션의 Claude든 명시적으로 다른 세션에 메시지를 보낼 수 있습니다.

469 469 

470세션 복사에는 Claude Code v2.1.212 이상이 필요합니다. v2.1.161부터 v2.1.211까지는 `/fork`가 대신 [포크된 서브에이전트](/docs/ko/sub-agents#fork-the-current-conversation)를 시작하며, 이제는 `/subtask`입니다. [에이전트 뷰가 꺼져 있으면](#turn-off-agent-view), `/fork`는 포크된 서브에이전트 동작을 유지하고 `/subtask`는 사용할 수 없습니다.470세션 복사에는 Claude Code v2.1.212 이상이 필요합니다. v2.1.161부터 v2.1.211까지는 `/fork`가 대신 [분기된 서브에이전트](/docs/ko/sub-agents#fork-the-current-conversation)를 시작하며, 이 기능은 이제 `/subtask`입니다. [에이전트 뷰가 꺼져 있으면](#turn-off-agent-view), `/fork`는 분기된 서브에이전트 동작을 유지하고 `/subtask`는 사용할 수 없습니다.

471 471 

472`/fork open a draft pull request with the work so far`와 같은 프롬프트를 전달하면 복사본이 즉시 작업을 시작합니다. 프롬프트가 없으면 복사본은 첫 번째 지시사항을 기다립니다: `claude agents`에서 해당 행을 선택하고 `Space`를 눌러 하나를 보내거나, `claude attach <id>`를 실행합니다. 선택한 행은 기다리는 동안 `space to send it a prompt`를 표시합니다.472`/fork open a draft pull request with the work so far`와 같은 프롬프트를 전달하면 복사본이 즉시 작업을 시작합니다. 프롬프트가 없으면 복사본은 첫 번째 지시사항을 기다립니다. `claude agents`에서 해당 행을 선택하고 `Space`를 눌러 지시사항을 보내거나, `claude attach <id>`를 실행합니다. 기다리는 동안 선택한 행에는 `space to send it a prompt`가 표시됩니다.

473 473 

474`/fork` 확인은 복사본의 상태(예: `session running`), 에이전트 뷰 행의 이름, 그리고 `claude attach`를 위한 세션 ID를 보여주는 한 줄입니다. 이름을 클릭하여 복사본으로 전환합니다: 이 세션은 백그라운드로 이동하며, `←`를 누르는 것과 동일하고, 에이전트 뷰는 복사본의 세션을 엽니다.474`/fork` 확인 메시지는 복사본의 상태(예: `session running`), 에이전트 뷰 행의 이름, 그리고 `claude attach`에 사용할 세션 ID를 보여주는 한 줄입니다. 이름을 클릭하면 복사본으로 전환됩니다. 이 세션은 `←`를 누른 것과 동일하게 백그라운드로 이동하고, 에이전트 뷰가 복사본의 세션을 엽니다.

475 475 

476복사본이 [제자리에서 편집](#how-file-edits-are-isolated)하는 경우를 제외하고, Claude Code는 코드 변경을 하기 전에 자신의 워크트리를 생성하도록 지시합니다. git 저장소 외부에서는 훅으로 생성된 워크트리에서 이동한 복사본만 지시사항을 받습니다. [`WorktreeCreate` 훅](/docs/ko/hooks#worktreecreate)이 없으면 복사본은 제자리에서 편집합니다. 워크트리에서 이동한 복사본은 또한 격리 설정이 무엇이든 해당 워크트리를 편집, 명령어 실행, 또는 입력하지 않도록 지시받습니다.476복사본이 [제자리에서 편집](#how-file-edits-are-isolated)하는 경우를 제외하고, Claude Code는 코드를 변경하기 전에 자체 워크트리를 생성하도록 복사본에 지시합니다. git 저장소 외부에서는 훅으로 생성된 워크트리에서 빠져나온 복사본만 이 지시를 받으며, [`WorktreeCreate` 훅](/docs/ko/hooks#worktreecreate)이 없으면 복사본은 제자리에서 편집합니다. 사용자의 워크트리에서 빠져나온 복사본은 격리 설정과 관계없이 해당 워크트리를 편집하거나, 그 안에서 명령을 실행하거나, 그 안으로 들어가지 말라는 지시도 받습니다.

477 477 

478복사본이 시작되는 위치는 현재 세션이 실행 중인 위치에 따라 다릅니다:478복사본이 시작되는 위치는 현재 세션이 실행 중인 위치에 따라 다릅니다:

479 479 

480* 디스패치된 모든 세션과 마찬가지로, 복사본은 [파일을 편집하기 전에 자신의 워크트리로 이동합니다](#how-file-edits-are-isolated). 이 경우 확인은 복사본이 실행되는 위치를 언급하지 않습니다.480* 디스패치된 다른 세션과 마찬가지로, 복사본은 [파일을 편집하기 전에 자체 워크트리로 이동합니다](#how-file-edits-are-isolated). 이 경우 확인 메시지는 복사본이 실행되는 위치를 언급하지 않습니다.

481* 세션이 시작 후 연결된 [워크트리](/docs/ko/worktrees)로 이동했을 때, 복사본은 이동 전 세션이 있던 위치에서 시작하며, [제자리에서 편집](#how-file-edits-are-isolated)하지 않으면 자신의 코드 변경을 자신의 워크트리에서 수행합니다. 워크트리가 브랜치에 체크아웃되면, 해당 지시사항은 또한 작업이 사용자의 작업을 기반으로 하는 복사본에 사용자의 브랜치를 기반으로 새 브랜치를 만들도록 지시합니다. 사용자의 브랜치는 워크트리에서 체크아웃된 상태로 유지되기 때문입니다. 확인은 `runs in the origin tree`로 끝납니다.481* 세션이 시작된 후 연결된 [워크트리](/docs/ko/worktrees)로 이동한 경우, 복사본은 이동 전 세션이 있던 위치에서 시작하며, [제자리에서 편집](#how-file-edits-are-isolated)하지 않는 한 그곳의 자체 워크트리에서 코드를 변경합니다. 사용자의 워크트리가 브랜치에 체크아웃되어 있으면, 해당 지시는 작업이 사용자의 작업을 기반으로 하는 복사본에게 새 브랜치를 사용자의 브랜치 기반으로 만들라고도 알립니다. 사용자의 브랜치는 사용자의 워크트리에 체크아웃된 상태로 유지되기 때문입니다. 확인 메시지는 `runs in the origin tree`로 끝납니다.

482* 주 워킹 트리가 있는 저장소의 연결된 [워크트리](/docs/ko/worktrees) 내부에서 세션을 시작했을 때, 복사본은 해당 주 워킹 트리에서 시작하며, 동일한 워크트리 자체 규칙이지만 브랜치 지시사항은 없습니다. 확인은 여기서도 `runs in the origin tree`로 끝납니다.482* 메인 작업 트리가 있는 저장소의 연결된 워크트리 안에서 세션을 시작한 경우, 복사본은 해당 메인 작업 트리에서 시작하며, 자체 워크트리 규칙은 동일하지만 브랜치 지시는 없습니다. 여기서도 확인 메시지는 `runs in the origin tree`로 끝납니다.

483* 주 워킹 트리가 없는 베어 저장소 레이아웃의 워크트리 내부에서 시작한 세션은 돌아갈 주 워킹 트리가 없으므로, 복사본은 제자리에 남아 있으며, 확인은 `edits this checkout`으로 끝납니다. 워크트리 격리가 [꺼져 있으면](#how-file-edits-are-isolated) 연결된 워크트리 내부가 아닌 세션에서도 동일한 메모가 나타납니다. 복사본이 열려 있는 파일을 편집하기 때문입니다.483* 베어 저장소 레이아웃의 워크트리 안에서 시작한 세션은 돌아갈 메인 작업 트리가 없으므로, 복사본은 제자리에 머물며 확인 메시지는 `edits this checkout`으로 끝납니다. 연결된 워크트리 안에 있지 않은 세션에서 워크트리 격리가 [꺼져 있을](#how-file-edits-are-isolated) 때도 같은 메모가 표시됩니다. 이 경우 복사본이 사용자가 열어 둔 파일을 편집하기 때문입니다.

484 484 

485복사본이 상속하지 않을 시작 플래그로 시작한 세션(예: 대체된 시스템 프롬프트 또는 `--tools` 허용 목록)은 포크할 수 없습니다. Claude Code는 부분 복사본을 만드는 대신 그렇게 말합니다. 에이전트 뷰에서 디스패치된 세션은 정상적으로 포크됩니다: 복사본은 세션이 온 것과 동일한 [에이전트 정의](/docs/ko/sub-agents) 및 추가된 지시사항으로 시작됩니다.485대체된 시스템 프롬프트나 `--tools` 허용 목록처럼 복사본이 상속하지 않는 시작 플래그로 시작한 세션은 분기할 수 없습니다. Claude Code는 부분 복사본을 만드는 대신 그 사실을 알립니다. 에이전트 뷰에서 디스패치된 세션은 정상적으로 분기됩니다. 복사본은 원래 세션과 동일한 [에이전트 정의](/docs/ko/sub-agents) 및 추가된 지시사항으로 시작됩니다.

486 486 

487<h4 id="what-carries-over-when-you-background">487<h4 id="what-carries-over-when-you-background">

488 백그라운드로 이동할 때 이월되는 것488 백그라운드로 이동할 때 이어지는 것

489</h4>489</h4>

490 490 

491백그라운드로 이동하면 저장된 대화에서 재개하는 새로운 프로세스가 시작되며, 진행 중인 작업이 이동합니다: 실행 중인 백그라운드 셸 명령어, 백그라운드된 서브에이전트, 동적 워크플로우, [`/loop`](/docs/ko/scheduled-tasks)로 생성한 예약된 작업, 그리고 Claude의 [아티팩트 댓글에 대한 자동 회신](/docs/ko/artifacts#let-claude-reply-to-comments-on-its-own)이 모두 이월되고 계속 실행됩니다. 서브에이전트는 시작한 모든 것과 함께 이동하므로, 모든 작업이 이동할 수 있을 때만 이월됩니다. 진행 중인 작업을 이월하는 대신 중지하려면 [`CLAUDE_DISABLE_ADOPT=1`](/docs/ko/env-vars#variables) 환경 변수를 설정합니다. Claude Code는 백그라운드로 이동하기 전에 확인을 요청합니다.491백그라운드로 이동하면 저장된 대화에서 재개하는 새 프로세스가 시작되며, 진행 중인 작업이 그 프로세스로 이동합니다. 실행 중인 백그라운드 셸 명령, 백그라운드로 보낸 서브에이전트, 동적 워크플로, [`/loop`](/docs/ko/scheduled-tasks)로 생성한 예약 작업, 그리고 Claude의 [아티팩트 댓글에 대한 자동 회신](/docs/ko/artifacts#let-claude-reply-to-comments-on-its-own)이 모두 이어져 그곳에서 계속 실행됩니다. 서브에이전트는 자신이 시작한 모든 것과 함께 이동하므로, 그 작업이 모두 이동할 수 있을 때만 이어집니다. 진행 중인 작업을 이어가는 대신 중지하려면 [`CLAUDE_DISABLE_ADOPT=1`](/docs/ko/env-vars#variables) 환경 변수를 설정합니다. 그러면 Claude Code는 백그라운드로 이동하기 전에 확인을 요청합니다.

492 492 

493[동적 워크플로우](/docs/ko/workflows)가 여전히 실행 중인 서브에이전트를 가지고 있을 때, Claude Code는 `Background this session?` 대화로 백그라운드로 이동하기 전에 요청하며, 몇 개의 서브에이전트가 재시작될 것인지 말합니다. 먼저 완료되도록 하려면 `Stay`를 선택합니다. 확인하면, Claude Code는 백그라운드 세션에서 실행을 재생합니다: 여전히 실행 중이던 서브에이전트는 처음부터 다시 시작되므로, 지금까지 사용한 토큰이 다시 소비됩니다. 어떤 완료된 서브에이전트가 저장된 결과를 반환하고 어떤 것이 다시 실행되는지는 [일시 중지 후 재개](/docs/ko/workflows#resume-after-a-pause)를 참조하세요.493[동적 워크플로](/docs/ko/workflows)에 아직 실행 중인 서브에이전트가 있으면, Claude Code는 백그라운드로 이동하기 전에 `Background this session?` 대화 상자로 묻고, 몇 개의 서브에이전트가 재시작되는지 알려줍니다. 먼저 완료되도록 하려면 `Stay`를 선택합니다. 확인하면 Claude Code는 백그라운드 세션에서 실행을 재생합니다. 아직 실행 중이던 서브에이전트는 처음부터 다시 시작되므로, 지금까지 사용한 토큰이 다시 소비됩니다. 완료된 서브에이전트 중 어떤 것이 저장된 결과를 반환하고 어떤 것이 다시 실행되는지는 [일시 중지 후 재개](/docs/ko/workflows#resume-after-a-pause)를 참조하세요.

494 494 

495Claude Code는 실행 중인 [모니터](/docs/ko/tools-reference#monitor-tool)와 같이 이월할 수 없는 작업을 중지하고, 모니터를 소유한 백그라운드된 서브에이전트를 함께 중지합니다. 이러한 작업이 실행 중이면, Claude Code는 `Background this session?` 대화를 표시하여 작업을 중지하기 전에 확인할 수 있습니다.495Claude Code는 실행 중인 [모니터](/docs/ko/tools-reference#monitor-tool)처럼 이어갈 수 없는 작업을 중지하며, 모니터를 소유한 백그라운드 서브에이전트도 함께 중지합니다. 이러한 작업이 실행 중이면 Claude Code는 `Background this session?` 대화 상자를 표시하여 작업을 중지하기 전에 확인할 수 있게 합니다.

496 496 

497백그라운드에 있으면, 세션은 새로운 서브에이전트, 모니터, 백그라운드 명령어를 시작할 수 있으며, 이들은 나중의 분리 및 재연결 전반에 걸쳐 계속 실행됩니다.497백그라운드로 이동한 후 세션은 새로운 서브에이전트, 모니터, 백그라운드 명령을 시작할 수 있으며, 이들은 이후 분리 및 재연결 후에도 계속 실행됩니다.

498 498 

499원본 시작의 구성 플래그는 백그라운드된 세션으로 전달되므로, 해당 MCP 서버, 설정, 그리고 폴백 모델이 계속 적용됩니다:499원래 시작할 때의 구성 플래그는 백그라운드 세션으로 이어지므로, 해당 MCP 서버, 설정, 폴백 모델이 계속 적용됩니다:

500 500 

501* `--mcp-config` 및 `--strict-mcp-config`501* `--mcp-config` 및 `--strict-mcp-config`

502* `--settings`502* `--settings`

506* `--fallback-model`506* `--fallback-model`

507* `--allow-dangerously-skip-permissions`507* `--allow-dangerously-skip-permissions`

508 508 

509세션 중에 [`/add-dir`](/docs/ko/permissions#additional-directories-grant-file-access-not-configuration)로 추가한 디렉토리도 이월됩니다. `--allow-dangerously-skip-permissions`를 이월하면 백그라운드된 세션에서 `bypassPermissions`에 도달할 수 있지만, 새로운 것을 부여하지는 않습니다: 모드는 여전히 [권한 모드, 모델, 및 노력](#permission-mode-model-and-effort)에 설명된 일회성 대화형 수락이 필요합니다.509세션 중에 [`/add-dir`](/docs/ko/permissions#additional-directories-grant-file-access-not-configuration)로 추가한 디렉터리도 이어집니다. `--allow-dangerously-skip-permissions`가 이어지면 백그라운드 세션에서 `bypassPermissions`에 도달할 수 있지만, 새로운 권한을 부여하지는 않습니다. 이 모드는 여전히 [권한 모드, 모델, effort](#permission-mode-model-and-effort)에 설명된 일회성 대화형 수락이 필요합니다.

510 510 

511<h3 id="from-your-shell">511<h3 id="from-your-shell">

512 셸에서512 셸에서

513</h3>513</h3>

514 514 

515`--bg` 또는 그 긴 형식 `--background`를 전달하여 백그라운드로 바로 가는 세션을 시작합니다:515`--bg` 또는 그 긴 형식 `--background`를 전달하여 바로 백그라운드로 가는 세션을 시작합니다:

516 516 

517```bash theme={null}517```bash theme={null}

518claude --bg "investigate the flaky SettingsChangeDetector test"518claude --bg "investigate the flaky SettingsChangeDetector test"

520 520 

521프롬프트는 `-p` 값이 아닌 위치 인수입니다. Claude Code는 세션이 생성되기 전에 `-p` 또는 `--print`와 결합된 `--bg`를 거부합니다. `--print`는 `claude agents`가 연결하는 대화형 세션을 시작하지 않기 때문입니다.521프롬프트는 `-p` 값이 아닌 위치 인수입니다. Claude Code는 세션이 생성되기 전에 `-p` 또는 `--print`와 결합된 `--bg`를 거부합니다. `--print`는 `claude agents`가 연결하는 대화형 세션을 시작하지 않기 때문입니다.

522 522 

523[신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)하지 않은 디렉토리의 터미널에서 `claude --bg`를 실행하면, 워크스페이스 신뢰 대화가 먼저 나타나고 수락하면 세션이 시작됩니다. 거부하면, Claude Code는 세션을 시작하지 않고 종료합니다. 스크립트와 같이 대화가 나타날 수 없는 곳에서는 명령어가 [`Workspace not trusted`](/docs/ko/errors#workspace-not-trusted-when-dispatching-a-background-session) 오류로 종료됩니다.523[신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)하지 않은 디렉터리의 터미널에서 `claude --bg`를 실행하면, 워크스페이스 신뢰 대화 상자가 먼저 나타나고 수락하면 세션이 시작됩니다. 거부하면 Claude Code는 세션을 시작하지 않고 종료합니다. 스크립트처럼 대화 상자가 나타날 수 없는 곳에서는 명령이 대신 [`Workspace not trusted`](/docs/ko/errors#workspace-not-trusted-when-dispatching-a-background-session) 오류로 종료됩니다.

524 524 

525`code-reviewer`와 같이 정의한 특정 [서브에이전트](/docs/ko/sub-agents)를 세션의 주 에이전트로 실행하려면, `--bg`를 `--agent`와 결합합니다:525`code-reviewer`처럼 직접 정의한 특정 [서브에이전트](/docs/ko/sub-agents)를 세션의 주 에이전트로 실행하려면 `--bg`를 `--agent`와 결합합니다:

526 526 

527```bash theme={null}527```bash theme={null}

528claude --agent code-reviewer --bg "address review comments on PR 1234"528claude --agent code-reviewer --bg "address review comments on PR 1234"

529```529```

530 530 

531이름이 서브에이전트와 일치하지 않으면, 시작이 실패합니다: Claude Code는 `no agent named` 경고를 인쇄하고 여전히 세션을 백그라운드로 보고하지만, 세션은 `--agent '<name>' not found` 오류로 즉시 종료됩니다.531이름이 서브에이전트와 일치하지 않으면 시작이 실패합니다. Claude Code는 `no agent named` 경고를 출력하고 여전히 세션을 백그라운드로 보냈다고 보고하지만, 세션은 `--agent '<name>' not found` 오류로 즉시 종료됩니다.

532 532 

533백그라운드된 세션이 나중에 재개되거나 재시작될 때, Claude Code는 에이전트 및 해당 도구 제한을 복원합니다. 시스템 프롬프트는 [재개된 대화의 시스템 프롬프트 플래그](/docs/ko/cli-reference#system-prompt-flags-in-resumed-conversations)를 참조하세요. 세션의 자신의 디렉토리에서 에이전트를 먼저 검색합니다. [해당 워크스페이스를 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)했다면, 프로젝트 범위 에이전트는 다른 디렉토리에서 세션이 재개될 때도 로드됩니다. 에이전트가 더 이상 존재하지 않으면, 세션은 기본 도구로 계속되고 해당 트랜스크립트는 [에이전트 이름을 지정하는 경고](/docs/ko/errors#session-agent-no-longer-available)와 함께 열립니다.533백그라운드 세션이 나중에 재개되거나 재시작될 때, Claude Code는 에이전트와 해당 도구 제한을 복원합니다. 시스템 프롬프트에 대해서는 [재개된 대화의 시스템 프롬프트 플래그](/docs/ko/cli-reference#system-prompt-flags-in-resumed-conversations)를 참조하세요. 사용자가 [해당 워크스페이스를 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)했다면 세션 자체의 디렉터리에서 에이전트를 먼저 검색하므로, 다른 디렉터리에서 세션을 재개해도 프로젝트 범위 에이전트가 로드됩니다. 에이전트가 더 이상 존재하지 않으면 세션은 기본 도구로 계속되며, 트랜스크립트는 [에이전트 이름을 알리는 경고](/docs/ko/errors#session-agent-no-longer-available)와 함께 열립니다.

534 534 

535기존 대화를 백그라운드에서 계속하려면, `--resume`으로 전체 세션 ID를 전달합니다:535기존 대화를 백그라운드에서 계속하려면 `--resume`으로 전체 세션 ID를 전달합니다:

536 536 

537```bash theme={null}537```bash theme={null}

538claude --resume 1f0e2c9a-6d0b-4c11-9f39-2a77c1d4e8b5 --bg "pick up where you left off and finish the migration"538claude --resume 1f0e2c9a-6d0b-4c11-9f39-2a77c1d4e8b5 --bg "pick up where you left off and finish the migration"

539```539```

540 540 

541Claude Code v2.1.257 이상에서, Claude Code는 동일한 ID로 해당 세션을 계속하거나, 새로운 ID로 복사본을 시작하고 제자리에서 계속할 수 없는 이유를 설명하는 `note:` 줄을 인쇄합니다. 세션이 제자리에서 계속되면, `claude agents`는 해당 행 하나를 표시합니다.541Claude Code v2.1.257 이상에서 Claude Code는 동일한 ID로 해당 세션을 계속하거나, 새로운 ID로 복사본을 시작하고 제자리에서 계속할 수 없었던 이유를 설명하는 `note:` 줄을 출력합니다. 세션이 제자리에서 계속되면 `claude agents`에는 해당 세션의 행이 하나만 표시됩니다.

542 542 

543`--bg`를 `--continue`, 단순 `--resume`, 또는 이름이나 파일 경로가 있는 `--resume`과 결합하면, Claude Code는 항상 이러한 복사본을 시작합니다. 메모 없이 의도적으로 복사본을 시작하려면 `--fork-session`을 추가합니다.543`--bg`를 `--continue`, 인수 없는 `--resume`, 또는 이름이나 파일 경로가 있는 `--resume`과 결합하면, Claude Code는 항상 이러한 복사본을 시작합니다. 메모 없이 의도적으로 복사본을 시작하려면 `--fork-session`을 추가합니다.

544 544 

545`--name`을 전달하여 자동 생성된 이름 대신 에이전트 뷰에서 세션의 표시 이름을 설정합니다:545`--name`을 전달하면 자동 생성된 이름 대신 에이전트 뷰에 표시될 세션 이름을 설정할 수 있습니다:

546 546 

547```bash theme={null}547```bash theme={null}

548claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"548claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"

549```549```

550 550 

551백그라운드로 이동한 후, Claude는 세션의 짧은 ID와 관리 명령어를 인쇄합니다. 백그라운드 세션을 호스팅하는 서비스가 아직 실행 중이 아니면, `--bg`는 먼저 이 출력 위에 `Starting background service…`를 인쇄할 수 있습니다. `--name`을 전달하면, 이름이 짧은 ID 뒤에 나타납니다:551백그라운드로 이동한 후 Claude는 세션의 짧은 ID와 세션 관리 명령을 출력합니다. 백그라운드 세션을 호스팅하는 서비스가 아직 실행 중이 아니면, `--bg`가 이 출력 위에 먼저 `Starting background service…`를 출력할 수 있습니다. `--name`을 전달하면 이름이 짧은 ID 뒤에 나타납니다:

552 552 

553```text theme={null}553```text theme={null}

554backgrounded · 7c5dcf5d · flaky-test-fix554backgrounded · 7c5dcf5d · flaky-test-fix

559```559```

560 560 

561<h4 id="run-a-shell-command">561<h4 id="run-a-shell-command">

562 셸 명령어 실행562 셸 명령 실행

563</h4>563</h4>

564 564 

565Claude 세션 대신 셸 명령어를 백그라운드 작업으로 실행하려면, `--exec`을 전달합니다. 다음 예제는 `pytest -x`를 백그라운드 작업으로 실행합니다:565Claude 세션 대신 셸 명령을 백그라운드 작업으로 실행하려면 `--exec`을 전달합니다. 다음 예제는 `pytest -x`를 백그라운드 작업으로 실행합니다:

566 566 

567```bash theme={null}567```bash theme={null}

568claude --bg --exec 'pytest -x'568claude --bg --exec 'pytest -x'

569```569```

570 570 

571에이전트 뷰에서, 디스패치 입력의 첫 번째 문자로 `!`를 입력하여 동일한 종류의 작업을 디스패치합니다: `!`는 접두사로 표시되고, 그 뒤의 모든 것이 명령어이며, `Enter`가 작업을 시작합니다.571에이전트 뷰에서는 디스패치 입력의 첫 번째 문자로 `!`를 입력하여 같은 종류의 작업을 디스패치합니다. `!`는 접두사로 표시되고, 그 뒤의 모든 내용이 명령이며, `Enter`를 누르면 작업이 시작됩니다.

572 572 

573명령어는 PTY 지원 작업으로 실행되고 에이전트 뷰에 행으로 나타나며, 가장 최근 출력 줄이 상태입니다. 셸 작업은 Claude 대신 명령어를 실행하므로, 모델이 호출되지 않고 출력이 어떤 세션으로도 전송되지 않습니다.573명령은 PTY 기반 작업으로 실행되고 에이전트 뷰에 행으로 나타나며, 가장 최근 출력 줄이 상태로 표시됩니다. 셸 작업은 Claude 대신 명령을 실행하므로 모델이 호출되지 않고, 출력은 어떤 세션으로도 전송되지 않습니다.

574 574 

575출력을 보려면, 행에 연결하고, `Space`를 눌러 연결하지 않고 미리 보거나, 셸에서 `claude logs <id>`를 실행합니다. 캡처된 출력은 메모리에 유지되고 디스크에 기록되지 않습니다. 행과 해당 출력은 명령어가 종료된 후 약 5분 후에 자동으로 정리되므로, 결과가 필요하면 그 전에 읽으세요.575출력을 보려면 행에 연결하거나, `Space`를 눌러 연결하지 않고 미리 보거나, 셸에서 `claude logs <id>`를 실행합니다. 캡처된 출력은 메모리에 유지되며 디스크에 기록되지 않습니다. 행과 출력은 명령이 종료된 후 약 5분 뒤에 자동으로 정리되므로, 결과가 필요하면 그 전에 확인하세요.

576 576 

577<h3 id="how-file-edits-are-isolated">577<h3 id="how-file-edits-are-isolated">

578 파일 편집이 격리되는 방식578 파일 편집이 격리되는 방식

583Claude는 다음의 경우 워크트리를 건너뜁니다:583Claude는 다음의 경우 워크트리를 건너뜁니다:

584 584 

585* 이미 열어 둔 세션을 `←` 또는 `/background`로 [백그라운드로 이동한](#from-inside-a-session) 경우. 해당 세션은 이미 작업하던 위치에서 계속 파일을 편집합니다585* 이미 열어 둔 세션을 `←` 또는 `/background`로 [백그라운드로 이동한](#from-inside-a-session) 경우. 해당 세션은 이미 작업하던 위치에서 계속 파일을 편집합니다

586* 세션이 이미 연결된 git 워크트리 내부에 있으며, Claude가 `.claude/worktrees/` 아래에 생성했거나 `git worktree add`로 다른 곳에 생성했는지 여부586* 세션이 이미 연결된 git 워크트리 안에 있는 경우. Claude가 `.claude/worktrees/` 아래에 생성했든 사용자가 `git worktree add`로 다른 곳에 생성했든 마찬가지입니다

587* Claude가 편집하는 파일이 연결된 git 워크트리 내부에 있으며, 예를 들어 세션이나 서브에이전트가 `git worktree add`로 생성한 것587* Claude가 편집하는 파일이 연결된 git 워크트리 안에 있는 경우. 예를 들어 세션이나 그 서브에이전트가 `git worktree add`로 생성한 워크트리입니다

588* 워킹 디렉토리가 git 저장소가 아니고 [`WorktreeCreate` 훅](/docs/ko/hooks#worktreecreate)이 구성되지 않음588* 작업 디렉터리가 git 저장소가 아니고 [`WorktreeCreate` 훅](/docs/ko/hooks#worktreecreate)이 구성되지 않은 경우

589* 쓰기가 워킹 디렉토리 외부589* 쓰기가 작업 디렉터리 외부에서 일어나는 경우

590 590 

591git 워크트리가 비실용적인 저장소에 대해 워크트리 격리를 끄려면, [`worktree.bgIsolation`](/docs/ko/settings-reference#worktree-bgisolation)을 `"none"`으로 설정합니다. 백그라운드 세션은 먼저 워크트리로 이동하지 않고 워킹 복사본을 직접 편집합니다. 프로젝트의 `.claude/settings.json`에 설정을 추가합니다:591git 워크트리가 실용적이지 않은 저장소에서 워크트리 격리를 끄려면 [`worktree.bgIsolation`](/docs/ko/settings-reference#worktree-bgisolation)을 `"none"`으로 설정합니다. 그러면 백그라운드 세션은 먼저 워크트리로 이동하지 않고 작업 복사본을 직접 편집합니다. 프로젝트의 `.claude/settings.json`에 설정을 추가합니다:

592 592 

593```json theme={null}593```json theme={null}

594{594{

598}598}

599```599```

600 600 

601git 저장소 외부에서, 세션은 워킹 디렉토리에 직접 쓰고 서로 격리되지 않으므로, 동일한 파일을 편집하는 병렬 세션을 디스패치하지 않도록 합니다. 다른 버전 제어 시스템을 사용하면, [`WorktreeCreate` 훅](/docs/ko/worktrees#non-git-version-control)을 구성하고 Claude는 git과 동일한 방식으로 편집을 격리합니다.601git 저장소 외부에서는 세션이 작업 디렉터리에 직접 쓰고 서로 격리되지 않으므로, 동일한 파일을 편집하는 병렬 세션을 디스패치하지 않도록 합니다. 다른 버전 관리 시스템을 사용한다면 [`WorktreeCreate` 훅](/docs/ko/worktrees#non-git-version-control)을 구성하면 Claude가 git과 동일한 방식으로 편집을 격리합니다.

602 602 

603git 저장소가 아닌 디렉터리에서 훅이 실패하면 Claude는 해당 디렉터리의 격리를 건너뛰고 작업 디렉터리를 제자리에서 편집합니다. git 저장소 안에서는 Claude가 편집 전에 워크트리로 이동시키는 세션은 그 이동이 이루어질 때까지 공유 체크아웃의 파일을 편집할 수 없습니다.603git 저장소가 아닌 디렉터리에서 훅이 실패하면 Claude는 해당 디렉터리의 격리를 건너뛰고 작업 디렉터리를 제자리에서 편집합니다. git 저장소 안에서는 Claude가 편집 전에 워크트리로 이동시키는 세션은 그 이동이 이루어질 때까지 공유 체크아웃의 파일을 편집할 수 없습니다.

604 604 

605세션의 워크트리 경로를 찾으려면, 세션을 미리 보거나 연결하고 워킹 디렉토리를 확인합니다.605세션의 워크트리 경로를 찾으려면 세션에 연결하여 작업 디렉터리를 확인합니다.

606 606 

607백그라운드 세션이 생성하는 [서브에이전트](/docs/ko/sub-agents)는 세션의 작업 디렉터리를 상속합니다. 세션이 워크트리에 들어간 후에는 서브에이전트의 파일 편집이 작업 복사본이 아닌 해당 워크트리에 반영됩니다. 대신 서브에이전트에 별도의 자체 워크트리를 제공하려면 frontmatter에서 [`isolation: worktree`](/docs/ko/sub-agents#supported-frontmatter-fields)를 설정하거나 생성할 때 `isolation: "worktree"`를 전달합니다.607백그라운드 세션이 생성하는 [서브에이전트](/docs/ko/sub-agents)는 세션의 작업 디렉터리를 상속합니다. 세션이 워크트리에 들어간 후에는 서브에이전트의 파일 편집이 작업 복사본이 아닌 해당 워크트리에 반영됩니다. 대신 서브에이전트에 별도의 자체 워크트리를 제공하려면 frontmatter에서 [`isolation: worktree`](/docs/ko/sub-agents#supported-frontmatter-fields)를 설정하거나 생성할 때 `isolation: "worktree"`를 전달합니다.

608 608 

609백그라운드 세션이 Claude가 입력한 워크트리에서 코드 변경을 했을 때, Claude Code는 Claude에게 완료하기 전에 작업을 보존하도록 지시하므로, 세션 및 워크트리를 삭제해도 생존합니다:609백그라운드 세션이 Claude가 들어간 워크트리에서 코드를 변경한 경우, Claude Code는 완료하기 전에 작업을 보존하도록 Claude에 지시하므로, 세션과 워크트리를 삭제해도 작업이 남습니다:

610 610 

611* **커밋 및 푸시**: Claude는 묻지 않고 커밋하며, 저장소에 원격이 있을 때 브랜치를 푸시합니다.611* **커밋 및 푸시**: Claude는 묻지 않고 커밋하며, 저장소에 원격이 있으면 브랜치를 푸시합니다.

612* **초안 풀 요청**: Claude는 작업이 요구할 때 열며, [`#N` 레이블](#pull-request-status)이 행에 나타납니다.612* **초안 풀 리퀘스트**: 작업에 필요하면 Claude가 초안 풀 리퀘스트를 열고, 행에 [`#N` 레이블](#pull-request-status)이 나타납니다.

613* **절대 안 함**: `main` 또는 `master`로 푸시, 강제 푸시, 병합.613* **절대 하지 않음**: `main` 또는 `master`로 푸시, 강제 푸시, 병합.

614* **사용자의 git 지시사항이 우선합니다**: 작업, `CLAUDE.md`, 또는 [메모리](/docs/ko/memory)가 커밋 또는 푸시를 직접 처리한다고 말하면, Claude는 git을 사용자에게 맡깁니다.614* **사용자의 git 지시사항이 우선합니다**: 작업, `CLAUDE.md`, 또는 [메모리](/docs/ko/memory)에 커밋이나 푸시를 사용자가 직접 처리한다고 되어 있으면, Claude는 git 작업을 사용자에게 맡깁니다.

615 615 

616자신을 격리하지 않은 체크아웃을 편집하는 세션은 여전히 커밋 또는 브랜치 전환 전에 요청합니다. 이는 격리가 `"none"`으로 설정되었을 때, 워크트리 이동이 실패했을 때, 또는 세션이 이미 존재하는 워크트리 내부에서 시작했을 때 적용됩니다.616스스로 격리하지 않은 체크아웃을 편집하는 세션은 여전히 커밋하거나 브랜치를 전환하기 전에 묻습니다. 이는 격리가 `"none"`으로 설정되었거나, 워크트리 이동이 실패했거나, 세션이 이미 존재하던 워크트리 안에서 시작된 경우에 적용됩니다.

617 617 

618작업이 무엇이든, Claude는 작업을 수행한 것과 작업이 있는 위치를 말하는 보고서로 작업을 끝냅니다: 경로, 브랜치, 풀 요청, 또는 답변 자체.618작업이 무엇이든 Claude는 무엇을 했는지와 작업 결과가 어디에 있는지(경로, 브랜치, 풀 리퀘스트, 또는 답변 자체)를 알리는 보고로 작업을 마칩니다.

619 619 

620<h4 id="what-deleting-a-session-removes">620<h4 id="what-deleting-a-session-removes">

621 세션 삭제가 제거하는 것621 세션 삭제 시 제거되는 것

622</h4>622</h4>

623 623 

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

625 625 

626Claude가 세션을 위해 생성한 워크트리에 어떤 일이 일어나는지:626Claude가 세션을 위해 생성한 워크트리는 다음과 같이 처리됩니다:

627 627 

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

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

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

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

632 632 

633 원격의 커밋은 삭제를 차단하지 않습니다. 로컬 복사본의 `origin` 원격의 기본 브랜치의 커밋도 마찬가지입니다. 해당 브랜치가 메인 체크아웃(저장소 디렉토리 자체가 아닌 워크트리)에 체크아웃되어 있으면.633 원격에 있는 커밋은 삭제를 막지 않습니다. `origin` 원격의 기본 브랜치의 로컬 복사본에 있는 커밋도 마찬가지이며, 단 해당 브랜치가 워크트리가 아닌 저장소 디렉터리 자체인 메인 체크아웃에 체크아웃되어 있어야 합니다.

634 634 

635 그 거부 후, 다음을 선택합니다:635 이렇게 거부된 후 다음 중에서 선택합니다:

636 636 

637 * 커밋을 유지하려면, 푸시하거나 해당 기본 브랜치에 병합한 다음 세션을 다시 삭제합니다.637 * 커밋을 유지하려면 푸시하거나 해당 기본 브랜치에 병합한 다음 세션을 다시 삭제합니다.

638 * 버리려면, 푸시하지 않고 다시 삭제합니다: 에이전트 뷰의 행에서 `Ctrl+X`를 두 번 누르거나, 거부가 인쇄한 `claude rm <id> --discard-unpushed` 명령어를 실행합니다. 이는 세션과 워크트리를 제거하고 푸시되지 않은 커밋과 커밋되지 않은 변경 사항을 버립니다.638 * 커밋을 버리려면 푸시하지 않고 세션을 다시 삭제합니다. 에이전트 뷰에서 해당 행에 `Ctrl+X`를 두 번 누르거나, 거부 메시지에 출력된 `claude rm <id> --discard-unpushed` 명령을 실행합니다. 이렇게 하면 세션과 워크트리, 그리고 워크트리의 브랜치가 제거되며, 푸시되지 않은 커밋과 커밋되지 않은 변경 사항이 모두 버려집니다.

639 639 

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

641 641 

642 다른 완료된 세션의 기록이 워크트리의 이름을 지정할 때도, 다시 삭제할 때 유지됩니다. 커밋을 푸시한 다음 다시 삭제합니다.642 완료된 다른 세션의 기록에도 해당 워크트리가 지정되어 있으면, 다시 삭제해도 워크트리가 유지됩니다. 커밋을 푸시한 다음 다시 삭제합니다.

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

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

645 645 

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

647 647 

648 Claude Code는 다음을 모두 확인할 수 있을 때만 이를 제공합니다:648 Claude Code는 다음을 모두 확인할 수 있을 때만 이 방법을 제시합니다:

649 649 

650 * 디렉토리는 저장소의 `.claude/worktrees/` 아래의 연결된 워크트리 중 하나입니다650 * 디렉터리가 `.claude/worktrees/` 아래에 있는 저장소의 연결된 워크트리 중 하나입니다

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

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

653 653 

654 Claude Code가 별도의 git 저장소로 대체된 서브모듈 체크아웃의 상태를 확인할 수 없을 때, 이것도 제공하지 않습니다.654 별도의 git 저장소로 대체된 서브모듈 체크아웃처럼 Claude Code가 서브모듈 체크아웃의 상태를 확인할 수 없는 경우에도 이 방법을 제시하지 않습니다.

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

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

657 657 

658직접 생성하고 세션을 시작한 워크트리는 어느 쪽이든 제자리에 남아 있습니다.658사용자가 직접 생성하고 그 안에서 세션을 시작한 워크트리는 어느 경우든 그대로 남습니다.

659 659 

660워크트리 디렉토리가 git 저장소에 속하지 않는 세션(저장소가 삭제되었거나 [`WorktreeCreate` 훅](/docs/ko/hooks#worktreecreate)이 디렉토리를 다른 곳에 생성했기 때문)도 여전히 삭제할 수 있습니다. 디렉토리에 파일이 남아 있는 동안:660저장소가 삭제되었거나 [`WorktreeCreate` 훅](/docs/ko/hooks#worktreecreate)이 디렉터리를 다른 곳에 생성했기 때문에 워크트리 디렉터리가 어떤 git 저장소에도 속하지 않는 세션도 삭제할 수 있습니다. 디렉터리에 파일이 남아 있는 동안에는 다음과 같습니다:

661 661 

662* 에이전트 뷰는 버리기 전에 동일한 `Ctrl+X` 이중 누르기를 요청합니다. 훅으로 생성된 디렉토리의 경우 [`WorktreeRemove` 훅](/docs/ko/hooks#worktreeremove)을 실행하고, 없으면 삭제를 거부하고 세션을 유지합니다.662* 에이전트 뷰는 파일을 버리기 전에 동일하게 `Ctrl+X`를 두 번 누르도록 요청합니다. 훅으로 생성된 디렉터리의 경우 대신 [`WorktreeRemove` 훅](/docs/ko/hooks#worktreeremove)을 실행하며, 훅이 없으면 삭제를 거부하고 세션을 유지합니다.

663* `claude rm`은 세션과 워크트리를 유지하고 이유의 이름을 지정합니다.663* `claude rm`은 세션과 워크트리를 유지하고 이유를 알립니다.

664 664 

665어느 경로든 다른 완료된 세션의 기록이 이름을 지정하는 디렉토리를 유지합니다.665어느 방법이든 완료된 다른 세션의 기록에 지정된 디렉터리는 유지됩니다.

666 666 

667<h3 id="set-the-model">667<h3 id="set-the-model">

668 모델 설정668 모델 설정

669</h3>669</h3>

670 670 

671에이전트 뷰 헤더에 표시된 모델 이름은 디스패치 기본값입니다. 입력에서 시작하는 새로운 세션은 이 모델을 사용하며, 이는 사용자 설정의 [`model` 설정](/docs/ko/settings-reference#model)에서 옵니다. [`/model` 선택기](/docs/ko/model-config)에서 모델을 선택하거나 설정을 직접 편집하여 설정합니다.671에이전트 뷰 헤더에 표시된 모델 이름은 디스패치 기본값입니다. 입력에서 시작하는 새 세션은 이 모델을 사용하며, 이 모델은 사용자 설정의 [`model` 설정](/docs/ko/settings-reference#model)에서 가져옵니다. [`/model` 선택기](/docs/ko/model-config)에서 모델을 선택하거나 설정을 직접 편집하여 지정합니다.

672 672 

673전체 에이전트 뷰 세션에 대해 디스패치 기본값을 재정의하려면, 에이전트 뷰를 열 때 `--model`을 전달합니다. [권한 모드, 모델, 및 노력](#permission-mode-model-and-effort)을 참조하세요.673에이전트 뷰 세션 전체에 대해 디스패치 기본값을 재정의하려면 에이전트 뷰를 열 때 `--model`을 전달합니다. [권한 모드, 모델, effort](#permission-mode-model-and-effort)를 참조하세요.

674 674 

675에이전트 뷰 내부에서 디스패치 기본값을 변경하려면, 디스패치 입력에 `/model` 뒤에 모델 이름을 입력하고 `Enter`를 누릅니다. 헤더는 `(session)` 마커와 함께 해당 모델을 표시하도록 업데이트되며, 그 후 디스패치하는 세션은 이를 사용합니다. `/model default`를 입력하여 재정의를 지우고 디스패치 기본값으로 돌아갑니다. 이 재정의는 현재 `claude agents` 실행의 나머지 동안 지속되고 설정 파일에 쓰지 않습니다. 다음 예제는 Opus에서 한 세션을 디스패치하고 Sonnet에서 다음을 디스패치합니다:675에이전트 뷰 안에서 디스패치 기본값을 변경하려면 디스패치 입력에 `/model`과 모델 이름을 입력하고 `Enter`를 누릅니다. 헤더가 `(session)` 마커와 함께 해당 모델을 표시하도록 업데이트되며, 이후 디스패치하는 세션은 이 모델을 사용합니다. 재정의를 지우고 디스패치 기본값으로 돌아가려면 `/model default`를 입력합니다. 이 재정의는 현재 `claude agents` 실행이 끝날 때까지 유지되며 설정 파일에 기록되지 않습니다. 다음 예제는 한 세션을 Opus로, 다음 세션을 Sonnet으로 디스패치합니다:

676 676 

677```text theme={null}677```text theme={null}

678/model opus678/model opus

681run the test suite681run the test suite

682```682```

683 683 

684각 백그라운드 세션은 다른 모델에서 실행될 수 있습니다. 한 세션에 대해 재정의하려면:684각 백그라운드 세션은 서로 다른 모델로 실행될 수 있습니다. 한 세션에 대해 재정의하려면:

685 685 

686* 셸에서, `claude --bg`와 함께 `--model`을 전달합니다.686* 셸에서 `claude --bg`와 함께 `--model`을 전달합니다.

687* 실행 중인 세션에 연결하고 `/model`을 실행하여 전환합니다: 선택기에서 선택하거나 입력한 `/model <name>`은 선택기에서 `s`를 누르지 않으면 새 세션의 기본값으로 저장됩니다. 세션 전용 전환은 세션이 재생성되면 지속됩니다.687* 실행 중인 세션에 연결하고 `/model`을 실행하여 전환합니다. 선택기에서 고르거나 `/model <name>`을 입력한 선택은, 선택기에서 `s`를 눌러 세션 전용으로 전환하지 않는 한 새 세션의 기본값으로 저장됩니다. 세션 전용 전환은 세션이 다시 생성되어도 유지됩니다.

688* 프론트매터가 `model` 필드를 설정하는 [서브에이전트](/docs/ko/sub-agents)를 디스패치합니다.688* frontmatter에 `model` 필드가 설정된 [서브에이전트](/docs/ko/sub-agents)를 디스패치합니다.

689 689 

690<h3 id="permission-mode-model-and-effort">690<h3 id="permission-mode-model-and-effort">

691 권한 모드, 모델, 및 노력691 권한 모드, 모델, effort

692</h3>692</h3>

693 693 

694백그라운드 세션은 설정, 제공자, 권한 모드, 모델, 그리고 노력을 디스패치한 위치와 방식에서 가져옵니다. 아래 소절은 각 소스와 감독자가 세션을 재시작할 때 지속되는 것을 다룹니다.694백그라운드 세션은 설정, 제공자, 권한 모드, 모델, effort를 디스패치한 위치와 방식에서 가져옵니다. 아래 하위 섹션에서는 각 출처와, 감독자가 세션을 재시작할 때 유지되는 항목을 다룹니다.

695 695 

696<h4 id="settings-and-provider">696<h4 id="settings-and-provider">

697 설정 및 제공자697 설정 및 제공자

698</h4>698</h4>

699 699 

700백그라운드 세션은 [설정](/docs/ko/settings)을 실행하는 디렉토리에서 읽으며, 이는 [이월한 구성 플래그](#what-carries-over-when-you-background)와 함께 거기서 `claude`를 시작한 것과 동일합니다. 여기에는 프로젝트 설정의 [`env` 값](/docs/ko/settings-reference#env)이 포함되므로, 거기에 설정된 `ANTHROPIC_MODEL` 또는 제공자 변수는 해당 디렉토리의 모든 백그라운드 세션에 적용됩니다.700백그라운드 세션은 실행되는 디렉터리에서 [설정](/docs/ko/settings)을 읽으며, 이는 [이어받은 구성 플래그](#what-carries-over-when-you-background)로 그곳에서 `claude`를 시작한 것과 같습니다. 여기에는 프로젝트 설정의 [`env` 값](/docs/ko/settings-reference#env)도 포함되므로, 그곳에 설정된 `ANTHROPIC_MODEL`이나 제공자 변수는 해당 디렉터리의 모든 백그라운드 세션에 적용됩니다.

701 701 

702백그라운드 세션은 또한 디스패치한 셸의 `PATH`로 실행되므로, 실행하는 명령어는 터미널과 동일한 도구를 찾습니다. `CLAUDE_CODE_USE_BEDROCK` 또는 `CLAUDE_CODE_USE_VERTEX`와 같은 클라우드 제공자 선택도 유지하며, `ANTHROPIC_DEFAULT_*_MODEL` 별칭과 내보낸 모든 [`CLAUDE_CODE_EXTRA_BODY`](/docs/ko/env-vars) 재정의도 유지합니다.702백그라운드 세션은 또한 디스패치한 셸의 `PATH`로 실행되므로, 세션이 실행하는 명령은 터미널과 동일한 도구를 찾습니다. `CLAUDE_CODE_USE_BEDROCK`이나 `CLAUDE_CODE_USE_VERTEX` 같은 해당 셸의 클라우드 제공자 선택도 유지되며, `ANTHROPIC_DEFAULT_*_MODEL` 별칭과 그 셸에서 내보낸 [`CLAUDE_CODE_EXTRA_BODY`](/docs/ko/env-vars) 재정의도 함께 유지됩니다.

703 703 

704<h4 id="llm-gateway">704<h4 id="llm-gateway">

705 LLM 게이트웨이705 LLM 게이트웨이

706</h4>706</h4>

707 707 

708[LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 Claude Code를 라우팅하면, 게이트웨이 변수를 셸에서 내보내는 대신 설정 파일의 `env` 블록에 넣고, 백그라운드 세션은 나머지 설정과 함께 읽습니다. [설정 파일에서 설정](/docs/ko/llm-gateway-connect#set-in-a-settings-file)은 블록과 자격 증명에 사용할 설정 파일을 표시합니다.708[LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 Claude Code를 라우팅한다면, 게이트웨이 변수를 셸에서 내보내는 대신 설정 파일의 `env` 블록에 넣으면 백그라운드 세션이 나머지 설정과 함께 이를 읽습니다. [설정 파일에서 설정](/docs/ko/llm-gateway-connect#set-in-a-settings-file)에서 해당 블록과 자격 증명에 사용할 설정 파일을 확인할 수 있습니다.

709 709 

710대신 셸에서만 게이트웨이 `ANTHROPIC_BASE_URL`을 내보내면, 백그라운드 세션에 도달합니다. [감독자](#the-supervisor-process)가 동일한 게이트웨이를 내보낸 셸에서 시작되었을 때만, 그리고 `ANTHROPIC_CUSTOM_HEADERS` 및 자격 증명과 함께 내보낸 경우에만, 그리고 이 경우에만:710대신 게이트웨이 `ANTHROPIC_BASE_URL`을 셸에서만 내보내면, 함께 내보낸 `ANTHROPIC_CUSTOM_HEADERS` 및 자격 증명과 함께 백그라운드 세션에 전달되는 것은 [감독자](#the-supervisor-process) 자체가 같은 게이트웨이를 내보낸 셸에서 시작된 경우뿐이며, 그마저도 다음 경우에만 해당합니다:

711 711 

712* `←` 또는 `/background`로 자신의 세션을 백그라운드로 이동합니다712* `←` 또는 `/background`로 자신의 세션을 백그라운드로 보내는 경우

713* 현재 있는 디렉토리로 세션을 디스패치합니다713* 현재 있는 디렉터리로 세션을 디스패치하는 경우

714* 현재 있는 디렉토리에서 중지된 세션을 깨우거나 회신합니다714* 현재 있는 디렉터리에서 중지된 세션에 연결하거나 회신하여 깨우는 경우

715 715 

716Claude Code는 클라우드 제공자 앞의 게이트웨이를 전달합니다. 디스패치한 셸이 제공자를 선택하고 해당 인증 바이패스 플래그와 함께 게이트웨이 엔드포인트를 내보내면, Claude Code는 `ANTHROPIC_BASE_URL`에 적용되는 조건 아래에서 엔드포인트 및 플래그 쌍을 `ANTHROPIC_CUSTOM_HEADERS`와 함께 전달합니다. 예를 들어, `CLAUDE_CODE_USE_VERTEX=1`을 `ANTHROPIC_VERTEX_BASE_URL` 및 `CLAUDE_CODE_SKIP_VERTEX_AUTH=1`과 함께 내보내면, Claude Code는 해당 엔드포인트와 플래그를 전달합니다.716Claude Code는 클라우드 제공자 앞에 있는 게이트웨이도 전달합니다. 디스패치하는 셸이 제공자를 선택하고 인증 우회 플래그와 함께 게이트웨이 엔드포인트를 내보내면, Claude Code는 `ANTHROPIC_BASE_URL`에 적용되는 조건에서 엔드포인트와 플래그 쌍을 `ANTHROPIC_CUSTOM_HEADERS`와 함께 세션에 전달합니다. 예를 들어 `CLAUDE_CODE_USE_VERTEX=1`을 `ANTHROPIC_VERTEX_BASE_URL` 및 `CLAUDE_CODE_SKIP_VERTEX_AUTH=1`과 함께 내보내면, Claude Code는 해당 엔드포인트와 플래그를 전달합니다.

717 717 

718Claude Code는 전달된 게이트웨이를 해당 세션의 실행 중인 프로세스에만 적용하고 디스크에 쓰지 않습니다.718Claude Code는 전달된 게이트웨이를 해당 세션의 실행 중인 프로세스에만 적용하며 디스크에 기록하지 않습니다.

719 719 

720<h4 id="permission-mode">720<h4 id="permission-mode">

721 권한 모드721 권한 모드

723 723 

724[권한 모드](/docs/ko/permissions)는 세션을 시작한 방식에 따라 다릅니다:724[권한 모드](/docs/ko/permissions)는 세션을 시작한 방식에 따라 다릅니다:

725 725 

726* **`/bg` 또는 `←`로 백그라운드된**: Claude Code는 세션이 있던 권한 모드를 유지하므로, `acceptEdits` 또는 `auto`로 전환한 것은 분리 후에도 유지됩니다726* **`/bg` 또는 `←`로 백그라운드로 보낸 경우**: Claude Code는 세션의 기존 권한 모드를 유지하므로, `acceptEdits`나 `auto`로 전환한 세션은 분리 후에도 그 모드를 유지합니다

727* **`←`로 연 에이전트 뷰에서 디스패치됨**: 대상의 자신의 구성이 먼저 오고, 세션의 권한 모드가 다른 것이 설정하지 않을 때 적용됩니다727* **`←`로 연 에이전트 뷰에서 디스패치한 경우**: 대상 자체의 구성이 먼저 적용되고, 다른 설정이 없을 때 원래 세션의 권한 모드가 적용됩니다

728* **셸에서 시작한 `claude agents` 또는 `claude --bg`에서 디스패치됨**: 새 세션은 해당 디렉토리에서 새 `claude` 세션이 시작되는 방식으로 시작됩니다. [세션이 시작되는 권한 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in)는 순서를 나열합니다728* **셸에서 시작한 `claude agents` 또는 `claude --bg`로 디스패치한 경우**: [디스패치 기본값](#dispatch-defaults)과 함께 연 에이전트 뷰에서 디스패치한 경우가 아니면, 새 세션은 해당 디렉터리에서 새 `claude` 세션이 시작되는 방식대로 시작됩니다. [세션이 시작되는 권한 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in)에 순서가 나와 있습니다

729 729 

730`←`로 연 에이전트 뷰에서 디스패치한 세션의 경우, Claude Code는 다음 중 첫 번째 적용되는 것에서 권한 모드를 가져옵니다:730`←`로 연 에이전트 뷰에서 디스패치한 세션의 경우, Claude Code는 다음 중 처음으로 적용되는 항목에서 권한 모드를 가져옵니다:

731 731 

7321. 대상 디렉토리의 [`permissions.defaultMode`](/docs/ko/settings-reference#permissions-defaultmode). 두 소스 규칙이 적용됩니다:7321. 대상 디렉터리의 [`permissions.defaultMode`](/docs/ko/settings-reference#permissions-defaultmode). 출처에 관한 두 가지 규칙이 적용됩니다:

733 * `auto` 및 `bypassPermissions`은 [관리 설정, `--settings` 파일, 또는 `~/.claude/settings.json`에서만 적용됩니다](/docs/ko/settings-reference#permissions-defaultmode).733 * `auto`와 `bypassPermissions`는 [관리형 설정, `--settings` 파일, 또는 `~/.claude/settings.json`에서만 적용됩니다](/docs/ko/settings-reference#permissions-defaultmode).

734 * Claude Code는 프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`에서 온 `defaultMode`를 거부합니다. 이는 세션이 있던 것보다 더 허용적인 모드를 선택합니다.734 * Claude Code는 프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`에 있는 `defaultMode`가 원래 세션의 모드보다 더 허용적인 모드를 선택하면 이를 거부합니다.

7352. 세션의 권한 모드7352. 원래 세션의 권한 모드

736 736 

737Claude Code가 소스의 모드를 너무 허용적으로 거부하면, 목록의 다음 소스가 결정합니다. 예를 들어, 플랜 모드 세션에서 `acceptEdits`를 요청하는 체크인된 설정이 있는 디렉토리로 디스패치하면, 새 세션은 플랜 모드에서 시작됩니다. 해당 `defaultMode`를 `~/.claude/settings.json`으로 이동하면, 세션의 권한 모드와 관계없이 적용됩니다.737Claude Code가 어떤 출처의 모드를 지나치게 허용적이라는 이유로 거부하면, 목록의 다음 출처가 결정합니다. 예를 들어 플랜 모드 세션에서 체크인된 설정이 `acceptEdits`를 요청하는 디렉터리로 디스패치하면, 새 세션은 플랜 모드로 시작합니다. 해당 `defaultMode`를 `~/.claude/settings.json`으로 옮기면 원래 세션의 권한 모드와 관계없이 적용됩니다.

738 738 

739허용성은 플랜, 그 다음 Manual 및 `dontAsk`, 그 다음 `acceptEdits` 및 auto(각각 다른 것보다 더 허용적으로 계산됨), 그 다음 `bypassPermissions`입니다.739허용 범위는 plan, 그다음 Manual과 `dontAsk`, 그다음 `acceptEdits`와 auto(서로가 서로보다 더 허용적인 것으로 간주됨), 그다음 `bypassPermissions` 순으로 넓어집니다.

740 740 

741<h4 id="dispatch-defaults">741<h4 id="dispatch-defaults">

742 디스패치 기본값742 디스패치 기본값

743</h4>743</h4>

744 744 

745에이전트 뷰에서 디스패치하는 모든 세션에 대해 기본값을 설정하려면, 열 때 `--permission-mode`, `--model`, `--effort`, 또는 `--agent` 중 하나를 전달합니다:745에이전트 뷰에서 디스패치하는 모든 세션의 기본값을 설정하려면, 에이전트 뷰를 열 때 `--permission-mode`, `--model`, `--effort`, `--agent` 중 원하는 것을 전달합니다:

746 746 

747```bash theme={null}747```bash theme={null}

748claude agents --permission-mode plan --model opus --effort high748claude agents --permission-mode plan --model opus --effort high

749```749```

750 750 

751여기서 `--effort`는 `ultracode`를 포함한 [최상위 `--effort` 플래그](/docs/ko/cli-reference#cli-flags)와 동일한 값을 허용합니다.751여기서 `--effort`는 `ultracode`를 포함하여 [최상위 `--effort` 플래그](/docs/ko/cli-reference#cli-flags)와 동일한 값을 허용합니다.

752 752 

753`--agent`는 디스패치 프롬프트가 `@name` 또는 첫 단어로 이름을 지정하지 않을 때 사용되는 [서브에이전트](/docs/ko/sub-agents)를 설정합니다. 설정된 [`agent` 설정](/docs/ko/settings-reference#agent)이 있으면 기본값이고, 그렇지 않으면 기본 제공 catch-all `claude` 에이전트입니다. 디스패치 입력에서 서브에이전트의 이름을 지정하면 둘 다 재정의합니다.753`--agent`는 디스패치 프롬프트가 `@name`이나 첫 단어로 서브에이전트를 지정하지 않을 때 사용되는 [서브에이전트](/docs/ko/sub-agents)를 설정합니다. 기본값은 [`agent` 설정](/docs/ko/settings-reference#agent)이 있으면 그 값이고, 없으면 기본 제공 범용 `claude` 에이전트입니다. 디스패치 입력에서 서브에이전트를 지정하면 둘 다 재정의됩니다.

754 754 

755`claude agents`는 또한 `--dangerously-skip-permissions`를 `--permission-mode bypassPermissions`의 약자로 허용하고, `--allow-dangerously-skip-permissions`를 각 디스패치된 세션의 `Shift+Tab` 사이클에서 `bypassPermissions`를 사용 가능하게 하여 해당 모드에서 시작하지 않습니다. 둘 다 [최상위 CLI 플래그](/docs/ko/cli-reference)와 일치합니다.755`claude agents`는 `--permission-mode bypassPermissions`의 약칭인 `--dangerously-skip-permissions`와, 해당 모드로 시작하지 않으면서 디스패치된 각 세션의 `Shift+Tab` 순환에서 `bypassPermissions`를 사용할 수 있게 하는 `--allow-dangerously-skip-permissions`도 허용합니다. 둘 다 [최상위 CLI 플래그](/docs/ko/cli-reference)와 동일합니다.

756 756 

757`--restricted`를 전달하여 뷰에서 디스패치하는 모든 세션을 [제한된 모드](/docs/ko/cli-reference#cli-flags)에서 시작합니다. 각각이 최상위 `--restricted` 플래그로 시작된 것처럼. Claude Code v2.1.248 이상이 필요합니다.757`--restricted`를 전달하면 뷰에서 디스패치하는 모든 세션이 각각 최상위 `--restricted` 플래그로 시작된 것처럼 [제한 모드](/docs/ko/cli-reference#cli-flags)로 시작됩니다. Claude Code v2.1.248 이상이 필요합니다.

758 758 

759활성 기본값은 디스패치 입력 아래의 바닥글에 나타납니다.759활성 기본값은 디스패치 입력 아래의 바닥글에 표시됩니다.

760 760 

761Claude Code는 `claude --bg --permission-mode bypassPermissions`를 거부합니다. 대화형으로 `claude --dangerously-skip-permissions`를 한 번 실행하여 바이패스 면책사항을 수락할 때까지. 해당 모드는 감시하지 않는 세션이 승인 없이 작동하도록 합니다. `--dangerously-skip-permissions` 또는 `--permission-mode bypassPermissions`를 `claude agents`에 전달하면 이전에 수락하지 않았을 때 동일한 면책사항을 표시하고, 수락하면 `bypassPermissions`를 뷰에서 시작하는 세션에 적용합니다. `--allow-dangerously-skip-permissions`를 전달하면 동일한 면책사항도 표시되고, 수락하면 `bypassPermissions`를 해당 세션의 `Shift+Tab` 사이클에서 사용 가능하게 하여 시작하지 않습니다.761Claude Code는 `claude --dangerously-skip-permissions`를 대화형으로 한 번 실행하여 우회 면책 조항을 수락하기 전까지 `claude --bg --permission-mode bypassPermissions`를 거부합니다. 이 모드에서는 사용자가 지켜보지 않는 세션이 승인 없이 작업하기 때문입니다. 이전에 수락하지 않았다면 `claude agents`에 `--dangerously-skip-permissions` 또는 `--permission-mode bypassPermissions`를 전달할 때도 같은 면책 조항이 표시되며, 수락하면 뷰에서 시작하는 세션에 `bypassPermissions`가 적용됩니다. `--allow-dangerously-skip-permissions`를 전달해도 같은 면책 조항이 표시되며, 수락하면 해당 세션을 그 모드로 시작하지 않으면서 `Shift+Tab` 순환에서 `bypassPermissions`를 사용할 수 있게 됩니다.

762 762 

763<h4 id="what-persists-across-restarts">763<h4 id="what-persists-across-restarts">

764 재시작 전반에 지속되는 것764 재시작 후에도 유지되는 것

765</h4>765</h4>

766 766 

767백그라운드 세션에 대해 선택한 권한 모드, 모델, 및 노력. [이월한 구성 플래그](#what-carries-over-when-you-background)와 함께, 감독자가 나중에 [중지 및 재시작](#the-supervisor-process)할 때 모두 지속됩니다. `claude --bg --dangerously-skip-permissions` 또는 `claude --bg --permission-mode bypassPermissions`로 시작한 세션은 해당 재시작 후 `bypassPermissions`에 유지됩니다. `/model` 또는 `/effort`로 중간 세션에서 변경한 모델 또는 노력도 유지됩니다.767백그라운드 세션에 대해 선택한 권한 모드, 모델, effort는 [세션이 이어받은 구성 플래그](#what-carries-over-when-you-background)와 함께, 감독자가 나중에 프로세스를 [중지하고 재시작](#the-supervisor-process)해도 모두 유지됩니다. `claude --bg --dangerously-skip-permissions` 또는 `claude --bg --permission-mode bypassPermissions`로 시작한 세션은 재시작 후에도 `bypassPermissions`를 유지합니다. 세션 도중 `/model` 또는 `/effort`로 변경한 모델이나 effort도 유지됩니다.

768 768 

769세션이 `--effort` 또는 `/effort`가 아닌 설정에서 노력을 가져온 경우, Claude Code는 세션을 시작할 때마다 설정을 다시 읽습니다. `settings.json`에서 저장된 노력을 편집한 후, 변경은 `←` 또는 `/bg`로 백그라운드하는 세션에 도달하고, 나중의 재시작에 도달합니다. 저장된 노력은 [`effortLevel`](/docs/ko/settings-reference#effortlevel) 키 또는 [`modelSettings`](/docs/ko/settings-reference#modelsettings) 항목입니다.769세션이 `--effort`나 `/effort`가 아닌 설정에서 effort를 가져왔다면, Claude Code는 세션의 프로세스를 시작할 때마다 설정을 다시 읽습니다. `settings.json`에 저장된 effort를 편집하면, 그 변경은 `←` 또는 `/bg`로 백그라운드로 보내는 세션과 그 이후의 재시작에 반영됩니다. 저장된 effort는 [`effortLevel`](/docs/ko/settings-reference#effortlevel) 키 또는 [`modelSettings`](/docs/ko/settings-reference#modelsettings) 항목입니다.

770 770 

771Claude Code는 또한 [`/rename`](/docs/ko/commands) 또는 `Ctrl+R`로 설정한 이름을 해당 재시작 전반에 유지하므로, [`claude --resume <name>`](/docs/ko/sessions#name-your-sessions)을 실행하여 세션에 도달할 수 있습니다.771Claude Code는 [`/rename`](/docs/ko/commands) 또는 `Ctrl+R`로 설정한 이름도 재시작 후에 유지하므로, 여전히 [`claude --resume <name>`](/docs/ko/sessions#name-your-sessions)을 실행하여 세션에 접근할 수 있습니다.

772 772 

773[`Ctrl+S`](/docs/ko/interactive-mode#general-controls)로 연결된 동안 스태시한 프롬프트도 세션과 함께 유지됩니다. 중지되거나 재시작된 후 세션을 다시 열고, `Ctrl+S`는 스태시된 텍스트를 복원합니다. 스태시의 붙여넣은 콘텐츠는 재시작을 견디지 못합니다.773연결된 동안 [`Ctrl+S`](/docs/ko/interactive-mode#general-controls)로 스태시한 프롬프트도 세션과 함께 유지됩니다. 프로세스가 중지되거나 재시작된 후 세션을 다시 열고 `Ctrl+S`를 누르면 스태시한 텍스트가 복원됩니다. 스태시에 포함된 붙여넣은 콘텐츠는 재시작 후 유지되지 않습니다.

774 774 

775<h3 id="settings-plugins-and-mcp-servers">775<h3 id="settings-plugins-and-mcp-servers">

776 설정, 플러그인, 및 MCP 서버776 설정, 플러그인, MCP 서버

777</h3>777</h3>

778 778 

779에이전트 뷰는 설정, 플러그인, MCP 서버, 및 추가 디렉토리를 로드하기 위해 `claude`와 동일한 구성 플래그를 허용합니다. 에이전트 뷰는 `--settings`, `--setting-sources`, 및 `--plugin-dir`을 자신에게 적용하고 모든 구성 플래그를 디스패치하는 세션으로 전달하므로, 이 방식으로 로드하는 플러그인 또는 MCP 서버는 해당 세션에서 사용 가능합니다.779에이전트 뷰는 설정, 플러그인, MCP 서버, 추가 디렉터리를 로드하기 위해 `claude`와 동일한 구성 플래그를 허용합니다. 에이전트 뷰는 `--settings`, `--setting-sources`, `--plugin-dir`을 자체에 적용하고 모든 구성 플래그를 디스패치하는 세션에 전달하므로, 이 방식으로 로드한 플러그인이나 MCP 서버는 해당 세션에서 사용할 수 있습니다.

780 780 

781| 플래그 | 효과 |781| 플래그 | 효과 |

782| :- | :- |782| :- | :- |

783| [`--settings <file-or-json>`](/docs/ko/settings) | 에이전트 뷰 및 디스패치된 세션에 대한 설정 재정의 |783| [`--settings <file-or-json>`](/docs/ko/settings) | 에이전트 뷰 및 디스패치된 세션의 설정 재정의 |

784| [`--setting-sources <sources>`](/docs/ko/cli-reference#cli-flags) | 에이전트 뷰 및 디스패치된 세션에서 명명된 설정 소스만 로드 |784| [`--setting-sources <sources>`](/docs/ko/cli-reference#cli-flags) | 에이전트 뷰 및 디스패치된 세션에서 지정한 설정 소스만 로드 |

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

786| [`--plugin-dir <path>`](/docs/ko/plugins/create#load-a-directory-or-archive-for-one-session) | 로컬 디렉토리에서 플러그인 로드 |786| [`--plugin-dir <path>`](/docs/ko/plugins/create#load-a-directory-or-archive-for-one-session) | 로컬 디렉터리에서 플러그인 로드 |

787| [`--mcp-config <file-or-json>`](/docs/ko/mcp) | 구성 파일 또는 JSON 문자열에서 MCP 서버 로드 |787| [`--mcp-config <file-or-json>`](/docs/ko/mcp) | 설정 파일 또는 JSON 문자열에서 MCP 서버 로드 |

788| `--strict-mcp-config` | `--mcp-config`에서만 MCP 서버를 사용하고 다른 MCP 구성을 무시합니다. 관리 MCP 파일 아래에서 플래그가 수행하는 작업은 [관리 mcp.json으로 배타적 제어](/docs/ko/managed-mcp#exclusive-control-with-managed-mcp-json)를 참조하세요 |788| `--strict-mcp-config` | `--mcp-config`의 MCP 서버만 사용하고 다른 MCP 구성은 무시합니다. 관리형 MCP 파일이 있을 때 이 플래그의 동작은 [managed-mcp.json을 통한 배타적 제어](/docs/ko/managed-mcp#exclusive-control-with-managed-mcp-json)를 참조하세요 |

789 789 

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

791 791 

792`--settings`, `--setting-sources`, 및 `--plugin-dir`을 `agents` 전에 또는 후에 배치할 수 있습니다. `--add-dir` 및 `--mcp-config`를 `agents` 후에 유지합니다: `agents` 전에 둘 중 하나를 배치하면, [`claude agents --json`](#manage-sessions-from-the-shell)이 `unknown option` 오류로 실패합니다.792`--settings`, `--setting-sources`, `--plugin-dir`은 `agents` 앞이나 뒤에 둘 수 있습니다. `--add-dir`과 `--mcp-config`는 `agents` 뒤에 두어야 합니다. 둘 중 하나라도 `agents` 앞에 두면 [`claude agents --json`](#manage-sessions-from-the-shell)이 `unknown option` 오류로 실패합니다.

793 793 

794다음 예제는 설정 재정의 및 하나의 추가 디렉토리로 에이전트 뷰를 엽니다:794다음 예제는 설정 재정의와 추가 디렉터리 하나로 에이전트 뷰를 엽니다:

795 795 

796```bash theme={null}796```bash theme={null}

797claude agents --settings ./ci-settings.json --add-dir ../shared-lib797claude agents --settings ./ci-settings.json --add-dir ../shared-lib

798```798```

799 799 

800`--settings`는 파일 경로 또는 인라인 JSON 문자열을 허용합니다. 파일 경로는 기존 파일을 가리켜야 합니다. 그렇지 않으면 Claude Code는 `Settings file not found` 오류로 종료됩니다.800`--settings`는 파일 경로 또는 인라인 JSON 문자열을 허용합니다. 파일 경로는 존재하는 파일을 가리켜야 하며, 그렇지 않으면 Claude Code는 `Settings file not found` 오류로 종료됩니다.

801 801 

802<h2 id="manage-sessions-from-the-shell">802<h2 id="manage-sessions-from-the-shell">

803 셸에서 세션 관리803 셸에서 세션 관리

810| `claude agents` | 에이전트 뷰 열기 |810| `claude agents` | 에이전트 뷰 열기 |

811| `claude agents --cwd <path>` | `<path>` 아래에서 시작된 세션으로 범위가 지정된 에이전트 뷰 열기 |811| `claude agents --cwd <path>` | `<path>` 아래에서 시작된 세션으로 범위가 지정된 에이전트 뷰 열기 |

812| `claude agents --json` | 세션을 JSON 배열로 인쇄하고 종료합니다. [세션을 JSON으로 나열](#list-sessions-as-json) 참조 |812| `claude agents --json` | 세션을 JSON 배열로 인쇄하고 종료합니다. [세션을 JSON으로 나열](#list-sessions-as-json) 참조 |

813| `claude attach <id>` | 이 터미널에서 세션에 연결 |813| `claude attach <id\|name>` | 이 터미널에서 세션에 연결 |

814| `claude logs <id>` | 세션의 최근 출력 인쇄 |814| `claude logs <id\|name>` | 세션의 최근 출력 인쇄 |

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

816| `claude respawn <id>` | 세션을 다시 시작하고, 실행 중이거나 중지된 상태에서 저장된 대화를 재개합니다. 예를 들어 업데이트된 Claude Code 바이너리를 선택하기 위해. 다시 시작된 세션은 저장된 대화를 재개하며, 디스크에 없으면 원래 프롬프트를 새 대화로 다시 실행합니다 |816| `claude respawn <id>` | 세션을 다시 시작하고, 실행 중이거나 중지된 상태에서 저장된 대화를 재개합니다. 예를 들어 업데이트된 Claude Code 바이너리를 선택하기 위해. 다시 시작된 세션은 저장된 대화를 재개하며, 디스크에 없으면 원래 프롬프트를 새 대화로 다시 실행합니다 |

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

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

819| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | 푸시되지 않은 커밋으로 인해 삭제가 거부된 세션을 삭제하고, worktree와 해당 브랜치 및 커밋을 함께 삭제합니다. 거부 시 출력된 정확한 값을 전달합니다. [세션 삭제 시 제거되는 항목](#what-deleting-a-session-removes) 참조. v2.1.260 이상 필요 |819| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | 푸시되지 않은 커밋으로 인해 삭제가 거부된 세션을 삭제하고, worktree와 해당 브랜치 및 커밋을 함께 삭제합니다. 거부 시 출력된 정확한 값을 전달합니다. [세션 삭제 시 제거되는 항목](#what-deleting-a-session-removes) 참조. v2.1.260 이상 필요 |

820| `claude rm <id> --force-remove-worktree <worktree-id>` | git 또는 `WorktreeRemove` 훅이 worktree를 제거할 수 없어 삭제가 거부된 세션을 삭제하고, worktree 디렉터리를 어쨌든 삭제하며 해당 브랜치는 저장소에 남겨둡니다. 거부 시 출력된 정확한 값을 전달합니다. [세션 삭제 시 제거되는 항목](#what-deleting-a-session-removes) 참조. v2.1.268 이상 필요 |820| `claude rm <id> --force-remove-worktree <worktree-id>` | git 또는 `WorktreeRemove` 훅이 worktree를 제거할 수 없어 삭제가 거부된 세션을 삭제하고, worktree 디렉터리를 어쨌든 삭제하며 해당 브랜치는 저장소에 남겨둡니다. 거부 시 출력된 정확한 값을 전달합니다. [세션 삭제 시 제거되는 항목](#what-deleting-a-session-removes) 참조. v2.1.268 이상 필요 |

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

822| `claude daemon stop --any` | 감독자 프로세스와 이를 호스팅하는 백그라운드 세션을 중지합니다. `--keep-workers`를 전달하여 백그라운드 세션을 실행 상태로 유지하면 다음 감독자가 이들에 다시 연결됩니다. 다음 `claude agents` 또는 `claude --bg`는 새로운 감독자를 시작합니다 |822| `claude daemon stop --any` | 감독자 프로세스와 이를 호스팅하는 백그라운드 세션을 중지합니다. `--keep-workers`를 전달하여 백그라운드 세션을 실행 상태로 유지하면 다음 감독자가 이들에 다시 연결됩니다. 다음 `claude agents` 또는 `claude --bg`는 새로운 감독자를 시작합니다 |

823 823 

824`claude attach`와 `claude logs`는 ID 대신 실행 중인 세션 이름의 일부를 받을 수 있습니다(예: `claude logs "auth refactor"`). 이름을 전달하려면 Claude Code v2.1.290 이상이 필요합니다.

825 

824<h3 id="list-sessions-as-json">826<h3 id="list-sessions-as-json">

825 세션을 JSON으로 나열827 세션을 JSON으로 나열

826</h3>828</h3>

863 865 

864Claude Code는 에이전트 뷰에 나열된 모든 세션을 현재 연결되어 있는지 여부와 관계없이 백그라운드 세션으로 취급합니다. 반대로 `claude`를 직접 실행하여 시작한 세션은 해당 터미널에 연결되어 있으며 [백그라운드로 보내지](#from-inside-a-session) 않는 한 터미널이 닫힐 때 종료됩니다.866Claude Code는 에이전트 뷰에 나열된 모든 세션을 현재 연결되어 있는지 여부와 관계없이 백그라운드 세션으로 취급합니다. 반대로 `claude`를 직접 실행하여 시작한 세션은 해당 터미널에 연결되어 있으며 [백그라운드로 보내지](#from-inside-a-session) 않는 한 터미널이 닫힐 때 종료됩니다.

865 867 

866어떤 종류의 세션에 있는지 확인하려면 [`/status`](/docs/ko/commands)를 실행합니다. `Session kind` 행은 백그라운드 세션에서 터미널이 연결되어 있는지 여부에 따라 `background job · attached` 또는 `background job · unattended`를 읽으며, 다른 모든 세션에서는 `interactive`를 읽습니다.868어떤 종류의 세션에 있는지 확인하려면 [`/status`](/docs/ko/commands)를 실행합니다. `Session kind` 행은 백그라운드 세션에서 터미널이 연결되어 있는지 여부에 따라 `background job · attached` 또는 `background job · unattended`를 표시하며, 다른 모든 세션에서는 `interactive`를 표시합니다.