# Harness Design

> Generator-Evaluator迭代工作流编排器，自动根据任务复杂度选择普通模式或PID增强模式。适用于任何需要"生成-评估"循环的场景：前端页面、文档、代码、方案设计等。普通模式用于简单任务（首轮>70%通过），PID模式自动升级用于复杂多Bug任务或出现退步时。触发词：harness、生成评估循环、质量迭代、Generator+Evaluator、对抗式生成、迭代优化、质量振荡、反馈控制、收敛监控、来回改、越改越差、迭代不稳定。即使用户只说"帮我迭代优化"或"我的Agent总在来回改"也应触发。

- Skill: `josephcooperhc/harness-design` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add josephcooperhc/harness-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/josephcooperhc/harness-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: JosephCooperHC (https://skillmd.com/u/josephcooperhc)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/josephcooperhc/harness-design

---


# Harness Design：自适应迭代工作流

Generator-Evaluator对抗迭代框架。简单任务用普通模式，复杂任务自动升级PID增强模式。

**自动模式选择**（基于实验验证的边界条件）：

```
Round 1 结果
├── 通过率 > 70% → 普通模式（实验T1/T2：三策略无差异）
├── 通过率 < 70% + 关联Bug → PID模式（实验T3：2轮vs3轮vs4轮）
└── 任何轮次出现退步 → 升级PID模式（实验T3：R3退步8→4）
```

---

## Phase 1：理解任务

通过对话确认4点：

1. **任务类型**：前端页面 / 文档 / 代码 / 方案 / 其他
2. **产出物**：具体交付什么
3. **目标用户**：谁使用/阅读
4. **质量期望**：什么算好

确定Generator的领域skill：

| 任务类型 | Generator skill |
|---------|----------------|
| 前端页面 | `frontend-design` |
| 技术文档 | `tech-doc-writer` |
| 代码 | 按语言选择或无skill |
| 方案 | `tech-doc-writer` 或 `product-design` |

---

## Phase 2：定义评估标准

帮用户把"好不好"变成可打分的维度。

### Step 2.1：推荐3-5个评估维度

每个维度需要：名称、权重（总和100%）、评分标准（四档）、检查项。

**预设模板（按任务调整）：**

| 任务类型 | 维度示例 |
|---------|---------|
| 前端 | 任务效率30%、信息层级25%、视觉一致20%、交互反馈15%、边界状态10% |
| 文档 | 准确性35%、完整性25%、可读性20%、可操作性20% |
| 代码 | 功能正确35%、代码质量25%、健壮性20%、性能20% |

### Step 2.2：与用户确认

展示维度表格，确认权重和覆盖面。

### Step 2.3：设定阈值

- 通过分数（默认7.5）
- 单项最低分（默认5.0）
- 最大迭代轮数（默认3轮）

---

## Phase 3：自适应迭代

### Step 3.1：生成Evaluator提示词

```
# [任务类型] Evaluator
你是独立评估器，与Generator对抗。
按N个维度逐项评分（1-10分），给出改进清单。
规则：只评不改、每个问题给可执行建议、同问题2轮未改升级P0。
```

### Step 3.2：Round 1 — 启动Generator-Evaluator

创建Generator subagent生成初版，创建Evaluator subagent评分。

### Step 3.3：自动边界检测（Round 1后执行）

```python
# 基于实验数据的边界判断
round1_score = evaluator_result.weighted_score  # 归一化到[0,1]

if round1_score >= 0.7:
    mode = "普通模式"  # 实验T1/T2：简单任务三策略无差异
elif has_correlated_failures(evaluator_result):
    mode = "PID增强模式"  # 实验T3：关联Bug时PID 2轮vs普通3轮
else:
    mode = "普通模式"  # 独立Bug，逐个修就行
```

**后续轮次：** 如果任何轮次出现退步（当前分<上轮分），自动升级到PID模式。
实验依据：T3简单重试R3从8/10退步到4/10，反馈控制可避免此问题。

升级时向用户报告：`"检测到[条件]，自动升级到PID增强模式。"`

### Step 3.4：普通模式迭代

```
WHILE 轮数 < 最大迭代轮数:
  1. Evaluator评分
  2. IF 达标 → 通过，交付
  3. IF 退步 → 升级到PID模式（Step 3.5）
  4. ELSE → 提取改进建议 → 新Generator subagent（上下文重置） → 继续
```

关键：每轮Generator用新subagent（上下文重置），避免上下文焦虑导致保守改动。

### Step 3.5：PID增强模式迭代

当自动检测触发PID模式时执行。详细参数和算法见 `references/pid-control.md`。

**PID模式与普通模式的3个核心差异（全部实验验证）：**

**差异1：精确反馈替代通用反馈**
- 普通模式："请根据以下问题改进"
- PID模式："T3/T7/T10失败，root cause是get()未更新访问顺序，修复时同时检查put()的recency更新"
- 实验证据：T3中PID 2轮收敛 vs Self-Refine 3轮，差异来自精确反馈+预防性提示

**差异2：PID控制信号调节反馈强度**
- 误差大(u>0.7)→重大重写指令
- 误差中(u 0.3-0.7)→中度修改
- 误差小(u<0.3)→轻微微调
- 实验中u=0.285（轻度），避免了过度修正

**差异3：Jury预检+Lyapunov退步检测**
- Jury预检：排除不稳定参数（实验A2：满足Jury 95%收敛 vs 违反Jury 0%收敛）
- Lyapunov V(i)=½e²检测退步（实验T3：ΔV=+16.0准确检测到R3崩溃）
- 注意：Lyapunov仅做检测预警，不自动降增益（实验A1验证自动降增益无效）

**PID模式的额外发现（已验证）：**
- 激进反馈/强模型更容易退步（实验B1：激进模式100→90）→ 用强模型时降低反馈增益
- 间隔反馈(N=2)省50%评估成本（实验B2：同速收敛但评估调用减半）

### Step 3.6：输出最终报告

```
## Harness 迭代报告

**任务**：[描述]
**模式**：普通模式 / PID增强模式（Round X自动升级，原因：[条件]）
**迭代轮数**：N
**最终评分**：X.X/10

### 评分明细
| 维度 | 权重 | R1 | R2 | ... | 最终 |
|------|------|-----|-----|-----|------|

### 模式切换记录（如有）
- Round 1: 普通模式，通过率65%（<70%且Bug有关联）
- Round 2: 自动升级PID模式，精确反馈+root cause

### 产出物位置
[路径]
```

---

## 注意事项

### 上下文重置
每轮Generator必须是新subagent。传入：原始任务+改进建议+上轮产出路径（参考用）。

### 生成与评估分离
不要让Generator评估自己。Evaluator只拿产出物和标准，不知道生成过程。

### 何时不需要Harness
- 任务一次就能做好 → 直接做
- 用户说"不用这么复杂" → 可只生成Evaluator提示词供手动使用
- 评估标准完全主观 → 用户手动审查

### PID模式何时不值得
- 首轮通过率>70%（实验验证：无差异）
- Bug相互独立（逐个修即可）
- 2轮内能解决（Self-Refine足够）