Superpowers：为Codex CLI装上持久技能库与工作记忆

如果你平时用 Codex CLI 写代码，一定有过这种体验：它能改 bug、能补测试，但每次都要你手把手告诉它“项目结构是什么、代码规范是什么、这次任务的目标是什么”。等于说，你请了一个能力很强的实习生，但每次都要重新培训一遍。Superpowers 这个工具，就是来解决这个问题的。它不是某个花哨插件，而是一套给 Codex 装“技能”和“工作记忆”的框架。

简单讲，你把团队的规范、常用脚本、某个模块的说明写成 SKILL.md 扔进.codex/skills目录，Codex 在干活时会自动检索并调用这些技能；写过的解决方案、踩过的坑也能沉淀成 TIL（Today I Learned），下次直接复用。它跑在命令行里，不挑编辑器，安装也很快。适合所有用 Codex CLI 写代码、尤其是做 Java 后端的老哥，也适合想给 AI 助手做“企业级调教”的人。今天这篇就从一个实际使用者的角度，把 superpowers 的安装、配置、核心机制、Java 实战和避坑经验一次讲透。

1. 为什么需要 Superpowers：从“每次从零开始”到“越用越顺手”

1.1 默认 Codex 的“失忆症”是效率最大瓶颈

用过 Codex CLI 的人应该都有同感：单次会话内它很强，但会话一旦结束，它就像失忆了一样。新开一个终端，再次执行codex，它又变成了一个“不太认识你项目”的新人。你昨天刚让它确认过“统一返回体是 R ，错误码第一位是数字”，今天换个模块，它又开始自由发挥，把返回体写成了ResponseEntity<Map<String, Object>>。

这在做 Java 后端的时候尤其明显。Java 项目的样板代码多、框架约定多、模块边界复杂，稍不注意，AI 生成的代码就会“接地气”得过了头：Controller 里直接操作 Repository、事务注解加到接口上、分页参数复制粘贴得七扭八歪。你不可能每次开新会话都把整套团队规范重新粘贴一遍，那样又累又容易漏。

我把这个现象叫“上下文焦虑”。Codex 不是不想做好，而是它的上下文窗口有限，你说得越少，它就越倾向于输出“最通用”的代码，而不是“最适合你项目”的代码。通用代码本身没错，但在一个成熟项目里，统一规范比所谓“更聪明”的写法重要得多。

1.2 Superpowers 到底给 Codex 补了什么

Superpowers 围绕“持久记忆”和“可复用技能”设计，核心有四个东西：

• 技能库（Skills）：把指令、规范、模板打包成一个个SKILL.md文件。AI 可以根据用户请求自动匹配并调用对应技能，不再需要你重复交代。
• 工作流（Workflows）：把多步骤任务拆成有序流程。比如“创建新接口”可以串联生成 Controller、Service、Mapper、DTO、测试用例和 API 文档，避免 AI 跳过关键环节。
• TIL（Today I Learned）：把本次会话里发现的解决方案、遇到的坑写成短文档。下次碰到类似问题，Codex 可以直接参考。
• 触发规则：通过SKILL.md里的description和when字段描述触发条件，Codex 在开始干活前会自动判断“现在该加载哪个技能”。

用表格看更直观：

我一直觉得，给 AI 助手做“技能包”其实就是在做轻量级的“知识工程”。你不是在写 Prompt，而是在给 AI 建一套“操作手册 + 经验手册 + 检查清单”。没有这套东西，AI 是能干活，但干出来的活永远带着“随机性”；有了它，AI 的输出就变成可预期、可审查、可复用的。

2. 快速安装与目录初始化：半小时搭好你的第一个技能库

2.1 安装前先确认环境

先说前提条件，避免装到一半卡住。我默认你用的是 macOS 或 Linux，Windows 用 WSL 也同理。需要准备三样东西：

• Node.js 16 及以上环境，因为 Superpowers 本体是用 Node 写的，全局命令靠 npm 分发。
• Codex CLI 已经装好，并且你至少跑通过一次codex命令，本地已有生效的认证配置。
• Git，虽然不强制，但技能库的管理强烈建议纳入版本控制，后面细说。

先执行检查：

node -v npm -v codex --version

如果你三个命令都有输出，就可以继续。如果codex命令找不到，先回去装 Codex CLI，别急着往下走。这一步卡住，后面全是白费。

2.2 安装与初始化命令

Superpowers 的安装相当简单，核心就是一条 npm 全局安装命令：

npm install -g superpowers

装完之后执行初始化：

superpowers init

init会在你的用户目录下创建一套默认的技能库骨架，还会放一个示例技能进去，方便你做冒烟测试。我第一次跑完init后还担心它要配一堆参数，结果没有，它只是很安静地把目录建好，然后打印出几个“下一步可以做什么”的提示。

这里有个细节：如果 npm 全局安装时遇到权限报错，别急着加sudo。先检查一下你的 npm 全局 prefix 是不是指向了用户目录。比如 Linux 上把 prefix 改成~/.npm-global，之后superpowers init就不会出现 EACCES 问题。

2.3 安装后目录结构长什么样

初始化完成后，你会看到类似这样的目录结构：

~/.codex/ ├── skills/ │ ├── _examples/ │ │ └── hello-world/ │ │ └── SKILL.md │ └── my-java-common/ │ ├── SKILL.md │ ├── references/ │ │ └── error-codes.md │ └── scripts/ │ └── gen_controller.py ├── til/ │ └── 2025-05-01-mybatis-result-map.md └── workflows/ └── create-rest-api.md

skills目录就是技能库，每个子目录里必须有一个SKILL.md。til目录放经验笔记，workflows目录放多步工作流定义。

另外，项目内部也能放技能。你可以在任意项目的根目录建.codex/skills，这样做的好处是：项目成员 clone 代码库之后，技能自动跟着项目走。Superpowers 在检索时，项目级技能会优先于全局技能，这一点非常关键，因为同一套技能放到别的项目里很可能就是“污染”。

2.4 和 Codex CLI 的对接方式

很多人会问：Superpowers 装了，Codex 怎么知道要用它？我实际用下来，它的思路很取巧：不劫持 Codex 的命令行入口，也不搞复杂的插件注册，而是复用了 Codex 已有的.codex目录约定。Codex 启动时会自动扫描当前项目根目录和用户目录下的.codex配置，Superpowers 只是往这个目录里放结构化文件。

也就是说，你不需要改 Codex 的启动脚本，也不用手动去source什么文件。只要技能目录位置正确，下次运行codex的时候，Superpowers 生成的文件就会被 Codex 读取到。如果你的版本有额外开关，README 里会写，打开就行；没有的话，直接把技能丢进对应目录就已经生效。

注意：如果你之前已经跑过 Codex，并且用了很久，建议在跑superpowers init之后，把所有终端窗口重启一遍。这个动作看似多余，但能避免 Codex 缓存旧目录结构的问题。

3. 核心机制拆解：SKILL.md 才是技能的“灵魂”

3.1 frontmatter 里哪些字段最重要

SKILL.md的格式沿用了静态站点生成器常见的 frontmatter 风格，文件头部用两行---包起来，里面是元信息。看起来很简单，但每个字段都影响技能能否被正确触发。

我常用的模板是这样：

--- name: spring-boot-api description: 生成符合团队规范的 Spring Boot Controller、Service、Mapper 和 DTO，适用于新增 REST 接口、CRUD 代码生成场景。 when: 用户要求创建新接口、补全 Controller 或生成 CRUD 模块时 version: 1.0.0 ---

name是技能的唯一标识，尽量用短横线连接的小写字母。description是给 AI 看的“广告文案”，它决定 Codex 在任务匹配时能不能捞到你这个技能。when是触发条件，描述得越具体，误触率越低。version主要是方便团队维护，可以后补。

这里我最想强调的还是when字段。比如你写一条技能用于“生成 MyBatis 的 XML Mapper 文件”，如果when写的是“处理 Mapper”，那用户说“帮我写个 DAO”时它就未必触发；但如果写的是“用户提到 Mapper XML、DAO、数据库查询、结果映射时”，命中率就会高很多。触发条件是靠语义匹配的，不是靠关键词精确匹配，所以把同义场景都写进去反而有帮助。

3.2 description 写不好，技能等于没写

很多人容易犯一个错误：description写得太抽象。比如“处理 Java 的事情”“关于 Spring Boot 的帮助”，这种描述在技能数量少时可能还能用，一旦你积累了二三十个技能，Codex 在匹配阶段就会被这些模糊描述带偏，要么找不到正确技能，要么同时调用好几个无关技能，输出一团混乱。

我把这个叫作“检索优先级陷阱”。AI 面对一堆技能时，不是按字母顺序挑，而是计算描述和当前任务的语义相似度。所以 description 应该像写搜索引擎的标题一样，包含三部分：

• 适用场景：什么时候用。
• 产出的东西：会生成 Controller、Mapper XML，还是完整测试。
• 约束关键词：项目里常说的术语，比如“统一返回体 R ”“分页 PageQuery”。

举个例子，下面两个描述差别很大：

description: Java 技能包

description: 生成符合团队规范的 Spring Boot Controller，包括参数校验、统一返回体 R<T>、异常处理和分页逻辑，适用于新增 REST 接口或补全 CRUD 模块时

第二种描述哪怕不读正文，AI 也知道这个技能大概能干什么。技能文件可以很长，但检索时 AI 大概率只先看 description 和 when，所以这两个字段就是你和 AI 之间的“第一道门面”。

3.3 技能正文怎么写才不会被 AI 无视

SKILL.md的正文部分，我的建议是“步骤化 + 清单化”，不要写长篇大论。AI 模型在推理时，更喜欢明确、简短、可检查的指令。你给它一段 3000 字的规范说明，它反而会把关键点淹没在叙述里。

一个靠谱的技能正文大概是这样的结构：

1. 输入信息：需要哪些实体类、请求参数、现有模块结构。
2. 执行步骤：每一步做什么，生成哪些文件，代码放在哪个包。
3. 硬性约束：必须用什么注解、禁止做什么、统一返回体是什么。
4. 验收标准：生成完成后，代码要满足哪些条件，比如“编译通过”“有测试覆盖创建和查询”。

如果你有更详细的背景知识，不要全塞进SKILL.md正文，而是放到同目录的references/子文件里。正文里只写一句“遇到订单状态流转时，参考 references/order-status.md”，这样既能控制主文件的长度，又不会丢掉关键细节。

3.4 从单个技能到多步工作流

有了几个基础技能之后，你自然会想串起来用。比如“开发一个新接口”这件事，涉及 Controller、Service、Mapper、DTO、测试、文档，如果每个环节都要单独触发，那 AI 还是容易“偏科”。这时候就可以在工作流文件里定义步骤：

# create-rest-api 1. 调用 skill: spring-boot-api 2. 调用 skill: spring-boot-service 3. 调用 skill: mybatis-mapper 4. 调用 skill: api-doc-update 5. 运行: mvn -Dtest=OrderControllerTest test

工作流的本质是把“人脑里的流程”显性化。做完这套之后，你再说“按流程创建一个 Order 的 CRUD”，Codex 就不会只给你生成一个 Controller 草稿，而是会沿着这几个步骤走完，最后还跑一遍测试。

3.5 TIL：把“踩坑经验”变成团队资产

TIL 是我个人最喜欢的功能。它像一个微型 wiki，专门记“今天刚知道的事”。比如你发现 Spring Boot 的@Transactional在同类内部调用时会失效，那就可以在til目录下写一个文件：

# 2025-05-01-spring-transaction-self-invocation.md - @Transactional 通过代理生效，同类方法内部调用不会走代理 - 解决方式：把内部方法拆到另一个 Service 类，或者使用 AopContext.currentProxy() - 相关代码示例见 ...

这类经验往往是你花了几个小时排查才得到的，让 AI 记住它，比记在云笔记里更有价值。因为 Codex 在后续会话里处理到相关代码时，能看到 TIL 文件，然后主动规避这个坑。

4. Java 场景实操：用 Superpowers 生成一组 Spring Boot CRUD 接口

4.1 准备一个最小 Java 项目

理论讲太多没用，直接上一段实战。我这边准备一个最小化的 Spring Boot 项目，还是典型的order-service模块。目录结构大致如下：

order-service/ ├── pom.xml └── src/main/java/com/example/order/ ├── OrderApplication.java ├── entity/ │ └── Order.java ├── controller/ ├── service/ └── repository/

pom.xml里引入 Spring Web、Validation、Spring Data JPA、Lombok 这几个基础依赖就行，不用搞复杂中间件，先把技能链路跑通。代码也不需要写完整，因为这一次的主角是 Superpowers 技能文件，不是项目代码。

4.2 编写团队专用的 Spring Boot 技能文件

进入项目根目录，建.codex/skills/spring-boot-crud/SKILL.md，内容参考如下：

--- name: spring-boot-crud description: 根据 JPA 实体生成 Controller、Service、Repository、DTO 和基础 CRUD 接口，统一使用 R<T> 返回体，分页使用 PageQuery，适用于用户要求新增 CRUD 模块时。 when: 用户提到新增接口、CRUD、Spring Data JPA、RestController、分页查询等场景时 version: 1.0.0 --- # Spring Boot CRUD 技能 ## 输入信息 - 实体类：需要处理哪个 Entity，主键字段、必填字段、唯一约束。 - 是否包含分页查询、状态流转、关联对象。 ## 执行步骤 1. 读取实体类字段，识别主键、必填项、唯一约束。 2. 创建 DTO 类：CreateReq / UpdateReq / Resp，字段与实体对应，使用 Lombok 注解。 3. 创建 Repository 接口，继承 JpaRepository，必要时补充查询方法。 4. 创建 Service 接口和实现类，事务注解 @Transactional 必须放在实现类方法上。 5. 创建 Controller，统一返回 R<T>，使用 @RestControllerAdvice 处理参数校验异常。 6. 分页请求参数继承 PageQuery，默认每页 10 条，返回 PageResp<T>。 7. 为 Controller 生成集成测试，覆盖创建、查询、更新、删除。 8. 更新 API 文档中的接口清单。 ## 硬性约束 - 禁止在 Controller 里直接注入 Repository。 - 所有接口统一走 R<T> 返回，成功码为 200，业务异常码从 10001 开始。 - 更新操作必须使用 DTO，禁止把 Entity 直接暴露给前端。 - 生成的代码必须能通过 `mvn -Dtest=OrderControllerTest test` 编译和测试。 ## 验收标准 - Controller 方法数量与 CRUD 需求一致。 - 每个方法都包含参数校验。 - 测试类至少包含 4 个用例：创建成功、查询成功、更新成功、删除成功。 - 编译无错误，测试全部通过。

这段内容看起来长，但读下来就是一份“AI 可执行的检查清单”。你会发现，技能正文里的每一条都是在回答“干活时最容易忽略什么”。把这些写清楚，Codex 的输出质量会提升一个档次。

4.3 在 Codex 会话里触发技能

技能写好后，进入项目目录，直接启动 Codex：

cd ~/projects/order-service codex exec "按照 spring-boot-crud 技能，为 Order 实体生成一组 CRUD 接口"

注意，不同版本的 Codex CLI 命令名可能略有差异，有的版本是codex exec "..."，有的版本是直接进入交互界面后再输入。以你自己的环境为准。关键是命令里要带上技能名spring-boot-crud，这样 Codex 大概率能快速匹配到刚写的技能文件。

实际跑的时候，Codex 会先分析 Order 实体的字段，然后按照技能里的步骤逐步生成。它生成的代码结构会比我之前“裸跑” Codex 的时候规范很多，Controller 里不再出现业务逻辑，Service 里的事务注解也放对了位置。整个流程跑完，它还会主动提示我测试命令还没执行，问我是否要跑一下——这个细节就是技能里“验收标准”起了作用。

4.4 把实现经验沉淀成 TIL

生成完成后，别急着关终端。如果你刚才在过程中发现了一个有意思的问题，比如“JPA 的PageRequest.of默认从第 0 页开始，但前端习惯从第 1 页传”，那就可以把它记到 TIL：

codex exec "把刚才发现的 PageRequest 页码转换问题记录到 TIL，并附上示例"

Superpowers 会在~/.codex/til下自动生成一个带日期的 Markdown 文件。下次再写分页接口时，Codex 就不会忘记这个约定，前端传 1 进来，它知道要先减 1。这种“一次踩坑，永久免疫”的效果，才是 Superpowers 最有吸引力的地方。

5. 常见问题与排查实录：这些坑我全踩过

5.1 技能文件明明写了，Codex 却像没看见

这是最常见的坑。我一开始把SKILL.md放在项目根目录下，写了个自定义文件夹skills/，结果 Codex 完全不搭理。后来发现，技能必须放在.codex/skills下，目录名不能乱改。如果你是项目级技能，路径就应该是：

<项目根>/.codex/skills/<技能名>/SKILL.md

如果是全局技能，则是：

~/.codex/skills/<技能名>/SKILL.md

另外，SKILL.md的文件名必须一字不差，大小写都不能错。Linux 环境下写skill.md或Skills.md，AI 大概率扫不到。还有一种情况是 frontmatter 格式写错了，比如少了description字段，或者 YAML 里的冒号没加空格，技能就会变成“普通 Markdown 文件”，自然不会触发。

排查顺序可以参考这张表：

5.2 技能描述没问题，但执行结果还是不理想

如果技能已经触发，但生成结果仍然不符合预期，问题多半出在正文的“颗粒度”。比如你只写了“生成 Controller、Service、Mapper”，但没写清楚“Mapper 接口不能手写 SQL”“统一返回体是 R ”“分页参数继承 PageQuery”，那 Codex 就会按自己的理解补全。它补的未必错，但不一定是团队要的。

我的实操建议是：技能正文里最好包含“禁止做什么”。AI 生成代码时，对正向指令的执行力很强，但对负面约束的依赖其实也很高。你把“禁止在 Controller 里直接注入 Repository”写进去，效果比写十遍“要分层清晰”都好。同时，正文步骤不要超过 10 条，超过之后信息容易被稀释。这时候就该拆技能，把“生成 Controller”和“生成 Mapper”拆成两个独立技能，再用 workflow 串起来。

5.3 全局技能污染了无关项目怎么办

如果你把“spring-boot-crud”这类技能放在全局目录，那么你在另一个 Python 项目里跑 Codex 时，它也可能尝试调用这个技能，输出一堆 Java 代码。解决办法有两个：

• 项目级优先：把跟某个项目强相关的技能都放到项目根目录的.codex/skills里，不要放全局。
• 用触发条件过滤：在when字段里限制触发场景，比如“仅当用户提到 Spring Boot、JPA、Controller 时使用”。如果当前是 Python 项目，语义匹配到的概率会低很多。

我现在的习惯是：全局只放真正通用的技能，比如“代码 Review 规范”“Git 提交信息格式”“单元测试命名规范”；其他和具体技术栈强相关的技能全部进项目仓库。这样既保留你的个人积累，又不会四处开火。

5.4 prompt 工程化：把技能当代码来维护

最后一个建议，也是我自己踩过几次坑之后总结出来的：Superpowers 的技能文件和代码一样，需要版本化、需要 review、需要测试。

你可以把.codex/skills目录纳入 Git 仓库，每次修改技能后提交 PR，让别人 review。技能文件里的每一项描述，其实都是一种“需求”，写错了会影响很多人。更重要的是，要定期验证技能是否还有效。我一般会准备一个最小示例项目，跑一次同样的 Codex 请求，把输出结果和你预期的代码做对比。这个过程成本不高，但能发现 description 漂移、步骤失效等细节问题。

另外，技能文件里尽量避免写绝对路径。你本机可能是/Users/zhangsan/projects/order-service，但同事电脑上可能是/home/lisi/order-service。正确做法是让 AI 自己判断当前项目路径，技能里只写相对路径和模块名，否则换一台电脑，技能就全废了。我第一次写技能时就踩了这个坑，后来统一改成“在项目根目录下执行 Maven 命令”，才彻底解决问题。

我个人把 Superpowers 跑了一个多月，最明显的感觉是：Codex 从“每次都要交代背景的新人”慢慢变成了“读过团队文档的熟手”。技能文件更新得越多，这种体感越强。最后再分享一个细节，技能文件里别放那些“过几天就想改”的临时内容，比如某个临时表的字段名，而是放在 TIL 里随用随查。技能是稳定的操作手册，TIL 是流动的经验笔记，两者分清楚，你的 AI 助手才会越用越顺手。