这几天，我用 SDD（Spec-Driven Development）模式完成了数字员工 AI 项目的长时间开发。这是我再一次完整跑通"从 spec → design → tasks → develop"的全流程。本文记录过程中的真实感悟、踩过的坑、可复用的方法，供自己和同行参考。

写在前面：为什么写这篇

SDD 模式这半年在 AI Coding 圈很火，但绝大多数分享只讲"怎么做"，不讲"做错了什么"。本文不是教程，而是复盘——记录我从零跑通一次 SDD 全流程后，真正沉淀下来的东西。

一、SDD 的本质：不是文档模板，是工作纪律

很多团队把 SDD 当成"四份文档模板"，但它的本质是工作纪律：

• 在写代码前强迫自己把模糊想清楚
• 在动手前强迫自己发现盲区
• 在每个阶段强迫自己停下来校验

这和传统敏捷"先跑起来再说"是对立的。SDD 适合的不是所有项目，但对"想清楚了再动手"的工程师来说，是质变工具。

二、四份文档的分工与时间投入

SDD 模式的核心是"先写文档，再写代码"。实际跑下来，我发现四份文档的性质、时间投入和迭代节奏完全不同。

1. spec.md：需求的锚点

spec.md 的本质是把模糊的需求变成精确的描述。写起来有点像流水线编程——逐条梳理功能点，逐句推敲措辞。

我的经验：至少花 1 天以上，而且不要闷头写，要和同事串讲一遍。串讲的过程会暴露你自己没想清楚的角落，别人一个问题就能让你发现某个功能点定义不清或者边界模糊。

关键经验：

【粒度控制】 - 单次 spec 不要贪大 - 大 spec 会导致 AI 在 develop 阶段上下文膨胀、注意力分散、偏离目标 - 把大需求拆成多个小 spec，每个聚焦一个明确的功能域 - 效果远好于一份大而全的文档 【迭代节奏】 - spec.md 我反复迭代了 3 次以上才稳定下来 - 不是写不好，是每次串讲都能发现新问题 - 不要追求一次写对，但要在动手前稳定

2. design.md：最耗时的环节，也是最重要的环节

design.md 是整个流程中时间投入最大的环节。我花了大约 1.5 到 2 天，而这还是建立在我对设计文档中提到的技术栈比较熟悉的前提下。

⚠️关键提示：如果 design 里引用了你不熟悉的技术，读懂和理解这些技术本身就要额外花大量时间——这不是"写文档"的时间，是"学习"的时间。

design.md 我反复校验了 6 次以上。每一次校验都是在回答一个问题：

“这个方案真的能落地吗？”

我会检查：

• 技术选型是否合理
• 模块边界是否清晰
• 数据流是否自洽
• 异常路径是否有兜底

6 次不算多，因为每次校验都会发现新的问题——有些是逻辑漏洞，有些是遗漏了边界条件，有些是某个技术方案在实践中根本行不通。

最重要的教训：

design.md 最终交付的版本和最初写的版本差异很大。这是正常的，不必追求一次写对。但差异积累到一定程度后，需要另起一个 session，把 spec 和 design 放在一起重新对齐。否则 spec 说的是一套，design 按另一套设计，develop 阶段就会左右互搏。

3. tasks.md：最快但也最容易出问题的环节

tasks.md 本身写起来比较快，因为有了 spec 和 design 做基础，任务拆分基本是水到渠成的。

我的做法：

【按 phase 划分】 - 每个 phase 是一个可验证的里程碑 - 完成一个 phase 后应该能跑起来看到效果 - 而不是等到最后才联调 【加 checklist】 - 每个 phase 里加一个功能开发 checklist - checklist 的作用是"校准" - 开发到中期以后，你会忘记哪些功能已经做了 - checklist 就是你随时回头看的导航仪 - 也是和 AI 沟通任务完成度的标尺

三、开发过程中的动态校准

1. 文档不是一次性交付物，而是活的

进入 develop 阶段后，前面三份文档（spec、design、tasks）不是"写完归档"的死文档，而是需要持续验证和校准的活文档。

开发过程中会暴露设计阶段没想到的问题——前后端联调的数据格式对不上、前端样式在不同浏览器表现不一致、某个 API 的响应时间超出预期——每一个实际遇到的问题都应该反过来检查：

是设计遗漏了，还是实现偏离了设计？

2. 反馈的完整性决定 AI 的有效性

这是一个容易被忽视的细节：你给 AI 的反馈信息必须完整。

举个真实例子，我遇到过一个前端 Bug：

【最初反馈】 "消息发送有问题" = 太模糊，AI 给的几个方向都没命中 【改进后反馈】 "嗯，当前成功创建 session 了。 我刚发送消息后，消息闪现一下后消失了， 帮我检查下。" = 把上下文（成功创建了 session） = 触发动作（发送消息） = 现象（闪现后消失） = 都描述清楚后，AI 很快定位到了是 WebSocket 消息处理的问题

教训：

AI 不像人类同事可以通过旁边观察你的屏幕来推断上下文。它的上下文完全来自你的文字描述。你少说一句，它就少知道一个约束，给出的方案就可能跑偏。

养成习惯："把现象、上下文、预期行为、实际行为都说清楚"的反馈习惯，效率会高很多。

四、一个人跑全流程的真实感受

SDD 模式下，一个人实际上承担了五个角色：

1. 需求分析师（写 spec） 2. 架构师（写 design） 3. 技术经理（写 tasks 分配任务） 4. 开发工程师（写代码） 5. 测试工程师（验证功能）

这是一条完整的 E2E 流水线，一个人从头干到尾。

好处

- 没有沟通成本 - 没有交接损耗 - 一个人的脑子里装着全部上下文 - 从需求到实现一以贯之 - 不存在"需求和实现之间隔了三层传话"的信息损耗 - 做出来的东西和最初想的东西高度一致

但累也是真的累

传统模式下，这些角色由不同的人分担，每个人只需要专注自己的环节。而 SDD 模式下，你一个人要在五个思维模式之间频繁切换——

上午在写 spec 想的是"用户到底要什么"
下午在写 design 想的是"这个架构能不能扛住并发"
晚上在 debug 想的是"这个样式为什么偏了 3 像素"

认知负荷非常高。

一个反直觉的事实

AI 并不会真正减轻你的认知负荷——它改变的是负荷的性质。

你不再是"写代码的人"，而是变成了"审代码的人 + 改需求的人 + 定架构的人 + 排任务的人 + 调样式的人"。

AI 帮你把打字量降下来了，但决策量和判断量反而上去了。每一个 AI 生成的方案，你都要判断对不对、好不好、有没有隐患。

这不是偷懒，这是换了一种方式的高强度工作。

五、给后来者的 5 条建议

如果你也想尝试 SDD 模式的 AI Coding，我的建议是：

1. 不要跳过 spec 和 design 直接写 tasks

这是最容易犯的错——觉得"我都想好了，直接开干吧"。

但"想好了"和"写清楚了"之间隔着一道巨大的鸿沟。写 spec 的过程就是在逼你自己把"觉得想清楚了"变成"真的想清楚了"。

2. design 阶段的校验要反复做，不要怕花时间

我花了 6 轮校验，到最后还在发现问题。

这不是效率低，这是在把问题消灭在纸面上而不是代码里。纸面上的问题改一句话的事，代码里的问题可能要改一整天。

3. tasks 的每个 phase 一定要可验证

如果做完一个 phase 你没法跑起来看到效果，说明这个 phase 的边界划得不对。

不可验证的 phase 会导致问题累积到最后集中爆发，那时候排查难度是指数级的。

4. 养成完整反馈的习惯

遇到 Bug 时，把"做了什么、期望什么、实际什么、有什么上下文"完整地告诉 AI。

你省下的那几行字的描述，可能会让你多花几个小时在来回试错上。

5. 接受"一个人是全栈流水线"的现实，但要知道自己的精力边界

一个人跑全流程适合中小型项目（比如几周以内的开发量），到了一定复杂度后，还是需要人来分担——哪怕只是找同事串讲一遍 spec 和 design，也能帮你发现盲区。

六、SDD 模式的真实定位

SDD 模式不是银弹，但它确实是目前把"AI 写代码"这件事从"碰运气"变成"有纪律"的最有效方法。

【它的优势】 - 把模糊需求逼成精确描述 - 把"想到"和"写清"拉开距离 - 把设计阶段的漏洞消灭在纸面上 - 把任务拆分成可验证里程碑 【它的代价】 - 前期文档投入大 - 一个人承担多个角色 - 认知负荷高 - 适合中小项目 【它的本质】 - 不是文档模板 - 是工作纪律 - 是"先想清楚再动手"

它累，但它可靠。

七、给未来的自己

这次跑通 SDD 全流程，最大的收获不是学会了某种新工具，而是建立了一种新的工作纪律：

1. 模糊的需求不能进 design 2. 不熟悉的技术不能进 design 3. 没有可验证里程碑的 phase 不能进 tasks 4. 不完整的反馈不能给 AI 5. 一个人 = 全栈流水线 = 知道边界

下次再开新项目，我会：

【第一步】花 1 天写 spec + 串讲 【第二步】花 2 天写 design + 6 轮校验 【第三步】花 0.5 天拆 tasks + 可验证 phase 【第四步】develop 阶段保持反馈完整性 【第五步】完成后复盘 + 更新 SDD 模板

八、思维模型附录

【本文使用的思维模型】 1. 第一性原理：从本质理解 SDD = 工作纪律 2. 系统思维：四份文档是有机整体，不是孤立模板 3. 反馈闭环：AI 上下文 = 你的反馈质量 4. 边界管理：一个人 = 多个角色 = 知道极限 5. 长期主义：把"碰运气"变成"有纪律"

九、给读者的两个问题

如果你也在用 SDD 模式，欢迎思考：

1. 你在 spec 阶段最长花过多少时间？ 我：1 天 + 3 次迭代 2. 你在 design 阶段发现的最大问题是什么？ 我：技术选型在实践上行不通

最后一句话：

工具不会让你变强，纪律才会。SDD 不是工具，是纪律。

附录：数字员工 AI 项目简介

简要说明项目背景，帮助读者理解本文讨论的具体场景。

【项目名】数字员工 AI（化名） 【周期】X 周 【规模】中等 【技术栈】略（保护具体技术选型） 【角色】一人 = 五个角色（需求 / 架构 / 任务 / 开发 / 测试）