如果你已经开始拿 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”分别该去哪找。
这张图的作用是帮你先建立“仓库脑图”:README 讲入口,hooks 负责启动注入,skills 是核心能力,docs/testing 与 docs/plans 负责验证和落盘。
bash code
find skills -mindepth 1 -maxdepth 1 -type d | sort | sed 's#^skills/##'
输出:
text code
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 个全记住。你第一次跑通,只要能把下面这条链路看见就够了:
text code
brainstorming -> writing-plans -> test-driven-development -> verification-before-completion
先装起来:按仓库原文走,不要自己脑补
这一节只留真正会用到的安装入口。
重点不是“支持多少平台”,而是 装完立刻能验证 。
Claude Code
bash code
/plugin install superpowers@claude-plugins-official
如果你走 marketplace:
bash code
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
做完检查: 新开一个会话,不要在旧会话里继续聊。
这张图对应的不是“安装成功”四个字,而是你真正要看的两个动作:命令有没有跑通、挂载后的检查结果是不是对的。
Cursor
在 Agent chat 里执行:
text code
/add-plugin superpowers
做完检查: 新开一个 chat,再发一个会触发 planning 的任务,不要直接让它写代码。
Codex
Codex 这条路最值得写。
因为你能清楚看到它到底装了什么。
.codex/INSTALL.md 里的步骤是:
bash code
git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
mkdir -p ~/.agents/skills
ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers
如果你要用到并行协作相关 skill,仓库文档还要求打开:
toml code
[features]
collab = true
装完先别急着用。先做 3 个检查。
看链接在不在:
bash code
ls -la ~/.agents/skills
理想输出至少有这一行:
text code
superpowers -> /home/you/.codex/superpowers/skills
看目标目录是不是真的有 skill:
bash code
ls ~/.codex/superpowers/skills
你应该看到一串目录名,而不是 No such file or directory。
改完后重启 Codex,再开新会话。
失败判断:
ln: File exists:说明你之前装过,先看它是不是指到正确路径
No such file or directory:通常是 clone 路径不对,或者 ~/.codex/superpowers 不存在
新会话里完全没变化:先别怪 skill,本质上多半是你还在旧 session 里
Gemini CLI
bash code
gemini extensions install https://github.com/obra/superpowers
更新:
bash code
gemini extensions update superpowers
做完检查: 开一个新会话,直接给 planning 型任务。
装完先别提需求,先确认它真的生效
安装成功不等于工作流生效。先验这 3 件事。
验证 1:skill 入口是否真的挂上了
如果你走 Codex,先看软链接:
bash code
ls -la ~/.agents/skills
你要找的是:
text code
superpowers -> .../superpowers/skills
检查点:
有链接:继续下一步
没链接:先别往下聊,安装本身就没完成
链接存在但指错目录:先修链接,不然 agent 看到的是旧版本或空目录
验证 2:会话启动时是否真的注入 using-superpowers
这一步最关键。
因为 Superpowers 不是“放一堆 Markdown 文件就算接入”。
如果你总怀疑“是不是只是装了文件,但根本没生效”,就看这层关系:SessionStart 是否触发、session-start 是否执行、using-superpowers 是否真的进了上下文。
仓库里的 hooks/hooks.json:
json code
{
"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 注入上下文。
如果你本地手动跑这个脚本,能看到类似输出开头:
json code
{
"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 的请求
第一次验证,不要发“帮我写个功能”。发这种:
text code
先别写代码,先帮我把这个功能做需求澄清和实现计划。
或者更直一点:
text code
help me plan this feature
预期结果不是“它回你了”,而是:
它先问范围、约束、验收标准
它先收敛方案
它不会第一句就开改文件
失败判断:
一上来直接贴实现:说明你看到的还是普通 coding agent 行为
只给很虚的流程话术,不落到文件/测试/命令:说明 workflow 没真正落地
第一次先认这 5 个 skill,够你跑通完整流程
第一次不用全学。先把这 5 个 skill 跑顺,你就已经不是“会装”,而是真的开始会用了。
第一次不需要全读完,先盯这 5 个。
1. brainstorming
用在什么时候: 新功能、改行为、边界不清。
直接这样下指令:
text code
先不要写代码。按 brainstorming 收敛目标、约束、验收标准和不做事项。
你想看到的输出:
它开始提必要问题
它能写出推荐方案
它能明确列出“这次不做什么”
如果失败: 它开始直接讨论数据库表结构、开始写代码、开始“顺手重构”,就打回去。
2. writing-plans
用在什么时候: 设计确认后,准备开工。
直接这样下指令:
text code
设计确认了。进入 writing-plans。把任务拆成小步骤,每一步写文件路径、命令、预期输出、自查动作。
你想看到的输出:
改哪些文件
先写哪个测试
跑什么命令
RED / GREEN 分别长什么样
每步做完怎么自查
如果失败: plan 只有“先改后端,再改前端,再测试”这种 PPT 句子,直接重来。
3. test-driven-development
用在什么时候: 新功能、修 bug、改行为。
直接这样下指令:
text code
按 TDD 做。先写 failing test,看到 RED 后再写最小实现,再确认 GREEN。
仓库里很直白:
text code
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
你要盯的不是口号,而是证据:
第一条测试命令是什么
红在哪里
改了哪些文件
绿之后又跑了哪些回归验证
4. systematic-debugging
用在什么时候: 测试挂了、行为不对、输出怪。
直接这样下指令:
text code
先别修。按 systematic-debugging 复现、取证、定位根因,再给修法。
你想看到的输出:
稳定复现步骤
相关日志 / 输入 / 响应
候选根因
如何排除
如果失败: 它一口气改 3 处试运气,那就不是调试,是碰运气。
5. verification-before-completion
用在什么时候: 任何它想说“做完了”的时刻。
直接这样下指令:
text code
先不要总结,先贴刚跑完的验证命令和输出,再说是否完成。
仓库里的底线是:
text code
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
这句你真得用起来。不然再漂亮的总结都可能是“口头完成”。
第一段话怎么说:直接复制这份模板
第一次把它带进现有项目,别说“帮我做个功能”。直接用这段:
text code
我要在现有项目里做一个中等复杂度的增量功能。
请按 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
bash code
pnpm vitest tests/orders/export-orders.e2e.spec.ts -t "returns csv with current filters"
Expected RED
text code
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
bash code
pnpm vitest tests/orders/export-orders.e2e.spec.ts -t "returns csv with current filters"
Expected GREEN
text code
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 导出
这一节直接带你做,不讲概念。
场景设定
假设项目里已经有:
text code
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。
第一句怎么下
不要说“加个导出”。直接这么发:
text code
我要在这个现有后台项目里新增“订单 CSV 导出”功能。
先不要写代码。
请先按 superpowers workflow 做 brainstorming:
1. 先问我必要问题
2. 收敛边界、验收标准、影响文件
3. 给出推荐方案和明确的不做事项
4. 在我确认前,不要进入实现
已知约束:
- 只做同步导出,不做异步任务
- 复用订单列表已有筛选条件
- 不顺手重构订单模块
- 测试命令是 `pnpm vitest`
- 如果权限或字段格式不明确,先停下来问我
这句话的作用只有一个:
把 agent 从“默认写代码”拽回“先收敛设计”。
你应该期待什么样的澄清结果
如果它真的在干活,你会看到这种输出,而不是直接贴 controller 代码:
markdown code
## 推荐方案
- 新增 `GET /api/admin/orders/export`
- 复用 `listOrders()` 的筛选条件解析
- CSV 固定字段:order_no、user_email、total、status、created_at
- 权限沿用后台订单列表权限
- 本次不做:异步导出、超大文件分片、导出记录表
## 验收标准
1. 传入与列表页一致的筛选参数时,只导出命中订单
2. 响应头包含 `text/csv`
3. 首行包含固定表头
4. 至少有一个 e2e 测试覆盖成功路径
检查点:
有明确接口名
有字段范围
有“不做事项”
有验收标准
少一个,都不要让它进实现。
设计确认后,马上逼它交任务单
直接发:
text code
设计确认。现在进入 writing-plans。
请把实现拆成小任务,每一步写清:
- 改哪些文件
- 先写哪个 failing test
- 跑什么命令
- 预期看到什么 RED / GREEN
- 这一步完成后如何自查
这里的关键不是“它有 plan”,而是这个 plan 够不够你照着验。
先写测试,不要先写实现
一个更像真实项目的测试,大概会长这样:
ts code
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:先确认它是真的失败,不是测歪了
先只跑这一条:
bash code
pnpm vitest tests/orders/export-orders.e2e.spec.ts -t "returns csv for current filters only"
你想看到的 RED:
text code
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:要么项目里已有同名接口,要么你压根测到了错误目标
最小实现:只补这次需求闭环
这类图的重点不是“炫代码”,而是提醒你盯住最小实现边界:controller、route、formatter 三块够不够闭环,别一上来抽出一整套导出框架。
这个阶段你要盯住的是“够用”,不是“架构上瘾”。
例如最小实现可以长这样:
ts code
// 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');
}
ts code
// 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);
}
ts code
// src/modules/orders/order.routes.ts
router.get('/export', requireAdminAuth, exportOrders);
这一段你要盯的检查点:
只新增当前需求需要的文件和路由
复用已有筛选逻辑
没开始造异步任务表、报表中心、S3 落盘、通用导出引擎
如果它开始做这些,就不是“想得周到”,而是已经越界。
GREEN:先跑单点,再跑模块回归
先重跑单点:
bash code
pnpm vitest tests/orders/export-orders.e2e.spec.ts -t "returns csv for current filters only"
理想输出:
text code
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)
再跑订单模块相关测试:
bash code
pnpm vitest tests/orders
失败判断:
单点绿,但模块回归挂:功能可能做通了,但破坏了既有行为
测试绿,但返回头不对:还不能叫完成
只说“本地验证通过”,不给命令和输出:默认不算完成
跑通后,怎么判断它不是在表演
至少做下面 5 个检查。
1)先看 diff 有没有超范围
如果只是 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
那就直接看:
bash code
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 原样贴出来
直接问:
text code
把这次 CSV 功能的 RED -> GREEN 命令和输出原样贴出来,只贴相关部分。
说不清,基本就是在“讲完成故事”。
4)自己手打一次接口
bash code
curl -i "http://localhost:3000/api/admin/orders/export?status=paid&from=2026-03-01&to=2026-03-31" \
-H "Authorization: Bearer <admin-token>"
至少看这几项:
text code
HTTP/1.1 200 OK
Content-Type: text/csv; charset=utf-8
Content-Disposition: attachment; filename="orders.csv"
再往下看响应体里有没有:
text code
order_no,user_email,total,status,created_at
SO-20260301
5)追问“不做事项”有没有被偷偷做掉
直接问:
text code
这次有没有顺手做异步导出、额外权限模型、通用导出抽象?如果有,逐项列出来。
它能正面回答,才像真的在按边界做事。
出问题先查这几件事,别只会说“重启试试”
这张图对应的是文章后半段最容易被跳过、但在真实使用里最值钱的部分:不是提醒你“可能失败”,而是告诉你旧会话、悬空软链接、虚 plan、没贴验证输出、RED 不干净各该先查什么。
1. 装上了,但表现得像没装
先检查是不是旧会话。Superpowers 的 hook 挂在 SessionStart 上,你在老 session 里继续追问,可能根本没重新注入。
先做:
text code
新开一个会话,再发一次“先不要写代码,先做需求澄清和计划”
如果新会话仍然直接写代码: 再去查 hook,而不是继续试 prompt。
2. ~/.agents/skills/superpowers 在,但 agent 不触发
先看两个路径:
bash code
ls -la ~/.agents/skills/superpowers
ls ~/.codex/superpowers/skills
你要确认的是:
软链接没断
目标目录真有 skill 文件
不是链接到了旧副本
典型坏样子:
No such file or directory:软链接悬空
目录存在但内容不对:版本不一致或路径搞错
3. 它一上来还是直接写代码
别跟它讨论理念,直接收紧指令:
text code
先不要实现。先进入 brainstorming,把范围、验收标准、不做事项收敛清楚。确认前不要改代码。
如果还不收,就再加一句:
text code
在你给出推荐方案、验收标准和不做事项之前,不要进入实现。
4. plan 写得像 PPT
直接打回去,别凑合用:
text code
这个 plan 还不能执行。请补成任务单:文件路径、测试命令、预期 RED / GREEN、每一步完成后的自查动作。
合格线很简单: 你能不能拿着这份 plan 去验它到底做没做。
5. 它说“完成了”,但没贴验证输出
按 verification-before-completion 追:
text code
不要总结,先贴刚刚运行的完整验证命令和输出,再说是否完成。
如果它只给一句“测试已通过”,继续追两样东西:
没有这两样,就先别认账。
6. RED 不够干净,失败原因混在一起
比如你本来想验证“接口未实现”,结果测出来是 401、数据库连接失败、测试环境没起。
这时不要继续写实现,先把 RED 清干净。
处理顺序:
先保证测试文件能被正确执行
再保证应用能正常启动
再补齐必要鉴权前提
最后确认失败点落在目标行为本身
只有这种 RED,后面的 GREEN 才有意义。
哪些场景该上,哪些场景别硬上
适合用
现有项目里的中等复杂度增量功能
一个 bug 涉及多层调用,不能靠猜修
你已经吃过“agent 改了很多,但方向不对”的亏
你想留下能复查的 plan、测试和验证痕迹
不太适合用
一两行小修
明确到不能再明确的机械替换
你只想 5 分钟把洞补上
项目本身没有测试基线,连验证命令都没有
它本质上还是一层工程流程。
小任务上会显得重。 但在返工成本高的任务里,这层“重”通常是省时间的。
最后只记住一件事:第一次别挑大活
第一次用 Superpowers,最适合的不是“重构整个老系统”,而是像“订单 CSV 导出”这种功能:
有明确入口
有明确输出
有单点测试
有 RED / GREEN
你能一眼看出它到底在真干活,还是在表演
最后你真正要盯住的,不是“它写得多快”,而是这 6 步有没有真的发生:
text code
先澄清
-> 再设计
-> 再出 plan
-> 先红后绿
-> 再验证
-> 最后才说完成
如果这条链路能在一个小功能上跑顺,Superpowers 对你就不是“又一个 agent 插件”。
它会变成一套你能拿来反复复用的干活流程。
关注微信公众号
想第一时间看到后续的工具拆解与实战更新,欢迎扫码关注公众号。