如何验收 Agent 的产出
系列入口：如何使用 Agent。本篇是 M8 的起点，承接 M7 的测试先行与Git 检查点。
一、为什么验收是不可省的一环
Agent 最擅长的恰恰也是最容易骗过你的：它产出的东西结构完整、措辞自信、命名规范，第一眼几乎无可挑剔。但形式上的完整从来不等于正确——它可能漏掉了某个你没反复强调的需求、把不相关的代码也改了、测试虽绿却没测到点上，甚至在信息不足处用一个看似合理的编造补上。
验收的本质，是把"我感觉它做完了"换成"我逐条确认它做对了"。 这一步省下来的几分钟，往往会在日后以线上 bug、返工、信任崩塌的形式加倍偿还。好消息是验收不必逐行死磕，有一套高效的固定流程。
二、第一步：先对照需求，而不是先看代码
验收最容易犯的顺序错误，是一上来就钻进代码细节。正确的第一步是回到最初的需求，逐条检查每一项是否都被满足，并且在看实现之前先做——因为这样你最容易发现"遗漏"。
为什么遗漏要最先查？因为它在代码里最不可见。一处写错的逻辑也许会被测试或运行暴露，但一个根本没做的需求，如果不主动核对清单，你在满屏新增代码里几乎察觉不到"这里本该还有一块"。Agent 尤其容易在需求有好几条时，把显眼的做了、把某条不起眼的悄悄略过，然后交回一份完整、肯定的总结。
实操很简单：把需求拆成可勾选的条目，逐一问"这个做了吗、证据在哪"。任何一条找不到对应的代码或测试，先标记为缺口，而不是被它"已完成"的总结说服。用需求清单驱动验收，而不是用它的交付总结驱动。
三、第二步：读 diff，看清真实改动
确认需求覆盖后，再看它具体改了什么。核心工具是 diff，而不是只看新增或修改后的最终文件——diff 同时告诉你"加了什么"和"动了什么、删了什么"。
读 diff 有几个重点：
- 有没有越界改动：它是否顺手改了你没要求动的文件、配置、公共接口？范围蔓延是常见隐患，一处"顺便"可能影响 unrelated 的功能。
- 删了什么：删除的代码、分支、校验是否真的不再需要，还是为了图省事被绕过。
- 改动是否对症：每处改动是否都能对应到某条需求，而不是塞进一堆说不清用途的东西。
一个高价值的习惯是看 diff 的文件清单和增删统计先建立整体印象，再聚焦高风险文件（鉴权、支付、数据迁移、对外接口）。你要验收的是"最小且正确的改动"，而不是"一大堆看起来很努力的改动"。
四、第三步：跑测试、构建与检查
静态阅读之后，必须用客观命令验证：测试是否通过、能否正常构建、lint/类型检查是否干净。这里要特别警惕两种"假绿"。
一种是测试本身无效——断言空泛、只验证"不报错"、或从未失败过，这样的测试全绿也保证不了行为。另一种是只跑了被改动的一小撮、没跑全量，集成层面的冲突因此漏掉。理想情况是先跑相关的快速测试做即时反馈，再跑一次完整套件确认没有牵一发而动全身。
对于没有测试或测试覆盖薄弱的部分，命令行能给的信号有限，这时更要靠你实际运行关键场景、手动走一遍主路径来补位。不要因为"命令全绿"就停下，先确认这些命令确实在检验你关心的行为。
五、第四步：抽样回到原始材料核对
最后一步针对最会伪装的问题——自信的编造和事实性错误。做法是从产出中随机挑几处关键陈述或实现，回到原始代码、数据或文档核对其是否属实，而不是仅凭内部逻辑自洽就放行。
这类抽查不必多，但要挑要害：它声称调用了某接口、某函数有几个调用方、某字段是这个含义——这些论断在真实代码里真的成立吗？Agent 在信息不足时会用同样自信的语气补全猜测，读的人很难凭文风分辨，而抽样核对能快速让这类"事实性幻觉"露馅。
这里的关键认识是：一段代码内部再自洽，如果它依据的外部事实是错的，依然是错的。 让"事实一致"和"逻辑正确"并列，你才挡得住这类最隐蔽的错误。
六、一个真实的验收场景
设想一个很常见的需求："给用户导出接口加一个按时间范围筛选的参数。"Agent 很快返回：参数已加、筛选逻辑写好、测试通过，总结里写着"任务完成"。如果你只看这份总结就放行，很可能漏掉下面这些真实发生过的问题，而它们恰好对应前面的四步。
对照需求时你可能发现：需求其实包含"默认时间范围为最近 30 天"，但代码里默认是全部数据——一条不显眼的需求被略过了。读 diff 时你发现它顺手把另一个导出方法的签名也"统一"改了，那是个被别处调用的公共方法——范围蔓延。跑测试确实全绿，但你点开那个新测试，发现断言只写了"返回 200"，无论筛选是否生效都会绿——假绿测。最后你核对它"复用了 formatDate 工具函数"的说法，发现那个函数处理的是展示格式、并不适合数据库查询——看似合理的错误依据。
这个例子说明：每个问题单看都不致命，叠在一起却会变成线上事故，而四步验收能在十分钟内把它们全部拦下。 验收的价值不在某一步多高深，而在这套顺序稳定地覆盖了遗漏、越界、无效验证和事实错误这四类高发缺陷。
七、怎么确认测试"真的有效"
全绿不等于被测，判断一个测试有没有效，有个朴素而强力的方法：故意把实现改坏一点，再跑测试，看它会不会变红。
你可以临时把一个关键条件取反、把一个边界值改错、或让函数返回错误结果。如果测试照样通过，说明它根本没有检验你关心的行为，是个给人安慰的摆设；只有它立刻变红，才证明它确实守在那里。这个"变异检查"不必对每个测试都做，抽查新增和关键路径上的几个即可，成本很低却能准确识别假绿。
同时看断言的质量：是否检查了具体的、可证伪的结果（具体数值、字段、状态变化），还是停留在"没抛异常""返回了东西"这类永远成立的空话。一个从不失败的测试，和没有测试相去不远。
八、长任务要在中途设验收点
验收不是只能在最后做。对于多步骤、跨文件的大任务，等它全部做完再一次性验收，往往既难审、返工又大——满屏改动里定位一个早期偏差代价很高。
更好的做法是像 异步长任务 讲的那样，在关键节点让它停下来交付一阶段成果，你快速确认方向无误后再放行下一步。比如先确认接口设计和改动范围、再确认核心逻辑、最后才是完善与收尾。这样一个早期的理解偏差会在刚出现时就被纠正，而不是被后面的几百行代码层层包裹。
中途验收点本质上是用小而频繁的确认，替代一次巨大而痛苦的终审。 这也让回退便宜——借助 Git 检查点，发现某步走偏只需退到上一个干净节点，而不是推翻整段工作。
九、发现问题后怎么打回
验收发现缺口或错误时，打回的方式直接影响修正质量。笼统地说"这里不对，改一下"，往往换来它在表面打补丁，甚至引入新问题。
高效的打回应具体、可验证、且限定范围：指出是哪条需求没满足、哪个文件哪处逻辑与事实不符，并明确期望行为与验证方式。例如"需求里要求默认最近 30 天，当前默认是全部；请改为默认 30 天并补一个能区分二者的测试，改完跑全量"。这样它既知道确切目标，也知道你会用什么标准复核，很难再用模糊措辞搪塞。
打回后同样要重新走一遍验证，特别留意它为修 A 是否碰了 B——回归往往就在这种"小修"里发生。
十、按风险分配验收精力
很多人觉得验收慢，是因为对所有改动平均用力——既低效，也容易因疲惫而在真正要命处松懈。更聪明的做法是按风险动态分配。
先花一两分钟用需求清单和 diff 的文件/增删统计建立全局印象，判断这次改动的整体风险。然后把精力压向高风险区：涉及鉴权与权限、资金与支付、数据迁移与删除、对外接口与契约、并发与事务的部分，值得逐行精读、跑全量、回源核对；而命名调整、注释、纯样板代码等低风险改动，快速浏览加针对性测试即可。判断一处改动是否高风险，可以问三个问题：错了会造成多大后果、是否难以察觉、回滚是否困难。 三个都偏重，就应深查。
这样做不是放松要求，而是把有限的注意力用在收益最高的地方。对低风险任务熟练后快速放行、对高风险任务始终保持最后一道关，这套"风险分级"既能保住质量，又不会让验收成为不可承受的负担。
十一、把验收经验沉淀成规则
验收中反复发现的同类问题，不应每次都靠人重新识别——那是经验的浪费。当你发现 Agent 在某一点上屡屡出错（总忘记默认值、总爱动无关文件、总写空泛断言），就应把这条教训从"我这次多留心"升级为写进规则或检查清单的固定约束。
例如把"新增筛选参数必须有默认行为并配可区分的测试""不得修改未在需求中出现的公共接口"写进项目的 AGENTS.md 或验收清单，让 Agent 在产出前就遵守、让你在验收时有据可依。这正是本系列一直强调的闭环：验收不只是拦截缺陷，更是把高频缺陷的知识沉淀下来，让系统一次比一次更不容易犯同样的错。 久而久之，需要你临场警惕的点会越来越少，验收也越来越快。
十二、别让验收沦为走过场
流程立起来之后，新的风险是它被机械执行：清单一条条打勾、命令一个个跑过，却没人真正在看结果——这种"仪式化验收"比没有验收更危险，因为它给人一种"已经严格把关"的错觉。
避免走过场的关键，是让每一步都带着问题去做，而不是走完动作就算数。对需求是真的在找"哪条没做"，读 diff 是真的在问"这处改动为什么需要"，跑测试是真的确认"它在检验我关心的行为"。验收的价值来自主动的怀疑和判断，而不是清单本身。 另一个实用办法是定期轮换验收视角、或让 Agent 充当独立审查者先提一轮问题，帮助始终保持新鲜的批判目光，而不是在熟悉中逐渐麻木。
归根到底，工具和流程都只是放大器：认真的判断配上这套流程会高效地挡住缺陷；而如果判断缺席，再完备的清单也只是自欺。守住"每一步都要真看、真想"，验收才不会退化成又一个橡皮图章。
十三、危险信号速查
| 信号 | 更可能的问题 | 动作 |
|---|---|---|
| 总结里写"全部完成"，某条需求却无对应代码 | 遗漏 | 回需求清单逐条勾 |
| diff 动了一堆无关文件 | 范围蔓延 | 要求收敛或逐处确认必要性 |
| 测试绿但断言空泛/从不失败 | 假绿测 | 改坏实现看是否变红 |
| 关键论断在代码里查无实据 | 编造 | 抽样回原始材料核对 |
| 只跑小测试、没跑全量 | 集成风险 | 跑完整套件与构建 |
| 结果与你对项目的直觉冲突 | 隐藏偏差 | 顺"为什么"追到上游 |
七、常见问题
Q：每一项都要这么查吗，会不会太慢？ 不必平均用力。先靠需求清单和 diff 统计快速扫整体，再把深查集中在高风险模块和你不确定处；这套流程熟练后很快，却能挡住绝大多数事故。
Q：Agent 给的变更说明能不能当验收依据？ 只能当线索，不能当结论。说明是它的自我汇报，验收要以需求、diff 和你亲自跑的验证为准。
Q：小改动也要走全套吗？ 按风险伸缩。一两行低风险改动快速核对即可；涉及核心逻辑、数据、对外接口的，再小也应跑测试、看影响面。
Q：怎么平衡信任和效率？ 信任应来自稳定可验证的记录：当它在同类任务上反复通过这套验收，你可以对低风险任务放宽抽查，但对高风险项始终保留最后一关。
Q：验收时发现可改可不改的风格问题，要纠结吗？ 分清主次：先确保需求、正确性、安全和质量这些硬项过关；纯风格、个人偏好类的小问题，若不影响可读与维护，不必逐条纠缠，更不要让大量风格争论淹没真正的风险。可把团队统一的风格固化进 lint 自动处理，把验收注意力留给机器管不了的部分。
八、验收检查清单
- 已对照需求逐条勾选，确认无遗漏，每条都有证据。
- 已读 diff，确认无越界改动、删除合理、改动对症。
- 已跑相关与全量测试、构建和检查，且测试确实有效。
- 已抽样把关键论断回到原始代码/数据核实。
- 高风险模块（鉴权、支付、迁移、对外接口）已重点复查。
- 不依赖 Agent 的自我总结做最终判断。
总结
验收 Agent 的产出，顺序很关键：先拿需求清单逐条勾、专查遗漏，再读 diff 看有无越界和误删，然后用真正有效的测试与构建做客观验证，最后抽样回到原始材料核对事实，专门防住"看起来很完整"的自信编造；把深查集中在高风险处，让信任建立在可验证的记录上，你才能既享受 Agent 的快、又不被它的"像那么回事"骗过。