Claudeのprompt cacheが効かないときの確認順：usage・接頭辞・TTL・SDK

先に結論

Claude APIのprompt cachingが効いていないように見える場合、料金や体感速度だけで判断せず、まずレスポンスのusageにあるキャッシュ作成・読み取りトークンを確認します。その後、同一モデル・同一ツール・同一の安定した接頭辞で2回続けて呼び出し、TTL、最小キャッシュ長、SDKやヘッダーの差を一つずつ切り分けます。最初の呼び出しがキャッシュ作成になる点も忘れないでください。

30秒要約

**確認日:** 2026年8月6日

• 判定の中心は `cache_creation_input_tokens` と `cache_read_input_tokens` です。
• 1回目は作成、2回目以降に読み取りが発生するため、単発テストでは判定できません。
• 接頭辞の一字、モデル、ツール、画像、thinking設定などが変わると再利用されない場合があります。
• 5分と1時間のTTL、SDKの自動キャッシュと明示的ブレークポイントを公式文書で確認します。

何が起きたか

Claude APIには、繰り返し使う長い接頭辞を再利用して処理時間や入力コストを抑えるprompt cachingがあります。ところが、アプリ側でキャッシュを有効にしたつもりでもusageの読み取りが増えない、毎回作成扱いになる、しばらくすると効かない、といった相談が起きます。多くは障害と決めつける前に、作成とヒットの区別、接頭辞の一致、TTL、対象モデル・SDKの条件を確認する必要があります。

今回の判断で重要なのは、出来事が報じられた日、対象となった製品・制度・運用、そして2026年8月6日時点の状態を一つの文に混ぜないことです。発表時点で正しかった条件が、現在も同じとは限りません。この記事では原典で示された出来事を起点にしながら、変更されやすい仕様、料金、募集状況、提供範囲は公式ページで再確認する前提にしています。

確定情報と観測を分ける

原典記事の体験談や担当者コメントは、導入判断に役立つ観測です。一方で、すべての環境へ再現する保証、将来の継続提供、独立した性能評価を意味しません。公式文書に書かれた仕様も、対象版や適用条件を外すと誤読につながります。

この対象で押さえる3つのポイント

最初のリクエストはキャッシュ作成になる

キャッシュが存在しない状態では読み取りは発生しません。1回目の `cache_creation_input_tokens` を確認し、TTL内に同じ安定部分を使って2回目を送ります。2回目の `cache_read_input_tokens` が増えるかを見ます。

人間には同じでもAPIには異なる接頭辞がある

日時、リクエストID、並び順、空白、ツール定義、画像、モデル名などが接頭辞へ混ざると、毎回異なる入力になります。動的情報はキャッシュ対象の後ろへ移し、安定部分を前に固定します。

SDKの抽象化と生リクエストを分けて確認する

SDKが自動キャッシュを提供する場合と、明示的なブレークポイントを設定する場合があります。SDK版を記録し、必要ならHTTPリクエストの形とusageを確認して、アプリの集計バグとAPI側の非ヒットを分離します。

影響と読者の判断

prompt cachingは長い規約、文書、ツール定義を繰り返すワークロードで効果が期待できます。一方、短い入力や毎回大きく変わる会話では、設計を複雑にしても利点が小さい場合があります。導入判断は、キャッシュ対象の長さ、再利用回数、TTL内の呼び出し密度、usageで測った実績から行います。

AI関連の更新を横断して確認する場合は、[AIニュース話題度レーダー](/ainews/)へ戻ると、単発の出来事を他の製品更新や導入事例と並べて確認できます。個別記事は結論を固定するものではなく、公式情報を再確認するための入口として利用してください。

Claude Code側の常時読み込み文書を短く保つ設計は、[Claude Codeの長期記憶設計](/ainews/article/claude-code-memory-architecture/)で扱っています。APIキャッシュとローカルの記憶ファイルは別機能ですが、安定情報と動的情報を分ける考え方は共通します。

確認手順1: 最小の2リクエストでヒットを確認する

1. 利用モデル、API版、SDK名と版、TTL設定を記録します。 2. 十分な長さの固定system文または文書を用意し、動的な日時を含めません。 3. 1回目を送信し、usageの作成トークンと読み取りトークンを保存します。 4. TTL内に、固定部分を一字も変えず末尾の質問だけ変えて2回目を送ります。 5. 2回目の読み取りトークンが増えたか確認します。 6. ヒットしたら、実アプリの入力と最小例を差分比較します。

この確認では、一度に複数の条件を変えないことが重要です。変更前の状態を保存し、1項目だけ変えて同じ入力を再実行します。結果が改善しても、変更した条件との因果関係が確認できない場合は「解決」と断定せず、「再現待ち」として扱います。

確認手順2: 実アプリで接頭辞差分を特定する

1. APIへ送る直前のJSONから秘密情報を除き、安定部分のハッシュを記録します。 2. 連続する2リクエストでモデル、system、tools、画像、thinking設定を比較します。 3. 日時、乱数、追跡IDなどの動的値をキャッシュ対象の後ろへ移します。 4. ツール定義の並び順とJSONシリアライズを固定します。 5. SDKを最新版へ上げる場合は変更履歴を読み、同じ最小テストを再実行します。 6. 料金集計はusageの区分を使い、請求画面だけで単発の成否を判断しません。

本番環境へ反映する前に、テスト用のデータ、リポジトリ、アカウント、テナントで同じ手順を再現してください。外部サービスへ送信される情報、保存されるログ、利用規約、料金発生条件を確認できない場合は、機密性の低い最小データに限定します。

復旧・導入で詰まったときの切り分け

キャッシュが効かなくてもAPI自体が正しく応答するなら、まず機能を無効化して本番処理を継続できるようにします。キャッシュ前提のコスト見積もりを一時停止し、上限アラートを厳しくします。認証情報を含む生リクエストを共有せず、再現用にはダミーキーと短縮した固定文書を使います。

切り分けの基本は、対象そのものの問題、ローカル環境の問題、アカウント・権限の問題、外部サービス側の一時的な問題を分離することです。公式ステータス、リリースノート、既知の問題を確認した後、最小構成で再現し、最後に既存環境へ戻します。削除や再インストールを最初に行うと証拠と設定を失うため、ログと設定の退避を先に行ってください。

検証結果を残すときの最小記録

再現できない成功例や、条件が分からない失敗例は、後から判断材料になりません。少なくとも次の項目を残してください。

スクリーンショットだけでなく、可能ならテキストのログも保存します。ただしAPIキー、トークン、個人情報、顧客データ、非公開コードは記録へ貼り付けず、伏字または安全な識別子へ置き換えてください。

更新履歴

• 2026-08-06: 現行公開ページの主題を保持し、原典・公式情報の確認経路、判断表、確認手順、復旧時の注意点を追加しました。

参考リンク

• [Anthropic Prompt Caching](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching) — キャッシュの仕組み、usage、TTL、設定条件の公式文書
• [Anthropic API Docs](https://docs.anthropic.com/) — 利用中SDKとAPI仕様を確認する公式文書