Superpowers —— 让 AI 编程代理具备工程化开发能力

Superpowers ------ 让 AI 编程代理具备工程化开发能力

目录

1. 项目简介
2. 核心原理
3. 核心技能详解
4. 安装部署
5. 核心命令与使用
6. 进阶扩展
7. 最佳实践
8. 总结

---

1. 项目简介

1.1 什么是 Superpowers

Superpowers 是由 Jesse Vincent 开发的一个完整的 AI 编程代理工作流系统，旨在为 AI 代理（如 Claude Code、Cursor、Codex 等）提供结构化、工程化的软件开发方法论。

属性	信息
仓库地址	https://github.com/obra/superpowers
当前版本	5.0.7
许可证	MIT
支持平台	Claude Code, Cursor, Codex, OpenCode, GitHub Copilot CLI, Gemini CLI
依赖情况	核心模块零第三方依赖

1.2 解决什么问题

在日常使用 AI 编程代理时，常见的问题包括：

• 缺乏系统性 --- AI 代理往往想到什么写什么，缺乏设计先行的工作习惯
• 跳过测试 --- 不写测试或后补测试，导致代码质量不可控
• 调试不规范 --- 遇到问题就改，改了再犯，循环往复
• 工作流碎片化 --- 没有统一的开发流程，不同人使用 AI 效果参差不齐
• 平台绑定 --- 技能和方法论无法跨 AI 平台迁移

Superpowers 通过可组合的技能系统（Skills）自动强制执行这些工程实践，确保 AI 代理在每次会话中都遵循最佳实践。

1.3 核心特性

✓ 开箱即用的 TDD 开发流程
✓ 强制性的设计先行方法论
✓ 系统化调试流程
✓ 多代理协作支持
✓ 零依赖，环保轻量
✓ 跨平台支持（6大主流AI编程平台）
✓ 技能即文档，所见即所用

---

2. 核心原理

2.1 技能系统（Skills）

在 Superpowers 中，**技能（Skill）**是核心概念。它是一种可重用的技术参考指南，帮助 AI 代理找到并应用有效的开发方法。

技能的结构

skills/
  skill-name/
    SKILL.md              # 主参考文档（必需）
    supporting-file.*     # 支持文件（如有需要）

技能的元数据格式

每个技能必须包含 YAML frontmatter：

---
name: skill-name-with-hyphens
description: Use when [触发条件] - [技能作用]
---

⚠️ 重要提醒 ：description 字段只能描述触发条件，而非总结工作流程。测试表明，描述工作流程会导致 AI 直接遵循描述而非阅读完整内容。

2.2 技能触发机制

Superpowers 遵循强制优先原则：

如果你认为某个技能有 1% 的可能性适用于你正在做的事情，你必须调用该技能。

核心引导技能 using-superpowers 明确规定了优先级：

用户指令 > Superpowers 技能 > 默认系统提示

2.3 技能一览

在了解工作流链之前，我们先认识一下所有核心技能。以下是 Superpowers 提供的技能及其作用：

技能分类速查

技能名称	中文名称	一句话说明
brainstorming	头脑风暴	创意工作前，通过提问和讨论确定最佳方案
using-git-worktrees	Git Worktree 隔离开发	创建独立的 Git worktree，避免污染主分支
writing-plans	撰写计划	将设计方案拆解为 2-5 分钟可完成的小任务
subagent-driven-development	子代理驱动开发	把任务分配给多个 AI 子代理并行执行
executing-plans	执行计划	在当前会话中顺序执行计划（无子代理）
test-driven-development	测试驱动开发	先写失败测试，再写代码使其通过（RED-GREEN-REFACTOR）
systematic-debugging	系统化调试	四阶段调试：根因调查→模式分析→假设验证→修复实施
verification-before-completion	完成前验证	声称"完成了"之前必须提供实际证据
requesting-code-review	请求代码审查	调用代码审查代理检查实现质量
receiving-code-review	响应代码审查	如何合理地接受或反驳审查意见
finishing-a-development-branch	完成开发分支	合并/PR/保留/丢弃分支的决策流程
dispatching-parallel-agents	并行代理调度	当多个问题相互独立时，并行派遣多个代理
writing-skills	编写技能	如何创建新的技能（遵循 TDD 方法）
using-superpowers	使用 Superpowers	引导技能，强制检查其他技能的适用性

每个技能的详细介绍

brainstorming（头脑风暴）

这是第一个被调用的技能。当你有一个新想法或需要实现新功能时，AI 不会直接开始写代码，而是先通过一系列问题帮助你理清思路：

• 这个功能解决什么问题？
• 有哪些可行的方案？
• 各方案的优缺点是什么？
• 最终选择哪个方案？

最终会把设计文档写入 docs/superpowers/specs/ 目录，等待你确认后才进入下一阶段。

---

using-git-worktrees（Git Worktree 隔离开发）

这个技能利用 Git 的 worktree 功能创建一个独立的开发目录。好处是：

• 你可以在多个分支之间切换而不需要 stash
• 实验性开发不会污染主分支
• 每个功能都有独立的干净工作区

---

writing-plans（撰写计划）

拿到设计方案后，这个技能把大任务拆解成小步骤。每个步骤：

• 耗时 2-5 分钟
• 有明确的文件路径
• 包含完整的代码（不是伪代码）
• 有验证步骤

这种"原子化"的任务让进度可追踪，也让并行执行成为可能。

---

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

这是 Superpowers 的核心纪律之一。流程是：

RED    → 写一个肯定会失败的测试
GREEN  → 写最少量代码让测试通过
REFACTOR → 重构优化

铁律：没有失败测试就不写生产代码。如果之前写了代码，要删除重写。

---

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

把计划中的每个任务分配给一个独立的 AI 子代理去执行。每个任务会经过两轮审查：

1. 规范审查 --- 子代理的实现是否符合计划？
2. 质量审查 --- 代码质量是否达标？

不通过就打回重做，通过才标记完成。

---

systematic-debugging（系统化调试）

遇到 Bug 时，不要急于修改。这个技能要求：

1. 调查根因 --- 阅读错误，复现问题，检查最近变更
2. 分析模式 --- 找类似工作的代码作参考
3. 假设验证 --- 形成单一假设，最小化测试
4. 实施修复 --- 创建失败测试，修复根因，验证

如果尝试 3 次修复仍失败，说明架构可能有问题。

---

verification-before-completion（完成前验证）

当 AI 声称"完成了"或"测试通过了"，这个技能要求必须提供实际证据：

1. 执行什么命令证明？
2. 执行完整命令
3. 检查输出和退出码
4. 证据是否充分？
5. 才能做出声明

防止 AI "觉得"完成了但实际没有。

---

requesting-code-review & receiving-code-review（请求/响应代码审查）

一对配合使用的技能：

• requesting 调用专门的代码审查代理
• receiving 指导如何合理地回应审查意见

回应审查时：

• 先理解而非反应
• 技术上验证建议
• 有理由的反对要据理力争
• 不要无脑接受恭维

---

finishing-a-development-branch（完成开发分支）

功能开发完成后，这个技能指导：

1. 验证测试全部通过
2. 选择执行策略：本地合并 / 创建 PR / 保留分支 / 丢弃
3. 执行清理

---

writing-skills（编写技能）

这是元技能，教你如何创建新技能。遵循同样的 TDD 方法：

1. RED --- 不使用技能运行场景，记录 AI 的"合理化借口"
2. GREEN --- 编写技能堵住这些借口
3. REFACTOR --- 继续找新借口，添加对策

---

using-superpowers（使用 Superpowers）

这是引导技能，会在每次会话开始时自动激活。它的作用是：

• 强制 AI 在任何动作前检查是否有适用技能
• 确保纪律不被绕过

2.4 工作流链

了解了这些技能后，我们来看它们是如何串联工作的：

brainstorming → using-git-worktrees → writing-plans →
  subagent-driven-development → finishing-a-development-branch

brainstorming → verification-before-completion
subagent-driven-development → requesting-code-review

简单来说，一个完整的功能开发流程是：

1. brainstorming（设计）
   ↓
2. using-git-worktrees（创建隔离环境）
   ↓
3. writing-plans（制定计划）
   ↓
4. subagent-driven-development（执行计划 + 两轮审查）
   ↓
5. requesting-code-review（代码审查）
   ↓
6. finishing-a-development-branch（完成分支）

此外，调试流程独立于主流程：

遇到 Bug → systematic-debugging（调试）
           ↓
verification-before-completion（验证修复）

2.5 纪律执行机制

Superpowers 不仅仅是文档，更是一套强制执行的纪律系统。例如：

• test-driven-development 明确规定：没有失败的测试，就不能写生产代码
• systematic-debugging 规定：修复前必须先调查根本原因
• verification-before-completion 要求：声明状态前必须提供实际证据

---

3. 核心技能详解

3.1 技能地图

类别	技能名称	用途
设计	brainstorming	创意工作前的设计阶段
规划	writing-plans	创建可执行的实施计划
执行	subagent-driven-development	多代理并行执行计划
执行	executing-plans	同会话顺序执行计划
测试	test-driven-development	TDD 测试驱动开发
调试	systematic-debugging	系统化调试流程
验证	verification-before-completion	完成前的证据验证
协作	requesting-code-review	请求代码审查
协作	receiving-code-review	响应代码审查反馈
版本	using-git-worktrees	Git worktree 隔离开发
收尾	finishing-a-development-branch	完成开发分支
扩展	writing-skills	如何编写新技能
引导	using-superpowers	强制技能使用检查

3.2 brainstorming ------ 设计先行

触发条件：任何创意工作之前

核心流程：

1. 探索项目上下文
2. 提供可视化伴侣（如需要）
3. 逐一提出澄清问题
4. 提出 2-3 个方案并说明权衡
5. 分段展示设计，获得确认
6. 编写设计文档到 docs/superpowers/specs/
7. 自检规范
8. 用户审阅
9. 调用 writing-plans 技能

关键规则 ：在用户批准设计之前，禁止调用任何实现技能。

3.3 test-driven-development ------ TDD 强制执行

触发条件：编写任何生产代码之前

核心流程（RED-GREEN-REFACTOR）：

1. RED: 编写一个会失败的测试
2. RUN: 运行测试，确认它失败
3. GREEN: 编写最少的代码使其通过
4. RUN: 运行测试，确认它通过
5. REFACTOR: 重构优化
6. COMMIT: 提交

铁律：

没有先写失败的测试，就不能写任何生产代码。

删除测试之前写的代码，重新开始。

3.4 systematic-debugging ------ 系统化调试

触发条件：遇到 Bug 需要修复时

四阶段流程：

┌─────────────────────────────────────────────────────────┐
│  Phase 1: Root Cause Investigation                      │
│  - 阅读错误信息                                          │
│  - 稳定复现问题                                          │
│  - 检查最近变更                                          │
│  - 收集多组件系统证据                                    │
├─────────────────────────────────────────────────────────┤
│  Phase 2: Pattern Analysis                              │
│  - 寻找工作的参考示例                                    │
│  - 对比参考资料                                          │
├─────────────────────────────────────────────────────────┤
│  Phase 3: Hypothesis and Testing                         │
│  - 形成单一假设                                          │
│  - 最小化测试                                            │
├─────────────────────────────────────────────────────────┤
│  Phase 4: Implementation                                │
│  - 创建失败测试                                          │
│  - 修复根本原因                                          │
│  - 验证修复                                              │
└─────────────────────────────────────────────────────────┘

关键规则：

在进行任何修复之前，必须先调查根本原因。

如果尝试 3+ 次修复仍失败：质疑架构设计。

3.5 subagent-driven-development ------ 多代理执行

触发条件：需要执行实施计划时

执行模型：

Per Task:
  ┌──────────────────────────────────────┐
  │  Dispatch Implementer Subagent       │
  │  (可能询问问题)                       │
  └──────────────────────────────────────┘
                    ↓
  ┌──────────────────────────────────────┐
  │  Dispatch Spec Reviewer Subagent    │
  │  验证是否符合计划规范                  │
  │       ↓ 不符合                        │
  │  Implementer 修复 → 重新审查          │
  └──────────────────────────────────────┘
                    ↓ 符合
  ┌──────────────────────────────────────┐
  │  Dispatch Code Quality Reviewer      │
  │  验证代码质量                         │
  │       ↓ 不通过                        │
  │  Implementer 修复 → 重新审查          │
  └──────────────────────────────────────┘
                    ↓ 通过
              Task Complete

模型选择策略：

任务类型	推荐模型
机械性任务（1-2 文件，清晰规范）	廉价模型
集成/判断任务	标准模型
架构/设计/审查	最强模型

3.6 verification-before-completion ------ 证据优先

触发条件：在声明任何状态之前

五步验证法：

BEFORE claiming any status:
1. IDENTIFY: 什么命令能证明这个说法？
2. RUN: 执行完整命令（全新、完整）
3. READ: 阅读完整输出，检查退出码
4. VERIFY: 输出是否确认了说法？
5. ONLY THEN: 做出声明

关键原则：

先证据，后断言

---

4. 安装部署

4.1 各平台安装方式

Claude Code

/plugin install superpowers@claude-plugins-official

或通过自定义市场：

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

Cursor

/add-plugin superpowers

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

Codex

让 Codex 执行：

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

手动安装：

git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
mkdir -p ~/.agents/skills
ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers

Windows 用户 ：使用 cmd /c mklink /J 代替 symlink。

OpenCode

在 opencode.json 中添加：

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

然后重启 OpenCode。

GitHub Copilot CLI

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

Gemini CLI

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

4.2 前置要求

要求	说明
Git	所有平台必需
对应平台的 CLI	Claude Code / Cursor / Codex 等
多代理支持	使用 subagent 功能时需要

4.3 验证安装

安装完成后，启动新会话，Superpowers 会通过 session-start hook 自动注入引导技能。你应该能看到类似提示：

Superpowers 技能已激活。在执行任何操作前，系统会检查是否有适用的技能。

---

5. 核心命令与使用

5.1 基本使用方式

Superpowers 的技能通过自然语言触发，不需要显式命令调用。AI 代理会在执行任何操作前自动检查是否有适用的技能。

查看可用技能

# 查看 skills 目录结构
ls -la ~/.claude/skills/superpowers/skills/

手动触发技能

在 Claude Code 中，可以使用 /skill 命令：

/skill test-driven-development

5.2 典型工作流示例

场景：实现一个新功能

Step 1: 头脑风暴设计

用户：我想给博客添加标签分类功能
AI：让我先进行设计阶段...
[调用 brainstorming 技能]

Step 2: 创建实施计划

AI：设计已批准。现在创建实施计划...
[调用 writing-plans 技能]

Step 3: 执行计划

AI：开始执行计划...
[调用 subagent-driven-development 技能]
- 任务 1: 添加标签数据模型
- 任务 2: 实现标签 API
- 任务 3: 添加标签管理界面
[每个任务执行 RED-GREEN-REFACTOR]

Step 4: 代码审查

AI：任务完成。请求代码审查...
[调用 requesting-code-review 技能]

Step 5: 合并分支

AI：审查通过。准备完成开发...
[调用 finishing-a-development-branch 技能]

5.3 调试工作流

场景：线上出现 Bug

用户：用户无法登录了
AI：[调用 systematic-debugging 技能]
1. 收集错误日志
2. 复现问题
3. 追溯根本原因
4. 创建失败测试
5. 修复 Bug
6. 验证修复
[调用 verification-before-completion 验证]

5.4 常用技能调用场景

场景	调用的技能
开始新功能开发	brainstorming → writing-plans
实施计划	subagent-driven-development
编写代码	test-driven-development
遇到 Bug	systematic-debugging
声称完成时	verification-before-completion
计划完成	requesting-code-review
收到审查反馈	receiving-code-review
分支完成	finishing-a-development-branch

---

6. 进阶扩展

6.1 自定义技能

用户可以创建自己的技能库。

技能存放位置

平台	个人技能目录
Claude Code	~/.claude/skills/my-skill/SKILL.md
Codex	~/.agents/skills/my-skill/SKILL.md
OpenCode	~/.config/opencode/skills/my-skill/SKILL.md
项目特定	.opencode/skills/ 在项目目录中

编写新技能的 TDD 方法

NO SKILL WITHOUT A FAILING TEST FIRST

RED 阶段：不使用技能运行压力场景，记录 AI 的合理化借口

GREEN 阶段：编写针对具体失败的技能

REFACTOR 阶段：寻找新的合理化借口，添加显式对策

技能模板

---
name: my-custom-skill
description: Use when [特定触发条件] - [技能作用]
---

# My Custom Skill

## Overview
核心原则，1-2 句话。

## When to Use
[小规模决策流程图（如果需要）]
症状和使用场景的子弹列表

## Core Pattern
Before/After 对比，内联代码

## Quick Reference
扫描用的表格或子弹

## Implementation
简单的内联，复杂的链接到文件

## Common Mistakes
什么出错 + 修复方法

## Real-World Impact (optional)
具体效果

6.2 Hooks 系统

Superpowers 使用 hooks 在关键时刻自动注入技能。

可用 Hooks

Hook 类型	触发时机	作用
SessionStart	会话启动/清除/压缩	注入 using-superpowers 引导技能

session-start Hook 详解

位置 ：hooks/session-start

功能：

1. 检查旧版 skills 目录，提示迁移
2. 读取 using-superpowers 技能内容
3. 以正确格式注入到当前平台

6.3 子代理提示模板

位于 skills/subagent-driven-development/：

模板文件	用途
implementer-prompt.md	实现子代理的提示模板
spec-reviewer-prompt.md	规范审查子代理的提示模板
code-quality-reviewer-prompt.md	代码质量审查子代理的提示模板

6.4 流程图系统

Superpowers 使用 Graphviz DOT 语言绘制流程图。

渲染工具 ：skills/writing-skills/render-graphs.js

渲染命令：

node skills/writing-skills/render-graphs.js

6.5 平台工具映射

技能使用 Claude Code 的工具名称。对于非 CC 平台，系统提供自动映射：

Claude Code 工具	映射目标
TodoWrite	OpenCode: todowrite
Task（多代理）	OpenCode: @mention 系统
Skill 工具	各平台原生 skill 工具

---

7. 最佳实践

7.1 何时创建新技能

应该创建：

• 技术不是直观显而易见的
• 你会在多个项目中引用
• 模式适用范围广
• 其他人也能受益

不应该创建：

• 一次性解决方案
• 标准实践（其他地方有更好文档）
• 项目特定约定（放 CLAUDE.md）
• 机械约束（能用正则强制执行的，自动化它）

7.2 技能命名规范

• 只使用字母、数字、连字符
• 动词优先，主动语态：creating-skills 而非 skill-creation
• 动名词适合流程：flattening-with-flags

7.3 技能描述最佳实践

# ❌ 错误 - 总结了工作流程
description: Use when executing plans - dispatches subagent per task with code review

# ✅ 正确 - 只描述触发条件
description: Use when executing implementation plans with independent tasks

7.4 技能压力测试

创建技能后，需要进行压力测试，模拟以下场景：

压力类型	场景示例
时间压力	截止日期、紧急情况
沉没成本	已投入数小时的工作
权威压力	高级工程师说跳过它
疲劳	工作到一天结束时
社交	不想看起来死板

示例压力场景：

你花了 4 小时实现。代码可以工作。现在是下午 6 点，
晚饭 6:30。代码审查明天上午 9 点。刚刚意识到忘了 TDD。

选项：
A) 删除代码，明天用 TDD 重新开始
B) 现在提交，明天写测试
C) 现在写测试（30 分钟），然后提交

选择 A、B 或 C。

7.5 纪律遵守建议

1. 不要绕过技能 --- 即使你觉得知道更好，也要先调用技能
2. 证据优先 --- 任何声明前先提供实际证据
3. 设计第一 --- 实现前总要先规划
4. 测试先行 --- 没有失败测试就不写生产代码
5. 根因优先 --- 修复前先理解问题

---

8. 总结

8.1 Superpowers 解决了什么

Superpowers 为 AI 编程代理带来了工程化开发的纪律性 。它不是简单地把开发规范写成文档，而是通过技能系统强制执行这些规范，确保 AI 代理在每次交互中都遵循最佳实践。

8.2 核心价值

✓ 标准化 --- 无论谁使用 AI，都能获得一致的工程质量
✓ 可追溯 --- 每个决策都有据可查
✓ 可验证 --- 完成前必须提供证据
✓ 跨平台 --- 一套技能库支持 6 大主流 AI 编程平台
✓ 零依赖 --- 轻量环保，无需额外安装

8.3 适用人群

人群	如何受益
开发团队	统一 AI 使用规范，提升代码质量
个人开发者	借助 AI 实现工程化开发习惯
技术管理者	建立可预测的 AI 开发流程
AI 研究者	参考技能系统设计

8.4 资源链接

资源	链接
GitHub 仓库	https://github.com/obra/superpowers
技能市场	obra/superpowers-marketplace
官方文档	仓库内的 skills/ 目录

8.5 参与贡献

Superpowers 对贡献有极高的标准：

• 94% 的 PR 会被拒绝
• 核心模块不接受第三方依赖
• 技能需要通过子代理压力测试
• PR 需要真实问题陈述，不接受理论修复

---

本文档基于 Superpowers v5.0.7编写，如有更新请以官方仓库为准。