Superpowers：AI 编码代理技能框架与软件开发方法论详解

项目地址：https://github.com/obra/superpowers 版本：v6.1.1（2026-07-02） 作者：Jesse Vincent（obra），Prime Radiant 团队 许可证：MIT GitHub Stars：259,000+（截至 2026 年 7 月） 主语言：Shell

一、Superpowers 是什么？

Superpowers 是一个为 AI 编码代理（coding agents）设计的完整软件开发方法论框架。它构建在一套可组合的技能（skills）之上，通过会话启动时的自动注入机制，让编码代理自动遵循系统化的开发流程。

核心定位

• 不是一个工具库，而是一套行为塑造框架（behavior-shaping framework）
• 不是可选的建议，而是强制性的工作流（mandatory workflows）
• 不依赖特定平台，支持 11+ 种主流 AI 编码代理

理念

二、Superpowers 能做什么？

Superpowers 通过 14 个核心技能（Skills）覆盖了软件开发的全生命周期：

技能库全览

核心工作流程

Superpowers 定义了一个从设计到交付的完整工作流：

1. brainstorming（头脑风暴）
   ↓ 主动提问，细化需求，产出设计文档
2. using-git-worktrees（Git 工作树）
   ↓ 创建隔离工作空间，验证测试基线
3. writing-plans（编写计划）
   ↓ 分解为 2-5 分钟的小任务，每步含精确路径和代码
4. subagent-driven-development（子代理驱动开发）
   ↓ 每个任务派发新子代理，双阶段审查（规格合规 + 代码质量）
5. test-driven-development（TDD）
   ↓ RED-GREEN-REFACTOR：写失败测试 → 看它失败 → 写最小代码 → 看它通过 → 提交
6. requesting-code-review（代码审查）
   ↓ 按严重程度报告问题，关键问题阻断进度
7. finishing-a-development-branch（完成分支）
   ↓ 验证测试 → 提供选项（合并/PR/保留/丢弃）→ 清理工作树

三、核心技能详解

3.1 using-superpowers（技能系统引导）

这是系统的入口技能，在每次会话开始时自动注入模型上下文。

核心规则： - 在任何回复（包括澄清问题）之前，必须先检查是否有相关技能适用 - 如果有 1% 的可能性某技能适用于你正在做的事，就必须调用它 - 技能不是建议，而是必须执行的流程

红旗机制：当模型产生"这只是个简单问题"、"我先了解一下代码"等想法时，就触发停止并检查技能。

优先级：用户指令（CLAUDE.md、AGENTS.md 等）> 技能 > 默认行为。

3.2 brainstorming（头脑风暴）

用途：在任何创造性工作之前，将粗略想法转化为完整设计和规格。

关键流程： 1. 探索项目上下文（文件、文档、最近提交） 2. 逐个提问来细化想法 3. 提出 2-3 个方案及其权衡，给出推荐 4. 分节展示设计，逐节获取用户批准 5. 将设计文档保存到 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md 6. 自审后交由用户审查 7. 转入 writing-plans 技能编写实现计划

硬性门控：在用户批准设计前，不写任何代码、不调用任何实现技能。

3.3 writing-plans（编写计划）

用途：将规格分解为可执行的细粒度任务计划。

核心原则： - 假设执行者对代码库零上下文、品味差 - 每步 2-5 分钟，包含精确文件路径和完整代码 - DRY（不重复）、YAGNI（不过度设计）、TDD（测试先行） - 任务保存到 docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

任务粒度：每个步骤是一个动作——"写失败测试"是一步，"运行确认失败"是一步，"写最小代码使测试通过"是一步，"运行测试确认通过"是一步，"提交"是一步。

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

这是 Superpowers v6.0 的核心创新，也是推荐的计划执行方式。

工作模式：

读取计划 → 创建待办列表 → 循环执行每个任务：
  派发新的实现子代理（不继承会话历史）→
  子代理实现、测试、提交、自审 →
  写 diff 文件，派发审查子代理（规格合规 + 代码质量）→
  如果有 Critical/Important 发现 → 派发修复子代理 → 重新审查 →
  标记完成，更新进度账本
→ 所有任务完成后 → 派发最终全分支审查子代理

v6.0 重大改进： - 从每个任务两个审查者合并为一个审查者（返回两个裁定：规格合规 + 代码质量） - diff 和任务文本以文件方式传递（避免粘贴在昂贵上下文中永久驻留） - 每次派发必须声明使用的模型（避免默认使用最贵模型） - 运行结束时进行单次全分支审查（替代逐任务重新审查）

效果：约 2 倍速度提升，近 50% token 消耗减少。

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

铁律：没有失败测试，就不写生产代码。先写代码再补测试？删掉，重来。

RED-GREEN-REFACTOR 循环： 1. RED：写一个最小的失败测试 2. 验证它确实以正确的方式失败 3. GREEN：写最少的代码让测试通过 4. 验证所有测试都通过 5. REFACTOR：清理代码，保持绿色 6. 进入下一个循环

适用场景：新功能、bug 修复、重构、行为变更。所有情况，无例外。

3.6 systematic-debugging（系统化调试）

铁律：没有根因调查，不提修复方案。

四阶段流程：

何时特别需要使用：时间压力下、看似简单的问题、已经试过多次修复、之前的修复没效果、对问题不完全理解时。

3.7 其他技能概要

四、如何上手？

4.1 支持的平台

Superpowers 支持 11 种主流 AI 编码代理：

4.2 基本使用步骤

安装后无需额外操作。Superpowers 会自动在每个会话启动时注入引导技能。

使用流程：

1. 启动编码代理（如 Claude Code）
2. 输入你的需求，例如："帮我做一个 React todo list"
3. Superpowers 自动触发：
4. 代理不会直接写代码，而是先进入 brainstorming 流程
5. 逐个提问，细化你的需求
6. 提出 2-3 个设计方案，推荐一个并解释原因
7. 分节展示设计，逐节获取你的确认
8. 设计批准后：
9. 自动创建 git worktree 隔离工作空间
10. 进入 writing-plans，分解为小任务计划
11. 你说 "go" 后，进入 subagent-driven-development
12. 每个任务派发子代理实现、测试、审查
13. 整个过程可能自主运行数小时而不偏离计划

关键体验：你不需要做任何特殊操作，编码代理自动拥有 Superpowers。

4.3 配置选项

禁用视觉遥测：

export SUPERPOWERS_DISABLE_TELEMETRY=true
# 或
export DISABLE_TELEMETRY=true
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=true

更新：Superpowers 的更新大多自动完成，具体取决于使用的编码代理平台。

五、技术架构

5.1 三层集成机制

Superpowers 采用三层架构来跨平台工作：

┌─────────────────────────────────────────────────┐
│  层 1：Skills（技能层 - 平台无关）               │
│  skills/ 目录是真理的来源，所有平台共享           │
│  技能描述"动作"而非"工具"                        │
├─────────────────────────────────────────────────┤
│  层 2：Tool Mapping（工具映射层 - 平台特定）      │
│  将动作词汇翻译为各平台的真实工具名              │
│  如"dispatch a subagent" → task / delegate      │
├─────────────────────────────────────────────────┤
│  层 3：Bootstrap（引导层 - 平台特定）             │
│  每次会话启动时自动注入 using-superpowers 内容   │
│  这是整个集成的核心：没有它，技能文件无效果       │
└─────────────────────────────────────────────────┘

5.2 三种集成形态

5.3 跨平台不变量

存在两条不可违反的规则：

1. 技能命名动作而非工具：不编辑技能内容来适配平台。移植只添加工具映射和引导注入，不改 skills/*/SKILL.md。
2. 一切通过平台自身的安装机制分发：不编辑用户文件。引导、技能、工具映射都通过插件的安装产物分发。

5.4 项目结构

superpowers/
├── skills/                          # 14 个核心技能（平台无关）
│   ├── using-superpowers/            # 引导技能（每次会话注入）
│   ├── brainstorming/                # 头脑风暴
│   ├── writing-plans/                # 编写计划
│   ├── subagent-driven-development/  # 子代理驱动开发
│   ├── executing-plans/              # 执行计划
│   ├── test-driven-development/      # TDD
│   ├── systematic-debugging/         # 系统化调试
│   ├── verification-before-completion/ # 完成前验证
│   ├── requesting-code-review/       # 请求代码审查
│   ├── receiving-code-review/        # 接收代码审查
│   ├── dispatching-parallel-agents/  # 并行代理调度
│   ├── using-git-worktrees/          # Git 工作树
│   ├── finishing-a-development-branch/ # 完成分支
│   └── writing-skills/              # 编写技能
├── hooks/                            # 会话启动钩子脚本
├── .claude-plugin/                   # Claude Code 插件清单
├── .codex-plugin/                    # Codex 插件清单
├── .cursor-plugin/                   # Cursor 插件清单
├── .kimi-plugin/                     # Kimi Code 插件清单
├── .opencode/                        # OpenCode 插件
├── .pi/                              # Pi 扩展
├── docs/                             # 文档
│   ├── porting-to-a-new-harness.md   # 移植到新平台指南
│   └── testing.md                    # 测试文档
├── tests/                            # 测试套件
├── scripts/                          # 脚本
├── README.md                         # 主文档
├── RELEASE-NOTES.md                  # 发行说明
├── AGENTS.md                         # 代理指令
├── CLAUDE.md                         # Claude 指令
├── GEMINI.md                         # Gemini 指令（已移除）
├── package.json                      # 包元数据
└── LICENSE                           # MIT 许可证

六、版本演进

重要里程碑

七、社区与资源

贡献流程

1. Fork 仓库
2. 切换到 dev 分支
3. 为你的工作创建分支
4. 按照 writing-skills 技能创建和测试新/修改的技能
5. 提交 PR，填写模板

注意：项目一般不接受新技能的贡献，技能更新必须适用于所有支持的编码代理。

八、与 Hermes Agent 的关系

Superpowers 的部分核心理念已被 Hermes Agent 采用并适配。Hermes 的以下技能明确标注为"adapted from obra/superpowers"：

这表明 Superpowers 的方法论对 AI 代理生态系统产生了广泛影响，Hermes Agent 将其核心开发流程技能的最佳实践吸收并适配到自己的技能框架中。

九、总结

Superpowers 是目前 GitHub 上最受关注的 AI 编码代理技能框架（259K+ stars），其核心价值在于：

1. 完整方法论：不是零散的工具集，而是从需求到交付的完整开发流程体系
2. 行为塑造：通过自动注入和强制流程，确保 AI 代理始终遵循最佳实践
3. 跨平台兼容：支持 11+ 种主流编码代理，技能内容不变，只适配工具映射
4. 子代理驱动：v6.0 的核心创新，通过子代理隔离 + 双阶段审查 + 文件化传递，实现高质量的自主开发
5. TDD 优先：铁律级的 TDD 执行——不写失败测试，不写生产代码
6. 系统化调试：四阶段根因分析，杜绝猜测式修复
7. 社区生态：活跃的 Discord 社区、商业支持选项，以及持续更新的版本

对于任何使用 AI 编码代理的团队或个人，Superpowers 都是一个值得安装和使用的方法论框架——它让 AI 不只是写代码，而是系统化地、可验证地、以高质量标准地完成软件开发。