Superpowers 教程：别再让 AI 一上来就写代码了

如果你经常用 Codex、Claude Code、Gemini、Cursor 写代码，大概率遇到过这种场面：

你只说了一句：

帮我加个登录功能。

AI 立刻开始狂写。

三分钟后，代码是有了。

问题也来了：

• 目录结构乱了
• 老逻辑被改坏了
• 没有测试
• 边界情况没处理
• 你问它为什么这么写，它开始一本正经胡说

这不是你不会用 AI。

是大多数 Agent 默认太“冲动”。

Superpowers 要解决的就是这件事：让 AI 写代码前先动脑子。

它在 GitHub 上已经拿到超过 195K Stars。更狠的是，它可以把 Codex、Claude Code、Gemini、Cursor 这类 AI 编程工具，约束成更接近真实资深工程师的工作方式。

重点：免费、开源、工作流清晰。

Superpowers 到底是什么？

你可以把 Superpowers 理解成一个“AI 编程工作流控制器”。

它不只是让模型回答问题，也不是单纯套一层 Prompt。

它的核心思路是：

不准 AI 拿到需求就写代码，必须按 7 个阶段走完。

这 7 个阶段是：

头脑风暴 -> 规范 -> 计划 -> 子Agent -> TDD -> 评审 -> 完成

听起来有点像团队开发流程，对吧？

没错。

一个靠谱的高级工程师接到需求，通常不会立刻敲代码。他会先问：

• 这个需求到底解决什么问题？
• 会影响哪些模块？
• 有哪些边界条件？
• 怎么拆任务？
• 测试怎么写？
• 改完怎么验证？

Superpowers 做的事，就是把这套习惯强塞给 AI。😄

为什么普通 AI 编程容易翻车？

很多人把 AI 当“打字更快的程序员”。

这就危险了。

AI 写代码快得离谱，可它经常缺这几样东西：

1. 缺少上下文判断

你让它改一个接口，它可能顺手改掉调用方。

你让它优化一段 SQL，它可能没注意线上数据量。

你让它重构组件，它可能把团队约定的命名风格搞没了。

2. 缺少拆解能力

复杂需求不能一口吃。

比如“给后台加权限系统”，里面至少有：

• 用户角色
• 权限模型
• 菜单控制
• 接口鉴权
• 数据库迁移
• 前端状态管理
• 单元测试
• 回归验证

普通 Agent 很容易写着写着就失控。

3. 缺少自我审查

AI 最烦人的地方不是写错。

人也会写错。

烦的是它写错之后，还能显得特别自信。

Superpowers 的价值就在这里：它逼着 Agent 停下来检查，而不是一路狂奔。

Superpowers 的 7 阶段工作流怎么用？

下面咱们把这 7 个阶段拆开讲。

你不用背概念。

照这个流程用，你的 AI 编程质量会稳很多。

阶段一：头脑风暴，让 AI 先别急着写

这一阶段的目标很简单：

让 AI 把问题想明白。

你可以让 Agent 先回答这些问题：

请先不要写代码。

帮我分析这个需求：
- 目标是什么？
- 涉及哪些模块？
- 可能有哪些边界情况？
- 有哪些实现方案？
- 哪种方案风险最低？

比如你要做一个“文件上传进度条”。

普通 AI 可能直接给你一段上传代码。

更好的做法是先让它分析：

• 是单文件还是多文件？
• 要不要断点续传？
• 上传失败怎么重试？
• 大文件要不要分片？
• 后端接口有没有返回进度？
• 前端状态怎么维护？

这一轮不写代码。

只做判断。

这一步能省掉后面大量返工。

阶段二：规范，把“怎么做”写清楚

需求聊明白后，要让 AI 写规范。

规范不是文档洁癖。

它是防止 AI 跑偏的护栏。

你可以要求它输出：

请基于上面的分析，输出一份实现规范：

- 功能范围
- 不做什么
- 输入输出
- 数据结构
- API 设计
- 错误处理
- 测试要求
- 验收标准

这里有个关键点：一定要写“不做什么”。

比如：

本次只实现普通文件上传进度展示，不实现分片上传、不实现断点续传、不改动现有鉴权逻辑。

这句话很值钱。

它能防止 AI 自作聪明。

AI 有时太热心了。

你让它加个按钮，它能顺手重构半个项目。

别笑，很多人都被这么坑过。

阶段三：计划，把大任务拆成小步骤

规范定了，就该拆计划。

好计划要具体到“下一步能直接开干”。

不要让 AI 写这种废话：

1. 实现功能
2. 添加测试
3. 优化代码

这等于没写。

你要它写成这样：

请输出可执行计划，每一步都要包含：
- 要修改的文件
- 修改目的
- 预期结果
- 验证方式

示例：

- 修改 `src/components/Uploader.tsx`
  - 增加上传进度状态 `progress`
  - 在上传过程中更新 UI
  - 验证：选择文件后，进度条从 0% 更新到 100%

- 修改 `src/api/upload.ts`
  - 给上传请求增加进度回调
  - 保持原有接口参数兼容
  - 验证：旧调用方式不报错

- 新增 `Uploader.test.tsx`
  - 测试上传中、上传成功、上传失败三种状态

看到没？

这才叫计划。

每一步都能落地。

阶段四：子 Agent，把专业问题交给专业角色

Superpowers 里很关键的一点，是让不同子 Agent 做不同事情。

你可以把它想成一个临时开发小队：

• 架构 Agent：看整体设计
• 实现 Agent：负责写代码
• 测试 Agent：补测试用例
• Review Agent：挑毛病
• 安全 Agent：检查风险

这比一个 Agent 从头干到尾靠谱很多。

比如你要改登录模块，可以这样分工：

请模拟多个子 Agent 协作：

1. 架构 Agent：检查当前方案是否影响现有登录流程
2. 安全 Agent：检查 token、cookie、权限校验风险
3. 测试 Agent：列出必须覆盖的测试场景
4. 实现 Agent：只在确认方案后写代码

为什么要这样做？

因为同一个 AI 在“写代码”和“审代码”之间来回切换，效果经常不稳定。

让它扮演明确角色，输出会更聚焦。

阶段五：TDD，先写测试再写实现

TDD 是很多人嘴上说喜欢，实际不爱做的东西。

可对 AI 编程来说，它特别有用。

因为测试就是安全绳。

你可以这样要求：

请按 TDD 流程执行：

- 先写失败测试
- 再写最小实现
- 确认测试通过
- 不要一次性大改

比如上传组件至少要测：

• 默认状态不显示进度
• 开始上传后显示进度条
• 上传中进度更新
• 上传成功显示完成状态
• 上传失败显示错误提示

测试先出来，AI 就不容易乱飞。

它每改一步，都有明确目标。

你也不用靠肉眼猜：“这段代码到底能不能跑？”

阶段六：评审，让 AI 自己先挨一顿骂

代码写完别急着合。

让 Review Agent 开喷。

你可以直接用这个 Prompt：

请以严格代码评审者的身份检查刚才的改动：

- 是否符合需求规范？
- 是否引入破坏性变更？
- 是否有重复代码？
- 是否有性能问题？
- 是否有安全隐患？
- 测试覆盖是否足够？
- 有没有更简单的实现？

请列出必须修改项和可选优化项。

这个阶段特别适合抓这些问题：

• AI 偷偷改了无关文件
• 异常处理漏了
• 类型定义写得太松
• 测试只测 happy path
• 命名看起来很炫，实际没人懂

建议你重点看“必须修改项”。

可选优化别全接。

AI 有时会把简单问题优化成毕业设计。

阶段七：完成，给你一份可交付总结

完成阶段不是说一句“已完成”。

你要让 AI 输出交付说明。

格式可以固定：

请输出最终交付总结：

- 完成了什么
- 修改了哪些文件
- 如何运行测试
- 如何手动验收
- 有哪些已知限制
- 后续可以优化什么

这一步很适合团队协作。

你把总结贴到 PR 描述里，Review 的同事能少问很多问题。

比如：

## 完成内容
- 为上传组件增加进度条展示
- 保持原有上传 API 兼容
- 增加上传成功、失败、进度更新测试

## 修改文件
- `src/components/Uploader.tsx`
- `src/api/upload.ts`
- `src/components/Uploader.test.tsx`

## 验收方式
- 执行 `pnpm test Uploader`
- 手动选择文件上传，观察进度从 0% 到 100%

## 已知限制
- 当前不支持分片上传
- 当前不支持断点续传

这才像一个能交活的工程师。

一套可以直接复制的 Superpowers 工作流 Prompt

如果你现在就想试，直接把下面这段丢给 Codex、Claude Code、Gemini 或 Cursor。

你现在必须按 7 阶段工作流完成任务，不允许跳步。

任务：{把这里替换成你的需求}

工作流如下：

1. 头脑风暴
- 不写代码
- 分析目标、影响范围、边界情况、风险点
- 给出可选方案和推荐方案

2. 规范
- 输出功能范围
- 明确不做什么
- 定义输入输出、数据结构、错误处理、验收标准

3. 计划
- 拆成可执行步骤
- 每一步说明要修改的文件、目的、验证方式

4. 子 Agent
- 架构 Agent 检查设计
- 测试 Agent 列测试场景
- 安全 Agent 检查风险
- 实现 Agent 等确认后再写代码

5. TDD
- 先写失败测试
- 再写最小实现
- 每次改动后说明测试结果

6. 评审
- 以严格 Reviewer 身份检查代码
- 列出必须修改项和可选优化项

7. 完成
- 输出交付总结
- 包含修改文件、测试命令、验收方式、已知限制

规则：
- 没有完成当前阶段，不要进入下一阶段
- 不要修改无关文件
- 不要扩大需求范围
- 遇到不确定点先提问

把 {把这里替换成你的需求} 换掉就能用。

简单粗暴，好用。

适合 Superpowers 的使用场景

它特别适合这些任务：

复杂功能开发

比如：

• 支付流程
• 权限系统
• 数据看板
• 多步骤表单
• 文件上传
• 消息通知

这些需求最怕 AI 一把梭。

用 7 阶段流程，能把风险压下来。

老项目改造

老项目里最可怕的不是代码丑。

是你不知道哪里不能碰。

Superpowers 的规范和评审阶段，可以逼 AI 先看影响范围，再动手。

需要测试兜底的功能

比如订单、登录、权限、账单。

这些模块一出错就要命。

TDD 阶段能让 AI 先搭安全网。

团队 PR 协作

完成阶段输出的总结，可以直接变成 PR 描述。

你不用再对着 Git Diff 苦思冥想：“我刚刚到底改了啥？”

不适合用 Superpowers 的场景

也别什么都上流程。

有些小事没必要这么重。

比如：

• 改一个文案
• 调一个按钮颜色
• 补一个简单类型
• 写一次性脚本
• 查一个 API 用法

这些任务直接问 AI 就行。

别为了拧一颗螺丝，开一场架构评审会。

避坑清单：别让工作流变成形式主义

用 Superpowers 时，最容易踩这几个坑。

坑 1：需求写得太模糊

别写：

帮我优化一下后台。

要写：

帮我优化后台用户列表页加载速度。
当前接口返回约 5000 条用户数据，页面首次渲染卡顿。
目标是把首次可交互时间控制在 2 秒内。
不要改后端接口。

AI 不是你肚子里的蛔虫。

你说得越具体，它越像个人。

坑 2：不限制范围

一定要写“不做什么”。

比如：

不要重构登录模块。
不要修改数据库结构。
不要引入新的第三方库。

这几句话能救命。

坑 3：跳过测试

很多人觉得测试慢。

可 AI 写错后你手动排查半小时，更慢。

关键模块别省测试。

坑 4：评审阶段只看结论

Review Agent 说“代码没问题”，你别马上信。

让它列证据。

比如：

请逐文件说明为什么这些改动符合规范，并指出潜在风险。

要它讲清楚。

讲不清楚，大概率有坑。

坑 5：一次塞太多任务

不要一次让 AI 完成：

• 登录
• 注册
• 权限
• 用户管理
• 菜单管理
• 审计日志

这不是需求。

这是创业计划书。

拆小一点。

一个工作流解决一个明确目标。

推荐用法：小步快跑，比一口吃成胖子靠谱

我的建议是这样用：

一个需求 -> 一份规范 -> 一个计划 -> 一组测试 -> 一次实现 -> 一轮评审

每轮控制在 30 分钟到 2 小时内。

如果超过这个范围，说明需求太大。

拆。

AI 编程最舒服的节奏不是“你给我整个系统”。

而是：

你负责判断方向，AI 负责执行细节。

你像技术负责人。

它像执行力爆表的队友。

前提是，你得给它流程。

开源地址怎么找？

Superpowers 是开源项目。

你可以直接去 GitHub 搜：

Superpowers GitHub

认准 Star 数量较高、说明里提到 Codex / Claude Code / Gemini / Cursor 工作流的项目。

如果你在团队里用，建议先做三件事：

• 看 README 里的安装方式
• 看 Issues 里有没有常见坑
• 用一个非核心小需求试跑一遍

别一上来就拿生产核心模块开刀。

稳一点，少加班。

结语：AI 写代码快，流程让它靠谱

Superpowers 真正厉害的地方，不是让 AI 多写几行代码。

而是让 AI 少乱写。

它把资深工程师的习惯拆成 7 个动作：

想清楚 -> 写规范 -> 拆计划 -> 分角色 -> 写测试 -> 做评审 -> 给交付

你会发现，AI 编程质量差很多时候不是模型问题。

是你让它太自由了。

给它边界，给它流程，给它验收标准。

它才更像一个能放心交任务的同事。