キャッシュのTTLを1時間に延ばすかは、離席の長さではなく戻る場所で決めています
Claude Code v2.1.242 で promptCacheTtl と subagentPromptCacheTtl が追加されました。1時間キャッシュが効く条件は離席時間ではなく、同じ作業ディレクトリと同じ git 状態へ戻るかどうかです。判断の順番と、効いているかを確かめる手順をまとめました。
プロンプトキャッシュを入れたのに請求が下がらなかったとき — cache_read を計測してヒット率の穴を塞ぐ運用メモ
cache_control を付けたのに Claude API の請求が下がらない。原因を推測で潰す前に cache_read と cache_creation を毎リクエスト記録し、ヒット率の穴を非決定プレフィックス・TTL 失効・しきい値未満の3系統に切り分ける運用メモです。
モデルを切り替えた朝、キャッシュヒット率はゼロに戻る — Opus 4.8 から Sonnet 5 への段替えとプロンプトキャッシュ再ウォーム設計
プロンプトキャッシュはモデル単位で分離されるため、モデル移行の初日はヒット率が0%から始まります。割合ベースの段階移行が二重にコストを壊す構造と、タスク系統単位で切り替えるコホート・カットオーバー設計を実測コードつきで整理します。
Claude API の Context Editing を入れたらエージェントが同じ調査を繰り返したとき — クリア境界とキャッシュ無効化を計測する運用メモ
Context Editing でツール結果を自動クリアしたら、エージェントが直前に読んだ内容を忘れて同じツールを呼び直し、キャッシュも毎回壊れてコストが上がった。沈黙する劣化を計測ログで切り分け、trigger・keep・clear_at_least を実測で決める運用メモです。
ツール定義を一行直しただけで、キャッシュが丸ごと作り直しになりました — cache_control ブレークポイントの置き場所
ヒット率が突然ゼロに張り付いた原因は、揮発するブロックを安定したブロックより上流に置いていたことでした。prefix キャッシュのカスケード失効の仕組みと、安定→揮発でブロックを並べ替え、4つしかない cache_control ブレークポイントをどこに置くかを実装と判断表で整理します。
毎朝のバッチでプロンプトキャッシュが毎回ミスしていた — 1時間TTLを延命するウォーミング間隔と損益分岐の出し方
数時間おきに走る定期実行では、1時間TTLのプロンプトキャッシュでも毎回コールドミスします。中身を変えずにTTLを延命するウォーミングの間隔をTTLから逆算し、読み取りコストを織り込んだ損益分岐を式で出す方法を、4サイトの自動生成パイプラインの実測とともにまとめました。
Claude API のプロンプトキャッシュが本番で静かにヒットしなくなるとき — TTLと節約額の実測メモ
プロンプトキャッシュは導入直後だけ効いて、本番では知らぬ間にヒットしなくなることがあります。完全一致プレフィックスを静かに壊す5つの要因、5分と1時間TTLの選び方、節約額を推測でなく実測に変える計装、変更頻度の階段で置くブレークポイント設計までを運用目線でまとめました。
多言語アプリの訳ブレを止める — Batch API と用語集キャッシュで Localizable.strings を一貫翻訳する設計
UI文字列を1本ずつ翻訳すると用語がブレます。Claude の Message Batches API と用語集のプロンプトキャッシュを組み合わせ、Localizable.strings を10言語以上へ一貫翻訳するパイプラインを、実測コストと落とし穴つきで設計します。
長時間走るエージェントの文脈が静かに劣化する — コンテキスト予算と圧縮の設計
夜通し走らせたエージェントの判断が朝には雑になる——原因は文脈の蓄積による希釈と位置効果です。コンテキストを予算として配分する設計、劣化を観測してから圧縮する手順、いつ何をどう捨てるかの実装、プロンプトキャッシュとの関係まで、動くコードと実測の勘所つきで扱います。
Claude API のプロンプトキャッシュを 5m と 1h で二段に分ける — TTL を分けるとコストは下がり運用は安定する
Anthropic API の cache_control には 5 分と 1 時間という 2 種類の TTL があります。これを「静的な前提情報は 1h、可変な few-shot は 5m」と二段に分けて運用する設計を、私の本番ワークロードで観測した数値とともに整理しました。
Claude API のプロンプトキャッシュがヒットしない時の診断手順
Claude API のプロンプトキャッシュが効いていない時、まず確認すべきは usage フィールドです。cache_read_input_tokens がゼロのまま増えない原因を、5つの典型パターンに沿って切り分けます。
Claude API のプロンプトキャッシュで月額コストを半分にした実装メモ
長文のシステムプロンプトを毎リクエスト送る本番ワークロードでは、プロンプトキャッシュの設計次第で月額コストが大きく変わります。ヒット率の計測から始める手順、TTLの選択、トークン下限と4ブロック上限の制約、toolsを1つ足してヒット率が0になった失敗談まで半年の運用実例でまとめました。