TL;DR
AIレビューは便利ですが、指摘された箇所だけを直して再レビューすると、次のレビューで似た問題が別の場所から出てきます。
そこで、レビュー結果を受けたAIが、指摘箇所だけでなく類似箇所まで確認し、さらに自分の修正自体も反証するようにAGENTS.mdの規約を変えました。
それでも再レビュー回数は思ったほど減りませんでした。
最終的には、同じ原因や守るべき条件に関する問題が複数の場所で繰り返されたら、AIが個別修正を続けず、構造そのものを見直すようにしました。
狙いはレビューを厳しくすることではなく、一度のレビューから得た情報で、次のレビューを減らすことです。
この記事で扱うこと
AIDD Skeletonでは、AGENTS.mdをAIエージェントが従う開発規約として使っています。
この記事で扱うのは、レビューAIそのものの精度を上げる話ではありません。
外部AIからレビュー指摘を受けた後、実装側AIがどこまで自律的に原因調査・修正・類似確認・反証まで進めるかを、AGENTS.mdの規約によって改善していった話です。
自分の開発では、実装やドキュメント変更の多くをAIエージェントに任せています。
実装側AIが変更と検証を行い、その結果をCodexやClaudeなどの別AI、あるいは別セッションでレビューします。
レビュー結果が返ってきた後も、人間が指摘を一件ずつ読み、
ここを直して
次はここも見て
と逐次指示する運用にはしたくありませんでした。
レビュー結果を受けた実装側AIが、AGENTS.mdに従って、
- 指摘の妥当性を確認する
- 必要な修正を行う
- 類似する問題がないか調べる
- 修正そのものを反証する
- 必要なら構造的な見直しへ進む
ところまで自律的に進めることを狙っています。
人間
│
│ 目的・作業範囲・権限・最終的な採否
▼
AGENTS.md
│
│ AIが従う行動規約
▼
実装側AI
│
│ 実装・変更・検証
▼
レビュー側AI
│
│ 指摘
▼
実装側AI
│
│ AGENTS.mdに従って自律的に
│ 修正・類似確認・反証・再評価
▼
必要なら再レビュー
人間が持つのは、何を作るか、どこまで変更してよいか、重要な判断を採用するかといった権限です。
この記事は、その境界を保ったまま、レビュー後のAIの動きをどこまで自律化できるかを詰めていった記録でもあります。
最初は、指摘された場所だけを直していた
AIレビューそのものはかなり便利です。
自分では見落としていた矛盾や境界条件、検証不足を普通に見つけてくれます。
ただ、しばらく使っていると別の問題が出てきました。
レビュー対応が終わらない。
初期の規約では、レビューで問題が見つかると、実装側AIはその指摘を解消します。
その変更を再レビューすると、今度は少し隣の問題が見つかる。
実装側AIはまたそれを直す。
さらに再レビューすると、また別の問題が出る。
レビュー1回目
Aを指摘
実装側AI
Aを修正
レビュー2回目
Bを指摘
実装側AI
Bを修正
レビュー3回目
Cを指摘
A、B、Cは別々の指摘に見えます。
でも、あとから見ると同じ原因だった、ということが結構ありました。
AIはその都度きちんと問題を直しています。
問題は、レビューから得られた情報を、その一件の修正にしか使っていなかったことでした。
その結果、外部レビューを何度も回す必要がありました。
レビュー料金や利用枠も消費しますが、それ以上に、人間がレビューの収束を待ち続ける時間も増えます。
この頃から、
最初の指摘が来た時点で、AI自身がもう少し先まで処理できないか？
と考えるようになりました。
指摘された場所だけ直すのをやめた
最初にやった改善はかなり素朴です。
レビュー指摘を受けたAIが、その箇所だけを直すのではなく、
- 同じ原因の箇所が他にもないか
- 同じ「守るべき条件」を持つ類似箇所はないか
- もっと上位の仕様や設計に原因がないか
まで確認するようにしました。
レビュー指摘
↓
実装側AIが原因を確認
↓
指摘箇所を修正
↓
類似箇所も確認
↓
必要なら同じ原因の問題をまとめて修正
同じ原因の問題は、必要な範囲でまとめて整合的に直す。
AIDD Skeletonでは、この考え方をCoherent Correctionとして入れました。
関連コミット
docs: restructure root governance boundaries
重要なのは、調査範囲と修正範囲を分けたことです。
AIは原因を理解するために周辺まで調べてよい。
ただし、調べた結果見つかった改善を何でも現在の作業へ取り込んでよいわけではありません。
現在の作業範囲で必要なものだけを修正する。
それ以外は、勝手に作業範囲へ追加しない。
AIの自律性を上げても、作業範囲まで勝手に広げないための境界です。
そもそも、レビュー指摘を全部直すわけでもない
類似箇所まで自律的に調べるようにすると、別の危険も出てきます。
レビュー側AIは、明らかな問題だけでなく改善案もかなり出します。
実装側AIがそれを全部、
指摘されたから直す
と扱えば、今度は作業範囲が際限なく広がります。
そこで、指摘が妥当かどうかと、今回どう扱うかを分けるようにしました。
例えば指摘の位置づけとしては、
作業を止める重大な問題
今回の範囲で直す必要がある問題
今後の改善候補
に分けます。
そのうえで、
今直す
採用しない
後回しにする
を別に判断します。
将来的には改善した方がよい。
でも今回の受け入れ条件には必要ない。
その場合、実装側AIは現在の修正へ勝手に取り込みません。
レビュー
↓
改善案を全部採用
↓
変更範囲が広がる
↓
レビュー対象が増える
↓
再レビューも増える
という状態を避けるためです。
この部分は、PR #30でレビュー結果全般の扱いとして整理しました。
PR #30: docs: govern feedback triage and review recall
AIに自律的なレビュー対応を任せるなら、何を自分で直してよく、何を勝手に現在の作業へ追加してはいけないかも同時に必要でした。
修正したら、その修正自体も疑う
類似箇所まで見るようにすると、かなりマシになりました。
ただ、それでも次のレビューで新しい問題が出ます。
理由の一つは、AI自身が行った修正そのものが、新しい問題を作ることがあるからです。
例えば、
指摘:
代替処理がない
実装側AIの修正:
代替処理を追加
とします。
元の指摘には答えています。
でも今度は、
代替処理そのものが失敗したら？
途中まで成功したら？
通常処理と同時に動いたら？
元々守りたかった条件を壊したら？
という問題が生まれる可能性があります。
そこで、AIが修正を終えた時点で完了とはせず、自分の修正自体を反証するようにしました。
この修正が間違っているとしたら、どう壊れるか
をAI自身が考えます。
さらに、レビュー指摘や検証失敗を単なる修正命令ではなく、見落としていた観点を知らせる手がかりとして扱うようになりました。
これが後のAdversarial Self-Reviewにつながっています。
関連PR
PR #31: docs: replace formal review with recursive adversarial self-review
例えば、
実際の保存先を使った検証が足りない
という指摘が来たとします。
実装側AIは、その一件へ実保存先のテストを追加するだけでは終わりません。
まず、
模擬的な検証結果を、実際の保存先で確認した証拠として扱っていないか
という見落としの観点を取り出します。
そして、その観点を関連する処理にも当てます。
レビュー指摘
↓
AIが「なぜ見落としたか」を分析
↓
不足していた観点を取り出す
↓
関連箇所にも同じ観点を適用
↓
必要な修正を行う
↓
その修正自体も反証
ここまでを、人間がレビューのたびに追加指示するのではなく、AIが従う規約へ入れていきました。
それでも、あまり状況が変わらなかった
ここまでで、レビュー指摘を受けたAIは、
指摘箇所を修正
↓
類似箇所も確認
↓
修正自体も反証
まで自律的に進むようになりました。
最初よりは明らかに良くなっています。
でも、再レビュー回数が劇的に減ったかというと、そうでもありませんでした。
まだ次のレビューで、
今度は別の場所に同じ種類の問題があります
と指摘される。
AIは目の前の問題への対応能力をかなり上げています。
それでも似た問題が続く。
ここでようやく、
目の前の問題への対応を強化するだけでは足りないのでは？
と考えるようになりました。
同じ種類の問題が何度も出るなら、原因は個別の箇所ではないかもしれません。
例えば、
- 本来守るべき条件が規約や設計に書かれていない
- 責任分担がおかしい
- 検証方法そのものが弱い
- 機能の分け方がおかしい
- 作業範囲の切り方がおかしい
といった、もっと上の構造に原因がある可能性があります。
ただし、毎回そこまで広く見るわけではない
最初からAIへ、
毎回リポジトリ全体を見て構造から考え直せ
と要求すると、今度は一回の作業自体が重くなります。
そこで、個別対応から構造の見直しへ切り替える条件を規約に入れました。
指摘A
↓
AIが修正 + 類似確認 + 反証
指摘B
↓
また同じ原因に関係している
指摘C
↓
別の場所でも同じ原因が出る
↓
AIが「個別問題ではない」と判断
↓
構造そのものを見直す
関連する指摘や修正が、別々の場所で同じ、または近い原因や守るべき条件を繰り返し示したことが切り替えの合図です。
ここでAIは、
A、B、Cをそれぞれ直せばよい
という判断をやめます。
見る対象を一段上へ移します。
個別の指摘
↓
同じ種類の失敗
↓
本来守るべき条件
↓
責任分担・機能の分け方・検証方法
具体的には、
- 暗黙になっている条件を明示すべきではないか
- 責任分担が間違っていないか
- 機能の分け方が不自然ではないか
- 検証方法や証拠の考え方自体が弱くないか
- 作業範囲の切り方が問題を生んでいないか
まで見直します。
個別修正ではなく、構造そのものを見直す段階です。AIDD Skeletonでは、これをStructural reassessmentと呼んでいます。
関連PR
PR #32: docs: compact adversarial self-review escalation
重要なのは、人間が「そろそろ全体を見て」と指示するまで待たないことです。
同じ原因の問題が繰り返し出ていること自体を、AIが構造見直しへ移る合図として扱います。
コード以外でも、同じ現象が起きた
ここまでの説明はコードレビューにもそのまま当てはまりますが、AIDD SkeletonではAIエージェント自身が従う規約ドキュメントを整理・圧縮したときにも、まったく同じ現象が起きました。
Adversarial Self-Reviewの規約が長くなってきたため、AI自身が内容を整理・圧縮する変更を行いました。
最初は、複数のルールを4項目程度へまとめる方向でした。
docs: compact adversarial self-review escalation
ところが外部AIレビューを通すと、意味が一つ抜けていました。
実装側AIはその指摘を受けて修正します。
再レビューすると、今度は別の意味が抜けていました。
実装側AIがまた修正します。
実際には、
- なぜ最初のレビューで見落としたのかを診断する条件
- 新しい情報が出たときにレビューへ戻る条件
- 最初のレビュー範囲をどこまで広げるか
- 大きな修正後に広いレビューへ戻る条件
- 指摘を次の検査観点として扱う条件
などが、レビューを重ねるたびに不足として見つかりました。
規約を圧縮
↓
レビューで意味Aの欠落
↓
AIがAを復元
↓
再レビューで意味Bの欠落
↓
AIがBを復元
↓
さらに意味Cの欠落
これは、まさにこの記事の最初に書いた状態です。
実装側AIは各指摘へ正しく対応していました。
でも、同じ種類の意味落ちが別の箇所から繰り返し出ています。
そこで、
「抜けた文言を一つずつ戻す」のではなく、「4項目へ圧縮する」という構造自体が問題なのでは？
と見直す方向へ進みました。
個別修正を続けるのをやめ、レビュー規約が持つ責任そのものを分け直しました。
最終的には、
- 最初の反証レビュー
- 指摘から見落とした観点を取り込む
- 修正自体を反証する
- どこまでレビューを続け、いつ広く見直すか
- 同じ原因が続いた場合に構造を見直す
という役割をそれぞれ明示する形になりました。
docs: separate adversarial review responsibilities
構造を見直すために作った規約が、自分自身にも構造の見直しを要求したことになります。
考え方だけでなく、AIが従う規約として残した
この仕組みは、自分がレビューするときの心得だけにはしていません。
次のAIエージェントも同じ判断を自律的にできるよう、AGENTS.mdへ明文化しています。
例えば、修正後の扱いについて実際の規約には次のルールがあります。
“Treat a material correction ... as a new adversarial surface.”
大きな修正そのものを、新しく反証すべき対象として扱うという意味です。
さらに、構造の見直しへ切り替える条件も明文化しています。
“findings or corrections repeatedly expose the same or closely related cause”
同じ、または近い原因が繰り返し出たら、それらを個別問題として処理し続けません。
AIは、暗黙になっている条件、責任分担、機能の分け方、検証方法などへ視点を上げます。
実際の規約はこのコミットで確認できます。
docs: separate adversarial review responsibilities
つまり、
人間がレビュー結果を見て、次に何を調べるか毎回AIへ指示する
運用から、
AIがレビュー結果を入力として受け、自分で次の調査・修正・反証・構造見直しを判断する
運用へ寄せていったわけです。
増やしたかったのはレビュー工程ではない
振り返ると、実装側AIの動きは、
局所修正
↓
類似箇所まで対応
↓
修正そのものを反証
↓
同じ原因が繰り返されたら構造を見る
と増えています。
一見すると、AIへ要求する作業をどんどん増やしたように見えます。
でも、目的は逆です。
外部AIへ再レビューを依頼する回数を減らしたかった。
高性能なレビュアーを使っても、
指摘A
↓
実装側AIが修正
↓
再レビュー
↓
指摘B
↓
実装側AIが修正
↓
再レビュー
を続ければ高くつきます。
人間が逐次修正指示を出さなくても、レビューのたびに外部AIを呼び直すコストは残ります。
逆に、一度の指摘から実装側AIが、
原因
類似箇所
不足していた観点
修正によって新しく起こり得る問題
構造上の共通原因
まで拾えれば、次の外部レビューで新しく出てくるものを減らせます。
だから今は、
一回のレビューで何件指摘されたか
より、
一回のレビューを受けて、実装側AIがどこまで自律的に問題を潰し切れるか
の方を重視しています。
レビューの目的も少し変わった
最初は、
レビュアーの指摘を全部なくす
ことがレビュー対応の終了条件に近かったです。
今は違います。
今後の改善候補が残ることもあります。
後回しにすることもあります。
採用しない提案もあります。
それでも、
- 現在の受け入れ条件を満たしている
- 必要な検証がある
- 今回の範囲で未解決の重大な問題がない
- 最新の修正によって、新しく確認すべき重大な壊れ方が残っていない
- 同じ原因の繰り返しによって、まだ構造を見直すべき兆候が残っていない
のであれば、現在の変更は受け入れられます。
すべての改善余地をなくすことと、現在の仕事を完成させることは別です。
AIレビューをかなり使うようになって、一番変わったのはここかもしれません。
レビュー側AIを強くすることだけではなく、
一度受けた指摘を、実装側AIが次の指摘を減らす材料として使えるようにする。
その方が、品質にもコストにも効きました。
AIDD Skeleton:
関連PR / コミット
- docs: restructure root governance boundaries
- PR #30: docs: govern feedback triage and review recall
- PR #31: docs: replace formal review with recursive adversarial self-review
- PR #32: docs: compact adversarial self-review escalation
- docs: separate adversarial review responsibilities
※この記事は筆者自身の開発経験・判断・問題意識をもとに、生成AI（ChatGPT）との対話を通じて構成・文章化しています。