Superpowers是一个为AI编程代理（如Claude Code、Codex、OpenCode）构建的完整软件开发工作流系统，它通过一套可组合的"技能"（Skills）和初始指令，让AI代理在编写代码时自动遵循软件工程最佳实践，将AI从简单的代码生成器转变为遵循严格工程规范的自动化开发者。

一、项目核心概述

项目背景：

• 开发者：Jesse Vincent（GitHub: obra）
• 开源协议：MIT License
• GitHub数据：31.5k+ Stars，2.4k+ Forks

核心定位：
Superpowers不是传统意义上的工具库，而是一个"AI编程代理的操作系统"，它通过强制性的工作流程确保AI代理像资深工程师一样工作，而不是像"没有经验的初级工程师"那样随意行事。

二、核心设计哲学

Superpowers建立在四个核心原则之上：

1. 测试驱动开发（TDD）

   • 永远先写测试，没有看到测试失败就不能确定测试是否真正测试了正确的行为
   • 严格执行RED-GREEN-REFACTOR循环

2. 系统化而非临时化

   • 用流程替代猜测，每个技能都有明确的决策流程图
   • 流程图作为"可执行规范"，AI必须遵循

3. 复杂度削减

   • 以简洁为首要目标，反复强调YAGNI（You Aren’t Gonna Need It）原则
   • 积极删除不必要的功能

4. 证据而非声明

   • 在宣布任务完成之前必须验证
   • 要求看到测试通过、代码运行，而不是"我觉得应该可以了"

三、完整工作流程

Superpowers构建了一个端到端的7阶段开发流程：

1. 头脑风暴（Brainstorming）

   • 当用户提出功能需求时，AI不会直接写代码
   • 通过苏格拉底式对话一次问一个问题，帮助厘清真正需求
   • 方案分200-300字的小节呈现，每节都需要用户确认

2. 工作区隔离（Using Git Worktrees）

   • 设计确认后，AI创建新的git分支和git worktree
   • 确保开发环境隔离，不污染主分支

3. 编写计划（Writing Plans）

   • 把设计拆解成2-5分钟可完成的小任务
   • 每个任务包含精确的文件路径、完整的代码、验证步骤

4. 执行计划（Executing Plans）或子代理驱动开发（Subagent-Driven Development）

   • 按计划执行任务，或为每个任务启动独立的AI子代理
   • 避免上下文污染，实现快速迭代

5. 测试驱动开发（Test-Driven Development）

   • 强制RED-GREEN-REFACTOR循环
   • 删除在测试之前写的任何代码

6. 请求代码审查（Requesting Code Review）

   • 在任务之间自动请求审查
   • 报告问题严重性，关键问题会阻塞进度

7. 完成开发分支（Finishing a Development Branch）

   • 任务完成后验证测试
   • 提供合并/PR/保留/丢弃选项，清理worktree

四、核心技能库详解

Superpowers包含14+个核心技能，分为多个类别：

测试相关技能

• test-driven-development：RED-GREEN-REFACTOR循环，包含测试反模式参考

调试相关技能

• systematic-debugging：四阶段根因分析（根因追踪、纵深防御、基于条件的等待）
• verification-before-completion：确保问题真正被修复

协作相关技能

• brainstorming：苏格拉底式设计精炼
• writing-plans：详细实施计划
• executing-plans：带检查点的批量执行
• dispatching-parallel-agents：并发子代理工作流
• requesting-code-review：预审查清单
• receiving-code-review：响应反馈
• using-git-worktrees：并行开发分支
• finishing-a-development-branch：合并/PR决策
• subagent-driven-development：两阶段审查的快速迭代

元技能

• writing-skills：创建新技能（包含测试方法论）
• using-superpowers：技能系统入门

五、技术架构与实现

架构设计

Superpowers采用分层技能引擎架构：

1. 元技能层：using-superpowers作为系统入口，管理技能触发规则
2. 核心技能层：包含7大领域技能（测试/调试/协作/元编程）
3. 执行层：subagent-driven-development实现任务分解与子代理调度

技能系统设计

• 技能发现机制：采用深度优先递归扫描算法，最大搜索深度默认为3层
• 动态加载流程：支持个人技能与官方技能的命名空间隔离
• 优先级规则：个人技能优先 > 显式命名空间 > 回退机制
• 技能遮蔽机制：个人技能自动覆盖官方同名技能

执行原理

Superpowers本身不包含可执行代码，它的"执行"完全依赖于AI对指令的理解与模拟操作：

• SKILL.md：自然语言指令，AI阅读后在对话中模拟执行步骤
• Git操作：AI生成shell命令建议，由用户或IDE执行
• 代码生成：AI输出完整、可粘贴的代码块
• 测试：AI先输出测试代码，要求用户运行并确认失败，再输出实现

六、安装部署指南

平台支持

Superpowers支持多个AI编程平台，安装方式各不相同：

平台	推荐安装方式	备注
Claude Code	官方插件市场	最方便，推荐方式
Cursor	插件市场	搜索"superpowers"安装
Codex	手动配置	需要执行特定命令
OpenCode	手动配置	需要创建符号链接
Gemini CLI	扩展安装	通过gemini extensions命令

详细安装步骤

1. Claude Code（推荐方式）

# 注册插件市场
/plugin marketplace add obra/superpowers-marketplace

# 安装插件
/plugin install superpowers@superpowers-marketplace

2. Cursor

# 在Cursor Agent聊天中
/add-plugin superpowers
# 或在插件市场中搜索"superpowers"

3. Codex

# 告诉Codex执行以下命令
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md

4. OpenCode

# 创建配置目录
mkdir -p ~/.config/opencode/superpowers

# 克隆仓库
git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers

# 创建插件符号链接
mkdir -p ~/.config/opencode/plugin
ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js ~/.config/opencode/plugin/superpowers.js

# Windows PowerShell用户
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.config\opencode\plugin\superpowers.js" -Target "$env:USERPROFILE\.config\opencode\superpowers\.opencode\plugin\superpowers.js" -Force

5. 手动安装（通用）

# 克隆仓库
git clone https://github.com/obra/superpowers.git

# Claude Code用户复制到skills目录
# 全局目录：~/.claude/skills/
# 项目级目录：项目/.claude/skills/
cp -r superpowers 项目/.claude/skills/

# 重启Claude Code

验证安装

启动新会话，让AI帮忙做能触发技能的事情，例如：

• “帮我规划这个功能”
• “让我们调试这个问题”
• “帮我设计一个用户通知系统”

如果安装成功，AI会自动使用相关技能。

更新插件

/plugin update superpowers

七、使用方法与实战指南

基本使用流程

1. 启动对话：正常与AI编程助手对话
2. 自动触发：当AI检测到开发任务时，会自动检查并应用相关技能
3. 交互式工作：按照技能的引导步骤进行开发

典型使用场景示例

场景1：开发新功能

用户：帮我设计一个用户通知系统

AI（使用brainstorming技能）：
我正在使用brainstorming技能来理解你的需求。
首先，这个功能的主要用户是谁？
A) 普通用户
B) 管理员  
C) 开发者
D) 其他（请说明）

场景2：测试驱动开发

// AI使用test-driven-development技能
// 步骤1：🔴 写失败的测试
test('should validate email format', () => {
  const result = validateEmail('invalid-email');
  expect(result.valid).toBe(false);
});

// 步骤2：运行测试，确认它失败
// $ npm test → FAIL

// 步骤3：🟢 写最小实现
function validateEmail(email: string) {
  return { valid: email.includes('@') };
}

// 步骤4：运行测试，确认通过
// $ npm test → PASS

// 步骤5：🔵 重构（如果需要）

场景3：子代理驱动开发

AI（使用subagent-driven-development技能）：
我正在使用subagent-driven-development技能。

=== 任务1：Hook安装脚本 ===
[派遣实现者子代理...]

实现者：在开始之前，hook应该安装在用户级别还是系统级别？
你：用户级别

实现者：收到，开始实现...
- 实现了install-hook命令
- 测试通过5/5
- 自检：发现遗漏了--force标志，已添加
- 已提交

[派遣规格审查子代理...]
规格审查：✅ 符合规格

[派遣代码质量审查子代理...]
代码审查：✅ 通过

任务1完成！

技能触发时机

技能	触发条件	关键活动
brainstorming	任何创造性工作之前	交互式需求澄清，输出设计文档
using-git-worktrees	设计批准后	创建隔离的工作空间
writing-plans	有批准的设计后	拆分为2-5分钟的小任务
executing-plans	有计划后	批量执行，带检查点
subagent-driven-development	有计划且需要并行时	为每个任务启动独立子代理
test-driven-development	实现过程中	强制RED-GREEN-REFACTOR循环
requesting-code-review	任务之间	审查是否符合计划
finishing-a-development-branch	任务完成后	处理合并/PR/清理

八、故障排除与常见问题

安装问题

Windows安装失败

• 问题：各种错误导致安装无法完成
• 解决方案：
  1. 重新下载安装包，确保下载完整
  2. 以管理员身份运行安装程序
  3. 使用Git Bash而非CMD或PowerShell
  4. 参考项目中的docs/windows/polyglot-hooks.md文件

跨平台部署差异

• Claude Code用户：直接通过市场安装
• Codex/OpenCode用户：需要手动配置
• Windows用户：推荐使用mklink /J创建目录junction而非普通符号链接

"Plugin hook error"错误

# 检查并修复脚本权限
chmod +x hooks/session-start.sh

# 手动执行钩子脚本排查错误
./hooks/session-start.sh --debug

# 更新到最新版本
git pull origin main && ./update.sh

"Bad substitution"错误（Ubuntu/Debian）

# 检查当前默认shell
ls -l /bin/sh

# 如指向dash，切换到bash
sudo dpkg-reconfigure dash  # 选择"No"

运行时问题

错误码	描述	常见场景	解决方案
R001	钩子执行失败	启动或功能切换时	检查脚本权限，查看日志
R002	资源加载错误	技能或插件调用时	验证技能目录结构
R003	参数解析异常	命令行输入错误时	检查命令格式
R004	权限访问拒绝	操作系统资源受限	检查文件权限

验证安装

# 验证技能目录是否存在
ls ~/.codex/superpowers/skills

# 或检查Claude Code的skills目录
ls ~/.claude/skills/

九、最佳实践与高级技巧

1. 技能创建指南

创建新技能时遵循TDD原则：

1. 先写测试：在编写技能之前运行基线场景
2. 看它失败：记录agent使用的确切合理化
3. 最小代码：编写解决那些特定违规的技能
4. 看它通过：验证agent现在合规
5. 重构循环：找到新的合理化 → 插入 → 重新验证

2. 技能目录结构

skills/
  skill-name/
    SKILL.md          # 主参考（必需）
    supporting-file.* # 仅在需要时

3. SKILL.md结构规范

---
name: skill-name
description: "Use when [触发条件] - [简要描述]"
---

# 技能名称
## 概述
[技能内容...]

4. 个人技能覆盖

• 个人技能位置：~/.claude/skills/（Claude Code）或~/.codex/skills/（Codex）
• 优先级：个人技能 > 官方技能
• 强制使用官方技能：使用superpowers:skill-name前缀

5. 性能优化

• Token效率：getting-started工作流<150字，频繁加载技能<200字
• 跨引用：仅使用技能名称，带有明确的必需标记
• 避免@链接：@语法立即强制加载文件，消耗大量上下文

十、适用场景与局限性

适合使用Superpowers的场景

1. 复杂功能开发：需要系统化设计的大型功能
2. 多人协作项目：需要统一代码规范的团队
3. 质量要求高的项目：金融、医疗等对代码质量要求严格的领域
4. AI Agent开发：想让AI Agent产生可靠输出的开发者
5. 教学和培训：教授软件工程最佳实践

不太适合的场景

1. 简单脚本编写：杀鸡用牛刀
2. 一次性探索实验：流程太重
3. 资源极度受限的环境：代理运行成本高

优势与局限性

优势：
经过验证的方法论：不是理论，而是实际可工作的系统
高度可组合：技能可以独立使用或组合
强制最佳实践：从流程上保证代码质量
多平台支持：覆盖主流AI编程工具
活跃维护：持续更新
丰富的技能库：开箱即用的15+技能

局限性：
学习曲线：需要理解其工作流哲学
平台依赖：需要特定的AI编程环境
配置复杂：多平台配置有一定门槛
中文支持：文档主要为英文
资源消耗：多代理模式可能消耗更多资源