Claude Codeのプロンプトキャッシュ｜途中でモデルを変えると、次の1回は履歴を全部読み直す

Claude Code のプロンプトキャッシュは、前回と先頭から同じ部分だけを再利用する仕組みだ。
だから作業の途中でモデルを切り替えると、会話の中身が同じでも、次の1回は履歴を全部読み直すことになる。
逆に、作業中に CLAUDE.md を書き換えてもキャッシュは壊れない。
ただし、その変更は今のセッションには効かない。

この記事は、Claude Code の公式ドキュメント「How Claude Code uses prompt caching」を2026年11月4日に読んで、僕が理解した範囲で整理したものだ。
料金が何円減ったという話はしない。
僕はその効果を測っていない。
書くのは、何をすると切れて、何をしても切れないか、という仕組みの話だけだ。

毎回、会話を最初から全部送っている

モデルは、リクエストとリクエストの間のことを覚えていない。
だから Claude Code は、メッセージを送るたびに、システムプロンプト、プロジェクトの情報、それまでのやり取り、新しいメッセージを全部まとめて送り直している。
新しい分は末尾に足されるだけなので、1回のリクエストの大部分は前回とまったく同じになる。
その同じ部分を処理し直さずに済ませるのが、プロンプトキャッシュだ。

照合は、リクエストの先頭から行われる。
これをプレフィックス（prefix）と呼ぶ。
照合は完全一致で、途中のどこかが変わると、そこから後ろは全部計算し直しになる。
ファイルごとに部分的にキャッシュする仕組みはない。

並び順は、変わりにくいものが先

Claude Code は、キャッシュが効きやすいように、変わりにくいものから順に並べている。

• システムプロンプト：基本の指示とツールの定義。読み込むツールの組み合わせが変わると変わる。
• プロジェクトの情報：CLAUDE.md や自動メモリなど。セッションの開始時と、/clear・/compact の後に変わる。
• 会話：メッセージ、応答、ツールの結果。毎ターン変わる。

会話の部分が増えても、前の2つはキャッシュされたままだ。
システムプロンプトが変わると、後ろが全部ずれるので、全体が無効になる。
何が切れるかは、ほとんどこの並びで説明がつく。

キャッシュが切れる操作

公式が挙げているのは、次のような操作だ。
切れると、次の1回が遅くなって費用も増える。
その後は新しいプレフィックスがキャッシュされる。

• モデルの切り替え：モデルごとにキャッシュが別なので、中身が同じでも全部読み直す。
• fast mode のオン・オフ：通常の速度とキャッシュが別になっている。
• エフォートの変更：多くのモデルでは切れる。Opus 5.5、Sonnet 5.5、Haiku 5.5、Fable 5.1 を API キーかサブスクで使っている場合は、既定で切れない。
• MCP サーバーの接続・削除：ツールの定義が変わる場合に切れる。ツールを後から読み込む設定なら、途中で接続しても影響しない。
• /compact：会話の部分を要約に置き換えるので、会話の部分は切れる。
• Claude Code のアップデート、画像がたまった時も、公式の一覧に入っている。

切れない操作と、CLAUDE.md の落とし穴

リポジトリのファイル編集、権限モードの変更、出力スタイルの変更、スキルの呼び出し、/rewind、サブエージェントの起動は、キャッシュを切らない。
末尾に足すだけか、リクエストそのものに触らないからだ。
スキルの仕組みはClaude Codeのスキルの記事に書いた。

気をつけたいのは CLAUDE.md だ。
プロジェクト直下とユーザー単位の CLAUDE.md は、セッションの開始時に1回読まれて、メモリに保持される。
作業の途中で書き換えてもキャッシュは切れないが、書き換えた内容も効かない。
反映されるのは、/clear、/compact、再起動の後だ。
「ルールを足したのに守ってくれない」という時は、まずこれを疑うことになる。

/compact が重くなるのは、休憩の後

/compact は、要約を作るために別のリクエストを1回送る。
中身は、システムプロンプトと、ツールと、要約する履歴だ。
キャッシュが温かいうちなら、この履歴はキャッシュから読めるので、会話の長さの割に費用は小さくて済む。

キャッシュの寿命を過ぎてから実行すると、読めるキャッシュがないので、履歴を全部処理し直す。
公式も、古いセッションを再開した時の /compact がいちばん高くつく、と書いている。
だから公式のおすすめは、自動圧縮を待たず、タスクの切れ目で実行することだ。
やった作業を丸ごと捨てるなら、/compact より /rewind のほうが、キャッシュ済みの地点まで戻れる。

寿命は5分か1時間

キャッシュは、しばらく使わないと切れる。
ヒットするたびにタイマーは戻るので、作業を続けている間は温かいままだ。
寿命には5分と1時間の2種類があり、既定は使い方で変わる。

• サブスクの利用枠の中：メインの会話は1時間。
• API キー、クラウド事業者、利用枠を超えた後の追加クレジット：5分。
• サブエージェントなど、メインの会話の外のリクエスト：基本は5分。

設定の promptCacheTtl で 5m か 1h を選べる。
1時間のほうは、キャッシュへの書き込み単価が高くなる。

当たっているかは /usage で見る

確かめるなら /usage だ。
セッションの欄に Prompt cache (main) の行が出て、ヒット率、ミスの回数、今キャッシュが温かいかが分かる。
v2.1.260 以降なら、最後にミスした原因の見当も出る。

ステータスラインで見るなら、cache_read_input_tokens と cache_creation_input_tokens の2つだ。
読み出しが書き込みより多ければ、うまく効いている。
書き込みがターンごとに多いままなら、先頭のどこかが毎回変わっている。

僕がやること

ここからは僕の考えだ。
僕の CLAUDE.md は、今日数えたら115行、約28KB あった。
ルールを足すことが多いので、書き足した後に同じセッションで効くと思わないようにする。
モデルとエフォートは最初に決めて、切り替えたくなったらタスクの切れ目まで待つ。
確実に守らせたいルールは、CLAUDE.md だけに頼らず、Claude Codeのフックに寄せるつもりだ。

出典

• How Claude Code uses prompt caching｜Claude Code Docs（2026年11月4日取得）