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 描述与代码,二者是否一致?
- 是否引入回归?——之前能正常工作的部分是否可能被破坏?
- 是否是正确的修复?——它解决的是根因还是症状?
- 是否完整?——还是需要配套变更才能真正解决问题?
- 是否一致?——是否遵循既有模式,还是无正当理由地偏离?
三、审查清单
- 范围与关注点分离
- PR 只做一件事(不把多个不相关修复捆绑在一起)
- PR 描述准确描述变更及其动机
- 若捆绑了修复,每个修复都清晰标识且可独立成立
- 危险信号:标题为“修复 X”的 PR 同时悄悄改了 Y。
- 根因分析
- 修复针对实际根因,而非下游症状
- 若根因复杂,PR 解释为何选择该特定方案
- PR 不掩盖更深层的架构问题
- 评估方法:问——如果导致该 bug 的底层条件以略有不同的方式再次出现,此修复是否仍然有效?若否,则是症状修复。
- 回归风险
- 变更不破坏既有行为
- 错误处理路径被保留(未被意外移除)
- 边界情况仍可工作(空状态、错误状态、并发访问)
- 若修改共享代码,所有调用方都被考虑在内
- 技巧:反向阅读 diff——关注被移除或更改的内容,而不仅是新增内容。被移除的行是回归藏身之处。
- 架构一致性
- 所用模式与代码库中类似事物的做法一致
- 若模式偏离既有代码,偏离有正当理由
- 未在未声明的情况下引入架构债务
- 技巧:在代码库中找到最接近的类比。若组件 A 以一种方式处理重试,而此 PR 让组件 B 以另一种方式处理重试,追问原因。
- 完整性
- 修复足以真正解决所述问题
- 若需要配套变更(后端+前端、迁移+代码),要么包含在内,要么明确跟踪
- 测试覆盖新行为(或给出不覆盖的明确理由)
- 危险信号:针对根因在后端的问题做前端修复。
- 安全
- 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 等模式。预防比审查时检测更可靠。
- 数据完整性
- 数据库模式变更幂等(可安全多次运行)
- 新字段有合理默认值或可为空
- 无数据丢失场景(例如覆盖字段而不保留先前值)
- 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 审查技能告诉你针对给定变更应从中提取哪些条目。