Harness Engineering 调查报告

最近一两个月，AI 编程圈里开始反复出现一个词：Harness Engineering。

乍一看，这词很像又一个新包装出来的方法论。其实没那么玄。把 OpenAI、Anthropic、Martin Fowler / Thoughtworks 这几条线放在一起看，它讨论的核心都差不多：当 Agent 真开始改代码、跑命令、提 PR、看日志、调浏览器之后，怎么给它搭一套能稳定干活的工程环境。

Prompt 是你对模型说什么，Context 是你喂给模型什么，Harness 则是你把模型放进什么样的工作台里。

先说结论：Harness 不是替代 Prompt，而是在外面再包一层

这几个概念最容易混：Prompt Engineering、Context Engineering、Harness Engineering。

可以直接理解成三层：

1. Prompt Engineering：你怎么提要求。
2. Context Engineering：你给模型什么信息，比如 RAG、Memory、MCP、文档、代码片段。
3. Harness Engineering：你给 Agent 配什么工具、约束、反馈回路和执行环境。

前两者主要发生在输入侧，Harness 更像运行时这一层。

所以 Harness 真正关心的，通常是这些事：

• Agent 能访问哪些文件、哪些系统、哪些工具。
• 仓库里有没有清楚的 AGENTS.md、设计文档、规范文档。
• 它改完代码后，会不会自动跑 lint、测试、CI。
• 它执行过程中，有没有日志、进度文件和 Git 痕迹可追。
• 出错之后，系统能不能及时把它拉回来。

也正因为这样，很多人会说：2025 年大家在谈 Agent，2026 年开始谈 Harness。

为什么这个概念突然火了

原因很简单：Agent 已经不只是聊天工具了。

早期大家研究的是怎么把提示词写清楚。后来开始研究怎么补上下文。等到 Claude Code、Codex 这类 coding agent 真能在仓库里改文件、跑命令、读日志、调浏览器，问题就变了。

这时候的瓶颈，往往已经不是模型会不会写代码，而是：

• 它能不能理解当前仓库的规则。
• 它做错事时能不能及时停下来。
• 它交出来的改动能不能被 lint、测试、CI、代码审查及时拦住。
• 它是不是处在一个适合自动化协作的工程环境里。

换句话说，模型能力当然还在涨，但系统外层的工程护栏开始和模型本身一样重要。

OpenAI、Anthropic、Thoughtworks 其实在说同一件事

三家的说法不完全一样，但落点很接近。

OpenAI：Harness 是 agent-first 世界里的基础设施

OpenAI 在 Harness engineering: leveraging Codex in an agent-first world 里讲得很直接：当 Codex 这类 agent 真进入开发流程后，关键不只是模型本身，而是周围整套工程设施。

他们强调的东西都很务实：

• 在仓库里放清楚的 AGENTS.md
• 补齐架构文档、设计文档、产品说明和约束说明
• 给 Agent 接浏览器调试、日志查询、监控查询这些工具
• 用 lint、CI、代码审查约束产出质量
• 把人和 Agent 的分工说清楚：Humans steer. Agents execute.

这句话很关键。它的意思不是人不写代码了，而是人更多负责定方向、收边界、验结果，执行这部分尽量交给 Agent。

Anthropic：重点不在“聪明”，而在“能不能连续干活”

Anthropic 那条线更关注长任务的稳定性。

一个 Agent 如果只是回答一句话，那没什么难的。真正麻烦的是它要连续跑几个小时，期间读写文件、调用工具、记录进度、和 Git 交互。到了这个阶段，最重要的就不是它偶尔能不能惊艳一次，而是它会不会在半路失控。

这类 harness 里，常见会有这些东西：

• 初始化脚本，比如 init.sh
• 进度记录文件，比如 claude-progress.txt
• 结构化 JSON 日志
• 清楚的 Git 工作方式
• 失败后的中断、恢复和复盘机制

这也说明了一件事：真正让 Agent 变可靠的，通常不是“再写一个神 prompt”，而是把它放进一个能观察、能回放、能纠偏的执行框架里。

Thoughtworks：把严格性外置

Thoughtworks 的 Birgitta Böckeler 和 Martin Fowler 那边，讲法更像传统软件工程。

核心意思可以概括成一句话：别指望模型自己自觉，严格性要放到系统外面。

做法也很熟：

• 让 Agent 处在有约束的环境里
• 用自动化检查替代“相信它会做对”
• 把工程知识尽量写进仓库，而不是留在人脑里

这个思路一点都不新。测试、静态检查、代码规范、发布流程，本来就是这么干的。区别只是现在被约束的对象不只有人，还多了 Agent。

一个更直白的定义：Harness 就是 Agent 的工作台

把 Agent 想成一个实习生，Harness 就是他坐下干活时周围的一切：桌上摆了什么文档，电脑里装了什么工具，哪些目录能碰，出了错谁来拦，干完活要不要走测试和审批。

所以 Harness 不是单个工具，也不是一份配置文件。它更像一整套组合：

• 输入侧：仓库文档、规范、架构说明、任务描述
• 执行侧：CLI、浏览器、日志系统、数据库、MCP 工具
• 约束侧：权限控制、目录范围、命令白名单、人工确认
• 反馈侧：lint、test、CI、监控、代码审查
• 记录侧：Git 历史、进度文件、日志、可回放的执行轨迹

所以很多人会直接说 Agent Harness。重点不在“提示词升级”，而在“给 Agent 搭一个能工作的工程台子”。

差的 Harness 和好的 Harness，差别非常大

差的 Harness 长什么样

常见情况是：

• 任务描述只有一句话，没背景，没边界
• Agent 能看整个仓库，但不知道哪里能动，哪里别碰
• 改完代码不跑测试，也不跑 linter
• 工具堆了一堆，但没有权限规则
• 没过程记录，出问题只能看最后结果
• 人类开发者得一直盯着补锅

这种时候，Agent 很容易变成“会动的随机数生成器”。偶尔有惊喜，但整体不稳定。

好的 Harness 长什么样

反过来，好的 harness 一般有这些特征：

• 仓库里有清楚的任务说明和约束说明
• 有 AGENTS.md、架构文档、模块文档、规范文档
• Agent 能直接用到需要的工具，但范围是受控的
• 改动自动经过 lint、test、CI
• 失败信息能及时反馈给 Agent 或人
• 整个过程可追踪，方便复盘和持续调整

这时候你会发现，Agent 不需要神一样聪明，也能稳定很多。

这波讨论里反复出现的几类组件

不同团队实现方式不一样，但常见的东西大同小异。

1. 仓库内文档

最常见的是 AGENTS.md，除此之外还有：

• ARCHITECTURE.md
• DESIGN.md
• FRONTEND.md
• RELIABILITY.md
• SECURITY.md
• docs/
• design-docs/
• exec-plans/
• product-specs/
• references/

这些文档不只是给人看。更重要的是，它们把原本散落在人脑里的工程知识，变成 Agent 也能直接消费的显式上下文。

2. 外部工具接入

比如：

• 浏览器调试能力，例如 Chrome DevTools Protocol
• 日志和观测系统，例如 LogQL、PromQL、TraceQL
• 代码库检索、终端、文件操作、数据库访问

Agent 只会看代码时，能力其实很有限。它能看浏览器、看日志、跑命令之后，才更像一个真正能排查问题的执行体。

3. 自动化校验

这一层其实最传统，但也最有用：

• linters
• tests
• CI/CD
• code review

很多团队真正提高 Agent 质量的方式，不是继续堆 prompt，而是把这些老工具重新接回 Agent 流程。模型负责生成候选方案，工程系统负责拦错。

4. 过程记录与可回放

这一点也很关键：

• 进度文件
• JSON 日志
• Git 痕迹
• 可恢复的任务状态

没有这些东西，Agent 任务一旦跑长，很快就会进入黑箱状态：它刚才做了什么，为什么这么改，失败发生在哪一步，全都不清楚。黑箱一出现，协作效率基本就开始掉。

为什么说 Harness 比 Prompt 更“硬”

Prompt 当然重要，但它有个天然问题：很多约束只存在于语言里。

你可以在 prompt 里写“不要修改核心模块”，但如果系统权限没限制、目录边界没写清、验证流程没接上，这句话本身很脆。

Harness 的价值就在这里。它把口头要求变成结构化约束。

比如：

• 不是“尽量别动这些目录”，而是直接限制可编辑范围
• 不是“改完记得跑测试”，而是自动触发测试
• 不是“如果失败请记录原因”，而是强制写进进度文件或日志
• 不是“你应该遵守规范”，而是让 linter 和 CI 来裁定

所以 Harness Engineering 更像工程，而不是提示词技巧。

它解决的不只是质量问题，还有人的带宽问题

我很认同一个判断：很多团队真正卡住的，不是“Agent 能不能多写点代码”，而是“人还跟不跟得上它的节奏”。

当 Agent 一次能改几十个文件、发多个 PR、并行跑几个任务时，如果没有好的 harness，人类开发者就会变成：

• 到处补文档的人
• 一直盯日志的人
• 替 Agent 收拾残局的人
• 在 review 和 debug 之间来回切的人

结果就是，Agent 表面上在提速，团队的心智负担却在上升。

好的 harness 反而是在减轻这种负担：

• 任务边界更清楚
• 错误暴露得更早
• 回溯成本更低
• 人的注意力能集中在更关键的地方

所以它不只是技术话题，也是协作设计问题。

Harness 会改写一部分开发者工作

这事其实挺现实。Agent 越来越能执行之后，开发者的很多工作都会重新分配。

以前很多人的成就感来自“这个功能是我亲手敲出来的”。但在 agent workflow 里，更重要的能力慢慢会变成：

• 定义任务边界
• 拆任务
• 写清楚约束和验收标准
• 判断 Agent 的产出哪里对、哪里不对
• 设计更好的反馈回路

这里面至少有三个变化。

第一，IC 和 Tech Lead 的边界会变

如果一个人能同时驱动多个 Agent 并行执行，那么“个人产能”这件事本身就变了。

不少原本偏 IC 的角色，会越来越像在做任务编排、质量把关和系统设计。不是不写代码，而是写代码不再是唯一核心动作。

第二，Flow 可能更顺，也可能更碎

这听起来矛盾，但很真实。

一方面，Agent 确实能替你接住很多碎活，比如查日志、跑脚本、改样板代码。另一方面，如果 harness 做得很差，你会被它的错误、歧义和返工不停打断。

真正决定体验差异的，很多时候不是 Agent 本身，而是外围系统搭得怎么样。

第三，新人 onboarding 也会被重写

以前带新人熟悉项目，要一起看目录、看模块、讲历史包袱。以后其中一部分东西，会先沉淀进 AGENTS.md、规范文档、执行手册，再交给 Agent 去消费和执行。

这意味着文档不再只是“给新人看的材料”，也越来越像“给 Agent 用的运行配置”。

为什么大家开始认真对待它

这波讨论里既有 OpenAI、Anthropic、Thoughtworks 的文章，也有一些基准测试和案例观察。虽然口径不完全一样，但趋势很明显：单纯换模型，不如先把 harness 搭好。

一些常见观察是：

• 只改 harness，不改模型，编码表现也可能明显提升
• LangChain Terminal Bench 2.0 这类评测，已经开始把 harness 当成关键变量
• 很多“AI 味”代码、无效 PR、无意义改动，问题不一定出在模型智力上，更可能是 harness 太弱

这一点很重要。

很多人一看到 Agent 产出差，就下意识觉得是模型不够强。现实里更常见的原因其实是：

• 任务上下文不够清楚
• 仓库级规则没写明白
• 没有验证闭环
• 没有接入真正需要的观测工具

模型当然重要，但它越来越像 CPU。真正影响系统表现的，是整台机器怎么组起来。

对普通开发者来说，最值得先补的是这三样

如果你已经在用 Claude Code、Codex、Cline 或别的 coding agent，我觉得最值得先补的，不是什么花哨工作流，而是下面三件事。

1. 把项目规则写出来

先别急着研究多 Agent 并行，先把这些最基础的东西补齐：

• 项目结构说明
• 哪些目录能改，哪些不能改
• 常用命令
• 测试方式
• 提交规范
• 关键模块边界

很多团队所谓的“AI 不靠谱”，本质上只是把本该显式写下来的规则，全都留在了老员工脑子里。

2. 把验证流程自动化

至少要做到：

• 改完自动跑 lint
• 改完自动跑核心测试
• 出错有明确反馈

如果验证还靠人手动检查，Agent 带来的收益会很快被吃掉。

3. 给它配对的工具，不要盲目堆工具

不是 MCP 越多越好，也不是工具越全越好。

真正有效的是：围绕任务场景，给 Agent 配上刚好够用的工具，再把边界说明白。

比如前端排障时，浏览器调试工具很关键；后端排障时，日志、trace、数据库只读查询更关键。工具和任务不匹配，最后只会制造更多噪音。

我的理解：Harness Engineering 本质上是个老问题

它真正回答的，其实还是那个老问题：怎么让一个不完全可靠的执行者，持续在复杂系统里产出可接受的结果。

以前我们回答这个问题，靠的是培训、规范、评审、测试、发布流程。现在执行者里多了 Agent，于是这个问题又被重新问了一遍。

所以我不太把 Harness Engineering 看成一个全新学科。更准确的说法也许是：软件工程在 AI Agent 时代的一次重新落地。

只是这一次，被管理的不再只有人，还有模型驱动的执行体。

最后

到 2026 年，Agent 的上限越来越像模型问题，Agent 的下限越来越像 harness 问题。

模型决定它能不能做得更好，Harness 决定它会不会稳定地做对。

这也是为什么越来越多团队开始把注意力从“怎么写一个更厉害的 prompt”，转向“怎么给 Agent 搭一套真正能落地的工程环境”。

后者没那么炫，但通常更值钱。

参考材料

• OpenAI - Harness engineering: leveraging Codex in an agent-first world（2026-02-11）
• Anthropic - Effective harnesses for long-running agents（2025-11-26）
• Martin Fowler / Birgitta Böckeler - Harness Engineering（2026-02-17）
• Mitchell Hashimoto - My AI Adoption Journey（2026-02-05）
• SmartScope - What Is Harness Engineering: Defining the Outside of Context Engineering
• Pawan Patra - A Developer's Guide to Harness Engineering（2026-02-22）
• InfoQ - OpenAI Introduces Harness Engineering
• Marius Anderie - The Psychology of Coding With AI Agents（2026-02）
• LangChain - Improving Deep Agents with harness engineering
• Phil Schmid - The importance of Agent Harness in 2026