Superpowers框架：为Codex CLI打造的AI编程技能包
1. 什么是Superpowers：不是游戏，是给AI编程代理的"技能包"
我第一次听到"superpowers"这个词，是在同事分享的一个GitHub仓库里。那会我正被Codex CLI气得不轻——让它写个接口，它直接写了三百行代码，既没看项目结构，也没跑测试，改了一下午需求，最后连编译都过不去。同事说你试试这个：一个叫superpowers的框架，专门给AI代理用的。我以为是游戏里的超能力插件，结果打开一看，是一堆Markdown文件，心里还想这能管用？
事实证明，能管用。它不仅管用，还彻底改变了我用AI编程的方式。
简单说，Superpowers是一个面向AI编程代理（比如Codex CLI、Claude Code这类工具）的"技能框架"。它的核心思路非常朴素：不要指望AI每次都能从零开始聪明地干活，而是把资深工程师的工作方法——规划、拆解、调试、测试、重构——固化成一组组可复用的"技能"文件。AI在执行任务前，会先读取这些技能文件，按照里面定义的步骤、检查清单、决策条件去操作。相当于你给AI配备了一套标准作业程序，而不是一句"你去搞定它"。
为什么要这么做？因为现在的AI代理虽然语言能力强，但"工程素养"极低。它不知道什么时候该停下来问需求，不知道写完代码应当先编译再自测，也不知道如何在一个陌生的代码库里定位问题。Superpowers把这些过程变成显式的协议，让AI从"聪明的新手"变成"流程化的老手"。
这套框架最核心的几个概念，我先用大白话讲清楚：
- 技能（Skill）：一个包含目的说明、使用条件、详细步骤、检查清单的Markdown文件（或目录）。每个技能解决一类问题，比如"制定实施计划"、"调试失败的测试"、"做代码审查"。
- 工作流（Workflow）：多个技能按照某种顺序组合起来，形成从需求到交付的完整流程。比如先"理解需求"，再"规划方案"，然后"实施变更"，最后"验证测试"。
- 协议（Protocol）：技能内部定义的行为准则。比如"调试时必须先重现问题，再猜测根因，每次只改一处，改完立即验证"。
- 检查清单（Checklist）：每完成一步就核对一遍的列表。这是确保AI不偷懒、不跳步的关键。
你可能会想，这不就是更好的提示词吗？对，但它比提示词强在三个地方：
- 模块化：技能可以像积木一样自由组合，而不是每次都把一大段提示词塞进对话里。
- 可迭代：你觉得某个技能的步骤不够好，直接改Markdown文件，立刻生效，不用重新训练任何模型。
- 团队共享：整个技能库就是一个Git仓库，可以多人协作维护。团队的工程方法论沉淀在代码库里，而不是存在某个人的脑子里。
热词里有个"codex superpowers"，说的就是专门为OpenAI Codex CLI适配的这个框架版本。Codex是OpenAI推出的命令行编程代理，而Superpowers相当于是给Codex装上了"职业插件"，让它从"会聊代码"变成"会做工程"。
这个项目目前是开源的，托管在GitHub上，主要面向使用Codex CLI、Claude Code等终端型AI代理的开发者。我的使用环境是macOS + Codex CLI 0.x，下面所有操作都是基于这个环境演示的。Windows用户注意路径和命令行工具的差异，但核心逻辑完全一样。
2. 安装Superpowers之前，先搞懂它的目录结构
2.1 它到底装到哪里
Superpowers不是一个需要编译的库，也不是一个常驻后台的服务，它就是一个目录，里面全是Markdown和JSON文件。安装的本质，是把这个目录下载到你本机，然后在Codex的配置文件里告诉它"技能仓库在这里"。
从GitHub上克隆下来的默认仓库，顶层结构大概是这样：
superpowers/ ├── README.md ├── SKILLS.md # 技能清单索引，Codex启动时读取它来了解有哪些技能 ├── commands/ # 自定义斜杠命令，比如 /superpowers ├── skills/ │ ├── plan/ │ ├── implement/ │ ├── debug/ │ ├── test/ │ ├── code-review/ │ └── ... └── workflows/ ├── feature-workflow.md └── fix-bug-workflow.mdSKILLS.md是关键。Codex每次会话开始时，会读取这个文件，相当于给AI一份"菜单"，告诉它当前系统里有哪些技能可用，每个技能是干什么的、什么时候该用。如果你的技能没被这个文件索引到，AI根本不知道有这个东西存在。
2.2 安装前需要准备什么
虽然严格来说Superpowers只依赖一个会读Markdown的AI代理，但实际使用中，我建议至少满足这几个条件：
- Codex CLI已安装并可用：我用的是
npm install -g @openai/codex装的版本，确保codex命令能正常执行。不同小版本对Superpowers的配置项略有差异，如果你用的版本很新，留意官方仓库的配置变更说明。 - Node.js 18+：Codex CLI本身是Node写的，而且部分技能里会调用node脚本做文件操作。
- 一个Git客户端：因为技能库本身就是Git仓库，你肯定要拉取和更新。
- 已配置好OpenAI API访问或Codex订阅：这个就不用多说了，没有模型后端，技能包再强也只是空壳。
一个很常见的坑：很多人以为装了Superpowers就等于给Codex加了某种"外挂模型"，不用付费了。不是的。它只是优化了AI的思考和行动流程，底层依然调用Codex的模型能力。你该花的token一分不少，只是花得更值了。
2.3 三步完成核心安装
我用的是最直接的"克隆到Codex配置目录"方案。Codex CLI在用户主目录下会生成一个.codex文件夹，里面有config.toml（或config.json，取决于版本）和settings.json。我以较新的settings.json配置为例。
第一步，克隆仓库到本地：
git clone https://github.com/obra/superpowers.git ~/.codex/superpowers如果你的.codex目录还不存在，Codex会在首次运行时创建它。克隆下来之后，先别急着配置，进去看一眼：
ls ~/.codex/superpowers确认里面有SKILLS.md和skills/目录，说明下载完整。
第二步，在Codex配置文件里指定技能库路径。找到~/.codex/settings.json（没有就手动建一个），加入这样一段：
{ "experimental": { "superpowers": { "enabled": true, "path": "/Users/你的用户名/.codex/superpowers" } } }注意path一定要写绝对路径。我一开始用了~/.codex/superpowers，Codex不解析波浪号，导致一直加载失败。改成/Users/xxx/...就正常了。
第三步，重启Codex CLI，随便开个新会话，输入：
/superpowers如果返回了技能列表，说明加载成功。如果提示"未知的命令"，检查两个地方：一是配置文件里的enabled是否真的为true；二是Codex CLI版本是否太旧，太旧版本不支持/superpowers命令，需要升级。
这套流程整个跑下来，顺利的话五分钟不到。但要注意，Superpowers项目迭代很快，主分支经常更新。我建议你把它当作一个普通Git仓库来维护，每隔一两周git pull一次，保持技能和工具链的同步更新。
3. 核心用法：怎么让Codex真正"使用"技能包
3.1 两种触发方式：显式指令与隐式引导
安装好之后，最经典的使用场景是这样的：你给Codex一个需求，比如"帮我看看这个项目的测试为什么挂了一个"。如果没有Superpowers，Codex大概率会直接打开测试文件，凭感觉改几行，然后说"应该好了"——它根本不会去跑一次完整测试来验证。有了Superpowers，你可以让它"使用debugging技能"来处理，它就会严格按照技能里定义的流程走：先复现失败，再查看相关代码，提出假设，逐个验证，修改后重新跑测试，最后给你一份根因分析。
我给你两个实际可用的触发方式。
方式一：显式指令。直接在对话里点明技能名称，比如：
使用debugging技能，帮我看一下
OrderServiceTest为什么编译失败。
这种方式最可靠，前提是你知道当前有哪些技能可用。不确定的话先输入/superpowers查看索引。
方式二：隐式引导。不说技能名，但描述场景让Codex自己根据技能描述匹配。比如：
我准备改
PaymentService里的支付逻辑，请走标准流程。
这里的"标准流程"会触发implement或feature-workflow。但注意，隐式触发能不能生效，取决于SKILLS.md里技能描述写得好不好。如果描述太泛，AI可能匹配不上，所以前期建议多用显式指令，用熟了再玩花的。
3.2 技能之间如何串联：工作流实例
单技能是"点"，工作流才是"线"。Superpowers默认提供了一些成型的Workflow，典型的特性开发流程是这样的：
- 理解需求：
explain-request技能，要求AI复述需求、列出假设、识别歧义，并给出待确认问题。 - 调研代码：
research技能，让AI基于代码库搜索相关实现，标记出可能受影响区域。 - 制定计划：
plan技能，把任务拆成若干个小步骤，每一步写明目标、涉及文件、验收标准。 - 实施变更：
implement技能，按计划逐项修改，每完成一项就在todo列表里勾掉。 - 自动化测试：
test技能，根据变更内容补充或调整单元测试，并执行测试套件。 - 代码审查：
code-review技能，以审查者视角重新审视diff，寻找逻辑漏洞、边界条件、安全隐患。
当整个工作流走完，AI已经不是一个"给你一段代码"的生成器，而是扮演了一个完整开发团队的多个角色。我在实际项目中用下来，最大的感受是：同样一个需求，正常直接让Codex做，经常要来回改四五轮；走一遍Superpowers工作流，通常一轮就能给出可合并的代码。代价是多消耗一些token和时间，但相比返工，这笔账非常划算。
3.3 技能加载的上下文机制
这里有个容易被忽略的技术细节：技能不是一开始就全部塞进对话上下文里的，那样token会爆炸。Codex在需要时才会根据SKILLS.md的索引，动态读取某个技能文件的完整内容，作为临时的"系统提示"加入上下文。
这个设计很聪明，也带来了一个使用上的要点：你千万别在同一会话里同时让AI处理好几个毫不相关的技能。比如一边让它用debugging修bug，一边让它用plan做远期规划——AI每加载一个技能，都会把那个技能的完整步骤塞进上下文，加载多了，后面的对话质量会被无关内容干扰。一次只专注于一个技能或一个工作流，效果最好。
3.4 自定义技能：把团队规范写进AI流程里
Superpowers最吸引我的点，是自定义技能异常容易。我在团队里推行过一段代码规范，不管是人还是AI都遵守。做法很简单，在skills/下新建一个目录，比如skills/git-commit，里面放一个SKILL.md文件即可。
这个文件的结构长这样：
--- name: git-commit description: 根据Git变更生成符合团队规范的提交信息。当需要创建commit时使用。 --- ## 步骤 1. 运行 `git diff` 查看当前变更内容。 2. 识别变更类型：feat, fix, refactor, docs, test。 3. 提交信息的首行不超过72个字符，动词用祈使句，例如"Add xxx"。 4. 如果有破坏性变更，在正文里以 `BREAKING CHANGE:` 开头说明。 ## 检查清单 - [ ] 提交信息里是否包含变更的核心目的？ - [ ] 是否避免使用'update'、'fix stuff'这类模糊描述？ - [ ] 是否将关联issue编号写在了正文？然后记得在根目录的SKILLS.md里加一行链接介绍它。保存后重启Codex，新技能马上生效。这个机制对于团队来说，等于把代码规范、测试策略、安全要求都做成了"可执行的文档"，AI只能遵从，全靠自觉的人类同事还靠谱点。
4. 在Java项目中实战Superpowers的体验与配置
4.1 为什么Java项目尤其需要这套流程
热词里有"superpowers java"，我猜很多人是在Java项目里用Codex遇到了一堆问题。这我太有体会了。Java项目相比Python、JavaScript有几个天然的"AI不友好"特征：
- 模块边界强：Maven或Gradle的多模块工程，类之间依赖关系复杂，AI经常改了一个模块，却不知道另一个模块编译失败。
- 构建工具链重：编译、测试、打包都需要调用Maven或Gradle，AI如果直接执行命令，第一次跑通常就是慢，第二次跑就是各种环境问题。
- 类型系统严格：Java泛型、受检异常、方法签名，AI生成的代码稍有疏忽就是一片红色编译错误。
- 框架隐式约定多：Spring Boot的自动配置、注解扫描、事务机制，AI在不了解整个上下文时，很容易写出"看似合理但跑不起来"的代码。
所以Java开发者用Codex，最需要的不是让它"写代码"，而是让它"在理解工程结构的前提下，按部就班地改代码"。Superpowers的plan、implement、test、debug技能组合起来，刚好能覆盖这些诉求。
4.2 为Java项目定制一个"骨架理解"技能
为了让AI在进入某个Java项目时快速建立正确的上下文，我写了一个自定义技能java-project-context。它会先让AI执行一系列命令，把项目的骨架和关键配置摸清楚，再决定后续操作。
技能文件放在skills/java-project-context/SKILL.md，核心步骤是这样的：
--- name: java-project-context description: 在任何Java项目中的编码或调试之前使用，用于建立项目结构、构建工具和依赖上下文。 --- ## 步骤 1. 探测构建工具。检查项目根目录是否有 `pom.xml`、`build.gradle`、`build.gradle.kts` 或 `settings.gradle`，确认是Maven还是Gradle项目。 2. 如果是Maven项目，运行 `mvn -q help:evaluate -Dexpression=project.build.sourceEncoding -DforceStdout` 查看项目编码，并读取根`pom.xml`中的 `<modules>` 了解模块结构。 3. 如果是Gradle项目，运行 `./gradlew projects` 查看子项目列表。 4. 搜索所有包含`@SpringBootApplication`的类，定位启动入口。 5. 查看 `src/main/resources/application.yml` 或 `application.properties`，记录已激活的profile和关键配置项。 6. 查看 `src/test` 目录，确认测试框架是JUnit 4还是JUnit 5，以及是否有Testcontainers依赖。 7. 将以上信息汇总，用简洁列表输出。 ## 检查清单 - [ ] 是否已确认构建工具？ - [ ] 是否已列出所有模块？ - [ ] 是否已找到启动类和配置？ - [ ] 是否已确认测试框架？在会话里这样用：
请使用java-project-context技能，然后帮我定位一下登录接口为什么返回500。
AI会先老老实实摸一遍项目，再开始排查。这一步看起来是浪费时间，反而能省下后面好几轮无头苍蝇式的尝试。实测下来，尤其是大型Spring Boot多模块项目，省的不只是时间，还有你的耐心。
4.3 Java环境下的常用命令注意事项
Superpowers的技能文件里，默认的test技能会优先执行npm test或pytest这类命令，但它不会自动识别Java项目。所以当你在Java项目里让AI运行测试时，它可能会卡在"找不到测试命令"这一步。
我的解决方法是主动在对话里给出明确指令：
使用test技能，运行
mvn test -Dtest=OrderServiceTest来执行指定的单元测试。
这样AI就会把技能流程套用在Maven命令上，该检查的检查、该验证的验证，比单纯让它"跑一下测试"靠谱得多。
另外，Java项目里有个环境坑：JAVA_HOME没配好，AI执行mvn命令时会报错。你可以在技能步骤里加一条："如果命令执行失败，运行echo $JAVA_HOME检查环境变量，并检查java -version是否可用。" 这属于真实场景下的经验补充，建议大家在自定义技能时多加这类容错逻辑。
4.4 调试技能在Java异常堆栈上的特殊用法
Java应用报错，最常见的不是逻辑错误，而是异常传播链太长。比如一个Controller层报NPE，根因可能在Service层，甚至在某次Mapper调用里。如果用普通的debugging技能，AI可能会盯着堆栈最顶部看半天，改来改去还是NPE。
我自己的经验是，在给AI的调试指令里，额外要求它"沿堆栈向下追踪三层"，并且关注Caused by段。Superpowers的debug技能里其实有类似的"检查异常链"步骤，但它不会主动做，除非你通过对话强化。你可以说：
使用debugging技能，重点分析Caused by信息，从最底层的根因开始修，而不是改最外层的报错点。
这样调整之后，AI处理Java异常的能力会提升一个档次。说到底，技能给的是流程框架，但有经验的判断还是得靠你喂给AI的线索来引导。
5. 常见安装与使用问题：我把踩过的坑都列在这里
5.1 技能加载了但AI不调用，怎么办
这是入门者问得最多的一个问题。明明安装了Superpowers，/superpowers也能列出技能，但跟Codex对话时，它压根不提什么技能，直接给答案。
原因很简单：AI默认认为用户只是想聊天，不需要走大流程。你要么显式点名技能，要么在会话开始时用一句"启动标准工作流"给它一个强信号。我见过更聪明的一种做法，是在Codex的系统提示词里追加一句："每当面对需要多步骤解决的软件工程任务时，应先查询superpowers技能清单并选择合适技能。"这句话可以放在Codex的AGENTS.md文件里，让每个会话自动带上这个指令。
5.2 技能文件写错了，AI照着废流程跑
自定义技能时，最容易出错的是YAML frontmatter。name和description是必填的，其他字段随意，但description一定不能太短。得有场景描述和触发条件，比如"当需要xxx时使用"，这样AI才能正确判断何时加载。
如果技能文件格式有错，Codex通常不会报错，而是直接忽略这个技能。排查方法是给技能文件起个怪异名字，比如zz-test-skill，然后问AI"当前有哪些zz开头的技能？"——如果它能答上来，说明加载没问题；如果答不上来，就是文件头有问题或没被SKILLS.md索引。
5.3 更新后技能库与Codex版本不兼容
Superpowers迭代快，有时一个git pull就把之前用的技能改得面目全非。我遇到过最惨的一次是，更新后/superpowers命令直接消失，原因是新版要求Codex CLI必须用config.toml配置，而我还在用旧的settings.json。
遇到这类情况，我的建议是先看GitHub仓库的README和releases说明，而不是盲目改配置。通常上游会写清楚"请升级到Codex 0.2.1以上"或"需要将配置迁移为XX格式"。然后对照自己的安装方式重新配置一遍。好在Superpowers本身的配置项不多，问题大不了就是重新指定一下路径。
5.4 用起来太慢、token消耗太大
Superpowers的工作流确实比直接对话慢、费token。一次完整的plan + implement + test，可能消耗普通对话三到五倍的token。但价值在于减少返工。如果你的任务是"临时查个函数用法"、"改个文案"，完全没必要启用技能——直接问就行。投身到中大型需求时，才值得走全套流程。
我还想提供一个折中方案：会话开始时只加载plan技能，让AI先出一个方案给你看，确认后再加载implement和test。这样能避免AI在错误方向上浪费大量token。说白了，技能是工具，什么时候用、用多重的工具，得靠人判断。
5.5 多语言环境下的技能冲突
一个项目里同时有Java、Python、前端代码很常见。Superpowers的通用技能（比如debug）是跨语言的，但有些技能会带着特定的语言倾向。例如test技能默认写的是"运行项目现有测试命令"，到了Java项目就不好使。
解决办法还是靠自定义技能。我给技术栈混合的项目写了一个stack-aware-skill，第一步就是检测当前目录的语言构成，然后动态选择对应的构建工具和测试命令。这样AI无论碰到哪种文件，都能找到对的执行方式。这个思路也挺适合接手一个不熟悉的代码仓库时用——先让AI"认识"这个项目，再谈改代码。
6. 我的使用心得：这些技巧值得反复练习
用了Superpowers大约两个月，从最初的好奇、踩坑，到现在已经成为我日常使用Codex CLI的标配，这里分享几个我认为最有价值的经验。
第一，善用"计划技能"拦住AI的手。默认情况下，AI特别爱直奔主题写代码。但一旦我明确说"先使用plan技能，不要写代码"，它就会乖乖地输出分步骤计划。我在Code review时，特别看重这个计划步骤。计划里的每一步都写清楚涉及哪个文件、要做怎样的改动，让我能在AI动手之前就发现设计方向的偏颇。这比让AI把错误代码写出来再返工要节省太多时间。
第二，把团队规范写成技能，比写在文档里管用一百倍。我团队有一套Git提交规范、数据库迁移规范、接口错误码规范。以前写在Notion里，基本没人看，AI更不会看。后来我把它们全部改写成Superpowers技能，在技能里写明"当进行数据库变更时必须运行mvn flyway:validate"，"当新增接口时必须增加对应错误码枚举"。这样AI在执行相关任务时，会自动把这些规范纳入流程，既能保证合规性，也减轻了人工审查负担。
第三，在AI的"技能组合拳"里加入人工确认节点。我不建议完全放手让AI自主跑完整个工作流。尤其在改动公共方法签名、数据库表结构、外部接口协议这些影响面大的环节，一定要在技能步骤里设计一个"暂停并等待用户确认"的节点。实现方法很简单：在技能步骤中写明"在修改核心接口前，输出改动方案并询问用户是否继续"。这样AI不会自顾自地改下去，而是先同步方案，等你点头再动手。这个人工节点的存在价值，远大于多消耗的那点token。
第四，Java项目里，让AI先用"java-project-context"技能跑一遍，再启动正式任务。很多Java开发者抱怨AI不懂Maven多模块结构，其实是他们省掉了这个"建立上下文"的步骤。你想想，一个刚入职的实习生，你都不指望他能立刻在巨大代码库里游刃有余，AI也一样。给它一点时间去摸清项目骨架，它后面的表现会完全不同。我现在任何Java项目的新会话，第一句永远是"使用java-project-context技能"。
第五，也是最重要的一条：管理好你的预期。Superpowers确实强大，但它不是魔法。它无法让AI理解你脑中的业务逻辑，无法替你做架构取舍，更无法为一个毫无上下文的需求凭空生成可维护的代码。它真正的价值，是把"AI能做的事"和"需要人判断的事"之间的边界变得更清晰——该让AI按流程执行的，就交给流程；该让人拍板的，技能设计里就留出人工确认的口子。我的个人感受是，与其说Superpowers赋予了AI超能力，不如说它给了我一套更好的与AI协作的脚手架。
最后再分享一个小技巧：把~/.codex/superpowers目录纳入你自己日常备份的范围，然后定期git pull上游更新，但不要轻易merge别人的自定义分支。技能库这个目录，本质上就是你团队的"可执行工程手册"，保持它的干净和稳定，比什么都重要。
