harness-engineering

name	harness-engineering
description	将复杂开发任务放入“harness 优先”的执行框架，规范代理在真实工具链中的自主执行、人机协作与主动求助。用于需要在代码库中持续迭代并以测试/日志/CI 为证据交付的场景，尤其适合长链路排障、跨模块修复、权限受限环境、CI 失败修复和需要明确“何时请求人工决策”的任务。

Harness Collaboration Skill

核心目标

• 把任务放进可执行 harness，而不是只依赖提示词。
• 用可观测证据驱动迭代：工具输出、测试结果、日志、CI 状态。
• 降低人机来回拉扯：让代理先跑，达到阈值再请求人工决策。
• 在求助时提供结构化选项，而不是只汇报失败。

执行流程

1) 先定义成功与边界

• 明确交付物、验收标准、约束条件、不可改动范围。
• 把任务拆成 3-6 个可验证里程碑，每步都能用命令或文件证据判定完成。
• 在开始前写明失败可接受范围（例如允许重试次数、最长探索时间）。

2) 优先完善 harness，再让代理执行

• 按最小权限逐级放开能力，不一次性给最高权限：
  • L1: 只读代码与文档
  • L2: 可运行测试与静态检查
  • L3: 可修改代码并回归
  • L4: 可执行需要授权的外部操作（发布、生产变更）
• 在每一级都定义“升级条件”和“回滚条件”。
• 缺少关键工具时先补工具链，再做深度优化。

3) 给代理自主探索预算，避免每步打断

• 设定时间预算和尝试预算（例如单问题最多 20 分钟或 3 次同类尝试）。
• 要求每轮迭代都产出证据：做了什么、结果如何、下一步假设是什么。
• 禁止“无证据重试”：同样手段失败后，必须换策略或请求人工输入。

4) 按阈值触发主动求助

• 任一条件满足即主动请求人工决策：
  • 同类失败连续 2-3 次，且误差模式一致；
  • 缺少关键上下文（需求口径、环境变量、数据权限）；
  • 需要越过安全边界或执行高风险变更；
  • 出现多解分支且成本/风险显著不同。
• 求助时一次性提供：
  • 已尝试动作与证据；
  • 根因假设与不确定点；
  • 2-3 个可选方案（收益、风险、时间成本）。

5) 用“选项型提问”提升协作效率

• 采用封闭式选项，减少往返：
  • 选项 A（推荐）：低风险、耗时短、覆盖 80% 场景
  • 选项 B：中风险、改动较大、收益更高
  • 选项 C：高风险、仅在强需求时采用
• 每次提问只聚焦一个决策点，避免在一个消息中混入多个问题。

6) 以“可追溯交付”收束

• 交付内容必须包含：
  • 变更清单（文件与关键行为）；
  • 验证证据（命令、结果、失败与修复过程）；
  • 已知风险与边界（明确未覆盖项）。
• 严禁静默降级、伪成功路径、隐藏失败。

主动协作消息模板

在触发求助阈值后，使用以下模板：

当前阻塞: <一句话描述>
已验证事实:
1) <证据1>
2) <证据2>
3) <证据3>

根因假设:
- H1: <假设 + 置信度>
- H2: <假设 + 置信度>

可选决策:
- A(推荐): <方案> | 成本 <x> | 风险 <y> | 预计耗时 <z>
- B: <方案> | 成本 <x> | 风险 <y> | 预计耗时 <z>
- C: <方案> | 成本 <x> | 风险 <y> | 预计耗时 <z>

需要你确认: <仅一个决策问题>

反模式

• 过早求助：尚未形成证据就请求人工接管。
• 无界重试：重复同一命令但不改变假设。
• 静默绕过：用兜底路径掩盖真实失败。
• 只报问题不报选项：把决策压力全部转移给人工。
• 完成后无证据：缺少可复现实验与验证记录。

参考资料

• 读取 references/harness-engineering-digest.md 获取文章蒸馏与落地检查清单。