一、简介

1.1 什么是 Superpowers

Superpowers 是由前 Anthropic 工程师 Jesse Vincent（GitHub: @obra）创建并维护的开源 Agentic Skills 框架，与 Prime Radiant 团队共同开发。它于 2025 年 10 月 9 日 随 Anthropic 官方插件系统同日发布，短短六个月便成为 2026 年 AI 编码智能体领域最受欢迎的开源项目之一。

Superpowers 的核心理念是："Skills are what give your agents Superpowers"（技能赋予智能体超能力）。它通过结构化的 Markdown 技能文档，教会 AI 代理按照软件工程方法论工作，而不是直接跳到输出。

1.2 核心定位

Superpowers 不是为 Claude Code 添加新功能、改进模型或扩大上下文窗口，而是改变方法论（Methodology）——即工作流程。它强制 Claude 在编写代码前经历五个结构化阶段：

Clarify（澄清） → Design（设计） → Plan（计划） → Code（编码） → Verify（验证）

1.3 关键数据

指标	数值
GitHub Stars	~167K
Forks	~6.7K
技能数量	14+ 核心技能
安装时间	~30 秒
API 调用减少	14%（中等复杂度任务）
成本节省	9%（Opus 4.6 测试）
开源协议	MIT

---

二、安装方法

2.1 官方市场安装（推荐）

自 2026 年 1 月 起，Superpowers 已入驻 Anthropic 官方插件市场，安装极为简便：

/plugin install superpowers@claude-plugins-official

安装时 Claude Code 会询问安装级别：

• User level (Global)：全局生效，推荐选择，所有项目和会话自动可用
• Project level：仅当前项目生效，适合先测试再全局安装

2.2 社区市场安装（备选）

# 步骤 1：注册 Superpowers 市场源
/plugin marketplace add obra/superpowers-marketplace

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

2.3 验证安装

/plugin list

确认输出中包含 superpowers。安装完成后，重启 Claude Code 会话即可自动生效。

2.4 兼容性

Superpowers 不仅支持 Claude Code，还兼容以下平台：

• Cursor
• OpenAI Codex CLI
• OpenCode
• GitHub Copilot CLI
• Gemini CLI

---

三、使用方法

3.1 技能自动触发机制

Superpowers 的技能不是手动调用的命令，而是根据上下文自动激活：

场景	自动激活的技能
讨论新功能需求	brainstorming
设计获批后	using-git-worktrees
开始实现	test-driven-development
任务完成	requesting-code-review
所有任务完成	finishing-a-development-branch

每个技能都包含：激活触发条件、红旗警示（识别错误场景）、流程检查清单、完成前验证标准。

3.2 核心命令

安装后，在 Claude Code 中输入 / 即可看到以 superpowers: 开头的命令：

/superpowers:brainstorm      # 交互式设计细化
/superpowers:write-plan      # 创建实现计划
/superpowers:execute-plan    # 使用子代理执行计划

3.3 五阶段工作流详解

阶段一：Clarify（澄清）

Superpowers 最颠覆性的功能是阻止 Claude 在没想清楚之前写代码。

示例对话：

用户：帮我做个登录功能

Claude：我将使用 brainstorming 技能来探索这个功能。

首先，让我问几个澄清问题：
1. 这个登录功能是要加到哪个项目里？还是一个全新的项目？
2. 你希望用什么技术栈？
3. 前端框架用哪个？
4. 登录认证方式用哪种？（账密 / OAuth / 两者都要）
5. 数据库用哪个？
6. 是否需要密码重置功能？
7. 是否需要"记住我"功能？
...

为什么重要：AI 最贵的 Bug 不是语法错误，而是方向错误。Brainstorming 阶段消耗约 3000-5000 tokens，但能避免方向性返工。

阶段二：Design（设计）

需求确认后，Claude 生成结构化设计文档：

# User Authentication System Design

## 功能需求
1. 用户注册（邮箱 + 密码）
2. 用户登录
3. 密码重置（邮件）
4. 记住我（JWT + Refresh Token）

## 技术选型
- 后端: Node.js + Express
- 数据库: SQLite
- 认证: JWT
- 加密: bcrypt

## API 设计
- POST /api/auth/register
- POST /api/auth/login
- POST /api/auth/refresh
- POST /api/auth/reset-password

阶段三：Plan（计划）

使用 writing-plans 技能将大任务拆分为 2-5 分钟可完成的小任务：

# Implementation Plan

## Task 1: 设计数据库 schema（预估 5 分钟）
- 创建 todos 表
- 定义字段: id, title, completed, createdAt

## Task 2: 创建 Express 路由（预估 10 分钟）
- POST /todos - 创建任务
- GET /todos - 列出任务
- GET /todos/:id - 获取单个任务
- PUT /todos/:id - 更新
- DELETE /todos/:id - 删除

## Task 3: 添加输入验证（预估 10 分钟）
- title 不能为空
- completed 必须为布尔值

## Task 4: 编写测试（预估 15 分钟）
- 为每个端点编写测试
- 覆盖边界情况

## Task 5: 启动服务器并验证（预估 5 分钟）
- 运行测试
- 手动测试 API

验收标准：
- 所有测试通过
- 每个端点 curl 测试通过

阶段四：Code（编码）

使用 executing-plans 技能分批执行计划，每完成一个任务暂停确认：

Claude: ✅ Task 1 数据库 schema 完成。继续？
用户: 继续
Claude: ✅ Task 2 Express 路由完成。继续？
...

阶段五：Verify（验证）

任务完成后自动触发代码审查，检查：

• 代码质量
• 安全性（SQL 注入、XSS 等）
• 测试覆盖率
• 文档完整性

---

四、核心技能详解

4.1 技能分类总览

类别	主要技能
测试与调试	test-driven-development, systematic-debugging, verification-before-completion
设计与规划	brainstorming, writing-plans, executing-plans
实现与集成	subagent-driven-development, using-git-worktrees, finishing-a-development-branch, dispatching-parallel-agents
代码审查	requesting-code-review, receiving-code-review
元技能	writing-skills, using-superpowers

4.2 重点技能解析

4.2.1 brainstorming（头脑风暴）

触发方式：讨论新功能时自动激活

功能：使用苏格拉底式提问澄清需求，避免 Claude 直接编码

示例：

用户：帮我建一个博客系统

Claude：
- 这个博客面向谁？技术读者还是普通读者？
- 是否需要支持 Markdown 编辑？
- 是否需要评论功能？
- 是否需要搜索功能？
- 单用户还是多作者？
- ...

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

触发方式：提及 "TDD"、"test-driven development"、"write tests first"

功能：强制遵循 Red-Green-Refactor 循环

传统方式 vs TDD 方式：

传统方式	TDD 方式
直接写代码	🔴 RED: 先写失败的测试
快速手动测试	🟢 GREEN: 写最小代码通过测试
发现 Bug 后打补丁	🔵 REFACTOR: 重构同时保持测试通过
测试？下次再说	重复循环

示例用法：

用户：使用 TDD 实现用户认证模块

Claude 将：
1. 先写测试（用户名/密码验证、Token 生成等）
2. 运行测试并确认全部失败（RED）
3. 编写最小实现代码
4. 运行测试并确认通过（GREEN）
5. 重构代码并提取共享逻辑
6. 再次运行测试确认通过（REFACTOR）

注意：如果不提及 "TDD"，Claude 可能不会写测试。该技能的作用是强制执行流程纪律，确保测试不被"遗忘"。

4.2.3 systematic-debugging（系统化调试）

功能：指导四阶段调查，三次失败尝试后进行架构层升级

流程：

1. 复现问题
2. 定位根因
3. 制定修复方案
4. 验证修复

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

功能：最强大的模式，用多个子代理替代单个长会话

工作流程：

1. 主代理创建计划
2. 为每个任务生成新的子代理执行
3. 审查代理（code-reviewer）检查工作
4. 主代理继续或请求修复

优势：每个子代理以干净的上下文开始，专注于单一任务，避免长会话中的累积混乱。

4.2.5 using-git-worktrees（Git Worktree 集成）

功能：使用 git worktrees 进行隔离开发

# 后台操作
git worktree add ../project-feature feature-branch
cd ../project-feature
# Claude 在此工作，main 分支保持干净

优势：

• 可在不同功能上运行多个 Claude 实例
• 实验期间保持 main 分支稳定
• 出错时易于清理

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

功能：同时调度多个子代理并行处理独立任务

4.2.7 requesting-code-review / receiving-code-review

功能：自动触发代码审查流程，检查代码质量、安全性和测试覆盖率

---

五、实战案例：构建用户认证系统

5.1 场景设定

假设你需要为一个 Express 应用添加用户认证系统，使用 Superpowers 完成全流程开发。

5.2 Step 1: 需求澄清（Brainstorming）

用户输入：

I need a user authentication system

Claude 响应（自动激活 brainstorming 技能）：

我将使用 brainstorming 技能来澄清这个需求。

澄清问题：
1. 这是 Web 应用还是移动应用？
2. 需要哪些登录方式？（邮箱/密码、OAuth、SSO）
3. 是否需要密码重置功能？
4. 是否需要"记住我"功能？
5. 是否需要多因素认证（MFA）？
6. 会话管理策略是什么？（JWT、Session、Refresh Token）
7. 密码复杂度要求？
8. 是否需要账户锁定机制？

用户回答后，Claude 生成确认的设计摘要，用户确认后进入下一阶段。

5.3 Step 2: 生成设计文档

# User Authentication System Design

## 功能需求
1. 用户注册（邮箱 + 密码）
2. 用户登录
3. 密码重置（邮件）
4. 记住我（JWT + Refresh Token）

## 技术选型
- 后端: Node.js + Express
- 数据库: SQLite
- 认证: JWT (access token + refresh token)
- 加密: bcrypt (cost factor: 12)
- 邮件: nodemailer

## API 设计
| 方法 | 路径 | 描述 |
|------|------|------|
| POST | /api/auth/register | 用户注册 |
| POST | /api/auth/login | 用户登录 |
| POST | /api/auth/refresh | 刷新 Token |
| POST | /api/auth/reset-password | 请求密码重置 |
| POST | /api/auth/reset-password/:token | 确认密码重置 |

## 数据库 Schema
```sql
CREATE TABLE users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  email TEXT UNIQUE NOT NULL,
  password_hash TEXT NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE refresh_tokens (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  user_id INTEGER REFERENCES users(id),
  token TEXT UNIQUE NOT NULL,
  expires_at DATETIME NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

### 5.4 Step 3: 编写实现计划

**用户输入**：

Use writing-plans to create the implementation plan

**Claude 生成计划**：

```markdown
# Implementation Plan: User Authentication System

## Task 1: 初始化项目和依赖（预估 5 分钟）
- 初始化 npm 项目
- 安装 express, bcryptjs, jsonwebtoken, sqlite3, nodemailer
- 创建项目目录结构

## Task 2: 创建数据库连接和 Schema（预估 5 分钟）
- 创建 db.js 连接 SQLite
- 执行 schema migration
- 添加 seed data（可选）

## Task 3: 编写用户模型和验证逻辑（预估 10 分钟）
- 创建 User 模型
- 实现密码哈希和验证
- 实现邮箱格式验证

## Task 4: TDD - 编写认证测试（预估 15 分钟）
- 注册端点测试（成功/失败场景）
- 登录端点测试（成功/失败场景）
- Token 刷新测试
- 密码重置测试

## Task 5: 实现注册端点（预估 10 分钟）
- POST /api/auth/register
- 输入验证
- 密码哈希
- 创建用户记录

## Task 6: 实现登录端点（预估 10 分钟）
- POST /api/auth/login
- 验证凭据
- 生成 JWT 和 Refresh Token
- 返回 Token 对

## Task 7: 实现 Token 刷新（预估 10 分钟）
- POST /api/auth/refresh
- 验证 Refresh Token
- 生成新的 Token 对
- 轮换 Refresh Token

## Task 8: 实现密码重置（预估 15 分钟）
- 请求重置端点
- 生成重置 Token
- 发送重置邮件
- 确认重置端点

## Task 9: 添加中间件和错误处理（预估 10 分钟）
- 认证中间件
- 错误处理中间件
- 请求日志

## Task 10: 集成测试和验证（预估 10 分钟）
- 运行所有测试
- 手动 API 测试（curl）
- 安全审查

验收标准：
- 所有测试通过
- 每个端点 curl 测试通过
- 无安全漏洞（SQL 注入、XSS）
- 代码覆盖率 > 80%

5.5 Step 4: 执行开发（TDD + Subagent）

用户输入：

Execute the plan above with TDD

Claude 执行流程：

🔄 激活 test-driven-development 技能

📋 Task 1: 初始化项目
  ✅ 创建 package.json
  ✅ 安装依赖
  ✅ 创建目录结构
  ⏸️ 暂停确认...

📋 Task 2: 数据库 Schema
  ✅ 创建 db.js
  ✅ 执行 migration
  ⏸️ 暂停确认...

📋 Task 3: TDD - 注册测试（RED）
  ✅ 编写注册成功测试
  ✅ 编写注册失败测试（重复邮箱、无效格式）
  🔴 运行测试 - 全部失败（预期）
  ⏸️ 暂停确认...

📋 Task 4: 实现注册端点（GREEN）
  ✅ 实现 POST /api/auth/register
  ✅ 添加输入验证
  ✅ 密码哈希处理
  🟢 运行测试 - 全部通过
  ⏸️ 暂停确认...

📋 Task 5: TDD - 登录测试（RED）
  ✅ 编写登录成功测试
  ✅ 编写登录失败测试
  🔴 运行测试 - 全部失败（预期）
  ⏸️ 暂停确认...

📋 Task 6: 实现登录端点（GREEN）
  ✅ 实现 POST /api/auth/login
  ✅ JWT Token 生成
  ✅ Refresh Token 管理
  🟢 运行测试 - 全部通过
  ⏸️ 暂停确认...

...（继续执行剩余任务）

5.6 Step 5: 代码审查

所有任务完成后，自动激活 requesting-code-review 技能：

## Code Review Report

### 代码质量 ✅
- 函数职责单一
- 命名清晰
- 错误处理完善

### 安全性 ✅
- 密码使用 bcrypt 哈希 ✅
- SQL 参数化查询 ✅
- JWT Secret 环境变量管理 ✅
- Refresh Token 轮换 ✅

### 测试覆盖率 ✅
- 单元测试: 24/24 通过
- 集成测试: 8/8 通过
- 覆盖率: 87%

### 建议改进
1. 添加 rate limiting 防止暴力破解
2. 考虑添加账户锁定机制
3. 日志中避免记录敏感信息

### 结论
代码质量良好，可以合并。

5.7 使用 Git Worktree 隔离开发

在整个过程中，Superpowers 自动使用 git worktrees：

# 主代理创建 feature 分支
git worktree add ../auth-system-feature auth-system

# 子代理在隔离目录工作
cd ../auth-system-feature
# 所有开发在此进行，main 分支不受影响

# 完成后清理
git worktree remove ../auth-system-feature

---

六、使用建议与注意事项

6.1 适用场景

Superpowers 最适合以下场景：

• ✅ 全新项目（Greenfield）：从零构建完整系统
• ✅ 复杂应用：需要多组件协调
• ✅ 重视测试和维护性：TDD 和质量优先
• ✅ 长时间自主工作：可让 AI 自主运行较长时间

6.2 不适用场景

以下情况不建议使用 Superpowers：

• ❌ 快速原型：速度比质量更重要
• ❌ 小型独立修改：现有代码库的小改动
• ❌ 即时交互协作：需要与 AI 紧密互动
• ❌ 简单任务：不值得完整规范的 overhead

注意：简单任务使用 Superpowers 反而会增加约 8% 的 token 开销。

6.3 最佳实践

1. 全局安装：选择 User level 安装，避免每个项目重复配置
2. 善用暂停：executing-plans 的暂停机制让你在每个阶段验证方向
3. 自定义技能：使用 writing-skills 元技能创建团队专属技能
4. 结合 Routine：将技能驱动的工作流提升为 Claude Code Routine，实现自动化触发

6.4 自定义技能

Superpowers 支持自定义技能。创建 SKILL.md 文件：

---
name: team-report
description: Creates standardized weekly team updates. Use when the user wants a team status report or weekly update.
---

# Weekly Team Update Skill

## Instructions
When creating a weekly team update, follow this structure:

1. **Wins This Week**: 3-5 bullet points of accomplishments
2. **Challenges**: 2-3 current blockers or concerns
3. **Next Week's Focus**: 3 key priorities
4. **Requests**: What the team needs from others

## Tone
- Professional but conversational
- Specific with metrics where possible
- Solution-oriented on challenges

---

七、总结

Superpowers 代表了 AI 辅助开发的重大进化——从简单的代码生成转向完整的项目生命周期自主管理。通过以下核心机制实现：

机制	价值
结构化流程	五阶段纪律避免方向性错误
TDD 强制执行	确保测试不被遗忘
子代理架构	干净上下文，避免累积混乱
Git Worktree	隔离开发，保护主分支
自动代码审查	持续质量保障
可组合技能	按需激活，灵活适配

正如 Jesse Vincent 所说："Skills are what give your agents Superpowers"。这套框架让 Claude Code 从"写代码工具"升级为"结构化工程伙伴"。

---

参考资源

• GitHub 仓库: github.com/obra/superpowers
• 官方市场: Superpowers @ Anthropic Marketplace
• 实验技能: github.com/obra/superpowers-lab
• 社区技能: github.com/obra/superpowers-skills
• 作者博客: fsck.com (Jesse Vincent)