驾驭工程：在智能体优先的世界中利用Codex

# 工程驾驭术：在智能体为先的世界里活用 Codex 来源：https://openai.com/index/harness-engineering/ 过去五个月，我们的团队一直在进行一项实验：用 **0 行手动编写的代码** 构建并交付一个软件产品的内部测试版。 该产品已有内部日常用户和外部 alpha 测试者。它正常发布、部署、崩溃、修复。不同之处在于，每一行代码——应用逻辑、测试、CI 配置、文档、可观测性和内部工具——都由 Codex 编写。我们估计，构建这个产品所花费的时间约为手工编写代码所需时间的 1/10。 **人类掌控方向，智能体执行操作。** 我们有意选择了这个约束，目的是构建必要的能力，使工程速度提升数个数量级。我们只有几周时间来交付最终达到百万行代码规模的产品。为此，我们需要理解当软件工程团队的主要工作不再是编写代码，而是设计环境、明确意图、构建反馈循环以使 Codex 智能体能够可靠工作时，会发生什么变化。 这篇文章讲述了我们用一组智能体构建全新产品时的所学——哪些环节失效了，哪些产生了复合效应，以及如何最大化我们唯一真正稀缺的资源：人的时间和精力。 第一次提交到一个空仓库是在 2025 年 8 月下旬。 初始脚手架——仓库结构、CI 配置、格式化规则、包管理器设置和应用程序框架——是由 Codex CLI 使用 GPT-5 生成，并在一小套现有模板的引导下完成的。甚至最初指导智能体如何在仓库中工作的 AGENTS.md 文件本身也是由 Codex 编写的。 没有预先存在的人类编写的代码来作为系统的锚点。从一开始，仓库就由智能体塑造。 五个月后，仓库包含大约一百万行代码，涵盖应用逻辑、基础设施、工具、文档和内部开发者工具。在此期间，大约有 1500 个拉取请求被打开并合并，而驱动 Codex 的工程团队仅由三人组成。这相当于每位工程师每天平均处理 3.5 个 PR，令人惊讶的是，随着团队扩展到现在的七名工程师，吞吐量 **不降反升**。重要的是，这并非为了产出而产出：该产品已在内部被数百名用户使用，包括每日活跃的内部高级用户。 在整个开发过程中，人类从未直接贡献任何代码。这成为了团队的核心原则：**不手动编写任何代码**。 缺少了手动的编码，**引入了一种不同的工程工作，侧重于系统、脚手架和杠杆效应**。 早期的进展比我们预期的要慢，不是因为 Codex 能力不足，而是因为环境定义不够明确。智能体缺乏达成高层次目标所需的工具、抽象和内部结构。我们工程团队的主要工作变成了让智能体能够执行有用的任务。 在实践中，这意味着采用深度优先的工作方式：将较大的目标分解为较小的构建块（设计、代码、评审、测试等），提示智能体构建这些块，并用它们来解锁更复杂的任务。当某件事失败时，修复方法几乎从来不是“再努力一点”。因为取得进展的唯一途径是让 Codex 完成工作，人类工程师总是会介入任务并问：“缺少了哪些能力？我们如何让这些能力对智能体既清晰又可执行？” 人类几乎完全通过提示与系统交互：工程师描述一项任务，运行智能体，然后让它打开一个拉取请求。为了驱动一个 PR 完成，我们指示 Codex 本地审查自己的更改，请求额外的特定智能体审查（无论是本地还是云端），响应任何人类或智能体给出的反馈，并在循环中迭代，直到所有智能体审查者满意（这实际上是一个 [Ralph Wiggum Loop](https://ghuntley.com/loop/)）。Codex 直接使用我们的标准开发工具（`gh`、本地脚本和仓库内置的技能）来收集上下文，无需人类复制粘贴到 CLI 中。 人类可以审查拉取请求，但并非必须。随着时间的推移，我们已将几乎所有的审查工作推向了智能体之间的处理。 随着代码吞吐量的增加，瓶颈变成了人类的 QA 能力。由于固定约束是人的时间和精力，我们致力于通过使应用 UI、日志和应用指标本身对 Codex 直接可读来为智能体增加更多能力。 例如，我们让应用能够按 git 工作树启动，这样 Codex 可以为每次变更启动并驱动一个实例。我们还将 Chrome DevTools 协议接入智能体运行时，并创建了用于处理 DOM 快照、截图和导航的技能。这使得 Codex 能够重现 bug、验证修复并直接推理 UI 行为。 我们对可观测性工具也做了同样的事情。日志、指标和追踪通过一个本地可观测性栈暴露给 Codex，该栈对于任何给定的工作树都是临时的。Codex 在应用的完全隔离版本上工作——包括其日志和指标——一旦任务完成，这些环境就会被拆除。智能体可以使用 LogQL 查询日志，使用 PromQL 查询指标。有了这些上下文，像“确保服务启动在 800ms 内完成”或“这四个关键用户旅程中没有 span 超过两秒”这样的提示就变得可行了。 我们经常看到单个 Codex 运行在单个任务上工作长达六个小时（通常是在人类睡觉的时候）。 上下文管理是让智能体在大型复杂任务中发挥作用的最大挑战之一。我们早期学到的教训之一很简单：**给 Codex 一张地图，而不是一本 1000 页的使用手册。** - **上下文是稀缺资源。** 一个巨大的指令文件会排挤任务、代码和相关文档——因此智能体要么错过关键约束，要么开始优化错误的目标。 - **过多的指导会变成“非指导”。** 当所有东西都“重要”时，就没有什么是重要的了。智能体最终会进行局部模式匹配，而不是有目的地导航。 - **它会迅速腐烂。** 一本单一的指南手册会变成陈旧规则的坟场。智能体无法分辨哪些仍然有效，人类停止维护它，文件悄悄地变成一个吸引人的麻烦。 - **难以验证。** 一个单一的文本块不适合进行机械检查（覆盖率、新鲜度、所有权、交叉链接），因此漂移是不可避免的。 因此，我们没有将 `AGENTS.md` 视为百科全书，而是将其视为 **目录**。 仓库的知识库存放在一个结构化的 `docs/` 目录中，作为记录系统。一个简短的 `AGENTS.md`（大约 100 行）被注入到上下文中，主要用作一张地图，包含指向其他地方更深层事实来源的指针。 仓库内知识存储布局。 设计文档被编目和索引，包括验证状态和一组定义智能体优先运营原则的核心信念。[架构文档](https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html) 提供了领域和包分层的顶层地图。一份质量文档对每个产品领域和架构层进行评分，跟踪随时间的差距。 计划被视为一等工件。临时轻量级计划用于小改动，而复杂的工作则被捕获在[执行计划](https://cookbook.openai.com/articles/codex_exec_plans)中，包含进度和决策日志，并检入仓库。活跃的计划、已完成的计划和已知的技术债务都被版本化并存放在一起，使智能体无需依赖外部上下文即可运行。 这实现了**渐进式信息展示**：智能体从一个小的、稳定的入口开始，并被告知下一步该看哪里，而不是一开始就被信息淹没。 我们通过机械方式强制执行这一点。专用的 linter 和 CI 任务验证知识库是否最新、交叉链接且结构正确。一个定期运行的“文档维护”智能体会扫描过时或不再反映实际代码行为的文档，并打开修复性的拉取请求。 随着代码库的发展，Codex 的设计决策框架也需要发展。 由于仓库完全由智能体生成，它首先针对 **Codex 的可读性** 进行了优化。就像团队为新入职的工程师提高代码的可导航性一样，我们人类工程师的目标是让智能体能够 **直接从仓库本身** 推理完整的业务领域。 从智能体的角度来看，在运行上下文中无法访问的任何事物实际上都不存在。存在于 Google 文档、聊天线程或人们头脑中的知识对系统来说是不可访问的。仓库本地、版本化的工件（例如代码、markdown、模式、可执行计划）才是它所能看到的。 我们了解到，随着时间的推移，我们需要将越来越多的上下文推入仓库。那个让团队对架构模式达成一致的 Slack 讨论？如果它对智能体不可发现，那么它就像三个月后新入职的工程师所不知道的东西一样难以理解。 给 Codex 更多上下文意味着组织和暴露正确的信息，以便智能体能够对其进行推理，而不是用临时指令淹没它。就像你会向新队友介绍产品原则、工程规范和团队文化（包括表情符号偏好）一样，向智能体提供这些信息会带来更一致的输出。 这种框架理清了许多权衡。我们更倾向于那些可以完全内部化并在仓库内推理的依赖和抽象。通常被描述为“无聊”的技术由于可组合性、API 稳定性和在训练集中的代表性，更容易被智能体建模。在某些情况下，让智能体重新实现部分功能比处理公共库的不透明上游行为更便宜。例如，我们没有引入通用的 `p-limit` 风格的包，而是实现了我们自己的带并发限制的 map 辅助函数：它与我们的 OpenTelemetry 仪器化紧密集成，有 100% 的测试覆盖率，并且行为完全符合我们的运行时预期。 将更多系统拉入智能体能够检查、验证和直接修改的形式，不仅会增加 Codex 的杠杆作用，而且还会增加其他也在代码库上工作的智能体（例如 [Aardvark](https://openai.com/index/introducing-aardvark/)）的杠杆作用。 仅靠文档并不能让完全由智能体生成的代码库保持一致性。**通过强制执行不变量，而不是微观管理实现，我们让智能体快速交付而不破坏基础架构。** 例如，我们要求 Codex [在边界处解析数据形状](https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/)，但不指定具体如何实现（模型似乎喜欢 Zod，但我们没有指定该特定库）。 智能体在 **边界严格、结构可预测** 的环境中最为有效，因此我们围绕一个严格的架构模型构建了应用。每个业务领域被划分为一组固定的层，具有严格验证的依赖方向和一组有限的允许边。这些约束通过自定义 linter（当然也是 Codex 生成的！）和结构测试以机械方式强制执行。 下图展示了规则：在每个业务领域（例如应用设置）内，代码只能通过一组固定的层（Types → Config → Repo → Service → Runtime → UI）“向前”依赖。横切关注点（认证、连接器、遥测、特性标志）通过一个单一显式接口进入：Providers。其他任何方式都是不允许的，并通过机械方式强制执行。 这种架构通常是你在拥有数百名工程师之后才会推迟考虑的。但对于编码智能体来说，它是一个早期的先决条件：这些约束正是能够在不出现衰退或架构漂移的情况下保持速度的原因。 在实践中，我们通过自定义 linter 和结构测试来强制执行这些规则，并加上一小组“品味不变量”。例如，我们静态地强制执行结构化日志记录、模式和类型的命名约定、文件大小限制以及特定平台的可靠性要求。由于 linter 是自定义的，我们编写错误消息以将修复指令注入智能体上下文。 在人类优先的工作流中，这些规则可能显得吹毛求疵或具有限制性。但对于智能体，它们变成了倍增器：一旦编码，它们就会同时应用于所有地方。 同时，我们明确哪些约束重要，哪些不重要。这类似于领导一个大型工程平台组织：集中强制执行边界，允许局部自主。你非常关心边界、正确性和可重复性。在这些边界内，你允许团队（或智能体）在解决方案的表达方式上拥有相当大的自由。 生成的代码并不总是符合人类的风格偏好，但这没关系。只要输出正确、可维护且对未来的智能体运行可读，就达到了标准。 人类品味被持续反馈回系统。审查评论、重构拉取请求和用户可见的 bug 被捕获为文档更新或直接编码到工具中。当文档不足时，我们将规则提升到代码中。 随着 Codex 吞吐量的增加，许多传统的工程规范变得适得其反。 仓库以最少的阻塞合并门禁运行。拉取请求生命周期很短。测试不稳定通常通过后续运行来处理，而不是无限期地阻塞进度。在一个智能体吞吐量远超人类注意力的系统中，纠错成本低，而等待成本高。 在低吞吐量的环境中，这将是轻率的。但在这里，它通常是正确的权衡。 当我们说代码库由 Codex 智能体生成时，意味着代码库中的一切。 智能体产生： - 产品代码和测试 - CI 配置和发布工具 - 内部开发者工具 - 文档和设计历史 - 评估工具链 - 审查评论和回应 - 管理仓库本身的脚本 - 生产仪表板定义文件 人类始终处于循环中，但在与我们习惯的不同抽象层上工作。我们确定优先级，将用户反馈转化为验收标准，并验证结果。当智能体遇到困难时，我们将其视为一个信号：确定缺少什么——工具、护栏、文档——并将其反馈回仓库，总是通过让 Codex 自己编写修复。 智能体直接使用我们的标准开发工具。它们拉取审查反馈，内联回复，推送更新，并经常自己 squash 和合并拉取请求。 随着开发循环的更多部分被直接编码到系统中——测试、验证、审查、反馈处理和恢复——仓库最近跨越了一个有意义的门槛，Codex 可以端到端地驱动一个新功能。 给定一个提示，智能体现在可以： - 验证代码库的当前状态 - 重现一个报告的 bug - 录制展示失败的视频 - 实施修复 - 通过驱动应用验证修复 - 录制第二个展示解决方案的视频 - 打开一个拉取请求 - 响应智能体和人类的反馈 - 检测并修复构建失败 - 仅在必要时升级给人类