Superpowers 上手指南：用 Skills 和子智能体组织 Claude Code 开发流程

AI（人工智能）写代码很快，但快并不等于工程质量稳定。需求没有澄清、设计没有沉淀、任务没有拆小、测试没有先行、审查没有分层，最后很容易出现一种结果：代码能跑，但后续没人敢改。

Superpowers 解决的正是这个问题。它不是一个单独的提示词模板，而是一套面向 AI 编程智能体的工程化工作流，核心做法是把传统软件工程里的需求分析、设计文档、TDD（测试驱动开发，Test-Driven Development）、代码审查、Git 分支管理，包装成一组可组合的 Skills，让 Claude Code 在开发时按流程推进，而不是靠一次长提示词自由发挥。

Superpowers 解决什么问题

在普通 AI 编码对话里，常见问题主要有四类：

它更适合需要长期维护的项目、团队协作项目、复杂功能开发，以及任何需要留下设计记录和审查记录的场景。对于一次性脚本或快速试验，完整流程可能显得过重，直接让 AI 辅助写代码反而更快。

整体架构：用 Skills 把开发流程模块化

Superpowers 的核心抽象是 Skill。一个 Skill 对应一类开发任务，例如需求澄清、编写计划、测试驱动开发、系统化调试、代码审查、使用 Git worktree 等。

可以把它理解成 Claude Code 的一套“工程行为准则”。当会话中出现合适的任务，插件会把对应 Skill 的上下文注入给 AI，让它按照该 Skill 定义的流程执行。

flowchart TB
    U[开发者指令] --> A[Claude Code / AI 编程智能体]
    A --> H[Session Hook 注入上下文]
    H --> S[Skills 技能系统]

    S --> B[brainstorming<br/>需求澄清]
    S --> P[writing-plans<br/>任务拆解]
    S --> T[test-driven-development<br/>测试驱动开发]
    S --> R[requesting-code-review<br/>代码审查]
    S --> G[using-git-worktrees<br/>环境隔离]
    S --> D[subagent-driven-development<br/>子智能体开发]

    D --> SA1[实现子智能体]
    D --> SA2[审查子智能体]
    D --> SA3[重试子智能体]

    B --> O[(design.md)]
    P --> O2[(plan.md)]
    T --> C[代码与测试]
    R --> C
    G --> W[独立 Git Worktree]
    C --> Git[(Git 历史)]
    O --> Git
    O2 --> Git

这套结构可以分成四层：

这个设计的重点不是“让 AI 更会写代码”，而是“让 AI 按工程流程写代码”。代码生成只是流程中的一环，前面有设计和计划，后面有测试和审查。

Skill 文件长什么样

Superpowers 的 Skill 使用 YAML Frontmatter 加 Markdown 的格式。YAML 部分声明名称、描述和触发条件，Markdown 部分写具体执行步骤。

一个简化后的 Skill 可以写成这样：

---
name: subagent-driven-development
description: Use when you have a plan.md and want to execute tasks through fresh subagents with two-phase review.
---

# Subagent-Driven Development

## Overview

每个任务都使用新的子智能体执行，避免长对话中的上下文污染。

## Process

1. 读取计划文件。
2. 为每个任务创建实现子智能体。
3. 实现完成后启动规范合规审查。
4. 规范通过后启动代码质量审查。
5. 任一审查失败时，创建新的子智能体重新实现。
6. 审查全部通过后，进入下一个任务。

这种格式的好处是简单、可读、可扩展。团队可以把内部规范写成自定义 Skill，例如：

• 后端接口必须包含 OpenAPI 描述；
• 数据库迁移必须提供回滚脚本；
• 前端组件必须包含可访问性检查；
• 所有业务逻辑必须有单元测试。

Skill 覆盖机制

Superpowers 支持个人 Skill 覆盖默认 Skill。解析顺序通常可以理解为：

1. ~/.claude/skills/        # 个人 Skill，优先级更高
2. plugin/skills/           # Superpowers 默认 Skill

如果两个目录中存在同名 Skill，个人目录里的版本会覆盖默认版本。需要强制使用默认 Skill 时，可以使用完全限定名：

superpowers:skill-name

这个机制适合团队做轻量定制。比如默认代码审查规则不符合团队规范，就可以复制一份同名 Skill 到个人或团队目录，改成自己的审查清单，而不需要修改插件代码。

子智能体驱动开发：避免长上下文拖垮实现质量

Superpowers 最关键的机制是 Subagent-Driven Development，也就是子智能体驱动开发。

普通 AI 编码通常是在一个长会话里不断追加上下文。功能越写越多，对话越拖越长，模型需要同时处理旧需求、旧决策、旧错误和新任务。到了后期，AI 可能会忘记真正的目标，也可能被早期错误实现带偏。

子智能体驱动开发换了一种方式：每个任务都使用新的子智能体，只给它当前任务所需的信息。实现完成后，再交给独立的审查子智能体检查。

flowchart TD
    P[plan.md<br/>任务计划] --> T1[任务 1]
    P --> T2[任务 2]
    P --> T3[任务 3]

    T1 --> A1[新的实现子智能体]
    A1 --> S1{规范合规审查}
    S1 -- 不通过 --> A1R[新的子智能体重做]
    A1R --> S1
    S1 -- 通过 --> Q1{代码质量审查}
    Q1 -- 不通过 --> A1R
    Q1 -- 通过 --> Done1[任务完成]

    T2 --> A2[新的实现子智能体]
    T3 --> A3[新的实现子智能体]

这个流程有几个直接收益：

这里的关键不是“子智能体数量越多越好”，而是任务必须足够清晰。如果 plan.md 写得模糊，子智能体拿到的输入也会模糊，最终只是把混乱并行化。

两阶段审查：先看做没做对，再看写得好不好

Superpowers 把代码审查拆成两个阶段：Spec Review 和 Code Quality Review。

第一阶段：Spec Review

Spec Review 只关心实现是否满足需求，不讨论代码风格。

这一阶段不要纠结命名好不好、函数是否优雅。功能没做对，代码再漂亮也没有意义。

第二阶段：Code Quality Review

Code Quality Review 在功能正确的基础上检查可维护性。

把审查拆成两段，可以避免评审时常见的混乱：一边讨论缩进和命名，一边漏掉功能缺陷；或者因为实现看起来整洁，就默认需求已经完整满足。

两种执行模式怎么选

Superpowers 里常见的执行方式可以分成两类：Subagent-Driven Development 和 Executing Plans。二者都依赖计划文件，但适用场景不同。

选择方式可以按这个规则：

标准开发流程

Superpowers 推荐的工作流接近一个小型软件开发生命周期。AI 不再直接从“我要一个功能”跳到“生成代码”，而是经过需求、设计、计划、实现、验证和收尾。

flowchart LR
    B[Brainstorming<br/>澄清需求] --> D[design.md<br/>设计文档]
    D --> W[Git Worktree<br/>隔离工作区]
    W --> P[writing-plans<br/>拆解任务]
    P --> M[选择执行模式]
    M --> SDD[Subagent Development<br/>子智能体开发]
    M --> EP[Executing Plans<br/>按计划执行]
    SDD --> TDD[TDD<br/>红-绿-重构]
    EP --> TDD
    TDD --> CR[Code Review<br/>代码审查]
    CR --> V[Verification<br/>完成前验证]
    V --> F[Finish Branch<br/>合并或收尾]

需求澄清：先把问题问清楚

很多 AI 编程失败不是因为模型不会写，而是输入太含糊。比如“做一个登录功能”至少需要澄清这些问题：

需要支持哪些登录方式？
用户名密码登录是否需要邮箱验证？
OAuth 需要支持哪些提供商？
Token 存在哪里？
Token 多久过期？
忘记密码怎么处理？
是否需要限制登录失败次数？
管理员和普通用户权限是否不同？

使用 Superpowers 时，可以直接调用 brainstorming：

/superpowers:brainstorm 我想开发一个简单的网页端 Todo 管理应用。

理想输出不是代码，而是设计文档。一个 Todo 应用的设计文档至少应该覆盖：

设计文档的价值在于把隐含需求显式化。后续子智能体执行任务时，不需要猜测业务规则，而是按文档实现。

Git Worktree：不要在一个工作区里来回切分支

Git worktree 可以让同一个仓库在不同目录里同时 checkout 不同分支。对于 AI 编程尤其有用，因为 AI 可能同时处理多个功能、修复多个问题，如果都挤在一个工作区里，文件状态很容易混乱。

传统分支切换方式：

git checkout main
git checkout -b feature/auth
# 开发中……
git checkout main

这种方式会频繁改变当前工作区文件，IDE（集成开发环境）也可能反复索引。

使用 worktree：

git worktree add ../auth-worktree -b feature/auth
cd ../auth-worktree

主工作区保持不动，新功能在独立目录里开发。多个功能可以并行存在：

project/
auth-worktree/
todo-theme-worktree/
bugfix-login-worktree/

常用检查命令：

git worktree list
git worktree prune

Writing Plans：把大任务拆成 2–5 分钟的小任务

子智能体执行效果很依赖任务颗粒度。任务太大，AI 容易一次改很多文件，审查也难定位问题；任务太小，又会带来过多流程开销。一个实用标准是：每个任务应该能在 2–5 分钟内完成，并且有明确验证方式。

Todo 应用的计划可以这样写：

## Task 1: 创建 Todo 数据模型

目标：
- 定义 Todo 类型
- 字段包含 id、title、completed、createdAt、updatedAt

验证：
- [ ] 类型定义通过编译
- [ ] createdAt 和 updatedAt 使用明确时间类型
- [ ] completed 默认值为 false

## Task 2: 实现 Todo 创建逻辑

目标：
- 实现 createTodo(title)
- title 需要去除首尾空格
- 空 title 不允许创建

验证：
- [ ] 正常标题可以创建 Todo
- [ ] 空字符串返回错误
- [ ] 只包含空格的字符串返回错误
- [ ] 新 Todo 默认未完成

## Task 3: 实现完成状态切换

目标：
- 实现 toggleTodo(id)
- 找不到 id 时返回错误
- 切换后更新 updatedAt

验证：
- [ ] completed 从 false 变 true
- [ ] completed 从 true 变 false
- [ ] 不存在的 id 不会修改列表

好的 plan.md 应该满足三个条件：

TDD：让测试成为实现边界

TDD 的基本循环是 RED-GREEN-REFACTOR：

flowchart LR
    R[RED<br/>先写失败测试] --> G[GREEN<br/>写最少代码让测试通过]
    G --> F[REFACTOR<br/>在测试保护下重构]
    F --> R

在 AI 编程里，TDD 的意义更明显。没有测试时，AI 很容易“看起来完成”；有测试时，任务是否完成会更客观。

例如创建 Todo 的测试可以先写成：

describe("createTodo", () => {
  it("creates an incomplete todo with trimmed title", () => {
    const todo = createTodo("  Learn Superpowers  ");

    expect(todo.title).toBe("Learn Superpowers");
    expect(todo.completed).toBe(false);
    expect(todo.id).toBeTruthy();
    expect(todo.createdAt).toBeInstanceOf(Date);
  });

  it("rejects empty title", () => {
    expect(() => createTodo("")).toThrow("title is required");
    expect(() => createTodo("   ")).toThrow("title is required");
  });
});

然后再让 AI 实现最小代码：

export type Todo = {
  id: string;
  title: string;
  completed: boolean;
  createdAt: Date;
  updatedAt: Date;
};

export function createTodo(title: string): Todo {
  const normalizedTitle = title.trim();

  if (!normalizedTitle) {
    throw new Error("title is required");
  }

  const now = new Date();

  return {
    id: crypto.randomUUID(),
    title: normalizedTitle,
    completed: false,
    createdAt: now,
    updatedAt: now,
  };
}

测试不是为了证明 AI 很强，而是为了限制 AI 不要偏离需求。

安装 Superpowers

在 Claude Code 中安装 Superpowers 通常只需要添加插件市场并安装插件。

添加 marketplace：

/plugin marketplace add obra/superpowers-marketplace

安装插件：

/plugin install superpowers@superpowers-marketplace

安装完成后重启 Claude Code。可以用下面的命令确认插件是否已经加载：

/plugin list

如果安装失败，可以清理缓存后强制重装：

rm -rf ~/.cache/superpowers

/plugin install superpowers@superpowers-marketplace --force

项目地址：

https://github.com/obra/superpowers

用 Todo 应用跑一遍完整流程

假设要开发一个网页端 Todo 管理应用，可以按下面的方式推进。

1. 澄清需求并生成设计

在 Claude Code 中输入：

/superpowers:brainstorm 我想开发一个简单的网页端 Todo 管理应用。

需求澄清阶段不要急着让 AI 写代码。需要让它明确：

Todo 是否需要持久化？
数据放 localStorage、IndexedDB 还是后端数据库？
是否需要过滤：全部、未完成、已完成？
是否需要编辑 Todo 标题？
是否需要批量清除已完成 Todo？
界面是否需要响应式布局？

确认方案后，让它生成设计文档。设计文档可以保存为：

design.md

2. 创建隔离工作区

如果当前项目已经是 Git 仓库，可以为 Todo 功能创建独立 worktree：

git worktree add ../todo-worktree -b feature/todo-app
cd ../todo-worktree

这样主工作区不会被 AI 的改动影响。即使功能开发失败，也可以直接删除该 worktree，不污染主目录。

3. 生成实现计划

让 Superpowers 基于设计文档生成计划：

/superpowers:writing-plans 根据 design.md 为 Todo 应用生成可执行计划，每个任务控制在 2–5 分钟，并包含验证步骤。

生成后的 plan.md 不要直接执行，先检查任务是否足够小、是否有测试、是否遗漏边界条件。

一个计划片段可能是：

## Task 1: 搭建 Todo 页面结构

目标：
- 创建 TodoApp 根组件
- 创建 TodoInput、TodoList、TodoItem 三个组件
- 页面包含标题、输入框、列表区域

验证：
- [ ] 页面可以正常渲染
- [ ] 输入框存在并可输入
- [ ] 空列表展示空状态

## Task 2: 实现新增 Todo

目标：
- 输入标题后按 Enter 创建 Todo
- 点击 Add 按钮创建 Todo
- 创建后清空输入框

验证：
- [ ] 输入有效标题可以新增
- [ ] 空标题不会新增
- [ ] 新增后输入框清空

4. 使用子智能体执行计划

计划明确后，可以使用子智能体驱动开发：

/superpowers:subagent-driven-development 使用 plan.md 执行开发，每个任务完成后进行规范合规审查和代码质量审查。

执行过程中，每个任务会经历：

sequenceDiagram
    participant Main as 主会话
    participant Impl as 实现子智能体
    participant Spec as 规范审查子智能体
    participant Quality as 质量审查子智能体

    Main->>Impl: 分配当前任务和必要上下文
    Impl-->>Main: 返回代码修改
    Main->>Spec: 检查是否满足任务规范
    Spec-->>Main: 通过 / 不通过
    alt 规范不通过
        Main->>Impl: 创建新子智能体重新实现
    else 规范通过
        Main->>Quality: 检查代码质量
        Quality-->>Main: 通过 / 不通过
    end

如果审查失败，比较理想的处理方式不是在同一段混乱上下文里反复打补丁，而是创建新的子智能体重新执行当前任务。这样可以减少“越修越乱”的概率。

5. 验证应用

所有任务完成后，不要只相信 AI 的完成声明。需要运行测试、类型检查和本地服务。

常见命令如下，具体以项目技术栈为准：

npm test
npm run typecheck
npm run lint
npm run dev

如果是前端项目，还应该手动验证这些路径：

6. 迭代新功能

完成基础 Todo 后，继续添加主题切换功能，可以重新走同样流程：

/superpowers:brainstorm 给 Todo 应用添加浅色和深色主题切换功能。

需要澄清的问题包括：

主题选择是否需要持久化？
默认主题跟随系统还是固定浅色？
切换按钮放在哪里？
是否需要支持 prefers-color-scheme？
主题变量使用 CSS variables 还是框架主题系统？

然后生成新的设计、计划、分支或 worktree：

git worktree add ../todo-theme-worktree -b feature/todo-theme
cd ../todo-theme-worktree

功能完成并通过测试后，再合并回主分支。

常用 Skills 速查

触发 Skill 的写法

Superpowers 可以根据上下文触发 Skill，但开发者直接写清楚意图会更稳定。

也可以组合多个意图：

用 TDD 方式实现用户认证，完成后进行规范合规审查和代码质量审查。

这类指令比“帮我写一个登录功能”更容易得到可控结果。

使用时容易踩的坑

任务太大

如果一个任务同时包含数据库迁移、接口、前端页面、测试和权限控制，子智能体很难一次做好。应该继续拆：

Task 1: 创建 User 数据模型
Task 2: 实现密码哈希工具
Task 3: 实现注册接口
Task 4: 编写注册接口测试
Task 5: 实现登录接口
Task 6: 增加登录失败限制

验证步骤不可执行

“确认功能正常”不是好验证。好的验证应该具体到命令、测试用例或可观察行为：

验证：
- [ ] npm test 通过
- [ ] 空密码返回 400
- [ ] 错误密码不会生成 token
- [ ] 连续 5 次失败后账号被临时限制

设计文档没有更新

AI 开发流程里，设计文档是后续实现的合同。如果中途改变需求，只改代码不改 design.md，后续子智能体会继续按旧设计执行。需求变化时，需要同步更新设计和计划。

把完整流程用在一次性脚本上

Superpowers 的流程有成本。一次性数据清洗脚本、临时命令、小型 Demo 不一定需要 brainstorming、plan、subagent、review 全套流程。它更适合需要长期维护、多人协作、反复迭代的代码。

Worktree 没清理

长期使用 worktree 后，可能残留无效目录或分支引用。可以定期检查：

git worktree list
git worktree prune

删除一个不再需要的 worktree：

rm -rf ../todo-theme-worktree
git worktree prune

常见问题排查

Claude Code 没有触发 Skill，直接开始写代码

可以按顺序检查：

/plugin list

确认 Superpowers 已安装后，尝试显式触发：

使用 brainstorming 技能来规划这个功能，不要直接写代码。

如果仍然不生效，可以重启当前 Claude Code 会话。

安装插件时报错

清理缓存并强制重新安装：

rm -rf ~/.cache/superpowers

/plugin install superpowers@superpowers-marketplace --force

Git worktree 创建失败

先确认 Git 版本。Git worktree 需要较新的 Git 版本支持：

git --version

清理残留 worktree 记录：

git worktree prune

手动测试：

git worktree add ../test-worktree -b test-branch

审查一直失败

审查反复失败通常说明任务输入不够清楚，或者任务过大。处理方式不是继续让 AI 修，而是回到计划文件：

把当前失败任务拆成更小的任务，并为每个任务补充明确验证步骤。

必要时回到设计文档，补齐缺失约束。

什么时候适合引入 Superpowers

Superpowers 的价值在于把 AI 编程纳入工程流程：先澄清需求，再形成设计，再拆任务，再让子智能体实现，并通过测试和两阶段审查确认结果。它不能替代开发者判断架构和业务取舍，但可以把重复、机械、容易遗漏的流程固定下来，让 AI 生成的代码更容易被验证、审查和维护。