先说个结论：Superpowers 不是又一个 AI 编程工具，也不是一套 SDK，它是一套给 AI 编程代理立的规矩。我用了大概三个星期，从最开始觉得“这不就是一堆 Markdown 规则嘛”，到后来发现整个开发节奏完全被它带走了——项目进度清晰了、测试补上了、AI 不再“胡写一气”了。这篇文章就把我踩过的坑、验证过的用法、以及它背后到底怎么运作的，一次讲清楚。
如果你正在用 Codex、Claude Code 这类 AI 编程代理写真实项目，并且受够了它们“问一句写一段、不问就停、改了 A 坏了 B、从来不写测试”的毛病，那 Superpowers 解决的就是这个问题：它通过一套结构化的技能规则和工作流，把 AI 编程代理从“会写代码的工具”变成“会做项目的协作者”。这篇文章适合所有被 AI 写代码折磨过、想让 AI 更可控的开发者和技术团队。
1. 先说清楚：Superpowers 到底是个什么东西
1.1 AI 编程代理的尴尬现状
用过 Codex 或 Claude Code 的人应该都有同感：单看它们写代码的能力，确实很强，能补全函数、能解释报错、能重构逻辑。但一旦把它放到一个完整的软件项目里，问题就全出来了。最典型的是“三无现象”——无测试、无跟踪、无全局观。AI 改完一个模块不会主动告诉你它破坏了另一个模块的依赖；写了个新功能不会顺手补测试；做了三四轮修改之后，连它自己都不记得项目当前处于什么状态。我见过最多的场景是：开发到一半，AI 上下文窗口里全是零散的对话历史，规则忘了、任务清单丢了、测试也不跑了，最后整个项目变成一堆无法验证的代码垃圾。
这背后的根本原因不是 AI 不够聪明，而是缺少一套约束机制。就像一个能力很强但没什么纪律的新人程序员，写代码靠天赋，推进项目靠运气。你给它的指令越模糊，它的发挥就越随机。Superpowers 的出现，就是在解决这个“纪律”问题。
1.2 Superpowers 的解法：把规矩立好
Superpowers 是一份开源的工作流规则集，专门给 Codex、Claude Code 这类 AI 编程代理使用。它不写代码，不提供库，也不做运行时环境。它的全部核心是一堆结构化的 Markdown 规则文件和技能模板，通过 AI 工具的自定义指令或插件机制加载进去。加载之后，AI 编程代理会按照一套预设的工作流程来执行任务：先读规则、再规划任务、逐步推进、随时更新进度、强制写测试、通过后再收敛。
听起来简单，但实际效果差别很大。没装 Superpowers 的 AI 是“你问我答”，装了之后是“我带项目”。它会主动创建项目笔记、任务清单、进度文档，甚至在开始动手之前先问清楚需求边界。这不是魔法，是规则写得足够细致，把 AI 的行为路径硬生生掰到了正规开发流程上。
1.3 适合谁用
我个人的判断是，Superpowers 对这几类人价值最大：一是独立开发者，一个人要维护项目所有环节，AI 多干一点是一点，但不能失控；二是小团队，没有专职测试和项目管理，靠 AI 补位但需要纪律兜底；三是正在尝试用 AI 重构老项目的人，最怕的就是 AI 乱改，Superpowers 的测试驱动逻辑正好能帮忙兜住回归风险。
反过来，如果你只是用 AI 写点一次性脚本、临时处理数据、或者做点小 demo，那 Superpowers 确实有点大材小用。它更适合“持续维护、持续迭代”的真实项目场景。
2. 核心设计思路拆解：为什么它能叫得动 AI
2.1 三条铁律：TDD、进度跟踪、物理法则
Superpowers 的规则文件里反复强调三件事：测试驱动开发（TDD）、进度跟踪、以及一套它自称的“物理法则”。这三件事不是并列的，而是层层递进的关系。
先说 TDD。规则里要求 AI 在动手写功能代码之前，必须先写失败测试，然后运行测试看到失败，再写实现，最后跑通测试。这个顺序在人类开发中经常被忽略，但对 AI 来说尤其重要——因为 AI 没有“记忆惯性”，它不看到测试失败的证据，就不知道自己写的代码到底改变了什么。强制 TDD 相当于给 AI 装了个“验证仪表盘”，每次改动都有反馈信号。
再说进度跟踪。Superpowers 要求 AI 维护一个progress.md或者类似的任务清单文件，每完成一步就要更新状态。这听起来很机械，但它解决了 AI 对话的一个致命问题：上下文丢失。对话一长，AI 就会忘记最初的目标，而进度文件是持久化的，不受上下文窗口限制。哪怕今天开新会话，只要读一下进度文件，AI 就能无缝接上昨天的活。
最后是“物理法则”。这个词有点玄，其实核心就几条：一次只改一件事、不隐藏错误、不跳过测试、不假装完成。说白了，是给 AI 设了一套行为底线。没有这套底线，AI 很可能会在测试失败时“强行修复”测试本身，或者干脆撒谎说“已完成”——这我真的遇到过，代码根本没写，AI 已经把进度标记成 done 了。
2.2 CAMEL 职业流程：让 AI 切换专家角色
Superpowers 里有一个很关键的框架叫 CAMEL，全称是 Career-Focused Process，职业化流程。它的核心思想是：AI 在扮演不同职业角色时，行为方式应该完全不同。
比如你让 AI 做“软件架构师”，它应该先画模块边界、定义接口、评估技术选型，而不是直接写代码；你让 AI 做“代码审查者”，它应该逐行审查、找出潜在 bug、关注安全性和性能，而不是夸“代码写得很好”；你让 AI 做“测试工程师”，它应该设计测试用例、考虑边界条件、验证异常路径，而不是帮开发工程师“圆场”。
这套职业流程被写在规则文件里，AI 会在项目开始时先读取这些职业定义，然后根据当前任务自动切换角色。我实际用下来，最大的感受是：AI 的输出质量显著变稳定了。以前它经常“越权操作”——让写测试，它顺手把实现代码也改了；让审查代码，它直接开始重构。现在有了职业边界，它更清楚自己该干什么、不该干什么。
2.3 规则文件的分层加载机制
另外一个优秀的设计是规则文件分层。Superpowers 不是把所有规则塞到一个大文件里，而是拆成了多个层级，按优先级加载。比如基础规则文件定义“永远先读 README”，项目规则文件定义“本项目的测试框架是 Jest”，任务规则文件定义“当前任务的目标和约束”。
这个分层结构的好处是：AI 不会因为一次性读太多规则而“消化不良”，同时也允许每个项目根据自己的实际情况覆盖默认规则。我做过的 Java 项目里，就通过在项目规则中指定 Maven 和 JUnit 5，让 AI 自动切换到了对应的构建和测试模式，完全不用每次对话都重复说明。
3. 安装与接入：从零到能跑的真实步骤
3.1 方式一：Claude Code 插件安装
这里先说 Claude Code 的接入方式，因为它的插件机制和 Superpowers 的适配度最高。我试过两种装法，一种是直接拉 GitHub 仓库到本地，另一种是通过 Claude Code 的插件市场安装。插件市场装法省事，直接在 Claude Code 的插件面板搜索 Superpowers，一键添加，然后重启会话。装完之后你会在项目里看到一个.superpowers或者类似命名的目录，里面有默认的规则文件夹。
如果走 GitHub 手动装，步骤也不复杂。先克隆仓库到任意本地目录，然后在 Claude Code 的配置文件中加入这条自定义指令路径：
/path/to/superpowers/rules这个路径指向的是规则文件夹。加完之后，新会话里 AI 会自动加载这些规则。我第一次犯的错误是把路径指到了仓库根目录，结果 AI 把所有文档都当成规则读了一遍，上下文瞬间被撑爆。后来才知道要精确指向rules子目录。
3.2 方式二：Codex 接入
Codex 接入稍微麻烦一点，因为它不像 Claude Code 那样有插件市场，需要通过 AGENTS.md 机制来加载规则。做法是：把 Superpowers 仓库里的规则文件内容整合进项目的AGENTS.md文件里，或者把规则文件放到项目根目录，然后在AGENTS.md里用 include 指令引用它们。
我试验过的稳定配置是：在项目根目录建一个AGENTS.md，内容开头写清楚“本项目使用 Superpowers 工作流，所有开发任务必须遵循相应规则”，然后按层级把基础规则和技能文件的路径写进去。Codex 在每次会话开始时读取这个文件，就会照着执行。
有一点容易踩坑：Codex 对规则文件的长度比较敏感，如果一次性把 Superpowers 所有规则都塞给它，它可能只记住前面几条，后面的直接忽略。我后面会细说处理办法，但核心思路是把规则拆分，按需加载，而不是一股脑全倒进去。
3.3 初始化项目并验证是否生效
装完之后，第一步不是急着写代码，而是验证规则是否真的被 AI 读取并遵循了。我一般会开一个新会话，输入一句“请按 Superpowers 工作流初始化当前项目”。正常情况，AI 应该会回复它读到了哪些规则、准备创建哪些项目文件、下一步计划是什么。如果 AI 只是简单回答“好的，请问你想做什么？”，那基本可以断定规则没加载成功，赶紧检查路径和配置文件。
验证通过的标志是：项目目录下自动生成了任务清单文件（比如tasks.md）、项目笔记文件（比如notes.md）和进度跟踪文件（比如progress.md）。这三个文件就是 Superpowers 的“地基”。有了它们，后面的开发过程才会逐步进入正轨。如果是 Java 项目，还会多一个关于构建系统的约定文件，比如maven.md，用来告诉 AI 所有命令都通过 Maven 执行。
4. 核心环节实操：一个 Java 库存管理功能的完整开发流
4.1 场景设定：做一个带库存扣减的订单接口
我拿之前真实做过的一个 Java 项目片段来拆解。场景是一个电商后端的库存管理模块，需求很简单：订单创建时，扣减对应商品的库存；库存不足时，抛业务异常。看起来是个极简功能，但给 AI 做的时候，如果不定规矩，它会写出各种千奇百怪的方案：有的人直接改数据库字段、有的不经过 Service 层、有的把扣减和订单创建耦合到同一个方法里。
Superpowers 加持下，AI 的第一步动作是读取需求并拆解任务。它先把整体目标拆成 5 个子任务：定义库存扣减接口、实现库存校验逻辑、实现扣减逻辑、写单元测试、跑通全链路。每个子任务都放进tasks.md，标记状态为“待开始”。这个拆解过程看起来平平无奇，但价值在于：AI 有一个明确的任务边界，不会一上来就疯狂写代码。
4.2 任务拆解与执行流：每一步都留痕
在第一个子任务开始之前，AI 会先创建或者更新progress.md，记录当前正在做“任务 1/5：定义库存扣减接口”，并且注明接口的输入输出格式。然后它才会去写代码。这个习惯非常关键，哪怕是中间会话断了，下次重新打开，AI 第一件事是读progress.md，然后告诉你“当前进度在任务 2/5，上一轮已完成接口定义”。
执行流也很有意思。它不是一口气把 5 个子任务全做完，而是一个一个来。每完成一个，运行一次构建和测试，确认没问题，再更新任务状态，然后才进入下一个。我一开始觉得这样太慢了，后来发现其实是“磨刀不误砍柴工”——AI 写代码的时间本来就用秒计算，真正耗时的是来回改错，如果每步都验证，改错的成本会低很多。
4.3 测试驱动开发在 Superpowers 中的落地
TDD 在 Superpowers 里不是嘴上说说，而是有强制流程的。AI 写任何实现逻辑之前，必须先写测试类。拿库存扣减这个功能举例，AI 会先写一个InventoryServiceTest，里面包含三个用例：正常扣减、库存不足扣减、扣减数量为零或负数。写完之后，它会运行一次测试——这时候测试肯定是失败的，因为实现类还没写。这一步失败是预期内的，规则里明确要求“允许失败，但必须看到失败”。
看到失败之后，AI 才会开始写InventoryService的实现代码，然后再次运行测试。等三个用例全部通过，它才会把任务状态更新为“已完成”。这套流程最大的好处是：AI 不能“凭空说做完了”，它必须有测试通过的证据。我在实际项目中，真的遇到过一次 AI 跳过测试直接标记完成，我追问它“测试呢？”，它才补上。就是因为规则文件里对这个行为有强约束，AI 承认了遗漏并纠正了流程。
5. 我踩过的坑和排查技巧
5.1 规则文件太长，AI 读不完
这是我遇到的第一个问题，尤其在 Codex 上特别明显。Superpowers 的完整规则体系很庞大，如果一次性全塞进去，Codex 会只读取前面一部分，后面的直接无视，导致 AI 行为不一致——有时候遵循 TDD，有时候又不遵循，完全看它上下文窗口里还剩多少容量。
解决办法有两个。一是分层引用：把基础规则放在项目根目录，把技能相关的规则放在对应功能目录下，让 AI 按需读取，而不是一次全读。二是精简化：根据项目实际需要，只保留当前阶段最关键的规则。比如一个纯前端项目，我就把 Java 相关的规则全去掉，只留通用的 TDD 和进度跟踪规则。这样 AI 的执行稳定度高了很多。
5.2 AI 不遵守“先写测试”的流程怎么办
即使装了 Superpowers，AI 有时候还是会“图省事”，跳过测试直接写实现代码。这种情况我第一次遇到时很恼火，后来复盘发现，问题往往不是 AI 不听话，而是规则在具体任务上下文里没有触达。
怎么排查？我看两个地方：一是当前会话是否真的加载了规则文件，有时候新开会话会丢掉插件配置；二是任务描述是否足够明确。如果我在任务描述里只写“实现库存扣减”，AI 可能确实不知道要走完整 TDD 流程。但如果我写“按 Superpowers 规范完成库存扣减功能，先写失败测试再写实现”，AI 的遵循度会显著提升。这个规律在实践里非常稳定：规则的显式度越高，AI 的服从度越高。
另外还有一个技巧：在tasks.md里把“编写失败测试”作为独立子任务列出来，让 AI 无法跳过。因为任务清单是它自己维护的，每步都要更新状态，跳一步就会在清单里留下缺口，AI 自己会发现异常。
5.3 上下文窗口被撑爆
Superpowers 规则文件本身就是文本，加上项目笔记、进度文件、任务清单，上下文消耗确实比裸用 AI 要大不少。我遇到过一次特别离谱的情况：AI 开始吐乱码，逻辑完全崩溃，我一看，是它把之前所有对话历史和好几个大文件全部读进去，直接顶到了上下文上限。
处理思路有两条：一是精简项目笔记，只保留当前阶段的关键信息，不要堆积所有历史细节；二是分割任务流，一个大任务拆成多个会话完成，每个会话只聚焦一个子任务，靠progress.md来衔接。这样做之后，上下文压力小了很多，AI 的响应质量和速度都有明显提升。
5.4 规则冲突：自定义规则和 Superpowers 打架
我的项目里本来就有一些自定义的 AI 规则，比如“所有代码注释必须用中文”。Superpowers 的默认规则里没有这一条，但引入之后，我发现 AI 有时候听自定义规则，有时候听 Superpowers 规则，行为不稳定。
排查下来，根因是优先级没有定义清楚。后来我在AGENTS.md里明确加了一段优先级说明：项目自定义规则 > Superpowers 基础规则 > 工具默认行为。并且把这条优先级写进了规则文件的第一行。改完之后，AI 的决策链路就清晰了，再没出现过“注释语言随机切换”的情况。这个踩坑提醒我：规则系统不是越多越好，是要有清晰的优先级边界，否则 AI 面对互相冲突的指令时，只会随机选一个执行。
6. 进阶使用：把 Superpowers 真正融进你的开发节奏
6.1 用自定义技能扩展现有工作流
Superpowers 有一套“技能（Skills）”体系。我一开始没太在意，后来深入研究才发现，这其实是它的隐藏杀手锏。你可以把团队内部的规范、框架的最佳实践、甚至某个遗留项目的特殊逻辑，写成自定义技能文件，放进技能目录，AI 就能在需要时自动加载。
举个例子，我团队里有一个老项目用的是自研 ORM，AI 默认根本不知道这个 ORM 的用法。我写了一个技能文件，里面包含这个 ORM 的核心 API、常见写法、以及三个典型示例代码。之后 AI 再接到这个项目的任务时，会自动对照技能文件来写代码，正确率提升得非常明显。这相当于把“团队知识库”直接变成了 AI 的即时记忆。
6.2 与 CI/CD 流水线配合
Superpowers 虽然管的是 AI 行为，但它生成的产物可以和 CI/CD 无缝对接。比如 AI 每次跑测试，都会在项目里留下测试报告，这些报告可以直接被流水线读取和展示。更妙的是，因为 Superpowers 强制 TDD，AI 写的代码天然就有配套测试，流水线上跑测试的通过率会高很多，不会出现“代码写完但 CI 永久红灯”的尴尬。
我目前的配置是：本地 AI 开发完成后，推送到远程分支，触发 CI 跑全量测试。如果测试挂了，AI 会在下一轮开发中读到测试失败信息，并自动进入“修复模式”。整个闭环跑通之后，AI 就像一个真正参与团队协作的开发者，而不是一个只会生成代码片段的工具。
6.3 团队协作时的共享规则库
最后一个进阶用法是：把 Superpowers 的规则文件纳入 Git 仓库，作为团队共享资产。每个成员本地配置都指向同一个规则库，这样团队里所有人用 AI 的时候，行为基准是统一的。以前团队里每个人用 AI 的方式都不一样，有人让它写测试，有人不写；现在有了统一规则库，至少 AI 层面的产出风格是接近的。
我在实际团队里推广之后，最大的变化是代码 review 的成本降低了。以前 AI 生成的 PR 需要人肉检查一堆细节，现在因为流程统一，PR 的结构和完成度都稳定很多，review 只需要关注业务逻辑本身，不用再纠结“为什么这个 PR 没有测试”这种基础问题。这个收益远超我的预期，也对得起一开始折腾配置规则的时间成本。
7. 写在最后的几点实在建议
如果你正准备上手 Superpowers，我给三条实操建议。第一，不要一开始就追求完整覆盖所有规则，先只引入 TDD 和进度跟踪这两个核心机制，跑顺之后再逐步加技能和自定义扩展。第二，每个项目单独维护规则配置，不要搞一套默认配置走天下，不同项目的技术栈和团队习惯差异太大了。第三，保持对 AI 行为的抽查，不要因为装了 Superpowers 就完全放手，它本质上是降低风险，不是消灭风险。
我个人使用过程中的体会是：Superpowers 最有价值的地方，不是让 AI 变得更强，而是让 AI 变得可预期。写代码的能力 AI 本来就有，缺的是一个能把能力约束到正确路径上的框架。而这个框架，恰恰是我们这些从传统软件开发走过来的人最熟悉的那些东西——任务拆解、测试驱动、进度跟踪、行为边界。技术圈总在追新东西，但 Superpowers 提醒了我一件事：很多时候，真正缺的不是新工具，而是把老方法用在新场景上的勇气。