本文是「智能日报系统」SDD 从零到一系列的第 4 篇。
proposal.md定了"做什么"，design.md定了"怎么做"，tasks.md回答最后两个问题：按什么顺序做？每步的验收标准是什么？ 它是 SDD 工作流的最后一环，也是直接驱动 AI 写代码的一环。
摘要 ：如何让 AI 完美执行你的代码需求？答案是把复杂的工程拆解成 AI 能够按部就班执行的"施工单"。本文详细拆解了 tasks.md 的任务五要素结构，教你如何通过精确引用章节号、设定可打勾的验收标准和显式声明依赖关系，将设计图转化为一条条可以直接喂给 AI 的指令。读完本文，你将掌握调度 AI 高效、稳定产出高质量代码的核心密码。
本文目录
一、tasks.md 的三层结构
tasks.md 文档的设计非常精炼，主要包含以下三层结构：
| 层次 | 内容 |
|---|---|
| 任务元信息 | 关联规范、任务总数、预计时间、执行策略 |
| 任务列表 | 每个任务的描述、输入、输出、依赖、验收标准 |
| 执行顺序 | 考虑依赖关系的阶段划分与并行安排 |
本项目的元信息开门见山：
markdown
- 关联规范：specs/proposal.md, specs/design.md
- 任务总数：10
- 预计总执行时间：3-4 小时（含测试）
- 执行策略：按依赖关系顺序执行，独立任务可并行"关联规范"这一行很重要 ------它声明了任务清单的上游依据，AI 执行任何任务时都可以回溯到 proposal.md 和 design.md 查上下文。
二、任务五要素：每个任务的标准结构
tasks.md 里的每个任务都由五个要素构成：
| 要素 | 回答的问题 |
|---|---|
| 描述 | 做什么 |
| 输入 | 依赖哪些前置产出（指向上游文档的具体章节） |
| 输出 | 交付什么文件 |
| 依赖 | 需要哪些任务先完成 |
| 验收标准 | 怎么判断完成（可打勾的清单） |
以 Task 3（GitHub 采集模块）为例，这是全项目最有代表性的任务：
markdown
## Task 3: 实现 GitHub 采集模块
描述：调用 GitHub API 获取指定仓库在指定时间范围内的 commit 记录，
返回 CommitRecord 列表。
输入：design.md §3.1（CommitRecord 数据模型），
design.md §4.1（采集层接口契约）
输出：collector/github.py + tests/test_github.py
依赖：Task 2
验收标准：
- [ ] collect() 函数签名符合 design.md §4.1 的接口定义
- [ ] 返回的每个 CommitRecord 包含全部 7 个字段且类型正确
- [ ] 支持分页查询（GitHub API 默认每页 30 条）
- [ ] API 超时时重试 3 次（间隔 5s），仍失败返回空列表 + 错误日志
- [ ] GitHub API 限流（HTTP 403）时，等待 reset 时间后重试
- [ ] 使用 mock 数据的单元测试全部通过逐要素拆解它的设计意图
"输入"精确到章节号 ------不写"参考 design.md"，而是写 design.md §3.1 和 §4.1。AI 拿到任务后能直接定位所需信息，不需要通读全文去猜哪一段相关。
"验收标准"条条对应上游规范：
- "函数签名符合 §4.1" → 接口约束（篇三第五节）；
- "7 个字段且类型正确" → 数据模型（篇三第四节）；
- "超时重试 3 次、限流等待 reset" →
proposal.md边界场景 +design.md错误处理表； - "mock 单元测试通过" → 每个任务自带测试，质量左移。
每个任务同时交付实现文件和测试文件 ------github.py + tests/test_github.py。验收不是"代码写完了"，而是"测试通过了"。任务完成的标准永远可机器验证。
10 个任务的结构完全一致，这里给出其余任务的一览表：
| # | 任务 | 输出 | 依赖 |
|---|---|---|---|
| 1 | 项目结构与基础配置 | pyproject.toml + config.yaml.example |
无 |
| 2 | 共享基础层（config/logger/errors/storage） | shared/ 四个模块 + 测试 |
T1 |
| 3 | GitHub 采集模块 | collector/github.py + 测试 |
T2 |
| 4 | 飞书任务采集模块 | collector/lark_task.py + 测试 |
T2 |
| 5 | 飞书消息采集模块 | collector/lark_msg.py + 测试 |
T2 |
| 6 | 日报生成模块 | generator/formatter.py, template.py + 测试 |
T2 |
| 7 | 邮件推送模块 | notifier/email.py + 测试 |
T6 |
| 8 | 飞书推送模块 | notifier/lark_bot.py + 测试 |
T6 |
| 9 | 主编排入口 | main.py |
T3~T8 |
| 10 | 集成测试 | tests/test_integration.py |
T9 |
注意 Task 6 的验收标准里有一条："某成员当天无任何记录，日报显示'今日无记录'"------它正是 proposal.md 边界场景的第一条。验收层的每一条边界场景，都能在 tasks.md 里找到落点。 这就是三层文档逻辑约束关系的实际体现。
三、执行顺序：依赖分析与并行压缩
任务之间的依赖关系，决定了执行计划。tasks.md 把 10 个任务压缩成 7 个阶段：
| 阶段 | 任务 | 并行度 | 说明 |
|---|---|---|---|
| 1 | T1 | 1 | 项目初始化 |
| 2 | T2 | 1 | 共享基础层（所有模块的前置依赖） |
| 3 | T3 + T4 + T5 | 3 | 三个采集模块可并行 |
| 4 | T6 | 1 | 日报生成（依赖采集层的数据模型） |
| 5 | T7 + T8 | 2 | 两个推送模块可并行 |
| 6 | T9 | 1 | 主编排入口（依赖所有模块） |
| 7 | T10 | 1 | 集成测试 |
最大并行度 3，总阶段数 7------依赖图长这样：
text
T1 ──> T2 ──┬──> T3 ──┐
├──> T4 ──┼──> T6 ──┬──> T7 ──┐
└──> T5 ──┘ └──> T8 ──┴──> T9 ──> T10为什么 T3/T4/T5 能并行？回看篇三：三个采集模块共用同一份接口契约（§4.1）和各自独立的数据模型（§3.1） ，互不依赖，所以可以同时开工。这就是 design.md 里"先钉死接口"的直接红利------并行度的设计，在 design 阶段就已经埋好了。
执行顺序表还有一个隐含价值：控制变更的影响范围。如果生成模块要改，从依赖图一眼看出受影响的只有 T7/T8/T9/T10，采集层不受牵连。
四、如何用任务单驱动 AI：一次真实指令的解剖
tasks.md 写完之后，驱动 AI 编码的方式变得极其简单。以下是一条真实使用过的指令（摘自项目 readme.md）：
请实现 Task 3（GitHub 采集模块）。
具体需求见
specs/tasks.md中 Task 3 的描述及验收标准。数据模型定义见
specs/design.md§3.1（CommitRecord 数据模型）。接口契约见
specs/design.md§4.1。错误处理策略见
specs/design.md§6.1。共享模块（config、logger、errors）已在
shared/目录中实现。请生成
collector/github.py及对应的测试文件tests/test_github.py。
注意这条指令的构造方式：
- 指定任务编号 ------AI 去读
tasks.md的 Task 3，获取描述和验收标准； - 逐项指出引用章节------数据模型（§3.1）、接口契约（§4.1）、错误处理（§6.1），信息精确投放；
- 声明已有资产------"共享模块已实现"，避免 AI 重新发明 config 读取；
- 明确交付物------实现文件 + 测试文件。
对比一下没有 tasks.md 时的指令："帮我写一个读取 GitHub 提交记录的模块"------所有细节靠 AI 猜。有了三份规范，指令从"描述愿望"变成了"调度施工"。
执行后的验收动作同样简单：逐条核对验收清单。每条都是可打勾的陈述句，谁来做验收都不会有分歧。
五、写好 tasks.md 的四条心法
- 输入写章节号，不写"参考文档"：精确投放上下文，AI 不用猜；
- 验收标准必须可打勾：每条都是一个可验证的陈述，最好能变成测试用例；
- 依赖关系显式声明：并行的前提是互不依赖，写清楚才能安全并行；
- 任务粒度对齐"一次 AI 会话"：一个任务一次执行、一次验收。粒度太粗，AI 一次改一大片难以核对；太细，调度成本上升。本项目 10 个任务 / 3-4 小时，是实践下来比较舒服的密度。
六、SDD 全流程至此闭环
text
proposal.md design.md tasks.md 代码 + 测试
─────────── ───────── ───────── ──────────
为什么做/做什么 → 系统怎么搭 → 按什么顺序做 → AI 按单施工
怎么算做完 模块/接口/约束 每步怎么验收 逐条验收打勾
▲ │
└───────────────── 验收结果反向验证目标 ←─────────────────┘