Harness Engineering：Agent 真正能交付，靠的不是更强模型，而是上下文、执行协议和验收闸门

真正决定 Agent 能不能进研发现场的，往往不是模型上限，而是 上下文供给、执行纪律 和 验收闸门 是否足够完整。
原文链接：AI 小老六

很多团队聊 Agent，习惯先盯着模型参数、推理能力和 benchmark 分数。但一旦把 Agent 放进真实工程环境，最先把项目拖垮的，往往不是模型不够聪明，而是它 不知道什么时候该停、什么时候该回滚、什么时候必须承认“我还没做完”。

一个模型偶尔能答对，不等于它能稳定交付；能写出一段像样代码，也不等于它能在复杂仓库里持续守住边界。Harness Engineering 要解决的，正是这层从“会做题”到“能交付”的巨大落差。

图：Agent 真正被驯化，靠的是外层工程约束而不是临场运气。

公开资料已经越来越清楚地指向同一个结论：很多团队吃到的第一波红利，并不来自模型换代，而是来自 Harness 补齐。SWE-bench 这类数据里，裸跑和成体系编排之间的巨大差距，本质上都在说明一件事：Agent 的能力，不只写在模型里，也写在模型外面的工程壳层里。

裸 Agent 为什么一到真实环境就失真

如果只让模型“自己决定怎么干”，常见问题基本逃不出下面四类：

失效点	现场表现	真正缺的东西
完成判定失真	代码刚写完就说“已经好了”，测试和验收没跟上	独立验收者、强制检查点
长任务跑偏	做着做着开始解决旁支问题，最后偏离原目标	阶段计划、Checkpoint、上下文回看
经验无法复用	每来一个新任务，都要重新拼 Prompt 和工具链	可复用 Skill、模板化流程
排障像开盲盒	出错后只能翻聊天记录猜过程	Trace、Hook、结构化产物

问题看上去五花八门，根子其实很朴素：模型天生会补全，它不天生会守纪律。 没有外部约束的时候，它会把“看起来合理”误当成“已经完成”，把“局部顺手”误当成“整体正确”。

说得再直一点，研发团队真正缺的不是一个更会答题的模型，而是一套能把 完成权从模型手里拿走 的执行体系。

Context Surface：先把真相铺在仓库里，再让 Agent 动手

Agent 犯错，很多时候不是因为不会推理，而是因为它压根没看到该看的东西。项目边界不知道，危险操作不知道，已有约束不知道，历史坑点也不知道。人类工程师拿着这种输入开工，照样会出事。

所以 Harness 的第一层，不是工作流，也不是多 Agent，而是 上下文表面必须先铺平。

一个能让 Agent 少走弯路的仓库，至少得把下面几件事写清楚：

这个仓库解决什么问题，哪些目标优先，哪些不是这次任务该碰的范围。
模块边界在哪里，哪些目录能改，哪些目录不能跨层调用。
验证入口是什么，跑哪些命令才能算完成最小自检。
危险区在哪里，比如数据库迁移、配置变更、外部 API、发布脚本。
深层资料放在哪，什么时候该继续下钻读取。

AGENTS.md 这类入口文件之所以重要，不是因为它神奇，而是因为它把“第一次读仓库最容易漏掉的事实”提前放到了门口。真正好用的写法通常都很克制：入口负责定边界，细节靠引用文档按需加载。

图：把边界、危险区和验证入口先铺到仓库门口。

一个有效的 Context Surface，至少要守住两个硬约束：

1. 隐式约定不能算上下文。 只有落到仓库里的事实，才配被 Agent 当成依据。
1. 入口不能无限膨胀。 入口负责框边界，细节靠按需读取，不然上下文窗口很快就会被噪音塞满。

Capability Stack：Rule、Tool、MCP、Skill 不是一回事

很多团队一开始搭 Harness，最容易把这几层搅在一起。结果往往是：规则写成工具，工具写成流程，流程又带着一堆隐式依赖，最后谁都不敢改。

一个更稳的分法如下：

层级	解决什么问题	典型形态	谁来维护
Rule	规定不能越过的边界	`AGENTS.md`、架构门禁、lint 规则	平台或团队约束
Tool	完成单一动作	读文件、搜代码、跑测试、写文件	Agent 直接调用
MCP	接入一组外部能力	飞书、代码平台、部署系统	协议层维护者
Skill	把动作和判断编成可复用经验	CI 排障、文档生成、发布流程	平台或业务团队

真正有价值的 Skill，不是把工具换个壳再包一遍，而是把“什么时候用、先做什么、失败后怎么办、怎么自检”这些经验固定下来。它本质上提供的是一套可复用的工作手法。

图：把边界、动作、外部能力和经验复用分层治理，系统才不会越长越乱。

Skill 一多，治理问题马上跟着来。比较实用的做法，是把 Skill 分成两类仓库：

标准库：跨团队复用，准入严格，要有 owner、依赖声明、自检命令和评估集。
业务库：贴近场景，迭代更快，允许试错，但要能被索引，长期没人用就归档。

另外两个字段非常关键，很多团队前期会忽略，后期一定会补：

exists_for：这个 Skill 是为了补哪一种模型短板而存在。
retire_when：什么条件下它应该退场。

少了这两个字段，Skill 库几乎一定会越堆越厚，最后变成经验债。

Execution Protocol：不要让 Agent 在现场发明流程

把任务丢给 Agent，只说一句“你去做吧”，跟把活交给一个完全没有工作手册的新同事差不多。它不一定做不出来，但过程会高度随机：简单任务可能被它拆成十几步，复杂任务又可能被它草草收尾。

成熟一点的 Harness，不会让 Agent 从零发明流程，而是先给出几类稳定模板：

模板	适用任务	强制顺序
Feature Loop	新功能开发	先明确验收，再实现，再补文档
Bugfix Loop	缺陷修复	先复现，再归因，再修复，再回归
Refactor Loop	不改行为的重构	先锁基线，再改结构，再核对行为
Investigation Loop	调研与探索	先列假设，再做实验，只允许产出结论

模板解决的是“先后顺序”，但执行时还有一个更麻烦的问题：决策、生成、验证经常会混成一团。 模型一边想方案，一边写代码，一边自己给自己判卷，最后往往哪一步都不可靠。

这也是 Planner-Generator-Evaluator 这类三段式架构反复被验证有效的原因。它的价值不在于“三个角色听起来更完整”，而在于它强行把三件最容易串味的事情拆开：

图：把计划、执行、检查和验收拆成独立阶段。

这里有一条纪律尤其重要：角色之间只交换结构化产物，不交换“思考过程”。

Planner 给计划，Generator 交代码和工件，Evaluator 只看计划、产物和检查结果。否则验证环节很容易被执行环节“说服”，最后又退回成模型自评。

长任务还要再补一层 Checkpoint。不是为了形式感，而是因为目标漂移在长上下文里几乎必然发生。一个能落地的 Checkpoint，至少要保存四样东西：

原始目标。
当前计划。
已完成产物。
剩余待办。

有了这个断点，任务中断能续跑，连续失败也能回退，而不是在错误状态上反复补丁。

Validation Gate：完成不是一句话，而是一组证据

很多团队已经愿意给 Agent 配 lint、测试和一些静态规则，但还是会踩一个坑：这些检查只能说明“结果看着还行”，却不能证明“过程没有跳步”。

所以真正可靠的系统，最后都会走向两层校验。

第一层是 Checker 金字塔，谁便宜谁先跑：

检查层	核心目标	触发时机
即时检查	语法、格式、类型、结构完整性	每次编辑后
模块测试	局部行为正确	子任务完成后
集成测试	组件协作正常	全流程收束前
人工审查	架构和业务判断是否站得住	自动化通过后

第二层是 强制验收闸门。这里真正关键的不是“再多一道检查”，而是系统不再相信模型的口头汇报。

一个像样的 StopHook，通常会做三件事：

查状态锁：每个阶段的准出产物都要留下 lock 或指纹。
查反向证据：测试报告、覆盖率、产物时间戳必须能对得上。
查计划对账：按计划反向遍历，每一步声明过的工件都得存在。

拿一个新增 RPC 的任务举例，这套机制会长得非常实在：

{
  "task": "新增 CreateOrder RPC",
  "steps": [
    {"id": 1, "artifact": "proto/order/order.proto"},
    {"id": 2, "artifact": "gen/order/order.pb.go"},
    {"id": 3, "artifact": "service/order/create_handler.go"},
    {"id": 4, "artifact": "service/order/create_handler_test.go"}
  ]
}

执行阶段不是一句“我做完了”就结束，而是要留下这样的验收痕迹：

.stage/step1.lock  -> 对应 proto 文件 SHA256
.stage/step2.lock  -> 对应生成代码 SHA256
.stage/step3.lock  -> 对应 handler 文件 SHA256
.stage/step4.lock  -> 对应测试文件 SHA256

coverage.out       -> 时间戳晚于代码提交
integration.log    -> 契约测试通过

最后由独立的 Evaluator 来判定：

计划里的工件是不是都在。
每一步是不是按顺序完成。
证据是不是新鲜的。
更高层测试是不是也过了。

到这一步，“完成”才从一句自然语言，变成一组 可以回放、可以审计、也可以打回重做的工程事实。

图：完成不是一句口头汇报，而是一串可核对的证据。

Ratchet Loop：规则要越用越准，但别把自己焊死

Harness 最容易走向两个极端：

什么都没有，模型随便跑，团队天天救火。
每出一次事故就加一条规则，最后系统像裹了十层胶带，谁也不敢拆。

比较健康的状态介于中间：每次失败都要沉淀，但每条沉淀都得知道自己为什么存在，也得知道什么时候可以删。

这就是所谓的棘轮效应。一次失败，最好至少沉成下面三类东西里的一个：

新的 lint 或架构规则。
新的 Skill 检查。
新的 Hook 或验收条件。

但与此同时，每条规则都应该带着退场条件活着。模型升级后，如果某类错误已经很少自然发生，还继续把旧约束钉死在流程里，Harness 很快会从保护壳变成阻力层。

我更认同一种朴素的治理方式：规则不是越多越好，规则只要比事故多一步就够。 剩下的，交给定期复盘和主动删减。

团队该从哪几步开始补齐 Harness

如果一个团队现在还处在“Agent 能用，但不太敢交付”的阶段，没必要一上来就铺满整套平台。更实际的起步顺序通常是下面这样：

阶段	先做什么	为什么先做它
第一步	写清 `AGENTS.md`、补验证入口、标注危险区	投入小，立刻降低误改和幻觉
第二步	跑起最便宜的 Checker，比如 lint、typecheck、局部测试	把低级错误挡在最前面
第三步	沉淀 3 到 5 个高频 Skill，建立最小注册表	把经验从 Prompt 里搬出来
第四步	给高频任务加模板和 P-G-E 拆分	让过程稳定，而不是靠临场发挥
第五步	上 StopHook、证据检查和规则回流机制	真正收回“完成判定权”

这条路看上去不花哨，但很实用。大多数团队不是死在“没有终极架构”，而是死在 还没把最基础的交付纪律立起来，就急着追求全自动。

图：先补上下文和检查，再补模板与验收闸门，团队更容易落地。

写在最后

Harness Engineering 说到底不是造一套漂亮名词，也不是给 Agent 外面再包一层复杂平台。它干的其实是两件很硬的事：

把上下文、能力、流程和验收，从“默认靠模型自己理解”改成“系统显式提供”。
把错误从一次性事故，变成可沉淀、可复用、可删改的工程资产。

模型决定系统能冲多高，Harness 决定系统会不会半路摔下来。对大多数研发团队来说，后者往往更急。

模型升级只能提高上限，Harness 才决定交付底线。

AI小老六