从第一次在终端里敲下codex那条命令开始我一直觉得这类 AI 编程助手有种聪明但不太会用的感觉你问它一句它能答得像模像样但真让它独立把一个功能从规划到落地做完它经常会走一步看一步甚至在一个错误方案上越走越远。后来我接触到superpowers这个项目才意识到问题不是模型不行而是缺了一套让 AI 按工程节奏干活的工作方法。简单说它是一个给 Codex CLI 加技能的库让 AI 在动手写代码之前先做头脑风暴、写设计文档、列实施计划再一步步实现并自查。这篇文章就聊聊它的设计思路、实际安装使用流程以及我在项目里踩过的一些坑。superpowers适合谁主要是已经在用 Codex CLI 但觉得它只会写码、不会做工程的人也包括想把团队编码流程沉淀下来、让每个 AI 会话都按统一规范走的团队。下面我按自己的实操顺序展开。1. 它到底在解决什么问题从会聊天到会干活1.1 痛点AI 编程助手往往答得快、想得浅只要用过 Codex 这类工具你一定遇过这种场面让它修复一个 Bug它直接把报错那行改掉然后自信地告诉你已修复。但仔细一看它根本没搞清楚这个函数的调用方有多少、改完是否影响其他模块、有没有对应的测试。模型本身的能力不差差的是它没有先想清楚再动手的强制流程。其实这就像刚入行的程序员给需求就写代码写到一半发现设计有问题推倒重来浪费一堆时间。老工程师会怎么处理先问清楚目标、列出可选方案、评估风险、写一份简要设计然后才开始编码。superpowers想做的就是把这些资深工程师的习惯变成 Codex 每轮任务里必须遵守的技能协议。我还发现一个更隐蔽的问题普通提示词虽然能临时让 AI 表现得谨慎一点但换个会话、换个项目这个人设就丢了。superpowers把工作方法固化到磁盘上的技能文件里只要安装一次每次启动 Codex 都会自动带上这套约束。它不是靠你每次花几百字去教育模型而是靠一套长期生效的配置文件。1.2 解决思路把资深工程师的工作方法沉淀成提示词技能superpowers本质上是一个技能库每个技能都对应一个专门的工作流程存放在~/.codex/skills/这样的目录下。Codex CLI 启动时会读取这些技能文件的说明当你的任务命中某个技能的应用场景时它就会自动把整套流程加载进上下文然后按步骤执行。这套思路和普通的写个 system prompt完全不同。普通提示词是一次性的对话开始前给一段指令之后模型就自由发挥了。superpowers的方式更接近Git 子模块技能是独立维护的一套流程文件可以升级、可以替换、可以只针对特定项目加载。你甚至能把手头项目的编码规范、架构约定也装进技能里让 AI 每次产出都符合团队习惯。我自己的理解是它本质上是把AI 的工作流和人的工作流对齐。人的工程节奏是先发散再收敛先设计再编码而默认状态下的 AI 是你问什么我答什么。superpowers通过技能链把线性问答改造成发散、设计、实现、审查的流程这也是它名字的由来不是让 AI 变聪明而是给它一套超能力般的成熟工作法。2. 安装前置条件与完整安装流程2.1 环境要求与前置准备安装superpowers之前你得先保证 Codex CLI 本身能正常工作。我当时的操作顺序是这样的先升级 Codex CLI 到较新版本然后确认系统里有 Git 和基础的 Node.js 环境。因为 Codex CLI 本身依赖 Node.js 运行时版本太老可能导致技能加载异常。另外要特别提醒superpowers的技能文件虽然是 Markdown但它的加载依赖AGENTS.md规范。Codex CLI 会从项目根目录和~/.codex/AGENTS.md里读取全局指令superpowers的安装脚本一般会自动把技能引用写进这些文件。如果你是自己手工配置必须先确认 Codex 版本支持AGENTS.md否则后面技能装了也可能不生效。检查是否满足条件其实就三步在终端输入codex --version确认版本确认ls ~/.codex目录存在再用git --version看看 Git 是否可用。~/.codex目录没有也没关系Codex 首次运行时会自动创建但提前确认一下能省掉后面不少排查时间。2.2 克隆项目并执行安装superpowers的安装方式非常直白就是把仓库克隆到本地然后跑它的安装脚本。我当时用的是下面这套命令git clone https://github.com/obra/superpowers.git cd superpowers ./install.sh安装脚本做的事情从常见实践来看通常有三部分把技能文件复制到~/.codex/skills/目录在~/.codex/AGENTS.md中写入对 superpowers 的引用如果有项目级配置也会给出提示让你决定是否让当前项目使用这套技能。整个安装过程大部分是静默的跑完之后终端会提示你重新打开 Codex 或重启终端。有一点要说明项目仓库更新比较快如果安装脚本的名字变了或者 README 里推荐了别的命令请以仓库文档为准。我建议安装前先扫一眼 README因为superpowers在不同阶段可能调整过目录结构跟着最新文档走最不容易踩坑。提示如果你不太放心让安装脚本改动~/.codex下的全局配置可以先手动备份一份AGENTS.md。我当时是把原有的AGENTS.md复制成了AGENTS.md.bak万一出问题可以秒回滚。2.3 安装后的验证与目录结构装完之后别急着用先做一轮验证。我习惯用下面的命令确认技能文件确实到位了ls ~/.codex/skills/正常情况下你会看到类似superpowers的目录里面是一系列技能子目录每个子目录里都放着一个SKILL.md文件。这个文件就是技能的核心它的开头部分描述了技能适用场景和触发条件正文部分则是具体的工作步骤。目录结构不对Codex 就弹不出技能这是后面最常见的坑之一。然后再检查~/.codex/AGENTS.md里有没有出现 superpowers 相关指引。如果没有可能是安装脚本没执行完整也可能你用了自定义路径。最简单的方式是手动追加一行类似Skills are available under ~/.codex/skills/当任务涉及方案设计、代码实现或审查时使用对应技能的说明。不过别照抄这句具体怎么引用得看你当前 Codex 支持的规范版本。验证完毕之后我还会跑一个极简任务测试比如在任意项目目录里输入codex 用 brainstorm 技能帮我把这个登录功能列出三个实现思路如果 Codex 真的按照技能里定义的头脑风暴流程来回答而不是直接给方案那就说明技能加载成功了。3. 核心技能拆解与实战调用从头脑风暴到代码审查3.1 核心技能链条brainstorm → design → implement → reviewsuperpowers最值得玩味的不是单个技能而是它串起来的那条工作链。一个功能从想法到上线它会把过程拆成四个阶段发散方案、设计文档、编码实现、代码审查。每个阶段对应一组技能上一阶段的产出会成为下一阶段的输入。拿给项目加一个导出报表功能举例。没有技能时Codex 很可能直接就开始写导出代码而有技能时它会先进入 brainstorm 阶段问你报表格式是 CSV 还是 Excel数据量级多大导出是同步还是异步需不需要权限控制。这些发散问题让需求边界清晰起来。紧接着是 design 阶段它会把前面讨论的结论整理成一份简短的设计文档包含改动范围、涉及文件、风险和验证方式。到了 implement 阶段Codex 会对照设计文档逐文件实现而不是凭记忆乱改。最后 review 阶段它会以审查者视角重新读一遍自己的代码找出潜在 Bug 和风格问题。这个链条的妙处在于每一环都在给下一环减负。没有前面的设计文档实现阶段很容易失控没有最后的审查代码质量只能靠运气。你可以把这条链理解成给 AI 戴了一副工程眼镜让它每一步都看得见上下文而不是只盯着眼前那几行代码。3.2 实战调用示例让 Codex 先做方案再动手在终端里实际调用时不一定要一次把四个技能都说全你可以按需触发。我的常用姿势是每次开场先描述目标然后点名当前阶段该用的技能名。因为技能文件里写明了自己的触发场景你点名也好、自然语言描述也罢Codex 都会自动挂载。举一个我最近的例子。我在一个内部工具项目里让它新增一个批处理导入功能命令大概是这样的codex 现在要新增一个批量导入用户的功能请先用 brainstorm 技能整理需求边界然后再用 design 技能输出一份实施计划接下来很有意思Codex 没有直接写代码而是先反问了一串问题比如导入文件的字段来源、数据校验失败之后是跳过还是中止、导入过程需不需要支持恢复等等。我补充完信息之后它自动进入设计文档阶段输出了一份内容明确的实施计划。整个过程没有我干预完全靠技能链把它推着走。如果你想让它一口气全流程做完也可以在确认需求后直接说按 superpowers 的完整流程完成这个功能从设计开始。不过我个人建议在项目规模不大时把前两个阶段走完就手动喊停因为设计文档和实际代码有时会存在偏差保留一个人工确认点会更稳妥。3.3 Java 场景扩展语言无关技能如何适配编程语言有人会问superpowers java到底是怎么回事。其实superpowers核心的技能链是语言无关的它管的是工作流程不是某个语言的语法。但 Java 项目有自己的特殊性规范命名、Maven 或 Gradle 构建、JUnit 测试约定、分层架构等等。如果不在技能里做约束Codex 写出来的 Java 代码可能在风格上四不像。我实际的做法是在项目根目录的AGENTS.md里追加 Java 相关约束比如所有新增类放在src/main/java下测试使用 JUnit 5遵循项目的包命名规则。然后再把 superpowers 的技能引用保留在全局层两层配置一叠加Codex 既能按流程工作又能产出符合团队预期的 Java 代码。如果你觉得标准技能链里缺少 Java 专属操作也可以自己写一个简单的 Java 技能文件规定编码前检查现有模块结构、实现时必须同时给出单元测试、完成后执行mvn test验证。这些技能文件可以按项目加载不影响其他语言项目。说白了superpowers给了你一个框架往框架里塞什么规范由你的项目说了算。4. 配置优化与自定义技能4.1 全局与项目级 AGENTS.md 的配合superpowers之所以灵活很大程度是因为 Codex 支持多级AGENTS.md配置。全局配置放在~/.codex/AGENTS.md适合放通用的工作流引用项目配置放在项目根目录适合放这个仓库独有的约束和模块说明。两级配置会合并生效这是最合理的组合方式。我把superpowers的引用放在全局配置里这样任何项目都能用这套技能链。然后在具体项目里我会写一份项目级AGENTS.md内容包括模块目录说明、构建命令、测试命令、代码风格要点。这样一来Codex 跑在任何一个项目里既知道怎么干活又知道这个项目的活该怎么干。这里有个细节要注意项目级配置经常会覆盖或干扰全局配置中的意图。比如全局说实现前必须写设计文档项目里如果有一段话强调本项目改动小可以直接改代码Codex 读到后可能就会跳过设计阶段。所以写项目级配置时最好和全局配置保持口径一致不要互相拆台。4.2 自定义一个技能需要考虑什么superpowers的设计思路鼓励你写自己的技能。新建一个技能其实就是在~/.codex/skills/下新建一个目录里面放一个SKILL.md文件。文件开头要写清楚这个技能是干什么的、什么时候触发正文里写详细步骤。这个格式和写操作手册很像关键是把步骤写得足够具体让 AI 有据可依。我在写自定义技能时提炼了几个要点第一触发条件必须明确描述要覆盖 AI 自然语言理解的范围例如当用户要求新增模块或重构现有模块时第二步骤要编号并且每一步尽量包含输出物比如分析现有代码结构并输出文件清单第三步骤之间要有逻辑闭环不能前一步结论和后一步操作对不上。还要注意别把技能写得又长又泛。技能文件不是越大越好它最终会占用 Codex 的上下文窗口。一个技能如果能用 300 行解决就不要写 800 行。凡是能在项目级AGENTS.md里表达的内容就放进AGENTS.md凡是需要一套完整工作流的才值得做成技能。提示自定义技能后如果 Codex 不识别先用ls ~/.codex/skills/你的技能名/SKILL.md确认路径再检查文件开头的触发描述是否够清晰。最常见的失效原因不是格式错而是描述写得含糊AI 根本不知道该用它。4.3 团队协作中的统一工作流superpowers还有一个被低估的价值团队统一工作流。以前大家用 Codex 是各用各的提示词有的人要求先写测试有的人习惯直接改代码产出风格完全靠个人习惯。现在只要把一套superpowers技能链和项目级AGENTS.md放进仓库全组人的 Codex 行为就都对齐了。具体操作上可以把~/.codex下的技能目录纳入团队内部共享仓库或者把技能文件打进项目仓库的.docs目录里再在AGENTS.md中指定路径引用。新成员入职后第一条命令就是安装 Codex、克隆项目、跑一遍安装脚本接手的风格和老成员完全一致。这种统一还能延伸到代码审查环节。团队成员手动做 Code Review 之前可以先让 Codex 用 review 技能过一遍代码把明显的问题清单列出来。人再看的时候重点就放在架构和业务逻辑上效率高不少。对我这种经常 solo 开发的人来说相当于白捡了一个不知疲倦的结对同事。5. 常见问题与排查技巧实录5.1 技能文件明明存在但 Codex 好像没读到这类问题我遇到得最多十有八九是路径或配置加载的问题。第一步检查~/.codex/skills/下是否存在对应的技能目录第二步检查AGENTS.md里是否真的引用了技能。如果都正常第三步重启 Codex 会话。很多人改完配置文件不重启结果旧会话一直用旧上下文。还有种情况是技能文件本身有语法或格式问题。superpowers的技能文件比较依赖标准的 Markdown 结构如果你手动改过文件某个标题层级乱了加载时可能静默失败。我的排查技巧是在终端里先把SKILL.md当普通文本用less打开看一眼确认头部说明字段都还在。如果以上都排除就要考虑是不是 Codex 版本太老。技能系统依赖的AGENTS.md和 skills 机制在近期的 Codex CLI 版本里才逐渐完善老版本根本不认这些文件。升级 Codex CLI 是最直接的解决方式。5.2 上下文窗口被技能说明占满怎么办技能越多Codex 每次对话需要载入的说明也越多上下文窗口很快会被撑满。尤其是加载了整个 superpowers 技能链以后如果再在会话里粘贴大量项目文件就会明显感觉到 Codex 开始忽略一些细节甚至记不住前面的设计文档。解决办法是分层加载。全局配置里只保留最核心的工作流技能把那些很少用的长技能从全局搬走改成在具体项目的AGENTS.md里按需引用。这样日常任务不会背着所有技能跑只有进了特定项目才加载对应那部分。另外对话过程中如果发现 Codex 开始丢上下文可以主动清空会话重开。因为 Codex 每次重开都会重新读取技能和配置你要是提供一份精简的项目概述它会很快回到状态。别试图在一个超长会话里把 10 个功能都做完那既费上下文又容易出错。5.3 版本兼容与升级注意事项升级 superpowers 本身不算难但要注意它和 Codex CLI 是独立演进的。我遇到过 Codex 更新后技能链命中的方式变了原来是直接读AGENTS.md里的引用新版本则要求技能文件放在特定子目录下导致旧技能全部失效。升级前先看 superpowers 仓库的 CHANGELOG 或 release notes确认它当前适配的 Codex 版本范围。如果只升了 Codex 而没升 superpowers出现异常时别急着去改技能文件很可能是版本不匹配。提示我的升级习惯是先把~/.codex/AGENTS.md和~/.codex/skills/整个备份一份再执行升级。万一新版本不符合预期把备份恢复回去马上就能回到可用状态。这个习惯救过我两次强烈建议照着做。6. 实际使用中我踩过的坑和心得最后分享几条我自己的心得体会。第一superpowers不是魔法它不会让 Codex 突然变聪明但它能把 Codex 的产出从零散答案变成工程产物。最直观的变化是我给它派活之后不再需要全程盯着中间到设计文档阶段停一下确认方向没问题再放它去写代码。第二技能文件本身就是团队资产。我以前总觉得写技能是在调工具后来发现它其实是在把团队做事的经验固化下来。你脑子里那些先查模块边界再动手测试要覆盖异常路径的隐性知识一旦写成技能就变成了团队所有人能复用的显性规范。第三别贪多。刚开始接触 superpowers 的时候我一下子往系统里塞了十几个技能结果 Codex 每次对话都很慢上下文先被技能说明吃掉了。后来我砍到核心四五个使用体验明显改善。技能这东西少而精胜过杂而全。如果你也在用 Codex 做正经项目我建议从标准技能链开始先用两三个项目跑顺再逐步加自己的自定义技能这条路最稳。