superpowers：把工程方法论装进Codex CLI，让AI代理能力复用

如果你用过一段时间 Codex CLI大概率会有这种感觉它在单次任务上确实聪明可每次开工都像是在重新教育一个新同事。同一个项目里测试规范、提交信息的写法、遇到报错时的排查步骤全都得在对话里重讲一遍讲得不够细它给出的结果就飘。也就是在这个反复折腾的过程中我注意到了 superpowers 这个项目——它做的事情很简单把零散在对话里的工程经验变成一套可以被 Codex 自动加载和调用的技能。装完之后Codex 不再是一个只会接单的实习生而是一个带着完整工作手册进场的工程师。这项目不是给你替换 Codex 的而是在 Codex CLI 之上加一层方法论层。你可以把它当成给编码代理配了一套 SOP每周的开发规范、TDD 流程、调试思路、代码评审清单全部写成技能文件让代理在合适的场景自动套用。下面我把这几个月的使用过程、踩过的坑、以及我自己写技能的完整路径都整理出来给正在折腾 codex superpowers 的朋友一个参考。1. 从能用到好用Codex CLI 的短板与我为什么盯上 superpowers1.1 每次重复交代需求的痛苦用 Codex CLI 跑真实的项目任务时最大的问题不是它不会写代码而是它每次都在裸奔。我举个例子团队约定所有新代码必须有单测而且测试要先写。这句话我在不同会话里至少说过三十遍。哪怕今天说了明天新开一个会话它又忘了。不是说 Codex 笨而是对话式代理天然没有长期肌肉记忆。你可能觉得那我把规范写进项目根目录的AGENTS.md不就行了确实能解决一部分问题但AGENTS.md更像一个静态说明书而真实开发里的场景是动态的遇到编译错误时应该走哪套排查流程写提交信息时应该按什么模板上线前要做哪些检查。这些是流程性知识不是事实性知识。把它们全塞进一个文档里要么文档越长越没人看要么代理分不清什么时候该用哪一段。superpowers 恰好是冲着这个痛点来的。它把流程性知识拆成一个一个独立的技能文件每个技能解决一个具体场景。代理在运行时根据任务类型去匹配技能而不是把整个知识库一次性吞进去。这个设计思路比单纯堆 prompt 要干净得多。1.2 superpowers 到底解决什么问题先说清楚superpowers 不是 Codex 的平替也不是某种新的编程语言它是一套运行在代理侧的技能管理框架。核心做法是把工程方法论写成 Markdown 文件通过配置让 Codex 在会话启动时加载这些文件并在对话过程中按需调用。举个例子。默认技能库里有一个写提交信息的技能它会要求代理先查看git diff和当前的提交历史再按 Conventional Commits 的格式生成信息并且在提交前明确说明改动的动机。我最开始觉得这功能平平无奇直到有一次我故意不装技能跑了同样一个提交Codex 给的信息就是一句Update file而加载技能之后它会给出带范围的、解释为什么改的描述。差距就是这么大。还有一个典型技能是调试。它的思路类似于科学排错法代理必须先生成假设再验证假设而不是看见报错就乱改。这个技能对解决棘手的偶发 bug 尤其管用。说穿了superpowers 是把我们这些老程序员脑子里的套路复制到了代理脑子里。1.3 什么时候你不该用 superpowers我不想把它吹成万能药。如果你只是拿 Codex 写一次性脚本、生成几行点对点的代码不装 superpowers 完全没问题甚至装了反而增加启动时的上下文开销让回答变慢一点。它是一个面向长期维护的项目和需要稳定工程质量的场景的工具。我现在的主要用法是把手头项目的工程规范沉淀成技能然后让 Codex 在每次开工时自动加载。这样无论会话怎么切换、模型怎么升级团队的核心要求不会丢。它解决的是一致性问题而不是智能问题。2. 把方法论装进代理superpowers 的技能机制拆解2.1 一个技能文件长什么样第一次打开 superpowers 的技能目录时我有点意外里面不是代码几乎全是 Markdown。每个技能就是一个.md文件文件头部有 frontmatter里面写着名称、描述、适用场景正文部分就是给代理看的完整指令。我拆开过一个典型的测试技能文件结构大致是--- name: pragmatic-unit-tests description: 在编写或修改代码后生成覆盖核心逻辑的单测避免过度 mock when: 用户要求写测试、或者在修改已有函数后未补充测试 --- # 编写务实的单元测试 - 先明确被测函数的行为边界 - 优先验证真实输入输出而不是只验证函数被调用 - mock 只在涉及外部 IO 时使用 - 测试命名要说明场景和期望结果这个 frontmatter 不是摆设它是代理做技能路由的依据。当任务描述和某个技能的name、description匹配时代理才会加载正文。也就是说技能的加载不是无脑全量加载而是按需匹配的。这也解释了为什么技能多了之后 Codex 的反应速度没有明显下降——不是因为它变聪明了而是因为大部分技能在大部分时刻根本没被唤醒。2.2 技能如何被唤醒我一开始很担心一个问题技能文件放在那里代理凭什么在正确的时机调用它后来看明白了这套机制靠的是两个层面的配合。第一层是启动时的索引。Codex 会话启动时superpowers 会把技能目录里的所有文件名、描述信息汇总成一个索引注入给代理。你可以把这个索引理解成一张菜单。代理知道有什么技能可用但不知道每个技能的细节。第二层是运行时匹配。当用户提出任务代理先对照菜单看看哪些技能和当前任务相关如果相关它再去读对应的 Markdown 文件把详细指令加载进上下文。这种先菜单后详情的设计明显是吸取了大模型 token 有限的教训——所有技能详情全部加载的话一万字上下文就没了。这其实和人类的工作方式很像。我进一个新公司时不会一下记住所有规章制度的细节但我知道有《请假流程》《报销规范》这些文档用到哪份查哪份。superpowers 就是在给代理建一个这样的知识文件柜。2.3 技能与 Codex 配置的衔接点在实现层面superpowers 和 Codex 的衔接主要靠两个入口一个是 Codex 的全局配置文件通常位于用户目录下另一个是项目级的AGENTS.md。superpowers 安装时会生成或修改配置让 Codex 在启动时把技能目录的路径和索引说明加载进去。同时它还建议在项目根目录放一个精简的AGENTS.md里面不写具体方法论只写本项目的工程规范见技能库xxx。这种分工很有意思项目级文档负责指路技能库负责方法论细节。好处是同样的技能可以在多个项目里复用不需要每个项目都复制一份完整规范。如果你要自己排查问题搞清楚这两个入口非常重要。很多时候代理没有调用技能不是技能写得不对而是配置入口没接上代理压根不知道有技能这回事。后面我会专门说排查方法。3. 从零开始安装、初始化与第一次验证3.1 环境准备codex CLI 与运行依赖动手之前先确认本机环境。superpowers 是架设在 Codex CLI 之上的所以前提条件是本机已经装好 Node.js 18 以上Codex CLI 本身依赖 Node 运行时Codex CLI 能正常跑通最简单的对话一个真实存在的 Git 项目最好不是空的方便验证效果我自己使用的是 macOS 环境路径上会和 Linux 略有差异但整体逻辑一样。如果你在 Windows 上折腾建议优先用 WSL别在 PowerShell 里硬搞路径问题和权限问题会省心很多。这里多说一句在安装任何工具之前先跑一个简单的codex exec test之类的命令确保 Codex 本身可用。很多人安装 superpowers 后发现问题回头一查其实是 Codex 本身没配好。这和装插件前先确认主程序能跑是一个道理。3.2 安装与项目目录结构安装 superpowers 我推荐用官方仓库里提供的安装脚本。大致步骤是# 先看一眼官方 README拿到当前推荐的安装命令 curl -sSfL https://raw.githubusercontent.com/obra/superpowers/main/install.sh | bash如果不想用管道执行远程脚本我理解这种谨慎也可以直接把仓库 clone 到本地然后手动把技能目录链接过去git clone https://github.com/obra/superpowers.git ~/.codex/superpowers安装完成后你会在用户目录下看到类似这样的结构~/.codex/ ├── config.toml # Codex 的全局配置superpowers 会往这里加技能路径 └── superpowers/ ├── skills/ │ ├── pragmatic-unit-tests.md │ ├── debug-with-scientific-method.md │ ├── write-good-commit-messages.md │ └── ... └── AGENTS.md # 技能库的索引说明装完之后别急着用先做一件事用你习惯的编辑器打开config.toml确认里面确实出现了 superpowers 相关的路径配置。很多安装失败都表现为装完了但 Codex 没反应九成是因为这里没写进去。3.3 跑一个真实的验证任务装好之后第一个验证任务不要选太复杂的。我的建议是找一个最近提交过的项目让 Codex 帮你写一条提交信息。cd ~/your-project codex exec 帮我看一下最近的改动并用 Conventional Commits 风格写一个提交信息如果你没装 superpowers这条命令的运行结果可能就是一句笼统的提交信息装了之后你会看到代理先去执行git diff和git log然后再组织语言。这其实就是技能被唤醒后的行为变化。还有个更直接的验证方式在对话里问 Codex你现在有哪些技能可用。如果加载成功它会列出技能菜单如果它一脸茫然说明索引没注入先去检查配置入口。我第一次跑验证时就遇到索引没注入的问题折腾了半小时才发现是 Codex 版本更新后默认配置文件路径变了。这类问题很常见也是我把安装章节单独拿出来写的原因——安装本身不难难的是确认装没装上。4. 写一个属于自己的技能以团队提交信息规范为例4.1 技能文件的骨架与 frontmatter 字段superpowers 自带的技能库确实够用但这个项目真正的价值在于自定义技能。只有把你团队自己的约定写进去它才真正变成你的神器。自定义技能的第一步是理解 frontmatter 里每个字段的含义。我看过的技能文件一般包含四个关键字段name技能的唯一名称英文短横线格式代理靠它做路由description一句话说明这个技能解决什么场景尽量包含触发词when明确告诉代理什么情况下该用这个技能avoid告诉代理什么情况下不要用这个技能这个字段容易被忽略但其实是防止误触发的最好工具我见过一个反例有人写了一个代码重构技能结果代理在每次改动代码时都觉得要重构把简单任务搞复杂。后来加了avoid字段限定只在大规模结构调整、且用户明确提出重构意图时启用问题立刻消失。所以写技能时不要只写这个技能是干嘛的要写什么情况下用它、什么情况下不要用。这就像给新同事布置任务只说有客户投诉你就处理是不够的还要告诉他哪些投诉可以自己处理、哪些必须上报。4.2 指令正文怎么写才不会被 AI 忽略技能正文是写给 AI 看的不是写给同事看的。我写了很多版之后总结出一个规律指令要动作化不要原则化。对比一下两种写法。原则化写法是提交信息应当清晰、简洁、包含足够上下文这种话代理看了等于白看因为它不知道怎么落地。动作化写法是# 写提交信息 1. 运行 git diff --stat 和 git diff理解本次改动的文件与内容 2. 运行 git log --oneline -10了解最近提交的风格 3. 按 Conventional Commits 格式组织type(scope): subject 4. 在 subject 中说明为什么改而不是只写改了什么 5. 如果改动涉及破坏性变更在正文中增加 BREAKING CHANGE 说明看到区别了吗动作化写法每一步都是可执行的命令或可观察的行为。AI 不是不会执行而是需要你把模糊的期望翻译成步骤。这也是我们这个职业里最核心的需求拆解能力只不过换了个输出对象。另外技能的描述里可以加入少量示例。AI 非常吃例子这一套一个对的比例子比十句抽象描述都管用。比如提交信息的技能里我会放两个示例一个优秀的、一个不合格的代理在生成时会明显向优秀示例靠拢。4.3 让技能进项目仓库并自动加载自定义技能写好后有两种落地方式。一种是放到全局技能目录~/.codex/superpowers/skills/这样所有项目都能用另一种是放在具体项目的.codex/skills/下实现项目级隔离。我的使用习惯是通用方法论测试、调试、提交信息放全局团队定制规则某个模块的开发规范、特殊的目录结构约定放项目级。这样既不影响其他项目又能让特定项目的信息保持聚焦。项目级技能的加载方式和全局技能略有不同它往往要和项目根目录的AGENTS.md做配合。我在AGENTS.md里一般这样写# 项目说明 这个项目使用 superpowers 管理工程规范。 与支付模块相关的改动请严格遵守 payment-module-rules 技能。 所有新功能必须配套测试参考 pragmatic-unit-tests 技能。这样写的好处是项目文档本身很短不会占据大量上下文代理遇到具体任务时再决定去读哪个技能。我之前见过有人把整篇规范塞进AGENTS.md结果文档两千多行每次对话都要把全量上下文带上又慢又容易让代理抓错重点。把原则留在AGENTS.md把操作手册放进技能目录才是合适的分工。5. 用了几周之后的真实感受与踩坑记录5.1 最容易翻车的三个场景第一个容易翻车的场景是技能名和任务描述匹配不上。我写过一个小技能叫react-component-guide描述里写的是针对 React 组件的开发规范。结果有几次我让 Codex 改一个纯工具函数它也莫名其妙去套这个技能导致代码风格变得很怪。后来我在描述里加了限制词写成仅当改动涉及 .tsx / .jsx 文件中的组件结构时使用误触发概率立刻下降。第二个翻车点是技能指令和当前项目的既有约定冲突。比如我的全局提交信息技能要求用 Conventional Commits但某个老项目一直在用简单的提交方式。如果全局技能优先于项目约定代理会按全局技能来反而破坏了项目历史风格。后来我学会在技能正文里加一句如果项目已有自己的提交规范以项目历史风格为准这样才避免了好心办坏事。第三个比较隐蔽是技能文件更新了但 Codex 用的是旧指令。因为技能是在会话启动时注入的如果你改了技能文件而当前会话没有重启代理会继续沿用旧版本的指令。我吃过一次亏更新了技能描述结果半天没生效还以为是语法错了最后重启会话就好了。如果你发现自己改了没效果先别怀疑语法重启会话再试。5.2 调试技能时看哪里技能不生效的时候我一般按三步排查。第一步确认技能文件在正确的目录下并且文件名和后缀没有拼错。第二步打开 Codex 的启动日志看启动时索引有没有被读进去重点搜技能目录的路径。第三步直接在对话里问代理你是否知道 xxx 技能或者让它复述技能要点看它到底加载到没有。这三步看起来简单但能解决九成问题。最容易被忽略的是第二步Codex 各版本的配置文件路径偶尔会变安装脚本默认写入的路径和实际运行路径可能对不上。反正记住一点代理没反应先确认加载再怀疑内容。还有一个我常用的小技巧在技能正文第一行写一句如果正确加载了这个技能请先回复已加载再继续执行。这样你在对话里一眼就能看出技能是否被唤醒省得猜。当然这行字要在调试完成后删掉不然每条对话都多一句废话。5.3 什么项目适合引入 superpowers用了三周之后我逐渐摸清了它的适用边界。最适合引入的项目有两个特征第一有明确的、可沉淀的工程规范第二代理会频繁参与同一个仓库的改动。比如持续在开发的业务系统、有测试要求的开源库这类项目把测试流程、提交规范、代码风格沉淀成技能价值非常大。不太适合的也有两类。一类是一次性脚本、原型验证这种用完即弃的任务引入技能属于杀鸡用牛刀。另一类是团队规范还在剧烈变动期的项目技能文件今天改一版明天改一版光维护技能就得花不少时间反而不如在对话里直接说清楚。如果拿开车类比Codex 默认状态是给你一台自动挡汽车能跑但操控上限有限superpowers 是给车加了一套辅助驾驶逻辑——前提是你得先想清楚自己要怎么开。没有明确的方法论意识的人装了的感受就是好像也没变强多少有方法论的人会觉得终于有个工具能把脑子里的流程落地了。5.4 持续维护技能库的方法技能库不是装完就结束的东西它需要持续维护。我现在养成一个习惯每次在对话中给 Codex 重复交代同一件要求时都会停下来想一想这个要求值不值得沉淀成一个技能。如果三天之内我需要第二次说同样的话那它就值得。维护技能库还有一个建议定期做技能瘦身。技能文件会越积越多而代理在启动时要扫描整个目录做索引虽然它是按需加载详情但数量过于庞大时索引本身的 token 开销也不小。每两周我会有意识地合并重复的技能、删掉已经不再使用的技能把技能数量控制在十个以内。三个高价值技能到位比二十个低价值技能堆在那里更实用。我个人在实际操作中的体会是把技能库当成代码来治理——有版本管理、有命名规范、有废弃机制而不是当成一个随手扔笔记的文件夹。superpowers 真正的上限不取决于这个工具本身而取决于你有没有把它当作一个长期维护的工程资产来对待。最后分享一个小技巧也是我最近才彻底用顺手的不要只给 Codex 装别人的技能一定要逼自己写一个。写第一个技能的过程就是把你脑子里的隐性经验显性化的过程。等到你发现自己写的技能反复被代理调用你就真正抓住这个工具的价值了。