Harness Engineering的核心方法论：不是写规则，而是设计控制系统

一句话定义

我们先来探讨一个相对硬核的概念：Harness Engineering。它并非Prompt Engineering的简单升级，而是一套完整的工程系统——将上下文、约束、验证、反馈回路以及清理机制，全部编码为agent可读、可执行且能持续演化的形态。这套体系正在重新定义AI 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拆解成六七个最佳实践来罗列，容易让人误以为它只是一张清单。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
• 检测架构约束违规并自动修复
• 追踪技术债务并生成偿还计划

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

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

闭环验证：从“会写”到“会验”

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

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

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

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

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

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

OpenAI文章中最关键的一句话，莫过于这一句：

这句话揭示了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的可维护性问题，不保证天然通用，也不自动解决功能正确性。适用前提、改造成本和验证缺口是采纳前必须评估的。

参考资料

• Harness engineering: leveraging Codex in an agent-first world — OpenAI
• Harness Engineering — Birgitta Böckeler / Martin Fowler
• The Emerging "Harness Engineering" Playbook — ignorance.ai
• Skill Issue: Harness Engineering for Coding Agents — HumanLayer
• Unlocking the Codex harness: how we built the App Server — OpenAI
• My AI Adoption Journey, Step 5: Engineer the Harness — Mitchell Hashimoto