Harness Engineering 深度解读：AI Agent 时代的工程范式革命

基于六篇核心文献的综合分析：OpenAI (Ryan Lopopolo)、Anthropic (Justin Young)、Martin Fowler (Birgitta Böckeler)、LangChain、Latent Space、Cassie Kozyrkov

一、什么是 Harness Engineering？

Harness Engineering 是 2025-2026 年 AI 工程领域最重要的新概念之一。它不是一个工具，不是一个框架，而是一套围绕 AI Agent 构建的约束、反馈与控制系统------让 Agent 在人类设定的边界内自主、可靠、可持续地工作。

用一个核心公式表达：

Harness Engineering ≠ 优化模型 → 优化模型运行的"环境"

这个概念的命名可能源自

Mitchell Hashimoto

（HashiCorp 创始人）的博客文章。Birgitta Böckeler 在 Martin Fowler 网站上指出："我喜欢 'harness' 这个词来描述我们用于管控 AI Agent 的工具和实践。"

与前两代范式的关系

关键跃迁：Prompt Engineering 和 Context Engineering 本质上仍是"人给输入，AI 给输出"的范式。

Harness Engineering 的质变在于------人不再直接干预 AI 的每一步操作，而是构建一整套系统来约束、引导和验证 AI Agent 的自主行为。

交互模式从"你问我答"变成了"赛道设计"。

二、为什么需要 Harness Engineering？

2.1 Agent 的"翻车"规律

Anthropic 的 Justin Young 通过长期观察 Claude 的行为，发现了一个核心规律：给 Agent 一个复杂的全栈项目，它的第一反应是试图在一个会话里把所有功能都做完。结果：

• 做到一半 context window 耗尽
• 留下半成品代码------功能写了一半没测试，模块间接口对不上
• 没有任何记录------下一个 Agent 会话不知道前一次做了什么
• 更糟糕的情况：Agent 过早宣布完成，实际上大量功能未经验证

这不是某个模型的个别问题，而是所有 Agent 的结构性缺陷。

2.2 "信任债务"（Trust Debt）概念

Cassie Kozyrkov（前 Google 首席决策科学家，现 Data Scientific CEO）提出了一个极具洞察力的概念------信任债务：

AI 就像一个极其听话但缺乏背景知识的实习生。它倾向于填补你指令中的空白，进行"自信的即兴发挥"。如果你不审计它的假设，这些假设就会变成"信任债务"------目前看起来没问题，但在未来某个时刻会爆炸。

信任债务的危险在于：

1. 不可见性：AI 做了你没要求的决定，但当时看起来合理
2. 累积性：每一次未审计的决定都在叠加风险
3. 爆发性：到出问题时，你得逆向工程那些你从未意识到的假设，代价极高

2.3 范式错位

问题的根源在于：

我们已经从"人写代码"进入了"AI 写代码"的时代但配套的工程体系还停留在"人写代码"的范式里

传统软件工程的所有实践------Code Review、架构规范、文档维护------都假设人类是代码的创作者。当 Agent 一天生成几百个 PR 时，这些假设全部崩塌：

• 人工 Code Review 变成瓶颈
• 靠人记住架构规范不现实
• 文档更新跟不上代码变化速度

Harness Engineering 就是为了填补这个空白而生的。

三、OpenAI 百万行代码实验深度分析

3.1 实验设计

Ryan Lopopolo 在 2026 年 2 月 11 日发布的文章披露了一个为期 5 个月的内部实验：

3.2 工程师角色转变

最深刻的发现不是数字，而是工程师角色的根本改变：

工程师不写代码之后，80% 的时间花在了构建 Harness 上------那套让 AI 能够自主、可靠、可持续工作的基础设施。

Ryan Lopopolo 用八个字概括核心理念：人类掌舵，智能体执行。

当 Agent 遇到困难时，工程师的思考不是"我该怎么帮它写完这段代码"，而是追问："Agent 缺乏什么能力？需要什么工具、什么抽象层、什么结构？" 然后由人类补充这些基础设施。

这意味着工程师从 "代码的编写者" 变成了 "环境的建筑师"。

3.3 Harness 的三大组件（Böckeler 归纳）

Birgitta Böckeler 在 Martin Fowler 网站上将 OpenAI 团队的 Harness 归纳为三个类别：

1 Context Engineering（上下文工程）

• 代码库中持续增强的知识库
• Agent 访问动态上下文的能力（可观测性数据、浏览器导航等）
• 不是一个巨大的全知文档，而是"地图式"的渐进式信息披露

2 Architectural Constraints（架构约束）

• 不仅由 LLM Agent 监控
• 更由确定性的自定义 linter 和结构化测试强制执行
• 层级依赖模型：Types → Config → Repo → Service → Runtime → UI
• 违反层级依赖的代码直接在 CI 中被拒绝

3 "Garbage Collection"（垃圾回收）

• 后台定期运行的清理 Agent
• 扫描文档与代码之间的不一致
• 扫描架构约束的违规
• 对抗熵增和腐烂------这是所有大型代码库的天敌

OpenAI 团队的迭代理念完美体现了 Harness 的核心思想：

"当 Agent 遇到困难时，我们将其视为一个信号：识别缺少什么------工具、护栏、文档------然后将其反馈到代码仓库中，始终由 Codex 本身来编写修复。"

3.4 Böckeler 的批判性分析

Böckeler 并非全盘接受 OpenAI 的叙事。她指出了一个明显缺失：

"所有描述的措施都聚焦于提高长期内部质量和可维护性。我在文章中缺少的是对功能和行为的验证。"

她还提醒读者注意利益相关性："OpenAI 在让我们相信 AI 可维护代码方面有既得利益。"

这是一个重要的平衡视角------Harness Engineering 听起来很美，但验证功能正确性这个最关键的环节，在 OpenAI 的文章中并不充分。

四、Anthropic 的长跑方案：跨越上下文窗口的断裂

4.1 核心问题

Justin Young 解决的是一个更底层的问题：Agent 怎么跨越 context window 的限制，实现真正的长期运行？

AI 的 context window 有限，一个复杂项目不可能在单个窗口内完成。每次新开会话，Agent 就像失忆了------不知道之前做过什么。

4.2 双层 Agent 架构

Anthropic 的解法是一个精妙的双层架构：

4.3 三个精妙的设计

设计一：全标失败策略

所有功能的初始状态标记为 "失败"。Agent 只能通过修改状态字段来标完成，不允许删除或编辑测试用例。

这堵死了 Agent 通过"降低标准"来"完成"任务的路。

设计二：每次只做一件事

Anthropic 发现 Agent 有强烈的"贪多嚼不烂"倾向。强制 "做一个功能就停" 看起来效率低，但实际上总体完成率高得多。

这背后的逻辑是：与其让 Agent 试图一次吃完蛋糕但半途而废，不如让它一块一块地吃，每块都吃完。

设计三：进度文件作为跨会话记忆

claude-progress.txt 不只是日志，它是 Agent 的 "外部记忆"：

• 每个新会话的第一件事：读进度文件 + git log
• 搞清楚"上一个自己"做了什么
• 从断点继续，而非从零开始

五、LangChain 的硬核定量验证

5.1 实验结果

LangChain 提供了整个 Harness Engineering 讨论中最有说服力的定量数据：

这是 Harness Engineering 最有力的证据：同一个模型，仅改变 Harness，排名从 30+ 跃升至 Top 5。

5.2 Trace Analyzer Skill：用 Agent 优化 Agent 的 Harness

LangChain 最创新的贡献是 Trace Analyzer Skill------一套 meta 层面的自动化工具：

1. 从 LangSmith 获取上一轮运行的追踪数据
2. 并行启动多个错误分析 Agent，各自诊断失败原因
3. 主 Agent 综合所有发现，提出 Harness 改进建议
4. 对 Harness 做针对性修改，进入下一轮

这个流程类似机器学习中的 Boosting------每一轮聚焦上一轮的错误，迭代改进。

5.3 四个关键改动详解

改动一：Plan-Build-Verify-Fix 强制闭环

Agent 最常见的失败模式：写完代码，自己看一遍觉得"看起来没问题"，然后就停了------不跑测试。

LangChain 的解法：PreCompletionChecklistMiddlewareAgent 宣告完成之前，mandatory 拦截，强制它跑验证。这类似

Ralph Wiggum Loop

，在 Agent 试图退出时用 hook 强制它继续执行验证步骤。

四步工作流：

1. Planning & Discovery：读任务、扫描代码库、建立初始计划
2. Build：实现计划，同时构建测试
3. Verify：运行测试，对照任务规格（不是对照自己的代码） 检查结果
4. Fix：分析错误，回溯原始规格，修复问题

改动二：环境上下文注入

LocalContextMiddleware 在 Agent 启动时就注入：

• 目录结构
• 可用工具（如 Python 安装路径）
• 超时时间
• 测评标准

LangChain 的定义精辟："Harness 工程师的职责是：准备和投递上下文，使 Agent 能够自主完成工作。"

改动三：死循环检测

LoopDetectionMiddleware 跟踪每个文件的编辑次数。当对同一文件编辑超过 N 次时，注入提示："考虑重新审视你的方案"。

LangChain 诚实地承认：这是针对当前模型缺陷的设计启发式。随着模型改进，这些护栏可能会变得不必要。但今天，它们帮助 Agent 正确且自主地执行。

改动四：推理三明治策略

不是"推理越多越好"。gpt-5.2-codex 有 4 个推理等级：low、medium、high、xhigh。

三明治策略：规划阶段用 xhigh（理解问题需要深度推理），执行阶段降档到 high（节省时间），验证阶段再回到 xhigh（抓 bug 需要深度推理）。

这个发现非常实用：推理资源是有限的，在正确的阶段投入正确量级的推理，比全程最高推理效果更好。

六、Cassie Kozyrkov 的管理者视角：12 条 Harness 法则

Cassie Kozyrkov 从管理者和决策科学的角度提出了 12 条 Harness Engineering 法则，核心思想包括：

核心原则

1. 人类掌舵，Agent 执行：工程师的角色是设计环境、明确意图、构建反馈回路
2. 可读性优先（Legibility）：Agent 的行为和决策链路必须对人类可追溯
3. 明确边界：越清晰的规矩 → 越大的 Agent 自主权
4. 全面文档化：不只是给人看，更是给下一个 Agent 看
5. 管理吞吐量：Agent 一天几百个 PR 时，必须有自动化审查机制
6. 持续清理：对抗代码库的熵增
7. 知道何时升级：哪些决策必须由人类做

信任债务的管理策略

Kozyrkov 强调：即使 Agent 表现优秀，也要像它是"Chris Careless"（最粗心的员工）一样建立安全网。

这不是对 AI 的不信任，而是工程上的审慎：

• 对最好的情况保持预期
• 对最差的情况做好防护
• 永远不要假设 AI 是完美的

七、行业大辩论：Big Model vs Big Harness

Latent Space 在 2026 年 3 月 5 日发起的文章将行业劈成两个阵营：

我的分析：时间尺度决定答案

这不是非此即彼的问题，而是任务复杂度和持续时间的函数：

短期 / 简单任务 → Big Model 胜出
  ↓ 复杂度增加
  ↓ 时间跨度增加  
长期 / 复杂项目 → Big Harness 不可或缺

• 熵增：代码越多，模式越分裂
• 上下文丢失：跨会话记忆断裂
• 模式漂移：Agent 复现已有的坏模式
• 信任债务：伏累积到不可逆

让一匹好马跑 100 米，不需要缰绳。让它拉着货物跑 100 公里穿越山路，没有缰绳不行。Harness 的价值随着任务的复杂度和持续时间指数增长。

八、五大核心组件深度拆解

综合六篇文献，Harness 的核心组件可以归纳为五层：

组件一：结构化知识系统

核心原则：AGENTS.md 当地图，不当百科全书。

repo/
├── AGENTS.md          ← 目录/地图，指向下面的详细文档
├── docs/
│   ├── architecture/  ← 整体架构设计
│   ├── domains/       ← 各业务域的详细文档
│   ├── plans/         ← 执行计划（版本控制的一等工件）
│   ├── specs/         ← 产品规格
│   └── runbooks/      ← 操作手册

关键洞察：

• context window 是稀缺资源------全塞进去反而淹没关键信息
• 大而全的文档腐烂最快------过时信息比没有信息更危险
• 需要 doc-gardening Agent 做自动文档维护

组件二：机械化架构约束

核心原则：把"品味"编码成机器可执行的检查。

这是最反直觉但最有效的部分。Birgitta Böckeler 精辟总结：

为了获得更高的 AI 自主性，运行时必须受到更严格的约束。增加信任需要的不是更多自由，而是更多限制。

具体做法：

• 层级依赖规则写成 Linter 规则，不是写在文档里靠人记
• Linter 错误信息本身就是教学材料------解释"为什么这个规则存在、正确做法是什么"
• Agent 遇到 Lint 错误时能自我理解并修正，无需人类介入

组件三：可观测性注入

核心认知转变：观测不再只是给人看的，而是给 AI 看的。

OpenAI 的做法：

• git worktree 启动独立应用实例
• 接入 Chrome DevTools Protocol，Agent 像人一样操作浏览器
• 用 LogQL/PromQL 查询日志和监控
• 执行可量化的验证任务："确保服务在 800ms 内启动"

Anthropic 的做法：

• 截图验证------用 Puppeteer 操作应用然后截图对比预期
• "显著提高了性能，使 Agent 能够识别并修复仅从代码中看不出的 Bug"

组件四：自修复闭环

核心问题：Agent 大量生成代码时，熵增速度放大十倍。

AI 会复现代码库中已有的坏模式------如果某处有烂代码，Agent 在相邻模块工作时可能模仿这种写法，导致坏模式扩散。

解法：代码库的"垃圾回收机制"

• 后台定期运行清洁 Agent
• 扫描偏离"黄金标准"的代码
• 自动提交重构 PR → CI 验证 → 自动合并
• 小额、高频、持续偿还技术债务

组件五：Agent 互审机制

核心问题：系统一天几百个 PR 时，人工 Code Review 是严重瓶颈。

OpenAI 的 Ralph Wiggum Loop：

• Agent A 写代码
• Agent B 审代码
• 有问题 → Agent A 改完再提交
• 直到 Agent B 通过

**人类的角色缩减到只介入架构层面的重大决策。**日常代码风格、逻辑正确性、测试覆盖------全部 Agent 互审。

九、Böckeler 的深层思考：被低估的未来影响

Birgitta Böckeler 在 Martin Fowler 网站上提出了几个被低估但极其重要的问题：

9.1 Harness 模板 = 未来的服务模板？

大多数组织只有两三种主要技术栈。未来的模板可能不只包含代码脚手架，还包含自定义 Linter、结构化测试、基础文档、架构约束规则。

技术栈的选择标准会因此改变------过去看社区活跃度、文档质量、开发者体验。以后要加一条："AI 友好性"------这个技术栈有没有好的 Harness 支持？

9.2 约束换自主的悖论

"为了可信赖的、AI 生成的大规模可维护代码，必须有所让步。所描述的 Harness 表明，增加信任和可靠性需要约束解空间：特定的架构模式、强制的边界、标准化的结构。这意味着放弃'生成任何东西'的灵活性。"

换言之："LLM 可以生成任何语言、任何模式"的早期炒作是误导性的。 要在规模上获得可靠结果，必须限制 Agent 的行动空间。

9.3 两个世界的分裂

给遗留代码库改造 Harness，"就像在一个从未运行过 static analysis 的代码库上突然开启全部规则------你会被警报淹没"。

行业可能分裂为：

• 新项目世界：从零开始用 Harness Engineering，高度 AI 自治
• 旧项目世界：遗留代码库，继续以人工为主

两个世界需要的技能组合截然不同。

9.4 对 OpenAI 叙事的怀疑

Böckeler 保持了健康的批判态度：

• OpenAI 花了 5 个月 建 Harness------这不是一蹴而就的事
• 文章缺少功能和行为的验证方面的讨论
• OpenAI 有既得利益让人相信 AI 可维护代码

"令人耳目一新的是听到关于严谨性应去向何处的具体想法和经验，而不是仅仅寄希望于'更好的模型'会神奇地解决可维护性问题。"

十、Harness Engineering 的本质洞察

10.1 核心逻辑：约束换自主

这是整个 Harness Engineering 最深刻的思想：

规矩越明确 → Agent 独立做的事越多约束越严格 → 信任越高 → 自主权越大

听起来矛盾，但和人类社会的运转逻辑完全一致：

• 法律越完善的社会，个人自由度越高
• 高速公路有护栏，你才敢踩到 120 码
• 手术室无菌规程越严格，手术越安全

10.2 工程师职业的重新定义

Harness Engineering 正在重新定义"工程师"这个职业：

传统工程师Harness 时代工程师价值 = 写代码的速度和质量价值 = 设计系统的能力核心技能 = 编码核心技能 = 约束设计、反馈回路设计、控制系统设计产出 = 代码产出 = Agent 可靠运行的环境关注 = 代码本身关注 = 支撑结构（工具、抽象、反馈回路）

"构建软件仍然需要纪律，但这种纪律更多地体现在支撑结构上------工具、抽象、反馈回路------而不是代码本身。" ------OpenAI

10.3 LangChain 的定义

Harness Engineering 是对模型智能的"塑形"------模型的能力参差不齐，Harness 的工作就是把这些能力塑造成适合具体任务的形状。

十一、落地指南：从今天开始

今天就能做

1. 把 AGENTS.md 写成地图：列出项目结构、核心模块、关键约定，指向详细文档位置。Agent 需要的是"去哪里找信息"，不是"所有信息"。
2. 把反复出现的 Review 意见变成 Linter 规则：ESLint 自定义规则、pre-commit hook、ArchUnit 结构化测试，把人的"品味"编码成机器可执行的检查。

一周内能做

1. 给 AI 工具加"完成前必须验证"的规则：在系统提示中加一条------标记任务完成之前，必须跑测试、启动应用验证、UI 变更要截图检查。
2. 建立进度追踪文件：为复杂任务创建 Agent 可读写的进度文件，每个工作单元完成后更新。解决上下文断裂问题。

需要投入时间

1. 让日志和指标对 Agent 可查：关键日志输出到文件，Agent 工具列表加"查看最近 N 行日志"的能力。
2. 定期跑"清洁 Agent"任务：每周一次，检查文档-代码一致性、架构违规、可抽象的重复模式。

十二、总结：三句话理解 Harness Engineering

1. 解决的不是"怎么让 AI 更聪明"，而是"怎么让 AI 可控地持续工作"。 聪明是模型公司的事，可控是工程师的事。
2. 核心逻辑是"用约束换自主"。 给 AI 设的规矩越明确，它能独立做的事就越多。
3. 正在重新定义"工程师"。 你的价值不再取决于写代码的速度，而取决于你设计约束、反馈回路和控制系统的能力。

AI 已经是千里马。千里马没缰绳，跑得再快也到不了目的地。Harness Engineering，就是这个时代最重要的缰绳。

参考文献

1. Ryan Lopopolo, Harness Engineering: Working with Codex in an Agent-First World, OpenAI, 2026.02.11

2. Birgitta Böckeler,Harness Engineering,MartinFowler.com, 2026.02.17

3. LangChain,Improving Deep Agents with Harness Engineering, 2026

4. Latent Space, Is Harness Engineering Real?, 2026.03.05

5. Justin Young, Effective Harnesses for Long-Running Agents, Anthropic Engineering, 2025.11.26

6. Cassie Kozyrkov, Harness Engineering: How to Supervise Code You Can't Read, Decision Intelligence, 2026.03.03