結論：4指標を同じsessionで追う
Claude Codeのprompt cacheは、hit率だけでなく、miss、再cacheされたtoken、warm/cold状態を同じsessionで追い、最後に総費用と合格出力数で評価します。最新の公式releaseでは、/costへsession単位のprompt-cache行が追加され、hit ratio、misses、tokens re-cached、warm/coldを確認できます。status line script向けには対応するprompt_cache objectが追加されています。
読者の具体的な困りごとは、cache TTLを設定しても本当に再利用されているか分からず、費用増減の原因を説明できないことです。読了後には、表示された数値から「安定」「変更が多い」「再利用間隔が合わない」のどれかを判断できます。次の行動は、代表agentまたはrepositoryを一つ選び、七日間のsession終了時に4指標と総費用を保存することです。
この監視機能はcacheを強制的に有効化する設定ではありません。model、prompt prefix、tools、Skills、agent定義、provider、再利用間隔が変わればmissや再cacheが増えます。また価格はmodelと契約経路で異なります。Claude Code release、status line文書、Anthropicのprompt cachingとpricingを公開直前に照合し、記事中の例を請求確定値として使いません。
/costとstatus lineの役割を分ける
/costは担当者がsessionを点検する時に向きます。作業終了時、異常時、設定変更直後に開き、hit ratio、miss数、再cache token、warm/coldを一まとまりで読みます。表示値の定義と単位は対応versionの公式文書で確認し、割合だけを転記せずsession ID、model、version、開始時刻、providerを添えます。短いsessionは母数が小さいため、1回だけの100%や0%で標準設定を変えません。
status lineのprompt_cache objectは、作業中に状態を常時表示したり、既存の運用scriptへ渡したりする用途に向きます。表示領域は狭いので「状態」「hit率」「再cache量」の三つを優先し、詳細はlogへ送ります。値が欠損する経路ではゼロと解釈せず「未取得」と表示します。script errorでClaude Code本体の作業を止めない一方、監視欠損をalertとして残します。
warmは直前のprefixが再利用できる可能性がある状態、coldは初回、TTL経過、重要なprefix変更などの調査起点として使います。ただし表示名だけから原因を断定しません。missが増えた時刻の前後で、Claude Code更新、model変更、settings、CLAUDE.md、Skills、MCP tools、agent frontmatter、provider認証を差分確認します。担当者の自由記述ではなく変更revisionへ結びます。
4指標を5つの判断へ変換する
- hit率：安定session間で比較し、母数と作業時間を添えます。
- miss：初回、TTL、prefix変更、model変更の候補へ分類します。
- 再cache token：大きな固定prefixが何度書き直されたかを見る手掛かりにします。
- warm/cold：同じ条件のsessionを分け、平均値の混在を防ぎます。
- 総費用：cache read/write、通常入力、出力、再試行を合算します。
hit率が高く総費用も下がり、品質が同じなら安定です。hit率が高くても再cache tokenが大きく、出力や再試行が増えていれば改善とは言えません。coldが毎回続く場合は実行間隔とTTL、sessionの起動方法、prefixの安定性を確認します。設定変更直後だけcoldで、その後warmへ移るなら想定内の可能性があります。
agent別の比較では、単純な平均hit率より「合格出力1件当たり総費用」を主指標にします。長い推論で高品質を出すagentと短い整形agentを同じ目標へ揃えません。p50とp90のsession費用、再試行率、処理時間も併記します。価格改定またはmodel更新の週はbaselineを分け、前月比の原因をcacheだけに帰属させません。
監視を導入する7手順
- Claude Codeの対応versionと公式release内容を確認します。
- 対象業務を一つに絞り、model、provider、agent revision、toolsを固定します。
- session終了時に
/costを確認し、4指標と総費用を記録します。 - status lineへ状態、hit率、再cache量を短く表示します。
- 欠損値をゼロに変換せず、未取得率を別指標にします。
- 七日後にwarm/cold別、agent別、変更revision別で比較します。
- 原因を一つだけ変更し、さらに七日間観測して標準化します。
改善候補は、安定した固定prefixを前方へ寄せる、頻繁に変わる情報を後方へ分離する、agentやtoolsのrevisionを不用意に毎回変えない、実行間隔に合うTTLを選ぶことです。機密情報をcacheへ長く置けるという意味ではなく、入力最小化とdata handlingは別gateで管理します。監視値を外部へ送る時はprompt本文やfile pathを含めず、集計に必要な数値と識別子だけにします。
運用チェックリストとHOLD条件
- 対応versionを確認した
- 4指標の定義を確認した
- modelを記録した
- providerを記録した
- agent revisionを記録した
- tools差分を記録した
- 欠損を未取得と扱う
- warm/coldを分けた
- 総費用で評価した
- 品質を同じ基準で採点した
- 再試行率を含めた
- 価格確認日がある
- 秘密情報をlogへ出さない
- rollback基準がある
HOLD条件は、表示値の単位が未確認、異なるmodelやproviderを混ぜた平均、欠損をゼロ扱い、hit率だけで費用削減を断定、個人情報やprompt本文を監視先へ送る場合です。status lineの表示があることを請求監査の代替にせず、期間集計と請求明細を突合します。
よくある質問と次の行動
hit率の目標は何%ですか？
共通の正解はありません。業務ごとに総費用、品質、時間のbaselineと比較します。
coldなら障害ですか？
初回や更新後は自然です。連続実行でも続く場合にTTLやprefix差分を調査します。
cache TTL記事との違いは何ですか？
TTL記事は設定選択、本記事は実際のsessionで効果を観測し原因を切り分ける検索意図です。
一次情報はClaude Code公式release、status line公式文書、prompt caching公式文書です。関連するcache TTLの選び方、status line利用量監視、API費用削減も確認してください。Miraigentの無料診断では、測定単位と改善順序を60秒で整理します。