結論：diagnostics objectをopt inし、nullとfingerprintを別の状態として記録する
Claude APIのcache diagnosticsを使うなら、Messages APIのリクエストへdiagnostics objectを明示的に追加し、応答のdiagnosticsをtraceへ保存します。2026年9月23日の公式リリースノートで、この機能はbetaを外して利用できるようになりました。diagnostics objectを送らないリクエストでも応答フィールドは存在し、値はnullです。これは異常ではなく「診断を要求していない」という状態なので、未取得・失敗と分けて監視します。
移行の目的は、キャッシュが効いたと推測することではありません。fingerprint、usage、リクエスト条件、previous_message_idを同じ実行記録へ並べ、キャッシュ挙動を再現できるようにすることです。料金削減率や速度改善率は、公式が保証する一律の値として扱わず、自社の入力長と会話パターンで測ります。
一次情報はClaude Platform公式リリースノートとPrompt Caching公式ドキュメントです。既存のClaude Codeのprompt cache監視ガイドがCLIの/costやstatus lineを扱うのに対し、この記事はAPIレスポンスの診断状態に限定します。
GA化で変わる点を比較する
| 観点 | 移行前の混乱 | GA仕様での扱い |
|---|---|---|
| 有効化 | beta headerだけを送り続ける | diagnostics objectで明示的にopt inする |
| 応答 | フィールドがない場合を異常とみなす | 常にdiagnosticsを読み、未要求はnullとする |
| fingerprint | 値だけでhitと断定する | usage、入力条件、会話IDと組み合わせる |
公式更新では、リクエストのfingerprintはdiagnostics objectを含む場合だけ保存されると説明されています。したがってheaderだけを残した互換運用や、最初のターンだけdiagnosticsを付ける実装では、後続のprevious_message_id追跡に穴ができます。既存クライアントが生成するJSONを確認し、呼び出し単位で方針を決めます。
移行する7手順
- 対象を決める。全リクエストを変える前に、長いsystem promptと複数ターンの代表workflowを選びます。
- 現行の証跡を保存する。SDKバージョン、model ID、beta header、入力token、latency、usageを移行前の基準値として残します。
- diagnostics objectを追加する。アプリの秘密値を含めず、診断結果をtrace IDへ紐付ける設計を先に作ります。
- headerの依存を確認する。公式仕様とSDKの対応を読み、互換headerが残っていても新仕様へ段階的に寄せます。
- nullを正常状態として分類する。diagnostics objectなし、応答欠落、JSON parse失敗を別のメトリクスにします。
- 複数ターンを試す。初回の
previous_message_idをnullにし、後続ターンでfingerprintと参照先が記録されるか確認します。 - 段階展開する。検証環境、少数tenant、全体の順に広げ、料金・latency・エラー率を同じ期間で比較します。
監視とレビューのチェックリスト
- diagnostics objectを送ったかどうかがログで判別できる。
- diagnosticsの
nullをAPI障害と誤カウントしていない。 - fingerprintをtenant、model、会話IDと分離して保存している。
- 入力本文や個人情報をログへ複製せず、必要な識別子だけを残している。
- 初回と後続ターンで
previous_message_idの扱いをテストした。 - 料金、latency、cache状態を同じサンプルで比較した。
- 仕様変更時にSDK、header、ダッシュボードの担当者が決まっている。
運用上の落とし穴は、diagnosticsを有効にした瞬間にキャッシュが必ず改善すると考えることです。診断データは判断材料であり、入力の置き方、TTL、prefixの一致、リクエストの分岐を自動で直しません。管理者は「診断値があるか」だけでなく、「その値からどの変更を承認したか」まで変更票に残します。
また、保存期間も先に決めます。fingerprintやusageの組み合わせが業務や顧客を推測できる場合、ログ基盤のアクセス権、マスキング、削除期限を通常のアプリログと分けます。開発用の全文payloadを本番へ流用せず、再現用fixtureを匿名化してください。Prompt Cachingの設計は、モデルの料金表だけでなく、入力の再利用性とデータ境界を同時に見ます。
検証では、同じpromptを繰り返すケースだけでなく、system promptの一部が変わるケース、tool定義を追加するケース、modelを切り替えるケースを用意します。diagnosticsの値が変わった時に「キャッシュが壊れた」と決めつけず、どの入力prefix、どのtenant、どのproviderで差が出たかを分解します。エラー通知は、APIエラー、診断未要求、診断値の変化、料金の増加を別の通知先へ分けると、担当者が初動を誤りにくくなります。
本番展開後も、診断データの存在そのものを成功指標にしません。代表workflowのp50・p95 latency、input token、output token、cache関連のusage、拒否率、請求額を週単位で見直します。仕様変更やSDK更新の前には、前週のfixtureを再実行し、差分があればリリースノートと照合します。これにより、APIの仕様変更をアプリの不具合や顧客の入力変化と混同せずに説明できます。
なお、診断の有効化を本番の全tenantへ広げる前に、ログのサンプリング率とアクセス権を確認します。診断値を保存する担当と料金を見る担当が異なる場合、同じIDを使っても本文を共有しない設計にします。障害時に必要な最小情報を定義し、復旧後は一時的な詳細ログを削除するところまでrunbookへ書いておくと、可観測性の追加がデータ保持リスクへ変わりません。
よくある質問と次の行動
beta headerをすぐ削除してよいですか？
本番で一括削除するのではなく、SDKと実レスポンスを検証し、diagnostics objectで同じ診断情報が得られることを確認してから段階移行します。
nullはキャッシュミスですか？
いいえ。diagnostics objectを送っていない場合のnullであり、キャッシュ状態そのものと同義ではありません。リクエスト条件とusageを合わせて判断します。
実装の担当が決まりません。
API実装、ログ基盤、セキュリティ、料金管理の責任を一枚の変更票にまとめると進めやすくなります。必要なら無料診断で整理できます。
モデル選定はClaude APIのモデル一覧ガイド、料金の見積もりはClaude料金ガイド、運用の監視境界はAPIコスト削減ガイドも参照してください。Miraigentの無料診断では、診断ログを残しながら業務へ導入する手順を一緒に棚卸しします。