Harness Engineering

Mar 11, 2026 · 4443 字

2026 年 2 月，OpenAI 的工程博客发布了一篇题为 Harness Engineering 的文章，描述了他们用三名工程师在五个月内交付一百万行代码的经历——其中没有一行是人工编写的。这篇文章给出了一个概念：在 Agent 优先的开发模式下，工程师的职责不再是写代码，而是建设让 Agent 能够有效工作的环境，也就是 Harness。

“Harness”原本是“挽具”的意思，用来控制和引导力量的方向。放在软件工程语境里，它指的是支撑 Agent 工作的完整基础设施——包括文档、约束、观测工具、反馈回路，以及把所有这些组织起来的方法。Harness Engineering 就是专门设计、构建和维护这套基础设施的工程方法。

为什么需要

Agent 失败的原因，通常不是模型能力不够，而是环境规范不够明确。

拿 Codex 的实践举例：早期进展比预期慢，原因不是模型出了问题，而是“环境的规范不够明确”。Agent 缺乏完成高级目标所需的工具、抽象层和内部结构，所以无法取得进展。碰到问题时，解决方案不该是“再提示一次”，而是追问——究竟还差什么，怎么让这个能力对 Agent 来说既清晰又可强制执行。

换句话说，Agent 在运行时只能访问它上下文里已有的内容。存在 Slack 记录里的决策、存在人脑里的经验，对 Agent 来说一律不存在。从这个角度看，一个没有 Harness 的 Agent 系统，就像一个刚入职的工程师，既没有代码规范，也没有文档，甚至连项目结构都没人介绍——能产出什么，完全靠运气。

更深层的问题是，随着 Agent 大量生成代码，代码库会出现漂移。Agent 会复制已有的模式，包括那些不理想的模式，错误会以指数速度扩散。没有持续的清理机制，技术债务会快速积累到不可控的程度。

核心构成

代码仓库即记录系统

Harness Engineering 的核心信念之一：Agent 的知识边界就是代码仓库的边界。

OpenAI 的实践是把代码库当作“记录系统”（system of record）来运营。所有设计决策、架构约定、执行计划、质量标准，都以 Markdown 的形式版本化入库。一份典型的知识库结构大致是：

docs/
├── design-docs/       # 设计文档（含验证状态）
├── exec-plans/        # 执行计划（活跃/已完成/技术债）
├── product-specs/     # 产品规格
├── references/        # 外部参考（llms.txt 格式）
├── generated/         # 自动生成内容
├── DESIGN.md
├── ARCHITECTURE.md
├── SECURITY.md
└── QUALITY_SCORE.md

重要的是渐进式披露原则：Agent 从一个小而稳定的切入点开始，被引导去下一步查什么，而不是一开始就被淹没。AGENTS.md 扮演的是目录角色，大约 100 行，告诉 Agent 去哪里找更深层的信息，而不是把所有规则都塞在里面变成百科全书。

一个巨大的 AGENTS.md 会失效，原因是多方面的：上下文是稀缺资源，一份庞杂的指令文件会挤掉任务本身；当一切都“重要”，Agent 最终靠本地模式匹配而不是主动导航；这份文件也会快速腐烂，陈旧规则变成干扰，且几乎无法做覆盖率和新鲜度检验。

Agent 可读性

与代码对人类工程师的可读性类似，Harness Engineering 强调代码库对 Agent 的可读性，简称 Agent Readability。

这要求工程师主动把知识“外化”到代码库里——那次在 Slack 上讨论并达成共识的架构决策，如果不写进 docs/，对 Agent 来说就不存在。产品原则、工程规范、甚至团队的表情符号偏好，都可以是上下文的一部分。

为了让应用程序本身也对 Agent 可读，OpenAI 做了以下几件事：

允许应用根据 git worktree 分支启动独立实例，Codex 可以为每个任务启动并驱动一个应用实例；
把 Chrome DevTools 协议接入 Agent 运行时，让 Agent 能直接进行 DOM 快照、截图和导航；
为每个工作树提供临时可观测性堆栈（Victoria Logs、Metrics、Traces），Agent 可以用 LogQL 查日志、用 PromQL 查指标、用 TraceQL 查链路追踪。

这样，“确保服务启动在 800ms 以内”或“这四个关键用户路径的任何 Span 不得超过两秒”这类提示才变得可操作。

架构约束

Agent 在有严格边界和可预测结构的环境中工作最高效。Harness Engineering 把架构约束视为早期先决条件，而不是等到团队扩大才引入。

一个典型的约束体系包含两层：

分层架构：每个业务域内，代码只能沿固定方向依赖（如 Types → Config → Repo → Service → Runtime → UI）。横切关注点（认证、遥测、功能标志）通过单一显式接口 Providers 进入，其他任何路径都不允许。

机械强制执行：这些规则不靠人工 Review，而通过自定义 Linter 和结构测试强制执行。Lint 的错误信息会在 Agent 上下文中注入修复指令，这样 Agent 不只是知道出了问题，还能直接得到怎么修的提示。

除了硬约束，还有一组“品味不变式”（taste invariants）作为更主观的机械规则：结构化日志、命名约定、文件大小限制、特定平台的可靠性要求。此类规则一旦编码，就会立即应用到所有地方——在 Agent 驱动的代码库里，它们是倍增器，而不是束缚。

熵管理

完全由 Agent 生成的代码库会不断产生熵。Agent 会放大已有模式，包括不良模式，漂移是不可避免的。

早期，OpenAI 团队每周五花 20% 的时间手动清理“AI 残渣”，这不具备可扩展性。解决方案是把清理过程自动化——制定一组黄金原则（golden principles），把主观的代码库品味规则编码成机械可检查的规则，再跑周期性的后台 Agent 任务：

扫描代码漂移，识别不再符合约束的模式；
更新质量评分；
发起针对性重构的 Pull Request，大多数可以在一分钟内完成审查并自动合并。

还有专门的 doc-gardening Agent 定期扫描那些不再反映真实代码行为的文档，自动发起修复 PR，阻止文档腐烂。

这套机制的本质类似垃圾回收：持续以小代价还技术债，而不是让债务累积到必须大规模人工介入。

如何实践

知识入库

把所有对 Agent 有价值的知识转化为代码库内可版本化的工件：

把架构决策写成设计文档（ADR），而不是只留在会议记录里；
外部库的文档用 llms.txt 格式存入 docs/references/，这样 Agent 不依赖外部检索也能获取；
任务计划以执行计划（exec plans）的形式提交入库，进度和决策日志也随之版本化，Agent 可以在不依赖外部上下文的情况下独立运转。

专职 Linter 和 CI 作业验证知识库的更新状况、是否有交叉链接且结构正确，防止文档与代码渐渐脱节。

构建反馈回路

判断 Agent 做得好不好，不能只看 Pull Request 数量，还要看应用是否实际正常运行。有效的反馈回路：

让 Agent 能直接复现 Bug、验证修复，并录制演示视频；
让 CI 失败、Lint 错误、测试失败对 Agent 可读，不只是报错码，还要附带如何修复；
用 Agent 对 Agent 的方式做代码审查，减少对人工注意力的依赖。

当 Agent 卡住时，把原因视为信号：缺少什么工具、缺少哪些约束、还有什么知识没入库，然后由 Agent 自己完成修复。

吞吐量对合并策略的影响

在传统低吞吐量环境中，PR 阻塞是常态，代价是可以接受的等待。在 Agent 驱动的高吞吐量环境下，这套逻辑会反转：纠错成本低，等待成本高。偶发测试失败通过后续重跑解决，而不是无限期阻塞进度。

这不是降低质量标准，而是基于经济学做出的权衡——在一个 Agent 每天能产出数十个 PR 的系统里，人工把守每个门控会成为最大的瓶颈。

Codex 与 App Server

OpenAI 在实践中使用 Codex 作为核心 Agent，底层由 Codex App Server 驱动。App Server 是 Codex 的运行框架，通过 JSON-RPC over stdio 向不同客户端（CLI、VS Code、浏览器端）暴露同一套 Agent 循环能力。

App Server 中有三个核心对话原语：

Item：输入/输出的基本单位，每个 Item 都有 started → delta → completed 的生命周期；
Turn：由用户输入发起的 Agent 工作单位，包含若干 Item；
Thread：用户与 Agent 的持久会话容器，可创建、恢复、派生和归档。

对于想要把 Agent 集成进自己工具链的团队，Codex 提供了几个入口：

codex app-server：完整运行框架，支持富事件流，适合构建完整 IDE 集成；
codex mcp-server：作为 MCP Server 对外暴露，适合现有 MCP 工作流；
codex exec：轻量 CLI 模式，适合 CI 场景的一次性执行；
Codex SDK：TypeScript 库，适合在服务端应用中以编程方式控制 Agent。

整体而言，Harness Engineering 是 Agent 优先开发模式下工程师角色的重新定义。不再是“写代码”，而是“建结构”——让 Agent 能可靠地在这个结构里工作，把人类的判断力以可执行的约束形式持续注入系统。