Claude API: キャッシュ診断で「どこが変わってキャッシュが外れたか」を特定する

どんな時に使う？

• 長いプロンプトのエージェントで、料金が想定より高い（キャッシュ読み取りが少ない）
• system プロンプトに時刻を入れる、JSON のキー順が毎回変わる、など見つけにくい原因を探したい

手順

1. 毎回のリクエストに beta ヘッダー cache-diagnosis-2026-04-07 を付ける（付けたリクエストだけ比較用に記録される）
2. 2回目以降は前回レスポンスの id を diagnostics.previous_message_id に入れる
3. レスポンスの diagnostics.cache_miss_reason.type を見る: model_changed / system_changed / tools_changed / messages_changed
4. usage.cache_read_input_tokens と組み合わせて判断
   • 診断 null かつ読み取り多 → 正常
   • 診断 null かつ読み取り少 → キャッシュ切れ。間隔を詰めるか 1時間 TTL を使う
   • *_changed かつ読み取り少 → 自分のバグ。示された箇所を固定する

よくある原因

• system プロンプトの先頭に日時やリクエストごとの値（→ 後ろのメッセージへ移す）
• Go／Swift などで tool_use の JSON キー順がランダム
• 会話履歴の途中を編集・切り詰めた
• tool_choice・thinking 設定・effort を途中で変えた

注意点

• 最初に分岐した箇所しか報告されない。直したら次を見る
• 関連: Claude Code: Haiku 5.5 の自動コンパクトを100Kにして安い料金帯に収める ／ ガイド: モデルと料金プランの選び方（AIコーディング）

出典

• @ClaudeDevs · 2026-05-19
• 公式: platform.claude.com