SpyBara
Go Premium

prompt-caching.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 67 additions and 67 deletions.

2026
Tue 6 23:59 Wed 7 23:59 Tue 13 23:57 Wed 14 22:58 Sat 17 23:57 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Sun 25 23:58 Thu 29 23:57

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

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

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

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

キャッシュの構成方法

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

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

4 つのターンが成長する水平バーとして表示されています。各ターンのリクエストには、前のターンのすべてと、最後に追加された最新の交換が含まれています。ターン 2 と 3 では、変更されていないプリフィックスがキャッシュから読み込まれ、新しい交換のみが処理されます。ターン 4 では、システムプロンプトが変更されたため、プリフィックスが一致しなくなり、リクエスト全体が再処理されてキャッシュに書き込まれます。

プリフィックスマッチングを最大限に活用するために、Claude Code は各リクエストを整理して、ターン間で変更されることが少ないコンテンツを最初に配置します。

レイヤー コンテンツ 変更される場合
システムプロンプト コア命令、ツール定義 読み込まれたツール定義のセットが変更される
プロジェクトコンテキスト CLAUDE.md、自動メモリ、スコープなしルール セッション開始時、または /clear または /compact の後
会話 メッセージ、Claude の応答、ツール結果 毎ターン

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

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

レイヤーテーブルに表示されないが、キャッシュされたままになるものに影響する 2 つの設定があります。

  • モデル：各モデルには独自のキャッシュがあります。モデルを切り替えると、コンテンツが同じであってもリクエスト全体が再計算されます。以下の モデルの切り替え を参照してください。
  • effort レベル：ほとんどのモデルでは、各 effort レベルには独自のキャッシュがあるため、セッション中に effort を変更するとリクエスト全体が再計算されます。API キーまたは Claude サブスクリプションを使用した Opus 5.5、Sonnet 5.5、Haiku 5.5、および Fable 5.1 では、デフォルトではキャッシュはそのままです。以下の effort レベルの変更 を参照してください。

[!TIP]

セッションの最初にモデルと effort レベルを選択し、/compact はタスク間の自然な区切りまで取っておいてください。タスク中に行う変更が少ないほど、キャッシュヒット率が高くなります。

キャッシュの場所

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

  • API キー、Claude サブスクリプション、または Claude Platform on AWS：キャッシュは Anthropic のインフラストラクチャに存在し、Claude API を通じてアクセスされます。
  • Amazon Bedrock または Google Cloud の Agent Platform：キャッシュはクラウドプロバイダーのサービングインフラストラクチャに存在します。
  • Microsoft Foundry：デプロイの ホスティングオプション によって異なります。Hosted on Azure のデプロイは Azure インフラストラクチャで提供されます。Hosted on Anthropic のデプロイは Anthropic のインフラストラクチャで提供されます。
  • カスタム ANTHROPIC_BASE_URL または LLM ゲートウェイ：キャッシュはリクエストが転送される場所に存在し、キャッシングが機能するかどうかはゲートウェイに依存します。

Claude Code は会話中にシステムコンテキスト（ファイル変更通知など）も追加し、CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS を設定しない限り、すべてのプロバイダーと接続でそのブロックをキャッシング用にマークします。その場合、そのブロックはキャッシュなしで送信されます。

プロバイダー独自のエンドポイント、Amazon Bedrock とその Mantle エンドポイント、Google Cloud の Agent Platform、および Microsoft Foundry では、Claude API と同じ方法でブロックをキャッシュします。

リクエストが LLM ゲートウェイ、カスタム ANTHROPIC_BASE_URL、または ANTHROPIC_BEDROCK_BASE_URL などのクラウドプロバイダーベース URL の上書きを通過する場合、キャッシュされたままになるものは、ゲートウェイが Claude Code が送信する cache_control マーカー をどのように処理するかに依存します。

  • 変更されずに転送する：ブロックと会話は、プロバイダー独自のエンドポイントと同じようにキャッシュされます。
  • cache_control という名前の 400 エラーでマークされたリクエストを拒否する：Claude Code はマーカーをブロックから最後の会話メッセージに移動させてリクエストを再送信し、Claude Code が終了するまでそこに保持します。ブロックはキャッシュなし入力として請求されます。会話はキャッシュされたままです。
  • マーカーを削除して成功を返す：会話履歴全体は、毎ターン、キャッシュなし入力として請求されます。ブロック形式のシステムコンテンツをプレーン文字列に変換するゲートウェイは、同じ方法でマーカーをドロップします。

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

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

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

モデルの切り替え

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

ターミナルで /model を実行すると、キャッシュがまだ温かく、新しいモデルが最後の応答を生成したモデルではない場合にのみ、Claude Code はスイッチの確認を求めます。キャッシュは、Claude Code がこの会話で最後にリクエストを送信した後、または Claude が最後に応答した後、1 つの キャッシュ TTL の間、温かいままです。その時間が経過すると、キャッシュは期限切れになるため、Claude Code は確認なしで切り替えます。

v2.1.238 より前では、Claude Code はキャッシュ TTL をチェックせず、キャッシュが期限切れになった後でも確認を求めていました。

PreModelSwitch フック を使用して、この確認を必須にするか、スキップすることもできます。

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

Fable モデル、Opus 5.5、Sonnet 5.5、および Opus 5 の 自動モデルフォールバック もモデルスイッチです。安全分類器がフォールバックモデルを持つカテゴリーでリクエストを警告すると、Claude Code はそのモデルでリクエストを再実行し、セッションはそこで続行されます。

スキルまたはコマンドのフロントマターがセッションの現在のモデル以外の model を指定する場合、そのターンもモデルスイッチです。次のリクエストはキャッシュヒットなしで会話履歴全体を読み込みます。セッションモデルは次のプロンプトで再開されます。context: fork スキルは、代わりに フォークされたサブエージェントのモデル を設定します。

effort レベルの変更

ほとんどのモデルでは、セッション中に effort レベル を変更すると、次のリクエストはキャッシュヒットなしで会話履歴全体を読み込みます。キャッシュがまだ温かい間、Claude Code は最初に変更を確認するよう求めます。

API キーまたは Claude サブスクリプションを使用する Opus 5.5、Sonnet 5.5、Haiku 5.5、および Fable 5.1 では、effort を変更してもキャッシュが保持され、Claude Code は確認なしに新しいレベルを適用します。これは Amazon Bedrock、Google Cloud の Agent Platform、または Claude アプリゲートウェイ には適用されません。また、CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS を設定した場合、または組織が HIPAA 構成を持つ場合にも適用されません。

v2.1.260 より前では、API キーまたは Claude サブスクリプションを使用する Fable 5.1 の effort を変更すると、キャッシュも無効化されていました。

fast mode のオン

fast mode を有効にすると、キャッシュキーの一部であるリクエストヘッダーが追加されるため、Claude Code が fast mode をオンにして送信する最初のリクエストはキャッシュヒットなしで会話履歴全体を読み込みます。Claude Code はターンの開始時にそのヘッダーを 1 回設定し、ターン全体でそれを保持するため、Claude が作業中に fast mode をオンにすると、ヘッダーからのキャッシュミスは次のターンの最初のリクエストで発生します。これらのキャッシュされていない入力トークンは fast mode の料金 で請求されます。これが、セッションの開始時に fast mode をオンにすることが、長いセッションの深くでオンにすることより低コストである理由です。現在のモデルが fast mode をサポートしていない場合、fast mode を有効にすると モデルも切り替わり、そのスイッチ自体が実行中のターンの次のリクエストから新しいキャッシュを開始します。

コストは会話ごとに 1 回適用されます。最初の fast mode ターンの後、Claude Code はヘッダーを送信し続け、キャッシュキーの一部ではないリクエストの速度設定のみを変更します。fast mode をオフにすること、レート制限後の標準速度への自動フォールバック、およびその後にオンに戻すことはすべてキャッシュを保持します。セッション中に 使用クレジットが不足した 場合、Claude Code は拒否された各 fast mode リクエストを同じ方法で標準速度で再試行するため、このフォールバックもキャッシュを保持します。/clear と /compact はこれをリセットします。これらはいずれにしてもその時点でキャッシュを再構築するためです。

MCP サーバーの接続または削除

ツール定義はシステムプロンプトレイヤーに存在するため、リクエスト内のツール定義のセットがターン間で変更されるとキャッシュが無効化されます。アドバイザーツール の切り替えは例外です。その定義はキャッシュブレークポイントの後に存在するため、/advisor を有効または無効にするとキャッシュされたプレフィックスはそのまま保持されます。MCP サーバー の変更がこれを行うかどうかは、ツール検索 がセッションの MCP ツールを遅延させるかどうかによります。これはサポートされているモデルのデフォルトです。

  • ツール遅延: Claude Code は会話の最初のリクエストからツールリストを保持するため、セッション中にサーバーが接続または切断されても、既にキャッシュされているものは何も影響を受けません。最初のリクエスト後に接続を完了するサーバーは、Claude がオンデマンドで読み込む遅延定義としてそのツールを提供します。
  • ツール事前読み込み: 定義を追加するとキャッシュが無効化され、意図的に削除してもそうなります。これは、ツール検索が オフまたは利用不可 である場合に適用されます。例えば、次のような場合です。
    • Opus 4.5、Sonnet 4.5、Haiku 4.5 より前の Google Cloud の Agent Platform モデル
    • Microsoft Foundry の Azure でホストされているデプロイ で、Claude Code がそのデプロイがツール検索を拒否することを検出した場合

ツール検索がない場合、セッション中のサーバー変更がキャッシュを無効化するかどうかは、何が変更されたかによります。各変更について、このテーブルはキャッシュが保持されるかどうか、および次のリクエストのツール定義に何が起こるかを示します。

セッション中の変更 キャッシュ 次のリクエストのツール定義
サーバーが接続する、または 動的ツール更新 がツールを追加する 無効化 新しい定義が追加される
サーバーがユーザーの操作なしで切断される（例えば、stdio サーバーのプロセスが終了する） 保持 サーバーの定義は変更されないままです。そのツールの 1 つへの呼び出しは、実行される代わりにエラーを返します。ただし、Claude Code がその呼び出しのために サーバーを再度起動する 場合を除きます
リモートサーバーが接続切断後に 自動的に再接続 する 保持（サーバーが再接続中に送信されたリクエストが WaitForMcpServers ツールを追加する場合を除き、その場合は 1 回無効化） サーバーの定義は変更されないままです。サーバーが再接続中に送信されたリクエストは、会話がまだそれをリストしていない場合に WaitForMcpServers を追加でき、ツールはその後会話の残りの間リストされたままになります
拒否ルール を使用するか、/mcp でサーバーを無効にするなど、意図的にツールを削除する 無効化 定義が削除される

ツールがプレフィックスに読み込まれる会話を再開する場合、その MCP サーバーの 1 つは最初のリクエストが送信されるときにまだ接続中である可能性があります。トランスクリプトがそのサーバーのツール定義を記録した場合、そのリクエストは記録されたとおりにそれらを含むため、サーバーが同じツールで接続を完了しても変更されません。

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

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

プラグイン を有効または無効にする場合、変更のコストはプラグインが提供するコンポーネントタイプによって異なります。以下のケースは各コンポーネントタイプ、Claude Code が変更を適用するタイミング、および同じセッション内でプラグインを再度無効にするときに何が起こるかをカバーしています。

キャッシュを保持するプラグインコンポーネント

Claude Code は、プラグインのスキル、コマンド、エージェント、フック、モニター、またはテーマのキャッシュを無効化することはありません。既存の会話の後にそれらのコンテンツを追加するため、次のリクエストはそのコンテンツに対して支払い、その前のすべてをキャッシュから読み込みます。

MCP サーバーを提供するプラグイン

MCP サーバー を提供するプラグインを有効または無効にする場合、Claude Code は MCP サーバーを接続または削除 するときと同じルールに従います。

コード インテリジェンス プラグイン

コード インテリジェンス プラグイン を有効にすると、Claude は LSP ツール を取得します。

プラグイン変更が適用されるタイミング

/plugin メニューで行った変更は /reload-plugins を通じて行われます。これは Claude Code がメニューを閉じるときに実行します。コストは、追加されたアナウンスメントまたは完全な再読み込みのいずれかで、変更が適用された後の最初のターンで支払われます。Claude Code は変更を独自に適用することもできます。

  • command ソースを持つプラグインの場合、Claude Code は プラグイン自体を再読み込みできます。
  • /plugin インターフェースからプラグインをインストール する場合、Claude Code はインストール中にそれを有効化できます。インストール概要は、それが行われたかどうかを示します。
  • v2.1.246 以降で /cd でセッションを移動 する場合、Claude Code は新しいディレクトリの設定が有効にするプラグインを移動の一部として適用します。/reload-plugins を保留させる完全な再読み込みの警告は表示されません。
  • 対話セッションでは、--plugin-dir で渡した プラグインのフォルダ 内のプラグインを追加または削除する場合、変更は直ちに適用されます。それを適用すると完全な再読み込みがトリガーされる場合、Claude Code は代わりに変更を保留し、/reload-plugins を実行するよう通知を表示します。Claude Code v2.1.265 以降が必要です。

/reload-plugins が実行され、再読み込みが完全な再読み込みをトリガーする場合、Claude Code は警告を表示し、再読み込みを適用しません。それでも適用するには /reload-plugins --force を実行します。

/reload-plugins は、デスクトップアプリ、Agent SDK、および -p を使用した非対話モード など、対話的なターミナルのないセッションでも、セッションに直接入力した場合に実行されます。Claude Code v2.1.260 以降が必要です。

これらのセッションでは、再読み込みはプラグイン MCP サーバー変更を除くすべてを適用します。これらは 次のセッションで有効になり、セッション中に完全な再読み込みのコストが発生することはありません。

セッション内で有効にしてから無効にするプラグイン

セッションの前半で有効にしたプラグインを無効にする場合、Claude Code は以前のリクエスト形状を復元します。そのプレフィックスがまだその キャッシュ有効期間 内にある場合、次のリクエストは再構築する代わりに古いキャッシュエントリを読み込みます。

ツール全体の拒否

Bash や WebFetch のような裸のツール名を 拒否ルール として追加する場合、Claude は /permissions を通じてルールを追加するか、設定ファイルを直接編集 するかに関わらず、次のリクエストからそのツールを呼び出すことができません。これには、ターンの途中で /permissions を通じて追加するルールも含まれます。

ツール検索 がアクティブな場合（サポートされているモデルのデフォルト）、リクエストのツール定義は変更されず、キャッシュされたプレフィックスは生き残ります。ツール検索が利用不可または無効な場合、Claude Code は定義を次のリクエストから削除し、キャッシュを無効化し、ルールを後で削除してもそうなります。

この方法でツールをブロックするのは、ツール名の位置で一致する拒否ルールのみです。裸のツール名、同等の Bash(*) フォーム、または ツール名グロブ （"*" など）です。"mcp__*" のような MCP ツールのみに一致するグロブは、同じ方法でそれらのツールをブロックします。Bash(rm *) のようなスコープ付き拒否ルール、およびすべての許可ルールと確認ルールは、Claude が見るツールを変更しません。Claude Code は Claude が呼び出しを試みるときにそれらをチェックし、プレフィックスはそのまま保持されます。

会話のコンテキスト圧縮

コンテキスト圧縮 はメッセージ履歴を概要に置き換えます。設計上、これは会話レイヤーを無効化します。次のリクエストには、古いものとプレフィックスを共有しない新しい、より短い履歴があるためです。システムプロンプトレイヤーとプロジェクトコンテキストレイヤーは、キャッシュされたままにできます。

  • システムプロンプト: 次のリクエストはこのレイヤーをキャッシュから読み込みます。ただし、再開された会話 が現在では古くなったシステムプロンプトを保持している場合を除きます。その会話が初めて圧縮されるとき、Claude Code は現在のプロンプトに切り替え、次のリクエストはこのレイヤーのキャッシュを 1 回再構築します。
  • プロジェクトコンテキスト: Claude Code はこのレイヤーをディスクから再読み込みします。次のリクエストがこのレイヤーをキャッシュから読み込むのは、CLAUDE.md とメモリがセッション開始以降変更されていない場合のみです。

概要を生成するために、Claude Code は別のリクエストを送信します。このリクエストには、会話のシステムプロンプト、ツール、および要約対象の履歴がそのまま含まれます。末尾には要約の指示が付きます。キャッシュが温かい間、そのリクエストはキャッシュからプレフィックスを読み込みます。そのため、セッション中の /compact はコンテキストサイズが示唆するコストの一部で済み、ほとんどの時間を概要の生成に費やします。

キャッシュ有効期間 より長い休止の後、読み込むキャッシュは残っていないため、要約リクエストはその履歴をキャッシュされていない入力として再処理します。これが /compact が 古いセッションを再開 するときに最もコストがかかる理由です。温かいケースと冷たいケースの両方で、圧縮後のターンは、はるかに短い概要のみのために会話キャッシュを再構築するため、そのターンは遅い部分ではありません。

[!TIP]

コンテキスト圧縮は、破棄するコンテキストがもう必要ないコンテンツである場合に有利に働きます。そのオーバーヘッドが発生するタイミングを選択するには、自動圧縮がタスク中にトリガーされるのを待つのではなく、タスク間などの作業の自然な区切りで /compact を実行します。完全に放棄したい方向に進んでしまった場合は、代わりに /rewind で以前のターンに戻してください。巻き戻しは、圧縮のように新しいプレフィックスを構築するのではなく、既にキャッシュされているプレフィックスまで切り詰めます。

1 時間の TTL が適用されているターミナルセッションで長い会話をアイドル状態のままにすると、Claude Code はキャッシュが期限切れになる少し前にその会話を圧縮することがあります。アイドル時の圧縮をオフにするには、idleCompaction を false に設定します。これには Claude Code v2.1.290 以降が必要です。

多くの画像の蓄積

API は各リクエストが運べる画像と PDF の数を制限します。現在の数については、API ドキュメントの リクエスト制限 を参照してください。Claude Code はまた、リクエスト内の画像と PDF の合計サイズを制限するため、大きなスクリーンショットは小さいものより少ない画像数で制限に達します。

次のリクエストがいずれかの制限を超える場合、Claude Code は送信する内容から最も古い画像と PDF のバッチを削除します。これにより、再度削除する必要があるまでさらに多くの余地が確保されます。Claude はもう削除された画像を見ることができません。Claude がそれらの 1 つを再度必要とする場合、再度共有してください。

画像を削除すると、それらを保持していたメッセージが変更されるため、次のリクエストはそれらのメッセージの最も早いものから会話を再処理します。Claude Code はバッチ単位で削除するため、新しいスクリーンショットごとに 1 つではなく、バッチごとに 1 つの遅いターンが表示されます。

Claude Code のアップグレード

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

[!NOTE]

アップグレード前に開始した会話を再開するコストについては、セッションの再開 を参照してください。

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

これらのアクションは、会話の末尾に追加されるか、リクエストにまったく触れません。CLAUDE.md の編集など、その中には /clear、/compact、または再起動までキャッシュを保持する理由が、変更が実行中のセッションに到達しない理由と同じであるものもあります。

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

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

セッション中に CLAUDE.md を編集する

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

サブディレクトリ内のネストされた CLAUDE.md ファイルとpaths: フロントマターを持つルールは、後で必要に応じて読み込まれます。読み込まれる前に自分で編集した場合は、その編集が反映されます。読み込まれた後、コンテンツは会話履歴の一部であるため、セッション中の編集は遡及的にそれを変更しません。

権限モードを変更する

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

出力スタイルを変更する

セッション中に /output-style、/config、または outputStyle 設定で出力スタイルを切り替えると、Claude は次のメッセージから新しいスタイルを使用します。Claude Code は新しいスタイルの指示をメッセージとして会話に配信するため、そのリクエストはシステムプロンプトと以前の会話をキャッシュから読み取ります。

v2.1.251 より前では、セッション中のスタイル切り替えはキャッシュを保持していましたが、/clear を実行するか新しいセッションを開始するまで適用されませんでした。

スキルとコマンドを呼び出す

スキルとコマンドは、呼び出しポイントでユーザーメッセージとして指示を挿入します。会話内の以前のものは何も変わりません。frontmatter で model という名前を付けたスキルまたはコマンドは、そのターンのモデル切り替えになる可能性があります。

/recap を実行する

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

会話を巻き戻す

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

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

セッションの再開

セッションを再開する場合、Claude Code は会話全体を再度送信し、リクエストはキャッシュから、そのプレフィックスの変更されていない部分で、かつ キャッシュの有効期限内にある部分を読み込みます。このページの上部にあるレイヤーテーブルは、各レイヤーで何が変わるかを示しています。

システムプロンプトは Claude Code のアップグレード後、または再開時に異なる --append-system-prompt テキストがある場合に変更されます。デフォルトでは、再開された会話は開始時のシステムプロンプトを保持するため、その履歴は同じプロンプトの背後にあり、会話がコンパクト化されるか新しい会話で変更が有効になります。再開されたセッションのシステムプロンプトフラグは Claude Code がすべてのリクエストでプロンプトを再構築する場合をカバーしています。

キャッシュライフタイム

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

Time to Live（TTL）は、キャッシュが生き残るギャップの長さを制御します。API は 2 つを提供します。5 分の TTL と、より長い休止を通じてキャッシュを温かく保つ1 時間の TTLですが、キャッシュ書き込みをより高いレートで請求します。より長い TTL は、セッションをアイドル状態のままにして戻ってくる場合に役立ちます。期限切れのプリフィックスが発生する再処理をスキップできるためです。5 分を超えてアイドル状態にならない短いバースト作業では、より高い書き込みレートが適用され、より長いキャッシュライフタイムが未使用のままになるため、コストが高くなります。

各リクエストが取得する TTL

Claude Code はリクエストごとに TTL を決定し、すべてのリクエストは 2 つの固定バケットのいずれかに該当します。

  • メイン会話: インタラクティブなターン、非インタラクティブな -p 実行、Agent SDK ターン、およびそれらと共にインラインで実行される Claude Code ヘルパー
  • その他すべて: サブエージェント、ワークフロー、プロセス内チームメイト、フォーク、圧縮、セッションタイトルなど、その会話の外で Claude Code が行うリクエスト

TTL を自分で選択しない限り、Claude Code は Claude サブスクリプション内でプランに含まれる使用量内でのみ 1 時間の TTL をリクエストします。そこでメイン会話に対して 1 時間をリクエストし、Anthropic がサーバー側で制御する小さなヘルパーリクエストセットをリクエストします。このテーブルは、両方の種類の請求下での各バケットのデフォルト TTL を示しています。

リクエストバケット Claude サブスクリプション、プラン使用量内 使用クレジット、API キー、またはクラウドプロバイダー
メイン会話 1 時間 5 分
その他すべて 5 分（ただし、サーバー制御のヘルパーリクエストは 1 時間） 5 分

プランの使用制限を超えて、Claude Code が使用クレジットを引き出すと、その使用量に対して課金されるため、Claude Code はメイン会話を、キャッシュ書き込みのレートがより低い 5 分の TTL に低下させます。そこで 1 時間の TTL を保つには、TTL を自分で選択してください。

TTL を自分で選択する

どちらのバケットに対しても TTL を設定できます。各コントロールは 5m または 1h を取り、Claude Code は他の値を無視します。

両方の設定と両方の環境変数には Claude Code v2.1.242 以降が必要です。API キーで署名するか、クラウドプロバイダーを使用する場合は、promptCacheTtl を 1h に設定して、メイン会話に 1 時間のキャッシュを与えます。その外のリクエストは、そのバケットに対しても TTL を選択するまで 5 分のデフォルトを保ちます。

複数のコントロールが適用される場合、Claude Code はこの順序で最初にマッチするものを取ります。

  1. FORCE_PROMPT_CACHING_5M=1。両方のバケットに対して 5 分を強制します
  2. バケットの環境変数
  3. バケットの設定
  4. サブエージェントのリクエストの場合、サブエージェントの experimental frontmatter フィールドの cacheTtl 値。Claude Code v2.1.248 以降が必要です。Claude サブスクリプションが使用クレジットを使用している間、Claude Code はそこの 1h を無視します
  5. ENABLE_PROMPT_CACHING_1H=1。両方のバケットに対して 1 時間をリクエストします
  6. リクエストのバケットのデフォルト

キャッシング動作をデバッグする場合、2 つの TTL を比較する場合、または管理設定で設定された長い TTL をオーバーライドする場合は、FORCE_PROMPT_CACHING_5M=1 を設定します。

メイン会話のキャッシュ書き込みが使用した TTL を確認するには、claude -p "hello" --output-format json を実行し、結果の usage.cache_creation を読みます。Claude Code は 1 時間のキャッシュ書き込みを ephemeral_1h_input_tokens の下で報告し、5 分のキャッシュ書き込みを ephemeral_5m_input_tokens の下で報告します。

ゲートウェイ経由または Amazon Bedrock で 1 時間の TTL を利用するには:

キャッシュスコープ

Claude Code では、キャッシュは事実上 1 つのマシンとディレクトリにスコープされます。システムプロンプトは自動メモリパスを埋め込み、会話は作業ディレクトリ、プラットフォーム、シェル、OS バージョンのアナウンスで開始されます。異なるディレクトリの 2 つのセッションは、したがって異なるプリフィックスを構築し、互いのキャッシュをミスします。

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

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

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

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

フィールド 意味
cache_creation_input_tokens このターンでキャッシュに書き込まれたトークン。キャッシュ書き込みレートで請求されます
cache_read_input_tokens このターンでキャッシュから提供されたトークン。モデルのキャッシュされたトークンレートで請求されます。標準入力レートより低くなります

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

セッションごとのサマリーについては、/usage を実行してください。メインの会話の最初の応答の後、Claude Code はセッションブロックにPrompt cache (main) 行を追加し、セッションのヒット率、ミス数、およびキャッシュが現在ウォームであるかどうかを表示します。statusline スクリプトは、prompt_cache オブジェクトから同じ数値を読み取ることができます。どちらも Claude Code v2.1.251 以降が必要です。

Prompt cache (main) 行は、Claude Code が識別できる場合、最後のミスの可能性のある原因も名前を付けます。例えば likely cause: tool definitions changed のようにです。可能性のある原因テキストには Claude Code v2.1.260 以降が必要です。

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

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

サブエージェントは、親とは別に、独自のシステムプロンプトとツールセットを持つ独自の会話を開始します。最初のリクエストは親のキャッシュを読み取りません。2 つのプリフィックスが異なるためです。また、独自のターン全体で独自のキャッシュを温めます。サブエージェントはメイン会話の TTL バケットの外にあるため、サブスクリプション上でも 5 分間の TTL を取得します。より長い TTL を選択するまでです。

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

一方、フォークは、親のシステムプロンプト、ツール、会話履歴を正確に継承するため、最初のリクエストは親のキャッシュを読み取ります。

他のリクエストも、以前のリクエストがキャッシュしたプリフィックスを読み取ることができます。

  • セッションコピー: /forkでコピーしたセッションは、コピーされた会話の最後にメッセージとして分離命令を受け取るため、元の会話が構築したキャッシュはそのままです。
  • コンパクト化: 会話のコンパクト化で説明されている要約呼び出しは、同じプリフィックス共有アプローチを使用します。
  • 再開されたサブエージェント: Claude がサブエージェントを再開する場合、再開実行の最初のリクエストは、元の実行が温めたキャッシュを読み取ることができます。
  • ワークフローファンアウト: ワークフローファンアウトの同じプリフィックスエージェントでは、Claude Code はデフォルトで最初のエージェント以外をすべて最大 5 秒間保持するため、最初のエージェントがキャッシュしたプリフィックスを読み取ることができます。

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

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

変数 効果
DISABLE_PROMPT_CACHING すべてのモデルに対して無効にする
DISABLE_PROMPT_CACHING_HAIKU デフォルトの Haiku モデルに対して無効にする
DISABLE_PROMPT_CACHING_SONNET デフォルトの Sonnet モデルに対して無効にする
DISABLE_PROMPT_CACHING_OPUS デフォルトの Opus モデルに対して無効にする
DISABLE_PROMPT_CACHING_FABLE Fable のみに対して無効にする

DISABLE_PROMPT_CACHING_HAIKU はデフォルトの Haiku モデル、haiku エイリアスが解決するモデルに適用されます。そのモデルがメインモデルである場合のメイン会話を含め、そのモデルが実行される場所ならどこでもキャッシングを無効にします。メイン会話をカバーするには Claude Code v2.1.283 以降が必要です。

この変数は、メインモデルと異なる場合、非推奨の ANTHROPIC_SMALL_FAST_MODEL 変数で設定したバックグラウンドモデルもカバーします。

メインモデルとしてピン留めした別の Haiku バージョンはキャッシングを保持します。それに対してキャッシングを無効にするには DISABLE_PROMPT_CACHING を設定してください。

DISABLE_PROMPT_CACHING_SONNET と DISABLE_PROMPT_CACHING_OPUS はそれぞれ、sonnet または opus エイリアスが解決するモデルに適用されます。別の Sonnet または Opus モデル ID をメインモデルとして設定した場合、そのモデルはキャッシングを保持します。たとえば、claude-sonnet-5 でのセッションはキャッシングを保持しますが、sonnet は claude-sonnet-5-5 に解決されます。そのモデルに対してキャッシングを無効にするには、DISABLE_PROMPT_CACHING を設定してください。

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

関連リソース