Superpowers 与 OpenSpec 使用指导手册

• Superpowers-lite 与 OpenSpec 通俗使用手册
• • 1. 先按你的真实开发方式理解
  • 2. 平时先用 Superpowers 的 5 个核心 skills
  • • 2.1 Superpowers 全量 skills 有 14 个
    • 2.2 Superpowers 的命令和 skills 不是一回事
  • 3. 做到什么程度才需要 OpenSpec
  • 4. OpenSpec 第一次介入时会生成什么
  • 5. OpenSpec 命令为什么有 11 个和 19 个两种说法
  • • 5.1 AI 聊天窗口里的 `/opsx` 命令：11 个
    • 5.2 终端里的 `openspec` CLI：你本机 1.3.1 有 19 个顶层命令
  • 6. 默认组合：Superpowers 主导，OpenSpec 记录
  • • 6.1 分工
    • 6.2 流程图
    • 6.3 例子：做登录功能
  • 7. 严格组合：OpenSpec 主导，Superpowers 辅助
  • • 7.1 分工
    • 7.2 流程图
    • 7.3 例子：做会员计费模块
  • 8. 两者会不会冲突
  • 9. 最短口诀

Superpowers-lite 与 OpenSpec 通俗使用手册

目标：让你知道什么时候用 Superpowers，什么时候拉 OpenSpec 进来，以及两者一起用时怎么不打架。

---

1. 先按你的真实开发方式理解

你从 0 到 1 做东西时，默认不要把流程搞重。最顺的方式是：

先让 Superpowers 管开发过程。
只有遇到值得长期记录的大功能，再让 OpenSpec 介入做记录。

也就是说，平时你只需要记住一句话：

Superpowers 负责“怎么把代码做出来”。
OpenSpec 负责“哪些需求变化要留下规范记录”。

后面所有命令和流程，都围绕这句话展开。

---

2. 平时先用 Superpowers 的 5 个核心 skills

Superpowers 本质上是一组给 AI 用的 skills。它不是要求你每一步都手动敲命令，而是让 AI 在合适的时候按这些 skills 工作。

你当前最适合默认启用这 5 个：

顺序	Skill	什么时候用	解决什么问题
1	brainstorming	你只有一个想法，还没讲清楚	把需求、边界、取舍问清楚
2	writing-plans	需求已经清楚，准备开发前	把需求拆成可执行计划
3	executing-plans	已经有计划，开始改代码	按计划一步步实现
4	test-driven-development	有核心逻辑、规则、算法、接口行为	先写测试，再写实现，避免拍脑袋
5	verification-before-completion	准备说“完成了”之前	跑测试、构建、检查，避免假完成

这 5 个已经能覆盖个人开发最常见的完整闭环：

想法 -> 需求 -> 计划 -> 实现 -> 测试 -> 验证

2.1 Superpowers 全量 skills 有 14 个

你不用一开始全装全用，但要知道完整 Superpowers 里还有哪些能力：

分组	Skills
需求与计划	brainstorming、writing-plans、executing-plans
测试与验证	test-driven-development、verification-before-completion
调试	systematic-debugging
Git / 分支	using-git-worktrees、finishing-a-development-branch
子代理 / 并行	subagent-driven-development、dispatching-parallel-agents
Review	requesting-code-review、receiving-code-review
元能力	using-superpowers、writing-skills

为什么你现在不需要默认全用：

worktree、分支收尾、子代理、代码 review 更适合团队协作或大型任务。
你个人从 0 到 1 开发，先用 5 个核心 skills 更轻。

2.2 Superpowers 的命令和 skills 不是一回事

你本机 Superpowers 仓库里能看到 3 个命令包装器：

命令包装器	对应 skill	作用
brainstorm	brainstorming	显式进入需求澄清
write-plan	writing-plans	显式要求写开发计划
execute-plan	executing-plans	显式要求按计划执行

这里要分清楚：

skills 是 AI 的工作规则。
命令包装器是手动点名某个 skill 的入口。

所以你不一定每次都要手动敲命令。你也可以直接对 AI 说：

用 Superpowers brainstorming 先帮我把这个功能需求梳理清楚。

---

3. 做到什么程度才需要 OpenSpec

如果只是改一个按钮、修一个小 bug、调一个样式，不需要 OpenSpec。

当你做到这类 事情时，再让 OpenSpec 介入：

场景	是否建议用 OpenSpec	原因
登录、权限、计费、订单、数据模型	建议	会影响长期业务规则
API 行为、数据库结构、核心流程	建议	后面别人或未来的你需要查依据
一次性小改动、文案、样式微调	不建议	记录成本大于收益

OpenSpec 介入时，不是先让它开发，而是先创建一条 change。

这里的 change 可以理解成：

一次值得记录的需求变化。
比如 add-login 就是一条“新增登录功能”的 change。

---

4. OpenSpec 第一次介入时会生成什么

当你在 AI 聊天窗口里说：

/opsx:propose add-login

OpenSpec 会围绕 add-login 这条 change 生成几类文件：

文件 / 目录	作用	你该怎么看
proposal.md	写为什么做、改什么、影响什么	这是变更说明
specs/	写需求、行为规则、场景	这是功能应该满足的规则
design.md	写技术方案、关键决策、风险取舍	这是实现思路
tasks.md	写实现任务清单	这是 OpenSpec 后续执行的依据

这几个文件的关系很简单：

proposal.md 说明为什么做。
specs/ 说明做成什么样。
design.md 说明怎么做。
tasks.md 说明按什么步骤做。

所以 OpenSpec 不只是“备忘录”。它也可以按 tasks.md 推进开发。问题在于：如果你已经让 Superpowers 写计划并执行，就不要再让 OpenSpec 同时执行第二套计划。

---

5. OpenSpec 命令为什么有 11 个和 19 个两种说法

这里不是冲突，是入口不同。

/opsx:* 是 AI 聊天窗口里的命令。
openspec 是终端 / PowerShell / CMD 里的 CLI 命令。

5.1 AI 聊天窗口里的 /opsx 命令：11 个

日常最常用的是这 5 个：

命令	作用
/opsx:propose	创建 change，并生成 proposal.md、specs/、design.md、tasks.md
/opsx:explore	先探索想法，不急着创建 change
/opsx:apply	按 tasks.md 推进实现
/opsx:sync	把 change 里的 specs/ 变化合并到主规范
/opsx:archive	功能完成后归档 change

扩展流程里还有 6 个：

命令	作用
/opsx:new	只创建 change 的基础结构
/opsx:continue	继续补下一类文件，比如先有 proposal，再补 specs
/opsx:ff	一次性补齐需要的 OpenSpec 文件
/opsx:verify	检查实现是否符合 specs/、tasks.md、design.md
/opsx:bulk-archive	批量归档多个 changes
/opsx:onboard	引导式熟悉 OpenSpec 流程

5.2 终端里的 openspec CLI：你本机 1.3.1 有 19 个顶层命令

这些是在 PowerShell  / CMD / 终端里敲的，不是在 AI 聊天窗口里敲的：

CLI 命令	作用
openspec init	初始化 OpenSpec
openspec update	更新 OpenSpec 指令文件
openspec list	列出 changes，或用 --specs 列出 specs
openspec view	打开交互式视图
openspec change	管理 change proposals
openspec archive	归档完成的 change，并更新主 specs
openspec spec	管理和查看 specs
openspec config	查看或修改全局配置
openspec schema	管理流程结构定义，属于高级配置
openspec validate	校验 changes 或 specs
openspec show	查看某个 change 或 spec
openspec feedback	提交反馈
openspec completion	管理 shell 自动补全
openspec status	查看某个 change 的文件完成状态
openspec instructions	输出创建文件或执行任务所需的指令
openspec templates	查看模板路径
openspec schemas	列出可用流程结构定义，属于高级配置
openspec new	创建新项目
openspec help	查看帮助

你日常不需要背 19 个。常用的是：

openspec list
openspec show <name>
openspec validate <name> --strict
openspec archive <name>

---

6. 默认组合：Superpowers 主导，OpenSpec 记录

这是最适合你现在的方式。

适合：

个人开发
从 0 到 1
需求还会变化
不想一开始就进入重流程

6.1 分工

工具	负责什么	不负责什么
Superpowers	澄清需求、写计划、执行计划、TDD、完成前验证	不负责长期规范归档
OpenSpec	记录重要 change，最后归档	不执行 /opsx:apply

关键规则：

Superpowers 主导时，不要用 /opsx:apply。
因为 Superpowers 的 executing-plans 已经在负责执行。

6.2 流程图

标记说明：

SP = Superpowers skill
OS = OpenSpec /opsx 命令

SP: brainstorming 梳理需求

这次是否值得长期记录

SP: writing-plans 写开发计划

OS: /opsx:propose 创建 change

OpenSpec 生成 proposal/specs/design/tasks

SP: executing-plans 按计划实现

SP: test-driven-development 覆盖核心逻辑

SP: verification-before-completion 跑验证

是否创建过 OpenSpec change

结束

OS: /opsx:archive 归档 change

6.3 例子：做登录功能

你可以这样对 AI 说：

我要做登录功能。
这次以 Superpowers-lite 为主流程。

先用 brainstorming 帮我澄清需求。
登录会影响长期业务规则，所以用 /opsx:propose add-login 记录一条 OpenSpec change。

OpenSpec 只负责生成和维护 proposal/specs/design/tasks。
开发计划用 writing-plans 来写。
实现用 executing-plans 来做。
核心认证逻辑用 test-driven-development。
完成前用 verification-before-completion 跑测试和构建。

不要用 /opsx:apply。
验证通过后，用 /opsx:archive add-login 归档。

这套方式里只有一个开发主线：

开发听 Superpowers 的。
OpenSpec 只留下重要需求变化的记录。

---

7. 严格组合：OpenSpec 主导，Superpowers 辅助

如果你想让需求、设计、任务全部先落成文件，再按文件执行，就让 OpenSpec 主导。

适合：

需求比较确定
功能影响面大
你想先写 proposal/specs/design/tasks
你愿意接受更强流程

7.1 分工

工具	负责什么	不负责什么
OpenSpec	创建 proposal.md、specs/、design.md、tasks.md，并用 /opsx:apply 推进实现	不只是记录
Superpowers	TDD 和完成前验证	不再写第二套计划

关键规则：

OpenSpec 主导时，不要再用 writing-plans / executing-plans。
因为 OpenSpec 已经有 design.md、tasks.md 和 /opsx:apply。

7.2 流程图

标记说明：

OS = OpenSpec /opsx 命令
SP = Superpowers skill

OS: /opsx:propose 创建 change

OpenSpec 生成 proposal/specs/design/tasks

OS: /opsx:apply 按 tasks.md 实现

SP: test-driven-development 补强核心逻辑测试

SP: verification-before-completion 跑真实验证

OS: /opsx:verify 检查实现是否符合 specs/tasks/design

OS: /opsx:archive 归档 change

7.3 例子：做会员计费模块

你可以这样对 AI 说：

我要做会员计费模块。
这次以 OpenSpec 为主流程。

请用 /opsx:propose add-membership-billing 生成 proposal/specs/design/tasks。
然后用 /opsx:apply 按 tasks.md 实现。

核心计费规则用 test-driven-development 辅助。
完成前用 verification-before-completion 跑测试和构建。
再用 /opsx:verify 检查实现是否符合 specs/tasks/design。
最后用 /opsx:archive add-membership-billing 归档。

不要再用 Superpowers writing-plans / executing-plans 写第二套计划。

这套方式里也是只有一个开发主线：

开发听 OpenSpec 的。
Superpowers 只补测试纪律和完成前验证。

---

8. 两者会不会冲突

它们不会天然冲突，冲突来自你让两边同时做同一件事。

最容易重复的 是这两组：

重复点	Superpowers	OpenSpec	怎么避免
写计划	writing-plans	design.md、tasks.md	只选一个作为主计划
执行开发	executing-plans	/opsx:apply	只选一个作为主执行

所以核心规则不是“谁更强”，而是：

一件事只选一个主流程。
另一个只能辅助，不要抢主流程。

---

9. 最短口诀

小改动：只用 Superpowers。

大功能，但你想轻一点：
Superpowers 主导，OpenSpec 记录。

大功能，而且你想严格按规范推进：
OpenSpec 主导，Superpowers 辅助。

永远不要：
Superpowers 和 OpenSpec 同时各写一套计划、各执行一遍开发。