Claude Code SuperPowers 使用指南

目录

1. 简介
2. 安装与配置
3. 核心概念
4. 可用技能列表
5. 常用命令与使用方式
6. 技能调用流程
7. 平台适配
8. 最佳实践
9. 常见问题

---

简介

Superpowers 是一个面向 AI 编程助手（Claude Code、Codex 等）的核心技能库插件，由 Jesse Vincent 开发并维护。

• 仓库地址：https://github.com/obra/superpowers
• 许可证：MIT
• 当前版本：5.1.0

它将复杂的工作流程——如测试驱动开发、系统化调试、代码审查、并行子代理调度等——封装为可复用的参考文档，AI 在遇到对应场景时自动加载并遵循。

核心价值：

• 规范化工作流程：确保每次操作都遵循经过验证的最佳实践
• 模块化扩展：按需安装，不增加无关开销
• 零依赖设计：插件本身不依赖任何第三方项目
• 纪律约束：通过 “Iron Law”（铁律）和反合理化表，防止 AI 在压力下跳过关键步骤

典型工作流： Brainstorming（构思） → Writing Plans（编写计划） → Subagent-Driven Development（子代理执行） → Verification（验证） → Finishing Branch（完成分支）

---

安装与配置

安装命令

通过 Skills CLI 安装：

# 安装 Superpowers 插件
npx skills add obra/superpowers -g -y

也可以从 GitHub 仓库克隆：

git clone https://github.com/obra/superpowers.git

安装后的效果

安装成功后，插件自动注册以下内容，无需额外配置：

类型	路径
技能（Skills）	skills/
子代理（Agents）	agents/
命令（Commands）	commands/
钩子（Hooks）	hooks/

技能目录结构

skills/
  skill-name/
    SKILL.md              # 主文档（必需）
    supporting-file.*     # 辅助文件（可选）

检查与更新

npx skills check       # 检查是否有更新
npx skills update      # 更新到最新版本

---

核心概念

指令优先级

Superpowers 技能会覆盖系统默认行为，但用户指令始终具有最高优先级：

1. 用户显式指令（CLAUDE.md、AGENTS.md、直接请求）——最高优先级
2. Superpowers 技能——在与默认系统行为冲突时覆盖
3. 默认系统提示——最低优先级

技能类型

类型	特点	示例
Rigid（严格型）	必须严格遵循，不能偏离	TDD、Systematic Debugging、Verification
Flexible（灵活型）	根据上下文灵活应用原则	Writing Plans、Writing Skills

技能文档自身会说明属于哪种类型。

技能调用铁律

即使只有 1% 的可能性某个技能适用，也必须调用它。

如果调用后发现技能不适用，可以跳过，但必须先检查。

常见合理化借口（需要警惕的思维陷阱）

借口	现实
“这只是一个简单的问题”	问题即任务，先检查技能
“我需要先了解更多上下文”	技能告诉你如何收集信息
“我可以快速查看文件”	文件缺乏对话上下文
“这个技能太复杂了，没必要”	简单的事也会变复杂
“我记得这个技能怎么用”	技能会演进，阅读当前版本

子代理（Subagent）支持

Superpowers 大量使用子代理模式：

• Claude Code：通过 Task 工具分发子代理
• Codex：通过 Task 工具
• 核心原则：每个子代理获得独立的上下文和精确的指令

---

可用技能列表

当前 Superpowers 插件包含 15 个技能：

技能名称	用途	类型
brainstorming	在创建功能、构建组件或修改行为之前进行创意构思与设计	Rigid
dispatching-parallel-agents	当面临 2 个以上独立任务时并行分发子代理	Flexible
executing-plans	在独立会话中执行已编写的实施计划	Rigid
find-skills	发现和安装来自开放技能生态系统的技能	Flexible
finishing-a-development-branch	实现完成后指导合并、创建 PR 或清理分支	Rigid
receiving-code-review	接收代码审查反馈时的正确处理姿势——技术严谨，非表演性认同	Rigid
requesting-code-review	完成任务或合并前发起代码审查	Flexible
subagent-driven-development	在当前会话中通过子代理逐个执行计划任务，含两阶段审查	Rigid
systematic-debugging	遇到任何 Bug、测试失败或意外行为时的系统化调试流程	Rigid
test-driven-development	实现任何功能或修复 Bug 前使用 TDD（先写测试）	Rigid
using-git-worktrees	确保功能工作在隔离的 Git worktree 中进行	Rigid
using-superpowers	技能系统总纲——定义何时调用技能、优先级、流程	Rigid
verification-before-completion	在声称工作完成前必须运行验证命令——证据优先	Rigid
writing-plans	为多步骤任务编写详细的实施计划	Flexible
writing-skills	创建、编辑和验证新技能（TDD 应用于过程文档）	Rigid

---

常用命令与使用方式

技能调用

技能通过 Skill 工具自动调用，不需要手动执行命令。当 AI 识别到当前任务与某个技能匹配时，会自动加载并遵循该技能。

插件管理命令

npx skills find [query]      # 搜索技能
npx skills add <pkg> -g -y   # 安装技能
npx skills check             # 检查更新
npx skills update            # 更新全部
npx skills init my-skill     # 创建自定义技能

各技能使用方式

brainstorming —— 创意构思

使用场景：创建新功能、构建组件、修改行为之前

触发条件 → AI 自动调用 brainstorming 技能
    ↓
探索项目上下文
    ↓
逐个提问（每次一个问题）
    ↓
提出 2-3 个方案并比较优劣
    ↓
分段呈现设计，每段获得批准后继续
    ↓
撰写设计文档 → 提交 git
    ↓
调用 writing-plans 技能

systematic-debugging —— 系统化调试

使用场景：遇到 Bug、测试失败、意外行为

Phase 1: 根因调查（读错误信息、复现、检查变更、追踪数据流）
Phase 2: 模式分析（找可工作的例子、对比差异）
Phase 3: 假设与测试（提出单一假设、最小化测试）
Phase 4: 实施修复（写测试 → 修复 → 验证）
    ↓ 如果 3 次修复仍失败 → 质疑架构设计

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

使用场景：实现任何功能或修复 Bug

# RED 阶段
# 1. 写一个失败的测试
# 2. 运行确认测试失败

# GREEN 阶段
# 3. 写最少量的代码使测试通过
# 4. 运行确认测试通过

# REFACTOR 阶段
# 5. 重构，保持测试绿色

铁律：没有失败的测试就不写生产代码。 如果先写了代码，删除它，重新从测试开始。

subagent-driven-development —— 子代理驱动开发

使用场景：已有实施计划，需要在当前会话中执行

读取计划文件 → 提取所有任务 → 创建 TodoWrite
    ↓
对每个任务：
  1. 分发实现者子代理
  2. 分发规格审查子代理 → 确认符合规格
  3. 分发代码质量审查子代理 → 确认代码质量
  4. 标记任务完成
    ↓
所有任务完成后 → 分发最终代码审查
    ↓
调用 finishing-a-development-branch 技能

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

使用场景：在声称任何工作完成、修复成功或测试通过之前

必须运行验证命令并读取输出：
  测试 → 确认通过
  Lint → 确认干净
  构建 → 确认成功
    ↓
然后才能声称"完成"

using-git-worktrees —— Git 隔离工作区

使用场景：开始需要隔离的功能开发

Step 0: 检测是否已在隔离工作区
Step 1: 创建隔离工作区（优先使用平台原生工具，回退到 git worktree）
Step 2: 项目设置（npm install / cargo build / pip install）
Step 3: 验证基线测试通过

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

使用场景：实现完成、所有测试通过后

验证测试通过
    ↓
检测环境（普通仓库 / worktree / 分离 HEAD）
    ↓
呈现 4 个选项：
  1. 本地合并到主分支
  2. 推送并创建 Pull Request
  3. 保持分支不变
  4. 丢弃此工作（需确认）
    ↓
执行选择 → 清理 worktree

find-skills —— 发现与安装技能

使用场景：用户询问"如何做 X"、“有没有技能可以做 X”

# 先查看 skills.sh 排行榜
# 然后搜索
npx skills find [query]

# 验证质量后推荐给用户
# 安装
npx skills add <owner/repo@skill> -g -y

---

技能调用流程

技能调用遵循以下决策流程：

用户消息
    ↓
可能有技能适用？
  ├─ 是 → 调用 Skill 工具 → 宣布使用哪个技能 → 严格按技能执行
  └─ 否 → 直接响应

多技能优先级

当多个技能可能适用时：

1. 流程技能优先（brainstorming、systematic-debugging）——决定如何 Approach 任务
2. 实施技能其次（writing-plans、TDD）——指导具体执行

技能间的依赖关系

using-superpowers (总纲)
    ↓
brainstorming → writing-plans → subagent-driven-development / executing-plans
    ↓                                                        ↓
writing-skills (可选)                              requesting-code-review
    ↓                                                        ↓
test-driven-development (实施中使用)              finishing-a-development-branch
    ↓
verification-before-completion (每次声称完成前)

---

平台适配

Superpowers 使用 Claude Code 的工具命名。在其他平台使用时，需要进行工具名称映射：

Claude Code ↔ Codex

Codex 原生支持 Superpowers 的 Task 工具，技能文件可直接使用。

工具名称参考

当技能文档中出现以下工具名时，使用你所在平台的对应工具：

概念	Claude Code / Codex
读取文件	Read
写入文件	Write
编辑文件	Edit
执行命令	Bash
搜索内容	Grep
搜索文件	Glob
任务追踪	TodoWrite
调用技能	Skill
分发子代理	Task

---

最佳实践

1. 始终先检查技能

收到任何任务时，先问自己"有技能适用吗？"——即使只有 1% 的可能性。

2. 不要在主分支上直接开发

始终使用 using-git-worktrees 创建隔离工作区，保护主分支的稳定性。

3. 遵循 TDD 铁律

• 没有失败的测试就不写生产代码
• 如果先写了代码，删除它，重新从测试开始

4. 系统化调试，不猜

遇到 Bug 时读错误信息、能复现再动手、提出单一假设。3 次修复失败后质疑架构。

5. 完成前必须验证

运行测试、lint、构建并确认全部通过。不要依赖"应该没问题"的假设。

6. 审查代码时保持技术严谨

验证建议是否适用于当前代码库，检查是否破坏现有功能，对不需要的功能说"不"（YAGNI 原则）。

7. 并行任务用子代理

3 个以上独立问题时，分发多个子代理并行处理。

8. 技能编写遵循 TDD

创建新技能时：先观察失败行为（RED）→ 编写最小技能（GREEN）→ 测试修补（REFACTOR）。

9. 技能描述只写"何时使用"

不要在工作流程描述中总结技能的流程，这会导致 AI 跳过阅读完整内容。

10. 跨项目复用

技能应该是通用的、跨项目可复用的。项目特定的约定放在 CLAUDE.md 中。

---

常见问题

Q: Superpowers 是什么？

A： 它是一个 Claude Code / Codex 插件，包含 15 个核心技能，覆盖 TDD、调试、代码审查、并行子代理等工作流。安装后技能自动注册。

Q: 安装命令是什么？

A： npx skills add obra/superpowers -g -y

Q: 技能会减慢开发速度吗？

A： 不会。系统化方法比试错快得多。数据表明：系统化调试 15-30 分钟修复，随机尝试需要 2-3 小时。

Q: 可以跳过某些技能步骤吗？

A： 不可以。跳过步骤就是违反技能精神。如果确实不需要某个技能（如原型代码），应与用户沟通后决定。

Q: 技能在哪个平台能用？

A： Claude Code 和 Codex 原生支持。其他平台需要工具名称映射。

Q: 多个技能同时适用怎么办？

A： 流程技能（brainstorming、debugging）优先于实施技能（TDD、writing-plans）。

Q: 如何创建自己的技能？

A： 运行 npx skills init my-skill-name 创建模板，然后遵循 writing-skills 技能的 TDD 流程。

Q: 子代理是什么？为什么需要它？

A： 子代理是 AI 的"分身"，拥有独立的上下文。每个任务独立处理，互不污染，还能并行执行。

Q: TDD 是不是太教条了？

A： TDD 本质上是务实的：它在提交前发现 Bug、防止回归、文档化行为、支持重构。测试先行迫使你在实现前思考边界条件。

---

本指南基于 Superpowers 5.1.0 版本编写。项目仓库：https://github.com/obra/superpowers