multi-review reference
multi-review は PR または local diff を local AI Agent で確認し、必要なら GitHub reviewer、validation、thread 対応まで収束させる review workflow である。
単発で結果だけを受け取りたい場合は review-only、ship を止める material finding だけを探したい場合は adversarial-review を使う。
対象読者と使いどころ
| 項目 | 内容 |
|---|---|
| 対象読者 | PR または local diff のレビューを、複数の確認経路と検証を含めて完了させたい利用者 |
| 目的 | 指摘の採否と必要な修正を記録し、未解決 action がなくなるまで review を進める |
| 代表的な入口 | /multi-review <PR番号>、/multi-review local、実装 workflow の PR 前 local review |
| 得られる結果 | reviewer の finding、検証結果、残っている対応、確認用 report |
まず何が起きるか
- 対象が PR か local diff かを確定する。
agents=は local reviewer、reviewers=は GitHub 上の reviewer / trigger として選ぶ。- reviewer の finding と validation failure を確認し、妥当な問題を修正する。
- 修正した finding の記録、再検証、必要な thread 対応を行い、同じ review cycle を再実行する。
- 最終 simplify、必要な E2E、CI、conflict、unresolved thread が収束したことを report で確認する。
ask-user がなければ、妥当な finding は自動修正し、誤検出、scope 外、nit は理由を記録する。
ask-user がある場合も reviewer 実行までは進め、finding の採否や thread 返信の前で確認する。
Target
PR target
PR 番号、PR URL、または branch を root --pr に渡す。
local reviewer に加え、reviewers= で GitHub reviewer を選べる。
CI、conflict、review thread、latest head も完了条件に含む。
local target
multi-review run --local を使う。
PR thread、GitHub Actions、GitHub reviewer には依存せず、local diff と指定した validation を確認する。
| option | 意味 |
|---|---|
local-phase=standalone / local-phase=pre-pr |
単独 local review か、実装 workflow の PR 前 review かを選ぶ |
base-branch=<branch> |
local diff の起点 branch |
task-context-file=<path> |
Issue、受け入れ条件、検証内容を reviewer に渡す |
--with-history <work-dir> |
前回 run の finding と対応履歴を引き継ぐ |
pre-pr local target は PR 作成前または追加 push 前の local validation / local reviewer gate である。 PR target で同じ HEAD と review context の成功結果を利用できる場合、local reviewer を重ねて起動せず履歴を再利用する。
Reviewer の選択
local reviewer
| 指定 | 意味 |
|---|---|
agents=codex |
Codex local reviewer |
agents=claude |
Claude local reviewer |
agents=copilot |
GitHub Copilot CLI local reviewer |
agents=codex,claude など |
複数の local reviewer |
agents=none |
local reviewer を起動しない |
agents=copilot は GitHub 上の Copilot reviewer ではない。
複数 runtime は同じ Issue context と diff を reviewer ごとに読むため、通常は 1 runtime から始め、高リスク変更だけ coverage を広げる。
GitHub reviewer
| 指定 | 意味 |
|---|---|
reviewers=copilot |
GitHub Copilot reviewer を依頼して結果を待つ |
reviewers=codex |
@codex review を依頼して結果を待つ |
reviewers=codex,copilot / reviewers=copilot,codex |
両方を使う。順序に意味はない |
reviewers=none |
GitHub reviewer を使わない |
reviewers= は GitHub 上の reviewer / trigger selector、agents= は local reviewer runtime selector である。
no-copilot-bot は旧互換の Copilot bot opt-out であり、reviewers= が明示されている場合は reviewers= を優先する。
現 HEAD の既存結果を再利用できる場合は reviewer request を省く。
--force-copilot-request はこの抑制より優先する。
Finding と再検証
reviewer の finding は、修正する fixed、誤検出や scope 外として退ける rejected、軽微な nit、既存実装で解消済みの verified に分けて記録する。
修正した finding には commit と成功した検証を結び付ける。
required severity 未満の finding は report に残るが、review を止めない。
–finding-required-severity critical|high|medium|low で停止対象の下限を指定できる。
| option | 意味 |
|---|---|
–finding-required-severity critical|high|medium|low |
review を止める finding の重大度下限を指定する |
--finding-verify-mode report_only |
修正確認を観測するが完了判定には加えない |
--finding-verify-mode required |
対象 finding の修正確認を完了条件にする |
--finding-verify-scope batch |
最終 review cycle で対象 finding をまとめて確認する |
--finding-verify-scope all |
finding ごとに確認する |
--finding-verify-scope off |
修正確認を起動しない。required mode とは併用できない |
--final-review-cycle |
batch 確認を行う最終 cycle を明示する |
timeout、format failure、許可不足、出力不備は finding なしに数えない。
修正後の review が必要なら、同じ --work-dir または --with-history で履歴をつないで再実行する。
Simplify
| 指定 | 意味 |
|---|---|
simplify=auto |
選択 runtime の 1 つで broad simplify を行う既定値 |
simplify=full |
選択 runtime ごとに code reuse、quality、efficiency を確認する |
simplify=off |
multi-review 内の simplify を行わない |
--final-broad |
他の review action が収束した最終 run で broad simplify を実行する |
multi-review 内の simplify は review phase の coverage であり、実装 workflow の PR 前 agent-simplify とは役割が異なる。
simplify=auto の broad simplify は最終 run で 1 回行う。
中間 run で未実行なら最終 simplify が必要な状態として report に残るため、--final-broad を付けた run まで進める。
Validation と最終確認
| 指定 | 意味 |
|---|---|
validation-mode=auto |
対象に応じた validation を行う |
validation-mode=off |
validation を実行しない |
validation-command=<cmd> |
実行する command を明示する |
validation-profile=<path> |
validation component の構成を指定する |
e2e=final |
通常検証と別に final E2E の結果を確認する |
validation failure は修正して再実行する。
codecov/patch だけが失敗する coverage-only failure は通常 CI failure と分けて扱う。
lint / test / build の失敗を coverage-only failure と同列に扱わない。
final E2E は unit test や local validation で代替しない。 実行不能または方法の判断が必要な場合は、成功扱いにせず利用者の確認へ戻す。
コメント整形
PR target で comment-density component を使うと、追加した Go、JavaScript、TypeScript、CSS、HTML、XML、Vue、Svelte、Astro、Java、Kotlin、Scala、Ruby、Perl、Lua、R、Python、Shell、SQL、YAML、TOML、PHP、C、C++、C#、Rust、Swift、Dart コメントの不足と過剰を観測する。
Go の宣言と JavaScript/TypeScript の function、class、method では、識別子名を言い換えただけのコメントも name_echo として記録する。各 name_echo は canonical language と file の範囲を保持する。SQL、YAML、TOML では name_echo を作らない。
密度が範囲外の file に 20 行以上の追加がある場合、または言い換え godoc が見つかった場合は、該当箇所だけを comment-fixer に渡す。通常の local review では fixer を自動起動しない。branch だけを整形する場合は fix-code-comments を使う。
comment-fixer は comment-fixer-context.v2 の言語、file ごとの範囲、選定理由を使う。Go は非コメント token 列、ほかの対応言語は非コメント byte 列を適用前後で比較する。HTML 系では markup と script / style、Astro frontmatter の境界を分ける。JVM 系では triple-quoted string と doc comment を分け、Kotlin と Scala の nested block comment を分類する。Ruby / Perl の heredoc、Perl POD、Lua long string、R の文字列も通常コメントと分ける。Python の docstring と複数行文字列、Shell の heredoc は string、shebang は code として扱う。SQL、YAML、TOML では quoted value や multiline string の comment marker を文字列として扱う。PHP では HTML text、PHP tag、文字列、heredoc、nowdoc の境界を分ける。C 系では C++ / C# の raw string と preprocessor / compiler directive 行をコメントから分離する。Rust、Swift、Dart では nested block comment を補正する。
文字列、protected directive、cgo preamble、対象外の行を変える patch は拒否する。
automatic mode は test file、生成 path、先頭 20 行に生成 marker がある file、平均非空行長が 255 byte 以上の minified file を除外する。密度逸脱または name_echo がない場合は comment-fixer を起動しない。
明示実行する manual mode は test file を含む changed comment hunk を全件対象にする。selection_reason=changed_comment の patch は既存の密度逸脱を判定せず、comment-only、protected directive、新しい name_echo の有無を検査する。agent が修正不要と判断した空 patch は no_quality_findings で正常終了する。
manual mode は非 test file の追加行を持つコード変更 hunk を code_change_hunks として同じ target に含める。changed comment hunk が無い file は selection_reason=changed_code になり、コメントを増やした file は再計測後の追加行コメント密度が max_pct 以下である場合だけ適用する。
agent unavailable、timeout、異常終了は pending attempt の結果として記録し、review workflow は継続する。
同じ PR で fixer を起動できるのは 2 回までである。agent の起動失敗、出力不備、安全検査の不通過、再計測の不成立は report に残るが、review workflow は止めない。
明示 --local mode は PR 番号を使わず、base ref から HEAD までの差分から observation を作る。PR mode の 20 行下限は適用しない。安全検証を通った patch は固定 message で commit し、branch 単位の履歴へ記録する。local 履歴には回数上限を設けず、PR 単位の履歴を読み書きしない。
Review loop の上限
| 指定 | 意味 |
|---|---|
max-local-review-loops=auto / max-local-review-loops=<positive-integer> / max-local-review-loops=unlimited |
local reviewer の再実行上限 |
max-github-review-loops=auto / max-github-review-loops=<positive-integer> / max-github-review-loops=unlimited |
GitHub reviewer の再実行上限 |
ask-user |
finding の採否や返信方針を利用者へ確認する |
direct run の上限は未指定または auto で 5 回に解決する。
unlimited は明示指定時だけ使う。
local reviewer と GitHub reviewer の上限は別に数える。
上限へ達した side は新しい finding の受付を止め、すでに受け付けた finding の対応を終える。 reviewer の再実行が必要なまま上限を使い切った場合は、上限を引き上げるか、打ち切るか、中止するかを利用者へ確認する。
Timing と transport
| 指定 | 意味 |
|---|---|
per-agent-timeout=15m |
local reviewer 1 件の timeout |
pause=15m |
GitHub reviewer の待機幅 |
quiescence=8m |
GitHub reviewer の静止判定時間 |
--claude-transport headless / --claude-transport direct-pty |
Codex runtime から Claude reviewer を呼ぶ transport |
これらの時間 option は、利用者が指定した場合だけ明示値として渡す。 選択した reviewer を別 runtime へ自動で切り替えない。
停止条件
次の場合は review を完了扱いにしない。
- target を安全に解決できない
- local target に PR 専用 option を渡している
- PR target で
agents=none reviewers=noneとなり review 経路がない - reviewer の許可、認証、CLI、transport に問題がある
- finding、validation failure、conflict、unresolved thread が残っている
- final simplify または指定された E2E が終わっていない
停止と再開
- finding がある: 妥当な問題を修正して検証し、finding の判断を記録して同じ cycle を再実行する。
- GitHub thread がある: 修正、検証、finding 記録、返信、resolve の順で処理する。
- validation failure がある: failure を修正し、同じ command を再実行する。
- conflict がある: PR head と base を合わせ、差分を確認してから review を再開する。
- timeout や format failure がある: reviewer の出力と transport を直し、finding なしとして閉じない。
- loop 上限へ達した: 未解決 finding の重大度と残作業を確認し、続行方針を決める。
中間 finding 対応後は PR 前 agent-simplify を最初からやり直さず、multi-review の finding 対応と再検証へ戻る。
結果の確認
multi-review-report.html では、対象、reviewer、finding の採否、検証結果、未解決 action、残リスクを確認できる。
multi-review-report.md は短い要約として使う。
required action が空でも、follow-up だけが残る場合は PR-ready や merge-ready と断定しない。 CI、latest head、GitHub reviewer、thread、E2E の対象が現在の PR と一致していることも確認する。
Examples
review-orchestrator --pr 123 multi-review run --agents codex
review-orchestrator --pr 123 multi-review run --agents codex --reviewers codex,copilot
review-orchestrator multi-review run --local --agents codex --validation-command "go test ./internal/..."
review-orchestrator multi-review run --local --local-phase pre-pr --base-branch main --agents claude --task-context-file <task-context-file> --validation-command "go test ./internal/..."
詳細 contract
実行 command、internal job、finding の機械形式、artifact schema、runtime recovery、durable state の詳細は claude/skills/multi-review/SKILL.md とその references/、docs/workflow-contracts/issue-workflows.json を正本とする。
公開文書は、review の選択、観測できる結果、利用者が対応する停止条件と復旧方法を扱う。
Related Docs
- review operations
- Issue workflow skill guide
- review-only reference
- adversarial-review reference
claude/skills/multi-review/SKILL.md