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

TL;DR: Claude Code는 프롬프트를 알아서 캐싱해줌. 기존 대화를 이어갈 때 이미 캐시된 앞부분은 전체 비용의 10%만 내면 됨. 기본적으로 토큰당 과금되는 Claude Code 설정은 프롬프트 캐시 TTL을 5분으로 잡음. 즉, Claude Code 세션을 이어가는 데 5분 넘게 걸리면, 매번 대화 전체에 대해 제값을 다 내야 한다는 소리임.

이제 토큰 사용량을 좀 더 신경 써야 할 때가 왔음 🙌 그래서 Claude Code의 프롬프트 프리픽스 캐싱 메커니즘을 최대한 활용하는 방법을 파고들어 봤음. 내가 알아낸 건 이거임. 관심 있으면 공식 문서도 한번 봐보셈. 아주 자세하고 잘 나와 있음

캐시 작동 방식

프롬프트 캐싱은 프리픽스 캐시(prefix cache) 방식임. 매 턴마다 API가 요청의 시작 부분(모델 + 시스템 프롬프트 + 프로젝트 컨텍스트 + 전체 대화 내역)을 최근 캐시된 내용과 대조해서, 새로 추가된 부분만 새로 처리함.

캐시 쓰기(write)는 Claude Code가 현재까지의 대화 내용을 특정 TTL(유효 시간, 5분 또는 1시간, 인증 방식이나 설정에 따라 다름) 동안 캐시하도록 저장하는 걸 말함. Claude Code 세션에서 이어지는 턴들이 그 정확한 프롬프트 "프리픽스"로 시작하면, 캐시가 사용되면서 해당 대화 부분은 엄청나게 할인된 요금으로 과금됨.

프리픽스 앞부분을 조금이라도 수정하면 캐시 미스가 발생함. 그럼 전체 내용을 다시 읽거나(혹은 다시 캐시로 저장하거나) 해서 전체 컨텍스트에 대해 다시 요금을 내야 함.

캐시된 프리픽스는 일정 시간 동안 활동이 없으면 만료되지만, 캐시 히트가 발생할 때마다 TTL이 초기화되니까 활발한 세션은 계속 캐시 상태로 유지됨.

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

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

기본 캐시 TTL은 인증 방식에 따라 다름

• Claude 구독 중이라면(예: 개인 프로/맥스 계정), 메인 대화는 추가 비용 없이 자동으로 1시간 TTL을 사용함. 사용 크레딧 한도를 초과했을 때만 5분으로 떨어짐.
• 기업용 토큰당 과금/API 키 / Bedrock / Vertex 환경에서는 기본값이 5분임. 1시간 TTL 캐시가 초기 비용이 더 비싸기 때문임.
• ENABLE_PROMPT_CACHING_1H=1 또는 FORCE_PROMPT_CACHING_5M=1로 캐시 TTL을 수동으로 덮어쓸 수 있음.
• 서브 에이전트는 구독 중이라도 항상 5분을 사용함.

비용 분석: 히트 vs 미스

캐싱이 비용에 미치는 영향을 시각화하기 위해 가상의 예시를 들어보겠음: 3,000 토큰의 기본 프롬프트가 있고, 이후 1,000 토큰씩 추가되는 대화 5라운드 진행.

계산:

• 캐시 히트 시: 누적된 컨텍스트에 대해 10% 읽기 요금을 내고, 새로 추가된 1,000 토큰에 대해서만 쓰기 프리미엄(5분은 1.25배, 1시간은 2배)을 냄.
• 캐시 미스 시: 제한 시간이 만료됨. 컨텍스트를 처음부터 다시 캐싱하기 위해 쓰기 프리미엄을 다 내야 함.