設計: cross-review のラウンドを減らす（出し切り・前のラウンドからの変更・設計の観点・agy を既定から外す）（#542 #786） by takemi-ohama · Pull Request #920 · devbasex/ai-plugins

takemi-ohama · 2026-09-23T13:33:02Z

Summary

cross-review のラウンド数を減らす設計（#542）と、agy が結果を残さずに収束を止める問題（#786）の設計。実装は含まない。#631（収束の条件を厳しくする）の採否もこの設計で決めた。

要求と受け入れ条件: issues/issue-542-786-requirements.md
設計: issues/issue-542-786-design.md
決定の記録: issues/issue-542-786-design-decisions.md

範囲外と判断した「結果を残さなかった担当を別のランタイムへ振り替える規則」は #919 として起票した。

決めたこと

issues/issue-542-786-design-decisions.md

決定 1: cross-review の既定の母集合から agy を外し、claude / codex / kiro とホストにする
決定 2: 既定の母集合に無い者を外す指定は、止めずに無視して 1 行で知らせる
決定 3: 1 ラウンド目から「見つけた指摘はすべて出す」を求める
決定 4: 2 ラウンド目以降は、前のラウンドからの変わったファイルの一覧と差分を読むコマンドを渡し、差分の本文は渡さない
決定 5: 設計 PR 向けの観点テンプレートを足し、設計の成果物は増やさない
決定 6: 既存コメントの控えをラウンドの開始ごとに取り直し、失敗しても止めない
決定 7: 収束の判定は変えない。新しい指摘が minor だけのラウンドは今も収束する
決定 8: 母集合の全員が見るまで収束しない条件（cross-review: 母集合の 3 者のうち 1 者も見ていない担当がいる間は収束にしない #631）は採らない
決定 9: 結果を残さなかった担当を別のランタイムへ振り替えることは、この変更に含めない
決定 10: 振動の検知・max_rounds・起動し直しの規則は変えない
決定 11: レビュー担当にはテストも背景の処理も起動させず、適用担当にはテストを前景で待たせる
決定 12: --only で名指しした者は、既定の母集合に無くても参加者にする

Test plan

設計に書いた座席の値を assignment.review_seats で実測した（4 者と 3 者の両方。設計の表と一致）
書き方の点検（markdown-writing のセルフチェックの grep 5 種）: 3 文書とも 0 件
ドキュメント再構成の前後の値を測った（平均文長 46.1 / 41.6 / 49.1 字 → 39.5 / 38.0 / 41.8 字）
cross-review が収束した（実行 3 の 3 ラウンド目で新しい指摘 0 件。verify-sweep exit=0 / 未解決 0 件）

🤖 Generated with Claude Code

https://claude.ai/code/session_01DhcogXCb1x3eStK4VoDDCy

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DhcogXCb1x3eStK4VoDDCy

takemi-ohama

🤖 cross-review | round 1 | codex | REQUEST_CHANGES

minor-only と指摘なしを区別できる新規性の集計契約を定義し、判定・記録・報告が同じ件数を使う設計へ修正してください。

takemi-ohama

🤖 cross-review | round 1 | kiro | REQUEST_CHANGES

minor_only 収束（決定 7 / AC17）が、既存の数え方の前提と噛み合わず到達不能になっている。証拠集約を通ったラウンドで数える 3 区分（verified_blocking / needs_human_judgment / unrefuted）は _classify_finding 上いずれも major/critical に限られ、minor は verified_non_blocking か insufficient_evidence へ落ちて数えられない。そのため NEW_FINDINGS>=1 は必ず NEW_BLOCKING_FINDINGS>=1 を意味し、『新しい指摘が minor だけ』の状態は生じない。設計の主目的（minor だけのラウンドで 1 ラウンド減らす）が動かないので、数え方の再定義かカウント対象区分の変更を設計へ含める必要がある。

証拠集約は minor を数えない区分へ落とすため、新しい指摘が minor だけのラウンドは今も収束する。決定 7 を「判定は変えない」に置き換え、judge の出力・状態ファイルの項目・テストの行を外した。 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DhcogXCb1x3eStK4VoDDCy

takemi-ohama · 2026-09-23T13:40:31Z

🔧 /ndf:fix サマリ | round 1 | commit `76d7f96`

対応件数: critical=0 / major=3 / minor=0（合計 3 件）
決着: 3 件 / 見送り: 0 件 / 却下: 0 件
CI: SUCCESS

takemi-ohama

🤖 cross-review | round 2 | claude | REQUEST_CHANGES

cross-review の既定母集合の変更が共有層を通じて cross-refactoring と --only の振る舞いも変える点、PR の巻き直し後の控えの取り直し対象が未定である点を設計へ反映してほしい。

takemi-ohama

🤖 cross-review | round 2 | kiro | APPROVE

要求・設計・決定の記録の 3 文書は相互に対応し、既存コードへの断定（review_seats の輪番、ALL_RUNTIMES の順、launch-reviewer.sh の「全件」の意味、apply.md の「適用ラウンドの単位で 1 回」、ラウンドごとの head_sha の記録）はいずれも実コードと一致することを確認した。座席の輪番（AC1: round1 codex+kiro / round2 claude+kiro / round3 claude+codex、AC4: --include agy で codex+agy / agy+kiro / claude+kiro）は review_seats の実装で再計算しても一致する。AC5 の grep 検証はディレクトリ全体を走査するため、prose の列挙が SKILL.md と 05 に限られても 02/06 の記述も網羅される。修正を要する矛盾・事実誤認・観点の欠落は見つからなかった。

…と時点を決める Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DhcogXCb1x3eStK4VoDDCy

takemi-ohama · 2026-09-23T13:47:56Z

🔧 /ndf:fix サマリ | round 2 | commit `c5f91e1`

対応件数: critical=0 / major=3 / minor=2（合計 5 件）
決着: 5 件 / 見送り: 0 件 / 却下: 0 件
CI: SUCCESS

takemi-ohama

🤖 cross-review | round 3 | claude | REQUEST_CHANGES

設計の範囲と決定は整合している。既存テスト・文書のうち変更で書き換えが要るものの列挙に漏れがあり、受け入れ条件の検証が字義どおりには通らない箇所を直す。

takemi-ohama

🤖 cross-review | round 3 | codex | REQUEST_CHANGES

既存コメント取得の部分失敗でも前の控えを保持できる契約に改め、変更ファイル一覧は実際のバイト数で6,000バイト上限を保証する設計に修正してください。

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DhcogXCb1x3eStK4VoDDCy

takemi-ohama · 2026-09-23T13:54:58Z

🔧 /ndf:fix サマリ | round 3 | commit `809c249`

対応件数: critical=0 / major=3 / minor=2（合計 5 件）
決着: 5 件 / 見送り: 0 件 / 却下: 0 件
CI: SUCCESS

takemi-ohama

🤖 cross-review | round 1 | codex | REQUEST_CHANGES

共有層の契約変更で期待値が変わる既存テストをテスト設計へ追加し、ラウンド開始時の控え更新を説明する運用文書も更新対象へ含めてください。

takemi-ohama

🤖 cross-review | round 1 | kiro | REQUEST_CHANGES

設計は前ラウンドの主要な指摘を反映済み。残る 3 点は、決定 12 の --only 変更が構成要素の変更対象一覧に無い（実装の抜けを招く）／変更の節が比較する『前のラウンド』が同一 PR に限定されるかが未定義（巻き直し後に別 PR の head と比較しうる）／launch-reviewer.sh の挿入位置が既存の $EXTRA_REVIEW_BLOCK と重なり曖昧、の 3 点。

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DhcogXCb1x3eStK4VoDDCy

takemi-ohama · 2026-09-23T14:02:31Z

🔧 /ndf:fix サマリ | round 1 | commit `189d3d0`

対応件数: critical=0 / major=3 / minor=2（合計 5 件）
決着: 5 件 / 見送り: 0 件 / 却下: 0 件
CI: SUCCESS

takemi-ohama

🤖 cross-review | round 2 | claude | REQUEST_CHANGES

3 文書の決定と範囲は対応している。書き換える既存テストの一覧の漏れ、--only で足した者の記録先、テスト設計の表の崩れを直す。

takemi-ohama

🤖 cross-review | round 2 | kiro | REQUEST_CHANGES

決定 2 で --exclude agy が excluded から ignored_exclude へ移るのに、その値を読む完了報告（cmd_report）と再開経路の複数テストが構成要素・テスト設計の一覧から漏れている。状態を書く側（ignored_exclude を足す）と読む側（report・resume）を突き合わせて、変更対象へ足すか読み手を更新してほしい。

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DhcogXCb1x3eStK4VoDDCy

takemi-ohama · 2026-09-23T14:10:48Z

🔧 /ndf:fix サマリ | round 2 | commit `f700f5f`

対応件数: critical=0 / major=1 / minor=4（合計 5 件）
決着: 5 件 / 見送り: 0 件 / 却下: 0 件
CI: FAILURE

takemi-ohama · 2026-09-23T14:12:52Z

範囲外と判断し、#922 として残した（継続的統合の pytest で揺れた時間の検査。この PR の変更とは無関係のため、失敗したジョブを再実行した）。

takemi-ohama

🤖 cross-review | round 1 | codex | REQUEST_CHANGES

コメント取得ヘルパーが初期化時と再取得時で異なる失敗条件を選べる契約にし、共通の参加者解決層で only の名前検証を維持してください。

takemi-ohama

🤖 cross-review | round 1 | kiro | APPROVE

設計・要求・決定の記録の 3 文書は相互に対応し、既存コードへの断定は実コードと一致することを確認した。座席の輪番（AC1: round1 codex+kiro / round2 claude+kiro / round3 claude+codex、AC4: --include agy で codex+agy / agy+kiro / claude+kiro）は review_seats を実データで再計算しても一致する。収束の判定（AC17）は _classify_finding が minor を verified_non_blocking / insufficient_evidence へ落とし COUNTED_CLASSIFICATIONS に入らないため、minor だけのラウンドは新規 0 件で収束するという記述が実装と一致する。既存コメントの控えの書き先（STATE_PR 固定）は launch-reviewer.sh:77 の読む名前と一致し、巻き直し後も current_pr から取得して STATE_PR 名へ書く設計は矛盾しない。変更の節の 6,000 バイト上限は一覧 5,000 打ち切り＋定型 600＋ほか N 件 30 で証明可能に収まる。前ラウンド 3 回（fix コミット f700f5f まで）で挙がった統合・整合の指摘は解消済み。新規に修正を要する矛盾・事実誤認・観点の欠落は見つからなかった。

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DhcogXCb1x3eStK4VoDDCy

takemi-ohama · 2026-09-23T14:21:30Z

🔧 /ndf:fix サマリ | round 1 | commit `02613a2`

対応件数: critical=0 / major=1 / minor=1（合計 2 件）
決着: 2 件 / 見送り: 0 件 / 却下: 0 件
CI: SUCCESS

takemi-ohama

🤖 cross-review | round 2 | claude | REQUEST_CHANGES

cross-refactoring の完了報告が ignored_exclude を読まず、cross-review 側だけに報告の 1 行を足す設計になっている。共通層の変更が及ぶ両方の報告で扱いを揃える。

takemi-ohama

🤖 cross-review | round 2 | kiro | REQUEST_CHANGES

決定 2 で --exclude agy が excluded から ignored_exclude へ移る一方、再開の参加者の作り直しは記録の excluded だけを読む（state.py:1630）。--exclude を再開時に再指定しない経路（--only / --include の再開）では ignored_exclude が復元されず、AC4d の report 行と状態の記録が再開後に消える。設計の state.py の責務か決定 12/2 の記述に、再開時に ignored_exclude を記録から復元する（または報告は再開で消えると明記する）ことを足してほしい。

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DhcogXCb1x3eStK4VoDDCy

takemi-ohama · 2026-09-23T14:26:11Z

🔧 /ndf:fix サマリ | round 2 | commit `19cfb1a`

対応件数: critical=0 / major=1 / minor=1（合計 2 件）
決着: 2 件 / 見送り: 0 件 / 却下: 0 件
CI: SUCCESS

takemi-ohama

🤖 cross-review | round 3 | claude | REQUEST_CHANGES

cross-refactoring の再開の経路が無視した除外を引き継がず AC4d を満たせない点と、cross-review の再開で既存の重なりの検査を黙って変える点を設計へ反映してほしい。

takemi-ohama

🤖 cross-review | round 3 | codex | REQUEST_CHANGES

cross-refactoring の再開でも無視した除外を引き継ぎ、完了報告から消えない設計とテストを追加してください。

…先を無視した除外だけに限る Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DhcogXCb1x3eStK4VoDDCy

takemi-ohama · 2026-09-23T14:31:10Z

🔧 /ndf:fix サマリ | commit `1cfe7b0`

対応件数: critical=0 / major=2 / minor=1（合計 3 件）
決着: 3 件 / 見送り: 0 件 / 却下: 0 件
CI: SUCCESS

takemi-ohama and others added 2 commits September 23, 2026 13:32

Docs: #542 #786 cross-review のラウンドを減らす設計（要求・設計・決定の記録）

3912bcf

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DhcogXCb1x3eStK4VoDDCy

Docs: #542 #786 決定の記録の見出しを本文の突き合わせの形にそろえる

1e32690

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DhcogXCb1x3eStK4VoDDCy