この記事で分かること：
- プロンプトキャッシュが効くコンテキスト構造と効かない構造の違い
- キャッシュを入れてもコストが増えるケース3パターン
- 本業で複数社のAPI連携を設計してきた視点での実務的な判断基準
「プロンプトキャッシュを使えばコストが下がる」——このメッセージだけが独り歩きして、実際には逆効果だったという話を複数の現場で聞く。
本業でCopilot StudioやDify Enterprise向けのAzure OpenAI連携を扱いながら、Claude APIも個人の自動化実験で使っている立場から、キャッシュの「罠」を整理したい。
キャッシュが効く条件を正しく理解する
Claude APIのプロンプトキャッシュは、システムプロンプトや参照ドキュメントなど「リクエスト間で変わらない部分」が長い場合にコストを削減できる仕組みだ。
具体的には：
- システムプロンプト（役割定義・ルール）が500〜1,000トークン以上ある
- 同じ文書を複数回参照する（RAGのコンテキスト注入など）
- 同一セッション内で同じ設定を繰り返し使う
これらに当てはまらないと、キャッシュのメリットはほぼ出ない。
失敗パターン1：毎回違う動的コンテンツをキャッシュしようとする
最も多い失敗が「プロンプト全体をキャッシュしようとする」パターン。
ユーザーの入力内容（質問・指示）は毎回変わる。動的な部分が含まれるとキャッシュが無効化され、再計算のコストだけが上乗せされる。
キャッシュできる部分とできない部分を構造で分離するのが基本で、システムプロンプトだけをキャッシュ対象にするのが正しい設計。
失敗パターン2：リクエスト頻度が低すぎてTTL切れが頻発する
Claude APIのキャッシュにはTTL（有効期限）がある。頻度が低い用途では、キャッシュが切れるたびに「コールドスタート」コストが発生する。
TTLが切れた状態でのリクエストは、通常トークンコストにキャッシュ保存コストが加わる。利用頻度が低い場合、かえって高くなることがある。
実務での判断基準：1分間に数回以上リクエストがある用途にキャッシュは向いている。1日数回しか呼ばないバッチ処理などには向かない。
失敗パターン3：キャッシュ対象にしたコンテキストが変更される設計
ベクターDBから取得した参照ドキュメントをキャッシュしている場合、ドキュメント内容が変わると都度キャッシュが無効化される。
定期的に更新されるナレッジベースを参照する用途では、キャッシュのヒット率が実測で想定より大幅に低くなることがある。「キャッシュを使っているはずなのにコストが下がらない」という相談の多くがこのパターン。
実際にコスト比較するときの確認項目
キャッシュ導入前に確認しておくべき指標：
| 確認項目 | 良い条件 | 注意が必要な条件 |
|---|---|---|
| システムプロンプト長 | 1,000トークン以上 | 200トークン未満 |
| リクエスト頻度 | 毎分複数回 | 1日数回以下 |
| コンテキストの変化 | ほぼ固定 | 頻繁に更新される |
まとめ
- プロンプトキャッシュは「長くて固定な部分がある高頻度用途」でのみ費用対効果が出る
- 動的コンテンツ・低頻度用途・頻繁に更新されるコンテキストには向かない
- 導入前に「キャッシュヒット率が実測でどれくらいか」を試算してから判断する
皆さんの現場でのClaude APIのキャッシュ活用、どんな用途でうまくいっていますか？
Claude APIのコスト設計について、noteでも詳しく書いています：
技術的な相談（Copilot・AIエージェント構築、60分のビデオチャット）も受け付けています。ご相談の際は「Qiitaを見た」とお書きください：https://coconala.com/services/4209036