说真的第一次看到 superpowers 这个名字的时候我第一反应是又一个人工智能营销噱头。但后来发现它跟 Codex 搭配着玩完全是另一回事。作为一个每天跟各种编程助手打交道的人我最大的感受是这玩意儿解决的压根不是有没有 AI 帮忙写代码的问题而是AI 怎么老是不按我的规矩来的问题。你辛辛苦苦在提示词里写一堆规范换个项目、换个会话它全给你忘了。superpowers 的思路很直接——它把那些可复用的编码规范、开发流程、检查清单封装成一个个技能包让 AI 在每次对话里都能稳定地调用。那些还在重复粘贴提示词的人真该看看这个东西。这篇文章我把它的核心逻辑、安装方式、实战玩法以及踩坑记录都写清楚适合已经在用或准备用 Codex 这类终端编程助手的人参考。无论你是个人开发者还是小团队技术负责人搞清楚这一套玩法能让 AI 产出的代码质量稳定上一个台阶。1. 为什么需要 superpowers从临时提示词到持久技能库1.1 Codex 这类编程助手的最大痛点先讲个场景。你用 Codex 在终端里跑一个 Java 项目提示词里写了遵循阿里巴巴规约方法不要超过 30 行异常要统一包装第一次它做得还行。但等到你切换目录、新开会话或者让同事来操作它又把规矩全忘了开始自由发挥。说白了传统提示词是一次性的它活在对话里对话结束就没了。我自己的项目里踩过很多次这种坑。团队定了 Git 提交信息格式AI 生成的提交记录花式放飞定了接口返回结构它给你冒出各种风格迥异的 JSON 字段。这些问题不是模型不够聪明而是你没有一种机制把这些约定变成 AI 每次都绕不开的上下文。superpowers 就是奔着这个痛点来的。它的核心思路是把技能skill定义成 Markdown 文件安装到 Codex CLI 的配置目录里之后每次 Codex 启动会话时这些技能文件会作为上下文的一部分被自动加载。换句话说提示词从一次性输入变成了常驻配置。这里要说清楚一点它对模型本身没有任何改造也不是什么新的编程语言。它就是一个很巧妙的工程化方案借用了文件系统的天然持久性把怎么让 AI 干活这件事沉淀成了可复用、可分发、可版本管理的东西。1.2 核心设计技能包就是一份给 AI 看的员工手册superpowers 最核心的概念叫 skill pack翻译成大白话就是技能包。一个技能包通常是一个目录里面放着一个或多个 Markdown 文件。每个文件的头部有一段 YAML frontmatter里面写清楚了技能的元信息name技能名称比如java-service-error-handlingdescription什么时候应该使用这个技能写清楚场景when_to_use触发条件这直接决定了 Codex 会不会自动调用它version版本号方便团队追踪迭代正文部分则是真正的干货任务拆解步骤、代码规范、检查清单、示例模板。你可以把它理解为给 AI 看的员工手册——不是让它自由发挥而是告诉它接到某类任务时必须按这套流程和标准来执行。拿生活化的类比来说这有点像给新入职的同事一份 onboarding 文档。没有文档的时候他干活全靠猜有了文档他在遇到对应场景时就知道翻到哪一页照着做。superpowers 做的事情本质上就是把团队的所有隐性知识显性化并注入到 AI 的每一次工作会话里。这里再对比一下 MCPModel Context Protocol。MCP 需要跑服务端、定义工具协议、配置权限适合做工具调用和外部系统数据交换。superpowers 则刻意保持轻量它只是文件零服务端、零依赖跟着仓库走就行。前者像给 AI 接 API后者像给 AI 定规矩。实际用下来两者不冲突但在规范代码产出这个场景下superpowers 占用更少、见效更快。1.3 适用场景它到底适合谁来用我自己总结了三个最适合用 superpowers 的场景个人开发者想让 AI 在自己不同的项目里始终保持同一种代码习惯小团队没有精力做复杂的平台化方案但希望 AI 产出符合团队约定对终端编程助手有重度依赖、每天要写大量重复性代码的人如果团队已经做了完善的 RAG、微调或者复杂的 MCP 工具链那 superpowers 可能显得有点原始。但如果你的状态是还在用 Codex 裸奔每次靠复制粘贴提示词维持规范那这绝对是当前性价比最高的升级路径没有之一。2. 环境准备与安装5 分钟把 superpowers 跑起来2.1 安装前需要确认的前置条件superpowers 本身是跑在 Node.js 环境里的命令行工具通过 npx 分发。所以在动手前先确认你的机器满足这几个条件项目要求说明Node.js18 及以上建议用 LTS 版本太老的版本会装不上npm/npx随 Node.js 自带确保 npx 命令能正常执行Codex CLI已安装并完成登录superpowers 的技能文件最终要装到 Codex 的配置目录里我的建议是先用node -v和codex --version分别确认环境和 Codex 可用再去执行安装命令。跳过这两步直接装出问题了排查起来反而多花时间。2.2 标准安装步骤安装命令非常简单就一行npx superpowers install第一次运行的时候它会让你选择要安装的技能包。superpowers 官方维护了一份技能包目录里面有各种常用技能代码审查、编写测试、规范提交信息、项目脚手架生成等等。你可以直接选全部安装也可以挑几个自己用得上的。我自己是先把那一批都装上了后面再慢慢删掉不需要的这样能快速看到全貌。装完之后它会把所有技能文件写入到 Codex 的配置目录里。在 macOS 上默认路径是~/.codex/skills/如果你自定义过 Codex 的配置目录位置会跟着变可以根据codex日志里的实际路径来确认。这是我自己机器上安装完成后技能目录的一个简化示例结构~/.codex/skills/ ├── superpowers/ │ ├── configure-superpowers/ # 技能包一 │ │ ├── SKILL.md │ │ └── scripts/ │ ├── code-review/ # 技能包二 │ │ ├── SKILL.md │ │ └── checklists/ │ ├── writing-tests/ │ │ └── SKILL.md │ └── conventional-commits/ │ └── SKILL.md每个技能包目录都至少有一个 SKILL.md或者叫 skill.md具体看版本这就是技能的核心描述文件。Codex 在每次会话启动时会扫描这些文件并作为上下文加载。装完之后如果不确定技能有没有被识别可以用这个命令看一下当前加载了哪些技能superpowers list正常输出会列出所有可用技能的目录路径和描述摘要。如果这个列表是空的说明安装路径没对上需要检查 Codex 的配置目录是否匹配。提示superpowers 的版本更新比较快部分命令参数在版本迭代后可能会有调整。如果你装的版本命令行为和我写的不完全一样优先以npx superpowers --help输出为准。2.3 账号与版本检查我踩过的一个坑是Codex 如果没登录superpowers 虽然能安装技能文件但 Codex 根本不会加载它们。因为技能本质上是给 Codex 会话用的上下文Codex 本身不可用技能装得再多也无济于事。所以装完 superpowers 后务必先跑一条最简单的 Codex 指令验证一下codex say hi如果 Codex 能正常回复再跑superpowers list看技能加载这样才能排查出问题到底出在哪个环节。3. 技能包怎么用让 AI 真正按你的规矩干活3.1 理解一个技能包的组成部分刚接触 superpowers 的人可能会有个误解技能包是不是一串很长的提示词其实不是。技能文件的核心价值在于它的结构比提示词更清晰且能被 AI 明确地寻址和引用。一个完整的技能包通常包含以下内容组成部分作用示例YAML frontmatter告诉 AI 你什么时候该用这个技能description: 用于创建新 Java 服务的单元测试目标描述说清楚任务完成后应该长什么样测试覆盖率不低于 80%命名遵循给定规则步骤清单把任务拆成 AI 可以逐条执行的顺序先找被测类再写测试框架基类再补异常分支检查清单任务完成前的自查项目是否覆盖空指针、边界值、超时场景示例代码给 AI 提供模仿的模板标准服务类测试代码片段之前提到技能文件头部需要 YAML frontmatter实际上是决定 Codex 是否能正确匹配技能的关键。我见过很多失败案例都是因为 description 写得太泛——比如写处理 Java 异常AI 在任何一个 Java 任务里都拿不准到底要不要触发最终结果就是技能形同虚设。关于语法这里补充一句不同版本的 superpowers 对 frontmatter 字段名的要求可能不一样。有的版本用description有的版本用when_to_use有的版本两者都支持。我在 2025 年最近一次更新后实测name和description是必须的when_to_use可以作为附加说明放在描述里。为了避免版本兼容问题我的习惯是在description里明确写清触发场景而不是完全依赖单独字段。3.2 动手创建一个自己的技能包下面我用一个常见场景演示给 Java 项目写单元测试。假设你的团队要求所有新增 service 类必须有单元测试且遵循 given-when-then 结构覆盖率达到 80% 以上。技能文件可以这么写--- name: java-service-unit-test description: 当在 Java 服务中新增或修改 service 类时使用此技能如果生成单元测试 version: 1.0.0 --- # Java Service 单元测试技能 在编写或修改 service 类后必须生成配套的单元测试。测试示例如下 ## 步骤 1. 定位被测 service 类及其依赖接口。 2. 使用 Mockito 创建依赖 mock 对象。 3. 测试方法命名使用 methodName_condition_expectedResult。 4. 测试结构遵循 given-when-then 三段式。 5. 运行 mvn test 确认所有测试通过。 ## 检查清单 - [ ] 被测类是否 100% 覆盖主要 public 方法 - [ ] 是否覆盖入参为空、边界值、异常路径 - [ ] 是否使用 AssertJ 而非 JUnit 原生断言 ## 示例 ExtendWith(MockitoExtension.class) class OrderServiceTest { Mock private OrderRepository orderRepository; InjectMocks private OrderService orderService; Test void createOrder_whenStockEnough_thenReturnOrder() { // given CartItem item new CartItem(sku123, 2); // when Order order orderService.createCartOrder(List.of(item)); // then assertThat(order.getStatus()).isEqualTo(OrderStatus.CREATED); } }写完后把这个文件放到~/.codex/skills/java-service-unit-test/目录下再运行superpowers list看到这个技能被列出来就可以用了。这里有一个关键点技能不是在对话中提到才生效它是在每次会话启动时被读进系统上下文的。也就是说只要 Codex 的会话加载了~/.codex/skills/AI 就知道存在这么一套规则。当你在对话里提到给 OrderService 写测试时它就能自动匹配到java-service-unit-test这个技能并执行。所以技能描述文件写得好不好直接决定 AI 会不会在正确的场景触发它。3.3 技能更新与资源管理技能文件装了一段时间后官方目录会更新你本地可能也需要迭代。更新分成两种情况本地修改自己的技能直接编辑~/.codex/skills/下的 Markdown 文件改完重新打开 Codex 会话即可生效。更新官方技能包可以重新运行npx superpowers update拉取最新版本。注意Codex 的上下文窗口是有限的。技能装了太多每次都会占用上下文容量留给实际代码对话的空间就少了。我的原则是够用就好别贪多。我自己的做法是每个技能文件控制在一屏内能读完的量需要大段代码模板的把模板拆到独立文件里技能 MD 文件只引用它。这样既保留了上下文空间又方便模块化复用。4. 实战集成superpowers 与 Codex 及工作流助手的组合玩法4.1 Codex 与 superpowers 的分工逻辑明白了技能包结构就该聊组合玩法了。很多人以为 superpowers 装完就结束了其实它最有价值的使用方式是把技能和其他自动化工具串起来让它真正嵌入到开发流程里而不只是写代码时有点用。先说 Codex 的定位。Codex 是 AI 执行者负责理解指令、编写代码、执行终端命令。superpowers 提供的是规则和流程。两者结合之后AI 的代码生成过程就从自由发挥变成了按技能规范执行。举个例子我之前让 Codex 在 Java 项目里新增一个订单查询接口它生成的代码层次混乱逻辑一股脑塞在 controller 里。后来我给项目写了一个名为 java-service-layering 的技能要求controller 只做参数校验service 做业务编排repository 做数据访问之后Codex 生成的代码结构就稳定了每个分层各司其职几乎没有再出现过整段业务代码堆在 controller 里的情况。4.2 与其他工作流助手的集成worbuddy 这类工具的玩法再来看闹出不少动静的 worbuddy 一类的自动化工具。理解这类工具很简单——它就像团队里一个专门跑流程的机器人你可以让它去执行任务拆解、进度追踪、结果汇报。和 superpowers 搭配时的逻辑是这样的worbuddy 负责拆解大任务判断当前需要 AI 完成哪些代码改动superpowers 负责给 Codex 提供怎么改的具体规则Codex 负责真正执行代码生成举个例子。你在项目里接到一个给用户模块增加头像上传功能的需求。worbuddy 把这个任务拆成若干子任务其中一个是编写用户头像上传接口。它调用 Codex 时Codex 的上下文里因为装好了 superpowers 技能会自动带上接口命名规范、异常处理规范、数据传输对象规范等约束。最终产出的代码从结构到风格都是统一的。我实际试过的一个组合流程是用 worbuddy 生成任务清单由 Codex 完成代码最后用 superpowers 里的 code-review 技能对生成结果做一轮AI 自审查。效果相当稳定明显比裸奔的 Codex 生成的代码干净很多。需要注意的坑是工作流助手很可能每次调 Codex 时会新建临时目录如果临时目录里没有技能配置那 Codex 就加载不到 superpowers 技能。我之前就吃过这个亏在 worbuddy 的工作目录下配置一次后才稳定加载。所以如果你在集成过程中发现技能没生效不要第一时间怀疑 superpowers 装坏了先确认 Codex 会话的工作目录是不是指向了技能安装目录。4.3 多种语言场景下的实际适配superpowers 的技能包目录里有很多跨语言技能但 Java 场景值得单拿出来说。为什么因为 Java 项目规范比脚本语言严格得多包名规范、目录结构、异常体系、Bean 校验每一个环节都有可能让 AI 自由发挥到面目全非。以 Spring Boot 项目为例我给项目装配了这几个 Java 技能技能名作用java-service-layering强制分层规范避免 controller 写业务逻辑java-exception-handling统一异常包装不允许把异常堆栈直接抛给前端java-unit-test-template强制给 service 写单元测试给定测试模板格式java-rest-api-response统一接口返回结构为 code/message/data 三级结构这一套搭配下来最直观的效果是同一段功能逻辑交给 Codex 编写使用 superpowers 前后的代码差异非常明显。用之前接口返回的数据结构五花八门用之后稳定到可以闭眼接前端。这里顺便说一句关于skill 写什么的建议不要试图把整个项目的所有规范塞进一个技能文件因为这样 Codex 会读得冗长、执行得拖沓。把大规范拆成几个小技能每个技能只解决一个具体问题触发时更精准上下文也不会浪费。我的经验是多技能、各自小而专远胜于一个大而全的技能包。5. 常见问题与排查实录5.1 安装失败与技能加载异常说到实际问题我把这几个月折腾 superpowers 遇到的坑集中列一下全是实测过的排查思路问题现象可能原因解决方案npx superpowers install卡住npm 网络代理或仓库慢换 npm 镜像源重试技能安装成功但superpowers list为空安装目录与 Codex 配置目录不一致手动定位 Codex 的 skills 目录复制过去Codex 会话完全不理会技能描述技能描述太泛触发条件不清晰重写 description写明具体场景通过工作流助手调用时技能失效临时目录未包含技能配置在真实工作目录中配置技能路径技能更新后 Codex 读的还是旧版本会话未重启新开一个 Codex 会话或重启终端我印象最深的是第二次安装时遇到的目录问题。当时 superpowers 更新版本后默认安装路径变了但我本地还残留着旧的路径导致superpowers list加载到的是旧技能。最后我把旧目录清掉重新安装才解决。所以你们升级版本后如果发现技能变了先看看是不是有新旧两套目录并存。5.2 技能不触发描述词与触发机制这类问题绝对是使用率最高的 bug。Codex 通过技能文件里的描述来决定是否在当前任务中使用它如果描述写处理 Java 异常那 AI 就有很多种理解方式可能触发也可能不触发。想让它准确触发描述就要写得更具体。下面是我从失败到成功的两个描述对比# 失败版本 description: 用于处理 Java 异常# 成功版本 description: 当在 Java Spring Boot 项目中编写 Controller 层方法或 Service 层方法时 如果方法内需要捕获异常或向上层抛出异常必须使用此技能统一包装为 BizException。第二个描述里包含了触发场景Controller 层或 Service 层方法、触发动作捕获异常或抛出异常、执行约束统一包装为 BizException。这样 Codex 就能在关键时刻明确地联想到这个技能。还有一个容易被忽略的细节技能文件里的步骤和检查清单要用清晰的命令式语气写。应该和可以这类词AI 会理解为建议而非必须最终执行时会打折。我自己的做法是全部改成必须需要禁止效果立竿见影。5.3 实测心得与避坑总结最后分享几条我自己录下来的经验。第一技能包需不需要版本管理我的回答是强烈建议。当你把 superpowers 用于团队协作时技能的迭代和代码迭代一样重要。每个技能文件的 frontmatter 里维护一个 version 字段升级规范的时候一起改技能发版记录和代码提交记录就能相互印证。第二不要迷信一次性安装所有技能。技能装得越多Codex 每次会话的固定开销越大。上下文窗口有限技能占多了留给代码的容量就少了。我个人的标准是常驻技能控制在 5 到 8 个特殊情况用临时技能文件补充。第三遇到不生效的问题时调试路径是固定的先验证 Codex 可用再验证 superpowers 列出技能最后检查技能触发条件。不要一上来就重装浪费时间的。用superpowers list配合一次简单对话测试往往五分钟内就能定位到问题。看到这里如果你已经按照上面的步骤把技能包跑起来了大概率能感受到AI 第一次真正按你的规矩干活的那种舒适感。我个人在实际项目里最直观的体感是用来做代码审查的技能包让 AI 不仅会写代码还会在写完代码之后用团队规范重新审视一遍自己把遗漏的异常处理和边界条件补上。这比单纯生成代码要好上一个量级。最后再分享一个自己常用的小技巧技能文件里除了写规则一定要写反例。AI 能从正面示例学到该怎么做但真正让它在边界场景不跑偏的往往是明确告诉它不要这样写的负面案例。比如禁止在 Controller 层直接操作数据库禁止吞掉异常后返回 null。这些反例写得越具体技能在实操中就越锋利。希望这套玩法也能给你的开发流程带来一些实在的改变。