SDD规范双框架实测：AI代码可追溯方案排行榜

先下一个硬判断：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写的每一行代码，都能做到有据可查、有规可循。

来源：互联网