Claude Codeの新規セッションでキャッシュ書込が増える仕組み

Claude Codeで新しいセッションを始めるたびに、毎回ほぼ同じ内容のスタートアップ文脈がキャッシュに書き直されている。GitHubのissue #98513は、そう報告しています。原因は、最初のユーザープロンプトが、セッションをまたいで変わらない文脈より前に置かれていることです。このissueはopenのままで、修正バージョンは示されていません。

新規セッションの最初のリクエストで何が起きているか

プロンプトキャッシュは、リクエストの先頭から一致する部分(プレフィックス)だけを再利用します。途中で1文字でも違えば、そこから後ろはすべて再計算されて書き込み直しになります。

issue #98513の報告者がAgent SDK経由で捕まえた送信内容は、次の並びでした(CLI 2.1.284、settingSources: ['project']、skills: 'all')。

つまり、毎回同じはずのスキル一覧やCLAUDE.mdが、毎回違う最初のプロンプトの後ろ、または同じメッセージの中に入っています。プロンプトが変わるだけで、後ろの内容は全部書き込み直しになります。

報告された実測値

issue本文の計測はclaude-sonnet-5-5で、1試行ごとに新規セッションを作り、最初のプロンプトを毎回別の文言にしています(各群n=31、交互に実行)。

• 既定の配置(メモリがmessages[0]): 最初のターンでcache_readは12,185、cache_creationは約32.5K
• 同じ内容をsystemPromptのappendへ移し、claudeMdExcludesでメモリファイルを除外した配置: cache_readは18,052、cache_creationは約16.1K

メモリをシステムプロンプト側へ移すと書込は約半分になりました。残る約16Kは、環境情報、遅延ツール、エージェント一覧、スキル一覧を含む後置のsystemメッセージで、報告者は、これを前に出すオプションが現状ないと書いています。excludeDynamicSections: trueを指定しても位置は変わらなかったそうです。

別の報告者は、起動時の文脈が約50kトークンあり、そのうち約14k(システムプロンプトと組み込みツール定義)しか読み取れていないと書いています。CLAUDE.md、メモリ、スキルとエージェントの一覧、MCPのツール名とサーバー指示にあたる約35kは、ほぼ毎回書き直されるとのことです(CLI 2.1.303)。

Linuxの別の報告者は、claude -pで次の3回を連続実行しました。

3回目はプロンプトが2回目と同一のため、スタートアップ文脈の全体が読み戻されています。文脈全体を共有できる状態にあり、妨げているのは最初のプロンプトの位置だけ、という切り分けです。

サブエージェントにも同じ形で効く

サブエージェントの最初のメッセージはタスクのプロンプトです。issueは、サブエージェントの生成にも同じ並びが当てはまると指摘しています。コメントの報告者は、1週間の171回の起動で、最初の呼び出しのキャッシュ書込の中央値が約20K、読取の中央値が0だったと書いています。ただし異なるエージェント種別はプレフィックスを共有しないため、この数字を全部このバグのせいにはしていません。

Claude Codeのドキュメントにも、サブエージェントは自分のシステムプロンプトとツールセットで会話を始め、最初のリクエストは親のキャッシュを読まない、と書かれています。サブエージェントの起動が親のキャッシュを壊さない点も記載があります。今回のissueが問うのは、その先の「同じ種別のエージェントを別タスクで起動したとき、共通部分を読み戻せるか」です。ワークフローのファンアウトで同じプレフィックスをそろえる設計はClaude Codeワークフローのプロンプトキャッシュで扱っています。

ドキュメントの説明との食い違い

ドキュメントのキャッシュ解説は、リクエストを「システムプロンプト」「プロジェクトコンテキスト(CLAUDE.md、自動メモリ、スコープなしのルール)」「会話」の3層に分け、不変に近い順に並べると説明しています。この説明どおりなら、新規セッション同士でプロジェクトコンテキストは共有されるように読めます。

issueの観測はそこと異なり、プロジェクトコンテキストと最初のプロンプトが同じメッセージの中に入ります。ドキュメントはこの点を書いていません。層の順序は正しくても、ブレークポイントの位置が違えば、共有できる範囲は変わります。関連issue #102042も、CLAUDE.mdと最初のプロンプトが同じキャッシュ区画に入っていると指摘しています(v2.1.299、macOS)。そこでは、ブレークポイントがsystem[1]、system[2]、最後のメッセージにしかないと報告されています。

費用への効き方を概算する

API料金表によれば、Claude Sonnet 5.5の5分キャッシュ書込は$2.50/MTok、キャッシュ読取は$0.10/MTokです。同じ16.1Kトークンでも、扱いはこれだけ変わります。書込の単価は読取のちょうど25倍($2.50 ÷ $0.10)です。料金表では、キャッシュ読取は基本入力価格の0.05倍、5分キャッシュの書込は1.25倍、1時間キャッシュの書込は2倍と区別されています。

• 書込: 16,100 × $2.50 ÷ 1,000,000 ≒ $0.040
• 読取: 16,100 × $0.10 ÷ 1,000,000 ≒ $0.0016

1セッションあたりは小さな差です。短いセッションを1日に何十回も立ち上げる運用や、サブエージェントを大量に起動するワークフローで差が積み上がります。issue #102042の報告者は、同じディレクトリで1時間のTTL内に再起動するメインスレッドが1日約29回あり、約44kトークンずつ書き直していると見積もっています。

サブスクリプションの利用上限に、キャッシュ書込がどれだけ効くかを示す数字は、issueにもAPI料金表にも載っていません。上の概算はAPI従量課金の単価で計算したものです。キャッシュ全般の消費への効き方はClaude Codeのキャッシュ時間と利用上限にまとめています。

自分の環境で確かめる

自分のセットアップでどれだけ当てはまるかは、最初のプロンプトだけを変えた2回の実行で比べられます。issueの報告者が使ったのは次の形です(フックは切り、モデルは軽いものを使います)。

claude -p "Reply with exactly the word: ok" \
  --model haiku --max-turns 1 --output-format json \
  --settings '{"disableAllHooks":true}'
claude -p "Reply with exactly the word: yes" \
  --model haiku --max-turns 1 --output-format json \
  --settings '{"disableAllHooks":true}'

JSON出力の使用量に含まれるキャッシュ読取とキャッシュ作成のトークン数を、2回で見比べます。2回目のcache_creationが1回目と同程度なら、プロンプトの違いで文脈が書き直されています。同じプロンプトを3回目に流して読取が跳ね上がれば、共有自体はできている状態です。

計測の際は次の条件を揃えます。

• 同じディレクトリで続けて実行する(CLAUDE.mdやスキルが同じになる)
• MCPサーバーの接続状況を同じにする。接続途中だと遅延ツールの一覧が変わり、以降が書き直される
• キャッシュのTTL内に実行する

今できる対処とできないこと

issue #102042の計測では、同じルールを--append-system-prompt-fileでシステム側へ移すと、最初のプロンプトが違ってもその分(約15k)が読み戻されました。システムプロンプトの側は共有される、という観測と一致します。

ただし、この方法はCLAUDE.mdの読み込みとは別の経路になります。階層ごとのCLAUDE.mdやルールのパス指定といった仕組みも使えなくなるため、読み込みの動作を確認したうえで、少量の固定ルールに限って試す範囲に留まります。スキル一覧、エージェント一覧、環境情報の後置分は、issueの報告者によれば今のところ前へ出すオプションがありません。

報告者のひとりは、セッション開始リクエストを並べ替える小さなローカルプロキシを回避策として公開しています。Anthropicが提供するものではない非公式のツールです。通信の中継は認証情報の取り扱いにも関わるため、使うかどうかは中身を確かめてから決めてください。

修正はissueが求める形で、ブレークポイントを最初のプロンプトの前に置くか、不変の文脈を前に出す選択肢を設けることです。修正が入るまでの間は、キャッシュの見え方をClaudeのプロンプトキャッシュの仕組みで押さえたうえで、短いセッションを乱立させず、まとめて走らせる運用が書込の回数を減らします。

判断の目安

issueはまだ議論の途中で、公式の見解や修正バージョンは記載されていません。進展を知るには、issue #98513と関連の#102042を見るのが確実です。