Harness Engineering：AI Agent 时代的工程范式革命
"人类掌舵，智能体执行。" ------ Ryan Lopopolo, OpenAI
1. 背景介绍
1.1 一个震撼性的实验
2026 年 2 月，OpenAI 工程师 Ryan Lopopolo 发布了一篇技术博客，披露了一个令人震惊的内部实验：
3 名工程师，历时 5 个月，构建了一个超过 100 万行代码的生产级应用，其中零行代码由人类手动编写。
这不是概念验证，而是一个有真实内测用户、经历过交付、部署、故障和修复完整生命周期的产品。整个过程中，每一行代码------从应用逻辑、测试、CI 配置、文档到内部工具------全部由 Codex Agent 编写。开发速度约为传统方式的 10 倍。
这个实验提出了一个根本性的问题：当 AI 可以写代码，工程师的工作是什么？
答案就是 Harness Engineering。
1.2 AI 工程的三次范式跃迁
要理解 Harness Engineering 为什么重要，需要先看清楚我们是如何一步步走到这里的。
| 阶段 | 时间 | 核心问题 | 交互模式 | 人与 AI 关系 |
|---|---|---|---|---|
| Prompt Engineering | 2023-2024 | 怎么把话说清楚 | 一问一答 | 出题者与答题者 |
| Context Engineering | 2025 | 怎么给够信息 | 给信息，生成内容 | 信息提供者与内容生成者 |
| Harness Engineering | 2026- | 怎么约束和验证自主行为 | 人造环境，AI 在里面跑 | 系统设计师与自主执行者 |
Prompt Engineering 阶段，核心焦虑是"怎么把话说清楚"。写好一个 Prompt，AI 就能给出好答案。解决的是单次对话的质量问题。
Context Engineering 阶段，人们发现光靠 Prompt 不够。AI 需要看到相关文档、代码片段、历史对话------Shopify CEO Tobi Lutke 在 2025 年将这个概念推到了风口浪尖。它解决的是信息输入的质量问题，但交互模式本质没变：你给信息，AI 生成内容。
Harness Engineering 阶段 ，发生了质的跃迁。我们不再优化"跟 AI 怎么说话"或"给 AI 什么信息"，而是构建一整套系统来约束、引导和验证 AI Agent 的自主行为。交互模式从"人给输入，AI 给输出"变成了"人造环境，AI 在里面跑"。
1.3 为什么旧范式不够用了
当 AI Agent 一天能生成几百个 PR 时，"人写代码"时代的所有工程实践都开始崩塌：
- 人工 Code Review 变成瓶颈：吞吐量远超人类注意力上限
- 靠人记住架构规范不现实：Agent 会复现代码库中已有的坏模式，技术债以 10 倍速度累积
- 文档更新跟不上代码变化：知识腐烂，Agent 基于过时信息做决策
- 上下文窗口限制：复杂项目无法在单个会话内完成，Agent 像失忆了一样
Cassie Kozyrkov（前 Google 首席决策科学家）将这个问题命名为**"信任债务"（Trust Debt）**：
"AI 就像一个极其听话但缺乏背景知识的实习生。它倾向于填补你指令中的空白，进行'自信的即兴发挥'。如果你不审计它的假设，这些假设就会变成信任债务------目前看起来没问题，但在未来某个时刻会爆发。"
Harness Engineering 就是为填补这个空白而生的。
2. 核心概念
2.1 什么是 Harness
"Harness" 的原义是马具------缰绳、鞍具、嚼子------一整套将强大但不可预测的动物导向正确方向的装备。
在软件工程中，Harness 指的是：一套用于引导、约束和赋能 AI Agent 的工程化框架和工具集。
这个概念最早由 Mitchell Hashimoto（HashiCorp 创始人）在其博客中推广，核心理念是：
"每当 Agent 犯一次错，就工程化地修复一次，让它永远不再犯同类错误。"
Birgitta Böckeler 在 Martin Fowler 网站上对此做了精准的定义：
"Harness Engineering 是对模型智能的'塑形'------模型的能力参差不齐，Harness 的工作就是把这些能力塑造成适合具体任务的形状。"
2.2 核心哲学：约束换自主
Harness Engineering 最反直觉也最深刻的洞察是：
规矩越明确 → Agent 独立做的事越多
约束越严格 → 信任越高 → 自主权越大这和人类社会的运转逻辑完全一致：法律越完善的社会，个人自由度越高；高速公路有护栏，你才敢踩到 120 码。
2.3 工程师角色的根本转变
范式跃迁
Harness 时代工程师
价值 = 设计系统的能力
核心技能 = 约束设计、反馈回路设计
产出 = Agent 可靠运行的环境
关注 = 支撑结构：工具、抽象、反馈回路
传统工程师
价值 = 写代码的速度和质量
核心技能 = 编码
产出 = 代码
关注 = 代码本身
工程师的主要工作变成三件事：
- 设计环境：让 Agent 能够可靠工作
- 明确意图：让 Agent 知道目标是什么
- 构建反馈回路：让 Agent 能够自我修正
3. 体系架构
Harness Engineering 的完整框架由三大支柱构成，共同服务于"人类掌舵，智能体执行"这一核心理念。
核心理念
人类掌舵，智能体执行
支柱一
上下文工程
Context Engineering
支柱二
架构约束
Architectural Constraints
支柱三
熵管理
Entropy Management
地图式 AGENTS.md
结构化 docs/ 体系
文档园丁 Agent
可观测性注入
层级依赖模型
自定义 Linter 规则
CI 强制执行
品味不变式编码
黄金标准定义
垃圾回收 Agent
自动重构 PR
AI 互审机制
3.1 支柱一：上下文工程（Context Engineering）
核心问题：让 Agent 知道"在哪里"和"该做什么"。
Agent 在运行时无法访问的信息，对它来说就不存在。存储在 Google Docs、Slack 消息或人们头脑中的知识，都无法被系统访问。
地图式渐进披露
错误做法是把所有信息塞进一个巨大的 AGENTS.md 文件。这会导致：
- 上下文是稀缺资源，巨大的指令文件会挤掉任务和代码
- 过多的指导反而无效，当一切都"重要"时，一切都不重要
- 文件会立即腐烂，成为陈旧规则的坟场
正确做法是渐进式披露：
repo/
├── AGENTS.md ← 约100行，只做目录/地图
├── ARCHITECTURE.md ← 顶层架构地图
└── docs/
├── design-docs/ ← 架构设计文档
├── exec-plans/ ← 执行计划（版本控制的一等工件）
│ ├── active/
│ └── completed/
├── product-specs/ ← 产品规格
├── references/ ← 外部参考文档
├── DESIGN.md
├── FRONTEND.md
├── PLANS.md
└── SECURITY.mdAgent 像新员工一样，从小入口逐步探索，按需深入，不会被信息淹没。
可观测性注入
传统可观测性是给人看的（仪表盘、报警）。在 Harness Engineering 中，观测是给 AI 看的。
OpenAI 的做法：
- 通过 git worktree 为每个 Agent 启动独立的应用实例
- 接入 Chrome DevTools Protocol，让 Agent 像人一样操作浏览器
- 用 LogQL 查询日志，用 PromQL 查询指标
这使得"确保服务在 800ms 内启动"或"关键用户旅程的任何跨度都不得超过两秒"这样的提示变得可行。
文档园丁 Agent
一个后台运行的专职 Agent，自动扫描文档与代码之间的不一致，发现过时内容就自动提交 PR 修复。主动对抗知识腐烂。
3.2 支柱二：架构约束（Architectural Constraints）
核心问题：让 Agent 知道"不能做什么"。
Böckeler 的核心洞察：
"为了获得更高的 AI 自主性，运行时必须受到更严格的约束。增加信任需要的不是更多自由，而是更多限制。"
层级依赖模型
Types
Config
Repo
Service
Runtime
UI
下层不能反向依赖上层。所有架构规则被编码为自定义 Linter 规则，违反即 CI 阻止合并------无论代码是人写的还是 AI 写的。
品味不变式编码
人类的工程品位------日志记录规范、命名约定、代码风格------一旦被编码为机械可执行的规则，就会被持续自动应用到每一行代码中。
关键细节：Linter 的错误信息本身也是上下文工程。它不只说"你违反了规则 X"，而是解释"为什么这个规则存在、正确做法是什么"。这样 Agent 读到错误后能自我理解并修正，无需人类介入。
3.3 支柱三：熵管理（Entropy Management）
核心问题：让系统不随时间腐烂。
AI 写代码有一个容易被忽视的问题：它会复现代码库中已有的坏模式。一个不好的设计模式，人类可能写了 3 处，AI 看到后认为这是"项目惯例"，于是在 30 个地方都用了同样的坏模式。
垃圾回收机制
主分支 CI 系统 代码仓库 垃圾回收 Agent 主分支 CI 系统 代码仓库 垃圾回收 Agent loop [定期运行] 扫描偏离黄金标准的代码 扫描文档与代码不一致 提交重构 PR 触发 CI 验证 验证通过，自动合并
技术债就像高息贷款：不断以小额贷款的方式偿还，总比让债务累积再痛苦地一次解决要好得多。
AI 互审机制（Ralph Wiggum Loop）
当一天产出几百个 PR 时，传统人工 Code Review 成为严重瓶颈。解法是引入 AI Reviewer：
Pull Request Agent B 审查者 Agent A 编写者 人类工程师 Pull Request Agent B 审查者 Agent A 编写者 人类工程师 loop [直到通过] 描述任务 提交代码 请求审查 发现问题，返回反馈 修改并更新 再次审查 继续反馈 继续修改 审查通过 仅在架构决策时介入
人类的角色缩减到只介入架构层面的重大决策。
4. 落地方案
4.1 OpenAI 的五层实施架构
OpenAI 的百万行代码实验揭示了一套完整的五层 Harness 实施架构：
第五层：AI 互审协作流程
Agent A 写代码 → Agent B 审代码
Ralph Wiggum Loop
第四层：自修复闭环
垃圾回收 Agent / 自动重构 PR / 技术债持续偿还
第三层：运行时验证与可观测性
Chrome DevTools 接入 / LogQL/PromQL 查询 / 截图验证
第二层：架构约束与品味
层级依赖 Linter / 品味不变式 / CI 强制执行
第一层：结构化知识体系
地图式 AGENTS.md / docs/ 文档体系 / 文档园丁 Agent
第一层：结构化知识体系
代码仓库即唯一真理源。所有决策依据------架构原则、业务规范、团队约定------以 Agent 可读的形式存入代码仓库，版本控制，机械可验证。
第二层：架构约束与品味
把"人类品味"编码为机械可执行的检查。自定义 Linter 强制层级依赖，违反即 CI 阻断合并。Linter 错误信息本身就是教学材料。
第三层：运行时验证与可观测性
让 Agent 能够"看见"应用的运行状态。接入 Chrome DevTools Protocol，让 Agent 像真实用户一样操作应用，截图与预期结果对比。日志、指标、UI 状态都设计成"机器可读"的格式。
第四层：自修复闭环
后台定期运行清洁 Agent，扫描偏离黄金标准的代码，自动提交重构 PR，CI 验证后自动合并。
第五层：AI 互审机制
Agent A 写代码，Agent B 审代码，循环直到通过。人类只介入架构层面的重大决策。
4.2 Anthropic 的长期运行方案
Anthropic 解决了一个更底层的问题：如何跨越上下文窗口的限制，实现真正的长期运行。
双层 Agent 架构
外部持久化存储
执行层 Workers
编排层 Orchestrator
任务分解 / 状态管理 / 进度追踪
Worker 1
功能 A
Worker 2
功能 B
Worker 3
功能 C
claude-progress.txt
功能状态列表 / git log
三个精妙设计
全标失败策略：所有功能的初始状态标记为"失败"。Agent 只能通过修改状态字段来标记完成，不允许删除或编辑测试用例。这堵死了 Agent 通过"降低标准"来"完成"任务的路。
每次只做一件事：强制单任务执行，避免上下文耗尽留下半成品。与其让 Agent 试图一次吃完蛋糕但半途而废，不如让它一块一块地吃，每块都吃完。
进度文件作为跨会话记忆：每个新会话的第一件事是读进度文件 + git log，搞清楚"上一个自己"做了什么，从断点继续，而非从零开始。
4.3 LangChain 的迭代优化方案
LangChain 提供了一套可重复的 Harness 改进循环，适用于在已有 Agent 上做定向优化。
改进循环
运行 Agent
收集 Trace
Trace 分析 Skill
并行错误诊断
主 Agent 汇总
提出改进建议
人类验证（可选）
修改 Harness
四个关键改造
改造一：强制自验证闭环
在系统提示词中强制四步工作流：
规划（Planning）→ 构建（Build）→ 验证（Verify）→ 修复（Fix）配合 PreCompletionChecklistMiddleware：Agent 宣告"完成"之前，强制拦截，要求先跑验证。不验证，不让退出。
改造二：环境上下文注入
LocalContextMiddleware 在 Agent 启动时自动注入：当前目录结构、已安装工具、时间预算限制、评分标准。省去 Agent 自己摸索环境的时间。
改造三：死循环检测
LoopDetectionMiddleware 跟踪每个文件的编辑次数。对同一文件编辑超过 N 次时，自动注入提示："考虑重新审视你的方案"。
改造四：推理三明治策略
规划阶段
xhigh 推理
充分理解问题
执行阶段
high 推理
节省时间
验证阶段
xhigh 推理
精确抓 bug
全程最高推理模式反而因超时导致得分下降。在正确的阶段投入正确量级的推理，比全程最高推理效果更好。
5. 实际应用
5.1 LangChain Deep Agents 框架
LangChain 将 Harness Engineering 的理念直接落地成了开源框架 Deep Agents，把核心能力预置好，开箱即用。
Deep Agents Harness 框架
规划能力
write_todos 工具 / 结构化任务列表 / 状态持久化
虚拟文件系统
ls / read_file / write_file / edit_file / glob / grep / execute
上下文管理
输入上下文塑形 / 自动压缩摘要 / 子 Agent 隔离
子 Agent 委派
上下文隔离 / 并行执行 / 结果压缩返回
Skills & Memory
AGENTS.md 始终加载 / Skills 按需加载 / 渐进式披露
Human-in-the-loop
指定工具调用前暂停 / 人类审批或修改 / 安全门控
框架与 Harness Engineering 三大支柱的对应关系：
| Harness Engineering 支柱 | Deep Agents 框架能力 |
|---|---|
| 上下文工程 | Memory（AGENTS.md）+ Skills（渐进式披露）+ 上下文管理 |
| 架构约束 | Human-in-the-loop（关键操作门控） |
| 熵管理 | 子 Agent 隔离 + 上下文压缩 |
5.2 从零开始的实施路径
对于希望在自己项目中落地 Harness Engineering 的团队，可以按以下路径逐步推进：
需要持续投入
让日志和指标对 Agent 可查
关键日志输出到文件
定期跑清洁 Agent 任务
检查文档-代码一致性
建立 Trace 分析机制
用数据驱动 Harness 迭代
一周内能做
给 AI 工具加完成前必须验证规则
系统提示中强制 Plan-Build-Verify-Fix
建立进度追踪文件
解决上下文断裂问题
今天就能做
把 AGENTS.md 写成地图
列出项目结构、核心模块、关键约定
把反复出现的 Review 意见
变成 Linter 规则
6. 效果对比
6.1 LangChain 的定量验证
LangChain 提供了整个 Harness Engineering 讨论中最有说服力的定量数据：
| 指标 | 优化前 | 优化后 | 提升 |
|---|---|---|---|
| Terminal Bench 2.0 得分 | 52.8% | 66.5% | +13.7% |
| 排名 | 30 名开外 | 前 5 名 | 大幅跃升 |
| 模型 | gpt-5.2-codex | gpt-5.2-codex | 未变 |
关键结论：模型完全没变，纯靠 Harness 优化，排名从 30 名开外跃升至前 5。
各项改造的贡献分解：
| 改造项 | 解决的问题 | 效果 |
|---|---|---|
| Plan-Build-Verify-Fix 强制循环 | 模型写完就停、不做测试 | 显著提升验证覆盖率 |
| 推理三明治策略 | 全程高推理反而超时 | 性能与成本最优平衡 |
| 环境上下文注入 | Agent 浪费时间搞清楚自己在哪 | 减少环境误判错误 |
| 死循环检测 | Agent 反复改同一文件陷入 doom loop | 提升任务完成率 |
6.2 OpenAI 的规模验证
| 指标 | 数据 |
|---|---|
| 团队规模 | 3 名工程师（后扩展至 7 名） |
| 开发周期 | 5 个月 |
| 代码规模 | 约 100 万行 |
| PR 数量 | 约 1,500 个 |
| 人均日均 PR | 3.5 个（扩展后吞吐量还增加了） |
| 人工编写代码 | 零行 |
| 速度提升 | 约 10 倍 |
6.3 三家公司实践的互补关系
| 公司 | 核心贡献 | 解决的问题 |
|---|---|---|
| OpenAI | Harness 全貌（五层架构） | 从 0 到 1 搭建完整驾驭系统 |
| Anthropic | 长期运行设计 | 跨越上下文窗口的底层限制 |
| LangChain | 定量验证 + 迭代方法论 | 从 1 到 100 优化现有系统性能 |
7. 思考展望
7.1 尚未解决的核心问题
Birgitta Böckeler 在 Martin Fowler 网站上提出了一个被刻意回避的关键问题：
"所有描述的措施都聚焦于提高长期内部质量和可维护性。我在文章中缺少的是对功能和行为的验证。"
代码能跑、测试能过，不等于功能是正确的。这是整个 Harness Engineering 方法论目前最大的空白。OpenAI 自己也在文章末尾承认：
"我们尚不清楚的是，在一个完全由智能体生成的系统中，架构连贯性会如何随着时间的推移而演变。"
7.2 行业大辩论：Big Model vs Big Harness
随着模型能力不断提升，一个自然的问题是：Harness 的价值会被更强的模型所取代吗？
Big Harness 阵营
Big Model 阵营
更强的模型能自己解决问题
短期简单任务
模型直接搞定
长期复杂项目
Harness 不可或缺
熵增、上下文丢失
模式漂移不会消失
任务复杂度和持续时间
合理的分析框架是：这不是非此即彼的问题，而是任务复杂度和持续时间的函数。短期简单任务，更强的模型确实能直接解决；但长期复杂项目中，熵增、上下文丢失、模式漂移、信任债务累积这些问题不会因为模型更强而消失，Harness 的价值随任务复杂度和持续时间指数增长。
7.3 行业分裂的隐忧
Böckeler 指出了一个被低估的长远问题：
新项目世界：从零开始用 Harness Engineering，高度 AI 自治，工程师是系统设计师。
旧项目世界：遗留代码库，给它改造 Harness "就像在一个从未运行过 static analysis 的代码库上突然开启全部规则------你会被警报淹没"。
两个世界需要截然不同的技能组合，行业可能因此产生越来越深的鸿沟。
7.4 技术栈选择标准的变化
未来的项目模板可能不只包含代码脚手架，还包含自定义 Linter、结构化测试、基础文档和架构约束规则。技术栈的选择标准将新增一个维度：
"AI 友好性"------这个技术栈有没有好的 Harness 支持？训练数据中的表现如何？API 稳定性如何？
7.5 自适应 Harness：用 Agent 优化 Agent
LangChain 的 Trace Analyzer Skill 展示了一个令人兴奋的方向：用 Agent 来优化 Agent 的 Harness。
这是 meta 层面的自动化------Harness 本身也可以被自动迭代改进，而不只是靠人工分析。随着这个方向的成熟，Harness Engineering 的迭代速度将大幅提升。
7.6 对工程师职业的深远影响
Harness Engineering 正在重新定义"工程师"这个职业的价值所在。
软件开发的未来，可能不再是关于"我们能写多快多好的代码"，而是关于"我们能设计多聪明多鲁棒的系统来驾驭 AI Agent 的巨大能量"。
我们正在从构建产品 转向构建能够构建产品的工厂。
8. 参考资料
-
Ryan Lopopolo --- Harness Engineering: Working with Codex in an Agent-First World , OpenAI, 2026-02-11
https://openai.com/index/harness-engineering/ -
Birgitta Böckeler --- Harness Engineering , MartinFowler.com, 2026-02-17
https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html -
LangChain Team --- Improving Deep Agents with Harness Engineering , LangChain Blog, 2026-03
https://blog.langchain.com/improving-deep-agents-with-harness-engineering/ -
Justin Young --- Effective Harnesses for Long-Running Agents, Anthropic Engineering, 2025-11-26
-
Cassie Kozyrkov --- Harness Engineering: How to Supervise Code You Can't Read, Decision Intelligence, 2026-03-03
-
Mitchell Hashimoto --- My AI Adoption Journey , mitchellh.com
https://mitchellh.com/writing/my-ai-adoption-journey -
LangChain Docs --- Deep Agents: Harness Capabilities
https://docs.langchain.com/oss/python/deepagents/harness -
Latent Space --- Is Harness Engineering Real?, 2026-03-05