Harness Engineering：在 Agent 优先的世界中驾驭 Codex

原文：OpenAI — Harness engineering: leveraging Codex in an agent-first world
整理日期：2026-03-04

核心实验：零人工代码构建产品

过去五个月，OpenAI 内部团队进行了一项激进实验：

用 0 行人工编写的代码，构建并发布一个软件产品的内部测试版。

这个产品已有内部日活用户和外部 alpha 测试者。它会部署、会崩溃、会被修复。唯一不同的是——每一行代码（应用逻辑、测试、CI 配置、文档、可观测性、内部工具）都由 Codex 编写。

成果：

  • 约 100 万行代码
  • 约 1500 个 Pull Request
  • 仅用 3 名工程师（后增至 7 名）驱动 Codex
  • 平均每位工程师每天 3.5 个 PR
  • 估算用时仅为手动编码的 1/10

核心哲学：人类掌舵，Agent 执行。

工程师角色的重新定义

当团队不再直接编写代码时，工程工作的性质发生了根本转变——聚焦于系统、脚手架和杠杆点。

早期的瓶颈

初期进展比预期慢，不是因为 Codex 能力不足，而是因为环境定义不足。Agent 缺乏完成高层次目标所需的工具、抽象和内部结构。

工程团队的新职责

深度优先工作法：

  1. 将大目标拆解为小模块（设计、代码、审查、测试等）
  2. 提示 Agent 构建这些模块
  3. 用它们解锁更复杂的任务

失败时的处理：从不”再试一次”。人类工程师介入并问：”缺失了什么能力？如何让它对 Agent 既可读又可执行？”

人类与系统的交互方式

人类几乎完全通过提示词与系统交互：

  • 工程师描述任务
  • 运行 Agent
  • 让 Agent 打开 Pull Request

PR 完成流程：

  1. Codex 在本地审查自己的修改
  2. 请求额外的 Agent 审查（本地和云端）
  3. 响应人类或 Agent 的反馈
  4. 循环迭代直到所有 Agent 审查通过（即 “Ralph Wiggum 循环”）
  5. Codex 使用标准开发工具（gh、本地脚本、仓库嵌入技能）直接获取上下文

审查转移：人类可能审查 PR，但不是必须的。随着时间推移，几乎所有审查工作都转移到了 Agent 之间处理。

让应用对 Agent 可读

随着代码吞吐量增加，瓶颈变成了人类 QA 容量。由于固定约束是”人类时间和注意力”，团队致力于增加 Agent 的能力——让应用 UI、日志和应用指标直接对 Codex 可读。

具体实践

1. 每个 Git Worktree 可启动应用

  • Codex 可以为每个变更启动一个实例

2. 集成 Chrome DevTools Protocol

  • 创建与 DOM 快照、截图和导航交互的技能
  • Codex 可以复现 bug、验证修复、直接推理 UI 行为

3. 可观测性工具

  • 日志、指标和追踪通过本地可观测性栈暴露给 Codex
  • 每个 Worktree 有完全隔离的应用版本（包括日志和指标）
  • Agent 可以用 LogQL 查询日志，用 PromQL 查询指标

示例提示词：

  • “确保服务启动在 800ms 内完成”
  • “这四个关键用户旅程中的任何 span 都不超过 2 秒”

4. 长时间运行

  • Codex 单次运行经常处理单个任务长达 6 小时以上（通常是人类睡觉时）

仓库知识作为系统记录

上下文管理是让 Agent 在大型复杂任务中有效的最大挑战之一。团队学到的第一课：给 Codex 一张地图，而不是 1000 页的说明书。

为什么不要巨型说明书

问题 说明
上下文稀缺 巨型说明书挤占了任务、代码和相关文档的空间
过度指导 = 无指导 当一切都”重要”时，什么都不重要
瞬间腐烂 单体手册变成陈旧规则的坟墓
难以验证 单体 blob 不适合机械检查

解决方案：AGENTS.md 作为目录

  • AGENTS.md（约 100 行）：注入上下文的入口，主要作为地图
  • docs/ 目录：结构化的知识库，作为系统记录
  • 渐进式披露：Agent 从稳定的小入口点开始，被告知下一步去哪里

知识库布局

内容 说明
设计文档 编目和索引，包括验证状态和核心信念
架构文档 领域和包分层的高级地图
质量文档 每个产品领域和架构层的评分，跟踪差距
计划 一等公民产物。小变更用轻量级计划，复杂工作用执行计划
技术债务 活跃计划、完成计划和已知技术债务都版本化并共存

机械执行

  • 专用 linters 和 CI 任务验证知识库是最新的、交叉链接的、结构正确的
  • 定期运行的 “doc-gardening” Agent 扫描陈旧或废弃的文档并打开修复 PR

Agent 可读性是目标

随着代码库演进，Codex 的设计决策框架也需要演进。由于仓库完全由 Agent 生成，它首先针对 Codex 的可读性进行优化。

核心原则

从 Agent 视角看：任何在运行时无法访问的上下文实际上都不存在。

不被读取的信息 = 不存在：

  • Google Docs、聊天线程、人们脑中的知识 → Agent 不可访问
  • 仓库本地的版本化产物（代码、markdown、schema、可执行计划）→ Agent 可以看到

持续推入仓库的内容

  • 对齐架构模式的 Slack 讨论？如果 Agent 无法发现，就像三个月后加入的新人一样未知
  • 给 Codex 更多上下文意味着组织和暴露正确信息，而非用临时指令淹没它
  • 就像给新同事介绍产品原则、工程规范和团队文化一样

技术选型考量

  • 偏好可以完全内化并在仓库中推理的依赖和抽象
  • “无聊”技术往往更容易让 Agent 建模（可组合性、API 稳定性、训练集中的表示）
  • 有时让 Agent 重新实现功能子集比处理不透明上游行为更便宜

示例：没有引入通用的 p-limit 包，而是自己实现了 map-with-concurrency helper：

  • 与 OpenTelemetry 仪器紧密集成
  • 100% 测试覆盖
  • 行为完全符合运行时预期

多 Agent 兼容

将更多系统以 Agent 可以检查、验证和直接修改的形式拉入，不仅增加 Codex 的杠杆，也增加其他 Agent（如 Aardvark）的杠杆。

强制执行架构和品味

仅靠文档无法保持完全 Agent 生成的代码库的一致性。通过强制执行不变量，而非微观管理实现，让 Agent 快速交付而不破坏基础。

示例约束

  • 要求 Codex 在边界解析数据形状，但不规定具体如何（模型似乎喜欢 Zod）

严格的分层架构

Agent 在有严格边界和可预测结构的环境中最有效。团队围绕严格的架构模型构建应用：

每个业务域划分为固定层集：

Types → Config → Repo → Service → Runtime → UI
  • 严格验证的依赖方向
  • 允许的边数量有限
  • 跨领域关注点（认证、连接器、遥测、功能标志）通过单一显式接口进入：Providers
  • 其他一切都禁止并机械执行

执行方式：

  • 自定义 linters（当然由 Codex 生成！）
  • 结构测试
  • 一小套”品味不变量”

品味不变量示例

  • 结构化日志
  • schema 和类型的命名约定
  • 文件大小限制
  • 平台特定的可靠性要求

修复指令注入：由于 lints 是自定义的，错误消息被写成将修复指令注入 Agent 上下文。

约束的权衡

在人类优先的工作流中，这些规则可能显得迂腐或约束。对 Agent 来说，它们成为乘数：一旦编码，就无处不在地应用。

大型工程平台组织的领导方式：

  • 中央强制执行边界
  • 本地允许自治
  • 深度关心边界、正确性和可重现性
  • 在这些边界内，给团队（或 Agent）显著的表达自由

结果：代码不总是匹配人类的风格偏好，没关系。只要输出正确、可维护、对未来的 Agent 运行可读，就达到标准。

高吞吐改变合并理念

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

新规则：

  • 最小化阻塞合并门
  • 短生命周期 PR
  • 测试不稳定通常用后续运行解决，而非无限期阻塞进度

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

原因：在 Agent 吞吐远超人类注意力的系统中，纠正成本低，等待成本高。

“Agent 生成”的真正含义

当说代码库由 Codex Agent 生成时，意思是仓库中的一切：

  • 产品代码和测试
  • CI 配置和发布工具
  • 内部开发者工具
  • 文档和设计历史
  • 评估框架
  • 审查评论和响应
  • 管理仓库本身的脚本
  • 生产仪表板定义文件

人类始终参与，但在不同的抽象层工作：

  • 确定优先级
  • 将用户反馈转化为验收标准
  • 验证结果

当 Agent 挣扎时：识别缺失的东西（工具、护栏、文档），将其反馈到仓库中——总是通过让 Codex 自己编写修复。

Agent 使用标准开发工具：拉取审查反馈、内联响应、推送更新、经常自己压缩和合并 PR。

递增的自主级别

随着更多开发循环直接编码到系统中——测试、验证、审查、反馈处理和恢复——仓库最近跨过一个有意义的阈值：Codex 可以端到端驱动新功能。

给定单个提示词，Agent 现在可以：

  1. 验证代码库当前状态
  2. 复现报告的 bug
  3. 录制演示失败的视频
  4. 实现修复
  5. 通过驱动应用验证修复
  6. 录制演示解决的第二个视频
  7. 打开 Pull Request
  8. 响应 Agent 和人类反馈
  9. 检测和修复构建失败
  10. 仅在需要判断时上报人类
  11. 合并变更

注意：这种行为严重依赖于仓库的特定结构和工具，在类似投资之前不应假设其泛化——至少目前还没有。

熵和垃圾回收

完全 Agent 自主也引入了新颖的问题。Codex 复制仓库中已存在的模式——甚至是不均匀或次优的模式。随着时间推移，这不可避免地导致漂移。

最初的人工清理（不可扩展）

团队过去每周五花 20% 的时间清理 “AI slop”。 unsurprisingly，那不可扩展。

解决方案：黄金原则 + 自动清理

黄金原则：直接的、机械的规则，保持代码库对未来 Agent 运行可读和一致。

示例：

  1. 偏好共享工具包而非手卷 helper，保持不变量集中
  2. 不”YOLO 风格”探测数据——验证边界或依赖类型 SDK，让 Agent 不会意外建立在猜测的形状上

定期清理流程：

  • 后台 Codex 任务定期扫描偏差
  • 更新质量评分
  • 打开针对性重构 PR
  • 大多数可在 1 分钟内审查并自动合并

效果像垃圾回收：技术债务像高利贷——几乎总是更好地持续小额偿还，而非让其复利然后痛苦地爆发处理。

人类品味一次捕获，然后在每行代码上持续执行。这也允许每天捕获和解决不良模式，而非让其在代码库中传播数天或数周。

仍在学习的课题

这种策略在内部发布和 OpenAI 内部采用方面表现良好。构建真实产品给真实用户帮助将投资锚定在现实中，并指导团队走向长期可维护性。

尚未知晓的：

  • 完全 Agent 生成的系统中架构一致性如何随年份演进
  • 人类判断在哪里增加最大杠杆
  • 如何编码这种判断使其复利
  • 随着模型能力持续提升，系统将如何演进

已明确的：

  • 构建软件仍然需要纪律，但纪律更多体现在脚手架而非代码
  • 保持代码库一致性的工具、抽象和反馈循环越来越重要

最困难的挑战现在集中在：

  • 设计环境
  • 构建反馈循环
  • 构建控制系统
  • 帮助 Agent 实现目标：大规模构建和维护复杂、可靠的软件

核心启示

1. 从”写代码”到”设计环境”

工程师的主要工作不再是编写代码，而是：

  • 设计环境
  • 明确意图
  • 构建反馈循环
  • 让 Codex Agent 能够可靠地工作

2. Agent 可读性是第一目标

代码首先要对 Agent 可读，其次才是对人类。这意味着：

  • 知识必须仓库本地化、版本化
  • 应用必须可被 Agent 观察和驱动
  • 架构必须严格且有边界

3. 高吞吐改变一切

当 Agent 吞吐远超人类注意力时：

  • 纠正成本低，等待成本高
  • 短生命周期 PR 优于长时间审查
  • 后续修复优于阻塞进度

4. 持续垃圾回收

技术债务必须通过编码的”黄金原则”持续清理，而非定期大扫除。

5. 渐进式披露

给 Agent 一张地图，而非百科全书。从小的稳定入口开始，教它下一步去哪里。

“随着像 Codex 这样的 Agent 承担软件生命周期中更大的部分，这些问题将更加重要。我们希望分享的一些早期经验能帮助你思考在哪里投资你的努力，这样你就可以只是构建东西。”

原文链接：https://openai.com/index/harness-engineering/
OpenAI 官方博客，2026年3月