superpowers 新手入门指南

created: 2026-05-20
tags: [superpowers, AI-agent, guide, beginner, claude-code]
source: https://github.com/obra/superpowers

版本: v5.1.0（2026年5月发布） | 作者: Jesse Vincent (obra) | 许可: MIT | GitHub Stars: 180K+

什么是 Superpowers？

Superpowers 不是 AI 模型 —— 它是一套软件开发方法学，运行在 AI 编程代理之上（如 Claude Code、Cursor、Codex CLI、Gemini CLI、Copilot CLI）。

它的核心目标：不让 AI 一上来就写代码，而是强制 AI 遵循一套严谨的工程流程。

💡 一句话总结：Superpowers 不是让 AI 更"聪明"，而是让 AI 更"靠谱"。

为什么要用 Superpowers？

核心哲学：三条铁律

这三条是不可协商的（non-negotiable）：

🔴 铁律一：没有测试，就没有生产代码

“如果你写不出一个会失败的测试，说明你根本没定义清楚’完成’的标准。”

🔴 铁律二：没有根因分析，就不修 Bug

“别瞎猜修复方案。先用四阶段系统调试法找到根因。”

🔴 铁律三：没有验证证据，就不算完成

“'看起来好了’不算数。跑一遍测试，把证据摆出来。”

安装指南

Claude Code（推荐，最成熟）

# 方式一：从官方 Claude 市场安装
/plugin install superpowers@claude-plugins-official

# 方式二：从 Superpowers 市场安装
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

Cursor

在 Cursor 的插件面板中执行：

/add-plugin superpowers

Codex CLI

/plugins → 搜索 superpowers → Install Plugin

或直接告诉 Codex：

“Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md”

Gemini CLI

gemini extensions install https://github.com/obra/superpowers

GitHub Copilot CLI

copilot plugin marketplace add obra/superpowers-marketplace
copilot plugin install superpowers@superpowers-marketplace

OpenCode

在 opencode.json 中添加：

{
  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
}

七步核心工作流程

安装完成后，当你给 AI 描述一个任务，它会自动走完以下 7 步：

第一步：头脑风暴（Brainstorming）

做什么：AI 会像苏格拉底一样问你问题，澄清需求。

产出：一份 docs/superpowers/specs/ 下的设计文档。

关键点：

• 此时不写任何代码
• 探索多种方案
• 明确验收标准

示例对话：

你：帮我写一个博客系统

AI（Superpowers 版）：好的，让我先澄清几个问题：
1. 这个博客主要面向什么受众？
2. 需要支持 Markdown 吗？
3. 需不需要评论功能？
4. 是静态站点还是动态服务端渲染？
...

第二步：Git 工作树（Using Git Worktrees）

做什么：在一个新的 Git 分支上创建隔离的工作区。

为什么：保证主分支（main/master）始终干净，互不干扰。

关键变化（v5.1.0）：

• 不再自动创建工作树，会先征求你的同意
• 只清理 .worktrees/ 目录下的工作树
• 优先使用平台内置的工作树工具

第三步：制定计划（Writing Plans）

做什么：把设计拆成2-5 分钟的细粒度任务。

每个任务包含：

• 精确的文件路径
• 完整的代码片段
• 验证步骤

示例计划片段：

任务 1/5：创建博客文章模型
- 文件: src/models/Post.ts
- 代码: [略]
- 验证: npm run test:model

任务 2/5：实现文章列表 API
- 文件: src/api/posts.ts
- 代码: [略]
- 验证: curl 测试端点

第四步：子代理驱动开发（Subagent-Driven Development）

这是 Superpowers 最有特色的步骤。

流程：

1. 主代理为每个任务启动一个全新的子代理（干净的上下文窗口）
2. 子代理完成任务后，主代理进行两阶段审查：
   • 阶段一：检查是否符合设计规范
   • 阶段二：检查代码质量
3. 通过审查后，进入下一个任务

优势：

• 避免上下文窗口污染
• 每个子任务都有"新鲜的大脑"
• 天然支持并行开发

第五步：测试驱动开发（Test-Driven Development）

严格的 RED → GREEN → REFACTOR 循环：

如果你发现自己写不出一个会失败的测试 —— 说明你还不够清楚自己要干什么。

第六步：代码审查（Requesting Code Review）

自动进行的代码审查：

• 对照计划检查每项任务是否完成
• 安全审查（SQL 注入、明文密码等）
• 架构一致性检查
• 错误处理检查
• 严重问题会阻断进度

第七步：分支收尾（Finishing a Development Branch）

验证所有测试通过后，你可以选择：

1. Merge —— 合并到主分支
2. Create PR —— 创建 Pull Request
3. Keep —— 保留工作树稍后继续
4. Discard —— 丢弃所有更改

14 个核心技能详解

Superpowers 的核心是 14 个可组合的技能，分为 4 大类：

🤝 协作流程类（9 个）

🧪 测试类（1 个）

🐛 调试类（2 个）

四阶段调试法：

1. 复现 —— 稳定重现 Bug
2. 隔离 —— 缩小范围到最小复现单元
3. 根因 —— 找到真正的根本原因
4. 修复 —— 写测试 → 修代码 → 验证

🔄 元技能类（2 个）

三种实战场景

场景一：全新项目开发

适用：从头开始的项目

流程：完整的 7 步流程

建议：前期多花时间在头脑风暴和计划阶段，后面的开发会非常顺畅。

场景二：现有项目 + 新功能

适用：在已有代码库上添加功能

流程：同样是完整的 7 步流程

注意：

• AI 会遵循现有代码模式
• 不会主动提出无关的重构
• 计划阶段会参考现有代码结构

场景三：修 Bug

适用：修复已有 Bug

流程：精简为 3 步

1. systematic-debugging —— 找根因
2. test-driven-development —— 写失败测试 → 修代码
3. verification-before-completion —— 验证修复有效

常见问题 FAQ

Q1：我要不要记住所有 14 个技能的名字？

不需要。 你只需要像平时一样描述任务，Superpowers 会自动检测并调用适用的技能。你不必自己手动调用它们。

Q2：它支持中文交互吗？

完全支持。 Superpowers 是方法论框架，语言取决于你用的 AI 工具。Claude Code 等工具都支持中文。

Q3：影响我现有的工作流吗？

正面的影响。 初期可能需要适应（比如习惯先写测试），但长期来看会显著提升代码质量。

Q4：我能不能自定义工作流？

可以。 通过 writing-skills 技能，你可以编写自己的技能。也可以参考社区项目如 [[#Coco（59 个技能）]]。

Q5：必须在 Git 仓库里用吗？

是的。 Git 工作树和分支收尾流程要求项目在 Git 仓库中。

Q6：v5.1.0 移除了哪些老功能？

• 移除了 /brainstorm、/execute-plan、/write-plan 等旧版斜杠命令
• 移除了独立的 code-reviewer 命名代理（已合并进技能内部）

进阶学习资源

官方资源

教程与文章

社区扩展项目

快速上手指南

想立刻上手？按这个清单走：

• 安装 Superpowers（看你用哪个 AI 工具）
• 打开一个 Git 项目
• 随便说一个需求，比如：“帮我添加一个用户登录功能”
• 观察 AI 自动走的 7 步流程
• 体验头脑风暴环节（回答 AI 的问题）
• 体验 TDD 环节（注意 AI 先写测试再写代码）
• 体验代码审查环节
• 完成第一个 Superpowers 驱动的开发任务 🎉

本指南基于 Superpowers v5.1.0 编写。由于项目迭代较快，建议定期查看 [[#官方资源]] 获取最新信息。