superpowers：给Codex CLI注入研发技能，让AI编码代理告别“失忆”

如果你现在打开 Codex CLI直接丢一句“帮我把这个支付模块重构成策略模式”它能干但大概率干完你还得自己重写一遍——因为它不知道你项目里有哪些约定不理解你说的“重构底线”是什么也没有“先补测试再动手”的肌肉记忆。这就是我最近半年重度使用 AI 编码代理后最真实的感受模型很聪明但默认状态下它就是个“聪明但失忆的实习生”。所以当我在 GitHub 上看到 superpowers 这个项目并且发现它的核心思路是“给 Codex 注入可复用的技能文件”时我几乎是一瞬间就理解了它为什么能火。简单说superpowers 是一套面向 Codex CLI 的开源技能框架它把 TDD、代码评审、复盘、文档编写这些研发实践编码成一个个 Markdown 格式的“技能包”让 Codex 在动手之前先读技能、再按方法论执行。这篇内容就围绕 superpowers 的使用指南、安装方式、核心机制和自定义技能展开适合正在用 Codex 写代码、但觉得 AI 输出“差点意思”的开发者也适合想给团队 AI 协作流程立规矩的工程负责人。1. superpowers 是什么一个给 Codex CLI 注入“肌肉记忆”的技能框架1.1 裸 Codex 的痛点聪明但失忆的实习生先说一个我自己的例子。有一段时间我每天用 Codex CLI 修小 bug指令写得很清楚“改这个函数、保持接口不变、补上错误处理”。Codex 每次都能改但它从不主动问我“这个函数被哪些地方调用了”“错误处理的项目规范是什么”更不会自觉补一个回归测试。结果就是单看 diff 没什么大问题但合并进去之后下一次迭代立刻感受到技术债在堆积。这不是模型能力不行而是使用方式出了问题。Codex 默认是一个无状态的对话代理你给它一个任务它就从当前聊天的上下文里猜你的意图。你项目里沉淀的代码规范、测试策略、重构边界、评审清单它一概不知。你可以把这些写成一大段 prompt 塞给它但 prompt 会随着对话变长而稀释而且每次新会话都要重新灌输一遍。superpowers 解决的就是这个问题。它的核心思路特别朴素把“有经验的工程师在动手前会做的那套动作”固化下来变成 Codex 每次开工前都必须阅读的 Markdown 文件。这些文件被称作技能skill存放在项目的src/skills目录下Codex 启动工作流时会先读技能、再干活从根上改变“上来就写代码”的坏习惯。1.2 superpowers 的解法把方法论变成可复用的技能文件superpowers 的作者是 Jesse Vincent这人在 Perl 社区和自动化测试领域很有名。他做这个项目的出发点很直白他不想每次都跟 Codex 重复解释“我们团队怎么做代码评审”“我们定义什么样的功能算完成”而是想让 Codex 像一个入职三年的老员工自己知道该按什么流程做事。具体实现上superpowers 被组织成一个 npm 包你可以在项目里执行npx --yes superpowerslatest init把它装进项目。装完之后项目下会出现src/skills目录里面有一堆SKILL.md文件每个文件就是一个技能。Codex 在处理任务前先读相关技能文件按里面的步骤和约束执行。这套设计的高明之处在于技能文件不是代码而是纯文本的 Markdown任何人都能读、能改、能写。你不需要会 Rust 或者学一套 DSL只需要用自然语言把“怎么做一件事”的步骤写清楚Codex 就能照着执行。这意味着技能库是活的团队完全可以根据自己的工程实践沉淀独有的技能而不是被工具厂商绑死。1.3 适用人群与含金量判断什么人适合用 superpowers我觉得分三类。第一类是已经在用 Codex 写生产代码的开发者你对 AI 输出质量不满意但又说不出到底哪里不对那 superpowers 能帮你把“质量预期”显式化。第二类是技术负责人你希望团队里所有人都用同一套 AI 协作规范而不是十个人有十种 prompt 风格把技能文件放进仓库就能做到统一。第三类是搞工具链研究的工程师你会对“怎么把工程方法论编码给 AI 执行”这个话题本身感兴趣。不过我也要泼一盆冷水superpowers 不是银弹它不会让 Codex 突然拥有更强的推理能力。它的本质是行为约束和上下文注入深度还是模型本身的深度。但同等模型条件下有技能约束和没技能约束的输出质量差距我用下来的感受是至少差一个档次。2. 安装与初始化5 分钟让 Codex 拥有技能库2.1 前置环境准备在开始安装之前先确认环境是否满足条件。superpowers 是围绕 Codex CLI 设计的所以第一步是装好 Codex CLI 并确保能正常对话。Codex CLI 的安装通常通过 npm 完成安装后你要有可用的 API 密钥或认证方式因为后续所有技能调用都发生在和 Codex 的会话里。Node 版本方面建议用 Node 18 以上npm 版本别太旧。我自己在 Node 20 环境里跑得很稳。这里有一点容易踩坑如果你之前装过旧版 Codex CLI最好先确认版本是新的因为 superpowers 的初始化脚本会调用 Codex 的某些配置能力版本太老会出现技能文件写进去了但 Codex 不读取的诡异问题。另外建议在 git 仓库里操作。superpowers 初始化会在项目里生成src/skills目录并改动配置文件这些改动最好通过 git 来追踪。如果你直接在一个已存在的生产项目里初始化我建议先建分支再做方便不满意就回滚。2.2 安装 superpowers 的三种方式第一种也是最推荐的方式直接用 npx 初始化npx --yes superpowerslatest init执行后脚本会检查当前目录然后创建或更新src/skills目录并写入默认技能包。命令跑完后你会发现多了几十个SKILL.md文件包括 boot、docs、review、test-driven-development、refactoring、post-mortem 等。第二种方式是全局安装 npm 包适合你在多个项目里都要用的情况npm install -g superpowers superpowers init第三种方式是把 superpowers 作为 git submodule 引入适合团队统一维护技能库的场景。这种方式的好处是技能文件可以随项目仓库一起评审、迭代坏处是更新起来比较麻烦需要手动拉取子模块。我个人体验是单人开发用第一种方式最省事团队协作用第三种方式更规范。2.3 初始化项目并验证技能生效初始化完成后最关键的一步是让 Codex 真的“看到”技能。superpowers 的设计里Codex 默认不会主动读技能需要你在会话中给出指令。最常见的启动方式是在新对话开头说一句话比如请先阅读 src/skills 下的相关技能然后按技能要求处理下面的任务修复登录接口的超时问题。Codex 在接下来的会话里会先读取src/skills目录里和任务相关的SKILL.md比如test-driven-development或coding-agent然后按照里面写的步骤来执行任务。验证是否生效有个小技巧你故意不提任何要求只让 Codex “开始处理这个 bug”如果它能主动问你要复现步骤、要相关测试、要先写失败用例说明技能已经被正确加载了。如果它的行为和没装技能前一模一样那就要检查技能文件路径和调用指令是否写对了。提示不要在初始化后直接问 Codex “你有哪些技能”因为它不一定能完整列出。更可靠的方式是打开src/skills目录自己看文件列表。3. 核心机制深度拆解技能如何改变 Codex 的行为3.1 SKILL.md 文件规范frontmatter 步骤化内容理解 superpowers 的核心就是理解SKILL.md文件格式。每个技能文件都是一个 Markdown 文档最顶部是 YAML frontmatter包含技能名称、描述和触发条件后面才是正文。下面是一份标准技能文件的骨架--- name: test-driven-development description: 在实现任何功能之前先编写失败的测试用例并确认其失败原因 --- # TDD 技能 ## 使用场景 - 新增功能 - 修复 bug - 重构代码 ## 执行步骤 1. 编写一个预期失败的测试用例 2. 运行测试并确认失败原因符合预期 3. 编写最小实现代码 4. 运行测试并确认通过 5. 重构并保持测试持续通过注意看这里的关键设计技能文件描述的不是模型能力而是行为规范。Codex 读到这个文件后会按照步骤 1 到 5 依次执行而不是凭自己的“习惯”自由发挥。你完全可以把团队内部的编码规范、提交信息格式、接口设计约定写进SKILL.md让 Codex 每次开工前都先复习一遍。还有一点值得注意技能文件里的描述越具体Codex 执行得越准。比如“编写测试”这种描述是模糊的“使用 pytest 编写测试测试文件放在 tests/ 目录覆盖正常路径和异常路径”这种描述才能稳定产出。这也是我用了一段时间后觉得最应该优化的方向——不是技能越多越好而是每条技能的指令颗粒度是否够细。3.2 子代理模式让多个 Codex 并行协作superpowers 里另一个很有想象力的机制是子代理subagents。它允许你在一次 Codex 会话里让模型扮演多个角色并行推进任务。听起来很玄实际实现也不复杂你把一个任务拆解成多个子任务每个子任务对应一段独立的对话上下文Codex 在子代理之间切换时各自保持各自的进度和信息。举个具体例子。假设我要重构一个订单模块我会让 Codex 同时开三个子代理一个负责分析现有代码、画出依赖关系一个负责编写迁移方案一个负责补测试。三个代理互不干扰最后我把三份结果合并起来做最终决策。这个模式解决了一个此前很头疼的问题Codex 在长对话里会逐渐丢失早期上下文而子代理相当于给每个任务开了独立的“窗口”有效避免上下文污染。不过子代理模式也有使用门槛。它需要你在技能文件里明确写出“什么时候该创建子代理”“子代理之间如何交接”否则 Codex 会陷入选择困难。我在实践中发现写出清晰的子代理分工比让 Codex 自己决定分工可靠得多。也就是说子代理机制本身不是魔法真正起作用的是你定义的组织方式。3.3 内置技能库地图从 boot 到 post-mortem初始化 superpowers 之后你会得到一套默认技能我建议先通读一遍。下面是我实际用下来觉得最有价值的几个技能以及它们各自解决什么问题技能名称解决的问题使用频次boot在开始任务前先了解项目结构、技术栈、构建方式每次会话test-driven-development用 TDD 流程约束功能开发避免直接写实现代码高频docs统一文档结构和更新策略避免文档散落中频review以评审者视角审查改动寻找边界条件和隐患高频refactoring明确重构的安全边界和步骤避免顺手改坏逻辑中频post-mortem组织故障复盘产出可执行的改进项低频拿boot来说这个技能让 Codex 在和项目“初次见面”时先做侦察。它读 README、看 package.json 或 pom.xml、梳理目录结构然后输出一份项目概览。有了这一步后续任务的质量会明显提升因为 Codex 至少知道自己在跟什么代码打交道。post-mortem则是我觉得最有“团队味”的一个技能。它让 Codex 按一套固定的复盘框架去分析故障而不是笼统地说“下次注意”。它会引导产出时间线、根因分析、影响范围、改进措施甚至自动把改进项拆成可执行的任务。这个技能特别适合团队引入因为复盘质量直接决定了一次事故到底只是事故还是变成了组织资产。4. 实操构建你的第一个自定义技能4.1 自定义技能的应用场景选择很多人看完默认技能后的第一反应是“我能不能自己写一个”。答案是当然可以而且我认为自定义技能才是 superpowers 真正拉开差距的地方。默认技能解决的是通用问题而你的项目一定有默认技能覆盖不到的专属痛点。我建议从高频且重复的痛点入手。比如你们项目规定所有对外 API 必须包含版本前缀、所有数据库操作必须走仓储层、所有新功能必须有性能测试基线。这些约束如果你通过 prompt 每次手动说一定会漏但写进一个project-rules技能文件里Codex 每次开工前都会看到。另外一个好的候选场景是“错误处理规范”。很多 AI 生成的代码在错误处理上很随意要么吞掉异常要么到处 catch 打日志。你可以写一个技能明确规定哪些异常应该抛出、哪些应该包装、错误消息的格式是什么。这类技能带来的提升比让模型“更聪明”要直接得多。4.2 手把手编写一份技能文件写技能文件本身不需要代码能力但需要你把脑子里的隐性知识显性化。下面我以一个 Java 项目中常用的“接口开发规范”为例展示一份完整技能文件该长什么样。文件放在src/skills/java-api-development/SKILL.md内容如下--- name: java-api-development description: 在 Java 项目中开发新的 REST API 时必须遵循的接口规范 --- # Java API 开发技能 ## 适用范围 - 新增接口 - 修改现有接口 - 重构接口调用逻辑 ## 必须遵守的约束 1. 所有接口路径必须包含 /api/v1 前缀 2. 请求和响应对象必须使用 record 类型 3. 禁止直接返回数据库实体 4. 错误响应必须使用统一错误码结构 5. 所有接口必须有 OpenAPI 注解 ## 执行步骤 1. 阅读现有 controller 代码确认风格一致 2. 创建 request 和 response record 3. 在 service 层实现业务逻辑 4. 编写单元测试覆盖成功和失败路径 5. 运行相关测试确认全部通过写完保存之后这个技能就生效了。注意 frontmatter 里的description很重要它决定了 Codex 在什么情况下会主动想起这个技能。描述写得越像“触发条件”Codex 越能在合适的时候调用它。4.3 在 Java 项目中调用技能的真实案例下面是我实际跑过的一个案例。我用 Codex 处理一个 Java Spring Boot 项目的新增用户注册接口在会话开头只给了它一句话请按 java-api-development 技能开发注册接口输入是邮箱和密码输出是用户信息。Codex 读了技能文件之后的表现让我明显感觉到流程被“掰正”了。它没有直接开写 Controller而是先说“按照技能要求我会先看现有 controller 代码确认风格”然后真的去读了目录结构。等它开始写代码时路径自动带上了/api/v1请求和响应用了 record没有把数据库实体直接扔出去最后还补了成功和失败两个测试。这个案例里最值钱的不是代码本身而是它证明了一个道理AI 编码代理能不能稳定产出很大程度上取决于你有没有给它一套可执行的约束。你给它越清晰的边界它给你的结果就越接近你想要的样子。自定义技能就是把这些边界“焊”进工作流里的最有效手段。5. 常见问题与排错实录5.1 安装与调用高频问题速查表我把自己和社区里经常遇到的问题整理成一张表供你排查时快速定位现象常见原因解决方案初始化后没有生成 src/skills 目录当前目录权限异常或 npx 缓存问题用 npm install -g superpowers 后重试 initCodex 不读取技能文件会话中未给出明确读取指令在首次消息中直接指定“请先阅读 src/skills”技能文件读了但行为没变化技能描述太笼统Codex 认为“没必要执行”细化技能步骤增加必须遵守的约束词子代理之间上下文混乱技能文件没有定义任务交接方式在技能中明确各代理职责和输出格式自定义技能不触发description 没有包含任务关键词修改 description对齐任务表述更新 superpowers 后自定义技能被覆盖初始化脚本覆盖了 src/skills自定义技能放在单独目录初始化后再合并如果你遇到“读了技能但行为没变化”的情况我建议你直接查看 Codex 的会话日志看它到底从技能文件里提炼出了什么。很多时候不是没读而是它读了但觉得自己“不需要照做”。5.2 让 superpowers 稳定发挥的五个使用习惯最后分享几个我踩过坑之后总结出来的使用习惯应该能帮你少走弯路。第一新会话必须重新触发技能读取。Codex 的上下文隔离性很强上一个会话里读过的技能这个会话默认不记得。所以每次新任务开始我都固定用同一句开场白把它写进自己的笔记里随时复制。第二技能文件里少用“尽量”“可以”这类模糊词多用“必须”“禁止”“唯一例外是”这种强约束表达。Codex 对强约束词的执行力比软约束高得多。第三不要让技能文件太长。单个技能最好能控制在 50 行以内太长会稀释重点Codex 会抓不住执行核心。如果需要表达复杂流程拆成多个技能文件通过子代理机制串联。第四定期做“技能评审”。我会每隔一两周翻一次 src/skills看看哪些技能实际用上了哪些是摆设。摆设技能就该删掉否则 Codex 每次都要读一堆不相关文件浪费上下文窗口。第五也是我觉得最重要的一点把技能文件当作代码来对待。它需要版本管理需要 CR需要测试。你不敢直接往主干上推一段没验证过的重构代码那也不该把没验证过的工作流塞给团队的 AI 代理。技能文件维护得越谨慎你从 superpowers 里得到的稳定性就越高。我自己已经把这套框架用成了每天的默认工作流不是因为它的名字有多酷而是它第一次让 AI 编码代理像“懂规矩的同事”而不是每次都靠运气的自动补全工具。