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 在任务中不读文件解决方案如果你发现明明装了 superpowersCodex 还是跟以前一样瞎猜首先去检查 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 字段写得模糊或者缺失 nameCodex 就可能找不到它。我见过有人把 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 定制自己的 skill7.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 CLIsuperpowers 增强后提升幅度为已有模块补写单元测试常遗漏边界分支和模块间依赖自动读取实现形成场景清单主动补齐关键分支明显跨文件重构接口调用只改当前文件不感知调用方主动搜索所有调用位置逐处核对显著修复偶发崩溃 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 编程还能这么编排”的感觉。