Harness Engineering：不是写规则，而是设计控制系统

AI程序员
7 阅读9分钟

一句话定义

Harness Engineering 不是 Prompt Engineering 的升级版，而是将上下文、约束、验证、反馈回路和清理机制编码成 agent 可读、可执行、可持续演化的工程系统。

OpenAI 在 2026 年 2 月发布的那篇文章反复强调的核心命题是：工程师的主要工作已经从"写代码"转移到 "design environments, specify intent, and build feedback loops"。他们自己也说，最大的挑战已经集中在 "designing environments, feedback loops, and control systems"。这不是修辞，这是他们用 5 个月、3 名工程师、0 行手写代码、约 100 万行 agent 生成代码的实践得出的结论。

本文综合 OpenAI 官方原文、Martin Fowler（Birgitta Böckeler）的解读、HumanLayer 的实战经验等多方视角，试图把 Harness Engineering 讲得更完整、更精确、更有边界感。

为什么叫 Harness？

"Harness" 的原义是马具——缰绳、鞍具、嚼子——一整套将强大但不可预测的动物导向正确方向的装备。Mitchell Hashimoto（Terraform/Ghostty 作者）在他的 AI 采纳历程博文中推广了这个概念，核心理念是：每当 agent 犯一次错，就工程化地修复一次，让它永远不再犯同类错误。

OpenAI 的文章虽然标题用了 "Harness Engineering"，正文只出现过一次 "harness"，但其描述的整套方法论——上下文管理、架构约束、反馈回路、熵治理——正是 harness 的工程化展开。

LangChain 的实验提供了量化佐证：同一个模型，仅改变 harness，Terminal Bench 2.0 得分从 52.8% 跳到 66.5%，排名从 Top 30 进入 Top 5。模型是商品，harness 是壁垒。

Harness 的三层控制结构

很多文章把 Harness Engineering 拆成六七个 best practices 罗列，容易让读者误以为它是一个 checklist。Birgitta Böckeler（发表于 Martin Fowler 站点）的解读更精确——她将 OpenAI 的实践收束为三个正交的控制维度：

1. Context Engineering：让 agent 看见正确的信息

从 agent 的视角出发，任何它在上下文中无法访问的信息，等于不存在。Google Docs 里的架构决策、Slack 里的技术对齐、工程师脑中的隐性知识——对 agent 来说全是黑洞。

OpenAI 的做法是把 repo 本身变成 system of record。所有知识——设计文档、架构图、执行计划、质量评分、技术债追踪——都以 versioned artifacts 的形式存在于代码仓库中。

AGENTS.md 是入口，不是知识本体。 这一点需要特别强调。OpenAI 的仓库里有 88 个 AGENTS.md 文件，根文件定义全局规则，子目录文件覆盖局部规则。但真正的知识库在结构化的 docs/ 目录里，包含 maps、execution plans、design specs，全部通过 linter 和 CI 校验交叉链接的一致性。

他们明确指出，"大一统的 AGENTS.md" 是反模式：

  • 上下文是稀缺资源。 一个巨型指令文件会挤占任务、代码和相关文档的空间，agent 要么遗漏关键约束，要么开始优化错误目标。
  • 当所有东西都 "重要"，没有东西是重要的。 agent 会退化为局部模式匹配，而不是有意图地导航。
  • 单体文件无法机械验证。 覆盖率、新鲜度、归属、交叉引用——这些都无法对一个 blob 做自动化检查，drift 不可避免。

所以正确的理解是：AGENTS.md 是目录，repo 内可版本化、可校验的知识组织才是核心。 渐进式披露（progressive disclosure）是关键设计原则——agent 在每个任务中只获取它需要的上下文，不多也不少。

2. Architectural Constraints：用机械手段限制解空间

约束不是审查，而是可执行的边界。

OpenAI 为每个业务域建立了严格的分层架构，依赖方向被强制为单向流动：

Types → Config → Repo → Service → Runtime → UI

横切关注点只能通过 Providers 注入。这些规则不靠 code review 人工执行，而是靠 custom lints 和 structural tests 机械强制。关键细节是：lint 报错信息本身会携带修复指令，直接喂回 agent 的上下文，形成自动修复闭环。

这意味着 harness 不是 "人 review agent 的输出"，而是 "机器先把 agent 约束在一个可维护的解空间里，agent 在边界内自主操作"。

Anthropic 团队在他们关于 long-running agent 的文章中从另一个方向验证了这个模式：他们发现用 JSON 做 feature tracking 比 Markdown 效果更好，因为 agent 不太会随意修改或覆盖结构化数据。结构本身就是约束。

3. Garbage Collection：持续清理熵增

代码库是活的系统，会腐烂。人写代码时技术债线性增长；agent 写代码时技术债指数增长——因为 agent 不会主动清理上一轮的遗留，反而会基于它继续构建。

OpenAI 的解法是部署 GC Agent——后台周期性运行的 agent，职责包括：

  • 扫描过期文档，提交清理 PR
  • 检测架构约束违规并自动修复
  • 追踪技术债务并生成偿还计划

这不是可选的 nice-to-have，而是规模化 agent coding 的生存条件。没有 GC，repo 的信噪比会随 agent 产出速度迅速恶化。

传统的技术债治理模式是 "累积 → 爆发 → 停下来还债"。Harness 的模式是 "GC Agent 持续运行 → 小增量清理 → 代码库自我清洁"。

闭环验证：从 "会写" 到 "会验"

代码吞吐量上来之后，瓶颈从 "写代码" 转移到 "验证代码"。这是 Harness Engineering 讨论中经常被低估的维度。

OpenAI 的突破点是让 agent 直接接入运行时可观测性：

  • UI 通道：agent 可以驱动浏览器、截取 DOM 快照和截图、操作页面验证交互
  • 日志通道：agent 可以查询错误日志、追踪请求链路
  • 指标通道：agent 可以查询延迟、吞吐量、错误率等运行时指标

典型工作流是：agent 自己启动服务 → 查询启动耗时指标 → 定位瓶颈 → 优化代码 → 再次验证 → 全程无人工介入。

这就是 Harness 的核心闭环：生成 → 约束 → 验证 → 反馈 → 再生成。缺少验证环节的 harness 只完成了一半。

迭代飞轮：agent 的失败是 harness 的输入

OpenAI 文章中最关键的一句话可能是：

When the agent struggles, we treat it as a signal: identify what is missing — tools, guardrails, documentation — and feed it back into the repository, always by having Codex itself write the fix.

这句话揭示了 Harness Engineering 的核心运作机制：它不是一次性设计好的静态系统，而是一个以 agent 失败为输入、以 harness 改进为输出的持续迭代飞轮。

Agent 犯错 → 分析缺失的约束/工具/文档 → 让 agent 自己修复 harness → 同类错误不再发生。

HumanLayer 团队的实战经验与此一致：他们的策略是 "bias towards shipping"——不预防性地优化 harness，而是在 agent 实际失败时才工程化修复。他们也发现了一些 anti-pattern：过度细分 sub-agent 的工具权限反而导致 tool thrash，效果更差。

这说明 harness 的设计需要实证驱动，不是理论上 "越严格越好"。

这套东西的边界在哪里

大部分关于 Harness Engineering 的讨论比较 "正向"，容易给读者一种 "明天就该全面推行" 的印象。但如果只讲好处不讲边界，文章的可信度会打折扣。

OpenAI 自己承认的局限

  • 这套方法高度依赖特定的仓库结构和工具投入，不能直接泛化到任意项目
  • 他们尚不清楚完全 agent 生成系统的长期架构一致性会如何演化
  • 5 个月、约 100 万行代码是一个令人印象深刻的数字，但 OpenAI 作为 Codex 的开发者，他们有动机让我们相信 agent 可维护的代码是可行的

Böckeler 指出的缺口

  • 文章描述的所有措施聚焦于长期内部质量和可维护性，但对 "功能和行为是否正确" 的验证 着墨不足
  • 旧代码库 retrofit 一套 harness 可能得不偿失——就像对一个从未跑过静态分析的代码库第一次开启 linter，alert 会淹没你

适用前提判断

从已有案例看，Harness Engineering 更适合：

  • 新项目或可强约束的项目：从零开始设计 harness 远比改造容易
  • 技术栈少、架构边界清晰的团队：Böckeler 观察到，大多数组织只有两三个主力技术栈，这些可以形成标准化 harness 模板
  • 愿意把文档、约束、观测、清理都工程化的组织：harness 不是 agent 的配置文件，是一整套工程基础设施
  • 有足够的迭代周期：OpenAI 花了 5 个月迭代 harness，这不是一周能搞定的事

对于已有大型遗留代码库的团队，更现实的路径可能是：先在增量模块上试点 harness，积累经验后再决定是否扩展。

Harness 与未来的工程范式

Böckeler 在文章中提出了几个值得思考的前瞻性问题：

Harness 会成为新一代 service template 吗？ 现在团队用 golden path / service template 初始化新服务；未来可能是从一组 harness 模板中选择，附带 custom linters、structural tests、基础 context 文档和 observability pipeline，然后在迭代中逐步特化。

约束运行时是 agent autonomy 的前提？ 早期 AI coding 的叙事是 "用任何语言、任何模式生成代码，LLM 会搞定一切"。但 OpenAI 的实践表明，提升信任和可靠性恰恰需要收窄解空间——固定架构模式、强制边界、标准化结构。自由度和可控性的 trade-off 是真实存在的。

Pre-AI 和 Post-AI 代码库会分化吗？ 从零构建的 harness-native 项目和遗留代码库的维护方式可能会走向完全不同的路径。这种分化在未来几年会越来越显著。

三句话总结

  1. Harness Engineering 的本质不是写规则，而是设计控制回路。 它由 context engineering、architectural constraints、garbage collection 三个正交维度构成一个完整的控制系统。

  2. AGENTS.md 只是入口，repo 内可版本化、可校验的知识才是核心。 大一统的指令文件是反模式；渐进式披露、结构化知识、机械化验证才是 scalable 的方案。

  3. 它解决的是规模化 agent coding 的可维护性问题，不保证天然通用，也不自动解决功能正确性。 适用前提、改造成本和验证缺口是采纳前必须评估的。

参考资料

avatar
文章
阅读
粉丝