Harness Engineering —— 让 AI Agent 可靠、持续、自主工作的工程体系
探讨 OpenAI 内部实验：0 行手写代码、100 万行代码、1500 个 PR，揭示 AI Agent 时代的工程挑战与体系设计。
Harness Engineering 技术分享 —— 让 AI Agent 可靠、持续、自主工作的工程体系
1. 引言：一个颠覆认知的实验
1.1 关键数据：5 个月 / 0 行手写 / 100 万行 / 1500 PR
2026 年 2 月，OpenAI 在官方博客发布了一篇题为 "Harness engineering: leveraging Codex in an agent-first world" 的文章，描述了一次内部实验：一个小型工程师团队，以 "0 行手动键入代码" 作为硬性约束，完全依赖 Codex Agent 完成所有开发工作——应用逻辑、测试、CI 配置、文档、可观测性、内部工具——构建并交付了一个拥有真实日活用户的内部 beta 产品。
核心数字：
| 指标 | 数值 | 说明 | | --- | --- | --- | | 实验周期 | ~5 个月 | 从零到可运行的生产级产品 | | 手写代码量 | 0 行 | 团队以此为强制约束（forcing function） | | 代码规模 | ~100 万行 | 已合并至主干，包含应用代码 + 测试 + 基础设施 | | 合并 PR 数 | ~1,500 个 | 5 个月内持续交付 | | 人均日吞吐 | ~3.5 PR / 人 / 天 | 初始 3 人团队，后扩展至 7 人 | | 估算效率倍数 | ~10× | 相较于纯手动编码的同等产出 |
这不是一个"demo 级 side project"——产品已经在线运行、部署、出过故障、被修复，而修复本身也是由 Agent 完成的。
1.2 核心启示：瓶颈从"写代码"迁移到"设计环境"
看到这组数据，很容易得出一个结论："Agent 写代码真快"。但 OpenAI 团队自己强调的重点并不在速度，而在一句话：
"Our most difficult challenges now center on designing environments, feedback loops, and control systems." （我们现在最难的挑战，集中在设计环境、反馈回路和控制系统上。）
这句话揭示了一个关键变化：
Thoughtworks 的 Distinguished Engineer Birgitta Böckeler 在 Martin Fowler 网站上发表了对这篇文章的解读：
"Unsurprisingly, what they describe sounds like much more work than just generating and maintaining a bunch of Markdown rules files. They built extensive tooling for the deterministic part of the harness."
换句话说：当 Agent 吞吐量已经远超人类时，真正的限制变成了三件事——上下文是否精准传达给了 Agent？架构是否足够清晰让生成代码天然趋向正确？出了错是否有自动机制发现并纠正？这三个问题，就是 Harness Engineering 要回答的。
2. 什么是驾驭工程（Harness Engineering）
2.1 定义与四个动词：Constrain / Inform / Verify / Correct
Harness Engineering（驾驭工程）的核心定义：设计一套环境与机制，使 AI Agent 能在可控边界内持续自主工作，并能被自动验证、快速纠错与持续改进。
它与"用 AI 帮忙写代码"的区别在于主动性：
| 维度 | 被动使用 AI | Harness Engineering | | --- | --- | --- | | 模式 | 遇到问题 → 找 AI 写一段 | 构建系统 → Agent 持续自主运行 | | 关注点 | 单次输出质量 | 长期可持续的输出可靠性 | | 工程师角色 | 写代码的人 + AI 辅助 | 系统设计者 + Agent 管理者 |
OpenAI 团队将驾驭系统的核心动作抽象为四个动词，这也是整套体系的骨架：
| 动词 | 中文 | 含义 | 落地形态举例 |
| --- | --- | --- | --- |
| Constrain | 约束 | 给 Agent 设定边界和规则 | 分层架构、单向依赖、库白名单、变更范围限制 |
| Inform | 告知 | 把正确知识放入 Agent 上下文 | AGENTS.md、docs/ 知识库、API 合约、ADR |
| Verify | 验证 | 自动检验 Agent 的输出 | CI 测试、自定义 Linter、结构测试、可观测性验收 |
| Correct | 修正 | 把错误信号反馈回 Agent | Lint 报错嵌入修复指引、自审 + 交叉 Agent 评审 |
四者构成一个闭环：
关键认知：Agent 视野里不存在"常识"——不在上下文中的信息，对 Agent 而言就是不存在。你以为"文档里写了"，Agent 看不到；你以为"这是团队共识"，Agent 不知道。Inform 的工作质量，直接决定了其他三个环节的上限。
2.2 马具隐喻：模型 vs 驾驭系统 vs 工程师
"Harness"一词来自马术。这个隐喻非常贴切：
- 一匹马的力量远超骑手，但它没有方向感；
- 驾驭系统（缰绳、马鞍、护栏）不是为了限制力量，而是把力量引向正确方向；
- 骑手不亲自奔跑，负责的是决策方向。
对应到 Agent 工程：
| 角色 | 对应 | 核心特点 | | --- | --- | --- | | 模型（Model） | 马 | 力量强大，无方向感，可能复制错误模式 | | 驾驭系统（Harness） | 马具 | 约束 + 护栏 + 反馈回路，确定性机制为主 | | 工程师（Engineer） | 骑手 | 不再亲自写代码，负责方向决策与系统设计 |
Martin Fowler 网站上 Birgitta Böckeler 的评价："我喜欢'harness'这个词来描述我们用来让 AI Agent 保持在正轨上的工具与实践。" 她同时指出，驾驭系统的确定性部分（Linter、结构测试、CI 钩子）比 LLM 部分更重要——这与直觉相反，但完全合理：你不能用一个非确定性系统去守护另一个非确定性系统。
2.3 工作模式的根本转变：从写代码到设计环境
这不是工具升级，而是工种迁移。
| 维度 | BEFORE（传统开发） | AFTER（Agent 驱动开发） | | --- | --- | --- | | 核心工作 | 写代码、调 Bug | 设计环境、构建反馈回路 | | 日常任务 | 实现功能、手动测试、Code Review | 描述意图、管理 Agent 行为、维护驾驭系统 | | 质量保障 | 人工 Review + 手动测试 | 自动化验证 + Agent 自审 + 交叉评审 | | 知识传递 | 口头沟通、Wiki、会议 | 版本化文档入仓（Agent 只信任能读到的东西） | | 架构治理 | 靠人自觉遵守 | 机械化强制执行（Linter / 结构测试 / Hook） |
OpenAI 团队的工作流可以概括为：
工程师在这个流程中的角色：不写代码，但决定 Agent 该做什么、怎么验证、出错怎么办。这正是"骑手"的工作。
3. 三大组成部分
Fowler 网站对 OpenAI 文章的归纳与此一致：Context Engineering / Architectural Constraints / "Garbage Collection"（用清理 Agent 对抗熵增）。三者缺一不可，共同构成驾驭系统的完整闭环。
3.1 上下文工程（Context Engineering）
Agent 的行为质量上限，由上下文质量决定。Shopify CEO Tobi Lütke 的定义被广泛引用：上下文工程是"为使任务能被 LLM 合理解决而提供所有上下文的艺术"。Redis 团队进一步强调：大多数 Agent 的失败不是模型失败，而是上下文提供失败。
参考：Redis — Context engineering: Best practices for an emerging discipline
3.1.1 静态与动态上下文
| 类型 | 内容示例 | 处理方式 | 特点 | | --- | --- | --- | --- | | 静态 | 架构文档、API 合约、编码规范、ADR、执行计划 | 进版本控制，随代码一起演进 | 可审计、可回滚、变更可追踪 | | 动态 | CI 状态、日志（LogQL）、指标（PromQL）、链路追踪、UI 截图 | 任务运行时实时注入 | 按需获取、最小相关集、用完即弃 |
OpenAI 团队的做法：工程师在 docs/ 目录维护结构化知识库（映射关系、执行计划、设计规范），同时让 Agent 能够访问可观测性数据和浏览器操作结果（通过 CDP 协议）。静态上下文决定"知道什么"，动态上下文决定"看到什么"。
3.1.2 上下文稀释与"Lost in the Middle"
直觉告诉我们"给 Agent 的信息越多越好"，但研究表明恰恰相反。
斯坦福大学等机构的论文 "Lost in the Middle: How Language Models Use Long Contexts"（arXiv:2307.03172）揭示了一个关键现象：
- 模型对信息位置高度敏感，对开头和结尾的利用最好，对中间部分显著退化。
- 即使是专门设计处理长上下文的模型，也无法免疫这一现象。
- 上下文越长，每一行的权重越低——这就是上下文稀释。
实践推论：把所有规则、约束、背景全部塞进一个超长文件是反模式。你以为在告诉 Agent，实际上是在稀释关键信号。
3.1.3 渐进式披露：AGENTS.md 是地图不是百科全书
解法是借鉴 UX 领域的**渐进式披露（Progressive Disclosure）**原则：主界面只保留核心入口，详细信息按需展开。
OpenAI 的 AGENTS.md 只有约 100 行——它是索引/地图，不是百科全书。真正的知识在 docs/ 目录里按模块组织，Agent 根据任务上下文按需读取。
repo/
├── AGENTS.md ← 入口索引（~100 行），指向下方各模块
├── docs/
│ ├── architecture.md ← 分层架构说明、依赖规则
│ ├── api-contracts.md ← 接口合约与数据形状定义
│ ├── adr/ ← 架构决策记录
│ │ ├── 001-auth.md
│ │ └── 002-cache.md
│ ├── runbooks/ ← 运行手册（故障处理流程）
│ └── style-guide.md ← 编码规范
└── src/
AGENTS.md已成为一个开放标准（agents.md），被 60,000+ 开源项目采用，兼容 OpenAI Codex、Google Jules、Cursor、GitHub Copilot 等主流 Agent 工具。
核心原则：入口文件做索引，每个文件聚焦一个主题，让 Agent 按需加载——而不是一次性倾倒所有信息。
3.2 架构约束（Architectural Constraints）
Agent 会模仿代码库中已有的模式。如果架构清晰，Agent 生成的代码就趋向清晰；如果架构混乱，Agent 会忠实地复制混乱——而且以 10× 的速度复制。
3.2.1 单向依赖链与分层架构
OpenAI 团队强制执行单向依赖流：
依赖方向只允许向右，不允许反向引用。 这不是靠文档约定，而是通过确定性机制强制执行。
3.2.2 机械化落地：Linter + 结构测试 + Pre-commit Hook
"约定"对人类都经常失效，对 Agent 更不可能靠"自觉"遵守。OpenAI 团队的做法是把架构规则编码为机器可执行的检查：
| 机制 | 作用 | 执行时机 | | --- | --- | --- | | 自定义 Linter | 检查依赖方向、禁止反向引用、强制命名规范 | 每次代码变更 | | 结构测试 | 验证模块边界完整性（类似 Java 的 ArchUnit） | CI 流水线 | | Pre-commit Hook | 在提交前拦截违规，阻止问题进入仓库 | Git commit 时 | | 交叉链接验证 | 确保文档引用不断链、架构说明与代码一致 | CI 流水线 |
这类清晰的分层架构，通常要等团队规模到几百人时才会认真建。但在 Agent 驱动开发的场景下，需要从第一天就建。Agent 不会主动整理架构，它只会按照已有结构复制和扩展。
3.3 熵管理（Entropy Management）
Agent 会复制已有模式——包括坏的模式。一个糟糕的函数命名、一个绕路的实现方式，会被 Agent 当作"规范"在整个代码库扩散。这就是 "AI Slop"（AI 垃圾扩散）。
3.3.1 AI Slop 的扩散机制
这是一个正反馈回路：坏模式越多 → Agent 越容易学到坏模式 → 生成更多坏代码 → 坏模式更多。传统开发中技术债是线性增长，Agent 时代是指数增长。
3.3.2 从人工清理到"以 Agent 打 Agent"
OpenAI 团队经历了四个阶段的演进：
| 阶段 | 策略 | 结果 | | --- | --- | --- | | Phase 1 问题出现 | 代码库积累低质量模式，Agent 不断复制扩散 | 质量持续下降 | | Phase 2 首次响应 | 每周五拿出 20% 时间，人工清理 AI Slop | 短期有效 | | Phase 3 方案失效 | Agent 产出速度远超人工清理速度 | 策略根本扛不住 | | Phase 4 正确解法 | 定期派清理 Agent 专门处理技术债 | 以 Agent 打 Agent ✅ |
核心理念：不要攒着等"大扫除"，要像 GC（垃圾回收）一样持续运行。 持续小额还债，优于周期性大爆炸重构。技术债的利息是复利，Agent 时代尤甚。
3.3.3 技术债的复利效应（GitClear 数据佐证）
这不是理论推演，行业数据已经证实了 AI 代码的熵增趋势。GitClear 分析了 2020–2024 年间 2.11 亿行代码变更，发现：
| 指标 | 数据 | 含义 | | --- | --- | --- | | 代码重复率 | 5 行以上相邻重复块频率 增加 8×（2024 vs 2023） | DRY 原则被系统性违反 | | 新增行占比 | 46% 的代码变更来自新增行 | "复制粘贴"取代"重构复用" | | 代码移动率 | 显著下降 | 开发者越来越少将旧代码整合为可重用模块 | | 交付稳定性 | AI 使用率每增 25%，交付稳定性下降 7.2% | Google 2024 DORA 报告 |
Kin Lane 的一句话总结："在我 35 年的技术职业生涯中，从未见过在如此短时间内产生如此多的技术债务。"
这正是熵管理存在的理由：Agent 时代的技术债不是"将来的问题"，而是"现在就在以复利速度积累的问题"。没有系统性的清理机制，代码库会在 Agent 的高吞吐下快速腐化。
4. 实施指南：落地与避坑
前三节讲的是"是什么"和"为什么"，这一节聚焦**"怎么做"**——从仓库治理、运行时可读性、反馈回路到合并策略，给出可直接落地的 Do / Don't 清单。
4.1 把代码仓库变成单一事实来源
Agent 只信任它能读到的内容。架构决策如果活在 Confluence 里、群聊记录里、或者某个人的脑子里——对 Agent 而言，它就不存在。
| ✅ Do | ❌ Don't |
| --- | --- |
| 所有架构决策写成版本化 Markdown 入仓 | 知识留在文档系统 / 群聊 / 人脑 |
| 设计讨论的结论同步到 docs/ | 只口头说"大家都知道这个规范" |
| ADR（架构决策记录）纳入 PR 流程 | 口头 review 结论不落 PR 注释 |
| 接口合约、数据形状定义紧邻代码 | 合约文档和代码分属不同仓库 |
OpenAI 团队的一个关键实践：当 Agent 犯错时，首先检查是不是上下文缺失——"When the agent struggles, we treat it as a signal: identify what is missing — tools, guardrails, documentation — and feed it back into the repository." Agent 的错误是驾驭系统的 bug，而不是 Agent 的 bug。
核心思维转换：Agent 出错 = 驾驭系统有 gap，修的不是 Agent 的输出，而是环境本身。每次修复都让系统变得更强，形成正向飞轮。
4.2 提升应用的 Agent 可读性（Legibility）
驾驭工程不只是给 Agent 写文档，还要让应用本身对 Agent 可读——Agent 要能感知运行状态、触发操作、观察结果。
OpenAI 团队接入了 Chrome DevTools Protocol（CDP），让 Agent 可以像人一样操作浏览器界面：
完整的 Agent 自主修 Bug 流程：复现 Bug → 实现修复 → 录视频验证 → 开 PR，全程无需人工 QA 介入。Agent 单次运行最长可达 6 小时。
关键设计：每个 Git worktree 拥有独立的日志/指标栈（LogQL / PromQL），用完即销毁——Agent 之间互不干扰，也不会污染共享环境。
| ✅ Do | ❌ Don't | | --- | --- | | 接入 CDP 或等效协议，让 Agent 可操作 UI | 只给指令不给反馈通道 | | 每个 worktree 独立可观测栈 | 让多个 Agent 共享同一个日志环境 | | 给 Agent 丰富的反馈信号（日志 + 指标 + 截图） | Agent 在黑盒里运行，出错只能靠人排查 | | 错误信息包含足够上下文（文件名、行号、修复建议） | 报错只有一句 "test failed" |
4.3 构建自修复反馈回路（Ralph Wiggum Loop）
反馈回路的目标：让 Agent 能自我纠错，而不是等人来发现问题。
"Ralph Wiggum Loop"得名于《辛普森一家》角色，其本质是一个迭代式自修复循环——Agent 执行任务 → 验证失败 → 根据错误信号自动修复 → 再次验证，直到通过或达到最大迭代次数。
让这个循环高效收敛的关键：Lint 错误信息本身要嵌入修复指引。不能只说"违反了规则 X"，要说"违反了规则 X，应该改成 Y，参考 docs/style-guide.md#naming"。
| ✅ Do | ❌ Don't | | --- | --- | | 自定义 Lint 错误嵌入修复指引与文档链接 | 报错信息只有规则编号，没有修复方向 | | 设置最大迭代次数（防止无限循环） | 不设上限，Agent 可能在不可能的任务上空转 | | 驾驭系统设计为"可拆卸"，模型升级后清理旧逻辑 | 让驾驭系统变成不可维护的黑魔法 | | 明确的完成标准（测试通过 / Lint 通过 / 截图匹配） | 完成标准模糊，Agent 不知道什么时候该停 |
Ralph Wiggum Loop 的哲学：迭代 > 完美。 不要指望 Agent 第一次就做对，但要确保它每次失败都能从反馈中学到东西并收敛。
4.4 调整合并哲学与吞吐量管理
传统 PR 审批流程是为了补偿"人写代码会犯错"。当 Agent 以每人每天 3.5 个 PR 的速度推进时，等待审批的时间成本比纠错成本高一个数量级。
| 策略 | 时间成本 | 说明 | | --- | --- | --- | | 等待人工审批 | 极高 | 每个 PR 等 1 天 × 1,500 PR = 1,500 人天浪费 | | 合并后发现问题再修 | 极低 | 高覆盖测试 + 快速回滚 = 分钟级纠错 |
这意味着合并哲学需要从"审批驱动"转向**"验证驱动"**：
| ✅ Do | ❌ Don't | | --- | --- | | 高覆盖自动化测试驱动快速合并 | 人工 review 每一个 Agent PR | | 优先使用"无聊"的、Agent 训练集内熟悉的技术栈 | 引入训练集外的"有趣新库" | | 保持快速回滚能力（feature flag / canary） | 合并后无回滚手段，出了问题只能 hotfix | | 减少阻塞式人工审批环节 | 保留高吞吐下的串行审批流程 |
5. 业界视角与开放问题
5.1 三个未解之问：架构演化 / 驾驭系统简化 / 工程师核心价值
OpenAI 自己也承认，这是一个连实践者都没有标准答案的领域。以下三个问题值得持续关注：
Q1：完全由 Agent 生成的系统，架构一致性如何随时间演化？
5 个月的实验证明了可行性，但 18 个月后呢？Agent 不具备跨长时间跨度的"架构记忆"，每次任务都是从当前上下文出发。随着代码库膨胀，上下文窗口能覆盖的比例越来越小，架构漂移的风险会如何变化？
Q2：模型能力持续提升后，今天的驾驭系统会如何简化？
当前的很多约束（如详细的 AGENTS.md、严格的 Lint 规则、自定义报错信息）本质上是在补偿模型的不足。随着模型推理能力、长上下文处理能力、代码理解能力的持续提升，哪些约束会变得多余？哪些会依然必要？
一个可能的演化方向：
| 可能简化的 | 可能长期保留的 | | --- | --- | | 详细的编码风格指引（模型内化） | 架构边界与依赖规则（业务决策） | | 冗长的修复指引（模型自主推理） | 可观测性基础设施（Agent 需要感知） | | 部分结构测试（模型理解架构意图） | 自动化测试（正确性验证不可替代） |
Q3：当整个团队都在用 Agent 时，工程师的核心价值在哪里？
如果 Agent 写了所有代码，工程师还在做什么？OpenAI 的回答是三个词：判断力（Judgment）、品味（Taste）、系统设计（System Design）。
- 判断力：决定做什么、不做什么；在多个可行方案中选择最合适的
- 品味：知道什么是"好"的架构、什么是"对"的抽象层次、什么时候该重构
- 系统设计：构建和维护驾驭系统本身——这是一个递归问题：你需要工程能力来构建让 Agent 发挥工程能力的系统
这与软件行业的一个长期趋势一致：每一次抽象层级的提升（汇编→高级语言→框架→云服务），工程师的工作都从"实现细节"上移到"设计决策"。Agent 是这个趋势的最新一跳。
附录：参考资料
- OpenAI — Harness engineering: leveraging Codex in an agent-first world
- InfoQ — OpenAI Introduces Harness Engineering for Agentic Codex Development (2026-02)
- Martin Fowler / Birgitta Böckeler — Harness Engineering
- AGENTS.md — A simple open format for guiding coding agents
- Redis — Context engineering: Best practices for an emerging discipline
- Liu et al. — Lost in the Middle: How Language Models Use Long Contexts (arXiv:2307.03172)
- LeadDev — How AI generated code accelerates technical debt
- GitClear — Coding on Copilot: 2024 Data Suggests Downward Pressure on Code Quality
- Google — 2024 DORA Report: AI's impact on delivery stability