AI编程新范式：SDD+OpenSpec+SuperPowers全栈工作流实战

不扯概念了，直接说结论：如果你还在用"vibe coding"的方式让AI写代码，那你的项目大概率离失控不远了。今天聊的这套组合——SDD（Specification-Driven Development，规范驱动开发）+ OpenSpec + SuperPowers，是我最近在Claude Code里实际跑通的全栈开发工作流，专门解决AI写代码"跑得欢、收不住"的问题。

先说背景。今年AI编程的热词从"vibe coding"变成了"harness × SDD"，ThoughtWorks的杰出工程师Birgitta Böckeler提出了SDD的三级分类框架，圈内一下子炸开了。核心观点很朴素：AI写代码之前，必须先把规范（Spec）写清楚，让AI像人类工程师一样先看图纸再动手。OpenSpec就是规范管理的工具，SuperPowers则是一套给Claude Code装的"技能包"，把头脑风暴、测试驱动开发、计划执行这些工程实践变成AI可调用的流程。

这篇文章不是翻译官方文档，是我自己在真实项目里踩坑、调参、复盘后的全套经验，适合正在用Claude Code、Codex、OpenCode这类AI编程工具，但觉得产出质量不稳定、代码复用性差、越改越乱的同学。如果你还没听说过OpenSpec和SuperPowers，这篇文章正好给你补上；如果你已经在用了，那看看我的用法跟你有什么不同，尤其是踩坑那段，应该能帮你省不少时间。

1. SDD是什么：为什么"凭感觉编码"不够了

1.1 从Vibe Coding到规范驱动开发

先聊聊vibe coding为什么不够用。去年到今年上半年，"vibe coding"这个词非常火，核心玩法就是你给AI一句"帮我写个博客系统"，然后AI哗哗生成一堆代码。初期确实爽，尤其是做原型、做Demo的时候，效率甩传统开发几条街。但到了项目中期，问题全冒出来了：AI生成的代码风格不统一、依赖关系混乱、改一个功能崩三个地方，甚至有时候AI自己都忘了之前生成过什么东西。

说白了，vibe coding的问题在于"没有上下文约束"。AI每次生成代码都像是在回答一道全新的题，它不知道你之前定过什么规则、文档里写过什么约束、哪些模块是核心不能动。这就好比你让一个实习生干活，但不给他看需求文档、不给他讲技术规范、不让他看现有代码，那他只能凭感觉写，写完大概率没法用。

SDD解决的就是这个问题。它的核心思想特别简单：先把规范写清楚，再让AI动手写代码。这个规范不是产品经理写的那种PRD，而是介于需求和代码之间的一种"可执行的规格说明"，包含背景、需求、技术方案、验收标准、测试策略等。AI拿到这份规格之后，它的行为模式就从"自由发挥"变成了"按图施工"，质量稳定性一下子就上来了。

1.2 Birgitta Böckeler的SDD三级分类框架

Birgitta Böckeler把SDD分成了三个层级，我自己用下来觉得这个分法确实精准，值得拆开讲。

第一级是没有规范或规范极弱。这时候AI基本纯靠提示词驱动，你告诉它做什么它就做什么，没有结构性约束。这是大多数vibe coding场景的现状，效率高但风险也高，适合做原型验证，不适合做生产级项目。

第二级是有规范，但规范是静态的。你会在项目里放一个README或文档，写清楚架构选型、命名规范、目录结构等。AI会参考这个文档来生成代码。但问题在于，这些规范不和实际代码产生关联，不随着项目的进展而更新，AI虽然不会跑偏太远，但也没法做到精细化控制。

第三级是规范真正驱动开发流程。这一层级下，规范是"活的"，每一个需求变更都对应一次规范的更新，AI生成代码的过程本身就是在驱动规范演进。OpenSpec在做的就是这一层的事：规范不仅指导AI写代码，而且被纳入版本管理、审查流程、测试流程，跟代码一样有生命周期。SuperPowers再把TDD、计划执行这些实践注入进去，让AI从一个"会写代码的工具"变成"遵守工程纪律的协作者"。

我个人的建议是：如果你是个人开发者做小项目，起步至少从第二级开始；如果做的是团队项目、要么不做要么做正规一点的，直接上第三级，后面省下来的重构时间远超前期写规范的成本。

2. OpenSpec：让规范从"文档"变成"代码"

2.1 OpenSpec的核心概念与目录结构

OpenSpec是个开源工具，它做的事情说白了就是把"规范"这种本来很虚的东西，变成了项目里一个实实在在的、可版本管理、可审查、可被AI读取的目录结构。

我用下来OpenSpec的核心概念主要有三个：

Spec（规范）：描述项目的核心能力、技术约束、架构决策。它有点像项目的"宪法"，是稳定不变的。比如"本项目是一个博客系统，支持Markdown、支持标签"——这些是高层描述，不随某个具体需求的增删而改变。在OpenSpec里，它们存放在 openspec/specs/ 目录下。

Change（变更）：描述一次具体需求变更。比如"给博客增加全文搜索功能"就是一个Change。Change里会包含背景分析、需求描述、技术方案、改动文件清单、验收标准等。在OpenSpec里，Change存放在 openspec/changes/ 目录下，每个Change对应一个带日期的目录。

Project（项目说明）：项目级的高层信息，包括项目简介、技术栈、运行方式等。它存放在 openspec/project.md 里。

安装OpenSpec很简单，只需要一条命令：

bash复制curl -fsSL https://openspec.dev/install.sh | bash

安装完到项目里初始化：

bash复制openspec init

运行后会生成 openspec/ 目录。我用一个小项目来展示目录结构：

text复制my-project/
├── openspec/
│   ├── project.md
│   ├── specs/
│   │   ├── architecture.md
│   │   ├── data-model.md
│   │   └── api-design.md
│   └── changes/
│       ├── 2025-06-10_add-full-text-search/
│       │   ├── proposal.md
│       │   └── tasks.md
│       └── 2025-06-15_add-user-auth/
│           ├── proposal.md
│           └── tasks.md

这个结构很妙的地方在于：规范和代码是并列的、可对比的。你打开PR的时候，代码变动和规范变动可以同时看到，审查者一眼就能看出"这次改动是不是符合规范"。

2.2 用OpenSpec定义需求变更的实操

初始化只是第一步，真正干活的时候要会创建Change。我用一个例子来说。

假设你要给项目加一个"用户注册"功能，传统的做法是直接跟AI说"帮我写用户注册功能"。但在OpenSpec的工作流里，你要先让AI写一份Change Proposal：

bash复制openspec new change "add-user-registration"

这条命令会在 openspec/changes/ 下创建一个新目录，里面有个Change文件模板。你打开后用AI辅助来填，或者直接用Claude Code来帮你填，里面有这些字段：背景、需求明细、不做的事、技术方案、涉及文件、验收标准、测试计划。

我的实操心得是，验收标准这栏一定要写具体，比如"注册成功后返回201状态码"、"密码必须经过BCrypt加密存储"，不要写"用户注册功能正常"这种废话。AI在实现功能的时候，会把这个验收标准当作硬性约束来执行，验收标准越具体，最终代码越接近你的预期。

Change写完之后，把它并入规格里：

bash复制openspec record

这个动作相当于把这次变更"转正"了，Change会被合并到 specs/ 下，成为长期规范的一部分。这样项目后面不管来了多少需求，规范和变更的历史都在，AI每次读到它的时候，都能知道自己处在项目的哪个阶段。

2.3 OpenSpec搭配Claude Code的工作机制

OpenSpec本身不生成代码，它是给AI编程工具（比如Claude Code、Codex、OpenCode）提供"上下文"的。实际跑起来是这样的：

1. 你在Claude Code里让AI为某个需求创建OpenSpec Change文件；
2. AI读取 openspec/ 下现有的规范和项目文档；
3. AI根据规范和Change文件生成代码，而不是直接凭空写；
4. 编码完成后，AI可以基于Change里的验收标准自行验证代码。

为了让Claude Code更顺滑地读取OpenSpec，我一般会在项目根目录的 CLAUDE.md 里写清楚规则。这个文件是Claude Code项目级的"记忆"文件，AI每次启动都会自动读取。

markdown复制# CLAUDE.md

## 项目开发流程

1. 开始新功能前，必须先查看 openspec/specs/ 下已有规范。
2. 如果需求在 openspec/changes/ 下已有对应 Change，严格按 Change 中的技术方案和验收标准执行。
3. 如果没有对应 Change，先创建 Change Proposal 并等待用户确认后再编码。
4. 编码完成后，按 Change 中的验收标准逐条自测并汇报结果。

这么写的效果非常明显：AI不再"每次都是第一次来"，而是真的像团队里一个持续工作的成员，记得住项目的规范和历史。我自己实测下来，代码的一致性和可维护性提升了一个档位。

要注意的是，OpenSpec目前有一些版本差异，不同版本的CLI命令可能略有不同。我建议装完之后先跑 openspec --help 看一下当前版本的命令列表，然后再初始化。另外，openspec record 会更新specs，建议这个动作放在代码合并之前做，保证规范和代码同步演进。

3. SuperPowers：给AI编码助手装上"职业习惯"

3.1 SuperPowers在做什么

如果你只用OpenSpec管好规范，AI的行为还是不够"专业"。为什么？因为规范管的是"做什么"，不管"怎么做"。AI还是有可能拿到规范之后，跳步、直接撸代码、不写测试、不复盘，甚至改完代码连自己改了什么都说不清。

SuperPowers就是来解决"怎么做"的。它是Jesse Vincent（GitHub上叫obra）开源的一套Claude Code技能包，仓库地址是 obra/superpowers。它的核心思路是：把软件工程里那些公认的好实践（头脑风暴、测试驱动开发、编写计划、执行计划、系统化调试、写提交信息等）封装成一个个可供AI调用的"技能"（Skills）。

你和AI对话的时候，可以明确要求它调用某个Skill来完成特定流程。比如跟AI说"用brainstorming技能来帮我梳理这个需求的实现方案"，它就真的会按照一套结构化流程，先问你问题、再分析选项、最后给出建议，而不是上来就甩给你一大堆代码。

3.2 安装SuperPowers到Claude Code

SuperPowers的安装方式经历过几次版本迭代。早期是手动把目录复制到 ~/.claude/skills/ 下，后来变成了用CLI去安装和管理。以目前最常见的安装方式为例，你在项目目录里执行两个命令就行：

bash复制# 先安装skills管理器
claude install-skill obra/superpowers -f --skip-verify

或者如果你已经用了Claude Code比较新的版本，可以直接在Claude Code里告诉AI：

text复制请使用SuperPowers技能包中的test-driven-development技能，为当前项目新增的Change编写测试。

不过我在实际使用中发现，手动克隆更可控。把仓库Clone到一个固定位置，然后在 ~/.claude/skills/ 里建软链，方便随时更新：

bash复制git clone https://github.com/obra/superpowers.git ~/.claude/superpowers
ln -s ~/.claude/superpowers/skills/* ~/.claude/skills/

这样操作之后，你用 ls ~/.claude/skills/ 就能看到一系列技能目录，包括brainstorming、writing-plans、executing-plans、test-driven-development、systematic-debugging等。

有个细节值得一提：如果你用的是OpenCode或者其他AI编程工具，安装路径会不一样，比如OpenCode的skills目录就在 ~/.config/opencode/skills/，把SuperPowers里的skills目录软链过去就行。不同工具对skills的调用语法略有差异，但SuperPowers的基础文件结构是通用的。

3.3 核心Skills拆解：Brainstorming、TDD、Plan

SuperPowers里的技能不少，我重点讲几个我平时用得最多的，也是和三件套工作流关系最紧密的。

Brainstorming（头脑风暴）：这个Skill适合在需求还没完全想清楚的时候用。它会引导AI和我之间进行多轮问答，把模糊的想法变成清晰的方案。它生成的内容不是代码，而是一份结构化的需求梳理文档，包含目标、约束、可选方案、推荐方案、风险评估。我觉得这个技能的关键价值在于：AI会主动问你问题，而不是默认"我懂了"。很多项目跑偏，就是因为AI以为自己懂了，你也没多解释，结果产出完全不在点上。

Writing Plans（编写计划）：这个Skill用来把OpenSpec的Change Proposal转换成可执行的逐步计划。它会按依赖关系拆任务，标注每个任务的完成标准。我实际用下来的感受是，AI拆任务的能力虽然不如资深工程师那么精准，但比"一条命令生成整个模块"要安全得多。尤其是中大型功能，拆成小步骤之后，每一步有验证点，出错的概率和排查成本都直线下降。

Test-Driven Development（测试驱动开发）：这是SuperPowers里含金量最高的技能之一。它会要求AI先写测试用例，再写实现代码，再运行测试验证。在AI编码的语境下，TDD的意义不仅是保证质量，更关键的是给AI一个"自检闭环"——AI写完代码之后自己跑测试，跑挂了就修，修完再跑，直到全绿。传统开发里TDD需要很强的自律性，但AI执行TDD反而非常简单，你只需要让它调用这个技能即可。

Executing Plans（执行计划）：当计划已经存在的时候，用这个Skill来执行。它会看着计划中的步骤一步步推进，每完成一步就做一次状态记录。这个技能和OpenSpec的Change配合起来非常顺：Change里的tasks.md就是计划，Executing Plans逐个执行，执行完一项勾一项。

我建议新手不要一上来就所有技能混着用。先只用OpenSpec管规范，再用SuperPowers的Executing Plans来推动编码，等你熟悉了这套节奏之后，再引入Brainstorming和TDD技能，逐步把整个流程武装起来。

4. 三件套实战：一个全栈功能从0到1

4.1 场景设定和准备工作

为了让你能照着动手，我用一个完整实例来演示"Claude Code + OpenSpec + SuperPowers"三件套的实际配合。假设我们要做一个"个人记账本"的Web应用，技术栈选型是Next.js + Prisma + SQLite，最近要新增的功能是"月度账单导出CSV"。

整个流程我会拆成五个阶段：初始化项目、写OpenSpec Change、让SuperPowers做方案规划、用TDD技能驱动编码、最后验证并归档规范。这些步骤跑通了，你换任何项目都可以套这个模板。

先做初始化：

bash复制npx create-next-app@latest ledger-app --typescript
cd ledger-app
curl -fsSL https://openspec.dev/install.sh | bash
openspec init

初始化完成后，把CLAUDE.md写起来。我上面已经给过一个模板，这里不重复。核心就一句话：让AI每次进入项目时知道，一切开发从规范开始。

4.2 用OpenSpec定义"导出CSV"需求

需求是这个：用户登录后，在账单列表页点击"导出CSV"按钮，能把当前月份的所有账单数据导出为CSV文件。

先把Change创建出来：

bash复制openspec new change "export-monthly-bills-csv"

然后让Claude Code打开这个文件，基于下面的提示来完善：

text复制用OpenSpec Change的规范格式，帮我完善这次变更提案。背景：用户需要一个月度账单导出功能。技术约束：使用Next.js API Route实现后端导出，使用csv-stringify生成CSV，文件需要UTF-8编码以兼容Excel。请补全需求明细、技术方案、验收标准。

AI生成的Proposal文件里，有两个部分我需要重点检查：

一个是"技术方案"。AI可能会写"在后端直接生成CSV并返回"，这句话看着对，但不够严谨。实际的项目里你要考虑，是前端生成还是后端生成？文件编码是UTF-8还是带BOM？导出的时候要不要校验用户权限？这些细节在Change阶段定清楚，后面AI编码时就不会出现"导出文件用Excel打开乱码"这种经典问题。

另一个是"验收标准"。我会要求至少写三条：接口返回200且Content-Type为text/csv；导出的文件包含表头：日期、分类、金额、备注；金额保留两位小数；测试覆盖导出接口。

把Change写完，我看一遍，确认无误后，进入下一阶段。

4.3 Superpowers介入：方案规划与TDD驱动

Change定稿后，我让Claude Code调用SuperPowers技能：

text复制请使用brainstorming技能，针对"export-monthly-bills-csv"这个Change，梳理出一个简洁的编码方案，重点考虑API Route的路径、Prisma查询逻辑和CSV序列化方式。

这时候AI会按Brainstorming的流程，反问我几个问题，比如"导出是按自然月还是按账单记录的月份字段？"、"是否需要考虑数据量超过一万条的情况？"等。这些问题其实都是合理的设计决策点，回答清楚之后，方案会比我直接拍脑袋定得更完整。

方案确认后，我让AI用writing-plans技能把这个方案拆成小任务，按依赖关系排序。第一个任务是"创建导出API Route，返回空CSV"，第二个是"实现Prisma查询当月账单"，第三个是"实现CSV序列化并返回"、第四个是"补充前端导出按钮和下载逻辑"。

然后，让AI套用TDD流程：

text复制请使用test-driven-development技能，先为导出API写集成测试和单元测试，再写实现代码。

这一步会看到AI先创建测试文件，再创建实现文件，最后跑测试验证。这里我要强调一个SuperPowers的细节：它的TDD流程里，测试运行器默认是 npm test，如果你项目用的不是Vitest或Jest，需要先在项目的配置里让它知道用什么来跑测试。我在项目里就是先在package.json里配好 "test": "vitest"，然后AI才会正确地执行测试命令。

4.4 验证、合入与规范归档

所有编码完成后，我手动或者让AI按验收标准逐条核对：

• API返回200且Content-Type为text/csv？——我在终端用curl测一下。
• 导出文件是否包含表头和正确金额格式？——实际下载打开看。
• 测试是否覆盖导出接口？——看测试覆盖率报告。

全部通过之后，执行OpenSpec的record操作，把Change转正归档：

bash复制openspec record

这条命令会把这次Change的结论合并到 openspec/specs/ 下，后续AI读取项目上下文时，就能看到项目已经支持"月度账单导出CSV"这个能力了。

我再提一个细节：归档之后，记得把 openspec/ 这个目录纳入Git管理。OpenSpec本身不依赖任何外部服务，是纯本地文件，这意味着你和AI的"契约"都留在仓库里，团队协作时，别人拉下来代码之后，AI也能通过OpenSpec把这些"历史记忆"继承过来。这一点我觉得是三件套组合里最值钱的部分。

5. 常见问题与排查技巧实录

5.1 三件套使用中的典型问题速查

我用这套组合跑了不少项目，也踩过不少坑。下面直接给一份问题速查表，每一个都是实际遇到过的。

5.2 我在实操中的三个独家经验

最后分享三个对提升成功率有决定性影响的经验。

第一，OpenSpec的规范文件不要写太长。我见过有人把架构规范写到两万字，结果AI读不进去，甚至读取后就忽略了关键约束。规范要精炼，能用表格绝不用长段落。一条规则一行字，比如"数据库访问必须走Prisma Client"、"所有金额字段用decimal类型"，核心信息一目了然。

第二，SuperPowers的Skills是可裁剪的。不是所有技能都适合你的项目。比如你项目里没有严格的TDD环境，那就可以把test-driven-development技能从 ~/.claude/skills/ 下临时移走，免得AI每次都在测试上较劲。反过来，如果你特别在意提交信息的规范，可以让AI每次提交前调用write-commit-message技能，生成规范的Conventional Commits格式提交信息。

第三，不要让AI同时承担"写规范"和"写代码"两个角色。我的做法是：写Change Proposal的时候，我尽量不指定技术方案，让AI基于背景来生成；但一旦Change进入编码阶段，我就通过提示词把规范锁定，不让AI在执行过程中临时改方案。规范是规划讨论时用的，代码是实现规范时的执行结果，这两个阶段一旦混在一起，AI就会边写边改方案，最后代码质量和规范一致性都崩掉。

目前这三件套的组合还在快速迭代中，OpenSpec的CLI版本、SuperPowers的Skills列表都在更新，今天这篇是基于我当前实测的版本写的。但核心思想不会变：让AI在约束下创造，而不是毫无边界地输出。无论工具怎么演进，在动手写代码之前先把规范和流程立起来，这个习惯永远都不会过时。

个人体会是，这套工作流最大的改变不在于代码质量本身（虽然确实提升很多），而在于我终于能放心地让AI连续工作几小时而不用全程盯着。因为每一行代码背后都有规范在兜底，有测试在验证，有归档在记录。这种"可控感"才是三件套真正值钱的地方。