问题从哪里开始
很多人第一次做 Agent，注意力会自然放在模型和 prompt 上：换一个更强的模型，写一段更长的系统提示词，再接几个工具，好像就能得到一个稳定工作的智能体。
但真正跑过一段时间后，问题会变得很具体：
- Agent 不知道项目里的约定，改出了风格不一致的代码。
- Agent 调用了危险命令，差点删掉不该删的文件。
- Agent 在长任务里越做越偏，最后给出一个“看起来完成了”的错误结果。
- Agent 读取网页、邮件或文档时，把外部内容里的指令也当成了该执行的命令。
这些问题很容易被归因成“模型不够聪明”。但在工程上，更有价值的问法是：模型外面的运行环境是不是设计得太松了？
这就是 Agent Harness Engineering 想解决的问题。Agent 不是单独一个大模型，而是：
1
Agent = Model + Harness
模型负责推理和生成，Harness 负责把模型放进一个可执行、可约束、可观察、可恢复的工程环境里。换句话说，Harness Engine 是 Agent 的运行支架和控制系统。
Harness 到底负责什么
可以把 Harness 理解成所有“不属于模型权重本身”的部分。它不只是 prompt，也不只是工具调用框架，而是一组围绕模型工作的工程能力。
上下文
模型每次能看到什么，先看到什么，哪些内容必须进入上下文，哪些内容应该被压缩、裁剪或延迟加载，这些都不是模型自己决定的。
在代码 Agent 里，常见的上下文包括：
- 系统提示词。
AGENTS.md、项目规范、代码风格说明。- 当前任务描述和历史对话。
- 文件内容、命令输出、测试失败日志。
- 工具说明、权限说明和外部资料。
上下文不是越多越好。塞得太多，模型会丢重点；给得太少，模型会瞎猜。Harness 的第一件事，就是把上下文变成一种工程资产，而不是临时复制粘贴。
工具
Agent 能否读文件、改文件、运行命令、打开浏览器、查文档、调用 API，本质上都由 Harness 提供。
工具设计会直接影响 Agent 的行为。一个含糊的工具名、过宽的参数 schema、互相重叠的工具集合，都会增加模型选错工具的概率。工具越多，不一定越强；很多时候，十个边界清楚的工具，比五十个互相重叠的工具更可靠。
更重要的是，工具描述本身也会进入模型上下文。也就是说，工具 schema 不只是开发体验问题，也是安全边界问题。一个外部 MCP server、浏览器插件或第三方工具，如果把不可信说明注入给模型，就可能在用户输入任务之前影响 Agent 的决策。
权限和沙箱
只要 Agent 能运行命令、访问文件或调用外部系统，就必须有权限边界。
好的 Harness 不会默认把所有能力一次性交给 Agent，而是根据任务分配最小权限。例如：
- 读文档任务只给读取权限，不给写文件权限。
- 总结邮件任务只给读取邮箱权限，不给发送邮件权限。
- 本地代码验证可以在沙箱里跑，不直接污染用户机器。
- 高风险命令需要人工确认或被 hook 拦截。
沙箱的意义不是让 Agent 更“聪明”，而是让 Agent 出错时伤害可控。工程系统不能假设模型永远不犯错，只能设计成犯错时不会造成不可恢复的后果。
Hooks 和反馈循环
prompt 里写“请不要犯错”并不可靠。Harness 需要把一部分规则变成可执行的约束。
比如：
- 修改代码后自动跑 typecheck。
- 测试失败时把错误日志反馈回 Agent。
- 提交前检查是否有被跳过的测试。
- 阻止
rm -rf、强推、删除生产表这类危险动作。 - 当 Agent 试图提前结束任务时，重新检查验收条件。
这类机制的关键是：成功时尽量安静，失败时给出足够清晰的信号。这样 Agent 不会被无用信息淹没，但一旦偏离目标，就能收到可操作的反馈。
每一次失败都应该沉淀成规则
Harness Engineering 最重要的心态，是把 Agent 的失败当作长期信号，而不是一次性事故。
如果 Agent 忘了项目使用 pnpm，而去运行 npm，那可以把包管理器约定写进 AGENTS.md。如果 Agent 经常在没有跑测试的情况下说完成了，那就把测试命令接进完成前检查。 如果 Agent 总是改动无关文件，那就要求它在编辑前先查看 git 状态，并在最终说明中列出 touched files。
但这并不意味着把所有想得到的规则都塞进去。规则也有成本。每一行规范都会占上下文，每一个 hook 都会增加运行时间，每一个权限弹窗都会打断流程。
更稳的做法是：
- 先让 Agent 真实工作。
- 记录它具体失败在哪里。
- 把高频或高风险失败沉淀成规则。
- 当模型能力或工作流变化后，再删除不再有价值的规则。
好的 Harness 不是越厚越好，而是每一层都能解释自己在防什么问题。
Harness 与 Loop Engineering 的关系
Loop Engineering 关注的是 Agent 怎么持续做事：观察、思考、行动、再观察，直到任务完成。
Harness Engineering 的范围更大。它不仅包含循环本身，还包含循环运行所需的环境：
- Agent 在循环里能看到哪些上下文。
- 每一步能调用哪些工具。
- 失败信号如何回流。
- 长任务如何压缩上下文或重启会话。
- 多个子 Agent 如何分工。
- 人类在什么节点介入确认。
如果说 loop 是 Agent 的工作节奏，Harness 就是让这个节奏能长期稳定运行的工程系统。
这也是为什么同一个模型，放在不同产品里表现差异会很大。底层模型可能相同，但工具、上下文、权限、沙箱、计划机制、恢复策略都不同，最后得到的 Agent 体验当然不同。
工程上怎么开始做
如果要在自己的项目里建设一个 Agent Harness，不需要一上来做复杂平台。可以从最小可用的几件事开始。
第一，写一份短的项目规则。不要写成长篇说明书，只保留真正会影响 Agent 行为的约定：包管理器、测试命令、禁止改动的目录、代码风格、完成标准。
第二，把验证命令接进工作流。只靠模型自评不够，至少要让 lint、typecheck、单元测试或构建命令成为完成任务前的反馈。
第三，给工具做边界。读和写分开，高风险操作需要确认，外部内容默认是不可信数据，不让它直接变成指令。
第四，保留失败日志。每次 Agent 出错，都记录触发场景、错误行为、应该新增的约束。不要靠感觉优化 prompt，要让真实失败驱动 Harness 演进。
第五，不急着平台化。多数团队的第一版 Harness，就是一份规则文件、几个脚本、几个 hook、一个清晰的权限策略。先让它解决真实问题，再决定是否抽象。
一个判断框架
当 Agent 出问题时，可以用下面这张表先定位问题：
| 现象 | 可能不是模型问题，而是 |
|---|---|
| Agent 不知道项目约定 | 上下文注入不完整 |
| Agent 乱选工具 | 工具命名、描述或 schema 不清楚 |
| Agent 长任务跑偏 | 缺少计划、检查点和上下文压缩 |
| Agent 说完成但结果坏了 | 没有自动验证和失败反馈 |
| Agent 执行了危险动作 | 权限、沙箱和 hook 不够 |
| Agent 被外部文本带偏 | 不可信内容隔离不足 |
这个框架比“换个模型试试”更有工程价值。模型升级当然重要，但能不能把能力稳定落到任务里，往往取决于 Harness。
小结
Agent Harness Engine 的核心不是做一个更华丽的 Agent 外壳，而是承认：大模型要进入真实工程，必须被放进一个有状态、有工具、有权限、有反馈、有恢复路径的运行系统。
未来模型会继续变强，但 Harness 不会消失。模型擅长的部分变了，Harness 负责的边界也会移动。旧的脚手架会被删掉，新的安全、协作、长期记忆和评估机制会长出来。
真正值得积累的，不是某一版 prompt，而是这套把失败变成规则、把规则变成系统、再让系统持续变轻的能力。
参考资料
- 微信公众号 AINLP：《Agent Harness Engineering 详解》
- Addy Osmani：Agent Harness Engineering
- LangChain Blog：The Anatomy of an Agent Harness
- Anthropic Engineering：Claude Code: Best practices for agentic coding