本文是我在团队做 AI 编码落地调研时，对一个开源 agentic skills 框架（Superpowers）的个人实践记录。 我会以一个真实项目的视角，讲清楚它到底解决了什么问题、核心原理是什么、怎么从零上手、 以及——它有哪些坑和局限。这不是项目功能说明书，而是一份选型调研 + 踩坑笔记。
一、先说我遇到的问题
过去一年，我和团队在把 coding agent 真正接进生产流程时，反复撞上同一堵墙：
agent 很会"聊"，但很难"交付"。
你让它写一个功能，它噼里啪啦给你一段代码，看着挺像回事；但一跑，报错；你让它修，它又给一版；你再跑，又崩。最后你发现，它不是在"开发"，而是在"猜"。没有测试、没有验证、没有可复用的过程，每一次都是重新掷骰子。
我们内部把这称为「聊天式建议」困局：
- 它不写测试，所以你永远不知道它对不对；
- 它不做计划，所以一个多步骤任务会被拆得乱七八糟；
- 它不验证，所以"看起来能跑"被当成了"真的能跑"；
- 它不收敛，所以同一个 bug 能被反复修三遍。
我当时的判断是：问题不在模型能力，而在"流程缺失"。 模型再强，如果没有一套强制性的工程纪律约束它，它就会退化成"聪明但不可靠的实习生"。
带着这个判断，我开始调研市面上那些号称"能把 agent 变成真正开发者"的框架。这篇文章的主角 —— Superpowers —— 就是我在这个过程中接触到的、对我启发最大的一个。
二、它是什么：一句话版本
Superpowers 是一套面向 coding agent 的软件开发方法论，构建在若干可组合的「skills」之上，外加一段让 agent 强制使用这些 skills 的初始指令。
用我自己的话翻译一下：它不是"一个工具"，而是一套"工作流 + 纪律"。 它把软件开发拆成一条流水线，每个环节都对应一个 skill，agent 必须按顺序走完，不能跳步。
这条流水线大致是：
brainstorming（头脑风暴出 spec）
↓
writing-plans（写实现计划）
↓
executing-plans / subagent-driven-development（执行）
↓
verification-before-completion（完成前验证）
↓
finishing-a-development-branch（收尾合并）
你会发现，这条链路和我之前研究的 Spec-Driven Development 方法论高度同构：先有规格、再有计划、任务可验证、最后闭环。这也是我为什么对这个框架格外感兴趣——它把一套我脑子里的抽象方法论，变成了 agent 能实际执行的硬约束。
三、核心原理：为什么"强制调用 skill"是关键
Superpowers 最反直觉、也最核心的设计，是一个看起来有点"专制"的规则：
哪怕只有 1% 的可能某个 skill 适用，你也必须调用它。 如果某个 skill 适用于你的任务，你没有选择。
这句话我第一次看到时觉得夸张。但真正用起来才发现，它是整个框架的灵魂。
3.1 为什么"强制"比"建议"有效
普通的 agent，你给它一堆 best practice，它大概率会"选择性忽略"。为什么？因为模型是概率驱动的，它倾向于走阻力最小的路径——直接写代码、直接给答案，因为这样"看起来更高效"。
而 Superpowers 的做法是把这些 best practice 变成不可跳过的关卡：
- 进入计划模式前，必须先头脑风暴；
- 写任何生产代码前，必须先写一个失败的测试；
- 声称"做完了"之前，必须先跑验证命令并展示输出。
这些不是"建议"，是铁律（Iron Law）。agent 一旦违反，就违背了它的核心指令。这就像给一个"聪明但爱偷懒"的实习生套上了一套强制 SOP——它再想走捷径，也迈不过去。
3.2 Skill 优先级：流程优先于实现
Superpowers 里还有个很讲究的规则：当多个 skill 同时适用时，流程类 skill 优先。 流程类 skill 先定"怎么做"，实现类 skill 再去"把它做出来"。
这背后是一个深刻的认识：先定方法，再动手。 很多 agent 之所以翻车，不是因为不会写代码，而是因为没想清楚"该用什么流程"就一头扎进去了。
3.3 为什么这套东西能"交付真实工作"
我最后总结出它区别于"聊天式 agent"的三个关键机制：
- 有规格：先头脑风暴出 spec，不是上来就写代码；
- 有计划和验证：每个任务都有确切的文件路径、完整代码、验证步骤；
- 有闭环：完成前必须跑验证，收尾时合并分支。
这三条加起来，恰好补齐了我在第一节说的"聊天式建议"的四个缺陷。所以它不是模型更强，而是流程更硬。
四、从入门到精通：一条完整的实操路径
下面我按"第一次接触 → 跑通一个真实任务 → 理解内部机制 → 进阶玩法"的顺序，把整个使用过程讲清楚。这部分是我实际操作时的记录，不是官方文档搬运。
4.1 第一步：安装与初始化
Superpowers 最常见的接入方式有两种，取决于你用的 agent 工具：
方式一：通过插件市场（适合 Claude Code）
在 Claude Code 里添加插件市场，然后安装 Superpowers 插件。装完之后，/skills 命令可以看到所有可用的 skill。
方式二：通过 skills CLI（通用）
用一条命令把 Superpowers 的 skills 装进你的 agent 环境：
npx skills add obra/superpowers
装完你会看到它带了一整套 skills，包括 brainstorming、writing-plans、test-driven-development、systematic-debugging 等。
我的建议：第一次用，别急着跑任务。 先花十分钟把
using-superpowers这个元技能读一遍。它是整个框架的"总开关"，讲清楚了 agent 该怎么发现和使用其他 skill。不看它，你会以为这只是个普通插件库。
4.2 第二步：理解目录结构
装好后，Superpowers 的 skills 会以目录形式存在，每个 skill 是一个文件夹，里面有个核心文件 SKILL.md，外加一些配套文件（比如 testing-anti-patterns.md、graphviz-conventions.dot 等）。
SKILL.md 是 skill 的"说明书"，里面写着：
- 何时使用（When to Use）：触发条件；
- 核心原则 / 铁律（Iron Law）：不可违反的硬约束；
- 具体步骤：agent 应该怎么做；
- 配套资源：指向同目录下的辅助文件。
这个结构让我意识到一件事：一个 skill 的"说明书"本身，就是它质量的关键。 写得好的 SKILL.md，让 agent 一看就知道"什么时候该用、该怎么用、不能违反什么"。
4.3 第三步：从 idea 到 spec —— 用 brainstorming
我第一次真正跑通 Superpowers，是从一个"给内部工具加个导出功能"的需求开始的。
按它的流程，第一步不是写代码，而是头脑风暴。这一步会：
- 判断需要多少流程：这个需求是简单的、中等的，还是复杂的？
- 理解上下文：探索现有代码库，搞清楚现状；
- 逐个澄清：一次只问一个问题，不轰炸你；
- 提出方案：给出 2–3 个设计思路；
- 等你批准：你确认后，才进入下一步。
最让我印象深刻的，是它一次只问一个问题。很多 agent 恨不得一口气抛给你十个问题，而它选择渐进式确认。这大大降低了"被信息淹没"的感觉。
这一步结束后，它会把设计写成一份 spec 文档，存放在 docs/superpowers/specs/ 目录下。而且它还会自检：检查 spec 里有没有占位符、有没有前后矛盾。
我的踩坑：别跳过这一步。 有一次我图快，直接让它"写个导出功能"，结果它跳过 brainstorming，直接开写，最后做出来的东西跟我想要的根本不是一回事。后来我老老实实走完 spec 流程，一次就对了。
4.4 第四步：从 spec 到计划 —— 用 writing-plans
spec 定稿后，进入 writing-plans。这一步会把功能拆解成一口一个（bite-sized）、可测试的任务。
它的关键设定是：写给一个从没看过这份代码库和 spec 的工程师看。 这意味着每个任务必须包含：
- 确切的文件路径：改哪个文件，写到哪；
- 完整的代码：不是"你懂的"，而是直接给全；
- 验证步骤：怎么确认这一步做对了。
这个设定非常高明。因为它逼着写计划的人把"模糊的意图"变成"可执行的指令"。如果一个任务连"改哪个文件、写完怎么验证"都说不清楚，那这个任务本身就是没想清楚。
而且，每个任务里都嵌入了 TDD 步骤——先写失败测试（RED），再让它通过（GREEN），最后重构（REFACTOR）。也就是说，计划不是"给你一堆待办"，而是"给你一堆可验证的、带测试的、有明确完成标准的小步骤"。
4.5 第五步：执行 —— 两种方式
计划写好后，有两条执行路径：
路径 A：executing-plans（顺序执行）
读取计划，严格按顺序执行，不做任何改动，分批进行，并在人类检查点停下来等你确认。
路径 B：subagent-driven-development（子代理驱动）
这是我个人更推荐、也更"专业"的方式。它会：
- 为每个任务派发一个全新的子代理（fresh subagent）；
- 每个任务完成后做两阶段审查：
- 先查 spec 合规（做的是不是 spec 要的东西）；
- 再查代码质量（写得好不好）；
- 最后做一次整条分支的总体审查。
为什么要用子代理？核心原因是上下文隔离。每个子代理只专注于自己的任务，不会因为前面任务的上下文而"污染"判断。这就像把一个大型开发任务拆给多个专注的工程师，而不是让一个人从头到尾扛着所有上下文。
我的踩坑：子代理方式更慢，但更可靠。 第一次用的时候，我嫌它"每步都要审查"太慢，就选了顺序执行。结果确实快，但有一个任务因为上下文混淆，做错了方向，返工的成本远超"慢"省下的时间。后来我学乖了：重要的、多步骤的任务，一律用子代理方式。
4.6 第六步：验证 —— verification-before-completion
这是整个框架里我最喜欢、也最"硬"的一条铁律：
没有完成声明，除非有新鲜的验证证据。 如果你没有在本条消息里运行过验证命令，你就不能声称它通过了。
这句话直击要害。它杜绝了 agent 最常犯的毛病——"看起来能跑"被当成"真的能跑"。
实际执行中，agent 必须：
- 运行验证命令（比如跑测试、跑 lint、跑构建）；
- 把输出展示给你看；
- 然后才能声称"完成了"。
如果验证失败，它不能"假装完成"，必须回去修，再验证，直到真的通过。
我的踩坑：这条铁律救了我很多次。 有一次 agent 说"导出功能写好了"，我按它的说法以为搞定了。但因为它没跑验证（或者跑了没展示），我后来手动一测，发现根本没生效。自从我强制要求"必须展示验证输出"，这类"假完成"就基本绝迹了。
4.7 第七步：收尾 —— finishing-a-development-branch
任务完成后，它不会把一堆半成品丢在那里。它会：
- 验证测试是否全部通过；
- 给你几个选项：合并 / 提 PR / 保留 / 丢弃；
- 清理工作区（worktree）。
这一步解决了"开发分支烂尾"的问题。很多 agent 干完活就不管了，留下一堆没合并、没清理的分支。而 Superpowers 强制走完这个收尾流程。
五、常见问题排查：systematic-debugging
除了主流程，Superpowers 还带了一个我非常喜欢的 skill：systematic-debugging（系统化调试）。
它的核心纪律是：
- 先复现，再修复（reproduce before you fix）；
- 一次只验证一个假设（one hypothesis at a time）；
- 找到根因，而不是打补丁。
这跟很多 agent"猜一个原因就改，改了不对再猜"的做法截然相反。它要求你：先稳定复现问题 → 定位 → 提出一个假设 → 用一个最小验证步骤去验证 → 确认根因 → 才动手修。
我的踩坑：这条几乎是我用过最"反直觉但最有效"的调试纪律。 一旦你习惯了"一次只测一个假设"，你会发现调试效率反而更高，因为每一轮都有确定的结论，而不是在碰运气。
六、踩坑与局限：它没那么完美
上面讲了很多它的优点。但作为一份调研记录，我必须把它的缺点和局限也讲清楚——这也是我判断一个工具值不值得用的关键。
6.1 它很"重"，对简单任务有点杀鸡用牛刀
这套流程是为复杂的、多步骤的开发任务设计的。但如果你只是改个文案、修个 typo，让它走完整的 brainstorming → spec → plan → subagent → review 流程，你会觉得极度繁琐。
它自己也承认这一点：会先判断"这个需求需要多少流程"。但实际用下来，这个判断并不总是准确的。有时一个简单任务，它也会启动一堆子代理，烧掉大量 token，最后只改了一行代码。
我的建议：简单任务别用完整流程。 我会在指令里明确告诉它"这是简单任务，不要走完整流程"，否则你会被流程本身拖垮。
6.2 token 消耗非常大
这是它最实际的成本问题。子代理 + 两阶段审查 + 每步验证，意味着每个任务都要多次调用模型。一个中等复杂度的功能，token 消耗可能是普通 agent 写法的 3–5 倍。
如果你用的是按 token 计费的模型，这笔账必须算清楚。它省下的是"返工"的时间，但花掉的是"流程"的 token。 到底值不值，取决于你的任务复杂度。
6.3 对"一次性、探索性"任务不友好
它的流程是线性的、面向交付的。但如果你是在做技术探索——比如"这个库能不能跑通""这个思路可不可行"——这种探索性的、可能随时推翻重来的任务，套上这套严谨流程反而会拖慢你的探索节奏。
探索阶段需要的是快速试错，而不是严谨的 spec 和测试。这是它最不擅长的场景。
6.4 "强制调用"可能带来误触发
前面说过，它的核心规则是"哪怕 1% 可能适用也要调用"。这带来一个副作用：skill 可能在不该触发的时候触发。
比如，你只是想问一个简单问题，它却因为"可能适用"而启动了 brainstorming。这种"过度触发"会让对话变得很啰嗦，也会消耗额外 token。它自己也承认这一点，并建议用户在遇到这种情况时明确告诉它"不要用某个 skill"。
6.5 依赖 agent 对 skill 的"理解能力"
这套框架的有效性，高度依赖底层 agent 是否能正确理解并遵循 SKILL.md 的指令。如果模型能力不足，它可能"读了但没执行"——比如明明要求先写失败测试，它却直接写实现。
也就是说，Superpowers 是放大器，不是替代品。 它能把一个"有纪律的 agent"变得更强，但没法把一个"没有纪律的 agent"变得有纪律。底层模型不行，这套框架反而会因为"流程复杂"而更容易出错。
6.6 与用户指令的优先级冲突
它有个规则是"用户指令优先于 skill 规则"。这本身是对的。但实际用起来有个坑：如果用户在指令里说了"不用 TDD"，而 skill 里说"必须 TDD"，agent 需要正确判断以哪个为准。
这个判断有时会出错。比如用户随口说了一句"这次别写测试"，agent 可能就整个任务都不写测试了，哪怕这个任务其实很需要测试。你需要学会精确地表达你的意图，而不是含糊其辞。
七、适用边界：它适合什么，不适合什么
基于上面的踩坑，我总结了一份适用边界，这也是我判断"什么时候该用它"的参考。
适合的场景
- 复杂的、多步骤的功能开发：需要拆解、验证、闭环的任务；
- 有明确验收标准的需求：能写成 spec 和测试的需求；
- 多人协作的代码库：需要上下文隔离、避免互相污染的任务；
- 对质量要求高的生产代码：宁可慢一点，也要保证正确性的任务；
- 需要长期维护的模块：有测试兜底，后续改动更安全。
不适合的场景
- 简单改动 / typo / 文案：走完整流程纯属浪费；
- 技术探索 / 快速原型：需要快速试错，而不是严谨流程；
- 一次性脚本：用完即弃，不值得投入流程成本；
- 对 token 成本敏感的团队：流程开销可能远超收益；
- 底层模型能力不足：框架无法弥补模型本身的纪律缺失。
八、它和我之前研究的 Spec-Driven Development 是什么关系
我在团队里一直推行一套叫 Spec-Driven Development（规格驱动开发） 的方法论。接触 Superpowers 之后，我发现两者高度同构，但侧重点不同。
相同之处
- 先有规格，再写代码：都强调"想清楚再动手"；
- 任务可验证：都要求每个任务有明确的完成标准；
- 强调闭环：都反对"看起来能跑"的假完成；
- 把方法论变成可执行的流程：都不是停留在理念层面。
不同之处
- Spec-Driven 是"方法论"：它是一套理念和最佳实践，需要人去执行，或者靠团队约定来落地；
- Superpowers 是"工程实现"：它是一套已经被写成代码/指令的、agent 能直接执行的流程。
换句话说，Spec-Driven 是"道"，Superpowers 是"术"的落地。 如果你已经在团队里推行了 Spec-Driven，那么 Superpowers 可以看作是把这套方法论自动化的工具；如果你还没接触过 Spec-Driven，那 Superpowers 本身就是一条很好的入门路径——因为它把抽象的"规格驱动"变成了 agent 必须遵守的硬约束。
这也解释了为什么我特别认可它：它把我脑子里那套"理想中的 agent 开发流程"真正变成了现实。
九、我的最终结论
最后，回到我开头的问题：coding agent 怎么才能从"聊天建议"变成"交付真实工作"？
我的答案是：光靠模型不够，必须有流程；而流程要真正生效，必须变成不可跳过的硬约束。
Superpowers 给我的最大启发，不是它发明了什么新东西——它没有。它只是把软件开发领域那些早就被验证过的最佳实践（规格先行、TDD、系统化调试、完成前验证、分支收尾），强制性地塞进了 agent 的执行流程里。
它的价值在于：让 agent 无法偷懒。 当"先写测试""跑验证再声明完成"变成不可违反的铁律时，agent 就不再是"聪明的实习生"，而是"守规矩的工程师"。
但我也要诚实地说：它不是银弹。 它太重、太耗 token、对探索性任务不友好、依赖底层模型能力。它适合的是**"重要的、复杂的、质量要求高的"生产开发**，而不是所有场景。
如果你也在被"agent 很会聊但不会交付"困扰，我建议你先别急着上完整流程，而是从它最核心的那条铁律开始：
没有验证证据，就没有完成。
光是这一条，就能让你的 agent 从"看起来能跑"进化到"真的能跑"。
