最近这一两年AI 编程工具已经成了不少开发者的标配。但用着用着你应该也会发现一个尴尬的问题模型上下文一长就“失忆”同样的任务每次都要把规则重新讲一遍遇到稍微复杂点的需求AI 给出的方案就像“一次性餐具”——用完就扔下次重新生成又是另一个思路。我一度以为这是模型的极限直到我接触到 superpowers才发现问题其实出在“交互方式”上。superpowers 不是一个普通的插件它是一套给 AI 编码助手典型如 Codex CLI使用的“技能增强框架”。你可以把它理解成给 AI 配了一套真正可复用的“工作手册”规划、拆分任务、写代码、自测、迭代每一个环节都有标准的操作流程而不是每次都在一个巨大的 prompt 里碰运气。装上之后AI 的行为会稳定很多输出质量也有了清晰的底线。这篇就基于我自己的实际使用经验从安装到日常用法、再到踩坑记录完整捋一遍 superpowers 的使用指南。如果你正在用 Codex 这类 AI 工具做真实项目又觉得“AI 写的代码不太能放心用”这套东西值得你花半小时试试。1. 先理解 superpowers 在解决什么问题1.1 为什么单单靠“聊天”没法把代码写好直接用 ChatGPT 或 Codex 写代码时最典型的一个痛点就是“没有过程管理”。你让它实现一个功能它立刻跳进实现细节跳过需求澄清、边界条件分析、方案设计直接开始输出代码。遇到小函数还好一旦涉及多个文件、数据库表、接口调用链这种“直接开写”的玩法基本必翻车。另一个痛点是上下文断裂。你上午跟 AI 确认了模块 A 的设计约束下午做模块 B 的时候只要不在同一个会话里它就彻底忘了。即使在同一会话里随着代码文件越贴越多它也常常把早期给出的关键决策淹没在历史里。superpowers 的思路是不依赖模型“临场发挥”而是把整个编码任务拆成一系列标准化的“技能流程”。比如先做需求澄清再做技术方案规划然后子任务拆分最后才进入编码。每个环节都有明确的目标和输出物。技能定义里写清楚了该做什么、不该做什么、如何自我检查这样即使换了会话、换了项目AI 的行为模式依然是稳定的。1.2 它跟普通 prompt 模板、插件市场里的扩展有什么区别有些人可能觉得superpowers 不就是一套精心设计的 prompt 吗我自己刚开始也这么想用完之后发现差异还是挺大的。普通的 prompt 优化本质是“一次性指令优化”。你可以在一个 prompt 里把角色、流程、约束写得很细但问题是执行过程中模型容易偏离指令尤其上下文变长后中间规则会被淹没无法对新任务自动适配每次都要重新组织语言缺乏结构化的“技能文件”管理复用到另一个项目时基本靠复制粘贴。superpowers 把“技能”做成了文件系统中的结构化单元。每个技能有名称、描述、触发条件和操作步骤核心的思维流程被硬编码成了可调用的步骤序列。AI 会先根据任务描述决定调用哪个技能然后严格按照技能内的流程执行。举个例子superpowers 里有一个很常用的技能叫 brainstorming头脑风暴。当你的任务描述不够清晰时它会主动触发AI 会反过来问你问题而不是急着动手。这个“先问清楚再做”的行为如果不靠技能约束仅靠 prompt 大概率是无法稳定复现的。也正是这种“可复现性”让 superpowers 在实际开发中真正好用同样是完成一个支付模块今天做和明天做AI 的思考路径基本一致不会出现昨天用方案 A、今天用方案 B 的混乱情况。1.3 适用场景与适用人群我个人的判断是superpowers 最适合这几类场景需求不明确、需要探索性开发的场景。superpowers 的流程会强制 AI 先澄清需求再做设计减少返工。涉及多文件、多步骤的中大型功能开发。subagents 等技能可以把任务拆给多个子任务协同完成解决单线程上下文瓶颈。需要长期维护、可复用的项目。技能文件和项目规则可以沉淀下来换人换模型都能保持一致。Java/Spring 这类结构性强、约定大于配置的技术栈。因为 superpowers 里的技能可以按项目自定义规则把团队的编码规范直接固化到 AI 的执行流程里。不过我也有个比较实际的提醒如果你只是写点一次性脚本、单文件工具或者你用的模型本身能力较弱superpowers 带来的收益不会特别明显反而会觉得流程繁琐。它更适合“认真做项目”的场景而非“随手写段代码”的场景。2. 安装与环境准备从零到能跑通第一个技能2.1 前置依赖Node.js 版本与 Codex CLIsuperpowers 是基于 Node.js 构建的命令行工具所以在安装之前先确保你的机器上已经具备以下环境Node.js 18 或更高版本我自己用的是 20.x运行很稳定低于 18 某些依赖如modelcontextprotocol/sdk会直接报错Codex CLI 0.44 或更高版本superpowers 通过 codex 的 MCP 机制接入老版本没有对应的能力一个好用的终端。Windows 用户建议用 PowerShell 7 或 Windows Terminal避免 cmd 的编码问题检查环境可以快速跑两条命令node -v codex --version如果codex还没装先装一下npm install -g openai/codex安装完成后可以用codex --version验证。这一步如果卡住多半是 npm 源的问题可以临时切到国内镜像源再装npm install -g openai/codex --registryhttps://registry.npmmirror.com2.2 安装 superpowers 的两种方式官方提供了两种安装方式我分别说一下我的体验。方式一npm 全局安装npm install -g superpowers这是最直接的方式装完后终端里就有superpowers命令了。不过要注意如果你的 Node 版本偏老这里很容易在编译原生模块时失败报错信息通常是node-gyp相关。解决办法是先把 Node 升到 18。方式二使用自动安装脚本curl -sSL https://superpowers.dev/install.sh | bash这个脚本会帮你检查环境、安装依赖并自动把 MCP 配置写入 Codex 的配置文件。我推荐第一次使用的人走这种方式省心很多。装完之后确认一下版本superpowers --version2.3 初始化项目让 Codex 识别到技能全局装好之后还需要进入你的项目目录做一次初始化。这个动作会创建一个.superpowers目录里面存放项目级别的技能配置和自定义规则。cd your-project superpowers init初始化完成之后我建议你观察一下生成的目录结构.superpowers/ skills/ project-rules/ config.json其中skills目录用来放项目自定义技能project-rules目录可以放项目级的规范说明。superpowers 自带的技能文件其实在全局安装目录里但项目目录允许你覆盖和扩展。这一步做完启动 Codex CLI 时它会自动加载.superpowers下的配置。你可以先跑一个简单的任务验证是否生效codex 调研一下当前目录的代码结构用中文输出报告如果 superpowers 正常工作你会看到 AI 先调用相关技能再开始分析整个交互过程明显比之前“有条理”得多。2.4 关于 Java 环境的特别说明搜索 superpowers 相关热词时“superpowers java”上了热搜看来用 Java 的朋友不少。这里单独说明一下 Java 项目使用 superpowers 的几个注意点确保JAVA_HOME环境变量正确设置并且 JDK 版本与项目要求一致。superpowers 的技能执行过程中可能需要调用mvn或gradle路径不对会导致构建失败。项目根目录的pom.xml或build.gradle建议放在 AI 最容易看到的位置必要时可以在.superpowers/project-rules/里写一条规则明确告诉 AI 构建命令是什么。Java 项目的编译输出目录target或build/classes建议加入.gitignore同时提醒 AI 不要分析生成的字节码文件。我实际在 Spring Boot 项目里用了一周发现只要把构建命令写清楚superpowers 的编码质量明显比裸 Codex 要高尤其在涉及多模块依赖时它会更主动地先梳理模块关系。3. 核心技能拆解superpowers 到底内置了哪些“能力”3.1 常用技能一览superpowers 内置了一套相当丰富的技能库我把日常用到的核心技能整理成了一张表方便大家对照参考。技能名称触发场景核心作用brainstorming需求模糊、方案未定通过多轮追问澄清需求输出问题清单和初步思路planning需求已明确需要设计方案拆解功能模块评估技术选型和风险生成实施计划subagents任务复杂、上下文过长把任务拆分给多个子代理并行处理最后汇总结果code-review代码已完成需要检查从可维护性、安全性、性能等维度审查代码并给出修改建议writing-notes需要沉淀文档将项目决策、经验、架构信息整理成可检索的文档debugging出现异常需要定位问题引导 AI 系统化排查而不是盲目猜测修改这六个技能里我最常用的是brainstorming和planning。以前直接让 AI“帮我写一个用户注册接口”它上来就给你一堆代码但没问清楚你用的是 Spring MVC 还是 WebFlux、是否需要验证码、用户表怎么设计。现在它会先触发 brainstorming反问我几个关键问题。等需求对齐了再进入 planning把接口定义、数据库变更、异常处理都规划好最后才编码。3.2 brainstorming 技能把模糊需求转换成明确问题这个技能的核心价值在于它把“提问”变成了一种标准动作。我举个例子你给 Codex 下达的任务是帮我给项目加一个限流功能没有技能约束时AI 可能会直接写一个拦截器或者 Filter 实现限流但具体限流算法、粒度、超出之后的响应方式全都靠猜。而触发 brainstorming 之后AI 会按流程先抛出几个问题限流是针对单个用户、单个 IP还是整个接口是使用固定窗口、滑动窗口还是令牌桶算法限流后是返回 429 错误还是排队等待是否需要支持分布式限流比如 Redis看到区别了吗同样是实现功能前者是“猜”后者是“确认”。对于真实项目来说后者的价值不言而喻。从我的经验看哪怕你心里的答案已经很清楚走一遍这个流程也值得因为 AI 问出的问题常常能帮你发现自己没想到的边界情况。3.3 planning 技能把大目标拆成可执行的子任务当需求澄清完superpowers 就会进入 planning 阶段。这个技能的主要输出是一份结构化的实施计划包括功能模块拆分把整个需求拆成若干独立的功能点技术方案选型比如用 Redis 还是本地缓存、用异步还是同步实施顺序编排标明哪些任务可以并行哪些必须串行风险点标注提前指出可能的技术难点和兼容性问题我一般会要求 AI 把计划以 Markdown 文件形式输出到项目目录的.superpowers/plans/下这样后续执行时可以直接引用。如果中途 Codex 会话断了重新启动后让它读取这个计划文件它就能无缝接续工作。这个习惯帮我避免了很多次“AI 忘了之前讨论结果”的情况。3.4 subagents 技能多线程并行解决复杂任务这个技能是我认为 superpowers 最“超能力”的一个特色。它的核心思想是把一个复杂任务拆分成多个子任务每个子任务由独立的子代理执行最后再汇总。因为每个子代理拥有独立的上下文窗口互不干扰所以整体能处理的信息量远超单线程方式。举个实际例子有一次我需要同时修改一个 Spring Boot 项目的 Controller、Service、Repository 三层代码。如果只用一个对话窗口AI 需要同时记住三层代码的上下文很容易混乱。我让 superpowers 用 subagents 技能把三个层的修改分别分配给三个子代理并行处理每个代理只关注自己那一层最后再统一检查和整合。整体质量明显比单线程输出稳定。不过这里有个小提醒subagents 的并行执行依赖模型本身的能力如果你的 Codex 还接了其他工具比如编译器输出、文件读写子代理之间共享文件状态可能会产生冲突。我通常会指定每个子代理只负责独立的文件避免互相覆盖。4. 实操演示用 superpowers 完成一个 Java 小功能4.1 任务目标与初始状态为了让大家有更直观的体感我拿一个具体的场景演示一遍完整流程。假设当前项目是一个基于 Spring Boot 3.x 的订单服务现在需求是给订单模块增加一个“取消订单”接口要求校验订单状态只有待支付状态才能取消并且取消后释放库存这个需求不算太复杂但涉及 Controller、Service、库存联动的几层修改非常适合演示 superpowers 的整体工作流。项目环境是 JDK 17、Maven、Spring Boot 3.2。4.2 第一步让 AI 先做需求澄清我直接在项目根目录启动 Codex CLI输入superpowers 帮我实现取消订单功能具体需求校验订单状态只有待支付状态才能取消取消后释放库存注意这里我在指令里显式提到了superpowers作用是提示模型优先选择对应的技能流程。如果你没有显式指定superpowers 也会根据任务描述自动匹配技能但显式触发更可控。Codex 收到命令后按照 brainstorming 技能开始向我提问。它问的几个问题是取消操作是物理删除订单还是将订单状态更新为“已取消”释放库存的具体含义是恢复商品的可售库存还是增加一个库存变更流水接口的入参是订单号还是订单项 ID如果订单已经处于“已发货”状态调用这个接口应该返回什么错误码这几个问题很关键尤其是“释放库存”这一点如果没有确认清楚AI 很可能只会更新订单状态而忘了库存操作。我逐一回答后任务进入 planning 阶段。4.3 第二步生成实施计划planning 技能输出的实施计划大致是这样的变更文件清单 1. OrderController.java - 新增 cancelOrder 接口 2. OrderService.java - 新增 cancelOrder 业务方法 3. OrderStatusEnum.java - 确认待支付状态定义 4. InventoryService.java - 新增 releaseStock 方法 5. OrderCancelRequest.java - 新增请求参数 DTO如存在则复用 实施顺序 1. 先定义接口 DTO 与状态枚举检查 2. 实现 Service 层取消逻辑 3. 调用 InventoryService 释放库存 4. 在 Controller 暴露接口 5. 补充单元测试这个计划文件会被保存到.superpowers/plans/20250115-order-cancel-plan.md。我确认计划没问题后指示 AI 开始执行。4.4 第三步逐文件编码与自测接下来 AI 按计划逐个文件编码。这里让我比较惊喜的是每一步修改完成后superpowers 会主动要求运行编译和测试来验证而不是一口气把所有代码写完再交付。以下是 Service 层核心代码的简化示例Service public class OrderService { private final OrderRepository orderRepository; private final InventoryService inventoryService; public OrderService(OrderRepository orderRepository, InventoryService inventoryService) { this.orderRepository orderRepository; this.inventoryService inventoryService; } public void cancelOrder(String orderId) { Order order orderRepository.findById(orderId) .orElseThrow(() - new OrderNotFoundException(orderId)); if (order.getStatus() ! OrderStatus.PENDING_PAYMENT) { throw new IllegalOrderStateException(只有待支付状态的订单才能取消); } order.setStatus(OrderStatus.CANCELLED); orderRepository.save(order); // 释放库存 inventoryService.releaseStock(order.getProductId(), order.getQuantity()); } }注意这里 AI 在实现取消逻辑后又主动在技能引导下做了一次自测检查边界条件订单不存在时抛什么异常、状态不匹配时是否会误操作库存、库存释放失败时订单状态是否会产生不一致。这个过程很接近一个真正开发者的自查节奏。4.5 第四步代码审查与收尾所有代码完成后我触发了一次code-review技能。AI 从几个维度审查了变更事务一致性库存释放和订单状态更新是否应该在同一个事务中。它建议在cancelOrder上增加Transactional避免库存扣了但订单没更新成功。幂等性重复调用取消接口是否会产生副作用。参数校验orderId为空时是否会抛出无意义的异常。这些都算是一针见血的问题。我在实际项目里确实遇到过类似的事务问题——AI 在编码阶段不见得能全部考虑到但配合 code-review 技能做一轮“自我找茬”质量明显上了一个台阶。最终AI 把完整的变更摘要和测试结果整理成一份简短报告整个流程到此结束。耗时大约十分钟比我手动检查和改代码快了很多。5. 常见问题与排查技巧实录5.1 安装或初始化时报错我遇到的第一类问题基本都集中在环境层面。这里把典型的报错和处理方案整理一下方便大家直接对表操作。报错内容可能原因解决方案Node.js version must be 18本机 Node 版本过低用nvm install 18升级后再重试Cannot find module modelcontextprotocol/sdk依赖安装不完整删除node_modules后重新npm installEACCES: permission denied权限不足不要用sudo直接装全局包改用 nvm 管理 NodeMCP server connection failedCodex 配置未生效检查~/.codex/config.toml中的 MCP server 配置关于config.toml我需要强调一下它的结构。superpowers 会在初始化时自动写入以下配置如果你手动修改注意保持格式一致[mcp.servers.superpowers] command superpowers args [mcp]如果你的 codex 配置文件是 JSON 格式则需要写成{ mcp: { servers: { superpowers: { command: superpowers, args: [mcp] } } } }我自己就曾经因为把配置文件改错了语法导致 codex 一直没有加载上技能。排查这类问题有个笨办法先断开所有自定义配置只保留默认配置确定能跑通再逐步加回。5.2 技能不触发或行为表现不稳定有时候你已经完成了安装但 AI 的执行方式跟之前没装 superpowers 时没什么区别。我从自己的经验看通常有三个原因原因一codex 版本太低。如果你装的是旧版 codex可能根本不支持 MCP 协议superpowers 自然不会被调用。用codex --version确认版本号老版本就直接升级。原因二项目目录没有初始化。很多人只在全局装了 superpowers忘了在自己的项目目录执行superpowers init。没有.superpowers目录技能就不会被加载。进到项目根目录重新初始化即可。原因三任务描述太“明确”了。superpowers 的某些技能比如 brainstorming需要模型判断“用户意图是否清晰”。如果你在任务里把每一步都写得死死的模型觉得没有歧义自然就不会触发澄清流程。这就好比你跟同事交代任务时把每个细节都说完了对方当然不会再问你问题。想强制触发某个技能可以在指令里显式写上技能名比如superpowers 用 brainstorming 技能分析一下当前需求输出需要澄清的问题我实测下来显式触发比自动触发的可靠性高得多建议在关键任务上总是显式指定。5.3 Java 项目中的常见坑在 Java 项目里用 superpowers有几个坑值得单独记录一下JAVA_HOME 未设置。superpowers 某些技能执行时会尝试调用 Maven 或 Gradle如果 JVM 环境变量没配好会报Unable to locate a Java Runtime。排查时先跑echo $JAVA_HOME mvn -version确认两处输出一致。如果你用 IDE 自带的 JDK终端里的mvn很可能找不到这种情况建议在~/.zshrc或~/.bashrc里显式export JAVA_HOME...。Lombok 依赖导致的源代码分析偏差。AI 在分析 Java 代码时如果遇到 Lombok 注解生成的 getter/setter它可能误以为字段没有访问接口进而提出“该字段缺少 getter/setter”这类无意义的修改建议。解决办法是在.superpowers/project-rules/下加一条规则项目使用 Lombok所有实体类字段默认具备 getter/setter。这样 AI 就不用去代码里猜了。Maven 私有仓库依赖拉取失败。如果你的项目使用了私有 Maven 仓库superpowers 执行构建时可能因为本地settings.xml没配置镜像而失败。我建议把仓库地址写进项目级的README或.superpowers/project-rules/让 AI 在需要构建时参考。5.4 上下文过长或会话中断怎么办这个应该是使用 AI 编程工具最头疼的问题之一。superpowers 并不能让上下文无限大但它提供了相对优雅的解决方案把中间产物持久化到文件而不是全部塞进对话。我的标准操作是每个阶段结束时让 AI 把阶段结论写入.superpowers/plans/目录如果会话中断新会话中直接告诉 AI“读取.superpowers/plans/xxx.md基于这个计划继续执行”每周做一次项目知识归档把重要的架构决策和编码规范沉淀到.superpowers/project-rules/。这个方法表面上只是“多写了几份文件”实际效果却相当于给 AI 装了一个外部记忆盘。模型本身的上下文限制没有变但它不再需要从零回忆项目背景所有关键信息都在文件里。6. 把 superpowers 融入日常开发我的配置习惯与效费比评估6.1 项目级规则的写法与示例superpowers 的自定义能力很大程度体现在project-rules上。我通常在项目初始化后做的第一件事就是创建一份项目规则文件例如.superpowers/project-rules/backend-rules.md# 项目规则 - 本项目使用 Spring Boot 3.xJava 17Maven - 实体类统一使用 Lombok - Controller 层只做参数接收和简单校验不写业务逻辑 - Service 层必须使用 Transactional 声明事务边界 - 所有接口统一返回 ResultT 包装对象 - 新增功能必须配套单元测试测试类命名以 Test 结尾 - 涉及数据库变更时需要补充对应 SQL 脚本写好之后superpowers 在执行任务时会自动加载这些规则并约束编码行为。这比你每次都在对话中重复强调“记得加事务”“记得写测试”要可靠得多。规则文件本身也是 git 仓库的一部分团队成员都能复用相当于把团队的编码规范直接“注入”到了 AI 的执行流程里。关于规则颗粒度我的经验是不要写太多抽象原则比如“代码要优雅”“要做好异常处理”这种话没意义AI 无法量化执行。要写就写可检查的硬性约束比如“所有日期类型统一使用java.time.LocalDateTime不使用java.util.Date”“接口入参必须使用 DTO 类禁止直接接收 Map”“RESTful 接口路径统一以/api开头”规则越具体AI 执行越不靠猜。我现在的项目规则文件大概有二十来条每条都是针对项目实际踩过的坑总结出来的效果比一开始写一堆泛泛而谈的“原则”好得多。6.2 在单文件脚本、小工具等轻量场景下要不要用前面我提到 superpowers 更适合正经项目但在某些轻量场景里它其实也能带来意外的好处。比如你需要写一个一次性数据处理脚本。这种任务简单不需要走 brainstorming、planning 那一整套流程。但 superpowers 的subagents技能也许能把任务拆成“数据读取”“清洗转换”“结果输出”三个子任务并行处理。不太复杂的任务也可以让它直接产出代码只要你在指令里表达得足够清晰AI 会判断是否需要触发技能流程。我个人的做法是在轻量场景下尽量给足上下文不需要用技能流程但如果是给公司项目写代码哪怕是很小的改动我也会显式控制它的流程至少把planning和code-review这两个环节走完。这不是形式主义而是为了确保 AI 输出符合项目约束不产生后续债务。6.3 一周体验后的效费比评估用了大概一周之后我最大的感受是superpowers 的核心价值不是让 AI 变得更“聪明”而是让 AI 变得“更稳”。效率上前几次使用会感觉变慢了因为多了澄清、规划、审查这些步骤。但放到整个项目周期看因为返工变少了最后的总时间是下降的。我实测过以前裸用 Codex 开发一个多模块功能可能要反复对话修修补补四五轮现在用 superpowers基本一两轮就能产出接近可合并的代码。质量上最明显的变化是“AI 开始主动确认需求了”。以前它像一个急于表现的实习生现在更像一个愿意先把问题想清楚再动手的资深同事。对于团队协作来说这种变化比单次生成代码的质量提升更宝贵。当然它也有适用边界。如果你用的是能力偏弱的模型或者任务本身特别简单superpowers 的流程化反而会带来不必要的开销。你需要根据自己的使用频率和项目复杂度灵活决定用多重的流程。6.4 创作新技能的初步尝试与边界最后聊一聊自定义技能。superpowers 允许你在.superpowers/skills/下创建自己的技能文件格式是 Markdown核心包含技能名称、描述、触发条件、执行步骤。我尝试创建一个简单的“代码提交信息生成”技能内容大致是# commit-message-generator 描述根据 git diff 生成符合 Conventional Commits 规范的提交信息 触发条件用户请求生成 commit message或提交代码前要求整理提交信息 执行步骤 1. 运行 git diff --cached 获取暂存区变更 2. 分类变更类型feat/fix/refactor/docs/style/test 3. 输出单行 subject不超过 50 字符使用祈使语气 4. 如有必要输出 body 说明变更动机把文件放到.superpowers/skills/commit-message-generator.md之后重新启动 codex就能通过superpowers调用这个技能了。整个过程没有写一行代码改的只是一个 Markdown 文件。这种“靠文档定义行为”的设计让我有一种很奇妙的感觉你不需要理解模型内部机制也不需要写复杂的程序只需要把正确的操作流程描述清楚AI 就会按照这个流程执行。技能文件就是 AI 的程序而你就是开发者。我不建议一上来就做特别复杂的自定义技能。先把内置技能用好理解一个技能文件的结构和触发逻辑再慢慢根据自己项目的需要添加规则。等你熟练了你会发现这其实是在给自己训练一个“懂你项目”的数字员工它的行为模式完全由你来定义。写在最后现在值得动手试试把 superpowers 接入我日常开发流程大概一周最大的变化不是代码生成速度变快了而是我对 AI 交付的东西“敢放心用了”。以前 Codex 写完代码我总要检查一遍有没有隐藏的坑现在它自己会先做一轮需求澄清、一轮规划、一轮自测、一轮代码审查剩下的问题已经少了很多。如果你跟我一样既想让 AI 提效又不想被它的不稳定输出拖累我建议你今晚就动手装一个试试。先做点小任务感受流程差异再逐步把它引入你的主力项目。流程化的确会多一点仪式感但配合项目规则去用它会慢慢从一个“聊天机器人”变成真正能打配合的编码搭子。
