English Version →

本篇代码示例：code/ 实战练习：Project 05. 让 agent 自己检查自己做的对不对

第九讲. 防止 agent 提前宣告完成

这节课要解决什么问题

你让 agent 实现"密码重置"功能。它改了数据库 schema、写了 API 端点、加了邮件模板，跑了单元测试（全部通过），然后自信地告诉你"做完了"。但实际一跑——密码重置链接发不出去（邮件服务配置缺失）、数据库迁移半途失败（schema 不一致）、端到端流程根本没走过一遍。

这不是偶然事件。Guo 等人 2017 年在 ICML 上的经典论文证明：现代神经网络系统性地过度自信——模型自报的置信度显著高于实际准确率。AI 编码 agent 也一样：它"觉得"做完了，但实际上差得远。你的 harness 必须用外部化的、基于执行的验证来替代 agent 的"感觉"。

核心概念

• 过早完成声明：agent 断言任务完成，但实际上存在未满足的正确性规范。核心问题：agent 依据代码层面的局部信心做判断，系统级正确性需要全局验证。
• 置信度校准偏差：agent 自报的完成信心与实际完成质量之间的系统性差距。对复杂多文件任务，这个偏差显著为正——agent 总是比实际做得更自信。
• 终止标准：一组明确的、可执行的判定条件，定义在 harness 里。agent 必须满足所有条件才能声明完成。"完成"从主观判断变成了客观判定。
• 验证-确认双闸门：第一层验证检查"代码是否正确实现了指定行为"；第二层确认检查"系统级行为是否满足端到端需求"。两层都通过才算完成。
• 运行时反馈信号：来自程序执行的日志、进程状态、健康检查。这是 harness 判定完成质量的客观基础，不是可选的调试工具。
• 完成优先级约束：先验证功能正确性，再处理性能，最后管风格。核心功能没验证通过之前，不许做重构。

为什么会这样

Agent 完成判定的四步滑坡

过早完成声明几乎总是遵循同一个序列：

1. 局部代码看起来没问题：语法正确、逻辑似乎合理。静态检查层面没有明显错误。
2. 运行时行为没有充分观测：harness 没强制要求全面执行验证，agent 跳过了实际运行或只跑了部分测试。
3. 验证被跳过或不完整：跑了单元测试但跳过集成测试，或者跑了测试但没检查覆盖率。
4. 基于不充分证据断言完成："代码看起来没问题"被当作"功能已完成"的证据。

每一步都在丢失信息。从任务规范到代码实现到运行时行为，每次转换都可能引入偏差，而每次跳过的验证都加剧了信息不对称。

单元测试通过 ≠ 任务完成

这是最常见的陷阱。agent 写了代码，跑了单元测试，全部绿色，然后说"做完了"。但单元测试的设计哲学——隔离被测单元、模拟依赖——恰好使其无法检测跨组件问题：

• 接口不匹配：A 调 B 时传参格式正确，但 B 的实际行为与 A 的假设不符。各自单元测试都通过，放在一起就崩。
• 状态传播错误：数据库迁移改了表结构，但缓存层还持有旧结构的缓存。单元测试不测跨层状态。
• 环境依赖：代码在测试环境（mock 一切）行为正确，在真实环境因为配置差异而失败。

"顺便重构"是完成判定的毒药

Claude Code 有一个常见行为模式：在核心功能还没验证通过时就开始重构代码、优化性能、改进风格。Knuth 说的"过早优化是万恶之源"在 agent 场景中有了新含义——重构会改变已完成验证和未完成验证之间的边界，可能破坏之前隐式正确的代码路径。

自我评价的系统性偏差

Anthropic 在 2026 年的研究中发现了一个更深层的失败模式：当 agent 被要求评估自己的工作时，它系统性地过度正面评价——即使人类观察者认为质量明显不达标。 这个问题在主观任务（如设计审美）上尤其严重——"布局是否精致"是一个判断题，agent 可靠地偏向正面。即使在有可验证结果的任务上，agent 也会因为判断失误而影响表现。

解决方案不是让 agent "更客观"——同一个模型既生成又评估，内在地倾向对自己慷慨。解决方案是把"干活的人"和"检查的人"分开。 一个独立的评估 agent，经过专门调校为"挑剔"之后，比让生成 agent 自我评估有效得多。Anthropic 的实验数据：

架构	运行时长	成本	核心功能是否可用
单 agent 裸跑	20 分钟	$9	否（游戏实体无法响应输入）
三 agent（planner + generator + evaluator）	6 小时	$200	是（游戏可以正常游玩）

这是同一个模型（Opus 4.5），同一段提示词（"做一个 2D 复古游戏编辑器"）。区别只在 harness——从"裸奔"到"planner 扩展需求 → generator 逐功能实现 → evaluator 用 Playwright 实际点击测试"。

来源：Anthropic: Harness design for long-running application development

怎么做才对

1. 外部化终止判定

完成判定不应该由 agent 自己做。harness 独立执行终止校验，输入是运行时信号，不是 agent 的置信度。在 CLAUDE.md 里写：

## 完成定义
- 功能完成 = 端到端验证通过，不是"代码写完了"
- 必须运行的验证层级:
  1. 单元测试通过
  2. 集成测试通过
  3. 端到端流程验证通过
- 在第 1 层没通过时，不许进入第 2 层
- 在第 2 层没通过时，不许进入第 3 层

2. 构建三层终止校验

• 第一层：语法与静态分析。成本最低，信息量最小，但必须通过。
• 第二层：运行时行为验证。测试执行、应用启动检查、关键路径验证。这是核心完成证据。
• 第三层：系统级确认。端到端测试、集成验证、用户场景模拟。防止过早声明的最后一道防线。

3. 为 agent 设计错误消息

OpenAI 在 Codex 实践中提出了一个特别有效的模式：给 agent 写的错误消息要包含修复指导。不要用 "Test failed"，而用 "Test failed: POST /api/reset-password returned 500. Check that the email service config exists in environment variables. The template file should be at templates/reset-email.html." 这种具体的、可操作的反馈让 agent 能自我修正，而不需要人类介入。

4. 运行时信号的具体形式

有效的运行时信号包括：

• 应用是否成功启动并达到就绪状态？
• 关键功能路径在运行时是否执行成功？
• 数据库写入、文件操作等副作用是否正确？
• 临时资源是否被清理？

实际案例

任务：实现用户密码重置功能。涉及数据库操作、邮件发送和 API 端点修改。

过早声明路径：agent 修改数据库 schema、编写 API 端点、添加邮件模板、跑单元测试（通过）、声明完成。

实际缺陷：(1) 端到端流程未测试——重置链接的实际发送和验证未确认。(2) 数据库迁移在部分执行后失败，导致 schema 不一致。(3) 邮件服务配置在目标环境中缺失。

harness 介入：终止校验强制执行——(1) 启动完整应用验证重置端点可访问；(2) 执行完整重置流程；(3) 验证数据库状态一致性。所有缺陷在会话内被发现，节省了 5-10 倍的后续修复成本。

关键要点

• agent 系统性地过度自信——置信度校准偏差是客观存在的，不是主观印象。
• 完成判定必须外部化——harness 独立验证，不信任 agent 的"感觉"。
• 三层校验缺一不可——语法通过、行为通过、系统通过，层层递进。
• 错误消息要面向 agent 设计——包含具体修复步骤，让 agent 能自我修正。
• 核心功能验证通过之前不许重构——完成优先级约束是防止过早优化的关键。

延伸阅读

• On Calibration of Modern Neural Networks - Guo et al. — 证明现代深度网络系统性地过度自信
• Building Effective Agents - Anthropic — 运行时证据在完成判定中的关键作用
• Harness Engineering - OpenAI — 过早完成声明是 agent 的主要失败模式之一
• The Art of Software Testing - Myers — 测试方法层次和有效性的经典参考

练习

1. 终止校验函数设计：为一个涉及数据库迁移和 API 修改的任务设计完整的终止校验。列出需要的运行时信号和每个信号的通过/失败标准。在一个实际任务上运行，记录它发现了哪些隐藏问题。

2. 校准偏差测量：选 10 个不同类型的编码任务，记录 agent 的自报完成信心和实际完成质量。计算偏差值，分析它和任务复杂度的关系。

3. 多层防御实验：对同一组任务跑三种配置——(a) 仅静态分析，(b) 加单元测试，(c) 完整三层校验。比较过早完成声明的比例和未捕获缺陷的数量。