SDD框架对比实战指南-SpecKit-OpenSpec-Superpowers
前言
上一篇文章讲了 Spec-Driven Development 的方法论。道理都懂了,但真到要落地的时候,你会发现货架上已经摆满了框架——GitHub 的 Spec Kit 有 137K Stars,Fission-AI 的 OpenSpec 有 62K Stars,Jesse Vincent 的 Superpowers 更是拿下了 288K Stars。
选哪个?
这不是"哪个更好"的问题,而是三种完全不同的 SDD 落地路线:
- Spec Kit:文档驱动,Constitution 立法 + 五步流水线生成 Spec 文件
- OpenSpec:变更驱动,以 Delta 标记追踪每次改动,专为老项目设计
- Superpowers:行为驱动,把开发纪律编码成 Agent 的"肌肉记忆",自动触发 TDD、审查、分支管理
一句话概括:Spec Kit 和 OpenSpec 关注"写什么"——怎么把需求变成高质量的 Spec 文件。Superpowers 关注"怎么做"——怎么让 Agent 在实现时不偷工减料。
1. 三种方案速览
| 维度 | Spec Kit | OpenSpec | Superpowers |
|---|---|---|---|
| 创建者 | GitHub | Fission-AI | Jesse Vincent / Prime Radiant |
| GitHub Stars | ~137K | ~62K | ~288K |
| 核心理念 | Constitution 立法 + 文件流水线 | 变更提案 + Delta 追踪 | 行为约束 + Subagent 三重审查 |
| 技术栈 | Python (uv/pipx) | TypeScript (npm) | Shell + JS(Plugin 机制) |
| 最适合 | 新项目从零开始 | 老项目加功能 | 重视代码质量和工程纪律的团队 |
| 落地路线 | 文档驱动 | 变更驱动 | 行为驱动 |
| Agent 兼容 | 30+ 工具 | 25+ 工具 | 7 个(Claude Code、Codex、Cursor、Copilot CLI、Gemini CLI、OpenCode) |
| 安装方式 | uv tool install | npm install -g | 各 Agent 的 Plugin 机制 |
2. Spec Kit 深度解析
2.1 先说人话
Spec Kit 是 GitHub 官方出品的 SDD 工具包。核心操作:先写一份"宪法"(Constitution)定义项目规矩,然后通过 CLI 逐步生成 Spec -> Plan -> Tasks -> Implementation。
所有生成的文件都存在 .specify/ 目录里,跟代码一起版本化。
2.2 工作流
flowchart LR
A["/speckit.constitution
定义项目规矩"] --> B["/speckit.specify
写需求规格"]
B --> C["/speckit.plan
设计实现方案"]
C --> D["/speckit.tasks
拆解任务列表"]
D --> E["/speckit.implement
逐步实现"]
E -->|反馈| B2.3 安装与初始化
# 安装 CLI(需要 Python 3.11+ 和 uv)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v1.0.0
# 在已有项目中初始化(以 Copilot 为例)
specify init . --ai copilot
# 检查环境
specify check
2.4 .specify/ 目录结构
.specify/
├── memory/ # 项目治理上下文
├── constitution.md # 项目宪法:编码规范、架构原则、禁止模式
├── spec.md # 需求规格:做什么、为什么做
├── plan.md # 实现方案:架构设计、技术选型
└── tasks.md # 任务清单:逐步实现的 checklist
2.5 Constitution 概念
这是 Spec Kit 最有特色的设计。constitution.md 是一份项目级的"宪法",所有后续生成的 Spec、Plan、Tasks 都必须遵守它。
包含内容:
- 编码风格规则("所有函数必须有 JSDoc 注释")
- 架构约束("数据层不允许直接调用 HTTP")
- 禁止模式("不允许使用 try-catch 吞异常")
- 测试要求("每个公共方法必须有单元测试")
Constitution 相当于给 Agent 一个持久化的 System Prompt,而且是团队共享、版本化的。
但有一个已知问题:EPAM 的案例研究发现,Agent 有时会无视 Constitution 中的规则。原因是 Constitution 只写了"不允许做 X",没解释为什么——模型遵循带理由的规则比裸禁令效果好得多。
2.6 扩展生态
Spec Kit 有一个庞大的扩展市场,60+ 社区扩展,分五类:
| 类别 | 作用 | 典型扩展 |
|---|---|---|
docs | 读取/验证/生成 Spec | QA Testing、Security Review |
code | 审查/修改代码 | Red Team、Verify |
process | 编排工作流 | Fleet Orchestrator、MAQA |
integration | 对接外部平台 | Jira、Azure DevOps、Linear |
visibility | 项目健康度报告 | 各类 Dashboard |
2.7 局限
- 绿地优先:为新项目设计,老项目改造是短板(微软最近才加了 brownfield 模块)
- Spec 不累积:每个功能的 Spec 是独立的,不会汇聚成系统级文档
- Constitution 可被绕过:Agent 不一定遵守,需要写明理由
- 全流程开销大:一个小 bug fix 走完五步流水线,明显过重
3. OpenSpec 深度解析
3.1 先说人话
OpenSpec 是 Fission-AI 做的轻量级 SDD 框架,专为老项目加功能设计。核心特色是 Delta 标记系统——每次变更不是重写整个 Spec,而是标记"新增/修改/删除了什么"。
它的哲学是"流动的,不是僵硬的;迭代的,不是瀑布的"。
3.2 工作流
flowchart LR
A["/opsx:propose
提出变更提案"] --> B["自动生成
proposal + specs + design + tasks"]
B --> C["/opsx:apply
逐步实现任务"]
C --> D["/opsx:verify
验证实现"]
D --> E["/opsx:archive
归档完成的变更"]
D -->|spec 漂移| F["/opsx:sync
同步 Spec 与代码"]3.3 安装与初始化
# 安装(需要 Node.js >= 20.19.0)
npm install -g @fission-ai/openspec@latest
# 初始化项目
openspec init
# 选择工作流配置(standard 或 expanded)
openspec config profile
3.4 目录结构
openspec/
├── project.md # 项目整体上下文
├── changes/
│ ├── add-auth-login/ # 每个变更一个文件夹
│ │ ├── proposal.md # 为什么做、改什么
│ │ ├── specs/ # 需求和场景
│ │ ├── design.md # 技术方案
│ │ └── tasks.md # 实现清单
│ └── archive/
│ └── 2026-04-20-fix-routing/ # 已完成的变更归档
└── ...
3.5 Delta 标记系统
这是 OpenSpec 的杀手特性。当你在老项目上加功能时,Spec 不是从头写——而是用 Delta 标记来描述增量变化:
ADDED:新增的功能/接口/文件MODIFIED:修改的已有逻辑REMOVED:删除的旧代码/行为
**Delta 标记的价值:防止 Agent 在实现新功能时"顺手"改了不该改的东西。**它给了 Agent 一个明确的边界——"只动标记了的部分,其他不许碰"。
完成后,Delta 会合并进主 Spec,这样系统级文档会随时间越来越完整,而不是像 Spec Kit 那样每个功能的 Spec 各自为政。
3.6 两种工作流 Profile
| Profile | 命令 | 适合 |
|---|---|---|
| Standard | propose -> apply -> archive | 快速迭代、小变更 |
| Expanded | 增加 new、continue、ff、verify、sync、bulk-archive、onboard | 复杂项目、多变更并行 |
3.7 /opsx:sync 解决 Spec Drift
Spec Drift(规格漂移)是所有 SDD 框架的头号敌人——Agent 实现过程中做了调整,但 Spec 没更新。
OpenSpec 的 /opsx:sync 命令可以反向同步:读取当前代码状态,更新 Spec 文件。这不是完全自动化,但比手动维护好得多。
3.8 局限
- 单 Agent 模式:没有多 Agent 编排能力,一个 Agent 跑全流程
- Sync 仍需手动触发:Spec 不会自动跟代码同步
- 小任务过重:一个 bug fix 要走 proposal -> design -> tasks,有点杀鸡用牛刀
4. Superpowers 深度解析
4.1 先说人话
Superpowers 是 Jesse Vincent(obra)和 Prime Radiant 团队做的 Agent 技能框架。它不生成 Spec 文件——它把开发纪律编码成 Agent 的自动行为:先问清楚再动手、先写测试再写代码、每个任务都要审查、完成前必须验证。
你不需要主动调用任何命令。Skills 自动触发——"Your coding agent just has Superpowers."
这是三个框架中 Stars 最多的项目(288K+),也是唯一一个不以 Spec 文件为中心的 SDD 方案。
4.2 安装
Superpowers 通过各 Agent 的 Plugin 机制安装,不需要额外的 CLI:
# Claude Code(官方 Plugin 市场)
/plugin install superpowers@claude-plugins-official
# OpenAI Codex CLI
# /plugins → 搜索 superpowers → 安装
# Cursor
# /add-plugin superpowers(在 Agent 聊天中执行)
# Gemini CLI
gemini extensions install https://github.com/obra/superpowers
# GitHub Copilot CLI
copilot plugin marketplace add
copilot plugin install superpowers
安装后,Agent 会自动加载 CLAUDE.md(或 AGENTS.md、GEMINI.md),Skills 从此刻开始生效。
4.3 三层架构
Layer 1 — 核心工作流 Skills
brainstorming → git-worktrees → writing-plans → subagent-driven-development → finishing-a-development-branch
Layer 2 — 辅助 Skill 库
systematic-debugging / verification-before-completion / dispatching-parallel-agents / receiving-code-review
Layer 3 — 行为规则层
Skills 不是建议,是强制工作流。Agent 在每个任务前自动检查并加载相关 Skill。
4.4 核心流水线
flowchart LR
A["brainstorming
苏格拉底式问答"] --> B["using-git-worktrees
隔离工作空间"]
B --> C["writing-plans
2-5 分钟粒度任务"]
C --> D["subagent-driven-development
Subagent 逐任务实现"]
D --> E["finishing-a-development-branch
merge / PR / 丢弃"]
F["test-driven-development"] -.->|贯穿全程| D
G["requesting-code-review"] -.->|每个任务后| D
H["verification-before-completion"] -.->|完成前必须| E4.5 六个核心 Skill 详解
brainstorming(第一道硬门禁)
任何新功能都必须先过这一关,不允许直接写代码。Skill 强制 Agent 进入苏格拉底式问答:
- 先读上下文:现有代码、文档、最近提交,不是上来就问
- 一次只问一个问题:防止用户遗漏、防止模型自己脑补答案
- 提出 2-3 个方案:强制做方案对比,不能只给一个"最佳方案"
- 分段确认:设计拆成小节,每节等你点头再继续
设计确认后才能进入下一步。在这之前,任何代码编写、脚手架生成、实现操作都被禁止。
using-git-worktrees(隔离实验)
设计批准后,自动创建 Git Worktree 隔离工作空间。不是简单开个分支——它会跑项目构建、验证测试基线干净,确保后续出的问题都是"这次改出来的"。
writing-plans(极致粒度)
把设计文档拆成 2-5 分钟的任务。铁律:每一步都必须包含完整的代码、精确的文件路径、可运行的命令和预期输出。
为什么这么极端?因为计划的执行者是一个全新的 Subagent——没有项目上下文、没有判断力、天然倾向跳过测试。计划必须详细到"复制粘贴就能跑"。
subagent-driven-development(核心执行引擎)
基于一个关键观察:长上下文对话会降低模型输出质量。随着 Token 累积,模型开始忘记约束、混淆边界、偏离计划。
解决方案:每个任务派一个全新的 Subagent,只给当前任务的指令和相关代码,不给历史包袱。
每个任务经过三道关:
- 实现者 Subagent 完成编码
- Spec 合规审查 Subagent 检查是否符合设计(关键指令:"Do Not Trust the Report"——必须自己读代码验证,不能只看实现者的报告)
- 代码质量审查 Subagent 检查代码质量和测试覆盖
Critical issues 直接阻断流程,不允许带伤前进。
test-driven-development(最刚性的 Skill)
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
先写测试、看它失败、写最少的代码让它通过、重构。如果先写了实现代码再补测试?删掉代码,从头来。不是"调整一下",不是"留着参考",是删掉重来。
Skill 里有一张 11 行的"合理化借口表",把所有"这次可以例外"的理由逐条驳回。
verification-before-completion(证据优先)
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
不允许说"应该能用了"、"我很有信心"。必须跑命令、看输出、确认退出码,然后才能说"完成了"。
4.6 反合理化工程
Superpowers 最独特的设计不是流程本身,而是它如何确保 Agent 不跳过流程。
Jesse Vincent 团队在实测中发现,Agent 会用各种"合理"的借口跳过步骤——"这个太简单了不需要设计"、"先写代码再补测试效率更高"、"让我先探索一下"。
应对策略:
- 合理化借口表:每个 Skill 列出 Agent 可能用来跳过的所有理由,逐条反驳
- 红旗清单:识别 Agent 正在偷偷跳过流程的信号
- 基础原则:如 "违反规则的字面意思就是违反规则的精神"——堵死所有"精神 vs 字面"的漏洞
- 四条硬规则:
- 设计批准前不许写代码
- 任务必须拆到可执行粒度
- 没有失败测试就没有生产代码
- Critical review 发现问题必须阻断
4.7 局限
- 前期交互成本高:brainstorming 阶段会显著拉长开发启动时间
- 不是所有任务都值得走全流程:一个错别字修复不需要设计 -> 计划 -> 审查的完整链路
- Token 消耗高:每个任务三次 Subagent 调用(实现 + Spec 审查 + 代码审查)
- 不生成系统级 Spec:产出的是代码和计划文档,不是可累积的系统规格说明
- Skill 质量决定一切:框架的效果完全取决于 Skill 写得好不好
5. 七个关键维度对比
| 维度 | Spec Kit | OpenSpec | Superpowers |
|---|---|---|---|
| Brownfield 支持 | 弱(正在补强) | 强(Delta 标记专为此设计) | 中性(不关心新旧,关注流程) |
| Spec Drift 应对 | /speckit.reconcile 扩展 | /opsx:sync 内建命令 | 不存在此问题(不维护独立 Spec 文件) |
| 多 Agent 编排 | 无(单 Agent 逐步执行) | 无(单 Agent 全流程) | 有(Subagent 实现 + 双重审查) |
| 代码审查内建 | 需安装扩展 | 无 | 内建(每个任务自动三重审查) |
| 安装复杂度 | 中(Python + uv) | 低(npm 一行) | 低(各 Agent 的 Plugin 一键安装) |
| Token 消耗 | 中(每步一次 LLM 调用) | 低(轻量流程) | 高(每任务三次 Subagent 调用) |
| 可移植性 | 高(30+ Agent 兼容) | 高(25+ Agent 兼容) | 中(7 个 Agent,核心体验在 Claude Code) |
6. 实战:同一个需求,三种做法
需求:给一个 Go CLI 项目加一个 auth login 命令,支持 OAuth2 授权码流程。
6.1 Spec Kit 做法
# 第一步:定义 Constitution(只做一次)
/speckit.constitution Create principles: Go 1.22+, cobra CLI framework,
no global state, table-driven tests, error wrapping with fmt.Errorf
# 第二步:写 Spec
/speckit.specify Add an "auth login" command that initiates OAuth2
authorization code flow, opens browser, starts local callback server,
exchanges code for token, stores token securely in ~/.config/myapp/
# 第三步:生成 Plan
/speckit.plan Use cobra for command structure, golang.org/x/oauth2
for OAuth, keyring for token storage
# 第四步:拆 Tasks
/speckit.tasks
# 第五步:实现
/speckit.implement
产出物在 .specify/ 目录,实现完成后 Spec 文件保留作为文档。
6.2 OpenSpec 做法
# 初始化(只做一次)
openspec init
# 提出变更提案——一条命令搞定
/opsx:propose Add auth login command with OAuth2 authorization code
flow, browser-based login, local callback server, secure token storage
# 自动生成:
# openspec/changes/add-auth-login/
# ├── proposal.md (ADDED: auth login command, MODIFIED: root command registration)
# ├── specs/
# ├── design.md
# └── tasks.md
# 实现所有任务
/opsx:apply
# 验证
/opsx:verify
# 归档
/opsx:archive
Delta 标记会明确标注哪些是新增、哪些是对现有代码的修改,防止 Agent 越界。
6.3 Superpowers 做法
# 你只需要说一句话:
> 我要给 CLI 加一个 auth login 命令,支持 OAuth2
# brainstorming 自动触发——Agent 开始苏格拉底式追问:
Agent: 先看了一下现有代码结构... cobra 框架,已有 auth 目录。
Agent: OAuth2 用哪种 flow?Authorization Code 还是 Device Code?
你: Authorization Code
Agent: Token 存哪里?keyring 还是文件?
你: keyring
Agent: headless 环境怎么处理?
你: 不考虑,只支持有浏览器的环境
Agent: 这是我的设计方案,分三部分确认...
# 设计确认后 → 自动创建 Git Worktree
# → 自动生成实现计划(每步 2-5 分钟)
# → 自动派 Subagent 逐任务执行:
Task 1: 写 auth login command 骨架
→ 实现者 Subagent → Spec 审查 Subagent → 代码审查 Subagent ✓
Task 2: 写 OAuth2 flow + 本地回调服务器
→ 实现者 → Spec 审查 → 代码审查 ✓
Task 3: 写 keyring token 存储
→ 实现者 → Spec 审查 → 代码审查 ✓
Task 4: 集成测试
→ 实现者 → Spec 审查 → 代码审查 ✓
# finishing-a-development-branch 自动触发:
Agent: 所有测试通过。你要 merge / 创建 PR / 保留分支 / 丢弃?
6.4 三种做法的关键区别
| 环节 | Spec Kit | OpenSpec | Superpowers |
|---|---|---|---|
| 需求澄清 | 人工写清楚传给 CLI | 人工写 proposal | Agent 主动 interview 你 |
| 方案设计 | LLM 一次性生成 plan.md | LLM 生成 design.md | 交互式苏格拉底问答,2-3 选项 |
| 任务执行 | 单 Agent 顺序执行 | 单 Agent 顺序执行 | Subagent 隔离执行 + 三重审查 |
| TDD 保障 | 靠 Constitution 要求 | 靠 Spec 描述 | 内建强制 TDD Skill |
| 质量保障 | Constitution 约束 | Delta 边界限制 | Subagent 审查 + Critical 阻断 |
| 产出物 | .specify/ Markdown | openspec/changes/ Markdown | 代码 + Git 分支 + 计划文档 |
| 人的参与度 | 高(每步都要人写输入) | 中(一条 propose 命令) | 低(说一句话,Agent 追问) |
7. 高阶玩法:框架组合
社区已经在探索混合使用多个框架。核心思路来自一篇 dev.to 文章提出的"三层模型":
| 层 | 关注点 | 框架 |
|---|---|---|
| Decision(决策) | 做什么、要不要做 | Spec Kit / OpenSpec |
| Context(上下文) | Spec 稳定性、防漂移 | OpenSpec(Delta + Sync) |
| Execution(执行) | 怎么做、质量保障 | Superpowers |
最务实的组合:用 OpenSpec 管理 Spec 文件和变更追踪 + 用 Superpowers 驱动执行流程和质量保障。一个管"写什么",一个管"怎么做"。
这种组合天然解决了一个问题:OpenSpec 的短板是没有多 Agent 编排和内建审查;Superpowers 的短板是不生成可累积的 Spec 文档。组合起来刚好互补。
8. 决策指南
你在做全新项目吗?
→ 是:Spec Kit(Constitution 帮你从第一行代码就立规矩)
→ 否 ↓
你在给老项目加功能?
→ 是:OpenSpec(Delta 标记防止 Agent 乱改已有代码)
→ 否 ↓
你重视代码质量、想要自动化的 TDD 和审查?
→ 是:Superpowers(Subagent 三重审查 + 内建 TDD)
→ 否 ↓
你的团队混用多种 AI 工具?
→ 是:Spec Kit 或 OpenSpec(Agent 无关,Spec 文件即接口)
→ 否 ↓
你需要审计追踪和合规?
→ 是:考虑 BMad Method(不在本文范围,但它专为此设计)
→ 否:选摩擦最低的那个——大多数情况是 OpenSpec
一个容易忽略的洞察:
Spec Kit 和 OpenSpec 解决的是"信息问题"——怎么让 Agent 拿到足够好的上下文。Superpowers 解决的是"行为问题"——怎么让 Agent 在拿到上下文后不偷工减料。
这两个问题是正交的。当前所有 SDD 框架的共同短板是 Spec Drift——Spec 和代码逐渐脱节。Spec Kit 和 OpenSpec 用 reconcile/sync 做"事后补救";Superpowers 用另一种思路——不维护独立 Spec 文件,把规范编码在流程中,Agent 每次执行都重新走流程,天然没有漂移。
但代价也很明显:没有可积累的系统级文档。当你需要给新人看"这个系统整体长什么样"的时候,Superpowers 不会帮你留下这份资产。所以,混合使用才是最优解。
9. 核心参考资料
| 资料 | 来源 |
|---|---|
| Superpowers 官方仓库 | github.com/obra/superpowers |
| GitHub Spec Kit 官方仓库 | github.com/github/spec-kit |
| OpenSpec 官方仓库 | github.com/Fission-AI/OpenSpec |
| Superpowers 工程化工作流分析 | apframework.com |
| Superpowers + gstack + GSD 组合方案 | dev.to/imaginex |
| Superpowers Skills Framework 研究 | rywalker.com |
| Spec Kit vs BMad vs OpenSpec 对比 | dev.to/willtorber |
| SDD 框架深度对比 | besthub.dev |
| OpenSpec 介绍 | rushis.com |
| GitHub Spec Kit 实验报告 | Visual Studio Magazine |
| OpenSpec Cursor 社区讨论 | forum.cursor.com |
| Spec-Driven Development 完全实战指南 | Spec-Driven Development完全实战指南 |