# OpenAI《Harness Engineering》深读:loop engineering 之前,先得把脚手架搭对

> 更新日期:2026/06。本篇是 loop engineering 深读系列的第 11 篇,深挖 OpenAI 官方博客《Harness Engineering: Leveraging Codex in an Agent-First World》(2026-05-27,作者 Ryan Lopopolo),它是目前唯一一份一手实践来源,也是 harness engineering 这个术语的定义性文本。

## TL;DR

OpenAI 的 Codex 团队用 **5 个月、3 个工程师(后来扩到 7 个)、0 行手写代码**,构建了一个约 **100 万行**代码、有真实内外部用户、能正常 ship/deploy/break/fix 的软件产品。整个过程中合并了约 **1500 个 PR**,平均 **3.5 PRs/engineer/day**,单次 Codex run 经常在单个任务上连续工作 **6 小时以上**(通常在工程师睡觉时)。

这篇博客真正贡献的不是这些数字,而是一个判断:**当一个团队的主要工作不再是写代码,而是设计环境、指定意图、构建让 agent 可靠工作的反馈循环时,工程纪律就从代码转移到了脚手架(scaffolding)**。OpenAI 把这套纪律命名为 **harness engineering**,它的三大支柱是 legibility(可读性)、repo-as-record(仓库即记录)、mechanical enforcement(机械式强制)。

在 loop engineering 的三层框架里(context → harness → loop),harness 是中间层,是 loop 能成立的地基。本篇就是来拆这个地基的:它到底是什么、里面装了什么、和 loop 怎么衔接、以及它和外部 agent runtime 的关键区别。

## 为什么这篇值得单独深读

loop engineering 这门手艺目前散落在五份主要材料里:Anthropic 的 DSD、Tosea 的综述、Truefoundry 的 runtime 视角、一些创业公司的高层访谈。这五份里,**只有 OpenAI 这一份是「正在做这件事的人,自己写的战报」**。其余四份都是综述、分析或第三方观察。

这个区别重要。综述文章会把概念梳理得很干净,但拿不到一手数字;OpenAI 这份恰好相反,它写得不那么教科书,但每个论断背后都有真实的代码量和 PR 在撑。本系列前几篇在讲 loop engineering 的概念地图,这一篇是地图上那块写着「这里有人真的走过」的标记。

具体来说,这份材料的独特价值有五点:

1. **唯一的一手硬数据**:100 万行 / 1500 PR / 3.5 PRs/engineer/day / 0 行手写 / 5 个月 / 单 run 6 小时+。其他材料给的是轶事,OpenAI 给的是统计。
2. **harness engineering 的最权威定义**:这篇是 harness 这个术语被大规模使用的源头之一。legibility / repo-as-record / mechanical enforcement / progressive disclosure 这四个概念必须从这里引用,而不是从二手综述转述。
3. **独有的具体机制**:**doc-gardening agent(文档园艺 agent)、golden principles(黄金原则)、garbage collection(垃圾回收)** 这三件套,只在 OpenAI 这份材料里出现过。它们把 loop engineering 从「设计一个循环」推进到「设计一个自治维护代码库的 agent 生态系统」。
4. **对「不泛化」的诚实**:OpenAI 自己写了警告,说他们的端到端自治「重度依赖这个 repo 的特定结构和工具,不应假定无需类似投入就能泛化,至少现在不能」。这种诚实是综述文章里看不到的。
5. **合并哲学的反转**:他们提出「corrections are cheap, waiting is expensive」(纠正便宜、等待昂贵),直接挑战传统工程规范。这是所有材料里最激进的运营主张。

## 心智模型:代码是 agent 开的车,harness 是给 agent 铺的路

在讲具体机制之前,先把 harness 这个词固定下来。它容易和另外两个词混:context(上下文)和 loop(循环)。loop engineering 的共识框架是三层结构:

- **context 层**:agent 运行时能拿到什么信息。包括 system prompt、tools、可读到的文件、历史会话。
- **harness 层**:agent 单次运行所处的完整环境。它决定 agent 在一次 run 里能用什么工具、有什么权限、碰到什么约束、如何得到反馈。
- **loop 层**:在时间维度上调度 harness。决定跑哪些任务、什么时候跑、跑出来的结果什么算 done、谁来判断。

用一句话区分:harness 是「一次 run 的内部环境」,loop 是「在时间上调度多次 run」。

用一个类比来固定:harness engineering 就像给 agent 铺好高速公路并装上护栏,代码(写什么实现)是 agent 自己开的车。工程师的工作不是替 agent 开车,而是修路、装护栏、立路标。车开得快不快、会不会翻,很大程度取决于路修得好不好,而不是车本身。

这个类比能解释 OpenAI 文章里几个反直觉的现象。第一,为什么团队规模从 3 人扩到 7 人,人均 PR 产出反而上升?因为路越修越好,任何一辆车跑在上面都快。第二,为什么「0 行手写代码」不是噱头?因为工程师的全部精力都用来修路了,没人需要去抢方向盘。第三,为什么他们敢让 Codex 单次 run 跑 6 小时?因为护栏足够硬,跑偏了会立刻被机械式约束拦下来,不会失控。

理解了这个类比,就能理解 OpenAI 那句核心断言为什么成立:**「building software still demands discipline, but the discipline shows up more in the scaffolding rather than the code」**(开发软件仍然需要纪律,但纪律更多体现在脚手架而不是代码上)。

需要警惕的一个术语陷阱:OpenAI 说的 harness,和 Truefoundry 说的「Agent Harness」,不是同一个东西。OpenAI 的 harness 是 **intra-agent**(agent 内部脚手架)——agent 跑起来时能读到的 repo 结构、能调用的工具、会撞上的 linter。Truefoundry 的 harness 是 **extra-agent**(agent 外部运行时)——给 agent 发身份、管预算、设 gate 的那一层外壳。两者都叫 harness,但层次完全不同。本篇讲的是 OpenAI 版。建议在团队内部用 intra-agent harness 和 extra-agent runtime 这两个词区分,避免开会吵半小时发现彼此在说不同的东西。

## 详细机制:三大支柱、三件套、一个 Loop、一个反转

下面逐个拆 OpenAI 在文章里描述的具体机制。所有数字和原话都来自原文,不掺二手转述。

### 先看基本面:实验长什么样

把最硬的一手数据集中列一遍,后面所有机制都是为了让这些数字成立:

- **时间线**:2025 年 8 月末首次 commit 到空仓库,5 个月后写这篇文章。
- **代码量**:约 **100 万行**。覆盖范围包括应用逻辑、基础设施、内部工具、文档、可观测性、内部开发者工具——全部由 Codex 写。
- **人力**:3 个工程师起步,扩到 7 个。**全程 0 行手写代码**。
- **吞吐**:约 **1500 个 PR** 被打开并合并。平均 **3.5 PRs/engineer/day**。团队扩张到 7 人后,人均吞吐反而上升(反直觉,后面解释)。
- **速度估计**:他们自己的估计是约手写时间的 **1/10**。
- **产品状态**:有内部每日用户 + 外部 alpha 测试者,正常 ship、deploy、break、fix。
- **长 run**:经常看到单次 Codex run 在单个任务上工作 **6 小时以上**,通常在工程师睡觉时。
- **初始 scaffold**:repo 结构、CI、formatting rules、package manager、app framework 都由 Codex CLI 用 GPT-5 生成。**连 AGENTS.md 都是 Codex 自己写的**。

最后一个点值得停一下。很多团队在引入 agent 时,第一件事是手写一份详尽的 AGENTS.md 当作「agent 使用手册」。OpenAI 的做法是反过来:让 agent 先写自己的手册,人再修。这背后的逻辑是,如果 agent 写不出自己的手册,说明它对 repo 的理解还不够 legible,这时人写的手册也只是人脑里的知识强行外化,不一定对得上 agent 实际能读到的东西。

### 第一支柱:legibility(可读性)

legibility 是 OpenAI 整篇文章的核心概念。它的定义不是「代码读起来优美」,而是「**agent 能不能在运行时直接从 repo 读出它需要的全部信息**」。原文有一句关键的范式宣言:

> 「From the agent's point of view, anything it can't access in-context while running effectively doesn't exist. Knowledge that lives in Google Docs, chat threads, or people's heads are not accessible to the system.」

从 agent 的视角看,任何它在运行时无法在上下文里访问到的东西,都等于不存在。活在 Google Docs、聊天记录、人脑子里的知识,对系统是不可达的。

这句话的逻辑链条很硬:agent 不能用「我没看到」当借口,因为 agent 的能力边界就是它的上下文边界。所以任何想让 agent 正确处理的约束,都必须以 agent 能读到的方式放进 repo。OpenAI 把这个原则推到了极致——他们甚至对齐架构模式的 Slack 讨论,如果 agent 发现不了,就被算作 illegible(不可读),就像一个三个月后入职的新人不知道这场讨论一样。

legibility 的第一个具体动作,是让应用本身对 agent 可读。OpenAI 做了三件事:

**1. 应用按 git worktree 可启动**。Codex 能针对每一个改动启动并驱动一个独立的应用实例。这意味着 agent 不需要等共享环境腾出来,也不会因为自己在调试而影响别人。

**2. 把 Chrome DevTools Protocol 接入 agent runtime**。OpenAI 专门创建了处理 DOM snapshots、screenshots、navigation 的 skills。这让 Codex 能复现 bug、验证修复、直接推理 UI 行为。这是从「agent 只能看代码」升级到「agent 能看应用跑起来的样子」。

**3. 可观测性工具同理开放**。logs、metrics、traces 通过一个 local observability stack 暴露给 Codex,每个 worktree 一份 ephemeral 实例,任务完成后拆掉。Codex 能用 LogQL 查 logs、用 PromQL 查 metrics。于是像「ensure service startup completes in under 800ms」(确保服务启动在 800ms 内完成)或「no span in these four critical user journeys exceeds two seconds」(这四条关键用户路径里的任何 span 不超过两秒)这种 prompt 就变得可执行——agent 自己去查指标,自己判断是否达标,不需要人来复核。

这三件事合起来,把 agent 从「能读代码」升级到「能读整个运行时」。这是 legibility 的最高形态。

legibility 还有一个反直觉的推论:**偏好无聊技术,必要时不惜重实现公共库**。原文说:

> 「We favored dependencies and abstractions that could be fully internalized and reasoned about in-repo.」

他们偏好那些能在 repo 内被完全消化和推理的依赖和抽象。被描述为「boring」的技术,对 agent 更容易建模——因为这些技术的组合性、API 稳定性、在训练集里的覆盖率都更好。一个具体例子:与其拉通用的 `p-limit` 包,他们自己实现了一个 map-with-concurrency helper。理由是自实现的版本能和 OpenTelemetry 紧密集成、做到 100% test coverage、行为完全符合 runtime 预期。绕开公共库的 opaque 行为,对 agent 来说,有时候比自己写一遍还贵。

这条推论对选型决策影响很大。传统工程评估一个依赖,看的是功能、性能、社区。agent 时代还要多加一条:这个依赖能不能被 agent 完全消化进 repo?如果不能,自己实现可能更便宜。

### 第二支柱:repo-as-record(仓库即记录)

第二个支柱是**把仓库当作唯一真实源(system of record)**。这条最容易讲懂,也最容易做错。

OpenAI 对 context management 的第一句忠告是:

> 「Give Codex a map, not a 1,000-page instruction manual.」

给 Codex 一张地图,不是一本 1000 页的说明书。

他们列了四条反对单体手册(monolithic manual)的理由,这四条值得原样记住,因为它们是判断「这份 AGENTS.md 是不是该减肥」的硬标准:

1. **Context is a scarce resource**(上下文是稀缺资源)。一份巨大的指令文件会挤掉任务描述、代码、相关文档的空间。agent 要么漏掉关键约束,要么开始优化错的约束。
2. **Too much guidance becomes non-guidance**(太多指导等于没有指导)。当一切都被标成「重要」时,什么都不重要。agent 最终在做局部模式匹配,而不是有意图地导航。
3. **It rots instantly**(它立刻腐烂)。单体手册会变成陈旧规则的坟墓。agent 分不清哪些规则还成立,人停止维护,这份文件悄悄变成一个 attractive nuisance(惹祸的东西)。
4. **It's hard to verify**(它难以验证)。一个大 blob 无法被机械检查(覆盖率、新鲜度、所有权、交叉引用),漂移不可避免。

OpenAI 的对策是把知识库分层。`AGENTS.md` 只保留约 100 行,作用是目录表(map),指向 repo 里更深处的真实源。真正的知识住在结构化的 `docs/` 目录里,布局如下:

- **设计文档**被编目并索引,每份带 verification status(验证状态),加上一组定义 agent-first 操作原则的 core beliefs。
- **架构文档**提供 domains 和 package layering 的顶层 map。
- **质量文档**给每个 product domain 和架构层打分,跟踪 gaps 随时间的变化。
- **plans 作为一等公民**:轻量临时 plan 用于小改动;复杂工作 captured 在 execution plans 里,带 progress 和 decision logs,全部 check 进 repo。active plans、completed plans、known technical debt 全部 versioned 且 co-located。这让 agent 不需要依赖外部 context(比如某个 Notion 页面或某条 Slack 消息)就能复现决策。

这套布局实现了 **progressive disclosure**(渐进式披露):agent 从一个小而稳定的入口开始,被指引接下来去哪看,而不是一上来就被淹没。这个概念借自前端交互设计——人打开一个复杂界面,不会一次看到全部选项,而是从主菜单逐层下钻。agent 的 context 窗口就是一个有限的「屏幕」,把它的注意力引导到对的位置,比塞给它所有信息更有效。

这套做法有一个隐藏的好处:它把知识的所有权(owner)也分散到了 repo 各处。一份单体 AGENTS.md 没有明确的 owner,谁都觉得别人会维护,最后没人维护。但一份 `docs/architecture/providers.md` 天然属于架构 owner,一份 `docs/domains/app-settings.md` 天然属于 settings domain 的 owner。OpenAI 让 CI 校验这些文档的 cross-link 和结构,等于把「文档所有权」这件事也 mechanically enforced 了。

这一点对应 loop engineering 6 原语里的 **skills(SKILL.md)原语**,但 OpenAI 把它做深了一层。多数团队理解的 skill 是「一个 SKILL.md 文件 + 一组 references」。OpenAI 版的 skill 是「整个结构化、可验证、自维护的知识库」,skills 不只是文件,而是一个能被 agent 导航、被 linter 检查、被 doc-gardening agent 修剪的活系统。

理解这个差异很重要,因为它决定了你的 agent 在多大程度上「知道自己知道什么」。一个只有单体手册的团队,agent 每次都要重新理解整个手册,而且会因为 context 不够而漏掉后半部分。一个有结构化知识库的团队,agent 能按需下钻,context 预算花在真正相关的部分。这是「agent 能跑」和「agent 能跑好」的分水岭。

### 第三支柱:mechanical enforcement(机械式强制)

前两个支柱是「让 agent 能读懂」,第三个支柱是「让 agent 不能乱来」。文档本身无法保证一个完全 agent-generated 的 codebase 保持 coherent。OpenAI 的做法是用机械式约束代替口头规范。

他们采用了一个 **rigid architectural model**(刚性架构模型):每个 business domain 被分成固定层数,strictly validated dependency directions 加 limited permissible edges。约束通过 custom linters(由 Codex 生成)+ structural tests 来强制。

具体到架构规则:每个 business domain(比如 App Settings)内部,代码只能「向前」依赖穿过固定层数,**Types → Config → Repo → Service → Runtime → UI**。Cross-cutting concerns(认证、connectors、telemetry、feature flags)通过单一显式接口 **Providers** 进入。其他依赖路径一律禁止,而且是 mechanically enforced。

原文有一段对这套架构的反直觉评价:

> 「This is the kind of architecture you usually postpone until you have hundreds of engineers. With coding agents, it's an early prerequisite: the constraints are what allows speed without decay or architectural drift.」

这种架构通常是等到团队有几百人才会动手做的。有了 coding agent,它成了早期前提:正是这些约束让速度不至于伴随 decay 或 architectural drift。

这个判断直接挑战了「先快速迭代、欠点债再说」的 startup 工程习惯。在 agent 时代,架构债的复利速度被 agent 放大了——agent 会复制现有 pattern,不管这个 pattern 好不好。如果不早期强制架构,几周后整个 codebase 就会被 agent 复制成自己最差的样子。OpenAI 的结论是,在 agent 时代,架构约束不是后期优化,而是 day-one 前提。

除了架构规则,他们还静态强制一批 **taste invariants**:structured logging、naming conventions for schemas and types、file size limits、platform-specific reliability requirements。关键设计是,因为 lints 是 custom 写的,他们把 error messages 写成「往 agent context 注入 remediation instructions」——lint 报错本身,就是给 agent 的修复指令。

这是一种很聪明的反馈回路设计:agent 触发 lint → lint 报错 → 报错文本直接告诉 agent 怎么修 → agent 自己修 → 重跑。整个过程不需要人介入。如果你做过 ESLint custom rule,你会知道把 error message 写成「human-readable explanation」是常见做法;OpenAI 把它升级成「agent-readable remediation」,等于把每个 lint rule 变成了一个 micro-loop。

贯穿这套强制的哲学,原文用一句话概括:

> 「By enforcing invariants, not micromanaging implementations, we let agents ship fast without undermining the foundation.」

通过强制不变量而不是微操实现,我们让 agent 能快速 ship,又不破坏地基。

更凝练的版本:**enforce boundaries centrally, allow autonomy locally**(中央强制边界,局部允许自治)。这像管理一个大型工程平台组织:深切关心 boundaries、correctness、reproducibility;边界之内,允许团队(或 agent)显著自由。结果代码不一定匹配人类风格偏好,但只要 correct、maintainable、legible to future agent runs,就算达标。

一个持续的回流机制:**human taste 捕获一次,然后在每行代码上持续强制**。review comments、refactoring PRs、user-facing bugs 都会被捕获,变成文档更新,或直接 encode 进 tooling。原文有一句很关键的句子:

> 「When documentation falls short, we promote the rule into code.」

当文档不够时,我们把规则提升成代码。

这句话值得每个写 AGENTS.md 的人贴在屏幕上。文档是软约束,会被 agent 忽略;code(linter、test、CI)是硬约束,agent 躲不过。如果一个规则反复被违反,别再写进文档了,把它写进 linter。

### 三件套:doc-gardening agent、golden principles、garbage collection

三个支柱之上,OpenAI 还建了三个只在他们的材料里出现过的具体机制。这三个机制合起来,是他们对抗「agent 自治必然产生熵」的核心武器。我把它叫做三件套。

**第一件:doc-gardening agent(文档园艺 agent)**。

文档会腐烂,这是常识。OpenAI 不靠人来维护文档,而是跑一个 recurring 的 doc-gardening agent,专门扫描那些不再反映真实代码行为的陈旧或过时文档,然后开 fix-up PR。专门的 linters 和 CI jobs 负责验证知识库是否 up-to-date、cross-linked、结构正确。

这个名字选得好——「gardening」(园艺)比「maintenance」(维护)更准确。维护暗示「坏了再修」,园艺暗示「持续修剪、除草、引导」。文档不是坏了才需要动,而是需要持续的轻度干预,否则它就会 overgrow 成无法导航的丛林。

这个 agent 对应 loop engineering 的一个新方向:**让 agent 维护 agent 自己用的知识库**。这是 loop 从「跑任务」升级到「维护能跑任务的环境」的标志。

**第二件:golden principles(黄金原则)**。

OpenAI 发现,Codex 会复制 repo 里已有的 pattern——即使这个 pattern 不均匀或次优。随着时间,必然 drift。初期他们靠人手动清理,团队曾经每周五花 20% 的时间清理「AI slop」(AI 拉的垃圾)。不出所料,这不 scale。

对策是把 **golden principles** 直接 encode 进 repo。这些 principles 是 opinionated、mechanical 的规则,用来保持 codebase 对未来 agent run 可读且一致。两个原文例子:

1. 偏好 shared utility packages 而不是 hand-rolled helpers(把不变量集中化)。
2. 不「YOLO-style」probe data——要么 validate boundaries,要么 rely on typed SDKs,让 agent 不能意外 build 在猜出来的数据 shape 上。

golden principles 的本质是:把团队品味(taste)固化成可机械执行的规则。人不用每次 review 都重复说「别手搓 helper,用 shared package」,这个品味被 encode 一次,然后由 lint rule 在每一行代码上持续强制。

**第三件:garbage collection(垃圾回收)**。

doc-gardening 是修剪文档,garbage collection 是清理代码。OpenAI 跑一组 background Codex tasks,定期扫描 deviations、更新 quality grades、开 targeted refactoring PRs。这些 PR 多数能在 1 分钟内 review 并 automerged。

原文用了垃圾回收做类比,这个类比选得很准:

> 「This functions like garbage collection. Technical debt is like a high-interest loan: it's almost always better to pay it down continuously in small increments than to let it compound and tackle it in painful bursts.」

这就像垃圾回收。技术债就像高息贷款:几乎总是用小额持续还清,比让它复利增长再痛苦地集中处理要好。

这里和内存垃圾回收的对应关系是:GC 不是「消灭所有垃圾」,而是「让垃圾积累速度低于清理速度,使系统长期可用」。agent 代码也一样,你不可能消灭所有 suboptimal pattern,但你可以让 background agent 持续清理,让 codebase 始终处于「对下一个 agent run 足够 legible」的状态。

三件套合起来回答了一个关键问题:**完全 agent 自治的 codebase 怎么不腐烂?**答案是让另一组 agent 持续修剪。这是 loop engineering 超越 L3(无人值守单任务)的下一站——不是单个 loop,而是一个自治维护 codebase 的 agent 生态系统。

这里值得停下来想一下「20% 时间清理 AI slop 不 scale」这句话的分量。OpenAI 是 7 个工程师的团队,每周五花 20% 时间清理,等于 1.4 个全职人力专门收拾 agent 拉的垃圾。这个成本对一个小团队已经不可接受,对一个想复制 OpenAI 做法的团队更是致命。他们最终用 background agent 替代人工清理,不是锦上添花,是被迫的。这给所有想上 agent loop 的团队一个硬指标:**如果你还没有自动化的垃圾回收机制,你的 agent loop 跑两周后就会被自己产生的 slop 淹没**。先建 garbage collection,再放开 agent 吞吐,顺序不能反。

三件套还隐含一个对「文档」「规范」「技术债」这三个传统概念的重新定义。在 agent 时代,文档不是给人读的说明,而是 agent 能 query 的数据库;规范不是 code style guide,而是 lint rule 里 encode 的 remediation;技术债不是 backlog 里的一条条 issue,而是一组 background agent 持续偿还的高息贷款。这三个概念的形态全变了,harness engineering 就是这些新形态的总和。

### Ralph Wiggum Loop:OpenAI 给自己工作流的命名

讲完了 harness 内部,来看 harness 和 loop 的衔接点。OpenAI 明确给自己推动 PR 到完成的工作流起了名字:**Ralph Wiggum Loop**。

原文定义:

> 「To drive a PR to completion, we instruct Codex to review its own changes locally, request additional specific agent reviews both locally and in the cloud, respond to any human or agent given feedback, and iterate in a loop until all agent reviewers are satisfied (effectively this is a Ralph Wiggum Loop).」

为了把 PR 推到完成,他们指示 Codex 本地 review 自己的改动、本地和云端都请求额外的特定 agent review、响应任何来自人或 agent 的反馈、在一个 loop 里迭代直到所有 agent reviewer 满意(实际上这就是一个 Ralph Wiggum Loop)。

这个名字和 DSD 的 Ralph Loop 同源,指 Geoffrey Huntley 在 2025 年 7 月提出的 pattern。OpenAI 等于在自己的官方博客里,把这个 pattern 正式命名并落地。

几个关键细节:

- Codex 直接用标准开发工具(github CLI、本地 scripts、repo 内嵌 skills)gather context,**不需要人 copy-paste 进 CLI**。
- 人可以 review PR,但**不被要求**。原文说「Over time, we've pushed almost all review effort towards being handled agent-to-agent」(随着时间,我们把几乎所有 review 工作推到了 agent-to-agent 处理)。

这一点对应 loop engineering 6 原语里的 **verifier(maker/checker 分离)原语**。Ralph Wiggum Loop 就是 maker/checker 的官方实现版本:maker agent 写代码,checker agent review,两者分离,迭代到收敛。

Ralph Wiggum Loop 正好站在 harness 和 loop 的边界上。它用到的所有工具(self-review、agent reviewer、CI、反馈处理)都属于 harness(单次 run 内的反馈机制);但「在一个 loop 里迭代直到所有 reviewer 满意」这个调度行为,已经跨进了 loop 层。它是 harness 向上托起 loop 的那个接口。

### 合并哲学的反转:corrections cheap, waiting expensive

吞吐上升后,OpenAI 发现许多常规工程规范变得适得其反。原文有一段直接挑战传统工程习惯的论述:

- 仓库用**最小 blocking merge gates** 运作。
- PR 短命。
- **Test flakes 通常用 follow-up runs 处理,而不是无限阻塞进展**。

核心断言是:

> 「In a system where agent throughput far exceeds human attention, corrections are cheap, and waiting is expensive.」

在一个 agent 吞吐远超人类注意力的系统里,纠正是便宜的,等待是昂贵的。

还有一句自我警示:

> 「This would be irresponsible in a low-throughput environment. Here, it's often the right tradeoff.」

这在低吞吐环境是不负责任的;在这里常常是对的 tradeoff。

这个反转的逻辑值得拆开看。传统工程里,等 CI 跑完再合并是为了避免坏代码进主干,因为人的时间宝贵,每修一次 flake 都要占用一个工程师的注意力。但在 agent 时代,agent 吞吐远超人注意力,flake 如果只是偶发,重跑一次的 token 成本远小于一个工程师停下来排查的成本。所以正确的做法是让 follow-up run 自动重跑,人只在 flake 变成系统性问题时介入。

注意这个反转有严格的前提:**只在 agent 吞吐远超人注意力的系统里成立**。低吞吐团队照搬,等于放任坏代码累积。这是本篇要诚实传达的边界之一。

## 真实案例:这个 100 万行的产品本身就是证据

OpenAI 的材料有一个独特优势:它描述的产品本身就是 loop engineering 的最强证据。不需要构造额外案例。

最戏剧性的段落是他们描述 repo 跨过的那个自治阈值。原文说,随着更多开发 loop 被编码进系统(testing、validation、review、feedback handling、recovery),**给定单个 prompt,Codex 现在能端到端驱动一个新 feature**。具体是 11 步:

1. 验证 codebase 当前状态。
2. 复现一个 reported bug。
3. **录制视频展示失败**。
4. 实现修复。
5. **通过驱动应用验证修复**。
6. **录制第二段视频展示问题已解决**。
7. 开 PR。
8. 响应 agent 和 human feedback。
9. 检测并修复 build failures。
10. **只在需要判断时升级给人**。
11. 合并改动。

注意第 3 步和第 6 步——agent 会**录视频**。这需要 Chrome DevTools Protocol 接入、需要应用按 worktree 可启动、需要可观测性 stack 全部就位。这是 legibility 支柱的直接产物。第 10 步是关键:「只在需要判断时升级给人」——这是 L3(无人值守)的标志,但仍是 L3 的早期形态,因为「需要判断」这个阈值本身还需要人来触发。

原文对这个成就给了一个很克制的警告,这份克制必须忠实传达:

> 「This behavior depends heavily on the specific structure and tooling of this repository and should not be assumed to generalize without similar investment—at least, not yet.」

这个行为重度依赖这个 repo 的特定结构和工具,不应假定无需类似投入就能泛化,至少现在不能。

这一句是所有想抄 OpenAI 做法的团队必须先读三遍的。他们能端到端,是因为他们已经投了:rigid architecture、custom linters、doc-gardening agent、per-worktree bootable app、Chrome DevTools skills、local observability stack。绝大多数团队没有这些投入,直接抄「给定一个 prompt 让 agent 跑 11 步」会失败。

还有一句对工程师角色重新定义的话,值得放在这里。原文说,早期进度比预期慢,不是因为 Codex 不行,而是因为环境欠规范——agent 缺乏做高层目标进展所需的工具、抽象、内部结构。所以工程师的主要工作变成了「enabling the agents to do useful work」。当某件事失败时:

> 「The fix is almost never to try harder. ... The answer is always to ask: what capability is missing, and how do we make it both legible and enforceable for the agent?」

修复几乎从来不是「再努力一点」。答案永远是问:缺什么能力?怎么让它对 agent 既可读又可强制执行?

这句话是工程师角色转换的核心。传统工程师 debug 时问「这段代码哪里错了」,agent 时代的工程师 debug 时问「这个环境缺什么 legible 且 enforceable 的能力」。问题域从代码转移到了 harness。

## 权衡与局限:0 手写、6 小时 run、和那个不披露的成本

OpenAI 的故事很漂亮,但有几个边界必须诚实指出,否则读者会误判可借鉴性。

**第一,「0 行手写代码」的绝对性是修辞选择**。prompt、AGENTS.md 的初始版本、architectural decisions、lint rules 里的「taste」——这些都是「写代码」的等价物。OpenAI 的定义把「写 prompt / 设计架构 / 定 invariant」排除在「写代码」之外。这不是说他们撒谎,而是说「0 行手写代码」描述的是一个特定切面(没有 .ts/.py 文件是人手敲的),不是「工程师什么都没做」。工程师做了大量高杠杆的设计工作,只是这些工作的产物不是代码行,而是 harness。

**第二,泛化性警告是真实的**。OpenAI 自己说「should not be assumed to generalize without similar investment」。他们的结果依赖一长串前置投入,绝大多数团队没有。盲目复制会失败。这不是 loop engineering 不行,是这套 harness 还没建好就想跑 loop。

**第三,成本不透明**。100 万行 / 1500 PR / 6h+ run 的 token 成本是天文数字,但 OpenAI 完全不披露。对 OpenAI 来说 token 不是约束(他们是模型提供商),对普通团队来说这是硬约束。DSD 在别处明确指出过这一点。这意味着 3.5 PRs/engineer/day 这个数字,对用第三方 API 的团队来说是不可复制的——你可能在第 200 个 PR 就因为账单停手。所有引用这个数字的人,都应该同时引用这个前提。

**第四,harness engineering 术语的重载**。已经在心智模型那节强调过,这里再压成一句:OpenAI 的 harness(intra-agent,agent 内部脚手架)≠ Truefoundry 的 Agent Harness(extra-agent,agent 外部 runtime)。两者都叫 harness,层次不同。读完本篇去读 Truefoundry 那篇时,先在脑子里做一次术语翻译。

**第五,agent-to-agent review 的质量未验证**。OpenAI 说「pushed almost all review effort towards agent-to-agent」,但没给 review 质量数据。这是 cognitive surrender(认知 surrender,指人逐渐失去对 codebase 理解)的高风险点——如果 reviewer agent 和 maker agent 共享盲点,错误会 compound,而且人不在环里,错误能藏得更久。OpenAI 的 doc-gardening 和 golden principles 是缓解措施,但原文承认「what we don't yet know is how architectural coherence evolves over years」(我们尚不知道架构连贯性在年尺度上如何演化)。长期认知债务仍是开放问题。

这个风险值得展开。maker agent 和 checker agent 往往来自同一个模型家族、读同一份 AGENTS.md、用同一套 lint rule。如果某个架构层存在设计盲点——比如「跨 domain 的 Provider 接口缺了一个错误码标准」——maker 不会主动加,checker 也读不出这是问题,因为 checker 的判断依据同样是这份有盲点的文档。结果是错误以「符合规范」的姿态沉淀下来,直到某个 user-facing bug 把它暴露。在人主导的 review 里,资深工程师的直觉能闻出这种「合规但不对」的味道;在 agent-to-agent review 里,这种直觉缺席。OpenAI 的 golden principles 试图把这种直觉固化成规则,但「直觉→规则」的转换本身就有损,无法 100% 还原。这是 harness engineering 留给未来的最大债务。

**第六,合并哲学的反转有适用前提**。「corrections cheap, waiting expensive」只在「agent throughput far exceeds human attention」时成立。低吞吐团队照搬会导致质量崩塌。判断标准是:你的 agent 是不是真的经常在排队等人?如果人比 agent 忙,这个反转成立;如果 agent 经常等人,这个反转不成立。具体一点:如果你的团队每天 agent 只能产出 3-5 个 PR,而你有 5 个工程师能 review,那等待 CI 重跑的成本其实是你自己注意力的成本,这时候「等 CI」反而是负责任的做法。OpenAI 之所以能反转,是因为他们 3 个工程师面对的是每天 10+ PR 的洪流,注意力才是真稀缺品。

另一个隐藏前提是「corrections」必须真的便宜。如果你的 follow-up run 不是自动触发而是要人手动点,如果你的 flake 不是偶发而是系统性,如果你的坏代码一旦合进主干会影响其他 agent 的 run——这些情况下 corrections 一点都不便宜。OpenAI 的 corrections 便宜,是因为他们有 per-worktree isolation 和 background garbage collection 兜底。没有这两层的团队,「corrections cheap」是一句空话。

**第七,立场的局限**。作者是 OpenAI 员工,产品是 Codex。这是 Codex 的 case study,天然有产品宣传成分。把 OpenAI 的结果当「loop engineering 已经到达 L3」的信号是对的,但把它当「任何团队都能复制」的承诺是错的。

## 落地建议:从 harness 到 loop 怎么衔接

读完这份材料,一个团队如果想往 loop engineering 走,合理的顺序是什么?基于 OpenAI 的经验和前面拆的机制,给一个务实的衔接路径。

**第一步:先做 legibility,别先做 loop**。多数团队一上来就想跑无人值守的 loop,这是错的。OpenAI 的顺序是先把 repo 变得对 agent 可读:AGENTS.md 减肥到 100 行以内,只做 map;把真正的知识结构化进 `docs/`;把 architectural decisions encode 成可验证的文档。这一步没做好,loop 跑得越快,agent 偏得越远。

**第二步:把口头规范升级成 mechanical enforcement**。挑三条你最在意的规范(比如「不允许跨层依赖」「所有 logging 必须 structured」「helper 必须放 shared package」),把它们写成 custom lint rule。lint 报错信息写成给 agent 看的 remediation instructions。这一步把 harness 从「能读」升级到「不能乱来」,是 Ralph Wiggum Loop 能收敛的前提。

**第三步:在 harness 内部先跑通 maker/checker**。在跑任何外部 loop 之前,先让一个 agent run 内部能完成「写代码 → self-review → 请求第二个 agent review → 响应反馈 → 收敛」。这就是 Ralph Wiggum Loop 的核心。如果单次 run 内 maker/checker 收敛不了,外部 loop 调度多次 run 只会放大不收敛。

判断 maker/checker 是否收敛的硬标准是:一个 PR 从开到合并,平均需要人介入几次?OpenAI 的答案是接近 0 次。如果你的答案还在 2-3 次,说明 harness 里缺东西——可能是 lint 不够严(agent 写得出不合规代码),可能是 AGENTS.md 不够 legible(agent 读懂不了意图),可能是可观测性没接(agent 无法自验证)。先把这些补齐,再谈外部 loop。

**第四步:再加 isolation 和长 run**。当 harness 内 maker/checker 能收敛,再让应用按 worktree 可启动(让 agent 能跑独立实例),再把可观测性接进来(让 agent 能自己查 metrics)。这两件到位后,agent 才能做 OpenAI 那 11 步里的「复现 bug → 录视频 → 验证修复」。

这一步的投入往往被低估。让一个应用按 worktree 可启动,意味着应用的配置、依赖、数据迁移都要支持「每个分支一个独立实例」。这对很多遗留系统是伤筋动骨的改造。OpenAI 能做到是因为整个 repo 从第一天就是 agent-generated、为 legibility 设计的。一个有十年历史的人类写的 codebase,要补这一层可能要花半年。这是「agent 原生」和「agent 改造」的天然鸿沟。

**第五步:最后才加 schedule 和外部 loop**。这是 loop engineering 的最上层。当单次 run 能稳定 6 小时+,再考虑在时间维度上调度多个 run。到这一步,你已经在 OpenAI 的水平线上了。

但即使到这一步,也别指望完全无人。OpenAI 的 11 步里第 10 步明确写了「只在需要判断时升级给人」——这意味着人还是在环里,只是从「每步都在」退到「只在判断点在」。loop engineering 的 L3 不是「零人工」,而是「人工只出现在判断点」。把这一点传达给想全自动的管理层,避免他们对 L3 抱有错误的期待。

**贯穿所有步骤的一件事:每发现一条反复被违反的规则,把它从文档提升成 code**。OpenAI 那句「When documentation falls short, we promote the rule into code」是贯穿 harness engineering 全程的口诀。文档是软约束,code 是硬约束。harness engineering 的本质,就是持续地把软约束升级成硬约束。

最后一句提醒:不要把 OpenAI 的结果当成 loop engineering 的终点。他们的 doc-gardening agent、golden principles、garbage collection 已经指向更远的方向——一个由 agent 生态系统自治维护的 codebase。但连他们自己都承认不知道这个系统在年尺度上会怎么演化。harness engineering 不是一门已经成熟的手艺,是一门刚刚被定义、正在被最前沿的几个团队现场摸索的手艺。本篇能做的,是把这个定义和这几个团队目前的理解,如实搬运过来。

## 延伸阅读

- **OpenAI《Harness Engineering: Leveraging Codex in an Agent-First World》**(Ryan Lopopolo, 2026-05-27)— 本篇深读的一手来源。原文链接:https://openai.com/index/harness-engineering/
- **本系列其他篇**:loop engineering 深读系列的其他文章,见 `docs/ai-coding/loop-engineering/` 目录。其中关于三层框架(context→harness→loop)和 6 原语的系统梳理,见系列总论篇。
- **Geoffrey Huntley 的 Ralph Loop 原始 pattern(2025-07)**:Ralph Wiggum Loop 的源头。OpenAI 在官方博客里正式命名并落地了这个 pattern。
- **DSD(Drive Stakeholder Decisions / Anthropic 的相关材料)**:对 loop engineering 的概念框架和 L0-L3 成熟度模型的系统梳理。本系列里有专门一篇深读。
- **Truefoundry 的 Agent Runtime 视角**:辨析 extra-agent runtime 与本篇讲的 intra-agent harness 的区别时,参考 Truefoundry 的材料。两者都叫 harness,层次不同。