Harness Engineering：当 AI Agent 开始写代码，工程师要搭建什么系统

2026 年初，Harness Engineering 开始频繁出现在 AI 编程讨论里。它不是“再换一个更强模型”的故事，也不是把 prompt 写得更长：当 coding agent 已经能够读仓库、改文件、运行命令、开 Pull Request，决定其产出是否可信的，越来越多是模型外部的工程系统。

一个更克制、也更准确的定义是：

Harness Engineering 是为 AI Agent 设计可读取的上下文、可操作的环境、可执行的约束与可闭环的反馈机制，使其能在真实项目中持续完成可验证工作的工程实践。

这个术语在 2026 年 2 月因为 Mitchell Hashimoto 的文章与 OpenAI 的 Codex 实验被广泛讨论；其背后的做法则更早已经出现在 Anthropic 对长时运行代理的研究中。随后，Thoughtworks 的 Birgitta Böckeler 在 Martin Fowler 网站发表长文，将它整理为更一般化的工程框架：guides 在行动前引导，sensors 在行动后纠错。

本文不讨论“Agent 会不会取代开发者”这种宏大命题，而回答更具体的问题：

1. Harness 到底包含什么？
2. 它和 Prompt Engineering、Context Engineering、MCP 有什么区别？
3. 为什么 OpenAI 与 Anthropic 都把注意力放到了 harness 上？
4. 一个普通团队怎样从现有仓库开始建设自己的 harness？

一、从 Prompt 到 Harness：变化的是工作闭环

在聊天机器人时代，开发者最常优化的是一轮对话的输入质量：

text
1Prompt -> Model -> Answer

到了代码代理时代，工作过程更像：

text
1Intent
2  -> repository context / rules / plan
3  -> agent changes code in an isolated environment
4  -> tests / browser / logs / review provide evidence
5  -> agent repairs or escalates
6  -> mergeable change and durable project memory

Agent 的输出不再只是一段文本，而可能是：

• 修改数十个文件
• 运行测试、迁移或浏览器验证
• 调用外部工具与服务
• 留下下一次 session 要继续使用的状态
• 创建、修复并合并一个 PR

此时只改 prompt 不够，因为失败往往不是“没有说清楚”，而是：

• Agent 根本看不到关键产品决策或架构规则
• 开发环境不能独立复现，验证路径太贵
• 仓库没有机械约束，错误模式被不断复制
• 长任务跨 session 后丢失进度或提前宣告完成
• 结果没有运行证据，只能靠人逐行猜测是否正确

Harness Engineering 的重点，就是把这些依赖人类经验的隐性条件，转换成 Agent 能检索、执行和验证的系统。

二、术语是如何形成的

1. Anthropic：先解决跨上下文工作的现实问题

Anthropic 在 2025 年 11 月 26 日 发布的《Effective harnesses for long-running agents》中，讨论了一个非常实际的问题：复杂应用无法在一个 context window 内完成，而新 session 不知道上一个 session 做了什么。

他们的实验采用了两类 Agent：

关键点不是角色名称，而是把记忆和完成标准外置：

• 用结构化 feature list 防止 Agent “做了几个页面就认为完成”
• 用 progress 文件和 Git 历史完成 session 交接
• 用启动脚本和浏览器测试让下一轮先恢复可工作的基线
• 每次只完成一个可验证的小单元，减少半成品扩散

这其实已经是一套完整 harness，只是当时讨论焦点放在“long-running agents”。

2. Mitchell Hashimoto：失败一次，就改善一次环境

Mitchell Hashimoto 在 2026 年 2 月 5 日 的《My AI Adoption Journey》中，把自己的第五阶段命名为 Engineer the Harness。他的核心实践非常直接：

• 如果 Agent 反复走错命令或 API，把正确路径写入 AGENTS.md
• 如果 Agent 无法确认页面、测试或构建是否正确，就补充可调用的验证工具
• 一旦看到某类错误，就尝试让同类错误以后能被引导或自动检测

这是一种“棘轮”思路：人工纠错不应只修掉本次产物，还应留下能提升后续 Agent 成功率的机制。

3. OpenAI：把 harness 作为 Agent-first 项目的主工程工作

OpenAI 于 2026 年 2 月 11 日 发布《Harness engineering: leveraging Codex in an agent-first world》，披露了一个内部 beta 项目实验：

• 从 2025 年 8 月底的空 Git 仓库开始
• 五个月后形成约一百万行代码的仓库
• 小规模团队驱动 Codex 打开并合并约 1,500 个 PR
• 应用逻辑、测试、CI、文档、可观测性与内部工具均由 Codex 生成

这不是一条可以无条件推广到所有项目的性能承诺。更有价值的是 OpenAI 公开了为此补齐的环境：

• 让每个 Git worktree 可独立启动一份应用
• 把 DOM snapshot、截图和导航能力暴露给 Agent，用于复现和验证 UI 修复
• 把日志、metrics、traces 暴露到每个临时工作环境中
• 用短 AGENTS.md 作为地图，把详细知识放在版本化的 docs/ 中
• 用自定义 lint 和结构测试机械约束依赖方向、边界解析、日志和文件大小
• 定期运行清理任务，修正文档腐化和代码中的坏模式

OpenAI 也明确提示：这种端到端能力高度依赖该仓库已有的结构和工具投入，不能假定在未经建设的项目中同样成立。

4. Birgitta Böckeler：从案例抽象为控制系统

Birgitta Böckeler 在 Martin Fowler 网站于 2026 年 4 月 2 日 发表的文章中，将 coding agent 的外部 harness 拆成两个互补部分：

他们进一步区分：

• Computational controls：确定性、廉价、可重复，例如编译器、lint、单元测试、依赖边界检查。
• Inferential controls：需要语义判断，例如由另一 Agent 评估需求实现程度、UI 质量或过度设计风险。

这个区分很重要。不能因为 LLM 可以 review，就放弃快速确定性检查；也不能因为测试全绿，就假设产品语义、交互质量和架构取舍一定正确。

三、Harness 不等于 Prompt，也不等于 MCP

几个概念经常混在一起，但它们处理的是不同层次的问题。

可以把 Prompt 和 Context 理解为 harness 的组成部分，把 MCP 理解为 harness 可能采用的一种能力接入协议。但一个安装了很多工具、塞入大量文档，却没有权限边界、完成标准和验证反馈的 Agent，并没有获得可靠的 harness。

四、一个可工作的 Harness 有哪些层

以下分层不是某个产品的固定协议，而是从公开案例中归纳出的实用模型。

1. 入口层：告诉 Agent 如何找到真实信息

入口文件不应成为百科全书。OpenAI 的经验是使用短小的 AGENTS.md 作为地图，再链接到仓库内版本化的详细知识。

text
1AGENTS.md                 # 入口：命令、关键规则、文档索引
2ARCHITECTURE.md           # 模块和依赖方向
3docs/
4  product/                # 需求与验收条件
5  plans/active/           # 正在执行的复杂任务
6  plans/completed/        # 决策记录与已完成工作
7  reliability/            # SLO、失败处理、运行手册
8  security/               # 权限边界与敏感操作

原则是：关键决策如果只存在聊天消息或某个人脑子里，对运行中的 Agent 就等于不存在。

2. 任务层：把意图转换成可验收的单元

“优化登录体验”不够可执行。Agent 需要明确的验收条件：

md
1## Password reset validation
2
3- Invalid email input shows inline error without issuing a request.
4- Valid submission shows the confirmation state.
5- The API endpoint remains backward compatible.
6- Add automated coverage for both paths.

长任务还需要有计划状态和决策日志。重点不是写更多文档，而是防止 Agent 在 session 切换后重新猜测需求。

3. 执行层：为 Agent 提供可恢复、可隔离的工作环境

真实 harness 必须让 Agent 安全动手：

• 每个任务使用隔离 worktree 或 sandbox
• 有一致的安装、启动、seed 与 teardown 命令
• 高风险动作需要权限批准
• 外部凭据按最小权限暴露
• 失败后能回到清晰的 Git 基线

没有执行隔离，Agent 的速度可能只是更快地污染共享环境。

4. 能力层：给 Agent 高质量而非无限量的工具

有效工具的特征是输入清楚、输出紧凑、失败可诊断。例如：

• 文件检索和局部编辑
• 运行特定测试或类型检查
• 打开本地页面、截取 DOM / screenshot、执行关键用户路径
• 查询任务对应的 logs、metrics、traces
• 读取 issue / PR review 或内部规范

工具越多不一定越好。工具缺乏描述、授权范围过大或返回噪声太多，都会消耗 context 并放大错误。

5. 约束层：把架构品味变成机器能执行的边界

对人类开发者，一段架构说明往往足以触发判断；Agent 更需要明确的、可失败的约束：

text
1Types -> Config -> Repository -> Service -> Runtime -> UI

可以通过以下手段执行：

• ESLint 自定义规则限制 import 方向
• structural tests 确认层级边界
• schema validation 强制外部数据先解析再进入业务逻辑
• 类型检查、格式化与文件大小阈值
• 禁止敏感模块调用不安全 API

好的约束关注 invariant，而不是规定每一行如何实现。否则 harness 会把 Agent 的执行空间锁死，同时产生难以维护的规则负担。

6. 反馈层：让 Agent 看见自己是否真的做对了

Harness 的质量很大程度取决于反馈延迟。一个任务修改后，要尽快回给 Agent 明确信号：

单元测试不能证明产品做对了事；AI review 也不能替代确定性测试。可靠反馈来自两者组合。

7. 记忆与治理层：让成功经验累积，让坏模式停止扩散

一次通过的 PR 并不代表系统会持续健康。Agent 会复制仓库中已经存在的模式，包括不好的模式。

因此 harness 还要管理：

• 版本化的 plan、decision record 和 progress
• 失败原因、修复动作与新增规则之间的追踪
• 定期文档校验和技术债扫描
• 权限操作与工具调用审计
• Agent 输出质量、回退率和人工介入点

这也是 OpenAI 将周期性清理比作 garbage collection 的原因：如果不持续清理，较高吞吐会更快积累熵。

五、关键控制环：Guides、Sensors 与修复策略

将上述组件收敛起来，一个团队应当建立以下闭环：

text
11. 人给出意图与验收条件
22. Agent 从仓库入口加载任务相关 guides
33. Agent 在隔离环境中做最小可验证修改
44. Sensors 立即产生证据：测试、截图、日志、review
55. Agent 根据证据修复，或在判断/权限边界处升级给人
66. 合并变化，并把新知识写回 guides 或 sensors

最后一步最容易被忽略。如果一个 review comment 只是修复当前 PR，同一问题很可能再次出现；如果它变成 lint 规则、模板、测试、skill 或架构文档，人的一次判断就能反复产生价值。

六、从零落地：一个团队的四阶段路线

不要一开始就建设复杂的多 Agent 编排系统。一个可靠 harness 通常是从重复痛点逐步生长出来的。

阶段一：让单个 Agent 可控完成小任务

先补齐最小闭环：

• 一个不超过几屏的 AGENTS.md
• 明确的 install、dev、test、lint、build 命令
• 对危险命令和密钥访问的限制
• 要求每次修改说明验证证据

此阶段衡量的不是“写了多少代码”，而是小 PR 是否更少需要返工。

阶段二：把重复的人类纠错编码进去

收集 review 中不断出现的问题，逐一选择最便宜的解决方式：

这就是 Hashimoto 所说的思想：修的是导致错误反复出现的工作环境。

阶段三：支持跨 session 和并行任务

当任务跨越多个 context window 或多个 Agent 时，增加持久化工件：

text
1docs/plans/active/feature-x.md
2docs/decisions/adr-00xx.md
3quality/known-failures.json
4scripts/verify-critical-path.sh

计划中至少记录：

• 当前验收目标
• 已完成和未完成步骤
• 已确认的技术决策及原因
• 验证方式与现有失败
• 下一轮应从哪里开始

这里不应依赖对话摘要充当唯一记忆。对话会被压缩或丢失，仓库工件可以被检索、review 与版本控制。

阶段四：测量 harness 本身并持续收敛

当 Agent 使用变成常态，开始记录：

• 从任务启动到首个可合并 PR 的时间
• 验证失败类型及出现频率
• 人工 review 发现但 sensors 没发现的问题
• PR 回退率、线上缺陷率、技术债趋势
• 每类工具和检查的成本、延迟与命中价值

如果某条规则持续不再有价值，或者模型升级后某个复杂流程已经成为冗余，也应删除或简化它。Anthropic 在后续 harness 文章中指出：harness 的每个组件都隐含了“模型自己做不到什么”的假设，而这些假设会随模型能力变化而过期。

七、一个最小仓库模板

以下模板足以从普通 Web 项目启动一次可靠性建设：

text
1repository/
2├── AGENTS.md
3├── ARCHITECTURE.md
4├── docs/
5│   ├── product/
6│   │   └── acceptance-criteria.md
7│   ├── plans/
8│   │   ├── active/
9│   │   └── completed/
10│   └── reliability/
11│       └── local-validation.md
12├── scripts/
13│   ├── setup-dev.sh
14│   └── verify-critical-path.sh
15├── eslint.config.mjs
16└── package.json

AGENTS.md 可以从非常短的内容开始：

md
1# Agent Entry Point
2
3## Start Here
4- Read `ARCHITECTURE.md` before cross-module changes.
5- Read the relevant file in `docs/product/` before behavior changes.
6- For multi-step work, create or update a plan in `docs/plans/active/`.
7
8## Commands
9- Install: `npm install`
10- Development: `npm run dev`
11- Validate: `npm run lint && npm run build`
12
13## Boundaries
14- Do not expose credentials in logs or test fixtures.
15- Do not change public API behavior without updating acceptance criteria.
16- Do not mark work complete without reporting validation evidence.

重要的不是文件名本身，而是这些内容必须可信、短小、可维护，而且能指向更深的事实源。

八、三种常见误区

1. 把长提示词当作 harness

一个写满禁止事项的巨型入口文件很快会腐化，并占满 Agent 真正需要用来理解代码与任务的上下文。入口应当导航，关键边界则尽量由测试和工具执行。

2. 只追求自主运行时间

Agent 连续运行六小时并不是成功标准。没有阶段性验收、权限隔离和运行证据，长运行时间只是扩大不可控修改的范围。

3. 把 OpenAI 的案例当作普遍基准

百万行代码和大量 PR 是特定实验的披露结果，不等于每个团队都应该采用“零人工写代码”，也不能单独证明长期维护成本更低。更可复用的结论是：在 Agent 高吞吐环境中，文档可读性、机械边界、可观测验证与持续清理变得更重要。

九、工程师的角色真的变了吗

角色有所上移，但责任没有消失。

在 Agent-first 工作流中，人类投入更多时间于：

• 把模糊意图变成可验收行为
• 选择哪些知识要沉淀为仓库事实
• 决定权限、风险与升级边界
• 把反复出现的 review 意见转成工具或规则
• 判断测试无法覆盖的产品语义与取舍

这不是“不再需要软件工程”，而是软件工程的一部分从逐行生产代码，转向设计一个能稳定生产、检查和修正变化的系统。

结语

Harness Engineering 之所以在 2026 年迅速变热，不是因为行业需要一个新名词，而是因为 coding agent 把一个原本隐性的事实暴露了出来：

可靠软件从来不只依赖写代码的能力，也依赖环境、约束、证据、交接和持续治理。

模型越能执行，外部系统越需要清楚地回答：

• 它应当看到什么？
• 它可以修改什么？
• 它如何知道自己做对了？
• 出错时谁阻止它、谁修复它、怎样避免再次发生？

当这些问题被写入文档、工具、测试、sandbox、观测和治理流程，Agent 才从“能生成代码”走向“能参与可靠交付”。这就是 Harness Engineering 的实际价值。

References

• Mitchell Hashimoto, My AI Adoption Journey, 2026-02-05: https://mitchellh.com/writing/my-ai-adoption-journey
• OpenAI, Ryan Lopopolo, Harness engineering: leveraging Codex in an agent-first world, 2026-02-11: https://openai.com/index/harness-engineering/
• Anthropic, Effective harnesses for long-running agents, 2025-11-26: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
• Anthropic, Prithvi Rajasekaran, Harness design for long-running application development, 2026-03-24: https://www.anthropic.com/engineering/harness-design-long-running-apps
• Anthropic, Lance Martin, Gabe Cemaj and Michael Cohen, Scaling Managed Agents: Decoupling the brain from the hands, 2026-04-08: https://www.anthropic.com/engineering/managed-agents
• Birgitta Böckeler, Harness engineering for coding agent users, MartinFowler.com, 2026-04-02: https://martinfowler.com/articles/harness-engineering.html

本文资料检索与链接核验日期：2026-05-25。OpenAI 案例中的规模与效率数据为其官方披露，不代表对其他代码库的普遍效果承诺。