Superpowers教程
markdown
2026年7月17日7 min read1,221 words
Updated 2026年7月17日
Superpowers 完整教程：AI 驱动的软件开发方法论
目录
- 痛点导入：我们遇到了什么问题？
- Superpowers 是什么？
- 核心理念：为什么这样做？
- 技能体系全解
- 快速入门：5 分钟安装
- 实战演示：完整开发流程
- 最佳实践与避坑指南
- 方法论总结：如何写好技术教程
1. 痛点导入：我们遇到了什么问题？
1.1 AI 编码助手的现状
当你使用 Claude Code、Cursor、GitHub Copilot 等 AI 编程工具时，是否遇到过以下情况？
| 症状 | 描述 |
|---|---|
| 盲目开始 | AI 一上来就写代码，写完才发现方向跑偏 |
| 上下文丢失 | 大项目进行到一半，AI 突然"失忆"，不知道之前做了什么 |
| 边界模糊 | 不清楚 AI 做了什么改动，为什么要这样改 |
| 质量参差 | 代码能跑，但架构混乱、缺少测试、难以维护 |
| 协作困难 | 多轮对话后，AI 的理解和你的意图南辕北辙 |
1.2 根本原因
AI 缺乏结构化的工作方法。
大多数 AI 编程工具是「问答式」的——你问，它答；你让它写，它就写。这种模式的问题在于：
1.3 Superpowers 的答案
Superpowers 不是另一个 AI 编程工具，而是一套让 AI 遵循规范流程工作的方法论。
核心理念：AI 不应该一上来就写代码。它应该先退后一步，询问真实目标，展示可消化的小块设计，编制清晰的实施计划，然后启动结构化的执行流程。
2. Superpowers 是什么？
2.1 一句话定义
Superpowers 是一个面向 AI 编码代理的技能框架（Skills Framework）和软件开发方法论。
2.2 项目档案
| 属性 | 内容 |
|---|---|
| GitHub | obra/superpowers |
| Stars | 243k |
| 最新版本 | v6.1.0 (2026-06-30) |
| 主要语言 | Shell (51.8%), JavaScript (41.1%) |
| 许可证 | MIT |
| 支持平台 | Claude Code, Cursor, Codex, Copilot CLI, Kimi Code, OpenCode, Pi 等 |
2.3 它不是什么？
| ❌ 不是 | ✅ 而是 |
|---|---|
| 替代 AI 编程工具 | 给 AI 编程工具装上"方法论引擎" |
| 另一个 IDE | 一套可组合的技能（Skills）系统 |
| 代码生成器 | 结构化的开发流程规范 |
3. 核心理念：为什么这样做？
3.1 四大哲学原则
原则一：测试驱动开发（TDD）
"先写测试，再写代码；让测试引导设计。"
RED (失败测试) → GREEN (最小代码通过) → REFACTOR (改进设计)
TDD 不是为了写测试而写测试，而是通过测试来定义行为边界、驱动设计决策、建立安全网。
原则二：系统性优于临时性
"每一步都有目的，每个决定都有依据。"
不要临时打补丁，而是思考问题的系统性解决方案。
原则三：复杂度最小化
"用最简单的方案解决问题，不为未来可能的需求预加复杂度。"
YAGNI 原则（You Aren't Gonna Need It）的体现。
原则四：以证据验证，而非主观断言
"代码好不好，看测试结果，不看感觉。"
所有变更都需要有对应的验证机制。
3.2 为什么 AI 需要方法论？
| 人类开发者 | AI 代理 |
|---|---|
| 有多年经验积累 | 依赖 prompt 质量 |
| 有自我纠错能力 | 容易陷入"幻觉" |
| 理解业务上下文 | 需要显式告知 |
| 会主动提问 | 默认直接执行 |
Superpowers 给 AI 装上了"思维框架"，让它像经验丰富的工程师一样思考。
4. 技能体系全解
Superpowers 的技能分为四大类，涵盖开发全生命周期：
┌─────────────────────────────────────────────────────────┐
│ Superpowers 技能库 │
├─────────────┬─────────────┬─────────────┬──────────────┤
│ Testing │ Debugging │ Collaboration│ Meta │
├─────────────┼─────────────┼─────────────┼──────────────┤
│ TDD │ 系统调试 │ 头脑风暴 │ 写技能 │
│ │ 完成前验证 │ 写计划 │ 使用指南 │
│ │ │ 执行计划 │ │
│ │ │ 并行代理 │ │
│ │ │ 代码审查 │ │
│ │ │ 接收审查 │ │
│ │ │ Git Worktree│ │
│ │ │ 完成分支 │ │
│ │ │ 子代理开发 │ │
└─────────────┴─────────────┴─────────────┴──────────────┘
4.1 Testing（测试）技能
test-driven-development
什么时候用：实现任何新功能时
核心流程：
触发时机：当开始实现功能时自动激活
4.2 Debugging（调试）技能
systematic-debugging
什么时候用：遇到 bug 时
四阶段根因分析：
阶段 1: 复现 → 找到能稳定复现 bug 的步骤
阶段 2: 隔离 → 缩小问题范围，定位关键代码
阶段 3: 追溯 → 追踪根因，不满足于表面修复
阶段 4: 验证 → 确认修复有效，添加回归测试
verification-before-completion
什么时候用：修复完成后
检查清单：
- 修复真正解决了问题吗？
- 有没有引入新的问题？
- 测试覆盖了这个场景吗？
4.3 Collaboration（协作）技能
brainstorming（头脑风暴）
什么时候用：开始任何任务之前
苏格拉底式提问流程：
1. 理解目标 → "你想解决什么问题？"
2. 探索约束 → "有什么限制条件？性能？兼容性？"
3. 分析边界 → "什么情况不需要处理？"
4. 讨论方案 → "有几种可能的方案？各有什么优缺点？"
5. 确认理解 → "我的理解是...对吗？"
输出：设计文档，记录决策和理由
writing-plans（编写计划）
什么时候用：头脑风暴确认后
任务分解原则：
- 每个任务 2-5 分钟完成
- 每个任务有精确的文件路径
- 每个任务有完整的代码变更
- 每个任务有验证步骤
计划格式：
## 任务 N：描述
### 文件
- `src/xxx.ts` (新增/修改)
### 变更
```typescript
// 具体代码
```
### 验证
1. 步骤1
2. 步骤2
executing-plans（执行计划）
什么时候用：计划编写完成后
执行模式：
- 逐个执行：一个任务完成 → 审查 → 下一个
- 批量执行 + 检查点：多个任务后人工审核
dispatching-parallel-agents（并行代理）
什么时候用：有多个独立任务时
工作流：
requesting-code-review（请求代码审查）
什么时候用：任务间自动触发
报告格式：
## 代码审查报告
### 🔴 阻塞性问题（必须修复）
- ...
### 🟡 严重问题（强烈建议修复）
- ...
### 🟢 建议改进（可选）
- ...
using-git-worktrees（使用 Git Worktree）
什么时候用：并行开发多个功能时
优势：
- 每个功能有独立的 git 工作目录
- 避免分支切换的上下文丢失
- 可以同时运行多个任务
finishing-a-development-branch（完成开发分支）
什么时候用：任务完成后
决策选项：
- 合并（Merge） → 代码已就绪
- 创建 PR → 需要团队审查
- 保留分支 → 暂时搁置
- 丢弃分支 → 放弃变更
4.4 Meta（元技能）
using-superpowers
用途：Superpowers 系统入门介绍，新用户必读
writing-skills
用途：如何创建新技能的最佳实践
5. 快速入门：5 分钟安装
5.1 支持的平台
| 平台 | 安装命令 |
|---|---|
| Claude Code | /plugin install superpowers@claude-plugins-official |
| Antigravity | agy plugin install https://github.com/obra/superpowers |
| Cursor | /add-plugin superpowers |
| GitHub Copilot CLI | copilot plugin install superpowers@superpowers-marketplace |
| Kimi Code | /plugins install https://github.com/obra/superpowers |
| OpenCode | Fetch from .opencode/INSTALL.md |
5.2 Claude Code 安装步骤
# 方法一：官方市场
/plugin install superpowers@claude-plugins-official
# 方法二：Superpowers 市场
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
5.3 安装验证
安装完成后，启动 Claude Code，输入：
/using-superpowers
如果看到欢迎信息和技能列表，说明安装成功。
5.4 禁用遥测（可选）
export SUPERPOWERS_DISABLE_TELEMETRY=true
Superpowers 默认会加载 Prime Radiant Logo 用于统计用户数（100% 可选）。
6. 实战演示：完整开发流程
场景：实现一个"用户登录"功能
Step 1: 头脑风暴（Brainstorming）
你输入：
我要做一个用户登录功能
Superpowers 激活 brainstorming 技能，开始提问：
🤔 在开始之前，我想先理解几个问题：
1. 认证方式：
- 用户名+密码？
- 第三方登录（Google/GitHub）？
- 手机验证码？
2. 会话管理：
- JWT Token？
- Session + Cookie？
3. 密码要求：
- 最小长度？
- 需要特殊字符？
4. 用户场景：
- 注册时是否需要邮箱验证？
- 忘记密码如何处理？
请告诉我你的具体需求。
你的回答：简单起见，先做用户名+密码+JWT
Superpowers 继续提问并最终输出设计文档：
# 用户登录功能设计
## 需求概述
- 用户名 + 密码登录
- JWT Token 会话管理
- 密码加密存储（bcrypt）
## API 设计
- POST /api/auth/login
- POST /api/auth/register
- POST /api/auth/logout
- GET /api/auth/me
## 数据模型
- User: id, username, email, passwordHash, createdAt
## 安全考虑
- 密码使用 bcrypt 加密（cost factor: 12）
- JWT 过期时间：24小时
- 登录失败锁定：5次后锁定15分钟
## 初步方案确认
请确认以上设计，或告诉我需要调整的地方。
Step 2: 编写计划（Writing Plans）
设计确认后，Superpowers 激活 writing-plans 技能：
## 用户登录功能实施计划
### 任务 1: 创建数据模型
- 文件：`src/models/user.ts`
- 创建 User 类型和 Prisma schema
- 验证：npx prisma validate
### 任务 2: 实现密码加密
- 文件：`src/utils/auth.ts`
- 使用 bcrypt 加密密码
- 验证：npm test
### 任务 3: 实现注册 API
- 文件：`src/routes/auth.ts`
- POST /api/auth/register
- 验证：curl 测试
### 任务 4: 实现登录 API
- 文件：`src/routes/auth.ts`
- POST /api/auth/login
- 返回 JWT Token
- 验证：curl 测试
### 任务 5: 编写集成测试
- 文件：`tests/auth.test.ts`
- 测试注册、登录、错误场景
- 验证：npm test
---
预计总时间：15-20 分钟
Step 3: 执行计划（Executing Plans）
Superpowers 开始执行：
📋 开始执行任务 1/5
🔄 正在创建数据模型...
✅ 任务 1 完成
🔍 正在审查...
检查项：
- [x] 类型定义完整
- [x] Prisma schema 有效
- [ ] 需要添加索引
📋 开始执行任务 2/5
...
每个任务完成后，Superpowers 会进行两阶段审查：
- 规格合规 → 代码是否满足计划要求？
- 代码质量 → 是否有潜在问题？
Step 4: 测试驱动开发（示例）
// 📝 先写测试 (RED)
describe('User Model', () => {
it('should hash password before saving', async () => {
const user = new User({
username: 'test',
password: 'PlainPassword123'
});
await user.save();
expect(user.passwordHash).not.toBe('PlainPassword123');
expect(await bcrypt.compare('PlainPassword123', user.passwordHash)).toBe(true);
});
});
// 📝 写最小代码通过 (GREEN)
class User {
passwordHash: string;
async save() {
this.passwordHash = await bcrypt.hash(this.password, 12);
// ... 保存逻辑
}
}
// 📝 重构 (REFACTOR)
class User {
private _password: string;
get password() { return this._password; }
set password(value: string) {
this.passwordHash = await bcrypt.hash(value, 12);
}
// ... 更干净的设计
}
7. 最佳实践与避坑指南
7.1 有效使用 Superpowers
| ✅ 推荐 | ❌ 避免 |
|---|---|
| 明确描述你的目标 | "帮我写个功能" |
| 回答 Superpowers 的提问 | 跳过澄清环节 |
| 确认设计后再开始 | 跳过头脑风暴 |
| 查看并确认计划 | 直接让 AI 写代码 |
| 定期检查进度 | 完全放手不管 |
7.2 调试时使用 systematic-debugging
遇到问题时，不要直接问"为什么报错"，而是：
1. 先复现：找到稳定的复现步骤
2. 再隔离：缩小问题范围
3. 再追溯：找到根因
4. 最后验证：确认修复有效
7.3 团队协作建议
- 代码审查是必须的：Superpowers 的 requesting-code-review 技能会自动在任务间触发
- 使用 Git Worktree：多人并行开发时保持工作区隔离
- 保留设计文档：brainstorming 的输出是重要的知识沉淀
8. 方法论总结：如何写好技术教程
8.1 本教程遵循的教学设计原则
| 原则 | 应用 | 理论依据 |
|---|---|---|
| 痛点导入 | 从 AI 编程的实际问题出发 | 成人学习理论：学习动机来自解决真实问题 |
| 循序渐进 | 概念 → 理念 → 技能 → 实战 | 认知负荷理论：分块降低认知负担 |
| 类比解释 | 用人类开发者的类比解释 AI 行为 | 建构主义：新知识需要依附已有知识 |
| 表格对比 | 用表格清晰呈现对比信息 | 双重编码理论：文字+结构增强记忆 |
| 代码示例 | 每个技能都有具体代码 | 做中学：实践出真知 |
| 流程图示 | 用 ASCII 图展示流程 | 空间认知：视觉化帮助理解 |
8.2 教程结构模板
1. 痛点导入（Why）
└── 读者面临的实际问题
2. 工具介绍（What）
└── 这个工具是什么，不是什么
3. 核心理念（Philosophy）
└── 为什么这样做，背后有什么原理
4. 技能详解（How）
└── 分解每个功能模块
5. 快速入门（Quick Start）
└── 5分钟能跑起来的最小示例
6. 实战演示（Demo）
└── 完整的端到端案例
7. 最佳实践（Best Practices）
└── 经验总结和避坑指南
8. 方法论总结（Meta）
└── 这篇教程本身的方法论
8.3 写作技巧
- 用读者的语言：避免术语堆砌，需要术语时先解释
- 小步快跑：每个章节控制在可消化的篇幅
- 多感官刺激：文字 + 代码 + 表格 + 图表
- 留白思考：不要把所有答案都塞给读者
- 承上启下：每个章节开头回顾上文，引出下文
附录
A. 资源链接
| 资源 | 链接 |
|---|---|
| GitHub 仓库 | https://github.com/obra/superpowers |
| 官方文档 | docs/ 目录下各平台文档 |
| Discord 社区 | discord.gg/35wsABTejz |
B. 相关工具对比
| 工具 | 定位 | Superpowers 能替代它吗？ |
|---|---|---|
| Claude Code | AI 编程工具 | 需要 Superpowers 提供方法论 |
| Cursor | AI 编程工具 | 需要 Superpowers 提供方法论 |
| Copilot | AI 编程工具 | 需要 Superpowers 提供方法论 |
| Superpowers | AI 方法论框架 | 补充上述工具的流程规范 |
C. 版本历史
- v6.1.0 (2026-06-30) - 最新版本
- v6.0.0 - 重大更新
- 查看完整发布说明：RELEASE-NOTES.md
教程版本：v1.0
最后更新：2026-07-01
作者：AI 应用工程师 / 教育专家