Claude Codeを定時実行のエージェントとして運用するとき、APIコストを左右するのはモデルの単価表よりも「プロンプトキャッシュがどこで切れるか」です。私はSNS運用の調査・執筆・審査を毎日複数のRoutineで回していますが、この構造を意識するようになったきっかけが、2026年8月末の連続リリースでした。キャッシュのヒット率がセッション単位で見えるようになり、エージェントごとにキャッシュの保持時間を指定できるようになり、そして「キャッシュが静かに切れていた」不具合が2件直された。この記事では、プロンプトキャッシュの仕組みと、切れる場所、観測と制御の手段、日次運用での設計の考え方を順にまとめます。
対象読者は、Claude Codeを対話だけでなく定時実行や自動運用に使い始めて、「使った分の請求が読めない」と感じている人です。前提として、プロンプトキャッシュそのものの説明から入るので、キャッシュを初めて聞く人でも追えるはずです。
プロンプトキャッシュとは何か
LLMのAPIは、リクエストのたびに会話の全文脈を送り直します。システムプロンプト、ツール定義、これまでの会話履歴。ターンが進むほど毎回送る量が増える構造です。
プロンプトキャッシュは、この「毎回同じ前半部分」をプロバイダ側に一時保存して、再送分の処理を割り引く仕組みです。執筆時点のAnthropic公式ドキュメントでは、キャッシュからの読み取りは通常の入力トークンの10%の価格、キャッシュへの書き込みは25%増し（5分TTLの場合）とされています。つまり同じプレフィックスを何度も送るワークロードなら、入力側のコストが大きく下がります。
Anthropic公式: Prompt cachingCache prompt prefixes with `cache_control` to cut costs and latency, using automatic caching or explicit breakpoints with 5-minute or 1-hour TTLs.platform.claude.comここで重要な性質がひとつ。キャッシュは「プレフィックス一致」で効きます。送っている内容の先頭からどこまでが前回と完全に同じか、で判定される。途中の1バイトでも変われば、そこから後ろのキャッシュは無効です。この性質が、後で説明する「静かに切れる」問題の根っこになります。
Claude Codeのセッションが毎ターン送っている中身を、先頭から順に並べるとこうなります。
- システムプロンプト（Claude Code本体の指示）
- ツール定義（組み込みツール＋接続しているMCPサーバーのツール群）
- プロジェクトの指示ファイルなど、セッション開始時に読み込まれる文脈
- これまでの会話履歴（ターンごとに末尾へ伸びる）
1〜3はターンが進んでも変わらない「固定部」、4だけが伸びていく「可変部」です。プロンプトキャッシュが狙っているのはまさにこの形で、固定部と会話履歴の先頭側をキャッシュに載せ、毎ターンの実質的な新規入力を「前ターンからの差分」だけにします。逆に言うと、固定部のどこかが変わると、その位置から後ろが全部キャッシュミスになる。先頭に近い場所ほど、変更のコストが大きい構造です。
エージェント運用では、なぜキャッシュが主役になるのか
対話で使っている分には、キャッシュはあまり意識しなくても働いてくれます。話が変わるのは、Claude Codeを定時実行で回し始めたときです。
私が運用しているSNS自動化のRoutineは、調査、記事やSNS原稿の執筆、公開前審査といった仕事を毎日決まった時刻に実行します。各セッションは長いシステムプロンプトと数十個のツール定義を持ち、審査は別のサブエージェント（critic）に分離しているので、1日の中で同じ形のプレフィックスが何度もAPIへ送られます。この構造だと、入力トークンの大半は「毎回同じ部分」の再送です。キャッシュが効いていれば1/10で済む部分が、切れていれば満額になる。日次で積み上がるので、月のコストはヒット率でほぼ決まります。
規模感をつかむために、公式の係数だけで机上計算をしてみます。固定部と履歴を合わせたプレフィックスが平均10万トークン、1セッション20ターンの仮定です。キャッシュなしなら入力は延べ200万トークン。キャッシュが理想的に効けば、初回に10万トークンの書き込み（1.25倍）を払い、残り19ターンの再送分は10%価格で済むので、入力コストはおおよそ「200万トークン分」から「約31.5万トークン分」相当まで下がる計算になります。実際のセッションは履歴が伸びるのでここまで単純ではありませんが、倍率の感覚としては、ヒットとミスで請求が数倍変わる世界です。数字はあくまで公式の価格比率から置いた試算で、私の実測値ではありません。
にもかかわらず、少し前までのClaude Codeには「いまキャッシュが効いているか」を確かめる手段がほとんどありませんでした。そこが8月末に変わります。
2026年8月末の3リリースで、観測と制御の道具が揃った
一次情報はClaude Code公式のchangelogです（確認日2026-08-30）。コスト関連の追加を時系列で並べます。
Claude Code公式changelogRelease notes for Claude Code, including new features, improvements, and bug fixes by version.code.claude.com
まず2.1.247（8月26日）で、API支出をプロファイルする /claude-api cost-optimize が追加されました。支出の内訳を分析する入口です。
次の2.1.248（8月27日）は2つ。エージェントのfrontmatterに experimental.cacheTtl が追加され、エージェント単位でプロンプトキャッシュのTTL（保持時間）を指定できるようになりました。あわせて、OAuthトークンの更新が長時間セッションのキャッシュミスを起こしていた問題と、再開したセッションでツール定義の変更がキャッシュミスを起こしていた問題が修正されています。
そして2.1.251（8月28日）で、/cost にセッション単位のプロンプトキャッシュ行が追加されました。ヒット率、ミス数、再キャッシュに使われたトークン、キャッシュがwarmかcoldか。ステータスライン用にも prompt_cache オブジェクトが公開され、SessionStartのresume hookはセッションの陳腐化度合いと推定再キャッシュコストを受け取るようになりました。/usage にはSpend limitの残量バーも付いています。
ばらばらの機能追加に見えますが、並べると一本の線になります。支出を分析する、キャッシュの保持時間を制御する、ヒット率を観測する。運用者から見れば「キャッシュを設計対象として扱ってよい」という整備です。
キャッシュは、どこで静かに切れるのか
私がこの流れで一番参考になったのは、新機能よりも「修正された2つの不具合」でした。どちらも、キャッシュが切れる典型的な場所を教えてくれます。
1つ目はOAuthトークンの更新です。長時間動くセッションの途中で認証トークンが更新されると、それがキャッシュミスに繋がっていた。ユーザーが書いたプロンプトは1文字も変わっていないのに、裏側の事情でプレフィックスの同一性が崩れるパターンです。
2つ目はツール定義の変更です。再開したセッションでツール定義が変わると、そこから後ろのキャッシュは全部作り直しになる。ツール定義はプロンプトの先頭近くに置かれる大きな塊なので、ここが変わると被害が大きい。MCPサーバーの構成を頻繁に入れ替えたり、動的にツールが増減する構成は、機能面では便利でも、キャッシュから見ると「毎回先頭を書き換えている」のと同じです。
どちらも本体側で修正済みですが、教訓は残ります。キャッシュはプレフィックス一致なので、切るのは派手な変更ではなく、自分が意識していない小さな差分です。システムプロンプトに現在時刻を埋め込む、実行のたびに並び順が変わるデータを先頭近くに置く、セッションごとにツール構成を変える。どれも同じ理由でヒット率を溶かします。
定時実行は「セッション内」と「セッション間」を分けて考える
もうひとつ、定時実行ならではの前提があります。キャッシュにはTTL（保持時間）があり、公式ドキュメントの既定は5分です。ターンとターンの間隔が短い対話セッションの内側では自然に持続しますが、たとえば24時間おきに起動する日次のRoutineでは、前日のキャッシュはとうに消えています。つまり定時実行のキャッシュは、実行のたびにcold start（初回書き込み）から始まる。
この前提から、効かせどころが2つに分かれます。
セッション内。1回の実行の中で何十ターンも回るなら、2ターン目以降のヒットが本命です。ここは前節の「プレフィックスを揺らさない」原則がそのまま効きます。逆に、1回の実行が数ターンで終わる軽いジョブは、書き込み25%増しの元が取りにくい。ジョブの長さによって、キャッシュの損益分岐が違うわけです。
セッション間。同じ形のセッションを短い間隔で何本も起動するなら、TTLの内側で相乗りできる可能性があります。experimental.cacheTtl がエージェント単位で保持時間を指定できるのは、この「次の実行までキャッシュを生かしておきたい」場面のための道具だと読んでいます。ただしTTLを伸ばすことにもコストの含意があるので、伸ばせば得という単純な話ではありません。
私のRoutine群は実行間隔が数時間〜1日なので、素直に考えればセッション間の相乗りは期待できず、勝負はセッション内のヒット率です。1回の実行が長い執筆系Routineはキャッシュの恩恵が大きく、短命の計測系ジョブは小さい。同じ「日次実行」でも、中身の形で経済性が違うという整理になります。
日次Routineでの設計判断
この整理を踏まえて、自分の運用では次の方針を採ることにしました。
まず観測から。/cost のキャッシュ行が出たことで、Routineごとのヒット率と再キャッシュトークンをセッション単位で確認できるようになりました。正直に書くと、各Routineの実測値はまだ取れていません。ここは未計測で、数字が揃ってから改めて書きます。先に手を打つのではなく、どのRoutineのヒット率が低いかを見てから直す順番です。
次に構造側の原則を3つ。
- プレフィックスの安定を最優先にする。システムプロンプト・ツール定義・参照ファイルの読み込み順を固定し、実行ごとに変わる情報（日付、対象データ）はできるだけ後ろに寄せる
- ツール構成をセッション中に揺らさない。使うMCPサーバーとツールの集合はRoutineの種類ごとに固定する
- サブエージェントの分離はキャッシュ境界の分離でもあると意識する。私の構成では審査用のcriticサブエージェントが本体と別のコンテキストを持つので、本体のキャッシュを審査で汚さない代わりに、critic側にも独自のプレフィックスができます。
experimental.cacheTtlがエージェント単位なのは、まさにこの境界ごとにキャッシュの寿命を変えたい場面があるからだと理解しています
TTLそのものについては、まだ様子見です。cacheTtl は名前のとおりexperimentalな設定なので、日次の本番Routineへ入れるのは、/cost でcold起動の再キャッシュコストが実際に痛いと確認できてからにします。新しい制御手段は「使えるようになった順」ではなく「観測で必要と分かった順」に入れる方が、運用は壊れません。
まとめ
- Claude Codeを定時実行で運用するときの入力コストは、プロンプトキャッシュのヒット率でほぼ決まる。キャッシュ読み取りは通常入力の10%価格、というのが執筆時点の公式ドキュメントの記載
- 定時実行のキャッシュは実行のたびにcold startから始まる。効かせどころはセッション内のターン間ヒットで、実行が長いジョブほど恩恵が大きい
- キャッシュはプレフィックス一致。切るのは派手な変更ではなく、トークン更新やツール定義の揺れといった意識しにくい差分で、この2つは2.1.248で本体側の不具合としても修正された
- 2026年8月末の3リリースで、支出の分析（
/claude-api cost-optimize）、保持時間の制御（experimental.cacheTtl）、ヒット率の観測（/costのキャッシュ行）が揃った - 設計の順番は観測が先。プレフィックスを安定させる原則を守りつつ、TTLの調整は
/costの実測で必要になってから入れる
自分のRoutine群のヒット率実測は、次の週次分析で取る予定です。数字が出たら、どのRoutineが一番キャッシュを溶かしていたかを含めて続きを書きます。