Claude Code에서 캐시 미스나 높은 token 비용을 보면 먼저 별도의 "미스 수수료"를 찾기 쉽습니다. 하지만 대부분의 경우 의미는 더 단순합니다. 재사용되어야 할 prefix가 저렴한 cache read로 처리되지 않았고, 입력이 다시 처리되었거나 cache creation으로 다시 쓰였다는 뜻입니다. 모델이 생성한 output tokens는 입력 캐시와 별도로 계속 비용에 포함됩니다.
2026년 5월 24일 기준 Anthropic 공개 가격에서 흔히 보이는 12.5x 표현은 수식으로 설명됩니다. 5분 cache write는 기본 input 가격의 1.25배이고, cache read는 같은 token 양에 대해 0.1배입니다. 1.25 / 0.1 = 12.5입니다. 이 숫자는 write와 read의 비교이지, Claude Code가 공식적으로 붙인 cache miss 추가 요금이 아닙니다.
따라서 먼저 확인할 것은 경로입니다. 이 숫자가 Claude 구독 사용량인지, API key 청구인지, Agent SDK 추정치인지, Bedrock, Vertex, Foundry, gateway 기록인지 구분해야 합니다. 그다음 cache_creation_input_tokens, cache_read_input_tokens, 모델, MCP 변경, /compact, Claude Code 버전, 시간대, 해당 경로의 청구 화면을 맞춰 봅니다. 이 순서를 건너뛰면 정상적인 캐시 무효화를 버그로 오해하기 쉽습니다.
빠른 판단: 캐시를 고치기 전에 경로를 증명한다
| 질문 | 짧은 답 | 필요한 증거 |
|---|---|---|
| 캐시 미스는 별도 요금인가? | 아니다. prefix가 저렴하게 읽히지 않고 다시 처리되거나 쓰인 상태다. | 같은 경로의 cache creation/read 필드. |
| 왜 12.5x라고 하나? | 5분 write 1.25x를 read 0.1x로 나누면 같은 token 양에서 12.5가 된다. | Anthropic 가격표와 usage fields. |
| 가장 먼저 볼 것은? | 경로 소유자다. 구독, API key, SDK, cloud provider, gateway를 섞지 않는다. | /status, /cost, Claude Console, Usage and Cost API, provider invoice. |
| 언제 의심할 만한가? | 비슷한 turn에서 high creation과 low read가 반복되고 model, MCP, route, 시간 간격이 안정적일 때다. | 인접 turn 비교, MCP 목록, version, timestamp, usage field. |
| 먼저 하지 말아야 할 것 | 원인 없이 /compact, provider 변경, 버그 단정을 하지 않는다. | prefix를 바꾼 행동을 먼저 찾는다. |
현재 경로 자체가 헷갈린다면 Claude Code API key vs subscription billing을 먼저 확인하는 편이 낫습니다. MCP 정의가 너무 많거나 tool context가 커져서 모든 요청이 무거운 문제라면 Claude Code MCP context overload가 더 넓은 원인입니다. 캐시 미스는 입력 재사용의 실패를 설명하지만, 구독 한도나 provider 청구 문제 전체를 대신 설명하지 않습니다.
12.5x는 write/read 수학이다
Claude API pricing은 일반 input, cache write, cache read, output을 나눠 표시합니다. 현재 공개된 구조에서 5분 cache write는 기본 input 가격의 1.25배, 1시간 cache write는 2배, cache read는 0.1배입니다.
text5-minute cache write / cache read = 1.25 / 0.1 = 12.5 1-hour cache write / cache read = 2.0 / 0.1 = 20
이 수식은 같은 prefix token 양을 비교할 때 유용합니다. 이전에는 read였는데 이번에는 write가 되었거나, 읽힐 것으로 기대한 prefix가 creation 쪽으로 잡혔다는 뜻입니다. 새 세션, 모델 변경, MCP server 연결이나 해제, 긴 idle, Claude Code 업데이트, /compact 직후에는 새 write가 한 번 생겨도 정상일 수 있습니다.
비용 차이는 prefix가 클수록 커집니다. 긴 대화 기록, 프로젝트 context, tool result, MCP server definitions, subagent context, file pack, 큰 system prompt가 앞쪽에 있으면 read가 실패한 한 turn이 크게 보일 수 있습니다. 작은 miss는 노이즈일 수 있지만, 큰 cache creation이 비슷한 turn마다 반복되면 진단해야 합니다.
토큰 분류표: total만 보면 원인을 놓친다
비싼 turn을 total tokens만 보고 판단하지 마십시오. total은 규모를 말하지만 원인은 말하지 않습니다. token class별로 나눠야 합니다.
| 항목 | 의미 | 사용 방법 |
|---|---|---|
| 일반 input tokens | 캐시에서 읽히지 않고 모델이 직접 처리한 입력. | 캐시가 없거나 일부만 일치한 경우의 기준 비용. |
cache_creation_input_tokens | prompt cache에 쓰였거나 creation 쪽에서 처리된 token. | 한 번의 예상 write는 정상일 수 있고, 반복되는 high creation이 중요하다. |
cache_read_input_tokens | 기존 cache entry에서 읽힌 token. | read가 creation보다 높으면 보통 재사용이 작동한다. |
| output tokens | 모델이 생성한 답변. | 입력 캐시 절감이 output을 무료로 만들지는 않는다. |
| subscription usage | plan, seat, limit window, reset 관련 사용량. | API invoice와 직접 비교하지 않는다. |
/cost 및 SDK cost fields | 로컬 또는 클라이언트 추정치. | 추세 확인에는 좋지만 공식 청구 증거보다 약하다. |
| Console, Usage and Cost API, provider invoice | 각 경로의 권위 있는 청구 화면. | 최종 금액 확인과 support packet에 사용한다. |
Agent SDK cost tracking은 total_cost_usd, costUSD 같은 값을 estimate로 다룹니다. 추정치는 runaway session을 잡고 비슷한 turn을 비교하는 데 유용하지만, 실제 비용 결론은 Claude Console, Usage and Cost API, provider invoice, 또는 해당 구독 사용량 화면에서 확인해야 합니다.
경로가 불분명하면 먼저 최소 확인부터 합니다.
bashclaude /status /cost
/status는 현재 계정 또는 route를 확인하는 데 쓰고, /cost는 API 스타일 비용 모니터링에 도움이 됩니다. 최종 청구 증거는 실행을 만든 경로의 화면에 속합니다.
Claude Code 캐시를 무효화하는 행동
Claude Code prompt caching의 핵심은 prefix matching입니다. 요청의 앞부분이 바뀌면 뒤쪽 내용이 비슷해도 기존 cache entry와 맞지 않을 수 있습니다. 그러므로 "token이 많았나"보다 "비싼 turn 직전에 prefix 모양이 바뀌었나"가 더 중요할 때가 많습니다.
| 최근 행동 | 위험도 | 다음 확인 |
|---|---|---|
| model 변경 | 높음 | spike 전후의 model과 timestamp를 비교한다. |
| MCP server 연결/해제 | 높음 | tool definitions가 초기 prefix를 바꿀 수 있다. |
| 전체 tool deny | 높음 | whole-tool denial은 tool context를 바꾼다. |
/compact | 높음 | conversation context를 다시 쓰므로 reuse를 끊을 수 있다. |
| Claude Code upgrade | 높음 | prompt shape나 cache scope가 달라질 수 있다. |
| provider, API route, gateway 변경 | 높음 | cache scope와 billing owner가 함께 바뀔 수 있다. |
| 긴 idle gap | 중간 | TTL이 만료되어 다음 read가 실패했을 수 있다. |
| subagent, fork, worktree, directory change | 중간 | context가 경로, 프로세스, agent scope로 갈라질 수 있다. |
| 파일 편집 | 낮음 | context를 추가하지만 반드시 초기 prefix를 깨지는 않는다. |
| output style 또는 permission mode 변경 | 낮음 | timing이 맞으면 기록할 필요가 있다. |
/recap 또는 rewind | 낮음 | 유용한 조작이지만 usage field는 확인한다. |
해석은 보수적으로 시작하는 편이 안전합니다. 의미 있는 context change 뒤의 cache write는 예상 가능한 동작입니다. 같은 route, 같은 model, 같은 MCP setup, 짧은 간격, 비슷한 prompt shape에서 high creation이 반복될 때 더 강한 문제가 됩니다.
경로별 증거: 서로 다른 숫자를 한 청구서로 만들지 않는다
동일한 Claude Code 작업도 서로 다른 계량 계약을 거칠 수 있습니다. subscription login, API key, Agent SDK, cloud provider, gateway 모두 usage나 cost를 표시할 수 있지만 같은 meter가 아닙니다.
| 경로 | 숫자가 의미할 수 있는 것 | 더 강한 증거 |
|---|---|---|
| Claude subscription login | plan/seat usage, limit window, reset timing, included usage. | Help Center usage 설명, account status, /status, plan message. |
| Claude API key | pay-as-you-go API token billing. | Claude Console, Usage and Cost API, project billing settings. |
| Agent SDK | SDK message 기반 usage와 cost estimate. | SDK fields와 Console 또는 Usage and Cost API 대조. |
| Bedrock, Vertex, Foundry | provider-routed model use, provider billing, cache support boundary. | cloud provider invoice와 route-specific request logs. |
| Gateway | gateway usage와 upstream pass-through behavior. | gateway logs와 가능하면 upstream billing. |
Claude Code costs와 Help Center usage article은 subscription usage와 API billing을 구분한다는 점에서 중요합니다. subscription limit message로 API spend를 증명하지 말고, SDK estimate로 구독 seat가 청구됐다고 증명하지 마십시오.
실제 증상이 limit window 중단이라면 Claude Code rate limit 또는 Claude Code rate limit reached를 보는 편이 맞습니다. cache math는 입력 측 소비를 설명하지만 quota recovery 전체 절차는 아닙니다.
수정 순서: 작은 변경 후 다음 turn에서 검증한다
한 번 비싼 turn이 나왔다고 전체 workflow를 바꿀 필요는 없습니다. 한 번에 하나의 요인만 다루고 다음 비슷한 turn에서 측정합니다.
- 경로를 식별한다. subscription usage, API key billing, SDK estimate, provider route, gateway route 중 무엇인지 확인한다.
- 캐시 필드를 읽는다. 여러 비슷한 turn에서
cache_creation_input_tokens와cache_read_input_tokens를 비교한다. - invalidator를 이름 붙인다. model, MCP, whole-tool denial,
/compact, upgrade, provider, TTL, subagent, fork, worktree, directory scope. - 초기 prefix를 안정화한다. 같은 작업 중 model이나 MCP setup을 자주 바꾸지 않는다.
- 무관한 작업은
/clear로 나눈다. 관련 없는 context가 앞쪽에 남으면 prefix가 커지고 불안정해진다. /compact는 자연스러운 경계에서 사용한다. 너무 큰 conversation에는 유용하지만 cache miss의 첫 반응은 아니다.- 1-hour TTL은 cadence로 판단한다. write multiplier가 더 높으므로 이후 read가 충분해야 이득이다.
- 다음 비슷한 turn을 확인한다. 성공하면 repeated creation이 줄고 read가 늘어야 한다.
model 변경, MCP 축소, compact, gateway 변경을 동시에 하면 결과를 해석하기 어렵습니다. 비용이 내려가도 어떤 행동이 원인이었는지 알 수 없습니다. 작은 변경과 같은 경로의 증거가 핵심입니다.
의심스러운 spike에 필요한 증거 묶음
"캐시 버그 같다"는 말보다 같은 경로와 같은 context shape를 비교할 수 있는 증거가 더 강합니다. 동료, FinOps, support engineer가 판단하려면 최소한 아래 요소가 필요합니다.
| 증거 | 중요한 이유 |
|---|---|
| timestamp와 timezone | usage records와 invoice를 맞춘다. |
| Claude Code version | upgrade가 prompt shape를 바꿀 수 있다. |
| model | model switch는 고위험 invalidator다. |
| active route | subscription, API key, SDK, provider, gateway를 섞지 않는다. |
| MCP server list 전후 | connect/disconnect가 초기 prefix를 바꿀 수 있다. |
| tool permission changes | whole-tool denial은 tool context를 바꾼다. |
/compact, /clear, /recap, rewind history | conversation shape 해석에 영향을 준다. |
cache_creation_input_tokens 및 cache_read_input_tokens | write/read의 핵심 증거다. |
| 비슷한 hit/miss turn 비교 | 단일 스크린샷보다 강하다. |
| billing surface | Console, Usage and Cost API, provider invoice, subscription usage. |
context change 직후 한 번의 cache write만으로는 버그라고 보기 어렵습니다. stable route, stable model, stable MCP setup, 짧은 간격, 비슷한 input shape에서도 high creation이 반복될 때 support packet으로 올릴 가치가 있습니다.
자주 묻는 질문
Claude Code cache miss는 별도 비용인가요?
아닙니다. 재사용 가능한 prefix가 저렴한 cache read로 읽히지 않고 다시 처리되거나 쓰인 상태로 보는 것이 안전합니다. 별도 fee 이름을 찾기보다 token class와 route를 봐야 합니다.
12.5x는 어디서 나오나요?
Anthropic의 현재 배율에서 5-minute cache write는 1.25x, cache read는 0.1x입니다. 같은 token 양이면 1.25 / 0.1 = 12.5입니다.
어떤 필드가 cache miss를 증명하나요?
cache_creation_input_tokens와 cache_read_input_tokens부터 봅니다. creation이 높고 read가 낮으면 prefix가 저렴하게 재사용되지 않았을 가능성이 있습니다. 단일 turn보다 여러 비슷한 turn의 비교가 중요합니다.
/compact가 token 비용을 줄이나요?
경우에 따라 그렇습니다. 너무 큰 conversation을 자연스러운 경계에서 줄이는 데 도움이 되지만, context를 다시 쓰기 때문에 cache reuse를 끊을 수도 있습니다.
1-hour TTL을 써야 하나요?
route가 지원하고 이후 read가 더 높은 write multiplier를 회수할 때만 의미가 있습니다. 긴 TTL은 자동 절감 기능이 아닙니다.
/cost는 Claude 청구서인가요?
아닙니다. /cost와 SDK cost fields는 monitoring에 유용한 추정치입니다. 최종 증거는 Claude Console, Usage and Cost API, provider invoice, gateway record, 또는 subscription usage surface입니다.
언제 캐시 버그를 의심할 수 있나요?
timestamp, version, model, route, MCP setup, permission changes, cache fields, 비슷한 hit/miss turn, billing surface가 같은 경로로 모인 뒤입니다. 그 전에는 일반 invalidation이나 TTL expiry일 가능성이 더 큽니다.