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

公众号名称：Git Trend

作者名称：wsleepybear

发布时间：2026-03-18 12:00

如果你已经开始拿 Claude Code、Codex、Gemini CLI 这类 agent 真做项目，你大概率已经踩过这种坑：它们很勤快，但第一反应总是直接改代码，最后要么做偏、要么返工、要么一堆“看起来完成了”的假完成。

这篇不讲理念，直接带你做三件事：把 Superpowers 装上、确认它真的生效、再拿一个真实的“订单 CSV 导出”功能跑一遍 澄清 → 计划 → RED → GREEN → 验收。你看完以后，不只是知道它是什么，而是知道怎么盯住 agent 别乱写、怎么判断它是不是在真干活。

项目卡片

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

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

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

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

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

输出：

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 个全记住。你第一次跑通，只要能把下面这条链路看见就够了：

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

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

这一节只留真正会用到的安装入口。重点不是“支持多少平台”，而是装完立刻能验证。

Claude Code

/plugin install superpowers@claude-plugins-official

如果你走 marketplace：

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

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

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

Cursor

在 Agent chat 里执行：

/add-plugin superpowers

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

Codex

Codex 这条路最值得写，因为你能清楚看到它到底装了什么。

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

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

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

[features]
collab = true

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

看链接在不在：

ls -la ～/.agents/skills

理想输出至少有这一行：

superpowers -> /home/you/.codex/superpowers/skills

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

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

更新：

gemini extensions update superpowers

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

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

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

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

如果你走 Codex，先看软链接：

ls -la ～/.agents/skills

你要找的是：

superpowers -> .../superpowers/skills

检查点：

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

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

这一步最关键，因为 Superpowers 不是“放一堆 Markdown 文件就算接入”。

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

仓库里的 hooks/hooks.json：

{
  "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 注入上下文。

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

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

检查点：

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

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

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

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

或者更直一点：

help me plan this feature

预期结果不是“它回你了”，而是：

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

失败判断：

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

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

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

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

1. `brainstorming`

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

直接这样下指令：

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

你想看到的输出：

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

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

2. `writing-plans`

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

直接这样下指令：

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

你想看到的输出：

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

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

3. `test-driven-development`

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

直接这样下指令：

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

仓库里很直白：

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

你要盯的不是口号，而是证据：

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

4. `systematic-debugging`

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

直接这样下指令：

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

你想看到的输出：

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

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

5. `verification-before-completion`

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

直接这样下指令：

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

仓库里的底线是：

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

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

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

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

我要在现有项目里做一个中等复杂度的增量功能。
请按 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`

- [ ] Step 1: 写 failing test
- [ ] Step 2: 运行测试，确认 RED

Run:

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

Expected RED:

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
Step 1: 增加 CSV formatter
Step 2: 新增 /export 路由，复用现有筛选逻辑
Step 3: 重跑单点测试，确认 GREEN

Run:

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

Expected GREEN:

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
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。

第一句怎么下

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

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

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

这句话的作用只有一个：把 agent 从“默认写代码”拽回“先收敛设计”。

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

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

## 推荐方案

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

## 验收标准

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

检查点：

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

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

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

直接发：

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

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

先写测试，不要先写实现

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

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：先确认它是真的失败，不是测歪了

先只跑这一条：

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

你想看到的 RED：

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 三块够不够闭环，别一上来抽出一整套导出框架。

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

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

// 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');
}

// 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);
}

// src/modules/orders/order.routes.ts
router.get('/export', requireAdminAuth, exportOrders);

这一步的检查点：

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

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

GREEN：先跑单点，再跑模块回归

先重跑单点：

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

理想输出：

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)

再跑订单模块相关测试：

pnpm vitest tests/orders

失败判断：

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

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

至少做下面 5 个检查。

1）先看 diff 有没有超范围

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

那就直接看：

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 原样贴出来

直接问：

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

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

4）自己手打一次接口

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

至少看这几项：

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

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

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

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

直接问：

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

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

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

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

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

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

先做：

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

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

2. `～/.agents/skills/superpowers` 在，但 agent 不触发

先看两个路径：

ls -la ～/.agents/skills/superpowers
ls ～/.codex/superpowers/skills

你要确认的是：

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

典型坏样子：

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

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

别跟它讨论理念，直接收紧指令：

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

如果还不收，就再加一句：

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

4. plan 写得像 PPT

直接打回去，别凑合用：

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

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

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

按 verification-before-completion 追：

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

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

具体命令
原始输出

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

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

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

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

处理顺序：

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

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

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

适合用

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

不太适合用

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

它本质上还是一层工程流程。小任务上会显得重，但在返工成本高的任务里，这层“重”通常是省时间的。

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

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

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

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

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

如果这条链路能在一个小功能上跑顺，Superpowers 对你就不是“又一个 agent 插件”，而是一套你能拿来反复复用的干活流程。

如果这篇对你有用，建议点个关注。我会持续把 GitHub 上值得用的 AI 工具拆成「最短上手闭环 + 坑点清单 + 可复用配置」，让你少走弯路。

引用链接

[1]https://github.com/obra/superpowers

cover_image

原创 wsleepybear Git Trend

Claude Code

Cursor

Codex

Gemini CLI

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

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

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

1. brainstorming

2. writing-plans

3. test-driven-development

4. systematic-debugging

5. verification-before-completion

Task 2: 补最小实现

第一句怎么下

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

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

先写测试，不要先写实现

RED：先确认它是真的失败，不是测歪了

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

GREEN：先跑单点，再跑模块回归

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

1）先看 diff 有没有超范围

2）核对 plan 里的文件，是否真的对应到 diff

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

4）自己手打一次接口

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

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

2. ～/.agents/skills/superpowers 在，但 agent 不触发

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

4. plan 写得像 PPT

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

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

适合用

不太适合用

引用链接

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

1. `brainstorming`

2. `writing-plans`

3. `test-driven-development`

4. `systematic-debugging`

5. `verification-before-completion`

2. `～/.agents/skills/superpowers` 在，但 agent 不触发