Agent 方法论框架 superpowers：只给流程，不给新工具
本文基于 superpowers 仓库 commit 44c9b2d（2026-07-27）梳理，该项目仍在持续迭代，具体行为以仓库 https://github.com/obra/superpowers 最新代码与文档为准。
superpowers 的核心不是它有多少个技能文件，而是它敢在会话第一句话之前就把「你必须先查技能」这条规则塞进上下文——它卖的是强制力，不是功能。
你装完之后不会多出任何一个新命令行工具、任何一个 MCP 服务、任何一个模型。你的编码 Agent 还是原来那个 Agent。变化只有一处：它接下来的每一次行动，都要先过一遍「有没有对应的技能」这道关卡。这个设计决定了它的全部价值，也决定了它全部的招人烦之处。
本篇把这个项目的构成、约束的生效路径、以及它明确不管的事情讲清楚。这是本系列的入口，后续篇会把它与 ECC（https://github.com/affaan-m/ECC ）、pi（https://github.com/earendil-works/pi ）放在一起做对照。
一、它解决的问题：Agent 知道方法论，但不照做
站内已经写过通用的 Agent 框架横向对比 和 规格驱动开发 SDD，那两篇讲的是方法论本身长什么样、该怎么组织流程。本篇讲的是另一件事：一个具体的开源项目，是用什么工程手段把这类方法论真的按在 Agent 头上执行的。方法论人人会写，难的是让一个随时想抄近路的 Agent 老实走完。
你大概率遇到过这个场景：你在 CLAUDE.md 里写清楚了「先写测试再写实现」，Agent 前两轮乖乖照做，第三轮碰到一个「看起来很简单」的改动，就直接把实现写了出来。你再提醒它，它会诚恳道歉，然后下一次继续犯。
superpowers 的仓库 README 把自己描述为「a complete software development methodology for your coding agents」，构建方式是一组可组合的技能，外加一些确保 Agent 真去用它们的初始指令。注意后半句——「确保 Agent 真去用它们」这部分，才是这个项目真正花力气的地方。
它对症的不是「Agent 不知道怎么做」，而是「Agent 知道但会自我说服跳过」。所以它的对策不是写更详细的教程，而是把 Agent 用来说服自己的那些话，一条条列出来，提前堵死。
二、约束是怎么生效的：从会话启动的第一毫秒开始
这套东西的生效链条比想象中短，短到你可以在半小时内读完全部关键代码。
链条起点是 hooks/hooks.json。它注册了一个 SessionStart 钩子，matcher 写的是 startup|clear|compact——会话启动、清空上下文、以及上下文压缩之后，各触发一次。压缩后重新触发这一点很关键：长会话被压缩掉的往往正是那些规则性内容，压缩完再注入一遍，规则才不会跟着上下文一起蒸发。
hooks.json 里登记的命令并不直接指向脚本，而是指向 hooks/run-hook.cmd。这个文件是个双解释的包装器：Windows 下 cmd 按批处理跑，去几个常见位置找 Git Bash，找不到就静默退出而不是报错——注释里写明了这样做的取舍，宁可少一次上下文注入，也不要让插件在没有 bash 的机器上炸掉。Unix 下同一个文件被当 shell 脚本执行，直接转交给同目录的脚本。
真正干活的是 hooks/session-start。它做的事情朴素得有点出人意料：把 skills/using-superpowers/SKILL.md 整个文件读出来，用 bash 的参数替换逐类转义成 JSON 字符串，再包进一段 <EXTREMELY_IMPORTANT> 标签里输出。输出这一步分了三个分支，靠环境变量判断当前宿主：Cursor 认下划线风格的顶层字段，Claude Code 认嵌套在 SessionStart 事件对象里的那个字段，其余宿主走 SDK 标准的顶层字段。脚本注释里特意说明了为什么必须三选一而不能一起吐——Claude Code 会把两种字段都读进去且不去重，同时输出等于把同一份规则塞两遍。
也就是说，同一份内容按不同宿主的约定换个包装再吐出去。这解释了为什么 README 的安装章节能列出那么多种宿主——Claude Code、Antigravity、Codex、Cursor、Factory Droid、Gemini CLI、GitHub Copilot CLI、Kimi Code、OpenCode、Pi。适配层做的是格式转换，方法论本体一份不变。这也是判断一个宿主集成是不是真集成的分水岭：只把技能文件拷过去，等于只有本体没有注入。
被注入的 using-superpowers 文件本身，写法比一般的规范文档凶得多。它开头就是一段 <EXTREMELY-IMPORTANT>：只要你觉得有 1% 的可能某个技能适用，就必须调用它；技能适用时你没有选择权；这不可协商，你没法把自己说服过去。
紧接着是一张叫 Red Flags 的表，左列是 Agent 的心理活动，右列是驳回理由。摘几行原文对照：
| Thought | Reality |
|---|---|
| ”This is just a simple question” | Questions are tasks. Check for skills. |
| ”The skill is overkill” | Simple things become complex. Use it. |
| ”I remember this skill” | Skills evolve. Read current version. |
这张表是整个项目设计取向最集中的体现。它默认 Agent 会为跳过流程编理由，于是把常见理由预先写成清单，让 Agent 在产生这个念头的瞬间就识别出「我正在合理化」。仓库的 CLAUDE.md 里专门有一句：不要在没有 eval 证据的情况下修改这类被精心调过的内容，Red Flags 表和合理化清单被点名列为不得随意改动的对象。
三、它由什么组成
skills/ 目录下是 14 个技能，每个是一个目录，主文件都叫 SKILL.md，带 name 和 description 两个 frontmatter 字段。下表是几块主要构件，仓库位置都是可以直接打开核对的真实路径：
| 组成部分 | 它负责什么 | 对应仓库位置 | 你什么时候会碰到它 |
|---|---|---|---|
| 会话启动钩子 | 每次启动、清空、压缩后注入引导内容 | hooks/hooks.json、hooks/session-start | 装完就在跑，平时无感 |
| 引导技能 | 定规矩：任何回应之前先查技能；含 Red Flags 表 | skills/using-superpowers/SKILL.md | 每个会话开头 |
| 头脑风暴 | 一次一问逼出需求，出设计稿，落盘成 spec | skills/brainstorming/SKILL.md | 你说「我们来做个 X」时 |
| 写计划 | 把设计拆成 2-5 分钟粒度的任务，含文件路径与验证步骤 | skills/writing-plans/SKILL.md | 设计通过之后 |
| 子代理驱动开发 | 每个任务派一个全新子代理，做完两段评审 | skills/subagent-driven-development/SKILL.md | 你说「开始干」之后 |
| 测试驱动开发 | 强制红绿循环，测试之前写的实现代码要删掉重来 | skills/test-driven-development/SKILL.md | 每次动实现代码 |
| 系统化调试 | 四阶段根因流程，没做完第一阶段不许提修复方案 | skills/systematic-debugging/SKILL.md | 出 bug、测试挂了 |
| 完工前验证 | 宣称「做完了」之前必须跑命令拿证据 | skills/verification-before-completion/SKILL.md | 你以为要收工的时候 |
| 写技能 | 教你怎么新增和测试技能 | skills/writing-skills/SKILL.md | 想自己扩展的时候 |
| 贡献守则 | 对 AI 贡献者的硬要求 | CLAUDE.md、AGENTS.md、GEMINI.md | 你想提 PR 的时候 |
除此之外还有若干配套文件值得单独提一句：skills/subagent-driven-development/ 下有 implementer-prompt.md、task-reviewer-prompt.md、re-review-prompt.md 三份提示词，实现者和评审者各用各的；skills/brainstorming/ 下有 spec-document-reviewer-prompt.md 和 visual-companion.md；skills/writing-skills/ 下有 persuasion-principles.md 和 testing-skills-with-subagents.md。角色拆分的思路和站内 Agent 角色分工 那篇讲的是同一类问题，区别是这里每个角色的提示词都以文件形式固化在仓库里，可以直接读。
许可证是 MIT。插件元数据在 .claude-plugin/plugin.json。
四、一条完整流水线走下来是什么样
README 的 The Basic Workflow 章节给了七步顺序，这七步不是建议，末尾那句写得很直白：Mandatory workflows, not suggestions。
你说「做个待办列表」，Agent 不写代码，先进头脑风暴。这个技能的 SKILL.md 里有一段 <HARD-GATE>：在你批准设计之前，不许调用任何实现技能、不许写代码、不许搭脚手架。它还专门有一节标题叫「Anti-Pattern: This Is Too Simple To Need A Design」，明说待办列表、单函数工具、配置修改，全都要走这个流程，设计可以短到几句话，但必须呈现出来并获得批准。提问规则是一次一个问题，一条消息只问一件事。
设计定稿后，落盘到 docs/superpowers/specs/ 下的日期命名文件并提交。然后是隔离工作区，再进写计划。计划文件的粒度要求写得很死：一个步骤就是一个动作，2 到 5 分钟——「写失败的测试」是一步，「跑一遍确认它失败」是一步，「写最小实现」是一步。写计划技能开头那句话很能说明它的假设：假设执行者对你的代码库零上下文、品味可疑。
进入实现阶段，主 Agent 不亲自写代码，而是每个任务派一个全新的子代理，做完之后过任务评审（先看是否符合规格，再看代码质量），全部任务结束再来一次整分支评审。这个技能里有一条对协作节奏影响很大的规定：任务之间不许停下来问人，除非遇到无法解决的阻塞或真正的歧义，「要不要继续？」这类询问被明确认定为浪费时间。
实现的每一步受 TDD 技能约束，它的铁律原文只有一行：NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST。后面跟着一句执行细则——测试之前写的代码，删掉，重来；不许留着当参考，不许边写测试边改它，不许再看它一眼。
想收工的时候还有一道关。完工前验证技能的铁律是 NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE，并且补了一句判定标准：如果你没有在这条消息里跑过验证命令，你就不能说它通过。这跟站内 验收标准怎么定 讨论的是同一类痛点，这里的做法是把「拿证据」变成一个不能跳过的门函数。
五、边界与代价：它明确不管什么
这套设计的取舍相当激进，值得逐条摊开。
它放弃了速度。 一个五行的改动，走完头脑风暴、设计落盘、写计划、TDD、两段评审，成本远高于你自己改。项目自己也承认这是全流程适用的，包括配置修改——这不是它没想到，是它有意为之。代价就是对小改动而言，这是不折不扣的过度设计。如果你的日常工作大量是零散的小修补，装上它你会被烦到想卸载。
它让 Agent 变啰嗦。 每次调技能要宣布「Using [skill] to [purpose]」，有清单的技能要求给每一项建一个 todo。这些都在消耗上下文和 token。技能文件本身也不短，注入的引导内容每次压缩后还要重来一遍。上下文预算紧张的场景需要提前算账，可以参考 Agent 上下文管理 里的思路。
它不管模型能力。 它约束的是流程顺序和行为边界，不会让模型更会写代码。模型选型、推理质量、token 定价，全在它的范围之外。
它不管你的技术栈。 仓库的 CLAUDE.md 明确写了，核心库只收通用技能，领域专用、工具专用、工作流专用的东西应当发布成独立插件。同一份文件里还写了 zero-dependency by design——引入第三方依赖的 PR 不会被接受，除非是新增宿主支持。所以别指望它自带你那套构建系统的知识。
它不适合探索性场景。 需求还没成型、你只是想快速试几个方向看看手感的时候，一个坚持要先出设计文档再动手的 Agent 会把节奏打断。从随手写到工程化本身有个过渡期，这一点在 从 vibe coding 到工程化 里讨论过，superpowers 站的是过渡完成之后那一端。
它不保证团队会接受。 「不许跳步」在个人项目里是自律，在多人协作里可能变成摩擦源。别人接手你这个仓库，看到 docs/superpowers/specs/ 和 docs/superpowers/plans/ 下堆的一叠文档，未必买账。
六、上手与避坑清单
先确认引导真的被注入了，别只看文件在不在盘上。 会踩是因为技能文件复制过去就摆在那儿，肉眼看着装好了，但没有会话启动注入，Agent 根本不会主动去读它们。仓库的 CLAUDE.md 在新宿主支持那一节给了一个可以自己跑的验收测试：开一个干净会话，发送一句「Let’s make a react todo list」，一个真正生效的集成会在写任何代码之前自动触发 brainstorming 技能。怎么避——照这句话试一次，没触发就是没装好。
多宿主要分别装。 会踩是因为你以为技能库是一份、装一次就够。README 的安装章节第一句就写了：安装方式因宿主而异，如果你用不止一个宿主，每个都要单独装。怎么避——按 README 里对应宿主那一小节的命令来，别跨着抄。
别指望它替你判断该不该跳过。 会踩是因为你觉得「小改动它应该会自己放宽」。它不会，头脑风暴技能里那个反模式小节就是专门堵这条路的。怎么避——using-superpowers 结尾写明了，用户指令优先于技能、技能优先于默认行为，只有你的人类搭档明确说了跳过，才能跳过。所以要绕开就明说，别指望它自己心领神会。
别顺手改技能文件。 会踩是因为你觉得某段措辞啰嗦、某张表冗余，想精简一下。仓库的 CLAUDE.md 有一整节讲这件事：技能不是散文，是塑造 Agent 行为的代码；修改行为塑造类内容的门槛非常高，需要 eval 证据。怎么避——真要改就用 writing-skills 技能，并跑一遍评测，别凭手感动刀。
想提 PR 先读贡献守则。 会踩是因为你让 Agent 去「给这个仓库贡献点东西」。CLAUDE.md 开头就对 AI Agent 喊停，要求你填完 .github/PULL_REQUEST_TEMPLATE.md 的每一节、搜索已有的开放和已关闭 PR、确认这是真实遇到的问题、披露自己的模型与宿主版本与已装插件、并让人类看过完整 diff。它还规定所有 PR 必须提交到 dev 分支而不是 main。怎么避——没有真实踩过的问题就别提 PR。
遥测想关就关。 README 说明了头脑风暴的可选视觉伴侣功能会从官网加载一个 logo，其中包含所使用的 superpowers 版本，不包含项目、提示词、宿主的信息。设置环境变量 SUPERPOWERS_DISABLE_TELEMETRY 为任意真值即可关闭，它同时也遵守 DISABLE_TELEMETRY 和 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC。
收束：三个问题判断你要不要装
装之前问自己三句话。第一，你的痛点是不是「Agent 知道规矩但会跳步」——如果是模型写不对代码，装它没用。第二，你能不能接受一个五行改动也要先出设计——不能接受就别装，或者只在大改动的会话里用。第三，你手上的项目有没有可跑的测试基线——TDD 和完工前验证这两个技能的全部约束力都建立在「有命令能跑出证据」之上，没有测试，它们退化成口号。
接下来该读哪个文件：从 skills/using-superpowers/SKILL.md 开始，它最短，也最能看出这个项目的脾气；然后是 hooks/session-start，看约束是怎么进到上下文里的；再看 skills/brainstorming/SKILL.md 里的 <HARD-GATE> 和 skills/test-driven-development/SKILL.md 里的 Iron Law，这两处是它最硬的地方，也是你最可能想绕过的地方。
本文属于 superpowers 方法论专题（共 30 篇，含三篇与其它开源 Agent 项目的对照）。想看把资产铺满的另一种取向，见 ECC 开源 Agent 套件专题。