把日常编码从 IDE 切到终端之后我对 Codex CLI 一度又爱又气。爱的是它确实能写气的是它总差点“工程师的自觉”——让它加个功能它真的只加功能不补测试、不更新文档、不检查边界。我一开始以为这是模型能力问题直到我把 obra 的 superpowers 装进~/.codex/skills才反应过来缺的根本不是智商是工作流。superpowers 说白了就是一套 AI 编码技能包把资深工程师的规划、TDD、调试、复盘方法写成一批 Markdown 技能文件让 Codex CLI 这类终端编码代理在干活时不再像个“只有天赋没有纪律”的实习生。这篇文章就记录我从安装到日常使用的完整过程以及那些文档里没写的坑顺便聊聊怎么把它塞进 Trae Work CN 这类带界面的 AI 编码环境。1. superpowers 到底是什么以及它为什么值得装1.1 一个“有纪律”的 AI 搭档先说清一个容易混淆的点superpowers 不是一个模型不是 API也不是 IDE 插件。它是一组 Markdown 技能文件核心是给 AI 编码代理定义一套行为准则。你可以把它理解成“新人手册 团队研发规范 代码评审清单”的合集只不过这本手册不是给人看的是给 AI 在每次行动前重读的。默认状态下你在 Codex 里说“帮我写一个函数”它就乖乖写一个函数。你不会意外它也不会多想。但如果你说“帮我把订单模块重构一下”它可能直接开干跳过测试、跳过对旧接口的兼容检查改完还自信满满。superpowers 改变的就是这个它把“资深工程师接到需求后本能会做的那套动作”固化成技能AI 一旦检测到任务匹配就会按技能里的步骤走——先规划、再写测试、看到测试失败、实现、重构、收尾。整个过程是显式的你可以随时打断、纠正。1.2 核心构成SKILL.md 与技能目录superpowers 的文件组织非常朴素每个技能一个文件夹里面至少有一个SKILL.md用自然语言描述这个技能的用途、触发条件、执行步骤和边界。某些技能还会附带参考文档、脚本或者模板。比如我这台机器上已经有一批技能目录core-workflow、test-driven-development、plan-formation、debugging、code-review、github-api等。每个目录名对应一种能力。SKILL.md的开头通常会写“Use this skill when...”明确告诉 AI 什么时候该用它什么时候不该用——这一点很重要否则 AI 会什么都往技能上套。在 Codex CLI 里技能的触发方式既可以是斜杠命令也可以是自然语言。你输入/tdd或者直接说“这次用 TDD 来做”AI 就会把test-driven-development技能里的流程加载出来然后一条条执行。相比普通对话这种触发方式更接近“给 AI 换了一套工作模式”。1.3 解决了哪三个实际问题第一AI 很少主动补测试。不是模型不行是没人告诉它“这个需求需要测试先行”。技能文件把这条规定写死了AI 每次处理功能开发都会先问测试写了吗第二多轮对话里 AI 会丢上下文。你前面说过“记得补测试”“记得处理空指针”聊了 20 轮之后它基本忘了。技能文件是持久化的约束它每次都会重新读取相当于把团队规范刻进了环境的肌肉记忆里。第三个人或小团队很难沉淀 prompt。你可以把一套好用的提示词存成文本但保存、版本管理、复用都是问题。superpowers 天然就是文件目录用 git 管理、团队共享、按项目裁剪都很方便。2. 安装前的环境确认版本和目录比想象中更容易出错2.1 先确认 Codex CLI 版本superpowers 依赖 Codex CLI 的 skills 机制而这个机制是 0.2.0 左右才正式开放的。如果你还在用老版本就算把技能文件复制进目录Codex 也不会加载。先跑一下codex --version如果版本低于 0.2.0建议直接升级npm install -g openai/codexlatest升级完再确认一次版本。我见过有人卡在这里半天因为技能目录建了、文件放了但 Codex 里就是看不到任何技能——本质是版本太老。2.2 找到正确的技能目录Codex CLI 的技能目录位置和系统有关macOS / Linux~/.codex/skills/Windows%USERPROFILE%\.codex\skills\注意是skills目录不是直接把技能文件夹丢进~/.codex根目录。我第一次手动安装时就犯了这个错结果技能文件躺在~/.codex下Codex 假装没看见。如果目录不存在先创建mkdir -p ~/.codex/skills创建完之后建议先看一下~/.codex下有没有config.toml确认 Codex 能正常读取配置。有些人的HOME路径被改过技能目录会跟着变这种情况在服务器或 CI 环境里特别常见。2.3 装之前先跑通一次对话这个步骤看起来多余但真的能省不少排查时间。在终端输入codex进入交互模式随便发一条消息确保 API 访问凭证配置正确、连一次对话能正常返回。很多人技能装完不生效排查到最后才发现codex 在这个终端里压根就没成功跑通过。先解决这个前置条件后面所有问题都会更好定位。3. Codex CLI 安装 superpowers 的完整流程3.1 一键脚本安装官方 README 提供了一键安装脚本本质是检测当前机器的 Codex 和 Claude Code 环境然后把技能文件复制到对应目录。命令是curl -sSL https://raw.githubusercontent.com/obra/superpowers/main/install.sh | bash脚本跑完会输出类似Installed superpowers for codex at ~/.codex/skills的提示。如果机器上没装 git脚本会失败所以先确保git --version有输出。我建议脚本跑完别急着走手动确认一下目录内容ls ~/.codex/skills正常情况下你会看到一堆以技能命名的文件夹。如果列表为空或者路径不对那就是脚本没有正确识别环境直接走 3.2 的手动安装。3.2 手动安装更可控也更推荐一键脚本方便但有时候我并不想全量安装或者想控制版本手动安装反而更稳。手动安装其实就是三步git clone https://github.com/obra/superpowers.git mkdir -p ~/.codex/skills cp -R superpowers/skills/* ~/.codex/skills/如果你只想装其中几个技能可以只复制对应的文件夹比如cp -R superpowers/skills/core-workflow superpowers/skills/test-driven-development ~/.codex/skills/手动安装的好处是技能文件是你自己拷过去的你知道它在那里也知道怎么删、怎么改。脚本安装虽然快但升级时容易覆盖你后续的自定义修改。3.3 验证安装是否生效进入 Codex 交互模式codex然后在输入框里敲/看命令列表里有没有类似/plan、/tdd、/intro的技能。如果列表里有说明技能已经被加载。如果没有先退出重启一次 Codex技能是在启动时扫描目录的不是热加载。更直接的验证方式是发一条消息请按照 TDD 技能处理这个任务帮我写一个判断字符串是否为合法邮箱的函数如果 AI 先给你列计划、再写测试文件说明技能真的生效了。如果它直接甩给你一个正则函数多半是技能没加载或者你的表达没有触发技能匹配。3.4 升级与卸载升级我的习惯是重新拉一次仓库然后手动覆盖cd /tmp git clone https://github.com/obra/superpowers.git cp -R superpowers/skills/* ~/.codex/skills/如果你改过某个技能文件覆盖前先备份。卸载很简单把~/.codex/skills下对应的技能目录删掉就行。想保留目录但让技能失效也可以把SKILL.md重命名成其他后缀。4. 在 Trae Work CN 里装载 superpowers skill4.1 为什么要折腾这件事Codex CLI 的强项在终端弱项是可视化操作。日常改文件、看 diff、跑测试我还是会切回 IDE。Trae Work CN 这类 AI 编码工具正好补上这一块界面上能直接看代码、右键跑命令、边写边问。既然 superpowers 本质上就是一堆 Markdown 规则文件理论上任何支持“技能/规则”加载的 AI 环境都可以复用——Trae Work CN 也不例外。4.2 导入自行思路与具体操作我这边实际操作下来的流程是先把 superpowers 源码拿到本地。用 git clone 或者直接下载仓库压缩包都行重点是拿到skills目录。打开 Trae Work CN 的设置找到技能、自定义规则或项目规则相关入口。不同版本入口名称不一样我用的版本是在项目配置目录下维护规则文件。把需要的技能文件夹复制到 Trae 能扫描到的目录。如果 Trae 支持项目级技能目录我建议优先放项目级这样只对当前仓库生效不会污染全局。如果 Trae 对技能目录的支持不够直接退一步的办法是把核心SKILL.md内容作为自定义规则粘贴到规则区。这样 AI 至少能读到行为约束只是少了一些斜杠命令式的触发。保存后重启 Trae 或新建一个会话让技能加载进去。4.3 验证与调整在 Trae Work CN 的对话窗口里输入类似“请使用 core-workflow 来处理我的需求”观察 AI 是否开始按步骤执行、先写计划、再询问边界条件。如果 AI 的反应和普通模式没区别大概率是规则没加载成功。另一个建议是不要一次导入全部技能。superpowers 全套技能对日常 IDE 会话来说偏重我通常会只导入core-workflow、test-driven-development、debugging这几个核心的剩下的按需再加。技能多了之后 AI 可能会在某些无关任务上执行额外步骤反而拖慢节奏。4.4 这类工具加载技能的共性逻辑无论 Codex CLI 还是 Trae Work CN加载技能的核心逻辑都是AI 在每次对话前或执行任务前会扫描当前可用的技能/规则文件把与任务匹配的内容注入上下文。所以关键点有三个文件格式对不对一般是 Markdown、目录位置对不对工具能扫到、内容是否描述清楚触发条件AI 得知道什么时候该用它。明白这个逻辑之后遇到“技能没生效”的问题就能很快定位先看文件在哪个目录再看文件格式是不是工具支持的最后看 SKILL.md 里的描述是否足够明确。5. 实操链路用 superpowers 跑通一次完整的 TDD 开发5.1 一个具体的小任务合法邮箱判断函数为了直观展示差异我用一个几乎每个开发者都写过的例子写一个 Python 函数判断输入字符串是不是合法邮箱。普通模式下的 Codex 会直接给你import re def is_valid_email(email: str) - bool: pattern r^[a-zA-Z0-9._%-][a-zA-Z0-9.-]\.[a-zA-Z]{2,}$ return bool(re.match(pattern, email))看起来没错但仔细想问题不少exampledomain这种没有顶级域名的字符串会被判为非法而某些内部系统的邮箱确实没有顶级域名超大字符串的性能没人测过对abc.com这样的输入没做处理最要命的是这段代码没有一行测试。5.2 加载 superpowers 之后发生了什么我让 Codex 启用 TDD 技能处理同一个任务它的行为完全变了首先它没有直接写实现而是先输出一个简短的执行计划先建测试文件、写边界用例、运行看到失败、再实现、再跑测试、最后重构。然后它创建了test_is_valid_email.py测试用例覆盖了常规邮箱、缺少、缺少域名、多个、空字符串、超长字符串、带中文注释的边界情况、以及明显不该通过的值。跑一遍测试确认全部失败。接下来才是写实现。而且它没有急着套正则而是先和我确认是否需要支持国际化域名是否需要支持 IP 作为域名这两个问题在普通模式下它从不主动问。实现写完之后测试全绿。它又花了一步做重构——把一层层嵌套的正则拆开改成更易读的组合逻辑并顺手补了类型注解。整个过程里它多次停顿等待我确认而不是一口气给完就闭嘴。这种“带着你走一遍研发流程”的体验和之前“丢给你一段代码”完全不同。5.3 我的真实体感最明显的不是代码质量飞跃而是节奏变了。以前我的 AI 编码流程是“我说需求、它扔代码、我来 review”本质上还是在使用一个高级补全工具。用上 superpowers 之后流程变成“我说需求、它提计划、我们讨论边界、它写测试、再实现”。代码质量提升是一方面更重要的是我对每次改动的内容和原因更清楚了。对于不熟悉 TDD 的人这套流程相当于有人逼着你把测试补完。对于本来就有 TDD 习惯的人它省去了每次对话里重复交代“先写测试再实现”的功夫。6. 容易被忽略的坑以及我的排查路径6.1 技能文件复制错位我前面提到过第一次手动安装时我把技能文件夹直接复制到了~/.codex根目录。结果 Codex 交互模式里/列不出任何技能但目录里明明有文件。排查到最后发现Codex 只认~/.codex/skills/下的目录且每个技能必须是一个独立文件夹SKILL.md必须在该文件夹下。把SKILL.md直接扔到skills根目录同样不识别。6.2 安装后技能没生效先别怀疑文件遇到技能不生效我现在的排查顺序是版本对不对 → 目录对不对 → 文件结构对不对 → 重启过没有 → 触发方式是不是符合技能描述。卡住的时候先在 Codex 里输入/help或查看斜杠命令列表确认 skills 相关命令存在再逐步排查。跳过这个过程直接改文件往往是瞎忙。6.3 自己改过的技能被升级覆盖这是最后一个容易踩的坑我用了一周后觉得core-workflow里的某个描述不够贴切手动改了一版。之后某天重新跑安装脚本全部被覆盖成原版。如果打算自定义技能建议 fork 一份仓库或者把自定义内容移到单独的技能目录里不做全量覆盖式升级。6.4 别把 superpowers 神化最后想泼一盆冷水。superpowers 不是魔法技能文件只是把方法论固化下来代码质量依然高度依赖底层模型的能力。小到一个变量改名大到临时排查一个线上问题都不必每次都走完整流程。我现在的使用姿势是轻量任务直接普通对话新功能、重构、复杂 bug 才主动切到对应的技能模式。工具是拿来用的不是拿来供着的。如果非要说这套东西给我最大的改变倒不是代码写得更好看了而是它让我重新想明白一件事所谓工程经验能被显式写下来的部分就该写下来交给工具去执行——这正是 superpowers 在做的事。