最近我开始把大量重复开发工作交给 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 中生成对应 SQLSQL 使用命名参数禁止使用字符串拼接。 - 在 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 编程当成了日常开发基础设施我建议花一个下午把技能体系装起来再挑一个你自己最烦的重复性工作写成技能实测跑通之后应该很快就能感受到这套思路带来的变化。 
长河君 · 2026/11/4 18:46:27 · 阅读 1.2k 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 中生成对应 SQLSQL 使用命名参数禁止使用字符串拼接。 - 在 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 编程当成了日常开发基础设施我建议花一个下午把技能体系装起来再挑一个你自己最烦的重复性工作写成技能实测跑通之后应该很快就能感受到这套思路带来的变化。