Superpowers技能包：让Codex遵循SOP的AI编程指南

1. superpowers 是什么：先搞清楚它和提示词模板的区别

1.1 从"问一句答一句"到"给 AI 一套工作方法"

第一次看到 superpowers 这个名字，我以为又是一堆花哨的 AI 提示词模板，或者某个 IDE 插件的营销包装。直到我把它装进 Codex，让它自己跑完一个完整任务，我才意识到这东西改变的不是对话框里的答案，而是 AI 的工作方式。

大多数人用 AI 编程助手的方式是：遇到问题，把问题粘贴进去，拿到一段代码，复制回到项目里，跑一下，报错了再粘回去。这种"问一句答一句"的用法不能说没用，但它非常依赖提问者的水平。你问得越细，AI 答得越好；你问得模糊，AI 给你的就是一段看似正确、实则到处是坑的代码。而 superpowers 的思路完全反过来——它不依赖你每次提问的运气，而是提前给 AI 配好一套工作规范，让它在动手之前先想清楚，在写完代码之后主动验证，在报错的时候按流程排查，而不是硬猜。

我更喜欢把它理解成"给 AI 装上一套职业素养"。就好比一个实习生刚进公司，能力强但没经验，你给他一份 SOP，他才能把能力稳定地发挥出来。superpowers 就是那份 SOP，而且是用 AI 能读懂、能执行的方式写的。

1.2 技能文件是一个"可执行的说明书"

superpowers 的核心单元叫"技能"（skill）。每一个技能本质上是一个 Markdown 文件，文件头部带一段 YAML 格式的元信息，声明这个技能叫什么、在什么场景下用、需要什么前置条件；正文部分则是给 AI 读的详细流程说明。

这里有个关键点：这不是普通的文档。Codex、Claude Code 这类终端 AI 代理在启动时会扫描指定目录下的技能文件，把匹配当前任务的技能内容注入到对话上下文中。换句话说，技能文件不是给人看的参考手册，而是会被 AI 自动加载、自动执行的指令集。

我用一个类比解释给团队的新人听：普通提示词相当于你跟 AI 说"帮我修这个 bug，认真点"；技能文件相当于你跟 AI 说"先复现问题，定位根因，列出可能原因，逐一验证，修复后补一条回归测试，最后告诉我你改了什么"。前者靠自觉，后者靠流程。遇到复杂任务时，流程带来的稳定性提升是肉眼可见的。

1.3 一套技能包能覆盖哪些场景

我实际用下来，superpowers 这种技能包机制覆盖的场景比想象中广。它不限制你写什么语言、用什么框架，因为技能本身就是一组可插拔的规则集合。你只需要按需加载，就能让 AI 在不同任务里表现出不同的工作习惯。

这套机制最值钱的地方，是技能可以被组合。同一个项目里，可以让 AI 先加载"任务拆解"技能，再在编码阶段加载"测试驱动"技能，最后用"代码审查"技能兜底。整个流程下来，AI 的行为方式会非常接近一个有经验的全栈工程师，而不是一个只会生成的文本模型。

2. 安装前先想清楚这三件事

2.1 环境清单：Node.js、Git、终端

安装 superpowers 之前，先把基础环境理一遍。技能文件本身是纯文本，不需要编译，但它的安装脚本、更新机制以及和 Codex 等代理的联动，基本都依赖 Node.js 和 Git。

我建议按这个清单自查：

• Node.js 18 以上版本，低版本跑安装脚本会报语法错误
• Git，用于克隆仓库和后续拉取更新
• 一个能用的终端，macOS 用 Terminal 或 iTerm2，Linux 用任意 shell，Windows 建议装 Windows Terminal 并开启 WSL 或 Git Bash
• 已经装好 Codex CLI，或者你打算用 Claude Code 等其他 AI 代理

有个细节容易被忽略：终端里 Node.js 的全局命令是否在 PATH 中。有些人装完 Node 后换了 shell，node命令找不到，安装脚本一执行就报node: command not found。检查方式很简单，在终端里输入node -v，能输出版本号就说明没问题。

我装过一台服务器，上面有多个 Node 版本，默认指向的是 v16，结果安装 superpowers 时脚本直接挂了。后来用nvm use 20切换版本，再跑安装脚本，一次通过。所以如果你机器上有 nvm、fnm 这类版本管理工具，装之前先确认当前 shell 用的是哪个版本。

2.2 版本选择：稳定版还是开发版

superpowers 这类开源项目通常会有两个版本轨道：一个是打了 tag 的 release 版本，一个是 main 分支上的最新开发版本。我的建议是：第一次安装、或者用在生产项目上时，选择 release 版本。

为什么这么说？因为技能文件本质上是在跟 AI 的行为习惯打交道，而各家 AI 代理的更新频率很高，今天能用的一条技能指令，明天可能因为模型输出格式变化就失效了。release 版本至少经过了一轮测试，和当前主流的 Codex、Claude Code 版本兼容性有基本保障。main 分支则是"新功能先行"，可能加了新技能，也可能正在调整旧技能的结构，稳定性说不准。

判断方法很简单：去仓库的 releases 页面看最新的 tag 是什么，克隆的时候切到那个 tag 上再安装。我一般用这个方式：

git clone <仓库地址> superpowers cd superpowers git checkout v1.2.0

具体 tag 名称以你拿到的仓库为准，不一定叫 v1.2.0，但思路是一样的。等基本用熟了，想体验新技能，再切回 main 分支也不迟。

2.3 提前准备的目录和权限

安装 superpowers 前，还要想清楚一个问题：技能文件要装到哪个目录。这取决于你用的 AI 代理。Codex 的全局配置目录通常在~/.codex/，Claude Code 在~/.claude/，技能目录一般就是这两个目录下的skills子目录。

在真正动手前，我建议先手动创建好目录结构，避免安装脚本因父目录不存在而中途失败。你可以先执行：

mkdir -p ~/.codex/skills

然后确认这个目录有读写权限。有些服务器环境出于安全考虑，把用户目录设为只读，或者用了只读的挂载盘，安装脚本复制文件时会直接报Permission denied。这种情况不需要硬改权限，把技能目录指到你有写权限的地方，再通过 AI 代理的配置文件去指定那个目录就行。

3. 安装 superpowers 的完整步骤和目录说明

3.1 下载与安装

拿到 superpowers 的仓库地址后，整个安装过程并不复杂。我通常是先克隆到本地临时目录，再运行安装脚本。这里给你一个参考流程：

git clone <官方仓库地址> superpowers cd superpowers node install.mjs

安装脚本会做几件事：检查 Node 版本、确认当前环境里的 AI 代理类型、把技能文件复制到对应的 skills 目录。如果你的环境中同时装了 Codex 和 Claude Code，脚本可能会让你选择目标，或者两个都装。不同版本的脚本行为不一样，以实际输出为准。

如果你不想用安装脚本，也有最笨但最可靠的办法：直接把仓库里的skills目录整个复制到~/.codex/skills下面。技能文件就是普通的 Markdown，复制之后只要目录层级正确，AI 代理下次启动时就能识别到。

我用过几次脚本安装，也手动复制过。说实话，对于这种纯文件型工具，手动复制反而更可控——你能清楚地知道装了什么、放在了哪。脚本的好处是它会顺带做一些目录校验，避免你放错位置。

3.2 初始化技能目录

安装完成后，打开~/.codex/skills目录，你看到的应该是按技能名分好的一堆子目录，每个子目录里至少有一个SKILL.md文件。结构大致长这样：

~/.codex/skills/ ├── debugging/ │ └── SKILL.md ├── test-driven-development/ │ └── SKILL.md ├── planning/ │ └── SKILL.md └── writing-commit-messages/ └── SKILL.md

SKILL.md这个名字是约定，AI 代理扫描技能目录时，会自动识别这个文件作为技能入口。有些技能还会带辅助文件，比如示例代码、模板、脚本，这些都放在同一个子目录下。你不需要管它们是什么，只要保证整个子目录的完整移动，不要只搬一个SKILL.md过去。

第一次装完后，建议做一次"冒烟测试"：打开 Codex，随便问一句"你现在有哪些技能"。如果配置正确，它会列出刚才看到的那些技能名。这一步很关键，能尽早发现目录挂载位置对不对，省得到后面真要用时才发现 AI 根本没加载到技能。

3.3 配置项怎么调

技能目录的位置不是硬编码的，你可以在 AI 代理的配置文件里改。Codex 的配置文件是~/.codex/config.toml，Claude Code 的配置在~/.claude/settings.json或者通过命令行的--skills-dir参数指定。

我习惯在config.toml里单独设一个技能目录路径，而不是用默认位置，这样做的原因是方便备份和同步。比如我把技能目录放在~/dotfiles/skills下，用软链接指到~/.codex/skills，这样 git 管理配置时可以把技能文件一起带上，换新机器时一条命令全部恢复。

# ~/.codex/config.toml 示例片段 [skills] dir = "~/.codex/skills"

不同的 AI 代理配置语法有差异，这个例子只是展示思路。你实际配置时，以你所用代理最新版文档为准。重点是想清楚：技能目录要固定下来，别今天装在一个地方、明天又挪到另一个地方，否则你后面会花大量时间排查"为什么技能失效了"。

3.4 安装失败的那几种常见原因

我踩过的安装坑，大致可以归成三类。

第一类是 Node 版本太老。安装脚本里用了一些新语法，老版本 Node 不认识，直接报SyntaxError。解决方案就是升级 Node，或者切到 18+ 版本。

第二类是技能目录放错了位置。脚本默认往~/.codex/skills里写，但如果你用的是包装工具或自定义过的 Codex 配置，实际读取的目录可能不是~/.codex/skills。排查方法是启动 Codex 后让它打印自己的配置，看它到底扫了哪个目录。

第三类是代理版本和技能格式不兼容。有些技能文件头部用了最新的 frontmatter 字段，而老版本代理解析时直接忽略，导致技能虽然装在目录里，但 AI 从来没有真正读到它。这种问题最隐蔽，表面上看一切正常，实际上等于没装。解决办法是把代理升级到较新版本，或者换用旧版技能包。

4. 与 Codex 配合跑通一个真实任务

4.1 让 Codex 识别到技能

安装完 superpowers 后，要验证它真的有用，最好的办法是跑一个真实任务。先说怎么让 Codex 识别技能。

Codex 在进入交互模式时会扫描配置好的技能目录，根据你的指令内容，自动决定要不要加载某个技能。它内部有一套匹配机制：技能文件头部 YAML 里的description字段写得好不好，直接影响匹配命中率。比如你写"帮我修一下这个报错"，它可能会加载debugging技能；你写"帮我给这个接口写测试"，它可能会加载test-driven-development技能。

如果你不确定技能有没有被加载，可以直接问 Codex："你打算怎么处理这个任务？"如果它回答里出现了技能文件中的术语、流程步骤，或者明确说"我将按照 XX 技能中的步骤执行"，那就是加载成功了。如果回答得含糊，只是说"我将仔细分析问题"，那基本是没匹配上，需要通过更明确的任务描述来触发。

4.2 用一次重构任务验证效果

我用一个具体的例子说明 superpowers 产生的差异。假设有一个 Python 脚本，功能是把 CSV 文件里的用户数据按城市分组统计。我让 Codex 做一次重构，把重复的分组逻辑提取成公共函数。

没有装 superpowers 时，Codex 的常见做法是：直接给我一个新版本脚本，告诉我"我把分组逻辑提取成了group_by_city函数"，然后结束。代码看起来没问题，但没有任何测试验证重构前后行为一致。

装了 superpowers 之后，它的行为路径明显变了。它会先问我要原始输入样例，然后写一个临时脚本验证当前输出，再开始重构，重构完后手动跑对比，最后问我要不要把验证脚本保留成单元测试。整个过程中，它不是一次性给你代码，而是一步步走完"理解现状-建立基线-实施变更-验证结果"的完整链路。

我对比过两次结果：第二次的代码未必比第一次写得更优雅，但正确性有保障得多。尤其对于老项目，你不知道重构会不会碰坏隐藏逻辑时，这种"先建基线再动手"的方式价值极高。

4.3 如何确认是 superpowers 在起作用

有人可能会问：这些行为也许只是 Codex 模型本来就有的能力，和 superpowers 有什么关系？

我的验证方法是做对照实验：先把技能目录临时改名，让 Codex 彻底扫不到技能，再让它执行同样的任务。这时候它的行为会退回"直接给代码"的模式。然后把技能目录改回来，再执行一次，行为又会变回"先分析再动手"。多重复几次，差异非常稳定。

还有一个小技巧：检查 Codex 的调试日志。通常开启 verbose 模式后，日志里会显示当前加载了哪些技能文件。如果你看到任务触发时日志里出现了loading skill: test-driven-development这类输出，那就板上钉钉了——技能确实被加载并参与了整个决策过程。

5. Java 项目中使用 superpowers 的实战姿势

5.1 为什么 Java 项目更需要技能约束

很多人都问 superpowers 在 Java 项目里怎么用，其实 Java 恰恰是最需要这类技能约束的场景之一。

原因是 Java 项目的工程化程度普遍较高：目录结构固定、构建流程标准、测试框架成熟，但也因此有了更多"规矩"。不是每个 AI 代理都了解你的项目约定，比如 Maven 的模块划分、Spring 的 Bean 扫描范围、Lombok 的使用习惯。没有技能约束时，AI 很容易按自己臆想的结构生成代码，放到你的项目里直接编译失败。

而 superpowers 里有一个很有价值的点：你可以把自己的项目规范写成自定义技能，让 AI 在动手前先读一遍。比如我在一个团队里维护的 Java 服务，就写了一个"项目编码规范"技能，里面包含了包结构说明、异常处理偏好、数据库访问层的使用约定。之后让 AI 改代码时，它生成的代码风格跟团队其他人写的几乎一致，Code Review 的时间大幅缩短。

5.2 在 Maven 项目中加载技能

具体到操作层面，Java 项目里用 superpowers 不需要额外装什么插件，你只是要确保 AI 代理在正确的目录下工作，并且能读取到技能。

Maven 项目有一个特点：多模块构建时，AI 如果从根目录跑mvn test，整个项目构建耗时很长。这时候技能就起作用了。你可以在技能文件里约定：涉及单一模块的修改，用mvn -pl <module> -am test只测受影响的模块。没有技能约束时，AI 可能傻乎乎地跑整个项目构建，浪费一大段时间。

我实际使用的流程是这样的：

1. 启动 Codex 时，工作目录指向项目根目录
2. 任务描述里说清楚改动范围，并点名"按照项目规范技能执行"
3. Codex 读取 Java 相关技能，先跑一次受影响模块的测试，确认基线
4. 改代码，补测试，再跑一次测试确认全绿
5. 把最终改动列出来给我审查

这个流程跑通之后，AI 生成的代码基本不需要大改，我要做的就是 review 逻辑本身。

5.3 一个 Spring Boot 接口开发的完整链路

拿一个最常见的场景说：给现有的 Spring Boot 服务新增一个查询用户的接口。

如果没有技能，AI 大概率会直接甩给你一段 Controller 代码，里面可能包括 Service、Repository 甚至 Entity 的完整实现。代码风格和你的项目未必一致，而且很可能没有测试。

有技能约束后，执行链路完全不一样。Codex 会先问现有接口的响应格式是什么，翻一下已有的 Controller 代码，确认项目用的是Result<T>包装还是裸对象返回；然后看 Service 层有没有现成的查询方法可以复用；等这些都摸清了，才开始写新增代码。测试方面，它会参考已有测试类里的写法，用 MockMvc 还是 RestAssured，都会按项目习惯来。

我印象很深的是，有一次它没有直接生成代码，而是先给了我一份改动清单：新增哪个 Controller 方法、哪个 Service 方法、哪个测试类，以及每步的风险点。我确认方案后才动手。这种"先出方案再实施"的风格，在有技能和没技能之间差别特别明显。

5.4 Maven/Gradle 和 JDK 版本带来的坑

Java 场景下有几个具体的技术坑要提前跟技能约定清楚。

JDK 版本是个大问题。你的项目可能用的是 Java 17，但 Codex 默认生成的代码可能用了 Java 21 才有的语法，比如SequencedCollection接口。编译时直接报错。我写技能时就会明确一条："本项目基于 Java 17，禁止使用 Java 21 新特性。"

Maven 和 Gradle 的选择也要写进技能。同一个项目可能会混用，但你要让 AI 明白：这个模块用 Maven 构建，那个模块用 Gradle 构建，不要擅自改构建文件。我就遇到过 AI 把pom.xml改坏了的情况，因为它在解析依赖冲突时自作主张调整了dependencyManagement。后来技能里加了警告："修改构建文件前必须先在 CR 里说明理由，不得静默调整。"

还有 Lombok 的坑。如果项目里用 Lombok，AI 生成的类如果不加@RequiredArgsConstructor或@Getter，代码看着没问题，编译就报找不到 getter。这类项目的隐性约束，是最值得写进技能的。

6. worbuddy 这类封装工具如何与 superpowers 串联

6.1 worbuddy 在实际项目里扮演什么角色

最近总是看到有人问"worbuddy 怎么用 superpowers"，我一开始也很疑惑这是什么。实际接触下来，我发现这类名字的工具往往不是什么神秘新东西，而是给 Codex 一类 AI 代理做了层封装：要么是提供了图形界面，要么是把常用工作流做成了按钮，要么是在某个 IDE 里集成了一些快捷操作，本质上还是一个前端壳，真正干活的还是底层那个被调用的 AI 代理或 CLI 工具。

理解了这一点，你就明白了 worbuddy 这类工具和 superpowers 的关系。它们不在同一个层级，不冲突。superpowers 提供的是"技能内容"，worbuddy 提供的是"启动入口和操作界面"。你完全可以在 worbuddy 的界面里触发一个任务，然后让底层的 Codex 在完成任务时加载 superpowers 的技能。这两者不是二选一，而是可以同时用的。

需要提醒的是，因为这类封装工具多半不是官方出品，不同版本、不同作者写的行为差异很大。别人能跑通的配置，到你这边不一定能直接复制。关键还是你自己要理解底层的运行机制，而不是死记配置步骤。

6.2 三种把 superpowers 串进 worbuddy 的方式

我整理过三种常见的串联方式，按可靠程度排序。

第一种，最可靠：配置 worbuddy 调用的底层 AI CLI 工具，让它直接使用你的全局技能目录。比如 worbuddy 底层调用的是 Codex，那你只需要确保~/.codex/skills下的 superpowers 技能存在。因为技能目录是全局的，worbuddy 发起的任务自然会走到同一套技能加载机制里。这种方式几乎不需要在 worbuddy 里做额外配置，成功率最高。

第二种，中等可靠：在 worbuddy 的任务模板或表单里，主动引用技能文件路径。很多封装工具会允许你自定义任务描述模板，你可以在模板里加一句"请阅读 ~/.codex/skills/xxx/SKILL.md 并按其中的流程执行"。这种方式等于手动把技能塞进上下文，不依赖代理自动匹配，命中率也不错，但前提是这个模板系统支持这样引用文件。

第三种，灵活但脆弱：利用 worbuddy 的工作流编排功能。比如在某些自动化工具里，你可以定义多步任务：第一步执行某个脚本，第二步调用 Codex 的 exec 模式，第三步运行测试。这时候 superpowers 通常只作为第二步的输入条件，你可以在调用命令时加上参数，指定技能目录或技能名称。问题在于这类封装工具更新频繁，参数可能随手就变，需要经常调试。

6.3 串联时的常见坑

第一种坑：worbuddy 里显示的是它自己的一套配置，看起来跟 Codex 无关，但实际还是会走底层代理的全局配置。如果你改了 superpowers 的技能文件，worbuddy 侧发现没生效，先别急着怀疑软件坏了，多半是它启动了独立的工作目录，而没有读取全局技能目录。这时候你要去它的设置里找"工作目录"或"自定义配置路径"之类的选项，把它指回去。

第二种坑：有些封装工具为了"安全"会限制 AI 对本地文件的读取范围，只允许访问项目目录。可 superpowers 的技能文件装在~/.codex/skills，不在项目目录里，AI 就读不到技能内容。解决办法是允许读取技能目录，或者把技能文件复制一份到项目里的.superpowers目录下。虽然不太优雅，但确实是一个能解决权限限制的偏方。

第三种坑：工作流冲突。你在 superpowers 技能里定义了一套"写代码前先跑测试"的流程，但 worbuddy 的工作流又是"直接生成代码再统一测试"，两套逻辑叠在一起会打架，AI 行为变得混乱。最好是二选一：要么让 worbuddy 做纯入口，把具体的流程决策完全交给 superpowers 技能；要么在 worbuddy 的工作流里关闭它的内置决策，只保留任务转发功能。

7. 用了一段时间后的避坑清单与心得

7.1 版本升级带来的技能失效

我遇到过几次比较伤的情况，都是因为升级了 Codex，或者升级了 superpowers 之后，原本跑得好好的技能突然不触发了。

原因通常是技能文件头部的 schema 字段变化了。老版本的技能可能用的是when_to_use,新版本改成了triggers,字段一变,代理的匹配逻辑就不认识了。装新技能包之前，建议先看一下升级日志里有没有 breaking change。没有升级日志的话，就把关键技能文件备份一份，升级后逐个验证，出问题还能回滚。

另外，技能文件里的指令描述如果太旧，和当前模型的行为习惯不匹配，也会出现"加载了但没照做"的情况。比如以前写"先运行 pytest",现在项目已经改用其他测试工具了,但技能里没更新,AI 就会跑错命令。所以技能文件本身也是需要维护的活文档,不是装完就一劳永逸。

7.2 Token 消耗和费用控制

装了 superpowers 之后，AI 的思考过程变长，消耗的 token 明显比裸用时要多。因为技能本质上就是让 AI"多干活":多读文件,多列计划,多验证，"多"出来的每一步都要算 token。

我自己控制成本的方法有三个。第一个是只对复杂任务启用技能，简单的提问不需要让它走完整流程。第二个是限制技能加载数量，如果有多个技能同时匹配，可以在任务描述里指定只加载某一个，不要默认全部加载。第三个是用非交互模式批量处理,比如codex exec跑固定任务，比聊天模式省去很多来回。

有人可能会觉得，为了"让 AI 多干活"多花 token 不值。我的看法是，如果你用 AI 只是为了生成一段能跑就算的代码，那确实没必要装 superpowers。但如果你要用 AI 维护一个正在生产运行的项目，多花的那点 token 对比少踩一个线上 bug 的代价，完全值得。

7.3 权限与安全边界

superpowers 带来的另一个问题是，它会主动让 AI 执行更多命令，比如跑测试、改文件、甚至提交 git。这些操作如果没权限控制，风险比单纯生成代码大得多。

我的第一道防线是：在技能文件里明确禁止某些危险操作。比如我在自己的技能模板里固定写一条"未经确认，不得执行 git push、不得修改远程分支、不得删除数据表相关脚本"。AI 对这类明确禁令的遵守程度要比通用提醒高得多。

第二道防线是：用最小权限账号跑 AI 代理。本地开发时我可能无所谓，但服务器环境我会专门建一个普通用户，不装危险的管理员权限工具。所谓"给 AI 超能力"，不等于给它过度的系统权限。这一点 ,越早想清楚越好。

第三道防线是：人工审查关键变更。技能可以规范 AI 的行为，但不能代替人的判断。尤其是涉及数据库迁移、支付逻辑、权限校验的改动，我从来不直接合入 AI 生成的代码，一定自己过一遍再走正式流程。

7.4 我的几点体会

最后说一点个人的使用习惯。superpowers 这类技能包机制，最容易被低估的价值不是"让 AI 更聪明"，而是"让 AI 的表现更稳定"。聪明是模型自己决定的，稳定是你给的规范和流程决定的。同一个模型，有技能约束和没技能约束，在复杂任务上的表现方差很大。技能的存在,让它的水平下限大幅提高,不会在关键时刻给你一个看似合理实则荒谬的结果。

如果你刚开始接触，我建议不要贪多，不要一次性装上几十个技能。先装三五个和你当前工作最相关的，比如调试、测试驱动、任务拆解，用一周时间观察 AI 的行为变化。习惯了之后再慢慢加，并且把你自己项目中沉淀出来的规范也写成技能。当你发现 AI 不再整天产出"看起来对但跑不动"的代码时，你就知道这套机制值在哪了。

还有一个很小的技巧，但很管用：技能文件里写流程时,记得把"结束条件"写清楚。比如调试技能里，要写"当且仅当测试全部通过时,才能认为修复完成"。没有明确结束条件，AI 可能会觉得"报错没了"就算完成，实际上测试还没跑。这个细节是我在多次对比中总结出来的，写进技能后，完成度的判断准确了很多。