《AI 渐进编程》之二十一：Agent 不光要交代码，还要交证据包

使用 AI 编程时，最容易被看到的是生成能力。

代码写出来了，页面生成了，接口补上了，看起来任务已经完成。

但在真实项目里，生成只是第一步。

这就像吊车搬运重物。货物被吊到目标区域，并不等于已经放准，还需要确认位置、偏差和后续影响。

AI 编程也是一样。

Agent 写完代码，不等于完成交付。

它还需要说明：改了什么，为什么这样改，影响了哪里，如何验证，还有哪些风险需要人判断。

这就是证据包。

AI 生成速度远超过人工审查速度。如果每次都让人检查全部代码，流程很快就会堵住。

证据包的作用，是把修改范围、验证结果和剩余风险提前整理出来，让人集中判断关键风险。

所以，AI 编程不应该只是生成式交付，而应该是验证式交付。

1. AI 的审查能力也要用起来

过去，代码审查主要依赖人。

人要读 diff、理解调用关系、判断影响范围、确认测试是否充分，还要识别隐藏风险。

这件事很难，也很耗时间。

AI 出现以后，不能只利用它的生成能力，也要利用它的审查能力。

Agent 在提交结果之前，应该先做一轮机器审查：

• 是否越过修改边界；
• 是否破坏调用关系；
• 是否只修复了表面问题；
• 是否缺少关键路径测试；
• 是否留下旧代码和过期注释；
• 是否有需要人工判断的风险。

这些检查不能完全替代人，但它可以把大量原本需要人从头梳理的信息提前整理出来。

2. 传统工程审代码，Agent 工程审证据

传统软件工程里，一轮开发大致是：

需求 → 设计 → 手写代码 → 人工审查 → 测试

代码是主要交付物。

审查者拿到代码 diff，再自己判断改动是否合理。

Agent 工程不应该只是把“手写代码”换成“AI 写代码”。

更合理的流程是：

意图与约束 → 项目状态检索 → 生成 / 执行 / 反馈循环 → 机器验证 → 证据包 → 人类风险审批

这里的关键变化是：

Agent 不能只交结果，还要交代结果是怎样来的。

它不仅要说“我改完了”，还要说明基于什么上下文修改、影响范围在哪里、已经验证了什么，还有哪些风险没有覆盖。

3. 证据包应该包括什么

证据包不是一堆日志。

它是一份让人能够快速判断风险的工程说明。

一份基本的证据包，可以包括：

任务目标 + 修改文件 + 关键改动 + 影响范围 + 验证结果 + 未覆盖风险 + 需要人工判断的问题

例如：

任务目标： 修复空购物车结算异常。 修改文件： - checkout/service.py - tests/test_checkout.py 关键改动： - 在结算前增加 empty cart 检查； - 阻止空购物车进入支付流程； - 增加空购物车测试。 影响范围： - checkout service； - order creation； - payment request path。 验证结果： - 空购物车测试通过； - 正常购物车测试通过； - 未发送 payment request。 未覆盖风险： - 未验证优惠券叠加场景； - 未验证多币种结算路径。 需要人工判断： - 空购物车错误提示文案是否符合产品要求。

这样的提交，比一句“已修复”有用得多。

4. 人类审批的是风险

Agent 可以生成代码，也可以整理证据。

但最后是否接受修改，仍然需要人类判断。

因为有些问题不是测试能完全决定的：

• 业务是否合理；
• 用户体验是否接受；
• 风险是否可承受；
• 是否符合长期架构方向；
• 是否应该现在解决，还是写入open_issues.md。

所以，人类审查的重点不只是逐行看代码，而是判断证据是否充分、风险是否说清、当前结果是否可以进入项目状态。

人不是重新替 Agent 做一遍，而是做最后的风险审批。

5. 证据包让交付可追踪

如果 Agent 每次只返回“已完成”，项目很快会变得不可追踪。

人不知道它基于什么理解修改，验证了哪些路径，有没有越界，留下了哪些风险。

所以，在长期项目里，证据包应该成为每一轮交付的一部分。

可以在current_task.md中提前要求：

本轮完成时，必须提交证据包，包括： 1. 修改文件清单； 2. 关键改动摘要； 3. 影响范围分析； 4. 已执行的验证； 5. 未覆盖风险； 6. 是否清理旧代码； 7. 需要人工审批的问题。

这不是形式主义。

它是在让 Agent 的工作变得可审查、可追踪、可回滚。

本章小结

Agent 工程的交付物，不应该只有代码，还应该有证据包。

代码说明“改了什么”，证据包说明“为什么这样改、验证了什么、还有什么风险”。

人类不必从零审查，而是基于证据包做风险判断。