最近一直在用 Codex CLI 写项目，感觉它能力有余但主动性不足。你说让它写个模块，它确实能写出来，但也仅仅是"写出来"——不会主动拆任务、不会先补测试、不会考虑边界情况，代码能跑，可离"能维护"差着一大截。后来我把社区里那套叫superpowers的技能包挂了上去，整个工作流立刻就不一样了。这里我把自己整理的安装过程、配置方法、核心技能拆解和踩坑实录一并写出来，给正在折腾 Codex、Cursor 这类工具的朋友做个参考。
先说清楚：superpowers 不是一个插件，也不是什么新框架，它本质上是一组高质量的结构化提示词文档。你把它挂载到 Codex 的上下文里，就等于给这个"聪明的实习生"发了一本标准操作手册。它解决的核心痛点是——AI 编程工具不是不会写代码，而是缺少一套稳定的"行为规范"：什么时候该先写测试，什么时候该停下来重构，拿到需求之后第一步该做什么。superpowers 就是把这类隐性经验显性化，让 Codex 的行为从一个"有问必答的智能补全器"变成"有章法、按节奏推进的结对程序员"。
这篇文章适合谁？如果你已经在用 Codex CLI、Cursor、Aider 这类 AI 编程工具，并且觉得生成的代码质量不稳定、AI 总是一上来就写一大堆代码、或者你对"代码质量、测试覆盖、可维护性"有要求，那这套技能包值得你花一个下午好好配置一遍。如果你是新手，刚开始接触 AI 编程，也可以直接抄我下面的配置流程，跑通后再回头理解原理。
1. superpowers 到底是什么：从"会写代码"到"按规范写代码"
1.1 它不是插件，而是一套"行为契约"
很多人第一次听说 superpowers，第一反应是去搜插件市场，结果什么都找不到。这其实是误解。superpowers 是一系列 Markdown 文档，通常是AGENTS.md、SKILLS.md或者一组存放在.codex/skills/目录下的模块化指令文件。Codex 这类工具在工作时会把这些文档加载进上下文，作为系统提示词的一部分。换句话说，superpowers 通过"写进上下文"的方式来影响 AI 的行为，而不是通过修改模型权重或者工具的底层逻辑。
我打个比方。你把 Codex 想象成一个刚入职的高级程序员，技术底子很好，但他对公司规范一无所知。你不知道这个项目要不要写测试、代码风格是什么样的、重构前要不要先跟团队打招呼。superpowers 就是那份入职手册——它不教他语法，不教他框架，只告诉他"在我们这里干活，步骤是这样、节奏是这样、优先级是这样"。一旦他接受了这份手册，他交出来的工作成果自然就带着"职业感"。
从技术实现上看，这套机制依赖的是现代 AI 助手普遍支持的指令系统。Codex CLI 会在启动时读取项目根目录的AGENTS.md，也会读取配置文件中指定的instructions路径；Cursor 有.cursor/rules/；Aider 有CONVENTIONS.md。superpowers 的技能包通常就放在这些目录下，由 AI 在推理过程中按需调用。它起作用的方式不是"硬编码逻辑"，而是通过自然语言描述来让模型"理解并内化"一套工作流程。这也是为什么它的运行效果与模型本身的能力有直接关系：模型越强，技能包发挥的空间越大。
1.2 为什么一套提示词文档能显著提升编码质量
我一开始也怀疑：就凭几个 Markdown 文件，能让 Codex 脱胎换骨？第一次实测之后，我信了。原因其实不玄乎——当前的代码生成模型在"理解复杂任务"和"遵循显式指令"之间，存在巨大的执行差异。你告诉 Codex"写一个用户注册接口"，它能写出来；但如果你的提示词里包含了"先分析需求边界、列出任务清单、为关键路径补充单元测试、在最后做一次异常路径审查"，它产出的代码结构会截然不同。superpowers 干的事，就是把这些"本该由有经验的工程师口头叮嘱的话"变成系统级的默认行为。
我用过一个很直观的例子验证这点。同样给 Codex 一个 Spring Boot 的UserService需求，没挂 superpowers 时，它会直接生成一个包含save、findById、deleteById的类，然后问我还要不要补点什么。挂了 superpowers 之后，它在动手写代码之前先输出了一份任务拆解清单——API 层放哪里、Service 层抽不抽接口、异常怎么映射、测试哪个类先写，然后一步一步执行。这两种输出的差别，不在于代码本身的语法，而在于"工程化程度"。
这里面还有一个深层原因：superpowers 技能的书写风格高度结构化。它所用的句式、占位符、步骤编号方式，与当前主流大模型的推理习惯非常契合。模型在读完这些文本后，会不自觉地在输出中模仿这种"结构化思维"——这其实就是提示工程里人尽皆知的 few-shot 效应，只是 superpowers 把这种效应规模化，变成了一个完整的行为体系。
1.3 它能做什么、不能做什么：把预期摆正
在继续讲安装之前，我先把 superpowers 的边界说清楚，免得有人期待落空。它能做的事情包括：约束 Codex 在编码前先做任务规划；引导 AI 遵循测试驱动开发的节奏；让代码变更按最小化原则推进——一次只改一个模块，改完就跑测试；在代码审查模式下，强制 AI 逐条检查变更与需求的对应关系。
它不能做的事情也很明确：它不能让 Codex 理解你还没说清楚的需求，不能凭空生成业务逻辑，也不能替代你对架构和产品方向的判断。它更像一个流程监管者，而不是一个领域专家。一句话总结：superpowers 很像是给 AI 助手装了一套"工程伦理与流程规范"，底层的代码生成能力该是什么样还是什么样，但输出成果的组织方式、推进顺序、质量意识会得到明显提升。
2. 安装与基础配置：把 superpowers 挂进 Codex
2.1 环境准备：先确认你的工具链版本
安装 superpowers 之前，建议先确定三件事：Codex CLI 已经装好并登录；Node.js 版本不低于 18；你有一个可以创建目录的项目文件夹。如果还没装 Codex，先跑一下 npm 全局安装。装完以后用--version确认一下，我在实际使用中发现，老版本的 CLI 对instructions目录的支持有过若干调整，所以尽量用较新的版本。
node -v npm -v codex --version如果codex命令提示找不到，检查一下 npm 的全局 bin 目录是否在 PATH 里。这里我不展开太多，因为这些属于 Codex 的基础环境问题，但千万不能跳过，因为后续所有技能包的加载都依赖 CLI 能正常运行。有一个容易忽略的点：如果你之前用过 ChatGPT 的网页端但从来没有在本机登录过 CLI，那么需要先执行codex login，这一步会拉起浏览器授权，完成后才能继续。
基本上，在这一步我能给的最实在的建议是：不要在一个"全新虚拟机"上直接挂 superpowers，先手动跑一个简单的对话任务，确认 Codex 的"裸机"状态是通的，再往上叠技能。否则，后面任何一个环节出错，都分不清是基础链路的问题还是技能包配置的问题。
2.2 拉取技能库：把 superpowers 文件放到项目里
superpowers 的安装方式和一般的 npm 包完全不同——它没有统一的install命令，而是"拷贝 + 挂载"。社区里有人把整理好的技能包仓库克隆到本地，然后在 Codex 配置里指向它。我的做法是建一个统一的技能缓存目录，然后在具体项目里用软链或路径引用的方式加载。
以我用得比较顺的布局为例：
mkdir -p ~/.codex/skills cd ~/.codex/skills git clone <superpowers 技能仓库地址> superpowers ls ~/.codex/skills/superpowers克隆完之后，你会看到类似下面的结构：plan.md、test-first.md、java.md、typescript.md、debugging.md等等。每个 markdown 文件对应一个独立技能，里面的写法高度模板化，有明确的职责定义、触发条件、执行步骤、禁止事项。不要小看这些"禁止事项"，它们往往是保证输出质量的关键。比如debugging.md里面通常会写"禁止在未确认根因的情况下盲目修改代码"，这一条在很多项目里都避免了不少灾难。
这里我开始列第二个容易踩的坑：superpowers 的技能文件必须按约定的命名和目录组织。它不像普通文档，你随手改个名字或者把文件散落在一堆别的 md 里，Codex 在按主题匹配技能时就会失灵。我的经验是尽量保留仓库的原始目录层级，只在需要的时候"裁剪内容"，而不是"重组结构"。
2.3 配置 Codex 读取技能：项目级配置是最稳的挂载方式
技能文件拉下来之后，接下来要解决的是"Codex 怎么知道去读这些文件"。这里有两种方式：全局配置和项目级配置。我强烈建议先试项目级配置，因为它的影响范围可控，不会污染你所有的项目，而且调试起来也更容易。
打开你的项目根目录，找到或创建一个.codex目录，然后在里面放一个config.toml。Codex 会按照配置文件中指定的路径去加载指令文件。下面是一个最简配置示例：
# 项目根目录：.codex/config.toml model = "gpt-5-codex" instructions = [ ".codex/skills/plan.md", ".codex/skills/test-first.md", ".codex/skills/java.md", ]这里instructions字段是一个数组，每个元素指向一个人类可读的技能文档。需要注意两项细节：路径是相对项目根目录的；文件顺序能影响 Codex 的上下文优先级，通常把"通用规划类技能"放前面，把"语言专属技能"放后面。
如果你希望技能包在多个项目里都能生效，不想每个项目复制一遍，可以用绝对路径指向~/.codex/skills/缓存目录下的文件，这样一次配置、到处复用。但我个人不太建议一上来就做全局挂载，因为等你后面挂到第三个、第四个技能包时，就知道"全局的副作用"有多难排查了。
2.4 验证技能是否生效：最简单的冒烟测试
配置完成后，需要做一个快速验证，确认 Codex 真的读到了技能包。我会跑到项目目录下执行一条很简单的指令，比如让 Codex 描述它打算怎么做一个小需求的实现方案。
cd ~/my-java-project codex "请根据当前项目的配置，规划一下如何实现一个简单的用户注册接口"如果技能包生效，我期望的输出里会出现明显的"规划感"，比如先列任务、再讲接口设计、最后提到测试策略。如果输出依然是一大段直接贴代码的回答，那说明技能没被加载进去。此时不要去怀疑模型，先回头检查路径和文件名。我在第一次配置时，就是因为少写了一个./前缀，导致 Codex 静默忽略了两个技能文件。这个问题在界面上没有任何报错，只有通过输出内容才能察觉。
你也可以在对话中直接问 Codex："你正在遵循哪些技能？"如果它能准确说出plan.md和test-first.md里的关键规则，那说明上下文已经生效。这个验证方法简单粗暴，但非常实用，能帮你排除各个层级的配置错误。
3. 核心技能包拆解：plan、test-first、Java 实战用法
3.1 任务分解技能：杜绝"一把梭"式的代码输出
superpowers 里面第一个让我改观的技能是任务规划。以前我让 Codex 写模块，它会在一个回复里贴出 200 行代码，看起来效率很高，但一旦实现过程中出现方案分歧，这 200 行全都得推翻重来。挂载了规划技能之后，Codex 的行为明显改变：它在生成实现代码之前，会先输出一个分步骤的计划，把需求拆解成可独立验证的任务卡片，确保每个步骤之间没有隐式依赖。
在项目里的效果是这样的：我给 Codex 一个需求——"在用户模块中增加邮箱修改功能，要求邮箱唯一性校验，并记录变更历史"。它不再直接冲进UserController里加接口，而是先输出一个计划：
- 检查现有 User 实体与数据库表结构，确定邮箱字段是否已有唯一索引。
- 在 Repository 层增加按邮箱查询的方法并处理唯一冲突异常。
- 在 Service 层实现修改逻辑，注意事务边界与历史记录写入。
- 在 Controller 层暴露接口，统一异常映射。
- 为上述逻辑编写测试，覆盖成功、邮箱重复、用户不存在三个分支。
这种变化看似只是"多了一个清单"，实际上意义非常大。首先，它把不可见的思维过程变成可审查的文本，你可以在 AI 动手之前纠正方向，而不用等写完代码才发现问题。其次，它天然地降低了 Codex 在长对话中"迷失上下文"的概率。因为每完成一个步骤，它会基于计划对自己说"还剩哪些事要做"，这种自我提醒机制对多轮编码特别重要。
实际操作中，我认为最值得借鉴的经验是：不要只依赖默认的规划技能，最好在计划出来后自己确认一遍，把不合理的步骤删掉再让它执行。AI 生成的计划有时候会过于严谨，把"打印一行日志"也当成一个任务，这是上下文膨胀的浪费。你在 prompt 里加一句"只列出与业务功能强相关的步骤，省略琐碎操作"，就能省下不少 token。
3.2 test-first 技能：让 Codex 先写失败测试，再写实现
superpowers 中的 test-first 技能是我最推崇的一个，如果你只打算挂载一个技能，那就挂它。这个技能的核心要求很朴素：在写任何功能代码之前，先写会失败的测试；在测试变绿之前，不允许写实现。很多人以为这只是一种"形式主义"、一种流程上的洁癖，但当你让 AI 遵循这个规则时，它会从根本上改变生成代码的思路。
举个真实场景。我在一个 Spring Boot 项目里让 Codex 实现一个findActiveUsers方法，它需要返回最近 30 天内有登录记录的用户。没有 test-first 技能时，Codex 会直接生成一个 JPA 查询方法，三条注解一行代码，看起来很漂亮。但挂上 test-first 技能后，它先在测试类里写了一个用内存数据库填充数据的用例，构造了一个 60 天前登录的用户、一个 10 天前登录的用户和一个从未登录的用户。测试运行时先红——因为查询方法还没实现。然后它才回去写真正的查询逻辑，最后把测试跑绿。
这个流程的价值在第二次、第三次修改需求时才会真正体现出来。当你想改动findActiveUsers的过滤条件时，那组测试就成了安全网。Codex 如果在后续对话中被要求修改这个方法，它会主动运行测试来验证自己的改动没有破坏原有行为。这种"回归保护"在纯生成式工作流里极其稀有，但却是工程质量的刚需。
我踩过的一个小坑是：test-first 技能会让 Codex 在一些非常简单的方法上也坚持先写测试，比如一个连 if 都没有的空方法。这会显著拖慢简单任务的执行速度。解决方案是在技能文件里，或者在对话提示词中，补充一句"对于纯数据封装、无业务逻辑的简单方法，可以直接实现并在测试中覆盖即可"。这样既保留了测试优先的质量保障，又不会为了流程而流程。
3.3 Java 技能包：superpowers-java 的关键规则与实战效果
热搜词里有"superpowers java"，这个词确实不是空穴来风，因为跟 Java 打交道的开发者对代码结构、命名约定、依赖管理要求是最苛刻的。superpowers 仓库中提供了专门针对 Java 生态的技能描述，这些规则包括：使用标准 Maven/Gradle 目录结构；在 Service 层使用接口隔离；统一异常处理与响应体封装；避免 Lombok 的过度使用；在写 JPA 仓库方法时优先考虑查询可读性等。这些规则单独拿出来都不稀奇，但集成到一个技能文件里，再由 Codex 统一执行，效果就很明显。
我曾经让 Codex 在同一项目、同一需求下分别执行"没挂 Java 技能"和"挂了 Java 技能"两组操作。没挂技能时，它生成的代码里包名直接用了 com.example，没加任何业务前缀，实体类一股脑把所有字段都直接暴露给 Controller，异常处理散落在各个方法里。挂了 Java 技能后，包名根据项目 artifactId 自动推导，Controller 层只接收 DTO，Service 层负责业务逻辑与事务边界，Repository 只保留单一职责的查询方法。代码量没有变多，但可读性和结构规范度完全是两种级别。
关于 Java 技能包还有一个实用细节：它通常内置了对 JUnit 5、AssertJ 和 Mockito 的"使用偏好"。如果你自己不熟悉这几个库，你可以让 Codex 在生成测试时直接依赖它们，而不用每次都用 JUnit 4 的旧风格。这点对很多从老项目转过来的团队很友好，相当于通过技能包完成了一次渐进式的测试框架升级。
实际执行 Java 任务时，我的操作方式是"项目配置 + 按需补充技能"。我会在项目的.codex/skills/目录下同时放着java.md和plan.md，然后在对话里告诉 Codex："请使用 superpowers/plan 制定实施计划，遵循 superpowers/java 的编码约定，先为 Service 层编写测试。"这种显式指定虽然略啰嗦，但比完全依赖自动匹配要稳定得多，因为 Codex 对"隐式技能调用"的判断偶尔会漏，显式点名则基本不会出错。
3.4 前端与 Web 技能：组件边界与可测试性
如果你主要写前端，superpowers 也有对应的技能包。前端技能包的规则通常会约定：组件分为展示组件与容器组件；状态管理方案需要显式说明并集中维护；样式方案需遵循项目的 CSS 变量体系；关键交互必须配套组件测试。这些规范约束之下，Codex 生成的 React 组件很少再出现"一堆业务逻辑塞进 useEffect"或者"所有状态都放在一个 Context 里"的问题。
我自己的一个前端任务是让 Codex 实现一个带防抖搜索的用户选择器。没挂技能时，它只用 useState 加 useEffect 写了一个"能用"的版本，防抖逻辑也每次手写一遍。挂了技能之后，它会先规划数据结构，再抽象一个独立的useDebouncedSearchhook，组件层面只负责渲染候选列表和处理选中状态，并且配套写了一个模拟用户输入后只发起一次请求的组件测试。这个 output 的"构造成熟度"与我团队里中高级前端写出来的东西高度接近。
4. 常见问题与排查技巧实录
4.1 技能包没有生效：路径、命名与版本三大元凶
挂载 superpowers 最常见的失败表现是"配了跟没配一样"。我在各种项目里遇到过很多次，总结下来元凶集中在三处。第一是路径写错，Codex 的instructions配置对路径非常敏感，绝对路径和相对路径都不建议省略前缀反斜杠，同时要确认你用的文件后缀是.md而不是.md.txt。第二是命名不匹配，部分技能包带有语言标识，比如java.md描述的全是 Java 规则，如果你在 Python 项目里测试它的效果，自然觉得"没生效"。第三是 Codex 版本对自定义指令的支持不完整，老版本可能只读取AGENTS.md而忽略instructions字段，遇到这种情况只能升级 CLI。
我的排查习惯是三步走：先用codex "你正在遵循哪些技能？"确认上下文有没有加载；再检查配置文件的 JSON/TOML 语法是否合法；最后查看 Codex 的日志输出，定位在加载阶段出现异常。前两步能解决九成以上的问题，剩下的一成才是环境层面的疑难杂症。
4.2 Java 项目里生成了"风格飘忽"的代码
另一个我见过很多次的场景是：同一个项目，明明挂了 Java 技能，但 AI 在部分对话里突然生成了一堆 Python 风格的命名，比如get_user_name这种下划线命名，或者漏掉了 Java 的强类型声明。排查后我发现，根因往往不是技能没加载，而是"上下文溢出"——当对话轮数过多，原来的技能指令被推进了远距离的上下文，模型注意力被中间堆积的对话内容分散，就会逐渐遗忘早期指令。
针对这个问题，我的做法是在长对话的中途"重新锚定"。当发现 Codex 的输出开始偏离风格时，我会在提示词里追加一句："请重新阅读项目 AGENTS.md 与 superpowers/java.md 中的代码规范，在后续生成中严格遵守。"这句话其实非常有效，因为大模型的注意力机制对最近的指令有明显的偏好，追加一句重新定向，相当于把技能从上下文深处"重新拉回注意力焦点"。用这个方法后，我基本没有再遇到中途风格漂移的问题。
4.3 技能包之间的相互冲突与 Token 膨胀
superpowers 装的技能越多，会不会越好？我的答案是：不会，反而容易互相打架。比如test-first.md要求所有功能先写测试，而debugging.md要求在排查紧急问题时"最小化变更、快速定位修复"。如果两个技能同时出现在上下文里，且没有优先级约定，Codex 可能在一次调试中一会儿执行"先写测试"一会儿执行"快速修复"，输出逻辑自相矛盾。更现实的问题是 Token 膨胀，技能文件本身会占用上下文窗口，挂得越多，留给真实代码分析的 token 就越少，生成质量反而下降。
我的优化策略是"按项目裁剪技能"。一个纯 CRUD 的 Spring Boot 服务，只需要plan.md、java.md、test-first.md三个技能；一个研究性质的脚本项目，只需要plan.md就够了。同时，我会在技能文件里加一个前置声明，明确该技能的"适用优先级"。例如在java.md的开头写："本技能适用于一切 Java 后端代码生成场景，若与其他技能冲突，以本技能的文件名为准并在规划阶段明确对齐。"这种声明能显著减少多技能共存时的行为紊乱。
4.4 快查表：最常见问题与对应解法
| 现象 | 大概率原因 | 解决方案 |
|---|---|---|
| 对话输出完全不像有技能约束 | instructions 路径无效或配置未加载 | 检查 config.toml 路径与文件存在性，用 "你正在遵循哪些技能？" 验证 |
| 初期有效，中途风格漂移 | 技能指令被长对话上下文挤出注意力区 | 追加一句"请重新阅读技能文件并严格遵守"重新锚定 |
| Java 项目生成 Python 风格代码 | 语言技能未匹配或上下文溢出 | 显式指定superpowers/java.md，减少同时挂载的其他技能 |
| 多技能互相矛盾 | 技能优先级未声明 | 在技能文件开头增加适用优先级说明 |
| 简单任务执行变慢 | 技能过多，test-first 对琐碎方法也强制先测 | 裁剪技能数量，追加"非业务逻辑方法可直接实现"的豁免说明 |
| Codex 频繁规划但不写代码 | 规划技能权重过高 | 对话中补充"完成规划后立即开始实现第一个任务" |
4.5 在 Cursor、Aider 等工具里复用这套技能
虽然本文主要讲的 Codex，但 superpowers 这套技能文件的格式非常通用，稍作迁移就能在别的 AI 编程工具里复用。Cursor 支持将.cursor/rules/目录下的文件作为项目规则，Aider 支持CONVENTIONS.md作为约定文件。你可以直接把你裁剪过的java.md拷贝成~/.cursor/rules/java.mdc的格式（Cursor 有自己的一点点格式包装），或者在 Aider 的CONVENTIONS.md里把核心规则按 bullet 分列出来。
我在迁移时的经验是：不要原样复制 superpowers 的文件，而是先让它在一个项目里跑一段时间，看哪些规则对你的团队真正产生了正面影响，然后把"有效的那几条"手写进目标工具的规则文件。这是因为每个工具对系统提示词的处理方式略有差别，原样复制可能带来意想不到的副作用。比如 Aider 的模型对超长规则文件的接受度比 Codex 差一些，把核心规则精简到 200 行以内的效果反而更好。
5. 把 superpowers 内化成自己的工程习惯
最后再分享一点个人体会。superpowers 这套技能包，表面上是给 Codex 用的，实际上它更像一面镜子，把你的工程理念"文档化、流程化、显性化"。我配置好之后第一次看到 Codex 输出规划清单时，忽然意识到——我平时要求团队成员做的事，不就是这些吗？先拆任务、再写测试、保持小步提交、避免过度设计。只是以前这些话只在 code review 时才会被说出来，而 superpowers 把这些话变成了默认动作。
所以比起直接抄一份别人的技能包，我更建议在你自己的项目里跑一段时间后，把那些"你反复向 AI 强调的要求"沉淀成一个项目专属的技能文件。比如你团队约定不要用某个依赖，或者 Controller 不允许直接返回实体类，把这些内容追加到project-rules.md里，挂到instructions列表的最后。这样你的工程规范就真正成了 AI 的肌肉记忆，而不是靠每次对话开头手动输入那一大段话。
与 superpowers 长期相处的过程中，我总结出的一个最有价值的用法是：把技能包当作"最严格的代码评审员"。当代码写完之后，我会让 Codex 加载code-review.md技能，对刚才生成的所有代码做一次彻头彻尾的审查，专门检查事务边界、并发安全、资源释放、异常路径和测试盲区。这个"写完再审一遍"的流程，帮我抓到了不少自己肉眼不会注意到的细节，比如一个在循环里打开的数据库连接，或者一个吞掉异常的空 catch 块。这些瑕疵单独看都不致命，但堆在一起就是线上故障的温床。
如果你愿意进一步探索，还可以试试让 Codex 同时加载两个互相制约的技能，比如plan.md负责约束它先想清楚再动手，refactor.md负责让它定期清理代码坏味道，两者交替作用下，长期维护的代码库会保持在一个相当干净的状态。用一句话说，superpowers 的真正价值不是让你写得更多，而是让 AI 在动手之前想得更周全，并在每一步留下可追溯、可验证的痕迹。
