Codex 用了一段时间我的感受很直接它是个不错的执行者但真不是自动懂事的开发者。你让它写测试它就写你不提 Git 规范它就把提交信息随便一写。问题不在模型在于工作流没有沉淀下来。后来我接触到一个叫 Superpowers 的开源项目定位就是给 Codex 这类 AI 编程助手装上一套“技能包”把 TDD、重构、调试、Git 提交规范这些经验固化成 Markdown 技能文件AI 遇到对应任务时自动加载。这篇文章不讲抽象概念直接从设计思路、安装配置、Java 实战到踩坑记录把这套东西怎么用讲清楚。适合两类人一是已经在用 Codex 但觉得它“不够专业”的开发者二是想把自己团队的研发流程固化进 AI 工作流的工程负责人。1. 先聊清楚Superpowers 是给 Codex 这类 AI 助手装“技能包”的开源方案1.1 为什么 Codex 默认状态下“有手没脑”很多人刚上手 Codex 时会觉得它很聪明让它生成一个函数、写一段 SQL、解释一段报错都像模像样。但一旦你让它完成一个完整任务比如“实现一个用户注册接口”你会发现它做的事情通常只是写一个 Controller、一个 Service然后就不吭声了。测试不写、边界条件不想、提交信息乱写甚至目录结构也随意。这是模型的问题吗不完全是。Codex 本身是一个很强的代码生成工具但它缺少“什么时候该做什么”的过程性知识。你给它一个接口它知道接口长什么样却不知道你的团队要求先写失败测试、再写实现、最后重构也不知道提交前要跑一遍完整测试。这些经验存在于资深开发者的脑子里却没有进入 AI 的上下文。所以我一开始的解决办法是每次对话都把流程粘贴一遍“请先写测试测试要覆盖成功和失败路径然后按最小实现让测试通过”。效果嘛时好时坏。prompt 长一点它勉强能跟上prompt 短一点它立刻回到自由发挥模式。这种手把手教学的方式本质上是在浪费对话轮数也让 AI 的输出极不稳定。Superpowers 解决的正是这个问题它把高手的经验写成一个个独立的 Markdown 技能文件通过路径和描述让 AI 在任务匹配时自动去读。它不改变模型能力而是改变了 AI 的“行动清单”。有了技能文件AI 面对任务时不再凭空猜流程而是先读一份“工作手册”再按手册执行。1.2 Superpowers 的核心组成和工作原理Superpowers 这套方案的核心结构不复杂总共三部分技能文件、技能目录、触发规则。技能文件是灵魂通常一个技能对应一个文件夹里面有一个SKILL.md作为主文件。这个文件开头有一段 YAML frontmatter写明技能名称、适用场景和简要描述正文就是具体的操作步骤、注意事项和示例。AI 读取它之后会在当前对话里形成一套临时规则后续代码生成、文件操作、命令执行都会受这套规则约束。技能目录是存放这些文件夹的地方。Superpowers 本身就是一个技能仓库里面按场景分类有 TDD 测试驱动开发、Git 工作流、调试排错、代码审查、文档编写等。使用的时候你把它克隆到 AI 工具约定的扫描路径下比如项目根目录的.codex/skills或全局配置目录AI 启动时就能发现这些技能。触发规则决定了 AI 什么时候读哪个技能。Superpowers 最常见的做法是让 AI 在开始任务前先扫描技能目录根据任务描述和技能文件的 description 做匹配。比如用户说“帮我给这个接口补测试”AI 看到tdd/SKILL.md里写着“适用于任何需要编写或补充测试的场景”就会先读取它再决定执行方式。这种机制有点像给 AI 配了一个“自动导航”不用你每次手动喊“先读手册”。我一开始觉得这个设计很玄但实际跑了一圈后发现它其实就是把“提示词工程”变成了“文件系统工程”。你不必在对话里塞满流程说明只需要保证文件放在正确位置、描述写清楚AI 自己就会去取。2. 核心设计拆解为什么预置技能比每次手写提示词更靠谱2.1 把隐性经验变成显性文件先回答一个关键问题为什么不把流程直接写进系统 prompt 或每次对话开头原因很现实系统 prompt 有长度限制而且塞进去的内容会被 AI 一视同仁地当成背景知识权重不高。你把 TDD 流程写在系统 prompt 里它确实知道有这么个东西但到了具体写代码的时候很可能还是按照训练数据里的“默认最佳实践”来而不是你定义的团队规范。技能文件不一样。它的核心是一个“按需加载”的动作AI 判断任务匹配后才去读取文件读到的内容会作为当前任务的高优先级指令。这种机制让流程规则更“新鲜”也更有针对性。就好比一个厨师你给他一本厚厚的菜谱让他背下来他做菜时未必每道菜都翻但你把某道菜的做法抽出来放在灶台上他做这道菜时自然会瞄一眼。我在自己项目里做过对比。同样是“写一个带测试的工具类”直接让 Codex 写它能跑但代码风格和测试覆盖都很随机我先让 Codex 读一下tdd技能文件再动手输出的代码结构明显更规范测试覆盖率也高得多。差异来源不在于模型而在于执行前多了一次“确认流程”的动作。2.2 技能文件如何被 AI“看到”和执行技能文件不是魔法它也是一份普通文档。真正让它生效的是你给 AI 的“阅读入口”。以 Codex 为例最常见的配置方式是在项目根目录创建AGENTS.md里面写清楚技能目录在哪里、哪些任务应该先读技能、如果没有对应技能就询问用户。Codex 每次会话开始时都会读取AGENTS.md相当于给 AI 一张地图。然后当任务触发时AI 会去skills目录下查找匹配的文件夹读取SKILL.md的 frontmatter再决定是否完整读取正文。下面是技能目录的典型结构your-project/ ├── AGENTS.md ├── .codex/ │ └── skills/ │ ├── tdd/ │ │ └── SKILL.md │ ├── git-commit/ │ │ └── SKILL.md │ └── java-spring/ │ └── SKILL.md └── src/AGENTS.md里的内容大致长这样项目使用 Maven 做构建测试命令是 mvn test。 在开始写代码前先扫描 .codex/skills 目录。 如果任务涉及测试、提交代码或 Spring 接口开发必须先读取对应技能文件再执行。这里的关键动作是“先扫描再读取”。如果你的项目结构足够清晰AI 几乎每次都能正确索引到技能。我踩过的一个坑是技能文件名用了中文或特殊字符AI 扫描时偶尔会忽略所以技能文件夹名最好统一用英文小写加连字符。2.3 这样设计的代价和边界技能模式不是没有代价。最明显的一点是它依赖 AI 的“自觉性”。如果模型在扫描目录时判断失误或者干脆跳过了扫描动作技能文件就只是摆设。所以你不能假设 AI 一定会去读每次会话开始后最好先给一句显式指令“先看 AGENTS.md按里面的技能规则执行。”这是成本最低的兜底方案。另一个边界是技能文件的粒度。我见过有人把一个“前端开发”大技能写成一份 2000 行的文档AI 读是读了但读完后上下文被撑满后面的代码生成明显变慢而且经常抓不住重点。技能要像菜谱而不是烹饪百科全书。一个技能只解决一类场景步骤控制在 10 到 20 步之间描述要具体到“命令怎么跑、文件放哪里、怎么判断成功”。太抽象AI 不懂太琐碎AI 抓不住主次。Superpowers 的这种“显性文件”思路本质上是把人的经验工程化。它不是让 AI 变聪明而是让 AI 在做事前先看一遍规矩。这一层设计和 prompt 工程相互补充而不是相互替代。3. 安装与配置从零把 Superpowers 跑起来3.1 克隆仓库并放到正确的技能目录安装 Superpowers 的第一步是把技能仓库克隆到你希望 AI 扫描的目录。按照社区最常见的使用方式一般有两种放法全局技能目录和项目级技能目录。全局技能目录对多项目通用。以 Codex CLI 为例可以把仓库克隆到~/.codex/skills下这样你所有项目都能用同一套技能。项目级技能目录则更灵活适合放进 Git 仓库里跟着项目走团队成员 clone 下来后技能自动生效。我个人的习惯是通用技能放全局团队特有规范放项目级。命令如下# 全局安装 git clone https://github.com/your-fork/superpowers.git ~/.codex/skills # 项目级安装 mkdir -p .codex/skills git clone https://github.com/your-fork/superpowers.git .codex/skills/superpowers需要注意Codex 扫描技能目录时通常只关心直接子目录下的技能文件夹。如果你把 Superpowers 仓库克隆到.codex/skills/superpowers那么技能文件夹就在superpowers/skills/下面AI 不一定能自动识别到这一层。为了解决这个问题我一般会把仓库里的skills/*直接复制到.codex/skills/下或者创建软链接让技能文件夹成为.codex/skills/的直接子目录。3.2 在 Codex 配置文件里声明技能目录光把文件放到位还不够你要让 Codex 知道这里存在技能。目前 Codex 生态的配置方式还在快速变化但一个稳妥的做法是在AGENTS.md里显式声明技能路径。示例# 项目/全局技能说明 技能目录.codex/skills/ 使用规则 - 开始任何代码任务前先查看技能目录下是否有匹配的 SKILL.md。 - 若存在匹配技能必须先阅读该文件再开始写代码。 - 若用户明确要求不使用技能则忽略此规则。这段声明看起来简单但它很重要。它相当于给 AI 设置了一个“行动预检”先看技能再动手。如果不写这段文件放在那里AI 也可能一直没发现。如果 Codex CLI 支持读取配置文件例如config.toml也可以在那里增加环境变量或 prompt 拼接逻辑。不过我的建议是优先使用AGENTS.md因为它随项目走不同项目可以有不同的技能规则也不会因为全局配置升级而被覆盖。3.3 最小可用的验证流程安装完之后不要急着开始大项目。先做一个最小验证确认技能真的被 AI 读到。我通常用“让 AI 总结技能目录”来测试。在 Codex 里输入请列出 skills 目录下所有可用的技能并告诉我 tdd 技能的使用步骤前三条。如果 AI 正确列出技能名称并复述出步骤说明扫描和读取都正常。如果 AI 说“我没有找到 skills 目录”那就检查路径你是不是把技能放错层级了AGENTS.md里有没有写清目录名当前会话是不是旧会话没有重新加载配置这个验证流程 5 分钟内就能完成但它能帮你排除 80% 的路径和配置问题。我见过很多人在技能没生效时反复重装工具最后发现只是目录层级多套了一层浪费了大半天。4. Java 项目实战用 Superpowers 驱动 AI 写 Spring Boot 接口4.1 在 Java 项目里准备环境Java 生态和前端、脚本语言项目有一个很大不同构建工具复杂Maven、Gradle 二选一还涉及到依赖下载、JDK 版本、测试框架选择。Superpowers 技能文件本身是语言无关的但里面的命令必须适配 Java 项目。我以一个常规的 Spring Boot 项目为例。项目使用 MavenJDK 17测试框架是 JUnit 5构建命令是mvn test。为了让 AI 在执行时少踩坑我会在AGENTS.md里写清楚基础环境JDK 版本17 构建工具Maven 3.9 测试命令mvn test 测试框架JUnit 5 Spring Boot Test这些信息看似基础但能避免 AI 在后面乱用npm test或者python -m pytest。Superpowers 里很多技能文件会包含“运行测试”这一步如果你的AGENTS.md声明了mvn testAI 就能直接照做。同时我会把技能目录里的tdd技能稍微做一点本地化比如在SKILL.md的步骤里注明“先写一个失败的 JUnit 测试再运行 mvn test 确认失败原因”。这不算改造只是把技能里的通用步骤映射到 Java 语境。4.2 实战案例让 AI 按 TDD 流程实现一个接口这一次我要让 Codex 实现一个简单接口GET /api/messages返回格式如下{content: Hello, Superpowers!}按我的经验如果直接让 AI 写它会一次性生成 Controller、Service、实体类然后告诉你“完成了”。但使用 Superpowers 后流程完全不同。我给的指令是请使用 tdd 技能为 GET /api/messages 接口开发功能。 要求 1. 先从 Controller 层写一个失败的 MockMvc 测试。 2. 运行 mvn test确认测试因缺少接口而失败。 3. 再编写最小实现代码直到测试通过。 4. 最后检查代码命名和结构并运行完整测试。Codex 读到“使用 tdd 技能”后会先去技能目录读取tdd/SKILL.md。技能文件里包含红-绿-重构流程先写失败测试、实现最小代码、重构。于是 AI 的第一步不是写 Controller而是创建src/test/java/com/example/MessageControllerTest.java。测试代码大概长这样package com.example; import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest; import org.springframework.test.web.servlet.MockMvc; import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get; import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath; import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status; WebMvcTest(MessageController.class) class MessageControllerTest { Autowired private MockMvc mockMvc; Test void shouldReturnHelloMessage() throws Exception { mockMvc.perform(get(/api/messages)) .andExpect(status().isOk()) .andExpect(jsonPath($.content).value(Hello, Superpowers!)); } }AI 写完测试后自动执行mvn test因为此时MessageController还不存在编译失败测试红。接着它开始写实现package com.example; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import java.util.Map; RestController RequestMapping(/api) public class MessageController { GetMapping(/messages) public MapString, String getMessage() { return Map.of(content, Hello, Superpowers!); } }再次运行测试全部通过。整个过程里AI 没有被用户催着“下一步再下一步”而是靠技能文件的流程自己推进。这对习惯传统编程的人来说有点不太适应但确实高效。4.3 接上 Git 工作流技能让提交信息符合规范代码写完不算完。Superpowers 里的另一个高频技能是 Git 工作流它会约束 AI 的提交行为先看 diff、再写提交信息、提交信息要符合 Conventional Commits 规范。我通常会让 Codex 在完成功能后自动进入 Git 流程。指令是使用 git-commit 技能检查本次改动生成符合 Conventional Commits 的提交信息并执行提交。AI 会先运行git diff然后根据技能文件里的规范把提交信息写成feat(api): add message endpoint with TDD这种格式。这一步省去了很多手动整理提交信息的精力。这里有个细节值得注意Superpowers 的 Git 技能不会自动执行git push因为推送是一个有副作用的操作。技能文件里通常会写成“提交到本地仓库不自动推送”。如果你希望 AI 自动推送需要在技能文件里显式增加“执行 git push 前必须经过用户确认”。这个边界很重要否则团队协作时容易把半成品推上远程分支。5. 常见问题与排查技巧技能不生效、AI 乱跑、Java 环境差异5.1 技能文件没有被加载怎么办我遇到的最高频问题就是“技能根本没被加载”。现象是你和 AI 说“使用 tdd 技能”它回一句“好的”然后继续按老套路写代码好像技能文件不存在。排查路径按顺序走第一确认路径。技能文件夹必须是 AI 扫描目录的直接子目录。如果你的结构是.codex/skills/repo/skills/tdd那就是多了一层AI 找不到。把所有技能文件夹直接放在.codex/skills/tdd层级上。第二确认AGENTS.md里的描述够不够明确。如果文件里只写了“技能目录在 .codex/skills”AI 可能不理解“什么时候该读”。要写清楚“任务涉及测试、提交、调试时必须先读技能”给 AI 一个明确的触发条件。第三确认你没有在旧会话里继续操作。技能扫描通常发生在会话建立时。你在会话中途修改了技能文件AI 可能仍然读取的是旧的上下文。新开一个会话再试。第四用最傻的命令兜底。直接在对话里输入“请打开.codex/skills/tdd/SKILL.md按里面的步骤执行”。显式指定路径AI 无法拒绝。这是最可靠的排查法。5.2 AI 读了技能但不照着做有时候技能文件确实被读了但 AI 给出的代码仍然不符合规范。这通常不是模型不听话而是技能文件里的指令和当前任务产生了冲突或者技能步骤写得不够可执行。举个例子技能里写“为每个公开方法编写测试”但你没有告诉 AI 测试框架是什么AI 就有可能生成 JUnit 4 风格的测试而项目用的是 JUnit 5导致编译失败。解决方法是把技能文件里的“测试”细化成“运行mvn test且使用 JUnit 5 注解”。另一个常见原因是技能文件里的步骤和用户需求存在歧义。用户说“实现一个查询接口”技能说“先写失败测试”AI 可能会困惑是先设计接口路径还是先写测试这时候需要在技能文件里加一句明确说明“从需求中提取接口路径和响应字段先写测试再实现。”把决策顺序写明白。如果还是不行就在提示词里给一个高优先级指令“本次任务必须以 tdd/SKILL.md 为准如果技能步骤与实际冲突按技能步骤执行。”这句“按技能为准”能压过很多模型的默认偏好。5.3 Java 项目特有的 Maven/Gradle 适配问题Java 项目里最容易出问题的不是技能逻辑而是构建工具细节。Maven 首次运行会下载大量依赖如果网络不好mvn test可能卡住几分钟。AI 在执行 TDD 流程时如果一直等不到结果就可能跳过测试直接写代码。我在技能文件里加入了超时提示“运行 mvn test 时等待时间不超过 120 秒如果超时先检查网络和本地仓库。”这个提示对 AI 很有用它不会傻等。还有一个坑是 Maven 多模块项目。比如项目分了common、api、service三个模块测试命令在父目录和模块目录下效果不一样。技能文件里的“运行测试”必须写明在哪个目录执行。我的做法是在AGENTS.md里声明模块结构并提醒 AI“测试命令必须在包含对应模块 pom.xml 的目录下执行”。另外如果项目用的不是 Maven 而是 Gradle记住让 AI 读技能时同时看到AGENTS.md里的gradle test说明。Superpowers 的技能文件本身不带构建工具知识它依赖项目配置文件把通用流程转成具体命令。5.4 问题速查表现象可能原因快速解法AI 完全没提到技能路径放错 / AGENTS.md 未声明显式要求“打开 SKILL.md”执行AI 读了技能但行为没变技能步骤不够具体细化步骤规定命令和产出物测试命令跑错没有声明 Maven/Gradle在 AGENTS.md 明确测试命令技能文件太大一次加载太多上下文拆分技能单个不超过 200 行提交信息不规范Git 技能未触发提醒“使用 git-commit 技能检查 diff”旧会话配置没生效技能目录修改后未重开新开会话再测试这张表是我自己排障时用的基本能覆盖 90% 的问题。剩下 10% 属于模型偶尔抽风重开会话一般都能解决。6. 进阶玩法把手艺写进自定义技能打造个人版 Superpowers6.1 用十分钟写一个最简技能文件Superpowers 不只可以用现成技能它还鼓励你把自己的习惯写成技能。比如你团队要求所有接口必须有 OpenAPI 注解所有数据库操作必须走 Repository 层这些规范都可以固化成技能。一个最简技能文件只需要三块frontmatter、正文步骤、示例。我用一个“Java 新增接口规范”技能来演示。创建目录.codex/skills/java-api-rule/在里面放SKILL.md--- name: java-api-rule description: 新增 HTTP 接口时必须遵守的规范适用于 Controller 开发和接口扩展场景。 --- # Java API 开发规范 ## 使用时机 - 新增 Controller 接口 - 修改已有接口路径或参数 ## 步骤 1. 在 Controller 类上使用 RestController 和 RequestMapping。 2. 每个接口方法显式标注 GetMapping、PostMapping 等 HTTP 方法注解。 3. 接口返回值统一放入 Service 层处理Controller 不写业务逻辑。 4. 如果涉及新增 DTO字段名使用 camelCase并在 Swagger 注解中补充说明。 5. 运行 mvn test 和 mvn compile确认无报错。 ## 示例 参考 src/main/java/com/example/controller 下的 MessageController。写完之后在AGENTS.md里补一行任务涉及 HTTP 接口时先读取java-api-rule技能。然后新开会话测试让 AI“新增一个删除接口”看它是否自动遵守这些规范。这个技能文件的核心价值不是文档而是“可执行”。AI 会真的按照步骤逐个操作而不是把你的规范当作参考意见。这也是 Superpowers 和普通 README 最大的区别。6.2 团队共享与版本管理建议技能文件一旦发挥作用就会成为团队的资产。我强烈建议把项目级技能目录纳入 Git 版本管理并指定专人维护。技能文件更新时走正常的代码审查流程不要直接改完就提交。团队共享有一个常见矛盾每个人都有自己的惯用技能放在同一个项目目录里会越积越多导致 AI 扫描时难以匹配。我的建议是分级管理通用技能放在自动化构建好的基础镜像或全局目录里团队特有技能放在项目目录里个人偏好技能单独放不提交到公共仓库。例如项目根目录.codex/skills/放团队规范用户全局目录~/.codex/skills/放通用编程技能个人目录~/.codex/personal-skills/放个人习惯。在AGENTS.md里只声明前两者个人技能通过额外指令触发。这样技能目录既不会被塞爆也不会泄露个人偏好给整个团队。6.3 什么时候没必要用 Superpowers说句实话不是所有项目都适合上这套技能机制。如果你只是写一次性脚本、做简单原型或者 AI 只是帮你做代码补全那 Superpowers 可能不但帮不上忙还会因为多了一次技能读取而拖慢响应。技能系统的价值在于“流程复用”而流程复用建立在频繁执行同类任务的基础上。低频、零散、探索型任务直接写 prompt 更高效。另外一个不适用场景是高度非确定性的探索任务。比如你要研究一个新的第三方库连你自己都不知道标准流程是什么技能文件自然也无从写起。这时候应该让 AI 自由探索而不是用技能框住它。Superpowers 适合的场景是你清楚知道“一件事应该怎么做”但希望每次都不打折扣地执行。它把“知道”和“做到”之间的距离缩短了这才是它的真正价值。说句实在话我用 Superpowers 最大的收获不是让 AI 多写了多少代码而是强迫自己把工作流想清楚了。你写得出来什么样的技能就约等于你日常开发里有哪些可复用的方法论。技能文件不是给 AI 看的文档它是你团队经验的持续集成。我的建议很简单从一两个高频场景开始比如 TDD 或者 commit 规范坚持用两周再回来改技能文件你会发现 AI 的表现完全不是同一个量级。