基于 review-pr Skill 的 PR 分支审查方法论:从 git diff 到缺陷分级报告
基于 review-pr Skill 的 PR 分支审查方法论:从 git diff 到缺陷分级报告
导读
本文围绕 Trail of Bits skills 仓库中 code-improver 插件所依赖的 review-pr 技能(Skill)展开,完整拆解它如何以“只审查分支变更面、而非整个仓库”为原则完成一次 Pull Request 审查:从建立 base 分支与 HEAD 之间的 diff、逐 hunk 校验正确性、核对测试覆盖、检查文档是否过期,到按严重级别逐条报告缺陷。与此同时,本文结合该技能在 pr-improver 入口技能与 improve.js 动态工作流中的实际调用方式,说明这一审查方法如何被循环复用、如何被机器校验,帮助读者在 Claude Code 等 Agent 环境中亲手落地这套可重复、可验证的 PR 审查流程。
一、认识 review-pr Skill:它是谁,用在哪儿
review-pr 是 code-improver 插件 默认配置的 PR 审查技能,其定义位于 plugins/code-improver/tests/fixtures/pr-review-toolkit/skills/review-pr/SKILL.md。它的定位是:把当前分支相对 base 分支的改动当作一次 Pull Request 来审查——审查新增与修改代码的正确性、这些代码的测试覆盖情况,以及文档是否被改动改得失真。
它在仓库中的使用场景有两层:
- 独立一次性审查:用户要求“review this branch / this diff / this PR”时,直接调用该技能即可完成单次审查;
- 自动化“审查-修复”循环的评审者(reviewer):
pr-improver技能在启动 improve.js 动态工作流时,默认把pr-review-toolkit:review-pr作为reviewer注入循环,让它在每一轮迭代中对分支改动反复审查,直到零 critical/major 缺陷(见 pr-improver 技能 的调用参数示例)。
从 pr-mode 评估用例 可以看到该技能被验证的方式:一个带 main 与 feature 分支的仓库,feature 分支上预埋了一个带测试缺口的中位数 bug、一条被改动搞过期的 README 声明,以及一个分支从未触碰过的目录中的“诱饵”bug——最终判分要求循环收敛、bug 被修复且补上测试、README 恢复准确、未触碰的文件保持字节级一致。这正是 review-pr“只审查变更面、不越界报告”的方法论被机器验证的具体体现。
二、Skill 元信息:触发条件与工具边界
review-pr 的 YAML frontmatter 定义了该技能的元信息,直接决定了它何时被触发、可以使用哪些工具:
| 字段 | 值 | 含义 |
|---|---|---|
name |
review-pr |
技能的唯一标识,被引用时使用命名空间形式 pr-review-toolkit:review-pr |
description |
Reviews the current branch's changes against its base branch as a pull request: correctness of new and modified code, test coverage for it, and documentation accuracy. Use when asked to review a branch, a diff, or a pull request. | 触发描述:当用户要求审查分支、diff 或 PR 时激活 |
allowed-tools |
Read Grep Glob Bash |
审查者可用的工具集合:读取文件、正则搜索、glob 定位、执行 shell 命令 |
值得注意的是 allowed-tools 中没有 Write/Edit——审查者被设计为只读角色,这保证审查行为本身不会污染工作区。在 improve.js 的循环中,这一点被进一步强化:每一轮都明确要求 reviewer “perform no writes at all”,审查与修复严格分离,修复由独立的 fixer 完成。
三、核心方法论:只审查变更面
Skill 正文开宗明义一句话定下铁律:
Review the branch's change surface, not the whole repository.
这是整个方法论的总纲。分支审查的边界是 diff,不是整个代码库;缺陷是否值得报告,取决于该缺陷是否位于分支实际改动过的文件/代码块中。这条边界在自动化循环里被升级成了机器强制约束:pr-improver 从 git diff --name-only <base>...HEAD 提取变更文件,再映射为目录级 glob 作为 scope,improve.js 的 scope guard 在每一轮修复后都会用 git diff 校验是否存在越界修改,越界即 halted。
四、五步审查流程详解
步骤 1:建立 diff——确定“变更面”的精确边界
第一步是确定要审什么:
git diff <base>...HEAD
<base>是调用方指定的基准分支名,未指定时回退到main;- 使用三点语法
...比较的是 base 与 HEAD 之间的共同祖先到 HEAD 的差异,即“分支真正带来的改动”,而非 base 当前状态与 HEAD 的差异; - 当工作区还带有属于该分支的未提交改动时,需要补充执行
git diff <base>(两点语法),把暂存区/工作区的未提交变更也纳入审查范围。
对应到 pr-improver 技能 中的落地实现:先 git rev-parse --show-toplevel 确认仓库根,再取参数或默认分支(git symbolic-ref refs/remotes/origin/HEAD 的短名,兜底 main),随后用 git diff --name-only <base>...HEAD 列出变更文件,并做一条防御性检查——当前分支就是 base 时拒绝运行(没有可审的 diff)。
从源码结构看,improve.js 的基线阶段 进一步把“diff 边界”固化为可审计的基线:记录 HEAD sha、用 git ls-files --others --exclude-standard 枚举未跟踪文件并逐个 hash-object 计算内容哈希——因为 git diff 永远看不见未跟踪文件的变化,内容哈希成为这些文件被越界改写时的唯一证据。
步骤 2:逐个 hunk 检查正确性
对每个被改动的代码块(hunk),从三个角度审查正确性:
- 边界输入上的错误结果(wrong results on edge inputs):空集合、长度奇偶、溢出、空指针、索引越界等边界情形是否处理正确;
- 未处理的错误路径(unhandled error paths):文件不存在、网络失败、解析失败、权限不足等错误分支是否有对应处理;
- 与函数名或调用方语义相矛盾的行为(behavior that contradicts the function's name or callers):实现是否辜负了函数名承诺的语义,或是否破坏了某个既有调用方对它的假设。
这三个角度共同构成“正确性审查”的完整检查面。在 pr-mode 评估用例 中,预埋的“偶数长度中位数”bug 正是“边界输入上结果错误”的典型:奇数长度返回中间元素、偶数长度应返回中间两元素的平均值,而预埋实现漏掉了后者。
步骤 3:核对变更行为的测试覆盖
审查者必须检查被改动的行为是否有测试覆盖:
New logic without a test exercising its edge cases is a finding.
即:新增逻辑若没有针对其边界情况的测试,本身就是一个 finding(缺陷项),而不是“建议”。这一条在循环机制里被强化为硬性要求——improve.js 的 FIX_SCHEMA 要求每个修复(verdict 为 fixed)都附带 pin:一个针对修复前代码必然失败、修复后通过的测试或断言(纯文档改动可标注 none: prose-only change)。也就是说,行为变更必须有“钉住”它的测试,修复是否成立由下一轮审查用读代码的方式验证(verified_fixed),而非由修复者自证。
步骤 4:检查 diff 是否让文档失真
Check documentation the diff made stale: statements in README or docs that were true on the base branch and are false after the change.
文档准确性与代码正确性同等重要:审查 README 或 docs 中那些在 base 分支上为真、改动后为假的陈述。典型场景是接口签名变了但文档还写着旧签名、默认值变了但文档还写着旧默认值、行为语义变了但文档仍描述旧行为。这类“文档过期”同样构成 finding。pr-mode 用例中预埋的“README 声称 mean 是唯一统计量”就是一条典型的被改动搞过期的文档陈述。
步骤 5:分级报告所有缺陷,且只报告分支触碰过的文件
最后一条是报告契约:
- 报告发现的每一个缺陷,并为每个缺陷标注严重级别(severity);
- 包括 minor 和 informational 级别的低危发现——不允许审查者自行预筛或扣留低危项;
- 不报告分支未触碰的文件中的缺陷——它们不在本次 Pull Request 范围内。
这条“低危也要报、越界不能报”的双向约束,恰好对应 improve.js 的 SEVERITIES 与 BLOCKING 定义:严重级别被归一化为 critical | major | minor | info 四级,其中 critical 和 major 构成阻塞级(blocking);报告阶段要求“不预筛”,而是否阻塞由循环在账本(ledger)层面统一裁决一次,而不是在每个 reviewer 那里各裁一次。
五、从单次审查到循环审查:review-pr 在自动化循环中的角色
review-pr 的单次方法论是闭环的(建立 diff → 审 hunk → 核测试 → 核文档 → 分级报告),但当它被嵌入 pr-improver 驱动的“审查-修复”循环时,还需要遵守额外的契约才能与账本、scope guard、振荡检测协同工作。这些契约定义在 improve.js 的 REVIEW_SCHEMA 中:
- 每条 finding 必须携带
id(file:line:class)、file、line、class、severity、title、evidence七个字段,其中class是短横线连接的缺陷类别(如dangling-reference); - 已知 finding 再次出现时必须复用账本中的精确 id,即使行号已发生偏移——这是账本能跨轮匹配、避免重复派发的关键;
- 被
rejected的 finding 除非带来new_evidence: true且确实提供拒绝理由未覆盖的新证据,否则不得重新上报——一轮裁决不被反复翻案; - 修复必须通过读代码验证:
verified_fixed列出确认成立的修复 id,没成立的修复按原 id 重新上报(等价于“修复未生效,重新开启”); - 如果该技能内部编排了专家子代理(SKILL_REVIEW_SCHEMA 的
dispatch模式),由于工作流子代理无法再派生子代理,它不能直接启动专家,而应把派发请求交回循环,由循环代为执行(最多 3 波、每波 8 个专家)后再继续审查。
六、一次真实运行的完整观感:pr-improver 如何驱动 review-pr
把上文串起来,一次典型的 PR 分支审查-修复运行如下:
- 用户发出类似“review this branch”或“clean up this branch until review passes”的指令;
pr-improver解析 base 分支与变更文件,推导出目录级 scope(<变更目录>/**),定位 improve.js 工作流脚本,以reviewer: {"kind": "skill", "name": "pr-review-toolkit:review-pr"}启动;- 工作流逐轮执行:审查(调用 review-pr)→ 账本裁决 → 修复(fixer 只处理阻塞级 finding,附测试 pin)→ scope 检查 → 再审查;
- 循环只有在“最后一次动作是零阻塞级 finding 的审查”时才以
converged: true结束;修复预算耗尽则显式输出 capped, NOT converged 并列出剩余阻塞项;连续三轮计数不降、同一 finding 连续三轮出现、或同一 finding 被“修复”两次,则触发振荡升级(escalation),要求设计决策而非继续烧轮次(见 README 的 Guarantees 一节); - 所有产物落在
.code-improver/<目标名>/目录:ledger.json(跨轮记忆)、fixes-round-N.diff(每轮累计 diff)、status.md、metrics.json等(README 的 Artifacts 表),且循环从不 commit,所有改动停留在工作区等待人工复核。
七、适用前提与边界
把 review-pr 投入实战前,需要明确它的适用前提:
- 必须位于 git 仓库内:diff 建立与 scope 校验都依赖可 diff 的基线;improve.js 在目标不在仓库时会以显式身份(
code-improver-baseline)执行git init并提交基线快照,且会大声告知用户“创建了一个 git 仓库”; - 运行环境为支持动态工作流的 Claude Code:循环本身是工作流脚本,其他客户端(如 Codex)只能加载技能、无法运行循环(README 的 Requirements);
- 审查者必须已安装:
review-pr技能由pr-review-toolkit插件提供;若该插件缺失,循环以halted: "reviewer-unavailable"大声退出并给出安装指引,绝不以内联模仿的审查顶替——因为那样会失去账本、scope guard 与升级保障的全部保证。
对于“仅需一次性审查”的场景,正确的做法是直接调用 review-pr 技能本身,而非启动循环——循环的价值在于迭代收敛,单次审查用不到它的全部机制。
总结
review-pr 用短短五步定义了一套可执行、可机器校验、可跨轮复用的 PR 分支审查方法论:以 diff 为唯一边界,逐 hunk 查正确性,用测试覆盖卡住新逻辑,用文档失真检查守住一致性,最终按 critical/major/minor/info 全量分级上报、严格限定在分支触碰过的文件内。它在 code-improver 插件中既可作为独立审查技能直接调用,也可作为 pr-improver 循环的默认 reviewer 反复执行,配合跨轮 findings 账本、机械 scope guard 与振荡升级机制,构成了一个“审查-修复直到干净为止”的自动化闭环。理解这份 Skill,等于同时掌握了单次 PR 审查的全部检查维度与自动化循环对审查者的全部接口契约。