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

1.1 什么是 Superpowers

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

1.2 解决什么问题

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

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

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

1.3 核心特性

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

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（头脑风暴）

这是第一个被调用的技能。当你有一个新想法或需要实现新功能时，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.1 技能地图

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

模型选择策略：

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

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

五步验证法：

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

关键原则：

先证据，后断言

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 前置要求

4.3 验证安装

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

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

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 常用技能调用场景

6.1 自定义技能

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

技能存放位置

编写新技能的 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

session-start Hook 详解

位置 ：hooks/session-start

功能：

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

6.3 子代理提示模板

位于 skills/subagent-driven-development/：

6.4 流程图系统

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

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

渲染命令：

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

6.5 平台工具映射

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

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.1 Superpowers 解决了什么

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

8.2 核心价值

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

 
8.3 适用人群
 

8.4 资源链接

8.5 参与贡献

Superpowers 对贡献有极高的标准：

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

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