SuperAPI AI 工具集

pr-review

编程与开发

查看项目

更新于 10-22 16:16

技能介绍

Synthesis PR Review 是一项针对 synthesis-coded 项目中拉取请求(PR)的审查技能。其核心观点是:PR 不只是“代码能否运行”,而是“这个变更是否让系统变得更好,而不是更糟”。该技能定义了如何评估这一点。

一、定位与适用范围

该技能与另外两项技能覆盖不同范围:

  • codebase-review:完整代码库审计(16 个类别,分层检查),适用于新项目接手、周期性健康检查或重大里程碑。
  • multi-contributor-synthesis-coding:集成工作流(adopt-and-adapt 模式、质量门禁),适用于将贡献者工作合并到主分支。
  • pr-review(本技能):对单个变更进行增量审查,适用于每个 PR,在同行批准或主导者集成之前。

PR 审查是三者中最频繁的,发生在每次变更上。multi-contributor-synthesis-coding 技能中的质量门禁在此同样适用,但本技能将其具体化为明确的审查步骤。

二、增量审查思维

PR 审查是增量审查——评估的是变更相对于代码库当前状态的影响,而不是评估代码库本身。关键问题包括:

  • 这个变更是否做到了它声称的事?——阅读 PR 描述与代码,二者是否一致?
  • 是否引入回归?——之前能正常工作的部分是否可能被破坏?
  • 是否是正确的修复?——它解决的是根因还是症状?
  • 是否完整?——还是需要配套变更才能真正解决问题?
  • 是否一致?——是否遵循既有模式,还是无正当理由地偏离?

三、审查清单

  1. 范围与关注点分离
  • PR 只做一件事(不把多个不相关修复捆绑在一起)
  • PR 描述准确描述变更及其动机
  • 若捆绑了修复,每个修复都清晰标识且可独立成立
  • 危险信号:标题为“修复 X”的 PR 同时悄悄改了 Y。
  1. 根因分析
  • 修复针对实际根因,而非下游症状
  • 若根因复杂,PR 解释为何选择该特定方案
  • PR 不掩盖更深层的架构问题
  • 评估方法:问——如果导致该 bug 的底层条件以略有不同的方式再次出现,此修复是否仍然有效?若否,则是症状修复。
  1. 回归风险
  • 变更不破坏既有行为
  • 错误处理路径被保留(未被意外移除)
  • 边界情况仍可工作(空状态、错误状态、并发访问)
  • 若修改共享代码,所有调用方都被考虑在内
  • 技巧:反向阅读 diff——关注被移除或更改的内容,而不仅是新增内容。被移除的行是回归藏身之处。
  1. 架构一致性
  • 所用模式与代码库中类似事物的做法一致
  • 若模式偏离既有代码,偏离有正当理由
  • 未在未声明的情况下引入架构债务
  • 技巧:在代码库中找到最接近的类比。若组件 A 以一种方式处理重试,而此 PR 让组件 B 以另一种方式处理重试,追问原因。
  1. 完整性
  • 修复足以真正解决所述问题
  • 若需要配套变更(后端+前端、迁移+代码),要么包含在内,要么明确跟踪
  • 测试覆盖新行为(或给出不覆盖的明确理由)
  • 危险信号:针对根因在后端的问题做前端修复。
  1. 安全
  • diff 中无凭据或密钥
  • 系统边界处有输入验证
  • 受保护端点的认证检查被保留
  • 无新的 SQL 注入、XSS 或命令注入向量
  • 在 diff 中 grep 任何 logger.*、print()、console.log() 语句里的 secret、token、password、key
  • 检查 JWT/认证代码绝不记录凭据
  • 确认开发便利项已移除(硬编码邮箱、自动登录、跳过认证标志)
  • 对于大型 PR(>1000 行),质疑是否应拆分
  • 要求 PR 描述——没有描述的 PR 更难审查,也更可能隐藏问题
  • AI 代码助手警告:AI 编码工具常引入包含敏感数据的调试日志。添加预提交检查,标记暂存文件中 log.*secret、print.*token、console.log.*password 等模式。预防比审查时检测更可靠。
  1. 数据完整性
  • 数据库模式变更幂等(可安全多次运行)
  • 新字段有合理默认值或可为空
  • 无数据丢失场景(例如覆盖字段而不保留先前值)
  • API 契约向后兼容(或破坏性变更是有意为之并有文档)

四、验证 AI 生成的分析

当有人(无论是 AI 工具、贡献者还是团队成员)给出根因分析时,要对照实际代码验证结论,而不仅是中间发现。

为何重要:AI 分析可能 6 项中 5 项正确,但在结论上关键性错误。中间发现(文件 X 调用函数 Y,函数 Y 查询表 Z)可能都准确,但最终结论(“因此 bug 在查询中”)可能遗漏了实际以不同方式处理该情况的替代代码路径。

验证流程:

  • 自己阅读被引用的代码。不要依赖他人对代码行为的总结。
  • 寻找替代代码路径。分析可能准确描述了一条路径,却遗漏了另一条以不同方式处理相同输入的路径(错误处理器、回退逻辑、中间件、装饰器)。
  • 对笼统结论保持怀疑。“零影响”“完全损坏”“从不工作”这类说法几乎总是错的。现实通常更微妙。
  • 检查系统级视图。函数级分析可能孤立地正确,却遗漏了与缓存、中间件、事件处理器或后台任务的交互,这些会改变行为。
  • 测试结论,而不仅是中间步骤。若分析称“修改 X 将修复 bug”,在行动前独立验证该主张。

综合工程师的职责是依据系统级理解验证结论。AI 或贡献者可能做了扎实的分析工作——但结论正是错误累积之处。

五、审查流程

面向同行评审者:

  • 代码是否讲得通?——无需作者解释能否跟上逻辑?
  • 是否与 PR 描述一致?——若否,哪个错了——代码还是描述?
  • 你是否愿意在凌晨 2 点调试这段代码?——若否,代码需要更清晰。
  • 检查类比。——在代码库中找到最相似的代码。此 PR 是否遵循相同模式?
  • 同行评审者应有权要求修改,而不仅是批准。橡皮图章式批准比不审查更糟——它制造虚假信心。

面向主导综合者(Lead Synthesist): 除上述所有内容外,还需评估:

  • 项目特定标准——白标合规、UI 术语、部署安全
  • 架构契合度——此变更是否让代码库朝正确方向前进?
  • 集成复杂度——adopt-and-adapt 流程会是什么样?
  • 解决方案完整性——是完全解决问题,还是部分修复?

六、撰写审查反馈

  • 具体。“第 47 行移除了错误恢复路径——若 API 调用失败,轮询将永不恢复”是可操作的。“这有问题”则不是。
  • 解释原因。不要只说哪里错,要解释后果。
  • 区分严重程度:
    • 必须修复——阻止合并,导致回归或数据丢失
    • 应当修复——不阻止合并,但应尽快处理
    • 考虑——改进建议,不阻止
    • 吹毛求疵——风格或偏好,可采纳可不采纳
  • 肯定优点。具体指出做得好的地方。这会强化你希望再次看到的模式。

七、常见反模式

  • 橡皮图章:未真正阅读代码就批准。比不审查更糟——制造虚假记录。修复:若没时间好好审查,就直说。
  • 捆绑式 PR:一个 PR 中多个不相关变更。使审查更难,使 git bisect 无用,使回滚危险。修复:要求作者拆分 PR。
  • 症状修复:让可见问题消失而不解决底层原因。修复:问“若底层条件以略有不同的方式再次出现会怎样?”
  • 未经验证的假设:“这应该能行”而无验证。对难以复现的 bug 尤其危险。修复:要求复现步骤和验证。
  • 偏离模式:以某种方式实现,而代码库其余部分以另一种方式实现。修复:指出既有模式并要求对齐。

八、与 adopt-and-adapt 的集成

当 PR 通过审查并准备集成时:

  • 若 PR 干净——直接合并(在 synthesis-coded 项目中罕见,但随着贡献者质量提升可能发生)
  • 若 PR 需要适配——主导综合者创建集成分支,应用 adopt-and-adapt 模式,并合并适配后的版本
  • 若 PR 需要后续工作——合并已就绪部分,为剩余工作创建工单,并记录依赖关系
  • 审查发现直接输入集成计划。

九、使用 codebase-review 技能进行 PR 审查

codebase-review 技能有 16 个类别和分层检查。并非所有都与单个 PR 相关。对于增量审查,选择性应用:

  • 始终检查(每个 PR):安全(Gate 2)、架构(Gate 3)、完整性(Gate 1)、错误处理
  • 相关时检查:性能(若变更触及热路径)、数据库(若涉及模式变更)、API 设计(若新增/修改端点)、可观测性(若影响日志/监控)

codebase-review 技能是参考目录。本 PR 审查技能告诉你针对给定变更应从中提取哪些条目。