Claude Code はプロンプトキャッシュを自動で使い、毎ターン送り直す会話履歴のうち変わっていない部分を再処理せずに済ませています。設定は不要ですが、モデルの切り替えや /compact のようにキャッシュを外してしまう操作があり、その直後の1ターンだけ遅く・高くなります。この記事では、キャッシュがどう組み立てられているか、どの操作で外れてどの操作なら保たれるか、寿命(TTL)の決まり方とヒット率の確認方法を、公式ドキュメントに沿って整理します。
キャッシュの層構造
モデルはリクエスト間で何も覚えていないため、Claude Code はメッセージを送るたびにシステムプロンプト・プロジェクトの文脈・これまでのメッセージとツール結果・新しいメッセージをまとめて送り直します。新しい内容は末尾に足されるので、各リクエストの大半は直前のリクエストと同じです。API はリクエストの先頭部分(プレフィックス)を最近処理した内容と完全一致で照合し、一致した部分をキャッシュから読みます。途中のどこかが1か所でも変わると、そこから後ろはすべて再計算になります。ファイル単位・区間単位のキャッシュはありません。
このため Claude Code は、ターン間でめったに変わらないものほど前に置く順序でリクエストを組み立てています。
| 層 | 内容 | 変わるとき |
|---|---|---|
| システムプロンプト | 基本の指示、ツール定義 | 読み込まれるツール定義の集合が変わったとき |
| プロジェクトの文脈 | CLAUDE.md、自動メモリ、パス指定のないルール | セッション開始時、/clear や /compact の後 |
| 会話 | 自分のメッセージ、Claude の応答、ツール結果 | 毎ターン |
会話層に追記してもシステムプロンプトとプロジェクト文脈はキャッシュに残りますが、システムプロンプトが変わるとすべてが無効になります。表に出てこない要素として、モデル(モデルごとに別のキャッシュ)とeffort レベル(多くのモデルでレベルごとに別のキャッシュ)もキャッシュの持ちに影響します。公式のおすすめは、モデルと effort はセッションの最初に決めておき、/compact は作業の区切りに回すことです。
キャッシュはサーバー側にあり、場所は認証方法で決まります。API キー・Claude のサブスクリプション・Claude Platform on AWS なら Anthropic の基盤、Amazon Bedrock や Google Cloud の Agent Platform ならそのクラウドの基盤です。ANTHROPIC_BASE_URL や LLM ゲートウェイを経由する場合は転送先次第で、ゲートウェイが cache_control マーカーを黙って取り除くと、会話履歴全体が毎ターン非キャッシュ入力として課金されます。
キャッシュが外れる操作
次の操作の直後は、キャッシュの一部または全部が外れて1ターンだけ遅く・高くなり、その後は新しいプレフィックスがキャッシュされます。作業の途中では避けられるものがほとんどです。
- モデルの切り替え:
/modelで切り替えると、内容が同じでも次のリクエストは会話全体をキャッシュなしで読みます。キャッシュがまだ温かいうちは、ターミナルで切り替え前に確認が出ます。opusplanはプランモードで Opus、実行時に Sonnet を使うので、プランモードの出入りがそのままモデル切り替えになります。frontmatter で別のmodelを指定したスキルやコマンドを呼んだターンも同様です。 - effort レベルの変更: 多くのモデルではキャッシュが外れます。ただし API キーまたはサブスクリプションで Fable 5.1 以降・Opus 5.5・Sonnet 5.5・Haiku 5.5 を使う場合はキャッシュが保たれます(Bedrock や Agent Platform などでは従来どおり外れます)。
- fast mode のオン・オフ: 標準速度と fast mode は別のキャッシュです。初めてオンにした直後のリクエストは、それまでの会話を fast mode の料金でキャッシュなしに読むため、使うならセッションの最初にオンにするのが安上がりです。
- MCP サーバーの接続・削除: ツール定義はシステムプロンプト層にあります。既定で有効なツール検索(MCP ツールの遅延読み込み)が働いていれば、最初のリクエストのツール一覧が会話中ずっと保たれるので影響しません。ツール検索がオフ・非対応の環境では、サーバーの追加や意図的な削除でキャッシュが外れます。
- プラグインの有効化・無効化: スキル・コマンド・エージェント・フックなどは会話の末尾に追記されるだけなのでキャッシュは保たれます。MCP サーバーを含むプラグインは上の MCP と同じ扱いです。
/reload-pluginsが全体の読み直しを伴う場合は警告が出て適用されず、/reload-plugins --forceで強制できます。 - ツールを丸ごと拒否するルール:
BashやWebFetchのようなツール名だけの deny ルールは、ツール検索が無効な環境でツール定義を消すためキャッシュが外れます。Bash(rm *)のような範囲付きの deny ルールや allow / ask ルールは、呼び出し時に判定されるだけなので影響しません。 - 会話の圧縮: 圧縮は履歴を要約に置き換えるので、設計上会話層は作り直しになります。要約を作るリクエスト自体は、キャッシュが温かければプレフィックスをキャッシュから読むため、文脈の大きさから想像するより安く済みます。逆にキャッシュの寿命を過ぎてから実行すると履歴全体をキャッシュなしで読むので、古いセッションを再開した直後の
/compactが最も高くつきます。 - 画像の蓄積: 1リクエストに載せられる画像や PDF の数・合計サイズの上限に近づくと、古いものからまとめて外され、その位置から後ろが再処理されます。
- Claude Code のアップグレード: 新しいバージョンではシステムプロンプトやツール定義が変わるのが普通なので、アップグレード後の最初の会話は先頭からキャッシュを作り直します。自動アップデートは次回起動時に適用され、セッション途中には適用されません。
キャッシュが保たれる操作
次の操作は会話の末尾に追記するだけか、リクエストに触れないため、キャッシュは保たれます。
- リポジトリ内のファイル編集: ファイルの中身は Claude が読んだときに会話へ追記されるだけです。以前読んだファイルを編集しても過去の読み取り結果は書き換わらず、変更があった旨の system-reminder が追記されます。
- セッション途中の CLAUDE.md 編集: プロジェクト直下とユーザーの CLAUDE.md はセッション開始時に一度だけ読まれます。途中で編集してもキャッシュは外れませんが、その編集も反映されません。新しい内容は次の
/clear・/compact・再起動で読み込まれます。サブディレクトリの CLAUDE.md やpaths:付きのルールは必要になった時点で読み込まれるので、読み込まれる前の編集なら反映されます。 - 権限モードの変更: Manual から accept edits への切り替えなどはシステムプロンプトもツール定義も変えません。例外は上で触れた
opusplanでのプランモードです。 - 出力スタイルの変更:
/output-styleなどで切り替えると、新しいスタイルの指示が会話中のメッセージとして渡されるため、キャッシュを保ったまま次のメッセージから反映されます。 - スキルやコマンドの呼び出し: 呼び出した位置にユーザーメッセージとして指示が挿入されるだけです(frontmatter で別モデルを指定している場合を除く)。
/recap: 要約を表示用のコマンド出力として追記するだけで、履歴は置き換えません。/rewind: 以前のターンまで会話を切り詰めるので、残った履歴はその時点でキャッシュを作ったのと同じ内容になり、以前のキャッシュにヒットします。方針ごと捨てたいときは、圧縮より巻き戻しのほうがキャッシュの面で有利です。- サブエージェントの起動: サブエージェントは独自のシステムプロンプトとツールで別の会話を始めるので親のキャッシュは読みませんが、親側から見れば呼び出しと結果が追記されるだけで、親のキャッシュには影響しません。一方、フォークは親の内容をそのまま引き継ぐため、最初のリクエストから親のキャッシュを読めます。
キャッシュの寿命(TTL)
キャッシュは一定時間使われないと期限切れになり、キャッシュにヒットするたびにタイマーがリセットされます。API には5分と1時間の TTL があり、1時間のほうが長い休憩をまたいで温かさを保てる代わりに、キャッシュ書き込みの単価が高くなります。席を離れて戻ってくる使い方なら1時間、5分以上空けずに短く作業する使い方なら5分が向いています。
自分で指定しない場合、Claude Code が1時間を要求するのはClaude のサブスクリプションをプラン内の利用枠で使っているときのメイン会話(と、Anthropic がサーバー側で決める一部の補助リクエスト)だけです。
| リクエストの区分 | サブスクリプション(プラン内) | 利用クレジット・API キー・クラウドプロバイダー |
|---|---|---|
メイン会話(対話ターン、-p 実行、Agent SDK のターン) | 1時間 | 5分 |
| それ以外(サブエージェント、ワークフロー、チームメイト、フォーク、圧縮、セッションタイトルなど) | 5分(サーバー側で決める補助リクエストは1時間) | 5分 |
自分で決めたい場合は、メイン会話は設定 promptCacheTtl または環境変数 CLAUDE_CODE_PROMPT_CACHE_TTL、それ以外は設定 subagentPromptCacheTtl または環境変数 CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL に 5m か 1h を指定します(v2.1.242 以降。他の値は無視されます)。たとえば API キーで使っていてメイン会話を1時間にしたいなら、settings.json に次のように書きます。
{
"promptCacheTtl": "1h"
}
複数の指定がある場合は、FORCE_PROMPT_CACHING_5M=1(両区分を5分に強制)、区分ごとの環境変数、区分ごとの設定、サブエージェントの frontmatter の cacheTtl、ENABLE_PROMPT_CACHING_1H=1(両区分に1時間を要求)、既定値の順で先に当てはまったものが使われます。実際にどちらの TTL で書き込まれたかは、claude -p "hello" --output-format json の結果の usage.cache_creation で、ephemeral_1h_input_tokens と ephemeral_5m_input_tokens のどちらに数字が入っているかで確かめられます。
なお、キャッシュは実質的に1台のマシン・1つのディレクトリ単位です。システムプロンプトに自動メモリのパスが入り、会話の冒頭に作業ディレクトリや OS の情報が入るためです。同じディレクトリで並行して動かすセッション同士はキャッシュを共有できますが、別のディレクトリのセッションとは共有されません。
ヒット率の確認と無効化
キャッシュの効き具合は、API が毎回返す2つのトークン数でわかります。ステータスラインのスクリプトで current_usage を読めば、ターンごとに確認できます。
cache_creation_input_tokens: このターンでキャッシュに書き込まれたトークン(書き込み単価で課金)cache_read_input_tokens: このターンでキャッシュから読まれたトークン(通常の入力より安いキャッシュ単価で課金)
読み込みが書き込みより大きく上回っていれば順調です。書き込みが毎ターン高いままなら、プレフィックスのどこかが毎回変わっています。セッション全体の集計は /usage で見られます。メイン会話の最初の応答以降、Session ブロックに Prompt cache (main) の行が加わり、リクエスト数・キャッシュから読んだ入力の割合・ミスの回数・いまキャッシュが温かいか(warm / cold)が表示されます(v2.1.251 以降)。v2.1.260 以降では、直近のミスについて likely cause: tool definitions changed のように推定原因も出ます。圧縮など Claude Code 自身が会話を書き換えたことによる作り直しは、ミスではなく「expected rebuild」として別に数えられます。
キャッシュの挙動を調べるときなど、まれに無効化したい場合は次の環境変数を 1 にします。通常の利用では有効のままにしておくのが公式の推奨です。
| 環境変数 | 効果 |
|---|---|
DISABLE_PROMPT_CACHING | すべてのモデルで無効化(モデル別の指定より優先) |
DISABLE_PROMPT_CACHING_HAIKU | 既定の Haiku モデル(haiku エイリアスの解決先)で無効化 |
DISABLE_PROMPT_CACHING_SONNET | 既定の Sonnet モデルで無効化 |
DISABLE_PROMPT_CACHING_OPUS | 既定の Opus モデルで無効化 |
DISABLE_PROMPT_CACHING_FABLE | Fable モデルで無効化 |
モデル別の変数はエイリアスの解決先にだけ効くため、別のモデル ID を直接指定している場合はキャッシュが残ります。その場合は DISABLE_PROMPT_CACHING を使います。組織全体の方針にしたいときは、これらや TTL の環境変数を管理設定の env ブロックに入れて配布できます。
本記事は Claude Code 公式ドキュメント「How Claude Code uses prompt caching」を元に、「Manage costs effectively」と「Environment variables」で表示内容と環境変数を照合した非公式の日本語解説です(確認日 2026-11-13)。仕様は更新される場合があるため、利用前に公式ドキュメントをご確認ください。