Back to Details

bug-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bug Review v2

Bug Review v2

Multi-pass PR review agent with 5 parallel review passes, majority voting, independent Opus validation, and resolution rate learning. Posts inline PR comments and optionally generates autofix commits. Tracks whether findings get resolved at merge time and uses that signal to improve future reviews.
多轮PR评审Agent，包含5个并行评审环节、多数投票机制、独立的Opus验证以及解决率学习能力。可在PR内发表行内评论，还可选择生成自动修复提交。追踪发现的问题在PR合并时是否得到解决，并使用该信号优化未来的评审效果。

When to Apply

适用场景

  • User asks to review a pull request for bugs or correctness issues
  • User runs 
    /bug-review <PR-number-or-URL>
  • User runs 
    /bug-review:resolve <PR>
    to classify resolutions after merge
  • User runs 
    /bug-review:report
    for resolution rate statistics
  • User asks for code review focused on logic errors, edge cases, or security
  • User wants to find bugs in a diff or set of changes
  • 用户请求审查 pull request 中的漏洞或正确性问题
  • 用户运行 
    /bug-review <PR-number-or-URL>
  • 用户运行 
    /bug-review:resolve <PR>
    以在PR合并后分类问题解决情况
  • 用户运行 
    /bug-review:report
    查看解决率统计数据
  • 用户请求聚焦于逻辑错误、边界场景或安全问题的代码评审
  • 用户想要在diff或变更集中查找漏洞

Setup

环境配置

On first run, verify:
  • gh
    CLI is installed and authenticated (
    gh auth status
    )
  • Current directory is a git repo with a GitHub remote
  • jq
    is installed (for JSON processing)
  • bc
    is installed (for resolution rate calculations; pre-installed on most systems)
Read config.json for configuration (passes, vote threshold, models, category weights).
首次运行时，请验证：
  • gh
    CLI 已安装并完成身份认证（
    gh auth status
    ）
  • 当前目录是绑定了GitHub远程仓库的git仓库
  • jq
    已安装（用于JSON处理）
  • bc
    已安装（用于计算解决率，大多数系统已预装）
查看 config.json 了解配置项（评审轮次、投票阈值、模型、分类权重）。

Workflow Overview

工作流概览

/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 <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

Command: /bug-review <PR>

命令：/bug-review <PR>

Step 1: Parse Input & Fetch Context

步骤1：解析输入并拉取上下文

  1. Parse the PR identifier (number, URL, or branch name)
  2. Check cache: Look for 
    ${CLAUDE_PLUGIN_DATA}/bug-review/cache/pr-{N}/
    — if cache exists for the same head commit, offer to resume from the last checkpoint
  3. Run 
    scripts/fetch-pr.sh <pr-identifier>
    to get PR diff + metadata as JSON
  4. Save the diff to a temp file for shuffling
  5. Run 
    scripts/gather-context.sh <changed-files-json>
    to get prioritized context (callers, types, tests, repo rules)
  6. Read 
    .bug-review.md
    from repo root if it exists
  7. Save checkpoint: Write context to 
    ${CLAUDE_PLUGIN_DATA}/bug-review/cache/pr-{N}/context.json
  1. 解析PR标识（编号、URL或分支名）
  2. 检查缓存：查找 
    ${CLAUDE_PLUGIN_DATA}/bug-review/cache/pr-{N}/
    —— 如果同一HEAD commit存在缓存，提供从最近 checkpoint 恢复的选项
  3. 运行 
    scripts/fetch-pr.sh <pr-identifier>
    获取PR diff和元数据，输出为JSON格式
  4. 将diff保存到临时文件用于打乱顺序
  5. 运行 
    scripts/gather-context.sh <changed-files-json>
    获取优先级上下文（调用方、类型、测试、仓库规则）
  6. 如果仓库根目录存在 
    .bug-review.md
    则读取内容
  7. 保存 checkpoint：将上下文写入 
    ${CLAUDE_PLUGIN_DATA}/bug-review/cache/pr-{N}/context.json

Step 2: Run 5 Parallel Review Passes

步骤2：运行5轮并行评审

For each pass (1-5), prepare a shuffled diff:
bash
scripts/shuffle-diff.sh <pass-number> < pr.diff > pass-<N>.diff
Launch 5 Agent subprocesses in parallel. Read review-passes.md for the exact prompt for each pass.
  • Pass 1: Logic & Edge Cases (seed 1)
  • Pass 2: Security & Data Integrity (seed 2)
  • Pass 3: Error Handling & API Contracts (seed 3)
  • Pass 4: Concurrency & State (seed 4)
  • Pass 5: Data Flow & Contracts (seed 5)
Use 
model
from config.json 
agent_model
(default: 
"sonnet"
).
Each agent returns a JSON array of findings.
Save checkpoint: Write all pass results to 
${CLAUDE_PLUGIN_DATA}/bug-review/cache/pr-{N}/pass-results.json
为每个评审轮次（1-5）准备打乱顺序的diff：
bash
scripts/shuffle-diff.sh <pass-number> < pr.diff > pass-<N>.diff
并行启动 5个Agent子进程。查看 review-passes.md 了解每个轮次的精确提示词。
  • 轮次1：逻辑与边界场景（seed 1）
  • 轮次2：安全与数据完整性（seed 2）
  • 轮次3：错误处理与API契约（seed 3）
  • 轮次4：并发与状态管理（seed 4）
  • 轮次5：数据流与契约（seed 5）
使用 config.json 中 
agent_model
指定的模型（默认：
"sonnet"
）。
每个Agent返回发现问题的JSON数组。
保存 checkpoint：将所有轮次结果写入 
${CLAUDE_PLUGIN_DATA}/bug-review/cache/pr-{N}/pass-results.json

Step 3: Aggregate & Vote

步骤3：汇总与投票

  1. Collect findings from all 5 passes
  2. Group findings by similarity: same file + line within +/-5 + same or related category
  3. Count votes per group
  4. Keep only findings with 3+ votes (majority of 5, configurable via 
    vote_threshold
    )
  5. Apply category weights from config.json: 
    final_score = votes × severity_weight × category_weight
  6. Categories with weight < 0.1 are suppressed entirely
  7. Rank by final_score descending
If only 1-2 passes found bugs and the others found none, present findings but note they lack consensus.
Save checkpoint: Write voted findings to cache.
  1. 收集所有5轮评审发现的问题
  2. 按相似度分组：相同文件 + 行号差在±5以内 + 相同或相关分类
  3. 统计每个分组的票数
  4. 仅保留票数≥3的问题（5轮的多数规则，可通过 
    vote_threshold
    配置）
  5. 应用 config.json 中的 分类权重：
    最终得分 = 票数 × 严重程度权重 × 分类权重
  6. 权重<0.1的分类会被完全屏蔽
  7. 按最终得分降序排序
如果仅有1-2轮发现漏洞，其余轮次未发现问题，则展示发现的问题但标注缺乏共识。
保存 checkpoint：将投票后的问题写入缓存。

Step 4: Independent Validation (Opus)

步骤4：独立验证（Opus）

Launch a separate Agent using 
validator_model
from config.json (default: 
"opus"
).
This agent has NOT seen the review passes. It receives only the voted findings and the original code. Read the Validator section in review-passes.md for the prompt.
For each finding, the validator outputs: 
{id, verdict: "KEEP"|"DISCARD", confidence, reasoning}
Remove DISCARDed findings. Multiply each finding's score by the validator's confidence.
Compute each finding's final 
confidence
field:
confidence = (votes / total_passes) × validator_confidence
Findings with confidence < 0.5 are shown with a "low confidence" warning.
Save checkpoint: Write validated findings to cache.
使用 config.json 中 
validator_model
指定的模型（默认：
"opus"
）启动 独立Agent。
该Agent未接触过之前的评审轮次结果，仅收到投票通过的问题和原始代码。查看 review-passes.md 中的验证器章节了解提示词。
对于每个问题，验证器输出：
{id, verdict: "KEEP"|"DISCARD", confidence, reasoning}
移除判定为DISCARD的问题，将每个问题的得分乘以验证器的置信度。
计算每个问题的最终 
confidence
字段：
confidence = (票数 / 总轮次) × 验证器置信度
置信度<0.5的问题会附带“低置信度”警告展示。
保存 checkpoint：将验证后的问题写入缓存。

Step 5: Dedup Against Prior Reviews

步骤5：与历史评审结果去重

Run 
scripts/dedup.sh <pr-number>
to get existing 
[bug-review]
comments. Match by location proximity (file + line within +/-10) and category — not text similarity.
运行 
scripts/dedup.sh <pr-number>
获取已存在的 
[bug-review]
评论。按位置接近度（文件 + 行号差在±10以内）和分类匹配，而非文本相似度。

Step 6: Present Findings to User

步骤6：向用户展示发现的问题

Display a table:
#SeverityConfidenceFileLineTitleVotes
For each finding, show full description, trigger scenario, suggested fix, and validator reasoning.
Ask the user (using AskUserQuestion with multiSelect):
  • Which findings to post as PR comments (default: all)
  • Which findings to autofix (default: none)
If no findings survived voting + validation: "No bugs found across 5 review passes. The changes look clean."
展示表格：
#严重程度置信度文件行号标题票数
对于每个问题，展示完整描述、触发场景、修复建议以及验证器判定理由。
（使用支持多选的AskUserQuestion）询问用户：
  • 哪些问题需要 作为PR评论发布（默认：全部）
  • 哪些问题需要 自动修复（默认：无）
如果没有问题通过投票+验证：“5轮评审未发现漏洞，变更内容无明显问题。”

Step 7a: Post PR Review

步骤7a：发布PR评审

Write approved findings to a temporary JSON file, then run:
bash
scripts/post-review.sh <pr-number> <findings-json-file>
Then persist findings for resolution tracking:
bash
scripts/store-findings.sh <pr-number> <findings-json-file> <head-commit-sha>
将通过的问题写入临时JSON文件，然后运行：
bash
scripts/post-review.sh <pr-number> <findings-json-file>
然后持久化问题用于解决率追踪：
bash
scripts/store-findings.sh <pr-number> <findings-json-file> <head-commit-sha>

Step 7b: Autofix (User-Selected Findings)

步骤7b：自动修复（用户选中的问题）

For each finding selected for autofix:
  1. Read the file and understand surrounding context
  2. Generate a minimal fix (smallest possible change)
  3. Apply the fix using the Edit tool
  4. Scope check: Run 
    git diff --stat
    — verify only the finding's file was modified and diff is under 20 lines. If exceeded, revert and warn.
  5. Run existing tests if available (
    npm test
    , 
    go test ./...
    , 
    pytest
    , etc.)
  6. If tests pass: commit with 
    fix: {title} [bug-review]
  7. If tests fail: revert the fix (
    git checkout -- <file>
    ) and report to user
  8. After all fixes: push to the PR branch
Safety: one commit per fix, run tests between fixes, never force-push, scope-validate every fix.
对于每个选中自动修复的问题：
  1. 读取文件并理解上下文
  2. 生成 最小修复（改动量最小的变更）
  3. 使用Edit工具应用修复
  4. 范围检查：运行 
    git diff --stat
    —— 确认仅修改了问题所属文件，且diff行数<20。如果超出则回滚并发出警告
  5. 如果有现有测试则运行（
    npm test
    、
    go test ./...
    、
    pytest
    等）
  6. 如果测试通过：提交代码，提交信息为 
    fix: {title} [bug-review]
  7. 如果测试失败：回滚修复（
    git checkout -- <file>
    ）并向用户报告
  8. 所有修复完成后：推送到PR分支
安全规则：每个修复单独提交，修复之间运行测试，禁止强制推送，每个修复都做范围校验。

Command: /bug-review:resolve <PR>

命令：/bug-review:resolve <PR>

Run after a PR is merged to classify whether findings were resolved.
  1. Run 
    scripts/classify-resolutions.sh <pr-number>
    • Loads stored findings from 
      ${CLAUDE_PLUGIN_DATA}/bug-review/findings/pr-{N}.json
    • Checks if PR is merged
    • For each finding: diffs code between review commit and merge commit
    • Classifies each as RESOLVED, UNRESOLVED, or INCONCLUSIVE
    • Updates the stored findings file with resolution data
  2. Display resolution summary to user
  3. If enough data accumulated (10+ findings, 3+ PRs): run 
    scripts/update-weights.sh
    to adjust category weights
在PR合并后运行，分类发现的问题是否已解决。
  1. 运行 
    scripts/classify-resolutions.sh <pr-number>
    • 从 
      ${CLAUDE_PLUGIN_DATA}/bug-review/findings/pr-{N}.json
      加载存储的问题
    • 检查PR是否已合并
    • 对于每个问题：对比评审提交和合并提交的代码差异
    • 将每个问题分类为RESOLVED（已解决）、UNRESOLVED（未解决）或INCONCLUSIVE（无法确定）
    • 更新存储的问题文件，添加解决状态数据
  2. 向用户展示解决情况汇总
  3. 如果积累了足够数据（≥10个问题，≥3个PR）：运行 
    scripts/update-weights.sh
    调整分类权重

Command: /bug-review:report

命令：/bug-review:report

Display resolution rate statistics across all tracked PRs.
Run 
scripts/resolution-report.sh
which outputs:
  • Overall resolution rate
  • Resolution rate by severity
  • Resolution rate by category (sorted worst-first to highlight noisy categories)
  • Suppressed categories (weight < 0.1)
展示所有已追踪PR的解决率统计数据。
运行 
scripts/resolution-report.sh
输出：
  • 整体解决率
  • 按严重程度划分的解决率
  • 按分类划分的解决率（最差的排在最前，突出高误报分类）
  • 被屏蔽的分类（权重<0.1）

Repo-Specific Rules (.bug-review.md)

仓库专属规则（.bug-review.md）

Teams can create 
.bug-review.md
at their repo root:
markdown
undefined
团队可以在仓库根目录创建 
.bug-review.md
：
markdown
undefined

Focus Areas

重点关注领域

  • Pay special attention to authentication flows
  • Check all database queries for SQL injection
  • 特别注意认证流程
  • 检查所有数据库查询是否存在SQL注入风险

Ignore

忽略规则

  • Don't flag issues in generated files (*.generated.ts)
  • Ignore style-only concerns
  • 不要标记生成文件的问题（*.generated.ts）
  • 忽略仅与代码风格相关的问题

Invariants

不变规则

  • All API endpoints must check req.user before accessing user data
  • Database migrations must be reversible
  • 所有API端点在访问用户数据前必须检查req.user
  • 数据库迁移必须支持回滚

Severity Overrides

严重程度覆盖

  • Treat any auth bypass as CRITICAL regardless of category default
undefined
  • 所有认证绕过问题一律视为CRITICAL，不受分类默认严重程度限制
undefined

How to Use

使用说明

Read workflow.md for detailed step-by-step with error handling. Read review-passes.md for all 5 review pass prompts and the validator. Read categories.md for bug categories and learned weights.
查看 workflow.md 了解包含错误处理的详细分步指南。 查看 review-passes.md 了解全部5个评审轮次的提示词和验证器规则。 查看 categories.md 了解漏洞分类和学习权重。

Related Skills

相关技能

  • Consider creating a Runbook skill for investigating bugs found by this review
  • Consider creating a CI/CD skill to run this review automatically on PR open
  • 可考虑创建 运行手册 技能，用于调查本评审发现的漏洞
  • 可考虑创建 CI/CD 技能，在PR新建时自动运行本评审