Claude Code에서 프롬프트 캐싱 작동 방식 (그리고 토큰 낭비 막는 방법)

요약: Claude Code는 사용자의 프롬프트를 진행하면서 캐시합니다. 기존 대화를 이어갈 때, 이미 캐시된 이전 부분의 프롬프트는 전체 비용의 10%만 청구됩니다. 기본적으로, 토큰당 과금 방식인 Claude Code는 프롬프트 캐시 TTL(Time To Live)을 5분으로 설정합니다. 이는 Claude Code 세션을 5분 이상 지속할 경우, 매 턴마다 전체 대화에 대해 정가를 지불하게 된다는 의미입니다.
토큰 사용에 더 신경 써야 할 때가 왔습니다 🙌 그래서 저는 Claude Code의 프롬프트 접두사 캐싱 메커니즘을 가장 잘 활용하는 방법을 알아보기 위해 깊이 파고들었습니다. 제가 알아낸 내용은 다음과 같습니다. 관심 있으시면, 전체 공식 문서는 여기 있으며 매우 훌륭하고 상세합니다
캐시 작동 방식
프롬프트 캐싱은 *접두사 캐시(prefix cache)*입니다. 매 턴마다 API는 요청의 시작 부분(모델 + 시스템 프롬프트 + 프로젝트 컨텍스트 + 전체 대화 기록)을 최근에 캐시된 내용과 일치시키고, 새로 추가된 대화 부분만 새로운 작업으로 간주합니다.
캐시 쓰기(cache write)는 Claude Code가 현재까지의 대화를 특정 TTL(Time To Live, 생존 시간) 동안 캐시하도록 커밋하는 것입니다: 인증 유형이나 구성에 따라 5분 또는 1시간입니다. 만약 Claude Code 세션에서 이어지는 턴들이 그 정확한 프롬프트

캐시 가격 (기본 입력 가격 대비)

캐시 읽기 (Cache read) = ~0.1x (10%)
캐시 쓰기 (Cache write) (5분 TTL) = 1.25x
캐시 쓰기 (Cache write) (1시간 TTL) = 2x

기본 캐시 TTL은 인증 방식에 따라 달라집니다.

Claude 구독 (예: 개인용 Pro/Max 계정)의 경우, 주요 대화는 추가 비용 없이 1시간 TTL을 자동으로 사용합니다. 사용 크레딧이 플랜 한도를 초과하는 경우에만 5분으로 떨어집니다.
토큰당 과금되는 엔터프라이즈 (Enterprise billed-per-token), API 키, Bedrock, Vertex 설정의 경우, 1시간 TTL 캐시의 초기 비용이 더 높기 때문에 기본값은 5분입니다.
ENABLE_PROMPT_CACHING_1H=1 또는 FORCE_PROMPT_CACHING_5M=1을 사용하여 캐시 TTL을 수동으로 재설정할 수 있습니다.
서브에이전트 (Subagents)는 구독 중이더라도 항상 5분을 사용합니다.

비용 분석: 캐시 히트 (Hits) vs. 미스 (Misses)
캐싱의 비용 영향을 시각화하기 위해 가상의 예시를 들어보겠습니다: 3,000 토큰의 기본 프롬프트가 있고, 이어서 각 1,000 토큰씩 추가되는 5회의 대화 라운드가 진행되는 경우입니다.
계산 방식:

캐시 히트 (Cache hit) 시: 누적된 컨텍스트에 대해 10%의 읽기 요율을 지불하며, 오직 새로운 1,000 토큰에 대해서만 쓰기 프리미엄 (5분은 1.25x, 1시간은 2x)을 지불합니다.
캐시 미스 (Cache miss) 시: 윈도우(Window)가 만료되었습니다. 처음부터 전체 컨텍스트를 다시 캐싱하기 위해 쓰기 프리미엄을 지불해야 합니다.

캐싱을 하지 않은 기준점과 비교한 5라운드 세션 전체의 총 토큰 비용은 다음과 같습니다:

시나리오	총 비용	결과
캐시 없음 (No Cache)	30.0 유닛	캐싱을 전혀 하지 않았을 때의 가상 기준 비용.
5분 TTL — 모두 히트 (All Hits)	12.2 유닛	가장 저렴함 (~60% 절감).
1시간 TTL — 모두 히트 (All Hits)	18.2 유닛	양호 (~40% 절감).
5분 TTL — 모두 미스 (All Misses)	37.5 유닛	캐시를 사용하지 않는 것보다 나쁨.
1시간 TTL — 모두 미스 (All Misses)	60.0 유닛	가장 비쌈 (기본 요율의 2배).

시사점 및 팁

가장 비용 효율적인 워크플로우는 장시간 실행되는 작업과 세션의 경우 항상 5분 윈도우를 맞추는 것입니다. 일관성을 유지하기 어려운 경우(회의, 컨텍스트 스위칭, 멀티태스킹 등)에는 1시간 TTL로 전환하는 것을 고려하되, 반드시 해당 캐시 윈도우를 활용해야 합니다. 그렇지 않으면 결과적으로 더 많은 비용을 지불하게 됩니다.

이로 인해 멀티태스킹을 하는 경우, 5분 TTL (Time To Live) 내에 이러한 캐시를 효과적으로 활용하기가 상당히 어려울 수 있다는 생각이 듭니다.

만약 휴식을 취할 계획이지만 나중에 세션을 계속 이어가고 싶다면, 다음 중 하나를 고려해 보세요:

1. 휴식을 취하기 전, 캐시가 아직 활성화(warm)되어 있는 동안 /compact 명령어를 실행합니다.
2. Claude에게 세션을