コーディングエージェントのプロンプトキャッシュ: 効率と破綻要因
コーディングエージェントはリクエストごとに全コンテキストを再送しますが、プロンプトキャッシュがそれをフル料金で課金されないようにします。ただし脆弱で、先頭付近の1バイトが変わるだけで次のターンはすべて再課金されます。
エージェントセッションの各ステップは新しい API リクエストです: 送信するメッセージと、エージェントが返すツール結果のバッチです。モデルはリクエスト間で状態を保持しないため、エージェントはシステムプロンプト、ツール定義、プロジェクト指示、会話全体、そして新しい部分をすべて再送します。そのほとんどは前回と一致しており、プロンプトキャッシュが二度処理されるのを防ぎます。
Claude Code がキャッシュを自動管理します。API ではトップレベルの cache_control フィールドを設定するだけで自動キャッシュが有効になります。Codex CLI が動作する OpenAI のモデルも同様のプレフィックスルールと独自の価格・有効期限を持ちます。以下の数値は Claude のものです。
正確なプレフィックス、固定順序
キャッシュは各リクエストの先頭（プレフィックス）を直近で処理したものと比較します。マッチは完全一致で、1文字でも変われば以降すべてが無効になります。ファイル単位やセクション単位のキャッシュはありません。
プレフィックスは固定順序で読み込まれます: ツール定義 → システムプロンプト → メッセージ。上位レベルで変更があるとそのレベル以降すべてが無効になります。メッセージを編集してもツールとシステムプロンプトはキャッシュされたままです。ツール定義を変えるとそれ以前のすべてが無効になります。
Claude Code は変化しにくいものを先頭に置きます: 指示とツール定義、次にプロジェクトコンテキスト（CLAUDE.md、メモリ、ルール）、最後に会話です。通常のターンでは前回リクエスト全体がプレフィックスとなり、最新のやり取りだけが新規です。
キャッシュ書き込みと読み取りのコスト
キャッシュは入力価格を変えるだけで、回答価格は変わりません。2026年9月時点で Anthropic は各モデルの基本入力価格の倍数で課金します: 5分有効期限の書き込みは基本入力の 1.25 倍、1時間は 2 倍、読み取りは 0.1 倍です（Claude Fable 5.1 は 0.025 倍、Claude Opus 5.5 は 0.05 倍）。最後のキャッシュポイント以降は通常入力として課金されます。
| モデル | 入力 | 出力 | キャッシュ読み取り | キャッシュ書き込み 5 分 | キャッシュ書き込み 1 時間 | コンテキスト |
|---|---|---|---|---|---|---|
| Claude Haiku 4.5 | 1.00 | 5.00 | 0.10 | 1.25 | 2.00 | 200,000 |
| Claude Sonnet 5 | 2.00 | 10.00 | 0.20 | 2.50 | 4.00 | 1,000,000 |
| Claude Sonnet 4.6 | 3.00 | 15.00 | 0.30 | 3.75 | 6.00 | 1,000,000 |
| Claude Opus 4.6 | 5.00 | 25.00 | 0.50 | 6.25 | 10.00 | 1,000,000 |
| Claude Opus 4.7 | 5.00 | 25.00 | 0.50 | 6.25 | 10.00 | 1,000,000 |
| Claude Opus 4.8 | 5.00 | 25.00 | 0.50 | 6.25 | 10.00 | 1,000,000 |
| Claude Opus 5 | 5.00 | 25.00 | 0.50 | 6.25 | 10.00 | 1,000,000 |
| Claude Opus 5.5 | 4.00 | 20.00 | 0.20 | 5.00 | 8.00 | 1,000,000 |
| Claude Fable 5 | 10.00 | 50.00 | 1.00 | 12.50 | 20.00 | 1,000,000 |
| Claude Fable 5.1 | 10.00 | 50.00 | 0.25 | 12.50 | 20.00 | 1,000,000 |
例として Claude Sonnet 5 で 100,000 トークンのコンテキストを考えると、基本入力価格は 1 万トークンあたり $0.02（$2/百万トークン）です。キャッシュから読むとリクエストあたり $0.02、キャッシュなしでは $0.20 です。ミス後に再書き込みすると、5分有効期限で $0.25、1時間で $0.40 となり、キャッシュなしより高くなります。書き込みは通常入力より高価に設定されているためです。
5分料金では、書き込みは多くのモデルで読み取りの 12.5 倍、Opus 5.5 で 25 倍、Fable 5.1 で 50 倍です。5分書き込みは最初の読み取りで元が取れ、1時間書き込みは2回の読み取りで元が取れます。
5分か1時間か
有効期限（TTL）はキャッシュされたプレフィックスが未使用でどれだけ残るかを示し、各読み取りでタイマーは追加コストなしでリセットされます。時計はリクエスト開始時にスタートし、応答がストリームで4分かかれば、次のリクエストは5分キャッシュの残り約1分で再利用できます。
2026年9月時点で Claude Code は、Claude サブスクリプションのプラン使用枠内ではメイン会話に1時間、APIキー・クラウドプロバイダー利用時やサブスクリプションがクレジットを消費した場合は5分のキャッシュを提供します。サブエージェントはデフォルトで5分です。
メイン会話の有効期限を変更するには設定の promptCacheTtl または環境変数 CLAUDE_CODE_PROMPT_CACHE_TTL を 5m または 1h に設定します（Claude Code v2.1.242 以降）。リクエスト間の間隔が5分から60分になる場合に1時間が有効です。5分未満の連続リクエストでは、書き込みコストが増えるだけです。
claude -p "hello" --output-format json書き込みに使用された有効期限を確認できます: usage.cache_creation に 1 時間書き込みは ephemeral_1h_input_tokens、5 分書き込みは ephemeral_5m_input_tokens として表示されます。
キャッシュを壊すが通知しないケース
ミスが起きてもエラーは出ませんが、ターンが遅くなり、使用量に読み取りの代わりに大きな書き込みが記録されます。コーディングエージェントでの主な原因は次の通りです。
- モデル切替: 各モデルは独自のキャッシュを持つため、タスク途中で
/modelを変更すると履歴全体が再読込されます。別モデルを呼び出すスキルやopusplanのプランモードも同様です。 - エフォート変更: 多くのモデルはエフォートレベルごとにキャッシュが分かれます。2026年9月時点で Opus 5.5 と Fable 5.1 は APIキーまたは Claude サブスクリプションでキャッシュを保持します。
- ツールセット変更: ツール定義はプレフィックスの最初に来るため、追加・削除で全体が無効になります。Claude Code はデフォルトで MCP ツールを遅延ロードするため、サーバ側の変更はプレフィックスに影響しませんが、カスタム
ANTHROPIC_BASE_URLゲートウェイ経由で前もってロードするとサーバ障害でキャッシュが壊れます。 - プロンプト冒頭の変更: システムプロンプトにタイムスタンプが入っていると、以降すべてが毎回書き換えられ、読み取りが行われません。Claude Code のアップグレードでもシステムプロンプトが変わるため、最初のセッションはキャッシュが冷たい状態で始まります。
- 有効期限を超えて停止: デフォルトは APIキーで5分、サブスクリプションで1時間です。
最初のターンが高コストになる理由
ミスは次のリクエストで一度だけ支払われます。プレフィックス全体が再処理され書き込み料金で保存され、その後のリクエストはキャッシュから読み取ります。そのため、ブレーク直後の最初のメッセージは遅く高コストになります。
コンパクションは設計上ミスであり、キャッシュが温かい間は安価です。要約リクエストがキャッシュから履歴を読み取るためです。長時間のブレーク後にコンパクトすると、履歴全体を未キャッシュで再読込するためコストが高くなります。
推奨習慣: セッション開始時にモデルとエフォートを設定し、作業を完了してから離れ、テーマが変わるときは /clear で新規セッションを開始します。デッドエンドを除去したいときは /rewind がコンパクトより効果的で、既にキャッシュされたプレフィックスまで巻き戻します。Pro と Max プランでは、長時間ブレーク後に要約から大規模セッションを再開できるオプションがあります。
キャッシュヒット率の確認方法
API はレスポンスごとに 3 つの入力トークン数を返します: cache_read_input_tokens（キャッシュから供給）、cache_creation_input_tokens（書き込み）、input_tokens（最後のキャッシュポイント以降）。合計入力はこの 3 つの合計です。
ヒット率はキャッシュ読み取りトークン数を合計入力で割ったものです。長時間キャッシュが温かいセッションではほとんどが読み取りになるはずです。短いセッションでは最初の書き込みが全入力の大部分を占めるため低くなります。長いセッションで低ヒット率が続く場合は上記リストの原因を疑ってください。
/usageClaude Code v2.1.251 以降では Prompt cache (main) 行にキャッシュから供給された入力の割合、ミス数、キャッシュがまだ温かいかが表示されます。
v2.1.260 以降では、最後のミス原因が判明すればそれも表示されます（例: ツール定義変更）。これはメイン会話のみ対象で、サブエージェントは独自のプロンプトとツールを持つため、最初のリクエストは親のキャッシュを読み取りません。API のコンソール使用量ページでもキャッシュ読み取り率がチャート表示され、ベータ版のキャッシュ診断（2026年9月時点）では連続リクエストの分岐点が報告されます。
サブスクリプション vs API: ミスの費用負担は?
APIキー利用時はミスが表のレートで課金され、レートリミットの余裕も影響します。多くの Claude モデルではキャッシュ読み取りは分毎入力トークン上限にカウントされませんが、書き込みと未キャッシュ入力はカウントされます。
Pro や Max プランではトークン単位の課金はなく、/usage のドル表示は API ユーザー向けの概算です。ミスはプラン上限から消費され、Claude Code のドキュメントでは長時間セッションが予想以上に上限を消費する原因としてキャッシュミスが挙げられています。Pro、Max、Team、Enterprise プランでは、ミスが最近の使用量の 10% を超えると /usage の内訳でフラグが立ちます。
キャッシュトークンもトークンであること
たとえ 1/10 の価格でも、コンテキスト全体はリクエストごとに再読取られます。Claude Code のドキュメントによれば、1 行の質問でも一日中開いたセッションでは会話全体の使用量が計上されます。したがって、プロンプト前半を安定させてキャッシュを保ち、コンテキストを小さく保つことで、各読み取り・ミスのコストを抑える習慣が重要です。
手動で小さく保ちたくない場合は、capsul がエージェント CLI を駆動し、タスクが要求する分だけをトークン予算内で送ります。予算に達すると残りを省略した旨を報告し、ベンチマークページでモデル別の測定結果と回答チェックが公開されています。
よくある質問
Claude Code はプロンプトキャッシュを自動で使いますか？
はい。DISABLE_PROMPT_CACHING 環境変数でオフにしない限り、Claude Code がキャッシュを管理し、変化しにくい部分を先頭に配置します。2026年9月時点で、Claude サブスクリプションのプラン使用枠内ではメイン会話が1時間、APIキーやクラウドプロバイダー利用時は5分のキャッシュが適用されます。
Claude のプロンプトキャッシュは5分ですか1時間ですか？
両方あります。API のデフォルトは5分で、各読み取りでタイマーは追加コストなしでリセットされます。1時間の有効期限は書き込みコストが基本入力の2倍になる代わりに、キャッシュが長く保持されます。2026年9月時点で、Claude Code はサブスクリプションでメイン会話に1時間、APIキーでは5分を使用します（promptCacheTtl で上書き可能）。5分以上の間隔がある場合に1時間が有利です。
Claude のキャッシュ読み取りトークンはどれくらい費用がかかりますか？
2026年9月時点で、キャッシュ読み取りはモデルの基本入力価格の0.1倍です（Claude Fable 5.1 は0.025倍、Claude Opus 5.5 は0.05倍）。Claude Sonnet 5 では 100 万トークンあたり $0.20、未キャッシュ入力は $2 です。キャッシュ書き込みは通常入力より高価なので、読み取りが発生して初めてコスト削減になります。
プロンプトキャッシュのヒット率が低いのはなぜですか？
多くの場合、プロンプト冒頭が変化しているか、リクエスト間隔がキャッシュ有効期限を超えているためです。コーディングエージェントでは、セッション途中でモデルやエフォートを切り替える、ツール定義が変わる、システムプロンプトにタイムスタンプが入る、APIキーで5分以上停止する、などが主な原因です。短いセッションは最初の書き込みが全入力の大部分を占めるため自然に低くなります。Claude Code の /usage ではミスがカウントされ、v2.1.260 以降では最後のミス原因が推測されて表示されます。
CLAUDE.md を編集するとプロンプトキャッシュは壊れますか？
Claude Code ではセッション中の編集はキャッシュを壊さず、効果もありません。プロジェクトルートやユーザーレベルの CLAUDE.md はセッション開始時に一度だけ読み込まれるため、編集は次の /clear、/compact、または再起動時まで反映されません。サブディレクトリの CLAUDE.md はそのディレクトリのファイルが初めて読み込まれたときにロードされます。
$ npm i -g @penra/capsul