SpyBara
Go Premium

Documentation 2026-06-16 21:57 UTC to 2026-06-17 17:02 UTC

118 files changed +6,879 −1,306. View all changes and history on the product overview
2026
Thu 18 02:02 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

admin-setup.md +24 −9

Details

22| [사용량 가시성 설정](#set-up-usage-visibility) | 지출 및 채택을 추적하는 방식 | [Analytics](/ko/analytics), [Monitoring](/ko/monitoring-usage), [Costs](/ko/costs) |22| [사용량 가시성 설정](#set-up-usage-visibility) | 지출 및 채택을 추적하는 방식 | [Analytics](/ko/analytics), [Monitoring](/ko/monitoring-usage), [Costs](/ko/costs) |

23| [데이터 처리 검토](#review-data-handling) | 데이터 보존 및 규정 준수 태세 | [Data usage](/ko/data-usage), [Security](/ko/security) |23| [데이터 처리 검토](#review-data-handling) | 데이터 보존 및 규정 준수 태세 | [Data usage](/ko/data-usage), [Security](/ko/security) |

24 24 

25## API 제공자 선택25<h2 id="choose-your-api-provider">

26 API 제공자 선택

27</h2>

26 28 

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

28 30 


40 42 

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

42 44 

43## 설정이 기기에 도달하는 방식 결정45<h2 id="decide-how-settings-reach-devices">

46 설정이 기기에 도달하는 방식 결정

47</h2>

44 48 

45관리 설정은 로컬 개발자 구성보다 우선하는 정책을 정의합니다. Claude Code는 네 가지 위치에서 이를 찾으며 주어진 기기에서 찾은 첫 번째 위치를 사용합니다.49관리 설정은 로컬 개발자 구성보다 우선하는 정책을 정의합니다. Claude Code는 아래의 네 가지 소스를 우선순위 순서대로 확인하고 비어 있지 않은 구성을 반환하는 첫 번째 소스를 적용합니다.

46 50 

47| 메커니즘 | 전달 | 우선순위 | 플랫폼 |51| 메커니즘 | 전달 | 우선순위 | 플랫폼 |

48| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--- | :------------- |52| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--- | :------------- |


63 67 

64[Server-managed settings](/ko/server-managed-settings) 및 [Settings files and precedence](/ko/settings#settings-files)를 참조하세요.68[Server-managed settings](/ko/server-managed-settings) 및 [Settings files and precedence](/ko/settings#settings-files)를 참조하세요.

65 69 

66## 시행할 항목 결정70<h2 id="decide-what-to-enforce">

71 시행할 항목 결정

72</h2>

67 73 

68관리 설정은 도구, 샌드박스 실행, MCP 서버 및 플러그인 소스 제한, 실행되는 hooks 제어를 잠글 수 있습니다. 각 행은 이를 구동하는 설정 키가 있는 제어 표면입니다.74관리 설정은 도구, 샌드박스 실행, MCP 서버 및 플러그인 소스 제한, 실행되는 hooks 제어를 잠글 수 있습니다. 각 행은 이를 구동하는 설정 키가 있는 제어 표면입니다.

69 75 


79| [Hook restrictions](/ko/settings#hook-configuration) | 관리 hooks만 로드; HTTP hook URL 제한 | `allowManagedHooksOnly`, `allowedHttpHookUrls` |85| [Hook restrictions](/ko/settings#hook-configuration) | 관리 hooks만 로드; HTTP hook URL 제한 | `allowManagedHooksOnly`, `allowedHttpHookUrls` |

80| [Disable agent view](/ko/agent-view#how-background-sessions-are-hosted) | `claude agents`, `--bg`, `/background` 및 온디맨드 감독자 비활성화 | `disableAgentView` |86| [Disable agent view](/ko/agent-view#how-background-sessions-are-hosted) | `claude agents`, `--bg`, `/background` 및 온디맨드 감독자 비활성화 | `disableAgentView` |

81| [Version floor](/ko/settings) | 자동 업데이트가 조직 전체 최소값 아래로 설치되는 것을 방지 | `minimumVersion` |87| [Version floor](/ko/settings) | 자동 업데이트가 조직 전체 최소값 아래로 설치되는 것을 방지 | `minimumVersion` |

88| [Required version range](/ko/settings) | 실행 중인 버전이 조직 승인 범위를 벗어날 때 시작을 거부합니다. 다운그레이드만 차단하는 `minimumVersion`보다 더 강력합니다 | `requiredMinimumVersion`, `requiredMaximumVersion` |

82 89 

83권한 규칙 및 샌드박싱은 다양한 계층을 다룹니다. WebFetch를 거부하면 Claude의 fetch 도구가 차단되지만 Bash가 허용되면 `curl` 및 `wget`은 여전히 모든 URL에 도달할 수 있습니다. 샌드박싱은 OS 수준에서 시행되는 네트워크 도메인 허용 목록으로 그 격차를 닫습니다.90권한 규칙 및 샌드박싱은 다양한 계층을 다룹니다. WebFetch를 거부하면 Claude의 fetch 도구가 차단되지만 Bash가 허용되면 `curl` 및 `wget`은 여전히 모든 URL에 도달할 수 있습니다. 샌드박싱은 OS 수준에서 시행되는 네트워크 도메인 허용 목록으로 그 격차를 닫습니다.

84 91 

85이러한 제어가 방어하는 위협 모델은 [Security](/ko/security)를 참조하세요.92이러한 제어가 방어하는 위협 모델은 [Security](/ko/security)를 참조하세요.

86 93 

87## 사용량 가시성 설정94<h2 id="set-up-usage-visibility">

95 사용량 가시성 설정

96</h2>

88 97 

89필요한 보고 내용에 따라 모니터링을 선택하세요.98필요한 보고 내용에 따라 모니터링을 선택하세요.

90 99 


96 105 

97클라우드 제공자는 AWS Cost Explorer, GCP Billing 또는 Azure Cost Management를 통해 지출을 노출합니다. Claude for Teams 및 Enterprise 플랜에는 [claude.ai/analytics/claude-code](https://claude.ai/analytics/claude-code)의 사용량 대시보드가 포함됩니다.106클라우드 제공자는 AWS Cost Explorer, GCP Billing 또는 Azure Cost Management를 통해 지출을 노출합니다. Claude for Teams 및 Enterprise 플랜에는 [claude.ai/analytics/claude-code](https://claude.ai/analytics/claude-code)의 사용량 대시보드가 포함됩니다.

98 107 

99## 데이터 처리 검토108<h2 id="review-data-handling">

109 데이터 처리 검토

110</h2>

100 111 

101Team, Enterprise, Claude API 및 클라우드 제공자 플랜에서 Anthropic은 코드 또는 프롬프트에 대해 모델을 학습하지 않습니다. API 제공자가 보존 및 규정 준수 태세를 결정합니다.112Team, Enterprise, Claude API 및 클라우드 제공자 플랜에서 Anthropic은 코드 또는 프롬프트에 대해 모델을 학습하지 않습니다. API 제공자가 보존 및 규정 준수 태세를 결정합니다.

102 113 


108 119 

109요청 수준 감사 로깅이 필요하거나 데이터 민감도별로 트래픽을 라우팅하려면 개발자와 제공자 사이에 [LLM gateway](/ko/llm-gateway)를 배치하세요. 규제 요구사항 및 인증은 [Legal and compliance](/ko/legal-and-compliance)를 참조하세요.120요청 수준 감사 로깅이 필요하거나 데이터 민감도별로 트래픽을 라우팅하려면 개발자와 제공자 사이에 [LLM gateway](/ko/llm-gateway)를 배치하세요. 규제 요구사항 및 인증은 [Legal and compliance](/ko/legal-and-compliance)를 참조하세요.

110 121 

111## 확인 및 온보딩122<h2 id="verify-and-onboard">

123 확인 및 온보딩

124</h2>

112 125 

113관리 설정을 구성한 후 개발자가 Claude Code 내에서 `/status`를 실행하도록 하세요. 출력에는 `Enterprise managed settings` 시작하는 줄이 포함되며 뒤에 괄호 안의 소스가 `(remote)`, `(plist)`, `(HKLM)`, `(HKCU)` 또는 `(file)` 중 하나입니다. [활성 설정 확인](/ko/settings#verify-active-settings)을 참조하세요.126관리 설정을 구성한 후 개발자가 Claude Code 내에서 `/status`를 실행하도록 하세요. **Status** 탭에서 `Setting sources` 줄은 `Enterprise managed settings` 다음에 괄호 안의 소스를 표시하며, 이는 `(remote)`, `(plist)`, `(HKLM)`, `(HKCU)` 또는 `(file)` 중 하나입니다. [활성 설정 확인](/ko/settings#verify-active-settings)을 참조하세요.

114 127 

115개발자가 시작하는 데 도움이 되도록 다음 리소스를 공유하세요:128개발자가 시작하는 데 도움이 되도록 다음 리소스를 공유하세요:

116 129 


126 139 

127개발자가 "You haven't been added to your organization yet"을 보면 해당 시트에 Claude Code 액세스가 포함되지 않으며 관리자 콘솔에서 업데이트해야 합니다.140개발자가 "You haven't been added to your organization yet"을 보면 해당 시트에 Claude Code 액세스가 포함되지 않으며 관리자 콘솔에서 업데이트해야 합니다.

128 141 

129## 다음 단계142<h2 id="next-steps">

143 다음 단계

144</h2>

130 145 

131제공자 및 전달 메커니즘을 선택한 후 자세한 구성으로 이동하세요:146제공자 및 전달 메커니즘을 선택한 후 자세한 구성으로 이동하세요:

132 147 

advisor.md +198 −0 created

Details

1> ## Documentation Index

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

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

4 

5# 어려운 결정을 조언자 도구로 에스컬레이션하기

6 

7> 주 모델을 더 강력한 조언자 모델과 쌍으로 만들어 Claude가 작업 중 핵심 순간에 조언자를 참고하도록 합니다.

8 

9{/* plan-availability: feature=advisor providers=anthropic */}

10 

11<Note>

12 조언자 도구는 실험적이며 Anthropic API를 사용하는 Claude Code v2.1.98 이상이 필요합니다. Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry에서는 사용할 수 없습니다. 동작, 가격 책정 및 가용성은 변경될 수 있습니다.

13</Note>

14 

15조언자 도구를 사용하면 Claude가 작업 중 핵심 순간(예: 접근 방식을 확정하기 전, 반복되는 오류에 막혔을 때, 작업 완료를 선언하기 전)에 일반적으로 더 강력한 두 번째 모델을 참고할 수 있습니다. 조언자는 모든 도구 호출 및 결과를 포함한 전체 대화를 받고 Claude가 계속하기 전에 적용할 지침을 반환합니다.

16 

17조언자는 Anthropic의 인프라에서 서버 측으로 실행되며 [서버 도구](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool)로 구독 및 API 청구 계정 모두에서 사용할 수 있습니다. 조언자로 작동할 모델을 선택하고 Claude가 호출 시기를 결정합니다.

18 

19이 페이지에서는 조언자를 활성화하는 방법, 허용되는 모델 쌍, Claude가 상담 중에 표시하는 내용, 조언자 사용이 청구되는 방식을 다룹니다.

20 

21<h2 id="when-to-use-the-advisor">

22 조언자를 사용할 때

23</h2>

24 

25조언자는 대부분의 턴이 일상적이지만 계획 품질이 결과를 결정하는 길고 다단계 작업에 적합합니다. 예시로는 대규모 리팩토링, 오류가 계속 반복되는 디버깅 세션, Claude가 완료를 선언하기 전에 독립적으로 확인하고 싶은 작업이 있습니다.

26 

27계획할 것이 거의 없는 짧은 작업이나 모든 턴에 가장 강력한 모델이 필요한 작업에서는 가치가 적습니다. 이러한 경우 [주 모델을 전환](/ko/model-config#setting-your-model)하거나 [조언자와 opusplan 및 서브에이전트 비교](#compare-with-related-features)를 참고하여 두 번째 의견을 얻는 다른 방법을 확인하세요.

28 

29<h2 id="enable-the-advisor">

30 조언자 활성화

31</h2>

32 

33조언자 모델을 세 가지 방법으로 설정할 수 있습니다:

34 

35* **`/advisor` 명령**: 세션 중간에 조언자를 설정 또는 변경하고 기본값으로 저장

36* **`advisorModel` 설정**: [설정 파일](/ko/settings)에서 지속적인 기본값 구성

37* **`--advisor` 플래그**: 시작 시 단일 세션에 대해 조언자 설정

38 

39이 중 하나가 조언자 모델을 설정하면 주 모델이 [이를 지원](#choose-an-advisor-model)하는 세션에 대해 조언자가 활성화됩니다. 사용을 중지하려면 [조언자 끄기](#turn-the-advisor-off)를 참고하세요.

40 

41<Note>

42 Fable 5를 조언자로 사용하려면 Claude Code v2.1.170 이상과 조직의 [Fable 5 액세스](/ko/model-config#work-with-fable-5)가 필요합니다.

43</Note>

44 

45<h3 id="use-the-/advisor-command">

46 `/advisor` 명령 사용

47</h3>

48 

49인수 없이 `/advisor`를 실행하여 사용 가능한 조언자 모델을 나열하는 선택기를 열거나 모델을 직접 전달하세요:

50 

51```

52/advisor opus

53```

54 

55선택 항목은 사용자 설정의 `advisorModel`에 저장되고 세션 전체에서 유지됩니다. 현재 주 모델이 조언자를 지원하지 않으면 선택 항목이 여전히 저장되고 [`/model`](/ko/model-config#setting-your-model)을 사용하여 [호환되는 주 모델](#choose-an-advisor-model)로 전환할 때 활성화됩니다.

56 

57<h3 id="set-advisormodel-in-settings">

58 설정에서 `advisorModel` 설정

59</h3>

60 

61세션을 열지 않고 조언자를 기본값으로 구성하려면 설정 파일에서 설정하세요:

62 

63```json theme={null}

64{

65 "advisorModel": "opus"

66}

67```

68 

69<h3 id="use-the-advisor-flag">

70 `--advisor` 플래그 사용

71</h3>

72 

73저장된 설정을 변경하지 않고 단일 세션에 대해 조언자를 설정하려면 플래그를 사용하여 시작하세요:

74 

75```bash theme={null}

76claude --advisor opus

77```

78 

79플래그는 해당 세션에 대해 `advisorModel` 설정보다 우선합니다. 세션의 주 모델이 조언자를 지원하지 않으면 `/advisor`와 달리 플래그는 오류로 종료됩니다.

80 

81<h2 id="choose-an-advisor-model">

82 조언자 모델 선택

83</h2>

84 

85조언자는 주 모델 이상의 기능을 가져야 합니다. 각 주 모델에 대해 허용되는 조언자는 다음과 같습니다:

86 

87| 주 모델 | 허용되는 조언자 | 참고 |

88| ----------------------------------------------- | ------------------------ | ------------------------------------- |

89| Haiku 4.5 | Fable, Opus, Sonnet | Haiku는 조언자를 호출할 수 있지만 조언자로 작동할 수 없습니다 |

90| Sonnet 4.6 | Fable, Opus, Sonnet | |

91| Opus 4.6 이상 | 주 모델의 버전 이상인 Fable, Opus | Opus 4.7 주 모델과 Opus 4.6 조언자는 거부됩니다 |

92| Fable 5 ({/* min-version: 2.1.170 */}v2.1.170+) | Fable | Opus 또는 Sonnet 조언자는 거부됩니다 |

93 

94Fable 5는 주 모델로 작동하든 조언자로 작동하든 Claude Code v2.1.170 이상과 Fable 5 액세스가 필요합니다.

95 

96조언자를 `opus`, `sonnet` 또는 `fable`로 설정하세요. 이러한 별칭은 각 모델의 최신 버전으로 확인됩니다. `claude-opus-4-8`과 같은 전체 모델 ID를 전달할 수도 있습니다.

97 

98하위 에이전트는 구성된 조언자를 상속하고 자신의 모델에 대해 동일한 쌍 확인을 적용합니다.

99 

100Claude Code는 요청을 보내기 전에 쌍을 검증합니다:

101 

102* 조언자가 주 모델보다 기능이 낮으면 조언자가 주 모델의 요청에 첨부되지 않습니다. `/advisor` 명령 출력과 알림에 이것이 표시됩니다. 자신의 모델이 쌍 확인을 만족하는 하위 에이전트는 여전히 조언자를 사용할 수 있습니다.

103* 주 모델 또는 조언자가 Claude Code가 인식하지 못하는 모델이면 조언자가 첨부되지 않습니다.

104 

105<h3 id="common-model-pairings">

106 일반적인 모델 쌍

107</h3>

108 

109허용되는 모든 쌍이 작동합니다. 이러한 조합은 비용과 기능을 다양한 방식으로 균형을 맞춥니다:

110 

111| 쌍 | 사용 시기 |

112| --------------------- | ---------------------------------------------------------------------------------------------------------- |

113| Sonnet 주 + Opus 조언자 | Sonnet은 일상적인 작업을 처리하고 계획, 모호한 실패, 완료 확인을 Opus로 에스컬레이션합니다 |

114| Sonnet 주 + Fable 조언자 | 전체 Fable 5를 실행하지 않고 결정 지점에서 Fable 5 지침을 받습니다. v2.1.170 이상과 Fable 5 액세스가 필요합니다 |

115| Haiku 주 + Opus 조언자 | 강력한 계획을 갖춘 가장 저렴한 주 모델입니다. Haiku 단독보다 비용이 높지만 주 모델을 Sonnet 또는 Opus로 전환하는 것보다 낮을 것으로 예상됩니다 |

116| Opus 주 + Opus 조언자 | 두 번째 Opus가 첫 번째를 검토합니다. 비용보다 독립적인 확인이 더 중요한 높은 위험도 작업에 유용합니다 |

117| Fable 주 + Fable 조언자 | Fable 5를 사용할 수 있을 때 가장 높은 기능 쌍(v2.1.170+). Fable은 Opus 및 Sonnet보다 높은 계층이므로 Fable 주 모델에 대해 유일하게 허용되는 조언자입니다 |

118| Sonnet 주 + Sonnet 조언자 | 일상적인 간과를 포착하기 위한 저비용 두 번째 의견 |

119 

120<h2 id="when-claude-consults-the-advisor">

121 Claude가 조언자를 참고할 때

122</h2>

123 

124Claude는 조언자를 호출할 시기를 결정합니다. 접근 방식을 확정하기 전, 오류가 계속 반복될 때, 작업 완료를 선언하기 전에 참고하는 경향이 있지만 타이밍은 규칙 기반이 아닌 모델 기반입니다.

125 

126프롬프트에서 `consult the advisor before you continue`와 같이 다른 도구를 요청하는 것과 같은 방식으로 상담을 요청할 수 있습니다. 조언자 호출을 제한하거나 강제하는 설정은 없습니다. 작업 중에 Claude가 더 자주 또는 덜 자주 참고하기를 원하면 지침에서 말하세요.

127 

128<h2 id="what-you-see-during-a-session">

129 세션 중에 표시되는 내용

130</h2>

131 

132Claude가 조언자를 호출하면 대화 기록에 호출이 진행 중인 동안 조언자 모델 이름이 있는 `Advising` 줄이 표시됩니다. 결과가 반환되면 줄은 조언자가 대화를 검토했음을 확인합니다. `Ctrl+O`를 눌러 확장하고 조언자의 전체 지침을 읽으세요.

133 

134Claude는 일반적으로 조언자의 지침을 따르지만 자신의 증거가 특정 주장과 모순될 때 적응합니다. 권장 단계가 시도했을 때 실패하거나 파일 내용이 조언과 모순되면 Claude는 지침을 무조건 따르기보다는 충돌을 표시합니다.

135 

136조언자는 항상 전체 대화를 받고 Claude가 타이밍을 제어합니다. 더 많은 제어 또는 다른 구성을 원하면 [조언자와 서브에이전트 및 opusplan 비교](#compare-with-related-features)를 참고하세요.

137 

138<h2 id="cost">

139 비용

140</h2>

141 

142각 조언자 호출은 대화를 조언자 모델로 보내므로 주 모델 사용 외에도 조언자 모델의 요금으로 토큰을 소비합니다. API 청구를 사용하면 조언자 토큰은 조언자 모델의 입력 및 출력 요금으로 청구됩니다. 구독 계획에서 조언자 사용은 계획의 사용 한도에 포함됩니다.

143 

144Claude는 모든 턴이 아닌 결정 지점에서 조언자를 호출하므로 더 빠른 주 모델을 더 강력한 조언자와 쌍으로 만드는 것이 일반적으로 전체 강력한 모델을 실행하는 것보다 비용이 적습니다. 조언자 사용은 [`/usage`](/ko/costs#track-your-costs)에 표시된 세션 합계에 포함됩니다.

145 

146조언자 토큰이 API 응답에서 보고되는 방식에 대해서는 Claude API 설명서의 [사용량 및 청구](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#usage-and-billing)를 참고하세요.

147 

148<h2 id="impact-on-prompt-caching">

149 프롬프트 캐싱에 미치는 영향

150</h2>

151 

152세션 중간에 조언자를 활성화하거나 비활성화해도 주 모델의 [프롬프트 캐시](/ko/prompt-caching)가 무효화되지 않습니다. [모델 또는 노력 수준 변경](/ko/prompt-caching#actions-that-invalidate-the-cache)과 달리 `/advisor` 토글은 캐시된 접두사를 유지하고 조언자가 반환한 지침은 나중의 턴에서 대화 기록의 일부로 캐시됩니다.

153 

154조언자 모델 자체의 대화 읽기는 캐시되지 않습니다. 각 조언자 호출은 전체 대화를 새로 처리하며 호출 간에 재사용이 없습니다.

155 

156<h2 id="requirements">

157 요구 사항

158</h2>

159 

160조언자 도구는 다음 모두를 요구합니다:

161 

162* **Claude Code v2.1.98 이상**: `claude update`를 실행하여 업그레이드하세요.

163* **Anthropic API만**: 조언자는 서버 실행 도구입니다. Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry에서는 사용할 수 없습니다. [LLM 게이트웨이](/ko/llm-gateway)를 통해 `ANTHROPIC_BASE_URL`로 구성된 경우 가용성은 게이트웨이가 요청을 Anthropic API로 그대로 전달하는지 여부에 따라 달라집니다.

164* **지원되는 주 모델**: Opus 4.6 이상, Sonnet 4.6 또는 Haiku 4.5. {/* min-version: 2.1.170 */}Fable 5도 Claude Code v2.1.170 이상에서 적합합니다.

165 

166<h2 id="turn-the-advisor-off">

167 조언자 끄기

168</h2>

169 

170조언자 사용을 중지하고 저장된 `advisorModel`을 지우려면 `/advisor off`를 실행하거나 `/advisor` 선택기에서 **No advisor**를 선택하세요:

171 

172```

173/advisor off

174```

175 

176`/advisor` 명령 및 `--advisor` 플래그를 포함하여 조언자 도구를 완전히 비활성화하려면 `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1`을 설정하세요. [환경 변수](/ko/env-vars)를 참고하세요.

177 

178<h2 id="compare-with-related-features">

179 관련 기능과 비교

180</h2>

181 

182조언자는 모델 강점을 결합하는 여러 방법 중 하나입니다. 더 강력한 모델을 언제 포함할지에 따라 선택하세요.

183 

184| 접근 방식 | 더 강력한 모델이 실행되는 시기 | 시작 방식 |

185| ----------------------------------------------------- | -------------------------------- | --------------------------- |

186| 조언자 도구 | 작업 중간의 결정 지점에서 | Claude가 지침이 필요할 때 호출합니다 |

187| [`opusplan`](/ko/model-config#opusplan-model-setting) | 계획 모드 중, 그 다음 실행을 위해 Sonnet으로 전환 | 계획 모드를 입력합니다 |

188| [서브에이전트](/ko/sub-agents#choose-a-model) (`model` 설정) | 전체 위임된 부작업에 대해 | Claude가 위임하거나 서브에이전트를 호출합니다 |

189| [`/model`](/ko/model-config#setting-your-model) | 이후의 모든 턴에 대해 | 모델을 전환합니다 |

190 

191<h2 id="see-also">

192 참고 항목

193</h2>

194 

195* [모델 구성](/ko/model-config): 모델 전환, 노력 수준 설정, `opusplan` 사용

196* [비용 효과적으로 관리](/ko/costs): 모델 전체의 토큰 사용량 추적

197* [Claude API의 조언자 도구](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool): 기본 서버 도구 이해 또는 Messages API에서 직접 사용

198* [조언자 전략](https://claude.com/blog/the-advisor-strategy): 빠른 주 모델을 더 강력한 조언자와 쌍으로 만드는 이유

Details

16 16 

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

18 18 

19<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-loop-diagram.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=1c6e8f28d80dba14a7287419656f1237" alt="에이전트 루프: 프롬프트 입력, Claude 평가, 도구 호출 또는 최종 답변으로 분기" width="720" height="212" data-path="images/agent-loop-diagram.svg" />19<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-loop-diagram.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=1c6e8f28d80dba14a7287419656f1237" alt="에이전트 루프 다이어그램: 프롬프트가 에이전트 루프에 진입하고, Claude가 평가하여 도구 호출을 요청하거나(결과가 다시 평가로 피드백됨) 최종 답변을 반환합니다" width="720" height="212" data-path="images/agent-loop-diagram.svg" />

20 20 

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

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


32 32 

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

34 34 

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

36 36 

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

38 38 

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

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

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

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

43 43 

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

45 45 

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

47 47 

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

49 49 

50<h2 id="message-types">50<h2 id="message-types">

51 메시지 타입51 메시지 타입


53 53 

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

55 55 

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

57 

58 * `"init"`: 세션 메타데이터가 포함된 첫 번째 메시지

59 * `"compact_boundary"`: [압축](#automatic-compaction) 후에 발생합니다

60 * `"informational"`: 루프의 일반 텍스트 상태 배너

61 * `"worker_shutting_down"`: 호스트가 종료되거나 Remote Control이 연결 해제되어 현재 턴 후에 루프가 종료됩니다

62 

63 TypeScript에서 `"init"` 이외의 각 서브타입은 `SDKSystemMessage`의 서브타입이 아니라 [`SDKMessage` 유니온](/ko/agent-sdk/typescript#sdkmessage)의 자체 타입입니다.

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

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

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


69 76 

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

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

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

73 80 

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

75 82 


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

184 191 

185| 수준 | 동작 | 적합한 경우 |192| 수준 | 동작 | 적합한 경우 |

186| :--------- | :----------- | :-------------------------- |193| :--------- | :----------- | :------------------------------------- |

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

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

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

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

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

192 199 

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

194 201 

195<Note>202<Note>

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


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

206 213 

207| 모드 | 동작 |214| 모드 | 동작 |

208| :-------------------- | :----------------------------------------------------------------------------------------------------------------- |215| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

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

211| `"plan"` | 읽기 전용 도구 실행; Claude는 소스 파일을 편집하지 않고 탐색하고 계획을 생성합니다 |218| `"plan"` | Claude는 소스 파일을 편집하지 않고 탐색하고 계획을 생성합니다; 파일 편집은 절대 자동 승인되지 않으며 `canUseTool` 콜백을 통해 프롬프트됩니다 |

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

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

214| `"bypassPermissions"` | 요청하지 않고 모든 허용된 도구를 실행합니다. Unix에서 루트로 실행할 때는 사용할 수 없습니다. 에이전트의 조치가 관심 있는 시스템에 영향을 미칠 수 없는 격리된 환경에서만 사용합니다 |221| `"bypassPermissions"` | 명시적 [`ask` 규칙](/ko/settings#permission-settings)이 일치하지 않는 한 요청하지 않고 모든 허용된 도구를 실행합니다; 권한이 평가되는 방식은 [권한이 평가되는 방식](/ko/agent-sdk/permissions#how-permissions-are-evaluated)을 참조하여 ask 규칙이 우선순위 순서에서 어디에 있는지 확인하세요. Unix에서 루트로 실행할 때는 사용할 수 없습니다. 에이전트의 조치가 관심 있는 시스템에 영향을 미칠 수 없는 격리된 환경에서만 사용합니다 |

215 222 

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

217 224 


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

306 313 

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

308| :------------------------------------ | :---------------------------------- | :----------------: |315| :------------------------------------ | :------------------------------------------------------------------------------------------ | :----------------: |

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

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

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

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

313| `error_max_structured_output_retries` | 구조화된 출력 검증이 구성된 재시도 제한 실패했습니다 | 아니오 |320| `error_max_structured_output_retries` | 구성된 재시도 제한 내에서 유효한 구조화된 출력이 생성되지 않았습니다: 모든 시도가 검증에 실패했거나, 모델 폴백이 성공적인 재시도 없이 완료된 출력을 취소했습니다 | 아니오 |

314 321 

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

316 323 


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

432 439 

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

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

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

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

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

Details

257 257 

258<CodeGroup>258<CodeGroup>

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

260 from claude_agent_sdk import ClaudeAgentOptions, query

261 import asyncio

262 

263 

264 async def main():

260 options = ClaudeAgentOptions(265 options = ClaudeAgentOptions(

261 env={266 env={

262 "CLAUDE_CODE_USE_BEDROCK": "1",267 "CLAUDE_CODE_USE_BEDROCK": "1",

263 "ENABLE_PROMPT_CACHING_1H": "1",268 "ENABLE_PROMPT_CACHING_1H": "1",

264 },269 },

265 )270 )

271 

272 async for message in query(prompt="Summarize this project", options=options):

273 print(message)

274 

275 

276 asyncio.run(main())

266 ```277 ```

267 278 

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

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

281 

269 const options = {282 const options = {

270 env: {283 env: {

271 ...process.env,284 ...process.env,


273 ENABLE_PROMPT_CACHING_1H: "1",286 ENABLE_PROMPT_CACHING_1H: "1",

274 },287 },

275 };288 };

289 

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

291 console.log(message);

292 }

276 ```293 ```

277</CodeGroup>294</CodeGroup>

278 295 

Details

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

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

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

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

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

41 * `isError` (선택사항): Claude가 반응할 수 있도록 도구 실패를 신호하려면 `true`로 설정합니다. [오류 처리](#handle-errors)를 참조하세요.41 * `isError` (선택사항): Claude가 반응할 수 있도록 도구 실패를 신호하려면 `true`로 설정합니다. [오류 처리](#handle-errors)를 참조하세요.

42 42 


363| 핸들러가 포착되지 않은 예외를 발생시킵니다 | 에이전트 루프가 중지됩니다. Claude는 오류를 보지 못하고 `query` 호출이 실패합니다. |363| 핸들러가 포착되지 않은 예외를 발생시킵니다 | 에이전트 루프가 중지됩니다. Claude는 오류를 보지 못하고 `query` 호출이 실패합니다. |

364| 핸들러가 오류를 포착하고 `isError: true` (TS) / `"is_error": True` (Python)를 반환합니다 | 에이전트 루프가 계속됩니다. Claude는 오류를 데이터로 보고 재시도하거나, 다른 도구를 시도하거나, 실패를 설명할 수 있습니다. |364| 핸들러가 오류를 포착하고 `isError: true` (TS) / `"is_error": True` (Python)를 반환합니다 | 에이전트 루프가 계속됩니다. Claude는 오류를 데이터로 보고 재시도하거나, 다른 도구를 시도하거나, 실패를 설명할 수 있습니다. |

365 365 

366아래 예제는 핸들러 내에서 두 가지 종류의 실패를 포착합니다. 0이 아닌 HTTP 상태는 응답에서 포착되어 오류 결과로 반환됩니다. 네트워크 오류 또는 잘못된 JSON은 주변 `try/except` (Python) 또는 `try/catch` (TypeScript)로 포착되어 오류 결과로도 반환됩니다. 두 경우 모두 핸들러는 정상적으로 반환되고 에이전트 루프가 계속됩니다.366아래 예제는 핸들러 내에서 두 가지 종류의 실패를 포착합니다. 200이 아닌 HTTP 상태는 응답에서 포착되어 오류 결과로 반환됩니다. 네트워크 오류 또는 잘못된 JSON은 주변 `try/except` (Python) 또는 `try/catch` (TypeScript)로 포착되어 오류 결과로도 반환됩니다. 두 경우 모두 핸들러는 정상적으로 반환되고 에이전트 루프가 계속됩니다.

367 367 

368<CodeGroup>368<CodeGroup>

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


375 @tool(375 @tool(

376 "fetch_data",376 "fetch_data",

377 "Fetch data from an API",377 "Fetch data from an API",

378 {"endpoint": str}, # 간단한 스키마378 {"endpoint": str}, # Simple schema

379 )379 )

380 async def fetch_data(args: dict[str, Any]) -> dict[str, Any]:380 async def fetch_data(args: dict[str, Any]) -> dict[str, Any]:

381 try:381 try:


461 이미지 및 리소스 반환461 이미지 및 리소스 반환

462</h2>462</h2>

463 463 

464도구 결과의 `content` 배열은 `text`, `image` `resource` 블록을 허용합니다. 동일한 응답에서 이들을 혼합할 수 있습니다.464도구 결과의 `content` 배열은 `text`, `image`, `audio`, `resource` 및 `resource_link` 블록을 허용합니다. 동일한 응답에서 이들을 혼합할 수 있습니다. 오디오 블록은 디스크에 저장되며 Claude는 저장된 파일 경로가 포함된 텍스트 블록을 받습니다. 리소스 링크 블록은 링크의 이름, URI 및 설명을 포함하는 텍스트 블록으로 변환됩니다.

465 465 

466<h3 id="images">466<h3 id="images">

467 이미지467 이미지

Details

729* **Python**: `pip install --upgrade claude-agent-sdk`729* **Python**: `pip install --upgrade claude-agent-sdk`

730* **TypeScript**: `npm install @anthropic-ai/claude-agent-sdk@latest`730* **TypeScript**: `npm install @anthropic-ai/claude-agent-sdk@latest`

731 731 

732<h3 id="user-messages-don-t-have-uuids">732<h3 id="user-messages-dont-have-uuids">

733 사용자 메시지에 UUID가 없음733 사용자 메시지에 UUID가 없음

734</h3>734</h3>

735 735 

Details

26 </Step>26 </Step>

27 27 

28 <Step title="SDK가 등록된 훅을 수집합니다">28 <Step title="SDK가 등록된 훅을 수집합니다">

29 SDK는 해당 이벤트 유형에 대해 등록된 훅을 확인합니다. 여기에는 `options.hooks`에 전달하는 콜백 훅과 해당 [`settingSources`](/ko/agent-sdk/typescript#settingSources) 또는 [`setting_sources`](/ko/agent-sdk/python#setting_sources) 항목이 활성화된 경우 설정 파일의 셸 명령 훅이 포함되며, 기본 `query()` 옵션에서는 활성화됩니다.29 SDK는 해당 이벤트 유형에 대해 등록된 훅을 확인합니다. 여기에는 `options.hooks`에 전달하는 콜백 훅과 해당 [`settingSources`](/ko/agent-sdk/typescript#settingsource) 또는 [`setting_sources`](/ko/agent-sdk/python#settingsource) 항목이 활성화된 경우 설정 파일의 셸 명령 훅이 포함되며, 기본 `query()` 옵션에서는 활성화됩니다.

30 </Step>30 </Step>

31 31 

32 <Step title="매처가 실행할 훅을 필터링합니다">32 <Step title="매처가 실행할 훅을 필터링합니다">

Details

16 기본 샌드박싱을 넘어선 보안 강화(네트워크 제어, 자격증명 관리 및 격리 옵션 포함)에 대해서는 [보안 배포](/ko/agent-sdk/secure-deployment)를 참조하십시오.16 기본 샌드박싱을 넘어선 보안 강화(네트워크 제어, 자격증명 관리 및 격리 옵션 포함)에 대해서는 [보안 배포](/ko/agent-sdk/secure-deployment)를 참조하십시오.

17</Info>17</Info>

18 18 

19## 서브프로세스 모델19<h2 id="the-subprocess-model">

20 서브프로세스 모델

21</h2>

20 22 

21이 페이지의 모든 호스팅 결정은 SDK가 에이전트를 실행하는 방식에서 비롯됩니다. 코드에서 `query()`를 호출하면 SDK는 별도의 `claude` CLI 프로세스를 생성하고 stdio를 통해 통신합니다. 해당 서브프로세스는 셸, 작업 디렉토리 및 로컬 디스크의 JSONL 세션 트랜스크립트를 소유합니다.23이 페이지의 모든 호스팅 결정은 SDK가 에이전트를 실행하는 방식에서 비롯됩니다. 코드에서 `query()`를 호출하면 SDK는 별도의 `claude` CLI 프로세스를 생성하고 stdio를 통해 통신합니다. 해당 서브프로세스는 셸, 작업 디렉토리 및 로컬 디스크의 JSONL 세션 트랜스크립트를 소유합니다.

22 24 


34 ```36 ```

35</CodeGroup>37</CodeGroup>

36 38 

37### 로컬 디스크에 존재하는 상태39<h3 id="state-that-lives-on-local-disk">

40 로컬 디스크에 존재하는 상태

41</h3>

38 42 

39세 가지 종류의 에이전트 상태가 기본적으로 컨테이너의 파일 시스템에 존재합니다. 이들 중 어느 것도 컨테이너 재시작, 축소 또는 다른 노드로의 이동을 견딜 수 없습니다.43세 가지 종류의 에이전트 상태가 기본적으로 컨테이너의 파일 시스템에 존재합니다. 이들 중 어느 것도 컨테이너 재시작, 축소 또는 다른 노드로의 이동을 견딜 수 없습니다.

40 44 


48 52 

49세션, 재개 및 포킹이 API 수준에서 어떻게 작동하는지에 대해서는 [세션](/ko/agent-sdk/sessions)을 참조합니다.53세션, 재개 및 포킹이 API 수준에서 어떻게 작동하는지에 대해서는 [세션](/ko/agent-sdk/sessions)을 참조합니다.

50 54 

51## 세션 패턴 선택55<h2 id="choose-a-session-pattern">

56 세션 패턴 선택

57</h2>

52 58 

53이 네 가지 패턴은 세션 수명 주기를 다룹니다: 컨테이너가 제공하는 세션에 상대적으로 얼마나 오래 존재하는지입니다. 컨테이너가 실행되는 위치에 대해서는 [호스팅 쿡북](https://github.com/anthropics/claude-cookbooks/blob/main/claude_agent_sdk/07_Hosting_the_agent.ipynb)에 로컬 Docker, Modal, Kubernetes용 [배포 가능한 코드](https://github.com/anthropics/claude-cookbooks/tree/main/claude_agent_sdk/hosting)가 있습니다. 여기서 세션 패턴을 선택하고 쿡북에서 배포 대상을 선택하십시오.59이 네 가지 패턴은 세션 수명 주기를 다룹니다: 컨테이너가 제공하는 세션에 상대적으로 얼마나 오래 존재하는지입니다. 컨테이너가 실행되는 위치에 대해서는 [호스팅 쿡북](https://github.com/anthropics/claude-cookbooks/blob/main/claude_agent_sdk/07_Hosting_the_agent.ipynb)에 로컬 Docker, Modal, Kubernetes용 [배포 가능한 코드](https://github.com/anthropics/claude-cookbooks/tree/main/claude_agent_sdk/hosting)가 있습니다. 여기서 세션 패턴을 선택하고 쿡북에서 배포 대상을 선택하십시오.

54 60 

55### 임시 세션61<h3 id="ephemeral-sessions">

62 임시 세션

63</h3>

56 64 

57각 사용자 작업에 대해 컨테이너를 생성하고 작업이 완료되면 삭제합니다. 일회성 작업에 최적입니다. 사용자는 작업이 완료되는 동안 AI와 상호작용할 수 있지만, 완료되면 컨테이너가 삭제됩니다.65각 사용자 작업에 대해 컨테이너를 생성하고 작업이 완료되면 삭제합니다. 일회성 작업에 최적입니다. 사용자는 작업이 완료되는 동안 AI와 상호작용할 수 있지만, 완료되면 컨테이너가 삭제됩니다.

58 66 


69}77}

70```78```

71 79 

72### 장기 실행 세션80<h3 id="long-running-sessions">

81 장기 실행 세션

82</h3>

73 83 

74지속적인 컨테이너 인스턴스를 실행하며, 종종 컨테이너당 여러 SDK 프로세스를 호스팅하여 진행 중인 작업을 제공합니다. 자율적으로 조치를 취하거나 콘텐츠를 제공하거나 대량의 메시지 스트림을 처리하는 에이전트에 최적입니다.84지속적인 컨테이너 인스턴스를 실행하며, 종종 컨테이너당 여러 SDK 프로세스를 호스팅하여 진행 중인 작업을 제공합니다. 자율적으로 조치를 취하거나 콘텐츠를 제공하거나 대량의 메시지 스트림을 처리하는 에이전트에 최적입니다.

75 85 


77 87 

78컨테이너는 HTTP 또는 WebSocket 엔드포인트를 노출하고 각 활성 세션을 장기 실행 쿼리 및 그 뒤의 서브프로세스에 매핑합니다. TypeScript에서는 [`streamInput()`](/ko/agent-sdk/typescript#query-object)을 사용하여 활성 세션에 턴을 추가하고 [`startup()`](/ko/agent-sdk/typescript#startup)을 사용하여 들어오는 트래픽 전에 서브프로세스를 미리 준비합니다. Python에서는 [`ClaudeSDKClient`](/ko/agent-sdk/python#claudesdkclient)를 사용하여 여러 턴에 걸쳐 세션을 열린 상태로 유지합니다. 컨테이너 크기를 메모리에 보유할 수 있는 최대 동시 세션 수에 맞게 조정하십시오.88컨테이너는 HTTP 또는 WebSocket 엔드포인트를 노출하고 각 활성 세션을 장기 실행 쿼리 및 그 뒤의 서브프로세스에 매핑합니다. TypeScript에서는 [`streamInput()`](/ko/agent-sdk/typescript#query-object)을 사용하여 활성 세션에 턴을 추가하고 [`startup()`](/ko/agent-sdk/typescript#startup)을 사용하여 들어오는 트래픽 전에 서브프로세스를 미리 준비합니다. Python에서는 [`ClaudeSDKClient`](/ko/agent-sdk/python#claudesdkclient)를 사용하여 여러 턴에 걸쳐 세션을 열린 상태로 유지합니다. 컨테이너 크기를 메모리에 보유할 수 있는 최대 동시 세션 수에 맞게 조정하십시오.

79 89 

80### 하이브리드 세션90<h3 id="hybrid-sessions">

91 하이브리드 세션

92</h3>

81 93 

82시작 시 [`SessionStore`](/ko/agent-sdk/session-storage)에서 수화되고 업데이트를 다시 유지하는 임시 컨테이너입니다. 많은 상호작용에 걸쳐 있지만 그 사이에 유휴 상태인 세션에 최적입니다. 컨테이너는 유휴 기간 동안 종료되고 사용자가 돌아올 때 다시 시작됩니다.94시작 시 [`SessionStore`](/ko/agent-sdk/session-storage)에서 수화되고 업데이트를 다시 유지하는 임시 컨테이너입니다. 많은 상호작용에 걸쳐 있지만 그 사이에 유휴 상태인 세션에 최적입니다. 컨테이너는 유휴 기간 동안 종료되고 사용자가 돌아올 때 다시 시작됩니다.

83 95 


119 131 

120전체 `SessionStore` 인터페이스 및 참조 어댑터는 [세션 저장소](/ko/agent-sdk/session-storage)를 참조하십시오.132전체 `SessionStore` 인터페이스 및 참조 어댑터는 [세션 저장소](/ko/agent-sdk/session-storage)를 참조하십시오.

121 133 

122### 다중 에이전트 컨테이너134<h3 id="multi-agent-container">

135 다중 에이전트 컨테이너

136</h3>

123 137 

124하나의 컨테이너 내에서 여러 SDK 서브프로세스를 실행합니다. 예를 들어 에이전트가 공유 환경에서 서로 상호작용하는 다중 에이전트 시뮬레이션과 같이 에이전트가 긴밀하게 협력해야 하는 경우에 최적입니다.138하나의 컨테이너 내에서 여러 SDK 서브프로세스를 실행합니다. 예를 들어 에이전트가 공유 환경에서 서로 상호작용하는 다중 에이전트 시뮬레이션과 같이 에이전트가 긴밀하게 협력해야 하는 경우에 최적입니다.

125 139 

126각 에이전트에 자신의 작업 디렉토리를 제공하여 서로의 파일을 덮어쓰지 않도록 하고, 에이전트별 `CLAUDE.md` 파일이 에이전트 간에 유출되지 않도록 설정 로딩을 격리합니다. 특정 옵션은 [다중 테넌트 격리](#multi-tenant-isolation)를 참조하십시오.140각 에이전트에 자신의 작업 디렉토리를 제공하여 서로의 파일을 덮어쓰지 않도록 하고, 에이전트별 `CLAUDE.md` 파일이 에이전트 간에 유출되지 않도록 설정 로딩을 격리합니다. 특정 옵션은 [다중 테넌트 격리](#multi-tenant-isolation)를 참조하십시오.

127 141 

128## 컨테이너 제공142<h2 id="provision-the-container">

143 컨테이너 제공

144</h2>

129 145 

130### 컨테이너 기반 샌드박싱146<h3 id="container-based-sandboxing">

147 컨테이너 기반 샌드박싱

148</h3>

131 149 

132프로세스 격리, 리소스 제한, 네트워크 제어 및 임시 파일 시스템을 위해 샌드박스 컨테이너 내에서 SDK를 실행합니다. 여러 제공자가 Agent SDK의 모델에 맞는 샌드박스 컨테이너 환경을 전문으로 합니다.150프로세스 격리, 리소스 제한, 네트워크 제어 및 임시 파일 시스템을 위해 샌드박스 컨테이너 내에서 SDK를 실행합니다. 여러 제공자가 Agent SDK의 모델에 맞는 샌드박스 컨테이너 환경을 전문으로 합니다.

133 151 


150 168 

151Docker, gVisor 및 Firecracker와 같은 자체 호스팅 옵션 및 상세한 격리 구성에 대해서는 [격리 기술](/ko/agent-sdk/secure-deployment#isolation-technologies)을 참조하십시오.169Docker, gVisor 및 Firecracker와 같은 자체 호스팅 옵션 및 상세한 격리 구성에 대해서는 [격리 기술](/ko/agent-sdk/secure-deployment#isolation-technologies)을 참조하십시오.

152 170 

153### 런타임 종속성171<h3 id="runtime-dependencies">

172 런타임 종속성

173</h3>

154 174 

155컨테이너는 SDK의 언어 런타임만 필요합니다:175컨테이너는 SDK의 언어 런타임만 필요합니다:

156 176 


159 179 

160번들된 바이너리는 SDK 패키지 버전에 고정되므로 SDK를 업데이트하는 것이 CLI를 업데이트하는 방법입니다. SDK는 semver를 따릅니다: 패치 릴리스를 지속적으로 적용하고 마이너 버전을 적용하기 전에 [TypeScript](https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/CHANGELOG.md) 또는 [Python](https://github.com/anthropics/claude-agent-sdk-python/blob/main/CHANGELOG.md) 변경 로그를 검토하십시오.180번들된 바이너리는 SDK 패키지 버전에 고정되므로 SDK를 업데이트하는 것이 CLI를 업데이트하는 방법입니다. SDK는 semver를 따릅니다: 패치 릴리스를 지속적으로 적용하고 마이너 버전을 적용하기 전에 [TypeScript](https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/CHANGELOG.md) 또는 [Python](https://github.com/anthropics/claude-agent-sdk-python/blob/main/CHANGELOG.md) 변경 로그를 검토하십시오.

161 181 

162### 리소스182<h3 id="resources">

183 리소스

184</h3>

163 185 

164새로 시작된 인스턴스의 경우 에이전트당 1GiB RAM, 5GiB 디스크 및 1 CPU가 합리적인 시작점입니다. 메모리 사용량은 세션 길이 및 도구 활동에 따라 증가하므로 유휴 기준선이 아닌 실제로 필요한 세션 길이 및 동시성에 맞게 크기를 조정하십시오. 호스트당 에이전트를 계산하는 방법은 [확장 및 동시성](#scaling-and-concurrency)을 참조하십시오.186새로 시작된 인스턴스의 경우 에이전트당 1GiB RAM, 5GiB 디스크 및 1 CPU가 합리적인 시작점입니다. 메모리 사용량은 세션 길이 및 도구 활동에 따라 증가하므로 유휴 기준선이 아닌 실제로 필요한 세션 길이 및 동시성에 맞게 크기를 조정하십시오. 호스트당 에이전트를 계산하는 방법은 [확장 및 동시성](#scaling-and-concurrency)을 참조하십시오.

165 187 

166### 네트워크188<h3 id="network">

189 네트워크

190</h3>

167 191 

168SDK는 `api.anthropic.com`으로 또는 Bedrock 또는 Vertex에서 실행할 때 제공자의 지역 엔드포인트로 아웃바운드 HTTPS가 필요합니다. 에이전트가 [MCP 서버](/ko/agent-sdk/mcp) 또는 외부 도구를 사용하는 경우 해당 엔드포인트에 대한 아웃바운드 액세스도 필요합니다. 프로덕션의 경우 도메인 허용 목록을 적용하고, 자격 증명을 주입하고, 요청을 기록하는 송신 프록시를 통해 아웃바운드 트래픽을 라우팅하십시오. 전체 패턴은 [보안 배포](/ko/agent-sdk/secure-deployment)를 참조하십시오.192SDK는 `api.anthropic.com`으로 또는 Bedrock 또는 Vertex에서 실행할 때 제공자의 지역 엔드포인트로 아웃바운드 HTTPS가 필요합니다. 에이전트가 [MCP 서버](/ko/agent-sdk/mcp) 또는 외부 도구를 사용하는 경우 해당 엔드포인트에 대한 아웃바운드 액세스도 필요합니다. 프로덕션의 경우 도메인 허용 목록을 적용하고, 자격 증명을 주입하고, 요청을 기록하는 송신 프록시를 통해 아웃바운드 트래픽을 라우팅하십시오. 전체 패턴은 [보안 배포](/ko/agent-sdk/secure-deployment)를 참조하십시오.

169 193 

170인바운드 트래픽의 경우 컨테이너에서 HTTP 또는 WebSocket 포트를 노출합니다. 애플리케이션은 해당 포트에서 클라이언트 요청을 처리하고 내부적으로 SDK를 호출합니다. 서브프로세스 자체는 네트워크에서 수신 대기하지 않습니다.194인바운드 트래픽의 경우 컨테이너에서 HTTP 또는 WebSocket 포트를 노출합니다. 애플리케이션은 해당 포트에서 클라이언트 요청을 처리하고 내부적으로 SDK를 호출합니다. 서브프로세스 자체는 네트워크에서 수신 대기하지 않습니다.

171 195 

172## 프로덕션 배포 문제 처리196<h2 id="handle-production-concerns">

197 프로덕션 배포 문제 처리

198</h2>

173 199 

174자체 호스팅 에이전트를 배포하기 전에 이러한 결정 사항을 검토하십시오.200자체 호스팅 에이전트를 배포하기 전에 이러한 결정 사항을 검토하십시오.

175 201 

176### 세션 및 상태 지속성202<h3 id="session-and-state-persistence">

203 세션 및 상태 지속성

204</h3>

177 205 

178기본 로컬 디스크는 재시작, 축소 또는 다른 노드로의 이동 시 손실됩니다. 사용자가 재개할 것으로 예상하는 모든 세션에 대해 [`SessionStore` 어댑터](/ko/agent-sdk/session-storage)를 사용하여 트랜스크립트를 지속 가능한 스토리지에 미러링하십시오. S3, Redis 및 Postgres 어댑터와 자신의 어댑터를 위한 적합성 제품군에 대해서는 [참조 구현](/ko/agent-sdk/session-storage#reference-implementations)을 참조하십시오.206기본 로컬 디스크는 재시작, 축소 또는 다른 노드로의 이동 시 손실됩니다. 사용자가 재개할 것으로 예상하는 모든 세션에 대해 [`SessionStore` 어댑터](/ko/agent-sdk/session-storage)를 사용하여 트랜스크립트를 지속 가능한 스토리지에 미러링하십시오. S3, Redis 및 Postgres 어댑터와 자신의 어댑터를 위한 적합성 제품군에 대해서는 [참조 구현](/ko/agent-sdk/session-storage#reference-implementations)을 참조하십시오.

179 207 


183* **미러링, 대체 아님**: 서브프로세스는 먼저 로컬 디스크에 쓰고, 스토어는 각 배치의 복사본을 받습니다. 로컬 쓰기가 권한이 있습니다.211* **미러링, 대체 아님**: 서브프로세스는 먼저 로컬 디스크에 쓰고, 스토어는 각 배치의 복사본을 받습니다. 로컬 쓰기가 권한이 있습니다.

184* **`mirror_error` 메시지**: 스토어가 거부하거나 시간 초과되면 SDK는 `{ type: "system", subtype: "mirror_error" }` 메시지를 내보내고 재시도 없이 쿼리를 계속합니다. 스토어 지속성이 중요한 경우 이에 대해 경고하십시오.212* **`mirror_error` 메시지**: 스토어가 거부하거나 시간 초과되면 SDK는 `{ type: "system", subtype: "mirror_error" }` 메시지를 내보내고 재시도 없이 쿼리를 계속합니다. 스토어 지속성이 중요한 경우 이에 대해 경고하십시오.

185 213 

186### 관찰성214<h3 id="observability">

215 관찰성

216</h3>

187 217 

188Agent SDK 에이전트는 많은 API 왕복에 걸쳐 도구 호출을 생성하는 장기 실행 프로세스입니다. 텔레메트리 없이는 어떤 도구가 실행되었는지, 얼마나 오래 걸렸는지, 또는 세션이 어디서 정체되었는지 볼 수 없습니다.218Agent SDK 에이전트는 많은 API 왕복에 걸쳐 도구 호출을 생성하는 장기 실행 프로세스입니다. 텔레메트리 없이는 어떤 도구가 실행되었는지, 얼마나 오래 걸렸는지, 또는 세션이 어디서 정체되었는지 볼 수 없습니다.

189 219 


201 231 

202프롬프트 텍스트 및 도구 입력은 기본적으로 내보내기에 포함되지 않습니다. 옵트인 플래그에 대해서는 [내보내기에서 민감한 데이터 제어](/ko/agent-sdk/observability#control-sensitive-data-in-exports)를 참조하고, 전체 신호 카탈로그에 대해서는 [관찰성](/ko/agent-sdk/observability)을 참조하십시오.232프롬프트 텍스트 및 도구 입력은 기본적으로 내보내기에 포함되지 않습니다. 옵트인 플래그에 대해서는 [내보내기에서 민감한 데이터 제어](/ko/agent-sdk/observability#control-sensitive-data-in-exports)를 참조하고, 전체 신호 카탈로그에 대해서는 [관찰성](/ko/agent-sdk/observability)을 참조하십시오.

203 233 

204### 인증 및 비밀234<h3 id="auth-and-secrets">

235 인증 및 비밀

236</h3>

205 237 

206호스팅 시점에 세 가지 인증 문제가 중요합니다:238호스팅 시점에 세 가지 인증 문제가 중요합니다:

207 239 


209* **인바운드**: 에이전트 컨테이너 앞의 게이트웨이에 인증을 배치하십시오. 에이전트는 사전 인증된 요청을 받아야 하며 사용자 토큰을 검증하는 구성 요소가 아니어야 합니다.241* **인바운드**: 에이전트 컨테이너 앞의 게이트웨이에 인증을 배치하십시오. 에이전트는 사전 인증된 요청을 받아야 하며 사용자 토큰을 검증하는 구성 요소가 아니어야 합니다.

210* **아웃바운드 도구**: 에이전트 환경에서 도구 자격 증명을 유지하십시오. 아웃바운드 호출을 요청이 컨테이너를 떠난 후 API 키를 주입하는 프록시를 통해 라우팅하십시오. 에이전트가 호출을 수행합니다. 프록시가 자격 증명을 추가합니다.242* **아웃바운드 도구**: 에이전트 환경에서 도구 자격 증명을 유지하십시오. 아웃바운드 호출을 요청이 컨테이너를 떠난 후 API 키를 주입하는 프록시를 통해 라우팅하십시오. 에이전트가 호출을 수행합니다. 프록시가 자격 증명을 추가합니다.

211 243 

212### 확장 및 동시성244<h3 id="scaling-and-concurrency">

245 확장 및 동시성

246</h3>

213 247 

214각 세션은 자체 서브프로세스에서 실행되므로 호스트의 동시성은 RAM이 보유할 수 있는 서브프로세스 수로 제한됩니다.248각 세션은 자체 서브프로세스에서 실행되므로 호스트의 동시성은 RAM이 보유할 수 있는 서브프로세스 수로 제한됩니다.

215 249 


225 259 

226단일 세션에서 [서브에이전트](/ko/agent-sdk/subagents)의 대규모 팬아웃은 API 속도 제한에 도달할 수 있습니다. 하나의 넓은 디스패치를 발행하는 대신 작업을 더 작은 배치로 나누십시오.260단일 세션에서 [서브에이전트](/ko/agent-sdk/subagents)의 대규모 팬아웃은 API 속도 제한에 도달할 수 있습니다. 하나의 넓은 디스패치를 발행하는 대신 작업을 더 작은 배치로 나누십시오.

227 261 

228### 비용262<h3 id="cost">

263 비용

264</h3>

229 265 

230Anthropic 토큰 비용은 일반적으로 컨테이너 인프라 비용을 한 자릿수 이상으로 지배합니다. 최소한으로 프로비저닝된 컨테이너는 시간당 약 \$0.05를 실행하는 반면, 단일 장기 에이전트 세션은 토큰에서 수 달러를 소비할 수 있습니다. 세션당 토큰 회계에 대해서는 [비용 추적](/ko/agent-sdk/cost-tracking)을 참조하십시오.266Anthropic 토큰 비용은 일반적으로 컨테이너 인프라 비용을 한 자릿수 이상으로 지배합니다. 최소한으로 프로비저닝된 컨테이너는 시간당 약 \$0.05를 실행하는 반면, 단일 장기 에이전트 세션은 토큰에서 수 달러를 소비할 수 있습니다. 세션당 토큰 회계에 대해서는 [비용 추적](/ko/agent-sdk/cost-tracking)을 참조하십시오.

231 267 

232### 다중 테넌트 격리268<h3 id="multi-tenant-isolation">

269 다중 테넌트 격리

270</h3>

233 271 

234기본 SDK 동작은 파일 시스템에서 설정 및 `CLAUDE.md` 메모리 파일을 읽습니다. 여러 테넌트를 제공하는 공유 컨테이너에서 이러한 파일은 한 테넌트의 컨텍스트를 다른 테넌트의 세션으로 유출할 수 있습니다.272기본 SDK 동작은 파일 시스템에서 설정 및 `CLAUDE.md` 메모리 파일을 읽습니다. 여러 테넌트를 제공하는 공유 컨테이너에서 이러한 파일은 한 테넌트의 컨텍스트를 다른 테넌트의 세션으로 유출할 수 있습니다.

235 273 


287 325 

288테넌트별 네트워크 제어에 대해서는 [보안 배포](/ko/agent-sdk/secure-deployment)를 참조하십시오.326테넌트별 네트워크 제어에 대해서는 [보안 배포](/ko/agent-sdk/secure-deployment)를 참조하십시오.

289 327 

290## 알려진 제한사항328<h2 id="known-limitations">

329 알려진 제한사항

330</h2>

291 331 

292배포 설계에서 이러한 사항들을 고려하십시오.332배포 설계에서 이러한 사항들을 고려하십시오.

293 333 

294| 제한사항 | 해결 방법 |334| 제한사항 | 해결 방법 |

295| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |335| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

296| 최상위 세션 타임아웃 없음 | 세션은 자동으로 타임아웃되지 않습니다. `Options`에서 `maxTurns`를 설정하여 에이전트가 중지되기 전에 수행하는 도구 사용 왕복 횟수를 제한하십시오. |336| 최상위 세션 타임아웃 없음 | 세션은 자동으로 타임아웃되지 않습니다. `Options`에서 `maxTurns`를 설정하여 에이전트가 중지되기 전에 수행하는 도구 사용 왕복 횟수를 제한하십시오. |

297| 장시간 세션에서의 메모리 증가 | 세션 길이를 제한하거나 서브프로세스를 주기적으로 재활용하십시오. [확장성 및 동시성](#확장성--동시성)을 참조하십시오. |337| 장시간 세션에서의 메모리 증가 | 세션 길이를 제한하거나 서브프로세스를 주기적으로 재활용하십시오. [확장성 및 동시성](#scaling-and-concurrency)을 참조하십시오. |

298| 대규모 병렬 서브에이전트 팬아웃으로 인한 속도 제한 도달 | 한 번에 광범위한 디스패치를 발행하는 대신 작업을 더 작은 배치로 나누십시오. |338| 대규모 병렬 서브에이전트 팬아웃으로 인한 속도 제한 도달 | 한 번에 광범위한 디스패치를 발행하는 대신 작업을 더 작은 배치로 나누십시오. |

299| 서브에이전트별 벽시계 데드라인 없음 | 각 [서브에이전트](/ko/agent-sdk/subagents)를 `AgentDefinition`의 `maxTurns`로 제한하십시오. 백그라운드 서브에이전트만의 경우, `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`는 `run_in_background` 서브에이전트가 출력 생성을 중지할 때 발동하는 정지 감시 장치를 설정합니다. 이는 총 런타임 데드라인이 아닙니다. |339| 서브에이전트별 벽시계 데드라인 없음 | 각 [서브에이전트](/ko/agent-sdk/subagents)를 `AgentDefinition`의 `maxTurns`로 제한하십시오. 백그라운드 서브에이전트만의 경우, `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`는 `run_in_background` 서브에이전트가 출력 생성을 중지할 때 발동하는 정지 감시 장치를 설정합니다. 이는 총 런타임 데드라인이 아닙니다. |

300 340 

301## 다음 단계341<h2 id="next-steps">

342 다음 단계

343</h2>

302 344 

303* [호스팅 쿡북](https://github.com/anthropics/claude-cookbooks/blob/main/claude_agent_sdk/07_Hosting_the_agent.ipynb): Docker, Modal, Kubernetes용 [배포 가능한 코드](https://github.com/anthropics/claude-cookbooks/tree/main/claude_agent_sdk/hosting)가 포함된 노트북 안내입니다.345* [호스팅 쿡북](https://github.com/anthropics/claude-cookbooks/blob/main/claude_agent_sdk/07_Hosting_the_agent.ipynb): Docker, Modal, Kubernetes용 [배포 가능한 코드](https://github.com/anthropics/claude-cookbooks/tree/main/claude_agent_sdk/hosting)가 포함된 노트북 안내입니다.

304* [세션 저장소](/ko/agent-sdk/session-storage): `SessionStore` 어댑터를 사용하여 호스트 간에 트랜스크립트를 유지합니다.346* [세션 저장소](/ko/agent-sdk/session-storage): `SessionStore` 어댑터를 사용하여 호스트 간에 트랜스크립트를 유지합니다.

agent-sdk/mcp.md +81 −29

Details

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

15</Note>15</Note>

16 16 

17## 빠른 시작17<h2 id="quickstart">

18 빠른 시작

19</h2>

18 20 

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

20 22 

21<CodeGroup>23<CodeGroup>

22 ```typescript TypeScript theme={null}24 ```typescript TypeScript theme={null}


70 72 

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

72 74 

73## MCP 서버 추가75<h2 id="add-an-mcp-server">

76 MCP 서버 추가

77</h2>

74 78 

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

76 80 

77### 코드에서81<h3 id="in-code">

82 코드에서

83</h3>

78 84 

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

80 86 


129 ```135 ```

130</CodeGroup>136</CodeGroup>

131 137 

132### 구성 파일에서138<h3 id="from-a-config-file">

139 구성 파일에서

140</h3>

133 141 

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

135 143 


144}152}

145```153```

146 154 

147## MCP 도구 허용155<h2 id="allow-mcp-tools">

156 MCP 도구 허용

157</h2>

148 158 

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

150 160 

151### 도구 명명 규칙161<h3 id="tool-naming-convention">

162 도구 명명 규칙

163</h3>

152 164 

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

154 166 

155### allowedTools로 자동 승인167<h3 id="auto-approve-with-allowedtools">

168 allowedTools로 자동 승인

169</h3>

156 170 

157`allowedTools`를 사용하여 특정 MCP 도구를 자동으로 승인하면 Claude가 권한 프롬프트 없이 사용할 수 있습니다:171`allowedTools`를 사용하여 특정 MCP 도구를 자동으로 승인하면 Claude가 권한 프롬프트 없이 사용할 수 있습니다:

158 172 


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

175 189 

176<Note>190<Note>

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

178</Note>192</Note>

179 193 

180### 사용 가능한 도구 검색194<h3 id="discover-available-tools">

195 사용 가능한 도구 검색

196</h3>

181 197 

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

183 199 


189}205}

190```206```

191 207 

192## 전송 유형208<h2 id="transport-types">

209 전송 유형

210</h2>

193 211 

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

195 213 


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

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

199 217 

200### stdio 서버218<h3 id="stdio-servers">

219 stdio 서버

220</h3>

201 221 

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

203 223 


253 </Tab>273 </Tab>

254</Tabs>274</Tabs>

255 275 

256### HTTP/SSE 서버276<h3 id="http/sse-servers">

277 HTTP/SSE 서버

278</h3>

257 279 

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

259 281 


311 333 

312스트리밍 가능한 HTTP 전송의 경우 `"type": "http"` 대신 사용합니다. `.mcp.json` 및 기타 JSON 구성 파일에서 `"streamable-http"`는 `"http"`의 별칭으로 허용됩니다. 프로그래밍 방식의 `mcpServers` 옵션은 `"http"`만 허용합니다.334스트리밍 가능한 HTTP 전송의 경우 `"type": "http"` 대신 사용합니다. `.mcp.json` 및 기타 JSON 구성 파일에서 `"streamable-http"`는 `"http"`의 별칭으로 허용됩니다. 프로그래밍 방식의 `mcpServers` 옵션은 `"http"`만 허용합니다.

313 335 

314### SDK MCP 서버336<h3 id="sdk-mcp-servers">

337 SDK MCP 서버

338</h3>

315 339 

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

317 341 

318## MCP 도구 검색342<h2 id="mcp-tool-search">

343 MCP 도구 검색

344</h2>

319 345 

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

321 347 

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

323 349 

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

325 351 

326## 인증352<h2 id="authentication">

353 인증

354</h2>

327 355 

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

329 357 

330### 환경 변수를 통해 자격 증명 전달358<h3 id="pass-credentials-via-environment-variables">

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

360</h3>

331 361 

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

333 363 


387 417 

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

389 419 

390### 원격 서버용 HTTP 헤더420<h3 id="http-headers-for-remote-servers">

421 원격 서버용 HTTP 헤더

422</h3>

391 423 

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

393 425 


445 </Tab>477 </Tab>

446</Tabs>478</Tabs>

447 479 

448### OAuth2 인증480<h3 id="oauth2-authentication">

481 OAuth2 인증

482</h3>

449 483 

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

451 485 


485 ```519 ```

486</CodeGroup>520</CodeGroup>

487 521 

488## 예제522<h2 id="examples">

523 예제

524</h2>

489 525 

490### 저장소에서 문제 나열526<h3 id="list-issues-from-a-repository">

527 저장소에서 문제 나열

528</h3>

491 529 

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

493 531 


584 ```622 ```

585</CodeGroup>623</CodeGroup>

586 624 

587### 데이터베이스 쿼리625<h3 id="query-a-database">

626 데이터베이스 쿼리

627</h3>

588 628 

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

590 630 


655 ```695 ```

656</CodeGroup>696</CodeGroup>

657 697 

658## 오류 처리698<h2 id="error-handling">

699 오류 처리

700</h2>

659 701 

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

661 703 


717 ```759 ```

718</CodeGroup>760</CodeGroup>

719 761 

720## 문제 해결762<h2 id="troubleshooting">

763 문제 해결

764</h2>

721 765 

722### 서버가 "failed" 상태를 표시합니다766<h3 id="server-shows-failed-status">

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

768</h3>

723 769 

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

725 771 


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

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

742 788 

743### 도구가 호출되지 않음789<h3 id="tools-not-being-called">

790 도구가 호출되지 않음

791</h3>

744 792 

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

746 794 


755};803};

756```804```

757 805 

758### 연결 시간 초과806<h3 id="connection-timeouts">

807 연결 시간 초과

808</h3>

759 809 

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

761 811 


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

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

765 815 

766## 관련 리소스816<h2 id="related-resources">

817 관련 리소스

818</h2>

767 819 

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

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

Details

12 12 

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

14 14 

15<h2 id="what-s-changed">15<h2 id="whats-changed">

16 변경 사항16 변경 사항

17</h2>17</h2>

18 18 


82}82}

83```83```

84 84 

85완료되었습니다! 다른 코드 변경은 필요하지 않습니다.85**5. [주요 변경 사항](#breaking-changes) 검토**

86 

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

86 88 

87<h3 id="for-python-projects">89<h3 id="for-python-projects">

88 Python 프로젝트의 경우90 Python 프로젝트의 경우


172 174 

173<CodeGroup>175<CodeGroup>

174 ```typescript TypeScript theme={null}176 ```typescript TypeScript theme={null}

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

178 

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

176 const result = query({ prompt: "Hello" });180 const before = query({ prompt: "Hello" });

177 181 

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

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

180 const result = query({184 const presetResult = query({

181 prompt: "Hello",185 prompt: "Hello",

182 options: {186 options: {

183 systemPrompt: { type: "preset", preset: "claude_code" }187 systemPrompt: { type: "preset", preset: "claude_code" }


185 });189 });

186 190 

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

188 const result = query({192 const customResult = query({

189 prompt: "Hello",193 prompt: "Hello",

190 options: {194 options: {

191 systemPrompt: "You are a helpful coding assistant"195 systemPrompt: "You are a helpful coding assistant"


233 237 

234<CodeGroup>238<CodeGroup>

235 ```typescript TypeScript theme={null}239 ```typescript TypeScript theme={null}

236 const result = query({240 import { query } from "@anthropic-ai/claude-agent-sdk";

241 

242 const isolatedResult = query({

237 prompt: "Hello",243 prompt: "Hello",

238 options: {244 options: {

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


241 });247 });

242 248 

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

244 const result = query({250 const projectOnlyResult = query({

245 prompt: "Hello",251 prompt: "Hello",

246 options: {252 options: {

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

Details

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

181 options = ClaudeAgentOptions(181 options = ClaudeAgentOptions(

182 env={182 env={

183 # ... 내보내기 도구 구성 ...183 # ... exporter configuration ...

184 "OTEL_SERVICE_NAME": "support-triage-agent",184 "OTEL_SERVICE_NAME": "support-triage-agent",

185 "OTEL_RESOURCE_ATTRIBUTES": "service.version=1.4.0,deployment.environment=production",185 "OTEL_RESOURCE_ATTRIBUTES": "service.version=1.4.0,deployment.environment=production",

186 },186 },


191 const options = {191 const options = {

192 env: {192 env: {

193 ...process.env,193 ...process.env,

194 // ... 내보내기 도구 구성 ...194 // ... exporter configuration ...

195 OTEL_SERVICE_NAME: "support-triage-agent",195 OTEL_SERVICE_NAME: "support-triage-agent",

196 OTEL_RESOURCE_ATTRIBUTES:196 OTEL_RESOURCE_ATTRIBUTES":

197 "service.version=1.4.0,deployment.environment=production",197 "service.version=1.4.0,deployment.environment=production",

198 },198 },

199 };199 };

Details

27 `deny` 규칙(`disallowed_tools` 및 [settings.json](/ko/settings#permission-settings)에서)을 확인합니다. 거부 규칙이 일치하면 `bypassPermissions` 모드에서도 도구가 차단됩니다. `Bash`와 같은 단순 이름의 거부 규칙은 이 평가가 시작되기 전에 Claude의 컨텍스트에서 도구를 제거하므로 `Bash(rm *)`와 같은 범위가 지정된 규칙만 이 단계에서 확인됩니다.27 `deny` 규칙(`disallowed_tools` 및 [settings.json](/ko/settings#permission-settings)에서)을 확인합니다. 거부 규칙이 일치하면 `bypassPermissions` 모드에서도 도구가 차단됩니다. `Bash`와 같은 단순 이름의 거부 규칙은 이 평가가 시작되기 전에 Claude의 컨텍스트에서 도구를 제거하므로 `Bash(rm *)`와 같은 범위가 지정된 규칙만 이 단계에서 확인됩니다.

28 </Step>28 </Step>

29 29 

30 <Step title="요청 규칙">

31 [settings.json](/ko/settings#permission-settings)에서 `ask` 규칙을 확인합니다. 요청 규칙이 일치하면 `bypassPermissions` 모드에서도 호출이 확인을 위해 [`canUseTool` 콜백](/ko/agent-sdk/user-input)으로 전달됩니다. `dontAsk` 모드에서는 일치하는 요청 규칙이 거부됩니다. 이 모드는 절대 프롬프트를 표시하지 않기 때문입니다.

32 </Step>

33 

30 <Step title="권한 모드">34 <Step title="권한 모드">

31 활성 [권한 모드](#permission-modes)를 적용합니다. `bypassPermissions`는 이 단계에 도달한 모든 항목을 승인합니다. `acceptEdits`는 파일 작업을 승인합니다. 다른 모드는 통과합니다.35 활성 [권한 모드](#permission-modes)를 적용합니다. `bypassPermissions`는 이 단계에 도달한 모든 항목을 승인합니다. `acceptEdits`는 파일 작업을 승인합니다. `plan`은 허용 규칙과 관계없이 파일 편집 및 셸 쓰기 도구를 `canUseTool` 콜백으로 라우팅하므로 계획 중에는 쓰기 작업을 자동 승인할 수 없습니다. 다른 모드는 통과합니다.

32 </Step>36 </Step>

33 37 

34 <Step title="허용 규칙">38 <Step title="허용 규칙">


40 </Step>44 </Step>

41</Steps>45</Steps>

42 46 

43<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=cc94220087262cd48c9b64a14c4e1c2c" alt="권한 평가 흐름 다이어그램" width="1024" height="260" data-path="images/agent-sdk/permissions-flow.svg" />47<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=cc94220087262cd48c9b64a14c4e1c2c" alt="5단계 권한 평가 흐름의 다이어그램으로, 위의 단계와 일치합니다: 도구 요청이 훅, 거부 규칙, 권한 모드, 허용 규칙 및 canUseTool을 통과합니다. 훅, 거부 규칙 및 canUseTool은 차단으로 라우팅할 수 있습니다. 권한 모드 우회, 허용 규칙 및 canUseTool은 실행으로 라우팅할 수 있습니다." width="1024" height="260" data-path="images/agent-sdk/permissions-flow.svg" />

44 48 

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

46 50 


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

59| `disallowed_tools=["Bash"]` | `Bash` 도구 정의가 요청에서 제거됩니다. Claude는 도구를 보지 못하며 시도할 수 없습니다. |63| `disallowed_tools=["Bash"]` | `Bash` 도구 정의가 요청에서 제거됩니다. Claude는 도구를 보지 못하며 시도할 수 없습니다. |

60| `disallowed_tools=["Bash(rm *)"]` | `Bash`는 계속 사용 가능합니다. `rm *`과 일치하는 호출은 `bypassPermissions`를 포함한 모든 권한 모드에서 거부됩니다. 다른 `Bash` 호출은 권한 모드로 통과합니다. |64| `disallowed_tools=["Bash(rm *)"]` | `Bash`는 계속 사용 가능합니다. `rm *`과 일치하는 호출은 `bypassPermissions`를 포함한 모든 권한 모드에서 거부됩니다. 다른 `Bash` 호출은 권한 모드로 통과합니다. |

65| `disallowed_tools=["*"]` | 모든 도구 정의가 요청에서 제거됩니다. 도구 이름 글롭이 거부 규칙에서 지원됩니다. `"*"`는 모든 도구와 일치하고 `"mcp__*"`는 모든 서버의 모든 MCP 도구와 일치합니다. |

66 

67허용 규칙은 리터럴 `mcp__<server>__` 접두사 이후에만 도구 이름 글롭을 허용합니다. 서버 세그먼트는 글롭이 없어야 하므로 규칙이 구성한 특정 서버의 이름을 지정합니다. `mcp__puppeteer__*`는 `puppeteer` 서버의 모든 도구와 일치하고 `mcp__github__get_*`는 해당 `get_` 도구와 일치합니다. `allowed_tools=["*"]` 또는 `allowed_tools=["mcp__*"]`와 같은 앵커되지 않은 항목은 시작 경고와 함께 무시되며 아무것도 자동 승인하지 않습니다.

61 68 

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

63 70 


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

88 95 

89| 모드 | 설명 | 도구 동작 |96| 모드 | 설명 | 도구 동작 |

90| :--------------------- | :---------- | :------------------------------------------------------------------------------------------------------- |97| :---------------------- | :---------- | :-------------------------------------------------------------------------------------------------------- |

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

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

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

94| `bypassPermissions` | 모든 권한 확인 무시 | 모든 도구는 권한 프롬프트 없이 실행됩니다(주의해서 사용) |101| `bypassPermissions` | 권한 확인 무시 | 도구는 권한 프롬프트 없이 실행됩니다. 명시적 [`ask` 규칙](#how-permissions-are-evaluated)이 일치하지 않는 한(주의해서 사용) |

95| `plan` | 계획 모드 | 읽기 전용 도구가 실행되고 Claude는 소스 파일을 편집하지 않고 분석 및 계획합니다 |102| `plan` | 계획 모드 | Claude는 소스 파일을 편집하지 않고 탐색 및 계획합니다. 파일 편집은 자동으로 승인되지 않으며 `canUseTool` 콜백을 통해 프롬프트합니다 |

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

97 104 

98<Warning>105<Warning>

99 **하위 에이전트 상속:** 부모가 `bypassPermissions`, `acceptEdits` 또는 `auto`를 사용할 때 모든 하위 에이전트는 해당 모드를 상속하며 하위 에이전트별로 재정의할 수 없습니다. 하위 에이전트는 주 에이전트와 다른 시스템 프롬프트와 덜 제한된 동작을 가질 수 있으므로 `bypassPermissions`를 상속하면 승인 프롬프트 없이 전체 자율 시스템 액세스 권한이 부여됩니다.106 **하위 에이전트 상속:** 부모가 `bypassPermissions`, `acceptEdits` 또는 `auto`를 사용할 때 모든 하위 에이전트는 해당 모드를 상속하며 하위 에이전트별로 재정의할 수 없습니다. 하위 에이전트는 주 에이전트와 다른 시스템 프롬프트와 덜 제한된 동작을 가질 수 있으므로 `bypassPermissions`를 상속하면 전체 자율 시스템 액세스 권한이 부여됩니다. 명시적 [`ask` 규칙](#how-permissions-are-evaluated)은 여전히 프롬프트를 강제합니다.

100</Warning>107</Warning>

101 108 

102<h3 id="set-permission-mode">109<h3 id="set-permission-mode">


212</h3>219</h3>

213 220 

214<h4 id="accept-edits-mode-acceptedits">221<h4 id="accept-edits-mode-acceptedits">

215 편집 수락 모드(`acceptEdits`)222 편집 수락 모드 (`acceptEdits`)

216</h4>223</h4>

217 224 

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


226 233 

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

228 235 

229<h4 id="don-t-ask-mode-dontask">236<h4 id="dont-ask-mode-dontask">

230 요청 안 함 모드(`dontAsk`)237 요청 안 함 모드 (`dontAsk`)

231</h4>238</h4>

232 239 

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


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

236 243 

237<h4 id="bypass-permissions-mode-bypasspermissions">244<h4 id="bypass-permissions-mode-bypasspermissions">

238 권한 무시 모드(`bypassPermissions`)245 권한 무시 모드 (`bypassPermissions`)

239</h4>246</h4>

240 247 

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


247</Warning>254</Warning>

248 255 

249<h4 id="plan-mode-plan">256<h4 id="plan-mode-plan">

250 계획 모드(`plan`)257 계획 모드 (`plan`)

251</h4>258</h4>

252 259 

253Claude를 읽기 전용 도구로 제한합니다. Claude는 파일을 읽고 읽기 전용 명령을 실행하여 코드베이스를 탐색할 있지만 소스 파일을 편집하지 않습니다. Claude는 계획을 최종화하기 전에 요구 사항을 명확히 하기 위해 `AskUserQuestion`을 사용할 수 있습니다. 이러한 프롬프트 처리는 [승인 및 사용자 입력 처리](/ko/agent-sdk/user-input#handle-clarifying-questions) 참조하세요.260Claude는 코드베이스를 탐색하고 소스 파일을 편집하지 않고 계획을 생성합니다. 읽기 전용 도구는 기본 모드처럼 실행됩니다. 파일 편집은 계획 모드에서 자동으로 승인되지 않으며, 허용 규칙이 일치하더라도 `canUseTool` 콜백을 통해 프롬프트합니다. Claude는 계획을 최종화하기 전에 요구 사항을 명확히 하기 위해 `AskUserQuestion`을 사용할 수 있습니다. [승인 및 사용자 입력 처리](/ko/agent-sdk/user-input#handle-clarifying-questions)에서 이러한 프롬프트 처리를 참조하세요.

254 261 

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

256 263 

Details

385 385 

386* [플러그인](/ko/plugins) - 완전한 플러그인 개발 가이드386* [플러그인](/ko/plugins) - 완전한 플러그인 개발 가이드

387* [플러그인 참조](/ko/plugins-reference) - 기술 사양387* [플러그인 참조](/ko/plugins-reference) - 기술 사양

388* [슬래시 명령어](/ko/agent-sdk/slash-commands) - SDK에서 슬래시 명령어 사용388* [Commands](/ko/agent-sdk/slash-commands) - SDK에서 명령어 사용

389* [서브에이전트](/ko/agent-sdk/subagents) - 전문화된 에이전트 작업389* [Subagents](/ko/agent-sdk/subagents) - 전문화된 에이전트 작업

390* [스킬](/ko/agent-sdk/skills) - Agent Skills 사용390* [Skills](/ko/agent-sdk/skills) - Agent Skills 사용

Details

132) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]132) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]

133```133```

134 134 

135<h4 id="parameters">135<h4 id="parameters-1">

136 매개변수136 매개변수

137</h4>137</h4>

138 138 


165 }165 }

166 ```166 ```

167 167 

168<h4 id="returns">168<h4 id="returns-1">

169 반환값169 반환값

170</h4>170</h4>

171 171 


228) -> McpSdkServerConfig228) -> McpSdkServerConfig

229```229```

230 230 

231<h4 id="parameters">231<h4 id="parameters-2">

232 매개변수232 매개변수

233</h4>233</h4>

234 234 


238| `version` | `str` | `"1.0.0"` | 서버 버전 문자열 |238| `version` | `str` | `"1.0.0"` | 서버 버전 문자열 |

239| `tools` | `list[SdkMcpTool[Any]] \| None` | `None` | `@tool` 데코레이터로 생성된 도구 함수 목록 |239| `tools` | `list[SdkMcpTool[Any]] \| None` | `None` | `@tool` 데코레이터로 생성된 도구 함수 목록 |

240 240 

241<h4 id="returns">241<h4 id="returns-2">

242 반환값242 반환값

243</h4>243</h4>

244 244 

245`ClaudeAgentOptions.mcp_servers`에 전달할 수 있는 `McpSdkServerConfig` 객체를 반환합니다.245`ClaudeAgentOptions.mcp_servers`에 전달할 수 있는 `McpSdkServerConfig` 객체를 반환합니다.

246 246 

247<h4 id="example">247<h4 id="example-1">

248 예제248 예제

249</h4>249</h4>

250 250 


289) -> list[SDKSessionInfo]289) -> list[SDKSessionInfo]

290```290```

291 291 

292<h4 id="parameters">292<h4 id="parameters-3">

293 매개변수293 매개변수

294</h4>294</h4>

295 295 


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

317| `created_at` | `int \| None` | 에포크 이후 세션 생성 시간 (밀리초) |317| `created_at` | `int \| None` | 에포크 이후 세션 생성 시간 (밀리초) |

318 318 

319<h4 id="example">319<h4 id="example-2">

320 예제320 예제

321</h4>321</h4>

322 322 


344) -> list[SessionMessage]344) -> list[SessionMessage]

345```345```

346 346 

347<h4 id="parameters">347<h4 id="parameters-4">

348 매개변수348 매개변수

349</h4>349</h4>

350 350 


367| `message` | `Any` | 원본 메시지 콘텐츠 |367| `message` | `Any` | 원본 메시지 콘텐츠 |

368| `parent_tool_use_id` | `None` | 향후 사용을 위해 예약됨 |368| `parent_tool_use_id` | `None` | 향후 사용을 위해 예약됨 |

369 369 

370<h4 id="example">370<h4 id="example-3">

371 예제371 예제

372</h4>372</h4>

373 373 


394) -> SDKSessionInfo | None394) -> SDKSessionInfo | None

395```395```

396 396 

397<h4 id="parameters">397<h4 id="parameters-5">

398 매개변수398 매개변수

399</h4>399</h4>

400 400 


405 405 

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

407 407 

408<h4 id="example">408<h4 id="example-4">

409 예제409 예제

410</h4>410</h4>

411 411 


433) -> None433) -> None

434```434```

435 435 

436<h4 id="parameters">436<h4 id="parameters-6">

437 매개변수437 매개변수

438</h4>438</h4>

439 439 


445 445 

446`session_id`가 유효한 UUID가 아니거나 `title`이 비어 있으면 `ValueError`를 발생시킵니다. 세션을 찾을 수 없으면 `FileNotFoundError`를 발생시킵니다.446`session_id`가 유효한 UUID가 아니거나 `title`이 비어 있으면 `ValueError`를 발생시킵니다. 세션을 찾을 수 없으면 `FileNotFoundError`를 발생시킵니다.

447 447 

448<h4 id="example">448<h4 id="example-5">

449 예제449 예제

450</h4>450</h4>

451 451 


473) -> None473) -> None

474```474```

475 475 

476<h4 id="parameters">476<h4 id="parameters-7">

477 매개변수477 매개변수

478</h4>478</h4>

479 479 


485 485 

486`session_id`가 유효한 UUID가 아니거나 `tag`가 정규화 후 비어 있으면 `ValueError`를 발생시킵니다. 세션을 찾을 수 없으면 `FileNotFoundError`를 발생시킵니다.486`session_id`가 유효한 UUID가 아니거나 `tag`가 정규화 후 비어 있으면 `ValueError`를 발생시킵니다. 세션을 찾을 수 없으면 `FileNotFoundError`를 발생시킵니다.

487 487 

488<h4 id="example">488<h4 id="example-6">

489 예제489 예제

490</h4>490</h4>

491 491 


910| `max_budget_usd` | `float \| None` | `None` | 클라이언트 측 비용 추정이 이 USD 값에 도달하면 쿼리 중지. `total_cost_usd`와 동일한 추정과 비교됨. 정확도 주의 사항은 [비용 및 사용량 추적](/ko/agent-sdk/cost-tracking) 참조 |910| `max_budget_usd` | `float \| None` | `None` | 클라이언트 측 비용 추정이 이 USD 값에 도달하면 쿼리 중지. `total_cost_usd`와 동일한 추정과 비교됨. 정확도 주의 사항은 [비용 및 사용량 추적](/ko/agent-sdk/cost-tracking) 참조 |

911| `disallowed_tools` | `list[str]` | `[]` | 거부할 도구. `"Bash"`와 같은 단순 이름은 Claude의 컨텍스트에서 도구를 제거합니다. `"Bash(rm *)"` 같은 범위 지정 규칙은 도구를 사용 가능하게 유지하고 `bypassPermissions`를 포함한 모든 권한 모드에서 일치하는 호출을 거부합니다. [권한](/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |911| `disallowed_tools` | `list[str]` | `[]` | 거부할 도구. `"Bash"`와 같은 단순 이름은 Claude의 컨텍스트에서 도구를 제거합니다. `"Bash(rm *)"` 같은 범위 지정 규칙은 도구를 사용 가능하게 유지하고 `bypassPermissions`를 포함한 모든 권한 모드에서 일치하는 호출을 거부합니다. [권한](/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |

912| `enable_file_checkpointing` | `bool` | `False` | 되감기를 위한 파일 변경 추적 활성화. [파일 체크포인팅](/ko/agent-sdk/file-checkpointing) 참조 |912| `enable_file_checkpointing` | `bool` | `False` | 되감기를 위한 파일 변경 추적 활성화. [파일 체크포인팅](/ko/agent-sdk/file-checkpointing) 참조 |

913| `model` | `str \| None` | `None` | 사용할 Claude 모델 |913| `model` | `str \| None` | `None` | Claude 모델 별칭 또는 전체 모델 이름. [허용되는 값 및 공급자별 ID](/ko/model-config#available-models) 참조 |

914| `fallback_model` | `str \| None` | `None` | 기본 모델이 실패할 경우 사용할 폴백 모델 |914| `fallback_model` | `str \| None` | `None` | 기본 모델이 실패할 경우 사용할 폴백 모델 |

915| `betas` | `list[SdkBeta]` | `[]` | 활성화할 베타 기능. 사용 가능한 옵션은 [`SdkBeta`](#sdkbeta) 참조 |915| `betas` | `list[SdkBeta]` | `[]` | 활성화할 베타 기능. 사용 가능한 옵션은 [`SdkBeta`](#sdkbeta) 참조 |

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


934| `plugins` | `list[SdkPluginConfig]` | `[]` | 로컬 경로에서 사용자 정의 플러그인 로드. 자세한 내용은 [플러그인](/ko/agent-sdk/plugins) 참조 |934| `plugins` | `list[SdkPluginConfig]` | `[]` | 로컬 경로에서 사용자 정의 플러그인 로드. 자세한 내용은 [플러그인](/ko/agent-sdk/plugins) 참조 |

935| `sandbox` | [`SandboxSettings`](#sandboxsettings) ` \| None` | `None` | 프로그래밍 방식으로 샌드박스 동작 구성. 자세한 내용은 [샌드박스 설정](#sandboxsettings) 참조 |935| `sandbox` | [`SandboxSettings`](#sandboxsettings) ` \| None` | `None` | 프로그래밍 방식으로 샌드박스 동작 구성. 자세한 내용은 [샌드박스 설정](#sandboxsettings) 참조 |

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

937| `skills` | `list[str] \| Literal["all"] \| None` | `None` | 세션에서 사용 가능한 스킬. 모든 발견된 스킬을 활성화하려면 `"all"`을 전달하거나, 스킬 이름 목록을 전달합니다. 설정하면 SDK는 `allowed_tools`에 나열하지 않고도 Skill 도구를 자동으로 활성화합니다. [스킬](/ko/agent-sdk/skills) 참조 |937| `skills` | `list[str] \| Literal["all"] \| None` | `None` | 세션에서 사용 가능한 스킬. 모든 발견된 스킬을 활성화하려면 `"all"`을 전달하거나, 스킬 이름 목록을 전달합니다. 설정하면 SDK는 `allowed_tools`에 Skill 도구를 자동으로 추가합니다. `tools`도 전달하는 경우 해당 목록에 `"Skill"`을 포함합니다. [스킬](/ko/agent-sdk/skills) 참조 |

938| `max_thinking_tokens` | `int \| None` | `None` | *Deprecated* - 생각 블록의 최대 토큰. 대신 `thinking` 사용 |938| `max_thinking_tokens` | `int \| None` | `None` | *Deprecated* - 생각 블록의 최대 토큰. 대신 `thinking` 사용 |

939| `thinking` | [`ThinkingConfig`](#thinkingconfig) ` \| None` | `None` | 확장된 생각 동작을 제어합니다. `max_thinking_tokens`보다 우선합니다 |939| `thinking` | [`ThinkingConfig`](#thinkingconfig) ` \| None` | `None` | 확장된 생각 동작을 제어합니다. `max_thinking_tokens`보다 우선합니다 |

940| `effort` | [`EffortLevel`](#effortlevel) ` \| None` | `None` | 생각 깊이를 위한 노력 수준 |940| `effort` | [`EffortLevel`](#effortlevel) ` \| None` | `None` | 생각 깊이를 위한 노력 수준. [노력 수준 조정](/ko/model-config#adjust-effort-level) 참조 |

941| `session_store` | [`SessionStore`](/ko/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | 세션 기록을 외부 백엔드로 미러링하여 모든 호스트가 이를 재개할 수 있도록 합니다. [외부 저장소에 세션 유지](/ko/agent-sdk/session-storage) 참조 |941| `session_store` | [`SessionStore`](/ko/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | 세션 기록을 외부 백엔드로 미러링하여 모든 호스트가 이를 재개할 수 있도록 합니다. [외부 저장소에 세션 유지](/ko/agent-sdk/session-storage) 참조 |

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

943 943 


960* `API_TIMEOUT_MS`: Anthropic 클라이언트의 요청당 시간 초과 (밀리초). 기본값 `600000`. 주 루프 및 모든 서브에이전트에 적용됩니다.960* `API_TIMEOUT_MS`: Anthropic 클라이언트의 요청당 시간 초과 (밀리초). 기본값 `600000`. 주 루프 및 모든 서브에이전트에 적용됩니다.

961* `CLAUDE_CODE_MAX_RETRIES`: 최대 API 재시도. 기본값 `10`. 각 재시도는 자체 `API_TIMEOUT_MS` 윈도우를 가지므로, 최악의 경우 벽시간은 대략 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 더하기 백오프입니다.961* `CLAUDE_CODE_MAX_RETRIES`: 최대 API 재시도. 기본값 `10`. 각 재시도는 자체 `API_TIMEOUT_MS` 윈도우를 가지므로, 최악의 경우 벽시간은 대략 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 더하기 백오프입니다.

962* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: `run_in_background`으로 시작된 서브에이전트의 정지 감시견. 기본값 `600000`. 각 스트림 이벤트에서 재설정됩니다. 정지 시 서브에이전트를 중단하고, 작업을 실패로 표시하고, 부분 결과와 함께 오류를 부모에게 표시합니다. 동기 서브에이전트에는 적용되지 않습니다.962* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: `run_in_background`으로 시작된 서브에이전트의 정지 감시견. 기본값 `600000`. 각 스트림 이벤트에서 재설정됩니다. 정지 시 서브에이전트를 중단하고, 작업을 실패로 표시하고, 부분 결과와 함께 오류를 부모에게 표시합니다. 동기 서브에이전트에는 적용되지 않습니다.

963* `CLAUDE_ENABLE_STREAM_WATCHDOG=1` with `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: 헤더가 도착했지만 응답 본문이 스트리밍을 중지할 때 요청을 중단합니다. 기본적으로 꺼져 있습니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`는 기본값 `300000`이고 해당 최소값으로 제한됩니다. 중단된 요청은 정상 재시도 경로를 거칩니다.963* `CLAUDE_ENABLE_STREAM_WATCHDOG=1` with `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: 헤더가 도착했지만 응답 본문이 스트리밍을 중지할 때 요청을 중단합니다. `CLAUDE_ENABLE_STREAM_WATCHDOG`이 설정되지 않으면 기본값은 직접 Anthropic API에서는 서버 제어이고 다른 공급자에서는 꺼져 있습니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`는 기본값 `300000`이고 해당 최소값으로 제한됩니다. 중단된 요청은 정상 재시도 경로를 거칩니다.

964 964 

965<h3 id="outputformat">965<h3 id="outputformat">

966 `OutputFormat`966 `OutputFormat`


977```977```

978 978 

979| 필드 | 필수 | 설명 |979| 필드 | 필수 | 설명 |

980| :------- | :- | :------------------------------- |980| :------- | :- | :---------------------------------------- |

981| `type` | 예 | 출력 검증을 위해 `"json_schema"`이어야 합니다 |981| `type` | 예 | JSON Schema 검증을 위해 `"json_schema"`이어야 합니다 |

982| `schema` | 예 | 출력 검증을 위한 JSON Schema 정의 |982| `schema` | 예 | 출력 검증을 위한 JSON Schema 정의 |

983 983 

984<h3 id="systempromptpreset">984<h3 id="systempromptpreset">


1016| :---------- | :---------------------- | :---------------------------- |1016| :---------- | :---------------------- | :---------------------------- |

1017| `"user"` | 전역 사용자 설정 | `~/.claude/settings.json` |1017| `"user"` | 전역 사용자 설정 | `~/.claude/settings.json` |

1018| `"project"` | 공유 프로젝트 설정 (버전 제어됨) | `.claude/settings.json` |1018| `"project"` | 공유 프로젝트 설정 (버전 제어됨) | `.claude/settings.json` |

1019| `"local"` | 로컬 프로젝트 설정 (gitignored) | `.claude/settings.local.json` |1019| `"local"` | 로컬 프로젝트 설정 (버전 제어되지 않음) | `.claude/settings.local.json` |

1020 1020 

1021<h4 id="default-behavior">1021<h4 id="default-behavior">

1022 기본 동작1022 기본 동작


1160```1160```

1161 1161 

1162| 필드 | 필수 | 설명 |1162| 필드 | 필수 | 설명 |

1163| :---------------- | :-- | :------------------------------------------------------------------------------------------------------ |1163| :---------------- | :-- | :----------------------------------------------------------------------------------------------------------------------------------------- |

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

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

1166| `tools` | 아니오 | 허용된 도구 이름의 배열. 생략하면 모든 도구를 상속합니다 |1166| `tools` | 아니오 | 허용된 도구 이름의 배열. 생략하면 모든 도구를 상속합니다 |

1167| `disallowedTools` | 아니오 | 에이전트의 도구 세트에서 제거할 도구 이름의 배열 |1167| `disallowedTools` | 아니오 | 에이전트의 도구 세트에서 제거할 도구 이름의 배열. MCP 서버 수준 패턴도 허용됩니다: `mcp__server` 또는 `mcp__server__*`는 해당 서버의 모든 도구를 제거하고, `mcp__*`는 모든 서버의 모든 MCP 도구를 제거합니다 |

1168| `model` | 아니오 | 이 에이전트의 모델 재정의. `"sonnet"`, `"opus"`, `"haiku"`, `"inherit"` 같은 별칭 또는 전체 모델 ID를 허용합니다. 생략하면 주 모델을 사용합니다 |1168| `model` | 아니오 | 이 에이전트의 모델 재정의. `"sonnet"`, `"opus"`, `"haiku"`, `"inherit"` 같은 별칭 또는 전체 모델 ID를 허용합니다. 생략하면 주 모델을 사용합니다 |

1169| `skills` | 아니오 | 이 에이전트가 사용할 수 있는 스킬 이름 목록 |1169| `skills` | 아니오 | 이 에이전트가 사용할 수 있는 스킬 이름 목록 |

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


1189PermissionMode = Literal[1189PermissionMode = Literal[

1190 "default", # Standard permission behavior1190 "default", # Standard permission behavior

1191 "acceptEdits", # Auto-accept file edits1191 "acceptEdits", # Auto-accept file edits

1192 "plan", # Planning mode - read-only tools only1192 "plan", # Planning mode - explore without editing

1193 "dontAsk", # Deny anything not pre-approved instead of prompting1193 "dontAsk", # Deny anything not pre-approved instead of prompting

1194 "bypassPermissions", # Bypass all permission checks (use with caution)1194 "bypassPermissions", # Bypass permission checks; explicit ask rules still prompt (use with caution)

1195]1195]

1196```1196```

1197 1197 


1206 "low", # Minimal thinking, fastest responses1206 "low", # Minimal thinking, fastest responses

1207 "medium", # Moderate thinking1207 "medium", # Moderate thinking

1208 "high", # Deep reasoning1208 "high", # Deep reasoning

1209 "xhigh", # Extended reasoning (Opus 4.7 only; falls back to "high" on other models)1209 "xhigh", # Extended reasoning (Opus 4.8 and Opus 4.7; falls back to "high" on other models)

1210 "max", # Maximum effort1210 "max", # Maximum effort

1211]1211]

1212```1212```


1432`ClaudeAgentOptions`의 `betas` 필드와 함께 사용하여 베타 기능을 활성화합니다.1432`ClaudeAgentOptions`의 `betas` 필드와 함께 사용하여 베타 기능을 활성화합니다.

1433 1433 

1434<Warning>1434<Warning>

1435 `context-1m-2025-08-07` 베타는 2026년 4월 30일부터 폐기되었습니다. Claude Sonnet 4.5 또는 Sonnet 4와 함께 이 헤더를 전달하면 효과가 없으며, 표준 200k 토큰 컨텍스트 윈도우를 초과하는 요청은 오류를 반환합니다. 1M 토큰 컨텍스트 윈도우를 사용하려면 [Claude Sonnet 4.6, Claude Opus 4.6 또는 Claude Opus 4.7](https://platform.claude.com/docs/en/about-claude/models/overview)로 마이그레이션하십시오. 이들은 베타 헤더 없이 표준 가격으로 1M 컨텍스트를 포함합니다.1435 `context-1m-2025-08-07` 베타는 2026년 4월 30일부터 폐기되었습니다. Claude Sonnet 4.5 또는 Sonnet 4와 함께 이 헤더를 전달하면 효과가 없으며, 표준 200k 토큰 컨텍스트 윈도우를 초과하는 요청은 오류를 반환합니다. 1M 토큰 컨텍스트 윈도우를 사용하려면 [Claude Sonnet 4.6, Claude Opus 4.6, Claude Opus 4.7 또는 Claude Opus 4.8](https://platform.claude.com/docs/en/about-claude/models/overview)로 마이그레이션하십시오. 이들은 베타 헤더 없이 표준 가격으로 1M 컨텍스트를 포함합니다.

1436</Warning>1436</Warning>

1437 1437 

1438<h3 id="mcpsdkserverconfig">1438<h3 id="mcpsdkserverconfig">


1706 uuid: str | None = None1706 uuid: str | None = None

1707```1707```

1708 1708 

1709`subtype` 필드는 다른 필드가 채워지는지 결정합니다. 이는 `"success"`, `"error_during_execution"`, `"error_max_turns"`, `"error_max_budget_usd"` 또는 `"error_max_structured_output_retries"` 중 하나입니다. Python 데이터클래스는 모든 변형을 하나의 형태로 평탄화하므로 반환된 서브타입에 적용되지 않는 필드는 `None`입니다.

1710 

1711대화가 오류로 끝날 때 여러 필드가 진단 세부 정보를 전달합니다:

1712 

1713* `is_error`: 대화가 오류 상태로 끝났을 때 `True`입니다. 항상 `error_*` 서브타입에서 `True`입니다. `subtype="success"`에서는 최종 모델 요청이 실패했을 때 `True`입니다. 즉, 에이전트 루프가 완료되었지만 마지막 API 호출이 오류를 반환했습니다.

1714* `api_error_status`: 종료 API 오류의 HTTP 상태 코드입니다. 턴이 오류 없이 끝났을 때 `None`입니다. `subtype="success"`에서만 채워집니다.

1715* `result`: `subtype="success"`에서 최종 어시스턴트 메시지의 텍스트이거나, `error_*` 서브타입에서 `None`입니다. `subtype="success"`이고 `is_error=True`일 때, 이는 사용 가능한 경우 API 오류 문자열을 보유하지만 비어 있을 수 있으므로 `api_error_status`와 이전 `AssistantMessage` 콘텐츠를 확인하십시오.

1716* `errors`: 최대 턴 메시지와 같은 루프 수준 오류 문자열입니다. `error_*` 서브타입에서만 채워집니다.

1717 

1709`usage` dict는 존재할 때 다음 키를 포함합니다:1718`usage` dict는 존재할 때 다음 키를 포함합니다:

1710 1719 

1711| 키 | 타입 | 설명 |1720| 키 | 타입 | 설명 |


3625 대신 중지하려면 샌드박스 설정에서 `"failIfUnavailable": True`를 설정하십시오. 이 키는 아직 `SandboxSettings`에 선언되지 않았지만, SDK는 이를 Claude Code로 전달하며, Claude Code는 이를 준수합니다. 그러면 `query()`는 메시지를 생성하기 전에 예외를 발생시키지 않고 `subtype="error_during_execution"`과 `errors`의 이유를 포함한 `ResultMessage`를 보고합니다. `query()`가 메시지를 생성하기 전에 예외를 발생시킬 것으로 예상하지 말고 해당 서브타입을 감시하십시오.3634 대신 중지하려면 샌드박스 설정에서 `"failIfUnavailable": True`를 설정하십시오. 이 키는 아직 `SandboxSettings`에 선언되지 않았지만, SDK는 이를 Claude Code로 전달하며, Claude Code는 이를 준수합니다. 그러면 `query()`는 메시지를 생성하기 전에 예외를 발생시키지 않고 `subtype="error_during_execution"`과 `errors`의 이유를 포함한 `ResultMessage`를 보고합니다. `query()`가 메시지를 생성하기 전에 예외를 발생시킬 것으로 예상하지 말고 해당 서브타입을 감시하십시오.

3626</Note>3635</Note>

3627 3636 

3628<h4 id="example-usage">3637<h4 id="example-usage-1">

3629 사용 예제3638 사용 예제

3630</h4>3639</h4>

3631 3640 

Details

340**권한 모드**는 원하는 인간 감독의 양을 제어합니다:340**권한 모드**는 원하는 인간 감독의 양을 제어합니다:

341 341 

342| 모드 | 동작 | 사용 사례 |342| 모드 | 동작 | 사용 사례 |

343| ----------------------- | -------------------------------------------- | ------------------------ |343| ----------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------ |

344| `acceptEdits` | 파일 편집 및 일반적인 파일 시스템 명령을 자동 승인하고 다른 작업을 요청합니다 | 신뢰할 수 있는 개발 워크플로우 |344| `acceptEdits` | 파일 편집 및 일반적인 파일 시스템 명령을 자동 승인하고 다른 작업을 요청합니다 | 신뢰할 수 있는 개발 워크플로우 |

345| `dontAsk` | `allowedTools`에 없는 모든 것을 거부합니다 | 잠금된 헤드리스 에이전트 |345| `dontAsk` | `allowedTools`에 없는 모든 것을 거부합니다 | 잠금된 헤드리스 에이전트 |

346| `auto` (TypeScript만 해당) | 모델 분류기가 각 도구 호출을 승인하거나 거부합니다 | 안전 가드레일이 있는 자율 에이전트 |346| `auto` (TypeScript만 해당) | 모델 분류기가 각 도구 호출을 승인하거나 거부합니다 | 안전 가드레일이 있는 자율 에이전트 |

347| `bypassPermissions` | 프롬프트 없이 모든 도구를 실행합니다 | 샌드박스 CI, 완전히 신뢰할 수 있는 환경 |347| `bypassPermissions` | 명시적 [`ask` 규칙](/ko/agent-sdk/permissions#how-permissions-are-evaluated)이 일치하지 않는 한 프롬프트 없이 모든 도구를 실행합니다 | 샌드박스 CI, 완전히 신뢰할 수 있는 환경 |

348| `default` | 승인을 처리하기 위해 `canUseTool` 콜백이 필요합니다 | 사용자 정의 승인 흐름 |348| `default` | 승인을 처리하기 위해 `canUseTool` 콜백이 필요합니다 | 사용자 정의 승인 흐름 |

349 349 

350위의 예제는 `acceptEdits` 모드를 사용하며, 이는 파일 작업을 자동 승인하므로 에이전트가 대화형 프롬프트 없이 실행될 수 있습니다. 사용자에게 승인을 요청하려면 `default` 모드를 사용하고 사용자 입력을 수집하는 [`canUseTool` 콜백](/ko/agent-sdk/user-input)을 제공합니다. 더 많은 제어를 위해 [권한](/ko/agent-sdk/permissions)을 참조합니다.350위의 예제는 `acceptEdits` 모드를 사용하며, 이는 파일 작업을 자동 승인하므로 에이전트가 대화형 프롬프트 없이 실행될 수 있습니다. 사용자에게 승인을 요청하려면 `default` 모드를 사용하고 사용자 입력을 수집하는 [`canUseTool` 콜백](/ko/agent-sdk/user-input)을 제공합니다. 더 많은 제어를 위해 [권한](/ko/agent-sdk/permissions)을 참조합니다.


369 다음 단계369 다음 단계

370</h2>370</h2>

371 371 

372첫 번째 에이전트를 생성했으므로 기능을 확장하고 사용 사례에 맞게 조정하는 방법을 알아봅니다:372이제 첫 번째 에이전트를 생성했으므로 기능을 확장하고 사용 사례에 맞게 조정하는 방법을 알아봅니다:

373 373 

374* **[권한](/ko/agent-sdk/permissions)**: 에이전트가 수행할 수 있는 작업과 승인이 필요한 시기를 제어합니다374* **[권한](/ko/agent-sdk/permissions)**: 에이전트가 수행할 수 있는 작업과 승인이 필요한 시기를 제어합니다

375* **[Hooks](/ko/agent-sdk/hooks)**: 도구 호출 전후에 사용자 정의 코드를 실행합니다375* **[Hooks](/ko/agent-sdk/hooks)**: 도구 호출 전후에 사용자 정의 코드를 실행합니다

Details

18 위협 모델18 위협 모델

19</h2>19</h2>

20 20 

21에이전트는 프롬프트 주입(처리하는 콘텐츠에 포함된 지시사항) 또는 모델 오류로 인해 의도하지 않은 작업을 수행할 수 있습니다. Claude 모델은 이에 저항하도록 설계되었습니다. 자세한 평가는 [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview) 및 배포하는 모델의 시스템 카드를 참조하십시오.21에이전트는 프롬프트 주입(처리하는 콘텐츠에 포함된 지시사항) 또는 모델 오류로 인해 의도하지 않은 작업을 수행할 수 있습니다. Claude 모델은 이에 저항하도록 설계되었습니다. 자세한 평가는 [모델 개요](https://platform.claude.com/docs/ko/about-claude/models/overview) 및 배포하는 모델의 시스템 카드를 참조하십시오.

22 22 

23그럼에도 불구하고 심층 방어는 좋은 관행입니다. 예를 들어, 에이전트가 고객 데이터를 외부 서버로 보내도록 지시하는 악성 파일을 처리하는 경우, 네트워크 제어가 해당 요청을 완전히 차단할 수 있습니다.23그럼에도 불구하고 심층 방어는 좋은 관행입니다. 예를 들어, 에이전트가 고객 데이터를 외부 서버로 보내도록 지시하는 악성 파일을 처리하는 경우, 네트워크 제어가 해당 요청을 완전히 차단할 수 있습니다.

24 24 

Details

150 ```150 ```

151</CodeGroup>151</CodeGroup>

152 152 

153두 번째 쿼리는 첫 번째 쿼리의 파일 요약을 출력하며, 이는 에이전트가 저장소에서 전체 컨텍스트와 함께 재개되었음을 보여줍니다.

154 

153<h2 id="write-your-own-adapter">155<h2 id="write-your-own-adapter">

154 자신의 어댑터 작성하기156 자신의 어댑터 작성하기

155</h2>157</h2>

Details

230 ```230 ```

231 231 

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

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

234 

235 const sessionId = "..."; // The ID you captured in the previous example

236 

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

234 for await (const message of query({238 for await (const message of query({

235 prompt: "Now implement the refactoring you suggested",239 prompt: "Now implement the refactoring you suggested",


245 ```249 ```

246</CodeGroup>250</CodeGroup>

247 251 

252이전 분석을 기반으로 하는 응답이 표시되어야 하며, 이는 에이전트가 이전 컨텍스트를 유지한 상태로 세션을 재개했음을 확인합니다.

253 

248<Tip>254<Tip>

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

250</Tip>256</Tip>

251 257 

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


268 # Fork: branch from session_id into a new session274 # Fork: branch from session_id into a new session

269 forked_id = None275 forked_id = None

270 async for message in query(276 async for message in query(

271 prompt="Instead of JWT, implement OAuth2 for the auth module",277 prompt="Instead of JWT, outline how OAuth2 would work for the auth module",

272 options=ClaudeAgentOptions(278 options=ClaudeAgentOptions(

273 resume=session_id,279 resume=session_id,

274 fork_session=True,280 fork_session=True,

281 max_turns=5,

275 ),282 ),

276 ):283 ):

277 if isinstance(message, ResultMessage):284 if isinstance(message, ResultMessage):


291 ```298 ```

292 299 

293 ```typescript TypeScript theme={null}300 ```typescript TypeScript theme={null}

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

302 

303 const sessionId = "..."; // The ID you captured in the previous example

304 

294 // Fork: branch from sessionId into a new session305 // Fork: branch from sessionId into a new session

295 let forkedId: string | undefined;306 let forkedId: string | undefined;

296 307 

297 for await (const message of query({308 for await (const message of query({

298 prompt: "Instead of JWT, implement OAuth2 for the auth module",309 prompt: "Instead of JWT, outline how OAuth2 would work for the auth module",

299 options: {310 options: {

300 resume: sessionId,311 resume: sessionId,

301 forkSession: true312 forkSession: true,

313 maxTurns: 5

302 }314 }

303 })) {315 })) {

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


323 ```335 ```

324</CodeGroup>336</CodeGroup>

325 337 

338`forkedId`가 원본 세션 ID와 다른지 확인해야 합니다. 원본 세션을 재개하면 여전히 JWT 스레드를 계속하며, 이는 포크가 원본 기록을 수정하지 않았음을 확인합니다.

339 

326<h2 id="resume-across-hosts">340<h2 id="resume-across-hosts">

327 호스트 간에 재개하기341 호스트 간에 재개하기

328</h2>342</h2>

Details

119 119 

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

121 121 

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

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

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

125 124 

126<h2 id="tool-restrictions">125<h2 id="tool-restrictions">

127 도구 제한126 도구 제한

Details

101 parent_tool_use_id: string | null;101 parent_tool_use_id: string | null;

102 uuid: UUID;102 uuid: UUID;

103 session_id: string;103 session_id: string;

104 ttft_ms?: number; // Time to first token in ms, present only on message_start events

104 };105 };

105 ```106 ```

106</CodeGroup>107</CodeGroup>

Details

218 ```218 ```

219</CodeGroup>219</CodeGroup>

220 220 

221<Note>

222 TypeScript SDK에서 예를 들어 읽는 파일이 누락되었을 때 메시지 생성기가 throw하면, 스트림은 원래 오류 대신 `Claude Code process aborted by user`라고 읽는 오류로 끝나므로, 해당 메시지가 표시되면 먼저 생성기 내부의 코드를 확인하십시오. 오류 앞에 번들된 SDK 소스의 긴 축소된 줄이 있을 수도 있으므로, 오류 텍스트를 찾기 위해 출력의 끝까지 읽으십시오.

223 

224 Python SDK에서는 생성기 예외가 디버그 수준에서 기록되고 세션이 raise하지 않고 정지되므로, 스트리밍 세션이 출력 없이 중단되면 디버그 로깅을 활성화하고 생성기를 확인하십시오.

225</Note>

226 

221<h2 id="single-message-input">227<h2 id="single-message-input">

222 단일 메시지 입력228 단일 메시지 입력

223</h2>229</h2>


247 * 자연스러운 다중 턴 대화253 * 자연스러운 다중 턴 대화

248</Warning>254</Warning>

249 255 

250<h3 id="implementation-example">256쿼리가 `error_max_turns`와 같은 오류 결과로 끝나면, 단일 메시지 `query()` 호출은 최종 결과 메시지를 생성한 후 실패 텍스트를 포함하는 오류를 발생시키므로, 코드가 계속 실행되어야 하는 경우 루프를 try 블록으로 감싸십시오. 결과 하위 유형에 대해서는 [결과 처리](/ko/agent-sdk/agent-loop#handle-the-result)를 참조하십시오.

257 

258<h3 id="implementation-example-1">

251 구현 예제259 구현 예제

252</h3>260</h3>

253 261 

Details

358 오류 처리358 오류 처리

359</h2>359</h2>

360 360 

361구조화된 출력 생성은 에이전트가 스키마와 일치하는 유효한 JSON을 생성할 수 없을 때 실패할 수 있습니다. 이는 일반적으로 스키마가 작업에 너무 복잡하거나, 작업 자체가 모호하거나, 에이전트가 검증 오류를 수정하려고 시도하는 동안 재시도 제한에 도달할 때 발생합니다.361구조화된 출력 생성은 에이전트가 스키마와 일치하는 유효한 JSON을 생성할 수 없을 때 실패할 수 있습니다. 이는 일반적으로 스키마가 작업에 너무 복잡하거나, 작업 자체가 모호하거나, 에이전트가 검증 오류를 수정하려고 시도하는 동안 재시도 제한에 도달할 때 발생합니다. 또한 검증 실패 없이도 발생할 수 있습니다: [모델 폴백](/ko/model-config#automatic-model-fallback)은 이미 완료된 출력을 스트림 중간에 취소할 수 있으며, 재시도가 이를 대체하지 않으면 실행이 동일한 오류로 종료됩니다. 디버깅하기 전에 결과 메시지의 `errors` 필드를 확인하여 두 가지 원인을 구분하십시오.

362 362 

363오류가 발생하면 결과 메시지에 무엇이 잘못되었는지 나타내는 `subtype`이 있습니다:363오류가 발생하면 결과 메시지에 무엇이 잘못되었는지 나타내는 `subtype`이 있습니다:

364 364 

365| Subtype | 의미 |365| Subtype | 의미 |

366| ------------------------------------- | ------------------------------ |366| ------------------------------------- | ----------------------------------------------------- |

367| `success` | 출력이 성공적으로 생성되고 검증됨 |367| `success` | 출력이 성공적으로 생성되고 검증됨 |

368| `error_max_structured_output_retries` | 에이전트가 여러 시도 후 유효한 출력을 생성할 없음 |368| `error_max_structured_output_retries` | 여러 시도 후 유효한 출력이 남지 않음(검증 실패 또는 성공적인 재시도가 없는 모델 폴백 취소) |

369 369 

370아래 예제는 `subtype` 필드를 확인하여 출력이 성공적으로 생성되었는지 또는 실패를 처리해야 하는지 결정합니다:370아래 예제는 `subtype` 필드를 확인하여 출력이 성공적으로 생성되었는지 또는 실패를 처리해야 하는지 결정합니다:

371 371 

372<CodeGroup>372<CodeGroup>

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

374 for await (const msg of query({374 for await (const msg of query({

375 prompt: "문서에서 연락처 정보를 추출하세요",375 prompt: "Extract contact info from the document",

376 options: {376 options: {

377 outputFormat: {377 outputFormat: {

378 type: "json_schema",378 type: "json_schema",


394 394 

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

396 async for message in query(396 async for message in query(

397 prompt="문서에서 연락처 정보를 추출하세요",397 prompt="Extract contact info from the document",

398 options=ClaudeAgentOptions(398 options=ClaudeAgentOptions(

399 output_format={"type": "json_schema", "schema": contact_schema}399 output_format={"type": "json_schema", "schema": contact_schema}

400 ),400 ),


411 411 

412**오류 방지 팁:**412**오류 방지 팁:**

413 413 

414* **스키마를 집중적으로 유지하세요.** 많은 필수 필드가 있는 깊게 중첩된 스키마는 만족하기 어렵습니다. 간단하게 시작하고 필요에 따라 복잡성을 추가하세요.414* **스키마를 집중적으로 유지하십시오.** 많은 필수 필드가 있는 깊게 중첩된 스키마는 만족하기 어렵습니다. 간단하게 시작하고 필요에 따라 복잡성을 추가하십시오.

415* **스키마를 작업과 일치시키세요.** 작업에 스키마가 요구하는 모든 정보가 없을 수 있으면 해당 필드를 선택적으로 만드세요.415* **스키마를 작업과 일치시키십시오.** 작업에 스키마가 요구하는 모든 정보가 없을 수 있으면 해당 필드를 선택적으로 만드십시오.

416* **명확한 프롬프트를 사용하세요.** 모호한 프롬프트는 에이전트가 생성할 출력을 알기 어렵게 합니다.416* **명확한 프롬프트를 사용하십시오.** 모호한 프롬프트는 에이전트가 생성할 출력을 알기 어렵게 합니다.

417 417 

418<h2 id="related-resources">418<h2 id="related-resources">

419 관련 리소스419 관련 리소스

Details

41 병렬화41 병렬화

42</h3>42</h3>

43 43 

44여러 서브에이전트를 동시에 실행하여 복잡한 워크플로우의 속도를 대폭 향상시킬 있습니다.44여러 서브에이전트를 동시에 실행할 있으므로, 독립적인 부분 작업은 모든 작업의 합이 아닌 가장 느린 작업의 시간에 완료됩니다.

45 45 

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

47 47 

48<h3 id="specialized-instructions-and-knowledge">48<h3 id="specialized-instructions-and-knowledge">

49 특화된 지침 및 지식49 특화된 지침 및 지식


178</h3>178</h3>

179 179 

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

181| :---------------- | :---------------------------------------------------------- | :-- | :--------------------------------------------------------------------------------------------------------------- |181| :---------------- | :---------------------------------------------------------- | :-- | :--------------------------------------------------------------------------------------------------------------------------------------------- |

182| `description` | `string` | 예 | 이 에이전트를 사용할 때를 설명하는 자연어 설명 |182| `description` | `string` | 예 | 이 에이전트를 사용할 때를 설명하는 자연어 설명 |

183| `prompt` | `string` | 예 | 에이전트의 역할과 동작을 정의하는 시스템 프롬프트 |183| `prompt` | `string` | 예 | 에이전트의 역할과 동작을 정의하는 시스템 프롬프트 |

184| `tools` | `string[]` | 아니오 | 허용된 도구 이름의 배열입니다. 생략하면 모든 도구를 상속합니다. |184| `tools` | `string[]` | 아니오 | 허용된 도구 이름의 배열입니다. 생략하면 모든 도구를 상속합니다. |

185| `disallowedTools` | `string[]` | 아니오 | 에이전트의 도구 세트에서 제거할 도구 이름의 배열 |185| `disallowedTools` | `string[]` | 아니오 | 에이전트의 도구 세트에서 제거할 도구 이름의 배열입니다. MCP 서버 수준 패턴도 허용됩니다: `mcp__server` 또는 `mcp__server__*`는 해당 서버의 모든 도구를 제거하고, `mcp__*`는 모든 서버의 모든 MCP 도구를 제거합니다. |

186| `model` | `string` | 아니오 | 이 에이전트의 모델 재정의입니다. `'sonnet'`, `'opus'`, `'haiku'`, `'inherit'` 또는 전체 모델 ID와 같은 별칭을 허용합니다. 생략하면 메인 모델로 기본 설정됩니다. |186| `model` | `string` | 아니오 | 이 에이전트의 모델 재정의입니다. `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'` 또는 전체 모델 ID와 같은 별칭을 허용합니다. 생략하면 메인 모델로 기본 설정됩니다. |

187| `skills` | `string[]` | 아니오 | 시작 시 에이전트의 컨텍스트에 미리 로드할 스킬 이름 목록입니다. 나열되지 않은 스킬은 Skill 도구를 통해 호출 가능합니다. |187| `skills` | `string[]` | 아니오 | 시작 시 에이전트의 컨텍스트에 미리 로드할 스킬 이름 목록입니다. 나열되지 않은 스킬은 Skill 도구를 통해 호출 가능합니다. |

188| `memory` | `'user' \| 'project' \| 'local'` | 아니오 | 이 에이전트의 메모리 소스 |188| `memory` | `'user' \| 'project' \| 'local'` | 아니오 | 이 에이전트의 메모리 소스 |

189| `mcpServers` | `(string \| object)[]` | 아니오 | 이 에이전트가 사용할 수 있는 MCP 서버(이름 또는 인라인 구성) |189| `mcpServers` | `(string \| object)[]` | 아니오 | 이 에이전트가 사용할 수 있는 MCP 서버(이름 또는 인라인 구성) |

190| `initialPrompt` | `string` | 아니오 | 이 에이전트가 메인 스레드 에이전트로 실행될 때 첫 번째 사용자 턴으로 자동 제출됩니다. 에이전트가 서브에이전트로 호출될 때는 무시됩니다. |

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

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

192| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max' \| number` | 아니오 | 이 에이전트의 추론 노력 수준 |193| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max' \| number` | 아니오 | 이 에이전트의 추론 노력 수준 |


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

196 197 

197<Note>198<Note>

198 서브에이전트는 자신의 서브에이전트를 생성할 수 없습니다. 서브에이전트의 `tools` 배열에 `Agent`를 포함하지 마세요.199 {/* min-version: 2.1.172 */}Claude Code v2.1.172부터 서브에이전트는 자신의 서브에이전트를 생성할 수 있습니다. 메인 에이전트 아래 5단계 깊이의 백그라운드 서브에이전트는 추가 서브에이전트를 생성할 수 없습니다. 포그라운드 서브에이전트는 모든 깊이에서 생성할 수 있습니다. 서브에이전트가 다른 서브에이전트를 생성하지 못하도록 하려면 `tools` 배열에서 `Agent`를 생략하거나 `disallowedTools`에 추가합니다. 전체 깊이 규칙은 [중첩된 서브에이전트](/ko/sub-agents#spawn-nested-subagents)를 참조하세요.

199</Note>200</Note>

200 201 

201<h3 id="filesystem-based-definition-alternative">202<h3 id="filesystem-based-definition-alternative">


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

216 217 

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

218| :----------------------------------------------------- | :------------------------------------------------- |219| :------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------- |

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

220| 프로젝트 CLAUDE.md (`settingSources`를 통해 로드됨) | 미리 로드된 스킬 콘텐츠(`AgentDefinition.skills`에 나열된 경우 제외) |221| 프로젝트 CLAUDE.md ([`settingSources`](/ko/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources)를 통해 로드됨) | 미리 로드된 스킬 콘텐츠(`AgentDefinition.skills`에 나열된 경우 제외) |

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

222 223 

223<Note>224<Note>


240 명시적 호출241 명시적 호출

241</h3>242</h3>

242 243 

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

244 245 

245```text theme={null}246```text theme={null}

246"Use the code-reviewer agent to check the authentication module"247"Use the code-reviewer agent to check the authentication module"


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

337</Note>338</Note>

338 339 

339 예시는 스트리밍된 메시지를 반복하여 서브에이전트가 호출될 때와 후속 메시지가 해당 서브에이전트의 실행 컨텍스트 내에서 시작될 때를 기록합니다.340메시지 구조는 SDK 간에 다릅니다. Python에서는 콘텐츠 블록이 `message.content`를 통해 직접 액세스됩니다. TypeScript에서는 `SDKAssistantMessage`가 Claude API 메시지를 래핑하므로 콘텐츠는 `message.message.content`를 통해 액세스됩니다.

340 341 

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

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

343</Note>

344 343 

345<CodeGroup>344<CodeGroup>

346 ```python Python theme={null}345 ```python Python theme={null}


427 426 

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

429 428 

430서브에이전트가 완료되면, Claude는 Agent 도구 결과에서 에이전트 ID를 받습니다. 서브에이전트를 프로그래밍 방식으로 재개하려면:429서브에이전트가 완료되면, Agent 도구 결과에는 `agentId: <id>`를 포함하는 텍스트 블록이 포함됩니다. 기본 제공 [`Explore` 및 `Plan` 에이전트](/ko/sub-agents#built-in-subagents)는 일회성이며 `agentId`를 반환하지 않으므로, 재개가 필요한 경우 사용자 정의 에이전트 또는 `general-purpose`를 사용하세요. 서브에이전트를 프로그래밍 방식으로 재개하려면:

431 430 

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

4332. **에이전트 ID 추출**: 메시지 콘텐츠에서 `agentId` 파싱4322. **에이전트 ID 추출**: Agent 도구 결과 텍스트에서 `agentId` 파싱

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

435 434 

436<Note>435<Note>

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

438 437 

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

440</Note>439</Note>

441 440 

442아래 예시는 흐름을 보여줍니다. 첫 번째 쿼리는 서브에이전트를 실행하고 세션 ID와 에이전트 ID를 캡처하고, 두 번째 쿼리는 세션을 재개하여 첫 번째 분석의 컨텍스트가 필요한 후속 질문을 합니다.441아래 예시는 사용자 정의 `endpoint-finder` 에이전트를 정의합니다. 첫 번째 쿼리는 이를 실행하고 Agent 도구 결과에서 세션 ID와 에이전트 ID를 캡처하고, 두 번째 쿼리는 세션을 재개하여 첫 번째 분석의 컨텍스트가 필요한 후속 질문을 합니다.

443 442 

444<CodeGroup>443<CodeGroup>

445 ```typescript TypeScript theme={null}

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

447 

448 // Helper to extract agentId from message content

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

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

451 if (message.type !== "assistant" && message.type !== "user") return undefined;

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

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

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

455 return match?.[1];

456 }

457 

458 let agentId: string | undefined;

459 let sessionId: string | undefined;

460 

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

462 for await (const message of query({

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

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

465 })) {

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

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

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

469 const extractedId = extractAgentId(message);

470 if (extractedId) agentId = extractedId;

471 // Print the final result

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

473 }

474 

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

476 if (agentId && sessionId) {

477 for await (const message of query({

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

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

480 })) {

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

482 }

483 }

484 ```

485 

486 ```python Python theme={null}444 ```python Python theme={null}

487 import asyncio445 import asyncio

488 import json

489 import re446 import re

490 from claude_agent_sdk import query, ClaudeAgentOptions447 from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ToolResultBlock

448 

449 AGENTS = {

450 "endpoint-finder": AgentDefinition(

451 description="Locates and catalogs API endpoints in a codebase.",

452 prompt="You find and document API endpoints. Report each endpoint's path, method, and handler.",

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

454 )

455 }

491 456 

492 457 

493 def extract_agent_id(text: str) -> str | None:458 def extract_agent_id(block: ToolResultBlock) -> str | None:

494 """Extract agentId from Agent tool result text."""459 """Extract agentId from an Agent tool result's text content."""

495 match = re.search(r"agentId:\s*([a-f0-9-]+)", text)460 parts = block.content if isinstance(block.content, list) else [{"text": block.content}]

496 return match.group(1) if match else None461 for part in parts:

462 if match := re.search(r"agentId:\s*([\w-]+)", part.get("text") or ""):

463 return match.group(1)

464 return None

497 465 

498 466 

499 async def main():467 async def main():

500 agent_id = None468 agent_id = None

501 session_id = None469 session_id = None

502 470 

503 # First invocation - use the Explore agent to find API endpoints471 # First invocation - run the endpoint-finder subagent

504 async for message in query(472 async for message in query(

505 prompt="Use the Explore agent to find all API endpoints in this codebase",473 prompt="Use the endpoint-finder agent to find all API endpoints in this codebase",

506 options=ClaudeAgentOptions(allowed_tools=["Read", "Grep", "Glob", "Agent"]),474 options=ClaudeAgentOptions(allowed_tools=["Read", "Grep", "Glob", "Agent"], agents=AGENTS),

507 ):475 ):

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

509 if hasattr(message, "session_id"):477 if hasattr(message, "session_id"):

510 session_id = message.session_id478 session_id = message.session_id

511 # Search message content for the agentId (appears in Agent tool results)479 # Search tool results for the agentId trailer

512 if hasattr(message, "content"):480 for block in getattr(message, "content", None) or []:

513 # Stringify the content so we can search it without traversing nested blocks481 if isinstance(block, ToolResultBlock):

514 content_str = json.dumps(message.content, default=str)482 agent_id = extract_agent_id(block) or agent_id

515 extracted = extract_agent_id(content_str)

516 if extracted:

517 agent_id = extracted

518 # Print the final result483 # Print the final result

519 if hasattr(message, "result"):484 if hasattr(message, "result"):

520 print(message.result)485 print(message.result)


524 async for message in query(489 async for message in query(

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

526 options=ClaudeAgentOptions(491 options=ClaudeAgentOptions(

527 allowed_tools=["Read", "Grep", "Glob", "Agent"], resume=session_id492 allowed_tools=["Read", "Grep", "Glob", "Agent"], agents=AGENTS, resume=session_id

528 ),493 ),

529 ):494 ):

530 if hasattr(message, "result"):495 if hasattr(message, "result"):


533 498 

534 asyncio.run(main())499 asyncio.run(main())

535 ```500 ```

501 

502 ```typescript TypeScript theme={null}

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

504 

505 const agents = {

506 "endpoint-finder": {

507 description: "Locates and catalogs API endpoints in a codebase.",

508 prompt: "You find and document API endpoints. Report each endpoint's path, method, and handler.",

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

510 }

511 };

512 

513 // Stringify content to search for agentId without traversing nested block types

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

515 if (message.type !== "assistant" && message.type !== "user") return undefined;

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

517 const match = content.match(/agentId:\s*([\w-]+)/);

518 return match?.[1];

519 }

520 

521 let agentId: string | undefined;

522 let sessionId: string | undefined;

523 

524 // First invocation - run the endpoint-finder subagent

525 for await (const message of query({

526 prompt: "Use the endpoint-finder agent to find all API endpoints in this codebase",

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

528 })) {

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

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

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

532 const extractedId = extractAgentId(message);

533 if (extractedId) agentId = extractedId;

534 // Print the final result

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

536 }

537 

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

539 if (agentId && sessionId) {

540 for await (const message of query({

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

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

543 })) {

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

545 }

546 }

547 ```

536</CodeGroup>548</CodeGroup>

537 549 

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

539 551 

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

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

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

543 555 

544<h2 id="tool-restrictions">556<h2 id="tool-restrictions-1">

545 도구 제한557 도구 제한

546</h2>558</h2>

547 559 


654</h2>666</h2>

655 667 

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

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

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

Details

217| 항목 형태: `{ content, status, activeForm }` | `TaskCreate` 입력: `{ subject, description, activeForm?, metadata? }`. `TaskUpdate` 입력: `{ taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }`. `status`는 `"pending"`, `"in_progress"`, 또는 `"completed"`이며, 삭제하려면 `status: "deleted"`를 설정 |217| 항목 형태: `{ content, status, activeForm }` | `TaskCreate` 입력: `{ subject, description, activeForm?, metadata? }`. `TaskUpdate` 입력: `{ taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }`. `status`는 `"pending"`, `"in_progress"`, 또는 `"completed"`이며, 삭제하려면 `status: "deleted"`를 설정 |

218| `block.input.todos`를 직접 렌더링 | 호출 전체에서 항목을 누적하거나, `TaskList` 도구 결과에서 스냅샷을 읽음 |218| `block.input.todos`를 직접 렌더링 | 호출 전체에서 항목을 누적하거나, `TaskList` 도구 결과에서 스냅샷을 읽음 |

219 219 

220할당된 작업 ID는 `TaskCreate` 입력에 없습니다. 일치하는 `tool_result`에서 `{ task: { id, subject } }`로 반환되므로, 맵을 키로 지정하기 위해 결과 블록에서 캡처합니다. 다음 예제는 [할일 변경 모니터링](#monitoring-todo-changes) 루프에 대한 최소한의 변경을 보여줍니다. 전체 목록을 렌더링하려면 스트림에서 `TaskList` 도구 결과를 감시하거나 `TaskCreate` 결과와 `TaskUpdate` 입력을 맵으로 누적합니다:220할당된 작업 ID는 `TaskCreate` 입력에 없습니다. 일치하는 `tool_result`에서 `{ task: { id, subject } }`로 반환되므로, 맵을 키로 지정하기 위해 결과 블록에서 캡처합니다. 다음 예제는 [할일 변경 모니터링](#monitoring-todo-changes) 루프에 대한 최소한의 변경을 보여줍니다. 전체 목록을 렌더링하려면 스트림에서 `TaskList` 도구 결과를 감시하거나 `TaskCreate` 결과와 `TaskUpdate` 입력을 맵으로 누적합니다.

221 

222스트리밍된 `tool_use` 입력은 모델이 내보낸 원본 형태입니다. Claude Code는 실행 전에 일부 거의 올바른 키 이름을 수정하여 `id` 또는 `task_id`를 `taskId`로, `active_form`을 `activeForm`으로 매핑하지만, 이 수정은 스트림에 반영되지 않습니다. 아래 샘플처럼 `TaskUpdate` 입력 필드를 방어적으로 읽으십시오. 정규 이름이 항상 존재한다고 가정하지 마십시오.

221 223 

222<CodeGroup>224<CodeGroup>

223 ```typescript TypeScript theme={null}225 ```typescript TypeScript theme={null}


233 const input = block.input as { subject: string };235 const input = block.input as { subject: string };

234 console.log(`+ ${input.subject}`);236 console.log(`+ ${input.subject}`);

235 } else if (block.name === "TaskUpdate") {237 } else if (block.name === "TaskUpdate") {

236 const input = block.input as { taskId: string; status?: string };238 const input = block.input as {

237 if (input.status) console.log(` ${input.taskId} -> ${input.status}`);239 taskId?: string;

240 id?: string;

241 task_id?: string;

242 status?: string;

243 };

244 const taskId = input.taskId ?? input.id ?? input.task_id;

245 if (taskId && input.status) console.log(` ${taskId} -> ${input.status}`);

238 }246 }

239 }247 }

240 }248 }


254 if block.name == "TaskCreate":262 if block.name == "TaskCreate":

255 print(f"+ {block.input['subject']}")263 print(f"+ {block.input['subject']}")

256 elif block.name == "TaskUpdate" and block.input.get("status"):264 elif block.name == "TaskUpdate" and block.input.get("status"):

257 print(f" {block.input['taskId']} -> {block.input['status']}")265 task_id = (

266 block.input.get("taskId")

267 or block.input.get("id")

268 or block.input.get("task_id")

269 )

270 if task_id:

271 print(f" {task_id} -> {block.input['status']}")

258 ```272 ```

259</CodeGroup>273</CodeGroup>

260 274 

Details

100}): Promise<WarmQuery>;100}): Promise<WarmQuery>;

101```101```

102 102 

103<h4 id="parameters">103<h4 id="parameters-1">

104 매개변수104 매개변수

105</h4>105</h4>

106 106 


109| `options` | [`Options`](#options) | 선택적 구성 객체입니다. `query()`의 `options` 매개변수와 동일합니다 |109| `options` | [`Options`](#options) | 선택적 구성 객체입니다. `query()`의 `options` 매개변수와 동일합니다 |

110| `initializeTimeoutMs` | `number` | 서브프로세스 초기화를 기다릴 최대 시간(밀리초)입니다. 기본값은 `60000`입니다. 초기화가 시간 내에 완료되지 않으면 프로미스는 타임아웃 오류로 거부됩니다 |110| `initializeTimeoutMs` | `number` | 서브프로세스 초기화를 기다릴 최대 시간(밀리초)입니다. 기본값은 `60000`입니다. 초기화가 시간 내에 완료되지 않으면 프로미스는 타임아웃 오류로 거부됩니다 |

111 111 

112<h4 id="returns">112<h4 id="returns-1">

113 반환값113 반환값

114</h4>114</h4>

115 115 


149): SdkMcpToolDefinition<Schema>;149): SdkMcpToolDefinition<Schema>;

150```150```

151 151 

152<h4 id="parameters">152<h4 id="parameters-2">

153 매개변수153 매개변수

154</h4>154</h4>

155 155 


204}): McpSdkServerConfigWithInstance;204}): McpSdkServerConfigWithInstance;

205```205```

206 206 

207<h4 id="parameters">207<h4 id="parameters-3">

208 매개변수208 매개변수

209</h4>209</h4>

210 210 


224function listSessions(options?: ListSessionsOptions): Promise<SDKSessionInfo[]>;224function listSessions(options?: ListSessionsOptions): Promise<SDKSessionInfo[]>;

225```225```

226 226 

227<h4 id="parameters">227<h4 id="parameters-4">

228 매개변수228 매개변수

229</h4>229</h4>

230 230 


251| `tag` | `string \| undefined` | 사용자가 설정한 세션 태그 ([`tagSession()`](#tagsession) 참조) |251| `tag` | `string \| undefined` | 사용자가 설정한 세션 태그 ([`tagSession()`](#tagsession) 참조) |

252| `createdAt` | `number \| undefined` | 첫 번째 항목의 타임스탬프에서 에포크 이후 밀리초 단위의 생성 시간 |252| `createdAt` | `number \| undefined` | 첫 번째 항목의 타임스탬프에서 에포크 이후 밀리초 단위의 생성 시간 |

253 253 

254<h4 id="example">254<h4 id="example-1">

255 예제255 예제

256</h4>256</h4>

257 257 


280): Promise<SessionMessage[]>;280): Promise<SessionMessage[]>;

281```281```

282 282 

283<h4 id="parameters">283<h4 id="parameters-5">

284 매개변수284 매개변수

285</h4>285</h4>

286 286 


303| `message` | `unknown` | 트랜스크립트의 원본 메시지 페이로드 |303| `message` | `unknown` | 트랜스크립트의 원본 메시지 페이로드 |

304| `parent_tool_use_id` | `string \| null` | 서브에이전트 메시지의 경우 생성 `Agent` 도구 호출의 `tool_use_id`입니다. 메인 세션 메시지 및 이전 세션의 경우 `null` |304| `parent_tool_use_id` | `string \| null` | 서브에이전트 메시지의 경우 생성 `Agent` 도구 호출의 `tool_use_id`입니다. 메인 세션 메시지 및 이전 세션의 경우 `null` |

305 305 

306<h4 id="example">306<h4 id="example-2">

307 예제307 예제

308</h4>308</h4>

309 309 


337): Promise<SDKSessionInfo | undefined>;337): Promise<SDKSessionInfo | undefined>;

338```338```

339 339 

340<h4 id="parameters">340<h4 id="parameters-6">

341 매개변수341 매개변수

342</h4>342</h4>

343 343 


362): Promise<void>;362): Promise<void>;

363```363```

364 364 

365<h4 id="parameters">365<h4 id="parameters-7">

366 매개변수366 매개변수

367</h4>367</h4>

368 368 


386): Promise<void>;386): Promise<void>;

387```387```

388 388 

389<h4 id="parameters">389<h4 id="parameters-8">

390 매개변수390 매개변수

391</h4>391</h4>

392 392 


412): Promise<ResolvedSettings>;412): Promise<ResolvedSettings>;

413```413```

414 414 

415<h4 id="parameters">415<h4 id="parameters-9">

416 매개변수416 매개변수

417</h4>417</h4>

418 418 


437| `provenance` | `Partial<Record<keyof Settings, ProvenanceEntry>>` | `effective`의 각 최상위 키에 대해 값을 제공한 소스 |437| `provenance` | `Partial<Record<keyof Settings, ProvenanceEntry>>` | `effective`의 각 최상위 키에 대해 값을 제공한 소스 |

438| `sources` | `Array<{ source, settings, path?, policyOrigin? }>` | 소스별 원본 설정, 가장 낮은 우선순위에서 가장 높은 우선순위 순서로 정렬됨 |438| `sources` | `Array<{ source, settings, path?, policyOrigin? }>` | 소스별 원본 설정, 가장 낮은 우선순위에서 가장 높은 우선순위 순서로 정렬됨 |

439 439 

440<h4 id="example">440<h4 id="example-3">

441 예제441 예제

442</h4>442</h4>

443 443 


472| `agent` | `string` | `undefined` | 메인 스레드의 에이전트 이름입니다. 에이전트는 `agents` 옵션 또는 설정에서 정의되어야 합니다 |472| `agent` | `string` | `undefined` | 메인 스레드의 에이전트 이름입니다. 에이전트는 `agents` 옵션 또는 설정에서 정의되어야 합니다 |

473| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | 프로그래밍 방식으로 서브에이전트 정의 |473| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | 프로그래밍 방식으로 서브에이전트 정의 |

474| `agentProgressSummaries` | `boolean` | `false` | `true`일 때 서브에이전트에 대한 한 줄 진행 요약을 생성하고 `summary` 필드를 통해 [`task_progress`](#sdktaskprogressmessage) 이벤트에서 전달합니다. 포그라운드 및 백그라운드 서브에이전트에 적용됩니다 |474| `agentProgressSummaries` | `boolean` | `false` | `true`일 때 서브에이전트에 대한 한 줄 진행 요약을 생성하고 `summary` 필드를 통해 [`task_progress`](#sdktaskprogressmessage) 이벤트에서 전달합니다. 포그라운드 및 백그라운드 서브에이전트에 적용됩니다 |

475| `allowDangerouslySkipPermissions` | `boolean` | `false` | 권한 건너뛰기 활성화합니다. `permissionMode: 'bypassPermissions'`를 사용할 때 필수입니다 |475| `allowDangerouslySkipPermissions` | `boolean` | `false` | 권한 건너뛰기를 활성화합니다. `permissionMode: 'bypassPermissions'`를 사용할 때 필수입니다 |

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

477| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | 베타 기능 활성화 |477| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | 베타 기능 활성화 |

478| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 도구 사용을 위한 사용자 정의 권한 함수 |478| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 도구 사용을 위한 사용자 정의 권한 함수 |


481| `debug` | `boolean` | `false` | Claude Code 프로세스에 대한 디버그 모드 활성화 |481| `debug` | `boolean` | `false` | Claude Code 프로세스에 대한 디버그 모드 활성화 |

482| `debugFile` | `string` | `undefined` | 특정 파일 경로에 디버그 로그를 작성합니다. 암묵적으로 디버그 모드를 활성화합니다 |482| `debugFile` | `string` | `undefined` | 특정 파일 경로에 디버그 로그를 작성합니다. 암묵적으로 디버그 모드를 활성화합니다 |

483| `disallowedTools` | `string[]` | `[]` | 거부할 도구입니다. `Bash`와 같은 단순 이름은 Claude의 컨텍스트에서 도구를 제거합니다. `Bash(rm *)`와 같은 범위 지정 규칙은 도구를 사용 가능하게 유지하고 `bypassPermissions`를 포함한 모든 권한 모드에서 일치하는 호출을 거부합니다. [권한](/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |483| `disallowedTools` | `string[]` | `[]` | 거부할 도구입니다. `Bash`와 같은 단순 이름은 Claude의 컨텍스트에서 도구를 제거합니다. `Bash(rm *)`와 같은 범위 지정 규칙은 도구를 사용 가능하게 유지하고 `bypassPermissions`를 포함한 모든 권한 모드에서 일치하는 호출을 거부합니다. [권한](/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |

484| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | `'high'` | Claude가 응답에 투입하는 노력의 양을 제어합니다. 적응형 사고와 함께 작동하여 사고 깊이를 안내합니다 |484| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | 모델 기본값 | Claude가 응답에 투입하는 노력의 양을 제어합니다. 적응형 사고와 함께 작동하여 사고 깊이를 안내합니다. [노력 수준 조정](/ko/model-config#adjust-effort-level) 참조 |

485| `enableFileCheckpointing` | `boolean` | `false` | 되감기를 위한 파일 변경 추적을 활성화합니다. [파일 체크포인팅](/ko/agent-sdk/file-checkpointing) 참조 |485| `enableFileCheckpointing` | `boolean` | `false` | 되감기를 위한 파일 변경 추적을 활성화합니다. [파일 체크포인팅](/ko/agent-sdk/file-checkpointing) 참조 |

486| `env` | `Record<string, string \| undefined>` | `process.env` | 환경 변수입니다. 설정하면 이는 `process.env`와 병합하는 대신 서브프로세스 환경을 대체하므로 `PATH`와 같은 상속된 변수를 유지하려면 `{ ...process.env, YOUR_VAR: 'value' }`를 전달합니다. [느린 또는 정지된 API 응답 처리](#handle-slow-or-stalled-api-responses)에서 이 패턴의 예제를 참조하고, 기본 CLI가 읽는 변수는 [환경 변수](/ko/env-vars)를 참조하세요. User-Agent 헤더에서 앱을 식별하려면 `CLAUDE_AGENT_SDK_CLIENT_APP`을 설정합니다 |486| `env` | `Record<string, string \| undefined>` | `process.env` | 환경 변수입니다. 설정하면 이는 `process.env`와 병합하는 대신 서브프로세스 환경을 대체하므로 `PATH`와 같은 상속된 변수를 유지하려면 `{ ...process.env, YOUR_VAR: 'value' }`를 전달합니다. [느린 또는 정지된 API 응답 처리](#handle-slow-or-stalled-api-responses)에서 이 패턴의 예제를 참조하고, 기본 CLI가 읽는 변수는 [환경 변수](/ko/env-vars)를 참조하세요. User-Agent 헤더에서 앱을 식별하려면 `CLAUDE_AGENT_SDK_CLIENT_APP`을 설정합니다 |

487| `executable` | `'bun' \| 'deno' \| 'node'` | 자동 감지 | 사용할 JavaScript 런타임 |487| `executable` | `'bun' \| 'deno' \| 'node'` | 자동 감지 | 사용할 JavaScript 런타임 |


499| `maxThinkingTokens` | `number` | `undefined` | *더 이상 사용되지 않음:* 대신 `thinking`을 사용합니다. 사고 프로세스의 최대 토큰 |499| `maxThinkingTokens` | `number` | `undefined` | *더 이상 사용되지 않음:* 대신 `thinking`을 사용합니다. 사고 프로세스의 최대 토큰 |

500| `maxTurns` | `number` | `undefined` | 최대 에이전트 턴 (도구 사용 왕복) |500| `maxTurns` | `number` | `undefined` | 최대 에이전트 턴 (도구 사용 왕복) |

501| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 서버 구성 |501| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 서버 구성 |

502| `model` | `string` | CLI의 기본값 | 사용할 Claude 모델 |502| `model` | `string` | CLI의 기본값 | Claude 모델 별칭 또는 전체 모델 이름입니다. [허용되는 값 및 공급자별 ID](/ko/model-config#available-models) 참조 |

503| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | MCP 유도 요청을 처리하기 위한 콜백입니다. MCP 서버가 사용자 입력을 요청하고 훅이 먼저 처리하지 않을 때 호출됩니다. 제공되지 않으면 처리되지 않은 유도 요청이 자동으로 거부됩니다 |503| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | MCP 유도 요청을 처리하기 위한 콜백입니다. MCP 서버가 사용자 입력을 요청하고 훅이 먼저 처리하지 않을 때 호출됩니다. 제공되지 않으면 처리되지 않은 유도 요청이 자동으로 거부됩니다 |

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

505| `outputStyle` | `string` | `undefined` | `Options` 필드가 아닙니다. 대신 인라인 [`settings`](/ko/settings) 객체 또는 설정 파일에서 `outputStyle`을 설정합니다. [출력 스타일 활성화](/ko/agent-sdk/modifying-system-prompts#activate-an-output-style) 참조 |505| `outputStyle` | `string` | `undefined` | `Options` 필드가 아닙니다. 대신 인라인 [`settings`](/ko/settings) 객체 또는 설정 파일에서 `outputStyle`을 설정합니다. [출력 스타일 활성화](/ko/agent-sdk/modifying-system-prompts#activate-an-output-style) 참조 |


553* `API_TIMEOUT_MS`: Anthropic 클라이언트의 요청당 타임아웃 (밀리초 단위). 기본값 `600000`. 메인 루프 및 모든 서브에이전트에 적용됩니다.553* `API_TIMEOUT_MS`: Anthropic 클라이언트의 요청당 타임아웃 (밀리초 단위). 기본값 `600000`. 메인 루프 및 모든 서브에이전트에 적용됩니다.

554* `CLAUDE_CODE_MAX_RETRIES`: 최대 API 재시도 횟수. 기본값 `10`. 각 재시도는 자체 `API_TIMEOUT_MS` 윈도우를 가지므로 최악의 경우 벽시간은 대략 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 더하기 백오프입니다.554* `CLAUDE_CODE_MAX_RETRIES`: 최대 API 재시도 횟수. 기본값 `10`. 각 재시도는 자체 `API_TIMEOUT_MS` 윈도우를 가지므로 최악의 경우 벽시간은 대략 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 더하기 백오프입니다.

555* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: `run_in_background`으로 시작된 서브에이전트에 대한 정지 감시견입니다. 기본값 `600000`. 각 스트림 이벤트에서 재설정되며, 정지 시 서브에이전트를 중단하고 작업을 실패로 표시하며 부분 결과와 함께 오류를 부모에게 표시합니다. 동기 서브에이전트에는 적용되지 않습니다.555* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: `run_in_background`으로 시작된 서브에이전트에 대한 정지 감시견입니다. 기본값 `600000`. 각 스트림 이벤트에서 재설정되며, 정지 시 서브에이전트를 중단하고 작업을 실패로 표시하며 부분 결과와 함께 오류를 부모에게 표시합니다. 동기 서브에이전트에는 적용되지 않습니다.

556* `CLAUDE_ENABLE_STREAM_WATCHDOG=1` 및 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: 헤더가 도착했지만 응답 본문이 스트리밍을 중지할 때 요청을 중단합니다. 기본적으로 꺼져 있습니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`는 기본값 `300000`이고 해당 최소값으로 고정됩니다. 중단된 요청은 일반 재시도 경로를 거칩니다.556* `CLAUDE_ENABLE_STREAM_WATCHDOG=1` 및 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: 헤더가 도착했지만 응답 본문이 스트리밍을 중지할 때 요청을 중단합니다. `CLAUDE_ENABLE_STREAM_WATCHDOG`이 설정되지 않으면 기본값은 직접 Anthropic API에서는 서버 제어이고 다른 공급자에서는 꺼져 있습니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`는 기본값 `300000`이고 해당 최소값으로 고정됩니다. 중단된 요청은 일반 재시도 경로를 거칩니다.

557 557 

558<h3 id="query-object">558<h3 id="query-object">

559 `Query` 객체559 `Query` 객체


658}658}

659```659```

660 660 

661<h4 id="methods">661<h4 id="methods-1">

662 메서드662 메서드

663</h4>663</h4>

664 664 


717```717```

718 718 

719| 필드 | 필수 | 설명 |719| 필드 | 필수 | 설명 |

720| :------------------------------------ | :-- | :------------------------------------------------------------------------------------------------------------------------- |720| :------------------------------------ | :-- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |

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

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

723| `disallowedTools` | 아니오 | 이 에이전트에 대해 명시적으로 허용하지 않을 도구 이름의 배열 |723| `disallowedTools` | 아니오 | 이 에이전트에 대해 명시적으로 허용하지 않을 도구 이름의 배열입니다. MCP 서버 수준 패턴도 허용됩니다: `mcp__server` 또는 `mcp__server__*`는 해당 서버의 모든 도구를 제거하고, `mcp__*`는 모든 서버의 모든 MCP 도구를 제거합니다 |

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

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

726| `mcpServers` | 아니오 | 이 에이전트에 사용 가능한 MCP 서버 사양 |726| `mcpServers` | 아니오 | 이 에이전트에 사용 가능한 MCP 서버 사양 |

727| `skills` | 아니오 | 에이전트 컨텍스트에 미리 로드할 스킬 이름의 배열 |727| `skills` | 아니오 | 에이전트 컨텍스트에 미리 로드할 스킬 이름의 배열 |

728| `initialPrompt` | 아니오 | 이 에이전트가 메인 스레드 에이전트로 실행될 때 첫 번째 사용자 턴으로 자동 제출됨 |728| `initialPrompt` | 아니오 | 이 에이전트가 메인 스레드 에이전트로 실행될 때 첫 번째 사용자 턴으로 자동 제출됨 |


874type PermissionMode =874type PermissionMode =

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

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

877 | "bypassPermissions" // 모든 권한 확인 무시877 | "bypassPermissions" // 권한 확인 무시; 명시적 요청 규칙은 여전히 프롬프트

878 | "plan" // 계획 모드 - 읽기 전용 도구만878 | "plan" // 계획 모드 - 편집 없이 탐색

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

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

881```881```


1035type SdkPluginConfig = {1035type SdkPluginConfig = {

1036 type: "local";1036 type: "local";

1037 path: string;1037 path: string;

1038 skipMcpDiscovery?: boolean;

1038};1039};

1039```1040```

1040 1041 

1041| 필드 | 타입 | 설명 |1042| 필드 | 타입 | 설명 |

1042| :----- | :-------- | :--------------------------------- |1043| :----------------- | :-------- | :----------------------------------------------------------------------------------------------------------------------------------- |

1043| `type` | `'local'` | `'local'`이어야 합니다 (현재 로컬 플러그인만 지원됨) |1044| `type` | `'local'` | `'local'`이어야 합니다 (현재 로컬 플러그인만 지원됨) |

1044| `path` | `string` | 플러그인 디렉토리의 절대 또는 상대 경로 |1045| `path` | `string` | 플러그인 디렉토리의 절대 또는 상대 경로 |

1046| `skipMcpDiscovery` | `boolean` | `true`일 때 SDK는 이 플러그인에서 스킬, 훅, 에이전트 및 명령을 로드하지만 해당 `.mcp.json` 또는 매니페스트 `mcpServers`를 읽지 않습니다. 애플리케이션이 플러그인의 MCP 연결을 소유할 때 이를 설정합니다. |

1045 1047 

1046**예제:**1048**예제:**

1047 1049 


1086 | SDKTaskProgressMessage1088 | SDKTaskProgressMessage

1087 | SDKTaskUpdatedMessage1089 | SDKTaskUpdatedMessage

1088 | SDKSessionStateChangedMessage1090 | SDKSessionStateChangedMessage

1091 | SDKWorkerShuttingDownMessage

1089 | SDKCommandsChangedMessage1092 | SDKCommandsChangedMessage

1090 | SDKNotificationMessage1093 | SDKNotificationMessage

1091 | SDKFilesPersistedEvent1094 | SDKFilesPersistedEvent


1096 | SDKPermissionDeniedMessage1099 | SDKPermissionDeniedMessage

1097 | SDKPromptSuggestionMessage1100 | SDKPromptSuggestionMessage

1098 | SDKAPIRetryMessage1101 | SDKAPIRetryMessage

1099 | SDKMirrorErrorMessage;1102 | SDKMirrorErrorMessage

1103 | SDKInformationalMessage;

1100```1104```

1101 1105 

1102<h3 id="sdkassistantmessage">1106<h3 id="sdkassistantmessage">


1183 result: string;1187 result: string;

1184 stop_reason: string | null;1188 stop_reason: string | null;

1185 ttft_ms?: number;1189 ttft_ms?: number;

1190 ttft_stream_ms?: number;

1186 total_cost_usd: number;1191 total_cost_usd: number;

1187 usage: NonNullableUsage;1192 usage: NonNullableUsage;

1188 modelUsage: { [modelName: string]: ModelUsage };1193 modelUsage: { [modelName: string]: ModelUsage };


1221결과의 여러 필드는 `subtype` 이상의 진단 세부 정보를 전달합니다:1226결과의 여러 필드는 `subtype` 이상의 진단 세부 정보를 전달합니다:

1222 1227 

1223* `api_error_status`: 대화를 종료한 API 오류의 HTTP 상태 코드입니다. API 오류 없이 턴이 종료되었을 때는 없거나 `null`입니다.1228* `api_error_status`: 대화를 종료한 API 오류의 HTTP 상태 코드입니다. API 오류 없이 턴이 종료되었을 때는 없거나 `null`입니다.

1224* `ttft_ms`: 첫 번째 토큰까지의 시간(밀리초)입니다. 성공 경로에만 표시됩니다.1229* `ttft_ms`: 첫 번째 토큰까지의 시간(밀리초)입니다. 첫 번째 완전한 어시스턴트 메시지가 도착할 때 측정됩니다. 성공 경로에만 표시됩니다.

1230* `ttft_stream_ms`: 응답 스트림이 열릴 때 첫 번째 `message_start` 스트림 이벤트까지의 시간(밀리초)입니다. `ttft_ms`보다 낮습니다. 두 시간 사이의 간격은 첫 번째 메시지를 스트리밍하는 데 소요된 시간입니다. 성공 경로에만 표시됩니다.

1225* `terminal_reason`: 루프가 종료된 이유입니다. `"completed"`, `"max_turns"`, `"tool_deferred"`, `"aborted_streaming"`, `"aborted_tools"`, `"hook_stopped"`, `"stop_hook_prevented"`, `"blocking_limit"`, `"rapid_refill_breaker"`, `"prompt_too_long"`, `"image_error"` 또는 `"model_error"` 중 하나입니다.1231* `terminal_reason`: 루프가 종료된 이유입니다. `"completed"`, `"max_turns"`, `"tool_deferred"`, `"aborted_streaming"`, `"aborted_tools"`, `"hook_stopped"`, `"stop_hook_prevented"`, `"blocking_limit"`, `"rapid_refill_breaker"`, `"prompt_too_long"`, `"image_error"` 또는 `"model_error"` 중 하나입니다.

1226* `fast_mode_state`: `"on"`, `"off"` 또는 `"cooldown"` 중 하나입니다.1232* `fast_mode_state`: `"on"`, `"off"` 또는 `"cooldown"` 중 하나입니다.

1227 1233 


1273 parent_tool_use_id: string | null;1279 parent_tool_use_id: string | null;

1274 uuid: UUID;1280 uuid: UUID;

1275 session_id: string;1281 session_id: string;

1282 ttft_ms?: number; // 첫 번째 토큰까지의 시간(ms), message_start 이벤트에만 표시됨

1276};1283};

1277```1284```

1278 1285 


1295};1302};

1296```1303```

1297 1304 

1305<h3 id="sdkinformationalmessage">

1306 `SDKInformationalMessage`

1307</h3>

1308 

1309루프에서 내보낸 일반 텍스트 배너입니다. 비오류 상태 라인, `UserPromptSubmit` 훅의 블록 이유와 같은 훅 피드백, 및 명령 출력을 전달합니다. `content`를 주어진 `level`에서 일반 텍스트로 렌더링합니다.

1310 

1311```typescript theme={null}

1312type SDKInformationalMessage = {

1313 type: "system";

1314 subtype: "informational";

1315 content: string;

1316 level: "info" | "notice" | "suggestion" | "warning";

1317 tool_use_id?: string;

1318 prevent_continuation?: boolean;

1319 uuid: UUID;

1320 session_id: string;

1321};

1322```

1323 

1324<h3 id="sdkworkershuttingdownmessage">

1325 `SDKWorkerShuttingDownMessage`

1326</h3>

1327 

1328원격 클라이언트가 하트비트 타임아웃을 기다리는 대신 워커가 사라진 이유를 표시할 수 있도록 정상적인 워커 종료 시 내보내집니다. `reason`은 호스트 CLI에서 설정한 짧은 snake\_case 문자열입니다(예: `"host_exit"` 또는 `"remote_control_disabled"`). 라이브 스트리밍할 때만 이에 대해 조치합니다. 재개된 세션은 이 메시지의 과거 인스턴스를 재생하므로 그 경우 무시합니다.

1329 

1330```typescript theme={null}

1331type SDKWorkerShuttingDownMessage = {

1332 type: "system";

1333 subtype: "worker_shutting_down";

1334 reason: string;

1335 uuid: UUID;

1336 session_id: string;

1337};

1338```

1339 

1298<h3 id="sdkplugininstallmessage">1340<h3 id="sdkplugininstallmessage">

1299 `SDKPluginInstallMessage`1341 `SDKPluginInstallMessage`

1300</h3>1342</h3>


1369type SDKMessageOrigin =1411type SDKMessageOrigin =

1370 | { kind: "human" }1412 | { kind: "human" }

1371 | { kind: "channel"; server: string }1413 | { kind: "channel"; server: string }

1372 | { kind: "peer"; from: string; name?: string }1414 | { kind: "peer"; from: string; name?: string; senderTaskId?: string }

1373 | { kind: "task-notification" }1415 | { kind: "task-notification" }

1374 | { kind: "coordinator" };1416 | { kind: "coordinator" }

1417 | { kind: "auto-continuation" };

1375```1418```

1376 1419 

1377| `kind` | 의미 |1420| `kind` | 의미 |

1378| ------------------- | ------------------------------------------------------------------------------------------------- |1421| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1379| `human` | 최종 사용자의 직접 입력입니다. 사용자 메시지에서 없는 `origin`도 인간 입력을 의미합니다. |1422| `human` | 최종 사용자의 직접 입력입니다. 사용자 메시지에서 없는 `origin`도 인간 입력을 의미합니다. |

1380| `channel` | [채널](/ko/channels)에 도착한 메시지입니다. `server`는 소스 MCP 서버 이름입니다. |1423| `channel` | [채널](/ko/channels)에 도착한 메시지입니다. `server`는 소스 MCP 서버 이름입니다. |

1381| `peer` | `SendMessage`를 통한 다른 에이전트 세션의 메시지입니다. `from`은 발신자 주소이고 `name`은 사용 가능할 때 발신자의 표시 이름입니다. |1424| `peer` | 다른 에이전트 세션의 메시지를 위해 예약되어 있습니다. `from`은 발신자 주소이고 `name`은 사용 가능할 때 발신자의 표시 이름입니다. `senderTaskId`는 메시지를 보낸 프로세스 내 백그라운드 서브에이전트의 작업 ID입니다. 교차 세션 피어의 경우 없습니다. Agent SDK는 이 출처를 내보내지 않습니다. 알 수 없는 출처로 취급하십시오. |

1382| `task-notification` | 백그라운드 작업이 완료된 후 주입된 합성 턴입니다. [`SDKTaskNotificationMessage`](#sdktasknotificationmessage)를 참조하십시오. |1425| `task-notification` | 백그라운드 작업이 완료된 후 주입된 합성 턴입니다. [`SDKTaskNotificationMessage`](#sdktasknotificationmessage)를 참조하십시오. |

1383| `coordinator` | [에이전트 팀](/ko/agent-teams)의 팀 코디네이터로부터의 메시지입니다. |1426| `coordinator` | [에이전트 팀](/ko/agent-teams)의 팀 코디네이터로부터의 메시지입니다. |

1427| `auto-continuation` | 새로운 사용자 입력 없이 세션이 계속될 때 주입된 합성 턴입니다. 예를 들어 후속 프롬프트를 트리거하는 명령 결과입니다. |

1384 1428 

1385<h2 id="hook-types">1429<h2 id="hook-types">

1386 훅 타입1430 훅 타입


1712type TeammateIdleHookInput = BaseHookInput & {1756type TeammateIdleHookInput = BaseHookInput & {

1713 hook_event_name: "TeammateIdle";1757 hook_event_name: "TeammateIdle";

1714 teammate_name: string;1758 teammate_name: string;

1759 /** @deprecated v2.1.178 이후로 사용되지 않음. 세션에서 파생된 팀 이름을 전달합니다. 제거될 예정입니다. */

1715 team_name: string;1760 team_name: string;

1716};1761};

1717```1762```


1727 task_subject: string;1772 task_subject: string;

1728 task_description?: string;1773 task_description?: string;

1729 teammate_name?: string;1774 teammate_name?: string;

1775 /** @deprecated v2.1.178 이후로 사용되지 않음. 세션에서 파생된 팀 이름을 전달합니다. 제거될 예정입니다. */

1730 team_name?: string;1776 team_name?: string;

1731};1777};

1732```1778```


1934 description: string;1980 description: string;

1935 prompt: string;1981 prompt: string;

1936 subagent_type: string;1982 subagent_type: string;

1937 model?: "sonnet" | "opus" | "haiku";1983 model?: "sonnet" | "opus" | "haiku" | "fable";

1938 resume?: string;1984 resume?: string;

1939 run_in_background?: boolean;1985 run_in_background?: boolean;

1940 max_turns?: number;1986 max_turns?: number;

1941 name?: string;1987 name?: string;

1942 team_name?: string;

1943 mode?: "acceptEdits" | "bypassPermissions" | "default" | "dontAsk" | "plan";1988 mode?: "acceptEdits" | "bypassPermissions" | "default" | "dontAsk" | "plan";

1944 isolation?: "worktree";1989 isolation?: "worktree";

1945};1990};


2385 | WorkflowOutput;2430 | WorkflowOutput;

2386```2431```

2387 2432 

2388<h3 id="agent">2433<h3 id="agent-1">

2389 Agent2434 Agent

2390</h3>2435</h3>

2391 2436 


2397 status: "completed";2442 status: "completed";

2398 agentId: string;2443 agentId: string;

2399 content: Array<{ type: "text"; text: string }>;2444 content: Array<{ type: "text"; text: string }>;

2445 resolvedModel?: string;

2400 totalToolUseCount: number;2446 totalToolUseCount: number;

2401 totalDurationMs: number;2447 totalDurationMs: number;

2402 totalTokens: number;2448 totalTokens: number;


2421 status: "async_launched";2467 status: "async_launched";

2422 agentId: string;2468 agentId: string;

2423 description: string;2469 description: string;

2470 resolvedModel?: string;

2424 prompt: string;2471 prompt: string;

2425 outputFile: string;2472 outputFile: string;

2426 canReadOutputFile?: boolean;2473 canReadOutputFile?: boolean;


2434 2481 

2435서브에이전트의 결과를 반환합니다. `status` 필드에서 구분됩니다: 완료된 작업의 경우 `"completed"`, 백그라운드 작업의 경우 `"async_launched"`, 대화형 서브에이전트의 경우 `"sub_agent_entered"`.2482서브에이전트의 결과를 반환합니다. `status` 필드에서 구분됩니다: 완료된 작업의 경우 `"completed"`, 백그라운드 작업의 경우 `"async_launched"`, 대화형 서브에이전트의 경우 `"sub_agent_entered"`.

2436 2483 

2437<h3 id="askuserquestion">2484`resolvedModel` 필드는 `completed` 및 `async_launched` 변형에서 서브에이전트가 실제로 실행된 모델의 이름을 지정하며, 이는 [`availableModels`](/ko/model-config#restrict-model-selection) 또는 다른 재정의가 적용될 때 요청된 `model` 입력과 다를 수 있습니다. {/* min-version: 2.1.174 */}이 필드는 Claude Code v2.1.174 이상이 필요합니다.

2485 

2486<h3 id="askuserquestion-1">

2438 AskUserQuestion2487 AskUserQuestion

2439</h3>2488</h3>

2440 2489 


2455 2504 

2456질문과 사용자의 답변을 반환합니다. `response`는 사용자가 구조화된 질문에 답하는 대신 자유 형식 답변을 입력했을 때 설정됩니다. 존재할 때, Claude는 질문별 답변 목록 대신 "사용자가 응답했습니다: …"를 받습니다.2505질문과 사용자의 답변을 반환합니다. `response`는 사용자가 구조화된 질문에 답하는 대신 자유 형식 답변을 입력했을 때 설정됩니다. 존재할 때, Claude는 질문별 답변 목록 대신 "사용자가 응답했습니다: …"를 받습니다.

2457 2506 

2458<h3 id="bash">2507<h3 id="bash-1">

2459 Bash2508 Bash

2460</h3>2509</h3>

2461 2510 


2480 2529 

2481stdout/stderr가 분할된 명령 출력을 반환합니다. 백그라운드 명령은 `backgroundTaskId`를 포함합니다.2530stdout/stderr가 분할된 명령 출력을 반환합니다. 백그라운드 명령은 `backgroundTaskId`를 포함합니다.

2482 2531 

2483<h3 id="monitor">2532<h3 id="monitor-1">

2484 Monitor2533 Monitor

2485</h3>2534</h3>

2486 2535 


2496 2545 

2497실행 중인 모니터의 백그라운드 작업 ID를 반환합니다. 이 ID를 `TaskStop`과 함께 사용하여 감시를 조기에 취소합니다.2546실행 중인 모니터의 백그라운드 작업 ID를 반환합니다. 이 ID를 `TaskStop`과 함께 사용하여 감시를 조기에 취소합니다.

2498 2547 

2499<h3 id="edit">2548<h3 id="edit-1">

2500 Edit2549 Edit

2501</h3>2550</h3>

2502 2551 


2530 2579 

2531편집 작업의 구조화된 diff를 반환합니다.2580편집 작업의 구조화된 diff를 반환합니다.

2532 2581 

2533<h3 id="read">2582<h3 id="read-1">

2534 Read2583 Read

2535</h3>2584</h3>

2536 2585 


2590 2639 

2591파일 타입에 적합한 형식의 파일 콘텐츠를 반환합니다. `type` 필드에서 구분됩니다.2640파일 타입에 적합한 형식의 파일 콘텐츠를 반환합니다. `type` 필드에서 구분됩니다.

2592 2641 

2593<h3 id="write">2642<h3 id="write-1">

2594 Write2643 Write

2595</h3>2644</h3>

2596 2645 


2622 2671 

2623구조화된 diff 정보를 포함한 쓰기 결과를 반환합니다.2672구조화된 diff 정보를 포함한 쓰기 결과를 반환합니다.

2624 2673 

2625<h3 id="glob">2674<h3 id="glob-1">

2626 Glob2675 Glob

2627</h3>2676</h3>

2628 2677 


2639 2688 

2640glob 패턴과 일치하는 파일 경로를 수정 시간별로 정렬하여 반환합니다.2689glob 패턴과 일치하는 파일 경로를 수정 시간별로 정렬하여 반환합니다.

2641 2690 

2642<h3 id="grep">2691<h3 id="grep-1">

2643 Grep2692 Grep

2644</h3>2693</h3>

2645 2694 


2660 2709 

2661검색 결과를 반환합니다. 형태는 `mode`에 따라 다릅니다: 파일 목록, 일치 항목이 있는 콘텐츠 또는 일치 항목 수.2710검색 결과를 반환합니다. 형태는 `mode`에 따라 다릅니다: 파일 목록, 일치 항목이 있는 콘텐츠 또는 일치 항목 수.

2662 2711 

2663<h3 id="taskstop">2712<h3 id="taskstop-1">

2664 TaskStop2713 TaskStop

2665</h3>2714</h3>

2666 2715 


2677 2726 

2678백그라운드 작업 중지 후 확인을 반환합니다.2727백그라운드 작업 중지 후 확인을 반환합니다.

2679 2728 

2680<h3 id="notebookedit">2729<h3 id="notebookedit-1">

2681 NotebookEdit2730 NotebookEdit

2682</h3>2731</h3>

2683 2732 


2699 2748 

2700원본 및 업데이트된 파일 콘텐츠를 포함한 노트북 편집 결과를 반환합니다.2749원본 및 업데이트된 파일 콘텐츠를 포함한 노트북 편집 결과를 반환합니다.

2701 2750 

2702<h3 id="webfetch">2751<h3 id="webfetch-1">

2703 WebFetch2752 WebFetch

2704</h3>2753</h3>

2705 2754 


2718 2767 

2719HTTP 상태 및 메타데이터를 포함한 가져온 콘텐츠를 반환합니다.2768HTTP 상태 및 메타데이터를 포함한 가져온 콘텐츠를 반환합니다.

2720 2769 

2721<h3 id="websearch">2770<h3 id="websearch-1">

2722 WebSearch2771 WebSearch

2723</h3>2772</h3>

2724 2773 


2740 2789 

2741웹에서 검색 결과를 반환합니다.2790웹에서 검색 결과를 반환합니다.

2742 2791 

2743<h3 id="workflow">2792<h3 id="workflow-1">

2744 Workflow2793 Workflow

2745</h3>2794</h3>

2746 2795 


2770| `scriptPath` | `string` | 이 실행을 위해 유지된 워크플로우 스크립트의 경로입니다. 스크립트를 다시 보내지 않고 다시 실행하려면 편집하고 `scriptPath`로 다시 전달하십시오 |2819| `scriptPath` | `string` | 이 실행을 위해 유지된 워크플로우 스크립트의 경로입니다. 스크립트를 다시 보내지 않고 다시 실행하려면 편집하고 `scriptPath`로 다시 전달하십시오 |

2771| `error` | `string` | 스크립트가 구문 검사에 실패할 때 설정됩니다. 존재할 때, `async_launched` 상태에도 불구하고 실행이 시작되지 않았습니다 |2820| `error` | `string` | 스크립트가 구문 검사에 실패할 때 설정됩니다. 존재할 때, `async_launched` 상태에도 불구하고 실행이 시작되지 않았습니다 |

2772 2821 

2773<h3 id="todowrite">2822<h3 id="todowrite-1">

2774 TodoWrite2823 TodoWrite

2775</h3>2824</h3>

2776 2825 


2797 TypeScript Agent SDK 0.3.142부터 `TodoWrite`는 기본적으로 비활성화됩니다. 대신 `TaskCreate`, `TaskGet`, `TaskUpdate`, `TaskList`를 사용하십시오. 모니터링 코드를 업데이트하려면 [작업 도구로 마이그레이션](/ko/agent-sdk/todo-tracking#migrate-to-task-tools)을 참조하거나, `CLAUDE_CODE_ENABLE_TASKS=0`을 설정하여 `TodoWrite`로 되돌립니다.2846 TypeScript Agent SDK 0.3.142부터 `TodoWrite`는 기본적으로 비활성화됩니다. 대신 `TaskCreate`, `TaskGet`, `TaskUpdate`, `TaskList`를 사용하십시오. 모니터링 코드를 업데이트하려면 [작업 도구로 마이그레이션](/ko/agent-sdk/todo-tracking#migrate-to-task-tools)을 참조하거나, `CLAUDE_CODE_ENABLE_TASKS=0`을 설정하여 `TodoWrite`로 되돌립니다.

2798</Note>2847</Note>

2799 2848 

2800<h3 id="taskcreate">2849<h3 id="taskcreate-1">

2801 TaskCreate2850 TaskCreate

2802</h3>2851</h3>

2803 2852 


2814 2863 

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

2816 2865 

2817<h3 id="taskupdate">2866<h3 id="taskupdate-1">

2818 TaskUpdate2867 TaskUpdate

2819</h3>2868</h3>

2820 2869 


2835 2884 

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

2837 2886 

2838<h3 id="taskget">2887<h3 id="taskget-1">

2839 TaskGet2888 TaskGet

2840</h3>2889</h3>

2841 2890 


2856 2905 

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

2858 2907 

2859<h3 id="tasklist">2908<h3 id="tasklist-1">

2860 TaskList2909 TaskList

2861</h3>2910</h3>

2862 2911 


2876 2925 

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

2878 2927 

2879<h3 id="exitplanmode">2928<h3 id="exitplanmode-1">

2880 ExitPlanMode2929 ExitPlanMode

2881</h3>2930</h3>

2882 2931 


2895 2944 

2896계획 모드 종료 후 계획 상태를 반환합니다.2945계획 모드 종료 후 계획 상태를 반환합니다.

2897 2946 

2898<h3 id="listmcpresources">2947<h3 id="listmcpresources-1">

2899 ListMcpResources2948 ListMcpResources

2900</h3>2949</h3>

2901 2950 


2913 2962 

2914사용 가능한 MCP 리소스의 배열을 반환합니다.2963사용 가능한 MCP 리소스의 배열을 반환합니다.

2915 2964 

2916<h3 id="readmcpresource">2965<h3 id="readmcpresource-1">

2917 ReadMcpResource2966 ReadMcpResource

2918</h3>2967</h3>

2919 2968 


2931 2980 

2932요청된 MCP 리소스의 콘텐츠를 반환합니다.2981요청된 MCP 리소스의 콘텐츠를 반환합니다.

2933 2982 

2934<h3 id="enterworktree">2983<h3 id="enterworktree-1">

2935 EnterWorktree2984 EnterWorktree

2936</h3>2985</h3>

2937 2986 


2955 `PermissionUpdate`3004 `PermissionUpdate`

2956</h3>3005</h3>

2957 3006 

2958권한 업데이트 작업입니다.3007권한을 업데이트하기 위한 작업입니다.

2959 3008 

2960```typescript theme={null}3009```typescript theme={null}

2961type PermissionUpdate =3010type PermissionUpdate =


3010type PermissionUpdateDestination =3059type PermissionUpdateDestination =

3011 | "userSettings" // 전역 사용자 설정3060 | "userSettings" // 전역 사용자 설정

3012 | "projectSettings" // 디렉토리별 프로젝트 설정3061 | "projectSettings" // 디렉토리별 프로젝트 설정

3013 | "localSettings" // Gitignored 로컬 설정3062 | "localSettings" // 로컬 프로젝트 설정

3014 | "session" // 현재 세션만3063 | "session" // 현재 세션만

3015 | "cliArg"; // CLI 인수3064 | "cliArg"; // CLI 인수

3016```3065```


3049```3098```

3050 3099 

3051<Warning>3100<Warning>

3052 `context-1m-2025-08-07` 베타는 2026년 4월 30일부터 폐기되었습니다. Claude Sonnet 4.5 또는 Sonnet 4와 함께 이 값을 전달하면 효과가 없으며, 표준 200k 토큰 컨텍스트 윈도우를 초과하는 요청은 오류를 반환합니다. 1M 토큰 컨텍스트 윈도우를 사용하려면 [Claude Sonnet 4.6, Claude Opus 4.6 또는 Claude Opus 4.7](https://platform.claude.com/docs/ko/about-claude/models/overview)로 마이그레이션하세요. 이들은 베타 헤더 없이 표준 가격으로 1M 컨텍스트를 포함합니다.3101 `context-1m-2025-08-07` 베타는 2026년 4월 30일부터 폐기되었습니다. Claude Sonnet 4.5 또는 Sonnet 4와 함께 이 값을 전달하면 효과가 없으며, 표준 200k 토큰 컨텍스트 윈도우를 초과하는 요청은 오류를 반환합니다. 1M 토큰 컨텍스트 윈도우를 사용하려면 [Claude Sonnet 4.6, Claude Opus 4.6, Claude Opus 4.7 또는 Claude Opus 4.8](https://platform.claude.com/docs/ko/about-claude/models/overview)로 마이그레이션하세요. 이들은 베타 헤더 없이 표준 가격으로 1M 컨텍스트를 포함합니다.

3053</Warning>3102</Warning>

3054 3103 

3055<h3 id="slashcommand">3104<h3 id="slashcommand">


3241```typescript theme={null}3290```typescript theme={null}

3242type CallToolResult = {3291type CallToolResult = {

3243 content: Array<{3292 content: Array<{

3244 type: "text" | "image" | "resource";3293 type: "text" | "image" | "audio" | "resource" | "resource_link";

3245 // 추가 필드는 타입에 따라 다릅니다3294 // 추가 필드는 타입에 따라 다릅니다

3246 }>;3295 }>;

3247 structuredContent?: Record<string, unknown>;3296 structuredContent?: Record<string, unknown>;

Details

16 16 

17이 가이드는 각 유형의 요청을 감지하고 적절하게 응답하는 방법을 보여줍니다.17이 가이드는 각 유형의 요청을 감지하고 적절하게 응답하는 방법을 보여줍니다.

18 18 

19## Claude가 입력이 필요한 시점 감지19<h2 id="detect-when-claude-needs-input">

20 Claude가 입력이 필요한 시점 감지

21</h2>

20 22 

21쿼리 옵션에 `canUseTool` 콜백을 전달합니다. 콜백은 Claude가 사용자 입력이 필요할 때마다 실행되며, 도구 이름과 입력을 인수로 받습니다.23쿼리 옵션에 `canUseTool` 콜백을 전달합니다. 콜백은 Claude가 사용자 입력이 필요할 때마다 실행되며, 도구 이름과 입력을 인수로 받습니다.

22 24 


43콜백은 두 가지 경우에 실행됩니다.45콜백은 두 가지 경우에 실행됩니다.

44 46 

451. **도구가 승인 필요**: Claude가 [권한 규칙](/ko/agent-sdk/permissions) 또는 모드에 의해 자동 승인되지 않은 도구를 사용하려고 합니다. 도구에 대해 `tool_name`을 확인합니다(예: `"Bash"`, `"Write"`).471. **도구가 승인 필요**: Claude가 [권한 규칙](/ko/agent-sdk/permissions) 또는 모드에 의해 자동 승인되지 않은 도구를 사용하려고 합니다. 도구에 대해 `tool_name`을 확인합니다(예: `"Bash"`, `"Write"`).

462. **Claude가 질문함**: Claude가 `AskUserQuestion` 도구를 호출합니다. `tool_name == "AskUserQuestion"`을 확인하여 다르게 처리합니다. `tools` 배열을 지정하는 경우 이것이 작동하려면 `AskUserQuestion`을 포함하십시오. 자세한 내용은 [명확화 질문 처리](#명확화-질문-처리)를 참조하십시오.482. **Claude가 질문함**: Claude가 `AskUserQuestion` 도구를 호출합니다. `tool_name == "AskUserQuestion"`을 확인하여 다르게 처리합니다. `tools` 배열을 지정하는 경우 이것이 작동하려면 `AskUserQuestion`을 포함하십시오. 자세한 내용은 [명확화 질문 처리](#handle-clarifying-questions)를 참조하십시오.

47 49 

48<Note>50<Note>

49 사용자에게 프롬프트하지 않고 도구를 자동으로 허용하거나 거부하려면 [훅](/ko/agent-sdk/hooks)을 대신 사용하십시오. 훅은 `canUseTool` 전에 실행되며 자신의 로직에 따라 요청을 허용, 거부 또는 수정할 수 있습니다. [`PermissionRequest` 훅](/ko/agent-sdk/hooks#available-hooks)을 사용하여 Claude가 승인을 기다리고 있을 때 외부 알림(Slack, 이메일, 푸시)을 보낼 수도 있습니다.51 사용자에게 프롬프트하지 않고 도구를 자동으로 허용하거나 거부하려면 [훅](/ko/agent-sdk/hooks)을 대신 사용하십시오. 훅은 `canUseTool` 전에 실행되며 자신의 로직에 따라 요청을 허용, 거부 또는 수정할 수 있습니다. [`PermissionRequest` 훅](/ko/agent-sdk/hooks#available-hooks)을 사용하여 Claude가 승인을 기다리고 있을 때 외부 알림(Slack, 이메일, 푸시)을 보낼 수도 있습니다.

50</Note>52</Note>

51 53 

52## 도구 승인 요청 처리54<h2 id="handle-tool-approval-requests">

55 도구 승인 요청 처리

56</h2>

53 57 

54쿼리 옵션에 `canUseTool` 콜백을 전달하면, Claude가 자동 승인되지 않은 도구를 사용하려고 할 때 실행됩니다. 콜백은 세 가지 인수를 받습니다.58쿼리 옵션에 `canUseTool` 콜백을 전달하면, Claude가 자동 승인되지 않은 도구를 사용하려고 할 때 실행됩니다. 콜백은 세 가지 인수를 받습니다.

55 59 


195 Python에서 `can_use_tool`은 [스트리밍 모드](/ko/agent-sdk/streaming-vs-single-mode)와 스트림을 열어 두기 위해 `{"continue_": True}`를 반환하는 `PreToolUse` 훅이 필요합니다. 이 훅이 없으면 권한 콜백이 호출되기 전에 스트림이 닫힙니다.199 Python에서 `can_use_tool`은 [스트리밍 모드](/ko/agent-sdk/streaming-vs-single-mode)와 스트림을 열어 두기 위해 `{"continue_": True}`를 반환하는 `PreToolUse` 훅이 필요합니다. 이 훅이 없으면 권한 콜백이 호출되기 전에 스트림이 닫힙니다.

196</Note>200</Note>

197 201 

198이 예제는 `y` 이외의 모든 입력이 거부로 처리되는 y/n 흐름을 사용합니다. 실제로는 사용자가 요청을 수정하거나, 피드백을 제공하거나, Claude를 완전히 리디렉션할 수 있는 더 풍부한 UI를 구축할 수 있습니다. 응답할 수 있는 모든 방법은 [도구 요청에 응답](#도구-요청에-응답)을 참조하십시오.202이 예제는 `y` 이외의 모든 입력이 거부로 처리되는 y/n 흐름을 사용합니다. 실제로는 사용자가 요청을 수정하거나, 피드백을 제공하거나, Claude를 완전히 리디렉션할 수 있는 더 풍부한 UI를 구축할 수 있습니다. 응답할 수 있는 모든 방법은 [도구 요청에 응답](#respond-to-tool-requests)을 참조하십시오.

199 203 

200### 도구 요청에 응답204<h3 id="respond-to-tool-requests">

205 도구 요청에 응답

206</h3>

201 207 

202콜백은 두 가지 응답 유형 중 하나를 반환합니다.208콜백은 두 가지 응답 유형 중 하나를 반환합니다.

203 209 


407 </Tab>413 </Tab>

408</Tabs>414</Tabs>

409 415 

410## 명확화 질문 처리416<h2 id="handle-clarifying-questions">

417 명확화 질문 처리

418</h2>

411 419 

412Claude가 여러 유효한 접근 방식이 있는 작업에 대해 더 많은 방향이 필요할 때 `AskUserQuestion` 도구를 호출합니다. 이는 `toolName`이 `AskUserQuestion`으로 설정된 `canUseTool` 콜백을 트리거합니다. 입력에는 Claude의 질문이 객관식 옵션으로 포함되어 있으며, 이를 사용자에게 표시하고 선택 사항을 반환합니다.420Claude가 여러 유효한 접근 방식이 있는 작업에 대해 더 많은 방향이 필요할 때 `AskUserQuestion` 도구를 호출합니다. 이는 `toolName`이 `AskUserQuestion`으로 설정된 `canUseTool` 콜백을 트리거합니다. 입력에는 Claude의 질문이 객관식 옵션으로 포함되어 있으며, 이를 사용자에게 표시하고 선택 사항을 반환합니다.

413 421 


505 }513 }

506 ```514 ```

507 515 

508 전체 필드 설명은 [질문 형식](#질문-형식)을 참조하십시오.516 전체 필드 설명은 [질문 형식](#question-format)을 참조하십시오.

509 </Step>517 </Step>

510 518 

511 <Step title="사용자로부터 답변 수집">519 <Step title="사용자로부터 답변 수집">


520 | `question` 필드(예: `"How should I format the output?"`) | 키 |528 | `question` 필드(예: `"How should I format the output?"`) | 키 |

521 | 선택된 옵션의 `label` 필드(예: `"Summary"`) | 값 |529 | 선택된 옵션의 `label` 필드(예: `"Summary"`) | 값 |

522 530 

523 다중 선택 질문의 경우 레이블 배열을 전달하거나 `", "`로 조인합니다. [자유 텍스트 입력을 지원](#자유-텍스트-입력-지원)하는 경우 사용자의 사용자 정의 텍스트를 값으로 사용합니다.531 다중 선택 질문의 경우 레이블 배열을 전달하거나 `", "`로 조인합니다. [자유 텍스트 입력을 지원](#support-free-text-input)하는 경우 사용자의 사용자 정의 텍스트를 값으로 사용합니다.

524 532 

525 <CodeGroup>533 <CodeGroup>

526 ```python Python theme={null}534 ```python Python theme={null}


551 </Step>559 </Step>

552</Steps>560</Steps>

553 561 

554### 질문 형식562<h3 id="question-format">

563 질문 형식

564</h3>

555 565 

556입력에는 `questions` 배열의 Claude 생성 질문이 포함됩니다. 각 질문에는 다음 필드가 있습니다.566입력에는 `questions` 배열의 Claude 생성 질문이 포함됩니다. 각 질문에는 다음 필드가 있습니다.

557 567 

558| 필드 | 설명 |568| 필드 | 설명 |

559| ------------- | -------------------------------------------------------------------------------------------------------------------- |569| ------------- | ------------------------------------------------------------------------------------------------------------------- |

560| `question` | 표시할 전체 질문 텍스트 |570| `question` | 표시할 전체 질문 텍스트 |

561| `header` | 질문의 짧은 레이블(최대 12자) |571| `header` | 질문의 짧은 레이블(최대 12자) |

562| `options` | 각각 `label` 및 `description`이 있는 2-4개 선택 사항의 배열입니다. TypeScript: 선택적으로 `preview`([아래](#option-previews-type-script) 참조) |572| `options` | 각각 `label` 및 `description`이 있는 2-4개 선택 사항의 배열입니다. TypeScript: 선택적으로 `preview`([아래](#option-previews-typescript) 참조) |

563| `multiSelect` | `true`인 경우 사용자가 여러 옵션을 선택할 수 있습니다. |573| `multiSelect` | `true`인 경우 사용자가 여러 옵션을 선택할 수 있습니다. |

564 574 

565콜백이 받는 구조:575콜백이 받는 구조:


580}590}

581```591```

582 592 

583#### 옵션 미리보기(TypeScript)593<h4 id="option-previews-typescript">

594 옵션 미리보기(TypeScript)

595</h4>

584 596 

585`toolConfig.askUserQuestion.previewFormat`은 각 옵션에 `preview` 필드를 추가하므로 앱이 레이블 옆에 시각적 목업을 표시할 수 있습니다. 이 설정이 없으면 Claude는 미리보기를 생성하지 않으며 필드가 없습니다.597`toolConfig.askUserQuestion.previewFormat`은 각 옵션에 `preview` 필드를 추가하므로 앱이 레이블 옆에 시각적 목업을 표시할 수 있습니다. 이 설정이 없으면 Claude는 미리보기를 생성하지 않으며 필드가 없습니다.

586 598 


621}633}

622```634```

623 635 

624### 응답 형식636<h3 id="response-format">

637 응답 형식

638</h3>

625 639 

626각 질문의 `question` 필드를 선택된 옵션의 `label`에 매핑하는 `answers` 객체를 반환합니다.640각 질문의 `question` 필드를 선택된 옵션의 `label`에 매핑하는 `answers` 객체를 반환합니다.

627 641 


631| `answers` | 키가 질문 텍스트이고 값이 선택된 레이블인 객체입니다. |645| `answers` | 키가 질문 텍스트이고 값이 선택된 레이블인 객체입니다. |

632| `response` | 선택적 자유형 회신으로 사용자가 구조화된 질문에 답하는 대신 입력한 내용입니다. |646| `response` | 선택적 자유형 회신으로 사용자가 구조화된 질문에 답하는 대신 입력한 내용입니다. |

633 647 

634다중 선택 질문의 경우 레이블 배열을 전달하거나 `", "`로 조인합니다. "Other" 옵션과 같은 질문별 자유 텍스트의 경우 사용자의 텍스트를 [자유 텍스트 입력 지원](#자유-텍스트-입력-지원)에 표시된 대로 `answers[question]`에 입력합니다. `response`는 사용자가 질문 카드를 닫고 특정 질문에 대한 답변이 아닌 일반적인 회신을 입력할 수 있는 UI가 있을 때만 설정합니다. `response`가 설정되면 Claude는 질문별 답변 목록 대신 "사용자가 응답했습니다: …"를 받습니다.648다중 선택 질문의 경우 레이블 배열을 전달하거나 `", "`로 조인합니다. "Other" 옵션과 같은 질문별 자유 텍스트의 경우 사용자의 텍스트를 [자유 텍스트 입력 지원](#support-free-text-input)에 표시된 대로 `answers[question]`에 입력합니다. `response`는 사용자가 질문 카드를 닫고 특정 질문에 대한 답변이 아닌 일반적인 회신을 입력할 수 있는 UI가 있을 때만 설정합니다. `response`가 설정되면 Claude는 질문별 답변 목록 대신 "사용자가 응답했습니다: …"를 받습니다.

635 649 

636```json theme={null}650```json theme={null}

637{651{


645}659}

646```660```

647 661 

648#### 자유 텍스트 입력 지원662<h4 id="support-free-text-input">

663 자유 텍스트 입력 지원

664</h4>

649 665 

650Claude의 사전 정의된 옵션이 항상 사용자가 원하는 것을 다루지는 않습니다. 사용자가 자신의 답변을 입력하도록 허용하려면:666Claude의 사전 정의된 옵션이 항상 사용자가 원하는 것을 다루지는 않습니다. 사용자가 자신의 답변을 입력하도록 허용하려면:

651 667 

652* Claude의 옵션 후에 추가 "Other" 선택을 표시하여 텍스트 입력을 허용합니다.668* Claude의 옵션 후에 추가 "Other" 선택을 표시하여 텍스트 입력을 허용합니다.

653* 사용자의 사용자 정의 텍스트를 답변 값으로 사용합니다("Other"라는 단어가 아님).669* 사용자의 사용자 정의 텍스트를 답변 값으로 사용합니다("Other"라는 단어가 아님).

654 670 

655전체 구현은 아래의 [완전한 예제](#완전한-예제)를 참조하십시오.671전체 구현은 아래의 [완전한 예제](#complete-example)를 참조하십시오.

656 672 

657### 완전한 예제673<h3 id="complete-example">

674 완전한 예제

675</h3>

658 676 

659Claude는 진행하기 위해 사용자 입력이 필요할 때 명확화 질문을 합니다. 예를 들어 모바일 앱의 기술 스택을 결정하는 데 도움을 달라는 요청을 받으면 Claude는 크로스 플랫폼 대 네이티브, 백엔드 선호도 또는 대상 플랫폼에 대해 물어볼 수 있습니다. 이러한 질문은 Claude가 추측하기보다는 사용자의 선호도와 일치하는 결정을 내리는 데 도움이 됩니다.677Claude는 진행하기 위해 사용자 입력이 필요할 때 명확화 질문을 합니다. 예를 들어 모바일 앱의 기술 스택을 결정하는 데 도움을 달라는 요청을 받으면 Claude는 크로스 플랫폼 대 네이티브, 백엔드 선호도 또는 대상 플랫폼에 대해 물어볼 수 있습니다. 이러한 질문은 Claude가 추측하기보다는 사용자의 선호도와 일치하는 결정을 내리는 데 도움이 됩니다.

660 678 


821 ```839 ```

822</CodeGroup>840</CodeGroup>

823 841 

824## 제한 사항842<h2 id="limitations">

843 제한 사항

844</h2>

825 845 

826* **서브에이전트**: `AskUserQuestion`은 현재 Agent 도구를 통해 생성된 서브에이전트에서 사용할 수 없습니다.846* **서브에이전트**: `AskUserQuestion`은 현재 Agent 도구를 통해 생성된 서브에이전트에서 사용할 수 없습니다.

827* **질문 제한**: 각 `AskUserQuestion` 호출은 각각 2-4개 옵션이 있는 1-4개 질문을 지원합니다.847* **질문 제한**: 각 `AskUserQuestion` 호출은 각각 2-4개 옵션이 있는 1-4개 질문을 지원합니다.

828 848 

829## 사용자 입력을 얻는 다른 방법849<h2 id="other-ways-to-get-user-input">

850 사용자 입력을 얻는 다른 방법

851</h2>

830 852 

831`canUseTool` 콜백과 `AskUserQuestion` 도구는 대부분의 승인 및 명확화 시나리오를 다루지만, SDK는 사용자로부터 입력을 얻는 다른 방법을 제공합니다.853`canUseTool` 콜백과 `AskUserQuestion` 도구는 대부분의 승인 및 명확화 시나리오를 다루지만, SDK는 사용자로부터 입력을 얻는 다른 방법을 제공합니다.

832 854 

833### 스트리밍 입력855<h3 id="streaming-input">

856 스트리밍 입력

857</h3>

834 858 

835다음이 필요할 때 [스트리밍 입력](/ko/agent-sdk/streaming-vs-single-mode)을 사용하십시오.859다음이 필요할 때 [스트리밍 입력](/ko/agent-sdk/streaming-vs-single-mode)을 사용하십시오.

836 860 


840 864 

841스트리밍 입력은 사용자가 승인 체크포인트에서만이 아니라 실행 전체에서 에이전트와 상호 작용하는 대화형 UI에 이상적입니다.865스트리밍 입력은 사용자가 승인 체크포인트에서만이 아니라 실행 전체에서 에이전트와 상호 작용하는 대화형 UI에 이상적입니다.

842 866 

843### 사용자 정의 도구867<h3 id="custom-tools">

868 사용자 정의 도구

869</h3>

844 870 

845다음이 필요할 때 [사용자 정의 도구](/ko/agent-sdk/custom-tools)를 사용하십시오.871다음이 필요할 때 [사용자 정의 도구](/ko/agent-sdk/custom-tools)를 사용하십시오.

846 872 


850 876 

851사용자 정의 도구는 상호 작용을 완전히 제어할 수 있지만 기본 제공 `canUseTool` 콜백을 사용하는 것보다 더 많은 구현 작업이 필요합니다.877사용자 정의 도구는 상호 작용을 완전히 제어할 수 있지만 기본 제공 `canUseTool` 콜백을 사용하는 것보다 더 많은 구현 작업이 필요합니다.

852 878 

853## 관련 리소스879<h2 id="related-resources">

880 관련 리소스

881</h2>

854 882 

855* [권한 구성](/ko/agent-sdk/permissions): 권한 모드 및 규칙 설정883* [권한 구성](/ko/agent-sdk/permissions): 권한 모드 및 규칙 설정

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

agent-teams.md +149 −83

Details

7> 공유 작업, 에이전트 간 메시징, 중앙 집중식 관리를 통해 함께 작동하는 여러 Claude Code 인스턴스를 조율합니다.7> 공유 작업, 에이전트 간 메시징, 중앙 집중식 관리를 통해 함께 작동하는 여러 Claude Code 인스턴스를 조율합니다.

8 8 

9<Warning>9<Warning>

10 에이전트 팀은 실험적이며 기본적으로 비활성화되어 있습니다. [settings.json](/ko/settings)이나 환경에 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`를 추가하여 활성화합니다. 에이전트 팀은 세션 재개, 작업 조율, 종료 동작 관련 [알려진 제한 사항](#limitations)이 있습니다.10 에이전트 팀은 실험적이며 기본적으로 비활성화되어 있습니다. [settings.json](/ko/settings)이나 환경에 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`를 추가하여 활성화합니다. 해당 변수가 없으면 세션 시작 시 팀이 설정되지 않고, 팀 디렉토리가 작성되지 않으며, Claude가 팀원을 생성하거나 제안하지 않습니다. 에이전트 팀은 세션 재개, 작업 조율, 종료 동작 관련 [알려진 제한 사항](#limitations)이 있습니다.

11</Warning>11</Warning>

12 12 

13에이전트 팀을 사용하면 함께 작동하는 여러 Claude Code 인스턴스를 조율할 수 있습니다. 한 세션이 팀 리더 역할을 하여 작업을 조율하고, 작업을 할당하며, 결과를 종합합니다. 팀원들은 독립적으로 작동하며, 각각 자신의 컨텍스트 윈도우에서 작동하고, 서로 직접 통신합니다.13에이전트 팀을 사용하면 함께 작동하는 여러 Claude Code 인스턴스를 조율할 수 있습니다. 한 세션이 팀 리더 역할을 하여 작업을 조율하고, 작업을 할당하며, 결과를 종합합니다. 팀원들은 독립적으로 작동하며, 각각 자신의 컨텍스트 윈도우에서 작동하고, 서로 직접 통신합니다.


15단일 세션 내에서 실행되고 메인 에이전트에게만 보고할 수 있는 [subagents](/ko/sub-agents)와 달리, 리더를 거치지 않고 개별 팀원과 직접 상호작용할 수도 있습니다.15단일 세션 내에서 실행되고 메인 에이전트에게만 보고할 수 있는 [subagents](/ko/sub-agents)와 달리, 리더를 거치지 않고 개별 팀원과 직접 상호작용할 수도 있습니다.

16 16 

17<Note>17<Note>

18 에이전트 팀은 Claude Code v2.1.32 이상이 필요합니다. `claude --version`으로 버전을 확인합니다.18 이 페이지는 v2.1.178 기준의 에이전트 팀을 설명합니다. `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`가 설정되면, 팀원을 생성할 때 더 이상 설정 단계가 필요하지 않으며, 세션이 종료될 때 정리가 자동으로 수행됩니다. v2.1.178 이전에는 먼저 Claude에게 팀을 생성하고 이름을 지정하도록 요청했으며, Claude는 `TeamCreate` 및 `TeamDelete` 도구를 사용하여 설정하고 제거했습니다. 두 도구는 더 이상 존재하지 않습니다. Agent 도구의 `team_name` 입력은 허용되지만 무시되며, `TaskCreated`, `TaskCompleted`, 및 `TeammateIdle` [hook payloads](/ko/hooks#taskcreated)의 `team_name` 필드는 세션에서 파생된 이름을 전달하며 더 이상 사용되지 않습니다.

19</Note>19</Note>

20 20 

21이 페이지에서 다루는 내용:21이 페이지에서 다루는 내용:


25* [팀원 제어하기](#control-your-agent-team), 표시 모드, 작업 할당, 위임 포함25* [팀원 제어하기](#control-your-agent-team), 표시 모드, 작업 할당, 위임 포함

26* [병렬 작업 모범 사례](#best-practices)26* [병렬 작업 모범 사례](#best-practices)

27 27 

28## 에이전트 팀을 사용할 28<h2 id="when-to-use-agent-teams">

29 에이전트 팀을 사용할 때

30</h2>

29 31 

30에이전트 팀은 병렬 탐색이 실질적인 가치를 더하는 작업에 가장 효과적입니다. 전체 시나리오는 [사용 사례 예시](#use-case-examples)를 참조합니다. 가장 강력한 사용 사례는 다음과 같습니다:32에이전트 팀은 병렬 탐색이 실질적인 가치를 더하는 작업에 가장 효과적입니다. 전체 시나리오는 [사용 사례 예시](#use-case-examples)를 참조합니다. 가장 강력한 사용 사례는 다음과 같습니다:

31 33 


36 38 

37에이전트 팀은 조율 오버헤드를 추가하고 단일 세션보다 훨씬 더 많은 토큰을 사용합니다. 팀원들이 독립적으로 작동할 수 있을 때 가장 잘 작동합니다. 순차적 작업, 동일 파일 편집, 또는 많은 종속성이 있는 작업의 경우 단일 세션이나 [subagents](/ko/sub-agents)가 더 효과적입니다.39에이전트 팀은 조율 오버헤드를 추가하고 단일 세션보다 훨씬 더 많은 토큰을 사용합니다. 팀원들이 독립적으로 작동할 수 있을 때 가장 잘 작동합니다. 순차적 작업, 동일 파일 편집, 또는 많은 종속성이 있는 작업의 경우 단일 세션이나 [subagents](/ko/sub-agents)가 더 효과적입니다.

38 40 

39### subagents와 비교41<h3 id="compare-with-subagents">

42 subagents와 비교

43</h3>

40 44 

41에이전트 팀과 [subagents](/ko/sub-agents) 모두 작업을 병렬화할 수 있지만, 다르게 작동합니다. 워커들이 서로 통신해야 하는지 여부에 따라 선택합니다:45에이전트 팀과 [subagents](/ko/sub-agents) 모두 작업을 병렬화할 수 있지만, 다르게 작동합니다. 워커들이 서로 통신해야 하는지 여부에 따라 선택합니다:

42 46 


56 60 

57결과를 보고하는 빠르고 집중된 워커가 필요할 때는 subagents를 사용합니다. 팀원들이 발견을 공유하고, 서로 도전하며, 자체적으로 조율해야 할 때는 에이전트 팀을 사용합니다.61결과를 보고하는 빠르고 집중된 워커가 필요할 때는 subagents를 사용합니다. 팀원들이 발견을 공유하고, 서로 도전하며, 자체적으로 조율해야 할 때는 에이전트 팀을 사용합니다.

58 62 

59## 에이전트 팀 활성화63<h2 id="enable-agent-teams">

64 에이전트 팀 활성화

65</h2>

60 66 

61에이전트 팀은 기본적으로 비활성화되어 있습니다. `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` 환경 변수를 `1`로 설정하여 활성화합니다. 셸 환경이나 [settings.json](/ko/settings)을 통해 설정할 수 있습니다:67에이전트 팀은 기본적으로 비활성화되어 있습니다. `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` 환경 변수를 `1`로 설정하여 활성화합니다. 셸 환경이나 [settings.json](/ko/settings)을 통해 설정할 수 있습니다:

62 68 


68}74}

69```75```

70 76 

71## 첫 번째 에이전트 팀 시작하기77<h2 id="start-your-first-agent-team">

78 첫 번째 에이전트 팀 시작하기

79</h2>

72 80 

73에이전트 팀을 활성화한 후, Claude에게 에이전트 팀을 만들도록 요청하고 자연어로 원하는 작업과 팀 구조를 설명합니다. Claude는 팀을 만들고, 팀원들을 생성하며, 프롬프트에 따라 작업을 조율합니다.81에이전트 팀을 활성화한 후, 자연어로 원하는 작업과 팀원들을 설명합니다. Claude는 팀원들을 생성하고 프롬프트에 따라 작업을 조율합니다.

74 82 

75이 예시는 세 가지 역할이 독립적이고 서로를 기다리지 않고 문제를 탐색할 수 있기 때문에 잘 작동합니다:83이 예시는 세 가지 역할이 독립적이고 서로를 기다리지 않고 문제를 탐색할 수 있기 때문에 잘 작동합니다:

76 84 

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

78I'm designing a CLI tool that helps developers track TODO comments across86I'm designing a CLI tool that helps developers track TODO comments across

79their codebase. Create an agent team to explore this from different angles: one87their codebase. Spawn three teammates to explore this from different angles:

80teammate on UX, one on technical architecture, one playing devil's advocate.88one on UX, one on technical architecture, one playing devil's advocate.

81```89```

82 90 

83그러면 Claude는 [공유 작업 목록](/ko/interactive-mode#task-list)을 가진 팀을 만들고, 각 관점에 대한 팀원들을 생성하며, 문제를 탐색하고, 발견을 종합하며, 완료되었을 때 [팀을 정리](#clean-up-the-team)하려고 시도합니다.91그러면 Claude는 [공유 작업 목록](/ko/interactive-mode#task-list)을 채우고, 각 관점에 대한 팀원들을 생성하며, 문제를 탐색하고, 완료되었을 때 발견을 종합합니다.

84 92 

85리더의 터미널은 모든 팀원과 그들이 작업 중인 내용을 나열합니다. Shift+Down을 사용하여 팀원들을 순환하고 직접 메시지를 보냅니다. 마지막 팀원 이후, Shift+Down은 리더로 돌아갑니다.93리더의 터미널은 모든 팀원과 그들이 작업 중인 내용을 나열합니다. Shift+Down을 사용하여 팀원들을 순환하고 직접 메시지를 보냅니다. 마지막 팀원 이후, Shift+Down은 리더로 돌아갑니다.

86 94 

87각 팀원이 자신의 분할 창에 있기를 원하면 [표시 모드 선택](#choose-a-display-mode)을 참조합니다.95각 팀원이 자신의 분할 창에 있기를 원하면 [표시 모드 선택](#choose-a-display-mode)을 참조합니다.

88 96 

89## 에이전트 팀 제어하기97<h2 id="control-your-agent-team">

98 에이전트 팀 제어하기

99</h2>

90 100 

91리더에게 자연어로 원하는 것을 말합니다. 지시에 따라 팀 조율, 작업 할당, 위임을 처리합니다.101리더에게 자연어로 원하는 것을 말합니다. 지시에 따라 팀 조율, 작업 할당, 위임을 처리합니다.

92 102 

93### 표시 모드 선택103<h3 id="choose-a-display-mode">

104 표시 모드 선택

105</h3>

94 106 

95에이전트 팀은 두 가지 표시 모드를 지원합니다:107에이전트 팀은 두 가지 표시 모드를 지원합니다:

96 108 


101 `tmux`는 특정 운영 체제에서 알려진 제한 사항이 있으며 전통적으로 macOS에서 가장 잘 작동합니다. iTerm2에서 `tmux -CC`를 사용하는 것이 `tmux`로의 권장 진입점입니다.113 `tmux`는 특정 운영 체제에서 알려진 제한 사항이 있으며 전통적으로 macOS에서 가장 잘 작동합니다. iTerm2에서 `tmux -CC`를 사용하는 것이 `tmux`로의 권장 진입점입니다.

102</Note>114</Note>

103 115 

104기본값은 `"auto"`이며, 이미 tmux 세션 내에서 실행 중이면 분할 창을 사용하고, 그렇지 않으면 in-process를 사용합니다. `"tmux"` 설정은 분할 창 모드를 활성화하고 터미널에 따라 tmux 또는 iTerm2를 사용할지 자동으로 감지합니다. 재정의하려면 `~/.claude/settings.json`에서 [`teammateMode`](/ko/settings#available-settings)를 설정합니다:116기본값은 `"auto"`이며, 이미 tmux 세션 내에서 실행 중이거나 터미널이 iTerm2인 경우 분할 창을 사용하고, 그렇지 않으면 in-process를 사용합니다. `"tmux"` 설정은 분할 창 모드를 활성화하고 터미널에 따라 tmux 또는 iTerm2를 사용할지 자동으로 감지합니다. 재정의하려면 `~/.claude/settings.json`에서 [`teammateMode`](/ko/settings#available-settings)를 설정합니다:

105 117 

106```json theme={null}118```json theme={null}

107{119{


120* **tmux**: 시스템의 패키지 관리자를 통해 설치합니다. 플랫폼별 지침은 [tmux wiki](https://github.com/tmux/tmux/wiki/Installing)를 참조합니다.132* **tmux**: 시스템의 패키지 관리자를 통해 설치합니다. 플랫폼별 지침은 [tmux wiki](https://github.com/tmux/tmux/wiki/Installing)를 참조합니다.

121* **iTerm2**: [`it2` CLI](https://github.com/mkusaka/it2)를 설치한 후, **iTerm2 → Settings → General → Magic → Enable Python API**에서 Python API를 활성화합니다.133* **iTerm2**: [`it2` CLI](https://github.com/mkusaka/it2)를 설치한 후, **iTerm2 → Settings → General → Magic → Enable Python API**에서 Python API를 활성화합니다.

122 134 

123### 팀원 및 모델 지정135<h3 id="specify-teammates-and-models">

136 팀원 및 모델 지정

137</h3>

124 138 

125Claude는 작업에 따라 생성할 팀원의 수를 결정하거나, 정확히 원하는 것을 지정할 수 있습니다:139Claude는 작업에 따라 생성할 팀원의 수를 결정하거나, 정확히 원하는 것을 지정할 수 있습니다:

126 140 

127```text theme={null}141```text theme={null}

128Create a team with 4 teammates to refactor these modules in parallel.142Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for

129Use Sonnet for each teammate.143each teammate.

130```144```

131 145 

132팀원들은 기본적으로 리더의 `/model` 선택을 상속하지 않습니다. 프롬프트가 지정하지 않을 때 사용되는 모델을 변경하려면, `/config`에서 **기본 팀원 모델**을 설정합니다. \*\*기본값(리더의 모델)\*\*을 선택하여 팀원들이 리더의 현재 모델을 따르도록 합니다.146팀원들은 기본적으로 리더의 `/model` 선택을 상속하지 않습니다. 프롬프트가 지정하지 않을 때 사용되는 모델을 변경하려면, `/config`에서 **기본 팀원 모델**을 설정합니다. \*\*기본값(리더의 모델)\*\*을 선택하여 팀원들이 리더의 현재 모델을 따르도록 합니다.

133 147 

134### 팀원을 위한 계획 승인 요구148<h3 id="require-plan-approval-for-teammates">

149 팀원을 위한 계획 승인 요구

150</h3>

135 151 

136복잡하거나 위험한 작업의 경우, 팀원들이 구현하기 전에 계획하도록 요구할 수 있습니다. 팀원은 리더가 접근 방식을 승인할 때까지 읽기 전용 계획 모드에서 작동합니다:152복잡하거나 위험한 작업의 경우, 팀원들이 구현하기 전에 계획하도록 요구할 수 있습니다. 팀원은 리더가 접근 방식을 승인할 때까지 읽기 전용 계획 모드에서 작동합니다:

137 153 


144 160 

145리더는 자율적으로 승인 결정을 내립니다. 리더의 판단에 영향을 미치려면, 프롬프트에 "테스트 커버리지를 포함하는 계획만 승인" 또는 "데이터베이스 스키마를 수정하는 계획 거부"와 같은 기준을 제공합니다.161리더는 자율적으로 승인 결정을 내립니다. 리더의 판단에 영향을 미치려면, 프롬프트에 "테스트 커버리지를 포함하는 계획만 승인" 또는 "데이터베이스 스키마를 수정하는 계획 거부"와 같은 기준을 제공합니다.

146 162 

147### 팀원과 직접 대화하기163<h3 id="talk-to-teammates-directly">

164 팀원과 직접 대화하기

165</h3>

148 166 

149각 팀원은 완전하고 독립적인 Claude Code 세션입니다. 모든 팀원에게 직접 메시지를 보내 추가 지시를 제공하고, 후속 질문을 하거나, 접근 방식을 재지정할 수 있습니다.167각 팀원은 완전하고 독립적인 Claude Code 세션입니다. 모든 팀원에게 직접 메시지를 보내 추가 지시를 제공하고, 후속 질문을 하거나, 접근 방식을 재지정할 수 있습니다.

150 168 

151* **In-process 모드**: Shift+Down을 사용하여 팀원들을 순환한 후 입력하여 메시지를 보냅니다. Enter를 눌러 팀원의 세션을 보고, Escape를 눌러 현재 턴을 중단합니다. Ctrl+T를 눌러 작업 목록을 전환합니다.169* **In-process 모드**: Shift+Down을 사용하여 팀원들을 순환한 후 입력하여 메시지를 보냅니다. Enter를 눌러 팀원의 세션을 보고, Escape를 눌러 현재 턴을 중단합니다. Ctrl+T를 눌러 작업 목록을 전환합니다.

152* **분할 창 모드**: 팀원의 창을 클릭하여 세션과 직접 상호작용합니다. 각 팀원은 자신의 터미널의 전체 보기를 가집니다.170* **분할 창 모드**: 팀원의 창을 클릭하여 세션과 직접 상호작용합니다. 각 팀원은 자신의 터미널의 전체 보기를 가집니다.

153 171 

154### 작업 할당 및 요청172<h3 id="assign-and-claim-tasks">

173 작업 할당 및 요청

174</h3>

155 175 

156공유 작업 목록은 팀 전체의 작업을 조율합니다. 리더는 작업을 만들고 팀원들이 이를 처리합니다. 작업은 세 가지 상태를 가집니다: 대기 중, 진행 중, 완료됨. 작업은 다른 작업에 종속될 수도 있습니다: 미해결 종속성이 있는 대기 중인 작업은 해당 종속성이 완료될 때까지 요청할 수 없습니다.176공유 작업 목록은 팀 전체의 작업을 조율합니다. 리더는 작업을 만들고 팀원들이 이를 처리합니다. 작업은 세 가지 상태를 가집니다: 대기 중, 진행 중, 완료됨. 작업은 다른 작업에 종속될 수도 있습니다: 미해결 종속성이 있는 대기 중인 작업은 해당 종속성이 완료될 때까지 요청할 수 없습니다.

157 177 


162 182 

163작업 요청은 파일 잠금을 사용하여 여러 팀원이 동시에 동일한 작업을 요청하려고 할 때 경합 조건을 방지합니다.183작업 요청은 파일 잠금을 사용하여 여러 팀원이 동시에 동일한 작업을 요청하려고 할 때 경합 조건을 방지합니다.

164 184 

165### 팀원 종료하기185<h3 id="shut-down-teammates">

186 팀원 종료하기

187</h3>

166 188 

167팀원의 세션을 우아하게 종료하려면:189팀원의 세션을 우아하게 종료하려면, 이름으로 참조합니다. 예를 들어, researcher라는 팀원이 있는 경우:

168 190 

169```text theme={null}191```text theme={null}

170Ask the researcher teammate to shut down192Ask the researcher teammate to shut down


172 194 

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

174 196 

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

176 198 

177완료되었을 때, 리더에게 정리하도록 요청합니다:199<h3 id="enforce-quality-gates-with-hooks">

178 200 hooks로 품질 게이트 적용

179```text theme={null}201</h3>

180Clean up the team

181```

182 

183이는 공유 팀 리소스를 제거합니다. 리더가 정리를 실행할 때, 활성 팀원을 확인하고 여전히 실행 중이면 실패하므로 먼저 종료합니다.

184 

185<Warning>

186 항상 리더를 사용하여 정리합니다. 팀원들은 정리를 실행하면 안 됩니다. 팀원의 팀 컨텍스트가 올바르게 해결되지 않아 리소스가 일관성 없는 상태로 남을 수 있기 때문입니다.

187</Warning>

188 

189### hooks로 품질 게이트 적용

190 202 

191[hooks](/ko/hooks)를 사용하여 팀원들이 작업을 마치거나 작업이 생성되거나 완료될 때 규칙을 적용합니다:203[hooks](/ko/hooks)를 사용하여 팀원들이 작업을 마치거나 작업이 생성되거나 완료될 때 규칙을 적용합니다:

192 204 


194* [`TaskCreated`](/ko/hooks#taskcreated): 작업이 생성될 때 실행됩니다. 종료 코드 2로 종료하여 생성을 방지하고 피드백을 보냅니다.206* [`TaskCreated`](/ko/hooks#taskcreated): 작업이 생성될 때 실행됩니다. 종료 코드 2로 종료하여 생성을 방지하고 피드백을 보냅니다.

195* [`TaskCompleted`](/ko/hooks#taskcompleted): 작업이 완료로 표시될 때 실행됩니다. 종료 코드 2로 종료하여 완료를 방지하고 피드백을 보냅니다.207* [`TaskCompleted`](/ko/hooks#taskcompleted): 작업이 완료로 표시될 때 실행됩니다. 종료 코드 2로 종료하여 완료를 방지하고 피드백을 보냅니다.

196 208 

197## 에이전트 팀이 어떻게 작동하는지209<h2 id="how-agent-teams-work">

210 에이전트 팀이 어떻게 작동하는지

211</h2>

198 212 

199이 섹션은 에이전트 팀 뒤의 아키텍처와 메커니즘을 다룹니다. 사용을 시작하려면 위의 [에이전트 팀 제어하기](#control-your-agent-team)를 참조합니다.213이 섹션은 에이전트 팀 뒤의 아키텍처와 메커니즘을 다룹니다. 사용을 시작하려면 위의 [에이전트 팀 제어하기](#control-your-agent-team)를 참조합니다.

200 214 

201### Claude가 에이전트 팀을 시작하는 방법215<h3 id="how-claude-starts-agent-teams">

216 Claude가 에이전트 팀을 시작하는 방법

217</h3>

202 218 

203에이전트 팀이 시작되는 두 가지 방법이 있습니다:219에이전트 팀이 번째 팀원이 생성될 때 형성되며, 메인 세션이 리더 역할을 합니다. 팀원이 생성되는 두 가지 방법이 있습니다:

204 220 

205* ** 요청**: 병렬 작업의 이점이 있는 작업을 제공하고 명시적으로 에이전트 팀을 요청합니다. Claude는 지시에 따라 팀을 만듭니다.221* **팀원을 요청합니다**: 병렬 작업의 이점이 있는 작업을 제공하고 명시적으로 팀원을 요청합니다. Claude는 지시에 따라 팀원을 생성합니다.

206* **Claude가 제안**: Claude가 작업이 병렬 작업의 이점이 있다고 판단하면, 생성을 제안할 수 있습니다. 진행하기 전에 확인합니다.222* **Claude가 팀원을 제안합니다**: Claude가 작업이 병렬 작업의 이점이 있다고 판단하면, 팀원 생성을 제안할 수 있습니다. 진행하기 전에 확인합니다.

207 223 

208두 경우 모두 제어 권한을 유지합니다. Claude는 승인 없이 팀을 만들지 않습니다.224두 경우 모두 제어 권한을 유지합니다. Claude는 승인 없이 팀원을 생성하지 않습니다.

209 225 

210### 아키텍처226<h3 id="architecture">

227 아키텍처

228</h3>

211 229 

212에이전트 팀은 다음으로 구성됩니다:230에이전트 팀은 다음으로 구성됩니다:

213 231 

214| 구성 요소 | 역할 |232| 구성 요소 | 역할 |

215| :-------- | :-------------------------------------------- |233| :-------- | :------------------------------------ |

216| **팀 리더** | 팀을 만들고, 팀원들을 생성하며, 작업을 조율하는 메인 Claude Code 세션 |234| **팀 리더** | 팀원을 생성하고 작업을 조율하는 메인 Claude Code 세션 |

217| **팀원들** | 할당된 작업에서 각각 작동하는 별도의 Claude Code 인스턴스 |235| **팀원들** | 할당된 작업에서 각각 작동하는 별도의 Claude Code 인스턴스 |

218| **작업 목록** | 팀원들이 요청하고 완료하는 공유 작업 항목 목록 |236| **작업 목록** | 팀원들이 요청하고 완료하는 공유 작업 항목 목록 |

219| **메일박스** | 에이전트 간 통신을 위한 메시징 시스템 |237| **메일박스** | 에이전트 간 통신을 위한 메시징 시스템 |


222 240 

223시스템은 작업 종속성을 자동으로 관리합니다. 팀원이 다른 작업이 종속된 작업을 완료하면, 차단된 작업은 수동 개입 없이 차단 해제됩니다.241시스템은 작업 종속성을 자동으로 관리합니다. 팀원이 다른 작업이 종속된 작업을 완료하면, 차단된 작업은 수동 개입 없이 차단 해제됩니다.

224 242 

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

226 244 

227* **팀 구성**: `~/.claude/teams/{team-name}/config.json`245* **팀 구성**: `~/.claude/teams/{team-name}/config.json`

228* **작업 목록**: `~/.claude/tasks/{team-name}/`246* **작업 목록**: `~/.claude/tasks/{team-name}/`

229 247 

230Claude Code는 팀을 만들 이 둘을 자동으로 생성하고 팀원들이 참여하거나, 유휴 상태가 되거나, 떠날 때 업데이트합니다. 팀 구성은 세션 ID tmux ID와 같은 런타임 상태를 보유하므로, 수동으로 편집하거나 사전 작성하지 마십시오: 다음 상태 업데이트에서 변경 사항이 덮어씌워집니다.248Claude Code는 세션 시작 이 둘을 자동으로 생성하고 팀원들이 참여하거나, 유휴 상태가 되거나, 떠날 때 업데이트합니다. 팀 구성 디렉토리는 세션이 끝날 제거됩니다. 작업 목록 디렉토리는 로컬에 유지되며 절대 업로드되지 않으므로, 재개된 세션은 작업을 유지합니다. 보존은 세션 트랜스크립트에 대해 이미 제어하는 것과 동일한 [`cleanupPeriodDays`](/ko/settings#available-settings)에 의해 관리됩니다.

249 

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

231 251 

232재사용 가능한 팀원 역할을 정의하려면, 대신 [subagent 정의 사용](#use-subagent-definitions-for-teammates)을 사용합니다.252재사용 가능한 팀원 역할을 정의하려면, 대신 [subagent 정의 사용](#use-subagent-definitions-for-teammates)을 사용합니다.

233 253 


235 255 

236프로젝트 수준의 팀 구성 동등물은 없습니다. 프로젝트 디렉토리의 `.claude/teams/teams.json`과 같은 파일은 구성으로 인식되지 않습니다. Claude는 이를 일반 파일로 취급합니다.256프로젝트 수준의 팀 구성 동등물은 없습니다. 프로젝트 디렉토리의 `.claude/teams/teams.json`과 같은 파일은 구성으로 인식되지 않습니다. Claude는 이를 일반 파일로 취급합니다.

237 257 

238### 팀원을 위해 subagent 정의 사용258<h3 id="use-subagent-definitions-for-teammates">

259 팀원을 위해 subagent 정의 사용

260</h3>

239 261 

240팀원을 생성할 때, 프로젝트, 사용자, 플러그인, 또는 CLI 정의 등 모든 [subagent 범위](/ko/sub-agents#choose-the-subagent-scope)의 [subagent](/ko/sub-agents) 유형을 참조할 수 있습니다. 이를 통해 보안 검토자 또는 테스트 실행자와 같은 역할을 한 번 정의하고 위임된 subagent와 에이전트 팀 팀원 모두로 재사용할 수 있습니다.262팀원을 생성할 때, 프로젝트, 사용자, 플러그인, 또는 CLI 정의 등 모든 [subagent 범위](/ko/sub-agents#choose-the-subagent-scope)의 [subagent](/ko/sub-agents) 유형을 참조할 수 있습니다. 이를 통해 보안 검토자 또는 테스트 실행자와 같은 역할을 한 번 정의하고 위임된 subagent와 에이전트 팀 팀원 모두로 재사용할 수 있습니다.

241 263 


251 subagent 정의의 `skills`과 `mcpServers` frontmatter 필드는 해당 정의가 팀원으로 실행될 때 적용되지 않습니다. 팀원들은 일반 세션과 동일하게 프로젝트 및 사용자 설정에서 skills과 MCP servers를 로드합니다.273 subagent 정의의 `skills`과 `mcpServers` frontmatter 필드는 해당 정의가 팀원으로 실행될 때 적용되지 않습니다. 팀원들은 일반 세션과 동일하게 프로젝트 및 사용자 설정에서 skills과 MCP servers를 로드합니다.

252</Note>274</Note>

253 275 

254### 권한276<h3 id="permissions">

277 권한

278</h3>

255 279 

256팀원들은 리더의 권한 설정으로 시작합니다. 리더가 `--dangerously-skip-permissions`로 실행되면, 모든 팀원도 그렇게 합니다. 생성 후, 개별 팀원 모드를 변경할 수 있지만, 생성 시 팀원별 모드를 설정할 수 없습니다.280팀원들은 리더의 권한 설정으로 시작합니다. 리더가 `--dangerously-skip-permissions`로 실행되면, 모든 팀원도 그렇게 합니다. 생성 후, 개별 팀원 모드를 변경할 수 있지만, 생성 시 팀원별 모드를 설정할 수 없습니다.

257 281 

258### 컨텍스트 및 통신282<h3 id="context-and-communication">

283 컨텍스트 및 통신

284</h3>

259 285 

260각 팀원은 자신의 컨텍스트 윈도우를 가집니다. 생성될 때, 팀원은 일반 세션과 동일한 프로젝트 컨텍스트를 로드합니다: CLAUDE.md, MCP servers, skills. 또한 리더의 생성 프롬프트를 받습니다. 리더의 대화 기록은 전달되지 않습니다.286각 팀원은 자신의 컨텍스트 윈도우를 가집니다. 생성될 때, 팀원은 일반 세션과 동일한 프로젝트 컨텍스트를 로드합니다: CLAUDE.md, MCP servers, skills. 또한 리더의 생성 프롬프트를 받습니다. 리더의 대화 기록은 전달되지 않습니다.

261 287 


268 294 

269리더는 팀원을 생성할 때 각 팀원에게 이름을 할당하며, 모든 팀원은 그 이름으로 다른 팀원에게 메시지를 보낼 수 있습니다. 나중의 프롬프트에서 참조할 수 있는 예측 가능한 이름을 얻으려면, 생성 지시에서 각 팀원을 무엇이라고 부를지 리더에게 말합니다.295리더는 팀원을 생성할 때 각 팀원에게 이름을 할당하며, 모든 팀원은 그 이름으로 다른 팀원에게 메시지를 보낼 수 있습니다. 나중의 프롬프트에서 참조할 수 있는 예측 가능한 이름을 얻으려면, 생성 지시에서 각 팀원을 무엇이라고 부를지 리더에게 말합니다.

270 296 

271### 토큰 사용297<h3 id="token-usage">

298 토큰 사용

299</h3>

272 300 

273에이전트 팀은 단일 세션보다 훨씬 더 많은 토큰을 사용합니다. 각 팀원은 자신의 컨텍스트 윈도우를 가지며, 토큰 사용은 활성 팀원의 수에 따라 증가합니다. 연구, 검토, 새로운 기능 작업의 경우, 추가 토큰은 일반적으로 가치가 있습니다. 일상적인 작업의 경우, 단일 세션이 더 비용 효율적입니다. 사용 지침은 [에이전트 팀 토큰 비용](/ko/costs#agent-team-token-costs)을 참조합니다.301에이전트 팀은 단일 세션보다 훨씬 더 많은 토큰을 사용합니다. 각 팀원은 자신의 컨텍스트 윈도우를 가지며, 토큰 사용은 활성 팀원의 수에 따라 증가합니다. 연구, 검토, 새로운 기능 작업의 경우, 추가 토큰은 일반적으로 가치가 있습니다. 일상적인 작업의 경우, 단일 세션이 더 비용 효율적입니다. 사용 지침은 [에이전트 팀 토큰 비용](/ko/costs#agent-team-token-costs)을 참조합니다.

274 302 

275## 사용 사례 예시303<h2 id="use-case-examples">

304 사용 사례 예시

305</h2>

276 306 

277이 예시들은 병렬 탐색이 가치를 더하는 작업을 에이전트 팀이 어떻게 처리하는지 보여줍니다.307이 예시들은 병렬 탐색이 가치를 더하는 작업을 에이전트 팀이 어떻게 처리하는지 보여줍니다.

278 308 

279### 병렬 코드 검토 실행309<h3 id="run-a-parallel-code-review">

310 병렬 코드 검토 실행

311</h3>

280 312 

281단일 검토자는 한 번에 한 가지 유형의 문제로 기울어지는 경향이 있습니다. 검토 기준을 독립적인 도메인으로 분할하면 보안, 성능, 테스트 커버리지가 모두 동시에 철저한 주의를 받습니다. 프롬프트는 각 팀원에게 고유한 렌즈를 할당하여 겹치지 않도록 합니다:313단일 검토자는 한 번에 한 가지 유형의 문제로 기울어지는 경향이 있습니다. 검토 기준을 독립적인 도메인으로 분할하면 보안, 성능, 테스트 커버리지가 모두 동시에 철저한 주의를 받습니다. 프롬프트는 각 팀원에게 고유한 렌즈를 할당하여 겹치지 않도록 합니다:

282 314 

283```text theme={null}315```text theme={null}

284Create an agent team to review PR #142. Spawn three reviewers:316PR #142를 검토하기 위해 명의 팀원을 배치합니다:

285- One focused on security implications317- 보안 영향에 중점을 두는 팀원

286- One checking performance impact318- 성능 영향을 확인하는 팀원

287- One validating test coverage319- 테스트 커버리지를 검증하는 팀원

288Have them each review and report findings.320각각 검토하고 발견 사항을 보고하도록 합니다.

289```321```

290 322 

291각 검토자는 동일한 PR에서 작동하지만 다른 필터를 적용합니다. 리더는 모두 완료된 후 세 명 모두의 발견을 종합합니다.323각 검토자는 동일한 PR에서 작동하지만 다른 필터를 적용합니다. 리더는 모두 완료된 후 세 명 모두의 발견을 종합합니다.

292 324 

293### 경쟁하는 가설로 조사하기325<h3 id="investigate-with-competing-hypotheses">

326 경쟁하는 가설로 조사하기

327</h3>

294 328 

295근본 원인이 불명확할 때, 단일 에이전트는 그럴듯한 설명 하나를 찾고 멈추는 경향이 있습니다. 프롬프트는 팀원들을 명시적으로 적대적으로 만들어 이를 방지합니다: 각 팀원의 일은 자신의 이론을 조사하는 것뿐만 아니라 다른 팀원들에게 도전하는 것입니다.329근본 원인이 불명확할 때, 단일 에이전트는 그럴듯한 설명 하나를 찾고 멈추는 경향이 있습니다. 프롬프트는 팀원들을 명시적으로 적대적으로 만들어 이를 방지합니다: 각 팀원의 일은 자신의 이론을 조사하는 것뿐만 아니라 다른 팀원들에게 도전하는 것입니다.

296 330 

297```text theme={null}331```text theme={null}

298Users report the app exits after one message instead of staying connected.332사용자들이 앱이 연결 상태를 유지하는 대신 메시지 후에 종료된다고 보고합니다.

299Spawn 5 agent teammates to investigate different hypotheses. Have them talk to3335명의 에이전트 팀원을 배치하여 다양한 가설을 조사하도록 합니다. 그들이 서로 대화하여

300each other to try to disprove each other's theories, like a scientific334과학적 토론처럼 서로의 이론을 반박하려고 하도록 합니다. 발견 사항 문서를

301debate. Update the findings doc with whatever consensus emerges.335나타나는 합의로 업데이트합니다.

302```336```

303 337 

304토론 구조가 여기서 핵심 메커니즘입니다. 순차적 조사는 앵커링으로 인해 고통받습니다: 한 이론이 탐색되면, 후속 조사는 그것에 편향됩니다.338토론 구조가 여기서 핵심 메커니즘입니다. 순차적 조사는 앵커링으로 인해 고통받습니다: 한 이론이 탐색되면, 후속 조사는 그것에 편향됩니다.

305 339 

306여러 독립적인 조사자가 적극적으로 서로의 이론을 반박하려고 할 때, 생존하는 이론은 실제 근본 원인일 가능성이 훨씬 높습니다.340여러 독립적인 조사자가 적극적으로 서로의 이론을 반박하려고 할 때, 생존하는 이론은 실제 근본 원인일 가능성이 훨씬 높습니다.

307 341 

308## 모범 사례342<h2 id="best-practices">

343 모범 사례

344</h2>

309 345 

310### 팀원에게 충분한 컨텍스트 제공346<h3 id="give-teammates-enough-context">

347 팀원에게 충분한 컨텍스트 제공

348</h3>

311 349 

312팀원들은 CLAUDE.md, MCP servers, skills를 포함한 프로젝트 컨텍스트를 자동으로 로드하지만, 리더의 대화 기록을 상속하지 않습니다. 자세한 내용은 [컨텍스트 및 통신](#context-and-communication)을 참조합니다. 생성 프롬프트에 작업별 세부 사항을 포함합니다:350팀원들은 CLAUDE.md, MCP servers, skills를 포함한 프로젝트 컨텍스트를 자동으로 로드하지만, 리더의 대화 기록을 상속하지 않습니다. 자세한 내용은 [컨텍스트 및 통신](#context-and-communication)을 참조합니다. 생성 프롬프트에 작업별 세부 사항을 포함합니다:

313 351 


318httpOnly cookies. Report any issues with severity ratings."356httpOnly cookies. Report any issues with severity ratings."

319```357```

320 358 

321### 적절한 팀 크기 선택359<h3 id="choose-an-appropriate-team-size">

360 적절한 팀 크기 선택

361</h3>

322 362 

323팀원의 수에 대한 하드 제한은 없지만, 실질적인 제약이 적용됩니다:363팀원의 수에 대한 하드 제한은 없지만, 실질적인 제약이 적용됩니다:

324 364 


332 372 

333작업이 실제로 팀원들이 동시에 작동하는 것의 이점이 있을 때만 확장합니다. 세 명의 집중된 팀원은 종종 다섯 명의 산만한 팀원을 능가합니다.373작업이 실제로 팀원들이 동시에 작동하는 것의 이점이 있을 때만 확장합니다. 세 명의 집중된 팀원은 종종 다섯 명의 산만한 팀원을 능가합니다.

334 374 

335### 작업을 적절히 크기 조정375<h3 id="size-tasks-appropriately">

376 작업을 적절히 크기 조정

377</h3>

336 378 

337* **너무 작음**: 조율 오버헤드가 이점을 초과합니다379* **너무 작음**: 조율 오버헤드가 이점을 초과합니다

338* **너무 큼**: 팀원들이 체크인 없이 너무 오래 작동하여 낭비된 노력의 위험이 증가합니다380* **너무 큼**: 팀원들이 체크인 없이 너무 오래 작동하여 낭비된 노력의 위험이 증가합니다


342 리더는 작업을 작업으로 나누고 팀원들에게 자동으로 할당합니다. 충분한 작업을 만들지 않으면, 작업을 더 작은 조각으로 분할하도록 요청합니다. 팀원당 5-6개의 작업을 유지하면 모두를 생산적으로 유지하고 누군가 막히면 리더가 작업을 재할당할 수 있습니다.384 리더는 작업을 작업으로 나누고 팀원들에게 자동으로 할당합니다. 충분한 작업을 만들지 않으면, 작업을 더 작은 조각으로 분할하도록 요청합니다. 팀원당 5-6개의 작업을 유지하면 모두를 생산적으로 유지하고 누군가 막히면 리더가 작업을 재할당할 수 있습니다.

343</Tip>385</Tip>

344 386 

345### 팀원들이 완료될 때까지 기다리기387<h3 id="wait-for-teammates-to-finish">

388 팀원들이 완료될 때까지 기다리기

389</h3>

346 390 

347때때로 리더는 팀원들을 기다리지 않고 작업을 자체적으로 구현하기 시작합니다. 이를 알아차리면:391때때로 리더는 팀원들을 기다리지 않고 작업을 자체적으로 구현하기 시작합니다. 이를 알아차리면:

348 392 


350Wait for your teammates to complete their tasks before proceeding394Wait for your teammates to complete their tasks before proceeding

351```395```

352 396 

353### 연구 및 검토로 시작하기397<h3 id="start-with-research-and-review">

398 연구 및 검토로 시작하기

399</h3>

354 400 

355에이전트 팀을 처음 사용하는 경우, 명확한 경계가 있고 코드 작성이 필요하지 않은 작업으로 시작합니다: PR 검토, 라이브러리 연구, 또는 버그 조사. 이러한 작업은 병렬 탐색의 가치를 보여주면서 병렬 구현과 함께 오는 조율 문제 없이 보여줍니다.401에이전트 팀을 처음 사용하는 경우, 명확한 경계가 있고 코드 작성이 필요하지 않은 작업으로 시작합니다: PR 검토, 라이브러리 연구, 또는 버그 조사. 이러한 작업은 병렬 탐색의 가치를 보여주면서 병렬 구현과 함께 오는 조율 문제 없이 보여줍니다.

356 402 

357### 파일 충돌 피하기403<h3 id="avoid-file-conflicts">

404 파일 충돌 피하기

405</h3>

358 406 

359두 팀원이 동일한 파일을 편집하면 덮어쓰기가 발생합니다. 각 팀원이 다른 파일 집합을 소유하도록 작업을 나눕니다.407두 팀원이 동일한 파일을 편집하면 덮어쓰기가 발생합니다. 각 팀원이 다른 파일 집합을 소유하도록 작업을 나눕니다.

360 408 

361### 모니터링 및 조율409<h3 id="monitor-and-steer">

410 모니터링 및 조율

411</h3>

362 412 

363팀원들의 진행 상황을 확인하고, 작동하지 않는 접근 방식을 재지정하며, 발견이 들어올 때 종합합니다. 팀을 무인으로 너무 오래 실행하면 낭비된 노력의 위험이 증가합니다.413팀원들의 진행 상황을 확인하고, 작동하지 않는 접근 방식을 재지정하며, 발견이 들어올 때 종합합니다. 팀을 무인으로 너무 오래 실행하면 낭비된 노력의 위험이 증가합니다.

364 414 

365## 문제 해결415<h2 id="troubleshooting">

416 문제 해결

417</h2>

366 418 

367### 팀원이 나타나지 않음419<h3 id="teammates-not-appearing">

420 팀원이 나타나지 않음

421</h3>

368 422 

369Claude에게 팀을 만들도록 요청한 후 팀원이 나타나지 않으면:423Claude에게 팀원을 생성하도록 요청한 후 팀원이 나타나지 않으면:

370 424 

371* In-process 모드에서, 팀원들이 이미 실행 중이지만 보이지 않을 수 있습니다. Shift+Down을 눌러 활성 팀원들을 순환합니다.425* In-process 모드에서, 팀원들이 이미 실행 중이지만 보이지 않을 수 있습니다. Shift+Down을 눌러 활성 팀원들을 순환합니다.

372* Claude에게 준 작업이 팀을 보증할 만큼 복잡한지 확인합니다. Claude는 작업에 따라 팀원을 생성할지 결정합니다.426* Claude에게 준 작업이 팀원을 보증할 만큼 복잡한지 확인합니다. Claude는 작업에 따라 팀원을 생성할지 결정합니다.

373* 분할 창을 명시적으로 요청했으면, tmux가 설치되어 있고 PATH에서 사용 가능한지 확인합니다:427* 분할 창을 명시적으로 요청했으면, tmux가 설치되어 있고 PATH에서 사용 가능한지 확인합니다:

374 ```bash theme={null}428 ```bash theme={null}

375 which tmux429 which tmux

376 ```430 ```

377* iTerm2의 경우, `it2` CLI가 설치되어 있고 Python API가 iTerm2 환경 설정에서 활성화되어 있는지 확인합니다.431* iTerm2의 경우, `it2` CLI가 설치되어 있고 Python API가 iTerm2 환경 설정에서 활성화되어 있는지 확인합니다.

378 432 

379### 너무 많은 권한 프롬프트433<h3 id="too-many-permission-prompts">

434 너무 많은 권한 프롬프트

435</h3>

380 436 

381팀원 권한 요청이 리더로 버블업되어 마찰을 일으킬 수 있습니다. 팀원들을 생성하기 전에 [권한 설정](/ko/permissions)에서 일반적인 작업을 사전 승인하여 중단을 줄입니다.437팀원 권한 요청이 리더로 버블업되어 마찰을 일으킬 수 있습니다. 팀원들을 생성하기 전에 [권한 설정](/ko/permissions)에서 일반적인 작업을 사전 승인하여 중단을 줄입니다.

382 438 

383### 팀원들이 오류에서 중지됨439<h3 id="teammates-stopping-on-errors">

440 팀원들이 오류에서 중지됨

441</h3>

384 442 

385팀원들은 오류를 만난 후 복구하지 않고 중지할 수 있습니다. In-process 모드에서 Shift+Down을 사용하거나 분할 모드에서 창을 클릭하여 출력을 확인한 후:443팀원들은 오류를 만난 후 복구하지 않고 중지할 수 있습니다. In-process 모드에서 Shift+Down을 사용하거나 분할 모드에서 창을 클릭하여 출력을 확인한 후:

386 444 

387* 직접 추가 지시를 제공합니다445* 직접 추가 지시를 제공합니다

388* 작업을 계속하기 위해 대체 팀원을 생성합니다446* 작업을 계속하기 위해 대체 팀원을 생성합니다

389 447 

390### 리더가 작업 완료 전에 종료됨448<h3 id="lead-shuts-down-before-work-is-done">

449 리더가 작업 완료 전에 종료됨

450</h3>

391 451 

392리더는 모든 작업이 실제로 완료되기 전에 팀이 완료되었다고 결정할 수 있습니다. 이 경우 계속하도록 말합니다. 또한 리더가 위임하지 않고 작업을 시작하면 팀원들이 완료될 때까지 기다리도록 말할 수 있습니다.452리더는 모든 작업이 실제로 완료되기 전에 팀이 완료되었다고 결정할 수 있습니다. 이 경우 계속하도록 말합니다. 또한 리더가 위임하지 않고 작업을 시작하면 팀원들이 완료될 때까지 기다리도록 말할 수 있습니다.

393 453 

394### 고아 tmux 세션454<h3 id="orphaned-tmux-sessions">

455 고아 tmux 세션

456</h3>

395 457 

396팀이 끝난 후 tmux 세션이 지속되면, 완전히 정리되지 않았을 수 있습니다. 세션을 나열하고 팀에서 만든 세션을 종료합니다:458팀이 끝난 후 tmux 세션이 지속되면, 완전히 정리되지 않았을 수 있습니다. 세션을 나열하고 팀에서 만든 세션을 종료합니다:

397 459 


400tmux kill-session -t <session-name>462tmux kill-session -t <session-name>

401```463```

402 464 

403## 제한 사항465<h2 id="limitations">

466 제한 사항

467</h2>

404 468 

405에이전트 팀은 실험적입니다. 주의할 현재 제한 사항:469에이전트 팀은 실험적입니다. 주의할 현재 제한 사항:

406 470 

407* **In-process 팀원과의 세션 재개 없음**: `/resume`과 `/rewind`는 in-process 팀원을 복원하지 않습니다. 세션을 재개한 후, 리더는 더 이상 존재하지 않는 팀원에게 메시지를 보내려고 시도할 수 있습니다. 이 경우 리더에게 새 팀원을 생성하도록 말합니다.471* **In-process 팀원과의 세션 재개 없음**: `/resume`과 `/rewind`는 in-process 팀원을 복원하지 않습니다. 세션을 재개한 후, 리더는 더 이상 존재하지 않는 팀원에게 메시지를 보내려고 시도할 수 있습니다. 이 경우 리더에게 새 팀원을 생성하도록 말합니다.

408* **작업 상태가 지연될 수 있음**: 팀원들이 때때로 작업을 완료로 표시하지 못하여 종속 작업을 차단합니다. 작업이 막혀 있는 것처럼 보이면, 작업이 실제로 완료되었는지 확인하고 작업 상태를 수동으로 업데이트하거나 리더에게 팀원을 밀도록 말합니다.472* **작업 상태가 지연될 수 있음**: 팀원들이 때때로 작업을 완료로 표시하지 못하여 종속 작업을 차단합니다. 작업이 막혀 있는 것처럼 보이면, 작업이 실제로 완료되었는지 확인하고 작업 상태를 수동으로 업데이트하거나 리더에게 팀원을 밀도록 말합니다.

409* **종료가 느릴 수 있음**: 팀원들은 현재 요청이나 도구 호출을 마친 후 종료되어 시간이 걸릴 수 있습니다.473* **종료가 느릴 수 있음**: 팀원들은 현재 요청이나 도구 호출을 마친 후 종료되어 시간이 걸릴 수 있습니다.

410* **세션당 한 팀**: 리더는 번에 팀만 관리할 있습니다. 팀을 시작하기 전에 현재 팀을 정리합니다.474* **세션당 한 팀**: 세션은 정확히 하나의 팀을 가지며, 해당 세션으로 범위가 지정됩니다. 추가 명명된 팀을 만들거나 세션 간에 팀을 공유할 수 없습니다.

411* **중첩된 팀 없음**: 팀원들은 자신의 팀이나 팀원을 생성할 수 없습니다. 리더만 팀을 관리할 수 있습니다.475* **중첩된 팀 없음**: 팀원들은 자신의 팀원을 생성할 수 없습니다. 리더만 팀을 관리할 수 있습니다.

412* **리더가 고정됨**: 팀을 만드는 세션은 수명 동안 리더입니다. 팀원을 리더로 승격하거나 리더십을 이전할 수 없습니다.476* **리더가 고정됨**: 세션은 수명 동안 리더입니다. 팀원을 리더로 승격하거나 리더십을 이전할 수 없습니다.

413* **생성 시 권한 설정**: 모든 팀원은 리더의 권한 모드로 시작합니다. 생성 후 개별 팀원 모드를 변경할 수 있지만, 생성 시 팀원별 모드를 설정할 수 없습니다.477* **생성 시 권한 설정**: 모든 팀원은 리더의 권한 모드로 시작합니다. 생성 후 개별 팀원 모드를 변경할 수 있지만, 생성 시 팀원별 모드를 설정할 수 없습니다.

414* **분할 창은 tmux 또는 iTerm2 필요**: 기본 in-process 모드는 모든 터미널에서 작동합니다. 분할 창 모드는 VS Code의 통합 터미널, Windows Terminal, Ghostty에서 지원되지 않습니다.478* **분할 창은 tmux 또는 iTerm2 필요**: 기본 in-process 모드는 모든 터미널에서 작동합니다. 분할 창 모드는 VS Code의 통합 터미널, Windows Terminal, Ghostty에서 지원되지 않습니다.

415 479 


417 **`CLAUDE.md`는 정상적으로 작동합니다**: 팀원들은 작업 디렉토리에서 `CLAUDE.md` 파일을 읽습니다. 이를 사용하여 모든 팀원에게 프로젝트별 지침을 제공합니다.481 **`CLAUDE.md`는 정상적으로 작동합니다**: 팀원들은 작업 디렉토리에서 `CLAUDE.md` 파일을 읽습니다. 이를 사용하여 모든 팀원에게 프로젝트별 지침을 제공합니다.

418</Tip>482</Tip>

419 483 

420## 다음 단계484<h2 id="next-steps">

485 다음 단계

486</h2>

421 487 

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

423 489 

agent-view.md +14 −5

Details

143 143 

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

145 145 

146v2.1.161부터 세션이 서브에이전트, 백그라운드 셸 명령 또는 모니터와 같은 두 개 이상의 병렬 작업 항목을 실행 중일 때, `2/5`와 같은 `done/total` 개수가 요약 텍스트 앞에 나타납니다.

147 

146각 새로고침은 일반 제공자를 통한 하나의 짧은 Haiku 클래스 요청이며, 세션 자체와 동일한 [데이터 사용 약관](/ko/data-usage)에 따라 청구되고 처리됩니다. Bedrock, Vertex AI, Microsoft Foundry 및 사용자 정의 게이트웨이와 같은 타사 제공자에서는 Haiku 모델이 구성되지 않은 경우 요청이 세션의 주 모델로 폴백됩니다. 이러한 제공자에서 이 요약에 대한 모델을 선택하려면 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/ko/model-config#environment-variables)을 설정합니다.148각 새로고침은 일반 제공자를 통한 하나의 짧은 Haiku 클래스 요청이며, 세션 자체와 동일한 [데이터 사용 약관](/ko/data-usage)에 따라 청구되고 처리됩니다. Bedrock, Vertex AI, Microsoft Foundry 및 사용자 정의 게이트웨이와 같은 타사 제공자에서는 Haiku 모델이 구성되지 않은 경우 요청이 세션의 주 모델로 폴백됩니다. 이러한 제공자에서 이 요약에 대한 모델을 선택하려면 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/ko/model-config#environment-variables)을 설정합니다.

147 149 

148<h3 id="pull-request-status">150<h3 id="pull-request-status">


170 172 

171선택된 행에서 `Space`를 눌러 엿보기 패널을 엽니다. 세션이 필요로 하는 것, 최근 출력 및 열린 풀 리퀘스트를 보여줍니다. 대부분의 경우 이것으로 충분하며 전체 트랜스크립트를 열 필요가 없습니다.173선택된 행에서 `Space`를 눌러 엿보기 패널을 엽니다. 세션이 필요로 하는 것, 최근 출력 및 열린 풀 리퀘스트를 보여줍니다. 대부분의 경우 이것으로 충분하며 전체 트랜스크립트를 열 필요가 없습니다.

172 174 

175v2.1.161부터 세션이 병렬 작업 항목을 실행 중일 때, 패널은 또한 가장 오래 실행 중인 항목의 이름과 실행 시간을 표시하므로 연결하지 않고도 세션이 기다리는 것을 볼 수 있습니다.

176 

173엿보기 패널에 답변을 입력하고 `Enter`를 눌러 해당 세션으로 전송합니다. 세션이 객관식 질문을 하는 경우 엿보기 패널은 옵션을 표시하고 숫자 키를 눌러 하나를 선택할 수 있습니다. 다른 차단된 세션의 경우 `Tab`을 눌러 입력을 편집하기 전에 제안된 답변으로 채웁니다. 답변 앞에 `!`를 붙여 Bash 명령을 대신 전송합니다.177엿보기 패널에 답변을 입력하고 `Enter`를 눌러 해당 세션으로 전송합니다. 세션이 객관식 질문을 하는 경우 엿보기 패널은 옵션을 표시하고 숫자 키를 눌러 하나를 선택할 수 있습니다. 다른 차단된 세션의 경우 `Tab`을 눌러 입력을 편집하기 전에 제안된 답변으로 채웁니다. 답변 앞에 `!`를 붙여 Bash 명령을 대신 전송합니다.

174 178 

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


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

225| `s:<state>` | 주어진 상태의 세션, 예: `s:working`. 또한 `s:blocked`를 수락하여 입력을 기다리는 모든 것 |229| `s:<state>` | 주어진 상태의 세션, 예: `s:working`. 또한 `s:blocked`를 수락하여 입력을 기다리는 모든 것 |

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

231| 다른 URL | 첫 번째 프롬프트에 해당 URL이 포함된 세션 |

227 232 

228<h3 id="keyboard-shortcuts">233<h3 id="keyboard-shortcuts">

229 키보드 단축키234 키보드 단축키


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

479 484 

480| 명령 | 목적 |485| 명령 | 목적 |

481| :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |486| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

482| `claude agents` | 에이전트 뷰 열기 |487| `claude agents` | 에이전트 뷰 열기 |

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

484| `claude agents --json` | 라이브 세션을 JSON 배열로 인쇄하고 종료합니다. 항목에는 `pid`, `cwd`, `kind`, `startedAt`이 있으며, 설정된 경우 `sessionId`, `name`, `status` 포함됩니다. `--cwd <path>`와 함께 사용하여 필터링 |489| `claude agents --json` | 활성 세션을 JSON 배열로 인쇄하고 종료합니다. 모든 라이브 세션과 프로세스가 종료되었어도 여전히 작동 중이거나 차단된 백그라운드 세션이 포함됩니다. 완료된 백그라운드 세션도 포함하려면 `--all` 추가합니다. 각 항목에는 `cwd`, `kind`, `startedAt`이 있습니다. 백그라운드 항목에는 `claude attach`/`logs`/`stop`에서 사용 가능한 `id`와 `state`도 있습니다. `state`는 `working`, `blocked`, `done`, `failed`, `stopped` 중 하나입니다. `pid`와 `status`는 프로세스가 활성 상태일 때만 표시되며, `status` `waiting`일 때는 `waitingFor`가 표시되어 `permission prompt` 또는 `input needed`와 같이 세션이 차단된 이유를 나타냅니다. `sessionId`와 `name`은 설정된 경우 표시됩니다. `--cwd <path>`와 함께 사용하여 필터링 |

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

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

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


530 535 

531각 백그라운드 세션에는 `CLAUDE_JOB_DIR` 환경 변수가 `~/.claude/jobs/<id>` 디렉토리로 설정되어 있으므로 세션이 실행하는 셸 명령은 병렬 세션과 충돌하지 않고 `$CLAUDE_JOB_DIR/tmp`에 임시 파일을 쓸 수 있습니다.536각 백그라운드 세션에는 `CLAUDE_JOB_DIR` 환경 변수가 `~/.claude/jobs/<id>` 디렉토리로 설정되어 있으므로 세션이 실행하는 셸 명령은 병렬 세션과 충돌하지 않고 `$CLAUDE_JOB_DIR/tmp`에 임시 파일을 쓸 수 있습니다.

532 537 

533파일을 직접 읽지 않고 이 상태를 검사하려면 `claude daemon status`를 실행합니다. 감독자에 도달할 수 있는지 여부, 프로세스 ID 및 버전, 소켓 디렉토리, 그리고 활성 백그라운드 세션의 수를 보고합니다. `/doctor`는 동일한 검사의 요약을 포함합니다. Windows에서 `claude daemon status`는 감독자의 파이프 키 파일이 잠겨 있거나 읽을 수 없을 때 일반적인 연결 실패를 보고하는 대신 기본 파일 오류를 표시합니다.538파일을 직접 읽지 않고 이 상태를 검사하려면 `claude daemon status`를 실행합니다. 감독자에 도달할 수 있는지 여부, 프로세스 ID 및 버전, 소켓 디렉토리, 그리고 활성 백그라운드 세션의 수를 보고합니다. `/doctor`는 동일한 검사의 요약을 포함합니다.

539 

540명령은 또한 실행 중인 감독자가 호출한 `claude`와 다른 버전에 있을 때 경고하며, 이는 감독자가 아직 다시 시작하지 않은 업데이트 후에 발생합니다. 경고는 두 버전을 모두 표시하고 새 버전을 적용하려면 `claude daemon stop --any`를 실행하도록 지시합니다. Claude Code가 OS 서비스로 설치된 경우 제안된 명령은 플래그 없이 `claude daemon stop`입니다.

541 

542Windows에서 `claude daemon status`는 감독자의 파이프 키 파일이 잠겨 있거나 읽을 수 없을 때 일반적인 연결 실패를 보고하는 대신 기본 파일 오류를 표시합니다.

534 543 

535<h3 id="turn-off-agent-view">544<h3 id="turn-off-agent-view">

536 에이전트 뷰 끄기545 에이전트 뷰 끄기


556 565 

557첫 번째 세션을 디스패치하기 전에 에이전트 뷰는 세션 목록 대신 짧은 온보딩 힌트와 예제 프롬프트를 표시합니다. 하단의 입력에 프롬프트를 입력하고 `Enter`를 눌러 첫 번째 세션을 디스패치합니다.566첫 번째 세션을 디스패치하기 전에 에이전트 뷰는 세션 목록 대신 짧은 온보딩 힌트와 예제 프롬프트를 표시합니다. 하단의 입력에 프롬프트를 입력하고 `Enter`를 눌러 첫 번째 세션을 디스패치합니다.

558 567 

559<h3 id="cannot-open-agents-because-background-tasks-are-running">568<h3 id="cannot-open-agents-because-work-is-running-in-the-background">

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

561</h3>570</h3>

562 571 

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

564 573 

565<h3 id="prompt-rejected-as-too-short">574<h3 id="prompt-rejected-as-too-short">

566 프롬프트가 너무 짧아서 거부됨575 프롬프트가 너무 짧아서 거부됨

agents.md +3 −3

Details

9[서브에이전트](/ko/sub-agents), [에이전트 뷰](/ko/agent-view), [에이전트 팀](/ko/agent-teams), [동적 워크플로우](/ko/workflows)는 각각 다른 방식으로 작업을 병렬화합니다. 올바른 선택은 각 대화에 직접 참여하고 싶은지, 작업을 넘기고 나중에 확인하고 싶은지, 아니면 Claude가 작업자 그룹을 조율하도록 하고 싶은지에 따라 달라집니다.9[서브에이전트](/ko/sub-agents), [에이전트 뷰](/ko/agent-view), [에이전트 팀](/ko/agent-teams), [동적 워크플로우](/ko/workflows)는 각각 다른 방식으로 작업을 병렬화합니다. 올바른 선택은 각 대화에 직접 참여하고 싶은지, 작업을 넘기고 나중에 확인하고 싶은지, 아니면 Claude가 작업자 그룹을 조율하도록 하고 싶은지에 따라 달라집니다.

10 10 

11| 접근 방식 | 제공되는 기능 | 사용 시기 |11| 접근 방식 | 제공되는 기능 | 사용 시기 |

12| :------------------------ | :---------------------------------------------------------------------- | :-------------------------------------------------------------------------------- |12| :------------------------ | :----------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- |

13| [서브에이전트](/ko/sub-agents) | 한 세션 내에서 자신의 컨텍스트에서 부작업을 수행하고 요약을 반환하는 위임된 작업자 | 부작업이 검색 결과, 로그 또는 다시 참조하지 않을 파일 내용으로 주 대화를 넘칠 때 |13| [서브에이전트](/ko/sub-agents) | 한 세션 내에서 자신의 컨텍스트에서 부작업을 수행하고 요약을 반환하는 위임된 작업자 | 부작업이 검색 결과, 로그 또는 다시 참조하지 않을 파일 내용으로 주 대화를 넘칠 때 |

14| [에이전트 뷰](/ko/agent-view) | `claude agents`로 열 수 있는 백그라운드에서 실행 중인 세션을 디스패치하고 모니터링하는 하나의 화면. 연구 미리보기 | 여러 개의 독립적인 작업이 있고 작업을 넘기고, 상태를 한눈에 확인하고, 필요할 때만 개입하고 싶을 때 |14| [에이전트 뷰](/ko/agent-view) | `claude agents`로 열 수 있는 백그라운드에서 실행 중인 세션을 디스패치하고 모니터링하는 하나의 화면. 연구 미리보기 | 여러 개의 독립적인 작업이 있고 작업을 넘기고, 상태를 한눈에 확인하고, 필요할 때만 개입하고 싶을 때 |

15| [에이전트 팀](/ko/agent-teams) | 공유 작업 목록과 에이전트 간 메시징을 통해 조율되는 여러 세션으로, 리더가 관리합니다. 실험적이며 기본적으로 비활성화됨 | Claude가 프로젝트를 여러 부분으로 나누고, 할당하고, 작업자들을 동기화 상태로 유지하기를 원할 때 |15| [에이전트 팀](/ko/agent-teams) | 공유 작업 목록과 에이전트 간 메시징을 통해 조율되는 여러 세션으로, 리더가 관리합니다. 실험적이며 기본적으로 비활성화됨 | Claude가 프로젝트를 여러 부분으로 나누고, 할당하고, 작업자들을 동기화 상태로 유지하기를 원할 때 |

16| [동적 워크플로우](/ko/workflows) | 많은 서브에이전트를 실행하고 그 결과를 확인하는 스크립트로, 한 번에 조율하기에는 너무 큰 작업용입니다. 연구 미리보기 | 작업이 너무 커서 소수의 서브에이전트로는 조율할 수 없을 때: 코드베이스 전체 감사, 500개 파일 마이그레이션, 또는 적대적 검증이 필요한 연구 |16| [동적 워크플로우](/ko/workflows) | 많은 서브에이전트를 실행하고 그 결과를 교차 검증하는 스크립트로, 한 번에 조율하기에는 너무 큰 작업용입니다. 번의 패스 이상이 필요한 작업용입니다 | 작업이 소수의 서브에이전트로는 조율할 수 없을 때, 또는 결과를 서로 검증하고 싶을 때: 코드베이스 전체 감사, 500개 파일 마이그레이션, 교차 검증된 연구, 또는 여러 각도에서 작성된 계획 |

17 17 

18모든 접근 방식에서 작업자는 Claude 세션입니다. 다른 도구를 포함하려면 [MCP 서버](/ko/mcp)로 Claude에 노출하세요.18모든 접근 방식에서 작업자는 Claude 세션입니다. 다른 도구를 포함하려면 [MCP 서버](/ko/mcp)로 Claude에 노출하세요.

19 19 


63 더 알아보기63 더 알아보기

64</h2>64</h2>

65 65 

66아래의 가이드는 하나의 접근 방식에 대한 설정 및 구성을 다룹니다:66가이드 아래는 하나의 접근 방식에 대한 설정 및 구성을 다룹니다:

67 67 

68* [사용자 정의 서브에이전트 생성](/ko/sub-agents): 재사용 가능한 전문가를 정의하고 사용할 수 있는 도구를 제어합니다.68* [사용자 정의 서브에이전트 생성](/ko/sub-agents): 재사용 가능한 전문가를 정의하고 사용할 수 있는 도구를 제어합니다.

69* [에이전트 뷰로 에이전트 관리](/ko/agent-view): 세션을 디스패치하고, 상태를 감시하고, 필요할 때 연결합니다.69* [에이전트 뷰로 에이전트 관리](/ko/agent-view): 세션을 디스패치하고, 상태를 감시하고, 필요할 때 연결합니다.

Details

6 6 

7> Amazon Bedrock을 통한 Claude Code 구성, 설정, IAM 구성 및 문제 해결에 대해 알아봅니다.7> Amazon Bedrock을 통한 Claude Code 구성, 설정, IAM 구성 및 문제 해결에 대해 알아봅니다.

8 8 

9export const ContactSalesCard = ({surface}) => {

10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;

11 const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

12 <line x1="5" y1="12" x2="19" y2="12" />

13 <polyline points="12 5 19 12 12 19" />

14 </svg>;

15 const STYLES = `

16.cc-cs {

17 --cs-slate: #141413;

18 --cs-clay: #d97757;

19 --cs-clay-deep: #c6613f;

20 --cs-gray-000: #ffffff;

21 --cs-gray-700: #3d3d3a;

22 --cs-border-default: rgba(31, 30, 29, 0.15);

23 font-family: inherit;

24}

25.dark .cc-cs {

26 --cs-slate: #f0eee6;

27 --cs-gray-000: #262624;

28 --cs-gray-700: #bfbdb4;

29 --cs-border-default: rgba(240, 238, 230, 0.14);

30}

31.cc-cs-card {

32 display: flex; align-items: center; justify-content: space-between;

33 gap: 16px; padding: 14px 16px; margin: 0;

34 background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default);

35 border-radius: 8px; flex-wrap: wrap;

36}

37.cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; }

38.cc-cs-text strong { font-weight: 550; color: var(--cs-slate); }

39.cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }

40.cc-cs-btn-clay {

41 display: inline-flex; align-items: center; gap: 8px;

42 background: var(--cs-clay-deep); color: #fff; border: none;

43 border-radius: 8px; padding: 8px 14px;

44 font-size: 13px; font-weight: 500;

45 transition: background-color 0.15s; white-space: nowrap;

46}

47.cc-cs-btn-clay:hover { background: var(--cs-clay); }

48.cc-cs-btn-ghost {

49 display: inline-flex; align-items: center; gap: 8px;

50 background: transparent; color: var(--cs-gray-700);

51 border: 0.5px solid var(--cs-border-default);

52 border-radius: 8px; padding: 8px 14px;

53 font-size: 13px; font-weight: 500;

54}

55.cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }

56.dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); }

57@media (max-width: 720px) {

58 .cc-cs-actions { width: 100%; }

59}

60`;

61 return <div className="cc-cs not-prose">

62 <style>{STYLES}</style>

63 <div className="cc-cs-card">

64 <div className="cc-cs-text">

65 <strong>Deploying Claude Code across your organization?</strong> Talk to sales about enterprise plans, SSO, and centralized billing.

66 </div>

67 <div className="cc-cs-actions">

68 <a href={`https://claude.com/pricing?${utm('view_plans')}#plans-business`} className="cc-cs-btn-ghost">

69 View plans

70 </a>

71 <a href={`https://claude.com/contact-sales?${utm('contact_sales')}`} className="cc-cs-btn-clay">

72 Contact sales {iconArrowRight()}

73 </a>

74 </div>

75 </div>

76 </div>;

77};

78 

79<ContactSalesCard surface="bedrock" />

80 

9<h2 id="prerequisites">81<h2 id="prerequisites">

10 필수 조건82 필수 조건

11</h2>83</h2>


45 수동으로 설정117 수동으로 설정

46</h2>118</h2>

47 119 

48예를 들어 CI 또는 스크립트된 엔터프라이즈 롤아웃에서 마법사 대신 환경 변수를 통해 Bedrock을 구성하려면 아래 단계를 따르십시오.120마법사 대신 환경 변수를 통해 Bedrock을 구성하려면(예: CI 또는 스크립트된 엔터프라이즈 롤아웃에서), 아래 단계를 따르십시오.

49 121 

50<h3 id="1-submit-use-case-details">122<h3 id="1-submit-use-case-details">

51 1. 사용 사례 세부 정보 제출123 1. 사용 사례 세부 정보 제출


141 "Credentials": {213 "Credentials": {

142 "AccessKeyId": "value",214 "AccessKeyId": "value",

143 "SecretAccessKey": "value",215 "SecretAccessKey": "value",

144 "SessionToken": "value"216 "SessionToken": "value",

217 "Expiration": "2026-01-01T00:00:00Z"

145 }218 }

146}219}

147```220```

148 221 

222`Expiration`은 선택 사항입니다. {/* min-version: 2.1.176 */}Claude Code v2.1.176부터 명령이 유효한 ISO 8601 `Expiration`을 반환하면 Claude Code는 해당 시간 5분 전까지 자격 증명을 캐시합니다. 이것이 없거나 이전 버전에서는 자격 증명이 1시간 동안 캐시됩니다.

223 

149<h3 id="3-configure-claude-code">224<h3 id="3-configure-claude-code">

150 3. Claude Code 구성225 3. Claude Code 구성

151</h3>226</h3>


155```bash theme={null}230```bash theme={null}

156# Bedrock 통합 활성화231# Bedrock 통합 활성화

157export CLAUDE_CODE_USE_BEDROCK=1232export CLAUDE_CODE_USE_BEDROCK=1

158export AWS_REGION=us-east-1 # 또는 선호하는 지역233export AWS_REGION=us-east-1 # AWS 프로필이 이미 지역을 설정한 경우 선택 사항

159 234 

160# 선택 사항: 소형/빠른 모델(Bedrock 및 Mantle)의 AWS 지역 재정의235# 선택 사항: 소형/빠른 모델(Bedrock 및 Mantle)의 AWS 지역 재정의

161# Bedrock에서는 ANTHROPIC_DEFAULT_HAIKU_MODEL236# Bedrock에서는 ANTHROPIC_DEFAULT_HAIKU_MODEL


168 243 

169Claude Code에 대해 Bedrock을 활성화할 때 다음을 염두에 두십시오:244Claude Code에 대해 Bedrock을 활성화할 때 다음을 염두에 두십시오:

170 245 

171* `AWS_REGION`은 필수 환경 변수입니다. Claude Code는 설정에 대해 `.aws` 구성 파일을 읽지 않습니다.246* {/* min-version: 2.1.172 */}v2.1.172부터 AWS 프로필의 지역을 재정의하거나 프로필에 지역이 없을 때만 `AWS_REGION` 설정하면 됩니다. Claude Code는 다음 순서로 지역을 확인합니다:

247 

248 * `AWS_REGION`

249 * `AWS_DEFAULT_REGION`

250 * AWS 공유 자격 증명 파일에서 먼저 읽은 다음 공유 구성 파일에서 읽은 활성 AWS 프로필에 설정된 `region`(AWS SDK 우선순위와 일치)

251 * `us-east-1`

252 

253 활성 프로필은 설정된 경우 `AWS_PROFILE`이고, 그렇지 않으면 `default`입니다. `AWS_SHARED_CREDENTIALS_FILE` 또는 `AWS_CONFIG_FILE`을 설정하여 기본이 아닌 파일 경로를 가리킵니다. `/status`를 실행하여 확인된 지역을 확인하십시오. 지역이 AWS 구성 파일 또는 기본 폴백에서 나온 경우 `/status`도 소스를 표시합니다. v2.1.171 이전에서는 Claude Code가 AWS 구성 파일을 읽지 않으므로 `AWS_REGION`을 명시적으로 설정하십시오.

172* Bedrock을 사용할 때 `/logout` 명령은 AWS 자격 증명을 통해 인증이 처리되므로 사용할 수 없습니다.254* Bedrock을 사용할 때 `/logout` 명령은 AWS 자격 증명을 통해 인증이 처리되므로 사용할 수 없습니다.

173* WebSearch 도구는 Bedrock에서 사용할 수 없습니다. [WebSearch 도구 동작](/ko/tools-reference#websearch-tool-behavior)을 참조하십시오.255* WebSearch 도구는 Bedrock에서 사용할 수 없습니다. [WebSearch 도구 동작](/ko/tools-reference#websearch-tool-behavior)을 참조하십시오.

174* 다른 프로세스에 유출되지 않도록 하려는 `AWS_PROFILE`과 같은 환경 변수에 설정 파일을 사용할 수 있습니다. 자세한 내용은 [설정](/ko/settings)을 참조하십시오.256* 다른 프로세스에 유출되지 않도록 하려는 `AWS_PROFILE`과 같은 환경 변수에 설정 파일을 사용할 수 있습니다. 자세한 내용은 [설정](/ko/settings)을 참조하십시오.


178</h3>260</h3>

179 261 

180<Warning>262<Warning>

181 여러 사용자에게 배포할 때 특정 모델 버전을 고정하십시오. 고정하지 않으면 `sonnet` 및 `opus`와 같은 모델 별칭이 최신 버전으로 확인되며, Anthropic이 업데이트를 출시할 Bedrock 계정에서 아직 사용할 수 없을 수 있습니다. Claude Code는 [시작 시](#startup-model-checks) 최신 버전을 사용할 수 없을 때 이전 버전으로 폴백하지만, 고정하면 사용자가 새 모델로 이동하는 시기를 제어할 수 있습니다.263 여러 사용자에게 배포할 때 특정 모델 버전을 고정하십시오. 고정하지 않으면 `sonnet` 및 `opus`와 같은 모델 별칭이 Claude Code의 Bedrock용 기본 제공 기본값으로 확인되며, 이는 최신 릴리스보다 뒤떨어질 있고 계정에서 아직 사용할 수 없을 수 있습니다. Claude Code는 기본값을 사용할 수 없을 때 [시작 시](#startup-model-checks) 이전 버전으로 폴백하지만, 고정하면 사용자가 새 모델로 이동하는 시기를 제어할 수 있습니다.

182</Warning>264</Warning>

183 265 

184이러한 환경 변수를 특정 Bedrock 모델 ID로 설정하십시오.266이러한 환경 변수를 특정 Bedrock 모델 ID로 설정하십시오.


191export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'273export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

192```274```

193 275 

194이러한 변수는 교차 지역 추론 프로필 ID(`us.` 접두사 포함)를 사용합니다. 다른 지역 접두사 또는 애플리케이션 추론 프로필을 사용하는 경우 적절히 조정하십시오. 현재 및 레거시 모델 ID는 [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview)를 참조하십시오. 전체 환경 변수 목록은 [모델 구성](/ko/model-config#pin-models-for-third-party-deployments)을 참조하십시오.276이러한 변수는 교차 지역 추론 프로필 ID(`us.` 접두사 포함)를 사용합니다. 다른 지역 접두사 또는 애플리케이션 추론 프로필을 사용하는 경우 적절히 조정하십시오. AWS GovCloud 지역에서는 `us-gov.` 접두사를 사용하십시오. 현재 및 레거시 모델 ID는 [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview)를 참조하십시오. 전체 환경 변수 목록은 [모델 구성](/ko/model-config#pin-models-for-third-party-deployments)을 참조하십시오.

195 277 

196고정 변수가 설정되지 않은 경우 Claude Code는 이러한 기본 모델을 사용합니다:278고정 변수가 설정되지 않은 경우 Claude Code는 이러한 기본 모델을 사용합니다:

197 279 


366export AWS_REGION=us-east-1448export AWS_REGION=us-east-1

367```449```

368 450 

369Claude Code는 `AWS_REGION`에서 엔드포인트 URL을 구성합니다. 사용자 정의 엔드포인트 또는 게이트웨이를 위해 재정의하려면 `ANTHROPIC_BEDROCK_MANTLE_BASE_URL`을 설정하십시오.451Claude Code는 AWS 지역에서 엔드포인트 URL을 구성합니다. {/* min-version: 2.1.172 */}v2.1.172부터 지역은 [위의 Bedrock](#3-configure-claude-code)과 동일한 우선순위로 해결되며, 이전 버전은 `AWS_REGION`만 사용합니다. 사용자 정의 엔드포인트 또는 게이트웨이를 위해 URL을 재정의하려면 `ANTHROPIC_BEDROCK_MANTLE_BASE_URL`을 설정하십시오.

370 452 

371Claude Code 내에서 `/status`를 실행하여 확인하십시오. Mantle이 활성화되면 제공자 줄에 `Amazon Bedrock (Mantle)`이 표시됩니다.453Claude Code 내에서 `/status`를 실행하여 확인하십시오. Mantle이 활성화되면 제공자 줄에 `Amazon Bedrock (Mantle)`이 표시됩니다.

372 454 

Details

136* **새로고침 간격**: 기본적으로 `apiKeyHelper`는 5분 후 또는 HTTP 401 응답 시 호출됩니다. 사용자 정의 새로고침 간격을 위해 `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` 환경 변수를 설정합니다.136* **새로고침 간격**: 기본적으로 `apiKeyHelper`는 5분 후 또는 HTTP 401 응답 시 호출됩니다. 사용자 정의 새로고침 간격을 위해 `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` 환경 변수를 설정합니다.

137* **느린 도우미 알림**: `apiKeyHelper`가 키를 반환하는 데 10초 이상 걸리면 Claude Code는 경과 시간을 표시하는 프롬프트 표시줄에 경고 알림을 표시합니다. 이 알림이 정기적으로 표시되면 자격증명 스크립트를 최적화할 수 있는지 확인합니다.137* **느린 도우미 알림**: `apiKeyHelper`가 키를 반환하는 데 10초 이상 걸리면 Claude Code는 경과 시간을 표시하는 프롬프트 표시줄에 경고 알림을 표시합니다. 이 알림이 정기적으로 표시되면 자격증명 스크립트를 최적화할 수 있는지 확인합니다.

138 138 

139`apiKeyHelper`, `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`은 터미널 CLI 세션에만 적용됩니다. Claude Desktop 및 원격 세션은 OAuth를 독점적으로 사용하며 `apiKeyHelper`를 호출하거나 API 키 환경 변수를 읽지 않습니다.139`apiKeyHelper`, `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`은 터미널 CLI 세션에만 적용됩니다. Claude Desktop 및 클라우드 세션은 OAuth를 독점적으로 사용하며 `apiKeyHelper`를 호출하거나 API 키 환경 변수를 읽지 않습니다.

140 140 

141<h3 id="authentication-precedence">141<h3 id="authentication-precedence">

142 인증 우선순위142 인증 우선순위

Details

33신뢰할 수 있는 인프라나 조직 전체 거부 규칙과 같이 여러 프로젝트에 적용되는 규칙의 경우 `autoMode` 설정 블록을 사용하세요. 분류기는 다음 범위에서 `autoMode`를 읽습니다:33신뢰할 수 있는 인프라나 조직 전체 거부 규칙과 같이 여러 프로젝트에 적용되는 규칙의 경우 `autoMode` 설정 블록을 사용하세요. 분류기는 다음 범위에서 `autoMode`를 읽습니다:

34 34 

35| 범위 | 파일 | 용도 |35| 범위 | 파일 | 용도 |

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

37| 한 명의 개발자 | `~/.claude/settings.json` | 개인 신뢰할 수 있는 인프라 |37| 한 명의 개발자 | `~/.claude/settings.json` | 개인 신뢰할 수 있는 인프라 |

38| 한 프로젝트, 한 명의 개발자 | `.claude/settings.local.json` | 프로젝트별 신뢰할 수 있는 버킷 또는 서비스, gitignored |38| 한 프로젝트, 한 명의 개발자 | `.claude/settings.local.json` | 프로젝트별 신뢰할 수 있는 버킷 또는 서비스 |

39| 조직 전체 | [관리 설정](/ko/server-managed-settings) | 모든 개발자에게 배포된 신뢰할 수 있는 인프라 |39| 조직 전체 | [관리 설정](/ko/server-managed-settings) | 모든 개발자에게 배포된 신뢰할 수 있는 인프라 |

40| `--settings` 플래그 또는 Agent SDK | 인라인 JSON | 자동화를 위한 호출별 재정의 |40| `--settings` 플래그 또는 Agent SDK | 인라인 JSON | 자동화를 위한 호출별 재정의 |

41 41 

channels.md +4 −4

Details

269 </Step>269 </Step>

270</Steps>270</Steps>

271 271 

272Claude가 터미널에서 멀리 있을 때 권한 프롬프트에 도달하면 세션이 응답할 때까지 일시 중지됩니다. [권한 릴레이 기능](/ko/channels-reference#relay-permission-prompts)을 선언하는 채널 서버는 이러한 프롬프트를 사용자에게 전달하여 원격으로 승인하거나 거부할 수 있습니다. 무인 사용의 경우 [`--dangerously-skip-permissions`](/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)는 프롬프트를 완전히 우회하지만 신뢰하는 환경에서만 사용하세요.272Claude가 터미널에서 멀리 있을 때 권한 프롬프트에 도달하면 세션이 응답할 때까지 일시 중지됩니다. [권한 릴레이 기능](/ko/channels-reference#relay-permission-prompts)을 선언하는 채널 서버는 이러한 프롬프트를 사용자에게 전달하여 원격으로 승인하거나 거부할 수 있습니다. 무인 사용의 경우 [`--dangerously-skip-permissions`](/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)는 명시적 요청 규칙 이외의 프롬프트를 우회하지만 신뢰하는 환경에서만 사용하세요.

273 273 

274비대화형 모드에서 `-p`로 채널을 실행할 때 여러 선택지 질문 및 계획 모드 승인과 같이 터미널 입력이 필요한 도구는 비활성화되므로 세션이 입력을 기다리며 멈추지 않습니다.274비대화형 모드에서 `-p`로 채널을 실행할 때 여러 선택지 질문 및 계획 모드 승인과 같이 터미널 입력이 필요한 도구는 비활성화되므로 세션이 입력을 기다리며 멈추지 않습니다.

275 275 


377 377 

378채널이 실행 중이면 다음 관련 기능을 살펴보세요:378채널이 실행 중이면 다음 관련 기능을 살펴보세요:

379 379 

380* [자신의 채널 구축](/ko/channels-reference): 아직 플러그인이 없는 시스템의 경우380* [자신의 채널 구축](/ko/channels-reference) - 아직 플러그인이 없는 시스템의 경우

381* [Remote Control](/ko/remote-control): 이벤트를 전달하는 대신 휴대폰에서 로컬 세션을 운전하기381* [Remote Control](/ko/remote-control) - 이벤트를 전달하는 대신 휴대폰에서 로컬 세션을 운전하기

382* [예약된 작업](/ko/scheduled-tasks): 푸시된 이벤트에 반응하는 대신 타이머에서 폴링하기382* [예약된 작업](/ko/scheduled-tasks) - 푸시된 이벤트에 반응하는 대신 타이머에서 폴링하기

Details

116 116 

117 파일은 순서대로 세 가지를 수행합니다:117 파일은 순서대로 세 가지를 수행합니다:

118 118 

119 * **서버 구성**: 기능에 `claude/channel`이 있는 MCP 서버를 생성합니다. 이것이 Claude Code에 이것이 채널임을 알려줍니다. [`instructions`](#server-options) 문자열은 Claude의 시스템 프롬프트로 이동합니다: Claude에 예상할 이벤트, 회신 여부, 회신해야 하는 경우 사용할 도구 및 전달할 속성(예: `chat_id`)을 알려줍니다.119 * **서버 구성**: 기능에 `claude/channel`이 있는 MCP 서버를 생성합니다. 이것이 Claude Code에 이것이 채널임을 알려줍니다. [`instructions`](#server-options) 문자열은 Claude의 시스템 프롬프트로 이동합니다: Claude에 예상할 이벤트, 회신 여부, 회신해야 하는 경우 회신을 라우팅하는 방법을 알려줍니다.

120 * **Stdio 연결**: stdin/stdout을 통해 Claude Code에 연결합니다. 이는 모든 [MCP 서버](https://modelcontextprotocol.io/docs/concepts/transports#standard-io)에 표준입니다: Claude Code가 이를 서브프로세스로 생성합니다.120 * **Stdio 연결**: stdin/stdout을 통해 Claude Code에 연결합니다. 이는 모든 [MCP 서버](https://modelcontextprotocol.io/docs/concepts/transports#standard-io)에 표준입니다: Claude Code가 이를 서브프로세스로 생성합니다.

121 * **HTTP 리스너**: 포트 8788에서 로컬 웹 서버를 시작합니다. 모든 POST 본문은 `mcp.notification()`을 통해 채널 이벤트로 Claude로 전달됩니다. `content`는 이벤트 본문이 되고 각 `meta` 항목은 `<channel>` 태그의 속성이 됩니다. 리스너는 `mcp` 인스턴스에 액세스해야 하므로 동일한 프로세스에서 실행됩니다. 더 큰 프로젝트의 경우 별도의 모듈로 분할할 수 있습니다.121 * **HTTP 리스너**: 포트 8788에서 로컬 웹 서버를 시작합니다. 모든 POST 본문은 `mcp.notification()`을 통해 채널 이벤트로 Claude로 전달됩니다. `content`는 이벤트 본문이 되고 각 `meta` 항목은 `<channel>` 태그의 속성이 됩니다. 리스너는 `mcp` 인스턴스에 액세스해야 하므로 동일한 프로세스에서 실행됩니다. 더 큰 프로젝트의 경우 별도의 모듈로 분할할 수 있습니다.

122 </Step>122 </Step>


142 claude --dangerously-load-development-channels server:webhook142 claude --dangerously-load-development-channels server:webhook

143 ```143 ```

144 144 

145 이 프로젝트에서 처음으로 세션을 시작할 때 Claude Code는 `.mcp.json`의 새 서버를 사용하기 전에 동의를 요청합니다. 대화 상자는 "이 프로젝트에서 새 MCP 서버를 찾음: webhook"을 보고합니다. **이 MCP 서버 사용**을 선택하여 계속합니다.

146 

145 Claude Code가 시작되면 MCP 구성을 읽고 `webhook.ts`를 서브프로세스로 생성하며 구성한 포트(이 예제에서는 8788)에서 HTTP 리스너가 자동으로 시작됩니다. 서버를 직접 실행할 필요가 없습니다.147 Claude Code가 시작되면 MCP 구성을 읽고 `webhook.ts`를 서브프로세스로 생성하며 구성한 포트(이 예제에서는 8788)에서 HTTP 리스너가 자동으로 시작됩니다. 서버를 직접 실행할 필요가 없습니다.

146 148 

149 시작 배너 아래의 흐린 공지는 채널이 등록되었음을 확인합니다: `Channels (experimental) messages from server:webhook inject directly in this session · restart without --dangerously-load-development-channels to stop`.

150 

147 "조직 정책에 의해 차단됨"이 표시되면 조직 관리자가 먼저 [채널을 활성화](/ko/channels#enterprise-controls)해야 합니다.151 "조직 정책에 의해 차단됨"이 표시되면 조직 관리자가 먼저 [채널을 활성화](/ko/channels#enterprise-controls)해야 합니다.

148 152 

149 별도의 터미널에서 HTTP POST를 메시지와 함께 서버로 보내 웹훅을 시뮬레이션합니다. 이 예제는 CI 실패 알림을 포트 8788로 보냅니다 (또는 구성한 포트):153 별도의 터미널에서 HTTP POST를 메시지와 함께 서버로 보내 웹훅을 시뮬레이션합니다. 이 예제는 CI 실패 알림을 포트 8788로 보냅니다 (또는 구성한 포트):


753curl -d "list the files in this directory" -H "X-Sender: dev" localhost:8788757curl -d "list the files in this directory" -H "X-Sender: dev" localhost:8788

754```758```

755 759 

756로컬 권한 대화가 Claude Code 터미널에서 열립니다. 잠시 후 프롬프트가 `/events` 스트림에 나타나며 5자 ID를 포함합니다. 원격 측에서 승인합니다:760파일 나열은 읽기 전용이므로 Claude는 승인 없이 실행합니다. 권한 대화는 Claude가 `reply` 도구를 호출하여 답변을 다시 보낼 때 열립니다. 로컬 대화가 Claude Code 터미널에서 열립니다. 잠시 후 프롬프트가 `/events` 스트림에 나타나며 5자 ID를 포함합니다. 원격 측에서 승인합니다:

757 761 

758```bash theme={null}762```bash theme={null}

759curl -d "yes <id>" -H "X-Sender: dev" localhost:8788763curl -d "yes <id>" -H "X-Sender: dev" localhost:8788

760```764```

761 765 

762로컬 대화가 닫히고 도구가 실행됩니다. Claude의 회신은 `reply` 도구를 통해 돌아오고 스트림에도 도착합니다.766로컬 대화가 닫히고 `reply` 도구가 실행되며 Claude의 회신이 스트림에 도착합니다.

763 767 

764이 파일의 3개의 채널 특정 부분:768이 파일의 3개의 채널 특정 부분:

765 769 


773 777 

774채널을 설치 가능하고 공유 가능하게 하려면 [플러그인](/ko/plugins)으로 래핑하고 [마켓플레이스](/ko/plugin-marketplaces)에 게시합니다. 사용자는 `/plugin install`로 설치한 다음 `--channels plugin:<name>@<marketplace>`로 세션별로 활성화합니다.778채널을 설치 가능하고 공유 가능하게 하려면 [플러그인](/ko/plugins)으로 래핑하고 [마켓플레이스](/ko/plugin-marketplaces)에 게시합니다. 사용자는 `/plugin install`로 설치한 다음 `--channels plugin:<name>@<marketplace>`로 세션별로 활성화합니다.

775 779 

776자신의 마켓플레이스에 게시된 채널은 [승인된 허용 목록](/ko/channels#supported-channels)에 없으므로 여전히 `--dangerously-load-development-channels`를 실행해야 합니다. 공식 마켓플레이스에 추가되려면 [공식 마켓플레이스에 제출](/ko/plugins#submit-your-plugin-to-the-official-marketplace)합니다. 채널 플러그인은 승인되기 전에 보안 검토를 거칩니다. 팀 및 엔터프라이즈 계획에서 관리자는 대신 조직의 자신의 [`allowedChannelPlugins`](/ko/channels#restrict-which-channel-plugins-can-run) 목록에 플러그인을 포함할 있으며, 이는 기본 Anthropic 허용 목록을 대체합니다.780자신의 마켓플레이스에 게시된 채널은 [승인된 허용 목록](/ko/channels#supported-channels)에 없으므로 여전히 `--dangerously-load-development-channels`를 실행해야 합니다. 기본 허용 목록은 `claude-plugins-official`의 채널 플러그인이며, Anthropic이 재량에 따라 관리합니다. [인앱 제출 양식](/ko/plugins#submit-your-plugin-to-the-community-marketplace) 플러그인을 커뮤니티 마켓플레이스에 추가하며, 이는 채널 허용 목록에 없습니다.

781 

782Anthropic 파트너 담당자와 함께 작업 중인 경우 공식 마켓플레이스 목록을 조정하기 위해 연락합니다. Team 및 Enterprise 계획에서 관리자는 대신 조직의 자신의 [`allowedChannelPlugins`](/ko/channels#restrict-which-channel-plugins-can-run) 목록에 플러그인을 포함할 수 있으며, 이는 기본 Anthropic 허용 목록을 대체합니다.

777 783 

778<h2 id="see-also">784<h2 id="see-also">

779 참고 항목785 참고 항목

chrome.md +1 −1

Details

264 참고 항목264 참고 항목

265</h2>265</h2>

266 266 

267* [컴퓨터 사용](/ko/computer-use): 브라우저에서 작업을 수행할 수 없을 때 네이티브 macOS 앱을 제어합니다.267* [컴퓨터 사용](/ko/computer-use): 브라우저에서 작업을 수행할 수 없을 때 네이티브 macOS 앱을 제어합니다

268* [VS Code에서 Claude Code 사용](/ko/vs-code#automate-browser-tasks-with-chrome): VS Code 확장 프로그램의 브라우저 자동화268* [VS Code에서 Claude Code 사용](/ko/vs-code#automate-browser-tasks-with-chrome): VS Code 확장 프로그램의 브라우저 자동화

269* [CLI 참조](/ko/cli-reference): `--chrome`을 포함한 명령줄 플래그269* [CLI 참조](/ko/cli-reference): `--chrome`을 포함한 명령줄 플래그

270* [일반적인 워크플로우](/ko/common-workflows): Claude Code를 사용하는 더 많은 방법270* [일반적인 워크플로우](/ko/common-workflows): Claude Code를 사용하는 더 많은 방법

Details

59 59 

60각 세션은 저장소가 복제된 새로운 Anthropic 관리 VM에서 실행됩니다. 이 섹션에서는 세션이 시작될 때 사용 가능한 것과 이를 사용자 정의하는 방법을 다룹니다.60각 세션은 저장소가 복제된 새로운 Anthropic 관리 VM에서 실행됩니다. 이 섹션에서는 세션이 시작될 때 사용 가능한 것과 이를 사용자 정의하는 방법을 다룹니다.

61 61 

62<h3 id="what-s-available-in-cloud-sessions">62<h3 id="whats-available-in-cloud-sessions">

63 클라우드 세션에서 사용 가능한 것63 클라우드 세션에서 사용 가능한 것

64</h3>64</h3>

65 65 

66클라우드 세션은 저장소의 새로운 복제본에서 시작됩니다. 저장소에 커밋된 모든 것이 사용 가능합니다. 자신의 머신에만 설치하거나 구성한 것은 사용할 수 없습니다.66클라우드 세션은 저장소의 새로운 복제본에서 시작됩니다. 저장소에 커밋된 모든 것이 사용 가능합니다. 자신의 머신에만 설치하거나 구성한 것은 사용할 수 없습니다.

67 67 

68| | 클라우드 세션에서 사용 가능 | 이유 |68| | 클라우드 세션에서 사용 가능 | 이유 |

69| :------------------------------------------------------------- | :-------------- | :-------------------------------------------------------------------------------------------- |69| :------------------------------------------------------------------ | :-------------- | :--------------------------------------------------------------------------------------------- |

70| 저장소의 `CLAUDE.md` | 예 | 복제본의 일부 |70| 저장소의 `CLAUDE.md` | 예 | 복제본의 일부 |

71| 저장소의 `.claude/settings.json` hooks | 예 | 복제본의 일부 |71| 저장소의 `.claude/settings.json` hooks | 예 | 복제본의 일부 |

72| 저장소의 `.mcp.json` MCP 서버 | 예 | 복제본의 일부 |72| 저장소의 `.mcp.json` MCP 서버 | 예 | 복제본의 일부 |


74| 저장소의 `.claude/skills/`, `.claude/agents/`, `.claude/commands/` | 예 | 복제본의 일부 |74| 저장소의 `.claude/skills/`, `.claude/agents/`, `.claude/commands/` | 예 | 복제본의 일부 |

75| `.claude/settings.json`에 선언된 플러그인 | 예 | 선언한 [마켓플레이스](/ko/plugin-marketplaces)에서 세션 시작 시 설치됩니다. 마켓플레이스 소스에 도달하려면 네트워크 액세스가 필요합니다 |75| `.claude/settings.json`에 선언된 플러그인 | 예 | 선언한 [마켓플레이스](/ko/plugin-marketplaces)에서 세션 시작 시 설치됩니다. 마켓플레이스 소스에 도달하려면 네트워크 액세스가 필요합니다 |

76| 사용자 `~/.claude/CLAUDE.md` | 아니오 | 저장소가 아닌 머신에 있습니다 |76| 사용자 `~/.claude/CLAUDE.md` | 아니오 | 저장소가 아닌 머신에 있습니다 |

77| 사용자 `~/.claude/skills/`, `~/.claude/agents/`, `~/.claude/commands/` | 아니오 | 저장소가 아닌 머신에 있습니다. 대신 저장소의 `.claude/` 디렉토리에 커밋하세요. claude.ai에서 활성화한 Skills는 클라우드 세션에 자동으로 로드됩니다 |

77| 사용자 설정에서만 활성화된 플러그인 | 아니오 | 사용자 범위 `enabledPlugins`는 `~/.claude/settings.json`에 있습니다. 저장소의 `.claude/settings.json`에 선언하세요 |78| 사용자 설정에서만 활성화된 플러그인 | 아니오 | 사용자 범위 `enabledPlugins`는 `~/.claude/settings.json`에 있습니다. 저장소의 `.claude/settings.json`에 선언하세요 |

78| `claude mcp add`로 추가한 MCP 서버 | 아니오 | 저장소가 아닌 로컬 사용자 구성에 씁니다. [`.mcp.json`](/ko/mcp#project-scope)에 서버를 선언하세요 |79| `claude mcp add`로 추가한 MCP 서버 | 아니오 | 저장소가 아닌 로컬 사용자 구성에 씁니다. [`.mcp.json`](/ko/mcp#project-scope)에 서버를 선언하세요 |

79| 정적 API 토큰 및 자격 증명 | 아니오 | 아직 전용 비밀 저장소가 없습니다. 아래를 참조하세요 |80| 정적 API 토큰 및 자격 증명 | 아니오 | 아직 전용 비밀 저장소가 없습니다. 아래를 참조하세요 |


353* 악의적인 요청으로부터의 보호354* 악의적인 요청으로부터의 보호

354* 속도 제한 및 남용 방지355* 속도 제한 및 남용 방지

355* 향상된 보안을 위한 콘텐츠 필터링356* 향상된 보안을 위한 콘텐츠 필터링

357* 요청된 호스트명의 DNS 수준 감사 추적

356 358 

357<h3 id="default-allowed-domains">359<h3 id="default-allowed-domains">

358 기본 허용 도메인360 기본 허용 도메인


745| `/context` | 예 | 현재 컨텍스트 윈도우에 있는 것을 표시합니다 |747| `/context` | 예 | 현재 컨텍스트 윈도우에 있는 것을 표시합니다 |

746| `/clear` | 아니오 | 사이드바에서 새 세션을 시작하세요 |748| `/clear` | 아니오 | 사이드바에서 새 세션을 시작하세요 |

747 749 

748자동 압축은 컨텍스트 윈도우가 용량에 접근할 때 자동으로 실행되며, CLI와 동일합니다. 더 일찍 트리거하려면 [환경 변수](#configure-your-environment)에서 [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/ko/env-vars)를 설정하세요. 예를 들어 `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70`은 기본값 \~95% 대신 70% 용량에서 압축합니다. 압축 계산을 위한 유효 윈도우 크기를 변경하려면 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/ko/env-vars)를 사용하세요.750자동 압축은 컨텍스트 윈도우가 용량에 접근할 때 자동으로 실행됩니다. 더 일찍 트리거하려면 [환경 변수](#configure-your-environment)에서 [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/ko/env-vars)를 설정하세요. 예를 들어 `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70`은 윈도우가 거의 가득 찰 때까지 기다리는 대신 70% 용량에서 압축합니다. 압축 계산을 위한 유효 윈도우 크기를 변경하려면 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/ko/env-vars)를 사용하세요.

749 751 

750[Subagents](/ko/sub-agents)는 로컬과 동일한 방식으로 작동합니다. Claude는 Task 도구로 이들을 생성하여 연구 또는 병렬 작업을 별도의 컨텍스트 윈도우로 오프로드하여 주 대화를 더 가볍게 유지할 수 있습니다. 저장소의 `.claude/agents/`에 정의된 Subagents는 자동으로 선택됩니다. [Agent teams](/ko/agent-teams)는 기본적으로 꺼져 있지만 [환경 변수](#configure-your-environment)에 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`을 추가하여 활성화할 수 있습니다.752[Subagents](/ko/sub-agents)는 로컬과 동일한 방식으로 작동합니다. Claude는 Task 도구로 이들을 생성하여 연구 또는 병렬 작업을 별도의 컨텍스트 윈도우로 오프로드하여 주 대화를 더 가볍게 유지할 수 있습니다. 저장소의 `.claude/agents/`에 정의된 Subagents는 자동으로 선택됩니다. [Agent teams](/ko/agent-teams)는 기본적으로 꺼져 있지만 [환경 변수](#configure-your-environment)에 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`을 추가하여 활성화할 수 있습니다.

751 753 


868 870 

869* 로컬에서 `/login`을 실행하여 자격 증명을 새로 고친 다음 다시 연결하세요871* 로컬에서 `/login`을 실행하여 자격 증명을 새로 고친 다음 다시 연결하세요

870* 세션을 소유한 동일한 계정으로 로그인했는지 확인하세요872* 세션을 소유한 동일한 계정으로 로그인했는지 확인하세요

871* `Remote Control may not be available for this organization`이 표시되면 관리자가 계획에 대해 원격 세션을 활성화하지 않았습니다873* `Remote Control may not be available for this organization`이 표시되면 관리자가 계획에 대해 클라우드 세션을 활성화하지 않았습니다

872 874 

873<h3 id="environment-expired">875<h3 id="environment-expired">

874 환경 만료876 환경 만료

claude-directory.md +1427 −1

Details

6 6 

7> Claude Code가 CLAUDE.md, settings.json, hooks, skills, commands, subagents, workflows, rules, auto memory를 읽는 위치입니다. 프로젝트의 .claude 디렉토리와 홈 디렉토리의 ~/.claude를 탐색합니다.7> Claude Code가 CLAUDE.md, settings.json, hooks, skills, commands, subagents, workflows, rules, auto memory를 읽는 위치입니다. 프로젝트의 .claude 디렉토리와 홈 디렉토리의 ~/.claude를 탐색합니다.

8 8 

9export const ClaudeExplorer = () => {

10 const A = useMemo(() => ({href, children}) => <a href={href} style={{

11 color: 'var(--ce-accent)',

12 textDecoration: 'none',

13 borderBottom: '1px dotted var(--ce-accent)'

14 }}>{children}</a>, []);

15 const C = useMemo(() => ({children}) => <code style={{

16 fontFamily: 'var(--ce-mono)',

17 fontSize: '0.92em',

18 padding: '1px 4px',

19 borderRadius: '3px',

20 background: 'var(--ce-surface)',

21 border: '0.5px solid var(--ce-border-subtle)'

22 }}>{children}</code>, []);

23 const commandsNote = useMemo(() => <>Commands and skills are now the same mechanism. For new workflows, use <A href="/en/skills">skills/</A> instead: same <C>/name</C> invocation, plus you can bundle supporting files.</>, []);

24 const FILE_TREE = useMemo(() => ({

25 project: {

26 label: 'your-project/',

27 children: [{

28 id: 'claude-md',

29 label: 'CLAUDE.md',

30 type: 'file',

31 icon: 'md',

32 color: '#6A9BCC',

33 badge: 'committed',

34 oneLiner: 'Project instructions Claude reads every session',

35 when: 'Loaded into context at the start of every session',

36 description: 'Project-specific instructions that shape how Claude works in this repository. Put your conventions, common commands, and architectural context here so Claude operates with the same assumptions your team does.',

37 tips: ['Target under 200 lines. Longer files still load in full but may reduce adherence', <>CLAUDE.md loads into every session. If something only matters for specific tasks, move it to a <A href="/en/skills">skill</A> or a path-scoped <A href="/en/memory#organize-rules-with-claude/rules/">rule</A> so it loads only when needed</>, 'List the commands you run most, like build, test, and format, so Claude knows them without you spelling them out each time', <>Run <C>/memory</C> to open and edit CLAUDE.md from within a session</>, <>Also works at <C>.claude/CLAUDE.md</C> if you prefer to keep the project root clean</>],

38 exampleIntro: 'This example is for a TypeScript and React project. It lists the build and test commands, the framework conventions Claude should follow, and project-specific rules like export style and file layout.',

39 example: `# Project conventions

40 

41## Commands

42- Build: \`npm run build\`

43- Test: \`npm test\`

44- Lint: \`npm run lint\`

45 

46## Stack

47- TypeScript with strict mode

48- React 19, functional components only

49 

50## Rules

51- Named exports, never default exports

52- Tests live next to source: \`foo.ts\` -> \`foo.test.ts\`

53- All API routes return \`{ data, error }\` shape`,

54 docsLink: '/en/memory'

55 }, {

56 id: 'mcp-json',

57 label: '.mcp.json',

58 type: 'file',

59 icon: 'json',

60 color: '#9B7BC4',

61 badge: 'committed',

62 oneLiner: 'Project-scoped MCP servers, shared with your team',

63 when: <>Servers connect when the session begins. Tool schemas are deferred by default and load on demand via <A href="/en/mcp#scale-with-mcp-tool-search">tool search</A></>,

64 description: <>Configures Model Context Protocol (MCP) servers that give Claude access to external tools: databases, APIs, browsers, and more. This file holds the project-scoped servers your whole team uses. Personal servers you want to keep to yourself go in <C>~/.claude.json</C> instead.</>,

65 tips: [<>Use environment variable references for secrets: <C>{'${GITHUB_TOKEN}'}</C></>, <>Lives at the project root, not inside <C>.claude/</C></>, <>For servers only you need, run <C>claude mcp add --scope user</C>. This writes to <C>~/.claude.json</C> instead of <C>.mcp.json</C></>],

66 exampleIntro: <>This example configures the GitHub MCP server so Claude can read issues and open pull requests. The <C>{'${GITHUB_TOKEN}'}</C> reference is read from your shell environment when Claude Code starts the server, so the token never lands in the file.</>,

67 example: `{

68 "mcpServers": {

69 "github": {

70 "command": "npx",

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

72 "env": {

73 "GITHUB_TOKEN": "\${GITHUB_TOKEN}"

74 }

75 }

76 }

77}`,

78 docsLink: '/en/mcp'

79 }, {

80 id: 'worktreeinclude',

81 label: '.worktreeinclude',

82 type: 'file',

83 icon: 'md',

84 color: '#8FA876',

85 badge: 'committed',

86 oneLiner: 'Gitignored files to copy into new worktrees',

87 when: <>Read when Claude creates a git worktree via <C>--worktree</C>, the <C>EnterWorktree</C> tool, or subagent <C>isolation: worktree</C></>,

88 description: <>Lists gitignored files to copy from your main repository into each new worktree. Worktrees are fresh checkouts, so untracked files like <C>.env</C> are missing by default. Patterns here use <C>.gitignore</C> syntax. Only files that match a pattern and are also gitignored get copied, so tracked files are never duplicated.</>,

89 tips: [<>Lives at the project root, not inside <C>.claude/</C></>, <>Git-only: if you configure a <A href="/en/hooks#worktreecreate">WorktreeCreate hook</A> for a different VCS, this file is not read. Copy files inside your hook script instead</>, <>Also applies to parallel sessions in the <A href="/en/desktop#work-in-parallel-with-sessions">desktop app</A></>],

90 exampleIntro: 'This example copies your local environment files and a secrets config into every worktree Claude creates. Comments start with # and blank lines are ignored, same as .gitignore.',

91 example: `# Local environment

92.env

93.env.local

94 

95# API credentials

96config/secrets.json`,

97 docsLink: '/en/worktrees#copy-gitignored-files-into-worktrees'

98 }, {

99 id: 'dot-claude',

100 label: '.claude/',

101 type: 'folder',

102 icon: 'folder',

103 color: 'var(--ce-accent)',

104 oneLiner: 'Project-level configuration, rules, and extensions',

105 description: 'Everything Claude Code reads that is specific to this project. If you use git, commit most files here so your team shares them; a few, like settings.local.json, are automatically gitignored. Each file badge shows which.',

106 children: [{

107 id: 'settings-json',

108 label: 'settings.json',

109 type: 'file',

110 icon: 'json',

111 color: 'var(--ce-text-3)',

112 badge: 'committed',

113 oneLiner: 'Permissions, hooks, and configuration',

114 when: <>Overrides global <C>~/.claude/settings.json</C>. Local settings, CLI flags, and managed settings override this</>,

115 description: 'Settings that Claude Code applies directly. Permissions control which commands and tools Claude can use; hooks run your scripts at specific points in a session. Unlike CLAUDE.md, which Claude reads as guidance, these are enforced whether Claude follows them or not.',

116 contains: [<><A href="/en/permissions">permissions</A>: allow, deny, or prompt before Claude uses specific tools or commands</>, <><A href="/en/hooks">hooks</A>: run your own scripts on events like before a tool call or after a file edit</>, <><A href="/en/statusline">statusLine</A>: customize the line shown at the bottom while Claude works</>, <><A href="/en/settings#available-settings">model</A>: pick a default model for this project</>, <><A href="/en/settings#environment-variables">env</A>: environment variables set in every session</>, <><A href="/en/output-styles">outputStyle</A>: select a custom system-prompt style from output-styles/</>],

117 tips: [<>Bash permission patterns support wildcards: <C>Bash(npm test *)</C> matches any command starting with <C>npm test</C></>, <>Array settings like <C>permissions.allow</C> combine across all scopes; scalar settings like <C>model</C> use the most specific value</>],

118 exampleIntro: <>This example allows <C>npm test</C> and <C>npm run</C> commands without prompting, blocks <C>rm -rf</C>, and runs Prettier on files after Claude edits or writes them.</>,

119 example: `{

120 "permissions": {

121 "allow": [

122 "Bash(npm test *)",

123 "Bash(npm run *)"

124 ],

125 "deny": [

126 "Bash(rm -rf *)"

127 ]

128 },

129 "hooks": {

130 "PostToolUse": [{

131 "matcher": "Edit|Write",

132 "hooks": [{

133 "type": "command",

134 "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"

135 }]

136 }]

137 }

138}`,

139 docsLink: '/en/settings'

140 }, {

141 id: 'settings-local-json',

142 label: 'settings.local.json',

143 type: 'file',

144 icon: 'json',

145 color: 'var(--ce-text-3)',

146 badge: 'gitignored',

147 oneLiner: 'Your personal settings overrides for this project',

148 when: 'Highest of the user-editable settings files; CLI flags and managed settings still take precedence',

149 description: 'Personal settings that take precedence over the project defaults. Same JSON format as settings.json, but not committed. Use this when you need different permissions or defaults than the team config.',

150 tips: [<>Same schema as settings.json. Array settings like <C>permissions.allow</C> combine across scopes; scalar settings like <C>model</C> use the local value</>, <>Claude Code adds this file to <C>~/.config/git/ignore</C> the first time it writes one. If you use a custom <C>core.excludesFile</C>, add the pattern there too. To share the ignore rule with your team, also add it to the project <C>.gitignore</C></>],

151 exampleIntro: 'This example adds Docker permissions on top of whatever the team settings.json allows.',

152 example: `{

153 "permissions": {

154 "allow": [

155 "Bash(docker *)"

156 ]

157 }

158}`,

159 docsLink: '/en/settings'

160 }, {

161 id: 'rules',

162 label: 'rules/',

163 type: 'folder',

164 icon: 'folder',

165 color: '#9B7BC4',

166 oneLiner: 'Topic-scoped instructions, optionally gated by file paths',

167 when: <>Rules without <C>paths:</C> load at session start. Rules with <C>paths:</C> load when a matching file enters context</>,

168 description: [<>Project instructions split into topic files that can load conditionally based on file paths. A rule without <C>paths:</C> frontmatter loads at session start like CLAUDE.md; a rule with <C>paths:</C> loads only when Claude reads a matching file.</>, <>Like CLAUDE.md, rules are guidance Claude reads, not configuration Claude Code enforces. For guaranteed behavior use <A href="/en/hooks">hooks</A> or <A href="/en/permissions">permissions</A>.</>],

169 tips: [<>Use <C>paths:</C> frontmatter with globs to scope rules to directories or file types</>, <>Subdirectories work: <C>.claude/rules/frontend/react.md</C> is discovered automatically</>, 'When CLAUDE.md approaches 200 lines, start splitting into rules'],

170 docsLink: '/en/memory#organize-rules-with-claude/rules/',

171 children: [{

172 id: 'rule-testing',

173 label: 'testing.md',

174 type: 'file',

175 icon: 'md',

176 color: '#9B7BC4',

177 badge: 'committed',

178 oneLiner: 'Test conventions scoped to test files',

179 when: <>Loaded when Claude reads a file matching the <C>paths:</C> globs below</>,

180 description: <>An example rule that only loads when Claude is working on test files. The <C>paths:</C> globs in the frontmatter define which files trigger it; here, anything ending in .test.ts or .test.tsx. For other files, this rule is not loaded into context.</>,

181 example: `---

182paths:

183 - "**/*.test.ts"

184 - "**/*.test.tsx"

185---

186 

187# Testing Rules

188 

189- Use descriptive test names: "should [expected] when [condition]"

190- Mock external dependencies, not internal modules

191- Clean up side effects in afterEach`

192 }, {

193 id: 'rule-api',

194 label: 'api-design.md',

195 type: 'file',

196 icon: 'md',

197 color: '#9B7BC4',

198 badge: 'committed',

199 oneLiner: 'API conventions scoped to backend code',

200 when: <>Loaded when Claude reads a file matching the <C>paths:</C> glob below</>,

201 description: <>A second example showing a rule scoped to backend code. The <C>paths:</C> glob matches files under src/api/, so these conventions load only when Claude is editing API routes.</>,

202 example: `---

203paths:

204 - "src/api/**/*.ts"

205---

206 

207# API Design Rules

208 

209- All endpoints must validate input with Zod schemas

210- Return shape: { data: T } | { error: string }

211- Rate limit all public endpoints`

212 }]

213 }, {

214 id: 'skills',

215 label: 'skills/',

216 type: 'folder',

217 icon: 'folder',

218 color: '#D4A843',

219 oneLiner: 'Reusable prompts you or Claude invoke by name',

220 when: <>Invoked with <C>/skill-name</C> or when Claude matches the task to a skill</>,

221 description: <>Each skill is a folder with a SKILL.md file plus any supporting files it needs. By default, both you and Claude can invoke a skill. Use frontmatter to control that: <C>disable-model-invocation: true</C> for user-only workflows like <C>/deploy</C>, or <C>user-invocable: false</C> to hide from the <C>/</C> menu while Claude can still invoke it.</>,

222 tips: [<>Skills accept arguments: <C>/deploy staging</C> passes "staging" as <C>$ARGUMENTS</C>. Use <C>$0</C>, <C>$1</C>, and so on for positional access</>, <>The <C>description</C> frontmatter determines when Claude auto-invokes the skill</>, 'Bundle reference docs alongside SKILL.md. Claude knows the skill directory path and can read supporting files when you mention them'],

223 docsLink: '/en/skills',

224 children: [{

225 id: 'skill-review',

226 label: 'security-review/',

227 type: 'folder',

228 icon: 'folder',

229 color: '#D4A843',

230 oneLiner: 'A skill bundling SKILL.md with supporting files',

231 children: [{

232 id: 'skill-review-md',

233 label: 'SKILL.md',

234 type: 'file',

235 icon: 'md',

236 color: '#D4A843',

237 badge: 'committed',

238 oneLiner: 'Entrypoint: trigger, invocability, instructions',

239 when: <>User types <C>/security-review &lt;target&gt;</C>; Claude cannot auto-invoke this skill</>,

240 description: [<>This skill uses <C>disable-model-invocation: true</C> so only you can trigger it; Claude never invokes it on its own.</>, <>The <C>!`...`</C> line runs a shell command and injects its output into the prompt. <C>$ARGUMENTS</C> substitutes whatever you typed after the skill name. Claude sees the skill directory path, so mentioning a bundled file like checklist.md lets Claude read it.</>],

241 example: `---

242description: Reviews code changes for security vulnerabilities, authentication gaps, and injection risks

243disable-model-invocation: true

244argument-hint: <branch-or-path>

245---

246 

247## Diff to review

248 

249!\`git diff $ARGUMENTS\`

250 

251Audit the changes above for:

252 

2531. Injection vulnerabilities (SQL, XSS, command)

2542. Authentication and authorization gaps

2553. Hardcoded secrets or credentials

256 

257Use checklist.md in this skill directory for the full review checklist.

258 

259Report findings with severity ratings and remediation steps.`

260 }, {

261 id: 'skill-checklist',

262 label: 'checklist.md',

263 type: 'file',

264 icon: 'md',

265 color: '#D4A843',

266 badge: 'committed',

267 oneLiner: 'Supporting file bundled with the skill',

268 when: 'Claude reads it on demand while running the skill',

269 description: <>Skills can bundle any supporting files: reference docs, templates, scripts. The skill directory path is prepended to SKILL.md, so Claude can read bundled files by name. For scripts in bash injection commands, use the <C>{'${CLAUDE_SKILL_DIR}'}</C> placeholder.</>,

270 example: `# Security Review Checklist

271 

272## Input Validation

273- [ ] All user input sanitized before DB queries

274- [ ] File upload MIME types validated

275- [ ] Path traversal prevented on file operations

276 

277## Authentication

278- [ ] JWT tokens expire after 24 hours

279- [ ] API keys stored in environment variables

280- [ ] Passwords hashed with bcrypt or argon2`

281 }]

282 }]

283 }, {

284 id: 'commands',

285 label: 'commands/',

286 type: 'folder',

287 icon: 'folder',

288 color: '#788C5D',

289 oneLiner: <>Single-file prompts invoked with <C>/name</C></>,

290 note: commandsNote,

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

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

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

294 docsLink: '/en/skills',

295 children: [{

296 id: 'cmd-example',

297 label: 'fix-issue.md',

298 type: 'file',

299 icon: 'md',

300 color: '#788C5D',

301 badge: 'committed',

302 oneLiner: <>Invoked as <C>/fix-issue &lt;number&gt;</C></>,

303 note: commandsNote,

304 description: [<>An example command for fixing a GitHub issue. Type <C>/fix-issue 123</C> and the <C>!`...`</C> line runs <C>gh issue view 123</C> in your shell, injecting the output into the prompt before Claude sees it.</>, <><C>$ARGUMENTS</C> substitutes whatever you typed after the command name. For positional access, use <C>$0</C> <C>$1</C> and so on.</>],

305 example: `---

306argument-hint: <issue-number>

307---

308 

309!\`gh issue view $ARGUMENTS\`

310 

311Investigate and fix the issue above.

312 

3131. Trace the bug to its root cause

3142. Implement the fix

3153. Write or update tests

3164. Summarize what you changed and why`

317 }]

318 }, {

319 id: 'output-styles',

320 label: 'output-styles/',

321 type: 'folder',

322 icon: 'folder',

323 color: '#5AA7A7',

324 oneLiner: 'Project-scoped output styles, if your team shares any',

325 when: 'Applied at session start when selected via the outputStyle setting',

326 description: <>Output styles are usually personal, so most live in <C>~/.claude/output-styles/</C>. Put one here if your team shares a style, like a review mode everyone uses. See <A href="#ce-global-output-styles">the Global tab</A> for the full explanation and example.</>,

327 docsLink: '/en/output-styles',

328 children: []

329 }, {

330 id: 'agents',

331 label: 'agents/',

332 type: 'folder',

333 icon: 'folder',

334 color: '#C46686',

335 oneLiner: 'Specialized subagents with their own context window',

336 when: 'Runs in its own context window when you or Claude invoke it',

337 description: 'Each markdown file defines a subagent with its own system prompt, tool access, and optionally its own model. Subagents run in a fresh context window, keeping the main conversation clean. Useful for parallel work or isolated tasks.',

338 tips: ['Each agent gets a fresh context window, separate from your main session', <>Restrict tool access per agent with the <C>tools:</C> frontmatter field</>, 'Type @ and pick an agent from the autocomplete to delegate directly'],

339 docsLink: '/en/sub-agents',

340 children: [{

341 id: 'agent-reviewer',

342 label: 'code-reviewer.md',

343 type: 'file',

344 icon: 'md',

345 color: '#C46686',

346 badge: 'committed',

347 oneLiner: 'Subagent for isolated code review',

348 when: 'Claude spawns it for review tasks, or you @-mention it from the autocomplete',

349 description: <>An example subagent restricted to read-only tools. The <C>description</C> frontmatter tells Claude when to delegate to it automatically; <C>tools:</C> limits it to Read, Grep, and Glob so it can inspect code but never edit. The body becomes the subagent's system prompt.</>,

350 example: `---

351name: code-reviewer

352description: Reviews code for correctness, security, and maintainability

353tools: Read, Grep, Glob

354---

355 

356You are a senior code reviewer. Review for:

357 

3581. Correctness: logic errors, edge cases, null handling

3592. Security: injection, auth bypass, data exposure

3603. Maintainability: naming, complexity, duplication

361 

362Every finding must include a concrete fix.`

363 }]

364 }, {

365 id: 'workflows',

366 label: 'workflows/',

367 type: 'folder',

368 icon: 'folder',

369 color: '#C46686',

370 oneLiner: 'Dynamic workflow scripts that orchestrate many subagents',

371 when: 'Loaded at startup; each file becomes a /<name> command',

372 description: <>Each <C>.js</C> file is a <A href="/en/workflows">dynamic workflow</A>: a script the runtime executes to spawn and coordinate many subagents. Workflows are written by Claude and saved here from <C>/workflows</C> rather than authored from scratch.</>,

373 tips: [<>Save a run from <C>/workflows</C> with <C>s</C> to create one of these</>, <>A project workflow takes precedence over a personal one in <C>~/.claude/workflows/</C> with the same name</>],

374 docsLink: '/en/workflows'

375 }, {

376 id: 'agent-memory',

377 label: 'agent-memory/',

378 type: 'folder',

379 icon: 'folder',

380 color: '#C46686',

381 badge: 'committed',

382 autogen: true,

383 oneLiner: 'Subagent persistent memory, separate from your main session auto memory',

384 when: 'First 200 lines (capped at 25KB) of MEMORY.md loaded into the subagent system prompt when it runs',

385 description: <>Subagents with <C>memory: project</C> in their frontmatter get a dedicated memory directory here. This is distinct from your <A href="/en/memory#auto-memory">main session auto memory</A> at <C>~/.claude/projects/</C>: each subagent reads and writes its own MEMORY.md, not yours.</>,

386 tips: [<>Only created for subagents that set the <C>memory:</C> frontmatter field</>, <>This directory holds project-scoped subagent memory, meant to be shared with your team. To keep memory out of version control use <C>memory: local</C>, which writes to <C>.claude/agent-memory-local/</C> instead. For cross-project memory use <C>memory: user</C>, which writes to <C>~/.claude/agent-memory/</C></>, <>The main session auto memory is a different feature; see <C>~/.claude/projects/</C> in the Global tab</>],

387 docsLink: '/en/sub-agents#enable-persistent-memory',

388 children: [{

389 id: 'agent-memory-sub',

390 label: '<agent-name>/',

391 type: 'folder',

392 icon: 'folder',

393 color: '#C46686',

394 autogen: true,

395 children: [{

396 id: 'agent-memory-md',

397 label: 'MEMORY.md',

398 type: 'file',

399 icon: 'md',

400 color: '#C46686',

401 badge: 'committed',

402 autogen: true,

403 oneLiner: 'The subagent writes and maintains this file automatically',

404 when: 'Loaded into the subagent system prompt when the subagent starts',

405 description: <>Works the same as your <A href="/en/memory#auto-memory">main auto memory</A>: the subagent creates and updates this file itself. You do not write it. The subagent reads it at the start of each task and writes back what it learns.</>,

406 example: `# code-reviewer memory

407 

408## Patterns seen

409- Project uses custom Result<T, E> type, not exceptions

410- Auth middleware expects Bearer token in Authorization header

411- Tests use factory functions in test/factories/

412 

413## Recurring issues

414- Missing null checks on API responses (src/api/*)

415- Unhandled promise rejections in background jobs`

416 }]

417 }]

418 }]

419 }]

420 },

421 global: {

422 label: '~/',

423 children: [{

424 id: 'claude-json',

425 label: '.claude.json',

426 type: 'file',

427 icon: 'json',

428 color: 'var(--ce-text-3)',

429 badge: 'local',

430 oneLiner: 'App state and UI preferences',

431 when: <>Read at session start for your preferences and MCP servers. Claude Code writes back to it when you change settings in <C>/config</C> or approve trust prompts</>,

432 description: <>Holds state that does not belong in settings.json: theme, OAuth session, per-project trust decisions, your personal MCP servers, and UI toggles. Mostly managed through <C>/config</C> rather than editing directly.</>,

433 tips: [<>IDE toggles like <C>autoConnectIde</C> and <C>externalEditorContext</C> live here, not in settings.json</>, <>The <C>projects</C> key tracks per-project state like trust-dialog acceptance and last-session metrics. Permission rules you approve in-session go to <C>.claude/settings.local.json</C> instead</>, <>MCP servers here are yours only: user scope applies across all projects, local scope is per-project but not committed. Team-shared servers go in <C>.mcp.json</C> at the project root instead</>],

434 example: `{

435 "autoConnectIde": true,

436 "externalEditorContext": true,

437 "mcpServers": {

438 "my-tools": {

439 "command": "npx",

440 "args": ["-y", "@example/mcp-server"]

441 }

442 }

443}`,

444 docsLink: '/en/settings#global-config-settings'

445 }, {

446 id: 'global-dot-claude',

447 label: '.claude/',

448 type: 'folder',

449 icon: 'folder',

450 color: 'var(--ce-accent)',

451 oneLiner: 'Your personal configuration across all projects',

452 description: 'The global counterpart to your project .claude/ directory. Files here apply to every project you work in and are never committed to any repository.',

453 children: [{

454 id: 'global-claude-md',

455 label: 'CLAUDE.md',

456 type: 'file',

457 icon: 'md',

458 color: '#6A9BCC',

459 badge: 'local',

460 oneLiner: 'Personal preferences across every project',

461 when: 'Loaded at the start of every session, in every project',

462 description: 'Your global instruction file. Loaded alongside the project CLAUDE.md at session start, so both are in context together. When instructions conflict, project-level instructions take priority. Keep this to preferences that apply everywhere: response style, commit format, personal conventions.',

463 tips: ['Keep it short since it loads into context for every project, alongside that project\'s own CLAUDE.md', 'Good for response style, commit format, and personal conventions'],

464 example: `# Global preferences

465 

466- Keep explanations concise

467- Use conventional commit format

468- Show the terminal command to verify changes

469- Prefer composition over inheritance`,

470 docsLink: '/en/memory'

471 }, {

472 id: 'global-settings',

473 label: 'settings.json',

474 type: 'file',

475 icon: 'json',

476 color: 'var(--ce-text-3)',

477 badge: 'local',

478 oneLiner: 'Default settings for all projects',

479 when: 'Your defaults. Project and local settings.json override any keys you also set there',

480 description: [<>Same keys as project <C>settings.json</C>: permissions, hooks, model, environment variables, and the rest. Put settings here that you want in every project, like permissions you always allow, a preferred model, or a notification hook that runs regardless of which project you're in.</>, <>Settings follow a precedence order: project <C>settings.json</C> overrides any matching keys you set here. This is different from CLAUDE.md, where global and project files are both loaded into context rather than merged key by key.</>],

481 example: `{

482 "permissions": {

483 "allow": [

484 "Bash(git log *)",

485 "Bash(git diff *)"

486 ]

487 }

488}`,

489 docsLink: '/en/settings'

490 }, {

491 id: 'keybindings',

492 label: 'keybindings.json',

493 type: 'file',

494 icon: 'json',

495 color: 'var(--ce-text-3)',

496 badge: 'local',

497 oneLiner: 'Custom keyboard shortcuts',

498 when: 'Read at session start and hot-reloaded when you edit the file',

499 description: <>Rebind keyboard shortcuts in the interactive CLI. Run <C>/keybindings</C> to create or open this file with a schema reference. Ctrl+C, Ctrl+D, Ctrl+M, and Caps Lock are reserved and cannot be rebound.</>,

500 exampleIntro: <>This example binds <C>Ctrl+E</C> to open your external editor and unbinds <C>Ctrl+U</C> by setting it to <C>null</C>. The <C>context</C> field scopes bindings to a specific part of the CLI, here the main chat input.</>,

501 example: `{

502 "$schema": "https://www.schemastore.org/claude-code-keybindings.json",

503 "$docs": "https://code.claude.com/docs/en/keybindings",

504 "bindings": [

505 {

506 "context": "Chat",

507 "bindings": {

508 "ctrl+e": "chat:externalEditor",

509 "ctrl+u": null

510 }

511 }

512 ]

513}`,

514 docsLink: '/en/keybindings'

515 }, {

516 id: 'themes',

517 label: 'themes/',

518 type: 'folder',

519 icon: 'folder',

520 color: '#5AA7A7',

521 oneLiner: 'Custom color themes',

522 when: <>Read at session start and hot-reloaded when files change. Listed in <C>/theme</C></>,

523 description: <>Each <C>.json</C> file defines a custom color theme: a built-in <C>base</C> preset plus an <C>overrides</C> map of color tokens. Create one interactively with <C>/theme</C> or write the JSON by hand. Selecting a custom theme stores <C>custom:&lt;slug&gt;</C> as your theme preference.</>,

524 example: `{

525 "name": "Dracula",

526 "base": "dark",

527 "overrides": {

528 "claude": "#bd93f9",

529 "error": "#ff5555",

530 "success": "#50fa7b"

531 }

532}`,

533 docsLink: '/en/terminal-config#create-a-custom-theme',

534 children: []

535 }, {

536 id: 'global-projects',

537 label: 'projects/',

538 type: 'folder',

539 icon: 'folder',

540 color: '#E8A45C',

541 autogen: true,

542 oneLiner: "Auto memory: Claude's notes to itself, per project",

543 when: 'MEMORY.md loaded at session start; topic files read on demand',

544 description: 'Auto memory lets Claude accumulate knowledge across sessions without you writing anything. Claude saves notes as it works: build commands, debugging insights, architecture notes. Each project gets its own memory directory keyed by the repository path.',

545 tips: [<>On by default. Toggle with <C>/memory</C> or <C>autoMemoryEnabled</C> in settings</>, 'MEMORY.md is the index loaded each session. The first 200 lines, or 25KB, whichever comes first, are read', 'Topic files like debugging.md are read on demand, not at startup', 'These are plain markdown. Edit or delete them anytime'],

546 docsLink: '/en/memory#auto-memory',

547 children: [{

548 id: 'memory-dir',

549 label: '<project>/memory/',

550 type: 'folder',

551 icon: 'folder',

552 color: '#E8A45C',

553 autogen: true,

554 oneLiner: "Claude's accumulated knowledge for one project",

555 children: [{

556 id: 'memory-md',

557 label: 'MEMORY.md',

558 type: 'file',

559 icon: 'md',

560 color: '#E8A45C',

561 badge: 'local',

562 autogen: true,

563 oneLiner: 'Claude writes and maintains this file automatically',

564 when: 'First 200 lines (capped at 25KB) loaded at session start',

565 description: 'Claude creates and updates this file as it works; you do not write it yourself. It acts as an index that Claude reads at the start of every session, pointing to topic files for detail. You can edit or delete it, but Claude will keep updating it.',

566 example: `# Memory Index

567 

568## Project

569- [build-and-test.md](build-and-test.md): npm run build (~45s), Vitest, dev server on 3001

570- [architecture.md](architecture.md): API client singleton, refresh-token auth

571 

572## Reference

573- [debugging.md](debugging.md): auth token rotation and DB connection troubleshooting`,

574 docsLink: '/en/memory'

575 }, {

576 id: 'memory-topic',

577 label: 'debugging.md',

578 type: 'file',

579 icon: 'md',

580 color: '#E8A45C',

581 badge: 'local',

582 autogen: true,

583 oneLiner: 'Topic notes Claude writes when MEMORY.md gets long',

584 when: 'Claude reads this when a related task comes up',

585 description: 'An example of a topic file Claude creates when MEMORY.md grows too long. Claude picks the filename based on what it splits out: debugging.md, architecture.md, build-commands.md, or similar. You never create these yourself. Claude reads a topic file back only when the current task relates to it.',

586 example: `---

587name: Debugging patterns

588description: Auth token rotation and database connection troubleshooting for this project

589type: reference

590---

591 

592## Auth Token Issues

593- Refresh token rotation: old token invalidated immediately

594- If 401 after refresh: check clock skew between client and server

595 

596## Database Connection Drops

597- Connection pool: max 10 in dev, 50 in prod

598- Always check \`docker compose ps\` first`

599 }]

600 }]

601 }, {

602 id: 'global-rules',

603 label: 'rules/',

604 type: 'folder',

605 icon: 'folder',

606 color: '#9B7BC4',

607 oneLiner: 'User-level rules that apply to every project',

608 when: <>Rules without <C>paths:</C> load at session start. Rules with <C>paths:</C> load when a matching file enters context</>,

609 description: 'Same as project .claude/rules/ but applies everywhere. Use this for conventions you want across all your work, like personal code style or commit message format.',

610 docsLink: '/en/memory#organize-rules-with-claude/rules/',

611 children: []

612 }, {

613 id: 'global-skills',

614 label: 'skills/',

615 type: 'folder',

616 icon: 'folder',

617 color: '#D4A843',

618 oneLiner: 'Personal skills available in every project',

619 when: <>Invoked with <C>/skill-name</C> in any project</>,

620 description: 'Skills you built for yourself that work everywhere. Same structure as project skills: each is a folder with SKILL.md, scoped to your user account instead of a single project.',

621 docsLink: '/en/skills',

622 children: []

623 }, {

624 id: 'global-commands',

625 label: 'commands/',

626 type: 'folder',

627 icon: 'folder',

628 color: '#788C5D',

629 oneLiner: 'Personal single-file commands available in every project',

630 note: commandsNote,

631 when: <>User types <C>/command-name</C> in any project</>,

632 description: 'Same as project commands/ but scoped to your user account. Each markdown file becomes a command available everywhere.',

633 docsLink: '/en/skills',

634 children: []

635 }, {

636 id: 'global-output-styles',

637 label: 'output-styles/',

638 type: 'folder',

639 icon: 'folder',

640 color: '#5AA7A7',

641 oneLiner: 'Custom system-prompt sections that adjust how Claude works',

642 when: 'Applied at session start when selected via the outputStyle setting',

643 description: [<>Each markdown file defines an output style: a section appended to the system prompt that, by default, also drops the built-in software-engineering task instructions. Use this to adapt Claude Code for uses beyond coding, or to add teaching or review modes.</>, <>Select a built-in or custom style with <C>/config</C> or the <C>outputStyle</C> key in settings. Styles here are available in every project; project-level styles with the same name take precedence.</>],

644 tips: ['Built-in styles Explanatory and Learning are included with Claude Code; custom styles go here', <>Set <C>keep-coding-instructions: true</C> in frontmatter to keep the default task instructions alongside your additions</>, 'Changes take effect on the next session since the system prompt is fixed at startup for caching'],

645 docsLink: '/en/output-styles',

646 children: [{

647 id: 'output-style-example',

648 label: 'teaching.md',

649 type: 'file',

650 icon: 'md',

651 color: '#5AA7A7',

652 badge: 'local',

653 oneLiner: 'Example style that adds explanations and leaves small changes for you',

654 when: <>Active when <C>outputStyle</C> in settings is set to <C>teaching</C></>,

655 description: <>This style appends instructions to the system prompt: Claude adds a "Why this approach" note after each task and leaves TODO(human) markers for changes under 10 lines instead of writing them itself. Select it by setting <C>outputStyle</C> to the filename without .md, or to the <C>name</C> field if you set one in frontmatter.</>,

656 example: `---

657description: Explains reasoning and asks you to implement small pieces

658keep-coding-instructions: true

659---

660 

661After completing each task, add a brief "Why this approach" note

662explaining the key design decision.

663 

664When a change is under 10 lines, ask the user to implement it

665themselves by leaving a TODO(human) marker instead of writing it.`

666 }]

667 }, {

668 id: 'global-agents',

669 label: 'agents/',

670 type: 'folder',

671 icon: 'folder',

672 color: '#C46686',

673 oneLiner: 'Personal subagents available in every project',

674 when: 'Claude delegates or you @-mention in any project',

675 description: 'Subagents defined here are available across all your projects. Same format as project agents.',

676 docsLink: '/en/sub-agents',

677 children: []

678 }, {

679 id: 'global-workflows',

680 label: 'workflows/',

681 type: 'folder',

682 icon: 'folder',

683 color: '#C46686',

684 oneLiner: 'Personal dynamic workflows available in every project',

685 when: 'Loaded at startup; each file becomes a /<name> command',

686 description: <>Workflow scripts saved here are available across all your projects. A project workflow with the same name in <C>.claude/workflows/</C> takes precedence.</>,

687 docsLink: '/en/workflows',

688 children: []

689 }, {

690 id: 'global-agent-memory',

691 label: 'agent-memory/',

692 type: 'folder',

693 icon: 'folder',

694 color: '#C46686',

695 autogen: true,

696 oneLiner: <>Persistent memory for subagents with <C>memory: user</C></>,

697 when: 'Loaded into the subagent system prompt when the subagent starts',

698 description: <>Subagents with <C>memory: user</C> in their frontmatter store knowledge here that persists across all projects. For project-scoped subagent memory, see <C>.claude/agent-memory/</C> instead.</>,

699 docsLink: '/en/sub-agents#enable-persistent-memory',

700 children: []

701 }]

702 }]

703 }

704 }), []);

705 const BADGE_STYLES = useMemo(() => ({

706 committed: {

707 bg: 'rgba(85,138,66,0.08)',

708 color: 'var(--ce-badge-committed)',

709 border: 'rgba(85,138,66,0.15)',

710 label: 'committed'

711 },

712 gitignored: {

713 bg: 'rgba(217,119,87,0.06)',

714 color: 'var(--ce-badge-gitignored)',

715 border: 'rgba(217,119,87,0.15)',

716 label: 'gitignored'

717 },

718 local: {

719 bg: 'rgba(115,114,108,0.06)',

720 color: 'var(--ce-badge-local)',

721 border: 'rgba(115,114,108,0.12)',

722 label: 'local only'

723 },

724 autogen: {

725 bg: 'rgba(232,164,92,0.1)',

726 color: 'var(--ce-badge-autogen)',

727 border: 'rgba(232,164,92,0.2)',

728 label: 'Claude writes'

729 }

730 }), []);

731 const allNodes = useMemo(() => {

732 const flatten = (nodes, acc, path, parentId) => {

733 for (const node of nodes) {

734 const nextPath = [...path, node.label];

735 acc[node.id] = {

736 ...node,

737 path: nextPath,

738 parentId

739 };

740 if (node.children) flatten(node.children, acc, nextPath, node.id);

741 }

742 return acc;

743 };

744 const project = flatten(FILE_TREE.project.children, {}, [FILE_TREE.project.label]);

745 const global = flatten(FILE_TREE.global.children, {}, [FILE_TREE.global.label]);

746 for (const id in project) project[id].root = 'project';

747 for (const id in global) global[id].root = 'global';

748 return {

749 ...project,

750 ...global

751 };

752 }, [FILE_TREE]);

753 const allFolderIds = useMemo(() => Object.keys(allNodes).filter(id => allNodes[id].type === 'folder'), [allNodes]);

754 const DEFAULT_EXPANDED = ['dot-claude', 'rules', 'skills', 'skill-review', 'commands', 'agents', 'agent-memory', 'agent-memory-sub', 'global-dot-claude', 'global-output-styles', 'global-projects', 'memory-dir'];

755 const [mounted, setMounted] = useState(false);

756 const [activeRoot, setActiveRoot] = useState('project');

757 const [selectedId, setSelectedId] = useState('claude-md');

758 const [expandedFolders, setExpandedFolders] = useState(() => new Set(DEFAULT_EXPANDED));

759 const [forceMobile, setForceMobile] = useState(false);

760 const [copiedId, setCopiedId] = useState(null);

761 const [isFullscreen, setIsFullscreen] = useState(false);

762 const copyTimeoutRef = useRef(null);

763 const rootRef = useRef(null);

764 useEffect(() => {

765 setMounted(true);

766 const applyHash = scroll => {

767 const hash = window.location.hash.slice(1);

768 if (!hash.startsWith('ce-')) return;

769 const id = hash.slice(3);

770 const node = allNodes[id];

771 if (!node) return;

772 setActiveRoot(node.root);

773 setSelectedId(id);

774 setExpandedFolders(new Set(allFolderIds));

775 if (scroll && rootRef.current) rootRef.current.scrollIntoView({

776 behavior: 'smooth',

777 block: 'start'

778 });

779 };

780 applyHash(false);

781 const onHashChange = () => applyHash(true);

782 const onFsChange = () => setIsFullscreen(!!document.fullscreenElement);

783 window.addEventListener('hashchange', onHashChange);

784 document.addEventListener('fullscreenchange', onFsChange);

785 return () => {

786 if (copyTimeoutRef.current) clearTimeout(copyTimeoutRef.current);

787 window.removeEventListener('hashchange', onHashChange);

788 document.removeEventListener('fullscreenchange', onFsChange);

789 };

790 }, []);

791 useEffect(() => {

792 if (!mounted || !rootRef.current) return;

793 const hash = window.location.hash.slice(1);

794 if (hash.startsWith('ce-') && allNodes[hash.slice(3)]) {

795 rootRef.current.scrollIntoView({

796 behavior: 'smooth',

797 block: 'start'

798 });

799 }

800 }, [mounted]);

801 if (!mounted) return null;

802 const selected = allNodes[selectedId];

803 const tree = FILE_TREE[activeRoot];

804 const isCopied = copiedId === selected.id;

805 const toggleFolder = id => {

806 const next = new Set(expandedFolders);

807 next.has(id) ? next.delete(id) : next.add(id);

808 setExpandedFolders(next);

809 };

810 const switchRoot = root => {

811 if (root === activeRoot) return;

812 setActiveRoot(root);

813 const firstId = FILE_TREE[root].children[0].id;

814 setSelectedId(firstId);

815 try {

816 history.replaceState(null, '', '#ce-' + firstId);

817 } catch (e) {}

818 };

819 const toggleFullscreen = () => {

820 if (!rootRef.current) return;

821 if (document.fullscreenElement) document.exitFullscreen(); else rootRef.current.requestFullscreen().catch(() => {});

822 };

823 const selectNode = n => {

824 setSelectedId(n.id);

825 if (n.type === 'folder' && !expandedFolders.has(n.id)) toggleFolder(n.id);

826 try {

827 history.replaceState(null, '', '#ce-' + n.id);

828 } catch (e) {}

829 };

830 const iconBtn = {

831 width: 28,

832 flexShrink: 0,

833 borderRadius: '6px',

834 border: 'none',

835 cursor: 'pointer',

836 background: 'transparent',

837 color: 'var(--ce-text-4)',

838 display: 'flex',

839 alignItems: 'center',

840 justifyContent: 'center'

841 };

842 const visibleFolderIds = allFolderIds.filter(id => allNodes[id].root === activeRoot);

843 const allExpanded = visibleFolderIds.every(id => expandedFolders.has(id));

844 const toggleAllFolders = () => {

845 const next = new Set(expandedFolders);

846 visibleFolderIds.forEach(id => allExpanded ? next.delete(id) : next.add(id));

847 setExpandedFolders(next);

848 };

849 const onTreeKeyDown = e => {

850 if (!['ArrowDown', 'ArrowUp', 'ArrowRight', 'ArrowLeft'].includes(e.key)) return;

851 const visible = [];

852 const walk = nodes => {

853 for (const n of nodes) {

854 visible.push(n.id);

855 if (n.children && expandedFolders.has(n.id)) walk(n.children);

856 }

857 };

858 walk(tree.children);

859 const i = visible.indexOf(selectedId);

860 if (i === -1) return;

861 e.preventDefault();

862 if (e.key === 'ArrowDown' && i < visible.length - 1) selectNode(allNodes[visible[i + 1]]); else if (e.key === 'ArrowUp' && i > 0) selectNode(allNodes[visible[i - 1]]); else if (e.key === 'ArrowRight' && selected.type === 'folder') {

863 if (!expandedFolders.has(selectedId)) toggleFolder(selectedId); else if (selected.children && selected.children.length) selectNode(allNodes[selected.children[0].id]);

864 } else if (e.key === 'ArrowLeft') {

865 if (selected.type === 'folder' && expandedFolders.has(selectedId)) toggleFolder(selectedId); else if (selected.parentId) selectNode(allNodes[selected.parentId]);

866 }

867 };

868 const copyExample = (id, text) => {

869 const done = () => {

870 setCopiedId(id);

871 if (copyTimeoutRef.current) clearTimeout(copyTimeoutRef.current);

872 copyTimeoutRef.current = setTimeout(() => setCopiedId(null), 2000);

873 };

874 const fallback = () => {

875 const ta = document.createElement('textarea');

876 ta.value = text;

877 ta.style.position = 'fixed';

878 ta.style.opacity = '0';

879 document.body.appendChild(ta);

880 ta.select();

881 try {

882 if (document.execCommand('copy')) done();

883 } catch (e) {}

884 document.body.removeChild(ta);

885 };

886 if (navigator.clipboard) {

887 navigator.clipboard.writeText(text).then(done, fallback);

888 } else {

889 fallback();

890 }

891 };

892 const renderIcon = (icon, color, size) => {

893 const sz = size || 14;

894 if (icon === 'folder') {

895 return <svg width={sz} height={sz} viewBox="0 0 14 14" fill="none">

896 <path d="M1.5 3.5a1 1 0 0 1 1-1h2.6l1 1.2h5.4a1 1 0 0 1 1 1v5.8a1 1 0 0 1-1 1h-9a1 1 0 0 1-1-1V3.5z" fill={color} fillOpacity="0.15" stroke={color} strokeWidth="1" />

897 </svg>;

898 }

899 if (icon === 'json') {

900 return <svg width={sz} height={sz} viewBox="0 0 14 14" fill="none">

901 <rect x="2" y="1.5" width="10" height="11" rx="1.5" fill={color} fillOpacity="0.15" stroke={color} strokeWidth="1" />

902 <text x="7" y="9" fontSize="6" fontFamily="monospace" fill={color} textAnchor="middle" fontWeight="700">{'{}'}</text>

903 </svg>;

904 }

905 return <svg width={sz} height={sz} viewBox="0 0 14 14" fill="none">

906 <rect x="2" y="1.5" width="10" height="11" rx="1.5" fill={color} fillOpacity="0.15" stroke={color} strokeWidth="1" />

907 <line x1="4.5" y1="5" x2="9.5" y2="5" stroke={color} strokeWidth="1" />

908 <line x1="4.5" y1="7" x2="9.5" y2="7" stroke={color} strokeWidth="1" />

909 <line x1="4.5" y1="9" x2="8" y2="9" stroke={color} strokeWidth="1" />

910 </svg>;

911 };

912 const renderNode = (node, depth) => {

913 const isFolder = node.type === 'folder';

914 const isExpanded = expandedFolders.has(node.id);

915 const isSelected = selectedId === node.id;

916 return <div key={node.id}>

917 <button role="treeitem" tabIndex={-1} onClick={() => selectNode(node)} aria-selected={isSelected} aria-expanded={isFolder ? isExpanded : undefined} style={{

918 display: 'flex',

919 alignItems: 'center',

920 gap: '5px',

921 width: '100%',

922 padding: `4px 8px 4px ${8 + depth * 16}px`,

923 background: isSelected ? 'var(--ce-accent-bg)' : 'transparent',

924 borderTop: 'none',

925 borderRight: 'none',

926 borderBottom: 'none',

927 borderLeft: isSelected ? '2px solid var(--ce-accent)' : '2px solid transparent',

928 outline: 'none',

929 cursor: 'pointer',

930 textAlign: 'left',

931 fontFamily: 'var(--ce-mono)',

932 fontSize: '13.5px',

933 color: isSelected ? 'var(--ce-accent)' : 'var(--ce-text-2)',

934 fontWeight: isSelected ? 550 : 400,

935 transition: 'all 0.1s'

936 }}>

937 {isFolder ? <span onClick={e => {

938 e.stopPropagation();

939 toggleFolder(node.id);

940 }} style={{

941 fontSize: '14px',

942 color: 'var(--ce-text-4)',

943 width: '20px',

944 height: '20px',

945 display: 'inline-flex',

946 alignItems: 'center',

947 justifyContent: 'center',

948 cursor: 'pointer',

949 borderRadius: '4px',

950 marginLeft: '-6px',

951 flexShrink: 0

952 }} onMouseEnter={e => {

953 e.currentTarget.style.background = 'var(--ce-arrow-hover)';

954 e.currentTarget.style.color = 'var(--ce-text-2)';

955 }} onMouseLeave={e => {

956 e.currentTarget.style.background = 'transparent';

957 e.currentTarget.style.color = 'var(--ce-text-4)';

958 }}>{isExpanded ? '▾' : '▸'}</span> : <span style={{

959 width: '14px',

960 flexShrink: 0

961 }} />}

962 {renderIcon(node.icon, node.color)}

963 <span style={{

964 flex: 1,

965 overflow: 'hidden',

966 textOverflow: 'ellipsis',

967 whiteSpace: 'nowrap'

968 }}>{node.label}</span>

969 {node.badge && BADGE_STYLES[node.badge] && <span title={BADGE_STYLES[node.badge].label} style={{

970 width: 6,

971 height: 6,

972 borderRadius: '50%',

973 background: BADGE_STYLES[node.badge].color,

974 flexShrink: 0,

975 opacity: 0.7

976 }} />}

977 </button>

978 {isFolder && isExpanded && node.children && <div role="group">{node.children.map(child => renderNode(child, depth + 1))}</div>}

979 </div>;

980 };

981 return <>

982 <style>{`

983 .ce-root {

984 --ce-mono: var(--font-mono, ui-monospace, monospace);

985 --ce-accent: #D97757;

986 --ce-accent-bg: rgba(217,119,87,0.06);

987 --ce-accent-border: rgba(217,119,87,0.12);

988 --ce-bg: #fff;

989 --ce-surface: #FAFAF7;

990 --ce-surface-hover: #F0EEE6;

991 --ce-border: #E8E6DC;

992 --ce-border-subtle: #F0EEE6;

993 --ce-text: #141413;

994 --ce-text-2: #5E5D59;

995 --ce-text-3: #73726C;

996 --ce-text-4: #9C9A92;

997 --ce-text-5: #B8B6AE;

998 --ce-sep: #D1CFC5;

999 --ce-code-header: #F5F4ED;

1000 --ce-code-bg: #1A1918;

1001 --ce-arrow-hover: rgba(0,0,0,0.08);

1002 --ce-badge-committed: #3d6b2e;

1003 --ce-badge-gitignored: #b85c3a;

1004 --ce-badge-local: #5e5d59;

1005 --ce-badge-autogen: #b07520;

1006 --ce-when-text: #4a7fb5;

1007 }

1008 .dark .ce-root {

1009 --ce-bg: #1a1918;

1010 --ce-surface: #232221;

1011 --ce-surface-hover: #2e2d2b;

1012 --ce-border: #3a3936;

1013 --ce-border-subtle: #2e2d2b;

1014 --ce-text: #e8e6dc;

1015 --ce-text-2: #c4c2b8;

1016 --ce-text-3: #9c9a92;

1017 --ce-text-4: #73726c;

1018 --ce-text-5: #5e5d59;

1019 --ce-sep: #4a4946;

1020 --ce-code-header: #2e2d2b;

1021 --ce-code-bg: #0d0d0c;

1022 --ce-arrow-hover: rgba(255,255,255,0.08);

1023 --ce-badge-committed: #6fa85c;

1024 --ce-badge-gitignored: #e08a60;

1025 --ce-badge-local: #9c9a92;

1026 --ce-badge-autogen: #e8a45c;

1027 --ce-when-text: #8bb4e0;

1028 }

1029 .ce-mobile-fallback { display: none; border: 1px solid rgba(0,0,0,0.1); background: rgba(0,0,0,0.03); }

1030 .dark .ce-mobile-fallback { border-color: rgba(255,255,255,0.15); background: rgba(255,255,255,0.04); }

1031 @media (max-width: 700px) {

1032 .ce-root:not(.ce-force) { display: none !important; }

1033 .ce-mobile-fallback { display: block; }

1034 }

1035 `}</style>

1036 {!forceMobile && <div className="ce-mobile-fallback" style={{

1037 padding: '14px 16px',

1038 borderRadius: '8px',

1039 fontSize: '14px'

1040 }}>

1041 The interactive explorer works best on a larger screen. See the <a href="#file-reference" style={{

1042 color: '#D97757'

1043 }}>file reference table</a> below, or <button onClick={() => setForceMobile(true)} style={{

1044 border: 'none',

1045 background: 'none',

1046 padding: 0,

1047 color: '#D97757',

1048 textDecoration: 'underline',

1049 cursor: 'pointer',

1050 font: 'inherit'

1051 }}>show the explorer anyway</button>.

1052 </div>}

1053 <div ref={rootRef} className={forceMobile ? 'ce-root ce-force' : 'ce-root'} style={{

1054 borderRadius: isFullscreen ? 0 : '12px',

1055 border: '1px solid var(--ce-border)',

1056 background: 'var(--ce-bg)',

1057 display: 'flex',

1058 alignItems: 'stretch',

1059 overflow: 'hidden',

1060 fontFamily: 'var(--font-sans, -apple-system, sans-serif)',

1061 ...isFullscreen && ({

1062 height: '100vh'

1063 })

1064 }}>

1065 {}

1066 <div style={{

1067 width: 'min(240px, 35%)',

1068 minWidth: '180px',

1069 flexShrink: 0,

1070 borderRight: '1px solid var(--ce-border-subtle)',

1071 background: 'var(--ce-surface)',

1072 display: 'flex',

1073 flexDirection: 'column'

1074 }}>

1075 <div style={{

1076 padding: '8px 8px 4px',

1077 borderBottom: '1px solid var(--ce-border-subtle)',

1078 display: 'flex',

1079 gap: '4px'

1080 }}>

1081 {['project', 'global'].map(root => <button key={root} onClick={() => switchRoot(root)} style={{

1082 flex: 1,

1083 padding: '6px 0',

1084 borderRadius: '6px',

1085 border: 'none',

1086 cursor: 'pointer',

1087 fontFamily: 'var(--ce-mono)',

1088 fontSize: '11.5px',

1089 background: activeRoot === root ? 'var(--ce-accent-bg)' : 'transparent',

1090 color: activeRoot === root ? 'var(--ce-accent)' : 'var(--ce-text-4)',

1091 fontWeight: activeRoot === root ? 600 : 430

1092 }}>

1093 {root === 'project' ? 'Project' : 'Global (~/)'}

1094 </button>)}

1095 <button onClick={toggleAllFolders} title={allExpanded ? 'Collapse all' : 'Expand all'} style={{

1096 ...iconBtn,

1097 fontSize: 11

1098 }}>

1099 {allExpanded ? '⊟' : '⊞'}

1100 </button>

1101 <button onClick={toggleFullscreen} title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'} style={{

1102 ...iconBtn,

1103 fontSize: 13

1104 }}>

1105 {isFullscreen ? '⤡' : '⛶'}

1106 </button>

1107 </div>

1108 <div role="tree" aria-label="Configuration files" tabIndex={0} onKeyDown={onTreeKeyDown} style={{

1109 padding: '6px 0',

1110 overflowY: 'auto',

1111 flex: 1,

1112 outline: 'none'

1113 }}>

1114 {tree.children.map(node => renderNode(node, 0))}

1115 </div>

1116 </div>

1117 

1118 {}

1119 <div style={{

1120 flex: 1,

1121 minWidth: 0,

1122 padding: '20px 24px',

1123 minHeight: '400px',

1124 overflowY: 'auto'

1125 }}>

1126 <span aria-live="polite" style={{

1127 position: 'absolute',

1128 width: 1,

1129 height: 1,

1130 overflow: 'hidden',

1131 clip: 'rect(0 0 0 0)'

1132 }}>{selected.label} selected</span>

1133 {}

1134 <div style={{

1135 fontFamily: 'var(--ce-mono)',

1136 fontSize: '11px',

1137 color: 'var(--ce-text-4)',

1138 marginBottom: '10px',

1139 cursor: 'default'

1140 }}>

1141 {selected.path.map((seg, i) => <span key={i}>

1142 <span style={{

1143 color: i === selected.path.length - 1 ? 'var(--ce-accent)' : 'var(--ce-text-4)'

1144 }}>{seg.replace(/\/$/, '')}</span>

1145 {i < selected.path.length - 1 && <span style={{

1146 color: 'var(--ce-sep)'

1147 }}> / </span>}

1148 </span>)}

1149 </div>

1150 

1151 {}

1152 <div style={{

1153 display: 'flex',

1154 alignItems: 'flex-start',

1155 gap: '10px',

1156 marginBottom: '10px'

1157 }}>

1158 <span style={{

1159 flexShrink: 0,

1160 display: 'flex'

1161 }}>{renderIcon(selected.icon, selected.color, 24)}</span>

1162 <div style={{

1163 flex: 1,

1164 minWidth: 0

1165 }}>

1166 <div style={{

1167 fontSize: '22px',

1168 fontWeight: 600,

1169 color: 'var(--ce-text)',

1170 letterSpacing: '-0.3px',

1171 lineHeight: '26px'

1172 }}>{selected.label}</div>

1173 {selected.oneLiner && <div style={{

1174 fontSize: '15px',

1175 color: 'var(--ce-text-3)',

1176 marginTop: '3px'

1177 }}>{selected.oneLiner}</div>}

1178 </div>

1179 <div style={{

1180 display: 'flex',

1181 gap: '4px',

1182 flexShrink: 0

1183 }}>

1184 {[selected.autogen && 'autogen', selected.badge].filter(Boolean).map(k => {

1185 const s = BADGE_STYLES[k];

1186 if (!s) return null;

1187 return <span key={k} style={{

1188 fontFamily: 'var(--ce-mono)',

1189 fontSize: '10px',

1190 fontWeight: 600,

1191 textTransform: 'uppercase',

1192 letterSpacing: '0.3px',

1193 padding: '2px 6px',

1194 borderRadius: '4px',

1195 background: s.bg,

1196 color: s.color,

1197 border: `0.5px solid ${s.border}`

1198 }}>{s.label}</span>;

1199 })}

1200 </div>

1201 </div>

1202 

1203 {}

1204 {selected.note && <div style={{

1205 padding: '10px 12px',

1206 borderRadius: '8px',

1207 marginBottom: '14px',

1208 background: 'rgba(217,119,87,0.06)',

1209 border: '1px solid rgba(217,119,87,0.2)',

1210 borderLeft: '3px solid var(--ce-accent)',

1211 fontSize: '15px',

1212 color: 'var(--ce-text-2)',

1213 lineHeight: 1.6

1214 }}>

1215 {selected.note}

1216 </div>}

1217 

1218 {}

1219 {selected.when && <div style={{

1220 padding: '8px 12px',

1221 borderRadius: '6px',

1222 background: 'rgba(106,155,204,0.06)',

1223 border: '0.5px solid rgba(106,155,204,0.12)',

1224 fontSize: '15px',

1225 color: 'var(--ce-when-text)',

1226 marginBottom: '16px'

1227 }}>

1228 <div style={{

1229 fontSize: '10px',

1230 fontWeight: 700,

1231 textTransform: 'uppercase',

1232 letterSpacing: '0.4px',

1233 opacity: 0.65,

1234 marginBottom: '3px'

1235 }}>When it loads</div>

1236 <div style={{

1237 fontWeight: 500

1238 }}>{selected.when}</div>

1239 </div>}

1240 

1241 {}

1242 {selected.description && <div style={{

1243 fontSize: '16px',

1244 color: 'var(--ce-text-2)',

1245 lineHeight: 1.65,

1246 marginBottom: '16px'

1247 }}>

1248 {Array.isArray(selected.description) ? selected.description.map((para, i) => <div key={i} style={{

1249 marginBottom: i < selected.description.length - 1 ? '12px' : 0

1250 }}>{para}</div>) : selected.description}

1251 </div>}

1252 

1253 {}

1254 {selected.contains && selected.contains.length > 0 && <div style={{

1255 marginBottom: '16px'

1256 }}>

1257 <div style={{

1258 fontSize: '11px',

1259 fontWeight: 700,

1260 color: 'var(--ce-text-4)',

1261 textTransform: 'uppercase',

1262 letterSpacing: '0.4px',

1263 marginBottom: '8px'

1264 }}>Common keys</div>

1265 {selected.contains.map((item, i) => <div key={i} style={{

1266 display: 'flex',

1267 gap: '7px',

1268 fontSize: '15px',

1269 color: 'var(--ce-text-2)',

1270 lineHeight: 1.5,

1271 marginBottom: '5px'

1272 }}>

1273 <span style={{

1274 fontSize: '7px',

1275 color: 'var(--ce-text-4)',

1276 marginTop: '6px'

1277 }}>●</span>

1278 <span>{item}</span>

1279 </div>)}

1280 </div>}

1281 

1282 {}

1283 {selected.tips && selected.tips.length > 0 && <div style={{

1284 padding: '12px 14px',

1285 borderRadius: '8px',

1286 background: 'var(--ce-surface)',

1287 border: '1px solid var(--ce-border-subtle)',

1288 marginBottom: '16px'

1289 }}>

1290 <div style={{

1291 fontSize: '11px',

1292 fontWeight: 700,

1293 color: 'var(--ce-accent)',

1294 textTransform: 'uppercase',

1295 letterSpacing: '0.4px',

1296 marginBottom: '6px'

1297 }}>Tips</div>

1298 {selected.tips.map((tip, i) => <div key={i} style={{

1299 display: 'flex',

1300 gap: '7px',

1301 fontSize: '14.5px',

1302 color: 'var(--ce-text-2)',

1303 marginBottom: i < selected.tips.length - 1 ? '5px' : 0

1304 }}>

1305 <span style={{

1306 fontSize: '7px',

1307 color: 'var(--ce-accent)',

1308 marginTop: '6px'

1309 }}>●</span>

1310 <span>{tip}</span>

1311 </div>)}

1312 </div>}

1313 

1314 {}

1315 {selected.example && <div style={{

1316 marginBottom: '16px'

1317 }}>

1318 {selected.exampleIntro && <div style={{

1319 fontSize: '15px',

1320 color: 'var(--ce-text-2)',

1321 lineHeight: 1.6,

1322 marginBottom: '10px'

1323 }}>

1324 {selected.exampleIntro}

1325 </div>}

1326 <div style={{

1327 display: 'flex',

1328 justifyContent: 'space-between',

1329 alignItems: 'center',

1330 padding: '6px 10px',

1331 background: 'var(--ce-code-header)',

1332 border: '1px solid var(--ce-border)',

1333 borderRadius: '8px 8px 0 0'

1334 }}>

1335 <span style={{

1336 fontFamily: 'var(--ce-mono)',

1337 fontSize: '11px',

1338 fontWeight: 600,

1339 color: 'var(--ce-text-3)'

1340 }}>{selected.label}</span>

1341 <button onClick={() => copyExample(selected.id, selected.example)} style={{

1342 padding: '3px 8px',

1343 borderRadius: '4px',

1344 fontSize: '11px',

1345 fontWeight: 600,

1346 cursor: 'pointer',

1347 transition: 'all 0.15s',

1348 background: isCopied ? 'rgba(85,138,66,0.08)' : 'var(--ce-code-header)',

1349 border: isCopied ? '0.5px solid rgba(85,138,66,0.2)' : '0.5px solid var(--ce-border)',

1350 color: isCopied ? '#558A42' : 'var(--ce-text-3)'

1351 }}>

1352 {isCopied ? '✓ Copied' : 'Copy'}

1353 </button>

1354 </div>

1355 <pre style={{

1356 margin: 0,

1357 padding: '12px 14px',

1358 background: 'var(--ce-code-bg)',

1359 color: '#E8E6DC',

1360 fontFamily: 'var(--ce-mono)',

1361 fontSize: '13px',

1362 lineHeight: 1.65,

1363 borderRadius: '0 0 8px 8px',

1364 overflowX: 'auto',

1365 whiteSpace: 'pre'

1366 }}>{selected.example}</pre>

1367 </div>}

1368 

1369 {}

1370 {selected.docsLink && <a href={selected.docsLink} style={{

1371 display: 'inline-flex',

1372 padding: '5px 12px',

1373 borderRadius: '6px',

1374 background: 'var(--ce-accent-bg)',

1375 border: '1px solid var(--ce-accent-border)',

1376 color: 'var(--ce-accent)',

1377 fontSize: '12px',

1378 fontWeight: 600,

1379 textDecoration: 'none'

1380 }}>Full docs →</a>}

1381 

1382 {}

1383 {selected.children && selected.children.length > 0 && <div style={{

1384 marginTop: '20px'

1385 }}>

1386 <div style={{

1387 fontSize: '11px',

1388 fontWeight: 700,

1389 color: 'var(--ce-text-4)',

1390 textTransform: 'uppercase',

1391 letterSpacing: '0.4px',

1392 marginBottom: '8px'

1393 }}>Contents</div>

1394 <div style={{

1395 display: 'flex',

1396 flexDirection: 'column',

1397 gap: '4px'

1398 }}>

1399 {selected.children.map(child => <button key={child.id} onClick={() => selectNode(child)} style={{

1400 display: 'flex',

1401 alignItems: 'center',

1402 gap: '8px',

1403 padding: '6px 8px',

1404 width: '100%',

1405 background: 'var(--ce-surface)',

1406 borderRadius: '6px',

1407 border: 'none',

1408 cursor: 'pointer',

1409 textAlign: 'left',

1410 transition: 'background 0.1s'

1411 }} onMouseEnter={e => e.currentTarget.style.background = 'var(--ce-surface-hover)'} onMouseLeave={e => e.currentTarget.style.background = 'var(--ce-surface)'}>

1412 {renderIcon(child.icon, child.color, 13)}

1413 <span style={{

1414 fontFamily: 'var(--ce-mono)',

1415 fontSize: '12px',

1416 color: 'var(--ce-text-2)'

1417 }}>{child.label}</span>

1418 {child.oneLiner && <span style={{

1419 fontSize: '11px',

1420 color: 'var(--ce-text-4)',

1421 overflow: 'hidden',

1422 textOverflow: 'ellipsis',

1423 whiteSpace: 'nowrap'

1424 }}>{child.oneLiner}</span>}

1425 </button>)}

1426 </div>

1427 </div>}

1428 </div>

1429 </div>

1430 </>;

1431};

1432 

9Claude Code는 프로젝트 디렉토리와 홈 디렉토리의 `~/.claude`에서 지침, 설정, skills, subagents, 메모리를 읽습니다. 프로젝트 파일을 git에 커밋하여 팀과 공유합니다. `~/.claude`의 파일은 모든 프로젝트에 적용되는 개인 설정입니다.1433Claude Code는 프로젝트 디렉토리와 홈 디렉토리의 `~/.claude`에서 지침, 설정, skills, subagents, 메모리를 읽습니다. 프로젝트 파일을 git에 커밋하여 팀과 공유합니다. `~/.claude`의 파일은 모든 프로젝트에 적용되는 개인 설정입니다.

10 1434 

11Windows에서 `~/.claude`는 `%USERPROFILE%\.claude`로 확인됩니다. [`CLAUDE_CONFIG_DIR`](/ko/env-vars)을 설정하면, 이 페이지의 모든 `~/.claude` 경로가 대신 해당 디렉토리 아래에 있습니다.1435Windows에서 `~/.claude`는 `%USERPROFILE%\.claude`로 확인됩니다. [`CLAUDE_CONFIG_DIR`](/ko/env-vars)을 설정하면, 이 페이지의 모든 `~/.claude` 경로가 대신 해당 디렉토리 아래에 있습니다.


18 1442 

19트리의 파일을 클릭하여 각 파일이 무엇을 하는지, 언제 로드되는지, 예제를 확인합니다.1443트리의 파일을 클릭하여 각 파일이 무엇을 하는지, 언제 로드되는지, 예제를 확인합니다.

20 1444 

21<h2 id="what-s-not-shown">1445<ClaudeExplorer />

1446 

1447<h2 id="what’s-not-shown">

22 표시되지 않는 항목1448 표시되지 않는 항목

23</h2>1449</h2>

24 1450 

Details

6 6 

7> AWS 인증, IAM 액세스 제어 및 AWS Marketplace 청구를 사용하여 Anthropic 운영 Claude API를 사용하도록 Claude Code를 구성합니다.7> AWS 인증, IAM 액세스 제어 및 AWS Marketplace 청구를 사용하여 Anthropic 운영 Claude API를 사용하도록 Claude Code를 구성합니다.

8 8 

9export const ContactSalesCard = ({surface}) => {

10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;

11 const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

12 <line x1="5" y1="12" x2="19" y2="12" />

13 <polyline points="12 5 19 12 12 19" />

14 </svg>;

15 const STYLES = `

16.cc-cs {

17 --cs-slate: #141413;

18 --cs-clay: #d97757;

19 --cs-clay-deep: #c6613f;

20 --cs-gray-000: #ffffff;

21 --cs-gray-700: #3d3d3a;

22 --cs-border-default: rgba(31, 30, 29, 0.15);

23 font-family: inherit;

24}

25.dark .cc-cs {

26 --cs-slate: #f0eee6;

27 --cs-gray-000: #262624;

28 --cs-gray-700: #bfbdb4;

29 --cs-border-default: rgba(240, 238, 230, 0.14);

30}

31.cc-cs-card {

32 display: flex; align-items: center; justify-content: space-between;

33 gap: 16px; padding: 14px 16px; margin: 0;

34 background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default);

35 border-radius: 8px; flex-wrap: wrap;

36}

37.cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; }

38.cc-cs-text strong { font-weight: 550; color: var(--cs-slate); }

39.cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }

40.cc-cs-btn-clay {

41 display: inline-flex; align-items: center; gap: 8px;

42 background: var(--cs-clay-deep); color: #fff; border: none;

43 border-radius: 8px; padding: 8px 14px;

44 font-size: 13px; font-weight: 500;

45 transition: background-color 0.15s; white-space: nowrap;

46}

47.cc-cs-btn-clay:hover { background: var(--cs-clay); }

48.cc-cs-btn-ghost {

49 display: inline-flex; align-items: center; gap: 8px;

50 background: transparent; color: var(--cs-gray-700);

51 border: 0.5px solid var(--cs-border-default);

52 border-radius: 8px; padding: 8px 14px;

53 font-size: 13px; font-weight: 500;

54}

55.cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }

56.dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); }

57@media (max-width: 720px) {

58 .cc-cs-actions { width: 100%; }

59}

60`;

61 return <div className="cc-cs not-prose">

62 <style>{STYLES}</style>

63 <div className="cc-cs-card">

64 <div className="cc-cs-text">

65 <strong>Deploying Claude Code across your organization?</strong> Talk to sales about enterprise plans, SSO, and centralized billing.

66 </div>

67 <div className="cc-cs-actions">

68 <a href={`https://claude.com/pricing?${utm('view_plans')}#plans-business`} className="cc-cs-btn-ghost">

69 View plans

70 </a>

71 <a href={`https://claude.com/contact-sales?${utm('contact_sales')}`} className="cc-cs-btn-clay">

72 Contact sales {iconArrowRight()}

73 </a>

74 </div>

75 </div>

76 </div>;

77};

78 

79export const Experiment = ({flag, treatment, children}) => {

80 const VID_KEY = 'exp_vid';

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

82 const fnv1a = s => {

83 let h = 0x811c9dc5;

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

85 h ^= s.charCodeAt(i);

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

87 }

88 return h >>> 0;

89 };

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

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

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

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

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

95 if (force) {

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

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

98 if (k === flag) return {

99 variant: v || 'treatment',

100 track: false

101 };

102 }

103 }

104 if (navigator.globalPrivacyControl) {

105 return {

106 variant: 'control',

107 track: false

108 };

109 }

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

111 if (prefsMatch) {

112 try {

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

114 return {

115 variant: 'control',

116 track: false

117 };

118 }

119 } catch {

120 return {

121 variant: 'control',

122 track: false

123 };

124 }

125 } else {

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

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

128 return {

129 variant: 'control',

130 track: false

131 };

132 }

133 }

134 let vid;

135 try {

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

137 if (ajsMatch) {

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

139 } else {

140 vid = localStorage.getItem(VID_KEY);

141 if (!vid) {

142 vid = crypto.randomUUID();

143 }

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

145 }

146 try {

147 localStorage.setItem(VID_KEY, vid);

148 } catch {}

149 } catch {

150 return {

151 variant: 'control',

152 track: false

153 };

154 }

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

156 return {

157 variant,

158 track: true,

159 vid

160 };

161 });

162 useEffect(() => {

163 if (!decision.track) return;

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

165 method: 'POST',

166 headers: {

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

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

169 },

170 body: JSON.stringify({

171 events: [{

172 event_type: 'GrowthbookExperimentEvent',

173 event_data: {

174 device_id: decision.vid,

175 anonymous_id: decision.vid,

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

177 experiment_id: flag,

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

179 environment: 'production'

180 }

181 }]

182 }),

183 keepalive: true

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

185 }, []);

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

187};

188 

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

190 

9AWS의 Claude Platform은 AWS 인증, IAM 액세스 제어 및 AWS Marketplace 청구를 지원하는 Anthropic 운영 Claude API입니다. 요청은 Anthropic의 API에 직접 도달하므로 동일한 릴리스 일정에 따라 [Claude API](https://platform.claude.com/docs)와 동일한 모델 및 기능을 사용할 수 있습니다. AWS 자격 증명 또는 워크스페이스 API 키로 인증하며, AWS Marketplace를 통해 비용을 지불합니다.191AWS의 Claude Platform은 AWS 인증, IAM 액세스 제어 및 AWS Marketplace 청구를 지원하는 Anthropic 운영 Claude API입니다. 요청은 Anthropic의 API에 직접 도달하므로 동일한 릴리스 일정에 따라 [Claude API](https://platform.claude.com/docs)와 동일한 모델 및 기능을 사용할 수 있습니다. AWS 자격 증명 또는 워크스페이스 API 키로 인증하며, AWS Marketplace를 통해 비용을 지불합니다.

10 192 

11이 가이드를 사용하여 Claude Platform on AWS를 통해 이미 프로비저닝한 워크스페이스를 가리키도록 Claude Code를 설정합니다. 이 전에 필요한 AWS 구독 및 워크스페이스 설정은 [Claude Platform on AWS 설명서](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws)를 참조하십시오.193이 가이드를 사용하여 Claude Platform on AWS를 통해 이미 프로비저닝한 워크스페이스를 가리키도록 Claude Code를 설정합니다. 이 전에 필요한 AWS 구독 및 워크스페이스 설정은 [Claude Platform on AWS 설명서](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws)를 참조하십시오.


92 3. 모델 버전 고정274 3. 모델 버전 고정

93</h3>275</h3>

94 276 

95Claude Platform on AWS는 직접 Claude API와 동일한 모델 ID를 사용합니다. 기본 별칭 `opus`, `sonnet` 및 `haiku`는 워크스페이스에서 사용 가능한 최신 버전으로 확인됩니다.277Claude Platform on AWS는 직접 Claude API와 동일한 모델 ID를 사용합니다. 기본 별칭 `fable`, `opus`, `sonnet` 및 `haiku`는 Claude Platform on AWS에 대한 Claude Code의 기본 제공 기본값으로 확인되며, 이는 최신 릴리스보다 뒤떨어질 수 있습니다. `ANTHROPIC_DEFAULT_OPUS_MODEL` 없이 `opus` 별칭은 Opus 4.7로 확인됩니다.

96 278 

97Claude Code를 팀에 배포하는 경우 모델 ID를 명시적으로 고정하여 새 릴리스가 모든 사람을 한 번에 이동하지 않도록 하십시오.279Claude Code를 팀에 배포하는 경우 모델 ID를 명시적으로 고정하여 새 릴리스가 모든 사람을 한 번에 이동하지 않도록 하십시오.

98 280 

99```bash theme={null}281```bash theme={null}

282export ANTHROPIC_DEFAULT_FABLE_MODEL=claude-fable-5

100export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7283export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7

101export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6284export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6

102export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5285export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5


157 모든 요청에서 `403 Forbidden` 또는 `AccessDenied`340 모든 요청에서 `403 Forbidden` 또는 `AccessDenied`

158</h3>341</h3>

159 342 

160Claude Code가 확인한 IAM 주체는 워크스페이스에서 Anthropic 서비스를 호출할 수 있는 권한이 없을 가능성이 높습니다. AWS 프로필에 연결된 역할 또는 Claude Code를 시작한 실행기를 확인하고 [IAM 작업 참조](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions)에 설명된 `aws-external-anthropic` 작업이 있는지 확인하십시오.343Claude Code가 확인한 IAM 주체는 워크스페이스에서 Anthropic 서비스를 호출할 수 있는 권한이 없을 가능성이 높습니다. AWS 프로필에 연결된 역할 또는 Claude Code를 시작한 실행기를 확인하고 [IAM 작업 참조](https://platform.claude.com/docs/ko/api/claude-platform-on-aws-iam-actions)에 설명된 `aws-external-anthropic` 작업이 있는지 확인하십시오.

161 344 

162`ANTHROPIC_AWS_API_KEY`를 설정한 경우 키가 SigV4보다 우선하고 오래된 키는 동일한 오류를 생성합니다. AWS Console의 **Claude Platform on AWS → API keys** 아래에서 키를 다시 생성하거나 변수를 해제하여 AWS 자격 증명으로 돌아가십시오.345`ANTHROPIC_AWS_API_KEY`를 설정한 경우 키가 SigV4보다 우선하고 오래된 키는 동일한 오류를 생성합니다. AWS Console의 **Claude Platform on AWS → API keys** 아래에서 키를 다시 생성하거나 변수를 해제하여 AWS 자격 증명으로 돌아가십시오.

163 346 


179 362 

180Claude Code 구성 전에 필요한 Claude Platform on AWS 구독, 워크스페이스 및 IAM 설정은 플랫폼 설명서에서 다룹니다.363Claude Code 구성 전에 필요한 Claude Platform on AWS 구독, 워크스페이스 및 IAM 설정은 플랫폼 설명서에서 다룹니다.

181 364 

182* [Claude Platform on AWS 개요](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws): 구독, 워크스페이스 설정 및 제품 참조365* [Claude Platform on AWS 개요](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws): 구독, 워크스페이스 설정 및 제품 참조

183* [IAM 작업 참조](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions): 권한 및 관리형 정책366* [IAM 작업 참조](https://platform.claude.com/docs/ko/api/claude-platform-on-aws-iam-actions): 권한 및 관리형 정책

cli-reference.md +13 −11

Details

13이러한 명령어를 사용하여 세션을 시작하고, 콘텐츠를 파이프하고, 대화를 재개하고, 업데이트를 관리할 수 있습니다:13이러한 명령어를 사용하여 세션을 시작하고, 콘텐츠를 파이프하고, 대화를 재개하고, 업데이트를 관리할 수 있습니다:

14 14 

15| 명령어 | 설명 | 예시 |15| 명령어 | 설명 | 예시 |

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

17| `claude` | 대화형 세션 시작 | `claude` |17| `claude` | 대화형 세션 시작 | `claude` |

18| `claude "query"` | 초기 프롬프트로 대화형 세션 시작 | `claude "explain this project"` |18| `claude "query"` | 초기 프롬프트로 대화형 세션 시작 | `claude "explain this project"` |

19| `claude -p "query"` | SDK를 통해 쿼리하고 종료 | `claude -p "explain this function"` |19| `claude -p "query"` | SDK를 통해 쿼리하고 종료 | `claude -p "explain this function"` |


26| `claude auth login` | Anthropic 계정에 로그인합니다. `--email`을 사용하여 이메일 주소를 미리 입력하고, `--sso`를 사용하여 SSO 인증을 강제하고, `--console`을 사용하여 Claude 구독 대신 API 사용 청구를 위해 Anthropic Console로 로그인할 수 있습니다 | `claude auth login --console` |26| `claude auth login` | Anthropic 계정에 로그인합니다. `--email`을 사용하여 이메일 주소를 미리 입력하고, `--sso`를 사용하여 SSO 인증을 강제하고, `--console`을 사용하여 Claude 구독 대신 API 사용 청구를 위해 Anthropic Console로 로그인할 수 있습니다 | `claude auth login --console` |

27| `claude auth logout` | Anthropic 계정에서 로그아웃합니다 | `claude auth logout` |27| `claude auth logout` | Anthropic 계정에서 로그아웃합니다 | `claude auth logout` |

28| `claude auth status` | 인증 상태를 JSON으로 표시합니다. 사람이 읽을 수 있는 출력을 위해 `--text`를 사용합니다. 로그인된 경우 코드 0으로 종료되고, 로그인되지 않은 경우 1로 종료됩니다 | `claude auth status` |28| `claude auth status` | 인증 상태를 JSON으로 표시합니다. 사람이 읽을 수 있는 출력을 위해 `--text`를 사용합니다. 로그인된 경우 코드 0으로 종료되고, 로그인되지 않은 경우 1로 종료됩니다 | `claude auth status` |

29| `claude agents` | [에이전트 보기](/ko/agent-view)를 열어 병렬 백그라운드 세션을 모니터링하고 디스패치합니다. `--cwd <path>`를 사용하여 해당 디렉토리 아래에서 시작된 세션만 표시하거나, `--json`을 사용하여 스크립팅을 위해 라이브 세션을 JSON 배열로 인쇄합니다. `--permission-mode`, `--model`, `--effort` 또는 `--agent`를 전달하여 [디스패치된 세션의 기본값](/ko/agent-view#permission-mode-model-and-effort)을 설정합니다. 최상위 `claude` 명령어처럼 `--settings`, `--add-dir`, `--plugin-dir` 및 `--mcp-config`를 허용합니다. 에이전트 보기를 열려면 대화형 터미널이 필요합니다 | `claude agents --json` |29| `claude agents` | [에이전트 보기](/ko/agent-view)를 열어 병렬 백그라운드 세션을 모니터링하고 디스패치합니다. `--cwd <path>`를 사용하여 해당 디렉토리 아래에서 시작된 세션만 표시하거나, `--json`을 사용하여 스크립팅을 위해 활성 세션을 JSON 배열로 인쇄합니다(`--json --all`은 완료된 백그라운드 세션도 포함합니다). `--permission-mode`, `--model`, `--effort` 또는 `--agent`를 전달하여 [디스패치된 세션의 기본값](/ko/agent-view#permission-mode-model-and-effort)을 설정합니다. 최상위 `claude` 명령어처럼 `--settings`, `--add-dir`, `--plugin-dir` 및 `--mcp-config`를 허용합니다. 에이전트 보기를 열려면 대화형 터미널이 필요합니다 | `claude agents --json` |

30| `claude attach <id>` | 이 터미널에서 [백그라운드 세션](/ko/agent-view#manage-sessions-from-the-shell)에 연결합니다 | `claude attach 7c5dcf5d` |30| `claude attach <id>` | 이 터미널에서 [백그라운드 세션](/ko/agent-view#manage-sessions-from-the-shell)에 연결합니다 | `claude attach 7c5dcf5d` |

31| `claude auto-mode defaults` | 기본 제공 [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기 규칙을 JSON으로 인쇄합니다. `claude auto-mode config`를 사용하여 설정이 적용된 유효한 구성을 확인합니다 | `claude auto-mode defaults > rules.json` |31| `claude auto-mode defaults` | 기본 제공 [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기 규칙을 JSON으로 인쇄합니다. `claude auto-mode config`를 사용하여 설정이 적용된 유효한 구성을 확인합니다 | `claude auto-mode defaults > rules.json` |

32| `claude daemon status` | 백그라운드 세션 [감독자](/ko/agent-view#the-supervisor-process)의 상태, 버전, 소켓 디렉토리 및 진단을 위한 워커 수를 인쇄합니다. 감독자가 실행 중이 아니면 1로 종료됩니다 | `claude daemon status` |32| `claude daemon status` | 백그라운드 세션 [감독자](/ko/agent-view#the-supervisor-process)의 상태, 버전, 소켓 디렉토리 및 진단을 위한 워커 수를 인쇄합니다. 감독자가 실행 중이 아니면 1로 종료됩니다 | `claude daemon status` |


51이러한 명령줄 플래그를 사용하여 Claude Code의 동작을 사용자 정의합니다. `claude --help`는 모든 플래그를 나열하지 않으므로, `--help`에 플래그가 없다고 해서 사용할 수 없다는 의미는 아닙니다.51이러한 명령줄 플래그를 사용하여 Claude Code의 동작을 사용자 정의합니다. `claude --help`는 모든 플래그를 나열하지 않으므로, `--help`에 플래그가 없다고 해서 사용할 수 없다는 의미는 아닙니다.

52 52 

53| 플래그 | 설명 | 예시 |53| 플래그 | 설명 | 예시 |

54| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- |54| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- |

55| `--add-dir` | Claude가 파일을 읽고 편집할 수 있는 추가 작업 디렉토리를 추가합니다. 파일 액세스를 부여합니다. 대부분의 `.claude/` 구성은 이러한 디렉토리에서 [검색되지 않습니다](/ko/permissions#additional-directories-grant-file-access-not-configuration). 각 경로가 디렉토리로 존재하는지 검증합니다. 이러한 디렉토리를 세션 간에 유지하려면 설정에서 [`permissions.additionalDirectories`](/ko/settings#permission-settings)를 설정합니다 | `claude --add-dir ../apps ../lib` |55| `--add-dir` | Claude가 파일을 읽고 편집할 수 있는 추가 작업 디렉토리를 추가합니다. 파일 액세스를 부여합니다. 대부분의 `.claude/` 구성은 이러한 디렉토리에서 [검색되지 않습니다](/ko/permissions#additional-directories-grant-file-access-not-configuration). 각 경로가 디렉토리로 존재하는지 검증합니다. 이러한 디렉토리를 세션 간에 유지하려면 설정에서 [`permissions.additionalDirectories`](/ko/settings#permission-settings)를 설정합니다 | `claude --add-dir ../apps ../lib` |

56| `--advisor <model>` | {/* min-version: 2.1.98 */}이 세션에 대해 서버 측 [advisor 도구](/ko/advisor)를 활성화합니다. 모델 별칭 사용: `opus`, `sonnet` 또는 `fable` ({/* min-version: 2.1.170 */}v2.1.170+) 또는 전체 모델 ID입니다. `advisorModel` 설정보다 우선합니다. Claude Code v2.1.98 이상이 필요합니다 | `claude --advisor opus` |

56| `--agent` | 현재 세션에 대한 에이전트를 지정합니다(`agent` 설정 재정의) | `claude --agent my-custom-agent` |57| `--agent` | 현재 세션에 대한 에이전트를 지정합니다(`agent` 설정 재정의) | `claude --agent my-custom-agent` |

57| `--agents` | JSON을 통해 사용자 정의 subagents를 동적으로 정의합니다. subagent [frontmatter](/ko/sub-agents#supported-frontmatter-fields)와 동일한 필드 이름과 에이전트의 지시사항에 대한 `prompt` 필드를 사용합니다 | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |58| `--agents` | JSON을 통해 사용자 정의 subagents를 동적으로 정의합니다. subagent [frontmatter](/ko/sub-agents#supported-frontmatter-fields)와 동일한 필드 이름과 에이전트의 지시사항에 대한 `prompt` 필드를 사용합니다 | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |

58| `--allow-dangerously-skip-permissions` | `Shift+Tab` 모드 사이클에 `bypassPermissions`를 추가합니다. 이를 통해 `plan`과 같은 다른 모드에서 시작하고 나중에 `bypassPermissions`로 전환할 수 있습니다. [권한 모드](/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode) 참조 | `claude --permission-mode plan --allow-dangerously-skip-permissions` |59| `--allow-dangerously-skip-permissions` | `Shift+Tab` 모드 사이클에 `bypassPermissions`를 추가합니다. 이를 통해 `plan`과 같은 다른 모드에서 시작하고 나중에 `bypassPermissions`로 전환할 수 있습니다. [권한 모드](/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode) 참조 | `claude --permission-mode plan --allow-dangerously-skip-permissions` |

59| `--allowedTools` | 권한 프롬프트 없이 실행되는 도구입니다. 패턴 매칭에 대해 [권한 규칙 구문](/ko/settings#permission-rule-syntax)을 참조하세요. 사용 가능한 도구를 제한하려면 `--tools`를 대신 사용하세요 | `"Bash(git log *)" "Bash(git diff *)" "Read"` |60| `--allowedTools`, `--allowed-tools` | 권한 프롬프트 없이 실행되는 도구입니다. 패턴 매칭에 대해 [권한 규칙 구문](/ko/settings#permission-rule-syntax)을 참조하세요. 사용 가능한 도구를 제한하려면 `--tools`를 대신 사용하세요 | `"Bash(git log *)" "Bash(git diff *)" "Read"` |

60| `--append-system-prompt` | 기본 시스템 프롬프트의 끝에 사용자 정의 텍스트를 추가합니다 | `claude --append-system-prompt "Always use TypeScript"` |61| `--append-system-prompt` | 기본 시스템 프롬프트의 끝에 사용자 정의 텍스트를 추가합니다 | `claude --append-system-prompt "Always use TypeScript"` |

61| `--append-system-prompt-file` | 파일에서 추가 시스템 프롬프트 텍스트를 로드하고 기본 프롬프트에 추가합니다 | `claude --append-system-prompt-file ./extra-rules.txt` |62| `--append-system-prompt-file` | 파일에서 추가 시스템 프롬프트 텍스트를 로드하고 기본 프롬프트에 추가합니다 | `claude --append-system-prompt-file ./extra-rules.txt` |

62| `--bare` | 최소 모드: hooks, skills, plugins, MCP 서버, 자동 메모리 및 CLAUDE.md의 자동 검색을 건너뜁니다. 스크립트된 호출이 더 빠르게 시작됩니다. Claude는 Bash, 파일 읽기 및 파일 편집 도구에 액세스할 수 있습니다. [`CLAUDE_CODE_SIMPLE`](/ko/env-vars)을 설정합니다. [bare 모드](/ko/headless#start-faster-with-bare-mode) 참조 | `claude --bare -p "query"` |63| `--bare` | 최소 모드: hooks, skills, plugins, MCP 서버, 자동 메모리 및 CLAUDE.md의 자동 검색을 건너뜁니다. 스크립트된 호출이 더 빠르게 시작됩니다. Claude는 Bash, 파일 읽기 및 파일 편집 도구에 액세스할 수 있습니다. [`CLAUDE_CODE_SIMPLE`](/ko/env-vars)을 설정합니다. [bare 모드](/ko/headless#start-faster-with-bare-mode) 참조 | `claude --bare -p "query"` |


70| `--debug` | 선택적 카테고리 필터링을 사용하여 디버그 모드를 활성화합니다(예: `"api,hooks"` 또는 `"!statsig,!file"`) | `claude --debug "api,mcp"` |71| `--debug` | 선택적 카테고리 필터링을 사용하여 디버그 모드를 활성화합니다(예: `"api,hooks"` 또는 `"!statsig,!file"`) | `claude --debug "api,mcp"` |

71| `--debug-file <path>` | 디버그 로그를 특정 파일 경로에 씁니다. 암묵적으로 디버그 모드를 활성화합니다. `CLAUDE_CODE_DEBUG_LOGS_DIR`보다 우선합니다 | `claude --debug-file /tmp/claude-debug.log` |72| `--debug-file <path>` | 디버그 로그를 특정 파일 경로에 씁니다. 암묵적으로 디버그 모드를 활성화합니다. `CLAUDE_CODE_DEBUG_LOGS_DIR`보다 우선합니다 | `claude --debug-file /tmp/claude-debug.log` |

72| `--disable-slash-commands` | 이 세션에 대해 모든 skills 및 명령어를 비활성화합니다 | `claude --disable-slash-commands` |73| `--disable-slash-commands` | 이 세션에 대해 모든 skills 및 명령어를 비활성화합니다 | `claude --disable-slash-commands` |

73| `--disallowedTools` | 거부 규칙입니다. 단순 도구 이름은 모델의 컨텍스트에서 해당 도구를 제거합니다. `Bash(rm *)`과 같은 범위 지정 규칙은 도구를 사용 가능하게 유지하고 일치하는 호출만 거부합니다 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |74| `--disallowedTools`, `--disallowed-tools` | 거부 규칙입니다. 단순 도구 이름은 모델의 컨텍스트에서 해당 도구를 제거합니다: `"Edit"`는 Edit를 제거하고, `"*"`는 모든 도구를 제거하며, `"mcp__*"`는 모든 MCP 도구를 제거합니다. `Bash(rm *)`과 같은 범위 지정 규칙은 도구를 사용 가능하게 유지하고 일치하는 호출만 거부합니다 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |

74| `--effort` | 현재 세션에 대한 [노력 수준](/ko/model-config#adjust-effort-level)을 설정합니다. 옵션: `low`, `medium`, `high`, `xhigh`, `max`; 사용 가능한 수준은 모델에 따라 다릅니다. [`effortLevel`](/ko/settings#available-settings) 설정을 이 세션에 대해 재정의하며 지속되지 않습니다 | `claude --effort high` |75| `--effort` | 현재 세션에 대한 [노력 수준](/ko/model-config#adjust-effort-level)을 설정합니다. 옵션: `low`, `medium`, `high`, `xhigh`, `max`; 사용 가능한 수준은 모델에 따라 다릅니다. [`effortLevel`](/ko/settings#available-settings) 설정을 이 세션에 대해 재정의하며 지속되지 않습니다 | `claude --effort high` |

75| `--enable-auto-mode` | {/* max-version: 2.1.110 */}v2.1.111에서 제거됨. 자동 모드는 이제 `Shift+Tab` 사이클에 기본적으로 포함됩니다. `--permission-mode auto`를 사용하여 시작합니다 | `claude --permission-mode auto` |76| `--enable-auto-mode` | {/* max-version: 2.1.110 */}v2.1.111에서 제거됨. 자동 모드는 이제 `Shift+Tab` 사이클에 기본적으로 포함됩니다. `--permission-mode auto`를 사용하여 시작합니다 | `claude --permission-mode auto` |

76| `--exclude-dynamic-system-prompt-sections` | 시스템 프롬프트의 머신별 섹션(작업 디렉토리, 환경 정보, 메모리 경로, git 상태)을 첫 번째 사용자 메시지로 이동합니다. 동일한 작업을 실행하는 다양한 사용자 및 머신 간에 프롬프트 캐시 재사용을 개선합니다. 기본 시스템 프롬프트에만 적용됩니다. `--system-prompt` 또는 `--system-prompt-file`이 설정되면 무시됩니다. 스크립트된 다중 사용자 워크로드의 경우 `-p`와 함께 사용합니다 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |77| `--exclude-dynamic-system-prompt-sections` | 시스템 프롬프트의 머신별 섹션(작업 디렉토리, 환경 정보, 메모리 경로, git 상태)을 첫 번째 사용자 메시지로 이동합니다. 동일한 작업을 실행하는 다양한 사용자 및 머신 간에 프롬프트 캐시 재사용을 개선합니다. 기본 시스템 프롬프트에만 적용됩니다. `--system-prompt` 또는 `--system-prompt-file`이 설정되면 무시됩니다. 스크립트된 다중 사용자 워크로드의 경우 `-p`와 함께 사용합니다 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |

77| `--exec` | 셸 명령어를 Claude 세션을 시작하는 대신 PTY 기반 백그라운드 작업으로 실행합니다. `--bg`와 함께 사용하여 셸에서 시작합니다 | `claude --bg --exec 'pytest -x'` |78| `--exec` | 셸 명령어를 Claude 세션을 시작하는 대신 PTY 기반 백그라운드 작업으로 실행합니다. `--bg`와 함께 사용하여 셸에서 시작합니다 | `claude --bg --exec 'pytest -x'` |

78| `--fallback-model` | 기본 모델이 과부하 상태이거나 사용할 수 없을 때 지정된 모델로 자동 폴백을 활성화합니다(예: 폐기된 모델). 인쇄 모드(`-p`) [백그라운드 세션](/ko/agent-view)에서 적용되며, 이는 비대화형으로 실행됩니다. 대화형 세션에서는 무시됩니다 | `claude -p --fallback-model sonnet "query"` |79| `--fallback-model` | 기본 모델이 과부하 상태이거나 사용할 수 없을 때 지정된 모델로 자동 폴백을 활성화합니다(예: 폐기된 모델). 쉼표로 구분된 목록을 순서대로 시도합니다. [폴백 모델 체인](/ko/model-config#fallback-model-chains) 참조. 세션 간에 체인을 유지하려면 [`fallbackModel` 설정](/ko/settings#available-settings) 사용하며, 플래그가 이를 재정의합니다 | `claude --fallback-model sonnet,haiku` |

79| `--fork-session` | 재개할 때 원본을 재사용하는 대신 새 세션 ID를 생성합니다(`--resume` 또는 `--continue`와 함께 사용) | `claude --resume abc123 --fork-session` |80| `--fork-session` | 재개할 때 원본을 재사용하는 대신 새 세션 ID를 생성합니다(`--resume` 또는 `--continue`와 함께 사용) | `claude --resume abc123 --fork-session` |

80| `--from-pr` | 특정 pull request에 연결된 세션을 재개합니다. PR 번호, GitHub 또는 GitHub Enterprise PR URL, GitLab merge request URL 또는 Bitbucket pull request URL을 허용합니다. Claude가 pull request를 생성할 때 세션이 자동으로 연결됩니다 | `claude --from-pr 123` |81| `--from-pr` | 특정 pull request에 연결된 세션을 재개합니다. PR 번호, GitHub 또는 GitHub Enterprise PR URL, GitLab merge request URL 또는 Bitbucket pull request URL을 허용합니다. Claude가 pull request를 생성할 때 세션이 자동으로 연결됩니다 | `claude --from-pr 123` |

81| `--ide` | 정확히 하나의 유효한 IDE를 사용할 수 있는 경우 시작 시 IDE에 자동으로 연결합니다 | `claude --ide` |82| `--ide` | 정확히 하나의 유효한 IDE를 사용할 수 있는 경우 시작 시 IDE에 자동으로 연결합니다 | `claude --ide` |

82| `--init` | [Setup hooks](/ko/hooks#setup)를 `init` 매처로 실행한 후 세션을 시작합니다(인쇄 모드만 해당) | `claude -p --init "query"` |83| `--init` | [Setup hooks](/ko/hooks#setup)를 `init` 매처로 실행한 후 세션을 시작합니다(인쇄 모드만 해당) | `claude -p --init "query"` |

83| `--init-only` | [Setup](/ko/hooks#setup) 및 `SessionStart` hooks를 실행한 후 대화를 시작하지 않고 종료합니다 | `claude --init-only` |84| `--init-only` | [Setup](/ko/hooks#setup) 및 `SessionStart` hooks를 실행한 후 대화를 시작하지 않고 종료합니다 | `claude --init-only` |

84| `--include-hook-events` | 모든 hook 라이프사이클 이벤트를 출력 스트림에 포함합니다. `--output-format stream-json`이 필요합니다 | `claude -p --output-format stream-json --include-hook-events "query"` |85| `--include-hook-events` | 모든 hook 라이프사이클 이벤트를 출력 스트림에 포함합니다. `--output-format stream-json`이 필요합니다 | `claude -p --output-format stream-json --verbose --include-hook-events "query"` |

85| `--include-partial-messages` | 부분 스트리밍 이벤트를 출력에 포함합니다. `--print`와 `--output-format stream-json`이 필요합니다 | `claude -p --output-format stream-json --include-partial-messages "query"` |86| `--include-partial-messages` | 부분 스트리밍 이벤트를 출력에 포함합니다. `--print`와 `--output-format stream-json`이 필요합니다 | `claude -p --output-format stream-json --verbose --include-partial-messages "query"` |

86| `--input-format` | 인쇄 모드에 대한 입력 형식을 지정합니다(옵션: `text`, `stream-json`) | `claude -p --output-format json --input-format stream-json` |87| `--input-format` | 인쇄 모드에 대한 입력 형식을 지정합니다(옵션: `text`, `stream-json`) | `claude -p --output-format json --input-format stream-json` |

87| `--json-schema` | 에이전트가 워크플로우를 완료한 후 JSON Schema와 일치하는 검증된 JSON 출력을 가져옵니다(인쇄 모드만 해당, [구조화된 출력](/ko/agent-sdk/structured-outputs) 참조) | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |88| `--json-schema` | 에이전트가 워크플로우를 완료한 후 JSON Schema와 일치하는 검증된 JSON 출력을 가져옵니다(인쇄 모드만 해당, [구조화된 출력](/ko/agent-sdk/structured-outputs) 참조) | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |

88| `--maintenance` | [Setup hooks](/ko/hooks#setup)를 `maintenance` 매처로 실행한 후 세션을 시작합니다(인쇄 모드만 해당) | `claude -p --maintenance "query"` |89| `--maintenance` | [Setup hooks](/ko/hooks#setup)를 `maintenance` 매처로 실행한 후 세션을 시작합니다(인쇄 모드만 해당) | `claude -p --maintenance "query"` |

89| `--max-budget-usd` | 중지하기 전에 API 호출에 소비할 최대 달러 금액(인쇄 모드만 해당) | `claude -p --max-budget-usd 5.00 "query"` |90| `--max-budget-usd` | 중지하기 전에 API 호출에 소비할 최대 달러 금액(인쇄 모드만 해당) | `claude -p --max-budget-usd 5.00 "query"` |

90| `--max-turns` | 에이전트 턴의 수를 제한합니다(인쇄 모드만 해당). 제한에 도달하면 오류로 종료됩니다. 기본적으로 제한 없음 | `claude -p --max-turns 3 "query"` |91| `--max-turns` | 에이전트 턴의 수를 제한합니다(인쇄 모드만 해당). 제한에 도달하면 오류로 종료됩니다. 기본적으로 제한 없음 | `claude -p --max-turns 3 "query"` |

91| `--mcp-config` | JSON 파일 또는 문자열에서 MCP 서버를 로드합니다(공백으로 구분) | `claude --mcp-config ./mcp.json` |92| `--mcp-config` | JSON 파일 또는 문자열에서 MCP 서버를 로드합니다(공백으로 구분) | `claude --mcp-config ./mcp.json` |

92| `--model` | 최신 모델의 별칭(`sonnet` 또는 `opus`) 또는 모델의 전체 이름으로 현재 세션에 대한 모델을 설정합니다. [`model`](/ko/settings#available-settings) 설정 및 [`ANTHROPIC_MODEL`](/ko/model-config#environment-variables)을 재정의합니다 | `claude --model claude-sonnet-4-6` |93| `--model` | 최신 모델의 별칭(`sonnet`, `opus`, `haiku` 또는 `fable`) 또는 모델의 전체 이름으로 현재 세션에 대한 모델을 설정합니다. [`model`](/ko/settings#available-settings) 설정 및 [`ANTHROPIC_MODEL`](/ko/model-config#environment-variables)을 재정의합니다 | `claude --model claude-sonnet-4-6` |

93| `--name`, `-n` | 세션의 표시 이름을 설정합니다. `/resume`과 터미널 제목에 표시됩니다. `claude --resume <name>`으로 명명된 세션을 재개할 수 있습니다. <br /><br />[`/rename`](/ko/commands)은 세션 중에 이름을 변경하고 프롬프트 표시줄에도 표시합니다 | `claude -n "my-feature-work"` |94| `--name`, `-n` | 세션의 표시 이름을 설정합니다. `/resume`과 터미널 제목에 표시됩니다. `claude --resume <name>`으로 명명된 세션을 재개할 수 있습니다. <br /><br />[`/rename`](/ko/commands)은 세션 중에 이름을 변경하고 프롬프트 표시줄에도 표시합니다 | `claude -n "my-feature-work"` |

94| `--no-chrome` | 이 세션에 대해 [Chrome 브라우저 통합](/ko/chrome)을 비활성화합니다 | `claude --no-chrome` |95| `--no-chrome` | 이 세션에 대해 [Chrome 브라우저 통합](/ko/chrome)을 비활성화합니다 | `claude --no-chrome` |

95| `--no-session-persistence` | 세션 지속성을 비활성화하여 세션이 디스크에 저장되지 않고 재개할 수 없습니다(인쇄 모드만 해당). [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/ko/env-vars) 환경 변수는 모든 모드에서 동일한 작업을 수행합니다 | `claude -p --no-session-persistence "query"` |96| `--no-session-persistence` | 세션 지속성을 비활성화하여 세션이 디스크에 저장되지 않고 재개할 수 없습니다(인쇄 모드만 해당). [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/ko/env-vars) 환경 변수는 모든 모드에서 동일한 작업을 수행합니다 | `claude -p --no-session-persistence "query"` |


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

105| `--remote-control-session-name-prefix <prefix>` | 명시적 이름이 설정되지 않은 경우 자동 생성된 [Remote Control](/ko/remote-control) 세션 이름의 접두사입니다. 기본값은 머신의 호스트명이며, `myhost-graceful-unicorn`과 같은 이름을 생성합니다. 동일한 효과를 위해 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX`를 설정합니다 | `claude remote-control --remote-control-session-name-prefix dev-box` |106| `--remote-control-session-name-prefix <prefix>` | 명시적 이름이 설정되지 않은 경우 자동 생성된 [Remote Control](/ko/remote-control) 세션 이름의 접두사입니다. 기본값은 머신의 호스트명이며, `myhost-graceful-unicorn`과 같은 이름을 생성합니다. 동일한 효과를 위해 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX`를 설정합니다 | `claude remote-control --remote-control-session-name-prefix dev-box` |

106| `--replay-user-messages` | stdin에서 사용자 메시지를 다시 내보내 stdout으로 승인합니다. `--input-format stream-json`과 `--output-format stream-json`이 필요합니다 | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |107| `--replay-user-messages` | stdin에서 사용자 메시지를 다시 내보내 stdout으로 승인합니다. `--input-format stream-json`과 `--output-format stream-json`이 필요합니다 | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |

107| `--resume`, `-r` | ID 또는 이름으로 특정 세션을 재개하거나 세션을 선택할 수 있는 대화형 선택기를 표시합니다. `/add-dir`으로 이 디렉토리를 추가한 세션을 포함합니다. v2.1.144부터 [백그라운드 세션](/ko/agent-view)은 선택기에 `bg`로 표시됩니다 | `claude --resume auth-refactor` |108| `--resume`, `-r` | ID 또는 이름으로 특정 세션을 재개하거나 세션을 선택할 수 있는 대화형 선택기를 표시합니다. `/add-dir`으로 이 디렉토리를 추가한 세션을 포함합니다. 세션 ID를 전달하면 현재 프로젝트 디렉토리 및 해당 git worktrees만 검색합니다. v2.1.144부터 [백그라운드 세션](/ko/agent-view)은 선택기에 `bg`로 표시됩니다 | `claude --resume auth-refactor` |

109| `--safe-mode` | {/* min-version: 2.1.169 */}손상된 구성을 문제 해결하기 위해 모든 사용자 정의를 비활성화한 상태로 시작합니다: CLAUDE.md, skills, plugins, hooks, MCP 서버, 사용자 정의 명령어 및 에이전트, 출력 스타일, 워크플로우, 사용자 정의 테마, 사용자 정의 키 바인딩, 상태 줄 및 파일 제안 명령어, LSP 서버 및 자동 메모리가 로드되지 않습니다. 인증, 모델 선택, 기본 제공 도구 및 권한은 정상적으로 작동하며, 이는 [`--bare`](/ko/headless#start-faster-with-bare-mode)와 다릅니다. 관리되는 설정 정책은 여전히 적용되며, 정책 구성 hooks, 상태 줄 및 파일 제안 명령어를 포함합니다. 관리되는 plugins, 관리되는 skills, 관리되는 CLAUDE.md 및 정책 구성 MCP 서버는 로드되지 않습니다. [Fable 5에서 자동 폴백](/ko/model-config#automatic-model-fallback)을 트리거하는 사용자 정의인지 확인하는 데 유용합니다. [`CLAUDE_CODE_SAFE_MODE`](/ko/env-vars)를 설정합니다 | `claude --safe-mode` |

108| `--session-id` | 대화에 특정 세션 ID를 사용합니다(유효한 UUID여야 함) | `claude --session-id "550e8400-e29b-41d4-a716-446655440000"` |110| `--session-id` | 대화에 특정 세션 ID를 사용합니다(유효한 UUID여야 함) | `claude --session-id "550e8400-e29b-41d4-a716-446655440000"` |

109| `--setting-sources` | 로드할 설정 소스의 쉼표로 구분된 목록(`user`, `project`, `local`) | `claude --setting-sources user,project` |111| `--setting-sources` | 로드할 설정 소스의 쉼표로 구분된 목록(`user`, `project`, `local`) | `claude --setting-sources user,project` |

110| `--settings` | 설정 JSON 파일 또는 인라인 JSON 문자열의 경로입니다. 여기서 설정한 값은 이 세션에 대해 `settings.json` 파일의 동일한 키를 재정의합니다. 생략한 키는 파일 기반 값을 유지합니다. [설정 우선순위](/ko/settings#settings-precedence) 참조 | `claude --settings ./settings.json` |112| `--settings` | 설정 JSON 파일 또는 인라인 JSON 문자열의 경로입니다. 여기서 설정한 값은 이 세션에 대해 `settings.json` 파일의 동일한 키를 재정의합니다. 생략한 키는 파일 기반 값을 유지합니다. [설정 우선순위](/ko/settings#settings-precedence) 참조 | `claude --settings ./settings.json` |


114| `--teleport` | 로컬 터미널에서 [웹 세션](/ko/claude-code-on-the-web)을 재개합니다 | `claude --teleport` |116| `--teleport` | 로컬 터미널에서 [웹 세션](/ko/claude-code-on-the-web)을 재개합니다 | `claude --teleport` |

115| `--teammate-mode` | [에이전트 팀](/ko/agent-teams) 팀원 표시 방식을 설정합니다: `auto`(기본값), `in-process` 또는 `tmux`. [`teammateMode`](/ko/settings#available-settings) 설정을 이 세션에 대해 재정의합니다. [디스플레이 모드 선택](/ko/agent-teams#choose-a-display-mode) 참조 | `claude --teammate-mode in-process` |117| `--teammate-mode` | [에이전트 팀](/ko/agent-teams) 팀원 표시 방식을 설정합니다: `auto`(기본값), `in-process` 또는 `tmux`. [`teammateMode`](/ko/settings#available-settings) 설정을 이 세션에 대해 재정의합니다. [디스플레이 모드 선택](/ko/agent-teams#choose-a-display-mode) 참조 | `claude --teammate-mode in-process` |

116| `--tmux` | worktree에 대한 tmux 세션을 생성합니다. `--worktree`가 필요합니다. 사용 가능한 경우 iTerm2 네이티브 창을 사용합니다. 기존 tmux의 경우 `--tmux=classic`을 전달합니다 | `claude -w feature-auth --tmux` |118| `--tmux` | worktree에 대한 tmux 세션을 생성합니다. `--worktree`가 필요합니다. 사용 가능한 경우 iTerm2 네이티브 창을 사용합니다. 기존 tmux의 경우 `--tmux=classic`을 전달합니다 | `claude -w feature-auth --tmux` |

117| `--tools` | Claude가 사용할 수 있는 기본 제공 도구를 제한합니다. 모두 비활성화하려면 `""`를 사용하고, 모두 사용하려면 `"default"`를 사용하거나, `"Bash,Edit,Read"`와 같은 도구 이름을 사용합니다 | `claude --tools "Bash,Edit,Read"` |119| `--tools` | Claude가 사용할 수 있는 기본 제공 도구를 제한합니다. 모두 비활성화하려면 `""`를 사용하고, 모두 사용하려면 `"default"`를 사용하거나, `"Bash,Edit,Read"`와 같은 도구 이름을 사용합니다. MCP 도구는 영향을 받지 않습니다. 이들도 거부하려면 `--disallowedTools "mcp__*"`를 사용하거나, `--mcp-config` 없이 `--strict-mcp-config`를 전달하여 MCP 서버가 로드되지 않도록 합니다 | `claude --tools "Bash,Edit,Read"` |

118| `--verbose` | 자세한 로깅을 활성화하고 전체 턴별 출력을 표시합니다. [`viewMode`](/ko/settings#available-settings) 설정을 이 세션에 대해 재정의합니다 | `claude --verbose` |120| `--verbose` | 자세한 로깅을 활성화하고 전체 턴별 출력을 표시합니다. [`viewMode`](/ko/settings#available-settings) 설정을 이 세션에 대해 재정의합니다 | `claude --verbose` |

119| `--version`, `-v` | 버전 번호를 출력합니다 | `claude -v` |121| `--version`, `-v` | 버전 번호를 출력합니다 | `claude -v` |

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

code-review.md +66 −24

Details

30 GitHub 앱을 설치하지 않고 터미널에서 로컬로 diff를 검토하려면 Claude Code 세션에서 `/code-review` 명령을 실행하십시오. [로컬에서 diff 검토](#review-a-diff-locally)를 참조하십시오.30 GitHub 앱을 설치하지 않고 터미널에서 로컬로 diff를 검토하려면 Claude Code 세션에서 `/code-review` 명령을 실행하십시오. [로컬에서 diff 검토](#review-a-diff-locally)를 참조하십시오.

31</Note>31</Note>

32 32 

33## 검토 작동 방식33<h2 id="how-reviews-work">

34 검토 작동 방식

35</h2>

34 36 

35관리자가 조직에 대해 Code Review를 [활성화](#set-up-code-review)하면 리포지토리의 구성된 동작에 따라 PR이 열릴 때, 모든 푸시 시 또는 수동으로 요청할 때 검토가 트리거됩니다. PR에서 `@claude review`를 [댓글로 작성](#manually-trigger-reviews)하면 모든 모드에서 검토가 시작됩니다.37관리자가 조직에 대해 Code Review를 [활성화](#set-up-code-review)하면 리포지토리의 구성된 동작에 따라 PR이 열릴 때, 모든 푸시 시 또는 수동으로 요청할 때 검토가 트리거됩니다. PR에서 `@claude review`를 [댓글로 작성](#manually-trigger-reviews)하면 모든 모드에서 검토가 시작됩니다.

36 38 


38 40 

39검토는 PR 크기 및 복잡도에 따라 비용이 증가하며 평균 20분 내에 완료됩니다. 관리자는 [분석 대시보드](#view-usage)를 통해 검토 활동 및 지출을 모니터링할 수 있습니다.41검토는 PR 크기 및 복잡도에 따라 비용이 증가하며 평균 20분 내에 완료됩니다. 관리자는 [분석 대시보드](#view-usage)를 통해 검토 활동 및 지출을 모니터링할 수 있습니다.

40 42 

41### 심각도 수준43<h3 id="severity-levels">

44 심각도 수준

45</h3>

42 46 

43각 결과는 심각도 수준으로 태그가 지정됩니다:47각 결과는 심각도 수준으로 태그가 지정됩니다:

44 48 


50 54 

51결과에는 확장 가능한 확장 추론 섹션이 포함되어 있으므로 Claude가 문제를 플래그한 이유와 문제를 검증한 방법을 이해할 수 있습니다.55결과에는 확장 가능한 확장 추론 섹션이 포함되어 있으므로 Claude가 문제를 플래그한 이유와 문제를 검증한 방법을 이해할 수 있습니다.

52 56 

53### 결과에 대한 평가 및 응답57<h3 id="rate-and-reply-to-findings">

58 결과에 대한 평가 및 응답

59</h3>

54 60 

55Claude의 각 검토 댓글은 이미 👍 및 👎가 첨부되어 있으므로 두 버튼 모두 GitHub UI에 나타나 한 번의 클릭으로 평가할 수 있습니다. 결과가 유용했으면 👍을 클릭하고 잘못되었거나 노이즈가 많으면 👎를 클릭합니다. Anthropic은 PR이 병합된 후 반응 개수를 수집하고 이를 사용하여 검토자를 조정합니다. 반응은 재검토를 트리거하거나 PR의 어떤 것도 변경하지 않습니다.61Claude의 각 검토 댓글은 이미 👍 및 👎가 첨부되어 있으므로 두 버튼 모두 GitHub UI에 나타나 한 번의 클릭으로 평가할 수 있습니다. 결과가 유용했으면 👍을 클릭하고 잘못되었거나 노이즈가 많으면 👎를 클릭합니다. Anthropic은 PR이 병합된 후 반응 개수를 수집하고 이를 사용하여 검토자를 조정합니다. 반응은 재검토를 트리거하거나 PR의 어떤 것도 변경하지 않습니다.

56 62 

57인라인 댓글에 응답해도 Claude가 응답하거나 PR을 업데이트하도록 프롬프트하지 않습니다. 결과에 대해 조치하려면 코드를 수정하고 푸시합니다. PR이 푸시 트리거 검토에 구독되어 있으면 다음 실행이 문제가 수정되었을 때 스레드를 해결합니다. 푸시하지 않고 새로운 검토를 요청하려면 [최상위 PR 댓글](#manually-trigger-reviews)로 `@claude review once`를 댓글로 작성합니다.63인라인 댓글에 응답해도 Claude가 응답하거나 PR을 업데이트하도록 프롬프트하지 않습니다. 결과에 대해 조치하려면 코드를 수정하고 푸시합니다. PR이 푸시 트리거 검토에 구독되어 있으면 다음 실행이 문제가 수정되었을 때 스레드를 해결합니다. 푸시하지 않고 새로운 검토를 요청하려면 [최상위 PR 댓글](#manually-trigger-reviews)로 `@claude review once`를 댓글로 작성합니다.

58 64 

59### 확인 실행 출력65<h3 id="check-run-output">

66 확인 실행 출력

67</h3>

60 68 

61인라인 검토 댓글 외에도 각 검토는 CI 확인과 함께 나타나는 **Claude Code Review** 확인 실행을 채웁니다. **Details** 링크를 확장하여 심각도별로 정렬된 모든 결과의 요약을 한 곳에서 확인합니다:69인라인 검토 댓글 외에도 각 검토는 CI 확인과 함께 나타나는 **Claude Code Review** 확인 실행을 채웁니다. **Details** 링크를 확장하여 심각도별로 정렬된 모든 결과의 요약을 한 곳에서 확인합니다:

62 70 


76 84 

77이는 심각도별 개수가 포함된 JSON 객체를 반환합니다(예: `{"normal": 2, "nit": 1, "pre_existing": 0}`). `normal` 키는 Important 결과의 개수를 보유합니다. 0이 아닌 값은 Claude가 병합 전에 수정할 가치가 있는 버그를 발견했음을 의미합니다.85이는 심각도별 개수가 포함된 JSON 객체를 반환합니다(예: `{"normal": 2, "nit": 1, "pre_existing": 0}`). `normal` 키는 Important 결과의 개수를 보유합니다. 0이 아닌 값은 Claude가 병합 전에 수정할 가치가 있는 버그를 발견했음을 의미합니다.

78 86 

79### Code Review가 확인하는 항목87<h3 id="what-code-review-checks">

88 Code Review가 확인하는 항목

89</h3>

80 90 

81기본적으로 Code Review는 정확성에 중점을 두고 있습니다: 형식 기본 설정이나 누락된 테스트 범위가 아닌 프로덕션을 중단할 버그입니다. 리포지토리에 [지침 파일을 추가](#customize-reviews)하여 확인하는 항목을 확장할 수 있습니다.91기본적으로 Code Review는 정확성에 중점을 두고 있습니다: 형식 기본 설정이나 누락된 테스트 범위가 아닌 프로덕션을 중단할 버그입니다. 리포지토리에 [지침 파일을 추가](#customize-reviews)하여 확인하는 항목을 확장할 수 있습니다.

82 92 

83## Code Review 설정93<h2 id="set-up-code-review">

94 Code Review 설정

95</h2>

84 96 

85관리자는 조직에 대해 한 번 Code Review를 활성화하고 포함할 리포지토리를 선택합니다.97관리자는 조직에 대해 한 번 Code Review를 활성화하고 포함할 리포지토리를 선택합니다.

86 98 


122 134 

123설정을 확인하려면 테스트 PR을 열어보십시오. 자동 트리거를 선택한 경우 **Claude Code Review**라는 확인 실행이 몇 분 내에 나타납니다. 수동을 선택한 경우 PR에서 `@claude review`를 댓글로 작성하여 첫 번째 검토를 시작합니다. 확인 실행이 나타나지 않으면 리포지토리가 관리자 설정에 나열되어 있고 Claude GitHub 앱이 액세스할 수 있는지 확인하십시오.135설정을 확인하려면 테스트 PR을 열어보십시오. 자동 트리거를 선택한 경우 **Claude Code Review**라는 확인 실행이 몇 분 내에 나타납니다. 수동을 선택한 경우 PR에서 `@claude review`를 댓글로 작성하여 첫 번째 검토를 시작합니다. 확인 실행이 나타나지 않으면 리포지토리가 관리자 설정에 나열되어 있고 Claude GitHub 앱이 액세스할 수 있는지 확인하십시오.

124 136 

125## 수동으로 검토 트리거137<h2 id="manually-trigger-reviews">

138 수동으로 검토 트리거

139</h2>

126 140 

127두 개의 댓글 명령이 요청 시 검토를 시작합니다. 둘 다 리포지토리의 구성된 트리거와 관계없이 작동하므로 수동 모드에서 특정 PR을 검토에 옵트인하거나 다른 모드에서 즉시 재검토를 받을 수 있습니다.141두 개의 댓글 명령이 요청 시 검토를 시작합니다. 둘 다 리포지토리의 구성된 트리거와 관계없이 작동하므로 수동 모드에서 특정 PR을 검토에 옵트인하거나 다른 모드에서 즉시 재검토를 받을 수 있습니다.

128 142 


144 158 

145해당 PR에서 검토가 이미 실행 중인 경우 요청은 진행 중인 검토가 완료될 때까지 대기열에 추가됩니다. PR의 확인 실행을 통해 진행 상황을 모니터링할 수 있습니다.159해당 PR에서 검토가 이미 실행 중인 경우 요청은 진행 중인 검토가 완료될 때까지 대기열에 추가됩니다. PR의 확인 실행을 통해 진행 상황을 모니터링할 수 있습니다.

146 160 

147## 검토 사용자 정의161<h2 id="customize-reviews">

162 검토 사용자 정의

163</h2>

148 164 

149Code Review는 리포지토리에서 두 개의 파일을 읽어 플래그할 항목을 안내합니다. 이들은 검토에 영향을 미치는 강도가 다릅니다:165Code Review는 리포지토리에서 두 개의 파일을 읽어 플래그할 항목을 안내합니다. 이들은 검토에 영향을 미치는 강도가 다릅니다:

150 166 

151* **`CLAUDE.md`**: Claude Code가 검토뿐만 아니라 모든 작업에 사용하는 공유 프로젝트 지침입니다. Code Review는 이를 프로젝트 컨텍스트로 읽고 새로 도입된 위반을 nit으로 플래그합니다.167* **`CLAUDE.md`**: Claude Code가 검토뿐만 아니라 모든 작업에 사용하는 공유 프로젝트 지침입니다. Code Review는 이를 프로젝트 컨텍스트로 읽고 새로 도입된 위반을 nit으로 플래그합니다.

152* **`REVIEW.md`**: 검토 전용 지침으로 검토 파이프라인의 모든 에이전트에 최우선 순위로 직접 주입됩니다. 이를 사용하여 플래그되는 항목, 심각도 및 결과 보고 방식을 변경합니다.168* **`REVIEW.md`**: 검토 전용 지침으로 검토 파이프라인의 모든 에이전트에 최우선 순위로 직접 주입됩니다. 이를 사용하여 플래그되는 항목, 심각도 및 결과 보고 방식을 변경합니다.

153 169 

154### CLAUDE.md170<h3 id="claude-md">

171 CLAUDE.md

172</h3>

155 173 

156Code Review는 리포지토리의 `CLAUDE.md` 파일을 읽고 새로 도입된 위반을 [nit 수준](#severity-levels) 결과로 처리합니다. 이는 양방향으로 작동합니다: PR이 `CLAUDE.md` 문을 오래된 것으로 만드는 방식으로 코드를 변경하면 Claude는 문서도 업데이트해야 한다고 플래그합니다.174Code Review는 리포지토리의 `CLAUDE.md` 파일을 읽고 새로 도입된 위반을 [nit 수준](#severity-levels) 결과로 처리합니다. 이는 양방향으로 작동합니다: PR이 `CLAUDE.md` 문을 오래된 것으로 만드는 방식으로 코드를 변경하면 Claude는 문서도 업데이트해야 한다고 플래그합니다.

157 175 


159 177 

160일반 Claude Code 세션에 적용하지 않으려는 검토 전용 지침의 경우 대신 [`REVIEW.md`](#review-md)를 사용하십시오.178일반 Claude Code 세션에 적용하지 않으려는 검토 전용 지침의 경우 대신 [`REVIEW.md`](#review-md)를 사용하십시오.

161 179 

162### REVIEW\.md180<h3 id="review-md">

181 REVIEW\.md

182</h3>

163 183 

164`REVIEW.md`는 리포지토리 루트의 파일로 Code Review가 리포지토리에서 어떻게 작동하는지를 재정의합니다. 그 내용은 검토 파이프라인의 모든 에이전트의 시스템 프롬프트에 최우선 순위 지침 블록으로 주입되어 기본 검토 지침보다 우선합니다.184`REVIEW.md`는 리포지토리 루트의 파일로 Code Review가 리포지토리에서 어떻게 작동하는지를 재정의합니다. 그 내용은 검토 파이프라인의 모든 에이전트의 시스템 프롬프트에 최우선 순위 지침 블록으로 주입되어 기본 검토 지침보다 우선합니다.

165 185 

166그것이 그대로 붙여넣어지기 때문에 `REVIEW.md`는 일반 지침입니다: [`@` import 구문](/ko/memory#import-additional-files)은 확장되지 않으며 참조된 파일은 프롬프트로 읽혀지지 않습니다. 적용하려는 규칙을 파일에 직접 입력합니다.186그것이 그대로 붙여넣어지기 때문에 `REVIEW.md`는 일반 지침입니다: [`@` import 구문](/ko/memory#import-additional-files)은 확장되지 않으며 참조된 파일은 프롬프트로 읽혀지지 않습니다. 적용하려는 규칙을 파일에 직접 입력합니다.

167 187 

168#### 조정할 수 있는 항목188<h4 id="what-you-can-tune">

189 조정할 수 있는 항목

190</h4>

169 191 

170`REVIEW.md`는 자유 형식 마크다운이므로 검토 지침으로 표현할 수 있는 모든 것이 범위 내입니다. 아래 패턴은 실제로 가장 큰 영향을 미칩니다.192`REVIEW.md`는 자유 형식 마크다운이므로 검토 지침으로 표현할 수 있는 모든 것이 범위 내입니다. 아래 패턴은 실제로 가장 큰 영향을 미칩니다.

171 193 


183 205 

184**요약 형태**: 검토 본문이 `2 factual, 4 style`과 같은 한 줄 집계로 시작하도록 요청하고 그것이 경우일 때 "factual 문제 없음"으로 시작하도록 요청합니다. 작성자는 세부 사항 전에 작업의 형태를 알고 싶어합니다.206**요약 형태**: 검토 본문이 `2 factual, 4 style`과 같은 한 줄 집계로 시작하도록 요청하고 그것이 경우일 때 "factual 문제 없음"으로 시작하도록 요청합니다. 작성자는 세부 사항 전에 작업의 형태를 알고 싶어합니다.

185 207 

186#### 예시208<h4 id="example">

209 예시

210</h4>

187 211 

188이 `REVIEW.md`는 백엔드 서비스의 심각도를 재보정하고, nit을 제한하고, 생성된 파일을 건너뛰고, 리포지토리별 확인을 추가합니다.212이 `REVIEW.md`는 백엔드 서비스의 심각도를 재보정하고, nit을 제한하고, 생성된 파일을 건너뛰고, 리포지토리별 확인을 추가합니다.

189 213 


211- 데이터베이스 쿼리는 호출자의 테넌트로 범위가 지정됩니다235- 데이터베이스 쿼리는 호출자의 테넌트로 범위가 지정됩니다

212```236```

213 237 

214#### 초점 유지238<h4 id="keep-it-focused">

239 초점 유지

240</h4>

215 241 

216길이는 비용이 있습니다: 긴 `REVIEW.md`는 가장 중요한 규칙을 희석합니다. 검토 동작을 변경하는 지침으로 유지하고 일반 프로젝트 컨텍스트는 `CLAUDE.md`에 남겨둡니다.242길이는 비용이 있습니다: 긴 `REVIEW.md`는 가장 중요한 규칙을 희석합니다. 검토 동작을 변경하는 지침으로 유지하고 일반 프로젝트 컨텍스트는 `CLAUDE.md`에 남겨둡니다.

217 243 

218## 사용량 보기244<h2 id="view-usage">

245 사용량 보기

246</h2>

219 247 

220[claude.ai/analytics/code-review](https://claude.ai/analytics/code-review)로 이동하여 조직 전체의 Code Review 활동을 확인합니다. 대시보드는 다음을 표시합니다:248[claude.ai/analytics/code-review](https://claude.ai/analytics/code-review)로 이동하여 조직 전체의 Code Review 활동을 확인합니다. 대시보드는 다음을 표시합니다:

221 249 


228 256 

229관리자 설정의 리포지토리 테이블은 각 리포지토리의 검토당 평균 비용도 표시합니다. 대시보드 비용 수치는 활동 모니터링을 위한 추정치입니다. 청구서 정확한 지출의 경우 Anthropic 청구서를 참조하십시오.257관리자 설정의 리포지토리 테이블은 각 리포지토리의 검토당 평균 비용도 표시합니다. 대시보드 비용 수치는 활동 모니터링을 위한 추정치입니다. 청구서 정확한 지출의 경우 Anthropic 청구서를 참조하십시오.

230 258 

231## 가격259<h2 id="pricing">

260 가격

261</h2>

232 262 

233Code Review는 토큰 사용량을 기반으로 청구됩니다. 각 검토는 평균 \$15-25의 비용이 소요되며, PR 크기, 코드베이스 복잡도 및 검증이 필요한 문제의 수에 따라 확장됩니다. Code Review 사용량은 [사용량 크레딧](https://support.claude.com/ko/articles/12429409-extra-usage-for-paid-claude-plans)을 통해 별도로 청구되며 계획에 포함된 사용량에 포함되지 않습니다.263Code Review는 토큰 사용량을 기반으로 청구됩니다. 각 검토는 평균 \$15-25의 비용이 소요되며, PR 크기, 코드베이스 복잡도 및 검증이 필요한 문제의 수에 따라 확장됩니다. Code Review 사용량은 [사용량 크레딧](https://support.claude.com/ko/articles/12429409-extra-usage-for-paid-claude-plans)을 통해 별도로 청구되며 계획에 포함된 사용량에 포함되지 않습니다.

234 264 


244 274 

245[분석](#view-usage)의 주간 비용 차트 또는 관리자 설정의 리포지토리별 평균 비용 열을 통해 지출을 모니터링합니다.275[분석](#view-usage)의 주간 비용 차트 또는 관리자 설정의 리포지토리별 평균 비용 열을 통해 지출을 모니터링합니다.

246 276 

247## 문제 해결277<h2 id="troubleshooting">

278 문제 해결

279</h2>

248 280 

249검토 실행은 최선의 노력입니다. 실패한 실행은 PR을 차단하지 않지만 자동으로 재시도하지도 않습니다. 이 섹션에서는 실패한 실행에서 복구하는 방법과 확인 실행이 찾을 수 없는 문제를 보고할 때 어디를 봐야 하는지 다룹니다.281검토 실행은 최선의 노력입니다. 실패한 실행은 PR을 차단하지 않지만 자동으로 재시도하지도 않습니다. 이 섹션에서는 실패한 실행에서 복구하는 방법과 확인 실행이 찾을 수 없는 문제를 보고할 때 어디를 봐야 하는지 다룹니다.

250 282 

251### 실패하거나 시간 초과된 검토 재트리거283<h3 id="retrigger-a-failed-or-timed-out-review">

284 실패하거나 시간 초과된 검토 재트리거

285</h3>

252 286 

253검토 인프라가 내부 오류에 도달하거나 시간 제한을 초과하면 확인 실행이 **Code review encountered an error** 또는 **Code review timed out** 제목으로 완료됩니다. 결론은 여전히 중립적이므로 병합을 차단하는 것은 없지만 결과가 게시되지 않습니다.287검토 인프라가 내부 오류에 도달하거나 시간 제한을 초과하면 확인 실행이 **Code review encountered an error** 또는 **Code review timed out** 제목으로 완료됩니다. 결론은 여전히 중립적이므로 병합을 차단하는 것은 없지만 결과가 게시되지 않습니다.

254 288 


256 290 

257GitHub의 Checks 탭의 **Re-run** 버튼은 Code Review를 재트리거하지 않습니다. 댓글 명령이나 새 푸시를 대신 사용하십시오.291GitHub의 Checks 탭의 **Re-run** 버튼은 Code Review를 재트리거하지 않습니다. 댓글 명령이나 새 푸시를 대신 사용하십시오.

258 292 

259### 검토가 실행되지 않았고 PR이 지출 한도 메시지를 표시합니다293<h3 id="review-didn’t-run-and-the-pr-shows-a-spend-cap-message">

294 검토가 실행되지 않았고 PR이 지출 한도 메시지를 표시합니다

295</h3>

260 296 

261조직의 월간 지출 한도에 도달하면 Code Review는 검토가 건너뛰어졌음을 설명하는 단일 댓글을 PR에 게시합니다. 검토는 다음 청구 기간의 시작 시 자동으로 재개되거나 관리자가 [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage)에서 한도를 높일 때 즉시 재개됩니다.297조직의 월간 지출 한도에 도달하면 Code Review는 검토가 건너뛰어졌음을 설명하는 단일 댓글을 PR에 게시합니다. 검토는 다음 청구 기간의 시작 시 자동으로 재개되거나 관리자가 [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage)에서 한도를 높일 때 즉시 재개됩니다.

262 298 

263### 인라인 댓글로 표시되지 않는 문제 찾기299<h3 id="find-issues-that-aren’t-showing-as-inline-comments">

300 인라인 댓글로 표시되지 않는 문제 찾기

301</h3>

264 302 

265확인 실행 제목이 문제가 발견되었다고 말하지만 diff에서 인라인 검토 댓글을 보지 못하면 결과가 표시되는 다른 위치를 확인하십시오:303확인 실행 제목이 문제가 발견되었다고 말하지만 diff에서 인라인 검토 댓글을 보지 못하면 결과가 표시되는 다른 위치를 확인하십시오:

266 304 


268* **Files changed annotations**: PR의 **Files changed** 탭을 엽니다. 결과는 검토 댓글과 별도로 diff 라인에 직접 첨부된 주석으로 렌더링됩니다.306* **Files changed annotations**: PR의 **Files changed** 탭을 엽니다. 결과는 검토 댓글과 별도로 diff 라인에 직접 첨부된 주석으로 렌더링됩니다.

269* **Review body**: 검토가 실행 중인 동안 PR을 푸시한 경우 일부 결과는 현재 diff에 더 이상 존재하지 않는 라인을 참조할 수 있습니다. 이들은 인라인 댓글이 아닌 검토 본문 텍스트의 **Additional findings** 제목 아래에 나타납니다.307* **Review body**: 검토가 실행 중인 동안 PR을 푸시한 경우 일부 결과는 현재 diff에 더 이상 존재하지 않는 라인을 참조할 수 있습니다. 이들은 인라인 댓글이 아닌 검토 본문 텍스트의 **Additional findings** 제목 아래에 나타납니다.

270 308 

271## 로컬에서 diff 검토309<h2 id="review-a-diff-locally">

310 로컬에서 diff 검토

311</h2>

272 312 

273[`/code-review` 명령](/ko/commands)은 GitHub 앱을 설치하지 않고 터미널에서 diff를 검토합니다. Claude Code 세션에서 실행하십시오: 현재 diff의 정확성 버그 및 {/* min-version: 2.1.151 */}재사용, 단순화 및 효율성 정리를 보고합니다. `--comment`를 전달하여 결과를 인라인 PR 댓글로 게시하거나 `--fix`를 전달하여 검토 후 결과를 작업 트리에 적용합니다.313[`/code-review` 명령](/ko/commands)은 GitHub 앱을 설치하지 않고 터미널에서 diff를 검토합니다. Claude Code 세션에서 실행하십시오: 정확성 버그 및 {/* min-version: 2.1.151 */}재사용, 단순화 및 효율성 정리를 보고합니다. 기본적으로 로컬 검토는 업스트림보다 앞선 브랜치의 커밋과 작업 트리의 커밋되지 않은 변경 사항을 포함합니다. `--comment`를 전달하여 결과를 인라인 PR 댓글로 게시하거나 `--fix`를 전달하여 검토 후 결과를 작업 트리에 적용합니다.

274 314 

275낮은 [노력 수준](/ko/model-config#adjust-effort-level)은 더 적은 수의 높은 신뢰도 결과를 반환하는 반면, `high`부터 `max`까지는 더 광범위한 범위를 제공하며 불확실한 결과를 포함할 수 있습니다. 노력 인수 없이 검토는 세션의 현재 노력을 사용합니다. 현재 diff 대신 특정 대상을 검토하려면 경로 또는 PR 참조를 전달합니다.315낮은 [노력 수준](/ko/model-config#adjust-effort-level)은 더 적은 수의 높은 신뢰도 결과를 반환하는 반면, `high`부터 `max`까지는 더 광범위한 범위를 제공하며 불확실한 결과를 포함할 수 있습니다. 노력 인수 없이 검토는 세션의 현재 노력을 사용합니다. 기본 diff 대신 다른 항목을 검토하려면 대상을 전달합니다: 파일 경로, PR 번호, 브랜치 이름 또는 `main...my-feature`와 같은 ref 범위입니다. ref 범위 형식은 브랜치의 업스트림이 어떻게 구성되어 있는지와 관계없이 `my-feature`에서 `main`으로의 풀 요청이 포함할 커밋된 diff를 검토합니다.

276 316 

277`/code-review ultra --fix`는 클라우드에서 더 깊은 [ultrareview](/ko/ultrareview)를 실행한 다음 세션으로 돌아올 때 결과를 작업 트리에 적용합니다.317`/code-review ultra --fix`는 클라우드에서 더 깊은 [ultrareview](/ko/ultrareview)를 실행한 다음 세션으로 돌아올 때 결과를 작업 트리에 적용합니다. Ultrareview는 자체 범위를 사용합니다: 현재 브랜치와 저장소의 기본 브랜치, 그리고 작업 트리의 커밋되지 않은 및 스테이징된 변경 사항입니다.

278 318 

279이 명령은 v2.1.147 이전에 `/simplify`로 명명되었으며 기본적으로 수정 사항을 적용했습니다. {/* min-version: 2.1.154 */}v2.1.154부터 `/simplify`는 버그를 찾지 않고 수정 사항을 적용하는 별도의 정리 전용 검토를 실행합니다. 버그 찾기를 위해 `/simplify`를 스크립트했다면 변경되지 않은 `/code-review --fix`로 전환하십시오.319이 명령은 v2.1.147 이전에 `/simplify`로 명명되었으며 기본적으로 수정 사항을 적용했습니다. {/* min-version: 2.1.154 */}v2.1.154부터 `/simplify`는 버그를 찾지 않고 수정 사항을 적용하는 별도의 정리 전용 검토를 실행합니다. 버그 찾기를 위해 `/simplify`를 스크립트했다면 변경되지 않은 `/code-review --fix`로 전환하십시오.

280 320 

281## 관련 리소스321<h2 id="related-resources">

322 관련 리소스

323</h2>

282 324 

283Code Review는 Claude Code의 나머지 부분과 함께 작동하도록 설계되었습니다. PR을 열기 전에 로컬에서 검토를 실행하거나, 자체 호스팅 설정이 필요하거나, `CLAUDE.md`가 도구 전체에서 Claude의 동작을 형성하는 방식에 대해 더 깊이 알고 싶다면 다음 페이지가 좋은 다음 단계입니다:325Code Review는 Claude Code의 나머지 부분과 함께 작동하도록 설계되었습니다. PR을 열기 전에 로컬에서 검토를 실행하거나, 자체 호스팅 설정이 필요하거나, `CLAUDE.md`가 도구 전체에서 Claude의 동작을 형성하는 방식에 대해 더 깊이 알고 싶다면 다음 페이지가 좋은 다음 단계입니다:

284 326 

commands.md +26 −15

Details

12 12 

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

14 14 

15## 일반적인 워크플로우 전반의 명령어15<h2 id="commands-across-a-typical-workflow">

16 일반적인 워크플로우 전반의 명령어

17</h2>

16 18 

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

18 20 


28 30 

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

30 32 

31## 모든 명령어33<h2 id="all-commands">

34 모든 명령어

35</h2>

32 36 

33아래 표는 Claude Code에 포함된 모든 명령어를 나열합니다. 대부분은 CLI에 코딩된 동작을 가진 기본 제공 명령어입니다. 두 가지 종류의 항목이 표시됩니다:37아래 표는 Claude Code에 포함된 모든 명령어를 나열합니다. 대부분은 CLI에 코딩된 동작을 가진 기본 제공 명령어입니다. 두 가지 종류의 항목이 표시됩니다:

34 38 


46| 명령어 | 목적 |50| 명령어 | 목적 |

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

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

53| `/advisor [model\|off]` | {/* min-version: 2.1.98 */}[advisor tool](/ko/advisor)을 활성화 또는 비활성화합니다. 이 도구는 작업 중 주요 순간에 두 번째 모델에 지침을 요청합니다. `opus`, `sonnet`, `fable` ({/* min-version: 2.1.170 */}v2.1.170+) 또는 전체 모델 ID를 허용합니다. 인수 없이 선택기를 엽니다. Claude Code v2.1.98 이상이 필요합니다 |

49| `/agents` | [agent](/ko/sub-agents) 구성을 관리합니다 |54| `/agents` | [agent](/ko/sub-agents) 구성을 관리합니다 |

50| `/autofix-pr [prompt]` | 현재 브랜치의 PR을 감시하고 CI가 실패하거나 검토자가 댓글을 남길 때 수정 사항을 푸시하는 [Claude Code on the web](/ko/claude-code-on-the-web#auto-fix-pull-requests) 세션을 생성합니다. `gh pr view`를 사용하여 체크아웃된 브랜치에서 열린 PR을 감지합니다. 다른 PR을 감시하려면 먼저 해당 브랜치를 체크아웃하세요. 기본적으로 원격 세션은 모든 CI 실패 및 검토 댓글을 수정하도록 지시받습니다. 프롬프트를 전달하여 다른 지침을 제공합니다. 예를 들어 `/autofix-pr only fix lint and type errors`. `gh` CLI 및 [Claude Code on the web](/ko/claude-code-on-the-web#who-can-use-claude-code-on-the-web)에 대한 액세스가 필요합니다 |55| `/autofix-pr [prompt]` | 현재 브랜치의 PR을 감시하고 CI가 실패하거나 검토자가 댓글을 남길 때 수정 사항을 푸시하는 [Claude Code on the web](/ko/claude-code-on-the-web#auto-fix-pull-requests) 세션을 생성합니다. `gh pr view`를 사용하여 체크아웃된 브랜치에서 열린 PR을 감지합니다. 다른 PR을 감시하려면 먼저 해당 브랜치를 체크아웃하세요. 기본적으로 클라우드 세션은 모든 CI 실패 및 검토 댓글을 수정하도록 지시받습니다. 프롬프트를 전달하여 다른 지침을 제공합니다. 예를 들어 `/autofix-pr only fix lint and type errors`. `gh` CLI 및 [Claude Code on the web](/ko/claude-code-on-the-web)에 대한 액세스가 필요합니다 |

51| `/background [prompt]` | 현재 세션을 [background agent](/ko/agent-view)로 분리하여 실행하고 이 터미널을 해제합니다. 분리하기 전에 한 가지 더 지침을 보내려면 프롬프트를 전달합니다. `claude agents`로 세션을 모니터링합니다. 별칭: `/bg` |56| `/background [prompt]` | 현재 세션을 [background agent](/ko/agent-view)로 분리하여 실행하고 이 터미널을 해제합니다. 분리하기 전에 한 가지 더 지침을 보내려면 프롬프트를 전달합니다. `claude agents`로 세션을 모니터링합니다. 별칭: `/bg` |

52| `/batch <instruction>` | **[Skill](/ko/skills#bundled-skills).** 코드베이스 전체에서 대규모 변경 사항을 병렬로 조율합니다. 코드베이스를 연구하고, 작업을 5\~30개의 독립적인 단위로 분해하고, 계획을 제시합니다. 승인되면 격리된 [git worktree](/ko/worktrees)에서 단위당 하나의 [background subagent](/ko/sub-agents#run-subagents-in-foreground-or-background)를 생성합니다. 각 subagent는 해당 단위를 구현하고, 테스트를 실행하고, pull request를 엽니다. git 리포지토리가 필요합니다. 예: `/batch migrate src/ from Solid to React` |57| `/batch <instruction>` | **[Skill](/ko/skills#bundled-skills).** 코드베이스 전체에서 대규모 변경 사항을 병렬로 조율합니다. 코드베이스를 연구하고, 작업을 5\~30개의 독립적인 단위로 분해하고, 계획을 제시합니다. 승인되면 격리된 [git worktree](/ko/worktrees)에서 단위당 하나의 [background subagent](/ko/sub-agents#run-subagents-in-foreground-or-background)를 생성합니다. 각 subagent는 해당 단위를 구현하고, 테스트를 실행하고, pull request를 엽니다. git 리포지토리가 필요합니다. 예: `/batch migrate src/ from Solid to React` |

53| `/branch [name]` | 이 시점에서 현재 대화의 브랜치를 만듭니다. 브랜치로 전환하고 원본을 보존하며, `/resume`을 사용하여 돌아갈 수 있습니다. 별칭: `/fork`. [`CLAUDE_CODE_FORK_SUBAGENT`](/ko/env-vars)가 설정되면, `/fork`는 대신 [forked subagent](/ko/sub-agents#fork-the-current-conversation)생성하며 더 이상 이 명령어의 별칭이 아닙니다 |58| `/branch [name]` | 이 시점에서 현재 대화의 브랜치를 만듭니다. 다른 방향을 시도할 수 있도록 현재 상태의 대화를 잃지 않습니다. 브랜치로 전환하고 원본을 보존하며, `/resume`을 사용하여 돌아갈 수 있습니다. 자신이 복사본으로 전환하는 대신 백그라운드 subagent에 부작업을 넘기려면 `/fork`사용하세요 |

54| `/btw <question>` | 대화에 추가하지 않고 빠른 [side question](/ko/interactive-mode#side-questions-with-%2Fbtw)을 합니다 |59| `/btw <question>` | 대화에 추가하지 않고 빠른 [side question](/ko/interactive-mode#side-questions-with-%2Fbtw)을 합니다 |

60| `/cd <path>` | {/* min-version: 2.1.169 */}이 세션을 새 작업 디렉토리로 이동합니다. 대화의 프롬프트 캐시는 보존됩니다. 새 디렉토리의 [`CLAUDE.md`](/ko/memory)는 시스템 프롬프트를 다시 빌드하는 대신 메시지로 추가됩니다. 세션은 새 디렉토리의 프로젝트 저장소로 재배치되므로 `--resume` 및 `--continue`가 거기서 찾습니다. 이전에 작업하지 않은 디렉토리를 신뢰하도록 프롬프트합니다. 세션을 이동하지 않고 추가 디렉토리에 액세스를 부여하려면 `/add-dir`을 사용하세요. [`Cd` permission rules](/ko/permissions#cd)로 `/cd` 대상을 제한하거나 비활성화합니다. Claude Code v2.1.169 이상이 필요합니다. 이전 버전은 `Unknown command: /cd`를 보고합니다 |

55| `/chrome` | [Claude in Chrome](/ko/chrome) 설정을 구성합니다 |61| `/chrome` | [Claude in Chrome](/ko/chrome) 설정을 구성합니다 |

56| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/ko/skills#bundled-skills).** 프로젝트의 언어(Python, TypeScript, Java, Go, Ruby, C#, PHP 또는 cURL) 및 Managed Agents 참조에 대한 Claude API 참조 자료를 로드합니다. 도구 사용, 스트리밍, 배치, 구조화된 출력 및 일반적인 함정을 다룹니다. 또한 코드가 `anthropic` 또는 `@anthropic-ai/sdk`를 가져올 때 자동으로 활성화됩니다. `/claude-api migrate`를 실행하여 기존 Claude API 코드를 최신 모델로 업그레이드합니다. Claude는 스캔할 파일과 대상 모델을 묻고, 모델 ID, thinking 구성 및 버전 간에 변경된 기타 매개변수를 업데이트합니다. `/claude-api managed-agents-onboard`를 실행하여 처음부터 새로운 Managed Agent를 만드는 대화형 안내를 받습니다 |62| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/ko/skills#bundled-skills).** 프로젝트의 언어(Python, TypeScript, Java, Go, Ruby, C#, PHP 또는 cURL) 및 Managed Agents 참조에 대한 Claude API 참조 자료를 로드합니다. 도구 사용, 스트리밍, 배치, 구조화된 출력 및 일반적인 함정을 다룹니다. 또한 코드가 `anthropic` 또는 `@anthropic-ai/sdk`를 가져올 때 자동으로 활성화됩니다. `/claude-api migrate`를 실행하여 기존 Claude API 코드를 최신 모델로 업그레이드합니다. Claude는 스캔할 파일과 대상 모델을 묻고, 모델 ID, thinking 구성 및 버전 간에 변경된 기타 매개변수를 업데이트합니다. `/claude-api managed-agents-onboard`를 실행하여 처음부터 새로운 Managed Agent를 만드는 대화형 안내를 받습니다 |

57| `/clear [name]` | 빈 컨텍스트로 새 대화를 시작합니다. 이전 대화는 `/resume`에서 사용 가능하게 유지됩니다. 이름을 전달하여 `/resume` 선택기에서 이전 대화에 레이블을 지정합니다. 같은 대화를 계속하면서 컨텍스트를 확보하려면 `/compact`를 대신 사용하세요. 별칭: `/reset`, `/new` |63| `/clear [name]` | 빈 컨텍스트로 새 대화를 시작합니다. 이전 대화는 `/resume`에서 사용 가능하게 유지됩니다. 이름을 전달하여 `/resume` 선택기에서 이전 대화에 레이블을 지정합니다. 같은 대화를 계속하면서 컨텍스트를 확보하려면 `/compact`를 대신 사용하세요. 별칭: `/reset`, `/new` |


74| `/feedback [report]` | 피드백을 제출하거나, 버그를 보고하거나, 대화를 공유합니다. 별칭: `/bug`, `/share` |80| `/feedback [report]` | 피드백을 제출하거나, 버그를 보고하거나, 대화를 공유합니다. 별칭: `/bug`, `/share` |

75| `/fewer-permission-prompts` | **[Skill](/ko/skills#bundled-skills).** 트랜스크립트에서 일반적인 읽기 전용 Bash 및 MCP 도구 호출을 스캔한 다음, 권한 프롬프트를 줄이기 위해 프로젝트 `.claude/settings.json`에 우선순위가 지정된 허용 목록을 추가합니다 |81| `/fewer-permission-prompts` | **[Skill](/ko/skills#bundled-skills).** 트랜스크립트에서 일반적인 읽기 전용 Bash 및 MCP 도구 호출을 스캔한 다음, 권한 프롬프트를 줄이기 위해 프로젝트 `.claude/settings.json`에 우선순위가 지정된 허용 목록을 추가합니다 |

76| `/focus` | 포커스 뷰를 전환합니다. 마지막 프롬프트, 편집 diffstats가 있는 한 줄 도구 호출 요약 및 최종 응답만 표시합니다. 선택 항목은 세션 전체에서 유지됩니다. 설정에서 [`viewMode`](/ko/settings#available-settings)를 설정하여 재정의할 수 있습니다. [fullscreen rendering](/ko/fullscreen)에서만 사용 가능합니다 |82| `/focus` | 포커스 뷰를 전환합니다. 마지막 프롬프트, 편집 diffstats가 있는 한 줄 도구 호출 요약 및 최종 응답만 표시합니다. 선택 항목은 세션 전체에서 유지됩니다. 설정에서 [`viewMode`](/ko/settings#available-settings)를 설정하여 재정의할 수 있습니다. [fullscreen rendering](/ko/fullscreen)에서만 사용 가능합니다 |

83| `/fork <directive>` | {/* min-version: 2.1.161 */}}[forked subagent](/ko/sub-agents#fork-the-current-conversation)를 생성합니다. 이는 전체 대화를 상속하고 지시문에서 작업하는 백그라운드 subagent이며, 당신은 계속 진행합니다. 그 결과는 완료되면 당신의 대화로 돌아옵니다. 대화의 복사본으로 자신이 전환하려면 `/branch`를 사용하세요. v2.1.161 이전에는 `/fork`가 `/branch`의 별칭입니다 |

77| `/goal [condition\|clear]` | [goal](/ko/goal)을 설정합니다. Claude는 조건이 충족될 때까지 여러 턴에 걸쳐 계속 작업합니다. 인수 없이 현재 또는 가장 최근에 달성한 goal을 표시합니다. `clear`, `stop`, `off`, `reset`, `none` 또는 `cancel`은 활성 goal을 조기에 제거합니다 |84| `/goal [condition\|clear]` | [goal](/ko/goal)을 설정합니다. Claude는 조건이 충족될 때까지 여러 턴에 걸쳐 계속 작업합니다. 인수 없이 현재 또는 가장 최근에 달성한 goal을 표시합니다. `clear`, `stop`, `off`, `reset`, `none` 또는 `cancel`은 활성 goal을 조기에 제거합니다 |

78| `/heapdump` | JavaScript 힙 스냅샷 및 메모리 분석을 `~/Desktop`에 작성하거나, Desktop 폴더가 없는 Linux의 경우 홈 디렉토리에 작성하여 높은 메모리 사용량을 진단합니다. [troubleshooting](/ko/troubleshooting#high-cpu-or-memory-usage)을 참조하세요 |85| `/heapdump` | JavaScript 힙 스냅샷 및 메모리 분석을 `~/Desktop`에 작성하거나, Desktop 폴더가 없는 Linux의 경우 홈 디렉토리에 작성하여 높은 메모리 사용량을 진단합니다. [troubleshooting](/ko/troubleshooting#high-cpu-or-memory-usage)을 참조하세요 |

79| `/help` | 도움말 및 사용 가능한 명령어를 표시합니다 |86| `/help` | 도움말 및 사용 가능한 명령어를 표시합니다 |


83| `/insights` | Claude Code 세션을 분석하는 보고서를 생성합니다. 프로젝트 영역, 상호 작용 패턴 및 마찰 지점을 포함합니다 |90| `/insights` | Claude Code 세션을 분석하는 보고서를 생성합니다. 프로젝트 영역, 상호 작용 패턴 및 마찰 지점을 포함합니다 |

84| `/install-github-app` | 리포지토리에 대해 [Claude GitHub Actions](/ko/github-actions) 앱을 설정합니다. 리포지토리를 선택하고 통합을 구성하는 과정을 안내합니다 |91| `/install-github-app` | 리포지토리에 대해 [Claude GitHub Actions](/ko/github-actions) 앱을 설정합니다. 리포지토리를 선택하고 통합을 구성하는 과정을 안내합니다 |

85| `/install-slack-app` | Claude Slack 앱을 설치합니다. OAuth 흐름을 완료하기 위해 브라우저를 엽니다 |92| `/install-slack-app` | Claude Slack 앱을 설치합니다. OAuth 흐름을 완료하기 위해 브라우저를 엽니다 |

86| `/keybindings` | 키바인딩 구성 파일을 열거나 만듭니다 |93| `/keybindings` | [keyboard shortcuts](/ko/keybindings) 파일을 엽니다 |

87| `/login` | Anthropic 계정에 로그인합니다 |94| `/login` | Anthropic 계정에 로그인합니다 |

88| `/logout` | Anthropic 계정에서 로그아웃합니다 |95| `/logout` | Anthropic 계정에서 로그아웃합니다 |

89| `/loop [interval] [prompt]` | **[Skill](/ko/skills#bundled-skills).** 세션이 열려 있는 동안 프롬프트를 반복적으로 실행합니다. 간격을 생략하면 Claude가 반복 사이에 자동으로 속도를 조절합니다. 프롬프트를 생략하면 Claude가 자동 유지 관리 검사를 실행하거나, [사용 가능한 경우](/ko/scheduled-tasks#run-the-built-in-maintenance-prompt), `.claude/loop.md`의 프롬프트를 실행합니다. 예: `/loop 5m check if the deploy finished`. [Run prompts on a schedule](/ko/scheduled-tasks)을 참조하세요. 별칭: `/proactive` |96| `/loop [interval] [prompt]` | **[Skill](/ko/skills#bundled-skills).** 세션이 열려 있는 동안 프롬프트를 반복적으로 실행합니다. 간격을 생략하면 Claude가 반복 사이에 자동으로 속도를 조절합니다. 프롬프트를 생략하면 [사용 가능한 경우](/ko/scheduled-tasks#run-the-built-in-maintenance-prompt) Claude가 자동 유지 관리 검사를 실행하거나 `.claude/loop.md`의 프롬프트를 실행합니다. 예: `/loop 5m check if the deploy finished`. [Run prompts on a schedule](/ko/scheduled-tasks)을 참조하세요. 별칭: `/proactive` |

90| `/mcp` | MCP 서버 연결 및 OAuth 인증을 관리합니다 |97| `/mcp [reconnect <server>\|enable\|disable [<server>\|all]]` | MCP 서버 연결 및 OAuth 인증을 관리합니다. 인수 없이 실행하여 대화형 목록을 열거나, `reconnect <server>`를 전달하여 연결이 끊긴 서버를 다시 연결하거나, `enable`/`disable`을 서버 이름 또는 `all`과 함께 전달하여 대화 상자를 열지 않고 연결 상태를 변경합니다 |

91| `/memory` | `CLAUDE.md` 메모리 파일을 편집하고, [auto-memory](/ko/memory#auto-memory)를 활성화 또는 비활성화하며, 자동 메모리 항목을 봅니다 |98| `/memory` | `CLAUDE.md` 메모리 파일을 편집하고, [auto-memory](/ko/memory#auto-memory)를 활성화 또는 비활성화하며, 자동 메모리 항목을 봅니다 |

92| `/mobile` | Claude 모바일 앱을 다운로드할 수 있는 QR 코드를 표시합니다. 별칭: `/ios`, `/android` |99| `/mobile` | Claude 모바일 앱을 다운로드할 수 있는 QR 코드를 표시합니다. 별칭: `/ios`, `/android` |

93| `/model [model]` | AI 모델을 전환하고 새 세션의 기본값으로 저장합니다. 이를 지원하는 모델의 경우 왼쪽/오른쪽 화살표를 사용하여 [effort level을 조정](/ko/model-config#adjust-effort-level)합니다. 인수 없이 선택기를 엽니다. 행에서 `s`를 눌러 현재 세션에만 전환합니다. 대화에 이전 출력이 있을 때 선택기가 확인을 요청합니다. 다음 응답이 캐시된 컨텍스트 없이 전체 기록을 다시 읽기 때문입니다. 확인되면 현재 응답이 완료될 때까지 기다리지 않고 변경 사항이 적용됩니다 |100| `/model [model]` | AI 모델을 전환하고 새 세션의 기본값으로 저장합니다. 이를 지원하는 모델의 경우 왼쪽/오른쪽 화살표를 사용하여 [effort level을 조정](/ko/model-config#adjust-effort-level)합니다. 인수 없이 선택기를 엽니다. 행에서 `s`를 눌러 현재 세션에만 전환합니다. 대화에 이전 출력이 있을 때 선택기가 확인을 요청합니다. 다음 응답이 캐시된 컨텍스트 없이 전체 기록을 다시 읽기 때문입니다. 확인되면 현재 응답이 완료될 때까지 기다리지 않고 변경 사항이 적용됩니다 |

94| `/passes` | 친구들과 Claude Code의 무료 1주일을 공유합니다. 계정이 적격인 경우에만 표시됩니다 |101| `/passes` | 친구들과 Claude Code의 무료 1주일을 공유합니다. 계정이 적격인 경우에만 표시됩니다 |

95| `/permissions` | 도구 권한에 대한 허용, 요청 및 거부 규칙을 관리합니다. 범위별로 규칙을 보고, 규칙을 추가 또는 제거하고, 작업 디렉토리를 관리하며, [최근 자동 모드 거부](/ko/auto-mode-config#review-denials)를 검토할 수 있는 대화형 대화 상자를 엽니다. 별칭: `/allowed-tools` |102| `/permissions` | 도구 권한에 대한 허용, 요청 및 거부 규칙을 관리합니다. 범위별로 규칙을 보고, 규칙을 추가 또는 제거하고, 작업 디렉토리를 관리하며, [최근 자동 모드 거부](/ko/auto-mode-config#review-denials)를 검토할 수 있는 대화형 대화 상자를 엽니다. 별칭: `/allowed-tools` |

96| `/plan [description]` | 프롬프트에서 직접 plan mode로 들어갑니다. 선택적 설명을 전달하여 plan mode로 들어가고 즉시 해당 작업으로 시작합니다. 예를 들어 `/plan fix the auth bug` |103| `/plan [description]` | 프롬프트에서 직접 plan mode로 들어갑니다. 선택적 설명을 전달하여 plan mode로 들어가고 즉시 해당 작업으로 시작합니다. 예를 들어 `/plan fix the auth bug` |

97| `/plugin` | Claude Code [plugins](/ko/plugins)를 관리합니다 |104| `/plugin [subcommand]` | Claude Code [plugins](/ko/plugins)를 관리합니다. 인수 없이 실행하여 플러그인 메뉴를 열거나, `list`, `install`, `enable` 또는 `disable`과 같은 subcommand를 전달하여 직접 작동합니다 |

98| `/powerup` | 애니메이션 데모가 포함된 빠른 대화형 레슨을 통해 Claude Code 기능을 발견합니다 |105| `/powerup` | 애니메이션 데모가 포함된 빠른 대화형 레슨을 통해 Claude Code 기능을 발견합니다 |

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

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

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

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

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

104| `/reload-plugins` | 모든 활성 [plugins](/ko/plugins)를 다시 로드하여 재시작하지 않고 보류 중인 변경 사항을 적용합니다. 각 다시 로드된 구성 요소의 개수를 보고하고 로드 오류를 표시합니다 |111| `/reload-plugins [--force]` | 모든 활성 [plugins](/ko/plugins)를 다시 로드하여 재시작하지 않고 보류 중인 변경 사항을 적용합니다. 각 다시 로드된 구성 요소의 개수를 보고하고 로드 오류를 표시합니다. 다시 로드가 로드된 MCP 도구를 변경하고 프롬프트 캐시를 무효화할 때, 명령어는 경고하고 `--force`를 전달하지 않으면 건너뜁니다 |

105| `/reload-skills` | {/* min-version: 2.1.152 */}[skill](/ko/skills) 및 명령어 디렉토리를 다시 스캔하여 세션 중에 디스크에서 추가되거나 변경된 skills를 재시작하지 않고 사용할 수 있도록 합니다. 사용 가능한 skills의 개수와 추가되거나 제거된 skills의 개수를 보고합니다 |112| `/reload-skills` | {/* min-version: 2.1.152 */}}[skill](/ko/skills) 및 명령어 디렉토리를 다시 스캔하여 세션 중에 디스크에서 추가되거나 변경된 skills를 재시작하지 않고 사용할 수 있도록 합니다. 사용 가능한 skills의 개수와 추가되거나 제거된 skills의 개수를 보고합니다. v2.1.152에서 추가됨 |

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

107| `/remote-env` | [`--remote`로 시작된 웹 세션](/ko/claude-code-on-the-web#configure-your-environment)에 대한 기본 원격 환경을 구성합니다 |114| `/remote-env` | [cloud agents](/ko/claude-code-on-the-web#configure-your-environment)에 대한 기본 환경을 선택합니다 |

108| `/rename [name]` | 현재 세션의 이름을 바꾸고 프롬프트 바에 이름을 표시합니다. 이름이 없으면 대화 기록에서 자동으로 생성합니다 |115| `/rename [name]` | 현재 세션의 이름을 바꾸고 프롬프트 바에 이름을 표시합니다. 이름이 없으면 대화 기록에서 자동으로 생성합니다 |

109| `/resume [session]` | ID 또는 이름으로 대화를 재개하거나 세션 선택기를 엽니다. v2.1.144부터 [background sessions](/ko/agent-view)이 선택기에 `bg`로 표시됩니다. 별칭: `/continue` |116| `/resume [session]` | ID 또는 이름으로 대화를 재개하거나 세션 선택기를 엽니다. v2.1.144부터 [background sessions](/ko/agent-view)이 선택기에 `bg`로 표시됩니다. 별칭: `/continue` |

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


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

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

119| `/setup-vertex` | [Google Vertex AI](/ko/google-vertex-ai) 인증, 프로젝트, 지역 및 모델 핀을 대화형 마법사를 통해 구성합니다. `CLAUDE_CODE_USE_VERTEX=1`이 설정되어 있을 때만 표시됩니다. 처음 Vertex AI를 사용하는 사용자는 로그인 화면에서도 이 마법사에 액세스할 수 있습니다 |126| `/setup-vertex` | [Google Vertex AI](/ko/google-vertex-ai) 인증, 프로젝트, 지역 및 모델 핀을 대화형 마법사를 통해 구성합니다. `CLAUDE_CODE_USE_VERTEX=1`이 설정되어 있을 때만 표시됩니다. 처음 Vertex AI를 사용하는 사용자는 로그인 화면에서도 이 마법사에 액세스할 수 있습니다 |

120| `/simplify [target]` | {/* min-version: 2.1.154 */}**[Skill](/ko/skills#bundled-skills).** 변경된 코드를 정리 기회에 대해 검토하고 수정 사항을 적용합니다. 4개의 검토 [agents](/ko/sub-agents)가 병렬로 실행되어 기존 헬퍼의 재사용, 단순화, 효율성 및 변경이 추상화의 올바른 수준에 있는지 여부를 다룹니다. v2.1.154부터 검토는 정확성 버그를 찾지 않습니다. 버그를 찾으려면 `/code-review`를 사용하세요. 이전 버전에서 `/simplify`는 `/code-review --fix`와 동일합니다. 특정 대상을 검토하려면 경로 또는 PR 참조를 전달합니다 |127| `/simplify [target]` | {/* min-version: 2.1.154 */}}**[Skill](/ko/skills#bundled-skills).** 변경된 코드를 정리 기회에 대해 검토하고 수정 사항을 적용합니다. 4개의 검토 [agents](/ko/sub-agents)가 병렬로 실행되어 기존 헬퍼의 재사용, 단순화, 효율성 및 변경이 추상화의 올바른 수준에 있는지 여부를 다룹니다. v2.1.154부터 검토는 정확성 버그를 찾지 않습니다. 버그를 찾으려면 `/code-review`를 사용하세요. 이전 버전에서 `/simplify`는 `/code-review --fix`와 동일합니다. 특정 대상을 검토하려면 경로 또는 PR 참조를 전달합니다 |

121| `/skills` | 사용 가능한 [skills](/ko/skills)를 나열합니다. `t`를 눌러 토큰 수로 정렬합니다. `Space`를 눌러 [Claude 또는 `/` 메뉴에서 skill을 숨기고](/ko/skills#override-skill-visibility-from-settings), `Enter`를 눌러 저장합니다 |128| `/skills` | 사용 가능한 [skills](/ko/skills)를 나열합니다. `t`를 눌러 토큰 수로 정렬합니다. `Space`를 눌러 [Claude 또는 `/` 메뉴에서 skill을 숨기고](/ko/skills#override-skill-visibility-from-settings), `Enter`를 눌러 저장합니다 |

122| `/stats` | `/usage`의 별칭입니다. Stats 탭에서 엽니다 |129| `/stats` | `/usage`의 별칭입니다. Stats 탭에서 엽니다 |

123| `/status` | 버전, 모델, 계정 및 연결성을 표시하는 Settings 인터페이스(Status 탭)를 엽니다. Claude가 응답하는 동안 현재 응답이 완료될 때까지 기다리지 않고 작동합니다 |130| `/status` | 버전, 모델, 계정 및 연결성을 표시하는 Settings 인터페이스(Status 탭)를 엽니다. Claude가 응답하는 동안 현재 응답이 완료될 때까지 기다리지 않고 작동합니다 |

124| `/statusline` | Claude Code의 [status line](/ko/statusline)을 구성합니다. 원하는 내용을 설명하거나 인수 없이 실행하여 셸 프롬프트에서 자동으로 구성합니다 |131| `/statusline` | Claude Code의 [status line](/ko/statusline)을 구성합니다. 원하는 내용을 설명하거나 인수 없이 실행하여 셸 프롬프트에서 자동으로 구성합니다 |

125| `/stickers` | Claude Code 스티커를 주문합니다 |132| `/stickers` | Claude Code 스티커를 주문합니다 |

126| `/stop` | 현재 [background session](/ko/agent-view)을 중지합니다. 백그라운드 세션에 연결되어 있을 때만 사용 가능합니다. 트랜스크립트 및 모든 worktree는 유지됩니다. 중지하지 않고 분리하려면 `/exit`를 사용하거나 `←`를 누르세요 |133| `/stop` | 현재 [background session](/ko/agent-view)을 중지합니다. 백그라운드 세션에 연결되어 있을 때만 사용 가능합니다. 트랜스크립트 및 모든 worktree는 유지됩니다. 중지하지 않고 분리하려면 `/exit`를 사용하거나 `←`를 누르세요 |

127| `/tasks` | 백그라운드 작업을 나열하고 관리합니다. `/bashes`로도 사용 가능합니다 |134| `/tasks` | 백그라운드에서 실행 중인 모든 항목을 보고 관리합니다. `/bashes`로도 사용 가능합니다 |

128| `/team-onboarding` | Claude Code 사용 기록에서 팀 온보딩 가이드를 생성합니다. Claude는 지난 30일간의 세션, 명령어 및 MCP 서버 사용을 분석하고 팀원이 첫 메시지로 붙여넣어 빠르게 설정할 수 있는 markdown 가이드를 생성합니다. claude.ai 구독자의 Pro, Max, Team 및 Enterprise 요금제의 경우, 팀원이 Claude Code에서 직접 열 수 있는 공유 링크도 반환합니다 |135| `/team-onboarding` | Claude Code 사용 기록에서 팀 온보딩 가이드를 생성합니다. Claude는 지난 30일간의 세션, 명령어 및 MCP 서버 사용을 분석하고 팀원이 첫 메시지로 붙여넣어 빠르게 설정할 수 있는 markdown 가이드를 생성합니다. claude.ai 구독자의 Pro, Max, Team 및 Enterprise 요금제의 경우, 팀원이 Claude Code에서 직접 열 수 있는 공유 링크도 반환합니다 |

129| `/teleport` | [Claude Code on the web](/ko/claude-code-on-the-web#from-web-to-terminal) 세션을 이 터미널로 가져옵니다. 선택기를 열고 브랜치와 대화를 가져옵니다. `/tp`로도 사용 가능합니다. claude.ai 구독이 필요합니다 |136| `/teleport` | [Claude Code on the web](/ko/claude-code-on-the-web#from-web-to-terminal) 세션을 이 터미널로 가져옵니다. 선택기를 열고 브랜치와 대화를 가져옵니다. `/tp`로도 사용 가능합니다. claude.ai 구독이 필요합니다 |

130| `/terminal-setup` | Shift+Enter 및 기타 바로 가기에 대한 터미널 키바인딩을 구성합니다. VS Code, Cursor, Devin Desktop, Alacritty 또는 Zed와 같이 필요한 터미널에서만 표시됩니다 |137| `/terminal-setup` | Shift+Enter 및 기타 바로 가기에 대한 터미널 키바인딩을 구성합니다. VS Code, Cursor, Devin Desktop, Alacritty 또는 Zed와 같이 필요한 터미널에서만 표시됩니다 |


141| `/web-setup` | 로컬 `gh` CLI 자격 증명을 사용하여 GitHub 계정을 [Claude Code on the web](/ko/web-quickstart#connect-from-your-terminal)에 연결합니다. `/schedule`은 GitHub가 연결되지 않은 경우 자동으로 이를 요청합니다 |148| `/web-setup` | 로컬 `gh` CLI 자격 증명을 사용하여 GitHub 계정을 [Claude Code on the web](/ko/web-quickstart#connect-from-your-terminal)에 연결합니다. `/schedule`은 GitHub가 연결되지 않은 경우 자동으로 이를 요청합니다 |

142| `/workflows` | [workflow](/ko/workflows#watch-the-run) 진행 상황 뷰를 열어 실행 중이거나 완료된 workflows를 감시하고, 일시 중지하고, 재개하거나, 저장합니다 |149| `/workflows` | [workflow](/ko/workflows#watch-the-run) 진행 상황 뷰를 열어 실행 중이거나 완료된 workflows를 감시하고, 일시 중지하고, 재개하거나, 저장합니다 |

143 150 

144## MCP 프롬프트151<h2 id="mcp-prompts">

152 MCP 프롬프트

153</h2>

145 154 

146MCP 서버는 명령어로 나타나는 프롬프트를 노출할 수 있습니다. 이들은 `/mcp__<server>__<prompt>` 형식을 사용하며 연결된 서버에서 동적으로 발견됩니다. 자세한 내용은 [MCP prompts](/ko/mcp#use-mcp-prompts-as-commands)를 참조하세요.155MCP 서버는 명령어로 나타나는 프롬프트를 노출할 수 있습니다. 이들은 `/mcp__<server>__<prompt>` 형식을 사용하며 연결된 서버에서 동적으로 발견됩니다. 자세한 내용은 [MCP prompts](/ko/mcp#use-mcp-prompts-as-commands)를 참조하세요.

147 156 

148## 참고 항목157<h2 id="see-also">

158 참고 항목

159</h2>

149 160 

150* [Skills](/ko/skills): 자신만의 명령어 만들기161* [Skills](/ko/skills): 자신만의 명령어 만들기

151* [대화형 모드](/ko/interactive-mode): 키보드 바로 가기, Vim 모드 및 명령어 기록162* [대화형 모드](/ko/interactive-mode): 키보드 바로 가기, Vim 모드 및 명령어 기록

Details

194 194 

195오타를 수정하기 위해 Opus를 사용하면 계산을 낭비합니다. 12파일 리팩토링에 Haiku를 사용하는 것은 다시 하도록 요청하는 것입니다.195오타를 수정하기 위해 Opus를 사용하면 계산을 낭비합니다. 12파일 리팩토링에 Haiku를 사용하는 것은 다시 하도록 요청하는 것입니다.

196 196 

197Claude Code는 Claude 앱과 같은 모델에서 실행되며, 세션 중에 전환할 수 있습니다. *Sonnet*은 일상적인 기능 작업, 버그, 테스트, 검토를 위한 기본 워크호스입니다. 대규모 리팩토링, 복잡한 디버깅 또는 높은 위험의 작업에는 *Opus*를 사용하십시오. 빠른 질문, 포맷팅, 속도가 중요한 기계적 편집에는 *Haiku*로 내려가십시오.197Claude Code는 Claude 앱과 같은 모델에서 실행되며, 세션 중에 전환할 수 있습니다. *Sonnet*은 일상적인 기능 작업, 버그, 테스트, 검토를 위한 기본 워크호스입니다. 대규모 리팩토링, 복잡한 디버깅 또는 높은 위험의 작업에는 *Opus*를 사용하십시오. 빠른 질문, 포맷팅, 속도가 중요한 기계적 편집에는 *Haiku*로 내려가십시오. *Fable 5*는 가장 어렵고 오래 실행되는 작업을 위한 가장 강력한 모델입니다. 기본값이 아니므로 `/model fable`로 선택하십시오. 사이버 보안 및 생물학 콘텐츠는 자동으로 Opus로 폴백됩니다.

198 198 

199*지금 시도하기:* `/model`을 입력하고 아직 하지 않았다면 Sonnet을 선택하십시오. 대부분의 작업에 올바른 기본값입니다.199*지금 시도하기:* `/model`을 입력하고 아직 하지 않았다면 Sonnet을 선택하십시오. 대부분의 작업에 올바른 기본값입니다.

200 200 

201📖 모델 구성 → https://code.claude.com/docs/en/model-config201📖 모델 구성 → https://code.claude.com/docs/ko/model-config

202```202```

203 203 

204| 모델 | 최적 용도 |204| 모델 | 최적 용도 |

205| ------ | ------------------------------------------ |205| ------- | ------------------------------------------------------------------------------------------------------------------------------- |

206| Fable 5 | 가장 어렵고 오래 실행되는 작업. 옵트인만 가능: `/model fable`로 선택하십시오. 사이버 보안 또는 생물학 콘텐츠는 [Opus로 폴백됩니다](/ko/model-config#automatic-model-fallback) |

206| Opus | 대규모 리팩토링, 복잡한 디버깅, 아키텍처 결정, 높은 위험 변경 |207| Opus | 대규모 리팩토링, 복잡한 디버깅, 아키텍처 결정, 높은 위험 변경 |

207| Sonnet | 일상적인 기능 작업, 버그 수정, 테스트, 문서, 코드 검토. 권장 기본값. |208| Sonnet | 일상적인 기능 작업, 버그 수정, 테스트, 문서, 코드 검토. 권장 기본값. |

208| Haiku | 빠른 질문, 포맷팅, 기계적 편집, 빠른 반복 |209| Haiku | 빠른 질문, 포맷팅, 기계적 편집, 빠른 반복 |


222 223 

223*지금 시도하기:* 피해온 버그를 선택하고 오류 메시지를 붙여넣으십시오.224*지금 시도하기:* 피해온 버그를 선택하고 오류 메시지를 붙여넣으십시오.

224 225 

225📖 빠른 시작 → https://code.claude.com/docs/en/quickstart226📖 빠른 시작 → https://code.claude.com/docs/ko/quickstart

226```227```

227 228 

228<h3 id="project-memory">229<h3 id="project-memory">


240 241 

241*지금 시도하기:* 주 리포지토리를 열고, `claude`를 실행하고, `/init`를 입력하십시오. 30초, 그 이후 모든 세션에서 보상됩니다.242*지금 시도하기:* 주 리포지토리를 열고, `claude`를 실행하고, `/init`를 입력하십시오. 30초, 그 이후 모든 세션에서 보상됩니다.

242 243 

243📖 CLAUDE.md 및 프로젝트 메모리 → https://code.claude.com/docs/en/memory244📖 CLAUDE.md 및 프로젝트 메모리 → https://code.claude.com/docs/ko/memory

244```245```

245 246 

246**@-참조**247**@-참조**


256 257 

257*지금 시도하기:* `@`를 입력한 다음 Tab을 누르십시오. 자동 완성은 도달 범위 내의 모든 파일을 표시합니다.258*지금 시도하기:* `@`를 입력한 다음 Tab을 누르십시오. 자동 완성은 도달 범위 내의 모든 파일을 표시합니다.

258 259 

259📖 파일 참조 → https://code.claude.com/docs/en/common-workflows260📖 파일 참조 → https://code.claude.com/docs/ko/common-workflows

260```261```

261 262 

262<h3 id="control-and-safety">263<h3 id="control-and-safety">


274 275 

275*지금 시도하기:* 다음 리팩토링에서 Shift+Tab을 누르면 "plan"이 표시될 때까지 누른 다음 변경 사항을 설명하십시오. 단일 파일이 움직이기 전에 전체 제안을 받을 것입니다.276*지금 시도하기:* 다음 리팩토링에서 Shift+Tab을 누르면 "plan"이 표시될 때까지 누른 다음 변경 사항을 설명하십시오. 단일 파일이 움직이기 전에 전체 제안을 받을 것입니다.

276 277 

277📖 권한 모드 → https://code.claude.com/docs/en/permissions278📖 권한 모드 → https://code.claude.com/docs/ko/permissions

278```279```

279 280 

280**체크포인팅 및 `/rewind`**281**체크포인팅 및 `/rewind`**


288 289 

289*지금 시도하기:* *Esc*를 두 번 눌러 rewind 메뉴를 열거나 `/rewind`를 입력하십시오. 상황이 잘못되기 전의 지점을 선택하십시오.290*지금 시도하기:* *Esc*를 두 번 눌러 rewind 메뉴를 열거나 `/rewind`를 입력하십시오. 상황이 잘못되기 전의 지점을 선택하십시오.

290 291 

291📖 체크포인팅 → https://code.claude.com/docs/en/checkpointing292📖 체크포인팅 → https://code.claude.com/docs/ko/checkpointing

292```293```

293 294 

294<h3 id="connect-your-tools">295<h3 id="connect-your-tools">


306 307 

307*지금 시도하기:* Claude에게 "이 리포지토리에서 [GitHub/Jira/Linear]에 대한 MCP 커넥터를 설정하세요"라고 요청하십시오. 구성을 작성할 것입니다.308*지금 시도하기:* Claude에게 "이 리포지토리에서 [GitHub/Jira/Linear]에 대한 MCP 커넥터를 설정하세요"라고 요청하십시오. 구성을 작성할 것입니다.

308 309 

309📖 MCP 커넥터 → https://code.claude.com/docs/en/mcp310📖 MCP 커넥터 → https://code.claude.com/docs/ko/mcp

310```311```

311 312 

312<h3 id="automate-your-workflows">313<h3 id="automate-your-workflows">


324 325 

325*지금 시도하기:* "git log에서 오늘 작업한 내용을 요약하는 /standup skill을 만들어주세요"를 입력한 다음 내일 아침 `/standup`을 실행하십시오.326*지금 시도하기:* "git log에서 오늘 작업한 내용을 요약하는 /standup skill을 만들어주세요"를 입력한 다음 내일 아침 `/standup`을 실행하십시오.

326 327 

327📖 Skills → https://code.claude.com/docs/en/skills328📖 Skills → https://code.claude.com/docs/ko/skills

328```329```

329 330 

330**Hooks**331**Hooks**


338 339 

339*지금 시도하기:* Claude에게 "완료되면 데스크톱 알림을 보내는 Stop hook를 추가하세요"라고 요청하십시오. 스크립트를 작성하고 연결할 것입니다.340*지금 시도하기:* Claude에게 "완료되면 데스크톱 알림을 보내는 Stop hook를 추가하세요"라고 요청하십시오. 스크립트를 작성하고 연결할 것입니다.

340 341 

341📖 Hooks 가이드 → https://code.claude.com/docs/en/hooks-guide342📖 Hooks 가이드 → https://code.claude.com/docs/ko/hooks-guide

342```343```

343 344 

344<h3 id="day-to-day-development">345<h3 id="day-to-day-development">


356 357 

357*지금 시도하기:* 다음에 뭔가 시각적으로 깨지면, 스크린샷을 찍고 프롬프트에 직접 붙여넣으십시오. 그런 다음 "여기서 뭐가 잘못됐어요?"라고 입력하십시오.358*지금 시도하기:* 다음에 뭔가 시각적으로 깨지면, 스크린샷을 찍고 프롬프트에 직접 붙여넣으십시오. 그런 다음 "여기서 뭐가 잘못됐어요?"라고 입력하십시오.

358 359 

359📖 이미지 작업 → https://code.claude.com/docs/en/common-workflows360📖 이미지 작업 → https://code.claude.com/docs/ko/common-workflows

360```361```

361 362 

362**Git 워크플로우**363**Git 워크플로우**


370 371 

371*지금 시도하기:* 다음 수정 후, git 클라이언트로 전환하는 대신, "좋은 메시지로 커밋하고 PR을 열어주세요"라고 입력하십시오.372*지금 시도하기:* 다음 수정 후, git 클라이언트로 전환하는 대신, "좋은 메시지로 커밋하고 PR을 열어주세요"라고 입력하십시오.

372 373 

373📖 풀 요청 생성 → https://code.claude.com/docs/en/common-workflows374📖 풀 요청 생성 → https://code.claude.com/docs/ko/common-workflows

374```375```

375 376 

376<h3 id="share-and-scale">377<h3 id="share-and-scale">


388 389 

389*지금 시도하기:* `/plugin`을 입력하고 스크롤하십시오. 알지 못했던 적어도 한 가지를 찾을 것입니다.390*지금 시도하기:* `/plugin`을 입력하고 스크롤하십시오. 알지 못했던 적어도 한 가지를 찾을 것입니다.

390 391 

391📖 Plugins → https://code.claude.com/docs/en/plugins392📖 Plugins → https://code.claude.com/docs/ko/plugins

392```393```

393 394 

394<h3 id="security-and-admin">395<h3 id="security-and-admin">


407 408 

408*지금 시도하기:* 다음에 질문이 나올 때를 위해 이 두 링크를 저장하십시오. 대부분의 보안 검토 질문에 답변합니다.409*지금 시도하기:* 다음에 질문이 나올 때를 위해 이 두 링크를 저장하십시오. 대부분의 보안 검토 질문에 답변합니다.

409 410 

410📖 https://code.claude.com/docs/en/security411📖 https://code.claude.com/docs/ko/security

411📖 https://code.claude.com/docs/en/data-usage412📖 https://code.claude.com/docs/ko/data-usage

412```413```

413 414 

414**모범 사례**415**모범 사례**


425 426 

426*지금 시도하기:* 이 중 하나 또는 두 개만 했다면, 누락된 것을 선택하고 다음 작업에서 하십시오. #claude-code에 변경 사항을 게시하십시오.427*지금 시도하기:* 이 중 하나 또는 두 개만 했다면, 누락된 것을 선택하고 다음 작업에서 하십시오. #claude-code에 변경 사항을 게시하십시오.

427 428 

428📖 모범 사례 → https://code.claude.com/docs/en/best-practices429📖 모범 사례 → https://code.claude.com/docs/ko/best-practices

429```430```

430 431 

431<h2 id="quick-reference">432<h2 id="quick-reference">

computer-use.md +5 −5

Details

164 네이티브 빌드 검증164 네이티브 빌드 검증

165</h3>165</h3>

166 166 

167macOS 또는 iOS 앱을 변경한 후 Claude에게 한 번에 컴파일하고 확인하도록 합니다.167macOS 또는 iOS 앱을 변경한 후 Claude에게 한 번에 컴파일하고 확인하도록 합니다:

168 168 

169```text theme={null}169```text theme={null}

170MenuBarStats 대상을 빌드하고, 실행하고, 기본 설정 창을 열고,170MenuBarStats 대상을 빌드하고, 실행하고, 기본 설정 창을 열고,


178 레이아웃 버그 재현178 레이아웃 버그 재현

179</h3>179</h3>

180 180 

181시각적 버그가 특정 창 크기에서만 나타날 때 Claude에게 찾도록 합니다.181시각적 버그가 특정 창 크기에서만 나타날 때 Claude에게 찾도록 합니다:

182 182 

183```text theme={null}183```text theme={null}

184설정 모달이 좁은 창에서 바닥글을 자릅니다. 앱 창 크기를 줄여서184설정 모달이 좁은 창에서 바닥글을 자릅니다. 앱 창 크기를 줄여서


192 시뮬레이터 흐름 테스트192 시뮬레이터 흐름 테스트

193</h3>193</h3>

194 194 

195XCTest를 작성하지 않고 iOS Simulator를 제어합니다.195XCTest를 작성하지 않고 iOS Simulator를 제어합니다:

196 196 

197```text theme={null}197```text theme={null}

198iOS Simulator를 열고, 앱을 실행하고, 온보딩 화면을 탭하고,198iOS Simulator를 열고, 앱을 실행하고, 온보딩 화면을 탭하고,


205 Desktop 앱과의 차이점205 Desktop 앱과의 차이점

206</h2>206</h2>

207 207 

208CLI 및 Desktop 표면은 동일한 컴퓨터 사용 엔진을 공유합니다. 몇 가지 차이점이 있습니다.208CLI 및 Desktop 표면은 동일한 컴퓨터 사용 엔진을 공유하며, 몇 가지 차이점이 있습니다.

209 209 

210| 기능 | Desktop | CLI |210| 기능 | Desktop | CLI |

211| :---------- | :---------------------------------- | :-------------------------- |211| :---------- | :---------------------------------- | :-------------------------- |


231 231 

232macOS는 화면 녹화를 부여한 후 요청 프로세스를 다시 시작해야 할 수 있습니다. Claude Code를 완전히 종료하고 새 세션을 시작합니다. 프롬프트가 계속되면 **시스템 설정 > 개인 정보 보호 및 보안 > 화면 녹화**를 열고 터미널 앱이 나열되고 활성화되어 있는지 확인합니다.232macOS는 화면 녹화를 부여한 후 요청 프로세스를 다시 시작해야 할 수 있습니다. Claude Code를 완전히 종료하고 새 세션을 시작합니다. 프롬프트가 계속되면 **시스템 설정 > 개인 정보 보호 및 보안 > 화면 녹화**를 열고 터미널 앱이 나열되고 활성화되어 있는지 확인합니다.

233 233 

234<h3 id="computer-use-doesn-t-appear-in-/mcp">234<h3 id="computer-use-doesnt-appear-in-/mcp">

235 `computer-use`가 `/mcp`에 나타나지 않음235 `computer-use`가 `/mcp`에 나타나지 않음

236</h3>236</h3>

237 237 

context-window.md +1591 −5

Details

6 6 

7> Claude Code의 컨텍스트 윈도우가 세션 중에 어떻게 채워지는지 보여주는 대화형 시뮬레이션입니다. 자동으로 로드되는 항목, 각 파일 읽기의 비용, 규칙과 훅이 언제 실행되는지 확인하세요.7> Claude Code의 컨텍스트 윈도우가 세션 중에 어떻게 채워지는지 보여주는 대화형 시뮬레이션입니다. 자동으로 로드되는 항목, 각 파일 읽기의 비용, 규칙과 훅이 언제 실행되는지 확인하세요.

8 8 

9Claude Code의 컨텍스트 윈도우는 Claude가 세션에 대해 알고 있는 모든 것을 보유합니다: 사용자의 지시사항, 읽은 파일, Claude 자신의 응답, 그리고 터미널에 나타나지 않는 콘텐츠입니다. 아래 타임라인은 무엇이 로드되고 언제 로드되는지를 설명합니다. 동일한 콘텐츠를 목록으로 보려면 [작성된 분석](#what-the-timeline-shows) 참조하세요.9export const ContextWindow = () => {

10 const MAX = 200000;

11 const STARTUP_END = 0.2;

12 {}

13 const EVENTS = useMemo(() => [{}, {

14 t: 0.015,

15 kind: 'auto',

16 label: 'System prompt',

17 tokens: 4200,

18 color: '#6B6964',

19 vis: 'hidden',

20 desc: 'Core instructions for behavior, tool use, and response formatting. Always loaded first. You never see it.',

21 link: null

22 }, {

23 t: 0.035,

24 kind: 'auto',

25 label: 'Auto memory (MEMORY.md)',

26 tokens: 680,

27 color: '#E8A45C',

28 vis: 'hidden',

29 desc: "Claude's notes to itself from previous sessions: build commands it learned, patterns it noticed, mistakes to avoid. The first 200 lines or 25KB, whichever comes first, are loaded into the conversation context.",

30 link: '/en/memory#auto-memory'

31 }, {

32 t: 0.06,

33 kind: 'auto',

34 label: 'Environment info',

35 tokens: 280,

36 color: '#6B6964',

37 vis: 'hidden',

38 desc: 'Working directory, platform, shell, OS version, and whether this is a git repo. Git branch, status, and recent commits load as a separate block at the very end of the system prompt.',

39 link: null

40 }, {

41 t: 0.08,

42 kind: 'auto',

43 label: 'MCP tools (deferred)',

44 tokens: 120,

45 color: '#9B7BC4',

46 vis: 'hidden',

47 desc: 'MCP tool names listed so Claude knows what is available. By default, full schemas stay deferred and Claude loads specific ones on demand via tool search when a task needs them. Set `ENABLE_TOOL_SEARCH=auto` to load schemas upfront when they fit within 10% of the context window, or `ENABLE_TOOL_SEARCH=false` to load everything.',

48 link: '/en/mcp#scale-with-mcp-tool-search'

49 }, {

50 t: 0.1,

51 kind: 'auto',

52 label: 'Skill descriptions',

53 tokens: 450,

54 color: '#D4A843',

55 vis: 'hidden',

56 noSurviveCompact: true,

57 desc: 'One-line descriptions of available skills so Claude knows what it can invoke. Full skill content loads only when Claude actually uses one. Skills with `disable-model-invocation: true` are not in this list. They stay completely out of context until you invoke them with `/name`. Unlike the rest of the startup content, this listing is not re-injected after `/compact`. Only skills you actually invoked get preserved.',

58 link: '/en/skills'

59 }, {

60 t: 0.12,

61 kind: 'auto',

62 label: '~/.claude/CLAUDE.md',

63 tokens: 320,

64 color: '#6A9BCC',

65 vis: 'hidden',

66 desc: 'Your global preferences. Applies to every project. Loaded alongside project instructions at the start of every conversation.',

67 link: '/en/memory#choose-where-to-put-claude-md-files'

68 }, {

69 t: 0.14,

70 kind: 'auto',

71 label: 'Project CLAUDE.md',

72 tokens: 1800,

73 color: '#6A9BCC',

74 vis: 'hidden',

75 desc: 'Project conventions, build commands, architecture notes. The most important file you can create. Lives in your project root, so your whole team gets the same instructions.',

76 tip: 'Keep it under 200 lines. Move reference content to skills or path-scoped rules so it only loads when needed.',

77 link: '/en/memory'

78 }, {}, {

79 t: 0.22,

80 kind: 'user',

81 label: 'Your prompt',

82 tokens: 45,

83 color: '#558A42',

84 vis: 'full',

85 desc: '"Fix the auth bug where users get 401 after token refresh"',

86 link: null

87 }, {}, {

88 t: 0.28,

89 kind: 'claude',

90 label: 'Read src/api/auth.ts',

91 tokens: 2400,

92 color: '#8A8880',

93 vis: 'brief',

94 desc: 'Main auth file. You see "Read auth.ts" in your terminal, but the 2,400 tokens of file content only Claude sees.',

95 tip: 'File reads dominate context usage. Be specific in prompts ("fix the bug in auth.ts") so Claude reads fewer files. For research-heavy tasks, use a subagent.',

96 link: null

97 }, {

98 t: 0.32,

99 kind: 'claude',

100 label: 'Read src/lib/tokens.ts',

101 tokens: 1100,

102 color: '#8A8880',

103 vis: 'brief',

104 desc: 'Following imports to the token module. Shown as a one-liner in your terminal.',

105 link: null

106 }, {

107 t: 0.35,

108 kind: 'auto',

109 label: 'Rule: api-conventions.md',

110 tokens: 380,

111 color: '#4A9B8E',

112 vis: 'brief',

113 desc: 'This rule in `.claude/rules/` has a `paths:` pattern matching `src/api/**`. It loaded automatically when Claude read a file in that directory. You see "Loaded .claude/rules/api-conventions.md" in your terminal, but not the rule content.',

114 link: '/en/memory#path-specific-rules'

115 }, {

116 t: 0.38,

117 kind: 'claude',

118 label: 'Read middleware.ts',

119 tokens: 1800,

120 color: '#8A8880',

121 vis: 'brief',

122 desc: 'Tracing the auth flow deeper.',

123 link: null

124 }, {

125 t: 0.41,

126 kind: 'claude',

127 label: 'Read auth.test.ts',

128 tokens: 1600,

129 color: '#8A8880',

130 vis: 'brief',

131 desc: 'Checking existing tests for expected behavior.',

132 link: null

133 }, {

134 t: 0.44,

135 kind: 'auto',

136 label: 'Rule: testing.md',

137 tokens: 290,

138 color: '#4A9B8E',

139 vis: 'brief',

140 desc: 'Another path-scoped rule, this one matching `*.test.ts` files. Triggered when Claude read auth.test.ts. Shown as a one-line "Loaded" notice.',

141 link: '/en/memory#path-specific-rules'

142 }, {

143 t: 0.47,

144 kind: 'claude',

145 label: 'grep "refreshToken"',

146 tokens: 600,

147 color: '#A09E96',

148 vis: 'brief',

149 desc: 'Search results across the codebase. You see the command ran, not the full output.',

150 link: null

151 }, {}, {

152 t: 0.53,

153 kind: 'claude',

154 label: "Claude's analysis",

155 tokens: 800,

156 color: '#D97757',

157 vis: 'full',

158 desc: 'Explains the bug: token invalidated too early in the rotation. This text appears in your terminal.',

159 link: null

160 }, {

161 t: 0.57,

162 kind: 'claude',

163 label: 'Edit auth.ts',

164 tokens: 400,

165 color: '#D97757',

166 vis: 'full',

167 desc: 'Fixes the token rotation order. The diff appears in your terminal.',

168 link: null

169 }, {

170 t: 0.59,

171 kind: 'hook',

172 label: 'Hook: prettier',

173 tokens: 120,

174 color: '#B8860B',

175 vis: 'hidden',

176 desc: 'A PostToolUse hook in `settings.json` runs prettier after every file edit and reports back via `hookSpecificOutput.additionalContext`. That field enters Claude\'s context. Plain stdout on exit 0 does not. It is written to the debug log only.',

177 tip: 'Output JSON with `additionalContext` to send info to Claude. For PostToolUse hooks, exit code 2 surfaces stderr as an error but cannot block since the tool already ran. Keep output concise since it enters context without truncation.',

178 link: '/en/hooks-guide'

179 }, {

180 t: 0.62,

181 kind: 'claude',

182 label: 'Edit auth.test.ts',

183 tokens: 600,

184 color: '#D97757',

185 vis: 'full',

186 desc: 'Adds a regression test for the fix. The diff appears in your terminal.',

187 link: null

188 }, {

189 t: 0.64,

190 kind: 'hook',

191 label: 'Hook: prettier',

192 tokens: 100,

193 color: '#B8860B',

194 vis: 'hidden',

195 desc: 'The same hook fires again for the test file. Every matching tool event triggers it.',

196 link: '/en/hooks-guide'

197 }, {

198 t: 0.67,

199 kind: 'claude',

200 label: 'npm test output',

201 tokens: 1200,

202 color: '#A09E96',

203 vis: 'brief',

204 desc: 'Runs the test suite. You see "Running npm test..." and the pass count, not the full 1,200 tokens of output.',

205 link: null

206 }, {

207 t: 0.70,

208 kind: 'claude',

209 label: 'Summary',

210 tokens: 400,

211 color: '#D97757',

212 vis: 'full',

213 desc: '"Fixed token rotation. Added regression test. All tests pass."',

214 link: null

215 }, {}, {

216 t: 0.72,

217 kind: 'user',

218 label: 'Your follow-up',

219 tokens: 40,

220 color: '#558A42',

221 vis: 'full',

222 desc: '"Use a subagent to research session timeout handling, then fix it"',

223 tip: 'Follow-ups add to the same context. Delegating research to a subagent keeps large file reads out of your main window.',

224 link: null

225 }, {

226 t: 0.79,

227 kind: 'claude',

228 label: 'Spawn research subagent',

229 tokens: 80,

230 color: '#D97757',

231 vis: 'brief',

232 desc: "Claude delegates the research to a subagent with a fresh, separate context window. It loads CLAUDE.md and the same MCP and skill setup, but starts without your conversation history or the main session's auto memory.",

233 link: '/en/sub-agents'

234 }, {

235 t: 0.795,

236 kind: 'sub',

237 label: 'System prompt',

238 tokens: 0,

239 subTokens: 900,

240 color: '#6B6964',

241 vis: 'hidden',

242 desc: "The subagent gets its own system prompt, shorter than the main session's. For the general-purpose agent, it's a brief prompt plus environment details. The main session's auto memory is not included. If a custom agent has memory: in its frontmatter, it loads its own separate MEMORY.md here instead.",

243 link: '/en/sub-agents#enable-persistent-memory'

244 }, {

245 t: 0.80,

246 kind: 'sub',

247 label: 'Project CLAUDE.md (own copy)',

248 tokens: 0,

249 subTokens: 1800,

250 color: '#6A9BCC',

251 vis: 'hidden',

252 desc: "The subagent loads CLAUDE.md too. Same file, same content, but it counts against the subagent's context, not yours. The built-in Explore and Plan agents skip this for a smaller context.",

253 link: '/en/sub-agents'

254 }, {

255 t: 0.805,

256 kind: 'sub',

257 label: 'MCP tools + skills',

258 tokens: 0,

259 subTokens: 970,

260 color: '#9B7BC4',

261 vis: 'hidden',

262 desc: "The subagent has access to the same MCP servers and skills. It gets most of the parent's tools, minus several that don't apply in a nested context, including plan-mode controls, background-task tools, and by default the Agent tool itself to prevent recursion.",

263 link: '/en/sub-agents'

264 }, {

265 t: 0.81,

266 kind: 'sub',

267 label: 'Task prompt from main',

268 tokens: 0,

269 subTokens: 120,

270 color: '#558A42',

271 vis: 'hidden',

272 desc: "Instead of a user prompt, the subagent receives the task Claude wrote for it: 'Research session timeout handling in this codebase.'",

273 link: '/en/sub-agents'

274 }, {

275 t: 0.82,

276 kind: 'sub',

277 label: 'Read session.ts',

278 tokens: 0,

279 subTokens: 2200,

280 color: '#8A8880',

281 vis: 'hidden',

282 desc: "Now the subagent does its work. This file read fills the subagent's context, not yours.",

283 link: '/en/sub-agents'

284 }, {

285 t: 0.825,

286 kind: 'sub',

287 label: 'Read timeouts.ts',

288 tokens: 0,

289 subTokens: 800,

290 color: '#8A8880',

291 vis: 'hidden',

292 desc: "Another file read in the subagent's separate context.",

293 link: '/en/sub-agents'

294 }, {

295 t: 0.83,

296 kind: 'sub',

297 label: 'Read config/*.ts',

298 tokens: 0,

299 subTokens: 3100,

300 color: '#8A8880',

301 vis: 'hidden',

302 desc: "The subagent can read as many files as it needs. None of this touches your main context.",

303 link: '/en/sub-agents'

304 }, {

305 t: 0.85,

306 kind: 'claude',

307 label: 'Subagent returns summary',

308 tokens: 420,

309 color: '#D97757',

310 vis: 'brief',

311 desc: "Only the subagent's final text response comes back to your context, plus a small metadata trailer with token counts and duration. The subagent read 6,100 tokens of files. You got a 420-token result. That's the context savings.",

312 link: '/en/sub-agents'

313 }, {

314 t: 0.86,

315 kind: 'claude',

316 label: "Claude's response",

317 tokens: 1200,

318 color: '#D97757',

319 vis: 'full',

320 desc: 'Analysis and fix for session timeouts. This text appears in your terminal.',

321 link: null

322 }, {}, {

323 t: 0.875,

324 kind: 'user',

325 label: '!git status',

326 tokens: 180,

327 color: '#558A42',

328 vis: 'full',

329 desc: "You ran a shell command with the ! prefix to see which files Claude modified. The command and its output both enter context as part of your message. Useful for grounding Claude in command output without Claude running it.",

330 link: '/en/interactive-mode#bash-mode-with-prefix'

331 }, {

332 t: 0.89,

333 kind: 'user',

334 label: '/commit-push',

335 tokens: 620,

336 color: '#558A42',

337 vis: 'brief',

338 desc: 'You invoked a skill that has `disable-model-invocation: true`. Its description was not in the skill index at startup, so it cost zero context until this moment. Now the full skill content loads and Claude follows its instructions to stage, commit, and push your changes.',

339 tip: 'Set `disable-model-invocation: true` on skills with side effects like committing, deploying, or sending messages. They stay out of context entirely until you need them.',

340 link: '/en/skills#control-who-invokes-a-skill'

341 }, {}, {

342 t: 0.93,

343 kind: 'compact',

344 label: '/compact',

345 tokens: 0,

346 color: '#D97757',

347 vis: 'brief',

348 desc: 'Replaces the conversation with a structured summary. You see a "Conversation compacted" message. The summarization happens without appearing in your terminal.',

349 link: '/en/how-claude-code-works#the-context-window'

350 }].filter(e => e.t !== undefined), []);

351 const VIS_META = {

352 hidden: {

353 label: 'Invisible in your terminal',

354 sub: 'This content does not appear in your terminal.'

355 },

356 brief: {

357 label: 'One-liner in your terminal',

358 sub: 'You see a brief mention, not the full content.'

359 },

360 full: {

361 label: 'Shown in your terminal',

362 sub: 'The actual content appears in your terminal.'

363 }

364 };

365 {}

366 const GATES = [{

367 at: 0.18,

368 kind: 'prompt',

369 text: 'Fix the auth bug where users get 401 after token refresh',

370 resumeTo: 0.22

371 }, {

372 at: 0.705,

373 kind: 'prompt',

374 text: 'Use a subagent to research session timeout handling, then fix it',

375 resumeTo: 0.72

376 }, {

377 at: 0.865,

378 kind: 'bang',

379 text: '!git status',

380 resumeTo: 0.875

381 }, {

382 at: 0.88,

383 kind: 'slash',

384 text: '/commit-push',

385 resumeTo: 0.89

386 }, {

387 at: 0.90,

388 kind: 'compact',

389 text: '/compact',

390 resumeTo: 1

391 }];

392 const KIND_META = {

393 auto: {

394 badge: 'auto',

395 detail: 'Auto-loaded',

396 badgeBg: 'rgba(94,93,89,0.15)',

397 badgeColor: '#8A8880'

398 },

399 user: {

400 badge: 'you',

401 detail: 'You typed this',

402 badgeBg: 'rgba(85,138,66,0.15)',

403 badgeColor: '#6BA656'

404 },

405 claude: {

406 badge: 'claude',

407 detail: "Claude's work",

408 badgeBg: 'rgba(217,119,87,0.12)',

409 badgeColor: '#D97757'

410 },

411 hook: {

412 badge: 'hook',

413 detail: 'Hook (automatic)',

414 badgeBg: 'rgba(184,134,11,0.15)',

415 badgeColor: '#CCA020'

416 },

417 compact: {

418 badge: 'compact',

419 detail: 'Compaction',

420 badgeBg: 'rgba(217,119,87,0.12)',

421 badgeColor: '#D97757'

422 },

423 sub: {

424 badge: 'subagent',

425 detail: "In subagent's context",

426 badgeBg: 'rgba(155,123,196,0.12)',

427 badgeColor: '#9B7BC4'

428 }

429 };

430 const LEGEND = [{

431 c: '#6B6964',

432 l: 'System'

433 }, {

434 c: '#6A9BCC',

435 l: 'CLAUDE.md'

436 }, {

437 c: '#E8A45C',

438 l: 'Memory'

439 }, {

440 c: '#D4A843',

441 l: 'Skills'

442 }, {

443 c: '#9B7BC4',

444 l: 'MCP'

445 }, {

446 c: '#4A9B8E',

447 l: 'Rules'

448 }, {

449 c: '#558A42',

450 l: 'You'

451 }, {

452 c: '#8A8880',

453 l: 'Files'

454 }, {

455 c: '#A09E96',

456 l: 'Output'

457 }, {

458 c: '#D97757',

459 l: 'Claude'

460 }, {

461 c: '#B8860B',

462 l: 'Hooks'

463 }];

464 const fmt = n => n >= 1000 ? (n / 1000).toFixed(1).replace(/\.0$/, '') + 'K' : n + '';

465 const [time, setTime] = useState(0);

466 const [playing, setPlaying] = useState(false);

467 const [hovIdx, setHovIdx] = useState(null);

468 const [selIdx, setSelIdx] = useState(null);

469 const [hovCat, setHovCat] = useState(null);

470 const [gatesPassed, setGatesPassed] = useState(0);

471 const [mounted, setMounted] = useState(false);

472 const [hasInteracted, setHasInteracted] = useState(false);

473 const lastRef = useRef(null);

474 const scrollRef = useRef(null);

475 const detailRef = useRef(null);

476 useEffect(() => setMounted(true), []);

477 const activeGate = GATES.find((g, i) => i >= gatesPassed && time >= g.at && time < g.resumeTo);

478 useEffect(() => {

479 if (!playing) return;

480 let raf;

481 let stopped = false;

482 const tick = ts => {

483 if (stopped) return;

484 if (!lastRef.current) lastRef.current = ts;

485 const dt = (ts - lastRef.current) / 1000;

486 lastRef.current = ts;

487 setTime(prev => {

488 const next = prev + dt * 0.032;

489 const gate = GATES.find((g, i) => i >= gatesPassed && next >= g.at && prev < g.resumeTo);

490 if (gate) {

491 stopped = true;

492 setPlaying(false);

493 return gate.at;

494 }

495 if (next >= 1) {

496 stopped = true;

497 setPlaying(false);

498 return 1;

499 }

500 return next;

501 });

502 if (!stopped) raf = requestAnimationFrame(tick);

503 };

504 raf = requestAnimationFrame(tick);

505 return () => {

506 stopped = true;

507 cancelAnimationFrame(raf);

508 lastRef.current = null;

509 };

510 }, [playing, gatesPassed]);

511 const sendPrompt = () => {

512 if (!activeGate) return;

513 const isCompact = activeGate.kind === 'compact';

514 setGatesPassed(n => n + 1);

515 setTime(activeGate.resumeTo);

516 setSelIdx(null);

517 setHovIdx(null);

518 if (!isCompact) setPlaying(true);

519 };

520 const visibleCount = EVENTS.filter(e => e.t <= time).length;

521 const preCompactVisible = useMemo(() => EVENTS.slice(0, visibleCount), [EVENTS, visibleCount]);

522 const compactGateIdx = GATES.length - 1;

523 const isCompacted = gatesPassed > compactGateIdx && preCompactVisible.some(e => e.kind === 'compact');

524 const {visible, preCompactTotal} = useMemo(() => {

525 const nonCompact = preCompactVisible.filter(e => e.kind !== 'compact');

526 if (!isCompacted) {

527 return {

528 visible: preCompactVisible,

529 preCompactTotal: 0

530 };

531 }

532 {}

533 const autoLoads = nonCompact.filter(e => e.kind === 'auto' && e.t < STARTUP_END && !e.noSurviveCompact);

534 const summarized = nonCompact.filter(e => e.t >= STARTUP_END && e.kind !== 'sub');

535 const sumTokens = summarized.reduce((s, e) => s + e.tokens, 0);

536 const summaryBlock = {

537 t: STARTUP_END,

538 kind: 'compact',

539 label: 'Conversation summary',

540 tokens: Math.round(sumTokens * 0.12),

541 color: '#A09E96',

542 vis: 'hidden',

543 desc: `All ${summarized.length} conversation events condensed into one structured summary. The summary keeps: your requests and intent, key technical concepts, files examined or modified with important code snippets, errors and how they were fixed, pending tasks, and current work. It replaces the verbatim conversation: full tool outputs and intermediate reasoning are gone. Claude can still reference the work but won't have the exact code it read earlier.`,

544 link: '/en/how-claude-code-works#the-context-window'

545 };

546 return {

547 visible: [...autoLoads, summaryBlock],

548 preCompactTotal: nonCompact.reduce((s, e) => s + e.tokens, 0)

549 };

550 }, [preCompactVisible, isCompacted]);

551 const {blocks, totalTokens} = useMemo(() => {

552 const bl = visible.map((e, visIdx) => ({

553 ...e,

554 id: e.label + e.t,

555 visIdx

556 })).filter(e => e.tokens > 0 || e.label === 'Conversation summary');

557 return {

558 blocks: bl,

559 totalTokens: bl.reduce((s, b) => s + b.tokens, 0)

560 };

561 }, [visible]);

562 const subTotal = useMemo(() => visible.filter(e => e.kind === 'sub').reduce((s, e) => s + (e.subTokens || 0), 0), [visible]);

563 useEffect(() => {

564 if (!scrollRef.current) return;

565 if (isCompacted) scrollRef.current.scrollTo({

566 top: 0,

567 behavior: 'smooth'

568 }); else if (playing || activeGate) scrollRef.current.scrollTop = scrollRef.current.scrollHeight;

569 }, [visible.length, !!activeGate, isCompacted]);

570 const rootRef = useRef(null);

571 const keyStateRef = useRef({});

572 const [isFullscreen, setIsFullscreen] = useState(false);

573 keyStateRef.current = {

574 time,

575 activeGate,

576 sendPrompt,

577 hasInteracted

578 };

579 useEffect(() => {

580 const onFsChange = () => setIsFullscreen(!!document.fullscreenElement);

581 document.addEventListener('fullscreenchange', onFsChange);

582 return () => document.removeEventListener('fullscreenchange', onFsChange);

583 }, []);

584 const toggleFullscreen = () => {

585 if (!rootRef.current) return;

586 if (document.fullscreenElement) document.exitFullscreen(); else rootRef.current.requestFullscreen().catch(() => {});

587 };

588 useEffect(() => {

589 const onKey = e => {

590 const tag = e.target.tagName;

591 if (tag === 'INPUT' || tag === 'BUTTON' || tag === 'TEXTAREA' || tag === 'SELECT' || e.target.isContentEditable) return;

592 if (!rootRef.current) return;

593 const rect = rootRef.current.getBoundingClientRect();

594 if (rect.width === 0 && rect.height === 0) return;

595 if (rect.bottom < 0 || rect.top > window.innerHeight) return;

596 if (e.code === 'Space') {

597 const {time: t, activeGate: g, sendPrompt: send, hasInteracted: hi} = keyStateRef.current;

598 if (!hi) return;

599 e.preventDefault();

600 if (t === 0) setPlaying(true); else if (g) send(); else if (t >= 1) {

601 setTime(0);

602 setGatesPassed(0);

603 setSelIdx(null);

604 setHovIdx(null);

605 setPlaying(true);

606 } else setPlaying(p => !p);

607 }

608 };

609 window.addEventListener('keydown', onKey);

610 return () => window.removeEventListener('keydown', onKey);

611 }, []);

612 const pct = totalTokens / MAX * 100;

613 const barColor = pct > 75 ? '#D97757' : pct > 50 ? '#B8860B' : '#558A42';

614 const activeIdx = selIdx !== null ? selIdx : hovIdx;

615 const hovEvent = activeIdx !== null ? visible[activeIdx] : null;

616 useEffect(() => {

617 if (detailRef.current) detailRef.current.scrollTop = 0;

618 }, [hovEvent]);

619 const focusT = hovEvent ? hovEvent.t : time;

620 const takeaway = isCompacted ? 'Compaction replaces the conversation with a structured summary. System prompt, CLAUDE.md, memory, and MCP tools reload automatically. The skill listing is the one exception. Only skills you actually invoked are preserved.' : focusT < STARTUP_END ? 'A lot loads before you type anything. CLAUDE.md, memory, skills, and MCP tools are all in context before your first prompt.' : focusT < 0.28 ? "Your prompt is tiny compared to what's already loaded. Most of Claude's context is project knowledge, not your words." : focusT < 0.50 ? 'Each file Claude reads grows the context. Path-scoped rules load automatically alongside matching files.' : focusT < 0.71 ? 'Hooks fire automatically on tool events. Output reaches Claude via additionalContext JSON. Exit code 2 surfaces stderr to Claude. Plain stdout on exit 0 goes to the debug log, not the transcript.' : focusT < 0.79 ? 'Follow-up questions keep building on the same context. Everything from earlier is still there.' : focusT < 0.87 ? "The subagent works in its own separate context window. None of its file reads touch yours. Only the final summary comes back." : focusT < 0.88 ? 'Bang commands run in your shell and prefix the output to your next message. Useful for grounding Claude in command results without it running them.' : focusT < 0.90 ? 'User-only skills stay out of context entirely until you invoke them. The skill index at startup only lists skills Claude can call on its own.' : '/compact summarizes the conversation to free space while keeping key information. In a real session, run it when context starts affecting performance or before a long new task.';

621 const terminalView = isCompacted ? 'A "Conversation compacted" message. The summarization happens silently.' : focusT < STARTUP_END ? 'The input box, waiting for your first message. Everything above loads silently before you type anything.' : focusT < 0.28 ? 'Your prompt. Claude hasn\'t started working yet.' : focusT < 0.52 ? 'Your prompt and "Reading files...". Rules show as one-line "Loaded" notices, not their content.' : focusT < 0.72 ? "Claude's response and file diffs. Hooks fire silently. Tool output like npm test shows as a brief summary, not the full content." : focusT < 0.79 ? 'Your follow-up prompt.' : focusT < 0.86 ? "A brief notice that a subagent is working, then its result. You don't see the subagent's individual file reads." : focusT < 0.90 ? "Claude's response, your git status output, and the commit-push skill running." : 'Your full conversation. /compact is available to run.';

622 const mono = 'var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace)';

623 const renderWithCode = s => s.split('`').map((part, i) => i % 2 === 1 ? <code key={i} style={{

624 fontFamily: mono,

625 fontSize: '0.92em',

626 background: 'var(--cw-track)',

627 padding: '1px 4px',

628 borderRadius: 3

629 }}>{part}</code> : part);

630 if (!mounted) return null;

631 return <>

632 <div className="cw-mobile-fallback">

633 This interactive timeline works best on a larger screen. See <a href="#what-the-timeline-shows" style={{

634 color: '#D97757'

635 }}>the written breakdown below</a> for the same concepts.

636 </div>

637 <div className="cw-root" ref={rootRef} onClickCapture={() => setHasInteracted(true)} style={isFullscreen ? {

638 height: '100vh',

639 borderRadius: 0,

640 display: 'flex',

641 flexDirection: 'column'

642 } : {}}>

643 <style>{`

644 .cw-root {

645 --cw-bg: #FAFAF8;

646 --cw-text: #1A1918;

647 --cw-text-2: #3D3C38;

648 --cw-text-3: #5E5D59;

649 --cw-text-dim: #6E6C64;

650 --cw-text-faint: #8A8880;

651 --cw-surface: rgba(0,0,0,0.025);

652 --cw-surface-2: rgba(0,0,0,0.04);

653 --cw-border: rgba(0,0,0,0.08);

654 --cw-track: rgba(0,0,0,0.04);

655 --cw-hover: rgba(0,0,0,0.04);

656 --cw-rail: rgba(0,0,0,0.08);

657 --cw-scrollbar: rgba(0,0,0,0.22);

658 background: var(--cw-bg);

659 border-radius: 12px;

660 overflow: hidden;

661 font-family: var(--font-sans, -apple-system, BlinkMacSystemFont, sans-serif);

662 color: var(--cw-text);

663 border: 1px solid var(--cw-border);

664 }

665 .dark .cw-root {

666 --cw-bg: #111110;

667 --cw-text: #E8E6DC;

668 --cw-text-2: #B8B6AE;

669 --cw-text-3: #9C9A92;

670 --cw-text-dim: #8A8880;

671 --cw-text-faint: #6E6C64;

672 --cw-surface: rgba(255,255,255,0.02);

673 --cw-surface-2: rgba(255,255,255,0.015);

674 --cw-border: rgba(255,255,255,0.06);

675 --cw-track: rgba(255,255,255,0.03);

676 --cw-hover: rgba(255,255,255,0.04);

677 --cw-rail: rgba(255,255,255,0.04);

678 --cw-scrollbar: rgba(255,255,255,0.18);

679 }

680 .cw-scroll::-webkit-scrollbar { width: 6px; }

681 .cw-scroll::-webkit-scrollbar-track { background: transparent; }

682 .cw-scroll::-webkit-scrollbar-thumb { background: var(--cw-scrollbar); border-radius: 3px; }

683 @keyframes cw-blink { 50% { opacity: 0; } }

684 @keyframes cw-fadein { from { opacity: 0; transform: translateY(-4px); } to { opacity: 1; transform: translateY(0); } }

685 .cw-compacted-row { animation: cw-fadein 0.3s ease-out backwards; }

686 .cw-mobile-fallback { display: none; padding: 14px 16px; border-radius: 8px; font-size: 14px; border: 1px solid rgba(0,0,0,0.1); background: rgba(0,0,0,0.03); }

687 .dark .cw-mobile-fallback { border-color: rgba(255,255,255,0.15); background: rgba(255,255,255,0.04); }

688 @media (max-width: 700px) {

689 .cw-root { display: none !important; }

690 .cw-mobile-fallback { display: block; }

691 }

692 `}</style>

10 693 

11## 타임라인이 보여주는 것694 {}

695 <div style={{

696 padding: '16px 20px 12px',

697 display: 'flex',

698 alignItems: 'flex-end',

699 gap: 24

700 }}>

701 <div style={{

702 flex: 1,

703 minWidth: 0

704 }}>

705 <div style={{

706 fontSize: 18,

707 fontWeight: 600,

708 letterSpacing: -0.3,

709 lineHeight: 1

710 }}>

711 Explore the context window

712 </div>

713 <div style={{

714 fontSize: 14,

715 color: 'var(--cw-text-dim)',

716 marginTop: 4

717 }}>

718 A simulated session showing what enters context and what it costs

719 </div>

720 </div>

721 <div style={{

722 textAlign: 'right',

723 flexShrink: 0

724 }}>

725 <div style={{

726 fontFamily: mono,

727 fontSize: 20,

728 fontWeight: 600,

729 color: barColor,

730 letterSpacing: -0.5,

731 lineHeight: 1

732 }}>

733 ~{fmt(totalTokens)}<span style={{

734 fontSize: 15,

735 fontWeight: 500,

736 marginLeft: 4

737 }}>tokens</span>

738 </div>

739 <div style={{

740 fontFamily: mono,

741 fontSize: 13,

742 color: 'var(--cw-text-dim)',

743 marginTop: 2

744 }} title="Token counts are illustrative. Actual values vary with your CLAUDE.md size, MCP servers, and file lengths.">

745 / {fmt(MAX)} · illustrative

746 </div>

747 </div>

748 </div>

749 

750 {}

751 <div style={{

752 padding: '0 20px'

753 }}>

754 <div style={{

755 height: 4,

756 borderRadius: 2,

757 background: 'var(--cw-track)',

758 overflow: 'hidden',

759 marginBottom: 6

760 }}>

761 <div style={{

762 width: pct + '%',

763 height: '100%',

764 background: barColor,

765 transition: 'width 0.6s cubic-bezier(0.4, 0, 0.2, 1), background 0.3s'

766 }} />

767 </div>

768 <div style={{

769 height: 28,

770 borderRadius: 5,

771 background: 'var(--cw-track)',

772 border: '1px solid var(--cw-border)',

773 overflow: 'hidden',

774 display: 'flex'

775 }}>

776 {blocks.map((b, i) => {

777 const w = Math.max(b.tokens / MAX * 100, 0.15);

778 const isHov = b.visIdx === activeIdx;

779 const catMatch = hovCat && b.color === hovCat;

780 const dimmed = hovCat ? !catMatch : activeIdx !== null && !isHov;

781 return <div key={b.id} onMouseEnter={() => setHovIdx(b.visIdx)} onMouseLeave={() => setHovIdx(null)} onClick={() => setSelIdx(selIdx === b.visIdx ? null : b.visIdx)} style={{

782 width: w + '%',

783 height: '100%',

784 background: b.color,

785 opacity: isHov || catMatch ? 1 : dimmed ? 0.25 : 0.65,

786 borderRight: i < blocks.length - 1 ? '0.5px solid var(--cw-border)' : 'none',

787 transition: 'opacity 0.15s',

788 cursor: 'pointer'

789 }} />;

790 })}

791 </div>

792 <div style={{

793 display: 'flex',

794 gap: 12,

795 marginTop: 6,

796 flexWrap: 'wrap',

797 justifyContent: 'space-between'

798 }}>

799 <div style={{

800 display: 'flex',

801 gap: 12,

802 flexWrap: 'wrap'

803 }}>

804 {LEGEND.map(x => {

805 const active = hovCat === x.c;

806 return <div key={x.l} onMouseEnter={() => setHovCat(x.c)} onMouseLeave={() => setHovCat(null)} style={{

807 display: 'flex',

808 alignItems: 'center',

809 gap: 4,

810 padding: '2px 6px',

811 borderRadius: 4,

812 cursor: 'pointer',

813 background: active ? 'var(--cw-hover)' : 'transparent',

814 transition: 'background 0.1s'

815 }}>

816 <div style={{

817 width: 6,

818 height: 6,

819 borderRadius: 1.5,

820 background: x.c,

821 opacity: active ? 1 : 0.7

822 }} />

823 <span style={{

824 fontSize: 12,

825 color: active ? 'var(--cw-text)' : 'var(--cw-text-dim)'

826 }}>{x.l}</span>

827 </div>;

828 })}

829 </div>

830 <div style={{

831 display: 'flex',

832 gap: 6,

833 alignItems: 'center',

834 fontSize: 12,

835 color: 'var(--cw-text-dim)'

836 }}>

837 <svg width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="#558A42" strokeWidth="2.5">

838 <path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z" /><circle cx="12" cy="12" r="3" />

839 </svg>

840 <span>= appears in your terminal</span>

841 </div>

842 </div>

843 </div>

844 

845 {}

846 <div style={{

847 display: 'flex',

848 padding: '14px 20px 0',

849 gap: 16,

850 height: isFullscreen ? 'calc(100vh - 240px)' : 420

851 }}>

852 

853 {}

854 <div ref={scrollRef} className="cw-scroll" style={{

855 flex: 1,

856 minWidth: 0,

857 overflowY: 'auto',

858 paddingRight: 8,

859 scrollBehavior: 'smooth'

860 }}>

861 {visible.length === 0 && !playing && <div style={{

862 height: '100%',

863 display: 'flex',

864 flexDirection: 'column',

865 alignItems: 'center',

866 justifyContent: 'center',

867 gap: 16

868 }}>

869 <div style={{

870 fontFamily: mono,

871 fontSize: 16,

872 color: 'var(--cw-text-dim)',

873 display: 'flex',

874 alignItems: 'center',

875 gap: 8

876 }}>

877 <span style={{

878 color: 'var(--cw-text-faint)'

879 }}>$</span>

880 <span>claude</span>

881 <span style={{

882 display: 'inline-block',

883 width: 8,

884 height: 16,

885 background: 'var(--cw-text-dim)',

886 opacity: 0.5,

887 animation: 'cw-blink 1s step-end infinite'

888 }} />

889 </div>

890 <button onClick={() => setPlaying(true)} style={{

891 padding: '10px 20px',

892 borderRadius: 8,

893 border: '1px solid rgba(217,119,87,0.3)',

894 background: 'rgba(217,119,87,0.08)',

895 color: '#D97757',

896 fontSize: 15,

897 fontWeight: 600,

898 cursor: 'pointer',

899 display: 'flex',

900 alignItems: 'center',

901 gap: 8

902 }}>

903 <span>▶</span>

904 <span>Start session</span>

905 </button>

906 <div style={{

907 fontSize: 13,

908 color: 'var(--cw-text-faint)',

909 maxWidth: 280,

910 textAlign: 'center',

911 lineHeight: 1.5

912 }}>

913 Watch what loads into context, from the moment you run <code style={{

914 fontFamily: mono

915 }}>claude</code> through a full conversation.

916 </div>

917 </div>}

918 {isCompacted && <div style={{

919 marginBottom: 10,

920 padding: '10px 12px',

921 borderRadius: 6,

922 background: 'rgba(217,119,87,0.05)',

923 border: '1px solid rgba(217,119,87,0.15)'

924 }}>

925 <div style={{

926 fontSize: 13,

927 fontWeight: 600,

928 color: '#D97757',

929 marginBottom: 3

930 }}>

931 After /compact

932 </div>

933 <div style={{

934 fontSize: 13,

935 color: 'var(--cw-text-3)',

936 lineHeight: 1.5,

937 fontFamily: mono

938 }}>

939 {fmt(preCompactTotal)} → {fmt(totalTokens)} tokens · freed {fmt(preCompactTotal - totalTokens)}

940 </div>

941 <div style={{

942 fontSize: 13,

943 color: 'var(--cw-text-dim)',

944 lineHeight: 1.5,

945 marginTop: 4

946 }}>

947 This is what's left in context: startup content, which lives outside the message history and reloads after compaction, plus a structured summary of the entire conversation. Skill descriptions don't reload.

948 </div>

949 </div>}

950 {time > 0 && visible.length > 0 && <div style={{

951 fontSize: 12,

952 fontWeight: 700,

953 color: 'var(--cw-text-faint)',

954 textTransform: 'uppercase',

955 letterSpacing: 0.6,

956 marginBottom: 6,

957 paddingLeft: 28

958 }}>

959 {isCompacted ? 'Reloaded after compact' : 'Before you type anything'}

960 </div>}

961 

962 {time > 0 && visible.map((evt, i) => {

963 const meta = KIND_META[evt.kind];

964 const isHov = hovIdx === i;

965 const prevKind = i > 0 ? visible[i - 1].kind : null;

966 const isSub = evt.kind === 'sub';

967 const enteringSubagent = isSub && prevKind !== 'sub';

968 const leavingSubagent = prevKind === 'sub' && !isSub;

969 let showPhase = null;

970 if (evt.kind === 'user' && prevKind !== 'user') showPhase = 'You'; else if (evt.kind === 'claude' && prevKind === 'user') showPhase = 'Claude works'; else if (evt.label === 'Conversation summary') showPhase = 'Summarized by /compact';

971 const isNewRow = isCompacted && !(evt.kind === 'auto' && evt.t < STARTUP_END);

972 return <div key={evt.label + evt.t} className={isNewRow ? 'cw-compacted-row' : ''} style={isNewRow ? {

973 animationDelay: `${i * 60}ms`

974 } : {}}>

975 {showPhase && <div style={{

976 fontSize: 12,

977 fontWeight: 700,

978 color: 'var(--cw-text-faint)',

979 textTransform: 'uppercase',

980 letterSpacing: 0.6,

981 marginTop: 14,

982 marginBottom: 6,

983 paddingLeft: 28

984 }}>

985 {showPhase}

986 </div>}

987 {enteringSubagent && <div style={{

988 marginLeft: 28,

989 marginTop: 6,

990 marginBottom: 2,

991 paddingLeft: 10,

992 borderLeft: '2px solid rgba(155,123,196,0.4)',

993 fontSize: 12,

994 fontWeight: 600,

995 color: '#9B7BC4',

996 textTransform: 'uppercase',

997 letterSpacing: 0.5

998 }}>

999 Subagent's separate context window

1000 </div>}

1001 {leavingSubagent && <div style={{

1002 marginLeft: 28,

1003 marginBottom: 6,

1004 paddingLeft: 10,

1005 paddingBottom: 6,

1006 borderLeft: '2px solid rgba(155,123,196,0.4)',

1007 fontSize: 12,

1008 color: 'var(--cw-text-dim)',

1009 fontFamily: mono

1010 }}>

1011 ↓ {fmt(subTotal)} tokens stayed in subagent's context · only the summary returns

1012 </div>}

1013 <div onMouseEnter={() => setHovIdx(i)} onMouseLeave={() => setHovIdx(null)} onClick={() => setSelIdx(selIdx === i ? null : i)} style={{

1014 display: 'flex',

1015 alignItems: 'flex-start',

1016 borderRadius: 6,

1017 cursor: 'pointer',

1018 background: selIdx === i || isHov ? 'var(--cw-hover)' : 'transparent',

1019 outline: selIdx === i ? '1px solid rgba(217,119,87,0.4)' : 'none',

1020 opacity: hovCat && evt.color !== hovCat ? 0.35 : 1,

1021 transition: 'background 0.1s, opacity 0.15s',

1022 marginLeft: isSub ? 28 : 0,

1023 paddingLeft: isSub ? 10 : 0,

1024 borderLeft: isSub ? '2px solid rgba(155,123,196,0.4)' : 'none'

1025 }}>

1026 <div style={{

1027 width: 28,

1028 display: 'flex',

1029 flexDirection: 'column',

1030 alignItems: 'center',

1031 paddingTop: 8,

1032 flexShrink: 0

1033 }}>

1034 <div style={{

1035 width: evt.kind === 'user' || evt.kind === 'compact' ? 10 : 7,

1036 height: evt.kind === 'user' || evt.kind === 'compact' ? 10 : 7,

1037 borderRadius: '50%',

1038 background: evt.color,

1039 opacity: isHov ? 1 : 0.6,

1040 transition: 'opacity 0.15s',

1041 boxShadow: isHov ? `0 0 8px ${evt.color}40` : 'none'

1042 }} />

1043 {i < visible.length - 1 && <div style={{

1044 width: 1.5,

1045 flex: 1,

1046 background: 'var(--cw-rail)',

1047 marginTop: 2,

1048 minHeight: 6

1049 }} />}

1050 </div>

1051 <div style={{

1052 flex: 1,

1053 minWidth: 0,

1054 padding: '5px 10px 5px 4px',

1055 display: 'flex',

1056 alignItems: 'center',

1057 gap: 8

1058 }}>

1059 <span style={{

1060 fontSize: 12,

1061 fontWeight: 600,

1062 padding: '1px 5px',

1063 borderRadius: 3,

1064 background: meta.badgeBg,

1065 color: meta.badgeColor,

1066 flexShrink: 0,

1067 fontFamily: mono

1068 }}>

1069 {meta.badge}

1070 </span>

1071 <span style={{

1072 fontSize: 15,

1073 fontFamily: mono,

1074 color: isHov ? 'var(--cw-text)' : evt.kind === 'user' ? '#558A42' : evt.kind === 'auto' ? 'var(--cw-text-dim)' : 'var(--cw-text-2)',

1075 flex: 1,

1076 minWidth: 0,

1077 overflow: 'hidden',

1078 textOverflow: 'ellipsis',

1079 whiteSpace: 'nowrap',

1080 fontWeight: evt.kind === 'user' ? 550 : 400

1081 }}>

1082 {evt.label}

1083 </span>

1084 {evt.tokens > 0 && <span style={{

1085 fontSize: 12,

1086 fontFamily: mono,

1087 color: 'var(--cw-text-faint)',

1088 flexShrink: 0

1089 }}>

1090 +{fmt(evt.tokens)}

1091 </span>}

1092 {evt.subTokens > 0 && <span style={{

1093 fontSize: 12,

1094 fontFamily: mono,

1095 color: '#9B7BC4',

1096 flexShrink: 0,

1097 opacity: 0.6

1098 }}>

1099 +{fmt(evt.subTokens)}

1100 </span>}

1101 {evt.tokens > 0 && <div style={{

1102 width: 50,

1103 height: 5,

1104 borderRadius: 2,

1105 background: 'var(--cw-track)',

1106 flexShrink: 0,

1107 overflow: 'hidden'

1108 }}>

1109 <div style={{

1110 width: Math.min(evt.tokens / 5000 * 100, 100) + '%',

1111 height: '100%',

1112 background: evt.color,

1113 opacity: isHov ? 0.8 : 0.4,

1114 transition: 'opacity 0.15s'

1115 }} />

1116 </div>}

1117 <span style={{

1118 width: 14,

1119 flexShrink: 0,

1120 display: 'flex',

1121 justifyContent: 'center'

1122 }} title={VIS_META[evt.vis].label}>

1123 {evt.vis !== 'hidden' && <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke={evt.vis === 'full' ? '#558A42' : 'currentColor'} style={{

1124 color: 'var(--cw-text-faint)',

1125 opacity: evt.vis === 'full' ? 1 : 0.5

1126 }} strokeWidth="2">

1127 <path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z" /><circle cx="12" cy="12" r="3" />

1128 </svg>}

1129 </span>

1130 </div>

1131 </div>

1132 </div>;

1133 })}

1134 

1135 {activeGate && (activeGate.kind === 'prompt' || activeGate.kind === 'bang' || activeGate.kind === 'slash') && <div style={{

1136 paddingLeft: 28,

1137 marginTop: 12,

1138 paddingRight: 8

1139 }}>

1140 <div style={{

1141 fontSize: 11,

1142 fontWeight: 600,

1143 color: '#6BA656',

1144 fontFamily: mono,

1145 textTransform: 'uppercase',

1146 letterSpacing: 0.5,

1147 marginBottom: 4,

1148 paddingLeft: 2

1149 }}>

1150 You type in your terminal

1151 </div>

1152 <div style={{

1153 display: 'flex',

1154 alignItems: 'flex-start',

1155 gap: 8,

1156 padding: '10px 12px',

1157 borderRadius: 6,

1158 background: 'rgba(85,138,66,0.06)',

1159 border: '1px solid rgba(85,138,66,0.2)'

1160 }}>

1161 <span style={{

1162 color: '#558A42',

1163 fontSize: 15,

1164 fontFamily: mono,

1165 flexShrink: 0

1166 }}>❯</span>

1167 <span style={{

1168 fontSize: 15,

1169 fontFamily: mono,

1170 color: 'var(--cw-text-2)',

1171 flex: 1,

1172 lineHeight: 1.5

1173 }}>

1174 {activeGate.text}

1175 <span style={{

1176 display: 'inline-block',

1177 width: 7,

1178 height: 13,

1179 marginLeft: 2,

1180 background: '#558A42',

1181 opacity: 0.5,

1182 verticalAlign: 'middle',

1183 animation: 'cw-blink 1s step-end infinite'

1184 }} />

1185 </span>

1186 <button onClick={sendPrompt} style={{

1187 padding: '5px 12px',

1188 borderRadius: 5,

1189 border: 'none',

1190 background: '#558A42',

1191 color: '#fff',

1192 fontSize: 13,

1193 fontWeight: 600,

1194 cursor: 'pointer',

1195 flexShrink: 0

1196 }}>

1197 {activeGate.kind === 'prompt' ? 'Send ↵' : 'Run ↵'}

1198 </button>

1199 </div>

1200 </div>}

1201 {activeGate && activeGate.kind === 'compact' && <div style={{

1202 paddingLeft: 28,

1203 marginTop: 12,

1204 paddingRight: 8

1205 }}>

1206 <div style={{

1207 padding: '12px 14px',

1208 borderRadius: 6,

1209 background: 'rgba(217,119,87,0.06)',

1210 border: '1px solid rgba(217,119,87,0.25)'

1211 }}>

1212 <div style={{

1213 fontSize: 13,

1214 color: 'var(--cw-text-3)',

1215 marginBottom: 8,

1216 lineHeight: 1.5

1217 }}>

1218 Context is at <span style={{

1219 fontFamily: mono,

1220 fontWeight: 600,

1221 color: barColor

1222 }}>{fmt(totalTokens)} tokens</span>.

1223 Run <code style={{

1224 fontFamily: mono,

1225 background: 'var(--cw-track)',

1226 padding: '1px 4px',

1227 borderRadius: 3

1228 }}>/compact</code> to

1229 summarize older exchanges and free space for more work.

1230 </div>

1231 <div style={{

1232 display: 'flex',

1233 alignItems: 'center',

1234 gap: 8

1235 }}>

1236 <span style={{

1237 color: '#D97757',

1238 fontSize: 15,

1239 fontFamily: mono

1240 }}>❯</span>

1241 <span style={{

1242 fontSize: 15,

1243 fontFamily: mono,

1244 color: 'var(--cw-text-2)',

1245 flex: 1

1246 }}>

1247 {activeGate.text}

1248 </span>

1249 <button onClick={sendPrompt} style={{

1250 padding: '5px 12px',

1251 borderRadius: 5,

1252 border: 'none',

1253 background: '#D97757',

1254 color: '#fff',

1255 fontSize: 13,

1256 fontWeight: 600,

1257 cursor: 'pointer',

1258 flexShrink: 0

1259 }}>

1260 Run ↵

1261 </button>

1262 </div>

1263 </div>

1264 </div>}

1265 </div>

1266 

1267 {}

1268 <div style={{

1269 width: 300,

1270 flexShrink: 0,

1271 display: 'flex',

1272 flexDirection: 'column'

1273 }}>

1274 <div ref={detailRef} className="cw-scroll" style={{

1275 padding: '14px 16px',

1276 borderRadius: 10,

1277 background: 'var(--cw-surface)',

1278 border: '1px solid var(--cw-border)',

1279 flex: 1,

1280 minHeight: 0,

1281 overflowY: 'auto',

1282 display: 'flex',

1283 flexDirection: 'column',

1284 gap: 10

1285 }}>

1286 {hovEvent ? <div>

1287 <div style={{

1288 display: 'flex',

1289 alignItems: 'center',

1290 gap: 8,

1291 marginBottom: 8

1292 }}>

1293 <div style={{

1294 width: 10,

1295 height: 10,

1296 borderRadius: 3,

1297 background: hovEvent.color,

1298 opacity: 0.8

1299 }} />

1300 <span style={{

1301 fontSize: 16,

1302 fontWeight: 600

1303 }}>{hovEvent.label}</span>

1304 </div>

1305 <div style={{

1306 display: 'flex',

1307 width: 'fit-content',

1308 padding: '3px 8px',

1309 borderRadius: 4,

1310 marginBottom: 8,

1311 background: KIND_META[hovEvent.kind].badgeBg

1312 }}>

1313 <span style={{

1314 fontSize: 12,

1315 fontWeight: 600,

1316 color: KIND_META[hovEvent.kind].badgeColor

1317 }}>

1318 {KIND_META[hovEvent.kind].detail}

1319 </span>

1320 </div>

1321 {hovEvent.tokens > 0 && <div style={{

1322 fontSize: 14,

1323 fontFamily: mono,

1324 color: 'var(--cw-text-dim)',

1325 marginBottom: 6

1326 }}>

1327 {fmt(hovEvent.tokens)} tokens

1328 </div>}

1329 {hovEvent.subTokens > 0 && <div style={{

1330 fontSize: 14,

1331 fontFamily: mono,

1332 color: '#9B7BC4',

1333 marginBottom: 6

1334 }}>

1335 {fmt(hovEvent.subTokens)} tokens in the subagent's context

1336 </div>}

1337 <p style={{

1338 fontSize: 15,

1339 color: 'var(--cw-text-3)',

1340 lineHeight: 1.55,

1341 margin: 0

1342 }}>

1343 {renderWithCode(hovEvent.desc)}

1344 </p>

1345 <div style={{

1346 marginTop: 10,

1347 padding: '8px 10px',

1348 borderRadius: 6,

1349 background: hovEvent.vis === 'full' ? 'rgba(85,138,66,0.08)' : 'var(--cw-surface-2)',

1350 border: '1px solid ' + (hovEvent.vis === 'full' ? 'rgba(85,138,66,0.2)' : 'var(--cw-border)')

1351 }}>

1352 <div style={{

1353 display: 'flex',

1354 alignItems: 'center',

1355 gap: 6,

1356 marginBottom: 3

1357 }}>

1358 <span style={{

1359 fontSize: 13,

1360 color: hovEvent.vis === 'full' ? '#558A42' : 'var(--cw-text-dim)'

1361 }}>

1362 {hovEvent.vis === 'full' ? '●' : hovEvent.vis === 'brief' ? '◐' : '○'}

1363 </span>

1364 <span style={{

1365 fontSize: 12,

1366 fontWeight: 600,

1367 color: 'var(--cw-text-2)'

1368 }}>

1369 {VIS_META[hovEvent.vis].label}

1370 </span>

1371 </div>

1372 <div style={{

1373 fontSize: 13,

1374 color: 'var(--cw-text-dim)',

1375 lineHeight: 1.4

1376 }}>

1377 {VIS_META[hovEvent.vis].sub}

1378 </div>

1379 </div>

1380 {hovEvent.tip && <div style={{

1381 marginTop: 10,

1382 padding: '8px 10px',

1383 borderRadius: 6,

1384 background: 'rgba(85,138,66,0.06)',

1385 border: '1px solid rgba(85,138,66,0.15)'

1386 }}>

1387 <div style={{

1388 fontSize: 12,

1389 fontWeight: 600,

1390 color: '#558A42',

1391 marginBottom: 3,

1392 display: 'flex',

1393 alignItems: 'center',

1394 gap: 4

1395 }}>

1396 <span>💡</span> Save context

1397 </div>

1398 <div style={{

1399 fontSize: 13,

1400 color: 'var(--cw-text-3)',

1401 lineHeight: 1.5

1402 }}>

1403 {renderWithCode(hovEvent.tip)}

1404 </div>

1405 </div>}

1406 {hovEvent.link && <a href={hovEvent.link} style={{

1407 display: 'inline-block',

1408 marginTop: 10,

1409 fontSize: 13,

1410 color: '#D97757',

1411 textDecoration: 'none',

1412 borderBottom: '1px solid rgba(217,119,87,0.3)'

1413 }}>

1414 Learn more →

1415 </a>}

1416 </div> : <div style={{

1417 display: 'flex',

1418 flexDirection: 'column',

1419 alignItems: 'center',

1420 textAlign: 'center',

1421 gap: 4,

1422 padding: '12px 0 4px'

1423 }}>

1424 <div style={{

1425 fontSize: 22,

1426 opacity: 0.2

1427 }}>👁</div>

1428 <div style={{

1429 fontSize: 14,

1430 fontWeight: 500,

1431 color: 'var(--cw-text-dim)'

1432 }}>Hover or click any event</div>

1433 <div style={{

1434 fontSize: 12,

1435 color: 'var(--cw-text-faint)',

1436 lineHeight: 1.4,

1437 maxWidth: 200

1438 }}>

1439 Hover to preview. Click to pin so you can scroll.

1440 </div>

1441 </div>}

1442 

1443 <div style={{

1444 padding: '10px 12px',

1445 borderRadius: 8,

1446 background: 'rgba(217,119,87,0.05)',

1447 border: '1px solid rgba(217,119,87,0.12)'

1448 }}>

1449 <div style={{

1450 fontSize: 11,

1451 fontWeight: 700,

1452 color: '#D97757',

1453 textTransform: 'uppercase',

1454 letterSpacing: 0.5,

1455 marginBottom: 3

1456 }}>

1457 Key takeaway

1458 </div>

1459 <div style={{

1460 fontSize: 13,

1461 color: 'var(--cw-text-3)',

1462 lineHeight: 1.5

1463 }}>

1464 {takeaway}

1465 </div>

1466 </div>

1467 

1468 <div style={{

1469 padding: '10px 12px',

1470 borderRadius: 8,

1471 background: 'var(--cw-surface-2)',

1472 border: '1px solid var(--cw-border)'

1473 }}>

1474 <div style={{

1475 fontSize: 11,

1476 fontWeight: 700,

1477 color: 'var(--cw-text-dim)',

1478 textTransform: 'uppercase',

1479 letterSpacing: 0.5,

1480 marginBottom: 3

1481 }}>

1482 In your terminal you see

1483 </div>

1484 <div style={{

1485 fontSize: 13,

1486 color: 'var(--cw-text-3)',

1487 lineHeight: 1.5

1488 }}>

1489 {terminalView}

1490 </div>

1491 </div>

1492 </div>

1493 </div>

1494 </div>

1495 

1496 {}

1497 <div style={{

1498 padding: '10px 20px 14px',

1499 display: 'flex',

1500 alignItems: 'center',

1501 gap: 10

1502 }}>

1503 <button aria-label={time >= 1 ? 'Restart' : activeGate ? 'Continue' : playing ? 'Pause' : 'Play'} onClick={() => {

1504 if (time >= 1) {

1505 setTime(0);

1506 setGatesPassed(0);

1507 setSelIdx(null);

1508 setHovIdx(null);

1509 setPlaying(true);

1510 } else if (activeGate) sendPrompt(); else setPlaying(!playing);

1511 }} style={{

1512 width: 30,

1513 height: 30,

1514 borderRadius: 6,

1515 border: 'none',

1516 background: 'rgba(217,119,87,0.1)',

1517 color: '#D97757',

1518 cursor: 'pointer',

1519 fontSize: 15,

1520 fontWeight: 700,

1521 display: 'flex',

1522 alignItems: 'center',

1523 justifyContent: 'center'

1524 }}>

1525 {time >= 1 ? '↺' : playing ? '⏸' : '▶'}

1526 </button>

1527 <div style={{

1528 flex: 1,

1529 height: 3,

1530 borderRadius: 2,

1531 background: 'var(--cw-track)',

1532 overflow: 'hidden'

1533 }}>

1534 <div style={{

1535 width: time * 100 + '%',

1536 height: '100%',

1537 background: '#D97757',

1538 transition: 'width 0.1s linear'

1539 }} />

1540 </div>

1541 <span style={{

1542 fontSize: 12,

1543 fontFamily: mono,

1544 color: 'var(--cw-text-faint)',

1545 minWidth: 30

1546 }}>

1547 {Math.round(time * 100)}%

1548 </span>

1549 <button onClick={toggleFullscreen} aria-label={isFullscreen ? 'Exit fullscreen' : 'Enter fullscreen'} title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'} style={{

1550 width: 28,

1551 height: 28,

1552 borderRadius: 6,

1553 border: '1px solid var(--cw-border)',

1554 background: 'var(--cw-surface)',

1555 color: 'var(--cw-text-dim)',

1556 cursor: 'pointer',

1557 fontSize: 15,

1558 flexShrink: 0,

1559 marginLeft: 4,

1560 display: 'flex',

1561 alignItems: 'center',

1562 justifyContent: 'center'

1563 }}>

1564 {isFullscreen ? '⤡' : '⛶'}

1565 </button>

1566 </div>

1567 </div>

1568 </>;

1569};

1570 

1571Claude Code의 컨텍스트 윈도우는 Claude가 세션에 대해 알고 있는 모든 것을 보유합니다: 사용자의 지시사항, 읽은 파일, Claude 자신의 응답, 그리고 터미널에 나타나지 않는 콘텐츠입니다. 아래 타임라인은 시작부터 압축까지 전체 세션을 재생합니다: 사용자가 입력하기 전에 무엇이 로드되고, 각 파일 읽기, 규칙, 훅이 Claude가 작업할 때 무엇을 추가하는지, 그리고 서브에이전트가 어떻게 대용량 읽기를 컨텍스트 밖으로 유지하는지 보여줍니다. 동일한 콘텐츠를 목록으로 보려면 [작성된 분석](#what-the-timeline-shows)을 참조하세요.

1572 

1573<ContextWindow />

1574 

1575<h2 id="what-the-timeline-shows">

1576 타임라인이 보여주는 것

1577</h2>

12 1578 

13세션은 대표적인 토큰 수를 포함한 현실적인 흐름을 따릅니다:1579세션은 대표적인 토큰 수를 포함한 현실적인 흐름을 따릅니다:

14 1580 


17* **후속 프롬프트**: [서브에이전트](/ko/sub-agents)가 자신의 별도 컨텍스트 윈도우에서 연구를 처리하므로 대용량 파일 읽기가 사용자의 윈도우에서 벗어납니다. 요약과 작은 메타데이터 트레일러만 돌아옵니다.1583* **후속 프롬프트**: [서브에이전트](/ko/sub-agents)가 자신의 별도 컨텍스트 윈도우에서 연구를 처리하므로 대용량 파일 읽기가 사용자의 윈도우에서 벗어납니다. 요약과 작은 메타데이터 트레일러만 돌아옵니다.

18* **끝에서**: `/compact`가 대화를 구조화된 요약으로 바꿉니다. 대부분의 시작 콘텐츠는 자동으로 다시 로드됩니다. 아래 표는 각 메커니즘에 어떤 일이 발생하는지 보여줍니다.1584* **끝에서**: `/compact`가 대화를 구조화된 요약으로 바꿉니다. 대부분의 시작 콘텐츠는 자동으로 다시 로드됩니다. 아래 표는 각 메커니즘에 어떤 일이 발생하는지 보여줍니다.

19 1585 

20## 압축 후 유지되는 1586<h2 id="what-survives-compaction">

1587 압축 후 유지되는 것

1588</h2>

21 1589 

22긴 세션이 압축될 때, Claude Code는 대화 기록을 요약하여 컨텍스트 윈도우에 맞춥니다. 사용자의 지시사항에 어떤 일이 발생하는지는 로드된 방식에 따라 달라집니다:1590긴 세션이 압축될 때, Claude Code는 대화 기록을 요약하여 컨텍스트 윈도우에 맞춥니다. 사용자의 지시사항에 어떤 일이 발생하는지는 로드된 방식에 따라 달라집니다:

23 1591 


35 1603 

36스킬 본문은 압축 후 다시 주입되지만 큰 스킬은 스킬당 제한에 맞게 잘리고, 총 예산을 초과하면 가장 오래된 호출된 스킬이 삭제됩니다. 잘림은 파일의 시작을 유지하므로 `SKILL.md`의 맨 위에 가장 중요한 지시사항을 배치하세요.1604스킬 본문은 압축 후 다시 주입되지만 큰 스킬은 스킬당 제한에 맞게 잘리고, 총 예산을 초과하면 가장 오래된 호출된 스킬이 삭제됩니다. 잘림은 파일의 시작을 유지하므로 `SKILL.md`의 맨 위에 가장 중요한 지시사항을 배치하세요.

37 1605 

38## 자신의 세션 확인1606<h2 id="when-your-context-fills-up">

1607 컨텍스트가 가득 찰 때

1608</h2>

1609 

1610Claude Code는 제한에 접근할 때 자동으로 압축하므로 컨텍스트 윈도우가 가득 차도 세션이 끝나지 않습니다. 자동 패스는 타임라인의 `/compact` 단계와 동일한 방식으로 작동합니다. [컨텍스트가 가득 찰 때](/ko/how-claude-code-works#when-context-fills-up)에서 보존되는 항목을 참조하세요.

1611 

1612자동 패스가 실행되기 전에 조치를 취할 수도 있습니다:

1613 

1614* **포커스를 맞춰 압축**: 긴 새 작업을 시작하기 전에 `/compact focus on the auth bug fix`와 같은 지시사항과 함께 `/compact`를 실행하세요. 요약은 자동 패스가 추측하는 중요한 항목 대신 사용자가 선택한 항목을 유지합니다.

1615* **작업 간 지우기**: 관련 없는 작업으로 전환할 때 `/clear`를 실행하세요. 오래된 대화는 다음에 필요한 파일을 밀어내고 모든 메시지에서 토큰을 소비합니다.

1616* **대용량 읽기 위임**: 연구를 [서브에이전트](/ko/sub-agents)에 보내 파일 콘텐츠가 사용자의 컨텍스트 윈도우가 아닌 서브에이전트의 컨텍스트 윈도우에 유지되도록 하세요.

1617 

1618더 작은 대화보다 더 큰 윈도우가 필요한 경우 Fable 5, Opus 4.6 이상, Sonnet 4.6은 100만 토큰 컨텍스트 윈도우를 지원합니다. 플랜별 가용성 및 `[1m]` 모델 변형을 선택하는 방법은 [확장 컨텍스트](/ko/model-config#extended-context)를 참조하세요. 압축은 더 큰 제한에서도 동일한 방식으로 작동합니다.

1619 

1620<h2 id="check-your-own-session">

1621 자신의 세션 확인

1622</h2>

39 1623 

40시각화는 대표적인 숫자를 사용합니다. 언제든지 실제 컨텍스트 사용량을 보려면 `/context`를 실행하여 카테고리별 라이브 분석과 최적화 제안을 확인하세요. `/memory`를 실행하여 시작 시 로드된 CLAUDE.md 및 자동 메모리 파일을 확인하세요.1624시각화는 대표적인 숫자를 사용합니다. 언제든지 실제 컨텍스트 사용량을 보려면 `/context`를 실행하여 카테고리별 라이브 분석과 최적화 제안을 확인하세요. `/memory`를 실행하여 시작 시 로드된 CLAUDE.md 및 자동 메모리 파일을 확인하세요.

41 1625 

42## 관련 리소스1626<h2 id="related-resources">

1627 관련 리소스

1628</h2>

43 1629 

44타임라인에 표시된 기능에 대한 더 깊은 내용은 다음 페이지를 참조하세요:1630타임라인에 표시된 기능에 대한 더 깊은 내용은 다음 페이지를 참조하세요:

45 1631 

costs.md +3 −1

Details

35 35 

36Pro, Max, Team 또는 Enterprise 요금제에서 `/usage`는 요금제 한도에 포함되는 항목의 분석도 표시합니다. 최근 사용량을 skills, subagents, plugins 및 개별 MCP 서버에 귀속시키며, 각각은 전체의 백분율로 표시됩니다. `d` 또는 `w`를 눌러 지난 24시간과 지난 7일 사이를 전환할 수 있습니다. 수치는 근사치이며 이 기기의 로컬 세션 기록에서 계산되므로 다른 기기 또는 claude.ai의 사용량은 포함되지 않습니다.36Pro, Max, Team 또는 Enterprise 요금제에서 `/usage`는 요금제 한도에 포함되는 항목의 분석도 표시합니다. 최근 사용량을 skills, subagents, plugins 및 개별 MCP 서버에 귀속시키며, 각각은 전체의 백분율로 표시됩니다. `d` 또는 `w`를 눌러 지난 24시간과 지난 7일 사이를 전환할 수 있습니다. 수치는 근사치이며 이 기기의 로컬 세션 기록에서 계산되므로 다른 기기 또는 claude.ai의 사용량은 포함되지 않습니다.

37 37 

38[VS Code 확장](/ko/vs-code#check-account-and-usage)에서 동일한 분석이 Day 및 Week 토글이 있는 Account & usage 대화 상자에 나타납니다. Claude Code v2.1.174 이상이 필요합니다.

39 

38<h2 id="managing-costs-for-teams">40<h2 id="managing-costs-for-teams">

39 팀 비용 관리41 팀 비용 관리

40</h2>42</h2>


196 확장 사고 조정198 확장 사고 조정

197</h3>199</h3>

198 200 

199확장 사고는 기본적으로 활성화되어 있습니다. 복잡한 계획 및 추론 작업의 성능을 크게 향상시키기 때문입니다. 사고 토큰은 출력 토큰으로 청구되며, 기본 예산은 모델에 따라 수만 개의 토큰이 될 수 있습니다. 깊은 추론이 필요하지 않은 더 간단한 작업의 경우, `/effort`를 사용하거나 `/model`에서 [노력 수준](/ko/model-config#adjust-effort-level)을 낮추거나, `/config`에서 사고를 비활성화하거나, `MAX_THINKING_TOKENS=8000`으로 예산을 낮춤으로써 비용을 줄일 수 있습니다.201확장 사고는 기본적으로 활성화되어 있습니다. 복잡한 계획 및 추론 작업의 성능을 크게 향상시키기 때문입니다. 사고 토큰은 출력 토큰으로 청구되며, 기본 예산은 모델에 따라 수만 개의 토큰이 될 수 있습니다. 깊은 추론이 필요하지 않은 더 간단한 작업의 경우, `/effort`를 사용하거나 `/model`에서 [노력 수준](/ko/model-config#adjust-effort-level)을 낮추거나, `/config`에서 사고를 비활성화하거나, [고정 사고 예산](/ko/model-config#adaptive-reasoning-and-fixed-thinking-budgets)이 있는 모델에서 `MAX_THINKING_TOKENS=8000`으로 예산을 낮춤으로써 비용을 줄일 수 있습니다. 적응형 추론 모델은 0이 아닌 예산을 무시하므로 대신 노력 수준을 사용하십시오. Fable 5에서는 사고 비활성화를 사용할 수 없으며, 항상 확장 사고를 사용합니다.

200 202 

201<h3 id="delegate-verbose-operations-to-subagents">203<h3 id="delegate-verbose-operations-to-subagents">

202 자세한 작업을 subagents에 위임204 자세한 작업을 subagents에 위임

data-usage.md +3 −3

Details

62**상업용 사용자(Team, Enterprise, API)**:62**상업용 사용자(Team, Enterprise, API)**:

63 63 

64* 표준: 30일 보관 기간64* 표준: 30일 보관 기간

65* [Zero data retention](/ko/zero-data-retention): Claude for Enterprise의 Claude Code에서 사용 가능합니다. ZDR은 조직별로 활성화되며, 새로운 조직은 계정 팀에서 별도로 ZDR을 활성화해야 합니다.65* [Zero data retention](/ko/zero-data-retention): Claude for Enterprise의 Claude Code에서 사용 가능합니다. ZDR은 표준 Enterprise 플랜에 포함되지 않으며, 적격 여부를 확인한 계정 팀에서 조직별로 활성화됩니다.

66* 로컬 캐싱: Claude Code 클라이언트는 세션 재개를 활성화하기 위해 `~/.claude/projects/` 아래의 일반 텍스트로 세션 기록을 로컬에 저장합니다(기본값 30일). `cleanupPeriodDays`로 기간을 조정합니다. 저장되는 내용 및 삭제 방법은 [application data](/ko/claude-directory#application-data)를 참조하세요.66* 로컬 캐싱: Claude Code 클라이언트는 세션 재개를 활성화하기 위해 `~/.claude/projects/` 아래의 일반 텍스트로 세션 기록을 로컬에 저장합니다(기본값 30일). `cleanupPeriodDays`로 기간을 조정합니다. 저장되는 내용 및 삭제 방법은 [application data](/ko/claude-directory#application-data)를 참조하세요.

67 67 

68웹에서 개별 Claude Code 세션을 언제든지 삭제할 수 있습니다. 세션을 삭제하면 세션의 이벤트 데이터가 영구적으로 제거됩니다. 세션 삭제 방법에 대한 지침은 [Delete sessions](/ko/claude-code-on-the-web#delete-sessions)를 참조하세요.68웹에서 개별 Claude Code 세션을 언제든지 삭제할 수 있습니다. 세션을 삭제하면 세션의 이벤트 데이터가 영구적으로 제거됩니다. 세션 삭제 방법에 대한 지침은 [Delete sessions](/ko/claude-code-on-the-web#delete-sessions)를 참조하세요.


83 83 

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

85 85 

86<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/claude-code-data-flow.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=5b1131530bdfdd415700a0cb4d4070c4" alt="Claude Code의 외부 연결을 보여주는 다이어그램: 설치/업데이트는 배포 서버에 연결되고, 사용자 요청은 Console auth, public-api, 그리고 선택적으로 metrics, Sentry, 버그 보고를 포함한 Anthropic 서비스에 연결됩니다" width="720" height="520" data-path="images/claude-code-data-flow.svg" />86<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/claude-code-data-flow.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=5b1131530bdfdd415700a0cb4d4070c4" alt="Claude Code의 외부 연결을 보여주는 다이어그램: 설치/업데이트는 배포 서버에 연결되고, 사용자 요청은 Console auth, public-api, 그리고 선택적으로 metrics Sentry를 포함한 Anthropic 서비스에 연결됩니다. /feedback으로 전송된 피드백은 Google Cloud Storage로 이동하고 선택적으로 GitHub 이슈를 생성합니다" width="720" height="520" data-path="images/claude-code-data-flow.svg" />

87 87 

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

89 89 


119 119 

120Claude Code는 사용자의 머신에서 Sentry에 연결하여 운영 오류 로깅을 수행합니다. 데이터는 TLS를 사용하여 전송 중에 암호화되고 256비트 AES 암호화를 사용하여 저장 시에 암호화됩니다. [Sentry 보안 문서](https://sentry.io/security/)에서 자세히 알아보세요. 오류 로깅을 거부하려면 `DISABLE_ERROR_REPORTING` 환경 변수를 설정합니다.120Claude Code는 사용자의 머신에서 Sentry에 연결하여 운영 오류 로깅을 수행합니다. 데이터는 TLS를 사용하여 전송 중에 암호화되고 256비트 AES 암호화를 사용하여 저장 시에 암호화됩니다. [Sentry 보안 문서](https://sentry.io/security/)에서 자세히 알아보세요. 오류 로깅을 거부하려면 `DISABLE_ERROR_REPORTING` 환경 변수를 설정합니다.

121 121 

122`/feedback` 명령을 실행하면 코드를 포함한 대화 기록의 복사본이 Anthropic으로 전송됩니다. 제출하기 전에 포함할 기록의 양을 선택합니다. 기본값인 현재 세션만 포함하거나, 지난 24시간 또는 7일 동안 같은 프로젝트의 다른 세션도 포함할 수 있습니다. 데이터는 TLS를 통해 전송 중에 암호화됩니다. 선택적으로 공개 저장소에 GitHub 이슈가 생성됩니다. 거부하려면 `DISABLE_FEEDBACK_COMMAND` 환경 변수를 `1`로 설정합니다.122`/feedback` 명령을 실행하면 코드를 포함한 대화 기록의 복사본이 Anthropic으로 전송됩니다. 제출하기 전에 포함할 기록의 양을 선택합니다. 기본값인 현재 세션만 포함하거나, 지난 24시간 또는 7일 동안 같은 프로젝트의 다른 세션도 포함할 수 있습니다. 데이터는 TLS를 통해 전송 중에 암호화되고 Google Cloud Storage에 저장되며, Google Cloud Storage는 기본적으로 저장된 데이터를 암호화합니다. 선택적으로 공개 저장소에 GitHub 이슈가 생성됩니다. 거부하려면 `DISABLE_FEEDBACK_COMMAND` 환경 변수를 `1`로 설정합니다.

123 123 

124Bedrock 또는 Vertex와 같은 타사 제공자를 사용하거나 Anthropic 자격 증명이 구성되지 않은 경우, `/feedback`은 보고서를 Anthropic으로 전송하는 대신 `~/.claude/feedback-bundles/` 아래의 로컬 아카이브에 작성합니다. 알려진 API 키 및 토큰 패턴은 아카이브가 작성되기 전에 제거됩니다. 파일을 Anthropic 계정 담당자에게 보내거나 지원 요청에 첨부할 때까지 머신을 벗어나지 않습니다.124Bedrock 또는 Vertex와 같은 타사 제공자를 사용하거나 Anthropic 자격 증명이 구성되지 않은 경우, `/feedback`은 보고서를 Anthropic으로 전송하는 대신 `~/.claude/feedback-bundles/` 아래의 로컬 아카이브에 작성합니다. 알려진 API 키 및 토큰 패턴은 아카이브가 작성되기 전에 제거됩니다. 파일을 Anthropic 계정 담당자에게 보내거나 지원 요청에 첨부할 때까지 머신을 벗어나지 않습니다.

125 125 

Details

78 깨끗한 구성에 대해 테스트78 깨끗한 구성에 대해 테스트

79</h2>79</h2>

80 80 

81대상 확인이 원인을 격리하지 못하거나 구성이 없는 상태에 있으면, 일반적인 설정에서 아무것도 로드하지 않는 세션과 비교합니다. [`CLAUDE_CONFIG_DIR`](/ko/env-vars)을 디렉토리로 지정하여 `~/.claude` 아래의 모든 항목을 우회하고, 프로젝트 구성도 건너뛰도록 `.claude` 폴더, `.mcp.json` 또는 `CLAUDE.md`가 없는 디렉토리에서 시작합니다.81{/* min-version: 2.1.169 */}[`claude --safe-mode`](/ko/cli-reference#cli-flags)로 시작합니다. 이는 `CLAUDE.md`, 스킬, 플러그인, , MCP 서버, 사용자 정의 명령 에이전트를 포함한 모든 사용자 정의가 비활성화된 세션을 시작합니다. 인증, 모델 선택, 기본 제공 도구 및 권한은 정상적으로 작동합니다. 안전 모드에서 문제가 사라지면, 이러한 표면 중 하나가 원인입니다. 위의 대상 확인을 사용하여 어느 것인지 찾습니다. 조직에서 배포한 관리 설정은 여전히 부분적으로 적용되므로, 정책 구성 훅 및 상태 줄은 안전 모드에서도 실행됩니다.

82 

83안전 모드에서 문제가 지속되거나 설정 자체가 의심스러우면, 일반적인 설정에서 아무것도 로드하지 않는 세션과 비교합니다. [`CLAUDE_CONFIG_DIR`](/ko/env-vars)을 빈 디렉토리로 지정하여 `~/.claude` 아래의 모든 항목을 우회하고, 프로젝트 구성도 건너뛰도록 `.claude` 폴더, `.mcp.json` 또는 `CLAUDE.md`가 없는 디렉토리에서 시작합니다.

82 84 

83```bash theme={null}85```bash theme={null}

84cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude86cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

desktop.md +27 −25

Details

67 67 

68프롬프트 상자는 외부 컨텍스트를 가져오는 두 가지 방법을 지원합니다:68프롬프트 상자는 외부 컨텍스트를 가져오는 두 가지 방법을 지원합니다:

69 69 

70* **@mention 파일**: `@` 다음에 파일 이름을 입력하여 파일을 대화 컨텍스트에 추가합니다. Claude는 그 파일을 읽고 참조할 수 있습니다. @mention은 원격 세션에서 사용할 수 없습니다.70* **@mention 파일**: `@` 다음에 파일 이름을 입력하여 파일을 대화 컨텍스트에 추가합니다. Claude는 그 파일을 읽고 참조할 수 있습니다. @mention은 클라우드 세션에서 사용할 수 없습니다.

71* **파일 첨부**: 첨부 버튼을 사용하여 이미지, PDF 및 기타 파일을 프롬프트에 첨부하거나, 파일을 프롬프트에 직접 드래그 앤 드롭합니다. 이는 버그 스크린샷, 디자인 목업 또는 참고 문서를 공유하는 데 유용합니다.71* **파일 첨부**: 첨부 버튼을 사용하여 이미지, PDF 및 기타 파일을 프롬프트에 첨부하거나, 파일을 프롬프트에 직접 드래그 앤 드롭합니다. 이는 버그 스크린샷, 디자인 목업 또는 참고 문서를 공유하는 데 유용합니다.

72 72 

73<h3 id="choose-a-permission-mode">73<h3 id="choose-a-permission-mode">


77권한 모드는 세션 중에 Claude가 가질 자율성을 제어합니다: 파일 편집, 명령 실행 또는 둘 다 전에 묻는지 여부입니다. 전송 버튼 옆의 모드 선택기를 사용하여 언제든지 모드를 전환할 수 있습니다. Claude가 수행하는 작업을 정확히 보기 위해 권한 요청으로 시작한 다음, 편하면 자동 수락 편집 또는 Plan mode로 이동합니다.77권한 모드는 세션 중에 Claude가 가질 자율성을 제어합니다: 파일 편집, 명령 실행 또는 둘 다 전에 묻는지 여부입니다. 전송 버튼 옆의 모드 선택기를 사용하여 언제든지 모드를 전환할 수 있습니다. Claude가 수행하는 작업을 정확히 보기 위해 권한 요청으로 시작한 다음, 편하면 자동 수락 편집 또는 Plan mode로 이동합니다.

78 78 

79| 모드 | 설정 키 | 동작 |79| 모드 | 설정 키 | 동작 |

80| ------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |80| ------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

81| **권한 요청** | `default` | Claude는 파일을 편집하거나 명령을 실행하기 전에 요청합니다. diff를 보고 각 변경 사항을 수락하거나 거부할 수 있습니다. 새 사용자에게 권장됩니다. |81| **권한 요청** | `default` | Claude는 파일을 편집하거나 명령을 실행하기 전에 요청합니다. diff를 보고 각 변경 사항을 수락하거나 거부할 수 있습니다. 새 사용자에게 권장됩니다. |

82| **자동 수락 편집** | `acceptEdits` | Claude는 파일 편집을 자동으로 수락하고 `mkdir`, `touch`, `mv`와 같은 일반적인 파일시스템 명령을 자동으로 수락하지만 다른 터미널 명령 실행 전에는 여전히 요청합니다. 파일 변경을 신뢰하고 더 빠른 반복을 원할 때 사용합니다. |82| **자동 수락 편집** | `acceptEdits` | Claude는 파일 편집을 자동으로 수락하고 `mkdir`, `touch`, `mv`와 같은 일반적인 파일시스템 명령을 자동으로 수락하지만 다른 터미널 명령 실행 전에는 여전히 요청합니다. 파일 변경을 신뢰하고 더 빠른 반복을 원할 때 사용합니다. |

83| **Plan mode** | `plan` | Claude는 파일을 읽고 명령을 실행하여 탐색한 다음 소스 코드를 편집하지 않고 계획을 제안합니다. 먼저 접근 방식을 검토하려는 복잡한 작업에 좋습니다. |83| **Plan mode** | `plan` | Claude는 파일을 읽고 명령을 실행하여 탐색한 다음 소스 코드를 편집하지 않고 계획을 제안합니다. 먼저 접근 방식을 검토하려는 복잡한 작업에 좋습니다. |

84| **Auto** | `auto` | Claude는 요청과의 정렬을 확인하는 백그라운드 안전 검사를 통해 모든 작업을 실행합니다. 감시를 유지하면서 권한 프롬프트를 줄입니다. Settings → Claude Code에서 활성화합니다. [가용성 요구 사항](#auto-mode-availability)을 아래에서 참조하세요. |84| **Auto** | `auto` | Claude는 요청과의 정렬을 확인하는 백그라운드 안전 검사를 통해 모든 작업을 실행합니다. 감시를 유지하면서 권한 프롬프트를 줄입니다. Settings → Claude Code에서 활성화합니다. [가용성 요구 사항](#auto-mode-availability)을 아래에서 참조하세요. |

85| **권한 무시** | `bypassPermissions` | Claude는 권한 프롬프트 없이 실행되며, CLI의 `--dangerously-skip-permissions`와 동일합니다. Settings → Claude Code의 "권한 무시 모드 허용"에서 활성화합니다. 샌드박스 컨테이너 또는 VM에서만 사용합니다. 엔터프라이즈 관리자는 이 옵션을 비활성화할 수 있습니다. |85| **권한 무시** | `bypassPermissions` | Claude는 명시적 [ask rules](/ko/permissions#manage-permissions)에 의해 강제된 권한 프롬프트를 제외하고 권한 프롬프트 없이 실행되며, CLI의 `--dangerously-skip-permissions`와 동일합니다. Settings → Claude Code의 "권한 무시 모드 허용"에서 활성화합니다. 샌드박스 컨테이너 또는 VM에서만 사용합니다. 엔터프라이즈 관리자는 이 옵션을 비활성화할 수 있습니다. |

86 86 

87`dontAsk` 권한 모드는 [CLI](/ko/permission-modes#allow-only-pre-approved-tools-with-dontask-mode)에서만 사용 가능합니다.87`dontAsk` 권한 모드는 [CLI](/ko/permission-modes#allow-only-pre-approved-tools-with-dontask-mode)에서만 사용 가능합니다.

88 88 

89<span id="auto-mode-availability" />89<span id="auto-mode-availability" />

90 90 

91Auto mode는 Anthropic API의 모든 사용자에게 제공되는 연구 미리보기이며 Claude Opus 4.6 이상 또는 Sonnet 4.6이 필요합니다. Google Cloud Vertex AI로 라우팅하는 엔터프라이즈 배포에서는 [set `CLAUDE_CODE_ENABLE_AUTO_MODE`](/ko/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry)할 때까지 auto mode가 꺼져 있으며, 거기서는 Claude Opus 4.7과 Opus 4.8만 지원됩니다.91Auto mode는 Anthropic API의 모든 사용자에게 제공되는 연구 미리보기이며 Claude Opus 4.6 이상 또는 Sonnet 4.6이 필요합니다. Google Cloud Vertex AI로 라우팅하는 엔터프라이즈 배포에서는 [`CLAUDE_CODE_ENABLE_AUTO_MODE`를 설정](/ko/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry)할 때까지 auto mode가 꺼져 있으며, 거기서는 Claude Opus 4.7과 Opus 4.8만 지원됩니다.

92 92 

93<Tip title="모범 사례">93<Tip title="모범 사례">

94 복잡한 작업을 Plan mode에서 시작하여 Claude가 변경하기 전에 접근 방식을 매핑하도록 합니다. 계획을 승인한 후 자동 수락 편집 또는 권한 요청으로 전환하여 실행합니다. 이 워크플로우에 대한 자세한 내용은 [먼저 탐색, 그 다음 계획, 그 다음 코드](/ko/best-practices#explore-first-then-plan-then-code)를 참조하세요.94 복잡한 작업을 Plan mode에서 시작하여 Claude가 변경하기 전에 접근 방식을 매핑하도록 합니다. 계획을 승인한 후 자동 수락 편집 또는 권한 요청으로 전환하여 실행합니다. 이 워크플로우에 대한 자세한 내용은 [먼저 탐색, 그 다음 계획, 그 다음 코드](/ko/best-practices#explore-first-then-plan-then-code)를 참조하세요.

95</Tip>95</Tip>

96 96 

97원격 세션은 자동 수락 편집 Plan mode를 지원합니다. 권한 요청은 원격 세션이 기본적으로 파일 편집을 자동으로 수락하기 때문에 사용할 없으며, 권한 무시는 원격 환경이 이미 샌드박스되어 있기 때문에 사용할 수 없습니다.97클라우드 세션은 자동 수락 편집, Plan mode, Auto mode를 지원합니다. 자동 수락 편집은 `default` 모드에 해당합니다: 클라우드 세션은 파일 편집을 미리 승인하므로 선택기는 권한 요청 대신 자동 수락 편집을 표시합니다. 권한 무시는 클라우드 환경이 이미 샌드박스되어 있기 때문에 사용할 수 없습니다.

98 98 

99엔터프라이즈 관리자는 사용 가능한 권한 모드를 제한할 수 있습니다. 자세한 내용은 [엔터프라이즈 구성](#enterprise-configuration)을 참조하세요.99엔터프라이즈 관리자는 사용 가능한 권한 모드를 제한할 수 있습니다. 자세한 내용은 [엔터프라이즈 구성](#enterprise-configuration)을 참조하세요.

100 100 


403 외부 도구 연결하기403 외부 도구 연결하기

404</h3>404</h3>

405 405 

406로컬 및 [SSH](#ssh-sessions) 세션의 경우 프롬프트 상자 옆의 **+** 버튼을 클릭하고 **Connectors**를 선택하여 Google Calendar, Slack, GitHub, Linear, Notion 등과 같은 통합을 추가합니다. 세션 전이나 중에 커넥터를 추가할 수 있습니다. **+** 버튼은 원격 세션에서 사용할 수 없지만 [루틴](/ko/routines)은 루틴 생성 시 커넥터를 구성합니다.406로컬 및 [SSH](#ssh-sessions) 세션의 경우 프롬프트 상자 옆의 **+** 버튼을 클릭하고 **Connectors**를 선택하여 Google Calendar, Slack, GitHub, Linear, Notion 등과 같은 통합을 추가합니다. 세션 전이나 중에 커넥터를 추가할 수 있습니다. **+** 버튼은 클라우드 세션에서 사용할 수 없지만 [루틴](/ko/routines)은 루틴 생성 시 커넥터를 구성합니다.

407 407 

408커넥터를 관리하거나 연결을 해제하려면 데스크톱 앱의 Settings → Connectors로 이동하거나 프롬프트 상자의 Connectors 메뉴에서 **Manage connectors**를 선택합니다.408커넥터를 관리하거나 연결을 해제하려면 데스크톱 앱의 Settings → Connectors로 이동하거나 프롬프트 상자의 Connectors 메뉴에서 **Manage connectors**를 선택합니다.

409 409 


425 425 

426로컬 및 [SSH](#ssh-sessions) 세션의 경우 프롬프트 상자 옆의 **+** 버튼을 클릭하고 **Plugins**를 선택하여 설치된 플러그인과 해당 skills를 봅니다. 플러그인을 추가하려면 서브메뉴에서 **Add plugin**을 선택하여 플러그인 브라우저를 열면 공식 Anthropic marketplace를 포함한 구성된 [marketplaces](/ko/plugin-marketplaces)의 사용 가능한 플러그인이 표시됩니다. **Manage plugins**를 선택하여 플러그인을 활성화, 비활성화 또는 제거합니다.426로컬 및 [SSH](#ssh-sessions) 세션의 경우 프롬프트 상자 옆의 **+** 버튼을 클릭하고 **Plugins**를 선택하여 설치된 플러그인과 해당 skills를 봅니다. 플러그인을 추가하려면 서브메뉴에서 **Add plugin**을 선택하여 플러그인 브라우저를 열면 공식 Anthropic marketplace를 포함한 구성된 [marketplaces](/ko/plugin-marketplaces)의 사용 가능한 플러그인이 표시됩니다. **Manage plugins**를 선택하여 플러그인을 활성화, 비활성화 또는 제거합니다.

427 427 

428플러그인은 사용자 계정, 특정 프로젝트 또는 로컬 전용으로 범위를 지정할 수 있습니다. 조직이 플러그인을 중앙에서 관리하는 경우 해당 플러그인은 CLI에서와 동일한 방식으로 데스크톱 세션에서 사용 가능합니다. 플러그인은 원격 세션에는 사용할 수 없습니다. 자신의 플러그인을 만드는 것을 포함한 전체 플러그인 참조는 [plugins](/ko/plugins)를 참조하세요.428플러그인은 사용자 계정, 특정 프로젝트 또는 로컬 전용으로 범위를 지정할 수 있습니다. 조직이 플러그인을 중앙에서 관리하는 경우 해당 플러그인은 CLI에서와 동일한 방식으로 데스크톱 세션에서 사용 가능합니다. 플러그인은 클라우드 세션에는 사용할 수 없습니다. 자신의 플러그인을 만드는 것을 포함한 전체 플러그인 참조는 [plugins](/ko/plugins)를 참조하세요.

429 429 

430<h3 id="configure-preview-servers">430<h3 id="configure-preview-servers">

431 미리보기 서버 구성하기431 미리보기 서버 구성하기


487| `program` | string | `node`로 실행할 스크립트. [언제 `program` vs `runtimeExecutable`을 사용할지](#when-to-use-program-vs-runtimeexecutable) 참조 |487| `program` | string | `node`로 실행할 스크립트. [언제 `program` vs `runtimeExecutable`을 사용할지](#when-to-use-program-vs-runtimeexecutable) 참조 |

488| `args` | string\[] | `program`에 전달되는 인수. `program`이 설정된 경우에만 사용됨 |488| `args` | string\[] | `program`에 전달되는 인수. `program`이 설정된 경우에만 사용됨 |

489 489 

490<a id="when-to-use-program-vs-runtimeexecutable" />

491 

490<h5 id="when-to-use-program-vs-runtimeexecutable">492<h5 id="when-to-use-program-vs-runtimeexecutable">

491 `program` vs `runtimeExecutable` 사용 시기493 `program` vs `runtimeExecutable` 사용 시기

492</h5>494</h5>


600 602 

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

602 604 

603<h3 id="remote-sessions">605<h3 id="cloud-sessions">

604 원격 세션606 클라우드 세션

605</h3>607</h3>

606 608 

607원격 세션은 앱을 닫아도 백그라운드에서 계속됩니다. 사용량은 별도의 컴퓨팅 요금 없이 [구독 계획 한도](/ko/costs)에 포함됩니다.609클라우드 세션은 앱을 닫아도 백그라운드에서 계속됩니다. 사용량은 별도의 컴퓨팅 요금 없이 [구독 계획 한도](/ko/costs)에 포함됩니다.

608 610 

609다양한 네트워크 액세스 수준 및 환경 변수를 가진 사용자 정의 클라우드 환경을 만들 수 있습니다. 원격 세션을 시작할 때 환경 드롭다운을 선택하고 **환경 추가**를 선택합니다. 네트워크 액세스 및 환경 변수 구성에 대한 자세한 내용은 [클라우드 환경](/ko/claude-code-on-the-web#the-cloud-environment)을 참조하세요.611다양한 네트워크 액세스 수준 및 환경 변수를 가진 사용자 정의 클라우드 환경을 만들 수 있습니다. 클라우드 세션을 시작할 때 환경 드롭다운을 선택하고 **환경 추가**를 선택합니다. 네트워크 액세스 및 환경 변수 구성에 대한 자세한 내용은 [클라우드 환경](/ko/claude-code-on-the-web#the-cloud-environment)을 참조하세요.

610 612 

611<h3 id="ssh-sessions">613<h3 id="ssh-sessions">

612 SSH 세션614 SSH 세션


710 712 

711IT 팀은 macOS의 MDM 또는 Windows의 그룹 정책을 통해 데스크톱 앱을 관리할 수 있습니다. 사용 가능한 정책에는 Claude Code 기능 활성화 또는 비활성화, 자동 업데이트 제어, 사용자 정의 배포 URL 설정이 포함됩니다.713IT 팀은 macOS의 MDM 또는 Windows의 그룹 정책을 통해 데스크톱 앱을 관리할 수 있습니다. 사용 가능한 정책에는 Claude Code 기능 활성화 또는 비활성화, 자동 업데이트 제어, 사용자 정의 배포 URL 설정이 포함됩니다.

712 714 

713* **macOS**: Jamf 또는 Kandji와 같은 도구를 사용하여 `com.anthropic.Claude` 기본 설정 도메인을 통해 구성합니다715* **macOS**: Jamf 또는 Kandji와 같은 도구를 사용하여 `com.anthropic.claudefordesktop` 기본 설정 도메인을 통해 구성합니다

714* **Windows**: `SOFTWARE\Policies\Claude`의 레지스트리를 통해 구성합니다716* **Windows**: `SOFTWARE\Policies\Claude`의 레지스트리를 통해 구성합니다

715 717 

716<h3 id="authentication-and-sso">718<h3 id="authentication-and-sso">


723 데이터 처리725 데이터 처리

724</h3>726</h3>

725 727 

726Claude Code는 로컬 세션에서 코드를 로컬로 처리하거나 원격 세션에서 Anthropic의 클라우드 인프라에서 처리합니다. 대화 및 코드 컨텍스트는 처리를 위해 Anthropic의 API로 전송됩니다. 데이터 보존, 개인 정보 보호, 규정 준수에 대한 자세한 내용은 [데이터 처리](/ko/data-usage)를 참조하세요.728Claude Code는 로컬 세션에서 코드를 로컬로 처리하거나 클라우드 세션에서 Anthropic의 클라우드 인프라에서 처리합니다. 대화 및 코드 컨텍스트는 처리를 위해 Anthropic의 API로 전송됩니다. 데이터 보존, 개인 정보 보호, 규정 준수에 대한 자세한 내용은 [데이터 처리](/ko/data-usage)를 참조하세요.

727 729 

728<h3 id="deployment">730<h3 id="deployment">

729 배포731 배포


762| `--resume`, `--continue` | 사이드바의 세션을 클릭합니다 |764| `--resume`, `--continue` | 사이드바의 세션을 클릭합니다 |

763| `--permission-mode` | 전송 버튼 옆의 모드 선택기 |765| `--permission-mode` | 전송 버튼 옆의 모드 선택기 |

764| `--dangerously-skip-permissions` | 권한 무시 모드. Settings → Claude Code → "권한 무시 모드 허용"에서 활성화합니다. 엔터프라이즈 관리자는 이 설정을 비활성화할 수 있습니다. |766| `--dangerously-skip-permissions` | 권한 무시 모드. Settings → Claude Code → "권한 무시 모드 허용"에서 활성화합니다. 엔터프라이즈 관리자는 이 설정을 비활성화할 수 있습니다. |

765| `--add-dir` | 원격 세션에서 **+** 버튼으로 여러 저장소 추가 |767| `--add-dir` | 클라우드 세션에서 **+** 버튼으로 여러 저장소 추가 |

766| `--allowedTools`, `--disallowedTools` | 세션별 동등물이 없습니다. [설정 파일](/ko/settings)의 권한 규칙이 여전히 적용됩니다. |768| `--allowedTools`, `--disallowedTools` | 세션별 동등물이 없습니다. [설정 파일](/ko/settings)의 권한 규칙이 여전히 적용됩니다. |

767| `--verbose` | [Verbose 보기 모드](#switch-view-modes) (Transcript 보기 드롭다운) |769| `--verbose` | [Verbose 보기 모드](#switch-view-modes) (Transcript 보기 드롭다운) |

768| `--print`, `--output-format` | 사용할 수 없습니다. Desktop은 대화형만 가능합니다. |770| `--print`, `--output-format` | 사용할 수 없습니다. Desktop은 대화형만 가능합니다. |


779* **[MCP servers](/ko/mcp)** `~/.claude.json` 또는 `.mcp.json`에 구성된 것은 둘 다에서 작동합니다781* **[MCP servers](/ko/mcp)** `~/.claude.json` 또는 `.mcp.json`에 구성된 것은 둘 다에서 작동합니다

780* **[Hooks](/ko/hooks)** 및 **[skills](/ko/skills)** 설정에 정의된 것은 둘 다에 적용됩니다782* **[Hooks](/ko/hooks)** 및 **[skills](/ko/skills)** 설정에 정의된 것은 둘 다에 적용됩니다

781* **[Settings](/ko/settings)** `~/.claude.json` 및 `~/.claude/settings.json`에서 공유됩니다. `settings.json`의 권한 규칙, 허용된 도구 및 기타 설정은 Desktop 세션에 적용됩니다.783* **[Settings](/ko/settings)** `~/.claude.json` 및 `~/.claude/settings.json`에서 공유됩니다. `settings.json`의 권한 규칙, 허용된 도구 및 기타 설정은 Desktop 세션에 적용됩니다.

782* **Models**: Sonnet, Opus, Haiku는 둘 다에서 사용 가능합니다. Desktop에서 전송 버튼 옆의 드롭다운에서 모델을 선택합니다. 세션 중에 동일한 드롭다운에서 모델을 변경할 수 있습니다.784* **Models**: 동일한 [모델](/ko/model-config#available-models)은 둘 다에서 사용 가능합니다. Desktop에서 전송 버튼 옆의 드롭다운에서 모델을 선택합니다. 세션 중에 동일한 드롭다운에서 모델을 변경할 수 있습니다.

783 785 

784<Note>786<Note>

785 **Claude Desktop 채팅 앱의 MCP 서버**: Desktop 앱은 `claude_desktop_config.json`에서 MCP 서버를 Code 탭 세션으로 로드하며, `~/.claude.json` 및 `.mcp.json`의 서버와 함께 작동합니다. `claude_desktop_config.json`에 정의된 서버는 Desktop 채팅 표면과 Code 탭 모두에서 사용 가능합니다.787 **Claude Desktop 채팅 앱의 MCP 서버**: Desktop 앱은 `claude_desktop_config.json`에서 MCP 서버를 Code 탭 세션으로 로드하며, `~/.claude.json` 및 `.mcp.json`의 서버와 함께 작동합니다. `claude_desktop_config.json`에 정의된 서버는 Desktop 채팅 표면과 Code 탭 모두에서 사용 가능합니다.


794이 표는 CLI와 Desktop 간의 핵심 기능을 비교합니다. CLI 플래그의 전체 목록은 [CLI 참조](/ko/cli-reference)를 참조하세요.796이 표는 CLI와 Desktop 간의 핵심 기능을 비교합니다. CLI 플래그의 전체 목록은 [CLI 참조](/ko/cli-reference)를 참조하세요.

795 797 

796| 기능 | CLI | Desktop |798| 기능 | CLI | Desktop |

797| ----------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |799| ----------------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

798| 권한 모드 | `dontAsk`를 포함한 모든 모드 | 권한 요청, 자동 수락 편집, Plan mode, Auto, Settings를 통한 권한 무시 |800| 권한 모드 | `dontAsk`를 포함한 모든 모드 | 권한 요청, 자동 수락 편집, Plan mode, Auto, Settings를 통한 권한 무시 |

799| `--dangerously-skip-permissions` | CLI 플래그 | 권한 무시 모드. Settings → Claude Code → "권한 무시 모드 허용"에서 활성화합니다 |801| `--dangerously-skip-permissions` | CLI 플래그 | 권한 무시 모드. Settings → Claude Code → "권한 무시 모드 허용"에서 활성화합니다 |

800| [Third-party providers](/ko/third-party-integrations) | Bedrock, Vertex, Foundry | Anthropic의 API (기본값). 엔터프라이즈 배포는 Vertex AI 및 게이트웨이 공급자를 구성할 수 있습니다. [엔터프라이즈 구성 가이드](https://support.claude.com/en/articles/12622667-enterprise-configuration)를 참조하세요. |802| [Third-party providers](/ko/third-party-integrations) | Bedrock, Vertex AI, Foundry | Anthropic의 API (기본값). 엔터프라이즈 배포는 Vertex AI 및 게이트웨이 공급자를 구성할 수 있습니다. [엔터프라이즈 구성 가이드](https://support.claude.com/en/articles/12622667-enterprise-configuration)를 참조하세요. Code 탭을 Bedrock, Vertex AI, Foundry 또는 자체 호스팅 LLM 게이트웨이에서 실행하려면 [Cowork on 3P 연구 미리보기](https://claude.com/docs/cowork/3p/overview)를 참조하세요. |

801| [MCP servers](/ko/mcp) | 설정 파일에 구성 | 로컬 및 SSH 세션의 Connectors UI 또는 설정 파일 |803| [MCP servers](/ko/mcp) | 설정 파일에 구성 | 로컬 및 SSH 세션의 Connectors UI 또는 설정 파일 |

802| [Plugins](/ko/plugins) | `/plugin` 명령 | 플러그인 관리자 UI |804| [Plugins](/ko/plugins) | `/plugin` 명령 | 플러그인 관리자 UI |

803| @mention 파일 | 텍스트 기반 | 자동 완성 포함; 로컬 및 SSH 세션만 |805| @mention 파일 | 텍스트 기반 | 자동 완성 포함; 로컬 및 SSH 세션만 |


809| Dispatch 통합 | 사용할 수 없음 | [사이드바의 Dispatch 세션](#sessions-from-dispatch) |811| Dispatch 통합 | 사용할 수 없음 | [사이드바의 Dispatch 세션](#sessions-from-dispatch) |

810| 스크립팅 및 자동화 | [`--print`](/ko/cli-reference), [Agent SDK](/ko/headless) | 사용할 수 없음 |812| 스크립팅 및 자동화 | [`--print`](/ko/cli-reference), [Agent SDK](/ko/headless) | 사용할 수 없음 |

811 813 

812<h3 id="what-s-not-available-in-desktop">814<h3 id="whats-not-available-in-desktop">

813 Desktop에서 사용할 수 없는 것815 Desktop에서 사용할 수 없는 것

814</h3>816</h3>

815 817 

816다음 기능은 CLI 또는 VS Code 확장에서만 사용 가능합니다:818다음 기능은 CLI 또는 VS Code 확장에서만 사용 가능하며, 명시된 경우를 제외하고는 그렇습니다:

817 819 

818* **Third-party providers**: Desktop은 Anthropic의 API에 기본적으로 연결됩니다. 엔터프라이즈 배포는 [관리 설정](https://support.claude.com/en/articles/12622667-enterprise-configuration)을 통해 Vertex AI 및 게이트웨이 공급자를 구성할 수 있습니다. Bedrock 또는 Foundry의 경우 [CLI](/ko/quickstart) 사용합니다.820* **Third-party providers**: Desktop은 Anthropic의 API에 기본적으로 연결됩니다. 엔터프라이즈 배포는 [관리 설정](https://support.claude.com/en/articles/12622667-enterprise-configuration)을 통해 Vertex AI 및 게이트웨이 공급자를 구성할 수 있습니다. CLI에서 Bedrock 또는 Foundry의 경우 [빠른 시작](/ko/quickstart) 참조하세요. 위 섹션의 예외로, [Cowork on 3P 연구 미리보기](https://claude.com/docs/cowork/3p/overview)는 Code 탭을 Bedrock, Vertex AI, Foundry 또는 자체 호스팅 LLM 게이트웨이에서 실행합니다.

819* **Linux**: 데스크톱 앱은 macOS 및 Windows에서만 사용 가능합니다. Linux에서는 [CLI](/ko/quickstart)를 사용합니다.821* **Linux**: 데스크톱 앱은 macOS 및 Windows에서만 사용 가능합니다. Linux에서는 [CLI](/ko/quickstart)를 사용합니다.

820* **Inline code suggestions**: Desktop은 자동 완성 스타일 제안을 제공하지 않습니다. 대화형 프롬프트 및 명시적 코드 변경을 통해 작동합니다.822* **Inline code suggestions**: Desktop은 자동 완성 스타일 제안을 제공하지 않습니다. 대화형 프롬프트 및 명시적 코드 변경을 통해 작동합니다.

821* **Agent teams**: 서로 메시지를 주고받는 병렬 Claude Code 세션은 [CLI](/ko/agent-teams)에서 사용 가능하며 Desktop에서는 사용할 수 없습니다. 한 세션 내에서 다중 에이전트 작업의 경우 [동적 워크플로우](/ko/workflows)를 사용합니다. 이는 Desktop에서 실행됩니다.823* **Agent teams**: 서로 메시지를 주고받는 병렬 Claude Code 세션은 [CLI](/ko/agent-teams)에서 사용 가능하며 Desktop에서는 사용할 수 없습니다. 한 세션 내에서 다중 에이전트 작업의 경우 [동적 워크플로우](/ko/workflows)를 사용합니다. 이는 Desktop에서 실행됩니다.


885 887 

886MCP 서버 토글이 응답하지 않거나 Windows에서 서버가 연결되지 않으면 서버가 설정에 올바르게 구성되었는지 확인하고, 앱을 다시 시작하고, Task Manager에서 서버 프로세스가 실행 중인지 확인하고, 연결 오류에 대한 서버 로그를 검토합니다.888MCP 서버 토글이 응답하지 않거나 Windows에서 서버가 연결되지 않으면 서버가 설정에 올바르게 구성되었는지 확인하고, 앱을 다시 시작하고, Task Manager에서 서버 프로세스가 실행 중인지 확인하고, 연결 오류에 대한 서버 로그를 검토합니다.

887 889 

888<h3 id="app-won-t-quit">890<h3 id="app-wont-quit">

889 앱이 종료되지 않음891 앱이 종료되지 않음

890</h3>892</h3>

891 893 


899* **설치 후 PATH가 업데이트되지 않음**: 새 터미널 창을 엽니다. PATH 업데이트는 새 터미널 세션에만 적용됩니다.901* **설치 후 PATH가 업데이트되지 않음**: 새 터미널 창을 엽니다. PATH 업데이트는 새 터미널 세션에만 적용됩니다.

900* **동시 설치 오류**: 진행 중인 다른 설치에 대한 오류가 표시되지만 없으면 관리자로 설치 프로그램을 실행해 보세요.902* **동시 설치 오류**: 진행 중인 다른 설치에 대한 오류가 표시되지만 없으면 관리자로 설치 프로그램을 실행해 보세요.

901 903 

902<h3 id="branch-doesn-t-exist-yet-when-opening-in-cli">904<h3 id="branch-doesnt-exist-yet-when-opening-in-cli">

903 CLI에서 열 때 "Branch doesn't exist yet"905 CLI에서 열 때 "Branch doesn't exist yet"

904</h3>906</h3>

905 907 


914 여전히 막혔나요?916 여전히 막혔나요?

915</h3>917</h3>

916 918 

917* [GitHub Issues](https://github.com/anthropics/claude-code/issues)에서 검색하거나 버그를 제출합니다919* 데스크톱 앱에서 Help → Get Support를 열거나 [Claude 지원 센터](https://support.claude.com/) 직접 방문합니다

918* [Claude 지원 센터](https://support.claude.com/) 방문합니다920* 독립 실행형 `claude` CLI에서도 재현되는 문제의 경우 [GitHub Issues](https://github.com/anthropics/claude-code/issues)에서 검색하거나 버그를 제출합니다

919 921 

920버그를 제출할 때 데스크톱 앱 버전, 운영 체제, 정확한 오류 메시지, 관련 로그를 포함합니다. macOS에서는 Console.app을 확인합니다. Windows에서는 Event Viewer → Windows Logs → Application을 확인합니다.922문제를 보고할 때 데스크톱 앱 버전, 운영 체제, 정확한 오류 메시지, 관련 로그를 포함합니다. macOS에서는 Console.app을 확인합니다. Windows에서는 Event Viewer → Windows Logs → Application을 확인합니다.

Details

66 66 

67 다음을 선택할 수도 있습니다:67 다음을 선택할 수도 있습니다:

68 68 

69 * **Remote**: Anthropic의 클라우드 인프라에서 세션을 실행하며, 앱을 닫아도 계속됩니다. 원격 세션은 [웹의 Claude Code](/ko/claude-code-on-the-web)와 동일한 인프라를 사용합니다.69 * **Remote**: Anthropic의 클라우드 인프라에서 세션을 실행하며, 앱을 닫아도 계속됩니다. 클라우드 세션은 [웹의 Claude Code](/ko/claude-code-on-the-web)와 동일한 인프라를 사용합니다.

70 * **SSH**: SSH를 통해 원격 머신(자신의 서버, 클라우드 VM 또는 dev 컨테이너)에 연결합니다. Desktop은 처음 연결할 때 원격 머신에 Claude Code를 자동으로 설치합니다.70 * **SSH**: SSH를 통해 원격 머신(자신의 서버, 클라우드 VM 또는 dev 컨테이너)에 연결합니다. Desktop은 처음 연결할 때 원격 머신에 Claude Code를 자동으로 설치합니다.

71 </Step>71 </Step>

72 72 

73 <Step title="모델 선택">73 <Step title="모델 선택">

74 전송 버튼 옆의 드롭다운에서 모델을 선택합니다. Opus, Sonnet, Haiku의 비교는 [모델](/ko/model-config#available-models)을 참조하세요. 나중에 동일한 드롭다운에서 모델을 변경할 수 있습니다.74 전송 버튼 옆의 드롭다운에서 모델을 선택합니다. 사용 가능한 모델의 비교는 [모델](/ko/model-config#available-models)을 참조하세요. 나중에 동일한 드롭다운에서 모델을 변경할 수 있습니다.

75 </Step>75 </Step>

76 76 

77 <Step title="Claude에게 할 일 지시">77 <Step title="Claude에게 할 일 지시">


129 129 

130Desktop은 그래픽 인터페이스를 갖춘 CLI와 동일한 엔진을 실행합니다. 동일한 프로젝트에서 둘 다 동시에 실행할 수 있으며, 구성(CLAUDE.md 파일, MCP servers, hooks, skills, 설정)을 공유합니다. 기능, 플래그 동등물, Desktop에서 사용할 수 없는 것의 전체 비교는 [CLI 비교](/ko/desktop#coming-from-the-cli)를 참조하세요.130Desktop은 그래픽 인터페이스를 갖춘 CLI와 동일한 엔진을 실행합니다. 동일한 프로젝트에서 둘 다 동시에 실행할 수 있으며, 구성(CLAUDE.md 파일, MCP servers, hooks, skills, 설정)을 공유합니다. 기능, 플래그 동등물, Desktop에서 사용할 수 없는 것의 전체 비교는 [CLI 비교](/ko/desktop#coming-from-the-cli)를 참조하세요.

131 131 

132<h2 id="what-s-next">132<h2 id="whats-next">

133 다음 단계133 다음 단계

134</h2>134</h2>

135 135 

discover-plugins.md +137 −69

Details

10 10 

11자신의 마켓플레이스를 만들고 배포하려고 하시나요? [플러그인 마켓플레이스 만들기 및 배포](/ko/plugin-marketplaces)를 참조하세요.11자신의 마켓플레이스를 만들고 배포하려고 하시나요? [플러그인 마켓플레이스 만들기 및 배포](/ko/plugin-marketplaces)를 참조하세요.

12 12 

13## 마켓플레이스 작동 방식13<h2 id="how-marketplaces-work">

14 마켓플레이스 작동 방식

15</h2>

14 16 

15마켓플레이스는 다른 사람이 만들어 공유한 플러그인의 카탈로그입니다. 마켓플레이스를 사용하는 것은 두 단계의 프로세스입니다:17마켓플레이스는 다른 사람이 만들어 공유한 플러그인의 카탈로그입니다. 마켓플레이스를 사용하는 것은 두 단계의 프로세스입니다:

16 18 


26 28 

27앱 스토어를 추가하는 것과 같다고 생각하면 됩니다. 스토어를 추가하면 해당 컬렉션을 검색할 수 있지만, 여전히 개별적으로 다운로드할 앱을 선택합니다.29앱 스토어를 추가하는 것과 같다고 생각하면 됩니다. 스토어를 추가하면 해당 컬렉션을 검색할 수 있지만, 여전히 개별적으로 다운로드할 앱을 선택합니다.

28 30 

29## 공식 Anthropic 마켓플레이스31<h2 id="official-anthropic-marketplace">

32 공식 Anthropic 마켓플레이스

33</h2>

30 34 

31공식 Anthropic 마켓플레이스(`claude-plugins-official`)는 Claude Code를 시작할 때 자동으로 사용 가능합니다. `/plugin`을 실행하고 **Discover** 탭으로 이동하여 사용 가능한 항목을 검색하거나 [claude.com/plugins](https://claude.com/plugins)에서 카탈로그를 확인합니다.35공식 Anthropic 마켓플레이스(`claude-plugins-official`)는 Claude Code를 시작할 때 자동으로 사용 가능합니다. `/plugin`을 실행하고 **Discover** 탭으로 이동하여 사용 가능한 항목을 검색하거나 [claude.com/plugins](https://claude.com/plugins)에서 카탈로그를 확인합니다.

32 36 


44 48 

45공식 마켓플레이스에는 여러 카테고리의 플러그인이 포함되어 있습니다:49공식 마켓플레이스에는 여러 카테고리의 플러그인이 포함되어 있습니다:

46 50 

47### 코드 인텔리전스51<h3 id="code-intelligence">

52 코드 인텔리전스

53</h3>

48 54 

49코드 인텔리전스 플러그인은 Claude Code의 기본 제공 LSP 도구를 활성화하여 Claude가 정의로 이동하고, 참조를 찾으며, 편집 직후 타입 오류를 볼 수 있도록 합니다. 이러한 플러그인은 [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) 연결을 구성하며, 이는 VS Code의 코드 인텔리전스를 지원하는 동일한 기술입니다.55코드 인텔리전스 플러그인은 Claude Code의 기본 제공 LSP 도구를 활성화하여 Claude가 정의로 이동하고, 참조를 찾으며, 편집 직후 타입 오류를 볼 수 있도록 합니다. 이러한 플러그인은 [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) 연결을 구성하며, 이는 VS Code의 코드 인텔리전스를 지원하는 동일한 기술입니다.

50 56 


70 플러그인을 설치한 후 `/plugin` Errors 탭에서 `Executable not found in $PATH`를 보면 위 표에서 필요한 바이너리를 설치하세요.76 플러그인을 설치한 후 `/plugin` Errors 탭에서 `Executable not found in $PATH`를 보면 위 표에서 필요한 바이너리를 설치하세요.

71</Note>77</Note>

72 78 

73#### 코드 인텔리전스 플러그인이 Claude에 제공하는 79<h4 id="what-claude-gains-from-code-intelligence-plugins">

80 코드 인텔리전스 플러그인이 Claude에 제공하는 것

81</h4>

74 82 

75코드 인텔리전스 플러그인이 설치되고 해당 언어 서버 바이너리를 사용할 수 있으면 Claude는 두 가지 기능을 얻습니다:83코드 인텔리전스 플러그인이 설치되고 해당 언어 서버 바이너리를 사용할 수 있으면 Claude는 두 가지 기능을 얻습니다:

76 84 


79 87 

80문제가 발생하면 [코드 인텔리전스 문제 해결](#code-intelligence-issues)을 참조하세요.88문제가 발생하면 [코드 인텔리전스 문제 해결](#code-intelligence-issues)을 참조하세요.

81 89 

82### 외부 통합90<h3 id="external-integrations">

91 외부 통합

92</h3>

83 93 

84이러한 플러그인은 미리 구성된 [MCP servers](/ko/mcp)를 번들로 제공하므로 수동 설정 없이 Claude를 외부 서비스에 연결할 수 있습니다:94이러한 플러그인은 미리 구성된 [MCP servers](/ko/mcp)를 번들로 제공하므로 수동 설정 없이 Claude를 외부 서비스에 연결할 수 있습니다:

85 95 


90* **커뮤니케이션**: `slack`100* **커뮤니케이션**: `slack`

91* **모니터링**: `sentry`101* **모니터링**: `sentry`

92 102 

93### 자동 보안 검토103<h3 id="automatic-security-review">

104 자동 보안 검토

105</h3>

94 106 

95`security-guidance` 플러그인은 Claude가 만드는 각 변경 사항을 일반적인 취약점에 대해 검토하고 Claude에게 같은 세션에서 발견한 내용을 수정하도록 지시합니다. [Claude가 코드를 작성할 때 보안 문제 포착](/ko/security-guidance)에서 검사하는 내용과 프로젝트별 규칙을 추가하는 방법을 참조하세요.107`security-guidance` 플러그인은 Claude가 만드는 각 변경 사항을 일반적인 취약점에 대해 검토하고 Claude에게 같은 세션에서 발견한 내용을 수정하도록 지시합니다. [Claude가 코드를 작성할 때 보안 문제 포착](/ko/security-guidance)에서 검사하는 내용과 프로젝트별 규칙을 추가하는 방법을 참조하세요.

96 108 

97### 개발 워크플로우109<h3 id="development-workflows">

110 개발 워크플로우

111</h3>

98 112 

99일반적인 개발 작업을 위한 skills 및 agents를 추가하는 플러그인:113일반적인 개발 작업을 위한 skills 및 agents를 추가하는 플러그인:

100 114 


103* **agent-sdk-dev**: Claude Agent SDK로 빌드하기 위한 도구117* **agent-sdk-dev**: Claude Agent SDK로 빌드하기 위한 도구

104* **plugin-dev**: 자신의 플러그인을 만들기 위한 도구 모음118* **plugin-dev**: 자신의 플러그인을 만들기 위한 도구 모음

105 119 

106### 출력 스타일120<h3 id="output-styles">

121 출력 스타일

122</h3>

107 123 

108Claude가 응답하는 방식을 사용자 정의합니다:124Claude가 응답하는 방식을 사용자 정의합니다:

109 125 

110* **explanatory-output-style**: 구현 선택에 대한 교육적 통찰력126* **explanatory-output-style**: 구현 선택에 대한 교육적 통찰력

111* **learning-output-style**: 기술 습득을 위한 대화형 학습 모드127* **learning-output-style**: 기술 습득을 위한 대화형 학습 모드

112 128 

113## 시도해보기: 데모 마켓플레이스 추가129<h2 id="community-marketplace">

130 커뮤니티 마켓플레이스

131</h2>

114 132 

115Anthropic은 또한 플러그인 시스템으로 가능한 것을 보여주는 예제 플러그인이 있는 [데모 플러그인 마켓플레이스](https://github.com/anthropics/claude-code/tree/main/plugins)(`claude-code-plugins`) 유지 관리합니다. 공식 마켓플레이스와 달리 이 마켓플레이스는 수동으로 추가해야 합니다.133[`anthropics/claude-plugins-community`](https://github.com/anthropics/claude-plugins-community) 커뮤니티 마켓플레이스는 Anthropic의 자동화된 검증 및 안전 심사를 통과한 타사 플러그인을 호스팅합니다. 각 플러그인은 카탈로그의 특정 커밋 SHA에 고정됩니다. 공식 마켓플레이스와 달리 수동으로 추가해야 합니다:

134 

135```shell theme={null}

136/plugin marketplace add anthropics/claude-plugins-community

137```

138 

139그런 다음 `claude-community` 마켓플레이스 이름을 사용하여 플러그인을 설치합니다:

140 

141```shell theme={null}

142/plugin install <plugin-name>@claude-community

143```

144 

145자신의 플러그인을 커뮤니티 마켓플레이스에 제출하려면 플러그인 생성 가이드의 [Submit your plugin to the community marketplace](/ko/plugins#submit-your-plugin-to-the-community-marketplace)를 참조하세요.

146 

147<h2 id="try-it-add-the-demo-marketplace">

148 시도해보기: 데모 마켓플레이스 추가

149</h2>

150 

151Anthropic은 플러그인 시스템으로 가능한 것들을 보여주는 예제 플러그인이 포함된 [데모 플러그인 마켓플레이스](https://github.com/anthropics/claude-code/tree/main/plugins)(`claude-code-plugins`)를 유지 관리합니다. 공식 마켓플레이스와 달리 이 마켓플레이스는 수동으로 추가해야 합니다.

116 152 

117<Steps>153<Steps>

118 <Step title="마켓플레이스 추가">154 <Step title="마켓플레이스 추가">


122 /plugin marketplace add anthropics/claude-code158 /plugin marketplace add anthropics/claude-code

123 ```159 ```

124 160 

125 이는 마켓플레이스 카탈로그를 다운로드하고 해당 플러그인을 사용 가능하게 합니다.161 이는 마켓플레이스 카탈로그를 다운로드하고 해당 플러그인을 사용 가능하게 만듭니다.

126 </Step>162 </Step>

127 163 

128 <Step title="사용 가능한 플러그인 찾아보기">164 <Step title="사용 가능한 플러그인 찾아보기">

129 `/plugin`을 실행하여 플러그인 관리자를 엽니다. 이는 **Tab** (또는 뒤로 가려면 **Shift+Tab**) 사용하여 순환할 수 있는 4개의 탭이 있는 탭 인터페이스를 엽니다:165 `/plugin`을 실행하여 플러그인 관리자를 엽니다. 이는 **Tab** (또는 뒤로 가려면 **Shift+Tab**) 사용하여 순환할 수 있는 4개의 탭이 있는 탭 인터페이스를 엽니다:

130 166 

131 * **Discover**: 모든 마켓플레이스에서 사용 가능한 플러그인 찾아보기167 * **Discover**: 모든 마켓플레이스에서 사용 가능한 플러그인 찾아보기

132 * **Installed**: 설치된 플러그인 보기 및 관리168 * **Installed**: 설치된 플러그인 보기 및 관리

133 * **Marketplaces**: 추가된 마켓플레이스 추가, 제거 또는 업데이트169 * **Marketplaces**: 추가된 마켓플레이스 추가, 제거 또는 업데이트

134 * **Errors**: 플러그인 로딩 오류 보기170 * **Errors**: 플러그인 로딩 오류 보기

135 171 

136 방금 추가한 마켓플레이스의 플러그인을 보려면 **Discover** 탭으로 이동합니다. {/* min-version: 2.1.154 */}현재 작업 디렉토리와 관련이 있는 것으로 표시된 플러그인은 **suggested for this directory** 레이블과 함께 맨 위에 고정됩니다.172 방금 추가한 마켓플레이스의 플러그인을 보려면 **Discover** 탭으로 이동합니다. {/* min-version: 2.1.154 */}관리자가 [`pluginSuggestionMarketplaces`](/ko/settings#available-settings) 관리 설정을 통해 마켓플레이스를 허용 목록에 추가한 경우, 현재 작업 디렉토리와 관련이 있는 것으로 표시된 플러그인은 **suggested for this directory** 레이블과 함께 맨 위에 고정됩니다.

137 </Step>173 </Step>

138 174 

139 <Step title="플러그인 설치">175 <Step title="플러그인 설치">

140 플러그인을 선택하여 세부 정보를 봅니다. 세부 정보 창에는 플러그인에 포함된 내용과 비용이 표시됩니다:176 플러그인을 선택하여 세부 정보를 봅니다. 세부 정보 창에는 플러그인에 포함된 내용과 비용이 표시됩니다:

141 177 

142 * {/* min-version: 2.1.143 */}**Context cost** 예상치로 플러그인이 매 턴마다 [컨텍스트 윈도우](/ko/features-overview#understand-context-costs)에 추가할 토큰 수를 확인할있습니다(Claude Code v2.1.143 이상)178 * {/* min-version: 2.1.143 */}플러그인이 매 턴마다 [컨텍스트 윈도우](/ko/features-overview#understand-context-costs)에 추가할 토큰 수를 있는 **Context cost** 예상치 (Claude Code v2.1.143 이상)

143 * {/* min-version: 2.1.144 */}플러그인의 **Last updated** 날짜(v2.1.144 이상)179 * {/* min-version: 2.1.144 */}플러그인의 **Last updated** 날짜 (v2.1.144 이상)

144 * {/* min-version: 2.1.145 */}플러그인의 명령어, 에이전트, 스킬, 훅 및 MCP와 LSP 서버를 나열하는 **Will install** 섹션으로, 설치 전에 정확히 무엇이 추가되는지 검토할 수 있습니다(v2.1.145 이상)180 * {/* min-version: 2.1.145 */}플러그인의 명령어, 에이전트, 스킬, 훅 및 MCP와 LSP 서버를 나열하는 **Will install** 섹션으로, 설치 전에 정확히 무엇이 추가되는지 검토할 수 있습니다 (v2.1.145 이상)

145 181 

146 설치 범위를 선택합니다:182 설치 범위를 선택합니다:

147 183 


149 * **Project scope**: 이 저장소의 모든 협력자를 위해 설치185 * **Project scope**: 이 저장소의 모든 협력자를 위해 설치

150 * **Local scope**: 이 저장소에서만 자신을 위해 설치186 * **Local scope**: 이 저장소에서만 자신을 위해 설치

151 187 

152 예를 들어 **commit-commands**(git 워크플로우 스킬을 추가하는 플러그인)를 선택하고 사용자 범위에 설치합니다.188 예를 들어 **commit-commands** (git 워크플로우 스킬을 추가하는 플러그인)를 선택하고 사용자 범위에 설치합니다.

153 189 

154 명령줄에서 직접 설치할 수도 있습니다:190 명령줄에서 직접 설치할 수도 있습니다:

155 191 


177 213 

178이 가이드의 나머지 부분에서는 마켓플레이스를 추가하고, 플러그인을 설치하며, 구성을 관리하는 모든 방법을 다룹니다.214이 가이드의 나머지 부분에서는 마켓플레이스를 추가하고, 플러그인을 설치하며, 구성을 관리하는 모든 방법을 다룹니다.

179 215 

180## 마켓플레이스 추가216<h2 id="add-marketplaces">

217 마켓플레이스 추가

218</h2>

181 219 

182`/plugin marketplace add` 명령어를 사용하여 다양한 소스에서 마켓플레이스를 추가합니다.220`/plugin marketplace add` 명령을 사용하여 다양한 소스에서 마켓플레이스를 추가합니다.

183 221 

184<Tip>222<Tip>

185 **바로가기**: `/plugin marketplace` 대신 `/plugin market`을 사용할 수 있으며, `remove` 대신 `rm`을 사용할 수 있습니다.223 **단축키**: `/plugin marketplace` 대신 `/plugin market`을 사용할 수 있으며, `remove` 대신 `rm`을 사용할 수 있습니다.

186</Tip>224</Tip>

187 225 

188* **GitHub 저장소**: `owner/repo` 형식(예: `anthropics/claude-code`)226* **GitHub 저장소**: `owner/repo` 형식(예: `anthropics/claude-code`)

189* **Git URL**: 모든 git 저장소 URL(GitLab, Bitbucket, 자체 호스팅)227* **Git URL**: 모든 git 저장소 URL(GitLab, Bitbucket, 자체 호스팅)

190* **로컬 경로**: 디렉토리 또는 `marketplace.json` 파일에 대한 직접 경로228* **로컬 경로**: 디렉터리 또는 `marketplace.json` 파일의 직접 경로

191* **원격 URL**: 호스팅된 `marketplace.json` 파일에 대한 직접 URL229* **원격 URL**: 호스팅된 `marketplace.json` 파일의 직접 URL

192 230 

193### GitHub에서 추가231<h3 id="add-from-github">

232 GitHub에서 추가

233</h3>

194 234 

195`.claude-plugin/marketplace.json` 파일을 포함하는 GitHub 저장소를 `owner/repo` 형식으로 추가합니다. 여기서 `owner`는 GitHub 사용자 이름 또는 조직이고 `repo`는 저장소 이름입니다.235`.claude-plugin/marketplace.json` 파일을 포함하는 GitHub 저장소를 `owner/repo` 형식으로 추가합니다. 여기서 `owner`는 GitHub 사용자명 또는 조직이고 `repo`는 저장소 이름입니다.

196 236 

197예를 들어 `anthropics/claude-code`는 `anthropics`가 소유한 `claude-code` 저장소를 나타냅니다:237예를 들어, `anthropics/claude-code`는 `anthropics`가 소유한 `claude-code` 저장소를 나타냅니다:

198 238 

199```shell theme={null}239```shell theme={null}

200/plugin marketplace add anthropics/claude-code240/plugin marketplace add anthropics/claude-code

201```241```

202 242 

203### 다른 Git 호스트에서 추가243<h3 id="add-from-other-git-hosts">

244 다른 Git 호스트에서 추가

245</h3>

204 246 

205전체 URL을 제공하여 모든 git 저장소를 추가합니다. 이는 GitLab, Bitbucket 및 자체 호스팅 서버를 포함한 모든 Git 호스트에서 작동합니다. Claude Code가 URL을 호스팅된 `marketplace.json` 파일에 대한 직접 링크로 처리하지 않고 저장소를 복제하도록 `.git` 접미사를 포함합니다.247전체 URL을 제공하여 모든 git 저장소를 추가합니다. 이는 GitLab, Bitbucket 및 자체 호스팅 서버를 포함한 모든 Git 호스트에서 작동합니다. `.git` 접미사를 포함하여 Claude Code가 저장소를 복제하도록 하고 URL을 호스팅된 `marketplace.json` 파일의 직접 링크로 처리하지 않도록 합니다.

206 248 

207HTTPS 사용:249HTTPS 사용:

208 250 


222/plugin marketplace add https://gitlab.com/company/plugins.git#v1.0.0264/plugin marketplace add https://gitlab.com/company/plugins.git#v1.0.0

223```265```

224 266 

225### 로컬 경로에서 추가267<h3 id="add-from-local-paths">

268 로컬 경로에서 추가

269</h3>

226 270 

227`.claude-plugin/marketplace.json` 파일을 포함하는 로컬 디렉토리를 추가합니다:271`.claude-plugin/marketplace.json` 파일을 포함하는 로컬 디렉터리를 추가합니다:

228 272 

229```shell theme={null}273```shell theme={null}

230/plugin marketplace add ./my-marketplace274/plugin marketplace add ./my-marketplace

231```275```

232 276 

233`marketplace.json` 파일에 대한 직접 경로를 추가할 수도 있습니다:277`marketplace.json` 파일의 직접 경로를 추가할 수도 있습니다:

234 278 

235```shell theme={null}279```shell theme={null}

236/plugin marketplace add ./path/to/marketplace.json280/plugin marketplace add ./path/to/marketplace.json

237```281```

238 282 

239### 원격 URL에서 추가283<h3 id="add-from-remote-urls">

284 원격 URL에서 추가

285</h3>

240 286 

241URL을 통해 원격 `marketplace.json` 파일을 추가합니다:287URL을 통해 원격 `marketplace.json` 파일을 추가합니다:

242 288 


248 URL 기반 마켓플레이스는 Git 기반 마켓플레이스에 비해 몇 가지 제한 사항이 있습니다. 플러그인을 설치할 때 "경로를 찾을 수 없음" 오류가 발생하면 [문제 해결](/ko/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces)을 참조하세요.294 URL 기반 마켓플레이스는 Git 기반 마켓플레이스에 비해 몇 가지 제한 사항이 있습니다. 플러그인을 설치할 때 "경로를 찾을 수 없음" 오류가 발생하면 [문제 해결](/ko/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces)을 참조하세요.

249</Note>295</Note>

250 296 

251## 플러그인 설치297<h2 id="install-plugins">

298 플러그인 설치

299</h2>

252 300 

253마켓플레이스를 추가한 후 플러그인을 직접 설치할 수 있습니다(기본적으로 사용자 범위에 설치됨):301마켓플레이스를 추가한 후 플러그인을 직접 설치할 수 있습니다(기본적으로 사용자 범위로 설치됨):

254 302 

255```shell theme={null}303```shell theme={null}

256/plugin install plugin-name@marketplace-name304/plugin install plugin-name@marketplace-name

257```305```

258 306 

259다른 [설치 범위](/ko/settings#configuration-scopes)를 선택하려면 대화형 UI를 사용합니다: `/plugin`을 실행하고 **Discover** 탭으로 이동한 후 플러그인에서 **Enter**를 누릅니다. 다음 옵션이 표시됩니다:307다른 [설치 범위](/ko/settings#configuration-scopes)를 선택하려면 대화형 UI를 사용하세요. `/plugin`을 실행하고 **Discover** 탭으로 이동한 후 플러그인에서 **Enter**를 누르세요. 다음 옵션이 표시됩니다:

260 308 

261* **User scope**(기본값): 모든 프로젝트에서 자신을 위해 설치309* **사용자 범위**(기본값): 모든 프로젝트에서 자신을 위해 설치

262* **Project scope**: 이 저장소의 모든 협력자를 위해 설치(`.claude/settings.json`에 추가)310* **프로젝트 범위**: 이 저장소의 모든 협력자를 위해 설치(`.claude/settings.json`에 추가)

263* **Local scope**: 이 저장소에서만 자신을 위해 설치(협력자와 공유되지 않음)311* **로컬 범위**: 이 저장소에서만 자신을 위해 설치(협력자와 공유되지 않음)

264 312 

265**managed** 범위의 플러그인도 볼 수 있습니다. 이는 관리자가 [관리되는 설정](/ko/settings#settings-files)을 통해 설치하며 수정할 수 없습니다.313**관리됨** 범위의 플러그인도 볼 수 있습니다. 이러한 플러그인은 관리자가 [관리 설정](/ko/settings#settings-files)을 통해 설치하며 수정할 수 없습니다.

266 314 

267<Warning>315<Warning>

268 플러그인을 설치하기 전에 신뢰할 수 있는지 확인하세요. Anthropic은 플러그인에 포함된 MCP servers, 파일 또는 기타 소프트웨어를 제어하지 않으며 의도한 대로 작동하는지 확인할 수 없습니다. 자세한 내용은 각 플러그인의 홈페이지를 확인하세요.316 플러그인을 설치하기 전에 신뢰할 수 있는지 확인하세요. Anthropic은 플러그인에 포함된 MCP 서버, 파일 또는 기타 소프트웨어를 제어하지 않으며 의도한 대로 작동하는지 확인할 수 없습니다. 자세한 내용은 각 플러그인의 홈페이지를 확인하세요.

269</Warning>317</Warning>

270 318 

271## 커뮤니티 마켓플레이스319<h2 id="manage-installed-plugins">

272 320 설치된 플러그인 관리

273[`anthropics/claude-plugins-community`](https://github.com/anthropics/claude-plugins-community)의 커뮤니티 마켓플레이스는 Anthropic의 자동화된 검증 및 보안 심사를 통과한 타사 플러그인을 호스팅합니다. 각 플러그인은 카탈로그의 특정 commit SHA에 고정됩니다. 공식 마켓플레이스와 달리 수동으로 추가해야 합니다:321</h2>

274 

275```shell theme={null}

276/plugin marketplace add anthropics/claude-plugins-community

277```

278 

279그런 다음 `claude-community` 마켓플레이스 이름을 사용하여 플러그인을 설치합니다:

280 

281```shell theme={null}

282/plugin install <plugin-name>@claude-community

283```

284 

285자신의 플러그인을 커뮤니티 마켓플레이스에 제출하려면 플러그인 생성 가이드의 [플러그인을 커뮤니티 마켓플레이스에 제출](/ko/plugins#submit-your-plugin-to-the-community-marketplace)을 참조하세요.

286 

287## 설치된 플러그인 관리

288 322 

289`/plugin`을 실행하고 **Installed** 탭으로 이동하여 플러그인을 보고, 활성화하고, 비활성화하거나, 제거합니다. 목록은 범위별로 그룹화되고 문제가 먼저 표시되도록 정렬됩니다: 로드 오류 또는 해결되지 않은 종속성이 있는 플러그인이 맨 위에 나타나고, 그 다음 즐겨찾기가 나타나며, 비활성화된 플러그인은 맨 아래의 축소된 헤더 뒤에 접혀 있습니다.323`/plugin`을 실행하고 **Installed** 탭으로 이동하여 플러그인을 보고, 활성화하고, 비활성화하거나, 제거합니다. 목록은 범위별로 그룹화되고 문제가 먼저 표시되도록 정렬됩니다: 로드 오류 또는 해결되지 않은 종속성이 있는 플러그인이 맨 위에 나타나고, 그 다음 즐겨찾기가 나타나며, 비활성화된 플러그인은 맨 아래의 축소된 헤더 뒤에 접혀 있습니다.

290 324 


294* 입력하여 플러그인 이름 또는 설명으로 필터링328* 입력하여 플러그인 이름 또는 설명으로 필터링

295* Enter를 눌러 플러그인의 세부 정보 보기를 열고 활성화, 비활성화 또는 제거329* Enter를 눌러 플러그인의 세부 정보 보기를 열고 활성화, 비활성화 또는 제거

296 330 

331세부 정보 보기는 플러그인이 제공하는 구성 요소를 표시합니다: 명령어, skills, agents, hooks, MCP servers 및 LSP servers. 동일한 인벤토리는 `claude plugin details` 명령어로 명령줄에서도 사용할 수 있습니다.

332 

297종속성을 선언하는 플러그인을 설치하면 설치 출력에 함께 자동 설치된 종속성이 나열됩니다.333종속성을 선언하는 플러그인을 설치하면 설치 출력에 함께 자동 설치된 종속성이 나열됩니다.

298 334 

299직접 명령어로 플러그인을 관리할 수도 있습니다.335직접 명령어로 플러그인을 관리할 수도 있습니다.

300 336 

337메뉴를 열지 않고 설치된 플러그인을 나열합니다:

338 

339```shell theme={null}

340/plugin list

341```

342 

343`--enabled` 또는 `--disabled`를 전달하여 해당 상태의 플러그인만 표시합니다.

344 

301플러그인을 제거하지 않고 비활성화합니다:345플러그인을 제거하지 않고 비활성화합니다:

302 346 

303```shell theme={null}347```shell theme={null}


323claude plugin uninstall formatter@your-org --scope project367claude plugin uninstall formatter@your-org --scope project

324```368```

325 369 

326### 재시작 없이 플러그인 변경 사항 적용370<h3 id="apply-plugin-changes-without-restarting">

371 재시작 없이 플러그인 변경 사항 적용

372</h3>

327 373 

328세션 중에 플러그인을 설치, 활성화 또는 비활성화할 때 `/reload-plugins`를 실행하여 재시작 없이 모든 변경 사항을 선택합니다:374세션 중에 플러그인을 설치, 활성화 또는 비활성화할 때 `/reload-plugins`를 실행하여 재시작 없이 모든 변경 사항을 선택합니다:

329 375 


333 379 

334Claude Code는 모든 활성 플러그인을 다시 로드하고 플러그인, skills, agents, hooks, 플러그인 MCP servers 및 플러그인 LSP servers의 개수를 표시합니다.380Claude Code는 모든 활성 플러그인을 다시 로드하고 플러그인, skills, agents, hooks, 플러그인 MCP servers 및 플러그인 LSP servers의 개수를 표시합니다.

335 381 

336재로드는 다음 요청에서 토큰 비용이 발생합니다: 새로 로드된 구성 요소는 대화에 추가된 콘텐츠에서 자신을 알리고, 기존 기록은 여전히 프롬프트 캐시에서 읽습니다. MCP servers를 제공하는 플러그인은 [tool search](/ko/mcp#scale-with-mcp-tool-search)에 의해 도구가 지연되지 않을 때 더 많은 비용이 발생합니다: 변경으로 인해 캐시가 무효화되고 다음 요청이 전체 대화를 다시 읽습니다. 자세한 내용은 [플러그인 활성화 또는 비활성화](/ko/prompt-caching#enabling-or-disabling-a-plugin)를 참조하세요.382재로드는 다음 요청에서 토큰 비용이 발생합니다: 새로 로드된 구성 요소는 대화에 추가된 콘텐츠에서 자신을 알리고, 기존 기록은 여전히 프롬프트 캐시에서 읽습니다. MCP servers를 제공하는 플러그인은 [tool search](/ko/mcp#scale-with-mcp-tool-search)에 의해 도구가 지연되지 않을 때 더 많은 비용이 발생합니다: 변경으로 인해 캐시가 무효화되고 다음 요청이 전체 대화를 다시 읽습니다. {/* min-version: 2.1.163 */}이 경우 `/reload-plugins`는 경고를 표시하고 재로드를 적용하지 않습니다. `--force`를 전달하여 어쨌든 적용합니다. 자세한 내용은 [플러그인 활성화 또는 비활성화](/ko/prompt-caching#enabling-or-disabling-a-plugin)를 참조하세요.

337 383 

338## 마켓플레이스 관리384<h2 id="manage-marketplaces">

385 마켓플레이스 관리

386</h2>

339 387 

340대화형 `/plugin` 인터페이스 또는 CLI 명령어를 통해 마켓플레이스를 관리할 수 있습니다.388대화형 `/plugin` 인터페이스 또는 CLI 명령어를 통해 마켓플레이스를 관리할 수 있습니다.

341 389 

342### 대화형 인터페이스 사용390<h3 id="use-the-interactive-interface">

391 대화형 인터페이스 사용

392</h3>

343 393 

344`/plugin`을 실행하고 **Marketplaces** 탭으로 이동하여:394`/plugin`을 실행하고 **Marketplaces** 탭으로 이동하여:

345 395 


348* 마켓플레이스 목록을 업데이트하여 최신 플러그인 가져오기398* 마켓플레이스 목록을 업데이트하여 최신 플러그인 가져오기

349* 더 이상 필요하지 않은 마켓플레이스 제거399* 더 이상 필요하지 않은 마켓플레이스 제거

350 400 

351### CLI 명령어 사용401<h3 id="use-cli-commands">

402 CLI 명령어 사용

403</h3>

352 404 

353직접 명령어로 마켓플레이스를 관리할 수도 있습니다.405직접 명령어로 마켓플레이스를 관리할 수도 있습니다.

354 406 


374 마켓플레이스를 제거하면 해당 마켓플레이스에서 설치한 모든 플러그인이 제거됩니다.426 마켓플레이스를 제거하면 해당 마켓플레이스에서 설치한 모든 플러그인이 제거됩니다.

375</Warning>427</Warning>

376 428 

377### 자동 업데이트 구성429<h3 id="configure-auto-updates">

430 자동 업데이트 구성

431</h3>

378 432 

379Claude Code는 시작 시 마켓플레이스 및 설치된 플러그인을 자동으로 업데이트할 수 있습니다. 마켓플레이스에 대해 자동 업데이트가 활성화되면 Claude Code는 마켓플레이스 데이터를 새로 고치고 설치된 플러그인을 최신 버전으로 업데이트합니다. 플러그인이 업데이트된 경우 `/reload-plugins`를 실행하도록 요청하는 알림이 표시됩니다.433Claude Code는 시작 시 마켓플레이스 및 설치된 플러그인을 자동으로 업데이트할 수 있습니다. 마켓플레이스에 대해 자동 업데이트가 활성화되면 Claude Code는 마켓플레이스 데이터를 새로 고치고 설치된 플러그인을 최신 버전으로 업데이트합니다. 플러그인이 업데이트된 경우 `/reload-plugins`를 실행하도록 요청하는 알림이 표시됩니다.

380 434 


400 454 

401Claude Code 업데이트를 수동으로 관리하지만 여전히 자동 플러그인 업데이트를 받으려는 경우에 유용합니다.455Claude Code 업데이트를 수동으로 관리하지만 여전히 자동 플러그인 업데이트를 받으려는 경우에 유용합니다.

402 456 

403## 팀 마켓플레이스 구성457<h2 id="configure-team-marketplaces">

458 팀 마켓플레이스 구성

459</h2>

404 460 

405팀 관리자는 `.claude/settings.json`에 마켓플레이스 구성을 추가하여 프로젝트에 대한 자동 마켓플레이스 설치를 설정할 수 있습니다. 팀 멤버가 저장소 폴더를 신뢰하면 Claude Code는 이러한 마켓플레이스 및 플러그인을 설치하도록 요청합니다.461팀 관리자는 `.claude/settings.json`에 마켓플레이스 구성을 추가하여 프로젝트에 대한 자동 마켓플레이스 설치를 설정할 수 있습니다. 팀 멤버가 저장소 폴더를 신뢰하면 Claude Code는 이러한 마켓플레이스 및 플러그인을 설치하도록 요청합니다.

406 462 


421 477 

422`extraKnownMarketplaces` 및 `enabledPlugins`를 포함한 전체 구성 옵션은 [플러그인 설정](/ko/settings#plugin-settings)을 참조하세요.478`extraKnownMarketplaces` 및 `enabledPlugins`를 포함한 전체 구성 옵션은 [플러그인 설정](/ko/settings#plugin-settings)을 참조하세요.

423 479 

424## 보안480<h2 id="security">

481 보안

482</h2>

425 483 

426플러그인 및 마켓플레이스는 사용자 권한으로 머신에서 임의의 코드를 실행할 수 있는 매우 신뢰할 수 있는 구성 요소입니다. 신뢰할 수 있는 소스에서만 플러그인을 설치하고 마켓플레이스를 추가합니다. 조직은 [관리되는 마켓플레이스 제한](/ko/plugin-marketplaces#managed-marketplace-restrictions)을 사용하여 사용자가 추가할 수 있는 마켓플레이스를 제한할 수 있습니다.484플러그인 및 마켓플레이스는 사용자 권한으로 머신에서 임의의 코드를 실행할 수 있는 매우 신뢰할 수 있는 구성 요소입니다. 신뢰할 수 있는 소스에서만 플러그인을 설치하고 마켓플레이스를 추가합니다. 조직은 [관리되는 마켓플레이스 제한](/ko/plugin-marketplaces#managed-marketplace-restrictions)을 사용하여 사용자가 추가할 수 있는 마켓플레이스를 제한할 수 있습니다.

427 485 

428## 문제 해결486<h2 id="troubleshooting">

487 문제 해결

488</h2>

429 489 

430### /plugin 명령어를 인식하지 못함490<h3 id="/plugin-command-not-recognized">

491 /plugin 명령어를 인식하지 못함

492</h3>

431 493 

432"알 수 없는 명령어" 또는 `/plugin` 명령어가 나타나지 않으면:494"알 수 없는 명령어" 또는 `/plugin` 명령어가 나타나지 않으면:

433 495 


438 * **네이티브 설치 프로그램**: [설정](/ko/setup)에서 설치 명령어를 다시 실행합니다.500 * **네이티브 설치 프로그램**: [설정](/ko/setup)에서 설치 명령어를 다시 실행합니다.

4393. **Claude Code 재시작**: 업데이트 후 터미널을 재시작하고 `claude`를 다시 실행합니다.5013. **Claude Code 재시작**: 업데이트 후 터미널을 재시작하고 `claude`를 다시 실행합니다.

440 502 

441### 일반적인 문제503<h3 id="common-issues">

504 일반적인 문제

505</h3>

442 506 

443* **마켓플레이스가 로드되지 않음**: URL에 액세스할 수 있고 `.claude-plugin/marketplace.json`이 경로에 있는지 확인합니다.507* **마켓플레이스가 로드되지 않음**: URL에 액세스할 수 있고 `.claude-plugin/marketplace.json`이 경로에 있는지 확인합니다.

444* **플러그인 설치 실패**: 플러그인 소스 URL에 액세스할 수 있고 저장소가 공개되어 있거나(또는 액세스 권한이 있는지) 확인합니다.508* **플러그인 설치 실패**: 플러그인 소스 URL에 액세스할 수 있고 저장소가 공개되어 있거나(또는 액세스 권한이 있는지) 확인합니다.


447 511 

448자세한 문제 해결 및 솔루션은 마켓플레이스 가이드의 [문제 해결](/ko/plugin-marketplaces#troubleshooting)을 참조하세요. 디버깅 도구는 [디버깅 및 개발 도구](/ko/plugins-reference#debugging-and-development-tools)를 참조하세요.512자세한 문제 해결 및 솔루션은 마켓플레이스 가이드의 [문제 해결](/ko/plugin-marketplaces#troubleshooting)을 참조하세요. 디버깅 도구는 [디버깅 및 개발 도구](/ko/plugins-reference#debugging-and-development-tools)를 참조하세요.

449 513 

450### 코드 인텔리전스 문제514<h3 id="code-intelligence-issues">

515 코드 인텔리전스 문제

516</h3>

451 517 

452* **언어 서버가 시작되지 않음**: 바이너리가 설치되어 있고 `$PATH`에서 사용 가능한지 확인합니다. `/plugin` Errors 탭에서 세부 정보를 확인합니다.518* **언어 서버가 시작되지 않음**: 바이너리가 설치되어 있고 `$PATH`에서 사용 가능한지 확인합니다. `/plugin` Errors 탭에서 세부 정보를 확인합니다.

453* **높은 메모리 사용량**: `rust-analyzer` 및 `pyright`와 같은 언어 서버는 대규모 프로젝트에서 상당한 메모리를 소비할 수 있습니다. 메모리 문제가 발생하면 `/plugin disable <plugin-name>`으로 플러그인을 비활성화하고 대신 Claude의 기본 제공 검색 도구를 사용합니다.519* **높은 메모리 사용량**: `rust-analyzer` 및 `pyright`와 같은 언어 서버는 대규모 프로젝트에서 상당한 메모리를 소비할 수 있습니다. 메모리 문제가 발생하면 `/plugin disable <plugin-name>`으로 플러그인을 비활성화하고 대신 Claude의 기본 제공 검색 도구를 사용합니다.

454* **모노레포에서 거짓 양성 진단**: 작업 공간이 올바르게 구성되지 않으면 언어 서버가 내부 패키지에 대해 해결되지 않은 import 오류를 보고할 수 있습니다. 이는 Claude의 코드 편집 능력에 영향을 주지 않습니다.520* **모노레포에서 거짓 양성 진단**: 작업 공간이 올바르게 구성되지 않으면 언어 서버가 내부 패키지에 대해 해결되지 않은 import 오류를 보고할 수 있습니다. 이는 Claude의 코드 편집 능력에 영향을 주지 않습니다.

455 521 

456## 다음 단계522<h2 id="next-steps">

523 다음 단계

524</h2>

457 525 

458* **자신의 플러그인 빌드**: [플러그인](/ko/plugins)을 참조하여 skills, agents 및 hooks를 만듭니다.526* **자신의 플러그인 빌드**: [플러그인](/ko/plugins)을 참조하여 skills, agents 및 hooks를 만듭니다.

459* **마켓플레이스 만들기**: [플러그인 마켓플레이스 만들기](/ko/plugin-marketplaces)를 참조하여 팀 또는 커뮤니티에 플러그인을 배포합니다.527* **마켓플레이스 만들기**: [플러그인 마켓플레이스 만들기](/ko/plugin-marketplaces)를 참조하여 팀 또는 커뮤니티에 플러그인을 배포합니다.

env-vars.md +43 −28

Details

73선택한 파일이 변수가 적용되는 대상을 제어합니다:73선택한 파일이 변수가 적용되는 대상을 제어합니다:

74 74 

75| 파일 | 적용 대상 |75| 파일 | 적용 대상 |

76| :---------------------------- | :----------------------------- |76| :---------------------------- | :-------------------------------------- |

77| `~/.claude/settings.json` | 모든 프로젝트에서 사용자 |77| `~/.claude/settings.json` | 모든 프로젝트에서 사용자 |

78| `.claude/settings.json` | 프로젝트에서 작업하는 모든 사람, 소스 제어에 체크인됨 |78| `.claude/settings.json` | 프로젝트에서 작업하는 모든 사람, 소스 제어에 체크인됨 |

79| `.claude/settings.local.json` | 이 프로젝트에서만 사용자, 체크인되지 않음 |79| `.claude/settings.local.json` | 이 프로젝트에서만 사용자 (직접 생성한 경우 gitignore에 추가) |

80| 관리형 설정 | 조직의 모든 사람, 관리자가 배포 |80| 관리형 설정 | 조직의 모든 사람, 관리자가 배포 |

81 81 

82각 파일이 있는 위치는 [설정 파일](/ko/settings#settings-files)을 참조하고, 둘 이상이 동일한 변수를 설정할 때 결합되는 방식은 [설정 우선순위](/ko/settings#settings-precedence)를 참조합니다.82각 파일이 있는 위치는 [설정 파일](/ko/settings#settings-files)을 참조하고, 둘 이상이 동일한 변수를 설정할 때 결합되는 방식은 [설정 우선순위](/ko/settings#settings-precedence)를 참조합니다.


96</h2>96</h2>

97 97 

98| 변수 | 목적 |98| 변수 | 목적 |

99| :------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |99| :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

100| `ANTHROPIC_API_KEY` | `X-Api-Key` 헤더로 전송되는 API 키입니다. 설정하면 로그인되어 있더라도 Claude Pro, Max, Team 또는 Enterprise 구독 대신 이 키가 사용됩니다. 비대화형 모드(`-p`)에서는 키가 있을 때 항상 사용됩니다. 대화형 모드에서는 키가 구독을 재정의하기 전에 한 번 승인하도록 프롬프트됩니다. 구독을 대신 사용하려면 `unset ANTHROPIC_API_KEY`를 실행합니다. |100| `ANTHROPIC_API_KEY` | `X-Api-Key` 헤더로 전송되는 API 키입니다. 설정하면 로그인되어 있더라도 Claude Pro, Max, Team 또는 Enterprise 구독 대신 이 키가 사용됩니다. 비대화형 모드(`-p`)에서는 키가 있을 때 항상 사용됩니다. 대화형 모드에서는 키가 구독을 재정의하기 전에 한 번 승인하도록 프롬프트됩니다. 구독을 대신 사용하려면 `unset ANTHROPIC_API_KEY`를 실행합니다. |

101| `ANTHROPIC_AUTH_TOKEN` | `Authorization` 헤더의 사용자 정의 값(여기서 설정한 값 앞에 `Bearer `가 붙습니다). |101| `ANTHROPIC_AUTH_TOKEN` | `Authorization` 헤더의 사용자 정의 값(여기서 설정한 값 앞에 `Bearer `가 붙습니다). |

102| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/ko/claude-platform-on-aws)의 워크스페이스 API 키이며, AWS 콘솔에서 생성됩니다. `x-api-key`로 전송되며 AWS SigV4보다 우선합니다. |102| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/ko/claude-platform-on-aws)의 워크스페이스 API 키이며, AWS 콘솔에서 생성됩니다. `x-api-key`로 전송되며 AWS SigV4보다 우선합니다. |


112| `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` | `/model` 선택기의 사용자 정의 모델 항목에 대한 표시 설명입니다. 설정하지 않으면 `Custom model (<model-id>)`로 기본값이 설정됩니다. |112| `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` | `/model` 선택기의 사용자 정의 모델 항목에 대한 표시 설명입니다. 설정하지 않으면 `Custom model (<model-id>)`로 기본값이 설정됩니다. |

113| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | `/model` 선택기의 사용자 정의 모델 항목에 대한 표시 이름입니다. 설정하지 않으면 모델 ID로 기본값이 설정됩니다. |113| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | `/model` 선택기의 사용자 정의 모델 항목에 대한 표시 이름입니다. 설정하지 않으면 모델 ID로 기본값이 설정됩니다. |

114| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | [모델 구성](/ko/model-config#customize-pinned-model-display-and-capabilities) 참조 |114| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | [모델 구성](/ko/model-config#customize-pinned-model-display-and-capabilities) 참조 |

115| `ANTHROPIC_DEFAULT_FABLE_MODEL` | [모델 구성](/ko/model-config#environment-variables) 참조 |

116| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | [모델 구성](/ko/model-config#customize-pinned-model-display-and-capabilities) 참조 |

117| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | [모델 구성](/ko/model-config#customize-pinned-model-display-and-capabilities) 참조 |

118| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | [모델 구성](/ko/model-config#customize-pinned-model-display-and-capabilities) 참조 |

115| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | [모델 구성](/ko/model-config#environment-variables) 참조 |119| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | [모델 구성](/ko/model-config#environment-variables) 참조 |

116| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | [모델 구성](/ko/model-config#customize-pinned-model-display-and-capabilities) 참조 |120| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | [모델 구성](/ko/model-config#customize-pinned-model-display-and-capabilities) 참조 |

117| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | [모델 구성](/ko/model-config#customize-pinned-model-display-and-capabilities) 참조 |121| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | [모델 구성](/ko/model-config#customize-pinned-model-display-and-capabilities) 참조 |


133| `ANTHROPIC_VERTEX_BASE_URL` | Vertex AI 엔드포인트 URL을 재정의합니다. 사용자 정의 Vertex 엔드포인트 또는 [LLM 게이트웨이](/ko/llm-gateway)를 통해 라우팅할 때 사용합니다. [Google Vertex AI](/ko/google-vertex-ai) 참조 |137| `ANTHROPIC_VERTEX_BASE_URL` | Vertex AI 엔드포인트 URL을 재정의합니다. 사용자 정의 Vertex 엔드포인트 또는 [LLM 게이트웨이](/ko/llm-gateway)를 통해 라우팅할 때 사용합니다. [Google Vertex AI](/ko/google-vertex-ai) 참조 |

134| `ANTHROPIC_VERTEX_PROJECT_ID` | Vertex AI 요청용 GCP 프로젝트 ID입니다. `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT` 또는 `GOOGLE_APPLICATION_CREDENTIALS` 자격 증명 파일의 프로젝트로 재정의됩니다. [Google Vertex AI](/ko/google-vertex-ai) 참조 |138| `ANTHROPIC_VERTEX_PROJECT_ID` | Vertex AI 요청용 GCP 프로젝트 ID입니다. `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT` 또는 `GOOGLE_APPLICATION_CREDENTIALS` 자격 증명 파일의 프로젝트로 재정의됩니다. [Google Vertex AI](/ko/google-vertex-ai) 참조 |

135| `ANTHROPIC_WORKSPACE_ID` | [워크로드 ID 페더레이션](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)용 워크스페이스 ID입니다. 페더레이션 규칙이 둘 이상의 워크스페이스로 범위가 지정되어 있을 때 토큰 교환이 어느 워크스페이스를 대상으로 할지 알 수 있도록 이를 설정합니다. |139| `ANTHROPIC_WORKSPACE_ID` | [워크로드 ID 페더레이션](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)용 워크스페이스 ID입니다. 페더레이션 규칙이 둘 이상의 워크스페이스로 범위가 지정되어 있을 때 토큰 교환이 어느 워크스페이스를 대상으로 할지 알 수 있도록 이를 설정합니다. |

140| `API_FORCE_IDLE_TIMEOUT` | {/* min-version: 2.1.169 */}바이트가 도착하지 않을 때 스트리밍 모델 응답을 중단하는 5분 유휴 타임아웃을 재정의합니다. 느린 [게이트웨이](/ko/llm-gateway) 또는 로컬 모델이 청크 사이에 5분 이상 일시 중지할 때 `0`으로 설정하여 타임아웃을 비활성화합니다. 모든 공급자에서 타임아웃을 활성화하려면 `1`로 설정합니다. 설정하지 않으면 타임아웃은 직접 Anthropic API 및 [Claude Platform on AWS](/ko/claude-platform-on-aws) 연결에서 비활성화되며, Claude Code의 자체 바이트 수준 스트림 감시견이 실행되고, [Vertex AI](/ko/google-vertex-ai), [Foundry](/ko/microsoft-foundry), [Mantle](/ko/amazon-bedrock#use-the-mantle-endpoint), [Bedrock](/ko/amazon-bedrock), 게이트웨이 연결을 포함한 다른 모든 공급자에서 활성화되므로 정체된 스트림이 중단되지 않고 중단됩니다. v2.1.169부터 |

136| `API_TIMEOUT_MS` | API 요청의 타임아웃(밀리초)(기본값: 600000, 또는 10분; 최대: 2147483647). 느린 네트워크에서 요청이 시간 초과되거나 프록시를 통해 라우팅할 때 이를 증가시킵니다. 최대값을 초과하는 값은 기본 타이머를 오버플로우하여 요청이 즉시 실패하게 합니다. |141| `API_TIMEOUT_MS` | API 요청의 타임아웃(밀리초)(기본값: 600000, 또는 10분; 최대: 2147483647). 느린 네트워크에서 요청이 시간 초과되거나 프록시를 통해 라우팅할 때 이를 증가시킵니다. 최대값을 초과하는 값은 기본 타이머를 오버플로우하여 요청이 즉시 실패하게 합니다. |

137| `AWS_BEARER_TOKEN_BEDROCK` | 인증용 Bedrock API 키([Bedrock API 키](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/) 참조) |142| `AWS_BEARER_TOKEN_BEDROCK` | 인증용 Bedrock API 키([Bedrock API 키](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/) 참조) |

138| `BASH_DEFAULT_TIMEOUT_MS` | 장시간 실행되는 bash 명령의 기본 타임아웃(기본값: 120000, 또는 2분) |143| `BASH_DEFAULT_TIMEOUT_MS` | 장시간 실행되는 bash 명령의 기본 타임아웃(기본값: 120000, 또는 2분) |

139| `BASH_MAX_OUTPUT_LENGTH` | bash 출력이 전체 출력이 파일에 저장되고 Claude가 경로와 짧은 미리보기를 받기 전의 최대 문자 수입니다. [Bash 도구 동작](/ko/tools-reference#bash-tool-behavior) 참조 |144| `BASH_MAX_OUTPUT_LENGTH` | bash 출력이 전체 출력이 파일에 저장되고 Claude가 경로와 짧은 미리보기를 받기 전의 최대 문자 수입니다. [Bash 도구 동작](/ko/tools-reference#bash-tool-behavior) 참조 |

140| `BASH_MAX_TIMEOUT_MS` | 모델이 장시간 실행되는 bash 명령에 대해 설정할 수 있는 최대 타임아웃(기본값: 600000, 또는 10분) |145| `BASH_MAX_TIMEOUT_MS` | 모델이 장시간 실행되는 bash 명령에 대해 설정할 수 있는 최대 타임아웃(기본값: 600000, 또는 10분) |

141| `CCR_FORCE_BUNDLE` | GitHub 액세스가 가능한 경우에도 [`claude --remote`](/ko/claude-code-on-the-web#send-local-repositories-without-github)가 로컬 리포지토리를 번들로 제공하고 업로드하도록 강제하려면 `1`로 설정합니다. |146| `CCR_FORCE_BUNDLE` | GitHub 액세스가 가능한 경우에도 [`claude --remote`](/ko/claude-code-on-the-web#send-local-repositories-without-github)가 로컬 리포지토리를 번들로 제공하고 업로드하도록 강제하려면 `1`로 설정합니다. |

142| `CLAUDECODE` | Claude Code가 생성하는 subprocess(Bash 및 PowerShell 도구, tmux 세션, [훅](/ko/hooks) 명령, [상태 줄](/ko/statusline) 명령, stdio [MCP 서버](/ko/mcp) subprocess)에서 `1`로 설정됩니다. Claude Code가 생성한 subprocess 내에서 스크립트가 실행 중인지 감지하는 데 사용합니다. |147| `CLAUDECODE` | Claude Code가 생성하는 subprocess(Bash 및 PowerShell 도구, tmux 세션, [훅](/ko/hooks) 명령, [상태 줄](/ko/statusline) 명령, stdio [MCP 서버](/ko/mcp) subprocess)에서 `1`로 설정됩니다. IDE 확장도 통합 터미널에서 이를 설정합니다. Claude Code가 생성한 subprocess 내에서 스크립트가 실행 중인지 감지하는 데 사용합니다. 현재 프로세스가 도구 호출 또는 훅에 의해 직접 생성되었는지, 아니면 Claude Code가 시작한 stdio [MCP 서버](/ko/mcp) 내부인지 확인하려면 `CLAUDE_CODE_CHILD_SESSION`을 대신 사용합니다. |

143| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 모든 기본 제공 [subagent](/ko/sub-agents) 유형(예: Explore 및 Plan)을 비활성화하려면 `1`로 설정합니다. 비대화형 모드(`-p` 플래그)에만 적용됩니다. SDK 사용자가 백지 상태를 원할 때 유용합니다. |148| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 모든 기본 제공 [subagent](/ko/sub-agents) 유형(예: Explore 및 Plan)을 비활성화하려면 `1`로 설정합니다. 비대화형 모드(`-p` 플래그)에만 적용됩니다. SDK 사용자가 백지 상태를 원할 때 유용합니다. |

144| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | SDK에서 생성한 MCP 서버의 도구 이름에서 `mcp__<server>__` 접두사를 건너뛰려면 `1`로 설정합니다. 도구는 원래 이름을 사용합니다. SDK 사용만 해당 |149| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | SDK에서 생성한 MCP 서버의 도구 이름에서 `mcp__<server>__` 접두사를 건너뛰려면 `1`로 설정합니다. 도구는 원래 이름을 사용합니다. SDK 사용만 해당 |

145| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 백그라운드 subagent의 정체 타임아웃(밀리초). 기본값 `600000`(10분). 타이머는 각 스트리밍 진행 이벤트에서 재설정됩니다. 윈도우 내에 진행이 도착하지 않으면 subagent가 중단되고 작업이 실패로 표시되며 부분 결과가 부모에게 표시됩니다. |150| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 백그라운드 subagent의 정체 타임아웃(밀리초). 기본값 `600000`(10분). 타이머는 각 스트리밍 진행 이벤트에서 재설정됩니다. 윈도우 내에 진행이 도착하지 않으면 subagent가 중단되고 작업이 실패로 표시되며 부분 결과가 부모에게 표시됩니다. |

146| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 자동 압축이 트리거되는 컨텍스트 용량의 백분율(1-100)을 설정합니다. 기본적으로 자동 압축은 약 95% 용량에서 트리거됩니다. `50`과 같은 낮은 값을 사용하여 더 일찍 압축합니다. 기본 임계값보다 높은 값은 효과가 없습니다. 대화와 subagent 모두에 적용됩니다. 백분율은 [상태 ](/ko/statusline)에서 사용 가능한 `context_window.used_percentage` 필드와 일치합니다. |151| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 자동 압축이 트리거되는 자동 압축 윈도우의 백분율(1-100)을 설정합니다. `50`과 같은 낮은 값을 사용하여 더 일찍 압축합니다. 변수는 Claude Code가 사전에 압축할 때만 일찍 압축을 유발합니다: `CLAUDE_CODE_AUTO_COMPACT_WINDOW`가 설정되었을 때, [클라우드 세션](/ko/claude-code-on-the-web)에서, [Remote Control](/ko/remote-control) 세션에서, [확장 컨텍스트](/ko/model-config#extended-context) 없이 Sonnet 4.6 Opus 4.6에서 기본적으로 200K 경계에서 압축합니다. 기본 로컬 세션과 같은 다른 경우에는 대화가 모델의 컨텍스트 제한에 도달할 때 자동 압축이 트리거됩니다. 재정의는 기본 임계값만 낮출 수 있으므로 기본값보다 높은 값은 효과가 없습니다. 주 대화와 subagent 모두에 적용됩니다. |

147| `CLAUDE_AUTO_BACKGROUND_TASKS` | 장시간 실행되는 에이전트 작업의 자동 백그라운드 처리를 강제로 활성화하려면 `1`로 설정합니다. 활성화되면 subagent는 약 2분 동안 실행한 후 백그라운드로 이동합니다. |152| `CLAUDE_AUTO_BACKGROUND_TASKS` | 장시간 실행되는 에이전트 작업의 자동 백그라운드 처리를 강제로 활성화하려면 `1`로 설정합니다. 활성화되면 subagent는 약 2분 동안 실행한 후 백그라운드로 이동합니다. |

148| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | 주 세션에서 각 Bash 또는 PowerShell 명령 후 원래 작업 디렉토리로 돌아갑니다. |153| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | 주 세션에서 각 Bash 또는 PowerShell 명령 후 원래 작업 디렉토리로 돌아갑니다. |

149| `CLAUDE_CODE_ACCESSIBILITY` | 기본 터미널 커서를 표시하고 반전된 텍스트 커서 표시기를 비활성화하려면 `1`로 설정합니다. macOS Zoom과 같은 화면 확대기가 커서 위치를 추적할 수 있습니다. |154| `CLAUDE_CODE_ACCESSIBILITY` | 기본 터미널 커서를 표시하고 반전된 텍스트 커서 표시기를 비활성화하려면 `1`로 설정합니다. macOS Zoom과 같은 화면 확대기가 커서 위치를 추적할 수 있습니다. |

150| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | `--add-dir`로 지정된 디렉토리에서 메모리 파일을 로드하려면 `1`로 설정합니다. `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md`, `CLAUDE.local.md`를 로드합니다. 기본적으로 추가 디렉토리는 메모리 파일을 로드하지 않습니다. |155| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | `--add-dir`로 지정된 디렉토리에서 메모리 파일을 로드하려면 `1`로 설정합니다. `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md`, `CLAUDE.local.md`를 로드합니다. 기본적으로 추가 디렉토리는 메모리 파일을 로드하지 않습니다. |

151| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | [전체 화면 렌더링](/ko/fullscreen)에서 증분 업데이트를 전송하는 대신 모든 프레임에서 전체 화면을 다시 칠하려면 `1`로 설정합니다. 전체 화면 모드에서 오래된 텍스트 또는 잘못된 위치의 텍스트 조각이 표시되면 이를 사용합니다. Claude Code는 Windows의 백그라운드 세션 및 [에이전트 보기](/ko/agent-view)에 대해 자동으로 이를 활성화합니다. |156| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | [전체 화면 렌더링](/ko/fullscreen)에서 증분 업데이트를 전송하는 대신 모든 프레임에서 전체 화면을 다시 칠하려면 `1`로 설정합니다. 전체 화면 모드에서 오래된 텍스트 또는 잘못된 위치의 텍스트 조각이 표시되면 이를 사용합니다. Claude Code는 Windows의 백그라운드 세션 및 [에이전트 보기](/ko/agent-view)에 대해 자동으로 이를 활성화합니다. |

157| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | Claude Code가 모델 ID를 노력 가능으로 인식하지 못할 때에도 모든 요청과 함께 [노력](/ko/model-config#adjust-effort-level) 매개변수를 전송하려면 `1`로 설정합니다. [LLM 게이트웨이](/ko/llm-gateway) 또는 사용자 정의 식별자 아래에서 모델을 제공하는 타사 공급자를 통해 라우팅할 때 사용합니다. Claude 3 모델, Sonnet 4.0 및 4.5, Opus 4.0 및 4.1, Haiku 4.5를 포함하여 API에서 노력 매개변수를 거부하는 모델은 요청이 실패하지 않도록 제외됩니다. |

152| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | 자격 증명을 새로 고쳐야 하는 간격(밀리초)([`apiKeyHelper`](/ko/settings#available-settings) 사용 시) |158| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | 자격 증명을 새로 고쳐야 하는 간격(밀리초)([`apiKeyHelper`](/ko/settings#available-settings) 사용 시) |

153| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 시스템 프롬프트의 시작 부분에서 속성 블록(클라이언트 버전 및 프롬프트 지문)을 생략하려면 `0`으로 설정합니다. 비활성화하면 [LLM 게이트웨이](/ko/llm-gateway)를 통해 라우팅할 때 프롬프트 캐시 히트율이 향상됩니다. Anthropic API 캐싱은 영향을 받지 않습니다. |159| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 시스템 프롬프트의 시작 부분에서 속성 블록(클라이언트 버전 및 프롬프트 지문)을 생략하려면 `0`으로 설정합니다. 비활성화하면 [LLM 게이트웨이](/ko/llm-gateway)를 통해 라우팅할 때 프롬프트 캐시 히트율이 향상됩니다. Anthropic API 캐싱은 영향을 받지 않습니다. |

154| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 자동 압축 계산에 사용되는 컨텍스트 용량을 토큰 단위로 설정합니다. 기본값은 모델의 컨텍스트 윈도우입니다: 표준 모델의 경우 200K 또는 [확장 컨텍스트](/ko/model-config#extended-context) 모델의 경우 1M입니다. 1M 모델에서 `500000`과 같은 낮은 값을 사용하여 압축 목적상 윈도우를 500K로 취급합니다. 값은 모델의 실제 컨텍스트 윈도우로 제한됩니다. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`는 이 값의 백분율로 적용됩니다. 이 변수를 설정하면 압축 임계값이 상태 줄의 `used_percentage`에서 분리되며, 이는 항상 모델의 전체 컨텍스트 윈도우를 사용합니다. |160| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 자동 압축 계산에 사용되는 컨텍스트 용량을 토큰 단위로 설정합니다. 기본값은 모델의 컨텍스트 윈도우입니다: 표준 모델의 경우 200K 또는 [확장 컨텍스트](/ko/model-config#extended-context) 모델의 경우 1M입니다. 1M 모델에서 `500000`과 같은 낮은 값을 사용하여 압축 목적상 윈도우를 500K로 취급합니다. 값은 모델의 실제 컨텍스트 윈도우로 제한됩니다. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`는 이 값의 백분율로 적용됩니다. 이 변수를 설정하면 압축 임계값이 상태 줄의 `used_percentage`에서 분리되며, 이는 항상 모델의 전체 컨텍스트 윈도우를 사용합니다. |

155| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 자동 [IDE 연결](/ko/vs-code)을 재정의합니다. 기본적으로 Claude Code는 지원되는 IDE의 통합 터미널 내에서 실행될 때 자동으로 연결됩니다. 이를 방지하려면 `false`로 설정합니다. tmux가 부모 터미널을 가리는 경우와 같이 자동 감지가 실패할 때 연결을 강제하려면 `true`로 설정합니다. [`autoConnectIde`](/ko/settings#global-config-settings) 전역 구성 설정보다 우선합니다. |161| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 자동 [IDE 연결](/ko/vs-code)을 재정의합니다. 기본적으로 Claude Code는 지원되는 IDE의 통합 터미널 내에서 실행될 때 자동으로 연결됩니다. 이를 방지하려면 `false`로 설정합니다. tmux가 부모 터미널을 가리는 경우와 같이 자동 감지가 실패할 때 연결을 강제하려면 `true`로 설정합니다. [`autoConnectIde`](/ko/settings#global-config-settings) 전역 구성 설정보다 우선합니다. |

156| `CLAUDE_CODE_CERT_STORE` | TLS 연결을 위한 CA 인증서 소스의 쉼표로 구분된 목록입니다. `bundled`는 Claude Code와 함께 제공되는 Mozilla CA 세트입니다. `system`은 운영 체제 신뢰 저장소입니다. 기본값은 `bundled,system`입니다. |162| `CLAUDE_CODE_CERT_STORE` | TLS 연결을 위한 CA 인증서 소스의 쉼표로 구분된 목록입니다. `bundled`는 Claude Code와 함께 제공되는 Mozilla CA 세트입니다. `system`은 운영 체제 신뢰 저장소입니다. 기본값은 `bundled,system`입니다. |

163| `CLAUDE_CODE_CHILD_SESSION` | {/* min-version: 2.1.172 */}Bash, PowerShell, Monitor 도구, [훅](/ko/hooks) 명령, [상태 줄](/ko/statusline) 명령을 통해 Claude Code가 생성하는 subprocess에서 `1`로 설정됩니다. stdio [MCP 서버](/ko/mcp) subprocess에는 설정되지 않으며, 이는 장기 실행되고 이를 생성한 세션보다 오래 지속됩니다. `CLAUDECODE`와 달리 이는 Claude Code의 자체 생성 경로에서만 설정되고 IDE 확장에서는 설정되지 않으므로 중첩 세션을 IDE 통합 터미널에서 시작된 최상위 `claude`와 안정적으로 구분합니다. 이 방식으로 시작된 중첩 대화형 `claude` TUI는 `--resume`, `--continue`, 위쪽 화살표 기록, `claude agents` 목록에서 자동으로 제외됩니다. 비대화형 `claude -p` 세션은 여전히 지속됩니다. `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1`을 설정하여 이 제외를 재정의합니다. Claude Code v2.1.172 이상이 필요합니다. |

157| `CLAUDE_CODE_CLIENT_CERT` | mTLS 인증용 클라이언트 인증서 파일의 경로 |164| `CLAUDE_CODE_CLIENT_CERT` | mTLS 인증용 클라이언트 인증서 파일의 경로 |

158| `CLAUDE_CODE_CLIENT_KEY` | mTLS 인증용 클라이언트 개인 키 파일의 경로 |165| `CLAUDE_CODE_CLIENT_KEY` | mTLS 인증용 클라이언트 개인 키 파일의 경로 |

159| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | 암호화된 CLAUDE\_CODE\_CLIENT\_KEY의 암호(선택 사항) |166| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | 암호화된 CLAUDE\_CODE\_CLIENT\_KEY의 암호(선택 사항) |

160| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 디버그 로그 파일 경로를 재정의합니다. 이름과 달리 이는 디렉토리가 아닌 파일 경로입니다. 디버그 모드를 `--debug`, `/debug`, 또는 `DEBUG` 환경 변수를 통해 별도로 활성화해야 합니다. 이 변수만 설정해도 로깅이 활성화되지 않습니다. [`--debug-file`](/ko/cli-reference#cli-flags) 플래그는 둘 다 한 번에 수행합니다. 기본값은 `~/.claude/debug/<session-id>.txt`입니다. |167| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 디버그 로그 파일 경로를 재정의합니다. 이름과 달리 이는 디렉토리가 아닌 파일 경로입니다. 디버그 모드를 `--debug`, `/debug`, 또는 `DEBUG` 환경 변수를 통해 별도로 활성화해야 합니다. 이 변수만 설정해도 로깅이 활성화되지 않습니다. [`--debug-file`](/ko/cli-reference#cli-flags) 플래그는 둘 다 한 번에 수행합니다. 기본값은 `~/.claude/debug/<session-id>.txt`입니다. |

161| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 디버그 로그 파일에 기록되는 최소 로그 수준입니다. 값: `verbose`, `debug`(기본값), `info`, `warn`, `error`. 전체 상태 줄 명령 출력과 같은 대용량 진단을 포함하려면 `verbose`로 설정하거나, 노이즈를 줄이려면 `error`로 올립니다. |168| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 디버그 로그 파일에 기록되는 최소 로그 수준입니다. 값: `verbose`, `debug`(기본값), `info`, `warn`, `error`. 전체 상태 줄 명령 출력과 같은 대용량 진단을 포함하려면 `verbose`로 설정하거나, 노이즈를 줄이려면 `error`로 올립니다. |

162| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | [1M 컨텍스트 윈도우](/ko/model-config#extended-context) 지원을 비활성화하려면 `1`로 설정합니다. 설정하면 1M 모델 변형을 모델 선택기에서 사용할 수 없습니다. 규정 준수 요구 사항이 있는 엔터프라이즈 환경에 유용합니다. |169| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | [1M 컨텍스트 윈도우](/ko/model-config#extended-context) 지원을 비활성화하려면 `1`로 설정합니다. 설정하면 1M 모델 변형을 모델 선택기에서 사용할 수 없습니다. 규정 준수 요구 사항이 있는 엔터프라이즈 환경에 유용합니다. |

163| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | Opus 4.6 및 Sonnet 4.6에 대해 [적응형 추론](/ko/model-config#adjust-effort-level)을 비활성화하려면 `1`로 설정합니다. `MAX_THINKING_TOKENS`로 제어되는 고정 사고 예산으로 돌아갑니다. v2.1.111부터 Opus 4.7 이상에는 효과가 없으며, 항상 적응형 추론을 사용합니다. |170| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | Opus 4.6 및 Sonnet 4.6에 대해 [적응형 추론](/ko/model-config#adjust-effort-level)을 비활성화하려면 `1`로 설정합니다. `MAX_THINKING_TOKENS`로 제어되는 고정 사고 예산으로 돌아갑니다. {/* min-version: 2.1.111 */}v2.1.111부터 Fable 5에는 효과가 없으며, Opus 4.7 이상에는 항상 적응형 추론을 사용합니다. |

171| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | {/* min-version: 2.1.98 */}[어드바이저 도구](/ko/advisor)를 비활성화하려면 `1`로 설정합니다. `/advisor` 명령 및 `--advisor` 플래그를 사용할 수 없게 되고 구성된 `advisorModel`은 무시됩니다. Claude Code v2.1.98 이상이 필요합니다. |

164| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | [백그라운드 에이전트 및 에이전트 보기](/ko/agent-view)를 끄려면 `1`로 설정합니다: `claude agents`, `--bg`, `/background`, 온디맨드 감독자. [`disableAgentView`](/ko/settings#available-settings) 설정과 동일합니다. |172| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | [백그라운드 에이전트 및 에이전트 보기](/ko/agent-view)를 끄려면 `1`로 설정합니다: `claude agents`, `--bg`, `/background`, 온디맨드 감독자. [`disableAgentView`](/ko/settings#available-settings) 설정과 동일합니다. |

165| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | [전체 화면 렌더링](/ko/fullscreen)을 비활성화하려면 `1`로 설정합니다. 클래식 메인 화면 렌더러를 사용합니다. 대화가 터미널의 기본 스크롤백에 남아 있으므로 `Cmd+f` 및 tmux 복사 모드가 평소처럼 작동합니다. `CLAUDE_CODE_NO_FLICKER` 및 [`tui`](/ko/settings#available-settings) 설정보다 우선합니다. `/tui default`로도 전환할 수 있습니다. [에이전트 보기](/ko/agent-view)에서 열린 백그라운드 세션에는 적용되지 않으며, 항상 전체 화면 렌더링을 사용합니다. |173| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | [전체 화면 렌더링](/ko/fullscreen)을 비활성화하려면 `1`로 설정합니다. 클래식 메인 화면 렌더러를 사용합니다. 대화가 터미널의 기본 스크롤백에 남아 있으므로 `Cmd+f` 및 tmux 복사 모드가 평소처럼 작동합니다. `CLAUDE_CODE_NO_FLICKER` 및 [`tui`](/ko/settings#available-settings) 설정보다 우선합니다. `/tui default`로도 전환할 수 있습니다. [에이전트 보기](/ko/agent-view)에서 열린 백그라운드 세션에는 적용되지 않으며, 항상 전체 화면 렌더링을 사용합니다. |

166| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | 첨부 파일 처리를 비활성화하려면 `1`로 설정합니다. `@` 구문이 있는 파일 언급은 파일 내용으로 확장되지 않고 일반 텍스트로 전송됩니다. |174| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | 첨부 파일 처리를 비활성화하려면 `1`로 설정합니다. `@` 구문이 있는 파일 언급은 파일 내용으로 확장되지 않고 일반 텍스트로 전송됩니다. |

167| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | [자동 메모리](/ko/memory#auto-memory)를 비활성화하려면 `1`로 설정합니다. `0`으로 설정하여 `--bare` 모드 또는 [`autoMemoryEnabled: false`](/ko/settings#available-settings)가 그렇지 않으면 비활성화할 때에도 자동 메모리를 강제로 켭니다. 비활성화되면 Claude는 자동 메모리 파일을 생성하거나 로드하지 않습니다. |175| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | [자동 메모리](/ko/memory#auto-memory)를 비활성화하려면 `1`로 설정합니다. `0`으로 설정하여 `--bare` 모드 또는 [`autoMemoryEnabled: false`](/ko/settings#available-settings)가 그렇지 않으면 비활성화할 때에도 자동 메모리를 강제로 켭니다. 비활성화되면 Claude는 자동 메모리 파일을 생성하거나 로드하지 않습니다. |

168| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Bash 및 subagent 도구의 `run_in_background` 매개변수, 자동 백그라운드 처리, Ctrl+B 단축키를 포함한 모든 백그라운드 작업 기능을 비활성화하려면 `1`로 설정합니다. |176| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Bash 및 subagent 도구의 `run_in_background` 매개변수, 자동 백그라운드 처리, Ctrl+B 단축키를 포함한 모든 백그라운드 작업 기능을 비활성화하려면 `1`로 설정합니다. |

177| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | Claude Code와 함께 제공되는 [skill](/ko/skills) 및 워크플로우를 비활성화하려면 `1`로 설정합니다: 번들 skill 및 워크플로우는 완전히 제거되고, `/init`과 같은 기본 제공 슬래시 명령은 입력 가능하지만 모델에서 숨겨집니다. 플러그인, `.claude/skills/`, `.claude/commands/`의 skill은 영향을 받지 않습니다. [`disableBundledSkills`](/ko/settings#available-settings) 설정과 동일합니다. `0`은 이를 재정의하지 않습니다. |

169| `CLAUDE_CODE_DISABLE_CLAUDE_MDS` | 사용자, 프로젝트, 자동 메모리 파일을 포함한 모든 CLAUDE.md 메모리 파일을 컨텍스트에 로드하지 않으려면 `1`로 설정합니다. |178| `CLAUDE_CODE_DISABLE_CLAUDE_MDS` | 사용자, 프로젝트, 자동 메모리 파일을 포함한 모든 CLAUDE.md 메모리 파일을 컨텍스트에 로드하지 않으려면 `1`로 설정합니다. |

170| `CLAUDE_CODE_DISABLE_CRON` | [예약된 작업](/ko/scheduled-tasks)을 비활성화하려면 `1`로 설정합니다. `/loop` skill과 cron 도구를 사용할 수 없게 되고 이미 예약된 모든 작업이 중지되며, 세션 중에 이미 실행 중인 작업을 포함한 모든 작업이 실행되지 않습니다. |179| `CLAUDE_CODE_DISABLE_CRON` | [예약된 작업](/ko/scheduled-tasks)을 비활성화하려면 `1`로 설정합니다. `/loop` skill과 cron 도구를 사용할 수 없게 되고 이미 예약된 모든 작업이 중지되며, 세션 중에 이미 실행 중인 작업을 포함한 모든 작업이 실행되지 않습니다. |

171| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Anthropic 특정 `anthropic-beta` 요청 헤더 및 베타 도구 스키마 필드(`defer_loading` 및 `eager_input_streaming` 등)를 API 요청에서 제거하려면 `1`로 설정합니다. 프록시 게이트웨이가 "Unexpected value(s) for the `anthropic-beta` header" 또는 "Extra inputs are not permitted"와 같은 오류로 요청을 거부할 때 사용합니다. 표준 필드(`name`, `description`, `input_schema`, `cache_control`)는 유지됩니다. |180| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Anthropic 특정 `anthropic-beta` 요청 헤더 및 베타 도구 스키마 필드(`defer_loading` 및 `eager_input_streaming` 등)를 API 요청에서 제거하려면 `1`로 설정합니다. 프록시 게이트웨이가 "Unexpected value(s) for the `anthropic-beta` header" 또는 "Extra inputs are not permitted"와 같은 오류로 요청을 거부할 때 사용합니다. 표준 필드(`name`, `description`, `input_schema`, `cache_control`)는 유지됩니다. |


180| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 첫 실행 시 공식 플러그인 마켓플레이스의 자동 추가를 건너뛰려면 `1`로 설정합니다. |189| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 첫 실행 시 공식 플러그인 마켓플레이스의 자동 추가를 건너뛰려면 `1`로 설정합니다. |

181| `CLAUDE_CODE_DISABLE_POLICY_SKILLS` | 시스템 전체 관리 skill 디렉토리에서 skill을 로드하지 않으려면 `1`로 설정합니다. 운영자가 프로비저닝한 skill을 로드하지 않아야 하는 컨테이너 또는 CI 세션에 유용합니다. |190| `CLAUDE_CODE_DISABLE_POLICY_SKILLS` | 시스템 전체 관리 skill 디렉토리에서 skill을 로드하지 않으려면 `1`로 설정합니다. 운영자가 프로비저닝한 skill을 로드하지 않아야 하는 컨테이너 또는 CI 세션에 유용합니다. |

182| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 대화 컨텍스트를 기반으로 자동 터미널 제목 업데이트를 비활성화하려면 `1`로 설정합니다. Agent SDK 및 `claude -p` 세션에서는 세션 제목을 생성하는 백그라운드 Haiku 요청도 건너뜁니다. |191| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 대화 컨텍스트를 기반으로 자동 터미널 제목 업데이트를 비활성화하려면 `1`로 설정합니다. Agent SDK 및 `claude -p` 세션에서는 세션 제목을 생성하는 백그라운드 Haiku 요청도 건너뜁니다. |

183| `CLAUDE_CODE_DISABLE_THINKING` | 모델 지원 또는 기타 설정과 관계없이 [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)를 강제로 비활성화하려면 `1` 설정합니다. `MAX_THINKING_TOKENS=0`보다 직접적입니다. |192| `CLAUDE_CODE_DISABLE_THINKING` | API 요청에서 `thinking` 매개변수를 완전히 생략하려면 `1`로 설정합니다. 이는 매개변수를 거부하는 프록시 및 게이트웨이를 위한 호환성 옵션입니다. 변수의 동작은 이전 버전과 동일합니다. 기본적으로 생각하는 모델에서 매개변수를 생략하면 모델이 여전히 생각할 수 있습니다. Anthropic API에서 [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)를 명시적으로 비활성화하려면 `MAX_THINKING_TOKENS=0` 대신 사용합니다. 이는 Fable 5에서도 효과가 없습니다. Fable 5는 사고를 끌 수 없기 때문입니다. [타사 공급자](/ko/third-party-integrations)에서 `0` 마찬가지로 매개변수를 생략하므로 두 변수는 거기서 동일하게 동작합니다. |

184| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | [전체 화면 렌더링](/ko/fullscreen)에서 가상 스크롤을 비활성화하려면 `1`로 설정합니다. 전체 화면 모드에서 스크롤이 메시지가 나타나야 할 위치에 빈 영역을 표시하면 이를 사용합니다. |193| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | [전체 화면 렌더링](/ko/fullscreen)에서 가상 스크롤을 비활성화하려면 `1`로 설정합니다. 전체 화면 모드에서 스크롤이 메시지가 나타나야 할 위치에 빈 영역을 표시하면 이를 사용합니다. |

185| `CLAUDE_CODE_DISABLE_WORKFLOWS` | [워크플로우](/ko/workflows#turn-workflows-off)를 비활성화하려면 `1`로 설정합니다. [`disableWorkflows`](/ko/settings#available-settings) 설정과 동일합니다. |194| `CLAUDE_CODE_DISABLE_WORKFLOWS` | [워크플로우](/ko/workflows#turn-workflows-off)를 비활성화하려면 `1`로 설정합니다. [`disableWorkflows`](/ko/settings#available-settings) 설정과 동일합니다. |

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

187| `CLAUDE_CODE_ENABLE_AUTO_MODE` | Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry에서 [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)를 사용 가능하게 하려면 `1`로 설정합니다. Claude Code v2.1.158 이상이 필요합니다. Anthropic API에는 효과가 없으며, 자동 모드는 기본적으로 사용 가능합니다. [Bedrock, Vertex AI 또는 Foundry에서 자동 모드 활성화](/ko/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry) 참조 |196| `CLAUDE_CODE_ENABLE_AUTO_MODE` | {/* min-version: 2.1.158 */}Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry에서 [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)를 사용 가능하게 하려면 `1`로 설정합니다. Claude Code v2.1.158 이상이 필요합니다. Anthropic API에는 효과가 없으며, 자동 모드는 기본적으로 사용 가능합니다. [Bedrock, Vertex AI 또는 Foundry에서 자동 모드 활성화](/ko/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry) 참조 |

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

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

190| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | Anthropic 바운드 비필수 트래픽이 차단될 때 "Claude가 어떻게 하고 있나요?" 세션 품질 설문조사를 자신의 [OpenTelemetry 수집기](/ko/monitoring-usage)로 라우팅하려면 `1`로 설정합니다. 설문조사 등급은 구성된 수집기에 OTEL 이벤트로만 내보내집니다. 이 모드에서는 설문조사 데이터가 Anthropic으로 전송되지 않습니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, `DISABLE_TELEMETRY`, 또는 `DO_NOT_TRACK`이 설정되었을 때 적용되며, 그렇지 않으면 효과가 없습니다. `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 및 조직 제품 피드백 정책이 우선합니다. |199| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | Anthropic 바운드 비필수 트래픽이 차단될 때 "Claude가 어떻게 하고 있나요?" 세션 품질 설문조사를 자신의 [OpenTelemetry 수집기](/ko/monitoring-usage)로 라우팅하려면 `1`로 설정합니다. 설문조사 등급은 구성된 수집기에 OTEL 이벤트로만 내보내집니다. 이 모드에서는 설문조사 데이터가 Anthropic으로 전송되지 않습니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, `DISABLE_TELEMETRY`, 또는 `DO_NOT_TRACK`이 설정되었을 때 적용되며, 그렇지 않으면 효과가 없습니다. `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 및 조직 제품 피드백 정책이 우선합니다. |

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

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

193| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | v2.1.142에서 제거됨. [빠른 모드](/ko/fast-mode) 기본적으로 Opus 4.7입니다. Opus 4.6을 유지하려면 `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1`을 설정합니다. |202| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | {/* max-version: 2.1.141 */}v2.1.142에서 제거됨. [빠른 모드](/ko/fast-mode) 기본값이 Opus 4.6에서 Opus 4.7로 이동했을 |

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

195| `CLAUDE_CODE_ENABLE_TASKS` | 세션이 구조화된 Task 도구(`TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`) 또는 레거시 `TodoWrite` 도구를 사용하는지 제어합니다. Claude Code v2.1.142부터 Task 도구는 모든 모드에서 기본값입니다. `TodoWrite`로 되돌리려면 `0`으로 설정합니다. [작업 목록](/ko/interactive-mode#task-list) 및 [Task 도구로 마이그레이션](/ko/agent-sdk/todo-tracking#migrate-to-task-tools) 참조 |204| `CLAUDE_CODE_ENABLE_TASKS` | 세션이 구조화된 Task 도구(`TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`) 또는 레거시 `TodoWrite` 도구를 사용하는지 제어합니다. {/* min-version: 2.1.142 */}Claude Code v2.1.142부터 Task 도구는 모든 모드에서 기본값입니다. `TodoWrite`로 되돌리려면 `0`으로 설정합니다. [작업 목록](/ko/interactive-mode#task-list) 및 [Task 도구로 마이그레이션](/ko/agent-sdk/todo-tracking#migrate-to-task-tools) 참조 |

196| `CLAUDE_CODE_ENABLE_TELEMETRY` | 메트릭 및 로깅을 위한 OpenTelemetry 데이터 수집을 활성화하려면 `1`로 설정합니다. OTel 내보내기를 구성하기 전에 필수입니다. [모니터링](/ko/monitoring-usage) 참조 |205| `CLAUDE_CODE_ENABLE_TELEMETRY` | 메트릭 및 로깅을 위한 OpenTelemetry 데이터 수집을 활성화하려면 `1`로 설정합니다. OTel 내보내기를 구성하기 전에 필수입니다. [모니터링](/ko/monitoring-usage) 참조 |

197| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | 쿼리 루프가 유휴 상태가 된 후 자동으로 종료되기 전에 대기할 시간(밀리초). SDK 모드를 사용하는 자동화된 워크플로우 및 스크립트에 유용합니다. |206| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | 쿼리 루프가 유휴 상태가 된 후 자동으로 종료되기 전에 대기할 시간(밀리초). SDK 모드를 사용하는 자동화된 워크플로우 및 스크립트에 유용합니다. |

198| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | [에이전트 팀](/ko/agent-teams)을 활성화하려면 `1`로 설정합니다. 에이전트 팀은 실험적이며 기본적으로 비활성화됩니다. |207| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | [에이전트 팀](/ko/agent-teams)을 활성화하려면 `1`로 설정합니다. 에이전트 팀은 실험적이며 기본적으로 비활성화됩니다. |

199| `CLAUDE_CODE_EXTRA_BODY` | 모든 API 요청 본문의 최상위 수준으로 병합할 JSON 객체입니다. Claude Code가 직접 노출하지 않는 공급자 특정 매개변수를 전달하는 데 유용합니다. |208| `CLAUDE_CODE_EXTRA_BODY` | 모든 API 요청 본문의 최상위 수준으로 병합할 JSON 객체입니다. Claude Code가 직접 노출하지 않는 공급자 특정 매개변수를 전달하는 데 유용합니다. |

200| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | 파일 읽기의 기본 토큰 제한을 재정의합니다. 전체 파일을 읽어야 할 때 유용합니다. |209| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | 파일 읽기의 기본 토큰 제한을 재정의합니다. 전체 파일을 읽어야 할 때 유용합니다. |

210| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | {/* min-version: 2.1.172 */}이 `claude`가 다른 Claude Code 세션 내부에서 시작되었을 때에도 트랜스크립트 지속성, 프롬프트 기록, `claude agents` 등록을 강제하려면 `1`로 설정합니다. 예를 들어 Claude Code의 Bash 도구에서 처음 시작된 tmux 서버에서 상속된 `CLAUDE_CODE_CHILD_SESSION` 값이 진정한 최상위 세션을 중첩으로 잘못 분류할 때 사용합니다. v2.1.169 이상에서도 인정됩니다. v2.1.170 및 v2.1.171에서는 효과가 없으며, 이를 재정의한 중첩 세션 감지가 제거되었습니다. |

201| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 터미널이 지원하지만 자동 감지되지 않을 때 DEC 개인 모드 2026 [동기화된 출력](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)을 강제로 활성화하려면 `1`로 설정합니다. Emacs `eat`과 같은 BSU/ESU를 구현하지만 기능 프로브에 응답하지 않는 에뮬레이터에 유용합니다. tmux에서는 효과가 없습니다. |211| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 터미널이 지원하지만 자동 감지되지 않을 때 DEC 개인 모드 2026 [동기화된 출력](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)을 강제로 활성화하려면 `1`로 설정합니다. Emacs `eat`과 같은 BSU/ESU를 구현하지만 기능 프로브에 응답하지 않는 에뮬레이터에 유용합니다. tmux에서는 효과가 없습니다. |

202| `CLAUDE_CODE_FORK_SUBAGENT` | [포크된 subagent](/ko/sub-agents#fork-the-current-conversation)를 모델의 기본값으로 만들려면 `1`로 설정합니다. Claude는 일반 목적 subagent를 사용하는 대신 포크를 생성합니다. 포크는 새로 시작하는 대신 전체 대화 컨텍스트를 상속하는 subagent이며, 모든 subagent 생성은 백그라운드에서 실행됩니다. 명시적 [`/fork`](/ko/commands) 명령은 이 변수 없이도 작동합니다. 대화형 모드와 SDK 또는 `claude -p`를 통해 작동합니다. |212| `CLAUDE_CODE_FORK_SUBAGENT` | [포크된 subagent](/ko/sub-agents#fork-the-current-conversation)를 모델의 기본값으로 만들려면 `1`로 설정하거나, 비활성화하려면 `0`으로 설정합니다. 서버 측 롤아웃을 재정의합니다. 활성화되면 Claude는 일반 목적 subagent를 사용하는 대신 포크를 생성합니다. 포크는 새로 시작하는 대신 전체 대화 컨텍스트를 상속하는 subagent이며, 모든 subagent 생성은 백그라운드에서 실행됩니다. 명시적 [`/fork`](/ko/commands) 명령은 이 변수 없이도 작동합니다. 대화형 모드와 SDK 또는 `claude -p`를 통해 작동합니다. |

203| `CLAUDE_CODE_GIT_BASH_PATH` | Windows 전용: Git Bash 실행 파일(`bash.exe`)의 경로입니다. Git Bash가 설치되었지만 PATH에 없을 때 사용합니다. [Windows 설정](/ko/setup#set-up-on-windows) 참조 |213| `CLAUDE_CODE_GIT_BASH_PATH` | Windows 전용: Git Bash 실행 파일(`bash.exe`)의 경로입니다. Git Bash가 설치되었지만 PATH에 없을 때 사용합니다. [Windows 설정](/ko/setup#set-up-on-windows) 참조 |

204| `CLAUDE_CODE_GLOB_HIDDEN` | Claude가 [Glob 도구](/ko/tools-reference#glob-tool-behavior)를 호출할 때 결과에서 dotfile을 제외하려면 `false`로 설정합니다. 기본적으로 포함됩니다. `@` 파일 자동 완성, `ls`, Grep 또는 Read에는 영향을 주지 않습니다. |214| `CLAUDE_CODE_GLOB_HIDDEN` | Claude가 [Glob 도구](/ko/tools-reference#glob-tool-behavior)를 호출할 때 결과에서 dotfile을 제외하려면 `false`로 설정합니다. 기본적으로 포함됩니다. `@` 파일 자동 완성, `ls`, Grep 또는 Read에는 영향을 주지 않습니다. |

205| `CLAUDE_CODE_GLOB_NO_IGNORE` | [Glob 도구](/ko/tools-reference#glob-tool-behavior)가 `.gitignore` 패턴을 존중하도록 하려면 `false`로 설정합니다. 기본적으로 Glob은 gitignored된 파일을 포함한 모든 일치하는 파일을 반환합니다. `@` 파일 자동 완성에는 영향을 주지 않으며, 이는 자체 [`respectGitignore` 설정](/ko/settings#available-settings)을 가집니다. |215| `CLAUDE_CODE_GLOB_NO_IGNORE` | [Glob 도구](/ko/tools-reference#glob-tool-behavior)가 `.gitignore` 패턴을 존중하도록 하려면 `false`로 설정합니다. 기본적으로 Glob은 gitignored된 파일을 포함한 모든 일치하는 파일을 반환합니다. `@` 파일 자동 완성에는 영향을 주지 않으며, 이는 자체 [`respectGitignore` 설정](/ko/settings#available-settings)을 가집니다. |


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

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

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

223| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | v2.1.160에서 제거되었으며 이제 작동하지 않습니다. 이전에는 [빠른 모드](/ko/fast-mode)를 Claude Opus 4.6에 고정했습니다. Opus 4.6이 폐기될 때까지 Opus 4.6에서 빠른 모드를 실행하려면 먼저 `/model`로 모델을 선택한 다음 `/fast on`을 실행합니다. |233| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | {/* max-version: 2.1.159 */}v2.1.160에서 제거되었으며 이제 작동하지 않습니다. 이전에는 [빠른 모드](/ko/fast-mode)를 Claude Opus 4.6에 고정했습니다. Opus 4.6이 폐기될 때까지 Opus 4.6에서 빠른 모드를 실행하려면 먼저 `/model`로 모델을 선택한 다음 `/fast on`을 실행합니다. |

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

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

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


232| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | GitHub `owner/repo` 플러그인 소스를 SSH 대신 HTTPS를 통해 복제하려면 `1`로 설정합니다. CI 러너, 컨테이너 또는 `github.com`에 대해 구성된 SSH 키가 없는 모든 환경에서 유용합니다. |242| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | GitHub `owner/repo` 플러그인 소스를 SSH 대신 HTTPS를 통해 복제하려면 `1`로 설정합니다. CI 러너, 컨테이너 또는 `github.com`에 대해 구성된 SSH 키가 없는 모든 환경에서 유용합니다. |

233| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 하나 이상의 읽기 전용 플러그인 시드 디렉토리의 경로이며, Unix에서는 `:`로, Windows에서는 `;`로 구분됩니다. 이를 사용하여 사전 채워진 플러그인 디렉토리를 컨테이너 이미지에 번들로 제공합니다. Claude Code는 시작 시 이러한 디렉토리에서 마켓플레이스를 등록하고 다시 복제하지 않고 사전 캐시된 플러그인을 사용합니다. [컨테이너용 플러그인 사전 채우기](/ko/plugin-marketplaces#pre-populate-plugins-for-containers) 참조 |243| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 하나 이상의 읽기 전용 플러그인 시드 디렉토리의 경로이며, Unix에서는 `:`로, Windows에서는 `;`로 구분됩니다. 이를 사용하여 사전 채워진 플러그인 디렉토리를 컨테이너 이미지에 번들로 제공합니다. Claude Code는 시작 시 이러한 디렉토리에서 마켓플레이스를 등록하고 다시 복제하지 않고 사전 캐시된 플러그인을 사용합니다. [컨테이너용 플러그인 사전 채우기](/ko/plugin-marketplaces#pre-populate-plugins-for-containers) 참조 |

234| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | Claude Code가 PowerShell을 생성할 때 `-ExecutionPolicy Bypass`를 전달하지 않으려면 `1`로 설정합니다. 도구 호출, 훅, 상태 줄 명령의 경우 대신 머신의 효과적인 실행 정책을 존중합니다. 기본적으로 Claude Code는 프로세스 범위에서 실행 정책을 우회하므로 `.ps1` 스크립트 및 모듈 가져오기가 기본 제한 Windows 설치에서 작동합니다. 프로세스 범위 우회는 이 설정과 관계없이 Group Policy `MachinePolicy` 또는 `UserPolicy`를 재정의하지 않습니다. |244| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | Claude Code가 PowerShell을 생성할 때 `-ExecutionPolicy Bypass`를 전달하지 않으려면 `1`로 설정합니다. 도구 호출, 훅, 상태 줄 명령의 경우 대신 머신의 효과적인 실행 정책을 존중합니다. 기본적으로 Claude Code는 프로세스 범위에서 실행 정책을 우회하므로 `.ps1` 스크립트 및 모듈 가져오기가 기본 제한 Windows 설치에서 작동합니다. 프로세스 범위 우회는 이 설정과 관계없이 Group Policy `MachinePolicy` 또는 `UserPolicy`를 재정의하지 않습니다. |

235| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | `ANTHROPIC_BASE_URL`이 사용자 정의 프록시를 가리킬 때 W3C 추적 컨텍스트를 전파하려면 `1`로 설정합니다. 전파는 모델 및 HTTP MCP 요청의 `traceparent` 헤더와 Bash, PowerShell, 훅 subprocess의 `TRACEPARENT` 환경 변수를 포함합니다. 기본적으로 전파는 Anthropic API에 직접 연결할 때만 활성화됩니다. v2.1.152에서 추가됨. [추적(베타)](/ko/monitoring-usage#traces-beta) 참조 |245| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | {/* min-version: 2.1.152 */}}`ANTHROPIC_BASE_URL`이 사용자 정의 프록시를 가리킬 때 W3C 추적 컨텍스트를 전파하려면 `1`로 설정합니다. 전파는 모델 및 HTTP MCP 요청의 `traceparent` 헤더와 Bash, PowerShell, 훅 subprocess의 `TRACEPARENT` 환경 변수를 포함합니다. 기본적으로 전파는 Anthropic API에 직접 연결할 때만 활성화됩니다. v2.1.152에서 추가됨. [추적(베타)](/ko/monitoring-usage#traces-beta) 참조 |

236| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | Claude Code를 포함하고 대신 모델 공급자 라우팅을 관리하는 호스트 플랫폼에서 설정합니다. 설정하면 설정 파일의 `CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY`와 같은 공급자 선택, 엔드포인트, 인증 변수가 무시되므로 사용자 설정이 호스트의 라우팅을 재정의할 수 없습니다. Bedrock, Vertex, Foundry에 대한 자동 원격 분석 옵트아웃도 건너뛰므로 원격 분석은 표준 `DISABLE_TELEMETRY` 옵트아웃을 따릅니다. [API 공급자별 기본 동작](/ko/data-usage#default-behaviors-by-api-provider) 참조 |246| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | Claude Code를 포함하고 대신 모델 공급자 라우팅을 관리하는 호스트 플랫폼에서 설정합니다. 설정하면 설정 파일의 `CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY`와 같은 공급자 선택, 엔드포인트, 인증 변수가 무시되므로 사용자 설정이 호스트의 라우팅을 재정의할 수 없습니다. Bedrock, Vertex, Foundry에 대한 자동 원격 분석 옵트아웃도 건너뛰므로 원격 분석은 표준 `DISABLE_TELEMETRY` 옵트아웃을 따릅니다. [API 공급자별 기본 동작](/ko/data-usage#default-behaviors-by-api-provider) 참조 |

237| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | 호출자 대신 프록시가 DNS 해석을 수행하도록 허용하려면 `1`로 설정합니다. 프록시가 호스트명 해석을 처리해야 하는 환경에 대해 옵트인합니다. |247| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | 호출자 대신 프록시가 DNS 해석을 수행하도록 허용하려면 `1`로 설정합니다. 프록시가 호스트명 해석을 처리해야 하는 환경에 대해 옵트인합니다. |

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

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

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

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

252| `CLAUDE_CODE_SAFE_MODE` | 안전 모드에서 시작하려면 `1`로 설정합니다: CLAUDE.md, skill, 플러그인, 훅, MCP 서버, 사용자 정의 명령 및 에이전트, 출력 스타일, 워크플로우, 사용자 정의 테마, 사용자 정의 키 바인딩, 상태 줄 및 파일 제안 명령, LSP 서버, 자동 메모리는 로드되지 않습니다. 손상된 구성을 문제 해결하기 위해. 관리 설정 정책은 여전히 적용되며, 정책 구성 훅, 상태 줄, 파일 제안 명령을 포함합니다. 관리 플러그인, 관리 skill, 관리 CLAUDE.md, 정책 구성 MCP 서버는 로드되지 않습니다. [`--safe-mode`](/ko/cli-reference#cli-flags) 전달과 동일합니다. 직접 생성된 자식 프로세스는 변수를 상속합니다. |

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

243| `CLAUDE_CODE_SCROLL_SPEED` | [전체 화면 렌더링](/ko/fullscreen#mouse-wheel-scrolling)에서 마우스 휠 스크롤 배수를 설정합니다. 1부터 20까지의 값을 허용합니다. 터미널이 증폭 없이 노치당 하나의 휠 이벤트를 보내는 경우 `vim`과 일치하도록 `3`으로 설정합니다. JetBrains IDE 터미널에서는 무시되며, Claude Code는 자체 스크롤 처리를 사용합니다. |254| `CLAUDE_CODE_SCROLL_SPEED` | [전체 화면 렌더링](/ko/fullscreen#mouse-wheel-scrolling)에서 마우스 휠 스크롤 배수를 설정합니다. 1부터 20까지의 값을 허용합니다. 그리고 `0.5`와 같은 1 미만의 분수 값을 허용하여 터미널의 기본 스크롤 경로에서 가속 트랙패드 및 휠 스크롤을 느리게 합니다. 터미널이 증폭 없이 노치당 하나의 휠 이벤트를 보내는 경우 `vim`과 일치하도록 `3`으로 설정합니다. JetBrains IDE 터미널에서는 무시되며, Claude Code는 자체 스크롤 처리를 사용합니다. |

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

245| `CLAUDE_CODE_SESSION_ID` | Bash 및 PowerShell 도구 subprocess에서 현재 세션 ID로 자동으로 설정됩니다. [훅](/ko/hooks) 명령 subprocess 및 stdio [MCP 서버](/ko/mcp) subprocess에서도 설정됩니다. [훅](/ko/hooks)에 전달된 `session_id` 필드와 일치합니다. `/clear`에서 업데이트됩니다. MCP 서버 subprocess는 생성될 때 ID를 유지하며, `--resume` 또는 `--continue` 통해 실행될 초기 시작 ID 대신 재개된 ID를 받을 수 있습니다. 스크립트 및 외부 도구를 Claude Code 세션과 연관시키는 데 사용합니다. |256| `CLAUDE_CODE_SESSION_ID` | Bash 및 PowerShell 도구 subprocess에서 현재 세션 ID로 자동으로 설정됩니다. [훅](/ko/hooks) 명령 subprocess 및 stdio [MCP 서버](/ko/mcp) subprocess에서도 설정됩니다. [훅](/ko/hooks)에 전달된 `session_id` 필드와 일치합니다. `/clear`에서 업데이트됩니다. MCP 서버 subprocess는 생성될 때 ID를 유지하며, `--resume <session-id>`에서 재개된 ID를 받습니다. `--continue` 또는 명시적 ID 없이 `--resume`에서 초기 시작 ID를 받을 수 있습니다. 스크립트 및 외부 도구를 Claude Code 세션과 연관시키는 데 사용합니다. |

246| `CLAUDE_CODE_SHELL` | 자동 셸 감지를 재정의합니다. 로그인 셸이 선호하는 작업 셸과 다를 때 유용합니다(예: `bash` vs `zsh`). |257| `CLAUDE_CODE_SHELL` | 자동 셸 감지를 재정의합니다. 로그인 셸이 선호하는 작업 셸과 다를 때 유용합니다(예: `bash` vs `zsh`). |

247| `CLAUDE_CODE_SHELL_PREFIX` | Claude Code가 생성하는 모든 셸 명령을 래핑할 명령 접두사: Bash 도구 호출, [훅](/ko/hooks) 명령, stdio [MCP 서버](/ko/mcp) 시작 명령. 로깅 또는 감사에 유용합니다. 예: `/path/to/logger.sh` 설정하면 각 명령을 `/path/to/logger.sh <command>`로 실행합니다. |258| `CLAUDE_CODE_SHELL_PREFIX` | Claude Code가 생성하는 모든 셸 명령을 래핑할 명령 접두사: Bash 도구 호출, [훅](/ko/hooks) 명령, [상태 줄](/ko/statusline) 명령, stdio [MCP 서버](/ko/mcp) 시작 명령. PowerShell 훅 및 exec 형식 훅은 접두사 없이 실행됩니다. 로깅 또는 감사에 유용합니다. 예: `/path/to/logger.sh` 같은 실행 파일 경로를 설정하면 각 명령을 `/path/to/logger.sh '<command>'`로 실행합니다. 래퍼는 명령줄을 `$1`의 단일 셸 인용 인수로 받으므로 래퍼는 `$1`을 셸로 다시 평가해야 합니다(예: `exec bash -c "$1"`). `$1`을 실행 파일 경로로 취급하면 `npx -y <package>`와 같은 인수를 전달하는 stdio MCP 서버가 손상됩니다. Bash 도구 호출의 경우 `$1`에는 Claude Code가 조립하는 전체 셸 호출이 포함되며, Claude가 실행한 명령만이 아닙니다. |

248| `CLAUDE_CODE_SIMPLE` | 최소 시스템 프롬프트 및 Bash, 파일 읽기, 파일 편집 도구만으로 실행하려면 `1`로 설정합니다. `--mcp-config`의 MCP 도구는 계속 사용 가능합니다. 훅, skill, 플러그인, MCP 서버, 자동 메모리, CLAUDE.md의 자동 검색을 비활성화합니다. OAuth 토큰 및 키체인 자격 증명은 읽지 않으므로 Anthropic 인증은 `ANTHROPIC_API_KEY` 또는 `--settings`의 `apiKeyHelper`에서 와야 합니다. [`--bare`](/ko/headless#start-faster-with-bare-mode) 전달과 동일합니다. |259| `CLAUDE_CODE_SIMPLE` | 최소 시스템 프롬프트 및 Bash, 파일 읽기, 파일 편집 도구만으로 실행하려면 `1`로 설정합니다. `--mcp-config`의 MCP 도구는 계속 사용 가능합니다. 훅, skill, 플러그인, MCP 서버, 자동 메모리, CLAUDE.md의 자동 검색을 비활성화합니다. OAuth 토큰 및 키체인 자격 증명은 읽지 않으므로 Anthropic 인증은 `ANTHROPIC_API_KEY` 또는 `--settings`의 `apiKeyHelper`에서 와야 합니다. [`--bare`](/ko/headless#start-faster-with-bare-mode) 전달과 동일합니다. |

249| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 모든 모델에서 더 짧은 시스템 프롬프트 및 축소된 도구 설명을 사용하려면 `1`로 설정합니다. `0`, `false`, `no`, 또는 `off`로 설정하여 실험 또는 서버 구성이 그렇지 않으면 활성화할 때에도 옵트아웃합니다. 전체 도구 세트, 훅, MCP 서버, CLAUDE.md 검색은 계속 활성화됩니다. |260| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 모든 모델에서 더 짧은 시스템 프롬프트 및 축소된 도구 설명을 사용하려면 `1`로 설정합니다. `0`, `false`, `no`, 또는 `off`로 설정하여 실험 또는 서버 구성이 그렇지 않으면 활성화할 때에도 옵트아웃합니다. 전체 도구 세트, 훅, MCP 서버, CLAUDE.md 검색은 계속 활성화됩니다. |

250| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | [Claude Platform on AWS](/ko/claude-platform-on-aws)에 대한 클라이언트 측 인증을 건너뜁니다. 게이트웨이가 요청에 자체 서명하는 경우 |261| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | [Claude Platform on AWS](/ko/claude-platform-on-aws)에 대한 클라이언트 측 인증을 건너뜁니다. 게이트웨이가 요청에 자체 서명하는 경우 |


258| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Anthropic 및 클라우드 공급자 자격 증명을 subprocess 환경(Bash 도구, 훅, MCP stdio 서버)에서 제거하려면 `1`로 설정합니다. 부모 Claude 프로세스는 API 호출을 위해 이러한 자격 증명을 유지하지만 자식 프로세스는 이를 읽을 수 없으므로 셸 확장을 통해 비밀을 유출하려는 프롬프트 주입 공격에 대한 노출을 줄입니다. Linux에서는 Bash subprocess를 격리된 PID 네임스페이스에서도 실행하므로 `/proc`을 통해 호스트 프로세스 환경을 읽을 수 없습니다. 부작용으로 `ps`, `pgrep`, `kill`은 호스트 프로세스를 보거나 신호할 수 없습니다. `allowed_non_write_users`가 구성되면 `claude-code-action`이 자동으로 이를 설정합니다. |269| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Anthropic 및 클라우드 공급자 자격 증명을 subprocess 환경(Bash 도구, 훅, MCP stdio 서버)에서 제거하려면 `1`로 설정합니다. 부모 Claude 프로세스는 API 호출을 위해 이러한 자격 증명을 유지하지만 자식 프로세스는 이를 읽을 수 없으므로 셸 확장을 통해 비밀을 유출하려는 프롬프트 주입 공격에 대한 노출을 줄입니다. Linux에서는 Bash subprocess를 격리된 PID 네임스페이스에서도 실행하므로 `/proc`을 통해 호스트 프로세스 환경을 읽을 수 없습니다. 부작용으로 `ps`, `pgrep`, `kill`은 호스트 프로세스를 보거나 신호할 수 없습니다. `allowed_non_write_users`가 구성되면 `claude-code-action`이 자동으로 이를 설정합니다. |

259| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 비대화형 모드(`-p` 플래그)에서 첫 번째 쿼리 전에 플러그인 설치가 완료될 때까지 대기하려면 `1`로 설정합니다. 이 없으면 플러그인이 백그라운드에서 설치되고 첫 번째 턴에서 사용하지 못할 수 있습니다. `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS`와 결합하여 대기를 제한합니다. |270| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 비대화형 모드(`-p` 플래그)에서 첫 번째 쿼리 전에 플러그인 설치가 완료될 때까지 대기하려면 `1`로 설정합니다. 이 없으면 플러그인이 백그라운드에서 설치되고 첫 번째 턴에서 사용하지 못할 수 있습니다. `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS`와 결합하여 대기를 제한합니다. |

260| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 동기 플러그인 설치의 타임아웃(밀리초). 초과되면 Claude Code는 플러그인 없이 진행하고 오류를 기록합니다. 기본값 없음: 이 변수가 없으면 동기 설치는 완료될 때까지 대기합니다. |271| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 동기 플러그인 설치의 타임아웃(밀리초). 초과되면 Claude Code는 플러그인 없이 진행하고 오류를 기록합니다. 기본값 없음: 이 변수가 없으면 동기 설치는 완료될 때까지 대기합니다. |

261| `CLAUDE_CODE_SYNC_SKILLS` | `CLAUDE_CODE_SYNC_SKILLS`이 설정되었을 때 비대화형 모드(`-p` 플래그)에서 첫 번째 쿼리 전에 활성화된 claude.ai skill을 `~/.claude/skills/`로 다운로드하고 10분마다 재동기화하려면 `1`로 설정합니다. [Claude Code on the web](/ko/claude-code-on-the-web) 세션에서 자동으로 설정됩니다. claude.ai 인증이 필요합니다. |272| `CLAUDE_CODE_SYNC_SKILLS` | `CLAUDE_CODE_SYNC_SKILLS`이 설정되었을 때 비대화형 모드(`-p` 플래그)에서 첫 번째 쿼리 전에 활성화된 claude.ai skill을 `~/.claude/skills/`로 다운로드하고 10분마다 재동기화하려면 `1`로 설정합니다. claude.ai 인증이 필요합니다. [Claude Code on the web](/ko/claude-code-on-the-web) 세션에서 자동으로 설정됩니다. |

273| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | `CLAUDE_CODE_SYNC_SKILLS`이 설정되었을 때 호스트가 세션 중에 skill 다시 로드를 요청할 때 중간 skill 재동기화의 타임아웃(밀리초)(기본값: 30000). 대기를 제한합니다. 초과되면 재동기화가 중지되고 남은 다운로드는 백그라운드에서 계속됩니다. |

262| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | `CLAUDE_CODE_SYNC_SKILLS`이 설정되었을 때 첫 번째 쿼리가 초기 skill 동기화를 기다리는 시간(밀리초)(기본값: 5000). 초과되면 쿼리가 진행되고 남은 skill 다운로드는 백그라운드에서 계속됩니다. |274| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | `CLAUDE_CODE_SYNC_SKILLS`이 설정되었을 때 첫 번째 쿼리가 초기 skill 동기화를 기다리는 시간(밀리초)(기본값: 5000). 초과되면 쿼리가 진행되고 남은 skill 다운로드는 백그라운드에서 계속됩니다. |

263| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | diff 출력에서 구문 강조를 비활성화하려면 `false`로 설정합니다. 색상이 터미널 설정을 방해할 때 유용합니다. 코드 블록 및 파일 미리보기에서 강조를 비활성화하려면 [`syntaxHighlightingDisabled`](/ko/settings) 설정을 사용합니다. |275| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | diff 출력에서 구문 강조를 비활성화하려면 `false`로 설정합니다. 색상이 터미널 설정을 방해할 때 유용합니다. 코드 블록 및 파일 미리보기에서 강조를 비활성화하려면 [`syntaxHighlightingDisabled`](/ko/settings) 설정을 사용합니다. |

264| `CLAUDE_CODE_TASK_LIST_ID` | 세션 간에 작업 목록을 공유합니다. 여러 Claude Code 인스턴스에서 동일한 ID를 설정하여 공유 작업 목록에서 조정합니다. [작업 목록](/ko/interactive-mode#task-list) 참조 |276| `CLAUDE_CODE_TASK_LIST_ID` | 세션 간에 작업 목록을 공유합니다. 여러 Claude Code 인스턴스에서 동일한 ID를 설정하여 공유 작업 목록에서 조정합니다. [작업 목록](/ko/interactive-mode#task-list) 참조 |

265| `CLAUDE_CODE_TEAM_NAME` | 이 팀원이 속한 에이전트 팀의 이름입니다. [에이전트 팀](/ko/agent-teams) 멤버에서 자동으로 설정됩니다. |277| `CLAUDE_CODE_TEAM_NAME` | 이 팀원이 속한 에이전트 팀의 이름입니다. [에이전트 팀](/ko/agent-teams) 멤버에서 자동으로 설정됩니다. |

266| `CLAUDE_CODE_TMPDIR` | 내부 임시 파일에 사용되는 임시 디렉토리를 재정의합니다. Claude Code는 이 경로에 `/claude-{uid}/`(Unix) 또는 `/claude/`(Windows)를 추가합니다. 기본값: macOS의 경우 `/tmp`, Linux/Windows의 경우 `os.tmpdir()`. v2.1.161부터 macOS 및 Linux에서 Bash subprocess는 경로가 너무 길어지면 일부 도구가 실패하므로 시스템 기본값 아래에 짧은 폴백 `$TMPDIR`을 받습니다. Claude Code의 자체 임시 파일은 항상 재정의를 사용합니다. |278| `CLAUDE_CODE_TMPDIR` | 내부 임시 파일에 사용되는 임시 디렉토리를 재정의합니다. Claude Code는 이 경로에 `/claude-{uid}/`(Unix) 또는 `/claude/`(Windows)를 추가합니다. 기본값: macOS의 경우 `/tmp`, Linux/Windows의 경우 `os.tmpdir()`. {/* min-version: 2.1.161 */}v2.1.161부터 macOS 및 Linux에서 [샌드박스](/ko/sandboxing) Bash subprocess는 경로가 너무 길어지면 일부 도구가 실패하므로 시스템 기본값 아래에 짧은 폴백 `$TMPDIR`을 받습니다. 샌드박스되지 않은 Bash 명령은 셸의 `$TMPDIR`을 변경되지 않고 상속합니다. Claude Code의 자체 임시 파일은 항상 재정의를 사용합니다. |

267| `CLAUDE_CODE_TMUX_TRUECOLOR` | tmux 내에서 24비트 truecolor 출력을 허용하려면 `1`로 설정합니다. 기본적으로 `$TMUX`가 설정되면 Claude Code는 256색으로 제한합니다. tmux는 구성되지 않으면 truecolor 이스케이프 시퀀스를 통과하지 않기 때문입니다. `~/.tmux.conf`에 `set -ga terminal-overrides ',*:Tc'`를 추가한 후 이를 설정합니다. [터미널 구성](/ko/terminal-config)에서 다른 tmux 설정을 참조합니다. |279| `CLAUDE_CODE_TMUX_TRUECOLOR` | tmux 내에서 24비트 truecolor 출력을 허용하려면 `1`로 설정합니다. 기본적으로 `$TMUX`가 설정되면 Claude Code는 256색으로 제한합니다. tmux는 구성되지 않으면 truecolor 이스케이프 시퀀스를 통과하지 않기 때문입니다. `~/.tmux.conf`에 `set -ga terminal-overrides ',*:Tc'`를 추가한 후 이를 설정합니다. [터미널 구성](/ko/terminal-config)에서 다른 tmux 설정을 참조합니다. |

268| `CLAUDE_CODE_USE_ANTHROPIC_AWS` | [Claude Platform on AWS](/ko/claude-platform-on-aws) 사용 |280| `CLAUDE_CODE_USE_ANTHROPIC_AWS` | [Claude Platform on AWS](/ko/claude-platform-on-aws) 사용 |

269| `CLAUDE_CODE_USE_BEDROCK` | [Bedrock](/ko/amazon-bedrock) 사용 |281| `CLAUDE_CODE_USE_BEDROCK` | [Bedrock](/ko/amazon-bedrock) 사용 |


274| `CLAUDE_CODE_USE_VERTEX` | [Vertex](/ko/google-vertex-ai) 사용 |286| `CLAUDE_CODE_USE_VERTEX` | [Vertex](/ko/google-vertex-ai) 사용 |

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

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

277| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 바이트 수준 스트리밍 유휴 감시견을 강제로 활성화하려면 `1`로 설정하거나, 강제로 비활성화하려면 `0`으로 설정합니다. 설정하지 않으면 감시견은 Anthropic API 연결에 대해 기본적으로 활성화됩니다. 바이트 감시견은 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 설정된 기간 동안 와이어에 바이트가 도착하지 않으면 연결을 중단합니다. 최소 5분이며 이벤트 수준 감시견과 독립적입니다. |289| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 바이트 수준 스트리밍 유휴 감시견을 강제로 활성화하려면 `1`로 설정하거나, 강제로 비활성화하려면 `0`으로 설정합니다. 설정하지 않으면 감시견은 직접 Anthropic API 및 [Claude Platform on AWS](/ko/claude-platform-on-aws) 연결에 대해 기본적으로 활성화됩니다. 바이트 감시견은 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 설정된 기간 동안 와이어에 바이트가 도착하지 않으면 연결을 중단합니다. 최소 5분이며 이벤트 수준 감시견과 독립적입니다. |

278| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | Amazon Bedrock `vnd.amazon.eventstream` 응답에서 바이트 수준 스트리밍 유휴 감시견을 활성화하려면 `1`로 설정합니다. 기본적으로 꺼져 있습니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 타임아웃을 구성합니다. |290| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | Amazon Bedrock `vnd.amazon.eventstream` 응답에서 바이트 수준 스트리밍 유휴 감시견을 활성화하려면 `1`로 설정합니다. 기본적으로 꺼져 있습니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 타임아웃을 구성합니다. |

279| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 이벤트 수준 스트리밍 유휴 감시견을 활성화하려면 `1`로 설정합니다. 기본적으로 꺼져 있습니다. 모든 공급자에 적용됩니다(Bedrock 포함). VertexFoundry의 경우 이것이 유일한 유휴 감시견입니다. Bedrock에서는 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK`으로 독립적인 바이트 수준 감시견을 활성화할 수도 있습니다. 둘 다 설정하면 함께 실행됩니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 타임아웃을 구성합니다. |291| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 이벤트 수준 스트리밍 유휴 감시견을 강제로 활성화하려면 `1`로 설정하거나, 강제로 비활성화하려면 `0`으로 설정합니다. 설정하지 않으면 기본값은 직접 Anthropic API에서 서버 제어이고 다른 공급자에서는 꺼져 있습니다. {/* min-version: 2.1.169 */}v2.1.169부터 직접 Anthropic API Claude Platform on AWS 이외의 공급자도 `API_FORCE_IDLE_TIMEOUT`에 설명된 독립적인 5분 본문 유휴 타임아웃을 가집니다. Bedrock에서는 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` 독립적인 바이트 수준 감시견을 활성화할 수도 있습니다. 둘 다 설정하면 함께 실행됩니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 타임아웃을 구성합니다. |

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

281| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 명시적 이름이 제공되지 않을 때 자동 생성된 [Remote Control](/ko/remote-control) 세션 이름의 접두사입니다. 기본값은 머신의 호스트명이며, `myhost-graceful-unicorn`과 같은 이름을 생성합니다. `--remote-control-session-name-prefix` CLI 플래그는 단일 호출에 대해 동일한 값을 설정합니다. |293| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 명시적 이름이 제공되지 않을 때 자동 생성된 [Remote Control](/ko/remote-control) 세션 이름의 접두사입니다. 기본값은 머신의 호스트명이며, `myhost-graceful-unicorn`과 같은 이름을 생성합니다. `--remote-control-session-name-prefix` CLI 플래그는 단일 호출에 대해 동일한 값을 설정합니다. |

282| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 스트리밍 유휴 감시견이 정체된 연결을 닫기 전의 타임아웃(밀리초). 바이트 수준 이벤트 수준 감시견 모두에 대해 기본값 및 최소 `300000`(5분). 낮은 값은 확장 사고 일시 중지 프록시 버퍼링을 흡수하도록 자동으로 제한됩니다. 타사 공급자의 경우 `CLAUDE_ENABLE_STREAM_WATCHDOG=1`이 필요합니다. Bedrock에서는 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`일 때도 적용됩니다. |294| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 스트리밍 유휴 감시견이 정체된 연결을 닫기 전의 타임아웃(밀리초). 설정하지 않으면 이벤트 수준 감시견은 기본값 300초이고 바이트 수준 감시견은 직접 Anthropic API 연결에서 기본값 180초입니다(Claude Platform on AWS 다른 공급자에서 300초). 설정하지 않은 180초 바이트 감시견 기본값은 별개의 값이며 5분 제한을 받지 않습니다. 타사 공급자의 이벤트 수준 감시견의 경우 `CLAUDE_ENABLE_STREAM_WATCHDOG=1`이 필요합니다. `API_FORCE_IDLE_TIMEOUT`에 설명된 본문 유휴 타임아웃은 독립적으로 적용됩니다. Bedrock에서는 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`일 때도 적용됩니다. |

283| `DEBUG` | 디버그 모드를 활성화하려면 `1`로 설정합니다. [`--debug`](/ko/cli-reference#cli-flags)로 실행하는 것과 동일합니다. 디버그 로그는 `~/.claude/debug/<session-id>.txt`에 기록되거나 `CLAUDE_CODE_DEBUG_LOGS_DIR`로 설정된 경로에 기록됩니다. `1`, `true`, `yes`, `on`의 참 값만 디버그 모드를 활성화하므로 다른 도구에 대해 설정된 `DEBUG=express:*`와 같은 네임스페이스 패턴은 이를 트리거하지 않습니다. |295| `DEBUG` | 디버그 모드를 활성화하려면 `1`로 설정합니다. [`--debug`](/ko/cli-reference#cli-flags)로 실행하는 것과 동일합니다. 디버그 로그는 `~/.claude/debug/<session-id>.txt`에 기록되거나 `CLAUDE_CODE_DEBUG_LOGS_DIR`로 설정된 경로에 기록됩니다. `1`, `true`, `yes`, `on`의 참 값만 디버그 모드를 활성화하므로 다른 도구에 대해 설정된 `DEBUG=express:*`와 같은 네임스페이스 패턴은 이를 트리거하지 않습니다. |

284| `DISABLE_AUTOUPDATER` | 자동 업데이트를 비활성화하려면 `1`로 설정합니다. 수동 `claude update`는 계속 작동합니다. `DISABLE_UPDATES`를 사용하여 둘 다 차단합니다. |296| `DISABLE_AUTOUPDATER` | 자동 업데이트를 비활성화하려면 `1`로 설정합니다. 수동 `claude update`는 계속 작동합니다. `DISABLE_UPDATES`를 사용하여 둘 다 차단합니다. |

285| `DISABLE_AUTO_COMPACT` | 컨텍스트 제한에 접근할 때 자동 압축을 비활성화하려면 `1`로 설정합니다. 수동 `/compact` 명령은 계속 사용 가능합니다. 압축이 발생하는 시기를 명시적으로 제어하려는 경우 사용합니다. |297| `DISABLE_AUTO_COMPACT` | 컨텍스트 제한에 접근할 때 자동 압축을 비활성화하려면 `1`로 설정합니다. 수동 `/compact` 명령은 계속 사용 가능합니다. 압축이 발생하는 시기를 명시적으로 제어하려는 경우 사용합니다. |


296| `DISABLE_LOGIN_COMMAND` | `/login` 명령을 숨기려면 `1`로 설정합니다. API 키 또는 `apiKeyHelper`를 통해 인증이 외부에서 처리될 때 유용합니다. |308| `DISABLE_LOGIN_COMMAND` | `/login` 명령을 숨기려면 `1`로 설정합니다. API 키 또는 `apiKeyHelper`를 통해 인증이 외부에서 처리될 때 유용합니다. |

297| `DISABLE_LOGOUT_COMMAND` | `/logout` 명령을 숨기려면 `1`로 설정합니다. |309| `DISABLE_LOGOUT_COMMAND` | `/logout` 명령을 숨기려면 `1`로 설정합니다. |

298| `DISABLE_PROMPT_CACHING` | 모든 모델에 대해 [프롬프트 캐싱](/ko/prompt-caching#disable-prompt-caching)을 비활성화하려면 `1`로 설정합니다(모델별 설정보다 우선). |310| `DISABLE_PROMPT_CACHING` | 모든 모델에 대해 [프롬프트 캐싱](/ko/prompt-caching#disable-prompt-caching)을 비활성화하려면 `1`로 설정합니다(모델별 설정보다 우선). |

311| `DISABLE_PROMPT_CACHING_FABLE` | Fable 모델에 대해 프롬프트 캐싱을 비활성화하려면 `1`로 설정합니다. |

299| `DISABLE_PROMPT_CACHING_HAIKU` | Haiku 모델에 대해 프롬프트 캐싱을 비활성화하려면 `1`로 설정합니다. |312| `DISABLE_PROMPT_CACHING_HAIKU` | Haiku 모델에 대해 프롬프트 캐싱을 비활성화하려면 `1`로 설정합니다. |

300| `DISABLE_PROMPT_CACHING_OPUS` | Opus 모델에 대해 프롬프트 캐싱을 비활성화하려면 `1`로 설정합니다. |313| `DISABLE_PROMPT_CACHING_OPUS` | Opus 모델에 대해 프롬프트 캐싱을 비활성화하려면 `1`로 설정합니다. |

301| `DISABLE_PROMPT_CACHING_SONNET` | Sonnet 모델에 대해 프롬프트 캐싱을 비활성화하려면 `1`로 설정합니다. |314| `DISABLE_PROMPT_CACHING_SONNET` | Sonnet 모델에 대해 프롬프트 캐싱을 비활성화하려면 `1`로 설정합니다. |


307| `ENABLE_PROMPT_CACHING_1H` | API 키, [Bedrock](/ko/amazon-bedrock), [Vertex](/ko/google-vertex-ai), [Foundry](/ko/microsoft-foundry), [Claude Platform on AWS](/ko/claude-platform-on-aws) 사용자를 위해 기본 5분 대신 1시간 [프롬프트 캐시 TTL](/ko/prompt-caching#cache-lifetime)을 요청하려면 `1`로 설정합니다. 구독 사용자는 자동으로 1시간 TTL을 받습니다. 1시간 캐시 쓰기는 더 높은 요금으로 청구됩니다. |320| `ENABLE_PROMPT_CACHING_1H` | API 키, [Bedrock](/ko/amazon-bedrock), [Vertex](/ko/google-vertex-ai), [Foundry](/ko/microsoft-foundry), [Claude Platform on AWS](/ko/claude-platform-on-aws) 사용자를 위해 기본 5분 대신 1시간 [프롬프트 캐시 TTL](/ko/prompt-caching#cache-lifetime)을 요청하려면 `1`로 설정합니다. 구독 사용자는 자동으로 1시간 TTL을 받습니다. 1시간 캐시 쓰기는 더 높은 요금으로 청구됩니다. |

308| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | 더 이상 사용되지 않음. 대신 `ENABLE_PROMPT_CACHING_1H` 사용 |321| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | 더 이상 사용되지 않음. 대신 `ENABLE_PROMPT_CACHING_1H` 사용 |

309| `ENABLE_TOOL_SEARCH` | [MCP 도구 검색](/ko/mcp#scale-with-mcp-tool-search)을 제어합니다. 설정 해제: 모든 MCP 도구는 기본적으로 연기되지만 Vertex AI에서 또는 `ANTHROPIC_BASE_URL`이 비자사 호스트를 가리킬 때 미리 로드됩니다. 값: `true`(항상 연기 및 베타 헤더 전송, Vertex AI 모델 Sonnet 4.5 또는 Opus 4.5보다 이전 또는 `tool_reference`를 지원하지 않는 프록시에서 요청 실패), `auto`(임계값 모드: 도구가 컨텍스트의 10% 이내에 맞으면 미리 로드), `auto:N`(사용자 정의 임계값, 예: 5%의 경우 `auto:5`), `false`(모두 미리 로드) |322| `ENABLE_TOOL_SEARCH` | [MCP 도구 검색](/ko/mcp#scale-with-mcp-tool-search)을 제어합니다. 설정 해제: 모든 MCP 도구는 기본적으로 연기되지만 Vertex AI에서 또는 `ANTHROPIC_BASE_URL`이 비자사 호스트를 가리킬 때 미리 로드됩니다. 값: `true`(항상 연기 및 베타 헤더 전송, Vertex AI 모델 Sonnet 4.5 또는 Opus 4.5보다 이전 또는 `tool_reference`를 지원하지 않는 프록시에서 요청 실패), `auto`(임계값 모드: 도구가 컨텍스트의 10% 이내에 맞으면 미리 로드), `auto:N`(사용자 정의 임계값, 예: 5%의 경우 `auto:5`), `false`(모두 미리 로드) |

310| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 모든 기본 모델에서 반복된 과부하 오류 후 [`--fallback-model`](/ko/cli-reference#cli-flags) 폴백을 트리거하려면 비어 있지 않은 값으로 설정합니다. 기본적으로 Opus 모델만 폴백을 트리거합니다. |323| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 모든 기본 모델에서 반복된 과부하 오류 후 폴백을 트리거하려면 비어 있지 않은 값으로 설정합니다. {/* min-version: 2.1.160 */}v2.1.160부터 구성된 [폴백 모델 체인](/ko/model-config#fallback-model-chains) 모든 기본 모델에 대해 반복된 과부하 오류에서 트리거되므로 변수는 폴백 모델로 전환하는 데 영향을 주지 않습니다. |

311| `FORCE_AUTOUPDATE_PLUGINS` | `DISABLE_AUTOUPDATER`를 통해 주 자동 업데이터가 비활성화된 경우에도 플러그인 자동 업데이트를 강제하려면 `1`로 설정합니다. |324| `FORCE_AUTOUPDATE_PLUGINS` | `DISABLE_AUTOUPDATER`를 통해 주 자동 업데이터가 비활성화된 경우에도 플러그인 자동 업데이트를 강제하려면 `1`로 설정합니다. |

312| `FORCE_PROMPT_CACHING_5M` | 1시간 TTL이 적용되는 경우에도 5분 프롬프트 캐시 TTL을 강제하려면 `1`로 설정합니다. `ENABLE_PROMPT_CACHING_1H` 재정의 |325| `FORCE_PROMPT_CACHING_5M` | 1시간 TTL이 적용되는 경우에도 5분 프롬프트 캐시 TTL을 강제하려면 `1`로 설정합니다. `ENABLE_PROMPT_CACHING_1H` 재정의 |

313| `HTTP_PROXY` | 네트워크 연결을 위한 HTTP 프록시 서버를 지정합니다. |326| `HTTP_PROXY` | 네트워크 연결을 위한 HTTP 프록시 서버를 지정합니다. |


315| `IS_DEMO` | 데모 모드를 활성화하려면 `1`로 설정합니다: 헤더 및 `/status` 출력에서 이메일 및 조직 이름을 숨기고 온보딩을 건너뜁니다. 세션을 스트리밍하거나 녹화할 때 유용합니다. |328| `IS_DEMO` | 데모 모드를 활성화하려면 `1`로 설정합니다: 헤더 및 `/status` 출력에서 이메일 및 조직 이름을 숨기고 온보딩을 건너뜁니다. 세션을 스트리밍하거나 녹화할 때 유용합니다. |

316| `MAX_MCP_OUTPUT_TOKENS` | MCP 도구 응답에서 허용되는 최대 토큰 수입니다. Claude Code는 출력이 10,000 토큰을 초과할 때 경고를 표시합니다. 도구가 [`anthropic/maxResultSizeChars`](/ko/mcp#raise-the-limit-for-a-specific-tool)를 선언하면 텍스트 내용에 대해 해당 문자 제한을 사용하지만, 해당 도구의 이미지 내용은 여전히 이 변수의 영향을 받습니다(기본값: 25000) |329| `MAX_MCP_OUTPUT_TOKENS` | MCP 도구 응답에서 허용되는 최대 토큰 수입니다. Claude Code는 출력이 10,000 토큰을 초과할 때 경고를 표시합니다. 도구가 [`anthropic/maxResultSizeChars`](/ko/mcp#raise-the-limit-for-a-specific-tool)를 선언하면 텍스트 내용에 대해 해당 문자 제한을 사용하지만, 해당 도구의 이미지 내용은 여전히 이 변수의 영향을 받습니다(기본값: 25000) |

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

318| `MAX_THINKING_TOKENS` | [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) 토큰 예산을 재정의합니다. 상한은 모델의 [최대 출력 토큰](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)에서 1을 뺀 값입니다. 사고를 완전히 비활성화하려면 `0`으로 설정합니다. [적응형 추론](/ko/model-config#adjust-effort-level)이 있는 모델에서는 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`을 통해 적응형 추론이 비활성화되지 않으면 예산이 무시됩니다. |331| `MAX_THINKING_TOKENS` | [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) 토큰 예산을 재정의합니다. 상한은 모델의 [최대 출력 토큰](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)에서 1을 뺀 값입니다. `0`으로 설정하여 Anthropic API에서 사고를 비활성화합니다. Fable 5는 사고를 끌 수 없으므로 이는 효과가 없습니다. [타사 공급자](/ko/third-party-integrations)에서 `0` 마찬가지로 매개변수를 생략하므로 [적응형 추론](/ko/model-config#adjust-effort-level)이 있는 모델은 여전히 생각할 수 있습니다. 0이 아닌 값의 경우 적응형 추론 모델에서 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`을 통해 적응형 추론이 비활성화되지 않으면 예산이 무시됩니다. |

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

320| `MCP_CONNECTION_NONBLOCKING` | 시작이 첫 번째 쿼리 전에 MCP 서버 연결을 기다리는지 여부를 제어합니다. Claude Code v2.1.142부터 MCP 시작은 기본적으로 비블로킹입니다: 서버는 백그라운드에서 연결되고 완료되면 도구를 사용할 수 있게 됩니다. `0`으로 설정하여 블로킹 5초 연결 대기를 복원합니다. [`alwaysLoad: true`](/ko/mcp#exempt-a-server-from-deferral)로 구성된 서버는 도구가 첫 번째 프롬프트를 빌드할 때 존재해야 하므로 이 변수와 관계없이 항상 시작을 차단합니다. |333| `MCP_CONNECTION_NONBLOCKING` | 시작이 첫 번째 쿼리 전에 MCP 서버 연결을 기다리는지 여부를 제어합니다. {/* min-version: 2.1.142 */}Claude Code v2.1.142부터 MCP 시작은 기본적으로 비블로킹입니다: 서버는 백그라운드에서 연결되고 완료되면 도구를 사용할 수 있게 됩니다. `0`으로 설정하여 블로킹 5초 연결 대기를 복원합니다. [`alwaysLoad: true`](/ko/mcp#exempt-a-server-from-deferral)로 구성된 서버는 도구가 첫 번째 프롬프트를 빌드할 때 존재해야 하므로 이 변수와 관계없이 항상 시작을 차단합니다. |

321| `MCP_CONNECT_TIMEOUT_MS` | 블로킹 MCP 시작이 연결 배치를 기다리는 시간(밀리초)을 설정하고 도구 목록을 스냅샷하기 전입니다(기본값: 5000). [`alwaysLoad: true`](/ko/mcp#exempt-a-server-from-deferral)로 표시된 서버에 적용됩니다. 마감 시점에 여전히 보류 중인 서버는 백그라운드에서 계속 연결되지만 다음 쿼리까지 나타나지 않습니다. `MCP_TIMEOUT`과 다르며, 이는 개별 서버의 연결 시도를 제한합니다. |334| `MCP_CONNECT_TIMEOUT_MS` | 블로킹 MCP 시작이 연결 배치를 기다리는 시간(밀리초)을 설정하고 도구 목록을 스냅샷하기 전입니다(기본값: 5000). [`alwaysLoad: true`](/ko/mcp#exempt-a-server-from-deferral)로 표시된 서버에 적용됩니다. 마감 시점에 여전히 보류 중인 서버는 백그라운드에서 계속 연결되지만 다음 쿼리까지 나타나지 않습니다. `MCP_TIMEOUT`과 다르며, 이는 개별 서버의 연결 시도를 제한합니다. |

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

323| `MCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE` | 시작 중에 병렬로 연결할 원격 MCP 서버(HTTP/SSE)의 최대 수(기본값: 20) |336| `MCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE` | 시작 중에 병렬로 연결할 원격 MCP 서버(HTTP/SSE)의 최대 수(기본값: 20) |

324| `MCP_SERVER_CONNECTION_BATCH_SIZE` | 시작 중에 병렬로 연결할 로컬 MCP 서버(stdio)의 최대 수(기본값: 3) |337| `MCP_SERVER_CONNECTION_BATCH_SIZE` | 시작 중에 병렬로 연결할 로컬 MCP 서버(stdio)의 최대 수(기본값: 3) |

325| `MCP_TIMEOUT` | MCP 서버 시작의 타임아웃(밀리초)(기본값: 30000, 또는 30초) |338| `MCP_TIMEOUT` | MCP 서버 시작의 타임아웃(밀리초)(기본값: 30000, 또는 30초) |

326| `MCP_TOOL_TIMEOUT` | MCP 도구 실행의 타임아웃(밀리초)(기본값: 100000000, 약 28시간). 서버별 `.mcp.json`의 `timeout` 필드가 해당 서버에 대해 이를 재정의합니다. 1000 미만의 값은 1초로 내림됩니다. |339| `MCP_TOOL_TIMEOUT` | MCP 도구 실행의 타임아웃(밀리초)(기본값: 100000000, 약 28시간). 서버별 `.mcp.json`의 `timeout` 필드가 해당 서버에 대해 이를 재정의합니다. 환경 변수의 경우 1000 미만의 값은 1초로 내림됩니다. 서버별 필드의 경우 1000 미만의 값은 무시됩니다. |

327| `NO_PROXY` | 프록시를 우회하여 직접 발급될 요청의 도메인 및 IP 목록 |340| `NO_PROXY` | 프록시를 우회하여 직접 발급될 요청의 도메인 및 IP 목록 |

328| `OTEL_LOG_RAW_API_BODIES` | Anthropic Messages API 요청 및 응답 JSON을 `api_request_body` / `api_response_body` 로그 이벤트로 내보냅니다. 60KB에서 잘린 인라인 본문의 경우 `1`로 설정하거나, 잘리지 않은 본문을 디스크에 쓰고 `body_ref` 경로를 내보내려면 `file:<dir>`로 설정합니다. 기본적으로 비활성화됩니다. 본문에는 전체 대화 기록이 포함됩니다. [모니터링](/ko/monitoring-usage#api-request-body-event) 참조 |341| `OTEL_LOG_RAW_API_BODIES` | Anthropic Messages API 요청 및 응답 JSON을 `api_request_body` / `api_response_body` 로그 이벤트로 내보냅니다. 60KB에서 잘린 인라인 본문의 경우 `1`로 설정하거나, 잘리지 않은 본문을 디스크에 쓰고 `body_ref` 경로를 내보내려면 `file:<dir>`로 설정합니다. 기본적으로 비활성화됩니다. 본문에는 전체 대화 기록이 포함됩니다. [모니터링](/ko/monitoring-usage#api-request-body-event) 참조 |

329| `OTEL_LOG_TOOL_CONTENT` | 도구 입력 및 출력 내용을 OpenTelemetry 스팬 이벤트에 포함하려면 `1`로 설정합니다. 민감한 데이터를 보호하기 위해 기본적으로 비활성화됩니다. [모니터링](/ko/monitoring-usage) 참조 |342| `OTEL_LOG_TOOL_CONTENT` | 도구 입력 및 출력 내용을 OpenTelemetry 스팬 이벤트에 포함하려면 `1`로 설정합니다. 민감한 데이터를 보호하기 위해 기본적으로 비활성화됩니다. [모니터링](/ko/monitoring-usage) 참조 |

330| `OTEL_LOG_TOOL_DETAILS` | 도구 입력 인수, MCP 서버 이름, 도구 실패 시 원본 오류 문자열, 기타 도구 세부 정보를 OpenTelemetry 추적 및 로그에 포함하려면 `1`로 설정합니다. PII를 보호하기 위해 기본적으로 비활성화됩니다. [모니터링](/ko/monitoring-usage) 참조 |343| `OTEL_LOG_TOOL_DETAILS` | 도구 입력 인수, MCP 서버 이름, 도구 실패 시 원본 오류 문자열, 기타 도구 세부 정보를 OpenTelemetry 추적 및 로그에 포함하려면 `1`로 설정합니다. PII를 보호하기 위해 기본적으로 비활성화됩니다. [모니터링](/ko/monitoring-usage) 참조 |

331| `OTEL_LOG_USER_PROMPTS` | 사용자 프롬프트 텍스트를 OpenTelemetry 추적 및 로그에 포함하려면 `1`로 설정합니다. 기본적으로 비활성화됩니다(프롬프트는 수정됨). [모니터링](/ko/monitoring-usage) 참조 |344| `OTEL_LOG_USER_PROMPTS` | 사용자 프롬프트 텍스트를 OpenTelemetry 추적 및 로그에 포함하려면 `1`로 설정합니다. 기본적으로 비활성화됩니다(프롬프트는 수정됨). [모니터링](/ko/monitoring-usage) 참조 |

332| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | 메트릭 속성에서 계정 UUID를 제외하려면 `false`로 설정합니다(기본값: 포함). [모니터링](/ko/monitoring-usage) 참조 |345| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | 메트릭 속성에서 계정 UUID를 제외하려면 `false`로 설정합니다(기본값: 포함). [모니터링](/ko/monitoring-usage) 참조 |

333| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 메트릭 속성에 세션 진입점을 포함하려면 `true`로 설정합니다(기본값: 제외). v2.1.152에서 추가됨. [모니터링](/ko/monitoring-usage) 참조 |346| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | {/* min-version: 2.1.152 */}메트릭 속성에 세션 진입점을 포함하려면 `true`로 설정합니다(기본값: 제외). v2.1.152에서 추가됨. [모니터링](/ko/monitoring-usage) 참조 |

334| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | v2.1.161부터 Claude Code는 `OTEL_RESOURCE_ATTRIBUTES` 키를 메트릭 데이터포인트 레이블에 첨부합니다. 이를 제외하려면 `false`로 설정합니다(기본값: 포함). [모니터링](/ko/monitoring-usage#multi-team-organization-support) 참조 |347| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | {/* min-version: 2.1.161 */}v2.1.161부터 Claude Code는 `OTEL_RESOURCE_ATTRIBUTES` 키를 메트릭 데이터포인트 레이블에 첨부합니다. 이를 제외하려면 `false`로 설정합니다(기본값: 포함). [모니터링](/ko/monitoring-usage#multi-team-organization-support) 참조 |

335| `OTEL_METRICS_INCLUDE_SESSION_ID` | 메트릭 속성에서 세션 ID를 제외하려면 `false`로 설정합니다(기본값: 포함). [모니터링](/ko/monitoring-usage) 참조 |348| `OTEL_METRICS_INCLUDE_SESSION_ID` | 메트릭 속성에서 세션 ID를 제외하려면 `false`로 설정합니다(기본값: 포함). [모니터링](/ko/monitoring-usage) 참조 |

336| `OTEL_METRICS_INCLUDE_VERSION` | 메트릭 속성에 Claude Code 버전을 포함하려면 `true`로 설정합니다(기본값: 제외). [모니터링](/ko/monitoring-usage) 참조 |349| `OTEL_METRICS_INCLUDE_VERSION` | 메트릭 속성에 Claude Code 버전을 포함하려면 `true`로 설정합니다(기본값: 제외). [모니터링](/ko/monitoring-usage) 참조 |

337| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | [Skill 도구](/ko/skills#control-who-invokes-a-skill)에 표시되는 skill 메타데이터의 문자 예산을 재정의합니다. 예산은 컨텍스트 윈도우의 1%에서 동적으로 확장되며, 8,000자의 폴백이 있습니다. 이전 버전과의 호환성을 위해 레거시 이름이 유지됩니다. |350| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | [Skill 도구](/ko/skills#control-who-invokes-a-skill)에 표시되는 skill 메타데이터의 문자 예산을 재정의합니다. 예산은 컨텍스트 윈도우의 1%에서 동적으로 확장되며, 8,000자의 폴백이 있습니다. 이전 버전과의 호환성을 위해 레거시 이름이 유지됩니다. |


347| `VERTEX_REGION_CLAUDE_4_5_SONNET` | Vertex AI 사용 시 Claude Sonnet 4.5의 리전을 재정의합니다. |360| `VERTEX_REGION_CLAUDE_4_5_SONNET` | Vertex AI 사용 시 Claude Sonnet 4.5의 리전을 재정의합니다. |

348| `VERTEX_REGION_CLAUDE_4_6_OPUS` | Vertex AI 사용 시 Claude Opus 4.6의 리전을 재정의합니다. |361| `VERTEX_REGION_CLAUDE_4_6_OPUS` | Vertex AI 사용 시 Claude Opus 4.6의 리전을 재정의합니다. |

349| `VERTEX_REGION_CLAUDE_4_6_SONNET` | Vertex AI 사용 시 Claude Sonnet 4.6의 리전을 재정의합니다. |362| `VERTEX_REGION_CLAUDE_4_6_SONNET` | Vertex AI 사용 시 Claude Sonnet 4.6의 리전을 재정의합니다. |

350| `VERTEX_REGION_CLAUDE_4_7_OPUS` | Vertex AI 사용 시 Claude Opus 4.7의 리전을 재정의합니다. v2.1.111에서 추가됨. |363| `VERTEX_REGION_CLAUDE_4_7_OPUS` | {/* min-version: 2.1.111 */}Vertex AI 사용 시 Claude Opus 4.7의 리전을 재정의합니다. v2.1.111에서 추가됨. |

364| `VERTEX_REGION_CLAUDE_4_8_OPUS` | {/* min-version: 2.1.154 */}Vertex AI 사용 시 Claude Opus 4.8의 리전을 재정의합니다. v2.1.154에서 추가됨. |

365| `VERTEX_REGION_CLAUDE_FABLE_5` | {/* min-version: 2.1.170 */}Vertex AI 사용 시 Claude Fable 5의 리전을 재정의합니다. v2.1.170에서 추가됨. |

351| `VERTEX_REGION_CLAUDE_HAIKU_4_5` | Vertex AI 사용 시 Claude Haiku 4.5의 리전을 재정의합니다. |366| `VERTEX_REGION_CLAUDE_HAIKU_4_5` | Vertex AI 사용 시 Claude Haiku 4.5의 리전을 재정의합니다. |

352 367 

353표준 OpenTelemetry 내보내기 변수(`OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_METRIC_EXPORT_INTERVAL`, `OTEL_RESOURCE_ATTRIBUTES` 및 신호별 변형)도 지원됩니다. 구성 세부 정보는 [모니터링](/ko/monitoring-usage)을 참조합니다.368표준 OpenTelemetry 내보내기 변수(`OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_METRIC_EXPORT_INTERVAL`, `OTEL_RESOURCE_ATTRIBUTES` 및 신호별 변형)도 지원됩니다. 구성 세부 정보는 [모니터링](/ko/monitoring-usage)을 참조합니다.

errors.md +198 −47

Details

14 Claude Code는 모델 응답을 위해 Claude API를 호출하므로 대부분의 런타임 오류는 기본 API 오류 코드에 매핑됩니다. 이 페이지에서는 Claude Code 내에서 각 오류의 의미와 복구 방법을 다룹니다. 원본 HTTP 상태 코드 정의는 [Claude Platform 오류 참조](https://platform.claude.com/docs/en/api/errors)를 참조하십시오.14 Claude Code는 모델 응답을 위해 Claude API를 호출하므로 대부분의 런타임 오류는 기본 API 오류 코드에 매핑됩니다. 이 페이지에서는 Claude Code 내에서 각 오류의 의미와 복구 방법을 다룹니다. 원본 HTTP 상태 코드 정의는 [Claude Platform 오류 참조](https://platform.claude.com/docs/en/api/errors)를 참조하십시오.

15</Note>15</Note>

16 16 

17## 오류 찾기17<h2 id="find-your-error">

18 오류 찾기

19</h2>

18 20 

19터미널에 표시되는 메시지를 아래 섹션과 일치시킵니다.21터미널에 표시되는 메시지를 아래 섹션과 일치시킵니다.

20 22 


26| `<model> is temporarily unavailable, so auto mode cannot determine the safety of...` | [서버 오류](#auto-mode-cannot-determine-the-safety-of-an-action) |28| `<model> is temporarily unavailable, so auto mode cannot determine the safety of...` | [서버 오류](#auto-mode-cannot-determine-the-safety-of-an-action) |

27| `Auto mode could not evaluate this action and is blocking it for safety` | [서버 오류](#auto-mode-cannot-determine-the-safety-of-an-action) |29| `Auto mode could not evaluate this action and is blocking it for safety` | [서버 오류](#auto-mode-cannot-determine-the-safety-of-an-action) |

28| `Auto mode classifier transcript exceeded context window` | [서버 오류](#auto-mode-cannot-determine-the-safety-of-an-action) |30| `Auto mode classifier transcript exceeded context window` | [서버 오류](#auto-mode-cannot-determine-the-safety-of-an-action) |

29| `You've hit your session limit` / `You've hit your weekly limit` | [사용 제한](#youve-hit-your-session-limit) |31| `You've hit your session limit` / `You've hit your weekly limit` | [사용 제한](#you%E2%80%99ve-hit-your-session-limit) |

32| `Usage credits required for 1M context` | [사용 제한](#usage-credits-required-for-1m-context) |

30| `Server is temporarily limiting requests` | [사용 제한](#server-is-temporarily-limiting-requests) |33| `Server is temporarily limiting requests` | [사용 제한](#server-is-temporarily-limiting-requests) |

31| `Request rejected (429)` | [사용 제한](#request-rejected-429) |34| `Request rejected (429)` | [사용 제한](#request-rejected-429) |

32| `Credit balance is too low` | [사용 제한](#credit-balance-is-too-low) |35| `Credit balance is too low` | [사용 제한](#credit-balance-is-too-low) |

33| `Not logged in · Please run /login` | [인증](#not-logged-in) |36| `Not logged in · Please run /login` | [인증](#not-logged-in) |

37| `Could not resolve authentication method` | [인증](#could-not-resolve-authentication-method) |

34| `Invalid API key` | [인증](#invalid-api-key) |38| `Invalid API key` | [인증](#invalid-api-key) |

35| `This organization has been disabled` | [인증](#this-organization-has-been-disabled) |39| `This organization has been disabled` | [인증](#this-organization-has-been-disabled) |

40| `Your organization has disabled API key authentication` | [인증](#your-organization-has-disabled-api-key-authentication) |

36| `Your organization has disabled Claude subscription access` | [인증](#your-organization-has-disabled-claude-subscription-access) |41| `Your organization has disabled Claude subscription access` | [인증](#your-organization-has-disabled-claude-subscription-access) |

37| `Routines are disabled by your organization's policy` | [인증](#routines-are-disabled-by-your-organizations-policy) |42| `Routines are disabled by your organization's policy` | [인증](#routines-are-disabled-by-your-organization%E2%80%99s-policy) |

38| `OAuth token revoked` / `OAuth token has expired` | [인증](#oauth-token-revoked-or-expired) |43| `OAuth token revoked` / `OAuth token has expired` | [인증](#oauth-token-revoked-or-expired) |

39| `does not meet scope requirement user:profile` | [인증](#oauth-scope-requirement) |44| `does not meet scope requirement user:profile` | [인증](#oauth-scope-requirement) |

40| `Unable to connect to API` | [네트워크](#unable-to-connect-to-api) |45| `Unable to connect to API` | [네트워크](#unable-to-connect-to-api) |


47| `Unable to resize image` | [요청 오류](#unable-to-resize-image) |52| `Unable to resize image` | [요청 오류](#unable-to-resize-image) |

48| `PDF too large` / `PDF is password protected` | [요청 오류](#pdf-errors) |53| `PDF too large` / `PDF is password protected` | [요청 오류](#pdf-errors) |

49| `Extra inputs are not permitted` | [요청 오류](#extra-inputs-are-not-permitted) |54| `Extra inputs are not permitted` | [요청 오류](#extra-inputs-are-not-permitted) |

50| `There's an issue with the selected model` | [요청 오류](#theres-an-issue-with-the-selected-model) |55| `There's an issue with the selected model` | [요청 오류](#there%E2%80%99s-an-issue-with-the-selected-model) |

51| `Claude Opus is not available with the Claude Pro plan` | [요청 오류](#claude-opus-is-not-available-with-the-claude-pro-plan) |56| `Claude Opus is not available with the Claude Pro plan` | [요청 오류](#claude-opus-is-not-available-with-the-claude-pro-plan) |

52| `thinking.type.enabled is not supported for this model` | [요청 오류](#thinking-type-enabled-is-not-supported-for-this-model) |57| `thinking.type.enabled is not supported for this model` | [요청 오류](#thinking-type-enabled-is-not-supported-for-this-model) |

53| `max_tokens must be greater than thinking.budget_tokens` | [요청 오류](#thinking-budget-exceeds-output-limit) |58| `max_tokens must be greater than thinking.budget_tokens` | [요청 오류](#thinking-budget-exceeds-output-limit) |


55| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [요청 오류](#usage-policy-refusal) |60| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [요청 오류](#usage-policy-refusal) |

56| 응답 품질이 평소보다 낮아 보임 | [응답 품질](#responses-seem-lower-quality-than-usual) |61| 응답 품질이 평소보다 낮아 보임 | [응답 품질](#responses-seem-lower-quality-than-usual) |

57 62 

58## 자동 재시도63<h2 id="automatic-retries">

64 자동 재시도

65</h2>

59 66 

60Claude Code는 오류를 표시하기 전에 일시적 오류를 재시도합니다. 서버 오류, 과부하 응답, 요청 시간 초과, 임시 429 스로틀, 끊어진 연결은 모두 지수 백오프를 사용하여 최대 10회 재시도됩니다. 재시도하는 동안 스피너는 `Retrying in Ns · attempt x/y` 카운트다운을 표시합니다.67Claude Code는 오류를 표시하기 전에 일시적 오류를 재시도합니다. 서버 오류, 과부하 응답, 요청 시간 초과, 임시 429 스로틀, 끊어진 연결은 모두 지수 백오프를 사용하여 최대 10회 재시도됩니다. 재시도하는 동안 스피너는 `Retrying in Ns · attempt x/y` 카운트다운을 표시합니다.

61 68 


66| [`CLAUDE_CODE_MAX_RETRIES`](/ko/env-vars) | 10 | 재시도 횟수입니다. 스크립트에서 오류를 더 빨리 표시하려면 낮추고, 더 긴 인시던트를 기다리려면 높입니다. |73| [`CLAUDE_CODE_MAX_RETRIES`](/ko/env-vars) | 10 | 재시도 횟수입니다. 스크립트에서 오류를 더 빨리 표시하려면 낮추고, 더 긴 인시던트를 기다리려면 높입니다. |

67| [`API_TIMEOUT_MS`](/ko/env-vars) | 600000 | 요청당 시간 초과(밀리초)입니다. 느린 네트워크 또는 프록시의 경우 높입니다. |74| [`API_TIMEOUT_MS`](/ko/env-vars) | 600000 | 요청당 시간 초과(밀리초)입니다. 느린 네트워크 또는 프록시의 경우 높입니다. |

68 75 

69## 서버 오류76<h2 id="server-errors">

77 서버 오류

78</h2>

70 79 

71이러한 오류는 계정이나 요청이 아닌 추론 제공자에서 발생합니다. Anthropic API의 경우 Anthropic 인프라를 의미합니다. Bedrock, Vertex AI, Foundry 또는 사용자 정의 게이트웨이의 경우 해당 제공자의 인프라를 의미합니다.80이러한 오류는 계정이나 요청이 아닌 추론 제공자에서 발생합니다. Anthropic API의 경우 Anthropic 인프라를 의미합니다. Bedrock, Vertex AI, Foundry 또는 사용자 정의 게이트웨이의 경우 해당 제공자의 인프라를 의미합니다.

72 81 

73### API Error: 500 Internal server error82<h3 id="api-error-500-internal-server-error">

83 API Error: 500 Internal server error

84</h3>

74 85 

75Claude Code는 모든 5xx 응답에 대해 상태 코드와 API의 오류 메시지를 표시합니다. 아래 예제는 Anthropic API의 500 응답을 보여줍니다.86Claude Code는 모든 5xx 응답에 대해 상태 코드와 API의 오류 메시지를 표시합니다. 아래 예제는 Anthropic API의 500 응답을 보여줍니다.

76 87 


88* 1분 기다린 후 메시지를 다시 보냅니다. 원본 메시지는 여전히 대화에 있으므로 긴 프롬프트의 경우 전체를 다시 붙여넣는 대신 `try again`을 입력할 수 있습니다.99* 1분 기다린 후 메시지를 다시 보냅니다. 원본 메시지는 여전히 대화에 있으므로 긴 프롬프트의 경우 전체를 다시 붙여넣는 대신 `try again`을 입력할 수 있습니다.

89* 게시된 인시던트가 없는데도 오류가 지속되면 `/feedback`을 실행하여 Anthropic이 요청 세부 정보로 조사할 수 있도록 합니다. 환경에서 `/feedback`을 사용할 수 없는 경우 [오류 보고](#report-an-error)를 참조하십시오.100* 게시된 인시던트가 없는데도 오류가 지속되면 `/feedback`을 실행하여 Anthropic이 요청 세부 정보로 조사할 수 있도록 합니다. 환경에서 `/feedback`을 사용할 수 없는 경우 [오류 보고](#report-an-error)를 참조하십시오.

90 101 

91### API Error: Repeated 529 Overloaded errors102<h3 id="api-error-repeated-529-overloaded-errors">

103 API Error: Repeated 529 Overloaded errors

104</h3>

92 105 

93API가 모든 사용자에게 일시적으로 용량이 가득 찼습니다. Claude Code는 이 메시지를 표시하기 전에 이미 여러 번 재시도했습니다.106API가 모든 사용자에게 일시적으로 용량이 가득 찼습니다. Claude Code는 이 메시지를 표시하기 전에 이미 여러 번 재시도했습니다.

94 107 


104* 몇 분 후 다시 시도117* 몇 분 후 다시 시도

105* `/model`을 실행하고 다른 모델로 전환하여 계속 작업합니다. 용량은 모델별로 추적되기 때문입니다. Claude Code는 한 모델이 특히 높은 부하를 받을 때 이를 수행하도록 프롬프트합니다. 예를 들어 `Opus is experiencing high load, please use /model to switch to Sonnet`.118* `/model`을 실행하고 다른 모델로 전환하여 계속 작업합니다. 용량은 모델별로 추적되기 때문입니다. Claude Code는 한 모델이 특히 높은 부하를 받을 때 이를 수행하도록 프롬프트합니다. 예를 들어 `Opus is experiencing high load, please use /model to switch to Sonnet`.

106 119 

107### Request timed out120<h3 id="request-timed-out">

121 Request timed out

122</h3>

108 123 

109API가 연결 기한 전에 응답하지 않았습니다.124API가 연결 기한 전에 응답하지 않았습니다.

110 125 


121* 느린 네트워크 또는 프록시가 원인인 경우 [자동 재시도](#automatic-retries)에 설명된 대로 `API_TIMEOUT_MS`를 높입니다.136* 느린 네트워크 또는 프록시가 원인인 경우 [자동 재시도](#automatic-retries)에 설명된 대로 `API_TIMEOUT_MS`를 높입니다.

122* 시간 초과가 자주 발생하고 네트워크가 정상인 경우 아래 [네트워크 및 연결 오류](#network-and-connection-errors)를 참조하십시오.137* 시간 초과가 자주 발생하고 네트워크가 정상인 경우 아래 [네트워크 및 연결 오류](#network-and-connection-errors)를 참조하십시오.

123 138 

124### Auto mode cannot determine the safety of an action139<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">

140 Auto mode cannot determine the safety of an action

141</h3>

125 142 

126[자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)가 작업을 분류하는 데 사용하는 모델이 결정을 생성할 수 없어서 자동 모드가 작업을 자동으로 승인하지 않았습니다. 표시되는 메시지는 분류기가 실패한 이유에 따라 다릅니다.143[자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)가 작업을 분류하는 데 사용하는 모델이 결정을 생성할 수 없어서 자동 모드가 작업을 자동으로 승인하지 않았습니다. 표시되는 메시지는 분류기가 실패한 이유에 따라 다릅니다.

127 144 


163* 나타나는 프롬프트에서 작업을 승인하거나 거부합니다.180* 나타나는 프롬프트에서 작업을 승인하거나 거부합니다.

164* `/compact`를 실행하여 대화 크기를 줄여서 후속 작업이 분류기 윈도우에 맞도록 합니다.181* `/compact`를 실행하여 대화 크기를 줄여서 후속 작업이 분류기 윈도우에 맞도록 합니다.

165 182 

166## 사용 제한183<h2 id="usage-limits">

184 사용 제한

185</h2>

167 186 

168이러한 오류는 계정 또는 플랜에 연결된 할당량에 도달했음을 의미합니다. 이는 모든 사람에게 영향을 미치는 [서버 오류](#server-errors)와는 다릅니다.187이러한 오류는 계정 또는 플랜에 연결된 할당량에 도달했음을 의미합니다. 이는 모든 사람에게 영향을 미치는 [서버 오류](#server-errors)와는 다릅니다.

169 188 

170### 세션 제한에 도달했습니다189<h3 id="you’ve-hit-your-session-limit">

190 세션 제한에 도달했습니다

191</h3>

171 192 

172구독 플랜에는 롤링 사용 허용량이 포함됩니다. 소진되면 다음 메시지 중 하나가 표시됩니다.193구독 플랜에는 롤링 사용 허용량이 포함됩니다. 소진되면 다음 메시지 중 하나가 표시됩니다.

173 194 


188 209 

189제한에 도달하기 전에 남은 허용량을 확인하려면 `rate_limits` 필드를 [사용자 정의 상태 줄](/ko/statusline#rate-limit-usage)에 추가하거나 데스크톱 앱에서 모델 선택기 옆의 [사용 링](/ko/desktop#check-usage)을 클릭합니다.210제한에 도달하기 전에 남은 허용량을 확인하려면 `rate_limits` 필드를 [사용자 정의 상태 줄](/ko/statusline#rate-limit-usage)에 추가하거나 데스크톱 앱에서 모델 선택기 옆의 [사용 링](/ko/desktop#check-usage)을 클릭합니다.

190 211 

191### 서버가 일시적으로 요청을 제한 중입니다212<h3 id="usage-credits-required-for-1m-context">

213 1M 컨텍스트에 필요한 사용 크레딧

214</h3>

215 

216선택한 모델은 1M 토큰 확장 컨텍스트 윈도우를 사용하며, 플랜에는 사용 크레딧을 통해서만 포함됩니다.

217 

218```text theme={null}

219API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context

220```

221 

222이는 할당량 소진이 아니라 자격 확인입니다. 세션 및 주간 허용량에 용량이 남아 있어도 발생합니다. [확장 컨텍스트](/ko/model-config#extended-context)에서 어떤 플랜에 1M 컨텍스트가 직접 포함되고 어떤 플랜에 사용 크레딧이 필요한지 확인하십시오.

223 

224컨텍스트가 200K 토큰을 초과하여 대화 중에 이 오류가 나타나면 Claude Code는 자동으로 대화를 표준 컨텍스트 제한 이하로 압축하고 이후 세션을 해당 제한으로 유지하므로 조치가 필요하지 않습니다. v2.1.172 이전 버전에서는 `/compact`를 포함한 모든 후속 요청에서 오류가 반복되었습니다. 해당 버전에서는 `/clear`를 실행하여 복구합니다. 아래 단계는 명시적으로 `[1m]` 모델을 선택한 경우에 적용됩니다.

225 

226**할 일:**

227 

228* `/model`을 실행하고 `[1m]` 접미사가 없는 변형을 선택하여 표준 컨텍스트 윈도우로 폴백합니다.

229* `/usage-credits`를 실행하여 Pro 및 Max에서 1M 변형에 대한 종량제 청구를 활성화하거나 Team 및 Enterprise에서 관리자에게 요청합니다.

230* `/model` 후에도 오류가 지속되면 1M 모델 ID가 다른 곳에 설정되어 있을 수 있습니다. [선택한 모델에 문제가 있습니다](#there%E2%80%99s-an-issue-with-the-selected-model)에서 우선 순위 순서로 확인할 구성 위치를 참조하십시오.

231* 모델 선택기에서 1M 변형을 완전히 제거하려면 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/ko/env-vars)을 설정합니다.

232 

233<h3 id="server-is-temporarily-limiting-requests">

234 서버가 일시적으로 요청을 제한 중입니다

235</h3>

192 236 

193API가 플랜 할당량과 무관한 단기 스로틀을 적용했습니다.237API가 플랜 할당량과 무관한 단기 스로틀을 적용했습니다.

194 238 


203* 잠시 기다린 후 다시 시도합니다.247* 잠시 기다린 후 다시 시도합니다.

204* 지속되면 [status.claude.com](https://status.claude.com)을 확인합니다.248* 지속되면 [status.claude.com](https://status.claude.com)을 확인합니다.

205 249 

206### 요청 거부됨 (429)250<h3 id="request-rejected-429">

251 요청 거부됨 (429)

252</h3>

207 253 

208API 키, Amazon Bedrock 프로젝트 또는 Google Vertex AI 프로젝트에 대해 구성된 속도 제한에 도달했습니다.254API 키, Amazon Bedrock 프로젝트 또는 Google Vertex AI 프로젝트에 대해 구성된 속도 제한에 도달했습니다.

209 255 


220* Anthropic API 키의 경우 [속도 제한 참조](https://platform.claude.com/docs/ko/api/rate-limits)에서 계층이 작동하는 방식과 워크스페이스별 상한을 설정하는 방법을 참조하십시오.266* Anthropic API 키의 경우 [속도 제한 참조](https://platform.claude.com/docs/ko/api/rate-limits)에서 계층이 작동하는 방식과 워크스페이스별 상한을 설정하는 방법을 참조하십시오.

221* 동시성 감소: [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/ko/env-vars)를 낮추고, 많은 병렬 서브에이전트 실행을 피하거나, 대량 스크립팅 실행을 위해 `/model`로 더 작은 모델로 전환합니다.267* 동시성 감소: [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/ko/env-vars)를 낮추고, 많은 병렬 서브에이전트 실행을 피하거나, 대량 스크립팅 실행을 위해 `/model`로 더 작은 모델로 전환합니다.

222 268 

223### 크레딧 잔액이 너무 낮습니다269<h3 id="credit-balance-is-too-low">

270 크레딧 잔액이 너무 낮습니다

271</h3>

224 272 

225Console 조직이 선불 크레딧을 모두 사용했습니다.273Console 조직이 선불 크레딧을 모두 사용했습니다.

226 274 


234* Pro, Max, Team 또는 Enterprise 플랜이 있는 경우 `/login`으로 구독 인증으로 전환합니다.282* Pro, Max, Team 또는 Enterprise 플랜이 있는 경우 `/login`으로 구독 인증으로 전환합니다.

235* Console에서 워크스페이스별 지출 상한을 설정하여 단일 프로젝트가 조직 잔액을 소진하지 않도록 합니다. [비용 효율적으로 관리](/ko/costs)를 참조하십시오.283* Console에서 워크스페이스별 지출 상한을 설정하여 단일 프로젝트가 조직 잔액을 소진하지 않도록 합니다. [비용 효율적으로 관리](/ko/costs)를 참조하십시오.

236 284 

237## 인증 오류285<h2 id="authentication-errors">

286 인증 오류

287</h2>

238 288 

239이러한 오류는 Claude Code가 API에 대한 신원을 증명할 수 없음을 의미합니다. 언제든지 `/status`를 실행하여 현재 활성 자격 증명을 확인합니다.289이러한 오류는 Claude Code가 API에 대한 신원을 증명할 수 없음을 의미합니다. 언제든지 `/status`를 실행하여 현재 활성 자격 증명을 확인합니다.

240 290 

241### Not logged in291<h3 id="not-logged-in">

292 Not logged in

293</h3>

242 294 

243이 세션에 유효한 자격 증명이 없습니다.295이 세션에 유효한 자격 증명이 없습니다.

244 296 


255 307 

256반복적으로 로그인하라는 메시지가 표시되면 시스템 시계 및 macOS Keychain 수정을 위해 [로그인되지 않음 또는 토큰 만료](/ko/troubleshoot-install#not-logged-in-or-token-expired)를 참조하십시오.308반복적으로 로그인하라는 메시지가 표시되면 시스템 시계 및 macOS Keychain 수정을 위해 [로그인되지 않음 또는 토큰 만료](/ko/troubleshoot-install#not-logged-in-or-token-expired)를 참조하십시오.

257 309 

258### Invalid API key310<h3 id="could-not-resolve-authentication-method">

311 Could not resolve authentication method

312</h3>

313 

314세션이 자격 증명 없이 API 클라이언트에 도달했습니다. 이는 [백그라운드 세션](/ko/agent-view), 클라우드 세션 및 첫 번째 요청 전에 대화형 로그인 확인이 실행되지 않는 Agent SDK 컨텍스트에 나타납니다.

315 

316```text theme={null}

317Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted

318```

319 

320{/* min-version: 2.1.174 */}v2.1.174 이전에는 유효한 자격 증명이 구성되어 있어도 유휴 사전 초기화된 워커에 할당된 백그라운드 또는 클라우드 세션이 이런 방식으로 실패할 수 있었습니다. 복구하려면 업그레이드하십시오. 현재 버전에서 오류는 워커 프로세스에 사용 가능한 자격 증명이 없음을 의미합니다.

321 

322**할 일:**

323 

324* 백그라운드 또는 클라우드 세션에 이것이 나타나고 자격 증명이 이미 구성되어 있으면 v2.1.174 이상으로 업그레이드합니다.

325* `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` 또는 클라우드 공급자 자격 증명이 대화형 셸뿐만 아니라 워커를 시작하는 환경에 설정되어 있는지 확인합니다.

326* Agent SDK의 경우 [인증 설정](/ko/agent-sdk/overview#get-started)을 참조하십시오.

327* 동일한 환경의 대화형 세션에서 `/status`를 실행하여 어느 자격 증명 소스가 해결되는지 확인합니다.

328 

329<h3 id="invalid-api-key">

330 Invalid API key

331</h3>

259 332 

260`ANTHROPIC_API_KEY` 환경 변수 또는 `apiKeyHelper` 스크립트가 API가 거부한 키를 반환했습니다.333`ANTHROPIC_API_KEY` 환경 변수 또는 `apiKeyHelper` 스크립트가 API가 거부한 키를 반환했습니다.

261 334 


271* 키가 [`apiKeyHelper`](/ko/settings#available-settings) 스크립트에서 오는 경우 스크립트를 직접 실행하여 stdout에 유효한 키를 인쇄하는지 확인합니다.344* 키가 [`apiKeyHelper`](/ko/settings#available-settings) 스크립트에서 오는 경우 스크립트를 직접 실행하여 stdout에 유효한 키를 인쇄하는지 확인합니다.

272* `/status`를 실행하여 Claude Code가 실제로 사용 중인 자격 증명 소스를 확인합니다.345* `/status`를 실행하여 Claude Code가 실제로 사용 중인 자격 증명 소스를 확인합니다.

273 346 

274### This organization has been disabled347<h3 id="this-organization-has-been-disabled">

348 This organization has been disabled

349</h3>

275 350 

276비활성화된 Console 조직의 오래된 `ANTHROPIC_API_KEY`가 구독 로그인을 재정의하고 있습니다.351비활성화된 Console 조직의 오래된 `ANTHROPIC_API_KEY`가 구독 로그인을 재정의하고 있습니다.

277 352 


288* 그 후 `/status`를 실행하여 활성 자격 증명이 구독인지 확인합니다.363* 그 후 `/status`를 실행하여 활성 자격 증명이 구독인지 확인합니다.

289* 환경 변수가 설정되지 않았는데도 오류가 지속되면 비활성화된 조직이 `/login`에 연결된 것입니다. 지원팀에 문의하거나 다른 계정으로 로그인합니다.364* 환경 변수가 설정되지 않았는데도 오류가 지속되면 비활성화된 조직이 `/login`에 연결된 것입니다. 지원팀에 문의하거나 다른 계정으로 로그인합니다.

290 365 

291### Your organization has disabled Claude subscription access366<h3 id="your-organization-has-disabled-api-key-authentication">

367 Your organization has disabled API key authentication

368</h3>

369 

370Console 조직의 관리자가 API 키 인증을 비활성화했으므로 API가 Claude Code가 전송하는 키를 거부합니다. `·` 뒤의 복구 힌트는 키가 어디에서 왔는지에 따라 다릅니다.

371 

372```text theme={null}

373Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account

374Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY to use your claude.ai account instead

375Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY and run /login to sign in with your claude.ai account

376Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account

377```

378 

379환경 변수와 `apiKeyHelper`는 `/login`보다 우선하므로 둘 중 하나가 여전히 키를 제공하는 동안 `/login`만 실행해서는 도움이 되지 않습니다. [인증 우선순위](/ko/authentication#authentication-precedence)를 참조하십시오.

380 

381**할 일:**

382 

383* 메시지에 `ANTHROPIC_API_KEY`가 명시되어 있으면 현재 셸에서 설정을 해제하고 셸 프로필 또는 `.env` 파일에서 제거한 후 `claude`를 다시 시작합니다.

384* 메시지에 `apiKeyHelper`가 명시되어 있으면 `settings.json`에서 [`apiKeyHelper`](/ko/settings#available-settings) 설정을 제거합니다.

385* `/login`을 실행하여 claude.ai 계정으로 로그인합니다.

386* 그 후 `/status`를 실행하여 활성 자격 증명이 API 키가 아닌 구독인지 확인합니다.

387* 자동화를 위해 API 키 인증이 필요한 경우 조직 관리자에게 Console에서 다시 활성화하도록 요청합니다.

388 

389<h3 id="your-organization-has-disabled-claude-subscription-access">

390 Your organization has disabled Claude subscription access

391</h3>

292 392 

293Claude 조직이 구독 로그인으로 Claude Code에 로그인하는 것을 허용하지 않습니다. 동일한 계정으로 `/login`을 다시 실행하면 동일한 오류가 반환됩니다.393Claude 조직이 구독 로그인으로 Claude Code에 로그인하는 것을 허용하지 않습니다. 동일한 계정으로 `/login`을 다시 실행하면 동일한 오류가 반환됩니다.

294 394 


304* 구독 대신 Console API 키로 인증합니다. 설정은 [Claude Console 인증](/ko/authentication#claude-console-authentication)을 참조하십시오.404* 구독 대신 Console API 키로 인증합니다. 설정은 [Claude Console 인증](/ko/authentication#claude-console-authentication)을 참조하십시오.

305* 관리자이고 액세스를 활성화하는 옵션이 보이지 않으면 [Anthropic 지원](https://support.claude.com)에 문의합니다.405* 관리자이고 액세스를 활성화하는 옵션이 보이지 않으면 [Anthropic 지원](https://support.claude.com)에 문의합니다.

306 406 

307### Routines are disabled by your organization's policy407<h3 id="routines-are-disabled-by-your-organizations-policy">

408 Routines are disabled by your organization's policy

409</h3>

308 410 

309팀 또는 엔터프라이즈 관리자가 조직 수준에서 루틴을 비활성화했습니다. 오류는 `/schedule` 및 claude.ai/code의 [Routines](/ko/routines) UI에서 루틴을 생성하거나 실행하려고 할 때 나타납니다.411팀 또는 엔터프라이즈 관리자가 조직 수준에서 루틴을 비활성화했습니다. 오류는 `/schedule` 및 claude.ai/code의 [Routines](/ko/routines) UI에서 루틴을 생성하거나 실행하려고 할 때 나타납니다.

310 412 


319* 관리자에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 **Routines** 토글을 활성화하도록 요청합니다.421* 관리자에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 **Routines** 토글을 활성화하도록 요청합니다.

320* 조직 수준의 루틴이 필요하지 않은 일회성 예약 작업의 경우 [예약된 작업](/ko/scheduled-tasks)을 참조하십시오.422* 조직 수준의 루틴이 필요하지 않은 일회성 예약 작업의 경우 [예약된 작업](/ko/scheduled-tasks)을 참조하십시오.

321 423 

322### OAuth token revoked or expired424<h3 id="oauth-token-revoked-or-expired">

425 OAuth token revoked or expired

426</h3>

323 427 

324저장된 로그인이 더 이상 유효하지 않습니다. 취소된 토큰은 어디서나 로그아웃했거나 관리자가 액세스를 제거했음을 의미합니다. 만료된 토큰은 자동 새로 고침이 세션 중에 실패했음을 의미합니다.428저장된 로그인이 더 이상 유효하지 않습니다. 취소된 토큰은 어디서나 로그아웃했거나 관리자가 액세스를 제거했음을 의미합니다. 만료된 토큰은 자동 새로 고침이 세션 중에 실패했음을 의미합니다.

325 429 


336* 시작 간 반복적인 로그인 프롬프트의 경우 [문제 해결](/ko/troubleshoot-install#not-logged-in-or-token-expired)의 시스템 시계 및 macOS Keychain 확인을 참조하십시오.440* 시작 간 반복적인 로그인 프롬프트의 경우 [문제 해결](/ko/troubleshoot-install#not-logged-in-or-token-expired)의 시스템 시계 및 macOS Keychain 확인을 참조하십시오.

337* `403 Forbidden` 및 OAuth 브라우저 문제를 포함한 기타 오류는 [로그인 및 인증](/ko/troubleshoot-install#login-and-authentication)을 참조하십시오.441* `403 Forbidden` 및 OAuth 브라우저 문제를 포함한 기타 오류는 [로그인 및 인증](/ko/troubleshoot-install#login-and-authentication)을 참조하십시오.

338 442 

339### OAuth scope requirement443<h3 id="oauth-scope-requirement">

444 OAuth scope requirement

445</h3>

340 446 

341저장된 토큰은 최신 기능이 필요한 권한 범위보다 앞서 있습니다. 이는 `/usage` 및 상태 줄 사용 표시기에서 가장 자주 표시됩니다.447저장된 토큰은 최신 기능이 필요한 권한 범위보다 앞서 있습니다. 이는 `/usage` 및 상태 줄 사용 표시기에서 가장 자주 표시됩니다.

342 448 


348 454 

349* `/login`을 실행하여 현재 범위로 새 토큰을 발급합니다. 먼저 로그아웃할 필요가 없습니다.455* `/login`을 실행하여 현재 범위로 새 토큰을 발급합니다. 먼저 로그아웃할 필요가 없습니다.

350 456 

351## 네트워크 및 연결 오류457<h2 id="network-and-connection-errors">

458 네트워크 및 연결 오류

459</h2>

352 460 

353이러한 오류는 Claude Code의 네트워크 요청이 목적지에 도달하지 못했음을 의미합니다. 일반적으로 로컬 네트워크, 프록시 또는 방화벽, 또는 클라우드 환경의 네트워크 정책에서 발생합니다.461이러한 오류는 Claude Code의 네트워크 요청이 목적지에 도달하지 못했음을 의미합니다. 일반적으로 로컬 네트워크, 프록시 또는 방화벽, 또는 클라우드 환경의 네트워크 정책에서 발생합니다.

354 462 

355### Unable to connect to API463<h3 id="unable-to-connect-to-api">

464 Unable to connect to API

465</h3>

356 466 

357API에 대한 TCP 연결이 실패했거나 완료되지 않았습니다.467API에 대한 TCP 연결이 실패했거나 완료되지 않았습니다.

358 468 


381* macOS에서 연결이 끊어지거나 제거된 VPN 클라이언트는 터널 인터페이스 또는 라우팅 규칙을 남길 수 있습니다. `ifconfig`에서 오래된 `utun` 인터페이스를 확인하고 시스템 설정에서 VPN의 네트워크 확장을 제거합니다.491* macOS에서 연결이 끊어지거나 제거된 VPN 클라이언트는 터널 인터페이스 또는 라우팅 규칙을 남길 수 있습니다. `ifconfig`에서 오래된 `utun` 인터페이스를 확인하고 시스템 설정에서 VPN의 네트워크 확장을 제거합니다.

382* Docker Desktop 및 유사한 컨테이너 런타임은 아웃바운드 트래픽을 가로챌 수 있습니다. 이를 종료하고 재시도하여 이를 배제합니다.492* Docker Desktop 및 유사한 컨테이너 런타임은 아웃바운드 트래픽을 가로챌 수 있습니다. 이를 종료하고 재시도하여 이를 배제합니다.

383 493 

384### SSL certificate errors494<h3 id="ssl-certificate-errors">

495 SSL certificate errors

496</h3>

385 497 

386네트워크의 프록시 또는 보안 어플라이언스가 자체 인증서로 TLS 트래픽을 가로채고 있으며 Claude Code가 이를 신뢰하지 않습니다.498네트워크의 프록시 또는 보안 어플라이언스가 자체 인증서로 TLS 트래픽을 가로채고 있으며 Claude Code가 이를 신뢰하지 않습니다.

387 499 


396* 전체 설정 지침은 [네트워크 구성](/ko/network-config#custom-ca-certificates)을 참조하십시오.508* 전체 설정 지침은 [네트워크 구성](/ko/network-config#custom-ca-certificates)을 참조하십시오.

397* 인증서 검증을 완전히 비활성화하는 `NODE_TLS_REJECT_UNAUTHORIZED=0`을 설정하지 마십시오.509* 인증서 검증을 완전히 비활성화하는 `NODE_TLS_REJECT_UNAUTHORIZED=0`을 설정하지 마십시오.

398 510 

399### Host not allowed in a cloud session511<h3 id="host-not-allowed-in-a-cloud-session">

512 Host not allowed in a cloud session

513</h3>

400 514 

401클라우드 세션 또는 루틴의 아웃바운드 HTTP 요청이 환경의 네트워크 정책에 의해 차단되었습니다.515클라우드 세션 또는 루틴의 아웃바운드 HTTP 요청이 환경의 네트워크 정책에 의해 차단되었습니다.

402 516 


417 531 

418액세스 수준 및 기본 허용 목록은 [네트워크 액세스](/ko/claude-code-on-the-web#network-access)를 참조하십시오. 로컬 CLI 세션은 이 정책의 영향을 받지 않습니다.532액세스 수준 및 기본 허용 목록은 [네트워크 액세스](/ko/claude-code-on-the-web#network-access)를 참조하십시오. 로컬 CLI 세션은 이 정책의 영향을 받지 않습니다.

419 533 

420## 요청 오류534<h2 id="request-errors">

535 요청 오류

536</h2>

421 537 

422이러한 오류는 API가 요청을 수신했지만 내용을 거부했음을 의미합니다.538이러한 오류는 API가 요청을 수신했지만 내용을 거부했음을 의미합니다.

423 539 

424### Prompt is too long540<h3 id="prompt-is-too-long">

541 Prompt is too long

542</h3>

425 543 

426대화 및 첨부 파일이 모델의 컨텍스트 윈도우를 초과합니다.544대화 및 첨부 파일이 모델의 컨텍스트 윈도우를 초과합니다.

427 545 


440 558 

441[컨텍스트 윈도우 탐색](/ko/context-window)을 참조하여 컨텍스트가 어떻게 채워지는지 대화형으로 확인합니다.559[컨텍스트 윈도우 탐색](/ko/context-window)을 참조하여 컨텍스트가 어떻게 채워지는지 대화형으로 확인합니다.

442 560 

443### Error during compaction: Conversation too long561<h3 id="error-during-compaction-conversation-too-long">

562 Error during compaction: Conversation too long

563</h3>

444 564 

445`/compact` 자체가 실패했습니다. 생성하는 요약을 보유할 충분한 여유 컨텍스트가 없기 때문입니다.565`/compact` 자체가 실패했습니다. 생성하는 요약을 보유할 충분한 여유 컨텍스트가 없기 때문입니다.

446 566 


455* Esc를 두 번 눌러 메시지 목록을 열고 몇 턴 뒤로 이동합니다. 이는 컨텍스트에서 가장 최근 메시지를 제거합니다. 그런 다음 `/compact`를 다시 실행합니다.575* Esc를 두 번 눌러 메시지 목록을 열고 몇 턴 뒤로 이동합니다. 이는 컨텍스트에서 가장 최근 메시지를 제거합니다. 그런 다음 `/compact`를 다시 실행합니다.

456* 뒤로 이동해도 충분한 공간이 확보되지 않으면 `/clear`를 실행하여 새 세션을 시작합니다. 이전 대화는 보존되며 `/resume`으로 다시 열 수 있습니다.576* 뒤로 이동해도 충분한 공간이 확보되지 않으면 `/clear`를 실행하여 새 세션을 시작합니다. 이전 대화는 보존되며 `/resume`으로 다시 열 수 있습니다.

457 577 

458### Request too large578<h3 id="request-too-large">

579 Request too large

580</h3>

459 581 

460원본 요청 본문이 토큰화 전에 API의 바이트 제한을 초과했습니다. 일반적으로 큰 붙여넣은 파일 또는 첨부 파일 때문입니다.582원본 요청 본문이 토큰화 전에 API의 바이트 제한을 초과했습니다. 일반적으로 큰 붙여넣은 파일 또는 첨부 파일 때문입니다.

461 583 


471* 콘텐츠를 붙여넣는 대신 경로로 큰 파일을 참조하여 Claude가 청크 단위로 읽을 수 있도록 합니다.593* 콘텐츠를 붙여넣는 대신 경로로 큰 파일을 참조하여 Claude가 청크 단위로 읽을 수 있도록 합니다.

472* 이미지의 경우 아래 [Image was too large](#image-was-too-large)를 참조하십시오.594* 이미지의 경우 아래 [Image was too large](#image-was-too-large)를 참조하십시오.

473 595 

474### Image was too large596<h3 id="image-was-too-large">

597 Image was too large

598</h3>

475 599 

476붙여넣거나 첨부한 이미지가 API의 크기 또는 치수 제한을 초과합니다.600붙여넣거나 첨부한 이미지가 API의 크기 또는 치수 제한을 초과합니다.

477 601 


480API Error: 400 ... image dimensions exceed max allowed size604API Error: 400 ... image dimensions exceed max allowed size

481```605```

482 606 

483이미지는 오류 대화 기록에 남아 있으므로 제거할 때까지 모든 후속 메시지가 동일한 오류로 실패합니다.607{/* min-version: 2.1.142 */}Claude Code는 처리할 없는 이미지를 텍스트 자리 표시자로 바꾸고 다시 시도하므로 후속 메시지가 성공합니다. 2.1.142 이전 버전에서는 붙여넣은 이미지가 대화에 남아 있을 수 있으며 후속 메시지마다 동일한 오류를 반복합니다. 이러한 버전에서 복구하려면 Esc를 두 번 눌러 이미지가 추가된 턴을 지나갑니다.

484 608 

485**할 일:**609**할 일:**

486 610 

487* Esc를 두 번 눌러 뒤로 이동하고 이미지가 추가된 턴을 지나갑니다.

488* 붙여넣기 전에 이미지 크기를 조정합니다. API는 단일 이미지의 경우 가장 긴 가장자리에서 최대 8000픽셀을 허용하거나 많은 이미지가 컨텍스트에 있을 때 2000픽셀을 허용합니다.611* 붙여넣기 전에 이미지 크기를 조정합니다. API는 단일 이미지의 경우 가장 긴 가장자리에서 최대 8000픽셀을 허용하거나 많은 이미지가 컨텍스트에 있을 때 2000픽셀을 허용합니다.

489* 전체 화면 대신 관련 영역의 더 타이트한 스크린샷을 찍습니다.612* 전체 화면 대신 관련 영역의 더 타이트한 스크린샷을 찍습니다.

490 613 

491### Unable to resize image614<h3 id="unable-to-resize-image">

615 Unable to resize image

616</h3>

492 617 

493Claude Code가 API로 보내기 전에 첨부된 이미지를 축소할 수 없습니다.618Claude Code가 API로 보내기 전에 첨부된 이미지를 축소할 수 없습니다.

494 619 


506* 메시지가 이미지를 변환하도록 요청하면 PNG, JPEG, GIF 또는 WebP로 변환하고 다시 첨부합니다. Claude Code는 이미지 프로세서 없이 이러한 형식의 치수를 확인할 수 있습니다.631* 메시지가 이미지를 변환하도록 요청하면 PNG, JPEG, GIF 또는 WebP로 변환하고 다시 첨부합니다. Claude Code는 이미지 프로세서 없이 이러한 형식의 치수를 확인할 수 있습니다.

507* 메시지가 치수 또는 크기 제한을 보고하면 첨부하기 전에 이미지를 해당 제한 아래로 크기 조정하거나 다시 압축합니다.632* 메시지가 치수 또는 크기 제한을 보고하면 첨부하기 전에 이미지를 해당 제한 아래로 크기 조정하거나 다시 압축합니다.

508 633 

509### PDF errors634<h3 id="pdf-errors">

635 PDF errors

636</h3>

510 637 

511첨부한 PDF를 처리할 수 없습니다.638첨부한 PDF를 처리할 수 없습니다.

512 639 


521* 과도한 크기의 PDF의 경우 Claude에게 전체 파일을 첨부하는 대신 Read 도구로 페이지 범위를 읽도록 요청하거나 `pdftotext`와 같은 도구로 텍스트를 추출하고 경로로 출력 파일을 참조합니다.648* 과도한 크기의 PDF의 경우 Claude에게 전체 파일을 첨부하는 대신 Read 도구로 페이지 범위를 읽도록 요청하거나 `pdftotext`와 같은 도구로 텍스트를 추출하고 경로로 출력 파일을 참조합니다.

522* 보호되거나 유효하지 않은 PDF의 경우 암호를 제거하거나 소스 애플리케이션에서 파일을 다시 내보낸 후 다시 시도합니다.649* 보호되거나 유효하지 않은 PDF의 경우 암호를 제거하거나 소스 애플리케이션에서 파일을 다시 내보낸 후 다시 시도합니다.

523 650 

524### Extra inputs are not permitted651<h3 id="extra-inputs-are-not-permitted">

652 Extra inputs are not permitted

653</h3>

525 654 

526Claude Code와 API 사이의 프록시 또는 LLM 게이트웨이가 `anthropic-beta` 요청 헤더를 제거했으므로 API가 이에 따라 달라지는 필드를 거부했습니다.655Claude Code와 API 사이의 프록시 또는 LLM 게이트웨이가 `anthropic-beta` 요청 헤더를 제거했으므로 API가 이에 따라 달라지는 필드를 거부했습니다.

527 656 


538* `anthropic-beta` 헤더를 전달하도록 게이트웨이를 구성합니다. [LLM 게이트웨이 구성](/ko/llm-gateway)을 참조하십시오.667* `anthropic-beta` 헤더를 전달하도록 게이트웨이를 구성합니다. [LLM 게이트웨이 구성](/ko/llm-gateway)을 참조하십시오.

539* 대체로 시작하기 전에 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/ko/env-vars)을 설정합니다. 이는 베타 헤더가 필요한 기능을 비활성화하여 헤더를 전달할 수 없는 게이트웨이를 통해 요청이 성공하도록 합니다.668* 대체로 시작하기 전에 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/ko/env-vars)을 설정합니다. 이는 베타 헤더가 필요한 기능을 비활성화하여 헤더를 전달할 수 없는 게이트웨이를 통해 요청이 성공하도록 합니다.

540 669 

541### There's an issue with the selected model670<h3 id="there’s-an-issue-with-the-selected-model">

671 There's an issue with the selected model

672</h3>

542 673 

543구성된 모델 이름이 인식되지 않았거나 계정이 이에 액세스할 수 없습니다. v2.1.160부터 뒤따르는 힌트는 여기에 대화형 형식으로 표시되며 표면에 따라 다릅니다.674구성된 모델 이름이 인식되지 않았거나 계정이 이에 액세스할 수 없습니다. v2.1.160부터 뒤따르는 힌트는 여기에 대화형 형식으로 표시되며 표면에 따라 다릅니다.

544 675 


555* 잘못된 모델이 계속 CLI에서 돌아오면 오래된 ID가 어딘가에 설정되어 있습니다. [우선순위 순서](/ko/model-config#setting-your-model)로 확인합니다. `--model` 플래그, `ANTHROPIC_MODEL` 환경 변수, 그 다음 `.claude/settings.local.json`의 `model` 필드, 프로젝트의 `.claude/settings.json`, 그리고 `~/.claude/settings.json`입니다. 오래된 값을 제거하면 Claude Code는 계정 기본값으로 폴백합니다.686* 잘못된 모델이 계속 CLI에서 돌아오면 오래된 ID가 어딘가에 설정되어 있습니다. [우선순위 순서](/ko/model-config#setting-your-model)로 확인합니다. `--model` 플래그, `ANTHROPIC_MODEL` 환경 변수, 그 다음 `.claude/settings.local.json`의 `model` 필드, 프로젝트의 `.claude/settings.json`, 그리고 `~/.claude/settings.json`입니다. 오래된 값을 제거하면 Claude Code는 계정 기본값으로 폴백합니다.

556* Vertex AI 배포의 경우 [Vertex AI 문제 해결](/ko/google-vertex-ai#troubleshooting)을 참조하십시오.687* Vertex AI 배포의 경우 [Vertex AI 문제 해결](/ko/google-vertex-ai#troubleshooting)을 참조하십시오.

557 688 

558### Claude Opus is not available with the Claude Pro plan689<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">

690 Claude Opus is not available with the Claude Pro plan

691</h3>

559 692 

560활성 구독 플랜에 선택한 모델이 포함되지 않습니다.693활성 구독 플랜에 선택한 모델이 포함되지 않습니다.

561 694 


569* 최근에 플랜을 업그레이드했는데도 여전히 이를 보면 `/logout`을 실행한 후 `/login`을 실행합니다. 저장된 토큰은 로그인 시 플랜을 반영하므로 웹에서 업그레이드해도 기존 세션에서 적용되지 않을 때까지 적용되지 않습니다.702* 최근에 플랜을 업그레이드했는데도 여전히 이를 보면 `/logout`을 실행한 후 `/login`을 실행합니다. 저장된 토큰은 로그인 시 플랜을 반영하므로 웹에서 업그레이드해도 기존 세션에서 적용되지 않을 때까지 적용되지 않습니다.

570* 각 플랜에 포함된 모델은 [claude.com/pricing](https://claude.com/pricing)을 참조하십시오.703* 각 플랜에 포함된 모델은 [claude.com/pricing](https://claude.com/pricing)을 참조하십시오.

571 704 

572### thinking.type.enabled is not supported for this model705<h3 id="thinking-type-enabled-is-not-supported-for-this-model">

706 thinking.type.enabled is not supported for this model

707</h3>

573 708 

574Claude Code 버전이 Opus 4.7 또는 Opus 4.8의 최소값보다 오래되었습니다. CLI가 모델이 더 이상 허용하지 않는 생각 구성을 보냈습니다.709Claude Code 버전이 Opus 4.7 또는 Opus 4.8의 최소값보다 오래되었습니다. CLI가 모델이 더 이상 허용하지 않는 생각 구성을 보냈습니다.

575 710 


583* 업그레이드할 수 없으면 `/model`을 실행하고 Opus 4.6 또는 Sonnet을 선택합니다.718* 업그레이드할 수 없으면 `/model`을 실행하고 Opus 4.6 또는 Sonnet을 선택합니다.

584* Agent SDK에서 이를 맞으면 [SDK 문제 해결](/ko/agent-sdk/quickstart#troubleshooting)을 참조하십시오.719* Agent SDK에서 이를 맞으면 [SDK 문제 해결](/ko/agent-sdk/quickstart#troubleshooting)을 참조하십시오.

585 720 

586### Thinking budget exceeds output limit721<h3 id="thinking-budget-exceeds-output-limit">

722 Thinking budget exceeds output limit

723</h3>

587 724 

588구성된 확장 생각 예산이 최대 응답 길이를 초과하므로 실제 답변을 위한 공간이 남지 않습니다.725구성된 확장 생각 예산이 최대 응답 길이를 초과하므로 실제 답변을 위한 공간이 남지 않습니다.

589 726 


598* `MAX_THINKING_TOKENS`를 낮추거나 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/ko/env-vars)를 생각 예산 위로 높입니다.735* `MAX_THINKING_TOKENS`를 낮추거나 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/ko/env-vars)를 생각 예산 위로 높입니다.

599* [확장 생각](/ko/model-config#extended-thinking)을 참조하여 예산이 출력 길이와 어떻게 상호 작용하는지 확인합니다.736* [확장 생각](/ko/model-config#extended-thinking)을 참조하여 예산이 출력 길이와 어떻게 상호 작용하는지 확인합니다.

600 737 

601### Tool use or thinking block mismatch738<h3 id="tool-use-or-thinking-block-mismatch">

739 Tool use or thinking block mismatch

740</h3>

602 741 

603대화 기록이 일관성 없는 상태로 API에 도달했습니다. 일반적으로 도구 호출이 중단되거나 턴이 스트림 중간에 편집된 후입니다.742대화 기록이 일관성 없는 상태로 API에 도달했습니다. 일반적으로 도구 호출이 중단되거나 턴이 스트림 중간에 편집된 후입니다.

604 743 


615* {/* max-version: 2.1.155 */}Opus 4.7 또는 Opus 4.8을 사용하는 경우 먼저 `claude update`를 실행합니다. v2.1.156 이전 버전은 정상적인 도구 사용 중에 이 오류를 트리거할 수 있으며 `/rewind`는 이를 지우지 않습니다.754* {/* max-version: 2.1.155 */}Opus 4.7 또는 Opus 4.8을 사용하는 경우 먼저 `claude update`를 실행합니다. v2.1.156 이전 버전은 정상적인 도구 사용 중에 이 오류를 트리거할 수 있으며 `/rewind`는 이를 지우지 않습니다.

616* `/rewind`를 실행하거나 Esc를 두 번 눌러 손상된 턴 전의 체크포인트로 뒤로 이동하고 거기서 계속합니다. [체크포인팅](/ko/checkpointing)을 참조하여 체크포인트가 생성되고 복원되는 방식을 확인합니다.755* `/rewind`를 실행하거나 Esc를 두 번 눌러 손상된 턴 전의 체크포인트로 뒤로 이동하고 거기서 계속합니다. [체크포인팅](/ko/checkpointing)을 참조하여 체크포인트가 생성되고 복원되는 방식을 확인합니다.

617 756 

618### Usage Policy refusal757<h3 id="usage-policy-refusal">

758 Usage Policy refusal

759</h3>

619 760 

620API가 대화의 내용이 [사용 정책](https://www.anthropic.com/legal/aup) 확인을 트리거했기 때문에 응답을 거부했습니다. 메시지에는 거부가 잘못되었다고 생각하는 경우 지원팀에 인용할 수 있는 요청 ID가 포함됩니다.761API가 대화의 내용이 [사용 정책](https://www.anthropic.com/legal/aup) 확인을 트리거했기 때문에 응답을 거부했습니다. 메시지에는 거부가 잘못되었다고 생각하는 경우 지원팀에 인용할 수 있는 요청 ID가 포함됩니다.

621 762 


629 770 

630* Esc를 두 번 누르거나 `/rewind`를 실행하여 거부를 트리거한 턴 전의 체크포인트로 뒤로 이동한 후 다시 표현하거나 다른 접근 방식을 시도합니다. [체크포인팅](/ko/checkpointing)을 참조하십시오.771* Esc를 두 번 누르거나 `/rewind`를 실행하여 거부를 트리거한 턴 전의 체크포인트로 뒤로 이동한 후 다시 표현하거나 다른 접근 방식을 시도합니다. [체크포인팅](/ko/checkpointing)을 참조하십시오.

631* 어느 턴이 원인인지 식별할 수 없으면 `/clear`를 실행하여 동일한 프로젝트에서 새 대화를 시작합니다. 이전 대화는 디스크에 보존되며 `/resume`에서 사용 가능합니다.772* 어느 턴이 원인인지 식별할 수 없으면 `/clear`를 실행하여 동일한 프로젝트에서 새 대화를 시작합니다. 이전 대화는 디스크에 보존되며 `/resume`에서 사용 가능합니다.

632* [비대화형 모드](/ko/headless)(`-p`)에서는 되감기를 사용할 수 없으므로 다시 표현된 프롬프트로 다시 시도하거나 `--continue` 없이 새 세션을 시작합니다.773* [비대화형 모드](/ko/headless)(`-p`)에서는 되감기를 사용할 수 없으므로 다시 표현된 프롬프트로 다시 시도하거나 `--continue` 없이 새 세션을 시작합니다. 정책 확인은 모델에 따라 다르므로 `--model`로 다른 모델로 전환하면 일부 경우에 거부를 해결할 수도 있습니다.

774 

775<h2 id="responses-seem-lower-quality-than-usual">

776 응답 품질이 평소보다 낮아 보임

777</h2>

778 

779Claude의 답변이 오류 없이 예상보다 덜 유능해 보이면 원인은 일반적으로 모델 자체가 아닌 대화 상태입니다. Claude Code는 모델 버전을 자동으로 변경하지 않습니다. 세 가지 특정 경우에 대체 모델로 전환할 수 있습니다.

633 780 

634## 응답 품질이 평소보다 낮아 보임781* 구성된 [`--fallback-model`](/ko/cli-reference#cli-flags)은 가용성 오류 해당 턴에만 인수를 받으며, 기록에 공지가 표시됩니다.

782* Bedrock 또는 Vertex AI 시작 확인에서 기본 모델을 사용할 수 없음을 발견합니다.

783* [자동 모델 대체](/ko/model-config#automatic-model-fallback)는 Fable 5에서 세션을 기본 Opus 모델로 이동하고 기록에 공지를 표시합니다.

635 784 

636Claude의 답변이 오류 없이 예상보다 덜 유능해 보이면 원인은 일반적으로 모델 자체가 아닌 대화 상태입니다. Claude Code는 모델 버전을 자동으로 변경하지 않습니다. Opus 할당량에 도달하거나 Bedrock 또는 Vertex AI 지역이 모델이 없는 경우와 같은 특정 경우에 대체 모델로 전환할 있습니다. 아래의 모델 선택 확인이 둘 다 포착하고 [모델 구성](/ko/model-config)은 대체가 적용되는 시기를 설명합니다.785아래의 모델 선택 확인이 번째와 번째 경우를 포착합니다. 번째는 `/model` 변경이 아닌 기록 공지로 나타납니다. [모델 구성](/ko/model-config)은 대체가 적용되는 시기를 설명합니다.

637 786 

638먼저 다음을 확인합니다.787먼저 다음을 확인합니다.

639 788 


646 795 

647위의 확인 후에도 품질이 여전히 이상해 보이면 `/feedback`을 실행하고 예상한 것과 얻은 것을 설명합니다. 이 방식으로 제출된 피드백에는 대화 기록이 포함되어 있으므로 Anthropic이 실제 회귀를 진단하는 가장 빠른 방법입니다. 제공자에서 `/feedback`을 사용할 수 없는 경우 [오류 보고](#report-an-error)를 참조하십시오.796위의 확인 후에도 품질이 여전히 이상해 보이면 `/feedback`을 실행하고 예상한 것과 얻은 것을 설명합니다. 이 방식으로 제출된 피드백에는 대화 기록이 포함되어 있으므로 Anthropic이 실제 회귀를 진단하는 가장 빠른 방법입니다. 제공자에서 `/feedback`을 사용할 수 없는 경우 [오류 보고](#report-an-error)를 참조하십시오.

648 797 

649## 오류 보고798<h2 id="report-an-error">

799 오류 보고

800</h2>

650 801 

651이 페이지는 Claude API의 오류를 다룹니다. Claude Code의 다른 구성 요소의 오류는 관련 가이드를 참조하십시오.802이 페이지는 Claude API의 오류를 다룹니다. Claude Code의 다른 구성 요소의 오류는 관련 가이드를 참조하십시오.

652 803 

fast-mode.md +2 −2

Details

35 빠른 모드 전환35 빠른 모드 전환

36</h2>36</h2>

37 37 

38다음 중 한 가지 방법으로 빠른 모드를 전환합니다:38빠른 모드를 다음 중 한 가지 방법으로 전환합니다:

39 39 

40* `/fast`를 입력하고 Tab을 눌러 켜거나 끕니다40* `/fast`를 입력하고 Tab을 눌러 켜거나 끕니다

41* [사용자 설정 파일](/ko/settings)에서 `"fastMode": true`를 설정합니다41* [사용자 설정 파일](/ko/settings)에서 `"fastMode": true`를 설정합니다


115* **Team 및 Enterprise의 관리자 활성화**: 빠른 모드는 Team 및 Enterprise 조직에 대해 기본적으로 비활성화됩니다. 사용자가 액세스할 수 있으려면 관리자가 명시적으로 [빠른 모드를 활성화](#enable-fast-mode-for-your-organization)해야 합니다.115* **Team 및 Enterprise의 관리자 활성화**: 빠른 모드는 Team 및 Enterprise 조직에 대해 기본적으로 비활성화됩니다. 사용자가 액세스할 수 있으려면 관리자가 명시적으로 [빠른 모드를 활성화](#enable-fast-mode-for-your-organization)해야 합니다.

116 116 

117<Note>117<Note>

118 관리자가 조직에 대해 빠른 모드를 활성화하지 않은 경우 `/fast` 명령은 "Fast mode has been disabled by your organization."을 표시합니다.118 관리자가 조직에 대해 빠른 모드를 활성화하지 않은 경우 `/fast` 명령은 "Fast mode has been disabled by your organization."을 표시합니다. 조직의 [`availableModels`](/ko/model-config#restrict-model-selection) 허용 목록이 빠른 모드 Opus 모델을 제외하는 경우 `/fast`는 "is not in your organization's allowed models"로 거부됩니다.

119</Note>119</Note>

120 120 

121<h3 id="enable-fast-mode-for-your-organization">121<h3 id="enable-fast-mode-for-your-organization">

Details

109 109 

110 **Skill에 넣으세요.** 참조 자료인 경우 Claude가 때때로 필요합니다(API 문서, 스타일 가이드) 또는 `/<name>`으로 트리거하는 워크플로우입니다(배포, 검토, 릴리스).110 **Skill에 넣으세요.** 참조 자료인 경우 Claude가 때때로 필요합니다(API 문서, 스타일 가이드) 또는 `/<name>`으로 트리거하는 워크플로우입니다(배포, 검토, 릴리스).

111 111 

112 **경험 법칙:** CLAUDE.md를 200줄 이하로 유지하세요. 증가하면 참조 콘텐츠를 skill로 이동하거나 [`.claude/rules/`](/ko/memory#organize-rules-with-clauderules) 파일로 분할하세요.112 **경험 법칙:** CLAUDE.md를 200줄 이하로 유지하세요. 증가하면 참조 콘텐츠를 skill로 이동하거나 [`.claude/rules/`](/ko/memory#organize-rules-with-claude%2Frules%2F) 파일로 분할하세요.

113 </Tab>113 </Tab>

114 114 

115 <Tab title="CLAUDE.md vs Rules vs Skills">115 <Tab title="CLAUDE.md vs Rules vs Skills">


198 198 

199기능은 여러 수준에서 정의될 수 있습니다. 사용자 전체, 프로젝트별, 플러그인을 통해, 또는 관리 정책을 통해. 또한 CLAUDE.md 파일을 하위 디렉토리에 중첩하거나 monorepo의 특정 패키지에 skill을 배치할 수 있습니다. 동일한 기능이 여러 수준에 존재할 때, 계층화 방식은 다음과 같습니다.199기능은 여러 수준에서 정의될 수 있습니다. 사용자 전체, 프로젝트별, 플러그인을 통해, 또는 관리 정책을 통해. 또한 CLAUDE.md 파일을 하위 디렉토리에 중첩하거나 monorepo의 특정 패키지에 skill을 배치할 수 있습니다. 동일한 기능이 여러 수준에 존재할 때, 계층화 방식은 다음과 같습니다.

200 200 

201* **CLAUDE.md 파일**은 추가적입니다. 모든 수준이 동시에 Claude의 컨텍스트에 콘텐츠를 제공합니다. 작업 디렉토리 및 위의 파일은 시작 시 로드되고, 하위 디렉토리는 작업할 때 로드됩니다. 지침이 충돌할 때, Claude는 판단을 사용하여 조정하며, 더 구체적인 지침이 일반적으로 우선합니다. [CLAUDE.md 파일이 로드되는 방식](/ko/memory#how-claudemd-files-load)을 참조하세요.201* **CLAUDE.md 파일**은 추가적입니다. 모든 수준이 동시에 Claude의 컨텍스트에 콘텐츠를 제공합니다. 작업 디렉토리 및 위의 파일은 시작 시 로드되고, 하위 디렉토리는 작업할 때 로드됩니다. 지침이 충돌할 때, Claude는 판단을 사용하여 조정하며, 더 구체적인 지침이 일반적으로 우선합니다. [CLAUDE.md 파일이 로드되는 방식](/ko/memory#how-claude-md-files-load)을 참조하세요.

202* **Skill과 subagent**는 이름으로 재정의됩니다. 동일한 이름이 여러 수준에 존재할 때, 우선순위에 따라 하나의 정의가 승리합니다(skill의 경우 관리 > 사용자 > 프로젝트; subagent의 경우 관리 > CLI 플래그 > 프로젝트 > 사용자 > 플러그인). 플러그인 skill은 [네임스페이스됩니다](/ko/plugins#add-skills-to-your-plugin). 충돌을 피하기 위해. [Skill 검색](/ko/skills#where-skills-live) 및 [subagent 범위](/ko/sub-agents#choose-the-subagent-scope)를 참조하세요.202* **Skill과 subagent**는 이름으로 재정의됩니다. 동일한 이름이 여러 수준에 존재할 때, 우선순위에 따라 하나의 정의가 승리합니다(skill의 경우 관리 > 사용자 > 프로젝트; subagent의 경우 관리 > CLI 플래그 > 프로젝트 > 사용자 > 플러그인). 플러그인 skill은 [네임스페이스됩니다](/ko/plugins#add-skills-to-your-plugin). 충돌을 피하기 위해. [Skill 검색](/ko/skills#where-skills-live) 및 [subagent 범위](/ko/sub-agents#choose-the-subagent-scope)를 참조하세요.

203* **MCP 서버**는 이름으로 재정의됩니다. 로컬 > 프로젝트 > 사용자. [MCP 범위](/ko/mcp#scope-hierarchy-and-precedence)를 참조하세요.203* **MCP 서버**는 이름으로 재정의됩니다. 로컬 > 프로젝트 > 사용자. [MCP 범위](/ko/mcp#scope-hierarchy-and-precedence)를 참조하세요.

204* **Hooks**는 병합됩니다. 모든 등록된 hook은 소스에 관계없이 일치하는 이벤트에 대해 실행됩니다. [Hooks](/ko/hooks)를 참조하세요.204* **Hooks**는 병합됩니다. 모든 등록된 hook은 소스에 관계없이 일치하는 이벤트에 대해 실행됩니다. [Hooks](/ko/hooks)를 참조하세요.


255 255 

256 **로드되는 내용:** 모든 CLAUDE.md 파일의 전체 콘텐츠(관리, 사용자 및 프로젝트 수준).256 **로드되는 내용:** 모든 CLAUDE.md 파일의 전체 콘텐츠(관리, 사용자 및 프로젝트 수준).

257 257 

258 **상속:** Claude는 작업 디렉토리에서 루트까지 CLAUDE.md 파일을 읽고, 해당 파일에 접근할 때 하위 디렉토리에서 중첩된 파일을 검색합니다. 자세한 내용은 [CLAUDE.md 파일이 로드되는 방식](/ko/memory#how-claudemd-files-load)을 참조하세요.258 **상속:** Claude는 작업 디렉토리에서 루트까지 CLAUDE.md 파일을 읽고, 해당 파일에 접근할 때 하위 디렉토리에서 중첩된 파일을 검색합니다. 자세한 내용은 [CLAUDE.md 파일이 로드되는 방식](/ko/memory#how-claude-md-files-load)을 참조하세요.

259 259 

260 <Tip>CLAUDE.md를 200줄 이하로 유지하세요. 참조 자료를 skill로 이동하면 온디맨드로 로드됩니다.</Tip>260 <Tip>CLAUDE.md를 200줄 이하로 유지하세요. 참조 자료를 skill로 이동하면 온디맨드로 로드됩니다.</Tip>

261 </Tab>261 </Tab>

fullscreen.md +22 −3

Details

104export CLAUDE_CODE_SCROLL_SPEED=3104export CLAUDE_CODE_SCROLL_SPEED=3

105```105```

106 106 

107`3` 값은 `vim` 및 유사한 애플리케이션의 기본값과 일치합니다. 설정은 1에서 20 사이의 값을 허용합니다.107`3` 값은 `vim` 및 유사한 애플리케이션의 기본값과 일치합니다. 설정은 1에서 20 사이의 값을 허용하며, 터미널의 기본 스크롤 경로에서 가속화된 트랙패드 및 휠 스크롤을 느리게 하기 위해 `0.5`와 같은 1 미만의 분수 값도 허용합니다.

108 108 

109스크롤 속도를 대화형으로 조정하려면 `/scroll-speed`를 실행합니다. 대화는 열려 있는 동안 스크롤할 수 있는 눈금자를 표시하므로 변경 사항을 즉시 느낄 수 있습니다. `←` 및 `→`를 눌러 조정하고, `r`을 눌러 자동 감지된 기본값으로 재설정하고, `Enter`를 눌러 저장합니다. 명령은 `CLAUDE_CODE_SCROLL_SPEED` 환경 변수가 설정하는 동일한 값을 작성하며, `~/.claude/settings.json`에 유지됩니다. 이 명령은 JetBrains IDE 터미널에서 사용할 수 없습니다.109스크롤 속도를 대화형으로 조정하려면 `/scroll-speed`를 실행합니다. 대화는 열려 있는 동안 스크롤할 수 있는 눈금자를 표시하므로 변경 사항을 즉시 느낄 수 있습니다. `←` 및 `→`를 눌러 조정하고, `r`을 눌러 자동 감지된 기본값으로 재설정하고, `Enter`를 눌러 저장합니다. 명령은 `CLAUDE_CODE_SCROLL_SPEED` 환경 변수가 설정하는 동일한 값을 작성하며, `~/.claude/settings.json`에 유지됩니다. 이 명령은 JetBrains IDE 터미널에서 사용할 수 없습니다.

110 110 

111기본 속도와 별도로 Claude Code는 휠을 빠르게 회전할 때 스크롤 속도를 가속화하므로 빠른 회전이 동일한 수의 느린 노치보다 더 많은 거리를 커버합니다. 가속을 끄고 노치당 일정한 속도를 유지하려면 [`settings.json`](/ko/settings#available-settings)에서 `wheelScrollAccelerationEnabled`를 `false`로 설정합니다. 이 설정에는 Claude Code v2.1.174 이상이 필요합니다.

112 

111<h3 id="scroll-in-the-jetbrains-ide-terminal">113<h3 id="scroll-in-the-jetbrains-ide-terminal">

112 JetBrains IDE 터미널에서 스크롤114 JetBrains IDE 터미널에서 스크롤

113</h3>115</h3>


171 173 

172마우스 캡처는 가장 일반적인 마찰 지점이며, 특히 SSH 또는 tmux 내에서 그렇습니다. Claude Code가 마우스 이벤트를 캡처하면 터미널의 기본 선택 시 복사가 작동하지 않습니다. 클릭 및 드래그로 만든 선택은 Claude Code 내부에 있으므로 터미널의 선택 버퍼에 없어서 tmux 복사 모드, Kitty 힌트 및 유사한 도구가 이를 볼 수 없습니다.174마우스 캡처는 가장 일반적인 마찰 지점이며, 특히 SSH 또는 tmux 내에서 그렇습니다. Claude Code가 마우스 이벤트를 캡처하면 터미널의 기본 선택 시 복사가 작동하지 않습니다. 클릭 및 드래그로 만든 선택은 Claude Code 내부에 있으므로 터미널의 선택 버퍼에 없어서 tmux 복사 모드, Kitty 힌트 및 유사한 도구가 이를 볼 수 없습니다.

173 175 

174Claude Code는 선택을 클립보드에 작성하려고 시도하지만 사용하는 경로는 설정에 따라 다릅니다. tmux 내에서는 tmux 붙여넣기 버퍼에 작성합니다. SSH를 통해서는 일부 터미널이 기본적으로 차단하는 OSC 52 이스케이프 시퀀스로 폴백합니다. iTerm2는 설정 → 일반 → 선택 → 터미널의 애플리케이션이 클립보드에 액세스할 수 있음을 켤 때까지 차단합니다. Claude Code는 각 복사 후 사용한 경로를 알려주는 토스트를 인쇄합니다.176Claude Code는 선택을 시스템 클립보드에 작성하며, 사용하는 경로는 설정에 따라 다릅니다. 로컬 세션에서는 기본 클립보드 도구를 실행합니다:

177 

178* **macOS**: `pbcopy`

179* **Linux**: Wayland의 경우 `wl-copy`, X11의 경우 설치된 `xclip` 또는 `xsel`. Claude Code는 클립보드와 PRIMARY 선택을 모두 작성하므로 중간 클릭 붙여넣기가 작동합니다.

180* **Windows 및 WSL**: PowerShell `Set-Clipboard`

181 

182tmux 내에서는 tmux 붙여넣기 버퍼에도 작성합니다. SSH를 통해서는 OSC 52 이스케이프 시퀀스로 폴백합니다. Claude Code는 각 복사 후 사용한 경로를 알려주는 토스트를 인쇄합니다.

183 

184일부 터미널은 기본적으로 OSC 52를 차단합니다. iTerm2는 설정 → 일반 → 선택 → 터미널의 애플리케이션이 클립보드에 액세스할 수 있음을 켤 때까지 차단합니다. iTerm2에서 [`/terminal-setup`](/ko/terminal-config)을 실행하면 이를 자동으로 활성화합니다.

185 

186일회성 기본 선택의 경우 사용할 키는 터미널에 따라 다릅니다:

187 

188* **Terminal.app**: `Fn`

189* **iTerm2**: `Option`

190* **VS Code, Cursor, 및 Devin Desktop**: `Shift`, 또는 `terminal.integrated.macOptionClickForcesSelection` 설정이 활성화된 macOS의 경우 `Option`

191* **대부분의 다른 터미널**: `Shift`

192 

193해당 키를 누른 상태에서 클릭 및 드래그합니다. 터미널이 선택을 Claude Code로 전달하는 대신 직접 처리하므로 `Cmd+C`와 같은 복사 단축키가 선택한 항목에 작동합니다. Claude Code는 화면 힌트에서도 올바른 키를 표시합니다.

175 194 

176일회성 기본 선택의 경우 터미널의 바이패스 수정자를 누른 상태에서 클릭 및 드래그합니다: iTerm2에서는 `Option`, 대부분의 Linux 및 Windows 터미널에서는 `Shift`. 수정자는 마우스 이벤트를 Claude Code로 전달하는 대신 터미널이 선택을 직접 처리하도록 지시하므로 `Cmd+C`와 터미널의 다른 복사 단축키가 작동합니다.195SSH 또는 tmux 내에서 Claude Code는 연결 중인 터미널을 항상 감지할 없으므로 힌트는 후보 키를 나열합니다.

177 196 

178기본 선택에 항상 의존하는 경우 `CLAUDE_CODE_DISABLE_MOUSE=1`을 설정하여 깜빡임 없는 렌더링과 평면 메모리를 유지하면서 마우스 캡처를 거부합니다:197기본 선택에 항상 의존하는 경우 `CLAUDE_CODE_DISABLE_MOUSE=1`을 설정하여 깜빡임 없는 렌더링과 평면 메모리를 유지하면서 마우스 캡처를 거부합니다:

179 198 

github-actions.md +102 −38

Details

12 Claude Code GitHub Actions는 [Claude Agent SDK](/ko/agent-sdk/overview)를 기반으로 구축되어 있으며, 이를 통해 Claude Code를 애플리케이션에 프로그래밍 방식으로 통합할 수 있습니다. SDK를 사용하여 GitHub Actions를 넘어서는 사용자 정의 자동화 워크플로우를 구축할 수 있습니다.12 Claude Code GitHub Actions는 [Claude Agent SDK](/ko/agent-sdk/overview)를 기반으로 구축되어 있으며, 이를 통해 Claude Code를 애플리케이션에 프로그래밍 방식으로 통합할 수 있습니다. SDK를 사용하여 GitHub Actions를 넘어서는 사용자 정의 자동화 워크플로우를 구축할 수 있습니다.

13</Note>13</Note>

14 14 

15<Info>15<h2 id="why-use-claude-code-github-actions">

16 **Claude Opus 4.8을 이제 사용할 수 있습니다.** Claude Code GitHub Actions는 기본적으로 Sonnet을 사용합니다. Opus 4.8을 사용하려면 [모델 파라미터](#breaking-changes-reference)를 `claude-opus-4-8`을 사용하도록 구성하십시오.16 Claude Code GitHub Actions를 사용하는 이유는 무엇입니까?

17</Info>17</h2>

18 

19## Claude Code GitHub Actions를 사용하는 이유는 무엇입니까?

20 18 

21* **즉시 PR 생성**: 필요한 사항을 설명하면 Claude가 모든 필요한 변경 사항이 포함된 완전한 PR을 생성합니다19* **즉시 PR 생성**: 필요한 사항을 설명하면 Claude가 모든 필요한 변경 사항이 포함된 완전한 PR을 생성합니다

22* **자동화된 코드 구현**: 이슈를 단일 명령으로 작동하는 코드로 변환합니다20* **자동화된 코드 구현**: 이슈를 단일 명령으로 작동하는 코드로 변환합니다


24* **간단한 설정**: 설치 프로그램과 API 키로 몇 분 안에 시작할 수 있습니다22* **간단한 설정**: 설치 프로그램과 API 키로 몇 분 안에 시작할 수 있습니다

25* **기본적으로 안전**: 코드는 Github의 러너에 유지됩니다23* **기본적으로 안전**: 코드는 Github의 러너에 유지됩니다

26 24 

27## Claude가 할 수 있는 것은 무엇입니까?25<h2 id="what-can-claude-do">

26 Claude가 할 수 있는 것은 무엇입니까?

27</h2>

28 28 

29Claude Code는 코드 작업 방식을 변환하는 강력한 GitHub Action을 제공합니다:29Claude Code는 코드 작업 방식을 변환하는 강력한 GitHub Action을 제공합니다:

30 30 

31### Claude Code Action31<h3 id="claude-code-action">

32 Claude Code Action

33</h3>

32 34 

33이 GitHub Action을 사용하면 GitHub Actions 워크플로우 내에서 Claude Code를 실행할 수 있습니다. 이를 사용하여 Claude Code 위에 사용자 정의 워크플로우를 구축할 수 있습니다.35이 GitHub Action을 사용하면 GitHub Actions 워크플로우 내에서 Claude Code를 실행할 수 있습니다. 이를 사용하여 Claude Code 위에 사용자 정의 워크플로우를 구축할 수 있습니다.

34 36 

35[저장소 보기 →](https://github.com/anthropics/claude-code-action)37[저장소 보기 →](https://github.com/anthropics/claude-code-action)

36 38 

37## 설정39<h2 id="setup">

40 설정

41</h2>

38 42 

39## 빠른 설정43<h2 id="quick-setup">

44 빠른 설정

45</h2>

40 46 

41이 작업을 설정하는 가장 쉬운 방법은 터미널에서 Claude Code를 통하는 것입니다. claude를 열고 `/install-github-app`을 실행하면 됩니다.47이 작업을 설정하는 가장 쉬운 방법은 터미널에서 Claude Code를 통하는 것입니다. claude를 열고 `/install-github-app`을 실행하면 됩니다.

42 48 


48 * 이 빠른 시작 방법은 직접 Claude API 사용자만 사용할 수 있습니다. Amazon Bedrock 또는 Google Vertex AI를 사용 중인 경우 [Amazon Bedrock & Google Vertex AI 사용](#using-with-amazon-bedrock-%26-google-vertex-ai) 섹션을 참조하십시오.54 * 이 빠른 시작 방법은 직접 Claude API 사용자만 사용할 수 있습니다. Amazon Bedrock 또는 Google Vertex AI를 사용 중인 경우 [Amazon Bedrock & Google Vertex AI 사용](#using-with-amazon-bedrock-%26-google-vertex-ai) 섹션을 참조하십시오.

49</Note>55</Note>

50 56 

51## 수동 설정57<h2 id="manual-setup">

58 수동 설정

59</h2>

52 60 

53`/install-github-app` 명령이 실패하거나 수동 설정을 선호하는 경우 다음 수동 설정 지침을 따르십시오:61`/install-github-app` 명령이 실패하거나 수동 설정을 선호하는 경우 다음 수동 설정 지침을 따르십시오:

54 62 


68 빠른 시작 또는 수동 설정을 완료한 후 이슈 또는 PR 댓글에서 `@claude`를 태그하여 작업을 테스트합니다.76 빠른 시작 또는 수동 설정을 완료한 후 이슈 또는 PR 댓글에서 `@claude`를 태그하여 작업을 테스트합니다.

69</Tip>77</Tip>

70 78 

71## 베타에서 업그레이드79<h2 id="upgrading-from-beta">

80 베타에서 업그레이드

81</h2>

72 82 

73<Warning>83<Warning>

74 Claude Code GitHub Actions v1.0은 베타 버전에서 v1.0으로 업그레이드하기 위해 워크플로우 파일을 업데이트해야 하는 주요 변경 사항을 도입합니다.84 Claude Code GitHub Actions v1.0은 베타 버전에서 v1.0으로 업그레이드하기 위해 워크플로우 파일을 업데이트해야 하는 주요 변경 사항을 도입합니다.


76 86 

77현재 Claude Code GitHub Actions의 베타 버전을 사용 중인 경우 워크플로우를 GA 버전을 사용하도록 업데이트하는 것이 좋습니다. 새 버전은 자동 모드 감지와 같은 강력한 새 기능을 추가하면서 구성을 단순화합니다.87현재 Claude Code GitHub Actions의 베타 버전을 사용 중인 경우 워크플로우를 GA 버전을 사용하도록 업데이트하는 것이 좋습니다. 새 버전은 자동 모드 감지와 같은 강력한 새 기능을 추가하면서 구성을 단순화합니다.

78 88 

79### 필수 변경 사항89<h3 id="essential-changes">

90 필수 변경 사항

91</h3>

80 92 

81모든 베타 사용자는 업그레이드하기 위해 워크플로우 파일에서 다음 변경 사항을 수행해야 합니다:93모든 베타 사용자는 업그레이드하기 위해 워크플로우 파일에서 다음 변경 사항을 수행해야 합니다:

82 94 


853. **프롬프트 입력 업데이트**: `direct_prompt`를 `prompt`로 바꿉니다973. **프롬프트 입력 업데이트**: `direct_prompt`를 `prompt`로 바꿉니다

864. **CLI 옵션 이동**: `max_turns`, `model`, `custom_instructions` 등을 `claude_args`로 변환합니다984. **CLI 옵션 이동**: `max_turns`, `model`, `custom_instructions` 등을 `claude_args`로 변환합니다

87 99 

88### 주요 변경 사항 참조100<h3 id="breaking-changes-reference">

101 주요 변경 사항 참조

102</h3>

89 103 

90| 이전 베타 입력 | 새 v1.0 입력 |104| 이전 베타 입력 | 새 v1.0 입력 |

91| --------------------- | ------------------------------------- |105| --------------------- | ------------------------------------- |


99| `disallowed_tools` | `claude_args: --disallowedTools` |113| `disallowed_tools` | `claude_args: --disallowedTools` |

100| `claude_env` | `settings` JSON 형식 |114| `claude_env` | `settings` JSON 형식 |

101 115 

102### 이전 및 이후 예제116<h3 id="before-and-after-example">

117 이전 및 이후 예제

118</h3>

103 119 

104**베타 버전:**120**베타 버전:**

105 121 


131 작업은 이제 구성에 따라 대화형 모드(`@claude` 멘션에 응답) 또는 자동화 모드(프롬프트로 즉시 실행)에서 실행할지 여부를 자동으로 감지합니다.147 작업은 이제 구성에 따라 대화형 모드(`@claude` 멘션에 응답) 또는 자동화 모드(프롬프트로 즉시 실행)에서 실행할지 여부를 자동으로 감지합니다.

132</Tip>148</Tip>

133 149 

134## 예제 사용 사례150<h2 id="example-use-cases">

151 예제 사용 사례

152</h2>

135 153 

136Claude Code GitHub Actions는 다양한 작업에 도움이 될 수 있습니다. [examples 디렉토리](https://github.com/anthropics/claude-code-action/tree/main/examples)에는 다양한 시나리오에 대한 즉시 사용 가능한 워크플로우가 포함되어 있습니다.154Claude Code GitHub Actions는 다양한 작업에 도움이 될 수 있습니다. [examples 디렉토리](https://github.com/anthropics/claude-code-action/tree/main/examples)에는 다양한 시나리오에 대한 즉시 사용 가능한 워크플로우가 포함되어 있습니다.

137 155 

138### 기본 워크플로우156<h3 id="basic-workflow">

157 기본 워크플로우

158</h3>

139 159 

140```yaml theme={null}160```yaml theme={null}

141name: Claude Code161name: Claude Code


154 # Responds to @claude mentions in comments174 # Responds to @claude mentions in comments

155```175```

156 176 

157### skills 사용177<h3 id="using-skills">

178 skills 사용

179</h3>

158 180 

159`prompt` 입력은 [skill](/ko/skills) 호출뿐만 아니라 일반 텍스트도 허용합니다:181`prompt` 입력은 [skill](/ko/skills) 호출뿐만 아니라 일반 텍스트도 허용합니다:

160 182 


180 prompt: "/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"202 prompt: "/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"

181```203```

182 204 

183### 프롬프트를 사용한 사용자 정의 자동화205<h3 id="custom-automation-with-prompts">

206 프롬프트를 사용한 사용자 정의 자동화

207</h3>

184 208 

185```yaml theme={null}209```yaml theme={null}

186name: Daily Report210name: Daily Report


198 claude_args: "--model opus"222 claude_args: "--model opus"

199```223```

200 224 

201### 일반적인 사용 사례225<h3 id="common-use-cases">

226 일반적인 사용 사례

227</h3>

202 228 

203이슈 또는 PR 댓글에서:229이슈 또는 PR 댓글에서:

204 230 


210 236 

211Claude는 자동으로 컨텍스트를 분석하고 적절하게 응답합니다.237Claude는 자동으로 컨텍스트를 분석하고 적절하게 응답합니다.

212 238 

213## 모범 사례239<h2 id="best-practices">

240 모범 사례

241</h2>

214 242 

215### CLAUDE.md 구성243<h3 id="claude-md-configuration">

244 CLAUDE.md 구성

245</h3>

216 246 

217저장소 루트에 `CLAUDE.md` 파일을 생성하여 코드 스타일 지침, 리뷰 기준, 프로젝트별 규칙 및 선호하는 패턴을 정의합니다. 이 파일은 Claude의 프로젝트 표준 이해를 안내합니다.247저장소 루트에 `CLAUDE.md` 파일을 생성하여 코드 스타일 지침, 리뷰 기준, 프로젝트별 규칙 및 선호하는 패턴을 정의합니다. 이 파일은 Claude의 프로젝트 표준 이해를 안내합니다.

218 248 

219### 보안 고려 사항249<h3 id="security-considerations">

250 보안 고려 사항

251</h3>

220 252 

221<Warning>API 키를 저장소에 직접 커밋하지 마십시오.</Warning>253<Warning>API 키를 저장소에 직접 커밋하지 마십시오.</Warning>

222 254 


231 263 

232API 키를 워크플로우 파일에 직접 하드코딩하는 대신 항상 GitHub Secrets(예: `${{ secrets.ANTHROPIC_API_KEY }}`)를 사용합니다.264API 키를 워크플로우 파일에 직접 하드코딩하는 대신 항상 GitHub Secrets(예: `${{ secrets.ANTHROPIC_API_KEY }}`)를 사용합니다.

233 265 

234### 성능 최적화266<h3 id="optimizing-performance">

267 성능 최적화

268</h3>

235 269 

236이슈 템플릿을 사용하여 컨텍스트를 제공하고, `CLAUDE.md`를 간결하고 집중적으로 유지하고, 워크플로우에 적절한 타임아웃을 구성합니다.270이슈 템플릿을 사용하여 컨텍스트를 제공하고, `CLAUDE.md`를 간결하고 집중적으로 유지하고, 워크플로우에 적절한 타임아웃을 구성합니다.

237 271 

238### CI 비용272<h3 id="ci-costs">

273 CI 비용

274</h3>

239 275 

240Claude Code GitHub Actions를 사용할 때 관련 비용을 인식합니다:276Claude Code GitHub Actions를 사용할 때 관련 비용을 인식합니다:

241 277 


257* 워크플로우 수준 타임아웃을 설정하여 실행 중인 작업을 방지합니다293* 워크플로우 수준 타임아웃을 설정하여 실행 중인 작업을 방지합니다

258* GitHub의 동시성 제어를 사용하여 병렬 실행을 제한하는 것을 고려합니다294* GitHub의 동시성 제어를 사용하여 병렬 실행을 제한하는 것을 고려합니다

259 295 

260## 구성 예제296<h2 id="configuration-examples">

297 구성 예제

298</h2>

261 299 

262Claude Code Action v1은 통합 파라미터로 구성을 단순화합니다:300Claude Code Action v1은 통합 파라미터로 구성을 단순화합니다:

263 301 


282 이슈 또는 PR 댓글에 응답할 때 Claude는 자동으로 @claude 멘션에 응답합니다. 다른 이벤트의 경우 `prompt` 파라미터를 사용하여 지침을 제공합니다.320 이슈 또는 PR 댓글에 응답할 때 Claude는 자동으로 @claude 멘션에 응답합니다. 다른 이벤트의 경우 `prompt` 파라미터를 사용하여 지침을 제공합니다.

283</Tip>321</Tip>

284 322 

285## Amazon Bedrock & Google Vertex AI 사용323<h2 id="using-with-amazon-bedrock--google-vertex-ai">

324 Amazon Bedrock & Google Vertex AI 사용

325</h2>

286 326 

287엔터프라이즈 환경의 경우 자신의 클라우드 인프라와 함께 Claude Code GitHub Actions를 사용할 수 있습니다. 이 접근 방식은 동일한 기능을 유지하면서 데이터 거주지 및 청구에 대한 제어를 제공합니다.327엔터프라이즈 환경의 경우 자신의 클라우드 인프라와 함께 Claude Code GitHub Actions를 사용할 수 있습니다. 이 접근 방식은 동일한 기능을 유지하면서 데이터 거주지 및 청구에 대한 제어를 제공합니다.

288 328 

289### 필수 조건329<h3 id="prerequisites">

330 필수 조건

331</h3>

290 332 

291클라우드 공급자와 함께 Claude Code GitHub Actions를 설정하기 전에 다음이 필요합니다:333클라우드 공급자와 함께 Claude Code GitHub Actions를 설정하기 전에 다음이 필요합니다:

292 334 

293#### Google Cloud Vertex AI의 경우:335<h4 id="for-google-cloud-vertex-ai">

336 Google Cloud Vertex AI의 경우:

337</h4>

294 338 

2951. Vertex AI가 활성화된 Google Cloud 프로젝트3391. Vertex AI가 활성화된 Google Cloud 프로젝트

2962. GitHub Actions에 대해 구성된 Workload Identity Federation3402. GitHub Actions에 대해 구성된 Workload Identity Federation

2973. 필요한 권한이 있는 서비스 계정3413. 필요한 권한이 있는 서비스 계정

2984. GitHub 앱(권장) 또는 기본 GITHUB\_TOKEN 사용3424. GitHub 앱(권장) 또는 기본 GITHUB\_TOKEN 사용

299 343 

300#### Amazon Bedrock의 경우:344<h4 id="for-amazon-bedrock">

345 Amazon Bedrock의 경우:

346</h4>

301 347 

3021. Amazon Bedrock이 활성화된 AWS 계정3481. Amazon Bedrock이 활성화된 AWS 계정

3032. AWS에서 구성된 GitHub OIDC Identity Provider3492. AWS에서 구성된 GitHub OIDC Identity Provider


609 </Step>655 </Step>

610</Steps>656</Steps>

611 657 

612## 문제 해결658<h2 id="troubleshooting">

659 문제 해결

660</h2>

613 661 

614### Claude가 @claude 명령에 응답하지 않음662<h3 id="claude-not-responding-to-claude-commands">

663 Claude가 @claude 명령에 응답하지 않음

664</h3>

615 665 

616GitHub 앱이 올바르게 설치되었는지 확인하고, 워크플로우가 활성화되었는지 확인하고, API 키가 저장소 시크릿에 설정되었는지 확인하고, 댓글에 `@claude`가 포함되어 있는지 확인합니다 (`/claude` 아님).666GitHub 앱이 올바르게 설치되었는지 확인하고, 워크플로우가 활성화되었는지 확인하고, API 키가 저장소 시크릿에 설정되었는지 확인하고, 댓글에 `@claude`가 포함되어 있는지 확인합니다 (`/claude` 아님).

617 667 

618### Claude의 커밋에서 CI가 실행되지 않음668<h3 id="ci-not-running-on-claude’s-commits">

669 Claude의 커밋에서 CI가 실행되지 않음

670</h3>

619 671 

620GitHub 앱 또는 사용자 정의 앱을 사용 중인지 확인합니다 (Actions 사용자 아님), 워크플로우 트리거에 필요한 이벤트가 포함되어 있는지 확인하고, 앱 권한에 CI 트리거가 포함되어 있는지 확인합니다.672GitHub 앱 또는 사용자 정의 앱을 사용 중인지 확인합니다 (Actions 사용자 아님), 워크플로우 트리거에 필요한 이벤트가 포함되어 있는지 확인하고, 앱 권한에 CI 트리거가 포함되어 있는지 확인합니다.

621 673 

622### 인증 오류674<h3 id="authentication-errors">

675 인증 오류

676</h3>

623 677 

624API 키가 유효하고 충분한 권한이 있는지 확인합니다. Bedrock/Vertex의 경우 자격 증명 구성을 확인하고 시크릿이 워크플로우에서 올바르게 명명되었는지 확인합니다.678API 키가 유효하고 충분한 권한이 있는지 확인합니다. Bedrock/Vertex의 경우 자격 증명 구성을 확인하고 시크릿이 워크플로우에서 올바르게 명명되었는지 확인합니다.

625 679 

626## 고급 구성680<h2 id="advanced-configuration">

681 고급 구성

682</h2>

627 683 

628### 작업 파라미터684<h3 id="action-parameters">

685 작업 파라미터

686</h3>

629 687 

630Claude Code Action v1은 단순화된 구성을 사용합니다:688Claude Code Action v1은 단순화된 구성을 사용합니다:

631 689 


644\*프롬프트는 선택 사항입니다. 이슈/PR 댓글에서 생략하면 Claude는 트리거 구문에 응답합니다\702\*프롬프트는 선택 사항입니다. 이슈/PR 댓글에서 생략하면 Claude는 트리거 구문에 응답합니다\

645\*\*직접 Claude API에 필수이며, Bedrock/Vertex에는 필수가 아닙니다703\*\*직접 Claude API에 필수이며, Bedrock/Vertex에는 필수가 아닙니다

646 704 

647#### CLI 인수 전달705<h4 id="pass-cli-arguments">

706 CLI 인수 전달

707</h4>

648 708 

649`claude_args` 파라미터는 모든 Claude Code CLI 인수를 허용합니다:709`claude_args` 파라미터는 모든 Claude Code CLI 인수를 허용합니다:

650 710 


660* `--allowedTools`: 허용된 도구의 쉼표로 구분된 목록. `--allowed-tools` 별칭도 작동합니다.720* `--allowedTools`: 허용된 도구의 쉼표로 구분된 목록. `--allowed-tools` 별칭도 작동합니다.

661* `--debug`: 디버그 출력 활성화721* `--debug`: 디버그 출력 활성화

662 722 

663### 대체 통합 방법723<h3 id="alternative-integration-methods">

724 대체 통합 방법

725</h3>

664 726 

665`/install-github-app` 명령이 권장되는 접근 방식이지만 다음을 수행할 수도 있습니다:727`/install-github-app` 명령이 권장되는 접근 방식이지만 다음을 수행할 수도 있습니다:

666 728 


670 732 

671자세한 인증, 보안 및 고급 구성 가이드는 [Claude Code Action 설명서](https://github.com/anthropics/claude-code-action/blob/main/docs)를 참조하십시오.733자세한 인증, 보안 및 고급 구성 가이드는 [Claude Code Action 설명서](https://github.com/anthropics/claude-code-action/blob/main/docs)를 참조하십시오.

672 734 

673### Claude의 동작 사용자 정의735<h3 id="customizing-claude’s-behavior">

736 Claude의 동작 사용자 정의

737</h3>

674 738 

675두 가지 방법으로 Claude의 동작을 구성할 수 있습니다:739두 가지 방법으로 Claude의 동작을 구성할 수 있습니다:

676 740 

Details

110claude --remote "Add retry logic to the payment webhook handler"110claude --remote "Add retry logic to the payment webhook handler"

111```111```

112 112 

113세션은 Anthropic 인프라에서 실행되고, GHES에서 저장소를 복제하며, 변경 사항을 분기로 다시 푸시합니다. `/tasks`를 사용하거나 [claude.ai/code](https://claude.ai/code)에서 진행 상황을 모니터링합니다. diff 리뷰, 자동 수정 및 루틴을 포함한 전체 원격 세션 워크플로우는 [웹에서 Claude Code](/ko/claude-code-on-the-web)를 참조하십시오.113세션은 Anthropic 인프라에서 실행되고, GHES에서 저장소를 복제하며, 변경 사항을 분기로 다시 푸시합니다. `/tasks`를 사용하거나 [claude.ai/code](https://claude.ai/code)에서 진행 상황을 모니터링합니다. diff 리뷰, 자동 수정 및 루틴을 포함한 전체 클라우드 세션 워크플로우는 [웹에서 Claude Code](/ko/claude-code-on-the-web)를 참조하십시오.

114 114 

115<h3 id="teleport-sessions-to-your-terminal">115<h3 id="teleport-sessions-to-your-terminal">

116 세션을 터미널로 Teleport116 터미널로 세션 Teleport

117</h3>117</h3>

118 118 

119`claude --teleport`를 사용하여 웹 세션을 로컬 터미널로 가져옵니다. Teleport는 분기를 가져오고 세션 기록을 로드하기 전에 동일한 GHES 저장소의 체크아웃에 있는지 확인합니다. 자세한 내용은 [teleport 요구 사항](/ko/claude-code-on-the-web#teleport-requirements)을 참조하십시오.119`claude --teleport`를 사용하여 웹 세션을 로컬 터미널로 가져옵니다. Teleport는 분기를 가져오고 세션 기록을 로드하기 전에 동일한 GHES 저장소의 체크아웃에 있는지 확인합니다. 자세한 내용은 [teleport 요구 사항](/ko/claude-code-on-the-web#teleport-requirements)을 참조하십시오.


205 GHES 인스턴스에 도달할 수 없음205 GHES 인스턴스에 도달할 수 없음

206</h3>206</h3>

207 207 

208리뷰 또는 웹 세션이 시간 초과되면 GHES 인스턴스가 Anthropic 인프라에서 도달 가능하지 않을 수 있습니다. 방화벽이 [Anthropic API IP 주소](https://platform.claude.com/docs/en/api/ip-addresses)에서 인바운드 연결을 허용하는지 확인합니다.208리뷰 또는 웹 세션이 시간 초과되면 GHES 인스턴스가 Anthropic 인프라에서 도달 가능하지 않을 수 있습니다. 방화벽이 [Anthropic API IP 주소](https://platform.claude.com/docs/ko/api/ip-addresses)에서 인바운드 연결을 허용하는지 확인합니다.

209 209 

210<h2 id="related-resources">210<h2 id="related-resources">

211 관련 리소스211 관련 리소스

gitlab-ci-cd.md +85 −29

Details

16 이 통합은 [Claude Code CLI and Agent SDK](/ko/agent-sdk/overview) 위에 구축되어 있으며, CI/CD 작업 및 사용자 정의 자동화 워크플로우에서 Claude를 프로그래밍 방식으로 사용할 수 있습니다.16 이 통합은 [Claude Code CLI and Agent SDK](/ko/agent-sdk/overview) 위에 구축되어 있으며, CI/CD 작업 및 사용자 정의 자동화 워크플로우에서 Claude를 프로그래밍 방식으로 사용할 수 있습니다.

17</Note>17</Note>

18 18 

19## GitLab에서 Claude Code를 사용하는 이유19<h2 id="why-use-claude-code-with-gitlab">

20 GitLab에서 Claude Code를 사용하는 이유

21</h2>

20 22 

21* **즉시 MR 생성**: 필요한 사항을 설명하면 Claude가 변경 사항과 설명이 포함된 완전한 MR을 제안합니다23* **즉시 MR 생성**: 필요한 사항을 설명하면 Claude가 변경 사항과 설명이 포함된 완전한 MR을 제안합니다

22* **자동화된 구현**: 단일 명령 또는 언급으로 이슈를 작동하는 코드로 변환합니다24* **자동화된 구현**: 단일 명령 또는 언급으로 이슈를 작동하는 코드로 변환합니다


25* **엔터프라이즈 준비**: Claude API, Amazon Bedrock 또는 Google Vertex AI를 선택하여 데이터 거주지 및 조달 요구 사항을 충족합니다27* **엔터프라이즈 준비**: Claude API, Amazon Bedrock 또는 Google Vertex AI를 선택하여 데이터 거주지 및 조달 요구 사항을 충족합니다

26* **기본적으로 안전**: GitLab 러너에서 실행되며 브랜치 보호 및 승인이 적용됩니다28* **기본적으로 안전**: GitLab 러너에서 실행되며 브랜치 보호 및 승인이 적용됩니다

27 29 

28## 작동 방식30<h2 id="how-it-works">

31 작동 방식

32</h2>

29 33 

30Claude Code는 GitLab CI/CD를 사용하여 격리된 작업에서 AI 작업을 실행하고 MR을 통해 결과를 다시 커밋합니다:34Claude Code는 GitLab CI/CD를 사용하여 격리된 작업에서 AI 작업을 실행하고 MR을 통해 결과를 다시 커밋합니다:

31 35 


40 44 

41지역 엔드포인트를 선택하여 지연 시간을 줄이고 기존 클라우드 계약을 사용하면서 데이터 주권 요구 사항을 충족합니다.45지역 엔드포인트를 선택하여 지연 시간을 줄이고 기존 클라우드 계약을 사용하면서 데이터 주권 요구 사항을 충족합니다.

42 46 

43## Claude가 할 수 있는 47<h2 id="what-can-claude-do">

48 Claude가 할 수 있는 것

49</h2>

44 50 

45Claude Code는 코드 작업 방식을 변환하는 강력한 CI/CD 워크플로우를 활성화합니다:51Claude Code는 코드 작업 방식을 변환하는 강력한 CI/CD 워크플로우를 활성화합니다:

46 52 


50* 테스트 또는 댓글로 식별된 버그 및 회귀 수정56* 테스트 또는 댓글로 식별된 버그 및 회귀 수정

51* 후속 댓글에 응답하여 요청된 변경 사항에 대해 반복57* 후속 댓글에 응답하여 요청된 변경 사항에 대해 반복

52 58 

53## 설정59<h2 id="setup">

60 설정

61</h2>

54 62 

55### 빠른 설정63<h3 id="quick-setup">

64 빠른 설정

65</h3>

56 66 

57가장 빠른 시작 방법은 `.gitlab-ci.yml`에 최소 작업을 추가하고 API 키를 마스킹된 변수로 설정하는 것입니다.67가장 빠른 시작 방법은 `.gitlab-ci.yml`에 최소 작업을 추가하고 API 키를 마스킹된 변수로 설정하는 것입니다.

58 68 


98작업과 `ANTHROPIC_API_KEY` 변수를 추가한 후 **CI/CD** → **파이프라인**에서 작업을 수동으로 실행하여 테스트하거나, MR에서 트리거하여 Claude가 브랜치에서 업데이트를 제안하고 필요한 경우 MR을 열도록 합니다.108작업과 `ANTHROPIC_API_KEY` 변수를 추가한 후 **CI/CD** → **파이프라인**에서 작업을 수동으로 실행하여 테스트하거나, MR에서 트리거하여 Claude가 브랜치에서 업데이트를 제안하고 필요한 경우 MR을 열도록 합니다.

99 109 

100<Note>110<Note>

101 Claude API 대신 Amazon Bedrock 또는 Google Vertex AI에서 실행하려면 아래의 [Amazon Bedrock & Google Vertex AI 사용](#amazon-bedrock--google-vertex-ai-사용) 섹션을 참조하여 인증 및 환경 설정을 확인하세요.111 Claude API 대신 Amazon Bedrock 또는 Google Vertex AI에서 실행하려면 아래의 [Amazon Bedrock & Google Vertex AI 사용](#using-with-amazon-bedrock-%26-google-vertex-ai) 섹션을 참조하여 인증 및 환경 설정을 확인하세요.

102</Note>112</Note>

103 113 

104### 수동 설정 (프로덕션에 권장)114<h3 id="manual-setup-recommended-for-production">

115 수동 설정 (프로덕션에 권장)

116</h3>

105 117 

106더 제어된 설정을 선호하거나 엔터프라이즈 공급자가 필요한 경우:118더 제어된 설정을 선호하거나 엔터프라이즈 공급자가 필요한 경우:

107 119 


120 * 이벤트 리스너에 "댓글 (노트)"에 대한 프로젝트 웹훅을 추가합니다 (사용하는 경우)132 * 이벤트 리스너에 "댓글 (노트)"에 대한 프로젝트 웹훅을 추가합니다 (사용하는 경우)

121 * 댓글에 `@claude`가 포함될 때 `AI_FLOW_INPUT` 및 `AI_FLOW_CONTEXT`와 같은 변수로 파이프라인 트리거 API를 호출하도록 리스너를 설정합니다133 * 댓글에 `@claude`가 포함될 때 `AI_FLOW_INPUT` 및 `AI_FLOW_CONTEXT`와 같은 변수로 파이프라인 트리거 API를 호출하도록 리스너를 설정합니다

122 134 

123## 예제 사용 사례135<h2 id="example-use-cases">

136 예제 사용 사례

137</h2>

124 138 

125### 이슈를 MR로 변환139<h3 id="turn-issues-into-mrs">

140 이슈를 MR로 변환

141</h3>

126 142 

127이슈 댓글에서:143이슈 댓글에서:

128 144 


132 148 

133Claude는 이슈 및 코드베이스를 분석하고, 브랜치에서 변경 사항을 작성하고, 검토를 위해 MR을 엽니다.149Claude는 이슈 및 코드베이스를 분석하고, 브랜치에서 변경 사항을 작성하고, 검토를 위해 MR을 엽니다.

134 150 

135### 구현 도움 받기151<h3 id="get-implementation-help">

152 구현 도움 받기

153</h3>

136 154 

137MR 토론에서:155MR 토론에서:

138 156 


142 160 

143Claude는 변경 사항을 제안하고, 적절한 캐싱으로 코드를 추가하고, MR을 업데이트합니다.161Claude는 변경 사항을 제안하고, 적절한 캐싱으로 코드를 추가하고, MR을 업데이트합니다.

144 162 

145### 버그 빠르게 수정163<h3 id="fix-bugs-quickly">

164 버그 빠르게 수정

165</h3>

146 166 

147이슈 또는 MR 댓글에서:167이슈 또는 MR 댓글에서:

148 168 


152 172 

153Claude는 버그를 찾고, 수정을 구현하고, 브랜치를 업데이트하거나 새 MR을 엽니다.173Claude는 버그를 찾고, 수정을 구현하고, 브랜치를 업데이트하거나 새 MR을 엽니다.

154 174 

155## Amazon Bedrock & Google Vertex AI 사용175<h2 id="using-with-amazon-bedrock--google-vertex-ai">

176 Amazon Bedrock & Google Vertex AI 사용

177</h2>

156 178 

157엔터프라이즈 환경의 경우 동일한 개발자 경험으로 클라우드 인프라에서 완전히 Claude Code를 실행할 수 있습니다.179엔터프라이즈 환경의 경우 동일한 개발자 경험으로 클라우드 인프라에서 완전히 Claude Code를 실행할 수 있습니다.

158 180 


238 </Tab>260 </Tab>

239</Tabs>261</Tabs>

240 262 

241## 구성 예제263<h2 id="configuration-examples">

264 구성 예제

265</h2>

242 266 

243파이프라인에 맞게 조정할 수 있는 즉시 사용 가능한 스니펫입니다.267파이프라인에 맞게 조정할 수 있는 즉시 사용 가능한 스니펫입니다.

244 268 

245### 기본 .gitlab-ci.yml (Claude API)269<h3 id="basic-gitlab-ci-yml-claude-api">

270 기본 .gitlab-ci.yml (Claude API)

271</h3>

246 272 

247```yaml theme={null}273```yaml theme={null}

248stages:274stages:


271 # Claude Code는 CI/CD 변수에서 ANTHROPIC_API_KEY를 사용합니다297 # Claude Code는 CI/CD 변수에서 ANTHROPIC_API_KEY를 사용합니다

272```298```

273 299 

274### Amazon Bedrock 작업 예제 (OIDC)300<h3 id="amazon-bedrock-job-example-oidc">

301 Amazon Bedrock 작업 예제 (OIDC)

302</h3>

275 303 

276**필수 조건:**304**필수 조건:**

277 305 


322 Bedrock의 모델 ID에는 지역별 접두사가 포함됩니다 (예: `us.anthropic.claude-sonnet-4-6`). 워크플로우에서 지원하는 경우 작업 구성 또는 프롬프트를 통해 원하는 모델을 전달합니다.350 Bedrock의 모델 ID에는 지역별 접두사가 포함됩니다 (예: `us.anthropic.claude-sonnet-4-6`). 워크플로우에서 지원하는 경우 작업 구성 또는 프롬프트를 통해 원하는 모델을 전달합니다.

323</Note>351</Note>

324 352 

325### Google Vertex AI 작업 예제 (Workload Identity Federation)353<h3 id="google-vertex-ai-job-example-workload-identity-federation">

354 Google Vertex AI 작업 예제 (Workload Identity Federation)

355</h3>

326 356 

327**필수 조건:**357**필수 조건:**

328 358 


375 Workload Identity Federation을 사용하면 서비스 계정 키를 저장할 필요가 없습니다. 저장소별 신뢰 조건 및 최소 권한 서비스 계정을 사용합니다.405 Workload Identity Federation을 사용하면 서비스 계정 키를 저장할 필요가 없습니다. 저장소별 신뢰 조건 및 최소 권한 서비스 계정을 사용합니다.

376</Note>406</Note>

377 407 

378## 모범 사례408<h2 id="best-practices">

409 모범 사례

410</h2>

379 411 

380### CLAUDE.md 구성412<h3 id="claude-md-configuration">

413 CLAUDE.md 구성

414</h3>

381 415 

382저장소 루트에 `CLAUDE.md` 파일을 생성하여 코딩 표준, 검토 기준 및 프로젝트별 규칙을 정의합니다. Claude는 실행 중에 이 파일을 읽고 변경 사항을 제안할 때 규칙을 따릅니다.416저장소 루트에 `CLAUDE.md` 파일을 생성하여 코딩 표준, 검토 기준 및 프로젝트별 규칙을 정의합니다. Claude는 실행 중에 이 파일을 읽고 변경 사항을 제안할 때 규칙을 따릅니다.

383 417 

384### 보안 고려 사항418<h3 id="security-considerations">

419 보안 고려 사항

420</h3>

385 421 

386**API 키 또는 클라우드 자격 증명을 저장소에 커밋하지 마세요**. 항상 GitLab CI/CD 변수를 사용합니다:422**API 키 또는 클라우드 자격 증명을 저장소에 커밋하지 마세요**. 항상 GitLab CI/CD 변수를 사용합니다:

387 423 


390* 작업 권한 및 네트워크 송신 제한426* 작업 권한 및 네트워크 송신 제한

391* 다른 기여자처럼 Claude의 MR을 검토합니다427* 다른 기여자처럼 Claude의 MR을 검토합니다

392 428 

393### 성능 최적화429<h3 id="optimizing-performance">

430 성능 최적화

431</h3>

394 432 

395* `CLAUDE.md`를 집중적이고 간결하게 유지합니다433* `CLAUDE.md`를 집중적이고 간결하게 유지합니다

396* 명확한 이슈/MR 설명을 제공하여 반복을 줄입니다434* 명확한 이슈/MR 설명을 제공하여 반복을 줄입니다

397* 작업 시간 초과를 구성하여 실행 중단을 방지합니다435* 작업 시간 초과를 구성하여 실행 중단을 방지합니다

398* 가능한 경우 러너에서 npm 및 패키지 설치를 캐시합니다436* 가능한 경우 러너에서 npm 및 패키지 설치를 캐시합니다

399 437 

400### CI 비용438<h3 id="ci-costs">

439 CI 비용

440</h3>

401 441 

402GitLab CI/CD와 함께 Claude Code를 사용할 때 관련 비용을 인식합니다:442GitLab CI/CD와 함께 Claude Code를 사용할 때 관련 비용을 인식합니다:

403 443 


415 * 적절한 `max_turns` 및 작업 시간 초과 값을 설정합니다455 * 적절한 `max_turns` 및 작업 시간 초과 값을 설정합니다

416 * 동시성을 제한하여 병렬 실행을 제어합니다456 * 동시성을 제한하여 병렬 실행을 제어합니다

417 457 

418## 보안 및 거버넌스458<h2 id="security-and-governance">

459 보안 및 거버넌스

460</h2>

419 461 

420* 각 작업은 제한된 네트워크 액세스가 있는 격리된 컨테이너에서 실행됩니다462* 각 작업은 제한된 네트워크 액세스가 있는 격리된 컨테이너에서 실행됩니다

421* Claude의 변경 사항은 MR을 통해 흐르므로 검토자가 모든 diff를 봅니다463* Claude의 변경 사항은 MR을 통해 흐르므로 검토자가 모든 diff를 봅니다


423* Claude Code는 쓰기를 제한하기 위해 작업 공간 범위 권한을 사용합니다465* Claude Code는 쓰기를 제한하기 위해 작업 공간 범위 권한을 사용합니다

424* 자신의 공급자 자격 증명을 가져오기 때문에 비용이 제어됩니다466* 자신의 공급자 자격 증명을 가져오기 때문에 비용이 제어됩니다

425 467 

426## 문제 해결468<h2 id="troubleshooting">

469 문제 해결

470</h2>

427 471 

428### Claude가 @claude 명령에 응답하지 않음472<h3 id="claude-not-responding-to-claude-commands">

473 Claude가 @claude 명령에 응답하지 않음

474</h3>

429 475 

430* 파이프라인이 트리거되고 있는지 확인합니다 (수동, MR 이벤트 또는 노트 이벤트 리스너/웹훅을 통해)476* 파이프라인이 트리거되고 있는지 확인합니다 (수동, MR 이벤트 또는 노트 이벤트 리스너/웹훅을 통해)

431* CI/CD 변수 (`ANTHROPIC_API_KEY` 또는 클라우드 공급자 설정)가 있고 마스킹 해제되어 있는지 확인합니다477* CI/CD 변수 (`ANTHROPIC_API_KEY` 또는 클라우드 공급자 설정)가 있고 마스킹 해제되어 있는지 확인합니다

432* 댓글에 `@claude` (not `/claude`)가 포함되어 있고 언급 트리거가 구성되어 있는지 확인합니다478* 댓글에 `@claude` (not `/claude`)가 포함되어 있고 언급 트리거가 구성되어 있는지 확인합니다

433 479 

434### 작업이 댓글을 쓰거나 MR을 열 수 없음480<h3 id="job-can’t-write-comments-or-open-mrs">

481 작업이 댓글을 쓰거나 MR을 열 수 없음

482</h3>

435 483 

436* `CI_JOB_TOKEN`이 프로젝트에 대한 충분한 권한이 있거나 `api` 범위가 있는 프로젝트 액세스 토큰을 사용하는지 확인합니다484* `CI_JOB_TOKEN`이 프로젝트에 대한 충분한 권한이 있거나 `api` 범위가 있는 프로젝트 액세스 토큰을 사용하는지 확인합니다

437* `mcp__gitlab` 도구가 `--allowedTools`에서 활성화되어 있는지 확인합니다485* `mcp__gitlab` 도구가 `--allowedTools`에서 활성화되어 있는지 확인합니다

438* 작업이 MR의 컨텍스트에서 실행되거나 `AI_FLOW_*` 변수를 통해 충분한 컨텍스트가 있는지 확인합니다486* 작업이 MR의 컨텍스트에서 실행되거나 `AI_FLOW_*` 변수를 통해 충분한 컨텍스트가 있는지 확인합니다

439 487 

440### 인증 오류488<h3 id="authentication-errors">

489 인증 오류

490</h3>

441 491 

442* **Claude API의 경우**: `ANTHROPIC_API_KEY`가 유효하고 만료되지 않았는지 확인합니다492* **Claude API의 경우**: `ANTHROPIC_API_KEY`가 유효하고 만료되지 않았는지 확인합니다

443* **Bedrock/Vertex의 경우**: OIDC/WIF 구성, 역할 가장 및 비밀 이름을 확인합니다. 지역 및 모델 가용성을 확인합니다493* **Bedrock/Vertex의 경우**: OIDC/WIF 구성, 역할 가장 및 비밀 이름을 확인합니다. 지역 및 모델 가용성을 확인합니다

444 494 

445## 고급 구성495<h2 id="advanced-configuration">

496 고급 구성

497</h2>

446 498 

447### 일반적인 매개변수 및 변수499<h3 id="common-parameters-and-variables">

500 일반적인 매개변수 및 변수

501</h3>

448 502 

449Claude Code는 다음과 같이 일반적으로 사용되는 입력을 지원합니다:503Claude Code는 다음과 같이 일반적으로 사용되는 입력을 지원합니다:

450 504 


458 정확한 플래그 및 매개변수는 `@anthropic-ai/claude-code` 버전에 따라 다를 수 있습니다. 작업에서 `claude --help`를 실행하여 지원되는 옵션을 확인합니다.512 정확한 플래그 및 매개변수는 `@anthropic-ai/claude-code` 버전에 따라 다를 수 있습니다. 작업에서 `claude --help`를 실행하여 지원되는 옵션을 확인합니다.

459</Note>513</Note>

460 514 

461### Claude의 동작 사용자 정의515<h3 id="customizing-claude’s-behavior">

516 Claude의 동작 사용자 정의

517</h3>

462 518 

463두 가지 주요 방법으로 Claude를 안내할 수 있습니다:519두 가지 주요 방법으로 Claude를 안내할 수 있습니다:

464 520 

glossary.md +4 −4

Details

162 Effort level162 Effort level

163</h3>163</h3>

164 164 

165각 턴에서 Claude가 적응형 추론 사고 예산을 얼마나 사용할지 제어하는 설정입니다. 더 높은 노력은 더 많은 사고 토큰과 더 깊은 추론을 의미합니다. 더 낮은 노력은 더 빠르고 저렴합니다. Effort는 Opus 4.6 이상 및 Sonnet 4.6에서 지원됩니다.165각 턴에서 Claude가 적응형 추론 사고 예산을 얼마나 사용할지 제어하는 설정입니다. 더 높은 노력은 더 많은 사고 토큰과 더 깊은 추론을 의미합니다. 더 낮은 노력은 더 빠르고 저렴합니다. Effort는 Fable 5, Opus 4.6 이상 및 Sonnet 4.6에서 지원됩니다.

166 166 

167자세히 알아보기: [노력 수준 조정](/ko/model-config#adjust-effort-level)167자세히 알아보기: [노력 수준 조정](/ko/model-config#adjust-effort-level)

168 168 


170 Extended thinking170 Extended thinking

171</h3>171</h3>

172 172 

173모델이 응답하기 전에 수행하는 가시적인 단계별 추론입니다. `MAX_THINKING_TOKENS`로 사고 토큰을 제한하거나 [노력 수준](#effort-level) 조정할 수 있습니다. 사고는 터미널에서 회색 이탤릭 텍스트로 나타납니다.173모델이 응답하기 전에 수행하는 가시적인 단계별 추론입니다. [노력 수준](#effort-level)으로 조정하거나 고정된 사고 예산이 있는 모델에서 `MAX_THINKING_TOKENS`로 사고 토큰을 제한할 수 있습니다. 사고는 터미널에서 회색 이탤릭 텍스트로 나타납니다.

174 174 

175자세히 알아보기: [확장 사고 사용](/ko/model-config#extended-thinking)175자세히 알아보기: [확장 사고 사용](/ko/model-config#extended-thinking)

176 176 


284 Project trust284 Project trust

285</h3>285</h3>

286 286 

287Claude Code가 구성을 로드하기 전에 디렉토리를 수락하는 일회성 대화입니다. 수락은 프로젝트 디렉토리별로 저장되며, 홈 디렉토리는 제외되고, 여기서 신뢰는 현재 세션에만 유지되며 각 실행 시 프롬프트가 다시 나타납니다. 신뢰는 마켓플레이스 플러그인의 자동 설치 및 프로젝트 정의 훅의 실행을 게이팅합니다. 디렉토리를 신뢰하면 `.claude/settings.json`, `.mcp.json` 및 기타 구성 파일이 적용됩니다.287Claude Code가 구성을 로드하기 전에 디렉토리를 수락하는 대화입니다. 수락은 프로젝트 디렉토리별로 저장되며, 홈 디렉토리는 제외되고, 여기서 신뢰는 현재 세션에만 유지되며 각 실행 시 프롬프트가 다시 나타납니다. 신뢰는 마켓플레이스 플러그인의 자동 설치 및 프로젝트 정의 훅의 실행을 게이팅합니다. 디렉토리를 신뢰하면 `.claude/settings.json`, `.mcp.json` 및 기타 구성 파일이 적용됩니다.

288 288 

289자세히 알아보기: [`.claude` 디렉토리](/ko/claude-directory)289자세히 알아보기: [`.claude` 디렉토리](/ko/claude-directory)

290 290 


292 Prompt injection292 Prompt injection

293</h3>293</h3>

294 294 

295파일, 웹 페이지 또는 도구 결과에 포함된 적대적 지침이며, Claude를 요청하지 않은 작업으로 리디렉션하려고 시도합니다. Claude Code의 방어에는 권한 시스템, 명령 차단 목록 및 신뢰 확인이 포함됩니다. [Auto mode](#auto-mode)는 도구 결과에서 의심스러운 내용을 스캔하는 서버 측 프로브와 도구 결과를 보지 않는 분류기를 추가하므로 주입된 텍스트가 승인 결정에 영향을 미칠 수 없습니다.295파일, 웹 페이지 또는 도구 결과에 포함된 적대적 지침이며, Claude를 요청하지 않은 작업으로 리디렉션하려고 시도합니다. Claude Code의 방어에는 권한 시스템, 명령 주입 탐지 및 신뢰 확인이 포함됩니다. [Auto mode](#auto-mode)는 도구 결과에서 의심스러운 내용을 스캔하는 서버 측 프로브와 도구 결과를 보지 않는 분류기를 추가하므로 주입된 텍스트가 승인 결정에 영향을 미칠 수 없습니다.

296 296 

297자세히 알아보기: [프롬프트 주입으로부터 보호](/ko/security#protect-against-prompt-injection)297자세히 알아보기: [프롬프트 주입으로부터 보호](/ko/security#protect-against-prompt-injection)

298 298 

Details

6 6 

7> Google Vertex AI를 통해 Claude Code를 구성하는 방법을 알아봅니다. 설정, IAM 구성 및 문제 해결을 포함합니다.7> Google Vertex AI를 통해 Claude Code를 구성하는 방법을 알아봅니다. 설정, IAM 구성 및 문제 해결을 포함합니다.

8 8 

9export const ContactSalesCard = ({surface}) => {

10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;

11 const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

12 <line x1="5" y1="12" x2="19" y2="12" />

13 <polyline points="12 5 19 12 12 19" />

14 </svg>;

15 const STYLES = `

16.cc-cs {

17 --cs-slate: #141413;

18 --cs-clay: #d97757;

19 --cs-clay-deep: #c6613f;

20 --cs-gray-000: #ffffff;

21 --cs-gray-700: #3d3d3a;

22 --cs-border-default: rgba(31, 30, 29, 0.15);

23 font-family: inherit;

24}

25.dark .cc-cs {

26 --cs-slate: #f0eee6;

27 --cs-gray-000: #262624;

28 --cs-gray-700: #bfbdb4;

29 --cs-border-default: rgba(240, 238, 230, 0.14);

30}

31.cc-cs-card {

32 display: flex; align-items: center; justify-content: space-between;

33 gap: 16px; padding: 14px 16px; margin: 0;

34 background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default);

35 border-radius: 8px; flex-wrap: wrap;

36}

37.cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; }

38.cc-cs-text strong { font-weight: 550; color: var(--cs-slate); }

39.cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }

40.cc-cs-btn-clay {

41 display: inline-flex; align-items: center; gap: 8px;

42 background: var(--cs-clay-deep); color: #fff; border: none;

43 border-radius: 8px; padding: 8px 14px;

44 font-size: 13px; font-weight: 500;

45 transition: background-color 0.15s; white-space: nowrap;

46}

47.cc-cs-btn-clay:hover { background: var(--cs-clay); }

48.cc-cs-btn-ghost {

49 display: inline-flex; align-items: center; gap: 8px;

50 background: transparent; color: var(--cs-gray-700);

51 border: 0.5px solid var(--cs-border-default);

52 border-radius: 8px; padding: 8px 14px;

53 font-size: 13px; font-weight: 500;

54}

55.cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }

56.dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); }

57@media (max-width: 720px) {

58 .cc-cs-actions { width: 100%; }

59}

60`;

61 return <div className="cc-cs not-prose">

62 <style>{STYLES}</style>

63 <div className="cc-cs-card">

64 <div className="cc-cs-text">

65 <strong>Deploying Claude Code across your organization?</strong> Talk to sales about enterprise plans, SSO, and centralized billing.

66 </div>

67 <div className="cc-cs-actions">

68 <a href={`https://claude.com/pricing?${utm('view_plans')}#plans-business`} className="cc-cs-btn-ghost">

69 View plans

70 </a>

71 <a href={`https://claude.com/contact-sales?${utm('contact_sales')}`} className="cc-cs-btn-clay">

72 Contact sales {iconArrowRight()}

73 </a>

74 </div>

75 </div>

76 </div>;

77};

78 

79<ContactSalesCard surface="vertex" />

80 

9<h2 id="prerequisites">81<h2 id="prerequisites">

10 필수 요구사항82 필수 요구사항

11</h2>83</h2>


155</h3>227</h3>

156 228 

157<Warning>229<Warning>

158 여러 사용자에게 배포할 때 특정 모델 버전을 고정합니다. 고정하지 않으면 `sonnet` 및 `opus`와 같은 모델 별칭이 최신 버전으로 확인되며, Anthropic이 업데이트를 출시할 Vertex AI 프로젝트에서 아직 활성화되지 않았을 수 있습니다. Claude Code는 최신 버전을 사용할 수 없을 때 시작 시 [이전 버전으로 폴백](#startup-model-checks)하지만, 고정하면 사용자가 새 모델로 이동하는 시기를 제어할 수 있습니다.230 여러 사용자에게 배포할 때 특정 모델 버전을 고정합니다. 고정하지 않으면 `sonnet` 및 `opus`와 같은 모델 별칭이 Claude Code의 Vertex AI용 기본 제공 기본값으로 확인되며, 이는 최신 릴리스보다 뒤떨어질 있고 프로젝트에서 아직 활성화되지 않았을 수 있습니다. Claude Code는 기본값을 사용할 수 없을 때 시작 시 [이전 버전으로 폴백](#startup-model-checks)하지만, 고정하면 사용자가 새 모델로 이동하는 시기를 제어할 수 있습니다.

159</Warning>231</Warning>

160 232 

161이러한 환경 변수를 특정 Vertex AI 모델 ID로 설정합니다.233이러한 환경 변수를 특정 Vertex AI 모델 ID로 설정합니다.

headless.md +9 −1

Details

62 `--bare`는 스크립트 및 SDK 호출에 권장되는 모드이며 향후 릴리스에서 `-p`의 기본값이 될 것입니다.62 `--bare`는 스크립트 및 SDK 호출에 권장되는 모드이며 향후 릴리스에서 `-p`의 기본값이 될 것입니다.

63</Note>63</Note>

64 64 

65<h3 id="background-tasks-at-exit">

66 종료 시 백그라운드 작업

67</h3>

68 

69Claude가 `claude -p` 실행 중에 [백그라운드 Bash 작업](/ko/tools-reference#bash-tool-behavior)을 시작하는 경우(예: 개발 서버 또는 감시 빌드), 해당 작업은 Claude가 최종 결과를 반환하고 stdin이 닫힌 후 약 5초 후에 종료됩니다. 유예 기간을 통해 결과 직후에 완료되는 작업이 여전히 출력을 전달할 수 있습니다. v2.1.163 이전에는 종료되지 않는 백그라운드 프로세스가 `claude -p` 호출을 무한정 열어 두었습니다.

70 

65<h2 id="examples">71<h2 id="examples">

66 예제72 예제

67</h2>73</h2>


226`--allowedTools` 플래그는 [권한 규칙 구문](/ko/settings#permission-rule-syntax)을 사용합니다. 뒤의 ` *`는 접두사 일치를 활성화하므로 `Bash(git diff *)`는 `git diff`로 시작하는 모든 명령을 허용합니다. 공백이 중요합니다: 없으면 `Bash(git diff*)`도 `git diff-index`와 일치합니다.232`--allowedTools` 플래그는 [권한 규칙 구문](/ko/settings#permission-rule-syntax)을 사용합니다. 뒤의 ` *`는 접두사 일치를 활성화하므로 `Bash(git diff *)`는 `git diff`로 시작하는 모든 명령을 허용합니다. 공백이 중요합니다: 없으면 `Bash(git diff*)`도 `git diff-index`와 일치합니다.

227 233 

228<Note>234<Note>

229 사용자가 호출한 [skills](/ko/skills)(`/code-review` 등) [기본 제공 명령](/ko/commands)은 대화형 모드에서만 사용할 있습니다. `-p` 모드에서는 대신 수행하려는 작업을 설명합니다.235 사용자가 호출한 [skills](/ko/skills) 및 사용자 정의 명령은 `-p` 모드에서 작동합니다: 프롬프트 문자열에 `/skill-name` 포함하면 Claude Code가 실행하기 전에 이를 확장합니다. `/config` 및 `/login`과 같은 대화형 대화를 열어주는 기본 제공 명령은 `-p` 모드에서 사용할 없습니다.

230</Note>236</Note>

231 237 

232<h3 id="customize-the-system-prompt">238<h3 id="customize-the-system-prompt">


265claude -p "Continue that review" --resume "$session_id"271claude -p "Continue that review" --resume "$session_id"

266```272```

267 273 

274동일한 디렉터리에서 두 명령을 실행합니다: 세션 ID 조회는 현재 프로젝트 디렉터리 및 해당 git worktrees로 범위가 지정됩니다. 전체 범위 규칙은 [세션 재개](/ko/sessions#resume-a-session)를 참조하십시오.

275 

268<h2 id="next-steps">276<h2 id="next-steps">

269 다음 단계277 다음 단계

270</h2>278</h2>

hooks.md +56 −17

Details

311이러한 필드는 모든 hook 유형에 적용됩니다:311이러한 필드는 모든 hook 유형에 적용됩니다:

312 312 

313| 필드 | 필수 | 설명 |313| 필드 | 필수 | 설명 |

314| :-------------- | :-- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |314| :-------------- | :-- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

315| `type` | 예 | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` 또는 `"agent"` |315| `type` | 예 | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` 또는 `"agent"` |

316| `if` | 아니오 | `"Bash(git *)"` 또는 `"Edit(*.ts)"`와 같은 권한 규칙 구문을 사용하여 이 hook이 실행될 때를 필터링합니다. hook은 도구 호출이 패턴과 일치할 때만 생성되거나 Bash 명령이 너무 복잡하여 구문 분석할 없을 생성됩니다. 도구 이벤트에서만 평가됩니다: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied`. 다른 이벤트에서는 `if`가 설정된 hook이 절대 실행되지 않습니다. [권한 규칙](/ko/permissions)과 동일한 구문을 사용합니다 |316| `if` | 아니오 | `"Bash(git *)"` 또는 `"Edit(*.ts)"`와 같은 권한 규칙 구문을 사용하여 이 hook이 실행될 때를 필터링합니다. hook 명령은 도구 호출이 패턴과 일치할 때만 실행됩니다. [Bash 일치 테이블](#bash-if-matching) 아래에서 Bash 패턴이 하위 명령, `$()`, 백틱에 대해 어떻게 평가되는지 확인하세요. 도구 이벤트에서만 평가됩니다: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied`. 다른 이벤트에서는 `if`가 설정된 hook이 절대 실행되지 않습니다. [권한 규칙](/ko/permissions)과 동일한 구문을 사용합니다 |

317| `timeout` | 아니오 | 취소하기 전 초 단위. 기본값: `command`, `http`, `mcp_tool`의 경우 600; `prompt`의 경우 30; `agent`의 경우 60. [`UserPromptSubmit`](#userpromptsubmit)은 `command`, `http`, `mcp_tool`의 기본값을 30으로 낮추고 [`MessageDisplay`](#messagedisplay)는 10으로 낮춥니다 |317| `timeout` | 아니오 | 취소하기 전 초 단위. 기본값: `command`, `http`, `mcp_tool`의 경우 600; `prompt`의 경우 30; `agent`의 경우 60. [`UserPromptSubmit`](#userpromptsubmit)은 `command`, `http`, `mcp_tool`의 기본값을 30으로 낮추고 [`MessageDisplay`](#messagedisplay)는 10으로 낮춥니다 |

318| `statusMessage` | 아니오 | hook이 실행되는 동안 표시되는 사용자 정의 스피너 메시지 |318| `statusMessage` | 아니오 | hook이 실행되는 동안 표시되는 사용자 정의 스피너 메시지 |

319| `once` | 아니오 | `true`인 경우 세션당 한 번만 실행된 후 제거됩니다. [Skill 및 에이전트의 Hook](#hooks-in-skills-and-agents)에서 선언된 hook에만 적용됨; 설정 파일 및 에이전트 frontmatter에서는 무시됨 |319| `once` | 아니오 | `true`인 경우 세션당 한 번만 실행된 후 제거됩니다. [Skill 및 에이전트의 Hook](#hooks-in-skills-and-agents)에서 선언된 hook에만 적용됨; 설정 파일 및 에이전트 frontmatter에서는 무시됨 |

320 320 

321`if` 필드는 정확히 하나의 권한 규칙을 보유합니다. 규칙을 결합하기 위한 `&&`, `||` 또는 목록 구문이 없습니다. 여러 조건을 적용하려면 각각에 대해 별도의 hook 핸들러를 정의합니다. Bash의 경우 규칙은 선행 `VAR=value` 할당이 제거된 후 도구 입력의 각 하위 명령에 대해 일치하므로 `if: "Bash(git push *)"` 는 `FOO=bar git push` 및 `npm test && git push` 모두와 일치합니다. hook은 모든 하위 명령이 일치할 때 실행되며 명령이 너무 복잡하여 구문 분석할 수 없을 때 항상 실행됩니다.321`if` 필드는 정확히 하나의 권한 규칙을 보유합니다. 규칙을 결합하기 위한 `&&`, `||` 또는 목록 구문이 없습니다. 여러 조건을 적용하려면 각각에 대해 별도의 hook 핸들러를 정의합니다.

322 

323<span id="bash-if-matching" />Bash 패턴의 경우 hook 명령이 실행되는지 여부는 패턴의 형태와 Claude가 호출하는 Bash 명령에 따라 다릅니다. 선행 `VAR=value` 할당은 일치하기 전에 제거됩니다.

324 

325| `if` 패턴 | Bash 명령 | Hook 실행? | 이유 |

326| :----------------- | :--------------------- | :------- | :------------------------------------------------------- |

327| `Bash(git *)` | `FOO=bar git push` | 예 | 선행 할당이 제거됨; `git push`가 일치 |

328| `Bash(git *)` | `npm test && git push` | 예 | 각 하위 명령이 확인됨; `git push`가 일치 |

329| `Bash(rm *)` | `echo $(rm -rf /)` | 예 | `$()` 및 백틱 내의 명령이 확인됨; `rm -rf /`가 일치 |

330| `Bash(rm *)` | `echo $(date)` | 아니오 | 어떤 하위 명령도 `rm *`과 일치하지 않음 |

331| `Bash(git push *)` | `echo $(date)` | 예 | 명령 이름보다 더 많이 지정하는 패턴은 `$()`, 백틱 또는 `$VAR`에서 어쨌든 hook을 실행 |

332 

333필터는 또한 Bash 명령을 구문 분석할 수 없을 때 열려 있으므로 패턴과 관계없이 hook을 실행합니다. `if` 필터는 최선의 노력이므로 hard allow 또는 deny를 적용하려면 hook 대신 [권한 시스템](/ko/permissions)을 사용하세요.

322 334 

323<h4 id="command-hook-fields">335<h4 id="command-hook-fields">

324 명령 hook 필드336 명령 hook 필드


461[공통 필드](#common-fields) 외에도 프롬프트 및 에이전트 hook은 이러한 필드를 허용합니다:473[공통 필드](#common-fields) 외에도 프롬프트 및 에이전트 hook은 이러한 필드를 허용합니다:

462 474 

463| 필드 | 필수 | 설명 |475| 필드 | 필수 | 설명 |

464| :------- | :-- | :--------------------------------------------------------- |476| :------- | :-- | :--------------------------------------------------------------------------------------------------------------- |

465| `prompt` | 예 | 모델에 전송할 프롬프트 텍스트. hook 입력 JSON에 대한 자리 표시자로 `$ARGUMENTS` 사용 |477| `prompt` | 예 | 모델에 전송할 프롬프트 텍스트. hook 입력 JSON에 대한 자리 표시자로 `$ARGUMENTS` 사용. 리터럴 텍스트를 포함하려면 백슬래시로 이스케이프: `\$1.00`은 `$1.00`으로 렌더링됨 |

466| `model` | 아니오 | 평가에 사용할 모델. 기본값은 빠른 모델 |478| `model` | 아니오 | 평가에 사용할 모델. 기본값은 빠른 모델 |

467 479 

468일치하는 모든 hook은 병렬로 실행되며 동일한 핸들러는 자동으로 중복 제거됩니다. 명령 hook은 명령 문자열과 `args`로 중복 제거되고 HTTP hook은 URL로 중복 제거됩니다. 핸들러는 현재 디렉토리에서 Claude Code의 환경으로 실행됩니다. `$CLAUDE_CODE_REMOTE` 환경 변수는 원격 웹 환경에서 `"true"`로 설정되고 로컬 CLI에서는 설정되지 않습니다.480일치하는 모든 hook은 병렬로 실행되며 동일한 핸들러는 자동으로 중복 제거됩니다. 명령 hook은 명령 문자열과 `args`로 중복 제제거되고 HTTP hook은 URL로 중복 제거됩니다. 핸들러는 현재 디렉토리에서 Claude Code의 환경으로 실행됩니다. `$CLAUDE_CODE_REMOTE` 환경 변수는 원격 웹 환경에서 `"true"`로 설정되고 로컬 CLI에서는 설정되지 않습니다.

469 481 

470<h3 id="reference-scripts-by-path">482<h3 id="reference-scripts-by-path">

471 경로별로 스크립트 참조483 경로별로 스크립트 참조


619| `agent_id` | subagent의 고유 식별자. hook이 subagent 호출 내부에서 발생할 때만 존재합니다. 이를 사용하여 subagent hook 호출을 메인 스레드 호출과 구별합니다. |631| `agent_id` | subagent의 고유 식별자. hook이 subagent 호출 내부에서 발생할 때만 존재합니다. 이를 사용하여 subagent hook 호출을 메인 스레드 호출과 구별합니다. |

620| `agent_type` | 에이전트 이름 (예: `"Explore"` 또는 `"security-reviewer"`). 세션이 `--agent`를 사용하거나 hook이 subagent 내부에서 발생할 때 존재합니다. subagent의 경우 subagent의 유형이 세션의 `--agent` 값보다 우선합니다. [사용자 정의 subagent](/ko/sub-agents)의 경우 이는 에이전트의 frontmatter에서 `name` 필드이며 파일명이 아닙니다. |632| `agent_type` | 에이전트 이름 (예: `"Explore"` 또는 `"security-reviewer"`). 세션이 `--agent`를 사용하거나 hook이 subagent 내부에서 발생할 때 존재합니다. subagent의 경우 subagent의 유형이 세션의 `--agent` 값보다 우선합니다. [사용자 정의 subagent](/ko/sub-agents)의 경우 이는 에이전트의 frontmatter에서 `name` 필드이며 파일명이 아닙니다. |

621 633 

622`SessionStart` hook만 `model` 필드를 받습니다. `$CLAUDE_MODEL` 환경 변수는 없습니다. hook 프로세스는 부모 환경을 상속하므로 셸에서 설정한 경우 `$ANTHROPIC_MODEL`을 읽을 수 있지만 세션 중에 `/model`로 모델을 전환할 때 해당 값은 변경되지 않습니다.634`SessionStart` hook만 `model` 필드를 받을 수 있으며 존재가 보장되지 않습니다. `$CLAUDE_MODEL` 환경 변수는 없습니다. hook 프로세스는 부모 환경을 상속하므로 셸에서 설정한 경우 `$ANTHROPIC_MODEL`을 읽을 수 있지만 세션 중에 `/model`로 모델을 전환할 때 해당 값은 변경되지 않습니다.

623 635 

624예를 들어 Bash 명령에 대한 `PreToolUse` hook은 stdin에서 다음을 받습니다:636예를 들어 Bash 명령에 대한 `PreToolUse` hook은 stdin에서 다음을 받습니다:

625 637 


782# Notification hook: Claude Code가 주의가 필요할 때 데스크톱을 ping합니다.794# Notification hook: Claude Code가 주의가 필요할 때 데스크톱을 ping합니다.

783input=$(cat)795input=$(cat)

784title="Claude Code'796title="Claude Code'

785body=$(jq -r '.message // 'Needs your attention'' <<<"$input")797body=$(jq -r '.message // 'Needs your attention'' <<<'$input")

786seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")798seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")

787jq -nc --arg seq "$seq" '{terminalSequence: $seq}'799jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

788```800```


815* [SessionStart](#sessionstart), [Setup](#setup), 및 [SubagentStart](#subagentstart): 대화 시작, 첫 번째 프롬프트 전827* [SessionStart](#sessionstart), [Setup](#setup), 및 [SubagentStart](#subagentstart): 대화 시작, 첫 번째 프롬프트 전

816* [UserPromptSubmit](#userpromptsubmit) 및 [UserPromptExpansion](#userpromptexpansion): 제출된 프롬프트 옆828* [UserPromptSubmit](#userpromptsubmit) 및 [UserPromptExpansion](#userpromptexpansion): 제출된 프롬프트 옆

817* [PreToolUse](#pretooluse), [PostToolUse](#posttooluse), [PostToolUseFailure](#posttoolusefailure), 및 [PostToolBatch](#posttoolbatch): 도구 결과 옆829* [PreToolUse](#pretooluse), [PostToolUse](#posttooluse), [PostToolUseFailure](#posttoolusefailure), 및 [PostToolBatch](#posttoolbatch): 도구 결과 옆

830* [Stop](#stop) 및 [SubagentStop](#subagentstop): 턴의 끝. 대화가 계속되므로 Claude가 피드백에 작용할 수 있습니다. [Stop 결정 제어](#stop-decision-control) 참조

818 831 

819여러 hook이 동일한 이벤트에 대해 `additionalContext`를 반환하면 Claude는 모든 값을 받습니다. 값이 10,000자를 초과하면 Claude Code는 전체 텍스트를 세션 디렉토리의 파일에 쓰고 짧은 미리보기와 함께 파일 경로를 Claude에 전달합니다.832여러 hook이 동일한 이벤트에 대해 `additionalContext`를 반환하면 Claude는 모든 값을 받습니다. 값이 10,000자를 초과하면 Claude Code는 전체 텍스트를 세션 디렉토리의 파일에 쓰고 짧은 미리보기와 함께 파일 경로를 Claude에 전달합니다.

820 833 


838 851 

839| 이벤트 | 결정 패턴 | 주요 필드 |852| 이벤트 | 결정 패턴 | 주요 필드 |

840| :---------------------------------------------------------------------------------------------------------------------------------- | :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |853| :---------------------------------------------------------------------------------------------------------------------------------- | :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

841| UserPromptSubmit, UserPromptExpansion, PostToolUse, PostToolUseFailure, PostToolBatch, Stop, SubagentStop, ConfigChange, PreCompact | 최상위 `decision` | `decision: "block"`, `reason` |854| UserPromptSubmit, UserPromptExpansion, PostToolUse, PostToolUseFailure, PostToolBatch, Stop, SubagentStop, ConfigChange, PreCompact | 최상위 `decision` | `decision: "block"`, `reason`. Stop 및 SubagentStop은 또한 [오류가 아닌 피드백을 위해 대화를 계속하는](#stop-decision-control) `hookSpecificOutput.additionalContext`를 허용합니다 |

842| TeammateIdle, TaskCreated, TaskCompleted | 종료 코드 또는 `continue: false` | 종료 코드 2는 stderr 피드백으로 작업을 차단합니다. JSON `{"continue": false, "stopReason": "..."}` 또한 팀원을 완전히 중지하여 `Stop` hook 동작과 일치합니다 |855| TeammateIdle, TaskCreated, TaskCompleted | 종료 코드 또는 `continue: false` | 종료 코드 2는 stderr 피드백으로 작업을 차단합니다. JSON `{"continue": false, "stopReason": "..."}` 또한 팀원을 완전히 중지하여 `Stop` hook 동작과 일치합니다 |

843| PreToolUse | `hookSpecificOutput` | `permissionDecision` (allow/deny/ask/defer), `permissionDecisionReason` |856| PreToolUse | `hookSpecificOutput` | `permissionDecision` (allow/deny/ask/defer), `permissionDecisionReason` |

844| PermissionRequest | `hookSpecificOutput` | `decision.behavior` (allow/deny) |857| PermissionRequest | `hookSpecificOutput` | `decision.behavior` (allow/deny) |


850| SessionStart, Setup, SubagentStart | 컨텍스트만 | `hookSpecificOutput.additionalContext`는 Claude를 위한 컨텍스트를 추가합니다. SessionStart는 또한 [`initialUserMessage`, `watchPaths`, `sessionTitle`, 및 `reloadSkills`](#sessionstart-decision-control)를 허용합니다. 차단 또는 결정 제어 없음 |863| SessionStart, Setup, SubagentStart | 컨텍스트만 | `hookSpecificOutput.additionalContext`는 Claude를 위한 컨텍스트를 추가합니다. SessionStart는 또한 [`initialUserMessage`, `watchPaths`, `sessionTitle`, 및 `reloadSkills`](#sessionstart-decision-control)를 허용합니다. 차단 또는 결정 제어 없음 |

851| WorktreeRemove, Notification, SessionEnd, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, FileChanged | 없음 | 결정 제어 없음. 로깅 또는 정리와 같은 부작용에 사용됨 |864| WorktreeRemove, Notification, SessionEnd, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, FileChanged | 없음 | 결정 제어 없음. 로깅 또는 정리와 같은 부작용에 사용됨 |

852 865 

866일부 이벤트는 또한 허용 또는 차단하는 것이 아니라 콘텐츠를 다시 작성할 수 있습니다:

867 

868* `PreToolUse` — `hookSpecificOutput` 바로 아래의 `updatedInput`은 실행 전에 도구의 인수를 바꿉니다 ([세부 정보](#pretooluse-decision-control))

869* `PermissionRequest` — `decision` 객체 내의 `updatedInput` ([세부 정보](#permissionrequest-decision-control))

870* `PostToolUse` — `updatedToolOutput`은 도구의 결과를 바꿉니다 ([세부 정보](#posttooluse-decision-control))

871* `UserPromptSubmit` — 프롬프트를 바꿀 수 없습니다; `additionalContext`를 옆에만 주입합니다

872 

873편집 또는 변환 사용 사례의 경우 아웃바운드 도구 입력에 대해 `PreToolUse`에서 가로채고 인바운드 도구 결과에 대해 `PostToolUse`에서 가로채세요.

874 

853다음은 각 패턴의 실제 예입니다:875다음은 각 패턴의 실제 예입니다:

854 876 

855<Tabs>877<Tabs>


926 SessionStart 입력948 SessionStart 입력

927</h4>949</h4>

928 950 

929[공통 입력 필드](#common-input-fields) 외에도 SessionStart hook은 `source`, `model`, 선택적으로 `agent_type` 및 `session_title`을 받습니다. `source` 필드는 세션이 시작된 방식을 나타냅니다: 새 세션의 경우 `"startup"`, 재개된 세션의 경우 `"resume"`, `/clear` 후 `"clear"`, 압축 후 `"compact"`. `model` 필드는 모델 식별자를 포함합니다. `claude --agent <name>`으로 Claude Code를 시작하면 `agent_type` 필드에 에이전트 이름이 포함됩니다. `session_title` 필드는 이미 설정된 경우 현재 세션 제목을 전달합니다. 예를 들어 `--name` 또는 `/rename`을 통해 설정된 경우입니다. `sessionTitle`을 내보내는 hook은 사용자가 명시적으로 설정한 제목을 덮어쓰지 않도록 먼저 `session_title`을 확인할 수 있습니다.951[공통 입력 필드](#common-input-fields) 외에도 SessionStart hook은 `source`, `model`, 선택적으로 `agent_type` 및 `session_title`을 받습니다. `source` 필드는 세션이 시작된 방식을 나타냅니다: 새 세션의 경우 `"startup"`, 재개된 세션의 경우 `"resume"`, `/clear` 후 `"clear"`, 압축 후 `"compact"`. `model` 필드는 모델 식별자를 포함합니다. 예를 들어 `/clear` 후 또는 대화 복구를 통해 세션이 복원될 때 생략될 수 있으므로 필드를 읽기 전에 확인하세요. `claude --agent <name>`으로 Claude Code를 시작하면 `agent_type` 필드에 에이전트 이름이 포함됩니다. `session_title` 필드는 이미 설정된 경우 현재 세션 제목을 전달합니다. 예를 들어 `--name` 또는 `/rename`을 통해 설정된 경우입니다. `sessionTitle`을 내보내는 hook은 사용자가 명시적으로 설정한 제목을 덮어쓰지 않도록 먼저 `session_title`을 확인할 수 있습니다.

930 952 

931```json theme={null}953```json theme={null}

932{954{


1506| `status` | 문자열 | `"completed"` | 동기 호출의 경우 `"completed"`, `run_in_background: true`의 경우 `"async_launched"` |1528| `status` | 문자열 | `"completed"` | 동기 호출의 경우 `"completed"`, `run_in_background: true`의 경우 `"async_launched"` |

1507| `agentId` | 문자열 | `"a4d2c8f1e0b3a297"` | subagent 실행의 식별자 |1529| `agentId` | 문자열 | `"a4d2c8f1e0b3a297"` | subagent 실행의 식별자 |

1508| `content` | 배열 | `[{"type": "text", "text": "Found 12 endpoints..."}]` | subagent의 최종 텍스트 블록 |1530| `content` | 배열 | `[{"type": "text", "text": "Found 12 endpoints..."}]` | subagent의 최종 텍스트 블록 |

1531| `resolvedModel` | 문자열 | `"claude-sonnet-4-5"` | subagent가 실행된 모델. 요청된 모델과 다를 수 있습니다. {/* min-version: 2.1.174 */}Claude Code v2.1.174 이상 필요 |

1509| `totalTokens` | 숫자 | `12450` | subagent의 턴 전체에서 청구된 총 토큰 |1532| `totalTokens` | 숫자 | `12450` | subagent의 턴 전체에서 청구된 총 토큰 |

1510| `totalDurationMs` | 숫자 | `48211` | subagent 실행의 벽시계 기간 |1533| `totalDurationMs` | 숫자 | `48211` | subagent 실행의 벽시계 기간 |

1511| `totalToolUseCount` | 숫자 | `7` | subagent가 수행한 도구 호출 수 |1534| `totalToolUseCount` | 숫자 | `7` | subagent가 수행한 도구 호출 수 |

1512| `usage` | 객체 | `{"input_tokens": 8320, ...}` | 유형별 토큰 분석: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |1535| `usage` | 객체 | `{"input_tokens": 8320, ...}` | 유형별 토큰 분석: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |

1513 1536 

1514`run_in_background: true` 호출의 경우 도구는 subagent를 시작한 후 즉시 반환되므로 `tool_response`는 사용 필드를 전달하지 않습니다. `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`이 있습니다.1537`run_in_background: true` 호출의 경우 도구는 subagent를 시작한 후 즉시 반환되므로 `tool_response`는 사용 필드를 전달하지 않습니다. `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, `resolvedModel`이 있습니다.

1538 

1539`resolvedModel` 필드는 subagent가 실제로 실행되는 모델의 이름을 지정하며, 이는 `tool_input`의 `model` 값과 다를 수 있습니다. Claude Code v2.1.174 이상이 필요합니다.

1540 

1541<a id="askuserquestion" />

1515 1542 

1516<h5 id="askuserquestion">1543<h5 id="askuserquestion">

1517 AskUserQuestion1544 AskUserQuestion


2088}2115}

2089```2116```

2090 2117 

2091SubagentStop hook은 [Stop hook](#stop-decision-control)과 동일한 결정 제어 형식을 사용합니다. 이들은 `additionalContext`를 지원하지 않습니다. `decision: "block"`을 `reason`과 함께 반환하면 subagent가 계속 실행되고 `reason`이 subagent의 다음 명령으로 전달됩니다. subagent가 반환한 후 부모 세션에 컨텍스트를 주입하려면 `Agent` 도구에서 [`PostToolUse`](#posttooluse) hook을 대신 사용합니다.2118SubagentStop hook은 [Stop hook](#stop-decision-control)과 동일한 결정 제어 형식을 사용합니다. 이들은 `hookSpecificOutput.additionalContext`를 지원하며 `hookEventName`을 `"SubagentStop"`으로 설정하여 subagent를 계속 실행하는 비오류 피드백을 제공합니다. `decision: "block"`을 `reason`과 함께 반환하면 subagent가 계속 실행되고 `reason`이 subagent의 다음 명령으로 전달됩니다. subagent가 반환한 후 부모 세션에 컨텍스트를 주입하려면 `Agent` 도구에서 [`PostToolUse`](#posttooluse) hook을 대신 사용합니다.

2092 2119 

2093<h3 id="taskcreated">2120<h3 id="taskcreated">

2094 TaskCreated2121 TaskCreated


2115 "task_subject": "Implement user authentication",2142 "task_subject": "Implement user authentication",

2116 "task_description": "Add login and signup endpoints",2143 "task_description": "Add login and signup endpoints",

2117 "teammate_name": "implementer",2144 "teammate_name": "implementer",

2118 "team_name": "my-project"2145 "team_name": "session-a1b2c3d4"

2119}2146}

2120```2147```

2121 2148 


2176 "task_subject": "Implement user authentication",2203 "task_subject": "Implement user authentication",

2177 "task_description": "Add login and signup endpoints",2204 "task_description": "Add login and signup endpoints",

2178 "teammate_name": "implementer",2205 "teammate_name": "implementer",

2179 "team_name": "my-project"2206 "team_name": "session-a1b2c3d4"

2180}2207}

2181```2208```

2182 2209 


2294`Stop` 및 `SubagentStop` hook은 Claude가 계속할지 여부를 제어할 수 있습니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 hook 스크립트는 이러한 이벤트 특정 필드를 반환할 수 있습니다:2321`Stop` 및 `SubagentStop` hook은 Claude가 계속할지 여부를 제어할 수 있습니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 hook 스크립트는 이러한 이벤트 특정 필드를 반환할 수 있습니다:

2295 2322 

2296| 필드 | 설명 |2323| 필드 | 설명 |

2297| :--------- | :------------------------------------------------------ |2324| :------------------------------------- | :------------------------------------------------------------------------------------------------------------- |

2298| `decision` | `"block"`은 Claude가 중지되는 것을 방지합니다. 생략하여 Claude가 중지하도록 허용 |2325| `decision` | `"block"`은 Claude가 중지되는 것을 방지합니다. 생략하여 Claude가 중지하도록 허용 |

2299| `reason` | Claude가 중지되는 것이 차단될 때 필수입니다. Claude에 계속해야 하는 이유를 알립니다 |2326| `reason` | Claude가 중지되는 것이 차단될 때 필수입니다. Claude에 계속해야 하는 이유를 알립니다 |

2327| `hookSpecificOutput.additionalContext` | 비오류 피드백 Claude. 대화가 계속되므로 Claude가 이에 따라 행동할 수 있지만 `decision: "block"`과 달리 트랜스크립트에 hook 오류가 아닌 hook 피드백으로 표시됩니다 |

2300 2328 

2301```json theme={null}2329```json theme={null}

2302{2330{


2305}2333}

2306```2334```

2307 2335 

2336`additionalContext`를 사용하면 hook이 설계대로 작동하고 Claude에 지침을 제공할 때 (예: "완료하기 전에 테스트 스위트를 실행하세요"). 대화를 `decision: "block"`과 동일한 루프 보호를 통해 계속하지만 트랜스크립트는 이를 `Stop hook feedback`으로 표시하고 hook 오류 알림이 표시되지 않습니다:

2337 

2338```json theme={null}

2339{

2340 "hookSpecificOutput": {

2341 "hookEventName": "Stop",

2342 "additionalContext": "Please run the test suite before finishing"

2343 }

2344}

2345```

2346 

2308<h3 id="stopfailure">2347<h3 id="stopfailure">

2309 StopFailure2348 StopFailure

2310</h3>2349</h3>


2359 "permission_mode": "default",2398 "permission_mode": "default",

2360 "hook_event_name": "TeammateIdle",2399 "hook_event_name": "TeammateIdle",

2361 "teammate_name": "researcher",2400 "teammate_name": "researcher",

2362 "team_name": "my-project"2401 "team_name": "session-a1b2c3d4"

2363}2402}

2364```2403```

2365 2404 


2452ConfigChange hook은 구성 변경이 적용되는 것을 차단할 수 있습니다. 종료 코드 2 또는 JSON `decision`을 사용하여 변경을 방지합니다. 차단되면 새 설정이 실행 중인 세션에 적용되지 않습니다.2491ConfigChange hook은 구성 변경이 적용되는 것을 차단할 수 있습니다. 종료 코드 2 또는 JSON `decision`을 사용하여 변경을 방지합니다. 차단되면 새 설정이 실행 중인 세션에 적용되지 않습니다.

2453 2492 

2454| 필드 | 설명 |2493| 필드 | 설명 |

2455| :--------- | :------------------------------------------- |2494| :--------- | :-------------------------------------------- |

2456| `decision` | `"block"`은 구성 변경이 적용되는 것을 방지합니다. 생략하여 변경을 허용 |2495| `decision` | `"block"`은 구성 변경이 적용되는 것을 방지합니다. 생략하여 변경을 허용 |

2457| `reason` | `decision`이 `"block"`일 때 사용자에게 표시되는 설명 |2496| `reason` | `decision`이 `"block"`일 때 사용자에게 표시되는 설명 |

2458 2497 

hooks-guide.md +20 −5

Details

506 506 

507여러 hooks가 동일한 이벤트와 일치하면 모든 hook의 명령이 완료될 때까지 실행된 후 Claude Code가 결과를 병합합니다. 하나의 hook이 `deny`를 반환하는 것이 형제 hooks의 실행을 중지하지 않습니다. 한 hook의 `deny`가 다른 hook의 부작용을 억제하는 것에 의존하지 마세요.507여러 hooks가 동일한 이벤트와 일치하면 모든 hook의 명령이 완료될 때까지 실행된 후 Claude Code가 결과를 병합합니다. 하나의 hook이 `deny`를 반환하는 것이 형제 hooks의 실행을 중지하지 않습니다. 한 hook의 `deny`가 다른 hook의 부작용을 억제하는 것에 의존하지 마세요.

508 508 

509모든 일치하는 hooks가 완료된 후 Claude Code는 출력을 결합합니다. `PreToolUse` 권한 결정의 경우 가장 제한적인 답변이 우선합니다: `deny` `ask`를 재정의하고 `ask` `allow` 재정의합니다. `additionalContext`의 텍스트는 모든 hook에서 유지되고 Claude와 함께 전달됩니다.509모든 일치하는 hooks가 완료된 후 Claude Code는 출력을 결합합니다. `PreToolUse` 권한 결정의 경우 가장 제한적인 답변이 우선합니다: `deny`, `defer`, `ask`, `allow` 순서입니다. `additionalContext`의 텍스트는 모든 hook에서 유지되고 Claude와 함께 전달됩니다.

510 510 

511아래 예제는 `Bash`에 두 개의 `PreToolUse` hooks를 등록합니다. 첫 번째는 모든 명령을 로그 파일에 추가하고 0으로 종료합니다. 두 번째는 명령에 `rm -rf`가 포함되어 있을 때 거부하기 위해 2로 종료하는 스크립트를 실행합니다:511아래 예제는 `Bash`에 두 개의 `PreToolUse` hooks를 등록합니다. 첫 번째는 모든 명령을 로그 파일에 추가하고 0으로 종료합니다. 두 번째는 명령에 `rm -rf`가 포함되어 있을 때 거부하기 위해 2로 종료하는 스크립트를 실행합니다:

512 512 


751 `if` 필드는 Claude Code v2.1.85 이상이 필요합니다. 이전 버전은 이를 무시하고 일치하는 모든 호출에서 hook을 실행합니다.751 `if` 필드는 Claude Code v2.1.85 이상이 필요합니다. 이전 버전은 이를 무시하고 일치하는 모든 호출에서 hook을 실행합니다.

752</Note>752</Note>

753 753 

754`if` 필드는 [권한 규칙 구문](/ko/permissions)을 사용하여 도구 이름과 인수를 함께 사용하여 hooks를 필터링하므로 hook 프로세스는 도구 호출이 일치할 때만 생성되거나 Bash 명령이 구문 분석하기에 너무 복잡할 때 생성됩니다. 이는 도구 이름만으로 그룹 수준에서 필터링하는 `matcher`를 초과합니다.754`if` 필드는 [권한 규칙 구문](/ko/permissions)을 사용하여 도구 이름과 인수를 함께 사용하여 hooks를 필터링하므로 hook 프로세스는 도구 호출이 일치할 때만 생성됩니다. 이는 도구 이름만으로 그룹 수준에서 필터링하는 `matcher`를 초과합니다.

755 755 

756예를 들어 모든 Bash 명령이 아닌 `git` 명령을 사용할 때만 hook을 실행하려면:756예를 들어 모든 Bash 명령이 아닌 `git` 명령을 사용할 때만 hook을 실행하려면:

757 757 


774}774}

775```775```

776 776 

777Hook 프로세스는 Bash 명령의 서브명령이 `git *`과 일치할 때만 생성되거나 명령이 서브명령으로 구문 분석하기에 너무 복잡할 때 생성됩니다. `npm test && git push`와 같은 복합 명령의 경우 Claude Code는 각 서브명령을 평가하고 `git push`가 일치하기 때문에 hook을 발생시킵니다. `if` 필드는 권한 규칙과 동일한 패턴을 허용합니다: `"Bash(git *)"`, `"Edit(*.ts)"` 등. 여러 도구 이름을 일치시키려면 각각 자신의 `if` 값을 가진 별도의 핸들러를 사용하거나 파이프 교대가 지원되는 `matcher` 수준에서 일치합니다.777Hook 명령이 실행되는지 여부는 `if` 패턴의 형태와 Claude가 호출하는 Bash 명령에 따라 달라집니다:

778 

779| `if` 패턴 | Bash 명령 | Hook이 실행되나요? | 이유 |

780| :----------------- | :--------------------- | :----------- | :---------------------------------------------------------- |

781| `Bash(git *)` | `git push` | 예 | 명령 이름이 일치합니다 |

782| `Bash(git *)` | `npm test && git push` | 예 | 각 서브명령이 확인됩니다; `git push`가 일치합니다 |

783| `Bash(git *)` | `echo $(git log)` | 예 | `$()` 및 백틱 내의 명령이 확인됩니다; `git log`가 일치합니다 |

784| `Bash(git *)` | `echo $(date)` | 아니오 | 서브명령이 `git *`과 일치하지 않습니다 |

785| `Bash(git push *)` | `echo $(date)` | 예 | 명령 이름보다 더 많이 지정하는 패턴은 `$()`, 백틱 또는 `$VAR`에서 어쨌든 hook을 실행합니다 |

786 

787필터는 또한 실패 시 열려 있으므로 Bash 명령을 구문 분석할 수 없을 때 패턴에 관계없이 hook을 실행합니다. 필터는 최선의 노력이므로 하드 허용 또는 거부를 적용하려면 hook 대신 [권한 시스템](/ko/permissions)을 사용합니다.

788 

789`if` 필드는 권한 규칙과 동일한 패턴을 허용합니다: `"Bash(git *)"`, `"Edit(*.ts)"` 등. 여러 도구 이름을 일치시키려면 각각 자신의 `if` 값을 가진 별도의 핸들러를 사용하거나 파이프 교대가 지원되는 `matcher` 수준에서 일치합니다.

778 790 

779`if`는 도구 이벤트에서만 작동합니다: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` 및 `PermissionDenied`. 다른 이벤트에 추가하면 hook이 실행되지 않습니다.791`if`는 도구 이벤트에서만 작동합니다: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` 및 `PermissionDenied`. 다른 이벤트에 추가하면 hook이 실행되지 않습니다.

780 792 


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

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

795 807 

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

797 809 

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

799 811 


806모델의 유일한 작업은 yes/no 결정을 JSON으로 반환하는 것입니다:818모델의 유일한 작업은 yes/no 결정을 JSON으로 반환하는 것입니다:

807 819 

808* `"ok": true`: 작업이 진행됩니다820* `"ok": true`: 작업이 진행됩니다

809* `"ok": false`: 작업이 차단됩니다. `Stop` 및 `SubagentStop` hooks의 경우 `reason`이 Claude에게 피드백으로 전달되어 계속 작업합니다. 다른 이벤트의 경우 턴이 종료되고 `reason`이 경고 줄로 채팅에 나타납니다. Claude는 이를 보지 못합니다.821* `"ok": false`: 작업이 차단됩니다. 이벤트에 따라 다음과 같이 작동합니다:

822 * `Stop` 및 `SubagentStop`: `reason`이 Claude에게 피드백으로 전달되어 계속 작업합니다

823 * `PreToolUse`: 도구 호출이 거부되고 `reason`이 도구 오류로 Claude에게 반환되어 조정하고 계속할 수 있습니다

824 * `PostToolUse`, `PostToolBatch`, `UserPromptSubmit`, 및 `UserPromptExpansion`: 턴이 종료되고 `reason`이 경고 줄로 채팅에 나타납니다

810 825 

811이 예제는 `Stop` hook을 사용하여 모든 요청된 작업이 완료되었는지 모델에 묻습니다. 모델이 `"ok": false`를 반환하면 Claude는 계속 작업하고 `reason`을 다음 지침으로 사용합니다:826이 예제는 `Stop` hook을 사용하여 모든 요청된 작업이 완료되었는지 모델에 묻습니다. 모델이 `"ok": false`를 반환하면 Claude는 계속 작업하고 `reason`을 다음 지침으로 사용합니다:

812 827 

Details

16 16 

17Claude에게 작업을 주면 세 가지 단계를 거칩니다: **컨텍스트 수집**, **작업 수행**, **결과 검증**. 이 단계들은 함께 진행됩니다. Claude는 파일을 검색하여 코드를 이해하든, 변경을 위해 편집하든, 작업을 확인하기 위해 테스트를 실행하든 전체적으로 도구를 사용합니다.17Claude에게 작업을 주면 세 가지 단계를 거칩니다: **컨텍스트 수집**, **작업 수행**, **결과 검증**. 이 단계들은 함께 진행됩니다. Claude는 파일을 검색하여 코드를 이해하든, 변경을 위해 편집하든, 작업을 확인하기 위해 테스트를 실행하든 전체적으로 도구를 사용합니다.

18 18 

19<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agentic-loop.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=4a30fb7ce2815012a9f27c955e2c6bb0" alt="에이전트 루프: 프롬프트가 Claude가 컨텍스트를 수집하고, 작업을 수행하고, 결과를 검증하고, 작업이 완료될 때까지 반복하도록 합니다. 언제든지 중단할 수 있습니다." width="720" height="280" data-path="images/agentic-loop.svg" />19<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agentic-loop.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=4a30fb7ce2815012a9f27c955e2c6bb0" alt="에이전트 루프 다이어그램: 프롬프트가 Claude가 컨텍스트를 수집하고, 작업을 수행하고, 결과를 검증하고, 작업이 완료될 때까지 반복하도록 합니다. 언제든지 중단할 수 있습니다." width="720" height="280" data-path="images/agentic-loop.svg" />

20 20 

21루프는 사용자가 요청한 내용에 맞게 조정됩니다. 코드베이스에 대한 질문은 컨텍스트 수집만 필요할 수 있습니다. 버그 수정은 세 단계를 반복적으로 거칩니다. 리팩토링은 광범위한 검증을 포함할 수 있습니다. Claude는 이전 단계에서 배운 내용을 바탕으로 각 단계에서 필요한 것을 결정하고, 수십 개의 작업을 연결하며 그 과정에서 방향을 수정합니다.21루프는 사용자가 요청한 내용에 맞게 조정됩니다. 코드베이스에 대한 질문은 컨텍스트 수집만 필요할 수 있습니다. 버그 수정은 세 단계를 반복적으로 거칩니다. 리팩토링은 광범위한 검증을 포함할 수 있습니다. Claude는 이전 단계에서 배운 내용을 바탕으로 각 단계에서 필요한 것을 결정하고, 수십 개의 작업을 연결하며 그 과정에서 방향을 수정합니다.

22 22 


186 186 

187`Shift+Tab`을 눌러 권한 모드를 순환하세요:187`Shift+Tab`을 눌러 권한 모드를 순환하세요:

188 188 

189* **기본값**: Claude는 파일 편집 및 셸 명령 전에 요청189* **기본값**: Claude는 파일 편집 및 셸 명령 전에 요청합니다

190* **자동 수락 편집**: Claude는 파일을 편집하고 `mkdir` 및 `mv`와 같은 일반적인 파일시스템 명령을 요청 없이 실행하지만 다른 명령은 여전히 요청190* **자동 수락 편집**: Claude는 파일을 편집하고 `mkdir` 및 `mv`와 같은 일반적인 파일시스템 명령을 요청 없이 실행하지만 다른 명령은 여전히 요청합니다

191* **계획 모드**: Claude는 읽기 전용 도구만 사용하여 실행 전에 승인할 있는 계획을 생성191* **계획 모드**: Claude는 소스 파일을 편집하지 않고 계획을 탐색하고 제안합니다. 기본 모드처럼 권한 프롬프트가 여전히 적용됩니다

192* **자동 모드**: Claude는 백그라운드 안전 검사로 모든 작업을 평가합니다. 현재 연구 미리보기입니다192* **자동 모드**: Claude는 백그라운드 안전 검사로 모든 작업을 평가합니다. 현재 연구 미리보기입니다

193 193 

194`.claude/settings.json`에서 특정 명령을 허용하여 Claude가 매번 요청하지 않도록 할 수 있습니다. 이는 `npm test` 또는 `git status`와 같은 신뢰할 수 있는 명령에 유용합니다. 설정은 조직 전체 정책에서 개인 선호도까지 범위를 지정할 수 있습니다. 자세한 내용은 [권한](/ko/permissions)을 참조하세요.194`.claude/settings.json`에서 특정 명령을 허용하여 Claude가 매번 요청하지 않도록 할 수 있습니다. 이는 `npm test` 또는 `git status`와 같은 신뢰할 수 있는 명령에 유용합니다. 설정은 조직 전체 정책에서 개인 선호도까지 범위를 지정할 수 있습니다. 자세한 내용은 [권한](/ko/permissions)을 참조하세요.


196***196***

197 197 

198<h2 id="work-effectively-with-claude-code">198<h2 id="work-effectively-with-claude-code">

199 Claude Code를 효과적으로 사용199 Claude Code를 효과적으로 사용하기

200</h2>200</h2>

201 201 

202팁은 Claude Code에서 더 나은 결과를 얻는 데 도움이 됩니다.202팁들은 Claude Code에서 더 나은 결과를 얻는 데 도움이 됩니다.

203 203 

204<h3 id="ask-claude-code-for-help">204<h3 id="ask-claude-code-for-help">

205 Claude Code에 도움을 요청205 Claude Code에 도움을 요청하기

206</h3>206</h3>

207 207 

208Claude Code는 사용 방법을 가르칠 수 있습니다. "hooks를 설정하려면 어떻게 하나요?" 또는 "CLAUDE.md를 구조화하는 최선의 방법은 무엇인가요?"와 같은 질문을 하면 Claude가 설명합니다.208Claude Code는 사용 방법을 가르칠 수 있습니다. "hooks를 설정하려면 어떻게 하나요?" 또는 "CLAUDE.md를 구조화하는 최선의 방법은 무엇인가요?"와 같은 질문을 하면 Claude가 설명합니다.


213* `/agents`는 사용자 정의 subagents 구성을 도와줍니다213* `/agents`는 사용자 정의 subagents 구성을 도와줍니다

214* `/doctor`는 설치의 일반적인 문제를 진단합니다214* `/doctor`는 설치의 일반적인 문제를 진단합니다

215 215 

216<h3 id="it-s-a-conversation">216<h3 id="its-a-conversation">

217 대화입니다217 대화형입니다

218</h3>218</h3>

219 219 

220Claude Code는 대화형입니다. 완벽한 프롬프트가 필요하지 않습니다. 원하는 것으로 시작한 다음 개선하세요:220Claude Code는 대화형입니다. 완벽한 프롬프트가 필요하지 않습니다. 원하는 것으로 시작한 다음 개선하세요:


257모호한 프롬프트는 작동하지만 더 많은 시간을 조종하는 데 소비합니다. 위와 같은 구체적인 프롬프트는 종종 첫 번째 시도에서 성공합니다.257모호한 프롬프트는 작동하지만 더 많은 시간을 조종하는 데 소비합니다. 위와 같은 구체적인 프롬프트는 종종 첫 번째 시도에서 성공합니다.

258 258 

259<h3 id="give-claude-something-to-verify-against">259<h3 id="give-claude-something-to-verify-against">

260 Claude가 검증할 수 있는 것을 제공260 Claude가 검증할 수 있는 것을 제공하기

261</h3>261</h3>

262 262 

263Claude는 자신의 작업을 확인할 수 있을 때 더 잘 수행합니다. 테스트 케이스를 포함하고, 예상 UI의 스크린샷을 붙여넣거나, 원하는 출력을 정의하세요.263Claude는 자신의 작업을 확인할 수 있을 때 더 잘 수행합니다. 테스트 케이스를 포함하고, 예상 UI의 스크린샷을 붙여넣거나, 원하는 출력을 정의하세요.


270시각적 작업의 경우 디자인의 스크린샷을 붙여넣고 Claude에게 구현을 비교하도록 요청하세요.270시각적 작업의 경우 디자인의 스크린샷을 붙여넣고 Claude에게 구현을 비교하도록 요청하세요.

271 271 

272<h3 id="explore-before-implementing">272<h3 id="explore-before-implementing">

273 구현 전에 탐색273 구현 전에 탐색하기

274</h3>274</h3>

275 275 

276복잡한 문제의 경우 연구와 코딩을 분리하세요. 계획 모드(`Shift+Tab` 두 번)를 사용하여 먼저 코드베이스를 분석하세요:276복잡한 문제의 경우 연구와 코딩을 분리하세요. 계획 모드(`Shift+Tab` 두 번)를 사용하여 먼저 코드베이스를 분석하세요:


282 282 

283계획을 검토하고 대화를 통해 개선한 다음 Claude가 구현하도록 하세요. 이 2단계 접근 방식은 코드로 바로 뛰어드는 것보다 더 나은 결과를 생성합니다.283계획을 검토하고 대화를 통해 개선한 다음 Claude가 구현하도록 하세요. 이 2단계 접근 방식은 코드로 바로 뛰어드는 것보다 더 나은 결과를 생성합니다.

284 284 

285<h3 id="delegate-don-t-dictate">285<h3 id="delegate-dont-dictate">

286 지시하지 말고 위임286 지시하지 말고 위임하기

287</h3>287</h3>

288 288 

289능력 있는 동료에게 위임하는 것처럼 생각하세요. 컨텍스트와 방향을 제공한 다음 Claude가 세부 사항을 파악하도록 신뢰하세요:289능력 있는 동료에게 위임하는 것처럼 생각하세요. 컨텍스트와 방향을 제공한 다음 Claude가 세부 사항을 파악하도록 신뢰하세요:


295 295 

296읽을 파일이나 실행할 명령을 지정할 필요가 없습니다. Claude가 파악합니다.296읽을 파일이나 실행할 명령을 지정할 필요가 없습니다. Claude가 파악합니다.

297 297 

298<h2 id="what-s-next">298<h2 id="whats-next">

299 다음 단계299 다음 단계

300</h2>300</h2>

301 301 

Details

27</h3>27</h3>

28 28 

29| 단축키 | 설명 | 컨텍스트 |29| 단축키 | 설명 | 컨텍스트 |

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

31| `Ctrl+C` | 중단 또는 입력 지우기 | 실행 중인 작업을 중단합니다. 실행 중인 작업이 없으면 첫 번째 누르기는 프롬프트 입력을 지우고 두 번째 누르기는 Claude Code를 종료합니다 |31| `Ctrl+C` | 중단 또는 입력 지우기 | 실행 중인 작업을 중단합니다. 실행 중인 작업이 없으면 첫 번째 누르기는 프롬프트 입력을 지우고 두 번째 누르기는 Claude Code를 종료합니다 |

32| `Ctrl+X Ctrl+K` | 이 세션에서 모든 실행 중인 [백그라운드 서브에이전트](/ko/sub-agents#run-subagents-in-foreground-or-background)를 종료합니다. 3초 이내에 두 번 누르면 확인 | 서브에이전트 제어 |32| `Ctrl+X Ctrl+K` | 이 세션에서 모든 실행 중인 [백그라운드 서브에이전트](/ko/sub-agents#run-subagents-in-foreground-or-background)를 종료합니다. 3초 이내에 두 번 누르면 확인 | 서브에이전트 제어 |

33| `Ctrl+D` | Claude Code 세션 종료 | EOF 신호 |33| `Ctrl+D` | Claude Code 세션 종료 | EOF 신호 |


39| `Ctrl+B` | 백그라운드 실행 작업 | bash 명령 및 에이전트를 백그라운드로 실행합니다. Tmux 사용자는 두 번 누르기 |39| `Ctrl+B` | 백그라운드 실행 작업 | bash 명령 및 에이전트를 백그라운드로 실행합니다. Tmux 사용자는 두 번 누르기 |

40| `Ctrl+T` | 작업 목록 토글 | 터미널 상태 영역에서 [작업 목록](#task-list) 표시 또는 숨기기 |40| `Ctrl+T` | 작업 목록 토글 | 터미널 상태 영역에서 [작업 목록](#task-list) 표시 또는 숨기기 |

41| `Left/Right 화살표` | 대화 상자 탭 순환 | 권한 대화 상자 및 메뉴의 탭 간 탐색 |41| `Left/Right 화살표` | 대화 상자 탭 순환 | 권한 대화 상자 및 메뉴의 탭 간 탐색 |

42| `Up/Down 화살표` 또는 `Ctrl+P`/`Ctrl+N` | 커서 이동 또는 명령 기록 탐색 | 여러 줄 입력에서 먼저 프롬프트 내에서 커서를 이동합니다. 커서가 이미 위쪽 또는 아래쪽 가장자리에 있으면 다시 누르면 명령 기록을 탐색합니다 |42| `Up/Down 화살표` 또는 `Ctrl+P`/`Ctrl+N` | 커서 이동 또는 명령 기록 탐색 | 입력이 여러 시각적 줄에 걸쳐 있을 때(바꿈 또는 여러 줄 여부), 먼저 프롬프트 내에서 커서를 이동합니다. 커서가 번째 또는 마지막 시각적 줄에 있으면 다시 누르면 명령 기록을 탐색합니다. {/* min-version: 2.1.169 */}v2.1.169부터 줄 바꿈된 단일 줄 입력은 여러 줄과 동일하게 작동합니다 |

43| `Esc` | Claude 중단 | 현재 응답 또는 도구 호출을 중간에 중지하여 리다이렉트할 수 있습니다. Claude는 지금까지 수행한 작업을 유지합니다 |43| `Esc` | Claude 중단 | 현재 응답 또는 도구 호출을 중간에 중지하여 리다이렉트할 수 있습니다. Claude는 지금까지 수행한 작업을 유지합니다 |

44| `Esc` + `Esc` | 입력 초안 지우기 또는 되돌리기 | 프롬프트 입력에 텍스트가 포함되어 있으면 이중 `Esc`는 이를 지우고 초안을 기록에 저장하여 `Up`으로 회수할 수 있습니다. 입력이 비어 있으면 이중 `Esc`는 [되돌리기 메뉴](/ko/checkpointing)를 열어 이전 지점에서 코드 및 대화를 복원하거나 요약합니다 |44| `Esc` + `Esc` | 입력 초안 지우기 또는 되돌리기 | 프롬프트 입력에 텍스트가 포함되어 있으면 이중 `Esc`는 이를 지우고 초안을 기록에 저장하여 `Up`으로 회수할 수 있습니다. 입력이 비어 있으면 이중 `Esc`는 [되돌리기 메뉴](/ko/checkpointing)를 열어 이전 지점에서 코드 및 대화를 복원하거나 요약합니다 |

45| `Shift+Tab` 또는 `Alt+M` (일부 구성) | 권한 모드 순환 | `default`, `acceptEdits`, `plan` 및 `auto` 또는 `bypassPermissions`와 같이 활성화한 모든 모드를 순환합니다. [권한 모드](/ko/permission-modes)를 참조하세요. |45| `Shift+Tab` 또는 `Alt+M` (일부 구성) | 권한 모드 순환 | `default`, `acceptEdits`, `plan` 및 `auto` 또는 `bypassPermissions`와 같이 활성화한 모든 모드를 순환합니다. [권한 모드](/ko/permission-modes)를 참조하세요. |

46| `Option+P` (macOS) 또는 `Alt+P` (Windows/Linux) | 모델 전환 | 프롬프트를 지우지 않고 모델 전환 |46| `Option+P` (macOS) 또는 `Alt+P` (Windows/Linux) | 모델 전환 | 프롬프트를 지우지 않고 모델 전환 |

47| `Option+T` (macOS) 또는 `Alt+T` (Windows/Linux) | 확장 사고 토글 | 확장 사고 모드를 활성화 또는 비활성화합니다. {/* min-version: 2.1.132 */}v2.1.132부터 이 단축키는 macOS에서 Option을 Meta로 구성하지 않고도 작동합니다 |47| `Option+T` (macOS) 또는 `Alt+T` (Windows/Linux) | 확장 사고 토글 | 확장 사고 모드를 활성화 또는 비활성화합니다. Fable 5에는 영향을 주지 않으며, 항상 확장 사고를 사용합니다. {/* min-version: 2.1.132 */}v2.1.132부터 이 단축키는 macOS에서 Option을 Meta로 구성하지 않고도 작동합니다 |

48| `Option+O` (macOS) 또는 `Alt+O` (Windows/Linux) | 빠른 모드 토글 | [빠른 모드](/ko/fast-mode) 활성화 또는 비활성화 |48| `Option+O` (macOS) 또는 `Alt+O` (Windows/Linux) | 빠른 모드 토글 | [빠른 모드](/ko/fast-mode) 활성화 또는 비활성화 |

49 49 

50<h3 id="text-editing">50<h3 id="text-editing">


94| 단축키 | 설명 | 참고 |94| 단축키 | 설명 | 참고 |

95| :----- | :---------- | :---------------------------------------- |95| :----- | :---------- | :---------------------------------------- |

96| `/` 시작 | 명령 또는 skill | [명령](#commands) 및 [skills](/ko/skills) 참조 |96| `/` 시작 | 명령 또는 skill | [명령](#commands) 및 [skills](/ko/skills) 참조 |

97| `!` 시작 | Bash 모드 | 명령을 직접 실행하고 실행 출력을 세션에 추가 |97| `!` 시작 | Shell 모드 | 명령을 직접 실행하고 실행 출력을 세션에 추가 |

98| `@` | 파일 경로 언급 | 파일 경로 자동 완성 트리거 |98| `@` | 파일 경로 언급 | 파일 경로 자동 완성 트리거 |

99 99 

100<h3 id="transcript-viewer">100<h3 id="transcript-viewer">


372| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |372| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |

373| `Space`, `Enter`, `Escape` | 답변을 해제하고 프롬프트로 돌아가기 |373| `Space`, `Enter`, `Escape` | 답변을 해제하고 프롬프트로 돌아가기 |

374| `Up` / `Down` | 답변 스크롤 |374| `Up` / `Down` | 답변 스크롤 |

375| `c` | 답변을 클립보드에 원본 Markdown으로 복사합니다. 하드 래핑된 터미널 렌더링이 아닌 소스 텍스트를 캡처하는 마우스 선택 대신 이를 사용하세요 |

375| `f` | 새 세션으로 포크합니다. 포크는 부모 대화에 이 질문과 답변을 실제 트랜스크립트 턴으로 상속하므로 전체 도구 액세스로 계속할 수 있습니다. 원본 세션은 [`/resume`](/ko/commands) 아래에 보존됩니다. 로컬 세션에서만 사용 가능 |376| `f` | 새 세션으로 포크합니다. 포크는 부모 대화에 이 질문과 답변을 실제 트랜스크립트 턴으로 상속하므로 전체 도구 액세스로 계속할 수 있습니다. 원본 세션은 [`/resume`](/ko/commands) 아래에 보존됩니다. 로컬 세션에서만 사용 가능 |

376| `x` | 현재 답변 위에 표시된 이전 `/btw` 교환 목록 지우기 |377| `x` | 현재 답변 위에 표시된 이전 `/btw` 교환 목록 지우기 |

377 378 

jetbrains.md +77 −25

Details

8 8 

9Claude Code는 전용 플러그인을 통해 JetBrains IDE와 통합되며, 대화형 diff 보기, 선택 영역 컨텍스트 공유 등의 기능을 제공합니다.9Claude Code는 전용 플러그인을 통해 JetBrains IDE와 통합되며, 대화형 diff 보기, 선택 영역 컨텍스트 공유 등의 기능을 제공합니다.

10 10 

11## 지원되는 IDE11<h2 id="supported-ides">

12 지원되는 IDE

13</h2>

12 14 

13Claude Code 플러그인은 다음을 포함한 대부분의 JetBrains IDE와 호환됩니다:15Claude Code 플러그인은 다음을 포함한 대부분의 JetBrains IDE와 호환됩니다:

14 16 


19* PhpStorm21* PhpStorm

20* GoLand22* GoLand

21 23 

22## 기능24<h2 id="features">

25 기능

26</h2>

23 27 

24* **빠른 실행**: `Cmd+Esc` (Mac) 또는 `Ctrl+Esc` (Windows/Linux)를 사용하여 편집기에서 직접 Claude Code를 열거나, UI의 Claude Code 버튼을 클릭합니다28* **빠른 실행**: `Cmd+Esc` (Mac) 또는 `Ctrl+Esc` (Windows/Linux)를 사용하여 편집기에서 직접 Claude Code를 열거나, UI의 Claude Code 버튼을 클릭합니다

25* **Diff 보기**: 코드 변경 사항을 터미널 대신 IDE diff 뷰어에 직접 표시할 수 있습니다29* **Diff 보기**: 코드 변경 사항을 터미널 대신 IDE diff 뷰어에 직접 표시할 수 있습니다


27* **파일 참조 바로가기**: `Cmd+Option+K` (Mac) 또는 `Alt+Ctrl+K` (Linux/Windows)를 사용하여 `@src/auth.ts#L1-99`와 같은 파일 참조를 삽입합니다31* **파일 참조 바로가기**: `Cmd+Option+K` (Mac) 또는 `Alt+Ctrl+K` (Linux/Windows)를 사용하여 `@src/auth.ts#L1-99`와 같은 파일 참조를 삽입합니다

28* **진단 공유**: IDE의 진단 오류 (lint 및 구문 오류 등)가 작업할 때 Claude와 자동으로 공유됩니다32* **진단 공유**: IDE의 진단 오류 (lint 및 구문 오류 등)가 작업할 때 Claude와 자동으로 공유됩니다

29 33 

30## 설치34<h2 id="installation">

35 설치

36</h2>

31 37 

32### 마켓플레이스 설치38플러그인은 IDE의 통합 터미널에서 `claude` 명령을 실행하고 이에 연결합니다. 자체 CLI 복사본을 번들로 제공하지 않으므로 두 부분을 모두 설치해야 합니다.

33 39 

34JetBrains 마켓플레이스에서 [Claude Code 플러그인](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-)을 찾아 설치하고 IDE를 다시 시작합니다.40<Steps>

41 <Step title="Claude Code CLI 설치">

42 아직 설치하지 않았다면 [빠른 시작](/ko/quickstart)을 따라 CLI를 설치합니다. `claude`가 PATH에 없으면 플러그인에 "Claude Code를 시작할 수 없음" 알림이 표시됩니다.

43 </Step>

44 

45 <Step title="JetBrains 플러그인 설치">

46 JetBrains 마켓플레이스에서 [Claude Code 플러그인](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-)을 설치하고 IDE를 다시 시작합니다.

47 </Step>

48</Steps>

49 

50`claude`가 IDE가 찾을 수 없는 위치에 설치된 경우 플러그인의 [Claude 명령 설정](#general-settings)에서 전체 경로를 설정합니다.

35 51 

36Claude Code를 아직 설치하지 않았다면, [빠른 시작 가이드](/ko/quickstart)에서 설치 지침을 참조하세요.52Claude Code는 모든 유료 Claude 구독(Pro, Max, Team 또는 Enterprise) 또는 Claude Console 계정과 함께 작동하며, API 키가 필요하지 않습니다. `claude`를 처음 실행할 때 [로그인](/ko/authentication#log-in-to-claude-code)하라는 메시지가 표시됩니다.

37 53 

38<Note>54<Note>

39 플러그인을 설치한 후 IDE를 완전히 다시 시작해야 적용될 수 있습니다.55 플러그인을 설치한 후 IDE를 완전히 다시 시작해야 적용될 수 있습니다.

40</Note>56</Note>

41 57 

42## 사용법58<h2 id="usage">

59 사용법

60</h2>

43 61 

44### IDE에서62<h3 id="from-your-ide">

63 IDE에서

64</h3>

45 65 

46IDE의 통합 터미널에서 `claude`를 실행하면 모든 통합 기능이 활성화됩니다.66IDE의 통합 터미널에서 `claude`를 실행하면 모든 통합 기능이 활성화됩니다.

47 67 

48### 외부 터미널에서68<h3 id="from-external-terminals">

69 외부 터미널에서

70</h3>

49 71 

50모든 외부 터미널에서 `/ide` 명령을 사용하여 Claude Code를 JetBrains IDE에 연결하고 모든 기능을 활성화합니다:72모든 외부 터미널에서 `/ide` 명령을 사용하여 Claude Code를 JetBrains IDE에 연결하고 모든 기능을 활성화합니다:

51 73 


59 81 

60Claude가 IDE와 동일한 파일에 액세스하도록 하려면, IDE 프로젝트 루트와 동일한 디렉터리에서 Claude Code를 시작합니다.82Claude가 IDE와 동일한 파일에 액세스하도록 하려면, IDE 프로젝트 루트와 동일한 디렉터리에서 Claude Code를 시작합니다.

61 83 

62## 구성84<h2 id="configuration">

85 구성

86</h2>

63 87 

64### Claude Code 설정88<h3 id="claude-code-settings">

89 Claude Code 설정

90</h3>

65 91 

66Claude Code의 설정을 통해 IDE 통합을 구성합니다:92Claude Code의 설정을 통해 IDE 통합을 구성합니다:

67 93 


692. `/config` 명령 입력952. `/config` 명령 입력

703. diff 도구를 `auto`로 설정하여 IDE에서 diff를 표시하거나, `terminal`로 설정하여 터미널에 유지합니다963. diff 도구를 `auto`로 설정하여 IDE에서 diff를 표시하거나, `terminal`로 설정하여 터미널에 유지합니다

71 97 

72### 플러그인 설정98<h3 id="plugin-settings">

99 플러그인 설정

100</h3>

73 101 

74\*\*설정 → 도구 → Claude Code \[Beta]\*\*로 이동하여 Claude Code 플러그인을 구성합니다:102\*\*설정 → 도구 → Claude Code \[Beta]\*\*로 이동하여 Claude Code 플러그인을 구성합니다:

75 103 

76#### 일반 설정104<h4 id="general-settings">

105 일반 설정

106</h4>

77 107 

78* **Claude 명령**: Claude를 실행할 사용자 정의 명령을 지정합니다 (예: `claude`, `/usr/local/bin/claude`, 또는 `npx @anthropic-ai/claude-code`)108* **Claude 명령**: Claude를 실행할 사용자 정의 명령을 지정합니다 (예: `claude`, `/usr/local/bin/claude`, 또는 `npx @anthropic-ai/claude-code`)

79* **Claude 명령을 찾을 수 없음에 대한 알림 표시 안 함**: Claude 명령을 찾을 수 없다는 알림을 건너뜁니다109* **Claude 명령을 찾을 수 없음에 대한 알림 표시 안 함**: Claude 명령을 찾을 수 없다는 알림을 건너뜁니다


84 WSL 사용자의 경우: Claude 명령으로 `wsl -d Ubuntu -- bash -lic "claude"`를 설정합니다 (`Ubuntu`를 WSL 배포판 이름으로 바꿉니다)114 WSL 사용자의 경우: Claude 명령으로 `wsl -d Ubuntu -- bash -lic "claude"`를 설정합니다 (`Ubuntu`를 WSL 배포판 이름으로 바꿉니다)

85</Tip>115</Tip>

86 116 

87#### ESC 키 구성117<h4 id="esc-key-configuration">

118 ESC 키 구성

119</h4>

88 120 

89ESC 키가 JetBrains 터미널에서 Claude Code 작업을 중단하지 않는 경우:121ESC 키가 JetBrains 터미널에서 Claude Code 작업을 중단하지 않는 경우:

90 122 


96 128 

97이렇게 하면 ESC 키가 Claude Code 작업을 제대로 중단할 수 있습니다.129이렇게 하면 ESC 키가 Claude Code 작업을 제대로 중단할 수 있습니다.

98 130 

99## 특수 구성131<h2 id="special-configurations">

132 특수 구성

133</h2>

100 134 

101### 원격 개발135<h3 id="remote-development">

136 원격 개발

137</h3>

102 138 

103<Warning>139<Warning>

104 JetBrains 원격 개발을 사용할 때는 \*\*설정 → 플러그인 (호스트)\*\*를 통해 원격 호스트에 플러그인을 설치해야 합니다.140 JetBrains 원격 개발을 사용할 때는 \*\*설정 → 플러그인 (호스트)\*\*를 통해 원격 호스트에 플러그인을 설치해야 합니다.


106 142 

107플러그인은 로컬 클라이언트 머신이 아닌 원격 호스트에 설치해야 합니다.143플러그인은 로컬 클라이언트 머신이 아닌 원격 호스트에 설치해야 합니다.

108 144 

109### WSL 구성145<h3 id="wsl-configuration">

146 WSL 구성

147</h3>

110 148 

111Claude Code를 WSL2의 JetBrains IDE와 함께 사용하고 "사용 가능한 IDE가 감지되지 않음"이 표시되는 경우, 원인은 일반적으로 WSL2의 NAT 네트워킹 또는 Windows 방화벽이 WSL2와 Windows 호스트에서 실행 중인 IDE 간의 연결을 차단하기 때문입니다. WSL1은 호스트의 네트워크를 직접 사용하므로 영향을 받지 않습니다.149Claude Code를 WSL2의 JetBrains IDE와 함께 사용하고 "사용 가능한 IDE가 감지되지 않음"이 표시되는 경우, 원인은 일반적으로 WSL2의 NAT 네트워킹 또는 Windows 방화벽이 WSL2와 Windows 호스트에서 실행 중인 IDE 간의 연결을 차단하기 때문입니다. WSL1은 호스트의 네트워크를 직접 사용하므로 영향을 받지 않습니다.

112 150 

113#### Windows 방화벽을 통해 WSL2 트래픽 허용151<h4 id="allow-wsl2-traffic-through-windows-firewall">

152 Windows 방화벽을 통해 WSL2 트래픽 허용

153</h4>

114 154 

115이것이 권장되는 해결책입니다. 기존 WSL2 네트워킹 모드를 유지하기 때문입니다.155이것이 권장되는 해결책입니다. 기존 WSL2 네트워킹 모드를 유지하기 때문입니다.

116 156 


138 </Step>178 </Step>

139</Steps>179</Steps>

140 180 

141#### WSL2를 미러링된 네트워킹으로 전환181<h4 id="switch-wsl2-to-mirrored-networking">

182 WSL2를 미러링된 네트워킹으로 전환

183</h4>

142 184 

143미러링된 네트워킹에는 Windows 11 22H2 이상이 필요합니다. Windows 10을 사용 중이면 대신 위의 방화벽 규칙을 사용합니다.185미러링된 네트워킹에는 Windows 11 22H2 이상이 필요합니다. Windows 10을 사용 중이면 대신 위의 방화벽 규칙을 사용합니다.

144 186 


151 193 

152그런 다음 PowerShell에서 `wsl --shutdown`으로 WSL을 다시 시작합니다.194그런 다음 PowerShell에서 `wsl --shutdown`으로 WSL을 다시 시작합니다.

153 195 

154## 문제 해결196<h2 id="troubleshooting">

197 문제 해결

198</h2>

155 199 

156### 플러그인이 작동하지 않음200<h3 id="plugin-not-working">

201 플러그인이 작동하지 않음

202</h3>

157 203 

158플러그인이 설치되었지만 Claude Code 기능이 IDE에 나타나지 않는 경우:204플러그인이 설치되었지만 Claude Code 기능이 IDE에 나타나지 않는 경우:

159 205 


162* IDE를 완전히 다시 시작합니다 (여러 번 수행해야 할 수 있습니다)208* IDE를 완전히 다시 시작합니다 (여러 번 수행해야 할 수 있습니다)

163* 원격 개발의 경우 플러그인이 원격 호스트에 설치되어 있는지 확인합니다209* 원격 개발의 경우 플러그인이 원격 호스트에 설치되어 있는지 확인합니다

164 210 

165### IDE가 감지되지 않음211<h3 id="ide-not-detected">

212 IDE가 감지되지 않음

213</h3>

166 214 

167`claude` 실행 시 "사용 가능한 IDE가 감지되지 않음"이 표시되는 경우:215`claude` 실행 시 "사용 가능한 IDE가 감지되지 않음"이 표시되는 경우:

168 216 

169* 플러그인이 설치되고 활성화되어 있는지 확인합니다217* 플러그인이 설치되고 활성화되어 있는지 확인합니다

170* IDE를 완전히 다시 시작합니다218* IDE를 완전히 다시 시작합니다

171* 통합 터미널에서 Claude Code를 실행 중인지 확인합니다219* 통합 터미널에서 Claude Code를 실행 중인지 확인합니다

172* WSL 사용자의 경우 위의 [WSL 구성](#wsl-구성)을 참조하세요220* WSL 사용자의 경우 위의 [WSL 구성](#wsl-configuration)을 참조하세요

173 221 

174### 명령을 찾을 수 없음222<h3 id="command-not-found">

223 명령을 찾을 수 없음

224</h3>

175 225 

176Claude 아이콘을 클릭하면 "명령을 찾을 수 없음"이 표시되는 경우:226Claude 아이콘을 클릭하면 "명령을 찾을 수 없음"이 표시되는 경우:

177 227 


1792. 플러그인 설정에서 Claude 명령 경로를 구성합니다2292. 플러그인 설정에서 Claude 명령 경로를 구성합니다

1803. WSL 사용자의 경우 구성 섹션에서 언급한 WSL 명령 형식을 사용합니다2303. WSL 사용자의 경우 구성 섹션에서 언급한 WSL 명령 형식을 사용합니다

181 231 

182## 보안 고려 사항232<h2 id="security-considerations">

233 보안 고려 사항

234</h2>

183 235 

184Claude Code가 자동 편집 권한이 활성화된 JetBrains IDE에서 실행될 때, IDE에서 자동으로 실행될 수 있는 IDE 구성 파일을 수정할 수 있습니다. 이는 자동 편집 모드에서 Claude Code를 실행하는 위험을 증가시킬 수 있으며 bash 실행에 대한 Claude Code의 권한 프롬프트를 우회할 수 있습니다.236Claude Code가 자동 편집 권한이 활성화된 JetBrains IDE에서 실행될 때, IDE에서 자동으로 실행될 수 있는 IDE 구성 파일을 수정할 수 있습니다. 이는 자동 편집 모드에서 Claude Code를 실행하는 위험을 증가시킬 수 있으며 bash 실행에 대한 Claude Code의 권한 프롬프트를 우회할 수 있습니다.

185 237 

keybindings.md +2 −2

Details

203`Task` 컨텍스트에서 사용 가능한 작업:203`Task` 컨텍스트에서 사용 가능한 작업:

204 204 

205| 작업 | 기본값 | 설명 |205| 작업 | 기본값 | 설명 |

206| :---------------- | :----- | :--------------- |206| :---------------- | :-------------------- | :------------------------------------------------------------------------------------------------------ |

207| `task:background` | Ctrl+B | 현재 작업을 백그라운드로 이동 |207| `task:background` | Ctrl+B, Ctrl+X Ctrl+B | 현재 작업을 백그라운드로 이동합니다. {/* min-version: 2.1.169 */}Ctrl+X Ctrl+B 조합은 v2.1.169 이상이 필요하며 tmux 접두사 충돌을 방지합니다 |

208 208 

209<h3 id="theme-actions">209<h3 id="theme-actions">

210 테마 작업210 테마 작업

large-codebases.md +10 −10

Details

30| 파일 스캔 대신 언어 서버를 통해 기호의 정의 또는 호출자 찾기 | [코드 인텔리전스 플러그인](#reduce-file-reads-with-code-intelligence) |30| 파일 스캔 대신 언어 서버를 통해 기호의 정의 또는 호출자 찾기 | [코드 인텔리전스 플러그인](#reduce-file-reads-with-code-intelligence) |

31| Claude가 워크트리를 생성할 때 작업에 필요한 디렉토리만 체크아웃 | [`worktree.sparsePaths`](#check-out-only-the-directories-you-need) |31| Claude가 워크트리를 생성할 때 작업에 필요한 디렉토리만 체크아웃 | [`worktree.sparsePaths`](#check-out-only-the-directories-you-need) |

32| 같은 세션에서 형제 패키지 또는 다른 저장소 읽기 및 편집 | [`--add-dir`](#grant-access-across-packages-or-repositories) 또는 `additionalDirectories` |32| 같은 세션에서 형제 패키지 또는 다른 저장소 읽기 및 편집 | [`--add-dir`](#grant-access-across-packages-or-repositories) 또는 `additionalDirectories` |

33| Claude에 관련이 있을 때만 로드되는 한 영역에 특정한 절차 제공 | 디렉토리별 [스킬](#add-per-directory-skills) |33| Claude에 관련이 있을 때만 로드되는 한 영역에 특정한 절차 제공 | 디렉토리별 [skills](#add-per-directory-skills) |

34| 많은 디렉토리별 CLAUDE.md 파일을 모든 사람이 설치하는 하나의 규칙 세트로 대체 | 내부 마켓플레이스의 [플러그인](#centralize-conventions-when-layering-stops-scaling) |34| 많은 디렉토리별 CLAUDE.md 파일을 모든 사람이 설치하는 하나의 규칙 세트로 대체 | 내부 마켓플레이스의 [플러그인](#centralize-conventions-when-layering-stops-scaling) |

35 35 

36<Tip>36<Tip>


148 148 

149다른 팀의 패키지, 레거시 코드, 또는 벤더된 하위 트리와 같이 작업하지 않는 디렉토리에 사용하십시오. 제외 목록은 정적이며 작업별 스위치가 아닙니다. 오늘 한 패키지에 집중하고 내일 다른 패키지에 집중하려면 제외를 편집하는 대신 [해당 패키지의 디렉토리에서 Claude를 시작](#choose-where-to-start-claude)하십시오.149다른 팀의 패키지, 레거시 코드, 또는 벤더된 하위 트리와 같이 작업하지 않는 디렉토리에 사용하십시오. 제외 목록은 정적이며 작업별 스위치가 아닙니다. 오늘 한 패키지에 집중하고 내일 다른 패키지에 집중하려면 제외를 편집하는 대신 [해당 패키지의 디렉토리에서 Claude를 시작](#choose-where-to-start-claude)하십시오.

150 150 

151이 제외를 자신만을 위해 원하면 설정을 `.claude/settings.local.json`에 넣으십시오. 이는 gitignored이고 커밋되지 않습니다. 패턴은 절대 파일 경로와 일치하는 글로브 구문을 사용하므로 상대 스타일 패턴을 `**/`로 시작하여 트리의 어디든 일치시킵니다. 아래 예제는 다른 팀이 소유한 패키지를 제외합니다:151이 제외를 자신만을 위해 원하면 설정을 `.claude/settings.local.json`에 넣으십시오. Claude Code는 이를 생성할 때 gitignore합니다. 여기서 직접 생성하므로 gitignore에 추가하십시오. 패턴은 절대 파일 경로와 일치하는 glob 구문을 사용하므로 상대 스타일 패턴을 `**/`로 시작하여 트리의 어디든 일치시킵니다. 아래 예제는 다른 팀이 소유한 패키지를 제외합니다:

152 152 

153```json .claude/settings.local.json theme={null}153```json .claude/settings.local.json theme={null}

154{154{


220 220 

221코드 인텔리전스 플러그인은 각 개발자의 머신에 언어의 언어 서버 바이너리가 필요합니다. [각 언어가 필요로 하는 바이너리](/ko/discover-plugins#code-intelligence)를 참조하십시오. 공식 마켓플레이스에서 설치하려면 마켓플레이스가 호스팅되는 GitHub에 대한 네트워크 액세스가 필요합니다. 제한된 네트워크에서는 [내부 Git 호스트 또는 로컬 경로에서 마켓플레이스를 추가](/ko/discover-plugins#add-from-other-git-hosts)하십시오.221코드 인텔리전스 플러그인은 각 개발자의 머신에 언어의 언어 서버 바이너리가 필요합니다. [각 언어가 필요로 하는 바이너리](/ko/discover-plugins#code-intelligence)를 참조하십시오. 공식 마켓플레이스에서 설치하려면 마켓플레이스가 호스팅되는 GitHub에 대한 네트워크 액세스가 필요합니다. 제한된 네트워크에서는 [내부 Git 호스트 또는 로컬 경로에서 마켓플레이스를 추가](/ko/discover-plugins#add-from-other-git-hosts)하십시오.

222 222 

223이는 위의 `claudeMdExcludes` 및 `Read` 거부 규칙과 잘 어울립니다. 이들은 관련 없는 콘텐츠를 컨텍스트에서 벗어나게 하고, 코드 인텍스는 Claude가 정의를 찾기 위해 남은 것을 읽지 못하도록 합니다.223이는 위의 `claudeMdExcludes` 및 `Read` 거부 규칙과 잘 어울립니다. 이들은 관련 없는 콘텐츠를 컨텍스트에서 벗어나게 하고, 코드 인텔리전스는 Claude가 정의를 찾기 위해 남은 것을 읽지 못하도록 합니다.

224 224 

225<h2 id="scope-worktrees-and-file-access">225<h2 id="scope-worktrees-and-file-access">

226 워크트리 및 파일 액세스 범위 지정226 워크트리 및 파일 액세스 범위 지정


385범위 내 스킬은 Claude를 시작하는 위치에 따라 다릅니다:385범위 내 스킬은 Claude를 시작하는 위치에 따라 다릅니다:

386 386 

387* **`packages/api/`와 같은 하위 디렉토리에서**: 해당 디렉토리의 스킬, 저장소 루트까지의 모든 상위 항목, 사용자 및 엔터프라이즈 수준387* **`packages/api/`와 같은 하위 디렉토리에서**: 해당 디렉토리의 스킬, 저장소 루트까지의 모든 상위 항목, 사용자 및 엔터프라이즈 수준

388* **저장소 루트에서**: 세션 중에 Claude가 터치하는 모든 하위 디렉토리의 스킬. 수백 개로 누적될 수 있음388* **저장소 루트에서**: 세션 중에 Claude가 터치하는 모든 하위 디렉토리의 스킬. 수백 개로 누적될 수 있습니다.

389* **[`--add-dir`](#grant-access-across-packages-or-repositories)으로 형제 추가 후**: 해당 형제의 스킬도 로드됩니다. `additionalDirectories` 설정은 파일 액세스만 부여하고 스킬을 로드하지 않습니다.389* **[`--add-dir`](#grant-access-across-packages-or-repositories)으로 형제 추가 후**: 해당 형제의 스킬도 로드됩니다. `additionalDirectories` 설정은 파일 액세스만 부여하고 스킬을 로드하지 않습니다.

390 390 

391이름은 항상 로드되지만 [많은 스킬이 있을 때 설명이 단축되어](/ko/skills#skill-descriptions-are-cut-short) Claude가 스킬 적용 여부를 결정하는 데 사용하는 키워드를 제거할 수 있습니다. 설명을 짧게 유지하고 요청에 포함될 단어로 시작하십시오. 예를 들어 "`packages/api/`에서 테스트 작성 또는 수정".391이름은 항상 로드되지만 [많은 스킬이 있을 때 설명이 단축되어](/ko/skills#skill-descriptions-are-cut-short) Claude가 스킬 적용 여부를 결정하는 데 사용하는 키워드를 제거할 수 있습니다. 설명을 짧게 유지하고 요청에 포함될 단어로 시작하십시오. 예를 들어 "`packages/api/`에서 테스트 작성 또는 수정".


402 402 

403항상 로드되는 CLAUDE.md에서 규칙 및 참조 콘텐츠를 작업과 관련이 있을 때만 로드되는 메커니즘으로 이동하십시오:403항상 로드되는 CLAUDE.md에서 규칙 및 참조 콘텐츠를 작업과 관련이 있을 때만 로드되는 메커니즘으로 이동하십시오:

404 404 

405* [스킬](/ko/skills): Claude가 작업과 관련이 있을 때만 로드하는 참조 자료405* [Skills](/ko/skills): Claude가 작업과 관련이 있을 때만 로드하는 참조 자료

406* [플러그인](/ko/plugins): 플랫폼 팀이 중앙에서 소유하는 스킬, 훅, 명령의 버전 관리 번들406* [Plugins](/ko/plugins): 플랫폼 팀이 중앙에서 소유하는 스킬, 훅, 명령의 버전 관리 번들

407* [MCP 서버](/ko/mcp): 조직이 이미 저장소에 대한 코드 검색 또는 RAG 인덱스를 실행하면 MCP 도구로 노출하여 Claude가 파일을 직접 읽는 대신 쿼리하도록 합니다.407* [MCP servers](/ko/mcp): 조직이 이미 저장소에 대한 코드 검색 또는 RAG 인덱스를 실행하면 MCP 도구로 노출하여 Claude가 파일을 직접 읽는 대신 쿼리하도록 합니다.

408 408 

409플랫폼 팀이 이를 중앙에서 적용하는 방법은 [서버 관리 또는 엔드포인트 관리 설정](/ko/server-managed-settings#choose-between-server-managed-and-endpoint-managed-settings)을 참조하십시오.409플랫폼 팀이 이를 중앙에서 적용하는 방법은 [server-managed or endpoint-managed settings](/ko/server-managed-settings#choose-between-server-managed-and-endpoint-managed-settings)을 참조하십시오.

410 410 

411<h3 id="recommend-the-right-plugin-at-session-start">411<h3 id="recommend-the-right-plugin-at-session-start">

412 세션 시작 시 올바른 플러그인 권장412 세션 시작 시 올바른 플러그인 권장

413</h3>413</h3>

414 414 

415규칙이 플러그인에 있으면 팀원이 트리의 낯선 부분에서 Claude를 시작할 때 해당 영역의 소유자가 유지하는 플러그인에 대한 신호가 없습니다. [`SessionStart` ](/ko/hooks#sessionstart)은 훅이 stdout에 인쇄하는 모든 것이 첫 번째 프롬프트 전에 Claude의 컨텍스트에 추가되므로 이 간격을 닫을 수 있습니다.415규칙이 플러그인에 있으면 팀원이 트리의 낯선 부분에서 Claude를 시작할 때 해당 영역의 소유자가 유지하는 플러그인에 대한 신호가 없습니다. [`SessionStart` hook](/ko/hooks#sessionstart)은 훅이 stdout에 인쇄하는 모든 것이 첫 번째 프롬프트 전에 Claude의 컨텍스트에 추가되므로 이 간격을 닫을 수 있습니다.

416 416 

417예를 들어 [ 입력](/ko/hooks#common-input-fields)에서 시작 디렉토리를 읽고, 저장소에 커밋된 경로-플러그인 맵에서 조회하고, Claude가 첫 번째 응답에서 전달할 권장 사항을 인쇄하는 스크립트를 작성할 수 있습니다. 훅을 작성하고 등록하려면 [훅으로 작업 자동화](/ko/hooks-guide)를 참조하십시오.417예를 들어 [hook input](/ko/hooks#common-input-fields)에서 시작 디렉토리를 읽고, 저장소에 커밋된 경로-플러그인 맵에서 조회하고, Claude가 첫 번째 응답에서 전달할 권장 사항을 인쇄하는 스크립트를 작성할 수 있습니다. 훅을 작성하고 등록하려면 [Automate actions with hooks](/ko/hooks-guide)를 참조하십시오.

418 418 

419<h2 id="put-it-together">419<h2 id="put-it-together">

420 모두 함께 사용420 모두 함께 사용

llm-gateway.md +2 −0

Details

14* **감사 로깅** - 규정 준수를 위한 모든 모델 상호작용 추적14* **감사 로깅** - 규정 준수를 위한 모든 모델 상호작용 추적

15* **모델 라우팅** - 코드 변경 없이 공급자 간 전환15* **모델 라우팅** - 코드 변경 없이 공급자 간 전환

16 16 

17이 페이지는 Claude Code CLI의 gateway 요구사항 및 구성을 다룹니다. Enterprise Desktop 배포는 [관리되는 설정](https://support.claude.com/ko/articles/12622667-enterprise-configuration)을 통해 gateway 공급자를 구성할 수 있습니다. Claude Desktop 앱은 자체 구성 키를 사용하는 [Cowork on 3P research preview](https://claude.com/docs/cowork/3p/gateway)를 통해 자체 호스팅된 gateway에 대해 실행할 수도 있습니다.

18 

17<h2 id="gateway-requirements">19<h2 id="gateway-requirements">

18 Gateway 요구사항20 Gateway 요구사항

19</h2>21</h2>

managed-mcp.md +1 −1

Details

44 managed-mcp.json으로 독점 제어44 managed-mcp.json으로 독점 제어

45</h2>45</h2>

46 46 

47`managed-mcp.json` 파일을 배포하면 Claude Code는 해당 파일이 정의하는 서버만 로드합니다. 사용자는 플러그인 제공 서버를 포함한 다른 MCP 서버를 추가, 수정 또는 사용할 수 없으며, claude.ai 커넥터도 사용할 수 없습니다. 이 파일은 [관리형 집합과 함께 허용](#allow-claude-ai-connectors-alongside-the-managed-set)하지 않는 한 claude.ai 커넥터도 억제합니다.47`managed-mcp.json` 파일을 배포하면 Claude Code는 해당 파일이 정의하는 서버만 로드합니다. 사용자는 플러그인 제공 서버를 포함한 다른 MCP 서버를 추가, 수정 또는 사용할 수 없습니다. 이 파일은 [관리형 집합과 함께 허용](#allow-claude-ai-connectors-alongside-the-managed-set)하지 않는 한 claude.ai 커넥터도 억제합니다.

48 48 

49두 가지 다른 설정이 관리형 집합을 추가로 필터링할 수 있습니다:49두 가지 다른 설정이 관리형 집합을 추가로 필터링할 수 있습니다:

50 50 

mcp.md +166 −80

Details

12 12 

13첫 번째 서버를 연결하는 경우 단계별 안내를 위해 [MCP 빠른 시작](/ko/mcp-quickstart)으로 시작하세요. 이 페이지는 전체 참고 자료입니다.13첫 번째 서버를 연결하는 경우 단계별 안내를 위해 [MCP 빠른 시작](/ko/mcp-quickstart)으로 시작하세요. 이 페이지는 전체 참고 자료입니다.

14 14 

15## MCP로 할 수 있는 15<h2 id="what-you-can-do-with-mcp">

16 MCP로 할 수 있는 것

17</h2>

16 18 

17MCP 서버가 연결되면 Claude Code에 다음을 요청할 수 있습니다:19MCP 서버가 연결되면 Claude Code에 다음을 요청할 수 있습니다:

18 20 


23* **워크플로우 자동화**: "이 10명의 사용자를 새로운 기능에 대한 피드백 세션에 초대하는 Gmail 초안을 생성하세요."25* **워크플로우 자동화**: "이 10명의 사용자를 새로운 기능에 대한 피드백 세션에 초대하는 Gmail 초안을 생성하세요."

24* **외부 이벤트에 반응**: MCP 서버는 [채널](/ko/channels)로도 작동할 수 있으며, 세션에 메시지를 푸시하므로 Claude는 자리를 비운 동안 Telegram 메시지, Discord 채팅 또는 webhook 이벤트에 반응할 수 있습니다.26* **외부 이벤트에 반응**: MCP 서버는 [채널](/ko/channels)로도 작동할 수 있으며, 세션에 메시지를 푸시하므로 Claude는 자리를 비운 동안 Telegram 메시지, Discord 채팅 또는 webhook 이벤트에 반응할 수 있습니다.

25 27 

26## MCP 서버 찾기 및 구축28<h2 id="find-and-build-mcp-servers">

29 MCP 서버 찾기 및 구축

30</h2>

27 31 

28[Anthropic Directory](https://claude.ai/directory)에서 검토된 커넥터를 찾아보세요. Directory 커넥터는 Claude Code와 동일한 MCP 인프라를 사용하므로 `claude mcp add`를 사용하여 여기에 나열된 모든 원격 서버를 추가할 수 있습니다.32[Anthropic Directory](https://claude.ai/directory)에서 검토된 커넥터를 찾아보세요. Directory 커넥터는 Claude Code와 동일한 MCP 인프라를 사용하므로 `claude mcp add`를 사용하여 여기에 나열된 모든 원격 서버를 추가할 수 있습니다.

29 33 


55 </Step>59 </Step>

56</Steps>60</Steps>

57 61 

58## MCP 서버 설치62<h2 id="installing-mcp-servers">

63 MCP 서버 설치

64</h2>

59 65 

60MCP 서버는 필요에 따라 여러 가지 방식으로 구성할 수 있습니다:66MCP 서버는 필요에 따라 여러 가지 방식으로 구성할 수 있습니다:

61 67 

62### 옵션 1: 원격 HTTP 서버 추가68<h3 id="option-1-add-a-remote-http-server">

69 옵션 1: 원격 HTTP 서버 추가

70</h3>

63 71 

64HTTP 서버는 원격 MCP 서버에 연결하기 위한 권장 옵션입니다. 이는 클라우드 기반 서비스에 가장 널리 지원되는 전송 방식입니다.72HTTP 서버는 원격 MCP 서버에 연결하기 위한 권장 옵션입니다. 이는 클라우드 기반 서비스에 가장 널리 지원되는 전송 방식입니다.

65 73 


77 85 

78`.mcp.json`, `~/.claude.json` 또는 `claude mcp add-json`을 통해 JSON으로 MCP 서버를 구성할 때, `type` 필드는 `http`의 별칭으로 `streamable-http`를 허용합니다. MCP 사양은 이 전송에 대해 `streamable-http`라는 이름을 사용하므로 서버 설명서에서 복사한 구성이 수정 없이 작동합니다.86`.mcp.json`, `~/.claude.json` 또는 `claude mcp add-json`을 통해 JSON으로 MCP 서버를 구성할 때, `type` 필드는 `http`의 별칭으로 `streamable-http`를 허용합니다. MCP 사양은 이 전송에 대해 `streamable-http`라는 이름을 사용하므로 서버 설명서에서 복사한 구성이 수정 없이 작동합니다.

79 87 

80### 옵션 2: 원격 SSE 서버 추가88<h3 id="option-2-add-a-remote-sse-server">

89 옵션 2: 원격 SSE 서버 추가

90</h3>

81 91 

82<Warning>92<Warning>

83 SSE (Server-Sent Events) 전송은 더 이상 사용되지 않습니다. 가능한 경우 HTTP 서버를 사용하세요.93 SSE (Server-Sent Events) 전송은 더 이상 사용되지 않습니다. 가능한 경우 HTTP 서버를 사용하세요.


95 --header "X-API-Key: your-key-here"105 --header "X-API-Key: your-key-here"

96```106```

97 107 

98### 옵션 3: 로컬 stdio 서버 추가108<h3 id="option-3-add-a-local-stdio-server">

109 옵션 3: 로컬 stdio 서버 추가

110</h3>

99 111 

100Stdio 서버는 컴퓨터에서 로컬 프로세스로 실행됩니다. 시스템에 직접 액세스하거나 사용자 정의 스크립트가 필요한 도구에 이상적입니다.112Stdio 서버는 컴퓨터에서 로컬 프로세스로 실행됩니다. 시스템에 직접 액세스하거나 사용자 정의 스크립트가 필요한 도구에 이상적입니다.

101 113 


108claude mcp add [options] <name> -- <command> [args...]120claude mcp add [options] <name> -- <command> [args...]

109 121 

110# 실제 예: Airtable 서버 추가122# 실제 예: Airtable 서버 추가

111claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \123claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \

112 -- npx -y airtable-mcp-server124 -- npx -y airtable-mcp-server

113```125```

114 126 

115<Note>127<Note>

116 **중요: 옵션 순서**128 **중요: 서버 인수를 `--`로 구분**

117 129 

118 모든 옵션(`--transport`, `--env`, `--scope`, `--header`) 서버 이름 **앞에** 와야 합니다. `--` (이중 대시)는 서버 이름과 MCP 서버에 전달되는 명령 및 인수를 구분합니다.130 Stdio 서버의 경우, `--` (이중 대시)는 Claude의 자체 옵션(예: `--transport`, `--env`, `--scope`) 서버를 실행하는 명령 인수를 구분합니다. `--` 이후의 모든 것은 서버에 그대로 전달됩니다.

119 131 

120 예를 들어:132 예를 들어:

121 133 

122 * `claude mcp add --transport stdio myserver -- npx server` → `npx server` 실행134 * `claude mcp add --transport stdio myserver -- npx server` → `npx server` 실행

123 * `claude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080` → `KEY=value`를 환경에서 `python server.py --port 8080` 실행135 * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → 환경에서 `KEY=value`를 사용하여 `python server.py --port 8080` 실행

124 136 

125 이는 Claude의 플래그와 서버의 플래그 간의 충돌을 방지합니다.137 `--`가 없으면 Claude Code는 위의 `--port`와 같은 서버의 플래그를 자신의 옵션으로 구문 분석하려고 시도합니다.

138 

139 `--env`는 여러 `KEY=value` 쌍을 허용합니다. 서버 이름이 `--env` 직후에 오면 CLI는 이름을 다른 쌍으로 읽고 거부하므로 위의 예와 같이 `--env`와 서버 이름 사이에 최소한 하나의 다른 옵션을 배치하세요.

126</Note>140</Note>

127 141 

128### 옵션 4: 원격 WebSocket 서버 추가142<h3 id="option-4-add-a-remote-websocket-server">

143 옵션 4: 원격 WebSocket 서버 추가

144</h3>

129 145 

130WebSocket 서버는 지속적인 양방향 연결을 유지하므로 Claude에 예고 없이 이벤트를 푸시하는 원격 MCP 서버에 적합합니다. 서버가 요청에만 응답하는 경우 HTTP를 대신 사용하세요. HTTP는 OAuth 및 `claude mcp add --transport` 플래그를 지원하지만 WebSocket은 둘 다 지원하지 않습니다.146WebSocket 서버는 지속적인 양방향 연결을 유지하므로 Claude에 예고 없이 이벤트를 푸시하는 원격 MCP 서버에 적합합니다. 서버가 요청에만 응답하는 경우 HTTP를 대신 사용하세요. HTTP는 OAuth 및 `claude mcp add --transport` 플래그를 지원하지만 WebSocket은 둘 다 지원하지 않습니다.

131 147 


138 154 

139`type: "ws"` 항목은 `http`와 동일한 `url`, `headers`, `headersHelper`, `timeout` 및 `alwaysLoad` 필드를 허용합니다. 인증은 헤더 전용이므로 `headers`에 정적 토큰을 전달하거나 [`headersHelper`](#use-dynamic-headers-for-custom-authentication)를 사용하여 연결 시 토큰을 생성하세요. `claude mcp add --transport` 플래그는 `ws`를 허용하지 않습니다.155`type: "ws"` 항목은 `http`와 동일한 `url`, `headers`, `headersHelper`, `timeout` 및 `alwaysLoad` 필드를 허용합니다. 인증은 헤더 전용이므로 `headers`에 정적 토큰을 전달하거나 [`headersHelper`](#use-dynamic-headers-for-custom-authentication)를 사용하여 연결 시 토큰을 생성하세요. `claude mcp add --transport` 플래그는 `ws`를 허용하지 않습니다.

140 156 

141### 서버 관리157<h3 id="managing-your-servers">

158 서버 관리

159</h3>

142 160 

143구성한 후에는 다음 명령으로 MCP 서버를 관리할 수 있습니다:161구성한 후에는 다음 명령으로 MCP 서버를 관리할 수 있습니다:

144 162 


164 182 

165서버 이름 `workspace`는 내부 사용을 위해 예약되어 있습니다. 구성에서 해당 이름의 서버를 정의하면 Claude Code는 로드 시 이를 건너뛰고 이름을 바꾸도록 요청하는 경고를 표시합니다.183서버 이름 `workspace`는 내부 사용을 위해 예약되어 있습니다. 구성에서 해당 이름의 서버를 정의하면 Claude Code는 로드 시 이를 건너뛰고 이름을 바꾸도록 요청하는 경고를 표시합니다.

166 184 

167### 동적 도구 업데이트185<h3 id="dynamic-tool-updates">

186 동적 도구 업데이트

187</h3>

168 188 

169Claude Code는 MCP `list_changed` 알림을 지원하므로 MCP 서버가 연결을 끊었다가 다시 연결할 필요 없이 사용 가능한 도구, 프롬프트 및 리소스를 동적으로 업데이트할 수 있습니다. MCP 서버가 `list_changed` 알림을 보내면 Claude Code는 해당 서버에서 사용 가능한 기능을 자동으로 새로 고칩니다.189Claude Code는 MCP `list_changed` 알림을 지원하므로 MCP 서버가 연결을 끊었다가 다시 연결할 필요 없이 사용 가능한 도구, 프롬프트 및 리소스를 동적으로 업데이트할 수 있습니다. MCP 서버가 `list_changed` 알림을 보내면 Claude Code는 해당 서버에서 사용 가능한 기능을 자동으로 새로 고칩니다.

170 190 

171### 자동 재연결191<h3 id="automatic-reconnection">

192 자동 재연결

193</h3>

172 194 

173HTTP 또는 SSE 서버가 세션 중에 연결이 끊어지면 Claude Code는 지수 백오프를 사용하여 자동으로 재연결합니다: 최대 5번의 시도, 1초 지연으로 시작하여 매번 두 배씩 증가합니다. 서버는 재연결이 진행 중인 동안 `/mcp`에서 보류 중으로 나타납니다. 5번의 실패 시도 후 서버는 실패로 표시되며 `/mcp`에서 수동으로 다시 시도할 수 있습니다. Stdio 서버는 로컬 프로세스이며 자동으로 재연결되지 않습니다.195HTTP 또는 SSE 서버가 세션 중에 연결이 끊어지면 Claude Code는 지수 백오프를 사용하여 자동으로 재연결합니다: 최대 5번의 시도, 1초 지연으로 시작하여 매번 두 배씩 증가합니다. 서버는 재연결이 진행 중인 동안 `/mcp`에서 보류 중으로 나타납니다. 5번의 실패 시도 후 서버는 실패로 표시되며 `/mcp`에서 수동으로 다시 시도할 수 있습니다. Stdio 서버는 로컬 프로세스이며 자동으로 재연결되지 않습니다.

174 196 

175HTTP 또는 SSE 서버가 시작 시 초기 연결에 실패할 때도 동일한 백오프가 적용됩니다. v2.1.121부터 Claude Code는 5xx 응답, 연결 거부 또는 시간 초과와 같은 일시적 오류에 대해 초기 연결을 최대 3번 재시도한 후, 여전히 연결할 수 없으면 서버를 실패로 표시합니다. 인증 및 찾을 수 없음 오류는 해결하기 위해 구성 변경이 필요하므로 재시도되지 않습니다.197HTTP 또는 SSE 서버가 시작 시 초기 연결에 실패할 때도 동일한 백오프가 적용됩니다. v2.1.121부터 Claude Code는 5xx 응답, 연결 거부 또는 시간 초과와 같은 일시적 오류에 대해 초기 연결을 최대 3번 재시도한 후, 여전히 연결할 수 없으면 서버를 실패로 표시합니다. 인증 및 찾을 수 없음 오류는 해결하기 위해 구성 변경이 필요하므로 재시도되지 않습니다.

176 198 

177### 채널을 사용한 메시지 푸시199<h3 id="push-messages-with-channels">

200 채널을 사용한 메시지 푸시

201</h3>

178 202 

179MCP 서버는 또한 메시지를 세션에 직접 푸시할 수 있으므로 Claude는 CI 결과, 모니터링 경고 또는 채팅 메시지와 같은 외부 이벤트에 반응할 수 있습니다. 이를 활성화하려면 서버가 `claude/channel` 기능을 선언하고 시작 시 `--channels` 플래그로 옵트인합니다. 공식적으로 지원되는 채널을 사용하려면 [채널](/ko/channels)을 참조하거나, 자신만의 채널을 구축하려면 [채널 참조](/ko/channels-reference)를 참조하세요.203MCP 서버는 또한 메시지를 세션에 직접 푸시할 수 있으므로 Claude는 CI 결과, 모니터링 경고 또는 채팅 메시지와 같은 외부 이벤트에 반응할 수 있습니다. 이를 활성화하려면 서버가 `claude/channel` 기능을 선언하고 시작 시 `--channels` 플래그로 옵트인합니다. 공식적으로 지원되는 채널을 사용하려면 [채널](/ko/channels)을 참조하거나, 자신만의 채널을 구축하려면 [채널 참조](/ko/channels-reference)를 참조하세요.

180 204 


192 * OAuth 2.0 인증이 필요한 원격 서버로 인증하려면 `/mcp`를 사용하세요216 * OAuth 2.0 인증이 필요한 원격 서버로 인증하려면 `/mcp`를 사용하세요

193</Tip>217</Tip>

194 218 

195서버당 `timeout`은 도구 호출당 하드 월클록 제한이며, 서버의 진행 알림은 이를 연장하지 않습니다. 1000 미만의 값은 1초로 내림됩니다. HTTP 및 SSE 서버의 경우, 요청당 fetch 첫 바이트 예산은 이 값에 관계없이 최소 60초이므로 도구 호출 감시견만 더 작은 값을 준수합니다.219서버당 `timeout`은 도구 호출당 하드 월클록 제한이며, 서버의 진행 알림은 이를 연장하지 않습니다. 1000 미만의 값은 무시되고 `MCP_TOOL_TIMEOUT`으로 넘어가거나, 해당 변수가 설정되지 않은 경우 약 28시간의 기본값으로 넘어갑니다. {/* min-version: 2.1.162 */}v2.1.162 이전에는 1000 미만의 값이 1초로 내림되었습니다. HTTP 및 SSE 서버의 경우, 요청당 fetch 첫 바이트 예산은 60초 최소값을 가집니다.

196 220 

197### 플러그인 제공 MCP 서버221<h3 id="plugin-provided-mcp-servers">

222 플러그인 제공 MCP 서버

223</h3>

198 224 

199[플러그인](/ko/plugins)은 MCP 서버를 번들로 제공할 수 있으며, 플러그인이 활성화되면 도구 및 통합을 자동으로 제공합니다. 플러그인 MCP 서버는 사용자 구성 서버와 동일하게 작동합니다.225[플러그인](/ko/plugins)은 MCP 서버를 번들로 제공할 수 있으며, 플러그인이 활성화되면 도구 및 통합을 자동으로 제공합니다. 플러그인 MCP 서버는 사용자 구성 서버와 동일하게 작동합니다.

200 226 


253 279 

254플러그인 서버는 플러그인에서 온 것을 나타내는 표시기와 함께 목록에 나타납니다.280플러그인 서버는 플러그인에서 온 것을 나타내는 표시기와 함께 목록에 나타납니다.

255 281 

282**플러그인 MCP 도구 이름**:

283 

284플러그인 번들 MCP 서버의 도구는 호출 가능한 이름에 플러그인 이름과 서버 키를 모두 포함합니다. 전체 형식은 `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`이며, `A-Z`, `a-z`, `0-9`, `_`, `-` 외의 모든 문자는 `_`로 바뀝니다. `my-plugin`이라는 플러그인에 번들된 `database-tools` 서버의 경우, `query` 도구는 다음과 같이 호출할 수 있습니다:

285 

286```

287mcp__plugin_my-plugin_database-tools__query

288```

289 

290[권한 규칙](/ko/permissions)에서 도구를 참조할 때, 스킬의 `allowed-tools` 목록에서, 또는 [서브에이전트의 `tools` 필드](/ko/sub-agents#available-tools)에서 이 전체 이름을 사용하세요.

291 

256**플러그인 MCP 서버의 이점**:292**플러그인 MCP 서버의 이점**:

257 293 

258* **번들 배포**: 도구 및 서버가 함께 패키징됨294* **번들 배포**: 도구 및 서버가 함께 패키징됨


261 297 

262플러그인과 함께 MCP 서버를 번들로 제공하는 방법에 대한 자세한 내용은 [플러그인 구성 요소 참조](/ko/plugins-reference#mcp-servers)를 참조하세요.298플러그인과 함께 MCP 서버를 번들로 제공하는 방법에 대한 자세한 내용은 [플러그인 구성 요소 참조](/ko/plugins-reference#mcp-servers)를 참조하세요.

263 299 

264## MCP 설치 범위300<h2 id="mcp-installation-scopes">

301 MCP 설치 범위

302</h2>

265 303 

266MCP 서버는 세 가지 범위에서 구성할 수 있습니다. 선택한 범위는 서버가 로드되는 프로젝트와 구성이 팀과 공유되는지 여부를 제어합니다. 관리자는 [관리형 구성](#managed-mcp-configuration)을 통해 엔터프라이즈 수준에서 서버를 배포할 수도 있습니다.304MCP 서버는 세 가지 범위에서 구성할 수 있습니다. 선택한 범위는 서버가 로드되는 프로젝트와 구성이 팀과 공유되는지 여부를 제어합니다. 관리자는 [관리형 구성](#managed-mcp-configuration)을 통해 엔터프라이즈 수준에서 서버를 배포할 수도 있습니다.

267 305 


271| [프로젝트](#project-scope) | 현재 프로젝트만 | 예, 버전 제어를 통해 | 프로젝트 루트의 `.mcp.json` |309| [프로젝트](#project-scope) | 현재 프로젝트만 | 예, 버전 제어를 통해 | 프로젝트 루트의 `.mcp.json` |

272| [사용자](#user-scope) | 모든 프로젝트 | 아니오 | `~/.claude.json` |310| [사용자](#user-scope) | 모든 프로젝트 | 아니오 | `~/.claude.json` |

273 311 

274### 로컬 범위312<h3 id="local-scope">

313 로컬 범위

314</h3>

275 315 

276로컬 범위는 기본값입니다. 로컬 범위 서버는 추가한 프로젝트에서만 로드되며 사용자에게만 비공개입니다. Claude Code는 해당 프로젝트의 경로 아래 `~/.claude.json`에 저장하므로 다른 프로젝트에는 동일한 서버가 나타나지 않습니다. 개인 개발 서버, 실험적 구성 또는 버전 제어에 포함하고 싶지 않은 자격 증명이 있는 서버에 로컬 범위를 사용하세요.316로컬 범위는 기본값입니다. 로컬 범위 서버는 추가한 프로젝트에서만 로드되며 사용자에게만 비공개입니다. Claude Code는 해당 프로젝트의 경로 아래 `~/.claude.json`에 저장하므로 다른 프로젝트에는 동일한 서버가 나타나지 않습니다. 개인 개발 서버, 실험적 구성 또는 버전 제어에 포함하고 싶지 않은 자격 증명이 있는 서버에 로컬 범위를 사용하세요.

277 317 


304}344}

305```345```

306 346 

307### 프로젝트 범위347<h3 id="project-scope">

348 프로젝트 범위

349</h3>

308 350 

309프로젝트 범위 서버는 프로젝트 루트 디렉토리의 `.mcp.json` 파일에 구성을 저장하여 팀 협업을 가능하게 합니다. 이 파일은 버전 제어에 체크인되도록 설계되어 모든 팀 멤버가 동일한 MCP 도구 및 서비스에 액세스할 수 있도록 합니다. 프로젝트 범위 서버를 추가하면 Claude Code는 자동으로 이 파일을 생성하거나 적절한 구성 구조로 업데이트합니다.351프로젝트 범위 서버는 프로젝트 루트 디렉토리의 `.mcp.json` 파일에 구성을 저장하여 팀 협업을 가능하게 합니다. 이 파일은 버전 제어에 체크인되도록 설계되어 모든 팀 멤버가 동일한 MCP 도구 및 서비스에 액세스할 수 있도록 합니다. 프로젝트 범위 서버를 추가하면 Claude Code는 자동으로 이 파일을 생성하거나 적절한 구성 구조로 업데이트합니다.

310 352 


329 371 

330보안상의 이유로 Claude Code는 `.mcp.json` 파일의 프로젝트 범위 서버를 사용하기 전에 승인을 요청합니다. 이러한 승인 선택을 재설정해야 하는 경우 `claude mcp reset-project-choices` 명령을 사용하세요.372보안상의 이유로 Claude Code는 `.mcp.json` 파일의 프로젝트 범위 서버를 사용하기 전에 승인을 요청합니다. 이러한 승인 선택을 재설정해야 하는 경우 `claude mcp reset-project-choices` 명령을 사용하세요.

331 373 

332### 사용자 범위374<h3 id="user-scope">

375 사용자 범위

376</h3>

333 377 

334사용자 범위 서버는 `~/.claude.json`에 저장되며 교차 프로젝트 접근성을 제공하므로 컴퓨터의 모든 프로젝트에서 사용할 수 있으면서 사용자 계정에만 비공개입니다. 이 범위는 개인 유틸리티 서버, 개발 도구 또는 다양한 프로젝트에서 자주 사용하는 서비스에 적합합니다.378사용자 범위 서버는 `~/.claude.json`에 저장되며 교차 프로젝트 접근성을 제공하므로 컴퓨터의 모든 프로젝트에서 사용할 수 있으면서 사용자 계정에만 비공개입니다. 이 범위는 개인 유틸리티 서버, 개발 도구 또는 다양한 프로젝트에서 자주 사용하는 서비스에 적합합니다.

335 379 


338claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic382claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

339```383```

340 384 

341### 범위 계층 및 우선순위385<h3 id="scope-hierarchy-and-precedence">

386 범위 계층 및 우선순위

387</h3>

342 388 

343동일한 서버가 둘 이상의 위치에 정의되면 Claude Code는 가장 높은 우선순위 소스의 정의를 사용하여 한 번 연결합니다. 해당 소스의 전체 서버 항목이 사용되며, 필드는 범위 간에 병합되지 않습니다.389동일한 서버가 둘 이상의 위치에 정의되면 Claude Code는 가장 높은 우선순위 소스의 정의를 사용하여 한 번 연결합니다. 해당 소스의 전체 서버 항목이 사용되며, 필드는 범위 간에 병합되지 않습니다.

344 390 


350 396 

351세 범위는 이름으로 중복을 일치시킵니다. 플러그인과 커넥터는 엔드포인트로 일치하므로 위의 서버와 동일한 URL 또는 명령을 가리키는 것은 중복으로 처리됩니다.397세 범위는 이름으로 중복을 일치시킵니다. 플러그인과 커넥터는 엔드포인트로 일치하므로 위의 서버와 동일한 URL 또는 명령을 가리키는 것은 중복으로 처리됩니다.

352 398 

353### `.mcp.json`의 환경 변수 확장399<h3 id="environment-variable-expansion-in-mcp-json">

400 `.mcp.json`의 환경 변수 확장

401</h3>

354 402 

355Claude Code는 `.mcp.json` 파일의 환경 변수 확장을 지원하므로 팀이 구성을 공유하면서 머신 특정 경로 및 API 키와 같은 민감한 값에 대한 유연성을 유지할 수 있습니다.403Claude Code는 `.mcp.json` 파일의 환경 변수 확장을 지원하므로 팀이 구성을 공유하면서 머신 특정 경로 및 API 키와 같은 민감한 값에 대한 유연성을 유지할 수 있습니다.

356 404 


386 434 

387필수 환경 변수가 설정되지 않았고 기본값이 없으면 Claude Code는 구성을 구문 분석하지 못합니다.435필수 환경 변수가 설정되지 않았고 기본값이 없으면 Claude Code는 구성을 구문 분석하지 못합니다.

388 436 

389## 실제 437<h2 id="practical-examples">

438 실제 예

439</h2>

390 440 

391{/* ### 예: Playwright로 브라우저 테스트 자동화441<h3 id="example-monitor-errors-with-sentry">

392 442 예: Sentry로 오류 모니터링

393```bash443</h3>

394claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest

395```

396 

397그런 다음 브라우저 테스트를 작성하고 실행합니다:

398 

399```text

400test@example.com으로 로그인 흐름이 작동하는지 테스트

401```

402```text

403모바일에서 체크아웃 페이지의 스크린샷 촬영

404```

405```text

406검색 기능이 결과를 반환하는지 확인

407``` */}

408 

409### 예: Sentry로 오류 모니터링

410 444 

411```bash theme={null}445```bash theme={null}

412claude mcp add --transport http sentry https://mcp.sentry.dev/mcp446claude mcp add --transport http sentry https://mcp.sentry.dev/mcp


432어떤 배포가 이러한 새로운 오류를 도입했습니까?466어떤 배포가 이러한 새로운 오류를 도입했습니까?

433```467```

434 468 

435### 예: 코드 검토를 위해 GitHub에 연결469<h3 id="example-connect-to-github-for-code-reviews">

470 예: 코드 검토를 위해 GitHub에 연결

471</h3>

436 472 

437GitHub의 원격 MCP 서버는 헤더로 전달된 GitHub 개인 액세스 토큰으로 인증합니다. 하나를 얻으려면 [GitHub 토큰 설정](https://github.com/settings/personal-access-tokens)을 열고, Claude가 작업하려는 리포지토리에 액세스할 수 있는 새로운 세분화된 토큰을 생성한 다음 서버를 추가하세요:473GitHub의 원격 MCP 서버는 헤더로 전달된 GitHub 개인 액세스 토큰으로 인증합니다. 하나를 얻으려면 [GitHub 토큰 설정](https://github.com/settings/personal-access-tokens)을 열고, Claude가 작업하려는 리포지토리에 액세스할 수 있는 새로운 세분화된 토큰을 생성한 다음 서버를 추가하세요:

438 474 


455나에게 할당된 모든 열린 PR을 보여주세요491나에게 할당된 모든 열린 PR을 보여주세요

456```492```

457 493 

458### 예: PostgreSQL 데이터베이스 쿼리494<h3 id="example-query-your-postgresql-database">

495 예: PostgreSQL 데이터베이스 쿼리

496</h3>

459 497 

460```bash theme={null}498```bash theme={null}

461claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \499claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \


476지난 90일 동안 구매하지 않은 고객을 찾으세요514지난 90일 동안 구매하지 않은 고객을 찾으세요

477```515```

478 516 

479## 원격 MCP 서버로 인증517<h2 id="authenticate-with-remote-mcp-servers">

518 원격 MCP 서버로 인증

519</h2>

480 520 

481많은 클라우드 기반 MCP 서버는 인증이 필요합니다. Claude Code는 보안 연결을 위해 OAuth 2.0을 지원합니다.521많은 클라우드 기반 MCP 서버는 인증이 필요합니다. Claude Code는 보안 연결을 위해 OAuth 2.0을 지원합니다.

482 522 


514 * OAuth 인증은 HTTP 서버에서 작동합니다554 * OAuth 인증은 HTTP 서버에서 작동합니다

515</Tip>555</Tip>

516 556 

517### 고정 OAuth 콜백 포트 사용557<h3 id="use-a-fixed-oauth-callback-port">

558 고정 OAuth 콜백 포트 사용

559</h3>

518 560 

519일부 MCP 서버는 미리 등록된 특정 리디렉션 URI가 필요합니다. 기본적으로 Claude Code는 OAuth 콜백을 위해 무작위로 사용 가능한 포트를 선택합니다. `--callback-port`를 사용하여 포트를 고정하여 `http://localhost:PORT/callback` 형식의 사전 등록된 리디렉션 URI와 일치하도록 합니다.561일부 MCP 서버는 미리 등록된 특정 리디렉션 URI가 필요합니다. 기본적으로 Claude Code는 OAuth 콜백을 위해 무작위로 사용 가능한 포트를 선택합니다. `--callback-port`를 사용하여 포트를 고정하여 `http://localhost:PORT/callback` 형식의 사전 등록된 리디렉션 URI와 일치하도록 합니다.

520 562 


527 my-server https://mcp.example.com/mcp569 my-server https://mcp.example.com/mcp

528```570```

529 571 

530### 사전 구성된 OAuth 자격 증명 사용572<h3 id="use-pre-configured-oauth-credentials">

573 사전 구성된 OAuth 자격 증명 사용

574</h3>

531 575 

532일부 MCP 서버는 동적 클라이언트 등록을 통한 자동 OAuth 설정을 지원하지 않습니다. "Incompatible auth server: does not support dynamic client registration"과 같은 오류가 표시되면 서버에 사전 구성된 자격 증명이 필요합니다. Claude Code는 또한 동적 클라이언트 등록 대신 클라이언트 ID 메타데이터 문서 (CIMD)를 사용하는 서버를 지원하며 자동으로 검색합니다. 자동 검색이 실패하면 먼저 서버의 개발자 포털을 통해 OAuth 앱을 등록한 다음 서버를 추가할 때 자격 증명을 제공합니다.576일부 MCP 서버는 동적 클라이언트 등록을 통한 자동 OAuth 설정을 지원하지 않습니다. "Incompatible auth server: does not support dynamic client registration"과 같은 오류가 표시되면 서버에 사전 구성된 자격 증명이 필요합니다. Claude Code는 또한 동적 클라이언트 등록 대신 클라이언트 ID 메타데이터 문서 (CIMD)를 사용하는 서버를 지원하며 자동으로 검색합니다. 자동 검색이 실패하면 먼저 서버의 개발자 포털을 통해 OAuth 앱을 등록한 다음 서버를 추가할 때 자격 증명을 제공합니다.

533 577 


598 * `claude mcp get <name>`을 사용하여 OAuth 자격 증명이 서버에 대해 구성되었는지 확인합니다642 * `claude mcp get <name>`을 사용하여 OAuth 자격 증명이 서버에 대해 구성되었는지 확인합니다

599</Tip>643</Tip>

600 644 

601### OAuth 메타데이터 검색 재정의645<h3 id="override-oauth-metadata-discovery">

646 OAuth 메타데이터 검색 재정의

647</h3>

602 648 

603특정 OAuth 인증 서버 메타데이터 URL을 가리켜 기본 검색 체인을 우회하도록 Claude Code를 설정합니다. MCP 서버의 표준 엔드포인트가 오류를 반환하거나 내부 프록시를 통해 검색을 라우팅하려는 경우에 `authServerMetadataUrl`을 설정합니다. 기본적으로 Claude Code는 먼저 `/.well-known/oauth-protected-resource`에서 RFC 9728 보호된 리소스 메타데이터를 확인한 다음 `/.well-known/oauth-authorization-server`에서 RFC 8414 인증 서버 메타데이터로 돌아갑니다.649특정 OAuth 인증 서버 메타데이터 URL을 가리켜 기본 검색 체인을 우회하도록 Claude Code를 설정합니다. MCP 서버의 표준 엔드포인트가 오류를 반환하거나 내부 프록시를 통해 검색을 라우팅하려는 경우에 `authServerMetadataUrl`을 설정합니다. 기본적으로 Claude Code는 먼저 `/.well-known/oauth-protected-resource`에서 RFC 9728 보호된 리소스 메타데이터를 확인한 다음 `/.well-known/oauth-authorization-server`에서 RFC 8414 인증 서버 메타데이터로 돌아갑니다.

604 650 


620 666 

621URL은 `https://`를 사용해야 합니다. `authServerMetadataUrl`은 Claude Code v2.1.64 이상이 필요합니다. 메타데이터 URL의 `scopes_supported`는 업스트림 서버가 광고하는 범위를 재정의합니다.667URL은 `https://`를 사용해야 합니다. `authServerMetadataUrl`은 Claude Code v2.1.64 이상이 필요합니다. 메타데이터 URL의 `scopes_supported`는 업스트림 서버가 광고하는 범위를 재정의합니다.

622 668 

623### OAuth 범위 제한669<h3 id="restrict-oauth-scopes">

670 OAuth 범위 제한

671</h3>

624 672 

625`oauth.scopes`를 설정하여 인증 흐름 중에 Claude Code가 요청하는 범위를 고정합니다. 이는 업스트림 인증 서버가 광고하는 것보다 더 많은 범위를 부여하고 싶지 않을 때 MCP 서버를 보안 팀이 승인한 부분 집합으로 제한하는 지원되는 방법입니다. 값은 RFC 6749 §3.3의 `scope` 매개변수 형식과 일치하는 단일 공백으로 구분된 문자열입니다.673`oauth.scopes`를 설정하여 인증 흐름 중에 Claude Code가 요청하는 범위를 고정합니다. 이는 업스트림 인증 서버가 광고하는 것보다 더 많은 범위를 부여하고 싶지 않을 때 MCP 서버를 보안 팀이 승인한 부분 집합으로 제한하는 지원되는 방법입니다. 값은 RFC 6749 §3.3의 `scope` 매개변수 형식과 일치하는 단일 공백으로 구분된 문자열입니다.

626 674 


644 692 

645서버가 나중에 도구 호출에 대해 403 `insufficient_scope`을 반환하면 Claude Code는 동일한 고정된 범위로 다시 인증합니다. 필요한 도구가 고정된 범위 외의 범위를 요구할 때 `oauth.scopes`를 확대합니다.693서버가 나중에 도구 호출에 대해 403 `insufficient_scope`을 반환하면 Claude Code는 동일한 고정된 범위로 다시 인증합니다. 필요한 도구가 고정된 범위 외의 범위를 요구할 때 `oauth.scopes`를 확대합니다.

646 694 

647### 사용자 정의 인증을 위한 동적 헤더 사용695<h3 id="use-dynamic-headers-for-custom-authentication">

696 사용자 정의 인증을 위한 동적 헤더 사용

697</h3>

648 698 

649MCP 서버가 OAuth (예: Kerberos, 단기 토큰 또는 내부 SSO)가 아닌 다른 인증 체계를 사용하는 경우 `headersHelper`를 사용하여 연결 시간에 요청 헤더를 생성합니다. Claude Code는 명령을 실행하고 출력을 연결 헤더에 병합합니다.699MCP 서버가 OAuth (예: Kerberos, 단기 토큰 또는 내부 SSO)가 아닌 다른 인증 체계를 사용하는 경우 `headersHelper`를 사용하여 연결 시간에 요청 헤더를 생성합니다. Claude Code는 명령을 실행하고 출력을 연결 헤더에 병합합니다.

650 700 


695 `headersHelper`는 임의의 셸 명령을 실행합니다. 프로젝트 또는 로컬 범위에서 정의될 때 작업 공간 신뢰 대화 상자를 수락한 후에만 실행됩니다.745 `headersHelper`는 임의의 셸 명령을 실행합니다. 프로젝트 또는 로컬 범위에서 정의될 때 작업 공간 신뢰 대화 상자를 수락한 후에만 실행됩니다.

696</Note>746</Note>

697 747 

698## JSON 구성에서 MCP 서버 추가748<h2 id="add-mcp-servers-from-json-configuration">

749 JSON 구성에서 MCP 서버 추가

750</h2>

699 751 

700MCP 서버에 대한 JSON 구성이 있는 경우 직접 추가할 수 있습니다:752MCP 서버에 대한 JSON 구성이 있는 경우 직접 추가할 수 있습니다:

701 753 


731 * `--scope user`를 사용하여 프로젝트 특정 구성 대신 사용자 구성에 서버를 추가할 수 있습니다783 * `--scope user`를 사용하여 프로젝트 특정 구성 대신 사용자 구성에 서버를 추가할 수 있습니다

732</Tip>784</Tip>

733 785 

734## Claude Desktop에서 MCP 서버 가져오기786<h2 id="import-mcp-servers-from-claude-desktop">

787 Claude Desktop에서 MCP 서버 가져오기

788</h2>

735 789 

736Claude Desktop에서 MCP 서버를 이미 구성한 경우 가져올 수 있습니다:790Claude Desktop에서 MCP 서버를 이미 구성한 경우 가져올 수 있습니다:

737 791 


764 * 동일한 이름의 서버가 이미 존재하면 숫자 접미사가 붙습니다 (예: `server_1`)818 * 동일한 이름의 서버가 이미 존재하면 숫자 접미사가 붙습니다 (예: `server_1`)

765</Tip>819</Tip>

766 820 

767## Claude.ai에서 MCP 서버 사용821<h2 id="use-mcp-servers-from-claude-ai">

822 Claude.ai에서 MCP 서버 사용

823</h2>

768 824 

769[Claude.ai](https://claude.ai) 계정으로 Claude Code에 로그인한 경우 Claude.ai에서 추가한 MCP 서버는 Claude Code에서 자동으로 사용 가능합니다:825[Claude.ai](https://claude.ai) 계정으로 Claude Code에 로그인한 경우 Claude.ai에서 추가한 MCP 서버는 Claude Code에서 자동으로 사용 가능합니다:

770 826 


794 850 

795Claude Code에서 추가한 서버는 동일한 URL을 가리키는 claude.ai 커넥터보다 [우선순위](#scope-hierarchy-and-precedence)를 갖습니다. 이 경우 `/mcp`는 커넥터를 숨김으로 표시하고 커넥터를 사용하려는 경우 중복을 제거하는 방법을 표시합니다.851Claude Code에서 추가한 서버는 동일한 URL을 가리키는 claude.ai 커넥터보다 [우선순위](#scope-hierarchy-and-precedence)를 갖습니다. 이 경우 `/mcp`는 커넥터를 숨김으로 표시하고 커넥터를 사용하려는 경우 중복을 제거하는 방법을 표시합니다.

796 852 

853Microsoft 365, Gmail, Google Calendar와 같은 일부 Anthropic 호스팅 커넥터는 업스트림 ID 공급자가 claude.ai에서 등록한 리디렉션 URL만 허용하기 때문에 Claude Code에서 로컬 OAuth를 지원하지 않습니다. v2.1.162부터 이러한 호스트 중 하나를 `/mcp`에서 인증하면 대신 claude.ai의 설정 → 커넥터에서 연결하도록 지시하는 메시지가 표시됩니다. 거기에서 연결되면 커넥터가 Claude Code에 자동으로 나타납니다.

854 

797Claude Code에서 claude.ai MCP 서버를 비활성화하려면 `ENABLE_CLAUDEAI_MCP_SERVERS` 환경 변수를 `false`로 설정합니다:855Claude Code에서 claude.ai MCP 서버를 비활성화하려면 `ENABLE_CLAUDEAI_MCP_SERVERS` 환경 변수를 `false`로 설정합니다:

798 856 

799```bash theme={null}857```bash theme={null}

800ENABLE_CLAUDEAI_MCP_SERVERS=false claude858ENABLE_CLAUDEAI_MCP_SERVERS=false claude

801```859```

802 860 

803## Claude Code를 MCP 서버로 사용861<h2 id="use-claude-code-as-an-mcp-server">

862 Claude Code를 MCP 서버로 사용

863</h2>

804 864 

805Claude Code 자체를 다른 애플리케이션이 연결할 수 있는 MCP 서버로 사용할 수 있습니다:865Claude Code 자체를 다른 애플리케이션이 연결할 수 있는 MCP 서버로 사용할 수 있습니다:

806 866 


854<Tip>914<Tip>

855 팁:915 팁:

856 916 

857 * 서버는 View, Edit, LS 등과 같은 Claude의 도구에 대한 액세스를 제공합니다917 * 서버는 View, Edit, LS 등과 같은 Claude의 도구에 대한 액세스를 제공합니다.

858 * Claude Desktop에서 Claude에게 디렉토리의 파일을 읽고, 편집하는 등을 요청해 보세요918 * Claude Desktop에서 Claude에게 디렉토리의 파일을 읽고, 편집하는 등을 요청해 보세요.

859 * 이 MCP 서버는 Claude Code의 도구만 MCP 클라이언트에 노출하므로 클라이언트는 개별 도구 호출에 대한 사용자 확인을 구현할 책임이 있습니다.919 * 이 MCP 서버는 Claude Code의 도구만 MCP 클라이언트에 노출하므로 클라이언트는 개별 도구 호출에 대한 사용자 확인을 구현할 책임이 있습니다.

860</Tip>920</Tip>

861 921 

862## MCP 출력 제한 및 경고922<h2 id="mcp-output-limits-and-warnings">

923 MCP 출력 제한 및 경고

924</h2>

863 925 

864MCP 도구가 큰 출력을 생성할 때 Claude Code는 토큰 사용량을 관리하여 대화 컨텍스트가 압도되지 않도록 합니다:926MCP 도구가 큰 출력을 생성할 때 Claude Code는 토큰 사용량을 관리하여 대화 컨텍스트가 압도되지 않도록 합니다:

865 927 


881* 상세한 보고서 또는 문서 생성943* 상세한 보고서 또는 문서 생성

882* 광범위한 로그 파일 또는 디버깅 정보 처리944* 광범위한 로그 파일 또는 디버깅 정보 처리

883 945 

884### 특정 도구의 제한 늘리기946<h3 id="raise-the-limit-for-a-specific-tool">

947 특정 도구의 제한 늘리기

948</h3>

885 949 

886MCP 서버를 구축하는 경우 도구의 `tools/list` 응답 항목에서 `_meta["anthropic/maxResultSizeChars"]`를 설정하여 개별 도구가 기본 디스크 유지 임계값보다 큰 결과를 반환할 수 있습니다. Claude Code는 해당 도구의 임계값을 주석 처리된 값으로 올립니다 (최대 500,000자의 하드 상한까지).950MCP 서버를 구축하는 경우 도구의 `tools/list` 응답 항목에서 `_meta["anthropic/maxResultSizeChars"]`를 설정하여 개별 도구가 기본 디스크 유지 임계값보다 큰 결과를 반환할 수 있습니다. Claude Code는 해당 도구의 임계값을 주석 처리된 값으로 올립니다 (최대 500,000자의 하드 상한까지).

887 951 


903 특정 MCP 서버에서 자주 출력 경고가 발생하면 `MAX_MCP_OUTPUT_TOKENS` 제한을 늘리는 것을 고려하세요. 또한 서버 작성자에게 `anthropic/maxResultSizeChars` 주석을 추가하거나 응답을 페이지 매김하도록 요청할 수 있습니다. 주석은 이미지 콘텐츠를 반환하는 도구에는 영향을 주지 않습니다. 이러한 경우 `MAX_MCP_OUTPUT_TOKENS`을 올리는 것이 유일한 옵션입니다.967 특정 MCP 서버에서 자주 출력 경고가 발생하면 `MAX_MCP_OUTPUT_TOKENS` 제한을 늘리는 것을 고려하세요. 또한 서버 작성자에게 `anthropic/maxResultSizeChars` 주석을 추가하거나 응답을 페이지 매김하도록 요청할 수 있습니다. 주석은 이미지 콘텐츠를 반환하는 도구에는 영향을 주지 않습니다. 이러한 경우 `MAX_MCP_OUTPUT_TOKENS`을 올리는 것이 유일한 옵션입니다.

904</Warning>968</Warning>

905 969 

906## MCP 리소스 요청에 응답970<h2 id="respond-to-mcp-elicitation-requests">

971 MCP 리소스 요청에 응답

972</h2>

907 973 

908MCP 서버는 작업 중에 구조화된 입력을 요청할 수 있습니다. 서버가 자체적으로 얻을 수 없는 정보가 필요할 때 Claude Code는 대화형 대화 상자를 표시하고 응답을 서버에 다시 전달합니다. 사용자 측에서 구성이 필요하지 않습니다: 서버가 요청할 때 리소스 요청 대화 상자가 자동으로 나타납니다.974MCP 서버는 작업 중에 구조화된 입력을 요청할 수 있습니다(elicitation). 서버가 자체적으로 얻을 수 없는 정보가 필요할 때 Claude Code는 대화형 대화 상자를 표시하고 응답을 서버에 다시 전달합니다. 사용자 측에서 구성이 필요하지 않습니다: 서버가 요청할 때 elicitation 대화 상자가 자동으로 나타납니다.

909 975 

910서버는 두 가지 방식으로 입력을 요청할 수 있습니다:976서버는 두 가지 방식으로 입력을 요청할 수 있습니다:

911 977 

912* **양식 모드**: Claude Code는 서버에서 정의한 양식 필드가 있는 대화 상자를 표시합니다 (예: 사용자 이름 및 암호 프롬프트). 필드를 입력하고 제출합니다.978* **양식 모드**: Claude Code는 서버에서 정의한 양식 필드가 있는 대화 상자를 표시합니다(예: 사용자 이름 및 암호 프롬프트). 필드를 입력하고 제출합니다.

913* **URL 모드**: Claude Code는 인증 또는 승인을 위해 브라우저 URL을 엽니다. 브라우저에서 흐름을 완료한 다음 CLI에서 확인합니다.979* **URL 모드**: Claude Code는 인증 또는 승인을 위해 브라우저 URL을 엽니다. 브라우저에서 흐름을 완료한 다음 CLI에서 확인합니다.

914 980 

915리소스 요청에 자동으로 응답하려면 [`Elicitation` ](/ko/hooks#Elicitation)을 사용하세요.981elicitation 요청에 자동으로 응답하려면 대화 상자를 표시하지 않고 [`Elicitation` hook](/ko/hooks#elicitation)을 사용하세요.

916 982 

917리소스 요청을 사용하는 MCP 서버를 구축하는 경우 [MCP 리소스 요청 사양](https://modelcontextprotocol.io/docs/learn/client-concepts#elicitation)에서 프로토콜 세부 정보 및 스키마 예를 참조하세요.983elicitation을 사용하는 MCP 서버를 구축하는 경우 [MCP elicitation 사양](https://modelcontextprotocol.io/docs/learn/client-concepts#elicitation)에서 프로토콜 세부 정보 및 스키마 예를 참조하세요.

918 984 

919## MCP 리소스 사용985<h2 id="use-mcp-resources">

986 MCP 리소스 사용

987</h2>

920 988 

921MCP 서버는 파일을 참조하는 방식과 유사하게 @ 멘션을 사용하여 참조할 수 있는 리소스를 노출할 수 있습니다.989MCP 서버는 파일을 참조하는 방식과 유사하게 @ 멘션을 사용하여 참조할 수 있는 리소스를 노출할 수 있습니다.

922 990 

923### MCP 리소스 참조991<h3 id="reference-mcp-resources">

992 MCP 리소스 참조

993</h3>

924 994 

925<Steps>995<Steps>

926 <Step title="사용 가능한 리소스 나열">996 <Step title="사용 가능한 리소스 나열">


931 `@server:protocol://resource/path` 형식을 사용하여 리소스를 참조합니다:1001 `@server:protocol://resource/path` 형식을 사용하여 리소스를 참조합니다:

932 1002 

933 ```text theme={null}1003 ```text theme={null}

934 @github:issue://123을 분석하고 수정 사항을 제안할 있나요?1004 Can you analyze @github:issue://123 and suggest a fix?

935 ```1005 ```

936 1006 

937 ```text theme={null}1007 ```text theme={null}

938 @docs:file://api/authentication의 API 문서를 검토해 주세요1008 Please review the API documentation at @docs:file://api/authentication

939 ```1009 ```

940 </Step>1010 </Step>

941 1011 


943 단일 프롬프트에서 여러 리소스를 참조할 수 있습니다:1013 단일 프롬프트에서 여러 리소스를 참조할 수 있습니다:

944 1014 

945 ```text theme={null}1015 ```text theme={null}

946 @postgres:schema://users와 @docs:file://database/user-model을 비교하세요1016 Compare @postgres:schema://users with @docs:file://database/user-model

947 ```1017 ```

948 </Step>1018 </Step>

949</Steps>1019</Steps>


957 * 리소스는 MCP 서버가 제공하는 모든 유형의 콘텐츠를 포함할 수 있습니다 (텍스트, JSON, 구조화된 데이터 등)1027 * 리소스는 MCP 서버가 제공하는 모든 유형의 콘텐츠를 포함할 수 있습니다 (텍스트, JSON, 구조화된 데이터 등)

958</Tip>1028</Tip>

959 1029 

960## MCP Tool Search로 확장1030<h2 id="scale-with-mcp-tool-search">

1031 MCP Tool Search로 확장

1032</h2>

961 1033 

962Tool Search는 MCP 컨텍스트 사용량을 낮게 유지하여 도구 정의를 Claude가 필요할 때까지 연기합니다. 세션 시작 시 도구 이름과 서버 지침만 로드되므로 더 많은 MCP 서버를 추가해도 컨텍스트 윈도우에 미치는 영향이 최소화됩니다.1034Tool Search는 MCP 컨텍스트 사용량을 낮게 유지하여 도구 정의를 Claude가 필요할 때까지 연기합니다. 세션 시작 시 도구 이름과 서버 지침만 로드되므로 더 많은 MCP 서버를 추가해도 컨텍스트 윈도우에 미치는 영향이 최소화됩니다. Claude Code는 서버당 고정된 도구 상한을 부과하지 않습니다. 실질적인 한계는 컨텍스트 윈도우 예산입니다.

963 1035 

964### 작동 방식1036<h3 id="how-it-works">

1037 작동 방식

1038</h3>

965 1039 

966Tool Search는 기본적으로 활성화됩니다. MCP 도구는 미리 로드되지 않고 연기되며, Claude는 검색 도구를 사용하여 작업에 필요할 때 관련 도구를 검색합니다. Claude가 실제로 사용하는 도구만 컨텍스트에 들어갑니다. 사용자 관점에서 MCP 도구는 이전과 정확히 동일하게 작동합니다.1040Tool Search는 기본적으로 활성화됩니다. MCP 도구는 미리 로드되지 않고 연기되며, Claude는 검색 도구를 사용하여 작업에 필요할 때 관련 도구를 검색합니다. Claude가 실제로 사용하는 도구만 컨텍스트에 들어갑니다. 사용자 관점에서 MCP 도구는 이전과 정확히 동일하게 작동합니다.

967 1041 

968임계값 기반 로딩을 선호하는 경우 `ENABLE_TOOL_SEARCH=auto`를 설정하여 컨텍스트 윈도우의 10% 이내에 맞을 때 스키마를 미리 로드하고 오버플로우만 연기합니다. 모든 옵션은 [Tool Search 구성](#configure-tool-search)을 참조하세요.1042임계값 기반 로딩을 선호하는 경우 `ENABLE_TOOL_SEARCH=auto`를 설정하여 컨텍스트 윈도우의 10% 이내에 맞을 때 스키마를 미리 로드하고 오버플로우만 연기합니다. 모든 옵션은 [Tool Search 구성](#configure-tool-search)을 참조하세요.

969 1043 

970### MCP 서버 작성자용1044<h3 id="for-mcp-server-authors">

1045 MCP 서버 작성자용

1046</h3>

971 1047 

972MCP 서버를 구축하는 경우 Tool Search가 활성화되면 서버 지침 필드가 더 유용해집니다. 서버 지침은 Claude가 [skills](/ko/skills)의 작동 방식과 유사하게 도구를 검색할 시기를 이해하는 데 도움이 됩니다.1048MCP 서버를 구축하는 경우 Tool Search가 활성화되면 서버 지침 필드가 더 유용해집니다. 서버 지침은 Claude가 [skills](/ko/skills)의 작동 방식과 유사하게 도구를 검색할 시기를 이해하는 데 도움이 됩니다.

973 1049 


979 1055 

980Claude Code는 도구 설명 및 서버 지침을 각각 2KB에서 자릅니다. 자르기를 피하려면 간결하게 유지하고 중요한 세부 정보를 시작 부분에 배치합니다.1056Claude Code는 도구 설명 및 서버 지침을 각각 2KB에서 자릅니다. 자르기를 피하려면 간결하게 유지하고 중요한 세부 정보를 시작 부분에 배치합니다.

981 1057 

982### Tool Search 구성1058<h3 id="configure-tool-search">

1059 Tool Search 구성

1060</h3>

983 1061 

984Tool Search는 기본적으로 활성화됩니다: MCP 도구는 연기되고 필요에 따라 검색됩니다. Claude Code는 Vertex AI에서 기본적으로 비활성화합니다. `ANTHROPIC_BASE_URL`이 비 자사 호스트를 가리킬 때도 비활성화됩니다(대부분의 프록시가 `tool_reference` 블록을 전달하지 않기 때문). 폴백을 재정의하려면 `ENABLE_TOOL_SEARCH`를 명시적으로 설정합니다.1062Tool Search는 기본적으로 활성화됩니다: MCP 도구는 연기되고 필요에 따라 검색됩니다. Claude Code는 Vertex AI에서 기본적으로 비활성화합니다. `ANTHROPIC_BASE_URL`이 비 자사 호스트를 가리킬 때도 비활성화됩니다(대부분의 프록시가 `tool_reference` 블록을 전달하지 않기 때문). 폴백을 재정의하려면 `ENABLE_TOOL_SEARCH`를 명시적으로 설정합니다.

985 1063 

986Tool Search는 `tool_reference` 블록을 지원하는 모델이 필요합니다: Sonnet 4 이상 또는 Opus 4 이상. Haiku 모델은 이를 지원하지 않습니다. Vertex AI에서는 Claude Sonnet 4.5 이상 및 Claude Opus 4.5 이상에서 Tool Search가 지원됩니다.1064Tool Search는 `tool_reference` 블록을 지원하는 모델이 필요합니다. Haiku 모델은 이를 지원하지 않습니다. Vertex AI에서는 Claude Sonnet 4.5 이상 및 Claude Opus 4.5 이상에서 Tool Search가 지원됩니다.

987 1065 

988`ENABLE_TOOL_SEARCH` 환경 변수로 Tool Search 동작을 제어합니다:1066`ENABLE_TOOL_SEARCH` 환경 변수로 Tool Search 동작을 제어합니다:

989 1067 


1015}1093}

1016```1094```

1017 1095 

1018### 서버를 연기에서 제외1096<h3 id="exempt-a-server-from-deferral">

1097 서버를 연기에서 제외

1098</h3>

1019 1099 

1020서버의 도구가 검색 단계 없이 항상 Claude에게 표시되어야 하는 경우 해당 서버의 구성에서 `alwaysLoad`를 `true`로 설정합니다. 그러면 `ENABLE_TOOL_SEARCH` 설정에 관계없이 해당 서버의 모든 도구가 세션 시작 시 컨텍스트에 로드됩니다. 매 턴마다 Claude가 필요로 하는 소수의 도구에 이를 사용합니다. 각 미리 로드된 도구는 대화에 사용할 수 있는 컨텍스트를 소비하기 때문입니다.1100서버의 도구가 검색 단계 없이 항상 Claude에게 표시되어야 하는 경우 해당 서버의 구성에서 `alwaysLoad`를 `true`로 설정합니다. 그러면 `ENABLE_TOOL_SEARCH` 설정에 관계없이 해당 서버의 모든 도구가 세션 시작 시 컨텍스트에 로드됩니다. 매 턴마다 Claude가 필요로 하는 소수의 도구에 이를 사용합니다. 각 미리 로드된 도구는 대화에 사용할 수 있는 컨텍스트를 소비하기 때문입니다.

1021 1101 


1037 1117 

1038`alwaysLoad: true`를 설정하면 서버가 연결될 때까지 시작이 차단되며, 표준 5초 연결 타임아웃으로 제한됩니다. 이는 MCP 시작이 기본적으로 [비차단](/ko/env-vars)이더라도 적용됩니다. 첫 번째 프롬프트가 빌드될 때 도구가 있어야 하기 때문입니다. 다른 서버는 계속해서 백그라운드에서 연결됩니다.1118`alwaysLoad: true`를 설정하면 서버가 연결될 때까지 시작이 차단되며, 표준 5초 연결 타임아웃으로 제한됩니다. 이는 MCP 시작이 기본적으로 [비차단](/ko/env-vars)이더라도 적용됩니다. 첫 번째 프롬프트가 빌드될 때 도구가 있어야 하기 때문입니다. 다른 서버는 계속해서 백그라운드에서 연결됩니다.

1039 1119 

1040## MCP 프롬프트를 명령으로 사용1120<h2 id="use-mcp-prompts-as-commands">

1121 MCP 프롬프트를 명령으로 사용

1122</h2>

1041 1123 

1042MCP 서버는 Claude Code에서 명령으로 사용 가능하게 되는 프롬프트를 노출할 수 있습니다.1124MCP 서버는 Claude Code에서 명령으로 사용 가능하게 되는 프롬프트를 노출할 수 있습니다.

1043 1125 

1044### MCP 프롬프트 실행1126<h3 id="execute-mcp-prompts">

1127 MCP 프롬프트 실행

1128</h3>

1045 1129 

1046<Steps>1130<Steps>

1047 <Step title="사용 가능한 프롬프트 검색">1131 <Step title="사용 가능한 프롬프트 검색">


1076 * 서버 및 프롬프트 이름은 정규화됩니다 (공백은 밑줄이 됨)1160 * 서버 및 프롬프트 이름은 정규화됩니다 (공백은 밑줄이 됨)

1077</Tip>1161</Tip>

1078 1162 

1079## 관리되는 MCP 구성1163<h2 id="managed-mcp-configuration">

1164 관리되는 MCP 구성

1165</h2>

1080 1166 

1081중앙 집중식 제어가 필요한 조직의 경우 MCP 서버에 사용자가 연결할 수 있는 서버를 제어하려면 [관리되는 MCP 구성](/ko/managed-mcp)을 참조하십시오. 이는 `managed-mcp.json`을 사용하여 고정된 서버 세트 배포, `allowedMcpServers` 및 `deniedMcpServers`로 서버 제한, 서버가 차단될 때 사용자가 보는 내용을 다룹니다.1167중앙 집중식 제어가 필요한 조직의 경우 MCP 서버에 사용자가 연결할 수 있는 서버를 제어하려면 [관리되는 MCP 구성](/ko/managed-mcp)을 참조하십시오. 이는 `managed-mcp.json`을 사용하여 고정된 서버 세트 배포, `allowedMcpServers` 및 `deniedMcpServers`로 서버 제한, 서버가 차단될 때 사용자가 보는 내용을 다룹니다.

mcp-quickstart.md +73 −45

Details

11이 가이드는 Claude Code CLI를 사용하여 한 개의 MCP 서버를 처음부터 끝까지 연결하는 과정을 안내합니다. 완료하면 서버가 연결되어 응답하고, 디스크에서 구성이 어디에 있는지 알 수 있으며, 가장 일반적인 연결 오류를 해결하는 방법을 알게 됩니다.11이 가이드는 Claude Code CLI를 사용하여 한 개의 MCP 서버를 처음부터 끝까지 연결하는 과정을 안내합니다. 완료하면 서버가 연결되어 응답하고, 디스크에서 구성이 어디에 있는지 알 수 있으며, 가장 일반적인 연결 오류를 해결하는 방법을 알게 됩니다.

12 12 

13<Note>13<Note>

14 데스크톱 앱, VS Code, 웹 등 다른 표면에서도 MCP 서버를 추가할 수 있습니다. [다른 표면에서 연결하기](#다른-표면에서-연결하기)를 참조하세요.14 데스크톱 앱, VS Code, 웹 등 다른 표면에서도 MCP 서버를 추가할 수 있습니다. [다른 표면에서 연결하기](#connect-from-other-surfaces)를 참조하세요.

15</Note>15</Note>

16 16 

17Claude Code에서 MCP 서버를 연결하고 구성하는 모든 방법은 [MCP 참조](/ko/mcp)를 참조하세요.17Claude Code에서 MCP 서버를 연결하고 구성하는 모든 방법은 [MCP 참조](/ko/mcp)를 참조하세요.

18 18 

19## 시작하기 전에19<h2 id="before-you-begin">

20 시작하기 전에

21</h2>

20 22 

21다음을 확인하세요:23다음을 확인하세요:

22 24 

23* [Claude Code 설치](/ko/quickstart) 및 인증 완료25* [Claude Code 설치](/ko/quickstart) 및 인증 완료

24* 프로젝트 디렉토리에서 터미널 열기. 빈 디렉토리를 포함한 모든 디렉토리가 작동합니다.26* 프로젝트 디렉토리에서 터미널 열기. 빈 디렉토리를 포함한 모든 디렉토리가 작동합니다.

25 27 

26## 서버 추가 및 확인28<h2 id="add-and-verify-a-server">

29 서버 추가 및 확인

30</h2>

27 31 

28아래 예제는 [Claude Code 문서 MCP 서버](https://code.claude.com/docs/mcp)에 연결합니다. 이는 Claude Code 문서에 대한 전체 텍스트 검색이 가능한 호스팅된 서버입니다. 인증이나 특별한 구성이 필요하지 않으므로 설정 흐름을 테스트하기 위한 첫 번째 서버로 적합합니다.32아래 예제는 [Claude Code 문서 MCP 서버](https://code.claude.com/docs/mcp)에 연결합니다. 이는 Claude Code 문서에 대한 전체 텍스트 검색이 가능한 호스팅된 서버입니다. 인증이나 특별한 구성이 필요하지 않으므로 설정 흐름을 테스트하기 위한 첫 번째 서버로 적합합니다.

29 33 

30단계는 모든 서버에 대해 동일합니다: 추가, 연결 상태 확인, 세션에서 사용, 선택적 정리 단계. 일부 서버는 [추가 MCP 서버 예제](#추가-mcp-서버-예제)에 표시된 브라우저 로그인과 같은 단계를 추가합니다. 더 많은 서버를 연결하려면 [Anthropic Directory](/ko/mcp#mcp-서버-찾기--구축)를 참조하세요.34단계는 모든 서버에 대해 동일합니다: 추가, 연결 상태 확인, 세션에서 사용, 선택적 정리 단계. 일부 서버는 [추가 MCP 서버 예제](#additional-mcp-server-examples)에 표시된 브라우저 로그인과 같은 단계를 추가합니다. 더 많은 서버를 연결하려면 [Anthropic Directory](/ko/mcp#find-and-build-mcp-servers)를 참조하세요.

31 35 

32<Steps>36<Steps>

33 <Step title="MCP 서버 추가">37 <Step title="MCP 서버 추가">


44 * `claude-code-docs`: 사용자가 만드는 이름입니다. 동일한 서버를 `docs`라고 호출해도 동일하게 작동합니다. Claude Code는 선택한 이름을 사용하여 Claude의 출력에서 서버의 도구에 레이블을 지정하고 `claude mcp remove`와 같은 명령에서 서버를 참조합니다.48 * `claude-code-docs`: 사용자가 만드는 이름입니다. 동일한 서버를 `docs`라고 호출해도 동일하게 작동합니다. Claude Code는 선택한 이름을 사용하여 Claude의 출력에서 서버의 도구에 레이블을 지정하고 `claude mcp remove`와 같은 명령에서 서버를 참조합니다.

45 * `https://code.claude.com/docs/mcp`: 서버가 호스팅되는 URL입니다.49 * `https://code.claude.com/docs/mcp`: 서버가 호스팅되는 URL입니다.

46 50 

47 명령은 `Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config`와 같은 확인을 출력합니다. `local config` 부분은 서버가 이 프로젝트에서 사용자에게 등록되었음을 의미합니다: 다른 프로젝트에서 Claude Code를 시작하면 이 서버는 활성화되지 않습니다. 모든 프로젝트에 대해 한 번 서버를 등록하려면 사용자 범위에서 추가하세요. [서버 범위 변경](#서버-범위-변경)에서 다룹니다.51 명령은 `Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config`와 같은 확인을 출력합니다. `local config` 부분은 서버가 이 프로젝트에서 사용자에게 등록되었음을 의미합니다: 다른 프로젝트에서 Claude Code를 시작하면 이 서버는 활성화되지 않습니다. 모든 프로젝트에 대해 한 번 서버를 등록하려면 사용자 범위에서 추가하세요. [서버 범위 변경](#change-server-scope)에서 다룹니다.

48 </Step>52 </Step>

49 53 

50 <Step title="연결 상태 확인">54 <Step title="연결 상태 확인">


57 서버는 상태 표시기와 함께 나타납니다:61 서버는 상태 표시기와 함께 나타납니다:

58 62 

59 | 상태 | 의미 |63 | 상태 | 의미 |

60 | :----------------------- | :---------------------------------------------------------------------------------------------------- |64 | :----------------------- | :-------------------------------------------------------------------------------------------------------------------------- |

61 | `✓ Connected` | 사용할 준비가 되었습니다. `claude-code-docs`에서 이것을 봐야 합니다 |65 | `✓ Connected` | 사용할 준비가 되었습니다. `claude-code-docs`에서 이것을 봐야 합니다 |

62 | `! Needs authentication` | 서버에 도달할 수 있지만 브라우저 로그인이 필요하거나 `--header`로 전달된 토큰이 필요합니다. [로그인이 필요한 서버 연결하기](#로그인이-필요한-서버-연결하기)를 참조하세요 |66 | `! Needs authentication` | 서버에 도달할 수 있지만 브라우저 로그인이 필요하거나 `--header`로 전달된 토큰이 필요합니다. [로그인이 필요한 서버 연결하기](#connect-a-server-that-requires-sign-in)를 참조하세요 |

63 | `✗ Failed to connect` | 서버가 응답하지 않았습니다. [문제 해결](#문제-해결)을 참조하세요 |67 | `✗ Failed to connect` | 서버가 응답하지 않았습니다. [문제 해결](#troubleshooting)을 참조하세요 |

64 | `✗ Connection error` | 연결 시도에서 오류가 발생했습니다. [문제 해결](#문제-해결)을 참조하세요 |68 | `✗ Connection error` | 연결 시도에서 오류가 발생했습니다. [문제 해결](#troubleshooting)을 참조하세요 |

65 | `⏸ Pending approval` | 아직 승인하지 않은 프로젝트 범위 서버입니다. [.mcp.json 직접 편집하기](#mcp-json-직접-편집하기)를 참조하세요 |69 | `⏸ Pending approval` | 아직 승인하지 않은 프로젝트 범위 서버입니다. [.mcp.json 직접 편집하기](#edit-mcp-json-directly)를 참조하세요 |

66 </Step>70 </Step>

67 71 

68 <Step title="서버 사용">72 <Step title="서버 사용">


91 ```95 ```

92 96 

93 <Note>97 <Note>

94 연결된 각 서버는 도구 이름과 서버 지침이 모든 세션에 로드되기 때문에 [Claude의 컨텍스트 윈도우](/ko/how-claude-code-works#컨텍스트-윈도우)에서 일부 공간을 차지합니다. 더 이상 사용하지 않는 서버를 제거하면 해당 공간을 확보할 수 있습니다.98 연결된 각 서버는 도구 이름과 서버 지침이 모든 세션에 로드되기 때문에 [Claude의 컨텍스트 윈도우](/ko/how-claude-code-works#the-context-window)에서 일부 공간을 차지합니다. 더 이상 사용하지 않는 서버를 제거하면 해당 공간을 확보할 수 있습니다.

95 </Note>99 </Note>

96 </Step>100 </Step>

97</Steps>101</Steps>

98 102 

99## 서버가 저장되는 위치103<h2 id="where-servers-are-saved">

104 서버가 저장되는 위치

105</h2>

100 106 

101`claude mcp add` 명령은 서버의 세부 정보를 구성 파일에 씁니다. 기본적으로 `local` 범위에서 서버를 등록합니다: 사용자에게만 비공개이며 현재 프로젝트에서만 활성화됩니다. `--scope user`를 전달하여 모든 프로젝트에 대해 한 번 등록하거나 `--scope project`를 전달하여 팀원과 공유합니다. [서버 범위 변경](#서버-범위-변경)에서 둘 다 설명합니다.107`claude mcp add` 명령은 서버의 세부 정보를 구성 파일에 씁니다. 기본적으로 `local` 범위에서 서버를 등록합니다: 사용자에게만 비공개이며 현재 프로젝트에서만 활성화됩니다. `--scope user`를 전달하여 모든 프로젝트에 대해 한 번 등록하거나 `--scope project`를 전달하여 팀원과 공유합니다. [서버 범위 변경](#change-server-scope)에서 둘 다 설명합니다.

102 108 

103<Note>109<Note>

104 `claude mcp add`는 PowerShell 및 Command Prompt를 포함한 모든 셸에서 동일하게 작동합니다. `claude` 세션 내부에서 `/mcp` 명령을 사용하여 이미 추가한 서버를 확인하고 관리합니다.110 `claude mcp add`는 PowerShell 및 Command Prompt를 포함한 모든 셸에서 동일하게 작동합니다. `claude` 세션 내부에서 `/mcp` 명령을 사용하여 이미 추가한 서버를 확인하고 관리합니다.


106 112 

107서버를 추가하는 다른 방법이 있으며, 각각은 이 페이지의 뒷부분에서 다룹니다:113서버를 추가하는 다른 방법이 있으며, 각각은 이 페이지의 뒷부분에서 다룹니다:

108 114 

109* [로컬 서버 추가](#로컬-서버-추가): URL에 연결하는 대신 머신에서 프로그램을 실행합니다.115* [로컬 서버 추가](#add-a-local-server): URL에 연결하는 대신 머신에서 프로그램을 실행합니다.

110* [`.mcp.json` 직접 편집하기](#mcp-json-직접-편집하기): 명령을 사용하는 대신 JSON 항목을 직접 작성합니다.116* [`.mcp.json` 직접 편집하기](#edit-mcp-json-directly): 명령을 사용하는 대신 JSON 항목을 직접 작성합니다.

111* [로그인이 필요한 서버 연결하기](#로그인이-필요한-서버-연결하기): 도구가 작동하기 전에 브라우저 로그인이 필요한 호스팅된 서버를 추가합니다.117* [로그인이 필요한 서버 연결하기](#connect-a-server-that-requires-sign-in): 도구가 작동하기 전에 브라우저 로그인이 필요한 호스팅된 서버를 추가합니다.

112 118 

113### 디스크에서 구성 찾기119<h3 id="find-your-configuration-on-disk">

120 디스크에서 구성 찾기

121</h3>

114 122 

115[범위 테이블](#디스크에서-구성-찾기)의 모든 파일은 `--scope` 플래그에 따라 두 파일에 저장된 서버 항목에 대해 동일한 JSON 형식을 사용합니다. 이러한 파일을 직접 편집할 필요는 없지만 위치를 알면 디버깅 및 버전 제어에 도움이 됩니다.123`claude mcp add` 명령은 `--scope` 플래그에 따라 두 파일에 걸쳐 저장된 가지 범위 하나에 서버를 씁니다. 이러한 파일을 직접 편집할 필요는 없지만 위치를 알면 디버깅 및 버전 제어에 도움이 됩니다.

116 124 

117| 범위 | 파일 | 사용 가능 대상 |125| 범위 | 파일 | 사용 가능 대상 |

118| :-------- | :-------------------------------------- | :----------------- |126| :-------- | :-------------------------------------- | :----------------- |


122 130 

123Windows에서 `~/.claude.json`은 `%USERPROFILE%\.claude.json`으로 확인되며, 일반적으로 `C:\Users\YourName\.claude.json`입니다. [`CLAUDE_CONFIG_DIR`](/ko/env-vars)을 설정한 경우 Claude Code는 대신 해당 디렉토리 내에서 `.claude.json`을 읽습니다.131Windows에서 `~/.claude.json`은 `%USERPROFILE%\.claude.json`으로 확인되며, 일반적으로 `C:\Users\YourName\.claude.json`입니다. [`CLAUDE_CONFIG_DIR`](/ko/env-vars)을 설정한 경우 Claude Code는 대신 해당 디렉토리 내에서 `.claude.json`을 읽습니다.

124 132 

125`claude mcp get claude-code-docs`를 실행하여 어느 범위가 서버의 정의를 보유하는지 확인합니다. 동일한 서버가 둘 이상의 범위에서 정의될 때 범위가 상호 작용하는 방식은 [MCP 설치 범위](/ko/mcp#mcp-설치-범위)를 참조하세요.133`claude mcp get claude-code-docs`를 실행하여 어느 범위가 서버의 정의를 보유하는지 확인합니다. 동일한 서버가 둘 이상의 범위에서 정의될 때 범위가 상호 작용하는 방식은 [MCP 설치 범위](/ko/mcp#mcp-installation-scopes)를 참조하세요.

126 134 

127## 서버 범위 변경135<h2 id="change-server-scope">

136 서버 범위 변경

137</h2>

128 138 

129서버의 범위는 추가할 때 고정되므로 범위를 변경하려면 항목을 제거하고 새 범위에서 다시 추가해야 합니다. 아래의 두 경우 모두 첫 번째 연습에서 로컬 항목을 제거하여 시작하므로 서버는 정의가 하나만 있습니다. 해당 연습의 끝에서 이미 제거한 경우 이 명령을 건너뜁니다:139서버의 범위는 추가할 때 고정되므로 범위를 변경하려면 항목을 제거하고 새 범위에서 다시 추가해야 합니다. 아래의 두 경우 모두 첫 번째 연습에서 로컬 항목을 제거하여 시작하므로 서버는 정의가 하나만 있습니다. 해당 연습의 끝에서 이미 제거한 경우 이 명령을 건너뜁니다:

130 140 


132claude mcp remove claude-code-docs --scope local142claude mcp remove claude-code-docs --scope local

133```143```

134 144 

135### 모든 프로젝트에서 서버 사용145<h3 id="use-a-server-in-all-your-projects">

146 모든 프로젝트에서 서버 사용

147</h3>

136 148 

137`user` 범위에서 서버를 다시 추가하여 열 수 있는 모든 프로젝트에서 활성화하되, 여전히 사용자에게만 비공개입니다:149`user` 범위에서 서버를 다시 추가하여 열 수 있는 모든 프로젝트에서 활성화하되, 여전히 사용자에게만 비공개입니다:

138 150 


140claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp152claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

141```153```

142 154 

143### 팀과 서버 공유155<h3 id="share-a-server-with-your-team">

156 팀과 서버 공유

157</h3>

144 158 

145`project` 범위에서 서버를 다시 추가하여 프로젝트 루트의 `.mcp.json`에 씁니다:159`project` 범위에서 서버를 다시 추가하여 프로젝트 루트의 `.mcp.json`에 씁니다:

146 160 


150 164 

151`.mcp.json`을 버전 제어에 커밋합니다. 저장소를 복제하고 Claude Code를 시작하는 팀원은 서버를 승인하라는 프롬프트를 보고 그들도 연결됩니다.165`.mcp.json`을 버전 제어에 커밋합니다. 저장소를 복제하고 Claude Code를 시작하는 팀원은 서버를 승인하라는 프롬프트를 보고 그들도 연결됩니다.

152 166 

153## 추가 MCP 서버 예제167<h2 id="additional-mcp-server-examples">

168 추가 MCP 서버 예제

169</h2>

154 170 

155첫 번째 연습에서는 로그인 없이 연결되는 호스팅된 서버를 사용했습니다. 아래 예제는 동일한 추가, 확인, 사용 흐름을 포함하는 다른 두 가지 일반적인 형태를 다룹니다.171첫 번째 연습에서는 로그인 없이 연결되는 호스팅된 서버를 사용했습니다. 아래 예제는 동일한 추가, 확인, 사용 흐름을 포함하는 다른 두 가지 일반적인 형태를 다룹니다.

156 172 

157### 로컬 서버 추가173<h3 id="add-a-local-server">

174 로컬 서버 추가

175</h3>

158 176 

159로컬 stdio 서버는 Claude Code가 URL을 통해 도달하는 서비스가 아닌 머신에서 서브프로세스로 시작하는 프로그램입니다. 브라우저, 파일 시스템 또는 데이터베이스 소켓과 같은 로컬 리소스에 액세스해야 하는 도구에 사용합니다.177로컬 stdio 서버는 Claude Code가 URL을 통해 도달하는 서비스가 아닌 머신에서 서브프로세스로 시작하는 프로그램입니다. 브라우저, 파일 시스템 또는 데이터베이스 소켓과 같은 로컬 리소스에 액세스해야 하는 도구에 사용합니다.

160 178 


200 </Step>218 </Step>

201</Steps>219</Steps>

202 220 

203### 로그인이 필요한 서버 연결하기221<h3 id="connect-a-server-that-requires-sign-in">

222 로그인이 필요한 서버 연결하기

223</h3>

204 224 

205Sentry, Linear, Notion과 같은 호스팅된 서비스는 OAuth 뒤에서 MCP 서버를 실행합니다: 서버의 URL을 추가한 다음 브라우저를 통해 로그인합니다.225Sentry, Linear, Notion과 같은 호스팅된 서비스는 OAuth 뒤에서 MCP 서버를 실행합니다: 서버의 URL을 추가한 다음 브라우저를 통해 로그인합니다.

206 226 

207아래 단계는 Sentry를 예제로 사용합니다. 다른 서비스에 연결하려면 [Anthropic Directory](/ko/mcp#mcp-서버-찾기--구축) 또는 서비스의 문서에서 찾을 수 있는 URL을 대체합니다.227아래 단계는 Sentry를 예제로 사용합니다. 다른 서비스에 연결하려면 [Anthropic Directory](/ko/mcp#find-and-build-mcp-servers) 또는 서비스의 문서에서 찾을 수 있는 URL을 대체합니다.

208 228 

209<Steps>229<Steps>

210 <Step title="서버 추가">230 <Step title="서버 추가">


226 246 

227 목록에서 `sentry`를 선택하고 Enter를 누른 다음 `Authenticate`를 선택합니다. 브라우저가 Sentry의 로그인 페이지로 열립니다. 거기서 연결을 승인합니다.247 목록에서 `sentry`를 선택하고 Enter를 누른 다음 `Authenticate`를 선택합니다. 브라우저가 Sentry의 로그인 페이지로 열립니다. 거기서 연결을 승인합니다.

228 248 

229 Claude Code로 돌아가면 서버의 상태가 연결됨으로 변경됩니다. 로그인이 실패하거나 브라우저가 열리지 않으면 [문제 해결](#문제-해결)을 참조하세요.249 Claude Code로 돌아가면 서버의 상태가 연결됨으로 변경됩니다. 로그인이 실패하거나 브라우저가 열리지 않으면 [문제 해결](#troubleshooting)을 참조하세요.

230 </Step>250 </Step>

231 251 

232 <Step title="서버 사용">252 <Step title="서버 사용">


234 </Step>254 </Step>

235</Steps>255</Steps>

236 256 

237OAuth 대신 정적 토큰으로 인증하는 서버는 `--header "Authorization: Bearer <token>"`을 사용하여 추가 시간에 토큰을 가져옵니다. 작동하는 버전은 [GitHub 예제](/ko/mcp#예제-코드-검토를-위해-github에-연결하기)를 참조하세요.257OAuth 대신 정적 토큰으로 인증하는 서버는 `--header "Authorization: Bearer <token>"`을 사용하여 추가 시간에 토큰을 가져옵니다. 작동하는 버전은 [GitHub 예제](/ko/mcp#example-connect-to-github-for-code-reviews)를 참조하세요.

238 258 

239## .mcp.json 직접 편집하기259<h2 id="edit-mcp-json-directly">

260 .mcp.json 직접 편집하기

261</h2>

240 262 

241[범위 테이블](#디스크에서-구성-찾기)의 모든 파일은 서버 항목에 대해 동일한 JSON 형식을 사용합니다. 이 섹션은 프로젝트 범위 파일인 `.mcp.json`을 편집합니다. 저장소에 체크인되므로 팀을 위한 구성 코드로도 작동하기 때문에 손으로 작성할 가치가 있습니다.263[범위 테이블](#find-your-configuration-on-disk)의 모든 파일은 서버 항목에 대해 동일한 JSON 형식을 사용합니다. 이 섹션은 프로젝트 범위 파일인 `.mcp.json`을 편집합니다. 저장소에 체크인되므로 팀을 위한 구성 코드로도 작동하기 때문에 손으로 작성할 가치가 있습니다.

242 264 

243프로젝트 루트에 `.mcp.json`을 만듭니다. 아래 예제는 이 가이드의 두 서버, HTTP를 통해 도달하는 호스팅된 문서 서버 및 로컬 `stdio` 프로세스로서의 Playwright 서버를 정의합니다:265프로젝트 루트에 `.mcp.json`을 만듭니다. 아래 예제는 이 가이드의 두 서버, HTTP를 통해 도달하는 호스팅된 문서 서버 및 로컬 `stdio` 프로세스로서의 Playwright 서버를 정의합니다:

244 266 


267 289 

268Claude Code가 처음으로 프로젝트 범위 서버를 보면 승인하도록 요청합니다. 프롬프트는 복제한 저장소가 동의 없이 머신에서 프로세스를 시작할 수 없도록 존재합니다. 프롬프트를 승인하거나 놓친 경우 나중에 승인하려면 `/mcp`를 실행합니다.290Claude Code가 처음으로 프로젝트 범위 서버를 보면 승인하도록 요청합니다. 프롬프트는 복제한 저장소가 동의 없이 머신에서 프로세스를 시작할 수 없도록 존재합니다. 프롬프트를 승인하거나 놓친 경우 나중에 승인하려면 `/mcp`를 실행합니다.

269 291 

270승인한 후 `/mcp`를 실행하고 서버가 연결됨으로 표시되는지 확인합니다. 대신 오류를 표시하면 [문제 해결](#문제-해결)을 참조하세요.292승인한 후 `/mcp`를 실행하고 서버가 연결됨으로 표시되는지 확인합니다. 대신 오류를 표시하면 [문제 해결](#troubleshooting)을 참조하세요.

271 293 

272## 다른 표면에서 연결하기294<h2 id="connect-from-other-surfaces">

295 다른 표면에서 연결하기

296</h2>

273 297 

274이 가이드는 `claude mcp` CLI 명령을 사용하지만 모든 Claude Code 표면은 MCP 서버에 연결할 수 있습니다:298이 가이드는 `claude mcp` CLI 명령을 사용하지만 모든 Claude Code 표면은 MCP 서버에 연결할 수 있습니다:

275 299 

276* **Claude Code 데스크톱 앱**: [Connectors UI](/ko/desktop#외부-도구-연결)를 통해 서버를 추가합니다.300* **Claude Code 데스크톱 앱**: [Connectors UI](/ko/desktop#connect-external-tools)를 통해 서버를 추가합니다.

277* **Claude Desktop 채팅 앱**: Claude Code와 별개의 앱입니다. `claude_desktop_config.json`에서 CLI로 서버를 복사하려면 macOS 또는 WSL에서 `claude mcp add-from-claude-desktop`을 실행합니다.301* **Claude Desktop 채팅 앱**: Claude Code와 별개의 앱입니다. `claude_desktop_config.json`에서 CLI로 서버를 복사하려면 macOS 또는 WSL에서 `claude mcp add-from-claude-desktop`을 실행합니다.

278* **VS Code**: [MCP를 사용하여 외부 도구에 연결하기](/ko/vs-code#mcp를-사용하여-외부-도구에-연결하기)를 참조하세요.302* **VS Code**: [MCP를 사용하여 외부 도구에 연결하기](/ko/vs-code#connect-to-external-tools-with-mcp)를 참조하세요.

279* **웹의 Claude Code**: 저장소에서 `.mcp.json`을 읽습니다. [.mcp.json 직접 편집하기](#mcp-json-직접-편집하기)를 참조하세요.303* **웹의 Claude Code**: 저장소에서 `.mcp.json`을 읽습니다. [.mcp.json 직접 편집하기](#edit-mcp-json-directly)를 참조하세요.

280* **Claude.ai**: [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 추가한 커넥터는 해당 계정으로 로그인할 때 CLI에 자동으로 로드됩니다. [Claude.ai에서 MCP 서버 사용하기](/ko/mcp#claude-ai에서-mcp-서버-사용하기)를 참조하세요.304* **Claude.ai**: [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 추가한 커넥터는 해당 계정으로 로그인할 때 CLI에 자동으로 로드됩니다. [Claude.ai에서 MCP 서버 사용하기](/ko/mcp#use-mcp-servers-from-claude-ai)를 참조하세요.

281 305 

282## 문제 해결306<h2 id="troubleshooting">

307 문제 해결

308</h2>

283 309 

284서버가 연결되지 않으면 세션 내부에서 `/mcp`를 사용하거나 셸에서 `claude mcp list`를 사용하여 상태를 확인한 다음 아래 증상과 일치시킵니다. `/mcp` 패널을 사용하면 세션을 떠나지 않고도 다시 연결하거나 인증할 수 있습니다.310서버가 연결되지 않으면 세션 내부에서 `/mcp`를 사용하거나 셸에서 `claude mcp list`를 사용하여 상태를 확인한 다음 아래 증상과 일치시킵니다. `/mcp` 패널을 사용하면 세션을 떠나지 않고도 다시 연결하거나 인증할 수 있습니다.

285 311 


292 </Accordion>318 </Accordion>

293 319 

294 <Accordion title="Status shows Failed to connect or Connection error">320 <Accordion title="Status shows Failed to connect or Connection error">

295 두 상태 모두 서버가 시작되지 않았거나 URL이 응답하지 않았음을 의미합니다. [로그인이 필요한 서버 연결하기](#로그인이-필요한-서버-연결하기)에서 다룬 브라우저 로그인이 아닌 토큰을 예상하는 HTTP 서버에도 나타날 수 있습니다.321 두 상태 모두 서버가 시작되지 않았거나 URL이 응답하지 않았음을 의미합니다. [로그인이 필요한 서버 연결하기](#connect-a-server-that-requires-sign-in)에서 다룬 브라우저 로그인이 아닌 토큰을 예상하는 HTTP 서버에도 나타날 수 있습니다.

296 322 

297 HTTP 서버의 경우 URL이 머신에서 도달 가능한지 확인합니다:323 HTTP 서버의 경우 URL이 머신에서 도달 가능한지 확인합니다:

298 324 


305 응답은 어떤 종류의 문제가 있는지 알려줍니다:331 응답은 어떤 종류의 문제가 있는지 알려줍니다:

306 332 

307 * `404` 또는 `405`: 서버가 실행 중입니다. 많은 MCP 엔드포인트는 POST 요청에만 응답하므로 이는 여전히 URL이 머신에서 도달 가능함을 확인합니다.333 * `404` 또는 `405`: 서버가 실행 중입니다. 많은 MCP 엔드포인트는 POST 요청에만 응답하므로 이는 여전히 URL이 머신에서 도달 가능함을 확인합니다.

308 * `401` 또는 `403`: 서버가 실행 중이고 인증이 필요합니다. [로그인이 필요한 서버 연결하기](#로그인이-필요한-서버-연결하기)에서 브라우저 로그인을 사용하거나 GitHub와 같이 토큰을 가져오는 서버의 경우 `claude mcp add` 명령에서 `--header "Authorization: Bearer <token>"`으로 전달합니다.334 * `401` 또는 `403`: 서버가 실행 중이고 인증이 필요합니다. [로그인이 필요한 서버 연결하기](#connect-a-server-that-requires-sign-in)에서 브라우저 로그인을 사용하거나 GitHub와 같이 토큰을 가져오는 서버의 경우 `claude mcp add` 명령에서 `--header "Authorization: Bearer <token>"`으로 전달합니다.

309 * 응답 없음: URL과 네트워크를 확인합니다.335 * 응답 없음: URL과 네트워크를 확인합니다.

310 336 

311 stdio 서버의 경우 터미널에서 구성된 명령을 직접 실행하여 기본 오류를 확인합니다. 이 가이드의 Playwright 서버의 경우 다음을 실행합니다:337 stdio 서버의 경우 터미널에서 구성된 명령을 직접 실행하여 기본 오류를 확인합니다. 이 가이드의 Playwright 서버의 경우 다음을 실행합니다:


363 </Accordion>389 </Accordion>

364 390 

365 <Accordion title="OAuth sign-in fails or browser doesn't open">391 <Accordion title="OAuth sign-in fails or browser doesn't open">

366 `/mcp`를 실행하고 서버를 선택한 다음 `Authenticate`를 다시 선택합니다. 브라우저가 자동으로 열리지 않으면 터미널에 표시된 URL을 복사하여 수동으로 엽니다. 고정 콜백 포트 및 사전 구성된 자격 증명은 [원격 MCP 서버로 인증하기](/ko/mcp#원격-mcp-서버로-인증하기)를 참조하세요.392 `/mcp`를 실행하고 서버를 선택한 다음 `Authenticate`를 다시 선택합니다. 브라우저가 자동으로 열리지 않으면 터미널에 표시된 URL을 복사하여 수동으로 엽니다. 고정 콜백 포트 및 사전 구성된 자격 증명은 [원격 MCP 서버로 인증하기](/ko/mcp#authenticate-with-remote-mcp-servers)를 참조하세요.

367 </Accordion>393 </Accordion>

368</AccordionGroup>394</AccordionGroup>

369 395 

370## 다음 단계396<h2 id="next-steps">

397 다음 단계

398</h2>

371 399 

372한 개의 서버가 연결되면 MCP가 활성화하는 나머지를 탐색합니다:400한 개의 서버가 연결되면 MCP가 활성화하는 나머지를 탐색합니다:

373 401 

374* [더 많은 MCP 서버 찾기](/ko/mcp#mcp-서버-찾기--구축) Anthropic Directory에서402* [더 많은 MCP 서버 찾기](/ko/mcp#find-and-build-mcp-servers) Anthropic Directory에서

375* [설치 범위를 사용하여 팀과 서버 공유하기](/ko/mcp#mcp-설치-범위)403* [설치 범위를 사용하여 팀과 서버 공유하기](/ko/mcp#mcp-installation-scopes)

376* [관리되는 설정 및 정책 제어로 조직을 위한 MCP 액세스 관리하기](/ko/managed-mcp)404* [관리되는 설정 및 정책 제어로 조직을 위한 MCP 액세스 관리하기](/ko/managed-mcp)

377* [프롬프트에서 @ 언급으로 MCP 리소스 참조하기](/ko/mcp#mcp-리소스-사용)405* [프롬프트에서 @ 언급으로 MCP 리소스 참조하기](/ko/mcp#use-mcp-resources)

378* [`/` 메뉴에서 MCP 프롬프트를 명령으로 실행하기](/ko/mcp#mcp-프롬프트를-명령으로-사용)406* [`/` 메뉴에서 MCP 프롬프트를 명령으로 실행하기](/ko/mcp#use-mcp-prompts-as-commands)

379* [MCP SDK를 사용하여 자신의 서버 구축하기](https://modelcontextprotocol.io/quickstart/server)407* [MCP SDK를 사용하여 자신의 서버 구축하기](https://modelcontextprotocol.io/quickstart/server)

memory.md +93 −33

Details

14이 페이지에서는 다음을 다룹니다:14이 페이지에서는 다음을 다룹니다:

15 15 

16* [CLAUDE.md 파일 작성 및 구성](#claude-md-files)16* [CLAUDE.md 파일 작성 및 구성](#claude-md-files)

17* [`.claude/rules/`를 사용하여 특정 파일 유형에 규칙 범위 지정](#organize-rules-with-clauderules)17* [`.claude/rules/`를 사용하여 특정 파일 유형에 규칙 범위 지정](#organize-rules-with-claude/rules/)

18* [자동 메모리 구성](#auto-memory)하여 Claude가 자동으로 노트를 작성하도록 함18* [자동 메모리 구성](#auto-memory)하여 Claude가 자동으로 노트를 작성하도록 함

19* [지침이 따라지지 않을 때 문제 해결](#troubleshoot-memory-issues)19* [지침이 따라지지 않을 때 문제 해결](#troubleshoot-memory-issues)

20 20 

21## CLAUDE.md vs 자동 메모리21<h2 id="claude-md-vs-auto-memory">

22 CLAUDE.md vs 자동 메모리

23</h2>

22 24 

23Claude Code에는 두 가지 상호 보완적인 메모리 시스템이 있습니다. 둘 다 모든 대화의 시작 시 로드됩니다. Claude는 이들을 강제된 구성이 아닌 컨텍스트로 취급합니다. 작업을 차단하려면 어떤 Claude의 결정과 관계없이 [PreToolUse 훅](/ko/hooks-guide)을 사용합니다. 지침이 더 구체적이고 간결할수록 Claude가 더 일관되게 따릅니다.25Claude Code에는 두 가지 상호 보완적인 메모리 시스템이 있습니다. 둘 다 모든 대화의 시작 시 로드됩니다. Claude는 이들을 강제된 구성이 아닌 컨텍스트로 취급합니다. 작업을 차단하려면 어떤 Claude의 결정과 관계없이 [PreToolUse 훅](/ko/hooks-guide)을 사용합니다. 지침이 더 구체적이고 간결할수록 Claude가 더 일관되게 따릅니다.

24 26 


34 36 

35Subagent도 자신의 자동 메모리를 유지할 수 있습니다. 자세한 내용은 [subagent 구성](/ko/sub-agents#enable-persistent-memory)을 참조하세요.37Subagent도 자신의 자동 메모리를 유지할 수 있습니다. 자세한 내용은 [subagent 구성](/ko/sub-agents#enable-persistent-memory)을 참조하세요.

36 38 

37## CLAUDE.md 파일39<h2 id="claude-md-files">

40 CLAUDE.md 파일

41</h2>

38 42 

39CLAUDE.md 파일은 프로젝트, 개인 워크플로우 또는 전체 조직에 대해 Claude에 지속적인 지침을 제공하는 마크다운 파일입니다. 이러한 파일을 일반 텍스트로 작성하면 Claude가 모든 세션의 시작 시 읽습니다.43CLAUDE.md 파일은 프로젝트, 개인 워크플로우 또는 전체 조직에 대해 Claude에 지속적인 지침을 제공하는 마크다운 파일입니다. 이러한 파일을 일반 텍스트로 작성하면 Claude가 모든 세션의 시작 시 읽습니다.

40 44 

41### CLAUDE.md에 추가할 시기45<h3 id="when-to-add-to-claude-md">

46 CLAUDE.md에 추가할 시기

47</h3>

42 48 

43CLAUDE.md를 다시 설명해야 할 내용을 적어두는 장소로 취급합니다. 다음과 같은 경우에 추가합니다:49CLAUDE.md를 다시 설명해야 할 내용을 적어두는 장소로 취급합니다. 다음과 같은 경우에 추가합니다:

44 50 


49 55 

50모든 세션에서 Claude가 보유해야 할 사실로 유지합니다: 빌드 명령, 규칙, 프로젝트 레이아웃, "항상 X를 수행합니다" 규칙. 항목이 다단계 절차이거나 코드베이스의 한 부분에만 중요한 경우 대신 [skill](/ko/skills) 또는 [경로 범위 규칙](#organize-rules-with-claude/rules/)으로 이동합니다. [확장 개요](/ko/features-overview#build-your-setup-over-time)에서 각 메커니즘을 사용할 시기를 다룹니다.56모든 세션에서 Claude가 보유해야 할 사실로 유지합니다: 빌드 명령, 규칙, 프로젝트 레이아웃, "항상 X를 수행합니다" 규칙. 항목이 다단계 절차이거나 코드베이스의 한 부분에만 중요한 경우 대신 [skill](/ko/skills) 또는 [경로 범위 규칙](#organize-rules-with-claude/rules/)으로 이동합니다. [확장 개요](/ko/features-overview#build-your-setup-over-time)에서 각 메커니즘을 사용할 시기를 다룹니다.

51 57 

52### CLAUDE.md 파일을 어디에 배치할지 선택58<h3 id="choose-where-to-put-claude-md-files">

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

60</h3>

53 61 

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

55 63 


64 72 

65대규모 프로젝트의 경우 [프로젝트 규칙](#organize-rules-with-claude/rules/)을 사용하여 지침을 주제별 파일로 나눌 수 있습니다. 규칙을 통해 특정 파일 유형 또는 하위 디렉토리에 지침의 범위를 지정할 수 있습니다.73대규모 프로젝트의 경우 [프로젝트 규칙](#organize-rules-with-claude/rules/)을 사용하여 지침을 주제별 파일로 나눌 수 있습니다. 규칙을 통해 특정 파일 유형 또는 하위 디렉토리에 지침의 범위를 지정할 수 있습니다.

66 74 

67### 프로젝트 CLAUDE.md 설정75<h3 id="set-up-a-project-claude-md">

76 프로젝트 CLAUDE.md 설정

77</h3>

68 78 

69프로젝트 CLAUDE.md는 `./CLAUDE.md` 또는 `./.claude/CLAUDE.md`에 저장할 수 있습니다. 이 파일을 만들고 프로젝트에서 작업하는 모든 사람에게 적용되는 지침을 추가합니다: 빌드 및 테스트 명령, 코딩 표준, 아키텍처 결정, 명명 규칙 및 일반적인 워크플로우. 이러한 지침은 버전 제어를 통해 팀과 공유되므로 개인 선호도보다는 프로젝트 수준의 표준에 중점을 두세요.79프로젝트 CLAUDE.md는 `./CLAUDE.md` 또는 `./.claude/CLAUDE.md`에 저장할 수 있습니다. 이 파일을 만들고 프로젝트에서 작업하는 모든 사람에게 적용되는 지침을 추가합니다: 빌드 및 테스트 명령, 코딩 표준, 아키텍처 결정, 명명 규칙 및 일반적인 워크플로우. 이러한 지침은 버전 제어를 통해 팀과 공유되므로 개인 선호도보다는 프로젝트 수준의 표준에 중점을 두세요.

70 80 


74 `CLAUDE_CODE_NEW_INIT=1`을 설정하여 대화형 다단계 흐름을 활성화합니다. `/init`은 설정할 아티팩트를 묻습니다: CLAUDE.md 파일, skills 및 hooks. 그런 다음 subagent로 코드베이스를 탐색하고 후속 질문을 통해 간격을 채우며 파일을 작성하기 전에 검토 가능한 제안을 제시합니다.84 `CLAUDE_CODE_NEW_INIT=1`을 설정하여 대화형 다단계 흐름을 활성화합니다. `/init`은 설정할 아티팩트를 묻습니다: CLAUDE.md 파일, skills 및 hooks. 그런 다음 subagent로 코드베이스를 탐색하고 후속 질문을 통해 간격을 채우며 파일을 작성하기 전에 검토 가능한 제안을 제시합니다.

75</Tip>85</Tip>

76 86 

77### 효과적인 지침 작성87<h3 id="write-effective-instructions">

88 효과적인 지침 작성

89</h3>

78 90 

79CLAUDE.md 파일은 모든 세션의 시작 시 컨텍스트 윈도우에 로드되어 대화와 함께 토큰을 소비합니다. [컨텍스트 윈도우 시각화](/ko/context-window)는 CLAUDE.md가 나머지 시작 컨텍스트를 기준으로 어디에 로드되는지 보여줍니다. 강제된 구성이 아닌 컨텍스트이기 때문에 지침을 작성하는 방식이 Claude가 얼마나 안정적으로 따르는지에 영향을 미칩니다. 구체적이고 간결하며 잘 구조화된 지침이 가장 잘 작동합니다.91CLAUDE.md 파일은 모든 세션의 시작 시 컨텍스트 윈도우에 로드되어 대화와 함께 토큰을 소비합니다. [컨텍스트 윈도우 시각화](/ko/context-window)는 CLAUDE.md가 나머지 시작 컨텍스트를 기준으로 어디에 로드되는지 보여줍니다. 강제된 구성이 아닌 컨텍스트이기 때문에 지침을 작성하는 방식이 Claude가 얼마나 안정적으로 따르는지에 영향을 미칩니다. 구체적이고 간결하며 잘 구조화된 지침이 가장 잘 작동합니다.

80 92 


90 102 

91**일관성**: 두 규칙이 서로 모순되면 Claude가 하나를 임의로 선택할 수 있습니다. CLAUDE.md 파일, 하위 디렉토리의 중첩된 CLAUDE.md 파일 및 [`.claude/rules/`](#organize-rules-with-claude/rules/)을 정기적으로 검토하여 오래되었거나 충돌하는 지침을 제거합니다. 모노레포에서는 [`claudeMdExcludes`](#exclude-specific-claude-md-files)를 사용하여 작업과 관련이 없는 다른 팀의 CLAUDE.md 파일을 건너뜁니다.103**일관성**: 두 규칙이 서로 모순되면 Claude가 하나를 임의로 선택할 수 있습니다. CLAUDE.md 파일, 하위 디렉토리의 중첩된 CLAUDE.md 파일 및 [`.claude/rules/`](#organize-rules-with-claude/rules/)을 정기적으로 검토하여 오래되었거나 충돌하는 지침을 제거합니다. 모노레포에서는 [`claudeMdExcludes`](#exclude-specific-claude-md-files)를 사용하여 작업과 관련이 없는 다른 팀의 CLAUDE.md 파일을 건너뜁니다.

92 104 

93### 추가 파일 가져오기105<h3 id="import-additional-files">

106 추가 파일 가져오기

107</h3>

94 108 

95CLAUDE.md 파일은 `@path/to/import` 구문을 사용하여 추가 파일을 가져올 수 있습니다. 가져온 파일은 확장되어 참조하는 CLAUDE.md와 함께 시작 시 컨텍스트에 로드됩니다.109CLAUDE.md 파일은 `@path/to/import` 구문을 사용하여 추가 파일을 가져올 수 있습니다. 가져온 파일은 확장되어 참조하는 CLAUDE.md와 함께 시작 시 컨텍스트에 로드됩니다.

96 110 


120 134 

121지침을 구성하는 더 구조화된 접근 방식은 [`.claude/rules/`](#organize-rules-with-claude/rules/)을 참조하세요.135지침을 구성하는 더 구조화된 접근 방식은 [`.claude/rules/`](#organize-rules-with-claude/rules/)을 참조하세요.

122 136 

123### AGENTS.md137<h3 id="agents-md">

138 AGENTS.md

139</h3>

124 140 

125Claude Code는 `CLAUDE.md`를 읽으며 `AGENTS.md`를 읽지 않습니다. 저장소가 이미 다른 코딩 에이전트에 `AGENTS.md`를 사용하는 경우 `CLAUDE.md`를 만들어 이를 가져오면 두 도구가 중복 없이 동일한 지침을 읽을 수 있습니다. Claude 특정 지침을 가져오기 아래에 추가할 수도 있습니다. Claude는 가져온 파일을 세션 시작 시 로드한 다음 나머지를 추가합니다:141Claude Code는 `CLAUDE.md`를 읽으며 `AGENTS.md`를 읽지 않습니다. 저장소가 이미 다른 코딩 에이전트에 `AGENTS.md`를 사용하는 경우 `CLAUDE.md`를 만들어 이를 가져오면 두 도구가 중복 없이 동일한 지침을 읽을 수 있습니다. Claude 특정 지침을 가져오기 아래에 추가할 수도 있습니다. Claude는 가져온 파일을 세션 시작 시 로드한 다음 나머지를 추가합니다:

126 142 


140 156 

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

142 158 

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

144 160 

145### CLAUDE.md 파일이 로드되는 방식161<h3 id="how-claude-md-files-load">

162 CLAUDE.md 파일이 로드되는 방식

163</h3>

146 164 

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

148 166 


154 172 

155CLAUDE.md 파일의 블록 수준 HTML 주석(`<!-- maintainer notes -->`)은 콘텐츠가 Claude의 컨텍스트에 주입되기 전에 제거됩니다. 컨텍스트 토큰을 소비하지 않고 인간 유지보수자를 위한 노트를 남기는 데 사용합니다. 코드 블록 내의 주석은 보존됩니다. Read 도구로 CLAUDE.md 파일을 직접 열 때 주석이 표시된 상태로 유지됩니다.173CLAUDE.md 파일의 블록 수준 HTML 주석(`<!-- maintainer notes -->`)은 콘텐츠가 Claude의 컨텍스트에 주입되기 전에 제거됩니다. 컨텍스트 토큰을 소비하지 않고 인간 유지보수자를 위한 노트를 남기는 데 사용합니다. 코드 블록 내의 주석은 보존됩니다. Read 도구로 CLAUDE.md 파일을 직접 열 때 주석이 표시된 상태로 유지됩니다.

156 174 

157#### 추가 디렉토리에서 로드175<h4 id="load-from-additional-directories">

176 추가 디렉토리에서 로드

177</h4>

158 178 

159`--add-dir` 플래그는 Claude에 주 작업 디렉토리 외부의 추가 디렉토리에 대한 액세스를 제공합니다. 기본적으로 이러한 디렉토리의 CLAUDE.md 파일은 로드되지 않습니다.179`--add-dir` 플래그는 Claude에 주 작업 디렉토리 외부의 추가 디렉토리에 대한 액세스를 제공합니다. 기본적으로 이러한 디렉토리의 CLAUDE.md 파일은 로드되지 않습니다.

160 180 


166 186 

167이는 추가 디렉토리에서 `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md` 및 `CLAUDE.local.md`를 로드합니다. [`--setting-sources`](/ko/cli-reference)에서 `local`을 제외하면 `CLAUDE.local.md`는 건너뜁니다.187이는 추가 디렉토리에서 `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md` 및 `CLAUDE.local.md`를 로드합니다. [`--setting-sources`](/ko/cli-reference)에서 `local`을 제외하면 `CLAUDE.local.md`는 건너뜁니다.

168 188 

169### `.claude/rules/`로 규칙 구성189<h3 id="organize-rules-with-claude/rules/">

190 `.claude/rules/`로 규칙 구성

191</h3>

170 192 

171대규모 프로젝트의 경우 `.claude/rules/` 디렉토리를 사용하여 지침을 여러 파일로 구성할 수 있습니다. 이렇게 하면 지침이 모듈식이 되고 팀이 유지 관리하기 쉬워집니다. 규칙을 [특정 파일 경로로 범위 지정](#path-specific-rules)할 수도 있으므로 Claude가 일치하는 파일로 작업할 때만 컨텍스트에 로드되어 노이즈를 줄이고 컨텍스트 공간을 절약합니다.193대규모 프로젝트의 경우 `.claude/rules/` 디렉토리를 사용하여 지침을 여러 파일로 구성할 수 있습니다. 이렇게 하면 지침이 모듈식이 되고 팀이 유지 관리하기 쉬워집니다. 규칙을 [특정 파일 경로로 범위 지정](#path-specific-rules)할 수도 있으므로 Claude가 일치하는 파일로 작업할 때만 컨텍스트에 로드되어 노이즈를 줄이고 컨텍스트 공간을 절약합니다.

172 194 


174 규칙은 모든 세션 또는 일치하는 파일이 열릴 때 컨텍스트에 로드됩니다. 항상 컨텍스트에 있을 필요가 없는 작업별 지침의 경우 대신 [skills](/ko/skills)를 사용하세요. 이는 호출할 때 또는 Claude가 프롬프트와 관련이 있다고 판단할 때만 로드됩니다.196 규칙은 모든 세션 또는 일치하는 파일이 열릴 때 컨텍스트에 로드됩니다. 항상 컨텍스트에 있을 필요가 없는 작업별 지침의 경우 대신 [skills](/ko/skills)를 사용하세요. 이는 호출할 때 또는 Claude가 프롬프트와 관련이 있다고 판단할 때만 로드됩니다.

175</Note>197</Note>

176 198 

177#### 규칙 설정199<h4 id="set-up-rules">

200 규칙 설정

201</h4>

178 202 

179프로젝트의 `.claude/rules/` 디렉토리에 마크다운 파일을 배치합니다. 각 파일은 `testing.md` 또는 `api-design.md`와 같은 설명적인 파일명으로 한 가지 주제를 다루어야 합니다. 모든 `.md` 파일은 재귀적으로 발견되므로 `frontend/` 또는 `backend/`와 같은 하위 디렉토리로 규칙을 구성할 수 있습니다:203프로젝트의 `.claude/rules/` 디렉토리에 마크다운 파일을 배치합니다. 각 파일은 `testing.md` 또는 `api-design.md`와 같은 설명적인 파일명으로 한 가지 주제를 다루어야 합니다. 모든 `.md` 파일은 재귀적으로 발견되므로 `frontend/` 또는 `backend/`와 같은 하위 디렉토리로 규칙을 구성할 수 있습니다:

180 204 


190 214 

191[`paths` frontmatter](#path-specific-rules)가 없는 규칙은 `.claude/CLAUDE.md`와 동일한 우선순위로 시작 시 로드됩니다.215[`paths` frontmatter](#path-specific-rules)가 없는 규칙은 `.claude/CLAUDE.md`와 동일한 우선순위로 시작 시 로드됩니다.

192 216 

193#### 경로별 규칙217<h4 id="path-specific-rules">

218 경로별 규칙

219</h4>

194 220 

195규칙은 `paths` 필드가 있는 YAML frontmatter를 사용하여 특정 파일로 범위를 지정할 수 있습니다. 이러한 조건부 규칙은 Claude가 지정된 패턴과 일치하는 파일로 작업할 때만 적용됩니다.221규칙은 `paths` 필드가 있는 YAML frontmatter를 사용하여 특정 파일로 범위를 지정할 수 있습니다. 이러한 조건부 규칙은 Claude가 지정된 패턴과 일치하는 파일로 작업할 때만 적용됩니다.

196 222 


229---255---

230```256```

231 257 

232#### 심볼릭 링크로 프로젝트 간 규칙 공유258<h4 id="share-rules-across-projects-with-symlinks">

259 심볼릭 링크로 프로젝트 간 규칙 공유

260</h4>

233 261 

234`.claude/rules/` 디렉토리는 심볼릭 링크를 지원하므로 공유 규칙 세트를 유지하고 여러 프로젝트에 링크할 수 있습니다. 심볼릭 링크는 해석되어 정상적으로 로드되며 순환 심볼릭 링크는 감지되고 우아하게 처리됩니다.262`.claude/rules/` 디렉토리는 심볼릭 링크를 지원하므로 공유 규칙 세트를 유지하고 여러 프로젝트에 링크할 수 있습니다. 심볼릭 링크는 해석되어 정상적으로 로드되며 순환 심볼릭 링크는 감지되고 우아하게 처리됩니다.

235 263 


240ln -s ~/company-standards/security.md .claude/rules/security.md268ln -s ~/company-standards/security.md .claude/rules/security.md

241```269```

242 270 

243#### 사용자 수준 규칙271<h4 id="user-level-rules">

272 사용자 수준 규칙

273</h4>

244 274 

245`~/.claude/rules/`의 개인 규칙은 컴퓨터의 모든 프로젝트에 적용됩니다. 프로젝트별이 아닌 선호도에 사용합니다:275`~/.claude/rules/`의 개인 규칙은 컴퓨터의 모든 프로젝트에 적용됩니다. 프로젝트별이 아닌 선호도에 사용합니다:

246 276 


252 282 

253사용자 수준 규칙은 프로젝트 규칙 전에 로드되어 프로젝트 규칙에 더 높은 우선순위를 제공합니다.283사용자 수준 규칙은 프로젝트 규칙 전에 로드되어 프로젝트 규칙에 더 높은 우선순위를 제공합니다.

254 284 

255### 대규모 팀을 위한 CLAUDE.md 관리285<h3 id="manage-claude-md-for-large-teams">

286 대규모 팀을 위한 CLAUDE.md 관리

287</h3>

256 288 

257조직에서 Claude Code를 팀 전체에 배포하는 경우 지침을 중앙 집중식으로 관리하고 로드되는 CLAUDE.md 파일을 제어할 수 있습니다.289조직에서 Claude Code를 팀 전체에 배포하는 경우 지침을 중앙 집중식으로 관리하고 로드되는 CLAUDE.md 파일을 제어할 수 있습니다.

258 290 

259#### 조직 전체 CLAUDE.md 배포291<h4 id="deploy-organization-wide-claude-md">

292 조직 전체 CLAUDE.md 배포

293</h4>

260 294 

261조직은 컴퓨터의 모든 사용자에게 적용되는 중앙 집중식으로 관리되는 CLAUDE.md를 배포할 수 있습니다. 이 파일은 개별 설정으로 제외될 수 없습니다.295조직은 컴퓨터의 모든 사용자에게 적용되는 중앙 집중식으로 관리되는 CLAUDE.md를 배포할 수 있습니다. 이 파일은 개별 설정으로 제외될 수 없습니다.

262 296 


302 336 

303설정 규칙은 Claude가 무엇을 하기로 결정하든 클라이언트에 의해 강제됩니다. CLAUDE.md 지침은 Claude의 행동을 형성하지만 하드 강제 레이어가 아닙니다.337설정 규칙은 Claude가 무엇을 하기로 결정하든 클라이언트에 의해 강제됩니다. CLAUDE.md 지침은 Claude의 행동을 형성하지만 하드 강제 레이어가 아닙니다.

304 338 

305#### 특정 CLAUDE.md 파일 제외339<h4 id="exclude-specific-claude-md-files">

340 특정 CLAUDE.md 파일 제외

341</h4>

306 342 

307대규모 모노레포에서 상위 CLAUDE.md 파일에는 작업과 관련이 없는 지침이 포함될 수 있습니다. `claudeMdExcludes` 설정을 통해 경로 또는 glob 패턴으로 특정 파일을 건너뛸 수 있습니다.343대규모 모노레포에서 상위 CLAUDE.md 파일에는 작업과 관련이 없는 지침이 포함될 수 있습니다. `claudeMdExcludes` 설정을 통해 경로 또는 glob 패턴으로 특정 파일을 건너뛸 수 있습니다.

308 344 


321 357 

322관리 정책 CLAUDE.md 파일은 제외될 수 없습니다. 이렇게 하면 개별 설정에 관계없이 조직 전체 지침이 항상 적용됩니다.358관리 정책 CLAUDE.md 파일은 제외될 수 없습니다. 이렇게 하면 개별 설정에 관계없이 조직 전체 지침이 항상 적용됩니다.

323 359 

324## 자동 메모리360<h2 id="auto-memory">

361 자동 메모리

362</h2>

325 363 

326자동 메모리를 통해 Claude는 아무것도 작성하지 않고도 세션 간에 지식을 축적할 수 있습니다. Claude는 작업할 때 자신을 위해 노트를 저장합니다: 빌드 명령, 디버깅 인사이트, 아키텍처 노트, 코드 스타일 선호도 및 워크플로우 습관. Claude는 모든 세션마다 뭔가를 저장하지 않습니다. 정보가 향후 대화에서 유용할지 여부에 따라 기억할 가치가 있는지 결정합니다.364자동 메모리를 통해 Claude는 아무것도 작성하지 않고도 세션 간에 지식을 축적할 수 있습니다. Claude는 작업할 때 자신을 위해 노트를 저장합니다: 빌드 명령, 디버깅 인사이트, 아키텍처 노트, 코드 스타일 선호도 및 워크플로우 습관. Claude는 모든 세션마다 뭔가를 저장하지 않습니다. 정보가 향후 대화에서 유용할지 여부에 따라 기억할 가치가 있는지 결정합니다.

327 365 


329 자동 메모리는 Claude Code v2.1.59 이상이 필요합니다. `claude --version`으로 버전을 확인합니다.367 자동 메모리는 Claude Code v2.1.59 이상이 필요합니다. `claude --version`으로 버전을 확인합니다.

330</Note>368</Note>

331 369 

332### 자동 메모리 활성화 또는 비활성화370<h3 id="enable-or-disable-auto-memory">

371 자동 메모리 활성화 또는 비활성화

372</h3>

333 373 

334자동 메모리는 기본적으로 켜져 있습니다. 토글하려면 세션에서 `/memory`를 열고 자동 메모리 토글을 사용하거나 프로젝트 설정에서 `autoMemoryEnabled`를 설정합니다:374자동 메모리는 기본적으로 켜져 있습니다. 토글하려면 세션에서 `/memory`를 열고 자동 메모리 토글을 사용하거나 프로젝트 설정에서 `autoMemoryEnabled`를 설정합니다:

335 375 


341 381 

342환경 변수를 통해 자동 메모리를 비활성화하려면 `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`을 설정합니다.382환경 변수를 통해 자동 메모리를 비활성화하려면 `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`을 설정합니다.

343 383 

344### 저장소 위치384<h3 id="storage-location">

385 저장소 위치

386</h3>

345 387 

346각 프로젝트는 `~/.claude/projects/<project>/memory/`에서 자신의 메모리 디렉토리를 가집니다. `<project>` 경로는 git 저장소에서 파생되므로 동일한 저장소 내의 모든 worktree 및 하위 디렉토리는 하나의 자동 메모리 디렉토리를 공유합니다. git 저장소 외부에서는 프로젝트 루트가 대신 사용됩니다.388각 프로젝트는 `~/.claude/projects/<project>/memory/`에서 자신의 메모리 디렉토리를 가집니다. `<project>` 경로는 git 저장소에서 파생되므로 동일한 저장소 내의 모든 worktree 및 하위 디렉토리는 하나의 자동 메모리 디렉토리를 공유합니다. git 저장소 외부에서는 프로젝트 루트가 대신 사용됩니다.

347 389 


369 411 

370자동 메모리는 컴퓨터 로컬입니다. 동일한 git 저장소 내의 모든 worktree 및 하위 디렉토리는 하나의 자동 메모리 디렉토리를 공유합니다. 파일은 컴퓨터 간 또는 클라우드 환경 간에 공유되지 않습니다.412자동 메모리는 컴퓨터 로컬입니다. 동일한 git 저장소 내의 모든 worktree 및 하위 디렉토리는 하나의 자동 메모리 디렉토리를 공유합니다. 파일은 컴퓨터 간 또는 클라우드 환경 간에 공유되지 않습니다.

371 413 

372### 작동 방식414<h3 id="how-it-works">

415 작동 방식

416</h3>

373 417 

374`MEMORY.md`의 처음 200줄 또는 처음 25KB(둘 중 먼저 오는 것)는 모든 대화의 시작 시 로드됩니다. 해당 임계값을 초과하는 콘텐츠는 세션 시작 시 로드되지 않습니다. Claude는 자세한 노트를 별도의 주제 파일로 이동하여 `MEMORY.md`를 간결하게 유지합니다.418`MEMORY.md`의 처음 200줄 또는 처음 25KB(둘 중 먼저 오는 것)는 모든 대화의 시작 시 로드됩니다. 해당 임계값을 초과하는 콘텐츠는 세션 시작 시 로드되지 않습니다. Claude는 자세한 노트를 별도의 주제 파일로 이동하여 `MEMORY.md`를 간결하게 유지합니다.

375 419 


379 423 

380Claude는 세션 중에 메모리 파일을 읽고 씁니다. Claude Code 인터페이스에서 "Writing memory" 또는 "Recalled memory"를 보면 Claude가 `~/.claude/projects/<project>/memory/`에서 활발히 업데이트하거나 읽고 있습니다.424Claude는 세션 중에 메모리 파일을 읽고 씁니다. Claude Code 인터페이스에서 "Writing memory" 또는 "Recalled memory"를 보면 Claude가 `~/.claude/projects/<project>/memory/`에서 활발히 업데이트하거나 읽고 있습니다.

381 425 

382### 메모리 감사 및 편집426<h3 id="audit-and-edit-your-memory">

427 메모리 감사 및 편집

428</h3>

383 429 

384자동 메모리 파일은 언제든지 편집하거나 삭제할 수 있는 일반 마크다운입니다. [`/memory`](#view-and-edit-with-memory)를 실행하여 세션 내에서 메모리 파일을 찾아보고 엽니다.430자동 메모리 파일은 언제든지 편집하거나 삭제할 수 있는 일반 마크다운입니다. [`/memory`](#view-and-edit-with-%2Fmemory)를 실행하여 세션 내에서 메모리 파일을 찾아보고 엽니다.

385 431 

386## `/memory`로 보기 및 편집432<h2 id="view-and-edit-with-/memory">

433 `/memory`로 보기 및 편집

434</h2>

387 435 

388`/memory` 명령은 현재 세션에 로드된 모든 CLAUDE.md, CLAUDE.local.md 및 규칙 파일을 나열하고, 자동 메모리를 켜거나 끌 수 있으며, 자동 메모리 폴더를 열 수 있는 링크를 제공합니다. 파일을 선택하여 편집기에서 엽니다.436`/memory` 명령은 현재 세션에 로드된 모든 CLAUDE.md, CLAUDE.local.md 및 규칙 파일을 나열하고, 자동 메모리를 켜거나 끌 수 있으며, 자동 메모리 폴더를 열 수 있는 링크를 제공합니다. 파일을 선택하여 편집기에서 엽니다.

389 437 

390Claude에게 "항상 npm이 아닌 pnpm을 사용합니다" 또는 "API 테스트에 로컬 Redis 인스턴스가 필요하다는 것을 기억합니다"와 같이 뭔가를 기억하도록 요청하면 Claude는 자동 메모리에 저장합니다. 대신 CLAUDE.md에 지침을 추가하려면 Claude에게 직접 "이것을 CLAUDE.md에 추가합니다"라고 요청하거나 `/memory`를 통해 파일을 직접 편집합니다.438Claude에게 "항상 npm이 아닌 pnpm을 사용합니다" 또는 "API 테스트에 로컬 Redis 인스턴스가 필요하다는 것을 기억합니다"와 같이 뭔가를 기억하도록 요청하면 Claude는 자동 메모리에 저장합니다. 대신 CLAUDE.md에 지침을 추가하려면 Claude에게 직접 "이것을 CLAUDE.md에 추가합니다"라고 요청하거나 `/memory`를 통해 파일을 직접 편집합니다.

391 439 

392## 메모리 문제 해결440<h2 id="troubleshoot-memory-issues">

441 메모리 문제 해결

442</h2>

393 443 

394이들은 CLAUDE.md 및 자동 메모리의 가장 일반적인 문제와 디버깅 단계입니다.444이들은 CLAUDE.md 및 자동 메모리의 가장 일반적인 문제와 디버깅 단계입니다.

395 445 

396### Claude가 CLAUDE.md를 따르지 않습니다446<h3 id="claude-isn’t-following-my-claude-md">

447 Claude가 CLAUDE.md를 따르지 않습니다

448</h3>

397 449 

398CLAUDE.md 콘텐츠는 시스템 프롬프트의 일부가 아니라 시스템 프롬프트 후 사용자 메시지로 전달됩니다. Claude는 이를 읽고 따르려고 하지만 특히 모호하거나 충돌하는 지침의 경우 엄격한 준수를 보장하지 않습니다.450CLAUDE.md 콘텐츠는 시스템 프롬프트의 일부가 아니라 시스템 프롬프트 후 사용자 메시지로 전달됩니다. Claude는 이를 읽고 따르려고 하지만 특히 모호하거나 충돌하는 지침의 경우 엄격한 준수를 보장하지 않습니다.

399 451 


412 [`InstructionsLoaded` hook](/ko/hooks#instructionsloaded)을 사용하여 로드된 지침 파일, 로드 시기 및 이유를 정확히 기록합니다. 이는 경로별 규칙 또는 하위 디렉토리의 지연 로드 파일을 디버깅하는 데 유용합니다.464 [`InstructionsLoaded` hook](/ko/hooks#instructionsloaded)을 사용하여 로드된 지침 파일, 로드 시기 및 이유를 정확히 기록합니다. 이는 경로별 규칙 또는 하위 디렉토리의 지연 로드 파일을 디버깅하는 데 유용합니다.

413</Tip>465</Tip>

414 466 

415### 자동 메모리가 저장한 내용을 모릅니다467<h3 id="i-don’t-know-what-auto-memory-saved">

468 자동 메모리가 저장한 내용을 모릅니다

469</h3>

416 470 

417`/memory`를 실행하고 자동 메모리 폴더를 선택하여 Claude가 저장한 내용을 찾아봅니다. 모든 것이 읽고, 편집하거나 삭제할 수 있는 일반 마크다운입니다.471`/memory`를 실행하고 자동 메모리 폴더를 선택하여 Claude가 저장한 내용을 찾아봅니다. 모든 것이 읽고, 편집하거나 삭제할 수 있는 일반 마크다운입니다.

418 472 

419### CLAUDE.md가 너무 큽니다473<h3 id="my-claude-md-is-too-large">

474 CLAUDE.md가 너무 큽니다

475</h3>

420 476 

421200줄을 초과하는 파일은 더 많은 컨텍스트를 소비하고 준수를 줄일 수 있습니다. [경로별 규칙](#path-specific-rules)을 사용하여 Claude가 일치하는 파일로 작업할 때만 지침을 로드하거나 모든 세션에서 필요하지 않은 콘텐츠를 정리합니다. [`@path` 가져오기](#import-additional-files)로 분할하면 조직화에 도움이 되지만 가져온 파일이 시작 시 로드되므로 컨텍스트를 줄이지는 않습니다.477200줄을 초과하는 파일은 더 많은 컨텍스트를 소비하고 준수를 줄일 수 있습니다. [경로별 규칙](#path-specific-rules)을 사용하여 Claude가 일치하는 파일로 작업할 때만 지침을 로드하거나 모든 세션에서 필요하지 않은 콘텐츠를 정리합니다. [`@path` 가져오기](#import-additional-files)로 분할하면 조직화에 도움이 되지만 가져온 파일이 시작 시 로드되므로 컨텍스트를 줄이지는 않습니다.

422 478 

423### `/compact` 후 지침이 손실된 것 같습니다479<h3 id="instructions-seem-lost-after-/compact">

480 `/compact` 후 지침이 손실된 것 같습니다

481</h3>

424 482 

425프로젝트 루트 CLAUDE.md는 압축을 완전히 생존합니다: `/compact` 후 Claude는 디스크에서 CLAUDE.md를 다시 읽고 세션에 새로 다시 주입합니다. 하위 디렉토리의 중첩된 CLAUDE.md 파일은 자동으로 다시 주입되지 않습니다. 해당 하위 디렉토리의 파일을 다시 읽을 때 다음에 다시 로드됩니다.483프로젝트 루트 CLAUDE.md는 압축을 완전히 생존합니다: `/compact` 후 Claude는 디스크에서 CLAUDE.md를 다시 읽고 세션에 새로 다시 주입합니다. 하위 디렉토리의 중첩된 CLAUDE.md 파일은 자동으로 다시 주입되지 않습니다. 해당 하위 디렉토리의 파일을 다시 읽을 때 다음에 다시 로드됩니다.

426 484 


428 486 

429[효과적인 지침 작성](#write-effective-instructions)을 참조하여 크기, 구조 및 구체성에 대한 지침을 확인합니다.487[효과적인 지침 작성](#write-effective-instructions)을 참조하여 크기, 구조 및 구체성에 대한 지침을 확인합니다.

430 488 

431## 관련 리소스489<h2 id="related-resources">

490 관련 리소스

491</h2>

432 492 

433* [구성 디버깅](/ko/debug-your-config): CLAUDE.md 또는 설정이 적용되지 않는 이유 진단493* [구성 디버깅](/ko/debug-your-config): CLAUDE.md 또는 설정이 적용되지 않는 이유 진단

434* [Skills](/ko/skills): 필요에 따라 로드되는 반복 가능한 워크플로우 패키지494* [Skills](/ko/skills): 필요에 따라 로드되는 반복 가능한 워크플로우 패키지

Details

6 6 

7> 설정, 구성 및 문제 해결을 포함하여 Microsoft Foundry를 통해 Claude Code를 구성하는 방법을 알아봅니다.7> 설정, 구성 및 문제 해결을 포함하여 Microsoft Foundry를 통해 Claude Code를 구성하는 방법을 알아봅니다.

8 8 

9export const ContactSalesCard = ({surface}) => {

10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;

11 const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

12 <line x1="5" y1="12" x2="19" y2="12" />

13 <polyline points="12 5 19 12 12 19" />

14 </svg>;

15 const STYLES = `

16.cc-cs {

17 --cs-slate: #141413;

18 --cs-clay: #d97757;

19 --cs-clay-deep: #c6613f;

20 --cs-gray-000: #ffffff;

21 --cs-gray-700: #3d3d3a;

22 --cs-border-default: rgba(31, 30, 29, 0.15);

23 font-family: inherit;

24}

25.dark .cc-cs {

26 --cs-slate: #f0eee6;

27 --cs-gray-000: #262624;

28 --cs-gray-700: #bfbdb4;

29 --cs-border-default: rgba(240, 238, 230, 0.14);

30}

31.cc-cs-card {

32 display: flex; align-items: center; justify-content: space-between;

33 gap: 16px; padding: 14px 16px; margin: 0;

34 background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default);

35 border-radius: 8px; flex-wrap: wrap;

36}

37.cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; }

38.cc-cs-text strong { font-weight: 550; color: var(--cs-slate); }

39.cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }

40.cc-cs-btn-clay {

41 display: inline-flex; align-items: center; gap: 8px;

42 background: var(--cs-clay-deep); color: #fff; border: none;

43 border-radius: 8px; padding: 8px 14px;

44 font-size: 13px; font-weight: 500;

45 transition: background-color 0.15s; white-space: nowrap;

46}

47.cc-cs-btn-clay:hover { background: var(--cs-clay); }

48.cc-cs-btn-ghost {

49 display: inline-flex; align-items: center; gap: 8px;

50 background: transparent; color: var(--cs-gray-700);

51 border: 0.5px solid var(--cs-border-default);

52 border-radius: 8px; padding: 8px 14px;

53 font-size: 13px; font-weight: 500;

54}

55.cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }

56.dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); }

57@media (max-width: 720px) {

58 .cc-cs-actions { width: 100%; }

59}

60`;

61 return <div className="cc-cs not-prose">

62 <style>{STYLES}</style>

63 <div className="cc-cs-card">

64 <div className="cc-cs-text">

65 <strong>Deploying Claude Code across your organization?</strong> Talk to sales about enterprise plans, SSO, and centralized billing.

66 </div>

67 <div className="cc-cs-actions">

68 <a href={`https://claude.com/pricing?${utm('view_plans')}#plans-business`} className="cc-cs-btn-ghost">

69 View plans

70 </a>

71 <a href={`https://claude.com/contact-sales?${utm('contact_sales')}`} className="cc-cs-btn-clay">

72 Contact sales {iconArrowRight()}

73 </a>

74 </div>

75 </div>

76 </div>;

77};

78 

79<ContactSalesCard surface="foundry" />

80 

9<h2 id="prerequisites">81<h2 id="prerequisites">

10 필수 조건82 필수 조건

11</h2>83</h2>


17* Azure CLI 설치 및 구성(선택 사항 - 자격 증명을 얻을 다른 메커니즘이 없는 경우에만 필요)89* Azure CLI 설치 및 구성(선택 사항 - 자격 증명을 얻을 다른 메커니즘이 없는 경우에만 필요)

18 90 

19<Note>91<Note>

20 Claude Code를 여러 사용자에게 배포하는 경우 Anthropic이 새 모델을 출시할 때 중단을 방지하기 위해 [모델 버전을 고정](#4-pin-model-versions)하세요.92 Claude Code를 여러 사용자에게 배포하는 경우 [모델 버전을 고정](#4-pin-model-versions)하기 전에 롤아웃하세요.

21</Note>93</Note>

22 94 

23<h2 id="setup">95<h2 id="setup">


90</h3>162</h3>

91 163 

92<Warning>164<Warning>

93 모든 배포에 대해 특정 모델 버전을 고정합니다. 고정하지 않고 모델 별칭(`sonnet`, `opus`, `haiku`)을 사용하면 Claude Code가 Foundry 계정에서 사용할 수 없는 최신 모델 버전을 사용하려고 시도하여 Anthropic이 업데이트를 출시할 기존 사용자가 중단될 있습니다. Azure 배포를 만들 때 "최신으로 자동 업데이트" 대신 특정 모델 버전을 선택합니다.165 모든 배포에 대해 특정 모델 버전을 고정합니다. 고정하지 않으면 `sonnet` `opus` 같은 모델 별칭이 Claude Code의 Foundry용 기본 제공 기본값으로 확인되며, 이는 최신 릴리스보다 뒤떨어질 수 있고 계정에서 아직 사용할 수 없을 있습니다. Foundry는 시작 모델 확인이 없으므로 기본값을 사용할 없을 요청이 실패합니다. Azure 배포를 만들 때 "최신으로 자동 업데이트" 대신 특정 모델 버전을 선택합니다.

94</Warning>166</Warning>

95 167 

96모델 변수를 1단계에서 만든 배포 이름과 일치하도록 설정합니다.168모델 변수를 1단계에서 만든 배포 이름과 일치하도록 설정합니다.


103export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'175export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'

104```176```

105 177 

106백그라운드 작업(예: 세션 제목 생성)은 일반적으로 Haiku 클래스 모델인 소형/빠른 모델을 사용합니다. Foundry에서 Claude Code는 모든 계정이 Haiku 배포를 가지고 있지 않기 때문에 기본 모델로 기본 설정됩니다. 백그라운드 작업에 Haiku를 사용하려면 위에 표시된 대로 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 계정에서 사용 가능한 Haiku 배포로 설정합니다.178세션 제목 생성과 같은 백그라운드 작업은 일반적으로 Haiku 클래스 모델인 소형/빠른 모델을 사용합니다. Foundry에서 Claude Code는 모든 계정이 Haiku 배포를 가지고 있지 않기 때문에 기본 모델로 기본 설정됩니다. 백그라운드 작업에 Haiku를 사용하려면 위에 표시된 대로 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 계정에서 사용 가능한 Haiku 배포로 설정합니다.

107 179 

108현재 및 레거시 모델 ID는 [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview)를 참조하세요. 전체 환경 변수 목록은 [모델 구성](/ko/model-config#pin-models-for-third-party-deployments)을 참조하세요.180현재 및 레거시 모델 ID는 [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview)를 참조하세요. 전체 환경 변수 목록은 [모델 구성](/ko/model-config#pin-models-for-third-party-deployments)을 참조하세요.

109 181 

model-config.md +150 −28

Details

32| 모델 별칭 | 동작 |32| 모델 별칭 | 동작 |

33| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |33| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |

34| **`default`** | 모델 재정의를 제거하고 계정 유형에 따른 권장 모델로 되돌리는 특수 값입니다. 자체로는 모델 별칭이 아닙니다 |34| **`default`** | 모델 재정의를 제거하고 계정 유형에 따른 권장 모델로 되돌리는 특수 값입니다. 자체로는 모델 별칭이 아닙니다 |

35| **`best`** | 현재 사용 가능한 가장 강력한 모델을 사용하며, 현재 `opus`와 동일합니다 |35| **`best`** | 조직에서 액세스할 있는 경우 Fable 5를 사용하고, 그렇지 않으면 최신 Opus 모델을 사용합니다 |

36| **`fable`** | 가장 어렵고 오래 실행되는 작업을 위해 Claude Fable 5를 사용합니다 |

36| **`sonnet`** | 일일 코딩 작업을 위해 최신 Sonnet 모델을 사용합니다 |37| **`sonnet`** | 일일 코딩 작업을 위해 최신 Sonnet 모델을 사용합니다 |

37| **`opus`** | 복잡한 추론 작업을 위해 최신 Opus 모델을 사용합니다 |38| **`opus`** | 복잡한 추론 작업을 위해 최신 Opus 모델을 사용합니다 |

38| **`haiku`** | 간단한 작업을 위해 빠르고 효율적인 Haiku 모델을 사용합니다 |39| **`haiku`** | 간단한 작업을 위해 빠르고 효율적인 Haiku 모델을 사용합니다 |


48 Opus 4.8은 Claude Code v2.1.154 이상이 필요합니다. `claude update`를 실행하여 업그레이드하세요.49 Opus 4.8은 Claude Code v2.1.154 이상이 필요합니다. `claude update`를 실행하여 업그레이드하세요.

49</Note>50</Note>

50 51 

52<h3 id="work-with-fable-5">

53 Fable 5로 작업하기

54</h3>

55 

56[Claude Fable 5](https://platform.claude.com/docs/ko/about-claude/models/introducing-claude-fable-5-and-claude-mythos-5)는 Claude Code에서 가장 강력한 모델이며, 한 번의 세션보다 큰 작업에 적합합니다. 긴 자율 세션을 유지하고, 행동하기 전에 조사하며, 더 작은 모델보다 더 자주 작업을 검증합니다.

57 

58Fable 5는 기본 모델이 아닙니다. `/model fable`로 선택합니다. 안전 분류기가 플래그를 지정하는 요청(대부분 사이버 보안 및 생물학 도메인)은 [자동 모델 폴백](#automatic-model-fallback)을 트리거합니다.

59 

60Fable 5를 최대한 활용하려면:

61 

62* **결과를 설명하고 단계는 설명하지 마세요**: 원하는 결과를 제공하고 경로를 계획하도록 합니다. 해당 결과가 유지될 때까지 작업을 계속하려면 [목표를 설정](/ko/goal)하세요.

63* **모호한 문제를 제공하세요**: 근본 원인 조사, 중단 디버깅 및 아키텍처 결정은 추가 조사 및 검증이 효과를 발휘하는 곳입니다.

64* **검증 알림을 건너뛰세요**: 더 적은 프롬프팅으로 자신의 작업을 검증하므로 테스트 또는 확인 알림은 일반적으로 불필요합니다.

65* **더 큰 작업을 크기 조정하세요**: 일반적으로 여러 부분으로 나누는 작업을 제공합니다. 긴 세션을 유지하면서 스레드를 잃지 않습니다.

66 

67<Note>

68 Fable 5는 Claude Code v2.1.170 이상이 필요합니다. 이전 버전은 모델 선택기에 Fable 5를 표시하지 않으며 선택할 수 없습니다. `claude update`를 실행하여 업그레이드하세요. Fable 5는 [제로 데이터 보존](/ko/zero-data-retention) 하에서 사용할 수 없으며, `/model` 선택기는 이를 생략하거나 비활성화된 상태로 표시합니다.

69</Note>

70 

51<h3 id="setting-your-model">71<h3 id="setting-your-model">

52 모델 설정72 모델 설정

53</h3>73</h3>


101 121 

102엔터프라이즈 관리자는 [관리 또는 정책 설정](/ko/settings#settings-files)에서 `availableModels`을 사용하여 사용자가 선택할 수 있는 모델을 제한할 수 있습니다.122엔터프라이즈 관리자는 [관리 또는 정책 설정](/ko/settings#settings-files)에서 `availableModels`을 사용하여 사용자가 선택할 수 있는 모델을 제한할 수 있습니다.

103 123 

104`availableModels`이 설정되면 사용자는 `/model`, `--model` 플래그 또는 `ANTHROPIC_MODEL` 환경 변수를 통해 목록에 없는 모델로 전환할 없습니다.124`availableModels`이 설정되면 허용 목록은 사용자가 모델을 지정할 있는 모든 위치에 적용됩니다:

125 

126* **메인 세션 모델**: `/model`, `--model` 플래그 및 `ANTHROPIC_MODEL` 환경 변수

127* **별칭 해석**: {/* min-version: 2.1.176 */}`ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL` 및 `ANTHROPIC_DEFAULT_FABLE_MODEL` 환경 변수는 허용된 별칭을 목록 외부의 모델로 리디렉션할 수 없습니다

128* **빠른 모드**: {/* min-version: 2.1.176 */}`/fast`는 목록 외부의 Opus 모델로 암시적으로 전환될 때 토글을 거부하며, "is not in your organization's allowed models" 메시지를 표시합니다

129* **서브에이전트 모델**: [서브에이전트](/ko/sub-agents#choose-a-model) frontmatter의 `model` 필드, Agent 도구의 `model` 매개변수, `/agents`의 모델 선택기 및 `CLAUDE_CODE_SUBAGENT_MODEL`

130* **어드바이저 모델**: 구성된 [`advisorModel`](/ko/advisor) 설정

131* **폴백 체인**: [폴백 모델 체인](#fallback-model-chains) 외부의 요소는 삭제됩니다

132 

133`/model`로 차단된 모델로 전환하면 오류로 거부되고, 차단된 `--model` 플래그 또는 `ANTHROPIC_MODEL` 값은 시작 시 요청된 모델과 대체된 모델을 모두 이름 지은 경고와 함께 대체되며 세션은 기본 모델에서 시작됩니다. 차단된 서브에이전트 또는 어드바이저 재정의는 요청을 실패하지 않고 상속되거나 기본 모델로 폴백됩니다.

105 134 

106```json theme={null}135```json theme={null}

107{136{


113 기본 모델 동작142 기본 모델 동작

114</h3>143</h3>

115 144 

116모델 선택기의 Default 옵션은 `availableModels`의 영향을 받지 않습니다. 항상 사용 가능하며 [사용자의 구독 계층을 기반으로 한](#default-model-setting) 시스템의 런타임 기본값을 나타냅니다.145기본적으로 모델 선택기의 Default 옵션은 `availableModels`의 영향을 받지 않습니다. 항상 사용 가능하며 [사용자의 구독 계층을 기반으로 한](#default-model-setting) 시스템의 런타임 기본값을 나타냅니다.

117 146 

118`availableModels: []` 경우에도 사용자는 자신의 계층에 대한 Default 모델로 Claude Code를 사용할 있습니다.147허용 목록을 Default 옵션으로 확장하려면 비어 있지 않은 `availableModels` 목록과 함께 관리 또는 정책 설정에서 `enforceAvailableModels`을 `true`로 설정합니다. 계층 기본값이 허용 목록에 없으면 Default는 계층 기본값 대신 첫 번째 허용된 항목으로 확인됩니다. 이는 Claude Code v2.1.175 이상이 필요합니다.

148 

149빈 `availableModels` 배열은 강제를 활성화하지 않습니다. `availableModels: []`인 경우에도 사용자는 `enforceAvailableModels`에 관계없이 자신의 계층에 대한 Default 모델로 Claude Code를 사용할 수 있습니다.

119 150 

120<h3 id="control-the-model-users-run-on">151<h3 id="control-the-model-users-run-on">

121 사용자가 실행하는 모델 제어152 사용자가 실행하는 모델 제어


123 154 

124`model` 설정은 초기 선택이지 강제가 아닙니다. 세션이 시작될 때 활성화되는 모델을 설정하지만 사용자는 여전히 `/model`을 열고 Default를 선택할 수 있으며, 이는 `model`이 설정된 것과 관계없이 계층에 대한 시스템 기본값으로 확인됩니다.155`model` 설정은 초기 선택이지 강제가 아닙니다. 세션이 시작될 때 활성화되는 모델을 설정하지만 사용자는 여전히 `/model`을 열고 Default를 선택할 수 있으며, 이는 `model`이 설정된 것과 관계없이 계층에 대한 시스템 기본값으로 확인됩니다.

125 156 

126모델 경험을 완전히 제어하려면 세 가지 설정을 함께 사용합니다:157모델 경험을 완전히 제어하려면 이러한 설정을 함께 사용합니다:

127 158 

128* **`availableModels`**: 사용자가 전환할 수 있는 명명된 모델을 제한합니다159* **`availableModels`**: 사용자가 전환할 수 있는 명명된 모델을 제한합니다

129* **`model`**: 세션이 시작될 활성화되는 초기 모델 선택을 설정합니다160* **`enforceAvailableModels`**: `availableModels` 허용 목록을 Default 옵션으로 확장하므로 Default는 목록 외부의 모델로 확인될 수 없습니다

130* **`ANTHROPIC_DEFAULT_SONNET_MODEL`** / **`ANTHROPIC_DEFAULT_OPUS_MODEL`** / **`ANTHROPIC_DEFAULT_HAIKU_MODEL`**: Default 옵션과 `sonnet`, `opus`, `haiku` 별칭이 확인되는 대상을 제어합니다161* **`model`**: 세션이 시작될 초기 모델 선택을 설정합니다

162* **`ANTHROPIC_DEFAULT_SONNET_MODEL`** / **`ANTHROPIC_DEFAULT_OPUS_MODEL`** / **`ANTHROPIC_DEFAULT_HAIKU_MODEL`** / **`ANTHROPIC_DEFAULT_FABLE_MODEL`**: Default 옵션과 `sonnet`, `opus`, `haiku`, `fable` 별칭이 확인되는 대상을 제어합니다

131 163 

132이 예시는 사용자를 Sonnet 4.5에서 시작하고, 선택기를 Sonnet과 Haiku로 제한하며, Default가 최신 릴리스가 아닌 Sonnet 4.5로 확인되도록 고정합니다:164이 예시는 사용자를 Sonnet 4.5에서 시작하고, 선택기를 Sonnet과 Haiku로 제한하며, Default가 계층 기본값이 아닌 허용 목록의 모델로 확인되도록 합니다:

133 165 

134```json theme={null}166```json theme={null}

135{167{

136 "model": "claude-sonnet-4-5",168 "model": "claude-sonnet-4-5",

137 "availableModels": ["claude-sonnet-4-5", "haiku"],169 "availableModels": ["claude-sonnet-4-5", "haiku"],

170 "enforceAvailableModels": true,

138 "env": {171 "env": {

139 "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5"172 "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5"

140 }173 }

141}174}

142```175```

143 176 

144`env` 블록이 없으면 선택기에서 Default를 선택하는 사용자는 최신 Sonnet 릴리스를 받게 되어 `model` 및 `availableModels`의 버전 고정을 우회합니다.177`enforceAvailableModels` 또는 `env` 블록이 없으면 선택기에서 Default를 선택하는 사용자는 자신의 계층에 대한 최신 릴리스를 받게 되어 `model` 및 `availableModels`의 버전 고정을 우회합니다. 두 설정은 서로 다른 범위를 다룹니다: `enforceAvailableModels`는 Default가 허용 목록을 따르도록 하고, `env` 블록은 `sonnet`과 같은 허용된 별칭이 확인되는 특정 버전을 고정합니다. 모델 패밀리 제한이 충분할 때는 `enforceAvailableModels`만 사용하고, 특정 버전을 고정해야 할 때는 `env` 블록을 추가합니다.

145 178 

146<h3 id="merge-behavior">179<h3 id="merge-behavior">

147 병합 동작180 병합 동작

148</h3>181</h3>

149 182 

150`availableModels`이 사용자 설정 및 프로젝트 설정과 같은 여러 수준에서 설정되면 배열이 병합되고 중복이 제거됩니다. 엄격한 허용 목록을 적용하려면 가장 높은 우선순위를 가지는 관리 또는 정책 설정에서 `availableModels`을 설정합니다.183`availableModels`이 사용자, 프로젝트 로컬 설정에서만 설정되면 배열이 병합되고 이러한 수준에서 중복이 제거됩니다.

184 

185`availableModels`이 관리 또는 정책 설정에서 설정되면 관리 또는 정책 값이 병합된 결과를 완전히 대체합니다: 사용자 또는 프로젝트 설정에서 추가된 항목은 이를 확대할 수 없습니다. 관리 및 정책 설정은 `enforceAvailableModels`에 대해 동일한 방식으로 낮은 우선순위 값을 대체합니다. Claude Code v2.1.175부터 이것이 엄격한 허용 목록을 적용하는 유일한 방법입니다. 이전 버전은 관리 목록을 낮은 우선순위 항목과 병합합니다.

151 186 

152<h3 id="mantle-model-ids">187<h3 id="mantle-model-ids">

153 Mantle 모델 ID188 Mantle 모델 ID

154</h3>189</h3>

155 190 

156[Bedrock Mantle 엔드포인트](/ko/amazon-bedrock#use-the-mantle-endpoint)가 활성화되면 `availableModels`의 `anthropic.`으로 시작하는 항목이 `/model` 선택기에 사용자 정의 옵션으로 추가되고 Mantle 엔드포인트로 라우팅됩니다. 이는 [타사 배포를 위한 모델 고정](#pin-models-for-third-party-deployments)에 설명된 별칭 전용 일치에 대한 예외입니다. 설정은 여전히 선택기를 나열된 항목으로 제한하므로 표준 별칭과 함께 모든 Mantle ID를 포함합니다.191[Bedrock Mantle 엔드포인트](/ko/amazon-bedrock#use-the-mantle-endpoint)가 활성화되면 `availableModels`의 `anthropic.`으로 시작하는 항목이 `/model` 선택기에 사용자 정의 옵션으로 추가되고 Mantle 엔드포인트로 라우팅됩니다. 설정은 여전히 선택기를 나열된 항목으로 제한하므로 표준 별칭과 함께 모든 Mantle ID를 포함합니다.

157 192 

158<h2 id="special-model-behavior">193<h2 id="special-model-behavior">

159 특수 모델 동작194 특수 모델 동작


172 207 

173Enterprise 종량제는 구독 시트가 아닌 사용량으로 청구되는 Enterprise 조직을 의미합니다.208Enterprise 종량제는 구독 시트가 아닌 사용량으로 청구되는 Enterprise 조직을 의미합니다.

174 209 

175Claude Code는 Opus의 사용 임계값에 도달하면 자동으로 Sonnet으로 폴백할있습니다.210Fable 5는 어떤 계정 유형에서도 기본 모델이 아닙니다. 세션은 `/model fable`, `model` 설정 또는 Fable 5를 사용할 있는 `best` 별칭으로 선택한 후에만 Fable 5를 사용합니다. `/model`로 선택하면 사용자 설정에서 선택된 모델로 저장되므로 모델을 변경할 때까지 이후 세션이 Fable 5에서 시작됩니다.

176 211 

177<h3 id="opusplan-model-setting">212<h3 id="opusplan-model-setting">

178 `opusplan` 모델 설정213 `opusplan` 모델 설정


185 220 

186이는 계획을 위한 Opus의 우수한 추론과 실행을 위한 Sonnet의 효율성이라는 두 가지 장점을 모두 제공합니다.221이는 계획을 위한 Opus의 우수한 추론과 실행을 위한 Sonnet의 효율성이라는 두 가지 장점을 모두 제공합니다.

187 222 

188Plan Mode Opus 단계는 표준 200K 컨텍스트 윈도우로 실행됩니다. [확장 컨텍스트](#extended-context) 설명된 자동 1M 업그레이드는 `opus` 모델 설정에 적용되며 `opusplan`으로 확장되지 않습니다.223Plan Mode Opus 단계는 `opus` 모델 설정과 동일한 컨텍스트 윈도우를 사용합니다. Opus가 [자동으로 1M 컨텍스트로 업그레이드](#extended-context)되는 구독 계층에서 `opusplan`은 Plan Mode에서도 업그레이드를 받습니다. 자동 업그레이드 계층이 아닌 경우 단계 모두에 1M 컨텍스트를 강제하려면 모델을 `opusplan[1m]`으로 설정합니다.

224 

225[`availableModels`](#restrict-model-selection)이 Opus를 제외할 때 `opusplan`은 전환하는 대신 Plan Mode에서 Sonnet에 유지됩니다. 마찬가지로 Sonnet이 제외될 때 일반적으로 Plan Mode에서 Sonnet으로 업그레이드되는 Haiku 세션도 Haiku에 유지됩니다.

226 

227Claude가 Plan 경계에서 전환하는 대신 작업 중간에 두 번째 모델을 참고할 시기를 결정하는 하이브리드 접근 방식은 [advisor tool](/ko/advisor)을 참조하세요.

228 

229<h3 id="fallback-model-chains">

230 폴백 모델 체인

231</h3>

232 

233주 모델이 과부하 상태이거나 사용할 수 없거나 다른 재시도 불가능한 서버 오류를 반환할 때 Claude Code는 요청이 실패하는 대신 폴백 모델로 전환할 수 있습니다. 인증, 청구, 속도 제한, 요청 크기 및 전송 오류는 절대 전환을 트리거하지 않습니다. 이들은 정상적인 재시도 및 오류 처리를 따릅니다.

234 

235하나 이상의 폴백 모델을 구성하고 Claude Code는 순서대로 시도하며 전환할 때 알림을 표시합니다. 전환은 현재 턴에만 지속되므로 다음 메시지는 주 모델을 먼저 다시 시도합니다. 체인은 중복 제거 후 3개 모델로 제한되며 추가 항목은 무시됩니다.

236 

237`--fallback-model` 플래그로 한 세션에 대한 체인을 설정합니다. 이 플래그는 쉼표로 구분된 목록을 허용합니다:

238 

239```bash theme={null}

240claude --fallback-model sonnet,haiku

241```

242 

243세션 전체에 체인을 유지하려면 [settings](/ko/settings)에서 `fallbackModel`을 배열로 설정합니다:

244 

245```json theme={null}

246{

247 "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]

248}

249```

250 

251`--fallback-model` 플래그는 `fallbackModel` 설정보다 우선합니다. 각 요소는 모델 이름 또는 별칭을 허용하며 `"default"`는 기본 모델로 확장됩니다.

252 

253두 가지 경우로 인해 요소가 건너뛰어집니다:

254 

255* **사용할 수 없는 모델**: 설정에 고정된 폐기된 모델과 같이 도달할 수 없는 모델은 건너뛰어지고 Claude Code는 다음 요소로 계속됩니다.

256* **허용 목록 외**: [`availableModels`](#restrict-model-selection)에서 허용되지 않는 요소는 체인을 읽을 때 삭제되고 시도되지 않습니다.

257 

258<h3 id="automatic-model-fallback">

259 자동 모델 폴백

260</h3>

261 

262이 섹션은 Fable 5의 콘텐츠 기반 폴백을 다룹니다. 모델이 과부하 상태이거나 사용할 수 없을 때의 가용성 기반 폴백은 [폴백 모델 체인](#fallback-model-chains)을 참조하세요.

263 

264Fable 5는 사이버 보안 및 생물학 콘텐츠에 대한 안전 분류기로 실행됩니다. 분류기가 요청에 플래그를 지정하면 Claude Code는 해당 요청을 기본 Opus 모델에서 다시 실행하고 트랜스크립트에 알림을 표시합니다: Anthropic API 및 [LLM gateway](/ko/llm-gateway) 배포의 경우 Opus 4.8, 또는 [Claude Platform on AWS](/ko/claude-platform-on-aws)의 경우 Opus 4.7.

265 

266세션은 그 Opus 모델에서 계속됩니다. Fable 5로 돌아가려면 `/model fable`을 실행합니다.

267 

268<h4 id="check-what-triggered-fallback">

269 폴백을 트리거한 것 확인

270</h4>

271 

272폴백은 세션의 첫 번째 요청에서 트리거될 수 있습니다. 이는 첫 번째 요청이 CLAUDE.md 콘텐츠 및 git 상태와 같은 워크스페이스 컨텍스트를 전달하기 때문입니다. 보안 또는 생물학 자료를 포함하는 저장소는 해당 컨텍스트만으로도 분류기를 트리거할 수 있습니다.

273 

274사용자 정의가 트리거인지 확인하려면 `claude --safe-mode`로 세션을 시작합니다. 이는 CLAUDE.md, skills, MCP servers 및 hooks와 같은 사용자 정의를 비활성화합니다. Git 상태 및 디렉토리 이름은 사용자 정의가 아니며 여전히 포함됩니다.

275 

276<h4 id="ask-before-switching">

277 전환하기 전에 묻기

278</h4>

279 

280요청에 플래그가 지정될 때마다 자동으로 전환하는 대신 어떤 일이 발생할지 결정하려면 `/config`를 실행하고 "메시지에 플래그가 지정되면 모델 전환"을 끕니다. 플래그가 지정된 요청은 두 가지 옵션으로 세션을 일시 중지합니다: Opus 모델로 전환하거나 프롬프트를 편집하고 Fable 5에서 다시 시도합니다.

281 

282일부 경우는 다르게 동작합니다:

283 

284* 두 모델이 동일한 요청에 플래그를 지정하면 프롬프트를 편집하고 다시 시도하거나 새 세션을 시작할 수 있습니다.

285* 모바일 [Claude Code on the web](/ko/claude-code-on-the-web) 세션에서는 편집 및 재시도가 지원되지 않습니다. 모델을 전환하거나 데스크톱 브라우저 또는 데스크톱 앱에서 세션을 계속합니다.

286* [비대화형 모드](/ko/cli-reference#cli-flags) 및 프롬프트를 표시할 수 없는 SDK 통합에서 플래그가 지정된 요청은 거부로 턴을 종료합니다.

287 

288<h4 id="enable-fallback-on-bedrock-vertex-ai-and-foundry">

289 Bedrock, Vertex AI 및 Foundry에서 폴백 활성화

290</h4>

291 

292[Amazon Bedrock](/ko/amazon-bedrock), [Google Vertex AI](/ko/google-vertex-ai) 및 [Microsoft Foundry](/ko/microsoft-foundry)에서 모델 ID는 공급자별로 다르므로 자동 폴백은 Claude Code가 관련된 두 모델을 식별할 수 있을 때만 작동합니다:

293 

294* Claude Code는 현재 모델을 Fable 5로 인식해야 합니다: 모델 ID에 `claude-fable-5`가 포함되거나 `ANTHROPIC_DEFAULT_FABLE_MODEL`의 값과 일치하거나 [`modelOverrides`](#override-model-ids-per-version)로 매핑됩니다.

295* 폴백 대상은 Opus 모델로 확인되어야 합니다: `ANTHROPIC_DEFAULT_OPUS_MODEL`의 값(설정된 경우) 또는 공급자의 모델 목록의 Opus 4.8 항목입니다.

296 

297모델을 식별할 수 없으면 Claude Code는 자동으로 전환하지 않습니다. 플래그가 지정된 요청은 거부 메시지로 종료되며 [`/model`](#setting-your-model)로 모델을 전환하고 다시 시도할 수 있습니다. 이러한 공급자에서 자동 폴백을 활성화하려면 `ANTHROPIC_DEFAULT_FABLE_MODEL`을 Fable 5 모델 ID로 설정하고 `ANTHROPIC_DEFAULT_OPUS_MODEL`을 Opus 4.8 모델 ID로 설정합니다.

298 

299<h4 id="security-research-and-biology-workloads">

300 보안 연구 및 생물학 워크로드

301</h4>

302 

303공격적인 보안 또는 생물학의 워크로드(침투 테스트, Capture the Flag(CTF) 연습 및 생물학 인접 코드베이스 포함)는 자주 폴백을 트리거하며 종종 첫 번째 요청에서 트리거됩니다. 실질적인 생물학 작업의 경우 거의 모든 요청이 재라우팅될 것으로 예상합니다.

304 

305이는 이러한 도메인에 대한 예상 라우팅이며 계정 플래그가 아닙니다. 조직이 이 작업을 위해 Fable 클래스 기능이 필요한 경우 신뢰할 수 있는 액세스 프로그램에 대해 Anthropic 계정 팀에 문의하세요.

189 306 

190<h3 id="adjust-effort-level">307<h3 id="adjust-effort-level">

191 노력 수준 조정308 노력 수준 조정


197 314 

198| 모델 | 수준 |315| 모델 | 수준 |

199| :-------------------- | :-------------------------------------- |316| :-------------------- | :-------------------------------------- |

317| Fable 5 | `low`, `medium`, `high`, `xhigh`, `max` |

200| Opus 4.8 및 Opus 4.7 | `low`, `medium`, `high`, `xhigh`, `max` |318| Opus 4.8 및 Opus 4.7 | `low`, `medium`, `high`, `xhigh`, `max` |

201| Opus 4.6 및 Sonnet 4.6 | `low`, `medium`, `high`, `max` |319| Opus 4.6 및 Sonnet 4.6 | `low`, `medium`, `high`, `max` |

202 320 

203활성 모델이 지원하지 않는 수준을 설정하면 Claude Code는 설정한 수준 이하의 가장 높은 지원 수준으로 폴백합니다. 예를 들어 `xhigh`는 Opus 4.6에서 `high`로 실행됩니다.321활성 모델이 지원하지 않는 수준을 설정하면 Claude Code는 설정한 수준 이하의 가장 높은 지원 수준으로 폴백합니다. 예를 들어 `xhigh`는 Opus 4.6에서 `high`로 실행됩니다.

204 322 

205기본 노력은 Opus 4.8, Opus 4.6 및 Sonnet 4.6에서 `high`이고 Opus 4.7에서 `xhigh`입니다.323기본 노력은 Fable 5, Opus 4.8, Opus 4.6 및 Sonnet 4.6에서 `high`이고 Opus 4.7에서 `xhigh`입니다.

206 324 

207Opus 4.8 또는 Opus 4.7을 처음 실행할 때 Claude Code는 이전에 다른 모델에 대해 다른 수준을 설정했더라도 해당 모델의 기본 노력을 적용합니다: Opus 4.8에서 `high`, Opus 4.7에서 `xhigh`. 전환 후 다른 수준을 선택하려면 `/effort`를 다시 실행하세요.325Fable 5, Opus 4.8 또는 Opus 4.7을 처음 실행할 때 Claude Code는 이전에 다른 모델에 대해 다른 수준을 설정했더라도 해당 모델의 기본 노력을 적용합니다: Fable 5 및 Opus 4.8에서 `high`, Opus 4.7에서 `xhigh`. 전환 후 다른 수준을 선택하려면 `/effort`를 다시 실행하세요.

208 326 

209`low`, `medium`, `high` 및 `xhigh`는 세션 전체에 유지됩니다. `max`는 토큰 지출에 제약이 없어 가장 깊은 추론을 제공하며 현재 세션에만 적용됩니다. 단, `CLAUDE_CODE_EFFORT_LEVEL` 환경 변수를 통해 설정된 경우는 예외입니다.327`low`, `medium`, `high` 및 `xhigh`는 세션 전체에 유지됩니다. `max`는 토큰 지출에 제약이 없어 가장 깊은 추론을 제공하며 현재 세션에만 적용됩니다. 단, `CLAUDE_CODE_EFFORT_LEVEL` 환경 변수를 통해 설정된 경우는 예외입니다.

210 328 


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

221| `low` | 지능 민감도가 낮은 짧고 범위가 지정된 지연 시간 민감 작업을 위해 예약 |339| `low` | 지능 민감도가 낮은 짧고 범위가 지정된 지연 시간 민감 작업을 위해 예약 |

222| `medium` | 일부 지능을 절충할 수 있는 비용 민감 작업의 토큰 사용량 감소 |340| `medium` | 일부 지능을 절충할 수 있는 비용 민감 작업의 토큰 사용량 감소 |

223| `high` | 토큰 사용량과 지능의 균형을 맞춥니다. Opus 4.8, Opus 4.6 및 Sonnet 4.6의 기본값 |341| `high` | 토큰 사용량과 지능의 균형을 맞춥니다. Fable 5, Opus 4.8, Opus 4.6 및 Sonnet 4.6의 기본값 |

224| `xhigh` | 더 높은 토큰 지출로 더 깊은 추론. Opus 4.7의 기본값 |342| `xhigh` | 더 높은 토큰 지출로 더 깊은 추론. Opus 4.7의 기본값 |

225| `max` | 까다로운 작업의 성능을 개선할 수 있지만 수익 감소를 보일 수 있으며 과도한 생각에 취약합니다. 광범위하게 채택하기 전에 테스트하세요 |343| `max` | 까다로운 작업의 성능을 개선할 수 있지만 수익 감소를 보일 수 있으며 과도한 생각에 취약합니다. 광범위하게 채택하기 전에 테스트하세요 |

226| `ultracode` | 각 실질적인 작업에 대해 `xhigh` 메시지별 추론으로 [동적 워크플로우](/ko/workflows)를 계획하는 Claude Code 설정입니다. 세션 전용 |344| `ultracode` | 각 실질적인 작업에 대해 `xhigh` 메시지별 추론으로 [동적 워크플로우](/ko/workflows)를 계획하는 Claude Code 설정입니다. 세션 전용 |


256 374 

257적응형 추론은 각 단계에서 사고를 선택 사항으로 만들므로 Claude는 일상적인 프롬프트에 더 빠르게 응답하고 이점을 얻는 단계를 위해 더 깊은 사고를 예약할 수 있습니다. Claude가 현재 수준이 생성하는 것보다 더 자주 또는 덜 자주 생각하기를 원하면 프롬프트 또는 `CLAUDE.md`에서 직접 말할 수 있습니다. 모델은 노력 설정 내에서 해당 지침에 응답합니다.375적응형 추론은 각 단계에서 사고를 선택 사항으로 만들므로 Claude는 일상적인 프롬프트에 더 빠르게 응답하고 이점을 얻는 단계를 위해 더 깊은 사고를 예약할 수 있습니다. Claude가 현재 수준이 생성하는 것보다 더 자주 또는 덜 자주 생각하기를 원하면 프롬프트 또는 `CLAUDE.md`에서 직접 말할 수 있습니다. 모델은 노력 설정 내에서 해당 지침에 응답합니다.

258 376 

259Opus 4.7 이상은 항상 적응형 추론을 사용합니다. 고정 사고 예산 모드 및 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`은 이에 적용되지 않습니다.377Opus 4.7 이상은 항상 적응형 추론을 사용합니다. Fable 5도 마찬가지입니다. 고정 사고 예산 모드 및 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`은 이에 적용되지 않습니다.

260 378 

261Opus 4.6 및 Sonnet 4.6에서 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`을 설정하여 `MAX_THINKING_TOKENS`로 제어되는 이전의 고정 사고 예산으로 되돌릴 수 있습니다. [환경 변수](/ko/env-vars)를 참조하세요.379Opus 4.6 및 Sonnet 4.6에서 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`을 설정하여 `MAX_THINKING_TOKENS`로 제어되는 이전의 고정 사고 예산으로 되돌릴 수 있습니다. [환경 변수](/ko/env-vars)를 참조하세요.

262 380 


267확장 사고는 Claude가 응답하기 전에 내보내는 추론입니다. [적응형 추론](#adjust-effort-level)을 지원하는 모델에서 노력 수준은 얼마나 많은 사고가 발생하는지에 대한 주요 제어입니다. 아래 설정은 사고를 켜거나 끄고 표시 방식을 제어합니다.385확장 사고는 Claude가 응답하기 전에 내보내는 추론입니다. [적응형 추론](#adjust-effort-level)을 지원하는 모델에서 노력 수준은 얼마나 많은 사고가 발생하는지에 대한 주요 제어입니다. 아래 설정은 사고를 켜거나 끄고 표시 방식을 제어합니다.

268 386 

269| 제어 | 설정 방법 |387| 제어 | 설정 방법 |

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

271| 현재 세션에 대한 토글 | macOS에서 `Option+T` 또는 Windows 및 Linux에서 `Alt+T`를 누릅니다 |389| 현재 세션에 대한 토글 | macOS에서 `Option+T` 또는 Windows 및 Linux에서 `Alt+T`를 누릅니다 |

272| 전역 기본값 설정 | `/config`를 실행하고 사고 모드를 토글합니다. `~/.claude/settings.json`에 `alwaysThinkingEnabled`로 저장됩니다 |390| 전역 기본값 설정 | `/config`를 실행하고 사고 모드를 토글합니다. `~/.claude/settings.json`에 `alwaysThinkingEnabled`로 저장됩니다 |

273| 노력에 관계없이 비활성화 | [`MAX_THINKING_TOKENS=0`](/ko/env-vars)을 설정합니다. 다른 값은 [고정 사고 예산](#adaptive-reasoning-and-fixed-thinking-budgets)에만 적용됩니다 |391| 노력에 관계없이 비활성화 | [`MAX_THINKING_TOKENS=0`](/ko/env-vars)을 설정합니다. 이는 Fable 5를 제외한 Anthropic API에서 사고를 끕니다. [타사 공급자](/ko/third-party-integrations)에서 이는 `thinking` 매개변수를 대신 생략하며 적응형 추론 모델은 여전히 생각할 수 있습니다. 다른 값은 [고정 사고 예산](#adaptive-reasoning-and-fixed-thinking-budgets)에만 적용됩니다 |

392 

393Fable 5에서는 사고를 끌 수 없습니다. 세션 토글, `alwaysThinkingEnabled` 및 `MAX_THINKING_TOKENS=0`은 여기서 효과가 없으며 Fable 5는 노력 수준에 따라 단계별로 얼마나 생각할지 결정합니다.

274 394 

275사고 출력은 기본적으로 축소됩니다. `Ctrl+O`를 눌러 자세한 모드를 토글하고 추론을 회색 기울임꼴 텍스트로 봅니다. Anthropic API의 대화형 세션은 기본적으로 편집된 사고 블록을 수신하므로 확장할 때 전체 요약을 사용할 수 있도록 하려면 [설정](/ko/settings)에서 `showThinkingSummaries: true`를 설정하세요. 축소되거나 편집된 경우에도 생성된 모든 사고 토큰에 대해 요금이 청구됩니다.395사고 출력은 기본적으로 축소됩니다. `Ctrl+O`를 눌러 자세한 모드를 토글하고 추론을 회색 기울임꼴 텍스트로 봅니다. Anthropic API의 대화형 세션은 기본적으로 편집된 사고 블록을 수신하므로 확장할 때 전체 요약을 사용할 수 있도록 하려면 [설정](/ko/settings)에서 `showThinkingSummaries: true`를 설정하세요. 축소되거나 편집된 경우에도 생성된 모든 사고 토큰에 대해 요금이 청구됩니다.

276 396 


278 확장 컨텍스트398 확장 컨텍스트

279</h3>399</h3>

280 400 

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

282 402 

283가용성은 모델 및 플랜에 따라 다릅니다. 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)이 필요합니다.403가용성은 모델 및 플랜에 따라 다릅니다. Max, Team 및 Enterprise 플랜에서 Opus는 추가 구성 없이 자동으로 1M 컨텍스트로 업그레이드됩니다. 이는 Team Standard 및 Team Premium 시트 모두에 적용됩니다. Anthropic API에서 Fable 5, Opus 4.8 및 Opus 4.7은 항상 1M 윈도우로 실행됩니다. 1M 컨텍스트를 사용하는 Sonnet은 자동 업그레이드의 일부가 아니며 Max를 포함한 모든 구독 플랜에서 [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)이 필요합니다.

284 404 

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

286| ---------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |406| ---------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |


340 460 

341| 환경 변수 | 설명 |461| 환경 변수 | 설명 |

342| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |462| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

463| `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable`에 사용할 모델이며, Claude Code가 [자동 모델 폴백](#automatic-model-fallback)을 위해 타사 제공자에서 Fable 5로 인식하는 모델 ID입니다. |

343| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus`에 사용할 모델 또는 Plan Mode가 활성화되었을 때 `opusplan`에 사용할 모델입니다. |464| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus`에 사용할 모델 또는 Plan Mode가 활성화되었을 때 `opusplan`에 사용할 모델입니다. |

344| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet`에 사용할 모델 또는 Plan Mode가 활성화되지 않았을 때 `opusplan`에 사용할 모델입니다. |465| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet`에 사용할 모델 또는 Plan Mode가 활성화되지 않았을 때 `opusplan`에 사용할 모델입니다. |

345| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku`에 사용할 모델 또는 [백그라운드 기능](/ko/costs#background-token-usage)입니다. |466| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku`에 사용할 모델 또는 [백그라운드 기능](/ko/costs#background-token-usage)입니다. |


353 474 

354[Bedrock](/ko/amazon-bedrock), [Vertex AI](/ko/google-vertex-ai), [Foundry](/ko/microsoft-foundry) 또는 [Claude Platform on AWS](/ko/claude-platform-on-aws)를 통해 Claude Code를 배포할 때 사용자에게 롤아웃하기 전에 모델 버전을 고정합니다.475[Bedrock](/ko/amazon-bedrock), [Vertex AI](/ko/google-vertex-ai), [Foundry](/ko/microsoft-foundry) 또는 [Claude Platform on AWS](/ko/claude-platform-on-aws)를 통해 Claude Code를 배포할 때 사용자에게 롤아웃하기 전에 모델 버전을 고정합니다.

355 476 

356고정하지 않으면 Claude Code는 최신 버전으로 확인되는 모델 별칭(`sonnet`, `opus`, `haiku`)을 사용합니다. Anthropic이 모델을 출시할 버전이 아직 사용자 계정에서 활성화되지 않으면 Bedrock 및 Vertex AI 사용자는 공지를 보고 해당 세션에 대해 이전 버전으로 폴백되며, Foundry 사용자는 Foundry에 동등한 시작 확인이 없기 때문에 오류를 봅니다.477고정하지 않으면 Claude Code는 `fable`, `opus`, `sonnet`, `haiku` 같은 모델 별칭을 사용하며, 이는 각 제공자에 대한 기본 제공 기본 모델 ID로 확인됩니다. 해당 기본값은 최신 Anthropic 릴리스보다 뒤떨어질 있으며, 가리키는 모델이 사용자 계정에서 아직 활성화되지 않았을 수 있습니다. 기본값을 사용할 수 없으면 Bedrock 및 Vertex AI 사용자는 공지를 보고 해당 세션에 대해 이전 버전으로 폴백되며, Foundry 사용자는 Foundry에 동등한 시작 확인이 없기 때문에 오류를 봅니다.

357 478 

358<Warning>479<Warning>

359 초기 설정의 일부로 세 가지 모델 환경 변수를 모두 특정 버전 ID로 설정합니다. 고정하면 사용자가 새 모델로 이동할 시기를 제어할 수 있습니다.480 초기 설정의 일부로 모델 환경 변수를 특정 버전 ID로 설정합니다. 고정하면 사용자가 새 모델로 이동할 시기를 제어할 수 있습니다.

360</Warning>481</Warning>

361 482 

362제공자에 대한 버전별 모델 ID와 함께 다음 환경 변수를 사용합니다:483제공자에 대한 버전별 모델 ID와 함께 다음 환경 변수를 사용합니다:


367| Vertex AI | `export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'` |488| Vertex AI | `export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'` |

368| Foundry | `export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'` |489| Foundry | `export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'` |

369 490 

370`ANTHROPIC_DEFAULT_SONNET_MODEL` `ANTHROPIC_DEFAULT_HAIKU_MODEL`에 대해 동일한 패턴을 적용합니다. 모든 제공자의 현재 및 레거시 모델 ID는 [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview)를 참조하세요. 사용자를 새 모델 버전으로 업그레이드하려면 이러한 환경 변수를 업데이트하고 다시 배포합니다.491`ANTHROPIC_DEFAULT_FABLE_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`에 대해 동일한 패턴을 적용합니다. 모든 제공자의 현재 및 레거시 모델 ID는 [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview)를 참조하세요. 사용자를 새 모델 버전으로 업그레이드하려면 이러한 환경 변수를 업데이트하고 다시 배포합니다.

371 492 

372고정된 모델에 대해 [확장 컨텍스트](#extended-context)를 활성화하려면 `ANTHROPIC_DEFAULT_OPUS_MODEL` 또는 `ANTHROPIC_DEFAULT_SONNET_MODEL`의 모델 ID에 `[1m]`을 추가합니다:493고정된 모델에 대해 [확장 컨텍스트](#extended-context)를 활성화하려면 `ANTHROPIC_DEFAULT_OPUS_MODEL` 또는 `ANTHROPIC_DEFAULT_SONNET_MODEL`의 모델 ID에 `[1m]`을 추가합니다:

373 494 


375export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8[1m]'496export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8[1m]'

376```497```

377 498 

378`[1m]` 접미사는 `opus` 및 `sonnet` 별칭의 모든 사용에 1M 컨텍스트 윈도우를 적용합니다. 이는 `opusplan`의 plan-mode Opus 단계를 확장하지 않으며, 이는 [200K에서 제한된 상태로 유지됩니다](#opusplan-model-setting).499`[1m]` 접미사는 `opus` 및 `sonnet` 별칭의 모든 사용에 1M 컨텍스트 윈도우를 적용합니다. 이는 [`opusplan`](#opusplan-model-setting)의 plan-mode Opus 단계를 포함합니다.

379 500 

380* Claude Code는 모델 ID를 제공자에게 보내기 전에 접미사를 제거합니다.501* Claude Code는 모델 ID를 제공자에게 보내기 전에 접미사를 제거합니다.

381* 기본 모델이 1M 컨텍스트를 [지원할 때만](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) `[1m]`을 추가합니다.502* 기본 모델이 1M 컨텍스트를 [지원할 때만](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) `[1m]`을 추가합니다.

382* 접미사는 모델별이 아닌 변수별로 읽혀집니다. Bedrock, Vertex 및 Foundry에서 한 변수의 `[1m]` 없는 모델 ID는 다른 변수가 접미사와 함께 동일한 모델을 설정하더라도 200K 컨텍스트를 사용합니다.503* 접미사는 모델별이 아닌 변수별로 읽혀집니다. Bedrock, Vertex 및 Foundry에서 한 변수의 `[1m]` 없는 모델 ID는 다른 변수가 접미사와 함께 동일한 모델을 설정하더라도 200K 컨텍스트를 사용합니다.

383 504 

384<Note>505<Note>

385 `settings.availableModels` 허용 목록은 타사 제공자를 사용할 때도 적용됩니다. 필터링은 제공자별 모델 ID가 아닌 모델 별칭(`opus`, `sonnet`, `haiku`) 일치합니다.506 `settings.availableModels` 허용 목록은 타사 제공자를 사용할 때도 적용됩니다. 필터링은 `opus`, 버전 접두사(예: `claude-opus-4-8`) 또는 전체 모델 ID와 같은 모델 별칭과 일치합니다. 모든 `[1m]` 접미사는 허용 목록 항목과 요청된 모델 모두에서 제거되므로 `claude-opus-4-8` 항목은 표준 및 1M 컨텍스트 Opus 행을 모두 허용합니다. `us.anthropic.` 같은 제공자별 접두사는 제거되지 않습니다. 선택기가 표시하는 것과 동일한 형식을 `availableModels`에 나열하거나 [`modelOverrides`](#override-model-ids-per-version) 통해 매핑합니다.

386</Note>507</Note>

387 508 

388<h3 id="customize-pinned-model-display-and-capabilities">509<h3 id="customize-pinned-model-display-and-capabilities">


399| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | `/model` 선택기에서 고정된 Opus 모델의 표시 설명입니다. 설정되지 않으면 `Custom Opus model`로 기본값 설정됩니다. |520| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | `/model` 선택기에서 고정된 Opus 모델의 표시 설명입니다. 설정되지 않으면 `Custom Opus model`로 기본값 설정됩니다. |

400| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 고정된 Opus 모델이 지원하는 기능의 쉼표로 구분된 목록입니다. |521| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 고정된 Opus 모델이 지원하는 기능의 쉼표로 구분된 목록입니다. |

401 522 

402동일한 `_NAME`, `_DESCRIPTION` 및 `_SUPPORTED_CAPABILITIES` 접미사는 `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL` 및 `ANTHROPIC_CUSTOM_MODEL_OPTION`에 사용 가능합니다.523동일한 `_NAME`, `_DESCRIPTION` 및 `_SUPPORTED_CAPABILITIES` 접미사는 `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `ANTHROPIC_DEFAULT_FABLE_MODEL` 및 `ANTHROPIC_CUSTOM_MODEL_OPTION`에 사용 가능합니다.

403 524 

404Claude Code는 모델 ID를 알려진 패턴과 비교하여 [노력 수준](#adjust-effort-level) 및 [확장 사고](#extended-thinking)와 같은 기능을 활성화합니다. Bedrock ARN 또는 사용자 정의 배포 이름과 같은 제공자별 ID는 종종 이러한 패턴과 일치하지 않아 지원되는 기능이 비활성화됩니다. `_SUPPORTED_CAPABILITIES`를 설정하여 Claude Code에 모델이 실제로 지원하는 기능을 알립니다:525Claude Code는 모델 ID를 알려진 패턴과 비교하여 [노력 수준](#adjust-effort-level) 및 [확장 사고](#extended-thinking)와 같은 기능을 활성화합니다. Bedrock ARN 또는 사용자 정의 배포 이름과 같은 제공자별 ID는 종종 이러한 패턴과 일치하지 않아 지원되는 기능이 비활성화됩니다. `_SUPPORTED_CAPABILITIES`를 설정하여 Claude Code에 모델이 실제로 지원하는 기능을 알립니다:

405 526 


427 버전별 모델 ID 재정의548 버전별 모델 ID 재정의

428</h3>549</h3>

429 550 

430위의 패밀리 수준 환경 변수는 패밀리 별칭당 하나의 모델 ID를 구성합니다. 동일한 패밀리 내의 여러 버전을 서로 다른 제공자 ID에 매핑해야 하는 경우 대신 `modelOverrides` 설정을 사용합니다.551패밀리 수준 환경 변수는 패밀리 별칭당 하나의 모델 ID를 구성합니다. 동일한 패밀리 내의 여러 버전을 서로 다른 제공자 ID에 매핑해야 하는 경우 대신 `modelOverrides` 설정을 사용합니다.

431 552 

432`modelOverrides`는 개별 Anthropic 모델 ID를 Claude Code가 제공자의 API에 보내는 제공자별 문자열에 매핑합니다. 사용자가 `/model` 선택기에서 매핑된 모델을 선택하면 Claude Code는 기본 제공 기본값 대신 구성된 값을 사용합니다.553`modelOverrides`는 개별 Anthropic 모델 ID를 Claude Code가 제공자의 API에 보내는 제공자별 문자열에 매핑합니다. 사용자가 `/model` 선택기에서 매핑된 모델을 선택하면 Claude Code는 기본 제공 기본값 대신 구성된 값을 사용합니다.

433 554 


463| `DISABLE_PROMPT_CACHING_HAIKU` | Haiku 모델에 대해서만 prompt caching을 비활성화하려면 `1`로 설정합니다. |584| `DISABLE_PROMPT_CACHING_HAIKU` | Haiku 모델에 대해서만 prompt caching을 비활성화하려면 `1`로 설정합니다. |

464| `DISABLE_PROMPT_CACHING_SONNET` | Sonnet 모델에 대해서만 prompt caching을 비활성화하려면 `1`로 설정합니다. |585| `DISABLE_PROMPT_CACHING_SONNET` | Sonnet 모델에 대해서만 prompt caching을 비활성화하려면 `1`로 설정합니다. |

465| `DISABLE_PROMPT_CACHING_OPUS` | Opus 모델에 대해서만 prompt caching을 비활성화하려면 `1`로 설정합니다. |586| `DISABLE_PROMPT_CACHING_OPUS` | Opus 모델에 대해서만 prompt caching을 비활성화하려면 `1`로 설정합니다. |

587| `DISABLE_PROMPT_CACHING_FABLE` | Fable 모델에 대해서만 prompt caching을 비활성화하려면 `1`로 설정합니다. |

466 588 

467캐시 TTL을 변경하거나 캐시 미스를 트리거하는 것이 무엇인지 알아보려면 [Claude Code가 prompt caching을 사용하는 방법](/ko/prompt-caching)을 참조하세요.589캐시 TTL을 변경하거나 캐시 미스를 트리거하는 것이 무엇인지 알아보려면 [Claude Code가 prompt caching을 사용하는 방법](/ko/prompt-caching)을 참조하세요.

Details

221**`claude_code.tool`**221**`claude_code.tool`**

222 222 

223| 속성 | 설명 | 게이트 대상 |223| 속성 | 설명 | 게이트 대상 |

224| ----------------- | ---------------------------------------------- | ----------------------- |224| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |

225| `tool_name` | 도구 이름 | |225| `tool_name` | 도구 이름 | |

226| `duration_ms` | 권한 대기 및 실행을 포함한 벽시계 지속 시간 | |226| `duration_ms` | 권한 대기 및 실행을 포함한 벽시계 지속 시간 | |

227| `result_tokens` | 도구 결과의 대략적인 토큰 크기 | |227| `result_tokens` | 도구 결과의 대략적인 토큰 크기 | |

228| `agent_id` | 도구를 실행한 하위 에이전트 또는 팀원의 식별자. 주 세션에는 없음 | |228| `agent_id` | 도구를 실행한 하위 에이전트 또는 팀원의 식별자. 주 세션에는 없음 | |

229| `parent_agent_id` | 이 에이전트를 생성한 에이전트의 식별자. 주 세션 및 직접 생성된 에이전트에는 없음 | |229| `parent_agent_id` | 이 에이전트를 생성한 에이전트의 식별자. 주 세션 및 직접 생성된 에이전트에는 없음 | |

230| `tool_use_id` | 이 호출에 대한 모델의 `tool_use` 블록 ID. [tool\_result](#tool-result-event) 및 [tool\_decision](#tool-decision-event) 이벤트의 `tool_use_id`와 훅 페이로드의 `tool_use_id`와 일치하므로 스팬을 해당 레코드에 조인할 수 있습니다 | |

231| `gen_ai.tool.call.id` | `tool_use_id`와 동일한 값. OpenTelemetry GenAI 의미론적 규칙 | |

230| `file_path` | Read, Edit 및 Write 도구의 대상 파일 경로 | `OTEL_LOG_TOOL_DETAILS` |232| `file_path` | Read, Edit 및 Write 도구의 대상 파일 경로 | `OTEL_LOG_TOOL_DETAILS` |

231| `full_command` | Bash 도구의 명령 문자열 | `OTEL_LOG_TOOL_DETAILS` |233| `full_command` | Bash 도구의 명령 문자열 | `OTEL_LOG_TOOL_DETAILS` |

232| `skill_name` | Skill 도구의 스킬 이름 | `OTEL_LOG_TOOL_DETAILS` |234| `skill_name` | Skill 도구의 스킬 이름 | `OTEL_LOG_TOOL_DETAILS` |


245**`claude_code.tool.execution`**247**`claude_code.tool.execution`**

246 248 

247| 속성 | 설명 | 게이트 대상 |249| 속성 | 설명 | 게이트 대상 |

248| ------------- | ------------------------------------------------------------------------------------ | ----------------------- |250| --------------------- | ------------------------------------------------------------------------------------ | ----------------------- |

249| `duration_ms` | 도구 본문 실행 시간 | |251| `duration_ms` | 도구 본문 실행 시간 | |

252| `tool_use_id` | 부모 `claude_code.tool` 스팬과 동일한 값 | |

253| `gen_ai.tool.call.id` | `tool_use_id`와 동일한 값. OpenTelemetry GenAI 의미론적 규칙 | |

250| `success` | `true` 또는 `false` | |254| `success` | `true` 또는 `false` | |

251| `error` | 실행이 실패했을 때 오류 범주 문자열 (예: `Error:ENOENT` 또는 `ShellError`). 게이트가 설정되면 전체 오류 메시지를 포함합니다 | `OTEL_LOG_TOOL_DETAILS` |255| `error` | 실행이 실패했을 때 오류 범주 문자열 (예: `Error:ENOENT` 또는 `ShellError`). 게이트가 설정되면 전체 오류 메시지를 포함합니다 | `OTEL_LOG_TOOL_DETAILS` |

252 256 


423모든 메트릭 및 이벤트는 다음 표준 속성을 공유합니다:427모든 메트릭 및 이벤트는 다음 표준 속성을 공유합니다:

424 428 

425| 속성 | 설명 | 제어 대상 |429| 속성 | 설명 | 제어 대상 |

426| ----------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |430| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |

427| `session.id` | 고유 세션 식별자 | `OTEL_METRICS_INCLUDE_SESSION_ID` (기본값: true) |431| `session.id` | 고유 세션 식별자 | `OTEL_METRICS_INCLUDE_SESSION_ID` (기본값: true) |

428| `app.version` | 현재 Claude Code 버전 | `OTEL_METRICS_INCLUDE_VERSION` (기본값: false) |432| `app.version` | 현재 Claude Code 버전 | `OTEL_METRICS_INCLUDE_VERSION` (기본값: false) |

429| `app.entrypoint` | 세션이 시작된 방식 (예: `cli`, `sdk-cli`, `sdk-ts`, `sdk-py` 또는 `claude-vscode`) | `OTEL_METRICS_INCLUDE_ENTRYPOINT` (기본값: false) |433| `app.entrypoint` | 세션이 시작된 방식, 예: `cli`, `sdk-cli`, `sdk-ts`, `sdk-py` 또는 `claude-vscode` | `OTEL_METRICS_INCLUDE_ENTRYPOINT` (기본값: false) |

430| `organization.id` | 조직 UUID (인증된 경우) | 사용 가능할 때 항상 포함됨 |434| `organization.id` | 조직 UUID (인증된 경우) | 사용 가능할 때 항상 포함됨 |

431| `user.account_uuid` | 계정 UUID (인증된 경우) | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (기본값: true) |435| `user.account_uuid` | 계정 UUID (인증된 경우) | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (기본값: true) |

432| `user.account_id` | Anthropic 관리 API와 일치하는 태그 형식의 계정 ID (인증된 경우) (예: `user_01BWBeN28...`) | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (기본값: true) |436| `user.account_id` | Anthropic 관리 API와 일치하는 태그 형식의 계정 ID (인증된 경우), 예: `user_01BWBeN28...` | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (기본값: true) |

433| `user.id` | 익명 장치/설치 식별자 (Claude Code 설치당 생성됨) | 항상 포함됨 |437| `user.id` | 실행 시 생성되고 `~/.claude.json`에 유지되는 무작위 익명 식별자입니다. 개인 정보를 포함하지 않으며 Claude 계정에서 파생되지 않습니다. 파일을 삭제하면 다음 실행 시 새로운 관련 없는 값이 생성됩니다. | 항상 포함됨 |

434| `user.email` | 사용자 이메일 주소 (OAuth를 통해 인증된 경우) | 사용 가능할 때 항상 포함됨 |438| `user.email` | 사용자 이메일 주소 (OAuth를 통해 인증된 경우) | 사용 가능할 때 항상 포함됨 |

435| `terminal.type` | 터미널 유형 (예: `iTerm.app`, `vscode`, `cursor` 또는 `tmux`) | 감지될 때 항상 포함됨 |439| `terminal.type` | 터미널 유형, 예: `iTerm.app`, `vscode`, `cursor` 또는 `tmux` | 감지될 때 항상 포함됨 |

436| `OTEL_RESOURCE_ATTRIBUTES`의 키 | 설정한 사용자 정의 속성, 예: `department` 또는 `team.id`. [다중 팀 조직 지원](#multi-team-organization-support)을 참조하세요 | `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` (기본값: true) |440| `OTEL_RESOURCE_ATTRIBUTES`의 키 | 설정한 사용자 정의 속성, 예: `department` 또는 `team.id`. [다중 팀 조직 지원](#multi-team-organization-support)을 참조하세요 | `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` (기본값: true) |

437 441 

438이벤트는 추가로 다음 속성을 포함합니다. 이들은 무한 카디널리티를 야기할 수 있으므로 메트릭에 절대 첨부되지 않습니다:442이벤트는 추가로 다음 속성을 포함합니다. 이들은 무한 카디널리티를 야기할 수 있으므로 메트릭에 절대 첨부되지 않습니다:


484 488 

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

486* `type`: (`"added"`, `"removed"`)490* `type`: (`"added"`, `"removed"`)

491* `model`: 변경을 수행한 모델의 모델 식별자 (예: "claude-sonnet-4-6"). {/* min-version: 2.1.172 */}Claude Code v2.1.172 이상 필요

487 492 

488<h4 id="pull-request-counter">493<h4 id="pull-request-counter">

489 풀 요청 카운터494 풀 요청 카운터


553* `tool_name`: 도구 이름 (`"Edit"`, `"Write"`, `"NotebookEdit"`)558* `tool_name`: 도구 이름 (`"Edit"`, `"Write"`, `"NotebookEdit"`)

554* `decision`: 사용자 결정 (`"accept"`, `"reject"`)559* `decision`: 사용자 결정 (`"accept"`, `"reject"`)

555* `source`: 결정 출처. `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"` 또는 `"user_reject"` 중 하나. [도구 결정 이벤트](#tool-decision-event)를 참조하여 각 값의 의미를 확인하세요.560* `source`: 결정 출처. `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"` 또는 `"user_reject"` 중 하나. [도구 결정 이벤트](#tool-decision-event)를 참조하여 각 값의 의미를 확인하세요.

556* `language`: 편집된 파일의 프로그래밍 언어 (예: `"TypeScript"`, `"Python"`, `"JavaScript"` 또는 `"Markdown"`). 인식되지 않는 파일 확장자의 경우 `"unknown"`을 반환합니다.561* `language`: 편집된 파일의 프로그래밍 언어, 예: `"TypeScript"`, `"Python"`, `"JavaScript"` 또는 `"Markdown"`. 인식되지 않는 파일 확장자의 경우 `"unknown"`을 반환합니다.

557 562 

558<h4 id="active-time-counter">563<h4 id="active-time-counter">

559 활성 시간 카운터564 활성 시간 카운터


625* `tool_use_id`: 이 도구 호출의 고유 식별자. 훅에 전달된 `tool_use_id`와 일치하여 OTel 이벤트와 훅 캡처 데이터 간의 상관관계를 허용합니다.630* `tool_use_id`: 이 도구 호출의 고유 식별자. 훅에 전달된 `tool_use_id`와 일치하여 OTel 이벤트와 훅 캡처 데이터 간의 상관관계를 허용합니다.

626* `success`: `"true"` 또는 `"false"`631* `success`: `"true"` 또는 `"false"`

627* `duration_ms`: 실행 시간 (밀리초)632* `duration_ms`: 실행 시간 (밀리초)

628* `error_type`: 도구가 실패했을 때 오류 범주 문자열 (예: `"Error:ENOENT"` 또는 `"ShellError"`)633* `error_type`: 도구가 실패했을 때 오류 범주 문자열, 예: `"Error:ENOENT"` 또는 `"ShellError"`

629* `error` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 도구가 실패했을 때 전체 오류 메시지634* `error` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 도구가 실패했을 때 전체 오류 메시지

630* `decision_type`: 항상 `"accept"`입니다. 이 이벤트는 도구가 실행된 후에만 내보내집니다 (거부된 호출은 도구 결과를 생성하지 않음)635* `decision_type`: 항상 `"accept"`입니다. 이 이벤트는 도구가 실행된 후에만 내보내집니다 (거부된 호출은 도구 결과를 생성하지 않음)

631* `decision_source`: 권한 결정이 나온 위치. `"config"`, `"hook"`, `"user_permanent"` 또는 `"user_temporary"` 중 하나. [도구 결정 이벤트](#tool-decision-event)를 참조하여 각 값의 의미를 확인하세요. 거부 전용 출처인 `"user_abort"` 및 `"user_reject"`는 이 이벤트에 나타나지 않습니다.636* `decision_source`: 권한 결정이 나온 위치. `"config"`, `"hook"`, `"user_permanent"` 또는 `"user_temporary"` 중 하나. [도구 결정 이벤트](#tool-decision-event)를 참조하여 각 값의 의미를 확인하세요. 거부 전용 출처인 `"user_abort"` 및 `"user_reject"`는 이 이벤트에 나타나지 않습니다.


661* `output_tokens`: 출력 토큰 수666* `output_tokens`: 출력 토큰 수

662* `cache_read_tokens`: 캐시에서 읽은 토큰 수667* `cache_read_tokens`: 캐시에서 읽은 토큰 수

663* `cache_creation_tokens`: 캐시 생성에 사용된 토큰 수668* `cache_creation_tokens`: 캐시 생성에 사용된 토큰 수

664* `request_id`: 응답의 `request-id` 헤더의 Anthropic API 요청 ID (예: `"req_011..."`). API가 반환할 때만 표시됩니다.669* `request_id`: 응답의 `request-id` 헤더의 Anthropic API 요청 ID, 예: `"req_011..."`. API가 반환할 때만 표시됩니다.

665* `speed`: 빠른 모드가 활성화되었는지 여부를 나타내는 `"fast"` 또는 `"normal"`670* `speed`: 빠른 모드가 활성화되었는지 여부를 나타내는 `"fast"` 또는 `"normal"`

666* `query_source`: 요청을 발급한 하위 시스템 (예: `"repl_main_thread"`, `"compact"` 또는 하위 에이전트 이름)671* `query_source`: 요청을 발급한 하위 시스템, 예: `"repl_main_thread"`, `"compact"` 또는 하위 에이전트 이름

667* `effort`: 요청에 적용된 [노력 수준](/ko/model-config#adjust-effort-level): `"low"`, `"medium"`, `"high"`, `"xhigh"` 또는 `"max"`. 모델이 노력을 지원하지 않을 때는 없음672* `effort`: 요청에 적용된 [노력 수준](/ko/model-config#adjust-effort-level): `"low"`, `"medium"`, `"high"`, `"xhigh"` 또는 `"max"`. 모델이 노력을 지원하지 않을 때는 없음

668* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: 요청에 대한 스킬, 플러그인, 에이전트 및 MCP 속성. [비용 카운터](#cost-counter)의 정의 및 수정 동작을 참조하세요.673* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: 요청에 대한 스킬, 플러그인, 에이전트 및 MCP 속성. [비용 카운터](#cost-counter)의 정의 및 수정 동작을 참조하세요.

669 674 


686* `status_code`: HTTP 상태 코드 (숫자). HTTP가 아닌 오류 (예: 연결 실패)의 경우 없음691* `status_code`: HTTP 상태 코드 (숫자). HTTP가 아닌 오류 (예: 연결 실패)의 경우 없음

687* `duration_ms`: 요청 지속 시간 (밀리초)692* `duration_ms`: 요청 지속 시간 (밀리초)

688* `attempt`: 초기 요청을 포함한 총 시도 횟수 (`1`은 재시도가 발생하지 않았음을 의미)693* `attempt`: 초기 요청을 포함한 총 시도 횟수 (`1`은 재시도가 발생하지 않았음을 의미)

689* `request_id`: 응답의 `request-id` 헤더의 Anthropic API 요청 ID (예: `"req_011..."`). API가 반환할 때만 표시됩니다.694* `request_id`: 응답의 `request-id` 헤더의 Anthropic API 요청 ID, 예: `"req_011..."`. API가 반환할 때만 표시됩니다.

690* `speed`: 빠른 모드가 활성화되었는지 여부를 나타내는 `"fast"` 또는 `"normal"`695* `speed`: 빠른 모드가 활성화되었는지 여부를 나타내는 `"fast"` 또는 `"normal"`

691* `query_source`: 요청을 발급한 하위 시스템 (예: `"repl_main_thread"`, `"compact"` 또는 하위 에이전트 이름)696* `query_source`: 요청을 발급한 하위 시스템, 예: `"repl_main_thread"`, `"compact"` 또는 하위 에이전트 이름

692* `effort`: 요청에 적용된 [노력 수준](/ko/model-config#adjust-effort-level). 모델이 노력을 지원하지 않을 때는 없음697* `effort`: 요청에 적용된 [노력 수준](/ko/model-config#adjust-effort-level). 모델이 노력을 지원하지 않을 때는 없음

693* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: 요청에 대한 스킬, 플러그인, 에이전트 및 MCP 속성. [비용 카운터](#cost-counter)의 정의 및 수정 동작을 참조하세요.698* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: 요청에 대한 스킬, 플러그인, 에이전트 및 MCP 속성. [비용 카운터](#cost-counter)의 정의 및 수정 동작을 참조하세요.

694 699 

700<h4 id="api-refusal-event">

701 API 거부 이벤트

702</h4>

703 

704API 요청이 `stop_reason: "refusal"`을 반환할 때 기록됩니다. 거부는 HTTP 오류가 아닌 성공적인 응답 스트림에 도착하므로 `api_error` 이벤트는 이에 대해 발생하지 않습니다. 이 이벤트를 사용하면 거부 빈도를 추적할 수 있습니다.

705 

706**이벤트 이름**: `claude_code.api_refusal`

707 

708**속성**:

709 

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

711* `event.name`: `"api_refusal"`

712* `event.timestamp`: ISO 8601 타임스탬프

713* `event.sequence`: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터

714* `model`: 요청의 모델 식별자

715* `request_id`: 응답의 `request-id` 헤더의 Anthropic API 요청 ID, 예: `"req_011..."`. API가 반환할 때만 표시됩니다.

716 

695<h4 id="api-request-body-event">717<h4 id="api-request-body-event">

696 API 요청 본문 이벤트718 API 요청 본문 이벤트

697</h4>719</h4>


733* `body_truncated`: 인라인 잘림이 발생했을 때 `"true"`. 파일 모드 및 잘림이 발생하지 않았을 때는 없음755* `body_truncated`: 인라인 잘림이 발생했을 때 `"true"`. 파일 모드 및 잘림이 발생하지 않았을 때는 없음

734* `model`: 모델 식별자756* `model`: 모델 식별자

735* `query_source`: 요청을 발급한 하위 시스템757* `query_source`: 요청을 발급한 하위 시스템

736* `request_id`: 응답의 `request-id` 헤더의 Anthropic API 요청 ID (예: `"req_011..."`). API가 반환할 때만 표시됩니다.758* `request_id`: 응답의 `request-id` 헤더의 Anthropic API 요청 ID, 예: `"req_011..."`. API가 반환할 때만 표시됩니다.

737 759 

738<h4 id="tool-decision-event">760<h4 id="tool-decision-event">

739 도구 결정 이벤트761 도구 결정 이벤트


780* `event.name`: `"permission_mode_changed"`802* `event.name`: `"permission_mode_changed"`

781* `event.timestamp`: ISO 8601 타임스탬프803* `event.timestamp`: ISO 8601 타임스탬프

782* `event.sequence`: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터804* `event.sequence`: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터

783* `from_mode`: 이전 권한 모드 (예: `"default"`, `"plan"`, `"acceptEdits"`, `"auto"` 또는 `"bypassPermissions"`)805* `from_mode`: 이전 권한 모드, 예: `"default"`, `"plan"`, `"acceptEdits"`, `"auto"` 또는 `"bypassPermissions"`

784* `to_mode`: 새 권한 모드806* `to_mode`: 새 권한 모드

785* `trigger`: 변경을 야기한 것. `"shift_tab"`, `"exit_plan_mode"`, `"auto_gate_denied"` 또는 `"auto_opt_in"` 중 하나. SDK 또는 브리지에서 전환이 시작될 때는 없음807* `trigger`: 변경을 야기한 것. `"shift_tab"`, `"exit_plan_mode"`, `"auto_gate_denied"` 또는 `"auto_opt_in"` 중 하나. SDK 또는 브리지에서 전환이 시작될 때는 없음

786 808 


800* `event.sequence`: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터822* `event.sequence`: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터

801* `action`: `"login"` 또는 `"logout"`823* `action`: `"login"` 또는 `"logout"`

802* `success`: `"true"` 또는 `"false"`824* `success`: `"true"` 또는 `"false"`

803* `auth_method`: 인증 방법 (예: `"oauth"`)825* `auth_method`: 인증 방법, 예: `"oauth"`

804* `error_category`: 작업이 실패했을 때 범주별 오류 종류. 원본 오류 메시지는 포함되지 않습니다826* `error_category`: 작업이 실패했을 때 범주별 오류 종류. 원본 오류 메시지는 포함되지 않습니다

805* `status_code`: 작업이 HTTP 오류로 실패했을 때 HTTP 상태 코드 (문자열)827* `status_code`: 작업이 HTTP 오류로 실패했을 때 HTTP 상태 코드 (문자열)

806 828 


819* `event.timestamp`: ISO 8601 타임스탬프841* `event.timestamp`: ISO 8601 타임스탬프

820* `event.sequence`: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터842* `event.sequence`: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터

821* `status`: `"connected"`, `"failed"` 또는 `"disconnected"`843* `status`: `"connected"`, `"failed"` 또는 `"disconnected"`

822* `transport_type`: 서버 전송 (예: `"stdio"`, `"sse"` 또는 `"http"`)844* `transport_type`: 서버 전송, 예: `"stdio"`, `"sse"` 또는 `"http"`

823* `server_scope`: 서버가 구성된 범위 (예: `"user"`, `"project"` 또는 `"local"`)845* `server_scope`: 서버가 구성된 범위, 예: `"user"`, `"project"` 또는 `"local"`

824* `duration_ms`: 연결 시도 지속 시간 (밀리초)846* `duration_ms`: 연결 시도 지속 시간 (밀리초)

825* `error_code`: 연결이 실패했을 때 오류 코드847* `error_code`: 연결이 실패했을 때 오류 코드

848* `is_plugin`: 서버가 플러그인에서 제공될 때 `true`, 그 외에는 `false`

849* `plugin_id_hash` (`is_plugin`이 `true`일 때): 플러그인 이름 및 마켓플레이스의 안정적인 해시 (이름을 노출하지 않고 플러그인별로 이벤트를 그룹화하기 위함)

850* `plugin.name` (`is_plugin`이 `true`일 때): 서버를 제공하는 플러그인의 이름. 타사 플러그인의 경우 `OTEL_LOG_TOOL_DETAILS=1`이 아니면 리터럴 문자열 `"third-party"`입니다. 공식 Anthropic 소스의 플러그인은 항상 이름으로 식별됩니다. `plugin_id_hash` 및 `plugin.name` 속성은 자신의 모니터링 백엔드로 흐르며 Anthropic으로 전송되지 않습니다

826* `server_name` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 구성된 서버 이름851* `server_name` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 구성된 서버 이름

827* `error` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 연결이 실패했을 때 전체 오류 메시지852* `error` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 연결이 실패했을 때 전체 오류 메시지

828 853 


840* `event.name`: `"internal_error"`865* `event.name`: `"internal_error"`

841* `event.timestamp`: ISO 8601 타임스탬프866* `event.timestamp`: ISO 8601 타임스탬프

842* `event.sequence`: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터867* `event.sequence`: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터

843* `error_name`: 오류 클래스 이름 (예: `"TypeError"` 또는 `"SyntaxError"`)868* `error_name`: 오류 클래스 이름, 예: `"TypeError"` 또는 `"SyntaxError"`

844* `error_code`: 오류에 있을 때 Node.js errno 코드 (예: `"ENOENT"`)869* `error_code`: 오류에 있을 때 Node.js errno 코드, 예: `"ENOENT"`

845 870 

846<h4 id="plugin-installed-event">871<h4 id="plugin-installed-event">

847 플러그인 설치됨 이벤트872 플러그인 설치됨 이벤트


885* `plugin_id_hash`: 플러그인 이름 및 마켓플레이스의 결정론적 해시 (구성된 내보내기로만 전송됨). 플릿 전체에서 로드된 서로 다른 타사 플러그인 수를 세는 것을 허용합니다 (이름 기록 없이)910* `plugin_id_hash`: 플러그인 이름 및 마켓플레이스의 결정론적 해시 (구성된 내보내기로만 전송됨). 플릿 전체에서 로드된 서로 다른 타사 플러그인 수를 세는 것을 허용합니다 (이름 기록 없이)

886* `has_hooks`: 플러그인이 훅을 제공하는지 여부911* `has_hooks`: 플러그인이 훅을 제공하는지 여부

887* `has_mcp`: 플러그인이 MCP 서버를 제공하는지 여부912* `has_mcp`: 플러그인이 MCP 서버를 제공하는지 여부

913* `host_owned_mcp`: SDK 호스트가 이 플러그인의 MCP 연결을 관리하고 Claude Code가 플러그인의 MCP 서버 구성 읽기를 건너뛸 때 `true`, 그 외에는 `false`. {/* min-version: 2.1.172 */}Claude Code v2.1.172 이상 필요

888* `skill_path_count`: 플러그인이 선언하는 스킬 디렉토리 수914* `skill_path_count`: 플러그인이 선언하는 스킬 디렉토리 수

889* `command_path_count`: 플러그인이 선언하는 명령 디렉토리 수915* `command_path_count`: 플러그인이 선언하는 명령 디렉토리 수

890* `agent_path_count`: 플러그인이 선언하는 에이전트 디렉토리 수916* `agent_path_count`: 플러그인이 선언하는 에이전트 디렉토리 수

917* `safe_mode`: 세션이 [`--safe-mode`](/ko/cli-reference)로 시작되었을 때 `"true"`, 그 외에는 `"false"`. 안전 모드에서 이 이벤트는 구성된 인벤토리만 보고합니다. 플러그인의 명령, 스킬, 훅 및 MCP 서버는 로드되지 않습니다. {/* min-version: 2.1.169 */}Claude Code v2.1.169 이상 필요

891 918 

892<h4 id="skill-activated-event">919<h4 id="skill-activated-event">

893 스킬 활성화됨 이벤트920 스킬 활성화됨 이벤트


906* `skill.name`: 스킬의 이름. 사용자 정의 및 타사 플러그인 스킬의 경우 `OTEL_LOG_TOOL_DETAILS=1`이 아니면 값은 자리 표시자 `"custom_skill"`입니다933* `skill.name`: 스킬의 이름. 사용자 정의 및 타사 플러그인 스킬의 경우 `OTEL_LOG_TOOL_DETAILS=1`이 아니면 값은 자리 표시자 `"custom_skill"`입니다

907* `invocation_trigger`: 스킬이 트리거된 방식 (`"user-slash"`, `"claude-proactive"` 또는 `"nested-skill"`)934* `invocation_trigger`: 스킬이 트리거된 방식 (`"user-slash"`, `"claude-proactive"` 또는 `"nested-skill"`)

908* `skill.source`: 스킬이 로드된 위치 (예: `"bundled"`, `"userSettings"`, `"projectSettings"`, `"plugin"`)935* `skill.source`: 스킬이 로드된 위치 (예: `"bundled"`, `"userSettings"`, `"projectSettings"`, `"plugin"`)

936* `skill.kind`: 스킬이 워크플로우 스킬일 때 `"workflow"`. 그 외에는 없음

909* `plugin.name` (`OTEL_LOG_TOOL_DETAILS=1`이거나 플러그인이 공식 마켓플레이스에서 온 경우): 스킬이 플러그인에서 제공될 때 소유 플러그인의 이름937* `plugin.name` (`OTEL_LOG_TOOL_DETAILS=1`이거나 플러그인이 공식 마켓플레이스에서 온 경우): 스킬이 플러그인에서 제공될 때 소유 플러그인의 이름

910* `marketplace.name` (`OTEL_LOG_TOOL_DETAILS=1`이거나 플러그인이 공식 마켓플레이스에서 온 경우): 스킬이 플러그인에서 제공될 때 소유 플러그인이 설치된 마켓플레이스938* `marketplace.name` (`OTEL_LOG_TOOL_DETAILS=1`이거나 플러그인이 공식 마켓플레이스에서 온 경우): 스킬이 플러그인에서 제공될 때 소유 플러그인이 설치된 마켓플레이스

911 939 


961* `event.name`: `"hook_registered"`989* `event.name`: `"hook_registered"`

962* `event.timestamp`: ISO 8601 타임스탬프990* `event.timestamp`: ISO 8601 타임스탬프

963* `event.sequence`: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터991* `event.sequence`: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터

964* `hook_event`: 훅 이벤트 유형 (예: `"PreToolUse"` 또는 `"PostToolUse"`)992* `hook_event`: 훅 이벤트 유형, 예: `"PreToolUse"` 또는 `"PostToolUse"`

965* `hook_type`: 훅 구현 유형: `"command"`, `"prompt"`, `"mcp_tool"`, `"http"` 또는 `"agent"`993* `hook_type`: 훅 구현 유형: `"command"`, `"prompt"`, `"mcp_tool"`, `"http"` 또는 `"agent"`

966* `hook_source`: 훅이 정의된 위치: `"userSettings"`, `"projectSettings"`, `"localSettings"`, `"flagSettings"`, `"policySettings"` 또는 `"pluginHook"`994* `hook_source`: 훅이 정의된 위치: `"userSettings"`, `"projectSettings"`, `"localSettings"`, `"flagSettings"`, `"policySettings"` 또는 `"pluginHook"`

995* `safe_mode`: 세션이 [`--safe-mode`](/ko/cli-reference)로 시작되었을 때 `"true"`, 그 외에는 `"false"`. {/* min-version: 2.1.169 */}Claude Code v2.1.169 이상 필요

967* `hook_matcher` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 설정된 경우 훅 구성의 매처 문자열996* `hook_matcher` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 설정된 경우 훅 구성의 매처 문자열

968* `plugin.name` (`hook_source`가 `"pluginHook"`일 때): 기여하는 플러그인의 이름. 공식 마켓플레이스 및 기본 제공 번들 외부의 플러그인의 경우 `OTEL_LOG_TOOL_DETAILS=1`이 아니면 값은 `"third-party"`입니다997* `plugin.name` (`hook_source`가 `"pluginHook"`일 때): 기여하는 플러그인의 이름. 공식 마켓플레이스 및 기본 제공 번들 외부의 플러그인의 경우 `OTEL_LOG_TOOL_DETAILS=1`이 아니면 값은 `"third-party"`입니다

969* `plugin_id_hash` (`hook_source`가 `"pluginHook"`일 때): 플러그인 이름 및 마켓플레이스의 결정론적 해시 (구성된 내보내기로만 전송됨). 이름을 기록하지 않고 기여하는 서로 다른 플러그인을 세는 것을 허용합니다998* `plugin_id_hash` (`hook_source`가 `"pluginHook"`일 때): 플러그인 이름 및 마켓플레이스의 결정론적 해시 (구성된 내보내기로만 전송됨). 이름을 기록하지 않고 기여하는 서로 다른 플러그인을 세는 것을 허용합니다


982* `event.name`: `"hook_execution_start"`1011* `event.name`: `"hook_execution_start"`

983* `event.timestamp`: ISO 8601 타임스탬프1012* `event.timestamp`: ISO 8601 타임스탬프

984* `event.sequence`: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터1013* `event.sequence`: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터

985* `hook_event`: 훅 이벤트 유형 (예: `"PreToolUse"` 또는 `"PostToolUse"`)1014* `hook_event`: 훅 이벤트 유형, 예: `"PreToolUse"` 또는 `"PostToolUse"`

986* `hook_name`: 매처를 포함한 전체 훅 이름 (예: `"PreToolUse:Write"`)1015* `hook_name`: 매처를 포함한 전체 훅 이름, 예: `"PreToolUse:Write"`

987* `num_hooks`: 일치하는 훅 명령 수1016* `num_hooks`: 일치하는 훅 명령 수

988* `managed_only`: 관리 정책 훅만 허용될 때 `"true"`1017* `managed_only`: 관리 정책 훅만 허용될 때 `"true"`

989* `hook_source`: `"policySettings"` 또는 `"merged"`1018* `hook_source`: `"policySettings"` 또는 `"merged"`

1019* `safe_mode`: 세션이 [`--safe-mode`](/ko/cli-reference)로 시작되었을 때 `"true"`, 그 외에는 `"false"`. {/* min-version: 2.1.169 */}Claude Code v2.1.169 이상 필요

990* `hook_definitions`: JSON 직렬화된 훅 구성. 상세 베타 추적과 `OTEL_LOG_TOOL_DETAILS=1`이 모두 활성화되어 있을 때만 포함됨1020* `hook_definitions`: JSON 직렬화된 훅 구성. 상세 베타 추적과 `OTEL_LOG_TOOL_DETAILS=1`이 모두 활성화되어 있을 때만 포함됨

991 1021 

992<h4 id="hook-execution-complete-event">1022<h4 id="hook-execution-complete-event">


1013* `total_duration_ms`: 모든 일치하는 훅의 벽시계 지속 시간1043* `total_duration_ms`: 모든 일치하는 훅의 벽시계 지속 시간

1014* `managed_only`: 관리 정책 훅만 허용될 때 `"true"`1044* `managed_only`: 관리 정책 훅만 허용될 때 `"true"`

1015* `hook_source`: `"policySettings"` 또는 `"merged"`1045* `hook_source`: `"policySettings"` 또는 `"merged"`

1046* `safe_mode`: 세션이 [`--safe-mode`](/ko/cli-reference)로 시작되었을 때 `"true"`, 그 외에는 `"false"`. {/* min-version: 2.1.169 */}Claude Code v2.1.169 이상 필요

1016* `hook_definitions`: JSON 직렬화된 훅 구성. 상세 베타 추적과 `OTEL_LOG_TOOL_DETAILS=1`이 모두 활성화되어 있을 때만 포함됨1047* `hook_definitions`: JSON 직렬화된 훅 구성. 상세 베타 추적과 `OTEL_LOG_TOOL_DETAILS=1`이 모두 활성화되어 있을 때만 포함됨

1017 1048 

1018<h4 id="hook-plugin-metrics-event">1049<h4 id="hook-plugin-metrics-event">


1069* `event.name`: `"feedback_survey"`1100* `event.name`: `"feedback_survey"`

1070* `event.timestamp`: ISO 8601 타임스탬프1101* `event.timestamp`: ISO 8601 타임스탬프

1071* `event.sequence`: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터1102* `event.sequence`: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터

1072* `event_type`: 설문 수명 주기 이벤트 (예: `"appeared"`, `"responded"` 또는 `"transcript_prompt_appeared"`)1103* `event_type`: 설문 수명 주기 이벤트, 예: `"appeared"`, `"responded"` 또는 `"transcript_prompt_appeared"`

1073* `appearance_id`: 하나의 설문 인스턴스에 대해 내보내진 이벤트를 연결하는 고유 ID1104* `appearance_id`: 하나의 설문 인스턴스에 대해 내보내진 이벤트를 연결하는 고유 ID

1074* `survey_type`: 이벤트를 생성한 설문. `"session"`은 "Claude가 어떻게 하고 있나요?" 평가 프롬프트입니다1105* `survey_type`: 이벤트를 생성한 설문. `"session"`은 "Claude가 어떻게 하고 있나요?" 평가 프롬프트입니다

1075* `response`: `responded` 이벤트에서 사용자의 선택1106* `response`: `responded` 이벤트에서 사용자의 선택


1089| ------------------------------------------------------------- | ---------------------------------------------------------------------------- |1120| ------------------------------------------------------------- | ---------------------------------------------------------------------------- |

1090| `claude_code.token.usage` | `type` (입력/출력), 사용자, 팀, 모델, `skill.name`, `plugin.name` 또는 `agent.name`별로 분류 |1121| `claude_code.token.usage` | `type` (입력/출력), 사용자, 팀, 모델, `skill.name`, `plugin.name` 또는 `agent.name`별로 분류 |

1091| `claude_code.session.count` | 시간 경과에 따른 채택 및 참여 추적 |1122| `claude_code.session.count` | 시간 경과에 따른 채택 및 참여 추적 |

1092| `claude_code.lines_of_code.count` | 코드 추가/제거를 추적하여 생산성 측정 |1123| `claude_code.lines_of_code.count` | 코드 추가제거를 추적하여 생산성 측정, 모델별로 분류 |

1093| `claude_code.commit.count` & `claude_code.pull_request.count` | 개발 워크플로우에 미치는 영향 이해 |1124| `claude_code.commit.count` & `claude_code.pull_request.count` | 개발 워크플로우에 미치는 영향 이해 |

1094 1125 

1095<h3 id="cost-monitoring">1126<h3 id="cost-monitoring">


1103* `skill.name`, `plugin.name` 및 `agent.name` 속성을 통해 특정 스킬, 플러그인 또는 서브에이전트 유형에 지출 귀속1134* `skill.name`, `plugin.name` 및 `agent.name` 속성을 통해 특정 스킬, 플러그인 또는 서브에이전트 유형에 지출 귀속

1104 1135 

1105<Note>1136<Note>

1106 비용 메트릭은 근사값입니다. 공식 청구 데이터는 API 제공자 (Claude Console, Amazon Bedrock 또는 Google Cloud Vertex)를 참조하세요.1137 비용 메트릭은 근사값입니다. 공식 청구 데이터는 API 제공자(Claude Console, Amazon Bedrock 또는 Google Cloud Vertex)를 참조하세요.

1107</Note>1138</Note>

1108 1139 

1109<h3 id="alerting-and-segmentation">1140<h3 id="alerting-and-segmentation">

1110 경고 및 세분화1141 경고 및 세분화

1111</h3>1142</h3>

1112 1143 

1113고려할 일반적인 경고:1144일반적인 경고 고려 사항:

1114 1145 

1115* 비용 급증1146* 비용 급증

1116* 비정상적인 토큰 소비1147* 비정상적인 토큰 소비

1117* 특정 사용자의 높은 세션 볼륨1148* 특정 사용자의 높은 세션 볼륨

1118 1149 

1119모든 메트릭은 `user.account_uuid`, `user.account_id`, `organization.id`, `session.id`, `model` `app.version`으로 세분화할 수 있습니다.1150모든 메트릭은 [표준 속성](#standard-attributes)으로 세분화할 수 있습니다. `model` 속성은 `claude_code.token.usage`, `claude_code.cost.usage`에서 사용 가능하며, v2.1.172부터 `claude_code.lines_of_code.count`에서도 사용 가능합니다. 커밋의 모델별 분류는 한 세션이 여러 모델에 걸쳐 있을 수 있으므로 `session.id`에서 토큰 또는 비용 메트릭에 대해 조인하여만 근사할 수 있습니다.

1120 1151 

1121<h3 id="detect-retry-exhaustion">1152<h3 id="detect-retry-exhaustion">

1122 재시도 소진 감지1153 재시도 소진 감지


1179 1210 

1180* `tool_result`: `tool_name` 및 `mcp_server_scope`를 유지하고, `mcp_server_name`, `mcp_tool_name` 및 인수를 생략합니다1211* `tool_result`: `tool_name` 및 `mcp_server_scope`를 유지하고, `mcp_server_name`, `mcp_tool_name` 및 인수를 생략합니다

1181* `tool_decision`: `tool_name`을 유지하고, `tool_parameters`를 생략합니다1212* `tool_decision`: `tool_name`을 유지하고, `tool_parameters`를 생략합니다

1182* `mcp_server_connection`: `server_name` 및 오류 메시지를 생략합니다1213* `mcp_server_connection`: `server_name` 및 오류 메시지를 생략하지만, `is_plugin`, `plugin_id_hash` 및 `plugin.name`을 유지하며, Anthropic이 아닌 플러그인 이름은 리터럴 `"third-party"`로 수정되므로 플러그인 제공 서버는 상세 로깅 없이도 구별 가능합니다

1183 1214 

1184<h3 id="map-security-questions-to-events">1215<h3 id="map-security-questions-to-events">

1185 보안 질문을 이벤트에 매핑1216 보안 질문을 이벤트에 매핑


1193| 권한 모드 에스컬레이션 | `permission_mode_changed` | `from_mode`, `to_mode`, `trigger` |1224| 권한 모드 에스컬레이션 | `permission_mode_changed` | `from_mode`, `to_mode`, `trigger` |

1194| 정책 훅이 작업을 차단함 | `hook_execution_complete` | `hook_event`, `num_blocking` |1225| 정책 훅이 작업을 차단함 | `hook_execution_complete` | `hook_event`, `num_blocking` |

1195| 로그인, 로그아웃 및 인증 실패 | `auth` | `action`, `success`, `error_category` |1226| 로그인, 로그아웃 및 인증 실패 | `auth` | `action`, `success`, `error_category` |

1196| MCP 서버 연결 또는 실패 | `mcp_server_connection` | `status`, `server_name`, `error_code` |1227| MCP 서버 연결 또는 실패 | `mcp_server_connection` | `status`, `server_name`, `is_plugin`, `error_code` |

1197| 플러그인 설치 및 출처 | `plugin_installed` | `plugin.name`, `marketplace.name`, `marketplace.is_official` |1228| 플러그인 설치 및 출처 | `plugin_installed` | `plugin.name`, `marketplace.name`, `marketplace.is_official` |

1198| 실행된 명령 및 터치된 파일 | `tool_result` (실행됨) 또는 `tool_decision` (거부됨) (`OTEL_LOG_TOOL_DETAILS=1` 포함) | `tool_parameters`; `tool_input` (`tool_result`만 해당) |1229| 실행된 명령 및 터치된 파일 | `tool_result` (실행됨) 또는 `tool_decision` (거부됨) (`OTEL_LOG_TOOL_DETAILS=1` 포함) | `tool_parameters`; `tool_input` (`tool_result`만 해당) |

1199 1230 


1230 1261 

1231* **시계열 데이터베이스 (예: Prometheus)**: 비율 계산, 집계된 메트릭1262* **시계열 데이터베이스 (예: Prometheus)**: 비율 계산, 집계된 메트릭

1232* **컬럼형 저장소 (예: ClickHouse)**: 복잡한 쿼리, 고유 사용자 분석1263* **컬럼형 저장소 (예: ClickHouse)**: 복잡한 쿼리, 고유 사용자 분석

1233* **완전한 기능의 관찰성 플랫폼 (예: Honeycomb, Datadog)**: 고급 쿼리, 시각화, 경고1264* **완전한 기능의 관찰성 플랫폼 (예: Honeycomb, Datadog, Grafana Cloud)**: 고급 쿼리, 시각화, 경고

1234 1265 

1235<h3 id="for-events/logs">1266<h3 id="for-events/logs">

1236 이벤트/로그의 경우1267 이벤트/로그의 경우


1238 1269 

1239* **로그 집계 시스템 (예: Elasticsearch, Loki)**: 전체 텍스트 검색, 로그 분석1270* **로그 집계 시스템 (예: Elasticsearch, Loki)**: 전체 텍스트 검색, 로그 분석

1240* **컬럼형 저장소 (예: ClickHouse)**: 구조화된 이벤트 분석1271* **컬럼형 저장소 (예: ClickHouse)**: 구조화된 이벤트 분석

1241* **완전한 기능의 관찰성 플랫폼 (예: Honeycomb, Datadog)**: 메트릭과 이벤트 간의 상관 관계1272* **완전한 기능의 관찰성 플랫폼 (예: Honeycomb, Datadog, Grafana Cloud)**: 메트릭과 이벤트 간의 상관 관계

1242 1273 

1243<h3 id="for-traces">1274<h3 id="for-traces">

1244 추적의 경우1275 추적의 경우


1247분산 추적 저장소 및 스팬 상관 관계를 지원하는 백엔드를 선택합니다:1278분산 추적 저장소 및 스팬 상관 관계를 지원하는 백엔드를 선택합니다:

1248 1279 

1249* **분산 추적 시스템 (예: Jaeger, Zipkin, Grafana Tempo)**: 스팬 시각화, 요청 워터폴, 지연 시간 분석1280* **분산 추적 시스템 (예: Jaeger, Zipkin, Grafana Tempo)**: 스팬 시각화, 요청 워터폴, 지연 시간 분석

1250* **완전한 기능의 관찰성 플랫폼 (예: Honeycomb, Datadog)**: 추적 검색 및 메트릭과 로그와의 상관 관계1281* **완전한 기능의 관찰성 플랫폼 (예: Honeycomb, Datadog, Grafana Cloud)**: 추적 검색 및 메트릭과 로그와의 상관 관계

1251 1282 

1252일일/주간/월간 활성 사용자 (DAU/WAU/MAU) 메트릭이 필요한 조직의 경우 효율적인 고유 값 쿼리를 지원하는 백엔드를 고려하세요.1283일일/주간/월간 활성 사용자 (DAU/WAU/MAU) 메트릭이 필요한 조직의 경우 효율적인 고유 값 쿼리를 지원하는 백엔드를 고려하세요.

1253 1284 


1269 ROI 측정 리소스1300 ROI 측정 리소스

1270</h2>1301</h2>

1271 1302 

1272원격 측정 설정, 비용 분석, 생산성 메트릭 및 자동화된 보고를 포함하여 Claude Code의 투자 수익률 측정에 대한 포괄적인 가이드는 [Claude Code ROI 측정 가이드](https://github.com/anthropics/claude-code-monitoring-guide)를 참조하세요. 이 저장소는 즉시 사용 가능한 Docker Compose 구성, Prometheus 및 OpenTelemetry 설정, Linear와 같은 도구와 통합된 생산성 보고서 생성 템플릿을 제공합니다.1303Claude Code의 투자 수익률 측정에 대한 포괄적인 가이드(원격 측정 설정, 비용 분석, 생산성 메트릭 및 자동화된 보고 포함)는 [Claude Code ROI 측정 가이드](https://github.com/anthropics/claude-code-monitoring-guide)를 참조하세요. 이 저장소는 즉시 사용 가능한 Docker Compose 구성, Prometheus 및 OpenTelemetry 설정, Linear와 같은 도구와 통합된 생산성 보고서 생성 템플릿을 제공합니다.

1273 1304 

1274<h2 id="security-and-privacy">1305<h2 id="security-and-privacy">

1275 보안 및 개인 정보 보호1306 보안 및 개인 정보 보호

Details

57 * 사용자: `~/.claude/output-styles`57 * 사용자: `~/.claude/output-styles`

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

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

60 

61 프로젝트 출력 스타일은 작업 디렉토리와 저장소 루트 사이의 모든 `.claude/output-styles/`에서 로드됩니다. {/* min-version: 2.1.178 */}v2.1.178부터 이러한 중첩된 디렉토리 중 하나 이상이 동일한 이름의 스타일을 정의하면 Claude Code는 작업 디렉토리에 가장 가까운 것을 사용합니다.

60 </Step>62 </Step>

61 63 

62 <Step title="Frontmatter 및 지침 추가">64 <Step title="Frontmatter 및 지침 추가">

overview.md +2 −2

Details

124 <Tab title="JetBrains">124 <Tab title="JetBrains">

125 IntelliJ IDEA, PyCharm, WebStorm 및 기타 JetBrains IDE용 플러그인으로 대화형 diff 보기 및 선택 컨텍스트 공유 기능이 있습니다.125 IntelliJ IDEA, PyCharm, WebStorm 및 기타 JetBrains IDE용 플러그인으로 대화형 diff 보기 및 선택 컨텍스트 공유 기능이 있습니다.

126 126 

127 JetBrains Marketplace에서 [Claude Code 플러그인](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-)을 설치하고 IDE를 다시 시작합니다.127 JetBrains Marketplace에서 [Claude Code 플러그인](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-)을 설치하고 IDE를 다시 시작합니다. 플러그인에는 별도로 설치되는 Claude Code CLI가 필요합니다. [JetBrains 설정 단계](/ko/jetbrains#installation)를 참조하세요.

128 128 

129 [JetBrains 시작하기 →](/ko/jetbrains)129 [JetBrains 시작하기 →](/ko/jetbrains)

130 </Tab>130 </Tab>


209 209 

210 * 책상에서 떠나 [원격 제어](/ko/remote-control)를 사용하여 휴대폰이나 모든 브라우저에서 계속 작업합니다210 * 책상에서 떠나 [원격 제어](/ko/remote-control)를 사용하여 휴대폰이나 모든 브라우저에서 계속 작업합니다

211 * [Dispatch](/ko/desktop#sessions-from-dispatch)에 휴대폰에서 작업을 메시지로 보내고 생성되는 데스크톱 세션을 엽니다211 * [Dispatch](/ko/desktop#sessions-from-dispatch)에 휴대폰에서 작업을 메시지로 보내고 생성되는 데스크톱 세션을 엽니다

212 * [웹](/ko/claude-code-on-the-web) 또는 [iOS 앱](https://apps.apple.com/app/claude-by-anthropic/id6473753684)에서 오래 실행되는 작업을 시작한 다음 `claude --teleport`를 사용하여 터미널로 가져옵니다212 * [웹](/ko/claude-code-on-the-web) 또는 [iOS 앱](https://apps.apple.com/app/claude-by-anthropic/id6473753684)에서 오래 실행되는 작업을 시작한 다음 `claude --teleport`를 사용하여 터미널로 가져옵니다. Teleport는 claude.ai 구독이 필요합니다.

213 * 터미널 세션을 [데스크톱 앱](/ko/desktop)으로 `/desktop`을 사용하여 시각적 diff 검토를 위해 전달합니다213 * 터미널 세션을 [데스크톱 앱](/ko/desktop)으로 `/desktop`을 사용하여 시각적 diff 검토를 위해 전달합니다

214 * 팀 채팅에서 작업을 라우팅합니다: [Slack](/ko/slack)에서 `@Claude`를 언급하고 버그 보고서를 포함하면 풀 요청을 다시 받습니다214 * 팀 채팅에서 작업을 라우팅합니다: [Slack](/ko/slack)에서 `@Claude`를 언급하고 버그 보고서를 포함하면 풀 요청을 다시 받습니다

215 </Accordion>215 </Accordion>

Details

25 25 

26`bypassPermissions`를 제외한 모든 모드에서 [보호된 경로](#protected-paths)에 대한 쓰기는 절대 자동 승인되지 않으며, 리포지토리 상태와 Claude의 자체 구성을 우발적인 손상으로부터 보호합니다.26`bypassPermissions`를 제외한 모든 모드에서 [보호된 경로](#protected-paths)에 대한 쓰기는 절대 자동 승인되지 않으며, 리포지토리 상태와 Claude의 자체 구성을 우발적인 손상으로부터 보호합니다.

27 27 

28모드는 기본선을 설정합니다. `bypassPermissions`를 제외한 모든 모드에서 특정 도구를 사전 승인하거나 차단하기 위해 [권한 규칙](/ko/permissions#manage-permissions)을 위에 계층화합니다. `bypassPermissions` 권한 계층을 완전히 건너뜁니다.28모드는 기본선을 설정합니다. 특정 도구를 사전 승인하거나 차단하기 위해 [권한 규칙](/ko/permissions#manage-permissions)을 위에 계층화합니다. 거부 규칙과 명시적 요청 규칙은 `bypassPermissions` 포함한 모든 모드에서 적용됩니다. 허용 규칙은 다른 모든 것이 이미 승인되었기 때문에 해당 모드에서는 효과가 없습니다.

29 29 

30<h2 id="switch-permission-modes">30<h2 id="switch-permission-modes">

31 권한 모드 전환31 권한 모드 전환


95 <Tab title="Web and mobile">95 <Tab title="Web and mobile">

96 [claude.ai/code](https://claude.ai/code)의 프롬프트 상자 옆 모드 드롭다운 또는 모바일 앱을 사용합니다. 권한 프롬프트는 승인을 위해 claude.ai에 나타납니다. 어떤 모드가 나타나는지는 세션이 실행되는 위치에 따라 다릅니다:96 [claude.ai/code](https://claude.ai/code)의 프롬프트 상자 옆 모드 드롭다운 또는 모바일 앱을 사용합니다. 권한 프롬프트는 승인을 위해 claude.ai에 나타납니다. 어떤 모드가 나타나는지는 세션이 실행되는 위치에 따라 다릅니다:

97 97 

98 * **[Claude Code on the web](/ko/claude-code-on-the-web)의 클라우드 세션**: 편집 자동 수락 및 계획 모드. 권한 요청, 자동 권한 무시는 사용할 수 없습니다.98 * **[Claude Code on the web](/ko/claude-code-on-the-web)의 클라우드 세션**: 편집 자동 수락, 계획 모드 자동 모드. 편집 자동 수락은 `default` 모드에 해당합니다: 클라우드 환경은 모드에 관계없이 파일 편집을 사전 승인하므로, 드롭다운은 권한 요청 대신 편집 자동 수락을 표시합니다. 설정의 `defaultMode: "acceptEdits"`는 여전히 적용됩니다. 자동 모드는 조직이 허용하고 선택한 모델이 지원할 때만 나타납니다. 권한 무시는 사용할 수 없습니다.

99 * **로컬 머신의 [원격 제어](/ko/remote-control) 세션**: 권한 요청, 편집 자동 수락, 계획 모드. 자동 및 권한 무시는 사용할 수 없습니다.99 * **로컬 머신의 [원격 제어](/ko/remote-control) 세션**: 권한 요청, 편집 자동 수락 계획 모드. 자동 및 권한 무시는 사용할 수 없습니다.

100 100 

101 원격 제어의 경우, 호스트를 시작할 때 시작 모드를 설정할 수도 있습니다:101 원격 제어의 경우, 호스트를 시작할 때 시작 모드를 설정할 수도 있습니다:

102 102 


176 자동 모드는 Claude Code v2.1.83 이상이 필요합니다.176 자동 모드는 Claude Code v2.1.83 이상이 필요합니다.

177</Note>177</Note>

178 178 

179자동 모드는 Claude가 권한 프롬프트 없이 실행되도록 합니다. 별도의 분류기 모델이 실행 전에 작업을 검토하여, 요청을 초과하여 확대되거나, 인식되지 않은 인프라를 대상으로 하거나, Claude가 읽은 적대적 콘텐츠에 의해 주도되는 것으로 보이는 모든 것을 차단합니다.179자동 모드는 Claude가 일상적인 권한 프롬프트 없이 실행되도록 합니다. 별도의 분류기 모델이 실행 전에 작업을 검토하여, 요청을 초과하여 확대되거나, 인식되지 않은 인프라를 대상으로 하거나, Claude가 읽은 적대적 콘텐츠에 의해 주도되는 것으로 보이는 모든 것을 차단합니다. 명시적 [요청 규칙](/ko/permissions#manage-permissions)은 여전히 프롬프트를 강제합니다.

180 180 

181자동 모드는 또한 Claude에게 명확히 하는 질문을 위해 멈추지 않고 계속 작업하도록 권장합니다. 그러나 Claude는 프롬프트나 스킬이 명시적으로 이를 필요로 할 때는 여전히 질문합니다. 권한 프롬프트를 유지하면서 더 강력한 자율적 동작을 원하면 [사전 예방적 출력 스타일](/ko/output-styles)을 대신 설정합니다.181자동 모드는 또한 Claude에게 명확히 하는 질문을 위해 멈추지 않고 계속 작업하도록 권장합니다. 그러나 Claude는 프롬프트나 스킬이 명시적으로 이를 필요로 할 때는 여전히 질문합니다. 권한 프롬프트를 유지하면서 더 강력한 자율적 동작을 원하면 [사전 예방적 출력 스타일](/ko/output-styles)을 대신 설정합니다.

182 182 


189* **플랜**: 모든 플랜.189* **플랜**: 모든 플랜.

190* **관리자**: Team 및 Enterprise에서, 관리자는 사용자가 켜기 전에 [Claude Code 관리자 설정](https://claude.ai/admin-settings/claude-code)에서 이를 활성화해야 합니다. 관리자는 [관리 설정](/ko/permissions#managed-settings)에서 `permissions.disableAutoMode`를 `"disable"`로 설정하여 이를 잠금할 수도 있습니다.190* **관리자**: Team 및 Enterprise에서, 관리자는 사용자가 켜기 전에 [Claude Code 관리자 설정](https://claude.ai/admin-settings/claude-code)에서 이를 활성화해야 합니다. 관리자는 [관리 설정](/ko/permissions#managed-settings)에서 `permissions.disableAutoMode`를 `"disable"`로 설정하여 이를 잠금할 수도 있습니다.

191* **모델**: Anthropic API에서 Claude Opus 4.6 이상 또는 Sonnet 4.6. Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry에서는 Claude Opus 4.7 및 Opus 4.8만 해당합니다. Sonnet 4.5, Opus 4.5, Haiku, claude-3 모델을 포함한 이전 모델은 어떤 제공자에서도 지원되지 않습니다.191* **모델**: Anthropic API에서 Claude Opus 4.6 이상 또는 Sonnet 4.6. Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry에서는 Claude Opus 4.7 및 Opus 4.8만 해당합니다. Sonnet 4.5, Opus 4.5, Haiku, claude-3 모델을 포함한 이전 모델은 어떤 제공자에서도 지원되지 않습니다.

192* **제공자**: Anthropic API에서 기본적으로 사용 가능합니다. Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry에서는 [CLAUDE\_CODE\_ENABLE\_AUTO\_MODE를 설정](#enable-auto-mode-on-bedrock-vertex-ai-or-foundry)할 때까지 자동 모드가 꺼져 있습니다.192* **제공자**: Anthropic API에서 기본적으로 사용 가능합니다. Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry에서는 [`CLAUDE_CODE_ENABLE_AUTO_MODE`를 설정](#enable-auto-mode-on-bedrock-vertex-ai-or-foundry)할 때까지 자동 모드가 꺼져 있습니다.

193 193 

194Claude Code가 자동 모드를 사용할 수 없다고 보고하면, 이러한 요구 사항 중 하나가 충족되지 않은 것입니다. 이는 일시적인 중단이 아닙니다. 모델을 이름으로 지정하고 자동 모드가 작업의 안전을 "결정할 수 없다"고 말하는 별도의 메시지는 일시적인 분류기 중단입니다. [오류 참조](/ko/errors#auto-mode-cannot-determine-the-safety-of-an-action)를 참조합니다.194Claude Code가 자동 모드를 사용할 수 없다고 보고하면, 이러한 요구 사항 중 하나가 충족되지 않은 것입니다. 이는 일시적인 중단이 아닙니다. 모델을 이름으로 지정하고 자동 모드가 작업의 안전을 "결정할 수 없다"고 말하는 별도의 메시지는 일시적인 분류기 중단입니다. [오류 참조](/ko/errors#auto-mode-cannot-determine-the-safety-of-an-action)를 참조합니다.

195 195 

196[설정](/ko/settings#available-settings)에서 `defaultMode: "auto"`를 설정했는데 세션이 오류 없이 `default` 모드로 시작하면, 설정이 `.claude/settings.json` 또는 `.claude/settings.local.json`에 있을 가능성이 높습니다. Claude Code는 이러한 파일의 `auto`를 무시하므로 리포지토리가 자신에게 자동 모드를 부여할 수 없습니다. 이를 `~/.claude/settings.json`으로 이동합니다.196[설정](/ko/settings#available-settings)에서 `defaultMode: "auto"`를 설정했는데 세션이 오류 없이 `default` 모드로 시작하면, 설정이 `.claude/settings.json` 또는 `.claude/settings.local.json`에 있을 가능성이 높습니다. Claude Code v2.1.142 이상은 이러한 파일의 `auto`를 무시하므로 리포지토리가 자신에게 자동 모드를 부여할 수 없습니다. 이를 `~/.claude/settings.json`으로 이동합니다.

197 197 

198<h3 id="enable-auto-mode-on-bedrock-vertex-ai-or-foundry">198<h3 id="enable-auto-mode-on-bedrock-vertex-ai-or-foundry">

199 Bedrock, Vertex AI, Foundry에서 자동 모드 활성화199 Bedrock, Vertex AI, Foundry에서 자동 모드 활성화

200</h3>200</h3>

201 201 

202[Amazon Bedrock](/ko/amazon-bedrock), [Google Cloud Vertex AI](/ko/google-vertex-ai), [Microsoft Foundry](/ko/microsoft-foundry)에서는 `CLAUDE_CODE_ENABLE_AUTO_MODE`가 `1`로 설정될 때까지 자동 모드가 `Shift+Tab` 사이클에 나타나지 않습니다. 이러한 제공자에서는 Claude Opus 4.7 및 Opus 4.8만 지원됩니다.202[Amazon Bedrock](/ko/amazon-bedrock), [Google Cloud Vertex AI](/ko/google-vertex-ai), [Microsoft Foundry](/ko/microsoft-foundry)에서는 `CLAUDE_CODE_ENABLE_AUTO_MODE`가 `1`로 설정될 때까지 자동 모드가 `Shift+Tab` 사이클에 나타나지 않습니다. 변수는 Claude Code v2.1.158 이상에서 작동합니다. 이러한 제공자에서는 Claude Opus 4.7 및 Opus 4.8만 지원됩니다.

203 203 

204한 명의 개발자에게 이를 활성화하려면, `~/.claude/settings.json`의 `env` 블록에 변수를 추가합니다:204한 명의 개발자에게 이를 활성화하려면, `~/.claude/settings.json`의 `env` 블록에 변수를 추가합니다:

205 205 


293 1. 서브에이전트가 시작되기 전에, 위임된 작업 설명이 평가되므로, 위험해 보이는 작업은 생성 시점에 차단됩니다.293 1. 서브에이전트가 시작되기 전에, 위임된 작업 설명이 평가되므로, 위험해 보이는 작업은 생성 시점에 차단됩니다.

294 2. 서브에이전트가 실행되는 동안, 각 작업은 부모 세션과 동일한 규칙으로 분류기를 통해 이동하며, 서브에이전트의 프론트매터의 모든 `permissionMode`는 무시됩니다.294 2. 서브에이전트가 실행되는 동안, 각 작업은 부모 세션과 동일한 규칙으로 분류기를 통해 이동하며, 서브에이전트의 프론트매터의 모든 `permissionMode`는 무시됩니다.

295 3. 서브에이전트가 완료되면, 분류기는 전체 작업 기록을 검토합니다. 반환 검사가 우려 사항에 플래그를 지정하면, 보안 경고가 서브에이전트의 결과에 앞에 붙습니다.295 3. 서브에이전트가 완료되면, 분류기는 전체 작업 기록을 검토합니다. 반환 검사가 우려 사항에 플래그를 지정하면, 보안 경고가 서브에이전트의 결과에 앞에 붙습니다.

296 

297 1단계는 Claude Code v2.1.178 이상이 필요합니다. 이전 버전은 2단계와 3단계에서 분류기를 적용했지만, 서브에이전트가 시작되기 전에 작업 설명을 평가하지 않았습니다.

296 </Accordion>298 </Accordion>

297 299 

298 <Accordion title="비용 및 지연">300 <Accordion title="비용 및 지연">


304 dontAsk 모드로 사전 승인된 도구만 허용306 dontAsk 모드로 사전 승인된 도구만 허용

305</h2>307</h2>

306 308 

307`dontAsk` 모드는 그렇지 않으면 프롬프트할 모든 도구 호출을 자동 거부합니다. `permissions.allow` 규칙과 일치하는 작업 및 [읽기 전용 Bash 명령](/ko/permissions#read-only-commands)만 실행할 수 있습니다. 명시적 `ask` 규칙은 프롬프트하는 대신 거부됩니다. 이는 모드를 완전히 비대화형으로 만들어 CI 파이프라인 또는 Claude가 정확히 수행할 수 있는 작업을 사전 정의하는 제한된 환경에 적합합니다.309`dontAsk` 모드는 그렇지 않으면 프롬프트할 모든 도구 호출을 자동 거부합니다. `permissions.allow` 규칙과 일치하는 작업 및 [읽기 전용 Bash 명령](/ko/permissions#read-only-commands)만 실행할 수 있습니다. 명시적 [`ask` 규칙](/ko/permissions#manage-permissions)은 프롬프트하는 대신 거부됩니다. 이는 모드를 완전히 비대화형으로 만들어 CI 파이프라인 또는 Claude가 정확히 수행할 수 있는 작업을 사전 정의하는 제한된 환경에 적합합니다. [Claude Code on the web](/ko/claude-code-on-the-web)의 클라우드 세션은 `defaultMode: "dontAsk"`를 무시합니다. 자세한 내용은 [bypassPermissions](#skip-all-checks-with-bypasspermissions-mode)를 참조하십시오.

308 310 

309플래그로 시작 시 설정합니다:311시작 시 플래그로 설정합니다:

310 312 

311```bash theme={null}313```bash theme={null}

312claude --permission-mode dontAsk314claude --permission-mode dontAsk


316 bypassPermissions 모드로 모든 검사 건너뛰기318 bypassPermissions 모드로 모든 검사 건너뛰기

317</h2>319</h2>

318 320 

319`bypassPermissions` 모드는 권한 프롬프트 및 안전 검사를 비활성화하여 도구 호출이 즉시 실행되도록 합니다. v2.1.126부터 이는 [보호된 경로](#protected-paths)에 대한 쓰기를 포함하며, 이전 버전은 여전히 프롬프트를 표시합니다. 파일 시스템 루트 또는 홈 디렉터리를 대상으로 하는 제거(예: `rm -rf /` 및 `rm -rf ~`)는 모델 오류에 대한 차단기로서 여전히 프롬프트를 표시합니다. 인터넷 액세스가 없는 컨테이너, VM 또는 개발 컨테이너와 같은 격리된 환경에서만 이 모드를 사용하십시오. 여기서 Claude Code는 호스트 시스템에 손상을 줄 수 없습니다.321`bypassPermissions` 모드는 권한 프롬프트 및 안전 검사를 비활성화하여 도구 호출이 즉시 실행되도록 합니다. v2.1.126부터 이는 [보호된 경로](#protected-paths)에 대한 쓰기를 포함하며, 이전 버전은 여전히 프롬프트를 표시합니다. 명시적 [요청 규칙](/ko/permissions#manage-permissions)은 여전히 이 모드에서 프롬프트를 강제하며, 파일 시스템 루트 또는 홈 디렉터리를 대상으로 하는 제거(예: `rm -rf /` 및 `rm -rf ~`)는 모델 오류에 대한 차단기로서 여전히 프롬프트를 표시합니다. 인터넷 액세스가 없는 컨테이너, VM 또는 개발 컨테이너와 같은 격리된 환경에서만 이 모드를 사용하십시오. 여기서 Claude Code는 호스트 시스템에 손상을 줄 수 없습니다.

320 322 

321활성화 플래그 중 하나로 시작한 세션에서 `bypassPermissions`에 들어갈 수 없습니다. 활성화하려면 다시 시작하십시오:323활성화 플래그 중 하나로 시작한 세션에서 `bypassPermissions`에 들어갈 수 없습니다. 활성화하려면 다시 시작하십시오:

322 324 


334 336 

335인식된 샌드박스 내에서는 검사가 자동으로 건너뜁니다. 컨테이너에서 자율적으로 실행하려면 [개발 컨테이너](/ko/devcontainer) 구성을 사용하십시오. 이는 Claude Code를 비root 사용자로 실행합니다.337인식된 샌드박스 내에서는 검사가 자동으로 건너뜁니다. 컨테이너에서 자율적으로 실행하려면 [개발 컨테이너](/ko/devcontainer) 구성을 사용하십시오. 이는 Claude Code를 비root 사용자로 실행합니다.

336 338 

339[웹의 Claude Code](/ko/claude-code-on-the-web)는 설정 파일의 `defaultMode: "bypassPermissions"` 또는 `"dontAsk"`를 준수하지 않으므로, 리포지토리의 체크인된 설정은 클라우드 세션을 bypass-permissions 모드에서 시작할 수 없습니다. 설정은 자동으로 무시되며 세션은 모드 드롭다운에 표시된 모드에서 시작됩니다. 클라우드 세션이 제공하는 모드에 대해서는 [권한 모드 전환](#switch-permission-modes)을 참조하십시오.

340 

337<Warning>341<Warning>

338 `bypassPermissions`는 프롬프트 주입 또는 의도하지 않은 작업에 대한 보호를 제공하지 않습니다. 프롬프트 없이 백그라운드 안전 검사를 위해 [자동 모드](#eliminate-prompts-with-auto-mode)를 대신 사용하십시오. 관리자는 [관리 설정](/ko/permissions#managed-settings)에서 `permissions.disableBypassPermissionsMode`를 `"disable"`로 설정하여 이 모드를 차단할 수 있습니다.342 `bypassPermissions`는 프롬프트 주입 또는 의도하지 않은 작업에 대한 보호를 제공하지 않습니다. 프롬프트 없이 백그라운드 안전 검사를 위해 [자동 모드](#eliminate-prompts-with-auto-mode)를 대신 사용하십시오. 관리자는 [관리 설정](/ko/permissions#managed-settings)에서 `permissions.disableBypassPermissionsMode`를 `"disable"`로 설정하여 이 모드를 차단할 수 있습니다.

339</Warning>343</Warning>


351| `dontAsk` | 거부 |355| `dontAsk` | 거부 |

352| `bypassPermissions` | 허용 |356| `bypassPermissions` | 허용 |

353 357 

358[`permissions.allow`](/ko/permissions#manage-permissions) 설정 파일의 규칙은 보호된 경로 쓰기를 사전 승인하지 않습니다. 안전 검사는 Claude Code가 설정에서 allow 규칙을 평가하기 전에 실행되므로, `~/.claude/settings.json` 또는 `.claude/settings.json`의 `Edit(.claude/**)` 같은 항목은 위 표의 모드별 결과를 변경하지 않습니다. 프롬프트를 표시하는 모드에서 `.claude/` 쓰기에 대한 프롬프트는 **예, Claude가 이 세션에서 자신의 설정을 편집하도록 허용**을 제공하며, 이는 해당 세션에서 나중의 `.claude/` 쓰기를 다시 프롬프트하지 않고 승인합니다.

359 

354보호된 디렉토리:360보호된 디렉토리:

355 361 

356* `.git`362* `.git`


362* `.devcontainer`368* `.devcontainer`

363* `.yarn`369* `.yarn`

364* `.mvn`370* `.mvn`

365* `.claude`, `.claude/commands`, `.claude/agents`, `.claude/skills`, `.claude/worktrees` 제외. Claude는 이러한 위치에서 정기적으로 콘텐츠를 생성합니다371* `.claude`, `.claude/worktrees` 제외 (Claude가 자신의 git worktrees를 저장하는 위치)

366 372 

367보호된 파일:373보호된 파일:

368 374 


380 참고 항목386 참고 항목

381</h2>387</h2>

382 388 

383* [권한](/ko/permissions): 허용, 요청, 거부 규칙. 관리 정책389* [권한](/ko/permissions): 허용, 요청, 거부 규칙; 관리 정책

384* [자동 모드 구성](/ko/auto-mode-config): 분류기에 조직이 신뢰하는 인프라를 알립니다390* [자동 모드 구성](/ko/auto-mode-config): 분류기에 조직이 신뢰하는 인프라를 알립니다

385* [Hooks](/ko/hooks): `PreToolUse` 및 `PermissionRequest` 훅을 통한 사용자 정의 권한 논리391* [Hooks](/ko/hooks): `PreToolUse` 및 `PermissionRequest` 훅을 통한 사용자 정의 권한 논리

386* [Ultraplan](/ko/ultraplan): 브라우저 기반 검토를 통해 Claude Code on the web 세션에서 계획 모드 실행392* [Ultraplan](/ko/ultraplan): 브라우저 기반 검토를 통해 Claude Code on the web 세션에서 계획 모드 실행

permissions.md +81 −8

Details

30* **Ask** 규칙은 Claude Code가 지정된 도구를 사용하려고 할 때마다 확인을 요청합니다.30* **Ask** 규칙은 Claude Code가 지정된 도구를 사용하려고 할 때마다 확인을 요청합니다.

31* **Deny** 규칙은 Claude Code가 지정된 도구를 사용하지 못하도록 방지합니다.31* **Deny** 규칙은 Claude Code가 지정된 도구를 사용하지 못하도록 방지합니다.

32 32 

33규칙은 순서대로 평가됩니다: **deny -> ask -> allow**. 첫 번째 일치하는 규칙이 우선이므로 deny 규칙이 항상 우선합니다.33규칙은 순서대로 평가됩니다: deny, ask, allow. 해당 순서의 첫 번째 일치 항목이 결과를 결정하며, 규칙 특이성은 순서를 변경하지 않습니다. `Bash(aws *)`와 같은 광범위한 deny 규칙은 `Bash(aws s3 ls)`와 같은 더 좁은 allow 규칙과도 일치하는 호출을 포함하여 모든 일치하는 호출을 차단하므로, deny 규칙은 허용 목록 예외를 포함할 수 없습니다. ask와 allow 사이에도 동일한 우선순위가 적용됩니다: 일치하는 ask 규칙은 동일한 호출과도 일치하는 더 구체적인 allow 규칙이 있을 때도 프롬프트를 표시합니다.

34 34 

35Deny 규칙은 도구 이름을 지정하는지 또는 도구 내의 패턴 범위를 지정하는지에 따라 다르게 작동합니다. `Bash`와 같은 단순 도구 이름은 도구를 Claude의 컨텍스트에서 완전히 제거하므로 Claude는 이를 볼 수 없습니다. `Bash(rm *)`와 같은 범위 지정 규칙은 도구를 사용 가능하게 유지하고 Claude가 시도할 때 일치하는 호출을 차단합니다.35Deny 규칙은 도구 이름을 지정하는지 또는 도구 내의 패턴 범위를 지정하는지에 따라 다르게 작동합니다. `Bash`와 같은 단순 도구 이름은 도구를 Claude의 컨텍스트에서 완전히 제거하므로 Claude는 이를 볼 수 없습니다. `Bash(rm *)`와 같은 범위 지정 규칙은 도구를 사용 가능하게 유지하고 Claude가 시도할 때 일치하는 호출을 차단합니다.

36 36 


45Claude Code는 도구 승인 방식을 제어하는 여러 권한 모드를 지원합니다. [권한 모드](/ko/permission-modes)에서 각 모드를 사용할 시기를 확인합니다. [설정 파일](/ko/settings#settings-files)에서 `defaultMode`를 설정합니다:45Claude Code는 도구 승인 방식을 제어하는 여러 권한 모드를 지원합니다. [권한 모드](/ko/permission-modes)에서 각 모드를 사용할 시기를 확인합니다. [설정 파일](/ko/settings#settings-files)에서 `defaultMode`를 설정합니다:

46 46 

47| 모드 | 설명 |47| 모드 | 설명 |

48| :------------------ | :------------------------------------------------------------------------------------------------------------ |48| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------ |

49| `default` | 표준 동작: 각 도구를 처음 사용할 때 권한을 요청합니다 |49| `default` | 표준 동작: 각 도구를 처음 사용할 때 권한을 요청합니다 |

50| `acceptEdits` | 작업 디렉토리 또는 `additionalDirectories`의 경로에 대해 파일 편집 및 일반적인 파일 시스템 명령(`mkdir`, `touch`, `mv`, `cp` 등)을 자동으로 수락합니다 |50| `acceptEdits` | 작업 디렉토리 또는 `additionalDirectories`의 경로에 대해 파일 편집 및 일반적인 파일 시스템 명령(`mkdir`, `touch`, `mv`, `cp` 등)을 자동으로 수락합니다 |

51| `plan` | Plan Mode: Claude는 파일을 읽고 읽기 전용 셸 명령을 실행하여 탐색하지만 소스 파일을 편집하지 않습니다 |51| `plan` | Plan Mode: Claude는 파일을 읽고 읽기 전용 셸 명령을 실행하여 탐색하지만 소스 파일을 편집하지 않습니다 |

52| `auto` | 배경 안전 검사를 통해 도구 호출을 자동으로 승인하여 작업이 요청과 일치하는지 확인합니다. 현재 연구 미리보기입니다 |52| `auto` | 배경 안전 검사를 통해 도구 호출을 자동으로 승인하여 작업이 요청과 일치하는지 확인합니다. 현재 연구 미리보기입니다 |

53| `dontAsk` | `/permissions` 또는 `permissions.allow` 규칙을 통해 사전 승인되지 않은 한 도구를 자동으로 거부합니다 |53| `dontAsk` | `/permissions` 또는 `permissions.allow` 규칙을 통해 사전 승인되지 않은 한 도구를 자동으로 거부합니다 |

54| `bypassPermissions` | 모든 권한 프롬프트를 건너뜁니다. 파일 시스템 루트 또는 홈 디렉토리 제거(예: `rm -rf /` 및 `rm -rf ~`)는 모델 오류에 대한 회로 차단기로 여전히 프롬프트합니다 |54| `bypassPermissions` | 명시적 `ask` 규칙으로 강제되는 권한 프롬프트를 제외한 모든 권한 프롬프트를 건너뜁니다. 파일 시스템 루트 또는 홈 디렉토리 제거(예: `rm -rf /` 및 `rm -rf ~`)는 모델 오류에 대한 회로 차단기로 여전히 프롬프트합니다 |

55 55 

56<Warning>56<Warning>

57 `bypassPermissions` 모드는 `.git`, `.config/git`, `.claude`, `.vscode`, `.idea`, `.husky`, `.cargo`, `.devcontainer`, `.yarn`, `.mvn`에 대한 쓰기를 포함한 모든 권한 프롬프트를 건너뜁니다. 파일 시스템 루트 또는 홈 디렉토리를 대상으로 하는 제거(예: `rm -rf /` 및 `rm -rf ~`)는 모델 오류에 대한 회로 차단기로 여전히 프롬프트합니다. 이 모드는 Claude Code가 손상을 일으킬 수 없는 컨테이너 또는 VM과 같은 격리된 환경에서만 사용합니다. 관리자는 [관리형 설정](#managed-settings)에서 `permissions.disableBypassPermissionsMode`를 `"disable"`로 설정하여 이 모드를 방지할 수 있습니다.57 `bypassPermissions` 모드는 `.git`, `.config/git`, `.claude`, `.vscode`, `.idea`, `.husky`, `.cargo`, `.devcontainer`, `.yarn`, `.mvn`에 대한 쓰기를 포함한 모든 권한 프롬프트를 건너뜁니다. 명시적 `ask` 규칙은 여전히 프롬프트를 강제하며, 파일 시스템 루트 또는 홈 디렉토리를 대상으로 하는 제거(예: `rm -rf /` 및 `rm -rf ~`)는 모델 오류에 대한 회로 차단기로 여전히 프롬프트합니다. 이 모드는 Claude Code가 손상을 일으킬 수 없는 컨테이너 또는 VM과 같은 격리된 환경에서만 사용합니다. 관리자는 [관리형 설정](#managed-settings)에서 `permissions.disableBypassPermissionsMode`를 `"disable"`로 설정하여 이 모드를 방지할 수 있습니다.

58</Warning>58</Warning>

59 59 

60`bypassPermissions` 또는 `auto` 모드가 사용되는 것을 방지하려면 [설정 파일](/ko/settings#settings-files)에서 `permissions.disableBypassPermissionsMode` 또는 `permissions.disableAutoMode`를 `"disable"`로 설정합니다. 이들은 재정의될 수 없는 [관리형 설정](#managed-settings)에서 가장 유용합니다.60`bypassPermissions` 또는 `auto` 모드가 사용되는 것을 방지하려면 [설정 파일](/ko/settings#settings-files)에서 `permissions.disableBypassPermissionsMode` 또는 `permissions.disableAutoMode`를 `"disable"`로 설정합니다. 이들은 재정의될 수 없는 [관리형 설정](#managed-settings)에서 가장 유용합니다.


91| `Read(./.env)` | 현재 디렉토리의 `.env` 파일 읽기와 일치합니다 |91| `Read(./.env)` | 현재 디렉토리의 `.env` 파일 읽기와 일치합니다 |

92| `WebFetch(domain:example.com)` | example.com으로의 가져오기 요청과 일치합니다 |92| `WebFetch(domain:example.com)` | example.com으로의 가져오기 요청과 일치합니다 |

93 93 

94<h3 id="match-by-input-parameter">

95 입력 매개변수로 일치

96</h3>

97 

98거부 및 요청 규칙은 `Tool(param:value)`를 사용하여 모든 도구의 최상위 입력 매개변수와 일치할 수 있습니다. 규칙은 Claude가 해당 매개변수가 정확한 값으로 설정된 도구를 호출할 때 일치합니다. 이 구문은 거부 및 요청 규칙용입니다. 한 매개변수 값에 대한 허용 규칙은 호출이 전반적으로 안전하다는 것을 확립하지 않으므로, 허용 규칙은 각 도구의 자체 지정자 구문을 계속 사용합니다. 이는 도구가 허용하는 모든 스칼라 매개변수에 대해 작동합니다:

99 

100| 규칙 | 일치 |

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

102| `Agent(model:opus)` | Opus 모델 계층을 요청하는 Agent 호출 |

103| `Agent(isolation:worktree)` | git worktree를 요청하는 Agent 호출 |

104| `Bash(run_in_background:true)` | 백그라운드에서 실행되는 Bash 호출 |

105 

106매개변수 일치는 다음 규칙을 따릅니다:

107 

108* 매개변수 이름은 Agent 도구의 `model`과 같이 도구 입력의 직접 필드여야 합니다. 객체 또는 배열 내에 중첩된 필드는 일치 가능하지 않습니다

109* 각 규칙은 하나의 매개변수를 지정합니다. `model`과 `isolation` 모두에 대해 게이트하려면, 한 규칙에 결합하는 대신 `Agent(model:opus)` 및 `Agent(isolation:worktree)` 두 규칙을 작성합니다

110* 값은 `*`를 와일드카드로 지원하여 모든 문자 시퀀스와 일치하므로, `Agent(isolation:*)`는 모든 명시적 격리 값과 일치합니다. `*` 없으면 일치는 정확합니다

111* 모델이 생략한 매개변수는 절대 일치하지 않으므로, `Agent(model:*)`는 `model`을 설정하지 않은 호출과 일치하지 않습니다

112* 값은 정규화 전에 Claude가 보내는 리터럴 입력과 비교됩니다. `Agent(model:opus)`는 별칭 `opus`와 일치하지만 전체 모델 ID와는 일치하지 않습니다. [`--verbose`](/ko/cli-reference)로 실행하여 각 도구 호출의 정확한 매개변수 이름과 값을 확인합니다

113* 콜론 주위의 공백은 무시됩니다

114 

115도구가 자체 정규화 규칙으로 이미 일치하는 필드는 이 방식으로 일치 가능하지 않습니다: Bash 및 PowerShell의 `command`, Read, Edit 및 Write의 `file_path`, Grep 및 Glob의 `path`, NotebookEdit의 `notebook_path`, WebFetch의 `url`. `Bash(command:rm *)`와 같은 규칙은 복합 명령으로 우회 가능하므로, Claude Code는 이를 무시하고 시작 경고를 발생시킵니다. 대신 `Bash(rm *)`, `Read(./path)` 또는 `WebFetch(domain:host)`를 사용합니다.

116 

94<h3 id="wildcard-patterns">117<h3 id="wildcard-patterns">

95 와일드카드 패턴118 와일드카드 패턴

96</h3>119</h3>


118 141 

119권한 대화 상자는 명령 접두사에 대해 "예, 다시 묻지 않기"를 선택할 때 공백으로 구분된 형식을 작성합니다. `:*` 형식은 패턴의 끝에서만 인식됩니다. `Bash(git:* push)`와 같은 패턴에서 콜론은 리터럴 문자로 취급되며 git 명령과 일치하지 않습니다.142권한 대화 상자는 명령 접두사에 대해 "예, 다시 묻지 않기"를 선택할 때 공백으로 구분된 형식을 작성합니다. `:*` 형식은 패턴의 끝에서만 인식됩니다. `Bash(git:* push)`와 같은 패턴에서 콜론은 리터럴 문자로 취급되며 git 명령과 일치하지 않습니다.

120 143 

144<h3 id="tool-name-wildcards">

145 도구 이름 와일드카드

146</h3>

147 

148거부 및 요청 규칙은 도구 이름 위치에서도 glob 패턴을 허용합니다. 패턴은 전체 도구 이름과 일치해야 합니다: `"*"`는 모든 도구와 일치하며, `"mcp__*"`는 모든 서버의 모든 MCP 도구와 일치합니다. 단순 이름 glob 거부 규칙과 일치하는 도구는 Claude의 컨텍스트에서 제거되며, 이는 단순 도구 이름과 동일합니다. 이 구성은 모든 MCP 도구를 거부합니다:

149 

150```json theme={null}

151{

152 "permissions": {

153 "deny": [

154 "mcp__*"

155 ]

156 }

157}

158```

159 

160허용 규칙은 리터럴 `mcp__<server>__` 접두사 이후에만 도구 이름 glob을 허용합니다. 서버 세그먼트는 glob이 없어야 하므로 규칙이 구성한 특정 서버를 지정합니다. `mcp__puppeteer__*`는 `puppeteer` 서버의 모든 도구와 일치하며, `mcp__github__get_*`는 해당 `get_` 도구와 일치합니다. `"*"`, `"B*"`, 또는 `"mcp__*"`와 같은 고정되지 않은 허용 glob은 경고와 함께 건너뛰어지며 자동으로 승인되지 않습니다.

161 

162도구 이름이 알려진 도구와 일치하지 않는 거부 또는 요청 규칙은 오타를 포착하기 위해 시작 경고를 생성합니다. `_` 또는 `*`를 포함하는 도구 이름은 확인에서 제외됩니다.

163 

164트랜스크립트 및 권한 대화 상자에서 도구에 대해 표시되는 레이블은 정규 이름과 다를 수 있습니다. 예를 들어, 트랜스크립트에서 `Stop Task`로 표시되는 도구의 정규 이름은 `TaskStop`입니다. 권한 규칙 및 [hook 매처](/ko/hooks)는 정규 이름만 일치시키므로, `Stop Task`로 작성된 규칙은 일치하지 않습니다. 거부 및 요청 규칙의 경우, 위의 시작 경고가 불일치를 포착합니다. [도구 참조](/ko/tools-reference)에 나열된 정규 이름을 사용합니다.

165 

121<h2 id="tool-specific-permission-rules">166<h2 id="tool-specific-permission-rules">

122 도구별 권한 규칙167 도구별 권한 규칙

123</h2>168</h2>


266 WebFetch311 WebFetch

267</h3>312</h3>

268 313 

269* `WebFetch(domain:example.com)` example.com으로의 가져오기 요청과 일치합니다314WebFetch 규칙은 `domain:` 접두사를 사용하고 요청된 URL의 호스트명과 일치합니다. 일치는 대소문자를 구분하지 않으며, `*` 와일드카드를 지원하고, 규칙과 호스트명 모두에서 후행 `.`을 제거하므로 `example.com.` `example.com`은 동일하게 취급됩니다.

315 

316* `WebFetch(domain:example.com)`은 `example.com`으로의 요청과 일치합니다

317* `WebFetch(domain:*.example.com)`은 `api.example.com` 또는 `a.b.example.com`과 같은 모든 깊이의 모든 서브도메인과 일치하지만 `example.com` 자체는 일치하지 않습니다

318* `WebFetch(domain:*)`는 모든 도메인과 일치하며 베어 `WebFetch` 규칙과 동등합니다

319 

320`*`는 선행 `*.` 또는 전체 패턴으로서만 `.`을 가로질러 일치합니다. 다른 곳에서는 하나의 레이블 내에 머물므로 `WebFetch(domain:github.*)`는 `github.io`와 일치하지만 공격자가 등록할 수 있는 도메인인 `github.evil.com`과는 일치하지 않습니다.

270 321 

271<h3 id="mcp">322<h3 id="mcp">

272 MCP323 MCP


296}347}

297```348```

298 349 

350<h3 id="cd">

351 Cd

352</h3>

353 

354`Cd` 규칙은 [`/cd` 명령](/ko/commands)이 세션을 이동할 수 있는 디렉토리를 제어합니다. `Cd`는 모델 호출 가능 도구가 아닙니다: Claude는 이를 호출할 수 없으며 규칙은 사용자가 직접 `/cd`를 실행할 때만 적용됩니다.

355 

356베어 `Cd` deny 규칙은 `/cd`를 완전히 비활성화합니다. `Cd(<path-pattern>)` deny 규칙은 일치하는 대상을 차단합니다. Deny 규칙은 대상의 모든 철자를 확인하며, 이것이 해결되는 각 심볼릭 링크 홉을 포함하므로 한 경로에 대해 작성된 규칙은 그것으로 해결되는 대상도 차단합니다.

357 

358`Cd` allow 규칙을 추가하면 `/cd`를 허용 목록 모드로 전환합니다: 해결된 대상 디렉토리는 allow 규칙 중 하나와 일치해야 하거나 `/cd`는 거부합니다. `Cd` 규칙이 구성되지 않으면 `/cd`는 기본 동작을 유지하고 익숙하지 않은 디렉토리를 신뢰하도록 프롬프트합니다.

359 

360경로 패턴은 [Read 및 Edit 규칙](#read-and-edit)의 `//`, `~/` 및 `/` 앵커를 공유하지만 일치는 gitignore 스타일이 아닌 전체 디렉토리 경로에 앵커됩니다. `*`는 정확히 하나의 경로 세그먼트와 일치하고 `**`는 세그먼트 전체에서 일치합니다. 후행 `/**`는 또한 명명된 루트와 일치합니다.

361 

362| 규칙 | 일치 | 일치하지 않음 |

363| --------------------- | ------------------------------- | -------------------------- |

364| `Cd(~/code/*)` | `~/code/app` | `~/code/app/src`, `~/code` |

365| `Cd(~/code/**)` | `~/code` 및 그 아래의 모든 디렉토리 | `~/code` 외부의 디렉토리 |

366| `Cd(**/node_modules)` | 어느 깊이에서나 모든 `node_modules` 디렉토리 | `node_modules/pkg` |

367 

299<h2 id="extend-permissions-with-hooks">368<h2 id="extend-permissions-with-hooks">

300 훅으로 권한 확장369 훅으로 권한 확장

301</h2>370</h2>


318 387 

319추가 디렉토리의 파일은 원래 작업 디렉토리와 동일한 권한 규칙을 따릅니다: 프롬프트 없이 읽을 수 있게 되며, 파일 편집 권한은 현재 권한 모드를 따릅니다.388추가 디렉토리의 파일은 원래 작업 디렉토리와 동일한 권한 규칙을 따릅니다: 프롬프트 없이 읽을 수 있게 되며, 파일 편집 권한은 현재 권한 모드를 따릅니다.

320 389 

390세션의 기본 작업 디렉토리를 다른 디렉토리를 추가하는 대신 변경하려면 [`/cd`](/ko/commands)를 사용합니다. `/cd` 명령은 Claude Code v2.1.169 이상이 필요합니다. `/add-dir`과 달리 세션을 재배치합니다: 새 디렉토리의 `CLAUDE.md`가 로드되고 `--resume`은 해당 위치에서 세션을 찾습니다.

391 

321<h3 id="additional-directories-grant-file-access-not-configuration">392<h3 id="additional-directories-grant-file-access-not-configuration">

322 추가 디렉토리는 파일 액세스를 부여하며, 구성은 아닙니다393 추가 디렉토리는 파일 액세스를 부여하며, 구성은 아닙니다

323</h3>394</h3>


331| 구성 | `--add-dir`에서 로드됨 |402| 구성 | `--add-dir`에서 로드됨 |

332| :--------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- |403| :--------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- |

333| `.claude/skills/`의 [Skills](/ko/skills) | 예, 라이브 리로드 포함 |404| `.claude/skills/`의 [Skills](/ko/skills) | 예, 라이브 리로드 포함 |

405| `.claude/agents/`의 [Subagents](/ko/sub-agents) | 예 |

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

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

336 408 

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

338 410 

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

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

341* **구성 디렉토리에서 시작**: 원하는 `.claude/` 구성이 포함된 디렉토리에서 Claude Code를 실행합니다413* **구성 디렉토리에서 시작**: 원하는 `.claude/` 구성이 포함된 디렉토리에서 Claude Code를 실행합니다

342 414 

343<h2 id="how-permissions-interact-with-sandboxing">415<h2 id="how-permissions-interact-with-sandboxing">


356* 샌드박스의 파일 시스템 제한은 [`sandbox.filesystem`](/ko/sandboxing) 설정을 Read 및 Edit deny 규칙과 결합합니다. 둘 다 최종 샌드박스 경계로 병합됩니다428* 샌드박스의 파일 시스템 제한은 [`sandbox.filesystem`](/ko/sandboxing) 설정을 Read 및 Edit deny 규칙과 결합합니다. 둘 다 최종 샌드박스 경계로 병합됩니다

357* 네트워크 제한은 WebFetch 권한 규칙을 샌드박스의 `allowedDomains` 및 `deniedDomains` 목록과 결합합니다429* 네트워크 제한은 WebFetch 권한 규칙을 샌드박스의 `allowedDomains` 및 `deniedDomains` 목록과 결합합니다

358 430 

359샌드박싱이 `autoAllowBashIfSandboxed: true`로 활성화되면(기본값), 권한에 `ask: Bash(*)` 포함되어 있어도 샌드박스된 Bash 명령은 프롬프트 없이 실행됩니다. 샌드박스 경계는 명령별 프롬프트를 대체합니다. 명시적 deny 규칙은 여전히 적용되며, `/`, 홈 디렉터리 또는 기타 중요한 시스템 경로를 대상으로 하는 `rm` 또는 `rmdir` 명령은 여전히 프롬프트를 트리거합니다. [샌드박스 모드](/ko/sandboxing#sandbox-modes)를 참조하여 이 동작을 변경합니다.431샌드박싱이 `autoAllowBashIfSandboxed: true`로 활성화되면(기본값), 권한에 `Bash` ask 규칙이 포함되어 있거나 [동등한 `Bash(*)` 형식](#match-all-uses-of-a-tool)이 포함되어 있어도 샌드박스된 Bash 명령은 프롬프트 없이 실행됩니다. 샌드박스 경계는 전체 도구 프롬프트를 대체합니다. `Bash(git push *)`와 같은 콘텐츠 범위 ask 규칙은 여전히 프롬프트를 강제하고, 명시적 deny 규칙은 여전히 적용되며, `/`, 홈 디렉터리 또는 기타 중요한 시스템 경로를 대상으로 하는 `rm` 또는 `rmdir` 명령은 여전히 프롬프트를 트리거합니다. 제외된 명령과 같이 샌드박스에서 실행되지 않는 명령은 일반적인 `Bash` ask 규칙을 따릅니다. [샌드박스 모드](/ko/sandboxing#sandbox-modes)를 참조하여 이 동작을 변경합니다.

360 432 

361<h2 id="managed-settings">433<h2 id="managed-settings">

362 관리형 설정434 관리형 설정


422</h2>494</h2>

423 495 

424* [설정](/ko/settings): 권한 설정 테이블을 포함한 완전한 구성 참조496* [설정](/ko/settings): 권한 설정 테이블을 포함한 완전한 구성 참조

497* [자동 모드 구성](/ko/auto-mode-config): 자동 모드 분류기에 조직이 신뢰하는 인프라를 알려줍니다

425* [샌드박싱](/ko/sandboxing): Bash 명령에 대한 OS 수준 파일 시스템 및 네트워크 격리498* [샌드박싱](/ko/sandboxing): Bash 명령에 대한 OS 수준 파일 시스템 및 네트워크 격리

426* [인증](/ko/authentication): Claude Code에 대한 사용자 액세스 설정499* [인증](/ko/authentication): Claude Code에 대한 사용자 액세스 설정

427* [보안](/ko/security): 보안 보호 및 모범 사례500* [보안](/ko/security): 보안 보호 및 모범 사례

platforms.md +4 −4

Details

4 4 

5# 플랫폼 및 통합5# 플랫폼 및 통합

6 6 

7> Claude Code를 실행할 위치를 선택하고 연결할 항목을 결정합니다. CLI, Desktop, VS Code, JetBrains, 웹 및 Chrome, Slack, CI/CD와 같은 통합을 비교합니다.7> Claude Code를 실행할 위치를 선택하고 연결할 항목을 결정합니다. CLI, Desktop, VS Code, JetBrains, 웹, 모바일 및 Chrome, Slack, CI/CD와 같은 통합을 비교합니다.

8 8 

9Claude Code는 모든 곳에서 동일한 기본 엔진을 실행하지만, 각 플랫폼은 다양한 작업 방식에 맞게 조정됩니다. 이 페이지는 워크플로우에 적합한 플랫폼을 선택하고 이미 사용 중인 도구를 연결하는 데 도움을 줍니다.9Claude Code는 모든 곳에서 동일한 기본 엔진을 실행하지만, 각 플랫폼은 다양한 작업 방식에 맞게 조정됩니다. 이 페이지는 워크플로우에 적합한 플랫폼을 선택하고 이미 사용 중인 도구를 연결하는 데 도움을 줍니다.

10 10 


12 Claude Code를 실행할 위치12 Claude Code를 실행할 위치

13</h2>13</h2>

14 14 

15프로젝트가 있는 위치와 작업 방식에 따라 플랫폼을 선택합니다.15작업 방식과 프로젝트가 있는 위치에 따라 플랫폼을 선택합니다.

16 16 

17| 플랫폼 | 최적 용도 | 제공 기능 |17| 플랫폼 | 최적 용도 | 제공 기능 |

18| :-------------------------------- | :----------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |18| :-------------------------------- | :----------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |

19| [CLI](/ko/quickstart) | 터미널 워크플로우, 스크립팅, 원격 서버 | 전체 기능 세트, [Agent SDK](/ko/headless), macOS의 [컴퓨터 사용](/ko/computer-use) (Pro 및 Max), 타사 제공자 |19| [CLI](/ko/quickstart) | 터미널 워크플로우, 스크립팅, 원격 서버 | 전체 기능 세트, [Agent SDK](/ko/headless), macOS의 [컴퓨터 사용](/ko/computer-use) (Pro 및 Max), 타사 제공자 |

20| [Desktop](/ko/desktop) | 시각적 검토, 병렬 세션, 관리형 설정 | Diff 뷰어, 앱 미리보기, Pro 및 Max의 [컴퓨터 사용](/ko/desktop#let-claude-use-your-computer) 및 [Dispatch](/ko/desktop#sessions-from-dispatch) |20| [Desktop](/ko/desktop) | 시각적 검토, 병렬 세션, 관리형 설정 | Diff 뷰어, 앱 미리보기, Pro 및 Max의 [컴퓨터 사용](/ko/desktop#let-claude-use-your-computer) 및 [Dispatch](/ko/desktop#sessions-from-dispatch) |

21| [VS Code](/ko/vs-code) | 터미널로 전환하지 않고 VS Code 내에서 작업 | 인라인 Diff, 통합 터미널, 파일 컨텍스트 |21| [VS Code](/ko/vs-code) | VS Code 내에서 터미널로 전환하지 않고 작업 | 인라인 Diff, 통합 터미널, 파일 컨텍스트 |

22| [JetBrains](/ko/jetbrains) | IntelliJ, PyCharm, WebStorm 또는 기타 JetBrains IDE 내에서 작업 | Diff 뷰어, 선택 공유, 터미널 세션 |22| [JetBrains](/ko/jetbrains) | IntelliJ, PyCharm, WebStorm 또는 기타 JetBrains IDE 내에서 작업 | Diff 뷰어, 선택 공유, 터미널 세션 |

23| [Web](/ko/claude-code-on-the-web) | 많은 조작이 필요하지 않은 장기 실행 작업 또는 오프라인 상태에서도 계속되어야 하는 작업 | Anthropic 관리형 클라우드, 연결 해제 후에도 계속 실행 |23| [Web](/ko/claude-code-on-the-web) | 많은 조작이 필요하지 않은 장기 실행 작업 또는 오프라인 상태에서도 계속되어야 하는 작업 | Anthropic 관리형 클라우드, 연결 해제 후에도 계속 실행 |

24| Mobile | 컴퓨터에서 멀리 떨어져 있을 때 작업 시작 및 모니터링 | iOS 및 Android용 Claude 앱의 클라우드 세션, 로컬 세션용 [Remote Control](/ko/remote-control), Pro 및 Max의 Desktop으로 [Dispatch](/ko/desktop#sessions-from-dispatch) |24| Mobile | 컴퓨터에서 멀리 떨어져 있을 때 작업 시작 및 모니터링 | iOS 및 Android용 Claude 앱의 클라우드 세션, 로컬 세션용 [Remote Control](/ko/remote-control), Pro 및 Max의 Desktop으로 [Dispatch](/ko/desktop#sessions-from-dispatch) |

25 25 

26CLI는 터미널 기반 작업을 위한 가장 완전한 플랫폼입니다. 스크립팅 및 Agent SDK는 CLI 전용입니다. 타사 제공자는 [VS Code](/ko/vs-code#use-third-party-providers)에서도 작동합니다. Enterprise [Desktop](/ko/desktop) 배포는 Vertex AI 및 게이트웨이 제공자를 지원합니다. Bedrock 또는 Foundry의 경우 Desktop 대신 CLI 또는 VS Code를 사용합니다. Desktop과 IDE 확장 프로그램은 일부 CLI 전용 기능을 포기하는 대신 시각적 검토와 더 긴밀한 편집기 통합을 제공합니다. 웹은 Anthropic의 클라우드에서 실행되므로 연결을 해제한 후에도 작업이 계속됩니다. Mobile은 동일한 클라우드 세션으로의 씬 클라이언트이거나 Remote Control을 통한 로컬 세션으로의 씬 클라이언트이며, Dispatch를 통해 Desktop으로 작업을 보낼 수 있습니다.26CLI는 터미널 기반 작업을 위한 가장 완전한 플랫폼입니다. 스크립팅 및 Agent SDK는 CLI 전용입니다. 타사 제공자는 [VS Code](/ko/vs-code#use-third-party-providers)에서도 작동합니다. Enterprise [Desktop](/ko/desktop) 배포는 Vertex AI 및 게이트웨이 제공자를 지원합니다. Bedrock 또는 Foundry의 경우 CLI 또는 VS Code를 사용하거나, 해당 제공자에서 Code 탭을 실행하는 [Cowork on 3P research preview](https://claude.com/docs/cowork/3p/overview)를 사용합니다. Desktop과 IDE 확장 프로그램은 일부 CLI 전용 기능을 포기하는 대신 시각적 검토와 더 긴밀한 편집기 통합을 제공합니다. 웹은 Anthropic의 클라우드에서 실행되므로 연결을 해제한 후에도 작업이 계속됩니다. Mobile은 동일한 클라우드 세션으로의 씬 클라이언트이거나 Remote Control을 통한 로컬 세션으로의 씬 클라이언트이며, Dispatch를 통해 Desktop으로 작업을 보낼 수 있습니다.

27 27 

28동일한 프로젝트에서 여러 플랫폼을 혼합하여 사용할 수 있습니다. 구성, 프로젝트 메모리 및 MCP 서버는 로컬 플랫폼 간에 공유됩니다.28동일한 프로젝트에서 여러 플랫폼을 혼합하여 사용할 수 있습니다. 구성, 프로젝트 메모리 및 MCP 서버는 로컬 플랫폼 간에 공유됩니다.

29 29 

plugin-hints.md +7 −4

Details

16 작동 방식16 작동 방식

17</h2>17</h2>

18 18 

19Claude Code는 Bash 및 PowerShell 도구를 통해 실행하는 모든 명령과 [hook](/ko/hooks) 명령에 대해 [`CLAUDECODE`](/ko/env-vars) 환경 변수를 `1`로 설정합니다. CLI가 해당 변수를 감지하면 자체 종료 `<claude-code-hint />` 태그를 stderr에 작성합니다. hook 명령에서 힌트 태그는 제거되고 무시됩니다. Bash 및 PowerShell 도구 출력만 설치 프롬프트를 트리거합니다.19Claude Code는 Bash 및 PowerShell 도구를 통해 실행하는 모든 명령과 [hook](/ko/hooks) 명령에 대해 [`CLAUDECODE`](/ko/env-vars) 환경 변수를 `1`로 설정합니다. {/* min-version: 2.1.172 */}v2.1.172부터는 해당 동일한 서브프로세스에서 [`CLAUDE_CODE_CHILD_SESSION`](/ko/env-vars)도 `1`로 설정합니다. CLI가 이러한 변수 중 하나를 감지하면 자체 종료 `<claude-code-hint />` 태그를 stderr에 작성합니다. hook 명령에서 힌트 태그는 제거되고 무시됩니다. Bash 및 PowerShell 도구 출력만 설치 프롬프트를 트리거합니다.

20 20 

21Claude Code가 명령 출력을 받으면 다음을 수행합니다:21Claude Code가 명령 출력을 받으면 다음을 수행합니다:

22 22 


31 힌트 내보내기31 힌트 내보내기

32</h2>32</h2>

33 33 

34`CLAUDECODE` 환경 변수에서 내보내기를 제어하여 마커가 일반 사용자의 터미널에 나타나지 않도록 합니다. 그런 다음 태그를 stderr에 자체 줄로 작성합니다.34환경 변수에서 내보내기를 제어하여 마커가 일반 사용자가 CLI를 직접 실행할 때 나타나지 않도록 다음, 태그를 stderr에 자체 줄로 작성합니다. 확인할 변수를 선택합니다:

35 35 

36다음 예제는 공식 마켓플레이스에서 `example-cli`라는 플러그인에 대한 힌트를 내보냅니다:36* `CLAUDECODE`: 모든 Claude Code 버전에서 설정되므로 가장 많은 세션에 도달합니다. Claude Code가 시작하는 tmux 세션 및 stdio MCP 서버 서브프로세스에서도 설정되며, IDE 확장 프로그램은 일반 사용자가 CLI를 직접 실행할 수 있는 통합 터미널에서 설정합니다.

37* {/* min-version: 2.1.172 */}`CLAUDE_CODE_CHILD_SESSION`: 도구 호출, 훅 명령 및 [상태 줄](/ko/statusline) 명령과 같이 Claude Code 자체가 생성하는 서브프로세스에서만 설정되므로 태그가 일반적으로 사용자 터미널에 도달하지 않습니다. tmux 서버와 같이 세션 내에서 시작된 장기 실행 프로세스는 변수를 캡처하므로 해당 프로세스에서 나중에 시작된 셸은 여전히 원본 태그를 표시합니다. Claude Code v2.1.172 이상이 필요하므로 이전 버전의 세션은 힌트를 놓칩니다.

38 

39다음 예제는 최대 도달 범위를 위해 `CLAUDECODE`에서 제어하고 공식 마켓플레이스의 `example-cli`라는 플러그인에 대한 힌트를 내보냅니다:

37 40 

38<CodeGroup>41<CodeGroup>

39 ```javascript Node.js theme={null}42 ```javascript Node.js theme={null}


147나머지 지침은 권장되지만 적용되지 않습니다. Claude Code는 CLI가 이를 따르는지 관찰할 수 없습니다:150나머지 지침은 권장되지만 적용되지 않습니다. Claude Code는 CLI가 이를 따르는지 관찰할 수 없습니다:

148 151 

149* **stderr에 작성**: stderr는 `example-cli deploy | jq`와 같은 셸 파이프라인에서 태그를 제외합니다. Claude Code는 두 스트림을 모두 스캔하므로 stdout도 작동합니다.152* **stderr에 작성**: stderr는 `example-cli deploy | jq`와 같은 셸 파이프라인에서 태그를 제외합니다. Claude Code는 두 스트림을 모두 스캔하므로 stdout도 작동합니다.

150* **`CLAUDECODE`에서 제어**: `CLAUDECODE` 환경 변수가 설정된 경우에만 내보냅니다. 이렇게 하면 마커가 CLI를 직접 실행하는 사용자에게 나타나지 않습니다.153* **환경 변수에서 제어**: `CLAUDECODE` 또는 `CLAUDE_CODE_CHILD_SESSION`이 설정된 경우에만 내보냅니다. 변수의 차이점은 [힌트 내보내기](#emit-the-hint)를 참조하세요.

151 154 

152<h2 id="get-your-plugin-into-the-official-marketplace">155<h2 id="get-your-plugin-into-the-official-marketplace">

153 공식 마켓플레이스에 플러그인 추가156 공식 마켓플레이스에 플러그인 추가

Details

171| `plugins` | array | 사용 가능한 플러그인 목록 | 아래 참조 |171| `plugins` | array | 사용 가능한 플러그인 목록 | 아래 참조 |

172 172 

173<Note>173<Note>

174 **예약된 이름**: 다음 마켓플레이스 이름은 공식 Anthropic 사용을 위해 예약되어 있으며 타사 마켓플레이스에서 사용할 수 없습니다: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `anthropic-agent-skills`, `knowledge-work-plugins`, `life-sciences`, `claude-for-legal`, `claude-for-financial-services`, `financial-services-plugins`. 공식 마켓플레이스를 사칭하는 이름(예: `official-claude-plugins` 또는 `anthropic-tools-v2`)도 차단됩니다.174 **예약된 이름**: 다음 마켓플레이스 이름은 공식 Anthropic 사용을 위해 예약되어 있으며 타사 마켓플레이스에서 사용할 수 없습니다: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `claude-plugins-community`, `claude-community`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `anthropic-agent-skills`, `knowledge-work-plugins`, `life-sciences`, `claude-for-legal`, `claude-for-financial-services`, `financial-services-plugins`. 공식 마켓플레이스를 사칭하는 이름(예: `official-claude-plugins` 또는 `anthropic-tools-v2`)도 차단됩니다.

175</Note>175</Note>

176 176 

177<h3 id="owner-fields">177<h3 id="owner-fields">


203 203 

204`plugins` 배열의 각 플러그인 항목은 플러그인과 플러그인을 찾을 위치를 설명합니다. [플러그인 매니페스트 스키마](/ko/plugins-reference#plugin-manifest-schema)의 모든 필드(예: `description`, `version`, `author`, `commands`, `hooks` 등)와 이러한 마켓플레이스 특정 필드를 포함할 수 있습니다: `source`, `category`, `tags` 및 `strict`.204`plugins` 배열의 각 플러그인 항목은 플러그인과 플러그인을 찾을 위치를 설명합니다. [플러그인 매니페스트 스키마](/ko/plugins-reference#plugin-manifest-schema)의 모든 필드(예: `description`, `version`, `author`, `commands`, `hooks` 등)와 이러한 마켓플레이스 특정 필드를 포함할 수 있습니다: `source`, `category`, `tags` 및 `strict`.

205 205 

206<h3 id="required-fields">206<h3 id="required-fields-1">

207 필수 필드207 필수 필드

208</h3>208</h3>

209 209 


253플러그인이 로컬 머신에 복제되거나 복사되면 `~/.claude/plugins/cache`의 로컬 버전 관리 플러그인 캐시에 복사됩니다.253플러그인이 로컬 머신에 복제되거나 복사되면 `~/.claude/plugins/cache`의 로컬 버전 관리 플러그인 캐시에 복사됩니다.

254 254 

255| 소스 | 유형 | 필드 | 참고 |255| 소스 | 유형 | 필드 | 참고 |

256| ------------ | ----------------------------- | ---------------------------------- | -------------------------------------------------- |256| ------------ | ----------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------ |

257| 상대 경로 | `string` (예: `"./my-plugin"`) | 없음 | 마켓플레이스 저장소 내의 로컬 디렉터리. `./`로 시작해야 합니다 |257| 상대 경로 | `string` (예: `"./my-plugin"`) | 없음 | 마켓플레이스 저장소 내의 로컬 디렉터리. `./`로 시작해야 합니다. 마켓플레이스 루트에 상대적으로 해석되며, `.claude-plugin/` 디렉터리가 아닙니다 |

258| `github` | object | `repo`, `ref?`, `sha?` | |258| `github` | object | `repo`, `ref?`, `sha?` | |

259| `url` | object | `url`, `ref?`, `sha?` | Git URL 소스 |259| `url` | object | `url`, `ref?`, `sha?` | Git URL 소스 |

260| `git-subdir` | object | `url`, `path`, `ref?`, `sha?` | git 저장소 내의 하위 디렉터리. 모노레포의 대역폭을 최소화하기 위해 희소하게 복제합니다 |260| `git-subdir` | object | `url`, `path`, `ref?`, `sha?` | git 저장소 내의 하위 디렉터리. 모노레포의 대역폭을 최소화하기 위해 희소하게 복제합니다 |


269 예를 들어, `acme-corp/plugin-catalog`에서 호스팅되는 마켓플레이스(마켓플레이스 소스)는 `acme-corp/code-formatter`에서 가져온 플러그인을 나열할 수 있습니다(플러그인 소스). 마켓플레이스 소스와 플러그인 소스는 다양한 저장소를 가리키며 독립적으로 고정됩니다.269 예를 들어, `acme-corp/plugin-catalog`에서 호스팅되는 마켓플레이스(마켓플레이스 소스)는 `acme-corp/code-formatter`에서 가져온 플러그인을 나열할 수 있습니다(플러그인 소스). 마켓플레이스 소스와 플러그인 소스는 다양한 저장소를 가리키며 독립적으로 고정됩니다.

270</Note>270</Note>

271 271 

272git 기반 소스 유형은 아래의 `github`, `url`, 및 `git-subdir`입니다. `ref`와 `sha`가 모두 설정되면 `sha`가 유효한 핀입니다. Claude Code는 고정된 커밋을 직접 가져오고 체크아웃하므로 분기 또는 태그가 업스트림에서 삭제되었더라도 커밋이 저장소에서 여전히 도달 가능한 한 설치가 성공합니다.

273 

272<h3 id="relative-paths">274<h3 id="relative-paths">

273 상대 경로275 상대 경로

274</h3>276</h3>


282}284}

283```285```

284 286 

285경로는 마켓플레이스 루트(`.claude-plugin/`을 포함하는 디렉터리)에 상대적으로 해석됩니다. 위의 예에서 `./plugins/my-plugin`은 `marketplace.json`이 `<repo>/.claude-plugin/marketplace.json`에 있더라도 `<repo>/plugins/my-plugin`을 가리킵니다. `.claude-plugin/` 외부로 나가기 위해 `../`를 사용하지 마세요.287경로는 마켓플레이스 루트(`.claude-plugin/`을 포함하는 디렉터리)에 상대적으로 해석됩니다. 위의 예에서 `./plugins/my-plugin`은 `marketplace.json`이 `<repo>/.claude-plugin/marketplace.json`에 있더라도 `<repo>/plugins/my-plugin`을 가리킵니다. 마켓플레이스 루트 외부로 나가기 위해 `../`를 사용하지 마세요.

286 288 

287<Note>289<Note>

288 상대 경로는 사용자가 Git(GitHub, GitLab 또는 git URL)을 통해 마켓플레이스를 추가할 때만 작동합니다. 사용자가 `marketplace.json` 파일에 대한 직접 URL을 통해 마켓플레이스를 추가하면 상대 경로가 올바르게 해석되지 않습니다. URL 기반 배포의 경우 GitHub, npm 또는 git URL 소스를 대신 사용합니다. 자세한 내용은 [문제 해결](#plugins-with-relative-paths-fail-in-url-based-marketplaces)을 참조하세요.290 상대 경로는 사용자가 Git(GitHub, GitLab 또는 git URL)을 통해 마켓플레이스를 추가할 때만 작동합니다. 사용자가 `marketplace.json` 파일에 대한 직접 URL을 통해 마켓플레이스를 추가하면 상대 경로가 올바르게 해석되지 않습니다. URL 기반 배포의 경우 GitHub, npm 또는 git URL 소스를 대신 사용합니다. 자세한 내용은 [문제 해결](#plugins-with-relative-paths-fail-in-url-based-marketplaces)을 참조하세요.


459 "source": "github",461 "source": "github",

460 "repo": "company/enterprise-plugin"462 "repo": "company/enterprise-plugin"

461 },463 },

462 "description": "엔터프라이즈 워크플로우 자동화 도구",464 "description": "Enterprise workflow automation tools",

463 "version": "2.1.0",465 "version": "2.1.0",

464 "author": {466 "author": {

465 "name": "Enterprise Team",467 "name": "Enterprise Team",


505* **`${CLAUDE_PLUGIN_ROOT}`**: hooks 및 MCP 서버 구성에서 이 변수를 사용하여 플러그인의 설치 디렉터리 내의 파일을 참조합니다. 플러그인이 설치될 때 캐시 위치에 복사되기 때문에 필요합니다. 플러그인 업데이트를 통해 유지되어야 하는 종속성 또는 상태의 경우 [`${CLAUDE_PLUGIN_DATA}`](/ko/plugins-reference#persistent-data-directory)를 대신 사용합니다.507* **`${CLAUDE_PLUGIN_ROOT}`**: hooks 및 MCP 서버 구성에서 이 변수를 사용하여 플러그인의 설치 디렉터리 내의 파일을 참조합니다. 플러그인이 설치될 때 캐시 위치에 복사되기 때문에 필요합니다. 플러그인 업데이트를 통해 유지되어야 하는 종속성 또는 상태의 경우 [`${CLAUDE_PLUGIN_DATA}`](/ko/plugins-reference#persistent-data-directory)를 대신 사용합니다.

506* **`strict: false`**: 이것이 false로 설정되어 있으므로 플러그인은 자신의 `plugin.json`이 필요하지 않습니다. 마켓플레이스 항목이 모든 것을 정의합니다. 아래의 [Strict 모드](#strict-mode)를 참조하세요.508* **`strict: false`**: 이것이 false로 설정되어 있으므로 플러그인은 자신의 `plugin.json`이 필요하지 않습니다. 마켓플레이스 항목이 모든 것을 정의합니다. 아래의 [Strict 모드](#strict-mode)를 참조하세요.

507 509 

510기본적으로 플러그인의 skills는 해당 `source` 아래의 `skills/` 디렉터리에서 로드되며, `skills` 아래에 나열된 모든 경로가 해당 스캔에 추가됩니다. 예외는 `source: "./"`와 같은 마켓플레이스 루트 소스이며, 여러 플러그인 항목이 하나의 `skills/` 폴더를 공유합니다. 이 경우 `skills/` 아래에 특정 하위 디렉터리를 나열하면 해당 목록이 항목의 완전한 집합이 되며, `skills/` 아래의 다른 디렉터리는 로드되지 않습니다. `skills/` 디렉터리 자체 또는 플러그인 루트를 나열하면 전체 스캔이 유지됩니다. 나열된 경로 중 어느 것도 존재하지 않으면 기본 스캔이 대신 실행됩니다.

511 

508<h3 id="strict-mode">512<h3 id="strict-mode">

509 Strict 모드513 Strict 모드

510</h3>514</h3>


1074* 플러그인 디렉터리에 필수 파일이 포함되어 있는지 확인합니다1078* 플러그인 디렉터리에 필수 파일이 포함되어 있는지 확인합니다

1075* GitHub 소스의 경우 저장소가 공개이거나 액세스 권한이 있는지 확인합니다1079* GitHub 소스의 경우 저장소가 공개이거나 액세스 권한이 있는지 확인합니다

1076* 플러그인 소스를 수동으로 복제/다운로드하여 테스트합니다1080* 플러그인 소스를 수동으로 복제/다운로드하여 테스트합니다

1081* 소스가 `ref`와 `sha`를 모두 고정하는 경우 삭제된 업스트림 분기 또는 태그는 설치를 차단하지 않습니다. 설치가 계속 실패하면 고정된 커밋이 저장소에 여전히 존재하는지 확인합니다

1077 1082 

1078<h3 id="private-repository-authentication-fails">1083<h3 id="private-repository-authentication-fails">

1079 개인 저장소 인증 실패1084 개인 저장소 인증 실패

plugins.md +9 −5

Details

197 플러그인 구조 개요197 플러그인 구조 개요

198</h2>198</h2>

199 199 

200skills를 사용하여 플러그인을 만들었지만, 플러그인에는 훨씬 더 많은 것이 포함될 수 있습니다: 사용자 정의 agents, hooks, MCP servers, LSP servers, 백그라운드 모니터.200skill을 사용하여 플러그인을 만들었지만, 플러그인에는 훨씬 더 많은 것이 포함될 수 있습니다: 사용자 정의 agents, hooks, MCP servers, LSP servers, 백그라운드 모니터.

201 201 

202<Warning>202<Warning>

203 **일반적인 실수**: `commands/`, `agents/`, `skills/`, `hooks/`를 `.claude-plugin/` 디렉토리 내에 넣지 마세요. `.claude-plugin/` 내에는 `plugin.json`만 들어갑니다. 다른 모든 디렉토리는 플러그인 루트 수준에 있어야 합니다.203 **일반적인 실수**: `commands/`, `agents/`, `skills/`, `hooks/`를 `.claude-plugin/` 디렉토리 내에 넣지 마세요. `.claude-plugin/` 내에는 `plugin.json`만 들어갑니다. 다른 모든 디렉토리는 플러그인 루트 수준에 있어야 합니다.


216| `bin/` | 플러그인 루트 | 플러그인이 활성화된 동안 Bash tool의 `PATH`에 추가되는 실행 파일 |216| `bin/` | 플러그인 루트 | 플러그인이 활성화된 동안 Bash tool의 `PATH`에 추가되는 실행 파일 |

217| `settings.json` | 플러그인 루트 | 플러그인이 활성화될 때 적용되는 기본 [설정](/ko/settings) |217| `settings.json` | 플러그인 루트 | 플러그인이 활성화될 때 적용되는 기본 [설정](/ko/settings) |

218 218 

219정확히 하나의 skill을 제공하는 플러그인은 `skills/` 디렉토리를 만드는 대신 `SKILL.md`를 플러그인 루트에 직접 배치할 수 있습니다. Claude Code는 이를 단일 skill로 로드하고 frontmatter `name` 필드를 호출 이름으로 사용합니다. 플러그인이 하나 이상의 skill로 성장할 수 있는 경우 `skills/` 레이아웃을 사용하세요.

220 

219<Note>221<Note>

220 **다음 단계**: 더 많은 기능을 추가할 준비가 되셨나요? [더 복잡한 플러그인 개발](#develop-more-complex-plugins)로 이동하여 agents, hooks, MCP servers, LSP servers를 추가하세요. 모든 플러그인 구성 요소의 완전한 기술 사양은 [플러그인 참조](/ko/plugins-reference)를 참조하세요.222 **다음 단계**: 더 많은 기능을 추가할 준비가 되셨나요? [더 복잡한 플러그인 개발](#develop-more-complex-plugins)로 이동하여 agents, hooks, MCP servers, LSP servers를 추가하세요. 모든 플러그인 구성 요소의 완전한 기술 사양은 [플러그인 참조](/ko/plugins-reference)를 참조하세요.

221</Note>223</Note>


343claude --plugin-dir ./my-plugin.zip345claude --plugin-dir ./my-plugin.zip

344```346```

345 347 

346`--plugin-dir` 플러그인이 설치된 마켓플레이스 플러그인과 동일한 이름을 가진 경우 로컬 복사본이 해당 세션에 우선합니다. 이를 통해 먼저 제거하지 않고도 이미 설치한 플러그인의 변경 사항을 테스트할 수 있습니다. 관리 설정에 의해 강제로 활성화된 마켓플레이스 플러그인은 유일한 예외이며 재정의할 수 없습니다.348`--plugin-dir` 플러그인이 설치된 마켓플레이스 플러그인과 동일한 이름을 가진 경우 로컬 복사본이 해당 세션에 우선합니다. 이를 통해 먼저 제거하지 않고도 이미 설치한 플러그인의 변경 사항을 테스트할 수 있습니다. 관리 설정에 의해 강제로 활성화되거나 비활성화된 플러그인은 유일한 예외이며 `--plugin-dir`로 재정의할 수 없습니다.

347 349 

348플러그인을 변경할 때 `/reload-plugins`를 실행하여 다시 시작하지 않고 업데이트를 적용합니다. 이는 플러그인, skills, agents, hooks, 플러그인 MCP servers, 플러그인 LSP servers를 다시 로드합니다. 플러그인 구성 요소를 테스트합니다:350플러그인을 변경할 때 `/reload-plugins`를 실행하여 다시 시작하지 않고 업데이트를 적용합니다. 이는 플러그인, skills, agents, hooks, 플러그인 MCP servers, 플러그인 LSP servers를 다시 로드합니다. 플러그인 구성 요소를 테스트합니다:

349 351 


402 404 

403Anthropic은 Claude Code 플러그인을 위한 두 개의 공개 마켓플레이스를 유지합니다:405Anthropic은 Claude Code 플러그인을 위한 두 개의 공개 마켓플레이스를 유지합니다:

404 406 

405* **`claude-plugins-official`**: Anthropic에서 유지 관리하는 엄선된 플러그인 세트입니다. 모든 Claude Code 설치에서 자동으로 사용 가능합니다.407* **`claude-plugins-official`**: Anthropic에서 유지 관리하는 엄선된 플러그인 세트입니다. Claude Code를 처음 대화형으로 시작할 때 자동으로 등록됩니다. 첫 번째 시작 전에 실행되는 비대화형 스크립트는 `claude plugin marketplace add anthropics/claude-plugins-official`로 명시적으로 추가해야 합니다.

406* **`claude-community`**: 검토 후 타사 제출이 도착하는 공개 커뮤니티 마켓플레이스입니다. 사용자는 `/plugin marketplace add anthropics/claude-plugins-community`로 추가하고 `@claude-community`로 설치합니다.408* **`claude-community`**: 검토 후 타사 제출이 도착하는 공개 커뮤니티 마켓플레이스입니다. 사용자는 `/plugin marketplace add anthropics/claude-plugins-community`로 추가하고 `@claude-community`로 설치합니다.

407 409 

408커뮤니티 마켓플레이스 검토를 위해 플러그인을 제출하려면 다음 앱 내 양식 중 하나를 사용하세요:410커뮤니티 마켓플레이스 검토를 위해 플러그인을 제출하려면 다음 앱 내 양식 중 하나를 사용하세요:

409 411 

410* **Claude.ai**: [claude.ai/settings/plugins/submit](https://claude.ai/settings/plugins/submit)412* **claude.ai**: [claude.ai/admin-settings/directory/submissions/plugins/new](https://claude.ai/admin-settings/directory/submissions/plugins/new)

411* **Console**: [platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit)413* **Console**: [platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit)

412 414 

415claude.ai 양식은 Team 또는 Enterprise 조직과 디렉토리 관리 액세스가 필요합니다. 조직 소유자는 기본적으로 이 액세스 권한을 가집니다. Team 또는 Enterprise 조직에 속하지 않은 개별 작성자는 대신 Console 양식을 사용할 수 있습니다.

416 

413제출하기 전에 로컬에서 `claude plugin validate`를 실행하세요. 검토 파이프라인은 모든 제출에 대해 동일한 검사를 실행하며, 자동화된 안전 검사도 함께 수행합니다.417제출하기 전에 로컬에서 `claude plugin validate`를 실행하세요. 검토 파이프라인은 모든 제출에 대해 동일한 검사를 실행하며, 자동화된 안전 검사도 함께 수행합니다.

414 418 

415승인된 플러그인은 [`anthropics/claude-plugins-community`](https://github.com/anthropics/claude-plugins-community) 카탈로그의 특정 커밋 SHA에 고정되며, CI는 저장소에 새 커밋을 푸시할 때 자동으로 핀을 업데이트합니다. 공개 카탈로그는 검토 파이프라인에서 매일 밤 동기화되므로 승인과 플러그인이 `marketplace.json`에 나타나는 사이에 지연이 있을 수 있습니다. 플러그인이 설치 가능한지 확인하려면 [커뮤니티 카탈로그](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)에서 이름을 검색하세요.419승인된 플러그인은 [`anthropics/claude-plugins-community`](https://github.com/anthropics/claude-plugins-community) 카탈로그의 특정 커밋 SHA에 고정되며, CI는 저장소에 새 커밋을 푸시할 때 자동으로 핀을 업데이트합니다. 공개 카탈로그는 검토 파이프라인에서 매일 밤 동기화되므로 승인과 플러그인이 `marketplace.json`에 나타나는 사이에 지연이 있을 수 있습니다. 플러그인이 설치 가능한지 확인하려면 [커뮤니티 카탈로그](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)에서 이름을 검색하세요.


512| 공유하려면 수동으로 복사해야 함 | `/plugin install`로 설치 |516| 공유하려면 수동으로 복사해야 함 | `/plugin install`로 설치 |

513 517 

514<Note>518<Note>

515 마이그레이션 후 중복을 피하기 위해 `.claude/`에서 원본 파일을 제거할 있습니다. 플러그인 버전이 로드될 우선합니다.519 마이그레이션 후 중복을 피하기 위해 `.claude/`에서 원본 파일을 제거합니다. 프로젝트 및 사용자 `.claude/agents/` 정의는 같은 이름의 플러그인 agents를 재정의하므로, 원본이 제거되면 플러그인 버전만 적용됩니다.

516</Note>520</Note>

517 521 

518<h2 id="next-steps">522<h2 id="next-steps">

Details

46* Claude는 작업 컨텍스트에 따라 자동으로 이들을 호출할 수 있습니다.46* Claude는 작업 컨텍스트에 따라 자동으로 이들을 호출할 수 있습니다.

47* Skills는 SKILL.md와 함께 지원 파일을 포함할 수 있습니다.47* Skills는 SKILL.md와 함께 지원 파일을 포함할 수 있습니다.

48 48 

49플러그인에 `skills/` 디렉토리가 없고 `skills` manifest 필드가 없으면, 플러그인 루트의 `SKILL.md`가 단일 skill로 로드됩니다. frontmatter `name` 필드를 설정하여 skill의 호출 이름을 제어하세요. 이 필드가 없으면 Claude Code는 설치 디렉토리 이름으로 폴백되며, 마켓플레이스에서 설치된 플러그인의 경우 매 업데이트마다 변경되는 버전 문자열입니다. 둘 이상의 skill을 제공하는 플러그인의 경우 위에 표시된 `skills/` 디렉토리 레이아웃을 사용하세요.

50 

49완전한 세부 정보는 [Skills](/ko/skills)를 참조하세요.51완전한 세부 정보는 [Skills](/ko/skills)를 참조하세요.

50 52 

51<h3 id="agents">53<h3 id="agents">


256**선택사항 필드:**258**선택사항 필드:**

257 259 

258| 필드 | 설명 |260| 필드 | 설명 |

259| :---------------------- | :--------------------------------------------- |261| :---------------------- | :------------------------------------------------------------------------------------- |

260| `args` | LSP 서버의 명령줄 인수 |262| `args` | LSP 서버의 명령줄 인수 |

261| `transport` | 통신 전송: `stdio` (기본값) 또는 `socket` |263| `transport` | 통신 전송: `stdio` (기본값) 또는 `socket` |

262| `env` | 서버 시작 시 설정할 환경 변수 |264| `env` | 서버 시작 시 설정할 환경 변수 |


265| `workspaceFolder` | 서버의 작업 공간 폴더 경로 |267| `workspaceFolder` | 서버의 작업 공간 폴더 경로 |

266| `startupTimeout` | 서버 시작을 기다릴 최대 시간 (밀리초) |268| `startupTimeout` | 서버 시작을 기다릴 최대 시간 (밀리초) |

267| `maxRestarts` | 포기하기 전 최대 재시작 시도 횟수 |269| `maxRestarts` | 포기하기 전 최대 재시작 시도 횟수 |

270| `diagnostics` | Claude의 컨텍스트에 진단을 푸시할지 여부 (기본값 `true`). 코드 네비게이션은 유지하되 자동 진단 주입을 억제하려면 `false`로 설정하세요. |

268 271 

269<Warning>272<Warning>

270 **언어 서버 바이너리를 별도로 설치해야 합니다.** LSP 플러그인은 Claude Code가 언어 서버에 연결하는 방법을 구성하지만, 서버 자체는 포함하지 않습니다. `/plugin` Errors 탭에서 `Executable not found in $PATH`를 보면 언어에 필요한 바이너리를 설치하세요.273 **언어 서버 바이너리를 별도로 설치해야 합니다.** LSP 플러그인은 Claude Code가 언어 서버에 연결하는 방법을 구성하지만, 서버 자체는 포함하지 않습니다. `/plugin` Errors 탭에서 `Executable not found in $PATH`를 보면 언어에 필요한 바이너리를 설치하세요.


629사용자 정의 경로가 플러그인의 기본 디렉토리를 대체하는지 확장하는지는 필드에 따라 다릅니다:632사용자 정의 경로가 플러그인의 기본 디렉토리를 대체하는지 확장하는지는 필드에 따라 다릅니다:

630 633 

631* **기본값 대체**: `commands`, `agents`, `outputStyles`, `experimental.themes`, `experimental.monitors`. 예를 들어 매니페스트가 `commands`를 지정하면 기본 `commands/` 디렉토리는 스캔되지 않습니다. 기본값을 유지하고 더 많은 것을 추가하려면 명시적으로 나열하세요: `"commands": ["./commands/", "./extras/"]`634* **기본값 대체**: `commands`, `agents`, `outputStyles`, `experimental.themes`, `experimental.monitors`. 예를 들어 매니페스트가 `commands`를 지정하면 기본 `commands/` 디렉토리는 스캔되지 않습니다. 기본값을 유지하고 더 많은 것을 추가하려면 명시적으로 나열하세요: `"commands": ["./commands/", "./extras/"]`

632* **기본값에 추가**: `skills`. 기본 `skills/` 디렉토리는 항상 스캔되며, `skills`에 나열된 디렉토리는 함께 로드됩니다.635* **기본값에 추가**: `skills`. 기본 `skills/` 디렉토리는 항상 스캔되며, `skills`에 나열된 디렉토리는 함께 로드됩니다. 예외: [소스가 마켓플레이스 루트로 확인되는 마켓플레이스 항목](/ko/plugin-marketplaces#advanced-plugin-entries)의 경우 특정 서브디렉토리를 선언하면 스캔을 대체합니다.

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

634 637 

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


1093| `--available` | 마켓플레이스에서 사용 가능한 플러그인 포함. `--json` 필요 | |1096| `--available` | 마켓플레이스에서 사용 가능한 플러그인 포함. `--json` 필요 | |

1094| `-h, --help` | 명령어 도움말 표시 | |1097| `-h, --help` | 명령어 도움말 표시 | |

1095 1098 

1099대화형 세션 내에서 `/plugin list`는 동일한 목록을 인라인으로 출력합니다. 대화형 형식은 `--enabled` 또는 `--disabled`를 허용하여 해당 상태의 플러그인만 표시하며, `ls`를 `list`의 약자로 사용합니다.

1100 

1096<h3 id="plugin-details">1101<h3 id="plugin-details">

1097 plugin details1102 plugin details

1098</h3>1103</h3>

Details

79 79 

80[`opusplan` 모델 설정](/ko/model-config#opusplan-model-setting)은 Plan 모드 중에 Opus로, 실행 중에 Sonnet으로 확인되므로 각 Plan 모드 토글은 모델 전환이고 새로운 캐시를 시작합니다.80[`opusplan` 모델 설정](/ko/model-config#opusplan-model-setting)은 Plan 모드 중에 Opus로, 실행 중에 Sonnet으로 확인되므로 각 Plan 모드 토글은 모델 전환이고 새로운 캐시를 시작합니다.

81 81 

82[Fable 5의 자동 모델 폴백](/ko/model-config#automatic-model-fallback)도 모델 전환입니다. 안전 분류기가 요청에 플래그를 지정하면 Claude Code는 기본 Opus 모델에서 다시 실행하고 세션이 계속됩니다.

83 

82<h3 id="changing-effort-level">84<h3 id="changing-effort-level">

83 노력 수준 변경85 노력 수준 변경

84</h3>86</h3>


101 MCP 서버 연결 또는 연결 해제103 MCP 서버 연결 또는 연결 해제

102</h3>104</h3>

103 105 

104도구 정의는 시스템 프롬프트 계층에 있으므로 요청 간에 도구 정의 집합이 변경되면 캐시가 무효화됩니다. [MCP 서버](/ko/mcp) 변경이 이를 수행하는지 여부는 해당 도구가 [도구 검색](/ko/mcp#scale-with-mcp-tool-search)으로 연기되는지 또는 프리픽스에 로드되는지에 따라 달라집니다:106도구 정의는 시스템 프롬프트 계층에 있으므로 요청 간에 도구 정의 집합이 변경되면 캐시가 무효화됩니다. [advisor 도구](/ko/advisor)를 토글하는 것은 예외입니다: 해당 정의는 캐시 중단점 이후에 있으므로 `/advisor`를 활성화 또는 비활성화하면 캐시된 프리픽스가 그대로 유지됩니다. [MCP 서버](/ko/mcp) 변경이 이를 수행하는지 여부는 해당 도구가 [도구 검색](/ko/mcp#scale-with-mcp-tool-search)으로 연기되는지 또는 프리픽스에 로드되는지에 따라 달라집니다:

105 107 

106* **연기된 도구**, 지원되는 모델의 기본값: 서버 연결, 연결 해제 또는 도구 목록 변경은 새로운 콘텐츠만 추가하고 이미 캐시된 항목을 방해하지 않습니다.108* **연기된 도구**, 지원되는 모델의 기본값: 서버 연결, 연결 해제 또는 도구 목록 변경은 새로운 콘텐츠만 추가하고 이미 캐시된 항목을 방해하지 않습니다.

107* **프리픽스에 로드된 도구**: 이에 대한 모든 변경은 캐시를 무효화합니다. 이는 [도구 검색을 사용할 수 없거나 비활성화](/ko/mcp#configure-tool-search)된 경우(예: Haiku 모델, Vertex AI 또는 사용자 정의 `ANTHROPIC_BASE_URL` 게이트웨이)에 발생합니다. 또한 [`alwaysLoad`](/ko/mcp#exempt-a-server-from-deferral)로 표시된 서버 또는 도구, 그리고 [임계값 기반 로딩](/ko/mcp#configure-tool-search)으로 유지되는 정의에 대해서도 발생합니다.109* **프리픽스에 로드된 도구**: 이에 대한 모든 변경은 캐시를 무효화합니다. 이는 [도구 검색을 사용할 수 없거나 비활성화](/ko/mcp#configure-tool-search)된 경우(예: Haiku 모델, Vertex AI 또는 사용자 정의 `ANTHROPIC_BASE_URL` 게이트웨이)에 발생합니다. 또한 [`alwaysLoad`](/ko/mcp#exempt-a-server-from-deferral)로 표시된 서버 또는 도구, 그리고 [임계값 기반 로딩](/ko/mcp#configure-tool-search)으로 유지되는 정의에 대해서도 발생합니다.


114 플러그인 활성화 또는 비활성화116 플러그인 활성화 또는 비활성화

115</h3>117</h3>

116 118 

117[플러그인](/ko/plugins)은 여러 구성 요소 유형을 번들로 제공하며, 변경 비용은 플러그인이 제공하는 구성 요소에 따라 달라집니다. 스킬, 명령, 에이전트, , LSP 서버, 모니터 및 테마는 캐시를 무효화하지 않습니다: 이들이 요청에 추가하는 모든 것은 기존 대화 후에 추가되므로 다음 요청은 새로운 콘텐츠에 대해 비용을 지불하지만 여전히 그 이전의 모든 것을 캐시에서 읽습니다.119[플러그인](/ko/plugins)은 여러 구성 요소 유형을 번들로 제공하며, 변경 비용은 플러그인이 제공하는 구성 요소에 따라 달라집니다. Skills, commands, agents, hooks, LSP 서버, monitors, themes는 캐시를 무효화하지 않습니다: 이들이 요청에 추가하는 모든 것은 기존 대화 후에 추가되므로 다음 요청은 새로운 콘텐츠에 대해 비용을 지불하지만 여전히 그 이전의 모든 것을 캐시에서 읽습니다.

118 120 

119예외는 [MCP 서버](/ko/plugins-reference#mcp-servers)를 제공하는 플러그인입니다. 하나를 활성화 또는 비활성화하면 [MCP 서버 연결 또는 연결 해제](#connecting-or-disconnecting-an-mcp-server)와 동일한 규칙을 따릅니다: 서버의 도구가 연기될 때 캐시가 유지되고, 프리픽스에 로드될 때 다음 요청이 전체 대화를 다시 읽습니다.121예외는 [MCP 서버](/ko/plugins-reference#mcp-servers)를 제공하는 플러그인입니다. 하나를 활성화 또는 비활성화하면 [MCP 서버 연결 또는 연결 해제](#connecting-or-disconnecting-an-mcp-server)와 동일한 규칙을 따릅니다: 서버의 도구가 연기될 때 캐시가 유지되고, 프리픽스에 로드될 때 다음 요청이 전체 대화를 다시 읽습니다.

120 122 

121플러그인 변경은 [`/reload-plugins`](/ko/discover-plugins#apply-plugin-changes-without-restarting)를 실행하거나 새 세션을 시작할 때 적용됩니다. 비용(추가된 공지 사항이든 전체 다시 읽기든)은 다시 로드 후 첫 턴에 표시되며, `/plugin install`, `/plugin enable` 또는 `/plugin disable`을 실행할 때가 아닙니다.123플러그인 변경은 [`/reload-plugins`](/ko/discover-plugins#apply-plugin-changes-without-restarting)를 실행하거나 새 세션을 시작할 때 적용됩니다. 비용(추가된 공지 사항이든 전체 다시 읽기든)은 다시 로드 후 첫 턴에 표시되며, `/plugin install`, `/plugin enable` 또는 `/plugin disable`을 실행할 때가 아닙니다. {/* min-version: 2.1.163 */}v2.1.163부터 다시 로드가 전체 다시 읽기를 트리거할 때 `/reload-plugins`는 경고를 표시하고 다시 로드를 적용하지 않습니다. `--force`를 전달하여 어차피 적용합니다.

122 124 

123세션 초반에 활성화한 플러그인을 비활성화하면 이전 요청 형태가 복원됩니다. 해당 프리픽스가 여전히 [캐시 수명](#cache-lifetime) 내에 있으면 다음 요청이 다시 구축하는 대신 이전 캐시 항목을 읽습니다.125세션 초반에 활성화한 플러그인을 비활성화하면 이전 요청 형태가 복원됩니다. 해당 프리픽스가 여전히 [캐시 수명](#cache-lifetime) 내에 있으면 다음 요청이 다시 구축하는 대신 이전 캐시 항목을 읽습니다.

124 126 


128 130 

129`Bash` 또는 `WebFetch`와 같은 단순 도구 이름을 [거부 규칙](/ko/permissions#manage-permissions)으로 추가하면 해당 도구가 Claude의 컨텍스트에서 완전히 제거됩니다. 기본 제공 도구 정의는 시스템 프롬프트 계층에 로드되므로 이러한 규칙을 추가하거나 제거하면 세션 중에 캐시가 무효화됩니다. 변경 사항은 `/permissions`를 통해 추가하든 [설정 파일을 직접 편집](/ko/settings#when-edits-take-effect)하든 다음 턴에 적용됩니다.131`Bash` 또는 `WebFetch`와 같은 단순 도구 이름을 [거부 규칙](/ko/permissions#manage-permissions)으로 추가하면 해당 도구가 Claude의 컨텍스트에서 완전히 제거됩니다. 기본 제공 도구 정의는 시스템 프롬프트 계층에 로드되므로 이러한 규칙을 추가하거나 제거하면 세션 중에 캐시가 무효화됩니다. 변경 사항은 `/permissions`를 통해 추가하든 [설정 파일을 직접 편집](/ko/settings#when-edits-take-effect)하든 다음 턴에 적용됩니다.

130 132 

131단순 도구 이름 또는 동등한 `Bash(*)` 형식만 이 효과를 가집니다. `Bash(rm *)`와 같은 범위가 지정된 거부 규칙과 모든 허용 및 요청 규칙은 Claude가 보는 도구를 변경하지 않습니다. Claude Code는 Claude가 호출을 시도할 때 이를 확인하여 프리픽스를 그대로 유지합니다.133단순 도구 이름, 동등한 `Bash(*)` 형식, 또는 `"*"`와 같은 [도구 이름 글로브](/ko/permissions#tool-name-wildcards)만 이 효과를 가집니다. `"mcp__*"`와 같이 MCP 도구만 일치하는 글로브는 해당 도구를 동일한 방식으로 제거하지만 일치하는 도구가 [연기](#connecting-or-disconnecting-an-mcp-server)될 때 캐시를 그대로 유지합니다. 기본값이므로 연기된 정의는 캐시된 프리픽스에 없었습니다. `Bash(rm *)`와 같은 범위가 지정된 거부 규칙과 모든 허용 및 요청 규칙은 Claude가 보는 도구를 변경하지 않습니다. Claude Code는 Claude가 호출을 시도할 때 이를 확인하여 프리픽스를 그대로 유지합니다.

132 134 

133<h3 id="compacting-the-conversation">135<h3 id="compacting-the-conversation">

134 대화 압축136 대화 압축


219 221 

220캐시된 프리픽스는 비활성 기간 후에 만료됩니다. 캐시에 히트하는 각 요청은 타이머를 재설정하므로 계속 작업하는 한 캐시는 따뜻하게 유지됩니다. 충분히 긴 간격 후에 다음 요청은 전체 입력을 다시 계산하고 캐시를 다시 설정합니다. 이것이 한동안 떨어진 후 돌아오는 첫 턴이 눈에 띄게 느릴 수 있는 이유입니다.222캐시된 프리픽스는 비활성 기간 후에 만료됩니다. 캐시에 히트하는 각 요청은 타이머를 재설정하므로 계속 작업하는 한 캐시는 따뜻하게 유지됩니다. 충분히 긴 간격 후에 다음 요청은 전체 입력을 다시 계산하고 캐시를 다시 설정합니다. 이것이 한동안 떨어진 후 돌아오는 첫 턴이 눈에 띄게 느릴 수 있는 이유입니다.

221 223 

222TTL(Time To Live)은 캐시가 견디는 간격의 길이를 제어합니다. API는 두 가지를 제공합니다: 5분 TTL과 더 긴 휴식을 통해 캐시를 따뜻하게 유지하지만 [캐시 쓰기를 더 높은 속도로 청구](/ko/build-with-claude/prompt-caching#pricing)하는 [1시간 TTL](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration). Claude Code는 인증 방식에 따라 TTL을 선택하며, 환경 변수로 재정의할 수 있습니다.224TTL(Time To Live)은 캐시가 견디는 간격의 길이를 제어합니다. API는 두 가지를 제공합니다: 5분 TTL과 더 긴 휴식을 통해 캐시를 따뜻하게 유지하지만 [캐시 쓰기를 더 높은 속도로 청구](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)하는 [1시간 TTL](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration). Claude Code는 인증 방식에 따라 TTL을 선택하며, 환경 변수로 재정의할 수 있습니다.

223 225 

224<h3 id="on-a-claude-subscription">226<h3 id="on-a-claude-subscription">

225 Claude 구독에서227 Claude 구독에서


241 TTL 재정의243 TTL 재정의

242</h3>244</h3>

243 245 

244인증에 관계없이 5분 TTL을 강제하려면 `FORCE_PROMPT_CACHING_5M=1`을 설정합니다. 이는 특정 모델 또는 제공자로 캐싱 동작을 디버깅하거나, 두 TTL을 비교하거나, [관리 설정](/ko/settings#settings-files)에 설정된 `ENABLE_PROMPT_CACHING_1H`을 재정의할 때 유용합니다.246`FORCE_PROMPT_CACHING_5M=1`을 설정하여 인증에 관계없이 5분 TTL을 강제합니다. 이는 캐시 동작을 디버깅하거나, 두 TTL을 비교하거나, [관리 설정](/ko/settings#settings-files)에 설정된 `ENABLE_PROMPT_CACHING_1H`을 재정의할 때 유용합니다.

245 247 

246<h2 id="cache-scope">248<h2 id="cache-scope">

247 캐시 범위249 캐시 범위


251 253 

252동일한 디렉토리에서 병렬로 실행하는 세션은 일치하는 프리픽스를 구축하고 서로의 캐시를 읽습니다. 순차 세션은 시작 시 git 상태 스냅샷이 일치할 때만 프리픽스를 공유합니다. 시스템 프롬프트도 분기 및 최근 커밋을 캡처하기 때문입니다.254동일한 디렉토리에서 병렬로 실행하는 세션은 일치하는 프리픽스를 구축하고 서로의 캐시를 읽습니다. 순차 세션은 시작 시 git 상태 스냅샷이 일치할 때만 프리픽스를 공유합니다. 시스템 프롬프트도 분기 및 최근 커밋을 캡처하기 때문입니다.

253 255 

254기본 API 캐시는 더 광범위합니다. 캐시는 조직 간에 격리되며, 일부 제공자에서는 [조직 내 워크스페이스 간](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-storage-and-sharing)에 격리됩니다. 이러한 경계 내에서 동일한 모델과 프리픽스를 가진 두 요청은 동일한 캐시를 읽습니다. 자동화된 프로세스의 플릿을 실행하는 Agent SDK 호출자의 경우 [사용자 및 머신 간 프롬프트 캐싱 개선](/ko/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)을 참조하여 시스템 프롬프트의 머신별 섹션을 억제하고 머신 간 캐시를 공유합니다.256기본 API 캐시는 더 광범위합니다. 캐시는 조직 간에 격리되며, 일부 제공자에서는 [조직 내 워크스페이스 간](https://platform.claude.com/docs/ko/build-with-claude/prompt-caching#cache-storage-and-sharing)에 격리됩니다. 이러한 경계 내에서 동일한 모델과 프리픽스를 가진 두 요청은 동일한 캐시를 읽습니다. 자동화된 프로세스의 플릿을 실행하는 Agent SDK 호출자의 경우 [사용자 및 머신 간 프롬프트 캐싱 개선](/ko/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)을 참조하여 시스템 프롬프트의 머신별 섹션을 억제하고 머신 간 캐시를 공유합니다.

255 257 

256<h2 id="check-cache-performance">258<h2 id="check-cache-performance">

257 캐시 성능 확인259 캐시 성능 확인


290| `DISABLE_PROMPT_CACHING_HAIKU` | Haiku만 비활성화 |292| `DISABLE_PROMPT_CACHING_HAIKU` | Haiku만 비활성화 |

291| `DISABLE_PROMPT_CACHING_SONNET` | Sonnet만 비활성화 |293| `DISABLE_PROMPT_CACHING_SONNET` | Sonnet만 비활성화 |

292| `DISABLE_PROMPT_CACHING_OPUS` | Opus만 비활성화 |294| `DISABLE_PROMPT_CACHING_OPUS` | Opus만 비활성화 |

295| `DISABLE_PROMPT_CACHING_FABLE` | Fable만 비활성화 |

293 296 

294조직 전체에 캐싱 정책을 설정하려면 이 중 하나 또는 [TTL 변수](#cache-lifetime)를 [관리 설정](/ko/settings#settings-files)의 `env` 블록에 넣습니다. 정상 사용의 경우 캐싱을 활성화된 상태로 유지합니다.297조직 전체에 캐싱 정책을 설정하려면 이 중 하나 또는 [TTL 변수](#cache-lifetime)를 [관리 설정](/ko/settings#settings-files)의 `env` 블록에 넣습니다. 정상 사용의 경우 캐싱을 활성화된 상태로 유지합니다.

295 298 

quickstart.md +13 −6

Details

118claude118claude

119```119```

120 120 

121세션 정보, 최근 대화최신 업데이트가 포함된 Claude Code 환영 화면이 표시됩니다. 사용 가능한 명령을 보려면 `/help`를 입력하거나 이전 대화를 계속하려면 `/resume`을 입력하십시오.121버전, 현재 모델작업 디렉토리가 표시된 Claude Code 프롬프트가 나타납니다. 사용 가능한 명령을 보려면 `/help`를 입력하거나 이전 대화를 계속하려면 `/resume`을 입력하십시오.

122 122 

123<Tip>123<Tip>

124 로그인(단계 2) 후 자격 증명이 시스템에 저장됩니다. [자격 증명 관리](/ko/authentication#credential-management)에서 자세히 알아보십시오.124 로그인(단계 2) 후 자격 증명이 시스템에 저장됩니다. [자격 증명 관리](/ko/authentication#credential-management)에서 자세히 알아보십시오.


278 필수 명령278 필수 명령

279</h2>279</h2>

280 280 

281일상적인 사용을 위한 가장 중요한 명령은 다음과 같습니다:281일상적인 사용을 위한 가장 중요한 명령은 다음과 같습니다. 셸 명령은 Claude Code를 시작하거나 재개하기 위해 터미널에서 실행됩니다. 세션 명령은 Claude Code가 시작된 후 내부에서 실행됩니다.

282 

283**셸 명령**

282 284 

283| 명령 | 기능 | 예시 |285| 명령 | 기능 | 예시 |

284| ------------------- | --------------------- | ----------------------------------- |286| ------------------- | --------------------- | ----------------------------------- |


287| `claude -p "query"` | 일회성 쿼리 실행 후 종료 | `claude -p "explain this function"` |289| `claude -p "query"` | 일회성 쿼리 실행 후 종료 | `claude -p "explain this function"` |

288| `claude -c` | 현재 디렉토리에서 가장 최근 대화 계속 | `claude -c` |290| `claude -c` | 현재 디렉토리에서 가장 최근 대화 계속 | `claude -c` |

289| `claude -r` | 이전 대화 재개 | `claude -r` |291| `claude -r` | 이전 대화 재개 | `claude -r` |

292 

293**세션 명령**

294 

295| 명령 | 기능 | 예시 |

296| ----------------- | -------------- | -------- |

290| `/clear` | 대화 기록 지우기 | `/clear` |297| `/clear` | 대화 기록 지우기 | `/clear` |

291| `/help` | 사용 가능한 명령 표시 | `/help` |298| `/help` | 사용 가능한 명령 표시 | `/help` |

292| `exit` 또는 Ctrl+D | Claude Code 종료 | `exit` |299| `/exit` 또는 Ctrl+D | Claude Code 종료 | `/exit` |

293 300 

294전체 명령 목록은 [CLI 참조](/ko/cli-reference)를 참조하십시오.301전체 명령 목록은 [CLI 참조](/ko/cli-reference)를 참조하고 전체 세션 명령 목록은 [명령 참조](/ko/commands)를 참조하십시오.

295 302 

296<h2 id="pro-tips-for-beginners">303<h2 id="pro-tips-for-beginners">

297 초보자를 위한 팁304 초보자를 위한 팁


336 </Accordion>343 </Accordion>

337</AccordionGroup>344</AccordionGroup>

338 345 

339<h2 id="what-s-next">346<h2 id="whats-next">

340 다음 단계347 다음 단계

341</h2>348</h2>

342 349 

343기본 사항을 배웠으므로 더 고급 기능을 살펴보십시오:350이제 기본 사항을 배웠으므로 더 고급 기능을 살펴보십시오:

344 351 

345<CardGroup cols={2}>352<CardGroup cols={2}>

346 <Card title="Claude Code 작동 방식" icon="microchip" href="/ko/how-claude-code-works">353 <Card title="Claude Code 작동 방식" icon="microchip" href="/ko/how-claude-code-works">

remote-control.md +72 −27

Details

26 26 

27이 페이지에서는 설정, 세션을 시작하고 연결하는 방법, Remote Control과 웹의 Claude Code를 비교하는 방법을 다룹니다.27이 페이지에서는 설정, 세션을 시작하고 연결하는 방법, Remote Control과 웹의 Claude Code를 비교하는 방법을 다룹니다.

28 28 

29## 요구 사항29<h2 id="requirements">

30 요구 사항

31</h2>

30 32 

31Remote Control을 사용하기 전에 환경이 다음 조건을 충족하는지 확인하세요:33Remote Control을 사용하기 전에 환경이 다음 조건을 충족하는지 확인하세요:

32 34 


34* **인증**: `claude`를 실행하고 아직 로그인하지 않았다면 `/login`을 사용하여 claude.ai를 통해 로그인하세요.36* **인증**: `claude`를 실행하고 아직 로그인하지 않았다면 `/login`을 사용하여 claude.ai를 통해 로그인하세요.

35* **작업 공간 신뢰**: 작업 공간 신뢰 대화를 수락하려면 프로젝트 디렉토리에서 최소한 한 번 `claude`를 실행하세요.37* **작업 공간 신뢰**: 작업 공간 신뢰 대화를 수락하려면 프로젝트 디렉토리에서 최소한 한 번 `claude`를 실행하세요.

36 38 

37## Remote Control 세션 시작39<h2 id="start-a-remote-control-session">

40 Remote Control 세션 시작

41</h2>

38 42 

39CLI 또는 VS Code 확장에서 Remote Control 세션을 시작할 수 있습니다. CLI는 세 가지 호출 모드를 제공하며, VS Code는 `/remote-control` 명령을 사용합니다.43CLI 또는 VS Code 확장에서 Remote Control 세션을 시작할 수 있습니다. CLI는 세 가지 호출 모드를 제공하며, VS Code는 `/remote-control` 명령을 사용합니다.

40 44 


46 claude remote-control50 claude remote-control

47 ```51 ```

48 52 

49 프로세스는 터미널에서 서버 모드로 계속 실행되어 원격 연결을 기다립니다. [다른 기기에서 연결](#다른-기기에서-연결)하는 데 사용할 수 있는 세션 URL을 표시하며, 스페이스바를 눌러 휴대폰에서 빠르게 액세스할 수 있는 QR 코드를 표시할 수 있습니다. 원격 세션이 활성화되어 있는 동안 터미널은 연결 상태 및 도구 활동을 표시합니다.53 프로세스는 터미널에서 서버 모드로 계속 실행되어 원격 연결을 기다립니다. [다른 기기에서 연결](#connect-from-another-device)하는 데 사용할 수 있는 세션 URL을 표시하며, 스페이스바를 눌러 휴대폰에서 빠르게 액세스할 수 있는 QR 코드를 표시할 수 있습니다. 원격 세션이 활성화되어 있는 동안 터미널은 연결 상태 및 도구 활동을 표시합니다.

50 54 

51 사용 가능한 플래그:55 사용 가능한 플래그:

52 56 


89 /remote-control My Project93 /remote-control My Project

90 ```94 ```

91 95 

92 이렇게 하면 현재 대화 기록을 이어받는 Remote Control 세션이 시작되며, [다른 기기에서 연결](#다른-기기에서-연결)하는 데 사용할 수 있는 세션 URL 및 QR 코드를 표시합니다. `--verbose`, `--sandbox` 및 `--no-sandbox` 플래그는 이 명령에서 사용할 수 없습니다.96 이렇게 하면 현재 대화 기록을 이어받는 Remote Control 세션이 시작됩니다.

97 

98 `--verbose`, `--sandbox` 및 `--no-sandbox` 플래그는 이 명령에서 사용할 수 없습니다.

93 </Tab>99 </Tab>

94 100 

95 <Tab title="VS Code">101 <Tab title="VS Code">


107 </Tab>113 </Tab>

108</Tabs>114</Tabs>

109 115 

110### 다른 기기에서 연결116<h3 id="check-connection-status">

117 연결 상태 확인

118</h3>

119 

120대화형 터미널 세션에서 `/rc active` 표시기는 연결이 유지되는 동안 입력 상자 아래 바닥글에 있으며, 터미널이 너무 좁으면 숨겨집니다. 표시기 텍스트는 claude.ai의 세션으로 연결되는 링크입니다. 아래쪽 화살표 키로 선택하고 Enter를 눌러 세션 URL과 [다른 기기에서 연결](#connect-from-another-device)하는 데 사용할 수 있는 QR 코드가 있는 상태 패널을 열거나, `/remote-control`을 다시 실행하여 다시 시도하세요.

121 

122연결이 실패하면 표시기가 빨간색으로 변하고 `/rc failed`로 표시됩니다. 아래쪽 화살표 키로 선택하고 Enter를 눌러 실패 이유와 해제 옵션을 보거나, `/remote-control`을 다시 실행하여 다시 시도하세요.

123 

124<h3 id="connect-from-another-device">

125 다른 기기에서 연결

126</h3>

111 127 

112Remote Control 세션이 활성화되면 다른 기기에서 연결하는 몇 가지 방법이 있습니다:128Remote Control 세션이 활성화되면 다른 기기에서 연결하는 몇 가지 방법이 있습니다:

113 129 


1223. 기존 대화 기록의 마지막 의미 있는 메시지1383. 기존 대화 기록의 마지막 의미 있는 메시지

1234. `myhost-graceful-unicorn`과 같은 자동 생성된 이름입니다. 여기서 `myhost`는 컴퓨터의 호스트 이름 또는 `--remote-control-session-name-prefix`로 설정한 접두사입니다.1394. `myhost-graceful-unicorn`과 같은 자동 생성된 이름입니다. 여기서 `myhost`는 컴퓨터의 호스트 이름 또는 `--remote-control-session-name-prefix`로 설정한 접두사입니다.

124 140 

125명시적 이름을 설정하지 않았다면 메시지를 보낸 후 제목이 프롬프트를 반영하도록 업데이트됩니다. claude.ai 또는 Claude 앱에서 세션의 이름을 바꾸면 `claude --resume`에 표시되는 로컬 제목도 업데이트됩니다.141명시적 이름을 설정하지 않았다면 메시지를 보낸 후 제목이 프롬프트를 반영하도록 업데이트됩니다. {/* min-version: 2.1.176 */}Claude Code v2.1.176부터 자동 생성된 제목은 대화의 언어 또는 구성된 [`language`](/ko/settings#available-settings) 설정과 일치합니다. claude.ai 또는 Claude 앱에서 세션의 이름을 바꾸면 `claude --resume`에 표시되는 로컬 제목도 업데이트됩니다.

126 142 

127환경에 이미 활성 세션이 있으면 계속할지 새로 시작할지 묻는 메시지가 표시됩니다.143환경에 이미 활성 세션이 있으면 계속할지 새로 시작할지 묻는 메시지가 표시됩니다.

128 144 

129Claude 앱이 아직 없으면 Claude Code 내에서 `/mobile` 명령을 사용하여 [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) 또는 [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude)용 다운로드 QR 코드를 표시하세요.145Claude 앱이 아직 없으면 Claude Code 내에서 `/mobile` 명령을 사용하여 [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) 또는 [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude)용 다운로드 QR 코드를 표시하세요.

130 146 

131### 모든 세션에 대해 Remote Control 활성화147<h3 id="enable-remote-control-for-all-sessions">

148 모든 세션에 대해 Remote Control 활성화

149</h3>

132 150 

133기본적으로 Remote Control은 `claude remote-control`, `claude --remote-control` 또는 `/remote-control`을 명시적으로 실행할 때만 활성화됩니다. 모든 대화형 세션에 대해 자동으로 활성화하려면 Claude Code 내에서 `/config`를 실행하고 **모든 세션에 대해 Remote Control 활성화**를 `true`로 설정하세요. 비활성화하려면 `false`로 다시 설정하세요. Desktop 앱에서는 **설정 → Claude Code → 기본적으로 원격 제어 활성화**에서도 전환할 수 있습니다.151기본적으로 Remote Control은 `claude remote-control`, `claude --remote-control` 또는 `/remote-control`을 명시적으로 실행할 때만 활성화됩니다. 모든 대화형 세션에 대해 자동으로 활성화하려면 Claude Code 내에서 `/config`를 실행하고 **모든 세션에 대해 Remote Control 활성화**를 `true`로 설정하세요. 비활성화하려면 `false`로 다시 설정하세요. Desktop 앱에서는 **설정 → Claude Code → 기본적으로 원격 제어 활성화**에서도 전환할 수 있습니다.

134 152 

135이 설정이 켜져 있으면 각 대화형 Claude Code 프로세스는 하나의 원격 세션을 등록합니다. 여러 인스턴스를 실행하면 각각 자체 환경 및 세션을 가져옵니다. 단일 프로세스에서 여러 동시 세션을 실행하려면 [서버 모드](#remote-control-세션-시작)를 대신 사용하세요.153이 설정이 켜져 있으면 각 대화형 Claude Code 프로세스는 하나의 원격 세션을 등록합니다. 여러 인스턴스를 실행하면 각각 자체 환경 및 세션을 가져옵니다. 단일 프로세스에서 여러 동시 세션을 실행하려면 [서버 모드](#start-a-remote-control-session)를 대신 사용하세요.

136 154 

137## 연결 및 보안155<h2 id="connection-and-security">

156 연결 및 보안

157</h2>

138 158 

139로컬 Claude Code 세션은 아웃바운드 HTTPS 요청만 수행하며 컴퓨터에서 인바운드 포트를 열지 않습니다. Remote Control을 시작하면 Anthropic API에 등록되고 작업을 폴링합니다. 다른 기기에서 연결하면 서버는 웹 또는 모바일 클라이언트와 로컬 세션 간의 메시지를 스트리밍 연결을 통해 라우팅합니다.159로컬 Claude Code 세션은 아웃바운드 HTTPS 요청만 수행하며 컴퓨터에서 인바운드 포트를 열지 않습니다. Remote Control을 시작하면 Anthropic API에 등록되고 작업을 폴링합니다. 다른 기기에서 연결하면 서버는 웹 또는 모바일 클라이언트와 로컬 세션 간의 메시지를 스트리밍 연결을 통해 라우팅합니다.

140 160 

141모든 트래픽은 TLS를 통해 Anthropic API를 통해 이동하며, 이는 모든 Claude Code 세션과 동일한 전송 보안입니다. 연결은 각각 단일 목적으로 범위가 지정되고 독립적으로 만료되는 여러 단기 자격 증명을 사용합니다.161모든 트래픽은 TLS를 통해 Anthropic API를 통해 이동하며, 이는 모든 Claude Code 세션과 동일한 전송 보안입니다. 연결은 각각 단일 목적으로 범위가 지정되고 독립적으로 만료되는 여러 단기 자격 증명을 사용합니다.

142 162 

143## Remote Control과 웹의 Claude Code 비교163<h2 id="remote-control-vs-claude-code-on-the-web">

164 Remote Control과 웹의 Claude Code 비교

165</h2>

144 166 

145Remote Control과 [웹의 Claude Code](/ko/claude-code-on-the-web)는 모두 claude.ai/code 인터페이스를 사용합니다. 주요 차이점은 세션이 실행되는 위치입니다: Remote Control은 컴퓨터에서 실행되므로 로컬 MCP servers, 도구 및 프로젝트 구성이 사용 가능하게 유지됩니다. 웹의 Claude Code는 Anthropic 관리 클라우드 인프라에서 실행됩니다.167Remote Control과 [웹의 Claude Code](/ko/claude-code-on-the-web)는 모두 claude.ai/code 인터페이스를 사용합니다. 주요 차이점은 세션이 실행되는 위치입니다: Remote Control은 컴퓨터에서 실행되므로 로컬 MCP servers, 도구 및 프로젝트 구성이 사용 가능하게 유지됩니다. 웹의 Claude Code는 Anthropic 관리 클라우드 인프라에서 실행됩니다.

146 168 

147로컬 작업 중간에 있고 다른 기기에서 계속하려고 할 때 Remote Control을 사용하세요. 로컬 설정 없이 작업을 시작하거나, 복제하지 않은 저장소에서 작업하거나, 여러 작업을 병렬로 실행하려고 할 때 웹의 Claude Code를 사용하세요.169로컬 작업 중간에 있고 다른 기기에서 계속하려고 할 때 Remote Control을 사용하세요. 로컬 설정 없이 작업을 시작하거나, 복제하지 않은 저장소에서 작업하거나, 여러 작업을 병렬로 실행하려고 할 때 웹의 Claude Code를 사용하세요.

148 170 

149## 모바일 푸시 알림171<h2 id="mobile-push-notifications">

172 모바일 푸시 알림

173</h2>

150 174 

151Remote Control이 활성화되면 Claude는 휴대폰으로 푸시 알림을 보낼 수 있습니다.175Remote Control이 활성화되면 Claude는 휴대폰으로 푸시 알림을 보낼 수 있습니다.

152 176 


172 </Step>196 </Step>

173 197 

174 <Step title="Claude Code에서 푸시 활성화">198 <Step title="Claude Code에서 푸시 활성화">

175 터미널에서 `/config`를 실행하고 **Claude가 결정할 때 푸시**를 활성화하세요.199 터미널에서 `/config`를 실행하고 사전 알림을 위해 **Claude가 결정할 때 푸시**를 활성화하거나, 권한 프롬프트 및 질문을 위해 **작업이 필요할 때 푸시**를 활성화하거나, 둘 다 활성화하세요.

176 </Step>200 </Step>

177</Steps>201</Steps>

178 202 


182* iOS에서 포커스 모드 및 알림 요약이 푸시를 억제하거나 지연시킬 수 있습니다. 설정 → 알림 → Claude를 확인하세요.206* iOS에서 포커스 모드 및 알림 요약이 푸시를 억제하거나 지연시킬 수 있습니다. 설정 → 알림 → Claude를 확인하세요.

183* Android에서 적극적인 배터리 최적화가 전달을 지연시킬 수 있습니다. 시스템 설정에서 Claude 앱을 배터리 최적화에서 제외하세요.207* Android에서 적극적인 배터리 최적화가 전달을 지연시킬 수 있습니다. 시스템 설정에서 Claude 앱을 배터리 최적화에서 제외하세요.

184 208 

185## 제한 사항209<h2 id="limitations">

210 제한 사항

211</h2>

186 212 

187* **대화형 프로세스당 하나의 원격 세션**: 서버 모드 외부에서 각 Claude Code 인스턴스는 한 번에 하나의 원격 세션을 지원합니다. 단일 프로세스에서 여러 동시 세션을 실행하려면 [서버 모드](#start-a-remote-control-session)를 사용하세요.213* **대화형 프로세스당 하나의 원격 세션**: 서버 모드 외부에서 각 Claude Code 인스턴스는 한 번에 하나의 원격 세션을 지원합니다. 단일 프로세스에서 여러 동시 세션을 실행하려면 [서버 모드](#start-a-remote-control-session)를 사용하세요.

188* **로컬 프로세스는 계속 실행되어야 함**: Remote Control은 로컬 프로세스로 실행됩니다. 터미널을 닫거나, VS Code를 종료하거나, 다른 방식으로 `claude` 프로세스를 중지하면 세션이 종료됩니다.214* **로컬 프로세스는 계속 실행되어야 함**: Remote Control은 로컬 프로세스로 실행됩니다. 터미널을 닫거나, VS Code를 종료하거나, 다른 방식으로 `claude` 프로세스를 중지하면 세션이 종료됩니다.

189* **장시간 네트워크 중단**: 컴퓨터가 켜져 있지만 약 10분 이상 네트워크에 도달할 수 없으면 세션이 시간 초과되고 프로세스가 종료됩니다. `claude remote-control`을 다시 실행하여 새 세션을 시작하세요.215* **장시간 네트워크 중단**: 컴퓨터가 켜져 있지만 약 10분 이상 네트워크에 도달할 수 없으면 세션이 시간 초과되고 프로세스가 종료됩니다. `claude remote-control`을 다시 실행하여 새 세션을 시작하세요.

190* **Ultraplan이 Remote Control 연결 해제**: [ultraplan](/ko/ultraplan) 세션을 시작하면 활성 Remote Control 세션이 연결 해제됩니다. 두 기능 모두 claude.ai/code 인터페이스를 차지하고 한 번에 하나만 연결될 수 있기 때문입니다.216* **Ultraplan이 Remote Control 연결 해제**: [ultraplan](/ko/ultraplan) 세션을 시작하면 활성 Remote Control 세션이 연결 해제됩니다. 두 기능 모두 claude.ai/code 인터페이스를 차지하고 한 번에 하나만 연결될 수 있기 때문입니다.

191* **일부 명령은 로컬 전용**: `/mcp`, `/plugin` 또는 `/resume`과 같이 터미널에서 대화형 선택기를 여는 명령은 로컬 CLI에서만 작동합니다. `/compact`, `/clear`, `/context`, `/usage`, `/exit`, `/usage-credits`, `/recap` 및 `/reload-plugins`를 포함하여 텍스트 출력을 생성하는 명령은 모바일 및 웹에서 작동합니다.217* **일부 명령은 로컬 전용**: `/plugin` 또는 `/resume`과 같이 터미널에서 대화형 선택기를 여는 명령은 로컬 CLI에서만 작동합니다. `/compact`, `/clear`, `/context`, `/usage`, `/exit`, `/usage-credits`, `/recap` 및 `/reload-plugins`를 포함하여 텍스트 출력을 생성하는 명령은 모바일 및 웹에서 작동합니다. {/* min-version: 2.1.166 */}v2.1.166부터 `/mcp`도 모바일 및 웹에서 작동합니다. 이는 선택기를 열지 않고 서버 상태의 텍스트 요약을 반환하며, 로컬 CLI와 동일한 `reconnect`, `enable` 및 `disable` [하위 명령](/ko/commands#all-commands)을 허용합니다. 한 가지 차이점이 있습니다. 모바일 및 웹에서 서버 이름 없이 `/mcp reconnect`를 실행하면 실패했거나 인증이 필요한 모든 서버를 다시 연결하는 반면, 로컬 CLI는 `reconnect`에 서버 이름이 필요합니다.

192 218 

193## 문제 해결219<h2 id="troubleshooting">

220 문제 해결

221</h2>

194 222 

195### "Remote Control에는 claude.ai 구독이 필요합니다"223<h3 id="remote-control-requires-a-claude-ai-subscription">

224 "Remote Control에는 claude.ai 구독이 필요합니다"

225</h3>

196 226 

197claude.ai 계정으로 인증되지 않았습니다. `claude auth login`을 실행하고 claude.ai 옵션을 선택하세요. `ANTHROPIC_API_KEY`가 환경에 설정되어 있으면 먼저 설정을 해제하세요.227claude.ai 계정으로 인증되지 않았습니다. `claude auth login`을 실행하고 claude.ai 옵션을 선택하세요. `ANTHROPIC_API_KEY`가 환경에 설정되어 있으면 먼저 설정을 해제하세요.

198 228 

199### "Remote Control에는 전체 범위 로그인 토큰이 필요합니다"229<h3 id="remote-control-requires-a-full-scope-login-token">

230 "Remote Control에는 전체 범위 로그인 토큰이 필요합니다"

231</h3>

200 232 

201`claude setup-token` 또는 `CLAUDE_CODE_OAUTH_TOKEN` 환경 변수의 장기 토큰으로 인증되었습니다. 이러한 토큰은 추론 전용으로 제한되며 Remote Control 세션을 설정할 수 없습니다. 대신 `claude auth login`을 실행하여 전체 범위 세션 토큰으로 인증하세요.233`claude setup-token` 또는 `CLAUDE_CODE_OAUTH_TOKEN` 환경 변수의 장기 토큰으로 인증되었습니다. 이러한 토큰은 추론 전용으로 제한되며 Remote Control 세션을 설정할 수 없습니다. 대신 `claude auth login`을 실행하여 전체 범위 세션 토큰으로 인증하세요.

202 234 

203### "Remote Control 적격성을 위해 조직을 결정할 수 없습니다"235<h3 id="unable-to-determine-your-organization-for-remote-control-eligibility">

236 "Remote Control 적격성을 위해 조직을 결정할 수 없습니다"

237</h3>

204 238 

205캐시된 계정 정보가 오래되었거나 불완전합니다. `claude auth login`을 실행하여 새로 고치세요.239캐시된 계정 정보가 오래되었거나 불완전합니다. `claude auth login`을 실행하여 새로 고치세요.

206 240 

207### "Remote Control이 아직 계정에 대해 활성화되지 않았습니다"241<h3 id="remote-control-is-not-yet-enabled-for-your-account">

242 "Remote Control이 아직 계정에 대해 활성화되지 않았습니다"

243</h3>

208 244 

209특정 환경 변수가 있으면 적격성 확인이 실패할있습니다:245Remote Control 롤아웃이 계정에 도달하지 않았거나 캐시된 자격이 최신이 아닙니다. 최근에 요금제를 변경한 경우 `claude auth logout`을 실행한 다음 `claude auth login`을 실행하여 새로 고치세요. `claude doctor`를 실행하여 어떤 개별 적격성 확인이 실패했는지 확인하세요. 환경 변수 충돌, 도달할 없는 확인, 조직 정책은 각각 자신의 메시지를 생성하므로 이 오류는 롤아웃 게이트 자체를 의미합니다.

210 246 

211* `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 또는 `DISABLE_TELEMETRY`: 설정을 해제하고 다시 시도하세요.247<h3 id="couldn’t-verify-remote-control-eligibility">

212* `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX` 또는 `CLAUDE_CODE_USE_FOUNDRY`: Remote Control은 claude.ai 인증이 필요하며 타사 제공자와 작동하지 않습니다.248 "Remote Control 적격성을 확인할 없습니다"

249</h3>

213 250 

214 어느 것도 설정되지 않았다면 `/logout`을 실행한 다음 `/login` 실행하여 새로 고치세요.251Claude Code가 Remote Control이 계정에 대해 활성화되어 있는지 확인하기 위해 기능 플래그 서비스에 도달할 수 없습니다. 일반적으로 오프라인 상태이거나 프록시가 요청을 차단하고 있기 때문입니다. 네트워크 액세스가 있으면 다시 시도하거나 `claude doctor` 실행하여 세부 정보를 확인하세요. 관련 메시지인 "조직의 Remote Control 정책을 확인할 수 없습니다"는 동일한 원인과 동일한 해결책을 가집니다. 두 메시지 모두 v2.1.178에서 추가되었습니다.

215 252 

216### "Remote Control이 조직의 정책에 의해 비활성화되었습니다"253<h3 id="remote-control-is-disabled-by-your-organization’s-policy">

254 "Remote Control은 조직의 정책에 의해 비활성화되었습니다"

255</h3>

217 256 

218이 오류에는 네 가지 서로 다른 원인이 있습니다. 먼저 `/status`를 실행하여 사용 중인 로그인 방법과 구독을 확인하세요.257이 오류에는 네 가지 서로 다른 원인이 있습니다. 먼저 `/status`를 실행하여 사용 중인 로그인 방법과 구독을 확인하세요.

219 258 


222* **관리자 토글이 회색으로 표시됨**: 조직에 Remote Control과 호환되지 않는 데이터 보존 또는 규정 준수 구성이 있습니다. 이는 관리자 패널에서 변경할 수 없습니다. Anthropic 지원팀에 문의하여 옵션을 논의하세요.261* **관리자 토글이 회색으로 표시됨**: 조직에 Remote Control과 호환되지 않는 데이터 보존 또는 규정 준수 구성이 있습니다. 이는 관리자 패널에서 변경할 수 없습니다. Anthropic 지원팀에 문의하여 옵션을 논의하세요.

223* **오류에 `disableRemoteControl`이 언급됨**: IT 관리자가 조직 전체 토글과 무관하게 [관리 설정](/ko/settings#settings-files)을 통해 이 장치에서 Remote Control을 비활성화했습니다.262* **오류에 `disableRemoteControl`이 언급됨**: IT 관리자가 조직 전체 토글과 무관하게 [관리 설정](/ko/settings#settings-files)을 통해 이 장치에서 Remote Control을 비활성화했습니다.

224 263 

225### "원격 자격 증명 가져오기 실패"264<h3 id="remote-credentials-fetch-failed">

265 "원격 자격 증명 가져오기 실패"

266</h3>

226 267 

227Claude Code가 Anthropic API에서 연결을 설정하기 위한 단기 자격 증명을 얻을 수 없습니다. `--verbose`로 다시 실행하여 전체 오류를 확인하세요:268Claude Code가 Anthropic API에서 연결을 설정하기 위한 단기 자격 증명을 얻을 수 없습니다. `--verbose`로 다시 실행하여 전체 오류를 확인하세요:

228 269 


236* 네트워크 또는 프록시 문제: 방화벽 또는 프록시가 아웃바운드 HTTPS 요청을 차단할 수 있습니다. Remote Control은 포트 443의 Anthropic API에 대한 액세스가 필요합니다.277* 네트워크 또는 프록시 문제: 방화벽 또는 프록시가 아웃바운드 HTTPS 요청을 차단할 수 있습니다. Remote Control은 포트 443의 Anthropic API에 대한 액세스가 필요합니다.

237* 세션 생성 실패: `Session creation failed — see debug log`도 표시되면 설정 초기에 실패가 발생했습니다. 구독이 활성 상태인지 확인하세요.278* 세션 생성 실패: `Session creation failed — see debug log`도 표시되면 설정 초기에 실패가 발생했습니다. 구독이 활성 상태인지 확인하세요.

238 279 

239## 올바른 접근 방식 선택280<h2 id="choose-the-right-approach">

281 올바른 접근 방식 선택

282</h2>

240 283 

241Claude Code offers several ways to work when you're not at your terminal. They differ in what triggers the work, where Claude runs, and how much you need to set up.284Claude Code offers several ways to work when you're not at your terminal. They differ in what triggers the work, where Claude runs, and how much you need to set up.

242 285 


248| [Slack](/en/slack) | Mention `@Claude` in a team channel | Anthropic cloud | [Install the Slack app](/en/slack#setting-up-claude-code-in-slack) with [Claude Code on the web](/en/claude-code-on-the-web) enabled | PRs and reviews from team chat |291| [Slack](/en/slack) | Mention `@Claude` in a team channel | Anthropic cloud | [Install the Slack app](/en/slack#setting-up-claude-code-in-slack) with [Claude Code on the web](/en/claude-code-on-the-web) enabled | PRs and reviews from team chat |

249| [Scheduled tasks](/en/scheduled-tasks) | Set a schedule | [CLI](/en/scheduled-tasks), [Desktop](/en/desktop-scheduled-tasks), or [cloud](/en/routines) | Pick a frequency | Recurring automation like daily reviews |292| [Scheduled tasks](/en/scheduled-tasks) | Set a schedule | [CLI](/en/scheduled-tasks), [Desktop](/en/desktop-scheduled-tasks), or [cloud](/en/routines) | Pick a frequency | Recurring automation like daily reviews |

250 293 

251## 관련 리소스294<h2 id="related-resources">

295 관련 리소스

296</h2>

252 297 

253* [웹의 Claude Code](/ko/claude-code-on-the-web): 컴퓨터 대신 Anthropic 관리 클라우드 환경에서 세션 실행298* [웹의 Claude Code](/ko/claude-code-on-the-web): 컴퓨터 대신 Anthropic 관리 클라우드 환경에서 세션 실행

254* [Ultraplan](/ko/ultraplan): 터미널에서 클라우드 계획 세션을 시작하고 브라우저에서 계획을 검토합니다299* [Ultraplan](/ko/ultraplan): 터미널에서 클라우드 계획 세션을 시작하고 브라우저에서 계획을 검토합니다

routines.md +3 −3

Details

140 일정 트리거 추가140 일정 트리거 추가

141</h3>141</h3>

142 142 

143일정 트리거는 반복 주기에 따라 루틴을 실행하거나 특정 미래 시간에 한 번 실행합니다. **트리거 선택** 섹션에서 사전 설정된 빈도를 선택하세요. 시간별, 일일, 평일 또는 주간. 시간은 로컬 시간대에 입력되고 자동으로 변환되므로 클라우드 인프라가 어디에 있든 루틴이 해당 벽시계 시간에 실행됩니다.143일정 트리거는 반복 주기에 따라 루틴을 실행하거나 특정 미래 시간에 한 번 실행합니다. **트리거 선택** 섹션에서 사전 설정된 빈도를 선택하세요: 시간별, 일일, 평일 또는 주간. 시간은 로컬 시간대에 입력되고 자동으로 변환되므로 클라우드 인프라가 어디에 있든 루틴이 해당 벽시계 시간에 실행됩니다.

144 144 

145실행은 엇갈림으로 인해 예약된 시간 몇 분 후에 시작될 수 있습니다. 오프셋은 각 루틴에 대해 일관됩니다.145실행은 엇갈림으로 인해 예약된 시간 몇 분 후에 시작될 수 있습니다. 오프셋은 각 루틴에 대해 일관됩니다.

146 146 


297| 초안 여부 | PR이 초안 상태인지 여부 |297| 초안 여부 | PR이 초안 상태인지 여부 |

298| 병합 여부 | PR이 병합되었는지 여부 |298| 병합 여부 | PR이 병합되었는지 여부 |

299 299 

300각 필터는 필드를 연산자와 쌍으로 지정합니다. 같음, 포함, 시작, 하나, 하나 아님 또는 정규식 일치.300각 필터는 필드를 연산자와 쌍으로 지정합니다: 같음, 포함, 시작, 하나, 하나 아님 또는 정규식 일치.

301 301 

302`matches regex` 연산자는 전체 필드 값을 테스트하며, 그 내의 부분 문자열이 아닙니다. `hotfix`를 포함하는 제목과 일치하려면 `.*hotfix.*`를 작성하세요. 주변 `.*` 없이는 필터가 정확히 `hotfix`인 제목과만 일치하며 앞이나 뒤에 아무것도 없습니다. 정규식 구문 없이 리터럴 부분 문자열 일치의 경우 대신 `contains` 연산자를 사용하세요.302`matches regex` 연산자는 전체 필드 값을 테스트하며, 그 내의 부분 문자열이 아닙니다. `hotfix`를 포함하는 제목과 일치하려면 `.*hotfix.*`를 작성하세요. 주변 `.*` 없이는 필터가 정확히 `hotfix`인 제목과만 일치하며 앞이나 뒤에 아무것도 없습니다. 정규식 구문 없이 리터럴 부분 문자열 일치의 경우 대신 `contains` 연산자를 사용하세요.

303 303 


423 423 

424CLI가 어떻게 구성되어 있든 관계없이 [claude.ai/code/routines](https://claude.ai/code/routines)에서 언제든지 루틴을 생성하고 관리할 수 있습니다.424CLI가 어떻게 구성되어 있든 관계없이 [claude.ai/code/routines](https://claude.ai/code/routines)에서 언제든지 루틴을 생성하고 관리할 수 있습니다.

425 425 

426<h3 id="routines-are-disabled-by-your-organization-s-policy">426<h3 id="routines-are-disabled-by-your-organizations-policy">

427 "루틴이 조직의 정책에 의해 비활성화되었습니다"427 "루틴이 조직의 정책에 의해 비활성화되었습니다"

428</h3>428</h3>

429 429 

Details

65 65 

66[권한 모드](/ko/permission-modes)는 도구 호출이 실행되는지 여부와 먼저 프롬프트를 받는지 여부를 결정합니다. 격리는 명령이 실행되면 접근할 수 있는 항목을 제한합니다. 둘은 함께 작동합니다: 권한 모드가 작업을 묻지 않고 실행하도록 하면 격리 경계는 해당 작업이 도달할 수 있는 항목을 제한합니다.66[권한 모드](/ko/permission-modes)는 도구 호출이 실행되는지 여부와 먼저 프롬프트를 받는지 여부를 결정합니다. 격리는 명령이 실행되면 접근할 수 있는 항목을 제한합니다. 둘은 함께 작동합니다: 권한 모드가 작업을 묻지 않고 실행하도록 하면 격리 경계는 해당 작업이 도달할 수 있는 항목을 제한합니다.

67 67 

68`--dangerously-skip-permissions`는 작업별 검토를 완전히 제거하므로 격리 경계가 Claude가 할 수 있는 작업을 제한하는 유일한 것입니다. 항상 컨테이너, VM 또는 [샌드박스 런타임](#sandbox-runtime) 내에서 실행하여 파일 도구, MCP 서버, 훅도 경계 내에 있도록 하세요.68`--dangerously-skip-permissions`는 명시적 [요청 규칙](/ko/permissions#manage-permissions)을 제외한 작업별 검토를 제거하므로 격리 경계가 Claude가 할 수 있는 작업을 제한하는 유일한 것입니다. 항상 컨테이너, VM 또는 [샌드박스 런타임](#sandbox-runtime) 내에서 실행하여 파일 도구, MCP 서버, 훅도 경계 내에 있도록 하세요.

69 69 

70[자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)는 프롬프트를 요청을 초과하여 확대되거나 인식되지 않은 인프라를 대상으로 하거나 Claude가 읽은 적대적 콘텐츠에 의해 주도되는 것으로 보이는 작업을 검토하고 차단하는 분류기로 바꿉니다. 분류기는 작업별 제어이지 격리 경계가 아니므로 격리 경계는 여전히 무인 실행을 위한 심층 방어를 추가하며 `--dangerously-skip-permissions`의 경우처럼 필수는 아닙니다.70[자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)는 프롬프트를 요청을 초과하여 확대되거나 인식되지 않은 인프라를 대상으로 하거나 Claude가 읽은 적대적 콘텐츠에 의해 주도되는 것으로 보이는 작업을 검토하고 차단하는 분류기로 바꿉니다. 분류기는 작업별 제어이지 격리 경계가 아니므로 격리 경계는 여전히 무인 실행을 위한 심층 방어를 추가하며 `--dangerously-skip-permissions`의 경우처럼 필수는 아닙니다.

71 71 

sandboxing.md +10 −7

Details

49 </Step>49 </Step>

50 50 

51 <Step title="Bash 명령 실행">51 <Step title="Bash 명령 실행">

52 Claude에게 빌드 또는 테스트 스위트와 같은 명령을 실행하도록 요청합니다. 기본적으로 샌드박스 내의 명령은 작업 디렉토리에만 쓸 수 있습니다. 명령이 새 네트워크 도메인에 처음 액세스해야 할 때 Claude Code가 승인을 요청합니다.52 Claude에게 빌드 또는 테스트 스위트와 같은 명령을 실행하도록 요청합니다. 기본적으로 샌드박스 내의 명령은 작업 디렉토리 및 세션 임시 디렉토리에만 쓸 수 있습니다. 명령이 새 네트워크 도메인에 처음 액세스해야 할 때 Claude Code가 승인을 요청합니다.

53 53 

54 샌드박싱할 수 없는 명령은 일반 권한 흐름으로 폴백합니다. 이러한 경계를 확대하거나 축소하려면 [샌드박싱 구성](#configure-sandboxing)을 참조하세요.54 샌드박싱할 수 없는 명령은 일반 권한 흐름으로 폴백합니다. 이러한 경계를 확대하거나 축소하려면 [샌드박싱 구성](#configure-sandboxing)을 참조하세요.

55 </Step>55 </Step>


134 134 

135* 명시적 [거부 규칙](/ko/permissions)은 항상 존중됩니다135* 명시적 [거부 규칙](/ko/permissions)은 항상 존중됩니다

136* `/`, 홈 디렉토리 또는 기타 중요한 시스템 경로를 대상으로 하는 `rm` 또는 `rmdir` 명령은 여전히 권한 프롬프트를 트리거합니다136* `/`, 홈 디렉토리 또는 기타 중요한 시스템 경로를 대상으로 하는 `rm` 또는 `rmdir` 명령은 여전히 권한 프롬프트를 트리거합니다

137* [Ask 규칙](/ko/permissions)은 일반 권한 흐름으로 폴백되는 명령에 적용됩니다137* `Bash(git push *)`와 같은 콘텐츠 범위 [ask 규칙](/ko/permissions)은 샌드박싱된 명령에 대해서도 프롬프트를 강제합니다

138* 단순 `Bash` ask 규칙 또는 동등한 `Bash(*)` 형식은 샌드박싱된 명령에 대해 건너뛰어지며, 일반 권한 흐름으로 폴백되는 명령에는 여전히 적용됩니다

138 139 

139**일반 권한 모드**: 모든 Bash 명령은 샌드박싱되었더라도 일반 권한 흐름을 거칩니다. 이는 더 많은 제어를 제공하지만 더 많은 승인이 필요합니다.140**일반 권한 모드**: 모든 Bash 명령은 샌드박싱되었더라도 일반 권한 흐름을 거칩니다. 이는 더 많은 제어를 제공하지만 더 많은 승인이 필요합니다.

140 141 

141두 모드 모두에서 샌드박스는 동일한 파일시스템 및 네트워크 제한을 적용합니다. 차이점은 샌드박싱된 명령이 자동 승인되는지 또는 명시적 권한이 필요한지 여부뿐입니다.142두 모드 모두에서 샌드박스는 동일한 파일시스템 및 네트워크 제한을 적용합니다. 차이점은 샌드박싱된 명령이 자동 승인되는지 또는 명시적 권한이 필요한지 여부뿐입니다.

142 143 

144세션 임시 디렉토리는 기본적으로 작업 디렉토리와 함께 샌드박스 내에서 쓰기 가능합니다. Claude Code는 샌드박싱된 명령에 대해 `$TMPDIR`을 이 디렉토리로 설정하므로 임시 파일을 작성하는 도구는 추가 구성 없이 작동합니다. 샌드박싱되지 않은 명령은 셸의 `$TMPDIR`을 변경되지 않은 상태로 상속하므로, 샌드박싱된 명령과 샌드박싱되지 않은 명령은 `$TMPDIR`을 다른 디렉토리로 해석합니다. 두 명령 간에 임시 파일을 전달하려면 작업 디렉토리 아래에 작성하세요.

145 

143일부 명령은 샌드박스 내에서 전혀 실행할 수 없습니다. 예를 들어 호환되지 않는 도구나 허용하지 않은 호스트가 필요한 도구입니다. 작업을 실패하거나 샌드박싱을 끄도록 요구하는 대신 Claude Code는 탈출 해치를 포함합니다: 명령이 샌드박스 제한으로 인해 실패하면 Claude는 실패를 분석하고 `dangerouslyDisableSandbox` 매개변수로 명령을 다시 시도할 수 있습니다. 다시 시도된 명령은 샌드박스 외부에서 실행되므로 일반 권한 흐름을 거치고 승인이 필요합니다.146일부 명령은 샌드박스 내에서 전혀 실행할 수 없습니다. 예를 들어 호환되지 않는 도구나 허용하지 않은 호스트가 필요한 도구입니다. 작업을 실패하거나 샌드박싱을 끄도록 요구하는 대신 Claude Code는 탈출 해치를 포함합니다: 명령이 샌드박스 제한으로 인해 실패하면 Claude는 실패를 분석하고 `dangerouslyDisableSandbox` 매개변수로 명령을 다시 시도할 수 있습니다. 다시 시도된 명령은 샌드박스 외부에서 실행되므로 일반 권한 흐름을 거치고 승인이 필요합니다.

144 147 

145[샌드박스 설정](/ko/settings#sandbox-settings)에서 `"allowUnsandboxedCommands": false`를 설정하여 이 탈출 해치를 비활성화할 수 있습니다. 비활성화되면 `/sandbox` Overrides 탭에 **Strict sandbox mode**로 표시되며, `dangerouslyDisableSandbox` 매개변수는 완전히 무시되고 모든 명령은 샌드박싱되거나 `excludedCommands`에 명시적으로 나열되어야 합니다.148[샌드박스 설정](/ko/settings#sandbox-settings)에서 `"allowUnsandboxedCommands": false`를 설정하여 이 탈출 해치를 비활성화할 수 있습니다. 비활성화되면 `/sandbox` Overrides 탭에 **Strict sandbox mode**로 표시되며, `dangerouslyDisableSandbox` 매개변수는 완전히 무시되고 모든 명령은 샌드박싱되거나 `excludedCommands`에 명시적으로 나열되어야 합니다.


154 157 

155`settings.json` 파일을 통해 샌드박스 동작을 사용자 정의합니다. 전체 구성 참조는 [설정](/ko/settings#sandbox-settings)을 참조하세요.158`settings.json` 파일을 통해 샌드박스 동작을 사용자 정의합니다. 전체 구성 참조는 [설정](/ko/settings#sandbox-settings)을 참조하세요.

156 159 

157기본적으로 샌드박싱된 명령은 현재 작업 디렉토리에만 쓸 수 있습니다. `kubectl`, `terraform` 또는 `npm`과 같은 하위 프로세스 명령이 프로젝트 디렉토리 외부에 쓰기해야 하면 `sandbox.filesystem.allowWrite`를 사용하여 특정 경로에 대한 액세스를 부여합니다:160기본적으로 샌드박싱된 명령은 현재 작업 디렉토리와 세션 임시 디렉토리에만 쓸 수 있습니다. `kubectl`, `terraform` 또는 `npm`과 같은 하위 프로세스 명령이 해당 디렉토리 외부에 쓰기해야 하면 `sandbox.filesystem.allowWrite`를 사용하여 특정 경로에 대한 액세스를 부여합니다:

158 161 

159```json theme={null}162```json theme={null}

160{163{


209 212 

210샌드박싱된 Bash 도구는 파일 시스템 액세스를 특정 디렉토리로 제한합니다:213샌드박싱된 Bash 도구는 파일 시스템 액세스를 특정 디렉토리로 제한합니다:

211 214 

212* **기본 쓰기 동작**: 현재 작업 디렉토리 및 그 하위 디렉토리에 대한 읽기 및 쓰기 액세스215* **기본 쓰기 동작**: 현재 작업 디렉토리 및 그 하위 디렉토리에 대한 읽기 및 쓰기 액세스, 그리고 `$TMPDIR`이 가리키는 세션 임시 디렉토리에 대한 액세스

213* **기본 읽기 동작**: 특정 거부된 디렉토리를 제외한 전체 컴퓨터에 대한 읽기 액세스. 이 기본값은 여전히 `~/.aws/credentials` 및 `~/.ssh/`와 같은 자격 증명 파일 읽기를 허용합니다. 이를 차단하려면 `denyRead`에 추가합니다.216* **기본 읽기 동작**: 특정 거부된 디렉토리를 제외한 전체 컴퓨터에 대한 읽기 액세스. 이 기본값은 여전히 `~/.aws/credentials` 및 `~/.ssh/`와 같은 자격 증명 파일 읽기를 허용합니다. 이를 차단하려면 `denyRead`에 추가합니다.

214* **차단된 액세스**: 명시적 권한 없이 현재 작업 디렉토리 외부의 파일을 수정할 수 없습니다. `~/.bashrc`와 같은 셸 구성 파일 및 `/bin/`의 시스템 바이너리 포함217* **차단된 액세스**: 명시적 권한 없이 현재 작업 디렉토리 및 세션 임시 디렉토리 외부의 파일을 수정할 수 없습니다. `~/.bashrc`와 같은 셸 구성 파일 및 `/bin/`의 시스템 바이너리 포함

215* **Git worktrees**: 작업 디렉토리가 [연결된 git worktree](/ko/worktrees)일 때, 샌드박스는 또한 메인 저장소의 공유 `.git` 디렉토리에 대한 쓰기를 허용하므로 `git commit`과 같은 명령이 refs 및 인덱스를 업데이트할 수 있습니다. 해당 디렉토리 내의 `hooks/` 및 `config`에 대한 쓰기는 계속 거부됩니다.218* **Git worktrees**: 작업 디렉토리가 [연결된 git worktree](/ko/worktrees)일 때, 샌드박스는 또한 메인 저장소의 공유 `.git` 디렉토리에 대한 쓰기를 허용하므로 `git commit`과 같은 명령이 refs 및 인덱스를 업데이트할 수 있습니다. 해당 디렉토리 내의 `hooks/` 및 `config`에 대한 쓰기는 계속 거부됩니다.

216* **구성 가능**: 설정을 통해 사용자 정의 허용 및 거부 경로를 정의합니다219* **구성 가능**: 설정을 통해 사용자 정의 허용 및 거부 경로를 정의합니다

217 220 


287`/sandbox`는 [권한 모드](/ko/permission-modes)가 아닙니다. 권한 모드는 도구 호출이 실행되는지 여부와 먼저 프롬프트되는지 여부를 결정하는 반면, 샌드박스는 Bash 명령이 실행되면 액세스할 수 있는 것을 제한합니다. 제어하는 것과 작업별 프롬프트를 대체하는 것이 다릅니다:290`/sandbox`는 [권한 모드](/ko/permission-modes)가 아닙니다. 권한 모드는 도구 호출이 실행되는지 여부와 먼저 프롬프트되는지 여부를 결정하는 반면, 샌드박스는 Bash 명령이 실행되면 액세스할 수 있는 것을 제한합니다. 제어하는 것과 작업별 프롬프트를 대체하는 것이 다릅니다:

288 291 

289| | 제어하는 것 | 프롬프트를 대체하는 것 |292| | 제어하는 것 | 프롬프트를 대체하는 것 |

290| :------------------------------------------------------------- | :------------------------ | :------------------------------------------------------------------------------------------ |293| :------------------------------------------------------------- | :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------- |

291| `/sandbox` | Bash 명령이 실행되면 액세스할 수 있는 것 | [자동 허용 모드](#sandbox-modes)의 샌드박스 경계 자체 |294| `/sandbox` | Bash 명령이 실행되면 액세스할 수 있는 것 | [자동 허용 모드](#sandbox-modes)의 샌드박스 경계 자체 |

292| [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode) | 각 도구 호출이 실행되는지 여부 | 작업을 검토하는 분류기 |295| [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode) | 각 도구 호출이 실행되는지 여부 | 작업을 검토하는 분류기 |

293| `--dangerously-skip-permissions` | 각 도구 호출이 실행되는지 여부 | 없음. [보호된 경로](/ko/permission-modes#protected-paths) 확인도 건너뜁니다. `/` 또는 홈 디렉토리 제거만 여전히 프롬프트합니다 |296| `--dangerously-skip-permissions` | 각 도구 호출이 실행되는지 여부 | 없음. [보호된 경로](/ko/permission-modes#protected-paths) 확인도 건너뜁니다. 명시적 [요청 규칙](/ko/permissions#manage-permissions) 제거 및 `/` 또는 홈 디렉토리 제거만 여전히 프롬프트합니다 |

294 297 

295샌드박스의 [자동 허용 모드](#sandbox-modes)는 [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)와 별개입니다: 자동 허용은 샌드박스 경계가 이를 포함하기 때문에 Bash 명령을 승인하는 반면, 자동 모드는 분류기를 사용하여 작업을 검토합니다. 두 가지는 독립적으로 작동하며 결합할 수 있습니다. 무인 실행을 위한 격리 경계를 선택하려면 [샌드박스 환경](/ko/sandbox-environments#how-isolation-relates-to-permission-modes)을 참조하세요.298샌드박스의 [자동 허용 모드](#sandbox-modes)는 [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)와 별개입니다: 자동 허용은 샌드박스 경계가 이를 포함하기 때문에 Bash 명령을 승인하는 반면, 자동 모드는 분류기를 사용하여 작업을 검토합니다. 두 가지는 독립적으로 작동하며 결합할 수 있습니다. 무인 실행을 위한 격리 경계를 선택하려면 [샌드박스 환경](/ko/sandbox-environments#how-isolation-relates-to-permission-modes)을 참조하세요.

296 299 

Details

194 지터194 지터

195</h3>195</h3>

196 196 

197모든 세션이 동일한 벽시계 시간에 API에 도달하는 것을 방지하기 위해 스케줄러는 실행 시간에 결정론적 오프셋을 추가합니다:197스케줄러는 모든 세션이 동일한 벽시계 시간에 API에 도달하는 것을 방지하기 위해 실행 시간에 결정론적 오프셋을 추가합니다:

198 198 

199* 반복 작업은 스케줄된 시간 이후 최대 30분 후에 실행되거나(또는 시간별보다 더 자주 실행되는 작업의 경우 간격의 최대 절반), 최대 30분으로 제한됩니다. `:00`에 스케줄된 시간별 작업은 `:30`까지 언제든지 실행될 수 있습니다.199* 반복 작업은 스케줄된 시간 이후 최대 30분 후에 실행되거나(또는 시간별보다 더 자주 실행되는 작업의 경우 간격의 최대 절반), 최대 30분으로 제한됩니다. `:00`에 스케줄된 시간별 작업은 `:30`까지 언제든지 실행될 수 있습니다.

200* 시간의 맨 위 또는 맨 아래에 스케줄된 일회성 작업은 최대 90초 일찍 실행됩니다.200* 시간의 맨 위 또는 맨 아래에 스케줄된 일회성 작업은 최대 90초 일찍 실행됩니다.

security.md +11 −11

Details

22 22 

23Claude Code는 기본적으로 엄격한 읽기 전용 권한을 사용합니다. 추가 작업이 필요한 경우(파일 편집, 테스트 실행, 명령 실행), Claude Code는 명시적 권한을 요청합니다. 사용자는 작업을 한 번만 승인할지 또는 자동으로 허용할지 제어할 수 있습니다.23Claude Code는 기본적으로 엄격한 읽기 전용 권한을 사용합니다. 추가 작업이 필요한 경우(파일 편집, 테스트 실행, 명령 실행), Claude Code는 명시적 권한을 요청합니다. 사용자는 작업을 한 번만 승인할지 또는 자동으로 허용할지 제어할 수 있습니다.

24 24 

25Claude Code는 투명하고 안전하도록 설계되었습니다. 예를 들어, bash 명령을 실행하기 전에 승인을 요구하여 직접 제어할 있습니다. 이 접근 방식을 통해 사용자와 조직은 권한을 직접 구성할 수 있습니다.25Claude Code는 시스템을 수정할 있는 Bash 명령을 실행하기 전에 승인을 요구합니다. `ls`, `cat`, `git status`와 같은 기본 제공 읽기 전용 명령 집합은 프롬프트 없이 실행됩니다. 이 접근 방식을 통해 사용자와 조직은 권한을 직접 구성할 수 있습니다.

26 26 

27자세한 권한 구성은 [Permissions](/ko/permissions)를 참조하십시오.27자세한 권한 구성은 [Permissions](/ko/permissions)를 참조하십시오.

28 28 


32 32 

33에이전트 시스템의 위험을 완화하기 위해:33에이전트 시스템의 위험을 완화하기 위해:

34 34 

35* **샌드박스 bash 도구**: [Sandbox](/ko/sandboxing) 사용하여 bash 명령을 파일 시스템 및 네트워크 격리로 실행하여 권한 프롬프트를 줄이면서 보안을 유지합니다. `/sandbox`를 사용하여 Claude Code가 자율적으로 작업할 수 있는 경계를 정의하도록 활성화합니다.35* **샌드박스 bash 도구**: [Sandbox](/ko/sandboxing) bash 명령을 파일 시스템 및 네트워크 격리로 실행하여 권한 프롬프트를 줄이면서 보안을 유지합니다. `/sandbox`를 사용하여 Claude Code가 자율적으로 작업할 수 있는 경계를 정의하도록 활성화합니다.

36* **쓰기 액세스 제한**: Claude Code는 시작된 폴더와 그 하위 폴더에만 쓸 수 있으며, 명시적 권한 없이 상위 디렉토리의 파일을 수정할 수 없습니다. Claude Code는 작업 디렉토리 외부의 파일을 읽을 수 있지만(시스템 라이브러리 및 종속성에 액세스하는 데 유용함), 쓰기 작업은 프로젝트 범위로 엄격히 제한되어 명확한 보안 경계를 만듭니다.36* **쓰기 액세스 제한**: Claude Code는 시작된 폴더와 그 하위 폴더에만 쓸 수 있으며, 명시적 권한 없이 상위 디렉토리의 파일을 수정할 수 없습니다. Claude Code는 작업 디렉토리 외부의 파일을 읽을 수 있지만(시스템 라이브러리 및 종속성에 액세스하는 데 유용함), 쓰기 작업은 프로젝트 범위로 엄격히 제한되어 명확한 보안 경계를 만듭니다.

37* **프롬프트 피로 완화**: 사용자별, 코드베이스별 또는 조직별로 자주 사용되는 안전한 명령을 허용 목록에 추가하는 지원37* **프롬프트 피로 완화**: 사용자별, 코드베이스별 또는 조직별로 자주 사용되는 안전한 명령을 허용 목록에 추가하는 지원

38* **Accept Edits 모드**: 파일 편집을 자동으로 승인하고 작업 디렉토리의 경로에 대해 `mkdir`, `touch`, `rm`, `mv`, `cp`, `sed`와 같은 고정된 파일 시스템 Bash 명령 집합을 자동으로 승인합니다. 다른 Bash 명령과 범위를 벗어난 경로는 여전히 프롬프트를 표시합니다.38* **Accept Edits 모드**: 파일 편집을 자동으로 승인하고 작업 디렉토리의 경로에 대해 `mkdir`, `touch`, `rm`, `mv`, `cp`, `sed`와 같은 고정된 파일 시스템 Bash 명령 집합을 자동으로 승인합니다. 다른 Bash 명령과 범위를 벗어난 경로는 여전히 프롬프트를 표시합니다.


56* **권한 시스템**: 민감한 작업에는 명시적 승인이 필요합니다.56* **권한 시스템**: 민감한 작업에는 명시적 승인이 필요합니다.

57* **컨텍스트 인식 분석**: 전체 요청을 분석하여 잠재적으로 해로운 지시사항을 감지합니다.57* **컨텍스트 인식 분석**: 전체 요청을 분석하여 잠재적으로 해로운 지시사항을 감지합니다.

58* **입력 살균**: 사용자 입력을 처리하여 명령 주입을 방지합니다.58* **입력 살균**: 사용자 입력을 처리하여 명령 주입을 방지합니다.

59* **명령 차단 목록**: `curl` 및 `wget`과 같이 웹에서 임의의 콘텐츠를 가져오는 위험한 명령을 기본적으로 차단합니다. 명시적으로 허용된 경우 [권한 패턴 제한](/ko/permissions#tool-specific-permission-rules) 인식하십시오.59* **네트워크 명령 승인**: `curl` 및 `wget`과 같이 웹에서 콘텐츠를 가져오는 명령은 기본적으로 자동 승인되지 않습니다. 다른 읽기 전용이 아닌 Bash 명령처럼 프롬프트가 표시되므로 한 번 승인하거나 `Bash(curl *)`와 같은 명시적 허용 규칙을 추가할 수 있습니다. 완전히 차단하려면 [`permissions.deny`](/ko/permissions#tool-specific-permission-rules) 추가하십시오.

60 60 

61<h3 id="privacy-safeguards">61<h3 id="privacy-safeguards">

62 개인정보 보호 장치62 개인정보 보호 장치


77* **네트워크 요청 승인**: 네트워크 요청을 하는 도구는 기본적으로 사용자 승인이 필요합니다.77* **네트워크 요청 승인**: 네트워크 요청을 하는 도구는 기본적으로 사용자 승인이 필요합니다.

78* **격리된 컨텍스트 윈도우**: 웹 가져오기는 별도의 컨텍스트 윈도우를 사용하여 잠재적으로 악의적인 프롬프트 주입을 방지합니다.78* **격리된 컨텍스트 윈도우**: 웹 가져오기는 별도의 컨텍스트 윈도우를 사용하여 잠재적으로 악의적인 프롬프트 주입을 방지합니다.

79* **신뢰 확인**: 첫 번째 코드베이스 실행 및 새 MCP 서버는 신뢰 확인이 필요합니다.79* **신뢰 확인**: 첫 번째 코드베이스 실행 및 새 MCP 서버는 신뢰 확인이 필요합니다.

80 * 참고: `-p` 플래그를 사용하여 비대화형으로 실행할 때 신뢰 확인이 비활성화됩니다. 예외는 [`--worktree`](/ko/worktrees)이며, 이는 여전히 디렉토리에 대해 신뢰가 수락되었어야 합니다.80 * 참고: `-p` 플래그를 사용하여 비대화형으로 실행할 때 신뢰 확인이 비활성화됩니다.

81 * 참고: Claude Code를 홈 디렉토리에서 직접 시작할 때 신뢰 수락은 현재 세션에만 유지되며 디스크에 기록되지 않으므로 각 시작 시 프롬프트가 다시 나타납니다. 이를 유지하는 설정은 없습니다. 신뢰 수락이 디렉토리별로 저장되는 프로젝트 하위 디렉토리에서 Claude Code를 시작하십시오.81 * 참고: Claude Code를 홈 디렉토리에서 직접 시작할 때 신뢰 수락은 현재 세션에만 유지되며 디스크에 기록되지 않으므로 각 시작 시 프롬프트가 다시 나타납니다. 이를 유지하는 설정은 없습니다. 신뢰 수락이 디렉토리별로 저장되는 프로젝트 하위 디렉토리에서 Claude Code를 시작하십시오.

82* **명령 주입 감지**: 의심스러운 bash 명령은 이전에 허용 목록에 있었더라도 수동 승인이 필요합니다.82* **명령 주입 감지**: 의심스러운 bash 명령은 이전에 허용 목록에 있었더라도 수동 승인이 필요합니다.

83* **폐쇄형 매칭 실패**: 일치하지 않는 명령은 기본적으로 수동 승인이 필요합니다.83* **폐쇄형 매칭 실패**: 일치하지 않는 명령은 기본적으로 수동 승인이 필요합니다.

84* **자연어 설명**: 복잡한 bash 명령에는 사용자 이해를 위한 설명이 포함됩니다.84* **자연어 설명**: 복잡한 bash 명령에는 사용자 이해를 위한 설명이 포함됩니다.

85* **보안 자격증명 저장소**: API 키 및 토큰은 암호화됩니다. [Credential Management](/ko/authentication#credential-management)를 참조하십시오.85* **보안 자격증명 저장소**: API 키 및 토큰은 사용 가능한 경우 macOS Keychain에 저장되며, Windows 및 Linux에서는 파일 권한으로 보호됩니다. [Credential Management](/ko/authentication#credential-management)를 참조하십시오.

86 86 

87<Warning>87<Warning>

88 **Windows WebDAV 보안 위험**: Windows에서 Claude Code를 실행할 때 WebDAV를 활성화하거나 Claude Code가 WebDAV 하위 디렉토리를 포함할 수 있는 `\\*`와 같은 경로에 액세스하도록 허용하지 않는 것이 좋습니다. [WebDAV는 Microsoft에서 보안 위험으로 인해 더 이상 사용되지 않습니다](https://learn.microsoft.com/en-us/windows/whats-new/deprecated-features#:~:text=The%20Webclient%20\(WebDAV\)%20service%20is%20deprecated). WebDAV를 활성화하면 Claude Code가 원격 호스트에 대한 네트워크 요청을 트리거하여 권한 시스템을 우회할 수 있습니다.88 **Windows WebDAV 보안 위험**: Windows에서 Claude Code를 실행할 때 WebDAV를 활성화하거나 Claude Code가 WebDAV 하위 디렉토리를 포함할 수 있는 `\\*`와 같은 경로에 액세스하도록 허용하지 않는 것이 좋습니다. [WebDAV는 Microsoft에서 보안 위험으로 인해 더 이상 사용되지 않습니다](https://learn.microsoft.com/en-us/windows/whats-new/deprecated-features#:~:text=The%20Webclient%20\(WebDAV\)%20service%20is%20deprecated). WebDAV를 활성화하면 Claude Code가 원격 호스트에 대한 네트워크 요청을 트리거하여 권한 시스템을 우회할 수 있습니다.


120 120 

121[웹에서 Claude Code](/ko/claude-code-on-the-web)를 사용할 때 추가 보안 제어가 적용됩니다:121[웹에서 Claude Code](/ko/claude-code-on-the-web)를 사용할 때 추가 보안 제어가 적용됩니다:

122 122 

123* **격리된 가상 머신**: 각 클라우드 세션은 격리된 Anthropic 관리 VM에서 실행됩니다.123* **격리된 가상 머신**: 각 클라우드 세션은 격리된 Anthropic 관리 VM에서 실행됩니다

124* **네트워크 액세스 제어**: 네트워크 액세스는 기본적으로 제한되며 비활성화되거나 특정 도메인만 허용하도록 구성할 수 있습니다.124* **네트워크 액세스 제어**: 네트워크 액세스는 기본적으로 제한되며 비활성화되거나 특정 도메인만 허용하도록 구성할 수 있습니다

125* **자격증명 보호**: 인증은 샌드박스 내에서 범위가 지정된 자격증명을 사용하는 보안 프록시를 통해 처리되며, 이는 실제 GitHub 인증 토큰으로 변환됩니다.125* **자격증명 보호**: 인증은 샌드박스 내에서 범위가 지정된 자격증명을 사용하는 보안 프록시를 통해 처리되며, 이는 실제 GitHub 인증 토큰으로 변환됩니다

126* **분기 제한**: Git 푸시 작업은 현재 작업 분기로 제한됩니다.126* **분기 제한**: Git 푸시 작업은 현재 작업 분기로 제한됩니다

127* **감사 로깅**: 클라우드 환경의 모든 작업은 규정 준수 및 감사 목적으로 기록됩니다.127* **감사 로깅**: 클라우드 환경의 모든 작업은 규정 준수 및 감사 목적으로 기록됩니다

128* **자동 정리**: 클라우드 환경은 세션 완료 후 자동으로 종료됩니다.128* **자동 정리**: 클라우드 환경은 세션 완료 후 자동으로 종료됩니다

129 129 

130클라우드 실행에 대한 자세한 내용은 [Claude Code on the web](/ko/claude-code-on-the-web)을 참조하십시오.130클라우드 실행에 대한 자세한 내용은 [Claude Code on the web](/ko/claude-code-on-the-web)을 참조하십시오.

131 131 

Details

260 260 

261검토 계층이 대화에서 메시지 없이 건너뛰는 일반적인 이유:261검토 계층이 대화에서 메시지 없이 건너뛰는 일반적인 이유:

262 262 

263* 디렉터리가 git 저장소가 아닙니다: 턴 끝 및 커밋 검토는 git 상태가 필요하고 저장소 외부에서 건너뜁니다.263* 디렉터리가 git 저장소가 아닙니다: 턴 끝 및 커밋 검토는 git 상태가 필요하고 저장소 외부에서 건너뜁니다

264* 세션에 Anthropic 인증이 없습니다: 모델 지원 검토는 건너뛰고 편집당 패턴 확인만 실행됩니다.264* 세션에 Anthropic 인증이 없습니다: 모델 지원 검토는 건너뛰고 편집당 패턴 확인만 실행됩니다

265* `security-patterns.yaml` 파일이 있지만 PyYAML을 가져올 수 없습니다: 파일이 무시됩니다. 대신 `security-patterns.json`을 사용합니다.265* `security-patterns.yaml` 파일이 있지만 PyYAML을 가져올 수 없습니다: 파일이 무시됩니다. 대신 `security-patterns.json`을 사용하십시오

266 266 

267<h2 id="related-resources">267<h2 id="related-resources">

268 관련 리소스268 관련 리소스

Details

174 174 

175Claude Code는 OpenTelemetry 구성과 같은 고급 설정을 제외하고 재시작 없이 설정 업데이트를 자동으로 적용하며, 이는 적용되려면 전체 재시작이 필요합니다.175Claude Code는 OpenTelemetry 구성과 같은 고급 설정을 제외하고 재시작 없이 설정 업데이트를 자동으로 적용하며, 이는 적용되려면 전체 재시작이 필요합니다.

176 176 

177<h3 id="invalid-entries-in-delivered-settings">

178 전달된 설정의 잘못된 항목

179</h3>

180 

181전달된 페이로드는 다른 관리 소스와 동일한 규칙으로 관대하게 구문 분석됩니다. 페이로드에 스키마 검증에 실패하는 항목이 포함되어 있으면 Claude Code는 해당 항목을 제거하고 검증 오류를 표시하며 남은 모든 유효한 설정을 적용합니다. 보안 적용 필드 처리 방법을 포함한 필드 수준 동작은 [관리 설정의 잘못된 항목](/ko/settings#invalid-entries-in-managed-settings)을 참조하십시오. Claude Code v2.1.169 이상이 필요합니다.

182 

183서버 관리 전달은 다음 동작을 추가합니다.

184 

185* `~/.claude/remote-settings.json`의 캐시는 잘못된 항목이 제거된 구제된 페이로드를 저장합니다. 원본 잘못된 페이로드는 절대 유지되지 않습니다.

186* 페이로드의 어떤 필드도 구제할 수 없으면 Claude Code는 마지막으로 수락된 캐시된 설정을 유지하고 치명적 오류를 기록합니다.

187* [보안 승인 대화](#security-approval-dialogs)는 구제된 페이로드를 평가하므로 제거된 잘못된 항목은 승인을 위해 표시되지 않으며 실행되지 않습니다.

188 

189전달 문제를 디버깅하려면 `claude --debug-file <path>`를 실행하고 로그에서 `Remote settings`를 검색합니다. 조직에 배포하기 전에 테스트 머신에서 `claude doctor`로 페이로드 변경을 검증합니다.

190 

177<h3 id="enforce-fail-closed-startup">191<h3 id="enforce-fail-closed-startup">

178 강제 실패 폐쇄 시작192 강제 실패 폐쇄 시작

179</h3>193</h3>

sessions.md +5 −5

Details

30| `claude --from-pr <number>` | 해당 풀 요청에 연결된 세션을 재개합니다 |30| `claude --from-pr <number>` | 해당 풀 요청에 연결된 세션을 재개합니다 |

31| `/resume` | 활성 세션 내에서 다른 대화로 전환합니다 |31| `/resume` | 활성 세션 내에서 다른 대화로 전환합니다 |

32 32 

33[`claude -p`](/ko/headless) 또는 [Agent SDK](/ko/agent-sdk/overview)로 생성된 세션은 세션 선택기에 나타나지 않지만, 세션 ID를 `claude --resume <session-id>`에 전달하여 여전히 재개할 수 있습니다.33[`claude -p`](/ko/headless) 또는 [Agent SDK](/ko/agent-sdk/overview)로 생성된 세션은 세션 선택기에 나타나지 않지만, 세션 ID를 `claude --resume <session-id>`에 전달하여 여전히 재개할 수 있습니다. 세션이 시작된 디렉토리에서 이를 실행합니다. 세션 ID 조회는 현재 프로젝트 디렉토리 및 해당 git worktree로 범위가 지정되므로, 다른 곳에서 생성된 세션은 `No conversation found with session ID: <session-id>`를 보고합니다.

34 34 

35<h3 id="where-the-session-picker-looks">35<h3 id="where-the-session-picker-looks">

36 세션 선택기가 찾는 위치36 세션 선택기가 찾는 위치

37</h3>37</h3>

38 38 

39세션은 프로젝트 디렉토리별로 저장됩니다. 기본적으로 세션 선택기는 현재 worktree의 대화형 세션과 `/add-dir`로 현재 디렉토리를 추가한 다른 곳에서 시작된 세션을 표시합니다. `Ctrl+W`를 사용하여 저장소의 모든 worktree로 확장하거나 `Ctrl+A`를 사용하여 이 머신의 모든 프로젝트로 확장합니다.39세션은 프로젝트 디렉토리별로 저장됩니다. 기본적으로 세션 선택기는 현재 worktree의 대화형 세션과 `/add-dir`로 현재 디렉토리를 추가한 다른 곳에서 시작된 세션을 표시합니다. {/* min-version: 2.1.169 */}v2.1.169부터 [`/cd`](/ko/commands)로 세션을 이동하면 새 디렉토리의 프로젝트 저장소로 재배치되므로 이후 해당 디렉토리의 선택기에 나타납니다. `Ctrl+W`를 사용하여 저장소의 모든 worktree로 확장하거나 `Ctrl+A`를 사용하여 이 머신의 모든 프로젝트로 확장합니다.

40 40 

41같은 저장소의 다른 worktree에서 세션을 선택하면 그 위치에서 재개됩니다. 관련 없는 프로젝트에서 세션을 선택하면 `cd` 및 재개 명령을 클립보드에 복사합니다.41같은 저장소의 다른 worktree에서 세션을 선택하면 그 위치에서 재개됩니다. 관련 없는 프로젝트에서 세션을 선택하면 `cd` 및 재개 명령을 클립보드에 복사합니다.

42 42 


136이 페이지들은 관련 세션 및 병렬 처리 메커니즘을 다룹니다:136이 페이지들은 관련 세션 및 병렬 처리 메커니즘을 다룹니다:

137 137 

138* [Worktrees](/ko/worktrees): 별도 분기에서 격리된 병렬 세션 실행138* [Worktrees](/ko/worktrees): 별도 분기에서 격리된 병렬 세션 실행

139* [체크포인팅](/ko/checkpointing): 코드 및 대화를 이전 지점으로 되감기139* [Checkpointing](/ko/checkpointing): 코드 및 대화를 이전 지점으로 되감기

140* [컨텍스트 윈도우](/ko/context-window): 컨텍스트를 채우는 것과 압축 후 유지되는 것140* [Context window](/ko/context-window): 컨텍스트를 채우는 것과 압축 후 유지되는 것

141* [비대화형 모드](/ko/headless): `claude -p` 아래의 세션 동작141* [Non-interactive mode](/ko/headless): `claude -p` 아래의 세션 동작

settings.md +118 −32

Details

94* **사용자 설정**은 `~/.claude/settings.json`에 정의되며 모든 프로젝트에 적용됩니다.94* **사용자 설정**은 `~/.claude/settings.json`에 정의되며 모든 프로젝트에 적용됩니다.

95* **프로젝트 설정**은 프로젝트 디렉토리에 저장됩니다:95* **프로젝트 설정**은 프로젝트 디렉토리에 저장됩니다:

96 * 소스 제어에 체크인되고 팀과 공유되는 설정을 위한 `.claude/settings.json`96 * 소스 제어에 체크인되고 팀과 공유되는 설정을 위한 `.claude/settings.json`

97 * 체크인되지 않은 설정을 위한 `.claude/settings.local.json`으로, 개인 설정 및 실험에 유용합니다. Claude Code는 `.claude/settings.local.json`이 생성될 때 git을 구성하여 이를 무시하도록 합니다.97 * 체크인되지 않은 설정을 위한 `.claude/settings.local.json`으로, 개인 설정 및 실험에 유용합니다. Claude Code는 `.claude/settings.local.json`이 생성될 때 git을 구성하여 이를 무시하도록 합니다. 파일을 직접 생성하는 경우 gitignore에 수동으로 추가합니다.

98* **Managed 설정**: 중앙 집중식 제어가 필요한 조직의 경우 Claude Code는 managed 설정을 위한 여러 전달 메커니즘을 지원합니다. 모두 동일한 JSON 형식을 사용하며 사용자 또는 프로젝트 설정으로 재정의할 수 없습니다:98* **Managed 설정**: 중앙 집중식 제어가 필요한 조직의 경우 Claude Code는 managed 설정을 위한 여러 전달 메커니즘을 지원합니다. 모두 동일한 JSON 형식을 사용하며 사용자 또는 프로젝트 설정으로 재정의할 수 없습니다:

99 99 

100 * **서버 관리 설정**: Anthropic의 서버에서 Claude.ai 관리 콘솔을 통해 전달됩니다. [서버 관리 설정](/ko/server-managed-settings)을 참조하세요.100 * **서버 관리 설정**: Anthropic의 서버에서 Claude.ai 관리 콘솔을 통해 전달됩니다. [서버 관리 설정](/ko/server-managed-settings)을 참조하세요.

101 * **MDM/OS 수준 정책**: macOS 및 Windows의 기본 장치 관리를 통해 전달됩니다:101 * **MDM/OS 수준 정책**: macOS 및 Windows의 기본 장치 관리를 통해 전달됩니다:

102 * macOS: `com.anthropic.claudecode` managed preferences domain. plist의 최상위 키는 `managed-settings.json`을 반영하며, 중첩된 설정은 딕셔너리이고 배열은 plist 배열입니다. Jamf, Kandji (Iru) 또는 유사한 MDM 도구의 구성 프로필을 통해 배포합니다.102 * macOS: `com.anthropic.claudecode` managed preferences domain. plist의 최상위 키는 `managed-settings.json`을 반영하며, 중첩된 설정은 딕셔너리이고 배열은 plist 배열입니다. Jamf, Iru (Kandji) 또는 유사한 MDM 도구의 구성 프로필을 통해 배포합니다.

103 * Windows: `HKLM\SOFTWARE\Policies\ClaudeCode` 레지스트리 키와 JSON을 포함하는 `Settings` 값 (REG\_SZ 또는 REG\_EXPAND\_SZ) (그룹 정책 또는 Intune을 통해 배포)103 * Windows: `HKLM\SOFTWARE\Policies\ClaudeCode` 레지스트리 키와 JSON을 포함하는 `Settings` 값 (REG\_SZ 또는 REG\_EXPAND\_SZ) (그룹 정책 또는 Intune을 통해 배포)

104 * Windows (사용자 수준): `HKCU\SOFTWARE\Policies\ClaudeCode` (최저 정책 우선순위, 관리자 수준 소스가 없을 때만 사용)104 * Windows (사용자 수준): `HKCU\SOFTWARE\Policies\ClaudeCode` (최저 정책 우선순위, 관리자 수준 소스가 없을 때만 사용)

105 * **파일 기반**: 시스템 디렉토리에 배포된 `managed-settings.json` 및 `managed-mcp.json`:105 * **파일 기반**: 시스템 디렉토리에 배포된 `managed-settings.json` 및 `managed-mcp.json`:


120 120 

121 [managed 설정](/ko/permissions#managed-only-settings) 및 [Managed MCP 구성](/ko/managed-mcp)을 참조하세요.121 [managed 설정](/ko/permissions#managed-only-settings) 및 [Managed MCP 구성](/ko/managed-mcp)을 참조하세요.

122 122 

123 이 [저장소](https://github.com/anthropics/claude-code/tree/main/examples/mdm)에는 Jamf, Kandji (Iru), Intune 및 그룹 정책에 대한 시작 배포 템플릿이 포함되어 있습니다. 이를 시작점으로 사용하고 필요에 맞게 조정합니다.123 이 [저장소](https://github.com/anthropics/claude-code/tree/main/examples/mdm)에는 Jamf, Iru (Kandji), Intune 및 그룹 정책에 대한 시작 배포 템플릿이 포함되어 있습니다. 이를 시작점으로 사용하고 필요에 맞게 조정합니다.

124 124 

125 <Note>125 <Note>

126 Managed 배포는 `strictKnownMarketplaces`를 사용하여 **플러그인 마켓플레이스 추가**를 제한할 수도 있습니다. 자세한 내용은 [Managed 마켓플레이스 제한](/ko/plugin-marketplaces#managed-marketplace-restrictions)을 참조하세요.126 Managed 배포는 `strictKnownMarketplaces`를 사용하여 **플러그인 마켓플레이스 추가**를 제한할 수도 있습니다. 자세한 내용은 [Managed 마켓플레이스 제한](/ko/plugin-marketplaces#managed-marketplace-restrictions)을 참조하세요.


174* `model`: 세션 중에 전환하려면 [`/model`](/ko/model-config#setting-your-model)을 사용합니다174* `model`: 세션 중에 전환하려면 [`/model`](/ko/model-config#setting-your-model)을 사용합니다

175* [`outputStyle`](/ko/output-styles): 시스템 프롬프트의 일부로, `/clear` 또는 재시작 시 다시 빌드됩니다175* [`outputStyle`](/ko/output-styles): 시스템 프롬프트의 일부로, `/clear` 또는 재시작 시 다시 빌드됩니다

176 176 

177<h3 id="invalid-entries-in-managed-settings">

178 Managed 설정의 유효하지 않은 항목

179</h3>

180 

181Managed 설정은 관대하게 파싱됩니다. Managed 구성에 스키마 검증에 실패하는 항목이 포함되어 있으면 Claude Code는 해당 항목을 제거하고 경고를 기록하며 남은 모든 유효한 정책을 적용합니다. 단일 오타가 조직의 나머지 정책을 비활성화할 수 없습니다. 이 동작은 세 가지 전달 메커니즘 모두에서 일관됩니다: [서버 관리 설정](/ko/server-managed-settings), MDM을 통해 배포된 plist 및 레지스트리 정책, 그리고 `managed-settings.json` 파일. Claude Code v2.1.169 이상이 필요합니다.

182 

183보안 적용 필드는 전체적으로 제거되는 대신 필드별로 처리됩니다:

184 

185| 필드 | 존재하지만 유효하지 않을 때의 동작 |

186| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------- |

187| `allowedMcpServers` | 값이 수정될 때까지 MCP 서버가 허용되지 않도록 빈 허용 목록으로 적용됩니다. 개별 유효하지 않은 항목은 제거되고 유효한 부분 집합이 적용됩니다. |

188| `allowManagedMcpServersOnly` | `true`로 처리됩니다. |

189| `availableModels` | {/* min-version: 2.1.175 */}값이 수정될 때까지 기본 모델만 사용 가능하도록 빈 허용 목록으로 적용됩니다. 개별 비문자열 항목은 제거되고 유효한 부분 집합이 적용됩니다. v2.1.175 이상에 적용됩니다. |

190| `enforceAvailableModels` | {/* min-version: 2.1.175 */}}`true`로 처리됩니다. v2.1.175 이상에 적용됩니다. |

191| `forceLoginOrgUUID` | 값이 수정될 때까지 조직이 로그인할 수 없습니다. |

192| `deniedMcpServers` | 개별 유효하지 않은 항목은 제거되고 유효한 부분 집합이 적용됩니다. 완전히 유효하지 않은 값은 경고와 함께 삭제됩니다. 모든 서버를 거부하면 정책이 명명하지 않은 서버를 차단하기 때문입니다. |

193 

194`requiredMinimumVersion` 및 `requiredMaximumVersion`은 설계상 실패하도록 열려 있습니다: 유효하지 않은 값은 적용되지 않고 제거되므로 잘못된 정책 푸시가 Claude Code 시작을 방지할 수 없습니다.

195 

196검증 오류는 세 곳에 표시됩니다:

197 

198* 대화형 세션은 시작 시 유효하지 않은 항목을 나열하는 대화를 표시합니다.

199* `-p`를 사용한 헤드리스 실행은 stderr에 요약을 인쇄합니다.

200* [`claude doctor`](/ko/debug-your-config)는 각 유효하지 않은 항목을 소스 및 필드와 함께 나열합니다.

201 

202정책 변경을 검증하려면 전사 배포 전에 테스트 머신에서 `claude doctor`를 실행합니다.

203 

204이 관대함은 managed 설정에만 적용됩니다. 사용자, 프로젝트 및 local 설정 파일은 엄격합니다: 검증에 실패하는 파일은 전체적으로 거부되고 보고됩니다.

205 

177<h3 id="available-settings">206<h3 id="available-settings">

178 사용 가능한 설정207 사용 가능한 설정

179</h3>208</h3>


181`settings.json`은 여러 옵션을 지원합니다:210`settings.json`은 여러 옵션을 지원합니다:

182 211 

183| 키 | 설명 | 예제 |212| 키 | 설명 | 예제 |

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

214| `advisorModel` | {/* min-version: 2.1.98 */}서버 측 [advisor 도구](/ko/advisor)를 위한 모델입니다. `"opus"`, `"sonnet"` 또는 `"fable"` ({/* min-version: 2.1.170 */}v2.1.170+)과 같은 모델 별칭 또는 전체 모델 ID를 허용합니다. `/advisor`를 실행할 때 자동으로 작성됩니다. Advisor를 비활성화하려면 설정 해제합니다. Claude Code v2.1.98 이상이 필요합니다 | `"opus"` |

185| `agent` | 메인 스레드를 명명된 subagent로 실행하고 `claude agents`에서 디스패치된 세션의 기본 에이전트를 설정합니다. 해당 subagent의 시스템 프롬프트, 도구 제한 및 모델을 적용합니다. [subagents 명시적으로 호출](/ko/sub-agents#invoke-subagents-explicitly)을 참조하세요 | `"code-reviewer"` |215| `agent` | 메인 스레드를 명명된 subagent로 실행하고 `claude agents`에서 디스패치된 세션의 기본 에이전트를 설정합니다. 해당 subagent의 시스템 프롬프트, 도구 제한 및 모델을 적용합니다. [subagents 명시적으로 호출](/ko/sub-agents#invoke-subagents-explicitly)을 참조하세요 | `"code-reviewer"` |

216| `agentPushNotifEnabled` | {/* min-version: 2.1.119 */}}[Remote Control](/ko/remote-control)이 연결되어 있을 때 Claude가 장시간 작업이 완료될 때와 같이 휴대폰에 사전 예방적 푸시 알림을 보낼 수 있도록 허용합니다. 기본값: `false`. `/config`에 **Claude가 결정할 때 푸시**로 표시됩니다. [모바일 푸시 알림](/ko/remote-control#mobile-push-notifications)을 참조하세요. Claude Code v2.1.119 이상이 필요합니다 | `true` |

186| `allowAllClaudeAiMcps` | (Managed 설정만) 배포된 `managed-mcp.json`과 함께 claude.ai 커넥터를 로드합니다. 그렇지 않으면 독점적 제어를 취하고 이를 억제합니다. [Managed MCP 구성](/ko/managed-mcp)을 참조하세요 | `true` |217| `allowAllClaudeAiMcps` | (Managed 설정만) 배포된 `managed-mcp.json`과 함께 claude.ai 커넥터를 로드합니다. 그렇지 않으면 독점적 제어를 취하고 이를 억제합니다. [Managed MCP 구성](/ko/managed-mcp)을 참조하세요 | `true` |

187| `allowedChannelPlugins` | (Managed 설정만) 메시지를 푸시할 수 있는 채널 플러그인의 허용 목록입니다. 설정되면 기본 Anthropic 허용 목록을 대체합니다. 정의되지 않음 = 기본값으로 폴백, 빈 배열 = 모든 채널 플러그인 차단. `channelsEnabled: true`가 필요합니다. [채널 플러그인 실행 제한](/ko/channels#restrict-which-channel-plugins-can-run)을 참조하세요 | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |218| `allowedChannelPlugins` | (Managed 설정만) 메시지를 푸시할 수 있는 채널 플러그인의 허용 목록입니다. 설정되면 기본 Anthropic 허용 목록을 대체합니다. 정의되지 않음 = 기본값으로 폴백, 빈 배열 = 모든 채널 플러그인 차단. `channelsEnabled: true`가 필요합니다. [채널 플러그인 실행 제한](/ko/channels#restrict-which-channel-plugins-can-run)을 참조하세요 | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |

188| `allowedHttpHookUrls` | HTTP hooks가 대상으로 할 수 있는 URL 패턴의 허용 목록입니다. `*`를 와일드카드로 지원합니다. 설정되면 일치하지 않는 URL을 가진 hooks는 차단됩니다. 정의되지 않음 = 제한 없음, 빈 배열 = 모든 HTTP hooks 차단. 배열은 설정 소스 전체에서 병합됩니다. [Hook 구성](#hook-configuration)을 참조하세요 | `["https://hooks.example.com/*"]` |219| `allowedHttpHookUrls` | HTTP hooks가 대상으로 할 수 있는 URL 패턴의 허용 목록입니다. `*`를 와일드카드로 지원합니다. 설정되면 일치하지 않는 URL을 가진 hooks는 차단됩니다. 정의되지 않음 = 제한 없음, 빈 배열 = 모든 HTTP hooks 차단. 배열은 설정 소스 전체에서 병합됩니다. [Hook 구성](#hook-configuration)을 참조하세요 | `["https://hooks.example.com/*"]` |


190| `allowManagedHooksOnly` | (Managed 설정만) Managed hooks, SDK hooks 및 managed 설정 `enabledPlugins`에서 강제 활성화된 플러그인의 hooks만 로드됩니다. 사용자, 프로젝트 및 다른 모든 플러그인 hooks는 차단됩니다. [Hook 구성](#hook-configuration)을 참조하세요 | `true` |221| `allowManagedHooksOnly` | (Managed 설정만) Managed hooks, SDK hooks 및 managed 설정 `enabledPlugins`에서 강제 활성화된 플러그인의 hooks만 로드됩니다. 사용자, 프로젝트 및 다른 모든 플러그인 hooks는 차단됩니다. [Hook 구성](#hook-configuration)을 참조하세요 | `true` |

191| `allowManagedMcpServersOnly` | (Managed 설정만) Managed 설정의 `allowedMcpServers`만 존중됩니다. `deniedMcpServers`는 여전히 모든 소스에서 병합됩니다. 사용자는 여전히 MCP 서버를 추가할 수 있지만 관리자 정의 허용 목록만 적용됩니다. [Managed MCP 구성](/ko/managed-mcp)을 참조하세요 | `true` |222| `allowManagedMcpServersOnly` | (Managed 설정만) Managed 설정의 `allowedMcpServers`만 존중됩니다. `deniedMcpServers`는 여전히 모든 소스에서 병합됩니다. 사용자는 여전히 MCP 서버를 추가할 수 있지만 관리자 정의 허용 목록만 적용됩니다. [Managed MCP 구성](/ko/managed-mcp)을 참조하세요 | `true` |

192| `allowManagedPermissionRulesOnly` | (Managed 설정만) 사용자 및 프로젝트 설정이 `allow`, `ask` 또는 `deny` 권한 규칙을 정의하는 것을 방지합니다. Managed 설정의 규칙만 적용됩니다. [Managed 전용 설정](/ko/permissions#managed-only-settings)을 참조하세요 | `true` |223| `allowManagedPermissionRulesOnly` | (Managed 설정만) 사용자 및 프로젝트 설정이 `allow`, `ask` 또는 `deny` 권한 규칙을 정의하는 것을 방지합니다. Managed 설정의 규칙만 적용됩니다. [Managed 전용 설정](/ko/permissions#managed-only-settings)을 참조하세요 | `true` |

193| `alwaysThinkingEnabled` | 모든 세션에 대해 기본적으로 [확장 사고](/ko/model-config#extended-thinking)를 활성화합니다. 일반적으로 직접 편집하기보다는 `/config` 명령을 통해 구성됩니다. 사고를 강제로 끄려면 `env`에서 [`CLAUDE_CODE_DISABLE_THINKING`](/ko/env-vars)을 설정합니다 | `true` |224| `alwaysThinkingEnabled` | 모든 세션에 대해 기본적으로 [확장 사고](/ko/model-config#extended-thinking)를 활성화합니다. 일반적으로 직접 편집하기보다는 `/config` 명령을 통해 구성됩니다. 사고를 강제로 끄려면 `env`에서 [`MAX_THINKING_TOKENS=0`](/ko/env-vars)을 설정합니다. 이는 Anthropic API에서 사고를 비활성화합니다. Fable 5는 제외되며, 이는 사고를 끌 수 없습니다. [제3자 공급자](/ko/third-party-integrations)에서 이는 `thinking` 매개변수를 생략하며, 적응형 추론 모델은 여전히 사고할 수 있습니다 | `true` |

194| `apiKeyHelper` | `/bin/sh`에서 실행될 사용자 정의 스크립트로 인증 값을 생성합니다. 이 값은 모델 요청에 대해 `X-Api-Key` 및 `Authorization: Bearer` 헤더로 전송됩니다. [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/ko/env-vars)로 새로고침 간격을 설정합니다 | `/bin/generate_temp_api_key.sh` |225| `apiKeyHelper` | `/bin/sh`에서 실행될 사용자 정의 스크립트로 인증 값을 생성합니다. 이 값은 모델 요청에 대해 `X-Api-Key` 및 `Authorization: Bearer` 헤더로 전송됩니다. [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/ko/env-vars)로 새로고침 간격을 설정합니다 | `/bin/generate_temp_api_key.sh` |

195| `attribution` | git 커밋 및 pull request에 대한 attribution을 사용자 정의합니다. [Attribution 설정](#attribution-settings)을 참조하세요 | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |226| `attribution` | git 커밋 및 pull request에 대한 attribution을 사용자 정의합니다. [Attribution 설정](#attribution-settings)을 참조하세요 | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |

227| `autoCompactEnabled` | {/* min-version: 2.1.119 */}컨텍스트가 한계에 접근할 때 자동으로 대화를 압축합니다. 기본값: `true`. `/config`에 **자동 압축**으로 표시됩니다. 환경 변수로 비활성화하려면 `env`에서 [`DISABLE_AUTO_COMPACT`](/ko/env-vars)를 설정합니다 | `false` |

196| `autoMemoryDirectory` | [자동 메모리](/ko/memory#storage-location) 저장소를 위한 사용자 정의 디렉토리입니다. 절대 경로 또는 `~/` 접두사 경로를 허용합니다. 프로젝트 또는 local 설정에서 이는 작업 공간 신뢰 대화를 수락한 후에만 적용됩니다. 복제된 저장소가 이 파일을 제공할 수 있기 때문입니다 | `"~/my-memory-dir"` |228| `autoMemoryDirectory` | [자동 메모리](/ko/memory#storage-location) 저장소를 위한 사용자 정의 디렉토리입니다. 절대 경로 또는 `~/` 접두사 경로를 허용합니다. 프로젝트 또는 local 설정에서 이는 작업 공간 신뢰 대화를 수락한 후에만 적용됩니다. 복제된 저장소가 이 파일을 제공할 수 있기 때문입니다 | `"~/my-memory-dir"` |

197| `autoMemoryEnabled` | [자동 메모리](/ko/memory#enable-or-disable-auto-memory)를 활성화합니다. `false`일 때 Claude는 자동 메모리 디렉토리에서 읽거나 쓰지 않습니다. 기본값: `true`. 세션 중에 `/memory`로도 전환할 수 있습니다. 환경 변수로 비활성화하려면 `env`에서 [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/ko/env-vars)를 설정합니다 | `false` |229| `autoMemoryEnabled` | [자동 메모리](/ko/memory#enable-or-disable-auto-memory)를 활성화합니다. `false`일 때 Claude는 자동 메모리 디렉토리에서 읽거나 쓰지 않습니다. 기본값: `true`. 세션 중에 `/memory`로도 전환할 수 있습니다. 환경 변수로 비활성화하려면 `env`에서 [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/ko/env-vars)를 설정합니다 | `false` |

198| `autoMode` | [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기가 차단하고 허용하는 것을 사용자 정의합니다. `environment`, `allow`, `soft_deny` 및 `hard_deny` 배열의 산문 규칙을 포함합니다. 배열에 리터럴 문자열 `"$defaults"`를 포함하여 해당 위치에서 기본 제공 규칙을 상속합니다. [자동 모드 구성](/ko/auto-mode-config)을 참조하세요. 공유 프로젝트 설정에서는 읽지 않음 | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |230| `autoMode` | [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기가 차단하고 허용하는 것을 사용자 정의합니다. `environment`, `allow`, `soft_deny` 및 `hard_deny` 배열의 산문 규칙을 포함합니다. 배열에 리터럴 문자열 `"$defaults"`를 포함하여 해당 위치에서 기본 제공 규칙을 상속합니다. [자동 모드 구성](/ko/auto-mode-config)을 참조하세요. 공유 프로젝트 설정에서는 읽지 않음 | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |

199| `autoScrollEnabled` | [fullscreen 렌더링](/ko/fullscreen)에서 새 출력을 대화의 맨 아래로 따릅니다. 기본값: `true`. `/config`에 **자동 스크롤**로 표시됩니다. 이것이 꺼져 있을 때도 권한 프롬프트는 여전히 보기로 스크롤됩니다 | `false` |231| `autoScrollEnabled` | [fullscreen 렌더링](/ko/fullscreen)에서 새 출력을 대화의 맨 아래로 따릅니다. 기본값: `true`. `/config`에 **자동 스크롤**로 표시됩니다. 이것이 꺼져 있을 때도 권한 프롬프트는 여전히 보기로 스크롤됩니다 | `false` |

200| `autoUpdatesChannel` | 업데이트를 따를 릴리스 채널입니다. 일반적으로 약 1주일 된 버전이고 주요 회귀가 있는 버전을 건너뛰는 `"stable"`을 사용하거나 가장 최근 릴리스인 `"latest"` (기본값)을 사용합니다. 자동 업데이트를 완전히 비활성화하려면 `env`에서 [`DISABLE_AUTOUPDATER`](/ko/setup#disable-auto-updates)를 설정합니다 | `"stable"` |232| `autoUpdatesChannel` | 업데이트를 따를 릴리스 채널입니다. 일반적으로 약 1주일 된 버전이고 주요 회귀가 있는 버전을 건너뛰는 `"stable"`을 사용하거나 가장 최근 릴리스인 `"latest"` (기본값)을 사용합니다. 자동 업데이트를 완전히 비활성화하려면 `env`에서 [`DISABLE_AUTOUPDATER`](/ko/setup#disable-auto-updates)를 설정합니다 | `"stable"` |

201| `availableModels` | `/model`, `--model` 또는 `ANTHROPIC_MODEL`을 통해 사용자가 선택할 수 있는 모델을 제한합니다. 기본 옵션에는 영향을 주지 않습니다. [모델 선택 제한](/ko/model-config#restrict-model-selection)을 참조하세요 | `["sonnet", "haiku"]` |233| `availableModels` | 사용자가 메인 세션, [subagents](/ko/sub-agents) [advisor](/ko/advisor)를 위해 선택할 수 있는 모델을 제한합니다. [모델 선택 제한](/ko/model-config#restrict-model-selection)을 참조하세요. `enforceAvailableModels`도 기본값을 제한하려면 참조하세요 | `["sonnet", "haiku"]` |

202| `awaySummaryEnabled` | 몇 분 동안 터미널에서 떨어져 있다가 돌아올 때 한 줄 세션 요약을 표시합니다. 비활성화하려면 `false`로 설정하거나 `/config`에서 세션 요약을 끕니다. [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](/ko/env-vars)와 동일합니다 | `true` |234| `awaySummaryEnabled` | 몇 분 동안 터미널에서 떨어져 있다가 돌아올 때 한 줄 세션 요약을 표시합니다. 비활성화하려면 `false`로 설정하거나 `/config`에서 세션 요약을 끕니다. [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](/ko/env-vars)와 동일합니다 | `true` |

203| `awsAuthRefresh` | `.aws` 디렉토리를 수정하는 사용자 정의 스크립트 ([고급 자격 증명 구성](/ko/amazon-bedrock#advanced-credential-configuration) 참조) | `aws sso login --profile myprofile` |235| `awsAuthRefresh` | `.aws` 디렉토리를 수정하는 사용자 정의 스크립트 ([고급 자격 증명 구성](/ko/amazon-bedrock#advanced-credential-configuration) 참조) | `aws sso login --profile myprofile` |

204| `awsCredentialExport` | AWS 자격 증명이 포함된 JSON을 출력하는 사용자 정의 스크립트 ([고급 자격 증명 구성](/ko/amazon-bedrock#advanced-credential-configuration) 참조) | `/bin/generate_aws_grant.sh` |236| `awsCredentialExport` | AWS 자격 증명이 포함된 JSON을 출력하는 사용자 정의 스크립트 ([고급 자격 증명 구성](/ko/amazon-bedrock#advanced-credential-configuration) 참조) | `/bin/generate_aws_grant.sh` |


213| `disableAgentView` | [배경 에이전트 및 에이전트 보기](/ko/agent-view)를 끄려면 `true`로 설정합니다: `claude agents`, `--bg`, `/background` 및 온디맨드 감독자. 일반적으로 [managed 설정](/ko/permissions#managed-settings)에서 설정됩니다. `CLAUDE_CODE_DISABLE_AGENT_VIEW`를 `1`로 설정하는 것과 동일합니다 | `true` |245| `disableAgentView` | [배경 에이전트 및 에이전트 보기](/ko/agent-view)를 끄려면 `true`로 설정합니다: `claude agents`, `--bg`, `/background` 및 온디맨드 감독자. 일반적으로 [managed 설정](/ko/permissions#managed-settings)에서 설정됩니다. `CLAUDE_CODE_DISABLE_AGENT_VIEW`를 `1`로 설정하는 것과 동일합니다 | `true` |

214| `disableAllHooks` | 모든 [hooks](/ko/hooks) 및 사용자 정의 [상태 줄](/ko/statusline) 비활성화 | `true` |246| `disableAllHooks` | 모든 [hooks](/ko/hooks) 및 사용자 정의 [상태 줄](/ko/statusline) 비활성화 | `true` |

215| `disableAutoMode` | [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)가 활성화되는 것을 방지하려면 `"disable"`로 설정합니다. `Shift+Tab` 순환에서 `auto`를 제거하고 시작 시 `--permission-mode auto`를 거부합니다. [managed 설정](/ko/permissions#managed-settings)에서 사용자가 재정의할 수 없을 때 가장 유용합니다 | `"disable"` |247| `disableAutoMode` | [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)가 활성화되는 것을 방지하려면 `"disable"`로 설정합니다. `Shift+Tab` 순환에서 `auto`를 제거하고 시작 시 `--permission-mode auto`를 거부합니다. [managed 설정](/ko/permissions#managed-settings)에서 사용자가 재정의할 수 없을 때 가장 유용합니다 | `"disable"` |

248| `disableBundledSkills` | [skills](/ko/skills) 및 Claude Code와 함께 제공되는 워크플로우를 비활성화하려면 `true`로 설정합니다: 번들 skills 및 워크플로우는 완전히 제거되고, `/init`과 같은 기본 제공 슬래시 명령은 입력 가능하지만 모델에서 숨겨집니다. 플러그인의 skills, `.claude/skills/` 및 `.claude/commands/`는 영향을 받지 않습니다. `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS`를 `1`로 설정하는 것과 동일합니다 | `true` |

216| `disableDeepLinkRegistration` | Claude Code가 시작 시 운영 체제에 `claude-cli://` 프로토콜 핸들러를 등록하는 것을 방지하려면 `"disable"`로 설정합니다. [Deep links](/ko/deep-links)를 사용하면 외부 도구가 사전 채워진 프롬프트로 Claude Code 세션을 열 수 있습니다. 프로토콜 핸들러 등록이 제한되거나 별도로 관리되는 환경에서 유용합니다 | `"disable"` |249| `disableDeepLinkRegistration` | Claude Code가 시작 시 운영 체제에 `claude-cli://` 프로토콜 핸들러를 등록하는 것을 방지하려면 `"disable"`로 설정합니다. [Deep links](/ko/deep-links)를 사용하면 외부 도구가 사전 채워진 프롬프트로 Claude Code 세션을 열 수 있습니다. 프로토콜 핸들러 등록이 제한되거나 별도로 관리되는 환경에서 유용합니다 | `"disable"` |

217| `disabledMcpjsonServers` | `.mcp.json` 파일에서 거부할 특정 MCP 서버 목록 | `["filesystem"]` |250| `disabledMcpjsonServers` | `.mcp.json` 파일에서 거부할 특정 MCP 서버 목록 | `["filesystem"]` |

218| `disableRemoteControl` | {/* min-version: 2.1.128 */}[Remote Control](/ko/remote-control) 비활성화: `claude remote-control`, `--remote-control` 플래그, 자동 시작 및 세션 내 전환을 차단합니다. 일반적으로 장치별 MDM 적용을 위해 [managed 설정](/ko/permissions#managed-settings)에 배치되지만 모든 범위에서 작동합니다. Claude Code v2.1.128 이상이 필요합니다 | `true` |251| `disableRemoteControl` | {/* min-version: 2.1.128 */}[Remote Control](/ko/remote-control) 비활성화: `claude remote-control`, `--remote-control` 플래그, 자동 시작 및 세션 내 전환을 차단합니다. 일반적으로 장치별 MDM 적용을 위해 [managed 설정](/ko/permissions#managed-settings)에 배치되지만 모든 범위에서 작동합니다. Claude Code v2.1.128 이상이 필요합니다 | `true` |


222| `effortLevel` | [노력 수준](/ko/model-config#adjust-effort-level)을 세션 간에 유지합니다. `"low"`, `"medium"`, `"high"` 또는 `"xhigh"`를 허용합니다. `/effort`를 이러한 값 중 하나로 실행할 때 자동으로 작성됩니다. `--effort` 및 [`CLAUDE_CODE_EFFORT_LEVEL`](/ko/env-vars)은 한 세션에 대해 이를 재정의합니다. [노력 수준 조정](/ko/model-config#adjust-effort-level)에서 지원되는 모델을 참조하세요 | `"xhigh"` |255| `effortLevel` | [노력 수준](/ko/model-config#adjust-effort-level)을 세션 간에 유지합니다. `"low"`, `"medium"`, `"high"` 또는 `"xhigh"`를 허용합니다. `/effort`를 이러한 값 중 하나로 실행할 때 자동으로 작성됩니다. `--effort` 및 [`CLAUDE_CODE_EFFORT_LEVEL`](/ko/env-vars)은 한 세션에 대해 이를 재정의합니다. [노력 수준 조정](/ko/model-config#adjust-effort-level)에서 지원되는 모델을 참조하세요 | `"xhigh"` |

223| `enableAllProjectMcpServers` | 프로젝트 `.mcp.json` 파일에 정의된 모든 MCP 서버를 자동으로 승인합니다 | `true` |256| `enableAllProjectMcpServers` | 프로젝트 `.mcp.json` 파일에 정의된 모든 MCP 서버를 자동으로 승인합니다 | `true` |

224| `enabledMcpjsonServers` | `.mcp.json` 파일에서 승인할 특정 MCP 서버 목록 | `["memory", "github"]` |257| `enabledMcpjsonServers` | `.mcp.json` 파일에서 승인할 특정 MCP 서버 목록 | `["memory", "github"]` |

258| `enforceAvailableModels` | {/* min-version: 2.1.175 */}}`true`이고 `availableModels`가 managed 또는 정책 설정의 비어있지 않은 목록일 때 기본 모델도 허용 목록으로 제한됩니다. [모델 선택 제한](/ko/model-config#restrict-model-selection)을 참조하고 `availableModels`가 여러 수준에서 설정될 때 [병합 동작](/ko/model-config#merge-behavior)을 참조하세요. Claude Code v2.1.175 이상이 필요합니다 | `true` |

225| `env` | 모든 세션에 적용될 환경 변수 및 Claude Code가 생성하는 하위 프로세스에 적용됩니다. {/* min-version: 2.1.143 */}v2.1.143부터 여기에 설정된 `NO_COLOR` 및 `FORCE_COLOR`는 하위 프로세스로 전달되지만 Claude Code 자체 인터페이스 색상은 변경하지 않습니다. Claude를 시작하기 전에 셸에서 이를 설정하여 인터페이스 색상을 변경합니다 | `{"FOO": "bar"}` |259| `env` | 모든 세션에 적용될 환경 변수 및 Claude Code가 생성하는 하위 프로세스에 적용됩니다. {/* min-version: 2.1.143 */}v2.1.143부터 여기에 설정된 `NO_COLOR` 및 `FORCE_COLOR`는 하위 프로세스로 전달되지만 Claude Code 자체 인터페이스 색상은 변경하지 않습니다. Claude를 시작하기 전에 셸에서 이를 설정하여 인터페이스 색상을 변경합니다 | `{"FOO": "bar"}` |

260| `fallbackModel` | 기본 모델이 과부하이거나 사용할 수 없을 때 순서대로 시도할 폴백 모델입니다. Claude Code는 턴의 나머지 부분에 대해 체인의 다음 사용 가능한 모델로 전환하고 알림을 표시합니다. `"default"`는 기본 모델로 확장됩니다. 체인은 3개 모델로 제한되며 추가 항목은 무시됩니다. 대부분의 배열 설정과 달리 이 키는 설정 파일 전체에서 병합되지 않습니다: 이를 정의하는 최고 우선순위 파일이 전체 체인을 제공합니다. [`--fallback-model`](/ko/cli-reference#cli-flags) 플래그는 한 세션에 대해 이를 재정의합니다. [폴백 모델 체인](/ko/model-config#fallback-model-chains)을 참조하세요 | `["claude-sonnet-4-6", "claude-haiku-4-5"]` |

226| `fastModePerSessionOptIn` | `true`일 때 빠른 모드는 세션 간에 지속되지 않습니다. 각 세션은 빠른 모드가 꺼진 상태로 시작되며 사용자가 `/fast`로 활성화해야 합니다. 사용자의 빠른 모드 설정은 여전히 저장됩니다. [세션별 옵트인 필요](/ko/fast-mode#require-per-session-opt-in)를 참조하세요 | `true` |261| `fastModePerSessionOptIn` | `true`일 때 빠른 모드는 세션 간에 지속되지 않습니다. 각 세션은 빠른 모드가 꺼진 상태로 시작되며 사용자가 `/fast`로 활성화해야 합니다. 사용자의 빠른 모드 설정은 여전히 저장됩니다. [세션별 옵트인 필요](/ko/fast-mode#require-per-session-opt-in)를 참조하세요 | `true` |

227| `feedbackSurveyRate` | [세션 품질 설문조사](/ko/data-usage#session-quality-surveys)가 적격일 때 나타날 확률 (0–1). 완전히 억제하려면 `0`으로 설정하거나 `env`에서 [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/ko/env-vars)를 설정합니다. Bedrock, Vertex 또는 Foundry를 사용할 때 유용하며 기본 샘플 레이트가 적용되지 않습니다 | `0.05` |262| `feedbackSurveyRate` | [세션 품질 설문조사](/ko/data-usage#session-quality-surveys)가 적격일 때 나타날 확률 (0–1). 완전히 억제하려면 `0`으로 설정하거나 `env`에서 [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/ko/env-vars)를 설정합니다. Bedrock, Vertex 또는 Foundry를 사용할 때 유용하며 기본 샘플 레이트가 적용되지 않습니다 | `0.05` |

263| `fileCheckpointingEnabled` | {/* min-version: 2.1.119 */}}각 편집 전에 파일을 스냅샷하여 [`/rewind`](/ko/checkpointing)가 이를 복원할 수 있도록 합니다. 기본값: `true`. `/config`에 \*\*코드 되감기 (체크포인트)\*\*로 표시됩니다. 환경 변수로 비활성화하려면 `env`에서 [`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`](/ko/env-vars)를 설정합니다 | `false` |

228| `fileSuggestion` | `@` 파일 자동 완성을 위한 사용자 정의 스크립트를 구성합니다. [파일 제안 설정](#file-suggestion-settings)을 참조하세요 | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |264| `fileSuggestion` | `@` 파일 자동 완성을 위한 사용자 정의 스크립트를 구성합니다. [파일 제안 설정](#file-suggestion-settings)을 참조하세요 | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |

265| `footerLinksRegexes` | {/* min-version: 2.1.176 */}정규식이 턴 출력과 일치할 때 바닥글에 클릭 가능한 배지를 렌더링합니다. 각 항목에는 `pattern`, 명명된 캡처 그룹에서 채워진 `{name}` 자리 표시자가 있는 `url` 템플릿 및 선택적 `label`이 있습니다. 사용자, `--settings` 플래그 및 managed 설정에서만 읽습니다. [바닥글 링크 배지](#footer-link-badges)에서 URL 제약, 스키마 허용 목록 및 제한을 참조하세요. Claude Code v2.1.176 이상이 필요합니다 | `[{"type": "regex", "pattern": "\\b(?<key>PROJ-\\d+)\\b", "url": "https://issues.example.com/browse/{key}", "label": "{key}"}]` |

229| `forceLoginMethod` | `claudeai`를 사용하여 Claude.ai 계정으로만 로그인을 제한하거나, `console`을 사용하여 Claude Console 계정으로만 제한합니다. Managed 설정에서 설정되면 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper`로 인증된 세션은 시작 시 차단됩니다. 어느 값도 먼저 자사 OAuth 없이 만족할 수 없기 때문입니다. Bedrock, Vertex 및 Foundry와 같은 제3자 공급자 세션은 차단되지 않습니다: 이들은 Anthropic이 아닌 클라우드 공급자에 대해 인증합니다 | `claudeai` |266| `forceLoginMethod` | `claudeai`를 사용하여 Claude.ai 계정으로만 로그인을 제한하거나, `console`을 사용하여 Claude Console 계정으로만 제한합니다. Managed 설정에서 설정되면 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper`로 인증된 세션은 시작 시 차단됩니다. 어느 값도 먼저 자사 OAuth 없이 만족할 수 없기 때문입니다. Bedrock, Vertex 및 Foundry와 같은 제3자 공급자 세션은 차단되지 않습니다: 이들은 Anthropic이 아닌 클라우드 공급자에 대해 인증합니다 | `claudeai` |

230| `forceLoginOrgUUID` | 로그인이 특정 Anthropic 조직에 속하도록 요구합니다. 단일 UUID 문자열을 허용하며, 이는 로그인 중에 해당 조직을 사전 선택하거나, 나열된 조직이 사전 선택 없이 허용되는 UUID 배열을 허용합니다. Managed 설정에서 설정되면 인증된 계정이 나열된 조직에 속하지 않으면 로그인이 실패합니다. `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper`로 인증된 세션은 시작 시 차단됩니다. 조직 멤버십을 확인할 수 없기 때문입니다. Bedrock, Vertex 및 Foundry와 같은 제3자 공급자 세션은 차단되지 않습니다: 클라우드 IAM을 사용하여 사용할 수 있는 클라우드 계정을 제한합니다. 빈 배열은 실패하고 잘못된 구성 메시지로 로그인을 차단합니다 | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` 또는 `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |267| `forceLoginOrgUUID` | 로그인이 특정 Anthropic 조직에 속하도록 요구합니다. 단일 UUID 문자열을 허용하며, 이는 로그인 중에 해당 조직을 사전 선택하거나, 나열된 조직이 사전 선택 없이 허용되는 UUID 배열을 허용합니다. Managed 설정에서 설정되면 인증된 계정이 나열된 조직에 속하지 않으면 로그인이 실패합니다. `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper`로 인증된 세션은 시작 시 차단됩니다. 조직 멤버십을 확인할 수 없기 때문입니다. Bedrock, Vertex 및 Foundry와 같은 제3자 공급자 세션은 차단되지 않습니다: 클라우드 IAM을 사용하여 사용할 수 있는 클라우드 계정을 제한합니다. 빈 배열은 실패하고 잘못된 구성 메시지로 로그인을 차단합니다 | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` 또는 `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |

231| `forceRemoteSettingsRefresh` | (Managed 설정만) 원격 managed 설정이 서버에서 새로 가져올 때까지 CLI 시작을 차단합니다. 가져오기가 실패하면 캐시된 또는 설정 없이 계속하는 대신 CLI가 종료됩니다. 설정되지 않으면 시작이 원격 설정을 기다리지 않고 계속됩니다. [실패 폐쇄 적용](/ko/server-managed-settings#enforce-fail-closed-startup)을 참조하세요 | `true` |268| `forceRemoteSettingsRefresh` | (Managed 설정만) 원격 managed 설정이 서버에서 새로 가져올 때까지 CLI 시작을 차단합니다. 가져오기가 실패하면 캐시된 또는 설정 없이 계속하는 대신 CLI가 종료됩니다. 설정되지 않으면 시작이 원격 설정을 기다리지 않고 계속됩니다. [실패 폐쇄 적용](/ko/server-managed-settings#enforce-fail-closed-startup)을 참조하세요 | `true` |


234| `httpHookAllowedEnvVars` | HTTP hooks가 헤더에 보간할 수 있는 환경 변수 이름의 허용 목록입니다. 설정되면 각 hook의 유효한 `allowedEnvVars`는 이 설정과의 교집합입니다. 정의되지 않음 = 제한 없음. 배열은 설정 소스 전체에서 병합됩니다. [Hook 구성](#hook-configuration)을 참조하세요 | `["MY_TOKEN", "HOOK_SECRET"]` |271| `httpHookAllowedEnvVars` | HTTP hooks가 헤더에 보간할 수 있는 환경 변수 이름의 허용 목록입니다. 설정되면 각 hook의 유효한 `allowedEnvVars`는 이 설정과의 교집합입니다. 정의되지 않음 = 제한 없음. 배열은 설정 소스 전체에서 병합됩니다. [Hook 구성](#hook-configuration)을 참조하세요 | `["MY_TOKEN", "HOOK_SECRET"]` |

235| `includeCoAuthoredBy` | **더 이상 사용되지 않음**: 대신 `attribution`을 사용하세요. git 커밋 및 pull request에 `co-authored-by Claude` 바이라인을 포함할지 여부 (기본값: `true`) | `false` |272| `includeCoAuthoredBy` | **더 이상 사용되지 않음**: 대신 `attribution`을 사용하세요. git 커밋 및 pull request에 `co-authored-by Claude` 바이라인을 포함할지 여부 (기본값: `true`) | `false` |

236| `includeGitInstructions` | Claude의 시스템 프롬프트에 기본 제공 커밋 및 PR 워크플로우 지침 및 git 상태 스냅샷을 포함합니다 (기본값: `true`). 예를 들어 자신의 git 워크플로우 skills을 사용할 때 이를 `false`로 설정하여 둘 다 제거합니다. `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` 환경 변수가 설정되면 이 설정보다 우선합니다 | `false` |273| `includeGitInstructions` | Claude의 시스템 프롬프트에 기본 제공 커밋 및 PR 워크플로우 지침 및 git 상태 스냅샷을 포함합니다 (기본값: `true`). 예를 들어 자신의 git 워크플로우 skills을 사용할 때 이를 `false`로 설정하여 둘 다 제거합니다. `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` 환경 변수가 설정되면 이 설정보다 우선합니다 | `false` |

237| `language` | Claude의 선호 응답 언어를 구성합니다 (예: `"japanese"`, `"spanish"`, `"french"`). Claude는 기본적으로 언어로 응답합니다. 또한 [음성 받아쓰기](/ko/voice-dictation#change-the-dictation-language) 언어를 설정합니다 | `"japanese"` |274| `inputNeededNotifEnabled` | {/* min-version: 2.1.119 */}[Remote Control](/ko/remote-control)이 연결되어 있을 때 권한 프롬프트 또는 질문이 입력을 기다리고 있을 때 휴대폰에 푸시 알림을 보냅니다. 기본값: `false`. `/config` **작업이 필요할 푸시**로 표시됩니다. [모바일 푸시 알림](/ko/remote-control#mobile-push-notifications) 참조하세요. Claude Code v2.1.119 이상이 필요합니다 | `true` |

238| `maxSkillDescriptionChars` | {/* min-version: 2.1.105 */}Claude가 턴에 보는 [skill 목록](/ko/skills#skill-descriptions-are-cut-short)의 결합된 `description` `when_to_use` 텍스트에 대한 skill별 문자 제한 (기본값: `1536`). 길이보다 텍스트는 잘립니다. 더 긴 설명을 유지하려면 높이고 턴당 더 많은 컨텍스트를 사용합니다. [`skillListingBudgetFraction`](#available-settings) 맞추려면 낮춥니다. `/doctor`는 현재 잘림 수와 영향을 받는 skills를 표시합니다. Claude Code v2.1.105 이상이 필요합니다 | `2048` |275| `language` | Claude의 선호 응답 언어를 구성합니다 (예: `"japanese"`, `"spanish"`, `"french"`). Claude는 기본적으로 언어로 응답합니다. 또한 [음성 받아쓰기](/ko/voice-dictation#change-the-dictation-language) 언어를 설정합니다. {/* min-version: 2.1.176 */}v2.1.176부터 설정되지 않으면 세션 제목이 대화의 언어와 일치합니다 | `"japanese"` |

239| `minimumVersion` | 배경 자동 업데이트 및 `claude update`가 버전 아래로 설치되는 것을 방지하는 하한입니다. `"latest"` 채널에서 `"stable"` 전환할 `/config` 통해 현재 버전에 머물기 또는 다운그레이드를 허용하라는 메시지가 표시됩니다. 머물기를 선택하면 값이 설정됩니다. 또한 [managed 설정](/ko/permissions#managed-settings)에서 조직 전체 최소값을 고정하는 유용합니다 | `"2.1.100"` |276| `maxSkillDescriptionChars` | {/* min-version: 2.1.105 */}Claude가 턴에 보는 [skill 목록](/ko/skills#skill-descriptions-are-cut-short)의 결합된 `description` `when_to_use` 텍스트에 대한 skill별 문자 제한 (기본값: `1536`). 길이보다 텍스트는 잘립니다. 설명을 유지하려면 높이고 턴당 많은 컨텍스트를 사용합니다. [`skillListingBudgetFraction`](#available-settings) 맞추려면 낮춥니다. Claude Code v2.1.105 이상이 필요합니다 | `2048` |

277| `minimumVersion` | 배경 자동 업데이트 및 `claude update`가 이 버전 아래로 설치되는 것을 방지하는 하한입니다. `"latest"` 채널에서 `"stable"`로 전환할 때 `/config`를 통해 현재 버전에 머물기 또는 다운그레이드를 허용하라는 메시지가 표시됩니다. 머물기를 선택하면 이 값이 설정됩니다. 또한 [managed 설정](/ko/permissions#managed-settings)에서 조직 전체 최소값을 고정하는 데 유용합니다. 시작을 완전히 차단하는 하드 플로어는 `requiredMinimumVersion`을 참조하세요 | `"2.1.100"` |

240| `model` | Claude Code에 사용할 기본 모델을 재정의합니다. `--model` 및 [`ANTHROPIC_MODEL`](/ko/model-config#environment-variables)은 한 세션에 대해 이를 재정의합니다 | `"claude-sonnet-4-6"` |278| `model` | Claude Code에 사용할 기본 모델을 재정의합니다. `--model` 및 [`ANTHROPIC_MODEL`](/ko/model-config#environment-variables)은 한 세션에 대해 이를 재정의합니다 | `"claude-sonnet-4-6"` |

241| `modelOverrides` | Anthropic 모델 ID를 Bedrock 추론 프로필 ARN과 같은 공급자 특정 모델 ID로 매핑합니다. 각 모델 선택기 항목은 공급자 API를 호출할 때 매핑된 값을 사용합니다. [버전별 모델 ID 재정의](/ko/model-config#override-model-ids-per-version)를 참조하세요 | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |279| `modelOverrides` | Anthropic 모델 ID를 Bedrock 추론 프로필 ARN과 같은 공급자 특정 모델 ID로 매핑합니다. 각 모델 선택기 항목은 공급자 API를 호출할 때 매핑된 값을 사용합니다. [버전별 모델 ID 재정의](/ko/model-config#override-model-ids-per-version)를 참조하세요 | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |

242| `otelHeadersHelper` | 동적 OpenTelemetry 헤더를 생성하는 스크립트입니다. 시작 시 및 주기적으로 실행됩니다. [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/ko/env-vars)로 새로고침 간격을 설정합니다. [동적 헤더](/ko/monitoring-usage#dynamic-headers)를 참조하세요 | `/bin/generate_otel_headers.sh` |280| `otelHeadersHelper` | 동적 OpenTelemetry 헤더를 생성하는 스크립트입니다. 시작 시 및 주기적으로 실행됩니다. [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/ko/env-vars)로 새로고침 간격을 설정합니다. [동적 헤더](/ko/monitoring-usage#dynamic-headers)를 참조하세요 | `/bin/generate_otel_headers.sh` |


244| `parentSettingsBehavior` | {/* min-version: 2.1.133 */}(Managed 설정만) Agent SDK 또는 IDE 확장과 같은 embedding host 프로세스에 의해 프로그래밍 방식으로 제공되는 managed 설정이 관리자 배포 managed 계층도 있을 때 적용되는지 여부를 제어합니다. `"first-wins"`: 부모 제공 설정이 삭제되고 관리자 계층만 적용됩니다. `"merge"`: 부모 제공 설정이 관리자 계층 아래에 적용되며, 정책을 강화할 수 있지만 완화할 수 없도록 필터링됩니다. 관리자 계층이 배포되지 않으면 영향을 주지 않습니다. 기본값: `"first-wins"`. Claude Code v2.1.133 이상이 필요합니다 | `"merge"` |282| `parentSettingsBehavior` | {/* min-version: 2.1.133 */}(Managed 설정만) Agent SDK 또는 IDE 확장과 같은 embedding host 프로세스에 의해 프로그래밍 방식으로 제공되는 managed 설정이 관리자 배포 managed 계층도 있을 때 적용되는지 여부를 제어합니다. `"first-wins"`: 부모 제공 설정이 삭제되고 관리자 계층만 적용됩니다. `"merge"`: 부모 제공 설정이 관리자 계층 아래에 적용되며, 정책을 강화할 수 있지만 완화할 수 없도록 필터링됩니다. 관리자 계층이 배포되지 않으면 영향을 주지 않습니다. 기본값: `"first-wins"`. Claude Code v2.1.133 이상이 필요합니다 | `"merge"` |

245| `permissions` | 권한의 구조는 아래 표를 참조하세요. | |283| `permissions` | 권한의 구조는 아래 표를 참조하세요. | |

246| `plansDirectory` | 계획 파일이 저장되는 위치를 사용자 정의합니다. 경로는 프로젝트 루트에 상대적입니다. 기본값: `~/.claude/plans` | `"./plans"` |284| `plansDirectory` | 계획 파일이 저장되는 위치를 사용자 정의합니다. 경로는 프로젝트 루트에 상대적입니다. 기본값: `~/.claude/plans` | `"./plans"` |

247| `pluginSuggestionMarketplaces` | (Managed 설정만) 공식 마켓플레이스 외에도 플러그인이 상황별 설치 제안으로 나타날 수 있는 마켓플레이스 이름입니다. 제안은 각 플러그인의 마켓플레이스 항목의 `relevance` 선언에서 나옵니다. 이름은 마켓플레이스가 머신에 등록되고 등록된 소스가 managed 설정에서도 선언될 때만 적용됩니다. 해당 이름에 대한 `extraKnownMarketplaces` 항목으로 또는 `strictKnownMarketplaces`의 항목으로 선언됩니다. 허용 목록 이름 아래에 다른 소스에서 등록된 마켓플레이스는 무시됩니다. | `["acme-corp-plugins"]` |285| `pluginSuggestionMarketplaces` | (Managed 설정만) 플러그인이 상황별 설치 제안으로 나타날 수 있는 마켓플레이스 이름입니다. 제안은 각 플러그인의 마켓플레이스 항목의 `relevance` 선언에서 나옵니다. 이름은 마켓플레이스가 머신에 등록되고 등록된 소스가 managed 설정에서도 선언될 때만 적용됩니다. 해당 이름에 대한 `extraKnownMarketplaces` 항목으로 또는 `strictKnownMarketplaces`의 항목으로 선언됩니다. 허용 목록 이름 아래에 다른 소스에서 등록된 마켓플레이스는 무시됩니다. 공식 마켓플레이스는 소스 요구 사항에서 제외됩니다: 이름만 허용 목록에 있으면 충분합니다. 이름은 공식 Anthropic 소스에서만 등록될 수 있기 때문입니다. | `["acme-corp-plugins"]` |

248| `pluginTrustMessage` | (Managed 설정만) 설치 전에 표시되는 플러그인 신뢰 경고에 추가될 사용자 정의 메시지입니다. 이를 사용하여 조직 특정 컨텍스트를 추가합니다. 예를 들어 내부 마켓플레이스의 플러그인이 검증되었음을 확인합니다. | `"All plugins from our marketplace are approved by IT"` |286| `pluginTrustMessage` | (Managed 설정만) 설치 전에 표시되는 플러그인 신뢰 경고에 추가될 사용자 정의 메시지입니다. 이를 사용하여 조직 특정 컨텍스트를 추가합니다. 예를 들어 내부 마켓플레이스의 플러그인이 검증되었음을 확인합니다. | `"All plugins from our marketplace are approved by IT"` |

249| `policyHelper` | {/* min-version: 2.1.136 */}관리자 배포 실행 파일로 시작 시 managed 설정을 동적으로 계산합니다. MDM 또는 시스템 `managed-settings.json` 파일에서만 적용됩니다. [정책 도우미로 managed 설정 계산](#compute-managed-settings-with-a-policy-helper)을 참조하세요. Claude Code v2.1.136 이상이 필요합니다 | `{"path": "/usr/local/bin/claude-policy"}` |287| `policyHelper` | {/* min-version: 2.1.136 */}관리자 배포 실행 파일로 시작 시 managed 설정을 동적으로 계산합니다. MDM 또는 시스템 `managed-settings.json` 파일에서만 적용됩니다. [정책 도우미로 managed 설정 계산](#compute-managed-settings-with-a-policy-helper)을 참조하세요. Claude Code v2.1.136 이상이 필요합니다 | `{"path": "/usr/local/bin/claude-policy"}` |

250| `preferredNotifChannel` | 작업 완료 및 권한 프롬프트 알림 방법: `"auto"`, `"terminal_bell"`, `"iterm2"`, `"iterm2_with_bell"`, `"kitty"`, `"ghostty"` 또는 `"notifications_disabled"`. 기본값: `"auto"`로, iTerm2, Ghostty 및 Kitty에서 데스크톱 알림을 보내고 다른 터미널에서는 아무것도 하지 않습니다. 모든 터미널에서 벨 문자를 울리려면 `"terminal_bell"`을 설정합니다. `/config`에 **알림**으로 표시됩니다. [터미널 벨 또는 알림 받기](/ko/terminal-config#get-a-terminal-bell-or-notification)를 참조하세요 | `"terminal_bell"` |288| `preferredNotifChannel` | 작업 완료 및 권한 프롬프트 알림 방법: `"auto"`, `"terminal_bell"`, `"iterm2"`, `"iterm2_with_bell"`, `"kitty"`, `"ghostty"` 또는 `"notifications_disabled"`. 기본값: `"auto"`로, iTerm2, Ghostty 및 Kitty에서 데스크톱 알림을 보내고 다른 터미널에서는 아무것도 하지 않습니다. 모든 터미널에서 벨 문자를 울리려면 `"terminal_bell"`을 설정합니다. `/config`에 **알림**으로 표시됩니다. [터미널 벨 또는 알림 받기](/ko/terminal-config#get-a-terminal-bell-or-notification)를 참조하세요 | `"terminal_bell"` |

251| `prefersReducedMotion` | 접근성을 위해 UI 애니메이션 (스피너, shimmer, flash 효과) 감소 또는 비활성화 | `true` |289| `prefersReducedMotion` | 접근성을 위해 UI 애니메이션 (스피너, shimmer, flash 효과) 감소 또는 비활성화 | `true` |

252| `prUrlTemplate` | PR 배지에 대한 URL 템플릿으로 바닥글 및 도구 결과 요약에 표시됩니다. `gh`에서 보고한 PR URL에서 `{host}`, `{owner}`, `{repo}`, `{number}` 및 `{url}`을 대체합니다. `github.com` 대신 내부 코드 검토 도구를 가리키도록 사용합니다. Claude의 산문에서 `#123` 자동 링크에는 영향을 주지 않습니다 | `"https://reviews.example.com/{owner}/{repo}/pull/{number}"` |290| `prUrlTemplate` | PR 배지에 대한 URL 템플릿으로 바닥글 및 도구 결과 요약에 표시됩니다. `gh`에서 보고한 PR URL에서 `{host}`, `{owner}`, `{repo}`, `{number}` 및 `{url}`을 대체합니다. `github.com` 대신 내부 코드 검토 도구를 가리키도록 사용합니다. Claude의 산문에서 `#123` 자동 링크에는 영향을 주지 않습니다 | `"https://reviews.example.com/{owner}/{repo}/pull/{number}"` |

291| `requiredMaximumVersion` | Managed 설정만. 시작할 수 있는 최대 Claude Code 버전입니다. 실행 중인 버전이 더 최신이면 Claude Code는 시작 시 종료되고 사용자에게 조직의 승인된 방법을 통해 승인된 버전을 설치하도록 지시합니다. `claude install <version>`도 작동할 수 있습니다. 배경 자동 업데이트 및 `claude update`는 천장 위의 버전을 건너뜁니다. 범위 내 설치는 범위 내로 유지됩니다. `claude update`, `claude install` 및 `claude doctor`는 사용자가 복구할 수 있도록 천장 위에서 계속 작동합니다. 이 설정보다 먼저 나온 버전은 무시합니다 | `"2.1.150"` |

292| `requiredMinimumVersion` | Managed 설정만. 시작하는 데 필요한 최소 Claude Code 버전입니다. 실행 중인 버전이 더 오래되면 Claude Code는 시작 시 종료되고 사용자에게 조직의 승인된 방법을 통해 업데이트하도록 지시합니다. `claude update`, `claude install` 및 `claude doctor`는 사용자가 복구할 수 있도록 바닥 아래에서 계속 작동합니다. 시작을 차단하지 않지만 다운그레이드를 방지하는 `minimumVersion`과 다릅니다. 이 설정보다 먼저 나온 버전은 무시합니다 | `"2.1.150"` |

253| `respectGitignore` | `@` 파일 선택기가 `.gitignore` 패턴을 존중할지 여부를 제어합니다. `true` (기본값)일 때 `.gitignore` 패턴과 일치하는 파일은 제안에서 제외됩니다 | `false` |293| `respectGitignore` | `@` 파일 선택기가 `.gitignore` 패턴을 존중할지 여부를 제어합니다. `true` (기본값)일 때 `.gitignore` 패턴과 일치하는 파일은 제안에서 제외됩니다 | `false` |

254| `showClearContextOnPlanAccept` | 계획 수락 화면에서 "컨텍스트 지우기" 옵션을 표시합니다. 기본값: `false`. 옵션을 복원하려면 `true`로 설정합니다 | `true` |294| `showClearContextOnPlanAccept` | 계획 수락 화면에서 "컨텍스트 지우기" 옵션을 표시합니다. 기본값: `false`. 옵션을 복원하려면 `true`로 설정합니다 | `true` |

255| `showThinkingSummaries` | 대화형 세션에서 [확장 사고](/ko/model-config#extended-thinking) 요약을 표시합니다. 설정되지 않거나 `false` (대화형 모드의 기본값)일 때 사고 블록은 API에 의해 편집되고 축소된 스텁으로 표시됩니다. 편집은 표시되는 내용만 변경하고 모델이 생성하는 내용은 변경하지 않습니다. 사고 지출을 줄이려면 [예산을 낮추거나 사고를 비활성화](/ko/model-config#extended-thinking)하세요. 비대화형 모드 (`-p`), Agent SDK 또는 VS Code와 같은 IDE 확장에서는 이 설정과 관계없이 항상 요약을 받습니다 | `true` |295| `showThinkingSummaries` | 대화형 세션에서 [확장 사고](/ko/model-config#extended-thinking) 요약을 표시합니다. 설정되지 않거나 `false` (대화형 모드의 기본값)일 때 사고 블록은 API에 의해 편집되고 축소된 스텁으로 표시됩니다. 편집은 표시되는 내용만 변경하고 모델이 생성하는 내용은 변경하지 않습니다. 사고 지출을 줄이려면 [예산을 낮추거나 사고를 비활성화](/ko/model-config#extended-thinking)하세요. 이 설정은 비대화형 모드 (`-p`), Agent SDK 또는 VS Code와 같은 IDE 확장에서는 영향을 주지 않습니다 | `true` |

256| `showTurnDuration` | 응답 후 턴 지속 시간 메시지를 표시합니다 (예: "Cooked for 1m 6s"). 기본값: `true`. `/config`에 **턴 지속 시간 표시**로 표시됩니다 | `false` |296| `showTurnDuration` | 응답 후 턴 지속 시간 메시지를 표시합니다 (예: "Cooked for 1m 6s"). 기본값: `true`. `/config`에 **턴 지속 시간 표시**로 표시됩니다 | `false` |

257| `skillListingBudgetFraction` | {/* min-version: 2.1.105 */}Claude가 각 턴에 보는 [skill 목록](/ko/skills#skill-descriptions-are-cut-short)을 위해 예약된 모델의 컨텍스트 윈도우의 분수 (기본값: `0.01` = 1%). 목록이 예산을 초과하면 가장 적게 사용되는 skills의 설명이 베어 이름으로 축소되어 Claude가 여전히 호출할 수 있지만 이유를 보지 못합니다. 더 많은 설명을 보이려면 높이고 턴당 더 많은 컨텍스트를 사용합니다. 더 많은 skills을 [`maxSkillDescriptionChars`](#available-settings) 아래에 맞추려면 낮춥니다. `/doctor`는 현재 잘림 수와 영향을 받는 skills를 표시합니다. Claude Code v2.1.105 이상이 필요합니다 | `0.02` |297| `skillListingBudgetFraction` | {/* min-version: 2.1.105 */}Claude가 각 턴에 보는 [skill 목록](/ko/skills#skill-descriptions-are-cut-short)을 위해 예약된 모델의 컨텍스트 윈도우의 분수 (기본값: `0.01` = 1%). 목록이 예산을 초과하면 가장 적게 사용되는 skills의 설명이 베어 이름으로 축소되어 Claude가 여전히 호출할 수 있지만 이유를 보지 못합니다. 더 많은 설명을 보이려면 높이고 턴당 더 많은 컨텍스트를 사용합니다. 더 많은 skills을 [`maxSkillDescriptionChars`](#available-settings) 아래에 맞추려면 낮춥니다. `/doctor`는 현재 잘림 수와 영향을 받는 skills를 표시합니다. Claude Code v2.1.105 이상이 필요합니다 | `0.02` |

258| `skillOverrides` | {/* min-version: 2.1.129 */}skill 이름으로 키가 지정된 skill별 가시성 재정의입니다. 값은 `"on"`, `"name-only"`, `"user-invocable-only"` 또는 `"off"`입니다. SKILL.md를 편집하지 않고 skill을 숨기거나 축소할 수 있습니다. 플러그인 skills에는 적용되지 않으며, 이는 `/plugin`을 통해 관리됩니다. `/skills` 메뉴는 이를 `.claude/settings.local.json`에 작성합니다. [설정에서 skill 가시성 재정의](/ko/skills#override-skill-visibility-from-settings)를 참조하세요. Claude Code v2.1.129 이상이 필요합니다 | `{"legacy-context": "name-only", "deploy": "off"}` |298| `skillOverrides` | {/* min-version: 2.1.129 */}skill 이름으로 키가 지정된 skill별 가시성 재정의입니다. 값은 `"on"`, `"name-only"`, `"user-invocable-only"` 또는 `"off"`입니다. SKILL.md를 편집하지 않고 skill을 숨기거나 축소할 수 있습니다. 플러그인 skills에는 적용되지 않으며, 이는 `/plugin`을 통해 관리됩니다. `/skills` 메뉴는 이를 `.claude/settings.local.json`에 작성합니다. [설정에서 skill 가시성 재정의](/ko/skills#override-skill-visibility-from-settings)를 참조하세요. Claude Code v2.1.129 이상이 필요합니다 | `{"legacy-context": "name-only", "deploy": "off"}` |


265| `strictKnownMarketplaces` | (Managed 설정만) 플러그인 마켓플레이스 소스의 허용 목록입니다. 정의되지 않음 = 제한 없음, 빈 배열 = 잠금. 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로고침 및 자동 업데이트에 적용되므로 정책이 설정되기 전에 추가된 마켓플레이스는 플러그인을 가져오는 데 사용할 수 없습니다. [Managed 마켓플레이스 제한](/ko/plugin-marketplaces#managed-marketplace-restrictions)을 참조하세요 | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |305| `strictKnownMarketplaces` | (Managed 설정만) 플러그인 마켓플레이스 소스의 허용 목록입니다. 정의되지 않음 = 제한 없음, 빈 배열 = 잠금. 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로고침 및 자동 업데이트에 적용되므로 정책이 설정되기 전에 추가된 마켓플레이스는 플러그인을 가져오는 데 사용할 수 없습니다. [Managed 마켓플레이스 제한](/ko/plugin-marketplaces#managed-marketplace-restrictions)을 참조하세요 | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |

266| `strictPluginOnlyCustomization` | (Managed 설정만) 플러그인 또는 managed 설정에서만 올 수 있도록 사용자 및 프로젝트 소스에서 skills, agents, hooks 및 MCP 서버를 차단합니다. `true`는 네 가지 모두를 잠그고, 배열은 명명된 것만 잠급니다. [`strictPluginOnlyCustomization`](#strictpluginonlycustomization)을 참조하세요 | `["skills", "hooks"]` |306| `strictPluginOnlyCustomization` | (Managed 설정만) 플러그인 또는 managed 설정에서만 올 수 있도록 사용자 및 프로젝트 소스에서 skills, agents, hooks 및 MCP 서버를 차단합니다. `true`는 네 가지 모두를 잠그고, 배열은 명명된 것만 잠급니다. [`strictPluginOnlyCustomization`](#strictpluginonlycustomization)을 참조하세요 | `["skills", "hooks"]` |

267| `syntaxHighlightingDisabled` | diffs, 코드 블록 및 파일 미리보기에서 구문 강조 비활성화 | `true` |307| `syntaxHighlightingDisabled` | diffs, 코드 블록 및 파일 미리보기에서 구문 강조 비활성화 | `true` |

268| `teammateMode` | [에이전트 팀](/ko/agent-teams) 팀원이 표시되는 방식: `auto` (tmux 또는 iTerm2에서 분할 창 선택, 그 외에는 in-process), `in-process` 또는 `tmux`. `--teammate-mode`은 한 세션에 대해 이를 재정의합니다. [디스플레이 모드 선택](/ko/agent-teams#choose-a-display-mode)을 참조하세요 | `"in-process"` |308| `teammateMode` | [에이전트 팀](/ko/agent-teams) 팀원이 표시되는 방식: `auto` (tmux 또는 iTerm2에서 분할 창 선택, 그 외에는 in-process), `in-process` 또는 `tmux` (tmux 또는 iTerm2를 사용하여 분할 창 선택, 터미널에서 감지됨). `--teammate-mode`은 한 세션에 대해 이를 재정의합니다. [디스플레이 모드 선택](/ko/agent-teams#choose-a-display-mode)을 참조하세요 | `"in-process"` |

269| `terminalProgressBarEnabled` | 지원되는 터미널에서 터미널 진행률 표시줄을 표시합니다: ConEmu, Ghostty 1.2.0+ 및 iTerm2 3.6.6+. 기본값: `true`. `/config`에 **터미널 진행률 표시줄**로 표시됩니다 | `false` |309| `terminalProgressBarEnabled` | 지원되는 터미널에서 터미널 진행률 표시줄을 표시합니다: ConEmu, Ghostty 1.2.0+ 및 iTerm2 3.6.6+. 기본값: `true`. `/config`에 **터미널 진행률 표시줄**로 표시됩니다 | `false` |

270| `tui` | 터미널 UI 렌더러입니다. 깜박임 없는 [alt-screen 렌더러](/ko/fullscreen)가 있는 가상화된 스크롤백을 위해 `"fullscreen"` 사용합니다. 클래식 메인 화면 렌더러를 위해 `"default"` 사용합니다. `/tui` 통해 설정합니다. [`CLAUDE_CODE_NO_FLICKER`](/ko/env-vars) 환경 변수도 설정할 있습니다 | `"fullscreen"` |310| `theme` | {/* min-version: 2.1.119 */}인터페이스의 색상 테마: `"auto"`, `"dark"`, `"light"`, `"dark-daltonized"`, `"light-daltonized"`, `"dark-ansi"`, `"light-ansi"` 또는 `"custom:<slug>"` 또는 `"custom:<plugin-name>:<slug>"` 같은 사용자 정의 테마 참조. 기본값: `"dark"`. [사용자 정의 테마 만들기](/ko/terminal-config#create-a-custom-theme) 참조하세요. `/config`에 **테마**로 표시됩니다 | `"dark"` |

311| `tui` | 터미널 UI 렌더러입니다. 깜박임 없는 [alt-screen 렌더러](/ko/fullscreen)가 있는 가상화된 스크롤백을 위해 `"fullscreen"`을 사용합니다. 클래식 메인 화면 렌더러를 위해 `"default"`를 사용합니다. `/tui`를 통해 설정합니다. [`CLAUDE_CODE_NO_FLICKER`](/ko/env-vars) 환경 변수도 설정할 수 있습니다. [에이전트 보기](/ko/agent-view)에서 열린 배경 세션은 이 설정과 관계없이 항상 fullscreen 렌더러를 사용합니다 | `"fullscreen"` |

271| `ultracode` | 세션에 대해 [ultracode](/ko/workflows#let-claude-decide-with-ultracode)를 켭니다. 세션 전용이며 `settings.json`에서 읽지 않습니다. `/effort ultracode`, `--settings` 또는 Agent SDK 제어 요청을 통해 설정합니다 | `true` |312| `ultracode` | 세션에 대해 [ultracode](/ko/workflows#let-claude-decide-with-ultracode)를 켭니다. 세션 전용이며 `settings.json`에서 읽지 않습니다. `/effort ultracode`, `--settings` 또는 Agent SDK 제어 요청을 통해 설정합니다 | `true` |

272| `useAutoModeDuringPlan` | 자동 모드를 사용할 수 있을 때 계획 모드가 자동 모드 의미론을 사용할지 여부입니다. 기본값: `true`. 공유 프로젝트 설정에서는 읽지 않음. `/config`에 "계획 중 자동 모드 사용"으로 표시됨 | `false` |313| `useAutoModeDuringPlan` | 자동 모드를 사용할 수 있을 때 계획 모드가 자동 모드 의미론을 사용할지 여부입니다. 기본값: `true`. 공유 프로젝트 설정에서는 읽지 않음. `/config`에 "계획 중 자동 모드 사용"으로 표시됨 | `false` |

314| `verbose` | {/* min-version: 2.1.119 */}잘린 요약 대신 전체 도구 출력을 표시합니다. 기본값: `false`. `/config`에 **상세 출력**으로 표시됩니다. `--verbose` 플래그는 한 세션에 대해 이를 재정의합니다 | `true` |

273| `viewMode` | 시작 시 기본 트랜스크립트 보기 모드: `"default"`, `"verbose"` 또는 `"focus"`. 설정되면 sticky `/focus` 선택을 재정의합니다. `--verbose` 플래그는 한 세션에 대해 이를 재정의합니다 | `"verbose"` |315| `viewMode` | 시작 시 기본 트랜스크립트 보기 모드: `"default"`, `"verbose"` 또는 `"focus"`. 설정되면 sticky `/focus` 선택을 재정의합니다. `--verbose` 플래그는 한 세션에 대해 이를 재정의합니다 | `"verbose"` |

274| `voice` | [음성 받아쓰기](/ko/voice-dictation) 설정: `enabled`는 받아쓰기를 켜고, `mode`는 `"hold"` 또는 `"tap"`을 선택하고, `autoSubmit`은 hold 모드에서 키 릴리스 시 프롬프트를 전송합니다. `/voice`를 실행할 때 자동으로 작성됩니다. Claude.ai 계정이 필요합니다 | `{ "enabled": true, "mode": "tap" }` |316| `voice` | [음성 받아쓰기](/ko/voice-dictation) 설정: `enabled`는 받아쓰기를 켜고, `mode`는 `"hold"` 또는 `"tap"`을 선택하고, `autoSubmit`은 hold 모드에서 키 릴리스 시 프롬프트를 전송합니다. `/voice`를 실행할 때 자동으로 작성됩니다. Claude.ai 계정이 필요합니다 | `{ "enabled": true, "mode": "tap" }` |

275| `voiceEnabled` | `voice.enabled`에 대한 레거시 별칭입니다. `voice` 객체를 선호합니다 | `true` |317| `voiceEnabled` | `voice.enabled`에 대한 레거시 별칭입니다. `voice` 객체를 선호합니다 | `true` |

318| `wheelScrollAccelerationEnabled` | {/* min-version: 2.1.174 */}[fullscreen 렌더링](/ko/fullscreen#mouse-wheel-scrolling)에서 빠른 스크롤 중에 마우스 휠 스크롤 속도를 가속화합니다. 기본값: `true`. 휠 노치당 일정한 스크롤 속도를 원하면 `false`로 설정합니다. Claude Code v2.1.174 이상이 필요합니다 | `false` |

276| `workflowKeywordTriggerEnabled` | {/* min-version: 2.1.157 */}프롬프트의 단어 `ultracode`이 [동적 워크플로우](/ko/workflows#ask-for-a-workflow-in-your-prompt)를 트리거할지 여부입니다. 하나를 트리거하지 않고 단어를 입력하려면 `false`로 설정합니다. `ultracode` 노력 설정, `/workflows` 및 저장된 워크플로우 명령은 영향을 받지 않습니다. 기본값: `true`. `/config`에 **Ultracode 키워드 트리거**로 표시됩니다. v2.1.157에서 추가됨; v2.1.160 이전에 트리거 키워드는 `workflow`였습니다 | `false` |319| `workflowKeywordTriggerEnabled` | {/* min-version: 2.1.157 */}프롬프트의 단어 `ultracode`이 [동적 워크플로우](/ko/workflows#ask-for-a-workflow-in-your-prompt)를 트리거할지 여부입니다. 하나를 트리거하지 않고 단어를 입력하려면 `false`로 설정합니다. `ultracode` 노력 설정, `/workflows` 및 저장된 워크플로우 명령은 영향을 받지 않습니다. 기본값: `true`. `/config`에 **Ultracode 키워드 트리거**로 표시됩니다. v2.1.157에서 추가됨; v2.1.160 이전에 트리거 키워드는 `workflow`였습니다 | `false` |

277| `wslInheritsWindowsSettings` | (Windows managed 설정만) `true`일 때 WSL의 Claude Code는 `/etc/claude-code`에 추가하여 Windows 정책 체인에서 managed 설정을 읽으며 Windows 소스가 우선합니다. Windows 관리자가 작성해야 하는 HKLM 레지스트리 키 또는 `C:\Program Files\ClaudeCode\managed-settings.json`에서 설정된 경우에만 적용됩니다. HKCU 정책도 WSL에 적용되려면 플래그를 HKCU 자체에도 설정해야 합니다. 기본 Windows에는 영향을 주지 않습니다 | `true` |320| `wslInheritsWindowsSettings` | (Windows managed 설정만) `true`일 때 WSL의 Claude Code는 `/etc/claude-code`에 추가하여 Windows 정책 체인에서 managed 설정을 읽으며 Windows 소스가 우선합니다. Windows 관리자가 작성해야 하는 HKLM 레지스트리 키 또는 `C:\Program Files\ClaudeCode\managed-settings.json`에서 설정된 경우에만 적용됩니다. HKCU 정책도 WSL에 적용되려면 플래그를 HKCU 자체에도 설정해야 합니다. 기본 Windows에는 영향을 주지 않습니다 | `true` |

278 321 


283이러한 설정은 `settings.json`이 아닌 `~/.claude.json`에 저장됩니다. 이들을 `settings.json`에 추가하면 스키마 검증 오류가 발생합니다.326이러한 설정은 `settings.json`이 아닌 `~/.claude.json`에 저장됩니다. 이들을 `settings.json`에 추가하면 스키마 검증 오류가 발생합니다.

284 327 

285<Note>328<Note>

286 v2.1.119 이전 버전은 `autoScrollEnabled`, `editorMode`, `showTurnDuration`, `teammateMode` 및 `terminalProgressBarEnabled` `settings.json` 대신 여기에 저장합니다.329 v2.1.119 이전 버전은 `theme`, `verbose`, `editorMode`, `autoCompactEnabled` 및 `preferredNotifChannel` 포함한 여러 `/config` 설정 키를 `settings.json` 대신 여기에 저장합니다.

287</Note>330</Note>

288 331 

289| 키 | 설명 | 예제 |332| 키 | 설명 | 예제 |


314 357 

315| 키 | 설명 | 예제 |358| 키 | 설명 | 예제 |

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

317| `allow` | 도구 사용을 허용하는 권한 규칙 배열입니다. 패턴 매칭 세부 사항은 아래 [권한 규칙 구문](#permission-rule-syntax)을 참조하세요 | `[ "Bash(git diff *)" ]` |360| `allow` | 도구 사용을 허용하는 권한 규칙 배열입니다. 도구 이름 globs는 `mcp__<server>__get_*`과 같이 리터럴 `mcp__<server>__` 접두사 뒤의 도구 위치에서만 지원됩니다. 서버 세그먼트는 glob 없어야 합니다. 패턴 매칭 세부 사항은 아래 [권한 규칙 구문](#permission-rule-syntax)을 참조하세요 | `[ "Bash(git diff *)" ]` |

318| `ask` | 도구 사용 시 확인을 요청하는 권한 규칙 배열입니다. 패턴 매칭 세부 사항은 아래 [권한 규칙 구문](#permission-rule-syntax)을 참조하세요 | `[ "Bash(git push *)" ]` |361| `ask` | 도구 사용 시 확인을 요청하는 권한 규칙 배열입니다. 패턴 매칭 세부 사항은 아래 [권한 규칙 구문](#permission-rule-syntax)을 참조하세요 | `[ "Bash(git push *)" ]` |

319| `deny` | 도구 사용을 거부하는 권한 규칙 배열입니다. 이를 사용하여 Claude Code 액세스에서 민감한 파일을 제외합니다. [권한 규칙 구문](#permission-rule-syntax) 및 [Bash 권한 제한](/ko/permissions#tool-specific-permission-rules)을 참조하세요 | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |362| `deny` | 도구 사용을 거부하는 권한 규칙 배열입니다. 이를 사용하여 Claude Code 액세스에서 민감한 파일을 제외합니다. 도구 이름은 glob 패턴을 허용합니다: `"*"`는 모든 도구를 거부하고 `"mcp__*"`는 모든 MCP 도구를 거부합니다. [권한 규칙 구문](#permission-rule-syntax) 및 [Bash 권한 제한](/ko/permissions#tool-specific-permission-rules)을 참조하세요 | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |

320| `additionalDirectories` | Claude가 액세스할 수 있는 추가 [작업 디렉토리](/ko/permissions#working-directories)입니다. 대부분의 `.claude/` 구성은 이러한 디렉토리에서 [발견되지 않습니다](/ko/permissions#additional-directories-grant-file-access-not-configuration) | `[ "../docs/" ]` |363| `additionalDirectories` | Claude가 액세스할 수 있는 추가 [작업 디렉토리](/ko/permissions#working-directories)입니다. 대부분의 `.claude/` 구성은 이러한 디렉토리에서 [발견되지 않습니다](/ko/permissions#additional-directories-grant-file-access-not-configuration) | `[ "../docs/" ]` |

321| `defaultMode` | Claude Code를 열 때 기본 [권한 모드](/ko/permission-modes)입니다. 유효한 값: `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`. {/* min-version: 2.1.142 */}Claude Code v2.1.142부터 프로젝트 또는 local 설정 (`.claude/settings.json`, `.claude/settings.local.json`)에서 설정되면 `auto`가 무시되므로 저장소가 자신에게 자동 모드를 부여할 수 없습니다. 대신 `~/.claude/settings.json`에서 설정합니다. `--permission-mode` CLI 플래그는 단일 세션에 대해 이 설정을 재정의합니다 | `"acceptEdits"` |364| `defaultMode` | Claude Code를 열 때 기본 [권한 모드](/ko/permission-modes)입니다. 유효한 값: `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`. {/* min-version: 2.1.142 */}Claude Code v2.1.142부터 프로젝트 또는 local 설정 (`.claude/settings.json`, `.claude/settings.local.json`)에서 설정되면 `auto`가 무시되므로 저장소가 자신에게 자동 모드를 부여할 수 없습니다. 대신 `~/.claude/settings.json`에서 설정합니다. `--permission-mode` CLI 플래그는 단일 세션에 대해 이 설정을 재정의합니다 | `"acceptEdits"` |

322| `disableBypassPermissionsMode` | `bypassPermissions` 모드가 활성화되는 것을 방지하려면 `"disable"`로 설정합니다. 이는 `--dangerously-skip-permissions` 명령줄 플래그를 비활성화합니다. 일반적으로 [managed 설정](/ko/permissions#managed-settings)에 배치되어 조직 정책을 적용하지만 모든 범위에서 작동합니다 | `"disable"` |365| `disableBypassPermissionsMode` | `bypassPermissions` 모드가 활성화되는 것을 방지하려면 `"disable"`로 설정합니다. 이는 `--dangerously-skip-permissions` 명령줄 플래그를 비활성화합니다. 일반적으로 [managed 설정](/ko/permissions#managed-settings)에 배치되어 조직 정책을 적용하지만 모든 범위에서 작동합니다 | `"disable"` |


326 권한 규칙 구문369 권한 규칙 구문

327</h3>370</h3>

328 371 

329권한 규칙은 `Tool` 또는 `Tool(specifier)` 형식을 따릅니다. 규칙은 순서대로 평가됩니다: 먼저 거부 규칙, 그 다음 요청, 그 다음 허용. 첫 번째 일치 규칙이 우승합니다.372권한 규칙은 `Tool` 또는 `Tool(specifier)` 형식을 따릅니다. 규칙은 순서대로 평가됩니다: 먼저 거부 규칙, 그 다음 요청, 그 다음 허용. 첫 번째 일치 규칙이 우승합니다. 규칙 특이성과 관계없이 결과를 결정합니다. [권한 규칙 평가 순서](/ko/permissions#manage-permissions)를 참조하세요.

330 373 

331빠른 예제:374빠른 예제:

332 375 


431**기본 커밋 attribution:**474**기본 커밋 attribution:**

432 475 

433```text theme={null}476```text theme={null}

434🤖 Generated with [Claude Code](https://claude.com/claude-code)477Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

435 

436 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

437```478```

438 479 

480세션의 활성 모델을 반영하는 trailer의 모델 이름입니다.

481 

439**기본 pull request attribution:**482**기본 pull request attribution:**

440 483 

441```text theme={null}484```text theme={null}


491```bash theme={null}534```bash theme={null}

492#!/bin/bash535#!/bin/bash

493query=$(cat | jq -r '.query')536query=$(cat | jq -r '.query')

537# your-repo-file-index를 자신의 파일 검색 명령으로 바꿉니다

494your-repo-file-index --query "$query" | head -20538your-repo-file-index --query "$query" | head -20

495```539```

496 540 

541<h3 id="footer-link-badges">

542 바닥글 링크 배지

543</h3>

544 

545`footerLinksRegexes` 설정은 입력 상자 아래 바닥글에 클릭 가능한 배지를 렌더링합니다. 이를 사용하여 검토 도구 및 이슈 추적기와 같은 프로젝트 CLI에서 인쇄한 ID를 세션 링크로 변환합니다.

546 

547각 항목의 `pattern` 정규식은 턴 출력과 일치합니다: 도구 결과 (파일 내용 및 가져온 페이지 포함) 및 Claude의 자체 응답. `url` 및 `label`의 `{name}` 자리 표시자는 패턴의 명명된 캡처 그룹에서 채워집니다.

548 

549다음 예제는 `PROJ-1234`와 같은 이슈 키가 턴 출력에 나타날 때마다 배지를 렌더링합니다. `(?<key>...)` 명명된 그룹이 키를 캡처하고 `{key}`가 URL 및 레이블로 대체됩니다:

550 

551```json ~/.claude/settings.json theme={null}

552{

553 "footerLinksRegexes": [

554 {

555 "type": "regex",

556 "pattern": "\\b(?<key>PROJ-\\d+)\\b",

557 "url": "https://issues.example.com/browse/{key}",

558 "label": "{key}"

559 }

560 ]

561}

562```

563 

564이렇게 구성하면 `PROJ-1234`가 도구 결과 또는 Claude의 응답에 나타날 때 `PROJ-1234` 칩이 바닥글에 나타나 `https://issues.example.com/browse/PROJ-1234`로 연결됩니다.

565 

566다음 제약이 각 항목에 적용됩니다:

567 

568| 제약 | 동작 |

569| :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

570| URL origin | 캡처된 값은 URL 인코딩되고 구성된 URL은 템플릿의 리터럴 origin을 공유해야 합니다. 캡처는 경로 세그먼트 또는 쿼리 값을 채울 수 있지만 링크가 가리키는 위치를 변경할 수 없습니다 |

571| URL 길이 | 2048자보다 긴 구성된 URL은 삭제됩니다 |

572| URL 스키마 | `https`, `http` 또는 인식된 편집기 또는 작업 공간 deep-link 스키마여야 합니다: `vscode`, `vscode-insiders`, `cursor`, `windsurf`, `zed`, `jetbrains`, `idea`, `slack`, `linear`, `notion`, `figma` |

573| 레이블 | 기본값은 일치한 텍스트이며 28개 표시 열로 잘립니다 |

574| 배지 수 | 최대 5개 배지가 렌더링됩니다. 가장 오래된 것이 새로운 일치로 대체되고 `/clear`가 이를 제거합니다 |

575| 설정 범위 | 사용자 설정, `--settings` 플래그 및 managed 설정에서만 읽습니다. 프로젝트 `.claude/settings.json` 및 local `.claude/settings.local.json`에서는 무시됩니다 |

576 

577턴이 완료되면 Claude Code는 메인 스레드에서 각 항목의 `pattern` 정규식을 턴 출력과 일치시키므로 느린 정규식은 완료될 때까지 UI를 차단합니다. `(a+)+$`와 같은 중첩된 수량자는 특정 입력에 대해 지수적으로 오래 걸릴 수 있고 세션을 고정시킬 수 있으므로 각 `pattern`을 선형으로 유지하고 `+` 또는 `*` 중첩을 피합니다.

578 

579바닥글 배지는 구성된 [사용자 정의 상태 줄](/ko/statusline)과 함께 렌더링됩니다. 어느 것도 다른 것을 대체하지 않습니다. 세션 데이터에서 자신의 콘텐츠를 계산하는 스크립트 기반 행에 상태 줄을 사용하고 스크립트 없이 대화에서 ID를 링크로 변환하려면 바닥글 배지를 사용합니다.

580 

497<h3 id="hook-configuration">581<h3 id="hook-configuration">

498 Hook 구성582 Hook 구성

499</h3>583</h3>


583예를 들어 사용자 설정이 `permissions.defaultMode`를 `acceptEdits`로 설정하지만 프로젝트의 공유 설정이 이를 `default`로 설정하면 프로젝트 값이 적용됩니다. 아래 예제는 배열 값 설정 (예: 권한 규칙)이 대신 어떻게 결합되는지를 다룹니다.667예를 들어 사용자 설정이 `permissions.defaultMode`를 `acceptEdits`로 설정하지만 프로젝트의 공유 설정이 이를 `default`로 설정하면 프로젝트 값이 적용됩니다. 아래 예제는 배열 값 설정 (예: 권한 규칙)이 대신 어떻게 결합되는지를 다룹니다.

584 668 

585<Note>669<Note>

586 **배열 설정은 범위 전체에서 병합됩니다.** 동일한 배열 값 설정 (예: `sandbox.filesystem.allowWrite` 또는 `permissions.allow`)이 여러 범위에 나타나면 배열은 **연결되고 중복 제거되며** 대체되지 않습니다. 이는 낮은 우선순위 범위가 높은 우선순위 범위에서 설정한 항목을 재정의하지 않고 항목을 추가할 수 있음을 의미하며 그 반대도 마찬가지입니다. 예를 들어 managed 설정이 `allowWrite`를 `["/opt/company-tools"]`로 설정하고 사용자가 `["~/.kube"]`를 추가하면 두 경로 모두 최종 구성에 포함됩니다.670 **배열 설정은 범위 전체에서 병합됩니다.** 동일한 배열 값 설정 (예: `sandbox.filesystem.allowWrite` 또는 `permissions.allow`)이 여러 범위에 나타나면 배열은 **연결되고 중복 제거되며** 대체되지 않습니다. 이는 낮은 우선순위 범위가 높은 우선순위 범위에서 설정한 항목을 재정의하지 않고 항목을 추가할 수 있음을 의미하며 그 반대도 마찬가지입니다. 예를 들어 managed 설정이 `allowWrite`를 `["/opt/company-tools"]`로 설정하고 사용자가 `["~/.kube"]`를 추가하면 두 경로 모두 최종 구성에 포함됩니다. 유일한 예외는 [`fallbackModel`](#available-settings)로, 위치가 의미를 가지는 순서가 지정된 체인입니다: 이를 정의하는 최고 우선순위 파일이 전체 값을 제공합니다. 또 다른 예외는 {/* min-version: 2.1.175 */}v2.1.175부터 [`availableModels`](#available-settings)로, managed 또는 정책 값이 낮은 우선순위 항목을 완전히 대체합니다. [병합 동작](/ko/model-config#merge-behavior)을 참조하세요.

587</Note>671</Note>

588 672 

589<h3 id="verify-active-settings">673<h3 id="verify-active-settings">

590 활성 설정 확인674 활성 설정 확인

591</h3>675</h3>

592 676 

593Claude Code 내에서 `/status`를 실행하여 어떤 설정 소스가 활성화되어 있고 어디에서 오는지 확인합니다. Status 탭에는 구성 계층을 나열하는 `Setting sources` 줄이 포함되어 있습니다 (예: `User settings` 또는 `Project local settings`). [managed 설정](/ko/managed-settings)이 적용되면 항목은 전달 채널을 괄호로 표시합니다 (예: `Enterprise managed settings (remote)`, `(plist)`, `(HKLM)`, `(HKCU)` 또는 `(file)`). 계층은 최소 하나의 키로 로드될 때만 목록에 나타나므로 빈 목록은 설정 소스를 찾을 수 없음을 의미합니다.677Claude Code 내에서 `/status`를 실행하여 활성 설정 소스를 확인합니다. 메뉴 내에서 **Status** 탭에는 세션에 대해 Claude Code가 로드한 각 계층을 나열하는 `Setting sources` 줄이 포함됩니다 (예: `User settings` 또는 `Project local settings`). [managed 설정](/ko/admin-setup#decide-how-settings-reach-devices)이 적용되면 항목은 전달 채널을 괄호로 표시합니다 (예: `Enterprise managed settings (remote)`, `(plist)`, `(HKLM)`, `(HKCU)` 또는 `(file)`). 계층은 해당 소스가 최소 하나의 키로 로드될 때만 목록에 나타나므로 빈 목록은 설정 소스를 찾을 수 없음을 의미합니다.

678 

679`Setting sources` 줄은 어떤 소스가 읽혀지는지 확인합니다. 각 개별 키를 제공한 계층을 표시하지는 않습니다. **Config** 탭은 동일한 대화에서 테마 및 verbose 출력과 같은 고정된 토글 집합의 편집기입니다. `settings.json` 내용의 보기가 아닙니다.

594 680 

595`Setting sources` 줄은 어떤 소스가 읽혀지는지 확인합니다. 각 개별 키를 제공한 계층을 표시하지는 않습니다. Config 탭은 동일한 대화에서 테마 verbose 출력과 같은 고정된 토글 집합의 편집기이며 `settings.json` 내용의 보기가 아닙니다. 설정 파일에 유효하지 않은 JSON 또는 검증에 실패한 값과 같은 오류가 포함되어 있으면 `/status`는 문제를 보고하여 수정할 수 있습니다.681설정 파일에 유효하지 않은 JSON 또는 검증에 실패한 값이 포함되어 있으면 Claude Code는 시작 설정 문제 알림을 표시하고 `/status` 영향을 받는 파일을 나열합니다. 오류의 세부 사항을 보려면 `/doctor` 실행합니다.

596 682 

597<h3 id="key-points-about-the-configuration-system">683<h3 id="key-points-about-the-configuration-system">

598 구성 시스템의 핵심 포인트684 구성 시스템의 핵심 포인트


603* **Skills**: `/skill-name`으로 호출하거나 Claude가 자동으로 로드할 수 있는 사용자 정의 프롬프트689* **Skills**: `/skill-name`으로 호출하거나 Claude가 자동으로 로드할 수 있는 사용자 정의 프롬프트

604* **MCP servers**: 추가 도구 및 통합으로 Claude Code를 확장합니다690* **MCP servers**: 추가 도구 및 통합으로 Claude Code를 확장합니다

605* **우선순위**: 높은 수준 구성 (Managed)이 낮은 수준 (User/Project)을 재정의합니다691* **우선순위**: 높은 수준 구성 (Managed)이 낮은 수준 (User/Project)을 재정의합니다

606* **상속**: 설정은 병합되며 구체적인 설정이 광범위한 설정을 추가하거나 재정의합니다692* **상속**: 설정은 범위 전체에서 병합됩니다. 스칼라 값은 높은 우선순위 범위에서 재정의되고, 배열은 연결됩니다 (예외: `fallbackModel`은 최고 우선순위 범위가 전체 체인을 제공합니다. v2.1.175부터 `availableModels`도 managed 또는 정책 값이 낮은 우선순위 항목을 완전히 대체합니다)

607 693 

608<h3 id="system-prompt">694<h3 id="system-prompt">

609 시스템 프롬프트695 시스템 프롬프트


684 770 

685* **사용자 설정** (`~/.claude/settings.json`): 개인 플러그인 설정771* **사용자 설정** (`~/.claude/settings.json`): 개인 플러그인 설정

686* **프로젝트 설정** (`.claude/settings.json`): 팀과 공유되는 프로젝트 특정 플러그인772* **프로젝트 설정** (`.claude/settings.json`): 팀과 공유되는 프로젝트 특정 플러그인

687* **Local 설정** (`.claude/settings.local.json`): 머신별 재정의 (커밋되지 않음)773* **Local 설정** (`.claude/settings.local.json`): 머신별 재정의, Claude Code가 생성할 때 gitignored됨

688* **Managed 설정** (`managed-settings.json`): 모든 범위에서 설치를 차단하고 마켓플레이스에서 플러그인을 숨기는 조직 전체 정책 재정의774* **Managed 설정** (`managed-settings.json`): 모든 범위에서 설치를 차단하고 마켓플레이스에서 플러그인을 숨기는 조직 전체 정책 재정의

689 775 

690<Note>776<Note>


798 884 

799**허용 목록 동작**:885**허용 목록 동작**:

800 886 

801* `undefined` (기본값): 제한 없음 - 사용자는 모든 마켓플레이스를 추가할 수 있음887* `undefined` (기본값): 제한 없음 - 사용자는 모든 마켓플레이스를 추가할 수 있습니다

802* 빈 배열 `[]`: 완전 잠금 - 사용자는 새 마켓플레이스를 추가할 수 없음888* 빈 배열 `[]`: 완전 잠금 - 사용자는 새 마켓플레이스를 추가할 수 없습니다

803* 소스 목록: 사용자는 정확히 일치하는 마켓플레이스만 추가할 수 있음889* 소스 목록: 사용자는 정확히 일치하는 마켓플레이스만 추가할 수 있습니다

804 890 

805**지원되는 모든 소스 유형**:891**지원되는 모든 소스 유형**:

806 892 


948 1034 

949마켓플레이스 소스는 사용자의 추가가 허용되려면 **정확히** 일치해야 합니다. git 기반 소스 (`github` 및 `git`)의 경우 이는 모든 선택적 필드를 포함합니다:1035마켓플레이스 소스는 사용자의 추가가 허용되려면 **정확히** 일치해야 합니다. git 기반 소스 (`github` 및 `git`)의 경우 이는 모든 선택적 필드를 포함합니다:

950 1036 

951* `repo` 또는 `url`이 정확히 일치해야 1037* `repo` 또는 `url`이 정확히 일치해야 합니다

952* `ref` 필드가 정확히 일치해야 (또는 둘 다 정의되지 않음)1038* `ref` 필드가 정확히 일치해야 합니다 (또는 둘 다 정의되지 않음)

953* `path` 필드가 정확히 일치해야 (또는 둘 다 정의되지 않음)1039* `path` 필드가 정확히 일치해야 합니다 (또는 둘 다 정의되지 않음)

954 1040 

955일치하지 **않는** 소스의 예:1041일치하지 **않는** 소스의 예:

956 1042 


1021 1107 

1022**중요 참고 사항**:1108**중요 참고 사항**:

1023 1109 

1024* 제한은 네트워크 요청 또는 파일 시스템 작업 전에 확인됨1110* 제한은 네트워크 요청 또는 파일 시스템 작업 전에 확인됩니다

1025* 차단되면 사용자는 소스가 managed 정책으로 차단되었음을 나타내는 명확한 오류 메시지를 봅니다1111* 차단되면 사용자는 소스가 managed 정책으로 차단되었음을 나타내는 명확한 오류 메시지를 봅니다

1026* 제한은 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로고침 및 자동 업데이트에 적용됩니다. 정책이 설정되기 전에 추가된 마켓플레이스는 해당 소스가 더 이상 허용 목록과 일치하지 않으면 플러그인을 설치하거나 업데이트하는 데 사용할 수 없습니다1112* 제한은 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로고침 및 자동 업데이트에 적용됩니다. 정책이 설정되기 전에 추가된 마켓플레이스는 해당 소스가 더 이상 허용 목록과 일치하지 않으면 플러그인을 설치하거나 업데이트하는 데 사용할 수 없습니다

1027* Managed 설정은 최고 우선순위를 가지며 재정의할 수 없습니다1113* Managed 설정은 최고 우선순위를 가지며 재정의할 수 없습니다

setup.md +28 −6

Details

258 258 

259[관리 설정](/ko/permissions#managed-settings)에서 이는 사용자 및 프로젝트 설정이 재정의할 수 없는 조직 전체 최소값을 적용합니다.259[관리 설정](/ko/permissions#managed-settings)에서 이는 사용자 및 프로젝트 설정이 재정의할 수 없는 조직 전체 최소값을 적용합니다.

260 260 

261`minimumVersion` 핀은 업데이트만 제한합니다. Claude Code가 버전 범위 외에서 시작되지 않도록 하려면 관리 설정 `requiredMinimumVersion` 및 `requiredMaximumVersion`을 대신 사용하세요. 업데이트는 또한 `requiredMaximumVersion` 상한을 준수합니다. [사용 가능한 설정](/ko/settings#available-settings)을 참조하세요.

262 

261<h3 id="disable-auto-updates">263<h3 id="disable-auto-updates">

262 자동 업데이트 비활성화264 자동 업데이트 비활성화

263</h3>265</h3>


366 Linux 패키지 관리자로 설치368 Linux 패키지 관리자로 설치

367</h3>369</h3>

368 370 

369Claude Code는 서명된 apt, dnf 및 apk 저장소를 게시합니다. 롤링 채널의 경우 `stable` `latest` 바꾸세요. 패키지 관리자 설치는 Claude Code를 통해 자동 업데이트되지 않습니다. 업데이트는 일반적인 시스템 업그레이드 워크플로우를 통해 제공됩니다.371Claude Code는 서명된 apt, dnf 및 apk 저장소를 게시합니다. 저장소는 가지 채널을 제공합니다. `stable` 일반적으로 약 1주일 된 버전을 제공하며 주요 회귀가 있는 릴리스를 건너뛰고, `latest` 모든 릴리스를 출시되는 즉시 제공합니다. 아래 명령은 대부분의 사용자에게 적합한 `stable` 채널을 구성합니다. 각 탭에는 `latest` 저장소 URL도 표시됩니다. 패키지 관리자 설치는 Claude Code를 통해 자동 업데이트되지 않습니다. 업데이트는 일반적인 시스템 업그레이드 워크플로우를 통해 제공됩니다.

370 372 

371모든 저장소는 [Claude Code 릴리스 서명 키](#binary-integrity-and-code-signing)로 서명됩니다. 키를 신뢰하기 전에 각 탭에 설명된 대로 확인하세요.373모든 저장소는 [Claude Code 릴리스 서명 키](#binary-integrity-and-code-signing)로 서명됩니다. 키를 신뢰하기 전에 각 탭에 설명된 대로 확인하세요.

372 374 

373<Tabs>375<Tabs>

374 <Tab title="apt">376 <Tab title="apt">

375 Debian 및 Ubuntu용입니다. 롤링 채널을 사용하려면 `deb` 줄의 `stable` 항목을 변경하세요: URL 경로 및 제품군 이름입니다.377 Debian 및 Ubuntu용입니다. 다음 명령은 `stable` 채널을 구성합니다:

376 378 

377 ```bash theme={null}379 ```bash theme={null}

378 sudo install -d -m 0755 /etc/apt/keyrings380 sudo install -d -m 0755 /etc/apt/keyrings


384 sudo apt install claude-code386 sudo apt install claude-code

385 ```387 ```

386 388 

389 대신 `latest` 채널을 사용하려면 URL 경로와 제품군 이름이 모두 변경됩니다. 이 `deb` 줄을 사용하세요:

390 

391 ```bash theme={null}

392 echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/latest latest main" \

393 | sudo tee /etc/apt/sources.list.d/claude-code.list

394 ```

395 

387 신뢰하기 전에 GPG 키 지문을 확인하세요: `gpg --show-keys /etc/apt/keyrings/claude-code.asc`는 `31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE`를 보고해야 합니다.396 신뢰하기 전에 GPG 키 지문을 확인하세요: `gpg --show-keys /etc/apt/keyrings/claude-code.asc`는 `31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE`를 보고해야 합니다.

388 397 

389 나중에 업그레이드하려면 `sudo apt update && sudo apt upgrade claude-code`를 실행하세요.398 나중에 업그레이드하려면 `sudo apt update && sudo apt upgrade claude-code`를 실행하세요.

390 </Tab>399 </Tab>

391 400 

392 <Tab title="dnf">401 <Tab title="dnf">

393 Fedora 및 RHEL용입니다:402 Fedora 및 RHEL용입니다. 다음 명령은 `stable` 채널을 구성합니다:

394 403 

395 ```bash theme={null}404 ```bash theme={null}

396 sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'405 sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'


404 sudo dnf install claude-code413 sudo dnf install claude-code

405 ```414 ```

406 415 

416 대신 `latest` 채널을 사용하려면 `baseurl`을 `latest` 저장소로 설정하세요:

417 

418 ```ini theme={null}

419 baseurl=https://downloads.claude.ai/claude-code/rpm/latest

420 ```

421 

407 dnf는 첫 설치 시 키를 다운로드하고 지문을 확인하도록 요청합니다. `31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE`와 일치하는지 확인한 후 수락하세요.422 dnf는 첫 설치 시 키를 다운로드하고 지문을 확인하도록 요청합니다. `31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE`와 일치하는지 확인한 후 수락하세요.

408 423 

409 나중에 업그레이드하려면 `sudo dnf upgrade claude-code`를 실행하세요.424 나중에 업그레이드하려면 `sudo dnf upgrade claude-code`를 실행하세요.

410 </Tab>425 </Tab>

411 426 

412 <Tab title="apk">427 <Tab title="apk">

413 Alpine Linux용입니다:428 Alpine Linux용입니다. 다음 명령은 `stable` 채널을 구성합니다:

414 429 

415 ```sh theme={null}430 ```sh theme={null}

416 wget -O /etc/apk/keys/claude-code.rsa.pub \431 wget -O /etc/apk/keys/claude-code.rsa.pub \


419 apk add claude-code434 apk add claude-code

420 ```435 ```

421 436 

437 `latest` 채널로 전환하려면 `stable` 저장소 줄을 제거하고 `latest` 저장소를 추가하세요:

438 

439 ```sh theme={null}

440 sed -i '\|downloads.claude.ai/claude-code/apk/stable|d' /etc/apk/repositories

441 echo "https://downloads.claude.ai/claude-code/apk/latest" >> /etc/apk/repositories

442 ```

443 

422 `sha256sum /etc/apk/keys/claude-code.rsa.pub`로 다운로드한 키를 확인하세요. 이는 `395759c1f7449ef4cdef305a42e820f3c766d6090d142634ebdb049f113168b6`을 보고해야 합니다.444 `sha256sum /etc/apk/keys/claude-code.rsa.pub`로 다운로드한 키를 확인하세요. 이는 `395759c1f7449ef4cdef305a42e820f3c766d6090d142634ebdb049f113168b6`을 보고해야 합니다.

423 445 

424 나중에 업그레이드하려면 `apk update && apk upgrade claude-code`를 실행하세요.446 나중에 업그레이드하려면 `apk update && apk upgrade claude-code`를 실행하세요.


455 매니페스트 서명 확인477 매니페스트 서명 확인

456</h4>478</h4>

457 479 

458다음 단계 1-3에는 `gpg` 및 `curl`이 있는 POSIX 셸이 필요합니다. Windows에서는 Git Bash 또는 WSL에서 실행하세요. 4단계에는 PowerShell 옵션이 포함됩니다.480단계 1-3에는 `gpg` 및 `curl`이 있는 POSIX 셸이 필요합니다. Windows에서는 Git Bash 또는 WSL에서 실행하세요. 단계 4에는 PowerShell 옵션이 포함됩니다.

459 481 

460<Steps>482<Steps>

461 <Step title="공개 키 다운로드 및 가져오기">483 <Step title="공개 키 다운로드 및 가져오기">


498 520 

499 유효한 결과는 `Good signature from "Anthropic Claude Code Release Signing <security@anthropic.com>"`을 보고합니다.521 유효한 결과는 `Good signature from "Anthropic Claude Code Release Signing <security@anthropic.com>"`을 보고합니다.

500 522 

501 `gpg`는 또한 새로 가져온 키에 대해 `WARNING: This key is not certified with a trusted signature!`을 인쇄합니다. 이는 예상된 것입니다. `Good signature` 줄은 암호화 확인이 통과했음을 확인합니다. 1단계의 지문 비교는 키 자체가 진정함을 확인합니다.523 `gpg`는 또한 새로 가져온 키에 대해 `WARNING: This key is not certified with a trusted signature!`을 인쇄합니다. 이는 예상된 것입니다. `Good signature` 줄은 암호화 확인이 통과했음을 확인합니다. 단계 1의 지문 비교는 키 자체가 진정함을 확인합니다.

502 </Step>524 </Step>

503 525 

504 <Step title="바이너리를 매니페스트와 비교">526 <Step title="바이너리를 매니페스트와 비교">

skills.md +18 −5

Details

22 번들 skills22 번들 skills

23</h2>23</h2>

24 24 

25Claude Code에는 모든 세션에서 사용 가능한 번들 skills 세트가 포함되어 있으며, `/code-review`, `/batch`, `/debug`, `/loop`, `/claude-api`를 포함합니다. 고정 로직을 직접 실행하는 대부분의 기본 제공 명령어와 달리, 번들 skills는 프롬프트 기반입니다: Claude에 상세한 지시사항을 제공하고 도구를 사용하여 작업을 조율하도록 합니다. 다른 skill과 동일한 방식으로 호출합니다: `/` 다음에 skill 이름을 입력합니다.25Claude Code에는 모든 세션에서 사용 가능한 번들 skills 세트가 포함되어 있으며, [`disableBundledSkills`](/ko/settings#available-settings) 설정으로 비활성화하지 않는 한 `/code-review`, `/batch`, `/debug`, `/loop`, `/claude-api`를 포함합니다. 고정 로직을 직접 실행하는 대부분의 기본 제공 명령어와 달리, 번들 skills는 프롬프트 기반입니다: Claude에 상세한 지시사항을 제공하고 도구를 사용하여 작업을 조율하도록 합니다. 다른 skill과 동일한 방식으로 호출합니다: `/` 다음에 skill 이름을 입력합니다.

26 26 

27번들 skills는 [명령어 참조](/ko/commands)에 나열되어 있으며, 목적 열에 **Skill**로 표시됩니다.27번들 skills는 [명령어 참조](/ko/commands)에 나열되어 있으며, 목적 열에 **Skill**로 표시됩니다.

28 28 


117| Project | `.claude/skills/<skill-name>/SKILL.md` | 이 프로젝트만 |117| Project | `.claude/skills/<skill-name>/SKILL.md` | 이 프로젝트만 |

118| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | 플러그인이 활성화된 위치 |118| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | 플러그인이 활성화된 위치 |

119 119 

120Skills가 여러 수준에서 같은 이름을 공유할 때, enterprise가 personal을 재정의하고, personal이 project를 재정의합니다. Plugin skills는 `plugin-name:skill-name` 네임스페이스를 사용하므로 다른 수준과 충돌할 수 없습니다. `.claude/commands/`에 파일이 있으면 동일한 방식으로 작동하지만, skill과 명령어가 같은 이름을 공유하면 skill이 우선합니다.120skills가 여러 수준에서 같은 이름을 공유할 때, enterprise가 personal을 재정의하고, personal이 project를 재정의합니다. 예를 들어, 프로젝트의 `.claude/skills/`에 있는 `code-review` skill은 번들된 `/code-review`를 대체합니다. Plugin skills는 `plugin-name:skill-name` 네임스페이스를 사용하므로 다른 수준과 충돌할 수 없습니다. `.claude/commands/`에 파일이 있으면 동일한 방식으로 작동하지만, skill과 명령어가 같은 이름을 공유하면 skill이 우선합니다.

121 

122Skills는 또한 작업 디렉토리 아래의 중첩된 `.claude/skills/` 디렉토리에서 로드됩니다. Claude가 하위 디렉토리의 파일을 읽거나 편집할 때, 해당 하위 디렉토리의 `.claude/skills/`에 있는 skills가 사용 가능해집니다. 이를 통해 monorepo 패키지가 자신의 skills를 제공할 수 있으며, 세션이 저장소 루트에서 시작되었더라도 해당 패키지에서 작업할 때 적용됩니다.

123 

124중첩된 skill이 다른 skill과 같은 이름을 공유하면, 둘 다 사용 가능합니다. 예를 들어, 프로젝트 루트에 `deploy` skill이 있고 `apps/web/.claude/skills/`에 다른 skill이 있는 경우:

125 

126* 중첩된 skill은 디렉토리 한정 이름 `apps/web:deploy` 아래에 나타납니다.

127* 해당 설명은 어느 디렉토리에 적용되는지 나타냅니다.

128* Claude는 작업 중인 파일과 일치하는 변형을 선택합니다.

129 

130`/deploy`를 입력하면 프로젝트 루트 skill이 실행됩니다. 중첩된 변형을 명시적으로 실행하려면 한정된 이름 `/apps/web:deploy`를 입력합니다.

121 131 

122<Note>132<Note>

123 `.claude-plugin/plugin.json`을 skill 폴더에 추가하면 `<name>@skills-dir`이라는 [플러그인](/ko/plugins-reference#skills-directory-plugins)으로 로드되므로, agents, hooks 및 MCP 서버를 번들로 제공할 수 있습니다. 프로젝트의 `.claude/skills/`에서는 먼저 작업 공간 신뢰 대화를 수락해야 합니다.133 `.claude-plugin/plugin.json`을 skill 폴더에 추가하면 `<name>@skills-dir`이라는 [플러그인](/ko/plugins-reference#skills-directory-plugins)으로 로드되므로, agents, hooks 및 MCP 서버를 번들로 제공할 수 있습니다. 프로젝트의 `.claude/skills/`에서는 먼저 작업 공간 신뢰 대화를 수락해야 합니다.


262아래 표는 각 레이아웃에 대해 명령어 이름이 어디에서 나오는지 보여줍니다:272아래 표는 각 레이아웃에 대해 명령어 이름이 어디에서 나오는지 보여줍니다:

263 273 

264| Skill 위치 | 명령어 이름 소스 | 예제 |274| Skill 위치 | 명령어 이름 소스 | 예제 |

265| :------------------------------------------------------ | :------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------- |275| :-------------------------------------------------------------------- | :--------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------- |

266| `~/.claude/skills/` 또는 `.claude/skills/` 아래의 Skill 디렉토리 | 디렉토리 이름 | `.claude/skills/deploy-staging/SKILL.md` → `/deploy-staging` |276| `~/.claude/skills/` 또는 `.claude/skills/` 아래의 Skill 디렉토리 | 디렉토리 이름 | `.claude/skills/deploy-staging/SKILL.md` → `/deploy-staging` |

277| [중첩된](#where-skills-live) `.claude/skills/` 디렉토리, 다른 skill과 이름이 충돌할 때 | 작업 디렉토리를 기준으로 한 하위 디렉토리 경로, 그 다음 skill 디렉토리 이름 | `apps/web/.claude/skills/deploy/SKILL.md` → `/apps/web:deploy` |

267| `.claude/commands/` 아래의 파일 | 확장자 없는 파일 이름 | `.claude/commands/deploy.md` → `/deploy` |278| `.claude/commands/` 아래의 파일 | 확장자 없는 파일 이름 | `.claude/commands/deploy.md` → `/deploy` |

268| Plugin `skills/` 하위 디렉토리 | 디렉토리 이름, plugin으로 네임스페이스됨 | `my-plugin/skills/review/SKILL.md` → `/my-plugin:review` |279| Plugin `skills/` 하위 디렉토리 | 디렉토리 이름, plugin으로 네임스페이스됨 | `my-plugin/skills/review/SKILL.md` → `/my-plugin:review` |

269| Plugin 루트 `SKILL.md` | Frontmatter `name`, plugin 디렉토리 이름을 폴백으로 사용 | `my-plugin/SKILL.md`에서 `name: review` → `/my-plugin:review`. [경로 동작 규칙](/ko/plugins-reference#path-behavior-rules) 참조 |280| Plugin 루트 `SKILL.md` | Frontmatter `name`, plugin 디렉토리 이름을 폴백으로 사용 | `my-plugin/SKILL.md`에서 `name: review` → `/my-plugin:review`. [경로 동작 규칙](/ko/plugins-reference#path-behavior-rules) 참조 |


288 299 

289인덱싱된 인수는 shell 스타일 인용을 사용하므로 다중 단어 값을 따옴표로 감싸서 단일 인수로 전달합니다. 예를 들어, `/my-skill "hello world" second`는 `$0`을 `hello world`로, `$1`을 `second`로 확장합니다. `$ARGUMENTS` 플레이스홀더는 항상 입력한 전체 인수 문자열로 확장됩니다.300인덱싱된 인수는 shell 스타일 인용을 사용하므로 다중 단어 값을 따옴표로 감싸서 단일 인수로 전달합니다. 예를 들어, `/my-skill "hello world" second`는 `$0`을 `hello world`로, `$1`을 `second`로 확장합니다. `$ARGUMENTS` 플레이스홀더는 항상 입력한 전체 인수 문자열로 확장됩니다.

290 301 

302리터럴 `$`를 숫자, `ARGUMENTS` 또는 선언된 인수 이름 앞에 포함하려면(예: 산문에서 `$1.00`), 백슬래시로 이스케이프합니다: `\$1.00`. 다른 `$` 앞의 백슬래시는 변경되지 않습니다. 토큰 바로 앞의 단일 백슬래시만 이스케이프합니다. `\\$1`과 같은 이중 백슬래시는 두 백슬래시를 제자리에 두고, `$1`은 여전히 인수 값으로 확장됩니다.

303 

291**치환을 사용한 예제:**304**치환을 사용한 예제:**

292 305 

293```yaml theme={null}306```yaml theme={null}


395---408---

396```409```

397 410 

398skill이 특정 도구를 사용하지 못하도록 차단하려면, [권한 설정](/ko/permissions)에 거부 규칙을 추가합니다.411skill이 활성화되었을 때 Claude의 사용 가능한 풀에서 도구를 제거하려면, skill의 frontmatter에서 `disallowed-tools`에 나열합니다. 다음 메시지를 보낼 때 제한이 해제됩니다. 모든 skills 및 프롬프트에서 도구를 차단하려면, [권한 설정](/ko/permissions)에 거부 규칙을 추가합니다.

399 412 

400<h3 id="pass-arguments-to-skills">413<h3 id="pass-arguments-to-skills">

401 Skills에 인수 전달414 Skills에 인수 전달


557 570 

558`agent` 필드는 사용할 subagent 구성을 지정합니다. 옵션에는 기본 제공 에이전트(`Explore`, `Plan`, `general-purpose`) 또는 `.claude/agents/`의 모든 사용자 정의 subagent가 포함됩니다. 생략하면 `general-purpose`를 사용합니다.571`agent` 필드는 사용할 subagent 구성을 지정합니다. 옵션에는 기본 제공 에이전트(`Explore`, `Plan`, `general-purpose`) 또는 `.claude/agents/`의 모든 사용자 정의 subagent가 포함됩니다. 생략하면 `general-purpose`를 사용합니다.

559 572 

560<h3 id="restrict-claude-s-skill-access">573<h3 id="restrict-claudes-skill-access">

561 Claude의 Skill 액세스 제한574 Claude의 Skill 액세스 제한

562</h3>575</h3>

563 576 

slack.md +1 −1

Details

182 182 

183이 채널 기반 모델을 통해 팀은 Claude Code 사용을 특정 채널로 제한하여 워크스페이스 수준 권한 이상의 추가 액세스 제어 계층을 제공할 수 있습니다.183이 채널 기반 모델을 통해 팀은 Claude Code 사용을 특정 채널로 제한하여 워크스페이스 수준 권한 이상의 추가 액세스 제어 계층을 제공할 수 있습니다.

184 184 

185<h2 id="what-s-accessible-where">185<h2 id="whats-accessible-where">

186 어디서 액세스할 수 있는지186 어디서 액세스할 수 있는지

187</h2>187</h2>

188 188 

statusline.md +63 −21

Details

15* 여러 세션에서 작업하고 이들을 구분해야 하는 경우15* 여러 세션에서 작업하고 이들을 구분해야 하는 경우

16* git 브랜치 및 상태를 항상 표시하려는 경우16* git 브랜치 및 상태를 항상 표시하려는 경우

17 17 

18Claude Code는 또한 [바닥글 링크 배지](/ko/settings#footer-link-badges)를 렌더링할 수 있습니다: 구성된 정규식이 대화의 텍스트와 일치할 때 바닥글에 나타나는 클릭 가능한 칩입니다. 이는 상태 표시줄과 독립적이며 스크립트와 상호작용하지 않습니다. 대신 [`footerLinksRegexes`](/ko/settings#footer-link-badges) 설정으로 구성합니다.

19 

18다음은 첫 번째 줄에 git 정보를 표시하고 두 번째 줄에 색상으로 구분된 컨텍스트 막대를 표시하는 [다중 줄 상태 표시줄](#display-multiple-lines)의 예입니다.20다음은 첫 번째 줄에 git 정보를 표시하고 두 번째 줄에 색상으로 구분된 컨텍스트 막대를 표시하는 [다중 줄 상태 표시줄](#display-multiple-lines)의 예입니다.

19 21 

20<Frame>22<Frame>


23 25 

24이 페이지는 [기본 상태 표시줄 설정](#set-up-a-status-line)을 안내하고, [데이터 흐름](#how-status-lines-work)이 Claude Code에서 스크립트로 어떻게 흐르는지 설명하며, [표시할 수 있는 모든 필드](#available-data)를 나열하고, git 상태, 비용 추적 및 진행률 표시줄과 같은 일반적인 패턴에 대한 [즉시 사용 가능한 예제](#examples)를 제공합니다.26이 페이지는 [기본 상태 표시줄 설정](#set-up-a-status-line)을 안내하고, [데이터 흐름](#how-status-lines-work)이 Claude Code에서 스크립트로 어떻게 흐르는지 설명하며, [표시할 수 있는 모든 필드](#available-data)를 나열하고, git 상태, 비용 추적 및 진행률 표시줄과 같은 일반적인 패턴에 대한 [즉시 사용 가능한 예제](#examples)를 제공합니다.

25 27 

26## 상태 표시줄 설정28<h2 id="set-up-a-status-line">

29 상태 표시줄 설정

30</h2>

27 31 

28[`/statusline` 명령](#use-the-%2Fstatusline-command)을 사용하여 Claude Code가 스크립트를 생성하도록 하거나, [수동으로 스크립트를 만들고](#manually-configure-a-status-line) 설정에 추가합니다.32[`/statusline` 명령](#use-the-%2Fstatusline-command)을 사용하여 Claude Code가 스크립트를 생성하도록 하거나, [수동으로 스크립트를 만들고](#manually-configure-a-status-line) 설정에 추가합니다.

29 33 

30### /statusline 명령 사용34<h3 id="use-the-/statusline-command">

35 /statusline 명령 사용

36</h3>

31 37 

32`/statusline` 명령은 표시하려는 내용을 설명하는 자연어 지시사항을 허용합니다. Claude Code는 `~/.claude/` 디렉토리에 스크립트 파일을 생성하고 설정을 자동으로 업데이트합니다:38`/statusline` 명령은 표시하려는 내용을 설명하는 자연어 지시사항을 허용합니다. Claude Code는 `~/.claude/` 디렉토리에 스크립트 파일을 생성하고 설정을 자동으로 업데이트합니다:

33 39 


35/statusline show model name and context percentage with a progress bar41/statusline show model name and context percentage with a progress bar

36```42```

37 43 

38### 상태 표시줄 수동 구성44<h3 id="manually-configure-a-status-line">

45 상태 표시줄 수동 구성

46</h3>

39 47 

40사용자 설정(`~/.claude/settings.json`, 여기서 `~`는 홈 디렉토리) 또는 [프로젝트 설정](/ko/settings#settings-files)에 `statusLine` 필드를 추가합니다. `type`을 `"command"`로 설정하고 `command`를 스크립트 경로 또는 인라인 셸 명령으로 지정합니다. 스크립트 생성에 대한 전체 설명은 [상태 표시줄 단계별 구축](#build-a-status-line-step-by-step)을 참조하세요.48사용자 설정(`~/.claude/settings.json`, 여기서 `~`는 홈 디렉토리) 또는 [프로젝트 설정](/ko/settings#settings-files)에 `statusLine` 필드를 추가합니다. `type`을 `"command"`로 설정하고 `command`를 스크립트 경로 또는 인라인 셸 명령으로 지정합니다. 스크립트 생성에 대한 전체 설명은 [상태 표시줄 단계별 구축](#build-a-status-line-step-by-step)을 참조하세요.

41 49 


66 74 

67선택적 `hideVimModeIndicator` 필드는 프롬프트 아래의 기본 제공 `-- INSERT --` 텍스트를 숨깁니다. 스크립트가 [`vim.mode`](#available-data) 자체를 렌더링할 때 이를 `true`로 설정하여 모드가 두 번 표시되지 않도록 합니다.75선택적 `hideVimModeIndicator` 필드는 프롬프트 아래의 기본 제공 `-- INSERT --` 텍스트를 숨깁니다. 스크립트가 [`vim.mode`](#available-data) 자체를 렌더링할 때 이를 `true`로 설정하여 모드가 두 번 표시되지 않도록 합니다.

68 76 

69### 상태 표시줄 비활성화77<h3 id="disable-the-status-line">

78 상태 표시줄 비활성화

79</h3>

70 80 

71`/statusline`을 실행하고 상태 표시줄을 제거하거나 지우도록 요청합니다(예: `/statusline delete`, `/statusline clear`, `/statusline remove it`). settings.json에서 `statusLine` 필드를 수동으로 삭제할 수도 있습니다.81`/statusline`을 실행하고 상태 표시줄을 제거하거나 지우도록 요청합니다(예: `/statusline delete`, `/statusline clear`, `/statusline remove it`). settings.json에서 `statusLine` 필드를 수동으로 삭제할 수도 있습니다.

72 82 

73## 상태 표시줄 단계별 구축83<h2 id="build-a-status-line-step-by-step">

84 상태 표시줄 단계별 구축

85</h2>

74 86 

75이 설명서는 현재 모델, 작업 디렉토리 및 컨텍스트 윈도우 사용량 백분율을 표시하는 상태 표시줄을 수동으로 만들어 내부 동작을 보여줍니다.87이 설명서는 현재 모델, 작업 디렉토리 및 컨텍스트 윈도우 사용량 백분율을 표시하는 상태 표시줄을 수동으로 만들어 내부 동작을 보여줍니다.

76 88 

77<Note>[`/statusline`](#use-the-statusline-command)을 원하는 내용 설명과 함께 실행하면 이 모든 것이 자동으로 구성됩니다.</Note>89<Note>[`/statusline`](#use-the-%2Fstatusline-command)을 원하는 내용 설명과 함께 실행하면 이 모든 것이 자동으로 구성됩니다.</Note>

78 90 

79이 예제는 macOS 및 Linux에서 작동하는 Bash 스크립트를 사용합니다. Windows에서는 [Windows 구성](#windows-configuration)을 참조하여 PowerShell 및 Git Bash 예제를 확인하세요.91이 예제는 macOS 및 Linux에서 작동하는 Bash 스크립트를 사용합니다. Windows에서는 [Windows 구성](#windows-configuration)을 참조하여 PowerShell 및 Git Bash 예제를 확인하세요.

80 92 


128 </Step>140 </Step>

129</Steps>141</Steps>

130 142 

131## 상태 표시줄 작동 방식143<h2 id="how-status-lines-work">

144 상태 표시줄 작동 방식

145</h2>

132 146 

133Claude Code는 스크립트를 실행하고 stdin을 통해 [JSON 세션 데이터](#available-data)를 파이프합니다. 스크립트는 JSON을 읽고 필요한 것을 추출한 다음 stdout에 텍스트를 인쇄합니다. Claude Code는 스크립트가 인쇄하는 모든 것을 표시합니다.147Claude Code는 스크립트를 실행하고 stdin을 통해 [JSON 세션 데이터](#available-data)를 파이프합니다. 스크립트는 JSON을 읽고 필요한 것을 추출한 다음 stdout에 텍스트를 인쇄합니다. Claude Code는 스크립트가 인쇄하는 모든 것을 표시합니다.

134 148 


150 164 

151<Note>상태 표시줄은 로컬에서 실행되며 API 토큰을 소비하지 않습니다. 자동 완성 제안, 도움말 메뉴 및 권한 프롬프트를 포함한 특정 UI 상호 작용 중에 일시적으로 숨겨집니다.</Note>165<Note>상태 표시줄은 로컬에서 실행되며 API 토큰을 소비하지 않습니다. 자동 완성 제안, 도움말 메뉴 및 권한 프롬프트를 포함한 특정 UI 상호 작용 중에 일시적으로 숨겨집니다.</Note>

152 166 

153## 사용 가능한 데이터167<h2 id="available-data">

168 사용 가능한 데이터

169</h2>

154 170 

155Claude Code는 stdin을 통해 스크립트에 다음 JSON 필드를 보냅니다:171Claude Code는 stdin을 통해 스크립트에 다음 JSON 필드를 보냅니다:

156 172 


297 스크립트에서 조건부 액세스로 누락된 필드를 처리하고 null 값을 폴백 기본값으로 처리합니다.313 스크립트에서 조건부 액세스로 누락된 필드를 처리하고 null 값을 폴백 기본값으로 처리합니다.

298</Accordion>314</Accordion>

299 315 

300### 컨텍스트 윈도우 필드316<h3 id="context-window-fields">

317 컨텍스트 윈도우 필드

318</h3>

301 319 

302`context_window` 객체는 가장 최근 API 응답의 라이브 컨텍스트 윈도우를 설명합니다. v2.1.132부터 `total_input_tokens` 및 `total_output_tokens`는 누적 세션 합계가 아닌 현재 컨텍스트 사용량을 반영합니다.320`context_window` 객체는 가장 최근 API 응답의 라이브 컨텍스트 윈도우를 설명합니다. v2.1.132부터 `total_input_tokens` 및 `total_output_tokens`는 누적 세션 합계가 아닌 현재 컨텍스트 사용량을 반영합니다.

303 321 


319 337 

320`current_usage` 객체는 세션의 첫 번째 API 호출 전에 `null`이고, `/compact` 직후에 다시 `null`이 되었다가 다음 API 호출이 이를 다시 채울 때까지 유지됩니다.338`current_usage` 객체는 세션의 첫 번째 API 호출 전에 `null`이고, `/compact` 직후에 다시 `null`이 되었다가 다음 API 호출이 이를 다시 채울 때까지 유지됩니다.

321 339 

322## 예제340<h2 id="examples">

341 예제

342</h2>

323 343 

324이 예제는 일반적인 상태 표시줄 패턴을 보여줍니다. 예제를 사용하려면:344이 예제는 일반적인 상태 표시줄 패턴을 보여줍니다. 예제를 사용하려면:

325 345 


329 349 

330Bash 예제는 [`jq`](https://jqlang.github.io/jq/)를 사용하여 JSON을 구문 분석합니다. Python 및 Node.js는 기본 제공 JSON 구문 분석을 가집니다.350Bash 예제는 [`jq`](https://jqlang.github.io/jq/)를 사용하여 JSON을 구문 분석합니다. Python 및 Node.js는 기본 제공 JSON 구문 분석을 가집니다.

331 351 

332### 컨텍스트 윈도우 사용량352<h3 id="context-window-usage">

353 컨텍스트 윈도우 사용량

354</h3>

333 355 

334현재 모델과 컨텍스트 윈도우 사용량을 시각적 진행률 표시줄과 함께 표시합니다. 각 스크립트는 stdin에서 JSON을 읽고, `used_percentage` 필드를 추출하고, 채워진 블록(▓)이 사용량을 나타내는 10자 막대를 구축합니다:356현재 모델과 컨텍스트 윈도우 사용량을 시각적 진행률 표시줄과 함께 표시합니다. 각 스크립트는 stdin에서 JSON을 읽고, `used_percentage` 필드를 추출하고, 채워진 블록(▓)이 사용량을 나타내는 10자 막대를 구축합니다:

335 357 


396 ```418 ```

397</CodeGroup>419</CodeGroup>

398 420 

399### 색상이 있는 git 상태421<h3 id="git-status-with-colors">

422 색상이 있는 git 상태

423</h3>

400 424 

401색상으로 구분된 스테이징 및 수정된 파일 표시기가 있는 git 브랜치를 표시합니다. 이 스크립트는 터미널 색상에 [ANSI 이스케이프 코드](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors)를 사용합니다: `\033[32m`은 녹색, `\033[33m`은 노란색, `\033[0m`은 기본값으로 재설정합니다.425색상으로 구분된 스테이징 및 수정된 파일 표시기가 있는 git 브랜치를 표시합니다. 이 스크립트는 터미널 색상에 [ANSI 이스케이프 코드](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors)를 사용합니다: `\033[32m`은 녹색, `\033[33m`은 노란색, `\033[0m`은 기본값으로 재설정합니다.

402 426 


490 ```514 ```

491</CodeGroup>515</CodeGroup>

492 516 

493### 비용 및 기간 추적517<h3 id="cost-and-duration-tracking">

518 비용 및 기간 추적

519</h3>

494 520 

495세션의 API 비용 및 경과 시간을 추적합니다. `cost.total_cost_usd` 필드는 현재 세션의 모든 API 호출 비용을 누적합니다. `cost.total_duration_ms` 필드는 세션 시작 이후의 총 경과 시간을 측정하는 반면, `cost.total_api_duration_ms`는 API 응답 대기에 소비된 시간만 추적합니다.521세션의 API 비용 및 경과 시간을 추적합니다. `cost.total_cost_usd` 필드는 현재 세션의 모든 API 호출 비용을 누적합니다. `cost.total_duration_ms` 필드는 세션 시작 이후의 총 경과 시간을 측정하는 반면, `cost.total_api_duration_ms`는 API 응답 대기에 소비된 시간만 추적합니다.

496 522 


551 ```577 ```

552</CodeGroup>578</CodeGroup>

553 579 

554### 여러 줄 표시580<h3 id="display-multiple-lines">

581 여러 줄 표시

582</h3>

555 583 

556스크립트는 여러 줄을 출력하여 더 풍부한 디스플레이를 만들 수 있습니다. 각 `echo` 문은 상태 영역에서 별도의 행을 생성합니다.584스크립트는 여러 줄을 출력하여 더 풍부한 디스플레이를 만들 수 있습니다. 각 `echo` 문은 상태 영역에서 별도의 행을 생성합니다.

557 585 


658 ```686 ```

659</CodeGroup>687</CodeGroup>

660 688 

661### 클릭 가능한 링크689<h3 id="clickable-links">

690 클릭 가능한 링크

691</h3>

662 692 

663이 예제는 GitHub 저장소에 대한 클릭 가능한 링크를 만듭니다. git 원격 URL을 읽고, `sed`를 사용하여 SSH 형식을 HTTPS로 변환하고, 저장소 이름을 OSC 8 이스케이프 코드로 래핑합니다. Cmd(macOS) 또는 Ctrl(Windows/Linux)을 누르고 클릭하여 브라우저에서 링크를 엽니다.693이 예제는 GitHub 저장소에 대한 클릭 가능한 링크를 만듭니다. git 원격 URL을 읽고, `sed`를 사용하여 SSH 형식을 HTTPS로 변환하고, 저장소 이름을 OSC 8 이스케이프 코드로 래핑합니다. Cmd(macOS) 또는 Ctrl(Windows/Linux)을 누르고 클릭하여 브라우저에서 링크를 엽니다.

664 694 


738 ```768 ```

739</CodeGroup>769</CodeGroup>

740 770 

741### 속도 제한 사용량771<h3 id="rate-limit-usage">

772 속도 제한 사용량

773</h3>

742 774 

743Claude.ai 구독 속도 제한 사용량을 상태 표시줄에 표시합니다. `rate_limits` 객체에는 `five_hour`(5시간 롤링 윈도우) 및 `seven_day`(주간) 윈도우가 포함됩니다. 각 윈도우는 `used_percentage`(0-100) 및 `resets_at`(윈도우가 재설정되는 Unix epoch 초)를 제공합니다.775Claude.ai 구독 속도 제한 사용량을 상태 표시줄에 표시합니다. `rate_limits` 객체에는 `five_hour`(5시간 롤링 윈도우) 및 `seven_day`(주간) 윈도우가 포함됩니다. 각 윈도우는 `used_percentage`(0-100) 및 `resets_at`(윈도우가 재설정되는 Unix epoch 초)를 제공합니다.

744 776 


804 ```836 ```

805</CodeGroup>837</CodeGroup>

806 838 

807### 비용이 많이 드는 작업 캐싱839<h3 id="cache-expensive-operations">

840 비용이 많이 드는 작업 캐싱

841</h3>

808 842 

809상태 표시줄 스크립트는 활성 세션 중에 자주 실행됩니다. `git status` 또는 `git diff`와 같은 명령은 특히 큰 저장소에서 느릴 수 있습니다. 이 예제는 git 정보를 임시 파일에 캐싱하고 5초마다만 새로 고칩니다.843상태 표시줄 스크립트는 활성 세션 중에 자주 실행됩니다. `git status` 또는 `git diff`와 같은 명령은 특히 큰 저장소에서 느릴 수 있습니다. 이 예제는 git 정보를 임시 파일에 캐싱하고 5초마다만 새로 고칩니다.

810 844 


935 ```969 ```

936</CodeGroup>970</CodeGroup>

937 971 

938### Windows 구성972<h3 id="windows-configuration">

973 Windows 구성

974</h3>

939 975 

940Windows에서 Claude Code는 Git Bash가 설치되어 있을 때 Git Bash를 통해 상태 표시줄 명령을 실행하거나, Git Bash가 없을 때 PowerShell을 통해 실행합니다.976Windows에서 Claude Code는 Git Bash가 설치되어 있을 때 Git Bash를 통해 상태 표시줄 명령을 실행하거나, Git Bash가 없을 때 PowerShell을 통해 실행합니다.

941 977 


990 ```1026 ```

991</CodeGroup>1027</CodeGroup>

992 1028 

993## 서브에이전트 상태 표시줄1029<h2 id="subagent-status-lines">

1030 서브에이전트 상태 표시줄

1031</h2>

994 1032 

995`subagentStatusLine` 설정은 [서브에이전트](/ko/sub-agents) 패널에 표시된 각 서브에이전트에 대한 사용자 정의 행 본문을 렌더링합니다. 기본 `name · description · token count` 행을 자신의 형식으로 바꾸는 데 사용합니다.1033`subagentStatusLine` 설정은 [서브에이전트](/ko/sub-agents) 패널에 표시된 각 서브에이전트에 대한 사용자 정의 행 본문을 렌더링합니다. 기본 `name · description · token count` 행을 자신의 형식으로 바꾸는 데 사용합니다.

996 1034 


1009 1047 

1010`statusLine`에 적용되는 동일한 신뢰 및 `disableAllHooks` 게이트가 여기에 적용됩니다. 플러그인은 [`settings.json`](/ko/plugins-reference#standard-plugin-layout)에서 기본 `subagentStatusLine`을 제공할 수 있습니다.1048`statusLine`에 적용되는 동일한 신뢰 및 `disableAllHooks` 게이트가 여기에 적용됩니다. 플러그인은 [`settings.json`](/ko/plugins-reference#standard-plugin-layout)에서 기본 `subagentStatusLine`을 제공할 수 있습니다.

1011 1049 

1012## 1050<h2 id="tips">

1051

1052</h2>

1013 1053 

1014* **모의 입력으로 테스트**: `echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25},"session_id":"test-session-abc"}' | ./statusline.sh`1054* **모의 입력으로 테스트**: `echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25},"session_id":"test-session-abc"}' | ./statusline.sh`

1015* **출력을 짧게 유지**: 상태 표시줄의 너비가 제한되어 있으므로 긴 출력이 잘리거나 어색하게 줄 바꿈될 수 있습니다1055* **출력을 짧게 유지**: 상태 표시줄의 너비가 제한되어 있으므로 긴 출력이 잘리거나 어색하게 줄 바꿈될 수 있습니다


1017 1057 

1018[ccstatusline](https://github.com/sirmalloc/ccstatusline) 및 [starship-claude](https://github.com/martinemde/starship-claude)와 같은 커뮤니티 프로젝트는 테마 및 추가 기능이 있는 사전 구축된 구성을 제공합니다.1058[ccstatusline](https://github.com/sirmalloc/ccstatusline) 및 [starship-claude](https://github.com/martinemde/starship-claude)와 같은 커뮤니티 프로젝트는 테마 및 추가 기능이 있는 사전 구축된 구성을 제공합니다.

1019 1059 

1020## 문제 해결1060<h2 id="troubleshooting">

1061 문제 해결

1062</h2>

1021 1063 

1022**상태 표시줄이 나타나지 않음**1064**상태 표시줄이 나타나지 않음**

1023 1065 

sub-agents.md +48 −18

Details

61 * **도구**: 읽기 전용 도구 (Write 및 Edit 도구에 대한 액세스 거부)61 * **도구**: 읽기 전용 도구 (Write 및 Edit 도구에 대한 액세스 거부)

62 * **목적**: 계획을 위한 코드베이스 연구62 * **목적**: 계획을 위한 코드베이스 연구

63 63 

64 plan mode에 있고 Claude가 코드베이스를 이해해야 할 때 연구를 Plan subagent에 위임합니다. 이렇게 하면 무한 중첩을 방지하면서(subagent는 다른 subagent를 생성할 없음) 필요한 컨텍스트를 수집합니다.64 plan mode에 있고 Claude가 코드베이스를 이해해야 할 때 연구를 Plan subagent에 위임하므로 탐색 출력이 별도의 컨텍스트 윈도우에 유지되고 대화는 읽기 전용으로 유지됩니다.

65 </Tab>65 </Tab>

66 66 

67 <Tab title="General-purpose">67 <Tab title="General-purpose">


84 </Tab>84 </Tab>

85</Tabs>85</Tabs>

86 86 

87내장 subagent는 항상 대화형 세션에 등록됩니다. 특정 내장 유형을 차단하려면 [특정 subagent 비활성화](#disable-specific-subagents)에 표시된 대로 `permissions.deny`에 추가하십시오. Claude가 어떤 subagent에도 위임하는 것을 방지하려면 [`permissions.deny`](/ko/permissions#tool-specific-permission-rules)를 사용하여 `Agent` 도구 자체를 거부하십시오. [비대화형 모드](/ko/headless) 및 [Agent SDK](/ko/agent-sdk/overview)에서는 [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/ko/env-vars)을 설정하여 모든 내장 유형을 제거하고 자신의 것만 제공하십시오.

88 

87이러한 내장 subagent 외에도 사용자 정의 프롬프트, 도구 제한, 권한 모드, hooks 및 skills를 사용하여 자신의 subagent를 만들 수 있습니다. 다음 섹션에서는 시작하는 방법과 subagent를 사용자 정의하는 방법을 보여줍니다.89이러한 내장 subagent 외에도 사용자 정의 프롬프트, 도구 제한, 권한 모드, hooks 및 skills를 사용하여 자신의 subagent를 만들 수 있습니다. 다음 섹션에서는 시작하는 방법과 subagent를 사용자 정의하는 방법을 보여줍니다.

88 90 

89<h2 id="quickstart-create-your-first-subagent">91<h2 id="quickstart-create-your-first-subagent">


158 /agents 명령 사용160 /agents 명령 사용

159</h3>161</h3>

160 162 

161`/agents` 명령은 subagent를 관리하기 위한 탭 인터페이스를 엽니다. **Running** 탭은 라이브 subagent를 표시하고 열거나 중지할 수 있습니다. **Library** 탭을 사용하면 다음을 수행할 수 있습니다:163`/agents` 명령은 subagent를 관리하기 위한 탭 인터페이스를 엽니다. **Running** 탭은 라이브 및 최근에 완료된 subagent를 나열하고 열거나 중지할 수 있습니다. **Library** 탭을 사용하면 다음을 수행할 수 있습니다:

162 164 

163* 사용 가능한 모든 subagent 보기 (내장, 사용자, 프로젝트, 플러그인)165* 사용 가능한 모든 subagent 보기 (내장, 사용자, 프로젝트, 플러그인)

164* 안내된 설정 또는 Claude 생성으로 새 subagent 만들기166* 안내된 설정 또는 Claude 생성으로 새 subagent 만들기


184 186 

185**프로젝트 subagent** (`.claude/agents/`)는 코드베이스에 특정한 subagent에 이상적입니다. 버전 제어에 체크인하여 팀이 협력하여 사용하고 개선할 수 있습니다.187**프로젝트 subagent** (`.claude/agents/`)는 코드베이스에 특정한 subagent에 이상적입니다. 버전 제어에 체크인하여 팀이 협력하여 사용하고 개선할 수 있습니다.

186 188 

187프로젝트 subagent는 현재 작업 디렉토리에서 위로 이동하여 검색됩니다. `--add-dir` 추가된 디렉토리는 [파일 액세스만 부여](/ko/permissions#additional-directories-grant-file-access-not-configuration)하며 subagent를 검색하지 않습니다. 프로젝트 간에 subagent를 공유하려면 `~/.claude/agents/` 사용하거나 [플러그인](/ko/plugins)을 사용합니다.189프로젝트 subagent는 현재 작업 디렉토리에서 위로 이동하여 검색되므로 거기서 저장소 루트까지의 모든 `.claude/agents/` 스캔됩니다. {/* min-version: 2.1.178 */}v2.1.178부터 이러한 중첩된 디렉토리 하나 이상이 동일한 `name` 정의할 Claude Code는 작업 디렉토리에 가장 가까운 정의를 사용합니다.

190 

191`--add-dir`로 추가된 디렉토리도 스캔됩니다: 추가된 디렉토리 내의 `.claude/agents/` 폴더는 프로젝트 subagent와 함께 로드됩니다. 다른 구성 유형이 `--add-dir`에서 로드되는 것에 대해서는 [추가 디렉토리](/ko/permissions#additional-directories-grant-file-access-not-configuration)를 참조하세요. `--add-dir` 없이 프로젝트 간에 subagent를 공유하려면 `~/.claude/agents/`를 사용하거나 [플러그인](/ko/plugins)을 사용합니다.

188 192 

189**사용자 subagent** (`~/.claude/agents/`)는 모든 프로젝트에서 사용 가능한 개인 subagent입니다.193**사용자 subagent** (`~/.claude/agents/`)는 모든 프로젝트에서 사용 가능한 개인 subagent입니다.

190 194 


282| `description` | 예 | Claude가 이 subagent에 위임해야 할 때 |286| `description` | 예 | Claude가 이 subagent에 위임해야 할 때 |

283| `tools` | 아니오 | [도구](#available-tools) subagent가 사용할 수 있습니다. 생략하면 모든 도구 상속. Skills를 컨텍스트에 미리 로드하려면 여기에 `Skill`을 나열하는 대신 `skills` 필드를 사용합니다 |287| `tools` | 아니오 | [도구](#available-tools) subagent가 사용할 수 있습니다. 생략하면 모든 도구 상속. Skills를 컨텍스트에 미리 로드하려면 여기에 `Skill`을 나열하는 대신 `skills` 필드를 사용합니다 |

284| `disallowedTools` | 아니오 | 거부할 도구, 상속되거나 지정된 목록에서 제거됨 |288| `disallowedTools` | 아니오 | 거부할 도구, 상속되거나 지정된 목록에서 제거됨 |

285| `model` | 아니오 | 사용할 [모델](#choose-a-model): `sonnet`, `opus`, `haiku`, 전체 모델 ID (예: `claude-opus-4-8`), 또는 `inherit`. 기본값: `inherit` |289| `model` | 아니오 | 사용할 [모델](#choose-a-model): `sonnet`, `opus`, `haiku`, `fable`, 전체 모델 ID (예: `claude-opus-4-8`), 또는 `inherit`. 기본값: `inherit` |

286| `permissionMode` | 아니오 | [권한 모드](#permission-modes): `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, 또는 `plan`. [플러그인 subagent](#choose-the-subagent-scope)에서는 무시됨 |290| `permissionMode` | 아니오 | [권한 모드](#permission-modes): `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, 또는 `plan`. [플러그인 subagent](#choose-the-subagent-scope)에서는 무시됨 |

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

288| `skills` | 아니오 | 시작 시 subagent의 컨텍스트에 로드할 [Skills](/ko/skills). 전체 skill 콘텐츠가 주입되며, 호출 가능하게 만들어지는 것이 아닙니다. Subagent는 여전히 Skill 도구를 통해 나열되지 않은 프로젝트, 사용자, 플러그인 skills를 호출할 수 있습니다 |292| `skills` | 아니오 | 시작 시 subagent의 컨텍스트에 로드할 [Skills](/ko/skills). 전체 skill 콘텐츠가 주입되며, 호출 가능하게 만들어지는 것이 아닙니다. Subagent는 여전히 Skill 도구를 통해 나열되지 않은 프로젝트, 사용자, 플러그인 skills를 호출할 수 있습니다 |


301 305 

302`model` 필드는 subagent가 사용하는 [AI 모델](/ko/model-config)을 제어합니다:306`model` 필드는 subagent가 사용하는 [AI 모델](/ko/model-config)을 제어합니다:

303 307 

304* **모델 별칭**: 사용 가능한 별칭 중 하나를 사용합니다: `sonnet`, `opus`, 또는 `haiku`308* **모델 별칭**: 사용 가능한 별칭 중 하나를 사용합니다: `sonnet`, `opus`, `haiku`, 또는 `fable`

305* **전체 모델 ID**: `claude-opus-4-8` 또는 `claude-sonnet-4-6`과 같은 전체 모델 ID를 사용합니다. `--model` 플래그와 동일한 값을 허용합니다309* **전체 모델 ID**: `claude-opus-4-8` 또는 `claude-sonnet-4-6`과 같은 전체 모델 ID를 사용합니다. `--model` 플래그와 동일한 값을 허용합니다

306* **inherit**: 주 대화와 동일한 모델을 사용합니다310* **inherit**: 주 대화와 동일한 모델을 사용합니다

307* **생략됨**: 지정하지 않으면 기본값은 `inherit`입니다 (주 대화와 동일한 모델 사용)311* **생략됨**: 지정하지 않으면 기본값은 `inherit`입니다 (주 대화와 동일한 모델 사용)


325 329 

326Subagent는 기본적으로 주 대화에서 사용 가능한 [내부 도구](/ko/tools-reference) 및 MCP 도구를 상속합니다. 다음 도구는 주 대화의 UI 또는 세션 상태에 따라 달라지며 `tools` 필드에 나열되어 있어도 subagent에서 사용할 수 없습니다:330Subagent는 기본적으로 주 대화에서 사용 가능한 [내부 도구](/ko/tools-reference) 및 MCP 도구를 상속합니다. 다음 도구는 주 대화의 UI 또는 세션 상태에 따라 달라지며 `tools` 필드에 나열되어 있어도 subagent에서 사용할 수 없습니다:

327 331 

328* `Agent`

329* `AskUserQuestion`332* `AskUserQuestion`

330* `EnterPlanMode`333* `EnterPlanMode`

331* `ExitPlanMode` (subagent의 [`permissionMode`](#permission-modes)가 `plan`인 경우 제외)334* `ExitPlanMode` (subagent의 [`permissionMode`](#permission-modes)가 `plan`인 경우 제외)


354 357 

355둘 다 설정되면 `disallowedTools`가 먼저 적용되고 `tools`가 남은 풀에 대해 해결됩니다. 둘 다에 나열된 도구는 제거됩니다.358둘 다 설정되면 `disallowedTools`가 먼저 적용되고 `tools`가 남은 풀에 대해 해결됩니다. 둘 다에 나열된 도구는 제거됩니다.

356 359 

360두 필드 모두 정확한 도구 이름 외에도 MCP 서버 수준 패턴을 허용합니다: `mcp__<server>` 또는 `mcp__<server>__*`는 명명된 서버의 모든 도구를 부여하거나 제거합니다. `disallowedTools`에서 `mcp__*`는 모든 서버의 모든 MCP 도구를 제거합니다. 이 예제는 `github` MCP 서버의 모든 도구를 제거하면서 다른 서버의 도구와 모든 내장 도구를 유지합니다:

361 

362```yaml theme={null}

363---

364name: local-only

365description: Inherits every tool except those from the github MCP server

366disallowedTools: mcp__github

367---

368```

369 

357<h4 id="restrict-which-subagents-can-be-spawned">370<h4 id="restrict-which-subagents-can-be-spawned">

358 생성할 수 있는 subagent 제한371 생성할 수 있는 subagent 제한

359</h4>372</h4>


378tools: Agent, Read, Bash391tools: Agent, Read, Bash

379```392```

380 393 

381`Agent`가 `tools` 목록에서 완전히 생략되면 에이전트는 subagent를 생성할 수 없습니다. 이 제한은 `claude --agent`를 사용하여 주 스레드로 실행되는 에이전트에만 적용됩니다. Subagent는 다른 subagent를 생성할 수 없으므로 `Agent(agent_type)`은 subagent 정의에서 효과가 없습니다.394`Agent`가 `tools` 목록에서 완전히 생략되면 에이전트는 subagent를 생성할 수 없습니다.

395 

396`Agent(agent_type)` 허용 목록 구문은 `claude --agent`를 사용하여 주 스레드로 실행되는 에이전트에만 적용됩니다. Subagent 정의에서 `tools`에 `Agent`를 나열하면 해당 subagent가 [중첩된 subagent를 생성](#spawn-nested-subagents)할 수 있지만 괄호 내의 모든 유형 목록은 무시됩니다.

382 397 

383<h4 id="scope-mcp-servers-to-a-subagent">398<h4 id="scope-mcp-servers-to-a-subagent">

384 Subagent에 MCP 서버 범위 지정399 Subagent에 MCP 서버 범위 지정


444| `plan` | Plan mode (읽기 전용 탐색) |459| `plan` | Plan mode (읽기 전용 탐색) |

445 460 

446<Warning>461<Warning>

447 `bypassPermissions`는 주의해서 사용하세요. 권한 프롬프트를 건너뛰어 subagent가 승인 없이 작업을 실행할 수 있습니다. `.git`, `.config/git`, `.claude`, `.vscode`, `.idea`, `.husky`, `.cargo`, `.devcontainer`, `.yarn`, `.mvn`에 대한 쓰기는 여전히 회로 차단기로 프롬프트합니다. 루트 및 홈 디렉토리 제거 (예: `rm -rf /`)는 여전히 회로 차단기로 프롬프트합니다. [권한 모드](/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)를 참조하세요.462 `bypassPermissions`는 주의해서 사용하세요. 권한 프롬프트를 건너뛰어 subagent가 승인 없이 작업을 실행할 수 있습니다. `.git`, `.config/git`, `.claude`, `.vscode`, `.idea`, `.husky`, `.cargo`, `.devcontainer`, `.yarn`, `.mvn`에 대한 쓰기를 포함하여 작업을 실행할 수 있습니다. 명시적 [`ask` 규칙](/ko/permissions#manage-permissions) 및 루트 및 홈 디렉토리 제거 (예: `rm -rf /`)는 여전히 프롬프트합니다. [권한 모드](/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)를 참조하세요.

448</Warning>463</Warning>

449 464 

450부모가 `bypassPermissions` 또는 `acceptEdits`를 사용하면 이것이 우선하며 재정의할 수 없습니다. 부모가 [auto mode](/ko/permission-modes#eliminate-prompts-with-auto-mode)를 사용하면 subagent는 auto mode를 상속하고 frontmatter의 모든 `permissionMode`는 무시됩니다: 분류기는 부모 세션과 동일한 차단 및 허용 규칙으로 subagent의 도구 호출을 평가합니다.465부모가 `bypassPermissions` 또는 `acceptEdits`를 사용하면 이것이 우선하며 재정의할 수 없습니다. 부모가 [auto mode](/ko/permission-modes#eliminate-prompts-with-auto-mode)를 사용하면 subagent는 auto mode를 상속하고 frontmatter의 모든 `permissionMode`는 무시됩니다: 분류기는 부모 세션과 동일한 차단 및 허용 규칙으로 subagent의 도구 호출을 평가합니다.


761 776 

762모든 background 작업 기능을 비활성화하려면 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 환경 변수를 `1`로 설정합니다. [환경 변수](/ko/env-vars)를 참조하세요.777모든 background 작업 기능을 비활성화하려면 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 환경 변수를 `1`로 설정합니다. [환경 변수](/ko/env-vars)를 참조하세요.

763 778 

764[`CLAUDE_CODE_FORK_SUBAGENT`](#fork-the-current-conversation)가 설정되면 `background` 필드와 관계없이 모든 subagent 생성이 background에서 실행됩니다. Fork는 여전히 터미널에서 발생하는 권한 프롬프트를 표시합니다. 명명된 subagent는 위에서 설명한 대로 모든 프롬프트를 자동으로 거부합니다.779[`CLAUDE_CODE_FORK_SUBAGENT`](#fork-the-current-conversation)가 `1`로 설정되면 `background` 필드와 관계없이 모든 subagent 생성이 background에서 실행됩니다. Fork는 여전히 터미널에서 발생하는 권한 프롬프트를 표시합니다. 명명된 subagent는 위에서 설명한 대로 모든 프롬프트를 자동으로 거부합니다.

765 780 

766<h3 id="common-patterns">781<h3 id="common-patterns">

767 일반적인 패턴782 일반적인 패턴


826 841 

827대화에 이미 있는 항목에 대한 빠른 질문의 경우 subagent 대신 [`/btw`](/ko/interactive-mode#side-questions-with-%2Fbtw)를 사용합니다. 전체 컨텍스트를 보지만 도구 액세스가 없으며 답변은 기록에 추가되지 않습니다.842대화에 이미 있는 항목에 대한 빠른 질문의 경우 subagent 대신 [`/btw`](/ko/interactive-mode#side-questions-with-%2Fbtw)를 사용합니다. 전체 컨텍스트를 보지만 도구 액세스가 없으며 답변은 기록에 추가되지 않습니다.

828 843 

829<Note>844<h3 id="spawn-nested-subagents">

830 Subagent는 다른 subagent를 생성할 수 없습니다. 워크플로우가 중첩된 위임이 필요한 경우 [Skills](/ko/skills) 또는 주 대화에서 [subagent 체인](#chain-subagents)을 사용합니다.845 중첩된 subagent 생성

831</Note>846</h3>

847 

848{/* min-version: 2.1.172 */}Claude Code v2.1.172부터 subagent는 자신의 subagent를 생성할 수 있습니다. 위임된 작업이 자체적으로 병렬 하위 작업으로 분할될 때 이를 사용합니다. 예를 들어 각 발견에 대해 검증자를 발송하는 검토자 subagent를 사용하면 중간 출력이 주 대화에 도달하지 않습니다. 최상위 subagent의 요약만 사용자에게 반환됩니다.

849 

850중첩된 subagent는 최상위 subagent와 동일한 방식으로 구성되며 동일한 [범위](#choose-the-subagent-scope)에서 해결됩니다. 프롬프트 입력 아래의 subagent 패널은 전체 트리를 표시합니다: 각 행은 하위 항목의 `(+N)` 개수를 표시하고, 행을 열면 해당 subagent의 직접 자식이 `main`으로 돌아가는 경로와 함께 표시됩니다. [`/agents`](#use-the-%2Fagents-command)의 Running 탭은 실행 중인 subagent를 평면 목록으로 나열합니다.

851 

852깊이는 각 수준이 [foreground 또는 background](#run-subagents-in-foreground-or-background)에서 실행되는지 여부와 관계없이 주 대화 아래의 subagent 수준 수로 계산됩니다:

853 

854* **Foreground subagent**: 모든 깊이에서 생성할 수 있습니다. 각 수준은 반환될 때까지 부모를 차단하므로 체인은 자체 제한됩니다: 주 대화는 전체 체인을 기다립니다.

855* **Background subagent**: 깊이 5의 background subagent는 Agent 도구를 받지 않으며 추가로 생성할 수 없습니다. 제한은 고정되어 있으며 구성할 수 없으며 실행 중인 동시 트리를 방지하기 위해 존재합니다.

856 

857특정 subagent가 다른 subagent를 생성하지 못하도록 하려면 [`tools`](#available-tools) 목록에서 `Agent`를 생략하거나 `disallowedTools`에 추가합니다.

858 

859[fork](#fork-the-current-conversation)는 여전히 다른 fork를 생성할 수 없습니다. 다른 subagent 유형을 생성할 수 있으며 깊이 제한에 포함됩니다.

832 860 

833<h3 id="manage-subagent-context">861<h3 id="manage-subagent-context">

834 Subagent 컨텍스트 관리862 Subagent 컨텍스트 관리


860 888 

861재개된 subagent는 모든 이전 도구 호출, 결과 및 추론을 포함한 전체 대화 기록을 유지합니다. Subagent는 새로 시작하는 대신 정확히 중단한 위치에서 계속됩니다.889재개된 subagent는 모든 이전 도구 호출, 결과 및 추론을 포함한 전체 대화 기록을 유지합니다. Subagent는 새로 시작하는 대신 정확히 중단한 위치에서 계속됩니다.

862 890 

863Subagent가 완료되면 Claude는 에이전트 ID를 받습니다. Claude는 `SendMessage` 도구를 에이전트의 ID를 `to` 필드로 사용하여 재개합니다. `SendMessage` 도구는 [agent teams](/ko/agent-teams)가 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`을 통해 활성화될 때만 사용 가능합니다.891Subagent가 완료되면 Claude는 에이전트 ID를 받습니다. 내장 Explore 및 Plan 에이전트는 일회성이며 에이전트 ID를 반환하지 않으므로 재개할 수 없습니다. 작업을 계속해야 할 때는 `general-purpose` 또는 사용자 정의 subagent를 사용합니다. Claude는 에이전트의 ID를 `to` 필드로 사용하여 `SendMessage` 도구를 사용하여 재개합니다. `SendMessage` 도구는 [agent teams](/ko/agent-teams)가 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`을 통해 활성화될 때만 사용 가능합니다.

864 892 

865Subagent를 재개하려면 Claude에 이전 작업을 계속하도록 요청합니다:893Subagent를 재개하려면 Claude에 이전 작업을 계속하도록 요청합니다:

866 894 


886 자동 압축914 자동 압축

887</h4>915</h4>

888 916 

889Subagent는 주 대화와 동일한 논리를 사용하여 자동 압축을 지원합니다. 기본적으로 자동 압축은 약 95% 용량에서 트리거됩니다. 압축을 더 일찍 트리거하려면 `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`를 더 낮은 백분율 (예: `50`)로 설정합니다. 자세한 내용은 [환경 변수](/ko/env-vars)를 참조하세요.917Subagent는 주 대화와 동일한 논리를 사용하여 자동 압축을 지원합니다. 압축은 동일한 조건에서 트리거되며, `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` subagent에도 적용됩니다. 재정의가 적용되는 시기는 [환경 변수](/ko/env-vars)를 참조하세요.

890 918 

891압축 이벤트는 subagent 트랜스크립트 파일에 기록됩니다:919압축 이벤트는 subagent 트랜스크립트 파일에 기록됩니다:

892 920 


908</h2>936</h2>

909 937 

910<Note>938<Note>

911 포크된 subagent는 Claude Code v2.1.117 이상이 필요합니다. {/* min-version: 2.1.161 */}v2.1.161부터 `/fork` 명령은 기본적으로 활성화되어 있습니다. 이전 버전에서는 [`CLAUDE_CODE_FORK_SUBAGENT`](/ko/env-vars) 환경 변수를 `1`로 설정해야 합니다. 포크를 모델의 *기본* 생성 동작으로 만드는 것은 실험적이며 향후 릴리스에서 변경될 수 있습니다. 동일한 변수를 설정하여 활성화합니다. 변수는 대화형 모드 SDK 또는 `claude -p`를 통해 인정됩니다.939 포크된 subagent는 Claude Code v2.1.117 이상이 필요합니다. {/* min-version: 2.1.161 */}v2.1.161부터 `/fork` 명령은 기본적으로 활성화되어 있습니다. 이전 버전에서는 [`CLAUDE_CODE_FORK_SUBAGENT`](/ko/env-vars) 환경 변수를 `1`로 설정해야 합니다. Claude 자체가 포크를 생성하도록 하는 것은 실험적이며 향후 릴리스에서 변경될 수 있습니다. 이 기능은 단계적 롤아웃의 일부로 대화형 세션에서도 활성화될 있습니다.

912</Note>940</Note>

913 941 

914포크는 새로 시작하는 대신 지금까지의 전체 대화를 상속하는 subagent입니다. 이렇게 하면 subagent가 일반적으로 제공하는 입력 격리가 떨어집니다: 포크는 주 세션과 동일한 시스템 프롬프트, 도구, 모델 및 메시지 기록을 보므로 상황을 다시 설명할 필요 없이 부작업을 전달할 수 있습니다. 포크의 자체 도구 호출은 여전히 대화에서 벗어나고 최종 결과만 돌아오므로 주 컨텍스트 윈도우가 깨끗하게 유지됩니다. 명명된 subagent가 유용하기에는 너무 많은 배경이 필요하거나 동일한 시작점에서 여러 접근 방식을 병렬로 시도하려는 경우 포크를 사용합니다.942포크는 새로 시작하는 대신 지금까지의 전체 대화를 상속하는 subagent입니다. 이렇게 하면 subagent가 일반적으로 제공하는 입력 격리가 떨어집니다: 포크는 주 세션과 동일한 시스템 프롬프트, 도구, 모델 및 메시지 기록을 보므로 상황을 다시 설명할 필요 없이 부작업을 전달할 수 있습니다. 포크의 자체 도구 호출은 여전히 대화에서 벗어나고 최종 결과만 돌아오므로 주 컨텍스트 윈도우가 깨끗하게 유지됩니다. 명명된 subagent가 유용하기에는 너무 많은 배경이 필요하거나 동일한 시작점에서 여러 접근 방식을 병렬로 시도하려는 경우 포크를 사용합니다.

915 943 

916`CLAUDE_CODE_FORK_SUBAGENT` 설정은 Claude Code를 가지 방식으로 변경합니다:944단계적 롤아웃과 관계없이 포크 모드를 제어하려면 [`CLAUDE_CODE_FORK_SUBAGENT`](/ko/env-vars)를 `1`로 설정하여 명시적으로 활성화하거나 `0`으로 설정하여 비활성화합니다. 이 변수는 대화형 모드 및 SDK 또는 `claude -p`를 통해 인정됩니다.

945 

946포크 모드를 활성화하면 Claude Code가 두 가지 방식으로 변경됩니다:

917 947 

918* Claude는 [general-purpose](#built-in-subagents) subagent를 사용할 때마다 포크를 생성합니다. Explore와 같은 명명된 subagent는 이전과 같이 생성됩니다.948* Claude는 `fork` subagent 유형을 명시적으로 요청하여 포크를 생성할 수 있습니다. subagent 유형 없이 생성하는 경우 여전히 [general-purpose](#built-in-subagents) subagent를 사용하며, Explore와 같은 명명된 subagent는 이전과 같이 생성됩니다.

919* 모든 subagent 생성이 [background](#run-subagents-in-foreground-or-background)에서 실행됩니다. 포크든 명명된 subagent든 상관없습니다. 생성을 동기식으로 유지하려면 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`를 `1`로 설정합니다.949* 모든 subagent 생성이 [background](#run-subagents-in-foreground-or-background)에서 실행됩니다. 포크든 명명된 subagent든 상관없습니다. 생성을 동기식으로 유지하려면 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`를 `1`로 설정합니다.

920 950 

921변수 설정 여부와 관계없이 `/fork` 다음에 지시문을 사용하여 포크를 직접 시작할 수 있습니다. Claude Code는 지시문의 첫 단어에서 포크의 이름을 지정합니다. 다음 예제는 주 세션에서 구현을 계속하는 동안 포크가 테스트 케이스를 작성하도록 포크합니다:951변수 설정 여부와 관계없이 `/fork` 다음에 지시문을 사용하여 포크를 직접 시작할 수 있습니다. Claude Code는 지시문의 첫 단어에서 포크의 이름을 지정합니다. 다음 예제는 주 세션에서 구현을 계속하는 동안 포크가 테스트 케이스를 작성하도록 포크합니다:


961 제한 사항991 제한 사항

962</h3>992</h3>

963 993 

964`CLAUDE_CODE_FORK_SUBAGENT=1`을 설정하면 대화형 세션, [비대화형 모드](/ko/headless) 및 Agent SDK에서 포크 모드를 활성화합니다. 포크는 추가 포크를 생성할 수 없습니다.994`CLAUDE_CODE_FORK_SUBAGENT=1`을 설정하면 대화형 세션, [비대화형 모드](/ko/headless) 및 Agent SDK에서 포크 모드를 활성화합니다. `CLAUDE_CODE_FORK_SUBAGENT`를 `0`으로 설정하면 서버 측 롤아웃을 포함하여 모든 곳에서 포크 모드를 비활성화합니다. 포크는 추가 포크를 생성할 수 없습니다.

965 995 

966<h2 id="example-subagents">996<h2 id="example-subagents">

967 예제 subagent997 예제 subagent

Details

6 6 

7> Claude Code가 다양한 타사 서비스 및 인프라와 통합되어 엔터프라이즈 배포 요구사항을 충족하는 방법을 알아봅니다.7> Claude Code가 다양한 타사 서비스 및 인프라와 통합되어 엔터프라이즈 배포 요구사항을 충족하는 방법을 알아봅니다.

8 8 

9export const ContactSalesCard = ({surface}) => {

10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;

11 const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

12 <line x1="5" y1="12" x2="19" y2="12" />

13 <polyline points="12 5 19 12 12 19" />

14 </svg>;

15 const STYLES = `

16.cc-cs {

17 --cs-slate: #141413;

18 --cs-clay: #d97757;

19 --cs-clay-deep: #c6613f;

20 --cs-gray-000: #ffffff;

21 --cs-gray-700: #3d3d3a;

22 --cs-border-default: rgba(31, 30, 29, 0.15);

23 font-family: inherit;

24}

25.dark .cc-cs {

26 --cs-slate: #f0eee6;

27 --cs-gray-000: #262624;

28 --cs-gray-700: #bfbdb4;

29 --cs-border-default: rgba(240, 238, 230, 0.14);

30}

31.cc-cs-card {

32 display: flex; align-items: center; justify-content: space-between;

33 gap: 16px; padding: 14px 16px; margin: 0;

34 background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default);

35 border-radius: 8px; flex-wrap: wrap;

36}

37.cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; }

38.cc-cs-text strong { font-weight: 550; color: var(--cs-slate); }

39.cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }

40.cc-cs-btn-clay {

41 display: inline-flex; align-items: center; gap: 8px;

42 background: var(--cs-clay-deep); color: #fff; border: none;

43 border-radius: 8px; padding: 8px 14px;

44 font-size: 13px; font-weight: 500;

45 transition: background-color 0.15s; white-space: nowrap;

46}

47.cc-cs-btn-clay:hover { background: var(--cs-clay); }

48.cc-cs-btn-ghost {

49 display: inline-flex; align-items: center; gap: 8px;

50 background: transparent; color: var(--cs-gray-700);

51 border: 0.5px solid var(--cs-border-default);

52 border-radius: 8px; padding: 8px 14px;

53 font-size: 13px; font-weight: 500;

54}

55.cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }

56.dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); }

57@media (max-width: 720px) {

58 .cc-cs-actions { width: 100%; }

59}

60`;

61 return <div className="cc-cs not-prose">

62 <style>{STYLES}</style>

63 <div className="cc-cs-card">

64 <div className="cc-cs-text">

65 <strong>Deploying Claude Code across your organization?</strong> Talk to sales about enterprise plans, SSO, and centralized billing.

66 </div>

67 <div className="cc-cs-actions">

68 <a href={`https://claude.com/pricing?${utm('view_plans')}#plans-business`} className="cc-cs-btn-ghost">

69 View plans

70 </a>

71 <a href={`https://claude.com/contact-sales?${utm('contact_sales')}`} className="cc-cs-btn-clay">

72 Contact sales {iconArrowRight()}

73 </a>

74 </div>

75 </div>

76 </div>;

77};

78 

9조직은 Anthropic을 통해 직접 또는 클라우드 제공자를 통해 Claude Code를 배포할 수 있습니다. 이 페이지는 올바른 구성을 선택하는 데 도움을 줍니다.79조직은 Anthropic을 통해 직접 또는 클라우드 제공자를 통해 Claude Code를 배포할 수 있습니다. 이 페이지는 올바른 구성을 선택하는 데 도움을 줍니다.

10 80 

81<ContactSalesCard surface="third_party_overview" />

82 

11<h2 id="compare-deployment-options">83<h2 id="compare-deployment-options">

12 배포 옵션 비교84 배포 옵션 비교

13</h2>85</h2>


271 클라우드 제공자를 위한 모델 버전 고정343 클라우드 제공자를 위한 모델 버전 고정

272</h3>344</h3>

273 345 

274[Bedrock](/ko/amazon-bedrock), [Vertex AI](/ko/google-vertex-ai), [Foundry](/ko/microsoft-foundry) 또는 [Claude Platform on AWS](/ko/claude-platform-on-aws)를 통해 배포하는 경우 `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL` 및 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 사용하여 특정 모델 버전을 고정합니다. 고정하지 않으면 모델 별칭이 최신 버전으로 확인되어 Anthropic이 아직 계정에서 활성화되지 않은 모델을 출시할 사용자가 손상될 수 있습니다. 각 제공자가 최신 버전을 사용할 수 없을 때 수행하는 작업에 대해서는 [모델 구성](/ko/model-config#pin-models-for-third-party-deployments)을 참조하십시오.346[Bedrock](/ko/amazon-bedrock), [Vertex AI](/ko/google-vertex-ai), [Foundry](/ko/microsoft-foundry) 또는 [Claude Platform on AWS](/ko/claude-platform-on-aws)를 통해 배포하는 경우 `ANTHROPIC_DEFAULT_FABLE_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL` 및 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 사용하여 특정 모델 버전을 고정합니다. 고정하지 않으면 모델 별칭이 Claude Code의 해당 제공자에 대한 기본 제공 기본값으로 확인되며, 이는 최신 릴리스보다 뒤떨어질 있고 계정에서 아직 활성화되지 않았을 있습니다. 고정하면 사용자가 모델로 이동하는 시기를 제어할 수 있습니다. 각 제공자가 기본값을 사용할 수 없을 때 수행하는 작업에 대해서는 [모델 구성](/ko/model-config#pin-models-for-third-party-deployments)을 참조하십시오.

275 347 

276<h3 id="configure-security-policies">348<h3 id="configure-security-policies">

277 보안 정책 구성349 보안 정책 구성

Details

44| `TaskOutput` | (더 이상 사용되지 않음) 백그라운드 작업에서 출력을 검색합니다. 작업의 출력 파일 경로에서 `Read`를 사용하는 것을 권장합니다 | 아니오 |44| `TaskOutput` | (더 이상 사용되지 않음) 백그라운드 작업에서 출력을 검색합니다. 작업의 출력 파일 경로에서 `Read`를 사용하는 것을 권장합니다 | 아니오 |

45| `TaskStop` | ID로 실행 중인 백그라운드 작업을 종료합니다 | 아니오 |45| `TaskStop` | ID로 실행 중인 백그라운드 작업을 종료합니다 | 아니오 |

46| `TaskUpdate` | 작업 상태, 종속성, 세부 정보를 업데이트하거나 작업을 삭제합니다 | 아니오 |46| `TaskUpdate` | 작업 상태, 종속성, 세부 정보를 업데이트하거나 작업을 삭제합니다 | 아니오 |

47| `TeamCreate` | 여러 팀원이 있는 [agent team](/ko/agent-teams)을 생성합니다. `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`이 설정되었을 때만 사용 가능합니다 | 아니오 |

48| `TeamDelete` | agent team을 해산하고 팀원 프로세스를 정리합니다. `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`이 설정되었을 때만 사용 가능합니다 | 아니오 |

49| `TodoWrite` | {/* min-version: 2.1.142 */}세션 작업 체크리스트를 관리합니다. v2.1.142부터 기본적으로 비활성화되어 있으며 `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`를 선호합니다. `CLAUDE_CODE_ENABLE_TASKS=0`을 설정하여 다시 활성화합니다 | 아니오 |47| `TodoWrite` | {/* min-version: 2.1.142 */}세션 작업 체크리스트를 관리합니다. v2.1.142부터 기본적으로 비활성화되어 있으며 `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`를 선호합니다. `CLAUDE_CODE_ENABLE_TASKS=0`을 설정하여 다시 활성화합니다 | 아니오 |

50| `ToolSearch` | [tool search](/ko/mcp#scale-with-mcp-tool-search)가 활성화되었을 때 지연된 도구를 검색하고 로드합니다 | 아니오 |48| `ToolSearch` | [tool search](/ko/mcp#scale-with-mcp-tool-search)가 활성화되었을 때 지연된 도구를 검색하고 로드합니다 | 아니오 |

51| `WaitForMcpServers` | {/* min-version: 2.1.142 */}백그라운드에서 여전히 연결 중인 하나 이상의 [MCP 서버](/ko/mcp)를 기다리므로, 요청이 세션을 다시 시작하지 않고도 해당 도구를 사용할 수 있습니다. Claude는 필요한 서버가 아직 연결되지 않았을 때 이를 호출합니다. [tool search](/ko/mcp#scale-with-mcp-tool-search)가 비활성화되었을 때만 나타나며, `ToolSearch`가 활성화되었을 때는 대기를 처리합니다 | 아니오 |49| `WaitForMcpServers` | {/* min-version: 2.1.142 */}백그라운드에서 여전히 연결 중인 하나 이상의 [MCP 서버](/ko/mcp)를 기다리므로, 요청이 세션을 다시 시작하지 않고도 해당 도구를 사용할 수 있습니다. Claude는 필요한 서버가 아직 연결되지 않았을 때 이를 호출합니다. [tool search](/ko/mcp#scale-with-mcp-tool-search)가 비활성화되었을 때만 나타나며, `ToolSearch`가 활성화되었을 때는 대기를 처리합니다 | 아니오 |


61대부분의 경우 Claude가 이러한 도구를 사용할 시기를 결정하며 Claude와 상호작용할 때 도구 이름을 직접 지정할 필요가 없습니다. 권한 및 기타 구성을 정의할 때 도구 이름을 직접 참조합니다:59대부분의 경우 Claude가 이러한 도구를 사용할 시기를 결정하며 Claude와 상호작용할 때 도구 이름을 직접 지정할 필요가 없습니다. 권한 및 기타 구성을 정의할 때 도구 이름을 직접 참조합니다:

62 60 

63* 설정의 [`permissions.allow` 및 `permissions.deny`](/ko/settings#available-settings) 및 `/permissions` 인터페이스에서61* 설정의 [`permissions.allow` 및 `permissions.deny`](/ko/settings#available-settings) 및 `/permissions` 인터페이스에서

62* [CLI 플래그](/ko/cli-reference)의 `--allowedTools` 및 `--disallowedTools`에서

64* Agent SDK의 [`allowedTools` 및 `disallowedTools`](/ko/agent-sdk/permissions#allow-and-deny-rules) 옵션에서63* Agent SDK의 [`allowedTools` 및 `disallowedTools`](/ko/agent-sdk/permissions#allow-and-deny-rules) 옵션에서

65* [subagent의 `tools` 또는 `disallowedTools`](/ko/sub-agents#supported-frontmatter-fields) frontmatter에서64* [subagent의 `tools` 또는 `disallowedTools`](/ko/sub-agents#supported-frontmatter-fields) frontmatter에서

66* [skill의 `allowed-tools`](/ko/skills#frontmatter-reference) frontmatter에서65* [skill의 `allowed-tools`](/ko/skills#frontmatter-reference) frontmatter에서


69이들 모두 동일한 규칙 형식인 `ToolName(specifier)`를 허용합니다. specifier는 도구에 따라 다르며, 여러 도구가 형식을 공유합니다:68이들 모두 동일한 규칙 형식인 `ToolName(specifier)`를 허용합니다. specifier는 도구에 따라 다르며, 여러 도구가 형식을 공유합니다:

70 69 

71| 규칙 형식 | 적용 대상 | 세부 정보 |70| 규칙 형식 | 적용 대상 | 세부 정보 |

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

73| `Bash(npm run *)` | Bash, Monitor | [명령 패턴 매칭](/ko/permissions#bash) |72| `Bash(npm run *)` | Bash, Monitor | [명령 패턴 매칭](/ko/permissions#bash) |

74| `PowerShell(Get-ChildItem *)` | PowerShell | [명령 패턴 매칭](/ko/permissions#powershell) |73| `PowerShell(Get-ChildItem *)` | PowerShell | [명령 패턴 매칭](/ko/permissions#powershell) |

75| `Read(~/secrets/**)` | Read, Grep, Glob, LSP | [경로 패턴 매칭](/ko/permissions#read-and-edit) |74| `Read(~/secrets/**)` | Read, Grep, Glob, LSP | [경로 패턴 매칭](/ko/permissions#read-and-edit) |

76| `Edit(/src/**)` | Edit, Write, NotebookEdit | [경로 패턴 매칭](/ko/permissions#read-and-edit) |75| `Edit(/src/**)` | Edit, Write, NotebookEdit | [경로 패턴 매칭](/ko/permissions#read-and-edit) |

77| `Skill(deploy *)` | Skill | [Skill 이름 매칭](/ko/skills#restrict-claude's-skill-access) |76| `Skill(deploy *)` | Skill | [Skill 이름 매칭](/ko/skills#restrict-claude%E2%80%99s-skill-access) |

78| `Agent(Explore)` | Agent | [Subagent 타입 매칭](/ko/permissions#agent-subagents) |77| `Agent(Explore)` | Agent | [Subagent 타입 매칭](/ko/permissions#agent-subagents) |

79| `WebFetch(domain:example.com)` | WebFetch | [도메인 매칭](/ko/permissions#webfetch) |78| `WebFetch(domain:example.com)` | WebFetch | [도메인 매칭](/ko/permissions#webfetch) |

80| `WebSearch` | WebSearch | specifier 없음; 도구 전체를 허용하거나 거부합니다 |79| `WebSearch` | WebSearch | specifier 없음; 도구 전체를 허용하거나 거부합니다 |


91 90 

92Agent 도구는 별도의 context window에서 subagent를 생성합니다. Subagent는 자신의 작업을 자율적으로 처리한 다음 단일 텍스트 결과를 부모 대화에 반환합니다. 부모는 subagent의 중간 도구 호출이나 출력을 보지 못하고, 최종 결과만 봅니다. Subagent가 실행하는 턴의 수를 제한하려면 [subagent 정의](/ko/sub-agents#supported-frontmatter-fields)에서 `maxTurns`를 설정합니다.91Agent 도구는 별도의 context window에서 subagent를 생성합니다. Subagent는 자신의 작업을 자율적으로 처리한 다음 단일 텍스트 결과를 부모 대화에 반환합니다. 부모는 subagent의 중간 도구 호출이나 출력을 보지 못하고, 최종 결과만 봅니다. Subagent가 실행하는 턴의 수를 제한하려면 [subagent 정의](/ko/sub-agents#supported-frontmatter-fields)에서 `maxTurns`를 설정합니다.

93 92 

94동일한 Agent 도구는 fork 모드가 활성화되었을 때 [forked subagent](/ko/sub-agents#fork-the-current-conversation)도 시작합니다. fork는 새로 시작하는 대신 전체 부모 대화를 상속하고, 항상 백그라운드에서 실행되며, 여전히 터미널에서 권한 프롬프트를 표시합니다. 이 섹션의 나머지 부분은 명명된 subagent를 설명합니다.93동일한 Agent 도구는 fork 모드가 활성화되었을 때 [forked subagent](/ko/sub-agents#fork-the-current-conversation)도 시작합니다. Fork는 새로 시작하는 대신 전체 부모 대화를 상속하고, 항상 백그라운드에서 실행되며, 여전히 터미널에서 권한 프롬프트를 표시합니다. 이 섹션의 나머지 부분은 명명된 subagent를 설명합니다.

95 94 

96명명된 subagent가 사용할 수 있는 도구는 [subagent 정의](/ko/sub-agents)의 `tools` 및 `disallowedTools` 필드에 따라 다릅니다:95명명된 subagent가 사용할 수 있는 도구는 [subagent 정의](/ko/sub-agents)의 `tools` 및 `disallowedTools` 필드에 따라 다릅니다:

97 96 


185* 기호의 정의로 이동184* 기호의 정의로 이동

186* 기호에 대한 모든 참조 찾기185* 기호에 대한 모든 참조 찾기

187* 위치의 타입 정보 가져오기186* 위치의 타입 정보 가져오기

188* 파일 또는 워크스페이스의 기호 나열187* 파일의 기호 나열

188* 워크스페이스 전체에서 기호 이름으로 검색

189* 인터페이스의 구현 찾기189* 인터페이스의 구현 찾기

190* 호출 계층 추적190* 호출 계층 추적

191 191 


304* 응답은 15분 동안 캐시되므로, 동일한 URL의 반복 가져오기는 빠르게 반환됩니다.304* 응답은 15분 동안 캐시되므로, 동일한 URL의 반복 가져오기는 빠르게 반환됩니다.

305* URL이 다른 호스트로 리다이렉트되면, WebFetch는 원본 URL과 리다이렉트 대상의 이름을 지정하는 텍스트 결과를 반환하고 따라가지 않습니다. Claude는 두 번째 WebFetch 호출로 새 URL을 가져옵니다.305* URL이 다른 호스트로 리다이렉트되면, WebFetch는 원본 URL과 리다이렉트 대상의 이름을 지정하는 텍스트 결과를 반환하고 따라가지 않습니다. Claude는 두 번째 WebFetch 호출로 새 URL을 가져옵니다.

306 306 

307기본 및 `acceptEdits` 권한 모드에서 WebFetch는 새 도메인에 처음 도달할 때 프롬프트합니다. 프롬프트 없이 미리 도메인을 허용하려면 `WebFetch(domain:example.com)`과 같은 권한 규칙을 추가합니다. `auto` 및 `bypassPermissions` [권한 모드](/ko/permissions#permission-modes)는 프롬프트를 완전히 건너뜁니다.307기본 및 `acceptEdits` 권한 모드에서 WebFetch는 새 도메인에 처음 도달할 때 프롬프트합니다. 단, 프롬프트 없이 가져오는 미리 승인된 설명서 도메인의 기본 제공 집합이 있습니다. 프롬프트 없이 미리 도메인을 허용하려면 `WebFetch(domain:example.com)`과 같은 권한 규칙을 추가합니다. `auto` 및 `bypassPermissions` [권한 모드](/ko/permissions#permission-modes)는 프롬프트를 완전히 건너뜁니다.

308 

309`deny`, `ask` 또는 `allow`의 명시적 `WebFetch(domain:...)` 규칙은 미리 승인된 집합보다 우선하므로, 미리 승인된 도메인을 차단하거나 프롬프트를 요구할 수 있습니다.

308 310 

309WebFetch는 `Claude-User`로 시작하는 `User-Agent` 헤더와 콘텐츠 협상을 지원하는 서버가 Markdown을 직접 반환할 수 있도록 HTML보다 Markdown을 선호하는 `Accept` 헤더를 설정합니다. [Sandbox](/ko/sandboxing) 네트워크 규칙은 별도로 구성되므로, sandboxed 프로세스가 도달하기를 원하는 도메인은 여전히 명시적 sandbox 권한 규칙이 필요합니다.311WebFetch는 `Claude-User`로 시작하는 `User-Agent` 헤더와 콘텐츠 협상을 지원하는 서버가 Markdown을 직접 반환할 수 있도록 HTML보다 Markdown을 선호하는 `Accept` 헤더를 설정합니다. [Sandbox](/ko/sandboxing) 네트워크 규칙은 별도로 구성되므로, sandboxed 프로세스가 도달하기를 원하는 도메인은 여전히 명시적 sandbox 권한 규칙이 필요합니다.

310 312 


312 WebSearch 도구 동작314 WebSearch 도구 동작

313</h2>315</h2>

314 316 

315WebSearch는 Anthropic의 [web search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool) 백엔드에 대해 쿼리를 실행하고 결과 제목과 URL을 반환합니다. 결과 페이지를 가져오지 않습니다. Claude가 검색 결과에서 찾은 페이지를 읽으려면 [WebFetch](#webfetch-tool-behavior)로 후속 조치합니다.317WebSearch는 Anthropic의 [web search](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-search-tool) 백엔드에 대해 쿼리를 실행하고 결과 제목과 URL을 반환합니다. 결과 페이지를 가져오지 않습니다. Claude가 검색 결과에서 찾은 페이지를 읽으려면 [WebFetch](#webfetch-tool-behavior)로 후속 조치합니다.

316 318 

317이 도구는 호출당 최대 8개의 백엔드 검색을 발행하여 반환 전에 검색을 내부적으로 개선할 수 있습니다. Claude는 `allowed_domains`로 특정 호스트만 포함하거나 `blocked_domains`로 제외하여 결과를 범위 지정할 수 있습니다. 두 목록은 단일 호출에서 결합할 수 없습니다.319이 도구는 호출당 최대 8개의 백엔드 검색을 발행하여 반환 전에 검색을 내부적으로 개선할 수 있습니다. Claude는 `allowed_domains`로 특정 호스트만 포함하거나 `blocked_domains`로 제외하여 결과를 범위 지정할 수 있습니다. 두 목록은 단일 호출에서 결합할 수 없습니다.

318 320 


348 350 

349Claude는 대화형 요약을 제공합니다. 정확한 MCP 도구 이름의 경우 `/mcp`를 실행합니다.351Claude는 대화형 요약을 제공합니다. 정확한 MCP 도구 이름의 경우 `/mcp`를 실행합니다.

350 352 

353<Note>

354 [advisor tool](/ko/advisor)은 Claude Code가 구현하는 도구가 아니라 API가 실행하는 [server tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool)입니다. 권한 규칙이나 hook 매처에서 참조할 수 있는 이름이 없습니다.

355</Note>

356 

351<h2 id="see-also">357<h2 id="see-also">

352 참고 항목358 참고 항목

353</h2>359</h2>

Details

24| `TLS connect error` 또는 `SSL/TLS secure channel` | [CA 인증서 업데이트](#tls-or-ssl-connection-errors) |24| `TLS connect error` 또는 `SSL/TLS secure channel` | [CA 인증서 업데이트](#tls-or-ssl-connection-errors) |

25| `Failed to fetch version` 또는 다운로드 서버에 도달할 수 없음 | [네트워크 및 프록시 설정 확인](#check-network-connectivity) |25| `Failed to fetch version` 또는 다운로드 서버에 도달할 수 없음 | [네트워크 및 프록시 설정 확인](#check-network-connectivity) |

26| `irm is not recognized` 또는 `&& is not valid` | [셸에 맞는 명령 사용](#wrong-install-command-on-windows) |26| `irm is not recognized` 또는 `&& is not valid` | [셸에 맞는 명령 사용](#wrong-install-command-on-windows) |

27| `Cask 'claude-code' is unavailable: No Cask with this name exists` | [Homebrew 업데이트](#homebrew-cask-unavailable-or-outdated) |

27| `'bash' is not recognized as the name of a cmdlet` | [Windows 설치 프로그램 명령 사용](#wrong-install-command-on-windows) |28| `'bash' is not recognized as the name of a cmdlet` | [Windows 설치 프로그램 명령 사용](#wrong-install-command-on-windows) |

28| `Claude Code on Windows requires either Git for Windows (for bash) or PowerShell` | [셸 설치](#claude-code-on-windows-requires-either-git-for-windows-for-bash-or-powershell) |29| `Claude Code on Windows requires either Git for Windows (for bash) or PowerShell` | [셸 설치](#claude-code-on-windows-requires-either-git-for-windows-for-bash-or-powershell) |

29| `Claude Code does not support 32-bit Windows` | [Windows PowerShell 열기, x86 항목 아님](#claude-code-does-not-support-32-bit-windows) |30| `Claude Code does not support 32-bit Windows` | [Windows PowerShell 열기, x86 항목 아님](#claude-code-does-not-support-32-bit-windows) |


61curl -sI https://downloads.claude.ai/claude-code-releases/latest62curl -sI https://downloads.claude.ai/claude-code-releases/latest

62```63```

63 64 

65PowerShell에서는 `curl.exe -sI`를 대신 실행하세요. PowerShell은 `curl`을 `Invoke-WebRequest`로 별칭 지정하며, 이는 `-sI` 플래그를 거부합니다.

66 

64`HTTP/2 200` 줄은 서버에 도달했음을 의미합니다. 출력이 없거나 `Could not resolve host` 또는 연결 시간 초과가 표시되면 네트워크가 연결을 차단하고 있습니다. 일반적인 원인:67`HTTP/2 200` 줄은 서버에 도달했음을 의미합니다. 출력이 없거나 `Could not resolve host` 또는 연결 시간 초과가 표시되면 네트워크가 연결을 차단하고 있습니다. 일반적인 원인:

65 68 

66* `downloads.claude.ai`를 차단하는 회사 방화벽 또는 프록시69* `downloads.claude.ai`를 차단하는 회사 방화벽 또는 프록시


95 98 

96설치가 성공했지만 `claude`를 실행할 때 `command not found` 또는 `not recognized` 오류가 발생하면 설치 디렉토리가 PATH에 없습니다. 셸은 PATH에 나열된 디렉토리에서 프로그램을 검색하고 설치 프로그램은 macOS/Linux에서 `~/.local/bin/claude`에 또는 Windows에서 `%USERPROFILE%\.local\bin\claude.exe`에 `claude`를 배치합니다.99설치가 성공했지만 `claude`를 실행할 때 `command not found` 또는 `not recognized` 오류가 발생하면 설치 디렉토리가 PATH에 없습니다. 셸은 PATH에 나열된 디렉토리에서 프로그램을 검색하고 설치 프로그램은 macOS/Linux에서 `~/.local/bin/claude`에 또는 Windows에서 `%USERPROFILE%\.local\bin\claude.exe`에 `claude`를 배치합니다.

97 100 

101<Note>

102 [VS Code 확장](/ko/vs-code)은 `claude`를 이 위치에 배치하지 않습니다. 확장 디렉토리 내에 CLI의 개인 복사본을 번들로 제공하며 자체 채팅 패널용으로 사용하고 PATH에 추가하지 않습니다. 확장만 설치한 경우 `~/.local/bin/claude`가 존재하지 않습니다. [독립 실행형 설치](/ko/setup)를 실행하여 터미널에서 `claude`를 사용한 다음 아래를 계속하세요.

103</Note>

104 

98PATH 항목을 나열하고 `local/bin`을 필터링하여 설치 디렉토리가 PATH에 있는지 확인하세요:105PATH 항목을 나열하고 `local/bin`을 필터링하여 설치 디렉토리가 PATH에 있는지 확인하세요:

99 106 

100<Tabs>107<Tabs>


188 ls -la ~/.local/bin/claude195 ls -la ~/.local/bin/claude

189 ```196 ```

190 197 

198 `ls` 명령이 `No such file or directory`를 인쇄하면 오류가 아닙니다. 이는 해당 위치에 아무것도 설치되지 않았음을 의미하므로 다음 검사로 이동하세요.

199 

191 ```bash theme={null}200 ```bash theme={null}

192 ls -la ~/.claude/local/201 ls -la ~/.claude/local/

193 ```202 ```


390 winget install Anthropic.ClaudeCode399 winget install Anthropic.ClaudeCode

391 ```400 ```

392 401 

402<h3 id="homebrew-cask-unavailable-or-outdated">

403 Homebrew cask를 사용할 수 없거나 오래됨

404</h3>

405 

406Homebrew가 `Error: Cask 'claude-code' is unavailable: No Cask with this name exists`를 보고하면 Homebrew cask 인덱스의 로컬 복사본이 cask의 게시 이전입니다. 인덱스를 새로 고치고 다시 시도하세요:

407 

408```bash theme={null}

409brew update

410brew install --cask claude-code

411```

412 

413Homebrew가 예상보다 이전 Claude Code 버전을 설치하면 동일한 오래된 인덱스가 일반적으로 원인입니다. `claude-code` cask는 안정적인 채널을 추적하며 일반적으로 최신 릴리스보다 약 1주일 뒤떨어져 있습니다. 최신 버전의 경우 대신 `brew install --cask claude-code@latest`를 실행하세요. 두 cask의 차이점은 [릴리스 채널 구성](/ko/setup#configure-release-channel)을 참조하세요.

414 

393<h3 id="tls-or-ssl-connection-errors">415<h3 id="tls-or-ssl-connection-errors">

394 TLS 또는 SSL 연결 오류416 TLS 또는 SSL 연결 오류

395</h3>417</h3>


592 614 

593Git이 다른 곳에 설치된 경우 PowerShell에서 `where.exe git`을 실행하여 경로를 찾고 해당 디렉토리의 `bin\bash.exe` 경로를 사용하세요.615Git이 다른 곳에 설치된 경우 PowerShell에서 `where.exe git`을 실행하여 경로를 찾고 해당 디렉토리의 `bin\bash.exe` 경로를 사용하세요.

594 616 

617**경로가 올바르고 파일이 존재하지만** Claude Code가 여전히 찾을 수 없다고 보고하면 AppLocker, 그룹 정책 소프트웨어 제한 정책 또는 EDR 에이전트와 같은 엔드포인트 보안 소프트웨어가 간섭할 수 있습니다. v2.1.116 이전 버전에서 Claude Code는 경로를 확인하기 위해 자식 프로세스(`cmd.exe`)를 생성했으며, 이러한 정책이 차단할 수 있습니다. 일반적인 신호는 `cmd.exe /c dir "C:\Program Files\Git\bin\bash.exe"`가 PowerShell에서 직접 실행할 때는 작동하지만 `claude.exe`에서 시작할 때는 자동으로 실패한다는 것입니다.

618 

619Claude Code v2.1.116 이상은 파일 시스템을 직접 확인하므로 먼저 업데이트하세요. 현재 버전에서 오류가 지속되면 IT 팀에 `claude.exe` 및 `cmd.exe`와 `bash.exe`를 포함한 생성하는 프로세스를 엔드포인트 보호 정책에서 허용 목록에 추가하도록 요청하세요.

620 

595<h3 id="claude-code-does-not-support-32-bit-windows">621<h3 id="claude-code-does-not-support-32-bit-windows">

596 Claude Code는 32비트 Windows를 지원하지 않음622 Claude Code는 32비트 Windows를 지원하지 않음

597</h3>623</h3>

Details

9이 페이지는 Claude Code가 실행 중일 때의 성능, 안정성 및 검색 문제를 다룹니다. 다른 문제의 경우 문제가 있는 위치와 일치하는 페이지부터 시작하세요:9이 페이지는 Claude Code가 실행 중일 때의 성능, 안정성 및 검색 문제를 다룹니다. 다른 문제의 경우 문제가 있는 위치와 일치하는 페이지부터 시작하세요:

10 10 

11| 증상 | 이동 |11| 증상 | 이동 |

12| :--------------------------------------------------------------------------------------- | :------------------------------------------------------------------ |12| :--------------------------------------------------------------------------------------- | :------------------------------------------------------------------- |

13| `command not found`, 설치 실패, PATH 문제, `EACCES`, TLS 오류 | [설치 및 로그인 문제 해결](/ko/troubleshoot-install) |13| `command not found`, 설치 실패, PATH 문제, `EACCES`, TLS 오류 | [설치 및 로그인 문제 해결](/ko/troubleshoot-install) |

14| 로그인 루프, OAuth 오류, `403 Forbidden`, "organization disabled", Bedrock/Vertex/Foundry 자격 증명 | [설치 및 로그인 문제 해결](/ko/troubleshoot-install#login-and-authentication) |14| 로그인 루프, OAuth 오류, `403 Forbidden`, "organization disabled", Bedrock/Vertex/Foundry 자격 증명 | [설치 및 로그인 문제 해결](/ko/troubleshoot-install#login-and-authentication) |

15| 설정이 적용되지 않음, hooks가 실행되지 않음, MCP 서버가 로드되지 않음 | [구성 디버깅](/ko/debug-your-config) |15| 설정이 적용되지 않음, hooks가 실행되지 않음, MCP 서버가 로드되지 않음 | [구성 디버깅](/ko/debug-your-config) |

16| `API Error: 5xx`, `529 Overloaded`, `429`, 요청 검증 오류 | [오류 참조](/ko/errors) |16| `API Error: 5xx`, `529 Overloaded`, `429`, 요청 검증 오류 | [오류 참조](/ko/errors) |

17| `model not found` 또는 `you may not have access to it` | [오류 참조](/ko/errors#theres-an-issue-with-the-selected-model) |17| `model not found` 또는 `you may not have access to it` | [오류 참조](/ko/errors#there%E2%80%99s-an-issue-with-the-selected-model) |

18| VS Code 확장이 Claude에 연결되지 않거나 감지하지 못함 | [VS Code 통합](/ko/vs-code#fix-common-issues) |18| VS Code 확장이 Claude에 연결되지 않거나 감지하지 못함 | [VS Code 통합](/ko/vs-code#fix-common-issues) |

19| JetBrains 플러그인 또는 IDE가 감지되지 않음 | [JetBrains 통합](/ko/jetbrains#troubleshooting) |19| JetBrains 플러그인 또는 IDE가 감지되지 않음 | [JetBrains 통합](/ko/jetbrains#troubleshooting) |

20| 높은 CPU 또는 메모리, 느린 응답, 중단, 검색이 파일을 찾지 못함 | [성능 및 안정성](#performance-and-stability) 아래 |20| 높은 CPU 또는 메모리, 느린 응답, 중단, 검색이 파일을 찾지 못함 | [성능 및 안정성](#performance-and-stability) 아래 |


361. `/compact`를 정기적으로 사용하여 컨텍스트 크기 감소361. `/compact`를 정기적으로 사용하여 컨텍스트 크기 감소

372. 주요 작업 사이에 Claude Code 닫기 및 다시 시작372. 주요 작업 사이에 Claude Code 닫기 및 다시 시작

383. 큰 빌드 디렉토리를 `.gitignore` 파일에 추가하는 것을 고려하세요383. 큰 빌드 디렉토리를 `.gitignore` 파일에 추가하는 것을 고려하세요

394. [`claude --safe-mode`](/ko/cli-reference#cli-flags)로 다시 시작하여 플러그인, MCP 서버 또는 hook이 원인인지 확인하세요. 이는 세션의 모든 사용자 정의를 비활성화합니다. 사용량이 감소하면 [구성 디버깅](/ko/debug-your-config#test-against-a-clean-configuration)을 참조하여 어느 것이 원인인지 찾으세요

39 40 

40메모리 사용량이 이 단계 후에도 높게 유지되면 `/heapdump`를 실행하여 JavaScript 힙 스냅샷과 메모리 분석을 `~/Desktop`에 작성하세요. Linux에 Desktop 폴더가 없으면 파일이 홈 디렉토리에 작성됩니다.41메모리 사용량이 이 단계 후에도 높게 유지되면 `/heapdump`를 실행하여 JavaScript 힙 스냅샷과 메모리 분석을 `~/Desktop`에 작성하세요. Linux에 Desktop 폴더가 없으면 파일이 홈 디렉토리에 작성됩니다.

41 42 


65 66 

66다시 시작해도 대화가 손실되지 않습니다. 같은 디렉토리에서 `claude --resume`을 실행하여 세션을 다시 시작하세요.67다시 시작해도 대화가 손실되지 않습니다. 같은 디렉토리에서 `claude --resume`을 실행하여 세션을 다시 시작하세요.

67 68 

68<h3 id="garbled-or-corrupted-text-in-an-editor-s-integrated-terminal">69<h3 id="garbled-or-corrupted-text-in-an-editors-integrated-terminal">

69 편집기의 통합 터미널에서 손상되거나 깨진 텍스트70 편집기의 통합 터미널에서 손상되거나 깨진 텍스트

70</h3>71</h3>

71 72 

ultraplan.md +1 −1

Details

38 38 

39명령어 및 키워드 경로는 시작하기 전에 확인 대화상자를 엽니다. 로컬 계획 경로는 해당 선택이 이미 확인 역할을 하므로 이 대화상자를 건너뜁니다. [Remote Control](/ko/remote-control)이 활성화되어 있으면 두 기능이 claude.ai/code 인터페이스를 차지하고 한 번에 하나만 연결될 수 있으므로 ultraplan이 시작될 때 연결이 끊깁니다.39명령어 및 키워드 경로는 시작하기 전에 확인 대화상자를 엽니다. 로컬 계획 경로는 해당 선택이 이미 확인 역할을 하므로 이 대화상자를 건너뜁니다. [Remote Control](/ko/remote-control)이 활성화되어 있으면 두 기능이 claude.ai/code 인터페이스를 차지하고 한 번에 하나만 연결될 수 있으므로 ultraplan이 시작될 때 연결이 끊깁니다.

40 40 

41클라우드 세션이 시작된 후 CLI의 프롬프트 입력은 원격 세션이 작동하는 동안 상태 표시기를 표시합니다:41클라우드 세션이 시작된 후 CLI의 프롬프트 입력은 클라우드 세션이 작동하는 동안 상태 표시기를 표시합니다:

42 42 

43| 상태 | 의미 |43| 상태 | 의미 |

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

ultrareview.md +1 −1

Details

115 관련 리소스115 관련 리소스

116</h2>116</h2>

117 117 

118* [Claude Code on the web](/ko/claude-code-on-the-web): 원격 세션 및 클라우드 샌드박스의 작동 방식 알아보기118* [Claude Code on the web](/ko/claude-code-on-the-web): 클라우드 세션 및 클라우드 샌드박스의 작동 방식 알아보기

119* [ultraplan으로 복잡한 변경 사항 계획](/ko/ultraplan): 사전 설계 작업을 위한 ultrareview의 계획 대응119* [ultraplan으로 복잡한 변경 사항 계획](/ko/ultraplan): 사전 설계 작업을 위한 ultrareview의 계획 대응

120* [비용 효과적으로 관리](/ko/costs): 사용량 추적 및 지출 한도 설정120* [비용 효과적으로 관리](/ko/costs): 사용량 추적 및 지출 한도 설정

vs-code.md +34 −8

Details

19설치하기 전에 다음을 확인하십시오:19설치하기 전에 다음을 확인하십시오:

20 20 

21* VS Code 1.98.0 이상21* VS Code 1.98.0 이상

22* Anthropic 계정(확장 프로그램을 처음 열 때 로그인합니다). Amazon Bedrock이나 Google Vertex AI와 같은 타사 공급자를 사용하는 경우 대신 [타사 공급자 사용](#use-third-party-providers)을 참조하십시오.22* Anthropic 계정: 모든 유료 Claude 구독(Pro, Max, Team 또는 Enterprise) 또는 Claude Console 계정이 작동하며, API 키가 필요하지 않습니다. 확장 프로그램을 처음 열 때 이 계정으로 [로그인](/ko/authentication#log-in-to-claude-code)합니다. Amazon Bedrock이나 Google Vertex AI와 같은 타사 공급자를 통해 Claude에 액세스하는 경우 설정 지침은 [타사 공급자 사용](#use-third-party-providers)을 참조하십시오.

23 23 

24<Tip>24<Tip>

25 확장 프로그램에는 CLI(명령줄 인터페이스) 포함되어 있으며, VS Code의 통합 터미널에서 고급 기능에 액세스할 있습니다. 자세한 내용은 [VS Code 확장 프로그램 vs. Claude Code CLI](#vs-code-extension-vs-claude-code-cli)를 참조하십시오.25 확장 프로그램에는 채팅 패널용 CLI(명령줄 인터페이스) 자체 복사본이 포함되어 있습니다. VS Code의 통합 터미널에서 `claude`를 실행하려면 [독립 실행형 CLI 설치](/ko/setup)도 필요합니다. 자세한 내용은 [VS Code 확장 프로그램 vs. Claude Code CLI](#vs-code-extension-vs-claude-code-cli)를 참조하십시오.

26</Tip>26</Tip>

27 27 

28<h2 id="install-the-extension">28<h2 id="install-the-extension">


36 36 

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

38 38 

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

40 40 

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

42 42 


131 131 

132Claude Code 패널 상단의 **세션 기록** 버튼을 클릭하여 대화 기록에 액세스합니다. 키워드로 검색하거나 시간별로 찾아볼 수 있습니다(오늘, 어제, 지난 7일 등). 대화를 클릭하여 전체 메시지 기록으로 재개합니다. 새 세션은 첫 번째 메시지를 기반으로 AI가 생성한 제목을 받습니다. 세션 위에 마우스를 올려 이름 바꾸기 및 제거 작업을 표시합니다: 설명적인 제목으로 이름을 바꾸거나 목록에서 삭제하려면 제거합니다. 세션 재개에 대한 자세한 내용은 [세션 관리](/ko/sessions)를 참조하십시오.132Claude Code 패널 상단의 **세션 기록** 버튼을 클릭하여 대화 기록에 액세스합니다. 키워드로 검색하거나 시간별로 찾아볼 수 있습니다(오늘, 어제, 지난 7일 등). 대화를 클릭하여 전체 메시지 기록으로 재개합니다. 새 세션은 첫 번째 메시지를 기반으로 AI가 생성한 제목을 받습니다. 세션 위에 마우스를 올려 이름 바꾸기 및 제거 작업을 표시합니다: 설명적인 제목으로 이름을 바꾸거나 목록에서 삭제하려면 제거합니다. 세션 재개에 대한 자세한 내용은 [세션 관리](/ko/sessions)를 참조하십시오.

133 133 

134<h3 id="resume-remote-sessions-from-claude-ai">134<h3 id="resume-cloud-sessions-from-claude-ai">

135 Claude.ai에서 원격 세션 재개135 Claude.ai에서 원격 세션 재개

136</h3>136</h3>

137 137 


155 원격 탭에는 GitHub 저장소로 시작된 웹 세션만 나타납니다. 재개하면 대화 기록이 로컬로 로드되며, 변경 사항은 claude.ai로 다시 동기화되지 않습니다.155 원격 탭에는 GitHub 저장소로 시작된 웹 세션만 나타납니다. 재개하면 대화 기록이 로컬로 로드되며, 변경 사항은 claude.ai로 다시 동기화되지 않습니다.

156</Note>156</Note>

157 157 

158<h3 id="check-account-and-usage">

159 계정 및 사용량 확인

160</h3>

161 

162명령 메뉴에서 `/usage`를 실행하여 계정 및 사용량 대화 상자를 엽니다. 로그인한 계정, 요금제 및 현재 세션과 주간 사용량 막대를 표시하며 각 제한이 재설정될 때까지의 시간을 보여줍니다.

163 

164대화 상자는 또한 요금제 제한에 기여하는 것을 분석합니다. 캐시 미스, 긴 컨텍스트, 서브에이전트 집약적 또는 고도로 병렬 세션 등 최근 사용량의 10% 이상을 차지하는 동작에 플래그를 지정하며, 각각에 대해 이를 줄이기 위한 팁을 제공합니다. 속성 테이블은 각 스킬, 서브에이전트, 플러그인 및 MCP 서버에서 얼마나 많은 사용량이 발생했는지 보여줍니다. Claude Code v2.1.174 이상이 필요합니다.

165 

166일일 및 주간 토글을 사용하여 지난 24시간과 지난 7일 사이를 전환합니다. 수치는 대략적이며 이 컴퓨터의 로컬 세션에서 계산되므로 다른 기기 또는 claude.ai의 사용량은 포함되지 않습니다. 사용량 추적 및 감소에 대한 자세한 내용은 [비용 추적](/ko/costs#track-your-costs)을 참조하십시오.

167 

158<h2 id="customize-your-workflow">168<h2 id="customize-your-workflow">

159 워크플로우 사용자 정의169 워크플로우 사용자 정의

160</h2>170</h2>


366 VS Code 확장 프로그램 vs. Claude Code CLI376 VS Code 확장 프로그램 vs. Claude Code CLI

367</h2>377</h2>

368 378 

369Claude Code는 VS Code 확장 프로그램(그래픽 패널)과 CLI(터미널의 명령줄 인터페이스) 모두로 사용 가능합니다. 일부 기능은 CLI에서만 사용 가능합니다. CLI 전용 기능이 필요한 경우 VS Code의 통합 터미널에서 `claude`를 실행합니다.379Claude Code는 VS Code 확장 프로그램(그래픽 패널)과 CLI(터미널의 명령줄 인터페이스) 모두로 사용 가능합니다. 일부 기능은 CLI에서만 사용 가능합니다. CLI 전용 기능이 필요한 경우 VS Code의 통합 터미널에서 `claude`를 실행합니다. 이를 위해서는 [독립 실행형 CLI 설치](/ko/setup)가 필요합니다. 확장 프로그램은 `claude`를 PATH에 추가하지 않습니다. [VS Code에서 CLI 실행](#run-cli-in-vs-code)을 참조하십시오.

370 380 

371| 기능 | CLI | VS Code 확장 프로그램 |381| 기능 | CLI | VS Code 확장 프로그램 |

372| ------------ | ------------------ | ------------------------------------------- |382| ------------ | ------------------ | ------------------------------------------- |


394 404 

395VS Code에 머물면서 CLI를 사용하려면 통합 터미널(Windows/Linux에서 `` Ctrl+` `` 또는 Mac에서 `` Cmd+` ``)을 열고 `claude`를 실행합니다. CLI는 diff 보기 및 진단 공유와 같은 기능을 위해 IDE와 자동으로 통합됩니다.405VS Code에 머물면서 CLI를 사용하려면 통합 터미널(Windows/Linux에서 `` Ctrl+` `` 또는 Mac에서 `` Cmd+` ``)을 열고 `claude`를 실행합니다. CLI는 diff 보기 및 진단 공유와 같은 기능을 위해 IDE와 자동으로 통합됩니다.

396 406 

407확장 프로그램을 설치해도 `claude`가 셸 PATH에 추가되지 않습니다. 확장 프로그램은 채팅 패널을 위해 CLI의 비공개 복사본을 번들로 제공하지만, 터미널에서 `claude`를 입력하려면 [독립 실행형 CLI 설치](/ko/setup)가 필요합니다. 설치를 한 번 실행하면 이 페이지의 명령(예: `claude mcp add` 및 `claude --resume`)이 모든 터미널에서 작동합니다. 설치 후에도 `claude`를 찾을 수 없으면 [PATH 확인](/ko/troubleshoot-install#verify-your-path)을 참조하십시오.

408 

397외부 터미널을 사용하는 경우 Claude Code 내에서 `/ide`를 실행하여 VS Code에 연결합니다.409외부 터미널을 사용하는 경우 Claude Code 내에서 `/ide`를 실행하여 VS Code에 연결합니다.

398 410 

399<h3 id="switch-between-extension-and-cli">411<h3 id="switch-between-extension-and-cli">


530 일반적인 문제 해결542 일반적인 문제 해결

531</h2>543</h2>

532 544 

533<h3 id="extension-won-t-install">545<h3 id="extension-wont-install">

534 확장 프로그램이 설치되지 않음546 확장 프로그램이 설치되지 않음

535</h3>547</h3>

536 548 


5862. "Claude Code" 검색5982. "Claude Code" 검색

5873. **제거** 클릭5993. **제거** 클릭

588 600 

589확장 프로그램 데이터를 제거하고 모든 설정을 재설정하려면:601확장 프로그램 데이터를 제거하고 모든 설정을 재설정하려면 플랫폼에 해당하는 확장 프로그램의 저장소 디렉터리를 삭제하십시오.

602 

603macOS에서:

590 604 

591```bash theme={null}605```bash theme={null}

592rm -rf ~/.vscode/globalStorage/anthropic.claude-code606rm -rf ~/Library/"Application Support"/Code/User/globalStorage/anthropic.claude-code

607```

608 

609Linux에서:

610 

611```bash theme={null}

612rm -rf ~/.config/Code/User/globalStorage/anthropic.claude-code

613```

614 

615Windows에서 PowerShell에서:

616 

617```powershell theme={null}

618Remove-Item -Recurse -Force "$env:APPDATA\Code\User\globalStorage\anthropic.claude-code"

593```619```

594 620 

595추가 도움말은 [문제 해결 가이드](/ko/troubleshooting)를 참조하십시오.621추가 도움말은 [문제 해결 가이드](/ko/troubleshooting)를 참조하십시오.

Details

129 </Step>129 </Step>

130 130 

131 <Step title="권한 모드 선택">131 <Step title="권한 모드 선택">

132 입력 옆의 모드 드롭다운은 기본값으로 **편집 자동 수락**이며, Claude는 승인을 기다리지 않고 변경 사항을 만들고 브랜치를 푸시합니다. Claude가 접근 방식을 제안하고 파일을 편집하기 전에 승인을 기다리도록 하려면 **Plan mode**로 전환합니다. 클라우드 세션은 Ask 권한, Auto 모드 또는 Bypass 권한을 제공하지 않습니다. 전체 목록은 [권한 모드](/ko/permission-modes)를 참조합니다.132 입력 옆의 모드 드롭다운은 기본값으로 **편집 자동 수락**이며, Claude는 승인을 기다리지 않고 변경 사항을 만들고 브랜치를 푸시합니다. Claude가 접근 방식을 제안하고 파일을 편집하기 전에 승인을 기다리도록 하려면 **Plan Mode**로 전환합니다. 클라우드 세션은 Ask 권한 또는 Bypass 권한을 제공하지 않습니다. 전체 목록은 [권한 모드](/ko/permission-modes)를 참조합니다.

133 </Step>133 </Step>

134 134 

135 <Step title="작업 설명 및 제출">135 <Step title="작업 설명 및 제출">

whats-new.md +16 −0

Details

8 8 

9주간 개발자 다이제스트는 업무 방식을 바꿀 가능성이 가장 높은 기능들을 강조합니다. 각 항목에는 실행 가능한 코드, 짧은 데모, 그리고 전체 문서로의 링크가 포함됩니다. 모든 버그 수정 및 사소한 개선 사항은 [changelog](/ko/changelog)를 참조하십시오.9주간 개발자 다이제스트는 업무 방식을 바꿀 가능성이 가장 높은 기능들을 강조합니다. 각 항목에는 실행 가능한 코드, 짧은 데모, 그리고 전체 문서로의 링크가 포함됩니다. 모든 버그 수정 및 사소한 개선 사항은 [changelog](/ko/changelog)를 참조하십시오.

10 10 

11<Update label="Week 24" description="2026년 6월 8–12일" tags={["v2.1.166–v2.1.176"]}>

12 **`/cd`**: 프롬프트 캐시를 다시 구축하지 않고 대화 중간에 현재 세션을 새로운 작업 디렉토리로 이동합니다.

13 

14 이번 주의 다른 기능들: **sub-agents는 자신의 sub-agents를 생성할 수 있습니다** (백그라운드 체인은 5단계 깊이로 제한됨); \*\*`--safe-mode`\*\*는 문제 해결을 위해 모든 사용자 정의를 비활성화한 상태로 Claude Code를 시작합니다; 그리고 \*\*`fallbackModel`\*\*은 순서대로 시도되는 최대 3개의 폴백 모델을 구성합니다.

15 

16 [Week 24 다이제스트 읽기 →](/ko/whats-new/2026-w24)

17</Update>

18 

19<Update label="Week 23" description="2026년 6월 1–5일" tags={["v2.1.158–v2.1.165"]}>

20 **Bedrock, Vertex, 그리고 Foundry의 Auto mode**: auto mode는 이제 Opus 4.7 및 Opus 4.8에 대해 타사 제공자에서 사용 가능하며, 권한 프롬프트를 백그라운드 안전 검사로 대체합니다.

21 

22 이번 주의 다른 기능들: **더 안전한 자동 편집**은 `acceptEdits` 모드에서 코드를 실행할 수 있는 파일을 작성하기 전에 프롬프트를 표시합니다; \*\*`/plugin list`\*\*는 설치된 플러그인을 인라인으로 출력합니다; 그리고 **version requirements**는 관리되는 배포에서 승인된 Claude Code 버전 범위를 요구할 수 있습니다.

23 

24 [Week 23 다이제스트 읽기 →](/ko/whats-new/2026-w23)

25</Update>

26 

11<Update label="Week 22" description="2026년 5월 25–29일" tags={["v2.1.150–v2.1.157"]}>27<Update label="Week 22" description="2026년 5월 25–29일" tags={["v2.1.150–v2.1.157"]}>

12 **Claude Opus 4.8**: Max, Team Premium, Enterprise 종량제, 그리고 Anthropic API 계정의 새로운 기본 모델로, 기본적으로 높은 노력 수준을 제공하며 가장 어려운 작업을 위해 `/effort xhigh`를 지원합니다.28 **Claude Opus 4.8**: Max, Team Premium, Enterprise 종량제, 그리고 Anthropic API 계정의 새로운 기본 모델로, 기본적으로 높은 노력 수준을 제공하며 가장 어려운 작업을 위해 `/effort xhigh`를 지원합니다.

13 29 

whats-new/2026-w23.md +100 −0 created

Details

1> ## Documentation Index

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

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

4 

5# 23주차 · 2026년 6월 1–5일

6 

7> Bedrock, Vertex, Foundry에서 자동 모드 실행, acceptEdits 모드에서 코드를 실행할 수 있는 파일 작성 전 프롬프트 표시, /plugin list로 설치된 플러그인 나열, 관리형 배포를 위한 승인된 버전 범위 필수.

8 

9<div className="digest-meta">

10 <span>릴리스 <a href="/ko/docs/changelog#2-1-158">v2.1.158 → v2.1.165</a></span>

11 <span>4가지 기능 · 6월 1–5일</span>

12</div>

13 

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">Bedrock, Vertex, Foundry에서 자동 모드</span>

17 <span className="digest-feature-pill">v2.1.158</span>

18 </div>

19 

20 <p className="digest-feature-lede">자동 모드는 이제 Opus 4.7 및 Opus 4.8용 Bedrock, Vertex, Foundry에서 사용 가능하며, 권한 프롬프트를 타사 제공자의 백그라운드 안전 검사로 대체합니다. <code>CLAUDE\_CODE\_ENABLE\_AUTO\_MODE=1</code>을 설정하여 옵트인합니다.</p>

21 

22 <p className="digest-feature-try">타사 제공자에서 옵트인한 후 Shift+Tab으로 자동 모드로 전환합니다:</p>

23 

24 ```bash terminal theme={null}

25 export CLAUDE_CODE_ENABLE_AUTO_MODE=1

26 ```

27 

28 <a className="digest-feature-link" href="/ko/docs/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry">타사 제공자에서 자동 모드 활성화</a>

29</div>

30 

31<div className="digest-feature">

32 <div className="digest-feature-header">

33 <span className="digest-feature-title">더 안전한 자동 편집</span>

34 <span className="digest-feature-pill">v2.1.160</span>

35 </div>

36 

37 <p className="digest-feature-lede">Claude Code는 이제 <code>acceptEdits</code> 모드에서도 코드를 실행할 수 있는 파일을 작성하기 전에 프롬프트를 표시합니다. 보호된 집합은 <code>.zshenv</code> 및 <code>.bash\_login</code>과 같은 셸 시작 파일, <code>\~/.config/git/</code> 아래의 git 구성, <code>.npmrc</code>, <code>.bazelrc</code>, <code>.pre-commit-config.yaml</code>과 같은 빌드 도구 구성을 포함합니다. 이러한 쓰기는 <code>bypassPermissions</code>을 제외한 어떤 모드에서도 자동으로 승인되지 않습니다.</p>

38 

39 <p className="digest-feature-try">acceptEdits 모드에서 작업합니다. Claude는 이제 이러한 파일을 작성하기 전에 일시 중지합니다:</p>

40 

41 ```bash terminal theme={null}

42 claude --permission-mode acceptEdits

43 ```

44 

45 <a className="digest-feature-link" href="/ko/docs/permission-modes#protected-paths">보호된 경로</a>

46</div>

47 

48<div className="digest-feature">

49 <div className="digest-feature-header">

50 <span className="digest-feature-title">/plugin list로 설치된 플러그인 나열</span>

51 <span className="digest-feature-pill">v2.1.163</span>

52 </div>

53 

54 <p className="digest-feature-lede">새로운 <code>/plugin list</code> 명령은 <code>/plugin</code> 메뉴를 열지 않고 설치된 플러그인을 인라인으로 출력하며, 셸에서 <code>claude plugin list</code>로도 사용할 수 있습니다. 대화형 형식에서 `--enabled` 또는 `--disabled`를 추가하여 해당 상태의 플러그인만 표시합니다.</p>

55 

56 <p className="digest-feature-try">현재 켜져 있는 플러그인을 나열합니다:</p>

57 

58 ```text Claude Code theme={null}

59 > /plugin list --enabled

60 ```

61 

62 <a className="digest-feature-link" href="/ko/docs/plugins-reference#plugin-list">플러그인 명령</a>

63</div>

64 

65<div className="digest-feature">

66 <div className="digest-feature-header">

67 <span className="digest-feature-title">관리형 배포를 위한 버전 요구사항</span>

68 <span className="digest-feature-pill">v2.1.163</span>

69 </div>

70 

71 <p className="digest-feature-lede">두 가지 관리형 설정인 <code>requiredMinimumVersion</code> 및 <code>requiredMaximumVersion</code>을 통해 조직에서 승인된 Claude Code 버전 범위를 요구할 수 있습니다. 범위를 벗어난 클라이언트는 시작 시 종료되고 사용자에게 조직의 방법을 통해 업데이트하도록 지시합니다. <code>claude update</code>, <code>claude install</code>, <code>claude doctor</code>는 계속 작동하므로 사용자가 여전히 복구할 수 있습니다.</p>

72 

73 <p className="digest-feature-try">관리형 설정에 하한을 추가하여 이전 클라이언트가 시작을 거부하도록 합니다:</p>

74 

75 ```json managed-settings.json theme={null}

76 "requiredMinimumVersion": "2.1.163"

77 ```

78 

79 <a className="digest-feature-link" href="/ko/docs/admin-setup#decide-what-to-enforce">적용할 항목 결정</a>

80</div>

81 

82<div className="digest-wins">

83 <p className="digest-wins-title">기타 개선사항</p>

84 

85 <div className="digest-wins-grid">

86 <div><a href="/ko/docs/workflows">동적 워크플로우</a>의 트리거 키워드가 <code>workflow</code>에서 <code>ultracode</code>로 변경되었습니다. 자신의 말로 워크플로우를 요청하면 여전히 작동하며, 키워드는 프롬프트에서 보라색으로 강조됩니다</div>

87 <div><a href="/ko/docs/hooks">Stop 및 SubagentStop 훅</a>은 <code>hookSpecificOutput.additionalContext</code>를 반환하여 Claude에 피드백을 제공하고 오류로 처리되는 대신 턴을 계속 진행할 수 있습니다</div>

88 <div><code>claude mcp</code> list, get, add는 더 이상 비밀을 출력하지 않습니다. 환경 변수 참조는 확장되지 않으며, 자격 증명 헤더 및 URL 비밀은 수정됩니다</div>

89 <div>병렬 도구 배치에서 실패한 Bash 명령은 더 이상 다른 명령을 취소하지 않습니다. 각 도구는 독립적으로 자신의 결과를 반환합니다</div>

90 <div>단일 파일 <code>grep</code>, <code>egrep</code>, <code>fgrep</code>으로 파일을 본 경우 파일을 편집할 때 더 이상 별도의 Read가 필요하지 않습니다</div>

91 <div>자동 완성 메뉴에서 명령을 클릭하면 즉시 실행하는 대신 프롬프트에 입력됩니다. Enter를 눌러 실행합니다</div>

92 <div><code>--tools</code>에 <code>Grep</code> 또는 <code>Glob</code>을 나열하면 이제 이름을 자동으로 무시하는 대신 임베드된 검색이 있는 네이티브 빌드에서 전용 검색 도구를 제공합니다</div>

93 <div><code>/effort</code>는 이제 선택한 수준이 새 세션의 기본값으로 유지될 때 확인합니다</div>

94 <div><code>OTEL\_RESOURCE\_ATTRIBUTES</code> 값은 이제 메트릭 데이터포인트의 레이블로 첨부되므로 팀 또는 리포지토리와 같은 사용자 정의 차원으로 사용 메트릭을 분할할 수 있습니다</div>

95 <div>Windsurf는 <code>/ide</code>, <code>/terminal-setup</code>, <code>/scroll-speed</code>에서 Devin Desktop으로 이름이 변경되었으며, 편집기의 브랜드 변경을 따릅니다</div>

96 <div><code>/btw</code>는 원본 마크다운 답변을 클립보드에 복사하는 <code>c to copy</code> 바로 가기를 얻습니다</div>

97 </div>

98</div>

99 

100[v2.1.158–v2.1.165 전체 변경 로그 →](/ko/changelog#2-1-158)

whats-new/2026-w24.md +84 −0 created

Details

1> ## Documentation Index

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

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

4 

5# 24주차 · 2026년 6월 8–12일

6 

7> /cd로 세션을 새 디렉토리로 이동하고, 하위 에이전트가 자신의 하위 에이전트를 생성하도록 하며, 안전 모드로 손상된 구성을 문제 해결합니다.

8 

9<div className="digest-meta">

10 <span>릴리스 <a href="/ko/docs/changelog#2-1-166">v2.1.166 → v2.1.176</a></span>

11 <span>3가지 기능 · 6월 8–12일</span>

12</div>

13 

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">/cd로 세션 이동</span>

17 <span className="digest-feature-pill">v2.1.169</span>

18 </div>

19 

20 <p className="digest-feature-lede">새로운 <code>/cd</code> 명령어는 프롬프트 캐시를 다시 빌드하지 않고 현재 세션을 다른 작업 디렉토리로 이동합니다. 새 디렉토리의 <code>CLAUDE.md</code>는 시스템 프롬프트를 대체하는 대신 메시지로 추가됩니다. 세션이 새 디렉토리의 프로젝트 저장소로 재배치되므로 `--resume`과 `--continue`가 그곳에서 찾습니다. Claude는 이전에 해당 디렉토리에서 작업하지 않은 경우 디렉토리를 신뢰하도록 사용자에게 요청합니다.</p>

21 

22 <p className="digest-feature-try">다시 시작하지 않고 세션을 다른 프로젝트로 이동합니다:</p>

23 

24 ```text Claude Code theme={null}

25 > /cd ../other-project

26 ```

27 

28 <a className="digest-feature-link" href="/ko/docs/commands#all-commands">명령어 참조</a>

29</div>

30 

31<div className="digest-feature">

32 <div className="digest-feature-header">

33 <span className="digest-feature-title">하위 에이전트가 하위 에이전트를 생성할 수 있음</span>

34 <span className="digest-feature-pill">v2.1.172</span>

35 </div>

36 

37 <p className="digest-feature-lede">하위 에이전트는 이제 자신의 하위 에이전트를 생성할 수 있습니다. 프롬프트 아래의 하위 에이전트 패널은 전체 트리를 표시합니다. 각 행은 자신의 하위 항목 개수와 <code>main</code>으로 돌아가는 경로를 포함합니다. 백그라운드 하위 에이전트는 실행 제어 불능 동시 트리를 방지하기 위해 5단계 깊이로 제한됩니다. 포그라운드 체인은 모든 깊이에서 생성될 수 있으며 자체 제한됩니다.</p>

38 

39 <p className="digest-feature-try">에이전트 보기를 열어 작업이 확산될 때 중첩된 트리를 확인합니다:</p>

40 

41 ```text Claude Code theme={null}

42 > /agents

43 ```

44 

45 <a className="digest-feature-link" href="/ko/docs/sub-agents#spawn-nested-subagents">중첩된 하위 에이전트 생성</a>

46</div>

47 

48<div className="digest-feature">

49 <div className="digest-feature-header">

50 <span className="digest-feature-title">안전 모드로 문제 해결</span>

51 <span className="digest-feature-pill">v2.1.169</span>

52 </div>

53 

54 <p className="digest-feature-lede">`--safe-mode`로 Claude Code를 시작하거나 <code>CLAUDE\_CODE\_SAFE\_MODE</code>를 설정하여 모든 사용자 정의가 비활성화된 상태로 시작합니다. <code>CLAUDE.md</code>, 스킬, 플러그인, 훅, MCP 서버, 사용자 정의 명령어 및 에이전트는 로드되지 않습니다. 인증, 모델 선택, 기본 제공 도구 및 권한은 계속 작동합니다. 안전 모드에서 문제가 사라지면 해당 표면 중 하나가 원인입니다.</p>

55 

56 <p className="digest-feature-try">손상된 구성을 격리하기 위해 깨끗한 세션을 시작합니다:</p>

57 

58 ```bash terminal theme={null}

59 claude --safe-mode

60 ```

61 

62 <a className="digest-feature-link" href="/ko/docs/debug-your-config#test-against-a-clean-configuration">깨끗한 구성에 대해 테스트</a>

63</div>

64 

65<div className="digest-wins">

66 <p className="digest-wins-title">기타 개선 사항</p>

67 

68 <div className="digest-wins-grid">

69 <div><a href="/ko/docs/model-config#fallback-model-chains"><code>fallbackModel</code></a>은 기본 모델이 과부하이거나 사용할 수 없을 때 순서대로 시도되는 최대 3개의 폴백 모델을 구성하며, `--fallback-model`은 이제 대화형 세션에도 적용됩니다</div>

70 <div>세션 제목은 이제 대화의 언어로 생성되며, <code>language</code> 설정으로 특정 제목을 고정할 수 있습니다</div>

71 <div>`claude agents --json`은 완료된 세션을 포함하기 위해 `--all`을 추가하고 새로운 <code>id</code> 및 <code>state</code> 필드를 추가하며, 더 이상 차단되거나 새로 발송된 세션을 생략하지 않습니다</div>

72 <div><code>/plugin</code>에서 마켓플레이스의 플러그인을 탐색할 때 이제 검색 표시줄이 있습니다</div>

73 <div>새로운 <code>disableBundledSkills</code> 설정 및 <code>CLAUDE\_CODE\_DISABLE\_BUNDLED\_SKILLS</code>는 번들된 스킬, 워크플로우 및 기본 제공 명령어를 모델에서 숨깁니다</div>

74 <div>거부 규칙은 도구 이름 위치에서 글로브를 허용하므로 <code>"\*"</code>는 모든 도구를 거부하며, 거부 규칙의 알 수 없는 도구 이름은 이제 시작 시 경고합니다</div>

75 <div>교차 세션 메시징이 강화되었습니다. 다른 세션에서 <code>SendMessage</code>를 통해 릴레이된 메시지는 더 이상 사용자 권한을 전달하지 않으며, 자동 모드는 이를 차단합니다</div>

76 <div>Amazon Bedrock은 <code>AWS\_REGION</code>이 설정되지 않은 경우 <code>\~/.aws</code> 구성 파일에서 AWS 지역을 읽으며, <code>/status</code>는 지역이 어디서 왔는지 표시합니다</div>

77 <div>새로운 <code>enforceAvailableModels</code> 관리 설정은 <code>availableModels</code> 허용 목록이 기본 모델도 제한하도록 합니다</div>

78 <div>Chrome 브라우저 도구의 Claude는 이제 도구당 하나씩이 아닌 단일 배치 호출로 로드됩니다</div>

79 <div><code>claude update</code>는 침묵하지 않고 다운로드하기 전에 대상 버전을 발표합니다</div>

80 <div>새로운 <code>footerLinksRegexes</code> 설정은 정규식 일치 링크 배지를 바닥글 행에 추가합니다</div>

81 </div>

82</div>

83 

84[v2.1.166–v2.1.176의 전체 변경 로그 →](/ko/changelog#2-1-166)

workflows.md +3 −1

Details

9{/* plan-availability: feature=workflows plans=pro,max,team,enterprise providers=all */}9{/* plan-availability: feature=workflows plans=pro,max,team,enterprise providers=all */}

10 10 

11<Note>11<Note>

12 동적 워크플로우는 연구 미리보기 상태입니다. Claude Code v2.1.154 이상이 필요하며 모든 유료 요금제, Anthropic API 액세스, Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry에서 사용 가능합니다. Pro에서는 `/config`의 동적 워크플로우 행에서 활성화하십시오.12 동적 워크플로우는 Claude Code v2.1.154 이상이 필요하며 모든 유료 요금제, Anthropic API 액세스, Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry에서 사용 가능합니다. Pro에서는 `/config`의 동적 워크플로우 행에서 활성화하십시오.

13</Note>13</Note>

14 14 

15동적 워크플로우는 대규모로 [서브에이전트](/ko/sub-agents)를 조율하는 JavaScript 스크립트입니다. Claude는 설명한 작업에 대한 스크립트를 작성하고, 런타임이 백그라운드에서 실행하는 동안 세션은 응답성을 유지합니다.15동적 워크플로우는 대규모로 [서브에이전트](/ko/sub-agents)를 조율하는 JavaScript 스크립트입니다. Claude는 설명한 작업에 대한 스크립트를 작성하고, 런타임이 백그라운드에서 실행하는 동안 세션은 응답성을 유지합니다.


198 198 

199Enter를 눌러 저장합니다. 워크플로우는 이후 세션에서 두 위치 중 하나에서 `/<name>`으로 실행됩니다.199Enter를 눌러 저장합니다. 워크플로우는 이후 세션에서 두 위치 중 하나에서 `/<name>`으로 실행됩니다.

200 200 

201{/* min-version: 2.1.178 */}v2.1.178부터 프로젝트 위치에 저장하면 작업 디렉토리와 저장소 루트 사이에 이미 존재하는 가장 가까운 `.claude/workflows/` 디렉토리에 쓰거나, 아직 존재하지 않으면 저장소 루트에 씁니다. 프로젝트 워크플로우는 또한 해당 경로를 따라 모든 `.claude/workflows/`에서 로드되며, 둘 이상이 같은 이름을 정의할 때 Claude Code는 작업 디렉토리에 가장 가까운 것을 실행합니다.

202 

201프로젝트 워크플로우와 개인 워크플로우가 이름을 공유하면 프로젝트 워크플로우가 실행됩니다.203프로젝트 워크플로우와 개인 워크플로우가 이름을 공유하면 프로젝트 워크플로우가 실행됩니다.

202 204 

203<h3 id="pass-input-to-a-saved-workflow">205<h3 id="pass-input-to-a-saved-workflow">

worktrees.md +3 −1

Details

36 36 

37세션 중에 Claude에게 "worktree에서 작업하기"를 요청할 수도 있으며, [`EnterWorktree`](/ko/tools-reference) 도구로 하나를 생성합니다. worktree에 들어가면 Claude는 `.claude/worktrees/` 아래의 다른 worktree로 `EnterWorktree`를 호출하여 직접 전환할 수 있습니다. 이전 worktree는 디스크에 그대로 남아 있습니다.37세션 중에 Claude에게 "worktree에서 작업하기"를 요청할 수도 있으며, [`EnterWorktree`](/ko/tools-reference) 도구로 하나를 생성합니다. worktree에 들어가면 Claude는 `.claude/worktrees/` 아래의 다른 worktree로 `EnterWorktree`를 호출하여 직접 전환할 수 있습니다. 이전 worktree는 디스크에 그대로 남아 있습니다.

38 38 

39처음으로 디렉터리에서 `--worktree`를 사용하기 전에 해당 디렉터리에서 `claude`를 한 번 실행하여 작업 공간 신뢰 대화를 수락합니다. 신뢰가 아직 수락되지 않았으면 `--worktree`는 오류와 함께 종료되고 먼저 디렉터리에서 `claude`를 실행하도록 요청하며, `-p` 결합할 때도 마찬가지입니다.39처음으로 디렉터리에서 `--worktree`를 사용하기 전에 해당 디렉터리에서 `claude`를 한 번 실행하여 작업 공간 신뢰 대화를 수락합니다. 신뢰가 아직 수락되지 않았으면 `--worktree`는 오류와 함께 종료되고 먼저 디렉터리에서 `claude`를 실행하도록 요청합니다. `-p` 사용한 비대화형 실행은 [신뢰 확인](/ko/security)을 건너뛰므로 `claude -p --worktree`는 이를 수행하지 않고 진행됩니다.

40 40 

41<Tip>41<Tip>

42 `.claude/worktrees/`를 `.gitignore`에 추가하여 worktree 내용이 메인 체크아웃에서 추적되지 않은 파일로 나타나지 않도록 합니다.42 `.claude/worktrees/`를 `.gitignore`에 추가하여 worktree 내용이 메인 체크아웃에서 추적되지 않은 파일로 나타나지 않도록 합니다.


102 102 

103Claude가 서브에이전트 및 [백그라운드 세션](/ko/agent-view#how-file-edits-are-isolated)을 위해 생성한 worktree는 [`cleanupPeriodDays`](/ko/settings#available-settings) 설정보다 오래되면 자동으로 제거되며, 커밋되지 않은 변경 사항, 추적되지 않은 파일 및 푸시되지 않은 커밋이 없는 경우입니다. `--worktree`로 생성한 worktree는 이 스윕으로 절대 제거되지 않습니다.103Claude가 서브에이전트 및 [백그라운드 세션](/ko/agent-view#how-file-edits-are-isolated)을 위해 생성한 worktree는 [`cleanupPeriodDays`](/ko/settings#available-settings) 설정보다 오래되면 자동으로 제거되며, 커밋되지 않은 변경 사항, 추적되지 않은 파일 및 푸시되지 않은 커밋이 없는 경우입니다. `--worktree`로 생성한 worktree는 이 스윕으로 절대 제거되지 않습니다.

104 104 

105에이전트가 실행 중인 동안 Claude는 해당 worktree에서 `git worktree lock`을 실행하여 동시 정리가 이를 제거할 수 없도록 합니다. 에이전트가 완료되면 잠금이 해제됩니다. 스윕이 유지하는 worktree를 정리하려면 `git worktree remove`를 실행하고, worktree에 커밋되지 않은 변경 사항이나 추적되지 않은 파일이 있으면 `--force`를 추가합니다.

106 

105<h2 id="manage-worktrees-manually">107<h2 id="manage-worktrees-manually">

106 worktree 수동 관리108 worktree 수동 관리

107</h2>109</h2>

Details

8 8 

9Zero Data Retention(ZDR)은 Claude for Enterprise를 통해 사용할 때 Claude Code에서 사용 가능합니다. ZDR이 활성화되면 Claude Code 세션 중에 생성된 프롬프트와 모델 응답은 실시간으로 처리되며 응답이 반환된 후 Anthropic에서 저장되지 않습니다. 단, 법률 준수 또는 오용 방지가 필요한 경우는 제외합니다.9Zero Data Retention(ZDR)은 Claude for Enterprise를 통해 사용할 때 Claude Code에서 사용 가능합니다. ZDR이 활성화되면 Claude Code 세션 중에 생성된 프롬프트와 모델 응답은 실시간으로 처리되며 응답이 반환된 후 Anthropic에서 저장되지 않습니다. 단, 법률 준수 또는 오용 방지가 필요한 경우는 제외합니다.

10 10 

11<Note>

12 ZDR은 표준 Claude for Enterprise 플랜에 포함되지 않으며 관리자 설정에서 활성화할 수 없습니다. 이는 적격 계정에서만 사용 가능하며 Anthropic의 별도 활성화가 필요합니다. 조직에서 ZDR이 필요한 경우 [영업팀에 문의](https://www.anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=zero_data_retention_request)하거나 Anthropic 계정 담당자에게 연락하여 적격 여부를 확인하세요.

13</Note>

14 

11Claude for Enterprise의 ZDR은 엔터프라이즈 고객에게 Zero Data Retention으로 Claude Code를 사용하고 관리 기능에 액세스할 수 있는 기능을 제공합니다:15Claude for Enterprise의 ZDR은 엔터프라이즈 고객에게 Zero Data Retention으로 Claude Code를 사용하고 관리 기능에 액세스할 수 있는 기능을 제공합니다:

12 16 

13* 사용자별 비용 제어17* 사용자별 비용 제어


31 ZDR이 포함하는 것35 ZDR이 포함하는 것

32</h3>36</h3>

33 37 

34ZDR은 Claude for Enterprise의 Claude Code를 통해 이루어진 모델 추론 호출을 포함합니다. 터미널에서 Claude Code를 사용할 때 전송하는 프롬프트와 Claude가 생성하는 응답은 Anthropic에서 보존되지 않습니다. 이는 사용되는 Claude 모델에 관계없이 적용됩니다.38ZDR은 Claude for Enterprise의 Claude Code를 통해 이루어진 모델 추론 호출을 포함합니다. 터미널에서 Claude Code를 사용할 때 전송하는 프롬프트와 Claude가 생성하는 응답은 Anthropic에서 보존되지 않습니다. 이는 ZDR 조직에서 사용 가능한 모든 모델에 적용됩니다. 일부 모델은 데이터 보존이 필요하며 ZDR에서 사용할 수 없습니다. [ZDR에서의 모델 가용성](#model-availability-under-zdr)을 참조하세요.

35 39 

36<h3 id="what-zdr-does-not-cover">40<h3 id="what-zdr-does-not-cover">

37 ZDR이 포함하지 않는 것41 ZDR이 포함하지 않는 것


54Claude for Enterprise의 Claude Code 조직에 대해 ZDR이 활성화되면 프롬프트 또는 완성을 저장해야 하는 특정 기능이 백엔드 수준에서 자동으로 비활성화됩니다:58Claude for Enterprise의 Claude Code 조직에 대해 ZDR이 활성화되면 프롬프트 또는 완성을 저장해야 하는 특정 기능이 백엔드 수준에서 자동으로 비활성화됩니다:

55 59 

56| 기능 | 이유 |60| 기능 | 이유 |

57| ----------------------------------------------- | ------------------------------------ |61| ------------------------------------------------ | ------------------------------------ |

58| [웹의 Claude Code](/ko/claude-code-on-the-web) | 대화 기록의 서버 측 저장이 필요합니다. |62| [웹의 Claude Code](/ko/claude-code-on-the-web) | 대화 기록의 서버 측 저장이 필요합니다. |

59| Desktop 앱의 [원격 세션](/ko/desktop#remote-sessions) | 프롬프트 및 완성을 포함하는 지속적인 세션 데이터가 필요합니다. |63| Desktop 앱의 [클라우드 세션](/ko/desktop#cloud-sessions) | 프롬프트 및 완성을 포함하는 지속적인 세션 데이터가 필요합니다. |

60| 피드백 제출(`/feedback`) | 피드백을 제출하면 대화 데이터가 Anthropic으로 전송됩니다. |64| 피드백 제출(`/feedback`) | 피드백을 제출하면 대화 데이터가 Anthropic으로 전송됩니다. |

61 65 

62이러한 기능은 클라이언트 측 표시에 관계없이 백엔드에서 차단됩니다. 시작 중에 Claude Code 터미널에서 비활성화된 기능이 표시되면 이를 사용하려고 시도하면 조직의 정책이 해당 작업을 허용하지 않음을 나타내는 오류가 반환됩니다.66이러한 기능은 클라이언트 측 표시에 관계없이 백엔드에서 차단됩니다. 시작 중에 Claude Code 터미널에서 비활성화된 기능이 표시되면 이를 사용하려고 시도하면 조직의 정책이 해당 작업을 허용하지 않음을 나타내는 오류가 반환됩니다.

63 67 

64향후 기능도 프롬프트 또는 완성을 저장해야 하는 경우 비활성화될 수 있습니다.68향후 기능도 프롬프트 또는 완성을 저장해야 하는 경우 비활성화될 수 있습니다.

65 69 

70<h3 id="model-availability-under-zdr">

71 ZDR에서의 모델 가용성

72</h3>

73 

74Claude Fable 5는 영구 데이터 보존 비활성화가 활성화된 조직에서는 사용할 수 없습니다. 이 모델 클래스는 [데이터 보존이 필요하므로](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements) ZDR 조직의 요청은 이를 통해 처리될 수 없습니다. 모델은 ZDR 조직의 `/model` 선택기에서 없거나 ZDR을 비활성화해야 한다는 공지와 함께 비활성화된 것으로 표시되며, 클라이언트 구성에 관계없이 서버는 이에 대한 요청을 거부합니다.

75 

76다른 모델은 ZDR에서 계속 사용할 수 있습니다. Fable 5는 기본 모델이 아니며, Fable 5가 사용 가능한 경우 Fable 5로 확인되는 `best` 별칭은 ZDR 조직을 포함하여 사용할 수 없는 조직의 경우 Opus로 확인됩니다.

77 

66<h2 id="data-retention-for-policy-violations">78<h2 id="data-retention-for-policy-violations">

67 정책 위반에 대한 데이터 보존79 정책 위반에 대한 데이터 보존

68</h2>80</h2>