本文是「智能日报系统」SDD 从零到一系列的第 5 篇（收官篇）。前四篇讲了理念与三份规范文档的写法，这一篇我们将把它们串成一次完整的动手实践：从空目录开始，按 SDD 流程搭出智能日报系统。每一步都附有可直接复用的 AI 指令模板，跟着做即可。
摘要：看完了理论，怎么落地？本文是全系列的实战大结局。我们将全景演示如何用 5 个步骤走完 SDD 闭环：从生成 proposal.md、design.md、tasks.md，到逐任务驱动 AI 写出高质量代码，最后进行集成验收。文中提供了可直接复用的“Prompt 模板”和自查清单，以及实战中常见踩坑问题的解答。带上这份施工指南，开启你的规范驱动开发之旅吧。
本文目录
- 全流程总览
- Step 1：写 proposal.md
- Step 2：写 design.md
- Step 3：写 tasks.md
- Step 4：逐任务驱动 AI 施工
- Step 5：集成测试与总验收
- 常见问题
- 结语：SDD 是一种可迁移的能力
一、全流程总览
Step 1 Step 2 Step 3 Step 4 Step 5
写 proposal → 写 design → 写 tasks → 逐任务驱动AI → 集成与验收
(why/what) (how) (order) (10个任务) (对照验收清单)
首先，在终端或编辑器中准备好项目目录骨架：
daily_report/
├── specs/
│ ├── proposal.md # Step 1 产出
│ ├── design.md # Step 2 产出
│ └── tasks.md # Step 3 产出
├── collector/ # 采集层（Step 4 产出）
├── generator/ # 生成层（Step 4 产出）
├── notifier/ # 推送层（Step 4 产出）
├── shared/ # 共享基础层（Step 4 产出）
├── tests/ # 单元测试 + 集成测试
├── main.py # 编排入口
├── config.yaml # 运行配置（含成员映射表）
└── .env # 密钥（不进 git！）
二、Step 1：写 proposal.md
打开 AI 对话窗口，使用以下指令模板（把 【】 里的内容替换为你自己的项目信息）：
我要做一个【项目一句话描述】。
背景痛点：【谁，每天/每周花多少时间做什么，带来什么问题】。
目标用户：【谁生产数据，谁消费数据】。
数据来源：【要对接哪些平台/API】。
请帮我产出 proposal.md，要求：
1. 按"目标层(why) → 范围层(what) → 验收层(done)"三层结构组织；
2. 范围层必须包含"本期不做什么"的明确排除项；
3. 验收标准必须可打勾，包含功能验收、性能验收、边界场景三部分；
4. 末尾附术语定义表；
5. 写完后逐条问我：哪些隐含决策你替我做了？我需要显式确认。
💡 心法提示：第 5 条是关键——让 AI 反过来逼你做决策，把“它可能猜错的环节”全部变成你明确的选项。
写完后自查（对照本系列的检查点）：
- 背景痛点有量化数字（如：每天浪费 15-30 分钟）。
- 用户画像清晰区分了生产者/消费者。
- 排除项至少 3 条，且锁死了 AI 最容易“贴心加戏”的地方（如：本期不做 AI 摘要）。
- 每条验收标准都能变成测试用例。
- 边界场景覆盖：空数据、限流/超时、Token 过期、非工作日。
三、Step 2：写 design.md
proposal.md 定稿后，进入架构设计阶段，继续发送指令：
基于 specs/proposal.md，帮我产出 design.md，要求：
1. 先给出架构选型及理由（理由必须能回溯到 proposal 的技术约束），
并用 ASCII 画出系统架构图；
2. 模块职责用三列表：文件 | 职责 | 不负责（"不负责"一列必须写）；
3. 定义层间数据模型（数据类字段、类型、注释），作为模块通用语言；
4. 定义各模块接口签名（函数名、参数类型、返回类型），标注章节号；
5. 关键技术选型写 ADR：背景、候选选项、决策、理由；
6. 非功能约束逐条工程化：错误处理对照表（场景→处理方式）、
安全清单、可运维性（日志格式/健康检查/配置方式）。
写完后重点自查两处：
- 每个模块的“不负责”列，是否锁住了 proposal 里的排除项？
- 错误处理表的每一行，是否都能对应 proposal 验收层的边界场景？
四、Step 3：写 tasks.md
架构蓝图敲定，最后来写施工单：
基于 specs/proposal.md 和 specs/design.md，帮我产出 tasks.md，要求：
1. 元信息：关联规范、任务总数、预计时间、执行策略；
2. 每个任务五要素：描述、输入（精确到 design.md 章节号）、输出、依赖、
验收标准（可打勾，含"单元测试通过"）；
3. 每个任务的交付物 = 实现文件 + 对应测试文件；
4. proposal 验收层的每一条（尤其是边界场景）都必须落到某个任务的验收标准里；
5. 末尾给执行顺序表：阶段划分、并行度、依赖图，
互不依赖的任务标注为可并行。
自查：
- 逐条核对
proposal.md验收清单，每条都有任务承接。 - 并行任务之间确实无共享文件（如 T3/T4/T5 三个采集模块互不干扰）。
- 任务粒度 = 一次 AI 会话能完成 + 一次验收能核对。
五、Step 4：逐任务驱动 AI 施工
按执行顺序表推进，每个任务用同一套指令模板。以 Task 2（共享基础层）为例：
请实现 Task 2（共享基础层）。
具体需求见 specs/tasks.md 中 Task 2 的描述及验收标准。
模块职责见 specs/design.md §2.4。
错误处理策略见 specs/design.md §6.1。
项目结构已按 Task 1 初始化完成。
请生成 shared/config.py、shared/logger.py、shared/errors.py、
shared/storage.py 及对应测试文件 tests/test_*.py。
完成后逐条对照 Task 2 验收标准自检，输出自检结果。
指令模板的固定套路（对应篇四解剖的四要素）：
- 指定任务编号 → AI 读
tasks.md获取描述与验收标准； - 逐项指引用章节号 → 数据模型、接口契约、错误处理精确投放；
- 声明已有资产 → 防止 AI 重复造轮子（如：声明 config 已实现）；
- 明确交付物 → 实现代码 + 测试代码。
每个任务完成后的固定动作：让 AI 自检验收清单 → 人工抽查关键条目（跑一遍测试、看函数签名是否与 §4.x 一致）→ 打勾确认，再进入下一个任务。
关键路径上的顺序绝对不能乱：T1 → T2 →（T3/T4/T5 并行）→ T6 →（T7/T8 并行）→ T9 → T10。
六、Step 5：集成测试与总验收
Task 9（main.py 编排）和 Task 10（集成测试）完成后，用 proposal.md 的验收清单做项目总验收。四种集成场景一个都不能少：
| 测试场景 | 预期结果 | 对应验收条款 |
|---|---|---|
| 正常：所有数据源可用 | 日报生成并推送成功 | 功能验收 |
| 降级：某个数据源超时 | 日报标注“数据获取失败”，其余正常 | 性能验收（严禁静默跳过） |
| 空数据：某成员无记录 | 对应板块显示“今日无记录” | 边界场景 |
| 全部失败：数据源全挂 | 不生成空日报，记录错误日志并告警 | 边界场景 |
上线前最后一件事：配置 Cron 定时任务，在正式放开推送前，先把“下一周的 18:00 自动触发”跑一遍 --dry-run 模式进行验证。
七、常见问题（FAQ）
Q1：AI 生成的代码偏离规范怎么办？ 不要“改代码将就”，而是回看规范：如果是 AI 理解错了，指出对应章节让它重做；如果发现规范本身没写清楚，先改规范再改代码——否则规范与代码会渐行渐远，SDD 就退化回了“Vibe Coding（瞎写）”。
Q2：规范写到多细才够？ 回到篇一的心法：改变系统行为的决策写进规范，只影响代码写法的交给 AI。拿不准时问自己：这条如果让 AI 猜，最坏会猜成什么样？ 如果猜错了你能接受，就不用写。
Q3：中途想加功能怎么办？
走变更流程：先改 proposal.md（范围层 + 验收层），再评估对 design.md 的影响，最后在 tasks.md 追加任务。三份文档同步更新，永远不让代码“领先于规范”。
Q4：每个任务都要写测试吗？ 要。测试是“任务完成”的可机器验证的证明，也是后续任务的安全网——如果 T2 的共享模块测试不通过，T3~T8 全都没有开工的意义。
八、结语：SDD 是一种可迁移的能力
回头看这个系列，我们真正练习的不是“做个日报工具”，而是一套人机协作的开发方法论：
proposal.md教你把模糊意图变成显性决策——这是产品能力；design.md教你先画地图再行军、给 AI 划边界——这是架构能力；tasks.md教你把蓝图拆成可验收的施工单——这是项目管理能力；- AI 只负责一样东西：在边界清晰的规范内，把代码一次写对。
工具会换代，模型会更强，但“把问题定义清楚再动手”这件事，永远是人的核心价值。
现在，打开你的编辑器，从写第一份 proposal.md 开始吧！
📚 系列导航
- 篇一：SDD 开发理念 —— 从“让 AI 写代码”到“让 AI 按规范写代码”
- 篇二：proposal.md —— 把模糊想法变成结构化规范
- 篇三：design.md —— 先画地图，再行军
- 篇四：tasks.md —— 把蓝图拆成 AI 可执行的施工单
- 篇五：实战篇 —— 从零搭建同款智能日报系统（本文）
(至此，「智能日报系统」SDD 从零到一系列已全部完结。如果这个系列对你有帮助，欢迎点赞、收藏、关注三连支持！)
