Harness Engineering 14：从单次协作到完整 Harness 闭环
完整 Harness 的目标，不是让 Agent 一次性生成更多代码，而是让它在每一轮都能更接近可交付结果。
这需要一个闭环：任务进入系统，经过计划和边界确认，Agent 执行单一 feature，验证器独立检查，运行信号进入反馈，状态写回仓库，最后留下干净现场。下一轮从这个状态继续。
完整闭环的组件
| 组件 | 作用 |
|---|---|
| 任务入口 | 把需求转成可验证 feature |
| 计划器 | 拆范围、写排除项、定义通过标准 |
| 执行者 | 只做当前 active feature |
| 验证器 | 独立跑检查和评价表 |
| 观测层 | 收集日志、trace、截图、测试结果 |
| 状态层 | 写回功能清单、进度、决策 |
| 交接层 | 保证下轮可恢复 |
| 清洁门控 | 构建、测试、临时文件和启动路径都过关 |
这不是必须一次搭完的复杂系统，而是可以逐步叠加的工程骨架。
角色分离：先从逻辑分离开始
计划器、执行者、验证器可以是三个独立 Agent，也可以是同一个工具的三次不同调用。关键是不要让同一个上下文既写代码又轻易批准自己。
| 角色 | 输入 | 输出 |
|---|---|---|
| 计划器 | 需求、架构、当前状态 | feature、范围、验收条件 |
| 执行者 | active feature、规则、环境 | 代码变更、初步验证 |
| 验证器 | diff、运行环境、评价表 | 通过、修订、阻塞 |
对于小项目，可以人工扮演计划器，把 Agent 用作执行者和验证器。对于长任务，再逐步自动化。
一轮工作应该怎么跑
| 阶段 | 动作 | 产物 |
|---|---|---|
| Intake | 把需求写成 feature | feature 条目 |
| Startup | 运行初始化和基线 | 初始化记录 |
| Contract | 明确范围和排除项 | 任务契约 |
| Build | 实现单一 feature | diff |
| Verify | 跑验证命令和用户路径 | 证据 |
| Evaluate | 按 rubric 评分 | 接受或修订 |
| Handoff | 写回状态和下一步 | 交接文件 |
| Clean | 清理并确认启动路径 | 干净现场 |
只要任一阶段失败，就不要跳到“完成”。失败也是输出，必须写回状态。
反馈要分层
Agent 需要的反馈不是一句“再改改”。反馈要分层，越具体越能减少重试成本。
| 层级 | 示例 |
|---|---|
| 事实 | 上传后 API 返回 500 |
| 原因 | 缺少导入任务状态迁移 |
| 位置 | src/import/service 的完成回调 |
| 修复方向 | 写入 done 状态并触发 UI 刷新 |
| 验证 | 重新跑上传端到端用例 |
这类反馈会让下一轮直接朝根因走。
实操练习一：裸跑对比
可以用一个两小时练习检验 Harness 价值。
| 组别 | 条件 |
|---|---|
| A 组 | 只给自然语言任务 |
| B 组 | 给入口、功能清单、初始化脚本、验收条件 |
比较指标：
| 指标 | 观察什么 |
|---|---|
| 首次启动时间 | Agent 多久进入可运行状态 |
| 越界修改 | 是否改了无关文件 |
| 验证完整度 | 是否跑到用户路径 |
| 交接质量 | 新会话能否接上 |
| 返工次数 | 失败后是否有明确方向 |
如果 B 组明显更稳，就说明 Harness 正在发挥作用。
实操练习二：把 review 反馈升级成规则
选择最近三次人类 review 中重复出现的问题，把它升级成 Harness 能力。
| 重复问题 | 升级路径 |
|---|---|
| 忘记跑构建 | clean-state checklist 加构建门控 |
| UI 越过服务层 | 依赖检查脚本 |
| 没记录验证证据 | feature 状态更新规则 |
| 错误态没有 UI | 端到端失败路径 |
| 新会话不知道进度 | handoff 模板强制填写 |
这是 Harness 变强的主要方式：把人的一次判断，变成系统的长期能力。
成熟度路线
| 阶段 | 标志 |
|---|---|
| Level 1 | 有入口说明和启动脚本 |
| Level 2 | 有 feature 状态和验证证据 |
| Level 3 | 有端到端关键路径和评价表 |
| Level 4 | 有独立验证角色和观测信号 |
| Level 5 | 有周期清理、质量文档和规则升级机制 |
不要跳级。没有最小工作区时，直接上多 Agent 调度只会把混乱自动化。
最后一条原则
Harness Engineering 的核心不是让 Agent 更听话，而是让工作可恢复、可验证、可改进。
强模型会继续变强，但长期可靠性仍然取决于外部系统：任务是否清楚、环境是否可跑、状态是否可读、反馈是否具体、完成是否有证据、交接是否干净。
把这些做好，Agent 才从一次性生成器变成可协作的工程执行者。
参考材料
- Walking Labs：Learn Harness Engineering
https://walkinglabs.github.io/learn-harness-engineering/en/ - Walking Labs 教程源码
https://github.com/walkinglabs/learn-harness-engineering