来源：《Learn Harness Engineering》sanbuphy 著（共127页）| 整理时间：2026-05-11 核心结论：Agent 效果不好，不一定是模型的问题，很可能是你的 Harness 不够好。
一、核心概念：什么是 Harness Engineering？
关键公式
Agent = Model + Harness
Harness = 模型权重之外的一切工程基础设施，包括：
- 指令文件（AGENTS.md / CLAUDE.md）
- 工具访问权限
- 运行环境配置
- 状态持久化机制
- 验证与反馈回路
三次范式迁移
| 年份 | 范式 | 核心问题 |
|---|---|---|
| 2023 | Prompt Engineering | 如何跟模型说话 |
| 2024-25 | Context Engineering | 给模型看什么 |
| 2026 | Harness Engineering | 如何让 Agent 在真实世界持续可靠地工作 |
反直觉前提
同一个模型（Opus 4.5），同一段提示词（“做一个 2D 复古游戏编辑器”）：
- 裸跑：20分钟，花 $9，游戏核心功能跑不起来
- 配上完整 Harness（planner + generator + evaluator）：6小时，花 $200，游戏可以正常游玩
模型没变，变的是马鞍。
二、Harness 五子系统模型（“厨房比喻”）
| 子系统 | 类比 | 核心内容 |
|---|---|---|
| 指令子系统 | 菜谱架 | AGENTS.md：项目概览、技术栈、硬约束、文档链接 |
| 工具子系统 | 刀具架 | Agent 的工具访问权限（最小权限原则） |
| 环境子系统 | 灶台 | 依赖锁定、版本固定、环境可重现（Docker/devcontainer） |
| 状态子系统 | 备菜台 | PROGRESS.md：已完成/进行中/已知问题/下一步 |
| 反馈子系统 | 出菜检查口 | 显式验证命令：pytest、mypy --strict、ruff check |
投入产出比最高的是反馈子系统——先把验证命令写清楚。
量化案例：TypeScript + React 项目（4 阶段递进）
| 阶段 | 添加的组件 | 成功率 |
|---|---|---|
| 只有 README | 无 | 20% |
| + AGENTS.md | 指令子系统 | 60% |
| + 验证命令 | 反馈子系统 | 80% |
| + 进度文件 | 状态子系统 | 接近100% |
三、12 讲核心要点速查
L01 模型能力强 ≠ 执行可靠
- Agent 失败的五层归因框架：任务规范、上下文供给、执行环境、验证反馈、状态管理
- 遇到失败先检查 Harness，再换模型
- 一个 AGENTS.md 可能比换一个更贵的模型更有效
L02 Harness 到底是什么
- 仓库是唯一事实来源——Agent 看不到的信息等于不存在
- “给地图，不给说明书”：AGENTS.md 控制在 100 行，充当目录而非百科全书
- 用等模型对照实验量化各子系统的边际贡献
L03 让代码仓库成为唯一的事实来源
冷启动测试：开全新 Agent 会话，只看仓库内容，能否回答：
- 这是什么系统？
- 怎么组织的？
- 怎么运行？
- 怎么验证？
- 现在进度如何？
ACID 状态管理原则：
- 原子性：每次逻辑操作用一个 git commit 原子化
- 一致性：定义验证谓词，不一致的中间状态不 commit
- 隔离性：多 Agent 并发时用独立进度文件或 git 分支隔离
- 持久性：跨会话必须的知识写到文件里
L04 把指令拆分到不同文件里
“巨型指令文件"陷阱：AGENTS.md 膨胀 → 中间迷失效应（Lost in the Middle）→ 关键约束被忽略
拆分架构：
AGENTS.md（50-200行）
├── 项目概览（2句话）
├── 运行命令（make setup / make test）
├── 全局硬约束（不超过15条）
└── 专题文档链接
├── docs/api-patterns.md
├── docs/database-rules.md
└── docs/testing-standards.md
重构后：安全约束遵循率从 60% → 95%，任务成功率从 45% → 72%。
L05 让跨会话的任务保持上下文连续
核心问题：上下文窗口有限 → 长任务必然跨会话 → 信息丢失（“失忆的工匠"困境）
连续性四件套：
- PROGRESS.md：当前状态/已完成/进行中/已知问题/下一步
- DECISIONS.md：重要决策 + 原因 + 否决方案
- git checkpoint：每完成原子工作单元就提交
- 会话上下班流程（在 AGENTS.md 中定义）
量化效果：重建时间减少约 78%，功能完成率从 58% → 100%，隐含缺陷率从 43% → 8%。
Anthropic 发现：对于 Sonnet 4.5，“上下文焦虑"严重，需要上下文重置（新会话 + 进度文件）；对于 Opus 4.5，压缩策略基本够用。Harness 设计需要针对具体模型而非通用模板。
L06 让 Agent 每次工作前先初始化
关键原则：初始化和实现的优化目标不同，必须分离。
自举契约（Bootstrap Contract）：项目能被全新 Agent 无歧义操作的四个条件：
- 能启动（
make dev） - 能测试（
make test） - 能看进度（PROGRESS.md）
- 能接手下一步（任务分解文件）
独立初始化 vs 混合方式：总重建时间减少约 60%，“慢即是快”。
L07 给 Agent 划清每次任务的边界
核心问题：Agent 天生有"多做一点"的冲动 → Overreach（过度延伸） → Under-finish（不足完成）
WIP=1 原则（来自 Kanban 方法论）：
- 任何时刻只允许一个任务处于"进行中"状态
- 当前功能点端到端验证通过后，才能开始下一个
- 不要在实现功能 A 时"顺便"重构功能 B
量化结果：WIP=1 比无约束策略代码量少 33%，但功能完成率高 133%（87.5% vs 37.5%）。
少做但做完，永远优于多做但做半。
L08 用功能清单约束 Agent 该做什么
功能清单是 Harness 的脊梁骨，其他组件（调度器、验证器、交接器）都依赖它。
三元组结构：每个功能项 = (行为描述, 验证命令, 当前状态)
状态机：not_started → active → passing（通过验证命令执行后才能转移）
{
"id": "F03",
"behavior": "POST /cart/items returns 201",
"verification": "curl -X POST ... | jq .status == 201",
"state": "passing",
"evidence": "commit abc123"
}
结构化功能清单 vs 自由备忘录：功能完成率高 45%，零重复实现。
L09 防止 Agent 提前宣告完成
核心问题：AI 系统性地过度自信——代码写满了不代表做对了。
“提前交卷"的滑坡：只跑单元测试 → 跳过集成测试 → “看起来没问题” → 宣告完成
三层终止校验：
- 语法与静态分析（lint/类型检查）
- 运行时行为验证（测试执行、应用启动）
- 系统级确认（端到端测试、集成验证）
关键原则：把"干活的人"和"检查的人"分开——让独立 evaluator agent 做验收，不能让 generator 自评。
L10 跑通完整流程才算真正验证
单元测试的系统性盲区：
- 接口不匹配（各自 mock 各自通过，合起来就崩）
- 状态传播错误（ORM 缓存 + 数据库迁移冲突）
- 资源生命周期问题（文件句柄、连接泄漏）
- 环境依赖性（测试环境 mock vs 真实环境差异）
架构边界执行原则：
- 规则从"写在文档里"变成"跑在 CI 里”
- 错误消息要面向 Agent 设计，包含"怎么修"的具体步骤
L11 让 Agent 的运行过程可观测
双层可观测性：
- 运行时可观测性（系统层）：日志、追踪、进程事件、健康检查 → 回答"发生了什么”
- 过程可观测性（决策层）：冲刺合同、评分标准、验收条件 → 回答"为什么这样做”
冲刺合同（Sprint Contract）：编码开始前协商的短期协议——明确任务范围、验证标准、排除项。
Anthropic 三 Agent 架构实验数据：
| 角色 | 职责 |
|---|---|
| Planner | 接收需求→扩展完整产品规格（只做高层设计，不规定技术细节） |
| Generator | 按 sprint 逐功能实现，每个 sprint 前签冲刺合同 |
| Evaluator | 用 Playwright 像用户一样点击测试，按评分标准逐维度打分 |
有完整可观测性 vs 无可观测性：效率差 3 倍（15分钟 vs 45分钟完成同一任务）。
L12 每次会话结束前都做好交接
核心规律（Lehman 软件演化定律）：熵增是默认状态，不主动管理则复杂性必然增加。
会话退出检查清单：
- [ ] 构建通过（npm run build）
- [ ] 所有测试通过（npm test）
- [ ] 功能清单已更新
- [ ] 无调试代码残留（console.log, debugger, TODO）
- [ ] 标准启动路径可用
12周演化数据对比：
| 指标 | 无清洁策略（第12周） | 有清洁策略（第12周） |
|---|---|---|
| 构建通过率 | 68% | 97% |
| 测试通过率 | 61% | 95% |
| 新会话启动时间 | 60+ 分钟 | 9 分钟 |
质量文档（Quality Document）：对每个模块持续评分的活跃工件，让代码库健康可追踪。
定期简化 Harness：随着模型能力提升，移除不再必要的约束。Harness 的有趣组合不是变少了，而是在移动。
四、三大来源的核心洞察对比
| 来源 | 核心贡献 | 关键结论 |
|---|---|---|
| Anthropic | 两 Agent 架构实验（Initializer + Coding Agent） | “从人类工程师日常实践中寻找灵感” |
| OpenAI | 零手写代码实验（5个月，100万行，3名工程师） | “纪律越来越多地体现在脚手架而非代码中” |
| Thoughtworks | 控制论框架（必要变异度定律） | “没有 Harness 的 Agent 是不可控的” |
五、可立即行动的实践清单
今天就能做的（30分钟内）
- 建 AGENTS.md：项目概览、运行命令、核心约束、验证命令
- 写 PROGRESS.md：当前状态/已完成/进行中/阻塞/下一步
- 做冷启动测试：开全新 Agent 会话，看能否回答 5 个基本问题
本周内做的
- 拆分过胖的指令文件：AGENTS.md → 50-200行路由文件 + docs/子目录
- 加端到端测试：单元测试通过≠完成，必须有集成验证
- 建功能清单：用 JSON/Markdown 记录三元组（行为/验证命令/状态）
持续迭代
- 每次会话结束前：跑退出检查清单，更新进度文件
- 每次失败时：归因到五层防御中的某一层，修那一层
- 每月一次：移除不再必要的 Harness 组件
六、一句话精华
2025 年证明了 Agent 能工作，2026 年要解决的是如何让 Agent 可靠地工作。
模型是引擎，Harness 是底盘、方向盘和刹车。没有引擎的车跑不了，但没有刹车的车会杀人。
整理人：hongxinbo | 来源：《Learn Harness Engineering》sanbuphy 著