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 18Codex 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/superpowersCodex不解析波浪号导致一直加载失败。改成/Users/xxx/...就正常了。第三步重启Codex CLI随便开个新会话输入/superpowers如果返回了技能列表说明加载成功。如果提示未知的命令检查两个地方一是配置文件里的enabled是否真的为true二是Codex CLI版本是否太旧太旧版本不支持/superpowers命令需要升级。这套流程整个跑下来顺利的话五分钟不到。但要注意Superpowers项目迭代很快主分支经常更新。我建议你把它当作一个普通Git仓库来维护每隔一两周git pull一次保持技能和工具链的同步更新。3. 核心用法怎么让Codex真正使用技能包3.1 两种触发方式显式指令与隐式引导安装好之后最经典的使用场景是这样的你给Codex一个需求比如帮我看看这个项目的测试为什么挂了一个。如果没有SuperpowersCodex大概率会直接打开测试文件凭感觉改几行然后说应该好了——它根本不会去跑一次完整测试来验证。有了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或GradleAI如果直接执行命令第一次跑通常就是慢第二次跑就是各种环境问题。类型系统严格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 -Dexpressionproject.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 -DtestOrderServiceTest来执行指定的单元测试。这样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别人的自定义分支。技能库这个目录本质上就是你团队的可执行工程手册保持它的干净和稳定比什么都重要。