什么是 harness engineering：让 AI 智能体成为可靠的工作工具

通俗地说什么是 harness engineering

Harness engineering 是一门工程学科，研究如何在语言模型周围搭建一个环境，让它能够稳定地完成真实工作。Harness 一词原意是“马具、挽具”：模型能力很强，但它本身不知道该往哪里走、该用什么工具、什么时候停下来。Harness 的作用就是引导这股力量。

最简短的表述是：

智能体 = 模型 + Harness

模型是权重，以及推理和生成文字或代码的能力。Harness 则是其余的一切：系统指令和 CLAUDE.md、AGENTS.md 之类的文件，工具集（shell、文件编辑、MCP 服务器），智能体运行命令时所在的沙箱，跨会话保存的状态文件，以及在出错时提醒智能体的测试、代码检查和钩子。如果拿走 Harness，剩下的只是一个只会用文字回答的聊天窗口。

为什么同一个智能体一会儿像资深工程师，一会儿像新手

这种情况很常见：同一个智能体，在一个代码仓库里像经验丰富的开发者，在另一个仓库里却东拼西凑，忘记昨天的决定，还会报告一个根本跑不通的功能“已完成”。第一反应往往是换一个更新的模型，但这通常无济于事，因为两次用的是同一个模型。差别在于环境。

这正是 harness engineering 的核心思路：智能体没有坏，坏的是它周围的东西。如果智能体无法运行测试，它就没法测试；如果没有地方记录，它不会记得自己已经试过什么；如果没有任何检查告诉它功能坏了，它就不知道功能坏了。这些是结构性缺陷，而不是模型的“性格”，可以系统地修复。

糟糕 Harness 的典型症状

• 每个新会话都要先修环境：依赖不对，数据库起不来，变量缺失。
• 智能体反复尝试已经被否决的方案，因为它不记得上一次会话。
• 规则明明写在指令文件里，智能体却照样忽略。
• “测试全部通过”，但功能其实是坏的，因为测试检查的是错误的东西。
• 智能体同时接手三个任务，却没有一个做完。

Harness 由什么组成：五个子系统

常见的误解是把 Harness 当成一个写着提示词的文件。实际上它由五种机制组成，每一种失效的方式都不同。

指令

指令解决的问题是：智能体能否找到需要的规则。好的入口文件是地图而不是教科书：一份简短的目录，列出验证命令和硬性约束，细节放在智能体需要时才打开的独立文档中。好的指令规定不变量（“所有 SQL 查询都必须参数化”），而不是逐行规定实现方式。

工具

智能体只能验证它有权限访问的东西。如果它无法运行代码检查器，那么“提交前运行检查器”这条规则毫无作用。工具既可以通过智能体的内置能力提供（读写文件、执行命令），也可以通过 MCP 提供——这是一种协议，让智能体能够访问数据库、浏览器和任务跟踪器。

环境

环境是智能体执行命令的地方。它应该能用一条命令启动，每次会话都保持一致，并且能限制错误造成的损失：不能访问生产环境的沙箱、独立的分支或工作副本，以及在一分钟内把一切恢复到初始状态的能力。

状态

模型在会话之间没有记忆：凡是没有写进仓库的东西，都会随着上下文窗口一起消失。因此目标、已完成的工作、做出的决定、走不通的路以及下一步，都必须存放在文件里。检验方法很简单：打开一个新会话，只对智能体说“继续”，看它能不能直接开始工作，还是会反问该做什么。

反馈

反馈回路是最重要的子系统。没有它，智能体就是自己唯一的裁判，并且会诚实地认为任务已经完成。测试、类型检查、代码检查器、每次修改后运行的钩子、浏览器中的端到端场景——这些都会在错误还便宜的时候，给智能体一个红色信号。

Harness 是一个回路，而不是一份清单

五个子系统构成一个闭环。模型读取指令，通过工具在环境中行动，修改仓库，验证环节检查结果。红色结果返回给模型去修复，绿色结果则记录到状态中。状态再为下一次会话更新指令。

指令 → 模型 → 工具 → 环境 → 修改
          ↑                    ↓
          └── 红色 ── 验证 ────┘
                         ↓ 绿色
                     状态 → （下一次会话）

去掉任何一个箭头，回路就会在那里断开。没有验证，智能体发现不了错误；没有状态，下一次会话就只能从头考古，而不是继续工作。因此，在某一个子系统上投入再多，也弥补不了另一个子系统的缺口：五页长的 AGENTS.md 无法替代缺失的测试。

Harness engineering 与提示词工程、上下文工程的区别

这三个概念是逐层嵌套的，而不是相互竞争的。

提示词工程是指令子系统的一部分。上下文工程涵盖指令和状态，决定智能体在每一刻能看到什么。Harness engineering 增加的是那些根本放不进上下文窗口的东西：访问权限、沙箱、测试、钩子、工作流程。再好的提示词也帮不了一个物理上无法运行测试的智能体。

为什么需要 Harness：长任务的数学

直觉上，一个每步都有 95% 正确率的模型，几乎是完美的。但智能体的任务由很多步骤组成，错误会不断累积。如果各步相互独立，那么一路零错误通过的概率就是各步概率的乘积：

0.95 ^ 10 ≈ 0.60
0.95 ^ 20 ≈ 0.36
0.95 ^ 50 ≈ 0.08

完成十步而无任何错误的运行大约只占 60%，五十步时则不到十分之一。把模型的正确率提高到 97% 成本很高，而且不在你的掌控之中。但在错误发生的那一步就把它捕获，并把它交还给智能体修复，这正是 Harness 的任务。反馈回路把“一个错误拖着下一个错误”的链条，变成了一串短小、可以及时修正的步骤。

示例：同一个智能体，两个仓库

任务：在一个基于 FastAPI 的支付后端中，加入优惠码折扣。

没有 Harness

智能体读了几个文件，写出了折扣计算函数和一个单独测试这个函数的单元测试。测试通过，智能体回复“已完成”。它不知道订单总额的计算位于另一个模块，也无法启动数据库、跑完整的下单流程。一天之后人们发现：购物车里根本没有应用折扣。

有 Harness

仓库根目录有一份几十行的 AGENTS.md：说明如何启动环境、哪些检查命令必须运行、支付架构写在哪里。用 docker compose up -d 就能启动环境。仓库里有一份计划文件，其中的完成标准是：“带优惠码的下单端到端场景通过”。每次修改后，钩子都会运行代码检查器和类型检查，智能体在声称完成之前必须运行一次端到端测试。

# AGENTS.md（节选）
## 验证——声称“完成”之前必须执行
make lint        # ruff + mypy
make test        # pytest，单元测试和集成测试
make e2e         # 下单场景

## MUST
- 金额以分计算（int），绝不使用 float
- 所有 SQL 查询都必须参数化
- 不要修改已在生产环境应用的迁移

模型还是同一个。但现在，智能体通过项目地图找到了计算总额的模块，端到端测试第一次运行就失败，智能体看出折扣没有传到购物车，修复之后，才在端到端测试通过后汇报。结果上的差别，完全来自 Harness。

从哪里开始

1. 说明智能体如何验证自己的工作：写下它必须运行的一到三条命令。反馈带来的效果最大，所以应该从它开始。
2. 让环境可以复现：用一条命令启动，并且能够快速回滚。
3. 建立状态文件：目标、已完成的工作、决定与死胡同、下一步。
4. 把指令精简成地图：验证命令、硬性约束，以及指向详细文档的链接。
5. 记录智能体的失败日志：每次失败都写下是哪个子系统让它出了问题。日志会告诉你接下来该修什么。

一个实用的做法是：给五个子系统各打 1 到 5 分，花半小时修复最弱的一项，然后在同一组典型任务上，分别在修复前后运行一遍。这样 Harness 的改进就是可以衡量的，而不是凭感觉。

总结

Harness engineering 关注的不是模型本身，而是它周围的一切：指令、工具、环境、状态和反馈回路。智能体的可靠性取决于这个闭环中最薄弱的一环，所以换一个模型很少能解决不稳定的问题，而增加一个测试或一份计划文件则常常有效。五个子系统以及整个 Harness 的搭建，都在 Harness 工程课程中结合实践做了详细讲解。