鸭梨公共文档

主题

Harness Engineering：当 AI 光速写代码，如何防止造出屎山 ​

1. 百万行代码零人工编写的震撼 ​

2026 年 2 月 11 日，OpenAI 发布了题为《Harness Engineering: Leveraging Codex in an Agent-First World》的技术博客[1]，披露了一个令人震惊的事实：

他们的团队使用 AI 代理构建了一个超过 100 万行代码的生产级应用，其中零行代码由人类手动编写。

这项实验始于 2025 年 8 月底，历时约 5 个月。项目最初由 3 名工程师驱动 Codex 代理，后来扩展到 7 人。期间共打开并合并了约 1500 个 Pull Request，平均每位工程师每天产出 3.5 个 PR，且这一效率随着团队规模扩大而持续提升[1:1]。

这不是科幻小说的情节，而是正在发生的现实。工程师们不再编写代码，而是设计让 AI 能够可靠编写代码的系统。这个系统——包括约束条件、反馈循环、文档、代码检查工具和生命周期管理——就是所谓的 Harness（工具/约束系统）。

Harness Engineering（驾驭工程）由此成为一门新兴学科，它正在重新定义软件工程师的角色和技能要求。

2. 什么是 Harness Engineering ​

2.1 马具的隐喻 ​

"Harness" 一词源自马具——缰绳、马鞍、马嚼子等装备，用于引导强大但不可预测的动物朝正确方向前进。这个隐喻非常贴切：

  • AI 代理就像一匹强壮的马，能力强大但行为难以预测
  • Harness 就是约束和引导它的装备
  • 好的 Harness 既能发挥 AI 的力量，又能控制其风险

正如《朝鲜日报》英文版报道中所指出的，Harness Engineering 中的 "Harness" 指的就是控制和引导马匹的装备，人类开发者的角色类似于为企业员工提供最新笔记本电脑并授予数据访问权限的管理者——他们创造环境让 AI "员工" 高效工作，同时控制其行为以防止安全问题[2]。

2.2 核心定义 ​

软件工程领域著名专家 Martin Fowler 将 Harness Engineering 定义为"用于约束 AI 代理的工具和实践"[3]。但范围远不止安全——一个精心设计的 Harness 不仅能防止代理出错，还能通过提供正确的上下文、工具和约束来增强其能力。

Harness Engineering 是设计使 AI 代理可靠的系统的学科，包括：

  • 约束（Constraints）：定义 AI 不能做什么
  • 反馈循环（Feedback Loops）：让 AI 知道它做得如何
  • 文档（Documentation）：为 AI 提供必要的上下文
  • 生命周期管理（Lifecycle Management）：管理代码的生成、审查、合并和维护

2.3 为什么需要 Harness Engineering ​

传统的软件工程假设代码由人类编写，而 Harness Engineering 假设代码由 AI 生成。这种转变带来了新的挑战：

代码熵增问题：AI 生成的代码会以不同于人类的方式积累技术债务。OpenAI 称之为"熵"——代理生成的代码会逐渐偏离最佳实践，产生难以维护的代码。这是因为 Codex 倾向于复制仓库中已存在的模式，即使这些模式不够理想[1:2]。

可维护性重新定义：传统上，可维护性意味着人类能够理解和修改代码。现在，可维护性更多地转向意图的清晰度、边界、契约和约束——这些允许人类和机器都能可靠地复现或演进系统。

规模化的 sloppy：模型移动速度快、规模化快，sloppy（草率）也会规模化。正如 InfoQ 报道所强调的，如果没有 Harness，AI 代理只是一个演示——在受控环境中工作出色，但在生产环境中不可预测地失败[4]。原始模型在会话之间没有记忆，如果没有 Harness 来持久化状态和提供上下文，代理会忘记它刚刚做的一切。

3. Harness Engineering 的三大支柱 ​

3.1 上下文工程（Context Engineering） ​

AI 代理的表现很大程度上取决于它获得的上下文。Harness Engineering 强调：

AGENTS.md 文件：在代码库根目录放置此文件，为 AI 代理提供项目概述、架构图、执行计划和质量标准。与代码一起版本控制，确保代理始终获得最新信息。

OpenAI 团队最初尝试了"单一巨型 AGENTS.md"的方法，但失败了。原因包括：上下文是稀缺资源，巨型指令文件会挤占任务、代码和相关文档的空间；当一切都"重要"时，什么都不重要；单一文件会很快过时；且难以验证[1:3]。

他们的解决方案是将 AGENTS.md 视为目录而非百科全书——大约 100 行的简短文件，主要作为地图，指向仓库其他地方的更深入信息源。

知识库维护：OpenAI 团队构建了一个结构化的 docs/ 目录作为系统记录，包含：

  • 设计文档（design-docs/）：包含核心信念和验证状态
  • 执行计划（exec-plans/）：活跃计划、已完成计划和技术债务追踪
  • 产品规范（product-specs/）：功能规格说明
  • 参考资料（references/）：设计系统参考、工具文档等
  • 质量评分（QUALITY_SCORE.md）：各产品领域和架构层的质量评级

文档一致性代理：后台代理定期扫描过时的文档，并打开清理 PR——为代理准备的文档，由代理维护。这实现了"渐进式披露"：代理从稳定的小入口点开始，被教导下一步去哪里查找，而不是一开始就 overwhelmed。

3.2 架构约束（Architectural Constraints） ​

为了防止 AI 生成"功能正确但难以维护"的代码，Harness Engineering 强调架构约束：

黄金原则（Golden Principles）：OpenAI 在代码库中编码了一套"黄金原则"——有主见的、机械化的规则，保持代码库对未来代理运行清晰和一致。例如：

  1. 优先共享工具包：优先使用共享的工具包而非手写的辅助函数，将不变量集中管理
  2. 不 YOLO 式探测数据：验证边界或依赖类型化的 SDK，防止代理基于猜测的数据结构构建代码

模块边界强制：OpenAI 为每个业务域构建了严格的分层架构，依赖方向受到严格验证。代码只能在固定层集内"向前"依赖：Types → Config → Repo → Service → Runtime → UI。跨领域关注点（认证、连接器、遥测、功能标志）通过单一显式接口 Providers 进入。任何违反都被机械地禁止和强制执行[1:4]。

这类似于领导大型工程平台组织：在中央强制执行边界，在本地允许自治。正如 Martin Fowler 团队所发现的，AI 代理在最有效时处于具有严格边界和可预测结构的环境中[3:1]。

代码设计即上下文：代码设计本身是上下文工程的重要组成部分。良好的模块化设计使 AI 更容易理解和修改代码。OpenAI 团队倾向于选择"无聊"的技术——由于可组合性、API 稳定性和训练集中的表示，这些技术更容易被代理建模。在某些情况下，让代理重新实现功能子集比处理公共库的不透明上游行为更便宜[1:5]。

3.3 熵管理（Entropy Management） ​

技术债务就像高利贷——持续小额偿还总是比让债务累积然后痛苦地一次性解决更好。

垃圾回收代理：最初，OpenAI 团队每周五花费 20% 的时间手动清理"AI slop"，但这无法扩展。取而代之的是，他们建立了定期的"垃圾回收"流程——后台 Codex 任务扫描偏差，更新质量等级，并打开针对性的重构 PR。大多数 PR 可以在一分钟内审查并自动合并[1:6]。

持续清理流程：人类品味被捕捉一次，然后在每一行代码上持续强制执行。这使得能够在日常基础上捕获和解决不良模式，而不是让它们在代码库中传播数天或数周。技术债务像高息贷款——持续小额偿还总比让债务累积然后痛苦地一次性解决更好。

质量等级系统：代码库中的每个模块都有质量等级，代理被鼓励优先改进低质量模块。质量文档追踪每个产品领域和架构层的质量等级，随时间记录差距。

4. OpenAI 的实践案例 ​

4.1 团队结构转变 ​

OpenAI 的工程师团队结构发生了根本性变化：

开发者：定义"做什么"和"为什么"。他们拥有意图、业务逻辑和架构图景。

AI 代理：执行"怎么做"。它处理语法、样板代码和文档。

正如 OpenAI 团队成员 Zach Brock 在 LinkedIn 上分享的："在 AI 时代，最优秀的工程师不是写代码最多的人，而是设计最弹性环境的人。"这种焦点的转变带来了 10 倍的速度提升[5]。

当开发者专注于"意图"和"环境"，让代理处理"实现"时，产出增加到每位开发者每天 3.5+ 个 PR。

4.2 实际工作流程 ​

人类几乎完全通过提示与系统交互：工程师描述任务，运行代理，允许它打开 Pull Request。为了推动 PR 完成，OpenAI 指示 Codex：

  1. 本地审查自己的变更
  2. 请求其他特定代理进行审查（本地和云端）
  3. 响应任何人类或代理给出的反馈
  4. 在循环中迭代直到所有代理审查者满意（这实际上是 Ralph Wiggum Loop）

Codex 直接使用标准开发工具（gh、本地脚本和仓库嵌入的技能）来收集上下文，无需人类复制粘贴到 CLI。人类可以审查 PR，但不是必须的。随着时间的推移，几乎所有审查工作都被推向代理对代理的处理[1:7]。

4.3 应用可观测性 ​

OpenAI 团队将 Chrome DevTools 协议接入代理运行时，创建了处理 DOM 快照、截图和导航的技能。这使得 Codex 能够：

  • 复现 Bug
  • 验证修复
  • 直接对 UI 行为进行推理

同样，日志、指标和追踪通过本地可观测性栈暴露给 Codex。代理可以：

  • 使用 LogQL 查询日志
  • 使用 PromQL 查询指标
  • 验证服务启动是否在 800ms 内完成
  • 确保关键用户旅程中的跨度不超过 2 秒

OpenAI 经常观察到单个 Codex 运行处理单个任务长达 6 小时以上（通常在人类睡觉时）[1:8]。

4.4 关键指标 ​

  • 代码产出：每位开发者每天 3.5+ 个 PR
  • 开发时间：估计以约 1/10 的时间完成了手工编码所需的工作量
  • PR 总量：约 1500 个 PR 在 5 个月内被打开并合并
  • 代码质量：通过持续的垃圾回收保持高质量
  • 技术债务：通过持续小额偿还控制债务累积
  • 开发者满意度：工程师专注于更高阶的工作，满意度提升

5. Harness Engineering 的行业影响 ​

5.1 工程师角色的演变 ​

Harness Engineering 正在改变工程师的工作内容：

传统工程师Harness 工程师
编写代码设计代码生成环境
调试实现调试约束和反馈循环
代码审查Harness 审查
技术决策意图和架构决策
手工重构设计自动化重构代理

正如 Martin Fowler 所描述的，人类工程师从"在循环中（in the loop）"转变为"在循环上（on the loop）"——不再亲自检查代理产生的每个工件，而是改进产生这些工件的 Harness[6]。

5.2 行业最佳实践的收敛 ​

从 OpenAI 到 Stripe，行业正在形成 Harness Engineering 的共识：

Stripe 的实践：Stripe 采用了不同但互补的方法。他们的 Minions 运行在隔离的、预热的"devboxes"中——与人类工程师使用的开发环境相同，但与生产和互联网隔离。代理可以通过 MCP 服务器访问 400 多个内部工具。关键洞察：代理需要与人类工程师相同的上下文和工具，而不是事后附加的集成[7]。

模型是商品，Harness 是护城河：正如评论者所指出的，这不是关于提示工程，而是关于使代理有效的架构思维。大多数团队仍将 AI 视为自动完成工具，而 OpenAI 展示了下一层：工程师作为编排者，而不是打字员[8]。

简单开始：一个好的 AGENTS.md 和预提交钩子比复杂的中间件更有影响力。

构建可撕掉的 Harness：过度工程会在模型改进时失效，保持适应性。

5.3 Symphony：OpenAI 的开源 Harness 框架 ​

2026 年 3 月 5 日，OpenAI 发布了 Symphony，一个用于编排自主 AI 代理的开源框架[9]。

Symphony 的特点：

  • 技术栈：使用 Elixir 和 Erlang/BEAM 运行时构建，专注于容错和并发
  • 配置方式：通过 WORKFLOW.md 文件进行配置，作为开发团队与代理之间的技术契约
  • 工作原理：轮询问题追踪器（如 Linear）识别代理可处理的任务
  • 实现运行生命周期：核心工作单元是实现运行（implementation run），遵循特定序列

这与 GitHub Copilot 的 Jira 编码代理（同一天进入公开预览）以及 Google ADK 的扩展形成了直接竞争，标志着"票据到 PR"愿景的市场正在快速整合[10]。

5.4 对软件工程教育的启示 ​

计算机科学教育可能需要调整课程：

  • 更多关注系统设计和架构
  • 强调约束设计和反馈系统
  • 培养"元编程"思维——编写生成代码的代码

正如一位评论者所说："AI 不会取代工程纪律。它重新定位了纪律。更少时间在代码中。更多时间在系统和结构中。这才是真正的杠杆所在。"[11]

6. 如何开始实践 Harness Engineering ​

6.1 入门步骤 ​

根据 NxCode 的完整指南[12]，入门 Harness Engineering 可以遵循以下步骤：

  1. 定义代理的范围：写下代理应该能做什么和绝不能做什么，成为权限清单

  2. 创建 AGENTS.md：为你的代码库创建一个简单的 AGENTS.md 文件，包含项目概述、架构图和编码规范。将其视为目录而非百科全书

  3. 设置预提交钩子：使用 linter 和代码格式化工具强制执行基本规范。Martin Fowler 建议逐步构建上下文规则文件，不要一开始就塞入太多内容

  4. 定义黄金原则：识别 3-5 条最重要的编码原则，写入代码库。通过机械规则而非微观管理实现来强制执行不变量

  5. 建立反馈循环：设置 CI/CD 流程，让 AI 代理知道代码是否通过测试。最简单的有效反馈循环是"写-测试-修复"循环

6.2 进阶实践 ​

多代理验证系统：像 Antfarm 那样，使用独立的验证代理检查代码质量。Martin Fowler 的实验引入了审查代理来双重检查 AI 的工作是否符合原始提示，这为捕捉错误和确保生成的代码符合需求提供了额外的安全网[13]。

文档一致性代理：让代理负责维护文档与代码的一致性。OpenAI 的"文档园艺"代理定期扫描过时或陈旧的文档，并打开修复 PR

质量等级系统：为代码库模块分配质量等级，优先改进低质量模块

参考应用程序：设置参考应用程序和 MCP（Model Context Protocol）服务器，可以向代理提供示例代码。这确保样本可编译且相互一致

6.3 常见陷阱 ​

过度约束：过多的约束会限制 AI 的创造力，找到平衡点。正如 Birgitta Böckeler 在 Martin Fowler 网站上指出的，提高 AI 生成代码的信任度和可靠性需要约束解决方案空间而不是扩展它[7:1]。

忽视人类审查：完全自动化的流程可能引入难以发现的问题，保持人类在关键决策中的参与。当需要判断时，代理应该升级到人类。

静态 Harness：Harness 需要随着模型能力和项目需求的变化而演进。模型能力在快速提升，半年前需要放入上下文的提示现在可能已经不再需要[14]。

工具透明度：关于上下文有多满以及什么占用了多少空间的透明度是帮助我们在这种平衡中导航的关键功能。

7. 未来展望 ​

7.1 Harness 即服务 ​

未来可能出现专门的 Harness 提供商，为不同技术栈和领域提供预构建的 Harness 模板。随着从 Codex、Claude Code、Cursor 到 LangChain 等各种工具的普及，Harness Engineering 的实践将变得越来越重要。

7.2 自适应 Harness ​

Harness 本身可能由 AI 维护，根据代码库的健康状况和团队反馈自动调整约束和规则。这形成了一种"代理飞轮"（agentic flywheel）：人类指导代理管理和改进 Harness，而不是手工操作[6:1]。

7.3 标准化 ​

AGENTS.md、WORKFLOW.md 等文件格式可能成为行业标准，类似于今天的 Dockerfile 和 docker-compose.yml。AGENTS.md 的倡议网站已经启动，推动这一标准的普及。

7.4 日益增长的自主性 ​

随着更多开发循环被直接编码到系统中——测试、验证、审查、反馈处理和恢复——仓库最近跨越了一个有意义的阈值，Codex 可以端到端地驱动新功能。给定单个提示，代理现在可以：

  • 验证代码库的当前状态
  • 复现报告的 Bug
  • 记录演示失败的视频
  • 实施修复
  • 通过驱动应用程序验证修复
  • 记录演示解决方案的第二段视频
  • 打开 Pull Request
  • 响应代理和人类反馈
  • 检测和修复构建失败
  • 仅在需要判断时升级到人类
  • 合并变更

这种行为严重依赖于仓库的特定结构和工具，至少目前还不能假设它能在没有类似投资的情况下推广[1:9]。

8. 结语：从编码到驯码 ​

Harness Engineering 代表了一种思维转变——从"编写代码"到"驯服代码生成"。在这个新范式中，最优秀的工程师不是写代码最快的人，而是设计最弹性环境的人。

正如 OpenAI 团队所强调的："构建软件仍然需要纪律，但纪律更多地体现在脚手架而非代码中。保持代码库一致性的工具、抽象和反馈循环变得越来越重要。我们现在最困难的挑战集中在设计环境、反馈循环和控制系统上。"[1:10]

这种严谨性的重新定位，正是 Harness Engineering 的核心所在。

AI 不会取代工程师，但使用 Harness Engineering 的工程师会取代不使用它的工程师。你准备好成为 Harness 工程师了吗？

9. 参考资源 ​

  1. https://openai.com/index/harness-engineering/ - OpenAI 官方博客：Harness Engineering: Leveraging Codex in an Agent-First World
  2. https://openai.com/index/unlocking-the-codex-harness/ - OpenAI：Unlocking the Codex harness: how we built the App Server
  3. https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html - Martin Fowler：Harness Engineering
  4. https://martinfowler.com/articles/exploring-gen-ai/context-engineering-coding-agents.html - Martin Fowler：Context Engineering for Coding Agents
  5. https://martinfowler.com/articles/exploring-gen-ai/humans-and-agents.html - Martin Fowler：Humans and Agents in Software Engineering Loops
  6. https://github.com/openai/symphony - OpenAI Symphony 开源框架
  7. https://www.infoq.com/news/2026/02/openai-harness-engineering-codex/ - InfoQ：OpenAI Introduces Harness Engineering
  8. https://www.nxcode.io/resources/news/what-is-harness-engineering-complete-guide-2026 - NxCode：What Is Harness Engineering? Complete Guide

10. 扩展阅读：Ralph Wiggum 循环 ​

OpenAI 在 Harness Engineering 实践中提到了一个有趣的概念——Ralph Wiggum 循环（Ralph Wiggum Loop）。这个名字源自《辛普森一家》中的角色 Ralph Wiggum，代表一种自我验证的循环机制。这个概念由 Geoffrey Huntley 详细阐述[15]。

在 Codex 的工作流程中，代理会：

  1. 审查自己的代码变更
  2. 请求其他代理进行代码审查
  3. 根据反馈进行迭代修改
  4. 直到所有审查者满意为止

这种"代理审查代理"的模式，使得人工审查的需求大幅降低，同时也确保了代码质量。正如 OpenAI 团队所说："随着时间的推移，我们几乎将所有审查工作都推向了代理对代理的处理。"

参考文献 ​

  1. OpenAI. (2026, February 11). Harness engineering: leveraging Codex in an agent-first world. https://openai.com/index/harness-engineering/ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎

  2. The Chosun Ilbo. (2026, March 26). Harness Engineering Emerges as Human Role in AI Coding Era. https://www.chosun.com/english/industry-en/2026/03/26/QEFHIB7ANJFC5A77U3ITLMGHQY/ ↩︎

  3. Martin Fowler. Harness Engineering. https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html ↩︎ ↩︎

  4. InfoQ. (2026, February). OpenAI Introduces Harness Engineering: Codex Agents Generate Software in 1/10th the Time. https://www.infoq.com/news/2026/02/openai-harness-engineering-codex/ ↩︎

  5. Zach Brock. LinkedIn Post on Harness Engineering. https://www.linkedin.com/posts/zbrock_harness-engineering-leveraging-codex-in-activity-7427414884402937857-86xB ↩︎

  6. Martin Fowler. Humans and Agents in Software Engineering Loops. https://martinfowler.com/articles/exploring-gen-ai/humans-and-agents.html ↩︎ ↩︎

  7. Ignorance.ai. The Emerging "Harness Engineering" Playbook. https://www.ignorance.ai/p/the-emerging-harness-engineering ↩︎ ↩︎

  8. Shamel Merchant. LinkedIn Post on Harness Engineering. https://www.linkedin.com/posts/shamelmerchant_harness-engineering-leveraging-codex-in-activity-7428490646602211328--DU6 ↩︎

  9. MarkTechPost. (2026, March 5). OpenAI Releases Symphony: An Open Source Agentic Framework. https://www.marktechpost.com/2026/03/05/openai-releases-symphony-an-open-source-agentic-framework-for-orchestrating-autonomous-ai-agents-through-structured-scalable-implementation-runs/ ↩︎

  10. sjramblings.io. OpenAI Symphony: When AI Agents Run Your Sprint Board. https://sjramblings.io/openai-symphony-autonomous-agent-orchestration/ ↩︎

  11. OpenAI Official LinkedIn. https://www.linkedin.com/posts/openai_harness-engineering-leveraging-codex-in-activity-7427411854349611008-U1PP ↩︎

  12. NxCode. What Is Harness Engineering? Complete Guide for AI Agent Development 2026. https://www.nxcode.io/resources/news/what-is-harness-engineering-complete-guide-2026 ↩︎

  13. Martin Fowler. How far can we push AI autonomy in code generation? https://martinfowler.com/articles/pushing-ai-autonomy.html ↩︎

  14. Martin Fowler. Context Engineering for Coding Agents. https://martinfowler.com/articles/exploring-gen-ai/context-engineering-coding-agents.html ↩︎

  15. Geoffrey Huntley. The Ralph Wiggum Loop. https://ghuntley.com/loop/ ↩︎