# Lesson 23.1: Harness 设计哲学——来自 Anthropic 工程团队的实战经验

## 本课目标

- 理解 Harness（驾驭层）的核心思想：探测→执行→评估→优化的闭环
- 掌握生成器-评估器分离原则——为什么不能让 AI 给自己打分
- 理解"上下文焦虑"现象以及重置 vs 压缩的权衡
- 学会 Sprint 合约——让代理先对齐"什么算完成"再动手
- 理解 Harness 演进——随模型进化做减法

> **前置知识**：本课建立在 Lesson 23（Hooks、Rules、Quality Gate）的基础上。如果你还不了解 Hook 的触发机制和 Quality Gate 的工作逻辑，请先回顾上一课。
>
> **来源**：本课核心内容来自 [Anthropic 工程博客：Harness design for long-running apps](https://www.anthropic.com/engineering/harness-design-long-running-apps)。

## 核心内容

### 什么是 Harness Engineering？

上一课你学了 Hooks、Rules、Quality Gate——这些是**单点自动化**。Harness Engineering 是**系统级自动化**——把所有单点串成一个闭环。

```
单点自动化（L23 学的）：
  编辑代码 → [Hook] 自动格式化
  提交代码 → [Quality Gate] 自动检查
  每一个点独立运行，互不关联

Harness Engineering（本课）：
  探测环境 → 执行任务 → 评估结果 → 优化配置 → 再循环
  ↑                                              ↓
  └──────────── 持续改进闭环 ──────────────────────┘

  所有单点被串成一个自我优化的系统
```

**一个类比**：单点自动化像家里的烟雾报警器——各管各的。Harness Engineering 像智能家居中控——温度、湿度、灯光、安防全部联动，还能根据你的习惯自动调整。

### 闭环的四个阶段

```
┌──────────────────────────────────────────────────────┐
│            Harness Engineering 闭环                    │
│                                                        │
│  ① 探测（Detect）                                      │
│     quality-gate.js 自动检测：                          │
│     有 package.json？→ 用 npm                          │
│     有 go.mod？→ 用 go test                            │
│     有 biome.json？→ 用 Biome                          │
│     什么都没有？→ 跳过，不报错                           │
│                    ↓                                   │
│  ② 执行（Execute）                                     │
│     /orchestrate → 多代理接力：                          │
│     planner → tdd-guide → code-reviewer → security     │
│     每个代理独立上下文，通过 Handoff 文档传递             │
│                    ↓                                   │
│  ③ 评估（Evaluate）                                    │
│     /harness-audit → 基于 **[EDD (Lesson 22.1)](lesson-22.1.md)** 的评分：     │
│     工具覆盖 + 上下文效率 + 质量门禁 + ...              │
│     评分 52/70 → 找到薄弱环节                           │
│                    ↓                                   │
│  ④ 优化（Optimize）                                    │
│     harness-optimizer 代理 → 提出最小改动：              │
│     "添加 cost-tracker Hook" → +3 分                    │
│     "补充 eval 模板" → +4 分                            │
│                    ↓                                   │
│  回到 ① → 下一轮探测、执行、评估、优化                   │
└──────────────────────────────────────────────────────┘
```

### 生成器-评估器分离——不要让 AI 给自己打分

Anthropic 工程团队发现了一个关键事实：**AI 给自己的工作打分时，会系统性地偏高**。就像学生自评总觉得"写得还行"，AI 也会合理化自己的问题。

解决方案借鉴了 GAN（生成对抗网络）的思想——**把"做事的"和"评判的"拆成两个独立代理**：

```
❌ 一个代理自己写、自己评：
   写代码 → 自我审查 → "看起来不错" → 通过
   （AI 倾向于认为自己的输出是合理的）

✅ 两个代理分工（Generator + Evaluator）：
   Generator（生成器）→ 写代码
   Evaluator（评估器）→ 独立审查（从未见过写代码的过程）
   → 评估器更容易发现问题，因为它没有"作者偏见"

> **关联回顾**：你在 **[Lesson 22.1 (EDD)](lesson-22.1.md)** 中已经学过了这个模式。它是整个 Harness 设计的灵魂——没有独立的评估器，闭环就会因自我美化而失效。
```

**为什么有效？** 独立评估器可以被调教得更加"怀疑主义"——要求它挑毛病比要求生成器自我批评容易得多。这个原则适用于主观领域（设计是否好看）和客观领域（代码是否正确）。

在 cc4pm 中，`/orchestrate` 的代理链天然实现了这一点：`code-reviewer` 代理独立于 `tdd-guide` 运行，它审查的代码不是自己写的。RFC-DAG 模式更是在架构层面强制分离——每个阶段用不同的代理上下文。

### Sprint 合约——先对齐"什么算完成"再动手

Anthropic 发现，让 AI 代理直接开干容易导致**目标偏移**——它实现的东西和你期望的不一样。解决方案是引入 **Sprint 合约**。

但在此之前，有一个更根本的前置判断：

> **如果一个任务连"什么算完成"都说不清楚，就不要急着交给 Claude Code 自主执行。**

这不是效率问题，而是**方向问题**。没有完成标准的任务交给自主代理，就像没有终点线的马拉松——AI 会一直跑，但不知道该在哪里停。结果要么过早停止（草草交差），要么过度发散（做了一堆你不要的东西）。

```
任务就绪度检查：

  能清晰描述"完成"的样子吗？
  ├─ 能 → 写成验收标准 → 进入 Sprint 合约 → 交给代理
  └─ 不能 → 先自己想清楚，或用 CIS 头脑风暴梳理
            → 不要急于自主执行
```

Sprint 合约的具体机制：

```
在 Generator 动手之前，Generator 和 Evaluator 先协商：

Generator 提出：
  "我将实现矩形填充工具，支持点击拖拽操作"

Evaluator 确认：
  "同意。验收标准：
   1. 矩形填充工具支持点击拖拽   ✓ 可验证
   2. 填充区域有视觉反馈          ✓ 可验证
   3. 支持撤销操作                ✓ 可验证"

双方对齐后 → Generator 开始实现
```

**为什么不直接写细致的 PRD？** 因为过于细致的 Spec 会"锁死"错误的技术路径——Sprint 合约只定义**验收条件**，不限定实现方式，给 AI 留出灵活空间。

这个思想和 Lesson 16（冲刺规划）中 Bob 代理的 Story 执行类似——但 Sprint 合约更聚焦于**代理之间的预协商**，不是人与代理之间的沟通。

### 上下文焦虑——AI 为什么会"草草收工"

Anthropic 发现了一个行为现象叫**"上下文焦虑"**（Context Anxiety）：当 AI 接近上下文窗口的上限时，它会**提前草草收工**——不是因为真的没空间了，而是因为它"感觉"快没空间了。

```
上下文焦虑的表现：
  ✏️ 本该详细实现的功能被简化为 TODO
  ✏️ 本该写 10 个测试的只写了 3 个
  ✏️ 开始用"为了简洁起见"来省略关键步骤
  ✏️ 主动提出"剩余部分留给下次"
```

这就是为什么长程任务需要**上下文重置**（接力跑），而不是**上下文压缩**：

| | 压缩（Compaction） | 重置（Reset/接力跑） |
|---|---|---|
| 做法 | 总结早期对话，保留在同一会话 | 完全清空，启动全新会话 |
| 上下文焦虑 | **依然存在**（AI 知道已聊很久） | **消除**（全新的开始） |
| 连续性 | 保留（对话历史的摘要在） | 中断（需要通过文件传递） |
| 代价 | 低（不需要额外协调） | 高（需要 Handoff 文档） |
| 适用场景 | 单次会话内的日常压缩 | 长程自主任务的步骤切换 |

**注意**：随着模型进化，上下文焦虑在减弱。Opus 4.6 比早期模型表现好很多。但在长程任务中，接力跑依然是更可靠的选择。

> **回顾**：Lesson 2 教了压缩（/compact），Lesson 3 教了会话管理（/continue）。这里的上下文重置是更激进的做法——不是压缩同一个会话，而是**结束会话、启动全新会话、通过文件传递状态**。下一课（L23.2）会详细讲四种具体的循环模式实现。

### Harness 演进——设计空间在迁移，而非消失

Harness 设计的一个核心原则：**每一层 Harness 都编码了对模型局限性的假设。当模型进化了，假设就过时了，Harness 就该简化。**

但 Anthropic 的结论不是"模型越强 Harness 越少"——而是更微妙的：

> **"Harness 的设计空间不会随模型进化而缩小，而是会迁移。有趣的工作是找到下一个新的组合。"**

旧的约束可以移除，但新的有趣组合出现了。比如旧模型需要"逐 Sprint 强制分解"，新模型不需要了——但新模型让"跨工具链的端到端评估"变得有价值了。

Anthropic 用真实项目数据证明了这一点：

```
┌─────────────────────────┬──────────┬────────┬──────────────┐
│ 配置                     │ 时间      │ 成本   │ 输出质量      │
├─────────────────────────┼──────────┼────────┼──────────────┤
│ 无 Harness（裸跑）       │ 20 分钟   │ $9     │ 核心功能损坏  │
│ 旧模型 + 完整 Harness    │ 6 小时    │ $200   │ 功能完整、精致 │
│ 新模型 + 简化 Harness    │ 约 4 小时  │ $125   │ 功能完整      │
└─────────────────────────┴──────────┴────────┴──────────────┘
```

**三个关键结论**：

1. **裸跑不可接受**——便宜（$9）但核心功能损坏、UX 糟糕
2. **完整 Harness 有效但贵**——$200 / 6h，质量优秀
3. **新模型 + 简化 Harness 是最优解**——$125 / 4h，质量相当，成本减半

**简化了什么？** 新模型能力提升后：
- 移除了逐 Sprint 的强制分解（单次连续会话即可）
- 评估从"每个 Sprint 后评估"变为"最终统一评估"
- 减少了显式脚手架（模型本身就会规划）

**实际操作**：每当模型升级后，用 `/harness-audit` 重新评估，逐步移除不再需要的约束——一次只移除一个组件，验证质量不下降后再移除下一个。

> **提示**：Harness 的进阶演进是**完全解耦**。在 **[Lesson 23.3](lesson-3.3.md)** 中，你将学习 Anthropic 最新的 **Managed Agents** 架构，它通过解耦「大脑」、「双手」与「会话」实现了极致的安全与性能。

### Evaluator 的价值边界——什么时候该用、什么时候多余

Anthropic 发现评估器不是万能的——它有一条**价值边界**：

```
模型可靠基线内的任务（简单功能、已有范式的实现）：
  → Evaluator 是多余开销，不增加质量，只增加成本
  → 用简单的测试套件就够了

超出基线的任务（复杂交互、主观判断、创新设计）：
  → Evaluator 提供可测量的价值提升
  → 越是主观的任务，Evaluator 越重要
```

**PM 的判断标准**：如果任务有明确的对错标准（API 返回正确数据），测试套件就够了。如果任务涉及主观判断（UX 是否好用、设计是否美观），才需要独立的 Evaluator 代理。

### 标准的措辞会塑造输出

Anthropic 还发现了一个微妙但重要的现象：**评估标准的具体措辞会直接影响生成结果**。

```
例子：评估标准中写了 "最好的设计是博物馆级的品质"
  → 所有迭代的设计开始向同一种"高雅"风格收敛
  → 不是因为评估器反馈，而是标准本身就在引导方向

启示：你写验收标准时选择的词语，就是在隐性地引导 AI 的输出方向。
  "简洁" → AI 产出极简风格
  "专业" → AI 产出企业风格
  "创新" → AI 产出实验性方案
```

**对 PM 的意义**：写 PRD 和验收标准时，**措辞不是中性的**。你选择的形容词会系统性地影响 AI 的输出方向——甚至在任何反馈循环开始之前就已经生效。

### 全景：Harness 设计的八个原则

```
① 说不清完成就别交   → 任务连"完成"都定义不了，不要交给自主代理
② 分离生成与评估     → Generator 和 Evaluator 独立运行
③ 量化主观判断       → 把"好不好"变成可打分的具体标准
④ 用重置代替压缩     → 长程任务用接力跑，不用无限对话
⑤ 先签合约再动手     → Sprint 合约避免目标偏移
⑥ 设计空间在迁移     → 旧约束移除，新组合出现
⑦ 识别价值边界       → 基线内不用 Evaluator，超出基线才用
⑧ 标准措辞即引导     → 验收标准的用词会隐性塑造输出方向
```

## 🛠️ 实操练习

### 练习 1：识别你项目中的 Generator 和 Evaluator

**思考题**：在你的工作流中，哪些环节是"自己写、自己评"的？如何拆分？

| 当前做法 | 拆分方案 |
|---------|---------|
| AI 写代码后自己说"完成了" | 加 /code-review 独立审查 |
| AI 写 PRD 后自己验证 | 用 /bmad-validate-prd 独立评估 |
| _______ | _______ |

### 练习 2：体验 Harness 成本对比

```bash
# 1. 先裸跑一个简单任务（观察质量）
claude -p "创建一个 todo 应用的 HTML 页面"

# 2. 再用 orchestrate 跑同一个任务（对比质量）
/orchestrate feature "创建一个 todo 应用的 HTML 页面"
```

**任务**：对比两种方式的输出质量，体会 Harness 的价值。

### 练习 3：检查你的 Harness 是否需要"做减法"

```bash
/harness-audit
```

**任务**：
1. 查看 7 维评分
2. 思考：如果换用更新的模型，哪些约束可以简化？
3. 记录你的判断

**检查清单**：
- [ ] 理解了生成器-评估器分离的原理
- [ ] 理解了上下文焦虑和重置 vs 压缩的区别
- [ ] 理解了 Sprint 合约的作用
- [ ] 理解了 Harness 演进的"做减法"原则
- [ ] 运行了 `/harness-audit`

---

## 常见问题

**Q: 生成器-评估器分离，和 /code-review 有什么关系？**

A: `/code-review` 就是这个原则的落地实现。当你用 `/orchestrate feature` 时，tdd-guide 写代码、code-reviewer 审查——它们是独立的代理，各自有独立的上下文窗口。code-reviewer 从未参与写代码的过程，所以它能更客观地发现问题。

**Q: 上下文焦虑是所有模型都有的吗？**

A: 程度不同。早期模型（如 Sonnet 4.5）比较明显，Opus 4.6 已经大幅改善。但在超长会话（数千轮交互）中，即使最新模型也可能出现类似现象。所以长程任务仍然推荐使用接力跑模式。

**Q: "做减法"会不会导致质量下降？**

A: 不会——前提是你**一次只移除一个组件**并验证质量不下降。Anthropic 的数据显示，新模型 + 简化 Harness 的质量与旧模型 + 完整 Harness 相当。关键是用 `/harness-audit` 定期审计，而不是盲目简化。

**Q: Sprint 合约是给开发者用的吗？PM 需要关注吗？**

A: PM 需要关注合约的**验收标准**部分——它定义了"什么算完成"。这和你在 Lesson 16 学的 Story 验收标准一脉相承。区别在于：Story 验收标准是人定的，Sprint 合约是代理自动协商的。你的参与点是**审查合约是否合理**。

## 下一步

请调用 `AskUserQuestion` 展示以下选项，让学习者点击选择；从每条中提炼 1-5 个词作为 label，其余写入 description，不要要求输入数字：

- 继续 Lesson 23.2：Harness 实操——循环模式、编排与审计
- 返回主菜单
- 退出学习

---
*阶段 4 | Lesson 23.1/26 | 上一课: Lesson 23 - 自动化工作流 | 下一课: Lesson 23.2 - Harness 实操*