最近“superpowers”这个词在AI编程圈子里蹿得特别快尤其是用Claude Code和Codex CLI的这群人几乎天天有人问它到底是什么、怎么装、怎么用。我最早也以为这又是个套壳插件后来专门腾了一个周末把项目源码、文档翻了一遍又在自己负责的Java服务上实际跑了两周才确定它根本不是某个“单点工具”而是一整套针对AI编码代理的技能工作流增强方案。这篇文章就是想把这段时间的实践、踩坑和心得一次性讲清楚。如果你正在用AI写代码尤其是已经受够了“AI写得快但不敢交、改起来更累”的状态那你应该接着看下去。它会告诉你superpowers是什么、怎么安装、怎么配合Codex和Java项目落地以及哪些细节是真正常规文档里不会写的。我尽量按一个工程老手的方式来讲不绕弯子。1. 先搞清楚superpowers是什么再决定要不要装1.1 它不是某个插件而是一套给AI编码代理的“技能工作流”很多人第一次听到superpowers会误以为它跟某款IDE插件、某个MCP服务、或者某个模型微调包是一类东西。实际完全不是。它的定位更接近一套“方法论行为规范”的外挂文件包通过向AI编码代理注入一批结构化的技能文件skills并配合总入口文件去约束AI的工作方式让AI从“你说一句、它写一大段”变成“你说需求、它先规划、再写测试、再实现、最后提交”这种更像成熟工程师的节奏。这套设计背后的逻辑其实很朴素。用过Claude Code或Codex CLI的人应该都有体会模型很强但默认状态下它倾向于直接生成代码。代码确实能跑但缺少设计过程、缺少测试、缺少对现有代码结构的尊重。superpowers通过体系化的技能定义强制把AI的工作拆成几个固定阶段。每个阶段是一个独立的技能文件里面写了完整的操作指令、决策判断、注意事项。AI在执行某个阶段时会像查手册一样把对应文件读进上下文照着里面的步骤走。你甚至可以把它理解成给AI配了一套“SOP手册”。没有这套手册AI是一个聪明但随性的新人有了这套手册AI变成了一个按流程走、每个动作都可以被review的靠谱同事。1.2 它和AGENTS.md、skills、MCP到底什么关系要理解superpowers得先分清它依赖的几个基础概念。AGENTS.md在Claude Code里通常叫CLAUDE.md是AI代理启动时自动读取的项目说明书用来描述项目结构、命令规范、代码风格。superpowers把它作为“总入口”在初始化后会把技能清单、调用方式、项目约定写进这个文件。这样AI只要在这个项目里启动就会知道“哦这个项目里有一整套技能规范遇到什么类型任务应该去读哪个技能文件”。skills技能文件则是存放在特定目录下的Markdown文件。每个文件名就是一个能力名称比如tdd.md、commit.md、brainstorm.md。文件内容由项目作者预先写好详细到具体步骤、工作流逻辑、注意事项。当AI判断当前任务匹配某个技能时会把文件内容作为指令引用并严格按内部定义的流程执行。MCPModel Context Protocol则跟superpowers是两类东西。MCP用来给AI挂接外部工具和数据源比如连数据库、查文档仓库。superpowers不负责这些它管理的是“AI做事的方式”。换句话说MCP解决的是“AI能用什么”superpowers解决的是“AI把事情做成什么样”。两者可以共存但别混淆。搞清楚这一层后你就不会问“它比MCP强在哪”这种问题了它们解决的问题根本不在一个维度上。1.3 为什么“先plan、再TDD、后commit”这个组合这么重要superpowers的技能体系里最核心的组合拳是三个技能brainstorm头脑风暴/需求澄清、tdd测试驱动开发、commit提交信息规范。这三个技能被设计成一条固定流水线这是整个框架里最有价值的部分也是你一定要理解的地方。先说brainstorm。它的职责不是写代码而是问问题。AI会用苏格拉底式的提问不断澄清你的需求、发现被忽略的边界条件、引导你列出验收标准。这一步的意义在于“人与AI对齐目标”。大部分AI生成代码跑偏的根源不是模型能力不够而是需求描述一开始就存在歧义。单讲效率多花三分钟澄清需求能省掉后面三十分钟改代码的时间。然后是tdd。这个技能会强制AI先写测试再写实现。测试代码本身就承载了需求验收标准它把“什么叫做对了”明确成了一组可执行的断言。AI写实现时只需要让它自己运行测试直到变绿。这个循环对人和AI都是很自然的约束没有测试AI很容易“自我感觉良好”地写出与预期不符的代码有了测试每一个中间步骤都有客观检验。最后是commit。这个技能负责生成结构清晰的提交信息描述本次改动做了什么、为什么这么做。它还把“小步提交”变成习惯。AI每完成一个原子改动就提交一次而不是憋一个大PR。这样回滚和review的粒度都小得多对团队协作是实打实的提升。这三个技能串起来之后AI的行为模式就从一个“自动代码生成器”变成了一套完整的工程闭环澄清→测试→实现→提交。这也是superpowers最核心的价值主张后面的安装和使用都围绕这一点展开。2. 安装与初始化三分钟把框架跑起来2.1 安装前置条件与版本选择安装superpowers之前先确认你本机已经具备三样东西Node.js建议16以上、Git、以及一个可用的AI编码代理工具。它可以是你已经装好的Claude Code也可以是OpenAI Codex CLI。因为superpowers本质是把技能文件和入口文件写到项目里跟你用哪个Agent运行并不存在强绑定。版本选择上有一点需要注意。如果你是在生产项目上试不建议直接从GitHub主干拉取最新代码就跑。这个项目迭代速度快动作频繁主干和正式发行tag之间可能有行为差异。稳妥的做法是查看仓库的releases页选择最近的稳定版本进行安装。我自己的习惯是把版本号记录在笔记里出了问题能快速回退。如果你从来没有用过Claude Code或Codex CLI我建议先把基础的问答功能跑通一次再引入superpowers。否则一旦出现异常你会分不清是Agent本身的问题还是技能框架的问题。基础工具的手感先有了排查起来会快很多。2.2 标准安装步骤含代码块根据项目仓库目前的主流初始化方式安装可以拆成两步拉框架代码然后在目标项目里做项目级初始化。一个常规流程是这样# 1. 找一个你希望保存工具源码的目录比如 ~/tools cd ~/tools # 2. 拉取主仓库 git clone https://github.com/obra/superpowers.git cd superpowers # 3. 安装依赖并执行安装脚本 npm install npm run setupnpm run setup会引导你选择安装范围装到当前目录还是装到一个全局位置。如果你希望所有项目都能使用框架也可以选择全局安装到用户级目录。不过我更推荐在单个项目内先做项目级初始化目的是让技能文件跟着项目走这样团队成员用同一个仓库时会自动继承这套规范不需要每个人都单独配置。初始化完成后脚本会在项目根目录生成两个重要结果一个是skills目录里面躺着框架自带的技能文件另一个是更新过的AGENTS.md或CLAUDE.md里面写入了技能索引和调用约定。如果你用的是Codex CLI入口文件名通常是AGENTS.mdClaude Code则更倾向使用CLAUDE.md。具体让AI读哪个文件取决于你当前用的Agent工具初始化脚本一般会自动识别。为了验证安装是否成功你还可以在项目目录里新建一个空的Markdown文件用中文写一句“请阅读项目技能规范然后总结本项目的技能列表和第一个技能的功能”。如果AI能正确地报出几个技能名称并给出说明说明入口文件已经被读到了安装这一环就算通了。2.3 初始化后目录长什么样怎么验证装好了完成初始化之后我建议你先别急着写业务代码而是花两分钟观察一下项目结构发生的变化。正常情况下应该看到类似这样的布局your-project/ ├── AGENTS.md # 项目入口AI启动时会读 ├── skills/ │ ├── brainstorm.md │ ├── plan.md │ ├── tdd.md │ ├── commit.md │ ├── debugging.md │ └── ... └── .superpowers/ # 框架运行状态与缓存这跟你自己手动写一个AGENTS.md来约束AI是完全不同的。普通AGENTS.md只能放一段静态说明AI大概率只是“看过”而superpowers把技能文件拆成粒度极细的独立模块AI在特定场景下会主动去加载对应模块并当作操作手册执行。这种动态按需调用的方式比一封长的提示词要可靠得多。验证装好没有我还有个更直接的办法直接把你的需求丢给AI看它是不是先开始问问题、出计划而不是急着一口气把代码全写了。如果它一上来就写代码说明技能没有被正确触发这时候就要回头检查入口文件是否被Agent正确加载了。3. 核心技能拆解哪些技能值得日常用3.1 核心技能清单与使用场景superpowers自带的技能文件不止一两个拆开看每个都对应一类高频场景。我用下来觉得最值得关注的是下面这些技能名称主要场景为什么值得用brainstorm需求澄清、功能设计强制AI先问问题减少需求歧义plan生成实施计划把大任务拆成小步骤让AI按步骤推进tdd测试驱动开发先写测试再写实现提高代码可验证性commit生成提交信息统一commit格式小步提交debugging定位并修复Bug引导AI先复现、再推断、再修复refactoring重构既有代码约束AI在重构时保持行为不变刚开始接触时不要贪多我建议团队只需要把brainstorm、tdd、commit这三个彻底用熟就已经能显著改变AI的工作输出质量。debugging和refactoring等后面再逐步放开。有人可能会问这些技能文件里的内容是不是固定的实际上你可以自行修改。这算superpowers的一个优势所在。如果团队有自己的编码规范完全可以改掉技能文件里的指令让这套框架变成团队定制版。但有一点要提醒修改技能文件前最好复制一份原文件备份并记录改了什么否则升级框架时容易冲突。3.2 技能调用的正确姿势别硬记关键词很多人误以为用superpowers就像给AI发指令绪词比如必须说“请执行brainstorm技能”AI才会触发对应技能。实际用下来这套框架对自然语言的兼容度比我预期要高。你只需要用日常语言描述当前场景AI就能根据语境自动匹配技能。比如你说“我有一个新功能想做但还没想清楚需求边界”它会自动进入brainstorm模式反过来向你提问。你说“帮我改这段逻辑顺便把相关测试加上”它大概率会进入tdd流程。正确姿势是“表达意图而不是发指令”。你越是自然地描述业务场景技能触发的准确率越高。这也解释了一个常见误区有人以为技能是靠关键词硬匹配触发的于是刻意把prompt写成“调用tdd技能”反而让AI在技能触发和任务理解之间做了不必要的往返。真正的做法是人负责描述清楚意图AI负责选择合适的技能路径。这个认知转换之后你会发现整个对话流畅度会有明显提升。3.3 Java项目的适配从“能跑”到“好用”这回的热搜词里有个“superpowers java”说明不少人在Java项目上尝试用它。我自己的主力项目就是Spring Boot的Java服务所以这块可以多说一点。superpowers的技能文件本身并不和某个语言绑定TDD流程在Java和Python里都能跑。但Java项目有其特殊性如果不做适配你很快会发现AI给出的测试命令、构建方式跟你项目实际不符。需要调整的核心有两块。第一块是测试命令约定常规技能文件里可能默认用pytest或npm test你在Java项目里必须显式告诉AI用mvn test还是./gradlew test以及要不要加-pl限定模块、要不要跳过某些集成测试。第二块是JUnit版本与断言语义Java 8和Java 17上跑的JUnit 4/5在写法上有差异如果项目还在用JUnit 4AI生成一套JUnit 5的测试代码就会很尴尬。我的做法是在AGENTS.md里追加一段Java项目约定明确写出## Java Project Convention - Build tool: Maven, run tests with mvn test -DfailIfNoTestsfalse - Java version: 17 - Test framework: JUnit 5 - Spring Boot 3.x, use SpringBootTest for integration tests - Always run mvn -q compile before writing tests这段文件会让AI在后续所有技能执行过程中都把Java约定纳入约束范围。适配之后TDD技能生成的测试代码基本可以直接跑起来构建命令也不会再瞎猜。这一步非常重要做和不做实际体验差距极大。3.4 与Codex CLI配合使用的经验这次的热词里还有“codex superpowers”说明很多人已经在Codex上用过或者准备用它。Codex CLI跟Claude Code的行为习惯不太一样它对AGENTS.md更敏感所以superpowers在Codex场景下的适配反而比想象中顺利。但有一个事要单独提醒你Codex CLI在自动执行命令的时候默认安全策略可能比较谨慎读写文件、执行测试类的命令经常需要确认。这跟TDD流程天然存在摩擦因为TDD要求反复运行测试每次都弹确认框的话体验会很割裂。解决办法是在Codex CLI的配置里调整权限级别把项目目录设置为可信目录或者在确认模式下放开对mvn test这类已知安全命令的自动执行。我实际用下来把本地项目目录加入白名单之后整个TDD循环变得顺畅很多。如果你用的是Codex网页版或IDE插件原理一样核心思路是让测试命令的自动执行不被卡在交互确认上。另外说一句Codex对技能文件里命令的解析比Claude Code更“字面化”。它很少自己脑补缺失参数所以你的技能文件里涉及命令行操作时参数一定要写完整。越是显式Codex执行得越准。这也算是我踩过几次坑之后的深刻教训。4. 实操过程实录从需求到提交走一遍完整流程4.1 场景与约束给旧服务加一个不再重复消费的接口为了让你更直观地理解这套工作流我拿一个真实发生过的场景来演示。团队有个订单回调服务第三方会重复推送同一事件目前逻辑是入库前手动检查是否已存在经常出现并发重复问题。需求是“做一个幂等事件接收接口对相同eventId的请求只处理一次”。这个需求表面看起来很简单但里面藏着不少没有说清的细节。比如“相同eventId”的作用域要不要叠加租户维度重复请求时返回成功还是返回已存在“只处理一次”的并发边界怎么保证这类问题如果人不先想清楚AI强行写出来的代码大概率会在代码评审时被同事挑战。按旧习惯我可能直接一句话丢给AI让它写实现这次我决定走superpowers的标准流程。先在对话里用一句话描述目标并明确希望按标准技能流程推进。接下来就是全套流程的实演。4.2 完整操作需求→brainstorm→plan→TDD→commit我把实际执行过程按顺序记录下来这一段基本是现场还原。第一步AI进入brainstorm技能。它没有急着写代码而是一口气向我提了五六个问题包括eventId的全局唯一性如何保证、重复请求与首次请求的响应体是否要求一致、是否需要支持事务内幂等、性能上允不允许每次都用数据库查询来判重、异常情况下是否需要兜底。这些问题里面有几个是我在初步需求里确实没考虑清楚的属于这个技能带来的实打实回报。第二步AI进入plan技能。它把功能拆成了五个步骤新增事件表结构、写幂等校验工具、实现处理器接口、补充并发场景测试、回归旧接口。每一步下面都写明了涉及的文件路径和验收目标。这个计划本身是可以直接作为开发任务的甚至可以直接贴到迭代需求卡里去。第三步进入tdd技能。AI先写了一批单元测试和集成测试用例覆盖单线程重复、多线程并发重复、极端情况下同eventId但不同租户等场景。因为这些测试本身就是从brainstorm阶段的澄清结果里推导出来的所以测试粒度很清楚。写完测试后开始写实现代码一边写一边跑测试直到所有测试通过。我在这个过程中基本处于观察状态只在测试全绿之后手动跑了一遍旧的回归用例确认旧接口没有受到影响。第四步进入commit技能。AI分析了git diff把改动按“新增表结构”“新增幂等工具类”“新增处理器”“更新测试”拆分成了多个原子提交每个提交的信息都写清了改动内容和原因。最终呈现出来的提交记录干净且可追溯比我自己随手commit的质量高。4.3 实测过程记录与结果观察整个流程下来有一组观察数据可以给你参考。从需求描述到测试全绿花费时间大概一个半小时这里面包含了不少AI提问等待我回答的时间。换作以前如果直接让AI写半小时能出代码但随后代码评审往往要改两三轮算上返工时间总消耗不仅没少反而更不容易控制。更重要的变化在心态层面。以前AI写完一段代码我总有一种“不确定它为何这么写”的悬空感这次因为有brainstorm阶段的澄清记录和TDD阶段的测试支撑我对最终代码的信任度明显更高。评审时同事提出“并发下会不会丢事件”的疑问我直接抛出了AI写好并跑通过的并发测试用例问题当场关闭。这种让AI自证正确性的方式在日常开发中带来的价值远超写代码本身。当然这个流程不是万能的。如果团队需求本身非常临时的、只做一次性验证脚本走完整套流程确实显得重。对探索类任务我会直接跳过plan和tdd只保留commit规范。框架是灵活的关键是你自己要清楚当前任务的属性。5. 常见问题与排查技巧实录5.1 高频问题速查表把大家问得最多、以及我自己在实际操作中遇到的高频问题整理成了表格方便快速定位。问题表现常见原因处理建议AI不触发任何技能直接就写代码入口文件没有加载成功确认AGENTS.md/CLAUDE.md存在且被Agent读取技能触发了但步骤执行不完整上下文被截断或技能文件被修改过检查是否同时开了多个工具导致上下文超限AI生成的测试命令跟你项目不符技能文件没有包含项目约定在AGENTS.md补充构建工具、测试框架等信息commit技能生成多条提交但顺序混乱没有要求AI先设计提交计划在plan阶段就要求列出提交粒度频繁弹确认框导致TDD流程卡顿Codex CLI安全策略太严格设置目录级信任放行已知测试命令升级后技能文件被覆盖初始化脚本重新生成默认文件升级前养成备份习惯5.2 我自己踩过的坑与解决思路第一个坑是高估了“自然语言触发”的稳定性。在一次需求中我用了“看一下这个模块改个接口”这种没头没尾的描述结果AI没有进入brainstorm阶段直接按照不太靠谱的理解改起了代码。后来我养成了习惯即使明确想让AI自主触发技能第一句描述也会尽量把目标、约束、明显边界带上而不是扔过去一个含混的句子。别把技能触发完全交给模型判断人该给的信息要给足。第二个坑是上下文溢出问题。当项目比较大时AI为了走流程会把多个技能文件、代码文件都读入上下文很容易在任务执行到一半时触发上下文窗口上限。我的应对方式是任务开始前主动清理无关历史对话甚至在一个新会话里重新描述需求。superpowers的技能文件是幂等的你随时可以开新会话继续执行并不会丢失工作流。这一点反而比传统对话式编程更适合大型项目。第三个坑是并发写测试时的性能问题。Java项目如果测试类过多mvn test跑起来时间很长AI在TDD循环里会频繁等待。这个坑不算框架的问题但如果不注意体验会大打折扣。我的建议是用Maven的-pl参数只测当前模块对于单测跑不动的场景可以把部分测试降级为本地手动验证而不是让AI在一个慢测试套件上反复空转。5.3 一些长期使用后的维护建议技能文件也是代码同样需要演进。我现在的做法是把superpowers的版本固定在项目文档里每次升级时先在一个实验分支上跑一周确认没有破坏性变化后再合到主干。对于团队里的新人我还会让他们先读一遍brainstorm.md和tdd.md。因为这两个文件本质上是对团队工程文化的最佳讲解比任何内部培训文档都直观。另外一个容易被忽略的细节是AGENTS.md既会被superpowers使用也可能被团队其他提示词模板使用。如果你在文件里追加了Java项目约定请务必保证这些约定跟团队真正的构建方式一致否则AI会严格遵守一份过期文档反而帮了倒忙。文档与代码同步维护是引入这类框架后必须承担的成本。最后说说我的整体体会。superpowers真正让我觉得值得推荐的不是某个单独技能而是它重新定义了人和AI写代码时分工的边界人负责想清楚要什么AI负责用规范的方式把它实现出来。它没有试图让AI变得更“聪明”而是让AI变得更“克制”。有了这层克制之后AI写代码的质量和可维护性确实上了一个台阶。如果你手里正好有一个中小型项目又正在犹豫要不要让AI深度参与日常开发我建议你找个周末把这个框架装到测试项目里让它完整跑一次TDD流程。亲身体验过“AI先对你提问、再写测试、再动代码”这个过程你就明白为什么它会值回安装成本。
