1. 从Codex CLI到superpowers为什么AI编程助手需要一个技能层如果你用过OpenAI的Codex CLI大概会有这样一种体验它确实能读懂仓库上下文能改代码、跑命令、提PR但用起来总感觉太被动了。你问一句它答一句你给一个任务它就机械地执行不会主动考虑项目的测试规范、代码风格、提交习惯更不会像资深工程师那样在动手前先规划好实现路径。我最早用Codex CLI时把它当成一个能读仓库的高级ChatGPT直到我遇到了superpowers。superpowers是给Codex CLI加装的一层技能系统。它不是独立的AI工具也不是IDE插件而是以Markdown文档、规则文件和会话变量为载体的增强框架。简单说它让Codex在每次会话开始时自动加载一组技能——比如测试驱动开发、代码审查、提交信息规范、重构流程——然后按照这些技能里定义的工作流去执行任务。装上之后Codex从你问它答变成了按行业最佳实践主动干活的形态。这个项目特别适合两类人。一类是被Codex CLI的裸奔状态困扰的开发者觉得每次都得手动在提示词里写请先写测试请遵循项目的提交规范写了一长串还是经常被忽略另一类是正在评估AI编程工具能否真正进入日常研发流程的团队负责人想知道除了聊天式补全CLI工具到底能不能承担端到端的工程任务。如果你之前用过Claude Code里的Skills功能再看superpowers会特别有亲切感——它本质上就是把类似的技能机制带到了Codex生态里。我自己是从一个Java后端项目的重构需求接触到superpowers的后面会专门讲这个场景。刚开始我也怀疑不就是一堆Markdown吗真能改变Codex的行为实际跑通之后我得说关键在于它把规则和工作流绑在了一起这在工程实践里是质的区别。下面我把安装、原理、实战和避坑完整走一遍。2. superpowers到底改了什么从会话级提示到项目级技能2.1 裸用Codex CLI的三个痛点先说清楚为什么需要superpowers。我用Codex CLI做了快两个月的小项目遇到的核心问题有三个。第一上下文注入靠手写提示词每次都重复劳动。比如我要求Codex在提交流程里先跑测试、再提交就得在每轮对话里重申这个要求一旦忘了这轮就回到裸奔状态。项目大了以后这种靠聊天上下文维持的约束几乎不可靠。第二项目规范散落在各处Codex读不完整。仓库里的README、CONTRIBUTING.md、CI脚本、代码风格配置Codex默认不会把它们全部识别为行为约束。它可能只知道这是Java项目但不知道我们要求每个新方法必须有单测不允许直接操作数据库连接。第三没有流程编排能力。真实开发不是生成一段代码这么简单而是先确认需求→再写测试→实现→跑构建→自查→提交。裸用Codex时它会把这一切压缩成一次生成跳过中间验证步骤产出质量很不稳定。2.2 superpowers的三大核心设计superpowers针对上面三个痛点做了三个对应的设计。第一个是技能Skills。每个技能是一个独立的Markdown文档包含标题、适用场景、具体步骤和示例。比如test-driven-development技能会告诉Codex先写失败测试→思考最小实现→运行测试→重构。Codex在会话开始时会读取技能列表把相关技能的内容放进自己的上下文窗口。从我的使用体验来看技能文档的信息密度和组织方式直接决定了Codex的执行质量这不是简单堆字数的提示词而是一套结构化的操作手册。第二个是规则文件AGENTS.md。这是Codex CLI原生支持的项目级指令文件superpowers在其中占据了一个特殊地位你能在项目根目录的AGENTS.md里引用superpowers的规则也可以把superpowers自身的规则文件作为全局配置。这样无论是新clone下来的项目还是日常开发的仓库Codex打开就能读到统一的技能规范。第三个是会话变量Session Variables。这是superpowers最有意思的部分。它允许在技能文档里使用{{VAR_NAME}}这样的占位符会话启动时自动替换成具体值。比如{{CODE_VERSION}}会替换为当前项目的语言或框架版本{{DEFAULT_SHELL}}替换为当前平台的Shell类型。这意味着同一份技能文档在Windows和macOS、在Java项目和Python项目里都能生成适配的执行命令。2.3 为什么技能文档比堆提示词有效我见过很多类似的提示词增强项目大多是在chatgpt系统提示里塞几百行规则。superpowers完全不是这个路子。它的技能文档是按需加载的Codex先读取技能清单根据当前任务只加载相关的技能详情。这就像你到了一个新团队不用先读完整个部门的SOP手册而是遇到什么问题翻什么手册——上下文窗口不浪费规则也更有针对性。而且技能是可以嵌套触发的。比如我常用的一个组合是plan技能定义总体流程里面的某个步骤会调用test-driven-development技能后者又依赖refactor技能。这种类似函数调用的机制让Codex具备了处理复杂任务的结构化能力。这一点在后面Java实战部分你会看得更清楚。3. 安装与初始配置从零到能跑通第一个技能3.1 环境准备与依赖版本在装superpowers之前先把基础环境确认好。我实测的推荐组合是组件建议版本说明Node.js18以上Codex CLI的运行时依赖20 LTS最稳Codex CLI0.20以上太老的版本不支持AGENTS.md的完整特性Git任意较新版本用于拉取superpowers仓库终端支持富文本推荐iTerm2、Windows Terminal或KonsoleCodex CLI的安装直接走npm就行命令是npm install -g openai/codex。装完先用codex --version验证一下。如果你的环境里同时有多个Codex版本我踩过全局和项目本地版本不一致的坑建议统一用全局版本避免后面superpowers加载规则时出现找到了文件但就是不生效的诡异问题。注意Codex CLI需要先登录OpenAI账号并配置好API密钥。superpowers本身不处理认证它只是在Codex之上做规则注入认证配置的优先级最高。3.2 获取superpowers并建立目录结构确认环境OK之后拉取superpowers仓库。我习惯把这类工具放在用户目录下的一个统一位置比如~/.codex/superpowers方便全局引用git clone https://github.com/obra/superpowers.git ~/.codex/superpowers拉下来之后目录里最重要的几个部分skills/所有技能文档的存放目录每个子目录是一个技能里面是SKILL.md文件。rules/全局规则文件比如AGENTS.md定义了Codex每次会话的行为约束。scripts/提供了一些辅助脚本用于技能安装、更新、状态检查。拿到仓库之后需要把superpowers接入Codex。核心操作是把superpowers的AGENTS.md链接到Codex的全局配置里。Codex读取项目级AGENTS.md的默认路径是你的工作目录但你可以通过环境变量让它在每次会话时都先读取superpowers的规则# 在 .zshrc 或 .bashrc 中追加 export CODEX_AGENTS_PATH$HOME/.codex/superpowers/rules/AGENTS.md:$HOME/.codex/AGENTS.md这样Codex每次启动时会把superpowers的规则作为优先级最高的指令载入。如果要细究原理Codex对AGENTS.md的加载路径是支持冒号分隔的列表的前面的配置优先级高于后面的。这个特性让superpowers能在不改动原有项目配置的前提下注入自己的规则。3.3 首次启动与技能加载验证配置好环境变量后在任意项目目录里执行codex进入交互模式然后问它一句当前加载了哪些可用的superpowers技能我第一次跑的时候Codex的回复是我检测到superpowers技能目录但技能清单尚未初始化。这说明规则链接已经生效技能清单需要额外初始化。初始化过程在superpowers设计里是自动完成的。当Codex会话启动并读取到规则文件时规则文件里会有一段加载技能清单的指令Codex会主动扫描skills/目录生成一份技能索引。这个过程可能需要几秒钟取决于技能数量和磁盘速度。完成后技能清单会缓存到~/.codex/superpowers_cache/下后续启动就直接读缓存了。如果Codex还是回答不知道有哪些技能可以手动触发一次扫描cd ~/.codex/superpowers ./scripts/manage_skills.sh list这个脚本会输出当前所有技能的名称和描述运行成功说明技能文件本身没问题。如果脚本也一片空白八成是skills目录路径出了问题检查一下仓库结构是否完整。3.4 给一个项目单独挂载技能集全局配置适合个人日常使用。但如果你在一个团队项目里想要给团队强制启用某些技能比如强制TDD、强制PR描述规范更规范的做法是在项目根目录的AGENTS.md里按需引入。我通常在项目AGENTS.md开头加这样一段# 项目规则 ## 行为规范 - 所有代码必须遵循superpowers的test-driven-development技能流程。 - 提交信息必须按superpowers的commit-message技能规范编写。 - 在修改涉及数据层的代码时必须执行database-migration技能中的检查清单。这么做的效果是Codex在这个项目里干活时会同时读取全局superpowers规则和项目级规则然后执行项目级优先、技能自动加载的逻辑。多项目协作时superpowers的使用就从一个开发者的个人偏好升级成了团队约束。4. 技能运行的核心原理规则文件、会话变量与提示词上下文4.1 AGENTS.md在Codex中的加载优先级与机制关于AGENTS.md有必要展开细说因为我周围很多朋友在配置superpowers时都卡在这一步。Codex CLI在每次会话开始时会按固定顺序读取几类上下文文件首先是内置的系统提示然后是全局的AGENTS.md也就是你通过环境变量指定的路径然后是当前工作目录及父目录里的AGENTS.md最后才是用户当前输入的对话内容。这个加载顺序决定了一件事AGENTS.md中的规则始终在用户消息之前注入所以不会被用户的一句随性提问覆盖掉。优先级上项目级AGENTS.md会覆盖全局配置但superpowers的规则文件需要保证自己在两种场景下都能被读到。如果你跟我一样用了环境变量注入全局规则再叠加项目级规则最终Codex会把两者合并处理冲突时项目级优先。还有一个容易忽略的细节Codex是递归向上查找AGENTS.md的。这意味着如果你的家目录下有一个全局的AGENTS.md它会被当作最高层的项目规则。我之前在家目录放了自己的通用规范结果每一个项目都莫名其妙要求提交信息必须包含Jira单号排查了很久才找到源头。所以用superpowers之前务必检查家目录有没有这类全局文件避免规则叠加后行为异常。4.2 技能文档的内部结构与写法一个标准的superpowers技能文档放在skills/技能名/SKILL.md结构大致如下--- name: test-driven-development description: 当需要编写新功能或修改已有代码时强制使用TDD流程。 --- # 测试驱动开发技能 ## 适用场景 - 新增功能 - 缺陷修复尤其是回归类问题 ## 工作流程 1. 先编写失败测试明确预期行为。 2. 运行测试确认其失败。 3. 编写最小实现代码让测试通过。 4. 运行全部测试确认无回归。 5. 检查代码质量执行重构。 ## 硬性要求 - 禁止跳过测试步骤。 - 禁止在测试未通过时提交代码。 - 每次重构后必须重新运行测试。这里的关键是description字段。Codex在扫描技能清单时会根据它的描述来判断当前任务匹配哪个技能然后只加载匹配技能的具体内容。所以写技能文档时description要尽量标注何时触发而工作流程则要尽可能具体到可执行。4.3 会话变量如何让技能适配多环境superpowers的会话变量是我觉得最被低估的功能。它的基本原理是在技能文档中预置占位符Codex启动时根据当前环境信息自动填充。常用的几个内置变量包括变量名说明示例值{{CODE_VERSION}}当前项目的语言/框架版本Python 3.11.4{{DEFAULT_SHELL}}当前终端的Shell类型zsh、powershell{{PACKAGE_MANAGER}}根据项目文件推断的包管理器npm、maven、cargo{{AGENTS}}已加载的所有规则文件路径/path/to/AGENTS.md比如workflow技能里有这样一段命令{{PACKAGE_MANAGER}} test在Java项目里会被替换成mvn test在Node项目里替换成npm test在Rust项目里替换成cargo test。一份技能多个语言生态通用这就是它的价值。我在给团队写内部技能时也学会了自定义局部变量在技能文档的Front Matter里定义键值对然后用{{变量名}}引用。虽然自定义变量的赋值逻辑需要靠Codex自己判断不如内置变量那么自动但用来约束输出格式非常方便比如强制提交信息追加某个前缀。4.4 缓存机制与更新策略superpowers的技能扫描结果有缓存这个缓存存储了技能清单。它会带来一个实际体验你新加了一个技能文档但Codex的下一次会话还是读旧清单新技能失踪。解决办法是在修改技能文件后删除缓存目录重新扫描。缓存目录的默认位置在~/.codex/superpowers_cache/。我处理更新时的固定动作是rm -rf ~/.codex/superpowers_cache codex这是个治标办法但确实管用。另外每次更新superpowers仓库时git pull也建议顺手清一次缓存因为技能本身的版本变更用不上旧索引。5. Java项目实战用superpowers驱动Codex走一遍TDD工作流5.1 场景设定一个订单金额计算组件的需求前面讲了很多原理现在来一个具体实战。我最近在做的一个内部订单系统需要新写一个金额计算组件根据商品单价、数量和折扣率计算订单总金额并支持叠加优惠券。这是一个典型的业务逻辑单元测试需求非常适合用来演示superpowers的技能编排。项目环境Java 17 Maven JUnit 5仓库里已经配置了项目级AGENTS.md引入了superpowers的test-driven-development和plan技能。5.2 第一阶段plan技能先做任务拆解启动Codex后我给出的第一条指令是我需要实现一个订单金额计算组件支持商品小计、折扣、优惠券叠加。请先按plan技能制定实施计划。Codex读取到plan技能的触发条件没有直接写代码而是先输出了这样的计划梳理业务规则列出输入输出和边界条件。根据测试驱动开发技能先编写单元测试覆盖正常、边界和异常场景。运行测试确认全部失败。实现金额计算逻辑满足所有测试。执行mvn test全量验证。按commit-message技能生成提交信息。这个输出让我很满意——它没有一头扎进代码而是先按技能约束完成了任务分解。这一步在裸用Codex时很难稳定复现因为普通会话下Codex更倾向于直接给出实现代码。5.3 第二阶段TDD技能约束下的测试先行我确认计划后要求Codex按计划执行第一步和第二步。接下来它做的事情完全符合TDD技能的规定。它先创建了测试文件OrderCalculatorTest.java其中包含正常场景单价100元、数量3、折扣率10%预期金额270元。边界场景折扣率为0优惠券不叠加。异常场景数量为0或负数时抛出IllegalArgumentException。写完后它主动执行了mvn test确认测试失败。我当时预期它会直接开始写实现实际上它是先停下来问我测试已确认失败是否开始编写最小实现这是TDD技能里红灯-绿灯-重构流程的体现。5.4 第三阶段实现与验证我回复开始实现Codex才创建了OrderCalculator类按最小实现原则让测试通过。随后它再次执行mvn test看到全部通过后进入自查环节。它按照superpowers的code-review技能逐项检查了参数校验是否完整、浮点数比较是否使用了BigDecimal而不是double、方法命名是否符合领域语义。它还主动指出了我原本没考虑到的点折扣率传入0.1代表10%但这个约定没有在接口文档里说清楚建议补充Javadoc。这种主动发现规范问题的行为就是技能文档带来的额外收益——Codex不再只是代码生成器它开始按工程师标准做自查。5.5 实测效果与配置细节整个流程跑下来我的感受是superpowers并不是缩短了耗时而是改变了产出质量和流程顺序。裸用Codex时一次任务可能在3分钟内获得代码测试提交消息superpowers模式下整个过程分阶段推进总耗时更长但中间的验证步骤一个不少测试质量明显更高。如果你的Java项目用了Lombok、Spring等框架技能文档里的命令还是有一些需要调整的地方。比如mvn test默认不会编译lombok生成的方法这会导致测试代码编译失败。我的做法是给项目的AGENTS.md补充一条规则执行测试前必须使用mvn compile验证编译通过。配置项建议值说明Java版本17技能文档中可指定{{CODE_VERSION}}测试命令mvn test -DfailIfNoTestsfalse防止无测试模块导致失败编译校验mvn compile在测试前执行浮点金额类型BigDecimal避免精度问题6. 常用技能组合与多语言适配6.1 我日常最常用的四组技能superpowers仓库里默认带了几十个技能实际用下来我日常离不开的是下面几组。第一组是plan加test-driven-development适用于几乎所有功能开发。plan负责拆解任务tdd负责约束编码过程。这一组合基本覆盖了日常80%的编码需求。第二组是code-review加security-audit适用于提交前的自查。code-review检查代码风格、重复代码、命名规范security-audit则重点检查硬编码密钥、SQL注入、依赖漏洞这些安全问题。对我来说这组技能最大的价值是让Codex在你自己检查之前先过一遍。第三组是commit-message加changelog适用于版本管理。它会根据当前的改动内容自动生成符合Conventional Commits规范的提交信息。配合我团队用的自动发版流程这个技能几乎是刚需。第四组是refactor加performance适用于老代码优化。refactor技能不追求改变外部行为只做结构性调整performance则关注热路径上的瓶颈。6.2 如何把技能迁移到Python、Go等生态前面说过一次技能文档通过会话变量适配多语言。具体到实操我的Python项目里几乎完全复用同一套技能不需要改技能文档只需要在项目AGENTS.md里明确包管理器- Python版本3.11 - 包管理器poetry - 测试命令poetry run pytestCodex在运行{{PACKAGE_MANAGER}}这类变量时会因为项目级规则中出现了poetry而自动识别。如果识别失败技能里可能会执行pip install这是我最不希望发生的事情。遇到这种情况排查思路很简单检查项目根目录的AGENTS.md里有没有明确包管理器信息。Go项目和Rust项目同理。Go的测试命令是go testRust是cargo test。只要规则文件写清楚了superpowers的技能一次编写、多语言复用是成立的。我在团队内部建立的规范是凡是涉及测试命令的技能统一使用{{PACKAGE_MANAGER}}占位符绝对不硬编码npm test或mvn test。7. 常见问题排查加载失败、命令识别错误、会话变量失效7.1 技能加载失败文件存在但Codex说不知道这类问题最常见的原因是缓存没清。技能清单是扫描快照你在skills/里加了新技能但Cache里还是旧列表所以Codex看不到新技能。解决的办法就是前面说的删掉~/.codex/superpowers_cache重启会话。第二种原因是技能文件格式不对。Codex扫描时读取的是SKILL.md里的name和description字段如果你用了其他字段名或者把description写得太模糊比如帮助用户解决问题Codex会把它识别为低匹配度技能不主动加载。我的经验是description里一定要包含可触发的动作词比如当需要创建新模块时使用此技能。7.2 命令执行不对在Java项目里跑了npm命令这个问题大概率是会话变量识别偏了。{{PACKAGE_MANAGER}}是根据项目文件推断的如果项目根目录同时有package.json和pom.xmlCodex可能选错。解决办法是在项目AGENTS.md里显式声明- 项目管理工具maven - 禁止使用npm或yarn命令。这种面向AI的规则文件需要比给人看的文档更武断。人知道上下文自动切换AI不知道。把限制写成禁止使用能从根上避免错误执行。7.3 会话变量没有被替换技能文档里出现了原始占位符有时候你会看到Codex的回复里直接出现{{PACKAGE_MANAGER}} test这说明变量没有被替换。原因一般是当前Codex版本不支持该变量或者变量名拼写不一致。我的排查顺序是先检查Codex版本再检查技能文件是不是用了{{}}两侧有空格比如{{ PACKAGE_MANAGER }}这种写法不会被识别最后检查变量名是不是PACKAGE_MANAGER而不是PACKAGE_MANGER这种笔误。实测下来版本不支持的概率最低空格问题最常见。7.4 与worbuddy类工具的配合问题最近有朋友问过我worbuddy这类AI编程辅助工具能不能也用superpowers的思路。我的看法是只要工具支持AGENTS.md或类似的指令文件加载机制就可以借鉴superpowers的技能文档写法。核心不是工具叫什么而是三件事一份结构化的技能清单、一种按需加载的机制、一组动态替换的环境变量。我在worbuddy上的尝试方式是把superpowers的skills/目录clone下来然后在worbuddy的项目规则文件里引入指定技能。它虽然没有Codex那样完整的技能缓存机制但对AGENTS.md的读取是有效的所以TDD技能、commit-message技能都能跑出接近的效果。如果你的工具完全不支持外部指令文件那superpowers的安装方式就需要调整——不过在我看来不给规则文件入口的工具本身也不太适合做严肃的工程任务。8. 实战心得怎么让superpowers真正融入日常开发多用了一段时间之后我最大的感受是superpowers不是一个装了就好的工具它更像一套需要你持续维护的规范体系。技能文档写得越贴近你团队的真实工作流Codex的表现就越好。默认仓库里的技能只能算通用模板真正好用的是你根据自己的项目痛点改过的版本。举个小例子。我们的项目要求所有对外接口的响应体封装成统一格式{code, message, data}裸用Codex时它经常自由发挥返回裸对象。后来我在项目的AGENTS.md里明确写了所有Controller返回值必须使用ApiResponse封装禁止返回裸类型效果立竿见影。superpowers培训出的Codex行为本质上就是这些写进规则文件里的话。另外技能文档的维护频率很重要。我一般每两周会做一次review看看这段时间哪些技能经常触发但给出的步骤不合实际哪些步骤执行率不高。比如我最初给plan技能规定必须输出时间估算后来发现Codex的时间估算不准团队也不依赖就去掉了。技能是活文档应该跟着你团队的实际磨合持续迭代。还有一点想提醒别给项目挂太多技能。技能数量太多Codex的上下文窗口会被技能文档占据留给真实任务的空间就少了。我实测过全局挂载30个技能的时候Codex后面几轮对话明显变笨因为有效上下文被挤占了。现在我的做法是全局只保留5个基础技能项目级再按需叠加2到3个效果最稳。最后分享一个我踩过几次坑之后形成的固定流程每次调整技能文档必做的三件事是——重开Codex会话、清缓存、用一条简单指令比如列出当前可用技能验证加载。这套流程变成了肌肉记忆之后superpowers的使用就很少出现文档改了但行为没变的怪问题了。