Claude が 92% のキャッシュヒット率を達成した方法：ケーススタディ
AI エージェントが一歩を踏み出すたびに、課税が発生します。
すべてをゼロから読み直すのです。
システム指示。ツール定義。3 ターン前にすでに読み込んだプロジェクトコンテキスト。そのすべてを。毎ターンごとに。
これがコンテキスト税です。そして、長期実行されるエージェント型ワークフローにおいて、これは多くの場合、AI インフラ全体で最も高額な項目です。
計算してみましょう：20,000 トークンのシステムプロンプトを 50 ターン実行すると、100 万トークンの冗長な計算 が全額請求され、新たな価値は一切生み出されません。
解決策はプロンプトキャッシングです。しかし、これを適切に活用するには、内部で実際に何が起こっているかを理解する必要があります。
何が変わり、何が変わらないかから始める
最適化を行う前に、エージェントのプロンプト（コンテキスト）の構造について明確に考える必要があります。
エージェントが送信するすべてのリクエストには、根本的に異なる 2 つの部分があります。
静的プレフィックス： システム指示、ツール定義、プロジェクトコンテキスト、動作ガイドラインが含まれます。このコンテンツは、セッションのすべてのターンで同一です。
動的テール： ユーザーメッセージ、ツール出力、ターミナル観測結果。これはリクエストごとに固有であり、会話が進むにつれて増えていきます。
この区別がすべてです。静的プレフィックスは、理由もなく再計算を続けている高コストな部分です。動的テールだけが、実際に新しい計算を必要とする唯一の部分です。
プロンプトキャッシングは、静的プレフィックスの数学的状態を保存することで機能し、将来のリクエストではその再計算を完全にスキップできるようにします。そのプレフィックスの処理に対しては 1 回だけ支払います。以降のすべてのターンは、メモリから読み取ります。
なぜこれが機能するのか：トランスフォーマーの実際の動作
キャッシングがなぜそれほど効果的なのかを本当に理解するには、モデルがプロンプトを読み取るときに内部で何が起こるかを理解する必要があります。
すべての LLM 推論リクエストには 2 つのフェーズがあります。
フェーズ 1：プリフィル
ここでモデルは、入力プロンプト全体を処理します。これは計算バウンドであり、コンテキスト内のすべてのトークンに対して高密度な行列乗算を実行することを意味します。モデルはすべてを読み取り、その表現を構築します。これが遅くて高コストなフェーズです。
フェーズ 2：デコード
ここでモデルは、出力トークンを 1 つずつ生成します。これは計算バウンドではなくメモリバウンドです。なぜなら、モデルは重い計算を実行するよりも、以前に計算された状態を読み取ることにほとんどの時間を費やすからです。
プリフィルフェーズ中に、トランスフォーマーは各トークンに対して 3 つのベクトル（Query、Key、Value）を構築します。アテンション機構はこれらを使用して、各トークンがシーケンス内の他のすべてのトークンとどのように関連するかを把握します。
ここで重要な洞察は、Key ベクトルと Value ベクトルは、それより前にあるトークンにのみ依存する ということです。特定のプレフィックスに対して一度計算されれば、変更する必要は決してありません。
以下の図は、今説明した内容を視覚的に示しています。
キャッシングがない場合、それらの Key-Value テンソルは、リクエストが完了した瞬間に破棄されます。次のリクエストはゼロから開始し、20,000 トークンすべてに対してそれらを再計算します。
KV キャッシングは、これらのテンソルを保存することでこれを解決します。 インフラストラクチャは、入力テキストの暗号化ハッシュによってインデックス付けされたこれらのテンソルを推論サーバーに保持します。同じプレフィックスを持つ新しいリクエストが来ると、ハッシュが一致し、テンソルが即座に取得され、モデルはその計算をすべてスキップします。
これにより、生成トークンあたりの計算複雑性が O(n²) から O(n) に低下します。50 ターンにわたって繰り返される 20,000 トークンのプレフィックスの場合、これは莫大な削減です。
経済性
価格体系を理解することで、このアーキテクチャ上の決定がなぜそれほど重要な結果をもたらすのかがわかります。
Anthropic がモデルファミリー全体でキャッシングの価格をどのように設定しているかを以下に示します。
理解すべき 3 つの数値：
- キャッシュ読み取りは、基本入力価格の 10% であり、キャッシュから読み取られたトークンごとに 90% 割引されます。
- キャッシュ書き込みは、基本入力価格よりも 25% 高く、KV テンソルを保存するための少額のプレミアムです。
- 拡張 1 時間キャッシングは、基本価格の 2 倍 です。
この計算が成立するのは、キャッシュヒット率が高いままである場合のみです。そこで、実際の状況でのその様子を示す最良の実例について説明します。
Claude Code：30 分間のセッションウォークスルー
Claude Code は、1 つの目的を中心に完全に構築されています。それは、キャッシュをホットに保つことです。
それが具体的に何を意味するかを理解するために、典型的な 30 分間のコーディングセッションがどのように進行し、正確に何が請求され、何が請求されないかを追跡してみましょう。
0 分目：セッション開始
Claude Code は、システムプロンプトとツール定義を読み込みます。また、プロジェクトルートにある CLAUDE.md ファイルも読み取ります。このファイルには、コードベースと規約が記述されています。このペイロードは、20,000 トークンを超えることがよくあります。
これがセッション全体で最も高額な瞬間です。すべてのトークンが新しいものです。しかし、このコストを支払うのは 1 回だけです。
1 分目から 5 分目：最初のコマンド
「認証モジュールを見て、改善点を提案して」のような最初の指示を入力します。
Claude Code は Explore Subagent を起動します。コードベース内を移動し、ファイルを開き、grep コマンドを実行し、関連するコードの全体像を構築します。これらすべてが動的テールに追加されます。
20,000 トークンの静的な基盤は？ すでにキャッシュにあります。$3.00/MTok ではなく、$0.30/MTok で読み戻されています。新しいツール出力とメッセージに対してのみ支払いが発生します。
6 分目から 15 分目：深い作業
Plan Subagent は、Explore Subagent からの調査結果を受け取ります。Claude Code は、生の結果をそのまま渡す（これにより動的テールが不必要に肥大化する）代わりに、簡潔なサマリーを渡します。これにより、サフィックスを管理可能に保ち、キャッシュを効率的に保ちます。
プランナーは、構造化された実装計画を作成します。それを確認し、承認すると、Claude Code が変更を開始します。このループのすべてのターンで、20,000 トークンのプレフィックスがキャッシュから読み取られます。キャッシュヒットごとに TTL がリセットされ、将来のターンに向けてキャッシュがウォームに保たれます。
16 分目から 25 分目：反復
調整を依頼します。Claude Code はアプローチを修正します。さらにツールコール、さらにターミナル出力。動的テールは成長していますが、それはこのセッションにおける新しいユニークなコンテンツのみを表しています。
この時点で、セッションは合計で数十万トークンを処理しています。しかし、20,000 トークンの基盤は、毎ターンキャッシュから読み取られています。
28 分目：/cost の実行
キャッシングがない場合、このようなセッションは簡単に 200 万トークンを超えます。Sonnet 4.5 のレートでは、約 $6.00 になります。
キャッシングが高効率で動作している場合：
- トークンの大部分は、$0.30/MTok でキャッシュから読み取られます。
- 新しい動的テールトークンのみが、新たに計算されます。
実際には、単一タスクで 80% 以上のコスト削減 が期待できます。これをすべてのユーザー、毎日について掛け合わせてみてください。
セッションが続くにつれてのシステムプロンプトレイアウトの概要を以下に示します。
すべてを壊すルール
プロンプトキャッシングに関する最も直感に反することは次のとおりです。
1 + 2 = 3。しかし、2 + 1 はキャッシュミスです。
インフラストラクチャはプロンプトをハッシュ化します。ハッシュは暗号化のための識別子です。その順序内で何かが変更されると、たとえ 2 つの要素の順序が異なるだけでも、ハッシュは変更されます。キャッシュは空です。プレフィックス全体が全額で再計算されます。
これに従う 3 つのルール：
- セッション中にツールを追加したり削除したりしないでください。キャッシュされたプレフィックスにはツールが含まれます。ツールを変更すると、その後のすべてが無効になります。
- セッションの途中でモデルを切り替えないでください。キャッシュはモデル固有です。会話の途中でより安価なモデルに切り替えるには、キャッシュ全体を再構築する必要があります。
- 状態を変更するためにプレフィックスを変更しないでください。代わりに、Claude Code はシステムに注意を促すタグを次のユーザーメッセージに追加します。プレフィックスは決して変更されません。
それがあなたにとって意味すること
上記のすべては、Claude Code がキャッシングをどのように処理するかを説明しています。独自のエージェントを作成する場合も、同じルールが適用されます。
プロンプトを構成する方法は次のとおりです。
- 上部にはシステム指示とルールがあります。途中で変更しないでください。
- 必要なツールをすべて事前にロードしてください。追加したり削除したりしないでください。
- その後に、取得されたコンテキストとドキュメントが続きます。期間中は静的です。
- 下部には、会話の履歴とツールの出力があります。
自動キャッシングがオンになっていると、会話が進むにつれてブレークポイントが自動的に前方に移動します。
Claude Code は自身のキャッシュを管理しています。Anthropic は API に自動キャッシングを追加したばかりなので、独自のエージェントでも同じことができます。
自動キャッシングがない場合、トークンの境界がどこにあるかを覚えておく必要がありました。境界を間違えると、キャッシュにアクセスできなくなります。
キャッシュセーフなフォークを使用して、コンテキスト制限に合わせてコンパクト化します。同じシステムプロンプト、ツール、会話を使用し、コンパクト化指示を新しいメッセージとして追加します。
コンパクト化呼び出しは、最後の呼び出しとほぼ同じように見えます。キャッシュされたプレフィックスが再び使用されます。新しいものとして請求されるのは、コンパクト化指示のみです。
API が機能しているかどうかを確認するには、各レスポンス内の次の 3 つのフィールドに注目してください。
- cache_creation_input_tokens：メモリに格納されたトークン
- cache_read_input_tokens：メモリから読み取られたトークン
- input_tokens：通常どおり処理されたトークン
キャッシュ効率スコアは、作成トークン数に対する読み取りトークン数です。アップタイムを監視するのと同じように、この数値を監視してください。
重要なポイント
プロンプトキャッシングは、オンにする機能ではありません。それは、それを中心に構築するアーキテクチャ上の規律です。
Claude Code は、それが大規模に行われた場合のその分野の最良の例です。
キャッシュヒット率 92%。コスト削減率 81%。
エージェントを作成している場合、これが設計図です。この課税を無視することはできません。それは存在します。重要なのは、それに対して支払っているのか、それとも排除しているのかだけです。
