code-review

コードレビュー — マルチエージェントによるローカルレビュー

概要

狭い範囲を担当するレビュアーエージェントを並列で実行し、その後、実際に影響のある指摘だけを残す検証役が「最初に修正すべき」項目を絞り込み、細かな指摘を抑制して、リポジトリのルートにある REVIEW.md にまとめます。基本原則： レビューに価値があるのは、スタイルではなく 誤った結果 を見つけたときです。各レーンは正確性と構造の健全性に焦点を当てます。検証役は、影響の小さい指摘を既定で DROP にするため、重要な情報が埋もれません。このスキルは対象範囲を決め、各エージェントに処理を割り当て、結果を出力します。判断を行うのはレビュアーと検証役です。

軽量パス。 ドキュメントのみの差分（コード、設定、依存関係の変更を伴わない文章やコメント）では、どのレーンも実行しません。REVIEW.md には **Lanes:** none — doc-only と **Verifier:** not run と記載されます。アーキテクチャやテストで判断するほどの規模ではない変更（1 行の修正、設定値、依存関係の更新など）では、**Lanes:** correctness (light path) として正確性レーンと検証役を実行します。アラートの背後にある 1 行の正規表現や、CVE 対応のバージョン更新にも、入力を追跡した検証が必要だからです。分岐、関数、ファイルのいずれかを追加する変更では、すべてのレーンを実行します。ユーザーがモデルを指定していない場合は、すべてのレーンと検証役の呼び出しで model: "sonnet" を渡してください。

モードとフラグ

フラグ	効果
(none) / path / --staged / --branch <base>	差分を対象にしたレビュー（既定の高速パス）
--repo	リポジトリ全体のレビュー — 差分だけでなく、すべてのソースファイルが対象（適合性チェック）
--blueprint <skill>	最も近い類似実装ではなく、指定したブループリントスキル（例：local-first-app）に基づいてアーキテクチャと UI/UX を評価します。差分の範囲も指定されている場合を除き、--repo を適用します
--background	git worktree で切り離して実行し、レビュー中も作業を続けられます（バックグラウンドモードを参照）
--nits	抑制された衛生面の指摘や細かな問題も表示します。既定では無効です

パイプライン

detect scope → dispatch reviewers (parallel Agent) → verifier (1 Agent) → synthesize → REVIEW.md

各レーンの完全なプロンプトは reference/AGENTS.md にあります（レーンの実行時に読み込みます）。

レーン	担当範囲	ブロッキング対象か
correctness	誤った結果：境界や off-by-one の誤り（日付、DST、月末）、タイムゾーンやロケールによるグループ化、金額やレートの計算、握りつぶされたエラー、アトミックでない書き込み、終了条件のないループ、破棄された非同期処理の結果、null や退化した入力	はい — 最優先
architecture	コードの目的に照らした構造の健全性：永続化や冪等性の意味づけの誤り、処理に必要な回復性の欠如、不変条件の破損、重要なコンテキストの欠落、動作を見えにくくする極端な複雑さ（ネスト 4 階層以上、サイクロマティック複雑度がおよそ 10 超）。「同僚の実装と違う」は対象外	はい
testing	変更部分のカバレッジとアサーションの強さ（メンバーシップの確認と完全一致の確認の違い、弱い truthiness 判定、モック化されたオラクル）	はい
ui-ux	タイポグラフィとカラーシステムの最低基準に照らした可読性とアクセシビリティ（本文が 16px 未満、コントラスト比が 4.5:1 未満、色だけを手掛かりにする、フォーカスやラベルの欠如）。対象範囲に UI が含まれる場合のみ実行	はい（条件付き）
hygiene	ブロッキング対象ではない一括チェック：シークレット、デッドコード、誤字、ドキュメントと依存関係の不整合、可読性、複雑さに関する中程度の細かな問題	いいえ — --nits が指定されない限り抑制。ただし実際の [Secret] は常に表示

フェーズ 1：対象範囲の検出

まずフラグを解析します。レビュー対象のファイルを、次の優先順位で決定します。--repo（リポジトリ内のすべてのソース。ただし以下の除外対象を除く）→ 明示的なパス引数 → --staged（git diff --cached）→ --branch <base>（git diff <base>...HEAD）→ デフォルト（ステージ済み＋未ステージの変更、git status --porcelain＋git diff HEAD）→ フォールバック（フィーチャーブランチで変更がない場合：git diff main...HEAD）。

バイナリ／画像アセット、生成ファイル、ビルド／依存関係／venv の出力は除外します。ロックファイル、パッケージマニフェスト、環境テンプレート、プロジェクトのドキュメントは除外しないでください。hygiene ではこれらが必要です。**UI の対象範囲を検出します。**ファイル一覧にコンポーネント／テンプレート／スタイル／デザイントークンのファイルが含まれる場合は、ui-ux レーンを追加します。含まれない場合はスキップします。

**リポジトリのルートを固定します。**レビュー対象ツリーの git rev-parse --show-toplevel を絶対パスに解決し、共有の前文内のすべてのレーンおよび検証担当者向けプロンプトの先頭に記載します。その理由は Gotchas で説明されています。

具体的なファイル一覧と差分テキストの両方を用意してから、ディスパッチを一度だけ行います（--repo の場合、「差分」は対象範囲内のファイルの現在の全内容です）。レビュー担当サブエージェントは会話のコンテキストなしで開始し、渡されていない内容は何も読み取れません。まず対象範囲をユーザーに報告します（「N 個のファイルをレビューします：…」）。差分モードで対象範囲が空の場合は、作業をでっち上げずに終了します（--repo は空になりません。これがその目的です）。

フェーズ 2：並列ディスパッチ

レビュー担当エージェントの呼び出しは1 つのメッセージで送信し、並行して実行します。すべて subagent_type: general-purpose とし、共有の前文によって読み取り専用にします。Explore はコード箇所を特定するために抜粋を読み、各レーンは関数全体とその呼び出し元を読む必要があります。必ず correctness、architecture、testing、hygiene をディスパッチし、UI の対象範囲が検出された場合に限り ui-ux を追加します。各プロンプトには、ファイル一覧と差分、レーンと無視する対象、出力形式を含め、file:line で具体的に示すよう求めます。reference/AGENTS.md の正確なひな形を使用します。--blueprint <skill> が指定されている場合は、そのスキルを読み込み、名前とルールを architecture と ui-ux のプロンプトに渡します。

フェーズ 2.5：検証＋影響度の下限

ファイル一覧、差分、統合済み候補を渡して、検証担当を 1 人（単一の Agent、general-purpose、共有の前置き）に割り当てます。完全なプロンプトはreference/AGENTS.md#verifierを参照してください。すべてのレーンが NO FINDINGS を返した場合は省略します。その場合、ヘッダーには **Verifier:** skipped — no candidates と記載し、STRENGTHS ブロックは省略します。検証担当の役割は、単なる誤検出フィルターではなく、シグナルフィルターです。

• **根拠：**各指摘で引用されている file:line を読み直します。引用が誤っている場合は、指摘を削除します。
• 差分の基準（差分モードのみ。--repo には差分がありません）：差分で追加または変更された行に対する指摘は残します。変更されていない行への指摘は、変更行が原因である場合に限り、Outside the diff — caused by path:line とラベルを付けて残します。それ以外は削除し、差分外としてカウントします。
• **影響度の下限：**残す指摘には、それによって防げる具体的な悪影響（誤った結果、データ損失、セキュリティ上の問題、実際のリグレッション、読者を実際に誤解させる落とし穴）を明記する必要があります。現実的に起こり得る最悪の結果が、見た目やスタイル、ドキュメントだけの問題、または「一貫性はないが何も壊れない」である場合は、下限を満たしません。[Nit] タグが付いている場合は nit バケットに振り分け、それ以外は削除します。影響度に迷ったら、削除します。
• 重大度は影響範囲に基づいて決定し、レーンの重大度に優先します。
• **補足事項：**実際に問題を引き起こす可能性はあるものの、ブロッキングではない影響（デプロイ順の手順や、作成する価値のある追加テストなど）を含む削除済み指摘は、最大 3 件まで、各 1 行で保留します。影響度が低いだけの指摘は削除したままにします。
• **STRENGTHS：**コードを読んで確認したうえで、適切に実装されている点を 2～4 件列挙し、それぞれ確認したファイルまたは行に結び付けます。根拠に基づく称賛は、細かなあら探しではなくレビューという印象を与えますが、根拠のない称賛は水増しに見えます。

検証担当は、STRENGTHS、「what to fix first」の要約（3～6 項目）、再評価後の重大度を付けて残したブロッキング指摘、ALSO NOTED、--nits が指定された場合のみ NITS セクション、および Verifier summary: kept N blocking of M; dropped J (W wrong-evidence, O off-diff, L low-impact); A also noted; H nits held. を返します。

フェーズ 3：統合

根拠、影響度、優先度の判断は検証担当がすでに済ませています。統合では書式を整えるだけです。

1. 存在する場合は、まず ## What the repo does well（STRENGTHS ブロック）を出力します。
2. 次に ## What to fix first を出力します。各項目は検証担当が示した 1 行の path:line — why it matters とし、順序もそのままにします。Nothing blocking — only polish remains. が返された場合は、その 1 行だけを出力します。
3. 残した指摘を、再評価後の重大度（Critical → Major → Minor）、次にファイルごとにまとめます。検証担当の重大度をそのまま適用し、Verifier note: と Outside the diff のラベルも残します。[Secret] 指摘は必ず記載します（Critical）。
4. **補足事項：**検証担当が保留した行があれば、Minor の後に ## Also noted として出力します。
5. Nits：--nits が指定された場合のみ、ファイルごとにまとめた簡潔な 1 行形式の ## Nit ブロックを出力します。それ以外は完全に省略します。サマリー行には保留数を引き続き記載します。
6. 重複排除：複数のレーンが同じ行を指摘した場合、最も重大なものを残し、レーン名を記載します。
7. Write を使用して、リポジトリのルート（git rev-parse --show-toplevel）にある REVIEW.md に上書き保存します。直接実行の場合は、チャットに 1 行だけ出力します：REVIEW.md written — X Critical, Y Major, Z Minor; H nits held (--nits to show)。

問題がない場合も、必ず REVIEW.md を書き込みます（ゼロ件のヘッダー＋STRENGTHS ブロック＋Nothing blocking — only polish remains.）。統合担当の範囲は構造のみです。新たな指摘を追加せず、再評価も行わず、直接実行の場合はレポートをチャットに出力しません。

**呼び出し元の指示が書式を優先します。**別のエージェントまたはラッパースキルからレビューを実行する場合は、その指示で求められている内容を返します。その返却内容がレポートです。その場合も REVIEW.md は書き込みます。指示で独自の重大度ラベル（たとえば Blocking / Should fix / Nit）が指定されている場合は、Critical、Major、Minor をそれぞれ対応するラベルに置き換え、REVIEW.md 全体で、検証担当の行も含めてそれらを使用します。差分外の指摘をすべて削除するなど、呼び出し元のより厳しいルールがある場合は、スキルのルールより優先します。

バックグラウンドモード

--background はレビューを切り離して実行するため、ユーザーは作業を続けられます。レビューを管理するスレッドから調整してください。通常はメインスレッドですが、委任されたエージェントでも構いません。サブエージェントは最大3階層までサブエージェントを起動できるためです。

1. オーケストレーターがスコープを確定し、差分テキストを取得します（Phase 1）。次のメッセージを出力します。Reviewing N files in the background — keep working; REVIEW.md will appear when done.
2. 各レビュアーを run_in_background: true、isolation: "worktree"、name なしでディスパッチします。どちらも Gotchas で説明されています。
3. オーケストレーターは制御を戻し、各レビュアーが完了するたびにハーネスが再度呼び出します。
4. すべてのレビュアーが戻ったら、検証担当をバックグラウンドでディスパッチします。
5. 完了したら、REVIEW.md を実際のリポジトリルート（レビュー対象の作業ツリーに対する git rev-parse --show-toplevel。レビュアーの worktree は削除されます）に書き込みます。これが「完了」の合図です。

--repo --background が最適です。数分かかるリポジトリ全体の適合性チェックを、作業を止めずに実行できます。

出力形式

リポジトリルートの REVIEW.md。セクションの順序は、ヘッダー（Generated / Scope / Lanes / Verifier: kept N blocking of M; dropped …; H nits held / Total）→ ## What the repo does well → ## What to fix first → ## Critical → ## Major → ## Minor（項目：[lane] line — 問題、リスク／根拠と修正方法。再評価された指摘には Verifier note: が付きます）→ ## Also noted（該当する場合）→ ## Nit（--nits 指定時のみ）。完全なレポート例は reference/EXAMPLE-REVIEW.md を参照してください。

例

✅ 良い例： レビュアー Agent を1回のメッセージで呼び出す → 待機 → 検証担当 Agent → REVIEW.md に書き込む → チャットには REVIEW.md written — 1 Critical, 2 Major, 0 Minor; 5 nits held (--nits to show) のみ表示されます。優れた正確性に関する指摘は具体的です。[correctness] src/allowance.ts:42 — 詳細ページには $10/wk と表示されるが、発生額は永久に $5/wk のまま（rate-row shadowing）。発生条件：週次レートが設定された項目。修正方法：表示行ではなく発生行からレートを読み取る。

❌ 悪い例： レビュアーを順番にディスパッチする。直接実行時に、完全なレポートを REVIEW.md ではなくチャットに出力する。「この変数名を変更することを検討してください」のような指摘が採用される（具体的な悪影響がなく、影響度の最低基準を満たさないはずです）。重要な2件の指摘が埋もれるほど、Nit の一覧をデフォルトで表示する。

✅ スコープ検出、バックエンドのみの差分： リストにコンポーネント、スタイル、トークンファイルがない場合は、ui-ux レーンをスキップして4つのレーンをディスパッチします。差分のスコープが空の場合は、--repo に範囲を広げずに停止してその旨を伝えます。

❌ 悪い例： CLI のみの差分に ui-ux をディスパッチし、技術的には正しいという理由でその指摘を採用する。

✅ 軽量パス、正規表現の1行修正： correctness レーンと検証担当のみを実行し、ヘッダーは Lanes: correctness (light path) です。

❌ 悪い例： 同じ修正に対してエージェントがまったく実行されないのに、REVIEW.md には Verifier: kept 0 blocking of 0 と記載される。実行されていない検証を、実施済みと示すヘッダーです。

✅ 検証担当による DROP が正しく機能する例： [architecture] src/db.ts:88 — src/cache.ts のパターンと異なる。具体的な影響が示されていないため、影響度の最低基準を満たしません。DROP され、dropped J (L low-impact) に計上されます。

品質の指標

• レビュアー Agent の呼び出しは1回のターンで行い、統合前に検証担当 Agent を1回実行します。
• レポートの先頭には ## What the repo does well と ## What to fix first を置きます。--nits を指定しない限り、Nit の一覧は表示されません。
• 採用される指摘はすべて具体的な悪影響を示します。正確性に関する指摘では、発生条件となる入力も示します。
• アーキテクチャに関する指摘は、「関連する別の箇所と異なる」ではなく、コードの目的に基づいて、実際の影響を論じます。
• 重大度には検証担当の影響度判断を反映します。影響度が低いだけの正しい指摘は、重大度を下げて残すのではなく、除外します。
• 引用する行はすべて差分内にあるか、原因となる変更行が明示されています。
• 成果物は REVIEW.md です（直接実行時、チャットには1行のみ表示）。ファイルは同じ場所に上書きします。

注意点

• レーンのディスパッチ時に name を渡さないでください。 エージェントに名前を付けるとチームメイトになり、チームメイトは別のチームメイトを起動できません。委任されたレビュー内では、バッチ全体が Teammates cannot spawn other teammates で拒否されます。再試行して復旧しますが、レーンごとにラウンドトリップが発生します。レーンを名前で指定することはないため、このパラメーターは省略してください。
• レーンはレビュー対象のツリーではなく、セッションのディレクトリから開始します。 そのディレクトリに同じリポジトリの別のチェックアウト（メインクローンの隣に多数の PR ワークツリーがある場合など）があると、相対パスやシンボル検索が別のブランチを参照し、このブランチには存在しない行や、別の機能に関するバグをレビューで指摘することがあります。共有プレアンブルにリポジトリの絶対パスを記載して対処し、検証器の差分アンカーで見落としを検出します。
• 連結した出力の行番号は誤っています。 cat a.py; cat b.py は結合したストリームに行番号を付けるため、レーンが 2 つ目のファイルの 72 行目を 192 行目として指摘することがあります。プレアンブルでは、1 つのファイルに対する grep -n、nl、または Read を必須としています。
• ワークツリーのレビュアーにはクリーンなツリーが見えます。 isolation: "worktree" のチェックアウトは HEAD を共有するため、その中で git diff を実行しても何も返りません。レビュアーはプロンプトから差分を読み取るため、レーンに差分を再取得させないでください。
• --repo モードには差分がありません。 レーンが受け取るのはファイル全体の内容であるため、+ 行を探すレーンは実際の問題があっても NO FINDINGS を返します。レーンがファイル全体をレビューできるよう、プロンプトにモードを渡してください。
• 検出結果の破棄は仕様であり、バグではありません。 検証器は、事実ではあるものの軽微な検出結果を意図的に削除します。復旧には --nits を使います。基準に達しない検出結果は破棄されるか Nit として保留され、より低い重大度で残されることはありません。
• ui-ux レーンは条件付きです。 バックエンド／CLI の差分で実行された場合、Phase-1 の UI 検出が UI 以外のファイルに一致しています。レーンのノイズを受け入れるのではなく、検出を修正してください。
• 複雑さは意図的に二段階で扱います。 挙動を隠すほど深刻な複雑さ（4 段階以上のネスト、約 >10 のサイクロマティック複雑度）は、アーキテクチャレーンによってブロックされ、落とし穴を明示する必要があります。つまり、将来の編集者が見落とす経路と、そこで起きる問題を示します。中程度の複雑さは、hygiene の [Nit] です。具体的な落とし穴が示されておらず、影響の基準を満たさない複雑さの指摘は、検出漏れではなく、基準が機能している証拠です。
• アーキテクチャに関する指摘は「同等のものと異なる」という内容に戻りがちです。 具体的な結果が示されていない指摘は、指摘とは言えません。正確なプロンプトを使ってレーンを再ディスパッチしてください。
• REVIEW.md は実行のたびに上書きされ、リポジトリの実際のルート（ワークツリーではなく git rev-parse --show-toplevel）に書き込まれます。 以前のレビューは失われるため、.gitignore に追加してください。gitignore では、プロジェクトルートをコピーするビルドを防げません。スタンドアロンの Next.js ビルドでルートの REVIEW.md が出力に含まれたことがあるため、.dockerignore とビルド時のコピー除外設定にも追加してください。

トラブルシューティング

• まだ細かいことを指摘しすぎる — 検証器が影響の基準を適用していません。reference/AGENTS.md#verifier のプロンプトをそのまま使って再ディスパッチし、「デフォルトでは DROP とし、残すすべての指摘で具体的な悪影響を明示すること」と指定してください。

対象範囲が空、差分が巨大、ブループリントが見つからない、ワークツリーのクリーンアップ：reference/TROUBLESHOOTING.md。

統合

/security-review（セキュリティ）、/review（番号でオープン中の PR を取得）、track-session（修正を追跡）、typography + color-system（ui-ux レーンの標準）、および --blueprint で使う local-first-app などのブループリントスキルと組み合わせて使用します。一般的な流れ：編集 → /code-review → REVIEW.md を読み、最初の項目を修正 → 再実行（上書き）→ 問題がなければコミット。大規模なレビューでは、/code-review --repo --blueprint <skill> --background を実行して作業を続けます。受信した PR のレビュー： 各 PR をそれぞれのワークツリーにチェックアウトし、そこで --branch <base> を実行します。PR ごとに委任エージェントを 1 つ使います。REVIEW.md はそのワークツリーのルートに作成されるため、複数の PR を互いに競合させずに並行してレビューできます。REVIEW.md を .gitignore に追加してください。CI の lint や人による PR レビューの代わりではなく、リンターが見逃す誤りを検出するコミット前チェックです。