智能体优先的软件工程：OpenAI 如何让 Codex 写完整个代码库

OpenAI 这篇 《Harness engineering: leveraging Codex in an agent-first world》 很适合拿来校准一件事：当编码智能体真的进入生产环境，工程师的价值不会消失，但工作重心会明显上移。

文章作者 Ryan Lopopolo 讲的是一个内部实验。OpenAI 团队从一个空 Git 仓库开始，用 Codex 构建并交付了一个内部 beta 产品。约束很强：不写任何一行手写代码。应用逻辑、测试、CI 配置、文档、可观测性和内部工具都由 Codex 生成。五个月后，这个仓库已经接近百万行代码；一个三人工程小组在这段时间里打开并合并了约 1500 个 PR。团队估算，这个产品用约十分之一的时间完成了原本需要人工编码的工作量。

这个数字很抓人，但更值得看的是背后的工程方法。OpenAI 没有把 Codex 当成更快的自动补全。他们把仓库、文档、工具、测试、日志和评审流程改造成智能体能理解、能验证、能修改的系统。

从“写代码”转向“设计工作环境”

原文里有一句很直接的话：人类负责引导，智能体负责执行。

这个分工听起来简单，落到工程里却意味着很多习惯要重写。早期进展慢，并不是因为 Codex 不会写代码，而是环境描述不够清楚。智能体缺少工具、抽象和内部结构时，高层目标很难变成可靠的实现。

所以工程师的任务变成了几类事：

• 把目标拆成更小的设计、实现、评审和验证任务。
• 让 Codex 自己构建缺失的工具和脚手架。
• 把失败当成环境缺陷，而不是一句“再试一次”。
• 把人类评审意见沉淀成文档、lint 或测试，让下一次运行能直接受益。

这和传统工程管理很像，只是“团队成员”变成了可并行运行的智能体。你不能只靠口头经验带它们做事，必须把规则放进仓库，放进工具链，放进 CI。

仓库成了系统记录

OpenAI 试过把所有规则塞进一个巨大的 AGENTS.md，结果不理想。上下文窗口有限，规则太多会互相稀释，文档也会快速过期。

他们后来把 AGENTS.md 缩短到大约 100 行，只把它当成目录。知识库放在结构化的 docs/ 目录里，包括设计文档、执行计划、产品规格、架构说明、质量评分、可靠性和安全要求。

flowchart TD
    A[短 AGENTS.md] --> B[告诉智能体去哪找资料]
    B --> C[docs 作为系统记录]
    C --> D[设计文档与产品规格]
    C --> E[执行计划与决策日志]
    C --> F[架构、质量、可靠性、安全规则]
    F --> G[lint、测试、CI 自动检查]

这件事对使用 Codex、Claude Code 或其他编码智能体的团队都很关键。智能体运行时看不到你脑子里的历史背景，也看不到散落在聊天记录和会议纪要里的决策。它能稳定利用的，是仓库里可检索、可版本化、可验证的材料。

文档不再只是给新同事看的。它也是智能体的工作界面。

可读性不是给人看的，也是给智能体看的

文章把一个词反复推到前台：legibility，可以理解为“可读性”或“可理解性”。

这里说的不是代码风格层面的好看，而是系统是否能被智能体读懂。OpenAI 为每个 Git worktree 启动隔离的应用实例，让 Codex 可以自己跑应用、看 DOM、截屏、导航、复现 bug 和验证修复。他们还把日志、指标和 trace 暴露给 Codex，让智能体能用 LogQL 和 PromQL 查询运行状态。

于是，提示词可以从“优化一下启动速度”变成更可验证的目标：

确保服务启动在 800ms 以内完成。

或者：

确保四条关键用户路径里没有任何 span 超过 2 秒。

这类目标对人也清楚，对智能体也可执行。关键在于系统提供了可观察的反馈，而不是让模型凭感觉判断“应该好了”。

架构边界越硬，智能体越能放开跑

OpenAI 的另一个经验是：文档本身无法维持一个完全由智能体生成的代码库。机械约束才会稳定执行。

他们把业务域拆成固定层次，并严格限制依赖方向。跨域能力通过明确的 Providers 入口进入。结构测试和自定义 lint 负责阻止错误依赖、文件过大、命名不一致、日志不结构化等问题。

这听起来像大平台团队才会提前做的事。但在智能体优先的工作流里，约束要更早出现。因为吞吐量上来之后，人类不可能逐行把关。规则必须变成可自动执行的边界。

flowchart LR
    T[Types] --> C[Config]
    C --> R[Repo]
    R --> S[Service]
    S --> RT[Runtime]
    RT --> UI[UI]
    P[Providers] --> C
    P --> S
    P --> RT

这也解释了为什么“让 AI 写更多代码”还不够。团队需要把品味、边界和质量要求编码进系统。注释、评审、事故复盘和用户反馈，最后都要回到仓库里的规则、测试或文档。

合并策略也会跟着吞吐量变化

原文提到，随着 Codex 吞吐量提高，一些传统工程规范会显得低效。这个仓库采用了较少的阻塞式合并门禁，PR 生命周期很短。测试 flaky 时，团队更倾向于后续运行修复，而不是无限期阻塞。

这句话不能脱离上下文照搬。OpenAI 的前提是：他们已经把大量反馈回路、隔离环境、智能体评审和结构约束放进了系统。没有这些基础，减少合并门禁只会制造混乱。

更准确的理解是：当修复成本很低、反馈速度很快、系统边界足够硬时，工程团队可以把一部分风险从“合并前拦截”转移到“合并后快速纠正”。这是一种吞吐量驱动的权衡，不是通用建议。

对普通团队有什么启发

这篇文章最有价值的地方，不是告诉你“从今天开始不要手写代码”。大多数团队也不该直接复制这个约束。

更现实的启发有三点。

第一，把仓库里的知识整理成智能体能用的入口。短 AGENTS.md 加结构化文档，比一份不断膨胀的总说明更容易维护。

第二，把验收标准写成可执行信号。测试、截图、日志查询、性能指标和 lint 都比一句“看起来没问题”更适合交给智能体。

第三，把重复出现的评审意见升级成规则。人类不应该一直提醒同一件事。提醒三次，就该考虑写进文档、脚本、检查器或模板。

仍然未知的部分

OpenAI 也没有把这套方法包装成终局答案。原文明确说，他们还不知道一个完全由智能体生成的系统在多年尺度上如何保持架构一致性，也还在学习人类判断应该放在哪里最有杠杆。

这个保留很重要。智能体优先的软件工程没有拿掉工程纪律，只是把纪律从“人手写每一行代码”迁移到“人设计环境、约束和反馈系统”。代码生成变快之后，稀缺的东西变成了注意力、判断和可验证的上下文。

如果你现在已经在团队里使用 Codex，这篇文章值得反复看。它提醒我们，下一阶段的工程能力可能不再只体现在谁写得快，而是体现在谁能把仓库改造成一个让智能体稳定工作的系统。