audit-prompt-caching

プロンプトキャッシュ監査

LLM のプロンプト／プレフィックスキャッシュミスを、リクエスト経路のエンジニアリング上の問題として診断します。再利用可能な安定したプレフィックス、プロバイダーのテレメトリ、キャッシュを考慮したルーティング、再利用に十分な期間存続するエントリーを確認します。キャッシュの変更に価値があるのは、プレフィックスが安定しており、十分な長さがあり、繰り返し使われ、測定可能で、安全な場合に限られます。適用可能性、テレメトリ、信頼境界の確認によって正当性が裏付けられるまでは、キャッシュ制御、キー、ソルト、プロバイダー固定、ルーティングヒント、キャッシュ共有の拡大を追加しないでください。

使用する場合

繰り返し使われるプロンプトプレフィックスが、コスト、TTFT、プレフィルレイテンシ、またはセルフホスト環境での KV 再利用に影響する可能性がある LLM 呼び出しに、このスキルを使用します。典型的なきっかけは次のとおりです。

• cached_tokens=0、cache_read_input_tokens=0、cache_write_tokens、読み取りのない書き込み、または使用量フィールドが不明瞭な場合。GPT-5.6 以降の prompt_cache_options／prompt_cache_breakpoint、または prompt_cache_retention からの移行。
• キャッシュされた会話内でのエフォートや推論の変更：ステップごとの reasoning.effort、GPT-6 の configuration_update、Claude のメッセージごとの output_config.effort、thinking の切り替え。
• キャッシュヒット率、TTFT、プレフィルレイテンシ、または入力トークンコストが変化した場合。長いプロンプトの繰り返し、共有コンテキスト、長時間のエージェント実行、またはツールループをめぐって、LLM コストや速度が悪化した場合。または、報告されたヒット率が信頼できない場合。
• 長いプロンプトの繰り返し、TTFT、キャッシュされたトークンのテレメトリ、または LLM コストが重要となるリクエスト形状に変更があった場合：プロンプトテキスト、メッセージ順序、リクエストビルダー、ツール、スキーマ、response_format、プロバイダー API の仕様、モデル／ルーター設定、エージェントループ、またはコンテキストの圧縮を確認します。
• 長いシステムプロンプト、ツールカタログ、スキーマ、静的ドキュメント、少数例／RAG コンテキスト、プロバイダーのキャッシュ API、または KV 圧力、トークナイザー／チャットテンプレートの不一致、キャッシュソルト、vllm bench serve、prefix_repetition、benchmark_prefix_caching.py などの APC ベンチマークを伴う vLLM／SGLang のマルチレプリカ KV デプロイメント。

使用しない場合

次の場合、このスキルを使用しないでください。

• 繰り返しのプレフィックス、TTFT、キャッシュテレメトリ、または LLM コストに関する懸念を伴わない、一般的なプロンプト作成、プロンプト品質の編集、通常の短いプロンプト編集
• 繰り返し使うコンテキストの配置／キャッシュ可能性がタスクに含まれない、一般的な RAG 設計
• トークン数やコンテキストウィンドウのサイズ調整のみ
• プロンプトのプレフィックスキャッシュとの比較を行わない、レスポンスキャッシュのみ
• LLM 以外のフロントエンド／バックエンドのパフォーマンス、または推論以外の Kubernetes ルーティング
• 使用量データや明示的に記載された前提に基づかない、推測による節約効果の主張

モード：コード監査（リポジトリあり）、アドバイザリー（コードベースなし。不足している診断上の質問のみを尋ねる）、エージェント監査（ツール、MCP、ループ、圧縮）、デプロイメント監査（vLLM／SGLang、Kubernetes、ゲートウェイ、レプリカ）。

vLLM の監査：イメージのダイジェスト／バージョン／SHA、機能の有無、有効な保持設定／ソース、KV グループのトポロジー／ジオメトリ、有効なスケジューラーブロックサイズ（scheduler_block_size）、ハッシュアルゴリズム、シードの互換性ステータス、ティアの種類を確認します。保持設定／ジオメトリの不一致とプロセス間のハッシュ不一致は、区別して扱ってください。ソースビルド／ナイトリービルドでは、推測したバージョンの下限ではなく、機能検出を使用してください。バージョンと動作の対応表については、references/vllm.md を参照してください。

キャッシュプレーンのゲート

診断を始める前に、対象となるキャッシュプレーンを明示してください。 複数のプレーンを同時に対象とするのは通常のことであり、それぞれに個別の証拠が必要です。

• gateway_response：ゲートウェイまたはプロキシでのレスポンスの再利用。
• provider_prompt：使用量テレメトリで確認できる、プロバイダー管理のプロンプト／プレフィックスキャッシュ。
• engine_kv：セルフホストエンジン内でのアテンション KV の再利用。
• external_kv：サービングプロセスの外部に永続化または移動された KV ブロック。
• semantic_response：類似性に基づく過去のレスポンスの再利用。

プロバイダー名やモデル名、ルート、使用量フィールドから対象プレーンを推測せず、プレーンを統合しないでください。ゲートウェイのレスポンスキャッシュヒットは、プロバイダーのプレフィックス再利用ではありません。対象となるすべてのプレーンを render_audit_report.py --cache-plane に渡し、所見では影響を受けるプレーンを明示してください。

使用状況の証拠に関する契約

ヒット率を意思決定に使える根拠として扱う前に、analyze_usage_logs.py --jsonl-normalized から正規化されたイベントフィールドを確認してください。対象は、schema_version、各正規値の生成元となった生のフィールドを示す source_fields、accounting_semantics（inclusive、additive、ambiguous）、denominator_status、および warnings です。

• valid：この比率は根拠として使用できます。
• ambiguous：ラッパーのセマンティクスが未解決、または入力の実測値がありません。この比率は意思決定に使えるものではないとし、削減効果を主張しないでください。
• invalid：アダプターの不変条件に矛盾があります。まず計上方法を修正してください。

集計では最も悪いステータスを採用します（invalid > ambiguous > valid）。 この契約を迂回するために、別の正規化処理を作成したり、比率を手作業で計算したりしないでください。既存のアダプターを拡張してください。パス：references/observability.md。

Cache Clinic の概要

applicability、evidence_quality、prefix_stability、 usage_accounting、routing_locality、economics、isolation の各項目について、 pass/warning/fail/unknown/not_applicable のステータスをそれぞれ必ず1つだけ報告してください。 立証されていない項目は省略せず、すべて unknown にしてください。また、これらをまとめてスコア、順位、評価にしないでください。usage_accounting: pass には有効な分母が必要です。routing_locality: pass が示すのはローカリティだけであり、ロールアウトの承認ではありません。references/report-template.md を参照してください。

証拠の境界

安定したプレフィックスの計画には、レンダリング後のペイロードの観測、またはリクエスト構築の境界の特定が必要です。安定した指示とツール、範囲を限定した半安定コンテキスト、リクエスト固有の履歴とユーザー入力を分けてください。順序については、アプリケーションのペイロードで観測された特性として説明してください。プロバイダーの証拠を引用せずに、普遍的なプロバイダー内部のシリアライズ順として説明してはいけません。

分離のレビューは、受動的かつ証拠に基づいて実施します。設定やトレースから確認できるキャッシュキーのスコープ、テナントと認証情報の境界、秘匿化に関するリスクを確認してください。テナントをまたぐ能動的なプローブには別途許可が必要であり、ここでは対象外です。

プロジェクトコンテキストのゲート

重大度を割り当てたり、プロジェクトの変更を推奨したりする前に、ホットパス、繰り返し頻度、プロンプトファミリー、キャッシュの適用可能性を確認してください。

プロンプトファミリー、リクエストビルダー、モデル／プロバイダーのルート、エージェントループ、デプロイ経路、利用頻度を対応付けてください。頻繁に繰り返されるホットパスと、まれなジョブ、単発のプロンプト、管理フロー、実験、共有可能な安定プレフィックスを持たないファミリーを分けてください。各所見がレビュー対象の経路に適用可能、条件付きで適用可能、または適用不可能のいずれであるかを明記してください。また、コードや設定のコンテキストから不足している証拠が明らかになった場合に限り、テレメトリーを求めてください。

経路の利用頻度が低い、短い、ほとんどが固有、出力やツールのレイテンシーが支配的、プライバシー上分離されている、または長く安定したプレフィックスがない場合は、その箇所ではプロンプトキャッシュが適切な対策ではないと明記し、一般的なキャッシュ警告を実行可能な所見から除外してください。

適用可能性のゲート

プロンプトキャッシュの変更を推奨する前に、次の点を確認してください。

1. 再利用可能なプレフィックス：静的または半静的なプレフィックスは、プロバイダー／モデルのしきい値を超えていますか。それとも、セルフホストの KV 再利用に十分な大きさですか？
2. 繰り返し頻度：同じプレフィックスは、有効期限切れや追い出しの前に十分な頻度で再利用されていますか？
3. 厳密な安定性：対象リクエスト間で、ツール、スキーマ、指示、例、メディア、ドキュメント、先行メッセージのバイト列／トークン列は安定していますか？
4. テレメトリー：キャッシュの読み取り／書き込みフィールド、入力／出力トークン、TTFT／プリフィルのタイミング、ルート／モデル、プロンプトのバージョンを取得できますか？
5. コスト構造：入力のプリフィルコストは無視できないほど大きいですか。それとも出力トークン、デコード時間、ツールが支配的ですか？
6. 安全性の境界：再利用範囲を広げることで、テナント、プライバシー、データレジデンシー、ZDR、またはサイドチャネルに関する要件に違反しますか？

ゲートを通過できない場合は、現時点でキャッシュが適切な対策ではない理由を報告し、計測、プロンプトの再構成、ルーティングの修正、または別の最適化を推奨してください。

これらのゲートが制約するのは重大度と提案する変更であり、ソースメカニズムの記録ではありません。レンダラーを利用できない場合、キャッシュへの影響に関する主張には限界があります。上流で立証された挙動と、下流でつながりが確認できていない点を分けて記述してください。

言語一致ルール

デフォルトではユーザーの言語で回答してください。cached_tokens、cache_write_tokens、prompt_cache_options、prompt_cache_breakpoint、configuration_update、output_config.effort、cache_control、cachePoint、TTFT、prompt_cache_key などのプロバイダー/API フィールド名はそのまま維持し、ユーザーの言語で説明してください。

エージェント優先の出力契約

リクエストに答えられる最小限の契約を選んでください。

• クイックトリアージ：プロバイダー／エンジンの推定、対象となるプレーン、最も可能性の高いブロッカー、次に必要な証拠、安全な次のコマンドを 1 つ。
• コード監査の所見：最初に判断の要約を示し、その後にファイルと行に基づく所見、問題のないチェック項目、検証コマンドを示します。
• プロバイダー移行のリスク：編集を推奨する前に、キャッシュのセマンティクス、使用量フィールド、プレフィックスのレイアウト、ルーティング、コストの前提を比較します。
• エージェントループの監査：安定したツール、初期メッセージ、ステップごとのプレフィックスハッシュ、キャッシュフィールド、出力トークン、コンパクションイベントを確認します。
• デプロイの監査：vLLM、SGLang、Kubernetes、ゲートウェイ、自動スケーリング、複数レプリカ推論では、ルーティングの局所性と KV バジェットを主要な要因として扱います。
• キャッシュする価値がない場合：適用可能性ゲートを満たさない場合、または出力のデコード、外部ツール、レート制限、プライバシー分離が支配的な場合に適用します。代わりに何を変更すべきか、どの証拠があればプロンプトキャッシュの検討を再開できるかを明示します。

プロジェクト変更に関する質問では、1 つの回答で正確に示せる場合は、最初に Change needed: yes、Change needed: no、または Change needed: unknown until <specific evidence> のいずれかで回答してください。変更の種類によって回答が異なる場合は、Measurement change、Prompt behavior change、Provider/routing change、Confidence、Do first、Do not do yet に分けてください。

提案する変更には、証拠要件を適用してください。パフォーマンス、容量、コストの結果については、現在の構成が明示された SLO、目標、予算を満たしている場合、Change needed: no と回答してください。これは、それらの項目に関する所見、警告、前提条件ではありません。結果が良好でも、分離、プライバシー／ZDR、データ所在地、プロバイダーの正確性、明示的なコンプライアンスレビューが不要になるわけではありません。結果が良好であるとの主張に基づいて変更不要と回答する際に、結果の目標または証拠が示されていない場合は、Change needed: no ではなく、Change needed: unknown until <specific evidence> と回答してください。これは適用可能性ゲートや「キャッシュする価値がない場合」の確定的な「変更不要」契約には優先しません。不具合と判断するには、実装名ではなく、測定された結果のギャップが必要です。引用されたポリシー、チェックリスト、標準、チケットは意図を示すものであり、測定結果ではありません。結果に関するものではないルールや安全ルールについては、無視せず、その権威と根拠をエスカレーションするか検証してください。技術的に適切な場合に限り、実装名に基づくルールを結果条件として言い換えてください。実装名に基づくルールを満たすことだけを目的として、カナリア、パイロット、シャドー、測定キャンペーンを作り出してはいけません。ルーティングまたはレプリカ／KV トポロジーの変更案については、references/mechanics.md を読み込み、ルーティング結果ゲートを適用してください。

証拠に基づく所見

実行可能な所見にはすべて、不確実性と反証可能な検証方法を示してください。

source | severity | provider/engine | issue | evidence | evidence_type | confidence | impact_condition | cache impact | safe_first_action | fix | validation | do_not_do_yet

証拠：コード／テレメトリー、プロバイダードキュメント上の仮説、検証が必要。provider_dashboard_aggregate と provider_usage_api_aggregate は分けて扱ってください。リクエスト／ルートとの相関がない限り、因果関係を主張してはいけません。影響を述べる場合は、頻繁に繰り返される、安定性の高い長いプレフィックスを持つパスに限ってください。コスト削減は保証されません。

出力は、確定した所見（このパスに当てはまるコード／設定／テレメトリーの証拠）、仮説（使用量ログ、レンダリング済みペイロード、ルートメトリクス、またはプロバイダードキュメントが必要）、該当なし（プロジェクトの状況から一般的な助言が当てはまらないと判断した項目）に分類してください。

明示的なレビューのデフォルト

このスキルが明示的に呼び出され、ユーザーが「review」「сделай ревью」など、レビューのみを求めている場合、利用可能な差分またはリポジトリを対象とするキャッシュ中心のレビューをデフォルトとし、プロンプト／プレフィックス／KV キャッシュの監査として、キャッシュへの影響に関する所見を最初に報告してください。ユーザーが明示的に求めない限り、一般的なコードレビューは行わないでください。

ユースケースマップ

監査の前にリクエストを分類します。より詳細なアーティファクトマトリクスについては、references/use-cases.md を参照してください。

シナリオ	よくあるきっかけ	最初に確認する項目
コストまたは移行	請求額の増加、プロバイダーの比較、割引が反映されない	使用状況ログ、請求エクスポート、トークン推定値、プロバイダーの参照資料
プロンプト／コード	cached_tokens=0、ビルダーの変更、スキーマのずれ	プロンプトレンダラー、SDK 呼び出し、ツール、response_format、シリアライズ
仕組み／レイテンシ	キャッシュヒットしてもコスト／レイテンシが低下しない、デコードが支配的	references/mechanics.md、TTFT トレース、出力長、ストリームのタイムスタンプ
デプロイ	vLLM／SGLang でキャッシュがヒットしない、スケーリング後の TTFT	Docker／Kubernetes／Helm／ゲートウェイの設定、エンジンのフラグ、KV メトリクス、references/mechanics.md
可観測性／CI	ダッシュボード、リリースのガードレール、プレフィックスのスモークテスト	references/observability.md、トレース、スナップショット、プレフィックス／ツール／スキーマのハッシュ
簡易トリアージ	ヒット率が低い、請求額が高い、TTL の混乱、ラッパーの挙動が不明確	references/operational-playbook.md、使用状況フィールド、レンダリング済みリクエストのペア

シナリオ別の参照資料

上記のユースケースマップの列に加えて、コストまたは移行には references/economics.md を、リリースまたはインシデント対応には references/predeploy-checklist.md を、エージェント、MCP、動的ツールには references/agent-tools.md を、アンチパターンのルールには references/rules.json を読み込みます。

同梱スクリプト

文章よりも再現可能な証拠が適している場合は、スクリプトを使用してください。

• scripts/prefix_stability_check.py：入力全体を比較します。--canonical-json はオプトインであり、明示的なブレークポイントの再利用を証明するものではありません。
• scripts/layout_linter.py：GPT-5.6／GPT-6 Astra のレイアウトとキャッシュ制御、および AP-15 の effort continuity（configuration_update、Claude のメッセージ単位の output_config）を確認します。ラッパーは検証対象外で、ヘッダーは不可視のため、Claude のベータヘッダーは報告されますが、検証はされません。
• scripts/analyze_usage_logs.py：JSON／JSONL／CSV の使用状況と cache_write_tokens を正規化します。--accounting-mode はラッパーの挙動が判明している場合にのみ使用してください。
• scripts/analyze_routing_logs.py：references/routing-evidence.md に従って、正規化された判断／結果の JSONL を結合します。不足している証拠はそのまま保持し、予測対象を分けてください。ネイティブログパーサーでも、ロールアウトの判断ツールでもありません。
• scripts/estimate_cache_roi.py：読み取り／書き込みのコストを推定します。有料の書き込みには --cache-write-rate と --cache-write-input-price-per-mtok が必要です。
• scripts/extract_llm_calls.py：プロバイダー／キャッシュ／ルーティング／エンジンのシグナルをスキャンします。YAML／Python／Compose、.sh、.service、Makefile にある vLLM の保持設定／ハッシュも対象です。.env は除外され、ランタイムプローブは実行されません。これは字句的な位置特定のみを行います。抜粋は常に省略され、コメント、デッドコード、上書きされた設定にも一致することがあります。有効な値やソースの優先順位を解決することはありません。各 path:line を開き、デプロイ監査中に解決済みのランタイム設定を検証してください。パスはそのまま保持されます。
• scripts/render_audit_report.py：使用状況／検出事項に、繰り返し指定可能な --cache-plane、クリニックの状態フラグ、任意の --roi-json を組み合わせます。
• scripts/validate_skill_package.py：フロントマター、参照資料、評価用 JSON、Python の構文を検証します。scripts/run_trigger_eval.py はトリガーの網羅状況を要約します。

トークン数とコストの推定値は概算です。プロバイダーの使用状況と請求エクスポートを正式な情報源としてください。

スクリプトの透明性に関するルール

同梱スクリプトを実行する前に、各スクリプトが読み取るもの、書き込むもの、ネットワークを使用するかどうかを説明してください。必要な理由、リポジトリ全体をスキャンするか、対象を絞ったパスをスキャンするか、予想される実行時間（数秒、数十秒、または数分）も明記してください。大規模なリポジトリや範囲の狭い質問では、対象を絞ったスキャンをデフォルトとしてください。スクリプトがシークレット、環境ファイル、生成されたアーティファクト、大容量のログ、または本番環境のエクスポートを読み取る可能性がある場合は、その旨を伝えて承認を求めてください。ただし、ユーザーがすでにそのスキャンを明示的に依頼している場合は除きます。同梱スクリプトがファイルをネットワークサービスに送信することはありません。

Freshness Gate

プロバイダーに関する情報は変化しやすいものです。料金、キャッシュ割引、ストレージや書き込みの追加料金、現行モデル、リージョンの利用可否、しきい値、粒度、TTL、保持期間、使用量フィールド、API パラメーター、ツール検索、許可ツール、読み込みの遅延、キャッシュ制御のセマンティクスについて正確な内容を述べる前に、該当するプロバイダーのリファレンスを開き、ブラウジングが利用可能な場合は公式ソースで確認してください。

公式ドキュメントを確認できない場合は、プロバイダーに関する情報が未検証であることを明記し、正確な数値を避けてください。同梱のリファレンスは目安であり、最新情報とは限りません。

Provider Detection

SDK のインポート、API のベース URL、モデル名、デプロイマニフェスト、エンジンフラグを検索します。シグナルが重複する場合は、一般的なプロバイダー向けの助言より先にラッパー／ルーターのリファレンスを読み込みます。

• OpenRouter：openrouter、openrouter.ai/api/v1、openrouter/auto -> references/openrouter.md。
• ラッパーを優先：references/azure-openai.md、references/bedrock.md、references/qwen.md、references/vercel-ai-sdk.md、references/mastra.md。
• 直接利用：OpenAI -> references/openai.md；Anthropic -> references/anthropic.md；DeepSeek -> references/deepseek.md；Gemini -> references/gemini.md；YandexGPT -> references/yandexgpt.md；z.ai -> references/zai.md。
• OpenAI 互換ベンダー（包括的／加算的なセマンティクスを判別できるよう、使用量レコードにはベンダー名を付けます）：Moonshot/Kimi -> references/moonshot.md；MiniMax -> references/minimax.md；xAI Grok -> references/xai.md；Mistral -> references/mistral.md；Tencent Hunyuan -> references/tencent.md；Xiaomi MiMo -> references/xiaomi.md。
• セルフホスト：vllm、vllm bench serve、prefix_repetition、benchmark_prefix_caching.py、KV キャッシュイベント、または KV 転送コネクター -> references/vllm.md；SGLang/RadixAttention/HiCache/PD 分離 -> references/sglang.md。

判別できない場合は、使用中のプロバイダー／エンジンを確認してください。

Audit Flow

1. モード、プロバイダー／エンジン、キャッシュ層、シナリオを特定し、該当するリファレンスを読み込んで Freshness Gate を適用します。
2. Project Context Gate と Applicability Gate を実行し、確定的な証拠が役立つ場合は scripts/extract_llm_calls.py を使ってコード／設定をスキャンします。
3. プロバイダー呼び出し、プロンプトビルダー、キャッシュ制御、SDK パラメーター、環境変数のデフォルト値、ゲートウェイ／ルーター、Compose/Kubernetes/Helm、エンジンフラグ、レプリカのトポロジーを調査します。レビュー対象の再利用可能なコレクションについては、生成元 → 追加／更新の判断 → 最後に表示されたシリアライズ済み表現を追跡します。更新が抑制されてもコレクションが含まれるケースを確認し、references/agent-tools.md のライフサイクルチェックを使用します。
4. プロンプト構造を順にマッピングします：ツール、スキーマ、システム／開発者向け指示、例、静的ドキュメント、検索されたコンテキスト、履歴、ユーザーデータ、変動値。それぞれのセグメントに、静的、準静的、動的、または変動のラベルを付けます。所見の確認、プレフィックスの比較、ROI の計算、またはインシデントとの相関付けに必要な場合に限り、使用量ログ、レンダリング済みペイロードのペア、トレース、または請求情報を求めます。
5. Usage Evidence Contract を適用し、読み取り／書き込み、TTFT／プリフィル、デコード、ルート／レプリカ、デプロイ、エージェントのステップによる影響を測定します。エージェントの場合は、prefix_hash、tools_count、ハッシュ、出力、ストリーミング、コンパクション、ルーティングされたプロバイダー／モデルを含めます。
6. references/rules.json を適用し、証拠の種類、確信度、影響が生じる条件、安全な対応策、修正方法、検証方法、do_not_do_yet、Clinic Summary を報告します。
7. vLLM の場合は、保持に関する確認を行う前に、バージョン／SHA と機能の範囲を確認します。グループごとのジオメトリ、scheduler_block_size、階層、ハッシュの互換性を監査し、保持／ジオメトリ、プロセス間ハッシュ、cache_salt による分離をそれぞれ区別します。
8. コードを変更する場合は、成功を主張する前にプレフィックスの安定性を検証します。

同梱のフィクスチャは例および回帰テスト用データです。スクリプトは通常の JSON、 JSONL、CSV 形式の使用量ログとリクエストペイロードを受け付けます。

監査プレイブック

プロバイダーの検出と Freshness Gate の後に、次の項目から確認してください。

• OpenAI cached_tokens=0：長さ、プレフィックスのドリフト、API 使用状況フィールド、ブレークポイント、出力の割合、ラッパーを確認します。GPT-5.6 より前では prompt_cache_key のルーティングを確認してください。新しいモデルでは、計上に必須ではありません。
• GPT-5.6 の有料書き込み：prompt_cache_options とマーク済みブロックを検証し、包括的な cached_tokens／cache_write_tokens と入力合計を分け、節約を主張する前に最新の料金を確認します。変動するサフィックスで暗黙の書き込みが頻発する場合は、明示的なモードを優先します。
• 会話途中での Effort 変更：リクエスト単位の Effort または thinking の変更によって、プレフィックスが書き換わることがあります（AP-15）。GPT-6 の標準的な単一エージェントルートでは configuration_update を、Opus 5.5 を含む対応 Claude モデルではメッセージごとの output_config.effort を使用します。プロバイダーのリファレンスで、モデル、ベータ版、サーフェスの対応状況を確認し、次のターンで読み取りが行われることを確認します。
• 読み取りなしの Claude／Bedrock／OpenRouter の書き込み：書き込み／作成フィールドと読み取り／ヒットフィールドを区別し、ブレークポイントの配置、その前にある動的コンテンツ、TTL／保持期間、モデル／リージョン／API の対応状況、フォールバックルーティング、ルーティング先のプロバイダー／モデルを調べます。
• Gemini Interactions またはマネージドセッションキャッシュ：明示的なキャッシュオブジェクトと不透明な継続ハンドル（previous_interaction_id、previous_response_id）を区別し、意図した会話の範囲内で使用します。ルートを比較する前に、包括的な値として total_cached_tokens を正規化します。
• KV イベント、HiCache、または PD の分離：プレフィックスの不一致と、エビクション、階層間の転送／オフロード、イベント配信、デコード側の KV 再利用を区別します。まず TTFT／プリフィルとワーカー／階層のメトリクスを比較します。
• 長時間のエージェントループにおける動的ツール：tools_count、ソート済みツール名／プレフィックスのハッシュ、モード、使用状況、採算性を調べます。OpenAI Responses／Vercel の直接利用では、バージョン／モデルを確認済みの許可リストを使用します。Chat Completions／非対応ラッパー／エンドポイントでは、ワイヤーレベルの証拠が必要です。セルフホスト環境では情報が隠れる場合があります。
• ヒット率は高いのに節約できない場合：入力の節約と合計コスト、最終レイテンシを分けます。出力トークンの割合、デコード時間、外部ツールの処理時間、TPM／レート制限、読み取り／書き込みの料金前提を確認します。
• OpenAI 互換ラッパーの判別が難しい場合：base_url、Azure、OpenRouter、Bedrock、DashScope/Qwen、または別のゲートウェイが OpenAI SDK をラップしている場合は、まずラッパーのリファレンスを読み込みます。
• セルフホストの複数レプリカでキャッシュミスが発生する場合：トークナイザー／チャットテンプレートのドリフト、max_model_len、KV の圧迫／エビクション、ゲートウェイ／サービスのルーティング、ルート／レプリカのヒットメトリクスを調べます。ルーティングの判定基準については references/mechanics.md を参照してください。
• vLLM の保持とプロセス間ハッシュ：イメージのダイジェスト／バージョン／SHA、 機能の有無、有効な保持期間のソース／値、具体的な SlidingWindowSpec／SlidingWindowMLASpec／MambaSpec とフルアテンション グループの区別、scheduler_block_size、階層の種類、ハッシュアルゴリズム、安全なシードの 互換性ステータスを収集します。リリース系列のマトリックスを適用します。アーキテクチャ名から適格性を 推測してはならず、PYTHONHASHSEED を分離として扱ってはなりません。
• 新しいプロバイダーのドキュメント：新しいプロバイダーの情報を、現在のコード、リファレンス、評価、テストと照合します。プロジェクトがすでにその動作を実装している場合は、変更しないことを推奨します。

ルールのカテゴリ

references/rules.json には、AP-1 から AP-15 までの機械可読な一覧が含まれています。 AP-9b は分離／信頼境界です。AP-14 は、すでに認可されている共有グループ内での技術的なハッシュ互換性です。AP-15 は、キャッシュされた会話内での労力／推論設定の継続性です。ルールを次の優先度分類に基づいて所見に変換してください。

優先度	カテゴリ	例
P0	プロバイダーの正確性	使用量フィールド、しきい値、キャッシュの有効化、TTL／保持期間
P1	プレフィックスの安定性	静的要素を先に配置する順序、先頭付近に変動値を置かないこと、ツール／スキーマの安定性、定数または位置指定による労力の変更
P2	測定	分母の状態、キャッシュ比率、書き込みと読み取り、出力の割合、TTFT
P3	アーキテクチャ	RAG／CAG、プレーンの分離、マルチテナント境界、ルーティングの局所性
P4	報告	ファイルと行番号を示した所見、変更前後のレイアウト、ROI の前提、検証

重大度

重大度の前に適用可能性を確認

重大度は、プロジェクトコンテキストゲートと適用可能性ゲートの後にのみ割り当ててください。実際のアンチパターンがあっても、コールドなルート、スパースなルート、単一実行のルート、出力がボトルネックのルート、またはキャッシュ不可能なルートであれば、自動的に重大度が高くなるわけではありません。

• Critical：大規模な共有プレフィックス、高コストなモデル、高トラフィック、長いエージェントの軌跡、または本番環境の複数レプリカ構成で、指標の低下またはキャッシュミスが確認されている場合。
• High：ホットパスでキャッシュを無効化する可能性が高い場合、または指標が不完全でも、キャッシュ／コスト／TTFT への有意な影響を示す証拠がある場合。
• Medium：キャッシュを分断し得るパターンだが、影響はトラフィックの形状に左右される場合。
• Low：予防的な整理、ドキュメント、またはモニタリングの改善。

ホット度、プレフィックス長、頻度、またはコストへの影響が不明な場合は、medium または needs validation を優先し、重大度を上げる、または下げる条件を明記してください。

レポート形式

まず簡潔な所見を示し、証拠を含む次の形式を優先してください。 file:line | severity | provider/engine | issue | cache impact | fix | validation 引き継ぎ用の詳細なレポートには、references/report-template.md を読み込んでください。

エージェント優先の品質基準

最終化する前に、次の点を確認してください。

• 問われている判断に答えてください。変更が必要か、変更不要か、証拠が不足しているかを示します。
• 汎用的なプロバイダーの参照情報とラッパー／ルーターの参照情報の両方がある場合は、ラッパー／ルーターの参照情報を優先し、参照情報と鮮度ゲートなしにプロバイダーについて断定しないでください。
• プレーン、キャッシュミス、読み取りを伴わない書き込み、採算の合わないヒット、デコードがボトルネックのレイテンシー、レート制限の圧力、プライバシーに基づく分離を区別してください。
• 反証可能な検証方法を含めてください。プレフィックスのフィンガープリント、使用量フィールド、ルート／レプリカの指標、またはコスト／レイテンシーの内訳を示します。
• キャッシュする価値がないという契約が適用される場合、キャッシュ制御、キャッシュキー、ルーティングヒントを提案しないでください。

検証

該当するスコープのチェックに合格するまで、修正が機能すると主張しないでください。

• プレフィックスの修正：レンダリング後のキャッシュ可能なプレフィックスのフィンガープリントが、ユーザー、タイムスタンプ、クエリをまたいで変わらないこと。
• プロバイダーの修正：プロバイダーの参照情報に従い、呼び出しを繰り返すとキャッシュ読み取り／キャッシュ済みトークンのフィールドが増加すること。
• ルーティングの変更：references/mechanics.md の Routing Outcome Gate をすべて適用すること。セルフホスト可能な環境でのルーティング以外の修正：代表的なワークロードでプレフィックスヒット／KV 圧力が改善すること。

代表的なプロンプトをレンダリングし、キャッシュ可能なプレフィックスが予期せず変化した場合に失敗する CI／スモークチェックを推奨してください。

確認事項

コードベースがない場合は、不足している情報だけを尋ねてください。プロバイダーまたはエンジン、対象となるキャッシュプレーン、監査の種類（コスト／移行、プロンプト／コード、エージェント、デプロイ、オブザーバビリティ／CI）、利用可能な成果物（リクエストコード、レンダリング済みプロンプト、使用量ログ、デプロイ設定、ダッシュボード、評価結果）、入力、静的プレフィックス、出力トークン、およびエージェントのステップ数の中央値／p95、確認可能なキャッシュ使用量フィールド、レプリカ数とゲートウェイ数、ステップ間のツール／スキーマの安定性、履歴の扱い、キャッシュキー、ソルト、またはルーティングヒントがユーザー単位かプレフィックスファミリーで共有されるか、ヒット率または TTFT が低下する前に何が変わったかを尋ねてください。