28 28 

29대화 계층의 변경은 시스템 프롬프트와 프로젝트 컨텍스트를 캐시된 상태로 유지합니다. 시스템 프롬프트의 변경은 모든 것을 무효화합니다. 왜냐하면 이제 모든 이후 콘텐츠가 다른 프리픽스 뒤에 있기 때문입니다. 세 번째 열은 완전한 목록이 아닌 일반적인 트리거를 제공하며, 아래 섹션에서 전체 집합을 다룹니다.29대화 계층의 변경은 시스템 프롬프트와 프로젝트 컨텍스트를 캐시된 상태로 유지합니다. 시스템 프롬프트의 변경은 모든 것을 무효화합니다. 왜냐하면 이제 모든 이후 콘텐츠가 다른 프리픽스 뒤에 있기 때문입니다. 세 번째 열은 완전한 목록이 아닌 일반적인 트리거를 제공하며, 아래 섹션에서 전체 집합을 다룹니다.

30 30 

31프리픽스 일치 규칙은 이 페이지의 대부분의 동작을 설명합니다. 예를 들어 [플랜 모드](/docs/ko/permission-modes.md#analyze-before-you-edit-with-plan-mode)와 [스킬 로딩](/docs/ko/skills.md)은 지침을 대화 메시지로 추가하므로 캐시된 프리픽스는 그대로 유지됩니다.31프리픽스 일치 규칙은 이 페이지의 대부분의 동작을 설명합니다. 예를 들어 [플랜 모드](https://code.claude.com/docs/ko/permission-modes.md#analyze-before-you-edit-with-plan-mode)와 [스킬 로딩](https://code.claude.com/docs/ko/skills.md)은 지침을 대화 메시지로 추가하므로 캐시된 프리픽스는 그대로 유지됩니다.

32 32 

33두 가지 설정은 계층 표에 나타나지 않지만 여전히 캐시된 상태에 영향을 미칩니다:33두 가지 설정은 계층 표에 나타나지 않지만 여전히 캐시된 상태에 영향을 미칩니다:

34 34 

43 43 

44캐싱은 서버 측에서 발생하며, 모델을 제공하는 인프라에서 발생합니다. 그 위치는 인증 방식에 따라 다릅니다:44캐싱은 서버 측에서 발생하며, 모델을 제공하는 인프라에서 발생합니다. 그 위치는 인증 방식에 따라 다릅니다:

45 45 

46* **API 키, Claude 구독 또는 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws.md)**: 캐시는 Anthropic의 인프라에 있으며 [Claude API](https://platform.claude.com/docs)를 통해 액세스됩니다.46* **API 키, Claude 구독 또는 [Claude Platform on AWS](https://code.claude.com/docs/ko/claude-platform-on-aws.md)**: 캐시는 Anthropic의 인프라에 있으며 [Claude API](https://platform.claude.com/docs)를 통해 액세스됩니다.

47* **Amazon Bedrock 또는 Google Cloud의 Agent Platform**: 캐시는 클라우드 제공자의 제공 인프라에 있습니다.47* **Amazon Bedrock 또는 Google Cloud의 Agent Platform**: 캐시는 클라우드 제공자의 제공 인프라에 있습니다.

48* **Microsoft Foundry**: 배포의 [호스팅 옵션](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)에 따라 다릅니다. Azure에서 호스팅되는 배포는 Azure 인프라에서 제공되고, Anthropic에서 호스팅되는 배포는 Anthropic의 인프라에서 제공됩니다.48* **Microsoft Foundry**: 배포의 [호스팅 옵션](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)에 따라 다릅니다. Azure에서 호스팅되는 배포는 Azure 인프라에서 제공되고, Anthropic에서 호스팅되는 배포는 Anthropic의 인프라에서 제공됩니다.

49* **사용자 정의 `ANTHROPIC_BASE_URL` 또는 [LLM gateway](/docs/ko/llm-gateway)**: 캐시는 요청이 전달되는 위치에 있으며, 캐싱이 작동하는지 여부는 게이트웨이에 따라 다릅니다.49* **사용자 정의 `ANTHROPIC_BASE_URL` 또는 [LLM gateway](https://code.claude.com/docs/ko/llm-gateway)**: 캐시는 요청이 전달되는 위치에 있으며, 캐싱이 작동하는지 여부는 게이트웨이에 따라 다릅니다.

50 50 

51Claude Code는 또한 파일 변경 알림과 같은 시스템 컨텍스트를 대화 중에 추가하고, [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)를 설정하지 않는 한 모든 제공자 및 연결에서 캐싱을 위해 해당 블록을 표시합니다. 이 경우 해당 블록은 캐시되지 않은 상태로 전송됩니다.51Claude Code는 또한 파일 변경 알림과 같은 시스템 컨텍스트를 대화 중에 추가하고, [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](https://code.claude.com/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)를 설정하지 않는 한 모든 제공자 및 연결에서 캐싱을 위해 해당 블록을 표시합니다. 이 경우 해당 블록은 캐시되지 않은 상태로 전송됩니다.

52 52 

53제공자의 자체 엔드포인트에서 Amazon Bedrock 및 해당 [Mantle endpoint](/docs/ko/amazon-bedrock.md#use-the-mantle-endpoint), Google Cloud의 Agent Platform 및 Microsoft Foundry는 Claude API와 동일한 방식으로 블록을 캐시합니다.53제공자의 자체 엔드포인트에서 Amazon Bedrock 및 해당 [Mantle endpoint](https://code.claude.com/docs/ko/amazon-bedrock.md#use-the-mantle-endpoint), Google Cloud의 Agent Platform 및 Microsoft Foundry는 Claude API와 동일한 방식으로 블록을 캐시합니다.

54 54 

55요청이 [LLM gateway](/docs/ko/llm-gateway), 사용자 정의 `ANTHROPIC_BASE_URL` 또는 [`ANTHROPIC_BEDROCK_BASE_URL`](/docs/ko/env-vars)과 같은 클라우드 제공자 기본 URL 재정의를 통과할 때, 캐시된 상태는 게이트웨이가 Claude Code가 보내는 [`cache_control` 마커](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints)를 어떻게 처리하는지에 따라 다릅니다:55요청이 [LLM gateway](https://code.claude.com/docs/ko/llm-gateway), 사용자 정의 `ANTHROPIC_BASE_URL` 또는 [`ANTHROPIC_BEDROCK_BASE_URL`](https://code.claude.com/docs/ko/env-vars)과 같은 클라우드 제공자 기본 URL 재정의를 통과할 때, 캐시된 상태는 게이트웨이가 Claude Code가 보내는 [`cache_control` 마커](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints)를 어떻게 처리하는지에 따라 다릅니다:

56 56 

57* **변경되지 않은 상태로 전달**: 블록과 대화가 제공자의 자체 엔드포인트와 동일한 방식으로 캐시됩니다.57* **변경되지 않은 상태로 전달**: 블록과 대화가 제공자의 자체 엔드포인트와 동일한 방식으로 캐시됩니다.

58* **`cache_control`을 명명하는 `400` 오류로 표시된 요청 거부**: Claude Code는 마커를 블록에서 마지막 대화 메시지로 이동하여 요청을 다시 보내고, Claude Code가 종료될 때까지 그 상태를 유지합니다. 블록은 캐시되지 않은 입력으로 청구됩니다. 대화는 캐시된 상태로 유지됩니다.58* **`cache_control`을 명명하는 `400` 오류로 표시된 요청 거부**: Claude Code는 마커를 블록에서 마지막 대화 메시지로 이동하여 요청을 다시 보내고, Claude Code가 종료될 때까지 그 상태를 유지합니다. 블록은 캐시되지 않은 입력으로 청구됩니다. 대화는 캐시된 상태로 유지됩니다.

59* **성공을 반환하면서 마커 제거**: 전체 대화 기록이 매 턴마다 캐시되지 않은 입력으로 청구됩니다. 블록 형식 시스템 콘텐츠를 일반 문자열로 변환하는 게이트웨이는 동일한 방식으로 마커를 삭제합니다.59* **성공을 반환하면서 마커 제거**: 전체 대화 기록이 매 턴마다 캐시되지 않은 입력으로 청구됩니다. 블록 형식 시스템 콘텐츠를 일반 문자열로 변환하는 게이트웨이는 동일한 방식으로 마커를 삭제합니다.

60 60 

61각 제공자가 저장하고 처리하는 것에 대해서는 [data usage](/docs/ko/data-usage.md)를 참조하세요. 캐시가 어디에 있든 항목은 비활성 기간 후에 만료되며, 아래의 [Cache lifetime](#cache-lifetime)에서 TTL과 연장 방법을 다룹니다.61각 제공자가 저장하고 처리하는 것에 대해서는 [data usage](https://code.claude.com/docs/ko/data-usage.md)를 참조하세요. 캐시가 어디에 있든 항목은 비활성 기간 후에 만료되며, 아래의 [Cache lifetime](#cache-lifetime)에서 TTL과 연장 방법을 다룹니다.

62 62 

63## 캐시를 무효화하는 작업63## 캐시를 무효화하는 작업

64 64 

76 76 

77### 모델 전환77### 모델 전환

78 78 

79각 모델은 자체 캐시를 가집니다. [`/model`](/docs/ko/model-config#setting-your-model)로 전환하면 내용이 동일하더라도 다음 요청이 캐시 히트 없이 전체 대화 기록을 읽습니다.79각 모델은 자체 캐시를 가집니다. [`/model`](https://code.claude.com/docs/ko/model-config#setting-your-model)로 전환하면 내용이 동일하더라도 다음 요청이 캐시 히트 없이 전체 대화 기록을 읽습니다.

80 80 

81터미널에서 `/model`을 실행하면 Claude Code는 캐시가 여전히 따뜻하고 새 모델이 마지막 응답을 생성한 모델이 아닐 때만 전환을 확인하도록 요청합니다. 캐시는 Claude Code가 이 대화에서 마지막으로 요청을 보낸 후 또는 Claude가 마지막으로 응답한 후 한 번의 [캐시 TTL](#cache-lifetime) 동안 따뜻하게 유지됩니다. 그 시간이 지나면 캐시가 만료되므로 Claude Code는 묻지 않고 전환합니다.81터미널에서 `/model`을 실행하면 Claude Code는 캐시가 여전히 따뜻하고 새 모델이 마지막 응답을 생성한 모델이 아닐 때만 전환을 확인하도록 요청합니다. 캐시는 Claude Code가 이 대화에서 마지막으로 요청을 보낸 후 또는 Claude가 마지막으로 응답한 후 한 번의 [캐시 TTL](#cache-lifetime) 동안 따뜻하게 유지됩니다. 그 시간이 지나면 캐시가 만료되므로 Claude Code는 묻지 않고 전환합니다.

82 82 

83v2.1.238 이전에는 Claude Code가 캐시 TTL을 확인하지 않았고 캐시가 만료된 후에도 물었습니다.83v2.1.238 이전에는 Claude Code가 캐시 TTL을 확인하지 않았고 캐시가 만료된 후에도 물었습니다.

84 84 

85[PreModelSwitch 훅](/docs/ko/hooks.md#premodelswitch-decision-control)으로 이 확인을 요구하거나 건너뛸 수도 있습니다.85[PreModelSwitch 훅](https://code.claude.com/docs/ko/hooks.md#premodelswitch-decision-control)으로 이 확인을 요구하거나 건너뛸 수도 있습니다.

86 86 

87[`opusplan` 모델 설정](/docs/ko/model-config#opusplan-model-setting)은 플랜 모드 중에는 Opus로, 실행 중에는 Sonnet으로 확인되므로 각 플랜 모드 토글은 모델 전환이며 새로운 캐시를 시작합니다.87[`opusplan` 모델 설정](https://code.claude.com/docs/ko/model-config#opusplan-model-setting)은 플랜 모드 중에는 Opus로, 실행 중에는 Sonnet으로 확인되므로 각 플랜 모드 토글은 모델 전환이며 새로운 캐시를 시작합니다.

88 88 

89Fable 모델, Opus 5.5, Sonnet 5.5, Opus 5의 [자동 모델 폴백](/docs/ko/model-config.md#automatic-model-fallback)도 모델 전환입니다. 안전 분류기가 폴백 모델이 있는 카테고리의 요청에 플래그를 지정하면 Claude Code는 해당 모델에서 요청을 다시 실행하고 세션이 계속됩니다.89Fable 모델, Opus 5.5, Sonnet 5.5, Opus 5의 [자동 모델 폴백](https://code.claude.com/docs/ko/model-config.md#automatic-model-fallback)도 모델 전환입니다. 안전 분류기가 폴백 모델이 있는 카테고리의 요청에 플래그를 지정하면 Claude Code는 해당 모델에서 요청을 다시 실행하고 세션이 계속됩니다.

90 90 

91스킬 또는 명령의 frontmatter가 세션의 현재 모델이 아닌 다른 [`model`](/docs/ko/skills#frontmatter-reference)을 지정하면 해당 턴도 모델 전환입니다. 다음 요청은 캐시 히트 없이 전체 대화 기록을 읽습니다. 세션 모델은 다음 프롬프트에서 재개됩니다. `context: fork` 스킬은 [포크된 서브에이전트의 모델](/docs/ko/skills.md#run-skills-in-a-subagent)을 대신 설정합니다.91스킬 또는 명령의 frontmatter가 세션의 현재 모델이 아닌 다른 [`model`](https://code.claude.com/docs/ko/skills#frontmatter-reference)을 지정하면 해당 턴도 모델 전환입니다. 다음 요청은 캐시 히트 없이 전체 대화 기록을 읽습니다. 세션 모델은 다음 프롬프트에서 재개됩니다. `context: fork` 스킬은 [포크된 서브에이전트의 모델](https://code.claude.com/docs/ko/skills.md#run-skills-in-a-subagent)을 대신 설정합니다.

92 92 

93### effort 수준 변경93### effort 수준 변경

94 94 

95대부분의 모델에서 세션 중간에 [effort 수준](/docs/ko/model-config.md#adjust-effort-level)을 변경하면 다음 요청이 캐시 히트 없이 전체 대화 기록을 읽습니다. 캐시가 여전히 따뜻한 동안 Claude Code는 먼저 변경을 확인하도록 요청합니다.95대부분의 모델에서 세션 중간에 [effort 수준](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level)을 변경하면 다음 요청이 캐시 히트 없이 전체 대화 기록을 읽습니다. 캐시가 여전히 따뜻한 동안 Claude Code는 먼저 변경을 확인하도록 요청합니다.

96 96 

97API 키 또는 Claude 구독이 있는 Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.1에서는 effort를 변경해도 캐시가 유지되며 Claude Code는 묻지 않고 새 수준을 적용합니다. 이는 Amazon Bedrock, Google Cloud의 Agent Platform, [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)에는 적용되지 않으며, [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)를 설정했거나 조직에 HIPAA 구성이 있을 때도 적용되지 않습니다.97API 키 또는 Claude 구독이 있는 Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.1에서는 effort를 변경해도 캐시가 유지되며 Claude Code는 묻지 않고 새 수준을 적용합니다. 이는 Amazon Bedrock, Google Cloud의 Agent Platform, [Claude 앱 게이트웨이](https://code.claude.com/docs/ko/claude-apps-gateway)에는 적용되지 않으며, [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](https://code.claude.com/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)를 설정했거나 조직에 HIPAA 구성이 있을 때도 적용되지 않습니다.

98 98 

99v2.1.260 이전에는 API 키 또는 Claude 구독이 있는 Fable 5.1에서 effort를 변경해도 캐시가 무효화되었습니다.99v2.1.260 이전에는 API 키 또는 Claude 구독이 있는 Fable 5.1에서 effort를 변경해도 캐시가 무효화되었습니다.

100 100 

101### 빠른 모드 켜기101### 빠른 모드 켜기

102 102 

103[빠른 모드](/docs/ko/fast-mode.md)를 활성화하면 캐시 키의 일부인 요청 헤더가 추가되므로 Claude Code가 빠른 모드를 켜고 보내는 첫 번째 요청은 캐시 히트 없이 전체 대화 기록을 읽습니다. Claude Code는 턴이 시작될 때 해당 헤더를 한 번 설정하고 전체 턴 동안 유지하므로 Claude가 작업 중일 때 빠른 모드를 켜면 헤더로 인한 캐시 미스가 다음 턴의 첫 번째 요청에서 발생합니다. 캐시되지 않은 입력 토큰은 [빠른 모드 요금](/docs/ko/fast-mode.md#understand-the-cost-tradeoff)으로 청구되므로 세션 시작 시 켜는 것이 긴 세션 깊숙이 켜는 것보다 비용이 적습니다. 현재 모델이 빠른 모드를 지원하지 않으면 빠른 모드를 활성화하면 [모델도 전환](#switching-models)되며, 그 전환은 실행 중인 턴의 다음 요청부터 자체적으로 새로운 캐시를 시작합니다.103[빠른 모드](https://code.claude.com/docs/ko/fast-mode.md)를 활성화하면 캐시 키의 일부인 요청 헤더가 추가되므로 Claude Code가 빠른 모드를 켜고 보내는 첫 번째 요청은 캐시 히트 없이 전체 대화 기록을 읽습니다. Claude Code는 턴이 시작될 때 해당 헤더를 한 번 설정하고 전체 턴 동안 유지하므로 Claude가 작업 중일 때 빠른 모드를 켜면 헤더로 인한 캐시 미스가 다음 턴의 첫 번째 요청에서 발생합니다. 캐시되지 않은 입력 토큰은 [빠른 모드 요금](https://code.claude.com/docs/ko/fast-mode.md#understand-the-cost-tradeoff)으로 청구되므로 세션 시작 시 켜는 것이 긴 세션 깊숙이 켜는 것보다 비용이 적습니다. 현재 모델이 빠른 모드를 지원하지 않으면 빠른 모드를 활성화하면 [모델도 전환](#switching-models)되며, 그 전환은 실행 중인 턴의 다음 요청부터 자체적으로 새로운 캐시를 시작합니다.

104 104 

105비용은 대화당 한 번 적용됩니다. 첫 번째 빠른 모드 턴 후 Claude Code는 계속 헤더를 보내고 캐시 키의 일부가 아닌 요청의 속도 설정만 변합니다. 빠른 모드를 끄기, [속도 제한 후 표준 속도로 자동 폴백](/docs/ko/fast-mode.md#handle-rate-limits), 나중에 다시 켜기는 모두 캐시를 유지합니다. 세션 중간에 [사용량 크레딧이 소진](/docs/ko/fast-mode.md#handle-rate-limits)되면 Claude Code는 거부된 각 빠른 모드 요청을 같은 방식으로 표준 속도에서 재시도하므로 이 폴백도 캐시를 유지합니다. `/clear`와 `/compact`는 어쨌든 그 지점에서 캐시를 다시 빌드하므로 이를 재설정합니다.105비용은 대화당 한 번 적용됩니다. 첫 번째 빠른 모드 턴 후 Claude Code는 계속 헤더를 보내고 캐시 키의 일부가 아닌 요청의 속도 설정만 변합니다. 빠른 모드를 끄기, [속도 제한 후 표준 속도로 자동 폴백](https://code.claude.com/docs/ko/fast-mode.md#handle-rate-limits), 나중에 다시 켜기는 모두 캐시를 유지합니다. 세션 중간에 [사용량 크레딧이 소진](https://code.claude.com/docs/ko/fast-mode.md#handle-rate-limits)되면 Claude Code는 거부된 각 빠른 모드 요청을 같은 방식으로 표준 속도에서 재시도하므로 이 폴백도 캐시를 유지합니다. `/clear`와 `/compact`는 어쨌든 그 지점에서 캐시를 다시 빌드하므로 이를 재설정합니다.

106 106 

107### MCP 서버 연결 또는 제거107### MCP 서버 연결 또는 제거

108 108 

109도구 정의는 시스템 프롬프트 레이어에 있으므로 요청의 도구 정의 집합이 턴 사이에 변경되면 캐시가 무효화됩니다. [어드바이저 도구](/docs/ko/advisor.md)를 토글하는 것은 예외입니다. 그 정의는 캐시 중단점 이후에 있으므로 `/advisor`를 활성화하거나 비활성화해도 캐시된 접두사가 그대로 유지됩니다. [MCP 서버](/docs/ko/mcp.md) 변경이 이를 수행하는지 여부는 [도구 검색](/docs/ko/mcp.md#scale-with-mcp-tool-search)이 세션의 MCP 도구를 지연하는지에 따라 달라집니다. 지원되는 모델의 기본값입니다.109도구 정의는 시스템 프롬프트 레이어에 있으므로 요청의 도구 정의 집합이 턴 사이에 변경되면 캐시가 무효화됩니다. [어드바이저 도구](https://code.claude.com/docs/ko/advisor.md)를 토글하는 것은 예외입니다. 그 정의는 캐시 중단점 이후에 있으므로 `/advisor`를 활성화하거나 비활성화해도 캐시된 접두사가 그대로 유지됩니다. [MCP 서버](https://code.claude.com/docs/ko/mcp.md) 변경이 이를 수행하는지 여부는 [도구 검색](https://code.claude.com/docs/ko/mcp.md#scale-with-mcp-tool-search)이 세션의 MCP 도구를 지연하는지에 따라 달라집니다. 지원되는 모델의 기본값입니다.

110 110 

111* **도구 지연됨**: Claude Code는 대화의 첫 번째 요청에서 도구 목록을 유지하므로 세션 중간에 서버가 연결되거나 연결 해제되어도 이미 캐시된 것을 방해하지 않습니다. 첫 번째 요청 후 연결을 마치는 서버는 Claude가 필요에 따라 로드하는 지연된 정의로 해당 도구를 제공합니다.111* **도구 지연됨**: Claude Code는 대화의 첫 번째 요청에서 도구 목록을 유지하므로 세션 중간에 서버가 연결되거나 연결 해제되어도 이미 캐시된 것을 방해하지 않습니다. 첫 번째 요청 후 연결을 마치는 서버는 Claude가 필요에 따라 로드하는 지연된 정의로 해당 도구를 제공합니다.

112* **도구 사전 로드됨**: 정의를 추가하면 캐시가 무효화되며, 의도적으로 제거하는 것도 마찬가지입니다. 이는 도구 검색이 [꺼져 있거나 사용할 수 없는](/docs/ko/mcp.md#configure-tool-search) 경우에 적용되며, 예를 들면 다음과 같습니다.112* **도구 사전 로드됨**: 정의를 추가하면 캐시가 무효화되며, 의도적으로 제거하는 것도 마찬가지입니다. 이는 도구 검색이 [꺼져 있거나 사용할 수 없는](https://code.claude.com/docs/ko/mcp.md#configure-tool-search) 경우에 적용되며, 예를 들면 다음과 같습니다.

113 * Opus 4.5, Sonnet 4.5, Haiku 4.5보다 이전의 Google Cloud의 Agent Platform 모델113 * Opus 4.5, Sonnet 4.5, Haiku 4.5보다 이전의 Google Cloud의 Agent Platform 모델

114 * Claude Code가 배포에서 도구 검색을 거부한다는 것을 감지한 이후의 Microsoft Foundry [Azure에서 호스팅되는 배포](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)114 * Claude Code가 배포에서 도구 검색을 거부한다는 것을 감지한 이후의 Microsoft Foundry [Azure에서 호스팅되는 배포](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)

115 115 

117 117 

118| 세션 중간 변경 | 캐시 | 다음 요청의 도구 정의 |118| 세션 중간 변경 | 캐시 | 다음 요청의 도구 정의 |

119| - | - | - |119| - | - | - |

120| 서버가 연결되거나 [동적 도구 업데이트](/docs/ko/mcp.md#dynamic-tool-updates)가 도구를 추가함 | 무효화됨 | 새 정의가 추가됨 |120| 서버가 연결되거나 [동적 도구 업데이트](https://code.claude.com/docs/ko/mcp.md#dynamic-tool-updates)가 도구를 추가함 | 무효화됨 | 새 정의가 추가됨 |

121| 서버가 사용자의 조치 없이 중단됨. 예: stdio 서버의 프로세스 종료 | 유지됨 | 서버의 정의는 변경되지 않음. 해당 도구 중 하나에 대한 호출은 실행되는 대신 오류를 반환함 |121| 서버가 사용자의 조치 없이 중단됨. 예: stdio 서버의 프로세스 종료 | 유지됨 | 서버의 정의는 변경되지 않음. Claude Code가 해당 호출을 위해 [서버를 다시 시작](https://code.claude.com/docs/ko/mcp.md#stdio-servers-that-exit-or-fail-to-start)하지 않는 한, 해당 도구 중 하나에 대한 호출은 실행되는 대신 오류를 반환함 |

122| 원격 서버가 연결 끊김 후 [자동으로 다시 연결](/docs/ko/mcp.md#automatic-reconnection) | 유지됨. 서버가 다시 연결되는 동안 보낸 요청이 `WaitForMcpServers` 도구를 추가하면 한 번 무효화됨 | 서버의 정의는 변경되지 않음. 서버가 다시 연결되는 동안 보낸 요청은 대화가 아직 나열하지 않았을 때 `WaitForMcpServers`를 추가할 수 있으며, 도구는 나머지 대화 동안 나열된 상태로 유지됨 |122| 원격 서버가 연결 끊김 후 [자동으로 다시 연결](https://code.claude.com/docs/ko/mcp.md#automatic-reconnection) | 유지됨. 서버가 다시 연결되는 동안 보낸 요청이 `WaitForMcpServers` 도구를 추가하면 한 번 무효화됨 | 서버의 정의는 변경되지 않음. 서버가 다시 연결되는 동안 보낸 요청은 대화가 아직 나열하지 않았을 때 `WaitForMcpServers`를 추가할 수 있으며, 도구는 나머지 대화 동안 나열된 상태로 유지됨 |

123| 의도적으로 도구를 제거함. 예: [거부 규칙](#denying-an-entire-tool)을 사용하거나 `/mcp`에서 서버를 비활성화함 | 무효화됨 | 정의가 제거됨 |123| 의도적으로 도구를 제거함. 예: [거부 규칙](#denying-an-entire-tool)을 사용하거나 `/mcp`에서 서버를 비활성화함 | 무효화됨 | 정의가 제거됨 |

124 124 

125도구가 접두사에 로드되는 대화를 재개할 때 해당 MCP 서버 중 하나는 첫 번째 요청이 나갈 때 여전히 연결 중일 수 있습니다. 트랜스크립트가 해당 서버의 도구 정의를 기록했다면 해당 요청은 기록된 대로 포함되므로 서버가 같은 도구로 연결을 마칠 때 변경되지 않습니다.125도구가 접두사에 로드되는 대화를 재개할 때 해당 MCP 서버 중 하나는 첫 번째 요청이 나갈 때 여전히 연결 중일 수 있습니다. 트랜스크립트가 해당 서버의 도구 정의를 기록했다면 해당 요청은 기록된 대로 포함되므로 서버가 같은 도구로 연결을 마칠 때 변경되지 않습니다.

128 128 

129### 플러그인 활성화 또는 비활성화129### 플러그인 활성화 또는 비활성화

130 130 

131[플러그인](/docs/ko/plugins/overview.md)을 활성화하거나 비활성화할 때 변경 비용은 플러그인이 제공하는 구성 요소 유형에 따라 달라집니다. 아래 경우는 각 구성 요소 유형, Claude Code가 변경을 적용하는 시기, 같은 세션에서 플러그인을 다시 비활성화할 때 어떤 일이 발생하는지를 다룹니다.131[플러그인](https://code.claude.com/docs/ko/plugins/overview.md)을 활성화하거나 비활성화할 때 변경 비용은 플러그인이 제공하는 구성 요소 유형에 따라 달라집니다. 아래 경우는 각 구성 요소 유형, Claude Code가 변경을 적용하는 시기, 같은 세션에서 플러그인을 다시 비활성화할 때 어떤 일이 발생하는지를 다룹니다.

132 132 

133#### 캐시를 유지하는 플러그인 구성 요소133#### 캐시를 유지하는 플러그인 구성 요소

134 134 

136 136 

137#### MCP 서버를 제공하는 플러그인137#### MCP 서버를 제공하는 플러그인

138 138 

139[MCP 서버](/docs/ko/plugins/components.md#mcp-servers)를 제공하는 플러그인을 활성화하거나 비활성화할 때 Claude Code는 [MCP 서버를 연결하거나 제거](#connecting-or-removing-an-mcp-server)할 때와 같은 규칙을 따릅니다.139[MCP 서버](https://code.claude.com/docs/ko/plugins/components.md#mcp-servers)를 제공하는 플러그인을 활성화하거나 비활성화할 때 Claude Code는 [MCP 서버를 연결하거나 제거](#connecting-or-removing-an-mcp-server)할 때와 같은 규칙을 따릅니다.

140 140 

141#### 코드 인텔리전스 플러그인141#### 코드 인텔리전스 플러그인

142 142 

143[코드 인텔리전스 플러그인](/docs/ko/plugins/code-intelligence.md)을 활성화하면 Claude는 [LSP 도구](/docs/ko/tools-reference.md#lsp-tool-behavior)를 얻습니다.143[코드 인텔리전스 플러그인](https://code.claude.com/docs/ko/plugins/code-intelligence.md)을 활성화하면 Claude는 [LSP 도구](https://code.claude.com/docs/ko/tools-reference.md#lsp-tool-behavior)를 얻습니다.

144 144 

145#### 플러그인 변경이 적용되는 시기145#### 플러그인 변경이 적용되는 시기

146 146 

147`/plugin` 메뉴에서 수행한 변경은 [`/reload-plugins`](/docs/ko/plugins/cli-reference#reload-plugins)를 통해 진행되며, Claude Code는 메뉴를 닫을 때 이를 실행합니다. 추가된 공지 또는 전체 다시 읽기 여부에 관계없이 비용을 지불하며, 변경이 적용된 후 첫 번째 턴에서 비용을 지불합니다. Claude Code는 또한 자체적으로 변경을 적용할 수 있습니다.147`/plugin` 메뉴에서 수행한 변경은 [`/reload-plugins`](https://code.claude.com/docs/ko/plugins/cli-reference#reload-plugins)를 통해 진행되며, Claude Code는 메뉴를 닫을 때 이를 실행합니다. 추가된 공지 또는 전체 다시 읽기 여부에 관계없이 비용을 지불하며, 변경이 적용된 후 첫 번째 턴에서 비용을 지불합니다. Claude Code는 또한 자체적으로 변경을 적용할 수 있습니다.

148 148 

149* `command` 소스가 있는 플러그인의 경우 Claude Code는 [플러그인 자체를 다시 로드](/docs/ko/plugins/loading.md#when-a-command-source-re-runs)할 수 있습니다.149* `command` 소스가 있는 플러그인의 경우 Claude Code는 [플러그인 자체를 다시 로드](https://code.claude.com/docs/ko/plugins/loading.md#when-a-command-source-re-runs)할 수 있습니다.

150* [`/plugin` 인터페이스에서 플러그인을 설치](/docs/ko/plugins/install#install-a-plugin)할 때 Claude Code는 설치 중에 활성화할 수 있습니다. 설치 요약은 활성화했는지 여부를 알려줍니다.150* [`/plugin` 인터페이스에서 플러그인을 설치](https://code.claude.com/docs/ko/plugins/install#install-a-plugin)할 때 Claude Code는 설치 중에 활성화할 수 있습니다. 설치 요약은 활성화했는지 여부를 알려줍니다.

151* v2.1.246 이상에서 [`/cd`로 세션을 이동](/docs/ko/permissions#move-the-session-to-another-directory)할 때 Claude Code는 새 디렉토리의 설정이 활성화하는 플러그인을 이동의 일부로 적용하며, `/reload-plugins`를 보류시키는 전체 다시 읽기 경고 없이 적용합니다.151* v2.1.246 이상에서 [`/cd`로 세션을 이동](https://code.claude.com/docs/ko/permissions#move-the-session-to-another-directory)할 때 Claude Code는 새 디렉토리의 설정이 활성화하는 플러그인을 이동의 일부로 적용하며, `/reload-plugins`를 보류시키는 전체 다시 읽기 경고 없이 적용합니다.

152* 대화형 세션에서 `--plugin-dir`으로 전달한 [플러그인 폴더](/docs/ko/plugins/create.md#load-a-directory-or-archive-for-one-session)에서 플러그인을 추가하거나 제거할 때 변경이 즉시 적용됩니다. 적용하면 전체 다시 읽기가 트리거되는 경우 Claude Code는 대신 변경을 보류하고 `/reload-plugins`를 실행하라는 공지를 표시합니다. Claude Code v2.1.265 이상이 필요합니다.152* 대화형 세션에서 `--plugin-dir`으로 전달한 [플러그인 폴더](https://code.claude.com/docs/ko/plugins/create.md#load-a-directory-or-archive-for-one-session)에서 플러그인을 추가하거나 제거할 때 변경이 즉시 적용됩니다. 적용하면 전체 다시 읽기가 트리거되는 경우 Claude Code는 대신 변경을 보류하고 `/reload-plugins`를 실행하라는 공지를 표시합니다. Claude Code v2.1.265 이상이 필요합니다.

153 153 

154`/reload-plugins`가 실행되고 다시 로드가 전체 다시 읽기를 트리거하면 Claude Code는 경고를 표시하고 다시 로드를 적용하지 않습니다. 그래도 적용하려면 `/reload-plugins --force`를 실행합니다.154`/reload-plugins`가 실행되고 다시 로드가 전체 다시 읽기를 트리거하면 Claude Code는 경고를 표시하고 다시 로드를 적용하지 않습니다. 그래도 적용하려면 `/reload-plugins --force`를 실행합니다.

155 155 

156`/reload-plugins`는 데스크톱 앱, Agent SDK, `-p`를 사용하는 [비대화형 모드](/docs/ko/headless.md)처럼 대화형 터미널이 없는 세션에서도 세션에 직접 입력하면 실행됩니다. Claude Code v2.1.260 이상이 필요합니다.156`/reload-plugins`는 데스크톱 앱, Agent SDK, `-p`를 사용하는 [비대화형 모드](https://code.claude.com/docs/ko/headless.md)처럼 대화형 터미널이 없는 세션에서도 세션에 직접 입력하면 실행됩니다. Claude Code v2.1.260 이상이 필요합니다.

157 157 

158이러한 세션에서 다시 로드는 플러그인 MCP 서버 변경을 제외한 모든 것을 적용하며, 플러그인 MCP 서버 변경은 [다음 세션에서 적용](/docs/ko/plugins/cli-reference.md#reload-plugins)되므로 세션 중간에 전체 다시 읽기 비용이 발생하지 않습니다.158이러한 세션에서 다시 로드는 플러그인 MCP 서버 변경을 제외한 모든 것을 적용하며, 플러그인 MCP 서버 변경은 [다음 세션에서 적용](https://code.claude.com/docs/ko/plugins/cli-reference.md#reload-plugins)되므로 세션 중간에 전체 다시 읽기 비용이 발생하지 않습니다.

159 159 

160#### 한 세션에서 활성화한 후 비활성화하는 플러그인160#### 한 세션에서 활성화한 후 비활성화하는 플러그인

161 161 

163 163 

164### 전체 도구 거부164### 전체 도구 거부

165 165 

166`Bash` 또는 `WebFetch`와 같은 도구 이름을 [거부 규칙](/docs/ko/permissions.md#manage-permissions)으로 추가하면 Claude는 `/permissions`를 통해 규칙을 추가하든 [설정 파일을 직접 편집](/docs/ko/settings.md#when-edits-take-effect)하든 다음 요청부터 해당 도구를 호출할 수 없습니다. 여기에는 턴 중간에 `/permissions`를 통해 추가한 규칙도 포함됩니다.166`Bash` 또는 `WebFetch`와 같은 도구 이름을 [거부 규칙](https://code.claude.com/docs/ko/permissions.md#manage-permissions)으로 추가하면 Claude는 `/permissions`를 통해 규칙을 추가하든 [설정 파일을 직접 편집](https://code.claude.com/docs/ko/settings.md#when-edits-take-effect)하든 다음 요청부터 해당 도구를 호출할 수 없습니다. 여기에는 턴 중간에 `/permissions`를 통해 추가한 규칙도 포함됩니다.

167 167 

168[도구 검색](/docs/ko/mcp.md#scale-with-mcp-tool-search)이 활성화되어 있을 때(지원되는 모델의 기본값), 요청의 도구 정의는 변경되지 않고 캐시된 접두사가 유지됩니다. 도구 검색을 사용할 수 없거나 비활성화되면 Claude Code는 다음 요청에서 정의를 제거하여 캐시를 무효화하며, 나중에 규칙을 제거해도 마찬가지입니다.168[도구 검색](https://code.claude.com/docs/ko/mcp.md#scale-with-mcp-tool-search)이 활성화되어 있을 때(지원되는 모델의 기본값), 요청의 도구 정의는 변경되지 않고 캐시된 접두사가 유지됩니다. 도구 검색을 사용할 수 없거나 비활성화되면 Claude Code는 다음 요청에서 정의를 제거하여 캐시를 무효화하며, 나중에 규칙을 제거해도 마찬가지입니다.

169 169 

170도구 이름 위치에서 일치하는 거부 규칙만 이 방식으로 도구를 차단합니다. 도구 이름, 동등한 `Bash(*)` 형식, 또는 `"*"`와 같은 [도구 이름 글로브](/docs/ko/permissions.md#tool-name-wildcards). MCP 도구만 일치하는 글로브(예: `"mcp__*"`)는 같은 방식으로 해당 도구를 차단합니다. `Bash(rm *)`와 같은 범위가 지정된 거부 규칙 및 모든 허용 및 요청 규칙은 Claude가 보는 도구를 변경하지 않습니다. Claude Code는 Claude가 호출을 시도할 때 이를 확인하여 접두사를 그대로 유지합니다.170도구 이름 위치에서 일치하는 거부 규칙만 이 방식으로 도구를 차단합니다. 도구 이름, 동등한 `Bash(*)` 형식, 또는 `"*"`와 같은 [도구 이름 글로브](https://code.claude.com/docs/ko/permissions.md#tool-name-wildcards). MCP 도구만 일치하는 글로브(예: `"mcp__*"`)는 같은 방식으로 해당 도구를 차단합니다. `Bash(rm *)`와 같은 범위가 지정된 거부 규칙 및 모든 허용 및 요청 규칙은 Claude가 보는 도구를 변경하지 않습니다. Claude Code는 Claude가 호출을 시도할 때 이를 확인하여 접두사를 그대로 유지합니다.

171 171 

172### 대화 압축172### 대화 압축

173 173 

174[압축](/docs/ko/context-window.md#what-survives-compaction)은 메시지 기록을 요약으로 바꿉니다. 설계상 이는 대화 레이어를 무효화합니다. 다음 요청에는 이전 것과 접두사를 공유하지 않는 새로운 더 짧은 기록이 있기 때문입니다. 시스템 프롬프트 레이어와 프로젝트 컨텍스트 레이어는 캐시된 상태로 유지될 수 있습니다.174[압축](https://code.claude.com/docs/ko/context-window.md#what-survives-compaction)은 메시지 기록을 요약으로 바꿉니다. 설계상 이는 대화 레이어를 무효화합니다. 다음 요청에는 이전 것과 접두사를 공유하지 않는 새로운 더 짧은 기록이 있기 때문입니다. 시스템 프롬프트 레이어와 프로젝트 컨텍스트 레이어는 캐시된 상태로 유지될 수 있습니다.

175 175 

176* **시스템 프롬프트**: [재개된 대화](#resuming-a-session)가 현재는 오래된 시스템 프롬프트를 유지하고 있는 경우가 아니라면 다음 요청은 캐시에서 이 레이어를 읽습니다. 해당 대화가 처음 압축될 때 Claude Code는 이를 현재 프롬프트로 전환하며, 다음 요청은 이 레이어의 캐시를 한 번 다시 빌드합니다.176* **시스템 프롬프트**: [재개된 대화](#resuming-a-session)가 현재는 오래된 시스템 프롬프트를 유지하고 있는 경우가 아니라면 다음 요청은 캐시에서 이 레이어를 읽습니다. 해당 대화가 처음 압축될 때 Claude Code는 이를 현재 프롬프트로 전환하며, 다음 요청은 이 레이어의 캐시를 한 번 다시 빌드합니다.

177* **프로젝트 컨텍스트**: Claude Code는 디스크에서 이 레이어를 다시 로드합니다. 다음 요청은 세션 시작 이후 CLAUDE.md 및 메모리가 변경되지 않은 경우에만 캐시에서 이 레이어를 읽습니다.177* **프로젝트 컨텍스트**: Claude Code는 디스크에서 이 레이어를 다시 로드합니다. 다음 요청은 세션 시작 이후 CLAUDE.md 및 메모리가 변경되지 않은 경우에만 캐시에서 이 레이어를 읽습니다.

178 178 

179요약을 생성하기 위해 Claude Code는 별도의 요청을 보냅니다. 이 요청은 대화의 시스템 프롬프트, 도구, 요약 대상 기록을 반복하며, 요약 지침으로 끝납니다. 캐시가 따뜻한 동안 해당 요청은 캐시에서 접두사를 읽습니다. 그러면 세션 중간 `/compact`는 컨텍스트 크기가 제안하는 것의 일부 비용만 들고 대부분의 시간을 요약 생성에 소비합니다.179요약을 생성하기 위해 Claude Code는 별도의 요청을 보냅니다. 이 요청은 대화의 시스템 프롬프트, 도구, 요약 대상 기록을 반복하며, 요약 지침으로 끝납니다. 캐시가 따뜻한 동안 해당 요청은 캐시에서 접두사를 읽습니다. 그러면 세션 중간 `/compact`는 컨텍스트 크기가 제안하는 것의 일부 비용만 들고 대부분의 시간을 요약 생성에 소비합니다.

180 180 

181[캐시 수명](#cache-lifetime)보다 긴 휴식 후에는 읽을 캐시가 남아 있지 않으므로 요약 요청은 해당 기록을 캐시되지 않은 입력으로 다시 처리합니다. 이것이 [이전 세션을 재개](/docs/ko/sessions.md#resume-a-session)할 때 `/compact`의 비용이 가장 많이 드는 이유입니다. 따뜻한 경우와 차가운 경우 모두에서 압축 후 턴은 훨씬 더 짧은 요약에 대해서만 대화 캐시를 다시 빌드하므로 해당 턴이 느린 부분이 아닙니다.181[캐시 수명](#cache-lifetime)보다 긴 휴식 후에는 읽을 캐시가 남아 있지 않으므로 요약 요청은 해당 기록을 캐시되지 않은 입력으로 다시 처리합니다. 이것이 [이전 세션을 재개](https://code.claude.com/docs/ko/sessions.md#resume-a-session)할 때 `/compact`의 비용이 가장 많이 드는 이유입니다. 따뜻한 경우와 차가운 경우 모두에서 압축 후 턴은 훨씬 더 짧은 요약에 대해서만 대화 캐시를 다시 빌드하므로 해당 턴이 느린 부분이 아닙니다.

182 182 

183> [!TIP]183> [!TIP]

184>184>

185> 압축은 더 이상 필요하지 않은 콘텐츠를 버릴 때 유리합니다. 오버헤드가 발생하는 시기를 선택하려면 작업 중간에 자동 압축이 트리거되기를 기다리는 대신 작업 간 자연스러운 휴식 시간에 `/compact`를 실행합니다. 완전히 포기하고 싶은 경로로 들어섰다면 대신 [`/rewind`](#rewinding-the-conversation)로 이전 턴으로 되돌아갑니다. 되감기는 압축처럼 새 접두사를 빌드하는 대신 이미 캐시된 접두사로 다시 잘라냅니다.185> 압축은 더 이상 필요하지 않은 콘텐츠를 버릴 때 유리합니다. 오버헤드가 발생하는 시기를 선택하려면 작업 중간에 자동 압축이 트리거되기를 기다리는 대신 작업 간 자연스러운 휴식 시간에 `/compact`를 실행합니다. 완전히 포기하고 싶은 경로로 들어섰다면 대신 [`/rewind`](#rewinding-the-conversation)로 이전 턴으로 되돌아갑니다. 되감기는 압축처럼 새 접두사를 빌드하는 대신 이미 캐시된 접두사로 다시 잘라냅니다.

186 186 

187긴 대화가 [1시간 TTL](#which-ttl-each-request-gets)을 사용하는 동안 터미널 세션에서 유휴 상태로 두면 Claude Code는 캐시가 만료되기 직전에 해당 대화를 압축할 수 있습니다. 유휴 압축을 끄려면 [`idleCompaction`](/docs/ko/settings-reference#idlecompaction)을 `false`로 설정합니다. 이 설정에는 Claude Code v2.1.290 이상이 필요합니다.187긴 대화가 [1시간 TTL](#which-ttl-each-request-gets)을 사용하는 동안 터미널 세션에서 유휴 상태로 두면 Claude Code는 캐시가 만료되기 직전에 해당 대화를 압축할 수 있습니다. 유휴 압축을 끄려면 [`idleCompaction`](https://code.claude.com/docs/ko/settings-reference#idlecompaction)을 `false`로 설정합니다. 이 설정에는 Claude Code v2.1.290 이상이 필요합니다.

188 188 

189### 많은 이미지 누적189### 많은 이미지 누적

190 190 

196 196 

197### Claude Code 업그레이드197### Claude Code 업그레이드

198 198 

199새로운 Claude Code 버전은 일반적으로 시스템 프롬프트 또는 도구 정의를 업데이트하므로 업그레이드 후 시작하는 첫 번째 대화는 맨 위에서 캐시를 빌드합니다. [자동 업데이트](/docs/ko/setup.md#auto-updates)는 백그라운드에서 새 버전을 다운로드하지만 다음 시작 시 적용하며 세션 중간에는 절대 적용하지 않으므로 세션 중간의 놀라움이 아니라 다시 시작한 후 캐시되지 않은 첫 턴으로 표시됩니다. `DISABLE_AUTOUPDATER=1`을 설정하여 업그레이드가 적용되는 시기를 제어합니다.199새로운 Claude Code 버전은 일반적으로 시스템 프롬프트 또는 도구 정의를 업데이트하므로 업그레이드 후 시작하는 첫 번째 대화는 맨 위에서 캐시를 빌드합니다. [자동 업데이트](https://code.claude.com/docs/ko/setup.md#auto-updates)는 백그라운드에서 새 버전을 다운로드하지만 다음 시작 시 적용하며 세션 중간에는 절대 적용하지 않으므로 세션 중간의 놀라움이 아니라 다시 시작한 후 캐시되지 않은 첫 턴으로 표시됩니다. `DISABLE_AUTOUPDATER=1`을 설정하여 업그레이드가 적용되는 시기를 제어합니다.

200 200 

201> [!NOTE]201> [!NOTE]

202>202>

217 217 

218### 저장소의 파일 편집218### 저장소의 파일 편집

219 219 

220파일 내용은 Claude가 파일을 읽을 때만 컨텍스트에 들어가며, 읽기는 대화에 추가됩니다. Claude가 이전에 읽은 파일을 편집해도 기록의 이전 읽기를 소급하여 변경하지 않습니다. 대신 Claude Code는 파일이 변경되었음을 나타내는 [`<system-reminder>`](/docs/ko/glossary#system-reminder)를 추가하고, 필요한 경우 Claude가 다시 읽습니다.220파일 내용은 Claude가 파일을 읽을 때만 컨텍스트에 들어가며, 읽기는 대화에 추가됩니다. Claude가 이전에 읽은 파일을 편집해도 기록의 이전 읽기를 소급하여 변경하지 않습니다. 대신 Claude Code는 파일이 변경되었음을 나타내는 [`<system-reminder>`](https://code.claude.com/docs/ko/glossary#system-reminder)를 추가하고, 필요한 경우 Claude가 다시 읽습니다.

221 221 

222### 세션 중 CLAUDE.md 편집222### 세션 중 CLAUDE.md 편집

223 223 

224프로젝트 루트 및 사용자 수준의 CLAUDE.md 파일은 세션 시작 시 한 번 읽혀지고 메모리에 보관됩니다. 세션 중 편집해도 캐시가 무효화되지 않지만, 편집 사항도 적용되지 않습니다. Claude는 세션 시작 시 로드된 버전으로 계속 작동합니다. 새로운 내용은 다음 `/clear`, `/compact` 또는 재시작 시 로드됩니다.224프로젝트 루트 및 사용자 수준의 CLAUDE.md 파일은 세션 시작 시 한 번 읽혀지고 메모리에 보관됩니다. 세션 중 편집해도 캐시가 무효화되지 않지만, 편집 사항도 적용되지 않습니다. Claude는 세션 시작 시 로드된 버전으로 계속 작동합니다. 새로운 내용은 다음 `/clear`, `/compact` 또는 재시작 시 로드됩니다.

225 225 

226[하위 디렉토리의 중첩된 CLAUDE.md 파일](/docs/ko/memory.md)과 [`paths:` frontmatter가 있는 규칙](/docs/ko/memory#path-specific-rules)은 나중에 필요할 때 로드됩니다. 로드되기 전에 직접 편집하면 적용됩니다. 로드된 후에는 내용이 대화 기록의 일부이므로 세션 중 편집은 소급하여 변경하지 않습니다.226[하위 디렉토리의 중첩된 CLAUDE.md 파일](https://code.claude.com/docs/ko/memory.md)과 [`paths:` frontmatter가 있는 규칙](https://code.claude.com/docs/ko/memory#path-specific-rules)은 나중에 필요할 때 로드됩니다. 로드되기 전에 직접 편집하면 적용됩니다. 로드된 후에는 내용이 대화 기록의 일부이므로 세션 중 편집은 소급하여 변경하지 않습니다.

227 227 

228### 권한 모드 변경228### 권한 모드 변경

229 229 

230[권한 모드](/docs/ko/permission-modes.md)를 수동에서 편집 수락으로 전환하는 것과 같이 전환해도 시스템 프롬프트나 도구 정의가 변경되지 않으므로 모드 변경은 캐시 안전합니다. 예외는 [`opusplan`](/docs/ko/model-config#opusplan-model-setting) 모델 설정이 있는 계획 모드로, 계획 모드에 들어가거나 나갈 때 모델을 Opus와 Sonnet 사이에서 전환합니다. 이는 모드 토글을 [모델 전환](#switching-models)으로 만듭니다.230[권한 모드](https://code.claude.com/docs/ko/permission-modes.md)를 수동에서 편집 수락으로 전환하는 것과 같이 전환해도 시스템 프롬프트나 도구 정의가 변경되지 않으므로 모드 변경은 캐시 안전합니다. 예외는 [`opusplan`](https://code.claude.com/docs/ko/model-config#opusplan-model-setting) 모델 설정이 있는 계획 모드로, 계획 모드에 들어가거나 나갈 때 모델을 Opus와 Sonnet 사이에서 전환합니다. 이는 모드 토글을 [모델 전환](#switching-models)으로 만듭니다.

231 231 

232### 출력 스타일 변경232### 출력 스타일 변경

233 233 

234세션 중 [`/output-style`](/docs/ko/output-styles#change-your-output-style), `/config` 또는 `outputStyle` 설정으로 [출력 스타일](/docs/ko/output-styles.md)을 전환하면, Claude는 다음 메시지부터 새로운 스타일을 사용합니다. Claude Code는 새로운 스타일의 지침을 대화의 메시지로 전달하므로, 해당 요청은 여전히 시스템 프롬프트와 이전 대화를 캐시에서 읽습니다.234세션 중 [`/output-style`](https://code.claude.com/docs/ko/output-styles#change-your-output-style), `/config` 또는 `outputStyle` 설정으로 [출력 스타일](https://code.claude.com/docs/ko/output-styles.md)을 전환하면, Claude는 다음 메시지부터 새로운 스타일을 사용합니다. Claude Code는 새로운 스타일의 지침을 대화의 메시지로 전달하므로, 해당 요청은 여전히 시스템 프롬프트와 이전 대화를 캐시에서 읽습니다.

235 235 

236v2.1.251 이전에는 세션 중 스타일 전환이 캐시를 유지했지만 `/clear`를 실행하거나 새 세션을 시작할 때까지 적용되지 않았습니다.236v2.1.251 이전에는 세션 중 스타일 전환이 캐시를 유지했지만 `/clear`를 실행하거나 새 세션을 시작할 때까지 적용되지 않았습니다.

237 237 

238### 스킬 및 명령 호출238### 스킬 및 명령 호출

239 239 

240[스킬](/docs/ko/skills.md)과 [명령](/docs/ko/commands.md)은 호출 지점에서 사용자 메시지로 지침을 주입합니다. 대화의 이전 내용은 변경되지 않습니다. 프론트매터에서 `model`을 지정하는 스킬 또는 명령은 해당 턴에 대한 [모델 전환](#switching-models)이 될 수 있습니다.240[스킬](https://code.claude.com/docs/ko/skills.md)과 [명령](https://code.claude.com/docs/ko/commands.md)은 호출 지점에서 사용자 메시지로 지침을 주입합니다. 대화의 이전 내용은 변경되지 않습니다. 프론트매터에서 `model`을 지정하는 스킬 또는 명령은 해당 턴에 대한 [모델 전환](#switching-models)이 될 수 있습니다.

241 241 

242### `/recap` 실행242### `/recap` 실행

243 243 

244[`/recap`](/docs/ko/interactive-mode#session-recap)은 터미널에 표시할 요약을 생성합니다. `/compact`와 달리 요약을 메시지 기록을 대체하는 대신 명령 출력으로 추가하므로, 캐시된 접두사는 그대로 유지됩니다.244[`/recap`](https://code.claude.com/docs/ko/interactive-mode#session-recap)은 터미널에 표시할 요약을 생성합니다. `/compact`와 달리 요약을 메시지 기록을 대체하는 대신 명령 출력으로 추가하므로, 캐시된 접두사는 그대로 유지됩니다.

245 245 

246### 대화 되감기246### 대화 되감기

247 247 

248[`/rewind`](/docs/ko/checkpointing)는 대화를 이전 턴으로 자릅니다. 남은 기록은 그 시점에서 캐시가 구축된 것과 동일한 내용이며, 시스템 프롬프트와 프로젝트 컨텍스트 레이어는 변경되지 않으므로 다음 요청은 이전 캐시 항목에 도달합니다. 그 이후의 모든 턴은 해당 접두사를 통해 읽었으며, 원래 턴이 TTL보다 오래 전이었더라도 항목을 따뜻하게 유지했습니다.248[`/rewind`](https://code.claude.com/docs/ko/checkpointing)는 대화를 이전 턴으로 자릅니다. 남은 기록은 그 시점에서 캐시가 구축된 것과 동일한 내용이며, 시스템 프롬프트와 프로젝트 컨텍스트 레이어는 변경되지 않으므로 다음 요청은 이전 캐시 항목에 도달합니다. 그 이후의 모든 턴은 해당 접두사를 통해 읽었으며, 원래 턴이 TTL보다 오래 전이었더라도 항목을 따뜻하게 유지했습니다.

249 249 

250대화와 함께 파일 체크포인트를 복원하는 것은 캐시에 별도의 영향을 미치지 않습니다. 파일 내용은 Claude가 파일을 읽을 때만 컨텍스트에 들어가며, [저장소의 파일 편집](#editing-files-in-your-repository)과 동일합니다.250대화와 함께 파일 체크포인트를 복원하는 것은 캐시에 별도의 영향을 미치지 않습니다. 파일 내용은 Claude가 파일을 읽을 때만 컨텍스트에 들어가며, [저장소의 파일 편집](#editing-files-in-your-repository)과 동일합니다.

251 251 

252## 세션 재개252## 세션 재개

253 253 

254[세션을 재개](/docs/ko/sessions.md#resume-a-session)할 때, Claude Code는 전체 대화를 다시 전송하며, 요청은 캐시에서 변경되지 않았고 여전히 [캐시 수명](#cache-lifetime) 내에 있는 접두사 부분을 읽습니다. 이 페이지 상단의 레이어 테이블은 각 레이어가 어떻게 변경되는지 나타냅니다.254[세션을 재개](https://code.claude.com/docs/ko/sessions.md#resume-a-session)할 때, Claude Code는 전체 대화를 다시 전송하며, 요청은 캐시에서 변경되지 않았고 여전히 [캐시 수명](#cache-lifetime) 내에 있는 접두사 부분을 읽습니다. 이 페이지 상단의 레이어 테이블은 각 레이어가 어떻게 변경되는지 나타냅니다.

255 255 

256시스템 프롬프트는 [Claude Code 업그레이드](#upgrading-claude-code) 후 또는 재개 시 다른 [`--append-system-prompt`](/docs/ko/cli-reference#system-prompt-flags) 텍스트로 변경될 수 있습니다. 기본적으로 재개된 대화는 시작할 때의 시스템 프롬프트를 유지하므로 해당 히스토리는 여전히 동일한 프롬프트 뒤에 있으며, 변경 사항은 대화가 압축되거나 새 대화에서 적용됩니다. [재개된 대화의 시스템 프롬프트 플래그](/docs/ko/cli-reference.md#system-prompt-flags-in-resumed-conversations)는 Claude Code가 모든 요청에서 프롬프트를 다시 빌드하는 경우를 다룹니다.256시스템 프롬프트는 [Claude Code 업그레이드](#upgrading-claude-code) 후 또는 재개 시 다른 [`--append-system-prompt`](https://code.claude.com/docs/ko/cli-reference#system-prompt-flags) 텍스트로 변경될 수 있습니다. 기본적으로 재개된 대화는 시작할 때의 시스템 프롬프트를 유지하므로 해당 히스토리는 여전히 동일한 프롬프트 뒤에 있으며, 변경 사항은 대화가 압축되거나 새 대화에서 적용됩니다. [재개된 대화의 시스템 프롬프트 플래그](https://code.claude.com/docs/ko/cli-reference.md#system-prompt-flags-in-resumed-conversations)는 Claude Code가 모든 요청에서 프롬프트를 다시 빌드하는 경우를 다룹니다.

257 257 

258## 캐시 수명258## 캐시 수명

259 259 

266Claude Code는 요청별로 TTL을 결정하며, 모든 요청은 두 가지 고정 버킷 중 하나에 해당합니다:266Claude Code는 요청별로 TTL을 결정하며, 모든 요청은 두 가지 고정 버킷 중 하나에 해당합니다:

267 267 

268* **메인 대화**: 대화형 턴, 비대화형 `-p` 실행, Agent SDK 턴, 그리고 Claude Code가 이들과 함께 인라인으로 실행하는 도우미268* **메인 대화**: 대화형 턴, 비대화형 `-p` 실행, Agent SDK 턴, 그리고 Claude Code가 이들과 함께 인라인으로 실행하는 도우미

269* **기타 모든 것**: Claude Code가 해당 대화 외부에서 수행하는 요청(예: [서브에이전트](/docs/ko/sub-agents.md), [워크플로우](/docs/ko/workflows.md), 인프로세스 [팀원](/docs/ko/agent-teams.md), 포크, 압축, 세션 제목)269* **기타 모든 것**: Claude Code가 해당 대화 외부에서 수행하는 요청(예: [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md), [워크플로우](https://code.claude.com/docs/ko/workflows.md), 인프로세스 [팀원](https://code.claude.com/docs/ko/agent-teams.md), 포크, 압축, 세션 제목)

270 270 

271TTL을 직접 선택하지 않으면 Claude Code는 Claude 구독 내에서 플랜의 포함된 사용량 범위 내에서만 1시간 TTL을 요청합니다. 여기서는 메인 대화에 대해 1시간을 요청하고, Anthropic이 서버 측에서 제어하는 작은 도우미 요청 세트를 요청합니다. 이 표는 두 가지 청구 방식 모두에서 각 버킷의 기본 TTL을 제공합니다.271TTL을 직접 선택하지 않으면 Claude Code는 Claude 구독 내에서 플랜의 포함된 사용량 범위 내에서만 1시간 TTL을 요청합니다. 여기서는 메인 대화에 대해 1시간을 요청하고, Anthropic이 서버 측에서 제어하는 작은 도우미 요청 세트를 요청합니다. 이 표는 두 가지 청구 방식 모두에서 각 버킷의 기본 TTL을 제공합니다.

272 272 

281 281 

282각 버킷에 대해 TTL을 설정할 수 있습니다. 각 제어는 `5m` 또는 `1h`를 사용하며, Claude Code는 다른 값을 무시합니다.282각 버킷에 대해 TTL을 설정할 수 있습니다. 각 제어는 `5m` 또는 `1h`를 사용하며, Claude Code는 다른 값을 무시합니다.

283 283 

284* **메인 대화**: [`promptCacheTtl`](/docs/ko/settings-reference#promptcachettl) 설정 또는 `CLAUDE_CODE_PROMPT_CACHE_TTL` [환경 변수](/docs/ko/env-vars.md)284* **메인 대화**: [`promptCacheTtl`](https://code.claude.com/docs/ko/settings-reference#promptcachettl) 설정 또는 `CLAUDE_CODE_PROMPT_CACHE_TTL` [환경 변수](https://code.claude.com/docs/ko/env-vars.md)

285* **기타 모든 것**: [`subagentPromptCacheTtl`](/docs/ko/settings-reference#subagentpromptcachettl) 설정 또는 `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` 환경 변수285* **기타 모든 것**: [`subagentPromptCacheTtl`](https://code.claude.com/docs/ko/settings-reference#subagentpromptcachettl) 설정 또는 `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` 환경 변수

286 286 

287두 설정과 두 환경 변수 모두 Claude Code v2.1.242 이상이 필요합니다. API 키로 로그인하거나 클라우드 제공자를 사용하는 경우 `promptCacheTtl`을 `1h`로 설정하여 메인 대화에 1시간 캐시를 제공하세요. 그 외부의 요청은 해당 버킷에 대해 TTL을 선택할 때까지 5분 기본값을 유지합니다.287두 설정과 두 환경 변수 모두 Claude Code v2.1.242 이상이 필요합니다. API 키로 로그인하거나 클라우드 제공자를 사용하는 경우 `promptCacheTtl`을 `1h`로 설정하여 메인 대화에 1시간 캐시를 제공하세요. 그 외부의 요청은 해당 버킷에 대해 TTL을 선택할 때까지 5분 기본값을 유지합니다.

288 288 

2911. `FORCE_PROMPT_CACHING_5M=1`로, 두 버킷 모두에 5분을 강제합니다2911. `FORCE_PROMPT_CACHING_5M=1`로, 두 버킷 모두에 5분을 강제합니다

2922. 버킷의 환경 변수2922. 버킷의 환경 변수

2933. 버킷의 설정2933. 버킷의 설정

2944. 서브에이전트의 요청의 경우, 서브에이전트의 [`experimental` 프론트매터 필드](/docs/ko/sub-agents#supported-frontmatter-fields)의 `cacheTtl` 값으로, Claude Code v2.1.248 이상이 필요합니다. Claude Code는 Claude 구독이 사용 크레딧을 사용 중일 때 거기서 `1h`를 무시합니다2944. 서브에이전트의 요청의 경우, 서브에이전트의 [`experimental` 프론트매터 필드](https://code.claude.com/docs/ko/sub-agents#supported-frontmatter-fields)의 `cacheTtl` 값으로, Claude Code v2.1.248 이상이 필요합니다. Claude Code는 Claude 구독이 사용 크레딧을 사용 중일 때 거기서 `1h`를 무시합니다

2955. `ENABLE_PROMPT_CACHING_1H=1`로, 두 버킷 모두에 1시간을 요청합니다2955. `ENABLE_PROMPT_CACHING_1H=1`로, 두 버킷 모두에 1시간을 요청합니다

2966. [요청의 버킷에 대한 기본값](#which-ttl-each-request-gets)2966. [요청의 버킷에 대한 기본값](#which-ttl-each-request-gets)

297 297 

298캐시 동작을 디버깅하거나, 두 TTL을 비교하거나, [관리 설정](/docs/ko/managed-settings.md)에서 설정한 더 긴 TTL을 재정의할 때 `FORCE_PROMPT_CACHING_5M=1`을 설정하세요.298캐시 동작을 디버깅하거나, 두 TTL을 비교하거나, [관리 설정](https://code.claude.com/docs/ko/managed-settings.md)에서 설정한 더 긴 TTL을 재정의할 때 `FORCE_PROMPT_CACHING_5M=1`을 설정하세요.

299 299 

300메인 대화의 캐시 쓰기가 사용한 TTL을 확인하려면 `claude -p "hello" --output-format json`을 실행하고 결과에서 `usage.cache_creation`을 읽으세요. Claude Code는 1시간 캐시 쓰기를 `ephemeral_1h_input_tokens` 아래에 보고하고 5분 캐시 쓰기를 `ephemeral_5m_input_tokens` 아래에 보고합니다.300메인 대화의 캐시 쓰기가 사용한 TTL을 확인하려면 `claude -p "hello" --output-format json`을 실행하고 결과에서 `usage.cache_creation`을 읽으세요. Claude Code는 1시간 캐시 쓰기를 `ephemeral_1h_input_tokens` 아래에 보고하고 5분 캐시 쓰기를 `ephemeral_5m_input_tokens` 아래에 보고합니다.

301 301 

302게이트웨이를 통하거나 Amazon Bedrock에서 1시간 TTL을 사용하려면 다음을 참고하세요:302게이트웨이를 통하거나 Amazon Bedrock에서 1시간 TTL을 사용하려면 다음을 참고하세요:

303 303 

304* **`ANTHROPIC_BASE_URL`로 설정한 LLM 게이트웨이**: 1시간 요청의 일부가 `anthropic-beta` 헤더로 전달되므로, [해당 헤더를 변경하지 않고 전달](/docs/ko/llm-gateway-protocol.md#request-headers)하도록 게이트웨이를 구성하세요304* **`ANTHROPIC_BASE_URL`로 설정한 LLM 게이트웨이**: 1시간 요청의 일부가 `anthropic-beta` 헤더로 전달되므로, [해당 헤더를 변경하지 않고 전달](https://code.claude.com/docs/ko/llm-gateway-protocol.md#request-headers)하도록 게이트웨이를 구성하세요

305* **[Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)**: 관리자에게 [게이트웨이 정책](/docs/ko/claude-apps-gateway-config.md#one-hour-prompt-cache)에서 1시간 TTL을 요청하도록 요청하세요305* **[Claude 앱 게이트웨이](https://code.claude.com/docs/ko/claude-apps-gateway)**: 관리자에게 [게이트웨이 정책](https://code.claude.com/docs/ko/claude-apps-gateway-config.md#one-hour-prompt-cache)에서 1시간 TTL을 요청하도록 요청하세요

306* **Amazon Bedrock**: 프롬프트 캐싱 지원, 최소 캐시 가능 접두사 길이, 1시간 TTL 가용성은 모두 모델에 따라 다릅니다. 캐시 토큰 수가 0으로 유지되면 Amazon Bedrock 설명서에서 [지원되는 모델, 지역 및 제한](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)을 확인하세요.306* **Amazon Bedrock**: 프롬프트 캐싱 지원, 최소 캐시 가능 접두사 길이, 1시간 TTL 가용성은 모두 모델에 따라 다릅니다. 캐시 토큰 수가 0으로 유지되면 Amazon Bedrock 설명서에서 [지원되는 모델, 지역 및 제한](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)을 확인하세요.

307 307 

308## 캐시 범위308## 캐시 범위

311 311 

312동일한 디렉토리에서 병렬로 실행하는 세션은 일치하는 접두사를 구축하고 서로의 캐시를 읽습니다. 순차 세션은 시작 시 촬영한 git 상태 스냅샷이 일치할 때만 접두사를 공유합니다. 각 대화는 해당 스냅샷의 분기 및 최근 커밋도 포함하기 때문입니다.312동일한 디렉토리에서 병렬로 실행하는 세션은 일치하는 접두사를 구축하고 서로의 캐시를 읽습니다. 순차 세션은 시작 시 촬영한 git 상태 스냅샷이 일치할 때만 접두사를 공유합니다. 각 대화는 해당 스냅샷의 분기 및 최근 커밋도 포함하기 때문입니다.

313 313 

314기본 API 캐시는 더 광범위합니다. 캐시는 조직 간에 격리되며, 일부 제공자의 경우 [조직 내 워크스페이스 간에 격리됩니다](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-storage-and-sharing). 이러한 경계 내에서 동일한 모델과 접두사를 가진 두 요청은 동일한 캐시를 읽습니다. Agent SDK 호출자가 자동화된 프로세스의 플릿을 실행하는 경우, [사용자 및 머신 간 프롬프트 캐싱 개선](/docs/ko/agent-sdk/modifying-system-prompts.md#improve-prompt-caching-across-users-and-machines)을 참조하여 자동 메모리 위치를 시스템 프롬프트 밖으로 이동하고 시스템 프롬프트의 캐시 항목을 사용자 및 머신 간에 공유합니다.314기본 API 캐시는 더 광범위합니다. 캐시는 조직 간에 격리되며, 일부 제공자의 경우 [조직 내 워크스페이스 간에 격리됩니다](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-storage-and-sharing). 이러한 경계 내에서 동일한 모델과 접두사를 가진 두 요청은 동일한 캐시를 읽습니다. Agent SDK 호출자가 자동화된 프로세스의 플릿을 실행하는 경우, [사용자 및 머신 간 프롬프트 캐싱 개선](https://code.claude.com/docs/ko/agent-sdk/modifying-system-prompts.md#improve-prompt-caching-across-users-and-machines)을 참조하여 자동 메모리 위치를 시스템 프롬프트 밖으로 이동하고 시스템 프롬프트의 캐시 항목을 사용자 및 머신 간에 공유합니다.

315 315 

316## 캐시 성능 확인316## 캐시 성능 확인

317 317 

318캐시 성능은 API가 모든 응답에서 보고하는 두 개의 토큰 수로 표시됩니다. 이를 실시간으로 확인하는 가장 직접적인 방법은 `current_usage` 객체를 읽는 [상태 표시줄 스크립트](/docs/ko/statusline.md)입니다:318캐시 성능은 API가 모든 응답에서 보고하는 두 개의 토큰 수로 표시됩니다. 이를 실시간으로 확인하는 가장 직접적인 방법은 `current_usage` 객체를 읽는 [상태 표시줄 스크립트](https://code.claude.com/docs/ko/statusline.md)입니다:

319 319 

320| 필드 | 의미 |320| 필드 | 의미 |

321| - | - |321| - | - |

324 324 

325높은 읽기 대 생성 비율은 캐싱이 잘 작동하고 있음을 의미합니다. 생성이 턴마다 높게 유지되면 접두사에서 뭔가 변경되고 있다는 뜻입니다. [캐시를 무효화하는 작업](#actions-that-invalidate-the-cache) 섹션에서 일반적인 원인을 나열합니다.325높은 읽기 대 생성 비율은 캐싱이 잘 작동하고 있음을 의미합니다. 생성이 턴마다 높게 유지되면 접두사에서 뭔가 변경되고 있다는 뜻입니다. [캐시를 무효화하는 작업](#actions-that-invalidate-the-cache) 섹션에서 일반적인 원인을 나열합니다.

326 326 

327세션별 요약을 보려면 `/usage`를 실행하세요. 주 대화의 첫 응답 후, Claude Code는 [`Prompt cache (main)` 라인](/docs/ko/costs#prompt-cache-statistics)을 세션 블록에 추가하여 세션의 히트 비율, 미스 횟수 및 캐시가 현재 따뜻한 상태인지 여부를 표시합니다. 상태 표시줄 스크립트는 [`prompt_cache` 객체](/docs/ko/statusline#prompt-cache-fields)에서 동일한 숫자를 읽을 수 있습니다. 둘 다 Claude Code v2.1.251 이상이 필요합니다.327세션별 요약을 보려면 `/usage`를 실행하세요. 주 대화의 첫 응답 후, Claude Code는 [`Prompt cache (main)` 라인](https://code.claude.com/docs/ko/costs#prompt-cache-statistics)을 세션 블록에 추가하여 세션의 히트 비율, 미스 횟수 및 캐시가 현재 따뜻한 상태인지 여부를 표시합니다. 상태 표시줄 스크립트는 [`prompt_cache` 객체](https://code.claude.com/docs/ko/statusline#prompt-cache-fields)에서 동일한 숫자를 읽을 수 있습니다. 둘 다 Claude Code v2.1.251 이상이 필요합니다.

328 328 

329`Prompt cache (main)` 라인은 Claude Code가 식별할 수 있을 때 마지막 미스의 가능한 원인을 이름으로 표시합니다. 예를 들어 `likely cause: tool definitions changed`입니다. 가능한 원인 텍스트는 Claude Code v2.1.260 이상이 필요합니다.329`Prompt cache (main)` 라인은 Claude Code가 식별할 수 있을 때 마지막 미스의 가능한 원인을 이름으로 표시합니다. 예를 들어 `likely cause: tool definitions changed`입니다. 가능한 원인 텍스트는 Claude Code v2.1.260 이상이 필요합니다.

330 330 

331조직 전체의 가시성을 위해 OpenTelemetry 내보내기는 사용자 및 세션별로 캐시 읽기 및 생성 토큰을 보고합니다. 메트릭 및 이벤트 속성 참조는 [사용량 모니터링](/docs/ko/monitoring-usage.md)을 참조하세요.331조직 전체의 가시성을 위해 OpenTelemetry 내보내기는 사용자 및 세션별로 캐시 읽기 및 생성 토큰을 보고합니다. 메트릭 및 이벤트 속성 참조는 [사용량 모니터링](https://code.claude.com/docs/ko/monitoring-usage.md)을 참조하세요.

332 332 

333## 서브에이전트와 캐시333## 서브에이전트와 캐시

334 334 

335[서브에이전트](/docs/ko/sub-agents.md)는 부모와 별도의 자체 시스템 프롬프트와 도구 세트로 자체 대화를 시작합니다. 첫 번째 요청은 두 접두사가 다르기 때문에 부모의 캐시를 읽지 않으며, 자신의 턴에 걸쳐 자체 캐시를 워밍합니다. 서브에이전트는 메인 대화 [TTL 버킷](#which-ttl-each-request-gets) 외부에 있으므로, [더 긴 것을 선택](#choose-the-ttl-yourself)할 때까지 구독 상태에서도 5분을 얻습니다.335[서브에이전트](https://code.claude.com/docs/ko/sub-agents.md)는 부모와 별도의 자체 시스템 프롬프트와 도구 세트로 자체 대화를 시작합니다. 첫 번째 요청은 두 접두사가 다르기 때문에 부모의 캐시를 읽지 않으며, 자신의 턴에 걸쳐 자체 캐시를 워밍합니다. 서브에이전트는 메인 대화 [TTL 버킷](#which-ttl-each-request-gets) 외부에 있으므로, [더 긴 것을 선택](#choose-the-ttl-yourself)할 때까지 구독 상태에서도 5분을 얻습니다.

336 336 

337부모의 캐시는 영향을 받지 않습니다. 부모 측에서 서브에이전트의 호출과 결과는 대화에 추가되어 부모의 접두사를 그대로 유지합니다.337부모의 캐시는 영향을 받지 않습니다. 부모 측에서 서브에이전트의 호출과 결과는 대화에 추가되어 부모의 접두사를 그대로 유지합니다.

338 338 

339반면 [포크](/docs/ko/sub-agents.md#fork-the-current-conversation)는 부모의 시스템 프롬프트, 도구 및 대화 기록을 정확히 상속하므로 첫 번째 요청이 부모의 캐시를 읽습니다.339반면 [포크](https://code.claude.com/docs/ko/sub-agents.md#fork-the-current-conversation)는 부모의 시스템 프롬프트, 도구 및 대화 기록을 정확히 상속하므로 첫 번째 요청이 부모의 캐시를 읽습니다.

340 340 

341다른 요청도 이전 요청이 캐시한 접두사를 읽을 수 있습니다:341다른 요청도 이전 요청이 캐시한 접두사를 읽을 수 있습니다:

342 342 

343* **세션 복사본**: [`/fork`로 복사](/docs/ko/agent-view#copy-the-session-with-%2Ffork)한 세션은 복사된 대화의 끝에 메시지로 격리 지침을 받으므로, 원본 대화가 구축한 캐시가 그대로 유지됩니다.343* **세션 복사본**: [`/fork`로 복사](https://code.claude.com/docs/ko/agent-view#copy-the-session-with-%2Ffork)한 세션은 복사된 대화의 끝에 메시지로 격리 지침을 받으므로, 원본 대화가 구축한 캐시가 그대로 유지됩니다.

344* **압축**: [대화 압축](#compacting-the-conversation)에 설명된 요약 호출은 동일한 접두사 공유 방식을 사용합니다.344* **압축**: [대화 압축](#compacting-the-conversation)에 설명된 요약 호출은 동일한 접두사 공유 방식을 사용합니다.

345* **재개된 서브에이전트**: Claude가 [서브에이전트를 재개](/docs/ko/sub-agents.md#resume-subagents)할 때, 재개된 실행의 첫 번째 요청은 원본 실행이 워밍한 캐시를 읽을 수 있습니다.345* **재개된 서브에이전트**: Claude가 [서브에이전트를 재개](https://code.claude.com/docs/ko/sub-agents.md#resume-subagents)할 때, 재개된 실행의 첫 번째 요청은 원본 실행이 워밍한 캐시를 읽을 수 있습니다.

346* **워크플로우 팬아웃**: [워크플로우 팬아웃](/docs/ko/workflows.md#prompt-caching-in-a-fan-out)에서 동일 접두사 에이전트의 경우, Claude Code는 첫 번째를 제외한 모든 것을 기본적으로 최대 5초 동안 보유하므로, 첫 번째 요청이 첫 번째 에이전트가 캐시한 접두사를 읽을 수 있습니다.346* **워크플로우 팬아웃**: [워크플로우 팬아웃](https://code.claude.com/docs/ko/workflows.md#prompt-caching-in-a-fan-out)에서 동일 접두사 에이전트의 경우, Claude Code는 첫 번째를 제외한 모든 것을 기본적으로 최대 5초 동안 보유하므로, 첫 번째 요청이 첫 번째 에이전트가 캐시한 접두사를 읽을 수 있습니다.

347 347 

348## prompt caching 비활성화348## prompt caching 비활성화

349 349 

365 365 

366`DISABLE_PROMPT_CACHING_SONNET`과 `DISABLE_PROMPT_CACHING_OPUS`는 각각 `sonnet` 또는 `opus` 별칭이 확인되는 모델에 적용됩니다. 다른 Sonnet 또는 Opus 모델 ID를 주 모델로 설정하면 해당 모델은 caching을 유지합니다. 예를 들어, `claude-sonnet-5`에서의 세션은 caching을 유지하지만 `sonnet`은 `claude-sonnet-5-5`로 확인됩니다. 해당 모델에 대해 caching을 비활성화하려면 `DISABLE_PROMPT_CACHING`을 설정합니다.366`DISABLE_PROMPT_CACHING_SONNET`과 `DISABLE_PROMPT_CACHING_OPUS`는 각각 `sonnet` 또는 `opus` 별칭이 확인되는 모델에 적용됩니다. 다른 Sonnet 또는 Opus 모델 ID를 주 모델로 설정하면 해당 모델은 caching을 유지합니다. 예를 들어, `claude-sonnet-5`에서의 세션은 caching을 유지하지만 `sonnet`은 `claude-sonnet-5-5`로 확인됩니다. 해당 모델에 대해 caching을 비활성화하려면 `DISABLE_PROMPT_CACHING`을 설정합니다.

367 367 

368조직 전체에서 caching 정책을 설정하려면 이러한 변수 중 하나 또는 [TTL 변수](#cache-lifetime)를 [관리되는 설정](/docs/ko/managed-settings.md)의 `env` 블록에 넣습니다. 일반적인 사용을 위해서는 caching을 활성화된 상태로 두십시오.368조직 전체에서 caching 정책을 설정하려면 이러한 변수 중 하나 또는 [TTL 변수](#cache-lifetime)를 [관리되는 설정](https://code.claude.com/docs/ko/managed-settings.md)의 `env` 블록에 넣습니다. 일반적인 사용을 위해서는 caching을 활성화된 상태로 두십시오.

369 369 

370## 관련 리소스370## 관련 리소스

371 371 

372* [Claude Code 구축에서 배운 교훈: 프롬프트 캐싱이 모든 것입니다](https://claude.com/blog/lessons-from-building-claude-code-prompt-caching-is-everything): Plan 모드, 연기된 도구 로딩 및 압축의 설계 근거372* [Claude Code 구축에서 배운 교훈: 프롬프트 캐싱이 모든 것입니다](https://claude.com/blog/lessons-from-building-claude-code-prompt-caching-is-everything): Plan 모드, 연기된 도구 로딩 및 압축의 설계 근거

373* [컨텍스트 윈도우 탐색](/docs/ko/context-window.md): 컨텍스트에 로드되는 내용 및 시기373* [컨텍스트 윈도우 탐색](https://code.claude.com/docs/ko/context-window.md): 컨텍스트에 로드되는 내용 및 시기

374* [토큰 사용량 감소](/docs/ko/costs.md#reduce-token-usage): 컨텍스트 크기 관리를 위한 캐싱 이상의 전략374* [토큰 사용량 감소](https://code.claude.com/docs/ko/costs.md#reduce-token-usage): 컨텍스트 크기 관리를 위한 캐싱 이상의 전략

375* [비용 추적 및 감소](/docs/ko/agent-sdk/cost-tracking.md): Agent SDK 호출자를 위한 캐시 토큰 추적 및 TTL 구성375* [비용 추적 및 감소](https://code.claude.com/docs/ko/agent-sdk/cost-tracking.md): Agent SDK 호출자를 위한 캐시 토큰 추적 및 TTL 구성

376* [프롬프트 캐싱](https://platform.claude.com/docs/en/build-with-claude/prompt-caching): 기본 API 메커니즘, 중단점 및 가격 책정376* [프롬프트 캐싱](https://platform.claude.com/docs/en/build-with-claude/prompt-caching): 기본 API 메커니즘, 중단점 및 가격 책정