1. 项目概述：superpowers 到底是什么
我最近在折腾一个叫superpowers的项目，起初看到名字还以为是某种游戏模组，点进去才发现 —— 这玩意是给 AI 编程助手用的“技能包”。如果你手头正在用 Codex、Copilot 这类 AI 编码工具，并且觉得它们“偶尔聪明、经常摆烂”，那 superpowers 就是用来解决这个问题的：它通过一套结构化的“技能”定义，让 AI 在接到任务时不再自由发挥，而是按照你预先设计好的步骤、规范和检查清单去执行。
说得直白一点，普通情况下你让 AI“帮我写一个 Java 的 HTTP 客户端”，它可能直接甩给你一段代码，能用但未必符合你项目的封装风格，也未必处理了超时、重试、日志这些细节。而叠加了 superpowers 之后，AI 会先加载对应的技能文件，按照里面定义的“先分析接口、再设计异常处理、最后写单测”这样的流程走一遍，产出的代码质量和稳定性会明显上一个台阶。
这篇文章适合这几类人看：
- 正在用 Codex CLI 或类似本地 AI 编程助手的开发者；
- 觉得 AI 写代码“能用但不好用”，想通过提示工程或工作流约束来提升质量的人；
- 对“技能包”这种新兴的 AI 工程化方式感兴趣，想自己定义一套团队级 AI 规范的人。
我会把 superpowers 的核心设计思路、安装配置方式、在 Java 项目里的实际用法，以及我踩过的几个坑一起写出来。不保证是最权威的教程，但保证都是实操过的。
2. 核心设计思路：为什么需要“技能包”而不是“更长的提示词”
2.1 AI 编程助手的“能力上限”不在模型，而在上下文
先聊一个很基础的认知：现在的大模型本身已经具备很强的代码生成能力，但直接扔给它一个需求，它往往会选择最“安全”的路径 —— 给一段能跑通的代码，而不是最符合你项目规范的代码。为什么？因为模型并不知道你的项目里有哪些约定，它只能靠猜。
传统解法是在提示词里写一大堆规则：“请遵循项目中的异常处理规范”“请为所有公共方法添加 Javadoc”“不要使用 Lombok”。但这样做的坏处显而易见：提示词越来越长，占用的上下文越来越多，而且规则之间可能互相冲突。我见过有人把提示词写到两千多字，结果模型反而把重要的约束给忽略了。
superpowers 的思路是把这些规则拆分成独立的、可复用的“技能文件”。每个技能文件聚焦一个主题，比如“编写 Java 单元测试”“设计 REST API”“重构遗留代码”。使用时不是一股脑全塞给 AI，而是根据当前任务动态加载对应的技能。这和“函数式编程”有点像：把大段逻辑拆成小函数，按需调用，而不是把所有逻辑堆在一个 main 方法里。
2.2 superpowers 的工作机制：技能、插件与钩子
从结构上看，superpowers 由三部分组成：技能包本体、技能定义文件、以及加载器（或者说运行时）。
技能包本体是一组 Markdown 或 YAML 文件，存放到项目的.superpowers/skills目录下。每个文件里面写清楚：
- 这个技能适用的场景（比如“当用户要求生成或修改 Java 实体类时”）；
- 需要遵守的规范（比如“所有实体类必须使用
record或@Data，两者选一，不要混用”）； - 推荐的执行步骤（比如“先检查现有代码风格，再生成代码，最后补充单元测试”）；
- 以及一个“完成标准”（比如“编译通过且测试覆盖率不低于 80%”）。
加载器则负责把技能注入到 AI 的上下文中。以 Codex CLI 为例，superpowers 会在启动时读取当前项目目录下的技能清单，把与本次任务相关的技能拼装成一段系统提示，附加到会话里。这样 AI 在生成代码时，看到的不是一个孤零零的需求，而是一整套“项目规范 + 任务流程 + 验收标准”。
这么设计的最大优势是隔离。你可以在 A 项目里定义一套严格的 Java 规范，在 B 项目里定义一套宽松的 Python 规范，互不干扰。切换项目时，AI 自动加载对应项目的技能，不需要你手动换提示词。
2.3 对比传统提示词，它解决了三个痛点
我实际用下来，认为相比直接在提示词里写规则，superpowers 至少解决了三个痛点。
第一个是上下文占用。一个技能文件通常控制在几百字以内，而传统把所有规则写进提示词的方式可能要上千字。你省下来的上下文可以用来放项目结构、代码片段或测试输出，这对长任务的连续性帮助很大。
第二个是可维护性。项目规范变了，你只需要改技能文件，而不是重新复制粘贴一段超长提示词。团队协作时，技能文件可以放进 Git 仓库，所有人共享同一套 AI 行为准则，代码风格自然就统一了。
第三个是可复用性。你在项目 A 里写好的技能，可以原样拷贝到项目 B。我维护了一套自己的“Java 后端开发技能包”，里面包含异常处理设计、日志规范、DTO 与实体转换规则，新项目初始化时直接拷贝过去，AI 立刻就能用，省掉了重新调教的时间。
3. 安装与配置：从零开始跑起来
3.1 前置条件：装好 Codex CLI
先说前提。superpowers 本身不是一个独立的编程工具，它必须配合一个 AI 编码助手来用。官方目前支持得最好的是 Codex CLI。如果你还没装，需要先搞定这个。
安装 Codex CLI 的方式很简单，在终端里执行：
npm install -g @openai/codex装完之后先跑一次codex，按提示登录你的 OpenAI 账号，完成认证。这一步走通之后，Codex 就能在终端里读取你的项目文件，和你对话并生成代码。
3.2 安装 superpowers：Git 克隆 + 符号链接
接下来安装 superpowers。它的安装方式不复杂，本质上是把技能文件下载到本地，然后让 Codex 能找到它们。
我用的方式是这样：
git clone https://github.com/superpowers/superpowers.git ~/.superpowers然后在你的项目根目录建一个.superpowers文件夹：
mkdir .superpowers cd .superpowers ln -s ~/.superpowers/skills skills这里用符号链接而不是直接复制，是为了后续更新方便。superpowers 项目更新时，你只要git pull一下，所有项目里的技能就都同步了。如果你用的是 Windows，符号链接可能需要管理员权限，也可以直接复制文件夹。
3.3 初始化项目配置
安装完成后，需要告诉 Codex 在启动时加载 superpowers。这一般是通过 Codex 的配置文件来实现的。
在项目根目录下找到（或创建）.codex/config.toml，内容大致如下：
model = "gpt-4o" system_prompt = "你是一名资深软件工程师，请遵循项目中的 superpowers 技能规范来完成工作。"然后，在~/.codex/config.toml的全局配置里，加上一条指向项目技能目录的规则。不过不同版本的 Codex 配置方式略有差异，我的经验是直接在项目目录下启动 Codex，它会自动读取当前目录下的.superpowers/skills。如果发现读不到，可以在config.toml里手动指定：
[superpowers] skills_path = ".superpowers/skills"这里有一个容易踩的坑：有些版本的 Codex 对config.toml的字段名称很敏感，如果写错了不会报错，但技能静默失效。我建议配置完以后，先故意用一个不在技能库里的需求来测试，比如问 AI“你加载了哪些技能？”如果它答不上来，说明配置没生效。
3.4 验证是否安装成功
有一种简单的验证方式：在你的项目里写一个简单需求，比如“给我写一个 Java 工具方法，用于将字符串按逗号拆分为 List”，然后观察 AI 的输出。
如果 superpowers 生效，AI 可能会先反问或说明“根据你的 Java 技能规范，我会先定义方法签名，再处理空值，最后补充单元测试”。如果没有这类结构化响应，而是直接甩代码，那就需要回头检查配置。
我自己第一次装的时候就没生效，折腾了半天才发现是config.toml里skills_path写成了绝对路径，而项目里的实际目录是相对路径，导致加载失败。这个问题后面会在常见问题里细说。
4. 核心实战：在 Java 项目里用 superpowers 做一次完整任务
4.1 场景设计：为订单服务编写批量查询接口
为了讲清楚 superpowers 的实际用法，我用一个真实的 Java 场景来演示：假设项目里有一个订单服务，需要为管理后台提供一个批量查询订单详情的接口，入参是订单号列表，出参是订单信息列表，要求做好参数校验、空列表处理、异常隔离和日志记录。
我把这个需求直接抛给 Codex，同时启用 superpowers 里的java-backend技能。下面是整个交互过程和我的观察。
4.2 第一步：AI 读取技能并拆解任务
启动 Codex 后，输入：
需求：新增一个批量查询订单详情的接口，入参为订单号列表，出参为订单信息列表。遵循项目的 superpowers 技能。AI 在几秒之后给出了一个执行计划，大致是：
- 确认项目现有代码结构和订单实体；
- 设计接口请求和响应 DTO；
- 实现 Service 层批量查询逻辑，注意单条失败不影响整体；
- 添加 Controller 入口；
- 补充单元测试。
这个计划的顺序其实就来自技能文件里写的“执行步骤”。如果没有 superpowers，很多 AI 会直接生成一个 Controller 加一个 Mapper 完事，根本不会先确认现有代码结构。单凭这一点，技能的价值已经体现出来了。
4.3 第二步：按技能规范生成代码
接下来 AI 开始写代码。我在技能文件里定义了这样几条核心规范：
- 请求参数必须使用
@NotBlank或@NotEmpty做校验； - Controller 层不允许直接返回
Map，必须有对应的Response<T>包装； - 批量查询时，如果某个订单号不存在或已被删除，不能抛异常中断整体，而是跳过并记录日志；
- 日志必须包含
orderBatchQuery这个关键词，方便后续链路追踪。
AI 生成的代码基本符合这些要求。比如它给出了这样一个 Service 方法片段：
public List<OrderInfoDTO> batchQuery(List<String> orderNoList) { if (CollectionUtils.isEmpty(orderNoList)) { log.info("orderBatchQuery|input list is empty"); return Collections.emptyList(); } List<OrderInfoDTO> result = new ArrayList<>(); for (String orderNo : orderNoList) { try { OrderPO po = orderMapper.selectByOrderNo(orderNo); if (po == null) { log.warn("orderBatchQuery|order not found|orderNo={}", orderNo); continue; } result.add(orderConverter.toDTO(po)); } catch (Exception e) { log.error("orderBatchQuery|query failed|orderNo={}", orderNo, e); } } return result; }这里的orderConverter、orderMapper都是 AI 在读取项目结构后自动匹配的现有组件，而不是凭空新建。我觉得这正是 superpowers 有价值的地方——不是模型变聪明了，而是它被引导着去参考项目上下文了。
4.4 第三步：AI 自动执行验证与收尾
生成完代码后，AI 没有直接结束，而是继续做这几件事：
- 检查 Mapper 接口中是否已经有
selectByOrderNo，如果没有就提示需要添加； - 生成对应的单元测试，测试用例覆盖空列表、部分订单不存在、正常批量查询三种情况；
- 最后运行
mvn compile验证代码能编译通过。
在我实际项目里，由于selectByOrderNo方法并不存在，AI 很识趣地没有硬编译，而是问我“需要我同时创建对应的 Mapper 方法吗？”。这种“知道自己缺什么”的行为，其实就是技能文件里“完成标准”部分在起作用。我在技能里写了一条：如果依赖的组件不存在，必须先询问或补齐，而不是假设它存在。
4.5 我定义的技能文件长什么样
为了让上面这个过程可复现，我把自己在 Java 项目里常用的一个技能文件贴出来，给大家做个参考。这个文件通常放在.superpowers/skills/java-backend.md。
--- name: java-backend description: 适用于 Java Spring Boot 后端接口开发 when_to_use: 当任务涉及新增或修改 Controller、Service、Mapper、DTO 时 --- ## 执行步骤 1. 先读取项目中的实体类、Mapper 接口、已有 Service 和 Controller，确认命名风格。 2. 设计接口入参和出参 DTO，必须继承统一响应基类。 3. 编写 Service 层业务逻辑，避免在 Controller 中写复杂判断。 4. 添加 Controller 入口，使用 @Valid 注解触发参数校验。 5. 补充单元测试，至少覆盖正常流程、空参数、异常分支。 ## 规范 - Controller 返回值统一使用 `Response<T>` 包装，禁止返回裸 Map。 - DTO 字段使用 `@NotBlank`、`@NotEmpty`、`@NotNull` 做校验。 - 日志使用 SLF4J，必须包含方法简写关键词。 - 批量操作循环中，单条异常不得中断整个循环。 - 如果引用的 Mapper 方法不存在，先创建或询问，不要假设存在。 ## 完成标准 - `mvn compile` 编译通过。 - 新增的测试类方法不少于 3 个。 - 代码格式与项目现有风格一致，不使用 Lombok 的项目不得强行使用 Lombok。这个文件的核心结构就是三段：执行步骤、规范、完成标准。AI 每次执行相关任务时都会参考这三段内容。你完全可以按自己的项目情况修改，比如把 Lombok 换成 record，或者加上团队特有的错误码约定。
4.6 不同语言场景的扩展思路
除了 Java，我把另一套技能文件用在了 Python 项目上。结构完全一样，只是规范变了，比如要求类型注解、使用pydantic做数据校验、单测使用pytest等。superpowers 的好处就在于技能文件与代码语言解耦，你只需要为不同语言各写一套规范，AI 会根据项目目录下的技能清单自动选用。
这里有个小技巧：技能文件的when_to_use字段要写清楚触发条件，否则 AI 可能会在不该用的时候也套用。比如“当用户要求编写 Vue 组件时”和“当用户要求设计数据库表结构时”显然是两套完全不同的技能，触发条件写得越明确，AI 的选择就越准。
5. 常见问题与排查技巧实录
5.1 技能没有生效，AI 依然自由发挥
这是我遇到最多的问题，占比可能有一半。表现是：配置了技能文件，但 AI 的回答没有任何结构化迹象，还是直接给代码。
排查步骤：
- 先确认技能目录路径是否正确。在项目根目录执行
ls .superpowers/skills，看文件是否在。 - 再确认 Codex 是否以当前目录启动。有些同学习惯在任意目录下执行
codex，这时候它可能并没有把当前目录当作工作目录，自然读不到项目里的技能。 - 如果前两步都没问题，在对话中直接问 AI：“你目前加载了哪些技能规范？”有些模型会诚实回答，有些则会编造。为了拿到真实结果，可以故意违反一条技能规范，看 AI 会不会提出纠正。比如我在 Java 技术规范里写了“禁止使用裸 Map 作为返回值”，然后让 AI 写一个返回
Map的接口，如果它直接照做，说明技能没加载。
5.2 技能文件太多，AI 上下文放不下
当你在.superpowers/skills下放了十几个技能文件时，加载器可能会试图把所有文件都塞进上下文，导致 token 不够用，甚至出现报错。
我的解决方案是分层管理。把技能文件分成“核心级”和“场景级”两类。核心级只放三四个最常用的，例如 Java 基础规范、代码提交规范、接口设计规范；场景级放在子目录里，或者用命名前缀区分，并在技能文件的when_to_use里写明适用条件。理论上加载器应该按需读取，但不同版本的实现策略不同，保守起见，最小化核心技能集是最稳妥的做法。
5.3 技能文件之间的规则冲突
项目大了以后，难免会出现两个技能文件互相矛盾的情况。比如一个文件要求“所有 DTO 使用 record”，另一个文件又写着“DTO 必须使用 @Data”。AI 同时加载两者时会困惑，可能选择其中一个，也可能两个都用，结果代码风格很怪。
解决办法是建立优先级规则。我习惯在技能文件的规范部分开头加一句“如果与其他技能冲突，以本文件为准”，或者反过来写明“本技能仅补充，不覆盖其他技能的字段命名规范”。这个办法很土，但实测有效。模型对显式的优先级说明比隐式判断要敏感得多。
5.4 特殊字符与文件编码问题
还有一个容易被忽略的细节：技能文件中的中文标点、引号、特殊符号可能被某些加载器错误解析。我曾经在一个 YAML 技能文件里用了中文全角冒号，导致整个文件加载失败，但终端没有任何报错。后面发现后，把所有标点统一改成半角，问题就消失了。
建议技能文件统一使用 UTF-8 编码，并且不要混合全角半角标点。尤其在description和when_to_use字段里，尽量用英文或标准中文标点。
5.5 更新 superpowers 后原有配置失效
由于 superpowers 迭代很快，某个版本升级后，技能文件的目录结构或配置字段可能会变化。我的习惯是不要直接git pull到旧项目里，而是先在临时目录 clone 新版，对比一下目录结构和示例文件，确认没有 breaking change 之后再应用到正式项目。
同时建议把自定义技能文件单独放一个目录，例如.superpowers/custom-skills，和官方技能区分开。这样即使官方升级，你的自定义技能也不容易被覆盖。
6. 一些更进阶的用法和个人体会
6.1 把技能文件变成团队共识
我目前在一个后端小组里小范围推行了 superpowers，效果还不错。做法很简单：把项目规范写进技能文件，然后要求组员本地 clone 一份，Codex 或兼容工具会自动遵守。以前 code review 时经常因为命名风格、返回格式吵来吵去，现在 AI 生成的代码从一开始就符合规范，人工 review 的压力小了很多。
当然，技能文件不可能覆盖所有 review 点，但它能把重复性的、规则明确的那部分自动挡掉，让人的精力集中在设计合理性和业务逻辑上。这个杠杆作用我觉得比单纯提升 AI 输出质量更有价值。
6.2 不要迷信技能文件，它本质还是提示词
有一点必须说清楚：superpowers 不是魔法，它本质上是把“给 AI 的约束”做成了文件化、模块化的形态。如果你的技能文件本身写得含糊，AI 照样会自由发挥。比如“保证代码质量”这种话就没有任何约束力，你应该写成“每个方法必须包含参数校验和日志记录”这种可检查的条目。
另外，我从实际使用中体会到，大模型对规范条数的容忍度是有限的。一个技能文件里如果塞了超过二十条规范，AI 很可能会漏掉后面的内容。我一般控制在十条以内，并且把最重要的三条放在最前面。如果规范确实很多，就拆成多个技能文件，按场景触发。
6.3 后续扩展：可以结合测试驱动和代码评审
我现在还在尝试把 superpowers 和测试驱动结合起来，比如定义一个新的技能tdd-java，要求在写任何业务代码之前，先产出失败的测试用例，然后引导 AI 实现功能让测试通过。目前实验的结果是，生成的测试覆盖率和逻辑严谨度都比直接要求“写测试”要好，因为技能文件里给出了具体的测试命名规范、断言风格和边界值用例设计方法。
后面我还打算在自己的开源项目里维护一套公共技能包，把 Java、Python、TypeScript 三套核心规范放进去，方便日后新项目直接复用。如果你也在折腾这个方向，我建议你也先整理一套属于自己的技能包，而不是直接照搬别人的。毕竟 AI 的行为规范，本质上反映了你希望它变成什么样的工程师。
