AIレビューを、
安心の儀式にしない

AIによるコードレビューを工程へ足すと、レビューを通した差分は安全になったように見えます。

ところが、レビューの対象範囲、強度の決め方、1差分あたりの上限、再実行の条件、終了条件を決めていない場合、レビューは品質の検査ではなく、不安を薄めるための儀式になります。

Netsujoでも、同じ差分へレビューを重ね、同種の指摘を人が毎回読み直す状態が発生しました。

結論は次のとおりです。

AIレビューには、レビュー対象の範囲、リスク分類、1差分あたりの予算、再レビュー条件、停止条件を先に決めます。

そして、機械検査のPASSとリスク分類は「どれだけレビューが必要か」を算出するだけにとどめ、実行してよいかどうかの許可とは別レイヤーに置きます。

本記事が扱うのは、レビュー予算、停止条件、再レビューGateという設計側です。レビューを何回まで回すか、どこで終えるか、指摘をどこへ移すかを、感覚ではなく数値と条件で決めます。

Incident Card

INCIDENT:
同じ差分に対するAIレビューへ、範囲・回数・費用・停止条件の定義がないまま運用していた

SYMPTOM:
レビューを繰り返しても指摘が収束せず、同種の指摘を人が毎回読み直していた

FALSE_ASSUMPTION:
レビュー回数を増やすほど品質は上がるので、レビューは多いほど安全である

ROOT_CAUSE:
レビュー対象の範囲、強度の決め方、1差分あたりの上限、再実行の条件、終了条件が実装されていなかった

IMMEDIATE_FIX:
1差分あたりの自動レビュー回数へ上限を置き、上限に達したら自動実行せず人間判断へ渡す

SYSTEM_FIX:
レビュー要求の算出（機械検査・リスク分類）と、実行許可（runtime status・予算・owner認可）を別レイヤーへ分離する

REMAINING_RISK:
上限内でも指摘の質は保証されず、レビュー予算の消費telemetryを観測できない場合がある

レビューを重ねても、指摘は収束しなかった

観測できた事実は次のとおりです。

• 差分ごとにAIレビューを回す運用を始めた
• 同じ差分へ再レビューを重ねると、前回と同種の指摘が再び返ってきた
• 指摘はテキストとして残るが、次の差分へ自動では効かず、人が毎回読み直していた
• レビュー1回あたりの待ち時間と費用が積み上がった
• 「レビューを通した」ことが安心材料になり、通したあとに何が保証されたのかを説明できなかった

削減率や工数の定量比較は未計測です。この記事で確認できるのは、回数上限・対象範囲・停止条件をリポジトリ上の実装として持っている状態までです。

誤った前提：レビューは多いほど安全である

レビューは無料ではありません。時間、費用、待ち時間、そして人の注意力という有限資源を消費します。

回数上限のないレビューは、実質的に「終了条件が存在しない」ことと同じです。終了の判断を人の感覚へ委ねると、条件は「不安が消えたら」になります。これは条件ではありません。同じ差分へ何度でも回せてしまいます。

もう一つの誤りは、レビューの出力を保証と読むことです。レビューが返すのは指摘であって、正しさの証明ではありません。

根本原因：レビュー要求と実行許可が同じ層にあった

最初の設計では、機械検査がPASSしたら自動でレビューを呼んでいました。この形では「検査PASS＝実行許可」になります。

現在のリポジトリでは、この2つを明示的に分離しています。scripts/quality/run-quality-gate.mjsの冒頭には、機械検査とリスク分類はレビュー需要を計算するだけであり、runtime実行を許可しないと書かれています。

.quality/codex-review-policy.jsonにも同じ規則が入っています。

executionAuthorization:
  source: .claude/agent-os/vendor/runtime-tools.json
  rule:   classification_or_machine_check_pass_never_authorizes_runtime_execution
  missingTelemetry: unknown_not_invented

レビューが必要かどうかと、いま実行してよいかどうかは、別の問いです。前者は差分から計算できます。後者はruntimeの状態、予算、認可に依存します。

その場の対処：1差分あたりの回数上限を置いた

まず、自動レビューを何回まで回してよいかを決めました。判定はscripts/quality/prepare-codex-review.mjsのdecideCodexEligibilityに集約されています。残っている門は3つだけです。

if レビュー対象の変更ファイルが0件:
    NOT_ELIGIBLE

if 機械検査が未実施:
    NOT_ELIGIBLE   # 先に quality gate を PASS させる

if 機械検査が FAIL:
    NOT_ELIGIBLE   # 直してから再実行する

if reviewCount >= maxReviewsPerPullRequest:
    NOT_ELIGIBLE   # 以降は自動実行せず人間判断

else:
    ELIGIBLE

maxReviewsPerPullRequestは.quality/codex-review-policy.jsonで3です。

ただし、この3はレビュー需要を算出するbundle準備側のループ上限です。同じファイルのlimitsNotesは、この値を「bundle準備のために残している需要ループの歯止め」と説明し、実行してよいかどうかは別レイヤーが持つと明記しています。実行可否は.claude/agent-os/vendor/runtime-tools.jsonにあるruntimeの可用性と予算が決めます。上限値と実行許可を同じ層に置かないことが、この設計の要点です。

差分の大きさでは止めていません。サイズ上限で止めると、大きい差分ほどレビューされないという逆転が起きるためです。代わりにlargeDiffFiles（25ファイル）とlargeDiffChangedLines（800行）を助言値として持ち、超えた場合は「分割したほうが指摘精度は上がる」と警告だけ返します。

仕組みへの変換：レビューを5つの層へ分ける

レビューを一つの塊として扱うと、上限も停止条件も置けません。次の5層へ分けます。

review scope：読ませないものを先に決める

対象範囲は「何を読ませるか」ではなく「何を読ませないか」から決めます。policyのexclude.pathsには.next/**、node_modules/**、coverage/**、**/*.min.js、**/*.map、画像やフォントなどのバイナリが並びます。除外したファイルは件数だけ報告します。

package-lock.jsonはmanifestOnlyとして扱います。全文は渡しませんが、依存変更のシグナルとしては数えます。

渡すのは差分限定のbundleだけです。リポジトリ全体を探索させると、入力量が差分と無関係に膨らみ、予算の見積りが成立しません。

risk classification：判断不能を安全側へ倒す

classify-change-risk.mjsはファイル単位でリスクを割り当てます。設計上重要な点は2つです。

• テストファイルはHighパターンへ一致してもMedium止まりにします。本番挙動を直接変えないためです。本番コードが同時に変わっていれば、そちらの判定でHighになります。
• ルールに一致しないファイルはLowへ落とさずMediumにします。判断できないことを、安全だと読み替えません。

分類の用途は推論強度の選択です。reasoning.highCategoriesにはauth、billing、db-schema、data-destruction、customer-data、env-deploy、signal-diagnosis、infrastructureの8カテゴリが入っています。それ以外はmediumです。

review budget：入力量と出力量の両方へ上限を置く

回数だけを絞っても、1回あたりの入出力が青天井なら費用は止まりません。policyは両側へ上限を持ちます。

出力側へ上限を置く理由は費用だけではありません。指摘が数十件返ると、人は上から順に読んで疲れます。指摘件数の上限は、読む側の予算でもあります。

rerun条件：再レビューの入口を1つに固定する

再レビューは「気になったから」では起動しません。起動条件は次に固定します。

1. レビュー対象の変更が存在する
2. 機械検査が実施済みでPASSしている
3. この差分の自動レビュー回数が上限未満である

機械検査がFAILしている状態でレビューを回すと、機械で判定できる問題をAIに読ませることになります。順序は逆にしません。

exit condition：終わり方を先に書く

停止条件は次の3つだけです。

EXIT_1: レビュー対象の変更が無い
EXIT_2: 自動レビュー回数が上限（3回）に到達した → 以降は人間判断
EXIT_3: 実行許可が無い（runtime status / 予算 / owner認可）

「指摘が0件になったら終わり」も停止条件にはしません。0件は観点の外に問題が無いことの証明ではないためです。終了は回数と状態で決めます。

指摘をtest・CI・Gateへ移す

レビュー予算を守る最大の方法は、同じ指摘を二度と人へ届かせないことです。指摘は性質ごとに移し先が違います。

レビューの価値は、指摘を出したことではなく、その指摘が次から機械側で止まる状態へ移ったことにあります。移せない指摘だけが、人の読む対象として残ります。

予算を使い切ったとき、何を止めて何を残すか

停止の設計で間違えやすいのは、停止を能力の剥奪と同一視することです。このリポジトリの正本.claude/agent-os/vendor/runtime-tools.jsonでは、Codex runtimeのstatusがemergency_stopped、reason_codeがCODEX_SPEND_EMERGENCY_STOPである一方、capability_revokedはfalseです。停止は一時的なruntime状態であり、reviewerやimplementerとしての資格は保持しています。

止まる操作と残る操作も分けています。

再開は既定で拒否です。例外はowner_authorization_id、token_budget_snapshot、spend_budget_remaining、exact_scope、expected_sha、spend_cap_usd、expires_atの全項目が同時に揃い、期限とSHAとscopeが一致するときだけ成立します。

観測できない予算値は推測で埋めません。実際のscoped overrideにはtoken_budget_snapshotとspend_budget_remainingがUNOBSERVABLEとして記録され、invented: falseが併記されています。予算が見えないことと、予算が十分にあることは別です。

再利用できるチェックリスト

1. レビュー対象へ含めないパスを列挙してあるか
2. 生成物・build成果物・バイナリを除外しているか
3. リスク分類が「判断不能」を安全側（Low以外）へ倒しているか
4. 1差分あたりの自動レビュー回数へ上限があるか
5. 上限到達後に何が起きるかを決めてあるか
6. 出力側（指摘件数・語数）へも上限があるか
7. 再レビューの起動条件が「機械検査PASS後」に固定されているか
8. 指摘の移し先（test / CI / Gate / 人間）が決まっているか
9. レビューの実行回数と入出力量を記録しているか
10. 実行許可が、レビュー要求の算出とは別レイヤーにあるか

10番が最後に残る要点です。ここが同じ層にあると、検査を通すこと自体が実行の理由になります。

Evidence

適用限界

• ここで示した数値はNetsujoの運用目安であり、普遍的な正解ではありません。
• レビュー費用や工数の削減効果は未計測です。この記事は上限と停止条件を持つ状態までを扱います。
• 予算の消費量を外部から観測できない場合があります。実際にUNOBSERVABLEとして記録されている項目があります。
• 決定の正本は移動します。2026-08-11の全件レビュー方針は2026-08-21のruntime policyへ置き換えられました。過去の決定文書を現在の運用として読まないでください。

残るリスク

• 上限内で実行しても、指摘の質は保証されません。回数の設計は、内容の正しさとは別です。
• 大きい差分ほど指摘精度は落ちます。サイズで止めない設計は、その代わりに警告と分割判断を人へ残しています。
• 指摘をtest・CI・Gateへ移す作業自体に工数がかかります。移す価値のない指摘まで機械化すると、検査の維持費が増えます。
• 停止条件を厳しくしすぎると、必要なレビューまで止まります。停止は一時状態として扱い、再開条件を先に書いておく必要があります。
• レビューを通した差分が安全である、という読み替えは設定では防げません。何を検査していないかを毎回書き残す運用が要ります。

まとめ

AIレビューを増やしても、範囲・分類・予算・再実行条件・停止条件が無ければ、レビューは安心の儀式になります。

review scope
+
risk classification
+
review budget（回数・入力量・出力量）
+
rerun条件
+
exit condition
+
指摘の移し先（test / CI / Gate / 人間）

この6つを先に決め、レビュー要求の算出と実行許可を別レイヤーへ置きます。終わり方を先に書いていないレビューは、終われません。

よくある質問

レビュー回数の上限は3回が適切ですか

Netsujoの運用目安です。普遍的な正解ではありません。指摘が収束しない差分は、回数を増やすより分割したほうが精度は上がります。上限到達後に人間判断へ渡した回数を記録し、実データで調整してください。

指摘が0件なら、レビューを終えてよいですか

0件は「その観点では見つからなかった」という意味です。正しさの証明ではありません。停止条件は回数と状態で決め、0件をもって安全と記録しません。

リスク分類でLowと判定された差分はレビュー不要ですか

分類の用途を、呼ぶか呼ばないかの判断に使うと、分類自体が外れたときに何も検出されません。現在の実装では、分類は推論強度の選択に使い、機械検査がPASSした差分は内容と大きさによらずレビュー対象にします。

AIレビューを止めているあいだ、品質はどう担保しますか

停止するのは実行であって、役割ではありません。機械検査は止めずに回し、機械で判定できない部分は人間のレビューへ戻します。

指摘をtestへ移す判断はどうしますか

同じ種類の指摘が2回出たら移す、を目安にします。1回目は個別の学びです。2回目からは、人の注意力ではなくシステムの欠陥として扱います。