SDD实践：用OpenSpec与SuperPowers把AI编程变成规范驱动的工程

先说一个最近的感受：2025 年 AI 编程圈子的关键词，已经从"vibe coding"悄悄变成了"带约束的编码"。我自己也是从"把需求往对话框一扔，让 AI 自由发挥"开始玩起的，爽是真爽，但项目一旦过了两三个模块，问题就来了——代码倒是能跑，可谁也说不清某个功能当初为什么要这么写，AI 改了一处逻辑，另一处的行为悄悄变了，需求文档和代码之间仿佛隔了一堵墙。后来我认真试了 SDD（Specification-Driven Development，基于规范编程），配合 OpenSpec 管规范文件、SuperPowers 给 AI 装技能，才算把"能写代码的 AI"变成了"按契约写代码的 AI"。这篇文章不堆概念，就讲讲我是怎么把这套组合落地到真实项目的，以及踩过的那些坑。

适合什么人看：正在用 Claude Code、Cursor、opencode 这类 AI 编程工具写真实项目，对代码质量和需求可追溯性开始有要求的开发者。如果你只想让 AI 跑通 Demo，可能用不上这套；但如果你要交付的东西需要维护、需要给别人看、需要三个月后还能改得动，那 SDD 这条路径值得认真试一次。

1. 为什么"先写规范再写代码"正在成为 AI 编码的新范式

1.1 从 vibe coding 的狂欢到失控

vibe coding 最典型的场景是：你打开一个对话窗口，把需求用大白话描述一遍，AI 噼里啪啦生成一堆代码，你复制粘贴运行，发现报错就继续让 AI 修，来回几次项目跑起来了。这个过程的爽感来自"零门槛"，但也埋了一个很深的雷——你几乎没有留下任何有意义的需求决策记录。

一旦项目开始膨胀，比如从单个脚本变成前端、后端加数据库的服务，对话式开发就开始失控。我印象很深的一次：让 AI 给内部工具加一个"数据过滤"功能，它自动把过滤逻辑塞进了原来的查询函数里，结果别的页面也调用了这个函数，整页数据少了一半。功能本身没错，但它的副作用完全超出了我提的需求边界。

这个问题的根源不是 AI 笨，而是需求上下文没有边界。对话天然是线性的、易丢失的，AI 在每一轮只能基于最近的聊天记录去猜，而代码库是一个高度耦合的结构。要让它在一个复杂的系统里做局部修改，必须有一个比"聊天记录"更可靠的东西来传递需求上下文。这就是规范文件。

1.2 SDD 是什么：规范不是文档，而是开发过程的"第一公民"

SDD，Specification-Driven Development，直译过来是基于规范编程。它和 TDD（测试驱动开发）经常被放在一起说，但两者约束的东西不一样：TDD 用测试约束"代码行为"，SDD 用规范约束"需求边界和验收结果"。

一个典型 SDD 循环是这样的：

1. 澄清需求，搞清楚"到底要解决什么问题"；
2. 把需求写成结构化的规范文件，明确功能范围、任务拆分、验收标准；
3. 让 AI 或人工按规范实现，遇到偏差先改规范再改代码；
4. 对照验收标准检查结果；
5. 根据实际代码变更反向更新规范，保证它不腐化。

很多人一听"写规范"就本能抗拒，觉得这是重型流程、是文档负担。但这里的关键区别在于：传统文档是写给"人"看的，写完就躺在 Wiki 里发霉；SDD 里的规范文件是写给"AI 执行者"看的操作契约，它会直接参与每一次代码生成。换句话说，规范不是项目的附加产物，而是开发过程中的第一公民。

1.3 这套范式解决的真实痛点

我之前在团队里试着总结过，SDD 真正解决的痛点是这三个：

• 需求反复横跳：产品说"加个筛选"，今天加，明天又改范围。有了规范的版本记录，每一次变更都对应到 spec 文件的某次修改，AI 不会再凭印象实现旧需求。
• 代码和需求对不上号：没有规范时，你很难回答"这个字段为什么存在"。有了 spec，你可以从代码反查到具体某条验收标准。
• 多人协作时语义不一致：规范就是团队间的共同语言。AI 编码工具再强，它也不会主动和别人对齐，只有一份显式的规范才能充当这个对齐锚点。

说白了，SDD 的本质是给 AI 的生成本能装一个"边界围栏"。围栏立在哪、能做什么不能做什么，全都写清楚，剩下的才是发挥空间。

2. OpenSpec：把"需求讨论"固化成仓库里的规范资产

2.1 OpenSpec 在整套工具链里的位置

光有 SDD 理念还不够，规范放哪、按什么格式写、怎么写才能让 AI 高效读取，这需要一个具体工具来承载。OpenSpec 就是干这个的。

它本质上是一个规范生命周期管理 CLI，专门为 AI 编码时代设计。它不会替你想需求，但会帮你把需求讨论的产物变成一套有结构的、可版本化的、能被 AI 直接读取的规范文件。你可以理解成：Git 管代码版本，OpenSpec 管规范版本，两者并存于同一个仓库，代码提交和规范提交天然关联。

这比在 Confluence 之类的地方开一个"需求文档"页面要强太多。因为规范文件直接躺在代码仓库里，AI 编码工具在生成代码前能通过文件路径定位到它，不需要任何额外的检索步骤。

2.2 规范仓库的文件结构与生命周期

我用了 OpenSpec 之后，习惯把规范仓库分成两类区域：一类是项目级长期规范，描述整个项目的架构原则、编码约定、常用术语；另一类是功能级提案，描述某个具体功能的需求和任务。

功能级提案的文件生命周期大致是这样的：

1. 新建提案（proposal）：包含问题背景、目标描述、范围内/范围外；
2. 任务拆分（tasks）：把功能拆成 AI 可执行的若干小任务；
3. 验收标准：每条标准都必须能判定"真或假"；
4. 实现完成后，提案进入"已实现"状态，但它不会消失，而是继续代表这块功能的当前契约；
5. 后续如果要改这个功能，不是重写提案，而是在原提案上追加变更说明，保留完整演进记录。

为什么规范要放在 Git 仓库而不是需求管理平台？因为 Git 天然拥有 Diff、历史回滚、分支评审这些能力。AI 可以直接通过 git diff 看到"这次需求相对上次改了什么"，从而精确实施变更。

2.3 安装与初始化：从零到第一个规范文件

OpenSpec 的安装流程属于典型的"跟着官方仓库 README 走就行"型，一般通过你常用的 JavaScript 包管理器全局安装一个 CLI，然后在项目根目录执行初始化命令。版本迭代快，具体包名和命令常会变化，我这里只说你一定要理解的核心动作：

bash复制# 伪代码级示意，实际包名/命令以官方仓库文档为准
npm install -g <openspec-cli包名>
openspec init

初始化之后，项目根目录会多出一个 specs 目录，里面通常内置了一份 README，说明目录约定、状态定义、书写模板。第一次打开那个目录的时候，你可能会觉得"就这么点东西？"，但请相信我，真正价值不在目录本身，而在"你开始往这个目录里写提案"这个动作。

我自己的做法是：初始化后先去给项目写一份"项目级规范"，把技术栈、目录约定、哪些模块不能乱动、数据库命名风格等写清楚。这份文件是后面所有功能提案的底座，AI 每次开工前先读它，比你在 prompt 里反复强调一百遍技术栈都管用。

2.4 从需求到规范：一条典型的记录长什么样

空谈结构容易虚，直接看一个简化示例。这是我给内部工具写的一个需求提案的骨架：

markdown复制# 提案：导出报表功能

## 背景
数据看板目前只能在线查看，业务方需要将明细数据导出到本地做二次分析。

## 目标
用户点击"导出"按钮后，根据当前筛选条件生成 CSV 文件并下载。

## 范围
- 本期只做 CSV 格式，不做 Excel
- 只支持按当前筛选条件导出，不支持自定义列
- 不做定时导出

## 任务
1. 在工具栏增加"导出"按钮
2. 实现后端导出接口，接收筛选条件并生成 CSV
3. 前端调用接口并触发下载
4. 超过 10 万行时给出提示，避免内存溢出

## 验收标准
- 用户选中日期范围和部门后点击导出，下载的文件只包含筛选后的数据
- CSV 文件首行为中文字段名
- 文件编码为 UTF-8，Excel 打开中文不乱码
- 导出期间页面不假死
- 超过 10 万行时提示"数据量过大，请缩小范围"

注意验收标准的写法：不是"导出功能要好用"这种模糊描述，而是每一条都能跑一遍看"是/否"的判定句。AI 实现完之后，我们可以拿着这份标准逐条打勾，哪些过了、哪些没过一目了然。

3. SuperPowers：给 AI 助手装上一套"可插拔技能库"

3.1 SuperPowers 解决的是什么层面的问题

有了 OpenSpec 管规范，AI 知道"要做什么"，但另一个问题冒出来了：AI 面对一个任务的时候，往往不知道用什么方法去做。

举个例子，你让 AI 修一个偶现的 bug，它最常见的反应是盯着代码看几秒，然后凭猜测改一处地方。多数时候能蒙对，但复杂问题下它就会反复试探，甚至越改越糟。人类工程师在调试复杂问题时有一套方法论：先复现、再二分定位、打日志验证假设、改一处测一处。AI 不是不会这套方法论，而是如果没有人提示，它默认不会激活这套流程。

SuperPowers 就是来解决这个问题的。它是一套开源的 AI 技能包，把专家级的工作流程封装成一个个"技能（skill）"文件。每个技能不是一个 prompt 模板，而是一本"操作手册"：包含目标、适用时机、步骤、注意事项，甚至附带的脚本和参考材料。AI 在遇到对应任务时，会读取这份手册，然后按里面的流程执行。

3.2 技能包的结构：SKILL.md 入口与按需加载

SuperPowers 的技能包采用了一个很聪明的设计：每个技能是一个目录，入口文件固定叫 SKILL.md，里面是 YAML 元信息加正文描述；目录下还可以附带 references、scripts、templates 等子目录，存放详细资料和可执行脚本。

AI 在会话开始或遇到任务时，通常只读取每个技能的 SKILL.md 入口文件，快速判断"这个技能适不适用当前情况"。一旦决定使用，才会去加载 references 里的详细内容和脚本。这相当于给 AI 建了一个"知识库的索引层"，既不会一上来把整个技能库的几万字全部灌进上下文，又能在需要时快速调取最关键的细节。

这个设计对我来说是决定性的。我最早尝试过把一堆方法论文档塞进系统提示词里，结果上下文被撑爆，AI 反而变蠢。SuperPowers 这种"先看索引、按需取用"的方式，才是技能类插件在上下文受限环境下的正确打开方式。

3.3 下载与接入：把技能库变成 AI 的肌肉记忆

SuperPowers 的获取方式很简单，就是去它的开源仓库克隆下来，然后把 skills 目录放到你所用 AI 工具的技能读取目录里。以我用的支持 Agent Skills 机制的编程工具为例，路径大概是这样的：

bash复制git clone https://github.com/obra/superpowers.git
# 把技能目录复制或软链接到 AI 工具的 skills 目录，如 ~/.claude/skills/

不同工具的技能目录位置不一样，安装完后重启会话验证一下：如果你在对话里提到某个领域的问题，AI 开始输出类似"让我先加载调试技能"的行为，说明技能已经生效。

我自己的建议是别一把梭全量启用所有技能。技能装多了也会造成选择困难，AI 有时候会纠结于"该用哪个技能"，反而降低了响应速度。我实测下来，优先启用这几个就够覆盖大部分日常开发：

3.4 验证技能是否生效的土办法

很多人装完技能不知道有没有用，我教一个土办法：给 AI 一个模糊需求，比如"帮我加一个把列表数据下载下来的功能"，然后看它的反应。

没有技能时，AI 会直接问一句或干脆开始写代码；有 Brainstorming 技能时，它会进入澄清模式，主动询问数据格式、下载量级、权限控制这些边界问题。如果你看到一个 AI 开始"像产品经理一样追问需求"，恭喜你，技能包生效了。

4. 一套可落地的 SDD 工作流：从模糊想法到可验收功能

4.1 环节总览与角色分工

前面分别讲了 OpenSpec 和 SuperPowers，现在把它们串成一条完整流水线。我自己在真实项目中跑顺的工作流是五个环节：

澄清 → 规范 → 实现 → 验证 → 同步

用表格理清每个环节里人和 AI 的分工：

这个方法论的关键在于：OpenSpec 负责"知道要做什么"的层面，SuperPowers 负责"怎么做才专业"的层面，人负责最后拍板和兜底。三个角色各司其职，才不会把压力全堆在 prompt 上。

4.2 实战案例：给内部工具增加"导出报表"功能

用一个我最近真实做过的需求来走一遍流程。场景：内部数据看板，用户希望把筛选后的明细数据导出成 CSV。

第一阶段，我没有直接让 AI 写代码，而是让 AI 用 Brainstorming 技能帮我澄清需求。我给的原始输入只有一句话"用户想导出数据"，AI 主动追问了这些问题：

• 导出格式是 CSV 还是 Excel？中文表头是否可以接受？
• 导出的数据范围是当前筛选后的结果，还是全量？
• 数据量大到多少需要做保护？
• 老版本的浏览器是否要兼容？

这些问题大部分我有答案，但"数据量保护"这个点我从没想过。这就是技能包带来的边际价值——它把资深工程师的提问习惯转移到了 AI 身上。

第二阶段，我把澄清结果交给 AI，让它按 OpenSpec 的模板生成提案、拆分任务、写验收标准。就是上一节展示的那个 spec 文件。我审阅时删掉了"支持自定义列"这条，因为第一版先不做，AI 把它归入"范围外"并写进了 spec。

第三阶段，AI 在实现前先读了项目级规范，确认了技术栈和数据库访问层约定，然后按 spec 的任务顺序逐项实现。因为任务是按"按钮 → 后端接口 → 前端调用 → 大数据量保护"拆分的，每一步的提交信息我都会让它关联到具体任务编号。

第四阶段，验证。我没有直接信 AI 的"测试全通过"，而是手动按验收标准逐条验了一遍：切了几个筛选条件导出、用 Excel 打开看中文是否乱码、故意选了个超大日期范围看拦截提示。果然发现一个问题：CSV 文件里超过 32767 行时，Excel 打开会截断。于是把这个限制补充进了验收标准，让 AI 在下载时同时输出一个拆分文件。

这个案例里最值得品味的不是哪一步代码写得漂亮，而是：一旦需求和验收标准被写进了规范文件，中途所有变更都变得有据可查。后面产品经理再说"导出这里还要加个 Excel 格式"，我们直接改 spec 里的范围说明，再走一遍流程就行。

4.3 每次交互的"输入-产物-检查点"

很多人用了 SDD 之后还是觉得乱，是因为没有建立"交互检查点"的习惯。我给自己定了一套硬规则：

• 每进入一个任务，必须先给 AI 提供三样东西：当前任务编号、对应的 spec 文件路径、完成标准。没有这三样就不开工。
• AI 完成一个任务后，必须输出三样东西：改了哪些文件、哪些验收标准已满足、哪些存在偏差或风险。
• 人必须有一个最小检查动作：至少看一眼 git diff，确认改动范围没有超出 spec 的任务边界。

这套动作看起来很繁琐，但它能避免大多数"AI 自作主张"问题。有一次 AI 为了完成"导出按钮"顺手重构了路由文件，如果我没有检查 diff 的习惯，这个改动就混进提交里了。

4.4 为什么看似慢，整体反而更快

这套流程最容易被吐槽的点是"写规范太慢了，AI 直接写早就完事了"。我的实测感受是：第一两天确实慢，因为你要适应全新的工作方式；但一旦项目进入稳态，速度会反超。

原因很简单：AI 生成的代码如果不设约束，会以极高速度制造"看起来完成但隐藏着边界问题"的代码，而这些代码的返工成本是指数级的。规范驱动的核心收益不是让 AI 写得更快，而是把返工控制在最小范围。就像装修房子，画图纸那几天看起来耽误工期，但你不画图纸直接让工人进场，砸墙改水电花的冤枉钱更多。

5. 落地过程中的关键坑：规范漂移、上下文损耗和信任边界

5.1 坑一：AI 不按规范走，出现规范漂移

SDD 落地第一个容易踩的坑，是 AI 写着写着就不按规范来了。最常见的表现：spec 里明确写了"本期只做 CSV，不做 Excel"，AI 实现时觉得"顺便把 Excel 做了也不难"，于是真的加了 Excel 导出功能。

听起来像是 AI 太勤快，但这在工程上是灾难：新增的功能没有经过验收、文档没有更新、后续维护负担凭空多了一块。

我试过各种阻止办法，最有效的是两招组合：第一，在 spec 里专门写一个"范围外"小节，把所有不做的事明确列出来，AI 看到这个列表后会把它理解为禁令而不是建议；第二，给 AI 的实现指令里加一句固定话术："只允许完成 tasks 中列出的内容，任何额外的功能增强都不允许，请在完成时自查 scope。"测试下来，规范漂移的概率能降低一大半。

5.2 坑二：规范太长，上下文爆炸

SDD 用得越久，规范文件越积越多。如果你贪心，把所有规范一次性塞进 AI 的上下文，它反而会"读不完"、"读不全"，甚至在处理当前任务时引用了过时规范。

解决思路是给规范分两级：索引级和详细级。

索引级规范是一份简短的项目规范索引，列出"哪个模块对应哪个 spec 文件"，控制在 500 字以内，常驻 AI 上下文。详细级规范是具体的功能提案和验收标准，只有在处理对应任务时才加载。

我在 OpenSpec 目录里加了一个 MAP.md 文件，职责就是充当索引。AI 每次开工先读它，根据任务找到对应 spec 的路径，再按需打开详细文件。这套做法把上下文消耗降了一个数量级。

5.3 坑三：把验收完全交给 AI，信任边界模糊

SDD 流程里最容易出现的一种偷懒心态是："反正测试是 AI 写的，跑完也都过了，那验收也让它来吧。"

这非常危险。AI 写的测试天然倾向于证明"AI 写的代码是对的"，因为测试用例来自同一套理解。我在一次实战中遇到过：AI 给导出接口写了单测，测试数据全部是默认值，等于把整个功能路径跑了一遍但没验证任何参数边界。测试全绿，实际一用就崩。

我的原则是：AI 生成的测试可以跑，但人的抽查不能省。至少在三个节点上，人必须亲自介入：需求理解是否正确、核心数据路径是否安全、验收标准中涉及钱和权限的部分是否达标。信任 AI 是好事，但信任边界必须画在"AI 能自我验证"和"必须人来看"之间。

5.4 坑四：多人同时改 spec，冲突比代码冲突还难解

当团队里多个人同时使用这套工作流的时候，spec 文件的冲突会是新的麻烦。代码冲突 git 会帮你合并，但需求冲突不能靠合并解决——比如两个人都新增了"导出"功能的提案，一个人定义的是 CSV，另一个人定义的是 Excel。

我的建议是让 spec 变更和代码变更走同一条评审通道：每个提案一个新分支，提案经过评审再合并到主干。另外，项目级规范一定要保持"单一负责人"模式，功能级提案允许并行，但项目级规范只能由一个人审阅合并，避免原则性内容被悄悄改掉。

6. 什么样的小队和项目真正适合这套玩法

6.1 最适合的地带：独立开发者、小产品和快速迭代团队

很多人潜意识里觉得 SDD 是大公司重型流程的产物，个人开发者用不上。我实际用下来得出的结论恰恰相反：SDD 最适合 1 到 10 人的小型团队。

原因也简单：大公司有需求评审、架构评审、测试团队，流程已经显式化了；小团队没有这些环节，需求往往存在于产品经理或者创始人的脑子里。当 AI 变成一个能每小时产出几千行代码的"超级实习生"时，唯一能低成本给这个实习生对齐需求的方式，就是一份规范文件。对独立开发者来说，个人全栈做项目时最容易出现的"一个月后看不懂自己代码"问题，也正好被 SDD 解决了一半。

6.2 不适合的场景：遗留系统改造、强合规项目

不是所有项目都适合立刻上 SDD。

遗留系统改造是最难啃的骨头。老项目代码和实际行为千疮百孔，如果你试图先写清规范再动代码，光补齐规范就要耗尽所有精力。这种场景更适合先做"事实记录"：让 AI 根据代码库反向生成当前行为的描述文档，再以这份文档为基础讨论哪些要改。

强合规项目（比如涉及审计、医疗、金融监管）不能把 spec 当作唯一的合规记录。规范驱动开发可以辅助需求追踪，但正式的合规文档体系不能省，否则审计时会非常被动。

完全没有 AI 编码工具的项目也不太适合 SDD。人类写代码时，详细规范的维护成本很高，很容易变成写了也不看、改了也不同步的僵尸文档。SDD 的价值在 AI 编码场景下才能最大化，因为 AI 是真的会去读规范的。

6.3 从 vibe coding 到 harness + SDD 的完整演进路径

如果你现在还在 vibe coding 阶段，想逐步过渡到 SDD，我建议按阶段升级，不要一步跳到位：

• 阶段一：随意 vibe coding。特点是让 AI 自由发挥，你自己也只关心"能不能跑"。这个阶段可以继续，但要开始养成分支提交的习惯。
• 阶段二：加 harness 约束。开始给 AI 设定规则，比如"不能修改哪些文件""不能使用哪些依赖""每次变更必须写变更说明"。SuperPowers 就在这个阶段介入。
• 阶段三：引入 SDD。把项目级规范和功能提案写起来，让 AI 先读规范再动手。OpenSpec 在这个阶段介入。
• 阶段四：全栈自动化。在 CI 里加入规范校验，比如检查 spec 文件是否存在、验收标准是否完整、新增代码是否有对应任务编号，实现"规范和代码同步"的半自动检查。

判断你是否应该进入下一阶段的信号很简单：当你在当前阶段反复遇到"AI 写得太快、管不住"的时候，就该升级了。不要等满盘乱象才开始行动。

6.4 与其它 AI 编程工具的搭配思路

OpenSpec 和 SuperPowers 都不是绑定某个特定 AI 工具的封闭体系。规范文件是纯文本的，技能文件是标准 Markdown 的，这意味着无论你用的是 Claude Code、Cursor 还是 opencode，都能接入。

我的搭配思路是：

1. 用 OpenSpec 管理规范文件，这部分是"项目的数据库"，任何 AI 工具都能读；
2. 把"必须读 spec 再动手"这条铁律写进各个工具的规则文件里；
3. 用 SuperPowers 提供方法论层面的技能，这层与 OpenSpec 的规范层互补，不冲突。

网上常有人拿 OpenSpec 和同类工具对比，比如看起来类似的规范驱动方案，我的看法是：工具都是表面，核心是"规范结构是否清晰、是否与代码同仓、是否真的会被 AI 读取执行"。只要满足这三个条件，用什么工具都能跑起来。

7. 最后：我的实测心得与方法论取舍

7.1 我保留了哪些，替换了哪些

用了大半年之后，我对手上这套组合做了一次"断舍离"。

保留的部分：提案阶段一定不跳过、验收标准一定写成可判定语句、每个功能提案必须关联明确任务。这三个习惯是 SDD 最有价值的骨架，省掉任何一个都会回到"AI 写完、人猜"的老路上。

替换的部分：我没有追求 OpenSpec 提案生命周期里所有状态的严谨流转，比如"提案 → 已批准 → 已实现 → 已归档"这套环节，我只保留了"提案 + 任务 + 验收标准"三件套。对个人项目和小团队而言，少一点流程仪式感，多一点直接产出，更重要。

SuperPowers 我也只保留了高频使用的四五个技能。技能太多会让 AI 在"选哪个"上消耗精力，保留最核心的 Brainstorming、Plan Writing、TDD、Debugging 已经能覆盖日常开发的大部分场景。其它的装一个是一个，不追求全量。

7.2 一个小技巧：用"规范同步检查"代替补文档的痛苦

最后分享一个让我受益巨大的小习惯：不要等到功能全部做完了再补规范文档，而是在每天收工时让 AI 跑一次规范同步检查。

做法是：让 AI 对比当天的代码变更和对应 spec 文件，输出一份"规范的哪些描述已经过时、哪些验收标准已被新逻辑覆盖、哪些范围外内容被悄悄实现"的报告。我每天花五分钟扫一眼这份报告，顺手把该更新的 spec 改掉。这比攒一周再花一小时补文档轻松得多，也避免了"代码已经变了、spec 还在描述旧世界"的经典腐化问题。

这套玩法不一定适合所有人，但如果你和我一样，已经受够了"AI 写代码一时爽，维护起来火葬场"的循环，真的值得花一个周末试试。先跑通一个最小功能，把提案、任务、验收标准三件套建起来，再逐步叠加技能和自动化检查——你会慢慢发现，AI 编码的爽和工程上的稳，是可以同时存在的。