Superpowers 上手实战:怎么把 coding agent 从直接开写,带回可控的工程流程

如果你已经开始拿 Claude Code、Codex、Gemini CLI 这类 agent 真做项目,你大概率已经踩过这种坑:它们很勤快,但第一反应总是直接改代码。

最后要么做偏,要么返工,要么一堆“看起来完成了”的假完成。

这篇不讲理念,直接带你做三件事:把 Superpowers 装上、确认它真的生效、再拿一个真实的“订单 CSV 导出”功能跑一遍 澄清 → 计划 → RED → GREEN → 验收

你看完以后,不只是知道它是什么。更重要的是,你会知道 怎么盯住 agent 别乱写、怎么判断它是不是在真干活

项目卡片

  • 项目名:Superpowers
  • GitHub:https://github.com/obra/superpowers
  • 总星数:约 8.6 万 Star
  • 一句话判断:如果你受够了 agent 一上来就乱写代码,这个仓库的价值就是先把它拉回“先想清楚再动手”的节奏。
  • 适合谁:已经在用 Claude Code、Codex、Gemini CLI 这类工具,而且开始在意测试、验收和别跑偏的人。

先看仓库结构,别一上来就乱装

真正上手前,先别急着装。先看仓库结构,你后面会更容易对上“安装、验证、skill、测试、plan”分别该去哪找。

Superpowers 仓库结构总览图

这张图的作用是帮你先建立“仓库脑图”:README 讲入口,hooks 负责启动注入,skills 是核心能力,docs/testing 与 docs/plans 负责验证和落盘。

bashcode
find skills -mindepth 1 -maxdepth 1 -type d | sort | sed 's#^skills/##'

输出:

textcode
brainstorming
dispatching-parallel-agents
executing-plans
finishing-a-development-branch
receiving-code-review
requesting-code-review
subagent-driven-development
systematic-debugging
test-driven-development
using-git-worktrees
using-superpowers
verification-before-completion
writing-plans
writing-skills

先别想着 14 个全记住。你第一次跑通,只要能把下面这条链路看见就够了:

textcode
brainstorming -> writing-plans -> test-driven-development -> verification-before-completion

先装起来:按仓库原文走,不要自己脑补

这一节只留真正会用到的安装入口。

重点不是“支持多少平台”,而是 装完立刻能验证

Claude Code

bashcode
/plugin install superpowers@claude-plugins-official

如果你走 marketplace:

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

做完检查: 新开一个会话,不要在旧会话里继续聊。

安装与接入检查示意图

这张图对应的不是“安装成功”四个字,而是你真正要看的两个动作:命令有没有跑通、挂载后的检查结果是不是对的。

Cursor

在 Agent chat 里执行:

textcode
/add-plugin superpowers

做完检查: 新开一个 chat,再发一个会触发 planning 的任务,不要直接让它写代码。

Codex

Codex 这条路最值得写。

因为你能清楚看到它到底装了什么。

.codex/INSTALL.md 里的步骤是:

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

如果你要用到并行协作相关 skill,仓库文档还要求打开:

tomlcode
[features]
collab = true

装完先别急着用。先做 3 个检查。

  1. 看链接在不在:
bashcode
ls -la ~/.agents/skills

理想输出至少有这一行:

textcode
superpowers -> /home/you/.codex/superpowers/skills
  1. 看目标目录是不是真的有 skill:
bashcode
ls ~/.codex/superpowers/skills

你应该看到一串目录名,而不是 No such file or directory

  1. 改完后重启 Codex,再开新会话。

失败判断:

  • ln: File exists:说明你之前装过,先看它是不是指到正确路径
  • No such file or directory:通常是 clone 路径不对,或者 ~/.codex/superpowers 不存在
  • 新会话里完全没变化:先别怪 skill,本质上多半是你还在旧 session 里

Gemini CLI

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

更新:

bashcode
gemini extensions update superpowers

做完检查: 开一个新会话,直接给 planning 型任务。

装完先别提需求,先确认它真的生效

安装成功不等于工作流生效。先验这 3 件事。

验证 1:skill 入口是否真的挂上了

如果你走 Codex,先看软链接:

bashcode
ls -la ~/.agents/skills

你要找的是:

textcode
superpowers -> .../superpowers/skills

检查点:

  • 有链接:继续下一步
  • 没链接:先别往下聊,安装本身就没完成
  • 链接存在但指错目录:先修链接,不然 agent 看到的是旧版本或空目录

验证 2:会话启动时是否真的注入 using-superpowers

这一步最关键。

因为 Superpowers 不是“放一堆 Markdown 文件就算接入”。

SessionStart 注入与 skill 加载关系图

如果你总怀疑“是不是只是装了文件,但根本没生效”,就看这层关系:SessionStart 是否触发、session-start 是否执行、using-superpowers 是否真的进了上下文。

仓库里的 hooks/hooks.json

jsoncode
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
            "async": false
          }
        ]
      }
    ]
  }
}

意思很直接:新会话启动时,自动执行 session-start

hooks/session-start 干的事,是把 skills/using-superpowers/SKILL.md 注入上下文。

如果你本地手动跑这个脚本,能看到类似输出开头:

jsoncode
{
  "additional_context": "<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill ..."
}

检查点:

  • 能看到 You have superpowers:说明启动注入逻辑在跑
  • 完全没有这段:先查 hook 配置,而不是继续测业务 prompt
  • 旧会话里没反应:这不是失败样本,必须新开 session 再看

验证 3:故意给一个会触发 planning 的请求

第一次验证,不要发“帮我写个功能”。发这种:

textcode
先别写代码,先帮我把这个功能做需求澄清和实现计划。

或者更直一点:

textcode
help me plan this feature

预期结果不是“它回你了”,而是:

  • 它先问范围、约束、验收标准
  • 它先收敛方案
  • 它不会第一句就开改文件

失败判断:

  • 一上来直接贴实现:说明你看到的还是普通 coding agent 行为
  • 只给很虚的流程话术,不落到文件/测试/命令:说明 workflow 没真正落地

第一次先认这 5 个 skill,够你跑通完整流程

Superpowers 五个常用 skill 地图

第一次不用全学。先把这 5 个 skill 跑顺,你就已经不是“会装”,而是真的开始会用了。

第一次不需要全读完,先盯这 5 个。

1. brainstorming

用在什么时候: 新功能、改行为、边界不清。

直接这样下指令:

textcode
先不要写代码。按 brainstorming 收敛目标、约束、验收标准和不做事项。

你想看到的输出:

  • 它开始提必要问题
  • 它能写出推荐方案
  • 它能明确列出“这次不做什么”

如果失败: 它开始直接讨论数据库表结构、开始写代码、开始“顺手重构”,就打回去。

2. writing-plans

用在什么时候: 设计确认后,准备开工。

直接这样下指令:

textcode
设计确认了。进入 writing-plans。把任务拆成小步骤,每一步写文件路径、命令、预期输出、自查动作。

你想看到的输出:

  • 改哪些文件
  • 先写哪个测试
  • 跑什么命令
  • RED / GREEN 分别长什么样
  • 每步做完怎么自查

如果失败: plan 只有“先改后端,再改前端,再测试”这种 PPT 句子,直接重来。

3. test-driven-development

用在什么时候: 新功能、修 bug、改行为。

直接这样下指令:

textcode
按 TDD 做。先写 failing test,看到 RED 后再写最小实现,再确认 GREEN。

仓库里很直白:

textcode
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

你要盯的不是口号,而是证据:

  • 第一条测试命令是什么
  • 红在哪里
  • 改了哪些文件
  • 绿之后又跑了哪些回归验证

4. systematic-debugging

用在什么时候: 测试挂了、行为不对、输出怪。

直接这样下指令:

textcode
先别修。按 systematic-debugging 复现、取证、定位根因,再给修法。

你想看到的输出:

  • 稳定复现步骤
  • 相关日志 / 输入 / 响应
  • 候选根因
  • 如何排除

如果失败: 它一口气改 3 处试运气,那就不是调试,是碰运气。

5. verification-before-completion

用在什么时候: 任何它想说“做完了”的时刻。

直接这样下指令:

textcode
先不要总结,先贴刚跑完的验证命令和输出,再说是否完成。

仓库里的底线是:

textcode
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

这句你真得用起来。不然再漂亮的总结都可能是“口头完成”。

第一段话怎么说:直接复制这份模板

第一次把它带进现有项目,别说“帮我做个功能”。直接用这段:

textcode
我要在现有项目里做一个中等复杂度的增量功能。
请按 superpowers workflow 来,不要直接改代码。

第一步:先做 brainstorming
- 问我必要问题
- 收敛目标、范围、验收标准
- 给出推荐方案和明确的不做事项

第二步:设计确认后,进入 writing-plans
- 把任务拆成尽量小的步骤
- 每一步写清:改哪些文件、运行什么命令、预期看到什么

第三步:执行时遵守 TDD
- 先写 failing test
- 先看到 RED
- 再写最小实现
- 再看到 GREEN

第四步:每完成一个任务块,先同步
- 改了什么
- 跑了什么验证
- 输出是什么
- 下一步做什么

如果遇到异常,不要猜修法,先切到 systematic-debugging。
如果要宣布完成,必须先跑验证命令并贴输出。

这个模板的作用不是“更礼貌”。

而是把 agent 锁进一个可检查的流程里。

别让 plan 写成 PPT,至少要细到这个粒度

真实工程任务单结构示意

你要的不是“路线图”,而是一份能拿来对照 diff、测试输出和验收标准的任务单。图里这几个模块:Task、Files、Run、Expected、Self-check,缺一个都容易变成 PPT。

下面这段不是“参考格式”,而是你应该真的要求它交出来的任务单。

示例标题: Orders CSV Export Implementation Plan

Goal 为后台订单列表增加按当前筛选条件导出 CSV 的能力。

Task 1:补失败测试

Files

  • Modify: tests/orders/export-orders.e2e.spec.ts
  • Reference: tests/orders/list-orders.e2e.spec.ts

Steps

  • Step 1:写 failing test
  • Step 2:运行测试,确认 RED

Run

bashcode
pnpm vitest tests/orders/export-orders.e2e.spec.ts -t "returns csv with current filters"

Expected RED

textcode
FAIL  tests/orders/export-orders.e2e.spec.ts > GET /api/admin/orders/export returns csv with current filters
AssertionError: expected 404 to be 200

Self-check

  • 失败原因是路由不存在或行为未实现
  • 不是测试文件路径错、环境没起、鉴权没配

Task 2:补最小实现

Files

  • Create: src/modules/orders/orderCsv.ts
  • Modify: src/modules/orders/order.controller.ts
  • Modify: src/modules/orders/order.routes.ts

Steps

  • Step 1:增加 CSV formatter
  • Step 2:新增 /export 路由,复用现有筛选逻辑
  • Step 3:重跑单点测试,确认 GREEN

Run

bashcode
pnpm vitest tests/orders/export-orders.e2e.spec.ts -t "returns csv with current filters"

Expected GREEN

textcode
PASS  tests/orders/export-orders.e2e.spec.ts > GET /api/admin/orders/export returns csv with current filters
Tests: 1 passed

Self-check

  • 返回头里有 text/csv
  • 结果只包含当前筛选命中的订单
  • 没顺手引入异步导出、报表系统或额外抽象

看到这里你就明白了:

plan 不是“路线图”,而是执行清单。

直接跑一遍:给现有项目加一个订单 CSV 导出

这一节直接带你做,不讲概念。

场景设定

假设项目里已经有:

textcode
src/
├── modules/
│   └── orders/
│       ├── order.controller.ts
│       ├── order.routes.ts
│       ├── order.service.ts
│       └── order.repository.ts
└── lib/http.ts

tests/
└── orders/
    ├── list-orders.e2e.spec.ts
    └── order-factory.ts

现在要加:按当前筛选条件导出订单 CSV。

第一句怎么下

不要说“加个导出”。直接这么发:

textcode
我要在这个现有后台项目里新增“订单 CSV 导出”功能。
先不要写代码。
请先按 superpowers workflow 做 brainstorming:
1. 先问我必要问题
2. 收敛边界、验收标准、影响文件
3. 给出推荐方案和明确的不做事项
4. 在我确认前,不要进入实现

已知约束:
- 只做同步导出,不做异步任务
- 复用订单列表已有筛选条件
- 不顺手重构订单模块
- 测试命令是 `pnpm vitest`
- 如果权限或字段格式不明确,先停下来问我

这句话的作用只有一个:

把 agent 从“默认写代码”拽回“先收敛设计”。

你应该期待什么样的澄清结果

如果它真的在干活,你会看到这种输出,而不是直接贴 controller 代码:

markdowncode
## 推荐方案

- 新增 `GET /api/admin/orders/export`
- 复用 `listOrders()` 的筛选条件解析
- CSV 固定字段:order_no、user_email、total、status、created_at
- 权限沿用后台订单列表权限
- 本次不做:异步导出、超大文件分片、导出记录表

## 验收标准

1. 传入与列表页一致的筛选参数时,只导出命中订单
2. 响应头包含 `text/csv`
3. 首行包含固定表头
4. 至少有一个 e2e 测试覆盖成功路径

检查点:

  • 有明确接口名
  • 有字段范围
  • 有“不做事项”
  • 有验收标准

少一个,都不要让它进实现。

设计确认后,马上逼它交任务单

直接发:

textcode
设计确认。现在进入 writing-plans。
请把实现拆成小任务,每一步写清:
- 改哪些文件
- 先写哪个 failing test
- 跑什么命令
- 预期看到什么 RED / GREEN
- 这一步完成后如何自查

这里的关键不是“它有 plan”,而是这个 plan 够不够你照着验。

先写测试,不要先写实现

一个更像真实项目的测试,大概会长这样:

tscode
import request from 'supertest';
import { app } from '../../src/lib/http';
import { createOrder } from '../factories/order-factory';

describe('GET /api/admin/orders/export', () => {
  test('returns csv for current filters only', async () => {
    await createOrder({ orderNo: 'SO-20260301', status: 'paid', total: 12800, createdAt: '2026-03-05T10:00:00Z' });
    await createOrder({ orderNo: 'SO-20260227', status: 'cancelled', total: 9900, createdAt: '2026-02-27T09:00:00Z' });

    const res = await request(app)
      .get('/api/admin/orders/export?status=paid&from=2026-03-01&to=2026-03-31')
      .set('Authorization', 'Bearer admin-test-token');

    expect(res.status).toBe(200);
    expect(res.headers['content-type']).toContain('text/csv');
    expect(res.text).toContain('order_no,user_email,total,status,created_at');
    expect(res.text).toContain('SO-20260301');
    expect(res.text).not.toContain('SO-20260227');
  });
});

RED:先确认它是真的失败,不是测歪了

先只跑这一条:

bashcode
pnpm vitest tests/orders/export-orders.e2e.spec.ts -t "returns csv for current filters only"

你想看到的 RED:

textcode
FAIL  tests/orders/export-orders.e2e.spec.ts > GET /api/admin/orders/export > returns csv for current filters only
AssertionError: expected 404 to be 200

这一段一定要盯细。

因为不同失败,含义完全不一样:

  • 404 -> 200:通常说明接口还没实现,这是正常 RED
  • 401/403:多半是权限前提没补齐,不代表功能逻辑错
  • test file not found:测试路径都错了,别进实现
  • app boot failed:环境没起,先修测试基线
  • 第一次就 PASS:要么项目里已有同名接口,要么你压根测到了错误目标

最小实现:只补这次需求闭环

CSV 导出最小实现示意图

这类图的重点不是“炫代码”,而是提醒你盯住最小实现边界:controller、route、formatter 三块够不够闭环,别一上来抽出一整套导出框架。

这个阶段你要盯住的是“够用”,不是“架构上瘾”。

例如最小实现可以长这样:

tscode
// src/modules/orders/orderCsv.ts
export function renderOrdersCsv(rows: Array<{
  orderNo: string;
  userEmail: string;
  total: number;
  status: string;
  createdAt: string;
}>) {
  const header = 'order_no,user_email,total,status,created_at';
  const body = rows.map(row => [
    row.orderNo,
    row.userEmail,
    row.total,
    row.status,
    row.createdAt,
  ].join(','));

  return [header, ...body].join('\n');
}
tscode
// src/modules/orders/order.controller.ts
export async function exportOrders(req: Request, res: Response) {
  const filters = parseOrderFilters(req.query);
  const rows = await orderService.listForExport(filters);
  const csv = renderOrdersCsv(rows);

  res.setHeader('Content-Type', 'text/csv; charset=utf-8');
  res.setHeader('Content-Disposition', 'attachment; filename="orders.csv"');
  res.status(200).send(csv);
}
tscode
// src/modules/orders/order.routes.ts
router.get('/export', requireAdminAuth, exportOrders);

这一段你要盯的检查点:

  • 只新增当前需求需要的文件和路由
  • 复用已有筛选逻辑
  • 没开始造异步任务表、报表中心、S3 落盘、通用导出引擎

如果它开始做这些,就不是“想得周到”,而是已经越界。

GREEN:先跑单点,再跑模块回归

先重跑单点:

bashcode
pnpm vitest tests/orders/export-orders.e2e.spec.ts -t "returns csv for current filters only"

理想输出:

textcode
PASS  tests/orders/export-orders.e2e.spec.ts > GET /api/admin/orders/export > returns csv for current filters only

Test Files  1 passed (1)
Tests       1 passed (1)

再跑订单模块相关测试:

bashcode
pnpm vitest tests/orders

失败判断:

  • 单点绿,但模块回归挂:功能可能做通了,但破坏了既有行为
  • 测试绿,但返回头不对:还不能叫完成
  • 只说“本地验证通过”,不给命令和输出:默认不算完成

跑通后,怎么判断它不是在表演

至少做下面 5 个检查。

1)先看 diff 有没有超范围

bashcode
git diff --stat

如果只是 CSV 导出,却改了十几二十个文件、顺手重构订单模块,这一轮就已经跑偏了。

2)核对 plan 里的文件,是否真的对应到 diff

如果 plan 说只改:

  • tests/orders/export-orders.e2e.spec.ts
  • src/modules/orders/orderCsv.ts
  • src/modules/orders/order.controller.ts
  • src/modules/orders/order.routes.ts

那就直接看:

bashcode
git diff -- tests/orders/export-orders.e2e.spec.ts src/modules/orders/orderCsv.ts src/modules/orders/order.controller.ts src/modules/orders/order.routes.ts

3)让它把 RED -> GREEN 原样贴出来

直接问:

textcode
把这次 CSV 功能的 RED -> GREEN 命令和输出原样贴出来,只贴相关部分。

说不清,基本就是在“讲完成故事”。

4)自己手打一次接口

bashcode
curl -i "http://localhost:3000/api/admin/orders/export?status=paid&from=2026-03-01&to=2026-03-31" \
  -H "Authorization: Bearer <admin-token>"

至少看这几项:

textcode
HTTP/1.1 200 OK
Content-Type: text/csv; charset=utf-8
Content-Disposition: attachment; filename="orders.csv"

再往下看响应体里有没有:

textcode
order_no,user_email,total,status,created_at
SO-20260301

5)追问“不做事项”有没有被偷偷做掉

直接问:

textcode
这次有没有顺手做异步导出、额外权限模型、通用导出抽象?如果有,逐项列出来。

它能正面回答,才像真的在按边界做事。

出问题先查这几件事,别只会说“重启试试”

常见失败与排查信息图

这张图对应的是文章后半段最容易被跳过、但在真实使用里最值钱的部分:不是提醒你“可能失败”,而是告诉你旧会话、悬空软链接、虚 plan、没贴验证输出、RED 不干净各该先查什么。

1. 装上了,但表现得像没装

先检查是不是旧会话。Superpowers 的 hook 挂在 SessionStart 上,你在老 session 里继续追问,可能根本没重新注入。

先做:

textcode
新开一个会话,再发一次“先不要写代码,先做需求澄清和计划”

如果新会话仍然直接写代码: 再去查 hook,而不是继续试 prompt。

2. ~/.agents/skills/superpowers 在,但 agent 不触发

先看两个路径:

bashcode
ls -la ~/.agents/skills/superpowers
ls ~/.codex/superpowers/skills

你要确认的是:

  • 软链接没断
  • 目标目录真有 skill 文件
  • 不是链接到了旧副本

典型坏样子:

  • No such file or directory:软链接悬空
  • 目录存在但内容不对:版本不一致或路径搞错

3. 它一上来还是直接写代码

别跟它讨论理念,直接收紧指令:

textcode
先不要实现。先进入 brainstorming,把范围、验收标准、不做事项收敛清楚。确认前不要改代码。

如果还不收,就再加一句:

textcode
在你给出推荐方案、验收标准和不做事项之前,不要进入实现。

4. plan 写得像 PPT

直接打回去,别凑合用:

textcode
这个 plan 还不能执行。请补成任务单:文件路径、测试命令、预期 RED / GREEN、每一步完成后的自查动作。

合格线很简单: 你能不能拿着这份 plan 去验它到底做没做。

5. 它说“完成了”,但没贴验证输出

verification-before-completion 追:

textcode
不要总结,先贴刚刚运行的完整验证命令和输出,再说是否完成。

如果它只给一句“测试已通过”,继续追两样东西:

  • 具体命令
  • 原始输出

没有这两样,就先别认账。

6. RED 不够干净,失败原因混在一起

比如你本来想验证“接口未实现”,结果测出来是 401、数据库连接失败、测试环境没起。

这时不要继续写实现,先把 RED 清干净。

处理顺序:

  1. 先保证测试文件能被正确执行
  2. 再保证应用能正常启动
  3. 再补齐必要鉴权前提
  4. 最后确认失败点落在目标行为本身

只有这种 RED,后面的 GREEN 才有意义。

哪些场景该上,哪些场景别硬上

适合用

  • 现有项目里的中等复杂度增量功能
  • 一个 bug 涉及多层调用,不能靠猜修
  • 你已经吃过“agent 改了很多,但方向不对”的亏
  • 你想留下能复查的 plan、测试和验证痕迹

不太适合用

  • 一两行小修
  • 明确到不能再明确的机械替换
  • 你只想 5 分钟把洞补上
  • 项目本身没有测试基线,连验证命令都没有

它本质上还是一层工程流程。

小任务上会显得重。 但在返工成本高的任务里,这层“重”通常是省时间的。

最后只记住一件事:第一次别挑大活

第一次用 Superpowers,最适合的不是“重构整个老系统”,而是像“订单 CSV 导出”这种功能:

  • 有明确入口
  • 有明确输出
  • 有单点测试
  • 有 RED / GREEN
  • 你能一眼看出它到底在真干活,还是在表演

最后你真正要盯住的,不是“它写得多快”,而是这 6 步有没有真的发生:

textcode
先澄清
-> 再设计
-> 再出 plan
-> 先红后绿
-> 再验证
-> 最后才说完成

如果这条链路能在一个小功能上跑顺,Superpowers 对你就不是“又一个 agent 插件”。

它会变成一套你能拿来反复复用的干活流程。


关注微信公众号

想第一时间看到后续的工具拆解与实战更新,欢迎扫码关注公众号。