Extreme Harness Engineering 学习笔记

Table of contents

1. 背景与问题

视频想解决的核心问题

Ryan Lopopolo 讨论的是一个比 Prompt Engineering、甚至比 Context Engineering 更靠后的问题：

• 当 Coding Agent 已经能完成大量编码任务后，人类如何把自己的时间从“盯代码”转移到“设计可自动化的软件交付系统”？
• 如何让 Agent 不只是“偶尔能写对代码”，而是能在真实仓库、真实 PR、真实构建、真实观测体系中持续完成工作？
• 当模型能力持续升级时，团队应该优化什么：模型本身、上下文、还是整个执行环境？

结论先行

Ryan 给出的答案是：

1. 把“手写代码”降为次要工作，甚至人为禁止。
2. 把“构建 Harness”提升为核心工程工作。
3. 把人类的稀缺资源定义为注意力，而不是 token。
4. 把 review、测试、可观测性、文档、规格、工作流都前移为 agent 可消费的结构化上下文。
5. 继续向上抽象：从“管理 agent”走向“管理工作”，这就是 Symphony 的意义。

📡 扩展
OpenAI 在 2026-02-11 的官方文章中，将 Harness Engineering 定义为一种 agent-first 的工程实践：他们用 Codex 在约 5 个月内，从空仓库构建并交付了一个内部 beta 产品，0 行手写代码，仓库规模约 100 万行代码，约 1,500 个 PR，估计耗时约为人工编码的 1/10。官方文章明确强调：人类主要做的是“设计环境、表达意图、建立反馈回路”，而不是直接写代码。
参考：OpenAI《Harness engineering: leveraging Codex in an agent-first world》、OpenAI《Unrolling the Codex agent loop》

2. 核心概念

2.1 Harness Engineering 是什么？

Harness Engineering 不是单点技巧，而是围绕 agent 交付可靠结果而构建的一整套“约束 + 上下文 + 工具 + 反馈 + 编排”系统。

可以把它理解为：

• 对人类：这是新的工程操作系统
• 对 agent：这是它的工作台、护栏、传感器、规则手册和自动化流水线
• 对团队：这是把“偶发成功”变成“可重复交付”的方法

与相近概念的区别

📡 扩展
Martin Fowler 将 Harness 理解为一种“cybernetic governor（控制器）”：通过 feed-forward（前馈约束）与 feedback（反馈传感器）共同调节代码库，使其朝“期望状态”收敛。这个视角非常重要，因为它说明 Harness 不只是“把文档喂给模型”，而是在持续调节系统。
参考：Martin Fowler《Harness engineering for coding agent users》

2.2 Codex Harness 是什么？

在 OpenAI 的语境里，Codex Harness 指的是支撑各种 Codex 体验的核心 agent loop 与执行逻辑。

它不只是一个 CLI，而是包含：

• 线程生命周期与持久化
• 配置与鉴权
• 工具执行
• sandbox 与扩展接入
• 与客户端的双向通信协议

📡 扩展
OpenAI 官方在《Unlocking the Codex harness》里说明：Web、CLI、IDE 扩展、macOS App 底层都复用同一个 Codex harness；App Server 通过双向 JSON-RPC 暴露线程管理、工具执行和事件流，使不同客户端都能接入同一套 agent runtime。
这意味着 “Harness” 在 OpenAI 不是抽象口号，而是具体的软件运行层。
参考：OpenAI《Unlocking the Codex harness: how we built the App Server》

2.3 Skills、AGENTS.md、Spec 的角色分工

📡 扩展
OpenAI 官方文档将 Skill 定义为“可版本化的 instructions + resources + optional scripts 包”，用于把可重复工作封装为稳定能力；同时官方将 AGENTS.md 定义为自动加载到上下文中的仓库级行为说明。两者不是竞争关系，而是分层互补：AGENTS.md 管全局约定，Skill 管可复用流程。
参考：OpenAI Developers《Agent Skills》《Custom instructions with AGENTS.md》《Customization》

3. 主体内容

3.1 从 Prompt 到 Harness 的演化脉络

flowchart TD
    A([起点：只优化提示词]) --> B[Prompt Engineering<br>优化单轮指令]
    B --> C[Context Engineering<br>优化信息装配]
    C --> D[Harness Engineering<br>优化执行环境与反馈回路]
    D --> E[Orchestration<br>从管理 agent 到管理工作]
    E ==> F([目标：稳定、规模化、低监督交付])

    style A fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px
    style B fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px
    style C fill:#fff3e0,stroke:#fb8c00,stroke-width:2px
    style D fill:#fff8e1,stroke:#f9a825,stroke-width:3px
    style E fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px
    style F fill:#e8f5e9,stroke:#43a047,stroke-width:3px

这一演化意味着什么？

字幕里的一个非常关键的变化是：

• 过去：先搭脚手架，再把模型放进固定状态机里跑
• 现在：让 Harness 成为“大盒子”，给模型足够上下文、工具和反馈，让它自己选择执行路径

这对应了 reasoning model 崛起后的工程范式变化：
团队不再预先把所有状态转移硬编码，而是把规则、边界、反馈和资源配置好，让模型在盒子里自主完成更多工作。

📡 扩展
OpenAI 在《Unrolling the Codex agent loop》中把 agent loop 描述为：用户输入 → 模型推理 → 工具调用 → 观察结果 → 更新上下文 → 再推理。这是最小闭环。Harness Engineering 做的事，就是把这个闭环从“能跑”提升到“能在真实工程里稳定运行”。
参考：OpenAI《Unrolling the Codex agent loop》

3.2 零手写代码实验：为什么要故意这么极端？

Ryan 的实验有一个非常强的约束：自己不写代码。

这不是噱头，而是工程策略。

背后的逻辑

• 如果人类还能随手下场补代码，就很难真正暴露 agent 的短板
• 一旦不允许手写代码，团队就被迫思考：
  • 缺的到底是 prompt 吗？
  • 还是缺了更小的构件？
  • 还是缺规格、工具、测试、可观测性、review 流程？
• 这样做会逼着团队把“人脑里的隐性工程经验”外显到仓库中

访谈中的关键观点

Ryan 的表述可以浓缩成两句：

1. 模型不行时，不是先怪模型，而是追问系统里缺了什么能力、上下文或结构。
2. 一旦某类错误反复出现，就把它固化为 Harness 的一部分，不要让人重复消耗注意力。

flowchart TD
    A([Agent 执行任务]) --> B{失败了吗？}
    B -- "❌ 是" --> C[定位失败根因]
    C --> D{缺什么？}
    D -- 上下文 --> E[补文档 / SPEC / AGENTS.md]
    D -- 能力 --> F[补 Skill / Script / Tool]
    D -- 反馈 --> G[补 Test / CI / Review / Observability]
    D -- 结构 --> H[重构构件 / 拆小任务 / 改仓库布局]
    E --> I[把经验沉淀进 Harness]
    F --> I
    G --> I
    H --> I
    I ==> J([下次同类问题自动处理])
    B -- "✅ 否" --> K([继续扩展自动化边界])

    style A fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px
    style B fill:#fff8e1,stroke:#f9a825,stroke-width:3px
    style C fill:#fff3e0,stroke:#fb8c00,stroke-width:2px
    style I fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px
    style J fill:#e8f5e9,stroke:#43a047,stroke-width:3px
    style K fill:#e8f5e9,stroke:#43a047,stroke-width:3px

📡 扩展
OpenAI 官方文章确认，这个实验从空仓库开始，连最初的仓库脚手架、CI 配置和初版 AGENTS.md 都是由 Codex 生成的。也就是说，这不是“人类写好骨架、模型补业务代码”，而是从一开始就在验证 agent-first 的完整链路。
参考：OpenAI《Harness engineering: leveraging Codex in an agent-first world》

3.3 为什么“一分钟构建”会成为核心约束？

这是整期里最值得抄到自己实践里的观点之一。

Ryan 反复强调：inner loop 要尽可能快，目标压到 1 分钟以内。

原因

因为对 agent 来说：

• 长构建时间会拉长反馈周期
• 慢反馈会削弱搜索效率
• 反馈变慢后，agent 更容易停滞、等待、上下文切换
• 最终吞吐下降，人类又被迫回来盯过程

实际动作

他们为了让 agent 高效，把构建系统一路调整：

• bespoke Makefile
• Bazel
• Turborepo
• Nx

这里真正重要的不是“最终选了哪个工具”，而是：
一旦 build 时间超预算，就立即把它视为系统退化信号，停下来分解 build graph，直到恢复到快反馈状态。

📡 扩展
在访谈整理稿中，Ryan 明确说 background shells 让 Codex 可以把耗时命令放后台跑，同时继续做 review 等其他工作；但即便如此，他们仍坚持“把 inner loop 压到 1 分钟”作为工程纪律，因为这能迫使系统维持高反馈密度。
这与传统“构建慢了再做专项治理”截然不同。
参考：Latent Space 访谈整理稿时间段 00:04:43–00:07:45

3.4 Humans are the bottleneck：稀缺资源变成了注意力

Ryan 的核心判断是：

模型与 GPU/token 可以并行扩张，但同步的人类注意力是硬上限。

因此团队关注点从“如何让 agent 多写一点代码”转向：

• 人类时间花在哪？
• 哪些判断可以前移为规则？
• 哪些 review 可以自动化？
• 哪些诊断信息可以直接给 agent，而不是给人看？

这会带来一个角色变化

3.5 Observability first：不给 agent“眼睛”，就只能靠人盯

Ryan 提到一个特别关键的投资方向：不是只给 agent 代码仓库，还要给它足够好的运行态可见性。

原因很直接：

• agent 要修问题，就要先看见问题
• 如果 observability 只有人类能消费，最终还是人来盯
• 真正的目标不是“让人更方便排障”，而是“让 agent 自己能排障”

他们的思路

• 先有 app
• 再快速补本地观测栈
• 用高层、快搭的开发工具把 traces / logs / metrics 拉起来
• 让 agent 能自行启动这套栈，而不是人先手工搭环境

flowchart TD
    A([用户 / 任务]) --> B[Codex Agent]
    B --> C[读仓库 / SPEC / AGENTS.md / Skills]
    B --> D[运行命令 / 构建 / 测试]
    D --> E[应用运行态]
    E --> F[日志]
    E --> G[指标]
    E --> H[链路追踪]
    F --> I[Observability Stack]
    G --> I
    H --> I
    I ==> B
    B --> J{问题定位完成？}
    J -- "❌ 否" --> C
    J -- "✅ 是" --> K([提交修复 / 发起 PR])

    style A fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px
    style B fill:#fff8e1,stroke:#f9a825,stroke-width:3px
    style I fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px
    style K fill:#e8f5e9,stroke:#43a047,stroke-width:3px

📡 扩展
Martin Fowler 在 Harness Engineering 的语境下，把这类机制视为“feedback sensors（反馈传感器）”；OpenAI 官方文章也强调 observability 是 agent 可自治的前提之一。没有观测，agent 只能在代码表层做猜测式修复。
参考：Martin Fowler《Harness engineering for coding agent users》、OpenAI《Harness engineering: leveraging Codex in an agent-first world》

3.6 Skills / 文档 / 规格：把工程品味写进上下文

字幕中最有价值的一段之一，是 Ryan 说他们本质上“从第一性原理重新发明了 skills”。

意思不是产品名，而是实践逻辑：

• 把团队经验拆成可复用、可被 agent 调用的小单元
• 用短总纲 + 多个局部 skill 组织知识
• 让“如何测试、如何 review、如何观察、如何满足非功能约束”变成仓库内显式内容

这部分的本质

不是“多写点文档”，而是：

把人的隐性判断，转成 agent 能反复消费的上下文资产。

例如：

• 代码风格
• 架构边界
• 可观测性要求
• 质量评分方法
• 调试套路
• 评审口径
• 产品习惯和团队偏好

为什么这比“改人”更便宜？

Ryan 说得很直白：
优先把行为变化编码进已有 skills，而不是要求每个工程师每次都手工重复同样的驱动动作。

📡 扩展
OpenAI 官方文档把 Skill 定义为 instructions、resources、optional scripts 的组合；同时强调一旦某种 prompting 模式被证明有效，就应该把它从“临时 prompt”升级为可复用的 AGENTS.md 或 Skill。
这与访谈里的做法高度一致。
参考：OpenAI Developers《Agent Skills》《Best practices》《AGENTS.md》

3.7 Agent-legible software：软件要写给模型，也要写给人

Ryan 的一个重要观点是：
未来的软件结构，不再只追求人类可读，还要追求 agent legibility（对 agent 可读、可消费、可操作）。

这会带来几种变化：

• 统一目录结构与模式
• 减少深层、例外式、不一致的组织方式
• 让包与模块具有更稳定的语义边界
• 把非功能约束写明，而不是靠老人经验口口相传

这不是反人类设计，而是把“人类默认靠经验弥补系统不一致”的债，提前还掉。

3.8 Delegating the PR lifecycle：连 PR 生命周期也能被委托

Ryan 在访谈里讨论了一个很多团队最不舒服的话题：agent merge。

他的立场并不是“永远完全无人工”，而是：

• 大量 review 可以转为 agent review
• 许多 human review 可以后移到 post-merge
• 人类仍保留关键发布口，如 release branch、smoke test、正式分发等

实际上是“重画人机边界”

sequenceDiagram
    participant H as Human
    participant A as Coding Agent
    participant R as Review Agent
    participant C as CI/Test
    participant M as Merge/Release Gate

    H->>A: 提交任务 / 意图 / 规格
    A->>A: 实现代码与测试
    A->>R: 请求本地或云端 review
    R-->>A: 反馈问题 / 可接受意见
    A->>C: 运行构建、测试、检查
    C-->>A: 返回结果
    A->>A: 修复并迭代
    A->>M: 提交 PR / 满足自动门禁
    M-->>H: 仅在关键门口请求确认
    H->>M: Smoke test / release 决策
    M-->>A: 合并或返工

这里真正重要的不是“敢不敢自动 merge”

而是：

• 哪些门禁已经足够结构化？
• 哪些问题可以通过 sensor 检出？
• 哪些高成本 review 可以转为 cheaper review？
• 哪些发布节点必须保留人工把关？

📡 扩展
OpenAI 官方文章说明，他们会要求 Codex 先在本地自审，再请求额外 agent review，并在反馈后反复迭代，直到 reviewer 满意。也就是说，重点不是“取消 review”，而是把 review 从人工同步劳动变成自动化回路的一部分。
参考：OpenAI《Harness engineering: leveraging Codex in an agent-first world》

3.9 Ghost libraries：从分发源码走向分发规格

访谈中出现了一个很有启发性的概念：Ghost Libraries。

其核心思想是：

• 不一定分发完整实现
• 而是分发一份高保真 spec
• 让 coding agent 根据 spec 在本地重建系统
• 再用 agent review / diff / 回环不断提高 spec 与实现的一致性

这意味着什么？

软件的“可移植单元”可能不再只是源码仓库，也可能是：

• 规格
• policy
• workflow
• skill 包
• 验收方式

flowchart TD
    A([已有系统]) --> B[抽取 SPEC]
    B --> C[让 Agent 按 SPEC 重建实现]
    C --> D[第二个 Agent 做对比评审]
    D --> E{SPEC 与实现偏差大吗？}
    E -- "✅ 是" --> F[更新 SPEC / 补遗漏约束]
    F -.-> C
    E -- "❌ 否" --> G([形成高保真 Ghost Library])

    style A fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px
    style B fill:#fff3e0,stroke:#fb8c00,stroke-width:2px
    style C fill:#fff8e1,stroke:#f9a825,stroke-width:3px
    style D fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px
    style G fill:#e8f5e9,stroke:#43a047,stroke-width:3px

📡 扩展
Symphony 的官方仓库 README 明确给出两种路径：
1）自己根据 SPEC.md 实现 Symphony；
2）直接使用实验性的 Elixir 参考实现。
这正是“以 spec 作为分发主载体”的典型例子。
参考：GitHub openai/symphony README 与 SPEC.md

3.10 Symphony：从“管理 agent”升级到“管理工作”

如果说 Harness 解决的是“单个或少量 agent 如何可靠工作”，那么 Symphony 解决的是“如何把整块工程工作编排成可持续运行的自动化系统”。

Symphony 的定位

Symphony 不是单纯的多 agent 聊天框架，而是：

• 读取 issue tracker 上的工作项
• 为每个 issue 创建隔离工作区
• 运行 coding agent session
• 收集 proof of work
• 驱动 rework / review / acceptance / landing

这是一个层次跃迁

• 之前：人类盯着 tmux pane 推多个 agent
• 之后：人类不管理 session，改为管理 work items 和 acceptance

flowchart TD
    A([Issue Tracker / Linear]) --> B[Symphony Orchestrator]
    B --> C[为每个任务创建隔离 workspace]
    C --> D[启动 Coding Agent Session]
    D --> E[实现代码 / 测试 / 说明 / 证明材料]
    E --> F[CI / Review / Complexity / Walkthrough]
    F --> G{满足质量门槛吗？}
    G -- "❌ 否" --> H[Rework 状态]
    H -.-> D
    G -- "✅ 是" --> I[提交 PR / 等待接受]
    I --> J([安全落地])

    style A fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px
    style B fill:#fff8e1,stroke:#f9a825,stroke-width:3px
    style F fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px
    style J fill:#e8f5e9,stroke:#43a047,stroke-width:3px

📡 扩展
openai/symphony 官方 README 写得非常直接：Symphony 的目标是让团队“管理工作，而不是监督 coding agents”。官方 SPEC.md 还强调了隔离工作区、repo 内 WORKFLOW.md 作为 policy 层、持续可观测性，以及 issue tracker 驱动的长时运行服务。
参考：GitHub openai/symphony README / SPEC.md

3.11 CLI 设计与 token-efficient tools：工具不是给人看的，要给 agent 吃

Ryan 在后半段提到一个很实用的工程原则：
CLI 输出要对 agent token-efficient。

意思是：

• 不要给 agent 大段无效噪音
• 不要让“全量格式化成功日志”淹没有效错误
• 输出应该尽量结构化、摘要化、可定位

这和传统 DevEx 的区别

传统 DevEx 优化的是“人看着舒服”。

Agent-first DevEx 优化的是：

• token 成本低
• 关键信号密度高
• 噪音最小
• 可以直接进入下一个动作

📡 扩展
访谈整理稿中，Ryan 举例说像构建系统、formatter 这类 CLI，应尽量静默掉“无关成功信息”，只把真正阻塞 agent 的异常、路径和关键信号暴露出来。这是把 CLI 当作 machine interface，而不只是 human interface。
参考：Latent Space 访谈整理稿约 00:48:00 附近

3.12 当前模型仍不擅长什么？

Ryan 并没有把 agent 说成“全能”。

他明确保留了几个难点：

• white-space 的 zero-to-one 新产品定义
• 特别棘手的大型重构
• 接口形状还不明确时的深层设计判断
• 需求本身还在摇摆时的持续同步

可以概括为：

当问题本身还没被结构化时，人类仍是主要建模者。

所以最适合 agent 的，不是“所有事”，而是：

• 已被清晰表述的问题
• 已有较稳定边界的问题
• 已有一定反馈传感器的问题
• 已能被分解与回路化的问题

4. 实践案例

4.1 OpenAI 内部零手写代码实验

已确认事实

📡 扩展
这里需要区分两个层级：

• 官方已确认：0 行手写代码、约 100 万 LOC、约 1,500 PR、约 1/10 时间。
• 播客/转述中出现：1B tokens/day、0% human review 等更激进表述。后者在本次检索里主要来自播客与其整理稿，不是 OpenAI 那篇官方博客的主文陈述，因此适合视作访谈语境中的说法，而不是官方白皮书级结论。

4.2 Symphony 的工作流案例

用一句话描述

把 issue tracker 变成 agent dispatch surface。

最小流程

1. 人把需求放进工单系统
2. Symphony 读取工单
3. 为工单创建隔离 workspace
4. 启动 coding agent
5. 生成实现、测试、证明材料
6. 经过 review / CI / rework
7. 到达接受标准后落地

这本质上是把“软件交付过程”产品化。

5. 可直接复用的方法论

5.1 一个适合个人/小团队的 Harness 起步顺序

flowchart TD
    A([先别追求全自动]) --> B[写最小 AGENTS.md]
    B --> C[把 1-2 个重复流程封装成 Skill]
    C --> D[补最小测试与 CI]
    D --> E[补最小 observability]
    E --> F[压短 inner loop]
    F --> G[把 review 口径写进仓库]
    G --> H([再考虑多 agent 编排])

    style A fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px
    style B fill:#fff3e0,stroke:#fb8c00,stroke-width:2px
    style C fill:#fff3e0,stroke:#fb8c00,stroke-width:2px
    style D fill:#fff8e1,stroke:#f9a825,stroke-width:2px
    style E fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px
    style F fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px
    style H fill:#e8f5e9,stroke:#43a047,stroke-width:3px

5.2 你可以立刻检查的 8 个问题

• 我的仓库里，有没有 AGENTS.md 这种长期约定文件？
• 我最常重复的 3 类 prompting，能不能做成 Skill？
• 构建/测试/格式化输出，对 agent 是否太吵？
• agent 出错时，我拿到的是“代码表象”还是“运行态证据”？
• 非功能要求（性能、日志、可维护性）有没有写进上下文？
• review 标准是否主要还存在于资深工程师脑子里？
• 哪些人工动作其实只是“重复确认”，可以前移为传感器？
• 我的 issue 到 PR 链路，是不是仍需要人盯 session 才能推进？

6. 核心结论

最重要的五点

1. Harness Engineering 的核心不是让模型更聪明，而是让系统更可交付。
2. 真正稀缺的资源不再是 token，而是人类同步注意力。
3. 一切重复判断，都值得被沉淀为文档、skill、policy、测试或传感器。
4. agent-first 软件需要 agent legibility：结构一致、信号清晰、反馈快速。
5. 未来的升级方向是 orchestration：从“驱动 agent”转向“管理工作与验收”。

对个人学习者/工程团队的适用建议

• 别一上来就追求“0 人工代码”
• 先把你当前最贵的人工环节找出来
• 哪一步最耗你同步注意力，就先在那里补 Harness
• 优先投资：
  • 可复用规则
  • 快反馈
  • 可观测性
  • 结构化输出
  • 仓库内长期上下文
• 当这些都起来之后，多 agent 编排才真正有意义

7. 延伸阅读与来源

官方 / 一手资料

1. OpenAI — Harness engineering: leveraging Codex in an agent-first world
2. OpenAI — Unlocking the Codex harness: how we built the App Server
3. OpenAI — Unrolling the Codex agent loop
4. OpenAI Developers — Agent Skills
5. OpenAI Developers — Custom instructions with AGENTS.md
6. GitHub — openai/symphony README
7. GitHub — openai/symphony SPEC.md

强相关二手资料

8. Latent Space — Extreme Harness Engineering for Token Billionaires（访谈整理稿）
9. Martin Fowler — Harness engineering for coding agent users

备注

• 本笔记中关于 0 行手写代码、约 100 万 LOC、约 1,500 PR、约 1/10 时间，以 OpenAI 官方文章为主。
• 本笔记中关于 1B tokens/day、更强烈的 “0% human review” 表述，主要来自播客与其整理稿，使用时应注明其语境，而不要误写成 OpenAI 官方博文原句。

8. 可拆分的 Obsidian 双链建议

推荐双链节点

• Harness Engineering
• Context Engineering
• Codex Harness
• Agent Loop
• AGENTS.md
• Agent Skills
• Symphony
• Agent Legibility
• Observability for Agents
• Token-efficient CLI
• Ghost Libraries
• AI-native Software Engineering

推荐派生原子笔记

1. Harness Engineering vs Context Engineering
2. 如何给 Coding Agent 设计 Feedback Sensors
3. AGENTS.md / Skills / SPEC.md 的职责边界
4. 为什么 Agent-first 团队要把 inner loop 压到 1 分钟
5. Symphony：从管理 Agent 到管理工作