obra/superpowers —— Jesse Vincent（Prime Radiant）开源的「AI 编码代理开发方法论」插件。不是工具库，而是一整套用自然语言写成、靠心理学与流程闸门约束 LLM 行为的可安装软件工程流程。
Superpowers 的定位一句话：把「先设计 → 再计划 → 子代理逐任务实现 → 双重评审 → 验证后合并」的完整方法论，做成一个跨 10 个编码代理平台可安装的插件。它不含一行业务代码，主体是 14 个 Markdown skill + 少量 bash/js 胶水，靠 SessionStart hook 在每个会话开头强制注入「必须用 skill」的元规则。
作者 Jesse Vincent（RT 请求跟踪系统、K-9 Mail 的作者），2025-10 首发，现由 Prime Radiant 公司维护并提供商业支持——这个项目本身已经从个人实验演化成产品。
Prompt 工程产品：用自然语言 + 流程闸门给 LLM 装「工程纪律」，可类比「给 agent 装的 ISO 流程体系」。
LLM 会在压力下合理化偷懒；对策不是更多规则，而是预先封死每一条合理化路径（rationalization table + red flags）。
SDD（subagent-driven development）的上下文经济学设计，和「用 TDD 方法写文档」的 writing-skills 元技能。
单源多分发：skills 只维护一份，各平台目录只放 manifest / 加载器；Codex 走 sync-to-codex-plugin.sh（466 行）做打包同步。这跟我们仓库 .agents/skills/（单源）→ .claude/skills/（分发）是同一个思路,但它做到了 10 个平台。平台差异（Codex 需要 multi_agent = true、Pi 原生支持 skills 等）收敛在 using-superpowers/references/*-tools.md 里,由元 skill 按需路由,而不是在每个 skill 里写 if-else——适配成本被压到了一个文件一平台。
整个系统的引导只有一个 hook：hooks/session-start（49 行 bash）。它在 startup|clear|compact 三个时机把 using-superpowers/SKILL.md 全文读出来、JSON 转义后包进 <EXTREMELY_IMPORTANT> 标签注入上下文：
# 平台探测：同一 hook 输出三种 JSON 形态
if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
printf '{ "additional_context": "%s" }' # Cursor: snake_case
elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ]; then
printf '{ "hookSpecificOutput": { "hookEventName": "SessionStart",
"additionalContext": "%s" } }' # Claude Code: 嵌套
else
printf '{ "additionalContext": "%s" }' # Copilot CLI / SDK 标准
fi三个源码细节值得注意：
${s//\\/\\\\} 等 5 连），注释明确说这是从逐字符循环重写来的性能优化——C 级单遍替换。没引入 jq/python 依赖，保证 hook 零依赖可移植。additional_context 和 hookSpecificOutput 且不去重——双发会导致内容注入两遍。这是踩坑后的防御。被注入的 using-superpowers 本体只有 62 行，但它是全系统的「宪法」：
If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill. … This is not negotiable. You cannot rationalize your way out of this.
并附一张 12 行的「危险念头 → 现实」对照表（"这只是个简单问题" / "我先看看代码" / "这个 skill 有点大材小用"……每条都是实测中 agent 用来跳过 skill 的借口）。同时明确优先级：用户指令 > skill > 默认行为，以及子代理豁免（<SUBAGENT-STOP>——被派活的子代理不再递归加载方法论,防止流程套流程）。
用 <HARD-GATE> 标签禁止在设计获批前写任何代码，并直接点名最常见的逃逸路径："这太简单了不需要设计"是反模式——todo list、单函数工具、改配置,全都要过设计。流程终态被显式钉死:「brainstorming 之后唯一允许调用的 skill 是 writing-plans」——防止 agent 拿到设计就自己开跑。问问题的纪律也做了约束:一次只问一个、优先多选题。
v6 新增「visual companion」:一个本地 HTTP server(scripts/server.cjs)在浏览器里展示 mockup/图表,规定只在「看比读更清楚」的问题上用,且 offer 必须是独立消息。注意:其 logo 从官网加载并带版本号,是项目唯一的遥测点(README 坦白说明,可用 SUPERPOWERS_DISABLE_TELEMETRY 关闭)。
计划文档的写作标准是给「零上下文、不懂测试设计」的执行者看的:每步一个动作(2-5 分钟)、精确文件路径、完整代码块、精确命令+预期输出。「No Placeholders」清单把 "TBD"、"add appropriate error handling"、"similar to Task N" 都定义为计划写作失败。每个任务带 Interfaces: 块(consumes/produces 精确签名)——因为执行任务的子代理只能看到自己的任务,这个块是它了解邻居任务接口的唯一渠道。这是为「无共享上下文的并行体」设计文档的典型手法。
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
写在测试前的代码?删除。不许留作"参考",不许边写测试边"改编",不许看它。Delete means delete.371 行里近半篇幅在逐条反驳合理化借口("我已经手测过了"/"删掉 X 小时的工作太浪费了"→沉没成本谬误/"TDD 太教条,我要务实"→务实=测试先行)。配套的 testing-anti-patterns.md 立了三条铁律:不许测 mock 行为、不许给生产类加 test-only 方法、不许不理解依赖就 mock。
subagent-driven-development(418 行 + 2 个 prompt 模板 + 3 个脚本)是整个项目工程含量最高的部分。模式:每个任务派一个全新子代理实现 → 任务级评审(spec 合规 + 代码质量双裁决) → 全部完成后再做一次全分支评审。控制器(主会话)只做编排,不碰实现。
这是它对「多代理编排烧 token」问题的系统性回答,每条都有实测事故背书:
| 机制 | 实现 | 防的事故(源码注释原文背书) |
|---|---|---|
| task-brief 脚本 | awk 从计划文档抽取单个任务全文到文件,子代理一次 Read 读入 | 任务文本经控制器 prompt 粘贴会常驻其上下文,每轮重读付费 |
| review-package 脚本 | git log --oneline + diff --stat + diff -U10 三段写入唯一命名文件,评审者读文件 | diff 从不进入控制器上下文;强调 BASE 用派发前记录的 SHA 而非 HEAD~1(后者会静默丢掉多 commit 任务的前几个 commit) |
| 报告文件契约 | 实现者全文报告写 task-N-report.md,只返回 ≤15 行摘要(状态/commit/一行测试总结) | 子代理打印回来的所有内容都会常驻控制器上下文 |
| 禁止粘贴历史 | "派发 prompt 描述一个任务,不描述会话历史" | 实测有 42k 字符的派发 prompt,99% 是粘贴的前序任务总结 |
| 进度台账 | .superpowers/sdd/progress.md 每任务追加一行(commit 区间+评审结论) | compaction 后控制器忘了做到哪,重派整段已完成任务序列——观测到的最贵事故 |
| 最终评审单修复者 | 全分支评审的 findings 派一个修复子代理带完整清单,不许一个 finding 一个修复者 | 实测一次 final-review 修复波的开销超过之前所有任务之和 |
skill 里有一节完整的模型选型经济学:机械转录型任务(计划里已含完整代码)用最便宜档;评审用中档起步;全分支终审必须用最强模型;派发时必须显式指定 model——不指定会静默继承主会话(通常最贵)的模型。还有一个反直觉洞察:轮次数比单价更决定成本——最便宜的模型做多步任务常要 2-3 倍轮次,总价反而更高。
实现者侧的心理安全设计同样少见:prompt 明写「说'这对我太难了'永远是 OK 的。坏活比不干更糟,升级不会被惩罚」,配 4 态状态机(DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT),控制器对 BLOCKED 有明确处置阶梯(补上下文→换更强模型→拆任务→升级到人),并禁止「不做任何改变就让同一模型重试」。
这是 Superpowers 区别于一般 prompt 集合的地方:它把「让 LLM 守规矩」当成一个有研究文献支撑的工程问题。persuasion-principles.md 引用 Meincke et al. (2025, N=28,000) ——说服技巧使 AI 合规率从 33% 提到 72%——并系统运用 Cialdini 七原则:
"YOU MUST"、"No exceptions"、Iron Law 命名——消除决策疲劳和合理化空间。
强制宣告"I'm using [skill] to [purpose]"、强制建 todo——公开承诺提高后续一致性。
每个纪律 skill 都有「借口→现实」表,条目全部来自基线测试中 agent 的逐字原话,不是作者想象。
"如果你正在想 X,停"——把违规前的念头本身做成触发器。
更精细的是「Match the Form to the Failure」:v6 加入的实证结论——禁止式规则只对「知规而违」的纪律失败有效;对「输出形状不对」的问题,禁止式措辞反而比不写还差(A/B 措辞测试中禁止组产出更多不想要的内容),该用「正向配方」(直接规定输出长什么样)。还有两条反直觉规则:「nuance 从句会重新打开谈判」(给获胜配方加一句"除非确有必要"就把稳定输出变成噪声)、「豁免从句不起作用」("此限制不适用于代码块"仍会抑制代码块——必须重构规则让它够不着豁免区)。
689 行的元技能,核心主张:写 skill 就是对流程文档做 TDD。映射关系完整:压力场景=测试用例;无 skill 跑基线看 agent 怎么违规=RED;写 skill 针对性封堵=GREEN;发现新借口就补条目再测=REFACTOR。Iron Law 同款:「没有失败测试就没有 skill」,对编辑既有 skill 同样适用。
两个有直接实操价值的发现:
claude CLI 验证 skill 触发行为、验证 worktree 路径策略、验证 SessionStart hook 输出格式。还有 analyze-token-usage.py 分析测试会话的 token 消耗——他们把 token 成本当作被测指标。bump-version.sh(220 行)+ Codex 打包/同步脚本(约 800 行)——多平台分发的复杂度都沉在这里。lint-shell.sh 全仓库 shellcheck;hook 里连 bash 版本 bug 的 workaround 都带 issue 链接。| 评价 | |
|---|---|
| 强 | 每条规则都有事故或实验背书。"42k 字符派发 prompt"、"重派已完成任务是最贵事故"、"HEAD~1 丢 commit"——这些注释说明规则是从真实运行的尸检里长出来的,不是纸上设计。这跟我们 .learnings/ 驱动规则演化是同一方法论,但它把结论直接内嵌进了规则正文。 |
| 强 | SDD 的上下文经济学是当前公开资料里最完整的多代理编排成本设计:工件走文件、报告限 15 行、台账抗 compaction、模型分层+轮次成本模型,自成一套可验证的体系。 |
| 强 | 把 prompt 措辞当可测对象(微测试+对照组+方差指标)在开源项目里几乎独一份,方法论可以直接搬用。 |
| 弱 | 全体系强依赖"每任务 2-5 分钟粒度 + 计划含完整代码"的前提。这对绿地小项目成立;对大型存量单体(跨模块契约、迁移链、共享 DB),计划阶段写出完整正确代码本身就是最难的部分,SDD 退化为"控制器替所有人写代码"。它自己也承认要靠 brainstorming 阶段拆子项目来绕。 |
| 弱 | TDD Iron Law 一刀切。"写在测试前的代码必须删除"对探索型工作(调 UI、试 API、原型)代价极高,exceptions 只留了"问人"。我们仓库明确走"集成测试为主、不写 mock-heavy 单测"路线,与其单测倾向的 RED-GREEN 循环有真实张力(见 §10)。 |
| 弱 | 高压措辞的军备竞赛属性。EXTREMELY_IMPORTANT、"1% 可能就必须调用"、每 skill 数百行反合理化条款——对每个会话都是常驻 token 税,且模型每代对齐性变化后这些措辞需要重新校准(他们自己用 evals 应对,但维护成本随平台×模型矩阵增长)。 |
| 险 | 无验证的流程真空区。verification-before-completion 只约束"跑命令看输出",没有我们 §17 意义上的"端到端真验"(多角色真点、真数据走查);评审全部基于 diff 阅读,行为正确性完全押在实现者跑的测试上——测试本身写歪时缺兜底层。 |
我们的 skill 体系(.agents/skills/ + CLAUDE.md 硬门)和 Superpowers 是同类系统的两个演化分支:它面向通用绿地开发、跨平台分发,我们面向单一大型业务仓库、契约面治理。逐项对照:
| 维度 | Superpowers | 我们(FFOA) | 判断 |
|---|---|---|---|
| 设计先行闸 | brainstorming HARD-GATE:设计获批前禁写代码 | §20 方案→计划→执行 + 执行预告三要素 + contract-check | 等价 双方都封了"直接开写";我们多了契约面判定,它多了"一次一问"的提问纪律(可借鉴) |
| 计划规格 | 2-5 分钟步 + 完整代码 + Interfaces 块 + No Placeholders 清单 | plan-feature / writing 计划较自由 | 可借鉴 No Placeholders 失败清单和 Interfaces(consumes/produces)块值得吸收进 plan 模板 |
| 子代理编排 | SDD:工件走文件、报告≤15行、progress 台账、模型分层 | Workflow 工具 + Agent fork;唤醒纪律铁律(token 成本) | 可借鉴 台账抗 compaction、review-package/task-brief 脚本化、"禁止粘贴历史"三条可直接落进我们的编排实践 |
| 测试哲学 | TDD Iron Law,单测粒度 RED-GREEN,先删后写 | 内真外假:集成测试为主、明确不写 mock-heavy 单测、5 条红线 CI 硬阻 | 冲突 不可直接引入;但它的 testing-anti-patterns 三铁律(别测 mock/别加 test-only 方法)与我们红线完全同向 |
| 完工验证 | verification-before-completion:跑命令拿证据才许宣称 | §17 本地真验硬门 + exploratory-verification 矩阵走查 | 我们更强 它停在"命令证据",我们要求端到端行为真验;但它的"禁止满意语气先于验证"措辞更锋利,可搬 |
| 规则写作方法 | writing-skills:基线测试→写规则→封堵循环;微测试;description 只写触发条件 | skill-creator / skill-audit,主要靠人审 | 最值得借鉴 "description 概括流程会让正文被跳过"这一实证发现,应立即对照检查我们全部 skill 的 description |
| 调试方法 | systematic-debugging 4 阶段 + 3 修不好即质疑架构 | 11 号三层拆解 + 排查取证闸 + 12 号五元根因 | 等价 双方几乎逐条对应;"3+ 次修复失败=架构问题不是假设问题"这条显式升级规则我们没有,可补 |
| 评审防腐 | 写/评 prompt 独立、禁止预判 finding、plan-mandated 仍是 finding | §20 审与执行 prompt 独立、ai-review verdict 门 | 可借鉴 "禁止在评审 prompt 里出现 do-not-flag"和"计划钦定的缺陷仍报"两条是我们没有明文的防腐条款 |