很多经常折腾 AI 编程工具的同学，估计都有过类似的体验：初次上手 Codex CLI，觉得挺新鲜，但用着用着总感觉缺了点东西。它能帮你改文件、跑命令、提交代码，可一旦遇到稍微复杂的项目，比如要处理多模块的 Java 工程、要保证代码风格一致、要让 AI 理解团队的历史决策，默认配置就显得“力气有余，章法不足”。
我所说的这个 superpowers，就是冲着这个痛点来的。它不是某个编程语言的框架，也不是什么花哨的 IDE 插件，而是一层跑在 Codex CLI 之上的“脚手架”和“技能包”，通过自定义指令、可复用的技能脚本、以及一套项目记忆机制，让 Codex 从“能干活”变成“会干活”。
如果你是刚听说这个概念，这篇文章会比较长，我会从它到底解决了什么问题讲起，然后给出一套完整的安装与落地步骤，拆解它的技能、记忆与配置机制，再结合 Java 项目的实际场景讲怎么用，最后是我自己踩过的一些坑和调整建议。适合两类人看：一类是已经用上 Codex CLI、但觉得交互质量和项目完成度不够的开发者；另一类是刚准备入坑 AI 编程助手、想一步到位搭好工作流的同学。
1. 从“默认 Codex”到“用得顺手”中间隔着一层脚手架
先说一个比较反直觉的结论：Codex CLI 本身的能力下限，在很多情况下不是由模型决定的，而是由你给它的上下文和指令决定的。模型的能力就摆在那里，但如果你不清不楚地把它丢进一个大型项目里，它很容易表现得像个“很聪明但不懂规矩”的新人。
1.1 Codex CLI 的能力边界到底在哪
Codex CLI 本质上是一个把大模型能力转化为命令行操作的代理工具。它能看到你的文件、执行终端命令、读日志、跑测试，然后基于这些信息决定下一步动作。这一套能力在单文件、小任务上非常能打，比如帮我写一个正则表达式、补一段单元测试、改一个明显的 bug，效果都相当好。
但一旦任务变成“理解整个 modules 的依赖关系”“按团队规范生成新接口”的时候，问题就来了。如果你不主动把相关规则和背景喂给它，它就靠“猜”。猜对了挺好，猜错了就是一顿无效操作，来回改好几轮，不仅浪费时间，还容易把项目改乱。
我当时遇到的具体场景是这样的：一个 Java 项目里分了 web 层、service 层、mapper 层，代码规范要求 Controller 里不能直接碰数据库。Codex 在默认配置下，经常不管三七二十一就在 Controller 里写出一堆 mapper 调用，编译是没问题的，但 code review 的时候直接被打回来。
这当然不能怪模型，模型没有被明确告知这套分层规则。但问题在于，如果每次任务都要我把这些规则反复粘贴进去，那我用不用 AI 助手区别也不大。我需要的是一个能让这些规则“沉淀”下来，并且自动注入到每次会话里的机制。
1.2 Superpowers 这支脚手架做了什么
superpowers 的核心思路，我理解下来就这么几句话：把操作经验写成可复用的技能，把项目背景沉淀为可查询的记忆，把每一条规则变成 Codex 在行动前必须参考的上下文。
第一层，它提供了一套自定义指令，相当于给 Codex 设定了“行为准则”。比如先理解需求再动手、改动前先搜索相关代码、每次修改后要跑测试等。这一层解决的是“AI 愿不愿意守规矩”的问题。
第二层，它引入了一个技能系统。每个技能本质上是一段带特定触发条件的提示词脚本，往往还配合一些自动化操作。比如“创建新接口”这个技能，不是简单让 Codex 写个方法完事，而是引导它按你的分层结构，把 Controller、Service、Mapper、DTO、甚至对应的单元测试模板都生成出来，并且保持命名风格统一。
第三层，它做了一个类似项目记忆的东西。项目中的重要决策、目录结构约定、技术栈选型理由，都可以写入一个结构化的记忆文件里。Codex 每次开始工作前会自动读取这部分内容，相当于它“入职第一天先读团队 wiki”。
这三层叠在一起，效果就很明显了。默认 Codex 像个聪明但散漫的临时工，叠加 superpowers 之后，更像一个懂团队规矩的正式成员。
1.3 我为什么决定引入它
说实话，我一开始对这类“给 AI 助手再加助手”的工具是持怀疑态度的。多一层就有多一层的维护成本，而且如果配置不当，反而可能给 Codex 注入更多噪音。
真正让我下定决心，是连续几个任务都出现同一个让我有点恼火的现象：Codex 明明在对话中已经确认了项目规范，但下一次新会话里又忘得一干二净，继续写不符合规范的代码。对话内的一致性它掌握得很好，但跨会话的“长期记忆”几乎为零。
superpowers 这种把规则外部化、文件化的思路，正好补上了这个缺口。规范不再停留在某一次对话的历史里，而是变成每次会话都会自动加载的上下文。只要配置文件在，任何新会话都能站在同一个起点上工作。
这个价值，用一句话概括就是：它让 AI 编程助手从“面向对话工作”变成了“面向项目工作”。而我需要的恰恰是后者。
2. 安装与启动：需要的环境与完整落地步骤
superpowers 的安装并不复杂，但有一个前提条件容易忽略：它并不是独立运行的软件，而是依附于 Codex CLI 的增强层。所以如果你还没有把 Codex CLI 装好、配好，后面的一切都无从谈起。
2.1 环境准备：先把 Codex CLI 跑起来
以我使用的环境为例，整体需要满足这么几个条件：
- 操作系统方面，macOS 和 Linux 都支持，Windows 下建议通过 WSL 或 Git Bash 使用，否则路径解析和终端能力会有一些兼容性问题。
- 需要提前安装 Node.js，因为 Codex CLI 是基于 Node 生态分发的，建议使用 LTS 版本，版本太老的运行时我遇到过依赖安装失败的情况。
- 访问 API 的凭证也要提前准备好，这里既可以是 OpenAI 官方的 API Key，也可以按你自己的服务渠道来配置，总之要保证 Codex CLI 在没有 superpowers 的情况下已经能正常对话和操作。
验证的方法很简单，随便让 Codex 执行一条命令，比如让它“看一下当前目录结构并说明几个关键文件的用途”。如果它能正常反馈，说明基础环境就绪。
提示：如果你的 Codex CLI 版本比较旧，建议先升级到较新的版本再做后续操作。superpowers 是紧跟 Codex CLI 能力演进的，版本差距太大时，容易出现在调用层面互相不匹配的问题。
2.2 安装路径与关键步骤
环境就绪之后，安装 superpowers 就非常直接了。核心思路是让 Codex CLI 能把 superpowers 提供的指令和技能文件加载进来。
在我实际操作时，安装过程主要分两步：
第一步是拉取项目文件。比较常见的做法是使用它提供的安装命令，比如在终端执行codex install superpowers或者通过包管理器方式获取，具体命令会因版本更新略有变化，建议以项目仓库 README 里的指引为准。
第二步是执行初始化。这一步会创建或修改 Codex CLI 的配置文件，把 superpowers 作为一个“依赖”写进去，并且生成一个工作目录，用来存放后续的技能和记忆文件。
有不少同学会在第一步之后直接开始用，结果发现 Codex 的行为没有任何变化。原因就是初始化没有执行，配置文件没有改动。一定要确保两个步骤都完成。
整个安装过程正常情况下几分钟就能结束。结束后，你可以检查自己的用户目录下是不是多了一个 superpowers 相关的配置目录，里面能看到类似于AGENTS.md、skills、memory这样的子目录或文件。看到这些就说明已经装进去了。
2.3 第一次启动与验证
装好之后先别急着丢复杂的任务过去，做一个简单的验证。
我习惯的做法是，在一个空目录里新建一个测试项目，然后在终端启动 Codex，直接输入类似这样的指令：“请根据 superpowers 的指导原则，分析当前项目状态，并告诉我接下来可以做什么。”
如果配置生效，你会观察到明显的不同：Codex 可能会先读取记忆文件，或者主动确认当前项目结构，而不是上来就埋头写代码。有些版本还支持输入superpowers或者类似的关键词，直接呼出技能菜单，列出当前可用的技能列表。
这里我想提醒一点：由于技能的加载机制牵涉到对系统指令的注入，首次启动时如果 Codex 卡住或响应变慢，不用太紧张。它可能正在读取记忆文件和技能列表，这个过程一般也就几秒钟。如果超过十几秒还没有反应，那就要检查文件路径和配置文件了。
3. 核心机制拆解：技能、记忆与配置结构
很多人第一次接触 superpowers，会被它的技能和记忆概念搞晕。其实换个角度来看就清楚多了：它不过是把原来“人肉提示词”里的那几件事，固化成了文件系统里的结构化内容。
3.1 技能的本质与组织方式
技能是 superpowers 最有特色的部分。我和它在本地磨合的过程中，倾向于把一个技能理解为：一个带固定流程的操作单元。
比如一个“添加新功能”的技能，它不是一句简单的“请帮我添加新功能”，而是会展开为一整套子步骤：确认需求范围 -> 检索现有实现 -> 确认接口风格 -> 生成分层代码 -> 补充测试 -> 运行验证。每一步都可以在技能脚本里写明具体要求，然后由 Codex 按顺序执行。
技能文件本身一般存放在专门的目录里，每个技能一个子目录，里面至少包含一个描述文件，说明这个技能是干什么的、在什么情况下触发、期望的输出是什么。有的技能还会附带模板文件，Codex 在生成代码时会参考这些模板，从而保证输出风格一致。
实际操作中，你可以先使用自带的一组通用技能，熟悉它的工作方式，再逐步添加自己的技能。比如我后来就加了一个“生成 API 文档”的技能，专门要求 Codex 在写完接口后，补一份符合团队模板格式的接口说明。
这里的关键不是技能数量多，而是定义清晰。一个好的技能，边界要窄、步骤要明确、可验证性要强。如果写的太宽泛，比如“帮我优化代码”，它基本上不会比普通对话强到哪去。
3.2 记忆与上下文：让 AI 不再“每次都是新员工”
记忆机制是我认为整个项目里最值得借鉴的设计。它解决的是跨会话信息丢失的问题。
默认情况下，Codex 的每一次会话虽然能通过自动生成的会话摘要保持一定连续性，但起主要作用的还是当前对话的内容。你上次告诉它的项目规则，下次新会话它大概率已经不记得了。
superpowers 的记忆机制，允许你把项目的关键信息写进结构化的 markdown 文件里。每次新会话开始，Codex 会主动加载这些文件，相当于把你想要传递的长期信息注入到上下文中。
哪些内容值得写进记忆文件？我根据自己的经验总结了这么几类：
- 项目目录结构和模块职责，这是 AI 理解工程入口最关键的信息。
- 技术栈和版本选型，包括为什么选这个框架、有没有什么已知限制。
- 编码规范，比如命名风格、分层约束、异常处理习惯等。
- 常见的坑，比如某个模块不能随便改、某个配置文件是自动生成的、某个命令必须在特定目录下执行。
这些内容不需要一次写完，完全可以随着项目的推进迭代补充。比如你在 review Codex 的代码时，发现它反复犯同一个错误，那就值得把对应的规则追加进记忆文件。改完以后，后续的会话基本就不会再犯同样的错。
这里的效果是肉眼可见的。原来我需要在新会话里反复粘贴项目背景，现在只需要一个指令，Codex 就会自己去加载记忆。省下来的不仅是时间，更是一种“它终于记住我了”的体验。
3.3 配置结构与自定义调整
superpowers 的配置文件一般集中在它自己的配置目录下，最核心的就是全局指令文件和记忆文件。
全局指令文件相当于给 Codex 设定的总纲。这里面的内容会覆盖到每一次会话。我一般会放以下内容：
- 工作模式设定，比如优先读取记忆文件、每次操作前先确认计划等。
- 通用质量要求，比如生成代码必须附带必要的注释、修改后必须运行相关测试等。
- 交互偏好，比如当遇到歧义时先提问而不是擅自假设等。
配置修改没什么玄学，就是标准的 markdown 文件编辑。改完后，下次会话就会自动加载。不过有一点要注意：配置内容不是写得越多越好。我之前有一段时候为了追求“规范”，写了一大堆条目，结果 Codex 每个会话要花很长时间处理这些指令，反而拖慢了效率。
我的建议是，配置要遵循“够用就行”的原则。核心规则保持在十到二十条左右，并且每条都尽量说得具体、不含糊。比如“不要修改 generated 目录下的文件”，就比“注意文件安全”要有效得多。
4. Java 项目里的实际应用：从代码生成到代码评审
可能有人会觉得，这种脚手架工具是不是更适合前端或脚本语言项目？毕竟文件更碎、约定更多。但我在 Java 项目里的实际体验是，它反而更能发挥价值，因为 Java 项目的结构更严格、分层更清晰，规则一旦设定好，AI 的执行效果非常稳定。
4.1 一个真实的代码生成案例
我给一个 Spring Boot 项目配置好 superpowers 之后，做的第一个实际任务是生成一个用户模块的完整接口。放在以前，我会手动把需求描述得很细，然后不停纠正 Codex 的层次问题。
那次我只在对话里简单说了一句“按团队规范，为 User 实体生成完整的 REST 接口”。接下来 Codex 的行为让我有点意外：它没有直接开始写代码，而是先加载了记忆文件，然后列出了一个简短的执行计划，包括先查看现有的 Controller 怎么写、异常处理怎么统一封装、分页返回结构是什么。
随后它按顺序生成了 Controller、Service 接口、ServiceImpl 实现、DTO 对象，最后还补了一个针对 Service 层的单元测试。整个过程下来，我几乎不需要做调整。代码风格和现有项目保持了高度一致，新接口的路由命名也符合团队的驼峰规范。
这个案例最让我感慨的不是代码质量，而是执行路径。因为它先读了项目里的规范文件，所以它知道自己应该先看什么、再写什么，而不是一上来就凭感觉制造一堆需要返工的半成品。
4.2 用来做代码评审，效率出奇地高
我本来以为 superpowers 只是用来“写代码”的，后来发现用来“审代码”同样顺手。
有段时间我在 review 一位同事提交的批量更新接口，总感觉事务边界处理得不太对，但一时又说不清问题在哪。我就让 Codex 来帮我分析这个接口的事务传播行为，并对比项目里其他批量操作的写法。
它先搜索了项目中相关的事务注解使用模式，然后对照记忆文件里写着的“事务不要在 Controller 层声明”的规则，很快就指出了问题：这个接口直接在 Controller 里开启了一个大事务，一旦内部某个操作失败，整个请求都会回滚，而且在长事务期间数据库连接一直被占用，并发性能会受影响。
这种审查能力让我意识到，superpowers 的价值不只是“从零生成代码”，它更像一个知道项目“哪些是雷区”的高级助手。你只需要把雷区配置好，它就能在评审时帮你扫出来。
4.3 项目级重构任务
Java 项目里的重构往往比从零编码更考验 AI 对项目结构的理解。有一次我要把一个 util 类里的方法按职责拆到两个不同的工具类中，并且要求所有调用点同步修改。
这个需求如果直接丢给默认 Codex 让它做，它会很机械地处理：找到调用点，替换方法名，然后完事。但容易被忽略的是 import 路径的调整、方法访问权限的变化、以及是否有反射调用会因此受影响。
在配置了 superpowers 的项目里，我额外写了一条记忆规则：“工具类拆分时必须检查反射调用与动态代理场景”。这条规则被加载后，Codex 在执行拆分任务时主动排查了项目中几个通过反射调用旧方法的位置，并给出了警告和迁移建议。
这个效果让我很认可一整套机制。因为规则是通过文件管理，我可以随时把团队的架构经验沉淀进去，下一次遇到类似场景，Codex 就会主动规避。长期下来，对项目代码质量的整体把控有明显提升。
5. 与 Codex CLI 的协同：分工、版本与进阶思路
很多人在安装类似工具时，都会有个疑问：它和我直接手写一堆提示词有什么区别？简单说，手写提示词是一次性的，而 superpowers 把提示词变成了可复用、可组织、可共享的项目资产。
5.1 Codex CLI 与 superpowers 的分工
Codex CLI 负责最底层的交互能力，比如读取文件、执行命令、调用模型推理；superpowers 负责更高层的策略，比如按什么顺序工作、参考哪些规则、达到什么标准叫“完成”。
听起来有点抽象，我举个例子：你在终端里输入一个需求，Codex CLI 负责解析这句话背后的意图，并把任务拆成多个动作。但拆完了之后是先搜索还是先写代码？写代码时遵循什么样的风格？写完后要不要跑测试？这些策略性的问题，Codex CLI 默认没有标准答案，它靠临场发挥。
superpowers 则相当于在 Codex CLI 的工作循环里插入了一层“策略层”。它在后台把策略注入到 Codex 的上下文中，让 Codex 在每一个决策点都有规则可依。
所以你可以理解为：Codex CLI 是执行引擎，superpowers 是经验库。前者解决“能不能做”，后者解决“怎么做才符合我的预期”。
5.2 版本匹配这个问题容易被低估
我在使用中遇到过这么一件事：升级完 Codex CLI 之后，发现原有的一些技能失效了，具体表现是 Codex 好像找不到这些技能文件。
排查下来，问题在于 superpowers 的入口方式依赖 Codex CLI 的某个配置接口，而新版调整了这个接口的位置。这其实提醒了我一个很实际的问题：使用这类工具，版本匹配是需要留意的。
我现在基本遵循一个原则：如果当前项目运行稳定，不会频繁去升级 Codex CLI 或 superpowers。只有当某个新版本提供了我非常需要的特性时，才考虑升级，并且升级后第一时间跑一遍技能自检，确认所有关键技能都能正常调用。
5.3 进阶思路：把它变成团队的“共享插件”
用顺了之后，你会慢慢发现 superpowers 的能力边界远不止个人使用。因为技能和记忆本质都是文件，这些文件是可以提交到代码仓库里共享的。
我在团队里做过一次实验：把整理好的技能目录和记忆文件模板放到项目的docs/ai目录下，让团队其他人也能一键安装相同的配置。这样做的最大好处是，每个人在同一个项目里使用 Codex 时，行为基线是一致的，不会出现这个人的 Codex 会写这种风格，那个人的 Codex 完全放飞自我的情况。
当然，这个做法需要同步一个团队约定：配置文件的修改要经过 review。否则每个人都在本地乱塞技能，反而会稀释规则的权威性。
6. 踩过的坑、调试思路与我的落地配置建议
任何工具用起来都不会一路平坦，superpowers 也有它的一些“脾气”和限制。这一部分把我实际踩过的坑整理出来，同时也给出我目前比较满意的配置思路。
6.1 最常遇到的几个问题
第一个问题是技能没有被正确加载。具体表现是，你明明已经把技能文件放好了，但 Codex 好像完全不知道它的存在。我遇到这种问题，常规检查路径是先看配置文件里的路径指向是否匹配，再看技能文件的目录层级是否符合预期。有时只是子目录多套了一层，Codex 就不认。
第二个问题是记忆文件内容过时。这个其实比上一个更隐蔽。因为记忆文件是一开始写好的，随着项目演进，原来的目录结构或技术选型可能已经变了，但文件里的内容没更新。结果 Codex 每次都在按旧规则工作，不仅没有帮助，反而添乱。
我现在的做法是，每隔一段时间主动去检查一遍记忆文件，把已经不适用的条目删掉，补充近期新形成的约定。这一步很关键，宁可让记忆文件精简一点，也不要让 AI 带着过期的认知行走江湖。
第三个问题是规则互相冲突。比如我在全局指令里写了“优先使用项目内已有的工具类”，但某个技能里又要求“为了提高可测试性可以引入新依赖”，这两条同时生效时，Codex 有时会陷入反复权衡，效率明显降低。
这种情况没有完美的自动解法，只能靠人肉梳理。遇到冲突时，我会明确把某一条规则加上“除非……否则”的限定条件，让两个规则各有各的适用场景。
6.2 我给新手的落地建议
如果你是在一个中等规模的 Java 项目里第一次尝试，我的建议是不要一上来就铺开所有功能。先做三件事就够了。
第一件事，只建立一个最小记忆文件，里面写上目录结构、技术栈和三条最重要的编码规范。重点是让 Codex 先有“项目认识”。
第二件事，从自带技能里挑一个跟你当前任务最匹配的用起来，不要急着写自定义技能。用得多了，你就自然知道技能应该怎么拆、粒度怎么控制。
第三件事，每次发现 Codex 犯了一个值得记录的错，就把对应的规则追加到记忆文件里。持续两三周，这个文件会变得非常有含金量，这就是你的项目与 AI 助手磨合出来的“私有知识库”。
我还想特别提一个容易被忽略的点：就算有了 superpowers，也不要省略对 Codex 输出结果的 review。它仍然可能犯错，只是犯错的方式改变了——从“违反上下文规则”变成“对规则理解得过于僵化”。它能帮你把低级工作自动化，但判断权始终要在自己手里。
6.3 我的最终配置心态
整个体验下来，我认为 superpowers 最大的价值不是那些花哨的技能脚本，而是一种把“调教 AI”这一动作变得系统化的思路。
你不需要什么魔法，也不需要会复杂的编程姿势。你只需要把一个项目该有的约定、边界和流程，有条理地写下来，让 AI 每次工作的起点都站在同一个高度。这套方法不仅能用在 Codex CLI 上，它对其他类似的 agent 工具也有参考价值。
如果你刚入坑，我真心建议先在一个有点结构、但又不是特别庞大的项目上试试。让 Codex 先读取记忆、再列计划、再动手执行，整个过程会让你对 AI 编程助手的上限有个全新的认识。它在细节上可能仍需要人盯，但确实已经把“从 0 到 1 的搭建过程”省去了大半。
试完之后你大概率会和我有同感：真正让 AI 变强的，不是模型本身，而是你愿意花多少心思去定义“该怎么干活”。
