工程技术：在智能体优先的世界中利用 Codex
来源: OpenAI Blog | 作者: Ryan Lopopolo（Codex 技术人员）| 日期: 2026-03-11 原文链接: https://openai.com/zh-Hans-CN/index/harness-engineering/
一句话总结
当代码全部由 Agent 生成时，工程师的核心任务不再是写代码，而是设计让 Agent 能可靠工作的环境、反馈回路和控制系统；Codex 团队用五个月、零人工代码产出约 100 万行代码和 1,500 个 PR 验证了这条路径。
速览
- 人类掌舵，智能体执行——五个月、约 100 万行代码、~1,500 PR，没有一行人工编写的代码；团队从 3 人扩到 7 人，吞吐量反增。
- 瓶颈不是 Agent 能力，而是环境规范——早期进展慢，是因为工具、抽象、结构不够明确，不是 Codex 不会写。
- 情境是稀缺资源，给地图不给百科全书——
AGENTS.md保持在 ~100 行作为目录，深层知识存在结构化的docs/里，渐进式披露。 - 仓库即一切，Slack/Docs/脑子里的知识等于不存在——运行时 Agent 情境之外的信息都无法被访问；一切必须 checked in。
- 强制不变量，不微观管理——用自定义 linter 把规则机械化（架构层级、命名、结构化日志），错误信息里直接注入修复指令。
- 让 UI、日志、指标对 Agent 直接可读——Git worktree 启动 app、Chrome DevTools 接入、临时可观测性堆栈（LogQL + PromQL），把人类 QA 从瓶颈中解放。
- 最小化阻塞合并门——Agent 吞吐量远超人类注意力时，等待成本 > 纠错成本；测试偶发失败重跑而非阻断。
- 端到端自主闭环已跑通——Codex 可独立完成：复现 bug → 录视频 → 修复 → 再录视频 → 开 PR → 回复反馈 → 修构建 → 合并，仅在需要判断时找人。
- 技术债务像高息贷款，持续小额偿还——把”黄金原则”编码进仓库，后台 Codex 任务扫描偏差并发起小型重构 PR，替代每周五 20% 时间集中清理。
- 支撑结构比代码本身更重要——纪律更多体现在文档、linter、反馈回路和架构约束上，而非代码风格。
核心内容
一、工程师工作重心：从写代码转向造环境
实验从 2025 年 8 月下旬的空仓库开始。初始架构（仓库结构、CI 配置、格式化规则、包管理器、应用框架）由 Codex CLI + GPT-5 基于一小套现有模板生成，连指导 Codex 工作的初始 AGENTS.md 都是 Codex 自己写的。
人类几乎只通过 prompt 交互：描述任务 → 运行 Agent → 让它开 PR → 指示它本地审查、请求额外智能体审查、响应反馈，一直循环直到所有审查者满意（作者称之为 “Ralph Wiggum 循环”）。Codex 直接使用 gh、本地脚本和仓库内嵌技能收集情境，人类不需要复制粘贴任何内容到 CLI。
过去五个月的产出规模：约 100 万行代码，约 1,500 个 PR 被开启并合并，团队从 3 名工程师扩展到 7 名，每人每天平均处理 3.5 个 PR。产品已交付给数百名内部 alpha 用户，其中包括每天使用的高级用户。
团队核心理念：不手动编写代码。由于没有人工编码实践，工程师工作的重点转向系统、架构和杠杆作用。
早期进展比预期慢，根因不是 Codex 能力不足，而是环境规范不够明确——Agent 缺少实现高级目标所需的工具、抽象层和内部结构。解决路径是深度优先：把大目标拆成小的构建模块（设计、代码、评审、测试），让 Codex 构建这些模块，再用它们解锁更复杂任务。当事情进行不顺时，答案不是”再努力一点”，而是追问”还需要什么能力，该怎么让它对 Agent 清晰可读且可强制执行”。
二、情境管理：给地图，不给百科全书
Codex 团队把 AGENTS.md 从”百科全书”改造为”内容目录”，因为巨型指令文件会带来四个问题：
- 情境是稀缺资源——巨大指令文件会挤掉任务、代码和相关文档，Agent 要么错过关键约束，要么针对错误约束优化。
- 过多指导反而无效——当一切都”重要”时，一切都不重要，Agent 最终变成本地模式匹配。
- 立即腐烂——巨大手册会变成陈旧规则的坟场，Agent 无法判断哪些仍有效，人类停止维护后就成了隐患。
- 难以核实——单个 blob 不适合机械检查（覆盖率、新鲜度、所有权、交叉链接），漂移不可避免。
仓库知识以结构化 docs/ 目录承载，作为”记录系统”。AGENTS.md 保持约 100 行，作为地图指向更深来源。设计文档被编目并含验证状态，核心理念定义智能体优先操作原则；架构文档 提供域和包分层的顶层地图；质量评分追踪每个产品领域和架构层的差距。
计划是一流工件：临时轻量计划用于小变更；复杂工作写入执行计划并附进度和决策日志，全部提交到仓库；活跃计划、已完成计划和已知技术债务都版本化、集中存放。
这实现渐进式披露：Agent 从小而稳定的切入点开始，被引导到下一步该去哪儿查，而不是一开始被淹没。机械执行这一点——专职的 linter 和 CI 作业验证知识库更新状况、交叉链接和结构；定期运行一个”doc-gardening” Agent 扫描过期或废弃文档，发起修复 PR。
三、仓库即现实：Codex 可读性优先
Codex 在运行时无法访问仓库情境之外的任何内容——Google Docs、聊天记录、人们头脑中的知识都不存在。仓库本地的、已版本化的工件（代码、Markdown、模式、可执行计划）就是它能看到的全部。
团队的具体做法：把越来越多的情境推到仓库里。那次让团队对架构模式达成一致的 Slack 讨论——如果 Agent 发现不了，那它就像迟了三个月入职的新员工一样毫不知情。引导 Agent 的方式类似引导新队友：产品原则、工程规范、团队文化（包括表情符号偏好）都要显式化。
这一框架带来几个具体取舍：
- 依赖选择偏向”枯燥”技术——可组合性强、API 稳定、在训练集里表现好的依赖项更容易建模。
- 某些场景下重新实现子集比调用库更便宜——团队没有引入通用
p-limit风格包，而是投入实现自己的带并发 map 辅助函数，理由是与 OpenTelemetry 仪表紧密集成、100% 测试覆盖、行为完全符合运行时预期。 - 目标是让其他 Agent 也能参与——将系统转化为 Agent 可检查、验证、修改的形式，杠杆效应不仅对 Codex 生效，也对 Aardvark 这类其他 Agent 生效。
四、强制不变量：用 linter 把品味机械化
仅靠文档维持不了完全由 Agent 生成的代码库的连贯性。关键是通过强制不变量（而非微观管理实施过程）让 Agent 能快速交付又不削弱基础。示例：团队要求 Codex 在边界处解析数据形状，但不规定具体实现（模型偏好 Zod，但未指定特定库）。
严格架构模型：应用围绕一个严格边界与可预测结构构建。每个业务域划分为一组固定层，依赖方向严格验证，仅允许有限边。规则：
- 每个业务领域内代码只能”向前”依赖：
Types → Config → Repo → Service → Runtime → UI - 横切关注点（认证、连接器、遥测、功能标志）通过一个显式接口进入：
Providers - 其他依赖都不被允许，通过自动化强制执行
这种架构通常要等到数百名工程师规模才会推行，但对编码 Agent 来说是早期先决条件——有约束速度才不降，架构才不漂移。
自定义 linter 与结构测试机械地执行规则，辅以一组”品味不变式”。具体示例：
- 静态强制结构化日志记录
- 模式和类型的命名约定
- 文件大小限制
- 特定平台的可靠性要求
这些 linter 是自定义的，团队在编写错误信息时会注入修复指令到 Agent 情境中——在人类工作流中这些规则可能显得束缚，在 Agent 工作流中它们是倍增器：一旦编码，所有地方立即应用。
团队明确区分哪些边界需要强制、哪些地方允许自主。类似领导大型工程平台组织：在中央强制边界（界限、正确性、可重复性），在本地允许自由（解决方案的表达方式）。生成的代码不总是符合人类风格偏好，这没关系——只要正确、可维护、对未来 Agent 清晰易读就达标。
人类品味通过反馈进入系统：审查评论、重构 PR、面向用户的 bug 会被记录为文档更新，或直接编码到工具中。当文档不够时，规则被转化为代码。
五、扩展 Agent 的可感知范围
随着代码吞吐量增加，瓶颈变成了人工 QA 能力。因为人类的时间和注意力是固定的，团队一直在给 Agent 增加能力，把应用的 UI、日志、应用指标等对 Codex 直接可读。具体实践：
- Git worktree 驱动的应用启动——让应用可根据 git worktree 启动，Codex 为每次更改启动并驱动一个实例。
- Chrome DevTools 协议接入 Agent 运行时——创建处理 DOM 快照、截图和导航的技能，使 Codex 能复现错误、验证修复、直接推理 UI 行为。
- 临时的本地可观测性堆栈——日志、指标、追踪通过一个本地堆栈展示给 Codex，对任意给定工作树都是临时的（任务完成后该版本的日志和指标被删除）。Agent 用 LogQL 查询日志、PromQL 查询指标。
- 长时单任务运行——经常看到单次 Codex 运行在单个任务上持续超过六小时（通常是人类睡眠时间）。
有了这些情境，像”确保服务启动在 800ms 内完成”或”这四个关键用户旅程中的任何跨度都不得超过两秒”这样的 prompt 就变得可行。
六、传统规范被反转：等待成本 > 纠错成本
Codex 吞吐量增加后，很多传统工程规范不再适用：
- 仓库在运行过程中尽量减少阻塞合并门
- PR 生命周期很短
- 测试偶发失败通过后续重跑解决，而不是无限期阻碍进展
在低吞吐量环境中这样做是不负责任的；但在 Agent 吞吐量远超人类注意力的系统中，纠错成本低、等待成本高，这通常是正确选择。
Agent 产出覆盖范围（即”整个代码库”）：
- 产品代码与测试
- CI 配置和发布工具
- 内部开发者工具
- 文档和设计历史
- 评估框架
- 审阅评论和回复
- 管理代码仓库本身的脚本
- 生产仪表板定义文件
人类始终参与其中，但抽象层级不同：优先处理工作、将用户反馈转化为验收标准、对结果进行验证。当 Agent 遇到困难，团队视为信号——识别缺失的工具、指导、约束、文档，把修复反馈到仓库里（修复本身也由 Codex 编写）。
端到端自主闭环：仓库最近跨过了一个门槛，Codex 能在一个 prompt 下端到端驱动新功能：
- 验证代码库的当前状态
- 重现已报告的漏洞
- 录制一个演示故障的视频
- 实施修复措施
- 通过运行应用程序来验证修复
- 录制第二个视频，演示解决方案
- 打开 Pull Request
- 回应智能体和人类反馈
- 检测并修复构建故障
- 仅在需要判断时才交由人工处理
- 合并更改
此行为很大程度上依赖仓库的具体结构和工具，不应在没有类似投入的情况下假定可泛化。
七、黄金原则：持续偿还技术债
完全自主的 Agent 带来新问题：Codex 会复现仓库中已存在的模式，包括不均衡或不理想的模式，随时间不可避免地漂移。
最初人类手动处理——团队过去每周五（占 20%）花时间清理”AI 残渣”，不具备可扩展性。
替代方案是把”黄金原则”直接编码到仓库中，建立循环清理流程。这些原则是带主观意见的机械规则，为了保持代码库对未来 Agent 运行的可读性和一致性。示例：
- 更倾向于共享实用程序包，而非手工编写的辅助工具——将不变式集中管理
- 不使用”YOLO 式”探测数据——验证边界或依赖类型化的 SDK，避免 Agent 基于猜测的结构构建
团队定期运行一组后台 Codex 任务，扫描偏差、更新质量等级、发起有针对性的重构 PR；其中大多数可以在一分钟内审查并自动合并。
这个机制的功能类似垃圾回收——技术债务像高息贷款，不断小额偿还优于累积后痛苦集中解决。人类品味一旦被捕捉就能持续应用到每一行代码，不良模式在当天被发现和解决，而不是在代码库中传播数天或数周。
八、尚未解决的问题
到目前为止，这一策略在 OpenAI 内部发布和采纳过程中表现良好——为真实用户构建真实产品，把投资锚定在现实中，引导向长期可维护性。
尚不清楚的问题：
- 完全由 Agent 生成的系统中，架构连贯性如何随时间演变
- 人类判断力在哪些方面能发挥最大作用，如何把这种判断力编码以发挥更大作用
- 随着模型能力增强，整个系统如何演变
构建软件仍然需要纪律，但纪律更多体现在支撑结构（工具、抽象、反馈回路）上，而不是代码上。当前最棘手的挑战集中在设计环境、反馈回路和控制系统方面，帮助 Agent 大规模构建和维护复杂、可靠的软件。
名言金句
- “人类掌舵。智能体执行。”
- “不手动编写代码。“（团队核心理念）
- “要给 Codex 的是一张地图，而不是一本 1,000 页的说明书。”
- “从智能体的角度来看，它在运行时无法在情境中访问的任何内容都是不存在的。”
- “构建软件仍然需要纪律，但纪律更多地体现在支撑结构上，而不是代码上。“
可行建议
- AGENTS.md 保持薄（~100 行），作为目录而非百科全书——深层知识放在结构化
docs/里，由专职 linter 和 CI 验证新鲜度与交叉链接 - 把设计文档、执行计划、技术债务作为一流工件签入仓库——版本化、编目、含验证状态，使 Agent 能独立运行无需外部情境
- 早期就用自定义 linter 强制架构边界——严格分层（如 Types → Config → Repo → Service → Runtime → UI），横切关注点走单一 Providers 接口
- 错误信息里嵌入修复指令——自定义 linter 报错时直接把修复指令注入 Agent 情境
- 让 app 对 Agent 可读——git worktree 启动、Chrome DevTools 接入、本地临时可观测性堆栈（LogQL + PromQL）
- 最小化阻塞合并门——吞吐量高时偶发失败重跑，避免等待成本超过纠错成本
- 建立后台”黄金原则”清理 Agent——每日扫描漂移、发起小型重构 PR，替代周期性集中清理
- 优先选”枯燥”技术——可组合、API 稳定、训练集表现好；必要时重新实现子集以换取可控性
资源清单
- Ralph Wiggum 循环（PR 审查循环的灵感来源）：https://ghuntley.com/loop/
- ARCHITECTURE.md 模式（仓库架构文档范式）：https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html
- Codex 执行计划指南（OpenAI Cookbook）：https://cookbook.openai.com/articles/codex_exec_plans
- Parse, don’t validate（边界解析原则）：https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/
- AI Is Forcing Us to Write Good Code（严格边界与可预测结构）：https://bits.logic.inc/p/ai-is-forcing-us-to-write-good-code
- Aardvark（OpenAI 另一个参与代码库开发的 Agent）：https://openai.com/index/introducing-aardvark/
- Codex 产品入口：https://openai.com/codex/