2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> 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.3> Use this file to discover all available pages before exploring further.

4 4 

5# Claude Code가 프롬프트 캐싱을 사용하는 방법5# Claude Code가 prompt caching을 사용하는 방법

6 6 

7> Claude Code는 프롬프트 캐싱을 자동으로 관리합니다. 모델 전환이 느린 캐시되지 않은 턴을 트리거하는 이유, `/compact`의 비용, CLAUDE.md 편집이 세션 중에 적용되지 않는 이유, 캐시 히트율을 확인하는 방법을 알아봅니다.7> Claude Code는 prompt caching을 자동으로 관리합니다. 모델 전환이 느린 캐시되지 않은 턴을 트리거하는 이유, `/compact`의 비용, CLAUDE.md 편집이 세션 중에 적용되지 않는 이유, 캐시 히트율을 확인하는 방법을 알아봅니다.

8 8 

9프롬프트 캐싱은 Claude Code를 더 빠르고 비용 효율적으로 만듭니다. 캐싱이 없으면 API는 매 턴마다 전체 기록을 다시 처리합니다. 캐싱을 사용하면 이미 처리한 내용을 재사용하고 변경된 내용에 대해서만 새로운 작업을 수행합니다.9Prompt caching은 Claude Code를 더 빠르고 비용 효율적으로 만듭니다. Caching이 없으면 API는 매 턴마다 전체 기록을 다시 처리합니다. Caching을 사용하면 이미 처리한 내용을 재사용하고, 재읽기를 [캐시된 토큰 요금](https://platform.claude.com/docs/en/about-claude/pricing)으로 청구하며, 변경된 내용만 완전히 처리합니다.

10 10 

11Claude Code는 [캐싱을 비활성화](#disable-prompt-caching)하지 않는 한 프롬프트 캐싱을 자동으로 처리합니다. 일부 작업이 캐시를 무효화하고 다음 응답을 더 느리고 비싸게 만들기 때문에 프롬프트 캐싱이 어떻게 작동하는지 아는 것이 여전히 유용합니다. 이 페이지에서는 어떤 작업이 그러한지, 일부 설정이 재시작을 기다리는 이유, 사용량이 높아 보일 때 캐시 성능을 확인하는 방법을 다룹니다.11Claude Code는 [비활성화](#disable-prompt-caching)하지 않는 한 prompt caching을 자동으로 처리합니다. 일부 작업이 캐시를 무효화하고 다음 응답을 더 느리고 비싸게 만들기 때문에 prompt caching이 어떻게 작동하는지 아는 것이 여전히 유용합니다. 이 페이지에서는 어떤 작업이 그러한지, 일부 설정이 적용되기 위해 재시작을 기다리는 이유, 사용량이 높아 보일 때 캐시 성능을 확인하는 방법을 다룹니다.

12 12 

13<h2 id="how-the-cache-is-organized">13<h2 id="how-the-cache-is-organized">

14 캐시가 구성되는 방식14 캐시가 어떻게 구성되는지

15</h2>15</h2>

16 16 

17Claude Code에서 메시지를 보낼 때마다 새로운 API 요청을 만듭니다. 모델은 요청 간에 아무것도 기억하지 않으므로 Claude Code는 전체 컨텍스트를 다시 보냅니다: 시스템 프롬프트, 프로젝트 컨텍스트, 모든 이전 메시지 및 도구 결과, 그리고 새로운 메시지입니다. 새로운 콘텐츠는 끝에 추가되므로 각 요청의 대부분은 이전 요청과 동일합니다. Prompt caching은 API가 변경되지 않은 부분을 다시 처리하지 않도록 하는 방법입니다.17Claude Code에서 메시지를 보낼 때마다 새로운 API 요청을 만듭니다. 모델은 요청 간에 아무것도 기억하지 않으므로 Claude Code는 전체 컨텍스트를 다시 보냅니다: 시스템 프롬프트, 프로젝트 컨텍스트, 모든 이전 메시지와 도구 결과, 그리고 새로운 메시지입니다. 새로운 콘텐츠는 끝에 추가되므로 각 요청의 대부분은 이전 요청과 동일합니다. 프롬프트 캐싱은 API가 변경되지 않은 부분을 다시 처리하지 않도록 하는 방법입니다.

18 18 

19API는 각 요청의 시작 부분(프리픽스라고 함)을 최근에 처리한 콘텐츠와 일치시켜 캐시합니다. 일반적인 턴에서 프리픽스는 전체 이전 요청이고 최신 교환만 새로운 것입니다. 일치는 정확하므로 프리픽스의 어디든지 변경되면 그 이후의 모든 것을 다시 계산합니다. 파일별 또는 세그먼트별 캐싱은 없습니다. API 참조에서 [prompt caching이 작동하는 방식](https://platform.claude.com/docs/ko/build-with-claude/prompt-caching#how-prompt-caching-works)을 참조하여 기본 메커니즘을 확인하세요.19API는 각 요청의 시작 부분(프리픽스라고 함)을 최근에 처리한 콘텐츠와 일치시켜 캐시합니다. 일반적인 턴에서 프리픽스는 전체 이전 요청이고 최신 교환만 새로운 것입니다. 일치는 정확하므로 프리픽스의 어느 곳이든 변경되면 그 이후의 모든 것이 다시 계산됩니다. 파일별 또는 세그먼트별 캐싱은 없습니다. API 참조에서 [프롬프트 캐싱이 어떻게 작동하는지](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#how-prompt-caching-works)를 참조하세요.

20 20 

21<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=f2e8f0b8298a50305fe428ca3f1d1594" className="dark:hidden" alt="네 개의 턴이 증가하는 수평 막대로 표시됩니다. 각 턴의 요청은 이전 턴의 모든 것과 끝에 추가된 최신 교환을 포함합니다. 턴 2와 3에서는 변경되지 않은 프리픽스가 캐시에서 읽혀지고 새로운 교환만 처리됩니다. 턴 4에서는 시스템 프롬프트가 변경되어 프리픽스가 더 이상 일치하지 않으므로 전체 요청이 다시 처리되고 기록됩니다." width="720" height="454" data-path="images/prompt-caching-prefix.svg" />21<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=f2e8f0b8298a50305fe428ca3f1d1594" className="dark:hidden" alt="네 개의 턴이 증가하는 수평 막대로 표시됩니다. 각 턴의 요청은 이전 턴의 모든 것과 끝에 추가된 최신 교환을 포함합니다. 턴 2와 3에서는 변경되지 않은 프리픽스가 캐시에서 읽혀지고 새로운 교환만 처리됩니다. 턴 4에서는 시스템 프롬프트가 변경되어 프리픽스가 더 이상 일치하지 않으므로 전체 요청이 다시 처리되고 기록됩니다." width="720" height="454" data-path="images/prompt-caching-prefix.svg" />

22 22 

25프리픽스 일치를 최대한 활용하기 위해 Claude Code는 각 요청을 정렬하여 턴 간에 거의 변경되지 않는 콘텐츠가 먼저 오도록 합니다:25프리픽스 일치를 최대한 활용하기 위해 Claude Code는 각 요청을 정렬하여 턴 간에 거의 변경되지 않는 콘텐츠가 먼저 오도록 합니다:

26 26 

27| 계층 | 콘텐츠 | 변경 시기 |27| 계층 | 콘텐츠 | 변경 시기 |

28| --------- | -------------------------------- | --------------------------------------- |28| --------- | ---------------------------- | ----------------------------------- |

29| 시스템 프롬프트 | 핵심 지침, 도구 정의, 출력 스타일 | 로드된 도구 정의 집합이 변경되거나 Claude Code가 업그레이드됨 |29| 시스템 프롬프트 | 핵심 지침, 도구 정의 | 로드된 도구 정의 집합이 변경될 때 |

30| 프로젝트 컨텍스트 | CLAUDE.md, 자동 메모리, 범위 지정되지 않은 규칙 | 세션 시작, 또는 `/clear` 또는 `/compact` 후 |30| 프로젝트 컨텍스트 | CLAUDE.md, 자동 메모리, 범위 미지정 규칙 | 세션 시작 후 또는 `/clear` 또는 `/compact` 후 |

31| 대화 | 사용자 메시지, Claude의 응답, 도구 결과 | 매 턴 |31| 대화 | 사용자 메시지, Claude의 응답, 도구 결과 | 매 턴마다 |

32 32 

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

34 34 

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

36 36 

37두 가지 설정은 프롬프트 텍스트의 일부가 아니므로 계층 표에 나타나지 않습니다. 하지만 둘 다 캐시 키의 일부입니다:37두 가지 설정은 계층 표에 나타나지 않지만 여전히 캐시된 상태에 영향을 미칩니다:

38 38 

39* **모델**: 각 모델은 자체 캐시를 가집니다. 모델을 전환하면 콘텐츠가 동일한 경우에도 전체 요청을 다시 계산합니다. 아래의 [모델 전환](#switching-models)을 참조하세요.39* **모델**: 각 모델은 자체 캐시를 가집니다. 모델을 전환하면 콘텐츠가 동일한 경우에도 전체 요청이 다시 계산됩니다. 아래의 [모델 전환](#switching-models)을 참조하세요.

40* **노력 수준**: 각 노력 수준은 동일한 모델에 대해 자체 캐시를 가집니다. 세션 중에 변경하면 전체 요청을 다시 계산하며, Claude Code는 변경을 적용하기 전에 확인을 요청합니다. 아래의 [노력 수준 변경](#changing-effort-level)을 참조하세요.40* **노력 수준**: 대부분의 모델에서 각 노력 수준은 자체 캐시를 가지므로 세션 중에 노력을 변경하면 전체 요청이 다시 계산됩니다. API 키 또는 Claude 구독이 있는 Fable 5.1에서는 기본적으로 캐시가 그대로 유지됩니다. 아래의 [노력 수준 변경](#changing-effort-level)을 참조하세요.

41 41 

42<Tip>42<Tip>

43 세션 시작 시 모델과 노력 수준을 선택한 다음 작업 간의 자연스러운 휴식을 위해 `/compact`를 저장합니다. 작업 중에 변경할수록 캐시 히트율이 높아집니다.43 세션 시작 시 모델과 노력 수준을 선택한 다음 작업 간의 자연스러운 중단점을 위해 `/compact`를 저장하세요. 작업 중에 변경을 적게 할수록 캐시 히트율이 높아집니다.

44</Tip>44</Tip>

45 45 

46<h3 id="where-the-cache-lives">46<h3 id="where-the-cache-lives">

47 캐시가 있는 위치47 캐시가 어디에 있는지

48</h3>48</h3>

49 49 

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

51 51 

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

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

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

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

56 56 

57각 제공자가 저장하고 처리하는 내용은 [데이터 사용](/docs/ko/data-usage)을 참조하세요. 캐시가 어디에 있든 항목은 비활성 기간 후에 만료되며, 아래의 [캐시 수명](#cache-lifetime)에서 TTL과 연장 방법을 다룹니다.57Claude Code는 또한 파일 변경 알림과 같은 시스템 컨텍스트를 대화 중에 추가하고, [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)를 설정하지 않는 한 모든 제공자 및 연결에서 캐싱을 위해 해당 블록을 표시합니다. 이 경우 해당 블록은 캐시되지 않은 상태로 전송됩니다.

58 

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

60 

61요청이 [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)를 어떻게 처리하는지에 따라 다릅니다:

62 

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

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

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

66 

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

58 68 

59<h2 id="actions-that-invalidate-the-cache">69<h2 id="actions-that-invalidate-the-cache">

60 캐시를 무효화하는 작업70 캐시를 무효화하는 작업

61</h2>71</h2>

62 72 

63이러한 작업으로 인해 다음 요청이 캐시의 일부 또는 전부를 놓칩니다. 한 번의 느리고 비싼 턴을 본 후 새로운 프리픽스가 캐시됩니다. 대부분은 작업 중에 비용이 있다는 것을 알면 피할 수 있습니다. 모델 전환은 뒤따르는 느린 턴을 알아차릴 때까지 무료로 느껴질 수 있습니다.73이러한 작업들은 다음 요청이 캐시의 일부 또는 전체를 놓치게 합니다. 한 번 느리고 더 비싼 턴을 보게 되며, 그 후 새로운 접두사가 캐시됩니다. 대부분은 작업 중에 비용이 있다는 것을 알면 피할 수 있습니다. 모델 전환은 뒤따르는 느린 턴을 알아차릴 때까지 자유로워 보일 수 있습니다.

64 74 

65* [모델 전환](#switching-models)75* [모델 전환](#switching-models)

66* [노력 수준 변경](#changing-effort-level)76* [노력 수준 변경](#changing-effort-level)

69* [플러그인 활성화 또는 비활성화](#enabling-or-disabling-a-plugin)79* [플러그인 활성화 또는 비활성화](#enabling-or-disabling-a-plugin)

70* [전체 도구 거부](#denying-an-entire-tool)80* [전체 도구 거부](#denying-an-entire-tool)

71* [대화 압축](#compacting-the-conversation)81* [대화 압축](#compacting-the-conversation)

82* [많은 이미지 누적](#accumulating-many-images)

72* [Claude Code 업그레이드](#upgrading-claude-code)83* [Claude Code 업그레이드](#upgrading-claude-code)

73 84 

74<h3 id="switching-models">85<h3 id="switching-models">

75 모델 전환86 모델 전환

76</h3>87</h3>

77 88 

78각 모델은 자체 캐시를 가집니다. [`/model`](/docs/ko/model-config#setting-your-model)로 전환하면 콘텐츠가 동일한 경우에도 다음 요청이 캐시 히트 없이 전체 대화 기록을 읽습니다.89각 모델에는 자체 캐시가 있습니다. [`/model`](/docs/ko/model-config#setting-your-model)로 전환하면 내용이 동일하더라도 다음 요청이 캐시 히트 없이 전체 대화 기록을 읽습니다.

90 

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

92 

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

94 

95[PreModelSwitch hook](/docs/ko/hooks#premodelswitch-decision-control)으로 이 확인을 요구하거나 건너뛸 수도 있습니다.

79 96 

80[`opusplan` 모델 설정](/docs/ko/model-config#opusplan-model-setting)은 Plan 모드 중에 Opus로, 실행 중에 Sonnet으로 확인되므로 각 Plan 모드 토글은 모델 전환이고 새로운 캐시를 시작합니다.97[`opusplan` 모델 설정](/docs/ko/model-config#opusplan-model-setting)은 계획 모드 중에는 Opus로, 실행 중에는 Sonnet으로 확인되므로 각 계획 모드 토글은 모델 전환이며 새로운 캐시를 시작합니다.

81 98 

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

100 

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

83 102 

84<h3 id="changing-effort-level">103<h3 id="changing-effort-level">

85 노력 수준 변경104 노력 수준 변경

86</h3>105</h3>

87 106 

88캐시는 [노력 수준](/docs/ko/model-config#adjust-effort-level)뿐만 아니라 모델로도 키가 지정되므로 `/effort`로 전환하면 다음 요청이 캐시 히트 없이 전체 대화 기록을 읽습니다. 대화가 시작되면 Claude Code는 캐시를 무효화할 노력 변경을 적용하기 전에 확인 대화를 표시합니다. 모델의 기본값을 명시적으로 설정하는 것과 같이 이미 적용 중인 동일한 수준으로 확인되는 변경은 대화를 건너뛰고 캐시를 유지합니다.107대부분의 모델에서 세션 중에 [노력 수준](/docs/ko/model-config#adjust-effort-level)을 변경하면 다음 요청이 캐시 히트 없이 전체 대화 기록을 읽습니다. 캐시가 여전히 따뜻한 동안 Claude Code는 먼저 변경을 확인하도록 요청합니다.

108 

109API 키 또는 Claude 구독이 있는 Fable 5.1에서 노력을 변경하면 캐시가 유지되고 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 구성이 있을 때도 적용되지 않습니다.

110 

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

89 112 

90<h3 id="turning-on-fast-mode">113<h3 id="turning-on-fast-mode">

91 빠른 모드 켜기114 빠른 모드 켜기

92</h3>115</h3>

93 116 

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

95 118 

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

97 120 

98<h3 id="connecting-or-disconnecting-an-mcp-server">121<h3 id="connecting-or-disconnecting-an-mcp-server">

99 MCP 서버 연결 또는 연결 해제122 MCP 서버 연결 또는 연결 해제

100</h3>123</h3>

101 124 

102도구 정의는 시스템 프롬프트 계층에 있으므로 요청 간에 도구 정의 집합이 변경되면 캐시가 무효화됩니다. [advisor 도구](/docs/ko/advisor)를 토글하는 것은 예외입니다: 해당 정의는 캐시 중단점 이후에 있으므로 `/advisor`를 활성화 또는 비활성화하면 캐시된 프리픽스가 그대로 유지됩니다. [MCP 서버](/docs/ko/mcp) 변경이 이를 수행하는지 여부는 해당 도구가 [도구 검색](/docs/ko/mcp#scale-with-mcp-tool-search)으로 연기되는지 또는 프리픽스에 로드되는지에 따라 달라집니다:125도구 정의는 시스템 프롬프트 레이어에 있으므로 턴 간에 요청의 도구 정의 집합이 변경되면 캐시가 무효화됩니다. [advisor 도구](/docs/ko/advisor)를 토글하는 것은 예외입니다. 그 정의는 캐시 breakpoint 후에 있으므로 `/advisor`를 활성화하거나 비활성화하면 캐시된 접두사가 그대로 유지됩니다. [MCP 서버](/docs/ko/mcp) 변경이 이를 수행하는지 여부는 해당 도구가 [도구 검색](/docs/ko/mcp#scale-with-mcp-tool-search)으로 연기되는지 또는 접두사에 로드되는지에 따라 달라집니다.

103 126 

104* **연기된 도구**, 지원되는 모델의 기본값: 서버 연결, 연결 해제 또는 도구 목록 변경은 새로운 콘텐츠만 추가하고 이미 캐시된 항목을 방해하지 않습니다.127* **연기된 도구**, 지원되는 모델의 기본값: 서버 연결, 연결 해제 또는 도구 목록 변경은 새 콘텐츠만 추가하고 이미 캐시된 것을 방해하지 않습니다.

105* **프리픽스에 로드된 도구**: 이에 대한 모든 변경은 캐시를 무효화합니다. 이는 [도구 검색을 사용할 수 없거나 비활성화](/docs/ko/mcp#configure-tool-search)된 경우(예: Google Cloud의 Agent Platform 또는 사용자 정의 `ANTHROPIC_BASE_URL` 게이트웨이)에 발생합니다. 또한 [`alwaysLoad`](/docs/ko/mcp#exempt-a-server-from-deferral)로 표시된 서버 또는 도구, 그리고 [임계값 기반 로딩](/docs/ko/mcp#configure-tool-search)으로 유지되는 정의에 대해서도 발생합니다.128* **접두사에 로드된 도구**: 이들에 대한 모든 변경이 캐시를 무효화합니다. 이는 [도구 검색을 사용할 수 없거나 비활성화](/docs/ko/mcp#configure-tool-search)된 경우에 발생합니다. 예를 들어 Claude 4.5 세대보다 이전의 Google Cloud의 Agent Platform 모델, 사용자 정의 `ANTHROPIC_BASE_URL` 게이트웨이, 또는 Claude Code가 배포가 도구 검색을 거부한다는 것을 감지하면 Microsoft Foundry [Azure에서 호스팅되는 배포](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)에서 발생합니다. 또한 [`alwaysLoad`](/docs/ko/mcp#exempt-a-server-from-deferral)로 표시된 서버 또는 도구에 대해, 그리고 [임계값 기반 로딩](/docs/ko/mcp#configure-tool-search)으로 유지되는 정의에 대해 발생합니다.

106 129 

107도구가 프리픽스에 로드될 때 무효화의 가장 일반적인 원인은 세션 중에 서버가 연결 또는 연결 해제되는 것입니다. 이는 사용자의 조치 없이 발생할 수 있습니다: stdio 서버의 프로세스가 종료되거나, HTTP 세션이 만료되거나, 서버가 [일시적 오류 후 자동으로 재연결](/docs/ko/mcp#automatic-reconnection)됩니다. 연결된 서버는 도구 목록을 변경하는 [동적 도구 업데이트](/docs/ko/mcp#dynamic-tool-updates)를 푸시할 수도 있습니다.130도구가 접두사에 로드될 때 무효화의 가장 일반적인 원인은 세션 중에 서버가 연결되거나 연결 해제되는 것입니다. 이는 사용자의 조치 없이 발생할 수 있습니다. stdio 서버의 프로세스가 종료되거나, HTTP 세션이 만료되거나, 서버가 [일시적 오류 후 자동으로 다시 연결](/docs/ko/mcp#automatic-reconnection)됩니다. 연결된 서버는 또한 도구 목록을 변경하는 [동적 도구 업데이트](/docs/ko/mcp#dynamic-tool-updates)를 푸시할 수 있습니다.

108 131 

109MCP 구성을 편집해도 캐시가 자동으로 변경되지 않습니다. 새로운 구성은 재시작 후에만 적용되며, 이때 서버가 연결 또는 연결 해제됩니다.132MCP 구성을 편집해도 캐시가 변경되지 않습니다. 새 구성은 재시작 후에만 적용되며, 이때 서버가 연결되거나 연결 해제됩니다.

110 133 

111<h3 id="enabling-or-disabling-a-plugin">134<h3 id="enabling-or-disabling-a-plugin">

112 플러그인 활성화 또는 비활성화135 플러그인 활성화 또는 비활성화

113</h3>136</h3>

114 137 

115[플러그인](/docs/ko/plugins)은 여러 구성 요소 유형을 번들로 제공하며, 변경 비용은 플러그인이 제공하는 구성 요소에 따라 달라집니다. Skills, commands, agents, hooks, LSP 서버, monitors, themes는 캐시를 무효화하지 않습니다: 이들이 요청에 추가하는 모든 것은 기존 대화 후에 추가되므로 다음 요청은 새로운 콘텐츠에 대해 비용을 지불하지만 여전히 그 이전의 모든 것을 캐시에서 읽습니다.138[플러그인](/docs/ko/plugins)을 활성화하거나 비활성화할 때 변경 비용은 플러그인이 제공하는 구성 요소 유형에 따라 달라집니다. 아래 경우는 각 구성 요소 유형, Claude Code가 변경을 적용하는 시기, 같은 세션에서 플러그인을 다시 비활성화할 때 발생하는 상황을 다룹니다.

139 

140<h4 id="plugin-components-that-keep-the-cache">

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

142</h4>

143 

144Claude Code는 플러그인의 스킬, 명령, 에이전트, hook, 모니터 또는 테마에 대해 캐시를 무효화하지 않습니다. 기존 대화 후에 콘텐츠를 추가하므로 다음 요청이 해당 콘텐츠에 대해 비용을 지불하고 여전히 캐시에서 그 전의 모든 것을 읽습니다.

145 

146<h4 id="plugins-that-provide-mcp-servers">

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

148</h4>

149 

150[MCP 서버](/docs/ko/plugins-reference#mcp-servers)를 제공하는 플러그인을 활성화하거나 비활성화할 때 Claude Code는 [MCP 서버를 연결하거나 연결 해제](#connecting-or-disconnecting-an-mcp-server)할 때와 동일한 규칙을 따릅니다.

116 151 

117예외는 [MCP 서버](/docs/ko/plugins-reference#mcp-servers)를 제공하는 플러그인입니다. 하나를 활성화 또는 비활성화하면 [MCP 서버 연결 또는 연결 해제](#connecting-or-disconnecting-an-mcp-server)와 동일한 규칙을 따릅니다: 서버의 도구가 연기될 때 캐시가 유지되고, 프리픽스에 로드될 때 다음 요청이 전체 대화를 다시 읽습니다.152* Claude Code가 서버의 도구를 연기하면 캐시를 유지합니다.

153* Claude Code가 도구를 접두사에 로드하면 다음 요청이 전체 대화를 다시 읽습니다.

118 154 

119플러그인 변경은 [`/reload-plugins`](/docs/ko/discover-plugins#apply-plugin-changes-without-restarting)를 실행하거나 새 세션을 시작할 때 적용됩니다. 비용(추가된 공지 사항이든 전체 다시 읽기든)은 다시 로드 후 첫 턴에 표시되며, `/plugin install`, `/plugin enable` 또는 `/plugin disable`을 실행할 때가 아닙니다. v2.1.163부터 다시 로드가 전체 다시 읽기를 트리거할 때 `/reload-plugins`는 경고를 표시하고 다시 로드를 적용하지 않습니다. `--force`를 전달하여 어차피 적용합니다.155<h4 id="code-intelligence-plugins">

156 코드 인텔리전스 플러그인

157</h4>

120 158 

121세션 초반에 활성화한 플러그인을 비활성화하면 이전 요청 형태가 복원됩니다. 해당 프리픽스가 여전히 [캐시 수명](#cache-lifetime) 내에 있으면 다음 요청이 다시 구축하는 대신 이전 캐시 항목을 읽습니다.159[코드 인텔리전스 플러그인](/docs/ko/discover-plugins#code-intelligence)을 활성화하면 Claude는 [LSP 도구](/docs/ko/tools-reference#lsp-tool-behavior)를 얻습니다.

160 

161<h4 id="when-plugin-changes-apply">

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

163</h4>

164 

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

166 

167* `command` 소스가 있는 플러그인의 경우 Claude Code는 [플러그인 자체를 다시 로드](/docs/ko/plugin-marketplaces#when-claude-code-re-runs-the-command)할 수 있습니다.

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

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

170* 대화형 세션에서 `--plugin-dir`으로 전달한 [플러그인 폴더](/docs/ko/plugins#test-your-plugins-locally)에서 플러그인을 추가하거나 제거할 때 변경이 즉시 적용됩니다. 적용할 경우 전체 다시 읽기가 트리거된다면 Claude Code는 대신 변경을 보류하고 `/reload-plugins`를 실행하라는 공지를 표시합니다. Claude Code v2.1.265 이상이 필요합니다.

171 

172`/reload-plugins`가 실행되고 다시 로드가 전체 다시 읽기를 트리거하면 Claude Code는 경고를 표시하고 다시 로드를 적용하지 않습니다. `/reload-plugins --force`를 실행하여 어쨌든 적용합니다.

173 

174`/reload-plugins`는 또한 데스크톱 앱, Agent SDK, [비대화형 모드](/docs/ko/headless)(`-p` 포함)와 같이 대화형 터미널이 없는 세션에서 실행되며, 세션에 직접 입력할 때 실행됩니다. Claude Code v2.1.260 이상이 필요합니다.

175 

176이러한 세션에서 다시 로드는 플러그인 MCP 서버 변경을 제외한 모든 것을 적용하며, [다음 세션에서 적용](/docs/ko/discover-plugins#apply-plugin-changes-without-restarting)되므로 세션 중에 전체 다시 읽기 비용이 발생하지 않습니다.

177 

178<h4 id="plugins-you-enable-and-then-disable-in-one-session">

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

180</h4>

181 

182세션 초반에 활성화한 플러그인을 비활성화할 때 Claude Code는 이전 요청 형태를 복원합니다. 해당 접두사가 여전히 [캐시 수명](#cache-lifetime) 내에 있으면 다음 요청이 다시 빌드하는 대신 이전 캐시 항목을 읽습니다.

122 183 

123<h3 id="denying-an-entire-tool">184<h3 id="denying-an-entire-tool">

124 전체 도구 거부185 전체 도구 거부

125</h3>186</h3>

126 187 

127`Bash` 또는 `WebFetch`와 같은 단순 도구 이름을 [거부 규칙](/docs/ko/permissions#manage-permissions)으로 추가하면 해당 도구가 Claude의 컨텍스트에서 완전히 제거됩니다. 기본 제공 도구 정의는 시스템 프롬프트 계층에 로드되므로 이러한 규칙을 추가하거나 제거하면 세션 중에 캐시가 무효화됩니다. 변경 사항은 `/permissions`를 통해 추가하든 [설정 파일을 직접 편집](/docs/ko/settings#when-edits-take-effect)하든 다음 턴에 적용됩니다.188`Bash` 또는 `WebFetch`와 같은 단순 도구 이름을 [거부 규칙](/docs/ko/permissions#manage-permissions)으로 추가하면 해당 도구가 Claude의 컨텍스트에서 완전히 제거됩니다. Claude Code는 기본 제공 도구 정의를 시스템 프롬프트 레이어에 로드하므로 세션 중에 이러한 규칙 중 하나를 추가하거나 제거하면 캐시가 무효화됩니다. Claude Code는 `/permissions`를 통해 규칙을 추가하거나 [설정 파일을 직접 편집](/docs/ko/settings#when-edits-take-effect)하여 다음 요청에 변경을 적용합니다. 여기에는 턴 중간에 `/permissions`를 통해 추가하는 규칙이 포함됩니다.

128 189 

129단순 도구 이름, 동등한 `Bash(*)` 형식, 또는 `"*"`와 같은 [도구 이름 글로브](/docs/ko/permissions#tool-name-wildcards)만 이 효과를 가집니다. `"mcp__*"`와 같이 MCP 도구만 일치하는 글로브는 해당 도구를 동일한 방식으로 제거하지만 일치하는 도구가 [연기](#connecting-or-disconnecting-an-mcp-server)될 때 캐시를 그대로 유지합니다. 기본값이므로 연기된 정의는 캐시된 프리픽스에 없었습니다. `Bash(rm *)`와 같은 범위가 지정된 거부 규칙과 모든 허용 및 요청 규칙은 Claude가 보는 도구를 변경하지 않습니다. Claude Code는 Claude가 호출을 시도할 때 이를 확인하여 프리픽스를 그대로 유지합니다.190도구 이름 위치에서 일치하는 거부 규칙만 이 효과를 가집니다. 단순 도구 이름, 동등한 `Bash(*)` 형식, 또는 `"*"`와 같은 [도구 이름 glob](/docs/ko/permissions#tool-name-wildcards)입니다. `"mcp__*"`와 같이 MCP 도구만 일치하는 glob은 해당 도구를 같은 방식으로 제거하지만 일치하는 도구가 [연기](#connecting-or-disconnecting-an-mcp-server)되면 캐시를 그대로 유지합니다. 기본값이므로 연기된 정의는 캐시된 접두사에 없었습니다. `Bash(rm *)`과 같은 범위 지정 거부 규칙, 그리고 모든 허용 및 요청 규칙은 Claude가 보는 도구를 변경하지 않습니다. Claude Code는 Claude가 호출을 시도할 때 확인하여 접두사를 그대로 유지합니다.

130 191 

131<h3 id="compacting-the-conversation">192<h3 id="compacting-the-conversation">

132 대화 압축193 대화 압축

133</h3>194</h3>

134 195 

135[압축](/docs/ko/context-window#what-survives-compaction)은 메시지 기록을 요약으로 바꿉니다. 설계상 이는 대화 계층을 무효화합니다. 다음 요청에는 이전 요청과 프리픽스를 공유하지 않는 새로운 더 짧은 기록이 있기 때문입니다. Claude Code는 시스템 프롬프트 계층을 재사용하고 디스크에서 프로젝트 컨텍스트를 다시 로드합니다. 이는 세션 시작 이후 CLAUDE.md와 메모리가 변경되지 않은 경우에만 캐시 히트됩니다.196[압축](/docs/ko/context-window#what-survives-compaction)은 메시지 기록을 요약으로 바꿉니다. 설계상 이는 대화 레이어를 무효화합니다. 다음 요청이 이전 것과 접두사를 공유하지 않는 새로운 더 짧은 기록을 가지기 때문입니다. Claude Code는 대화가 [변경될 시스템 프롬프트를 유지하면서 재개](#resuming-a-session)되지 않는 한 시스템 프롬프트 레이어를 재사용합니다. 그 경우 첫 번째 압축이 현재 프롬프트로 전환되고 해당 레이어가 한 번 다시 빌드됩니다. 디스크에서 프로젝트 컨텍스트를 다시 로드하며, 세션 시작 이후 CLAUDE.md 및 메모리가 변경되지 않은 경우에만 캐시 히트합니다.

197 

198요약을 생성하기 위해 Claude Code는 대화와 동일한 시스템 프롬프트, 도구, 기록을 가진 별도의 요청을 보내고 최종 사용자 메시지로 요약 지침을 추가합니다. 캐시가 따뜻한 동안 해당 요청이 캐시에서 접두사를 읽으므로 세션 중 `/compact`는 컨텍스트 크기가 제안하는 것의 일부 비용이 들고 대부분의 시간을 요약 생성에 소비합니다.

136 199 

137요약을 생성하기 위해 Claude Code는 대화와 동일한 시스템 프롬프트, 도구 및 기록을 가진 일회성 요청을 보내고, 최종 사용자 메시지로 요약 지침을 추가합니다. 프리픽스를 공유하기 때문에 해당 요청은 전체 기록을 다시 처리하는 대신 기존 캐시를 읽습니다. 압축 시간의 대부분은 캐시 미스가 아닌 요약 생성에 소요됩니다. 뒤따르는 턴은 훨씬 더 짧은 요약에 대해서만 대화 캐시를 다시 구축하므로 압축 후 턴은 느린 부분이 아닙니다.200[캐시 수명](#cache-lifetime)보다 긴 휴식 후에는 읽을 캐시가 남아 있지 않으므로 요약 요청이 캐시되지 않은 입력으로 전체 기록을 다시 처리합니다. 이것이 [이전 세션을 재개](/docs/ko/sessions#resume-from-a-summary)할 때 `/compact`의 비용이 가장 많은 이유입니다. 따뜻한 경우와 차가운 경우 모두에서 압축 후 턴이 훨씬 더 짧은 요약에 대해서만 대화 캐시를 다시 빌드하므로 해당 턴이 느린 부분이 아닙니다.

138 201 

139<Tip>202<Tip>

140 압축은 더 이상 필요하지 않은 컨텍스트를 버릴 때 유리합니다. 오버헤드가 발생할 시기를 선택하려면 작업 간과 같은 자연스러운 휴식 시간에 `/compact`를 실행하고, 자동 압축이 작업 중에 트리거될 때까지 기다리지 마세요. 완전히 포기하고 싶은 경로를 따라가셨다면 압축이 새로운 경로를 구축하는 대신 이미 캐시된 프리픽스로 다시 자르는 [`/rewind`](#rewinding-the-conversation)를 사용하세요.203 압축은 더 이상 필요하지 않은 컨텍스트를 버릴 때 유리합니다. 오버헤드가 발생하는 시기를 선택하려면 작업 간 또는 작업 간과 같은 자연스러운 휴식 시간에 `/compact`를 실행하고 자동 압축이 작업 중에 트리거될 때까지 기다리지 마세요. 완전히 포기하고 싶은 경로를 따라가면 대신 [이전 턴으로 `rewinding`](#rewinding-the-conversation)하세요. 되감기는 압축이 수행하는 새로운 것을 빌드하는 대신 이미 캐시된 접두사로 다시 자릅니다.

141</Tip>204</Tip>

142 205 

206<h3 id="accumulating-many-images">

207 많은 이미지 누적

208</h3>

209 

210API는 각 요청이 수행할 수 있는 이미지 및 PDF의 수를 제한합니다. 현재 숫자는 API 문서의 [요청 제한](https://platform.claude.com/docs/en/build-with-claude/vision#request-limits)을 참조하세요. Claude Code는 또한 요청의 이미지 및 PDF의 총 크기를 제한하므로 큰 스크린샷은 작은 것보다 더 적은 이미지로 제한에 도달합니다.

211 

212다음 요청이 제한을 초과하면 Claude Code는 보내는 것에서 가장 오래된 이미지 및 PDF의 배치를 제거하여 다시 제거해야 하기 전에 더 많은 공간을 확보합니다. Claude는 더 이상 제거된 이미지를 볼 수 없습니다. Claude가 다시 필요하면 다시 공유하세요.

213 

214이미지를 제거하면 이를 보유한 메시지가 변경되므로 다음 요청이 해당 메시지 중 가장 이른 것부터 대화를 다시 처리합니다. Claude Code가 한 번에 배치를 제거하기 때문에 각 새 스크린샷마다 하나씩이 아니라 배치당 한 번의 느린 턴을 봅니다.

215 

143<h3 id="upgrading-claude-code">216<h3 id="upgrading-claude-code">

144 Claude Code 업그레이드217 Claude Code 업그레이드

145</h3>218</h3>

146 219 

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

148 221 

149<Note>222<Note>

150 업그레이드 후 [세션을 재개](/docs/ko/sessions#resume-a-session)하면 캐시 히트 없이 전체 대화 기록을 다시 처리합니다. 기록이 이제 다른 시스템 프롬프트 뒤에 있기 때문입니다. 비용은 재개된 대화의 길이에 따라 확장되므로 긴 세션으로 돌아가는 첫 턴이 보내는 가장 비싼 요청일 수 있습니다.223 업그레이드 전에 시작한 대화를 재개하는 비용은 [세션 재개](#resuming-a-session)를 참조하세요.

151</Note>224</Note>

152 225 

153<h2 id="actions-that-keep-the-cache">226<h2 id="actions-that-keep-the-cache">

154 캐시를 유지하는 작업227 캐시를 유지하는 작업

155</h2>228</h2>

156 229 

157이러한 작업은 대화의 끝에 추가되거나 요청을 전혀 건드리지 않습니다. CLAUDE.md 편집 또는 출력 스타일 변경과 같은 일부는 설정 변경이 재시작을 기다리는 이유이기도 합니다.230이러한 작업들은 대화의 끝에 추가되거나 요청을 전혀 건드리지 않습니다. CLAUDE.md 편집과 같은 일부 작업들은 변경 사항이 `/clear`, `/compact` 또는 재시작까지 실행 중인 세션에 도달하지 않는 이유와 동일한 이유로 캐시를 유지합니다.

158 231 

159* [저장소의 파일 편집](#editing-files-in-your-repository)232* [저장소의 파일 편집](#editing-files-in-your-repository)

160* [세션 중 CLAUDE.md 편집](#editing-claude-md-mid-session)233* [세션 중 CLAUDE.md 편집](#editing-claude-md-mid-session)

161* [출력 스타일 변경](#changing-output-style)

162* [권한 모드 변경](#changing-permission-mode)234* [권한 모드 변경](#changing-permission-mode)

235* [출력 스타일 변경](#changing-output-style)

163* [스킬 및 명령 호출](#invoking-skills-and-commands)236* [스킬 및 명령 호출](#invoking-skills-and-commands)

164* [`/recap` 실행](#running-%2Frecap)237* [`/recap` 실행](#running-%2Frecap)

165* [대화 되감기](#rewinding-the-conversation)238* [대화 되감기](#rewinding-the-conversation)

169 저장소의 파일 편집242 저장소의 파일 편집

170</h3>243</h3>

171 244 

172파일 콘텐츠는 Claude가 읽을 때만 컨텍스트에 들어가며, 읽기는 대화에 추가됩니다. Claude가 이전에 읽은 파일을 편집해도 기록의 이전 읽기를 소급하여 변경하지 않습니다. 대신 Claude Code는 파일이 변경되었음을 나타내는 `<system-reminder>`를 추가하고, 필요한 경우 Claude가 다시 읽습니다.245파일 내용은 Claude가 파일을 읽을 때만 컨텍스트에 들어가며, 읽기는 대화에 추가됩니다. Claude가 이전에 읽은 파일을 편집해도 기록의 이전 읽기를 소급하여 변경하지 않습니다. 대신 Claude Code는 파일이 변경되었음을 나타내는 `<system-reminder>`를 추가하고, 필요한 경우 Claude가 다시 읽습니다.

173 246 

174<h3 id="editing-claude-md-mid-session">247<h3 id="editing-claude-md-mid-session">

175 세션 중 CLAUDE.md 편집248 세션 중 CLAUDE.md 편집

176</h3>249</h3>

177 250 

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

179 252 

180[하위 디렉토리의 중첩된 CLAUDE.md 파일](/docs/ko/memory)과 [`paths:` 프론트매터가 있는 규칙](/docs/ko/memory#path-specific-rules)은 나중에 로드되며, Claude가 일치하는 파일을 처음 읽을 때 로드됩니다. 로드되기 전에 편집하면 적용됩니다. 로드된 후 콘텐츠는 대화 기록의 일부이므로 세션 중 편집은 소급하여 변경하지 않습니다.253[하위 디렉토리의 중첩된 CLAUDE.md 파일](/docs/ko/memory)과 [`paths:` 프론트매터가 있는 규칙](/docs/ko/memory#path-specific-rules)은 Claude가 일치하는 파일을 처음 읽을 때 나중에 로드됩니다. 로드되기 전에 편집하면 적용됩니다. 로드된 후에는 내용이 대화 기록의 일부이므로 세션 중 편집은 소급하여 변경하지 않습니다.

181 254 

182<h3 id="changing-output-style">255<h3 id="changing-permission-mode">

183 출력 스타일 변경256 권한 모드 변경

184</h3>257</h3>

185 258 

186[출력 스타일](/docs/ko/output-styles)은 Claude Code가 세션 시작 시 한 번 읽는 시스템 프롬프트의 일부입니다. `/config` 또는 `outputStyle` 설정을 통해 세션 중에 변경해도 캐시가 무효화되지 않지만 변경도 적용되지 않습니다. Claude는 세션 시작 시 로드된 스타일을 계속 사용합니다. 새로운 스타일은 다음 `/clear` 또는 재시작 시 로드됩니다.259[권한 모드](/docs/ko/permission-modes)를 수동에서 편집 수락으로 전환하는 것과 같이 전환해도 시스템 프롬프트나 도구 정의가 변경되지 않으므로 모드 변경은 캐시 안전합니다. 예외는 [`opusplan`](/docs/ko/model-config#opusplan-model-setting) 모델 설정이 있는 계획 모드로, 계획 모드에 들어가거나 나갈 때 모델을 Opus와 Sonnet 사이에서 전환합니다. 이는 모드 토글을 [모델 전환](#switching-models)으로 만듭니다.

187 260 

188<h3 id="changing-permission-mode">261<h3 id="changing-output-style">

189 권한 모드 변경262 출력 스타일 변경

190</h3>263</h3>

191 264 

192[권한 모드](/docs/ko/permission-modes) 간 전환(예: 기본값에서 편집 수락으로)은 시스템 프롬프트 또는 도구 정의를 변경하지 않으므로 모드 변경은 캐시 안전입니다. 예외는 [`opusplan`](/docs/ko/model-config#opusplan-model-setting) 모델 설정이 있는 Plan 모드입니다. 이는 Plan 모드에 들어가거나 나갈 때 모델을 Opus와 Sonnet 간에 전환합니다. 이는 모드 토글을 [모델 전환](#switching-models)으로 만듭니다.265세션 중 `/config` 또는 `outputStyle` 설정으로 [출력 스타일](/docs/ko/output-styles)을 전환하면, Claude는 다음 메시지부터 새로운 스타일을 사용합니다. Claude Code는 새로운 스타일의 지침을 대화의 메시지로 전달하므로, 해당 요청은 여전히 시스템 프롬프트와 이전 대화를 캐시에서 읽습니다.

266 

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

193 268 

194<h3 id="invoking-skills-and-commands">269<h3 id="invoking-skills-and-commands">

195 스킬 및 명령 호출270 스킬 및 명령 호출

196</h3>271</h3>

197 272 

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

199 274 

200<h3 id="running-/recap">275<h3 id="running-/recap">

201 `/recap` 실행276 `/recap` 실행

202</h3>277</h3>

203 278 

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

205 280 

206<h3 id="rewinding-the-conversation">281<h3 id="rewinding-the-conversation">

207 대화 되감기282 대화 되감기

208</h3>283</h3>

209 284 

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

286 

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

288 

289<h2 id="resuming-a-session">

290 세션 재개

291</h2>

292 

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

211 294 

212대화와 함께 파일 체크포인트를 복원해도 캐시에 별도의 영향을 주지 않습니다. 파일 콘텐츠는 [저장소의 파일 편집](#editing-files-in-your-repository)과 동일하게 Claude가 읽을 때만 컨텍스트에 들어갑니다.295시스템 프롬프트는 [Claude Code 업그레이드](#upgrading-claude-code) 후 또는 재개 시 다른 [`--append-system-prompt`](/docs/ko/cli-reference#system-prompt-flags) 텍스트로 변경될 수 있습니다. 기본적으로 재개된 대화는 시작할 때의 시스템 프롬프트를 유지하므로 해당 히스토리는 여전히 동일한 프롬프트 뒤에 있으며, 변경 사항은 대화가 압축되거나 새 대화에서 적용됩니다. [재개된 대화의 시스템 프롬프트 플래그](/docs/ko/cli-reference#system-prompt-flags-in-resumed-conversations)는 `--system-prompt-snapshot off`와 베어 모드를 다루며, 이 경우에는 적용되지 않습니다.

213 296 

214<h2 id="cache-lifetime">297<h2 id="cache-lifetime">

215 캐시 수명298 캐시 수명

216</h2>299</h2>

217 300 

218캐시된 프리픽스는 비활성 기간 후에 만료됩니다. 캐시에 히트하는 각 요청은 타이머를 재설정하므로 계속 작업하는 한 캐시는 따뜻하게 유지됩니다. 충분히 긴 간격 후에 다음 요청은 전체 입력을 다시 계산하고 캐시를 다시 설정합니다. 이것이 한동안 떨어진 후 돌아오는 첫 턴이 눈에 띄게 느릴 수 있는 이유입니다.301캐시된 접두사는 비활성 기간 후에 만료됩니다. 캐시에 도달하는 각 요청은 타이머를 재설정하므로 계속 작업하는 한 캐시는 따뜻한 상태로 유지됩니다. 충분히 긴 간격 후에는 다음 요청이 전체 입력을 다시 계산하고 캐시를 다시 설정하므로, 한동안 떠난 후 돌아온 첫 번째 턴이 눈에 띄게 느릴 수 있습니다.

302 

303Pro 또는 Max 플랜에서 긴 휴식 후 대규모 세션을 재개할 때 Claude Code는 [요약에서 재개할 수 있도록 제안](/docs/ko/sessions#resume-from-a-summary)하므로 이후 요청이 전체 기록을 전달하지 않습니다.

219 304 

220TTL(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을 선택하며, 환경 변수로 재정의할 수 있습니다.305TTL(Time to Live)은 캐시가 유지되는 간격의 길이를 제어합니다. API는 두 가지를 제공합니다: 5분 TTL과 [1시간 TTL](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration)로, 더 긴 휴식 시간 동안 캐시를 따뜻하게 유지하지만 [캐시 쓰기를 더 높은 요금으로 청구합니다](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing). 더 긴 TTL은 세션을 유휴 상태로 두었다가 돌아올 때 도움이 됩니다. 만료된 접두사가 비용이 드는 재처리를 건너뛸 수 있기 때문입니다. 5분을 초과하여 유휴 상태가 되지 않는 짧은 작업 버스트에서는 더 비용이 많이 듭니다. 여기서 더 높은 쓰기 요금이 적용되고 더 긴 캐시 수명이 사용되지 않습니다.

221 306 

222<h3 id="on-a-claude-subscription">307<h3 id="which-ttl-each-request-gets">

223 Claude 구독에서308 각 요청이 받는 TTL

224</h3>309</h3>

225 310 

226Claude 구독에서 Claude Code는 자동으로 1시간 TTL을 요청합니다. 사용량은 토큰당 청구되지 않고 계획에 포함되므로 더 긴 TTL은 추가 비용이 없으며 캐시가 따뜻하게 유지되는 기간에만 영향을 줍니다.311Claude Code는 요청별로 TTL을 결정하며, 모든 요청은 두 가지 고정 버킷 중 하나에 해당합니다:

227 312 

228계획의 사용량 한도를 초과했고 Claude Code가 [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)을 사용 중인 경우 해당 사용량에 대해 청구되므로 Claude Code는 자동으로 TTL을 5분으로 낮춥니다.313* **메인 대화**: 대화형 턴, 비대화형 `-p` 실행, Agent SDK 턴, 그리고 Claude Code가 이들과 함께 인라인으로 실행하는 도우미

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

229 315 

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

231 API 키 또는 타사 제공자에서

232</h3>

233 317 

234API 키, Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 AWS의 Claude Platform에서 토큰당 요금을 지불하므로 TTL은 기본적으로 더 저렴한 5분으로 유지됩니다. [1시간 TTL](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration)을 선택하려면 `ENABLE_PROMPT_CACHING_1H=1`을 설정합니다.318| 요청 버킷 | Claude 구독, 플랜 사용량 범위 내 | 사용 크레딧, API 키 또는 클라우드 제공자 |

319| ------- | --------------------------- | ------------------------- |

320| 메인 대화 | 1시간 | 5분 |

321| 기타 모든 것 | 5분, 서버 제어 도우미 요청 제외(1시간 받음) | 5분 |

235 322 

236Amazon Bedrock에서 프롬프트 캐싱 지원, 최소 캐시 가능 프리픽스 길이 및 1시간 TTL 가용성은 모두 모델에 따라 다릅니다. 캐시 토큰 수가 0으로 유지되면 Amazon Bedrock 설명서에서 [지원되는 모델, 지역 및 제한](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)을 확인하세요.323플랜의 사용량 한도를 초과하고 Claude Code가 [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)을 사용하기 시작하면 해당 사용량에 대해 청구되므로 Claude Code는 메인 대화를 더 저렴한 5분 TTL로 낮춥니다. 메인 대화에서 1시간 TTL을 유지하려면 [TTL을 직접 선택하세요](#choose-the-ttl-yourself).

237 324 

238<h3 id="override-the-ttl">325<h3 id="choose-the-ttl-yourself">

239 TTL 재정의326 TTL을 직접 선택하세요

240</h3>327</h3>

241 328 

242`FORCE_PROMPT_CACHING_5M=1`을 설정하여 인증에 관계없이 5분 TTL을 강제합니다. 이는 캐시 동작을 디버깅하거나, 두 TTL을 비교하거나, [관리 설정](/docs/ko/settings#settings-files)에 설정된 `ENABLE_PROMPT_CACHING_1H`을 재정의할 때 유용합니다.329각 버킷에 대해 TTL을 설정할 수 있습니다. 각 제어는 `5m` 또는 `1h`를 사용하며, Claude Code는 다른 값을 무시합니다.

330 

331* **메인 대화**: [`promptCacheTtl`](/docs/ko/settings-reference#promptcachettl) 설정 또는 `CLAUDE_CODE_PROMPT_CACHE_TTL` [환경 변수](/docs/ko/env-vars)

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

333 

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

335 

336둘 이상의 제어가 적용되면 Claude Code는 다음 순서에서 첫 번째 일치를 사용합니다:

337 

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

3392. 버킷의 환경 변수

3403. 버킷의 설정

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

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

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

344 

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

346 

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

348 

349`ANTHROPIC_BASE_URL`로 설정한 LLM 게이트웨이를 통해 1시간 요청의 일부가 `anthropic-beta` 헤더에서 이동하므로 게이트웨이를 구성하여 [해당 헤더를 변경하지 않고 전달하세요](/docs/ko/llm-gateway-protocol#request-headers). 1시간 TTL은 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway#availability-and-limitations)를 통해 사용할 수 없습니다. Amazon Bedrock에서 프롬프트 캐싱 지원, 최소 캐시 가능 접두사 길이, 1시간 TTL 가용성은 모두 모델에 따라 다릅니다. 캐시 토큰 수가 0으로 유지되면 Amazon Bedrock 설명서에서 [지원되는 모델, 지역 및 제한](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)을 확인하세요.

243 350 

244<h2 id="cache-scope">351<h2 id="cache-scope">

245 캐시 범위352 캐시 범위

246</h2>353</h2>

247 354 

248Claude Code에서 캐시는 효과적으로 한 대의 머신과 디렉토리로 범위가 지정됩니다. 시스템 프롬프트는 작업 디렉토리, 플랫폼, 셸, OS 버전 및 자동 메모리 경로를 포함하므로 다른 디렉토리의 두 세션은 다른 프리픽스를 구축하고 서로의 캐시를 놓칩니다. 여기에는 동일한 저장소의 worktree가 포함됩니다. 각 worktree는 자체 작업 디렉토리를 가지기 때문입니다.355Claude Code에서 캐시는 효과적으로 하나의 머신과 디렉토리로 범위가 지정됩니다. 각 대화는 작업 디렉토리, 플랫폼, 셸 및 OS 버전을 포함하며, 시스템 프롬프트는 자동 메모리 경로의 이름을 지정하므로 서로 다른 디렉토리의 두 세션은 서로 다른 접두사를 구축하고 서로의 캐시를 놓칩니다. 여기에는 각 worktree가 자신의 작업 디렉토리를 가지고 있으므로 동일한 저장소의 worktrees도 포함됩니다.

249 356 

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

251 358 

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

253 360 

254<h2 id="check-cache-performance">361<h2 id="check-cache-performance">

255 캐시 성능 확인362 캐시 성능 확인

256</h2>363</h2>

257 364 

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

259 366 

260| 필드 | 의미 |367| 필드 | 의미 |

261| ----------------------------- | --------------------------------------- |368| ----------------------------- | --------------------------------------- |

262| `cache_creation_input_tokens` | 이 턴에서 캐시에 기록된 토큰, 캐시 쓰기 속도로 청구됨 |369| `cache_creation_input_tokens` | 이번 턴에 캐시에 기록된 토큰, 캐시 쓰기 요금으로 청구됨 |

263| `cache_read_input_tokens` | 이 턴에서 캐시에서 제공된 토큰, 표준 입력 속도의 약 10%로 청구됨 |370| `cache_read_input_tokens` | 이번 턴에 캐시에서 제공된 토큰, 표준 입력 요금의 약 10%로 청구됨 |

371 

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

264 373 

265높은 읽기 대 생성 비율은 캐싱이 잘 작동하고 있음을 의미합니다. 생성이 턴마다 높게 유지되면 프리픽스에서 뭔가 변경되고 있습니다. [캐시를 무효화하는 작업](#actions-that-invalidate-the-cache) 섹션에서 일반적인 원인을 나열합니다.374세션별 요약을 보려면 `/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 이상이 필요합니다.

266 375 

267조직 전체의 가시성을 위해 OpenTelemetry 내보내기는 사용자 및 세션당 캐시 읽기 및 생성 토큰을 보고합니다. 메트릭 및 이벤트 속성 참조는 [사용량 모니터링](/docs/ko/monitoring-usage)을 참조하세요.376`Prompt cache (main)` 라인은 Claude Code가 식별할 수 있을 때 마지막 미스의 가능한 원인을 이름으로 표시합니다. 예를 들어 `likely cause: tool definitions changed`입니다. 가능한 원인 텍스트는 Claude Code v2.1.260 이상이 필요합니다.

377 

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

268 379 

269<h2 id="subagents-and-the-cache">380<h2 id="subagents-and-the-cache">

270 서브에이전트 및 캐시381 서브에이전트와 캐시

271</h2>382</h2>

272 383 

273[서브에이전트](/docs/ko/sub-agents)는 부모와 별개의 자체 대화를 시작하며, 자체 시스템 프롬프트 및 도구 집합을 가집니다. 자체 캐시를 구축하며, 첫 호출 시 캐시 히트가 없고 자체 턴에 걸쳐 따뜻해집니다. 서브에이전트는 자동 1시간 TTL이 주 대화에 적용되더라도 5분 TTL을 사용합니다.384[서브에이전트](/docs/ko/sub-agents)는 부모와 별도의 자체 시스템 프롬프트와 도구 세트로 자체 대화를 시작합니다. 첫 번째 요청은 두 접두사가 다르기 때문에 부모의 캐시를 읽지 않으며, 자신의 턴에 걸쳐 자체 캐시를 워밍합니다. 서브에이전트는 메인 대화 [TTL 버킷](#which-ttl-each-request-gets) 외부에 있으므로, [더 긴 것을 선택](#choose-the-ttl-yourself)할 때까지 구독 상태에서도 5분을 얻습니다.

385 

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

387 

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

274 389 

275부모의 캐시는 영향을 받지 않습니다. 부모 측에서 서브에이전트의 호출 및 결과는 대화에 추가되어 부모의 프리픽스를 그대로 유지합니다.390다른 요청도 이전 요청이 캐시한 접두사를 읽을 수 있습니다:

276 391 

277[포크](/docs/ko/sub-agents#fork-the-current-conversation)는 대조적으로 부모의 시스템 프롬프트, 도구 및 대화 기록을 정확히 상속하므로 첫 요청은 부모의 캐시를 읽습니다. [대화 압축](#compacting-the-conversation)에서 설명한 압축 요약 호출은 동일한 프리픽스 공유 접근 방식을 사용합니다.392* **세션 복사본**: [`/fork`로 복사](/docs/ko/agent-view#copy-the-session-with-%2Ffork)한 세션은 복사된 대화의 끝에 메시지로 격리 지침을 받으므로, 원본 대화가 구축한 캐시가 그대로 유지됩니다.

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

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

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

278 396 

279<h2 id="disable-prompt-caching">397<h2 id="disable-prompt-caching">

280 프롬프트 캐싱 비활성화398 prompt caching 비활성화

281</h2>399</h2>

282 400 

283캐싱을 비활성화하는 것은 특정 모델 또는 제공자로 캐싱 동작을 디버깅할 때 가끔 유용합니다. 끄려면 다음 환경 변수 중 하나를 `1`로 설정합니다:401특정 모델이나 공급자와의 caching 동작을 디버깅할 때 caching을 비활성화하는 것이 유용할 수 있습니다. 이를 끄려면 다음 환경 변수 중 하나를 `1`로 설정합니다:

284 402 

285| 변수 | 효과 |403| 변수 | 효과 |

286| ------------------------------- | -------------- |404| ------------------------------- | -------------- |

290| `DISABLE_PROMPT_CACHING_OPUS` | Opus만 비활성화 |408| `DISABLE_PROMPT_CACHING_OPUS` | Opus만 비활성화 |

291| `DISABLE_PROMPT_CACHING_FABLE` | Fable만 비활성화 |409| `DISABLE_PROMPT_CACHING_FABLE` | Fable만 비활성화 |

292 410 

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

294 412 

295<h2 id="related-resources">413<h2 id="related-resources">

296 관련 리소스414 관련 리소스