Claude Code のサブエージェントはキャッシュが5分で切れる、は本当か。手元のログで測った

開発未分類

Claude Code のサブエージェントはキャッシュが5分で切れる、は本当か

こんな話を目にした。

Claude のサブエージェントのプロンプトキャッシュは5分しか持たない（本体は1時間）。5分を過ぎたら、フルプライスのコストがドカンドカンとのしかかってくる。だからサブエージェント、とくに Agent Teams の使いすぎには気をつけたほうがいい。

前半は本当だった。手元のログで、本体とサブエージェントのキャッシュの寿命がはっきり分かれていた。後半は言い過ぎで、切れても定価には戻らない。サブエージェントが高くつく理由は別のところにあった。

手元のログで TTL を数えた

Claude Code はセッションの記録を ~/.claude/projects/<プロジェクト>/<セッションID>.jsonl に残す。サブエージェントの記録は、同じ場所の <セッションID>/subagents/agent-*.jsonl に別ファイルで残る。

API の応答に含まれる usage.cache_creation には、キャッシュに書き込んだトークン数が寿命ごとに分けて入っている。ephemeral_5m_input_tokens が5分キャッシュで、ephemeral_1h_input_tokens が1時間キャッシュだ。直近7日に更新された記録ファイルを選び、本体とサブエージェントに分けて足し合わせた。ファイル単位で選んでいるので、7日より前に始めて最近また使ったセッションは、古い分も含めて数えている。

5分キャッシュへの書き込み1時間キャッシュへの書き込み
本体セッション02.33億トークン
サブエージェント（129本）1.14億トークン0

本体はすべて1時間、サブエージェントはすべて5分だった。混ざっているものは1件もない。最近のサブエージェントを8本選んで1本ずつ見ても、全部が5分のほうに入っていた。

切れても「定価」には戻らない

ここからが後半の話になる。料金の倍率は Anthropic のプロンプトキャッシュの説明ページ（→ Prompt caching）に書いてある。通常の入力単価を1としたときの値だ。

操作単価
5分キャッシュへの書き込み1.25
1時間キャッシュへの書き込み2
キャッシュからの読み取り0.1

キャッシュが切れたあとの呼び出しでは、同じ内容をもう一度キャッシュに書き込む。払うのは書き込みの単価で、5分キャッシュなら1.25倍になる。1時間キャッシュの書き込み（2倍）よりは安い。

もう1つ大事なのが、寿命の数え方だ。同じページに「キャッシュは使うたびに無料で寿命が延びる」とある。5分というのは作ってからの時間ではなく、最後に使ってから次に使うまでの間隔のことだ。

サブエージェントは、ふつう数秒から数十秒の間隔で次の呼び出しをする。5分も空くのは、1回のツール実行が5分を超えたときくらいだろう。長いビルドやテスト、応答の遅いブラウザ操作などがそれにあたる。そういう待ちがなければ、ほとんどの呼び出しは0.1倍の読み取りで済む。

損得の分かれ目も計算できる。5分キャッシュは最初の書き込みが1時間キャッシュより0.75倍ぶん安い。そのかわり、5分を超えて1時間に満たない空きが1回でもあると、5分キャッシュだけが書き直しになり、読み取りで済んだ場合より1.15倍ぶん余計にかかる。1体のサブエージェントが一度でも5分以上（1時間未満）止まれば、1時間キャッシュより高くつく。止まらなければ5分のほうが安い。1時間を超えて止まった場合は、どちらのキャッシュも切れて書き直しになるので、書き込み単価の安い5分のほうがやはり安い。

本当に効いていたのは「1体ごとの初期費用」

ログをもう少し見ると、サブエージェントが高くつく理由は別のところにあった。

サブエージェントは、本体のキャッシュを使えない。起動するたびに、システムプロンプト、CLAUDE.md、ツール定義などを最初から書き込み直す。しかも仕事が終われば消えるので、書いたキャッシュを長く使い回せない。

同じファイルで、読み取り量が書き込み量の何倍あるかを比べた。

書き込み読み取り読み取り ÷ 書き込み
本体セッション2.33億244億約105倍
サブエージェント1.14億27億約24倍

本体は、書き込んだ量の100倍以上を読み取りに回せている。サブエージェントは24倍ほどで終わっている。単価を掛けて入力のコストに直すと、書き込みが占める割合は本体で約6分の1、サブエージェントで約3分の1になる。サブエージェントは、入力のコストのうちかなりの部分を「準備」に払っている。

なお、記録ファイルには同じ応答の usage が複数行に重複して入ることがあるので、トークン数の絶対値は実際より大きく出ているかもしれない。本体とサブエージェントで条件は同じなので、比率の比較には影響しないと考えている。

Agent Teams はどうか

Agent Teams のチームメイトは、ほかのメンバーからの連絡を待って長く止まる使い方になりやすい。もしチームメイトもサブエージェントと同じく5分キャッシュなら、5分を超える待ちのたびに書き直しが起きる。「Agent Teams はとくに気をつけたほうがいい」という話は、この点ではうなずける。

ただし、手元には Agent Teams の記録がなかったので、チームメイトのキャッシュ寿命は測れていない。ここは推測にとどまる。

まとめ

  • サブエージェントのキャッシュが5分で、本体が1時間なのは本当だった（手元の記録では例外なし）
  • 5分は「最後に使ってから」の時間で、切れても定価ではなく1.25倍の書き込みになる。止まらずに動いているサブエージェントなら、ほとんど問題にならない
  • サブエージェントが高くつくのは、1体ごとにキャッシュを作り直す初期費用のせいだ。数ファイルを読むだけの仕事なら、本体で読んだほうが安い
  • 長いツール実行や連絡待ちで5分以上止まる使い方をすると、書き直しが繰り返される。並べて動かすなら、止まらない仕事を任せるのがよい

自分の記録で確かめる方法

Git Bash や macOS のターミナルで、次のように数えられる。

cd ~/.claude/projects
sum() {
  [ $# -eq 0 ] && { echo "5m=0 1h=0（記録なし）"; return; }
  grep -ho '"ephemeral_5m_input_tokens":[0-9]*' "$@" | awk -F: '{s+=$2} END{printf "5m=%d ", s}'
  grep -ho '"ephemeral_1h_input_tokens":[0-9]*' "$@" | awk -F: '{s+=$2} END{printf "1h=%d\n", s}'
}
echo "サブエージェント:"; sum $(find . -path '*subagents*' -name '*.jsonl' -mtime -7)
echo "本体:"; sum $(find . -maxdepth 2 -name '*.jsonl' -mtime -7)

使っているプランや設定によっては結果が変わるかもしれない。自分の環境で一度数えてみるのがいちばん確実だ。

#Claude Code#サブエージェント#プロンプトキャッシュ#コスト