Claude Code のプロンプトキャッシュの仕組みと注意点

Claude Code エンジニアリング 7分で読めます

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ターンだけ遅く・高くなり、その後は新しいプレフィックスがキャッシュされます。作業の途中では避けられるものがほとんどです。

キャッシュが保たれる操作

次の操作は会話の末尾に追記するだけか、リクエストに触れないため、キャッシュは保たれます。

キャッシュの寿命(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 を読めば、ターンごとに確認できます。

読み込みが書き込みより大きく上回っていれば順調です。書き込みが毎ターン高いままなら、プレフィックスのどこかが毎回変わっています。セッション全体の集計は /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_FABLEFable モデルで無効化

モデル別の変数はエイリアスの解決先にだけ効くため、別のモデル ID を直接指定している場合はキャッシュが残ります。その場合は DISABLE_PROMPT_CACHING を使います。組織全体の方針にしたいときは、これらや TTL の環境変数を管理設定の env ブロックに入れて配布できます。

本記事は Claude Code 公式ドキュメント「How Claude Code uses prompt caching」を元に、「Manage costs effectively」と「Environment variables」で表示内容と環境変数を照合した非公式の日本語解説です(確認日 2026-11-13)。仕様は更新される場合があるため、利用前に公式ドキュメントをご確認ください。