我最早接触 Codex CLI 的时候感觉这东西确实比直接开个网页对话框强不少但你用得越久越会发现一个问题它每次开始干活都像失忆了一样明明上次已经调教好的编码风格、测试规范、项目约束下一次对话里它又忘了又得重新把上下文喂一遍。直到我试了 GitHub 上那套叫 superpowers 的开源技能包才意识到问题的本质不在模型能力而在工作流组织方式。这篇文章我就把自己从零开始安装、配置、实际用它写 Java 项目的完整过程写出来包括它内部的文件结构和触发逻辑是怎么设计的以及我踩过的那些坑。这套东西适合谁适合已经在用 Codex CLI、或者打算深度使用 AI 编程助手的开发者。如果你只是偶尔让 AI 写个爬虫脚本那可能用不太上但如果你是想让 AI 真正参与到日常项目开发里希望它每次都能按同样的思路处理问题、复用你沉淀下来的代码规范那 superpowers 这套东西几乎就是你现在缺的那块拼图。1. 项目定位与核心设计思路拆解1.1 superpowers 到底解决了什么问题先说个背景。OpenAI 的 Codex CLI 是个跑在终端里的编程代理你给它一个任务它自己会计划、写代码、跑测试、看报错、再改代码反复迭代直到搞定。这个形态听起来很理想但实际用起来有个特别别扭的地方每一次会话都是独立的。你上次告诉它“单元测试要用 JUnit 5 不要用 JUnit 4”“重构之前先跑一遍全量测试”“遇到编译错误先读日志再改代码”这些东西在下次会话里全都归零了。AI 编程助手缺的不是推理能力缺的是“稳定的工作习惯”。你可以把 Codex CLI 理解成一个能力很强但性格像金鱼的新同事你每次都要重新教他一遍做事流程。superpowers 就是针对这个问题诞生的它把“如何做计划”“如何调试”“如何写代码”“如何排查问题”这些方法论固化成了可复用的技能文件skills放进 Codex 的配置目录里让 AI 在每次会话中都能自动加载这些技能。这个项目原本是自动化交互小说里的世界观设定后来作者把它移植成了 Codex CLI 的插件式技能库。里面不止有硬核的调试、重构、性能优化技能还保留了小说世界观里的一些理念型技能比如“正念”“感恩”“非暴力沟通”这些。听起来有点玄乎但实际用下来你会发现这些技能是在约束 AI 的行为模式帮它建立一套稳定的做事原则效果比单纯堆提示词强太多。1.2 技能库的分层结构与触发机制superpowers 的技能不是一堆乱七八糟的 prompt 文件堆在一起它的组织方式是分层的这跟我们在工程里做模块化设计是一个道理。顶层是规则型技能定义的是 AI 的基本行事准则比如“在行动前先思考”“使用系统化方法解决问题”“分清事实与假设”这类元认知层面的约束。中间层是核心协作技能包括制定计划、分解任务、渐进式总结这些跨场景通用的能力。再往下才是具体的技术技能像写代码、调试、代码复现、浏览器操作、性能优化等等。最后是工作流技能把多个子技能串联起来形成完整的执行流程。这个分层最大的价值在于组合性。AI 接到一个任务后不是简单套用某一个技能而是会根据任务类型动态组合多个技能。比如让它修一个 bug它会先调用“制定计划”技能拆解任务再调用“调试”技能定位问题修复时调用“写代码”技能最后用“遵循规范”技能检查代码风格。每一层技能各司其职又可以通过前置条件互相引用形成一个完整的技能调用链。触发机制也很有意思。你不需要手动告诉 AI “现在请使用制定计划技能”技能文件里的前置条件描述会让 AI 在遇到对应场景时自动调用。这个原理类似于我们给 AI 准备了一堆工具每个工具描述了“当出现什么情况时应该使用我”AI 根据当前的上下文自己判断是否触发。实际用下来只要把技能文件放到位AI 的响应逻辑确实会发生明显改变它在动手之前会先输出思考过程和计划不再像以前那样直接甩代码。2. 环境准备与安装全流程实录2.1 安装 Codex CLI 并完成认证superpowers 依赖 Codex CLI 运行所以第一步是先把 Codex 装好。如果你之前已经装过可以直接跳到目录配置部分但如果你是从零开始这里我把完整步骤写一遍。# 安装 Codex CLI我用的是 npm 方式 npm install -g openai/codex安装完成后先验证一下版本确保装的是支持 skills 目录的版本。我当前用的是 0.37 版本这之后的版本基本都支持~/.codex/skills目录。codex --version然后是登录认证。Codex CLI 的认证方式有几种ChatGPT 登录、API Key、本地配置都行。我因为日常开发本来就要调 API所以直接用了 API Key 方式。需要注意的是不同认证方式影响的是计费渠道和可用模型不影响技能系统的工作逻辑。# 建议第一次直接运行 codex 进入交互界面 codex首次运行会提示你选择认证方式ChatGPT 登录或者 API Key 按提示操作就可以了。装好之后先随便给它发一条消息测一下连通性确认能正常返回再继续下一步。2.2 拉取 superpowers 仓库并部署技能文件接下来把 superpowers 仓库拉下来。这个仓库是开源的直接 git clone 即可。git clone https://github.com/obra/superpowers.git如果你 GitHub 拉取速度不太理想也可以直接去 Releases 页面下载对应版本的压缩包。不过我个人建议用 git clone之后想更新技能库可以直接git pull。拉下来后重点看两个目录skills目录放的是所有技能文件scripts目录里是构建脚本。部署的核心操作就是把skills目录里的内容放到 Codex 的技能目录里去。如果你之前没用过 superpowers本地可能还没有这个目录需要手动创建。# 创建技能目录 mkdir -p ~/.codex/skills # 把 superpowers 仓库里的 skills 内容复制进去 # 注意是把内容复制进去不是整个文件夹塞进去 cp -r superpowers/skills/* ~/.codex/skills/这里有个细节必须提醒copypaste 之后要检查目录结构确保~/.codex/skills下面直接就是各个技能文件夹比如writing、debugging、collaboration这些而不能多套了一层skills/skills。我第一次部署的时候就犯了这个错误结果 Codex 一个技能都没识别到。检查完结构后我还需要把你的项目级配置也处理一下。superpowers 的作者会在项目根目录生成一个AGENTS.md文件里面写了 Codex 应该如何配合这套技能系统工作。我的做法是把关键内容合并进自己的项目说明文件里避免和已有的项目配置冲突。这个后面在常见问题部分我会详细说。2.3 验证技能是否被成功识别部署完成后怎么确定技能真的装上了打开 Codex CLI随便问一句“你现在能用哪些技能”如果识别正常它会列出一堆技能名称包括写代码、调试、规划、重构等等。如果它回答“我没有技能系统”或者列不出来那基本就是目录结构出了问题。还有一种验证方式就是看日志。Codex CLI 启动的时候会扫描技能目录如果目录路径不对日志里会报告扫描失败或者扫描结果为 0 项。我那次路径错误就是靠看日志发现的。目录结构验证无误后还有一步初始化动作让 AI 建立“记忆文件”。superpowers 的技能系统里包含记忆机制AI 会在每次会话结束时把关键结论、项目约定写入 memory 目录。首次使用时你可以主动让它“请创建记忆文件并记录当前项目的技术栈和架构约定”这一步相当于给 AI 建立第一份项目档案之后每个会话它都会自动读取这些记忆实现跨会话的上下文连续。3. 核心机制拆解技能文件到底怎么工作3.1 SKILL.md 的解析与编写规范superpowers 里的每个技能都是一个目录目录里有一个SKILL.md文件外加一些辅助资源。这个SKILL.md的格式是 Markdown但头部带了 YAML frontmatter有点像我们写博客文章或者 Jekyll 页面时的配置头。frontmatter 里的字段不多最关键的是name和description。name是技能的唯一标识AI 靠这个来引用技能description是这个技能的“自我介绍”它描述了“什么时候应该使用这个技能”。这个 description 必须在开头就写清楚该技能适用的触发场景。--- name: 调试问题 description: 当代码出现报错、测试失败、程序异常时使用该技能定位问题根源并给出修复方案。 ---我看到很多人在自定义技能的时候不注意 description 的写法写得要么太笼统比如“用于调试”要么太具体只描述某一个 bug。正确的写法是描述“触发条件”什么时候该用、用来解决什么类别的任务。因为 AI 是根据语义来匹配技能的description 写得越精确AI 越能在合适的时机把技能调出来。SKILL.md 正文部分写的是技能的执行流程。superpowers 的正文往往是分段式结构从核心原则、执行步骤、到最后的效果校验层次分明。以写代码技能为例正文会先给出几条核心原则比如“遵循现有代码风格”“扩展而非重写”然后列出具体步骤先读需求文档、再制定修改计划、然后写代码、最后验证测试最后还要一个完成后自查的检查表。这个结构本质上是在约束 AI 的思考路径。3.2 子技能引用与技能组合机制superpowers 最有意思的设计是技能之间可以互相调用。一个技能文件的正文里可以写“前置条件需要先完成计划制定技能”这就等于让 AI 在执行本技能之前先去调用另一个技能。我举个例子collaboration协作技能是一个顶层技能它的执行流程里会要求 AI 使用“思考”技能来做深度分析、使用“计划”技能来制定实施步骤、使用“进度追踪”技能来管理任务状态。而每个被调用的子技能自身又可能有更细粒度的前置技能。这样就形成了一棵技能调用树。这套机制的价值在于你不用把每个技能写成一个包含所有步骤的巨型 prompt而是拆成细粒度的小技能再在需要的时候组合。真正的 AI 编程工作流跟我们在代码里做函数抽象一样把公共逻辑抽出来复用。如果你自己也想往 superpowers 里添加自定义技能强烈建议遵循这个原则每个技能只做一件事但做得足够深入通过前置条件和其他技能串联。技能调用并不是强制的指令式调用而是建议式的。AI 读到“前置条件需要先完成计划制定技能”这句话会理解为在执行当前步骤前应该先走完计划技能但它也有一定的自主判断空间。所以我个人的经验是如果想要某个调用是绝对强制的就把话写得更加绝对比如“不允许在制定书面的分步骤计划之前开始编码”效果比“建议先制定计划”要明显得多。3.3 起始工作流与记忆机制的价值superpowers 里还有一个starter工作流技能它相当于整个技能系统的启动入口。每次 Codex 开启新会话如果项目配好了这个工作流AI 会先执行它再接收用户的后续指令。这个启动过程包括读取记忆文件、理解项目背景、检查环境状态、确认目标和约束最后才开始干活。这就像给 AI 立了一套“晨会制度”。以前每次新会话AI 都是被一个问题直接砸醒然后迷迷糊糊开始输出代码现在它先花一点时间把上下文拉齐确定自己知道项目是干嘛的、技术栈是什么、有没有历史约定再开始思考具体问题。实测下来这一步确实让后续回答的准确率高了不少至少不会再犯“把 Java 项目当成 Python 项目来处理”这种低级错误。记忆机制是我觉得最值得借鉴的设计。技能系统里有一个专门的记忆技能AI 会在会话结束时总结这次做完了什么、发现了什么问题、哪些约定需要长期遵守并写入记忆文件。下次新会话启动时AI 会自动读取这些记忆。这本质上就是在给 AI 建立长期记忆。你可以把它理解成 AI 版的变更日志changelog只不过记录的不是代码变更而是上下文和决策记录。有一点需要注意记忆文件可能会在长期使用中逐渐膨胀塞满一堆过期的中间态信息。我自己会定期手动清理一下记忆文件把已经完成的项目和过时的决策删除只保留当前还需要遵守的约定。不然时间长了AI 读文件的速度变慢不说还可能被一些过时信息干扰判断。4. 实战记录用 superpowers 驱动 Java 项目修复4.1 问题场景与初始调用光说不练没有说服力。下面我用一个自己实际经历的场景完整走一遍 superpowers 的工作流程。当时我在改一个 Spring Boot 的库存服务模块遇到了一个典型的空指针问题。某些商品没有设置默认仓库在查询库存时会直接抛 NPE。这是一个很常见的问题但如果直接让 AI 修通常会得到一个“在调用处判空”的临时补丁治标不治本。我打开 Codex CLI给了它一个很简洁的指令“商品详情接口现在会抛空指针异常帮我定位根因并彻底修复。”如果是没有配置技能系统的 Codex它大概率会直接开始翻代码、找报错点、改两行代码完事。但在 superpowers 体系下它的响应方式完全不一样。它会先进入起始工作流读取项目记忆和仓库结构然后告诉你按照调试技能的流程先要复现问题再做根因分析。4.2 技能驱动的完整排查与修复链路我记得当时的会话过程大致是这样的AI 先调用调试技能要求我提供完整的异常堆栈和复现步骤。我把栈信息贴给它之后它没有马上说“这里没判空所以加个判断”而是先做了一个假设列表列出了几种可能的原因——实体类字段默认值问题、查询结果真的是空、映射层把 null 传给了业务层、或者前端传参本身就是空。然后它逐个验证这些假设。在验证过程中AI 使用了一个很关键的技能动作向我要测试用例或者运行测试。它自己在沙箱环境里写了几个单元测试来覆盖“未设置默认仓库时查询库存”的分支。测试通过红绿变化确认了根因InventoryQueryService里的warehouseMapper.findById()返回了null数据库里的库存记录存在但仓库记录因为外键失效导致查不到问题不在实体类字段而在查询链路的数据完整性边界。接下来 AI 进入修复阶段。这次它没有直接改业务代码而是先问了一个问题根据当前项目的代码规范这类“查不到关联数据”的情况业务层应该报错、返回空对象、还是使用降级逻辑它主动去查项目已有的异常处理规范和类似场景的历史处理方法。我是把 superpowers 里的代码规范类技能和项目AGENTS.md挂接在一起的所以它真的跑到AGENTS.md里查到了项目约定所有查询服务遇到关联数据缺失时统一抛出带业务码的BizException。最终代码修复分两步在查询逻辑中显式检查仓库对象是否为 null并抛出包含商品 ID 和仓库 ID 的带业务语义的异常在接口层的全局异常处理器中补充对该异常码的映射返回 404。修完之后 AI 还自动跑了一遍相关模块的测试并且更新了记忆文件记录了“库存模块的关联查询必须检查空值”这一条长期约定。4.3 修复前后的效果对比与经验沉淀修复前后最大的区别不是“NPE 没再出现了”这么简单而是整个处理过程的系统性。以前的 AI 修复是点状的报错在哪就改哪superpowers 加持下是链状的从复现、多条假设验证、根因确认、项目规范查询、修复实施、到回归测试全覆盖。从耗时上看第一次完整走这个流程确实比直接让 AI 改代码要慢多了至少 5 到 10 分钟的交互过程主要是排查假设、写测试、查规范这几步。但这次修复之后同类问题在库存模块里再也没出现过。如果还是以前那种“哪里报错改哪里”的思路我可能要反复修好几轮才能把整个链路都补上。而且那几条沉淀在记忆文件里的约定在后续所有有关库存模块的会话里都会自动生效这个长期价值无法估算。我自己复盘这次实操时有个体会superpowers 的核心价值不在于让 AI 变“聪明”而在于让 AI 变“稳定”。聪明是模型自己决定的稳定则完全依靠外部工作流系统的约束。把解决问题的方法论固化下来每次执行都走同一套流程产出的质量下限被大幅拉高了。5. 常见问题与避坑心得速查5.1 六个高频问题排查表我自己还有不少群友在安装和使用过程中踩过各种各样的坑有些问题几乎每换一个项目就会遇到一次。这里直接整理成速查表。问题表现可能原因解决办法Codex 完全不理会技能回复跟没装之前一样技能目录路径不对或者 Codex 版本过旧检查~/.codex/skills下直接是否就是技能文件夹确认 Codex 版本 ≥ 0.37技能识别到了但没有按流程执行项目的AGENTS.md没有关联技能系统或者配置方式冲突在AGENTS.md中加入调用规范说明让 Codex 在处理任务前先评估技能匹配情况技能调用链太长导致响应慢每次任务都要走太多技能步骤推理消耗大精简技能的前置条件避免不必要的深层嵌套记忆文件越来越大、越来越乱没有定期清理过期决策堆积定期手动清理记忆文件只保留当前有效约定更新技能库后自定义技能被覆盖直接复制时把自定义技能文件混在官方技能目录里自定义技能单独用custom_skills目录维护不要放进官方同名目录内AI 过度依赖技能、死板执行技能描述写得过于强硬调整技能正文的语气给 AI 留出一定的自主判断空间这六个问题是我最常遇到的其中有几个特别典型值得单独展开聊一聊。5.2 配置冲突与路径检查路径问题是第一关也是拦住最多人的一关。很多教程只说了要复制 skills 目录但没说清楚复制的是“内容”而不是“目录本身”。我第一次就是直接在~/.codex下把整个superpowers仓库链接过去了结果技能目录变成了~/.codex/superpowers/skillsCodex 扫描的时候什么都没找到。检查路径是否正确的办法很简单# 列出技能目录应该看到的是技能文件夹而不是其他嵌套层 ls -la ~/.codex/skills/ # 确认 Codex 日志里没有技能加载失败的信息 codex --debug另外Codex 版本太旧也会导致技能系统整个不可用。如果你确认路径没问题但技能还是不被识别先升级一下 Codexnpm update -g openai/codex尽量保持 Codex 是最新版本因为这个项目迭代很快技能系统的接口也在持续变化中旧版本可能无法解析新版技能文件的某些字段。5.3 技能更新与自定义维护策略superpowers 仓库更新很活跃隔三差五就会新增技能或者优化原有技能的描述。这本来是好事但如果你有自定义技能直接git pull或者重新复制就可能被覆盖。我自己维护了一套比较保险的方案官方技能和自定义技能分开放。我的做法是~/.codex/skills里只放从 superpowers 官方仓库复制来的技能自定义技能放在~/.codex/custom_skills目录里然后在技能目录里建一个软链接指向它。这样更新官方技能库时只重新复制官方目录的内容自定义技能完全不受影响。# 在官方技能目录里创建自定义技能的软链接 ln -s ~/.codex/custom_skills/my-custom-skill ~/.codex/skills/my-custom-skill还有一个值得提醒的点不要贪多把所有技能都装满。技能文件越多AI 在每次匹配的时候需要考虑的范围就越大决策时间会变长。我通常只装当前工作需要的技能写代码、调试、重构、测试、记忆管理、计划制定再加一两个项目特化技能。够用就好保持系统轻量。5.4 关于过度自动化的反思最后一个可能不算 bug 但值得反思的问题技能系统太强了会“过度自动化”。什么意思AI 一旦养成了“先做计划再写代码”的习惯即使你只是让它改一个文本拼写错误它也会认真走完整个流程包括读记忆、做计划、写测试、更新记忆。对真正大的任务来说这是严谨对小任务来说这就是浪费时间。我现在的处理方式是分场景使用。小任务直接用一个轻量的“快速任务”技能里面明确写了“不需要做正式计划、不需要写测试、直接执行并返回结果”重要改动才走完整技能链路。在项目AGENTS.md里写清楚“什么量级的任务应该走什么流程”这比每次手动控制 AI 要高效得多。另外一个深层的问题是过度依赖外部技能流程会不会让开发者的判断力钝化我的体会是关键在于你要不要理解技能的机理。如果你只是把 superpowers 当成一个黑盒装上去看到 AI 变乖了就什么都不管那确实会钝化。但如果你像我一样把技能文件一个个打开读一遍理解它是怎么描述任务、怎么编排步骤的那你其实是在把一套优秀的工程方法论外化出去这种情况下收获远大于损失。我个人在实际使用中最推荐的切入方式是先不装全量技能只装“制定计划”和“调试问题”这两个把一个已经熟悉的小项目交给它重构对比一下前后差异。等你理解了技能的运行机制再逐步把其他技能加进来这样才能真正掌控这套系统而不是被它牵着走。技能文件就像项目管理里的流程模板它存在的意义是保证下限而上限永远取决于你怎么用。