控制系统设计指南：Harness Engineering权威解析
Harness Engineering 精确定义
先厘清一个工程概念：Harness Engineering。它不是 Prompt Engineering 的简单延伸，而是一套完整的工程系统——将上下文、约束、验证、反馈回路与清理机制，编码为 agent 可读、可执行、可持续演化的结构化形态。
OpenAI 在 2026 年 2 月发布的里程碑论文中反复强调：工程师的核心任务已从“编写代码”转向“设计环境、明确意图、构建反馈回路”。他们直言当前最大的挑战集中在“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
- 检测架构约束违规并自动修复
- 追踪技术债务并生成偿还计划
这不是可选的 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 文章中最关键的一句话，可能是这一句：
这句话揭示了 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 项目和遗留代码库的维护方式，可能会走向完全不同的路径。这种分化在未来几年会越来越显著。
三句话总结
Harness Engineering 的本质不是写规则，而是设计控制回路。它由 context engineering、architectural constraints、garbage collection 三个正交维度构成一个完整的控制系统。
AGENTS.md 只是入口，repo 内部可版本化、可校验的知识才是核心。大一统的指令文件是反模式；渐进式披露、结构化知识、机械化验证才是可 scalable 的方案。
它解决的是规模化 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