Superpowers：给 AI 编程助手装上工程纪律

AI 编程助手最容易出问题的地方，不是不会写代码，而是太急着写代码。

你说“加个登录页”，它马上改文件。你说“修个 bug”，它先猜原因。你说“这个功能简单”，它也相信了。最后代码看起来跑了，但需求没想清楚、测试没补上、边界没验证。

Superpowers 要解决的就是这个问题：把成熟工程师会做的步骤，变成 AI agent 必须遵守的工作流。

它不是一个神奇 prompt，也不是让模型“更聪明”的插件。它更像一套团队规章：动手前先澄清，写代码前先计划，实现前先写测试，结束前必须验证。

Superpowers 是什么

Superpowers 是 Jesse Vincent 和 Prime Radiant 团队维护的开源项目。项目地址是 https://github.com/obra/superpowers。

它给 Claude Code、Codex、Cursor、Gemini CLI、OpenCode、GitHub Copilot CLI 等编程助手提供一组可组合的 skills。这些 skills 会在合适的任务里自动触发，约束 agent 按工程流程工作。

核心思想很简单：

不要让 AI 直接写代码。先让它把问题想清楚，再让它按可验证的步骤执行。

Superpowers 的 README 把它定义为一套完整的软件开发方法论，建立在 composable skills 和初始指令之上。重点不是“多一个工具”，而是“让 agent 形成一套固定的工作习惯”。

它改变了什么

没有 Superpowers 时，你和 AI 编程助手的协作经常像这样：

• 你描述一个功能
• agent 直接改代码
• 你发现方向不对
• agent 再补测试
• 你继续指出遗漏
• 最后谁也不确定改动是否完整

Superpowers 把流程倒过来：

• brainstorming：先问清楚你到底要什么
• writing-plans：把设计拆成可执行的小任务
• test-driven-development：先写失败测试，再写实现
• systematic-debugging：遇到 bug 时找根因，不靠猜
• requesting-code-review：完成后先自查，再交给你看
• finishing-a-development-branch：收尾时验证、整理、决定合并方式

这套流程听起来慢，但在真实项目里通常更省时间。因为最贵的不是多问两个问题，而是半小时后发现方向错了。

适合什么场景

Superpowers 最适合三类工作。

第一类：需求还没完全想清楚的功能开发。

比如“做一个导入功能”“加一个仪表盘”“重构设置页”。这些请求看起来明确，实际有很多隐藏决策：数据从哪里来、失败怎么处理、权限怎么限制、老用户会不会受影响。

Superpowers 会先触发 brainstorming，让 agent 把这些问题问出来。

第二类：需要稳定性的代码修改。

只要你在改业务逻辑、修 bug、重构模块，就会碰到回归风险。Superpowers 的 TDD skill 会强制先写测试，看到测试失败，再写最小实现。

这不是仪式感。测试先失败，才能证明它真的抓住了问题。

第三类：多人或多 agent 协作。

Superpowers 里有 writing-plans、executing-plans、dispatching-parallel-agents、subagent-driven-development 等协作 skills。它们的价值是把“大任务”切成“小任务”，让每一步都有检查点。

当你让 agent 连续工作一两个小时，这种结构很重要。没有结构，长任务会慢慢偏离原本目标。

不适合什么场景

Superpowers 也不是所有事情都该用。

如果你只是让 agent 查一个命令、改一个错别字、生成一段临时代码，它的完整流程会显得重。

如果你的团队明确不想用 TDD，Superpowers 的默认习惯会和团队文化冲突。它的技能里有很强的流程约束，尤其是 test-driven-development。你需要先决定：要的是速度感，还是可验证的稳定性。

还有一点容易忽略：Superpowers 不是替你做产品判断。它会帮 agent 提问、拆解和验证，但最终需求边界还是要你拍板。你不能把一个含糊的想法丢给它，然后期待它自动变成正确产品。

安装方式

Superpowers 支持多个编程环境。不同环境的安装方式不一样。

Claude Code 可以从官方插件市场安装：

/plugin install superpowers@claude-plugins-official

也可以先添加 Superpowers marketplace：

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

Codex CLI 和 Codex App 可以从官方 Codex 插件市场安装。Codex CLI 中打开插件界面：

/plugins

搜索 Superpowers，然后选择安装。

Codex App 中，在侧边栏打开 Plugins，在 Coding 分类里找到 Superpowers，点击加号安装。

如果你使用 Codex 的原生 skill discovery，也可以按项目提供的方式手动安装：

git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
mkdir -p ~/.agents/skills
ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers

然后重启 Codex，让它重新发现 skills。

Gemini CLI 的安装命令是：

gemini extensions install https://github.com/obra/superpowers

更新时运行：

gemini extensions update superpowers

快速上手

安装后，你不用记住每个 skill 怎么调用。Superpowers 的目标就是让相关技能自动触发。

最简单的试法是给 agent 一个真实但不大的任务：

给这个项目增加一个导入 CSV 的功能。先和我确认需求，不要直接写代码。

如果 Superpowers 正常工作，agent 不应该马上改文件。它会先进入 brainstorming，问你导入格式、错误处理、重复数据、权限、结果展示等问题。

等设计清楚后，它会写计划。计划会把任务拆成几分钟能完成的小步骤，包含文件路径、测试方式和验证方法。

进入实现时，TDD skill 会要求先写失败测试。你会看到类似这样的节奏：

yarn test path/to/import.test.ts

测试失败后，agent 才写最小实现。测试通过后，再重构。

这就是 Superpowers 的核心体验：少一点“我觉得可以”，多一点“我已经验证过”。

实战流程：让 Agent 做一个 CSV 导入功能

下面用一个完整例子串起来：给后台增加“导入用户 CSV”的功能。

目标不是展示某个框架的代码，而是看 Superpowers 在每个阶段怎么介入。你可以把 CSV 换成支付回调、数据导出、权限改造、设置页重构，流程基本一样。

阶段一：启动和技能检查

用到的 skill：using-superpowers

这个阶段发生在会话开始时。它的作用是提醒 agent：做任务前先检查有没有相关 skill，不能凭感觉直接开干。

你不需要手动调用它。安装成功后，agent 会在处理任务前检查技能列表。

你可以这样开始：

给后台增加用户 CSV 导入功能。导入字段包括 email、name、role。
先不要写代码，先确认需求和边界。

如果 Superpowers 正常工作，agent 的第一反应不应该是打开文件，而是进入需求澄清。

你要观察的是：它有没有主动说“我会先使用 brainstorming”，或者至少开始提问。如果它直接改代码，可以明确打断：

先使用 Superpowers 的 brainstorming 流程，不要直接实现。

阶段二：需求澄清

用到的 skill：brainstorming

brainstorming 的用途不是聊天，而是把模糊需求变成可实现的设计。

在 CSV 导入这个例子里，它通常会问：

• CSV 第一行是否必须是表头
• email 重复时是跳过、覆盖，还是报错
• role 只能取哪些值
• 单次导入数量有没有限制
• 导入失败时是否允许部分成功
• 管理员从哪里看到导入结果
• 是否需要下载错误行报告

你要做的是逐项拍板。不要急着让 agent 写代码。

一个可落地的回答可以这样写：

规则如下：
- 第一行必须是表头
- email 必填且不能重复
- role 只允许 admin、member
- 单次最多 1000 行
- 允许部分成功
- 失败行要返回行号和错误原因
- 暂时不做错误报告下载

brainstorming 的输出应该是一份设计草案。它会分段给你确认，而不是一次甩出一大篇。

你可以继续追问：

把“不做”的范围也列出来，避免实现时越界。

这一步很重要。Superpowers 强调 YAGNI，不需要的功能不要顺手做。

阶段三：隔离工作区

用到的 skill：using-git-worktrees

设计确认后，Superpowers 会建议创建独立工作区和分支。

用途很直接：避免 agent 在当前工作树里把未完成代码、用户改动和实验代码混在一起。

你可以让它执行：

设计确认了。使用 git worktree 创建独立分支来实现。

agent 应该做几件事：

• 检查当前 git 状态
• 创建新分支，比如 feature/csv-import
• 创建 worktree
• 进入新工作区
• 跑一次现有测试，确认基线是干净的

如果项目很小，你也可以不启用 worktree，但要明确告诉 agent：

这个改动很小，不创建 worktree。继续在当前分支实现，但先检查 git status。

worktree 不是仪式。它解决的是隔离问题。长任务、多 agent、风险较高的重构，值得用。

阶段四：写实施计划

用到的 skill：writing-plans

writing-plans 把设计变成可执行计划。好的计划不是“实现导入功能”这种大块任务，而是几分钟能完成的小步骤。

Superpowers 要求计划里写清楚：

• 要改哪些文件
• 每一步做什么
• 先写哪个测试
• 运行什么命令验证
• 完成标准是什么

你可以这样触发：

根据刚才确认的设计，写一个实施计划。每个任务控制在 2-5 分钟内，包含测试和验证步骤。

一个合理的计划会长这样：

• 新增 CSV 解析测试，覆盖空文件、缺字段、重复 email
• 新增 importUsers 服务的失败测试
• 实现最小 CSV 解析逻辑
• 实现 role 校验和行级错误返回
• 接入后台 API 路由
• 给页面增加上传入口和结果展示
• 跑单元测试、类型检查和端到端手动验证

你要重点检查三件事：

• 有没有把未知需求写成已确认事实
• 有没有顺手加“下载报告”“导入历史”这类未确认功能
• 每一步是否都有验证方式

如果计划太粗，直接要求重写：

这个计划太粗。把每一步拆到可以独立测试和提交的粒度。

阶段五：选择执行方式

用到的 skill：executing-plans 或 subagent-driven-development

计划确认后，有两种执行方式。

executing-plans 适合你想保持人工检查点的任务。agent 会按批次执行，做完一段停下来让你看。

你可以这样说：

按计划执行。每完成两个任务停下来汇报一次，不要连续做完整个功能。

subagent-driven-development 适合任务更大、可以拆给多个子 agent 的场景。它会让子 agent 执行任务，再做两阶段审查：先看是否符合规格，再看代码质量。

你可以这样说：

这个任务可以用 subagent-driven-development。每个子任务完成后都做规格审查和代码质量审查。

怎么选？

场景	建议方式
小功能、你想盯紧过程	executing-plans
中大型功能、任务边界清楚	subagent-driven-development
多个独立模块可并行	dispatching-parallel-agents
你还没完全信任 agent	executing-plans

如果你第一次用 Superpowers，建议先用 executing-plans。它慢一点，但你更容易看清每一步发生了什么。

阶段六：测试驱动实现

用到的 skill：test-driven-development

这是 Superpowers 最强硬的部分。

它要求 agent 按 RED-GREEN-REFACTOR 做：

• RED：先写失败测试
• GREEN：写最小实现让测试通过
• REFACTOR：在测试保护下整理代码

对于 CSV 导入，第一步不应该是写 parser，而是写失败测试：

先为“空 CSV 返回错误”写失败测试。运行测试，确认它确实失败后再实现。

你要看 agent 有没有真的运行测试。只写测试但不运行，不算 RED。

一个正常节奏是：

yarn test src/server/importUsers.test.ts

测试失败后，再实现最小逻辑：

现在只实现空 CSV 校验，让刚才这个测试通过。不要顺手实现其他规则。

然后继续下一个用例：

• 缺少 email 列
• role 不是 admin 或 member
• 同一个文件里 email 重复
• 部分成功时返回成功数量和失败行

每个行为都先有失败测试，再有实现。

Superpowers 会反对“先写一大坨实现，再补测试”。如果 agent 已经写了实现但没有测试，严格的 TDD 流程会要求删除或回退未测试代码，再从测试开始。

阶段七：遇到 bug 时找根因

用到的 skill：systematic-debugging

假设导入时有个测试偶发失败：本地通过，CI 失败。

普通 agent 容易开始猜：加等待、改超时、换 mock。systematic-debugging 会强制按四阶段走：

• 复现问题
• 找到具体失败条件
• 追踪根因
• 加防护，避免同类问题再发生

你可以这样触发：

这个测试在 CI 上偶发失败。使用 systematic-debugging，不要猜原因。先收集证据。

好的调试过程会包括：

• 对比本地和 CI 的 Node 版本、时区、文件编码
• 打印失败输入，而不是只看错误消息
• 找到是否依赖对象遍历顺序、系统换行符或异步时序
• 用更稳定的断言替代脆弱断言

它的价值在于防止“修了症状，根因还在”。

阶段八：完成前验证

用到的 skill：verification-before-completion

很多 agent 会在代码改完后说“应该可以了”。Superpowers 不接受“应该”。

verification-before-completion 的用途是逼 agent 给证据。

你可以要求：

在宣布完成前，执行 verification-before-completion。列出你实际运行过的命令和结果。

对于 CSV 导入，验证至少应包括：

• 单元测试通过
• 类型检查通过
• lint 或格式化检查通过
• 手动上传一个正常 CSV
• 手动上传一个包含错误行的 CSV
• 确认页面展示成功数和错误原因

如果某个验证没跑，agent 必须说没跑，而不是含糊带过。

阶段九：代码审查

用到的 skill：requesting-code-review 和 receiving-code-review

requesting-code-review 用于 agent 自查或请另一个审查者检查。它不只看代码能不能跑，还看是否符合计划、有没有过度实现、有没有风险。

你可以这样说：

实现完成后，先做 requesting-code-review。按严重程度列出问题，critical 问题必须先修。

审查应该覆盖：

• 是否严格实现了已确认范围
• 是否有未测试分支
• 是否吞掉错误
• 是否把 CSV 内容直接信任为安全输入
• 是否影响现有用户管理逻辑

如果审查给出反馈，receiving-code-review 会指导 agent 逐条处理：

根据 review feedback 修复问题。每条反馈都说明处理方式，不能静默跳过。

这个阶段的重点不是“找茬”，而是防止 agent 自信地把半成品交付给你。

阶段十：收尾和合并

用到的 skill：finishing-a-development-branch

任务完成后，finishing-a-development-branch 负责收尾。

它会做这些事：

• 重新运行关键测试
• 检查 git diff
• 总结变更
• 提供下一步选项：合并、创建 PR、保留分支、丢弃 worktree
• 清理临时工作区

你可以这样触发：

使用 finishing-a-development-branch 收尾。先验证，再给我合并或创建 PR 的选项。

一个好的收尾报告应该包含：

• 实现了什么
• 没实现什么
• 跑了哪些验证命令
• 还有哪些残余风险
• 当前分支和文件变更状态

这一步让长任务有明确终点。否则 agent 很容易停在“代码改完了”的半路上。

常用触发话术

Superpowers 理想状态下会自动触发，但你可以用更明确的话把 agent 拉回流程。

你想做什么	可以这样说
先澄清需求	先用 brainstorming，不要写代码
写实施计划	用 writing-plans，把任务拆到 2-5 分钟粒度
隔离分支	用 using-git-worktrees 创建独立工作区
按计划执行	用 executing-plans，每完成一批停下来汇报
大任务自动推进	用 subagent-driven-development，并进行两阶段 review
严格 TDD	先用 test-driven-development，必须看到失败测试
调试问题	用 systematic-debugging，先收集证据，不要猜
完成前检查	用 verification-before-completion，列出实际运行结果
代码审查	用 requesting-code-review，按严重程度报告问题
处理审查反馈	用 receiving-code-review，逐条说明处理方式
收尾分支	用 finishing-a-development-branch，验证后给合并选项

记住一句话：你不是在“调用 prompt”，你是在把 agent 放进一个工程流程里。

一个具体例子

假设你要修一个问题：用户上传空 CSV 时，系统没有给出错误提示。

没有流程约束时，agent 可能会直接找到上传逻辑，加一个 if 判断，然后说“已修复”。

Superpowers 的做法会更笨一点，也更可靠：

• 先复现问题
• 写一个失败测试：空 CSV 应返回“文件为空”
• 确认测试因为缺少校验而失败
• 添加最小校验逻辑
• 运行测试，确认通过
• 再检查相邻场景：只有表头、空行、编码异常

这不是为了显得专业。它只是把“我猜修好了”换成“这个失败用例现在过了”。

常见踩坑

以为装了就不用管。

Superpowers 会让 agent 更有纪律，但你仍然要做需求判断。它会问问题，你要回答。它会给计划，你要确认。它不是自动驾驶。

把流程当阻碍。

刚开始你可能会觉得它话多。尤其是 brainstorming，会在你想快速开干时拦一下。但这个拦截往往正是价值所在。真正浪费时间的是返工，不是澄清。

在不合适的任务上强行使用。

临时脚本、一次性实验、简单文本修改，不一定需要完整 TDD 流程。你可以明确告诉 agent 这是 throwaway prototype，避免流程过重。

忽略项目已有规范。

Superpowers 提供的是通用工程纪律，不知道你项目里的业务约定。仓库里的 AGENTS.md、CLAUDE.md、STYLE_GUIDE.md 仍然更高优先级。团队规范要写在项目内，不要只依赖插件默认行为。

和普通 Agent Skill 的区别

普通 skill 往往解决一个垂直问题，比如“生成封面图”“写代码评审”“翻译文档”。

Superpowers 更像一组工程习惯的组合包。它不是让 agent 多会一个技能，而是改变 agent 的工作顺序。

区别可以这样看：

类型	解决什么问题	典型结果
单个 Agent Skill	某个具体任务怎么做	输出更专业
Superpowers	整个开发过程怎么推进	工作更可控

如果你已经在维护自己的 skills，Superpowers 也能作为底层流程层使用：你的业务 skill 负责“做什么”，Superpowers 负责“按什么节奏做”。

结尾

AI 编程助手真正缺的不是速度，而是刹车。

Superpowers 给它装上的就是这套刹车系统：先问清楚，再写计划；先让测试失败，再写实现；先验证，再宣布完成。

当你开始把 agent 用在真实项目里，这些流程不会显得啰嗦。它们会变成你愿意把更多工作交给 AI 的理由。

GitHub: https://github.com/obra/superpowers

Codex 安装说明: https://raw.githubusercontent.com/obra/superpowers/main/.codex/INSTALL.md