Claude Code で cache miss や高い token コストが見えたとき、最初に探すべきものは「未命中という名前の追加料金」ではありません。多くの場合、再利用できるはずの prefix が安い cache read に乗らず、入力が再処理された、または cache creation として再度書き込まれたという意味です。モデルが生成した output tokens は、入力側のキャッシュとは別に通常どおり発生します。
2026 年 5 月 24 日時点の Anthropic の公開価格では、5 分の cache write は基本 input の 1.25 倍、cache read は 0.1 倍です。同じ token 量で見れば 1.25 / 0.1 = 12.5 になります。つまり 12.5x は「書き込みと読み取りの比較」であり、Claude Code が公式に定義した cache miss 罰金ではありません。
次に確認するのは経路です。その数字は Claude のサブスクリプション利用量なのか、API key の従量課金なのか、Agent SDK の推定値なのか、Bedrock、Vertex、Foundry、gateway の記録なのか。経路を決めずに /compact を打つ、モデルを変える、バグだと決める、という順番にすると証拠が壊れます。まず cache_creation_input_tokens、cache_read_input_tokens、モデル、MCP、バージョン、時刻、請求面をそろえます。
まず見るもの：経路、フィールド、直前の変更
| 問い | 短い答え | 集める証拠 |
|---|---|---|
| cache miss は別料金か | いいえ。安い read が起きず、prefix が再処理または再書き込みされた状態です。 | 同じ経路の cache creation と cache read。 |
| なぜ 12.5x と言われるのか | 5 分 write は 1.25x、read は 0.1x。同量なら 1.25 / 0.1 = 12.5 です。 | Anthropic の価格表と usage フィールド。 |
| 最初に確認すること | どの経路の数字か。subscription、API key、SDK、cloud provider、gateway を混ぜないこと。 | /status、/cost、Console、Usage and Cost API、provider invoice。 |
| 疑わしいパターン | 同じような turn で high creation、low read が続き、model、MCP、route、時間間隔が安定している。 | 隣接 turn の比較、MCP 一覧、model、version、時刻。 |
| 先にやらないこと | 原因不明のまま compact、provider 変更、bug 断定をしないこと。 | まず prefix を変えた行動を特定します。 |
経路そのものが曖昧なら、先に Claude Code API key とサブスクリプション課金 を確認してください。MCP 定義や tool context が大きすぎるなら Claude Code MCP context overload が近い問題です。キャッシュミスは入力側の再利用に関する説明であり、限度額、プラン窓、プロバイダー請求の全体像を一つで解決するものではありません。
12.5x は write/read の倍率で読む
Claude API pricing は、通常 input、cache write、cache read、output を分けています。現在の公開説明では、5 分 cache write が 1.25x、1 時間 cache write が 2x、cache read が 0.1x です。
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 になった、あるいは read されると思った prefix が creation 側に出た、という読み方です。新しい会話、model の切り替え、MCP server の接続や切断、長い idle、Claude Code の更新、/compact の直後に一度 creation が増えることは、正常な説明で足りる場合があります。
コスト差が目立つのは prefix が大きいときです。長い会話履歴、プロジェクト context、tool result、MCP server definitions、subagent context、file pack、大きな system prompt が早い位置にあると、read できなかっただけで 1 turn が重く見えます。小さな miss はノイズかもしれませんが、大きな creation が似た turn で繰り返されるなら調査対象です。
token の分類帳：total だけでは原因が見えない
高い turn を total tokens だけで見ると、量はわかっても原因がわかりません。Claude Code の数字は token class に分けて読んだほうが安全です。
| メーター | 意味 | 使い方 |
|---|---|---|
| 通常 input tokens | キャッシュから読まれず、モデルが直接処理した入力。 | キャッシュがない、または一部だけ一致した場合の基礎コスト。 |
cache_creation_input_tokens | prompt cache に書かれた、または creation 側で処理された token。 | 1 回の expected 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 の早期発見には役立ちますが、最終的な請求証拠としては Claude Console、Usage and Cost API、provider invoice など経路ごとの公式面に戻ります。
経路が曖昧なときは、まず最小確認をします。
bashclaude /status /cost
/status は現在の account や route を見るため、/cost は API 風の費用監視に使うためのものです。請求を確定する証拠は、その run を生んだ経路に属します。
何が 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 は available 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 が path、process、agent scope で分かれる可能性。 |
| ファイル編集 | 低め | context は増えますが、必ず早い prefix を壊すとは限りません。 |
| output style や permission mode の変更 | 低め | timing が一致する場合だけ記録します。 |
/recap や rewind | 低め | 便利な操作ですが、usage fields は確認します。 |
安全な解釈は控えめです。意味のある context change のあとに cache write が出るのは自然です。stable route、stable model、stable MCP setup、短い時間差、似た prompt shape でも high creation が続くなら、異常として扱う価値があります。
経路ごとの証拠を混ぜない
同じ Claude Code 作業でも、数字は別々の契約から来ることがあります。subscription login、API key、Agent SDK、cloud provider、gateway はどれも usage や cost を表示し得ますが、同じメーターではありません。
| 経路 | 数字が意味し得るもの | 強い証拠 |
|---|---|---|
| Claude subscription login | plan/seat usage、limit window、reset timing、included usage。 | Help Center の usage 説明、account status、/status、plan message。 |
| Claude API key | 従量課金 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 経由の model use、provider billing、cache support boundary。 | cloud provider invoice と route-specific 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 で subscription seat の請求を証明しないこと。
実際の症状が limit window の中断なら、Claude Code rate limit または Claude Code rate limit reached を参照してください。cache math は入力側消費の説明であり、quota recovery 全体の代わりではありません。
修正の順序：小さく変えて次の turn で測る
一度の高コスト turn を見て、すぐに全体の作業設計を変える必要はありません。1 つずつ変え、次の似た turn で測ります。
- 経路を特定する。 subscription usage、API key billing、SDK estimate、provider route、gateway route のどれか。
- cache fields を読む。 数回の似た 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は自然な切れ目で使う。 会話が大きすぎるときは有効ですが、cache miss への最初の反応ではありません。- 1-hour TTL は cadence で判断する。 write が高くなるため、後続 read が十分あるときだけ意味があります。
- 次の似た turn を検証する。 成功なら repeated creation が下がり、read が増えます。
同時に model 変更、MCP 削減、compact、gateway 変更をすると、下がった理由がわかりません。修正は小さく、証拠は同じ経路で比較します。
疑わしい spike の証拠セット
「cache bug かもしれない」という報告より、同じ経路と同じ context shape を比較できる証拠のほうが有用です。
| 証拠 | 重要な理由 |
|---|---|
| timestamp と timezone | usage record と 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 の直後に 1 回 write が出た程度では、bug と呼ぶには弱いです。stable route、stable model、stable MCP setup、短い時間差、似た input shape でも high creation が繰り返されるなら、support packet としてまとめる価値があります。
よくある質問
Claude Code の cache miss は別料金ですか？
いいえ。再利用できる prefix が cache read で安く読まれず、再処理または再書き込みされた状態として読むのが安全です。別料金名を探すより、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 が安く再利用されていない可能性があります。1 回より複数の似た turn の比較が重要です。
/compact は token コストを下げますか？
場合によります。大きすぎる conversation を自然な境界で縮めるには役立ちますが、context を書き換えるため cache reuse を切ることもあります。
1-hour TTL は使うべきですか？
route が対応し、後続 read が高い write multiplier を回収できるときだけです。長い TTL は自動的に安くなる機能ではありません。
/cost は Claude の請求書ですか？
いいえ。/cost や SDK cost fields は監視に便利な推定値です。最終証拠は Claude Console、Usage and Cost API、provider invoice、gateway record、または subscription usage surface です。
いつ cache bug を疑えますか？
timestamp、version、model、route、MCP setup、permission changes、cache fields、似た hit/miss turn、billing surface が同じ経路でそろったあとです。それ以前は普通の invalidation や TTL expiry のほうがよくあります。