第 13 章 | 编写 tasks.md

更新于 2026/5/10
💡 进群学习加 wx: agentupdate
(申请发送: agentupdate)

第 13 章：编写 tasks.md

学习目标

把 spec 翻译成可执行的"组"——dispatch 的最小单位。

任务清单的核心结构

## 1. 组名

- [ ] 1.1 任务描述
- [ ] 1.2 任务描述
- [ ] 1.3 任务描述

## 2. 组名

- [ ] 2.1 ...

两个硬规则：

  • ## N. 数字标题划分组（这是 dispatch 的边界）
  • - [ ] checkbox 是状态标记（developer 完成后改 - [x]）

组的粒度

flowchart LR
    Bad1["太粗:
1 组 30 个 task"] --> ProB1["每次 dispatch
上下文爆炸"]
    Bad2["太细:
每 task 一组"] --> ProB2["dispatch 50+ 次
编排成本高"]
    Good["合适:
3~7 task / 组"] --> ProG["dispatch 10~15 次
每次工作量明确"]

    style Bad1 fill:#ffcdd2
    style Bad2 fill:#ffcdd2
    style Good fill:#c8e6c9

→ MVP 阶段先按 3~7 task / 组拆。

组与 Requirement 的映射

不是 1:1，是多对多：

组 3 (TTS Backend)        ─┬→ Requirement: TTS 配音生成
                           └→ 部分: Markdown 解析 (narration 字段)

组 7 (编排器)              ─┬→ Requirement: 同步策略
                           ├→ Requirement: 录制中错误暂停 (部分)
                           └→ 部分: 终端控制

→ 一个组可以涉及多个 Requirement，一个 Requirement 也可被多个组实现。

任务的"完成定义"

每条 task 必须可被 yes/no 验证。模板：

✅ "实现 TTSBackend 抽象类，方法 synthesize(text) -> Path"
   → 看代码有没有这个类、方法签名对不对，能立刻判断
   
❌ "完善 TTS 模块"
   → "完善"是什么？验不了
   
❌ "提高代码质量"
   → 同上，含糊

实例：doc2video 的 13 个组

flowchart TB
    G1["1. 项目脚手架
(4 task)"] --> G2["2. Markdown 解析
(5 task)"]
    G2 --> G3["3. TTS Backend
(4 task)"]
    G2 --> G4["4. Tmux 终端控制
(6 task)"]
    G3 --> G7["7. 编排器
(5 task) TDD"]
    G4 --> G7
    G2 --> G5["5. 文档面板
(5 task)"]
    G5 --> G7
    G4 --> G6["6. 屏幕录制
(5 task)"]
    G6 --> G7
    G7 --> G8["8. Dry-run 预检
(5 task)"]
    G7 --> G9["9. 错误暂停
(7 task) TDD"]
    G7 --> G10["10. 视频合成
(4 task)"]
    G10 --> G11["11. 报告输出
(3 task)"]
    G11 --> G12["12. CLI 整合
(5 task)"]
    G12 --> G13["13. 文档与示例
(3 task)"]

    style G7 fill:#fff9c4
    style G9 fill:#fff9c4

→ 黄色标记是 TDD 组（先写测试再实现）。

排序规则

✅ 上游模块先做（脚手架 → 解析 → TTS / 终端 → 编排）
✅ 独立可并行的组排相邻（TTS 与 Tmux 互不依赖）
✅ 集成组放最后（CLI 整合、E2E 示例）
✅ 复杂的 TDD 组明确标注
❌ 不要按"工作量大小"排序
❌ 不要把验证类组放最前

TDD 标记

某些组需要先写测试（H3 规则）：

## 7. 编排器（同步策略）  <!-- TDD -->

- [ ] 7.1 ...
- [ ] 7.2 ...

<!-- TDD --> 注释告诉 dev.md 在 dispatch developer 之前先 dispatch tester 写失败测试。

反模式

❌ 一个组 20+ task                 太大
❌ 一个组 1 task                   太碎
❌ 跨组循环依赖                    死锁
❌ task 不可验证                   无法判断完成
❌ task 列出"实现"动词但没说要什么  没契约

你现在能做什么

  • 把 spec 拆成 5~15 个组
  • 每条 task 都能 yes/no 验证完成
  • 标记需要 TDD 的复杂组
  • 画出组的依赖图