🔧
一、什么是 Harness Engineering？
"Harness Engineering" — Mitchell Hashimoto（Ghostty 作者）的原始定义：
"It is the idea that anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again."
中文：每次发现 Agent 犯了一个错误，你就花时间工程化一个解决方案，让它永远不再犯这个错。
"It is the idea that anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again."
中文：每次发现 Agent 犯了一个错误，你就花时间工程化一个解决方案，让它永远不再犯这个错。
词源：为什么叫 "Harness"？
Harness（马具/挽具）的字面含义是套在马身上、让人能够控制和引导马匹的那套装置。
就像驯马不是限制马的能力，而是让马的能量能被有效引导——Harness Engineering 不是限制 Agent，而是通过积累约束让 Agent 更可靠。
核心思路：把每一次"事故"转化为"永久规则"。不是在每次出问题后手动修复，而是建立一个系统，让错误变成无法再发生的约束。这是一种持续改进的工程哲学，类似于软件工程中每发现一个 bug 就写一个测试用例，防止回归。
📅
二、概念的起源与传播
这个词由 Mitchell Hashimoto（Ghostty 终端作者、前 HashiCorp 联合创始人）在 2026 年 2 月 5 日正式命名，随后业界头部机构相继跟进，短短 2 个月就成为 AI 工程圈的热词。
2026.02.05
Mitchell Hashimoto 命名
在博客《My AI Adoption Journey》中正式提出"harness engineering"这个词。
描述了他 6 个阶段的 AI 采用历程，第 5 步就是 Engineer the Harness。
首次命名
描述了他 6 个阶段的 AI 采用历程，第 5 步就是 Engineer the Harness。
首次命名
2026.02.11
OpenAI 官方博客跟进
《Harness engineering: leveraging Codex in an agent-first world》
以百万行级别真实代码库为案例，讲述如何用 Codex 做 harness engineering。
提到团队曾每周 20% 时间在清理"AI slop"，通过 harness 彻底解决。
OpenAI 背书
以百万行级别真实代码库为案例，讲述如何用 Codex 做 harness engineering。
提到团队曾每周 20% 时间在清理"AI slop"，通过 harness 彻底解决。
OpenAI 背书
2026.03.24
Anthropic 发布 Harness Design 深度文章
《Harness design for long-running application development》
系统性讲解 Planner + Generator + Evaluator 三 Agent 架构。
披露了 6 小时/$200 构建完整游戏 vs 20 分钟/$9 单 Agent 失败的对比数据。
Anthropic 实践
系统性讲解 Planner + Generator + Evaluator 三 Agent 架构。
披露了 6 小时/$200 构建完整游戏 vs 20 分钟/$9 单 Agent 失败的对比数据。
Anthropic 实践
2026.04.02
Martin Fowler 总结归纳
《Harness engineering for coding agent users》
架构圣经作者将其归纳进"Context Engineering + Harness Engineering"的完整心智模型。
学术背书
架构圣经作者将其归纳进"Context Engineering + Harness Engineering"的完整心智模型。
学术背书
为什么 2026 年初突然火了？
Claude Code、Cursor 等 IDE Agent、OpenAI Codex 在 2025 下半年大规模普及后，开发者开始遭遇一个共同的痛点：Agent 总是在同一个地方犯同样的错误，而每次都要人工干预修复。Harness Engineering 正是对这个痛点的系统性回答。
Claude Code、Cursor 等 IDE Agent、OpenAI Codex 在 2025 下半年大规模普及后，开发者开始遭遇一个共同的痛点：Agent 总是在同一个地方犯同样的错误，而每次都要人工干预修复。Harness Engineering 正是对这个痛点的系统性回答。
📝
三、两种实践形式
Mitchell Hashimoto 在原文中明确定义了 Harness Engineering 的两种具体形式，从简到复：
形式一详解：AGENTS.md 的积累
AGENTS.md（或 CLAUDE.md、CURSOR_RULES 等）是告诉 Agent "在这个项目里你应该怎么行动"的配置文件。Harness Engineering 把它变成一个活的错误日志：
❌ 普通做法（没有 Harness）
- Agent 跑了
xcodebuild，失败 - 你手动纠正，告诉它用
swift build - 下一个 session，Agent 又跑
xcodebuild - 你再次纠正……无限循环
✅ Harness 做法
- Agent 跑了
xcodebuild，失败 - 你在
AGENTS.md加一行：- Use swift build, not xcodebuild - 之后所有 session 永久生效
- 这个错误从此消失
📌 Ghostty 项目真实 AGENTS.md 示例（Mitchell Hashimoto 公开的）
# Ghostty Inspector AGENTS.md # 下面每一行都来自一次真实的 Agent 犯错 - Never run `git push` without explicit user approval - Use `swift build` not `xcodebuild` for command line builds - Screenshot tool is available at ./scripts/screenshot.sh - When adding a new feature, always check if Inspector.swift needs updating - The build directory is .build/, not build/ - Tests are run with `swift test`, not `make test`
→ 这个文件就像一个「事故报告数据库」，每一行都是一次血泪教训的结晶。
形式二详解：专用验证工具
某些错误用文字描述无法彻底解决，比如 Agent 生成了 UI 但不知道自己的 UI 长什么样。这时候就需要给 Agent 一个"感官"：
| 常见问题 | 工程化解决方案（工具） | 原理 |
|---|---|---|
| Agent 不知道自己写的 UI 是否正常 | 提供截图工具 take_screenshot(url) |
让 Agent 能"看见"自己的输出 |
| Agent 跑全套测试太慢，跳过验证 | 提供过滤测试工具 run_tests_filtered(pattern) |
低成本让 Agent 随时自验证 |
| Agent 改了 API 但不知道是否 Breaking | 提供 API 验证脚本 | 每次修改后自动检查兼容性 |
| Agent 构建命令总是出错 | 提供包装好的 build.sh 脚本 |
统一入口，屏蔽工具差异 |
| Agent 无法验证数据库状态 | 提供 DB 快照对比工具 | 让 Agent 能自我检查数据正确性 |
🔑 关键洞察（来自 Mitchell 原文）：
"If you give an agent a way to verify its work, it more often than not fixes its own mistakes and prevents regressions."
给 Agent 验证自己工作的方式，它往往能自己修复错误并防止回归。
工具不仅是约束，更是 Agent 的"感官"和"自检能力"。
"If you give an agent a way to verify its work, it more often than not fixes its own mistakes and prevents regressions."
给 Agent 验证自己工作的方式，它往往能自己修复错误并防止回归。
工具不仅是约束，更是 Agent 的"感官"和"自检能力"。
🐛
四、为什么 Agent 总是犯错？根本原因分析
Anthropic 在多次长时间 Agent 测试中，总结出了两大类结构性失效模式：
失效模式一：上下文窗口问题（Context Drift）
Context Anxiety（上下文焦虑）：某些模型在上下文接近它认为的上限时，会开始"草草收尾"——即使任务还没完成，也会输出"我已经完成了"。
解决方案是 Context Reset（上下文重置）：完全清空上下文，通过结构化的"交接文档"让新 Agent 接续工作。不是压缩旧内容，而是给 Agent 一块全新的黑板。
解决方案是 Context Reset（上下文重置）：完全清空上下文，通过结构化的"交接文档"让新 Agent 接续工作。不是压缩旧内容，而是给 Agent 一块全新的黑板。
失效模式二：自我评估偏差（Self-Evaluation Bias）
❌ Agent 自我评估的实际表现
- Agent 写出了明显有问题的 UI
- 让它评估自己的工作
- 它充满信心地给出好评
- "这个设计非常好，色彩和谐……"
- 但人眼一看：又丑又平庸的 AI 模板风
✅ 根本原因
- 被训练成 "helpful and harmless"
- 倾向于给 LLM 生成内容打高分
- 自评时没有外部参照标准
- → 同一个 Agent 无法既当运动员又当裁判
Anthropic 原文洞察：
"Separating the agent doing the work from the agent judging it proves to be a strong lever."
把做工作的 Agent 和评判工作的 Agent 分开，是解决这个问题的有力杠杆。单独训练一个挑剔的 Evaluator，比让 Generator 批评自己的工作容易得多。
"Separating the agent doing the work from the agent judging it proves to be a strong lever."
把做工作的 Agent 和评判工作的 Agent 分开，是解决这个问题的有力杠杆。单独训练一个挑剔的 Evaluator，比让 Generator 批评自己的工作容易得多。
🪞
五、设计可靠 Evaluator：把主观标准变客观
Anthropic 工程师首先在前端设计领域实验 Evaluator，把"这好不好看"拆解成 4 个可打分的维度：
① 设计质量（Design Quality）
整体感：色彩、排版、布局是否统一，创造出独特氛围和个性。
② 原创性（Originality）
是否有自定义决策？还是清一色库默认值 / AI 生成模板风（白卡片+紫渐变）？
③ 工艺（Craft）
字体层级、间距一致性、色彩对比度——技术执行质量的基准检查。
④ 功能性（Functionality）
用户能否理解界面？找到主要操作？无需猜测完成任务？
Evaluator 调优过程
初始：直接评估 → 全是好评
观察到 Evaluator 发现了真实问题，然后自我说服说没关系，最终批准劣质输出。
调优 1：加入 Few-shot 示例 + 详细打分依据
用少量真实案例校准 Evaluator 口味，确保评分标准对齐，减少分数漂移。
调优 2：给 Evaluator 配备 Playwright MCP
让 Evaluator 能真实点击运行中的页面，截图后仔细研究，而不只是看静态代码。
调优 3：加入锚定语言
在 prompt 加入 "the best designs are museum quality" 后，Generator 输出向更高质量收敛。
最终效果：5~15 次迭代后显著提升
荷兰艺术博物馆网站案例：第 9 次还是普通深色主题，第 10 次突然用 CSS 3D 透视做出了空间画廊体验——这种创意飞跃在单次生成中从未见过。
🏗️
六、三 Agent Harness 架构（Anthropic 实战方案）
将 Generator-Evaluator 模式推广到全栈代码生成，最终形成三 Agent 架构：
三个 Agent 职责速查表
| Agent | 输入 | 输出 | 核心原则 |
|---|---|---|---|
| 🗂️ Planner | 1-4 句用户描述 | 完整产品 spec（16 特性、10 Sprint、设计语言） | 只关注"做什么"，不干涉技术细节 |
| ⚙️ Generator | Spec + Sprint 合同 | 每个 Sprint 的完整代码实现 | Sprint 结束前先自评，再交 QA |
| 🔍 Evaluator | 运行中的 App | PASS/FAIL + 精确到行号的 bug 描述 | 任一维度低于阈值 → Sprint FAIL |
通信机制：所有 Agent 间通过文件交接，而不是直接调用。
文件方式的优势：跨上下文窗口持久化、调试友好有完整日志、Agent 解耦只需关心读写格式。
文件方式的优势：跨上下文窗口持久化、调试友好有完整日志、Agent 解耦只需关心读写格式。
📋
七、Sprint 合同机制：先"签合同"再写代码
在每个 Sprint 开始前，Generator 和 Evaluator 先协商并锁定验收标准，再动手写代码：
📌 真实 Sprint 3 合同（关卡编辑器）中，Evaluator 发现的 FAIL 示例
| 合同条款 | Evaluator 的精确 bug 描述 |
|---|---|
| 矩形填充工具支持拖拽填充区域 | FAIL fillRectangle 函数存在但 mouseUp 时未触发 |
| 用户可删除已放置的实体生成点 | FAIL Delete 键同时要求 selection 和 selectedEntityId，但点击只设置 selectedEntityId |
| 通过 API 重排动画帧 | FAIL PUT /frames/reorder 定义在 /{frame_id} 后，FastAPI 把 'reorder' 当整数 frame_id 解析，返回 422 |
→ Evaluator 反馈精确到具体文件和 bug 原因，Generator 收到后无需额外排查即可修复。
📊
八、效果数据：三 Agent vs 单 Agent
实验一：复古游戏制作器（相同 prompt）
| 方式 | 耗时 | 费用 | 游戏能玩吗？ | 功能完整度 |
|---|---|---|---|---|
| 单 Agent | 20 分钟 | $9 | ❌ 游戏核心功能损坏（输入无响应） | 基础 UI + 大量 stub |
| 三 Agent Harness | 6 小时 | $200 | ✅ 完全可玩，可控制角色移动 | 16 特性 + AI 集成 + 音效 + 分享 |
实验二：浏览器 DAW（数字音频工作站）
| 阶段 | 耗时 | 费用 |
|---|---|---|
| Planner | 4.7 分钟 | $0.46 |
| Build Round 1 | 2 小时 7 分 | $71.08 |
| QA Round 1 | 8.8 分钟 | $3.24 |
| Build Round 2 | 1 小时 2 分 | $36.89 |
| QA Round 2 | 6.8 分钟 | $3.09 |
| Build Round 3 | 10.9 分钟 | $5.88 |
| QA Round 3 | 9.6 分钟 | $4.06 |
| 总计 | 3 小时 50 分 | $124.70 |
最终效果：完整浏览器 DAW，含编曲视图、混音台、传输控制，并内置 AI Agent——可通过自然语言提示 Agent 自动设置节拍、铺写旋律、构建鼓点、调整混响。整首歌完全通过提示词生成。
🌐
九、与 Context Engineering 的关系（Martin Fowler 模型）
Martin Fowler（架构圣经作者）在 2026 年 4 月 2 日将这两个概念系统化为完整心智模型：
| 维度 | Context Engineering | Harness Engineering |
|---|---|---|
| 解决的问题 | Agent 不了解环境和任务 | Agent 反复犯同一类错误 |
| 核心文件 | README、System Prompt、工具描述 | AGENTS.md、验证脚本 |
| 构建方式 | 项目启动时一次性设计 | 每次 Agent 犯错后迭代积累 |
| 作用时机 | Session 开始时加载 | Agent 执行过程中持续约束 |
| 类比 | 入职培训手册 | 事故报告 + 流程改进规定 |
结合使用效果 = 让 Agent 真正可靠
Context Engineering 告诉 Agent"你是谁、你在哪、你有什么"；Harness Engineering 告诉 Agent"你以前犯过这些错，永远别再犯"。两者缺一不可。
Context Engineering 告诉 Agent"你是谁、你在哪、你有什么"；Harness Engineering 告诉 Agent"你以前犯过这些错，永远别再犯"。两者缺一不可。
🔄
十、随模型能力迭代的 Harness 演进
一个关键洞察：Harness 不是一成不变的，要随着底层模型能力的提升而简化。
"Resist over-engineering early. A simpler harness that works for now is better than a complex one designed for hypothetical future capabilities."
抵制过度工程化。一个现在能用的简单 Harness，比为假设的未来能力设计的复杂 Harness 更好。
抵制过度工程化。一个现在能用的简单 Harness，比为假设的未来能力设计的复杂 Harness 更好。
Anthropic 的实际经验：使用 Opus 4.6 版本后，Sprint 结构变得不再必要，直接改为单次最终 QA 检查就够了。
| 模型能力 | Harness 复杂度 | 实际变化 |
|---|---|---|
| 早期模型（Sonnet 4.5 等） | 复杂 | 需要 Sprint 结构 + 每步合同 + 多次迭代 |
| 升级版模型（Opus 4.6 等） | 简化 | 可移除 Sprint 机制，改为单次最终 Evaluator 检查 |
| 未来更强模型 | 最简 | 可能只需要 AGENTS.md，不再需要独立 Evaluator |
判断 Evaluator 是否还必要的标准：
"The value of an evaluator scales with the difficulty of the task relative to the model's capability."
任务难度超出模型独立能力的部分越大，Evaluator 价值越高。随着模型越来越强，很多过去需要 Evaluator 的场景会逐渐变成模型自己就能搞定。
"The value of an evaluator scales with the difficulty of the task relative to the model's capability."
任务难度超出模型独立能力的部分越大，Evaluator 价值越高。随着模型越来越强，很多过去需要 Evaluator 的场景会逐渐变成模型自己就能搞定。
🎯
十一、总结与实践建议
Harness Engineering 核心原则速查
| 原则 | 具体做法 |
|---|---|
| 每错必录 | 每次 Agent 犯错，立刻在 AGENTS.md 加一行规则 |
| 先简后繁 | 从 AGENTS.md 文字规则开始，确实不够用再写验证工具 |
| 给 Agent 眼睛 | 给它截图工具、测试工具，让它能自我验证 |
| 分离职责 | 复杂任务中，Generator 和 Evaluator 必须是独立 Agent |
| 先签合同 | 每个 Sprint 开始前，先锁定验收标准，再动手写代码 |
| 随模型简化 | 底层模型能力增强后，主动评估哪些 Harness 可以去掉 |
实践路径建议
第一步：建立 AGENTS.md，开始录错
新建
AGENTS.md，每次 Agent 犯了同一个错误，就加一条规则。这是成本最低、收益最稳定的开始。第二步：识别哪些错误需要工具解决
如果某类错误用文字描述不够（比如 UI 问题），就开始写对应的验证脚本：截图工具、测试过滤工具等。
第三步：长任务引入独立 Evaluator
当任务超过单个上下文窗口、或者 Generator 开始给自己打高分时，引入独立 Evaluator Agent。
第四步：随模型升级调整复杂度
每次换用更强的底层模型，重新评估 Harness 的复杂度，移除已经不再必要的约束。
一句话定义（最后再记一遍）
Harness Engineering = 每次发现 Agent 犯错，就工程化一个解决方案，让它永远不再犯这个错。
— Mitchell Hashimoto, 2026.02.05
— Mitchell Hashimoto, 2026.02.05