obra/superpowers 保姆级部署教程：30 万星的开源 Agent 技能框架与编码方法论
一句话定位：GitHub 开源项目
obra/superpowers是一套面向编码智能体（coding agent）的完整软件开发方法论 + 可组合技能（skills）框架——装上之后，你的 Claude Code / Cursor / Codex / Gemini CLI 等编码 Agent 不会一上来就闷头写代码，而是先和你澄清需求、写设计文档、拆任务、走 TDD、做代码评审，再由子代理（subagent）逐个任务推进， autonomously 连续工作数小时不跑偏。slogan：A complete software development methodology for your coding agents, built on a set of composable skills and some initial instructions that make sure your agent uses them.
仓库地址：https://github.com/obra/superpowers · 许可证：MIT · ⭐ 310,037 · 由 Jesse Vincent 与 Prime Radiant 团队维护
▲ 图 0：Superpowers 官方应用图标（仓库 assets/app-icon.png，官方 logo）
一、项目简介
Superpowers 要解决的问题非常具体：现在的编码 Agent 虽然能力强，但普遍缺一套「工程纪律」——你说一句「帮我做个 React 待办列表」，它立刻开写，既不问你到底要什么，也不写设计、不拆任务、不先写测试，写完直接丢给你，出了问题也没有评审环节。Superpowers 把一整套成熟的软件工程实践（头脑风暴、规格澄清、写计划、TDD、代码评审、worktree 隔离、子代理并行）做成一组可被 Agent 自动触发的技能（skill），再用一段引导指令（using-superpowers）让 Agent 在每次会话开始时自动加载。
它不是一个独立的应用，而是一个插件/扩展，挂载在你已经在用的编码智能体之上。官方在 README 中列出了 16 种已支持的宿主：Claude Code、Antigravity、Codex App、Codex CLI、Cursor、Devin CLI、Factory Droid、Gemini CLI、GitHub Copilot CLI、Grok Build CLI、Kimi Code、OpenCode、Pi、Qwen Code、Hermes Agent、Muse——同一个仓库、同一套技能，跨宿主通用。多个宿主同时使用时，需要分别在每个宿主里各装一遍。
项目由 Jesse Vincent 与 Prime Radiant 团队维护，以 MIT 许可证开源；2025 年 10 月发布后迅速登顶，目前 Star 数已突破 31 万。官方也提供企业级商业支持（额外工具、托管额度），联系邮箱 sales@primeradiant.com。
二、功能特点
| 能力 | 说明 |
|---|---|
| 💡 头脑风暴先行 | brainstorming 技能在动手写代码前自动触发，通过提问把你真正想要的东西和动机逼出来，再把理解回放给你确认；小改动在聊天里敲定，大项目会产出一份 builder 可据此排期的书面设计文档 |
| 🗂️ 设计 → 计划 → 执行闭环 | 写计划（writing-plans）把工作拆成 2–5 分钟的小任务，每个任务都有精确文件路径、完整代码、验证步骤；执行时要么走子代理逐任务派发+评审（最严谨），要么在当前会话内联执行+最后整体评审（最省） |
| ✅ 强制 RED-GREEN TDD | test-driven-development 技能强制先写失败测试、看它失败、再写最小实现让它通过、再提交；测试之前写的代码会被要求删掉 |
| 🔍 系统化调试 | systematic-debugging 是一套四阶段根因定位流程，附带根因追踪、纵深防御、条件等待等技术；verification-before-completion 确保「真的修好了」再宣称完成 |
| 🌿 Git worktree 隔离 | using-git-worktrees 在设计批准后自动开新分支、建隔离工作区、跑项目初始化、确认干净的测试基线；finishing-a-development-branch 在任务结束时给出 merge / PR / 保留 / 丢弃选项并清理工作区 |
| 👀 代码评审 | requesting-code-review 在任务之间对照计划评审、按严重程度报告问题，关键问题会阻断进度；receiving-code-review 负责回应评审反馈 |
| 🤖 子代理驱动开发 | subagent-driven-development 给每个任务派发一个全新的子代理，任务完成后做两阶段评审（先看是否符合规格，再看代码质量）；dispatching-parallel-agents 支持并行子代理工作流 |
| 🐞 自我诊断 | diagnosing-superpowers 技能：当会话行为异常（技能误触发、该触发不触发、Agent 偏离计划），让 Agent 自己读会话记录、带行级证据给出诊断，还能打包一个脱敏的 bug 报告 |
| 🧩 跨宿主一致 | 同一套技能同时支持 Claude Code、Cursor、Codex、Gemini CLI、Copilot CLI 等 16 种宿主，技能行为在所有宿主上一致 |
| 🧰 技能可扩展 | writing-skills 技能教你按官方最佳实践创建新技能（含测试方法论）；技能行为测试基于 superpowers-evals 的 drill eval harness |
三、环境要求
- 宿主：一个支持插件/扩展机制的编码智能体。推荐首选 Claude Code（官方一等公民支持，带 SessionStart 钩子自动注入引导）；其他可选 Cursor、Codex App / CLI、Gemini CLI、GitHub Copilot CLI、Kimi Code、Qwen Code 等。
- 运行时：Superpowers 本身是 Markdown 技能 + 引导指令，不需要独立运行时；它随宿主 Agent 一起运行。从源码开发/调试技能时，需要对应宿主的 CLI 与 Node 环境。
- Git：使用 worktree 隔离工作流需要本机可用的 git；项目本身通过 git 克隆或插件市场分发。
- 网络：安装时需访问 GitHub 拉取插件；运行时默认会从官网加载 Prime Radiant logo（仅携带版本号的匿名遥测，100% 可选关闭）。
- 平台：宿主 Agent 能跑的地方（macOS / Linux / Windows 下的 WSL 等）即可，无额外 OS 限制。
四、保姆级部署步骤
下面以最主流的 Claude Code 为例给出完整安装路径；其他宿主的一行命令汇总在 4.3 节。
4.1 在 Claude Code 中安装（官方市场）
打开 Claude Code，在会话里直接输入斜杠命令安装 Anthropic 官方市场收录的版本：
/plugin install superpowers@claude-plugins-official安装完成后，using-superpowers 引导会在每个新会话开始时自动注入，技能随之自动触发。无需重启，开一个新会话即可生效。
4.2 在 Claude Code 中安装（Superpowers 自家市场）
如果你想同时装上 Superpowers 以及其他相关插件，也可以走官方维护的 marketplace：
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace两条命令依次执行即可。两种方式二选一，不要重复安装。
4.3 其他编码宿主一行安装
多宿主并存时，请在每个宿主里分别安装（OpenCode 明确说明即使你在别处装过也要单独装一遍）：
| 宿主 | 安装命令 |
|---|---|
| Antigravity | agy plugin install "https://github.com/obra/superpowers" |
| Cursor | 在 Agent 聊天里执行 /add-plugin superpowers，或在插件市场搜索 superpowers |
| Devin CLI | devin plugins install obra/superpowers |
| Factory Droid | droid plugin marketplace add "https://github.com/obra/superpowers" 然后 droid plugin install superpowers@superpowers |
| Gemini CLI | gemini extensions install "https://github.com/obra/superpowers" |
| GitHub Copilot CLI | copilot plugin marketplace add obra/superpowers-marketplace 然后 copilot plugin install superpowers@superpowers-marketplace |
| Grok Build CLI | grok plugin install superpowers@xai-official --trust |
| Kimi Code | /plugins install "https://github.com/obra/superpowers" |
| Pi | pi install git:github.com/obra/superpowers |
| Qwen Code | qwen extensions install obra/superpowers（提示时选 superpowers） |
| Hermes Agent | hermes plugins install obra/superpowers --enable，装完重启会话 |
| Muse | git clone "https://github.com/obra/superpowers.git" 然后 muse plugins install ./superpowers 与 muse plugins approve superpowers |
| Codex App | 侧边栏 Plugins → Coding 区找到 Superpowers → 点 + 按提示安装 |
| Codex CLI | 输入 /plugins 打开插件搜索界面，搜 superpowers，选 Install Plugin |
| OpenCode | 对 OpenCode 说：Fetch and follow instructions from "https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md" |
4.4 验证安装是否生效
最直接的验证方法：新开一个会话，对 Agent 说一句 Let's make a react todo list。如果安装成功，Agent 会在写任何代码之前自动触发 brainstorming 技能——开始反问你需求、和你确认设计，而不是直接开写。看到这个行为就说明 Superpowers 已经接管了你的编码工作流。
五、配置说明
Superpowers 安装后无需任何配置即可使用。技能会根据你正在做的任务自动判断该不该触发，你不需要手动调用。几个值得知道的开关：
- 关闭匿名遥测：brainstorming 技能有一个可选的可视化伴侣（visual companion），默认会从官网加载 Prime Radiant logo，请求里仅携带当前 Superpowers 版本号，不携带你的项目、提示词或 Agent 任何细节。要完全关闭，设置环境变量
SUPERPOWERS_DISABLE_TELEMETRY为任意真值；同时 Superpowers 也会尊重 Claude Code 的DISABLE_TELEMETRY与CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC两个退避开关。 - 技能行为是强制工作流而非建议：Agent 在任何任务前都会检查是否有相关技能，brainstorming / TDD / 代码评审等环节会被强制走一遍，而不是「可选参考」。
- 更新：Superpowers 的更新随宿主走，多数宿主是自动更新；Devin CLI / Gemini CLI / Qwen Code / Muse 等需要手动跑对应的 update 命令（如
devin plugins update superpowers、gemini extensions update superpowers、muse plugins update superpowers）。 - 企业支持：需要额外工具、托管额度或商业支持时，邮件联系 sales@primeradiant.com。
六、使用方法
6.1 标准工作流七步
Superpowers 接管后，一次完整的开发会长这样：
- brainstorming：你说要做什么，Agent 反问细节，把理解回放给你确认；小改动聊天里敲定，大项目产出书面设计文档。
- using-git-worktrees：设计批准后，Agent 自动开新分支、建隔离工作区、跑初始化、确认干净的测试基线。
- writing-plans：把工作拆成 2–5 分钟一个的小任务，每个任务有精确文件路径、完整代码、验证步骤。
- subagent-driven-development 或 executing-plans：要么给每个任务派发全新子代理（每个任务后评审一次，最严谨），要么在当前会话内联执行（最后整体评审一次，最省）。
- test-driven-development：实现阶段强制 RED-GREEN-REFACTOR——先写失败测试、看它失败、写最小实现、看它通过、提交。
- requesting-code-review：任务之间对照计划评审，按严重程度报告问题，关键问题阻断进度。
- finishing-a-development-branch：任务全部完成后，确认测试通过，给出 merge / PR / 保留 / 丢弃选项，并清理工作区。
官方描述：在这套流程下，Agent 连续 autonomously 工作数小时、不偏离你制定的计划，是很常见的情况。
6.2 会话出问题时自我诊断
如果某次会话行为异常——技能该触发没触发、不该触发乱触发、Agent 偏离计划、重复劳动、Token 消耗异常——直接对 Agent 说：
figure out what went wrong with superpowers in this session它会调用 diagnosing-superpowers 技能读当前会话记录、带行级证据给出诊断。要诊断更早的某次会话，带上会话 id：
figure out what went wrong with superpowers in session <id>该技能还能按你的要求打包一个脱敏的 bundle，用于向官方提 issue。
6.3 哲学底线
整个框架贯彻四条原则：测试驱动开发（永远先写测试）、系统化优于临时应对（流程优于猜）、把降低复杂度作为首要目标、证据优于声明（宣称成功前先验证）。
七、常见问题 FAQ
问一：Superpowers 是一个独立的 AI 编码工具吗？需要我把 Claude Code 换掉吗？
答：不是。它是一个插件/扩展，挂在你已经在用的编码智能体之上——Claude Code、Cursor、Codex、Gemini CLI、Copilot CLI 等都可以装。你不需要换工具，只是给现有 Agent 加上一套工程方法论。多个宿主同时用，就在每个宿主里各装一遍。
问二：装了之后为什么 Agent 不直接写代码，反而一直问我问题？
答：这正是设计目标。brainstorming 技能会在动手写代码前自动触发，先把你真正想要的东西和动机澄清出来，再把设计文档给你确认；确认之后才进入拆任务、写计划、TDD 的阶段。觉得被问烦了可以直接说「按你的理解继续」，但官方建议至少把设计文档过一遍再放行。
问三：Agent 写代码不先跑测试，或者跳过评审怎么办？
答：test-driven-development 技能强制 RED-GREEN-REFACTOR，测试之前写的代码会被要求删掉；requesting-code-review 在任务之间强制对照计划评审。如果某次会话技能没触发，让 Agent 跑 figure out what went wrong with superpowers in this session 自我诊断。
问四：会不会偷偷上传我的代码或对话？
答：默认的唯一对外请求是 brainstorming 可视化伴侣从官网加载 logo，请求里只带版本号，不带项目、提示词、对话内容，也不收集你的点击行为。设置环境变量 SUPERPOWERS_DISABLE_TELEMETRY 为任意真值即可完全关闭，它也尊重 Claude Code 的两个官方退避开关。
问五：怎么升级？多宿主怎么同步？
答：Claude Code 走插件市场自动更新；Devin CLI / Gemini CLI / Qwen Code / Muse 等需要手动跑对应 update 命令（如 gemini extensions update superpowers）。不同宿主之间互不影响，每个宿主独立维护自己安装的那份。
相关链接
- 项目仓库：obra/superpowers
- 官方发布公告：Superpowers release announcement（Jesse Vincent 博客）
- Claude Code 插件市场页：claude.com/plugins/superpowers
- Superpowers marketplace：obra/superpowers-marketplace
- 技能行为测试 harness：prime-radiant-inc/superpowers-evals
- 维护方官网：Prime Radiant
- 社区 Discord：加入 Discord
- 发布通知订阅：primeradiant.com/superpowers
- OpenCode 安装文档：docs/README.opencode.md
- Kimi Code 安装文档：docs/README.kimi.md