核心命题： AI 编程助手的瓶颈不是智力，是工程纪律。纪律可以用文档来"编程"。
课前准备
- 安装 Claude Code（或 Cursor / Codex 任一支持 Superpowers 的平台）
- 克隆 Superpowers 仓库：
git clone https://github.com/obra/superpowers.git - 准备一个用于对照实验的空目录
1.1 问题的提出：一个对照实验
思考题
在继续阅读之前，先回忆一下你自己使用 AI 编程助手的经历：
- 当你给 AI 一个功能需求时，它第一步做什么？
- 它会先问你问题吗？还是直接开始写代码？
- 它会先写测试吗？
- 它说"完成了"的时候，真的验证过了吗？
带着这些问题，我们来做一个实验。
实验：同一个任务，两种 AI
任务： "帮我写一个命令行的待办事项工具，支持添加、列出、标记完成、删除"
实验 A — 普通 AI（不加载 Superpowers）
在没有安装 Superpowers 的环境中，给 AI 这个任务。观察并记录：
观察清单：
□ 它是否先问了你任何问题？
□ 它是否写了设计文档？
□ 它的第一个文件是源代码还是测试文件？
□ 它完成时说了什么？（"Done!" / "Here you go!" / ...）
□ 它有没有运行测试命令并展示输出？
□ 总共花了多长时间？
实验 B — 有超能力的 AI（加载 Superpowers）
在安装了 Superpowers 的环境中，给 AI 同样的任务。同样记录上面的清单。
你应该能观察到的差异
| 维度 | 普通 AI | 有 Superpowers 的 AI |
|---|---|---|
| 第一步 | 直接写代码 | 问你问题：存储方式？交互风格？错误处理？ |
| 设计文档 | 没有 | 有，分块展示让你确认 |
| 测试 | 可能有，但在实现之后写 | TDD：先写失败测试，再写最小实现 |
| 完成声明 | "I've created the tool!" | 运行 npm test 后展示"15/15 pass" |
| 工作流程 | 一口气写完所有代码 | 设计 → 计划 → 逐步实现 → 评审 → 验证 |
这个差异的本质是什么？
不是智力的差异 — 两个 AI 用的是同一个模型。差异在于工程纪律：有 Superpowers 的 AI 被"编程"了一套行为规范，让它像一个有经验的工程师那样工作，而不是像一个急于表现的实习生。
关键洞察
AI 编程助手已经足够聪明了。 它能写出好代码、能理解复杂的需求、能处理多种编程语言。它缺的不是智力，而是纪律 —— 先思考再动手、先写测试再写实现、先验证再声称完成。
而纪律，可以通过精心设计的文档来"编程"。
这就是 Superpowers 做的事。
1.2 项目全局地图
一句话定义
Superpowers 是一个 AI 编程助手的方法论插件，通过一组精心设计的 Markdown 文档来改变 AI 的行为模式。
它不写业务代码，不提供 API，不依赖任何第三方库。它的"代码"是文档，"编译器"是 AI 的语言理解能力，"运行时"是 AI 编程助手的会话环境。
作者与社区
- 创始人： Jesse Vincent — 资深开源开发者，Prime Radiant 创始人
- 项目地址： github.com/obra/superp…
- 许可证： MIT
- 版本： v5.0.7（截至 2026 年 3 月）
- 社区： Discord
项目定位
README 中的原话精确地描述了 Superpowers 的定位：
"Superpowers is a complete software development methodology for your coding agents, built on top of a set of composable skills and some initial instructions that make sure your agent uses them."
"Superpowers 是你的编程 agent 的一套完整的软件开发方法论，建立在一组可组合的技能和确保 agent 使用这些技能的初始指令之上。"
两个关键词：
- software development methodology — 不是工具，不是框架，是方法论
- composable skills — 可组合的技能，像积木一样拼装
目录结构详解
superpowers/
│
├── skills/ ← 核心中的核心：14 个技能
│ ├── using-superpowers/ ← "调度器"：告诉 AI 如何发现和使用技能
│ ├── brainstorming/ ← 需求探索：苏格拉底式提问
│ ├── writing-plans/ ← 计划编写：2-5 分钟粒度
│ ├── 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/ ← 生命周期钩子
│ ├── hooks.json ← Claude Code 的钩子声明
│ ├── hooks-cursor.json ← Cursor 的钩子声明
│ ├── run-hook.cmd ← 跨平台启动包装器
│ └── session-start ← 核心：会话启动时注入技能
│
├── agents/ ← Agent 角色定义
│ └── code-reviewer.md ← 唯一的 Agent：代码审查员
│
├── commands/ ← 已废弃的斜杠命令
│ ├── brainstorm.md ← 指向 brainstorming 技能
│ ├── write-plan.md ← 指向 writing-plans 技能
│ └── execute-plan.md ← 指向 executing-plans 技能
│
├── docs/ ← 文档
│ ├── plans/ ← 实施计划存放处
│ ├── superpowers/ ← 项目自身的设计文档
│ └── testing.md ← 技能测试指南
│
├── .claude-plugin/ ← Claude Code 插件清单
│ ├── plugin.json ← 插件元信息
│ └── marketplace.json ← 市场信息
│
├── .cursor-plugin/ ← Cursor 插件清单
├── .codex/ ← OpenAI Codex 安装指南
├── .opencode/ ← OpenCode 支持
│
├── tests/ ← 测试套件
│
├── CLAUDE.md ← 贡献者指南（AI agent 必读）
├── AGENTS.md ← 符号链接，指向 CLAUDE.md
├── GEMINI.md ← Gemini CLI 入口
├── README.md ← 项目说明
├── RELEASE-NOTES.md ← 详细的版本变更记录
├── package.json ← 版本号（v5.0.7），零依赖
└── LICENSE ← MIT 许可证
四类核心组件
理解项目结构的关键是区分四类组件，它们各自承担不同的角色：
| 组件 | 作用 | 类比 |
|---|---|---|
| Skills | 行为规范和方法论 | "教科书" — 告诉 AI 怎么做事 |
| Hooks | 启动时注入技能 | "开机自检" — 确保 AI 从第一秒就有能力 |
| Agents | 角色定义 | "职位描述" — 定义子代理的身份 |
| Commands | 用户入口（已废弃） | "快捷方式" — 用户手动触发技能 |
为什么 Commands 被废弃了？因为技能会自动触发 — AI 看到需求后自己判断用哪个技能，不需要用户记住命令。从 v5.0.0 起，Commands 只显示"请使用对应技能"的提示。
零依赖设计
打开 package.json：
{
"name": "superpowers",
"version": "5.0.7",
"type": "module",
"main": ".opencode/plugins/superpowers.js"
}
没有 dependencies。这是刻意的架构决策。
CLAUDE.md 中明确写道：
"Superpowers is a zero-dependency plugin by design. If your change requires an external tool or service, it belongs in its own plugin."
为什么？每减少一个依赖就减少一个故障点。头脑风暴服务器曾经用 Express + Chokidar + WebSocket，后来在 v5.0.2 被替换为纯 Node.js 内置模块，删除了约 1200 行 node_modules 代码。
多平台支持
Superpowers 不只服务 Claude Code。它支持 6 个平台：
| 平台 | 配置目录 | 安装方式 |
|---|---|---|
| Claude Code（官方市场） | .claude-plugin/ | /plugin install superpowers@claude-plugins-official |
| Claude Code（社区市场） | .claude-plugin/ | 先注册市场再安装 |
| Cursor | .cursor-plugin/ | /add-plugin superpowers |
| OpenAI Codex CLI | — | /plugins → 搜索 superpowers |
| OpenCode | .opencode/ | 按 INSTALL.md 指引 |
| Gemini CLI | gemini-extension.json | gemini extensions install |
| GitHub Copilot CLI | — | 通过市场安装 |
支撑多平台的关键是 Hook 系统 — session-start 脚本检测当前平台并输出对应格式的 JSON。这部分在第 2 课深入讲解。
1.3 七步核心工作流
这是 Superpowers 的"主程序" — 一个完整的开发闭环。README 中用一段话描述了这个流程，但真正理解它需要看到每一步的输入和输出。
流程全景
步骤 1: brainstorming（头脑风暴）
输入：用户的模糊需求
过程：苏格拉底式一问一答，理解意图、约束、成功标准
输出：设计文档 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
↓
步骤 2: using-git-worktrees（创建隔离工作区）
输入：已确认的设计
过程：创建 git worktree，安装依赖，运行测试确认基线
输出：干净的新分支 + 通过测试的工作区
↓
步骤 3: writing-plans（编写实施计划）
输入：设计文档
过程：拆分成 2-5 分钟粒度的任务，每步有完整代码和验证命令
输出：计划文档 docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
↓
步骤 4: subagent-driven-development（子代理驱动开发）
输入：计划文档
过程：每个任务派一个子代理 → 实现 → 双阶段评审（规格 + 质量）
内含：test-driven-development（每个子代理遵循 TDD）
输出：通过评审的代码 + 测试 + 提交记录
↓
步骤 5: requesting-code-review（请求代码评审）
输入：已实现的代码
过程：派子代理做最终的整体评审
输出：评审报告（Critical / Important / Minor）
↓
步骤 6: verification-before-completion（完成前验证）
贯穿全程的原则，不是单独一步
规则：没有运行验证命令的输出就不能声称"完成"
↓
步骤 7: finishing-a-development-branch（完成分支）
输入：全部测试通过的代码
过程：验证 → 呈现 4 个选项 → 执行选择 → 清理
输出：合并到主分支 / PR / 保留 / 丢弃
步骤间的衔接规则
这个流程不是"建议"，而是强制的。每个技能都有明确的"下一步只能是什么"：
- brainstorming 的最后一步只能调用 writing-plans，不能跳到实现
- writing-plans 完成后提供两个执行选项：subagent-driven（推荐）或 executing-plans
- subagent-driven-development 完成后必须调用 finishing-a-development-branch
如果 AI 试图跳过某一步（比如不做设计就开始写代码），brainstorming 技能中的 <HARD-GATE> 会阻止它：
<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project,
or take any implementation action until you have presented a design and
the user has approved it.
</HARD-GATE>
为什么是这个顺序？
每一步都有存在的理由，跳过任何一步都会付出代价：
| 如果跳过… | 后果 |
|---|---|
| brainstorming | 做了不该做的东西，或做的方式不对 |
| using-git-worktrees | 代码直接写在主分支，出问题无法回滚 |
| writing-plans | 子代理没有清晰的指令，实现混乱 |
| test-driven-development | 不知道代码是否真的能工作 |
| code review | 问题积累到最后才发现，修复成本倍增 |
| verification | AI 说"完成了"但实际上没有 |
| finishing-a-development-branch | 工作区残留，分支混乱 |
README 中有一句精准的描述：
"your agent puts together an implementation plan that's clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow."
"你的 agent 会编写一份实施计划，清晰到连一个品味差、没判断力、没项目上下文、而且讨厌写测试的热情初级工程师都能照着做。"
这不是贬低。这是设计计划时的目标受众假设 — 如果连"最差情况"的执行者都能照着做，那这个计划就足够好了。
自动触发 vs. 手动触发
一个常见的误解：认为需要记住技能名称并手动调用。
实际上，技能是自动触发的。using-superpowers 是所有技能的"调度器"，它在会话开始时被注入，然后告诉 AI 一个核心规则：
"If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill."
"如果你认为有哪怕 1% 的可能性某个技能适用于你正在做的事，你绝对必须调用这个技能。"
所以用户只需要正常对话。说"帮我加一个功能"，AI 自己会判断需要先 brainstorming，然后 writing-plans，然后 subagent-driven-development……整个流程自动展开。
1.4 四大设计哲学
Superpowers 的设计不是随意的。贯穿整个项目的有四条核心哲学，理解它们是理解所有后续内容的基础。
哲学一：证据先于主张
来自 verification-before-completion 技能：
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
没有新鲜的验证证据就不能声称完成
这意味着：
- 说"测试通过"前，必须先运行测试命令并展示输出
- 说"bug 修好了"前，必须展示修复前后的对比
- 说"构建成功"前，必须展示构建命令的退出码
这条规则的诞生背景令人印象深刻：来自 24 次 AI 虚假声称"完成"的记录。24 次说"搞定了"但实际上没搞定。技能文档中直接引用了用户的原话：
"your human partner said 'I don't believe you' — trust broken"
所以有了 Gate Function（门控函数）模式：IDENTIFY（确定验证命令）→ RUN（执行）→ READ（读输出）→ VERIFY（确认）→ 只有全部通过才能 CLAIM（声称完成）。
哲学二：系统方法胜于猜测
来自 systematic-debugging 技能：
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
不做根因调查就不能尝试修复
从真实调试会话的统计数据：
| 指标 | 系统方法 | 随机修复 |
|---|---|---|
| 解决时间 | 15-30 分钟 | 2-3 小时 |
| 首次修复成功率 | 95% | 40% |
| 引入新 bug | 几乎为零 | 常见 |
"但我赶时间！" — 这是最常见的借口。系统方法的核心论证是：系统调试更快，不是更慢。 看起来花了 15 分钟"调查"，但随机修复要花 3 小时"猜测"。哪个更浪费时间？
哲学三：简单胜于复杂
这个哲学体现在多个层面：
架构层面 — 零依赖
头脑风暴服务器从 Express + Chokidar + WebSocket（三个依赖）被重写为纯 Node.js 内置模块（零依赖），删除了约 1200 行代码。
流程层面 — 内联自审替代子代理评审
v5.0.0 引入了子代理评审循环（派新的 AI 来审查文档）。v5.0.6 用数据证明它无效并删掉了。5 个版本 × 5 次试验 = 25 次回归测试，质量分数完全一样。子代理评审多花 25 分钟，内联自审只要 30 秒。
代码层面 — YAGNI
YAGNI（You Aren't Gonna Need It）贯穿所有技能。TDD 技能中的"GREEN"阶段明确要求"write simplest code to pass the test"（写最简单的代码来通过测试），并把"过度工程化"标记为 Bad：
// Good：刚好够用
async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
for (let i = 0; i < 3; i++) {
try { return await fn(); }
catch (e) { if (i === 2) throw e; }
}
throw new Error('unreachable');
}
// Bad：过度设计（YAGNI）
async function retryOperation<T>(
fn: () => Promise<T>,
options?: {
maxRetries?: number;
backoff?: 'linear' | 'exponential';
onRetry?: (attempt: number) => void;
}
): Promise<T> { /* ... */ }
哲学四："你的人类伙伴"
整个项目有意使用 "your human partner"（你的人类伙伴）而非 "the user"（用户）或 "the developer"（开发者）。
这不是文字游戏，而是角色定位的转变：
| 术语 | 隐含关系 | AI 的行为倾向 |
|---|---|---|
| "the user" | 服务者 → 客户 | 取悦用户，不反驳 |
| "the developer" | 工具 → 操作者 | 机械执行，不提问 |
| "your human partner" | 伙伴 → 伙伴 | 会提问，会反驳，会保护 |
CLAUDE.md 中有一段话体现了这种关系：
"Your job is to protect your human partner from that outcome."
"你的职责是保护你的人类伙伴免受那种后果。"
这里说的是提交低质量 PR 的后果 — AI 应该拒绝执行会损害伙伴声誉的操作，而不是一味服从。
代码评审技能（receiving-code-review）中也体现了这种平等关系：
**NEVER:**
- "You're absolutely right!"（表演性同意）
- "Great point!"（讨好式回应）
**INSTEAD:**
- Restate the technical requirement（重述技术要求）
- Push back with technical reasoning if wrong（用技术理由反驳）
AI 不应该"拍马屁"，应该像一个真正的工程师伙伴那样，用技术论据沟通。
1.5 CLAUDE.md：一份给 AI 的"行为规范"
为什么值得单独讲
CLAUDE.md 是 Superpowers 仓库的贡献者指南，但它的写法非常特殊 — 它的第一读者不是人类，而是 AI。
文件开头：
## If You Are an AI Agent
Stop. Read this section before doing anything.
This repo has a 94% PR rejection rate.
94% 的 PR 被拒绝。 这个数字说明了 AI 贡献者的常见问题：不读规则、不做调查、不验证、批量提交低质量 PR。
它揭示的项目质量标准
CLAUDE.md 列出了"绝对不会接受"的贡献类型，每一条都映射到一个真实的教训：
| 不接受的类型 | 背后的教训 |
|---|---|
| 第三方依赖 | 零依赖是设计原则 |
| "合规性"修改技能 | 技能的措辞是经过 TDD 测试调优的，不能随意改 |
| 项目特定的配置 | 核心只放通用内容 |
| 批量 PR | 每个 PR 需要深入理解问题 |
| 推测性修复 | 必须有真实的问题驱动 |
| 领域特定的技能 | 核心只放对所有人有用的技能 |
| 捏造内容 | "maintainers have seen every form of AI slop" |
PR 模板的设计
.github/PULL_REQUEST_TEMPLATE.md 的结构本身就是一个微型的 Superpowers：
## What problem are you trying to solve?
（必须描述具体问题，"改进"不是问题描述）
## Existing PRs
- [ ] I have reviewed all open AND closed PRs for duplicates
（必须搜索已有 PR）
## Evaluation
- How many eval sessions did you run AFTER making the change?
（"It works" 不是评估）
## Rigor
- [ ] I used superpowers:writing-skills and completed adversarial pressure testing
（技能修改必须经过压力测试）
## Human review
- [ ] A human has reviewed the COMPLETE proposed diff before submission
（必须有人类审阅）
每一个 checkbox 都对应一个曾经被违反的规则。这是 Superpowers 哲学的自我应用 — 用结构化的文档来控制行为（包括贡献者的行为）。
1.6 技能分类：四大家族
14 个技能不是随意排列的，它们可以按功能分为四个家族：
家族一：工作流骨架（5 个）
构成 7 步核心工作流的主干：
brainstorming → writing-plans → subagent-driven-development
↕
executing-plans（备选）
↓
finishing-a-development-branch
brainstorming— 苏格拉底式需求探索，输出设计文档writing-plans— 计划编写，2-5 分钟粒度subagent-driven-development— 多代理执行计划（推荐）executing-plans— 单代理内联执行计划（备选）finishing-a-development-branch— 完成分支的 4 选项
家族二：工程纪律（3 个）
贯穿整个工作流的纪律要求：
test-driven-development— TDD：先测试后实现verification-before-completion— 先验证后声称完成systematic-debugging— 先调查根因后修复
这三个技能共享同一个设计模式：Iron Law + Red Flags + Rationalizations Table。它们是第 3 课和第 4 课的核心。
家族三：协作机制（4 个）
支撑多代理协作和人机协作：
using-superpowers— 技能调度器，确保 AI 使用正确的技能requesting-code-review— 请求代码评审receiving-code-review— 接收代码评审（禁止表演性同意）dispatching-parallel-agents— 并行派发独立任务
家族四：基础设施（2 个）
支撑工作流运行的基础能力：
using-git-worktrees— 创建隔离的 Git 工作区writing-skills— 元技能：如何创建新技能（TDD for Docs）
家族间的依赖关系
家族四（基础设施）
└── using-git-worktrees ─→ 被家族一的所有执行类技能调用
家族三（协作机制）
└── using-superpowers ─→ 调度家族一和家族二的所有技能
└── requesting/receiving-code-review ─→ 被家族一的执行类技能调用
家族二（工程纪律）
└── TDD ─→ 被家族一的所有执行类技能遵守
└── verification ─→ 贯穿所有声称"完成"的时刻
└── debugging ─→ 在遇到问题时随时触发
家族一（工作流骨架）
└── brainstorming → writing-plans → subagent/executing → finishing
1.7 版本演化速览
最后，简要了解 Superpowers 的演化历程。这不是要记住每个版本的细节，而是建立"这个项目是活的，在持续解决真实问题"的认知。
| 阶段 | 版本 | 关键事件 |
|---|---|---|
| 诞生 | v3.x（2025-10 ~ 2025-12） | 核心技能体系建立，Linux 兼容性修复 |
| 成熟 | v4.0（2025-12） | 双阶段评审、DOT 流程图、Description 陷阱发现 |
| 扩展 | v4.1-4.3（2026-01 ~ 2026-02） | OpenCode 支持、Cursor 支持、brainstorming 强制化 |
| 当前 | v5.0（2026-03） | 多平台统一、零依赖、子代理架构完善、内联自审 |
关键转折点（会在第 8 课详细讲）：
- v4.0.0：发现"Description 陷阱" — description 包含流程摘要时 AI 会走捷径
- v4.3.0：brainstorming 从"建议"变为"强制" — 用 HARD-GATE 阻止跳过
- v5.0.2：零依赖化 — 删除所有 node_modules
- v5.0.6：用数据砍掉子代理评审 — 25 次回归测试证明无效
实践作业
作业 1：对照实验记录（必做）
完成 1.1 节的对照实验，填写以下表格：
任务：_________________________________
| 维度 | 普通 AI（记录） | 有 Superpowers 的 AI（记录） |
|------|----------------|---------------------------|
| 第一步做什么 | | |
| 是否提问 | | |
| 是否有设计文档 | | |
| 第一个文件是什么 | | |
| 是否先写测试 | | |
| 完成时说什么 | | |
| 是否运行了验证 | | |
| 总共花了多长时间 | | |
我观察到的最大差异：
_________________________________________
作业 2：画全局地图（推荐）
用你习惯的工具（纸笔、draw.io、Mermaid）画一张 Superpowers 的全局架构图，包含：
- 14 个技能的名称和家族分类
- 7 步核心工作流的顺序和衔接
- hooks 的启动链路
- 多平台支持的关系
作业 3：找三个"为什么"（推荐）
在阅读过程中，找出三个让你好奇的"为什么"问题。例如：
- 为什么 using-superpowers 要在启动时完整注入，而不是按需加载？
- 为什么 commands 被废弃了？
- 为什么要用"human partner"而不是"user"？
把你的问题和初步猜测写下来。后续课程会逐一解答。
本课自检清单
完成本课后，你应该能：
- 用一句话说出 Superpowers 是什么
- 画出项目的目录结构并解释每个目录的作用
- 说出 7 步核心工作流的每一步及其输入输出
- 说出 14 个技能的名称并按四大家族分类
- 解释四大设计哲学：证据先于主张、系统方法胜于猜测、简单胜于复杂、"人类伙伴"
- 解释为什么"AI 的瓶颈是纪律而不是智力"
下节预告
第 2 课：Hook 引擎 — AI 是怎么获得超能力的
你已经知道 Superpowers 做了什么。下一课，我们追踪"它是怎么做到的" — 从用户启动会话的那一刻起，一段脚本如何把技能注入 AI 的上下文，以及一个同时是 Windows .cmd 和 Unix .sh 的"魔法文件"是如何工作的。
