| 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 获取文章蒸馏与落地检查清单。
