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 安装 superpowersGit 克隆 符号链接接下来安装 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必须有对应的ResponseT包装批量查询时如果某个订单号不存在或已被删除不能抛异常中断整体而是跳过并记录日志日志必须包含orderBatchQuery这个关键词方便后续链路追踪。AI 生成的代码基本符合这些要求。比如它给出了这样一个 Service 方法片段public ListOrderInfoDTO batchQuery(ListString orderNoList) { if (CollectionUtils.isEmpty(orderNoList)) { log.info(orderBatchQuery|input list is empty); return Collections.emptyList(); } ListOrderInfoDTO 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 返回值统一使用 ResponseT 包装禁止返回裸 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 的行为规范本质上反映了你希望它变成什么样的工程师。