Superpowers 深度解读

来源：github.com/obra/superpowers · v5.0.7 · 作者 Jesse Vincent (Prime Radiant) 许可证：MIT · 社区 Discord：discord.gg/35wsABTejz

一、它是什么 —— 重新定义 AI 编程代理的工作方式

一句话定位

Superpowers 不是工具集，是一套"可执行的过程规范"。 它通过 14 个精心设计的 Skill，强制 AI 编程代理遵循经过验证的软件工程实践：先设计再编码、先测试再实现、先审查再推进。

与传统 system prompt 的本质区别

维度	system prompt	Superpowers Skill
加载方式	全量注入，永远存在	按需触发，只在相关时加载
体积	越大越好？上下文窗口有限	每个 Skill 独立，frontmatter 控制发现
可组合性	所有规则平铺在一起	Skill 天然可组合，互不干扰
更新成本	改一处影响全局	单个 Skill 独立迭代
抵抗合理化	"AI 会找理由绕过规则"	Skill 内置反合理化条款

核心理念转变：从"告诉 AI 做什么"变成"告诉 AI 什么时候该停下来思考"。

四条基本原则

原则	含义	对应实践
测试驱动	先写测试，永远如此	TDD Skill，删除先于测试写的代码
系统化优于临时	流程胜过猜测	七阶段强制工作流
复杂度缩减	简洁是首要目标	Skill 中明确禁止过度工程
证据优于声明	先验证再宣布成功	验证 Skill，不接受"应该没问题"

二、七阶段强制工作流

Superpowers 定义了一条从"模糊想法"到"可合并代码"的完整流水线：

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ 1.头脑风暴 │───▶│ 2.Worktree │───▶│ 3.编写计划 │───▶│ 4.子代理   │
│  (设计先行) │    │  (隔离分支) │    │  (任务拆解) │    │  (独立执行) │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
                                                       │
┌──────────┐    ┌──────────┐    ┌──────────┐           │
│ 7.完成分支 │◀───│ 6.代码审查 │◀───│ 5.TDD    │◀──────────┘
│  (合并/PR) │    │  (自动触发) │    │  (红绿重构) │
└──────────┘    └──────────┘    └──────────┘

阶段	触发时机	核心机制	设计意图
头脑风暴	写代码之前	提问细化 → 分段展示设计 → 确认后才动手	防止 AI 直接跳入编码
Git Worktree	设计通过后	创建隔离分支 → 项目设置 → 验证测试基线	隔离变更，安全可回退
编写计划	设计确认后	拆为 2-5 分钟任务 → 含文件路径和验证步骤	把模糊设计变成精确指令
子代理执行	计划就绪后	每任务一个子代理 → 两阶段审查	上下文隔离 + 自动质控
TDD	实现过程中	RED → GREEN → REFACTOR 循环	强制纪律，不接受"后补测试"
代码审查	任务之间	对照计划审查 → 关键问题阻断进度	防止偏差累积
完成分支	所有任务完成	验证测试 → 提供 merge/PR/保留/丢弃选项	有序收尾

关键创新点

头脑风暴阶段（设计先行）

Superpowers 拒绝让 AI 直接写代码。即使你说"帮我加个按钮"，它也会先问：这个按钮放哪？什么样式？点击后做什么？只有在你确认设计后才动手。

这种"设计先行"的理念与 SDD 的 No Spec, No Code 异曲同工 —— 不把需求想清楚就不准动手。

子代理执行（上下文隔离）

每个任务分配一个全新的子代理，没有历史上下文污染。子代理只看到当前任务的精确指令，完成后将结果交给审查代理。这种设计解决了长对话中 AI "遗忘前文约束"的经典问题。

三、Skill 系统 —— 方法论的核心载体

Skill 的结构

每个 Skill 是一个独立目录，核心是 SKILL.md：

skills/
├── brainstorming/
│   └── SKILL.md          # 主文件（必需）
├── test-driven-development/
│   └── SKILL.md
├── systematic-debugging/
│   ├── SKILL.md
│   └── root-cause-tracing.md   # 补充参考（可选）
└── ...

SKILL.md 的 YAML frontmatter 是触发机制的关键：

yaml

---
name: test-driven-development
description: Use when writing or modifying any code to enforce strict TDD discipline
---

frontmatter 规范：

description 必须以 "Use when..." 开头，描述触发条件
总长度 ≤ 1024 字符
用第三人称书写（因为会注入到 system prompt）

Skill 触发机制（Claude Search Optimization）

Superpowers 不把所有规则一次性塞进上下文。而是通过精心编写的 description 字段，让 AI 代理在遇到相关场景时主动搜索并调用 Skill：

用户："帮我加一个登录功能"
  → AI 识别到"写代码"意图
  → 搜索 Skill 描述，匹配到 brainstorming
  → 加载 brainstorming SKILL.md
  → 按 Skill 指导开始提问，而不是直接写代码

这种设计被作者称为 Claude Search Optimization (CSO) —— 类似 SEO，但优化对象是 AI 的技能发现能力。

核心 Skill 解读

1. test-driven-development —— TDD 纪律执行器

这是 Superpowers 最核心的 Skill。它不只告诉 AI "要写测试"，而是详细列举了 AI 在压力下会用的所有借口，并逐一封堵：

AI 常见借口	Skill 的回应
"这只是个小改动，不需要测试"	所有代码变更都需要测试，无一例外
"我先写实现，后补测试"	删除先于测试写的代码，从测试开始重来
"测试框架不支持这种场景"	找到测试方式或简化到可测试的程度
"时间紧，先跳过"	TDD 是加速器不是减速器，跳过只会更慢

铁律：代码先于测试写 = 删除重来。

2. systematic-debugging —— 四阶段根因分析

不猜测、不试错。严格遵循：

1. 观察收集 → 复现问题，记录精确错误信息
2. 假设生成 → 基于证据列出可能原因（最多 3 个）
3. 验证排除 → 逐一验证，用最小实验排除假设
4. 修复确认 → 修复后验证，确保没引入新问题

据作者统计，系统性调试将修复时间从 2-3 小时压缩到 15-30 分钟，首次修复率从 40% 提升到 95%。

3. brainstorming —— 苏格拉底式设计推演

写代码前强制进入提问模式：

不展示代码，只展示设计方案
分段展示，每段等待确认
可视化方案通过浏览器 Companion 展示
保存设计文档供后续阶段参考

4. subagent-driven-development —— 自主执行引擎

将实现计划拆成独立任务，每个任务由全新子代理执行：

两阶段审查：先检查规格合规性（做没做对），再检查代码质量（写得好不好）
状态协议：DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT
审查循环：不通过就迭代，直到审查代理批准

Skill 编写本身就是 TDD

Superpowers 对"如何创建新 Skill"有严格要求 —— 没有失败场景，就没有新 Skill：

RED  → 在没有 Skill 的情况下运行压力测试，记录 AI 的合理化借口和失败模式
GREEN → 编写最小 Skill，只解决上述特定合理化
REFACTOR → 封堵漏洞，保持合规

这就是 Skill 体系的"铁律"：NO SKILL WITHOUT A FAILING TEST FIRST。

四、子代理驱动开发 —— 自主工作的关键

为什么需要独立子代理

问题	根因	子代理方案
越改越偏	长对话上下文累积导致遗忘原始需求	每个任务全新上下文，只看到精确指令
改 A 坏 B	AI 对项目全局理解随对话退化	子代理只关注当前任务，减少"顺手改"
审查流于形式	自己审查自己的代码	独立审查代理，对照原始计划逐条验证

两阶段审查机制

子代理完成任务
  │
  ▼
┌─────────────────┐
│ 第一阶段：规格合规 │ ← 对照实现计划逐条检查
│ 做没做对？       │
└────────┬────────┘
         │ 通过
         ▼
┌─────────────────┐
│ 第二阶段：代码质量 │ ← 检查可读性、安全性、性能
│ 写得好不好？     │
└────────┬────────┘
         │
         ▼
    DONE / DONE_WITH_CONCERNS

关键设计： 如果审查不通过，不交给同一个人改 —— 而是把审查反馈作为新的上下文，让新的子代理来修复。这避免了"自己给自己打补丁"的递归退化。

与传统"AI 自主编程"的区别

维度	直接让 AI 干活	Superpowers 子代理模式
任务粒度	"实现登录功能"	"在 auth.ts:42 添加 JWT 验证函数，参数为..."
上下文管理	全部堆在一个对话	每任务独立上下文
质量控制	人工审查（经常跳过）	自动两阶段审查
偏差修正	发现偏了手动拉回来	审查代理自动阻断
工作时长	几十分钟后开始漂移	可持续数小时不偏离

五、与 HCodeFlow SDD 的对比与启示

核心理念对比

维度	HCodeFlow (SDD)	Superpowers
核心产出	Spec（需求文档、架构设计）	Skill（可执行的过程规范）
驱动方式	文档驱动："No Spec, No Code"	流程驱动："先设计 → 再计划 → 后实现"
工作流形态	7 个 Agent 角色协作（PM/Arch/Dev...）	7 个阶段流水线（头脑风暴 → 完成分支）
质量控制	合并检查清单 + 规则引擎	TDD 纪律 + 两阶段自动审查
分发机制	框架升级脚本 → 下游项目	插件市场 → 多平台安装
定制能力	marker 下方可自定义	Skill 可组合但核心不可改

可借鉴的三个方向

1. Skill 级别的精细行为控制

HCodeFlow 的规则文件（project_rule.md）是全局性的，所有规则平铺在一起。Superpowers 的 Skill 机制提供了另一种思路：按场景拆分行为规范，按需加载。

对于 HCodeFlow 的启示：

将 project_rule.md 中的规则按触发场景分组
为不同工作流阶段提供独立的"行为卡片"
减少单次注入的规则量，降低认知负担

2. 子代理 + 自动审查的闭环

HCodeFlow 已经定义了 QA Agent 角色和 merge_checklist，但审查依赖人工触发。Superpowers 的"每个任务自动审查 + 关键问题阻断"机制值得参考：

在 Dev Agent 完成任务后自动触发 QA 审查
审查不通过自动阻断，不允许跳过
审查结果结构化（DONE / CONCERNS / BLOCKED）

3. 反合理化设计（Rationalization Resistance）

这是 Superpowers 最独特的设计理念 —— 在规则中预判 AI 可能的"借口"，并逐一封堵。

HCodeFlow 的规则文件可以这样增强：

markdown

# 当前
- 所有代码变更必须有对应的测试

# 借鉴 Superpowers 后
- 所有代码变更必须有对应的测试
  - AI 可能说"这只是小改动" → 小改动更容易测试，不是跳过的理由
  - AI 可能说"先写实现后补测试" → 不接受后补，从测试开始
  - AI 可能说"框架不支持" → 找到测试方式或简化到可测试

六、安装与快速体验

安装方式

Claude Code（推荐）：

bash

# 官方插件市场安装
/plugin install superpowers@claude-plugins-official

其他平台：

平台	安装方式
Cursor	`/add-plugin superpowers`
Copilot CLI	通过 marketplace 安装
OpenCode	从 INSTALL.md 获取安装脚本
Gemini CLI	`gemini extensions install https://github.com/obra/superpowers`

最小验证步骤

安装后，用以下 prompt 触发 Superpowers 工作流：

帮我给项目添加一个配置文件加载功能

预期行为（如果 Superpowers 正常工作）：

AI 不会直接写代码
会先进入头脑风暴阶段，问你一系列问题
确认设计后才创建 Worktree
拆分任务后会走 TDD 流程

如果 AI 直接开始写代码，说明 Skill 没有正确触发 —— 检查插件安装状态。

七、总结

一句话定位

Superpowers 把 AI 编程代理从"热心的初级开发者"变成了"遵守纪律的资深工程师"。

适合什么团队

追求代码质量和工程规范的团队
希望 AI 能长时间自主工作而不偏离计划
需要将 TDD、DRY、YAGNI 等实践固化到 AI 行为中
愿意接受"AI 先问再动手"的工作节奏

不适合什么场景

需要快速原型验证、不在乎代码质量的探索阶段
改一行配置就完事的小修改（流程开销大于收益）
团队尚未接受"设计先行"理念，直接上手会有挫败感

核心收获

Superpowers 最大的价值不在于它的 14 个 Skill 或 7 阶段工作流，而在于它对 AI 行为的深刻理解：

AI 在压力下会合理化 —— 所以规则要预判并封堵借口
AI 在长对话中会漂移 —— 所以每个任务要独立上下文
AI 会跳过"不重要"的步骤 —— 所以关键步骤要强制阻断
AI 会过度工程 —— 所以简洁是首要目标

这些洞察对任何设计 AI 编程工作流的团队都有参考价值。

一、它是什么 —— 重新定义 AI 编程代理的工作方式 ​

一句话定位 ​

与传统 system prompt 的本质区别 ​

四条基本原则 ​

二、七阶段强制工作流 ​

关键创新点 ​

三、Skill 系统 —— 方法论的核心载体 ​

Skill 的结构 ​

Skill 触发机制（Claude Search Optimization） ​

核心 Skill 解读 ​

1. test-driven-development —— TDD 纪律执行器 ​

2. systematic-debugging —— 四阶段根因分析 ​

3. brainstorming —— 苏格拉底式设计推演 ​

4. subagent-driven-development —— 自主执行引擎 ​

Skill 编写本身就是 TDD ​

四、子代理驱动开发 —— 自主工作的关键 ​

为什么需要独立子代理 ​

两阶段审查机制 ​

与传统"AI 自主编程"的区别 ​

五、与 HCodeFlow SDD 的对比与启示 ​

核心理念对比 ​

可借鉴的三个方向 ​

1. Skill 级别的精细行为控制 ​

2. 子代理 + 自动审查的闭环 ​

3. 反合理化设计（Rationalization Resistance） ​

六、安装与快速体验 ​

安装方式 ​

最小验证步骤 ​

七、总结 ​

一句话定位 ​

适合什么团队 ​

不适合什么场景 ​

核心收获 ​

一、它是什么 —— 重新定义 AI 编程代理的工作方式

一句话定位

与传统 system prompt 的本质区别

四条基本原则

二、七阶段强制工作流

关键创新点

三、Skill 系统 —— 方法论的核心载体

Skill 的结构

Skill 触发机制（Claude Search Optimization）

核心 Skill 解读

1. test-driven-development —— TDD 纪律执行器

2. systematic-debugging —— 四阶段根因分析

3. brainstorming —— 苏格拉底式设计推演

4. subagent-driven-development —— 自主执行引擎

Skill 编写本身就是 TDD

四、子代理驱动开发 —— 自主工作的关键

为什么需要独立子代理

两阶段审查机制

与传统"AI 自主编程"的区别

五、与 HCodeFlow SDD 的对比与启示

核心理念对比

可借鉴的三个方向

1. Skill 级别的精细行为控制

2. 子代理 + 自动审查的闭环

3. 反合理化设计（Rationalization Resistance）

六、安装与快速体验

安装方式

最小验证步骤

七、总结

一句话定位

适合什么团队

不适合什么场景

核心收获