SDD 模式 AI Coding 实战感悟 — 数字员工 AI 项目开发总结

这几天我用 SDDSpec-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 周 【规模】中等 【技术栈】略保护具体技术选型 【角色】一人 五个角色需求 / 架构 / 任务 / 开发 / 测试