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 和 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 -->|反馈| B

2.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 都必须遵守它。

包含内容:

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 局限


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 标记来描述增量变化:

**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 局限


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"] -.->|完成前必须| E

4.5 六个核心 Skill 详解

brainstorming(第一道硬门禁)

任何新功能都必须先过这一关,不允许直接写代码。Skill 强制 Agent 进入苏格拉底式问答:

设计确认后才能进入下一步。在这之前,任何代码编写、脚手架生成、实现操作都被禁止。

using-git-worktrees(隔离实验)

设计批准后,自动创建 Git Worktree 隔离工作空间。不是简单开个分支——它会跑项目构建、验证测试基线干净,确保后续出的问题都是"这次改出来的"。

writing-plans(极致粒度)

把设计文档拆成 2-5 分钟的任务。铁律:每一步都必须包含完整的代码、精确的文件路径、可运行的命令和预期输出。

为什么这么极端?因为计划的执行者是一个全新的 Subagent——没有项目上下文、没有判断力、天然倾向跳过测试。计划必须详细到"复制粘贴就能跑"。

subagent-driven-development(核心执行引擎)

基于一个关键观察:长上下文对话会降低模型输出质量。随着 Token 累积,模型开始忘记约束、混淆边界、偏离计划。

解决方案:每个任务派一个全新的 Subagent,只给当前任务的指令和相关代码,不给历史包袱。

每个任务经过三道关:

  1. 实现者 Subagent 完成编码
  2. Spec 合规审查 Subagent 检查是否符合设计(关键指令:"Do Not Trust the Report"——必须自己读代码验证,不能只看实现者的报告)
  3. 代码质量审查 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 会用各种"合理"的借口跳过步骤——"这个太简单了不需要设计"、"先写代码再补测试效率更高"、"让我先探索一下"。

应对策略:

4.7 局限


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完全实战指南