Superpowers — AI 驱动的软件工程方法论框架
·
Superpowers — AI 驱动的软件工程方法论框架
GitHub: https://github.com/obra/superpowers
Stars: 20万+ | Forks: 1.8万+ | License: MIT
作者: Obra
目录
1. 项目概述
一句话概括
Superpowers 是一套把完整软件工程方法论封装成「可组合工作流」的 AI 技能框架，让 Claude Code 等 AI 编程助手遵循严格规范执行开发任务。
核心理念
| 理念 | 含义 |
|---|---|
| 方法论 > 提示词 | 不是随意对话，而是结构化的工程流程 |
| 可组合 | 技能之间像积木一样拼接，形成完整流水线 |
| 验证驱动 | 每一步都有验证门槛，拒绝"我觉得行" |
| 诚实地报告 | AI 不做表演性附和，只说有证据的结论 |
为什么重要？
传统开发中，人负责流程把控；AI 辅助开发中，如果 AI 不遵循方法论，就会：
- 跳过测试直接说"完成了"
- 盲目接受代码审查意见
- 不验证就提交代码
Superpowers 解决的核心问题：让 AI 像一个训练有素的工程师一样工作，而不是一个急于取悦你的助手。
2. 什么是 Skill（技能）
定义
Skill 是一个以 SKILL.md 为核心的 markdown 文档，定义了：
- 触发条件：什么时候该用这个技能
- 执行步骤：按什么顺序做什么
- 规则约束：什么能做、什么绝对不能做
- 模板与参考：配套的 prompt 模板和示例
文件结构
skills/
├── brainstorming/ # 头脑风暴
│ ├── SKILL.md # ← 核心定义文件
│ ├── visual-companion.md # 视觉辅助模板
│ ├── spec-document-reviewer-prompt.md
│ └── scripts/ # 辅助脚本
│ ├── server.cjs
│ ├── helper.js
│ └── start-server.sh
├── writing-plans/ # 编写计划
│ ├── SKILL.md
│ └── plan-document-reviewer-prompt.md
├── test-driven-development/ # 测试驱动开发
│ ├── SKILL.md
│ └── testing-anti-patterns.md
└── ...
SKILL.md 的元数据格式
---
name: skill-name # 技能名称
description: 触发条件的描述 # 什么时候该自动激活
---
# 技能标题
## 具体内容...
description 字段非常关键——它告诉 AI 什么时候应该自动触发这个技能，而不需要用户显式请求。
3. 安装与使用
安装方式
Superpowers 作为 Claude Code 插件安装：
# 在 Claude Code 中添加插件
/install-plugin obra/superpowers
安装后，技能会自动加载到 Claude Code 的上下文中。
使用方式
方式一：自然触发（推荐）
直接描述你的需求，AI 会根据 description 字段自动匹配并激活对应技能：
你：我想给这个项目加一个用户认证功能，但不确定用什么方案
AI：（自动触发 brainstorming 技能）
方式二：显式调用
直接指定要用的技能：
你：用 writing-plans 技能帮我做一个实现计划
你：用 TDD 方式实现这个功能
你：帮我 review 这段代码
方式三：组合使用
多个技能自动串联，形成完整流程：
brainstorming → writing-plans → executing-plans → TDD → verification → code-review
支持的 AI 编程工具
| 工具 | 支持状态 |
|---|---|
| Claude Code | 原生支持 |
| OpenCode | 支持 |
| Codex (OpenAI) | 支持 |
| Cursor | 部分支持 |
| Gemini | 部分支持 |
4. 11 大核心技能详解
技能全景图
┌─────────────────────────────────────────────────────┐
│ Superpowers 技能体系 │
├──────────┬──────────┬──────────┬────────────────────┤
│ 规划阶段 │ 执行阶段 │ 质量阶段 │ 协作阶段 │
├──────────┼──────────┼──────────┼────────────────────┤
│brainstorm│executing │ TDD │requesting-code- │
│ ing │ plans │ │ review │
├──────────┼──────────┼──────────┼────────────────────┤
│ writing │ subagent │verify- │receiving-code- │
│ plans │ driven │ before │ review │
│ │ dev │completion│ │
├──────────┼──────────┼──────────┼────────────────────┤
│ │dispatch- │systematic│finishing-a- │
│ │ parallel │debugging │ dev-branch │
│ │ agents │ │ │
├──────────┼──────────┼──────────┼────────────────────┤
│ │git │ │ │
│ │worktrees │ │ │
└──────────┴──────────┴──────────┴────────────────────┘
+ writing-skills (元技能：创建新 Skill)
+ using-superpowers (使用指南)
4.1 Brainstorming — 头脑风暴
触发条件：当需要探索问题空间、生成想法、评估方案时
核心目标：在动手写代码之前，先把问题想清楚
执行流程：
1. 定义问题
↓
2. 发散：列出所有可能的方案（不评判）
↓
3. 收敛：评估每个方案的利弊
↓
4. 推荐：给出最佳方案并说明理由
↓
5. 输出：明确的设计文档，而非模糊的想法
特色功能 — 视觉化头脑风暴：
项目内置了一个本地 WebSocket 服务器，可以把头脑风暴过程可视化为思维导图/框架图，在浏览器中实时查看。
规范文档评审：
头脑风暴技能还附带一个 spec-document-reviewer-prompt，用于在头脑风暴结束后评审输出的设计文档是否：
- 完整覆盖了需求
- 方案有清晰的取舍理由
- 技术可行性经过验证
关键规则：
| 规则 | 说明 |
|---|---|
| 先发散后收敛 | 不能一上来就否定方案 |
| 每个方案都要有利弊分析 | 没有银弹 |
| 必须给出明确推荐 | 不能以"都行"结尾 |
4.2 Writing Plans — 编写计划
触发条件：当需要将设计转化为可执行的实施计划时
核心目标：把模糊的需求变成可逐步执行的任务清单
计划文档结构：
# 实施计划：[功能名称]
## 目标
[一句话描述最终要达成什么]
## 前置条件
- [依赖1]
- [依赖2]
## 实施步骤
### Phase 1: [阶段名称]
- [ ] Task 1: 描述...
- [ ] Task 2: 描述...
### Phase 2: [阶段名称]
- [ ] Task 1: 描述...
- [ ] Task 2: 描述...
## 风险与缓解
| 风险 | 缓解措施 |
|------|---------|
| ... | ... |
## 验收标准
- [ ] 标准1
- [ ] 标准2
计划评审器：
与头脑风暴类似，编写计划也有配套的 plan-document-reviewer-prompt，负责检查：
- 任务是否足够具体、可执行
- 是否有遗漏的步骤
- 依赖关系是否标注清楚
- 验收标准是否可量化
关键规则：
| 规则 | 说明 |
|---|---|
| 任务必须原子化 | 每个任务应该是 1 个明确的动作 |
| 必须标注依赖 | 哪些任务必须在哪些之后 |
| 必须有验收标准 | 每个阶段完成的标准是什么 |
| 计划必须可验证 | 能明确判断"做完"还是"没做完" |
4.3 Executing Plans — 执行计划
触发条件：当有已写好的计划并需要逐步执行时
核心目标：严格按照计划执行，不遗漏、不跳步
执行原则：
1. 读取计划 → 确认当前位置
2. 执行当前任务 → 严格按计划描述操作
3. 验证当前任务 → 确认真正完成后再继续
4. 更新状态 → 标记已完成，记录变更
5. 进入下一个 → 不回头，不并行（除非计划允许）
关键约束：
| 约束 | 说明 |
|---|---|
| 不跳步 | 即使觉得"很简单"也必须走完流程 |
| 不加戏 | 不做计划之外的"优化"或"改进" |
| 不假设完成 | 每一步都要验证，而不是"觉得做完了" |
| 遇阻即停 | 遇到计划未覆盖的问题，停下来讨论 |
4.4 Test-Driven Development (TDD) — 测试驱动开发
触发条件：当实现新功能或修复 Bug 时
核心目标：先写测试再写代码，确保每一行代码都有测试覆盖
TDD 红绿循环：
🔴 RED → 写一个失败的测试（定义期望行为）
🟢 GREEN → 写最少的代码让测试通过
🟡 REFACTOR → 在测试保护下重构代码
完整流程：
1. 理解需求 → 明确期望行为
2. 写失败测试 → 运行确认测试失败（RED）
3. 写实现代码 → 让测试通过（GREEN）
4. 重构 → 保持测试通过的前提下改进代码
5. 重复 → 直到所有需求都被测试覆盖
测试反模式（来自 testing-anti-patterns.md）：
| 反模式 | 问题 | 正确做法 |
|---|---|---|
| 测试实现细节 | 重构就断 | 测试行为，不测实现 |
| 过度 mock | 测了个寂寞 | 只 mock 外部边界 |
| 一个测试测多件事 | 难定位失败 | 一个测例一个断言 |
| 不测边界条件 | 线上出 bug | 空值、溢出、边界都要测 |
| 测试间有依赖 | 顺序敏感 | 每个测试独立运行 |
| 测试无断言 | 跑过=通过？ | 每个测试必须有明确断言 |
4.5 Requesting Code Review — 请求代码审查
触发条件：当完成功能实现、准备请求他人审查代码时
核心目标：生成结构化的审查请求，让审查者高效理解变更
Code Reviewer 模板：
项目提供了一个 code-reviewer.md 模板，定义了审查者的角色和行为规范：
- 审查者应关注：正确性、安全性、性能、可维护性
- 审查者不应关注：风格偏好（交给 linter）、非此次变更的问题
审查请求应包含的信息：
1. 变更摘要 — 改了什么、为什么改
2. 影响范围 — 涉及哪些模块
3. 测试情况 — 过了哪些测试
4. 风险点 — 哪里最可能出问题
5. 需要特别关注的地方 — 请求审查者重点看的部分
4.6 Receiving Code Review — 接收代码审查
触发条件：当收到代码审查反馈时
核心目标：技术性地处理反馈，不做表演性附和
这是 Superpowers 最有特色的设计之一，它明确禁止 AI 做以下行为：
禁止清单：
| 禁止行为 | 替代做法 |
|---|---|
| “You’re absolutely right!” | 陈述技术事实或直接行动 |
| “Great point!” | 重述需求或提出疑问 |
| “Let me implement that now” | 先验证再实现 |
| 任何感谢表达 | 代码本身就是回应 |
正确流程：
收到反馈
↓
1. 完整阅读 → 不急于反应
2. 理解需求 → 用自己的话重述
3. 验证可行性 → 对照代码库检查
4. 评估正确性 → 这个建议在这对吗？
5. 回应 → 技术性确认 或 有理有据地反驳
6. 实现 → 逐项修改，逐项测试
什么时候应该反驳：
- 建议会破坏现有功能
- 审查者缺乏完整上下文
- 违反 YAGNI 原则（不需要的功能）
- 对当前技术栈不正确
- 与已有的架构决策冲突
YAGNI 检查：
如果审查者建议"好好实现"某个功能：
grep 代码库查找实际使用
如果未使用 → "这个端点没被调用，删掉更好(YAGNI)?"
如果有使用 → 再好好实现
4.7 Subagent-Driven Development — 子代理驱动开发
触发条件：当任务可以并行分解、需要多个 AI 代理协作时
核心目标：把大任务拆分给多个 AI 子代理并行执行，最后整合
三个角色：
| 角色 | Prompt 模板 | 职责 |
|---|---|---|
| Implementer | implementer-prompt.md |
执行具体编码任务 |
| Spec Reviewer | spec-reviewer-prompt.md |
检查实现是否符合规格 |
| Code Quality Reviewer | code-quality-reviewer-prompt.md |
检查代码质量 |
Spec Reviewer 的核心原则：
“不要信任实现者的报告。独立验证一切。”
实现者说"做完了"？
→ Spec Reviewer 自己去看代码
→ 逐行对比需求
→ 检查遗漏、多余、误解
→ 产出验证报告
工作流：
┌──────────────┐
│ 主控代理 │
└──────┬───────┘
┌──────────────┼──────────────┐
▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│ Implementer│ │ Implementer│ │ Implementer│
│ (Task 1) │ │ (Task 2) │ │ (Task 3) │
└──────┬─────┘ └──────┬─────┘ └──────┬─────┘
│ │ │
▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│Spec Review │ │Spec Review │ │Spec Review │
└──────┬─────┘ └──────┬─────┘ └──────┬─────┘
└──────────────┼──────────────┘
▼
┌──────────────┐
│ Quality │
│ Review │
└──────────────┘
4.8 Dispatching Parallel Agents — 调度并行代理
触发条件：当多个独立任务可以同时执行时
核心目标：识别并行机会，同时调度多个 AI 代理加速开发
与 SDD 的关系：SDD 是方法论，并行调度是技术手段。SDD 的 Implementer 可以通过并行调度来加速。
适用场景：
✅ 适合并行：
- 多个互不依赖的功能模块
- 前后端分离的开发
- 多种测试的编写
- 文档与代码同步编写
❌ 不适合并行：
- 有强依赖关系的任务
- 修改同一文件的多个任务
- 需要逐步验证的流程（TDD）
4.9 Systematic Debugging — 系统化调试
触发条件：当遇到 Bug 或异常行为需要定位根因时
核心目标：用科学方法定位 Bug 根因，而不是随机试错
核心方法 — 根因追踪（root-cause-tracing.md）：
1. 观察症状 → 精确描述错误现象
2. 形成假设 → 最可能的原因是什么
3. 设计实验 → 怎么验证这个假设
4. 执行实验 → 观察结果
5. 更新认知 → 假设成立？继续。不成立？新假设。
6. 重复直到找到根因
纵深防御（defense-in-depth.md）：
调试不只是修一个 Bug，而是在多个层面防止同类问题复发：
- 修复当前 Bug → 添加测试 → 添加监控 → 改进流程
辅助工具：
| 工具 | 用途 |
|---|---|
find-polluter.sh |
找到污染测试环境的罪魁祸首 |
| 条件等待机制 | 处理异步/时序相关的 Bug |
| 测试压力验证 | 在压力条件下复现问题 |
4.10 Verification Before Completion — 完成前验证
触发条件：当准备声称工作已完成、准备提交或创建 PR 时
核心目标：没有证据就不允许声称完成
铁律：
没有新鲜的验证证据，就不允许做完成声明
门槛函数：
声称任何状态之前：
1. 识别：什么命令能证明这个声明？
2. 执行：运行完整命令（新鲜的、完整的）
3. 阅读：完整输出，检查退出码，统计失败数
4. 验证：输出是否确认声明？
- 否 → 拿证据说明实际状态
- 是 → 带着证据做出声明
5. 然后才能：说出"完成"
常见错误对照：
| 声称 | 需要的证据 | 不够的证据 |
|---|---|---|
| 测试通过了 | 测试命令输出：0 失败 | “上次跑过了” |
| 代码检查通过 | Linter 输出：0 错误 | 部分检查、推测 |
| 构建成功 | 构建命令：退出码 0 | Linter 过了、日志看着不错 |
| Bug 修好了 | 原始症状测试：通过 | 代码改了，“应该修了” |
危险信号：
- 用了"应该"、“大概”、“看起来”
- 在验证前表达满意（“太好了！”、“完美！”）
- 信任代理的成功报告
- 依赖部分验证
来自 24 次失败记忆的教训：用户说过"我不信你" —— 信任一旦打破就很难修复。
4.11 Finishing a Development Branch — 完成开发分支
触发条件：当功能分支开发完成，准备合并时
核心目标：在合并前做最后的质量把关
检查清单：
1. 所有测试通过 → 运行完整测试套件
2. 代码审查完成 → 审查意见已处理
3. 文档已更新 → README、API 文档等
4. 迁移已处理 → 数据库迁移等
5. 变更日志已更新 → 记录了本次变更
6. 合并策略确认 → squash / merge / rebase
4.12 补充技能
Using Git Worktrees — 使用 Git 工作树
在多个分支间并行工作而不互相干扰的技术。
Writing Skills — 编写技能（元技能）
这是最独特的技能 —— 一个教你如何编写新 Skill 的 Skill。
核心参考文档：
anthropic-best-practices.md— Anthropic 官方的 Skill 编写最佳实践persuasion-principles.md— 如何让 AI 更好地遵循 Skill 指令testing-skills-with-subagents.md— 用子代理测试 Skillexamples/— 实际示例
Using Superpowers — 使用指南
总览性技能，说明如何组合使用所有其他技能，以及不同 AI 工具的能力对照。
5. 完整工作流：从想法到交付
推荐的端到端流程
💡 需求想法
│
▼
┌─────────────────────┐
│ 1. Brainstorming │ ← 发散思维，探索方案
│ 头脑风暴 │
└─────────┬───────────┘
│ 输出：设计方案
▼
┌─────────────────────┐
│ 2. Writing Plans │ ← 拆解为可执行步骤
│ 编写计划 │
└─────────┬───────────┘
│ 输出：实施计划
▼
┌─────────────────────┐
│ 3. Executing Plans │ ← 按部就班执行
│ 执行计划 │ ↕ 交替使用
│ + TDD │ ← 先测试再实现
│ 测试驱动开发 │
└─────────┬───────────┘
│ 执行中遇到 Bug？
▼
┌─────────────────────┐
│ Systematic Debugging│ ← 科学方法定位根因
│ 系统化调试 │
└─────────┬───────────┘
│ 任务可并行？
▼
┌─────────────────────┐
│ Subagent-Driven │ ← 拆分子代理并行执行
│ Development │
│ + Parallel Agents │
└─────────┬───────────┘
│ 实现完成
▼
┌─────────────────────┐
│ 4. Verification │ ← 拿证据说话，不允许"应该行"
│ 完成前验证 │
└─────────┬───────────┘
│ 验证通过
▼
┌─────────────────────┐
│ 5. Code Review │ ← 请求审查 + 接收审查
│ 代码审查 │
└─────────┬───────────┘
│ 审查通过
▼
┌─────────────────────┐
│ 6. Finish Branch │ ← 最终检查、合并
│ 完成分支 │
└─────────┬───────────┘
│
▼
✅ 交付
工作流组合示例
场景 1：新功能开发
brainstorming → writing-plans → TDD → verification → code-review → finish-branch
场景 2：Bug 修复
systematic-debugging → TDD(red-green) → verification → code-review → finish-branch
场景 3：大型功能（可并行）
brainstorming → writing-plans → subagent-driven-dev + parallel-agents → TDD → verification → code-review → finish-branch
6. 编写你自己的 Skill
Skill 编写最佳实践（来自 anthropic-best-practices.md）
好的 Skill 应该：
- 触发条件明确 —
description字段精确描述什么情况下该用 - 步骤可执行 — 不是"考虑一下"，而是"做 X → 做 Y → 做 Z"
- 有禁止清单 — 明确列出不允许做的事
- 有验证标准 — 每一步完成的标准是什么
- 上下文自足 — 不需要外部文档就能理解
来自 persuasion-principles.md 的技巧：
| 技巧 | 说明 |
|---|---|
| 用否定句式 | “不要做 X” 比 “请做 Y” 更有效 |
| 给出反面示例 | 禁止清单 + 正确做法的对照 |
| 强调后果 | “如果跳过验证 = 撒谎” |
| 具体胜于抽象 | “运行测试看到 0 failures” > “确保测试通过” |
| 铁律格式 | 用"NEVER"、"ALWAYS"等绝对词 |
创建一个 Skill 的步骤
1. 创建目录：skills/my-skill/
2. 编写 SKILL.md：
- YAML frontmatter (name + description)
- 概述：这个技能解决什么问题
- 流程：具体的执行步骤
- 规则：什么可以做、什么不可以做
- 示例：正确和错误的对照
3. 添加辅助文件（可选）：
- prompt 模板
- 辅助脚本
- 参考文档
4. 测试：用 testing-skills-with-subagents.md 的方法测试
示例：一个简单的 Skill
---
name: commit-hygiene
description: Use when making a git commit to ensure message quality and staging correctness
---
# Commit Hygiene
## Overview
Every commit tells a story. Make yours worth reading.
## Steps
1. Run `git status` — review what changed
2. Stage ONLY related changes — never `git add -A`
3. Write message in format: `type(scope): description`
4. Verify: `git diff --cached` matches intent
## Rules
- NEVER commit with empty message
- NEVER use `git add .` or `git add -A`
- NEVER include .env, credentials, or secrets
- ALWAYS verify staged changes before committing
## Examples
✅ `feat(auth): add JWT token refresh endpoint`
✅ `fix(csv): handle empty rows in parser`
❌ `update stuff`
❌ `fix bug`
❌ `wip`
7. Hooks 机制
什么是 Hooks
Hooks 是在特定事件发生时自动执行的脚本，用来在技能之外增加自动化行为。
Superpowers 的 Hook 配置
{
"hooks": {
"SessionStart": [
{
"matcher": "startup|clear|compact",
"hooks": [
{
"type": "command",
"command": "run-hook.cmd session-start",
"async": false
}
]
}
]
}
}
这意味着每次 Claude Code 启动、清除上下文或压缩对话时，都会执行 session-start 脚本，确保技能上下文被正确加载。
8. 总结与思考
核心思想回顾
| 维度 | 传统 AI 对话 | Superpowers 方法论 |
|---|---|---|
| 流程 | 随意聊天 | 结构化流水线 |
| 验证 | “我觉得行” | 必须有证据 |
| 审查 | 盲目接受 | 技术性评估 |
| 调试 | 随机试错 | 科学实验法 |
| 开发 | 先写代码再补测试 | 先写测试再写代码 |
| 协作 | 单代理串行 | 多代理并行 |
| 完成标准 | “差不多了” | 验证清单全部通过 |
哲学层面
Superpowers 的核心不是某个具体技能，而是一种工程态度：
- 诚实 — 不确定的就说不确定，不表演自信
- 严谨 — 每一步都有证据支撑
- 结构化 — 用流程代替直觉
- 可组合 — 小模块拼接成大系统
适合谁用？
| 角色 | 收益 |
|---|---|
| 个人开发者 | 获得一个严格遵循工程方法的 AI 结对编程伙伴 |
| 技术团队 | 统一团队的 AI 辅助开发规范 |
| 学生 | 学习真正的软件工程方法论，而不只是语法 |
| 开源维护者 | 提高 PR 质量标准 |
推荐学习路径
初学者路径：
using-superpowers → brainstorming → writing-plans → TDD → verification
进阶路径：
executing-plans → code-review → systematic-debugging
高级路径：
subagent-driven-dev → parallel-agents → writing-skills → 自定义 Skill
课件基于 GitHub 仓库 obra/superpowers 整理
20万+ Stars 的背后，是社区对"让 AI 像工程师一样工作"这一理念的认可
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
4
0- 0
已为社区贡献1条内容
所有评论(0)