1. 项目概述Codex的超能力从哪来说实话我第一次看到superpowers这个项目名的时候心里想的是又一个中二味十足的开源项目。但等我真正把它装进Codex CLI里跑了两周之后我收回这句话。superpowers这个项目给AI编程助手带来的变化确实配得上超能力这三个字。如果你已经在用OpenAI的Codex CLI做日常开发大概率会遇到这么几个场景同样是让它改一个bug有时候它表现得像十年老架构师有时候又像刚毕业的实习生发挥非常不稳定你让它遵循项目里的代码规范它嘴上答应写出来的代码却还是自己那套风格你想让它执行一套固定的流程比如先写测试再写实现它总是做着做着就跳步骤。这些问题不是Codex本身笨而是你缺少一套系统化引导它的机制。superpowers就是来补这个短板的。简单来说superpowers是一个开源框架专门用来给Codex CLI注入持久化的行为准则、可复用的技能包和快捷命令。它不是要替代Codex而是站在Codex和你的项目之间把怎么跟这个AI助手协作这件事变成了一套有章法的流程。你可以把它理解为给一个聪明但散漫的实习生配上了一套标准作业手册和工具箱。装上之后你再跟Codex说帮我修复这个测试失败它就知道要先理解失败原因、再写最小修复、最后跑全量验证而不是瞎蒙一通。这个项目适合谁我认为最适合三类人一是深度使用Codex CLI、觉得效果时好时坏的人二是团队里想让AI辅助开发的流程标准化的人三是想研究怎么用AGENTS.md和技能文件体系来驯服AI助手的人。如果你是刚接触Codex的新手也可以装但建议先熟悉Codex的基本用法否则你很难分辨哪些进步是superpowers带来的。2. 整体设计与核心机制拆解2.1 三层能力模型superpowers最核心的设计思路是把给AI的指令分成了三个层级。理解了这个分层你基本就理解了整个项目的精髓。最底层是AGENTS.md规则文件它相当于宪法定义了AI在你项目里工作的所有基本原则。比如项目的技术栈是什么、代码风格偏好、构建命令有哪些、禁止做什么。这一层是持久的Codex每次进入项目都会读到。中间层是技能Skills它相当于一套SOP手册集合。每个技能是一个Markdown文件针对某类任务给出具体的操作步骤和决策依据。比如如何写单元测试如何做代码审查如何排查内存泄漏。技能不是全部都塞给AI而是按需加载——你在对话里触发某个关键词Codex才会去读对应的技能文件。最上层是命令Commands它是预定义好的对话入口相当于快捷宏。你输入一个斜杠命令比如 /reviewCodex就知道接下来要做一轮完整的代码审查流程自动调用相关技能和规则。这个分层设计的高明之处在于它没有试图一次性把海量信息塞给AI。做过大模型提示工程的人都知道上下文窗口是有限的指令越多AI越容易迷失重点。superpowers的做法是把指令分级缓存、按需加载让AI在每一刻只关注当前任务需要的知识。这个思路完全可以平移到我们日常写提示词的实践中。2.2 AGENTS.md规则系统AGENTS.md这个概念现在已经被很多AI编程工具接受了它本质上是一个给AI看的项目说明书。superpowers对这套系统的增强在于它不仅仅让你写规则还提供了一整套规则模板和加载机制。在官方推荐的目录结构里你的项目根目录会有一份根级AGENTS.md定义了全局规则。如果你在子目录里再放AGENTS.mdCodex进入那个子目录时就会合并加载。这非常像我们在工程里做的配置分层全局配置做兜底局部配置做覆盖。我自己的项目里根级AGENTS.md会写这些东西项目语言和框架、包管理器、测试命令、代码风格要点、禁止事项比如不允许生成没跑过的代码、依赖引入规范。有个容易忽略的细节是AGENTS.md里不要写空泛的口号比如写出高质量的代码——AI不会因为这句话而改变行为。你要写的是可验证的、具体的指令比如所有新增的函数必须附带Javadoc它才能严格执行。superpowers自带了一套AGENTS.md初始化模板覆盖了工程配置、代码风格、安全注意事项等项目必备条款。你只要照着模板删改就行不用从零开始想。2.3 Skills技能系统如果说AGENTS.md是宪法那Skills就是案例库。每个技能文件都是一份Markdown文档里面用结构化语言描述了面对某类任务时应该怎么做决策、按什么顺序执行、有哪些坑要避开。superpowers内置了不少技能我挑几个印象深刻的代码审查技能会给出审查清单和分级标准、测试驱动开发技能强制先写失败测试再写实现、调试技能教AI用科学方法二分定位问题、重构技能小步重构、每步都跑测试。这些技能的质量相当高明显是作者从实际工程经验里提炼出来的不是随便写写的套话。技能的加载机制很有意思它在对话里靠关键词触发。举个例子我在对话里提到修复这个bugCodex会自动匹配到调试技能然后它就会按照调试技能里的方法执行。如果你不想用技能也可以关闭这个自动匹配。触发之后技能内容会作为上下文注入AI的思考方式会明显向技能文件里描述的方法靠拢。这个机制解决了一个很实际的问题你不需要每次都在对话里重复叮嘱AI该怎么做。技能文件写一次永久生效而且所有项目都能复用。我现在自己的技能库里大概积累了几十个自定义技能覆盖代码审查、SQL优化、Docker镜像瘦身、接口文档生成这些高频场景每次让AI干活之前它都会自动带上对应的作战手册。3. 安装与快速上手3.1 环境要求安装superpowers之前你需要先准备好两样东西一个能正常运行的Codex CLI环境以及Git。Codex CLI的安装方式我这里不多啰嗦官方文档里有很详细的说明核心是安装之后要完成登录认证确保在终端里执行 codex 能正常对话。还有一个容易被忽略的准备工作确认你的Codex版本不要太旧。superpowers的一些功能依赖Codex对AGENTS.md和技能的加载特性如果你用的是非常老的版本可能加载机制都不一样。我建议在装superpowers之前先把Codex升级到最新版本省得后面踩一些莫名其妙的版本坑。系统方面macOS和Linux都没问题Windows用户我建议用WSL2来跑因为整个工具链在Windows原生终端下的行为偶尔会有细微差异文件路径、软链接这些都可能出问题。3.2 安装步骤安装流程并不复杂我在一个干净的Ubuntu环境上完整跑过一次整个过程五分钟以内。大致分三步。第一步把项目仓库拉下来。这个项目的GitHub仓库地址我放在后面说明里。你不需要fork直接clone主仓库就行反正技能文件自己也会不断增删。git clone https://github.com/obra/superpowers.git cd superpowers第二步运行安装脚本。脚本会做的事情是在Codex的配置目录里建立好技能目录、命令目录的软链接或者拷贝把核心AGENTS.md放置到合适的位置完成初始化。有些环境下它会问你要不要设置默认的Codex配置文件我建议你选择是除非你已经有一套非常个性化的配置了。./install.sh第三步验证安装结果。装完之后进入任何一个你准备用Codex开发的项目目录打开Codex CLI在对话里问它一句你有哪些可以使用的技能。如果它能列出一串技能名称说明加载成功了。我发现一个更直观的验证方式直接在对话里触发一个技能关键词比如review this code看它的输出是不是明显带上了一种结构化的审查逻辑。如果是说明技能真的被触发了。3.3 初始化与验证到这里其实还没完。superpowers装了只是第一步关键是每进入一个新的项目目录Codex需要知道这个项目的AGENTS.md在哪里。所以你在每个项目里要么在项目根目录放一份AGENTS.md要么让Codex能往上找到全局规则。实操中我更推荐的做法是项目根目录放一个精简版的AGENTS.md专注写项目特定的技术栈和命令全局的、跟技能相关的规则交给superpowers管理。这样层级清晰各管各的。验证阶段的几个常见检查点我也列一下检查技能目录里是否有内容确认软链接生效。检查Codex对话里是否能列出技能清单。跑一次简单的任务比如请对这个项目做结构分析看它的行为风格是否和装之前有明显不同。我自己刚开始安装的时候犯过一个低级错误clone下来之后忘了运行安装脚本直接就在项目里开Codex然后用了一会儿觉得这不是跟之前一样吗。后来才反应过来规则文件都没有落盘等于白装。所以安装完之后一定先验证别急着干活。4. 核心功能实操与实战配置4.1 开发模式让AI深度参与日常开发superpowers有一个让我觉得真正提升了开发体验的功能是它把AI的使用方式分成了几种开发模式。在普通问答模式里你问一句它答一句适合查API、问概念。但在开发模式里它会表现得像一个搭档你告诉它当前项目的状态、需要实现的目标它自己会拆解任务、读相关文件、按技能执行、给出可提交的改动并在最后用测试验证自己写的代码。我实际用下来的感觉是切到开发模式之后Codex的主动性明显增强。它会自己去看项目结构而不是等你喂代码片段写完代码会主动跑测试遇到不确定的地方会停下来问你而不是闷头瞎写。这套行为逻辑不是神奇的魔法就是靠AGENTS.md里的规则一句一句约束出来的。启动开发模式的方式有两种一种是进入Codex之后用斜杠命令切换另一种是在项目AGENTS.md里默认设置。如果你主要是想拿Codex当结对编程伙伴用我建议直接在项目里默认开启开发模式省得每次手动切。在Java项目里用这个模式特别爽。我维护的一个Spring Boot老项目模块多、依赖关系乱之前让Codex改代码时常踩到别的模块一跑测试就炸。开了开发模式、配好技能之后它干活前会先花时间摸清模块依赖图改动前还会检查影响范围。当然这不是绝对可靠但出错率确实降低了一大截。4.2 自定义技能实战为Java项目定制专属作战手册很多人的使用误区是装上superpowers之后觉得自带技能够用就行。但真正让这个工具产生质变的是你会写自己的技能文件。我拿一个Java项目的实际例子来说说怎么定制。比如我经常处理升级依赖版本这种活。以前让Codex升级某个Maven依赖它总能升级成功但经常忽略兼容性问题比如某个API在新版本里废弃了或者某个传递依赖跟现有的库冲突。这些坑每次都要我事后提醒。后来我写了一个升级Java依赖的技能内容大致包括先读取pom.xml确认当前版本和目标版本。检查目标版本的Release Notes里是否有breaking changes。升级后执行mvn test compile找出编译错误。逐个解决编译错误优先使用官方迁移指南里的方案。跑全量测试重点关注改动涉及模块的上下游模块。最后生成一份变更说明列出升级影响。写技能文件的时候有个核心技巧描述步骤时要具体但不要过度约束。你不需要告诉AI第2行代码怎么改你只需要告诉它采用什么策略、避开什么坑、验证什么指标让它在执行细节上有发挥空间在方向和准则上没有自由度。写完技能文件之后把它放进技能目录然后在对话里触发它对应的关键词。比如我把上面这个技能的关键词设为upgrade-dependency。之后只要在对话里提到升级依赖Codex就会自动加载这套流程。实测下来升级依赖这件事的返工率低了很多我不用再跟在后面检查它漏没漏跑测试了。4.3 命令系统把复杂流程变成一句话命令系统是superpowers的另一个效率利器。你可以把一串操作打包成一个斜杠命令。以我自己为例我最常用的是 /tdd 命令流程是读取需求描述、按照测试驱动开发的节奏先写失败测试、实现最小代码、跑测试变绿、重构执行任务每完成一个节点都要做一次状态汇报。以前我需要在对话里打一大段话让Codex按TDD来写现在只需要敲一个斜杠命令。另一个高频使用的是 /review 命令它会执行一轮代码审查先列出变动的文件清单然后逐个文件分析按正确性、性能、安全、可读性、测试覆盖五个维度输出问题列表最后给出修改建议和优先级排序。这个命令的输出质量非常高我已经把它固化到了团队的日常开发流程里。自定义命令也不复杂。原理很简单命令本质上就是一串预设好的提示词当你敲下斜杠命令时系统会把后面的内容拼接成一个完整的请求连同相关技能一起喂给Codex。你只需要按照模板写好命令定义文件即可。命令和技能配合起来效果是叠加的。命令负责发起流程技能负责流程中每个环节的执行细节。这个设计有点像把朴实的宏和函数库绑到一起用。4.4 AGENTS.md里的Java环境配置模板针对Java项目我分享一个我已经跑顺的AGENTS.md片段你可以直接参考着改。# Java 项目规则 ## 环境信息 - 语言版本: Java 17 - 构建工具: Maven 3.9 - 测试框架: JUnit 5, Mockito - 项目管理: 多模块Maven项目根目录包含父pom.xml ## 工作流程 - 每次修改代码前先明确依赖模块避免破坏模块边界 - 所有变更必须先通过 mvn test 后再提交 - 遇到测试失败时先阅读失败日志定位根因禁止盲目修复 ## 代码风格 - 遵循项目已有的Checkstyle配置 - 新增公共API必须附带Javadoc说明 - 禁止引入未在pom.xml中声明的依赖这个模板的作用是给Codex划定一个清晰的工作边界。写规则的时候注意顶部的环境信息很重要因为Codex在不知道技术栈的情况下常常会做出错误的默认假设。比如你没告诉它这是个Maven多模块项目它可能会只编译当前模块的代码然后自信地说测试全通过了实际上别的模块早就被你改坏了。5. 常见问题与排查技巧实录5.1 安装阶段的问题我见过最多的安装问题是技能目录没有正确地链接到Codex的配置目录。表现是安装完superpowers后进入Codex输入命令想看技能列表结果一片空白一个技能都列不出来。这个问题的根源多数情况下是安装脚本执行时Codex的配置目录还不存在。Codex CLI通常是在你第一次运行它的时候才创建配置目录的如果你先装了superpowers再运行Codex脚本可能找不到目标目录技能链接自然就不存在了。解决办法也很简单先手动运行一次 codex 命令让它完成初始化创建目录然后再重新执行superpowers的安装脚本。我遇到这类问题第一反应永远是重跑一下安装脚本十次有八次能解决。还有一个环境坑个别Linux发行版的软链接行为不一样导致技能文件是拷贝而不是链接过去的。这时候你后续更新superpowers仓库里的技能文件本地的副本不会跟着变。建议装完之后查一下本地技能目录里的文件是不是软链接——如果显示的是普通文件确认一下安装脚本当时是不是用了复制模式。为了保持可更新性我宁愿删掉重链也不想用拷贝的版本。5.2 配置阶段的问题配置阶段最大的坑是AGENTS.md写得太长太杂。我一开始恨不得把所有规范都塞进去结果Codex的行为变得笨拙且犹豫——它每写一行代码都要想想自己的行为是不是违反了哪条规则创造力反而被束缚了。后来我学到一个原则AGENTS.md里只放不可违背的硬约束比如技术栈、构建命令、禁止项把如何做一件具体的事的方法论都放到技能文件里。这样规则文件短小精悍AI注意力不分散技能文件又能保证在需要的时候才加载。还有一个小细节容易被忽视AGENTS.md换行和特殊字符。Codex解析Markdown的时候有时候会把某些特殊符号当作格式符号处理导致规则没有按预期生效。我碰到过一次AGENTS.md里的某个代码块因为反引号嵌套错误让Codex整个理解错乱了。排查的方法是在Codex对话里直接问它当前项目的AGENTS.md里写了哪些关于测试的要求如果它答不出来或者答错了基本可以断定是文件格式有问题。5.3 使用阶段的问题使用阶段我遇到最多的问题是技能没有被触发。你明明在对话里提到了关键词但AI好像完全没看到技能文件。排查思路其实很标准。第一步确认技能文件确实放在了正确目录并且文件名格式没问题。第二步确认关键词在技能文件的元信息里声明过。第三步在对话里直接问AI你现在正在使用哪些技能看它能不能正确列举——能列举但没执行说明是理解层面偏差不能列举说明是加载机制出了问题。我自己遇到过一次很隐蔽的问题我在两个技能文件里设置了同一个关键词后来发现Codex每次只加载其中一个而且不一定是我想用的那个。从那以后我给自己定了个规矩每个关键词全局唯一技能职责边界清晰宁可多写几个技能文件也不要一个技能文件里塞一堆杂活。最后再分享一个使用心得superpowers不是装了就不用管的工具它需要随着项目的演进持续维护。技能文件要不断新增、修正、删减AGENTS.md要根据项目实际情况调整。我每周都会花一点时间翻看一下这周让AI干活时有哪些地方不顺把经验沉淀成新的技能规则。用久了你会发现这才是superpowers真正的超能力——它逼着你把自己对工程的理解逐步固化成一个AI搭档能读懂、能执行的体系。这套积累比任何单个技能文件都有价值。