Pre

Superpowers - 01 让 AI 真正“懂工程”：Superpowers 软件开发工作流深度解析

Superpowers - 02 用 15 个技能给你的 AI 装上「工程大脑」：Superpowers 快速开始深度解析

Superpowers - 03 一文搞懂 Superpowers：面向多平台 AI 编码助手的安装与实践指南

面向读者：已经在用 Claude Code、Cursor、Copilot、Gemini 等 AI 编码工具的开发者，以及在做 AI Agent / 工具链设计的工程师与研究者。

---

一、为什么我们需要一个“给 AI 上工程课”的架构？

大模型编码助手已经足够“会写代码”，但离“会做工程”还差一大截：它们会在没有需求澄清的前提下直接开写、跳过测试驱动开发（TDD）、忽略设计规范，甚至在一次长对话中逐渐“遗忘”最初的约束。

Superpowers 的设计目标，就是通过一套零运行时依赖的指令架构，把这种“冲动写代码”的行为纠正为可控、可审计、可组合的工程工作流。

换句话说，Superpowers 不给你一套运行时代码框架，而是给你的 AI coding agent 上了一门“软件工程实践课”，并通过 Markdown 技能和平台钩子，强制它按流程办事。

---

二、全局视角：Superpowers 是什么，它到底改变了什么？

2.1 定义：一个“零依赖、可组合的工作流引擎”

在架构层面，Superpowers 有几个非常鲜明的特征：

• 零运行时依赖：核心完全由 Markdown、Shell 脚本和少量插件描述构成，没有必须引入的语言运行时、SDK 或服务端组件。
• 指令架构而非代码框架：所有“能力”都体现在 SKILL.md、Hooks 配置和 Agent 提示词中，这些文档本身就是行为定义。
• 跨多平台统一行为：通过不同平台的 Hook / 插件系统，在 Claude Code、Cursor、Copilot CLI、Gemini CLI、Codex、OpenCode 上实现尽可能一致的体验。

它最核心的价值：拦截“直接写代码”的自然倾向，替换为“头脑风暴 → 设计 → 计划 → subagent 执行 → TDD → 系统化调试 → 代码审查”的强制工作流。

2.2 三大机制：支撑这一切的基础

Superpowers 的行为变革依赖三大机制：

1. 钩子注入（SessionStart Hook 等）：确保每次新会话、一键清空之后，AI 都会重新加载“使用 Superpowers”这套总控技能。
2. 技能发现与触发：基于技能前置数据中的 description 等字段，自动匹配用户意图并选择要激活的技能。
3. 强制工作流门控（硬性门控）：每个技能末尾定义“未完成不得前进”的条件，直到用户确认或清单完成才能进入下一阶段。

可以把它理解为：在不改动模型本身的前提下，通过“系统提示词 + 技能协议 + 平台钩子”，搭起一个软性的但非常严密的工程流程外骨骼。

---

三、仓库结构：从目录布局看设计哲学

Superpowers 仓库很“干净”，但每个目录都承担清晰的架构职责。

3.1 顶层目录一览

该仓库组织为五个顶级目录，每个目录服务于不同的架构目的。理解此布局是导航和扩展系统的关键。

目录	用途说明	示例关键文件
hooks/	各平台会话初始化脚本、Hook 配置	session-start、hooks.json
skills/	工作流技能，每个技能一个独立 SKILL.md	brainstorming/、test-driven-development/ 等
agents/	专业化 subagent 角色提示词	code-reviewer.md
commands/	旧版斜杠命令（现在已被技能替代）	brainstorm.md 等
docs/	规格文档、平台 README、测试说明	README.codex.md、testing.md
tests/	按平台/能力划分的集成测试	claude-code/、opencode/ 等

这个结构传递了一个信号：技能和提示词是“一等公民”，测试也不是附属品，而是架构的一部分。

---

四、第一层：平台适配与会话注入——怎么让每个平台都“听话”？

Superpowers 要做的是“全平台统一行为”，但现实世界的 AI IDE/CLI 各有一套插件体系。
第一层架构就是通过多种注入手段，把同一套 using-superpowers 技能植入到不同平台的会话生命周期中。

4.1 SessionStart Hook：最主力的注入方式

SessionStart 是最关键的入口，它在以下时机触发：

• 新开一个 AI 会话
• 执行 /clear 或 /compact 等“重置上下文”的指令后

在这些时刻，hooks/session-start 脚本会：

1. 读取 skills/using-superpowers/SKILL.md 的内容。
2. 根据当前平台的环境变量（如 CURSOR_PLUGIN_ROOT、CLAUDE_PLUGIN_ROOT、COPILOT_CLI）判断运行环境。
3. 输出各平台要求的 JSON 结构，将技能内容注入为“额外上下文”。

表格化理解会更直观：

平台	环境变量检测	输出 JSON 字段
Cursor	CURSOR_PLUGIN_ROOT	{ "additional_context": "..." }
Claude Code	CLAUDE_PLUGIN_ROOT 且非 COPILOT_CLI	{ "hookSpecificOutput": { "additionalContext": "..." } }
Copilot/其他	COPILOT_CLI 或默认	{ "additionalContext": "..." }

钩子配置通过 hooks/hooks.json 和 hooks/hooks-cursor.json 分别在 Claude/Copilot 和 Cursor 中注册对应的事件触发规则。

---

4.2 备选注入路径：兼容不支持钩子的平台

有些平台不提供 Session Hook，这时 Superpowers 使用替代路径：

• Gemini CLI：通过 GEMINI.md 中的 @-include 指令，引入 using-superpowers 技能以及 Gemini 专用的工具映射说明。
• Codex：利用其原生“技能发现机制”，要求用户创建从 ~/.agents/skills/superpowers/ 指向仓库 skills/ 的符号链接。
• OpenCode：基于 Bun 的插件，在 config 钩子中注册技能，并通过 experimental.chat.system.transform 注入引导上下文。

这些路径最终都指向同一个事实：using-superpowers 是整个系统行为的唯一入口，如果这个技能没被注入，Superpowers 就不存在。

---

五、第二层：技能引擎——“技能即行为代码”

如果说 Hook 负责“把 Superpowers 带进房间”，那技能引擎就负责“规定 AI 在房间里该怎么表现”。

5.1 SKILL.md 的解剖：一个技能长什么样？

每个技能都是一个独立的 SKILL.md，结构由 writing-skills 这个元技能规定：

组件	作用
YAML 前置数据	定义 name / description，驱动平台解析和自动激活匹配
作用域门控	避免 subagent 再次触发同一流程技能，防止递归与重复
指令优先级说明	明确“用户 > 技能 > 默认系统提示词”的指令层级
检查清单	可转化为 Todo/Task 的步骤列表，构成操作的主干
流程图（DOT）	用 Graphviz 描述技能内部决策流程，便于人类和工具理解
危险信号表	罗列常见“合理化借口”及其反制策略，防止跳过关键步骤
硬性门控	明确“不满足什么条件就不能往下执行”的硬规则

特别要强调的是 description：它不仅是文案，而是自动激活触发器。平台会用它来做语义匹配，当用户请求“看起来有 1% 可能相关”时，也会倾向于调用对应技能。

---

5.2 刚性技能 vs 弹性技能

Superpowers 把技能分成两大类：

• 刚性技能：比如 test-driven-development、systematic-debugging，要求模型必须严格遵守，任何偏离都被视为流程失败。
• 弹性技能：比如 brainstorming、writing-plans，提供原则与步骤，但允许模型根据上下文做一定调整。

用一个例子来感受差异：

• 使用 TDD 技能时，agent 必须先写失败测试，再实现代码，再运行并修正，直到测试通过。
• 使用头脑风暴技能时，则可以在“列举多个方案 → 比较 → 选择”的框架内，根据项目情况灵活取舍内容。

---

5.3 工具映射：跨平台复用技能的关键

技能内部使用的工具名称以 Claude Code 为“母语”（如 Skill、TodoWrite、Task）。
在其他平台上，要通过映射文件做名称转换：

• references/copilot-tools.md：把 Skill 映射为 Copilot CLI 的 skill 工具等。
• references/codex-tools.md：映射到 Codex 对应的工具。
• references/gemini-tools.md：为 Gemini CLI 提供自动加载的工具映射说明。

在 OpenCode 中，这个转换由插件层负责，插件自动在 Claude 和 OpenCode 工具名之间做转换。这样一来，同一个技能文件可以在多平台直接复用。

---

六、第三层：开发工作流管道——从“一句需求”到“可审计交付”的全过程

第三层是 Superpowers 的“灵魂”：如何把“帮我做个功能”这句话，拆解成一条可验证的工程流水线。

6.1 强制的技能序列与硬性门控

工作流的形态大致是这样的：

1. brainstorming：澄清目标、提出多种方案、讨论权衡。
2. writing-plans：把选定方案拆解为任务、定义验收条件。
3. subagent-driven-development：按任务创建 subagent，执行实现与审查。
4. test-driven-development：在适当阶段嵌入 TDD 流程。
5. systematic-debugging：出现问题时调用调试技能。
6. code-review 工作流：最终进行规范与质量审查。

每个技能都是一个“硬性门控”：

• 未完成当前技能的检查清单
• 或者用户没有明确确认输出

都不能进入下一技能。比如在 brainstorming 阶段，会明确写着“在设计方案展示并获得用户批准前，不得开始任何实现工作”。

---

6.2 Subagent 驱动架构：用“任务隔离”对抗上下文污染

最复杂的技能是 subagent-driven-development。它解决的是一个常见问题：单个对话上下文会逐渐污染模型的行为，越到后期越偏离最初规范。

Superpowers 的做法是：

• 对于计划中的每个任务，创建一个全新的 subagent，并给它一组专门的指令（含上下文裁剪）。
• 任务完成后，触发两阶段审查：
  • 规范合规性审查：专门的审查者 subagent 检查是否符合原始设计/计划。
  • 代码质量审查：另一位审查者从架构、可维护性、风格等维度评估质量。

这种模式有几个好处：

• 每个任务在相对独立、干净的上下文中执行，降低“之前对话越攒越乱”的风险。
• 审查者不被开发过程的“情绪”影响，只对照规范和质量标准来评价。
• 自然形成了一种接近“多人协作”的结构，只不过这些角色都是由同一个基础模型扮演。

在测试目录中，甚至有端到端 subagent 工作流案例，例如 Go 分形项目、Svelte 待办应用的完整流水线，用来回归验证这一架构。

---

七、第四层：Agent 定义——把“角色”变成可复用构件

除了技能，Superpowers 还定义了可复用的 Agent 角色，目前主要集中在代码审查方向。

7.1 代码审查 Agent：一个专业 reviewer 的建模

agents/code-reviewer.md 定义了一个高级代码审查员角色，其能力包括：

• 对照计划和规范检查实现是否一致。
• 检查代码质量、模式使用、架构合理性。
• 按严重程度分类问题（严重 / 重要 / 建议），便于开发者逐步处理。

这个 Agent 的 YAML 前置数据中包含 model: inherit 字段，表示它不会强行指定模型，而是沿用父会话的选择。
这样做的优势是：在不同平台、不同模型组合下都能被技能安全复用。

---

7.2 子审查提示词：精细化到不同审查维度

在 subagent-driven-development 技能目录下，还内置了若干专用提示词，如 spec-reviewer-prompt.md、code-quality-reviewer-prompt.md。它们只在对应技能内部被引用，用于进一步区分“规范审查”和“质量审查”的语气与关注点。

从架构角度看：技能定义流程，Agent 定义角色，两者组合才形成完整的开发工作流。

---

八、第五层：测试基础设施——把“提示词工程”当代码来测

Superpowers 明确把技能当作“行为代码”，所以它也建立了一套较完备的测试体系。

8.1 按平台与场景划分的测试目录

测试目录大致长这样：

测试目录	主要验证内容
tests/claude-code/	技能文档审查系统、subagent 开发集成、Token 用量分析
tests/opencode/	插件加载、技能优先级、工具功能
tests/brainstorm-server/	可视化伴侣 WebSocket 协议、生命周期、Win 兼容性
tests/skill-triggering/	基于用户提示的自动技能激活
tests/explicit-skill-requests/	多轮对话、Haiku 模型兼容性
tests/subagent-driven-dev/	端到端 subagent 工作流（Go 分形、Svelte Todo）

这说明作者并不把“提示词工程”当作纯文案，而是运行在 CI 思维下的“软代码”。

---

8.2 写技能也要 TDD：writing-skills 元技能

更有意思的是，Superpowers 用 writing-skills 这个元技能，把“写技能本身”也纳入了 TDD 循环：

• 先写对抗性压力测试场景。
• 在没有技能的情况下跑一遍，看模型会怎样“乱来”。
• 写技能内容，重新跑测试，验证是否真正改变行为。
• 对引入的改动要求提供前后效果评估，否则难以通过合并审查。

在 CONTRIBUTING 文档中提到，该项目 PR 拒绝率达 94%，很大一部分原因是要防止经过仔细调优的技能被无意破坏。这个态度也从侧面凸显了：在 Superpowers 的世界里，提示词就是生产级代码。

---

九、设计原则与约束：支撑整个架构的“硬骨头”

Superpowers 在 CLAUDE.md 等文档中总结了一些重要的设计约束，它们贯穿在所有层级中。

9.1 零外部依赖：易安装、易审计

项目刻意避免依赖复杂的运行时组件：

• 核心逻辑全部落在 Markdown 文件和 Shell 脚本上。
• 唯一的 package.json 基本只用于 OpenCode 插件入口，而非提供完整 NPM 包。

这带来几个现实好处：

• 安装简单，适合在企业、受限环境中部署。
• 安全审计成本低，开发者可以直接逐行阅读行为定义。

---

9.2 指令层级：用户永远在最上层

系统明确确立了三层指令优先级：

1. 用户指令（含用户自己的 CLAUDE.md 或等价配置）
2. Superpowers 技能指令
3. 默认系统提示词

这意味着：如果你在自己的配置中定义了某些约束，它可以覆盖甚至部分禁用 Superpowers 的行为。最终控制权仍然在开发者手里，而不是在某套框架上。

---

9.3 抵抗“合理化”：不要指望模型自觉遵守

Superpowers 的很多细节都围绕一个前提：大模型会想方设法偷懒、跳步、给自己找借口。

因此才有：

• 危险信号表：提前写好“模型常用借口”及其反驳，例如“为了节省时间我直接实现了”，对应的反制是“违反了 TDD 的顺序要求”等。
• 硬性门控：不是“建议先做 A 再做 B”，而是明写“如果未完成 A 的清单，则拒绝执行 B”。

从工程角度看，这是一种非常务实的设计：与其幻想模型会“理解并自律”，不如把规矩写死在系统里，甚至专门为“不守规矩”设计对策。

---

十、版本管理：把多文件版本号当作系统配置来维护

Superpowers 用 .version-bump.json 管理版本号分布，声明哪些文件包含版本字段，比如 package.json、gemini-extension.json 等。
scripts/bump-version.sh 会根据这个配置做几件事：

• 检查已声明文件之间的版本是否一致。
• 扫描仓库中未声明的版本字符串，防止“漏改”。
• 一次性、原子性地更新所有版本号。

当前仓库版本为 5.0.7，并在多个文件中保持同步。
对于一个主要由文档和提示词构成的项目，这种版本管理方式显得有点“奢侈”，但也反映出作者把它当作正式工程系统在对待。

---

十一、对使用者的启发：如何在自己的项目里借鉴 Superpowers？

最后，用几个落地建议来总结 Superpowers 对我们设计 AI 开发工作流的启发价值。

11.1 如果你在做企业内 AI 工程平台

可以借鉴的点包括：

• 把“技能”抽象为可组合的工作流单元，并用结构化格式（YAML + Markdown）定义。
• 使用类似 SessionStart 的机制，在每次对话重建时注入统一的“工程守则”。
• 为关键流程（需求澄清、测试、审查）设计刚性技能，并通过硬性门控禁止跳步。

11.2 如果你只是个人开发者，日常用 Claude / Cursor 写代码

可以从轻量级方式开始：

• 参考 Superpowers 的 SKILL.md 结构，为自己常用的流程（例如“为接口设计写用例”、“为 PR 做审查”）写一份 mini 技能。
• 在自己的 CLAUDE.md 或等价配置中，加入类似“先头脑风暴、再写计划、最后才允许写代码”的提示。
• 尝试手动模拟 subagent 思路：把大任务拆分成任务列表，每个任务在单独对话中执行并审查，再整合回主仓库。

11.3 如果你在研究“结构化提示词系统”或 Agent 架构

Superpowers 提供了一套非常值得研究的公开样本：

• 如何用前置数据驱动技能发现与激活。
• 如何把“危险信号表”用于对抗模型的系统性偏差。
• 如何通过多层测试让提示词工程进入“可回归”的状态。

---

无论你是希望让日常 AI 编码更“守规矩”的个体开发者，还是在构建下一代 AI IDE / Agent 平台的架构师，Superpowers 都提供了一个值得仔细拆解与借鉴的范例：用纯指令层的设计，把“会写代码”的模型训练成“会做工程”的伙伴。