SpyBara
Go Premium

Documentation 2026-05-12 22:57 UTC to 2026-05-13 23:01 UTC

26 files changed +418 −150. View all changes and history on the product overview
2026
Sun 31 06:39 Sat 30 06:23 Fri 29 06:38 Thu 28 06:37 Wed 27 06:42 Tue 26 06:33 Sun 24 06:25 Sat 23 06:18 Fri 22 06:33 Thu 21 06:36 Wed 20 06:35 Tue 19 06:34 Mon 18 23:59 Sun 17 01:01 Fri 15 22:58 Thu 14 17:02 Wed 13 23:01 Tue 12 22:57 Mon 11 23:00 Sun 10 23:03 Sat 9 04:57 Fri 8 22:00 Thu 7 22:59 Tue 5 23:00 Mon 4 22:58 Sat 2 18:14 Fri 1 18:19

admin-setup.md +3 −1

Details

24 24 

25## API 제공자 선택25## API 제공자 선택

26 26 

27Claude Code는 여러 API 제공자 중 하나를 통해 Claude에 연결됩니다. 선택에 따라 청구, 인증 상속하는 규정 준수 태세가 결정됩니다.27Claude Code는 여러 API 제공자 중 하나를 통해 Claude에 연결됩니다. 선택에 따라 청구, 인증, 상속하는 규정 준수 태세 및 개발자가 사용할 수 있는 Claude Code 기능이 결정됩니다.

28 28 

29| 제공자 | 다음의 경우 선택 |29| 제공자 | 다음의 경우 선택 |

30| :---------------------------- | :------------------------------------------------------------------------ |30| :---------------------------- | :------------------------------------------------------------------------ |


34| Google Vertex AI | 기존 GCP 규정 준수 제어 및 청구를 상속하려는 경우 |34| Google Vertex AI | 기존 GCP 규정 준수 제어 및 청구를 상속하려는 경우 |

35| Microsoft Foundry | 기존 Azure 규정 준수 제어 및 청구를 상속하려는 경우 |35| Microsoft Foundry | 기존 Azure 규정 준수 제어 및 청구를 상속하려는 경우 |

36 36 

37일부 Claude Code 기능에는 Claude.ai 계정이 필요합니다. [Claude Code on the web](/ko/claude-code-on-the-web), [Routines](/ko/routines), [Code Review](/ko/code-review), [Remote Control](/ko/remote-control) 및 [Chrome extension](/ko/chrome)은 Console API 키 또는 클라우드 제공자 자격증명만으로는 사용할 수 없습니다. Bedrock, Vertex 또는 Foundry를 통해 배포하는 경우 개발자가 Claude for Teams 또는 Enterprise 시트도 필요한지 계획하세요. 각 기능 페이지에는 해당 플랜 요구사항이 나열되어 있습니다.

38 

37인증, 지역 및 기능 패리티를 다루는 전체 제공자 비교는 [enterprise deployment overview](/ko/third-party-integrations)를 참조하세요. 각 제공자의 인증 설정은 [Authentication](/ko/authentication)에 있습니다.39인증, 지역 및 기능 패리티를 다루는 전체 제공자 비교는 [enterprise deployment overview](/ko/third-party-integrations)를 참조하세요. 각 제공자의 인증 설정은 [Authentication](/ko/authentication)에 있습니다.

38 40 

39[Network configuration](/ko/network-config)의 프록시 및 방화벽 요구사항은 제공자와 관계없이 적용됩니다. 여러 제공자 앞에 단일 엔드포인트를 원하거나 중앙 집중식 요청 로깅을 원하는 경우 [LLM gateway](/ko/llm-gateway)를 참조하세요.41[Network configuration](/ko/network-config)의 프록시 및 방화벽 요구사항은 제공자와 관계없이 적용됩니다. 여러 제공자 앞에 단일 엔드포인트를 원하거나 중앙 집중식 요청 로깅을 원하는 경우 [LLM gateway](/ko/llm-gateway)를 참조하세요.

Details

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

69 69 

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

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

72| `"project"` | 프로젝트 CLAUDE.md, `.claude/rules/*.md`, 프로젝트 스킬, 프로젝트 훅, 프로젝트 `settings.json` | `<cwd>/.claude/` 및 파일시스템 루트까지의 상위 디렉토리(`.claude/`를 찾거나 이상 상위 디렉토리가 없을 중지) |72| `"project"` | 프로젝트 CLAUDE.md, `.claude/rules/*.md`, 프로젝트 스킬, 프로젝트 훅, 프로젝트 `settings.json` | `<cwd>/.claude/` (`settings.json` 훅의 경우); `<cwd>` 및 모든 상위 디렉토리(CLAUDE.md 규칙의 경우); `<cwd>` 저장소 루트까지의 모든 상위 디렉토리(스킬의 경우) |

73| `"user"` | 사용자 CLAUDE.md, `~/.claude/rules/*.md`, 사용자 스킬, 사용자 설정 | `~/.claude/` |73| `"user"` | 사용자 CLAUDE.md, `~/.claude/rules/*.md`, 사용자 스킬, 사용자 설정 | `~/.claude/` |

74| `"local"` | CLAUDE.local.md(gitignored), `.claude/settings.local.json` | `<cwd>/` |74| `"local"` | CLAUDE.local.md, `.claude/settings.local.json` | `<cwd>/.claude/` (`settings.local.json`의 경우); `<cwd>` 및 모든 상위 디렉토리(CLAUDE.local.md의 경우) |

75 75 

76`settingSources`를 생략하는 것은 `["user", "project", "local"]`과 동일합니다.76`settingSources`를 생략하는 것은 `["user", "project", "local"]`과 동일합니다.

77 77 

78`cwd` 옵션은 SDK가 프로젝트 설정을 찾는 위치를 결정합니다. `cwd` 또는 상위 디렉토리 어느 것도 `.claude/` 폴더를 포함하지 않으면 프로젝트 수준 기능이 로드되지 않습니다.78`cwd` 옵션은 SDK가 프로젝트 수준 입력을 찾는 위치를 결정합니다. CLAUDE.md와 규칙은 `<cwd>` 모든 상위 디렉토리에서 로드됩니다. 스킬은 `<cwd>`와 저장소 루트까지의 모든 상위 디렉토리에서 로드됩니다. 프로젝트 `settings.json`과 훅은 `<cwd>/.claude/`에서만 로드되며 상위 디렉토리 폴백이 없습니다.

79 79 

80### settingSources가 제어하지 않는 것80### settingSources가 제어하지 않는 것

81 81 


98### CLAUDE.md 로드 위치98### CLAUDE.md 로드 위치

99 99 

100| 수준 | 위치 | 로드 시기 |100| 수준 | 위치 | 로드 시기 |

101| :------------- | :--------------------------------------------- | :------------------------------------------------------------------ |101| :------------ | :------------------------------------------------------------ | :------------------------------------------------------------------ |

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

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

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

105| 프로젝트(하위 디렉토리) | `cwd`의 하위 디렉토리에 있는 `CLAUDE.md` 파일 | `settingSources`에 `"project"` 포함, 에이전트가 해당 서브트리의 파일을 읽을 때 필요에 따라 로드 |105| 프로젝트(하위 디렉토리) | `cwd`의 하위 디렉토리에 있는 `CLAUDE.md` 파일 | `settingSources`에 `"project"` 포함, 에이전트가 해당 서브트리의 파일을 읽을 때 필요에 따라 로드 |

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

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

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

109 109 

Details

108 108 

109#### 출력 스타일 생성109#### 출력 스타일 생성

110 110 

111출력 스타일은 프론트매터에 `name`과 `description`이 있는 마크다운 파일이며, 그 뒤에 프롬프트 내용이 있습니다. 모든 프로젝트에서 사용 가능한 사용자 수준 스타일의 경우 `~/.claude/output-styles/`에 저장하거나, 팀과 커밋하고 공유할 수 있는 프로젝트 수준 스타일의 경우 저장소의 `.claude/output-styles/`에 저장하십시오.111출력 스타일은 [frontmatter](/ko/output-styles#frontmatter)에 메타데이터가 있는 마크다운 파일이며, 그 뒤에 프롬프트 내용이 있습니다. 모든 프로젝트에서 사용 가능한 사용자 수준 스타일의 경우 `~/.claude/output-styles/`에 저장하거나, 팀과 커밋하고 공유할 수 있는 프로젝트 수준 스타일의 경우 저장소의 `.claude/output-styles/`에 저장하십시오.

112 112 

113아래 예제는 코드 리뷰 담당자 페르소나를 정의합니다. 프로젝트 전체에서 사용 가능하도록 `~/.claude/output-styles/code-reviewer.md` 저장하십시오:113기본적으로, 사용자 정의 출력 스타일은 `claude_code` 프리셋의 소프트웨어 엔지니어링 명령을 자신의 명령으로 바꿉니다. 이를 유지하고 명령을 위에 계층화하려면, frontmatter에서 `keep-coding-instructions: true` 설정하십시오. 에이전트가 여전히 소프트웨어 엔지니어링 작업을 수행할 때 이를 유지하십시오. 역할을 완전히 바꿀 때는 이를 제외하십시오.

114 

115아래 예제는 코딩 명령을 유지하는 코드 리뷰 담당자 페르소나를 정의합니다. 코드 리뷰는 Claude Code의 보안 및 코드 품질 지침의 이점을 여전히 얻기 때문입니다. 프로젝트 전체에서 사용 가능하도록 `~/.claude/output-styles/code-reviewer.md`로 저장하십시오:

114 116 

115```markdown ~/.claude/output-styles/code-reviewer.md theme={null}117```markdown ~/.claude/output-styles/code-reviewer.md theme={null}

116---118---

117name: Code Reviewer119name: Code Reviewer

118description: Thorough code review assistant120description: Thorough code review assistant

121keep-coding-instructions: true

119---122---

120 123 

121You are an expert code reviewer.124You are an expert code reviewer.


299네 가지 사용자 정의 방법은 위치, 공유 방식, `claude_code` 사전에서 보존되는 내용이 다릅니다.302네 가지 사용자 정의 방법은 위치, 공유 방식, `claude_code` 사전에서 보존되는 내용이 다릅니다.

300 303 

301| 기능 | CLAUDE.md | 출력 스타일 | `systemPrompt`과 함께 추가 | 사용자 정의 `systemPrompt` |304| 기능 | CLAUDE.md | 출력 스타일 | `systemPrompt`과 함께 추가 | 사용자 정의 `systemPrompt` |

302| ------------- | --------- | ----------- | --------------------- | --------------------- |305| ------------- | --------- | ------------- | --------------------- | --------------------- |

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

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

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

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

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

308| **환경 컨텍스트** | 자동 | 자동 | 자동 | 제공해야 함 |311| **환경 컨텍스트** | 자동 | 자동 | 자동 | 제공해야 함 |

309| **사용자 정의 수준** | 추가만 | 기본값 바꾸기 | 추가만 | 완전 제어 |312| **사용자 정의 수준** | 추가만 | 기본값 바꾸기 또는 확장 | 추가만 | 완전 제어 |

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

311| **범위** | 프로젝트별 | 사용자 또는 프로젝트 | 코드 세션 | 코드 세션 |314| **범위** | 프로젝트별 | 사용자 또는 프로젝트 | 코드 세션 | 코드 세션 |

312 315 

Details

7> Claude Code를 라이브러리로 사용하여 프로덕션 AI 에이전트 구축하기7> Claude Code를 라이브러리로 사용하여 프로덕션 AI 에이전트 구축하기

8 8 

9<Note>9<Note>

10 Claude Code SDK의 이름이 Claude Agent SDK로 변경되었습니다. 이전 SDK에서 마이그레이션하는 경우 [마이그레이션 가이드](/ko/agent-sdk/migration-guide) 참조하십시오.10 Starting June 15, 2026, Agent SDK and `claude -p` usage on subscription plans will draw from a new monthly Agent SDK credit, separate from your interactive usage limits. See [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) for details.

11</Note>11</Note>

12 12 

13자율적으로 파일을 읽고, 명령을 실행하고, 웹을 검색하고, 코드를 편집하는 등의 작업을 수행하는 AI 에이전트를 구축하십시오. Agent SDK는 Claude Code를 강화하는 동일한 도구, 에이전트 루프 및 컨텍스트 관리를 Python 및 TypeScript로 프로그래밍할 수 있도록 제공합니다.13자율적으로 파일을 읽고, 명령을 실행하고, 웹을 검색하고, 코드를 편집하는 등의 작업을 수행하는 AI 에이전트를 구축하십시오. Agent SDK는 Claude Code를 강화하는 동일한 도구, 에이전트 루프 및 컨텍스트 관리를 Python 및 TypeScript로 프로그래밍할 수 있도록 제공합니다.

14 14 

15<Note>

16 Opus 4.7(`claude-opus-4-7`)은 Agent SDK v0.2.111 이상이 필요합니다. `thinking.type.enabled` API 오류가 표시되면 [문제 해결](/ko/agent-sdk/quickstart#troubleshooting)을 참조하십시오.

17</Note>

18 

19<CodeGroup>15<CodeGroup>

20 ```python Python theme={null}16 ```python Python theme={null}

21 import asyncio17 import asyncio

Details

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

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

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

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

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

24 24 

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

26 26 

27<Note>27<Note>

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

29</Note>29</Note>

30 30 

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


253 253 

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

255 255 

256**작업 디렉토리 확인**: SDK는 `cwd` 옵션을 기준으로 Skills를 로드합니다. `.claude/skills/`를 포함하는 디렉토리를 가리키는지 확인하십시오:256**작업 디렉토리 확인**: SDK는 `cwd` 옵션의 `.claude/skills/` 및 저장소 루트까지의 모든 상위 디렉토리에서 Skills를 로드합니다. `cwd`가 `.claude/skills/`를 포함하는 디렉토리를 가리키거나 그 아래에 있으며, 동일한 저장소 내에 있는지 확인하십시오:

257 257 

258<CodeGroup>258<CodeGroup>

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

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

261 options = ClaudeAgentOptions(261 options = ClaudeAgentOptions(

262 cwd="/path/to/project", # Must contain .claude/skills/262 cwd="/path/to/project", # .claude/skills/ here or in a parent directory

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

264 skills="all",264 skills="all",

265 )265 )


268 ```typescript TypeScript theme={null}268 ```typescript TypeScript theme={null}

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

270 const options = {270 const options = {

271 cwd: "/path/to/project", // Must contain .claude/skills/271 cwd: "/path/to/project", // .claude/skills/ here or in a parent directory

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

273 skills: "all"273 skills: "all"

274 };274 };

Details

1841 1841 

1842진행 상황을 추적하기 위한 구조화된 작업 목록을 만들고 관리합니다.1842진행 상황을 추적하기 위한 구조화된 작업 목록을 만들고 관리합니다.

1843 1843 

1844<Note>

1845 `TodoWrite`는 더 이상 사용되지 않으며 향후 릴리스에서 제거될 예정입니다. 대신 `TaskCreate`, `TaskGet`, `TaskUpdate` 및 `TaskList`를 사용하세요. `CLAUDE_CODE_ENABLE_TASKS=1`을 설정하여 옵트인합니다. 코드 변경 모니터링 방법은 [작업 도구로 마이그레이션](/ko/agent-sdk/todo-tracking#migrate-to-task-tools)을 참조하세요.

1846</Note>

1847 

1848### TaskCreate

1849 

1850**도구 이름:** `TaskCreate`

1851 

1852```typescript theme={null}

1853// SDK에서 아직 내보내지지 않음; 로컬로 정의합니다.

1854type TaskCreateInput = {

1855 subject: string;

1856 description: string;

1857 activeForm?: string;

1858 metadata?: Record<string, unknown>;

1859};

1860```

1861 

1862단일 작업을 만들고 할당된 ID를 반환합니다.

1863 

1864### TaskUpdate

1865 

1866**도구 이름:** `TaskUpdate`

1867 

1868```typescript theme={null}

1869// SDK에서 아직 내보내지지 않음; 로컬로 정의합니다.

1870type TaskUpdateInput = {

1871 taskId: string;

1872 status?: "pending" | "in_progress" | "completed" | "deleted";

1873 subject?: string;

1874 description?: string;

1875 activeForm?: string;

1876 addBlocks?: string[];

1877 addBlockedBy?: string[];

1878 owner?: string;

1879 metadata?: Record<string, unknown>;

1880};

1881```

1882 

1883ID로 하나의 작업을 패치합니다. `status`를 `"deleted"`로 설정하여 제거합니다.

1884 

1885### TaskGet

1886 

1887**도구 이름:** `TaskGet`

1888 

1889```typescript theme={null}

1890// SDK에서 아직 내보내지지 않음; 로컬로 정의합니다.

1891type TaskGetInput = {

1892 taskId: string;

1893};

1894```

1895 

1896하나의 작업에 대한 전체 세부 정보를 반환하거나, ID를 찾을 수 없을 때 `null`을 반환합니다.

1897 

1898### TaskList

1899 

1900**도구 이름:** `TaskList`

1901 

1902```typescript theme={null}

1903// SDK에서 아직 내보내지지 않음; 로컬로 정의합니다.

1904type TaskListInput = {};

1905```

1906 

1907현재 목록의 모든 작업의 스냅샷을 반환합니다.

1908 

1844### ExitPlanMode1909### ExitPlanMode

1845 1910 

1846**도구 이름:** `ExitPlanMode`1911**도구 이름:** `ExitPlanMode`


2273 2338 

2274이전 및 업데이트된 작업 목록을 반환합니다.2339이전 및 업데이트된 작업 목록을 반환합니다.

2275 2340 

2341<Note>

2342 `TodoWrite`는 더 이상 사용되지 않으며 향후 릴리스에서 제거될 예정입니다. 대신 `TaskCreate`, `TaskGet`, `TaskUpdate`, `TaskList`를 사용하십시오. `CLAUDE_CODE_ENABLE_TASKS=1`을 설정하여 옵트인합니다. 코드 변경 모니터링 방법은 [작업 도구로 마이그레이션](/ko/agent-sdk/todo-tracking#migrate-to-task-tools)을 참조하십시오.

2343</Note>

2344 

2345### TaskCreate

2346 

2347**도구 이름:** `TaskCreate`

2348 

2349```typescript theme={null}

2350// Not yet exported from the SDK; define locally.

2351type TaskCreateOutput = {

2352 task: {

2353 id: string;

2354 subject: string;

2355 };

2356};

2357```

2358 

2359할당된 ID와 함께 생성된 작업을 반환합니다.

2360 

2361### TaskUpdate

2362 

2363**도구 이름:** `TaskUpdate`

2364 

2365```typescript theme={null}

2366// Not yet exported from the SDK; define locally.

2367type TaskUpdateOutput = {

2368 success: boolean;

2369 taskId: string;

2370 updatedFields: string[];

2371 error?: string;

2372 statusChange?: {

2373 from: string;

2374 to: string;

2375 };

2376};

2377```

2378 

2379업데이트 결과를 반환하며, 어떤 필드가 변경되었는지 포함합니다.

2380 

2381### TaskGet

2382 

2383**도구 이름:** `TaskGet`

2384 

2385```typescript theme={null}

2386// Not yet exported from the SDK; define locally.

2387type TaskGetOutput = {

2388 task: {

2389 id: string;

2390 subject: string;

2391 description: string;

2392 status: "pending" | "in_progress" | "completed";

2393 blocks: string[];

2394 blockedBy: string[];

2395 } | null;

2396};

2397```

2398 

2399전체 작업 레코드를 반환하거나, ID를 찾을 수 없을 때 `null`을 반환합니다.

2400 

2401### TaskList

2402 

2403**도구 이름:** `TaskList`

2404 

2405```typescript theme={null}

2406// Not yet exported from the SDK; define locally.

2407type TaskListOutput = {

2408 tasks: Array<{

2409 id: string;

2410 subject: string;

2411 status: "pending" | "in_progress" | "completed";

2412 owner?: string;

2413 blockedBy: string[];

2414 }>;

2415};

2416```

2417 

2418현재 목록의 모든 작업의 스냅샷을 반환합니다.

2419 

2276### ExitPlanMode2420### ExitPlanMode

2277 2421 

2278**도구 이름:** `ExitPlanMode`2422**도구 이름:** `ExitPlanMode`

agent-view.md +133 −55

Details

6 6 

7> 하나의 화면에서 많은 Claude Code 세션을 디스패치하고 관리합니다. 에이전트 뷰는 모든 세션이 무엇을 하고 있는지, 어떤 세션이 입력을 필요로 하는지 보여줍니다.7> 하나의 화면에서 많은 Claude Code 세션을 디스패치하고 관리합니다. 에이전트 뷰는 모든 세션이 무엇을 하고 있는지, 어떤 세션이 입력을 필요로 하는지 보여줍니다.

8 8 

9`claude agents`로 열 수 있는 에이전트 뷰는 모든 백그라운드 세션을 위한 하나의 화면입니다: 무엇이 실행 중인지, 무엇이 입력을 필요로 하는지, 무엇이 완료되었는지를 보여줍니다. 새로운 세션을 디스패치하고, 트랜스크립트를 스크롤하는 대신 한눈에 상태를 확인하고, 필요할 때만 개입합니다. 세션은 터미널이 연결되지 않은 상태에서도 백그라운드에서 계속 실행됩니다.9`claude agents`로 열 수 있는 에이전트 뷰는 모든 백그라운드 세션을 위한 하나의 화면입니다: 무엇이 실행 중인지, 무엇이 입력을 필요로 하는지, 무엇이 완료되었는지를 보여줍니다. 새로운 세션을 디스패치하고, 트랜스크립트를 스크롤하는 대신 한눈에 상태를 확인하고, 필요할 때만 개입합니다. 각 백그라운드 세션은 터미널이 연결되지 않은 상태에서도 계속 실행되는 완전한 Claude Code 대화이므로, 언제든지 열고, 답변하고, 떠날 수 있습니다.

10 10 

11버그 수정, 리퀘스트 검토, 로그 조사 Claude가 동시에 작업할 있는 여러 독립적인 작업이 있을 에이전트 뷰를 사용합니다. 문제를 함께 해결하고 싶을 때는 세션에 연결하고 Claude Code를 대화형으로 평소처럼 사용합니다.11<img src="https://mintcdn.com/claude-code/1B48Qz2Z9hac4SLG/images/agent-view-light.png?fit=max&auto=format&n=1B48Qz2Z9hac4SLG&q=85&s=7a186c96ed47d6700d084d77e786be65" className="dark:hidden" alt="터미널의 에이전트 뷰: 헤더는 Claude Code v2.1.140, 모델, 작업 디렉토리 요약 개수를 표시합니다. 세션은 입력 필요, 작업 중, 완료됨으로 그룹화되며, 하단에 디스패치 입력과 키보드 힌트의 바닥글이 있습니다." width="1772" height="780" data-path="images/agent-view-light.png" />

12 12 

13에이전트 뷰의 세션은 독립적으로 실행되며 사용자에게만 보고합니다. 서브에이전트, 에이전트 , 워크트리와 비교하려면 [병렬로 에이전트 실행](/ko/agents)을 참조하세요.13<img src="https://mintcdn.com/claude-code/1B48Qz2Z9hac4SLG/images/agent-view-dark.png?fit=max&auto=format&n=1B48Qz2Z9hac4SLG&q=85&s=a5bed7434bae368faea3a8f023b52aa2" className="hidden dark:block" alt="터미널의 에이전트 뷰: 헤더는 Claude Code v2.1.140, 모델, 작업 디렉토리 및 요약 개수를 표시합니다. 세션은 입력 필요, 작업 , 완료됨으로 그룹화되며, 하단에 디스패치 입력과 키보드 힌트의 바닥글이 있습니다." width="1772" height="780" data-path="images/agent-view-dark.png" />

14 

15Claude가 사용자의 감시 없이 작업할 수 있는 여러 독립적인 작업이 있을 때 에이전트 뷰를 사용합니다. 버그 수정, 풀 리퀘스트 검토, 불안정한 테스트 조사를 세 개의 행으로 디스패치하고, 다른 창에서 계속 작업하며, 행에 입력이 필요하거나 결과가 있음을 표시할 때 다시 확인합니다.

16 

17에이전트의 세션에서 더 직접적으로 작업하려면, 행에 연결하여 전체 대화에 진입합니다.

18 

19에이전트 뷰를 서브에이전트, 에이전트 팀 및 워크트리와 비교하려면 [병렬로 에이전트 실행](/ko/agents)을 참조하세요.

14 20 

15<Note>21<Note>

16 에이전트 뷰는 연구 미리보기이며 Claude Code v2.1.139 이상이 필요합니다. `claude --version`으로 버전을 확인합니다. 기능이 발전함에 따라 인터페이스와 키보드 단축키가 변경될 수 있으며, 관리자는 [`disableAgentView`](#how-background-sessions-are-hosted) 관리 설정으로 조직의 에이전트 뷰를 비활성화할 수 있습니다.22 에이전트 뷰는 연구 미리보기이며 Claude Code v2.1.139 이상이 필요합니다. `claude --version`으로 버전을 확인합니다. 기능이 발전함에 따라 인터페이스와 키보드 단축키가 변경될 수 있습니다.

17</Note>23</Note>

18 24 

19이 페이지에서 다루는 내용:25이 페이지에서 다루는 내용:

20 26 

21* [빠른 시작](#quick-start)27* [빠른 시작](#quick-start): Claude에게 백그라운드에서 작업할 작업을 제공하고, 확인하고, 필요할 때 개입합니다

22* [에이전트 뷰로 세션 모니터링](#monitor-sessions-with-agent-view), 상태 아이콘, 엿보기 및 답변, 연결, 구성 및 키보드 단축키 포함28* [에이전트 뷰로 세션 모니터링](#monitor-sessions-with-agent-view), 상태 아이콘, 엿보기 및 답변, 연결, 구성 및 키보드 단축키 포함

23* [새로운 에이전트 디스패치](#dispatch-new-agents), 에이전트 뷰에서, 세션 내에서, 또는 셸에서29* [에이전트 뷰에서 새로운 에이전트 디스패치](#dispatch-new-agents), 세션 내에서, 또는 셸에서

24* [셸에서 세션 관리](#manage-sessions-from-the-shell)30* [셸에서 세션 관리](#manage-sessions-from-the-shell)

25* [백그라운드 세션이 호스팅되는 방식](#how-background-sessions-are-hosted), 감독자 프로세스에 의해31* [백그라운드 세션이 호스팅되는 방식](#how-background-sessions-are-hosted), 감독자 프로세스에 의해

26 32 

27## 빠른 시작33## 빠른 시작

28 34 

29이 연습은 에이전트 뷰를 열고, 세션을 디스패치하고, 엿보기 패널에서 답변하고, 전체 대화를 위해 연결하는 방법을 보여줍니다.35이 연습은 핵심 에이전트 루프를 다룹니다: 작업을 디스패치하고, Claude가 작업하면서 행이 업데이트되는 것을 지켜보고, 엿보기로 확인하고 답변하고, 전체 대화를 위해 연결합니다. 디스패치한 세션은 에이전트 뷰를 닫은 후에도 계속 실행되므로, 언제든지 떠났다가 돌아올 수 있습니다.

30 36 

31<Steps>37<Steps>

32 <Step title="에이전트 뷰 열기">38 <Step title="에이전트 뷰 열기">


36 claude agents42 claude agents

37 ```43 ```

38 44 

39 에이전트 뷰가 하단의 입력과 세션이 시작되면서 채워지는 테이블과 함께 열립니다. 언제든지 `Esc`를 눌러 종료합니다. 세션은 계속 실행됩니다.45 에이전트 뷰가 하단의 입력과 세션이 시작되면서 채워지는 테이블과 함께 열립니다. 언제든지 `Esc`를 눌러 셸로 돌아갑니다. 세션은 떠나 있는 동안 계속 실행되며 다음에 에이전트 뷰를 열 때 다시 나타납니다.

40 </Step>46 </Step>

41 47 

42 <Step title="세션 디스패치">48 <Step title="세션 디스패치">

43 입력에 프롬프트를 입력하고 `Enter`를 누릅니다. 새로운 세션이 시작되고 작업 중인지, 입력을 기다리는지, 완료되었는지를 보여주는 행으로 나타납니다. 여러 세션을 병렬로 실행하려면 반복합니다. 세션은 구독 할당량을 독립적으로 사용하므로 번에 많은 세션을 디스패치하기 전에 [제한사항](#limitations) 참조하십시오.49 작업을 설명하는 프롬프트를 입력하고 `Enter`를 누릅니다. 새로운 백그라운드 세션이 해당 작업에서 시작되고 작업 중인지, 입력을 기다리는지, 완료되었는지를 보여주는 행으로 나타납니다. 새로운 세션은 에이전트 헤더에 표시된 모델과 해당 디렉토리에서 `claude`를 실행할 얻을 있는 동일한 [권한 모드](#permission-mode-and-settings) 사용합니다.

50 

51 여기에 입력하는 모든 프롬프트는 자신의 새로운 세션을 시작합니다. 다른 프롬프트를 입력하고 `Enter`를 누르면 첫 번째 세션에 후속 메시지를 보내는 대신 첫 번째 세션과 함께 두 번째 세션을 시작합니다. 이렇게 여러 세션을 병렬로 실행할 수 있습니다.

52 

53 각 세션은 구독 할당량을 독립적으로 사용하므로, 한 번에 많은 세션을 디스패치하기 전에 [제한사항](#limitations)을 참조하십시오.

44 </Step>54 </Step>

45 55 

46 <Step title="엿보기 및 답변">56 <Step title="엿보기 및 답변">

47 화살표 키로 행을 선택하고 `Space`를 눌러 세션이 무엇을 하고 있는지 또는 무엇이 필요한지 확인합니다. 답변을 입력하고 `Enter`를 눌러 에이전트 뷰를 떠나지 않고 전송합니다.57 화살표 키로 행을 선택하고 `Space`를 눌러 엿보기 패널을 엽니다. 전체 대화 기록이 아닌 세션의 가장 최근 출력 또는 기다리고 있는 질문을 표시합니다. 답변을 입력하고 `Enter`를 눌러 에이전트 뷰를 떠나지 않고 전송합니다.

48 </Step>58 </Step>

49 59 

50 <Step title="연결 및 분리">60 <Step title="연결 및 분리">

51 전체 대화를 원할 때 행에서 `Enter` 또는 `→`를 눌러 연결합니다. 세션이 `claude`를 실행한 것처럼 정확히 터미널을 인수합니다. 빈 프롬프트에서 `←`를 눌러 분리하고 테이블로 돌아갑니다.61 전체 대화를 원할 때 행에서 `Enter` 또는 `→`를 눌러 연결합니다. 세션이 `claude`를 실행한 것처럼 정확히 터미널을 인수합니다. 빈 프롬프트에서 `←`를 눌러 분리하고 테이블로 돌아갑니다.

52 </Step>62 </Step>

53</Steps>

54 63 

55기존 대화형 세션을 에이전트 뷰로 가져오려면 세션 내에서 `/bg`를 실행하거나, 빈 프롬프트에서 `←`를 눌러 세션을 백그라운드로 보내고 한 단계에서 에이전트 뷰를 엽니다. 세션은 백그라운드에서 계속 실행되고 행으로 나타납니다. 셸에서 직접 새로운 백그라운드 세션을 시작하려면 `claude --bg "<prompt>"`를 실행합니다.64 <Step title="기존 세션 가져오기">

65 이미 열려 있는 세션을 에이전트 뷰로 이동하려면 세션 내에서 `/bg`를 실행하거나, 빈 프롬프트에서 `←`를 눌러 세션을 백그라운드로 보내고 한 단계에서 에이전트 뷰를 엽니다. 세션은 계속 실행되며 디스패치한 세션과 함께 행으로 나타납니다.

66 </Step>

67</Steps>

56 68 

57`claude agents`를 `claude` 대신 기본 진입점으로 사용할 수 있습니다: 에이전트 뷰에서 모든 작업을 디스패치하고, 전체 대화를 원할 때 연결하고, `←`를 눌러 테이블로 돌아갑니다.69`claude agents`를 `claude` 대신 기본 진입점으로 사용할 수 있습니다: 에이전트 뷰에서 모든 작업을 디스패치하고, 전체 대화를 원할 때 연결하고, `←`를 눌러 테이블로 돌아갑니다.

58 70 


60 72 

61`claude agents`를 실행하여 에이전트 뷰를 엽니다. 전체 터미널을 차지하고 상태별로 그룹화된 모든 세션을 나열하며, 고정된 세션과 입력이 필요한 세션이 맨 위에 있습니다. 각 행은 세션의 이름, 현재 활동 및 마지막 변경 이후 경과 시간을 보여줍니다.73`claude agents`를 실행하여 에이전트 뷰를 엽니다. 전체 터미널을 차지하고 상태별로 그룹화된 모든 세션을 나열하며, 고정된 세션과 입력이 필요한 세션이 맨 위에 있습니다. 각 행은 세션의 이름, 현재 활동 및 마지막 변경 이후 경과 시간을 보여줍니다.

62 74 

63목록은 [config directory](#how-background-sessions-are-hosted)의 모든 백그라운드 세션을 포함하며, 작업 중인 프로젝트나 worktree에 관계없이 한 저장소에서 시작된 세션과 다른 worktree에서 시작된 세션이 함께 나타납니다. 다른 터미널에서 열려 있는 대화형 세션은 [백그라운드로 보낼](#from-inside-a-session) 때까지 나타나지 않으며, [서브에이전트](/ko/sub-agents) 별도의 행으로 나열되지 않습니다.75목록은 시작한 모든 백그라운드 세션을 표시하며, 모든 프로젝트에 걸쳐 있습니다. 한 저장소에서 작업하는 세션과 다른 worktree에서 작업하는 세션은 모두 여기에 나타나며, 에이전트 뷰를 연 디렉토리와 관계없이 표시됩니다. 다른 터미널에서 열려 있는 대화형 세션은 [백그라운드로 보낼](#from-inside-a-session) 때까지 나타나지 않습니다. [서브에이전트](/ko/sub-agents) [팀원](/ko/agent-teams)은 세션이 생성하는 별도의 행으로 나열되지 않습니다.

64 76 

65```text theme={null}77```text theme={null}

66고정됨78고정됨

67 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m79 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m

68 80 

69검토 준비 완료81검토 준비 완료

70 ∙ jump physics github.com/anthropics/example/pull/2048 ● 2h82 ∙ jump physics github.com/example/game/pull/2048 ● 2h

71 83 

72입력 필요84입력 필요

73 ✻ power-up design needs input: double jump or wall climb? 1m85 ✻ power-up design needs input: double jump or wall climb? 1m


82 … 6 more94 … 6 more

83```95```

84 96 

85각 행의 아이콘은 두 가지 신호를 전달합니다. 표시기는 세션의 상태를 나타내고, 아이콘의 모양은 기본 프로세스가 여전히 실행 중인지 여부를 나타냅니다. 상태는 다음과 같습니다:97### 세션 상태 읽기

98 

99각 행은 세션의 상태를 나타내는 아이콘으로 시작하며, 아이콘의 색상과 애니메이션이 상태를 보여줍니다:

100 

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

102| :---- | :----- | :---------------------------------- |

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

104| 입력 필요 | 노란색 | Claude가 특정 질문이나 권한 결정을 기다리는 중 |

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

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

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

108| 중지됨 | 회색 | 세션이 `Ctrl+X` 또는 `claude stop`으로 중지됨 |

86 109 

87| 표시기 | 상태 | 의미 |110별도로, 아이콘의 모양은 기본 프로세스가 실행 중인지 여부를 나타냅니다:

88| :---- | :---- | :---------------------------------- |

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

90| 노란색 | 입력 필요 | Claude가 입력을 기다리는 중, 보통 권한 결정 또는 답변 |

91| 흐릿함 | 유휴 | 세션이 입력을 기다리는 중이지만 특정 질문에 차단되지 않음 |

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

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

94| 회색 | 중지됨 | 세션이 `Ctrl+X` 또는 `claude stop`으로 중지됨 |

95 111 

96아이콘의 모양은 기본 프로세스가 여전히 실행 중인지 여부를 나타냅니다. `✻` 또는 Claude가 작업 중일 때 애니메이션 `✽`는 세션이 활성 상태이고 즉시 답변할 수 있음을 의미합니다. `∙`는 프로세스가 종료되었지만 여전히 엿보기, 답변 또는 연결할 수 있음을 의미합니다: Claude는 중단된 위치에서 세션을 다시 시작합니다. `✢`는 [`/loop`](/ko/commands) 세션이 반복 사이에 절전 중이며, 행은 실행 횟수와 다음 반복까지의 카운트다운을 보여줍니다.112| 모양 | 의미 |

113| :--------------- | :------------------------------------------------------------------ |

114| `✻` 또는 애니메이션 `✽` | 세션 프로세스가 활성 상태이며 즉시 응답 |

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

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

97 117 

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

99 119 

100세션은 디스크에 유지됩니다: 터미널을 닫거나 자동 업데이트가 발생해도 손실되지 않으며, `claude agents`를 다시 열면 모두 표시됩니다. 머신이 절전 상태이거나 종료되면 실행 중인 세션이 중지됩니다; `claude respawn --all`로 다시 시작합니다.120세션 상태는 자동 업데이트 감독자 재시작을 통해 디스크에 유지됩니다. 머신이 절전 상태이거나 종료되면 실행 중인 세션이 중지됩니다. `claude respawn --all`로 다시 시작합니다.

101 121 

102각 행의 한 줄 요약은 구성된 [Haiku 클래스 모델](/ko/model-config)에 의해 생성되므로 행은 세션이 무엇을 하고 있는지, 무엇이 필요한지, 또는 트랜스크립트를 열지 않고도 무엇을 생성했는지 알려줄 수 있습니다. 세션이 적극적으로 작동하는 동안 요약은 최대 15초마다 한 번, 그리고 각 턴이 끝날 때 한 번 새로고침됩니다. 각 새로고침은 일반 제공자를 통한 하나의 짧은 Haiku 클래스 요청이며, 세션 자체와 동일한 [데이터 사용 약관](/ko/data-usage)에 따라 청구되고 처리됩니다.122### 요약

123 

124각 행의 한 줄 요약은 [Haiku 클래스 모델](/ko/model-config)에 의해 생성되므로 행은 세션이 무엇을 하고 있는지, 무엇이 필요한지, 또는 트랜스크립트를 열지 않고도 무엇을 생성했는지 알려줄 수 있습니다. 세션이 적극적으로 작동하는 동안 요약은 최대 15초마다 한 번, 그리고 각 턴이 끝날 때 한 번 새로고침됩니다.

125 

126각 새로고침은 일반 제공자를 통한 하나의 짧은 Haiku 클래스 요청이며, 세션 자체와 동일한 [데이터 사용 약관](/ko/data-usage)에 따라 청구되고 처리됩니다.

127 

128### 풀 리퀘스트 상태

103 129 

104세션이 풀 리퀘스트를 열면 상태 점이 행의 오른쪽 가장자리에 나타나며, 하이퍼링크를 지원하는 터미널에서 풀 리퀘스트에 연결됩니다. 세션이 둘 이상의 풀 리퀘스트를 열었을 때 개수가 점 앞에 나타나고 색상은 가장 주의가 필요한 것을 반영합니다.130세션이 풀 리퀘스트를 열면 상태 점이 행의 오른쪽 가장자리에 나타나며, 하이퍼링크를 지원하는 터미널에서 풀 리퀘스트에 연결됩니다. 세션이 둘 이상의 풀 리퀘스트를 열었을 때 개수가 점 앞에 나타나고 색상은 가장 주의가 필요한 것을 반영합니다.

105 131 


122 148 

123### 세션에 연결149### 세션에 연결

124 150 

125선택된 행에서 `Enter` 또는 `→`를 눌러 연결하거나, `Alt+1`부터 `Alt+9`까지 눌러 포커스된 그룹의 N번째 세션에 직접 연결합니다. 에이전트 뷰는 `claude`를 실행한 것처럼 정확히 전체 대화형 세션으로 대체됩니다. 연결하면 Claude는 떠나 있는 동안 발생한 일에 대한 짧은 요약을 게시합니다.151선택된 행에서 `Enter` 또는 `→`를 눌러 연결합니다. 에이전트 뷰는 `claude`를 실행한 것처럼 정확히 전체 대화형 세션으로 대체됩니다. 연결하면 Claude는 떠나 있는 동안 발생한 일에 대한 짧은 요약을 게시합니다.

126 152 

127연결된 동안 세션은 다른 Claude Code 세션처럼 작동합니다: 모든 [명령](/ko/commands), 키보드 단축키 및 기능이 작동합니다.153연결된 동안 세션은 다른 Claude Code 세션처럼 작동합니다: 모든 [명령](/ko/commands), 키보드 단축키 및 기능이 작동합니다.

128 154 


134 160 

135### 목록 구성161### 목록 구성

136 162 

137에이전트 뷰는 상태별로 세션을 그룹화하며, 입력이 필요한 세션이 작업 중이거나 완료된 세션 위에 있습니다. `Ctrl+S` 눌러 대신 디렉토리별로 그룹화로 전환합니다. 선택 사항은 실행 간에 저장됩니다. 그룹 내에서 `Ctrl+T`로 세션을 위에 고정하고, `Shift+↑` `Shift+↓`로 순서를 변경하거나, 그룹 헤더에서 `Enter`를 눌러 축소합니다. 세션을 제거하려면 `Ctrl+X`를 눌러 중지하고 2초 이내에 `Ctrl+X`를 다시 눌러 삭제합니다. 그룹 헤더에서 `Ctrl+X`를 누르면 확인 해당 그룹의 모든 세션이 삭제됩니다.163에이전트 뷰는 세션을 그룹화하여 입력이 필요한 세션이 위에 있고, `검토 준비 완료`와 `입력 필요` `작업 중`과 `완료됨` 위에 있습니다. 그룹 이름은 [상태](#read-session-state) 위의 일대일 매핑이 아닙니다: 세션이 열린 리퀘스트를 가지면 `검토 준비 완료`로 이동하고, `완료됨` 완료되고, 실패하고, 중지된 세션을 함께 수집합니다. `Ctrl+S`를 눌러 대신 디렉토리별로 그룹화로 전환합니다. 선택 사항은 실행 간에 저장됩니다.

164 

165그룹 내에서:

166 

167* `Ctrl+T`를 눌러 세션을 맨 위에 고정

168* `Shift+↑` 또는 `Shift+↓`를 눌러 세션 순서 변경

169* `Ctrl+R`을 눌러 세션 이름 바꾸기

170* 그룹 헤더에서 `Enter`를 눌러 축소

138 171 

139오래된 완료된 세션은 목록을 짧게 유지하기 위해 "… N more" 행으로 접힙니다. 실패 열린 리퀘스트가 있는 세션은 항상 표시됩니다.172세션을 목록에서 제거하려면 `Ctrl+X`를 눌러 중지하고 2초 이내에 `Ctrl+X`를 다시 눌러 삭제합니다. 그룹 헤더에서 `Ctrl+X`를 누르면 확인 해당 그룹의 모든 세션이 삭제됩니다.

140 173 

141### 목록 필터링174삭제하면 세션이 에이전트 뷰에서 제거되고 [worktree](#how-file-edits-are-isolated)를 정리하며, 커밋되지 않은 변경 사항을 포함합니다. 따라서 삭제하기 전에 유지하려는 작업을 푸시하거나 커밋합니다. 대화 트랜스크립트는 디스크에 남아 있으며 `claude --resume`을 통해 사용 가능합니다.

175 

176오래된 완료된 세션은 목록을 짧게 유지하기 위해 `… N more` 행으로 접힙니다. 실패 및 열린 풀 리퀘스트가 있는 세션은 항상 표시됩니다.

177 

178### 세션 필터링

142 179 

143디스패치 입력에 입력하여 디스패치 대신 필터링합니다:180디스패치 입력에 입력하여 디스패치 대신 필터링합니다:

144 181 

145| 필터 | 표시 |182| 필터 | 표시 |

146| :-------------------- | :-------------------------------------- |183| :-------------------- | :------------------------------------------------------------- |

147| `a:<name>` | 명명된 에이전트를 실행하는 세션 |184| `a:<name>` | 명명된 에이전트를 실행하는 세션 |

148| `s:<state>` | 주어진 상태의 세션, 예: `s:blocked` (입력이 필요한 세션) |185| `s:<state>` | 주어진 상태의 세션, 예: `s:working`. 또한 `s:blocked` 수락하여 입력을 기다리는 모든 것 |

149| `#<number>` 또는 PR URL | 해당 풀 리퀘스트에서 작업하는 세션 |186| `#<number>` 또는 PR URL | 해당 풀 리퀘스트에서 작업하는 세션 |

150 187 

151### 키보드 단축키188### 키보드 단축키

152 189 

153에이전트 뷰에서 `?`를 눌러 모든 단축키를 확인합니다. 가장 일반적인 것들:190에이전트 뷰에서 `?`를 눌러 모든 단축키를 확인합니다. 아래 표는 이를 요약합니다.

154 191 

155| 단축키 | 작업 |192| 단축키 | 작업 |

156| :-------------------- | :------------------------------- |193| :-------------------- | :----------------------------------- |

157| `↑` / `↓` | 행 간 이동 |194| `↑` / `↓` | 행 간 이동 |

158| `Enter` | 선택된 세션에 연결하거나, 입력에 텍스트가 있으면 디스패치 |195| `Enter` | 선택된 세션에 연결하거나, 입력에 텍스트가 있으면 디스패치 |

159| `Space` | 선택된 세션의 엿보기 패널 열기 또는 닫기 |196| `Space` | 선택된 세션의 엿보기 패널 열기 또는 닫기 |

160| `Shift+Enter` | 디스패치하고 즉시 연결 |197| `Shift+Enter` | 디스패치하고 즉시 연결 |

161| `→` | 선택된 세션에 연결 |198| `→` | 선택된 세션에 연결 |

162| `Alt+1`..`Alt+9` | 포커스된 그룹의 N번째 세션에 연결 |199| `Alt+1`..`Alt+9` | 현재 그룹의 세션 1–9에 연결 |

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

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

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

166| `Ctrl+R` | 선택된 세션 이름 바꾸기 |203| `Ctrl+R` | 선택된 세션 이름 바꾸기 |


177 214 

178### 에이전트 뷰에서215### 에이전트 뷰에서

179 216 

180에이전트 뷰 하단의 입력에 프롬프트를 입력하고 `Enter`를 눌러 새로운 백그라운드 세션을 시작합니다. 세션은 프롬프트에서 자동으로 이름이 지정됩니다. 나중에 `Ctrl+R`로 이름을 바꿀 수 있습니다. 이미지를 프롬프트에 붙여넣어 작업에 스크린샷이나 다이어그램을 포함합니다.217에이전트 뷰 하단의 입력에 프롬프트를 입력하고 `Enter`를 눌러 새로운 백그라운드 세션을 시작합니다. 세션은 프롬프트에서 자동으로 이름이 지정됩니다. 나중에 `Ctrl+R`로 이름을 바꿀 수 있습니다.

218 

219프롬프트에 이미지를 붙여넣어 작업에 스크린샷이나 다이어그램을 포함합니다.

181 220 

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

183 222 


190| `#<number>` 또는 풀 리퀘스트 URL | 세션이 이미 해당 PR에서 작업 중이면 디스패치 대신 선택 |229| `#<number>` 또는 풀 리퀘스트 URL | 세션이 이미 해당 PR에서 작업 중이면 디스패치 대신 선택 |

191| `Shift+Enter` | 디스패치하고 즉시 새 세션에 연결 |230| `Shift+Enter` | 디스패치하고 즉시 새 세션에 연결 |

192 231 

193`/`를 입력하여 [스킬](/ko/skills)을 디스패치합니다. 반복되는 작업을 스킬로 패키징하면 프롬프트를 다시 입력하지 않고 에이전트 뷰에서 동일한 워크플로우를 여러 번 시작할 수 있습니다. 빈 입력에서 `Tab`을 눌러 모든 디스패치 가능한 서브에이전트를 검색하거나, 제안이 표시될 때 강조된 제안을 적용합니다.232반복되는 작업을 [스킬](/ko/skills) 패키징하면 프롬프트를 다시 입력하지 않고 에이전트 뷰에서 동일한 워크플로우를 여러 번 시작할 수 있습니다.

194 233 

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

196 235 

197#### 특정 디렉토리로 디스패치236#### 특정 디렉토리로 디스패치

198 237 


206 245 

207### 세션 내에서246### 세션 내에서

208 247 

209`/background` 또는 별칭 `/bg`를 실행하여 현재 대화를 분리하고 계속 실행합니다. `/bg run the test suite and fix any failures`와 같은 프롬프트를 전달하여 분리하기 전에 하나의 추가 명령을 보냅니다.248`/background` 또는 별칭 `/bg`를 실행하여 현재 대화를 백그라운드 세션으로 이동합니다. `/bg run the test suite and fix any failures`와 같은 프롬프트를 전달하여 먼저 하나의 추가 명령을 보냅니다.

249 

250대화형 세션에서 백그라운드로 이동하면 저장된 대화에서 재개되는 새로운 프로세스가 시작되므로 서브에이전트, [모니터](/ko/tools-reference#monitor-tool) 및 백그라운드 명령을 실행하는 것이 이동되지 않습니다. Claude는 실행 중인 것이 있을 때 백그라운드로 이동하기 전에 확인을 요청합니다. 백그라운드에 있으면 세션은 새로운 서브에이전트, 모니터 및 백그라운드 명령을 시작할 수 있으며, 이들은 나중의 분리 및 재연결 전체에서 계속 실행됩니다.

210 251 

211### 셸에서252### 셸에서

212 253 


234 275 

235### 파일 편집이 격리되는 방식276### 파일 편집이 격리되는 방식

236 277 

237에이전트 뷰, `/bg` 또는 `claude --bg`에서 시작된 모든 백그라운드 세션은 작업 디렉토리에서 시작되지만 거기에 파일을 쓰는 것이 차단됩니다. 세션이 파일을 편집해야 할 Claude는 자동으로 이를 `.claude/worktrees/` 아래의 격리된 [git worktree](/ko/worktrees)로 이동하므로 병렬 세션은 동일한 체크아웃을 읽을 수 있지만 각각은 자신의 것에 씁니다. 세션이 이미 워크트리 내에 있을 때, 작업 디렉토리가 git 저장소가 아닐 때, 또는 작업 디렉토리 외부에 쓸 때는 차단이 적용되지 않습니다.278에이전트 뷰, `/bg` 또는 `claude --bg`에서 시작된 모든 백그라운드 세션은 작업 디렉토리에서 시작됩니다. 파일을 편집하기 전에 Claude는 세션을 `.claude/worktrees/` 아래의 격리된 [git worktree](/ko/worktrees)로 이동하므로 병렬 세션은 동일한 체크아웃을 읽을 수 있지만 각각은 자신의 것에 씁니다. Claude는 세션이 이미 `.claude/worktrees/` 아래에 있을 때, 작업 디렉토리가 git 저장소가 아닐 때, 또는 작업 디렉토리 외부에 쓸 때는 이를 건너뜁니다.

279 

280git 저장소 외부에서 세션은 작업 디렉토리에 직접 쓰며 서로 격리되지 않으므로 동일한 파일을 편집하는 병렬 세션을 디스패치하지 않도록 합니다.

238 281 

239워크트리는 세션을 삭제할 때 제거되므로 삭제하기 전에 유지하려는 변경 사항을 병합하거나 푸시합니다. 세션의 워크트리 경로를 찾으려면 세션을 엿보거나 연결하고 작업 디렉토리를 확인합니다.282워크트리는 세션을 삭제할 때 제거되므로 삭제하기 전에 유지하려는 변경 사항을 병합하거나 푸시합니다. 세션의 워크트리 경로를 찾으려면 세션을 엿보거나 연결하고 작업 디렉토리를 확인합니다.

240 283 

241서브에이전트가 시작된 방식에 관계없이 항상 자체 워크트리에서 실행되도록 하려면 프론트매터에서 [`isolation: worktree`](/ko/sub-agents#supported-frontmatter-fields)를 설정합니다.284서브에이전트가 시작된 방식에 관계없이 항상 자체 워크트리에서 실행되도록 하려면 프론트매터에서 [`isolation: worktree`](/ko/sub-agents#supported-frontmatter-fields)를 설정합니다.

242 285 

286### 모델 설정

287 

288에이전트 뷰 헤더에 표시된 모델 이름은 디스패치 기본값입니다. 입력에서 시작하는 새로운 세션은 이 모델을 사용하며, 이는 모든 세션에서 [`/model`](/ko/model-config)이 제어하는 것과 동일한 설정입니다.

289 

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

291 

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

293* 실행 중인 세션에 연결하고 거기서 `/model`을 실행합니다. 세션이 다시 생성되면 변경 사항이 유지됩니다.

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

295 

243### 권한 모드 및 설정296### 권한 모드 및 설정

244 297 

245디스패치된 세션은 실행되는 디렉토리에서 [설정](/ko/settings) 및 [권한 모드](/ko/permissions)를 읽으며, 마치 거기서 `claude`를 시작한 것처럼 동일합니다. 에이전트 뷰 입력에서 디스패치하면 권한 모드를 전달하지 않으므로 세션은 해당 디렉토리의 설정에서 `defaultMode`를 사용하거나 디스패치된 [서브에이전트의 프론트매터](/ko/sub-agents#supported-frontmatter-fields)에서 `permissionMode`를 사용합니다.298디스패치된 세션은 실행되는 디렉토리에서 [설정](/ko/settings) 및 [권한 모드](/ko/permissions)를 읽으며, 마치 거기서 `claude`를 시작한 것처럼 동일합니다. 에이전트 뷰 입력에서 디스패치하면 권한 모드를 전달하지 않으므로 세션은 해당 디렉토리의 설정에서 `defaultMode`를 사용하거나 디스패치된 [서브에이전트의 프론트매터](/ko/sub-agents#supported-frontmatter-fields)에서 `permissionMode`를 사용합니다.


248 301 

249## 셸에서 세션 관리302## 셸에서 세션 관리

250 303 

251모든 백그라운드 세션에는 셸에서 사용할 수 있는 짧은 ID가 있습니다. 이 명령은 스크립팅이나 에이전트 뷰를 열고 싶지 않을 때 유용합니다.304모든 백그라운드 세션에는 셸에서 사용할 수 있는 짧은 ID가 있습니다. ID는 `claude --bg`로 세션을 시작할 때 출력되며, 각 세션의 ID는 `~/.claude/jobs/` 아래의 디렉터리 이름입니다. 이 명령은 스크립팅이나 에이전트 뷰를 열고 싶지 않을 때 유용합니다.

252 305 

253| 명령 | 목적 |306| 명령 | 목적 |

254| :--------------------- | :----------------------- |307| :--------------------- | :----------------------------------------- |

255| `claude agents` | 에이전트 뷰 열기 |308| `claude agents` | 에이전트 뷰 열기 |

256| `claude attach <id>` | 이 터미널에서 세션에 연결 |309| `claude attach <id>` | 이 터미널에서 세션에 연결 |

257| `claude logs <id>` | 세션의 최근 출력 인쇄 |310| `claude logs <id>` | 세션의 최근 출력 인쇄 |

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

259| `claude respawn <id>` | 대화를 유지하면서 중지된 세션 다시 시작 |312| `claude respawn <id>` | 대화를 유지하면서 중지된 세션 다시 시작 |

260| `claude respawn --all` | 모든 중지된 세션 다시 시작 |313| `claude respawn --all` | 모든 중지된 세션 다시 시작 |

261| `claude rm <id>` | 목록에서 세션 제거 |314| `claude rm <id>` | 목록에서 세션 제거. 커밋되지 않은 변경 사항이 없으면 worktree 정리 |

262 315 

263## 백그라운드 세션이 호스팅되는 방식316## 백그라운드 세션이 호스팅되는 방식

264 317 

265백그라운드 세션은 터미널 및 에이전트 뷰와 별도의 사용자별 감독자 프로세스에 의해 호스팅됩니다. 세션을 백그라운드로 보내거나 에이전트 뷰를 자동으로 시작되며 직접 관리하지 않습니다. 감독자 세션은 대화형 세션과 동일한 자격 증명으로 인증하고 모델 API 이상의 추가 네트워크 연결을 하지 않습니다.318에이전트 뷰에 나열된 모든 세션은 현재 연결되어 있는지 여부와 관계없이 백그라운드 세션으로 간주됩니다. 반대로 `claude`를 직접 실행하여 시작한 세션은 해당 터미널에 연결되어 있으며 [백그라운드로 보내지](#from-inside-a-session) 않는 터미널이 닫힐 종료됩니다.

319 

320### 감독자 프로세스

321 

322백그라운드 세션은 터미널 및 에이전트 뷰와 별도의 사용자별 감독자 프로세스에 의해 호스팅됩니다. 감독자는 세션을 백그라운드로 보내거나 에이전트 뷰를 열 때 자동으로 시작되며 직접 관리하지 않습니다.

323 

324감독자 및 세션은 대화형 세션과 동일한 자격 증명으로 인증하고 모델 API 이상의 추가 네트워크 연결을 하지 않습니다.

325 

326각 백그라운드 세션은 자체 Claude Code 프로세스이며 터미널이 아닌 감독자에 의해 관리됩니다. 적극적으로 작업 중이거나, 입력을 기다리거나, 터미널이 연결된 세션은 프로세스를 실행 상태로 유지합니다.

266 327 

267각 백그라운드 세션은 자체 Claude Code 프로세스이며 터미널이 아닌 감독자에게 부모입니다. 적극적으로 작업 중이거나, 입력을 기다리거나, 터미널이 연결된 세션은 프로세스를 실행 상태로 유지합니다. 세션이 완료되고 약 1시간 동안 연결되지 않은 상태로 있으면 감독자는 리소스를 확보하기 위해 프로세스를 중지합니다. 트랜스크립트와 상태는 디스크에 유지되며, 다음에 연결하거나, 엿보거나, 답변할 때 감독자는 중단된 위치에서 새로운 프로세스를 시작합니다. 모든 세션이 완료되고 터미널이 연결되지 않으면 감독자 자체가 종료되고 세션을 백그라운드로 보내거나 에이전트 뷰를 때 다시 시작됩니다.328세션이 완료되고 약 1시간 동안 연결되지 않은 상태로 있으면 감독자는 리소스를 확보하기 위해 프로세스를 중지합니다. 트랜스크립트와 상태는 디스크에 유지되며, 다음에 연결하거나, 엿보거나, 답변할 때 감독자는 중단된 위치에서 새로운 프로세스를 시작합니다. 모든 세션이 완료되고 터미널이 연결되지 않으면 감독자 자체가 종료되고 다음에 필요할 때 다시 시작됩니다.

268 329 

269감독자는 디스크에 설치된 Claude Code 바이너리를 감시하고 일반 [자동 업데이터](/ko/setup#auto-updates)가 교체한 후 새 버전으로 다시 시작합니다. 이는 네트워크 검사가 아닌 로컬 파일 감시입니다. 백그라운드 세션은 분리된 프로세스이므로 다시 시작을 통해 계속 실행되고 새 감독자는 다시 연결됩니다.330감독자는 디스크에 설치된 Claude Code 바이너리를 감시하고 일반 [자동 업데이터](/ko/setup#auto-updates)가 교체한 후 새 버전으로 다시 시작합니다. 이는 네트워크 검사가 아닌 로컬 파일 감시입니다. 백그라운드 세션은 분리된 프로세스이므로 다시 시작을 통해 계속 실행되고 새 감독자는 다시 연결됩니다.

270 331 

332### 상태가 저장되는 위치

333 

271세션 상태는 Claude Code 구성 디렉토리 아래에 저장됩니다. [`CLAUDE_CONFIG_DIR`](/ko/env-vars)을 설정하면 감독자는 `~/.claude` 대신 해당 디렉토리를 사용하고 자체 세션이 있는 별도의 인스턴스로 실행됩니다.334세션 상태는 Claude Code 구성 디렉토리 아래에 저장됩니다. [`CLAUDE_CONFIG_DIR`](/ko/env-vars)을 설정하면 감독자는 `~/.claude` 대신 해당 디렉토리를 사용하고 자체 세션이 있는 별도의 인스턴스로 실행됩니다.

272 335 

273| 경로 | 내용 |336| 경로 | 내용 |


276| `~/.claude/daemon/roster.json` | 실행 중인 백그라운드 세션 목록, 다시 시작 후 다시 연결하는 데 사용됨 |339| `~/.claude/daemon/roster.json` | 실행 중인 백그라운드 세션 목록, 다시 시작 후 다시 연결하는 데 사용됨 |

277| `~/.claude/jobs/<id>/state.json` | 에이전트 뷰에 표시되는 세션별 상태 |340| `~/.claude/jobs/<id>/state.json` | 에이전트 뷰에 표시되는 세션별 상태 |

278 341 

342### 에이전트 뷰 끄기

343 

279백그라운드 에이전트 및 에이전트 뷰를 완전히 끄려면 `disableAgentView` [설정](/ko/settings)을 `true`로 설정하거나 `CLAUDE_CODE_DISABLE_AGENT_VIEW` 환경 변수를 설정합니다. 관리자는 [관리 설정](/ko/permissions#managed-settings)을 통해 이를 적용할 수 있습니다.344백그라운드 에이전트 및 에이전트 뷰를 완전히 끄려면 `disableAgentView` [설정](/ko/settings)을 `true`로 설정하거나 `CLAUDE_CODE_DISABLE_AGENT_VIEW` 환경 변수를 설정합니다. 관리자는 [관리 설정](/ko/permissions#managed-settings)을 통해 이를 적용할 수 있습니다.

280 345 

281## 문제 해결346## 문제 해결

282 347 

348### `claude agents`가 에이전트 뷰를 열지 않고 서브에이전트를 나열함

349 

350`claude agents`가 개수를 출력한 후 구성된 서브에이전트를 나열하고 종료되면, 에이전트 뷰를 사용할 수 없는 환경입니다. 이전 버전은 Bedrock, Vertex AI 또는 Foundry를 통해 연결된 경우를 포함하여 모든 환경에서 에이전트 뷰를 열지 않았습니다. `claude update`를 실행하여 최신 버전을 설치합니다.

351 

352업데이트 후에도 에이전트 뷰가 열리지 않으면, 설정 또는 환경 변수에 의해 [꺼져 있는지](#turn-off-agent-view) 확인합니다.

353 

283### 에이전트 뷰가 세션 없이 열림354### 에이전트 뷰가 세션 없이 열림

284 355 

285에이전트 뷰는 첫 번째 세션을 디스패치할 때까지 비어 있습니다. 하단의 입력에 프롬프트를 입력하고 `Enter`를 누릅니다.356에이전트 뷰는 첫 번째 세션을 디스패치할 때까지 비어 있습니다. 하단의 입력에 프롬프트를 입력하고 `Enter`를 누릅니다.

286 357 

358### 백그라운드 작업이 실행 중이어서 에이전트를 열 수 없음

359 

360`←`를 눌러 현재 세션을 백그라운드로 전환할 때 `Cannot open agents — N background task(s) running`이 표시되면, 세션에 서브에이전트, 워크플로우 또는 백그라운드 셸 명령과 같은 진행 중인 작업이 있으며, 바로가기는 이를 자동으로 중단하지 않습니다. `/tasks`를 실행하여 실행 중인 작업을 확인한 후 `/bg`를 실행하여 중단을 확인합니다. 백그라운드할 때 전송되는 항목과 전송되지 않는 항목에 대해서는 [세션 내에서](#from-inside-a-session)를 참조합니다.

361 

362### 프롬프트가 너무 짧아서 거부됨

363 

364디스패치 입력은 대화형 오프닝이 아닌 작업 설명을 예상합니다. 4자 미만의 프롬프트는 `Too short` 힌트와 함께 거부되므로 실수로 누른 키가 세션을 시작하지 않습니다. 세션이 수행할 작업을 설명합니다. 예를 들어 `investigate the flaky checkout test`와 같이 설명합니다.

365 

287### 머신을 깨운 후 세션이 중지됨으로 표시됨366### 머신을 깨운 후 세션이 중지됨으로 표시됨

288 367 

289백그라운드 세션은 절전 또는 종료를 견디지 못합니다. 중지된 세션에 연결하거나, 엿보거나, 답변하면 중단된 위치에서 다시 시작됩니다. 모두 한 번에 다시 시작하려면 `claude respawn --all`을 실행합니다.368백그라운드 세션은 절전 또는 종료를 견디지 못하므로, 실행 중이던 세션은 깨어난 후 중지됨으로 표시됩니다. 이들 하나에 연결하거나, 엿보거나, 답변하면 세션이 중단된 위치에서 다시 시작됩니다. 모두 한 번에 다시 시작하려면 `claude respawn --all`을 실행합니다.

290 369 

291### 세션이 연결 후 응답이 느림370### 세션이 연결 후 응답이 느림

292 371 


298 377 

299## 제한 사항378## 제한 사항

300 379 

301에이전트 뷰는 연구 미리보기입니다. 주의할 현재 제한 사항:380에이전트 뷰는 연구 미리보기 상태이며 다음과 같은 제한 사항이 있습니다:

302 381 

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

304* **세션은 로컬**: 백그라운드 세션은 머신에서 실행되고 절전 또는 종료 중지됩니다.383* **세션은 로컬입니다**: 백그라운드 세션은 사용자의 머신에서 실행되며 머신이 절전 모드로 전환되거나 종료되면 중지됩니다.

305* **워크트리는 세션과 함께 삭제됨**: 자체 워크트리에서 파일을 편집한 세션을 삭제하기 전에 변경 사항을 병합하거나 푸시합니다.384* **워크트리는 세션과 함께 삭제됩니다**: 자체 워크트리에서 파일을 편집한 세션을 삭제하기 전에 변경 사항을 병합하거나 푸시합니다.

306 385 

307## 다음 단계386## 관련 리소스

308 387 

309에이전트 뷰를 이해했으므로 이러한 관련 기능을 살펴봅니다:388Claude를 병렬로 실행하는 다른 방법은 다음을 참조하십시오:

310 389 

311* [에이전트를 병렬로 실행](/ko/agents): 에이전트 뷰를 서브에이전트, 에이전트 팀 및 워크트리와 비교합니다390* [에이전트를 병렬로 실행](/ko/agents): 에이전트 뷰를 서브에이전트, 에이전트 팀 및 워크트리와 비교합니다

312* [서브에이전트](/ko/sub-agents): 사용자 정의 프롬프트, 도구 및 격리를 사용하여 재사용 가능한 에이전트 구성을 정의합니다

313* [에이전트 팀](/ko/agent-teams): 서로 메시지를 주고받는 여러 세션을 조정합니다391* [에이전트 팀](/ko/agent-teams): 서로 메시지를 주고받는 여러 세션을 조정합니다

314* [웹의 Claude Code](/ko/claude-code-on-the-web): 로컬 대신 관리되는 클라우드 환경에서 세션을 실행합니다392* [웹의 Claude Code](/ko/claude-code-on-the-web): 로컬 대신 관리되는 클라우드 환경에서 세션을 실행합니다

Details

143 143 

144### 장기 토큰 생성144### 장기 토큰 생성

145 145 

146<Note>

147 Starting June 15, 2026, Agent SDK and `claude -p` usage on subscription plans will draw from a new monthly Agent SDK credit, separate from your interactive usage limits. See [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) for details.

148</Note>

149 

146CI 파이프라인, 스크립트 또는 대화형 브라우저 로그인을 사용할 수 없는 기타 환경의 경우 `claude setup-token`으로 1년 OAuth 토큰을 생성합니다:150CI 파이프라인, 스크립트 또는 대화형 브라우저 로그인을 사용할 수 없는 기타 환경의 경우 `claude setup-token`으로 1년 OAuth 토큰을 생성합니다:

147 151 

148```bash theme={null}152```bash theme={null}

Details

33클라우드 세션은 코드를 복제하고 분기를 푸시하기 위해 GitHub 저장소에 액세스해야 합니다. 두 가지 방법으로 액세스 권한을 부여할 수 있습니다:33클라우드 세션은 코드를 복제하고 분기를 푸시하기 위해 GitHub 저장소에 액세스해야 합니다. 두 가지 방법으로 액세스 권한을 부여할 수 있습니다:

34 34 

35| 방법 | 작동 방식 | 최적 대상 |35| 방법 | 작동 방식 | 최적 대상 |

36| :--------------- | :----------------------------------------------------------------------------------------- | :------------------- |36| :--------------- | :---------------------------------------------------------- | :------------------------------------------------ |

37| **GitHub App** | [웹 온보딩](/ko/web-quickstart) 중에 특정 저장소에 Claude GitHub App을 설치합니다. 액세스는 저장소별로 범위가 지정됩니다. | 저장소별 명시적 인증을 원하는 팀 |37| **GitHub App** | [웹 온보딩](/ko/web-quickstart) 중에 Claude GitHub App을 승인합니다. | 브라우저 온보딩; [자동 수정](#auto-fix-pull-requests)을 원하는 팀 |

38| **`/web-setup`** | 터미널에서 `/web-setup`을 실행하여 로컬 `gh` CLI 토큰을 Claude 계정과 동기화합니다. 액세스는 `gh` 토큰이 볼 수 있는 것과 일치합니다. | 이미 `gh`를 사용하는 개별 개발자 |38| **`/web-setup`** | 터미널에서 `/web-setup`을 실행하여 로컬 `gh` CLI 토큰을 Claude 계정과 동기화합니다. | 이미 `gh`를 사용하는 개별 개발자 |

39 

40<Note>

41 두 방법 모두에서 클라우드 세션은 Claude GitHub App이 설치된 저장소뿐만 아니라 연결된 GitHub 계정이 볼 수 있는 모든 저장소에 액세스할 수 있습니다. App 설치는 [자동 수정](#auto-fix-pull-requests)을 위한 PR 웹훅을 활성화합니다. 이는 세션 수준의 액세스 제어가 아닙니다. 클라우드 세션에서 팀이 도달할 수 있는 저장소를 제한하려면 GitHub 자체에서 액세스를 제한하세요. 예를 들어 연결된 GitHub 계정의 팀 또는 저장소 멤버십을 제한하면 됩니다.

42</Note>

39 43 

40두 방법 모두 작동합니다. [`/schedule`](/ko/routines)은 두 형태의 액세스를 확인하고 구성되지 않은 경우 `/web-setup`을 실행하라는 메시지를 표시합니다. `/web-setup` 안내는 [터미널에서 연결](/ko/web-quickstart#connect-from-your-terminal)을 참조하세요.44두 방법 모두 작동합니다. [`/schedule`](/ko/routines)은 두 형태의 액세스를 확인하고 구성되지 않은 경우 `/web-setup`을 실행하라는 메시지를 표시합니다. `/web-setup` 안내는 [터미널에서 연결](/ko/web-quickstart#connect-from-your-terminal)을 참조하세요.

41 45 

42GitHub App은 PR 웹훅을 수신하기 위해 App을 사용하는 [자동 수정](#auto-fix-pull-requests)에 필요합니다. `/web-setup`으로 연결했다가 나중에 자동 수정을 원하면 해당 저장소에 App을 설치하세요.46GitHub App은 App을 사용하여 PR 웹훅을 수신하는 [자동 수정](#auto-fix-pull-requests)에 필요합니다. `/web-setup`으로 연결했다가 나중에 자동 수정을 원하면 해당 저장소에 App을 설치하세요.

43 47 

44Team 및 Enterprise 관리자는 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)의 Quick web setup 토글로 `/web-setup`을 비활성화할 수 있습니다.48Team 및 Enterprise 관리자는 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)의 Quick web setup 토글로 `/web-setup`을 비활성화할 수 있습니다.

45 49 


739* **모바일 앱에서**: Claude에 PR을 자동 수정하도록 지시합니다. 예를 들어 "watch this PR and fix any CI failures or review comments"743* **모바일 앱에서**: Claude에 PR을 자동 수정하도록 지시합니다. 예를 들어 "watch this PR and fix any CI failures or review comments"

740* **기존 PR**: PR URL을 세션에 붙여넣고 Claude에 자동 수정하도록 지시합니다744* **기존 PR**: PR URL을 세션에 붙여넣고 Claude에 자동 수정하도록 지시합니다

741 745 

746자동 수정은 PR별 토글입니다. 모니터링을 중지하려면 웹 세션에서 CI 상태 표시줄을 열고 **Auto-fix** 토글을 해제하거나, Claude에 PR 감시를 중지하도록 지시합니다.

747 

742### Claude가 PR 활동에 응답하는 방식748### Claude가 PR 활동에 응답하는 방식

743 749 

744자동 수정이 활성화되면 Claude는 새 검토 주석 및 CI 검사 실패를 포함한 PR의 GitHub 이벤트를 수신합니다. 각 이벤트에 대해 Claude는 조사하고 진행 방식을 결정합니다:750자동 수정이 활성화되면 Claude는 새 검토 주석 및 CI 검사 실패를 포함한 PR의 GitHub 이벤트를 수신합니다. 각 이벤트에 대해 Claude는 조사하고 진행 방식을 결정합니다:


772 778 

773* [status.claude.com](https://status.claude.com)에서 클라우드 세션 인시던트를 확인하세요779* [status.claude.com](https://status.claude.com)에서 클라우드 세션 인시던트를 확인하세요

774* 용량이 온디맨드로 프로비저닝되므로 1분 후 다시 시도하세요780* 용량이 온디맨드로 프로비저닝되므로 1분 후 다시 시도하세요

775* 저장소에 도달할 수 있는지 확인하세요. 개인 저장소는 해당 저장소에 액세스할 있는 GitHub App이 설치되어 있거나 `/web-setup`을 통해 동기화된 `gh` 토큰이 필요합니다. [GitHub 인증 옵션](#github-authentication-options)을 참조하세요.781* 저장소에 도달할 수 있는지 확인하세요. 연결하는 GitHub 계정은 Claude GitHub App 인증 또는 `/web-setup`을 통해 동기화된 `gh` 토큰을 통해 GitHub의 저장소에 액세스할 수 있어야 합니다. 저장소에 App을 설치할 필요는 없습니다. [GitHub 인증 옵션](#github-authentication-options)을 참조하세요.

776 782 

777### Remote Control 세션 만료 또는 액세스 거부783### Remote Control 세션 만료 또는 액세스 거부

778 784 

commands.md +4 −4

Details

60| `/diff` | 커밋되지 않은 변경 사항과 턴별 diff를 표시하는 대화형 diff 뷰어를 엽니다. 왼쪽/오른쪽 화살표를 사용하여 현재 git diff와 개별 Claude 턴 사이를 전환하고, 위/아래를 사용하여 파일을 탐색합니다 |60| `/diff` | 커밋되지 않은 변경 사항과 턴별 diff를 표시하는 대화형 diff 뷰어를 엽니다. 왼쪽/오른쪽 화살표를 사용하여 현재 git diff와 개별 Claude 턴 사이를 전환하고, 위/아래를 사용하여 파일을 탐색합니다 |

61| `/doctor` | Claude Code 설치 및 설정을 진단하고 확인합니다. 결과는 상태 아이콘과 함께 표시됩니다. `f`를 눌러 Claude가 보고된 문제를 수정하도록 합니다 |61| `/doctor` | Claude Code 설치 및 설정을 진단하고 확인합니다. 결과는 상태 아이콘과 함께 표시됩니다. `f`를 눌러 Claude가 보고된 문제를 수정하도록 합니다 |

62| `/effort [level\|auto]` | 모델 [effort level](/ko/model-config#adjust-effort-level)을 설정합니다. `low`, `medium`, `high`, `xhigh` 또는 `max`를 허용합니다. 사용 가능한 수준은 모델에 따라 다르며 `max`는 세션 전용입니다. `auto`는 모델 기본값으로 재설정합니다. 인수 없이 대화형 슬라이더를 엽니다. 왼쪽 및 오른쪽 화살표를 사용하여 수준을 선택하고 `Enter`를 눌러 적용합니다. 현재 응답이 완료될 때까지 기다리지 않고 즉시 적용됩니다 |62| `/effort [level\|auto]` | 모델 [effort level](/ko/model-config#adjust-effort-level)을 설정합니다. `low`, `medium`, `high`, `xhigh` 또는 `max`를 허용합니다. 사용 가능한 수준은 모델에 따라 다르며 `max`는 세션 전용입니다. `auto`는 모델 기본값으로 재설정합니다. 인수 없이 대화형 슬라이더를 엽니다. 왼쪽 및 오른쪽 화살표를 사용하여 수준을 선택하고 `Enter`를 눌러 적용합니다. 현재 응답이 완료될 때까지 기다리지 않고 즉시 적용됩니다 |

63| `/exit` | CLI를 종료합니다. 별칭: `/quit` |63| `/exit` | CLI를 종료합니다. 연결된 [background session](/ko/agent-view#attach-to-a-session)에서 이 명령어는 분리하고 세션은 계속 실행됩니다. 별칭: `/quit` |

64| `/export [filename]` | 현재 대화를 일반 텍스트로 내보냅니다. 파일 이름이 있으면 해당 파일에 직접 작성합니다. 없으면 클립보드에 복사하거나 파일에 저장할 수 있는 대화 상자를 엽니다 |64| `/export [filename]` | 현재 대화를 일반 텍스트로 내보냅니다. 파일 이름이 있으면 해당 파일에 직접 작성합니다. 없으면 클립보드에 복사하거나 파일에 저장할 수 있는 대화 상자를 엽니다 |

65| `/extra-usage` | 속도 제한에 도달했을 때 계속 작업할 수 있도록 추가 사용량을 구성합니다 |65| `/extra-usage` | 속도 제한에 도달했을 때 계속 작업할 수 있도록 추가 사용량을 구성합니다 |

66| `/fast [on\|off]` | [fast mode](/ko/fast-mode)를 켜거나 끕니다 |66| `/fast [on\|off]` | [fast mode](/ko/fast-mode)를 켜거나 끕니다 |


92| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}v2.1.91에서 제거됨. 대신 Claude에 직접 pull request 댓글을 보도록 요청하세요. 이전 버전에서는 GitHub pull request의 댓글을 가져와 표시합니다. 현재 브랜치의 PR을 자동으로 감지하거나 PR URL 또는 번호를 전달합니다. `gh` CLI가 필요합니다 |92| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}v2.1.91에서 제거됨. 대신 Claude에 직접 pull request 댓글을 보도록 요청하세요. 이전 버전에서는 GitHub pull request의 댓글을 가져와 표시합니다. 현재 브랜치의 PR을 자동으로 감지하거나 PR URL 또는 번호를 전달합니다. `gh` CLI가 필요합니다 |

93| `/privacy-settings` | 개인정보 보호 설정을 보고 업데이트합니다. Pro 및 Max 요금제 구독자만 사용 가능합니다 |93| `/privacy-settings` | 개인정보 보호 설정을 보고 업데이트합니다. Pro 및 Max 요금제 구독자만 사용 가능합니다 |

94| `/radio` | Claude FM lo-fi 라디오를 브라우저에서 엽니다. 브라우저를 사용할 수 없을 때 스트림 URL을 인쇄합니다. Bedrock, Vertex 또는 Foundry에서는 사용할 수 없습니다 |94| `/radio` | Claude FM lo-fi 라디오를 브라우저에서 엽니다. 브라우저를 사용할 수 없을 때 스트림 URL을 인쇄합니다. Bedrock, Vertex 또는 Foundry에서는 사용할 수 없습니다 |

95| `/recap` | 현재 세션의 한 줄 요약을 요청 시 생성합니다. 자동으로 나타나는 [Session recap](/ko/interactive-mode#session-recap)을 참조하세요. 이는 떠난 후 표시됩니다 |95| `/recap` | 현재 세션의 한 줄 요약을 요청 시 생성합니다. 떠난 표시되는 자동 요약인 [Session recap](/ko/interactive-mode#session-recap)을 참조하세요 |

96| `/release-notes` | 대화형 버전 선택기에서 변경 로그를 봅니다. 특정 버전을 선택하여 해당 릴리스 노트를 보거나, 모든 버전을 표시하도록 선택합니다 |96| `/release-notes` | 대화형 버전 선택기에서 변경 로그를 봅니다. 특정 버전을 선택하여 해당 릴리스 노트를 보거나, 모든 버전을 표시하도록 선택합니다 |

97| `/reload-plugins` | 모든 활성 [plugins](/ko/plugins)를 다시 로드하여 재시작하지 않고 보류 중인 변경 사항을 적용합니다. 각 다시 로드된 구성 요소의 개수를 보고하고 로드 오류를 표시합니다 |97| `/reload-plugins` | 모든 활성 [plugins](/ko/plugins)를 다시 로드하여 재시작하지 않고 보류 중인 변경 사항을 적용합니다. 각 다시 로드된 구성 요소의 개수를 보고하고 로드 오류를 표시합니다 |

98| `/remote-control` | 이 세션을 claude.ai에서 [remote control](/ko/remote-control)할 수 있도록 합니다. 별칭: `/rc` |98| `/remote-control` | 이 세션을 claude.ai에서 [remote control](/ko/remote-control)할 수 있도록 합니다. 별칭: `/rc` |


102| `/review [PR]` | 현재 세션에서 로컬로 pull request를 검토합니다. 더 깊은 클라우드 기반 검토는 [`/ultrareview`](/ko/ultrareview)를 참조하세요 |102| `/review [PR]` | 현재 세션에서 로컬로 pull request를 검토합니다. 더 깊은 클라우드 기반 검토는 [`/ultrareview`](/ko/ultrareview)를 참조하세요 |

103| `/rewind` | 대화 및/또는 코드를 이전 지점으로 되감기하거나 선택한 메시지에서 요약합니다. [checkpointing](/ko/checkpointing)을 참조하세요. 별칭: `/checkpoint`, `/undo` |103| `/rewind` | 대화 및/또는 코드를 이전 지점으로 되감기하거나 선택한 메시지에서 요약합니다. [checkpointing](/ko/checkpointing)을 참조하세요. 별칭: `/checkpoint`, `/undo` |

104| `/sandbox` | [sandbox mode](/ko/sandboxing)를 전환합니다. 지원되는 플랫폼에서만 사용 가능합니다 |104| `/sandbox` | [sandbox mode](/ko/sandboxing)를 전환합니다. 지원되는 플랫폼에서만 사용 가능합니다 |

105| `/schedule [description]` | [routines](/ko/routines)를 만들거나, 업데이트하거나, 나열하거나, 실행합니다. Claude가 설정 과정을 대화형으로 안내합니다. 별칭: `/routines` |105| `/schedule [description]` | [routines](/ko/routines)를 만들거나, 업데이트하거나, 나열하거나, 실행합니다. Anthropic 관리 클라우드 인프라에서 실행됩니다. Claude가 설정 과정을 대화형으로 안내합니다. 별칭: `/routines` |

106| `/scroll-speed` | 마우스 휠 [scroll speed](/ko/fullscreen#mouse-wheel-scrolling)를 대화형으로 조정합니다. 대화 상자가 열려 있는 동안 스크롤할 수 있는 눈금자를 사용하여 변경 사항을 미리 봅니다. [fullscreen rendering](/ko/fullscreen)에서만 사용 가능하며 JetBrains IDE 터미널에서는 사용할 수 없습니다 |106| `/scroll-speed` | 마우스 휠 [scroll speed](/ko/fullscreen#mouse-wheel-scrolling)를 대화형으로 조정합니다. 대화 상자가 열려 있는 동안 스크롤할 수 있는 눈금자를 사용하여 변경 사항을 미리 봅니다. [fullscreen rendering](/ko/fullscreen)에서만 사용 가능하며 JetBrains IDE 터미널에서는 사용할 수 없습니다 |

107| `/security-review` | 현재 브랜치의 보류 중인 변경 사항을 보안 취약점에 대해 분석합니다. git diff를 검토하고 주입, 인증 문제 및 데이터 노출과 같은 위험을 식별합니다 |107| `/security-review` | 현재 브랜치의 보류 중인 변경 사항을 보안 취약점에 대해 분석합니다. git diff를 검토하고 주입, 인증 문제 및 데이터 노출과 같은 위험을 식별합니다 |

108| `/setup-bedrock` | [Amazon Bedrock](/ko/amazon-bedrock) 인증, 지역 및 모델 핀을 대화형 마법사를 통해 구성합니다. `CLAUDE_CODE_USE_BEDROCK=1`이 설정되어 있을 때만 표시됩니다. 처음 Bedrock을 사용하는 사용자는 로그인 화면에서도 이 마법사에 액세스할 수 있습니다 |108| `/setup-bedrock` | [Amazon Bedrock](/ko/amazon-bedrock) 인증, 지역 및 모델 핀을 대화형 마법사를 통해 구성합니다. `CLAUDE_CODE_USE_BEDROCK=1`이 설정되어 있을 때만 표시됩니다. 처음 Bedrock을 사용하는 사용자는 로그인 화면에서도 이 마법사에 액세스할 수 있습니다 |


121| `/theme` | 색상 테마를 변경합니다. 터미널의 어두운 또는 밝은 배경을 따르는 `auto` 옵션, 밝은 색과 어두운 색 변형, 색맹 접근 가능(daltonized) 테마, 터미널의 색상 팔레트를 사용하는 ANSI 테마 및 `~/.claude/themes/` 또는 plugins의 [custom themes](/ko/terminal-config#create-a-custom-theme)를 포함합니다. \*\*New custom theme…\*\*를 선택하여 새로 만듭니다 |121| `/theme` | 색상 테마를 변경합니다. 터미널의 어두운 또는 밝은 배경을 따르는 `auto` 옵션, 밝은 색과 어두운 색 변형, 색맹 접근 가능(daltonized) 테마, 터미널의 색상 팔레트를 사용하는 ANSI 테마 및 `~/.claude/themes/` 또는 plugins의 [custom themes](/ko/terminal-config#create-a-custom-theme)를 포함합니다. \*\*New custom theme…\*\*를 선택하여 새로 만듭니다 |

122| `/tui [default\|fullscreen]` | 터미널 UI 렌더러를 설정하고 대화를 유지하면서 다시 시작합니다. `fullscreen`은 [flicker-free alt-screen renderer](/ko/fullscreen)를 활성화합니다. 인수 없이 활성 렌더러를 인쇄합니다 |122| `/tui [default\|fullscreen]` | 터미널 UI 렌더러를 설정하고 대화를 유지하면서 다시 시작합니다. `fullscreen`은 [flicker-free alt-screen renderer](/ko/fullscreen)를 활성화합니다. 인수 없이 활성 렌더러를 인쇄합니다 |

123| `/ultraplan <prompt>` | [ultraplan](/ko/ultraplan) 세션에서 계획을 작성하고, 브라우저에서 검토한 다음, 원격으로 실행하거나 터미널로 다시 보냅니다 |123| `/ultraplan <prompt>` | [ultraplan](/ko/ultraplan) 세션에서 계획을 작성하고, 브라우저에서 검토한 다음, 원격으로 실행하거나 터미널로 다시 보냅니다 |

124| `/ultrareview [PR]` | [ultrareview](/ko/ultrareview)를 사용하여 클라우드 샌드박스에서 깊은 다중 agent 코드 검토를 실행합니다. Pro 및 Max에서 2026년 5월 5일까지 3회 무료 실행을 포함한 후 [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)가 필요합니다 |124| `/ultrareview [PR]` | [ultrareview](/ko/ultrareview)를 사용하여 클라우드 샌드박스에서 깊은 다중 agent 코드 검토를 실행합니다. Pro 및 Max에서 3회 무료 실행을 포함한 후 [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)가 필요합니다 |

125| `/upgrade` | 업그레이드 페이지를 열어 더 높은 요금제로 전환합니다 |125| `/upgrade` | 업그레이드 페이지를 열어 더 높은 요금제로 전환합니다 |

126| `/usage` | 세션 비용, 요금제 사용 제한 및 활동 통계를 표시합니다. 구독별 세부 정보는 [cost tracking guide](/ko/costs#using-the-%2Fusage-command)를 참조하세요. `/cost` 및 `/stats`는 별칭입니다 |126| `/usage` | 세션 비용, 요금제 사용 제한 및 활동 통계를 표시합니다. 구독별 세부 정보는 [cost tracking guide](/ko/costs#using-the-%2Fusage-command)를 참조하세요. `/cost` 및 `/stats`는 별칭입니다 |

127| `/vim` | {/* max-version: 2.1.91 */}v2.1.92에서 제거됨. Vim과 Normal 편집 모드 사이를 전환하려면 `/config` → Editor mode를 사용하세요 |127| `/vim` | {/* max-version: 2.1.91 */}v2.1.92에서 제거됨. Vim과 Normal 편집 모드 사이를 전환하려면 `/config` → Editor mode를 사용하세요 |

Details

364 364 

365공식 Anthropic 마켓플레이스는 기본적으로 자동 업데이트가 활성화되어 있습니다. 타사 및 로컬 개발 마켓플레이스는 기본적으로 자동 업데이트가 비활성화되어 있습니다.365공식 Anthropic 마켓플레이스는 기본적으로 자동 업데이트가 활성화되어 있습니다. 타사 및 로컬 개발 마켓플레이스는 기본적으로 자동 업데이트가 비활성화되어 있습니다.

366 366 

367관리자는 관리되는 설정에서 각 [`extraKnownMarketplaces`](/ko/settings#extraknownmarketplaces) 항목에 `"autoUpdate": true`를 설정하여 각 사용자가 전환하도록 요구하지 않고 조직 마켓플레이스에 대한 자동 업데이트를 활성화할 수 있습니다.

368 

367Claude Code 및 모든 플러그인에 대해 모든 자동 업데이트를 완전히 비활성화하려면 `DISABLE_AUTOUPDATER` 환경 변수를 설정합니다. 자세한 내용은 [자동 업데이트](/ko/setup#auto-updates)를 참조하세요.369Claude Code 및 모든 플러그인에 대해 모든 자동 업데이트를 완전히 비활성화하려면 `DISABLE_AUTOUPDATER` 환경 변수를 설정합니다. 자세한 내용은 [자동 업데이트](/ko/setup#auto-updates)를 참조하세요.

368 370 

369Claude Code 자동 업데이트를 비활성화하면서 플러그인 자동 업데이트를 활성화된 상태로 유지하려면 `DISABLE_AUTOUPDATER`와 함께 `FORCE_AUTOUPDATE_PLUGINS=1`을 설정합니다:371Claude Code 자동 업데이트를 비활성화하면서 플러그인 자동 업데이트를 활성화된 상태로 유지하려면 `DISABLE_AUTOUPDATER`와 함께 `FORCE_AUTOUPDATE_PLUGINS=1`을 설정합니다:

env-vars.md +2 −0

Details

129| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 인증용 OAuth 새로 고침 토큰입니다. 설정하면 `claude auth login`이 브라우저를 열지 않고 이 토큰을 직접 교환합니다. `CLAUDE_CODE_OAUTH_SCOPES`가 필요합니다. 자동화된 환경에서 인증을 프로비저닝하는 데 유용합니다. |129| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 인증용 OAuth 새로 고침 토큰입니다. 설정하면 `claude auth login`이 브라우저를 열지 않고 이 토큰을 직접 교환합니다. `CLAUDE_CODE_OAUTH_SCOPES`가 필요합니다. 자동화된 환경에서 인증을 프로비저닝하는 데 유용합니다. |

130| `CLAUDE_CODE_OAUTH_SCOPES` | 새로 고침 토큰이 발급된 공백으로 구분된 OAuth 범위(예: `"user:profile user:inference user:sessions:claude_code"`). `CLAUDE_CODE_OAUTH_REFRESH_TOKEN`이 설정되면 필수입니다. |130| `CLAUDE_CODE_OAUTH_SCOPES` | 새로 고침 토큰이 발급된 공백으로 구분된 OAuth 범위(예: `"user:profile user:inference user:sessions:claude_code"`). `CLAUDE_CODE_OAUTH_REFRESH_TOKEN`이 설정되면 필수입니다. |

131| `CLAUDE_CODE_OAUTH_TOKEN` | Claude.ai 인증용 OAuth 액세스 토큰입니다. `/login`의 대안으로 SDK 및 자동화된 환경에 사용됩니다. 키체인 저장 자격 증명보다 우선합니다. [`claude setup-token`](/ko/authentication#generate-a-long-lived-token)으로 생성합니다. |131| `CLAUDE_CODE_OAUTH_TOKEN` | Claude.ai 인증용 OAuth 액세스 토큰입니다. `/login`의 대안으로 SDK 및 자동화된 환경에 사용됩니다. 키체인 저장 자격 증명보다 우선합니다. [`claude setup-token`](/ko/authentication#generate-a-long-lived-token)으로 생성합니다. |

132| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | [빠른 모드](/ko/fast-mode)를 Claude Opus 4.6에서 유지하려면 `1`로 설정합니다. `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE`보다 우선하므로, 기본값이 어떻게 변경되든 Opus 4.6을 고정해야 하는 경우 이를 설정합니다. |

132| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 보류 중인 OpenTelemetry 스팬을 플러시하는 타임아웃(밀리초)(기본값: 5000). [모니터링](/ko/monitoring-usage) 참조 |133| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 보류 중인 OpenTelemetry 스팬을 플러시하는 타임아웃(밀리초)(기본값: 5000). [모니터링](/ko/monitoring-usage) 참조 |

133| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 동적 OpenTelemetry 헤더를 새로 고치는 간격(밀리초)(기본값: 1740000 / 29분). [동적 헤더](/ko/monitoring-usage#dynamic-headers) 참조 |134| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 동적 OpenTelemetry 헤더를 새로 고치는 간격(밀리초)(기본값: 1740000 / 29분). [동적 헤더](/ko/monitoring-usage#dynamic-headers) 참조 |

134| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | 종료 시 OpenTelemetry 내보내기가 완료되는 타임아웃(밀리초)(기본값: 2000). 메트릭이 종료 시 삭제되면 증가시킵니다. [모니터링](/ko/monitoring-usage) 참조 |135| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | 종료 시 OpenTelemetry 내보내기가 완료되는 타임아웃(밀리초)(기본값: 2000). 메트릭이 종료 시 삭제되면 증가시킵니다. [모니터링](/ko/monitoring-usage) 참조 |


143| `CLAUDE_CODE_REMOTE` | Claude Code가 [클라우드 세션](/ko/claude-code-on-the-web)으로 실행 중일 때 자동으로 `true`로 설정됩니다. 훅 또는 설정 스크립트에서 이를 읽어 클라우드 환경에 있는지 감지합니다. |144| `CLAUDE_CODE_REMOTE` | Claude Code가 [클라우드 세션](/ko/claude-code-on-the-web)으로 실행 중일 때 자동으로 `true`로 설정됩니다. 훅 또는 설정 스크립트에서 이를 읽어 클라우드 환경에 있는지 감지합니다. |

144| `CLAUDE_CODE_REMOTE_SESSION_ID` | [클라우드 세션](/ko/claude-code-on-the-web)에서 현재 세션의 ID로 자동으로 설정됩니다. 세션 트랜스크립트로 다시 연결하는 링크를 구성하려면 이를 읽습니다. [세션으로 아티팩트 다시 연결](/ko/claude-code-on-the-web#link-artifacts-back-to-the-session) 참조 |145| `CLAUDE_CODE_REMOTE_SESSION_ID` | [클라우드 세션](/ko/claude-code-on-the-web)에서 현재 세션의 ID로 자동으로 설정됩니다. 세션 트랜스크립트로 다시 연결하는 링크를 구성하려면 이를 읽습니다. [세션으로 아티팩트 다시 연결](/ko/claude-code-on-the-web#link-artifacts-back-to-the-session) 참조 |

145| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 이전 세션이 중간에 끝난 경우 자동으로 재개하려면 `1`로 설정합니다. SDK 모드에서 사용되므로 모델이 SDK가 프롬프트를 다시 전송할 필요 없이 계속됩니다. |146| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 이전 세션이 중간에 끝난 경우 자동으로 재개하려면 `1`로 설정합니다. SDK 모드에서 사용되므로 모델이 SDK가 프롬프트를 다시 전송할 필요 없이 계속됩니다. |

147| `CLAUDE_CODE_RESUME_PROMPT` | 세션이 중간에 끝난 후 재개할 때 주입되는 계속 메시지를 재정의합니다. 기본값은 `Continue from where you left off.`입니다. 장시간 실행되는 에이전트의 스폰 스크립트는 이를 더 지시적인 부팅 메시지로 설정할 수 있습니다. 빈 문자열은 기본값을 사용합니다. |

146| `CLAUDE_CODE_SCRIPT_CAPS` | `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`이 설정되었을 때 세션당 특정 스크립트를 호출할 수 있는 횟수를 제한하는 JSON 객체입니다. 키는 명령 텍스트에 대해 일치하는 부분 문자열입니다. 값은 정수 호출 제한입니다. 예를 들어 `{"deploy.sh": 2}`는 `deploy.sh`를 최대 2번 호출할 수 있습니다. 일치는 부분 문자열 기반이므로 `./scripts/deploy.sh $(evil)`과 같은 셸 확장 트릭도 여전히 제한에 포함됩니다. `xargs` 또는 `find -exec`을 통한 런타임 팬아웃은 감지되지 않습니다. 이는 심층 방어 제어입니다. |148| `CLAUDE_CODE_SCRIPT_CAPS` | `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`이 설정되었을 때 세션당 특정 스크립트를 호출할 수 있는 횟수를 제한하는 JSON 객체입니다. 키는 명령 텍스트에 대해 일치하는 부분 문자열입니다. 값은 정수 호출 제한입니다. 예를 들어 `{"deploy.sh": 2}`는 `deploy.sh`를 최대 2번 호출할 수 있습니다. 일치는 부분 문자열 기반이므로 `./scripts/deploy.sh $(evil)`과 같은 셸 확장 트릭도 여전히 제한에 포함됩니다. `xargs` 또는 `find -exec`을 통한 런타임 팬아웃은 감지되지 않습니다. 이는 심층 방어 제어입니다. |

147| `CLAUDE_CODE_SCROLL_SPEED` | [전체 화면 렌더링](/ko/fullscreen#mouse-wheel-scrolling)에서 마우스 휠 스크롤 배수를 설정합니다. 1부터 20까지의 값을 허용합니다. 터미널이 증폭 없이 노치당 하나의 휠 이벤트를 보내는 경우 `vim`과 일치하도록 `3`으로 설정합니다. JetBrains IDE 터미널에서는 무시되며, Claude Code는 자체 스크롤 처리를 사용합니다. |149| `CLAUDE_CODE_SCROLL_SPEED` | [전체 화면 렌더링](/ko/fullscreen#mouse-wheel-scrolling)에서 마우스 휠 스크롤 배수를 설정합니다. 1부터 20까지의 값을 허용합니다. 터미널이 증폭 없이 노치당 하나의 휠 이벤트를 보내는 경우 `vim`과 일치하도록 `3`으로 설정합니다. JetBrains IDE 터미널에서는 무시되며, Claude Code는 자체 스크롤 처리를 사용합니다. |

148| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | [SessionEnd](/ko/hooks#sessionend) 훅의 시간 예산(밀리초)을 재정의합니다. 세션 종료, `/clear`, 대화형 `/resume`을 통한 세션 전환에 적용됩니다. 기본적으로 예산은 1.5초이며, 설정 파일에서 구성된 가장 높은 훅별 `timeout`으로 자동으로 올라가며, 최대 60초입니다. 플러그인 제공 훅의 타임아웃은 예산을 올리지 않습니다. |150| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | [SessionEnd](/ko/hooks#sessionend) 훅의 시간 예산(밀리초)을 재정의합니다. 세션 종료, `/clear`, 대화형 `/resume`을 통한 세션 전환에 적용됩니다. 기본적으로 예산은 1.5초이며, 설정 파일에서 구성된 가장 높은 훅별 `timeout`으로 자동으로 올라가며, 최대 60초입니다. 플러그인 제공 훅의 타임아웃은 예산을 올리지 않습니다. |

fast-mode.md +2 −0

Details

80 80 

81Opus 4.6의 빠른 모드는 Opus 4.7과 함께 계속 사용할 수 있습니다. 둘 다 동일한 빠른 모드 속도 제한 풀을 공유합니다: 어느 모델에서든 사용량은 동일한 제한에서 차감됩니다.81Opus 4.6의 빠른 모드는 Opus 4.7과 함께 계속 사용할 수 있습니다. 둘 다 동일한 빠른 모드 속도 제한 풀을 공유합니다: 어느 모델에서든 사용량은 동일한 제한에서 차감됩니다.

82 82 

83빠른 모드를 Opus 4.6으로 명시적으로 고정하려면 `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1`을 설정합니다. 이 변수는 우선순위를 가지므로 `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE`이 설정되었는지 여부와 관계없이 빠른 모드는 Opus 4.6에서 실행됩니다.

84 

83## 비용 트레이드오프 이해85## 비용 트레이드오프 이해

84 86 

85빠른 모드는 표준 Opus보다 토큰당 가격이 높습니다:87빠른 모드는 표준 Opus보다 토큰당 가격이 높습니다:

goal.md +1 −1

Details

128 128 

129## 요구 사항129## 요구 사항

130 130 

131`/goal`은 평가자가 hooks 시스템의 일부이기 때문에 신뢰 대화를 수락한 워크스페이스에서만 실행됩니다. [`disableAllHooks`](/ko/hooks#disable-or-remove-hooks)가 관리 정책 설정에서 설정되면 `/goal`을 사용할 수 없습니다. 두 경우 모두 명령은 조용히 아무것도 하지 않는 대신 이유를 알려줍니다.131`/goal`은 평가자가 hooks 시스템의 일부이기 때문에 신뢰 대화를 수락한 워크스페이스에서만 실행됩니다. [`disableAllHooks`](/ko/hooks#disable-or-remove-hooks)가 모든 설정 수준에서 설정되거나 관리 설정에서 [`allowManagedHooksOnly`](/ko/settings#hook-configuration)가 설정되면 `/goal`을 사용할 수 없습니다. 경우에 명령은 조용히 아무것도 하지 않는 대신 이유를 알려줍니다.

132 132 

133## 참고 항목133## 참고 항목

134 134 

headless.md +4 −4

Details

6 6 

7> Agent SDK를 사용하여 CLI, Python 또는 TypeScript에서 Claude Code를 프로그래밍 방식으로 실행합니다.7> Agent SDK를 사용하여 CLI, Python 또는 TypeScript에서 Claude Code를 프로그래밍 방식으로 실행합니다.

8 8 

9[Agent SDK](/ko/agent-sdk/overview)는 Claude Code를 구동하는 동일한 도구, 에이전트 루프 및 컨텍스트 관리를 제공합니다. 스크립트 및 CI/CD용 CLI로 사용하거나 완전한 프로그래밍 방식 제어를 위한 [Python](/ko/agent-sdk/python) 및 [TypeScript](/ko/agent-sdk/typescript) 패키지로 사용할 수 있습니다.

10 

11<Note>9<Note>

12 CLI는 이전에 "헤드리스 모드"라고 불렸습니다. `-p` 플래그 모든 CLI 옵션은 동일한 방식으로 작동합니다.10 Starting June 15, 2026, Agent SDK and `claude -p` usage on subscription plans will draw from a new monthly Agent SDK credit, separate from your interactive usage limits. See [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) for details.

13</Note>11</Note>

14 12 

15CLI에서 Claude Code를 프로그래밍 방식으로 실행하려면 프롬프트와 함께 `-p`를 전달하고 [CLI 옵션](/ko/cli-reference) 사용합니다:13[Agent SDK](/ko/agent-sdk/overview)는 Claude Code를 구동하는 동일한 도구, 에이전트 루프 컨텍스트 관리를 제공합니다. 스크립트 및 CI/CD용 CLI로 사용하거나 완전한 프로그래밍 방식 제어를 위한 [Python](/ko/agent-sdk/python) 및 [TypeScript](/ko/agent-sdk/typescript) 패키지로 사용할 수 있습니다.

14 

15Claude Code를 비대화형 모드에서 실행하려면 프롬프트와 함께 `-p`를 전달하고 [CLI 옵션](/ko/cli-reference)을 사용합니다:

16 16 

17```bash theme={null}17```bash theme={null}

18claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"18claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

hooks-guide.md +1 −1

Details

754| [Plugin](/ko/plugins) `hooks/hooks.json` | 플러그인이 활성화되었을 때 | 예, 플러그인과 함께 번들됨 |754| [Plugin](/ko/plugins) `hooks/hooks.json` | 플러그인이 활성화되었을 때 | 예, 플러그인과 함께 번들됨 |

755| [Skill](/ko/skills) 또는 [agent](/ko/sub-agents) frontmatter | Skill 또는 에이전트가 활성화되어 있는 동안 | 예, 컴포넌트 파일에 정의됨 |755| [Skill](/ko/skills) 또는 [agent](/ko/sub-agents) frontmatter | Skill 또는 에이전트가 활성화되어 있는 동안 | 예, 컴포넌트 파일에 정의됨 |

756 756 

757Claude Code에서 [`/hooks`](/ko/hooks#the-hooks-menu)를 실행하여 이벤트별로 그룹화된 모든 구성된 hooks를 찾아봅니다. 모든 hooks를 한 번에 비활성화하려면 설정 파일에서 `"disableAllHooks": true`를 설정합니다.757Claude Code에서 [`/hooks`](/ko/hooks#the-hooks-menu)를 실행하여 이벤트별로 그룹화된 모든 구성된 hooks를 찾아봅니다. 모든 hooks를 한 번에 비활성화하려면 설정 파일에서 `"disableAllHooks": true`를 설정합니다. 관리형 설정에서 구성된 Hooks는 `disableAllHooks`도 설정되지 않는 한 실행됩니다.

758 758 

759Claude Code가 실행 중인 동안 설정 파일을 직접 편집하면 파일 감시자가 일반적으로 hook 변경을 자동으로 선택합니다.759Claude Code가 실행 중인 동안 설정 파일을 직접 편집하면 파일 감시자가 일반적으로 hook 변경을 자동으로 선택합니다.

760 760 

memory.md +2 −2

Details

51 51 

52### CLAUDE.md 파일을 어디에 배치할지 선택52### CLAUDE.md 파일을 어디에 배치할지 선택

53 53 

54CLAUDE.md 파일은 여러 위치에 있을 수 있으며, 각각 다른 범위를 가집니다. 구체적인 위치가 광범위한 위치보다 우선합니다.54CLAUDE.md 파일은 여러 위치에 있을 수 있으며, 각각 다른 범위를 가집니다. 아래 표는 로드 순서대로 나열되어 있으며, 가장 광범위한 범위에서 가장 구체적인 범위까지이므로 프로젝트 지침이 사용자 지침 이후에 컨텍스트에 나타납니다.

55 55 

56| 범위 | 위치 | 목적 | 사용 사례 | 공유 대상 |56| 범위 | 위치 | 목적 | 사용 사례 | 공유 대상 |

57| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ---------------------------- | -------------- |57| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ---------------------------- | -------------- |

58| **관리 정책** | • macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`<br />• Linux 및 WSL: `/etc/claude-code/CLAUDE.md`<br />• Windows: `C:\Program Files\ClaudeCode\CLAUDE.md` | IT/DevOps에서 관리하는 조직 전체 지침 | 회사 코딩 표준, 보안 정책, 규정 준수 요구사항 | 조직의 모든 사용자 |58| **관리 정책** | • macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`<br />• Linux 및 WSL: `/etc/claude-code/CLAUDE.md`<br />• Windows: `C:\Program Files\ClaudeCode\CLAUDE.md` | IT/DevOps에서 관리하는 조직 전체 지침 | 회사 코딩 표준, 보안 정책, 규정 준수 요구사항 | 조직의 모든 사용자 |

59| **프로젝트 지침** | `./CLAUDE.md` 또는 `./.claude/CLAUDE.md` | 프로젝트에 대한 팀 공유 지침 | 프로젝트 아키텍처, 코딩 표준, 일반적인 워크플로우 | 소스 제어를 통한 팀 멤버 |

60| **사용자 지침** | `~/.claude/CLAUDE.md` | 모든 프로젝트에 대한 개인 선호도 | 코드 스타일 선호도, 개인 도구 단축키 | 본인만(모든 프로젝트) |59| **사용자 지침** | `~/.claude/CLAUDE.md` | 모든 프로젝트에 대한 개인 선호도 | 코드 스타일 선호도, 개인 도구 단축키 | 본인만(모든 프로젝트) |

60| **프로젝트 지침** | `./CLAUDE.md` 또는 `./.claude/CLAUDE.md` | 프로젝트에 대한 팀 공유 지침 | 프로젝트 아키텍처, 코딩 표준, 일반적인 워크플로우 | 소스 제어를 통한 팀 멤버 |

61| **로컬 지침** | `./CLAUDE.local.md` | 개인 프로젝트별 선호도; `.gitignore`에 추가 | 샌드박스 URL, 선호하는 테스트 데이터 | 본인만(현재 프로젝트) |61| **로컬 지침** | `./CLAUDE.local.md` | 개인 프로젝트별 선호도; `.gitignore`에 추가 | 샌드박스 URL, 선호하는 테스트 데이터 | 본인만(현재 프로젝트) |

62 62 

63작업 디렉토리 위의 디렉토리 계층 구조에 있는 CLAUDE.md 및 CLAUDE.local.md 파일은 시작 시 전체 로드됩니다. 하위 디렉토리의 파일은 Claude가 해당 디렉토리의 파일을 읽을 때 필요에 따라 로드됩니다. [CLAUDE.md 파일이 로드되는 방식](#how-claude-md-files-load)에서 전체 해석 순서를 참조하세요.63작업 디렉토리 위의 디렉토리 계층 구조에 있는 CLAUDE.md 및 CLAUDE.local.md 파일은 시작 시 전체 로드됩니다. 하위 디렉토리의 파일은 Claude가 해당 디렉토리의 파일을 읽을 때 필요에 따라 로드됩니다. [CLAUDE.md 파일이 로드되는 방식](#how-claude-md-files-load)에서 전체 해석 순서를 참조하세요.

model-config.md +1 −1

Details

231 231 

232Opus 4.7, Opus 4.6 및 Sonnet 4.6은 대규모 코드베이스를 사용한 긴 세션을 위해 [100만 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/ko/build-with-claude/context-windows#1m-token-context-window)를 지원합니다.232Opus 4.7, Opus 4.6 및 Sonnet 4.6은 대규모 코드베이스를 사용한 긴 세션을 위해 [100만 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/ko/build-with-claude/context-windows#1m-token-context-window)를 지원합니다.

233 233 

234가용성은 모델 및 플랜에 따라 다릅니다. Max, Team 및 Enterprise 플랜에서 Opus는 추가 구성 없이 자동으로 1M 컨텍스트로 업그레이드됩니다. 이는 Team Standard 및 Team Premium 시트 모두에 적용됩니다.234가용성은 모델 및 플랜에 따라 다릅니다. Max, Team 및 Enterprise 플랜에서 Opus는 추가 구성 없이 자동으로 1M 컨텍스트로 업그레이드됩니다. 이는 Team Standard 및 Team Premium 시트 모두에 적용됩니다. 1M 컨텍스트를 사용하는 Sonnet은 자동 업그레이드의 일부가 아니며 모든 구독 플랜(Max 포함)에서 [추가 사용](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)이 필요합니다.

235 235 

236| 플랜 | 1M 컨텍스트를 사용하는 Opus | 1M 컨텍스트를 사용하는 Sonnet |236| 플랜 | 1M 컨텍스트를 사용하는 Opus | 1M 컨텍스트를 사용하는 Sonnet |

237| ---------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |237| ---------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |

output-styles.md +57 −40

Details

6 6 

7> 소프트웨어 엔지니어링 이상의 용도로 Claude Code 적응시키기7> 소프트웨어 엔지니어링 이상의 용도로 Claude Code 적응시키기

8 8 

9출력 스타일은 Claude가 응답하는 방식을 변경하며, Claude가 알고 있는 내용을 변경하지 않습니다. 이들은 시스템 프롬프트를 수정하여 역할, 톤, 출력 형식을 설정하면서 스크립트 실행, 파일 읽기 및 쓰기, TODO 추적과 같은 핵심 기능을 유지합니다. 매 턴마다 동일한 음성이나 형식을 다시 요청하거나 Claude가 소프트웨어 엔지니어 이외의 역할을 하기를 원할 때 사용합니다.9출력 스타일은 Claude가 응답하는 방식을 변경하며, Claude가 알고 있는 내용을 변경하지 않습니다. 이들은 시스템 프롬프트를 수정하여 역할, 톤, 출력 형식을 설정합니다. 매 턴마다 동일한 음성이나 형식을 다시 요청하거나 Claude가 소프트웨어 엔지니어 이외의 역할을 하기를 원할 때 사용합니다.

10 

11사용자 정의 출력 스타일은 지침을 시스템 프롬프트에 추가하고 Claude Code의 기본 제공 소프트웨어 엔지니어링 지침을 유지할지 여부를 선택할 수 있게 합니다. Claude가 여전히 코딩하고 있지만 통신 방식을 변경할 때(예: 항상 다이어그램으로 답변)는 유지합니다. Claude가 쓰기 어시스턴트나 데이터 분석가와 같이 소프트웨어 엔지니어링을 수행하지 않을 때는 제외합니다.

10 12 

11프로젝트, 규칙 또는 코드베이스에 대한 지침은 대신 [CLAUDE.md](/ko/memory)를 사용합니다.13프로젝트, 규칙 또는 코드베이스에 대한 지침은 대신 [CLAUDE.md](/ko/memory)를 사용합니다.

12 14 


16 18 

17세 가지 추가 기본 제공 출력 스타일이 있습니다:19세 가지 추가 기본 제공 출력 스타일이 있습니다:

18 20 

19* **Proactive**: Claude가 즉시 실행하고, 일상적인 결정을 위해 일시 중지하는 대신 합리적인 가정을 하며, 계획보다 행동을 선호합니다.21* **Proactive**: Claude가 즉시 실행하고, 일상적인 결정을 위해 일시 중지하는 대신 합리적인 가정을 하며, 계획보다 행동을 선호합니다. 이는 [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)와 동일한 지침을 적용하지만 권한 모드를 변경하지 않으므로, 도구가 실행되기 전에 여전히 권한 프롬프트를 볼 수 있습니다.

20 이는 [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)와 동일한 지침을 적용하지만 권한 모드를 변경하지 않으므로, 도구가 실행되기 전에 여전히 권한 프롬프트를 볼 수 있습니다.

21 22 

22* **Explanatory**: 소프트웨어 엔지니어링 작업을 완료하는 동안 교육용 "Insights"를 제공합니다. 구현 선택 사항과 코드베이스 패턴을 이해하는 데 도움이 됩니다.23* **Explanatory**: 소프트웨어 엔지니어링 작업을 완료하는 동안 교육용 "Insights"를 제공합니다. 구현 선택 사항과 코드베이스 패턴을 이해하는 데 도움이 됩니다.

23 24 

24* **Learning**: 협업 방식의 학습 모드로, Claude는 코딩하면서 "Insights"를 공유할 뿐만 아니라 사용자가 작은 전략적 코드 조각을 직접 작성하도록 요청합니다. Claude Code는 구현할 코드에 `TODO(human)` 마커를 추가합니다.25* **Learning**: 협업 방식의 학습 모드로, Claude는 코딩하면서 "Insights"를 공유할 뿐만 아니라 사용자가 작은 전략적 코드 조각을 직접 작성하도록 요청합니다. Claude Code는 구현할 코드에 `TODO(human)` 마커를 추가합니다.

25 26 

26## 출력 스타일의 작동 방식

27 

28출력 스타일은 Claude Code의 시스템 프롬프트를 직접 수정합니다.

29 

30* 사용자 정의 출력 스타일은 `keep-coding-instructions`가 true가 아닌 한 코딩 관련 지침(테스트를 통한 코드 검증 등)을 제외합니다.

31* 모든 출력 스타일은 시스템 프롬프트 끝에 추가된 자체 사용자 정의 지침을 가집니다.

32* 모든 출력 스타일은 대화 중에 Claude가 출력 스타일 지침을 준수하도록 상기시키는 알림을 트리거합니다.

33 

34토큰 사용량은 스타일에 따라 다릅니다. 시스템 프롬프트에 지침을 추가하면 입력 토큰이 증가하지만, prompt caching은 세션의 첫 번째 요청 이후 이 비용을 줄입니다. 기본 제공 Explanatory 및 Learning 스타일은 설계상 Default보다 더 긴 응답을 생성하므로 출력 토큰이 증가합니다. 사용자 정의 스타일의 경우, 출력 토큰 사용량은 지침이 Claude에게 생성하도록 지시하는 내용에 따라 달라집니다.

35 

36## 출력 스타일 변경27## 출력 스타일 변경

37 28 

38`/config`를 실행하고 **Output style**을 선택하여 메뉴에서 스타일을 선택합니다. 선택 사항은 [로컬 프로젝트 수준](/ko/settings)의 `.claude/settings.local.json`에 저장됩니다.29`/config`를 실행하고 **Output style**을 선택하여 메뉴에서 스타일을 선택합니다. 선택 사항은 [로컬 프로젝트 수준](/ko/settings)의 `.claude/settings.local.json`에 저장됩니다.


49 40 

50## 사용자 정의 출력 스타일 만들기41## 사용자 정의 출력 스타일 만들기

51 42 

52사용자 정의 출력 스타일은 frontmatter와 시스템 프롬프트에 추가될 텍스트가 포함된 Markdown 파일입니다:43사용자 정의 출력 스타일은 Markdown 파일입니다: frontmatter는 메타데이터용이고, 다음에 시스템 프롬프트에 추가할 지침이 있습니다.

53 44 

54```markdown theme={null}45<Steps>

55name: My Custom Style46 <Step title="Markdown 파일 만들기">

56description:47 세 가지 수준 중 하나에 저장합니다. 파일 이름이 스타일 이름이 되며, frontmatter에서 `name`을 설정하지 않는 한 그렇습니다.

57 A brief description of what this style does, to be displayed to the user

58 48 

59# Custom Style Instructions49 * 사용자: `~/.claude/output-styles`

50 * 프로젝트: `.claude/output-styles`

51 * 관리형 정책: [관리형 설정 디렉토리](/ko/settings#settings-files) 내의 `.claude/output-styles`

52 </Step>

60 53 

61You are an interactive CLI tool that helps users with software engineering54 <Step title="Frontmatter 지침 추가">

62tasks. [Your custom instructions here...]55 Claude Code의 소프트웨어 엔지니어링 지침을 유지할지 여부를 결정합니다. Claude가 통신 방식을 변경하지만 여전히 동일한 방식으로 코딩하기를 원하면 `keep-coding-instructions: true`를 설정합니다. Claude가 소프트웨어 엔지니어링을 수행하지 않을 경우 제외합니다.

63 56 

64## Specific Behaviors57 예제는 Claude의 코딩 동작을 유지하면서 모든 설명 앞에 다이어그램을 배치합니다:

65 58 

66[Define how the assistant should behave in this style...]59 ```markdown theme={null}

67```60 ---

61 name: Diagrams first

62 description: Lead every explanation with a diagram

63 keep-coding-instructions: true

64 ---

68 65 

69이러한 파일은 가지 수준에 저장할 있습니다:66 When explaining code, architecture, or data flow, start with a Mermaid diagram showing the structure, then explain in prose.

70 67 

71* 사용자: `~/.claude/output-styles`68 ## Diagram conventions

72* 프로젝트: `.claude/output-styles`69 

73* 관리형 정책: [관리형 설정 디렉토리](/ko/settings#settings-files) 내의 `.claude/output-styles`70 Use `flowchart TD` for control flow and `sequenceDiagram` for request paths. Keep diagrams under 15 nodes.

71 ```

72 </Step>

73 

74 <Step title="스타일로 전환">

75 `/config`를 실행하고 **Output style** 아래에서 스타일을 선택합니다. 새 세션을 시작할 때 적용됩니다.

76 </Step>

77</Steps>

74 78 

75[플러그인](/ko/plugins-reference)도 `output-styles/` 디렉토리에 출력 스타일을 포함할 수 있습니다.79[플러그인](/ko/plugins-reference)도 `output-styles/` 디렉토리에 출력 스타일을 포함할 수 있습니다.

76 80 

77### Frontmatter81### Frontmatter

78 82 

79출력 스타일 파일은 메타데이터 지정을 위한 frontmatter를 지원합니다:83출력 스타일 파일은 다음 frontmatter 필드를 지원합니다:

80 84 

81| Frontmatter | 목적 | 기본값 |85| Frontmatter | 목적 | 기본값 |

82| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- | :--------- |86| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- | :--------- |

83| `name` | 출력 스타일의 이름(파일 이름이 아닌 경우) | 파일 이름에서 상속 |87| `name` | 파일 이름이 아닌 경우 출력 스타일의 이름 | 파일 이름에서 상속 |

84| `description` | `/config` 선택기에 표시되는 출력 스타일의 설명 | 없음 |88| `description` | `/config` 선택기에 표시되는 출력 스타일의 설명 | 없음 |

85| `keep-coding-instructions` | Claude Code의 시스템 프롬프트의 코딩 관련 부분을 유지할지 여부 | false |89| `keep-coding-instructions` | Claude Code의 기본 제공 소프트웨어 엔지니어링 지침 유지 | `false` |

86| `force-for-plugin` | 플러그인 출력 스타일만 해당: 사용자가 선택하지 않아도 플러그인이 활성화될 때마다 이 스타일을 자동으로 적용합니다. 사용자의 `outputStyle` 설정을 재정의합니다. 여러 활성화된 플러그인이 이를 설정하면 먼저 로드된 것이 우선합니다. | false |90| `force-for-plugin` | 플러그인 출력 스타일만 해당: 사용자가 선택하지 않아도 플러그인이 활성화될 때마다 이 스타일을 자동으로 적용합니다. 사용자의 `outputStyle` 설정을 재정의합니다. 여러 활성화된 플러그인이 이를 설정하면 먼저 로드된 것이 우선합니다. | `false` |

87 91 

88## 관련 기능과의 비교92## 출력 스타일의 작동 방식

93 

94출력 스타일은 Claude Code의 시스템 프롬프트를 직접 수정합니다.

89 95 

90### 출력 스타일 vs. CLAUDE.md vs. --append-system-prompt96* 모든 출력 스타일은 시스템 프롬프트 끝에 추가된 자체 사용자 정의 지침을 가집니다.

97* 모든 출력 스타일은 대화 중에 Claude가 출력 스타일 지침을 준수하도록 상기시키는 알림을 트리거합니다.

98* 사용자 정의 출력 스타일은 `keep-coding-instructions`가 `true`로 설정되지 않는 한 범위 지정, 주석 작성, 작업 검증 방법과 같은 Claude Code의 기본 제공 소프트웨어 엔지니어링 지침을 제외합니다.

91 99 

92Claude가 코딩 어시스턴트로서의 역할을 중단할지 아니면 기본 역할을 유지하고 더 많이 학습할지에 따라 선택합니다. 출력 스타일은 Claude Code의 시스템 프롬프트에서 소프트웨어 엔지니어링 부분을 사용자의 역할과 음성으로 바꾸므로, Claude가 글쓰기 편집자나 데이터 분석 어시스턴트와 같은 다른 정체성을 채택해야 사용합니다. CLAUDE.md와 `--append-system-prompt`는 모두 Claude Code의 기본 정체성을 유지하고 여기에 추가하므로, Claude가 프로젝트 규칙이나 추가 지침을 따르는 코딩 어시스턴트로 남아야 사용합니다.100토큰 사용량은 스타일에 따라 다릅니다. 시스템 프롬프트에 지침을 추가하면 입력 토큰이 증가하지만, prompt caching은 세션의 번째 요청 이후 비용을 줄입니다. 기본 제공 Explanatory Learning 스타일은 설계상 Default보다 응답을 생성하므로 출력 토큰이 증가합니다. 사용자 정의 스타일의 경우, 출력 토큰 사용량은 지침이 Claude에게 생성하도록 지시하는 내용에 따라 달라집니다.

93 101 

94메커니즘도 다릅니다. 출력 스타일은 시스템 프롬프트를 직접 편집합니다. CLAUDE.md는 시스템 프롬프트 이후에 사용자 메시지로 내용을 추가합니다. `--append-system-prompt`는 아무것도 제거하지 않고 시스템 프롬프트의 끝에 내용을 추가합니다.102## 관련 기능과의 비교

95 103 

96### 출력 스타일 vs. [Agents](/ko/sub-agents)104여러 기능이 Claude Code의 동작을 사용자 정의합니다. 출력 스타일은 시스템 프롬프트를 직접 수정하고 모든 응답에 적용됩니다. 다른 기능들은 기본 시스템 프롬프트를 변경하지 않고 지침을 추가하거나 특정 작업으로 범위를 지정합니다.

97 105 

98모든 세션에서 주 대화가 응답하는 방식을 변경하려면 출력 스타일을 사용합니다. 주 대화가 위임하는 별도로 범위가 지정된 도우미가 필요할 때는 [subagent](/ko/sub-agents)를 사용합니다. 출력 스타일은 주 에이전트 루프의 시스템 프롬프트에만 영향을 미칩니다. 에이전트는 특정 작업을 처리하며 자신의 모델, 도구, 호출 시기에 대한 컨텍스트를 가질 있습니다.106| 기능 | 작동 방식 | 사용 시기 |

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

108| 출력 스타일 | 시스템 프롬프트를 수정합니다 | 매 턴마다 다른 역할, 톤, 또는 기본 응답 형식을 원할 때 |

109| [CLAUDE.md](/ko/memory) | 시스템 프롬프트 이후에 사용자 메시지를 추가합니다 | Claude가 항상 프로젝트 규칙과 코드베이스 컨텍스트를 알아야 할 때 |

110| `--append-system-prompt` | 아무것도 제거하지 않고 시스템 프롬프트에 추가합니다 | 단일 호출을 위한 일회성 추가를 원할 때 |

111| [Agents](/ko/sub-agents) | 자신의 시스템 프롬프트, 모델, 도구를 가진 subagent를 실행합니다 | 초점이 맞춰진 작업을 위해 별도로 범위가 지정된 도우미를 원할 때 |

112| [Skills](/ko/skills) | 호출되거나 관련성이 있을 때 작업별 지침을 로드합니다 | 재사용 가능한 워크플로우가 있을 때 |

99 113 

100### 출력 스타일 vs. [Skills](/ko/skills)114## 관련 리소스

101 115 

102출력 스타일은 Claude가 응답하는 방식(형식, 톤, 구조)을 수정하며 선택되면 항상 활성화됩니다. Skills는 `/skill-name`으로 호출하거나 관련성이 있을 때 Claude가 자동으로 로드하는 작업별 프롬프트입니다. 일관된 형식 지정 기본 설정에는 출력 스타일을 사용하고, 재사용 가능한 워크플로우작업에는 skills를 사용합니다.116* [Settings](/ko/settings): `outputStyle` 필드가 있는 위치설정 우선순위 작동 방식

117* [Permission modes](/ko/permission-modes): Proactive 스타일은 권한 모드를 변경하지 않고 자동 모드를 미러링합니다

118* [Plugins](/ko/plugins): skills, hooks, agents와 함께 출력 스타일을 패키징하고 배포합니다

119* [Debug your configuration](/ko/debug-your-config): 출력 스타일이 적용되지 않는 이유를 진단합니다

permissions.md +5 −3

Details

138 138 

139#### 읽기 전용 명령139#### 읽기 전용 명령

140 140 

141Claude Code는 기본 제공 Bash 명령 집합을 읽기 전용으로 인식하고 모든 모드에서 권한 프롬프트 없이 실행합니다. 여기에는 `ls`, `cat`, `head`, `tail`, `grep`, `find`, `wc`, `diff`, `stat`, `du`, `cd` 및 `git`의 읽기 전용 형식이 포함됩니다. 집합은 구성할 수 없습니다. 이러한 명령 중 하나에 대해 프롬프트를 요구하려면 `ask` 또는 `deny` 규칙을 추가합니다.141Claude Code는 기본 제공 Bash 명령 집합을 읽기 전용으로 인식하고 모든 모드에서 권한 프롬프트 없이 실행합니다. 여기에는 `ls`, `cat`, `echo`, `pwd`, `head`, `tail`, `grep`, `find`, `wc`, `which`, `diff`, `stat`, `du`, `cd` 및 `git`의 읽기 전용 형식이 포함됩니다. 집합은 구성할 수 없습니다. 이러한 명령 중 하나에 대해 프롬프트를 요구하려면 `ask` 또는 `deny` 규칙을 추가합니다.

142 142 

143따옴표 없는 glob 패턴은 모든 플래그가 읽기 전용인 명령에 대해 허용되므로 `ls *.ts` 및 `wc -l src/*.py`는 프롬프트 없이 실행됩니다. `find`, `sort`, `sed` 및 `git`과 같이 쓰기 가능하거나 실행 가능한 플래그가 있는 명령은 glob이 `-delete`와 같은 플래그로 확장될 수 있으므로 따옴표 없는 glob이 있을 때 여전히 프롬프트합니다.143따옴표 없는 glob 패턴은 모든 플래그가 읽기 전용인 명령에 대해 허용되므로 `ls *.ts` 및 `wc -l src/*.py`는 프롬프트 없이 실행됩니다. `find`, `sort`, `sed` 및 `git`과 같이 쓰기 가능하거나 실행 가능한 플래그가 있는 명령은 glob이 `-delete`와 같은 플래그로 확장될 수 있으므로 따옴표 없는 glob이 있을 때 여전히 프롬프트합니다.

144 144 


290| `.claude/settings.json`의 플러그인 설정 | `enabledPlugins` 및 `extraKnownMarketplaces`만 |290| `.claude/settings.json`의 플러그인 설정 | `enabledPlugins` 및 `extraKnownMarketplaces`만 |

291| [CLAUDE.md](/ko/memory) 파일, `.claude/rules/` 및 `CLAUDE.local.md` | `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`이 설정된 경우에만. `CLAUDE.local.md`는 추가로 `local` 설정 소스가 필요하며, 이는 기본적으로 활성화됩니다 |291| [CLAUDE.md](/ko/memory) 파일, `.claude/rules/` 및 `CLAUDE.local.md` | `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`이 설정된 경우에만. `CLAUDE.local.md`는 추가로 `local` 설정 소스가 필요하며, 이는 기본적으로 활성화됩니다 |

292 292 

293서브에이전트, 명령, 출력 스타일, 기타 설정을 포함한 다른 모든 것은 현재 작업 디렉토리 해당 부모, `~/.claude/` 사용자 디렉토리 및 관리형 설정에서만 발견됩니다. 프로젝트 전체에서 해당 구성을 공유하려면 다음 방법 중 하나를 사용합니다:293서브에이전트, 명령, 출력 스타일은 현재 작업 디렉토리 및 해당 부모, `~/.claude/`의 사용자 디렉토리 관리형 설정에서 발견됩니다. 기타 `settings.json` 키는 현재 작업 디렉토리의 `.claude/` 폴더에서 로드되며 부모 디렉토리 폴백이 없고, 사용자 `~/.claude/settings.json` 및 관리형 설정과 함께 로드됩니다. 프로젝트 전체에서 해당 구성을 공유하려면 다음 방법 중 하나를 사용합니다:

294 294 

295* **사용자 수준 구성**: `~/.claude/agents/`, `~/.claude/output-styles/` 또는 `~/.claude/settings.json`에 파일을 배치하여 모든 프로젝트에서 사용 가능하게 합니다295* **사용자 수준 구성**: `~/.claude/agents/`, `~/.claude/output-styles/` 또는 `~/.claude/settings.json`에 파일을 배치하여 모든 프로젝트에서 사용 가능하게 합니다

296* **플러그인**: 팀이 설치할 수 있는 [플러그인](/ko/plugins)으로 구성을 패키징하고 배포합니다296* **플러그인**: 팀이 설치할 수 있는 [플러그인](/ko/plugins)으로 구성을 패키징하고 배포합니다


353 353 

354도구가 어느 수준에서든 거부되면 다른 수준은 이를 허용할 수 없습니다. 예를 들어, 관리형 설정 deny는 `--allowedTools`로 재정의할 수 없으며, `--disallowedTools`는 관리형 설정이 정의하는 것 이상의 제한을 추가할 수 있습니다.354도구가 어느 수준에서든 거부되면 다른 수준은 이를 허용할 수 없습니다. 예를 들어, 관리형 설정 deny는 `--allowedTools`로 재정의할 수 없으며, `--disallowedTools`는 관리형 설정이 정의하는 것 이상의 제한을 추가할 수 있습니다.

355 355 

356권한이 사용자 설정에서 허용되지만 프로젝트 설정에서 거부되면, 프로젝트 설정이 우선이며 권한이 차단됩니다.356Embedding hosts는 [`parentSettingsBehavior`](/ko/settings#settings-precedence)가 `"merge"`로 설정되어 있을 SDK `managedSettings` 옵션을 통해 추가 관리형 정책을 제공할 수 있습니다. Embedder 값은 정책을 강화할 수 있지만 완화할 수는 없습니다.

357 

358예를 들어, 사용자 설정에서 도구가 허용되고 프로젝트 설정에서 거부되면, deny 규칙이 이를 차단합니다. 그 반대도 마찬가지입니다: 사용자 수준의 deny는 프로젝트 수준의 allow를 차단합니다. 왜냐하면 모든 범위의 deny 규칙이 allow 규칙보다 먼저 평가되기 때문입니다.

357 359 

358## 예시 구성360## 예시 구성

359 361 

Details

516* **기본값에 추가**: `skills`. 기본 `skills/` 디렉토리는 항상 스캔되며, `skills`에 나열된 디렉토리는 함께 로드됩니다.516* **기본값에 추가**: `skills`. 기본 `skills/` 디렉토리는 항상 스캔되며, `skills`에 나열된 디렉토리는 함께 로드됩니다.

517* **자체 병합 규칙**: [hooks](#hooks), [MCP servers](#mcp-servers) 및 [LSP servers](#lsp-servers). 각 섹션에서 여러 소스가 어떻게 결합되는지 참조하세요.517* **자체 병합 규칙**: [hooks](#hooks), [MCP servers](#mcp-servers) 및 [LSP servers](#lsp-servers). 각 섹션에서 여러 소스가 어떻게 결합되는지 참조하세요.

518 518 

519플러그인에 기본 폴더와 일치하는 매니페스트 키가 모두 있으면 Claude Code v2.1.140 이상은 `/doctor`, `claude plugin list` 및 `/plugin` 상세 보기에서 무시된 폴더에 플래그를 지정합니다. 플러그인은 여전히 매니페스트 경로를 사용하여 로드됩니다. 매니페스트 키가 기본 폴더를 가리킬 때는 경고가 표시되지 않습니다 (예: `"commands": ["./commands/deploy.md"]`). 이 경우 폴더가 명시적으로 처리되기 때문입니다.

520 

519모든 경로 필드의 경우:521모든 경로 필드의 경우:

520 522 

521* 모든 경로는 플러그인 루트에 상대적이어야 하며 `./`로 시작해야 합니다.523* 모든 경로는 플러그인 루트에 상대적이어야 하며 `./`로 시작해야 합니다.

Details

170 170 

171이 설정을 활성화하기 전에 네트워크 정책이 `api.anthropic.com`에 대한 연결을 허용하는지 확인합니다. 해당 엔드포인트에 도달할 수 없으면 CLI는 시작 시 종료되고 사용자는 Claude Code를 시작할 수 없습니다.171이 설정을 활성화하기 전에 네트워크 정책이 `api.anthropic.com`에 대한 연결을 허용하는지 확인합니다. 해당 엔드포인트에 도달할 수 없으면 CLI는 시작 시 종료되고 사용자는 Claude Code를 시작할 수 없습니다.

172 172 

173v2.1.139 이상에서는 `claude auth` 하위 명령(예: `claude auth login`)이 이 확인에서 제외되므로 만료된 자격 증명이 설정 가져오기 실패의 원인인 경우 사용자가 다시 인증할 수 있습니다.

174 

173### 보안 승인 대화175### 보안 승인 대화

174 176 

175보안 위험을 초래할 수 있는 특정 설정은 적용되기 전에 명시적인 사용자 승인이 필요합니다.177보안 위험을 초래할 수 있는 특정 설정은 적용되기 전에 명시적인 사용자 승인이 필요합니다.


204서버 관리 설정은 중앙 집중식 정책 적용을 제공하지만 클라이언트 측 제어로 작동합니다. 관리되지 않는 기기에서 관리자 또는 sudo 액세스 권한이 있는 사용자는 Claude Code 바이너리, 파일 시스템 또는 네트워크 구성을 수정할 수 있습니다.206서버 관리 설정은 중앙 집중식 정책 적용을 제공하지만 클라이언트 측 제어로 작동합니다. 관리되지 않는 기기에서 관리자 또는 sudo 액세스 권한이 있는 사용자는 Claude Code 바이너리, 파일 시스템 또는 네트워크 구성을 수정할 수 있습니다.

205 207 

206| 시나리오 | 동작 |208| 시나리오 | 동작 |

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

208| 사용자가 캐시된 설정 파일을 편집함 | 변조된 파일이 시작 시 적용되지만 다음 서버 가져오기에서 올바른 설정이 복원됩니다. |210| 사용자가 캐시된 설정 파일을 편집함 | 변조된 파일이 시작 시 적용되지만 다음 서버 가져오기에서 올바른 설정이 복원됩니다. |

209| 사용자가 캐시된 설정 파일을 삭제함 | 첫 시작 동작이 발생합니다. 설정이 비동기적으로 가져오지며 짧은 적용되지 않은 시간이 있습니다. |211| 사용자가 캐시된 설정 파일을 삭제함 | 첫 시작 동작이 발생합니다. 설정이 비동기적으로 가져오지며 짧은 적용되지 않은 시간이 있습니다. |

210| API를 사용할 수 없음 | 캐시된 설정이 있으면 적용되고, 그렇지 않으면 다음 성공적인 가져오기까지 관리 설정이 적용되지 않습니다. `forceRemoteSettingsRefresh: true`를 사용하면 CLI는 계속하는 대신 종료됩니다. |212| API를 사용할 수 없음 | 캐시된 설정이 있으면 적용되고, 그렇지 않으면 다음 성공적인 가져오기까지 관리 설정이 적용되지 않습니다. `forceRemoteSettingsRefresh: true`를 사용하면 CLI는 계속하는 대신 종료됩니다. [`claude auth` 부분 명령](#enforce-fail-closed-startup) 제외 |

211| 사용자가 다른 조직으로 인증함 | 관리 조직 외부의 계정에 대해 설정이 전달되지 않습니다. |213| 사용자가 다른 조직으로 인증함 | 관리 조직 외부의 계정에 대해 설정이 전달되지 않습니다. |

212| 사용자가 [타사 모델 공급자](#platform-availability)를 구성함 | 서버 관리 설정이 우회됩니다. 여기에는 `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_MANTLE`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY` 설정 또는 기본이 아닌 `ANTHROPIC_BASE_URL` 설정이 포함됩니다. |214| 사용자가 [타사 모델 공급자](#platform-availability)를 구성함 | 서버 관리 설정이 우회됩니다. 여기에는 `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_MANTLE`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY` 설정 또는 기본이 아닌 `ANTHROPIC_BASE_URL` 설정이 포함됩니다. |

213 215 

settings.md +6 −4

Details

49 49 

50### 범위가 상호 작용하는 방식50### 범위가 상호 작용하는 방식

51 51 

52동일한 설정이 여러 범위에서 구성되면 구체적인 범위가 우선합니다:52동일한 설정이 여러 범위에서 구성되면 Claude Code는 우선순위 순서대로 적용합니다:

53 53 

541. **Managed** (최고) - 아무것도 재정의할 수 없음541. **Managed** (최고) - 아무것도 재정의할 수 없음

552. **명령줄 인수** - 임시 세션 재정의552. **명령줄 인수** - 임시 세션 재정의


574. **Project** - 사용자 설정 재정의574. **Project** - 사용자 설정 재정의

585. **User** (최저) - 다른 것이 설정을 지정하지 않을 때 적용585. **User** (최저) - 다른 것이 설정을 지정하지 않을 때 적용

59 59 

60예를 들어, 사용자 설정에서는 권한이 허용되지만 프로젝트 설정에서는 거부되면, 프로젝트 설정이 우선하고 권한이 차단됩니다.60예를 들어, 사용자 설정에서 `spinnerTipsEnabled`를 `true`로 설정하고 프로젝트 설정에서 `false`로 설정하면 프로젝트 값이 적용됩니다. 권한 규칙은 재정의하지 않고 범위 전체에서 병합되기 때문에 다르게 작동합니다. [설정 우선순위](#settings-precedence)를 참조하십시오.

61 61 

62### 범위를 사용하는 것62### 범위를 사용하는 것

63 63 


268| :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |268| :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |

269| `worktree.baseRef` | 새 worktrees가 분기하는 ref입니다. `"fresh"` (기본값)은 깨끗한 트리와 일치하는 원격에 대해 `origin/<default-branch>`에서 분기합니다. `"head"`는 현재 local `HEAD`에서 분기하므로 푸시되지 않은 커밋 및 feature-branch 상태가 worktree에 있습니다. `--worktree`, `EnterWorktree` 도구 및 subagent 격리에 적용됩니다 | `"head"` |269| `worktree.baseRef` | 새 worktrees가 분기하는 ref입니다. `"fresh"` (기본값)은 깨끗한 트리와 일치하는 원격에 대해 `origin/<default-branch>`에서 분기합니다. `"head"`는 현재 local `HEAD`에서 분기하므로 푸시되지 않은 커밋 및 feature-branch 상태가 worktree에 있습니다. `--worktree`, `EnterWorktree` 도구 및 subagent 격리에 적용됩니다 | `"head"` |

270| `worktree.symlinkDirectories` | 각 worktree에서 중복을 피하기 위해 메인 저장소에서 symlink할 디렉토리입니다. 기본적으로 디렉토리는 symlink되지 않습니다 | `["node_modules", ".cache"]` |270| `worktree.symlinkDirectories` | 각 worktree에서 중복을 피하기 위해 메인 저장소에서 symlink할 디렉토리입니다. 기본적으로 디렉토리는 symlink되지 않습니다 | `["node_modules", ".cache"]` |

271| `worktree.sparsePaths` | git sparse-checkout (cone mode)을 통해 각 worktree에서 체크아웃할 디렉토리입니다. 나열된 경로만 디스크에 작성되므로 대규모 monorepos에서 더 빠릅니다 | `["packages/my-app", "shared/utils"]` |271| `worktree.sparsePaths` | git sparse-checkout을 통해 각 worktree에서 체크아웃할 디렉토리입니다. 나열된 경로만 디스크에 작성되므로 대규모 monorepos에서 더 빠릅니다 | `["packages/my-app", "shared/utils"]` |

272 272 

273worktrees에 `.env`와 같은 gitignored 파일을 복사하려면 설정 대신 프로젝트 루트의 [`.worktreeinclude` 파일](/ko/worktrees#copy-gitignored-files-into-worktrees)을 사용합니다.273worktrees에 `.env`와 같은 gitignored 파일을 복사하려면 설정 대신 프로젝트 루트의 [`.worktreeinclude` 파일](/ko/worktrees#copy-gitignored-files-into-worktrees)을 사용합니다.

274 274 


525 525 

526이 계층 구조는 조직 정책이 항상 적용되면서도 팀과 개인이 자신의 경험을 사용자 정의할 수 있도록 보장합니다. CLI, [VS Code 확장](/ko/vs-code) 또는 [JetBrains IDE](/ko/jetbrains)에서 Claude Code를 실행하든 동일한 우선순위가 적용됩니다.526이 계층 구조는 조직 정책이 항상 적용되면서도 팀과 개인이 자신의 경험을 사용자 정의할 수 있도록 보장합니다. CLI, [VS Code 확장](/ko/vs-code) 또는 [JetBrains IDE](/ko/jetbrains)에서 Claude Code를 실행하든 동일한 우선순위가 적용됩니다.

527 527 

528예를 들어 사용자 설정이 `Bash(npm run *)` 허용하지만 프로젝트의 공유 설정이 이를 거부하면 프로젝트 설정이 우선하고 명령이 차단됩니다.528예를 들어 사용자 설정이 `permissions.defaultMode`를 `acceptEdits`로 설정하지만 프로젝트의 공유 설정이 이를 `default`로 설정하면 프로젝트 값이 적용됩니다. 아래 예제는 배열 값 설정 (예: 권한 규칙)이 대신 어떻게 결합되는지를 다룹니다.

529 529 

530<Note>530<Note>

531 **배열 설정은 범위 전체에서 병합됩니다.** 동일한 배열 값 설정 (예: `sandbox.filesystem.allowWrite` 또는 `permissions.allow`)이 여러 범위에 나타나면 배열은 **연결되고 중복 제거되며** 대체되지 않습니다. 이는 낮은 우선순위 범위가 높은 우선순위 범위에서 설정한 항목을 재정의하지 않고 항목을 추가할 수 있음을 의미하며 그 반대도 마찬가지입니다. 예를 들어 managed 설정이 `allowWrite`를 `["/opt/company-tools"]`로 설정하고 사용자가 `["~/.kube"]`를 추가하면 두 경로 모두 최종 구성에 포함됩니다.531 **배열 설정은 범위 전체에서 병합됩니다.** 동일한 배열 값 설정 (예: `sandbox.filesystem.allowWrite` 또는 `permissions.allow`)이 여러 범위에 나타나면 배열은 **연결되고 중복 제거되며** 대체되지 않습니다. 이는 낮은 우선순위 범위가 높은 우선순위 범위에서 설정한 항목을 재정의하지 않고 항목을 추가할 수 있음을 의미하며 그 반대도 마찬가지입니다. 예를 들어 managed 설정이 `allowWrite`를 `["/opt/company-tools"]`로 설정하고 사용자가 `["~/.kube"]`를 추가하면 두 경로 모두 최종 구성에 포함됩니다.


672* `hostPattern`: 마켓플레이스 호스트와 일치하는 정규식 패턴 (`hostPattern` 사용)672* `hostPattern`: 마켓플레이스 호스트와 일치하는 정규식 패턴 (`hostPattern` 사용)

673* `settings`: 별도의 호스팅 저장소 없이 settings.json에 직접 선언된 인라인 마켓플레이스 (`name` 및 `plugins` 사용)673* `settings`: 별도의 호스팅 저장소 없이 settings.json에 직접 선언된 인라인 마켓플레이스 (`name` 및 `plugins` 사용)

674 674 

675각 마켓플레이스 항목은 선택적 `autoUpdate` Boolean도 허용합니다. `source`와 함께 `"autoUpdate": true`를 설정하여 Claude Code가 해당 마켓플레이스를 새로고침하고 시작 시 설치된 플러그인을 업데이트하도록 합니다. 생략하면 공식 Anthropic 마켓플레이스는 기본값이 `true`이고 다른 모든 마켓플레이스는 기본값이 `false`입니다. [자동 업데이트 구성](/ko/discover-plugins#configure-auto-updates)을 참조하세요.

676 

675`source: 'settings'`를 사용하여 호스팅된 마켓플레이스 저장소를 설정하지 않고 작은 플러그인 세트를 인라인으로 선언합니다. 여기에 나열된 플러그인은 GitHub 또는 npm과 같은 외부 소스를 참조해야 합니다. 여전히 `enabledPlugins`에서 각 플러그인을 별도로 활성화해야 합니다.677`source: 'settings'`를 사용하여 호스팅된 마켓플레이스 저장소를 설정하지 않고 작은 플러그인 세트를 인라인으로 선언합니다. 여기에 나열된 플러그인은 GitHub 또는 npm과 같은 외부 소스를 참조해야 합니다. 여전히 `enabledPlugins`에서 각 플러그인을 별도로 활성화해야 합니다.

676 678 

677```json theme={null}679```json theme={null}

skills.md +2 −2

Details

97 97 

98Claude Code는 skill 디렉토리의 파일 변경을 감시합니다. `~/.claude/skills/`, 프로젝트 `.claude/skills/`, 또는 `--add-dir` 디렉토리 내의 `.claude/skills/` 아래에서 skill을 추가, 편집 또는 제거하면 Claude Code를 다시 시작하지 않고도 현재 세션 내에서 적용됩니다. 세션이 시작되었을 때 존재하지 않았던 최상위 skills 디렉토리를 생성하려면 Claude Code를 다시 시작해야 새 디렉토리를 감시할 수 있습니다.98Claude Code는 skill 디렉토리의 파일 변경을 감시합니다. `~/.claude/skills/`, 프로젝트 `.claude/skills/`, 또는 `--add-dir` 디렉토리 내의 `.claude/skills/` 아래에서 skill을 추가, 편집 또는 제거하면 Claude Code를 다시 시작하지 않고도 현재 세션 내에서 적용됩니다. 세션이 시작되었을 때 존재하지 않았던 최상위 skills 디렉토리를 생성하려면 Claude Code를 다시 시작해야 새 디렉토리를 감시할 수 있습니다.

99 99 

100#### 중첩된 디렉토리에서 자동 검색100#### 상위 및 중첩된 디렉토리에서 자동 검색

101 101 

102하위 디렉토리의 파일로 작업할 때, Claude Code는 중첩된 `.claude/skills/` 디렉토리에서 skills를 자동으로 검색합니다. 예를 들어, `packages/frontend/`의 파일을 편집하는 경우, Claude Code는 `packages/frontend/.claude/skills/`에서도 skills를 찾습니다. 이는 패키지가 자신의 skills를 가진 monorepo 설정을 지원합니다.102프로젝트 skills는 시작 디렉토리의 `.claude/skills/`와 저장소 루트까지의 모든 상위 디렉토리에서 로드되므로, 하위 디렉토리에서 Claude를 시작해도 루트에서 정의된 skills를 선택합니다. 시작 디렉토리 아래의 하위 디렉토리에 있는 파일로 작업할 때, Claude Code는 필요에 따라 중첩된 `.claude/skills/` 디렉토리에서 skills를 검색합니다. 예를 들어, `packages/frontend/`의 파일을 편집하는 경우, Claude Code는 `packages/frontend/.claude/skills/`에서도 skills를 찾습니다. 이는 패키지가 자신의 skills를 가진 monorepo 설정을 지원합니다.

103 103 

104각 skill은 `SKILL.md`를 진입점으로 하는 디렉토리입니다:104각 skill은 `SKILL.md`를 진입점으로 하는 디렉토리입니다:

105 105 

ultrareview.md +4 −4

Details

49Ultrareview는 플랜의 포함된 사용량이 아닌 추가 사용량에 대해 청구되는 프리미엄 기능입니다.49Ultrareview는 플랜의 포함된 사용량이 아닌 추가 사용량에 대해 청구되는 프리미엄 기능입니다.

50 50 

51| 플랜 | 포함된 무료 실행 | 무료 실행 후 |51| 플랜 | 포함된 무료 실행 | 무료 실행 후 |

52| ----------------- | ---------------------- | ------------------------------------------------------------------------------------------------- |52| ----------------- | --------- | ------------------------------------------------------------------------------------------------- |

53| Pro | 2026년 5월 5일까지 3회 무료 실행 | [추가 사용량](https://support.claude.com/ko/articles/12429409-extra-usage-for-paid-claude-plans)으로 청구됨 |53| Pro | 3회 무료 실행 | [추가 사용량](https://support.claude.com/ko/articles/12429409-extra-usage-for-paid-claude-plans)으로 청구됨 |

54| Max | 2026년 5월 5일까지 3회 무료 실행 | [추가 사용량](https://support.claude.com/ko/articles/12429409-extra-usage-for-paid-claude-plans)으로 청구됨 |54| Max | 3회 무료 실행 | [추가 사용량](https://support.claude.com/ko/articles/12429409-extra-usage-for-paid-claude-plans)으로 청구됨 |

55| Team 및 Enterprise | 없음 | [추가 사용량](https://support.claude.com/ko/articles/12429409-extra-usage-for-paid-claude-plans)으로 청구됨 |55| Team 및 Enterprise | 없음 | [추가 사용량](https://support.claude.com/ko/articles/12429409-extra-usage-for-paid-claude-plans)으로 청구됨 |

56 56 

57Pro 및 Max 구독자는 기능을 시도하기 위해 3회의 무료 ultrareview 실행을 받습니다. 이 3회 실행은 계정당 일회성 할당이며 새로 고쳐지지 않으며 2026년 5월 5일에 만료됩니다. 3회를 모두 사용한 후 또는 무료 실행 기간이 끝난 후 각 리뷰는 추가 사용량으로 청구되며 일반적으로 변경 사항의 크기에 따라 $5에서 $20의 비용이 듭니다. 원격 세션이 시작되면 실행이 계산되므로 조기에 중단하거나 완료되지 않은 리뷰도 무료 실행을 사용합니다. 유료 리뷰의 경우 추가 사용량은 실행된 부분에 대해서만 청구됩니다.57Pro 및 Max 구독자는 기능을 시도하기 위해 3회의 무료 ultrareview 실행을 받습니다. 이 3회 실행은 계정당 일회성 할당이며 새로 고쳐지지 않습니다. 3회를 모두 사용한 후 또는 무료 실행 기간이 끝난 후 각 리뷰는 추가 사용량으로 청구되며 일반적으로 변경 사항의 크기에 따라 $5에서 $20의 비용이 듭니다. 원격 세션이 시작되면 실행이 계산되므로 조기에 중단하거나 완료되지 않은 리뷰도 무료 실행을 사용합니다. 유료 리뷰의 경우 추가 사용량은 실행된 부분에 대해서만 청구됩니다.

58 58 

59Ultrareview는 항상 무료 실행 외에 추가 사용량으로 청구되기 때문에 계정 또는 조직은 유료 리뷰를 시작하기 전에 추가 사용량을 활성화해야 합니다. 추가 사용량이 활성화되지 않은 경우 Claude Code는 시작을 차단하고 켤 수 있는 청구 설정으로 연결합니다. `/extra-usage`를 실행하여 현재 설정을 확인하거나 변경할 수도 있습니다.59Ultrareview는 항상 무료 실행 외에 추가 사용량으로 청구되기 때문에 계정 또는 조직은 유료 리뷰를 시작하기 전에 추가 사용량을 활성화해야 합니다. 추가 사용량이 활성화되지 않은 경우 Claude Code는 시작을 차단하고 켤 수 있는 청구 설정으로 연결합니다. `/extra-usage`를 실행하여 현재 설정을 확인하거나 변경할 수도 있습니다.

60 60