1. 一个不够懂规矩的 Codex以及 Superpowers 想解决的问题最近总有人问我你天天吹 AI 编程怎么感觉你写代码也没快多少说实话我一开始用 Codex 的时候确实有这种感觉。它确实能写但写出来的东西总差点意思——我让它按项目规范改一行代码它给我把整个文件重写了我让它参考某个接口的既有写法它装没看见最离谱的是它可以完美通过编译但完全不符合我们团队代码评审的规矩。如果你也在用 Codex CLI 或者类似的 AI 编程助手并且觉得它能力是有但就是不听指挥那这大概率不是你提示词写得不够好而是你缺了一层约束和上下文。我今天想聊的 Superpowers就是专门解决这个问题的。Superpowers 是什么用一句话说它是一套围绕 Codex 命令行工具构建的超能力扩展包或者说是一组配置、模板和自动化脚本的集合。它把 AI 编程助手的调用方式从你问一句它答一句变成了一套有规范、有模板、有流程的工程体系。这个项目最初来自开源社区核心理念也很朴素既然 AI 可以自己写代码那我能不能把整个团队的技术规范、代码风格、架构约束全部塞进去让它从一开始就别跑偏这套工具特别适合三类人一是被 AI 助手自作主张折磨的日常使用者二是想把 AI 代码生成纳入团队工作流、但又不想靠人工一条条审查规范的技术负责人三是喜欢折腾 CLI 工具、习惯把一切操作都脚本化的开发者。我属于第一类和第三类的混合体所以这篇文章我会从实际使用角度出发把安装、配置、核心功能、在 Java 项目里的落地实践以及我踩过的一些坑都聊一遍。我能很坦白地说Superpowers 不是那种装上就能哇一声的工具它更像是给 AI 助手戴上的一套行为准则。但一旦你把这个准则调教好后面省的心力是几何级别的。2. 安装与初始化我的实测路径和最容易卡住的地方先说结论Superpowers 的安装并不复杂但网上的教程大多写得含糊尤其是初始化那一步很多人卡在装完了不知道下一步该干嘛的状态里。2.1 装之前先确认环境如果你已经装好了 Node.js 和 Codex CLI那基本就具备了安装 Superpowers 的前置条件。我这边实测的版本组合是 Node.js 18 和最新版 Codex CLI。这里有一个容易被忽略的点Superpowers 本身是一个命令行增强包它的运行依赖于 Codex 的插件机制所以 Codex 版本不能太老建议提前跑一下codex --version确认版本号比较新。安装 Superpowers 本身最常规的方式是直接从 GitHub 仓库克隆。我记得官方的说明里给的就是 clone 到本地目录然后运行它自带的安装脚本。以常见流程为例大致是这样git clone https://github.com/superpowers-ai/superpowers.git cd superpowers ./setup.sh在这个过程里脚本会自动检测你的 Codex 配置目录并把需要的配置文件和插件目录链接过去。实测下来这一步一般不会报错真正的问题出在下一步脚本跑完之后你得知道它把东西装到哪里了、改了什么文件。2.2 初始化那一步认真读输出安装完成之后脚本通常会提示你运行一个初始化命令。很多人习惯性跳过或者直接开个新终端就去问了然后发现 Codex 的行为完全没有变化于是回头骂工具不好用。以实际经验来说初始化做的事情大致是在 Codex 的配置目录下生成SUPERPOWERS.md或者类似的引导文件并注册一批内置的模板和技能。我建议你在初始化之后先不要急着写业务代码而是先打开 Codex 的配置文件看一眼里面多了哪些项。我这里的情况是装完之后 Codex 的启动行为会发生变化——它会在每次会话开始时多读入一批上下文文件。这其实是 Superpowers 的核心机制之一通过约定目录和文件名让 AI 在动手之前就能看到项目规范。目录结构和文件内容的约定在不同版本的小细节上会有差别但大方向是统一的所以官网文档永远是第一参考。2.3 用一个简单项目做冒烟测试环境装好之后我强烈建议你先新建一个空目录放一个最简单的文件比如只有两个方法的 Java 类或者一个 Python 脚本然后让 Codex 帮你加一个功能。注意观察它有没有做这几件事有没有先读你的规范文件、有没有沿用你现有的命名风格、有没有在动手前给出方案说明。如果这三件事它都做了说明 Superpowers 已经生效了。如果没有多半是初始化步骤出了问题或者配置文件没有被正确加载。这里有个排查技巧直接在会话里问 Codex 当前加载了哪些上下文文件它一般会老实告诉你。我在第一次跑通这个流程的时候最直观的感受是它突然变得像团队里的老员工了动手之前会先确认需求写出来的代码风格也跟项目保持一致。这就是 Superpowers 的核心价值所在。3. 三类核心资产模板、技能与工作坊的实际用法Superpowers 真正让我觉得这东西有点东西的是它的三类核心资产模板templates、技能skills、工作坊workflows。这三样东西如果玩明白了等于给你的 AI 助手赋予了三种不同层次的约束能力。3.1 模板给 AI 立规矩的合同模板模板的作用是把一类重复任务的输出格式固定下来。比如你团队要求所有的数据库访问层必须包含统一的日志输出、异常处理、事务边界那就可以把这些要求写成一个模板文件。之后每次让 Codex 写新的 Repository 类它就会自动套用你的模板。用模板和不用的区别有点像你让一个实习生自由发挥写周报和给他一份上周的周报当格式参考之间的区别。自由发挥的时候他写出来的东西不可控有了模板他至少会在格式和结构上对齐你的预期。在 Superpowers 里模板一般放在约定的模板目录下文件名就是触发词。比如你有一个repository.md的模板那你在提示词里提到按照 repository 模板创建 UserRepositoryCodex 就能找到并套用对应的结构。3.2 技能把你擅长的做法教给 AI技能比模板更进一步。模板约束的是写出来的东西长什么样技能约束的是做这件事的过程中应该遵守什么步骤和原则。举个例子我自己维护了一个处理遗留系统代码重构的技能。这个技能文件里写的是第一步先定位现有调用方第二步梳理行为变化第三步写兼容层第四步才动原方法。以前我直接让 Codex 帮我重构一个方法它会很干脆地改掉方法签名然后留下一堆编译错误。现在有了技能约束它会先问我调用方有哪些、要不要保持向后兼容整个过程变得谨慎得多。技能文件的编写不需要什么特殊格式本质上就是一份 Markdown 文档。难的不是格式而是你要把你脑子里默认的那些做事原则明确地写出来。这事听起来简单做起来其实挺考验人的因为很多经验你已经内化了根本不觉得那是需要交代的事情。3.3 工作坊多步骤任务的流程编排工作坊是三者中层级最高、也最复杂的。它解决的场景是一个任务往往不是一步到位的而是需要多个步骤串行执行并且步骤之间可能有依赖关系。我比较常用的一个工作坊场景是从需求到实现。它大概的流程是先让 AI 根据需求文档生成技术方案然后确认方案、拆解任务清单、逐个实现、最后跑测试并总结变更影响范围。整个过程里AI 不会直接跳到写代码那一步而是会一步步来每次只做当前环节的事。如果你用过 CI/CD 流水线理解工作坊就不难。它就是给 AI 的思维过程加了一条流水线让大任务的执行从野路子变成按工位走流程。3.4 这类资产为什么有效说说底层逻辑我自己的理解是这样大模型的能力边界其实很宽但它默认的行为模式是最通用的模式而不是你的模式。通用模式下写出来的代码当然能跑但未必符合你的团队要求。Superpowers 的模板、技能和工作坊本质上是在模型推理之前用工程化的手段注入你期望的行为约束把通用模式扳到定制模式。这个思路和传统的低代码平台或者代码生成器有本质区别。代码生成器是把你限制死你只能在它给的框架里选Superpowers 则是把约束和自由度都交给文本表达你要多严它可以多严你要多灵活它也可以多灵活。这也是为什么它值得花时间去调教——因为你投入的每一份规范都会被 AI 之后无数次会话重复利用。4. Java 项目怎么用出效果规范注入与任务编排Java 应该是很多人实际工作中接触最多的语言了所以我把 Superpowers 在 Java 项目里的用法单独拎出来讲一讲。毕竟Java 项目通常有更强的规范诉求分层、命名、异常处理、框架约束处处都是可配置的行为边界。4.1 把项目约束写进规范文件我的做法是在项目根目录建一个AGENTS.md或者类似的规范说明文件里面写明这个项目的基本规则。比如使用 Spring Boot 3.x、Controller 层只做参数校验和路由转发、Service 层处理业务逻辑并且事务边界必须在 Service 方法上、Repository 层不允许直接暴露 JPA 实体给上层等等。这些内容以前是写给人看的文档放上去就没然后了。现在有了 Superpowers这些规范文件就成了 AI 的入职培训手册。每次 Codex 进入会话都会优先读它于是它在写新代码时就会主动遵守这些约束。我最近让它新增一个订单查询接口它自己就知道要拆成 Controller、Service、Repository 三层而且命名完全符合项目里的既有风格。4.2 让 AI 沿袭项目既有代码风格Java 项目里有个很头疼的事同一个项目里不同时期写的代码风格可能完全不同——有人用Autowired有人用构造器注入有人返回值直接给实体有人坚持用 DTO。以前让 AI 写代码它倾向用最常见的方式而这往往不是你项目里的方式。解决办法是把风格说明直接写进规范文件。比如我在规范里明确写了依赖注入一律使用构造器方式禁止字段注入之后 AI 写出来的新代码就再没出现过Autowired字段注入。还有一个很实用的技巧如果项目里有几个值得参考的模范类把它们的路径写在规范文件里让 AI 在动手前主动阅读那几个类模仿其中的写法。实测下来这个方法比在提示词里干巴巴说参考现有代码风格管用得多。4.3 用工作坊编排一次完整的 Java 功能开发我说一个最近真实跑过的工作坊流程任务是为一个订单模块加批量导出功能。如果直接让 Codex 写它可能一分钟内就给我丢出一堆代码但质量参差不齐。用工作坊编排后的流程大致是这样的第一步先让它阅读需求描述和现有订单模块的代码结构输出一份技术方案包括需要改动的文件清单和新增的类第二步对方案进行评审它可以自问自答这个方案有没有考虑大数据量下的内存问题第三步确认无误后再开始写代码写完一个文件汇报一次变更点第四步自动检查编译和测试最后生成一段简短的设计说明方便我提交代码评审。这套流程跑完最大的感受是它不像一个只写代码的生成器更像一个能自己规划、自检、交活的开发。代码质量和可评审性都提升了一个档次我能把精力放在真正需要人判断的地方。4.4 性能与数据库约束的注入Java 后端几乎绕不开数据库问题。我踩过一个真实例子有一回我让 AI 写一个报表查询接口它美滋滋地给我写了一堆循环查数据库的代码——功能没错但那个性能放到生产环境就是事故。后来我在规范文件里加了两条禁止在循环内查询数据库、涉及多条数据时必须用批量查询或者 join。从那以后这样的低级性能问题就基本绝迹了。这给我的启发是AI 不是你肚子里的蛔虫你不告诉它什么是不能做的它就只能按通用思维给你正确但平庸的答案。把团队积累的代码评审结论整理成规范注入给 Superpowers等于给 AI 装了团队的避坑记忆这比事后一条条评审省力太多。5. 我踩过的几个坑和现在固定下来的工作流工具再好用也有坑尤其是一个还在快速迭代中的开源项目。我用了这段时间遇到过几个比较有代表性的问题这里逐个说一下也顺便聊聊我现在固定下来的一套使用流程。5.1 坑一版本迭代导致配置结构变动Superpowers 的版本更新不算慢我遇到过升级之后之前可用的技能突然消失的情况。排查下来发现是配置文件里路径引用变了旧路径已经不存在了。这个坑的教训是升级后不要在旧会话里继续干活先花五分钟确认配置加载正常必要时重新跑一下初始化命令。5.2 坑二规范文件过度膨胀我一开始很兴奋把团队所有的编码规范全怼进一个文件里写了两千多行。结果 AI 的表现反而不稳定了有时候会忽略一些关键约束。后来我才意识到上下文能力是有限度的规范文件内容太多AI 的注意力会被稀释。解决办法是把规范拆分成多个主题文件按需加载——比如数据库规范单独一个文件API 设计规范单独一个文件项目结构规范单独一个文件。5.3 坑三技能内容写得过于抽象写技能的时候容易犯一个毛病用形容词描述期望行为比如保持代码优雅注意性能。AI 对这类模糊表述的理解完全看运气。正确的写法是把抽象要求翻译成可检查的具体动作比如避免在循环中访问数据库就比注意性能有用得多。这一点我建议所有使用 Superpowers 的人都认真反思一下自己写的技能文件——如果你写的内容自己都检查不了那 AI 大概率也做不到。5.4 我现在的工作流踩完这些坑我现在的日常使用流程大致是这样的新项目起步时先写好项目规范文件明确技术栈、分层约定、命名风格、禁用项接入 Superpowers 后跑一次初始化然后用一个小需求验证行为是否符合预期日常开发中简单的任务直接对话完成复杂的任务交给工作坊分步执行每次代码评审发现有共性问题顺手补进技能文件让 AI 下次自己注意每隔一段时间整理技能库把过时的、重复的内容删掉保持每个文件短小精悍。这套流程跑下来最大的变化不是说 AI 写的代码完美到不用改而是它犯的低级错误明显变少了代码风格和项目规范的贴合度高了很多评审的压力小了不少。对我个人来说Superpowers 带来的不是自动写代码的爽感而是AI 终于听劝的踏实感。如果你现在也在用 Codex 或者其他命令行形态的 AI 编程工具并且对每次都要把规范和上下文反复粘贴这件事感到疲倦我真心建议你花一个下午试试 Superpowers。别指望一次装好就万事大吉第一天的调教是会花点时间但之后的收益是持续的——这大概是目前把 AI 变成自己团队的人最直接有效的一条路径。
