1. 캐시 구성 요소

Prefix (text 기반)

레이어 내용
System Prompt Layer 기본 도구(core tools) + 기본 system 지침
Project Context Layer CLAUDE.md 등 세션 고정 설정 파일
Conversation Layer 지금까지 누적된 대화 내역 (Message, Reply)

Header (Request metadata)

  • Model
  • Effort level
  • Fast mode

Appended requests

Skills · Commands · Agents · Hooks · LSP server · Monitors · Themes · Deferred tools · advisor tool

Cache-Hit 조건

  • 캐시가 Hit되면 모델에 전체 텍스트를 Compute해서 넣을 필요가 없음
  • Cache Key(Prefix + Header) 가 바뀌면 → 다시 Compute해서 넣어야 함

**Tip

  • 세션 시작 시 Model과 Effort를 먼저 선택하고, 작업 중간에는 가급적 변경을 피할 것.
  • 자연스러운 휴식 타이밍에 /compact로 관리하면 캐시 히트 확률이 올라감!

캐시가 있는 위치

캐싱은 서버 측에서 발생하며, Model을 제공하는 인프라에 위치함.

사용 환경 캐시 위치
API, OAuth, Claude Platform on AWS Anthropic Infra (Claude API를 통해 액세스)
Amazon Bedrock, GCP Agent Platform 클라우드 제공자의 Infra
Microsoft Foundry Anthropic 인프라로 요청이 라우팅됨
사용자 정의 ANTHROPIC_BASE_URL / LLM gateway 요청이 전달되는 위치. 작동 여부는 gateway에 따라 다름

2. 캐시를 무효화하는 작업 — "Cache Key가 바뀔 때"

① 모델 전환

각 모델은 자체 캐시를 가지므로, 세션 도중 model을 전환하면 다음 요청에서 전체 context를 다시 읽어야 함.

  • opusplan, Fable 자동 모델 fallback 도 모델 전환에 해당 → 캐시 없이 re-run하고 동일 세션 내에서 작업 진행

② Effort level 변경

동일한 모델이어도 각 effort마다 자체 캐시를 가지므로, effort 수준이 바뀌면 re-run됨.

  • 단, 각 모델마다 default effort가 있어서 default와 똑같은 effort로 변경하면 무효화 없이 캐시 유지

③ Fast Mode 켜기

Request Header가 추가되므로, 다음 요청이 Cache-hit 없이 전체 context를 읽음.

  • 캐싱 안 된 input token은 fast mode rates로 청구 → 세션 시작 시 켜는 것이 중간에 켜는 것보다 저렴
  • Fast mode는 Opus model에서만 지원
  • 다른 모델에서 활성화하려 하면 Claude Code가 자동으로 Opus로 전환 → 새 캐시가 시작됨

④ disconnect된 MCP Server 연결

MCP도 tool이므로 System Prompt Layer에 속함. 중간에 tool 정의 집합이 변경되면 캐시가 무효화될 수 있음.

1) 일반적인 경우 (Deferred tools, 기본값)

  • Tool Search 활성화 상태
  • Tool이 백그라운드 영역에 있어 search해서 꺼내 쓰는 방식
  • 서버 연결/해제, 도구 목록 변경 → 새 내용만 추가되고 기존 캐시는 유지됨

 

2) Prefix-loaded tools

  • Tool Search 비활성화 상태
    • GC Agent Platform
    • Custom Gateway (Custom ANTHROPIC_BASE_URL)
    • alwaysLoad로 표시된 서버/도구
  • Prefix에 tool이 다 적혀 있으므로 tool이 바뀌면 Prefix가 깨짐 → 캐시 무효화

 

3) advisor 도구

  • Cache breakpoint 이후에 있으므로, (비)활성화해도 캐시 유지

⑤ Plugin (비)활성화

플러그인 변경은 /reload-plugins 실행 또는 새 세션 시작 시점에 적용됨.
→ 따라서 중간에 /plugin install, /plugin enable, /plugin disable을 해도 캐시는 바뀌지 않음.

/reload-plugins로 전체 context를 다시 읽어야 하는 경우의 동작:

  1. 경고 메시지 발생 (비용이 많이 들 거라는 경고)
  2. 자동으로 reload 적용 X (실수로 비용 낭비하지 않도록)
  3. --force flag를 붙이면 경고를 무시하고 reload 진행

=> Plugin Skill Prompt 영향으로 인한 캐시 무효화 위험 → 그래서 경고가 필요함

 

한편 Skills, commands, agents, hooks, LSP 서버, monitors, themes는 캐시를 무효화하지 않음.
(이 Request들은 기존 대화 뒤에 추가되므로, 그 이전의 모든 것은 캐시에서 읽음)

⑥ 기본 Tool을 '거부 규칙'에 추가

기본 Tool(예: Bash, WebFetch 등)은 System Prompt Layer에 있으므로, 거부 규칙에 추가하면 Context에서 완전히 제거됨 → 세션 중 캐시 무효화

  • 단, Deferred tools를 deny하면 캐시 유지 (예: mcp__*, Bash(rm *) 같은 범위 지정 거부 규칙)

⑦ Compact

메시지 기록을 요약으로 바꾸므로, 설계상 Conversation Layer를 무효화시킴
→ System Prompt Layer는 재사용하고, Project Context는 disk에서 다시 load함

 

CLAUDE.md와 Memory가 변경되지 않은 경우에만 Cache-Hit
평소에 CLAUDE.md를 편집하는 건 기존 캐시 영역에 즉각 영향을 주지 않아 캐시가 유지됨
하지만 /compact를 실행하는 순간 디스크의 최신 상태를 강제로 다시 긁어오기 때문에, 그 사이 CLAUDE.md나 Memory가 수정됐다면 캐시 무효화!

 

compaction 생성을 위해 System Prompt, Tools, History를 일회성 요청하고 요약 지침을 conversation으로 추가함
→ Prefix를 공유하므로 기존 캐시를 유지하여 읽음

 

compaction 생성 요청 자체는 요약 생성 때문에 리소스가 들지만, 그 이후부터는 짧아진 대화 기록을 바탕으로 Cache-Hit를 유지하며 효율적으로 작업 가능

 

Compact Tip

  • 더 이상 필요하지 않은 Context를 버릴 때 유리함
  • auto-compaction을 기다리지 말고, 휴식 시간에 한 번씩 /compact 실행 권장
  • Compaction이 과도했거나 Context가 유실됐다면 /rewind로 되돌릴 수 있음

⑧ Claude 업데이트

새로운 Claude Code 버전은 일반적으로 시스템 프롬프트 또는 도구 정의를 업데이트하므로 업그레이드 후 첫 번째 요청은 캐시를 처음부터 다시 구축

자동 업데이트는 백그라운드에서 새 버전을 다운로드하지만 다음 시작 시에만 적용하므로 세션 중에 놀라운 일이 아닌 재시작 후 적용됨

3. 캐시를 유지하는 작업

① repo의 file 편집

File Contents는 Read할 때만 Context에 들어가며, 이는 Conversation에 추가됨

파일이 변경됐으면, Claude Code가 자동으로 <system-reminder> 태그를 붙여 메시지를 추가하는 방식

② 세션 중 CLAUDE.md 편집

CLAUDE.md는 세션 시작 시 한 번 읽혀지고 Memory에 보관됨

세션 중에 편집해도 편집본이 적용되지 않음

/clear, /compact or 세션 재시작을 해야 변경되어 로드됨

③ 출력 스타일 변경

출력 스타일은 세션 시작 시 한 번만 읽은 System Prompt의 일부

/config 또는 outputStyle로 설정하며, CLAUDE.md와 마찬가지로 중간에 편집해도 적용되지 않음

④ 권한 모드 변경

권한 모드는 System Prompt or tool 정의를 변경하지 않으므로 캐시가 유지됨

단, opusplan 모델 설정한 Plan mode에서는 모델이 바뀌므로 캐시가 무효화됨

⑤ Skill / Command 호출

호출 지점에서 Conversation layer에 들어가므로 캐시가 유지됨

⑥ /recap 실행

  • /recap : 터미널에 표시할 요약을 생성

메시지 기록을 바꾸는 대신 요약을 명령 출력으로 추가하기 때문에 Prefix가 유지됨

⑦ /rewind 실행

  • /rewind: 대화를 이전 턴으로 되돌림

남은 기록들은 이미 Cache로 구축되어 있으므로, 캐시가 유지됨

3. 캐시 수명 (Cache Lifetime)

Cached Prefix는 비활성 기간 후 만료됨

각 요청은 Cache-Hit 타이머를 재설정하므로, 계속 작업하는 한 캐시는 유지됨

TTL(Time To Live, 캐시가 견디는 간격 길이)가 초과되면 캐시가 무효화됨

 

OAuth Subscription

자동으로 1시간 TTL 요청

한도 초과 후 Credit 사용할 시에는 자동으로 TTL이 5분으로 감소됨

API key or third-party provider

기본 5분 유지

ENABLE_PROMPT_CACHING_1H=1 옵션을 설정하여 1시간 TTL 설정 가능

Override the TTL

FORCE_PROMPT_CACHING_5M=1를 적용하면 인증 방식, 환경 설정에 관계없이 5분 TTL 강제

4. 캐시 범위

  • 머신과 디렉토리 단위 격리

System Prompt에는 작업 디렉토리, 플랫폼, 셸, OS 버전, 자동 메모리 경로 등이 포함

따라서, 디렉토리가 다르면 서로 캐시를 공유하지 못하고 각각 따로 구축함

동일 repo의 git worktree에서 디렉토리가 달라도 캐시를 공유하지 않음

 

  • 동일 디렉토리에서의 다른 섹션

병렬 세션 - Prefix가 일치하므로 서로 캐시를 읽고 공유

순차 세션 - 시작 지점의 git 상태 스냅샷이 일치할 떄만 캐시를 공유하며, 커밋 상태가 달라지면 System Prompt가 바뀌어 캐시를 공유할 수 없음

 

  • API

기본적으로 Organization 단위로 격리되며, 제공자에 따라 조직 내 workspace 단위로 격리될 수도 있음

이 경계 안에서 동일한 Model & Prefix를 가진 요청이라면 캐시를 공유

 

  • Agent SDK

다른 디렉토리 or 머신에서 에이전트를 실행하면 Prefix가 달라지는 문제점 발생

=> excludeDynamicSections: true 옵션을 활성화하면 세션 별 동적 프롬프트가 System Prompt에서 빠져 첫 번째 사용자로 이동하므로, 정적 프리셋과 append 텍스트만 남아 여러 머신이나 디렉토리 간에도 프롬프트 캐시를 공유할 수 있음

5. 캐시 성능 확인

캐시 성능은 API가 모든 응답에 보고하는 두 개의 토큰 수로 표시됨

필드 요약 의미
cache_creation_input_tokens 캐시 쓰기/생성 이번 턴에서 캐시가 기록된 토큰, 캐시 쓰기 속도로 청구됨
cache_read_input_tokens 캐시 읽기/재사용 이번 턴에서 캐시에서 제공한 토큰, 표준 입력 속도의 약 10%로 청구됨

current_usage: 라이브로 위 두 필드를 감시

=> 비용 관리할 떄 '캐시' 파트에서는 캐시 무효화를 중점으로 모니터링 및 관리하면 됨!

OpenTelemetry(OTel)

표준화된 로그, 메트릭, 추적 데이터를 수집하고 전송하기 위한 오픈소스 관찰성(Observability) 표준

=> Claude Code가 이를 지원하므로, 캐시 비용 모니터링 결과를 모니터링 서버로 보낼 수 있음

6. 서브에이전트 및 캐시

서브에이전트는 자체 캐시를 구축함

자동 한 시간 TTL이 메인 세션에 적용되더라도, 여기에서는 5분 TTL을 사용

부모의 캐시는 영향을 받지 않음

 

=> 부모의 프리픽스는 그대로 유지되며, 포크(Fork)의 경우 부모의 시스템 프롬프트, 도구, 대화 기록을 정확히 상속하므로 첫 요청에서 부모의 캐시를 그대로 읽음

Fork

부모 대화의 완벽한 복사본으로써, 부모의 Cache Key, Conversation을 그대로 물려받아 세션을 시작하는 행위

7. 프롬프트 캐싱 비활성화

  • DISABLE_PROMPT_CACHING : 모든 모델에 대해 비활성화
  • DISABLE_PROMPT_CACHING_HAIKU/SONNET/OPUS/FABLE : 특정 모델에 대해 비활성화

만약 조직 전체에 Caching 정책을 설정하려면, 위 변수 or TTL 변수를 설정 파일의 env 블록에 넣으면 됨

출처

Claude Code Docs - Prompt Caching

'Claude Code' 카테고리의 다른 글

[Claude Code] Tool 정리 - 01  (0) 2026.08.22