如果你最近在用 Codex CLI 干活八成已经在 GitHub 或技术社区刷到过 superpowers 这个项目。star 涨得飞快评论区清一色是“装完之后 Codex 像换了个人”。我一开始觉得这名字营销味太重但真正照着 README 装了一遍、跑了两三个完整功能之后我的结论是这名字不虚。它不是给 Codex 加了一两个花哨功能而是把一套完整的工程师工作方法直接注入到 AI 编码代理的行为里让 Agent 从“能写代码”变成“会做项目”。这篇文章就把我这几周的实操过程、踩坑经验、技能拆解全部写出来覆盖安装、配置、核心技能、完整实战流程和问题排查适合所有在用 Codex CLI、或者想让 AI 编程更可控更规范的开发者参考。1. superpowers 到底是什么给 Codex CLI 装上一套“工程师思维”简单说superpowers 是一个开源的“技能包”项目专门给 OpenAI 的 Codex CLI 设计。GitHub 上的仓库地址是 obra/superpowers作者是 Jesse Vincent。它的核心不是训练一个新模型也不是写了一个更聪明的提示词模板而是提供了一整套结构化的技能文件告诉 Codex 在什么场景下应该怎么思考、怎么规划、怎么动手写代码。1.1 从“能写代码”到“会做项目”Codex CLI 默认的行为模式说好听点是“快”说难听点是“莽”。你给它一个需求它通常会立刻打开文件开始改改完告诉你“完成了”。小任务这么干没问题但一旦落到真实项目里——多文件、老代码、有测试、有历史包袱——它就容易犯三类错误第一没搞清楚需求就开始动手做出来的东西和你心里想的完全是两回事第二直接改核心文件不留余地、不补测试改完整个项目跑不起来第三不会规划东一榔头西一棒子改到哪算哪。superpowers 的思路是模型本身已经足够强缺的是“过程约束”。它通过一整套技能文件把工程师日常的工作流——需求澄清、方案设计、编写计划、测试驱动开发、代码评审、安全审查——变成 Agent 可以随时调用的“行为准则”。装上之后你再让 Codex 做一个功能它不会再上来就改代码而是先问清楚需求再写一份计划然后按计划逐步实现每一步都带着测试走。说白了就是给一个能力很强但没什么耐心的年轻程序员配了一位经验丰富的导师。1.2 典型应用场景与适合人群我实测下来最值得用 superpowers 的场景有三个。一是新项目从零搭建brainstorm 技能会帮你在动手前把需求、边界、用户故事全部理清避免“第一版就写歪”。二是老项目加功能planning 技能会先生成一份包含数据模型、接口、测试策略在内的实施计划你确认了它才动手大大降低了改崩老代码的概率。三是重构和 Debug专门的调试技能会引导它系统化定位问题而不是靠瞎猜。适合的人群也很明确已经装了 Codex CLI、但觉得默认效果不够稳定的开发者团队里想统一 AI 编码流程、让 Agent 行为可控的工程负责人还有对 AI 编程感兴趣、想理解“技能Skills机制”到底能做什么的学习者。如果你只是偶尔用 Codex 改一行配置、写一个脚本那 superpowers 可能有点重但只要你认真拿它写真实项目这套流程带来的收益会非常明显。2. 为什么需要 superpowers拆解技能机制背后的设计思路在讲安装和用法之前我建议你先理解 Codex CLI 的技能机制。这不是背景知识而是你后面排查问题、自定义技能时必须用到的基础。2.1 Codex CLI 的技能机制是怎么运作的Codex CLI 支持从目录加载“技能”。一个技能本质上是一个文件夹里面有一个核心文件叫 SKILL.md用 Markdown 编写带一段 YAML frontmatter 定义了技能的名称和描述。Codex 启动时会扫描技能目录把每个技能的描述加载到上下文里当你的请求触发了某个技能描述对应的场景它就会读取完整的技能文件按照里面的指令行动。技能目录默认放在~/.codex/skills/也可以放在项目目录下实现团队级共享。除了按需激活某些技能还可以设置为“始终可用always-on”也就是每次会话都把完整内容加载进来适合那些希望 Agent 逢事必守的规则比如“所有代码必须先有测试”。这个机制的精妙之处在于技能就是纯文本完全透明、可编辑。Agent 的行为出了偏差你不用去调“神秘参数”直接打开技能文件看是哪条指令写得不够清楚改一行就能见效。这比传统的“调提示词”要可维护得多。2.2 superpowers 的核心设计先思考、再计划、后实现、必测试superpowers 的整个技能体系围绕一条工程主线展开先思考再计划后实现必测试。这条主线不是口号而是被拆成了一个个可独立调用的技能。第一个环节是“先思考”。brainstorm 技能要求 Codex 在动手前先和你来回对话把需求、约束条件、非目标、用户故事全部问清楚。它甚至会让 Agent 先复述一遍你的需求确认理解一致才进入下一步。第二个环节是“再计划”。writing-plans 技能会把讨论结果转成一份结构化实施计划包含背景、技术方案、分步任务、验收标准、风险点。这份计划本身就是一份可评审的文档你点头它才能继续。第三个环节是“后实现必测试”。test-driven-development 技能规定实现必须走红-绿-重构循环先写测试看到失败再写最小实现让测试通过最后重构收尾。除此之外还有 code-review、security-review、debugging 等一系列辅助技能覆盖开发全流程。这套设计的高明之处在于它把“经验”变成了“文件”。项目里的任何一个人甚至一个新加入的 AI 代理只要加载了 superpowers就等于站在同一位资深工程师的肩膀上干活。团队协作时你不用再苦口婆心地告诉 AI“你要先写计划”技能本身就替你说了。3. 安装与基础配置从零开始启用 superpowers下面进入实操环节。我以 macOS 终端为例Windows 和 Linux 的原理一致只是路径略有差异。3.1 安装前置条件首先保证本机已经装好 Codex CLI 并且能正常登录调用模型。安装 Codex CLI 通常用 npm 或 Homebrew装完在终端执行codex能正常交互即可。其次你需要 git因为安装过程本质上是从 GitHub 拉取技能文件。最后确认终端网络可以正常访问 GitHub 和 npm 源这一步是后续所有操作的前提。我建议安装前先把 Codex 版本更新到比较新的版本技能机制在早期版本里有过不少变化老版本可能缺失相关命令。升级方式一般是重新执行当初安装 Codex 的命令再codex --version确认。3.2 通过 codex install 安装技能包superpowers 的 README 提供了专门的安装命令。以我当时安装的版本为例codex install github.com/obra/superpowers执行后Codex 会从 GitHub 拉取仓库并把技能目录安装到本机技能目录。如果命令提示找不到可以先 clone 仓库到本地再指定路径安装git clone https://github.com/obra/superpowers.git ~/superpowers codex install ~/superpowers提示这个工具迭代很快安装命令的细节将来可能调整。你只需要记住一条原则——安装动作就是把整个skills目录里的内容放到 Codex 能扫描到的技能目录。遇到命令变了到仓库 README 里找最新写法即可。安装完成后codex install 通常还会输出一段后续指引提示你在 Codex 会话里激活 superpowers。不同版本的提示不完全一样但核心是让你在 Codex 里输入类似“Use the superpowers skill to help me get set up”这样的指令让它引导你完成初始化流程。这个初始化很重要它会检查技能是否被正确识别并且帮助你生成后续会话要用的上下文配置。3.3 验证安装与查看技能列表装完不是就结束了一定要验证。最简单的方式是直接问 Codex 自己codex然后在会话里输入“请列出你现在可用的 skills并告诉我 superpowers 是否已经加载”。如果它回答中提到了 brainstorm、writing-plans、test-driven-development 等技能说明安装成功。更直接的办法是查看本机技能目录ls ~/.codex/skills/正常情况下你会看到 superpowers 下的各个技能子文件夹每个文件夹里都有一个 SKILL.md。我还建议检查一下配置文件~/.codex/config.toml确认是否有和 superpowers 相关的配置项。部分版本要求在配置里声明技能可用类似下面的结构字段名请以你本机 Codex 版本为准[always_available_skills] superpowers true这条配置会把 superpowers 的技能描述常驻上下文让 Codex 随时知道它们存在。缺点是会多占用一些上下文空间如果你只在大任务时用 superpowers不设置 always-on 也行。3.4 在 Trae 中复用 superpowers 技能热词里有人提到“trae work cn 安装 superpowers skill”我在实践里也试过。Trae 这类 AI IDE 本身支持自定义技能或自定义 Agent 指令机制和 Codex 的 SKILL.md 非常像。所以复用方式很直接把 superpowers 仓库里的技能文件夹拷贝到 Trae 的技能目录或者通过 Trae 的设置面板手动创建技能粘贴内容。以 Trae 国内版为例在设置中找到“技能”或“自定义指令”入口新建技能时填入技能名称、描述然后把对应 SKILL.md 正文复制进去即可。我试过把 brainstorm 和 test-driven-development 两个技能导入到 Trae 里实测它在 IDE 里也能按技能要求先提问再动手。如果你直接使用 Trae 的 CLI 工具部分版本也支持类似codex install的技能导入命令但兼容性不如手动粘贴稳定。4. 核心技能逐项拆解与实操要点superpowers 不是单一技能而是十几个技能的集合。我挑几个最常用、最核心的逐项拆解每一个都告诉你它是干什么的、怎么触发、有什么坑。4.1 brainstorm动手编码前的需求澄清这是我觉得价值最高的一个技能。没有它Codex 默认遇到一个需求就直接脑补细节然后开工有了它Codex 第一个动作是提问。触发方式很简单你在会话里直接说Use the brainstorm skill to help me design the tag feature.这个技能会指导 Codex 做几件事先用自己的话复述需求确认理解一致然后针对需求中的模糊地带提问——使用者是谁、边界条件是什么、哪些功能明确不做、有没有性能要求、是否需要兼容旧数据。它甚至会把讨论结果整理成包含用户故事和验收标准的文档。实操要点你不需要在第一次提问时就把所有需求说清楚这恰恰是 brainstorm 的价值——它是“对话式”的。我踩过的坑是有些开发者装完 superpowers 后还是习惯一口气把所有细节砸给 Codex结果 Codex 反而不知道从哪里开始。正确姿势是给一个大方向让它逐步提问你逐步回答信息密度更高。4.2 writing-plans输出一份可执行的实施计划brainstorm 讨论清楚了下一步让 Codex 写计划。这个技能的触发指令类似Now use the writing-plans skill to create an implementation plan based on our discussion.它会输出一份结构完整的 Markdown 计划文档包含背景与目标、技术方案选型、数据模型设计、接口定义、分步实施任务、测试策略、验收标准、风险与回滚方案。每步任务都会被描述得非常具体比如“修改 models.py 中 Todo 模型新增 tags 多对多关系并新增一条数据库迁移”。这里有个关键点计划写完后你应该要求 Codex 把计划保存成项目里的一个文件比如docs/plans/tags-feature.md。好处有两个一是后续会话可以随时引用这份文件不用把计划重复塞进上下文二是你可以在文件里直接批注修改让 Codex 按你的意见调整。我的经验是在让 Codex 动手实现前一定要花五分钟仔细读计划。计划里的技术选型如果不对改计划只需要几十秒但你直接让它开写改代码可能就是几个小时。计划阶段是所有 AI 编码流程里性价比最高的审阅点。4.3 test-driven-development让测试驱动开发真正落地这是 superpowers 里约束力最强的一个技能也是让代码质量产生质变的关键。触发方式Use the test-driven-development skill while implementing the plan.技能会要求 Codex 严格遵循循环先写一个会失败的测试运行确认失败写最小实现代码让测试通过运行确认通过然后重构。并且要求每个逻辑单元都独立提交提交信息里说明这一步为什么这么做。实操中你会看到 Codex 的行为明显变化——它不再一口气改十个文件而是改一个测试、跑一次、改一段实现、再跑一次。这个过程虽然显得“慢”但每一步都有反馈出问题立刻知道在哪。坑也有。最大的坑是当项目里已有大量没有测试的老代码时技能可能会要求你为所有老代码补测试这会非常耗时。我的做法是在计划阶段就明确测试范围告诉 Codex“只对新增功能写测试老代码只做回归验证”技能其实是允许你通过对话调整范围的关键是你要主动提。4.4 元技能writing-skills 与自定义技能superpowers 里有一类特殊技能是用来“制造技能”的这就是 writing-skills。它教 Codex 如何把一个重复性工作流封装成标准技能文件。技能文件的格式如下--- name: 技能名称 description: 在什么场景下使用这个技能 --- # 技能说明 这里写具体的操作步骤和规范使用 Markdown 标题组织内容。比如你发现团队每次提交代码都要遵循一套特殊的 commit 规范你可以让 Codex 用 writing-skills 写一个conventional-commits技能以后每次提交前它会自动按规范生成提交信息。这个元技能把 superpowers 从“一个工具”变成了“一套工具制造系统”也是我认为最值得投入时间研究的功能。4.5 辅助技能debugging、code-review、security-review 等除了主线技能superpowers 还附带了不少辅助技能。debugging 技能引导 Codex 按“复现—定位—修复—验证”的流程来排查问题而不是瞎猜。code-review 技能让 Codex 以代码评审者的视角审查改动找逻辑错误、边界问题、可维护性问题。security-review 技能专门扫描安全风险比如硬编码密钥、注入漏洞、越权访问。我在功能完成后习惯让 Codex 运行一轮 code-review凭经验说它能发现不少我自己没注意到的边界错误。下面这个表是我目前最常用的几个技能及触发场景方便你快速索引技能名称触发时机我的使用频率brainstorm新功能开始前需求还不清晰时高writing-plans需求清晰后动手编码前高test-driven-development实现功能时高debugging程序出现 bug 需要定位时中code-review功能实现完成后中writing-skills需要沉淀重复工作流时低但价值极大5. 完整实操流程一个功能从想法到落地的全过程理论讲再多不如完整走一遍。下面我用一个真实场景演示给一个已有的 Node.js TODO 应用增加“标签”功能。5.1 场景设定与准备工作假设项目已经存在技术栈是 Express SQLite前端是简单的 HTML 页面没有测试框架。我进入项目目录启动 Codex CLI。由于项目里没有 AGENTS.md我先让它读取项目结构对代码有个基本了解。这一步很重要Codex 对项目的理解程度直接影响后续计划质量。5.2 第一步激活 brainstorm 技能输入Use the brainstorm skill to help me design a tagging feature for this todo app.Codex 没有立刻打开文件而是开始提问。它先复述了自己的理解“你想给每个 todo 添加一个或多个标签用于分类和筛选”然后问我几个问题标签和 todo 是一对多还是多对多标签需不需要独立管理页面筛选时是要精确匹配还是模糊搜索旧的 todo 数据是否需要兼容标签为空的情况。我逐条回答后它输出了一份简短的讨论纪要里面包含用户故事“作为一个使用者我可以给 todo 添加多个标签并按标签筛选 todo 列表。”以及明确列出的“非目标”暂不做标签管理页面。到这里第一个环节结束我对需求的边界已经有了明确共识。5.3 第二步生成并评审实施计划接着输入Use the writing-plans skill to create a detailed implementation plan from our brainstorm notes.Codex 生成了计划文档核心内容大概是这样# 标签功能实施计划 ## 背景 TODO 应用需要支持给每条待办添加多个标签并支持按标签筛选。 ## 数据模型 - 新增 tags 表id, name - 新增 todo_tags 关联表todo_id, tag_id - 每条 todo 可关联 0..n 个标签 ## 接口设计 - POST /api/todos/:id/tags 添加标签 - DELETE /api/todos/:id/tags/:tagId 移除标签 - GET /api/todos?tagxxx 按标签筛选 ## 实施步骤 1. 创建数据库迁移新增 tags 和 todo_tags 表 2. 更新数据访问层支持标签读写 3. 新增标签相关 API 路由 4. 前端增加标签展示和筛选控件 5. 补充接口测试与基础回归测试 ## 验收标准 - 能通过 API 为 todo 添加和移除标签 - 能通过 tag 参数筛选出包含该标签的 todo - 无标签的旧数据访问不受影响我检查后觉得接口设计合理唯一修改是把“前端增加标签展示”步骤调整为“先加 API 和测试前端最后做”然后让 Codex 更新计划。确认无误后我要求它把计划保存为docs/plans/tags-feature.md。5.4 第三步按 TDD 流程实现输入Use the test-driven-development skill to implement the plan. Start with step 1 and 2.Codex 开始按计划推进。它先搭建了一个最小测试框架然后为数据访问层写出测试运行失败再实现迁移和查询逻辑运行通过。整个过程每一步都有输出我能清楚看到它先写哪个文件、为什么写。中途遇到过一个问题SQLite 的测试需要清空数据库避免数据污染Codex 在计划里没有预见到。它没有擅自跳过而是停下来向我说明情况并建议在测试初始化时重建内存数据库。我同意后它继续执行。这个细节是我觉得整个流程最像“真人工程师”的时刻——遇到与计划偏差的问题先沟通而不是闷头硬改。5.5 第四步验证、评审并沉淀自定义技能API 和前端全部完成、测试通过后我又运行了两次技能Use the code-review skill to review all changes. Use the security-review skill to check the new API endpoints.code-review 帮我发现了一个筛选接口的分页边界问题security-review 则提示新增接口缺少输入长度校验。修复这两处后我又让 Codex 用 writing-skills 把这套“新功能开发流程”封装成一个团队技能以后项目里任何新功能都可以复用这套规范。整个流程下来功能完成、测试齐备、文档齐全这是我用 Codex 默认模式很难达到的完成度。6. 常见问题与排查技巧实录用的时间长了总会遇到各种问题。我把踩过的坑和排查思路整理成速查表希望能帮你少走弯路。问题现象可能原因排查与解决技能完全不生效技能目录路径不对或 Codex 版本过旧检查~/.codex/skills/是否有技能文件夹升级 Codex 版本不点名技能时 Codex 不主动用技能描述不匹配任务类型或未开启 always-on任务开始时显式点名技能高频技能设置为始终可用会话上下文过长回答变慢同时加载的 always-on 技能太多只保留最核心的 1-2 个技能常驻其他按需触发自定义技能与其他技能重名技能目录命名冲突统一技能命名前缀避免覆盖Codex 跳过计划直接改代码用户指令里包含“尽快”“直接改”等授权在 prompt 中明确“先写计划等我确认再实现”在 AGENTS.md 中声明流程Trae 里技能导入后不生效技能正文结构或目录识别差异确认文件名必须为 SKILL.md描述字段清晰重新导入并重启6.1 排查技能加载问题的通用方法如果你怀疑某个技能没被加载最直接的排查方法是让 Codex 自己描述它当前能做什么“请列出你已经读取的所有技能名称和描述。”如果它列出的技能缺少了你要用的那个要么是目录没扫到要么是 SKILL.md 的 frontmatter 写错了。注意技能描述要足够具体描述写得模糊模型很难在正确时机触发它。6.2 上下文管理的经验superpowers 的技能文件合计起来内容不少如果全部设为 always-onCodex 的上下文会被大量占用留给实际代码的注意力就不够了。我的经验是坚持“按需激活”原则只在任务开始时点名需要的技能。长任务做到一半感觉 Codex 反应迟钝就开一个新会话把已有的计划文档路径告诉它让它读取计划后继续而不是在一个越来越臃肿的会话里硬扛。6.3 关于技能安全的提醒最后必须提醒一句技能文件本质上是可执行的“行为指令”它可以让 Codex 运行命令、修改文件、甚至执行脚本。所以最好不要从不可信的来源随意安装技能包安装后也值得花几分钟打开 SKILL.md 读一遍确认里面没有要求执行可疑操作的指令。用 superpowers 这类开源项目前先看看它的 issues 和代码质量这也是一个工程师的基本素养。我自己在实际使用中最深的体会是AI 编程工具的上限从来不只取决于模型多聪明还取决于你愿不愿意给它一套好流程。superpowers 的价值不是让 Codex 写出更花哨的代码而是让每一次编码都变成可控的、可评审的、可复盘的工程行为。装完之后你可能会发现真正“开挂”的不是 Codex是你自己——因为你终于有了一套监督和驾驭 AI 的方法。
Codex CLI神器superpowers：注入工程师思维，让AI编程从写代码到做项目
如果你最近在用 Codex CLI 干活八成已经在 GitHub 或技术社区刷到过 superpowers 这个项目。star 涨得飞快评论区清一色是“装完之后 Codex 像换了个人”。我一开始觉得这名字营销味太重但真正照着 README 装了一遍、跑了两三个完整功能之后我的结论是这名字不虚。它不是给 Codex 加了一两个花哨功能而是把一套完整的工程师工作方法直接注入到 AI 编码代理的行为里让 Agent 从“能写代码”变成“会做项目”。这篇文章就把我这几周的实操过程、踩坑经验、技能拆解全部写出来覆盖安装、配置、核心技能、完整实战流程和问题排查适合所有在用 Codex CLI、或者想让 AI 编程更可控更规范的开发者参考。1. superpowers 到底是什么给 Codex CLI 装上一套“工程师思维”简单说superpowers 是一个开源的“技能包”项目专门给 OpenAI 的 Codex CLI 设计。GitHub 上的仓库地址是 obra/superpowers作者是 Jesse Vincent。它的核心不是训练一个新模型也不是写了一个更聪明的提示词模板而是提供了一整套结构化的技能文件告诉 Codex 在什么场景下应该怎么思考、怎么规划、怎么动手写代码。1.1 从“能写代码”到“会做项目”Codex CLI 默认的行为模式说好听点是“快”说难听点是“莽”。你给它一个需求它通常会立刻打开文件开始改改完告诉你“完成了”。小任务这么干没问题但一旦落到真实项目里——多文件、老代码、有测试、有历史包袱——它就容易犯三类错误第一没搞清楚需求就开始动手做出来的东西和你心里想的完全是两回事第二直接改核心文件不留余地、不补测试改完整个项目跑不起来第三不会规划东一榔头西一棒子改到哪算哪。superpowers 的思路是模型本身已经足够强缺的是“过程约束”。它通过一整套技能文件把工程师日常的工作流——需求澄清、方案设计、编写计划、测试驱动开发、代码评审、安全审查——变成 Agent 可以随时调用的“行为准则”。装上之后你再让 Codex 做一个功能它不会再上来就改代码而是先问清楚需求再写一份计划然后按计划逐步实现每一步都带着测试走。说白了就是给一个能力很强但没什么耐心的年轻程序员配了一位经验丰富的导师。1.2 典型应用场景与适合人群我实测下来最值得用 superpowers 的场景有三个。一是新项目从零搭建brainstorm 技能会帮你在动手前把需求、边界、用户故事全部理清避免“第一版就写歪”。二是老项目加功能planning 技能会先生成一份包含数据模型、接口、测试策略在内的实施计划你确认了它才动手大大降低了改崩老代码的概率。三是重构和 Debug专门的调试技能会引导它系统化定位问题而不是靠瞎猜。适合的人群也很明确已经装了 Codex CLI、但觉得默认效果不够稳定的开发者团队里想统一 AI 编码流程、让 Agent 行为可控的工程负责人还有对 AI 编程感兴趣、想理解“技能Skills机制”到底能做什么的学习者。如果你只是偶尔用 Codex 改一行配置、写一个脚本那 superpowers 可能有点重但只要你认真拿它写真实项目这套流程带来的收益会非常明显。2. 为什么需要 superpowers拆解技能机制背后的设计思路在讲安装和用法之前我建议你先理解 Codex CLI 的技能机制。这不是背景知识而是你后面排查问题、自定义技能时必须用到的基础。2.1 Codex CLI 的技能机制是怎么运作的Codex CLI 支持从目录加载“技能”。一个技能本质上是一个文件夹里面有一个核心文件叫 SKILL.md用 Markdown 编写带一段 YAML frontmatter 定义了技能的名称和描述。Codex 启动时会扫描技能目录把每个技能的描述加载到上下文里当你的请求触发了某个技能描述对应的场景它就会读取完整的技能文件按照里面的指令行动。技能目录默认放在~/.codex/skills/也可以放在项目目录下实现团队级共享。除了按需激活某些技能还可以设置为“始终可用always-on”也就是每次会话都把完整内容加载进来适合那些希望 Agent 逢事必守的规则比如“所有代码必须先有测试”。这个机制的精妙之处在于技能就是纯文本完全透明、可编辑。Agent 的行为出了偏差你不用去调“神秘参数”直接打开技能文件看是哪条指令写得不够清楚改一行就能见效。这比传统的“调提示词”要可维护得多。2.2 superpowers 的核心设计先思考、再计划、后实现、必测试superpowers 的整个技能体系围绕一条工程主线展开先思考再计划后实现必测试。这条主线不是口号而是被拆成了一个个可独立调用的技能。第一个环节是“先思考”。brainstorm 技能要求 Codex 在动手前先和你来回对话把需求、约束条件、非目标、用户故事全部问清楚。它甚至会让 Agent 先复述一遍你的需求确认理解一致才进入下一步。第二个环节是“再计划”。writing-plans 技能会把讨论结果转成一份结构化实施计划包含背景、技术方案、分步任务、验收标准、风险点。这份计划本身就是一份可评审的文档你点头它才能继续。第三个环节是“后实现必测试”。test-driven-development 技能规定实现必须走红-绿-重构循环先写测试看到失败再写最小实现让测试通过最后重构收尾。除此之外还有 code-review、security-review、debugging 等一系列辅助技能覆盖开发全流程。这套设计的高明之处在于它把“经验”变成了“文件”。项目里的任何一个人甚至一个新加入的 AI 代理只要加载了 superpowers就等于站在同一位资深工程师的肩膀上干活。团队协作时你不用再苦口婆心地告诉 AI“你要先写计划”技能本身就替你说了。3. 安装与基础配置从零开始启用 superpowers下面进入实操环节。我以 macOS 终端为例Windows 和 Linux 的原理一致只是路径略有差异。3.1 安装前置条件首先保证本机已经装好 Codex CLI 并且能正常登录调用模型。安装 Codex CLI 通常用 npm 或 Homebrew装完在终端执行codex能正常交互即可。其次你需要 git因为安装过程本质上是从 GitHub 拉取技能文件。最后确认终端网络可以正常访问 GitHub 和 npm 源这一步是后续所有操作的前提。我建议安装前先把 Codex 版本更新到比较新的版本技能机制在早期版本里有过不少变化老版本可能缺失相关命令。升级方式一般是重新执行当初安装 Codex 的命令再codex --version确认。3.2 通过 codex install 安装技能包superpowers 的 README 提供了专门的安装命令。以我当时安装的版本为例codex install github.com/obra/superpowers执行后Codex 会从 GitHub 拉取仓库并把技能目录安装到本机技能目录。如果命令提示找不到可以先 clone 仓库到本地再指定路径安装git clone https://github.com/obra/superpowers.git ~/superpowers codex install ~/superpowers提示这个工具迭代很快安装命令的细节将来可能调整。你只需要记住一条原则——安装动作就是把整个skills目录里的内容放到 Codex 能扫描到的技能目录。遇到命令变了到仓库 README 里找最新写法即可。安装完成后codex install 通常还会输出一段后续指引提示你在 Codex 会话里激活 superpowers。不同版本的提示不完全一样但核心是让你在 Codex 里输入类似“Use the superpowers skill to help me get set up”这样的指令让它引导你完成初始化流程。这个初始化很重要它会检查技能是否被正确识别并且帮助你生成后续会话要用的上下文配置。3.3 验证安装与查看技能列表装完不是就结束了一定要验证。最简单的方式是直接问 Codex 自己codex然后在会话里输入“请列出你现在可用的 skills并告诉我 superpowers 是否已经加载”。如果它回答中提到了 brainstorm、writing-plans、test-driven-development 等技能说明安装成功。更直接的办法是查看本机技能目录ls ~/.codex/skills/正常情况下你会看到 superpowers 下的各个技能子文件夹每个文件夹里都有一个 SKILL.md。我还建议检查一下配置文件~/.codex/config.toml确认是否有和 superpowers 相关的配置项。部分版本要求在配置里声明技能可用类似下面的结构字段名请以你本机 Codex 版本为准[always_available_skills] superpowers true这条配置会把 superpowers 的技能描述常驻上下文让 Codex 随时知道它们存在。缺点是会多占用一些上下文空间如果你只在大任务时用 superpowers不设置 always-on 也行。3.4 在 Trae 中复用 superpowers 技能热词里有人提到“trae work cn 安装 superpowers skill”我在实践里也试过。Trae 这类 AI IDE 本身支持自定义技能或自定义 Agent 指令机制和 Codex 的 SKILL.md 非常像。所以复用方式很直接把 superpowers 仓库里的技能文件夹拷贝到 Trae 的技能目录或者通过 Trae 的设置面板手动创建技能粘贴内容。以 Trae 国内版为例在设置中找到“技能”或“自定义指令”入口新建技能时填入技能名称、描述然后把对应 SKILL.md 正文复制进去即可。我试过把 brainstorm 和 test-driven-development 两个技能导入到 Trae 里实测它在 IDE 里也能按技能要求先提问再动手。如果你直接使用 Trae 的 CLI 工具部分版本也支持类似codex install的技能导入命令但兼容性不如手动粘贴稳定。4. 核心技能逐项拆解与实操要点superpowers 不是单一技能而是十几个技能的集合。我挑几个最常用、最核心的逐项拆解每一个都告诉你它是干什么的、怎么触发、有什么坑。4.1 brainstorm动手编码前的需求澄清这是我觉得价值最高的一个技能。没有它Codex 默认遇到一个需求就直接脑补细节然后开工有了它Codex 第一个动作是提问。触发方式很简单你在会话里直接说Use the brainstorm skill to help me design the tag feature.这个技能会指导 Codex 做几件事先用自己的话复述需求确认理解一致然后针对需求中的模糊地带提问——使用者是谁、边界条件是什么、哪些功能明确不做、有没有性能要求、是否需要兼容旧数据。它甚至会把讨论结果整理成包含用户故事和验收标准的文档。实操要点你不需要在第一次提问时就把所有需求说清楚这恰恰是 brainstorm 的价值——它是“对话式”的。我踩过的坑是有些开发者装完 superpowers 后还是习惯一口气把所有细节砸给 Codex结果 Codex 反而不知道从哪里开始。正确姿势是给一个大方向让它逐步提问你逐步回答信息密度更高。4.2 writing-plans输出一份可执行的实施计划brainstorm 讨论清楚了下一步让 Codex 写计划。这个技能的触发指令类似Now use the writing-plans skill to create an implementation plan based on our discussion.它会输出一份结构完整的 Markdown 计划文档包含背景与目标、技术方案选型、数据模型设计、接口定义、分步实施任务、测试策略、验收标准、风险与回滚方案。每步任务都会被描述得非常具体比如“修改 models.py 中 Todo 模型新增 tags 多对多关系并新增一条数据库迁移”。这里有个关键点计划写完后你应该要求 Codex 把计划保存成项目里的一个文件比如docs/plans/tags-feature.md。好处有两个一是后续会话可以随时引用这份文件不用把计划重复塞进上下文二是你可以在文件里直接批注修改让 Codex 按你的意见调整。我的经验是在让 Codex 动手实现前一定要花五分钟仔细读计划。计划里的技术选型如果不对改计划只需要几十秒但你直接让它开写改代码可能就是几个小时。计划阶段是所有 AI 编码流程里性价比最高的审阅点。4.3 test-driven-development让测试驱动开发真正落地这是 superpowers 里约束力最强的一个技能也是让代码质量产生质变的关键。触发方式Use the test-driven-development skill while implementing the plan.技能会要求 Codex 严格遵循循环先写一个会失败的测试运行确认失败写最小实现代码让测试通过运行确认通过然后重构。并且要求每个逻辑单元都独立提交提交信息里说明这一步为什么这么做。实操中你会看到 Codex 的行为明显变化——它不再一口气改十个文件而是改一个测试、跑一次、改一段实现、再跑一次。这个过程虽然显得“慢”但每一步都有反馈出问题立刻知道在哪。坑也有。最大的坑是当项目里已有大量没有测试的老代码时技能可能会要求你为所有老代码补测试这会非常耗时。我的做法是在计划阶段就明确测试范围告诉 Codex“只对新增功能写测试老代码只做回归验证”技能其实是允许你通过对话调整范围的关键是你要主动提。4.4 元技能writing-skills 与自定义技能superpowers 里有一类特殊技能是用来“制造技能”的这就是 writing-skills。它教 Codex 如何把一个重复性工作流封装成标准技能文件。技能文件的格式如下--- name: 技能名称 description: 在什么场景下使用这个技能 --- # 技能说明 这里写具体的操作步骤和规范使用 Markdown 标题组织内容。比如你发现团队每次提交代码都要遵循一套特殊的 commit 规范你可以让 Codex 用 writing-skills 写一个conventional-commits技能以后每次提交前它会自动按规范生成提交信息。这个元技能把 superpowers 从“一个工具”变成了“一套工具制造系统”也是我认为最值得投入时间研究的功能。4.5 辅助技能debugging、code-review、security-review 等除了主线技能superpowers 还附带了不少辅助技能。debugging 技能引导 Codex 按“复现—定位—修复—验证”的流程来排查问题而不是瞎猜。code-review 技能让 Codex 以代码评审者的视角审查改动找逻辑错误、边界问题、可维护性问题。security-review 技能专门扫描安全风险比如硬编码密钥、注入漏洞、越权访问。我在功能完成后习惯让 Codex 运行一轮 code-review凭经验说它能发现不少我自己没注意到的边界错误。下面这个表是我目前最常用的几个技能及触发场景方便你快速索引技能名称触发时机我的使用频率brainstorm新功能开始前需求还不清晰时高writing-plans需求清晰后动手编码前高test-driven-development实现功能时高debugging程序出现 bug 需要定位时中code-review功能实现完成后中writing-skills需要沉淀重复工作流时低但价值极大5. 完整实操流程一个功能从想法到落地的全过程理论讲再多不如完整走一遍。下面我用一个真实场景演示给一个已有的 Node.js TODO 应用增加“标签”功能。5.1 场景设定与准备工作假设项目已经存在技术栈是 Express SQLite前端是简单的 HTML 页面没有测试框架。我进入项目目录启动 Codex CLI。由于项目里没有 AGENTS.md我先让它读取项目结构对代码有个基本了解。这一步很重要Codex 对项目的理解程度直接影响后续计划质量。5.2 第一步激活 brainstorm 技能输入Use the brainstorm skill to help me design a tagging feature for this todo app.Codex 没有立刻打开文件而是开始提问。它先复述了自己的理解“你想给每个 todo 添加一个或多个标签用于分类和筛选”然后问我几个问题标签和 todo 是一对多还是多对多标签需不需要独立管理页面筛选时是要精确匹配还是模糊搜索旧的 todo 数据是否需要兼容标签为空的情况。我逐条回答后它输出了一份简短的讨论纪要里面包含用户故事“作为一个使用者我可以给 todo 添加多个标签并按标签筛选 todo 列表。”以及明确列出的“非目标”暂不做标签管理页面。到这里第一个环节结束我对需求的边界已经有了明确共识。5.3 第二步生成并评审实施计划接着输入Use the writing-plans skill to create a detailed implementation plan from our brainstorm notes.Codex 生成了计划文档核心内容大概是这样# 标签功能实施计划 ## 背景 TODO 应用需要支持给每条待办添加多个标签并支持按标签筛选。 ## 数据模型 - 新增 tags 表id, name - 新增 todo_tags 关联表todo_id, tag_id - 每条 todo 可关联 0..n 个标签 ## 接口设计 - POST /api/todos/:id/tags 添加标签 - DELETE /api/todos/:id/tags/:tagId 移除标签 - GET /api/todos?tagxxx 按标签筛选 ## 实施步骤 1. 创建数据库迁移新增 tags 和 todo_tags 表 2. 更新数据访问层支持标签读写 3. 新增标签相关 API 路由 4. 前端增加标签展示和筛选控件 5. 补充接口测试与基础回归测试 ## 验收标准 - 能通过 API 为 todo 添加和移除标签 - 能通过 tag 参数筛选出包含该标签的 todo - 无标签的旧数据访问不受影响我检查后觉得接口设计合理唯一修改是把“前端增加标签展示”步骤调整为“先加 API 和测试前端最后做”然后让 Codex 更新计划。确认无误后我要求它把计划保存为docs/plans/tags-feature.md。5.4 第三步按 TDD 流程实现输入Use the test-driven-development skill to implement the plan. Start with step 1 and 2.Codex 开始按计划推进。它先搭建了一个最小测试框架然后为数据访问层写出测试运行失败再实现迁移和查询逻辑运行通过。整个过程每一步都有输出我能清楚看到它先写哪个文件、为什么写。中途遇到过一个问题SQLite 的测试需要清空数据库避免数据污染Codex 在计划里没有预见到。它没有擅自跳过而是停下来向我说明情况并建议在测试初始化时重建内存数据库。我同意后它继续执行。这个细节是我觉得整个流程最像“真人工程师”的时刻——遇到与计划偏差的问题先沟通而不是闷头硬改。5.5 第四步验证、评审并沉淀自定义技能API 和前端全部完成、测试通过后我又运行了两次技能Use the code-review skill to review all changes. Use the security-review skill to check the new API endpoints.code-review 帮我发现了一个筛选接口的分页边界问题security-review 则提示新增接口缺少输入长度校验。修复这两处后我又让 Codex 用 writing-skills 把这套“新功能开发流程”封装成一个团队技能以后项目里任何新功能都可以复用这套规范。整个流程下来功能完成、测试齐备、文档齐全这是我用 Codex 默认模式很难达到的完成度。6. 常见问题与排查技巧实录用的时间长了总会遇到各种问题。我把踩过的坑和排查思路整理成速查表希望能帮你少走弯路。问题现象可能原因排查与解决技能完全不生效技能目录路径不对或 Codex 版本过旧检查~/.codex/skills/是否有技能文件夹升级 Codex 版本不点名技能时 Codex 不主动用技能描述不匹配任务类型或未开启 always-on任务开始时显式点名技能高频技能设置为始终可用会话上下文过长回答变慢同时加载的 always-on 技能太多只保留最核心的 1-2 个技能常驻其他按需触发自定义技能与其他技能重名技能目录命名冲突统一技能命名前缀避免覆盖Codex 跳过计划直接改代码用户指令里包含“尽快”“直接改”等授权在 prompt 中明确“先写计划等我确认再实现”在 AGENTS.md 中声明流程Trae 里技能导入后不生效技能正文结构或目录识别差异确认文件名必须为 SKILL.md描述字段清晰重新导入并重启6.1 排查技能加载问题的通用方法如果你怀疑某个技能没被加载最直接的排查方法是让 Codex 自己描述它当前能做什么“请列出你已经读取的所有技能名称和描述。”如果它列出的技能缺少了你要用的那个要么是目录没扫到要么是 SKILL.md 的 frontmatter 写错了。注意技能描述要足够具体描述写得模糊模型很难在正确时机触发它。6.2 上下文管理的经验superpowers 的技能文件合计起来内容不少如果全部设为 always-onCodex 的上下文会被大量占用留给实际代码的注意力就不够了。我的经验是坚持“按需激活”原则只在任务开始时点名需要的技能。长任务做到一半感觉 Codex 反应迟钝就开一个新会话把已有的计划文档路径告诉它让它读取计划后继续而不是在一个越来越臃肿的会话里硬扛。6.3 关于技能安全的提醒最后必须提醒一句技能文件本质上是可执行的“行为指令”它可以让 Codex 运行命令、修改文件、甚至执行脚本。所以最好不要从不可信的来源随意安装技能包安装后也值得花几分钟打开 SKILL.md 读一遍确认里面没有要求执行可疑操作的指令。用 superpowers 这类开源项目前先看看它的 issues 和代码质量这也是一个工程师的基本素养。我自己在实际使用中最深的体会是AI 编程工具的上限从来不只取决于模型多聪明还取决于你愿不愿意给它一套好流程。superpowers 的价值不是让 Codex 写出更花哨的代码而是让每一次编码都变成可控的、可评审的、可复盘的工程行为。装完之后你可能会发现真正“开挂”的不是 Codex是你自己——因为你终于有了一套监督和驾驭 AI 的方法。