Table of contents
Open Table of contents
1. 为什么验证是 Harness 的关键
如何设计测试体系，是让 Agent 产出稳定可靠项目的关键依靠。
静态的代码语法、逻辑检查不足以发现问题。Agent 生成的代码可能没有明显错误，但端到端运行时仍会出错。缺少合格的测试会出现更多隐性错误，偏差累积，离「可靠」越来越远。
2. 问题根源
在设计测试文件之前，先搞清两类典型问题：
2.1 过度自信
Agent 对自己的设计往往十分自信，设计质量与项目实际质量难以对齐，且偏差多为正向。Agent 完成单元测试后就可能自行判定成功。
在主观任务（如设计审美）上尤其严重——「布局是否精致」是判断题，Agent 可靠地偏向正面。即使在有可验证结果的任务上，Agent 也可能因判断失误影响表现。
2.2 过早/无依据的重构
Agent 在单元测试通过（但项目质量尚不足以端到端跑通）时，仍可能对已实现功能做重构优化，从局部缺点出发逐步偏离正确方向。
2.3 缺少可靠的测试环境
测试难以发现隐性问题，许多本可避免的问题要到实际运行才暴露。若在该问题之上继续实现新功能，后续修正代价更大。
一个功能的测试应遵循准则：小而可靠。
3. Verification 设计：三层校验
对「过度自信」的解法是：把「干活的人」和「检查的人」分开。
3.1 三层测试校验
| 层级 | 内容 | 作用 |
|---|---|---|
| （1）静态层 | 语法检查、静态分析 | 保证基础正确，才有资格进入后续测试 |
| （2）运行层 | 测试执行、应用启动检查、关键路径验证 | 核心完成证据——不仅要写了，还要能跑 |
| （3）系统层 | 端到端测试、集成验证、用户场景模拟 | 防止过早声明的最后一道防线——不仅要能跑，还要跑对 |
上述内容可写入 AGENTS.md，模板参考：
## 完成定义
- 功能完成 = 端到端验证通过，不是"代码写完了"
- 必须运行的验证层级:
1. 单元测试通过
2. 集成测试通过
3. 端到端流程验证通过
- 在第 1 层没通过时，不许进入第 2 层
- 在第 2 层没通过时，不许进入第 3 层3.2 重构问题的约束
完成优先级约束： 先验证功能正确性，再处理性能，最后管风格。核心功能没验证通过之前，不许做重构。
3.3 问题可读性
设置 log 文件，让 Agent 在布置好测试环境后能发现问题，从 log 中看到运行健康状态——这是系统稳定性的保证。
4. OpenAI Codex 实践：可操作的错误消息
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 能自我修正，而不需要人类介入。
参考：OpenAI — Harness engineering: leveraging Codex in an agent-first world
5. 小结
Verification 子系统是 Harness 中投入少、回报高的一环。把完成定义写进仓库、分层校验、约束重构顺序，并用可操作的错误消息闭环——Agent 才能从「写完代码」走向「行为被证明正确」。