审阅 是做什么的?
从一个独立的视角,在两个独立的维度上评判变更:方向性(是否构建了正确的内容,即规格)和质量(是否构建良好)。审阅发现必须有证据支持,并根据真实用户可能遇到的情况评定严重程度。然后,基于技术上的严谨性而非顺从性来处理发现项。
核心原则: 只有当变更确实改善了代码库的健康状况并完成了要求时,才批准该变更,即使它不是你编写的方式。从不批准你实际上没有阅读和检查的变更。
流程位置: 规格 → 计划 → 构建 (+ 测试) → 审阅 → 合并。
第一步:确定范围
- 用户指定范围(PR、分支、提交范围、文件)。否则:当前分支与其与默认分支的合并基础之间的内容,加上未提交的更改。
- 在执行任何其他操作之前,先解析固定提交点并确认范围非空:
git rev-parse <ref>、git log <ref>..HEAD --oneline、git diff <ref>...HEAD --stat(用于已提交的工作),以及git diff --cached --stat(已暂存)、git diff --stat(未暂存)和git status --short(未跟踪)(用于未提交的更改)。审阅两者的并集。当未提交的更改在范围内时,请告知每位审阅者(审阅者提示中有相应内容)。如果提交引用无效,或两者范围均为空,则在此处失败。 - 对于 PR,阅读其描述和关联的问题。
第二步:收集意图
按顺序查找:变更所实现的规格和计划(specs/<slug>/、提交/PR 中的链接、用户提供的路径)、构建记录中的 Ruling: 行,以及它关闭的问题。用两三句话重述意图。如果没有规格,请说明:此时方向性维度将根据 PR 描述和用户的合理期望进行评判。
同时查找标准:CONTRIBUTING.md、CODING_STANDARDS.md、CLAUDE.md/AGENTS.md、lint 配置、ADR、术语表。
大小检查。 约 100 行改动是理想的,约 300 行对于一个逻辑变更来说是可接受的,约 1000 行则太大而难以有效审阅:建议拆分(按堆叠、按文件组或按垂直切片)作为一个发现项。重构与功能开发混在一起算两次变更。
第三步:使用全新上下文进行审阅
作者对自己的假设视而不见,编写代码的 session 也是如此。当子智能体工具可用时,使用 reviewer-prompt.md 分派具有全新上下文的审阅者:给他们差异(作为文件或精确命令)、规格/计划路径、标准文件和记录裁决。绝对不要给他们的 session 历史。审阅者是只读的,并且不会生成他们自己的审阅者。
并行运行,以便一个维度不能掩盖另一个维度:
- 方向性审阅者:遗漏、多余、误解。
- 质量审阅者:正确性、测试、设计、安全、性能。
- (可选,适用于高风险或大范围变更) 影响范围审阅者:grep 无法显示的,这个变更会破坏什么。
对于整个分支的审阅,使用最强大的可用模型。如果没有子智能体工具,则自己分轮次完成每个维度的审阅,并将结果标记为自我审阅:弱于全新的审阅者,由用户判断是否足够。
内联审阅自己刚刚完成的分支不能替代此步骤。
方向性维度
将差异与要求进行对比:
- 遗漏:需求或成功标准被跳过、部分实现或声称实现但未实际实现。引用规格中的相关行。
- 多余:没有人要求的行为、推测性的选项、钩子或抽象(范围蔓延,YAGNI)。
- 误解:正确的功能以错误的方式构建,或者解决了错误的问题。
- 从差异中无法验证:存在于未更改代码中或跨多个变更的需求。列出需要检查的内容而非猜测。
规格是一份愿景文档,而非详尽清单。 在规格未提及之处,合理的用户期望就是要求。规格对一个输入保持沉默,不等于允许它导致崩溃。
质量维度
先阅读测试:它们揭示了意图和覆盖率。
测试
- 每个新行为是否都有一个在行为被破坏时会失败的测试?尽可能通过实验来回答:翻转变更添加的一个条件并运行测试套件,在一个独立的工作树或副本中进行,以便被审阅的检查点永不改变。如果突变测试仍然通过,则是一个发现项:指出缺失的测试。
- 通过公共接口测试行为,而非内部实现;不针对 mock 进行断言;不包含由被测试代码计算的期望值;仅在系统边界使用 mock。
- 错误修复必须有回归测试。没有跳过或禁用的测试。测试输出清晰。
正确性
- 符合规格;处理边缘情况(null、空、零、最大值、unicode、并发);错误路径,而不仅仅是快乐路径;差一错误、竞态、可能不同步的状态。
可读性和简洁性
- 名称能说明事物是什么以及做什么。控制流程简单明了。能否用更少的行数实现?每个抽象是否物有所值(在第三次使用前不要泛化)?
- 死代码、无操作变量、
// removed注释、没人需要的兼容性 shim。 - 注释解释为什么,而不是是什么。描述变通方法的注释通常标志着未修复的根本原因。
设计
- 符合现有模式;新模式需要有理由。
- 重构是减少了读者必须理解的概念,还是仅仅转移了它们?优先选择使分支、模式或层消失的版本。
- 功能逻辑泄露到共享模块中;与现有辅助函数几乎重复;在无关的流程上强行添加条件判断;针对相同结构反复使用 switch 语句(缺少模型或调度器);必须与第一个布尔值保持同步的第二个布尔值(缺少状态机)。
- 只有单个调用者的包装器和直通层(内联它们)。可变状态的范围比需要的更宽。
- 在边界进行验证,内部信任。没有用静默回退掩盖不明确的不变量;没有不必要的
any/强制类型转换。 - 文件增长:导致文件远超健康大小的变更应首先进行分解。
安全性
- 不可信输入(HTTP、CLI、文件、环境变量、LLM 输出、第三方响应)在边界处验证。查询参数化。输出编码。在需要处检查身份验证/授权。秘密信息不应出现在代码、日志和 VCS 中。新的依赖项需有合理理由、得到维护、许可证兼容;检查 lockfile 差异。
性能
- N+1 查询、无界循环或获取、缺少分页、阻塞性的同步工作、热路径上的大内存分配、不必要的重渲染。尽可能量化(“~50ms/行,1000 行时”)。
味道基线(判断性调用;仓库文档化的标准优先): 神秘命名、重复代码、依恋情结、数据泥团、基本类型偏执、重复 Switch、霰弹式修改、发散式变化、夸夸其谈未来性、消息链、中间人。
影响范围维度(高风险或大范围变更)
列出调用者不是该做的工作;grep 一秒钟就能完成。该做的工作是 grep 无法显示的破坏:
- 找到这个变更安全所基于的一个事实(“这个调用只删除已经失效的条目”)。通过运行代码来证明:编写一个脚本,在固定版本下导入真实库并调用确切的函数。
- 查看符号搜索停止的地方:库源代码和本地补丁、执行时序(异步排序、清理)、序列化格式(JSON 结构、数据库列、线协议、读取相同字节的其他语言)、特性开关、三跳之外的消费者。
- 对于每个风险:它如何破坏、
file:line、可能性、成本以及最便宜的检查。将已检查并排除的风险单独列出。
第四步:验证每个发现项
听起来合理的发现项并非真正的发现项,除非经过检查。
- 对照访问该代码的调用者、守卫条件和测试进行检查。如果它们排除了该发现项,则放弃。
- 证明重要的发现项:一个失败的测试、一个重现脚本或显示错误行为的命令输出。优先选择通过运行证明的发现项,而不是看似合理的。
- 将预先存在的缺陷与本次变更引入的回归缺陷分开标记。
- 合并具有相同根本原因的发现项。
- 零发现项是有效结果。 不要为了显得周全而捏造发现项。
阻止合并的标准
发现项可以被评为严重或重要,从而阻止合并,仅当它通过证据确立时:
- 一个显示错误行为的运行(测试、脚本或命令),或者
- 一个具体的输入,通过代码一步步追踪到错误输出,每一步都有
file:line。
一个无法通过这种方式确立的合理担忧(“这可能会破坏X”,“边缘情况可能未处理”)将被评为轻微并标记为未验证。它不会阻止合并。列出它,以便作者可以检查。
第五步:分级并报告
根据对软件交付后合理用户的影响进行分级,而非根据规格是否提及触发条件。
| 严重程度 | 含义 | 需要采取的行动 |
|---|---|---|
| 严重 | 安全漏洞、数据丢失、核心功能损坏 | 阻止合并 |
| 重要 | 错误或脆弱的行为、遗漏的需求、未经测试的行为、吞没的错误、破坏性的重复或设计 | 合并前修复 |
| 轻微 | 润色、小的简化、更广的覆盖率 | 作者决定;如果推迟,记录在案 |
| 不值一提 | 风格偏好 | 可选 |
| 仅供参考 | 上下文,无需操作 | 无 |
从影响力最大的开始:首先是正确性和安全性,然后是结构问题和遗漏的简化,最后是其余内容。如果有一个结构问题加十个不值一提的小问题,那么结构问题就是审阅的全部内容。提出解决方案,而不仅仅是问题:“用按 kind 键控的查找表替换这个 if 链”、“内联这个单调用者包装器”、“重用 utils/date.ts 中的 formatDate”。
要诚实:不要走形式的“LGTM”,不要把真正的错误轻描淡写为“可能是个小问题”,也不要把不值一提的小问题夸大为严重。具体指出哪些地方做得好。
使用 reviewer-prompt.md 中的格式:方向性裁决、优点、按严重程度列出的问题(每个问题包含 file:line、错误内容、重要性、修复方法、证据)、影响范围说明、拒绝评判(已考虑但搁置的行为,附理由)以及裁决:批准、有条件批准或请求变更。保持方向性和质量部分分开;不要跨部分重新排序。
裁决规则: 仅当至少一个严重或重要发现项满足上述证据标准时,才请求变更。一个完成了要求且仅有轻微或未验证问题的变更将被批准,同时列出这些问题。拒绝一个正确的变更对作者造成的代价,与批准一个有问题的变更一样大。
第六步:处理发现项(当你是作者时)
审阅反馈是需要评估的输入,而不是必须执行的命令。
- 全部阅读后再做回应。如果任何条目不清楚,在任何实现之前先询问:条目之间通常有关联。
- 重述每个条目为一项技术要求,并对照代码进行验证。这对这个代码库是否正确?它是否破坏了什么?当前代码这样写是否有原因?审阅者是否拥有全部上下文?
- 用证据反驳当它错误时:一个测试、一个
file:line、一个测量。如果一个建议添加了一个未使用的“合适”特性,请检查使用情况;YAGNI 也适用于审阅者。将任何与他们先前决定相冲突的内容升级给用户。 - 按顺序修复:严重/阻塞 -> 简单 -> 复杂。每个修复先创建一个重现该发现的失败测试(通过
test),然后进行修复,最后是全部绿色的测试套件。进行一次专注的修复,而不是无限循环。 - 未修复的轻微问题放在最终消息的“已推迟”列表中。你决定不修复的发现项是一个有理由的已记录决策。
- 没有表演性的同意。 没有“您完全正确!”、“好发现!”或感谢之词。陈述你更改了什么(“已修复:空行现在仅输出带标题行的 CSV;测试
exports header for empty view”)或代码保持不变的原因。如果你反驳但后来发现自己错了,用一句话说明并修复它。
在 GitHub 上,回复内联评论线程,而不是发表顶层评论。
合并前(完成定义)
- 每个规格成功标准均已满足并在运行系统中验证
- 新行为有在无变更时会失败的测试;整个测试套件绿色通过,输出清晰
- 没有未解决的关键或重要发现项;推迟的项目附有理由
- 没有死代码、调试输出或注释掉的代码块;变更范围限定于任务
- Lint、类型检查、构建通过
- 已考虑迁移、配置和标志;对于有风险的变更存在回滚路径
- 公共接口和用户可见行为已文档化;对于难以撤销的决策有 ADR
- 提交消息和 PR 描述以独立的语言说明变更了什么以及为什么
- 在项目要求的地方,已获得人工批准
常见错误认知
| 想法 | 现实 |
|---|---|
| “测试通过了,所以没问题” | 测试无法捕获错误的设计、安全漏洞或对规格的误读。 |
| “我写的,我知道它是正确的” | 同一个作者,同样的盲点。获取全新视角。 |
| “AI 生成的代码可能没问题” | 当它出错时,它自信且看似合理。它需要更多而不是更少的审查。 |
| “重构后更清晰了” | 如果读者要理解的概念数量相同,那只是移动了。 |
| “我们稍后再清理” | 稍后很少会来。现在修复或明确记录。 |
| “规格没有提到那个输入” | 沉默不等于允许。根据用户得到的结果进行分级。 |
| “审阅者说‘轻微’,所以它是轻微的” | 根据影响重新分级。 |
| “修复很明显,不需要测试” | 失败的测试是证明发现项真实存在且已消除的唯一证据。 |
| “审阅者可能是对的” | 先对照代码验证。 |
危险信号
- 没有阅读证据的“LGTM”
- 没有
file:line的发现项,或者未经检查调用者和守卫条件就声称的发现项 - 方向性和质量发现项合并到一个排序列表中
- 将不值一提的小问题放在正确性错误之前
- 审阅者获得了作者的 session 历史
- 修复审阅发现项时没有先创建失败的测试
- 实施部分反馈意见而忽略其他意见