Superpowers 框架完全指南：让 Claude Code 和 Codex 拥有”超能力”
摘要：Superpowers 是一个基于技能（Skills）的 AI 编程代理框架，由 Jesse Vincent 开发。它通过一套可组合的技能和标准化工作流程，让 Claude Code、Codex 等编码助手能够像专业工程师一样思考和工作。本文将详细介绍 Superpowers 的安装配置、核心技能系统，以及在 Claude Code 和 Codex 上的实战使用。
一、Superpowers 是什么？
Superpowers 是一个完整的软件开发工作流框架，专为编码代理（Coding Agents）设计。它的核心理念是：
让 AI 代理在写代码之前，先理解你要做什么，然后制定计划，最后才执行。
1.1 核心工作流程
Superpowers 强制 AI 遵循以下流程：
1. 头脑风暴（Brainstorming）→ 理解需求，澄清模糊点 2. 设计确认（Design Sign-off）→ 分块展示设计，等待用户确认 3. 实现计划（Implementation Plan）→ 拆解为 2-5 分钟的小任务 4. 执行开发（TDD + Subagent）→ 测试驱动开发，子代理执行 5. 代码审查（Code Review）→ 每个任务完成后审查 6. 分支收尾（Finish Branch）→ 合并/PR/清理
1.2 为什么需要 Superpowers？
没有 Superpowers 的 AI 编程：
- 直接跳进代码实现
- 不理解真实需求
- 容易跑偏，需要反复纠正
- 缺乏测试，质量不稳定
有 Superpowers 的 AI 编程：
- 先问清楚”你真正想要什么”
- 设计分块确认，避免误解
- 任务拆解清晰，可追踪
- 强制 TDD，质量有保障
- 自动代码审查，问题早发现
1.3 技能（Skills）系统
Superpowers 的核心是技能系统。每个技能是一个包含 SKILL.md 文件的目录，定义了：
- 触发条件（什么时候使用这个技能）
- 执行步骤（具体怎么做）
- 输出规范（应该产生什么结果）
技能是强制性的，不是建议。当条件匹配时，AI 必须使用对应的技能。
二、安装 Superpowers
Superpowers 支持多个平台：Claude Code、Cursor、Codex、OpenCode、Gemini CLI。安装方式因平台而异。
2.1 Claude Code 安装
方式一：官方插件市场（推荐）
# 启动 Claude Code claude # 安装插件 /plugin install superpowers@claude-plugins-official
方式二：Superpowers 市场
# 先注册市场 /plugin marketplace add obra/superpowers-marketplace # 安装插件 /plugin install superpowers@superpowers-marketplace
验证安装
安装完成后，重启 Claude Code，你会看到一个新的注入提示：
<session-start-hook> <EXTREMELY_IMPORTANT> You have Superpowers. **RIGHT NOW, go read**: @/Users/jesse/.claude/plugins/cache/Superpowers/skills/getting-started/SKILL.md </EXTREMELY_IMPORTANT> </session-start-hook>
更新插件
/plugin update superpowers
2.2 Cursor 安装
在 Cursor Agent 聊天中：
# 方式一：直接安装 /add-plugin superpowers # 方式二：在市场搜索 # 在插件市场搜索 "superpowers"
2.3 Codex（OpenAI）安装
Codex 使用本地技能发现机制，需要手动克隆和创建符号链接。
步骤 1：克隆仓库
git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
步骤 2：创建技能符号链接
# 创建技能目录 mkdir -p ~/.agents/skills # 创建符号链接 ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers
Windows 用户（使用 Junction）
Windows 上符号链接可能需要管理员权限，使用 Junction 替代：
# 创建目录 New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills" # 创建 Junction（不需要开发者模式） cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"
步骤 3：配置多代理支持（可选）
部分技能（如 dispatching-parallel-agents、subagent-driven-development）需要 Codex 的多代理功能：
# ~/.codex/config.toml [features] multi_agent = true
步骤 4：重启 Codex
技能在 Codex 启动时被发现。重启后，询问：
Tell me about your superpowers
更新技能
cd ~/.codex/superpowers && git pull
技能通过符号链接即时更新，无需重启。
卸载
# 删除符号链接 rm ~/.agents/skills/superpowers # 可选：删除克隆的仓库 rm -rf ~/.codex/superpowers
2.4 OpenCode 安装
OpenCode 使用插件系统，配置更简单。
步骤 1：修改配置文件
在全局或项目级的 opencode.json 中添加：
{
"plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
}
步骤 2：指定版本（可选）
{
"plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"]
}
步骤 3：重启 OpenCode
插件会自动通过 Bun 安装并注册所有技能。
验证
Tell me about your superpowers
使用技能工具
use skill tool to list skills use skill tool to load superpowers/brainstorming
清理旧安装
如果之前用 git clone + 符号链接安装过，先清理：
# 删除旧符号链接 rm -f ~/.config/opencode/plugins/superpowers.js rm -rf ~/.config/opencode/skills/superpowers # 可选：删除克隆的仓库 rm -rf ~/.config/opencode/superpowers # 从 opencode.json 移除 skills.paths 配置
2.5 Gemini CLI 安装
# 安装扩展 gemini extensions install https://github.com/obra/superpowers # 更新扩展 gemini extensions update superpowers
三、核心技能详解
Superpowers 包含多个技能，覆盖完整的开发流程。以下是核心技能的介绍和使用场景。
3.1 设计与规划类
brainstorming – 头脑风暴
触发时机：开始写代码之前
功能：
- 通过提问澄清模糊需求
- 探索多种实现方案
- 分块展示设计，等待用户确认
- 保存设计文档
示例对话：
用户：我想做一个待办事项应用 AI（触发 brainstorming）： 好的，让我先了解一些细节： 1. 这个应用是 Web 端、移动端还是桌面端？ 2. 需要用户登录吗？数据存在哪里？ 3. 需要哪些核心功能？（增删改查、分类、提醒...） 4. 有技术栈偏好吗？ 5. 预计用户规模？ 我们先花 5 分钟把需求理清楚，再开始设计。
writing-plans – 编写实现计划
触发时机：设计确认后
功能：
- 将工作拆解为 2-5 分钟的小任务
- 每个任务包含：精确文件路径、完整代码、验证步骤
- 强调 YAGNI（You Aren’t Gonna Need It）和 DRY 原则
计划示例：
## 任务 1：项目初始化 - 文件：`package.json`, `tsconfig.json` - 步骤： 1. 创建 package.json，配置 dependencies 2. 创建 tsconfig.json，启用严格模式 - 验证：`npm install` 无错误 ## 任务 2：数据库 Schema - 文件：`src/db/schema.ts` - 步骤： 1. 定义 Todo 接口 2. 创建 SQLite 表结构 - 验证：运行迁移脚本 ## 任务 3：API 路由 - 文件：`src/routes/todos.ts` - 步骤： 1. GET /todos - 获取列表 2. POST /todos - 创建 3. PUT /todos/:id - 更新 4. DELETE /todos/:id - 删除 - 验证：curl 测试每个端点
3.2 开发与执行类
using-git-worktrees – 使用 Git 工作树
触发时机：设计批准后，开始实现前
功能：
- 在新分支上创建隔离的工作区
- 运行项目初始化
- 验证测试基线干净
优势：
- 支持并行开发多个功能
- 不会互相干扰
- 易于清理和回滚
subagent-driven-development – 子代理驱动开发
触发时机：计划确认后
功能：
- 为每个任务分配 fresh subagent
- 两阶段审查：规范合规性 → 代码质量
- 自动继续下一个任务
工作流程：
主代理 → 分派任务 1 → Subagent A → 完成 → 审查 → ✓
→ 分派任务 2 → Subagent B → 完成 → 审查 → ✓
→ 分派任务 3 → Subagent C → 完成 → 审查 → ✗ 修复
→ ...
test-driven-development – 测试驱动开发
触发时机：实现过程中
功能：
- 强制 RED-GREEN-REFACTOR 循环
- 写失败测试 → 看它失败 → 写最少代码 → 看它通过 → 提交
- 删除测试前写的代码
核心原则：
1. 先写测试（RED） 2. 运行测试，确认失败 3. 写刚好能让测试通过的代码（GREEN） 4. 运行测试，确认通过 5. 重构代码（REFACTOR） 6. 提交
executing-plans – 执行计划
触发时机：有计划，但不使用子代理时
功能：
- 批量执行任务
- 在关键点设置人工检查点
- 适合小型任务或快速迭代
3.3 审查与收尾类
requesting-code-review – 请求代码审查
触发时机：任务完成后
功能：
- 对照计划审查代码
- 按严重程度报告问题
- 关键问题阻止进度
审查清单：
- [ ] 代码符合设计规范吗？
- [ ] 测试覆盖充分吗？
- [ ] 有安全漏洞吗？
- [ ] 性能可接受吗？
- [ ] 代码可读吗？
finishing-a-development-branch – 完成开发分支
触发时机：所有任务完成后
功能：
- 验证所有测试通过
- 提供选项：合并/PR/保留/丢弃
- 清理工作树
3.4 调试类
systematic-debugging – 系统化调试
触发时机：遇到 bug 时
功能：
- 4 阶段根因分析流程
- 根因追踪技术
- 防御性编程
- 条件等待技术
调试流程：
1. 复现问题 → 最小化复现步骤 2. 定位根因 → 二分查找、日志分析 3. 设计修复 → 考虑边界情况 4. 验证修复 → 确保真的修好了
verification-before-completion – 完成前验证
触发时机：声称修复 bug 后
功能：
- 确保问题真的解决了
- 防止”看起来修好了”的假阳性
3.5 协作类
dispatching-parallel-agents – 分派并行代理
触发时机：需要并发处理多个任务时
功能：
- 同时启动多个子代理
- 协调结果合并
- 适合独立任务
receiving-code-review – 接受代码审查
触发时机：收到审查反馈时
功能：
- 如何回应审查意见
- 优先级处理（Critical → Major → Minor）
- 讨论和协商技巧
3.6 元技能
writing-skills – 编写技能
触发时机：需要创建新技能时
功能：
- 技能创建最佳实践
- 技能测试方法
- 技能文档规范
using-superpowers – 使用 Superpowers 入门
触发时机：新会话开始
功能：
- 介绍技能系统
- 如何查找和使用技能
- 技能使用纪律
四、核心原则
Superpowers 建立在几个核心原则之上：
4.1 测试驱动开发（TDD）
写测试优先，永远。
- 测试是规格说明
- 测试是安全网
- 测试是设计工具
4.2 系统化胜过临时发挥
流程胜过猜测。
- 遵循既定流程
- 不要跳过步骤
- 每一步都有明确目标
4.3 复杂度降低
简单性是首要目标。
- YAGNI：你不会需要它
- DRY：不要重复自己
- KISS：保持简单
4.4 证据胜过声明
验证后再宣布成功。
- 不要说”应该修好了”
- 要说”测试通过了”
- 用数据说话
五、实战示例
5.1 示例 1：用 Claude Code 开发功能
场景：为现有项目添加用户登录功能
# 启动 Claude Code claude
对话流程：
用户：我想给项目添加用户登录功能
[AI 自动触发 brainstorming 技能]
AI: 好的，让我先了解一些细节：
1. 需要哪些登录方式？（邮箱/密码、OAuth、魔法链接...）
2. 用现有的认证服务还是自己实现？
3. 需要记住登录状态吗？session 还是 JWT？
4. 有安全要求吗？（2FA、密码强度...）
5. 用户表已经存在吗？
我们先花几分钟把需求理清楚。
用户：1. 邮箱/密码 + Google OAuth
2. 自己实现，用 JWT
3. 需要记住登录，7 天有效期
4. 需要密码强度和 2FA
5. 用户表已存在，需要加字段
[AI 保存设计文档，触发 using-git-worktrees]
AI: 好的，我创建一个隔离的 worktree 来做这个功能...
[创建新分支，验证测试基线]
AI: 这是实现计划，请确认：
## 任务 1：数据库迁移
- 添加 2FA 字段到 users 表
- 创建 refresh_tokens 表
## 任务 2：JWT 服务
- 实现 token 生成和验证
- 配置 7 天过期
## 任务 3：登录 API
- POST /auth/login
- POST /auth/refresh
- POST /auth/logout
## 任务 4：Google OAuth
- 配置 OAuth 客户端
- 实现回调处理
## 任务 5：2FA 实现
- TOTP 生成
- QR 码展示
- 验证端点
每个任务都有测试要求。确认后可以开始吗？
用户：确认，开始吧
[AI 触发 subagent-driven-development]
AI: 好的，我开始分派任务给子代理执行。每个任务完成后会进行代码审查。
...
[2 小时后]
AI: 所有任务完成！测试全部通过。
审查总结：
- ✓ 所有功能符合设计
- ✓ 测试覆盖率 92%
- ✓ 无安全漏洞
- ✓ 代码质量良好
接下来你想：
1. 创建 GitHub Pull Request
2. 本地合并到 main 分支
3. 保持分支，稍后处理
4. 丢弃这个 worktree
5.2 示例 2：用 Codex 调试问题
场景：生产环境认证服务失败
# 启动 Codex codex
对话流程：
用户：生产环境的认证服务挂了，用户无法登录
[AI 自动触发 systematic-debugging 技能]
AI: 明白，我们按系统化流程来排查。
## 阶段 1：复现问题
1. 错误信息是什么？
2. 所有用户都受影响还是部分？
3. 什么时候开始的？
4. 最近有部署或配置变更吗？
用户：1. 返回 500 Internal Server Error
2. 所有用户
3. 大约 30 分钟前
4. 没有部署，但 1 小时前重启过服务器
[AI 触发 verification-before-completion]
AI: 好的，让我先检查日志...
[分析日志，定位问题]
AI: 找到根因了：JWT 签名密钥的环境变量在重启后丢失。
修复方案：
1. 临时：手动设置环境变量
2. 永久：修复启动脚本，确保环境变量持久化
我先临时修复，让服务恢复，然后再处理根本问题。可以吗？
用户：可以，先恢复服务
[AI 执行修复，验证]
AI: 服务已恢复。我运行了测试登录，确认可以正常认证。
接下来修复启动脚本，确保重启后环境变量不会丢失...
[完成修复，添加监控]
AI: 修复完成。我还添加了一个健康检查端点，可以监控认证服务状态。
建议：
1. 添加环境变量变更的告警
2. 定期测试认证流程
3. 考虑用密钥管理服务（如 AWS Secrets Manager）
六、技能开发：创建你自己的技能
Superpowers 允许你创建自定义技能，扩展 AI 的能力。
6.1 技能结构
~/.agents/skills/my-skill/
├── SKILL.md # 必需：技能定义
├── references/ # 可选：参考资料
│ └── example.md
└── scripts/ # 可选：辅助脚本
└── run.sh
6.2 SKILL.md 格式
--- name: my-custom-skill description: 当 [条件] 时使用 - [做什么] --- # 技能名称 ## 触发条件 [描述什么时候应该使用这个技能] ## 执行步骤 1. 第一步 2. 第二步 3. ... ## 输出规范 [应该产生什么结果] ## 注意事项 - 安全提示 - 边界情况 - 常见错误
6.3 示例：代码格式化技能
--- name: format-code description: 当代码提交前或审查时发现格式问题 - 自动格式化代码 --- # 代码格式化技能 ## 触发条件 - 用户请求格式化代码 - 代码审查发现格式不一致 - 提交前自动检查 ## 执行步骤 1. 检测项目使用的格式化工具： - 查找 `.prettierrc`、`.eslintrc` 等配置文件 - 检查 `package.json` 中的格式化脚本 2. 安装依赖（如果需要）： ```bash npm install --save-dev prettier eslint
- 运行格式化：
npm run format # 或 npx prettier --write . - 验证格式化结果：
- 运行 linter 检查
- 确认没有引入功能变更
- 提交格式化变更（单独提交）：
git add -A git commit -m "chore: auto-format code"
输出规范
- 格式化后的代码
- 格式化报告（修改了哪些文件）
- 单独的 git 提交
注意事项
- 格式化提交应该与功能提交分开
- 不要在一次提交中混合功能变更和格式化
- 大项目可能需要分批次格式化
--- ## 七、故障排查 ### 7.1 技能没有触发 **可能原因**： - 技能描述不够清晰 - 触发条件不匹配 - 技能未被正确加载 **解决方法**： ```bash # Claude Code: 检查插件状态 /plugin list # Codex: 检查符号链接 ls -la ~/.agents/skills/superpowers # OpenCode: 检查插件加载 opencode run --print-logs "hello" 2>&1 | grep -i superpowers
7.2 技能执行失败
可能原因：
- 缺少依赖（二进制、环境变量）
- 权限问题
- 技能逻辑错误
解决方法：
- 检查技能的前置条件
- 查看 AI 的错误输出
- 手动执行技能中的命令验证
7.3 更新后技能不工作
解决方法：
# Claude Code /plugin update superpowers # Codex cd ~/.codex/superpowers && git pull # OpenCode # 重启 OpenCode，插件会自动更新 # 全部不行：卸载重装
八、最佳实践
8.1 使用建议
- 让流程自然发生：不要强制跳过步骤
- 认真阅读设计：AI 会分块展示，每块都要确认
- 信任 TDD：即使看起来慢，长期来看更快
- 利用子代理：复杂任务分派出去，主代理做协调
- 审查每个任务：不要等到最后才审查
8.2 不适合的场景
Superpowers 不适合：
- 快速原型（直接写代码更快）
- 简单修改（一两行代码的改动）
- 探索性编程（还不知道要做什么）
8.3 性能优化
- 大项目：使用 worktrees 并行开发
- 复杂功能：拆分成多个小计划
- 紧急修复：可以跳过部分流程，但要事后补上测试
九、社区与资源
9.1 官方资源
- GitHub: https://github.com/obra/superpowers
- 博客: https://blog.fsck.com/2025/10/09/superpowers/
- Discord: https://discord.gg/Jd8Vphy9jq
- 问题追踪: https://github.com/obra/superpowers/issues
9.2 相关资源
- AgentSkills 规范: https://agentskills.io
- Microsoft Amplifier: https://github.com/microsoft/amplifier
- Cialdini 影响力研究: https://gail.wharton.upenn.edu/research-and-insights/call-me-a-jerk-persuading-ai/
9.3 贡献技能
Superpowers 欢迎社区贡献技能：
- Fork 仓库
- 创建技能分支
- 遵循
writing-skills技能创建和测试 - 提交 PR
十、总结
Superpowers 是一个革命性的 AI 编程框架，它通过技能系统和标准化流程，让编码代理能够：
✅ 先理解，后实现 – 避免误解和返工
✅ 测试驱动 – 质量有保障
✅ 任务拆解 – 可追踪、可管理
✅ 自动审查 – 问题早发现
✅ 可扩展 – 自定义技能满足特定需求
适用人群：
- 用 AI 进行严肃软件开发的人
- 需要 AI 遵循工程最佳实践的团队
- 希望 AI 更可靠、更可预测的用户
下一步行动：
- 根据你的平台安装 Superpowers
- 尝试一个小型项目，体验完整流程
- 阅读
getting-started技能深入了解 - 考虑贡献你自己的技能到社区
参考资料：
本文基于 Superpowers v5.x 编写，安装方式可能随版本更新而变化。请参考官方文档获取最新信息。