Harness Engineering 驾驭工程：原理与概念

一、驾驭工程是什么

1.1 三层次能力对比

1.2 Agent = Model + Harness

Agent = Model + Harness

—— Vivek Trivedy 在首篇 HaaS 博文（2025-09-23）中给出这一公式化表达；Birgitta Böckeler 于 2026-04-02 在 martinfowler.com 整理传播。

1.3 同任务三模式

• 裸 API：返回三块代码，但永远不会真的创建文件、运行测试、看到测试失败后自己改。它只是在对话框里写字。

• Code Interpreter：真的创建 .py 文件、运行 pytest、看到失败。但没有访问本地项目的能力，没有 git，关闭窗口所有进度清零。

• Claude Code：在本地创建完整项目结构，写完代码跑 pytest，失败了就改，最后 commit 到 git，下次打开从进度文件接着跑。

二、承认抵触——为什么驾驭工程不是新瓶装旧酒

2.1 你的软件工程师直觉没有错

"这不就是 feedback control 吗？控制系统搞了几十年了。" "换个名字就能发博客涨粉。" "LangChain 三年前就在做这件事，只是现在包装成新概念。"

2.2 四条来自一手源的证据

2.3 译名锁定

三、三代工程的包含关系与术语边界

3.1 三代工程：包含关系而非替代关系

• 提示词工程（2022-2023）：管单轮 LLM 对话里如何把问题问得更好。

• 上下文工程（2024-2025）：管多轮对话里喂给 LLM 的信息如何更精准——包括 RAG、tool calling schema、对话历史管理、instruction caching。

• 驾驭工程（2025-2026）：管多轮工具调用 + 长时间运行时，整个系统如何不失败——包括循环刹车、状态持久化、验证闭环、子代理分治。

3.2 术语边界

⚠️ 常见误区：把 scaffolding 当 harness 的同义词。很多博客把 "prompt scaffolding" 和 "harness" 混用，让读者低估 harness 的工程复杂度。真正的 harness 必须覆盖：(a) 循环终止刹车、(b) 跨 session 进度持久化、(c) 真机功能验证——三者缺一就不是完整 harness。

3.3 LangChain 三层架构

四、为什么此刻是驾驭工程的拐点

4.1 Karpathy 的判断：2025 Q3 是分水岭

"Agents basically didn't work before December [2024]. Now they just barely work. And this is the window where harness engineering becomes real engineering." —— Andrej Karpathy（YC AI Startup School 2025-06-17 主题演讲）

4.2 8 节点时间轴

4.3 两个决定性证据

证据一（LangChain 2026-02-17）：同模型、同 benchmark、只改 harness，Terminal Bench 2.0 从 52.8% → 66.5%，+13.7 个百分点。

证据二（OpenAI 2026-02-11）：一个内测产品，5 个月、约 100 万行代码、约 1500 个 PR、全程零人工编码、开发时间约为传统方式的 1/10。

五、Naive Agent 的八大故障模式

5.1 ~50 行 Naive Agent 完整代码

⚠️ 踩坑预警：subprocess.run 的 returncode 被丢弃。run_pytest 函数只返回 result.stdout，而 result.returncode 被直接丢掉——这意味着即使 pytest 失败，agent 拿到的也只是一段普通字符串，它会以为任务成功。正确做法：显式保留 returncode——return {"passed": result.returncode == 0, "output": result.stdout + result.stderr}。

5.2 八大故障模式清单

六、八大机制——逐一击破故障模式

6.1 Agent Loop 四相循环（解 ① 循环失控）

官方出处：Building agents with the Claude Agent SDK（Anthropic，2025-09-29）

6.2 Tool Use 工具编排（解 ④ tool 错误吞）

官方出处：Building agents with the Claude Agent SDK（Anthropic，2025-09-29）；MCP（Model Context Protocol）官方规范进一步标准化了这种 schema 契约。

6.3 Progress Tracking 进度追踪（解 ⑤ 状态丢失）

官方出处：Effective Harnesses for Long-Running Agents（Anthropic，2025-11-26，Justin Young）

6.4 Context Management 上下文管理（解 ② context 溢出 / ③ cache miss）

⚠️ 踩坑预警：在 system prompt 里加时间戳、用户名、当前任务。很多开发者把当前任务状态写进 system prompt，以为"让模型知道当前在做什么"更好——实际上这会让每轮的 system prompt 前缀都不同，prompt cache 全部失效。正确做法：system prompt 只放固定的"角色定义"，当前任务全部放进 user 消息。

官方出处：Automatic Context Compaction Cookbook（Claude Agent SDK 官方）

6.5 Feature List 任务拆解（解 ② context 溢出的源头）

6.6 Verification Loop 验证闭环（解 ④ tool 错误的下游）

官方出处：Effective Harnesses for Long-Running Agents（Anthropic，2025-11-26）

6.7 Subagents 子代理分治（解 ② context 溢出的另一种解法）

官方出处：Building agents with the Claude Agent SDK（Anthropic，2025-09-29）

6.8 Generator-Evaluator（GAN 启发的三角色架构，解 ⑦ 缺自动化评审）

官方出处：Harness Design for Long-Running Application Development（Anthropic，2026-03-24，Prithvi Rajasekaran）

6.9 机制 × 故障模式对照表

注：⑥ 缺权限闸和 ⑧ 成本失控的完整解决方案（Permission Gate 权限闸 / Token Budget 成本预算）后面讲解。

七、三支柱正交视角

7.1 三支柱定义

来源说明：三支柱是本课程综合 Martin Fowler 系博客（Böckeler 2026-04-02）、Anthropic Rajasekaran（2026-03-24）、Phil Schmid（2026-01-05）多来源抽象的工程维度框架。

7.2 三支柱视角的价值

• Context Engineering (输入端：怎么在第一时间把对的资料喂给它)：Claude Code 读取你项目目录里的 CLAUDE.md（相当于 RAG 系统 prompt）、在长会话时触发 session 压缩（compaction）、把进度写进 progress 文件——这三项都在"整理 agent 看见的信息"。

• Architectural Constraints (控制流：它发疯的时候，你怎么硬生生把它按住)：Claude Code 提供 27 种 hook 让你约束工具行为、内置 Permission Gate 控制危险操作、通过 Task tool（subagent 机制）做分治隔离——这三项都在"约束 agent 能做什么"（设红线、拉电闸）。

• Garbage Collection (状态流：内存快被撑爆时，怎么有策略地遗忘)：Claude Code 有 token budget 防爆预算、做 session compaction 回收过期上下文；Anthropic 2025→2026 的工程路线注释也在从 compaction 逐步转向 reset——这条支柱核心是容错与动态收敛。

• 按机制视角：它解了八大故障模式里的哪几条？

• 按支柱视角：它主要投资在哪一柱？

7.3 八大机制 × 三支柱对照表

八、生态地图——坐标系的实战运用

8.1 10+ 主流 Harness 产品全景

8.2 四系家族树

九、三句官方警示——harness 不是银弹

9.1 警示一：harness 会过时

"A harness encodes assumptions that go stale. What works for Claude 3.5 may not work for Claude 4.5." ——Anthropic 官方博文（2025-11-26，Justin Young）

9.2 警示二：Build to Delete（建造以便删除）

"The best harness is the one you're most willing to throw away and rewrite. The dataset of failures from your current harness is more valuable than the harness itself." ——Phil Schmid（2026-01-05，Bitter Lesson 三原则之一）

9.3 警示三：三大开放争议还没定论

• 多 Agent（Subagents 分治）vs 单 Loop（Feature List 拆分）：多 Agent 隔离性更好但协调开销更大；单 Loop 简单可控但 context 膨胀压力全在一个 loop 里。

• Compaction（压缩旧 context）vs Reset（重置 context 重来）：compaction 保留历史但引入摘要噪声；reset 干净但丢失跨 session 推理链，强依赖 Progress Tracking 做外置记忆补救。

• CLI-first vs IDE-native：CLI-first 擅长长任务自主运行 + 脚本化编排；IDE-native 擅长行内交互式修改 + 视觉反馈。两种哲学尚未分出胜负。

十、总结

1. Agent = Model + Harness（Vivek Trivedy 原创；Böckeler @ martinfowler.com 传播）

2. 八大故障模式——①循环失控 ②context 溢出 ③cache miss ④tool 错误吞 ⑤状态丢失 ⑥缺权限闸 ⑦缺自动化评审 ⑧成本失控

3. 八大机制——Agent Loop / Tool Use / Progress Tracking / Context Management / Feature List / Verification Loop / Subagents / Generator-Evaluator

4. 三支柱正交视角——Context Engineering / Architectural Constraints / Garbage Collection

5. 四系家族树——CLI-first / IDE-native / Cloud-sandbox / SDK-harness

📌 信息源归属：

• Agent = Model + Harness 公式：Vivek Trivedy（2025-09-23 首篇 HaaS 博文）/ Birgitta Böckeler @ martinfowler.com（2026-04-02）

• Terminal Bench +13.7pp 实证数据：LangChain 博客 2026-02-17，Vivek Trivedy（原文链接）

• OpenAI 约 100 万行 / 零人工编码 / 1/10 时间：OpenAI 工程团队博文 2026-02-11

• 八大机制主要出处：Claude Agent SDK 博文（2025-09-29）+ Anthropic Effective Harnesses（2025-11-26）+ Anthropic Harness Design（2026-03-24）

• 术语首用节点：Vivek Trivedy（2025-09-23）

📌 术语：

术语	含义
pp	percentage point，百分点。例 "+13.7pp" 即"提升 13.7 个百分点"
Terminal Bench 2.0	Stanford 推出的终端任务基准，考核 Agent 在真实 shell 环境完成复杂任务的通过率
SWE-bench / SWE-bench Verified	Princeton 提出的 GitHub issue 修复基准；Verified 是经人工复核的高质量子集
prompt cache	LLM 按输入前缀命中的缓存机制，前缀不变可复用，前缀被改写则缓存全部作废
HaaS	Harness-as-a-Service，由 Vivek Trivedy 在 2025-09-23 首篇博文中创造
GAN	Generative Adversarial Network，生成对抗网络，核心思路是"生成者 vs 鉴别者"对抗提升质量
Bitter Lesson	Rich Sutton 2019 年 AI 经典论文——简单通用方法最终胜过复杂领域知识

📎 参考文章

• 大模型Agent智能体开发实战