你有没有遇到过这种情况：对 AI 编程助手说“帮我做一个待办事项应用”，它立刻开始写代码。文件一个接一个地涌出，几百行代码很快出现在屏幕上。
然后你发现：它完全猜错了你的需求。
问题不在某个 AI 的 bug，而在很多 AI 编码代理的默认行为：收到请求就行动，没有停下来问“你真正想要的是什么”。在 demo 里，这种反应速度看起来很厉害；但在真实项目里，它往往意味着需求没问清、架构先拍脑袋、测试最后再补，最后你花更多时间收拾残局。
Superpowers 这个开源项目做了一件看似反直觉的事：给 AI 编程助手装上一套“技能库”，让它在动手之前先停下来匹配方法。重点不在让 AI 写得更快，而在让 AI 先用对流程。
我的判断是：Superpowers 值得读，靠的不是又发明了一个新 Agent 框架，靠的是它抓住了 AI 编程最容易失控的地方：AI 太愿意行动，却太不愿意先确认。
一、仓库信息卡片
| Project | obra/superpowers |
| Stars | 236k+，截至 2026-06-23 GitHub API 查询 |
| Language | Shell |
| License | MIT |
| Latest release | v6.0.3 |
| 一句话价值 | 把 AI 编码代理从“听到需求就开写”，拉回到“先匹配技能、再走流程、最后验证结果”的工程化路径。 |
| Codex | 15 分钟了解架构原理：Superpowers Codex 解读 |
| Classroom | 40 分钟看交互 PPT / 视频讲解：Superpowers Classroom |
这是一份非官方学习伴读，源项目事实仍然以 obra/superpowers 为准。我会把能在源码、本地 Codex 页面、DeepWiki / Classroom 采集材料里对上的内容当作事实来写；涉及架构取舍、学习路径和工程启发的部分，则是我顺着代码读下来后的分析和补充。
二、一张大图先看懂 Superpowers
这张图可以先按三层看。
第一层是会话入口。Superpowers 会在 AI 会话启动时，把 using-superpowers 这个元技能注入上下文。这个元技能不处理具体任务；它告诉 Agent：接下来做任何事之前，都要先检查有没有适用技能。
第二层是技能库。brainstorming 负责需求澄清，writing-plans 负责把设计拆成可执行计划，test-driven-development 约束测试顺序，systematic-debugging 约束排查路径，subagent-driven-development 负责把大任务拆给子 Agent 执行。
第三层是平台适配。Claude Code、Cursor、OpenCode、Codex、Gemini CLI、GitHub Copilot CLI 的插件机制都不一样，Superpowers 的做法是尽量把平台差异放在 shim、hook、tool mapping 里，把真正的方法论沉到 skills/ 目录。
所以它的核心已经超出“某个平台的插件”，更接近一个跨平台的 AI 编码工作流协议。
三、技术选型：它到底选了什么，不选什么
这一节直接用 Codex 课程里的选型判断。
Superpowers 真正要比较的对象，并非 LangGraph、CrewAI 这类业务 Agent 编排框架。它不关注“怎么把多个业务 Agent 串起来”，它关注“怎么给 AI 编程助手定规矩，并让它真的执行”。
所以它面对的是四条路线：
| 裸用 Claude Code | 无，靠每次手打提示 | 基本无约束，行为很依赖当轮上下文 | 一次性问答、写小脚本、临时探索 |
| CLAUDE.md / AGENTS.md 规则 | 会话开始被动注入 | 软建议，AI 可能遵守，也可能绕过 | 单项目编码规范、团队约定、轻量流程提示 |
| Cursor Rules | 编辑器内按文件或上下文匹配 | 中等约束，但绑定 Cursor 工作流 | 深度使用 Cursor 的团队 |
| Superpowers | SessionStart Hook 主动加载技能体系 | 硬门控，可以阻断错误流程 | 需要 AI 严格执行工程纪律的个人或小团队 |
这张表的重点不在“谁功能更多”，重点在五个维度的取舍：
| 触发 | AI 看到规则才可能使用 | 会话开始主动注入，第一轮回复前生效 |
| 强度 | 建议提醒 | HARD-GATE 硬阻断 |
| 复用 | 通常绑定单个项目 | 技能可以跨项目组合和迁移 |
| 门槛 | 写几行规则就能用 | 要维护一套 SKILL.md 技能体系 |
| 平台 | 通用文本，迁移成本低 | 依赖 Hook / Skill / Tool Mapping 适配层 |
这里最关键的差别是：前三者本质上都是“建议”，Superpowers 追求的是“纪律”。比如一个需求还没澄清，普通规则只能提醒 AI “最好先问清楚”；Superpowers 的 brainstorming 技能会把它变成硬门控：设计没有得到确认前，不应该进入写代码阶段。
如果只看表层，它像一堆 Markdown；如果看实现，它其实是四个东西的组合：
— SessionStart Hook
| +– 把元技能注入上下文，让规则在第一轮回复前生效
|
+– Skill Registry
| +– 用 SKILL.md 的 frontmatter 做发现和触发
|
+– Tool Mapping
| +– 把 Claude Code 的工具语义翻译到 Codex / Gemini / Copilot / OpenCode
|
+– Workflow Protocol
+– 把 brainstorming、planning、TDD、subagent、review 串成可审查流程
更关键的是它的几个工程取舍。
| 如何触发流程 | Slash command，比如 /brainstorm | 直接用 Skill / native skill discovery | Slash command 依赖平台命令系统，跨平台成本高；Skill 可以通过描述字段做语义触发 |
| 如何让规则生效 | 把说明写进 README / 项目文档 | SessionStart 同步注入 using-superpowers | 文档不进上下文就等于不存在；同步 hook 保证第一轮回复前已加载 |
| 如何跨平台 | 每个平台写一套技能 | 共享 skills，平台侧只做 shim 和 tool mapping | 方法论保持一份，工具名差异放在映射层，减少版本漂移 |
| 如何处理用户自定义 | 核心规则不可覆盖 | 用户指令最高优先级，项目 / 个人技能可覆盖 | AI 需要流程，但用户仍然拥有最终控制权 |
| 如何处理复杂任务 | 一个长上下文 Agent 做到底 | fresh subagent per task + 两阶段 review | 降低上下文污染，把规格符合度和代码质量拆开审查 |
| 如何写计划 | 大纲式 TODO | 明确文件、接口、测试、命令、期望输出 | 计划要能交给“没上下文的执行者”，否则子 Agent 会重新猜 |
但这不代表所有人都应该上 Superpowers。Codex 课程里的判断很克制：如果你只是想让 AI 记住几条项目规范，先用 CLAUDE.md 或 AGENTS.md。如果你已经发现 AI 经常跳过测试、不先设计就写代码、在 bug 里反复打转、对模糊需求直接动手，才值得引入 Superpowers。
适合引入的场景很明确：
- 你重度使用 Claude Code / Cursor / Codex 这类编程 Agent；
- 你的痛点不是“模型不够聪明”，而是“AI 不守纪律”；
- 你有重复性工作流想固化，比如 TDD、系统化调试、代码审查、计划拆解；
- 你愿意持续维护 Markdown 技能文件，而不是只想要一次性提示词；
- 你的团队能接受 AI 被流程门控阻断，而不是随时直接开写。
不适合的场景也很明确：
- 你想找一个运行时 SDK，把它集成进自己的产品；
- 你的 Agent 工具不支持 Hook、Skill 或类似机制；
- 你的任务大多是改一两行的小修，全流程会变成负担；
- 你不希望 AI 行为被硬门控阻断；
- 你的团队没有人愿意维护 SKILL.md 体系。
所以最后的选型结论是：要建议，用项目规则；要纪律，再上 Superpowers。
这几个选择连起来看，Superpowers 其实在反对三件事。
第一，反对把 AI 流程做成“靠人记得输入命令”的命令系统。所以 v5.1.0 起，旧的 /brainstorm、/write-plan、/execute-plan 这类命令存根被移除，转向技能发现和技能调用。
第二，反对把团队规范做成“希望 AI 会自觉遵守”的静态文档。它用 SessionStart hook 把元技能塞进上下文，而且 hooks.json 里 async: false，意味着这一步必须在会话继续前完成。
第三，反对每个平台维护一套方法论。Claude Code、Cursor、Codex、Gemini CLI、OpenCode、Copilot CLI 的工具名和插件机制都不一样，但 Superpowers 尽量让 skill 讲“动作语义”，再由平台映射到具体工具。
所以它真正要回答的问题，不是“AI 会不会写代码”；它要回答“AI 能不能被一个稳定协议约束住”。
四、核心原理：一次请求如何穿过 Superpowers
还是回到开头那个例子：你说“帮我做一个待办事项应用”。
没有 Superpowers 时，AI 很可能直接进入实现：创建文件、写组件、补样式、顺手选技术栈。 装了 Superpowers 后，真正发生的是一条拦截链。
1. 会话启动：先把“元技能”放进上下文
Superpowers 最重要的第一步发生在用户发消息之前，也就是会话启动阶段。
Claude Code / Cursor / Copilot 这类平台通过 hook 机制触发 hooks/session-start。Codex 侧还有独立的 hooks-codex.json 和 session-start-codex。这些脚本做的事情很克制：
— 读取 skills/using-superpowers/SKILL.md
+– 对内容做 JSON 转义
+– 判断当前平台需要哪种输出格式
+– 输出 additionalContext / hookSpecificOutput.additionalContext
+– 让 Agent 在第一轮回复前看到技能协议
这里有几个工程细节值得注意。
run-hook.cmd 是一个 polyglot wrapper，同一个文件要能在 Windows CMD 和 Unix bash 下工作。因为 Cursor / Claude Code 在 Windows 上执行 hook 时可能走 cmd.exe，直接跑 bash 脚本会失效，所以它会寻找 Git Bash 或 PATH 里的 bash.exe，再转交给真正的 session-start。
session-start 里没有依赖 jq；它用 bash 参数替换处理 \\、"、换行、回车、tab。这个选择看起来土，但很工程化：插件要在用户刚装好的环境里跑，不能假设用户机器上一定有完整工具链。
最后输出格式还要分平台：
| Cursor | additional_context |
| Claude Code | hookSpecificOutput.additionalContext |
| Copilot CLI / SDK 风格平台 | additionalContext |
| Codex | session-start-codex 输出 hookSpecificOutput.additionalContext |
这一步解决的是“规则如何进入模型上下文”的问题。很多 AI 工程规范失效，根本原因往往不在规范写得差，而在模型根本没稳定看到它。
2. 元技能：把“建议”改成强制检查
进入上下文的是 using-superpowers。它不像普通说明文，更像整套系统的启动协议。
它做了三件事。
第一，定义 1% 规则：只要有一点可能某个技能适用，就必须先调用技能。重点不在那个百分比本身，重点是把“我觉得不用”这类主观判断压到最低。
第二，规定调用时机：技能检查发生在任何回复或行动之前，甚至在澄清问题之前。也就是说，Agent 不能先说“我问几个问题”，再想起来要不要用 brainstorming；它应该先判断有没有过程技能适用。
第三，明确优先级：用户显式指令最高，Superpowers 技能其次，默认系统行为最低。这个设计很重要，因为如果技能凌驾于用户指令之上，它就会变成另一个不可控的黑箱。
这其实是在解决 AI 编程代理的一个隐性缺陷：模型知道好流程，却太容易在具体任务里为跳过流程找理由。
3. Skill 发现：description 是路由索引，不是简介
Skill 的文件形态很简单：一个目录，一个 SKILL.md。
但它不是随便写一篇 Markdown。文件头部的 YAML frontmatter 至少包含两个字段：
name: brainstorming
description: "You MUST use this before any creative work …"
这里的 description 是整个系统的路由索引。Agent 不靠人工点菜单来选技能；它会把当前任务和每个 skill 的描述做语义匹配。
这就解释了为什么 Superpowers 的技能描述往往写得很“硬”：You MUST use this before any creative work。这属于触发策略，不是文风问题。描述写成“helps with planning”就太软，模型很容易把它当成可选参考；写成明确触发条件，才更像一个路由规则。
实现里还有一层 resolution 逻辑：如果同名技能存在多处，系统按优先级查找。典型顺序是项目级技能优先，其次个人技能，最后才是 Superpowers 内置技能。这样你可以覆盖默认流程，而不是被框架锁死。
request skill: brainstorming
|
+– project skill exists?
| +– yes -> use project version
|
+– personal skill exists?
| +– yes -> use personal version
|
+– core superpowers skill exists?
+– yes -> use library version
这就是它和“把规则写死在插件里”的区别：Superpowers 提供默认工程纪律，但不剥夺项目自己的规则。
4. Tool Mapping：同一套技能怎么跑在不同平台
Superpowers 的技能大多以 Claude Code 的动作语义书写，比如 Skill、Task、TodoWrite、Read、Edit、Bash。
问题是，Gemini CLI、Codex、Copilot CLI 不叫这些名字。直接复制技能会导致 Agent 读懂了流程，却不知道本平台该用什么工具执行。
所以它引入了 tool mapping layer。这个层不做复杂 runtime，只提供一张“工具语义翻译表”。
| 调用技能 | activate_skill | 原生 skill loading | skill |
| 创建 todo | write_todos | update_plan | todos table / sql |
| 派发子 Agent | @generalist | spawn_agent | task |
| 读文件 | read_file | shell / native file tools | view |
| 改文件 | replace / write_file | apply_patch / native file tools | edit / create |
| 跑命令 | run_shell_command | shell | bash |
Codex 这边还有一个具体要求：如果要支持 subagent-driven-development 这类技能，需要在配置里启用 multi-agent，让 spawn_agent、wait_agent、close_agent 可用。
这个设计的价值在于：技能作者不需要为每个平台重写一套流程，只要动作语义稳定，平台适配可以单独演进。
5. Workflow Protocol：它不是调用一个技能就结束
Superpowers 的真正深度在 workflow protocol。
拿“新增一个功能”来说，brainstorming 不是普通头脑风暴，它有一个 HARD-GATE：设计没有展示并获得用户确认之前，禁止调用实现技能、禁止写代码、禁止脚手架项目。
这一步解决的是需求阶段的失控：AI 最容易把“我理解了”误判成“我可以开写了”。
设计通过之后，writing-plans 会把需求拆成实施计划。它对计划质量要求很重：先列文件结构，再拆任务；任务要有明确文件、接口、测试、命令、期望输出；不能写 TBD、TODO、类似 Task N、添加适当错误处理这种占位句。
这一步解决的是交接阶段的失控：如果计划只是大纲，后面的执行 Agent 还是会重新猜。
执行阶段，subagent-driven-development 继续往下约束：
— 主 Agent 读取 plan，创建 todo
+– 每个 task 派一个 fresh implementer subagent
+– 子 Agent 独立实现、测试、自审
+– 主 Agent 生成 review package
+– task reviewer 做两阶段审查
| +– spec compliance: 是否符合规格
| +– code quality: 代码质量是否过关
+– 不通过则派 fix subagent
+– 全部完成后再做 whole-branch review
这里最有意思的是 fresh subagent 和两阶段 review。
fresh subagent 的价值不在“多开几个 AI 干活”，而在控制上下文污染。主会话里有大量讨论、历史、偏好和中间判断，执行一个小任务时并不都需要。子 Agent 只拿任务 brief、接口、约束和报告契约，反而更不容易被无关上下文带偏。
两阶段 review 也不是仪式感。spec compliance 问的是“做没做对”，code quality 问的是“写得好不好”。这两个问题如果混在一次审查里，审查者很容易被一个维度影响另一个维度：功能对了就放过烂实现，或者代码漂亮但漏需求。
这才是 Superpowers 比普通 Prompt 模板深的地方。它给 AI 的不是一段“请认真一点”的话；它在需求、计划、执行、审查、收尾每个阶段都加了可触发的协议。
6. 这套架构的代价
Superpowers 不是没有代价。
它会让第一次响应变慢。以前你说一句“加深色模式”，AI 立刻开写；现在它可能先触发 brainstorming，读项目上下文，问你跟随系统还是手动切换，是否要持久化偏好。
它也会显得“重”。对改一个 typo、调一个按钮颜色这种任务，全套流程确实可能过度。
但它的判断是：真实项目里，最贵的地方不在 AI 少写了几分钟代码，真正贵的是 AI 在错误方向上写得太快。只要这个判断成立，Superpowers 的协议化设计就有意义。
五、Classroom PPT 深度预览：用交互模拟看懂命令与脚本链路
如果只读 GitHub README，你大概率会理解 Superpowers 的概念，但不一定能形成一条学习路径。Classroom 版本做的事情，是把这个仓库拆成一套可以顺着看的交互课程。
这部分不只是贴图。Superpowers Classroom 的优势在于 PPT 可以超出静态页面：课程数据里既有 slide，也有 interactive 场景；交互页可以通过动作脚本逐步高亮节点、切换平台状态、模拟工具映射和输出日志，让用户更快理解“命令怎么触发、脚本怎么注入、平台怎么适配”。
下面 8 张是从完整 Classroom 里精选出来的核心场景，其中包含交互页播放到最后一步后的最终态截图。真正打开 Classroom 后，读者可以按课程动作一步步看它如何从用户请求走到 Hook、Skill、Tool Mapping 和 Workflow Protocol。
1. 课程导读与全景规划
第一张图解决的是“我为什么要学这个”。它把 Superpowers 从一个 GitHub 仓库，转成一套学习任务：先理解项目定位，再理解 Skill 系统，再进入架构、工具映射和开发工作流。
这对新读者很重要。因为 Superpowers 很容易被误解成“又一个 Prompt 集合”，但它真正值得读的地方在方法论和触发机制。
2. 项目定位与方法论价值
这一页对应本文开头的问题：AI 为什么会一听需求就开始写代码。课程把 Superpowers 的价值放在“行为约束”上，而不是“能力增强”上。
这个定位很准确。很多 AI 工具都在强调更快、更强、更自动化；Superpowers 反过来强调“该慢的时候慢下来”。
3. 核心概念速览全景图
这张图是交互页播放到最后一步后的最终态。课程动作会按顺序高亮输入源、平台集成层、配置入口、核心逻辑和技能映射节点，把用户请求、自然语言空间、平台集成层、核心逻辑层、实体空间和 Skill Entity Mapping 串成一条完整链路。
这比单独解释每个模块更直观：Superpowers 的价值不止某个孤立技能，它把“用户意图 -> 平台注入 -> 核心调度 -> 技能实体映射”变成闭环。
4. Mandatory Skill Check Protocol
这一页对应本文的核心判断：Superpowers 不停留在建议 AI “最好先想想”，它把技能检查做成协议。
如果你只记住一个设计，就是这个：在任何行动前，Agent 都要先判断有没有技能适用。它用强约束去对抗 AI 的默认冲动。
5. Architecture 整体架构
这一页讲的是系统架构：会话入口、元技能、核心技能、多平台适配，各自在哪一层。
如果你想快速判断这个仓库值不值得深入读，先看这一页。它能帮你判断：Superpowers 不属于业务 Agent 框架，更接近面向 AI 编码代理的工程流程框架。
6. Tool Mapping Layer 工具映射
这一页对应正文里的跨平台适配。Claude Code、Codex、Gemini、Copilot 的工具名不一样，但技能希望表达的是动作语义。
Tool Mapping Layer 的作用就是把 Skill、Task、TodoWrite 这类动作翻译到不同平台的真实工具上，避免每个平台重写一套方法论。
完整课堂里还有对应的交互式映射页：可以在 Claude Code、Copilot、Gemini、Codex 之间切换状态，右侧输出面板会模拟各平台工具调用的解析日志。这类交互比单纯看表格更适合讲清楚“同一条技能指令，为什么到不同平台会变成不同命令”。
7. Complete Workflow Pipeline
这一页把从 brainstorming 到 planning、worktree、TDD、subagent、review、finish 的完整开发链路串起来。
看懂这张图，就能理解为什么 Superpowers 不只是一个技能列表。它真正想做的是把 AI 编码过程变成一条可审查的工程流水线。
8. Subagent-Driven Development
最后这张图讲 fresh subagent 的价值：目标不在多开几个 AI，而在隔离上下文、防止上下文污染，并通过 review 把结果重新收束回来。
这也是 Superpowers 最值得工程团队借鉴的地方：当任务变复杂时，不要让一个长上下文 Agent 从头扛到尾，而是把任务、上下文、验证和审查拆开。
完整 PPT 不止这些截图。这里放的是精选核心预览，目的是让你先确认这套课的讲解路径和内容质量。
六、写在最后
Superpowers 给我的最大启发不止是“你也应该安装这个插件”。它引出了另一个更底层的问题：当 AI 开始替我们写越来越多代码时，我们到底要把什么东西写进流程里。
以前我们写工程规范，是给人看的。现在这些规范还要能被 AI 触发、理解、执行和验证。 这可能会变成 AI 原生软件工程里很重要的一类基础设施。
想要完整 PPT：关注本账号，回复「superpowers」获取。 想看下一个开源项目解读：在评论区留下仓库名。
