AIエージェントに実装を任せ始めると、次に詰まるのは「レビューもAIに任せてよいのか」です。自己レビューをさせれば十分なのか、browserで画面確認までさせるべきなのか、Claude Code code review や ultrareview をどこで使うのか、最後に人間は何を見ればよいのか。この順番を決めないまま導入すると、レビューが増えたのに merge 判断はむしろ曖昧になります。
この記事では、AI review harness を AIエージェントが作った差分を、段階的な検証レーンに流す設計 として整理します。Harness Engineering の全体像は Harness Engineering とは？、Codex の画面確認は Codex browser use ガイド、Claude Code のPRレビュー機能は Claude Code code review 実践ガイド、最後の受け入れ判断は Codex レビュー完了ゲート設計ガイド に分けています。
今回扱うのは、自己レビュー、決定論的検証、browser検証、深いPRレビュー、人間ゲート のつなぎ方です。
先に結論: review harness は4段に分ける
AIレビューは、強いレビュー機能を1つ選ぶ話ではありません。実務では次の4段に分けた方が安定します。
| 段階 | 目的 | 代表的な手段 | 通してよい差分 |
|---|---|---|---|
| Self check | エージェント自身に明白な漏れを直させる | checklist、local /code-review、lint、test | 小さな実装、文言、軽い修正 |
| Evidence check | 動作証拠を集める | test log、screenshot、browser use、trace | UI、API、権限、状態遷移 |
| Deep review | 人間が読み飛ばす欠陥を探す | Claude Code Code Review、ultrareview、security scan | auth、billing、migration、権限変更 |
| Human gate | merge / deploy の責任を確定する | diff、work log、証跡、残リスク確認 | すべて |
私なら、AIが作った差分をいきなり「AIレビュー済み」とは呼びません。まず本人にチェックさせる。次に実行結果を出させる。リスクが高ければ別のレビューlaneに回す。最後に人間が受け入れ条件だけを見る。この順にします。
review_harness:
self_check:
required:
- scoped_diff_summary
- changed_files_reason
- local_tests_or_reason
evidence_check:
required_when:
- ui_change
- api_contract_change
- permission_or_auth_change
deep_review:
required_when:
- auth
- payment
- data_migration
- external_write
- security_boundary
human_gate:
required:
- scope_match
- verification_log
- unresolved_risk
- rollback_or_revert_planポイントは、レビューを「感想」ではなく 状態遷移 にすることです。どの条件を満たしたら次の段へ進むのか、どこで止めるのかを明示します。
なぜAIレビューだけでは足りないのか
OpenAI の Harness Engineering 記事では、エージェントがPRを作り、ローカルレビューや追加のagent reviewを依頼し、フィードバックへ応答しながら反復する運用が説明されています。同時に、UI、ログ、メトリクスをエージェントが読める形にする重要性も書かれています。
ここから分かるのは、レビュー品質はモデル単体ではなく、レビュー対象を読める形にしているかで決まるということです。diffだけを読ませるより、起動手順、失敗ログ、画面状態、trace、受け入れ条件を渡した方がレビューは具体的になります。
Harness Engineering の原型を説明したブログでも、失敗したら「次回から同じ失敗を防ぐ仕組み」を作ること、AGENTS.md のような指示と、スクリーンショットやテストのような実際のツールを組み合わせることが強調されています。
つまり review harness は、次のようなものです。
- レビュー観点を毎回プロンプトで思い出させない
- 画面やログを人間の感想ではなく証拠として残す
- AIレビュー結果をそのまま承認にしない
- 高リスク差分だけ深いレビューへ昇格する
- 最後の責任境界を人間側に残す
「AIがレビューしたからOK」ではなく、「AIがどの証拠を見て、どの条件まで確認したか」を残す設計です。
Self check: まず本人に戻す
最初のレビューは、差分を作ったAIエージェント自身に戻します。ただし、自由文で「確認して」では弱いです。
Before finalizing, run a self check:
- List the files you changed and why each file was necessary.
- Confirm the request scope did not expand.
- Run the existing relevant verification command, or explain why no command exists.
- Identify one plausible regression and how you checked it.
- Do not claim browser verification unless you actually opened the page.この段階の目的は、深い欠陥探しではありません。明白なスコープ逸脱、検証漏れ、説明不能な変更をその場で落とすことです。
私がよく使う判定は次です。
| 観点 | 通す条件 | 止める条件 |
|---|---|---|
| scope | 依頼されたファイル・機能に収まっている | unrelated refactor が混ざる |
| verification | 既存コマンドを実行済み、または未実行理由が具体的 | 「たぶん動く」だけ |
| regression | 影響範囲を1つ以上言語化できる | 影響範囲を答えられない |
| evidence | log、diff、screenshot などがある | 最終報告だけがある |
local /code-review のような軽いレビューは、この self check と相性がよいです。PR全体の深い監査ではなく、作業中に「この差分は明らかに危ないか」を早く見る用途に寄せます。
Evidence check: 画面・ログ・テストをレビュー可能にする
AIレビューが弱くなる典型は、レビュー対象がdiffだけのときです。UI変更なら実画面、API変更ならrequest / response、非同期処理ならlog、権限変更なら拒否ケースの証拠が必要です。
Codex browser use のような仕組みは、ここで使います。目的は「AIにブラウザを触らせること」ではなく、画面状態を review artifact にすることです。
evidence_packet:
branch: feature/settings-overflow
route: http://localhost:4321/settings/billing
viewport: 390x844
state: over_quota_warning
checked:
- no_horizontal_scroll
- warning_text_does_not_cover_cta
- console_has_no_new_error
artifacts:
- screenshot_mobile_settings_billing.png
- pnpm_build_log.txt
not_checked:
- production_billing_submitこの粒度で残すと、人間は「本当に画面を見たのか」を聞き直さずに済みます。逆に、次のような報告は review harness では証拠不足です。
UIを確認しました。問題ありません。どのURLか、どのviewportか、どの状態か、何を未確認にしたかがないためです。
Deep review: 高リスク差分だけ別laneへ昇格する
Claude Code の Code Review docs では、PRに対して複数の専門agentが並列に確認し、logic error、security vulnerability、edge case、regression を探す仕組みとして説明されています。一方で、PRをapproveしたりblockしたりするものではなく、既存のレビューworkflowを保つ前提です。
ultrareview はさらに深いレビューlaneです。公式docsでは、/code-review ultra が remote sandbox で reviewer agent fleet を起動し、通常のlocal /code-review より広いcoverageと独立検証を狙うものとして説明されています。ただし、研究preview、利用条件、費用、投稿可否、diff上限があります。
ここで重要なのは、すべてのPRを深いレビューに回さないことです。深いレビューは強いですが、遅く、費用があり、結果を読む負荷もあります。
私なら次の条件で昇格します。
| 昇格条件 | 使うレビュー | 理由 |
|---|---|---|
| auth / permission / billing | Code Review + ultrareview | 読み飛ばしの影響が大きい |
| migration / data repair | ultrareview +人間確認 | rollback不能な副作用がある |
| public UI の重要導線 | browser evidence + Code Review | 見た目とロジックの両方が必要 |
| security boundary | security scan + Code Review | 専用toolとPR reviewの責務が違う |
| 文言・小さなCSS修正 | self check + browser evidence | 深いレビューの費用対効果が低い |
AIレビューを重ねるほど安全になる、とは限りません。どのレビューが何を見たかが重複し、誰も最終判断しない状態になるからです。深いレビューは「重要差分を止めるための昇格先」として使います。
Human gate: 人間は全部を読み直さない
review harness を作る理由は、人間がすべてのdiffを最初から読み直すためではありません。人間が見るべきものを絞るためです。
最後に人間が見るのは、次の4つで十分なことが多いです。
- 依頼範囲とdiffが一致しているか
- 検証証跡が対象状態を覆っているか
- AIレビューの未解決findingが残っていないか
- merge後に戻す手段があるか
テンプレートにするとこうです。
## Human review gate
Scope:
- Requested:
- Changed:
- Out of scope:
Evidence:
- Commands:
- Browser / screenshot:
- Logs / traces:
AI reviews:
- Self check:
- Code Review:
- Ultrareview:
- Security scan:
Decision:
- Accept:
- Hold:
- Rollback / revert plan:この gate で Accept に進めないなら、AIに「直して」と戻すより、どの段階へ戻すかを指定します。
| 問題 | 戻す先 |
|---|---|
| 依頼範囲から外れている | Self check |
| 画面証拠が足りない | Evidence check |
| 重要findingが残っている | Deep review後の修正 |
| merge後の戻し方がない | Human gateで保留 |
戻し先を決めると、AIエージェントは同じ修正を雑に繰り返しにくくなります。
REVIEW.md と AGENTS.md は分ける
review harness を作るとき、すべてを AGENTS.md に入れたくなります。これは早い段階で破綻します。通常の作業指示、コマンド、禁止事項、レビュー観点、PRテンプレートが1つに混ざると、エージェントも人間も読みません。
私は次のように分けます。
| ファイル | 役割 | 書く内容 |
|---|---|---|
AGENTS.md | 作業全体の共通ルール | コマンド、禁止操作、Git運用、応答方針 |
REVIEW.md | レビュー専用の観点 | 重点リスク、severity、見なくてよいstyle指摘 |
| PR template | 人間の受け入れ判断 | 検証、スクリーンショット、rollback |
| scripts | 決定論的な検証 | lint、test、schema check、screenshot取得 |
レビュー専用の判断は REVIEW.md に寄せます。たとえば、style nit を出しすぎるAIレビューなら、REVIEW.md に「style only の指摘は出さず、bug / security / regression を優先」と書きます。逆に、絶対に落としたい禁止操作は自然言語ではなく script や permission に寄せます。
小さく始める設定例
最初から全自動レビュー基盤を作る必要はありません。私なら、最初の1週間は次だけにします。
week_1_review_harness:
required_for_every_ai_change:
- self_check_summary
- verification_command_or_reason
- changed_files_reason
required_for_ui_change:
- local_url
- viewport
- screenshot_or_browser_comment_summary
required_for_high_risk_change:
- second_ai_review
- unresolved_findings_list
- rollback_plan
human_gate:
- scope_match
- evidence_match
- final_accept_or_holdここで運用して、実際に漏れたものだけを追加します。毎回「テストを忘れる」なら command を固定する。毎回「画面を見たと言うだけ」なら browser evidence を必須化する。毎回「PRでstyle指摘だけ増える」なら REVIEW.md を直す。この順番が Harness Engineering です。
よくある失敗
1. AIレビューを承認者にしてしまう
AIレビューはfindingを出す役です。承認者ではありません。特に外部write、権限変更、顧客データ、課金、認証は、人間のaccept条件を残します。
2. browser確認を「見た」だけで終える
画面確認は、URL、viewport、state、checked、not_checked まで残して初めてレビュー証跡になります。スクリーンショットがあっても、どのbranchの画面か分からなければ弱いです。
3. 深いレビューを普段使いする
ultrareview や深いmulti-agent reviewは、高リスク差分に絞る方が続きます。小さな修正まで毎回回すと、費用、待ち時間、finding消化で運用が止まります。
4. 失敗した段階を記録しない
レビューで見つかった問題が、self check不足なのか、evidence不足なのか、deep reviewでしか見つからない性質なのかを残さないと、次回の改善につながりません。
review_failure_log:
finding: "mobile CTA was hidden behind sticky footer"
caught_by: human_gate
missed_by:
- self_check
- browser_evidence
fix_to_harness:
- require mobile viewport screenshot for checkout route
- add sticky footer overlap item to REVIEW.mdこの記録があると、次回から同じ失敗を防ぐ仕組みにできます。
まとめ
AI review harness は、AIレビュー機能の寄せ集めではありません。AIエージェントが作った差分を、自己レビュー、証拠化、深いレビュー、人間ゲートへ流すための設計です。
小さく始めるなら、まず self check と verification log を必須にします。UI変更だけ browser evidence を足し、auth / billing / migration / permission のような高リスク差分だけ deep review へ昇格します。最後に、人間はdiff全体を読むのではなく、scope、evidence、unresolved finding、rollback を見ます。
この順番にすると、レビューは「AIにもう一度見てもらう」ではなく、次に同じ失敗を起こさないためのハーネスになります。