核验范围：本文固定分析 obra/superpowers v6.1.1，重点阅读了 README、hooks/session-start、skills/using-superpowers/SKILL.md、skills/brainstorming/SKILL.md、skills/test-driven-development/SKILL.md、skills/subagent-driven-development/SKILL.md、skills/writing-skills/SKILL.md 和 CLAUDE.md。这个项目迭代很快，因此文中的文件链接都指向 tag，而不是 main。我没有独立运行它的行为评测，也不会把 README 的流程描述当成效果保证。

用户说：「给后台加一个 CSV 导出。」

如果没有额外约束，编码 Agent 往往会直接开始改路由、拼字符串、写文件。等它交出结果时，才有人发现几个问题：导出哪些字段？管理员和普通用户权限一样吗？十万行数据能一次性读进内存吗？日期、逗号和 Excel 公式要怎么处理？空数据时下载一个空文件，还是返回提示？

Superpowers 想处理的不是「模型能不能写出 CSV」，而是模型会不会在该停下来问问题的时候停下来，在该写测试时先写测试，在该交付时拿出证据。它把这些工程习惯写进一组可组合的 Skills，再用一份会话开始时注入的短指令提醒 Agent：任何动作之前，先检查有没有相关 Skill。

这篇文章不把它说成「装上就更聪明」的插件。我更想把它拆成四个能落到文件和实际行为上的问题：Skill 是怎样进入上下文的？所谓自动触发究竟自动在哪里？一项需求会怎样穿过这套流程？如果要借它的思路，怎样证明自己的规则不是徒增仪式感？

先建立一个不会混淆的心智模型

初学者读这类项目时，最容易把 Skill、工具、插件和模型本身揉成一团。先把分工拆开，后面才看得懂 session-start 为什么重要。

可以把 Superpowers 放在「工作方法」这一层。它不新增编译器、数据库或权限系统，而是改变 Agent 看到任务后更倾向走哪条路。真正能硬性拦截错误的仍然是权限、测试、Git Hook、CI 和人工 review。

这点看似扫兴，却很实用。只要把 Skill 当成软约束，你就不会因为 Agent 偶尔跳过流程而觉得项目「失效」了；反过来，也不会把生产权限交给一段写得很有气势的 Markdown。

这篇文章能带你走到哪里

Superpowers 究竟安装了什么

仓库把自己称为「一套给 coding agent 用的软件开发方法论」，底座是可组合的 Skills 与一组初始指令。README 里列出了 14 个 Skill，覆盖设计、计划、隔离工作区、测试驱动开发、系统化调试、评审和收尾。

它和「在 CLAUDE.md 写一句‘改完请跑测试’」的差异，不在于字数更多，而在于信息分层和触发时机：

举个很小的例子。「所有 API 修改都跑 pnpm test api」是这个仓库特有的事实，放项目规则里最合适；「修改有可测试行为的代码时，先写一个会失败的测试，再写最小实现」是跨项目的工作方法，适合做成 Skill。前者不需要模型判断是否适用，后者需要。

Superpowers 的 14 个 Skills 可以先按用途记，而不是强行背名字：

名称里最容易误导人的是 using-superpowers。它不是帮你完成某个业务任务的 Skill，而是门卫。它要求 Agent 在回应、提问、读文件和查看代码前，先判断是否存在相关 Skill；如果相关，就先调用它。源码 甚至专门列出「这只是个简单问题」「我先看一眼文件」「这个流程太重了」等自我说服的红旗。这种文案不是为了好看，而是在针对模型常见的捷径：先行动，再补流程。

自动加载的完整链路

「Skills 自动触发」这句话很容易让人误以为仓库里有个后台程序，会实时分析你的每一句话，然后替模型选中正确的 Markdown。v6.1.1 的 Claude Code、Cursor、Copilot CLI 等适配并不是这样工作。它把一小段引导内容放进会话上下文，剩下的选择仍由模型和 harness 的 Skill 机制共同完成。

以仓库里的 hooks/session-start 为例，脚本做的事情可以压缩成下面几步：

1. 找到插件根目录。
2. 读取 skills/using-superpowers/SKILL.md 的全文。
3. 把内容转义为 JSON 字符串。
4. 根据环境变量，输出 Claude Code、Cursor 或通用 SDK 能识别的「附加上下文」字段。

脚本的核心意图可以用下面这段伪代码表示。它不是仓库原码，只是为了让第一次看 Hook 的人抓住数据流：

1
2
3

bootstrap = read("skills/using-superpowers/SKILL.md")
context = "You have superpowers.\n\n" + bootstrap
emit_json(additional_context=context)

  flowchart TD
  A["启动 Claude Code、Cursor 或兼容 harness"] --> B["harness 触发 SessionStart Hook"]
  B --> C["Hook 读取 using-superpowers 的全文"]
  C --> D["把 bootstrap 写进本次会话的附加上下文"]
  D --> E["模型先知道：动作前要检查相关 Skill"]
  E --> F["任务与某个 Skill 匹配"]
  F --> G["通过 Skill 工具或宿主原生机制读取该 Skill"]
  G --> H["按正文中的流程调用工具、测试和 review"]
  

这里有一个上下文工程上的取舍。为什么不把 14 个 SKILL.md 全塞进启动消息？因为每一份操作细节都会占上下文，而且大多数任务只用到其中一两份。Superpowers 选择让 using-superpowers 常驻，它的职责很窄，只负责提醒「先找流程」；brainstorming、TDD、调试等正文等到需要时再读。常驻的是目录和纪律，细节按需展开。

这个策略并非唯一答案。某些 harness 会在会话开始时先暴露所有 Skill 的名称与描述，模型据此选择；有些平台需要通过工具读取；Pi 的适配又额外在上下文压缩后重新注入 bootstrap。README 的安装说明 明确写着安装方式按 harness 区分，Pi 的扩展行为也单独说明。文章或教程若不交代这一层，就很容易让读者以为「把一个 SKILL.md 放到磁盘上，所有 Agent 都会自动懂得加载它」。事实并非如此。

自动不是魔法：真正发生了什么

更准确地说，Superpowers 实现的是「提高流程被选择的概率」，不是「用代码强制执行状态机」。中间至少有四个环节，每一环都可能影响结果：

1. 插件有没有被当前 harness 正确安装和发现。
2. 会话启动时 Hook 有没有真的运行，附加上下文有没有被宿主接收。
3. 当前任务是否能让模型判断出某个 Skill 相关。
4. 模型读完 Skill 后，是否拥有执行其中命令、启动子 Agent、创建 worktree 的工具和权限。

这也是为什么同一套 Superpowers 在不同 Agent 产品上的体验会不同。模型能力、系统提示、工具名称、上下文窗口和权限政策都在变。即使在同一产品里，用户的一条更高优先级指令也可以要求跳过某个步骤。using-superpowers 本身也承认用户和项目指令优先于 Skill。

可以把它类比成经验丰富的同事在你桌上贴了一张流程卡：「改支付模块前先跑回归测试。」这张卡会让你少忘事，但它不能自动替你执行命令，也不能在你绕过测试时切断键盘。要想真的挡住未测代码，仍要靠 CI、分支保护和发布权限。

这个边界反而告诉我们，哪些内容该放到哪一层：

把可程序化验证的规则写成自动检查，把依赖判断的规则写进 Skill。这条分工比「把一切都写进提示词」可靠得多。

把「导出 CSV」这项需求走一遍

现在回到开头的需求。为了看清每个环节的作用，假设项目已经有用户列表接口，管理员希望导出筛选后的用户数据。这里的重点不是 CSV 库的 API，而是 Agent 在每个岔路口应当拿到什么信息、交出什么证据。

第一步：brainstorming 先收敛需求，而不是展示长篇推理

brainstorming 会在写代码前介入设计确认。它不是让 Agent 把所有可能性都抛给用户，而是先读现有代码、文档和测试，能查出的事实自己查；只有那些会改变实现、又无法从仓库得出的业务选择，才请用户决定。

在这个例子里，一份有用的澄清应接近下面这样：

1
2
3
4

我会复用用户列表当前的筛选条件和管理员权限校验。
需要确认两点：
1. 导出是否包含手机号、邮箱这类个人信息？
2. 结果可能超过 10 万条时，是允许异步生成下载链接，还是先限制导出条数？

这两问会改变权限判断、查询方式、存储和接口形态。相反，「CSV 用逗号还是分号」通常可遵循项目约定或目标软件默认值，不必打断用户。一个好的澄清阶段产出的是经过确认的设计，不是一串没有结论的提问。

第二步：把设计写成能被别人执行的计划

设计获确认后，writing-plans 的定位是把目标拆成细粒度任务。README 对它的描述很具体：任务要给出文件路径、完整代码和验证方式，而不只是「实现导出功能」。Basic Workflow

同一件事，下面两种计划的差别很大：

1
2
3
4
5
6
7
8
9

差：实现 CSV 导出，写测试。

好：
1. 在 src/users/export.ts 增加 buildUserCsv(rows)，只接受已脱敏的行。
   验证：为逗号、换行、双引号各写一个单元测试。
2. 在 src/routes/admin-users.ts 增加 GET /admin/users/export。
   验证：非管理员得到现有的 403 错误结构；筛选条件与列表接口一致。
3. 为空结果和 1 万条结果增加集成测试。
   验证：响应头、文件名、行数与查询结果一致。

「完整代码」在真实项目里并不一定意味着把大段实现全贴进计划，更重要的是让执行者知道改哪里、遵循哪种接口、以什么结果验收。对初学者来说，计划里最值得模仿的是「每一步都有可观察的完成条件」。没有它，Agent 很容易在「代码看起来已经写完」的地方停下。

第三步：是否创建 worktree，取决于并行和风险

Superpowers 的典型流程会在设计确认后使用 using-git-worktrees，在新分支和独立目录中工作，再检查测试基线是否干净。它解决的是并行开发互相踩文件、试验性改动污染当前工作区的问题，不是任何改动都必须开一个目录。

如果你一边维护线上热修，一边让 Agent 开发这个导出功能，worktree 很有价值：两套依赖和改动隔离，随时可以放弃实验分支。如果你只是把一处文案从「登入」改成「登录」，创建 worktree、跑完整安装、走多轮 review 很可能比改字本身贵。流程应该按风险和任务规模伸缩。

第四步：TDD 不是「最后补一份测试」

test-driven-development 的红绿重构循环要求先写会失败的测试，亲眼看到它失败，再写刚好足以让测试通过的实现，最后才整理代码。README 还把「已经先写了实现怎么办」的答案写得相当激进：删掉，再从失败测试开始。TDD Skill

以 CSV 转义为例，红灯阶段不是只写一句「应该能导出」：

1
2
3
4

it('quotes a cell that contains a comma', () => {
  expect(buildUserCsv([{ name: 'Li, Ming', email: 'a@example.com' }]))
    .toContain('"Li, Ming"')
})

先运行它，确认当前没有 buildUserCsv 或现有实现确实不满足预期。接着写最小实现使它变绿，再补双引号和换行的例子。这样做不是因为测试带来某种仪式感，而是把「转义规则是否正确」从模型的自我判断，变成一个能重复运行的外部反馈。

TDD 也有边界。纯视觉调整、一次性数据修复、探索性原型未必都适合先写单元测试，但它们仍需要相应的验证方式，例如截图对比、迁移前后数据核对或人工验收。不要把「没有单测」偷换成「无需验证」。

第五步：子 Agent 是隔离上下文的手段，不是人多就好

实现计划时，Superpowers 提供两条路线：executing-plans 适合分批执行并保留人工检查点；subagent-driven-development 则为每个相对独立的任务派一个新的实现 Agent，随后做「规格符合度」和「代码质量」两道 review，最后还有一次整分支 review。子 Agent Skill

这条路线的价值在于隔离，而不是神秘的多智能体协作。主会话保存设计、全局约束和进度；负责 CSV 转义的子 Agent 只拿到它需要的任务说明和接口；reviewer 只看计划要求与 diff。上下文更短，审查目标也更明确。

不过，任务之间高度耦合时，硬拆反而会制造协调成本。比如导出接口的权限模型、异步任务队列和下载签名都依赖同一个新架构，三个 Agent 分头改很可能各自做出不兼容的假设。这时由一个 Agent 连续实现，或先把架构设计写得更细，通常比并行更稳。

第六步：把「完成」换成可拿出来的证据

CSV 功能完成时，不应只有一句「已实现」。至少应能交代：

• 管理员、非管理员、空结果、带特殊字符的结果分别跑了什么测试。
• 导出字段和脱敏规则是否与确认的设计一致。
• 筛选条件是否确实复用了列表接口的语义。
• 大数据量策略是否符合最初决定的同步或异步方案。
• review 是否发现了问题，问题怎样处理。

verification-before-completion、requesting-code-review 和 finishing-a-development-branch 分别在不同节点提醒这件事。流程最后不是自动 merge，而是验证测试后，把合并、发 PR、保留分支或丢弃分支等选择摆出来。README 这很符合真实开发：技术完成不等于产品已发布，发布还涉及权限、风险和团队决策。

每个环节到底在防什么

把上述步骤串起来很容易变成一张好看的流程图。真正理解它，要看每一步针对的失败模式。

表中的最后一列很关键。Superpowers 的价值是让错误更早暴露、让过程可审阅，不是消灭不确定性。规格错了，十轮 review 也可能稳定地把错误规格做得很漂亮。

为什么 writing-skills 把文档也当成 TDD

这个仓库最值得借鉴的一点，反而不在日常开发流程，而在它怎样修改自己的 Skills。writing-skills 提出把 TDD 映射到过程文档：先拿一个有压力的真实场景让没有 Skill 的 Agent 执行，观察它怎样失败；再写最小规则修正这个失败；重新测试；最后专门寻找新的钻空子方式并补洞。源码

可以把映射写成这样：

它对 description 的提醒尤其具体：description 只说明「什么时候用」，不要把整个流程浓缩进去。原因不是文风偏好，而是仓库作者在测试里观察到，模型可能只照 description 的简写行动，跳过正文。比如把「两阶段 review」塞进描述，模型可能只做一次 review；把描述改成「在当前会话执行包含独立任务的实现计划时使用」，模型才会去读正文里的流程图。

这不是放之四海皆准的规则。不同 harness 对 description 的展示和加载方式不同，自己的 Skill 也未必有同样的失败模式。值得拿走的方法是：不要凭感觉把规则越写越凶。先找一次真实失败，再为那次失败写最小补丁，再用相同任务复测。

从 Superpowers 借三件事，先不要照搬整套流程

如果你刚开始用 AI 写代码，我不建议第一天就给项目塞进 14 个强制流程。更实用的起点是挑一件你已经反复踩坑的事，做成一个小闭环。

1. 先把项目事实和通用方法分开

可以在项目规则里写：

1
2
3

修改 API 后运行：pnpm test api
不得读取 .env.production
用户隐私字段只能在 admin 路由返回

这些是事实和硬边界。再用 Skill 写「修改 API 时怎样确认权限、怎样为行为变化补测试、怎样核对错误响应」。前者应尽量自动化，后者需要 Agent 结合上下文判断。

2. 让触发条件具体到能被识别

下面两句的差别不在文采：

1
2
3
4
5

# 模糊，模型不知道何时该读
description: 帮助处理后端问题

# 可识别，写出了症状和场景
description: 当新增或修改 HTTP 接口、权限校验、错误响应或数据库写入时使用；在改代码前确认接口契约与验证方式。

第二句可能仍需要随实际任务调整，但至少给了模型可匹配的信号。不要把一百种无关任务都塞进去，触发范围越大，误触发和上下文成本越高。

3. 用一个前后对照任务验证，而不是凭「感觉更专业」判断

拿一个可重复的任务，例如「给已有列表接口加 CSV 导出」，事先写出验收表：

不要只数「测试跑了没有」。如果规则让关键遗漏减少，但把每个十分钟改动都变成一小时会议，它就需要缩小触发范围；如果规则没有改变任何可观察行为，也许该删掉，或者改成 CI 能执行的检查。CLAUDE.md 同样强调，涉及行为塑形的改动需要足够的 eval 证据，而不是只凭作者相信它有效。贡献指南

成本、边界与几个容易踩的坑

Superpowers 的默认偏好是宁可多走一道流程，也不要漏掉流程。这对中等以上、会影响架构或多个文件的任务很合理；对每个任务都照搬，就会出现反效果。

第一个坑是把 Skill 当权限系统。Skill 说「不要删除生产数据」没有实际阻断力。真正的做法是不给默认 Agent 生产写权限，并在部署路径上设置审批。

第二个坑是把「先问用户」理解成什么都问。能从代码、文档、测试和已有接口查出的事实应该自己查。只有业务选择会改变方案，且仓库里没有答案时，才值得打断用户。

第三个坑是把 TDD 误解成测试数量竞赛。一个只断言函数存在的测试没有保护价值。优先覆盖会影响用户、权限、金钱、数据完整性和边界格式的行为；能用集成测试更直接地验证契约时，也别为了形式硬拆成十个脆弱的 mock。

第四个坑是把子 Agent 当并行按钮。并行有前提：任务边界清楚、接口稳定、冲突小。共享同一套刚设计出来的抽象时，先把设计讲明白往往更快。

第五个坑是相信「流程跑过，所以结果正确」。运行过的命令、测试报告和 review 结论都是证据，但证据覆盖不到的部分仍可能出错。尤其是外部服务、生产数据、性能和安全，必须补上相应的环境和人工判断。

初学者怎样开始用

如果你要直接体验 Superpowers，v6.1.1 的 README 为 Claude Code、Codex、Cursor、Pi 等 harness 分别提供了安装入口。安装说明 先确认你使用的平台是否在列表中，再按该平台的方式安装。不要把 Claude Code 的 Hook 配置原样复制到另一个产品里，文件能放进去不代表宿主会执行它。

第一次试用时，选一个有边界、能测试、但不会影响生产的功能。比如「为管理后台列表增加一个只导出 ID 与创建时间的 CSV 接口」。观察 Agent 是否会：

1. 先查看项目已有的权限和列表实现。
2. 只为会改变方案的地方提问。
3. 在实现前给出能审阅的计划。
4. 写并运行能失败、能通过的测试。
5. 最后用 diff、测试结果和未决风险说明完成情况。

只要其中某一步明显没有发生，不要急着追加十条「必须」或「严禁」。先确认插件是否真的被加载、当前 harness 是否有对应工具、任务描述是否触发了 Skill，再用一个更窄的规则和同一任务重新验证。很多所谓「提示词不听话」，根源是加载链路或执行权限，而不是语气不够强硬。

小结

Superpowers 的核心机制并不复杂：启动 Hook 把 using-superpowers 注入会话，模型因此被提醒在行动前检查相关 Skill；真正的流程细节再通过 Skill 工具或宿主机制按需读取。它把需求澄清、计划、测试、评审和收尾写成一套可复用的工作方法。

它的价值不在于替你决定 CSV 的字段，也不在于让所有 Agent 变成不会犯错的高级工程师。它提供的是一条更不容易跳步的路径，并要求把「完成了」的判断落到测试、diff 和 review 等可检查的证据上。

对初学者而言，最值得先学的不是 14 个 Skill 的名字，而是三个习惯：先分清事实与业务选择，先为重要行为准备验证，再让每条规则接受前后对照的检验。做到这三点后，再决定要不要引入 worktree、子 Agent 或更严格的流程，才不会把工程方法变成一套昂贵的仪式。

参考资料

• Superpowers v6.1.1 仓库与 README
• SessionStart Hook
• using-superpowers Skill
• brainstorming Skill
• test-driven-development Skill
• subagent-driven-development Skill
• writing-skills Skill
• 贡献指南 CLAUDE.md