# Harness Engineering

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

- Skill: `misonl/harness-engineering` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add misonl/harness-engineering`
- Raw SKILL.md: https://api.skillmd.com/api/skills/misonl/harness-engineering/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: misonl (https://skillmd.com/u/misonl)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/misonl/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) 以“可追溯交付”收束

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

## 主动协作消息模板

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

```text
当前阻塞: <一句话描述>
已验证事实:
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` 获取文章蒸馏与落地检查清单。