OpenAI 官方分享：Harness工程

本文是来自 OpenAI 官方blog的真实工程实践分享。

在过去的五个月里，他们做了一个非常有趣的实验：完全不靠人类手写一行代码，只依靠自家的 Codex Agent，做出了一个包含上百万行代码的真实软件产品。

这篇文章详细记录了他们是怎么做到这一点的。当程序员不再需要亲自写代码，而是变成给 AI 搭建环境、定规则、建反馈循环的人时，整个开发流程会发生什么变化？他们遇到了哪些坑，又摸索出了哪些好用的方法？

从提示词（Prompt）工程到上下文（Context）工程再到Harness工程，这篇一线的经验分享非常有参考价值。

原文链接：https://openai.com/index/harness-engineering/

以下是全文翻译

过去五个月里，我们的团队一直在进行一项实验：构建并发布一款软件产品的内部 Beta 版，而其中手动编写的代码为 0 行。

该产品有内部的日常用户和外部的 Alpha 测试人员。它会发布、部署、崩溃并被修复。与众不同的是，每一行代码——应用逻辑、测试、CI（持续集成）配置、文档、可观测性以及内部工具——都由 Codex（OpenAI 开发的编程模型）编写。据我们估计，构建这款产品所花的时间大约只有手动编写代码的十分之一。

人类掌舵。Agent 执行。

我们刻意选择了这种限制，借此迫使自己去构建必要的基础设施，从而将工程速度提升几个数量级。我们只有几周的时间来交付最终高达上百万行的代码。为此，我们需要弄清楚，当一个软件工程团队的主要工作不再是写代码，而是设计环境、指定意图以及构建反馈循环，让 Codex Agent 能够可靠地工作时，事情会发生怎样的改变。

这篇文章讲述了我们与一个 Agent 团队共同构建全新产品时学到的经验——什么崩溃了，什么产生了复利效应，以及如何最大化我们唯一真正稀缺的资源：人类的时间和注意力。

我们从一个空的 Git 仓库开始

向空仓库的首次提交发生在 2025 年 8 月下旬。

初始的脚手架——仓库结构、CI 配置、格式化规则、包管理器设置和应用框架——是由 Codex CLI 结合 GPT-5，在少量现有模板的引导下生成的。甚至连指导 Agent 如何在仓库中工作的初始 AGENTS.md 文件本身也是由 Codex 编写的。

没有任何预先存在的人类编写的代码来锚定这个系统。从一开始，这个仓库就是由 Agent 塑造的。

五个月后，该仓库包含大约一百万行代码，涵盖应用逻辑、基础设施、工具、文档和内部开发者实用程序。在此期间，由仅有三名工程师组成的小团队驱动 Codex，开启并合并了大约 1,500 个 PR（Pull Request，拉取请求）。这相当于每位工程师每天平均处理 3.5 个 PR，令人惊讶的是，随着团队扩展到现在的七名工程师，这个吞吐量还在增加。重要的是，这并非为了输出而输出：该产品已被数百名内部用户使用，包括日常的内部重度用户。

在整个开发过程中，人类从未直接贡献过任何代码。这成为了团队的核心理念：零手动编写代码。

重新定义工程师的角色

缺乏人类亲手编写代码的环节，引入了一种不同类型的工程工作，其重点在于系统、脚手架和杠杆效能。

早期的进展比我们预期的要慢，这不是因为 Codex 能力不足，而是因为环境不够明确。Agent 缺乏朝着高级目标迈进所需的工具、抽象和内部结构。我们工程团队的首要工作变成了赋能 Agent 去做有用的工作。

在实践中，这意味着采用深度优先的工作方式：将大目标分解为较小的构建块（设计、代码、审查、测试等），提示 Agent 构建这些块，并利用它们来解锁更复杂的任务。当某项工作失败时，解决办法几乎从不是让它“再努力一点”。因为取得进展的唯一方法是让 Codex 去完成工作，人类工程师总是会介入任务并思考：“缺失了什么能力，我们如何让这种能力对 Agent 而言既清晰易懂又具有强制性？”

人类几乎完全通过提示词（Prompt）与系统进行交互：工程师描述一个任务，运行 Agent，并让它打开一个 PR。为了推动一个 PR 完成，我们指示 Codex 在本地审查自己的更改，并在本地和云端请求特定的其他 Agent 审查，对任何人类或 Agent 给出的反馈做出回应，并在循环中不断迭代，直到所有 Agent 审查者都满意为止（实际上这是一个 Ralph Wiggum Loop）。Codex 直接使用我们的标准开发工具（gh 命令行工具、本地脚本和内置于仓库的技能）来收集上下文，无需人类在 CLI 中复制和粘贴。

人类可以审查 PR，但这不是必需的。随着时间的推移，我们已将几乎所有的审查工作交由 Agent 之间（agent-to-agent）来处理。

提高应用程序的可读性

随着代码吞吐量的增加，我们的瓶颈变成了人类的 QA（质量保证）能力。由于固定的限制一直是人类的时间和注意力，我们致力于通过让应用 UI、日志和应用指标本身对 Codex 直接可见且易懂（legible），从而为 Agent 添加更多能力。

例如，我们让应用可以基于每个 Git 工作树（worktree）启动，这样 Codex 就可以为每次更改启动并驱动一个实例。我们还将 Chrome DevTools Protocol 接入到 Agent 运行时中，并创建了处理 DOM 快照、截图和导航的技能。这使 Codex 能够重现错误、验证修复，并直接推理 UI 行为。

MCP 驱动应用程序以验证其工作”。Codex 选择一个目标，在触发 UI 路径之前和之后对状态进行快照，通过 Chrome DevTools 观察运行时事件，应用修复，重新启动，并循环重新运行验证，直到应用程序变得干净无误。" class="rich_pages wxw-img" data-ratio="0.975925925925926" data-type="jpeg" data-w="1080" style="max-width: 100%;max-height: 600px !important;height: auto;display: block;margin: 24px auto;border-radius: 6px;" data-imgfileid="100000592" data-aistatus="1">

我们对可观测性工具做了同样的处理。日志、指标和链路追踪通过本地的可观测性技术栈暴露给 Codex，该技术栈对于任何给定的工作树都是短暂存在的。Codex 在该应用的一个完全隔离的版本上工作——包括其日志和指标，这些在任务完成后就会被销毁。Agent 可以使用 LogQL 查询日志，使用 PromQL 查询指标。有了这些上下文，像“确保服务在 800 毫秒内完成启动”或“这四个关键用户旅程中的任何跨度不得超过两秒”这样的提示词就变得可以处理了。

我们经常看到单次 Codex 运行会在一个任务上连续工作长达六个小时（通常是在人类睡觉的时候）。

我们将仓库知识作为记录系统

上下文管理是让 Agent 在处理庞大且复杂的任务时保持高效的最大挑战之一。我们最早学到的经验之一很简单：给 Codex 一张地图，而不是一本 1,000 页的说明手册。

• 上下文是一种稀缺资源。 巨大的指令文件会挤占任务、代码和相关文档的空间——因此 Agent 要么会错过关键约束，要么开始针对错误的目标进行优化。

• 过多的指导就等于“没有指导”。 当一切都“很重要”时，就意味着没有什么是真正重要的。Agent 最终只会在局部进行模式匹配，而不是有意识地去导航。

• 它会瞬间腐烂。 一个庞大单一的手册会变成过时规则的坟墓。Agent 无法分辨哪些规则仍然有效，人类也停止了维护，这份文件悄然变成了一个诱人的陷阱。

• 它很难被验证。 单一的文本块不适合进行机械检查（覆盖率、新鲜度、所有权、交叉链接），因此偏离是不可避免的。

因此，我们不再将 AGENTS.md 视为百科全书，而是将其视为目录。

仓库的知识库位于结构化的 docs/ 目录中，被视为事实记录系统。一个简短的 AGENTS.md（大约 100 行）被注入到上下文中，主要充当地图的作用，指向其他地方更深层次的事实来源。

仓库内的知识存储布局。

设计文档被分类并建立索引，包括验证状态和一套定义 Agent 优先操作原则的核心理念。架构文档提供了领域和包分层的顶层地图。一份质量文档对每个产品领域和架构层进行评分，随着时间的推移跟踪存在的问题。

计划（Plans）被视为一等公民。短暂的轻量级计划用于小规模的更改，而复杂的工作则被记录在执行计划中，并带有进度和决策日志，这些记录会被提交到仓库中。进行中的计划、已完成的计划和已知的技术债务都经过版本控制并存放在一起，使得 Agent 能够在不依赖外部上下文的情况下进行操作。

这实现了渐进式披露：Agent 从一个小而稳定的切入点开始，并被告知接下来去哪里寻找信息，而不是一开始就被海量信息淹没。

我们通过机制来强制执行这一点。专用的代码检查工具（linters）和 CI 任务会验证知识库是否最新、交叉链接是否有效以及结构是否正确。一个定期运行的“文档园丁（doc-gardening）”Agent 会扫描那些不能反映真实代码行为的过时或废弃文档，并开启修复性的 PR。

Agent 可读性是终极目标

随着代码库的演进，Codex 的设计决策框架也需要随之演进。

因为该仓库完全是由 Agent 生成的，所以它首先针对 Codex 的可读性进行了优化。就像团队致力于为新入职的工程师提高代码的可导航性一样，我们人类工程师的目标是让 Agent 能够直接从仓库本身推理出完整的业务领域。

从 Agent 的角度来看，任何它在运行时无法在上下文中访问的内容，实际上就是不存在的。存在于 Google Docs、聊天记录或人类大脑中的知识，系统是无法访问的。它能看到的只有仓库本地的、受版本控制的产物（例如代码、Markdown 文档、Schema、可执行计划）。

我们认识到，随着时间的推移，我们需要将越来越多的上下文推送到仓库中。那场让团队在架构模式上达成一致的 Slack 讨论？如果 Agent 无法发现它，它就变得不可读了，就像三个月后加入的新员工对它一无所知一样。

给 Codex 更多的上下文意味着要组织和暴露正确的信息，以便 Agent 能够对其进行推理，而不是用临时的指令淹没它。就像你会向新团队成员介绍产品原则、工程规范和团队文化（包括对表情符号的偏好）一样，将这些信息提供给 Agent 会带来更加对齐的输出。

这种框架澄清了许多权衡。我们倾向于使用可以完全被内部化并在仓库中推理的依赖项和抽象。那些通常被称为“无聊”的技术往往更容易被 Agent 建模，因为它们具有更好的可组合性、API 稳定性和在训练集中的高覆盖率。在某些情况下，让 Agent 重新实现部分功能，甚至比去应对公共库中不透明的上游行为成本更低。例如，我们没有引入类似于 p-limit 的通用包，而是实现了一个自己的并发映射辅助工具：它与我们的 OpenTelemetry 埋点紧密集成，拥有 100% 的测试覆盖率，并且其行为完全符合我们运行时的预期。

将系统的更多部分转变为 Agent 可以直接检查、验证和修改的形式，可以增加杠杆效能——这不仅是为了 Codex，也是为了正在该代码库上工作的其他 Agent（例如 Aardvark）。

强制执行架构与品味

仅仅依靠文档并不能保持一个完全由 Agent 生成的代码库的连贯性。通过强制执行不变量，而不是微观管理实现细节，我们让 Agent 在不破坏基础的前提下快速交付。例如，我们要求 Codex 在边界处解析数据形状（parse data shapes at the boundary），但不规定具体如何实现（模型似乎喜欢用 Zod，但我们并没有指定那个特定的库）。

Agent 在具有严格边界和可预测结构的环境中最有效，因此我们围绕严格的架构模型构建了该应用程序。每个业务领域都被划分为一组固定的层，具有经过严格验证的依赖方向和一组有限的允许边缘。这些约束通过自定义的代码检查工具（当然也是 Codex 生成的！）和结构测试被机械地强制执行。

下面的图表展示了这个规则：在每个业务领域（例如应用设置）内，代码只能通过一组固定的层（Types → Config → Repo → Service → Runtime → UI）“向前”依赖。横切关注点（如认证、连接器、遥测、特性开关）通过一个单一的显式接口进入：Providers。任何其他操作都是被禁止的，并且会被机械地强制执行。

这种架构通常是你推迟到拥有数百名工程师时才会考虑的。但在编码 Agent 时代，它是早期的先决条件：正是这些约束条件使得开发能够保持高速，而不会导致代码腐烂或架构漂移。

在实践中，我们通过自定义检查工具和结构测试，加上一小组“品味不变量”来强制执行这些规则。例如，我们静态地强制执行结构化日志记录、Schema 和类型的命名约定、文件大小限制，以及通过自定义检查来满足特定平台的可靠性要求。由于这些检查是自定义的，我们在编写错误消息时，会将修复说明注入到 Agent 的上下文中。

在以人类优先的工作流中，这些规则可能会让人觉得迂腐或受到限制。但在 Agent 环境下，它们变成了乘数：一旦编码，它们就会同时应用于所有地方。

同时，我们会明确哪些地方的约束很重要，哪些地方则不然。这有点像领导一个庞大的工程平台组织：集中强制执行边界，允许局部自治。你非常关心边界、正确性和可复现性。但在这些边界内，你允许团队（或 Agent）在如何表达解决方案方面享有很大的自由。

最终生成的代码并不总是符合人类的代码风格偏好，这没关系。只要输出是正确的、可维护的，并且对于未来运行的 Agent 是可读的，它就达到了标准。

人类的品味会持续反馈到系统中。审查评论、重构 PR 以及面向用户的错误，都会被捕获为文档更新或直接编码到工具中。当文档不足以起作用时，我们会将该规则直接提升为代码强制执行。

吞吐量改变了代码合并哲学

随着 Codex 吞吐量的增加，许多传统的工程规范变得适得其反。

该仓库在运行中采用了最小化阻断合并的关卡。PR 的生命周期很短。测试中的偶发性失败通常通过后续的运行来解决，而不是无限期地阻断进展。在一个 Agent 吞吐量远远超过人类关注度的系统中，纠正错误的成本很低，而等待的成本却很高。

这在低吞吐量的环境中是不负责任的。但在我们这里，这通常是正确的权衡。

“Agent 生成”到底意味着什么

当我们说代码库是由 Codex Agent 生成时，我们指的是代码库中的所有内容。

Agent 会产出：

• 产品代码和测试

• CI 配置和发布工具

• 内部开发者工具

• 文档和设计历史

• 评估测试工具

• 审查评论和回应

• 管理仓库本身的脚本

• 生产环境仪表盘定义文件

人类始终保持在闭环中，但工作在与以往不同的抽象层级上。我们对工作进行优先级排序，将用户反馈转化为验收标准，并验证结果。当 Agent 遇到困难时，我们将其视为一个信号：识别缺少了什么——工具、护栏、文档——然后将其反馈回仓库，这个过程始终是让 Codex 自己编写修复。

Agent 直接使用我们的标准开发工具。它们会拉取审查反馈，进行内联回应，推送更新，并经常执行合并提交（squash and merge）它们自己的 PR。

不断提高的自治水平

随着越来越多的开发循环被直接编码到系统中——测试、验证、审查、反馈处理和恢复——这个仓库最近跨过了一个重要的门槛：Codex 现在可以端到端地驱动一个新特性的开发。

只需一个提示词，Agent 现在就可以：

• 验证代码库的当前状态

• 重现报告的错误

• 录制一个展示该失败的视频

• 实施修复

• 通过驱动应用程序验证修复效果

• 录制第二个视频以展示问题已解决

• 开启一个 PR

• 响应 Agent 和人类的反馈

• 检测并修复构建失败

• 仅在需要人类判断时才向上升级报告

• 合并更改

这种行为在很大程度上依赖于这个仓库的特定结构和工具，因此不应假设在没有同等投资的情况下也能泛化——至少，现在还不能。

熵与垃圾回收

完全的 Agent 自治也引入了新的问题。 Codex 会复制仓库中已经存在的模式——甚至是那些参差不齐或次优的模式。随着时间的推移，这不可避免地会导致代码偏离规范。

最初，人类只能手动解决这个问题。我们的团队过去每个星期五（占工作周的 20%）都要花时间清理“AI 垃圾”。不出所料，这种方式无法规模化。

取而代之的是，我们开始将我们称之为“黄金原则”的东西直接编码到仓库中，并构建了一个定期循环的清理流程。这些原则是带有强烈倾向性、机械式的规则，旨在保持代码库清晰，并保证未来的 Agent 运行具有一致性。例如：（1）我们更喜欢共享的实用工具包，而不是手写的辅助函数，以此将不变量保持在中心位置；（2）我们绝不使用“YOLO 式”的数据探测——我们验证边界或依赖强类型的 SDK，以防止 Agent 意外地在猜测的数据结构上进行构建。我们会按照固定节奏运行一组后台 Codex 任务，扫描代码库的偏差，更新质量评分，并开启针对性的重构 PR。其中大部分检查可以在一分钟内完成审查并自动合并。

这就像垃圾回收一样。技术债务就像高息贷款：不断以小额增量偿还，几乎总是好过让它不断复利、最后不得不痛苦地一次性解决。人类的品味被捕获一次，然后不断地强制应用到每一行代码上。这也让我们能够每天捕获并解决不良模式，而不是让它们在代码库中蔓延数天或数周。

我们仍在学习的内容

到目前为止，这种策略在 OpenAI 内部的发布和采用方面非常成功。为真实用户构建真实的产品，有助于将我们的投资扎根于现实，并引导我们走向长期的可维护性。

我们目前还不知道在完全由 Agent 生成的系统中，架构连贯性会如何在数年的时间里演变。我们仍在探索人类判断在何处能带来最大的杠杆效能，以及如何对这种判断进行编码，使其产生复利效应。我们也不知道随着时间的推移、模型变得越来越强大，这个系统将如何演变。

但有一点变得很清晰：构建软件仍然需要纪律，只不过这种纪律更多地体现在脚手架而不是代码中。保持代码库连贯的工具、抽象和反馈循环正变得越来越重要。

我们现在面临的最困难的挑战集中在设计环境、反馈循环和控制系统上，这些系统可以帮助 Agent 实现我们的目标：规模化地构建和维护复杂、可靠的软件。

随着像 Codex 这样的 Agent 承担软件生命周期中越来越大的部分，这些问题将变得更加重要。我们希望分享一些早期的经验教训能够帮助大家思考应该把精力投入在哪里，从而让你只需专注构建事物。