🦸 Superpowers 完整培训指南：让 AI 编程代理遵循工程纪律

📌 作者信息
项目仓库：https://github.com/obra/superpowers
作者：Jesse Vincent (GitHub ID: obra)
GitHub Stars：116k+ ⭐
适合人群：使用 Claude Code / Cursor / Codex 等 AI 编程工具的开发者

---

📋 文档导航

---

一、Superpowers 是什么？

1.1 一句话定义

Superpowers 是一个代理技能框架（Agentic Skills Framework），通过 SKILL.md 文件定义的「技能」，让 AI 编码代理自动遵循结构化的软件开发流程——从头脑风暴到 TDD、从计划制定到代码审查，每个环节都有对应的技能来规范行为。

1.2 解决的核心问题

💡 背景
根据调研数据，84% 的开发者已在使用 AI 编程工具，但 AI 生成的代码在 PR 审查中被打回的概率是人工代码的 1.7 倍。

痛点	没有 Superpowers	有了 Superpowers
需求理解	AI 直接写代码，跳过澄清	苏格拉底式提问，先把事情想清楚
测试环节	先写代码，测试成事后补丁	强制 TDD，先写测试再写代码
代码质量	没有把关机制	两阶段代码审查，Critical 阻塞
上下文污染	长对话导致 AI 偏离方向	子代理隔离，每次任务上下文干净
工程纪律	缺乏 TDD、YAGNI 约束	14 个技能强制最佳实践

1.3 核心特性一览

特性	说明
🚀 自动触发	技能根据上下文自动激活，不需要手动记住命令
🔒 强制执行	不是「建议」而是「强制」，AI 跳过测试会被阻止
🧩 可组合	14 个核心技能像乐高积木一样组合，覆盖完整开发生命周期
💰 Token 轻量	核心引导不到 2000 Token，技能按需加载
🌐 多平台支持	Claude Code、Cursor、Codex、OpenCode、Gemini CLI 等 14 款工具

---

二、安装指南

2.1 Claude Code 安装（推荐）

# 步骤 1：注册插件市场（只需执行一次）
/plugin marketplace add obra/superpowers-marketplace

# 步骤 2：安装 Superpowers 插件
/plugin install superpowers@superpowers-marketplace

# 步骤 3：更新技能到最新版本
/plugin update superpowers

# 步骤 4：重启 Claude Code 或新开会话

# 步骤 5：验证安装
/help

✅ 验证成功：你应该看到以下新命令

• /superpowers:brainstorm - 交互式设计精炼
• /superpowers:write-plan - 创建实施计划
• /superpowers:execute-plan - 批量执行计划

2.2 其他平台安装

Cursor 安装

# 在 Cursor Agent 聊天中执行
/add-plugin superpowers

# 或在插件市场搜索 "superpowers"

Codex / OpenCode 安装

# 告诉 AI 执行以下命令
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md

# OpenCode 用户使用
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

2.3 插件管理命令

# 查看已安装插件
/plugin list

# 更新插件
/plugin update superpowers

# 卸载插件
/plugin uninstall superpowers

---

三、七阶段工作流详解

Superpowers 定义了一套完整的七阶段开发工作流：

阶段 1：🧠 头脑风暴（Brainstorming）

目标：在动手之前，先把事情想清楚

触发方式：

• 自然语言：我想做一个用户认证系统
• 斜杠命令：/superpowers:brainstorm

AI 行为：

你：我想开发一个 Todo List 应用

AI：在开始实现之前，我需要了解几个关键问题：

1️⃣ 技术栈选择
   - 纯前端（React/Vue）还是前后端分离？
   - 用什么数据库？SQLite / PostgreSQL / MongoDB？

2️⃣ 核心功能范围
   - 需要用户认证吗？
   - 需要任务优先级或截止日期吗？
   - 需要标签或分类功能吗？

3️⃣ 部署场景
   - Web 应用？桌面客户端？移动端？
   - 需要离线支持吗？

请逐一回答，我将探索 2-3 种方案供你选择...

设计文档示例（保存到 docs/plans/YYYY-MM-DD-todo-design.md）：

# Todo List 应用设计方案

## 技术选型
**推荐方案**：React + TypeScript + localStorage

### 方案对比

| 方案 | 优点 | 缺点 | 适用场景 |
|------|------|------|----------|
| React + localStorage | 简单，无需后端 | 数据不共享 | 个人使用 |
| React + Firebase | 实时同步，用户认证 | 依赖外部服务 | 快速原型 |
| Next.js + PostgreSQL | 全功能，可扩展 | 开发成本高 | 生产环境 |

## 功能范围
1. 添加任务（文本 + 优先级）
2. 完成任务（toggle）
3. 删除任务
4. 筛选（全部/进行中/已完成）
...

阶段 2：🔀 Git Worktree 隔离

目标：不要在主分支上做实验

AI 自动行为：

🤖 正在创建隔离的开发环境...

1️⃣ 创建新分支：feature/todo-app
2️⃣ 创建 Git Worktree：~/projects/myapp-todo
3️⃣ 运行项目初始化
4️⃣ 确认现有测试全部通过 ✅

📍 你的工作空间已隔离，不会影响主分支

阶段 3：📋 制定计划（Writing Plans）

目标：把大象拆成可以吃的小块

输出格式：每个任务 2-5 分钟可完成

# Todo List 实施计划

**Goal**: Build a simple Todo List app with React

---

### Task 1: 添加任务类型定义

**Files**:
- Create: src/types.ts
- Test: tests/types.test.ts

**Steps**:
1. 写失败测试：`test('Task should have text and completed fields')`
2. 运行测试 → 预期 FAIL ❌
3. 写最小代码让测试通过
4. 重构
5. 运行测试 → 预期 PASS ✅
6. Commit: `git add . && git commit -m "Add Task type definition"`

**验证命令**: `npm test`

---

### Task 2: 添加 localStorage 持久化

**Files**:
- Modify: src/types.ts
- Create: src/storage.ts
- Test: tests/storage.test.ts

... (继续下一个任务)

阶段 4：🤖 子代理驱动开发（Subagent-Driven Development）

目标：让专注的小代理逐个攻克任务

执行模式选择：

模式	说明	适用场景
Subagent 驱动	每个任务派遣新子代理，双阶段审查	复杂项目，长期自治
批量执行	主会话批量执行，定期检查点	中等复杂度

阶段 5：🧪 测试驱动开发（TDD）

目标：先写测试，再写代码，没有例外

RED-GREEN-REFACTOR 循环：

强制示例：

❌ 错误做法（会被阻止）：
你：写一个 email 验证函数
AI：好的，这是代码...（直接开始写）

✅ 正确做法（Superpowers 强制）：
你：写一个 email 验证函数

AI：按照 TDD 流程，我先写失败测试：

// RED: 先写失败测试
test('rejects empty email', async () => {
  const result = await validateEmail('');
  expect(result.valid).toBe(false);
  expect(result.error).toBe('Email required');
});

// 运行测试 → FAIL ❌ (function not defined)

// GREEN: 写最少代码
function validateEmail(email: string) {
  if (!email?.trim()) {
    return { valid: false, error: 'Email required' };
  }
  return { valid: true };
}

// 运行测试 → PASS ✅

// REFACTOR: 代码已简洁，无需重构

常见借口及反驳：

AI 常见借口	Superpowers 反驳
“我已经手动测试过了”	❌ 临时测试不等于系统化测试
“这应该能工作”	✅ 必须看到测试通过才算
“这太简单了，不需要测试”	❌ 越简单越需要测试保护
“这只是个原型”	❌ 原型更需要测试避免回归

阶段 6：🔍 代码审查（Code Review）

目标：自己写的代码，也要有人 Review

两阶段审查流程：

审查问题分级：

级别	说明	处理方式
🔴 Critical	阻塞进度，必须修复	修复前不能继续
🟠 Major	重要问题，建议修复	可以记录但不阻塞
🟡 Minor	优化建议，可选处理	保持记录即可

阶段 7：✅ 分支完成（Branch Completion）

目标：善始善终

AI 提供选项：

🎉 所有任务已完成，测试全部通过

请选择下一步操作：

1️⃣ [合并到主分支] 
   git checkout main && git merge feature/todo-app

2️⃣ [创建 Pull Request]
   创建 PR 并通知团队审查

3️⃣ [保留分支]
   暂时保留，稍后合并

4️⃣ [丢弃分支]
   git branch -D feature/todo-app

5️⃣ [继续开发]
   回到规划阶段，添加新任务

请输入选项编号：

---

四、14 个核心技能详解

4.1 技能总览

类别	技能名称	核心功能
🧠 系统	using-superpowers	技能路由引擎，所有对话的入口
📝 系统	writing-skills	创建新技能的方法论
🤝 协作	brainstorming	苏格拉底式需求精炼
📋 协作	writing-plans	生成 2-5 分钟粒度的实施计划
🚀 协作	executing-plans	批量执行含人工检查点
🎯 协作	dispatching-parallel-agents	并发子代理工作流
🤖 协作	subagent-driven-development	子代理驱动开发 + 两阶段审查
🔍 协作	requesting-code-review	提交代码审查前的自查清单
💬 协作	receiving-code-review	响应代码审查反馈
🧪 测试	test-driven-development	强制 RED-GREEN-REFACTOR 循环
🔧 调试	systematic-debugging	4 阶段根因分析
✅ 调试	verification-before-completion	确认问题真正被修复
🔀 版本控制	using-git-worktrees	Git Worktree 隔离开发
🏁 版本控制	finishing-a-development-branch	合并/创建 PR 的决策工作流

4.2 技能触发机制

触发优先级：

触发关键词（不需要记命令）：

意图	关键词示例
规划功能	plan 一个功能、帮我规划、设计一下
写代码	implement、实现这个功能、帮我写
调试问题	debug 这个测试、为什么报错了、帮忙排查
代码审查	review 这段代码、帮我看看有没有问题
重构优化	refactor 这个模块、怎么优化更好

---

五、实战案例

案例 1：开发一个 Todo List 应用

Step 1: 需求提出

你：我想用 React 开发一个简单的 Todo List 应用

Step 2: AI 触发 Brainstorming

AI：收到！让我先通过 brainstorming 帮你澄清需求。

❓ 问题 1：关于技术栈
   - 是纯前端还是要后端？
   - 用 Create React App / Vite / Next.js？
   - 数据存储在哪？localStorage / Firebase / 自己后端？

❓ 问题 2：核心功能
   - 只需要增删改查，还是要支持：
     - 任务优先级？
     - 截止日期？
     - 标签/分类？
     - 搜索/筛选？

❓ 问题 3：用户体验
   - 需要离线支持吗？
   - 要支持拖拽排序吗？
   - 需要暗色模式吗？

请逐一回答，我将给出 2-3 个方案供你选择...

Step 3: 确认设计，进入规划

✅ 设计确认完成！

📄 设计文档已保存到 docs/plans/2026-01-15-todo-design.md

现在进入规划阶段，我将把设计拆解为 2-5 分钟可完成的小任务...

Step 4: 执行 TDD 循环

🤖 开始执行计划 - Task 1: 添加任务类型

📝 RED 阶段：写失败测试
test('Task should have text and completed fields', () => {
  const task = new Task('Buy milk', false);
  expect(task.text).toBe('Buy milk');
  expect(task.completed).toBe(false);
});

▶ 运行测试
✗ FAIL: ReferenceError: Task is not defined

🟢 GREEN 阶段：写最少代码
class Task {
  constructor(public text: string, public completed: boolean) {}
}

▶ 运行测试
✓ PASS

🔄 REFACTOR 阶段：无需重构

✅ Task 1 完成！

案例 2：Bug 修复流程

你：我的代码在用户注册时偶尔会崩溃，帮我看看

AI：按照 systematic-debugging 流程，我们进行四阶段分析：

📌 阶段 1：复现问题
   - 复现步骤是什么？
   - 必现还是偶现？频率？
   - 控制台错误信息？

📌 阶段 2：采集数据
   - 最小复现代码？
   - 相关日志？
   - 环境信息？

📌 阶段 3：分析原因
   - 列出可能的根因假设
   - 逐一验证

📌 阶段 4：验证修复
   - 必须通过 TDD 验证

你：请提供更多信息...

案例 3：快速代码审查

你：帮我 review 这段代码

/superpowers:request-code-review

代码：
function calculateTotal(items) {
  let total = 0;
  for (let i = 0; i < items.length; i++) {
    total += items[i].price * items[i].quantity;
  }
  return total;
}

AI：🔍 代码审查报告

【规格审查】✅ 通过
   - 函数功能符合需求

【质量审查】

🔴 Critical: 无
🟠 Major: 
   - 缺少空值检查：items[i] 可能为 null/undefined
   - 缺少类型定义：建议添加 TypeScript 类型
 
🟡 Minor:
   - 可以使用 reduce 简化循环

建议修复 Major 问题后再合并...

---

六、常见问题 FAQ

Q1: 安装后没反应怎么办？

# 1. 检查 Claude Code 版本（需要 >= 2.0.13）
claude --version

# 2. 验证插件是否安装
/plugin list

# 3. 尝试触发关键词
"帮我 plan 一个功能" 或 "plan 一下这个"

# 4. 如果还是不行，手动触发
/superpowers:brainstorm

Q2: Superpowers 让 AI 变慢了，值得吗？

场景	建议
快速原型/一次性脚本	可能不需要完整流程
生产级代码/长期维护项目	绝对值得！

收益量化：

• 减少 70% 的后期调试时间
• 单元测试覆盖率从 45% 提升到 85%+
• 代码审查时间减少 60%
• Claude Code 可自主运行数小时不偏离方向

Q3: 如何创建自定义技能？

# 步骤 1：在 skills/ 目录创建文件
skills/my-custom-skill/SKILL.md

# 步骤 2：使用 YAML Frontmatter 定义元数据
---
name: my-custom-skill
trigger: custom-scenario
priority: 50
---

# 步骤 3：编写技能内容
## When to use this skill
...

## Process
1. Step 1
2. Step 2
...

## Verification Checklist
- [ ] Check 1
- [ ] Check 2

Q4: 团队如何统一使用？

# 1. 创建团队技能库（内部 Git 仓库）
git clone git@github.com:your-org/team-skills.git
cd team-skills
npm install

# 2. 自动安装到所有项目
npx superpowers-zh

# 3. 提交团队规范
git add .
git commit -m "feat: 添加团队规范技能"

---

七、最佳实践

7.1 推荐的完整工作流

1️⃣  /superpowers:brainstorm  → 输入你的需求，让 AI 充分提问讨论

2️⃣  /superpowers:write-plan   → 生成计划文档

3️⃣  手动审查计划（关键！）→ 和 AI 来回修改，确保细节正确

4️⃣  /superpowers:execute-plan → 让子代理按计划执行

⚠️ 关键心得：不要跳过手动审查计划这一步！
计划的质量直接决定了执行的质量。花时间在计划上，可以节省大量返工的时间。

7.2 适用场景判断

7.3 不太适合的场景

• ❌ 快速 Bug 修复（一两行代码）
• ❌ 原型和 Demo（不需要工程纪律）
• ❌ 单文件小改动
• ❌ 简单的配置变更

---

八、生态系统与资源

8.1 相关仓库

仓库	说明
obra/superpowers	核心插件
obra/superpowers-marketplace	Claude Code 插件市场
jnMetaCode/superpowers-zh	🇨🇳 中文增强版 + 6 个中国特色技能
obra/superpowers-skills	社区技能库
obra/superpowers-lab	实验性技能

8.2 支持的平台

平台	安装方式
Claude Code	插件市场一键安装 ⭐
Cursor	/add-plugin superpowers
Windsurf	插件市场搜索
Kiro	手动安装
Gemini CLI	手动安装
Codex CLI	INSTALL.md
OpenCode	INSTALL.md
Aider	手动安装
Trae	手动安装
Qwen Code	手动安装

8.3 学习资源

• 📖 官方文档
• 📝 博客：Superpowers 诞生记
• 📝 Superpowers 4.0 发布说明
• 💬 GitHub Discussions

---

九、总结

核心价值

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   🦸 Superpowers = 让 AI 用「正确的方式」写代码            │
│                                                             │
│   不是追求 AI 写更多代码，而是追求 AI 遵循工程纪律           │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Superpowers vs 其他工具

特性	Superpowers	普通 AI 编程
需求澄清	✅ 强制 Brainstorming	❌ 直接写代码
测试覆盖	✅ 强制 TDD	❌ 跳过测试
代码审查	✅ 自动双阶段审查	❌ 无
长期自治	✅ 数小时自主运行	❌ 单次交互
工程纪律	⭐⭐⭐⭐⭐	⭐

行动建议

🚀 现在就开始：
   1. 打开 Claude Code
   2. 执行 /plugin marketplace add obra/superpowers-marketplace
   3. 执行 /plugin install superpowers@superpowers-marketplace
   4. 用一个小项目开始体验

---

📌 编者手记

Superpowers 代表了 AI 编程的一个重要思路转变：与其让 AI 写更多代码，不如让 AI 用正确的方式写代码。

它通过一套精心设计的技能系统，将数十年的软件工程最佳实践——TDD、系统化调试、结构化规划、代码审查——编码成 AI 可以理解和执行的指令。

如果你正在用 Claude Code 做真实项目开发，Superpowers 值得一试。

---

参考资料：GitHub - obra/superpowers、博客园教程、AI产品库

---

💬 讨论区

您使用 Superpowers 有什么心得？欢迎在评论区分享！

如果觉得这篇文章有帮助，请点赞并关注，我会持续更新 AI 编程工具的最新教程。

---