Superpowers 项目全面解析

一、项目是什么

Superpowers 是一套专为 AI 编程助手设计的软件开发方法论插件，支持 Claude Code、OpenAI Codex、Cursor、Gemini CLI 等多个平台。

它的核心价值：让 coding agent 不直接拍脑袋写代码，而是像有纪律的工程团队一样工作------先理解需求、再规划方案、再逐步实现、最后验证。

二、如何生效

生效机制

Superpowers 通过 SessionStart Hook 自动注入上下文，无需用户手动操作。

复制代码

插件安装 → 注册 Hook → 每次会话启动 → 自动触发

具体流程：

用户安装插件（Claude Code marketplace、npm、手动安装等）
插件向 Claude Code 注册 SessionStart 事件钩子（定义于 hooks/hooks.json）
每次新对话启动时，钩子脚本 hooks/session-start 自动运行
脚本读取 skills/using-superpowers/SKILL.md 的内容，将其作为 EXTREMELY_IMPORTANT 注入到 AI 的 system prompt 中
using-superpowers 这个引导 skill 告诉 AI：每次收到消息前，先检查是否有适用的 skill，有的话必须调用
AI 使用 Skill 工具按需加载其余 skill 的完整内容

关键设计：

只有 using-superpowers 在每次会话时完整注入（节省 token）
其他所有 skill 按需加载（懒加载）
支持多平台：Claude Code、Cursor、Copilot CLI 输出格式不同，session-start 脚本自动适配

平台适配

平台	安装方式	Hook 格式
Claude Code	`/plugin install superpowers`	`hookSpecificOutput.additionalContext`
Cursor	Plugin Marketplace	`additional_context`
Copilot CLI	`skill` 工具	`additionalContext`
Gemini CLI	`GEMINI.md` + `activate_skill`	自动映射
OpenAI Codex	`/plugins` 搜索安装	Codex 工具映射

三、Skills 列表与说明

项目共包含 12 个核心 skill，分为三类：

类型一：流程守护型（强制遵守）

这类 skill 定义明确的"铁律"，不允许任何理由跳过。

1. `using-superpowers` --- 入口引导

触发时机： 每次对话开始时自动注入
作用：

告知 AI 如何发现和调用其他 skill
建立优先级规则：用户指令 > Superpowers skills > 默认行为
列出"绝对不能跳过 skill 检查"的借口（Red Flags 表格）
定义 skill 调用流程图：收到消息 → 判断是否有 skill → 调用 Skill 工具 → 宣告使用 → 执行

2. `test-driven-development` --- 测试驱动开发

触发时机： 实现任何功能或 bug fix 之前
核心铁律：

css 复制代码

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

流程： RED（写失败测试）→ GREEN（最小实现）→ REFACTOR（重构）
强制要求：

写代码前没有失败测试？删掉重来
测试一写就通过？说明在测试已有行为，修正测试
不允许"以后再补测试"的理由

3. `systematic-debugging` --- 系统化调试

触发时机： 遇到任何 bug、测试失败、意外行为时
核心铁律：

objectivec 复制代码

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

四阶段：

根因调查：读错误信息、复现、检查变更、追踪数据流
模式分析：找到工作的类似代码，对比差异
假设验证：提出单一假设，最小化测试
实现修复：先写失败测试，再修复，验证通过

特别规则： 如果尝试了 3 次以上修复仍失败，停止！质疑架构，而不是继续打补丁。

4. `verification-before-completion` --- 完成前验证

触发时机： 声称任务完成、提交代码、创建 PR 之前
核心铁律：

objectivec 复制代码

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

要求： 必须运行验证命令并展示输出，才能说"完成了"。
禁止： "应该能过"、"我有信心"、"上次看起来没问题"------这些都不算证据。

类型二：工作流型（规范流程）

这类 skill 定义完整的开发工作流程，确保每个阶段都有完整的产出。

5. `brainstorming` --- 头脑风暴 / 需求设计

触发时机： 任何创造性工作（新功能、新组件、修改行为）之前
硬门控：

复制代码

禁止在设计被用户批准之前写任何代码

完整流程（9步）：

探索项目现有上下文
视觉伴侣（如有 UI 相关问题）
逐一提问（每次只问一个问题）
提出 2-3 个方案（含权衡对比和推荐）
分节展示设计，逐节获取用户确认
将设计文档写入 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
自检 spec（查占位符、矛盾、歧义）
用户审阅 spec
调用 writing-plans 创建实现计划

6. `writing-plans` --- 编写实现计划

触发时机： 有了 spec 或需求，准备开始多步任务之前
核心原则： 假设执行者是"没有项目背景的技能熟练工程师"，每步都要写具体、可执行的内容。
任务粒度： 每步 2-5 分钟，包含：

写失败测试
运行确认失败
写最小实现
运行确认通过
提交

输出物： 保存到 docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
完成后： 提供两种执行方式供选择------Subagent 驱动（推荐）或 Inline 执行。

7. `executing-plans` --- 执行计划（单会话）

触发时机： 有现成实现计划，在同一会话中顺序执行
流程：

加载计划，批判性审阅
逐任务执行：标记 in_progress → 按步执行 → 标记完成
全部完成后调用 finishing-a-development-branch

重要提示： 如果平台支持子 agent，优先用 subagent-driven-development，质量更高。

8. `subagent-driven-development` --- 子 Agent 驱动开发

触发时机： 有实现计划，需要在当前会话中执行独立任务时
核心原则： 每个任务派发一个全新的子 agent，拥有干净的上下文，不继承主会话历史。
每个任务的流程：

派发实现者子 agent（使用 implementer-prompt.md）
实现者完成后 → 派发 spec 合规审查子 agent
Spec 审查通过 → 派发代码质量审查子 agent
两轮审查都通过 → 标记任务完成
所有任务完成 → 最终代码审查 → 调用 finishing-a-development-branch

模型选择原则：

机械实现任务 → 廉价快速模型
集成和判断任务 → 标准模型
架构设计和审查 → 最强模型

9. `dispatching-parallel-agents` --- 并行 Agent 分发

触发时机： 面对 2 个以上相互独立、无共享状态的任务时
核心原则： 每个独立问题域派发一个 agent，并发执行。
适用场景：

多个测试文件以不同原因失败
多个子系统独立损坏
各问题可独立理解，无共享状态

不适用： 问题相互关联、需要全局上下文、agent 会互相干扰时。

10. `finishing-a-development-branch` --- 完成开发分支

触发时机： 实现完成、测试通过，需要决定如何集成工作时
流程：

运行测试，确认全部通过
确认基础分支（main/master）
呈现 4 个选项供用户选择：
- 本地合并
- 推送并创建 PR
- 保持现状
- 丢弃工作（需输入 discard 确认）
执行选择，清理 worktree

11. `using-git-worktrees` --- Git Worktree 隔离工作区

触发时机： 开始功能开发前，或执行实现计划前
目的： 创建隔离的 git worktree，避免污染主工作区。
流程：

检查是否已有 .worktrees/ 或 worktrees/ 目录
验证目录已在 .gitignore 中（未忽略则自动添加并提交）
创建 worktree：git worktree add <path> -b <branch>
自动检测并安装依赖（npm/pip/cargo/go）
运行测试确认基线干净

类型三：代码审查型

12. `requesting-code-review` --- 发起代码审查

触发时机： 完成任务、实现重要功能或合并前
方式： 派发 code-reviewer 子 agent，提供精确构建的上下文（而非主会话历史）。
必须审查的时机：

subagent-driven-development 中每个任务后
重大功能完成后
合并到 main 之前

13. `receiving-code-review` --- 接收代码审查

触发时机： 收到代码审查反馈时
核心原则： 技术评估，而非情绪表演。
禁止行为：

"你说得对！" / "好建议！"（表演性认同）
"我马上实现"（验证之前不能做）

正确做法：

完整读取反馈
用自己的话复述需求（或提问）
对照代码库验证
技术性承认或有理由地反驳
逐条实现，每条单独测试

外部评审者的反馈要保持怀疑态度，验证后再实施。

14. `writing-skills` --- 编写新 Skill

触发时机： 创建新 skill、编辑现有 skill 或部署前验证时
核心理念： 写 skill = TDD 用于流程文档。
铁律：

objectivec 复制代码

NO SKILL WITHOUT A FAILING TEST FIRST

流程：

RED：不带 skill 运行压力测试，记录 agent 的违规行为和借口
GREEN：写针对这些具体借口的最小 skill
REFACTOR：找新的合理化借口，添加明确的反驳，反复测试直到无懈可击

四、Skills 调用关系图

css 复制代码

会话开始
   └─ [自动注入] using-superpowers
          │
          ├─ 有创意工作？→ brainstorming
          │       └─ 设计批准后 → writing-plans
          │                └─ 执行方式选择
          │                      ├─ subagent-driven-development（推荐）
          │                      │     ├─ [每任务] requesting-code-review
          │                      │     └─ 完成后 → finishing-a-development-branch
          │                      └─ executing-plans
          │                            └─ 完成后 → finishing-a-development-branch
          │
          ├─ 有 Bug？→ systematic-debugging
          │       └─ 修复时 → test-driven-development
          │
          ├─ 写代码？→ test-driven-development
          │
          ├─ 多个独立任务？→ dispatching-parallel-agents
          │
          ├─ 需要隔离工作区？→ using-git-worktrees
          │       └─ 开发完成 → finishing-a-development-branch
          │
          ├─ 声称完成？→ verification-before-completion
          │
          ├─ 收到代码审查？→ receiving-code-review
          │
          └─ 创建 Skill？→ writing-skills

五、核心设计原则

原则	说明
YAGNI	不构建假设的未来需求，保持最小实现
TDD	所有代码必须先有失败测试
DRY	不重复自己
证据优先	不能凭感觉声称"完成了"，必须有运行结果
根因优先	不找到根因不修复
懒加载	Skills 按需加载，不在会话开始时全部注入（节省 token）
子 agent 隔离	子 agent 不继承主会话上下文，由主 agent 精确构建所需信息
人类主权	用户指令永远优先于任何 skill

Superpowers 项目全面解析