Claude Code agentのcache TTLを5mと1hから選ぶ方法

結論：作業間隔のp75で5mと1hを選ぶ

読者の困りごとは、長いsystem promptやSkillsを何度も読み込むagentの費用と応答時間を下げたい一方、1hを選ぶと常に得なのか、変更した指示がいつ反映されるか分からないことです。読了後には、agentごとに5m、1h、未設定のどれで検証を始めるか判断できます。次の行動は、実行時刻、前回からの間隔、cache read/write token、総費用、指示revisionを一週間記録することです。

公式仕様、料金、制限を分けて確認する

公式changelogが保証するのは設定名、許容値、適用の優先条件です。cache hitそのものを保証する設定ではありません。promptのprefix、tool定義、model、provider、認証更新などが変わればmissし得ます。frontmatterは対象agentの定義へ置き、構文errorや未対応versionでは期待どおり動かないため、Claude Code version、agent名、設定revision、実行providerを証跡へ含めます。

Anthropic公式prompt caching文書は、cache writeとcache readを通常入力とは別の単価で扱い、TTLにより書込単価が異なる場合があることを示しています。価格はmodel、platform、契約、更新時点で変わるため、固定金額をこの記事から転記せず公式pricing表を公開直前に確認します。1hは再利用可能時間が長い反面、長TTLのwrite費用と無効化頻度を含めて比較します。Bedrock、Vertex、Foundryやgateway経由では対応条件と計測項目が異なる可能性があるため、利用providerの文書も確認します。

この機能は内容を永続保存するknowledge baseではありません。TTL後の再利用、cache keyの完全な制御、必ず同じ応答になることを期待しません。個人情報やsecretをcacheへ入れてよい根拠にもならず、入力最小化、契約上のdata handling、retention、regionを別に確認します。agentの指示を更新した時はrevisionを変え、旧prefixが再利用されたと誤解しない観測を用意します。

5m・1h・未設定を6軸で比較する

1. 再利用間隔：連続実行は5m、承認やCIをまたぐ処理は1h、単発は未設定から始めます。
2. write費用：長TTLの単価とmiss回数を掛け、read節約額だけで判断しません。
3. hit率：実行間隔だけでなくprompt prefix、tools、modelが安定しているかを見ます。
4. 変更反映：緊急policyを頻繁に変えるagentは短いTTLまたはrevision分離が扱いやすくなります。
5. provider：直接APIとcloud providerで対応・請求・metricsを分けます。
6. 監査：agent revision、TTL、cache read/write、総token、処理結果を一つのrun IDへ結びます。

例として、同じformatで100件を連続分類するagentは5mでも高い再利用が見込めます。担当者reviewを20分待って修正するagentは1hが候補です。週に一度だけ動くagentは長TTLを設定しても次回へ残らないため、prompt短縮やBatchなど別の改善を優先します。複数agentで似たpromptを使っても、cache keyが共有されると仮定せず個別に測定します。

安全に導入する7手順

1. 対象agentの目的を一つに絞り、frontmatterと本文のrevisionを固定します。
2. 過去一週間の実行間隔を集計し、中央値とp75、5分以内率、60分以内率を出します。
3. 短い定型処理は5m、待機を含む処理は1h、単発は未設定で仮説を置きます。
4. agent frontmatterへexperimental.cacheTtlを追加し、対応versionで構文を確認します。
5. 同じmodel、tools、provider、入力群で一週間A/Bし、品質条件を変えません。
6. cache read/write token、入力費用、総費用、p50応答時間、miss理由を比較します。
7. 節約額と運用負担が基準を満たすagentだけ採用し、月次で価格とhit率を再確認します。

費用判定は「1 run当たり総費用」と「合格出力1件当たり費用」で行います。cache hitが増えても再試行や誤回答が増えれば不採用です。cache関連値が取得できない経路では総入力tokenと請求額、時間で代替し、推測のhit率を確定値として報告しません。設定変更日は同時にpromptを変えず、原因を一つに固定します。

企業運用チェックリストとHOLD条件

• 対応versionを確認した
• agentの検索意図が一つ
• 実行間隔を実測した
• modelを固定した
• providerを固定した
• prompt revisionを保存した
• tools差分を記録した
• cache readを測れる
• cache writeを測れる
• 総費用で比較した
• 品質を同じ基準で採点した
• 個人情報を最小化した
• 価格再確認日がある
• rollback手順がある

HOLD条件は、請求経路が不明、agent定義が毎回変わる、modelとtoolsを固定できない、品質評価がない、秘密情報を長く保持できるという誤解がある場合です。cache TTLは費用上限でも速度保証でもありません。月額上限、session予算、同時実行、停止条件は別に設定します。

小さな差でも、同じ条件を二週間以上観測してから標準化します。価格改定、model更新、agent定義変更があった週はbaselineを分け、以前の節約率をそのまま使いません。財務reportには推定hit率ではなく、請求明細と取得できたcache tokenを添付します。

よくある質問と次の行動

一次情報はClaude Code公式changelogとPrompt caching公式文書、料金はAnthropic公式pricingです。関連するClaude Codeのコスト管理、API費用削減、利用量の常時確認も確認してください。Miraigentの無料診断では、測定単位と停止条件を60秒で整理します。