Superpowers 完整指南：AI 编程代理工程化工作流的革命
一、什么是 Superpowers？
Superpowers 是一个为 AI 编程代理（如 Claude Code、Codex、OpenCode）打造的完整软件开发工作流系统。
它的核心理念是：通过一套可组合的"技能"（Skills）和初始指令，让 AI 代理在编写代码时自动遵循最佳实践，而不是像"没有经验的初级工程师"那样随意行事。
核心定位
| 维度 | 描述 |
|---|---|
| 目标 | 让 AI 编程代理像资深工程师一样工作 |
| 方法 | 把最佳实践编码成可执行的工作流 |
| 效果 | 自动遵循 TDD、代码审查、测试驱动开发 |
项目背景
- 开发者：Jesse Vincent（GitHub: obra）
- Star：16.1k+
- Fork：1.3k+
- 开源协议：MIT
二、核心设计哲学
Superpowers 建立在四个核心原则之上：
1. 测试驱动开发（TDD）
永远先写测试。没有看到测试失败，就不能确定测试是否真正测试了正确的行为。
RED-GREEN-REFACTOR 循环：
- RED：写一个会失败的测试
- GREEN：写最少的代码让测试通过
- REFACTOR：重构优化代码
2. 系统化而非临时化
用流程替代猜测。
- 每个技能都有明确的决策流程图（用 DOT/GraphViz 语法定义）
- 流程图作为"可执行规范"，AI 必须遵循
3. 复杂度削减
以简洁为首要目标。
- 技能中反复强调 YAGNI（You Aren't Gonna Need It）原则
- 积极删除不必要的功能
4. 证据而非声明
在宣布任务完成之前，必须验证。
- 看到测试通过
- 看到代码运行
- 而不是"我觉得应该可以了"
三、完整工作流程
Superpowers 构建了一个端到端的开发流程：
第一阶段：头脑风暴（Brainstorming）
当你说"我想做一个 X 功能"时，AI 不会直接写代码。
它会像苏格拉底式对话一样，一次问一个问题，帮你厘清真正的需求。
- 方案分 200-300 字的小节呈现
- 每节都要你确认"看起来对吗"
第二阶段：工作区隔离（Using Git Worktrees）
设计确认后，AI 会：
- 创建新的 git 分支
- 创建 git worktree
- 确保开发环境隔离，不污染主分支
第三阶段：编写计划（Writing Plans）
把设计拆解成 2-5 分钟的小任务。
每个任务都有：
- 精确的文件路径
- 完整的代码片段
- 验证步骤
目标是让"一个没有判断力、没有项目背景、讨厌写测试的热情初级工程师"也能执行。
第四阶段：子代理驱动开发（Subagent-Driven Development）
这是 v4.0 的重大创新！
主代理为每个任务派遣一个"新鲜"的子代理（没有上下文污染），实现任务后进行两阶段审查：
阶段一：规格符合性审查
- 代码是否完全符合需求规格？
- 是否多做了？少做了？
阶段二：代码质量审查
- 只有规格审查通过后才进行
- 检查代码是否干净、测试覆盖是否足够
审查是循环的：发现问题 → 修复 → 再审查，直到通过。
第五阶段：收尾（Finishing a Development Branch）
所有任务完成后：
- 验证测试
- 呈现选项（合并 / 创建 PR / 保留 / 丢弃）
- 清理 worktree
四、技能库详解
项目包含 14 个核心技能，分为几大类别：
测试类
| 技能 | 功能 |
|---|---|
test-driven-development | 强制执行 RED-GREEN-REFACTOR 循环 |
核心规则：先写测试失败的代码？删掉，重新来
包含详细的反模式参考。
调试类
| 技能 | 功能 |
|---|---|
systematic-debugging | 四阶段根因定位流程 |
verification-before-completion | 确保问题真正被修复 |
整合技术：
- root-cause-tracing（逆向追踪调用栈）
- defense-in-depth（多层验证）
- condition-based-waiting（基于条件的等待替代任意超时）
协作类
| 技能 | 功能 |
|---|---|
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 | 两阶段审查的快速迭代 |
元技能
| 技能 | 功能 |
|---|---|
using-superpowers | 技能系统入门 |
writing-skills | 如何创建新技能 |
五、技术架构亮点
1. 流程图作为可执行规范
技能文件使用 DOT 语法定义决策流程图：
- 不是装饰性的
- 是 AI 必须遵循的权威定义
- 解决了"描述覆盖流程图"的陷阱
2. 描述陷阱的发现与解决
项目团队发现：
- 如果技能描述中包含工作流摘要，AI 会跟随简短描述而忽略详细流程图
解决方案：
- 描述只写触发条件（"Use when X"）
- 不写流程细节
3. 反合理化设计
using-superpowers 技能中专门列出了 AI 常见的逃避借口及其反驳：
| 常见借口 | 正确反驳 |
|---|---|
| "我已经手动测试过了" | 错误，临时测试不等于系统化测试 |
| "这应该能工作" | 必须看到测试通过才算 |
| "这太简单了，不需要测试" | 越简单越需要测试保护 |
4. 测试基础设施
项目包含三套测试框架：
- 技能触发测试：验证技能能否从"朴素"提示触发
- Claude Code 集成测试：使用
claude -p进行无头测试 - 子代理工作流端到端测试：包含完整的 Go 和 Svelte 测试项目
六、跨平台支持
Claude Code
通过插件市场安装：
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
有原生的 Skill 工具支持。
Codex / OpenCode
通过获取远程指令文件引导安装，共享核心模块 lib/skills-core.js。
Cursor Agent
/plugin-add superpowers
七、安装指南
Claude Code 安装
# 第一步：添加市场
/plugin marketplace add obra/superpowers-marketplace
# 第二步：安装插件
/plugin install superpowers@superpowers-marketplace
# 第三步：验证
输入 /help，你应该能看到：
- /superpowers:brainstorm - 头脑风暴
- /superpowers:write-plan - 写计划
- /superpowers:execute-plan - 执行计划
Codex 安装
告诉 Codex：
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md
Codex 会自动完成所有安装步骤。
OpenCode 安装
一键安装脚本：
#!/bin/bash
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
mkdir -p ~/.config/opencode/skills
八、使用示例：做一个待办事项应用
第一步：启动头脑风暴
你只需要说：
"我想做一个待办事项应用"
注意：你不需要输入任何特殊命令！ Superpowers 会自动触发。
AI 会：
- 先侦察：看看你的项目目录，了解现有代码结构
- 一次问一个问题：不会一下子问你10个问题
- 给你选项：尽量给你 A/B/C 选择
第二步：设计文档输出
问完所有关键问题后，AI 会：
- 把设计分成 200-300 字的小节展示给你
- 每节都问你："这部分对吗？"
- 全部确认后，写入
docs/plans/2025-01-10-todo-app-design.md
第三步：创建隔离工作区
你说"是的，准备好了"
AI 会自动：
- 创建新分支：
feature/todo-app - 创建 worktree：一个独立的工作目录
- 运行项目初始化：确保环境能跑起来
- 验证测试基线：确保现有测试都是绿色的
第四步：编写实现计划
你不能说"做一个待办事项应用"，你得说：
- 第一步：创建 Todo 数据结构
- 第二步：实现"添加"功能
- 第三步：实现"删除"功能
- ...
每一步都要小到 2-5 分钟能完成。
第五步：执行计划
RED（红色）：写一个会失败的测试
运行测试：npm test → 失败（因为 addTodo 还不存在）
关键：你必须亲眼看到测试失败！
如果测试一开始就通过，说明：
- 你测试的是已有功能（没意义）
- 测试写错了（危险）
GREEN（绿色）：写最少的代码让测试通过
九、版本演进
| 版本 | 核心创新 |
|---|---|
| v4.0.0 | 两阶段代码审查 + 调试技术整合 |
| v3.0 | 迁移到 Anthropic 官方技能系统 |
| v2.0 | 实现技能仓库分离，支持社区贡献 |
十、总结
Superpowers 本质上是在回答一个问题：
如何让 AI 代理像有经验的工程师一样工作，而不是像"会写代码但不懂工程"的实习生？
答案
用流程图定义决策点，用测试验证行为，用子代理实现关注点分离，用两阶段审查确保质量。
把最佳实践编码成可执行的、不可逃避的工作流。
