驾驭工程：在智能体优先（Agent-first）的世界中发挥 Codex 的作用

作者：Ryan Lopopolo，技术团队成员 2026 年 2 月 11 日

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

这款产品有内部的日常用户，也有外部的 Alpha 测试者。它会发布、部署、出 Bug，然后被修复。与众不同的是，这里面的每一行代码——从应用逻辑、测试、CI（持续集成）配置、文档、可观测性，到内部工具——全部都是由 Codex 编写的。我们估计，构建出这个产品所花费的时间，只有人工编写代码所需时间的十分之一。

人类负责掌舵。智能体负责执行。 (Humans steer. Agents execute.)

我们刻意选择了这一限制条件，目的就是为了逼迫自己去构建必要的基础设施，从而实现工程开发速度数量级的提升。我们当时只有几周的时间，却要交付最终多达上百万行代码的项目。为了实现这一目标，我们需要搞清楚：当一个软件工程团队的首要工作不再是写代码，而是设计环境、明确意图并构建反馈循环，从而让 Codex 智能体能够可靠地开展工作时，一切会发生怎样的变化。

这篇文章记录了我们在与一个智能体团队共同从零构建一款全新产品时学到的经验——包括哪些做法失败了，哪些做法产生了复利效应，以及我们该如何最大化地利用我们唯一真正稀缺的资源：人类的时间与注意力。

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

向空仓库提交的第一行代码发生在了 2025 年 8 月底。

最初的脚手架（Scaffold）——仓库结构、CI 配置、格式化规则、包管理器设置以及应用程序框架——是由带有 GPT-5 模型的 Codex CLI 基于一小套现有模板生成的。甚至连指导智能体如何在仓库中开展工作的初始 AGENTS.md 文件本身，也是由 Codex 编写的。

不存在任何预先人工编写的代码来作为系统的锚点。从一开始，整个仓库的形态就是由智能体塑造的。

五个月后，该仓库已经包含了大约一百万行代码，涵盖了应用程序逻辑、基础设施、工具、文档以及内部开发者实用工具。在那段期间，由于一个小型的由三名工程师组成的团队驱动着 Codex，大约有 1500 个 PR（Pull Requests）被开启并合并。这意味着平均每位工程师每天能处理 3.5 个 PR，而且令人惊讶的是，随着团队规模如今扩大到七名工程师，吞吐量反而增加了。重要的是，这并非为了产出而产出：这款产品已经被数百名内部用户使用，其中不乏内部的重度日常用户。

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

重新定义工程师的角色

由于无需亲手编写代码，一种截然不同的工程工作方式被引入进来，它的重心变成了系统、脚手架和杠杆效能。

前期的进展比我们预想的要慢，这并非是因为 Codex 能力不行，而是因为环境中的规范不够明确。智能体缺乏在推进高级目标时所需的工具、抽象和内部结构。于是，我们工程团队的首要工作就变成了使智能体能够去做有用的工作。

在实践中，这意味着采用深度优先的工作方式：将宏大的目标拆解成较小的构建块（设计、编码、审查、测试等），通过 Prompt 提示智能体去构建这些模块，然后利用它们来解锁更复杂的任务。当出现故障时，解决办法几乎从不该是“再努力试一次”。因为取得进展的唯一方法是让 Codex 去完成工作，所以人类工程师总是会介入任务并扪心自问：“这里缺少了哪种能力？我们如何才能让这种能力对智能体既清晰易读（legible），又能够被强制执行（enforceable）？”

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

人类可以去审查 Pull Request，但这并非是必需的。随着时间的推移，我们已经将几乎所有的审查工作推向了“智能体对智能体（agent-to-agent）”的模式。

随着代码吞吐量的增加，我们的瓶颈变成了人类 QA（质量保证）的能力。因为固定的限制因素一直是人类的时间和注意力，所以我们努力为智能体添加更多的功能，让诸如应用程序 UI、日志和应用指标等内容本身能够直接被 Codex 所“阅读”。

例如，我们使应用程序能够按 Git worktree 启动，这样 Codex 就可以启动并驱动针对每一次更改的一个独立实例。我们还将 Chrome DevTools 协议（CDP）接入了智能体运行时，并创建了用于处理 DOM 快照、屏幕截图和页面导航的技能（skills）。这使得 Codex 能够重现 Bug、验证修复结果，并直接对 UI 行为进行推理。

我们在可观测性工具上也做了同样的事情。通过为任意给定的 worktree 提供的一个临时本地可观测性技术栈，日志、指标和链路追踪都暴露给了 Codex。Codex 在该应用程序的一个完全隔离的版本上工作——包括其对应的日志和指标，一旦任务完成，它们就会被销毁。智能体可以使用 LogQL 查询日志，使用 PromQL 查询指标。有了这些可用的上下文，像“确保服务在 800 毫秒内启动完毕”或“在这些关键的四个用户旅程中，没有任何链路追踪跨度（span）超过两秒”这样的 Prompt 提示便成为了可能。

我们经常看到，单次运行的 Codex 为了某项单一任务，可以连续工作长达 6 个小时以上（通常这还是在人类睡觉的时候）。

提高应用程序的可读性

让智能体在庞大且复杂的任务中发挥作用，最大的挑战之一在于上下文管理。我们最早学到的经验之一非常简单：给 Codex 一张地图，而不是一本 1000 页的说明手册。

我们曾尝试过使用“一个庞大的 AGENTS.md 文件”的方法。不出所料，它失败了：

• 上下文是一种稀缺资源。 巨大的指令文件挤占了用于存放任务、代码和相关文档的上下文空间——这导致智能体要么错过了关键的限制条件，要么开始针对错误的目标进行优化。
• 过多的指导等同于没有指导。 当每件事都是“重点”时，就没有重点了。智能体最终只会陷入局部的模式匹配（pattern-matching），而不是有目的地进行导航。
• 它会瞬间腐化失效。 大一统的手册很快就会变成过时规则的墓地。智能体无法分辨哪些内容依然真实有效，人类也停止了维护，这个文件悄无声息地变成了一个“诱人的陷阱”。
• 难以验证。 单一的代码块不容易进行机械式的检查（比如覆盖率、新鲜度、归属权、交叉链接等），所以内容的偏离漂移（drift）是不可避免的。

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

我们让仓库知识成为了唯一的记录系统

该仓库的知识库位于一个结构化的 docs/ 目录中，它被视为系统的数据源/唯一记录系统（System of record）。一份简短的 AGENTS.md（大约 100 行）被注入到上下文中，它主要充当地图的作用，其中的指针指向位于其他位置的、更深层次的真相源。

AGENTS.md
ARCHITECTURE.md
docs/
├── design-docs/
│ ├── index.md
│ ├── core-beliefs.md
│ └── ...
├── exec-plans/
│ ├── active/
│ ├── completed/
│ └── tech-debt-tracker.md
├── generated/
│ └── db-schema.md
├── product-specs/
│ ├── index.md
│ ├── new-user-onboarding.md
│ └── ...
├── references/
│ ├── design-system-reference-llms.txt
│ ├── nixpacks-llms.txt
│ ├── uv-llms.txt
│ └── ...
├── DESIGN.md
├── FRONTEND.md
├── PLANS.md
├── PRODUCT_SENSE.md
├── QUALITY_SCORE.md
├── RELIABILITY.md
└── SECURITY.md

设计文档经过了归类和索引，包括验证状态和一组定义智能体优先操作原则的核心信念（core beliefs）。架构文档提供了域和包分层的顶层视图映射。一份质量评估文档对每个产品域和架构层进行评分，追踪随时间推移而产生的差距。

计划（Plans）被视为一等公民的产物。临时的轻量级计划用于微小的更改，而复杂的工作则被记录在执行计划中，附带将被检入（checked into）代码仓库的进度和决策日志。进行中的计划、已完成的计划以及已知的技术债都会被进行版本控制并放在一起，这使得智能体在运作时无需依赖外部上下文。

这就实现了渐进式信息披露（Progressive disclosure）：智能体从一个微小而稳定的入口点开始，并被告知接下来应该去哪里寻找信息，而不是一上来就被巨量信息淹没。

我们在机制上强制执行这一点。专门的 Linter（代码检查工具）和 CI 任务会验证知识库是否处于最新状态、交叉链接是否正确以及结构是否合理。一个周期性的“文档园丁”智能体会扫描那些不能反映真实代码行为的过时或陈旧文档，并开启修复性的 Pull Request。

智能体的可读性是我们的目标

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

因为这个代码仓库完全是由智能体生成的，所以它首先针对的是 Codex 的可读性（legibility）进行优化的。就像团队旨在为新入职的工程师提高代码的易导航性一样，我们人类工程师的目标是让智能体能够直接从代码仓库本身去推理完整的业务领域。

从智能体的角度来看，任何它在运行时无法在上下文内访问到的东西，实际上就等同于不存在。存在于 Google Docs、聊天记录线程或人们脑海中的知识，系统是无法获取的。仓库本地的、经过版本控制的文件产物（例如代码、Markdown 文件、Schema 模型、可执行的计划等）是它唯一能看到的东西。

我们意识到，随着时间的推移，我们需要将越来越多的上下文推送进仓库中。比如那段在 Slack 上让团队就某个架构模式达成一致的讨论？如果智能体无法发现它，那么这就属于“不可读”的范畴——这就跟一个三个月后才加入团队的新员工对此一无所知是一样的。

给 Codex 提供更多的上下文，意味着我们需要组织和暴露正确的信息，以便智能体能够在其之上进行推理，而不是用大量随意的、特定情况的指令去淹没它。这就好比你要给一位新队友培训产品原则、工程规范和团队文化（包括对表情符号的偏好），把这些信息提供给智能体同样会引导出更加符合要求的结果产出。

这种框架澄清了许多权衡取舍。我们倾向于使用能够完全在仓库内被内部化并进行推理的依赖项和抽象概念。通常被称为“乏味（boring）”的技术，往往更容易让智能体去建模，因为它们具有可组合性、API 稳定性以及在训练数据集中有更好的覆盖率。在某些情况下，让智能体去重新实现部分功能，也比去想办法绕过公共库中那些不透明的底层行为要来得成本更低。

将系统更多的部分提取出来，转化为智能体可以直接检查、验证和修改的形式，这不仅增加了 Codex 的杠杆效能，也方便了在代码库上工作的其他智能体（例如 Aardvark）。

强制执行架构规范与品味

单靠文档并不能保持一个完全由智能体生成的代码库的一致性。通过强制设定不变的原则（invariants），而不是去微观管理实现细节，我们让智能体能够快速交付，同时又不会破坏基础架构。

智能体在具备严格边界和可预测结构的环境中最有效，因此我们围绕一个严谨的架构模型构建了这款应用。每个业务领域都被划分为一组固定的层级，并对依赖方向进行了严格的验证，只允许有限的边（edges）交互。这些限制是通过定制的 Linter（当然，它们也是由 Codex 生成的！）和结构化测试来被机械地强制执行的。

下图展示了这一规则：在每个业务领域（如 App Settings）内，代码只能沿着一组固定的层级“向前”依赖（Types → Config → Repo → Service → Runtime → UI）。跨领域关注点（认证、连接器、遥测、特性开关）只通过一个单一的显式接口（Providers）进入。其他任何做法都是被禁止的，并会被机械化地强制拦截。

这种架构通常是在你拥有数百名工程师时才会去考虑实施的。但在使用编程智能体时，它却成了前期的必备条件：正是有了这些限制，才保证了在快速开发时不会发生代码腐化或架构漂移（drift）。

在实践中，我们通过自定义的 Linter、结构化测试以及一小套“品味原则（taste invariants）”来执行这些规则。例如，我们静态地强制实施结构化日志记录、Schema 和类型的命名约定、文件大小限制，以及针对特定平台的可靠性要求。由于 Linter 是自定义的，所以我们会专门编写错误信息，从而将补救说明直接注入到智能体的上下文中。

在以人类为中心的工作流中，这些规则可能会让人觉得迂腐或受到束缚。但对于智能体而言，它们成了倍增器：一旦被编码下来，它们就能同时应用于所有地方。

这也类似于领导一个庞大的工程平台组织：中央强制执行边界，局部允许自治。你非常关心边界、正确性和可复现性。但在这些边界之内，你允许团队——或者智能体——在表达解决方案时拥有极大的自由。

生成的代码并不总是符合人类的风格偏好，但这也没关系。只要输出的代码是正确的、可维护的，并且对未来的智能体运行来说具有可读性，它就达到了标准。

人类的品味（Taste）会被持续不断地反馈回系统中。代码审查评论、代码重构 PR 以及面向用户的 Bug，都会被作为文档的更新保存下来，或者直接被编码进工具当中。当文字文档的约束力不够时，我们就会将规则直接固化成代码。

吞吐量改变了合并哲学

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

仓库的运行中只有极少部分会造成阻塞的合并关卡（blocking merge gates）。Pull Request 是短命的。测试用例的不稳定（Test flakes）通常会在后续运行中直接处理，而不是去无限期地阻碍开发进度。在一个智能体的吞吐量远远超过人类注意力的系统里，纠正错误的成本是非常低廉的，而等待的成本才是高昂的。

如果在低吞吐量的环境下这样做，那是极不负责任的。但在这种环境下，它往往成为了正确的权衡。

所谓的“由智能体生成”究竟意味着什么

当我们说代码库是由 Codex 智能体生成的时，我们的意思是：代码库里的所有内容。

智能体会生成：

• 产品代码和测试用例
• CI 配置文件和发布工具
• 内部开发者工具
• 文档和设计历史记录
• 评估脚手架（Evaluation harnesses）
• 代码审查评论及其回复
• 用于管理代码仓库本身的脚本
• 生产环境仪表板的定义文件

人类始终在环（in the loop），但工作在一种我们以前从未接触过的、截然不同的抽象层级上。我们负责划分工作的优先级，将用户反馈转化为验收标准，并验证结果。当智能体陷入困境时，我们将其视为一种信号：找出缺少了什么——是工具、护栏，还是文档——然后将它反馈到仓库中，而且做法永远是让 Codex 自己去编写修复方案。

智能体会直接使用我们的标准开发工具。它们会拉取审查意见、进行内联回复、推送更新，并经常主动将它们自己的 Pull Request 压缩并合并掉。

不断提高的自主性水平

随着越来越多的开发循环被直接编码到了系统中——包括测试、验证、审查、反馈处理和故障恢复——这个仓库最近跨越了一个有意义的门槛：Codex 已经能够端到端（end-to-end）地驱动一个新特性的开发。

只要给出一个单独的 Prompt，智能体现在可以：

• 验证代码库的当前状态
• 重现报告出的 Bug
• 录制一段演示该故障的视频
• 实现修复方案
• 通过驱动应用程序来验证修复结果
• 录制第二段演示问题已解决的视频
• 开启 Pull Request
• 对来自智能体和人类的反馈进行回复
• 侦测并补救构建（build）过程中的失败问题
• 只有在需要做出复杂判断时，才会升级上报给人类
• 合并代码更改

不过，这种行为极度依赖于这个仓库的特定结构和工具生态，目前还不能假设在没有类似投入的情况下，它能够轻易推广到其他地方——至少现在还不行。

熵增与垃圾回收

完全的智能体自主性也引入了一些新颖的问题。Codex 会去复制仓库中已经存在的模式——即使是那些参差不齐或者次优的模式。随着时间的推移，这就不可避免地会导致代码漂移（drift）。

最初，人类是手动解决这个问题的。我们团队以前每个周五（占一周时间的 20%）都要花在清理“AI 制造的代码垃圾（AI slop）”上。毫不意外地，这种做法根本无法扩展规模。

取而代之的是，我们开始将那些被我们称之为“黄金原则（golden principles）”的东西直接编码进仓库，并建立了一个周期性的自动清理流程。这些原则属于一种非常有主见的、机械化的规则，目的是为将来的智能体运行保持代码库的清晰和一致。例如：（1）我们更偏好共享的实用工具包，而不是手搓的辅助函数，以此来保证不可变约束的中心化；（2）我们不以“莽撞的 YOLO 风格”去探测数据——我们要么验证数据边界，要么依赖类型化（typed）的 SDK，这样智能体就不会在猜测出来的数据结构上去构建代码。

我们设定了一组按固定节奏在后台运行的 Codex 任务，它们负责扫描代码偏差、更新质量评级，并开启目标明确的重构 Pull Request。这其中大多数的 PR 都能在不到一分钟内被审查完毕，并进行自动合并。

这项机制的作用就像是垃圾回收（Garbage collection）。技术债就像一笔高利贷：将其拆分成微小的增量来持续偿还，几乎总是好于让它复利累积、然后再痛苦地一次性集中解决。人类的品味（Taste）被一次性捕捉记录，然后被持续强制应用到每一行代码上。这让我们得以每天都能抓取并解决不良的代码模式，而不是任由它们在代码库中蔓延数天甚至数周。

我们仍在学习的经验

到目前为止，这项策略在 OpenAI 的内部发布及采用过程中，一直运作良好。为真实用户打造真实的产品，有助于将我们的投入扎根于现实之中，并引导我们走向长期的可维护性。

我们尚不清楚的是，在一个完全由智能体生成的系统里，架构的一致性在未来数年间会如何演变。我们仍在学习：人类的判断力究竟在哪里能发挥出最大的杠杆作用，以及如何对这种判断力进行编码，从而让它产生复利。我们也不知道，随着未来模型的能力变得越来越强，这个系统自身会怎样进化。

但有一点已经变得非常清晰：构建软件依然需要纪律，只不过这种纪律不再体现在写代码上，而是更多地展现在如何搭建脚手架上。 那些用来保持代码库一致性的工具、抽象思维和反馈循环，正变得比以往任何时候都更加重要。

我们目前面临的最艰巨挑战，集中在如何设计环境、反馈循环和控制系统上，以此来帮助智能体实现我们的终极目标：在大规模下构建并维护复杂的、可靠的软件。

随着像 Codex 这样的智能体在软件生命周期中接管越来越大的比重，这些问题将会变得越发重要。我们希望分享的这些早期经验，能够帮助你思考未来应该在哪些地方投入精力，从而让你只需要去随心所欲地构建事物。