プロンプトキャッシュのしくみ
Claude Code が自動管理するプロンプトキャッシュの仕組みと、何をするとキャッシュが無効化されるかを整理する
この節で学ぶこと
この節では、Claude Code が自動で行っているプロンプトキャッシュ（prompt caching）の仕組み — 何がキャッシュされ、どんな操作が無効化するか — がわかります。
変わっていない部分は読み直さず再利用する
モデル切替や /compact など一部の操作は再利用を止め、次の応答が急に遅く・高くなる
プロンプトキャッシュとは
Claude Code とのやり取りは、実は「会話」ではなく「毎回まっさらに送られる手紙」です。モデルはリクエストとリクエストの間、何も覚えていません。ターンが進むたびに、Claude Code はシステムプロンプト・プロジェクトの情報・それまでの会話とツール結果の全部を、新しい発言と一緒にもう一度まるごと送り直しています。
分厚い契約書
前文（毎回ほぼ同じ内容）を担当者が律儀に全部読み直していたら日が暮れる
前文はもう読んだ
変更があった最後のページだけ確認すればいい
プレフィックスを再利用
サーバー側が先頭から完全一致する部分（プレフィックス）を記憶し、読み直さず使い回す
一致判定は完全一致。プレフィックスのどこか1か所でも変わると、そこから後ろは全部再計算になる
ファイル単位・セクション単位で部分的にキャッシュが効く、という仕組みではありません。プレフィックス全体が先頭から一致するかどうかだけで判定されます。
リクエストは3層でできている
Claude Code は「めったに変わらないものを先頭に、よく変わるものを末尾に」並べることで、プレフィックス一致を最大化しています。
- 1
ターン1
システムプロンプト・プロジェクトコンテキスト・会話をすべて送信し、キャッシュに書き込む
- 2
ターン2〜3
会話レイヤーだけが末尾に伸びる。先頭2層はキャッシュから読み直す
- 3
ターン4（モデル切り替え等）
システムプロンプトが変わり、それより後ろすべてが再計算される
| レイヤー | 内容 | 変わるタイミング |
|---|---|---|
| システムプロンプト | コア指示・ツール定義・出力スタイル | 読み込まれるツール定義の集合が変わった時、または Claude Code がアップグレードされた時 |
| プロジェクトコンテキスト | CLAUDE.md・自動メモリ・スコープなしのルール | セッション開始時、または /clear・/compact の後 |
| 会話 | あなたの発言・Claude の応答・ツール結果 | 毎ターン |
会話レイヤーだけが変わる分にはシステムプロンプトとプロジェクトコンテキストはキャッシュされたままです。逆にシステムプロンプトが変わると、それより後ろの内容は別のプレフィックスの後ろに座ることになるため、すべて無効化されます。
さらに、プロンプトの文章そのものではないのにキャッシュキーの一部になっている設定が2つあります。
モデル
モデルごとに別々のキャッシュを持つ。/model でモデルを切り替えると、内容が同一でもリクエスト全体が再計算される
エフォートレベル
同じモデルでもエフォートレベルごとに別キャッシュ。セッション途中で /effort を変えるとリクエスト全体が再計算されるため、Claude Code は変更前に確認ダイアログを出す。今と同じレベルに設定し直す場合はダイアログがスキップされキャッシュも保たれる
ここがポイント
モデルとエフォートレベルは文章に出てこないが、キャッシュキーの一部
キャッシュを無効化する操作
次の操作は、次のリクエストでキャッシュの一部または全部をミスさせます。1回だけ遅く・高くなるターンが発生し、その後は新しいプレフィックスがキャッシュされます。
モデルの切り替え（/model）
モデルごとに別キャッシュのため。opusplan 設定はプランモード切り替えのたびにモデルが変わるので毎回モデル切り替え扱いになる
エフォートレベルの変更（/effort）
エフォートレベルごとに別キャッシュのため
ファストモードを ON にする
リクエストヘッダーがキャッシュキーの一部になるため。以後はヘッダーを送り続けるので、2回目以降の ON/OFF はキャッシュを保つ
MCPサーバーの接続・切断
ツール定義がシステムプロンプト層にあり、それが変わるため。ツール検索（tool search）で遅延読み込みされている場合は末尾に追記されるだけなのでキャッシュは無効化されない
プラグインの有効化・無効化
提供するのがスキル・コマンド・エージェント・フック等なら追記のみでキャッシュは保たれる。MCPサーバーを提供するプラグインの場合は上と同じ扱い
ツール全体を deny ルールで禁止
Bash や "*" のような裸のツール名・ツール名グロブでの deny はツール定義自体をシステムプロンプトから取り除くため無効化する。Bash(rm *) のようなスコープ付き deny ルールや allow・ask ルールは無効化しない
会話の圧縮（/compact）
会話履歴を要約に置き換えるため、会話レイヤーが新しい短い履歴になり、元のプレフィックスと共有できない
Claude Code のアップグレード
新バージョンは通常システムプロンプトやツール定義を更新するため
キャッシュを保つ操作
一方で、次の操作は会話の末尾に追記するだけか、リクエストの中身に一切触れないため、キャッシュを保ちます。
ファイル編集
リポジトリ内のファイルを編集しても、読み直しは会話の末尾への追記として扱われる
CLAUDE.md の編集
セッション途中で編集してもキャッシュは壊れない（内容の反映は次の /clear・/compact まで待つ。後述）
出力スタイルの変更
セッション開始時に一度だけ読み込まれるため、途中変更してもキャッシュは壊れない（反映も後回しになる。後述）
権限モードの切り替え
切り替えてもキャッシュは壊れない。ただし opusplan モデル設定ではプランモードの出入りがモデル切り替えになるため例外
スキル・スラッシュコマンドの呼び出し
呼び出し時点の指示をユーザーメッセージとして追記するだけ
/recap の実行
要約をコマンド出力として追記するだけで、会話履歴自体は置き換えない
会話を巻き戻す
巻き戻し先はすでにキャッシュ済みのプレフィックスなので、そこから読み直せる（詳細は公開準備中）
サブエージェントの起動
親のキャッシュには影響しない（詳しい仕組みは後述）
CLAUDE.md をセッション途中で編集しても反映されない
プロジェクトルートとユーザーレベルの CLAUDE.md はセッション開始時に一度だけ読み込まれ、メモリ上に保持されます。セッション途中で編集しても、キャッシュは無効化されない代わりに、その編集内容も適用されません。Claude はセッション開始時点の内容のまま動き続け、新しい内容が反映されるのは次の /clear・/compact・再起動のタイミングです。
なお、サブディレクトリのネストした CLAUDE.md や paths: frontmatter 付きのルールは、Claude が該当ファイルを最初に読んだ時点で読み込まれるため、それより前の編集は反映されます（読み込み後の編集は反映されません）。出力スタイルの変更も同様に、セッション開始時に一度だけ読み込まれるため、途中変更は次の /clear か再起動まで反映を待ちます。
キャッシュの生存期間とスコープ
キャッシュされたプレフィックスは、一定時間操作がないと失効します。キャッシュにヒットするたびにタイマーがリセットされるので、作業を続けている限り温かい状態が保たれます。
1時間
サブスクリプション（Pro/Max等）の既定 TTL
5分
APIキー等、トークン単価課金の既定 TTL
5分
使用量クレジット消費時に自動で切り替わる TTL
1時間 TTL を維持したい場合は環境変数 ENABLE_PROMPT_CACHING_1H=1 を設定します。対象は Claude のサブスクリプションに加え、APIキー・Amazon Bedrock・Google Cloud の Agent Platform・Microsoft Foundry・Claude Platform on AWS です。
デバッグ等で強制的に5分 TTL に固定したい場合は FORCE_PROMPT_CACHING_5M=1 を設定します。
export ENABLE_PROMPT_CACHING_1H=1キャッシュのスコープは実質的に「1台のマシン×1つのディレクトリ」単位です。システムプロンプトには作業ディレクトリ・プラットフォーム・シェル・OSバージョン・自動メモリのパスが埋め込まれるため、ディレクトリが違うセッション同士は別々のプレフィックスとなり、キャッシュを共有しません。
ワークツリー（worktree）をまたぐ
同じリポジトリでもワークツリー（worktree）ごとに作業ディレクトリが異なるため、別キャッシュになる
同じディレクトリで並行実行
同じディレクトリで並行実行しているセッション同士は一致するプレフィックスを作るため、互いのキャッシュを読み合える
キャッシュ性能を確認する
API のレスポンスには毎回、キャッシュ性能を示す2つのトークン数が含まれます。
書き込みは高い
cache_creation_input_tokens はこのターンでキャッシュに書き込んだトークン数（キャッシュ書き込み単価で課金）
読み込みは安い
cache_read_input_tokens はこのターンでキャッシュから読み込んだトークン数（標準入力単価の約10%で課金）
statusline（公開準備中）から current_usage を参照すると、この2つをリアルタイムで確認できます。読み込み対書き込みの比率が高いほどキャッシュが効いている状態で、書き込みがターンをまたいで高止まりしている場合は、上の「キャッシュを無効化する操作」のどれかが毎回起きている可能性があります。
サブエージェントとキャッシュ
サブエージェントと fork は、親のキャッシュを引き継げるかどうかが違います。
サブエージェント
fork
サブエージェント
fork
サブエージェント
fork
/compact の要約生成リクエストも fork と同様の仕組みでプレフィックスを共有しています。
つまずきポイント
よくある誤解
Claude Code とは「会話」を続けているので、前のターンの内容はモデル側に覚えられていると思われがち
実際は
実際は毎ターン、システムプロンプトから会話履歴まで全部をまるごと送り直している。モデル自身は何も覚えておらず、サーバー側がプレフィックス（先頭から一致する部分）を読み直さずに再利用しているだけ
よくある誤解
モデルの切り替えは「タダ」で、コストもかからないと思われがち
実際は
切り替え直後の1ターンは、内容が同じでもキャッシュがゼロから作り直されるため、遅く・高いターンになる。切り替えるならセッションの冒頭でまとめて決めるのが安全
よくある誤解
セッション中に CLAUDE.md を編集すればすぐに Claude の挙動に反映されると思われがち
実際は
プロジェクトルート・ユーザーレベルの CLAUDE.md はセッション開始時に一度だけ読み込まれる。編集してもキャッシュは壊れない代わりに反映もされず、次の /clear・/compact・再起動まで待つ必要がある
よくある誤解
deny ルールを追加すればどんな書き方でもキャッシュが無効化されると思われがち
実際は
Bash のような裸のツール名や "*" はツール定義そのものを消すため無効化するが、Bash(rm *) のようなスコープ付きルールはツールの呼び出し可否のチェックだけなのでキャッシュには影響しない
- 参考（公式ではない）: 長時間セッションで急に応答が遅くなったら、まず「直前に何を切り替えたか（モデル・エフォート・ファストモード・MCP接続）」を疑うと原因特定が早いです
関連リンク
- コンテキストウィンドウの全体像: コンテキストウィンドウを理解する
- 権限モードとキャッシュの関係: 権限モードを選ぶ
- 原文: How Claude Code uses prompt caching
出典
- How Claude Code uses prompt caching（取得日: 2026-08-18）