# Task Harness 方法论

## 为什么需要 Harness？

Agent 的核心限制是**无状态**——每次会话都从零开始，没有之前会话的记忆。没有结构的 Agent 会以可预测的方式失败：

| 失败模式 | 表现 |
|---------|------|
| 贪多嚼不烂 | 试图一次做太多，代码只实现了一半 |
| 过早宣称完成 | 声称工作完成了，实际还有遗漏 |
| 破坏环境 | 留下编译错误、测试失败、依赖冲突 |
| 重复探索 | 每次会话花大量时间重新发现项目结构 |

Harness 就是解决这些问题的**外部记忆系统**。

## 为什么用 JSON 做任务清单？

这是方法论中最关键的洞察：

模型倾向于自由改写 Markdown 文件——改写措辞、重组结构、删减内容。这种"过度编辑"倾向会导致任务清单逐渐失真：步骤被简化、验证条件被弱化、优先级被悄悄调整。

JSON 文件被模型更谨慎对待。模型更可能只修改特定字段（如 `passes`），而保留其余结构不变。这种差异对维护任务完整性至关重要。

## 核心设计原则

### 1. 单一真相来源（Single Source of Truth）

`feature_list.json` 是唯一的项目状态文件。所有判断都基于它：
- 什么还没做？→ `passes: false` 的功能
- 做了什么？→ `passes: true` 的功能
- 总进度？→ `passed / total`

不要在其他文件中维护重复的任务列表。

### 2. 叙事性日志（Narrative Log）

`progress.txt` 用自然语言记录"做了什么"和"为什么"。JSON 精确但不解释原因。当 Agent 需要理解某个设计决策的背景时，叙事日志比 JSON 中的步骤列表更有用。

### 3. 快速上下文恢复（Fast Context Restore）

`init.sh` 在 5 秒内提供全部关键信息：git 状态、完成进度、剩余任务。Agent 不需要花 30 秒读文件就能知道该做什么。

### 4. 增量推进（Incremental Progress）

每个会话只做 1-2 个功能。这看起来慢，但实际更快：
- 更少的回滚风险
- 更可靠的验证
- 更清晰的 git 历史
- 更容易恢复中断的工作

## 常见问题

### Q: 任务拆得太细，会不会效率低？

**不会。** Agent 在大任务上的失败率远高于小任务。一个 10 步任务被中断后，很难判断哪一步完成了、哪一步是半成品。拆成 10 个独立功能后，每个都能被独立验证和提交。

### Q: 为什么要强制 commit + push？

**防止进度丢失。** Agent 会话可能因超时、错误、网络中断等原因终止。如果工作只在本地，就会丢失。Push 到远程后，即使本地出问题也能从远程恢复。

另外，每个功能一个 commit 使得：
- 可以用 `git revert` 独立回滚某个功能
- 可以用 `git log` 追踪每个功能的变化
- 多人协作时可以清楚看到每个功能的改动

### Q: feature_list.json 太大了怎么办？

如果功能超过 50 个，考虑分阶段创建：
- 先创建当前阶段的 20-30 个功能
- 当前阶段完成后，再创建下一阶段的功能

这样保持文件大小可控，Agent 读取更快。

### Q: Agent 不遵守规则怎么办？

在 `AGENTS.md` 中以明确的规则形式写好约束。AGENTS.md 会在每次会话开始时被加载到 Agent 的上下文中，比普通文件更有约束力。

关键规则要放在 `AGENTS.md` 的 `Rules` 部分，而不是 `## Notes` 或 `## Tips` 中。

### Q: steps 数组中的步骤应该多详细？

**越具体越好。** 好的步骤应该能让 Agent 无需猜测就执行：

```
// 差：太模糊
"修改样式"

// 好：足够具体
"在 web/src/index.css 的 :root 块中添加 --semi-color-primary: #DC2626"
```

具体的步骤还能防止 Agent "过度发挥"——在不该改的地方做改动。

## 最佳实践

### 1. 功能 ID 命名

使用有意义的 ID，一眼就能看出属于哪个版本/阶段：

```
v1-01, v1-02, ...    # 第一版功能
v2-01, v2-02, ...    # 第二版功能
fix-01, fix-02       # 修复类
infra-01             # 基础设施类
```

### 2. 分类（category）

按代码层级分类，帮助 Agent 理解功能间的关系：

```
foundation    # 基础设施（字体、颜色、配置）
layout        # 布局结构（页面框架、导航）
components    # 组件（按钮、卡片、表单）
pages         # 具体页面
api           # 后端接口
database      # 数据库相关
verification  # 验证和测试
```

### 3. 验证条件（verification）

每个功能必须有可执行的验证条件：

```
// 差：主观描述
"看起来更好"

// 好：可执行的检查
"bun run build 成功无错误"
"登录页桌面端显示左右分屏，移动端只有表单区"
"表头 font-weight: 600，font-size: 12px"
```

### 4. progress.txt 格式

使用统一的日志格式，让后续会话容易解析：

```
----------------------------------------
会话 #N - 功能ID: 功能描述
----------------------------------------
时间: YYYY-MM-DD

完成工作:
  [x] 具体做了什么
    - 文件: path/to/file (line XX)
    - 改动: 具体变更

提交:
  - commit: abc1234 feat(scope): 描述
  - push: origin main

进度:
  - 已完成: N/M
  - 下一个: feature-id (描述)
```

### 5. 处理阻塞

当 Agent 遇到无法解决的问题时：

```
⚠️ 阻塞: 描述遇到的问题
原因: 为什么无法继续
尝试: 已经尝试过的解决方案
建议: 可能的解决方向
```

不要让 Agent 绕过阻塞继续做其他功能——这可能导致后续功能也失败。

## 参考

- [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — Anthropic 官方方法论文章
- [task-harness SKILL.md](../SKILL.md) — 技能主入口
- [templates/](templates/) — Harness 文件模板