从第一次在终端里敲下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 → review
superpowers最值得玩味的不是单个技能，而是它串起来的那条工作链。一个功能从想法到上线，它会把过程拆成四个阶段：发散方案、设计文档、编码实现、代码审查。每个阶段对应一组技能，上一阶段的产出会成为下一阶段的输入。
拿给项目加一个"导出报表"功能举例。没有技能时，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 做正经项目，我建议从标准技能链开始，先用两三个项目跑顺，再逐步加自己的自定义技能，这条路最稳。
