Superpowers扩展框架：把Codex CLI升级为带技能库的AI开发执行团队

最近我开始把大量重复开发工作交给 Codex CLI 去做之后，很快撞上一个所有重度用户都会遇到的问题：模型能力确实强，但它不懂我的项目约定、不懂我的团队规范、更不会主动按照固定流程去跑完"改代码-跑测试-生成变更记录"这一整套动作。每次开新对话都要花大量篇幅重新描述背景，遇到复杂任务还会出现上下文不够用、中途跑偏的情况。我找到的解法是一个叫 Superpowers 的开源扩展框架，它把 Codex CLI 从"单次对话式助手"升级成了"带技能库的 AI 开发执行团队"。

这篇文章就基于我实际使用 Superpowers 的经验，讲讲它到底解决了什么问题、怎么装、怎么配、怎么在 Java 工程里写自己的技能，以及在真实项目中踩过的坑和排查思路。适合已经用上 Codex CLI、觉得默认模式不够顺手，想把它改造成符合自己团队工作流的开发者。

1. 先说结论：Superpowers 到底解决了什么问题

Superpowers 这个名字起得很直白，它的目标就是给命令行里的 AI 编程助手加上一套"超能力"。具体来说，它做的不是重新发明一个助手，而是在现有助手之上加了一层技能系统，让每次对话都能以结构化、可复用、可版本化控制的方式来完成真实任务。

在没有 Superpowers 之前，我使用 Codex CLI 的典型流程是这样的：写一段自然语言指令，模型根据当前工作目录的文件上下文开始干活。问题在于，指令的表述质量直接决定输出质量，而每个人、每一天、每个任务里的表述都不一样。你很难保证今天写的 prompt 和上周写的有同等质量，更不用说让团队其他成员复用我这套经验了。

装上 Superpowers 之后，核心区别在于：任务从"一次性描述"变成了"调用技能"。我可以在仓库里放一批技能文件，每个技能文件描述一个完整的工作流，包括输入参数、执行步骤、完成定义、约束条件，甚至包括需要模型特别注意的坑。Codex CLI 在开始干活前会先加载这些技能定义，然后以它为蓝本去执行。

这个设计对实际工作流的影响非常明显。拿我手头的一个 Java 多模块 Maven 项目举例：以前让 Codex 新增一个接口，它只知道写一个 controller 类，但不会主动去更新 OpenAPI 文档、不会按照我们团队的命名规范创建 DTO、也不会追加数据库迁移脚本。我用 Superpowers 定义了一个"新增后端 API"技能之后，执行结果变成了完整的可交付变更集——所有相关文件一次到位，连 changelog 都生成了。

它适合的人群也比较好判断：如果你已经在用 Codex CLI，并且感觉"每次都要重复解释很烦"；如果你带着团队一起用 AI 编程，想统一工作流而不是靠每个人的临场发挥；如果你想给 Java、Go、Python 等项目定制符合自身技术栈的执行规范，那 Superpowers 这套思路就是为你准备的。

2. 安装与初始配置：30 分钟跑通第一个技能

2.1 环境准备与安装步骤

Superpowers 对基础环境的要求不高，我实测下来就三点：能正常运行的 Codex CLI、Node.js 环境（v18 以上）、以及 Git。它本身不是一个大平台，更像是一个技能包的渲染和执行引擎，所以在安装上是比较轻的。

我当时的操作步骤很简单：

# 第一步：全局安装 superpowers 命令行工具 npm install -g @superpowers/cli # 第二步：在需要启用技能的项目目录里初始化 cd your-project-dir superpowers init # 第三步：确认 Codex CLI 能识别到新配置 codex --version superpowers status

第一次执行superpowers init的时候，它会往项目目录写入一个.superpowers文件夹和对应的配置文件。这一步做的事情实际上是把技能运行环境挂到当前项目上，让 Codex CLI 在启动对话时能够自动感知这些技能的存在。

提示：如果你是在公司的存量仓库里初始化，建议先把.superpowers加进.gitignore再看团队意见，有些团队希望技能配置入库共享，有些则只希望留在个人环境里。这个判断标准和.vscode目录类似，先统一好口径再操作，避免后面产生噪音提交。

2.2 第一次启动：技能目录去哪了

安装完成后第一件事，我建议先运行superpowers status，它会给出当前项目的技能加载情况。正常状态下你会看到两类路径：

• 全局技能目录：放在用户主目录下，一般是~/.superpowers/skills，放一些跨项目复用的通用技能，比如"编写高质量的 commit message""生成变更日志""代码走查"这类谁也不挑项目的技能。
• 项目技能目录：放在.superpowers/skills下，存放和当前仓库强相关的技能，比如"新增 Java Service 接口""导出前端 API 类型定义"这种高度绑定当前业务规范的技能。

我第一次用的时候没搞清楚这个区分，把项目相关的技能直接丢到了全局目录里，结果到了新机器上发现技能列表很全，但项目里的技能却一个都没加载。调整之后，规则就清晰了：通用能力走全局，业务规范走项目。全局技能可以随着你换项目一直带着走，项目技能则跟仓库一起走。这个分离还有一个好处，就是团队评审技能变更时，只需要看项目目录里的那部分 diff，不会混入个人偏好。

2.3 配置文件的几个重要参数

Superpowers 的配置文件是.superpowers/config.json，我打开看了一眼，里面有不少值得按需调整的项。我常用的几个：

{ "auto_load_skills": true, "default_context_depth": 20000, "skill_search_paths": [".superpowers/skills", "~/.superpowers/skills"], "codex_model_preference": "gpt-4o", "strict_mode": false }

auto_load_skills决定每次启动 Codex 对话时是否自动读取技能清单。我建议保持开启，否则你需要手动指定技能才会生效，这又回到老路上去了。default_context_depth是给技能文件内容设定一个最大注入长度，避免技能写得太多导致上下文被占满。我刚用的时候往里塞了几十个技能，结果模型每次都要读一遍，上下文很快就满了，后来把不相关的技能移出去，再把上下文深度压到 20000 token 左右，对话质量明显回升。codex_model_preference则是在技能里没有明确指定模型时，所有技能默认使用的模型。strict_mode开启后，技能执行过程中模型必须严格执行流程，不能自己"发挥"跳过步骤，这个在跑正式交付流程时比较有用。

2.4 验证技能是否被正确加载

配置这东西，光写不验是容易出事的。我的习惯是每次改完配置都跑一个快速验证：

superpowers list superpowers describe <技能名>

list会把当前环境里所有可用技能列出来，describe则显示某个技能的详细定义。这个环节特别适合检查技能文件编写时有没有语法问题。我遇到过好几次的情况是：技能 YAML 文件里某一行缩进错了，Superpowers 不会直接让 Codex 启动失败，但技能会静默加载失败。只有主动运行 describe，它才会提示解析错误在哪个文件的哪一行。这个"无声失败"的坑，后面这块我会专门再讲。

3. 技能体系的工作原理：从 Prompt 模板到可执行工作流

3.1 核心概念：技能、命令、工作流

Superpowers 的管理单位是"技能"，一个技能就是一个结构化的指令包。它和我以前随手写的 prompt 模板有本质区别：prompt 模板只是文本替换，而技能是一等公民，有元信息、有输入参数声明、有执行协议。

在我理解里，Superpowers 的技能模型由三部分组成：

• 技能定义：描述这个技能解决什么问题、在什么场景下触发、有哪些前置条件。
• 执行步骤：告诉模型应该按什么顺序完成哪些事，哪些步骤可以并行，哪些必须串行。
• 约束与验收标准：明确什么能做、什么不能做，以及任务结束前必须检查哪些内容。

这套东西最舒服的地方在于，它是写给模型读的，同时也是写给团队里的开发者读的。新人接手项目时，与其翻几个小时的 README，不如直接看对应技能的描述文件，能很直观地理解一个任务从开始到交付需要经过哪些环节。

我最初拿它做的事是写代码生成技能，比如"新增定时任务""新增数据库表并生成对应 Repository"。后来发现，流程管理类的技能价值更高，比如"发布前的检查清单"这种，它不写一行代码，但能把模型在真实项目中容易漏掉的环节全部守住。

3.2 技能文件写在哪里、怎么写

技能文件是有固定结构的。一个最小技能文件长这样：

--- name: generate-java-controller description: 为业务模块生成标准 REST Controller，包含参数校验与统一返回结构。 trigger: 当用户要求新增或修改 Controller 时使用此技能。 args: - name: entity_name description: 实体类名，例如 User required: true steps: - 根据实体类名列出需要生成的字段。 - 生成 Controller 类，使用项目统一的 ResponseBody 包装。 - 生成参数校验注解，并统一异常处理。 - 检查生成的类是否符合公司规范中的命名约定。 verify: - 所有新增文件能通过编译。 - 不使用项目中不存在的依赖。

这段结构实际上就是在教模型"如何像一个熟悉这个项目的工程师一样干活"。它明确告诉模型什么时候触发、要提供什么参数、按什么顺序做、最后检查什么。和纯自然语言 prompt 相比，它的信息密度高得多，而且执行效果稳定得多。

如果技能逻辑比较复杂，我推荐把描述和实现分开：描述文件里只写核心步骤，实现细节放到同目录下的附属文件里，用references字段引用。这样平时让模型看技能描述就够用，需要深入时再去读参考文件。

3.3 官方技能包里有啥

Superpowers 官方自带了一批通用技能，覆盖的场景基本都是所有开发者都会遇到的日常工作。我实际用下来觉得最值钱的几个：

• commit-message-writer：根据当前 git diff 生成符合 Conventional Commits 规范的提交信息。它比我用过的所有 commit 工具好在会主动读 diff 内容并归纳类型，而不是只让你选一个 scope。
• code-reviewer：对指定范围的代码做走查，重点看正确性、安全隐患、可维护性，输出结论时不废话。我把这个技能结合 CI 使用，每次 MR 提交后让它先跑一遍，再人工复审，效率提高很多。
• test-case-generator：分析代码变更并生成对应单元测试。这个技能尤其在 Java 项目里好用，能根据 Spring 的注解自动识别 Mock 场景并生成测试骨架。
• changelog-updater：扫描变更文件并更新 CHANGELOG.md，免去手动整理的麻烦。

这些官方技能给我最大的启发是：它们都很克制，不会试图一次做完所有事情。每个技能只解决一个明确的子问题，这让调用时的行为可预期。我建议刚接触 Superpowers 时先不要急着自创技能，把官方技能用熟，理解它们的编写风格和粒度，再开始定制自己的。

4. 在 Java 项目里实战：从模板技能到自定义工作流

4.1 搭建基于 Maven 结构的 Java 技能环境

先给个上下文：我手头的服务是标准的多模块 Spring Boot Maven 工程，模块之间通过内部依赖共享接口定义。这类工程最麻烦的地方是，代码生成不能只在一个模块里闭门造车，往往还要同步改依赖模块、更新 API 定义、写兼容层。以前每天花在"机械劳动"上的时间很多，而 Superpowers 正好可以把这一整串动作固化下来。

superpowers init --java-maven

这个命令会按 Maven 项目惯例生成技能骨架，包括技能目录分层的建议、常见 Java 代码生成技能的模板，以及和mvn compile联动的验证脚本示例。后面如果要在团队里推广，这个骨架可以直接入库，作为统一的初始配置。

我实际用下来的体会是，JVM 生态的检查工具链特别适合和技能结合。Superpowers 可以调用任意的 Shell 命令，所以技能步骤里可以写：

steps: - name: 生成单元测试 command: mvn -pl ${module} -Dtest=${testClass} test

把构建命令内嵌进技能的好处是，模型在执行到这一步时必须真实运行一次验证，而不是嘴上说"应该能编译"。

4.2 自定义一个"新增后端 API"技能

我在团队里第一个打磨成熟的自定义技能长这样，这里分享一个简化的版本：

--- name: add-rest-api description: 新增一个完整 REST API，包括 Controller、Service、Mapper 接口、MyBatis XML、OpenAPI 注解以及对应测试。 trigger: 用户请求新增一个后端接口，或要求对现有模块增加资源。 args: - name: resource_name description: 资源名称，例如 order required: true - name: operations description: 需要支持的 CRUD 操作列表，例如 create,read,update,delete destination: src/main/java/com/example/module steps: - 在指定模块下新建 Controller 文件，路径按模块分包规则生成。 - 同步创建 Service 接口与实现类，事务注解统一使用当前项目版本。 - 创建 VO/Query 参数类，沿用已有的 BaseQuery 和统一响应体。 - 检查是否已有对应表的 Mapper 接口，存在则补充方法，不存在则创建并注册在 MyBatis 配置里。 - 在 Mapper XML 中生成对应 SQL，SQL 使用命名参数，禁止使用字符串拼接。 - 在 API 文档注解中补充 post 或 get 的摘要信息，URL 按 RESTful 风格命名。 verify: - cd ${project_root} && mvn -q -pl ${module} -am compile - 确认没有引入未在 pom.xml 中声明的依赖。

这段技能用了几个我认为很关键的技巧。destination字段让模型不用再瞎猜文件应该放哪；每个步骤的描述都在缩小模型的搜索空间，避免它"自由发挥"出团队规范之外的结构；最后两个 verify 步骤则是把质量关。实战中，这个技能生成的代码不说 100% 完美，但风格统一程度已经接近一个熟练的初级工程师写出来的水平。

4.3 构建一个"跨模块变更"组合技能

单接口技能只是第一层。更妙的是，Superpowers 允许一个技能调用其他技能，也就是把多个技能组合成一个更大的工作流。

--- name: add-order-feature description: 新增订单相关功能，包含 API 新增、数据库表变更与文档更新。 steps: - skill: add-rest-api args: resource_name: order - skill: add-database-migration args: table_name: "order" - skill: update-openapi-doc - skill: changelog-updater verify: - mvn -q test

这个"组合"模式是我推荐所有团队都去试试的方向。因为单个技能的诉求是聚焦，组合技能的诉求才是覆盖完整业务流程。通过把技能当作积木，团队可以在约定统一的前提下灵活搭出不同粒度的自动化流水线。

4.4 编写技能时的语法细节与缩进陷阱

在 Java 项目里跑了段时间，我对技能文件的编写有几个比较深的体会。

缩进是本框架里最容易踩的坑。Superpowers 的技能定义支持 YAML 和 Markdown 前置元数据格式，如果你用 YAML，就必须严格遵守缩进规则。我曾经把一个步骤列表写成了普通段落，缩进差了两个空格，结果模型一直把步骤描述当成正文读，执行的时候完全没有步骤概念，输出质量和一段普通 prompt 没区别。排查了半天才发现是语法问题。

第二个坑是步骤过于抽象。写技能时，我一开始犯的错是像写文章一样描述步骤，比如"优化代码质量"这种话。模型确实会响应，但响应方式是千奇百怪的。后来我把所有步骤都改成可验证、可量化的描述，比如"移除非空判断的冗余逻辑，并重新运行 findbugs 检查"。步骤描述越接近验收标准，执行就越稳定。

第三个心得是把执行命令写进技能。像 Java 项目的编译、测试、打包都有固定的 mvn 命令，提前写进技能步骤里，模型执行任务后就会自动跑验证。这一步极大减少了我人工回头检查的时间。

5. 常见问题与排查技巧实录

5.1 技能静默加载失败的排查

这是我碰到的第一个诡异问题：配置文件没错，目录也存在，但superpowers list里就是看不到某个技能。后来我发现，问题出在技能文件的文件头结构不完整。Superpowers 加载技能时会做严格解析，如果声明块缺字段，比如漏掉name或者description，它不会弹错误，而是直接跳过。

排查口诀：列表缺技能，先看文件头，再看缩进，最后看编码。编码问题主要发生在 Windows 环境下，文件如果是带 BOM 的 UTF-8，解析器可能直接读不出内容。我把项目的技能文件全部统一成 UTF-8 无 BOM 之后，这类问题就绝迹了。

5.2 模型不按技能步骤执行怎么办

技能文件写得再清楚，模型还是可能跳过步骤，尤其在没有开启严格模式的时候。我看过模型"自作聪明"地把两个步骤合并了，步骤数量看起来变少，但这其实违背了技能设计时对流程的控制意图。

我的经验有两个层面。第一，开启strict_mode，它在执行层约束模型按步骤执行，实质上是把步骤列表作为更硬的约束传给模型。第二，技能设计上要给步骤之间设置依赖钩子，比如"上一步生成的实体类名要在下一步中使用"，让步骤之间的衔接有信息传递，模型想跳也跳不过去。

还有一个辅助手段：在技能里加上一段"禁止"声明，明确写出什么不能做。比如对 Java 项目我可以写"禁止在 Controller 中直接操作数据库""禁止修改 pom.xml 中未提及的依赖版本"，这些负面约束对模型执行行为的矫正效果非常显著。

5.3 技能上下文占用太高怎么办

技能用多了，尤其是项目技能和全局技能同时加载时，上下文会迅速膨胀。我的 Codex 会话有时刚开始就只剩很少的上下文给实际任务对话，问题就出在技能加载太多了。解决方式也很直接：控制加载技能的数量和大小。auto_load_skills开启的情况下，我建议保持项目技能在 10 个以内，全局技能在 5 个以内，每个技能的描述文件控制在 40 行以内。更详细的内容放附属文件，等需要时再让模型去读取。

5.4 Java 项目里的编译验证卡死

技能里如果写了mvn compile，模型会在环境里真实执行这个命令。但 Maven 编译有时比较慢，长时间看不到返回时，模型可能会误判为失败，自己在那里反复重试甚至改代码来"修复"根本不存在的编译错误。我遇到过它把好好的 pom.xml 改了几行导致后续构建失败的问题。

解决思路是给技能里的命令加上超时和最小化范围。比如验证某个模块的编译时，不要用全量构建，而是：

mvn -q -pl ${module} -am compile -DskipTests -o

离线模式减少网络等待，限定模块范围减少无关代码干扰。这一步在配置 CI 库比较大的单体仓库时尤其重要。

6. 扩充技能库的常见模式

6.1 个人使用时的技能沉淀路径

我一直认为，技能体系最有价值的地方不在于"现成能用"，而在于它能作为个人和团队的经验沉淀载体。以前我解决一个问题之后，经验就留在大脑里，换台电脑就没了。现在我会在解决完一个相对复杂的任务后，把任务的处理过程复盘并抽象成一个技能文件，放进项目或全局技能目录里。

一个典型个人技能沉淀场景：团队要把一批老接口从 HTTP 迁移到 gRPC，迁移逻辑比较复杂，包含字段类型映射、方法命名规则、错误码处理方式。跑完第一个迁移后，我把整个流程整理成技能文件，之后迁移后续接口时就只是调用技能、提供接口名，生成结果的质量基本稳定。这个思路用一句话总结就是：凡是固定流程，皆可沉淀为技能。

6.2 团队协作时的技能评审与版本管理

当技能文件纳入 Git 版本管理后，它的定位就不仅是个人效率工具，而是团队工作规范的资产。我的建议是给技能文件单独开目录，并在 MR 审核时检查技能变更，因为技能直接影响模型行为，它和依赖版本变更同等重要。

我们团队目前的运作模式是：技能文件存在项目根目录.superpowers/skills，变更者必须更新技能描述和示例，评审者重点确认步骤是否和团队实际流程一致、步骤是否可验证、有没有过于宽松的描述。一旦技能合入主干，后续所有使用 Codex 的成员在本地拉取后就会自动使用新技能。这个机制对团队统一代码风格非常有效。

6.3 与 CI 流程结合的进阶玩法

Superpowers 本身是命令行工具，所以它的技能还可以在 CI 里调用。我现在已经在团队 CI 的"代码扫描"阶段接了一个 code-review 技能，每次 MR 触发时在代码扫描容器里调用 Codex CLI 做一轮 AI 走查，把结果作为参考评论打到 MR 上，再由开发人员确认。这个用法把技能从"本地对话助手"变成了"自动化流水线组件"，适用场景一下子扩大了很多。

如果要在 CI 里稳定使用，建议给技能执行写一个独立的配置文件，把模型、上下文大小、超时时间都固定下来，避免依赖个人本地环境。CI 场景下稳定性优先级高于灵活性。

7. 几个值得一开始就养成的习惯

用 Superpowers 这段时间，我总结出几个特别建议新手上路时就注意的习惯，能少踩很多坑。

第一个是从最小技能开始写。不要一上来就造一个 50 行的大技能，先写一个 10 行左右、只做一件事的技能，跑通之后再加步骤。因为技能排错本身是有成本的，最小化技能能让你快速验证目录、加载、执行链路是否通畅。

第二个是把技能描述当成代码来写。技能文件会受到同行评审，会被版本管理，会随着时间演化。给它写清晰的描述、说明触发条件、标注已知边界，这都是代码工程的基本功，技能文件同样需要。

第三个是定期做技能"瘦身"。技能文件很容易变得臃肿。每隔一段时间，我会把技能列表拉出来，看看哪些技能已经有段时间没被调用了。长期不用的技能可以归档而不是直接删除，以防后续复用。

第四个是主动查看技能的加载日志。运行时用superpowers log查看技能加载情况是个好习惯。我这里遇到过一次时间戳异常导致的缓存失效问题，技能文件改了但加载的还是旧版本，排查了很久才发现是缓存键没更新。后来每改完技能文件我都会强制刷新缓存再验证，这个问题就再也没有出现过。

8. 关于扩展方向的一些思考

Superpowers 让我重新思考了 AI 编程工具的使用方式。以前我在意提示词怎么写才让模型理解，现在我更在意怎么把一次正确的执行过程固定下来，让它反复发生。前者是对话技巧，后者是工程方法。

现在我在团队里推了一个模式：每个新任务到手上，先想清楚这属于"一次性的探索任务"还是"可复用的常规任务"。前者就直接对话，后者就先去查有没有对应技能，没有就先写一个。长期坚持下来，常规任务的执行质量越来越稳定，团队的效率随着技能库的丰富呈现非线性增长。

Java 技术栈尤其适合这套玩法。Java 工程类型化强、目录结构规范、构建链路明确，本来就有很多规则可以固定下来。MyBatis、Spring 的套路化代码用技能生成，配合 Maven 验证，能实现很多以前需要人工盯着的环节全自动化。我也看到社区里已经有不少人把这些技能打包成公共库，直接按需装进自己的环境。

我个人的体会是，Superpowers 这类工具的价值不是让你的 AI 助手更"聪明"，而是让你和团队的工程规范更容易被 AI 遵守。工具会迭代，模型会换代，但一套经过实战锤炼的技能库，会像一个越用越厚的方法论手册，持续为整个团队创造价值。如果你和我一样已经把 AI 编程当成了日常开发基础设施，我建议花一个下午把技能体系装起来，再挑一个你自己最烦的重复性工作写成技能，实测跑通之后，应该很快就能感受到这套思路带来的变化。