1. 先搞清楚：superpowers 到底是什么东西
最近我跟身边几个搞开发的朋友聊天，发现大家都在提一个叫 superpowers 的项目。一开始我还以为是某个超级英雄题材的开源游戏，结果一查才发现，这玩意的定位很有意思——它不是一个独立的应用，而是一套专门给 AI 编程工具“加Buff”的增强方案，核心是围绕 OpenAI 的 Codex CLI 做的。
简单说，Codex CLI 是官方出的命令行编程助手，你装了它之后，就相当于在终端里多了一个AI结对编程伙伴。但很多人在实际用的时候会发现一个问题：Codex CLI 在给你生成代码、改代码的时候，经常不考虑你项目的上下文，也不会自主决定去读哪些文件、跑哪些测试、改完一个地方之后会不会影响别的地方。说白了，它有“手”有“嘴”，但缺少一套“行动规划”的脑子。
superpowers 干的事情，就是把这个“脑子”补上。它不是插件，更准确地说是基于 Codex CLI 的一套配置、一套 skill（技能指令集）和一套工作流协议的集合。你可以把它理解成给 Codex 装了一本《程序员最佳实践手册》，并且教会了它在动手写代码之前先去“思考”的完整流程。
这套方案在技术圈热起来不是没道理。整个方案的核心目标就一句话：把 AI 从一个只会“听命令生成代码”的工具，变成一个能自主完成编程子任务的代理。用官方文档里那句很直接的话来说——它给 Codex 赋予了“阅读项目、制定计划、逐步执行、自我校验、返回结果”的能力闭环。
如果你是一个每天被重复性 coding 任务缠身的开发者，比如写单元测试、修历史遗留的 bug、做代码 review、为了加一个字段要动五个文件这种活，那 superpowers 是真的能帮你省下一大块时间的。它也比较适合那些愿意花一点时间研究配置、折腾终端的开发者。在这篇文章里，我会从设计思路、安装配置、核心机制、实操流程和踩坑经验几个方面，把这个项目彻底拆开揉碎讲清楚。
2. 为什么需要这样一套“增强方案”
要真正理解 superpowers 的价值，得先搞清楚 Codex CLI 这类工具原本的短板在哪里。我用过一段时间的 Codex CLI，坦白讲，单论代码生成能力，它是相当强的，尤其是在 Python、Go、TypeScript 这类主流语言上，能写出来的代码质量远超预期。但问题恰恰不在生成代码质量上，而在于它“怎么干活”。
举个很典型的例子：假设项目里有一个注册功能模块，你想让 Codex 把里面的用户名校验从纯正则改成调用一个统一的校验函数。如果我直接把需求甩给 Codex，它最常见的操作是：找到你这个校验逻辑所在的位置，生成一个调用新函数的代码，改完就停了。至于新函数是否已经存在？是否存在同名但语义不同的函数？项目里其他地方是否已经有类似校验逻辑？这些它统统不会主动去查。你要是不问，它就不说，改完还不跑测试，一眼看过去代码确实改了，但实际上是“盲改”，很容易破坏原有行为。
这种问题出现的根因在于：Codex CLI 默认的运行模式是“一次性对话 + 上下文窗口”。它只看得见当前对话里你贴进去的代码和你明确让它读的文件，看不见项目全局结构。每次对话之间也是互相独立的，这个任务里学到的上下文，下个任务就会忘光。
superpowers 解决问题的思路很简单，但很聪明——它不改 Codex 的代码，而是人为地给 Codex 搭建了一套“行为框架”。具体来说，通过几个经过精心设计的 AGENTS.md 文件，告诉 Codex：“你是一个能干的资深工程师，在你动手之前，你必须先了解项目结构，再读相关文件，然后制定计划，接着按步骤执行，最后验证结果。”同时，它把一些高频子任务，比如“写测试”“修 bug”“做 review”“读代码”等等，拆成了独立的 skill 文件。每个 skill 文件里写得清清楚楚：这个任务的目标是什么、第一步做什么、第二步做什么、如何判定任务完成。
用大白话讲，这就好比一个刚入职的开发新人，脑袋聪明，动手也快，但就是不知道公司的代码规范、不知道项目模块在哪、更不知道哪些地方不能乱碰。superpowers 就是那份“部门新人培训手册”，把该知道的规矩、该走的流程全部写明白了，新人照着做就行。
这个方案的思路，本质上也暗合了现代软件工程里的一种趋势：AI 要真正融入研发流程，不能光靠模型本身的能力，更重要的是配套的流程、规范和工具链。大家其实都有感受，GPT-4o 在独立回答编程问题时表现惊人地好，但真扔进一个几万行代码的项目里做改动，反而容易踩雷，原因就是缺少一套工程化的执行约束。superpowers 恰好补上了这一环。
3. 核心机制拆解：AGENTS.md 与 Skill 系统的配合
3.1 AGENTS.md：让 Codex 先“通读全局”再动手
superpowers 整个框架的基石，是一套分布在不同目录层级里的 AGENTS.md 文件。这里先给不太熟悉 Codex CLI 的读者解释一下背景：Codex CLI 新版本支持读取项目里的 AGENTS.md 文件，把它作为“系统提示词”的一部分注入到每个对话上下文中。这个文件里写的内容，就是 AI 在回答任何问题之前都会读到的“背景知识”。
superpowers 的安装过程，实际上就是往你的项目目录里放这么一套分层的 AGENTS.md 文件。最顶层的那一份，会写清楚整个工作流程的基本原则，比如“在开始任何任务之前，先阅读相关文件，理解现有架构”之类的。子目录里还会有针对特定模块或特定任务类型的说明。这样一来，不管 Codex 在哪个层级被唤起，它都能先看到这些规则，再决定怎么干活。
这个设计其实很像微服务架构里的服务发现机制。Codex 本身是那台不知道下游服务地址的网关，AGENTS.md 就是注册中心告诉它“上游有哪些服务、各在什么位置”。没有这一步，AI 就是无头苍蝇；有了这一步，它至少知道先往哪儿看。
3.2 Skill 系统：把大任务拆成标准化子流程
AGENTS.md 负责约束行为习惯，而真正执行具体任务的是 Skill 系统。superpowers 给 Codex 内置了一整套可复用的子流程文件，每个 skill 等于一段标准作业程序（SOP）。这些 skill 涵盖的场景很全，从写代码、写测试、修复 bug 到做 code review 都有对应指令集。
拿“修复 bug”这个 skill 来举例，它的指令逻辑大致是这样：先让 Codex 阅读 bug 相关的代码和历史上下文，找到问题根因，然后列出可能的解决方案并给出理由，再选择其中一个方案动手改，改完之后必须运行相关测试，并在最终报告里明确说明“改了什么、为什么这么改、测试结果如何”。整个过程环环相扣，不允许 AI 跳过任何一步。这种“先理解、再计划、后执行、终验证”的方式，正好避开了大模型直接生成代码时容易忽略上下文和结果验证的通病。
另外我还注意到，这套 skill 系统本身也是可扩展的。如果你想增加一个属于自己团队的 skill，比如“执行数据库迁移”或者“发布新版本到测试环境”，只需要按照注解格式写一个新的 markdown 文件放进去就行。在文件头部用 YAML 格式标记好名称、描述、适用场景，Codex 每轮对话时会把可用的 skill 列表一起纳入考虑范围，按当前任务性质动态调用，不需要你去手动切换。
3.3 状态记忆与会话管理：为什么任务完成后还“记得”刚才的事
还有一个功能值得一提，就是 superpowers 引入的“任务状态记录”机制。以往我们跟 Codex 对话是做完一个任务就结束了，下个任务它又变成了“失忆状态”。superpowers 会在每次任务执行过程中把中间产物和最终结果按一定规则写入工作区文件，新任务开始时会主动读取这些记录，从而做到跨会话的上下文衔接。
这个方法本质上就是拿文件系统当长期记忆用。它思路朴素，效果却很实在。尤其在做那种前后有依赖关系的多步骤任务时，这个机制帮我省去了大量反复解释上下文的时间。我第一次用的时候，发现 Codex 竟然能自己引用我之前已经确认过的架构决策，那种“它把我当回事儿”的感觉，说实话比大多数 IDE 插件靠谱多了。
4. 安装与配置全流程：从零到能跑
4.1 环境准备：先装好 Codex CLI 和 Node.js
整个过程的第一步，是先确保本机环境是达标的。superpowers 是跑在 Codex CLI 之上的，所以第一步自然得先把 Codex CLI 装好。安装方式一般有两种，一种是通过 Homebrew 安装 brew install codex，另一种是通过 npm 全局安装 npm install -g @openai/codex。我个人更习惯用 Homebrew，因为后续维护升级比较省心。
装完 Codex CLI 之后，记得先在终端里跑一下 codex --version 确认版本号。如果之前装过老版本，建议顺手升级到最新。superpowers 新版本对 Codex CLI 版本是有最低要求的，版本太老的话部分 skill 功能可能不生效。
另外因为要安装扩展子依赖，本机建议装好 Node.js 18 以上版本。如果你之前装过一些开源的 Node 包管理工具比如 pnpm，也都能正常兼容，不必刻意换工具链。下面的步骤我就按 Node.js 自带 npm 来演示。
4.2 安装 superpowers：两种方案实测对比
superpowers 提供两种安装方式，一种适合临时试用，另一种适合多人团队长期共用同一套配置。
快速体验方式是在项目根目录执行 npx superpowers。这个命令会自动完成大部分初始化工作：拉取框架核心文件、生成默认 AGENTS.md 结构、在项目内创建好组织 skills 的目录。整个过程大约几分钟，属于“无脑下一步”式体验。我用它快速跑通了一个小工具项目，体验不错。
但如果你的场景是团队协作，我强烈建议用第二种方式——fork 官方仓库后手动配置。因为你肯定不希望团队里每个人的 AGENTS.md 内容各自漂移，今天张三改一版明天李四改一版，那项目行为就乱了。把 framework 和 skills 放进统一维护的仓库，通过 git 进行版本管理，再配合 CI 做文件完整性校验，这才是能规模化的方式。
团队用还有一种更轻量的思路：把整套目录结构打包成一个模板仓库，新项目直接基于模板初始化。团队里所有开发者的 Codex 行为就都一致了，遇到问题也好排查，因为你至少知道现场长什么样。
4.3 初始化后的目录结构长什么样
真正跑起来之后，项目的根目录下会多出若干个文件和文件夹，结构大致如下：
your-project/ ├── AGENTS.md ├── .superpowers/ │ ├── framework/ │ │ ├── AGENTS.md │ │ ├── codex_context.md │ │ └── workflow/ │ │ ├── task-lifecycle.md │ │ └── ... │ ├── skills/ │ │ ├── code-review.md │ │ ├── fix-bug.md │ │ ├── write-tests.md │ │ ├── ... │ └── memories/ │ ├── worklog.md │ └── decisions.log其中框架级的 AGENTS.md 定义的是通用行为准则，skills 目录下存的是各个子任务技能模板，memories 目录则用于记录跨会话的上下文信息。我在实际使用过程中有一个习惯，每完成一个比较有代表性的子任务，都会手动往 decisions.log 里追加一条记录，写清楚当时为什么选这个方案。Codex 在后续对话中会主动读取这个文件，我发现它引用决策记录时给出的建议，比完全“记忆空白”时要合理得多。
5. 实操演示：用 superpowers 完成一次典型编码任务
5.1 任务背景：为支付模块补齐单元测试
为了把实操过程讲清楚，我自己搭了一个很小的模拟项目，里面有一个处理订单折扣的计算模块，核心是一个 function，逻辑里包含会员折扣、满减叠加、折扣上限封顶。需求很明确：要先读代码理解清楚规则，再写一组覆盖各个分支的单元测试。
我把这个任务原原本本地丢给了 Codex，关闭了 superpowers 的状态，先看它默认表现。结果它也写出了测试，但用例覆盖很粗糙，只测了最普通的折扣路径，像满减与会员折扣叠加这种关键分支压根没覆盖到，边界值也没有处理。
接着我启用了 superpowers，重新把同一个任务跑了一遍。这次 Codex 的行为立刻就不一样了。它先是主动列出了资目录，读了模块源码，又翻了我项目里的测试配置文件，确认了测试框架版本之后，才开始动笔。整个过程它自己把控节奏，完全不需要我提示“先看代码再写”。
5.2 关键日志：看 Codex 如何自主决策
我当时把整个对话过程留了日志，其中几个关键节点特别能说明 superpowers 的作用。在动手之前 Codex 先是说了一句“为了准确理解折扣计算规则，我先读取订单模块的源码，并检查现有测试的覆盖情况”，这个动作在默认状态下是绝对没有的。默认的 Codex 更倾向于“你告诉我看哪个文件，我就看哪个文件”。
然后它写测试的时候，主动列出了场景清单，比如“注册会员 + 满 300 减 50，折扣上限封顶后实付金额是多少”。在最终交付之前，它自己执行了测试命令，发现有一个用例因为浮点精度问题失败了，就做了针对性的修复并重新跑了一遍，直到测试全绿才结束任务。
对比两个结果，最直观的感受是：默认的 Codex 是“秒回”，但往往华而不实；接了 superpowers 之后，响应速度略有下降，因为多了一道读文件和计划环节，但交付质量明显上了一个台阶，真正是“慢工出细活”。
5.3 参数卡与配置细节
如果你也想让你的 Codex 在这些关键行为上更贴合自己的偏好，可以手动去调整几个地方。
第一个是 skill 的 triggers 描述。每个 skill 文件的描述字段决定 Codex 在什么场景下会调用这个技能。比如默认的 fix-bug 描述是“用于分析并修复代码缺陷”，你如果想限定它只处理测试相关的 bug，可以改成“用于分析并修复测试用例相关的代码缺陷”，这样 Codex 的调用精度会明显提升。
第二个是 AGENTS.md 里的 root-level instruction。我建议在框架 AGENTS.md 文件靠前的位置加上一行“在执行任务前，必须先读取项目结构和相关文件”，这句话简单但管用，等于给整个会话定了个总基调。
第三个是测试的 baseline 配置。如果你的项目里已经有现成测试集，建议在 AGENTS.md 里写清楚“所有改动不得破坏现有测试套件”，这个约束对防止 AI 在重构过程中胡来非常重要。实测加了这句话之后，Codex 在执行任何修改前会自觉跑全量测试的概率大幅上升，而且就算时间来不及，它也至少会告诉你目前有多少测试没跑，把风险交回给你判断。
6. 常见问题与排查技巧实录
6.1 Codex 在任务中不读文件解决方案
如果你发现明明装了 superpowers，Codex 还是跟以前一样瞎猜，首先去检查 AGENTS.md 在项目目录里的层级位置是否正确。Codex 只会在当前工作目录或其上级目录中寻找 AGENTS.md。如果你把框架文件放在了项目根目录之下，但在子目录里启动会话，Codex 会优先读取子目录中的 AGENTS.md，如果没有，就回到更上层的。所以最稳妥的办法是保证根目录的 AGENTS.md 存在，并且里面明确写清“开始任务前必须阅读 xxx 文件”。
还有一种可能是 context window 太长导致 Codex 忽略了一些文件。项目比较大的场景下，AGENTS.md 里的内容写得太多太杂，反而会稀释真正重要的信息。我的经验是，根目录的 AGENTS.md 只写通用行为规范，控制在 60 行以内，具体模块的事项放到对应子目录单独写。这样 AI 每次读文件成本低，重点也突出，实际效果比一份超长文档好得多。
6.2 Skill 文件无法被识别排查
如果你发现自己新加的 skill 完全不触发，先检查文件头部的 metadata 信息是否写完整。superpowers 是通过解析文件头部 YAML 来决定何时调用该 skill 的，如果 description 字段写得模糊或者缺失 name，Codex 就可能找不到它。我见过有人把 description 写成中文“用于修复 bug”，但实际上框架的匹配逻辑依赖的是语义相似度，对中文的支持一般，最好在中英文描述之外再加一组 trigger keywords，比如 bug、fix、defect、issue 这些英文关键词。
改完 skill 文件后还有一个关键动作，就是要开启一个新会话。Codex 读取 skill 列表的时机在会话初始化阶段，你中途追加文件的话，当前会话是不认识新 skill 的。这个坑我踩过一次，一开始以为是文件内容写错了，排查半天才发现就是没开新会话。
6.3 性能变慢与消耗超预期
装了 superpowers 之后 Codex 响应速度变慢是正常的，因为它每次会话都会先读 AGENTS.md、扫描可用 skill 列表，任务如果涉及多步骤还会主动拉取多个文件。这种变慢只要在可接受范围就能忍。真正需要警惕的情况是任务本身不复杂，但 Codex 却疯狂读取项目里的一堆无关文件，导致 token 消耗暴涨。
这个问题的根源多半出在 AGENTS.md 里写了“读取项目全局”之类的描述上。我调整过一版比较温和的描述：“仅在任务涉及跨模块依赖时读取项目全局结构”，之后就明显好转。另一个技巧是在将项目加入 Codex 工作目录时，排除 log 目录、编译输出目录这类低频价值的文件，能减少不少无谓的 token 损失。实测在包含 1.2 万行代码的项目里，配置合理之后每次任务的 token 开销比混乱配置时下降了差不多四成。
6.4 多人协作时配置互相覆盖
团队场景下出现这个问题的概率很大。开发者 A 约定 skill 放在 A 目录，开发者 B 又习惯放 B 目录，结果两人在同一分支上工作，一提交就把对方的配置冲掉了。我的建议是把整个 superpowers 配置目录作为独立仓库管理，通过 submodule 或 vendor 方式引入到项目中，平时禁止直接改 main 分支的配置。
另外在团队里如果用 git 管理，记得在分支合并前做一次 AGENTS.md 的 diff review。这个文件决定整个团队 AI 助手的“性格”，改起来的影响面比业务代码都大，绝不能走“先合了再说”的路子。我自己吃过一次亏，团队里有人调整了 root-level instruction 之后合入主干，结果所有开发者本地 Codex 开始强行给代码补注释，风格变化大得让人措手不及。
7. 更进一步：如何基于 superpowers 定制自己的 skill
7.1 定义一个“团队规范检查” Skill 的过程
superpowers 的扩展性是我觉得它最好玩的地方。这里直接用一个实例讲解自定义 skill 的完整过程。假设我们团队强制要求所有对外接口的 HTTP handler 必须做入参校验，我就可以写一个叫做“检查 handler 入参校验”的 skill 记下来。
首先在 skills 目录下新建一个规范命名的 markdown 文件，文件名用 kebab-case。文件头部写清楚 metadata，描述里一定要带上“HTTP handler、参数校验、request validation”这类关键词，确保 Codex 正确识别调用场景。正文部分按顺序写执行步骤：识别 handler 入口、核对参数校验逻辑、检查是否存在绕过校验的路径、输出审查结果。
为了让 Codex 执行得更精准，还可以在步骤里加上“对比同模块内其他 handler 的常规做法”这一条，这样它就能基于项目既有风格做个“一致性检查”。我用了这个方法之后，发现它在 review 代码时给出的建议要比默认状态贴合团队风格得多。
7.2 Skill 文件中结构性描述模板参考
我把一个典型的 skill 文件结构模板放在这里，供大家直接改着用：
--- name: check-http-handler-validation description: Check HTTP handlers for input validation. Use when reviewing API endpoints or middleware that handle external input. triggers: - http handler - request validation - endpoint --- # Check HTTP Handler Validation ## Objective Ensure every handler validates all external input before passing it downstream. ## Steps 1. List all handler functions in the target file. 2. For each handler, check whether validation logic exists before business logic. 3. Identify any input fields that are not validated. 4. Compare with sibling handlers to confirm consistency. 5. Present findings in a concise table. ## Definition of Done - No unvalidated external input remains. - Findings are reported in the final response table.这套结构写完丢进目录就能用。我特别提一下 steps 编号的作用，AI 对这类型结构化指令的执行效果是最好的，你写的逻辑链条越清晰，它跑出来的结果越可控。要是没有步骤层级只有一大段描述，经常会出现执行完第三步忘了第五步的情况。
8. 不同场景下的效果对比与适用边界
8.1 适合的 vs 不适合的场景
为了让大家心里更有数，我这里直接用自己实测过的几类任务做个对比。
| 场景 | 默认 Codex CLI | superpowers 增强后 | 提升幅度 |
|---|---|---|---|
| 为已有模块补写单元测试 | 常遗漏边界分支和模块间依赖 | 自动读取实现，形成场景清单，主动补齐关键分支 | 明显 |
| 跨文件重构接口调用 | 只改当前文件，不感知调用方 | 主动搜索所有调用位置，逐处核对 | 显著 |
| 修复偶发崩溃 bug | 容易定位表层原因后草草修复 | 先读完整上下文再分析根因，给出多个方案 | 显著 |
| 快速生成一次性脚本 | 直接输出可运行代码 | 会额外检查脚本的依赖和环境上下文，略显多余 | 可能反而慢 |
| 写一个简单的 HTML 页面 | 干脆利落 | 会增加阅读工程结构等多余步骤 | 无增益 |
这张表是我个人很主观的经验判断，但也能看出一个规律：superpowers 的最大价值体现在“需要理解现有系统才能交付”的任务上，任务越依赖上下文，提升越明显；而对那些独立生成的绿手任务，它的优势就很不明显了，甚至还会因为多余的步骤破坏体验。
8.2 什么时候建议不要用这套方案
还有一种情况我也要提醒一下。如果你的项目还在非常早期的原型阶段，代码天天推倒重来，目录结构一个星期变两回，那装不装 superpowers 意义不大。因为它的核心能力依赖稳定的代码结构，如果上下文本身每天都在变，AI 读了也记不住什么，反而徒增配置项的维护成本。
真到了项目进入稳定迭代期，模块边界开始清晰，测试体系也基本建立起来，再引入这套方案就是性价比很高的决定了。
9. 结合最新热词：superpowers 社区的现状与趋势
最近“superpowers 使用指南”和“codex superpowers”这两个热词热度一直居高不下，背后的原因细心想想也不难理解。Codex CLI 的发布本身就把不少人的 AI 工作流从 IDE 插件迁移到了终端，而 superpowers 等于在大家正在寻找“如何让 Codex 更靠谱”的时候，递上了一套最优解，自然引发一轮研究高峰。
目前这个方案在 GitHub 上已经积累了不少讨论，仓库本身迭代得也挺快。社区里对它的评价总体很正向，也有不少人开始往里面贡献自定义 skill，形成了一个小小的生态。我在逛 issue 区的时候，经常能看到有人把自定义 skill 分享出来，比如“自动生成数据库迁移脚本”“自动分析 API 响应结构”。这种分享氛围让它的成长速度比我预想的要快。
坦白讲，当前这个领域还有一个很有意思的现象，就是大家不再单纯比拼底层模型的能力，而开始比拼基于模型的工程配套。superpowers 这套方案能不能成为行业标配还不确定，但它的出现确实给大家打开了一个思路：AI 编程助手的价值，从来不只是模型强，更重要的是你给它设计的那套“工作方法论”好不好。
对于刚接触它的开发者，我只有一个建议：别把安装它当终点，把它当作一个起点。先去理解它的行为框架，再根据自己项目实际情况去裁剪和扩展配置，折腾个一两天，你会有一种“原来 AI 编程还能这么编排”的感觉。
