先说一个核心判断：AI编码助手确实在飞速迭代，把需求往对话框里一扔，几秒钟就能生成几百行代码，那种“效率翻倍”的错觉，体验过的开发者都懂。但先别高兴太早——真把这类代码放到生产环境里跑一跑，你很快就会发现一个苦涩的事实：写代码从来都不是软件开发里最难的那一环，“写对代码”才是真正的挑战。

什么叫写对？符合设计意图、覆盖所有边界场景、没有多余或逻辑矛盾、还能经得起维护和迭代的考验。这些事情，AI不会自动帮你搞定。它不理解你的项目边界，不懂你的业务场景，更不会主动去规避那些未来会让你头疼的技术债。如果没有一套完善的开发规范来约束它的行为，那所谓的“AI写代码”，与其说是提升了编程效率，不如说是在批量制造“未来的技术债务”。

正是因为看清楚了这一点，“规范驱动开发”（SDD，Spec-Driven Development）的理念才真正站上了台面。它的逻辑说起来很简单，就一句话：先想清楚再动手。在让AI写代码之前，先把需求规范、设计标准、验收条件全都明确下来，用规范文档给AI“画好地图”，再通过验证环节确保代码不跑偏。今天这篇文章，我们就把支撑SDD落地的两个核心框架——OpenSpec和Superpowers——从头到尾拆一遍。看看它们到底是怎么解决AI编码“不规范”这个痛点的，以及在实战中应该如何选择、如何使用。

一、先搞懂：什么是规范驱动开发（SDD）

在聊具体工具之前，有必要先把SDD的逻辑和自己以往的“AI写代码”习惯做一个明确的切割。

很多人用不好AI编码助手，核心原因就一个：脑子里没有“先规范后编码”这根弦，结果就是反复掉进“需求→写代码→不满意→返工”这个死循环里。

1.1 传统AI辅助编码的痛点

传统的AI辅助编码流程，简单、直接，但也挺“撞大运”的：用户大概说个需求，AI直接输出代码，用户凭肉眼检查，发现不对了再让AI改。这个流程乍看高效，但只要用过几次就知道，里面藏着三个非常要命的问题。

第一个是需求传递永远有偏差。用户的描述往往是碎片化的，比如丢一句“写一个后台服务启动检查功能”，但启动失败怎么办？要不要阻塞主程序？兼容哪些服务类型？这些细节统统没说。AI只能靠“蒙”，出来的一大堆代码里夹杂着大量臆断，和真实需求差了十万八千里。

第二个是缺乏可追溯性。代码一旦出了bug，你根本找不到当初的设计意图——为什么要这么写？当时的技术选型逻辑是什么？没有文档、没有记录，唯一的办法就是逐行读代码来猜测。对于长期项目来说，这是非常恐怖的一件事情。

第三个，也是最隐蔽的问题：技术债积累。AI生成的代码难免会有冗余、不规范、兼容性差之类的小毛病。一次两次可以接受，但长期下来，这些小毛病会像滚雪球一样越滚越大，直到把你的项目拖进一个不可维护的泥潭。

1.2 SDD的核心逻辑与优势

SDD的思路从根本上颠倒了上面那种模式。它的完整闭环其实很朴素：用户描述需求 → 生成规范文档 → AI按规范实现 → 按规范验证。核心就是一句话——用文档约束行为，用验证确保正确。

相比传统模式，SDD的优势几乎是降维的。第一，需求传递前所未有的精准。一套完整的规范文档能把模糊的需求拆成具体的目标、场景、验收条件，AI照着文档执行，几乎不会走偏。第二，开发过程全程可追溯。每一次变更、每一步决策，都有设计文档做支撑。后期出了问题，不用再盲人摸象，直接定位到设计环节就行。第三，技术债被大幅压缩。因为规范文档会提前把代码标准、技术选型、测试要求全写死，AI产出的代码从一开始就是“规范的”，后期维护省下来的时间，远比前期多花在写文档上的时间多。

说得更直白一点：SDD不是否定AI的效率，它是在用规范给AI“立规矩”，确保AI的高效全部打在了正确的靶子上。

二、OpenSpec：规格驱动的变更管理框架

OpenSpec是一个结构化的开发工作流框架。它的核心思想其实就是一句话：“每一次变更，都应该有完整的设计文档可以追溯。” 注意，它不是一个独立的工具，而是一套可以嵌入任意AI编码助手中的工作流规范，通过几个简单命令就能驱动整个流程。特别适合需要长期维护、注重变更追溯的软件项目。

2.1 快速上手：安装与初始化

OpenSpec基于Node.js开发，安装和初始化非常简单。

打开终端，直接全局安装最新版本：

npm install -g @fission-ai/openspec@latest

进入项目目录后执行初始化：

cd your-project
openspec init

完成后，项目根目录下会多出一个叫“openspec”的文件夹，里面包含了规范文档、变更记录等核心目录。后续所有的文档编写和变更管理，都在这儿进行。

2.2 核心概念：Artifact链

OpenSpec真正的灵魂，是一条叫作“Artifact依赖链”的文档链条。所谓Artifact，指的是每一个环节生成的规范文档，它们相互关联、层层细化，共同构成一个可追溯的体系。链条长这样：

proposal.md → design.md → specs/*.md → tasks.md → 代码实现 → 归档

这条链上的每个环节职责都非常清晰，缺一不可。

（1）proposal.md：变更提案

说白了就是变更的“立项报告”，核心任务是说清楚“为什么做”。不需要太复杂的技术细节，重点写清楚三样东西：变更的原因、最终目标（含非目标）、以及对项目的影响范围。

举个例子，如果要做一个“启动时检查并拉起后台服务”的变更，proposal.md里就要写清楚：当前后台服务可能没启动，导致核心功能挂了，这是原因；目标是让项目启动时自动检查服务状态、未启动就自动拉起，非目标是不改变服务本身的运行逻辑；影响范围限定在项目启动流程和后台服务依赖模块，不碰其他业务。

（2）design.md：设计决策

提案通过了，接下来就是“怎么做”。design.md的核心任务，是把技术方案的选择过程、替代方案的对比逻辑、以及潜在的风险评估都记录在案。它要证明你的技术选型是合理且可行的。

还是上面那个例子，design.md要说明白了：这次决定复用项目中已有的ServiceUtils工具类，因为省时省力减少冗余；替代方案也不是没有考虑过，比如自己重新写一套检查逻辑，但经过对比后发现复用的性价比更高；同时也要承认，复用的潜在风险是ServiceUtils的版本兼容问题，并提前想好解决方案——先验证工具类的可用性，必要时做版本适配。

（3）specs/*.md：需求规格

这是整个规范文档体系的重头戏。specs目录下每个文件都采用“Requirements + Scenarios”的格式来写，尤其是其中的Scenarios，必须用“WHEN/THEN”的句式把不同场景下的预期行为写得一清二楚。

回到后台服务启动检查的例子，spec文件会覆盖4个核心场景：
- WHEN后台服务未注册，THEN提示服务未注册，不执行拉起
- WHEN后台服务已运行，THEN不做任何操作，输出正常提示
- WHEN后台服务未运行但已注册，THEN自动拉起，输出成功提示
- WHEN服务拉起失败，THEN输出失败提示，不阻塞主程序

这4个场景，就是AI实现代码时必须严格遵循的“宪章”。

（4）tasks.md：任务清单

specs解决了“做成什么样”的问题，tasks.md则负责把需求拆成一个个具体可执行的checkbox。每个任务就是一个独立可完成的小步骤，确保AI能按顺序执行，一个细节都不落下。

后台服务启动检查的tasks.md，拆成了三个核心任务：
1. 在项目启动入口处添加服务检查逻辑，调用ServiceUtils工具类
2. 实现4个场景的判断逻辑，对应specs要求
3. 添加日志输出，记录检查结果和拉起状态

（5）代码实现与归档

所有Artifact文档都准备齐全之后，就可以让AI按照tasks.md逐个实现代码了。实现完成后经过验证环节确认符合specs要求，最后进行归档。归档之后，这条变更的完整信息——包括所有Artifact文档和代码变更——就被封存进了指定目录，形成永久可查的历史记录。

2.3 用命令驱动全流程

OpenSpec提供了一组简单的命令来支持整个SDD流程。这里整理了最常用的几个：

2.4 一个完整演示：启动时检查并拉起后台服务

理论说得再多，不如动手完整跑一遍。我们拿“启动时检查并拉起UniCloudService后台服务”这个需求来演示OpenSpec的完整流程。

第一步：快速生成所有Artifact文档
这个需求相对简单，可以直接使用快速通道命令一次性搞定：

/opsx:ff 启动时检查并拉起 UniCloudService 后台服务

执行之后，AI会自动在openspec/changes目录下创建一个活跃变更文件夹，里面整整齐齐地放着4个核心文档：

• proposal.md：阐述变更原因。当前UniCloudService可能处于未启动状态，导致依赖它的功能无法正常使用，这个变更要在项目启动时自动检查并拉起，提升系统稳定性。

• design.md：技术方案决策。复用项目中已有的ServiceUtils工具类，调用其checkService和startService方法；启动失败时不阻塞主程序，只输出日志提示；替代方案是自己写一套，对比后选择复用。

• specs/unicloud-service-startup/spec.md：4个核心场景，覆盖未注册、已运行、未运行、启动失败。

• tasks.md：3个可执行任务，每个任务都写得明明白白。

第二步：按任务实现代码
文档准备齐全后，输入：

/opsx:apply

这个命令会驱动AI逐个处理tasks.md里的任务。每完成一个任务，AI都会自动对照specs文件进行验证，确保没有遗漏场景、没有错误逻辑。比如完成任务2（场景判断逻辑）后，AI会自动检查是否覆盖了全部4个场景、预期行为是否一致。

第三步：变更归档
代码实现并验证通过后，输入归档命令：

/opsx:archive

执行后，OpenSpec会把该变更的所有文档和代码封存到openspec/changes/archive目录下，命名格式为“日期-变更描述”，比如“2026-03-25-start-unicloud-service”。以后任何时候想回溯这个变更的设计思路、实现细节，直接去翻归档目录就行了。

2.5 主spec + delta spec体系：越用越完善

OpenSpec最有特色的设计，其实是它的“主spec + delta spec”体系。这个设计能实现项目级规格知识库的长期积累，让规范文档随着项目一起成长，而不是每次变更都要从头写起。

从目录结构可以看得很清楚：

openspec/
├── specs/ # 主specs（项目级知识库）
│ └── disk-mount/spec.md
└── changes/
├── start-unicloud-service/ # 活跃变更
│ ├── proposal.md
│ ├── design.md
│ ├── specs/ # delta specs（变更级）
│ │ └── unicloud-service-startup/spec.md
│ └── tasks.md
└── archive/ # 已归档变更

spec被清晰分成了两类：位于openspec/specs目录下的叫主spec，它是项目级的规格知识库，按功能模块组织（比如disk-mount、user-auth等），是整个团队共享的基础规范。而每个变更里特有的specs目录，存放的是delta spec，只包含这次变更新增或修改的内容，不必重复编写主spec里已经有的。

更有意思的地方在于：当变更归档时，OpenSpec会自动把delta spec中的内容同步到主spec里。也就是说，主spec会随着每一次变更自动迭代升级，越用越完善。将来的新开发需求，直接翻阅主spec就能找到参考，不需要重新设计、不需要重复劳动。

三、Superpowers：多袋里协作的完整开发工作流

如果说OpenSpec的侧重点在“变更追溯和知识积累”上，那Superpowers更突出的则是“执行质量和自动化审查”。它是由Jesse Vincent开发的开源项目，主打“子袋里驱动开发”和“强制TDD”，支持Claude Code、Cursor、Codex、Gemini CLI等多个AI编码平台。说直白一点，有了它，AI就像一个训练有素的开发团队一样在干活。

3.1 核心概念：Skills组合

Superpowers的核心，是一系列可组合的指令文件——每个Skill都是一份Markdown文档，定义了AI在某个特定开发阶段该做什么、怎么做。这些Skills按功能分类，相互配合，共同拼接出完整的开发工作流。

下面这张表整理了Superpowers的核心Skills及其各自的职责：

这套Skills是可以灵活组合的：简单需求，只用brainstorming、writing-plans、subagent-driven-development三个就够了；复杂需求，则可以把test-driven-development、requesting-code-review等也加进来，层层把关。

3.2 完整工作流程：从需求到收尾

Superpowers的工作流程非常清晰，每个阶段都有对应的Skill驱动：

brainstorming → using-git-worktrees → writing-plans → subagent-driven-dev → finishing-branch

（1）brainstorming：苏格拉底式对话
这是起点。AI会像一个训练有素的产品经理，不断向用户提问，把需求里模棱两可的地方一一敲碎、问透彻。比如用户说“实现一个用户登录接口”，AI就会依次追问：登录方式有哪些？要不要记住密码功能？密码加密怎么处理？失败提示怎么设计？有没有防刷机制？一步步把模糊的描述变成一份完整的设计文档。

（2）using-git-worktrees：隔离工作空间
需求梳理完成之后，AI会创建一个独立的Git工作空间（git worktree），和主分支完全隔离。在这个工作空间里，还会验证当前代码的编译基线，确保依赖安装完整、代码能正常编译。这样开发过程中的任何变更都不会污染主分支。

（3）writing-plans：拆解bite-sized tasks
设计文档确定后，AI会执行writing-plans Skill，把需求拆成一系列“2-5分钟可完成”的小任务。比如“实现用户登录接口”，会被拆成：定义路由（2分钟）、编写参数校验逻辑（3分钟）、实现密码加密比对（4分钟）、编写响应逻辑（3分钟）、编写单元测试（5分钟）。每个任务都有明确的时间预估和执行目标，避免了“一锅粥”式的编码。

（4）subagent-driven-dev：子袋里隔离实现
这是Superpowers最核心也是最能打的阶段。AI扮演“Controller（编排者）”的角色，为每一个小任务派遣完全独立的子袋里，这些子袋里拥有独立的上下文，彼此之间绝不串场。

每个任务的执行过程是这样的：
1. Controller先派遣一个Implementer子袋里去写代码。它会先确认任务细节，有疑问就向用户提问，确认清楚后开始实现，同时按TDD要求编写测试用例。完成后自行审查，并向Controller上报状态（DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT）。
2. 接着Controller派遣一个Spec Reviewer子袋里，对照plan和设计文档，检查Implementer的输出是否符合需求。重点关注需求覆盖、场景遗漏、是否过度实现等问题。不通过就退回重改。
3. 最后Controller还会派一个Code Quality Reviewer子袋里，从代码规范、架构合理性、安全性、测试覆盖率等维度审查质量，将问题分级为Critical、Important、Minor，通知Implementer修复后再审。

这种多子袋里隔离的设计，最大的价值在于“客观性”。Implementer只管实现，Reviewer只管检查，审查者不会因为“这是我写的代码”而产生心理包袱。而且独立的上下文也避免了长对话中AI逻辑漂移的问题。

（5）finishing-branch：收尾工作
所有任务完成并通过审查后，AI执行finishing-a-development-branch Skill，完成最后的收尾：验证分支所有测试是否通过，创建PR并填写详细的变更描述，最后根据项目要求决定保留或丢弃当前分支。

3.3 核心特色1：强制TDD

Superpowers的另一大特征，就是“强制TDD”。在Plan阶段，每个task的步骤里就已经把TDD的流程写进去了。Implementer如果没有先写测试就开始写代码，Spec Reviewer会直接拒绝审查。

具体到每个task里的TDD步骤，长这样：

• Step 1：写失败测试（RED）——此时代码还没写，测试必然失败
• Step 2：运行确认失败——确保测试用例本身是有效的
• Step 3：写最小实现代码——只写能让测试通过的最少代码
• Step 4：运行确认通过（GREEN）——确认测试通过
• Step 5：提交——把代码和测试一起提交

这种强制TDD的设计，意味着每一行代码背后都有一组测试用例在为其背书。

3.4 核心特色2：两阶段审查

每个task完成后，必须经过两轮独立审查才能进入下一个task。两轮审查的关注点和先后顺序非常讲究：

注意这个顺序不是随意的：第一阶段审查必须在第二阶段之前。道理很简单——如果代码本身做的事情就不符合需求，那就算它的代码质量再高，也毫无意义。先确保“做对”，再确保“做好”，这个先后顺序本身就是一种效率。

四、OpenSpec与Superpowers深度对比：该怎么选？

OpenSpec和Superpowers都是SDD理念的优秀实践，但它们的侧重点、核心能力和适用场景有非常大的差异。下面从几个关键维度来一次彻底的对比，帮你快速找到适合自己项目的那个。

4.1 核心定位与哲学

4.2 工作流程对比

4.3 核心能力差异

（1）子袋里 vs 单袋里

（2）Spec管理

（3）测试策略

4.4 适用场景：选对框架才是关键

五、总结：SDD的终极目标，让AI写对每一行代码

把OpenSpec和Superpowers从头到底拆解一遍之后，你会发现一个有意思的事实：这两者虽然侧重点完全不同，但绕来绕去，它们都在解决同一个核心问题——AI写出来的代码，到底靠不靠谱？

OpenSpec的优势写在它的名字里：Spec驱动 + 变更追溯 + 知识积累。它能让每一次变更都有完整的设计文档作为支撑，形成项目级的规格知识库。适合那些需要长期维护、非常注重变更管理的大型项目。

Superpowers的优势也非常清楚：子袋里隔离 + TDD强制 + 自动化审查。它能让AI像一支有纪律的团队一样工作，每个环节都有独立的角色检查对错。更适合全新项目、或者对测试覆盖率和代码质量有严苛要求的场景。

但要注意的是，这两个框架不是非此即彼的关系，更像是两把互补的利器。在实际开发中，完全可以把它们结合起来用：用OpenSpec来做spec管理和变更追溯，保证每次变更都有据可查；同时从Superpowers那里借鉴它的审查和git worktree能力，强化合规审查，提升代码执行质量。最终的目标从来都不是去纠结选哪个，而是确保——AI写的每一行代码，都能做到有据可查、有规可循。