先写变更约定，让AI提交更易审查

AI 写出的 PR，最难审的往往不是某一行代码，而是「为什么连这个文件也改了」。一次空值判断修复，顺手带进依赖升级、测试工具重写和配置调整，每处都能解释，整个 PR 却失去了边界。

作者提出的办法很轻：动手前写一页变更清单，约定目标、范围和验证方式，审查时逐项核对。它不能保证代码正确，但能让人看清自己到底在批准什么。对已经让 Agent 独立改代码的团队，这比再加一段漂亮的 AI 总结更有用。

为什么写完再补总结，管不住变更范围

作者对 AI 编程的观察是：生成代码变快，也让扩大范围变得便宜。人顺手重构一个模块，至少要付出打字、切换思路的成本；Agent 接到模糊任务后，可能把附近所有能改进的地方都当成任务的一部分。

问题不在于这些改动一定不好，而在于它们是否应该一起交付。

事后总结回答的是「已经做了什么」。模型很擅长为现成的 diff 编出流畅说明，却不能据此证明这些决定事先获得了认可。作者建议增加的 manifest，可以理解为一份实施前的变更约定：目标是什么，预计改哪里，靠什么证明完成，遇到哪些变化需要停下来确认。

审查的依据，应当包括实施前的约定，而不只是实施后的解释。

作者强调清单只保留 6 个字段。下面这份模板用于固定审查需要的信息，原样放进 PR 模板即可：

## Agent change manifest

### Task
One sentence describing the user-visible outcome.

### Expected scope
- Files or directories expected to change
- Explicit non-goals

### Approach
The smallest intended change and any important constraint.

### Evidence
- Checks to run
- Manual behavior to verify

### Risks and rollback
What could break, and how to undo the change.

### Not verified
What the agent could not test or confirm.

要重点看 Expected scope 和 Not verified：前者让范围可以核对，后者让未完成的验证不至于被「任务已完成」盖过去。它不是提示词记录，也不是 800 行工作日志，留下的是约定和证据。

一次表单修复，怎样划出够用的边界

作者给了一个接近真实场景的示例：个人资料里的 bio 是可选项，但留空时无法保存。原文称它为「real-ish example」，没有提供对应仓库或实际运行结果，因此应把它当作示范，不能当作修复效果的实测记录。

下面这份清单把一个模糊的「修复保存问题」，收敛到了具体输入处理和文件范围：

### Task
Allow users to save a profile when bio is empty.

### Expected scope
- `app/profile/ProfileForm.tsx`
- `app/profile/profile.test.tsx`
- No schema, dependency, or API changes.

### Approach
Treat an empty bio as undefined before the existing validation call.

### Evidence
- Run the profile test file.
- Manually save a profile with a blank bio in localhost.

### Risks and rollback
Risk: whitespace-only input behavior changes. Roll back the normalization line.

### Not verified
Did not test the mobile layout.

最该核对的是 No schema, dependency, or API changes. 这一行：如果 diff 里突然多了包、后端迁移或接口修改，审查者马上就有理由追问必要性。

这份示例也没有只写「测试通过」。它指定运行资料页测试，并在 localhost 手动保存空白 bio；同时指出纯空格输入可能受影响，移动端布局没有验证。范围、风险和证据由此连了起来。

实际执行分两阶段：先让 Agent 检查代码，只提出清单；任务负责人修正范围后，再让它实施。作者说小改动花一分钟就能完成这一步，但没有给出计时数据。

遇到新证据可以调整清单。比如发现必须修改另一个文件，就补上原因、更新验证项，再继续。重点是让扩大的范围成为一次可见的决定，避免等到审查 diff 时才发现「修个按钮」变成了页面重做。

审查分三遍，先看文件，再看行为和证据

第一遍先扫文件列表。每个变更文件，都应出现在预期范围里，或者有补充解释；预计要改却没有改的文件，也可能提示方案没做完整，但仍需结合实际判断。

夹带的全局格式化和无关重构，作者主张拆成独立 PR。即便重构合理，把它混进 bug 修复，也会增加寻找关键变更的成本。

作者还提到，大型研究发现失败的 Agent PR 往往涉及更多文件、更多检查失败和无关修改。不过原文没有给研究名称、样本量或链接，这里只能把它作为作者引用的论据，不能当作已经核实的统计结论。

第二遍沿用户实际操作路径审查。UI 改动就在本地浏览器里操作；API 改动要验证请求和错误响应；后台任务要检查重试与幂等，也就是重复执行会不会造成重复副作用。支付改动则应关注状态如何流转，不能只看新函数是否写得漂亮。

AI 可以协助这一遍审查，但需要拿到清单、diff、相关上下文和已执行检查。作者反对让它把所有猜测直接发成 PR 评论，建议先由人核实，再要求修改，减少围着虚构问题返工。

第三遍检查证据：声明的测试是否执行，构建失败是否如实报告，还有哪些浏览器状态、代码分支或外部依赖没验证。

「没有验证」是需要交接的信息，不该被包装成「应该没问题」。

作者据此提出小团队规则：每个 PR 一份清单，目标描述用户可见结果，每个文件变更都有范围依据，依赖、CI、迁移和权限变更必须获得审查者明确批准。最后这条尤其严格，因为它们可能影响当前业务代码之外的执行过程，需要懂相应领域的人参与审查。Agent 的最小权限也能配合这条规则，在执行环节限制未经批准的改动。

我的判断

我认同它把「控制范围」提前到了实施阶段。只对 Agent 说「保持 PR 小一点」，没有定义这次任务的小是什么；只靠事后总结，又容易接受一份听起来合理的解释。文件范围、非目标和验证方式，比这两种做法更容易核对。

但这仍是一套经验方法。原文没有提供团队规模、试行前后审查耗时、缺陷率或返工率，也没有与普通 PR 模板做对照。「它有效」是作者的判断，不能据此承诺审查效率会提高多少。

它还有一个前提：任务负责人有能力判断初始范围。陌生代码库里的问题可能跨层出现，预期文件列表不能变成禁止调查的边界。合理扩展需要记录理由；如果只奖励「一个文件都没多改」，也可能把必要修复压掉。

与现有工具相比，它最适合承担范围说明和验证交接。测试负责检查行为，CI 执行自动检查，代码所有者规则帮助找到合适的审查人。清单无法替代这些环节，也挡不住团队匆忙点下批准。

能拿来做什么

• 下次让 Agent 独立修复表单或实现功能时，先让它只读检查并填写这 6 个字段。确认目标、预计文件和非目标后，再进入修改阶段；一行拼写修正可以省去这套流程。
• 审前端 PR 时先扫文件列表，再打开 localhost 走清单里的操作路径。像空 bio 这样的修复，要同时核对输入处理、纯空格风险和对应测试，不能只接受「保存成功」的结论。
• 给 Agent 的审查输入同时附上 manifest、diff、相关文件和检查结果，并要求明确填写 Not verified。AI 提出的疑点先由人核实，再转成修改要求。
• 按作者建议试行两周，回看哪些 PR 更容易审、哪些仍然混乱，再调整模板。涉及依赖、CI、迁移或权限时单独明确审批要求，无关重构拆成后续 PR。