2217173240/coding-agent-prompt-best-practice/harness-engineering

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