컨텍스트 엔지니어링 실패모드 위키

Claude Code — 프롬프트 캐싱과 비용 레버

8 min read

상위: 08_00_MOC

Claude Code — 프롬프트 캐싱과 비용 레버

프롬프트 캐싱의 원리

Claude Code는 매 턴마다 전체 컨텍스트를 API에 재전송한다. 프롬프트 캐싱은 이 중 변경되지 않은 prefix 부분을 서버에 캐시해 재처리 비용을 절감한다.

“Without caching, the API would reprocess your full history on every turn. With caching, it reuses what it already processed and only does new work for what changed.” — How Claude Code uses prompt caching, Anthropic

캐시는 prefix 매칭으로 작동한다. prefix 어디에서든 변경이 생기면 그 뒤의 모든 내용이 다시 처리된다. 파일별·세그먼트별 캐싱은 없다.

3개 캐시 레이어

레이어내용변경 시점
시스템 프롬프트핵심 지시, 도구 정의, output style로드된 도구 정의 세트 변경, Claude Code 업그레이드
프로젝트 컨텍스트CLAUDE.md, auto memory, unscoped rules세션 시작, /clear·/compact 후
대화사용자 메시지, Claude 응답, 도구 결과매 턴

시스템 프롬프트 레이어가 바뀌면 그 아래 모든 레이어가 다시 처리된다. 반대로 대화 레이어만 바뀌면 시스템 프롬프트와 프로젝트 컨텍스트는 캐시가 그대로 유지된다.

캐시 무효화 트리거

아래 동작은 다음 요청에서 캐시 미스(cache miss)를 일으킨다.

트리거영향 레이어
모델 전환 (/model)전체 (모델별 독립 캐시)
effort 레벨 변경 (/effort)전체
fast mode 활성화전체 (첫 활성화만; 이후 토글·속도 조절은 유지)
MCP 서버 연결/해제시스템 프롬프트 (deferred 도구는 유지)
플러그인 활성화/비활성화 (MCP 포함 시)시스템 프롬프트
전체 도구 거부 규칙 추가/제거시스템 프롬프트
/compact대화 레이어 (시스템·프로젝트는 재로드)
Claude Code 업그레이드전체 (시스템 프롬프트·도구 정의 변경)

캐시를 유지하는 동작

다음 동작은 캐시 prefix를 그대로 유지한다.

동작이유
저장소 파일 편집파일 내용은 Claude가 읽을 때 대화에 추가됨
CLAUDE.md 세션 중 편집이미 로드된 버전이 메모리에 유지됨
output style 변경시스템 프롬프트는 세션 시작 시 1회만 읽음
권한 모드 전환프롬프트 텍스트 변경 없음
Skills·Commands 호출대화 끝에 추가됨
/recap요약을 커맨드 출력으로 추가 (히스토리 대체 아님)
/rewind기존 캐시 prefix 재활용 (가장 경제적)
서브에이전트 스폰부모 캐시 prefix 유지 (서브에이전트는 자체 캐시 구축)

CLAUDE.md 편집의 중요한 함정:

“Editing CLAUDE.md mid-session does not invalidate the cache, but the edit also doesn’t apply. Claude keeps working with the version that was loaded at session start. The new content loads on the next /clear, /compact, or restart.” — How Claude Code uses prompt caching, Anthropic

TTL (Time-To-Live)

인증 방식기본 TTL옵션
Claude 구독 (Pro/Max/Team)1시간 (자동)FORCE_PROMPT_CACHING_5M=1으로 강제 5분
API 키 / Bedrock / Vertex5분ENABLE_PROMPT_CACHING_1H=1으로 1시간

“On a Claude subscription, Claude Code requests the one-hour TTL automatically. Usage is included in your plan rather than billed per token, so the longer TTL costs you nothing extra.” — 동일 문서

구독 사용량 한도를 넘겨 usage credits로 넘어가면 TTL도 자동으로 5분으로 바뀐다.

비용 기준점

“Across enterprise deployments, the average cost is around $13 per developer per active day and $150-250 per developer per month, with costs remaining below $30 per active day for 90% of users.” — Manage costs effectively, Anthropic

캐시 성능 지표 (API 응답에 포함):

필드의미
cache_creation_input_tokens캐시에 새로 쓴 토큰 (캐시 쓰기 요금)
cache_read_input_tokens캐시에서 읽은 토큰 (표준 입력의 ~10% 요금)

read 대 creation 비율이 높을수록 캐싱이 잘 듣고 있다는 뜻이다. 반대로 creation이 계속 높게 나온다면 prefix가 매 턴 바뀌고 있다는 신호다.

Extended Thinking 비용

“Extended thinking is enabled by default because it significantly improves performance on complex planning and reasoning tasks. Thinking tokens are billed as output tokens, and the default budget can be tens of thousands of tokens per request.” — Manage costs effectively, Anthropic

비용 절감 방법:

  • /effort 레벨을 낮춤 (adaptive-reasoning 모델은 effort level만 유효)
  • /config에서 thinking 비활성화
  • 고정 thinking 예산 모델: MAX_THINKING_TOKENS=8000 환경변수
  • Fable 5는 extended thinking 항상 활성화 — 비활성화 불가

캐시 범위 이해

캐시는 사실상 한 머신·한 디렉토리 범위로 묶인다.

  • 시스템 프롬프트에 CWD·플랫폼·셸·OS·auto-memory 경로가 박혀 있다.
  • 다른 디렉토리에서 실행하면 prefix가 달라져 캐시 미스가 난다.
  • 같은 레포의 worktree도 CWD가 다르므로 캐시를 공유하지 못한다.
  • 같은 디렉토리에서 돌리는 병렬 세션은 prefix를 공유하므로 캐시도 함께 쓴다.

Agent SDK로 여러 머신을 다룰 때는 시스템 프롬프트의 머신별 섹션을 억제하면 머신끼리 캐시를 공유할 수 있다.

실무 전략

1. 긴 세션 시작 전 모델·effort 확정
   (세션 중 변경 = 전체 캐시 무효화 + 비용 급증)

2. 작업 전환 시점에 수동 /compact
   (자동 컴팩션이 작업 중간에 터지는 것 방지)

3. /rewind > /compact
   (잘못된 방향으로 갔을 때: /rewind는 기존 캐시 재활용)

4. CLAUDE.md 고쳤으면 /compact 또는 재시작
   (편집만으로는 적용 안 됨)

5. MCP 서버는 세션 시작 전에 설정
   (세션 중 연결/해제 = 캐시 무효화)

참고문헌

관련 노트

그래프 뷰

백링크