TDD 实战：Claude Code Superpowers 保姆级教程14 个 Skills 全解析 + 实战开发

一句话总结： Superpowers 是 Claude Code 最受欢迎的插件框架，通过 14 个结构化技能，把 AI 编程从"随性发挥"变成"工程化流水线"------先想清楚、再写测试、最后才编码。

一、什么是 Superpowers？

1.1 定义

Superpowers 是一个免费、开源的 Claude Code 插件框架 ，由 Jesse Vincent （GitHub: obra）于 2025 年 10 月发布。它通过 14 个结构化技能（Skills） 为 Claude Code 注入软件工程纪律：

编码前先头脑风暴，想清楚再动手
强制执行 TDD（测试驱动开发） ：先写失败的测试，再写实现代码
支持并行子代理（Subagents） 开发，每个任务在独立的 Git Worktree 中执行
所有代码都必须经过两阶段代码审查

1.2 Superpowers 和传统 AI 编程有什么不同？

对比维度	传统 AI 编程（Vibe Coding）	Superpowers
编码方式	直接告诉 AI "帮我写个XX功能"	先头脑风暴 → 设计文档 → 计划 → 测试 → 编码
代码质量	不稳定，依赖 AI 的"灵感"	通过 TDD 和代码审查保障
需求理解	AI 猜测你的意图	通过结构化提问确认需求
执行方式	单线程串行	多子代理并行，各自独立
错误处理	出了问题再改	系统化调试，先找根因再修复

核心理念： Superpowers 不是让 AI "写代码更快"，而是让 AI "按工程规范写代码"。

二、为什么需要 Superpowers？

2.1 传统 AI 编程的痛点

如果你经常使用 Claude Code 或其他 AI 编程工具，一定遇到过这些问题：

❌ 需求理解偏差

md 复制代码

你："帮我写一个用户注册功能"
AI：写了邮箱注册，但你想要的是手机号注册...

❌ 代码质量不稳定

md 复制代码

第一次让 AI 写：代码优雅、结构清晰
第二次让 AI 写：风格完全不同、甚至引入了 bug

❌ 缺少工程纪律

md 复制代码

没有设计文档、没有计划、没有审查------完全靠"感觉"推进

2.2 Superpowers 的解决思路

Superpowers 通过 14 个技能 构建了一套完整的工程化开发流水线：

2.3 三条铁律（Iron Laws）

Superpowers 有三条不可违反的铁律：

不需要记住所有铁律，Superpowers 会自动在每一步检查并提醒你。

三、快速开始

3.1 环境准备

前提条件： 需要安装 Claude Code 并支持 /plugin 命令

确认你的 Claude Code 版本是否支持插件：

bash 复制代码

# 在 Claude Code 中输入
/plugin

如果提示命令不存在，请先安装 Claude Code

3.2 安装 Superpowers（3 条命令）

bash 复制代码

# 第一步：添加 Superpowers 插件市场
/plugin marketplace add obra/superpowers-marketplace

# 第二步：安装 Superpowers 插件
/plugin install superpowers@superpowers-marketplace

# 第三步：验证安装是否成功
/skills

安装成功后，执行 /skills 应该能看到 14 个技能列表：

阶段	技能	一句话总结
🚪 入口	`using-superpowers`	总开关 + 技能路由
✍️ 划	`brainstorming`	先想清楚需求
✍️ 划	`writing-plans`	把需求拆成小任务
✍️ 划	`executing-plans`	按顺序执行任务
⚙️ 执行	`subagent-driven-development`	每个任务用独立子代理
⚙️ 执行	`dispatching-parallel-agents`	多个子代理并行工作
⚙️ 执行	`using-git-worktrees`	每个子代理隔离工作区
🧪 测试	`test-driven-development`	先写测试再写代码
🐛 调试	`systematic-debugging`	结构化找根因
🔍 审查	`requesting-code-review`	主动发起审查
🔍 审查	`receiving-code-review`	系统化处理反馈
✅ 完成	`verification-before-completion`	完成前强制验证
✅ 完成	`finishing-a-development-branch`	规范收尾和合并
🔧 扩展	`writing-skills`	创建自定义技能

3.3 激活 Superpowers

每次新的 Claude Code 会话开始时，输入以下命令激活：

md 复制代码

/superpowers:using-superpowers

它会激活 "技能优先协议"（Skill-First Protocol） ------Claude 在执行任何操作之前，都会先搜索是否有相关的 Superpowers 技能可用。

激活后，你可以直接描述你的需求，Superpowers 会自动引导你完成整个开发流程。

3.4 安装后的目录结构

技术原理： 每个技能本质上是一个 SKILL.md 文件（Markdown + YAML 前置配置），Claude Code 会读取这些文件来"学习"对应的工程纪律。注意文件名大小写敏感------必须是大写的 SKILL.md。

四、Superpowers 的 14 个核心技能

Superpowers 的 14 个技能可以分为 7 大类，覆盖软件开发的完整生命周期：

4.1 🧠 规划与设计类（3 个技能）

① brainstorming（头脑风暴）

核心作用： 在写任何代码之前，通过苏格拉底式提问，彻底搞清楚需求

做什么：

阻止 Claude 直接开始写代码
通过一系列澄清问题，深入理解你的真实需求
探索边界条件、异常场景、用户期望
最终产出一份设计文档（Design Document）

工作流程：

为什么重要： 很多 bug 和功能缺失的根源是------需求本身就没说清楚。头脑风暴把这些模糊的需求在编码之前就解决掉。

② writing-plans（编写计划）

核心作用： 把设计文档拆解成可执行的原子任务

做什么：

读取头脑风暴产出的设计文档
将每个功能拆解为原子级别的任务（Atomic Tasks）
每个任务都有明确的验收标准（Acceptance Criteria）
任务之间标注依赖关系和执行顺序

输出示例：

md 复制代码

## 实现计划

### 任务 1: 初始化项目结构
- 创建 React + TypeScript 项目
- 配置 ESLint 和 Prettier
- 验收标准：`npm start` 能正常启动

### 任务 2: 定义数据模型
- 创建 Todo 类型定义
- 包含 id、title、completed、createdAt、updatedAt 字段
- 验收标准：类型定义通过 TypeScript 编译检查

### 任务 3: 实现 Todo 增删改查
- 实现 addTodo、deleteTodo、toggleTodo、updateTodo
- 编写单元测试
- 验收标准：所有 CRUD 操作的单元测试通过

③ executing-plans（执行计划）

核心作用： 按计划顺序批量执行任务

做什么：

读取 writing-plans 产出的任务列表
按顺序逐个执行，每个任务完成后设置检查点（Checkpoint）
在不适合使用子代理的场景下使用（比如任务之间有强依赖）

4.2 ⚙️ 开发与执行类（3 个技能）

④ subagent-driven-development（子代理驱动开发）

核心作用： 将每个任务委派给独立的子代理执行

这是 Superpowers 最重要的创新之一！

做什么：

为每个任务生成一个全新的子代理（Subagent）
子代理在独立的 Git Worktree 中工作（避免代码冲突）
每个子代理有自己的"干净上下文"，不会受到其他任务的干扰
完成后通过两阶段审查合并回主分支

架构图：

为什么用子代理？

避免上下文污染： 长时间运行的 Claude 会话，上下文越长越容易"忘记"之前的约定
避免代码冲突： 每个子代理在自己的 Git 分支上工作
支持并行： 多个独立任务可以同时执行

⑤ dispatching-parallel-agents（并行子代理调度）

核心作用： 同时协调 2 个以上的独立子代理

做什么：

识别哪些任务可以并行执行（没有依赖关系）
同时启动多个子代理
等待所有子代理完成后，统一合并结果

什么时候用：

多个功能模块之间互相独立
想加快开发速度
例如：前端 UI 和后端 API 可以并行开发

⑥ using-git-worktrees（使用 Git Worktree）

核心作用： 为每个并行子代理创建隔离的工作空间

做什么：

使用 git worktree add 为每个子代理创建独立的工作目录
每个 worktree 有自己的分支，互不影响
任务完成后通过 git merge 合并回主分支

什么是 Git Worktree？

4.3 🧪 测试类（1 个技能）

⑦ test-driven-development（测试驱动开发）

核心作用： 强制执行 TDD 的"红→绿→重构"循环

TDD 的三个阶段：

Superpowers 的 TDD 铁律：

先写测试 ------ 在写任何实现代码之前，必须先写一个会失败的测试
让测试通过 ------ 写最少的代码让测试变绿
重构优化 ------ 在测试保护下优化代码

4.4 🐛 调试类（1 个技能）

⑧ systematic-debugging（系统化调试）

核心作用： 用结构化的方法定位和修复 Bug，杜绝"瞎猜式修 Bug"

四个调试阶段：

4.5 🔍 代码审查类（2 个技能）

⑨ requesting-code-review（请求代码审查）

核心作用： 完成任务后，主动发起结构化代码审查

做什么：

生成代码变更摘要（改了什么、为什么改）
标注需要重点审查的区域
按照审查清单逐项检查

⑩ receiving-code-review（接收代码审查）

核心作用： 系统化地处理审查反馈

三步流程：

4.6 🏁 完成类（1 个技能）

⑪ finishing-a-development-branch（完成开发分支）

核心作用： 正确地收尾和合并开发分支

做什么：

确认所有测试通过
确认代码审查已完成
生成提交信息（Commit Message）
合并到主分支
清理临时分支和 Worktree

4.7 🔧 元技能（3 个技能）

⑫ using-superpowers（使用 Superpowers）

核心作用： 入口技能 / 技能路由器

做什么：

作为 Superpowers 的总入口
在每次会话开始时激活"技能优先协议"
根据当前上下文，自动路由到最合适的技能
像一个"交通警察"一样指挥整个流程

⑬ writing-skills（编写新技能）

核心作用： 创建自定义的 Superpowers 技能

做什么：

指导你编写新的 SKILL.md 文件
将 TDD 的理念应用到技能文档编写中
支持社区共建技能库

⑭ collaboration（协作模式）

核心作用： 优化人机协作的模式

做什么：

定义人类和 AI 各自的职责边界
指导什么时候该让人类做决策
指导什么时候 AI 可以自主行动

五、Superpowers 的完整工作流程

5.1 全流程图

把 14 个技能串联起来，就是一条完整的开发流水线：

5.2 每个阶段的"门禁"

Superpowers 的每个阶段之间都有门禁（Gate） ------上一阶段不通过，不能进入下一阶段：

门禁	条件	不通过的后果
头脑风暴 → 写计划	设计文档已确认	Claude 会继续提问，不会开始拆解任务
写计划 → 开发	所有任务都有验收标准	Claude 会要求你完善任务描述
开发 → 审查	所有测试通过	Claude 会先调试，不会提交审查
审查 → 完成	审查反馈已全部处理	Claude 会继续修改，不会合并

六、实战：用 Superpowers 开发一个 TODO List

下面我们通过一个完整的实战案例，体验 Superpowers 的完整开发流程。

📋 需求描述

使用Vue3 + ts开发一个TODO List待办事项项目，支持以下功能：

新增待办事项
编辑待办事项
单个&批量修改待办事项状态
单个&批量删除待办事项

Step 1：激活 Superpowers

bash 复制代码

# 首先创建项目并初始化
mkdir markdown-notebook && cd markdown-notebook
npm init -y
npm install typescript ts-node @types/node --save-dev
npx tsc --init

# 启动 Claude Code
claude

在 Claude Code 中输入：

md 复制代码

/using-superpowers

此时 Claude 已进入 Superpowers 模式，会自动识别并使用相关技能。

Step 2：头脑风暴（brainstorming）

你输入需求：

md 复制代码

使用Vue3 + ts开发一个TODO List待办事项项目，UI组件采用element-plus，不需要参考别的项目，
这个是一个全新的项目。

Claude 不会直接开始写代码，而是进入头脑风暴模式，开始提问：

（1）头脑风暴 --- 让我先了解清楚你的需求

Q1: 这个TODO List范围你想做到哪个程度？

Q2: 数据如何存储？

Q3: 状态管理用哪种方案？

(2) 你逐一回答后，Claude 生成设计文档：

md 复制代码

# TODO List 待办事项（进阶版）设计文档

- 日期：2026-07-12
- 技术栈：Vite + Vue 3 + TypeScript + Element Plus + Pinia
- 项目位置：复用 `20-claude-demo/01-claude-superpowers/` 目录

## 1. 目标

构建一个进阶版待办事项单页应用，用于学习 Vue 3 全家桶（`<script setup>` + Pinia）与 Element Plus 的核心用法。数据本地持久化，刷新不丢失。

## 2. 功能范围（进阶版）

- 新增待办：标题、优先级、分类、截止日期
- 编辑待办（行内编辑）
- 删除待办（二次确认）
- 标记完成 / 取消完成
- 筛选：按状态（全部 / 未完成 / 已完成）
- 筛选：按分类
- 关键字搜索（匹配标题）
- 清除已完成
- 统计：总数 / 已完成 / 未完成 / 完成率
- 截止日期临近或过期时给出视觉提示

明确不做（YAGNI）：拖拽排序、导入导出、深色模式、后端 API、多标签 tag（分类为单值）。

## 3. 技术栈选型

| 维度 | 选择 | 理由 |
| --- | --- | --- |
| 构建工具 | Vite | Vue 3 官方推荐，启动快 |
| UI 库 | Element Plus，按需引入（`unplugin-vue-components` + `unplugin-auto-import`） | 官方推荐方案，体积小，模板内零注册 |
| 状态管理 | Pinia | Vue 3 生态主流，结构清晰、可测试 |
| 持久化 | localStorage | 纯前端、无后端依赖 |
| 测试 | Vitest | Vite 原生，测 store 纯逻辑 |

## 4. 数据模型（`src/types/todo.ts`）

export type Priority = 'low' | 'medium' | 'high'

export interface Todo {
  id: string
  title: string
  done: boolean
  priority: Priority
  category: string        // 分类，如「工作」「学习」
  dueDate: string | null  // ISO 日期字符串 yyyy-mm-dd
  createdAt: number
  updatedAt: number
}

export type FilterStatus = 'all' | 'active' | 'completed'

export interface TodoFilter {
  status: FilterStatus
  category: string        // 'all' 或具体分类名
  keyword: string
}

优先级展示色：high=danger（红）、medium=warning（橙）、low=primary（蓝）。

## 5. 目录结构

01-claude-superpowers/
├── index.html
├── package.json            ← 重写（替换原纯 TS 配置）
├── tsconfig.json
├── tsconfig.node.json
├── vite.config.ts          ← Element Plus 按需引入 + 路径别名 @
├── src/
│   ├── main.ts             ← 挂载 App + Pinia
│   ├── App.vue             ← 页面布局容器
│   ├── env.d.ts           ← Vue SFC 类型声明
│   ├── types/todo.ts       ← 类型定义
│   ├── stores/todo.ts      ← Pinia store
│   ├── utils/storage.ts    ← localStorage 读写封装
│   └── components/
│       ├── TodoInput.vue   ← 新增表单
│       ├── TodoFilter.vue  ← 筛选 + 搜索 + 统计
│       ├── TodoList.vue    ← 列表容器 + 空状态
│       └── TodoItem.vue    ← 单项（含行内编辑）
└── tests/（或 src 下 __tests__）
    └── todo.store.spec.ts  ← store 单元测试

原 `package.json` / `node_modules` / `package-lock.json`（纯 TS 脚手架）将被替换；`.claude` 目录保留。

## 6. Pinia Store（`src/stores/todo.ts`）

### state
- `todos: Todo[]`
- `filter: TodoFilter`（默认 `{ status: 'all', category: 'all', keyword: '' }`）

### getters
- `filteredTodos`：依次按 `status`（all 跳过 / active 取 !done / completed 取 done）、`category`（'all' 跳过，否则精确匹配）、`keyword`（小写包含匹配 title）过滤
- `categories`：从 `todos` 提取去重后的分类列表
- `stats`：`{ total, completed, active, completionRate }`，`completionRate = total === 0 ? 0 : completed / total`

### actions
- `addTodo(payload)`：生成 id（`crypto.randomUUID()`）、时间戳，push 进 `todos`
- `updateTodo(id, patch)`：合并 patch，更新 `updatedAt`
- `removeTodo(id)`
- `toggleTodo(id)`：翻转 `done`
- `clearCompleted()`：移除所有 `done === true`
- `setFilter(patch)`：合并更新 `filter`

### 持久化
- store 创建后注册 `$subscribe`：任意 state 变化时调用 `saveTodos(todos)`
- 初始化：构造函数中调用 `loadTodos()` 填充 `todos`（解析失败回退空数组）

## 7. 组件设计

### `App.vue`
页面容器：顶部标题区 + `TodoInput` + `TodoFilter` + `TodoList`。

### `TodoInput.vue`
- 字段：标题 `el-input`（回车提交）、优先级 `el-select`（默认 medium）、分类 `el-select allow-create filterable`（可选已有或新建）、截止日期 `el-date-picker`（value-format=YYYY-MM-DD）、添加按钮
- 校验：标题 trim 后非空，否则 `ElMessage.warning('请输入待办标题')`
- 提交后清空标题、保留分类与优先级，便于连续添加

### `TodoFilter.vue`
- 状态切换 `el-radio-group`（全部 / 未完成 / 已完成）
- 分类 `el-select`（选项来自 store `categories`，含「全部分类」）
- 关键字 `el-input`（带搜索图标，clearable）
- 「清除已完成」`el-button`（`el-popconfirm` 确认）
- 统计文字：「已完成 X / 共 Y（完成率 Z%）」

### `TodoList.vue`
- 遍历 `filteredTodos` 渲染 `TodoItem`
- 列表为空时显示 `el-empty`（区分「无待办」与「筛选无结果」文案）

### `TodoItem.vue`
- 左：复选框勾选完成（标题完成后加删除线）
- 中：标题、分类 `el-tag`、优先级 `el-tag`、截止日期（过期且未完成 → danger 文字）
- 右：「编辑」「删除」按钮
- 编辑态：切换为内联表单（标题 input + 优先级 + 分类 + 日期 + 保存/取消），回车或点保存调用 `updateTodo`

## 8. 数据流

TodoInput  ──addTodo()──►  Pinia store  ──$subscribe──►  localStorage
TodoFilter ──setFilter()─►      ▲
TodoItem   ──toggle/update/remove─┘
                                 │
                          filteredTodos (getter)
                                 ▼
                            TodoList → TodoItem 渲染


单向数据流：组件只读 getter、派发 action；持久化由 store 自动完成，组件无感知。

## 9. 错误处理与边界

- `utils/storage.ts` 的 `loadTodos` / `saveTodos` 全部 `try/catch`：
  - 读取解析失败 → 返回空数组 + `console.warn`
  - 写入失败（隐私模式 / 配额超限）→ `console.warn`，不阻断 UI
- 表单校验标题非空
- `id` 用 `crypto.randomUUID()`；若环境不支持则回退 `Date.now() + Math.random().toString(36)`
- 截止日期：仅展示，过期判断基于字符串日期比较（当天为正常）

## 10. 测试策略（Vitest）

- store 单元测试覆盖：
  - `addTodo`：新增项字段完整、id/时间戳生成
  - `updateTodo` / `toggleTodo` / `removeTodo`：状态正确变更，`updatedAt` 更新
  - `clearCompleted`：仅移除已完成项
  - `filteredTodos`：status / category / keyword 三种条件组合
  - `stats` / `completionRate`：含 total=0 的边界
  - `categories`：去重
- localStorage 用内存对象 mock，验证 `$subscribe` 触发写入

## 11. 实现里程碑（供 writing-plans 拆解）

1. 脚手架：重写 `package.json`、`vite.config.ts`、`tsconfig`、`index.html`、`main.ts`、`App.vue`，安装依赖，验证 `npm run dev` 启动
2. 类型 + 持久化：`types/todo.ts`、`utils/storage.ts`
3. Pinia store + 单元测试
4. 组件：`TodoItem` → `TodoList` → `TodoFilter` → `TodoInput`
5. 组装 `App.vue`、样式微调
6. `npm run build` 验证构建通过

✅ 门禁通过： 你确认设计文档后，进入下一阶段。

Step 3：编写计划（writing-plans）

Claude 自动调用 writing-plans 技能，将设计文档拆解为原子任务：

md 复制代码

# 实现计划
Task1：**脚手架** --- 重写 package.json、Vite/TS 配置、安装依赖、启动验证
Task2：**类型 + storage**（TDD）
Task3：**Pinia store**（TDD，含 11 个用例）
Task4：**TodoItem** --- 展示 + 行内编辑
Task5：**TodoList** --- 列表 + 空状态
Task6：**TodoFilter** --- 筛选/搜索/统计/清除已完成
Task7：**TodoInput** --- 新增表单 + 校验
Task8：**组装 App.vue** + 全流程人工验证
Task9：**构建验证** + 收尾

✅ 门禁通过： 你确认任务拆解合理后，进入开发阶段。

Step 4: 调用 executing-plans 技能来按计划落地

Step 5：TDD 开发（test-driven-development）

会先按照计划编写测试用例，再按照测试用例进行实现，需要TDD的Task会完成（TDD 红→绿→重构这个流程）

Step 6：代码审查（Code Review）

每完成一个任务，Claude 自动发起代码审查：

md 复制代码

审查清单：
├── ✅ 所有测试通过，测试全绿（15/15），生产构建通过，类型检查通过。
├── ✅ 代码风格一致
├── ✅ 错误处理完善（文件不存在、ID 不存在等边界情况）
├── ⚠️ 建议：delete 命令缺少二次确认
│   → 已修复：添加了 "确定要删除吗？(y/n)" 确认提示
├── ✅ 类型安全（TypeScript 编译无错误）
└── ✅ 无硬编码路径
审查结果：通过 ✅

Step 7：完成开发分支（Finishing）

所有任务完成后，Claude 执行收尾工作：

bash 复制代码

# 运行完整测试套件
npx vitest run
# ✅ 15 tests passed

# TypeScript 编译检查
npx tsc --noEmit
# ✅ No errors

# 生成 Git 提交
git add .
git commit -m "feat: 实现 TODO List 应用 v1.0

- 支持待办事项 CRUD（增删改查）
- 支持标签分类和过滤
- 数据持久化到本地存储中
- 完整的单元测试覆盖

Co-Authored-By: Claude <xxx@xxx.com>"

最终项目结构

最终页面效果

七、Superpowers 与 OpenSpec 的关系

很多开发者会问：Superpowers 和 OpenSpec 是不是竞争对手？该选哪个？

7.1 对比表

维度	Superpowers	OpenSpec
核心理念	技能驱动（Skill-Based）	规范驱动（Spec-Driven）
侧重点	执行质量、工程纪律	需求治理、决策可追溯
工作方式	AI 自动发现并调用技能	基于结构化规范文档
最佳场景	大型代码库、并行开发	合规要求高、需求频繁变更
安装方式	Claude Code 插件	npm 全局安装
上手难度	⭐⭐ 较简单（激活即用）	⭐⭐⭐ 中等（需要学习规范格式）

7.2 可以一起用！

Superpowers 和 OpenSpec 不是互斥的，推荐组合：

八、常见问题与排错

8.1 安装问题

问题	解决方案
`/plugin` 命令不识别	更新 Claude Code：`npm install -g @anthropic-ai/claude-code@latest`
安装后看不到技能	重启 Claude Code，执行 `/skills` 验证
只显示 7 个技能（应该 14 个）	已知缓存问题，重启会话即可
`SKILL.md` 未检测到	检查文件名大小写，必须是大写 `SKILL.md`

8.2 使用问题

问题	解决方案
技能没有自动激活	每次会话开始时执行 `/superpowers:using-superpowers`
头脑风暴问太多问题	可以在回答中说"需求已经明确"来跳过
子代理执行太慢	小项目可以关闭并行，使用 `executing-plans` 串行执行
Git Worktree 创建失败	确保当前目录是 Git 仓库，且没有未提交的更改

8.3 性能优化建议

场景	建议
小项目（< 5 个文件）	跳过并行子代理，使用串行执行
简单 Bug 修复	可以跳过头脑风暴，直接从 TDD 开始
大型项目	启用全部 14 个技能，充分利用并行能力

九、学习资源

资源	链接
GitHub 仓库	github.com/obra/superp...
作者博客	blog.fsck.com
技能市场	obra/superpowers-marketplace
社区技能库	obra/superpowers-skills