1.1 Superpowers#

Superpowers 是由 Jesse Vincent（obra）维护的 AI Agent 工程化开发工作流集合，核心理念是 Process over Prompt（流程大于提示词）。它通过一系列结构化的子技能，约束 AI 在编码前完成思考、规划、验收条件定义，在编码中遵循 TDD、子代理审查、代码审查，在编码后完成验证与分支收尾。

核心价值：

• 将资深工程师的工作纪律（TDD、代码审查、验证优先）编码为 AI 可遵循的流程。
• 防止 AI 一上来就写代码导致方向偏离。
• 通过强制验证与审查环节，减少”看起来对了但测试没跑”的回归风险。

1.2 OpenSpec#

OpenSpec 是由 Fission AI 开源的规范驱动开发框架，核心理念是 Spec before Code（代码之前先写规范）。它通过结构化工件（proposal、specs、design、tasks）将需求意图、行为契约、技术方案与实现任务固化下来，作为人类与 AI 之间的”真相源”。

核心价值：

• 在 AI 写任何一行代码之前，先对齐需求范围与验收条件。
• 通过 Delta Specs 机制让规范像代码一样版本化演进。
• 将 BDD 风格的 Given/When/Then 场景直接转化为测试与验证依据。

2.1 Superpowers 的功能特性与应用场景#

2.2 OpenSpec 的功能特性与应用场景#

3.1 Superpowers 使用步骤#

Superpowers 以 Claude Code 插件形式运行，安装后自动生效。日常开发中 AI 会根据当前任务自动匹配并调用相关子技能。

典型执行流程：

3.2 OpenSpec 使用步骤#

OpenSpec 通过 CLI 与 AI 命令两种方式工作。

快速路径：

探索路径（需求模糊时使用）：

精细路径（复杂项目、团队协作）：

4.1 Superpowers 子技能#

Superpowers 共包含 14 个子技能，覆盖完整 SDLC：

4.2 OpenSpec 命令与能力#

5.1 环境要求#

• Node.js：≥ 20.19.0（OpenSpec CLI 要求）
• AI 客户端：Claude Code（Superpowers 与 OpenSpec 命令均支持）
• Git：用于工作区隔离与变更归档

5.2 安装 Superpowers#

1
/plugin marketplace add obra/superpowers-marketplace
2
/plugin install superpowers@superpowers-marketplace

安装后无需手动触发，AI 会在每次任务前自动检查适用的子技能。

5.3 安装 OpenSpec#

1
# 安装 CLI
2
npm install -g @fission-ai/openspec@latest
3

4
# 在项目根目录初始化
5
cd your-project
6
openspec init --tools claude

初始化后会生成 .openspec 目录和 AGENTS.md 文件：

1
openspec/
2
├── specs/              # 系统当前行为规范（真相源）
3
│   └── <domain>/
4
│       └── spec.md
5
├── changes/            # 每个变更的工作区
6
│   └── <change-name>/
7
│       ├── proposal.md
8
│       ├── design.md
9
│       ├── tasks.md
10
│       └── specs/      # 增量规范（Delta Specs）
11
└── config.yaml

6.1 卸载 Superpowers#

1
/plugin uninstall superpowers

卸载后，AI 不再自动调用 Superpowers 子技能。已创建的工作区与 Git 分支不受影响。

6.2 卸载 OpenSpec#

1
# 卸载全局 CLI
2
npm uninstall -g @fission-ai/openspec

6.3 残留清理#

清理 Superpowers 残留：

1
# Claude Code 插件目录（默认位置）
2
rm -rf ~/.claude/plugins/superpowers

清理 OpenSpec 残留：

1
# 删除项目内的 OpenSpec 目录与文件
2
rm -rf .openspec
3
rm -f AGENTS.md
4

5
# 可选：删除已归档的变更记录
6
rm -rf openspec/

7.1 协同场景#

单独使用 OpenSpec，可以解决”想清楚”的问题；单独使用 Superpowers，可以解决”做对了”的问题。两者结合时，Spec 成为 TDD 的输入源，TDD 成为 Spec 的质量保障。

适合协同使用的场景：

• 新功能开发：需求需要结构化对齐，代码需要 TDD 与审查保障。
• 复杂重构：涉及多文件改动，需要明确边界条件与回归测试。
• 团队协作：Spec 作为人类与 AI 之间的契约，降低沟通歧义。
• 长期维护：archive 沉淀知识，worktree 隔离风险。

7.2 协同优势#

7.3 协同操作步骤#

7.4 实战示例：实现订单导出功能#

Step 1：OpenSpec 规划

1
/opsx:propose order-export

需求描述：

实现订单导出接口，支持按时间范围导出 CSV。单次最多 5000 条，时间范围不超过 31 天，只能导出当前租户数据。

OpenSpec 生成四个工件。审核后确认关键内容：

1
# proposal.md 要点
2
- 目标：订单导出 CSV 接口
3
- 范围内：CSV 生成、权限校验、数量限制、时间范围校验
4
- 范围外：异步导出、邮件通知、Excel 格式
5

6
# specs/ 关键场景
7
Given 用户是 tenant-A 的管理员
8
When  请求导出 tenant-A 在 2024-01-01 到 2024-01-31 的订单
9
Then  返回 CSV，字段为 order_no, amount, status, created_at
10

11
Given 用户尝试导出 tenant-B 的数据
12
When  请求导出
13
Then  返回 403，错误信息为 "无权访问该租户数据"
14

15
# tasks.md 清单
16
1.1 创建 OrderExportController
17
1.2 实现 OrderExportService（查询 + CSV 生成）
18
1.3 添加权限校验（只能导出当前租户）
19
1.4 添加数量限制（≤5000 条）
20
1.5 添加时间范围校验（≤31 天）
21
1.6 编写单元测试（覆盖 4 种边界场景）

Step 2：Superpowers 执行

进入执行阶段后，Superpowers 自动接管：

1
🧠 brainstorming：对 task 1.1 做需求对齐
2
   → 确认 Controller 路径、请求参数格式、返回体结构
3

4
🌿 git worktree：创建隔离工作区
5
   → git worktree add ../project-order-export -b feat/order-export
6

7
🔴 TDD：先写失败测试
8
   → test: 导出正常路径返回 CSV
9
   → test: 超过 5000 条返回 400
10
   → test: 越权租户返回 403
11
   → test: 时间范围超限返回 400
12

13
🟢 实现：让测试通过
14
   → 实现 Controller、Service、权限校验
15

16
🔵 验证：verification-before-completion
17
   → 贴出 mvn test 输出
18
   → 贴出 git diff --stat
19

20
🔍 代码审查：requesting-code-review
21
   → 子代理检查权限绕过风险、SQL 注入、边界条件

Step 3：协同收尾

1
/opsx:verify    # 检查实现是否覆盖所有 Spec 场景
2
/opsx:archive   # 归档，增量规范合并到主规范

Superpowers 的 finishing-a-development-branch 负责最终的测试验证与 Git 清理。

7.5 关键协同点#

1. Spec 是 TDD 的输入源：OpenSpec specs/ 中的 Given/When/Then 场景可直接转化为测试用例。
2. verify 对齐 Spec 与实现：Superpowers 的 verification-before-completion 关注”测试通过没”，OpenSpec 的 verify 关注”实现跟 Spec 对上了没”。
3. archive 沉淀知识：OpenSpec 归档规范，Superpowers 归档代码，两者共同形成可追溯的变更记录。

Q1：OpenSpec 与 Superpowers 必须一起使用吗？#

A：不是必须。OpenSpec 更适合需求复杂、需要结构化对齐的场景；Superpowers 更适合任何需要工程纪律的编码任务。两者组合可覆盖完整闭环，但单独使用也能产生价值。

Q2：Superpowers 安装后为什么不生效？#

A：检查以下三点：

1. 是否正确执行了 /plugin install 命令；
2. Claude Code 版本是否支持该插件；
3. 当前任务是否触发了相应的子技能（部分子技能只在特定场景下激活）。

Q3：OpenSpec 的 Spec 应该写到什么粒度？#

A：Spec 应描述行为契约（Given/When/Then），不写实现细节。判断标准：如果实现方式变了但外部行为不变，就不该出现在 Spec 里。

Q4：如何处理开发过程中的需求变更？#

A：回到 OpenSpec 修改 Spec，重新生成 Delta，然后再用 Superpowers 执行。不要在代码里绕过 Spec。

Q5：团队如何协作使用 OpenSpec？#

A：将 .openspec 目录纳入版本控制，每个变更独立目录，通过 PR 流程审核 proposal 与 specs。归档后的主规范作为团队共享的真相源。