AIレビュー指示の固定部と可変部を分けて並べる順序と、その料金
AIレビュー指示の固定部と可変部を分けて並べる順序と、その料金
同じ基準文書を使って1日に何度もレビューを回すなら、指示文の並べ方で入力の課金が変わる。固定部を先に置く理由は料金だけで、出力の質とは関係がない。そして固定部に「今回の PR は配送設定の変更である」のような1文を混ぜると、キャッシュは毎回作り直しになり、入力の課金は公式の倍率で計算してキャッシュを使わない場合の1.23倍になる。利点が消えるだけでなく、何もしないより高くつく。
この記事の提案を使うのは、同じ基準文書を添えたレビューを1日に何度も回すときである。1日に1回なら並べ替えの利得は出ない。
指示文を書いた順に並べたときの形
レビュー指示は、書いた順に並べると材料が先に来る。構成ファイルのレビューであれば、差分を貼ってから「次の基準で見てほしい」と続ける形になりやすい。
次の差分をレビューしてほしい。
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
（省略）
判定基準は次の4条である。
1. CI の権限は必要な範囲を超えていないか
2. イメージはダイジェストで固定されているか
3. 公開するポートを外へ出していないか
4. 本番の設定に開発用の既定値が残っていないか
対象外: 表記の揺れ、キーの並び順、コメントの有無この指示文のうち、毎回変わるのは差分だけである。4条の基準と対象外の宣言は、半年単位で変わらない。それでも並びの上では差分が先に来るので、基準の部分は毎回ちがう位置から始まる文字列になる。
キャッシュの前提になる規則
プロンプトキャッシュの挙動は公式ドキュメントに書かれている（Prompt caching、取得日 2026-10-11）。並べ方の要件は、このうち4つの記述から導ける。
1. 前方一致で作られ、順序が決まっている。 ドキュメントは「Cache prefixes are created in the following order: tools, system, then messages. This order forms a hierarchy where each level builds upon the previous ones.」と書いている。キャッシュの単位は先頭からの連続した部分であって、指示文の中の好きな場所を指して「ここを覚えておく」とは言えない。
2. 変更したレベルと、それ以降が無効になる。 ツール定義を変えると全体が無効になり、システムプロンプトを変えるとシステムとメッセージが無効になる。前に置いたものを1文字変えると、後ろにあるものは覚え直しになる。
3. 短いものは黙ってキャッシュされない。 最小のトークン数はモデルで違い、claude-opus-5 は512、claude-sonnet-5 は1,024、claude-haiku-4-5 は4,096である。ドキュメントは「Shorter prompts cannot be cached, even if marked with cache_control. Any requests to cache fewer than this number of tokens will be processed without caching, and no error is returned.」と書いている。エラーが返らないので、指定したつもりで効いていない状態が続く。
4. 書き込みと読み出しで値段が違う。 基準の入力価格に対して、5分の保持で書くときが1.25倍、1時間の保持で書くときが2倍、読み出しが0.1倍である（claude-opus-5 の場合。Claude Opus 5.5 と Claude Sonnet 5.5 は読み出しが0.05倍）。保持の長さは cache_control の ttl で 5m か 1h を選ぶ。
4つめは、並べ方の判断がそのまま金額になることを意味する。読み出しが0.1倍で書き込みが1.25倍なので、読み出しに回らなかった書き込みは、キャッシュしない場合より高い。
固定部に1文混ぜると何が起きるか
倍率が分かっているので、並べ方ごとの入力の課金を計算できる。以下は実測ではなく、公式の倍率による計算である。
条件をそろえる。1回の入力が10,000トークンで、そのうち基準文書と対象外の宣言が9,000トークン、差分が1,000トークンとする。これを5分以内の間隔で1日20回回す。基準の入力価格を1とした相当量で比べる。
| 並べ方 | 1回目 | 2回目以降（各回） | 20回の合計 | 倍率 |
|---|---|---|---|---|
| キャッシュを使わない | 10,000 | 10,000 | 200,000 | 1.00 |
| 固定部を先に置き、境界でキャッシュする | 9,000×1.25＋1,000＝12,250 | 9,000×0.1＋1,000＝1,900 | 48,350 | 0.24 |
| 固定部に毎回変わる1文が混ざっている | 12,250 | 12,250 | 245,000 | 1.23 |
3行目が、固定部に「今回の PR は配送設定の変更である」や日付を混ぜた場合である。前に置いたものが毎回変わるので、規則2により後ろの部分も毎回作り直しになる。書き込みの1.25倍を20回払い、読み出しの0.1倍は一度も使わない。
1時間の保持を選ぶと1回目が 9,000×2＋1,000＝19,000 になり、20回の合計は55,100（0.28倍）である。5分の保持より高いが、呼び出しの間隔が5分を超えるなら、こちらでないと2回目から作り直しになる。
数字は条件で変わる。変わらないのは次の形である。固定部の割合が大きく、呼び出しの回数が多いほど利得が出て、固定部に可変の文字列が1つでも混ざると符号が反転する。
境界を引く規則
どこまでを固定部にするかは、内容ではなく更新の頻度で決める。レビュー指示を構成する部分を頻度で分けると、境界は1本に決まる。
| 部分 | 変わる頻度 | 置く位置 |
|---|---|---|
| 判定基準の出所（規約、約束、基準の条文） | 月単位 | 固定部 |
| 対象外の宣言（表記の揺れ、並び順など） | 月単位 | 固定部 |
| 出力項目の定義（1件あたりに書かせる欄） | 月単位 | 固定部 |
| 対象の範囲の書き方（差分だけを見る、など一般の指示） | 月単位 | 固定部 |
| レビュー対象の差分 | 毎回 | 可変部 |
| PR の題名、担当者、日付、PR 番号 | 毎回 | 可変部 |
| 「今回は配送の設定を変えた」のような変更の要旨 | 毎回 | 可変部 |
判断に迷うのは最後の3行である。変更の要旨を基準文書の近くに置くと読みやすくなるので、固定部の末尾に混ざりやすい。混ざった時点で、上の表の3行目の状態になる。
境界を引くときの点検は2つである。固定部を声に出して読んで、今日の PR に固有の語が1つも出てこないこと。そして固定部の長さがモデルの最小トークン数を超えていること。4条の約束だけなら数百字で、claude-opus-5 の512トークンに届かない可能性がある。届いていないときはエラーが出ないので、usage の cache_creation_input_tokens が0のままかどうかで確かめる。
並べ方の雛形
固定部を先に置き、境界でキャッシュを指定する。固定部の中身は自分の規約に置き換える。
## 対象の範囲
貼られた差分だけをレビューする。差分に現れていない行は指摘しない。
## 判定基準の出所
次の4条だけを基準にする。4条に当たらないことは書かない。
1. CI の権限は必要な範囲を超えていないか
2. イメージはダイジェストで固定されているか
3. 公開するポートを外へ出していないか
4. 本番の設定に開発用の既定値が残っていないか
## 出力項目
指摘1件ごとに次の3行を書く。1件も無ければ「指摘なし」と書く。
- 場所: <ファイル:行>
- 条: <1 から 4 のどれに当たるか>
- 主張: <何が問題か。一文>
## 対象外の宣言
表記の揺れ、キーの並び順、コメントの有無は対象外とする。## 今回の差分
（差分を貼る）API から呼ぶ場合は、固定部の最後のブロックに cache_control を付ける。
{
"type": "text",
"text": "（上の固定部の全文）",
"cache_control": { "type": "ephemeral", "ttl": "5m" }
}呼び出しの間隔が5分を超えるなら "ttl": "1h" にする。間隔が1時間を超えるなら、並べ替えても2回目以降の読み出しに届かないので、この提案は効かない。
キャッシュを指定できない環境向けの代替がある。 並べ替えだけを採ることである。固定部を先、可変部を後にして、固定部に今日の語を入れない形は、キャッシュの指定とは独立に保てる。指定できる環境へ移ったときに、境界を1行足すだけで済む。順序を直す作業と、キャッシュを有効にする作業を同時にやらない。
出力の質とは別の話である
並べ替えの根拠は料金だけで、指摘の質については何も言っていない。長い入力の中で基準文書と差分の対応付けがどうなるかは別の問題で、この記事の範囲の外にある。
区別が要るのは、順序を変えた結果として出力が変わったときに、原因を取り違えないためである。固定部を前に出したあとで指摘の傾向が変わったなら、それは並べ替えの効果ではなく、固定部と可変部のあいだに入っていた文を落としたか、位置を変えたことによる。並べ替えのときは、文の削除や書き換えを同時に行わない。
キャッシュを無効にするものが、差分以外にもある。公式ドキュメントによると、思考の設定を変えると（budget_tokens の値や思考のモード）メッセージのキャッシュは無効になる。effort の値を最上位で変えた場合も、前のやり取りで作ったキャッシュには届かなくなる。キャッシュを前提にした会話の途中で、思考量の設定を変えない。 モデルを替えた場合も当然に作り直しになる。
指示文の点検
- 固定部を読んで、今日の PR に固有の語（題名、番号、日付、変更の要旨）が1つも出てこないか
- 判定基準・対象外の宣言・出力項目の定義が、すべて可変部より前にあるか
- 固定部の長さが、使うモデルの最小トークン数を超えているか
usageのcache_creation_input_tokensとcache_read_input_tokensを見て、2回目以降が読み出しになっているか- 呼び出しの間隔に合う保持（5分か1時間）を選んでいるか
- 間隔が保持を超えるなら、並べ替えの利得が無いことを確かめたか
- 思考量の設定を、キャッシュを使う一連の呼び出しの途中で変えていないか
- 並べ替えと同時に、文の削除や書き換えをしていないか
- キャッシュを指定できない環境では、並べ替えだけを採っているか
- 1日の呼び出し回数を数えて、倍率を計算したか
おわりに
プロンプトキャッシュは前方一致で作られ、前に置いたものを変えると後ろが無効になる。だからレビュー指示では、月単位でしか変わらない部分（判定基準、対象外の宣言、出力項目の定義）を先に置き、毎回変わる部分（差分、PR の題名、変更の要旨）を後ろに置く。
この並べ替えが効くのは料金に対してだけで、出力の質とは関係がない。公式の倍率で計算すると、入力10,000トークンのうち9,000が固定部で1日20回回す場合、並べ替えとキャッシュの指定で0.24倍になる。固定部に毎回変わる1文が混ざっていると1.23倍になり、キャッシュを使わないより高くつく。
次に取る行動を1つ挙げる。いま使っているレビュー指示を上から読み、今日の PR に固有の語が最初に出てくる位置に線を引く。その線より上が固定部で、下が可変部である。線より上に固有の語が残っていたら、それを下へ移すだけで並べ替えは終わる。