Claude Code がプロンプトキャッシングを使用する方法

Claude Code はプロンプトキャッシングを自動的に管理します。モデル切り替えがキャッシュなしの遅いターンをトリガーする理由、/compact のコスト、CLAUDE.md の編集がセッション中に適用されない理由、キャッシュヒット率を確認する方法を確認してください。

プロンプトキャッシングにより、Claude Code はより高速で費用効率的になります。キャッシングがなければ、API はターンごとに完全な履歴を再処理します。キャッシングがあれば、既に処理したものを再利用し、変更されたものに対してのみ新しい作業を行います。

Claude Code はプロンプトキャッシングを自動的に処理します。ただし、無効にすることはできます。プロンプトキャッシングの仕組みを理解することは依然として有用です。キャッシュを無効にするアクションがあり、次の応答が遅くなり、再構築中により高くなるためです。このページでは、どのアクションがそうであるか、一部の設定が再起動を待つ理由、使用量が高く見える場合にキャッシュパフォーマンスを確認する方法について説明します。

キャッシュの構成方法

Claude Code でメッセージを送信するたびに、新しい API リクエストが行われます。モデルはリクエスト間で何も記憶しないため、Claude Code は完全なコンテキストを再送信します。システムプロンプト、プロジェクトコンテキスト、すべての以前のメッセージとツール結果、および新しいメッセージです。新しいコンテンツは最後に追加されます。つまり、各リクエストのほとんどは前のリクエストと同じです。プロンプトキャッシングは、API が変更されなかった部分を再処理しないようにする方法です。

API は、プリフィックスと呼ばれる各リクエストの開始を、最近処理したコンテンツと照合することでキャッシュします。通常のターンでは、プリフィックスは前のリクエスト全体であり、最新の交換のみが新しいものです。一致は正確であるため、プリフィックスのどこかの変更は、その後のすべてを再計算します。ファイルごとまたはセグメントごとのキャッシングはありません。API リファレンスのプロンプトキャッシングの仕組みを参照して、基礎となるメカニズムを確認してください。

プリフィックスマッチングを最大限に活用するために、Claude Code は各リクエストを順序付けして、ターン間で変更されることがめったにないコンテンツが最初に来るようにします。

会話レイヤーへの変更は、システムプロンプトとプロジェクトコンテキストをキャッシュしたままにします。システムプロンプトへの変更は、すべての後続コンテンツが異なるプリフィックスの後ろに配置されるため、すべてを無効にします。3 番目の列は、完全なリストではなく一般的なトリガーを示しており、以下のセクションでは、セッション開始時に固定される出力スタイルなどのコンテンツを含む完全なセットについて説明します。

プリフィックスマッチルールは、このページのほとんどの動作を説明しています。たとえば、Plan mode とスキル読み込みは、会話メッセージとして命令を追加するため、キャッシュされたプリフィックスはそのままです。

2 つの設定はプロンプトテキストの一部ではないため、レイヤーテーブルに表示されません。ただし、どちらもキャッシュキーの一部です。

• モデル: 各モデルは独自のキャッシュを持ちます。モデルを切り替えると、コンテンツが同じであっても、リクエスト全体が再計算されます。以下のモデルの切り替えを参照してください。
• 努力レベル: 各努力レベルは同じモデルに対して独自のキャッシュを持ちます。セッション中に変更すると、リクエスト全体が再計算され、Claude Code は変更を適用する前に確認を求めます。以下の努力レベルの変更を参照してください。

キャッシュが存在する場所

キャッシングはサーバー側で行われ、モデルを提供するインフラストラクチャで行われます。その場所は、認証方法によって異なります。

• API キー、Claude サブスクリプション、またはClaude Platform on AWS: キャッシュは Anthropic のインフラストラクチャに存在し、Claude API を通じてアクセスされます
• Bedrock または Vertex AI: キャッシュはクラウドプロバイダーのサービングインフラストラクチャに存在します
• Foundry: リクエストは Anthropic のインフラストラクチャにルーティングされます
• カスタム ANTHROPIC_BASE_URL またはLLM gateway: キャッシュはリクエストが転送される場所に存在し、キャッシングが機能するかどうかはゲートウェイに依存します

各プロバイダーが保存および処理するものについては、データ使用を参照してください。キャッシュがどこに存在するかに関わらず、エントリは非アクティブ期間後に期限切れになり、以下のキャッシュライフタイムは TTL とそれを延長する方法について説明します。

キャッシュを無効にするアクション

これらのアクションにより、次のリクエストはキャッシュの一部またはすべてをミスします。1 回限りの遅く、より高価なターンが表示され、その後、新しいプリフィックスがキャッシュされます。ほとんどは、コストがあることを知ったら、タスク中に回避可能です。モデル切り替えは、その後の遅いターンに気付くまで無料に感じることができます。

• モデルの切り替え
• 努力レベルの変更
• 高速モードの有効化
• MCP サーバーの接続または切断
• プラグインの有効化または無効化
• ツール全体の拒否
• 会話のコンパクト化
• Claude Code のアップグレード

モデルの切り替え

各モデルは独自のキャッシュを持ちます。/model で切り替えると、次のリクエストはコンテンツが同じであっても、キャッシュヒットなしで会話履歴全体を読み取ります。

opusplan モデル設定は、Plan Mode 中に Opus に、実行中に Sonnet に解決されるため、各 Plan Mode トグルはモデル切り替えであり、新しいキャッシュを開始します。

Fable 5 での自動モデルフォールバックもモデル切り替えです。安全性分類器がリクエストにフラグを立てると、Claude Code はデフォルトの Opus モデルで再実行し、セッションはそこで続行されます。

努力レベルの変更

キャッシュは努力レベルとモデルの両方によってキー付けされるため、/effort で切り替えると、次のリクエストはキャッシュヒットなしで会話履歴全体を読み取ります。会話が開始されたら、Claude Code はキャッシュを無効にする努力レベルの変更を適用する前に確認ダイアログを表示します。モデルのデフォルトを明示的に設定するなど、既に有効な同じレベルに解決される変更は、ダイアログをスキップしてキャッシュを保持します。

高速モードの有効化

高速モードを有効にすると、キャッシュキーの一部であるリクエストヘッダーが追加されるため、次のリクエストはキャッシュヒットなしで会話履歴全体を読み取ります。これらのキャッシュされていない入力トークンは高速モードレートで課金されます。これが、セッションの開始時に有効にする方が、長いセッションの深くで有効にするよりもコストが低い理由です。非 Opus モデルから高速モードを有効にすると、モデルも切り替わります。これにより、独自に新しいキャッシュが開始されます。

コストはキャッシュごとに 1 回適用されます。最初の高速モードターンの後、Claude Code はヘッダーを送信し続け、リクエストの速度設定のみを変更します。これはキャッシュキーの一部ではありません。高速モードをオフにする、レート制限後の標準速度への自動フォールバック、および後で再度有効にすることはすべてキャッシュを保持します。/clear と /compact はこれをリセットします。これらはとにかくそれらのポイントでキャッシュを再構築するためです。

MCP サーバーの接続または切断

ツール定義はシステムプロンプトレイヤーに存在するため、リクエスト間でリクエスト内のツール定義のセットが変更されるとキャッシュが無効になります。advisor ツールのトグルは例外です。その定義はキャッシュブレークポイントの後に存在するため、/advisor を有効化または無効化してもキャッシュされたプリフィックスはそのままです。MCP サーバーの変更がこれを行うかどうかは、そのツールがツール検索によって遅延されるか、プリフィックスに読み込まれるかによって異なります。

• 遅延ツール、サポートされているモデルのデフォルト：サーバーの接続、切断、またはツールリストの変更は、新しいコンテンツのみを追加し、既にキャッシュされているものを妨害しません。
• プリフィックスに読み込まれるツール：それらへの変更はキャッシュを無効にします。これはツール検索が利用不可または無効な場合に発生します。Haiku モデル、Vertex AI、またはカスタム ANTHROPIC_BASE_URL ゲートウェイなど。また、alwaysLoadとマークされたサーバーまたはツール、およびしきい値ベースの読み込みによって前もって保持される定義についても発生します。

ツールがプリフィックスに読み込まれる場合、無効化の最も一般的な原因は、セッション中にサーバーが接続または切断されることです。これはアクションなしで発生する可能性があります。stdio サーバーのプロセスが終了するか、HTTP セッションが期限切れになるか、サーバーが一時的な障害後に自動的に再接続します。接続されたサーバーは、ツールリストを変更する動的ツール更新をプッシュすることもできます。

MCP 設定を編集しても、それ自体ではキャッシュは変更されません。新しい設定は再起動後にのみ有効になります。これは、サーバーが接続または切断されるときです。

プラグインの有効化または無効化

プラグインは複数のコンポーネントタイプをバンドルし、変更のコストはプラグインが提供するコンポーネントによって異なります。Skills、commands、agents、hooks、LSP サーバー、monitors、themes は決してキャッシュを無効にしません。リクエストに追加するものはすべて既存の会話の後に追加されるため、次のリクエストは新しいコンテンツに対して支払いますが、それでもその前のすべてをキャッシュから読み取ります。

例外はMCP サーバーを提供するプラグインです。1 つを有効化または無効化することは、MCP サーバーの接続または切断と同じルールに従います。サーバーのツールが遅延されるとキャッシュが保持され、プリフィックスに読み込まれると次のリクエストは会話全体を再度読み取ります。

プラグインの変更は、/reload-pluginsを実行するか、新しいセッションを開始するときに適用されます。コスト（追加されたアナウンスメントまたは完全な再読み取り）は、/plugin install、/plugin enable、または /plugin disable を実行するときではなく、リロード後の最初のターンに表示されます。{/* min-version: 2.1.163 */}v2.1.163 以降、リロードが完全な再読み取りをトリガーする場合、/reload-plugins は警告を表示し、リロードを適用しません。--force を渡して、とにかく適用します。

セッションの前半で有効にしたプラグインを無効にすると、以前のリクエスト形状が復元されます。そのプリフィックスがまだキャッシュライフタイム内にある場合、次のリクエストは再構築するのではなく、古いキャッシュエントリを読み取ります。

ツール全体の拒否

Bash や WebFetch のような裸のツール名を拒否ルールとして追加すると、そのツールは Claude のコンテキストから完全に削除されます。組み込みツール定義はシステムプロンプトレイヤーに読み込まれるため、これらのルールの 1 つを追加または削除するとセッション中にキャッシュが無効になります。変更は、/permissions を通じて追加するか、設定ファイルを直接編集するかにかかわらず、次のターンで有効になります。

ツール名位置で一致する拒否ルールのみがこの効果を持ちます。裸のツール名、同等の Bash(*) 形式、またはツール名グロブ（"*" など）。"mcp__*" のような MCP ツールのみに一致するグロブは、それらのツールを同じ方法で削除しますが、一致したツールが遅延されている場合、デフォルトではキャッシュはそのままです。遅延定義はキャッシュされたプリフィックスに含まれていなかったため。Bash(rm *) のようなスコープ付き拒否ルール、およびすべての許可ルールと質問ルールは、Claude が見るツールを変更しません。Claude Code は Claude が呼び出しを試みるときにそれらをチェックし、プリフィックスをそのままにします。

会話のコンパクト化

コンパクト化は、メッセージ履歴を要約に置き換えます。設計上、これは会話レイヤーを無効にします。次のリクエストには、古いものとプリフィックスを共有しない新しい、より短い履歴があるためです。Claude Code はシステムプロンプトレイヤーを再利用し、ディスクからプロジェクトコンテキストを再度読み込みます。これは、セッション開始以降 CLAUDE.md とメモリが変更されていない場合にのみキャッシュヒットします。

要約を生成するために、Claude Code は、会話と同じシステムプロンプト、ツール、履歴を持つ 1 回限りのリクエストを送信し、最終ユーザーメッセージとして要約命令を追加します。プリフィックスを共有するため、そのリクエストは既存のキャッシュを読み取り、完全な履歴を再処理しません。コンパクト化の時間のほとんどは、キャッシュミスではなく、要約の生成に費やされます。その後のターンは、はるかに短い要約に対してのみ会話キャッシュを再構築するため、コンパクト化後のターンは遅い部分ではありません。

Claude Code のアップグレード

新しい Claude Code バージョンは通常、システムプロンプトまたはツール定義を更新するため、アップグレード後の最初のリクエストはキャッシュを最初から再構築します。自動更新は新しいバージョンをバックグラウンドでダウンロードしますが、次の起動時に適用され、セッション中には適用されません。そのため、セッション中のサプライズではなく、再起動後のキャッシュなしの最初のターンとして表示されます。DISABLE_AUTOUPDATER=1 を設定して、アップグレードが適用されるタイミングを制御します。

キャッシュを保持するアクション

これらのアクションは、会話の最後に追加するか、リクエストにまったく触れません。CLAUDE.md の編集や出力スタイルの変更など、一部は、設定変更が再起動を待つ理由でもあります。

• リポジトリ内のファイルの編集
• セッション中の CLAUDE.md の編集
• 出力スタイルの変更
• 権限モードの変更
• スキルとコマンドの呼び出し
• /recap の実行
• 会話の巻き戻し
• サブエージェントの生成

リポジトリ内のファイルの編集

ファイルコンテンツがコンテキストに入るのは Claude が読むときだけであり、読み取りは会話に追加されます。Claude が以前読んだファイルを編集しても、履歴内の以前の読み取りは遡及的に変更されません。代わりに、Claude Code はファイルが変更されたことを示す <system-reminder> を追加し、必要に応じて Claude が再度読み取ります。

セッション中の CLAUDE.md の編集

プロジェクトルートとユーザーレベルの CLAUDE.md ファイルはセッション開始時に 1 回読み取られ、メモリに保持されます。セッション中に編集してもキャッシュは無効になりませんが、編集も適用されません。Claude はセッション開始時に読み込まれたバージョンで作業を続けます。新しいコンテンツは次の /clear、/compact、または再起動時に読み込まれます。

サブディレクトリ内のネストされた CLAUDE.md ファイルとpaths: frontmatter を持つルールは、Claude が最初に一致するファイルを読むときに後で読み込まれます。読み込まれる前に編集すると、有効になります。読み込まれた後、コンテンツは会話履歴の一部であるため、セッション中の編集は遡及的に変更されません。

出力スタイルの変更

出力スタイルはシステムプロンプトの一部であり、Claude Code はセッション開始時に 1 回読み取ります。/config または outputStyle 設定を使用してセッション中に変更してもキャッシュは無効になりませんが、変更も適用されません。Claude はセッション開始時に読み込まれたスタイルを使用し続けます。新しいスタイルは次の /clear または再起動時に読み込まれます。

権限モードの変更

権限モード間の切り替え（デフォルトから編集受け入れへなど）は、システムプロンプトまたはツール定義を変更しないため、モード変更はキャッシュセーフです。例外は、opusplan モデル設定を使用した Plan mode です。これは、Plan mode に入るか出るときにモデルを Opus と Sonnet の間で切り替えます。これにより、モード切り替えはモデル切り替えになります。

スキルとコマンドの呼び出し

スキルとコマンドは、呼び出しポイントでユーザーメッセージとして命令を注入します。会話内の以前のものは何も変わりません。

`/recap` の実行

/recapは、ターミナルに表示するための要約を生成します。/compact とは異なり、メッセージ履歴を置き換えるのではなく、コマンド出力として要約を追加するため、キャッシュされたプリフィックスはそのままです。

会話の巻き戻し

/rewindは、会話を以前のターンに切り詰めます。残りの履歴は、その時点でキャッシュが構築されたのと同じコンテンツであり、システムプロンプトとプロジェクトコンテキストレイヤーは変更されないため、次のリクエストは以前のキャッシュエントリにヒットします。それ以降のすべてのターンはそのプリフィックスを通じて読み取られており、元のターンが TTL より長い前であっても、エントリを温かく保ちました。

会話と一緒にファイルチェックポイントを復元しても、キャッシュに対する個別の効果はありません。ファイルコンテンツがコンテキストに入るのは Claude が読むときだけであり、リポジトリ内のファイルの編集と同じです。

キャッシュライフタイム

キャッシュされたプリフィックスは、非アクティブ期間後に期限切れになります。キャッシュにヒットするすべてのリクエストはタイマーをリセットするため、作業を続ける限りキャッシュは温かく保たれます。十分に長いギャップの後、次のリクエストは完全な入力を再計算し、キャッシュを再確立します。これが、立ち去った後の最初のターンが顕著に遅い理由です。

Time to Live（TTL）は、キャッシュが生き残るギャップの長さを制御します。API は 2 つを提供します。5 分の TTL と、より長い休憩を通じてキャッシュを温かく保つ1 時間の TTLですが、キャッシュ書き込みをより高いレートで請求します。Claude Code は認証方法に基づいて TTL を選択し、環境変数でオーバーライドできます。

Claude サブスクリプション上

Claude サブスクリプションでは、Claude Code は 1 時間の TTL を自動的にリクエストします。使用量はトークンごとに請求されるのではなく、プランに含まれるため、より長い TTL は追加費用がかからず、キャッシュが温かく保たれる期間にのみ影響します。

プランの使用量制限を超えており、Claude Code が使用クレジットを引き出している場合、その使用量に対して請求されるため、Claude Code は自動的に TTL を 5 分に低下させます。

API キーまたはサードパーティプロバイダー上

API キー、Bedrock、Vertex、Foundry、または Claude Platform on AWS では、トークンごとのレートを支払うため、TTL はデフォルトでより安い 5 分のままです。1 時間の TTLにオプトインするには、ENABLE_PROMPT_CACHING_1H=1 を設定します。

Bedrock では、プロンプトキャッシングサポート、最小キャッシュ可能プリフィックス長、および 1 時間の TTL 可用性はすべてモデルによって異なります。キャッシュトークン数がゼロのままの場合は、Bedrock ドキュメントのサポートされているモデル、リージョン、制限を確認してください。

TTL をオーバーライドする

FORCE_PROMPT_CACHING_5M=1 を設定して、認証に関わらず 5 分の TTL を強制します。これは、キャッシング動作をデバッグする場合、2 つの TTL を比較する場合、または管理設定で設定された ENABLE_PROMPT_CACHING_1H をオーバーライドする場合に便利です。

キャッシュスコープ

Claude Code では、キャッシュは事実上 1 つのマシンとディレクトリにスコープされます。システムプロンプトは、作業ディレクトリ、プラットフォーム、シェル、OS バージョン、および自動メモリパスを埋め込むため、異なるディレクトリの 2 つのセッションは異なるプリフィックスを構築し、互いのキャッシュをミスします。これには、同じリポジトリの worktrees が含まれます。各 worktree は独自の作業ディレクトリを持つためです。

同じディレクトリで並行して実行するセッションは、一致するプリフィックスを構築し、互いのキャッシュを読み取ります。順序付きセッションは、起動時の git ステータススナップショットが一致する場合にのみプリフィックスを共有します。システムプロンプトはブランチと最近のコミットもキャプチャするためです。

基礎となる API キャッシュはより広いです。キャッシュは組織間で分離され、一部のプロバイダーでは、組織内のワークスペース間で分離されます。これらの境界内で、同じモデルとプリフィックスを持つ 2 つのリクエストは同じキャッシュを読み取ります。自動化されたプロセスのフリートを実行する Agent SDK 呼び出し元については、ユーザーとマシン間でプロンプトキャッシングを改善を参照して、システムプロンプトのマシンごとのセクションを抑制し、マシン間でキャッシュを共有します。

キャッシュパフォーマンスを確認する

キャッシュパフォーマンスは、API がすべての応答で報告する 2 つのトークン数として表示されます。最も直接的な方法は、current_usage オブジェクトを読み取るstatusline スクリプトを監視することです。

読み取りから作成への比率が高いほど、キャッシングが機能しています。作成がターンごとに高いままの場合、プリフィックスで何かが変更されています。キャッシュを無効にするアクションセクションは、通常の原因をリストします。

組織全体の可視性については、OpenTelemetry エクスポーターはユーザーとセッションごとにキャッシュ読み取りと作成トークンを報告します。メトリックとイベント属性リファレンスについては、使用状況の監視を参照してください。

サブエージェントとキャッシュ

サブエージェントは、親とは別に、独自のシステムプロンプトとツールセットを持つ独自の会話を開始します。独自のキャッシュを構築し、最初の呼び出しでキャッシュヒットなしで開始し、独自のターン全体で温まります。サブエージェントは、サブスクリプション上でも 5 分の TTL を使用します。自動 1 時間の TTL はメイン会話に適用されるためです。

親のキャッシュは影響を受けません。親の側から、サブエージェントの呼び出しと結果は会話に追加され、親のプリフィックスはそのままです。

一方、フォークは、親のシステムプロンプト、ツール、会話履歴を正確に継承するため、最初のリクエストは親のキャッシュを読み取ります。会話のコンパクト化で説明されているコンパクト化要約呼び出しは、同じプリフィックス共有アプローチを使用します。

プロンプトキャッシングを無効にする

キャッシング動作を特定のモデルまたはプロバイダーでデバッグするときは、キャッシングを無効にすることが時々役立ちます。オフにするには、これらの環境変数のいずれかを 1 に設定します。

組織全体でキャッシングポリシーを設定するには、これらのいずれかまたは TTL 変数を 管理設定の env ブロックに入れます。通常の使用では、キャッシングを有効のままにしてください。

関連リソース

• Claude Code の構築から学んだ教訓: プロンプトキャッシングがすべて: Plan mode、遅延ツール読み込み、コンパクト化の設計根拠
• コンテキストウィンドウを探索: コンテキストに読み込まれるもの、いつ読み込まれるか
• トークン使用量を削減: コンテキストサイズを管理するためのキャッシング以外の戦略
• コストを追跡および削減: Agent SDK 呼び出し元のキャッシュトークン追跡と TTL 設定
• プロンプトキャッシング: 基礎となる API メカニズム、ブレークポイント、価格設定