Agent Harness Engineering (O'Reilly / Addy Osmani)
来源：https://www.oreilly.com/radar/agent-harness-engineering/ 原文：https://addyosmani.com/blog/agent-harness-engineering/ 作者：Addy Osmani 收录时间：2026-05-18
核心论点
一个体面的模型 + 优秀的 harness > 一个优秀的模型 + 糟糕的 harness。
过去两年我们在争论哪个模型最好，但模型只是 Agent 的一个输入。其余全是 harness：prompts、tools、context policies、hooks、sandbox、subagents、feedback loops、recovery paths。
Agent = Model + Harness. 如果你不是模型，你就是 harness。
"Skill Issue" 重构
模式： Agent 做蠢事 → 工程师怪模型 → "等下一个版本吧"
Harness 思维： 失败是可追溯的。Agent 不知道某个约定 → 加到 AGENTS.md。Agent 运行了破坏性命令 → 加 hook 阻止。Agent 在 40 步任务中迷路 → 拆成 planner + executor。Agent 不断"完成"坏代码 → 把 typecheck 背压信号接入循环。
HumanLayer: "这不是模型问题，是配置问题。"
关键数据： Terminal Bench 2.0 上，Claude Opus 4.6 在 Claude Code 内得分远低于同一模型在自定义 harness 中的得分。Viv 的团队仅通过改变 harness 就从 Top 30 跳到 Top 5。
棘轮原则：每个错误变成规则
每当 Agent 犯错，你就花时间设计一个方案，让这个错误永远不会再次发生。
不是一笑了之，不是重试。是信号。
- Agent 提交了注释掉的测试 → AGENTS.md 加"永远不要注释测试"
- precommit hook 加
grep检查.skip(和xit( - reviewer subagent 把注释测试标记为 blocker
每条规则都应能追溯到具体的失败。 你无法下载一个 harness——它是你的失败历史塑造的。
Harness 组件（从行为反推设计）
1. 文件系统 & Git — 持久状态
最基础的原语。模型只能直接操作上下文内的内容。文件系统让 Agent 有：
- 工作空间读写数据/代码/文档
- 卸载中间工作（而非全放在上下文里）
- 多 Agent 和人类通过共享文件协调
Git 加上版本控制：跟踪进度、回滚错误、分支实验。
2. Bash & 代码执行 — 通用工具
今天的主循环是 ReAct 循环：推理 → 工具调用 → 观察结果 → 重复。
可以预建每个可能的工具，或者给 Agent bash 让它按需构建。给 Agent bash 就像给一个人一个厨房，而不是教他用一个厨房小工具。
3. Sandbox & 默认工具
Bash 必须在安全的地方运行。Sandbox 提供：
- 隔离的执行环境
- 命令白名单、网络隔离
- 按需创建/销毁
- 预装语言运行时、Git、测试 CLI、无头浏览器
4. 记忆 & 搜索 — 持续学习
模型只有权重 + 当前上下文。注入知识的唯一方式是上下文注入。
- AGENTS.md 每次 start 注入 → Agent 编辑 → 下次 session 继承 → 粗糙但有效的持续学习
- Web 搜索 & MCP 工具桥接训练截止后的新知识
5. 对抗上下文腐烂
上下文填满 → 模型推理能力下降。三种技术：
| 技术 | 说明 | |------|------| | Compaction | 窗口快满时智能总结旧上下文 | | Tool-call offloading | 大工具输出只保留头尾，完整版存文件 | | Progressive disclosure | Skills 按需揭示，不一次全加载 |
Anthropic 补充：长时间任务需要 full context reset（从紧凑 handoff 文件重建 session），compaction 不够。
6. 长期执行：Ralph 循环、规划、验证
Ralph 循环： Hook 拦截 Agent 退出 → 将原始 prompt 注入新的上下文窗口 → 强制继续。每次迭代从文件系统读取上一个状态。简单技巧，把单 session Agent 变成多 session Agent。
规划： 模型将目标分解为步骤 → 写入 plan 文件。每步后自验证。
Planner/Generator/Evaluator 分离： 分离生成和评估优于自评。Agent 自评时可靠地偏向正面。Sprint Contract（事前协商"完成"定义）比事后检查更能捕获范围漂移。
7. Hooks — 执行层
"我告诉 Agent 做 X" vs "系统强制 X"
Hook 在特定生命周期点运行（tool call 前、文件编辑后、commit 前、session 开始时）。
原则：成功静默，失败详细。 Typecheck 通过 → 无输出。失败 → 错误文本注入循环 → Agent 自纠正。
8. AGENTS.md & 工具选择
AGENTS.md 仍是最高杠杆的配置点，因为每轮都在 system prompt 中。
两条硬经验：
- 保持简短 — HumanLayer 控制在 60 行以内。每行都在争夺注意力，更多规则让每条规则更重要性降低。飞行员检查清单，不是风格指南。
- 挣得每行 — 规则应追溯到具体失败或硬约束。否则是噪音。棘轮，不是头脑风暴。
工具同理： 10 个聚焦工具 > 50 个重叠工具。模型需要在脑中保持菜单。工具描述是可信文本——恶意 MCP 可以在你输入之前就 prompt-inject 你的 Agent。
关键洞察
Harness 不缩小，它移动
更好的模型不会让 harness 过时。任务天花板提高了，新的失败模式出现：
- 上下文焦虑消失了 → 需要多天记忆策略
- 模型能做更多 → 需要协调 3 个专门 Agent 的 harness
- 生成的 UI → 需要设计质量评估器
"Harness 中的每个组件都编码了一个关于模型不能自己做什么的假设。" — Anthropic
当模型在某方面变好，对应组件变无用代码应移除。当模型解锁新能力，新脚手架需要跟上。
模型-Harness 训练循环
今天的 Agent 产品在 posttraining 时 harness 在循环中。模型特别擅长 harness 设计者认为它应该擅长的动作。这就是为什么 Opus 4.6 在 Claude Code 内和别人的 harness 内感觉不同。
两个实践启示：
- Harness 是活系统，不是一次性配置
- "最佳" harness 不一定是模型训练时的那个，而是为你的任务设计的
Harness as a Service (HaaS)
从 LLM API（给你 completion）到 Harness API（给你 runtime）：
- Claude Agent SDK / Codex SDK / OpenAI Agents SDK
- 自带：循环、工具、上下文管理、hooks、sandbox 原语
- 你只需自定义