Superpowers：如何约束 Coding Agent
一、Superpowers 是什么？
Superpowers 是一套给 Coding Agent 使用的开发方法论。
它不是简单的 prompt 集合，也不是几个零散的 Markdown 文件，而是一套围绕 Agent 行为约束设计出来的工作流系统。
它的核心思路是：
- 基于一组可组合的 skills；
- 通过初始指令和插件入口，让 Agent 在合适的场景自动使用这些 skills；
- 把 Agent 从“直接写代码”，约束成“先设计、再计划、再实现、最后验证”的开发流程。
换句话说，Superpowers 给 Coding Agent 加了一套工程纪律。
普通 Agent 很容易在拿到需求之后直接开始写代码。它可能看起来很快，但这也意味着它经常会跳过真实软件开发里最关键的几个环节：设计、计划、测试和审查。
Superpowers 解决的正是这个问题。
二、Superpowers 解决了什么问题？
Coding Agent 最大的问题不是不会写代码，而是太容易“直接写代码”。
普通 Agent 在开发过程中，常见的问题包括：
第一，跳过设计。
用户给出一个模糊想法后，Agent 往往会立刻开始实现。但这时需求可能还没被真正理解，边界还没被澄清，方案也没有经过比较。结果就是代码写出来了，但方向可能已经偏了。
第二，跳过测试。
很多 Agent 会先写实现，再补测试。这样的问题是，测试很容易变成“验证当前实现没报错”，而不是验证需求是否真的被满足。真正的 TDD 应该是先写一个按预期失败的测试，再写最小实现让测试通过。
第三，跳过审查。
Agent 完成任务后，经常会直接宣布完成。但它可能没有完整跑测试，没有对照需求检查，也没有做代码审查。这样很容易出现“看起来完成了，但其实漏了边界情况”的问题。
Superpowers 的作用，就是不让 Agent 凭感觉写代码。
它要求 Agent 必须走一套完整流程：
先设计
↓
再计划
↓
再实现
↓
最后验证
这套流程本质上是在把成熟软件工程中的纪律，迁移到 Coding Agent 的工作方式里。
三、Superpowers 的整体架构
从项目结构上看，Superpowers 大致可以分成几部分：
.claude-plugin Claude Code 的插件元信息
.codex-plugin Codex 的插件元信息
.cursor-plugin Cursor 的插件元信息
hooks 启动入口，主要服务于 Claude Code 和 Cursor
scripts 本地辅助工具
skills 核心，定义各种 skill 工作流
tests 测试验证
docs 文档说明
所以它不是只服务某一个 Agent，而是一个多 Agent 适配系统。它可以通过不同插件入口，接入 Claude Code、Codex、Cursor 等工具。
其中最核心的目录是 skills。
skills 不是一堆普通 Markdown，而是一组 skill package。每个 skill package 都描述了一种开发场景下 Agent 应该如何行动。
一个最基础的 skill package 至少包含：
SKILL.md
SKILL.md 是入口文件，里面会写清楚这个 skill 的名称、触发条件、使用场景和执行流程。
复杂一点的 skill package，还可能包含：
references 长参考资料
prompts 子代理模板
scripts 本地辅助工具
html/js 可视化或交互资源
比如 brainstorming 这个 skill 的结构可能是这样的：
skills/
brainstorming/
SKILL.md
visual-companion.md
scripts/
start-server.sh
server.cjs
frame-template.html
helper.js
stop-server.sh
其中：
SKILL.md是入口文件，定义什么时候触发 brainstorming，以及它要求 Agent 怎么做；visual-companion.md用来说明什么时候需要浏览器可视化辅助；scripts里是这个 skill 用到的本地工具，比如启动服务、展示 HTML 页面、记录用户点击结果等。
其他 skill 也遵循类似模式：
skills/
test-driven-development/
SKILL.md
using-superpowers/
SKILL.md
verification-before-completion/
SKILL.md
这说明 Superpowers 的核心不是“提示词”，而是把开发流程拆成一个个可识别、可触发、可执行、可验证的 skill。
四、Codex 中的入口与 using-superpowers
以 Codex 为例，Superpowers 的入口大致是这样的：
也就是说，.codex-plugin/plugin.json 会告诉 Codex：
skills 目录在 ./skills/
然后 Codex 会扫描这个目录下的各个 skill package，读取每个 SKILL.md 的 frontmatter。
其中最关键的是 using-superpowers。
它相当于 Superpowers 的总入口。它告诉 Agent：你不能只凭自己的习惯行动，而是每次收到用户消息后，都要先判断有没有适用的 skill。
它对 Agent 的约束大致是：
收到用户消息
↓
判断有没有任何 skill 可能适用
↓
如果有，哪怕只有 1% 可能，也要调用 Skill tool
↓
告诉用户：我正在用哪个 skill 做什么
↓
看这个 skill 有没有 checklist
↓
如果有，把 checklist 变成 todo
↓
严格按照 skill 执行
↓
最后才回复用户
这一步非常重要。
因为它不是让 Agent “想起来的时候用一下 skill”，而是从入口层面规定：Agent 必须主动检查 skill 是否适用。
比如准备写实现计划时，Agent 不能直接进入计划阶段，而是要先判断有没有做过 brainstorming：
准备写计划
↓
判断有没有做过 brainstorming
↓
如果没有，先调用 brainstorming skill
↓
然后再判断有没有其他 skill 适用
↓
继续执行后续 skill 流程
这就把 Agent 的行为从“自由发挥”，变成了“受流程约束的工程行为”。
五、brainstorming：阻止 Agent 直接开写
brainstorming 是 Superpowers 里非常关键的一个 skill。
它解决的问题是：当用户提出一个模糊想法时，Agent 不应该直接实现，而应该先把想法变成经过确认的设计。
它的触发时机是：
在任何创造性工作之前触发
比如：
- 创建一个新功能；
- 修改一个已有功能；
- 设计一个组件；
- 改变系统行为；
- 做一个需要权衡方案的开发任务。
brainstorming 的核心作用，就是把“模糊想法”推进成“清晰设计”。
它第一步不是写代码，而是理解上下文。
它禁止 Agent 因为任务看起来简单，就跳过设计环节。
最终，它要求产出一份经过用户确认的 spec 文档。
在 brainstorming 里，有三个容易混淆的概念：
Checklist
Process Flow
The Process
它们的关系可以这样理解：
Checklist = 做什么
Process Flow = 按什么顺序做，遇到 yes/no 怎么分支
The Process = 每一步具体怎么做
Checklist 是强制任务清单，要求 Agent 为每一步创建 todo，并按顺序完成。
Process Flow 是流程图版本，展示整个 brainstorming 的路径，包括用户批准、修改、继续等分支。
The Process 则是详细执行说明，比如如何判断范围、如何提出澄清问题、如何给出方案、如何写 spec。
它的流程大致是：
探索项目上下文
↓
判断是否需要视觉辅助
↓
如果需要，单独询问是否启用 visual companion
↓
询问澄清问题
↓
提出 2-3 个方案
↓
展示设计
↓
用户是否批准？
├─ 不批准：继续修改设计
└─ 批准：写设计文档
↓
自检 spec
↓
用户审查 spec
├─ 要修改：回去改文档
└─ 批准：调用 writing-plans
所以，brainstorming 并不是单纯“帮用户想想方案”。
它本质上是一个硬门禁。
它强制 Agent 在写代码之前，先把需求变成明确的设计，并让用户确认。
六、从设计到开发：plan、TDD、review、finish
设计确认以后，Superpowers 并不会让 Agent 直接进入自由编码状态。
它还会继续用后续 skills 约束完整开发过程。
README 里的基本工作流大致是：
design approved
↓
using-git-worktrees
↓
writing-plans
↓
executing-plans / subagent-driven-development
↓
test-driven-development
↓
requesting-code-review
↓
finishing-a-development-branch
不过，这些 skill 文件之间不一定是严格链式调用。
比如：
brainstorming在设计确认后，会 handoff 到writing-plans；using-git-worktrees更像是在进入实现前，根据场景触发的隔离工作区机制；test-driven-development会在真正需要写代码时触发；requesting-code-review会在任务完成、主要功能实现后或合并前触发；finishing-a-development-branch则负责最后的 Git 收尾。
可以把它们理解成一组工程护栏。
| 阶段 | Skill | 作用 |
|---|---|---|
| 设计确认后 | using-git-worktrees | 不在原工作区直接乱改，先创建隔离分支或 worktree，并验证初始测试状态 |
| 写计划 | writing-plans | 不允许直接实现，必须拆成小任务，每个任务包含文件路径、代码说明和验证步骤 |
| 执行计划 | executing-plans / subagent-driven-development | 不允许一次性大改，必须按任务或批次推进，并在关键节点检查 |
| 写代码 | test-driven-development | 不允许先写实现，必须遵循 RED → GREEN → REFACTOR |
| 任务完成后 | requesting-code-review | 不允许只靠自我声明完成，必须对照 plan 和需求审查问题 |
| 收尾 | finishing-a-development-branch | 不允许“看起来好了”就结束，必须跑测试、决定 merge / PR / 保留 / 丢弃，并清理 worktree |
每个 skill 都可以从四个问题理解：
1. 什么时候触发？
2. 它禁止 Agent 做什么？
3. 它强制 Agent 做什么？
4. 它的产出物或检查点是什么？
下面分别看几个关键 skill。
七、writing-plans：把设计拆成可执行计划
writing-plans 的触发时机是：
已经有 spec / requirements，并且任务是多步骤开发任务，在真正改代码之前触发。
它禁止 Agent 直接写代码，也禁止写模糊计划。
比如下面这种计划是不合格的：
1. 添加测试
2. 实现功能
3. 处理边界情况
4. 跑测试
因为它太空了，没有文件路径，没有具体改动，没有测试命令，也没有预期结果。
writing-plans 强制 Agent 写一份详细的 implementation plan。
这个计划要把任务拆成 2-5 分钟可以完成的小步骤。每一步都应该包含：
- 精确文件路径；
- 具体代码说明；
- 测试命令；
- 预期结果。
它还强调：
- TDD；
- DRY；
- YAGNI；
- 频繁提交；
- 自检 spec 覆盖；
- 检查占位符；
- 检查类型一致性。
它最终产出的是类似这样的计划文档：
docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
写完计划后，Agent 不能直接继续开发，而是要让用户选择执行方式：
subagent-driven-development
或
executing-plans
这一步的关键是：计划必须足够具体，具体到另一个 Agent 也可以照着执行。
八、test-driven-development：强制红绿重构
test-driven-development 的触发时机是：
实现功能、修 bug、重构、修改行为，需要写代码之前。
它禁止 Agent 先写实现再补测试。
它也禁止写一个一开始就成功的测试。因为如果测试一写出来就通过，就无法证明这个测试真的覆盖了新需求。
它强制 Agent 遵循 TDD 的经典流程：
RED
↓
GREEN
↓
REFACTOR
也就是：
- 先写一个失败的测试；
- 确认测试是因为预期原因失败；
- 写最小实现让测试通过；
- 在测试保护下重构代码。
它的产出物不是单纯的测试文件，而是一个更强的检查点：
每个功能都有测试代码，并且测试是按预期原因先失败，再被实现代码修复。
这能有效防止 Agent 写出“看起来有测试，其实没验证需求”的代码。
九、requesting-code-review：不能只靠自己宣布完成
requesting-code-review 的触发时机是：
完成任务、实现主要功能，或者合并代码之前。
它禁止 Agent 因为任务简单就跳过审查。
它也禁止 Agent 忽略严重问题，或者在没有修复审查问题的情况下继续执行。
这个 skill 会强制 Agent 派出 code reviewer subagent，并给 reviewer 明确上下文：
改了什么
需求是什么
BASE_SHA 是什么
HEAD_SHA 是什么
审查反馈会按严重程度处理：
- Critical：立即修；
- Important：继续前必须修；
- Minor：可以记录；
- 如果 reviewer 错了，必须用技术理由反驳，而不是情绪化争辩。
它的产出物是每一次代码审查结果，以及针对审查结果的处理记录。
这一步的意义在于：Agent 不能只靠自我声明“我完成了”，而是必须引入独立审查。
十、executing-plans：按计划执行，而不是边写边猜
executing-plans 的触发时机是：
已经有一个计划，并且要在一个连续会话中带有断点审查地执行这个计划。
它禁止几件事：
- 禁止没审查计划就执行；
- 禁止不按照 plan 进行；
- 禁止跳过验证；
- 禁止猜测；
- 禁止遇到阻碍直接绕过去；
- 禁止没有同意就在 master / main 上开发。
它强制 Agent 先审查计划，有疑问就不执行。
然后把 plan 转换成 todo list，按每一步推进。每完成一批任务，都要检查结果。
执行完成后，还要进入 finishing-a-development-branch。
所以 executing-plans 的产出不是一段代码，而是：
按照 plan 创建任务表；
逐步执行每个任务；
每一步都有验证；
最终进入开发分支收尾流程。
它解决的是 Agent 常见的另一个问题：计划写得很好，但真正执行时又开始自由发挥。
十一、finishing-a-development-branch：安全收尾
finishing-a-development-branch 的触发时机是：
开发完成，并且测试通过以后，需要决定如何在 Git 上收尾。
它禁止没有测试通过就进行 Git 操作。
它也禁止不安全操作，比如：
- 没有明确确认就删除分支；
- 没有明确选项就自动合并；
- 在环境不清楚时贸然清理 worktree；
- 用含糊方式处理开发分支。
它强制 Agent 走一个安全收尾流程：
验证所有测试通过
↓
识别当前环境
↓
展示可选方案
↓
根据用户选择执行
↓
必要时清理 worktree 和分支
它的产出是把当前开发成果安全地合并、保留、提交 PR，或者按用户选择丢弃。
这一步的价值在于：开发完成不等于工作完成。真正的结束，还包括测试、集成、合并策略和工作区清理。
十二、如何验证 skill 真的生效？
Superpowers 还有一个很重要的特点：它不只定义规则，还测试规则是否真的生效。
相关测试包括：
tests/skill-triggering/run-test.sh
tests/explicit-skill-requests/run-test.sh
docs/testing.md
CLAUDE.md
这里的测试不是简单 mock。
它会启动真实的 Agent 会话，然后检查 transcript 或 stream-json，确认 Agent 是否真的调用了对应 Skill。
也就是说，它不是只检查代码有没有跑通，而是在检查 Agent 的行为是否符合预期。
这也是 Superpowers 很值得学习的地方。
它把“Agent 是否遵守流程”这件事，也变成了可以验证的测试对象。
十三、Superpowers 给我的启发
Superpowers 最有价值的地方，不是某一个具体 skill，而是它背后的设计思想。
它把 Coding Agent 从一个“会写代码的聊天助手”，变成了一个“受工程流程约束的开发执行者”。
它的核心启发可以总结成三点。
第一，Agent 需要入口规则。
如果只靠用户每次提醒，Agent 很容易忘记流程。所以 Superpowers 通过插件入口和 using-superpowers，在会话开始时就把规则注入进去，让 Agent 每次行动前都先判断是否需要使用 skill。
第二，Agent 需要流程约束。
开发不是只有写代码。真实开发包括需求澄清、设计确认、计划拆解、测试驱动、代码审查和分支收尾。Superpowers 用不同 skill 把这些环节拆开，并为每个环节建立清晰规则。
第三，Agent 行为也需要测试。
如果一个流程只是写在文档里，但不能验证它是否真的被 Agent 执行，那它就很容易失效。Superpowers 通过真实 Agent 会话测试，去验证 skill 是否真的触发，这让“Agent 遵守流程”变成了可测试的工程问题。
所以，我对 Superpowers 的理解是：
Superpowers 不是 prompt 集合，
而是一套 Agent 行为约束系统。
它通过入口注入规则，
通过 skills 约束流程，
通过 tests 验证行为。
这也是它和普通提示词最大的区别。
普通提示词更多是在告诉 Agent：“你应该怎么做。”
而 Superpowers 更进一步，它在告诉 Agent：
什么时候必须停下来；
什么时候必须设计；
什么时候必须写计划；
什么时候必须测试；
什么时候必须审查；
什么时候才算真正完成。
这套思路对我最大的启发是：以后设计 Coding Agent 工作流时，不能只想着“怎么让它更聪明”，还要想着“怎么让它更守纪律”。
因为在真实开发里，可靠性往往不是来自一次很聪明的发挥，而是来自一套稳定、可重复、可验证的流程。
浙公网安备 33010602011771号