harness-engineering

name	harness-engineering
description	当你在搭建模型外围的运行与治理层（约束、验证、纠正、故障恢复、回退）时使用；当 Agent"能做事"但"不可靠做事"——频繁幻觉、选错工具、越权、无法自恢复、过早声称完成时使用。不适用于单个工具的描述设计（见 tool-design），也不适用于提示词措辞（见 prompt-engineering）。

Harness 工程（Harness Engineering）

子 Skill 索引（渐进式披露：目录常驻，正文按需加载）

子 Skill	目录	何时深入加载
约束/验证/纠正	harness-constrain-verify	实现三层保障机制、防 reward hacking
编排模式	harness-orchestration	选工作流 vs 自主 Agent、选模型、选框架

角色与读者

面向生产级 Agent 系统的开发者。本 Skill 服务的目标：把"能跑的 Demo"变成"可靠的产品"。核心公式：Agent = Model + Harness，其中 Harness = 上下文管理 + 工具接口 + 约束 + 验证 + 纠正。生产级系统中 Harness 绝大部分代码都在实现约束/验证/纠正，而非上下文与工具本身。

核心原则（配正例/反例）

1. 约束优先于指导：能用代码强制的就不要用文档建议

   • Linter 规则、类型约束、CI 检查是"做不了"；提示词"请遵循…"只是"建议别做"。
   • 正例：把业务规则编码进校验器/Linter/CI；把"付款前不能预订"由代码强制执行。

2. 验证要自动化，反馈越快、越结构化越好

   • 人工审查是不可扩展的瓶颈。测试套件、代码质量检查、行为监控的投入回报率远高于加人力。
   • 正例：write_file 后立即跑 linter，结构化错误列表作为工具返回值；错误信息越接近错误发生时刻，纠正效率越高。
   • 验证只看结构化数据（JSON 字段），不看模型自由文本（可能已被提示注入操纵）。

3. 约束的是动作而非结果（防过程性错误 / reward hacking）

   • 结果正确 ≠ 过程正确：删库重建"修复"了故障但数据没了；删失败测试"通过"了测试但没解决问题。
   • 正例：对 rm -rf、删除生产数据、覆盖未读文件设专门检查与审批（语义解析 + Sidecar 复核）。

4. 回退要可靠，安全网内才敢试错

   • Git 分支、沙盒环境、快照机制确保任何错误可逆。
   • 正例：代码修改走 worktree/PR，出错可回滚。

5. 故障边界控制：故障只在同一批并行调用内传播，不上升到父级

   • 正例：同时读三个文件，一个找不到只报告这一个失败，不取消另外两个、不中止整个任务。
   • 反例：一个命令失败导致整个任务中止的脆弱模式。

执行流程（SOP 检查清单）

1. 盘点五要素：上下文管理、工具接口、约束、验证、纠正，逐项检查是否齐备。
2. 建立验收基线（测试套件/CI/审查标准）、执行边界（模块边界/依赖规则/权限）、反馈信号（linter/测试/类型检查）、回退手段（Git/沙盒/快照）。
3. 对危险动作设专门检查（语义解析而非关键字黑名单）+ 审批（Sidecar 只读结构化字段）。
4. 设计故障恢复：先分类（可重试/不可重试）再计数（重复指纹/连续失败），分级恢复（静默重试→降级接续→暴露给用户），每条路径有熔断上限。
5. 评估改动时用"边界集 + 保留集"验证，最小 diff + 可回滚。

禁止清单（写清合法例外）

• 禁止把业务规则只写在文档/提示词里。例外：规则的自然语言版本可放提示词供理解解释，但关键决策点必须有代码化校验做"守门员"。
• 禁止在确认无法恢复前暴露中间态（工具调用失败先静默重试，不把半成品给用户）。例外：所有自动手段用尽后才呈现错误并附已尝试的恢复动作。
• 禁止无限重试（每条恢复路径必须有熔断上限，阈值来自生产数据而非拍脑袋）。例外：可重试错误（限流/过载/网络抖动）才重试，且指数退避+随机抖动。
• 禁止用关键字黑名单作为唯一安全手段（Shell 组合爆炸可绕过，需语义解析理解命令真实效果）。
• 禁止把权限检查放在动态生成的业务代码里（应下沉到数据层，见 agent-security）。

参考资料

• 本书第 1.2 节《Harness 工程》+ 第 5.1.4/5.1.5 节《Harness 工程在 Coding Agent 中的实践》《故障与错误恢复》。
• 笔记 01-AI-Agent入门.md、05-Coding-Agent与通用Agent.md。
• Anthropic "Harness design for long-running application development"。