最近我花了不少时间调教 Codex让它别一上来就写代码。按理说AI 编程助手已经是很多人的日常可如果你想让它在真实项目里扛事光靠默认行为远远不够。后来我找到社区里一个叫 superpowers 的项目它不改变模型本身却能给 Codex 加一层工作规则让 AI 从“想到哪写到哪”变成“先规划、再测试、后实现、最后复盘”。这篇文章就聊聊我是怎么用它、踩过哪些坑以及怎样把它变成自己的开发习惯。如果你已经在用 Codex 这类工具看这篇应该会很对胃口即使还没开始用也能从这套思路里得到一些启发。1. superpowers到底是什么不是插件而是一套写给AI的“工作手册”1.1 核心机制把工作流封装成技能文件superpowers 的核心是一堆 Markdown 文件每个文件对应一个“技能”比如 test-first、plan-and-execute、review。这些文件不是给人看的知识文档而是当你在对话中触发某个技能时Codex 会读取文件内容并把它当作本次任务的额外行为准则。你可以把每个技能想象成给实习生的一页纸操作规范写了“先做A再做B”AI 就会照着走。这里有一个很关键的工程化思路大模型本身没有持久的记忆也不会自动遵循复杂的团队规范你只能通过提示词影响它的行为。superpowers 把这件事做成了可持续积累的模块。和普通一句话提示词相比它的优势体现在三点一是可复用同一个技能可以出现在任何项目里不用每次重新编二是可组合多个技能可以串成一条完整流水线三是可版本管理改了一个文件就等于改了所有新会话中的 AI 行为。我见过最典型的误区是有人以为 superpowers 是一个需要编译安装的插件或者是一个新的代码生成引擎。其实它既不改变模型权重也不封装 API它就是一套结构化的 text 指令。Codex 之所以能“听懂”是因为技能文件里写的是清晰、可执行的步骤而不是模棱两可的建议。换句话说它不是造车而是给司机一本驾驶手册。1.2 解决的真实痛点从“有问必答”到“靠谱交付”直接用 Codex 最大的体验落差是它写出来的代码很流畅但经常跑偏。比如我让它给一个工具类加方法它会直接写实现加几个测试却不先问我边界条件让它重构它往往一口气改好几处最后没法定位是哪一步出了问题。superpowers 解决的就是这种“过程失控”。它不直接提高模型智商而是强制 AI 先展示计划再按计划推进每一步都有检查点。你可以把这个过程类比成一个老工程师带新人新人代码能力不差但不知道先澄清需求、再写测试、最后小步提交。老工程师给新人一张 check-list新人照着做产出质量自然稳定。superpowers 就是那张 check-list而且是用 AI 能理解的语言写的。它并不限制想象力而是把“发散”放在“规划阶段”把“收敛”放在“执行阶段”。这既保留了 AI 的优势又能规避它容易自作主张的问题。比如AI 可以在一开始列出三个方案但只有在用户确认后它才会选一个深入实现。这个“先对齐再动手”的动作对真实项目尤其重要。直接让 AI 全权发挥大概率会得到一份“看起来很完整、但需求完全错位”的代码。1.3 适合谁用正在用 Codex/CLI 编程助手的人适合三拨人。第一拨是已经把 Codex 接入日常开发、但总在返工的人装上技能能明显减少无效改动。第二拨是团队里想统一 AI 使用规范的人把技能文件提交到仓库所有人都按同一套规则和 AI 协作。第三拨是提示词爱好者想看看一个完整技能包是怎么设计出来的。如果你只是偶尔用 AI 查两个 API这个项目可能对你来说偏重但只要你想让 AI 独立处理完整任务就值得动起来。直接使用和加 superpowers 的行为差异我可以用一张表说明对比维度直接使用 CodexCodex superpowers行为风格偏随机看上下文心情有固定流程按步骤走测试覆盖看需求描述是否提醒强制先写测试修改范围可能一次改很多文件小步提交便于定位问题可复用性每次重新描述规则技能文件沉淀随处可用指令可维护性聊天记录不可维护文件可 review、可版本化装不装不是“能不能用”的问题而是“用起来稳不稳”的问题。如果你已经厌倦了给 AI 反复擦屁股这个项目值得认真看一遍。2. 安装与初始化从零到第一个技能跑通2.1 环境准备与依赖检查开始之前先确认你的环境是完整的。superpowers 本质上是文本技能包但它要配合 CLI 工具使用所以 Git、Node.js 和 Codex CLI 这三样基本跑不掉。Node 版本不要太老建议直接用 LTS否则后续技能管理脚本可能出现一些莫名其妙的兼容问题。打开终端跑一遍这三条命令git --version node --version codex --version如果哪一步提示 command not found先把它补齐再继续。别跳过这一步否则后面技能文件扫描不到你会以为项目坏了其实是基础环境没有装好。我在一台新机器上试过Codex 已经装好但忘了装 Git结果连仓库都克隆不下来排查了半天才发现是最基础的依赖缺了。2.2 获取并放置 superpowers 技能包克隆项目仓库到本地。我习惯放在用户目录下一个叫 superpowers 的文件夹里命令长这样git clone 仓库地址 ~/superpowers具体仓库地址以项目 README 为准不同版本可能会变。克隆完之后先用ls确认一下目录结构ls ~/superpowers/skills正常情况下应该能看到很多 markdown 文件文件名就是技能名。如果只有一个 README说明仓库结构和你预期的不一样这时候不要硬找直接打开 README 看它推荐的目录结构。我遇到过一些改版后的技能包把技能文件挪到了prompts/下面如果按照旧习惯配置永远扫不到。接下来让 Codex 能找到这个技能目录。如果 Codex CLI 支持配置文件可以在config.toml里加一行skill_dirs [~/superpowers/skills]如果你不想改全局配置也可以在启动 Codex 时带一个参数比如codex --skill-dir ~/superpowers/skills不同版本的启动参数可能不一样所以遇到问题最优先看codex --help输出。这步如果做对了后面整个流程就顺了做错了后面所有技能都会像没听见一样。2.3 触发和验证怎么知道安装成功装完之后我在新会话里先做一个最小验证输入“superpowers list”。如果它能在技能目录里找到文件就会把可用的技能列出来。这一步特别重要不要上来就直接让它干活。列出来之后可以随手启用一个简单的技能比如“启用 review 技能帮我看看当前目录有没有明显问题。”如果 AI 开始按照技能里定义的步骤回复而不是只凭感觉乱说就说明技能生效了。如果列不出来先别怀疑人生按第5章的排查表走一遍大多数问题都出在路径和配置上。我第一次装的时候技能文件明明在目录里但superpowers list就是空。后来才发现我把技能目录挂到了全局配置但 Codex 当前工作目录不在用户目录相对路径解析出了问题。改成绝对路径之后立刻就好了。2.4 让技能跟着项目走团队级配置我自己不用全局技能目录因为不同项目写法不一样。更推荐在项目根目录建一个.ai/skills/目录把常用的技能文件复制进去然后在项目里放一份AGENTS.md写明“先读取 .ai/skills 下技能再开始工作”。这样每次在新会话中打开项目Codex 会先看到项目自己的约定再决定用哪个技能。团队协作时这些文件可以进 Git所有人拉下来就是同一套规则比在聊天里口头要求 AI 稳定得多。团队配置还有一个好处新人加入时不用自己在聊天框里手工复制一大段规范。只要让 AI 读取AGENTS.md它就会自动把项目里约定的技能文件都加载进来。相比每个人维护一份个人配置这种方式既统一又容易审计。代码 review 的时候技能文件也可以被 review规则是怎么演化的都有迹可循。3. 核心技能拆解三类最常用的“超能力”3.1 规划型技能动手之前先对齐第一个我常启用的是 plan-and-execute。它会要求 AI 在写代码前先输出一个简短计划包含目标、受益点、具体步骤和验收标准。用户确认后 AI 才继续。这个技能最大的作用不是“多一步废话”而是把任务拆到可验证的颗粒度。比如你让它“给用户模块加一个导出功能”如果不加约束它可能立刻开始写导出 Excel 的代码但你其实只需要 CSV。启用 plan-and-execute 后它会先问导出格式、文件大小上限、是否需要异步处理。这些问题看似耽误时间实际上能阻止一次大返工。我自己的习惯是凡是需要改动多个文件的任务必须先启用这个技能。有一次我让它重构一个支付回调模块它一上来就列出“改为策略模式、增加重试、调整日志、补充测试”四件事。我只想先调整异常处理其他都还没想好。看到计划之后我立刻让它只保留第一项后面三项留到下一轮。如果没有这个技能按 AI 的默认行为它很可能一口气全部改完到时候我想回退都不知道从哪下手。3.2 执行型技能用 TDD 把 AI 关进“笼子”第二个是 test-first也就是测试先行。这个技能会要求 AI 按“红-绿-重构”三步走先写失败测试运行确认失败然后写实现让测试通过最后清理重复代码。老实说直接用自然语言要求 AI “先写测试”时它经常会在实现代码里夹带测试。用了技能文件以后AI 会真的先创建测试文件再跑测试命令看到失败输出后才会开始写实现。这里放一个简化的技能文件示例你自己也可以照着写# test-first 当用户要求实现或修改功能时跟随以下步骤 1. 确认当前测试框架和运行命令。 2. 为预期行为编写最小测试。 3. 运行测试并确认失败。 4. 编写满足测试的最小实现。 5. 再次运行测试直到通过。 6. 重构保持测试绿色。为什么这个技能有效因为“先写测试”这个动作本身就把需求变成了可验证的标准。AI 如果在实现阶段跑偏测试会立刻告诉它错了。相比“你觉得没问题就行”测试是一种客观反馈。尤其是 Java、Python 这种测试工具链成熟的语言让 AI 跑mvn test或pytest相当于给它戴上了缰绳。3.3 检查型技能让 AI 自己审自己的代码第三个是 review。它会要求 AI 像代码审查者一样检查变更关注边界条件、错误处理、性能、可读性和安全风险。启动时机通常是实现完成后、提交前。我经常这样用“启用 review检查刚才改的 Calculator 类。”AI 会输出问题列表和建议而不是简单说“看起来不错”。这个技能的价值在于把 AI 从“作者”切换到“审查者”视角变化能发现很多自嗨留下的坑。有一次 AI 刚写完一段文件写入逻辑review 技能就指出没有处理文件路径不存在的情况也没有考虑编码格式还建议用 try-with-resources 替代手动 close。这些问题在生成代码时被我忽略了但它转换成审查者视角后反而一条条挑出来了。这说明技能的“角色设定”非常关键同一个模型只要让它扮演审查者它的输出风格就会完全不同。3.4 定制你自己的技能格式其实很简单真正让我觉得 superpowers 值得长期用的原因是自定义技能的门槛几乎为零。一个技能文件就是一个 markdown 文件用#标题起个名字正文写触发条件和步骤。比如我自己写了一个 “commit-message” 技能要求 AI 根据 git diff 生成符合 Conventional Commits 的提交信息还写了一个 “cleanup” 技能专门删除注释掉的代码和未使用的 import。这些文件放在技能目录里下一次对话就能用。模板很直白# 技能名 当用户要求做X时按以下步骤执行 1. ... 2. ... 3. ... 输出格式... 注意事项...有个技巧技能文件里最好写明“必须执行的步骤”而不是“建议”因为 AI 对祈使句的遵从度更高。同时把验收标准写上它才知道什么时候可以停止。比如 commit-message 里我会写“只在确认没有未暂存改动时运行命令”这能避免它在错误时机读取 diff。4. 实操过程用 superpowers 完成一次带测试的 Java 代码改动4.1 场景与准备为了展示完整流程我造了一个真实感很强的场景。假设一个 Maven 管理的 Java 项目里有一个Calculator类目前只有add方法。我的需求是给它增加一个divide方法并且要求除数为 0 时抛出IllegalArgumentException。不使用 superpowers 时我大概率会直接让 AI“加一个 divide 方法”它能写出来但不一定想到处理边界和测试。这次我全程遵循 test-first 技能。先看现有代码public class Calculator { public int add(int a, int b) { return a b; } }项目是标准 Maven 结构测试目录已经存在测试框架用的是 JUnit 5。我会把这一点提前告诉 Codex避免它默认生成 JUnit 4 的Before和assertEquals混搭代码。4.2 完整对话流程记录我在 Codex 里输入启用 test-first 技能。当前项目是 Java 8 Maven测试框架是 JUnit 5。请给 Calculator 类增加 divide 方法除数为 0 时抛出 IllegalArgumentException。按照技能的流程Codex 先确认现状然后生成了测试文件public class CalculatorTest { Test void divide_shouldReturnQuotient_whenDivisorIsValid() { Calculator calculator new Calculator(); assertEquals(5, calculator.divide(10, 2)); } Test void divide_shouldThrow_whenDivisorIsZero() { Calculator calculator new Calculator(); assertThrows(IllegalArgumentException.class, () - calculator.divide(10, 0)); } }生成测试文件之后Codex 调用mvn test让测试自然失败。这一步很关键如果 AI 跳过了“看到失败”的环节我会立刻在对话里打断它要求它把测试运行结果贴出来。随后它实现了一个最小的divide方法public int divide(int a, int b) { if (b 0) { throw new IllegalArgumentException(divisor must not be zero); } return a / b; }再次运行mvn test所有测试通过。最后它主动检查测试中是否有重复代码并确认没有其它改动。这个流程看起来很基础但“先失败再通过”这个顺序比让 AI 直接给结果要可靠得多。因为测试失败给了你一个“需求还没被满足”的证据也给了 AI 一个明确的开始点。4.3 哪些环节容易翻车怎么绕开第一AI 可能会跳过“确认测试框架”这一步直接按默认 JUnit 4 生成测试。解决办法是在启用技能时显式告诉项目版本和框架不要让它猜。第二运行测试命令时Codex 可能因为工作目录不对而找不到pom.xml需要在提示里补充“项目根目录是当前目录”。第三启用多个技能时AI 容易混乱。比如同时启用 plan-and-execute 和 test-first它可能在写计划时就穿插测试。我现在的做法是一次只启用一个或者写一个组合技能把步骤串起来。还有一个小坑如果项目里原本就有大量失败的测试test-first 技能会分不清“新增测试导致失败”和“历史测试就挂了”。所以最好先把基线测试跑一遍确认当前是绿色再让 AI 按技能走。否则 AI 可能被失败输出搞懵甚至开始修复跟需求无关的历史问题白白浪费一轮上下文。5. 常见问题与排查技巧实录5.1 速查表五个典型症状症状可能原因解决办法技能不生效技能目录路径配置错误或技能名拼写不一致运行superpowers list验证检查配置AI 不按技能走对话上下文过长技能规则被冲淡重新启用一次技能或开新会话技能文件扫描不到文件扩展名错误、编码不是 UTF-8、权限问题检查扩展名是否 .md转成 UTF-8运行测试/构建命令失败工作目录不对、构建工具版本不一致显式告诉 AI 项目根目录确认命令技能内容互相覆盖同时启用了多个冲突技能一次只启用一个或写组合技能这张表是我实际排查中总结出来的。大多数问题最后都落在“路径配错”和“上下文太长”这两个根因上。上下文太长尤其隐蔽技能规则在最开头声明但任务做到一半AI 已经处理了十几轮对话后面的自然语言指令会逐渐盖过前面的技能约束。这时候最简单的解法就是开新会话重新加载技能而不是在一个长对话里死磕。5.2 三个独家避坑技巧把技能的启用语句放在需求之前例如先说“启用 test-first”再说“实现 divide 方法”。顺序很重要AI 会优先响应最近的高优先级指令但技能启用句如果在需求后面容易被当作背景信息忽略。不要用“你可能需要……”这类模糊表达技能文件里全部写成“必须……”或“依次执行”AI 会更听话。语气越软AI 越容易自由发挥。每次新会话开始时先用superpowers list确认技能目录生效再开始正式任务。这不花多少时间但能避免白干半天然后才发现技能没加载。这几条都是我在使用中被坑出来的经验特别是第二条。第一次写技能文件时我用了大量“可以尝试”“建议考虑”的措辞结果 AI 经常不执行后来改成“必须”“依次执行”效果立竿见影。5.3 一个完整的排查实例技能明明在目录里Codex 却不认有一次我把技能放到项目.ai/skills下但在 Codex 里输入superpowers list却看不到。排查后发现配置里写成了.ai/skills的绝对路径而目录名其实多了一层custom。换句话说路径少写了一层。把路径改成.ai/skills/custom后立刻生效。这件事提醒我每次克隆新版本或改目录结构后先验证而不是靠上一次的经验。还有一个类似案例同事把技能文件命名为test-first.md但在对话里用的是“使用测试优先技能”Codex 没有把中文描述和英文技能文件名匹配上。改回“启用 test-first”后就好了。技能名的匹配是字面意义上的不要指望 AI 帮你做近义词匹配。6. 个人实操感受与扩展建议6.1 使用两周后的直观变化我连续用了两周之后最明显的感受不是代码变聪明了而是返工少了。以前一个中型功能可能要跟 AI 来回五轮现在大概一到两轮就能落出基本可用的代码。因为它在动手之前就把需求边界、测试路径和验收标准总结出来了给我的干扰信息少了很多。代价是第一次用的时候会觉得“太慢了”但算上后续避免的坑整体时间反而更短。另一个变化是我对 AI 的信任度提高了。默认情况下我总担心它漏掉边界条件每次都要逐行 review。现在有了技能约束它至少会在写实现前先确认需求、写测试、再自审我虽然不会完全放心但可以把更多精力放在设计层面而不是机械查漏。这个转变对我来说才是 superpowers 真正值钱的地方。6.2 把 superpowers 迁移到团队协作后来我把技能目录放进了团队仓库要求协作的人按照技能定义和 AI 沟通。有个同事一开始很抗拒觉得多此一举但用了两周后也承认AI 生成的 pull request 质量更稳定代码 review 节省了不少时间。团队协作时要注意技能文件也要 review因为 AI 的行为规则会直接影响产出质量不能写了就完事。我建议在项目里专门留一份文档记录每个技能文件的适用范围和坑点。比如 test-first 适合单模块功能但不适合大规模架构重构review 适合提交前检查但不适合在需求还没对齐时用。团队里如果有人踩了坑就把经验补进技能文档里。这样 superpowers 就从一个静态工具变成了团队知识库。6.3 最后分享一个小技巧把“需求澄清”放在最前面我自己每次开新会话会先启用一个“plan-and-execute”或自制的“需求澄清”技能让 AI 先列出所有需要确认的问题回答完之后再进入实现。这一步看似多花两分钟但在复杂需求上能避免几小时的无效开发。你可以根据项目情况自定义这个技能比如强制 AI 列出“影响范围、兼容性、边界条件、后续扩展”四项。这大概是我从 superpowers 里挖到的最大价值。如果你打算试这个项目我建议你从 test-first 和 plan-and-execute 这两个技能开始跑通一次带测试的功能改动之后再慢慢定制自己的技能文件。不要一上来就追求大而全先把最痛的返工问题解决掉后面自然会知道该往哪个方向加规则。
