同一个模型在一个项目里能连续跑两小时自己改 bug、自己验证、自己收尾在另一个项目里连环境都装不起来第三轮开始胡编 API最后留下一堆你不敢合并的 diff。我们习惯把这种差异归因于模型还不够聪明。但只要你多试几个仓库就会发现真正拉开差距的往往是第二个变量这个项目有没有为 AI 准备好一套可理解、可动手、可验证、可恢复的工程环境。这套环境在英文里被叫作 harness——马具、挽具、测试夹具。名字很准。马的力量从来不是新问题问题是怎么把那股力气接到犁上而不是让它野跑。一、先把三个被混用的词分开Prompt Engineering管一次提问怎么写。Context Engineering管这一轮该把哪些信息塞进上下文窗口——检索、压缩、排序、丢弃。Harness Engineering管的范围更大代理在这个仓库里能不能安全地完成一个完整的工程闭环。理解上下文 → 做有界改动 → 选对验证方式 → 解读失败 → 修复 → 重跑验证 → 判断残余风险是否需要人工复核注意这条链它不是生成代码而是带着反馈回路的生成。harness 的本职不是让模型更聪明而是让它每一次猜测都能廉价地撞在现实上撞错了能自己掉头。链条上任何一环断掉代理就会在那一环开始猜——而猜出来的东西看起来和真做出来的完全一样这才是最贵的地方。上图就是这个闭环的骨架看清现状 → 动手改 → 验证 → 失败诊断 → 修复重跑 → 该人审的交给人。harness 的全部工程本质上就是在保证这六个箭头没有一个靠希望连接。顺带把几个相邻概念钉牢写文章时不再互相冒充概念是什么类比Model推理内核马的体力Scaffold代理运行时的骨架循环、状态、提示组装马鞍与缰绳本体Harness项目 工具为代理准备的可操作环境整套挽具与犁Tool / MCP代理能调用的外部能力手里的家伙Skill打包好的做法与流程知识驯马的手艺AGENTS.md项目对代理说的话场地说明书日常讨论里 harness 和 scaffold 常常混用但差别很实在scaffold 是产品方给的harness 是你在自己仓库里挣来的。你换不了模型也多半换不了 agent 产品但 harness 完全在你的控制范围内——这也是它值得单独写一篇文章的原因。二、Harness 的六根承重柱判断一个项目的 harness 强弱不用凭感觉。看这六件事能不能连成一条链。1. 上下文地图导航图不是百科全书代理需要知道从哪个文件进、哪些目录能碰、哪些是生成物不能手改、常见改动该跑哪条命令。AGENTS.md是最常见的入口但它只是入口。根目录塞一份三千行的什么都写一点的说明书效果通常比一份两百行的地图更差——上下文是稀缺资源冗余本身就是噪声。真正的好信号是里面写的路径、命令、版本号和仓库当前状态一致。过期的正确文档比没有文档更危险因为代理会相信它。2. 统一的命令入口npm run check一把梭还是有人知道其实是三个脚本按顺序跑Makefile、package scripts、justfile、Taskfile、Gradle task——形式不重要重要的是存在一个不需要问人就能发现的入口并且脚本名会自己解释意图check、test:unit、test:e2e、typecheck、verify-generated。反过来任何需要你先手动开一下那个服务这个要先在群里问老王的隐式步骤都是 harness 上的洞。同样关键的还有能按范围跑测试。只能全量跑的仓库代理每验证一次都要付十分钟的代价很快它就会开始觉得应该没问题。3. 快反馈便宜的手段要能先撞一条经验慢的端到端测试本身不是问题它是唯一反馈才是问题。理想的层次从便宜到昂贵格式与 lint → 类型检查 → 单元测试 → 契约/架构测试 → 集成 → 端到端。代理改完一个函数三秒内要知道红绿改完一个模块一分钟内要知道有没有破坏不变量。全栈 Docker 起一次十分钟的项目代理一定会偷工减料——这不是模型品德问题是激励结构问题。4. 机械约束写在文档里的规矩等于没有规矩“我们的 domain 层不许 import infra 层”——这句话在 README 里出现一百次也不如一条真正会红的架构测试。能机械验证的东西很多类型系统、自定义 lint、依赖方向检查、生成物一致性golden file、schema diff、API 兼容性、迁移检查、密钥扫描。判据不是有没有一个叫 linter 的工具而是这条规则违反之后会不会自动变红。这也是 harness 最反直觉的一点给代理加约束反而扩大了它的能力半径。规则可验证时它敢改规则只靠人评审时它每改一步都在赌。5. 失败可诊断红要红得能定位失败信息只有一句timeout、一坨噪声日志、或者外部服务返回 500代理就会开始瞎试。好的 harness 让失败自带路径断言有期望/实际差异lint 报出被违反的规则名和修复方向端到端失败留下截图、trace、DOM 快照。还有一层常被忽略代理自己的执行轨迹要可审计。跑了哪些命令、调了哪些工具、改了哪些文件、最终证据是什么。没有这层事后复盘只能靠回忆。6. 安全与副作用把危险路径默认关掉代理能连生产数据库、能删队列、能发真实邮件、能推真实云资源——这不是能力这是事故候补。成熟做法是让危险动作默认不可达而不是在文档里写请不要在生产环境执行迁移和部署走 dry-run删除类操作要审批密钥与凭据不进上下文沙箱与最小权限是默认档外部写操作留审计记录。三、成熟度从有个文件到机器帮你把关给 harness 打分需要一个不掺水的标尺。一个够用的五级划分级别含义判据F0缺失只有人脑里的记忆F1存在有文件、有命令、有规则但质量和新鲜度存疑F2可用普通代理能在有限努力内发现并用起来F3可复现有文档、本地可跑、跨任务稳定重复F4被强制机械验证、自动化或纳入治理流程F4 只留给机械证明文档写得再漂亮也不算。这条纪律很重要否则评估会退化成谁 PPT 好谁分高。四、四个最常见的误判误判一文档多 harness 强。文档只是上下文入口。要问的是它有没有接到可执行的反馈上。一个只有 README 但make check三秒出结果的项目胜过十个知识沉淀文档齐全、跑起来全靠猜的项目。误判二有 CI 文件 有门禁。.github/workflows里有 yaml不代表这些检查是 required也不代表分支保护开着。静态看仓库得出的这类结论诚实的写法是标UNVERIFIED。误判三这次跑通了 可复现。一次成功可能靠某个本地遗留状态、某条没写下来的环境变量。可复现的意思是从干净状态出发按项目自有的非交互路径第二个人或第二个代理还能走到同一个绿灯。误判四大项目要整体打分。大型仓库常常是分裂的——代码级反馈很强类型、单测、架构测试都齐运行时和集成支持很弱起不了服务、没有 seed 和 reset。分开判才不会得出这项目挺好的呀和这项目根本没法用两种都对的说法。五、四周能落地的顺序不要试图一次做完美。按投入产出比这个顺序几乎不会错。第 1 周一个入口。建check格式 lint 类型 单测保证本地一条命令能跑完并写进AGENTS.md。这一周结束时代理少掉的是不知道该跑什么这类失败——通常也是占比最高的一类。第 2 周把AGENTS.md改成地图。两百行以内只留三类内容目录边界与禁改区、命令入口、常见改动对应哪条验证路径。删掉一切背景介绍和过期命令。顺手把生成物、迁移、fixture 标清楚。第 3 周把最常被违反的两条规矩变成会红的东西。挑两条真实发生过返工的规则做成架构测试或自定义 lint。别一次做十条——十条里九条会因为太吵被// disable掉。第 4 周补失败可见性。让端到端失败留下截图与 trace让测试断言打印期望/实际差异给环境加一个doctor或健康检查。然后回头补一层可复现的 reset。再往后是第五周以后的事把 CI 与本地命令对齐、给危险操作加审批门、把密钥扫描和依赖扫描接上。六、为什么这件事值得长期投入模型每半年换一代scaffold 随产品版本变你的 prompt 技巧会贬值——但 harness 是复利资产。它由命令入口、可分范围跑的测试、机械约束、可诊断的失败和默认安全的边界构成这些东西对上一个模型有用对下一个同样有用对代理有用对新来的同事一样有用。一个粗糙但真实的变化是harness 到位之后你给代理的指令会从帮我改 X注意别动 Y记得跑 Z缩短成把 X 修一下。因为那些约束不再需要你每次口头重复——它们已经长在仓库里了。马从来不是问题。问题是我们花了太多力气养马太少力气造犁。本文的 Harness 分级与判据参考了 Better Harness 方法论中关于 Harness Engineering 与 Agent Work Loop 的评估框架F0–F4 成熟度、六项证据维度、闭环定义结合自己在多个仓库里踩过的坑整理而成。