第一次听说superpowers这个词是我在折腾 Codex CLI 时从 GitHub 刷到的。项目正文不到十行但评论区里一堆人在晒使用心得同一个 Codex装上之后突然学会了先写测试、做代码审查、按流程拆任务。我当时刚被嘴上答应先写测试转头就把实现和测试一起写完的 Codex 气到看到这个项目标题的瞬间就点进去了。装完试了一周最大的感受是它不是给 Codex 加什么魔法而是给它补上了一套做事流程。这篇文章会从头梳理 superpowers 的安装、使用指南、常见技能逻辑以及我在真实项目里踩过的坑。如果你正在用 Codex CLI、Claude Code 这类 AI 编程工具或者想把 AI 编码助手纳入团队规范这篇应该能帮上忙。1. superpowers 到底是什么给 Codex CLI 加 Buff 的技能包1.1 从聪明但没章法到有章法先明确一下背景。Codex CLI 是 OpenAI 推出的终端编程助手你可以在命令行里让它读写文件、跑测试、提交代码能力很强。但用久了你会发现一个问题它非常擅长完成一个点却很不擅长遵循一套流程。我举个实际例子。你告诉它给这个支付模块补个单测它大概率会直接写一个测试文件出来可如果你要求的是先分析现有逻辑、列出风险点、再写一个能暴露 bug 的失败测试、确认红了之后才改实现它就会开始自由发挥。不是它笨而是 prompt 里的流程描述一旦超过几条模型就开始凭惯性补全。superpowers 这个项目就是冲着这个问题去的。它的本质是一批精心编写的 AGENTS.md 和技能模板装到 Codex 之后会让助手在启动时自动读入一套约定什么任务要按什么步骤做、哪些操作不允许、哪些工具先调用。你可以把它理解成游戏里的 Buff —— 不改底层角色属性但改变角色的行为习惯。1.2 三层结构AGENTS.md、技能、命令我用了一周之后把它的机制简化成三层理解这三层基本就掌握了使用思路层级作用类比AGENTS.md全局行为守则Codex 启动时自动加载员工手册技能Skills面向某类任务的详细操作流程按需读取操作手册命令Commands)组合技能和动作的快捷入口快捷键或批处理脚本AGENTS.md 是入口。Codex CLI 在项目根目录读到这个文件后会把里面的规则当作默认行为约束。superpowers 的 AGENTS.md 会再引用 skills 目录下的技能描述告诉 Codex遇到 TDD 相关需求时去读 skills/tdd.md 并按里面的步骤执行。命令则更像快捷指令比如nuke可以在上下文乱掉时一键重置会话subagents可以把大任务拆给多个子任务并行处理。这层设计最打动我的地方是所有规则都是文本文件可以进 git可以 diff可以评审。它不像你在 prompt 栏里手敲一段指令那样转瞬即逝而是变成项目资产换台机器、换个同事规则依然在。1.3 它和普通 Prompt 工程的区别很多人第一次接触 superpowers 会问这不就是写更好的 prompt吗我一开始也这么想后来发现区别在加载机制上。普通 prompt 是你每次对话都要重复或靠记忆补充上下文一长就失效而 superpowers 走的是文件加载链路Codex 启动时自动读取 AGENTS.md 中的引用并展开相当于把规则写进了它的工作记忆。它不需要你每次提醒先写测试再实现因为启动时就把这份约定带上了。另一个区别是状态管理。技能文件里可以写当前步骤允许做什么、不允许做什么比如 TDD 技能会明确要求实现代码必须在测试确认失败后才允许编写。这种流程约束靠对话往往很难稳定维持但靠文件系统加载的规则就很稳。提示理解这一点之后你排查问题时的思路会完全不一样——如果 Codex 没按技能行事先检查它有没有读到文件而不是怀疑它今天状态不好。2. 安装与激活两条路径的完整流程2.1 官方推荐的一键安装如果你只是想先试试,官方 README 推荐的方式是一条 curl 命令。我建议你在安装前先看一眼脚本内容毕竟把远程脚本直接灌进 shell 这种事得确认来源再执行curl -fsSL https://raw.githubusercontent.com/obra/superpowers/main/install.sh | bash这条命令会把项目克隆到你的用户目录下的.codex/superpowers并生成或更新基础配置。执行完看输出如果最后提示成功一般就能在用户目录找到这个文件夹ls -la ~/.codex/superpowers你大概率会看到AGENTS.md、skills/、commands/以及一些说明文档。我对新工具的习惯是先翻一遍AGENTS.md因为后面所有行为规则都从它开始。国内网络直连 GitHub 偶尔会很慢如果卡在下载阶段别反复重试直接关掉脚本改用下面的手动方式。2.2 手动克隆安装与目录结构手动安装其实更可控尤其你想长期使用或二次开发时git 仓库管理会方便很多git clone https://github.com/obra/superpowers.git ~/.codex/superpowers装完后我建议执行一次更新检查确认目录不是空的find ~/.codex/superpowers -maxdepth 1 -type f | head -20这个目录的结构是理解一切的钥匙。我整理一下常见的几个部分AGENTS.md入口规则负责描述全局行为守则和技能索引。skills/包含各种技能的 Markdown 文件比如 TDD、代码审查、计划撰写等。commands/命令脚本往往是技能的快捷触发方式也可能是辅助脚本。一些按功能拆分的子目录比如专门放上下文管理、模型行为约定的文件。手动克隆的额外好处是升级方便后续跟着上游更新就是一次git pull。我前面第一次用一键脚本安装完后来想改技能文件发现项目结构理解不清干脆删掉重新git clone了一遍反而更顺手。2.3 激活到 Codex CLI让项目读到规则光把文件放到~/.codex/superpowers还不够。Codex 默认并不会主动去读这个目录你需要在项目根目录的AGENTS.md里显式引用它。比如项目根目录新建或修改AGENTS.md加入这样一行/Users/你的用户名/.codex/superpowers/AGENTS.md这里有个大坑引用里尽量不要用~Codex 对波浪号展开的处理在不同版本里表现不一致。我第一次就是写了~/.codex/superpowers/AGENTS.md结果完全没生效换成绝对路径立刻就好了。激活之后怎么验证开一个新的 Codex 会话不要急着让它写代码先问它根据你加载的项目规则列出你需要在做 TDD 时遵循的步骤。如果它能复述出先写失败测试、确认红、再实现、确认绿、重构这类流程说明链路已经通了。不能用旧会话验证因为上下文是加载时固定的改完文件必须开新会话。2.4 顺带说说 Claude Code 和其他兼容前端很多朋友问我 superpowers 是不是只能配 Codex。其实不是凡是支持 AGENTS.md 或类似项目上下文文件机制的 AI 编程工具思路都一样。以 Claude Code 为例它读的是CLAUDE.md你完全可以在里面同样加一行/Users/你的用户/.codex/superpowers/AGENTS.md让它复用同一套技能文件。还有社区里出现的 workbuddy有人写成 worbuddy这类工具核心思路也差不多找到它加载项目级规则文件的配置项把 superpowers 目录里的 AGENTS.md 引进去。我个人的判断是这类工具最终都会往项目规则文件 按需加载技能 Markdown的方向收敛所以现在花时间把技能写成平台无关的 Markdown之后迁移成本非常低。3. 使用 superpowers 的正确姿势技能、命令与上下文3.1 技能的触发机制技能不是时刻都在内存里的。如果你把几十个技能文件的完整内容都塞进上下文对话窗口很快就会爆。所以 superpowers 的做法通常是AGENTS.md 里只放技能索引——每个技能的名字和一句话描述真正执行时 Codex 发现当前任务匹配某个描述再去读取对应的技能文件。这意味着你对 Codex 说话时最好把技能相关的关键词说出来。比如你说用 TDD 模式来开发这个新接口它就更容易检索到 TDD 技能你说提交前帮我做一次正式审查formal review它就会去读审查技能的完整步骤。我实际用下来发现一个技巧在 AGENTS.md 里给项目写一条默认规则比如本仓库所有新增公共方法都必须走 TDD 技能流程之后你甚至不用每次提 TDD 三个字母Codex 读到公共方法变更时会自动联想到该技能。这比靠临场发挥稳定得多。3.2 高频技能拆解我把自己项目里最常用的几个技能列一下方便你有个具体概念技能典型触发词实际作用TDD用 TDD 流程先写测试强制红灯-绿灯-重构循环formal-review正式审查提交前检查对改动做结构化审查并输出报告nuke重置上下文重新开始清理当前会话上下文、回到初始状态subagents拆分子任务并行处理把大任务拆成独立子任务并交给多个执行者writing-plans先写计划动手前先产出分步骤实施计划以 formal-review 举例它不会直接改代码而是要求 Codex 先收集所有改动文件逐项检查逻辑一致性、测试覆盖、潜在边界问题最后给出修改建议清单。这个技能对提交前自查特别有用能治住代码能跑就赶紧提交的坏毛病。nuke 这个命令我在早期使用频率很高。上下文跑偏或规则混乱时一条命令重置会话省得手动开新窗口再贴一遍项目背景。3.3 命令与技能的区别和配合很多教程把命令和技能混着讲导致新人以为它们是同一种东西。从我观察来看技能是流程文档命令是动作入口。一个技能可以被多个命令引用一个命令也可能串联多个技能。举个例子subagents命令执行时可能先读取任务拆解技能把大任务拆成几个小任务再给每个子任务挂不同的技能上下文。命令更像调度器技能才是真正干活的说明书。如果你打开目录看到commands/下有一个nuke脚本你可以瞄一眼它内部是否只是删除了某个临时上下文文件——这种设计会帮助你理解其实没有魔法就是一些约定和文件的组合。3.4 管理上下文规模这是我用了一周后最想提醒的一点技能文件越多索引描述写得越差Codex 越容易忽略你的指令。具体来说AGENTS.md 里技能列表部分不要塞大段描述每个技能一行、说清楚触发词即可。详细步骤留在技能文件里。另外项目根目录的 AGENTS.md 只放这个项目特有的规则通用技能索引保持精简。如果你把所有团队规范都写进项目级文件Codex 的上下文很快会被占满核心规则反而变得不突出。我在一个仓库里试过把三四个大型技能完全展开到 AGENTS.md结果 Codex 的行为变得飘忽不定缩短索引只保留两行描述之后表现马上稳定了。4. 实战用 superpowers 给一个 Java 项目做 TDD 改造4.1 场景设定纸上谈兵没意思我讲一个自己实际做过的场景。我有一个遗留的 Spring Boot 服务PaymentService里有个calculateFee方法负责根据订单金额和支付渠道计算手续费。这个类写得比较乱外部依赖多而且没有任何单元测试。更麻烦的是这个费率计算方法一直有个隐蔽 bug整点边界时按小时计费的结果会多算一分钱。我当时的任务不是重构整个类而是先把这个 bug 用测试暴露出来再修复同时保证不破坏其他逻辑。这正是 TDD 技能发挥价值的场景也是我决定引入 superpowers 的直接原因。4.2 激活技能与设计指令我先在项目根目录的AGENTS.md里加了两行项目级规则- 修改 PaymentService 时必须先走 TDD 技能流程。 - 单元测试使用 JUnit 5 Mockito禁止启动 Spring Context。第一行是为了让 Codex 自动联想到 TDD 技能第二行是项目特有约束避免它去 bootstrap 整个 Spring 容器。随后我开了一个新会话给出这样的指令在 PaymentService 的 calculateFee 方法上按 TDD 流程处理。 当前已知嫌疑整点边界时小时计费可能存在一分钱误差。 请先按技能步骤拆解执行每完成一步向我确认不要一次性生成全部代码。为什么要强调分步确认因为 Java 遗留代码的测试跑起来慢如果 Codex 一股脑把测试、实现、重构全做了出问题时你根本不知道是哪一步引入的。分步执行虽然啰嗦但每个环节都可验证。4.3 执行过程观察Codex 读取 TDD 技能后先输出了一段执行计划第一步是写一个能暴露边界 bug 的失败测试第二步是运行测试确认红灯第三步才是修改实现让测试变绿最后是整理代码并确认无回归。它创建的测试用例选在了 23:59 与 00:00 的交界。运行mvn -q -DtestPaymentServiceTest test后果不其然红灯错误断言信息里能看到那个一分钱误差。到这一步我心里就有底了——测试确实戳中了问题而不是覆盖了无关逻辑。随后 Codex 修改了费率计算中的时间取整逻辑再跑一次测试绿灯。整个过程没有出现过一次测试还没失败就动手改实现的情况这在我之前裸用 Codex 时很难稳定做到。4.4 Java 场景的特殊注意点用 superpowers 跑 Java 项目有几件事技能文件本身未必会教你的外部依赖 Mock 策略要写进项目规则。PaymentService依赖一个外部 HTTP 服务如果项目规则里不写明必须使用 Mockito mock 该客户端Codex 可能会去启动真实的连接测试立刻变慢还容易挂。测试运行命令要给它一个短路径。我直接在 AGENTS.md 里追加了运行单个测试类使用mvn -q -Dtest类名 test它就不会每次都跑全量构建。与 Checkstyle/SpotBugs 的顺序问题。formal-review 技能默认审查代码逻辑不一定知道你们项目要过 Checkstyle。遇到这事我选择在项目规则里补充一句正式审查时必须同时执行mvn verify比它自己猜要强得多。总之一句话superpowers 给的是通用流程骨架而项目特色和工具链约束必须靠你的 AGENTS.md 补全两者配合才是完整方案。5. 踩坑实录技能不生效与命令丢失的完整排查链路5.1 场景 A技能文件存在但 Codex 完全不理会关键词我遇到的第一个典型问题是技能文件明明白白在skills/目录里但不管我怎么提TDDformal reviewCodex 都无动于衷。我的排查链路是这样的建议你也按顺序来先在会话里问 Codex你从项目规则文件中加载到了哪些技能如果它一脸茫然说明 AGENTS.md 入口本身没加载上。检查AGENTS.md里的引用路径。我之前踩过~波浪号不展开的坑改成绝对路径后解决。如果技能列表能说出一部分、但缺了你关心的那个去看那个技能文件头部有没有写description字段。superpowers 的自动发现机制依赖文件头描述缺失描述的技能可能不会被加入索引。确认是不是被项目内其他规则覆盖。有些仓库会有多层AGENTS.md子目录规则优先于根目录如果子目录里写了一条相反的约束Codex 可能就不走技能了。最后所有修改都必须开新会话验证旧会话里加载的上下文不会热更新。这个问题我反复踩每次都以为配置坏了其实是没开新会话。5.2 场景 B功能好像生效了但回答质量忽高忽低还有一种更隐蔽的情况技能确实被加载了但那天 Codex 的表现依然不稳定。排查后发现是技能文件太长核心约束写在文档中后部模型上下文一长就把关键部分挤出了有效范围。我处理方式是重构技能文件结构把最重要的约束放在文章开头前五段内详细的操作示例拆到单独的子文档技能正文里只留链接或摘要。比如禁止在测试失败前修改实现代码这种硬约束提到最前面之后所有细节都围绕它展开。整理了一份自查清单碰到质量问题可以逐项过检查项说明技能触发词是否清晰描述能否让模型准确匹配任务硬约束是否前置关键禁令必须在前 1/3 处出现技能文件是否过长超过上下文窗口会被截断控制篇幅是否与其他技能冲突两个技能可能对同一操作给出不同指示5.3 场景 C更新后自定义命令被覆盖用 git 管理的东西早晚会遇到这个问题。我基于 superpowers 写了一个自定义命令然后某天执行git pull想同步上游更新结果发现自定义命令目录里的文件被上游同名文件覆盖了。原因很简单我没有把自定义内容单独隔离出去而是直接放在了 superpowers 管理的commands/路径下。上游一旦引入同名文件git pull就会发生冲突或覆盖。排查之后我改成了自定义内容独立目录的方案把自己的命令放到~/.codex/superpowers-custom/然后在 AGENTS.md 里再增加一次引用。这样更新上游时自定义目录不受影响。如果你已经 fork 了项目也可以走上游加 remote、自己维护 main 分支的路线但对多数人来说上游更新 独立自定义目录更省心。5.4 排查工具与日志碰到实在解释不了的问题别瞎猜开日志看。Codex 运行时的详细输出能告诉你它到底读了哪些文件、执行了哪个技能、哪一步报了错。我在排查时经常看两样东西一是会话里的技能加载声明也就是让 Codex 自己汇报规则二是 CLI 的 verbose 模式输出里面能看到 AGENTS.md 的读取记录和指令展开情况。记住一点规则链路的每一步都是文件系统上的真实动作只要路径对、格式对、新会话已开启技能就没有理由不生效。6. 进阶自己写一个团队级技能包6.1 一个自定义技能的完整示例能够熟练使用之后你最想做的肯定是写自己的技能。我以生成发布说明为例给你看一个最小可用的技能文件长什么样--- name: release-notes description: 根据 git 历史和版本差异生成发布说明。当用户说生成发布说明或release notes时使用。 --- # Release Notes 技能 ## 输入 - base_ref起始分支或标签 - head_ref目标分支或标签 ## 执行步骤 1. 运行 git log --oneline --no-merges base..head 获取提交列表。 2. 按功能、修复、重构、依赖分组提交信息。 3. 对无法归类的提交标记为其他不要臆造类型。 4. 输出 markdown 格式到 RELEASE_NOTES.md。 ## 禁止事项 - 不要添加提交记录中不存在的条目。 - 不要修改任何源代码文件。 - 不要自动提交或推送文件。把这个文件放到skills/release-notes.md然后在 AGENTS.md 的技能索引里补一行- release-notes: 根据 git 历史生成发布说明当用户提到发布说明时使用。这样一个团队级别的新技能就算诞生了。关键不是格式多花哨而是把输入、步骤、禁止事项都写清楚模型执行时才不会跑偏。6.2 让团队统一使用技能文件写出来没人用等于零。我的做法是把整个技能目录推进团队代码仓库这样每次更新都有评审记录、有 diff新同事 clone 下来直接在项目根目录的 AGENTS.md 里引用就行。如果团队已经用了 git submodule也可以把 superpowers 和自定义技能目录作为 submodule 引入方便统一锁定版本。我更推荐把自定义技能目录和上游 superpowers 目录分开管理避免上游更新影响团队定制内容。配套建议是写一个一页 README把激活步骤写清楚clone 什么、AGENTS.md 加什么引用、新会话怎么验证。团队里不是所有人都了解 AI 工具的内部机制一份实操文档能省掉大量口口相传。6.3 与各类前端的兼容实践文章开头提到 workbuddy 这类工具我最后再展开说一下。这类工具既然要处理同一套技能 Markdown就说明技能描述本身并没有绑定某一家模型。我在写自定义技能时坚持一个原则所有步骤都写成做什么、产出什么不写任何一家产品特有的调用语法。这样做的好处是今天这个技能在 Codex 里能用明天迁到 workbuddy 或者 Claude Code 上只需要调整加载配置那一层技能正文完全不用动。这其实也是 superpowers 整个项目最有价值的地方——它不依赖某个具体神器的私有能力而是把人的方法论固化成模型无关的文档。最后分享一个我验证技能是否生效的小技巧装完任何新技能第一件事不是直接开干而是让 Codex 先复述它理解到的技能内容。它若能把触发条件、执行步骤、禁止事项都说出来说明上下文链路是通的说不出多半就是引用路径或技能头部描述的问题。这个让 AI 总结自己的办法很土但每次都能最快定位问题比翻日志高效得多。顺着这个思路去扩展自己的技能包你会慢慢找到那种工具真正按你的规矩办事的掌控感。