第一章：AI Harness 概论

为什么有人用 AI 十倍提效，有人一地鸡毛？

2026 年初，OpenAI 公布了一个令人震惊的数据：他们的一个内部团队，仅 3 名工程师，在 5 个月内用 Codex 生成了约 100 万行可上线的产品代码——没有一行是手写的。每位工程师平均每天合并 3.5 个 Pull Request，团队总共完成了约 1500 个 PR [1]。

与此同时，在技术社区的另一端，大量开发者的体验截然不同：

• 让 AI 写的代码"看起来能跑"，但越改越烂
• 需求稍微一复杂就开始胡说八道
• 几轮迭代之后，代码库变成了一团无人敢碰的浆糊
• 最终只能推倒重来

同样的模型，同样的工具，为什么结果天差地别？

很多人把 AI Agent 当成了自动驾驶——输入目的地，躺平等到站。但现实是，当前的 AI 助手更像一匹未经驯服的野马：力量惊人，速度极快，但如果没有缰绳、马鞍和跑道，它只会把你甩下来。

差距不在模型能力，而在于你是否建立了一套驾驭系统。

OpenAI 团队将这套系统称为 Harness [1]，Martin Fowler 网站上的深度分析将其上升为一种工程方法论——Harness Engineering（驾驭工程） [2]。

什么是 Harness Engineering

定义

Harness Engineering（驾驭工程） 是一套系统化的方法，用于约束、引导和支撑 AI 系统在可控边界内自主和可靠地工作。

它包含两个层面：

类比理解

传统软件测试 ≈ 选择题考试
  题目固定，答案固定，对就是对，错就是错

AI 系统评估 ≈ 作文批改
  题目开放，答案多样，需要多维度评分

AI Harness Engineering ≈ 驯马术 + 赛马规则
  不只是评判马跑得好不好（评估）
  更重要的是给马装上缰绳、划定跑道、清理障碍（驾驭）

"Harness"一词的由来

Harness 在英语中的本意是马具/挽具——缰绳、马鞍、挽具的统称。不是要消灭马的力量，而是引导它、控制它，让它的力量为你所用。

这个比喻精确地描述了人类与 AI 之间应有的关系：

graph LR
    subgraph "没有 Harness"
        A1[野马] -->|力量惊人但失控| A2[甩下骑手]
    end
    
    subgraph "有 Harness"
        B1[驯服的马] -->|缰绳引导方向| B2[高效到达目标]
        B3[马鞍提供稳定] --> B2
        B4[跑道划定边界] --> B2
    end
    
    style A2 fill:#f66,stroke:#333
    style B2 fill:#6f6,stroke:#333

失控的根源

在讨论如何驾驭之前，我们需要先理解"失控"到底发生在哪里。

大模型的信息边界

Code Agent 最容易被忽视的特性是它的信息边界：

Agent 在运行时无法在上下文中访问的内容，对它来说就不存在 [1]

• 你的 Google Docs 里写了详细的架构设计？不存在
• 你在 Slack 里和同事讨论了三天的技术方案？不存在
• 你脑子里那个"这里应该用单例模式"的想法？更不存在

对 Agent 来说，只有代码仓库本地的、已版本化的工件才是真实的——代码、文档、配置、计划。其余一切都是虚空。

更危险的是，Agent 会忠实地复现代码库中已有的模式——包括那些不理想的模式。如果你的代码库里有三种不同风格的错误处理，Agent 会随机挑一种来用。随着时间推移，这种模式复现会导致不可避免的漂移和熵增。

典型的"翻车姿势"

失败的本质

所有翻车姿势背后，指向同一个根因：

不是模型不够强，是环境不够明确。

OpenAI 团队坦承："早期进展比预期慢，原因不是 Codex 能力不足，而是我们没有为它提供足够清晰的工具、抽象层和内部结构。" [1]

当他们把精力从"让 Agent 更努力"转向"让环境更清晰"时，一切开始加速。

三大支柱

Harness Engineering 归纳为三大支柱：

graph TB
    A[Harness Engineering] --> B[上下文工程]
    A --> C[架构约束]
    A --> D[垃圾收集]
    
    B --> B1[让 Agent 看得见]
    C --> C1[让 Agent 不走偏]
    D --> D1[让代码库不腐烂]
    
    B1 --> B2[代码仓库作为<br/>唯一真相来源]
    B1 --> B3[渐进式披露]
    B1 --> B4[运行时可观测]
    
    C1 --> C2[确定性规则<br/>而非自然语言]
    C1 --> C3[分层架构]
    C1 --> C4[品味编码化]
    
    D1 --> D2[用 Agent 对抗<br/>Agent 的熵]
    D1 --> D3[技术债务持续偿还]
    D1 --> D4[文档花园维护]
    
    style A fill:#4a9,stroke:#333
    style B fill:#69d,stroke:#333
    style C fill:#d94,stroke:#333
    style D fill:#a4d,stroke:#333

支柱一：上下文工程 —— 让 Agent 看得见

核心命题：你必须把 Agent 需要知道的一切，显式地、结构化地放进代码仓库。

你不说，Agent 就不知道。

关键实践：

• 代码仓库是唯一的真相来源（System of Record）
• 渐进式披露：入口文件精简，详细信息分散在小文档中
• 让 Agent 能看见运行时：集成日志、指标、链路追踪
• 面向 Agent 可读性选择技术栈："枯燥"的技术反而更好用

支柱二：架构约束 —— 让 Agent 不走偏

核心命题：限制解决方案空间，才能增加输出的信任度和可靠性。

能用代码强制执行的约束，就不要用自然语言描述。

关键实践：

• 确定性规则 > 自然语言描述：linter、结构测试、CI 作业
• 修复指令注入：在错误信息中嵌入 Agent 可理解的修复指导
• 分层架构：单向依赖，机械地强制执行
• 品味编码化：代码风格、命名约定、日志格式

支柱三：垃圾收集 —— 让代码库不腐烂

核心命题：熵增不可避免，必须建立持续对抗熵增的机制。

用自动化对抗自动化，用 Agent 对抗 Agent 的熵。

关键实践：

• 漂移扫描：定期运行后台任务检测偏差
• 自动重构 PR：小而聚焦的重构请求，快速审查合并
• 文档花园：自动扫描过时文档并修复
• 技术债务如同高息贷款：持续小额偿还，不要让债务累积

三层演进：从 Prompt 到 Harness

2022-2026 的范式跃迁

AI 编程辅助领域经历了三次重大范式转移，每一次都重新定义了"人与 AI 协作"的含义：

2022  Prompt Engineering（提示词工程）
      │   核心信念：只要提示词写得好，AI 就能输出好结果
      │   代表实践：few-shot、chain-of-thought、角色扮演
      │   局限：对复杂任务无能为力，模型上下文窗口有限
      │
2025  Context Engineering（上下文工程）
      │   核心信念：问题不在提示词，在于给 AI 的上下文不够
      │   代表实践：RAG、长上下文、AGENTS.md、文档结构设计
      │   局限：只有"看得见"还不够，Agent 还会"走偏"
      │
2026  Harness Engineering（驾驭工程）
          核心信念：需要完整的约束-引导-支撑体系
          代表实践：架构约束 + 垃圾收集 + 评估体系 + 监控闭环
          标志：OpenAI Codex 团队 100 万行代码实践

graph TB
    subgraph "2022: Prompt Engineering"
        P1[提示词技巧] --> P2[单次交互]
    end
    
    subgraph "2025: Context Engineering"
        C1[RAG + 长上下文] --> C2[多轮对话]
        C3[AGENTS.md] --> C2
    end
    
    subgraph "2026: Harness Engineering"
        H1[上下文工程] --> H2[完整的驾驭体系]
        H3[架构约束] --> H2
        H4[垃圾收集] --> H2
        H5[评估 + 监控] --> H2
    end
    
    P2 -->|"上下文不够"| C1
    C2 -->|"Agent 走偏"| H1
    
    style P2 fill:#f96,stroke:#333
    style C2 fill:#ff6,stroke:#333
    style H2 fill:#6f6,stroke:#333

关键数据

一句话概括 Harness 的价值：

同一个模型，换一套运行环境，编程基准的成功率就从 42% 跳到了 78%。 [7]

这不是模型升级，这是环境升级。

操作系统类比

Hugging Face 的 Philipp Schmid 提出了一个精妙的类比 [8]：

AI Agent 系统类比操作系统：

┌─────────────────────────────────────────┐
│            Application (Agent)          │  ← 执行任务的应用
├─────────────────────────────────────────┤
│          Operating System (Harness)     │  ← 调度、约束、保护
├─────────────────────────────────────────┤
│  CPU (模型)    │  Memory (上下文)        │  ← 硬件资源
└─────────────────────────────────────────┘

没有 OS 的计算机 = 没有 Harness 的 Agent
├── 应用可以随意访问任何内存（上下文混乱）
├── 没有进程隔离（任务互相干扰）
├── 没有调度机制（资源浪费）
└── 任何一个 Bug 都可能让整个系统崩溃

arxiv 上的论文 [9] 将这一架构形式化为三层：

Scaffolding（脚手架层）
├── 工具定义、API 封装、基础交互协议
│
Harness（驾驭层）
├── 上下文管理、约束执行、错误恢复、进度跟踪
│
Context Engineering（上下文工程层）
├── 文档结构、知识注入、运行时信息

护栏悖论

行业实践中出现了一个反直觉的现象：

护栏悖论的数学表达：

短期速度 = 原始速度（护栏看起来是负担）
长期速度 = 原始速度 × 约束有效性（护栏是加速器）

当约束有效性 > 0 时：
├── 第 1 周：看起来慢了（加了 linter、CI）
├── 第 4 周：速度恢复（Agent 学会了自我纠正）
├── 第 12 周：速度反超（熵增被控制，代码库保持健康）
└── 第 24 周：差距拉大（无护栏团队的代码库已半腐烂）

路线之争：大模型 vs 大 Harness

Noam Brown 的"拐杖论"

OpenAI 的 Noam Brown（o1 模型的核心研究员）提出了一个尖锐的观点：

"很多所谓的 Harness 只不过是弱模型的拐杖。当模型足够强的时候，这些拐杖反而成了束缚。" [7]

这个观点在学术界有不少支持者。他们认为：

拐杖论的核心逻辑：
├── 当前模型还不够强 → 需要 Harness 补偿
├── 模型会持续进化 → Harness 终将多余
├── 过度投资 Harness → 浪费工程资源
└── 结论：把资源投入到模型训练上

代表证据：
├── GPT-3 → GPT-4 的能力跃迁
├── SWE-bench 分数持续刷新
└── few-shot → zero-shot 的趋势

实践派的反驳

然而，真正大规模使用 Agent 的工程团队给出了不同的答案：

实践派的逻辑：
├── 模型再强也需要约束 → 速度带来的熵增是物理规律
├── OpenAI 自己在用 Harness → 100 万行代码不是靠"更强的模型"
├── 约束和模型是互补的 → 不是替代关系
└── 结论：模型越强，Harness 越重要

代表证据：
├── OpenAI Codex 团队的三大支柱实践
├── Stripe 1300 PR/周的 Agent 模式
├── Cursor 的"constraints > instructions"发现
└── Anthropic 的长时运行 Agent 最佳实践

两种观点的和解

更准确的理解是：这两者不矛盾。

graph TB
    subgraph "模型能力提升"
        M1[更强的推理] --> M2[更少的错误]
        M2 --> M3[更广的任务范围]
    end
    
    subgraph "Harness 进化"
        H1[更精细的约束] --> H2[更高的吞吐]
        H2 --> H3[更复杂的系统]
    end
    
    M3 -->|"解锁更复杂任务"| H1
    H3 -->|"暴露新能力边界"| M1
    
    style M3 fill:#69d,stroke:#333
    style H3 fill:#d94,stroke:#333

和解公式：

有效产出 = 模型能力 × Harness 有效性

情况 A：强模型 + 无 Harness → 高初始速度，快速衰减
情况 B：弱模型 + 强 Harness → 稳定但产出有限
情况 C：强模型 + 强 Harness → 指数级增长 ← 目标

从评估到驾驭：本书的完整框架

Harness Engineering 不仅仅是"评估 AI 输出好不好"，更是一个完整的驾驭体系：

graph TB
    subgraph "广义驾驭层"
        C1[上下文工程]
        C2[架构约束]
        C3[垃圾收集]
    end
    
    subgraph "评估测试层"
        E1[评估体系设计]
        E2[测试方法论]
        E3[架构实现]
    end
    
    subgraph "实战应用层"
        P1[LLM 评估]
        P2[RAG 评估]
        P3[Agent 评估]
        P4[监控优化]
    end
    
    C1 & C2 & C3 --> E1
    E1 & E2 & E3 --> P1 & P2 & P3 & P4
    P4 -.->|反馈| C1 & C2 & C3

评估测试的本质差异

开发者角色的转变

Harness Engineering 意味着开发者角色的根本性转变：

graph LR
    A[写代码的人] -->|AI 时代| B[设计环境的人]
    
    B --> B1[设计约束规则]
    B --> B2[设计反馈回路]
    B --> B3[设计控制系统]

三阶段演变

这并不意味着工程能力变得不重要——恰恰相反。设计一个好的驾驭系统，需要对架构、测试、自动化和软件工程原则有更深的理解。

实践循环：从今天开始

你不需要一步到位。核心循环很简单：

graph TB
    A[Agent 在某个任务上挣扎] --> B[识别缺失的约束/文档/工具]
    B --> C[补充缺失的部分<br/>最好让 Agent 自己来写]
    C --> D[纳入体系]
    D --> E[Agent 下次表现更好]
    E --> A

OpenAI 团队的原话："当 Agent 挣扎时，我们将其视为信号：识别缺失的内容——工具、护栏、文档——并将其反馈到仓库中，始终让 Codex 自己编写修复程序。" [1]

今天就可以做的快速诊断：

• 你有预提交钩子吗？它们检查什么？
• 你有自定义 linter 规则吗？还是只用默认配置？
• 你的项目有 AGENTS.md 吗？它有多长？
• 你的架构约定是写在文档里，还是通过代码强制执行的？
• 当 Agent 写出不符合预期的代码时，你的第一反应是手动修改，还是思考"缺了什么约束"？

章节安排

第一部分：基础篇（你正在这里）
├── 第一章：AI Harness 概论
├── 第二章：AI 系统的特殊性
├── 第三章：上下文工程 —— 让 Agent 看得见
├── 第四章：架构约束 —— 让 Agent 不走偏
└── 第五章：垃圾收集 —— 与熵的持久战

第二部分：方法论篇
├── 第六章：评估体系设计
└── 第七章：AI 测试方法论

第三部分：架构与实现篇
├── 第八章：Harness 架构设计
└── 第九章：核心组件实现

第四部分：实战篇
├── 第十章：LLM 评估实战
├── 第十一章：RAG 评估实战
├── 第十二章：Agent 评估与 Multi-Agent
└── 第十三章：监控与持续优化

附录
├── 工具与框架
├── 评估指标速查
├── FAQ 与最佳实践
└── 读者练习与实践

小结

参考文献：

• [1] Ryan Lopopolo, "Harness engineering: leveraging Codex in an agent-first world", OpenAI, 2026
• [2] Birgitta Böckeler, "Harness Engineering", martinfowler.com, 2026
• [7] "模型不是关键，Harness 才是", 微信公众号, 2026
• [8] Philipp Schmid, "The OS Analogy for AI Agents", Hugging Face, 2026
• [9] arxiv, "Scaffolding, Harness, and Context Engineering: A Three-Layer Architecture for AI Agents", 2026

下一章，我们将深入探讨 AI 系统的特殊性，理解为什么传统方法失效的根本原因。

行业数据：AI 质量问题的真实代价

根据行业研究报告数据：

引用来源：

• [3] Gartner, "Generative AI Hype Cycle", 2024
• [4] OWASP, "Top 10 for LLM Applications", 2024
• [5] McKinsey, "The State of AI in 2024"
• [6] Stanford HAI, "AI Index Report 2024"

ROI 分析

成本构成

收益分析

ROI 计算示例

假设：
- 年度 AI 服务收入: $1M
- 平均质量事故损失: <span class="katex"><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:1em;vertical-align:-0.25em;"></span><span class="mord">100</span><span class="mord mathnormal" style="margin-right:0.07153em;">K</span><span class="mord">/</span><span class="mord cjk_fallback">次</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="mbin">−</span><span class="mspace" style="margin-right:0.2222em;"></span></span><span class="base"><span class="strut" style="height:0.6833em;"></span><span class="mord cjk_fallback">历史事故频率</span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel">:</span><span class="mspace" style="margin-right:0.2778em;"></span></span><span class="base"><span class="strut" style="height:1em;vertical-align:-0.25em;"></span><span class="mord">4</span><span class="mord cjk_fallback">次</span><span class="mord">/</span><span class="mord cjk_fallback">年</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="mbin">−</span><span class="mspace" style="margin-right:0.2222em;"></span></span><span class="base"><span class="strut" style="height:0.6833em;"></span><span class="mord mathnormal" style="margin-right:0.08125em;">H</span><span class="mord mathnormal">a</span><span class="mord mathnormal" style="margin-right:0.02778em;">r</span><span class="mord mathnormal">n</span><span class="mord mathnormal">ess</span><span class="mord cjk_fallback">投入</span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel">:</span></span></span></span>100K 初期 + <span class="katex"><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:1em;vertical-align:-0.25em;"></span><span class="mord">20</span><span class="mord mathnormal" style="margin-right:0.07153em;">K</span><span class="mord">/</span><span class="mord cjk_fallback">年收益</span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel">:</span><span class="mspace" style="margin-right:0.2778em;"></span></span><span class="base"><span class="strut" style="height:0.7667em;vertical-align:-0.0833em;"></span><span class="mord">−</span><span class="mord cjk_fallback">事故减少</span><span class="mord">50</span></span></span></span>200K/年
- 效率提升 30% → 价值 <span class="katex"><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:1em;vertical-align:-0.25em;"></span><span class="mord">100</span><span class="mord mathnormal" style="margin-right:0.07153em;">K</span><span class="mord">/</span><span class="mord cjk_fallback">年</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="mbin">−</span><span class="mspace" style="margin-right:0.2222em;"></span></span><span class="base"><span class="strut" style="height:0.6833em;"></span><span class="mord cjk_fallback">总收益</span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel">:</span></span></span></span>300K/年

ROI = (<span class="katex"><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.7667em;vertical-align:-0.0833em;"></span><span class="mord">300</span><span class="mord mathnormal" style="margin-right:0.07153em;">K</span><span class="mord">−</span></span></span></span>20K) / $100K = 280% (首年)

组织架构建议

团队角色分工

与其他团队的协作