说实话第一次听说Superpowers这个词的时候我以为是某种新的编程语言或框架宣传语。直到我在Codex CLI里真正装上这套技能库才意识到它解决的是我一直忍着没说的那个痛点AI编码工具不是不够强而是太“听话”了。你给它一个模糊任务它立刻给你吐一堆代码你让它改个bug它顺手把旁边不该动的逻辑也重构了。这种“答非所问”不是模型变笨了而是缺少一套“先想清楚再动手”的约束机制。Superpowers就是给Codex CLI补上这套机制的开源技能包让终端里的AI从一个“有求必应的代码生成器”变成一个“先规划、再实现、最后自查”的协作工程师。这篇文章我会从安装到实操把Superpowers的使用逻辑和背后设计讲透适合正在用Codex CLI做真实项目的开发者也适合那些想在AI辅助下建立规范工作流的团队。1. Superpowers是什么让Codex CLI从“接单”变成“干活”1.1 技能包与提示词模板的差别很多人第一次接触Superpowers时都会问这不就是一堆Markdown提示词模板吗我自己刚开始也有这个疑问但真正拆开它的目录结构之后就明白了提示词模板只是表象核心差别在“技能”这个载体上。Codex CLI从某个版本开始支持自定义技能Skills技能是一个目录里面有SKILL.md作为技能说明还可以附带脚本、参考资料、命令入口。Codex在处理任务时会按需加载技能目录里的说明把其中的步骤和方法当成行为约束。Superpowers做的工作是把一批经过验证的工程工作流——比如需求分析、方案规划、测试驱动开发、代码审查——封装成一个个这样的技能目录。它和普通的提示词模板最大的区别在于提示词是一次性的技能是可复用的、可组合的、可被模型识别并自动触发的行为单元。我打个比方提示词模板像是一张手写菜谱你得把它拿出来递给厨师技能则像是厨师自己熟悉的一套标准操作流程你只需要说“按咱们店里的规矩做”他自然知道先去备菜、再起锅、最后摆盘。Superpowers就是那套“店里的规矩”。1.2 工作流被显式化的意义我认为Superpowers最有价值的地方不是它提供了多少个技能而是它把“工作流”这件事从隐性的变成了显性的。以前用Codex CLI工作流完全靠模型临场发挥。你让它写个订单模块它可能直接开始写写完了你才发现缺少异常处理、没有写测试、接口设计也是拍脑袋。Superpowers的做法是强制把流程拆开先用调研类技能摸清现状再用规划类技能输出实施方案然后才进入编码阶段编码过程中穿插测试技能最后用审查技能做一次自查。每一步都有明确的输入和输出模型不再凭感觉跳步。这种显式化带来两个直接好处。第一你可以在任意节点介入而不是等Codex把整段代码写完了才说“这里不是我要的”。第二你可以在项目里复用同一套流程标准不管换人还是换项目质量下限被拉高了。对团队协作来说这一点比任何代码规范文档都更落地。2. 安装与初始化五分钟把技能库放进本地Codex2.1 前置条件在动手之前先确认环境满足几个条件。Superpowers本身基于Node.js生态所以本地需要Node.js 18以上版本npm版本建议9以上Codex CLI需要已经安装完成并且你已经完成了认证能在终端里和Codex正常对话。这些条件不满足的话后面安装过程会报各种奇怪的错我见过有人卡在npx阶段大半天最后发现是Node版本太旧。另外我强烈建议在类Unix环境macOS或WSL2里的Linux下安装使用。不是Windows不能用而是技能目录路径、脚本权限这些细节在Unix环境下更省心。如果你主力是Windows至少给Codex CLI装一套WSL2环境后面会少踩很多坑。2.2 安装命令与目录结构安装Superpowers最简单的方式是用npx直接执行安装器npx obra/superpowerslatest install执行这个命令后安装器会自动探测Codex的配置目录通常就是~/.codex把Superpowers的技能目录复制到~/.codex/skills下并顺手更新~/.codex/AGENTS.md让Codex在启动时能感知到这些技能的存在。整个过程只需要几分钟。如果你不放心自动安装器做了什么也可以手动来从GitHub上把obra/superpowers仓库克隆到本地然后查看仓库里的安装脚本再自行执行。两种方式最终的效果是一样的区别只在于你愿不愿意相信那个自动脚本。安装完成后检查一下技能目录是否真的被写入了ls ~/.codex/skills正常情况下你会在输出里看到superpowers这个目录进去以后能看到SKILL.md以及若干子目录。这一步很重要别跳过因为有不少人安装时报了成功实际却因为路径探测错误把技能装到了别处后面调用的时候自然怎么都不生效。2.3 验证安装结果装完之后怎么确认Codex真的认识这些技能一个很简单的办法新开一个Codex CLI会话直接问它“你现在可用哪些技能”或者更直接一点告诉它“请阅读你的技能列表然后告诉我你准备怎么帮我完成下面的任务”。如果安装正常Codex会明确引用到Superpowers的技能名称并按照技能格式输出内容。另外一个更硬核的验证方式是直接查看AGENTS.md文件内容。安装器会在里面追加一段关于技能入口的说明你可以grep一下grep -i superpowers ~/.codex/AGENTS.md能搜到内容说明Codex会话启动时就能看到这些技能了。搜不到也别慌手动把这行内容追加进去通常就解决了。2.4 版本更新与长期维护Superpowers迭代速度不慢尤其是技能定义这类东西会随着Codex CLI本身的技能机制变化而调整。我的习惯是每隔一两周升一次级npx obra/superpowerslatest install --force加--force会覆盖已有文件但要小心如果你自己往~/.codex/skills里写了自定义技能升级前最好先备份。我踩过一次坑升级时手一抖把自定义技能目录清掉了还好有备份才没白费功夫。所以自定义技能一定要单独放一个目录别和Superpowers混在一起。3. 技能体系与使用流程理解“怎么用”比“用哪个”更重要3.1 核心技能的分类逻辑Superpowers里包含的技能数量不算少而且不同版本的清单会有差异。我从实际使用的角度把它们大致分成三类。第一类叫“侦察类”核心是让Codex先理解现状再动手。比如描述代码库结构、分析某个模块的依赖关系、定位bug的影响范围。这类技能解决的是“瞎改”的问题。没有它们时Codex经常凭猜测改代码有了它们以后它会先花时间把相关文件读一遍再给你一个分析结论。第二类叫“施工类”核心是把开发过程拆成可验证的步骤。比如制定实现计划、按测试驱动方式写功能代码、做代码重构。这类技能解决的是“跳过步骤”的问题。它会让Codex在写代码之前先交一份计划给你确认写完一段代码后自动补上对应测试。第三类叫“质检类”核心是完成后的核对。比如按验收标准做代码审查、检查变更集是否越界、核查依赖是否合理。这类技能解决的是“自我感觉良好”的问题逼着Codex用第三方视角重新审视自己刚写的东西。这三类技能不是孤立的它们合在一起才构成完整的工程循环。如果你只用了其中某一类体验会大打折扣。3.2 一次典型的“规划→开发→审查”循环我实际跑项目时最常用的循环是这样展开的拿到一个需求我先不急着让Codex写代码而是调用规划类技能。Codex会先读项目结构、读关键文件然后输出一份实施方案包括改动涉及的文件、实现顺序、风险点、验收思路。我把这份方案过一遍觉得没问题后再让它进入开发阶段。开发阶段它会按计划逐步实现并且每完成一个子任务就主动跑一遍测试。全部写完后我再调起审查类技能让它以“不加班的老工程师”视角检查自己的产出找出实现和计划之间的偏差。这个流程看起来比直接写代码慢不少但结合我自己的项目经验它反而省时间。因为直接生成代码的快是快在生成那一刻后面调试、返工、跟AI来回解释需求的时间才是真正的大头。Superpowers把大头压住了小头的生成速度慢一点完全可以接受。3.3 SKILL.md里到底写了什么技能之所以能生效靠的是SKILL.md文件。这个文件本身就是一个规范格式的Markdown文档头部有一段元信息声明技能的名字和描述正文则是Codex应该遵循的步骤和行为约束。我翻开默认技能的SKILL.md看过里面写得非常具体比如“在开始实现之前必须先输出一个实现计划计划中必须包含文件路径和测试策略”“如果代码涉及外部依赖先把依赖变化列出来等待用户确认”。这些描述本质上就是把资深工程师的工作习惯翻译成了模型能理解的语言。这也解释了为什么Superpowers不只是一个提示词合集它把每一个技能都做成了有边界、有输入输出、有质量标准的可执行单元。我自己写技能时也参考了这套写法效果确实比随手写个prompt稳定得多后面第5章我会细说。4. 实操从一份含糊需求到一次可交付的改动4.1 任务与规格的写法纸上谈兵没意思我拿一个具体的需求来演示。假设现有项目里有一个订单模块现在要新增功能超过30分钟未支付的订单自动取消同时要发通知给用户。这是一个边界清楚但涉及面不小的小需求适合用来走一遍Superpowers流程。我先在Codex CLI里给出一段相对完整的任务描述大意是“订单模块新增过期自动取消功能超时时间30分钟可配置取消后要发送站内通知需要补测试涉及订单状态、定时任务、通知三个模块。”这段描述不完美但已经包含了核心业务规则和影响范围足够让Codex进入工作流。为什么我强调“先写需求再开动”因为Superpowers的规划技能对输入质量很敏感。输入越含糊规划出来的方案就越发散。哪怕你花两分钟把需求里的业务规则写清楚后面省下来的沟通时间也是十分钟打底。4.2 在Codex CLI里驱动整个流程我进入Codex CLI后第一句指令是“用规划技能为‘订单超时自动取消’这个需求产出一份实施方案重点是确认改动范围和实现顺序。”Codex收到后没有直接写代码而是读订单服务、订单状态枚举、数据库表结构、现有定时任务配置然后给出一份包含六个步骤的实施方案。我看完方案后圈定了一个疑问点方案里提到用Spring的Scheduled来做定时扫描但现有系统里用的是分布式任务调度组件。我直接在会话里指出来Codex修正了方案改为使用已有的调度组件。这一步是Superpowers流程里最有价值的地方——方案先行意味着你的判断可以作用在“图纸”上而不是作用在“已经盖好的歪楼”上。方案确认后我接着让它进入开发阶段并明确要求“按照计划的第二步到第五步实现每完成一个子功能都跑一遍现有测试。”Codex开始逐个文件动手改状态机、加超时查询方法、写通知逻辑每次改动都聚焦在最小范围。其中一个子步骤里它想顺手优化订单查询的索引建设被我用“本次改动不涉及数据库性能调优”这句话拦了回去。全部写完后我调起审查技能审查这个变更。审查结果列出了两条实现和方案不一致的地方一是有个通知场景没做幂等处理二是取消订单的日志级别偏低。我让Codex根据审查意见修复后才算真正结束这个任务。4.3 复盘这套流程到底值不值整个过程下来Codex实际坐在那里写代码的时间不多大量时间花在了读代码、列计划、被纠偏、自查上。如果只看“产出代码的速度”Superpowers肯定不如裸用Codex CLI来得快。但它把一次本可能需要来回返工五轮的开发过程压缩成了一轮有惊无险的闭环。我个人的体会是复杂度越高的任务越值得走这套流程。如果你只是让Codex写一个工具函数那直接生成就好用技能反而是杀鸡用牛刀。但如果任务是跨模块的、涉及状态变更的、需要补测试的那Superpowers带来的稳定性收益就很明显了。5. 定制自己的技能把团队规范固化成AI行为5.1 一个最小可用的SKILL.md如果你想把团队独有的开发规范写进技能里其实不复杂。最基本的做法是在~/.codex/skills下新建一个目录比如叫my-project-rules然后在里面创建一个SKILL.md文件。我用一个简化例子给你看格式--- name: my-project-rules description: 当改动涉及支付模块时必须检查幂等性并在提交前标注影响范围。 --- # 团队编码约束 1. 所有支付相关接口必须保证幂等。 2. 数据库迁移脚本必须放在 migrations/ 目录并在提交信息中引用版本号。 3. 任何对外接口的变更都需要在变更说明中标注“兼容性影响”。Codex会话启动时会读取~/.codex/AGENTS.md而AGENTS.md里会引用技能目录中的技能说明。只要你把技能目录放对位置Codex在处理相关任务时就能看到并遵循这些规则。这个机制本质上就是一个能被模型自动读取的团队规范库。5.2 编写技能时的三条纪律第一技能描述必须说清楚“什么时候用”。description字段不能写“提升代码质量”这种空话要写“当用户要求修改支付流程或增加新支付方式时”模型才能准确判断触发时机。描述写不清楚技能就永远不被调用。第二技能正文里不要堆砌抽象原则。写“代码要整洁”等于没写要写“函数超过80行时必须拆分为多个小函数”这种可验证的规则。模型对可验证规则的执行可靠性远高于对抽象原则的理解能力。第三控制单个技能的信息量。我见过有人把一个技能写成五千字的规范文档结果Codex加载时浪费大量上下文token效果反而不如只写最关键的十条规则。技能是“行为约束器”不是“知识库”不必要的信息删掉就好。5.3 把自定义技能纳入版本管理我自己维护自定义技能时会把这些技能目录放进独立的Git仓库和项目代码分开管理。这样多台机器之间同步方便升级Superpowers时也不会误删。团队场景下这个仓库还可以直接共享让大家本地的Codex行为保持一致。如果你发现某个技能在多个项目里都很管用比如“提交前必须生成CHANGELOG”那把它沉淀到一个独立技能里后面所有项目都能受益。我后来把团队的技术栈规范、发布检查清单都做成了技能现在新同事入职后只要装好Codex和Superpowers本地的AI辅助行为就和大家保持一致了。6. Superpowers在Java项目里的落地姿势6.1 Java技能包解决了什么问题因为搜索热词里有不少“superpowers java”这里单独讲一下Java场景。Java项目有几个典型痛点一是模板代码多二是框架约定强三是项目结构容易越改越乱。Superpowers生态里专门有针对Java的技能扩展包核心目的是把Java项目里的常规操作“技能化”。比如从一个需求出发生成接口骨架、把大聚合根拆成端口与适配器结构、为Spring Boot项目补充规范的测试基线这些工作技能包里都有对应的流程。它不是取代Spring或Maven而是让Codex在Java项目里能遵循一套合理的工程习惯不会随手把Service写成一个五百行的大类。6.2 Java项目里实际怎么配合使用我在Java项目里使用Superpowers时的典型做法是先让Codex用描述类技能梳理现有模块的依赖关系和分层结构再针对新的接口需求做规划规划里明确标注“Controller层只负责参数转换、Service层只负责业务逻辑、仓储层只负责数据访问”。实际执行中Java技能包对测试的要求比通用技能更严格会要求生成完整的单元测试和集成测试而“测试类命名要符合*Test规范、测试数据要使用独立测试库”这类规则也会被写进技能描述里。这些细节单独拿出来说都不复杂但如果没有技能的硬性约束Codex在Java项目里的行为很容易漂移。如果你只在一个Java仓库里工作我建议不要把Java技能包全局启用而是把它放在项目级的~/.codex/skills下或者使用项目内的技能配置方式避免影响其他语言项目的使用体验。7. 常见问题与排查把我踩过的坑直接告诉你7.1 安装类和权限类问题安装Superpowers时最常见的报错是npx执行权限不足典型症状是安装过程提示EACCES: permission denied。这种问题多半是npm全局目录权限没配好不要直接绕道用sudo装正确的方向是检查当前用户的npm全局目录是否可写该修目录权限就修目录权限免得过两天装别的包又踩一遍。另一个经常让人困惑的问题就是“明明装了Superpowers但Codex好像完全不认识它”。我遇到这种问题第一时间检查~/.codex/AGENTS.md有没有包含技能入口再检查~/.codex/skills的文件结构是否完整。这两个环节任何一个断了Codex都感知不到技能存在。7.2 运行行为与上下文问题有人反馈说“Codex倒是读了技能但总是做一半就停下来问我要权限”。这个大多不是技能的问题而是Codex执行技能里的命令脚本时需要确认。Codex CLI对命令执行有权限控制技能里的自动化脚本如果涉及文件写入或外部命令调用都可能触发确认机制。想在长任务里减少打断就在会话开始时明确告诉Codex“按技能流程执行必要时自主运行命令”。还有一类问题是上下文过长。技能目录里的参考资料太多或者AGENTS.md里写了太多内容会导致Codex的上下文被无关细节挤占。我见过一个项目把AGENTS.md写成了百科全书Codex每次对话光加载规范就花掉一大截上下文。给技能瘦身、给AGENTS.md做减法是解决这类问题最直接的手段。7.3 自定义技能没有生效自己的技能建好了目录也对但Codex就是不认这种情况十有八九是frontmatter里的name字段写错了。技能目录名是my-project-rulesname属性也得和它保持一致的风格最好是同一个名字别用中文或带空格的名字Codex识别时容易出现偏差。另外技能正文的开头部分要足够清晰地点明适用场景和动作。Codex不是把技能全文逐字逐句都吃进去的它靠description来判断“这个技能和当前任务相不相关”。如果description写得含糊比如“提供代码质量建议”那你的技能大概率永远不会被触发。我打磨自定义技能时会花最多时间在description上反复斟酌给它写清“在什么前提下、针对什么任务、给出什么动作”效果立竿见影。8. 最后分享一个我在项目里的用法技能体系这种机制最妙的不是一个个技能的拼装而是把“好习惯”从人身上搬到了模型行为里。我现在已经不把它当“Codex增强插件”了而是当团队的代码评审清单来用每个技能等于一个检查点代码交付前过一遍遗漏自然变少。如果你是刚开始接触Superpowers我的建议是先不要贪多挑一个最困扰你的环节比如测试总是写不全或代码越改越烂用对应的技能对准那个环节跑两个迭代之后你自然会感受到“流程”这东西在AI协作里的重量。