bug-review

Bug Review v2

5 つの並列レビュー、過半数による投票、Opus による独立検証、解決率学習を行う複数パスの PR レビューエージェントです。PR にインラインコメントを投稿し、オプションで自動修正コミットを生成します。マージ時に指摘事項が解決されたかどうかを追跡し、その情報を使って今後のレビューを改善します。

適用する場合

• バグや正確性の問題について、プルリクエストのレビューを依頼された場合
• ユーザーが /bug-review <PR-number-or-URL> を実行した場合
• ユーザーがマージ後の解決状況を分類するために /bug-review:resolve <PR> を実行した場合
• ユーザーが解決率の統計を確認するために /bug-review:report を実行した場合
• ユーザーがロジックエラー、エッジケース、セキュリティに焦点を当てたコードレビューを依頼した場合
• ユーザーが差分または一連の変更からバグを見つけたい場合

セットアップ

初回実行時に、次を確認します。

• gh CLI がインストールされ、認証済みであること（gh auth status）
• 現在のディレクトリが GitHub リモートを持つ git リポジトリであること
• JSON 処理用の jq がインストールされていること
• 解決率の計算用の bc がインストールされていること（ほとんどのシステムではプリインストールされています）

設定（パス、投票しきい値、モデル、カテゴリの重み）については、config.json を読みます。

ワークフローの概要

/bug-review <PR>
  |
  v
Fetch PR context + gather-context.sh
  |
  v
5 parallel passes (shuffled diffs, Sonnet) --> Aggregate & vote (3/5 majority)
  |
  v
Independent Opus validator --> Dedup --> Present findings --> Post + store
  |
  (later, after merge)
  v
/bug-review:resolve <PR> --> Classify resolutions --> Update category weights

コマンド：/bug-review

ステップ 1：入力の解析とコンテキストの取得

1. PR 識別子（番号、URL、またはブランチ名）を解析します
2. キャッシュを確認：${CLAUDE_PLUGIN_DATA}/bug-review/cache/pr-{N}/ を調べます。同じ head commit のキャッシュが存在する場合は、最後のチェックポイントから再開するか確認します
3. scripts/fetch-pr.sh <pr-identifier> を実行し、PR の差分とメタデータを JSON として取得します
4. シャッフル用に差分を一時ファイルに保存します
5. scripts/gather-context.sh <changed-files-json> を実行し、優先順位付けされたコンテキスト（呼び出し元、型、テスト、リポジトリのルール）を取得します
6. リポジトリのルートに .bug-review.md があれば読み込みます
7. チェックポイントを保存：コンテキストを ${CLAUDE_PLUGIN_DATA}/bug-review/cache/pr-{N}/context.json に書き込みます

ステップ 2：5 つの並列レビューを実行

各パス（1～5）について、シャッフルした差分を準備します。

scripts/shuffle-diff.sh <pass-number> < pr.diff > pass-<N>.diff

5 つの Agent サブプロセスを並列で起動します。各パスの正確なプロンプトについては、review-passes.md を読みます。

• パス 1：ロジックとエッジケース（シード 1）
• パス 2：セキュリティとデータ整合性（シード 2）
• パス 3：エラー処理と API コントラクト（シード 3）
• パス 4：並行処理と状態（シード 4）
• パス 5：データフローとコントラクト（シード 5）

config.json の agent_model（デフォルト："sonnet"）の model を使用します。

各エージェントは、指摘事項を格納した JSON 配列を返します。

チェックポイントを保存：すべてのパスの結果を ${CLAUDE_PLUGIN_DATA}/bug-review/cache/pr-{N}/pass-results.json に書き込みます

ステップ 3：集約と投票

1. 5 つすべてのパスから指摘事項を集めます
2. 類似性に基づいて指摘事項をグループ化します。同じファイルで行番号が +/-5 以内、かつ同じカテゴリまたは関連するカテゴリであることを条件とします
3. グループごとに票数を数えます
4. 3 票以上の指摘事項のみを残します（5 つのうち過半数。vote_threshold で設定可能）
5. config.json のカテゴリの重みを適用します：final_score = votes × severity_weight × category_weight
6. 重みが 0.1 未満のカテゴリは完全に除外します
7. final_score の降順で順位付けします

1～2 つのパスだけがバグを見つけ、ほかのパスが何も見つけなかった場合は、指摘事項を提示しつつ、合意が得られていないことを明記します。

チェックポイントを保存：投票後の指摘事項をキャッシュに書き込みます。

ステップ 4：独立検証（Opus）

config.json の validator_model（デフォルト："opus"）を使い、別の Agent を起動します。

このエージェントはレビューの各パスの結果を見ていません。投票後の指摘事項と元のコードのみを受け取ります。プロンプトについては、review-passes.md の Validator セクションを読みます。

指摘事項ごとに、検証エージェントは {id, verdict: "KEEP"|"DISCARD", confidence, reasoning} を出力します。

DISCARD と判定された指摘事項を削除します。各指摘事項のスコアに、検証エージェントの信頼度を掛けます。

各指摘事項の最終的な confidence フィールドを計算します。

confidence = (votes / total_passes) × validator_confidence

信頼度が 0.5 未満の指摘事項には「信頼度が低い」という警告を表示します。

チェックポイントを保存：検証済みの指摘事項をキャッシュに書き込みます。

ステップ 5：過去のレビューとの重複を除外する

scripts/dedup.sh <pr-number> を実行し、既存の [bug-review] コメントを取得します。 テキストの類似度ではなく、場所の近さ（ファイルと行番号の差が ±10 以内）とカテゴリで照合します。

ステップ 6：検出結果をユーザーに提示する

次の表を表示します。

#	重大度	信頼度	ファイル	行	タイトル	投票数

各検出結果について、詳細な説明、発生条件、修正案、バリデーターの判断理由を示します。

AskUserQuestion を使用し、multiSelect でユーザーに確認します。

• PR コメントとして投稿する検出結果（デフォルト：すべて）
• 自動修正する検出結果（デフォルト：なし）

投票と検証を通過した検出結果がない場合は、「5 回のレビューですべて確認しましたが、バグは見つかりませんでした。変更内容に問題はありません。」と表示します。

ステップ 7a：PR レビューを投稿する

承認された検出結果を一時 JSON ファイルに書き込み、その後、次を実行します。

scripts/post-review.sh <pr-number> <findings-json-file>

次に、解決状況の追跡用に検出結果を保存します。

scripts/store-findings.sh <pr-number> <findings-json-file> <head-commit-sha>

ステップ 7b：自動修正（ユーザーが選択した検出結果）

自動修正する検出結果ごとに、次の手順を実行します。

1. ファイルを読み、周辺のコンテキストを把握します。
2. 最小限の修正（可能な限り小さな変更）を作成します。
3. Edit ツールを使って修正を適用します。
4. 範囲を確認：git diff --stat を実行し、変更されたファイルが検出結果のファイルのみであり、差分が 20 行未満であることを確認します。超過した場合は元に戻して警告します。
5. 利用可能であれば、既存のテストを実行します（npm test、go test ./...、pytest など）。
6. テストが成功した場合：fix: {title} [bug-review] でコミットします。
7. テストが失敗した場合：修正を元に戻し（git checkout -- <file>）、ユーザーに報告します。
8. すべての修正後、PR ブランチにプッシュします。

安全対策：修正ごとに 1 つのコミットを作成し、修正の間にテストを実行します。強制プッシュは行わず、すべての修正について範囲を検証します。

コマンド：/bug-review:resolve

PR のマージ後に実行し、検出結果が解決されたかどうかを分類します。

1. scripts/classify-resolutions.sh <pr-number> を実行します。
   • 保存済みの検出結果を ${CLAUDE_PLUGIN_DATA}/bug-review/findings/pr-{N}.json から読み込みます。
   • PR がマージされているか確認します。
   • 各検出結果について、レビュー時のコミットとマージコミット間のコードの差分を確認します。
   • それぞれを RESOLVED、UNRESOLVED、INCONCLUSIVE に分類します。
   • 解決状況データで保存済みの検出結果ファイルを更新します。
2. 解決状況の概要をユーザーに表示します。
3. 十分なデータ（検出結果 10 件以上、PR 3 件以上）が蓄積されている場合：カテゴリの重みを調整するため、scripts/update-weights.sh を実行します。

コマンド：/bug-review:report

追跡対象のすべての PR における解決率の統計を表示します。

/scripts/resolution-report.sh を実行すると、次の内容が出力されます。

• 全体の解決率
• 重大度別の解決率
• カテゴリ別の解決率（誤検出の多いカテゴリを目立たせるため、悪い順にソート）
• 抑制されたカテゴリ（重み < 0.1）

リポジトリ固有のルール（.bug-review.md）

チームはリポジトリのルートに .bug-review.md を作成できます。

## Focus Areas
- Pay special attention to authentication flows
- Check all database queries for SQL injection

## Ignore
- Don't flag issues in generated files (*.generated.ts)
- Ignore style-only concerns

## Invariants
- All API endpoints must check req.user before accessing user data
- Database migrations must be reversible

## Severity Overrides
- Treat any auth bypass as CRITICAL regardless of category default

使用方法

エラー処理を含む詳細な手順については、workflow.md をお読みください。 5 つすべてのレビューパスのプロンプトとバリデーターについては、review-passes.md をお読みください。 バグカテゴリと学習済みの重みについては、categories.md をお読みください。

関連スキル

• このレビューで見つかったバグを調査するための Runbook スキルの作成を検討してください。
• PR の作成時にこのレビューを自動実行する CI/CD スキルの作成を検討してください。