OpenAI官方Harness工程实践指南

过去五个月，OpenAI团队进行了一场堪称碘伏性的实验：他们从零开始，构建并发布了一款内部Beta版软件产品，而整个过程，没有手动编写一行代码。

这款产品拥有内部日常用户和外部Alpha测试者，会经历发布、部署、崩溃和修复的完整生命周期。其独特之处在于，从应用逻辑、测试、持续集成配置，到文档、可观测性工具和内部脚本——总计约百万行代码，全部由OpenAI自家的编程模型Codex生成。据团队估算，完成这项工作所花费的时间，大约只有传统手工编码方式的十分之一。

人类负责掌舵，Agent负责执行。

这个看似极端的限制，是团队有意为之。他们想借此逼迫自己构建一套必要的基础设施，从而将工程效率提升几个数量级。面对在几周内交付百万行代码的挑战，核心问题变成了：当一个软件工程团队的核心任务不再是写代码，而是设计环境、明确意图、构建反馈循环，以确保AI Agent能可靠工作时，一切会变成什么样？

这篇文章，正是他们与AI Agent团队共同打造新产品过程中，所积累的一手经验：哪些地方曾崩溃，哪些做法产生了复利效应，以及如何最大化人类工程师最宝贵的资源——时间和注意力。

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

故事始于2025年8月下旬，一个空荡荡的Git仓库迎来了它的首次提交。

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

这里没有任何预先存在的人类代码作为“锚点”。从一开始，这个仓库的基因就由Agent塑造。

五个月后，这个仓库已经容纳了大约一百万行代码，覆盖了应用逻辑、基础设施、工具、文档和内部开发工具。在此期间，一个最初仅由三名工程师组成的团队，驱动Codex开启并合并了大约1500个拉取请求（PR）。这相当于每位工程师平均每天处理3.5个PR。更令人惊讶的是，当团队扩展到七名工程师后，这个吞吐量还在持续增加。重要的是，这并非为了堆砌代码而堆砌：该产品已被数百名内部用户实际使用，其中包括高粘性的日常用户。

在整个过程中，人类从未直接贡献过任何代码行。这成为了团队的铁律：零手动编码。

重新定义工程师的角色

当亲手写代码的环节消失，一种新型的工程工作便浮现出来，其重点转向了系统、脚手架和杠杆效应。

早期的进展比预想的要慢，但这并非因为Codex能力不足，而是因为环境不够清晰。Agent缺乏朝着高级目标迈进所需的工具、抽象和内部结构。于是，工程团队的首要工作变成了赋能Agent，让它能完成有用的工作。

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

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

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

提高应用程序的可读性

随着代码吞吐量的激增，瓶颈变成了人类的质量保证（QA）能力。既然固定的限制始终是人类的时间和注意力，团队便开始致力于让应用界面、日志和应用指标本身对Codex直接可见且可理解，从而为Agent赋予更多能力。

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

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

团队经常观察到，单次Codex运行能在一个任务上连续工作长达六个小时（通常是在人类工程师睡觉的时候）。

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

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

• 上下文是稀缺资源。 庞大的指令文件会挤占任务、代码和相关文档的空间——结果就是，Agent要么错过关键约束，要么开始针对错误的目标进行优化。
• 过多的指导等于没有指导。 当一切都“很重要”时，就意味着没有什么是真正重要的。Agent最终只会在局部进行模式匹配，而不是有意识地进行全局导航。
• 它会瞬间腐烂。 一个庞大单一的说明书会变成过时规则的坟墓。Agent无法分辨哪些规则仍然有效，人类也停止了维护，这份文件悄然变成了一个诱人的陷阱。
• 它很难被验证。 单一的文本块不适合进行机械检查（覆盖率、新鲜度、所有权、交叉链接），因此偏离是不可避免的。

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

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

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

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

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

团队通过机制来强制执行这一点。专用的代码检查工具和CI任务会验证知识库是否最新、交叉链接是否有效以及结构是否正确。一个定期运行的“文档园丁”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。

强制执行架构与品味

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

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

这种架构通常是你推迟到拥有数百名工程师时才会考虑的。但在编码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承担软件生命周期中越来越大的部分，这些问题将变得更加重要。希望这些早期的经验教训，能帮助大家思考应该把精力投入在哪里，从而让你只需专注构建事物本身。