2026-03-25
0. 太长不读
2026 年 AI Agent 圈最火的一个词：Harness Engineering（驾驭工程）。核心发现：决定 Agent 表现的不是模型本身，而是包裹在模型外面的那套系统。
两个标志性实验：
- LangChain：模型固定，只改 Harness，Terminal Bench 2.0 得分从 52.8% → 66.5%，排名 Top 30 → Top 5
- OpenAI：3 个工程师 + Codex Agent，5 个月零行手写代码，合并 1500 个 PR，约 100 万行代码
本文从定义、组成、实践三个维度拆解 Harness Engineering，核心结论：
- Harness 不是一个新技术，而是把 System Prompt、Tools、Hooks、Memory、评测等散落实践整合成一个学科
- 模型是马，Harness 是缰绳——同一匹马配不同缰绳，表现天差地别
- 工程师的角色从"写代码"变成"设计 Agent 的工作环境"
1. Harness 是什么
一句话定义
Agent Harness 是包裹在语言模型外面的所有非模型代码：提示、工具、中间件、状态管理、反馈回路。模型提供智能，Harness 让智能变得可用。
类比
传统开发： 程序员 → 写代码 → 产出软件
Harness 时代：工程师 → 造环境 → Agent 在环境里跑 → 产出软件
就像带一个能力极强但没有背景知识的新员工入职——你不替他干活，而是准备好入职文档、编码规范、CI 流程和 Review 机制，让他自己高效产出。
和 Context Engineering 的关系
2025 年流行的词叫 Context Engineering（上下文工程），关注的是"怎么给模型提供好的输入"。Harness Engineering 是它的超集：
Context Engineering ⊂ Harness Engineering
Context Engineering:
系统提示 + 上下文管理 + 记忆
Harness Engineering:
系统提示 + 上下文管理 + 记忆
+ 工具编排 + 中间件 + 评测 + 反馈闭环 + 安全边界
Context Engineering 管"模型看到什么"，Harness Engineering 还管"模型能做什么、怎么验证、出错怎么办"。
2. Harness 由什么组成
六大组件
┌─────────────────────────────────────────────┐
│ Agent Harness │
│ │
│ ┌─────────────┐ ┌──────────────────────┐ │
│ │ System Prompt│ │ Tools / Skills / MCP │ │
│ │ 身份、约束、 │ │ Agent 能调用什么 │ │
│ │ 行为规范 │ │ │ │
│ └─────────────┘ └──────────────────────┘ │
│ │
│ ┌─────────────┐ ┌──────────────────────┐ │
│ │ Middleware │ │ Context Architecture │ │
│ │ / Hooks │ │ 分层上下文、 │ │
│ │ 确定性逻辑 │ │ 渐进加载、压缩策略 │ │
│ └─────────────┘ └──────────────────────┘ │
│ │
│ ┌─────────────┐ ┌──────────────────────┐ │
│ │ Persistent │ │ Verification Loop │ │
│ │ Memory │ │ 自我验证、评测、 │ │
│ │ 文件系统状态 │ │ 反馈闭环 │ │
│ └─────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────┘
│
┌──────┴──────┐
│ LLM 模型 │
│ （不动这里） │
└─────────────┘
各组件职责
| 组件 | 做什么 | 对应工具 |
|---|---|---|
| System Prompt | 定义 Agent 身份、行为约束、完成标准 | CLAUDE.md / AGENTS.md / SOUL.md |
| Tools | Agent 能调用的外部能力 | MCP Server、Skill 脚本 |
| Middleware / Hooks | 在模型调用前后插入确定性逻辑 | Claude Code Hooks、LangChain Middleware |
| Context Architecture | 管理上下文质量，防止 Context Rot | Skills 延迟加载、滑动窗口、Prompt Caching |
| Persistent Memory | 跨会话的状态持久化 | MEMORY.md、进度文件、git 历史 |
| Verification Loop | 验证 Agent 产出是否正确 | 单元测试、Lint、评测体系 |
关键认知：这些组件单独看都不新鲜，Harness Engineering 的贡献是把它们当成一个整体来设计。
3. LangChain 实验：只改 Harness，涨了 13.7 分
实验设置
- 模型：GPT-5.2-Codex，全程固定不动
- 基准：Terminal Bench 2.0，89 个任务（机器学习、调试、生物信息等）
- 只改三个变量：System Prompt、Tools、Middleware
Middleware 管道
LangChain 把 Harness 设计成可组合的中间件链：
Agent Request
│
├→ LocalContextMiddleware
│ 启动时扫描 cwd 及上下级目录
│ 定位 Python 安装路径等工具
│ 减少环境类报错
│
├→ LoopDetectionMiddleware
│ 检测 Agent 是否在重复相同动作
│ 触发时强制换策略
│
├→ ReasoningSandwichMiddleware
│ "推理三明治"：规划和验证阶段多分配算力
│ 中间执行阶段正常算力
│ 注意：xhigh 设置反而更差（53.9%），因为超时
│
├→ PreCompletionChecklistMiddleware
│ 提交前强制跑验证清单
│ 告诉 Agent "你的产出会被程序化测试"
│
▼
Agent Response
关键发现
| 改了什么 | 效果 |
|---|---|
| 加 LocalContextMiddleware | 环境报错大幅减少 |
| 加 LoopDetection | 消除死循环，任务完成率上升 |
| 推理三明治（high 档） | 63.6%（最优） |
| 推理三明治（xhigh 档） | 53.9%（超时反而更差） |
| 自我验证提示 | Agent 开始主动写测试验证自己 |
| 综合以上 | 52.8% → 66.5%，Top 30 → Top 5 |
最反直觉的结论：给更多算力不一定更好。推理预算分配比总量更重要——在规划和验证阶段花算力，在执行阶段省算力。
4. OpenAI 实验：零行手写代码，百万行产出
基本数据
- 团队规模：起步 3 人，后扩至 7 人
- 时间跨度：5 个月
- 产出：约 100 万行代码（应用逻辑、测试、CI、文档、内部工具）
- PR 数量：约 1500 个
- 人均日吞吐：3.5 个 PR
- 手写代码：零行，全部由 Codex Agent 生成
- 效率：传统方式的约 10 倍
四条核心原则
1. Agent 看不到的内容等于不存在
知识必须存在于代码库本身。AGENTS.md 约 100 行，作为索引指向设计文档、架构图、质量评分——全部版本化，在仓库里维护。
AGENTS.md（索引，约 100 行）
├→ docs/architecture.md
├→ docs/design-decisions/
├→ docs/quality-grades/
└→ docs/execution-plans/
2. 约束编码化，而非文档化
规则不写在 Wiki 里让人去看，而是编进 Linter、类型系统、CI 规则和结构测试。Agent 选择性遵守文档，但无法绕过编译器。
❌ 文档里写："请不要跨层调用"
✅ 结构测试：依赖方向必须是 Types → Config → Repo → Service → Runtime → UI
违反即 CI 失败
3. Agent 端到端自主完成
从问题复现 → 实现 → 测试 → 开 PR，全链路不需人介入。人只在最后做 Review（大多数 PR 一分钟内可审完）。
4. 最小化合并阻力
测试偶发失败用重跑处理，不阻塞进度。定期有后台 Codex 任务扫描偏差、更新质量评分、开重构 PR——像垃圾回收一样自动清理。
AGENTS.md 是动态反馈循环
不是写一次就丢那的静态文档：
Agent 开始 session → 读 AGENTS.md
│
Agent 执行任务 → 遇到失败
│
Agent 更新 AGENTS.md ← 把失败原因和解法写回去
│
下一个 Agent session → 读到更新后的 AGENTS.md → 不再重复犯错
还有一套"黄金原则"被编码进仓库：
- 优先用共享 utility 包，不要手写 helper（集中维护不变量）
- 不准 YOLO 式探测数据——必须用类型化 SDK，不能靠猜
- 定期清理任务：扫描偏差、打质量分、自动开重构 PR
5. 从 Harness 视角重新理解 Claude Code
Claude Code 本身就是一个 Harness。把它的能力映射到 Harness 的六大组件：
| Harness 组件 | Claude Code 对应 | 作用 |
|---|---|---|
| System Prompt | CLAUDE.md | 项目约定、行为规范 |
| Tools | MCP Server + 内置工具（Bash、Read、Edit...） | Agent 能做什么 |
| Middleware / Hooks | Hooks（PreToolUse / PostToolUse） | 工具调用前后插入逻辑 |
| Context Architecture | Skills 延迟加载 + Prompt Caching | 上下文质量管理 |
| Persistent Memory | MEMORY.md + 进度文件 | 跨会话状态 |
| Verification Loop | 测试运行 + Lint + 子 Agent 验证 | 产出验证 |
你已经在做 Harness Engineering 了
如果你做过以下任何一件事，你就已经在做 Harness Engineering：
- 写了 CLAUDE.md 定义项目规范 → System Prompt
- 接了 Notion MCP Server → Tools
- 配了 Hook 在提交前跑 lint → Middleware
- 写了 Skill 定义代码审查流程 → Context + Verification
- 用了 MEMORY.md 记录跨会话信息 → Persistent Memory
Harness Engineering 不是让你学新东西，而是让你意识到这些散落的实践应该当成一个整体来设计。
6. 怎么落地
四象限定位
OpenAI 提出的任务分类框架——先搞清楚你的任务在哪个象限：
验证可自动化
│
┌─────────────┼─────────────┐
│ │ │
│ 需人审查 │ 最适合Agent │
│ 吞吐量受限 │ ← 目标区域 │
目标 │ │ │
清晰 ────┤─────────────┼─────────────┤
│ │ │
│ Agent无用 │ 高效地跑偏 │
│ │ │
└─────────────┼─────────────┘
│
验证靠人工
Harness 的核心工作就是把任务推向右上角——让目标更明确（System Prompt），让验证更自动化（Verification Loop）。
落地顺序
第一步：写 CLAUDE.md / AGENTS.md
↓ 定义 Agent 能看到什么
第二步：编码化约束
↓ 规则进 Linter / CI / 类型系统，不靠 Agent 自觉
第三步：接工具
↓ MCP 接外部系统，Skills 定义使用流程
第四步：加 Middleware
↓ Hook 在关键节点插入确定性逻辑
第五步：建评测
↓ 每个真实失败转成测试用例
第六步：闭环
↓ Agent 失败 → 更新文档 → 下次不再犯
一个最小可用 Harness
如果只能做三件事：
- 写一份好的 CLAUDE.md：项目结构、命名规范、禁止事项、常用命令。Agent 看不到的等于不存在。
- 把验收标准变成可执行的：不是"代码要干净"，而是
npm run lint && npm test通过。 - 记录失败并更新：每次 Agent 犯错，把原因和解法写回 CLAUDE.md。这就是最小版的反馈闭环。
这三件事做到位，你的 Agent 表现会有明显提升——不需要换更贵的模型。
7. 常见误区
| 误区 | 事实 |
|---|---|
| "换更好的模型就行" | LangChain 实验证明：同一模型，只改 Harness，涨 13.7 分 |
| "Harness 就是写好 Prompt" | Prompt 只是六大组件之一，还有工具、中间件、评测、记忆 |
| "多给算力就能解决" | xhigh 推理档位反而更差，算力分配比总量更关键 |
| "AGENTS.md 写一次就行" | 它是动态反馈循环，Agent 失败时要更新，不是静态文档 |
| "把规则写清楚 Agent 就会遵守" | 文档化的规则会被忽略，必须编码进 CI / Linter / 类型系统 |
| "Harness 是个新技术要从头学" | 你已经在做了——CLAUDE.md、MCP、Hooks、Skills 都是 Harness 的一部分 |
8. 工程师角色的变化
这可能是 Harness Engineering 最深远的影响。
之前
工程师的一天：
读需求 → 设计方案 → 写代码 → 写测试 → 提 PR → 等 Review → 合并
现在
工程师的一天：
分解目标 → 写清楚验收标准 → 配好 Agent 环境 → 启动 Agent
→ 审查 PR（大多数一分钟搞定）→ 遇到失败更新 AGENTS.md → 循环
核心转变：从"我来写"变成"我来定义什么算对，让 Agent 去写" 。
OpenAI 给出的数据：3 个工程师，人均每天审查合并 3.5 个 PR。这意味着工程师的瓶颈不再是写代码的速度，而是：
- 能不能把目标描述清楚
- 能不能把验收标准自动化
- 能不能设计好反馈闭环
这三项，恰好就是 Harness Engineering 的核心。
9. 划重点
- Harness Engineering 是 2026 年 Agent 领域最重要的工程范式：模型不动，只改 Harness，性能就能大幅提升。
- Harness 由六大组件构成：System Prompt、Tools、Middleware、Context Architecture、Persistent Memory、Verification Loop。单独看都不新鲜，整体设计才是关键。
- LangChain 用中间件管道（环境扫描 → 循环检测 → 推理分配 → 提交验证）把得分从 52.8% 拉到 66.5%。最反直觉的发现：推理预算分配比总量更重要。
- OpenAI 用 AGENTS.md 作为动态反馈循环 + 约束编码化 + 端到端自主 + 后台清理任务，3 人团队 5 个月产出百万行代码。
- 核心工作是把任务推向"目标明确 + 验证自动化"的象限。做不到这一点，换什么模型都没用。
- 落地可以从三件事开始：写好 CLAUDE.md、把验收标准变成可执行的、每次失败更新文档。
- 工程师角色从"写代码"变成"设计 Agent 的工作环境"——定义什么算对、怎么验证、出错怎么更新。
参考资料
- OpenAI, Harness engineering: leveraging Codex in an agent-first world
- LangChain, Improving Deep Agents with harness engineering
- LangChain, The Anatomy of an Agent Harness
- Martin Fowler, Harness Engineering
- OpenAI, Unlocking the Codex harness
- InfoQ, OpenAI Introduces Harness Engineering
- NxCode, Harness Engineering Complete Guide
- Tw93, 你不知道的 Agent：原理、架构与工程实践
