superpowers：基于Codex CLI的AI编程增强技能包实战详解

1. 先搞清楚superpowers到底是什么

先说结论：superpowers不是某个独立编程语言，也不是一个具体框架，而是一套围绕Codex CLI打造的增强技能包。说得更直白一点，它是一套“给AI编程助手加Buff”的规则、脚本与工作流集合，让你在终端里用Codex干活时，不再只是简单的一问一答，而是拥有完整的任务规划、代码操作、测试执行、命令运行甚至网页检索能力。

我第一次接触这个项目时，其实是有点困惑的。因为“superpowers”这个名字太泛了，搜索结果里既有人讨论游戏里的超人设定，也有人聊个人成长方法论。直到我顺着“codex superpowers”这个热词摸到GitHub仓库，才明白这是一个非常接地气的开发工具项目。它可以理解为一套“前置技能库”：你在项目里配置好它之后，Codex能根据你的需求自动调用对应技能，比如深度思考、代码库检索、运行测试、读取文档、甚至处理Jira任务。

那它到底解决了什么问题？用过Codex CLI的人应该都有体会：默认情况下，你让它改代码，它可能只给你一段代码片段；你让它排查问题，它可能只给建议，不会实际执行命令。而superpowers把这类“半自动”体验升级成了“全自动”——它会先读你的项目结构，再定位相关文件，然后执行测试，最后迭代修改，直到跑通为止。

这套东西适合谁？我觉得有三类人特别值得尝试：第一类是已经在用Codex CLI但觉得效率一般的开发者；第二类是刚接触AI编程、希望有一套标准化工作流的团队；第三类是像我一样，喜欢折腾终端工具链、愿意花时间配置环境的效率控。如果你完全没用过Codex，也没关系，下文会从环境准备开始讲，你照着做就能跑起来。

说实话，这类技能框架类项目，真正有价值的不是代码本身，而是它定义的那套“思考方式”。你学会了之后，甚至可以自己写新的技能，把它扩展成你自己的超级工具箱。

2. 动手之前：环境准备与安装流程

2.1 前置依赖：先把Codex CLI跑起来

superpowers是跑在Codex CLI之上的，所以第一步是确保你的机器上已经装好了Codex CLI。我用的是macOS环境，Node版本保持在18以上，安装过程非常简单：

npm install -g codex codex --version

如果你之前没装过，建议先跑一遍codex --help看看基本命令，再试着让它回答一个简单问题，比如“给我写一个Python的快速排序”，确认整个链路是通的。

这里有个小坑：Codex CLI会自动读取仓库里的AGENTS.md文件作为行为约束，后续安装superpowers时也会用到这个文件。如果你的项目本来就有自己的一套AGENTS.md，建议先备份一下，因为superpowers安装过程会创建或修改这个文件。

2.2 安装superpowers：一条命令还是手动克隆？

superpowers的官方安装方式推荐用codex自带的能力去自动获取，其实就是让Codex自己去下载仓库、配置技能目录。我试过在空白目录里执行：

codex "install superpowers from the superpowers community repo"

Codex会自己找到GitHub上的仓库，把文件克隆到本地，然后生成AGENTS.md和.superpowers目录。这个过程看着很神奇，本质上是Codex调用了shell工具执行了git clone和文件复制。

如果你习惯手动控制，也可以直接克隆仓库：

git clone https://github.com/obviouslyai/superpowers.git

然后自己把skills目录、commands目录复制到项目的.superpowers下。两种方式各有优劣：自动安装省心，适合新手；手动克隆则能让你看清文件结构，方便后续自定义。

我个人的建议是：第一次用自动安装，跑通之后再去看目录结构。因为如果一开始就手动克隆，你可能会被一堆文件搞得头大，不知道哪些是核心、哪些是辅助。

2.3 目录结构解读：明白文件放哪里才算入门

装完之后，你的项目里会多出几个关键部分，我先挑核心的讲：

• AGENTS.md：项目级的行为说明书，Codex每次对话都会读取它。superpowers安装时会在里面写入技能加载规则，告诉Codex去哪里找技能、怎么加载。
• .superpowers/skills/：存放各类技能的目录，每个技能一个子文件夹。
• .superpowers/commands/：存放自定义命令脚本。
• .superpowers/scripts/：被技能调用的底层脚本，通常是Python、Bash或Node脚本。

我刚开始用的时候，最大的误解是以为AGENTS.md只是给人看的文档。其实它对Codex来说就是“操作手册”——它决定了Codex在处理你的需求时，先读什么、后做什么、遇到问题怎么处理。所以如果你想让Codex表现出某种特定的行为模式，改这个文件是最直接的。

这点可以类比成给新同事写一份“入职第一天必读”，你写得越清楚，对方上手越快，犯错的概率越低。superpowers把这套思想工程化了，而且把它做成了可复用的技能包。

3. 核心玩法：技能系统与工作流实操

3.1 技能系统：每个列表一个专用工具

superpowers的核心是技能系统。每个技能说白了就是一组完整的“操作指令集”，包含三部分：

• SKILL.md：技能说明，告诉Codex这个技能在什么场景下使用、需要哪些输入、会执行哪些步骤。
• 脚本文件：实际干活的代码，可能是Python脚本、Bash脚本或者Node脚本。
• 引用资源：技能需要的数据、模板、文档等。

举个例子，它的codebase-rag技能是用来检索和理解大型代码库的。过去你让Codex改代码，它往往只能看到当前文件或者在上下文里的内容，而有了这个技能，Codex会先用脚本把项目索引一遍，找到相关文件之后再动手改。

再比如thoughts技能，它的作用是让Codex在动手前先写出详细思考过程。每次执行主任务前，它会先生成一个“想法日志”，列出修改计划、潜在风险和验证方式。这对于需要多文件、多步骤的复杂任务特别有用，能大幅降低改出问题的概率。

我给这套机制一个比较通俗的比喻：技能就像你给一个全能助手配备的“专用工具箱”，每个箱子标签清清楚楚，需要时自动打开，用完自动放回。Codex本身是那个助手，而superpowers就是那面整齐的工具墙。

3.2 深度思考模式：让Codex先想后做

我是从一次改代码事故里意识到“先想后做”有多重要的。当时我让Codex去重构一个Java模块，它二话不说就把一个公共方法签名改了，结果导致三个调用方全部编译失败，还花了我一个多小时排查。

所以superpowers里我最喜欢的一个技能就是deep-think，它会强制Codex在动代码之前先做完整的思考和规划。具体效果是这样的：你发出一个复杂需求，它不会直接甩代码，而是一步一步分析——当前实现的问题点在哪里、改动的文件有哪些、影响面有多大、需要跑哪些测试来验证。

如果你觉得每次都要触发这个模式太麻烦，还有一个快捷键式的命令：/deepthink。在Codex对话界面里输入这个命令，后面跟上你的任务描述，就可以直接进入深度思考模式。实测下来，对于跨文件改动、数据库迁移、架构调整这类任务，这个模式能明显减少返工。

3.3 命令系统：把常用操作变成斜杠指令

除了技能，superpowers还自带了一批以斜杠开头的快捷命令。比如：

• /fix：自动分析当前报错信息，生成修复方案并尝试修复。
• /test：运行项目测试，并把结果反馈给Codex，让它根据失败信息继续修正。
• /explain：让Codex解释当前代码或整个模块的功能。
• /review：对最近的改动做代码审查。

我实际用得最多的是/test。以前让Codex写完代码之后，我得手动跑一遍测试，再把报错信息贴回给它，来回折腾好几轮。现在直接输入/test，Codex自己跑测试、自己看报错、自己改代码，直到测试通过为止。这一条就能省掉大量时间。

可能有朋友会问：这些命令和写死在脚本里的指令有什么区别？区别在于，同一个命令在不同的项目、不同的技术栈下，执行的行为可以不同。因为命令背后读的是当前项目的AGENTS.md和所在目录的结构，所以它天然就是“上下文感知”的，这也是superpowers这个名字的真正含义——把通用AI变成项目专属的超级助手。

4. 场景实战：从零跑通一个Java任务

4.1 实战场景设计

光看文档不算上手，我拿自己最近做的一个真实案例来演示整个工作流。这个任务是给一个Spring Boot项目增加一个简单的REST接口，要求是接收GET请求，返回当前时间的字符串格式。看起来很简单，但项目里已经有了一套自己的异常处理、响应包装类和时间格式化工具，直接写肯定踩坑。

关键点在于：新人写这个接口可能半小时也搞不定，因为要先搞清楚项目的包结构、响应码规范、时间工具类的调用方式。而superpowers的价值就是让Codex自己“先探索再动手”。

4.2 实战过程拆解：探索、规划、编码、验证

我启动Codex后输入了如下需求：

codex "add a GET endpoint /api/now that returns current server time as formatted string in the existing response wrapper"

接下来发生的过程让我印象深刻：

第一步，Codex先调用了codebase-rag技能，扫描了整个项目的文件结构，检索了Controller目录、Service层、异常处理和响应包装类的相关代码。它花了大概十几秒，然后告诉我它打算放在哪个包下，以及会用到哪个响应类。

第二步，它进入deep-think模式，列出改动文件和风险点。它注意到项目里有一个统一的ApiResponse<T>包装类，还发现了DateUtils工具类，所以放弃了直接用LocalDateTime.now().toString()的偷懒做法，决定复用现有工具类和包装格式。

第三步，它才开始写代码。改动范围就两个文件：新建一个NowController.java，以及注册路由（项目里路由是集中配置的，所以要动配置类）。

第四步，它自动执行了/test命令，跑了项目里现有的测试用例，确认新增接口不影响其他功能。整个交互大概持续了两分钟，最终代码风格和项目现有代码保持一致，不需要我做额外调整。

4.3 参数选择与常用配置参考

如果你也想在自己的项目里复现这个效果，有几个配置点值得注意：

• AGENTS.md里最好写清楚项目的技术栈、测试命令和代码风格约定。superpowers自带的模板可以保证基本语法，但你的项目特有问题需要自己补充。
• 如果项目很庞大（比如生产代码超过10万行），建议先用codebase-rag生成一次索引，不然每次对话都要花很长时间扫描文件。
• Codex的模型温度参数会影响代码风格一致性，我一般用0.2左右，太低太死板，太高容易放飞自我。

还有一个实用技巧：给你的项目写一个“验收清单”放在AGENTS.md里，比如“所有新接口必须使用ApiResponse包装”“时间格式必须使用DateUtils.format”。Codex在完成一个任务后会自己核对清单，这是保证代码质量最有效的方式。

5. 常见问题与排查技巧实录

5.1 技能加载失败或没生效

症状是：你明明在项目里配置了superpowers，但Codex表现得跟没装一样，还是普通的一问一答。

排查思路我建议分三步走：

第一步，确认AGENTS.md是否被正确读取。你可以直接在对话里问Codex：“根据AGENTS.md，你应该使用哪些技能？”如果它能准确回答，说明加载正常；如果一脸茫然，那就是文件路径或权限问题。

第二步，确认技能目录是.superpowers/skills还是.codex/skills。不同版本的Codex对技能目录的读取路径有差异。我在一次升级后发现技能全部失效，折腾半天才发现是Codex新版本改了默认目录，把旧目录软链过去就解决了。

第三步，检查技能里的脚本是否能独立运行。有些技能依赖Python库或Node包，如果你的环境缺少依赖，技能加载就会失败。手动执行一下技能里的主脚本，能快速定位是代码问题还是权限问题。

5.2 技能执行超时或卡死

这个问题最常出现在codebase-rag扫描大项目时。我第一次在几个G的代码仓库里跑，结果等了十几分钟都没反应，还以为卡死了。

后来摸索出来的解决方案是：在项目的.superpowers/config.json里手动指定exclude目录，把node_modules、target、dist这些无关目录排除掉。扫描范围缩到十分之一，速度立刻快了起来。

还有一个经验是：如果你的项目本身就特别大，直接分词再让Codex理解并不高效，不如拆分模块做索引。比如按服务或子模块分别生成索引文件，需要哪个模块时再定向检索，这样速度和准确度都能兼顾。

5.3 代码被改坏的自救方案

这是我最想强调的一点：无论AI工具多强大，都不要在没备份的情况下让它大改。superpowers虽然思考过程严密，但它本质上还是在做概率生成，难免有认知盲区。

我的习惯是：每次让Codex动代码之前，先把当前分支打个标签，或者直接用Git的stash功能。一旦发现改坏了，一条git checkout .就能恢复原样，不用提心吊胆。

另外，我也建议在AGENTS.md里加一条硬性规则：“任何改动不得跳过大范围测试或类型检查。”实测下来，加了这条规则之后，Codex改编代码的谨慎程度明显提高，返工率下降不少。

5.4 常见问题速查表

6. 一些值得继续深挖的扩展玩法

如果你已经跑通了基础流程，还可以再往前探索几层，这几个方向我觉得都挺值得尝试。

第一个方向是自定义技能。superpowers自带的技能足够应付日常开发，但每个项目的痛点不一样，学着写一个自己的技能会非常划算。比如我有一个项目需要频繁生成数据库迁移脚本，于是我写了一个db-migrate技能，里面预设了SQL模板和版本命名规则，Codex每次执行迁移脚本生成都统一又规范。

实际上，写一个技能没有想象中复杂。你只需要新建一个目录，写一个SKILL.md描述这个技能的用途和输入输出，再放一个可执行脚本，然后在AGENTS.md中注册看看。我第一个技能从开始写到调通也就花了不到一晚上，之后的边际收益却非常大。

第二个方向是把superpowers接入团队协作流程。你可以把AGENTS.md里的一部分规范沉淀成团队级别的文档，让每个分支、每次PR都通过Codex自动审查。我们团队现在要求所有代码合并前跑一遍/review，让Codex从风格、性能和潜在Bug三个维度先过一遍，再交给人工reviewer，效率提高非常明显。

第三个方向是尝试和其他终端AI工具组合使用。市面上的AI编程工具不止一种，superpowers的核心设计思路（技能目录 + AGENTS.md组织方式）其实是可以复用的。如果你还在用其他AI工具，不妨尝试把类似的技能目录搬到那边去，只要工具支持读取自定义规则文件，这套方法论就能迁移过去。

我在实际使用中最深的体会是：superpowers这类项目表面上是在配置工具，本质上是在帮你梳理“你自己平时到底是怎么干活的”。你只有把自己的工作流拆清楚了，才能把它写成技能让AI执行。反过来说，一旦写清楚了，AI的工作质量反而会倒逼你优化自己的开发流程，形成正向循环。

最后分享一个小技巧：如果你发现某个技能总是发挥不稳定，别急着改代码，先看看它的SKILL.md写得够不够细。绝大多数情况下，不是代码逻辑有问题，而是“使用说明书”写得不够清楚。把这层想明白了，很多稀奇古怪的问题都能迎刃而解。