Superpowers 项目全面剖析

Superpowers 项目全面解析

一、项目是什么

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

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

二、如何生效

生效机制

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

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

具体流程：

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

关键设计：

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

平台适配

三、Skills 列表与说明

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

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

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

1.using-superpowers— 入口引导

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

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

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

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

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

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

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

3.systematic-debugging— 系统化调试

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

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

四阶段：

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

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

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

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

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

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

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

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

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

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

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

完整流程（9步）：

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

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

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

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

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

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

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

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

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

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

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

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

模型选择原则：

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

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

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

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

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

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

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

1. 运行测试，确认全部通过

2. 确认基础分支（main/master）

3. 呈现 4 个选项供用户选择：

   • 本地合并
   • 推送并创建 PR
   • 保持现状
   • 丢弃工作（需输入discard确认）

4. 执行选择，清理 worktree

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

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

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

类型三：代码审查型

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

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

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

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

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

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

正确做法：

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

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

14.writing-skills— 编写新 Skill

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

NO SKILL WITHOUT A FAILING TEST FIRST

流程：

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

四、Skills 调用关系图

会话开始 └─ [自动注入] 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

五、核心设计原则