# プロンプトキャッシュミスの原因をAPIで特定する

> Claude APIのCache Diagnosticsはcache_miss_reasonでsystem_changedなど4種のキャッシュ無効化原因を返す。2026年9月23日にGA化した仕組みと実装パターンを解説する。

- Canonical: https://kuucorp.com/blog/claude-cache-diagnostics-api-design/
- Date: 2026-10-03
- Last modified: 2026-10-03
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
キャッシュ読み込みトークンが急にゼロへ落ちても、Messages APIの`usage`フィールドは理由を教えてくれない。システムプロンプトが変わったのか、ツール定義が変わったのか、履歴の編集が原因なのか——従来は仮説を立てて1つずつ潰すしかなかった。2026年9月23日にGA化した[Cache Diagnostics](/blog/prompt-caching-agent-design-context-reuse/)は、この当てずっぽうのデバッグを構造化されたレスポンスに置き換える。

## Cache Diagnosticsとは何か

> Cache Diagnosticsは直前のレスポンスIDを渡すだけで、2つのリクエストのプロンプト接頭辞がどこで分岐したかをAPIが特定する機能だ。

リクエストに`diagnostics`オブジェクトを含めると、APIはそのリクエストのフィンガープリントを`id`に紐づけて保存する。次のターンで直前の`id`を`diagnostics.previous_message_id`として渡すと、APIは保存済みフィンガープリントと新リクエストを比較し、レスポンスの`diagnostics`フィールドに分岐点を返す。初回ターンは比較対象が無いため`previous_message_id: null`を渡してオプトインするだけでよい。かつて必要だった`cache-diagnosis-2026-04-07`ベータヘッダーは不要になり、GA後は送っても無視される。

## キャッシュミスの原因はどう分類されるか

> `cache_miss_reason`はtypeで判別する共用体で、model/system/tools/messagesの変更4種と、比較不能だった2種を返す。

具体的には`model_changed`（モデル自体が変わった）、`system_changed`（システムプロンプトにタイムスタンプ等を埋め込んだ）、`tools_changed`（ツール定義の順序や内容が変わった）、`messages_changed`（過去の会話履歴を追記ではなく編集・削除した）の4種が分岐点を示す。加えて`previous_message_not_found`（フィンガープリントの保持期限切れや別ワークスペース起因）、`unavailable`（`thinking`や`tool_choice`など他パラメータの変更、または比較範囲を超えた長い会話）がある。各`*_changed`型は`cache_missed_input_tokens`という目安の推定値も持ち、どれだけのキャッシュ済み接頭辞を失ったかが分かる。

## usageとdiagnosticsをどう組み合わせて読むか

> `diagnostics`は「リクエストが変わったか」、`usage.cache_read_input_tokens`は「キャッシュが実際に当たったか」を示し、両方を見て初めて原因が切り分かる。

`diagnostics`が`null`で読み込みトークンが高ければ正常動作だ。`null`なのに読み込みトークンが低い場合は、リクエスト自体は一致しているがキャッシュエントリが期限切れになったケースで、5分TTLから1時間TTLへの切り替えが有効な対処になる。`*_changed`型が返り読み込みトークンも低ければ、それが本当のバグであり`type`が示す原因を直す対象になる。

## 実装と運用で何に注意すべきか

> フィンガープリントはハッシュとトークン数推定のみで生テキストを保持せず、ZDR適格だが保持期間は短く、継続したターンでの利用が前提になる。

マルチターンのループでは、直前レスポンスの`id`を毎ターン`previous_message_id`として引き渡す実装にする。ストリーミングでは`diagnostics`が`message_start`イベントに載るため、SDKのアキュムレータで最終メッセージまで保持すればよい。Claude API専用の機能でAmazon BedrockやGoogle Cloud経由では使えない点、フィンガープリントの保存先が同一ワークスペースに限られる点は事前に把握しておく必要がある。SMBではAPI呼び出し全体に`diagnostics`を常時組み込んでログに`cache_miss_reason`を残すだけで十分だが、エンタープライズで複数チームがモデルルーティングを行う場合は[LLMゲートウェイ](https://kuucorp.com/services/rde/)側でモデル固定や`system`プロンプトの一意性を保証する設計が要る。コスト計測基盤全体との統合は[AI FinOps設計](/blog/ai-finops-token-cost-instrumentation/)も参照してほしい。

## 参考

- [Cache diagnostics - Claude Platform Docs](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics)
- [Prompt caching - Claude Platform Docs](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
- [Pricing - Claude Platform Docs](https://platform.claude.com/docs/en/about-claude/pricing)

## まとめ

Cache Diagnosticsは、キャッシュミスという「見えない事故」を`cache_miss_reason`という診断可能な情報に変える機能だ。`usage.cache_read_input_tokens`と組み合わせれば、リクエストのバグとキャッシュエントリの期限切れを切り分けられ、プロンプトキャッシュのコストメリットを継続的に確保できる。自社のエージェント基盤にキャッシュ監視を組み込みたい場合は、[Kuuのエージェント運用支援](https://kuucorp.com/services/ai-ops/)で設計・実装を相談できる。