Superpowers实战：给AI编程助手补上开发流程纪律（TDD/计划/重构）
先交代一句：如果你是被“superpowers”这个名字吸引进来的，我劝你先把期望值放对。它不是那种装上就能让AI助手原地封神的魔法插件，更不是一键生成全栈项目的银弹。我个人的定义是，它是给 Claude Code、Codex CLI 这类 AI 编程助手补上一套“开发流程自觉”——让模型不再像个记忆力只有 4K 的天才实习生，而是能老老实实按 TDD、先计划后动手、小步重构这些人类工程师早已验证过的套路干活。过去半年我把它跑在几个真实项目上，效果不是“变强了”，而是“从不可用变成可用了”。这篇文章把我的实操过程、踩过的坑、扒出来的内部机制全写下来，给正在纠结要不要装它的同学做个参考。
1. Superpowers 是什么：它不是插件，是一套“开发方法论”
1.1 它到底解决了什么问题
先说个很普遍的现象。用 AI 编程助手写代码，第一版通常都像样，可一旦让它改需求、加功能、修 Bug，事情就开始失控。你让它改 A 方法，它顺手把 B 模块的变量名也改了；你让它写单元测试，它写出来的测试和实现互相“作弊”；你让它提交代码，commit message 永远是fix或者update。这些问题的根源不是模型笨，而是它没有“过程记忆”——每次对话都是一张白纸，它不知道人类开发者在大厂里是怎么一步步把代码落地的。
Superpowers 的核心思路就这么朴素：把人类开发者的成熟工作流固化成一堆 Markdown 技能文件，AI 在开始干活之前先“查阅”对应流程，然后照着走。它给 AI 补的不是智力，是流程纪律。
1.2 项目背景与生态
这个项目是 Jesse Vincent（Perl 社区的老熟人，ID 是 obra）发起的，选择在 GitHub 上开源，主仓库叫obra/superpowers。它的定位很有意思，不是一个独立的 IDE 插件，也不是一个编译器扩展，而是一个“技能包集合”，同时支持两款主流的终端型 AI 编程助手：Claude Code 和 OpenAI 的 Codex CLI。
安装方式也是围绕这两款助手展开的。Claude Code 走的是插件市场协议，Codex CLI 走的是它的 plugin 命令。也就是说，Superpowers 像一个中间层，把抽象的“开发方法论”翻译成不同助手能识别的技能目录。这个设计让它的可迁移性很好，同一套技能，换个底层模型也能用。
1.3 适用人群，先对号入座
我用了小半年之后，觉得它最值得推荐给下面三类人：
- 正在用 Claude Code 或 Codex CLI 做真实业务开发，但对 AI 产出的代码质量不满意，尤其是测试缺失、逻辑跳步、乱改无关代码这些毛病。
- 团队里已经有一套代码规范（TDD 流程、commit 规范、Code Review 清单），想让 AI 也遵守团队的规矩，而不是每次都得在 prompt 里反复强调。
- 想研究“如何给 AI 编程助手设计技能”的开发者，Superpowers 提供了一个非常干净的参考实现。
反过来，如果你只是想让 AI 帮你写个一次性脚本，或者只是问几个语法问题，那 Superpowers 对你来说确实有点杀鸡用牛刀，它更适合持续的、多文件的、需要维护质量的开发任务。
2. 技能机制的底层设计，我一层一层扒给你看
2.1 一个技能就是一个 Markdown 文件
很多人第一次看到 Superpowers 的项目结构会愣一下，因为它实在太“简陋”了。整个技能库就是一堆.md文件，放在skills目录下。每个技能文件包含两部分：一段 YAML 格式的 frontmatter，和一段正文。
frontmatter 里最关键的两个字段是name和description。name是技能的唯一标识，比如test-driven-development；description是给模型看的“技能使用说明”，里面写清楚“这个技能什么时候该被调用、解决了什么问题”。正文部分则是一步步的操作指引，告诉模型具体该怎么执行。
我拿一个简化版的技能文件给你看：
--- name: test-driven-development description: 在实现任何新功能前，先编写失败的测试用例，然后运行测试确认失败，再编写满足测试的最小实现代码。适合需要新增业务逻辑、修复 Bug 或重构代码的场景。 --- # TDD 工作流 1. 梳理需求，圈定要变更的行为边界。 2. 编写一个或多个失败测试，描述期望结果。 3. 运行测试，确认它们是红的（fail）。 4. 编写恰好能让测试通过的最简实现，不做多余设计。 5. 运行全部测试，确认是绿的（pass）。 6. 在测试保护下重构，消除重复代码，改善命名。这个设计有两个深层原因。第一是 Markdown 本身对模型非常友好，不需要解析器，模型可以直接读取和理解。第二是文件即技能，意味着任何人都能自己写技能，无需编译、无需打包，丢进目录就能生效。
2.2 模型怎么知道该调用哪个技能
这是整套机制里最巧妙的部分。Superpowers 在系统提示词（system prompt）里注入了一段“技能选择指令”，大致逻辑是：当用户提出一个开发任务时，先浏览技能目录，根据任务的语义匹配description，选出相关技能，然后读取正文按步骤执行。
举个例子，你告诉 AI“帮我重构一下这个模块”，模型看到refactoring技能的描述是“在保持外部行为不变的前提下，改善代码结构。适用于代码中存在重复、长函数、命名混乱等坏味道”，它就会主动去读这个文件，然后按里面的步骤走。
如果任务复杂，它会同时选中多个技能。比如“给用户模块增加邮箱校验功能”，它会同时触发test-driven-development（先写测试）和writing-plans（先写计划）。
2.3 为什么非要用“按需加载”，而不是一股脑全塞进去
这也回答了一个我很长时间没想明白的问题：为什么不把全部技能直接写进系统提示词里，让模型随时调用？
如果你用过 API 就知道，系统提示词越长，模型对后面内容的注意力就越容易被稀释，而且每次请求都会消耗大量 token。Superpowers 的技能库目前有十几个核心技能，每个技能正文动辄几百行，全塞进去既不经济，也会干扰模型对当前任务的理解。
按需加载的核心收益是：上下文干净，每步只加载当前需要的技能，token 消耗可控，技能之间不会互相打架。再加上，当技能以文件形式存在时，用户可以随时删改，模型在执行时看到的是最新版本。
2.4 核心哲学：让 AI 像人一样工作
我认真读了 Superpowers 的技能列表，发现它其实是在向 AI 灌输一套“精英开发者行为准则”。这套准则拆开来无非是：先想清楚再做、先写测试再写实现、改动保持最小、提交说明要解释动机、Code Review 要从维护者视角看问题。
听起来都是常识，但如果你用了 AI 写代码，就会知道这些“常识”恰恰是模型最缺的。模型天生倾向于“直接给答案”，而人类工程师的经验是“先建立安全网再动手”。Superpowers 就是在两者之间加了一个流程翻译器。
3. 安装与初始配置，跟着走一遍就行
3.1 安装前的环境准备
Superpowers 本身没有编译过程，对环境要求只有三层：
- 一个能跑的 Claude Code 或 Codex CLI，版本不要太老，建议保持最新版。
- 能正常访问 GitHub，因为安装插件是从 GitHub 拉取的。
- Node.js 环境（Claude Code 和 Codex CLI 都基于 Node，系统里顺手装一个没坏处）。
如果你还没装 Codex CLI，可以用下面的命令装，装完确认版本：
npm install -g @openai/codex codex --version如果你用的是 Claude Code，直接在终端里执行claude进入交互界面即可。注意，这两款助手都需要你提前完成登录认证，否则后面无法读取模型。
3.2 在 Claude Code 里安装 Superpowers
Claude Code 的插件系统走的是“市场（marketplace）”模式。第一步，把 Superpowers 的市场地址加进去。在 Claude Code 会话里输入：
/plugin marketplace add obra/superpowers看到类似Added marketplace: superpowers-marketplace的提示就说明市场添加成功。第二步，从市场安装插件本身：
/plugin install superpowers装完之后，你可以用下面的斜杠命令检查当前已安装的插件，确认列表里有superpowers：
/plugin status3.3 在 Codex CLI 里安装 Superpowers
Codex CLI 的安装方式更直接，用的是plugin子命令。我实测的流程是：
codex plugin install obra/superpowers这条命令会把插件安装到 Codex 的配置目录。安装完成后，建议重启 Codex CLI，让插件配置加载生效。启动后可以用下面命令确认：
codex plugin status不同版本的 Codex CLI 对插件协议的支持略有差异，如果你用的版本比较老，可能没有plugin命令。这种情况我建议先升级：
npm install -g @openai/codex@latest3.4 安装后立刻做这两件事
插件装完不代表万事大吉。我第一次装的时候就是直接开始让它写代码，结果它表现得跟没装一样。后来才发现少了两步。
第一件事，启动一个全新的会话，让模型“重新加载”技能索引。如果你是在旧会话里装的插件，技能信息不会自动注入。
第二件事，跑一个初始化技能。在会话里直接输入：
请初始化 superpowers 技能，并告诉我当前项目的技术栈、测试框架和构建命令。这一步会让模型去读取技能配置，并尝试生成一份项目档案。它会把项目的关键信息（比如 Maven 项目、JUnit 5、mvn test）写到一个项目级配置里，之后所有 TDD、重构技能都能直接用这些信息执行测试命令。
4. 核心技能包逐个拆解
4.1 brainstorming：动手之前，先把想法聊清楚
brainstorming技能专治“AI 一听需求就直接开写”的毛病。它的工作方式很有意思，模型不会直接产出代码，而是先向你提出一系列澄清问题，比如“这个功能的核心用户是谁”“如果校验失败应该返回什么错误结构”“是否需要考虑并发场景”。
为什么这个设计有效？因为绝大多数翻车现场，都是需求和实现之间缺了一场对话。你脑子里想的“校验邮箱格式”，和 AI 理解的“校验邮箱格式”，可能差着十万八千里。它先帮你把边界划清楚，后面写出来的代码才是在正确的轨道上。
4.2 writing-plans：把大任务拆成可执行的小步
writing-plans是我个人最常用的技能之一，尤其适合“跨多个文件的新功能”。它会引导模型产出一份 Markdown 格式的实施计划，包含阶段划分、每个阶段要改哪些文件、涉及哪些函数、风险点在哪、如何验证。
它的价值在于：第一，计划一旦写出来，人和 AI 之间就有了一个“共识文档”，你可以直接审计划，而不是审代码；第二，后续实现时 AI 会反复对照计划，不会越改越偏。我的习惯是让它输出计划之后，花两分钟读一遍，有偏差当场纠正，这比等代码写出来再纠正省事太多。
4.3 test-driven-development：给 AI 装上“先写测试”的肌肉记忆
这个技能是整个 Superpowers 的招牌。它的执行路径我已经在上文展示过：红、绿、重构。真正让它和其他“让 AI 写测试”的做法拉开差距的地方，是它强制模型“先运行测试确认失败”。
很多 AI 写测试的情况是：模型编一个测试，再编一个实现，两个一起“恰好”通过，但实际上测试根本没验证任何东西。Superpowers 的流程要求模型在写实现之前先运行测试——测试应该失败，因为功能还不存在。这一步看起来多此一举，却能把测试的有效性直接拉满。
我碰到过几次模型偷懒的情况：它写完测试直接说“假定测试通过”，然后开始写实现。这时候我会打断它，明确说“请先运行测试，把失败结果贴出来再继续”。你不需要为此感到愧疚，因为严格遵循流程，本身就是这个工具的核心价值。
4.4 refactoring：在不改变行为的前提下优化结构
refactoring技能的引入时机很讲究。它专门用于处理“功能能跑，但代码很烂”的情况，而且它要求模型在整个过程中保持测试全绿。这个约束比“优化代码”四个字精确得多，它把重构的安全边界划得清清楚楚。
技能内部还会教模型一些重构技法：提取函数、引入解释变量、替换条件逻辑为空态、合并重复分支等等。它不追求一步到位，而是鼓励小步提交。我自己的体会是，AI 在小步重构时的表现远好于“一次性大改”——后者常常把逻辑改崩，前者则每一步都可验证。
4.5 debugging：先形成假设，再动手验证
debugging技能解决的是 AI 修 Bug 时的“瞎试”问题。默认情况下，AI 看到一个报错，第一反应往往是直接给一段“可能修复”的代码。而 Superpowers 会强制它按一套科学方法论走：先复现问题，再根据现象列出多个假设，然后逐一验证，定位根因，最后才动手修复。
这个流程最妙的地方在于，它要求模型明确区分“根因”和“表象”。比如一个“接口返回 500”的 Bug，表象是异常处理不够健壮，根因却是底层缓存没清空。按照旧习惯，AI 大概率会在接口层加个 try-catch 草草收场；按照 debugging 流程，它会顺着调用链往下查，直到看到真正的火山口。
4.6 writing-commits：让每次提交都像一封短说明信
这个技能初看很“轻”，但实际使用体验提升巨大。它生成的 commit message 遵循一个原则：说明“为什么”，而不是“做了什么”。比如：
fix(auth): 修复 token 过期后仍能访问受保护接口的问题 用户在登录态失效后，前端会拿到一个 401 响应，但由于拦截器 只处理了网络错误，导致页面出现空白。现在在响应拦截器中统一 捕获 401 并跳转到登录页。对比一下 AI 默认生成的“update auth interceptor”，这差别一眼就能看出来。这个技能对我最大的帮助是：一周后翻 git log，我能瞬间找到关键词，而不是对着“update”发愣。
4.7 reviewing-work：让 AI 自己当一回 Code Reviewer
reviewing-work技能一般放在功能实现之后。它会拉出当前分支的改动，然后站在一个严格的 Reviewer 角度审查：有没有潜在 Bug、测试有没有覆盖边界、有没有破坏既有行为、命名和结构是否合理、有没有安全隐患。
好的一面是，它能把很多问题拦在提交之前。坏的一面是，它会有点话痨，有时会给出一些“在团队里根本不成立”的意见。我的处理方式是把它当成一个低成本的同行评审，意见听一半，结合自己的判断过滤。
5. 实战复盘：用 Superpowers 给 Java 项目加一个用户注册接口
5.1 场景设定
这个案例来自我一个 Spring Boot 项目，需求是给现有的用户模块加一个“邮箱注册”接口，要求：邮箱格式必须合法、密码强度必须达标、注册成功后返回用户基本信息。这个需求看起来简单，但涉及 Controller、Service、Repository、异常处理等多个层次，而且要求有单测覆盖。
5.2 第一阶段：计划和澄清
我打开 Codex CLI，输入：
使用 superpowers 流程，帮我实现邮箱注册接口。项目用 Spring Boot 3 + Maven + JUnit 5。模型随即触发了brainstorming和writing-plans。它先向我确认了几个细节：密码强度规则、邮箱是否唯一、注册失败是否返回统一错误码、密码是否加密存储。确认完后，它输出了一份实施计划，大致改变了新文件、修改文件、关键步骤。
我没有直接说“开始”，而是让它把计划里“密码加密方案”这一条改明确，指定用 BCrypt。它立刻更新了计划。这一步只花了三分钟，却避免了后续返工。
5.3 第二阶段：先写测试，再跑 Red
计划确认后，模型开始进入 TDD 节奏。它在src/test/java下新建了一个测试类，覆盖了邮箱格式非法、密码强度不足、注册成功三个场景。然后它运行了测试：
mvn test -Dtest=RegistrationServiceTest当然，测试是失败的，因为RegistrationService这个类还不存在。失败结果被它贴了出来，并注释了一句“符合预期，当前是 red 状态”。这个流程完整走下来，我心里其实已经很踏实了，因为测试不是马后炮，而是先行的。
5.4 第三阶段：实现、重构、提交
测试红完之后，模型开始编写最简实现。它创建了RegistrationService、RegistrationController，补上了UserRepository的接口方法，并引入了 Spring Security Crypto 里的BCryptPasswordEncoder做密码加密。
实现完成后，它再次运行全部测试，确认全绿。然后执行了refactoring技能，把 Controller 里的参数校验抽到了一个独立的@ValidDTO 类里，Service 层的密码强度校验也抽成了私有方法。最后它用writing-commits技能产出了一条语义清晰的 commit message，并建议我检查后再提交。
整个过程大概二十分钟，完成后代码覆盖率直接看得到，核心路径全有测试保护。相比我以前“人来写测试”的流程，这个效果已经相当接近一位中级工程师的产出质量了。
5.5 在这个案例里我学到的三点
第一，流程前置约束比代码能力更重要。AI 不是不能写好代码，而是默认路径总想走捷径。Superpowers 的每一步都像护栏，把它按在正确的轨道上。
第二，Java 项目的初始化配置做一次，一劳永逸。我在第一次使用时就让它识别了 Maven 和 JUnit，之后每次跑测试它都知道该用mvn test，不会瞎猜。
第三，人工 review 仍然不可缺席。AI 写的计划和代码我都会读一遍，尤其是边界条件。你可以把它当副驾驶，但方向盘必须还在自己手上。
6. 常见问题与避坑指南
6.1 技能一直不生效，怎么办
这个是最多人在讨论区问的问题。我的排查顺序是：先确认插件真的装上了（/plugin status或codex plugin status）；再确认当前会话是新开的，旧会话不会自动加载插件；最后用一个简单的 prompt 试探，比如“请列出你现在会用的开发技能”，如果它列出来的内容透明显不是 Superpowers 的风格，说明技能没注入成功，考虑重装。
6.2 模型有时还是会跳过流程，怎么约束
AI 不是每时每刻都严格遵守流程。我自己遇到过两次它“忘了”先跑测试的情况，原因通常是任务太简单、上下文里太多干扰信息。我的经验是：在 prompt 里把流程写死，不要只说“按 superpowers 流程来”，而是说“如果没有运行测试失败就禁止提交代码”。另外，可以在项目的AGENTS.md或 CLAUDE 规则文件里加上同样的要求，让约束在每次会话中都生效。
6.3 Token 消耗变大，值不值
这是个现实问题。装上 Superpowers 之后，模型确实会多读技能文件、多输出计划、多跑几个步骤，单次任务的 token 消耗估计会多出 30% 到 50%。我的判断是：如果这些 token 换回来的是更高的代码质量、更少的返工，那非常值。如果你只是写一次性脚本，确实可以不用它。
6.4 自己加一个技能，没有想象中难
Superpowers 最让我喜欢的一点是技能可扩展。我后来自己写了一个“日志规范检查”技能，存放在~/.superpowers/skills/logging-check.md，内容就是：检查新增代码里的日志是否包含上下文信息、是否使用了正确的日志级别、敏感数据是否被脱敏。自从加了它，AI 在日志这块的产出明显规范了。
6.5 一次别让 AI 连续干太多活
最后一个建议来自我惨痛的经验。Superpowers 流程虽好，但你如果让它一口气同时完成“新功能 + 重构 + 补充历史测试 + 改文档”，它还是会崩。一次只交付一个类型的变更，比流程本身更重要。先实现功能，再单独开一次会话来重构，这样每一步都能被验证。
用了这段时间，我最强烈的感受是：Superpowers 的价值不在“多酷”，而在“多稳”。它把 AI 从一个记忆力有限、路径依赖严重的新手，硬掰成一个讲流程、守纪律的协作对象。如果你也受够了 AI 写代码时那种“每次都要从头教”的感觉，我建议你今晚就装上它，然后挑一个真实的小需求走上一个完整流程。记得，它给你的是方法，方法能不能起作用，还得看你会不会坚决地用。