AI

每天吃透一个 AI 知识点 — SDD（规范驱动开发）

Posted Cola🌀

转载：小红书 AI产品赵哥

前言 🔖

相信很多宝子都幻想过这样的场景：对着电脑说一句 “帮我做一个类似小红书的 App”，然后端起咖啡，几分钟后，一个完美的 App 就自动生成了。

梦想很丰满，但现实往往很骨感。你很可能会得到一个四不像的、充满 Bug 的半成品。然后你开始抓狂地跟 AI 来回拉扯：“这里不对，那里要改，哎呀你怎么又理解错了！”

问题的核心在于，我们和 AI 之间，缺少了一个至关重要的中间人 —— 一份清晰明确且无歧义的施工图纸。

而我们今天要深入探讨的，就是一种强制我们和 AI 先画好图纸再施工的开发方法论，它的名字叫做 —— SDD（Specification Driven Development，规范驱动开发）。

　　

一、SDD 是什么？ 🔖

为什么 AI 编程没它不行？ 要理解 SDD，我们先来看一个生活中的例子：装修房子。

不使用 SDD 的随缘装修：

你找到一个装修队，对工头说：“师傅，帮我把这房子装成现代简约风，温馨一点。”

工头点点头，然后就开工了。结果可能是：

  • 插座位置不对，挡住了你新买的柜子。
  • 墙面颜色太深，和你想要的 “温馨” 感觉完全不搭。
  • 厨房动线设计不合理，做个饭像在跳障碍赛。

你不得不让他们返工，敲墙、改电、重新刷漆……

使用 SDD 的图纸装修：

在开工前，你和设计师坐下来，花时间反复沟通，最终敲定了一套完整的设计方案和施工图纸。图纸上精确地标注了：

  • 每一个插座、开关的位置和高度。
  • 每一面墙要用的油漆色号。
  • 橱柜、家电的尺寸和摆放位置。
  • 详细的材料清单和工期计划。

工头拿到这份图纸后，只需要按图施工。虽然前期沟通设计的时间长了，但整个施工过程会非常顺畅，极少出现返工，最终效果也大概率符合你的预期。

💡 SDD 的核心思想，就是先对齐，再开发。

它强制要求在写下任何一行代码之前，开发者（无论是人还是 AI）必须首先与需求方（你）共同确认一份详尽的规格说明书（Specification）。这份说明书不是泛泛地说 “要做什么”，而是要细致入微地描述每一个功能的具体规格。

在 Vibe Coding 时代，这一点尤为重要。因为 AI 虽然强大，但它不会读心术。你给它一个模糊的需求，它就会用自己脑补的细节去填充，而这些细节很可能不是你想要的。

引入 SDD，就相当于在你的 “一句话需求” 和 AI 的 “一通乱写” 之间，加了一个强制确认环节。这个环节会产出一系列结构化的文档，比如：

  • 需求说明（Proposal）：为什么要做这个功能？背景是什么？
  • 功能规格（Specs）：这个功能在各种情况下应该如何表现？
  • 设计方案（Design）：技术上怎么实现？用什么框架？
  • 开发计划（Tasks）：具体要分几步来做？每一步干什么？

你和 AI 逐一审核并确认这些文档后，AI 才会真正开始写代码。这样做的好处是巨大的：

  1. 极大提升开发质量：需求在源头就被理清了，避免了后期因理解偏差导致的大量返工。
  2. 强制你深度思考：SDD 会引导你把自己的模糊想法具体化，很多你自己没想到的细节，都会在这个过程中被挖掘出来。
  3. 让 AI 更懂你：AI 拿到的是结构化、无歧义的任务指令，它的思考有了清晰的边界，自然就能写出更符合你要求的代码。

别以为这个过程会浪费时间和 Token。相比于需求不明确导致的来回折腾，前期在写文档上投入的时间，绝对是最划算的投资。

　　

二、OpenSpec 登场：AI 时代 SDD 最佳实践 🔖

目前在 Vibe Coding 领域，有很多框架都在尝试实践 SDD，其中 OpenSpec 生态中的理念和工具链做得非常出色。

OpenSpec 本身是一个能让你在本地终端与大语言模型交互，并让它直接执行代码的开源项目。而社区围绕它，发展出了一套高效的工作流和方法论，完美地体现了 SDD 的精髓。

假设我们的需求是：“帮我做一个 AI 对话机器人”。

🔹第一步：需求探索与澄清 (Explore)

很多时候，我们自己也想不清楚所有细节。这时候，你不需要憋着，直接把你的初步想法告诉 AI，然后启动**探索模式**。

在 OpenSpec 的工作流中，你可以使用 `explore` 模式，然后输入：

帮我做一个 AI 对话机器人，实现基本功能：我输入问题，AI 给出答复。

AI 不会立刻开始写代码。相反，它会像一个产品经理一样，反过来向你提问，引导你把需求细化：

AI: 好的，收到！为了更好地实现您的需求，我有几个问题需要和您确认：

1. 前端界面：您希望这个机器人运行在网页上，还是一个桌面应用，或者只是在命令行里？
2. AI 模型：您打算使用哪家的大语言模型？比如 OpenAI 的 GPT 系列，还是某个国产模型？
3. 技术架构：您对后端技术栈有什么偏好吗？比如用 Python 的 Flask 还是 FastAPI？

你回答：“我想要一个网页界面，用国产大模型，后端用 Python FastAPI。”

AI 收到你的反馈后，可能会给出一个初步的设计方案，然后继续追问：

AI: 明白了。基于您的选择，我建议采用 Vue.js 做前端，FastAPI 做后端。关于细节，还有几个问题：

1. 具体模型：您想接入哪个具体的国产模型？（比如文心一言、通义千问等）
2. 对话历史：需要支持多轮对话，让机器人记住我们之前的聊天内容吗？
3. 流式输出：您希望机器人的回答像 ChatGPT 那样一个字一个字地 “吐” 出来（流式输出），还是等它全部想好了一次性显示？

看到这个过程了吗？你不再是一个人苦思冥想，而是把 AI 变成了一个帮你梳理需求的智能伙伴。很多你没想到的问题，它都会主动抛出来。

　　

🔹第二步：生成规范文档 (Propose)

当你和 AI 通过多轮对话，把需求细节基本敲定后，就可以执行下一步了。在 OpenSpec 工作流中，这对应 propose 模式。

AI 会把你俩刚才讨论的所有内容，自动整理成一套结构化的规范文档。它会在你的项目里创建一个文件夹，比如 [2024-05-21]-AI-Chatbot-Feature，里面包含了以下几个核心文件：

  • proposal.md：需求说明书。它会用 “为什么做（背景）、做什么（目标）、怎么做（概览）” 的结构，宏观地描述这次开发任务。
  • design.md：技术设计方案。详细说明前端用什么框架、后端用什么框架、数据库选型、API 接口设计、调用哪个 AI 模型等技术细节。
  • specs/：一个专门的功能规格文件夹。这是 SDD 的精髓所在。AI 会把 proposal.md 里提到的每一个功能点，都单独拎出来写一份详尽的规格说明。
    • 比如，specs/streaming_output.md 这个文件里会详细描述 “流式输出” 这个功能。它可能会用当…… 则……（Given-When-Then）的句式来写，这种格式 AI 最喜欢了：
      • 场景：用户发送消息后成功获取流式响应
        • 当 (Given) 用户在前端页面输入问题并点击发送；
        • 且 (And) 后端成功调用了国产大模型的流式接口；
        • 则 (Then) 前端页面应该逐字显示模型返回的内容，直到接收到结束标记。
  • tasks.md：开发任务清单。AI 会根据上面的文档，自动生成一个详细的开发计划，把整个项目拆解成一个个具体的、可执行的小任务，比如 “1. 初始化 FastAPI 项目”、“2. 编写前端页面基础结构”、“3. 实现调用大模型 API 的接口” 等等。

到这一步，你作为需求方，需要做的就是仔细阅读这些 AI 生成的图纸。如果有任何不满意的地方，可以直接修改文档，或者让 AI 重新生成，直到你完全确认为止。

　　

🔹第三步：执行开发 (Apply)

当所有规范文档都确认无误后，最激动人心的时刻到了。你只需要执行 apply 命令。

AI 此时会：

  1. 完整地阅读 tasks.md 里的任务清单；
  2. 对于每一个任务，它会回头去查找 design.md 和 specs/ 文件夹里对应的详细要求；
  3. 然后，它就严格按照规范，一步一步地编写代码、安装依赖、创建文件。

因为所有的思考和决策工作都在前两步完成了，这一步的 AI 几乎不会自由发挥。它的任务就是把图纸变成实体建筑。

整个过程你都可以在终端里看到，AI 会告诉你它正在做什么，完成了哪一步。几分钟后，它甚至可能会自己运行测试，并告诉你 “开发完成，请验证”。

　　

🔹第四步：归档 (Archive)

功能开发完成并验证无误后，最后一步是归档，对应 archive 命令。

这一步会做两件很重要的事：

  1. 任务归档：把这次开发任务的整个文件夹（[2024-05-21]-AI-Chatbot-Feature）移动到一个叫 archive/ 的历史文件夹里，相当于把做完的项目存起来。
  2. 知识沉淀：这是最关键的操作。它会把你这次新增或修改的功能规格文件（specs/ 里的内容），合并到项目根目录下一个总的 specs/ 文件夹中。
    • 如果是新功能：直接把新功能的规格文件复制过去。
    • 如果是修改旧功能：它会智能地找到旧的规格文件，用新的描述去更新它，而不是简单地追加。

这样做的目的是，让项目根目录下的 specs/ 文件夹，永远保持着整个系统当前最新、最全的功能规格说明。这就像一本活的、永远保持更新的系统说明书。当未来要新增或修改功能时，AI 可以先阅读这本说明书，更好地理解现有系统的全貌。

至此，一个完整的、由 SDD 驱动的 AI 开发流程就走完了。

　　

三、SDD 思想的本质与价值

你可能会觉得，这套流程好复杂，又是文档又是归档的。但请记住，复杂的是工具的实现，而它背后的思想却很朴素也很强大。

SDD 的本质，是软件工程中 “需求明确化” 思想在 AI 时代的落地。它承认并试图解决一个根本矛盾：人类的思维是模糊、跳跃和感性的，而机器的执行是精确、线性和逻辑的。

SDD 就像一个翻译器和稳定器，它通过一套结构化的流程，把我们模糊的想法，翻译成机器能精确理解的指令。

即便你暂时不用这些自动化工具，也应该在与 AI 协作时，在脑中建立起 SDD 的思维模型。在让 AI 写代码前，先试着自己回答这几个问题：

  • Proposal：我为什么要做这个？
  • Specs：它具体在什么情况下应该表现出什么行为？
  • Design：技术上大概要怎么实现？
  • Tasks：我要分几步来做？

当你能把这些问题想清楚，并用文字描述出来再交给 AI，你会发现它的智商和情商都提高好几个档次。

你不需要看那些文档，AI 会看。这句话点出了精髓。在人类开发中，很多开发者懒得写文档，也懒得看文档。但在数字世界里，AI 是最听话的员工，你给它提供了结构化的规范文档，它就会严格遵循，给你带来高质量的回报。

SDD 不会随着模型升级而消失。因为模型会变聪明，但它永远无法 100% 猜透你的心思。只要人机协作存在，这种“先对齐，再执行”的范式就永远有价值。