你可能已经发现最近AI编程圈的讨论热度突然集中在一个词上superpowers。无论是Twitter上的技术大V还是各种AI编程社群的聊天记录都在反复提到它甚至有人直接说“Codex加上superpowers才算完整”。这到底是个什么东西值得这么多人专门去安装、去研究、去写教程先说结论superpowers是给OpenAI Codex CLI设计的一套工作流增强包它通过引入“技能skills”的概念让AI编程助手从“你说一句它写一段”的被动工具变成能自己规划任务、修正错误、持续执行下去的主动工作流。简单类比一下原生Codex像一个聪明但需要你步步引导的新人而装上了superpowers的Codex相当于给这个新人配了一套完整的标准作业流程手册它知道自己该怎么拆任务、按什么顺序执行、遇到问题怎么排查。这篇内容我会从实际使用者的角度把superpowers到底是什么、怎么安装、日常工作流怎么跑通、以及我在Java项目里实际使用中踩过的坑和总结的经验一次性讲透。无论你只是听过这个名字想试试看还是已经装好但用不起来这篇文章都应该能帮你省下不少时间。1. 先说清楚superpowers到底解决什么问题1.1 原生Codex CLI的痛点过去几个月我一直在高强度使用Codex CLI说实话它确实能写代码但用得越深越能感觉到几个绕不开的问题。第一个痛点是上下文窗口的浪费。Codex的上下文窗口是有限的你让它做一件稍微复杂的任务比如“帮我实现一个带鉴权的用户管理模块”它可能需要你反复补充信息数据库用什么、框架是什么、鉴权要JWT还是Session、接口风格是REST还是RPC。这些对话来回会大量消耗上下文空间经常聊到一半前面的细节已经被挤出了窗口它就开始“失忆”前后逻辑对不上。第二个痛点是计划能力的缺失。原生Codex接到任务后倾向于“直接开写”而不是先想清楚怎么做。这在简单任务上没问题但一旦任务涉及多个文件、多个步骤它很容易写到一半发现方向错了然后推倒重来浪费大量token和你的耐心。第三个痛点是错误恢复能力弱。代码报错了它经常陷入“改一处、测一下、又报错、再改”的死循环缺乏一个系统性的排查机制。这些痛点单独拿出任何一个都好忍但叠在一起就会让人产生一种“AI写代码还是不如我自己来”的挫败感。1.2 superpowers的解法给AI装上“技能”superpowers的思路其实非常朴素但确实很聪明不要试图提高AI的智力而是给它一套可以做“程序化决策”的工作流。具体来说superpowers定义了一个“技能”的概念。技能是一组Markdown格式的文档每个文档描述了一个标准操作流程。例如“创建CLI应用”是一个技能“彻底测试”是一个技能“保存工作”是一个技能。这些技能文档会被放在一个特定目录下当你准备开始一项新工作时创建一个新目录并初始化superpowers环境AI会扫描这些技能文档然后根据你的任务描述自动选择并加载相关的技能。这意味着什么呢意味着AI不再靠“临场发挥”来工作而是按照一份经过验证的标准流程来执行。就拿“创建CLI应用”这个技能来说它会让AI先生成环境指纹和规划文档做出详细的实现计划然后才允许开始写代码。而且在执行过程中AI会定期检查测试、更新进度而不是一头扎进代码里不管外部状态。1.3 它和原生Codex的实际使用差异我用一个表格来说明两者的直观差异这样你就能快速理解为什么这么多人愿意折腾这个工具维度原生Codex CLICodex superpowers接任务后的第一反应直接尝试理解并开始写代码扫描技能库加载匹配的工作流面对复杂任务容易遗漏需求、上下文错乱先生成规划文档再逐步执行错误处理改一行测一次缺乏系统性有固定的检查点按流程排查跨项目复用每次都是“从零开始”技能文档可以沉淀和复用上下文管理指令信息来回占用窗口环境指纹、规则文件集中管理坦白说我用上superpowers之后最大的感受不是“AI变聪明了”而是“AI变得可靠了”。两者的区别很大聪明是偶发的可靠是可预期的。2. 安装与环境配置从零开始到跑起来2.1 需要准备的前置环境在动手安装superpowers之前先把环境检查一遍避免中途出错。Node.js 22.11或更高版本这是当前版本必须满足的条件低于这个版本会直接报错或者出现诡异的异步问题。Codex CLI本身需要先装好并且至少登录过一次确保命令行里能正常调用。Git用来克隆superpowers仓库。系统支持上macOS和Linux经过充分测试Windows用户建议在WSL2里运行纯原生的PowerShell环境会有一些兼容性问题后面我会细说。检查Node版本的命令很简单node --version如果你发现自己版本太低别犹豫去Node官网装LTS版本或者用nvm切一下nvm install 22 nvm use 222.2 安装过程记录安装流程其实只有三步克隆仓库、运行初始化脚本、配置Codex的AGENTS.md文件。第一步git clone https://github.com/obra/superpowers.git这里我建议你克隆到一个固定位置比如~/tools/superpowers因为后面配置里会用到绝对路径位置太随意以后自己都找不到。第二步是运行初始化脚本cd superpowers ./install.sh脚本运行过程中会做几件事把技能文件复制到~/.codex/skills目录下生成一个环境指纹文件配置一些默认的行为参数。装完之后验证一下技能是否就位ls ~/.codex/skills正常的话你会看到好几十个目录每个对应一个技能比如create-cli-app、save-work、test-driven-development、plan-ms-relationship等等。第三步是配置Codex CLI的规则文件。Codex CLI在启动时会读取AGENTS.md文件作为对AI的全局指示。superpowers要求你创建一个~/.codex/AGENTS.md内容大致指向它自身的规则文档请阅读 ~/.codex/skills/superpowers/AGENTS.md 来获取详细操作指南然后按照其中的指示执行。这样设置之后每次启动Codex它会先读到这行指示再深入去加载完整的技能规则。如果~/.codex目录下已经存在AGENTS.md记得手动合并一下不要直接覆盖以免丢失以前的全局配置。2.3 Windows用户的注意事项这算是这个工具的“历史遗留问题”目前版本对Windows的原生支持还不算完美。我同事在纯PowerShell环境下试过主要问题是脚本中的一些Unix命令比如cp、mkdir -p、source在PowerShell里要么行为不一致要么直接不存在。如果你的开发环境以Windows为主建议这样处理在WSL2里安装Ubuntu 22.04以上的发行版。Node.js、Codex CLI、Git全部装到WSL2里面。日常使用Codex时也通过WSL2的终端来操作。这样本质上就是一个干净的Linux环境所有安装步骤都能顺畅跑通。Windows本地的IDE依然可以访问WSL2里的文件系统通过\\wsl$\Ubuntu\...路径不会影响你的开发习惯。2.4 安装后的自检清单装完之后别急着干活先做一次快速自检确认环境是健康的在任意新建目录下运行codex看它是否提到“发现以下技能broader-context, check-environment, ...”。运行codex时给它一个简单任务比如“列出当前目录结构”看AI的回复是否正常且遵循了技能指引。查看~/.codex/skills/superpowers/AGENTS.md文件是否存在且内容非空。这三项都通过了说明安装基本到位可以开始正式的开发工作流了。3. 核心工作流三种速度档位与实操细节3.1 三种速度档位怎么选superpowers把使用方式划分成三个档位这个设计我觉得非常实用因为不是所有任务都值得走完整的技能流程。1倍速模式适合那种很简单、很直接的任务比如“帮我重构一下某个函数的命名”。在这个模式下你就像正常使用Codex一样直接描述需求它直接写代码不额外加载复杂技能。使用方式是在提示词里加上请使用1倍速模式处理以下任务。2倍速模式是日常开发的主流选择。它会让AI稍微做一点思考和规划后再动手适合大多数功能开发、修bug的任务。特征是AI会在动手前先列出一个简短的行动计划然后按计划执行。我在实际使用中大概有70%的时间都在这个档位。3倍速模式对应完整的superpowers工作流。AI会加载相关技能生成环境指纹创建规划文档按步骤推进执行过程中还会定期检查进度和测试。适合从零开始的模块开发、大型重构、研究型任务。使用方式是请使用3倍速模式处理以下任务或者直接说“请按superpowers标准的完整流程来”。这三个档位对应的核心区别在于“AI需要在多大程度上自主规划和决策”。3.2 每个项目开始前必做的事superpowers的规则中有一个核心动作建立新工作目录。它强烈建议每次新任务都在一个新目录中开启这样有几个好处环境指纹只针对当前任务不会被其他项目干扰。规划文档和执行文档有清晰的归属不会多个任务混在一起。后续保存工作技能可以准确识别哪部分文件属于哪个项目。新建目录的步骤是mkdir my-new-feature cd my-new-feature codex当你第一次在该目录中启动codex时它会引导你做一个简单的环境指纹初始化。环境指纹会记录当前的项目结构、技术栈、已有文件状态等。这样AI在后续执行任务时能基于环境信息做决策而不是完全依赖聊天的上下文。我在一开始忽视了这一步直接用旧目录跑任务结果AI经常把新任务的规划和旧项目的文件混在一起。后来养成新目录启动的习惯后整个流程顺畅了很多。3.3 保存工作这是最容易忽略但要命的环节在完整技能流程中有一个“保存工作”的技能这个设计看起来平淡无奇实际使用中才知道它有多重要。AI在执行长任务的过程中它会持续维护一份状态文件。这份状态文件记录了当前进度哪些步骤已完成、哪些待办、哪些测试通过了、哪些还没跑。当你执行到某个阶段想要暂停或者上下文被token限制需要开启新会话时它会先保存当前状态新会话启动时再读取这个状态文件实现无缝续接。实际操作中我的习惯是每完成一个阶段任务就让AI开启“保存工作”技能在进行下一步新任务前让AI先读取最近的状态文件避免在多个任务之间反复切换否则状态文件会互相覆盖。这个习惯帮我省了很多重新说明上下文的麻烦。有一次我连续做了三个小时的任务中途Context耗尽我本来以为要重新描述一遍需求了结果新会话一启动AI自动读取了状态继续往下走那一刻我真的觉得这个工具值了。3.4 技能库的正确使用方式superpowers默认带了几十个技能但实际开发中你不可能也不需要所有技能同时生效。它的技能选择机制是“按需加载”AI会根据当前任务描述匹配最相关的技能。比如你要做一个Java模块它可能加载“创建CLI应用”相关的技能来指导项目初始化你要修复一个bug它可能加载“测试驱动开发”相关的技能来规范流程。那么问题来了这些技能文档在哪里全部在~/.codex/skills目录下。每个技能都是一个独立目录内部有SKILL.md文件描述该技能的适用场景、执行步骤、输出要求。如果你觉得自己常用的工作流没有被覆盖完全可以照着已有技能文档的格式自己写一个技能。我之前就把团队内部的代码规范写成了一个技能文档这样AI在执行任务时就会自动遵循团队规范不需要我在每句话里反复强调。4. 实操案例用superpowers完成一个Java小任务这个部分我拿一个真实的例子来演示这样你能看到整个流程是怎么跑的。4.1 场景设定我需要在某个老项目里新增一个工具类用来生成带过期时间的临时令牌供接口鉴权使用。技术栈是Java 17 Maven项目里已经引入了Hutool工具库和JUnit 5。按照习惯我启动了一个新目录mkdir temp-token-generator cd temp-token-generator codexCodex启动后我先让它做环境扫描。4.2 AI的规划阶段我给出的任务描述是“请使用3倍速模式按完整技能流程实现一个Java工具类用于生成带过期时间的临时令牌要求在Java 17环境下运行使用Hutool的加密工具。”AI首先初始化了环境指纹然后生成了规划文档。我注意到它主动做了几件事读取了当前目录结构此时基本是空的判断这是一个新建模块需要初始化Maven项目结构确认了Java 17的特性可以正常使用比如记录类型、模式匹配、密封类等搜索了技能库中与“创建工具库”“单元测试”相关的技能。然后它给出了一个简要的执行计划初始化Maven项目结构生成pom.xml实现TokenGenerator类包含生成令牌和校验令牌两个核心方法编写单元测试覆盖令牌有效、令牌过期、令牌篡改三个场景运行测试确认通过保存工作状态。说实话看到它主动列出这个计划我的第一反应是很安心的。因为我知道后面的执行大概率不会跑偏。4.3 执行阶段的细节AI先创建了pom.xml。这个过程中它注意到了一个细节项目父级版本和Java版本需要对齐它自动选择了Java 17对应的编译器插件版本。然后创建了src/main/java和src/test/java目录结构。接着实现TokenGenerator类。关键的实现逻辑是生成的令牌包含用户标识、过期时间戳和签名三部分。签名部分用Hutool的HmacAlgorithm.HmacSHA256计算保证了令牌内容的完整性和防篡改性。实际生成的代码大约长这样public class TokenGenerator { public static String generate(String userId, Duration ttl, String secret) { String payload userId : (System.currentTimeMillis() ttl.toMillis()); String signature DigestUtil.hmacSha256(payload, secret).toString(); return Base64.getUrlEncoder().withoutPadding() .encodeToString((payload : signature).getBytes(StandardCharsets.UTF_8)); } public static boolean isValid(String token, String secret) { try { String decoded new String(Base64.getUrlDecoder().decode(token), StandardCharsets.UTF_8); String[] parts decoded.split(:); if (parts.length ! 3) return false; String payload parts[0] : parts[1]; String signature DigestUtil.hmacSha256(payload, secret).toString(); if (!signature.equals(parts[2])) return false; long expiresAt Long.parseLong(parts[1]); return System.currentTimeMillis() expiresAt; } catch (Exception e) { return false; } } }这里我额外提一点AI生成代码时主动用了Base64.getUrlEncoder().withoutPadding()这个细节很关键。因为URL安全Base64编码在拼接URL参数时不会产生和/字符也不会因为填充的号给参数解析带来麻烦。这种经验类的细节体现出了技能库中积累的“隐性知识”正在发挥作用。4.4 测试运行的收获代码写完进入测试阶段。AI的流程是先写测试再运行测试。它生成三个测试用例分别验证正常生成、过期令牌被拒绝、篡改令牌被拒绝。第一轮跑完之后发现“篡改令牌被拒绝”这个用例没通过。原因是一个很典型的坑JUnit测试里修改令牌内容但没修改签名而签名计算时包含了完整payload按理说签名不匹配应该被拒绝。我本来以为AI会直接修改断言逻辑来“强行通过测试”结果它没有。它打印出调试信息发现split(:)时出了问题因为Base64的URL安全编码结果可能包含-和_字符但冒号分隔符本身没有冲突真正的问题是测试代码中decoded.split(:)得到的parts数组长度不对。实际上它定位到是测试数据构造时拼接的字符串里含有多余的冒号导致split后数组越界用String.join(:, new String[]{...})之后问题解决了。整个过程大概用了几分钟期间我几乎没有干预这就是superpowers完整的错误恢复流程跑通的案例。4.5 保存工作与收尾最后一轮测试全部通过后AI按流程更新了进度文档并提示我可以保存工作。我让它执行了保存技能所有关键文件包括pom.xml、TokenGenerator.java、测试文件、状态文档都被记录下来。这个案例想说明的核心是在这个完整流程中AI的能力边界并没有突破它只是遵守了更好的工作习惯而这些习惯正是围绕任务组织好的文档化流程赋予给它的。5. 常见问题与避坑经验速查使用superpowers这段时间我在各种环境里遇到过不少问题这里整理成一张速查表每条都是实测过的经验不想踩坑的话建议直接收藏。问题现象根本原因解决方案codex启动后完全不加载技能AGENTS.md文件路径不对或内容缺失检查~/.codex/AGENTS.md是否存在内容是否正确指向superpowers的规则文件某些技能在任务中没生效技能库路径变了或技能文件损坏重新执行install.sh或手动补全~/.codex/skills目录下的文件Node版本不满足要求旧版本异步API不一致脚本执行失败使用nvm升级到Node 22.11升级后重启终端Windows下脚本执行报错Unix命令在PowerShell下不可用迁移到WSL2环境运行AI在长任务中开始“遗忘”早期规划上下文窗口溢出进度信息丢失使用保存工作技能在新会话中让AI读取状态文件再继续新任务的规划文档覆盖旧任务一直在同一目录启动codex每个新任务都创建独立目录确保环境指纹隔离技能文档太多选择混乱默认技能库覆盖范围广但未必符合个人场景编写自定义技能文档沉淀团队或个人的工作流规范codex运行时卡在初始化界面网络原因导致CLI无法正常连接后端服务检查网络连通性确保CLI能正常访问所需服务后重试5.1 重点关注的两个“坑”除了上面的速查表还有两个问题值得展开说。第一个是“不要在同一会话里频繁切换任务”。我早期的使用习惯是让AI在同一目录里先写一个日志工具再写一个缓存模块最后又让它优化之前那个日志工具。结果AI的状态文档互相覆盖进度记录张冠李戴整个上下文乱成一锅粥。自从养成“一任务一目录”的习惯后这个问题彻底消失了。第二个是“技能文档不是数量越多越好”。默认技能库有几十个技能但我实际常用的只有四五个。技能过多反而会增加AI的决策负担它需要在更多候选里选最合适的。我的建议是根据自己最常做的开发类型整理一份精简的“个人核心技能集”比如“创建CLI应用”、“测试驱动开发”、“保存工作”这三个必留其他的按业务需求补充即可。5.2 如何排查技能加载异常遇到AI没有按技能执行的情况可以依次做这几个排查动作看启动日志中是否有“发现以下技能”的列表。如果这个列表为空说明技能库读取失败。手动打开~/.codex/skills/superpowers/AGENTS.md确认文件内容能被人类正常阅读解析。在对话中直接问AI“你在初始化时读了哪些技能文档”有时它自己会告诉你漏掉了什么。检查Codex CLI版本是否为最新个别版本对AGENTS.md的解析有差异。6. 我的使用心得什么场景下它最能发挥作用最后说一下我在实际使用中总结的经验。superpowers在两种场景下价值最大化。第一种是从零开始搭建一个完整模块的时候AI能按流程生成规划、初始化项目、写代码、写测试、跑测试整个过程行云流水。第二种是功能迭代频繁的存量项目AI通过读取环境指纹和规则文件能在不依赖你反复解释上下文的情况下快速进入正确的工作状态。相对的不太适合用完整技能流程的场景是那种你在几秒钟内就能自己搞定的小改动比如改个变量名、调整一下注释。这种任务还用完整流程反而会显得嫌重。这也是为什么我会一直强调“按需选择速度档位”而不是所有任务都3倍速。另外我强烈建议把技能库当作团队资产来维护。我自己就是把团队的编码规范、接口设计约定、常见异常处理模式写成了自定义技能文档。这样每个新同事用AI干活时AI会自动遵循团队规范减少了大量重复性Code Review反馈。对我来说superpowers并不神秘它的核心贡献是让AI编程从一个“碰运气的实验”变成了一条“有章法的流水线”。工具本身还在快速迭代中但即便是现在这个版本已经足够让你的日常开发体验产生质的变化。如果你也在使用Codex CLI或者正准备尝试AI辅助编程花半小时装上superpowers再跑一轮真实任务这个投入一定值得。如果你在安装或使用中遇到了上面没提到的问题欢迎留言我尽量抽时间回复。