很久以前我有个挺天真的想法给 AI 编程助手丢一句话它就能把整个项目写好。后来实际用下来发现模型本身再聪明如果你不告诉它该按什么流程干活它一样会把代码写得又乱又飘——喜欢一上来就动手写完了才发现需求理解偏了返工成本比你自己写还高。直到我接触了superpowers这个开源项目才意识到问题不在模型而在工作方式。简单说superpowers 是一套给 Codex、Claude Code 这类 AI 编程工具预制的技能包它不是插件也不是某个 IDE 扩展而是一组结构化的技能文件。装上之后AI 在动手写代码之前会先学会一件事怎么澄清需求、怎么拆解计划、怎么按步执行、怎么在出错时系统化排查。说白了就是给 AI 补上正规军的作战流程。这篇文章我就把自己从安装到实战的完整过程写出来尤其是那些文档里没写、你只有踩过坑才知道的细节。如果你正被AI 写代码一时爽review 火葬场折磨或者想让 Codex 在 Java、Python 这类工程里输出更可控这篇内容应该能帮你少走不少弯路。1. superpowers 到底做了什么它不是插件而是一套AI 工作流技能包1.1 为什么要给 AI 编程助手加技能先想一个问题你在公司带一个刚毕业的新人会直接甩给他一个需求让他写代码吗大概率不会。你会先让他复述需求、确认边界、拆任务、估时间甚至告诉他遇到问题先自己排查别急着来问我。这一整套东西就是工作流是一个人能稳定产出的前提。但绝大多数人用 AI 编程工具的时候恰恰跳过了这一步。Codex 拿到 prompt 就开写写完就交差根本不会问你这个需求和现有模块有什么关系改动影响范围有多大。这不是模型笨而是它默认的执行路径就是最短路径。superpowers 做的事情就是把这些工作流以技能的形式塞给 AI让它每次开工前都被强制进入一套规范流程。项目作者把技能分成几个核心方向包括 brainstorming需求头脑风暴、planning执行计划、executing按步执行、troubleshooting分步调试等。每个技能内部都有非常具体的操作协议AI 会通过读取技能说明文件来学习这些协议然后在对话中按命令触发。这里要强调一下它改的不是模型本身的推理能力而是提示词层面的执行框架——与其说是增强 AI不如说是约束 AI。1.2 四个核心技能各自管什么我把这套技能包理解成一个项目经理 资深工程师的角色组合拆开看是这样的brainstorming需求澄清强制 AI 在动手前把需求问清楚。比如用户说我要一个用户登录功能AI 不会直接写而是会反问登录方式有哪些有没有第三方 OAuthtoken 有效期多久忘记密码怎么处理这套技能的本质是把模糊需求通过多轮问答变成可执行的需求说明。planning执行计划需求清楚了之后AI 会把整个实现拆成多个步骤每一步都明确目标、涉及文件、验证方式。它甚至会给每个步骤编号方便后续按编号执行这就是网上常看到的 evaluate、next-step 这类命令的由来。executing按步执行在 planning 生成的计划基础上AI 会一个步骤一个步骤地执行每完成一步就做自检而不是一口气把所有文件写完。troubleshooting分步调试执行过程中报错了AI 会先让你描述现象、贴报错信息然后一步步定位问题而不是直接瞎改。这几个技能合在一起让 AI 的工作方式从问答式变成了项目制。虽然每次对话看起来多绕了几步但最终交付质量确实高了不止一个档次。1.3 为什么叫 superpowers从会写代码到会干活项目名叫 superpowers 其实特别贴切。打个比方普通模式下你用的是普通员工 AI它什么都会一点但你得随时盯着superpowers 模式下的 AI 更像一个有自驱力的工程师你给它一个模糊目标它自己知道要进入 brainstorming 来澄清自己会拆计划自己会按步执行失败了还会自己排查。对我来说它最大的价值不是让 AI 写代码更快而是让 AI 的产出可以被预测。以前我 review AI 代码的时候经常气得头疼因为它东一榔头西一棒子现在它每一步都在计划内我是按计划去 review压力完全不一样了。2. 从零安装到接入 Codex我把踩过的坑提前标出来2.1 环境要求与装前检查先别急着 clone把环境准备好。superpowers 对本地环境的要求不算高但你得确认三样东西Git用来克隆仓库这个基本都有。Node.js很多辅助脚本依赖 Node 运行时建议版本不低于 18否则某些技能脚本跑不起来。我自己的机器上是 Node 20一切正常。Codex CLI 或兼容的 AI 编程工具目前社区里用得最多的就是 Codex 和 Claude Code你至少要有其中一个能跑通基础对话。装前检查这一段我建议你在终端里先跑一句node -v git --version codex --version如果三个都有正常输出就可以继续了。如果codex命令不存在说明 Codex CLI 还没安装或者没有加入 PATH先装好再来。2.2 克隆仓库与技能目录的路径选择这是我在实际安装时遇到的第一个坑。很多教程让你 clone 到项目目录里结果每个项目都复制一份维护起来非常痛苦。我的建议是把它放到一个独立目录比如用户主目录下的隐藏文件夹cd ~ git clone https://github.com/obra/superpowers.git .superpowers注意仓库地址以官方 README 为准。克隆完成后你会看到类似这样的结构~/.superpowers/ ├── skills/ │ ├── brainstorming/ │ ├── planning/ │ ├── executing/ │ └── troubleshooting/ ├── AGENTS.md └── README.mdskill 文件其实都是 Markdown 文档加配套脚本。Markdown 文档给 AI 看脚本则是辅助执行用的。所以你要是想自己改技能完全可以直接编辑这些 Markdown门槛很低。如果你用的不是 Codex 而是其他工具也可以照这个思路 clone 到任意位置后面只要在配置里把路径指过去就行。2.3 让 Codex 认识 superpowers全局指令的配置方法这是整个安装过程中最关键的一步。克隆完成不代表 Codex 会自动加载技能你必须告诉它每次开工前先去看看这些技能文件。Codex CLI 有一个全局指令文件机制一般是~/.codex/AGENTS.md。你把下面这段内容追加进去Before starting any coding task, read the skill definitions in ~/.superpowers/skills/. Follow the command protocols defined in those skills for brainstorming, planning, executing, and troubleshooting. If the user says a command like evaluate, next-step, dothat, or reference, comply with the corresponding skill.保存之后建议新开一个 Codex 会话再测试。如果你用的是 Claude Code则在~/.claude/CLAUDE.md里加类似内容原理一样。这里有个容易被忽略的细节Codex 对系统指令的加载是按会话来的如果你修改 AGENTS.md 之前已经开了会话必须重启会话才生效。我有一次改完配置忘了重启跟 AI 聊了半天发现技能根本没加载白白浪费了十几分钟。2.4 验证技能是否真正加载配置完怎么确认生效最简单的办法在 Codex 里输入你加载了哪些技能请列出技能名称和对应的命令。如果配置成功它会告诉你加载了 brainstorming、planning、executing、troubleshooting 这几个技能以及相关命令。如果它一脸茫然说明 AGENTS.md 没有被读取按下面顺序排查确认~/.codex/AGENTS.md文件路径拼写正确。确认 Codex 会话已重启。在 Codex 里输入pwd和ls -la ~/.superpowers/skills/看能不能正确列出文件。这一套验证做完基本上就能进入实战了。3. 核心命令是怎么工作的evaluate、next-step、dothat 的调用逻辑3.1 技能加载原理SKILL.md 就是 AI 的操作手册你可能会好奇AI 是怎么知道 superpowers 的操作协议的答案就在于每个技能目录下的 SKILL.md 文件。这个文件用 Markdown 写成内容非常像一份操作手册里面定义了这个技能解决什么问题在什么情况下应该触发支持哪些命令每个命令的参数和输出格式执行步骤的先后顺序和判定标准。当你在对话里输入evaluate或者next-step这类命令时Codex 会去对应技能的 SKILL.md 里找到命令定义然后按里面的规则执行。这本质上就是提示词工程的模块化——把零散的工作流指令变成了可复用、可组合的函数库。所以你可以把 superpowers 理解成AI 的操作系统补丁SKILL.md 就是补丁里定义的 API 规范AI 通过 AGENTS.md 的引导在运行时动态加载这些规范。3.2 常用命令对照表用了一段时间之后我把高频命令整理成了一张表方便大家快速查阅命令所属技能作用典型场景brainstormbrainstorming对需求进行多轮澄清拿到模糊需求时evaluateplanning评估当前状态决定下一步动作不知道接下来该做什么时next-stepplanning/executing输出并执行计划中的下一步按计划推进时dothatexecuting明确执行指定的一步计划已分解成具体任务时referenceexecuting把某个文件或模块设为参考上下文改动前需要理解现有代码时summaryexecuting生成当前进展摘要中断后恢复上下文时troubleshoottroubleshooting进入分步排查模式出现编译错误或测试失败时这张表不是官方文档的复述而是我自己实际使用中哪些命令真正用得上的总结。比如summary这个命令很多教程没提但跨天续接会话的时候真的救命——AI 会把当前进度、已改文件、待办事项压缩成一段摘要你贴到新会话里就能无缝接续。3.3 什么时候手动干预命令也不能全自动说实话superpowers 不是万能的。有些场景下你不需要走完整套流程比如只改一个配置项的取值完全不需要 brainstorming一个文件里的 bug 修复没必要拆成十个 step 去执行。这种时候我一般会直接告诉 AI跳过 planning直接做而不是强行让它走流程。superpowers 的价值在于你可以在需要的时候把它拉进规范流程而不是每时每刻都开着。项目方也支持这种用法——技能系统只是一个框架触发权始终在用户手里。另外有个使用上的小技巧如果你发现 AI 在 planning 阶段拆出的步骤太粗可以这样要求把第二步再拆细一点按函数粒度拆。它能理解并重新生成计划。反过来如果步骤太细我会说合并同类步骤保留关键节点即可。这个度需要你根据自己的项目复杂度去磨合。4. 实战走查用 Codex superpowers 做完一个 Java 小需求4.1 从 brainstorming 开始先别急着写代码空谈概念没用我拿一个真实的 Java 需求走一遍。假设产品经理丢来一句话给后台管理系统加一个用户导入功能支持 Excel。如果是以前我会直接让 Codex 写代码然后它就会自作主张选 EasyExcel、设计一个上传接口、写一个解析逻辑完了告诉你完成了。但导入涉及的问题远比这句话丰富表头怎么校验重复数据怎么处理最多允许导入多少行失败后是整体回滚还是逐行提示在 superpowers 模式下我先输入brainstorm我要给后台管理系统加一个用户导入功能支持 Excel。AI 没有直接写代码而是开始抛问题。其中有几条我印象非常深刻导入的 Excel 是否有固定模板表头字段名和顺序是什么重复用户判断的唯一键是用户名还是邮箱导入过程中如果某一行数据格式错误是跳过该行继续导入还是整个文件失败回滚一个文件最多允许多少行数据需不需要异步处理已有用户被重复导入时是报错、跳过还是更新覆盖这些问题看似繁琐但每一个都是你要是上线以后才发现就得改数据库、改接口、加班的级别。我当时把答案一条条整理给了它最后它生成了一份结构化的需求说明包含数据格式规范、校验规则、失败处理策略、性能约束。到这一步你会发现brainstorming 的价值不在于多问了几个问题而在于把隐性需求逼到了台面上。4.2 planning 阶段把计划拆到可以下一步执行需求澄清之后我输入基于上面的需求说明进入 planning给出执行计划。AI 开始拆分任务。它给出来的计划大概是这样的引入 EasyExcel 依赖版本锁定新增UserImportDTO和UserImportResultVO两个数据传输对象实现UserImportService.importUsers(MultipartFile file)核心逻辑编写 Excel 模板校验工具类新增导入结果查询接口和前端页面编写单元测试覆盖正常、重复、格式错误三类场景。每一步都标了涉及文件和验收标准。比如第一步的验收标准是pom.xml 中能解析到 EasyExcel 相关类mvn compile通过第三步的验收标准是同一批次内重复数据只保留第一条重复记录写入错误列表并返回。这个时候你就能看出 planning 的功力了它把用户导入功能拆成了可验证、可单独交付的任务块。以前让 AI 直接写的代码是一次性生成一大坨出了问题你甚至不知道从哪开始排查现在每一步都是一个检查点哪一步挂了就修哪一步。4.3 executing 阶段让 AI 按步执行并自检计划确认后我挨个输入next-stepAI 会执行计划中的第一步然后停下来汇报改了哪些文件、结果如何、自检是否通过。我实际测试中有一个很典型的例子——第二步生成 DTO 的时候AI 刚开始设计的字段和表头不一致把手机号字段命名成了phoneNumber而模板表头里叫mobile。如果在以前这种不一致可能要等到联调测接口时才会暴露但因为 superpowers 要求每一步执行完要做自检对照计划里的验收标准它在第三步开始前发现了这个命名不一致主动问我按哪个字段名统一。这一下就帮我避免了一次返工。最终代码写完AI 运行了mvn test先是两个用例没过它没有直接改测试断言而是先报给我看然后进入 troubleshooting 流程定位是逻辑问题还是测试数据问题。4.4 失败与 troubleshooting让 AI 自己描述问题再修上面提到的两个失败用例其实暴露的是一个边界条件问题当用户名为空但邮箱合法时当前逻辑抛了IllegalArgumentException但需求里定义的是空用户名记录到错误列表不影响其他行导入。这个 bug 是需求与实现的偏差不是语法错误。我输入troubleshoot测试用例失败了报错信息和期望行为如下...AI 没有马上改代码而是先让你描述现象再列出可能的根因然后逐项排查最后才给出修复方案。它给的修复是在校验阶段把用户名为空从抛异常改到收集错误并跳过该行再补一个对应的单元测试。修复完测试全绿整个流程收工。这一个完整流程走下来我最大的感受是superpowers 把思考过程从黑盒变成了白盒。以前你只能看到模型丢出来的结果现在你能看到需求澄清、任务拆解、自检报告、失败分析每一步都可追踪。5. 真实使用中的问题与调优建议5.1 技能没有生效AI 还是自顾自写代码这是我被问得最多的问题我明明配置了 AGENTS.md为什么 AI 还是不理技能包我遇到过几种情况会话没重启。AGENTS.md 的改动不会热更新你必须在配置后新开一个对话。项目里有自己的 AGENTS.md。Codex 读取指令时如果项目级配置和全局配置都存在有可能项目级配置覆盖了你的全局技能引导。解决办法是把 superpowers 的加载指令也加到项目级 AGENTS.md 里或者在对话里直接补一句在开始前先读取 ~/.superpowers/skills 下的技能定义。命令写得不标准。比如你输入下一步AI 可能不会触发next-step技能而是理解为普通对话。superpowers 的触发依赖明确的命令词建议直接输入next-step或dothat不要用自然语言变体。5.2 上下文太长被截断超大项目里要善用 summarysuperpowers 每一步都要输出自检和汇报这确实会消耗更多上下文 token。在超大仓库里计划还没执行一半Codex 就开始失忆。我的应对方法是在 planning 阶段生成计划后先让 AI 输出一份summary保存到本地如果上下文快满了就开新会话把摘要贴进去继续用next-step推进executing 阶段尽量少让 AI 引用大文件全文用读取第 X 行到第 Y 行代替读取整个文件。出现这种问题时先检查是不是你的需求根本没有拆细让 AI 在一次回复里塞了太多内容。superpowers 的流程设计本身就是为了小而美的步骤而不是大而全的输出如果发现步骤太大回到 planning 阶段重新拆分。5.3 公司规范怎么融进去自定义技能包superpowers 最好的地方就是它允许你自定义技能。我们团队有自己的一套代码规范Controller 层必须返回统一响应体、禁止在 Service 里直接 new Thread、日志必须带 traceId。以前这些规范都是写进文档里AI 根本不看现在我可以把它们做成一个独立的技能放进~/.superpowers/skills/team-rules/SKILL.md并在 AGENTS.md 里追加一句同时加载 team-rules 技能。新的 SKILL.md 内容大概是# Team Rules ## 适用范围 所有 Java 后端代码生成任务。 ## 强制规则 - Controller 层方法必须返回 ResultT禁止直接返回实体类 - Service 层禁止创建线程池或 new Thread - 所有日志必须包含 traceId 占位符 - 新增依赖必须经过架构组确认。 ## 检查方式 代码生成完成后逐条对照上述规则自检并在汇报中列出每条规则的检查结果。只要配上这个技能AI 写出来的东西从一开始就符合团队规范code review 的压力直接减了一半。这个思路大家可以举一反三——不只是代码规范数据库命名、接口文档格式、commit message 规范全都能做成技能。5.4 什么时候不建议用 superpowers最后说点实在的不是什么场景都适合套这套流程。我自己的判断标准是一次性脚本、临时调试代码不需要走 brainstorming 和 planning直接写反而更快简历级 Demo、原型验证目标是快速看到效果流程会拖慢节奏改动量极小一两行配置用了就是纯损耗需求本身极度明确且无歧义比如把所有System.out.println换成 log.info没必要让 AI 反问。superpowers 最擅长的是那种需求模糊、改动面广、失败影响大的中大型任务。在上面这些场景里我通常会在对话里加一句跳过 superpowers 流程直接执行完全没问题。6. 往深处玩从用技能到写技能如果你已经用熟了官方技能我强烈建议你开始写自己的技能。这算是 superpowers 提供的最被低估的能力。写一个技能没那么玄乎核心就三件事定义触发条件、定义执行步骤、定义验收标准。拿我最近做的一个前端技能举例。我们团队前端代码风格比较统一我建了一个frontend-cleanup技能触发条件是对 React 组件进行重构执行步骤是先梳理组件 props 和 state标记无用代码然后拆分子组件最后跑 lint 和类型检查验收标准是重构后组件开闭原则满足度高、lint 通过、props 命名符合团队规范。每次 Codex 重构完组件我都会让它跑一遍这个技能产出质量稳定得让人感动。写技能的时候有个关键点步骤别写太细AI 需要一定的自由发挥空间验收标准必须可执行不能写优化代码质量这种虚的要写npm run lint通过且无any类型这种能一句话验证的。另外官方技能包里的 brainstorming 和 planning 是通用的一般情况下不建议改这两部分因为它们是整个流程的地基。要定制优先从 executing 和团队规范类技能入手。说回到开头那个问题为什么同样的 AI 助手有人用起来像神兵利器有人用起来像人工智障superpowers 给出的答案是把方法论外置到提示词框架里让 AI 在正确的流程里干活。我个人用下来的体会是它并不能让代码凭空少写但它能让每一段代码都有迹可循、可审查、可预测这才是它最值钱的地方。最后给想上手的朋友一个建议别想着一次装完就全懂先拿一个小项目跑通 brainstorming 和 planning 两个技能感受一下AI 主动向你提问和AI 拆计划拆得比你还细是什么体验再决定要不要全面铺开。这套东西用对了你可能会跟我一样越来越不愿意回到裸奔模式的 Codex 了。
