最近一直在折腾 Codex CLI，顺手把 GitHub 上很火的 superpowers 技能包装上了。用了两周，最大的感受是：它把 AI 写代码这件事从"随机炼丹"变成了"按流程施工"。如果你也在用 Codex CLI、Claude Code 这类编程智能体，却总觉得"让它干活像开盲盒"——这次生成的代码能跑，下次就崩给你看，那 superpowers 大概率能解决你的问题。
这个项目由 Jesse Vincent（GitHub 上的 obra）发起，火起来的速度相当快。它本质是一套 SKILL.md 技能集合，把 TDD、调试、Web 开发、项目规划这些实操流程，固化成了智能体可以主动读取并执行的标准化步骤。说白了，就是给 AI 装上一套"工程师职业习惯"，让它不再是一个只会接话的对话模型，而是一个真正能按规范干活的协作者。
这篇文章我会从"它到底解决什么问题"讲起，再到安装部署、核心技能拆解、真实会话记录，最后是常见坑的排查。全程用我自己的实操经历说话，你可以直接照着抄作业。
1. superpowers 是什么：先搞清楚它解决的痛点
1.1 一个看似普通却改变工作流的技能包
superpowers 的官方定位是"为编程智能体提供可复用的技能"。听起来很抽象，我换个说法：它是一组 Markdown 文件，每个文件定义了一个完整的工作流程，比如"如何用测试驱动开发写一个功能""如何系统化调试一个 bug""如何给 Web 应用做数据库迁移"。智能体在接到任务时，会先扫描这些技能文件，找到匹配项，然后按文件里的步骤一步步执行。
这个思路最巧妙的地方在于：它不依赖某个特定模型，也不依赖某个特定 IDE。只要你的工具支持读取 Markdown 指令——Codex CLI、Claude Code、Gemini CLI 都可以——就能把这些技能"注入"给智能体。所以它是一个完全开放、跨平台、跨模型的工作流增强方案。
1.2 Codex CLI 为什么需要"动力增强"
先说痛点。Codex CLI 本身的代码理解和生成能力很强，但默认状态下有两个明显问题。
第一个问题是"没有过程意识"。你让它写一个带数据库操作的功能，它可能会直接甩给你一大段代码，但没有测试、没有分步验证、没有错误处理。你也不知道它为什么这么写，出错了更不知道从哪里排查。这就像让一个实习生直接上手写核心模块，写完了算完事，至于能不能跑、有没有边界情况，全靠运气。
第二个问题是"上下文漂移"。Codex CLI 有上下文窗口限制，对话一长，它就容易忘记你最初的约束条件。今天告诉它"项目用 TypeScript 严格模式"，明天它可能在某个文件里又用了 JavaScript 的隐式类型转换。这不是模型笨，而是缺少一个持续存在的"操作规范"来约束它的行为。
superpowers 干的就是这件事。它把人在开发中总结出的最佳实践，写成了智能体每次开工前都要"读一遍"的流程文件。比如 TDD 技能会强制它先写失败测试，再写实现，再做重构；调试技能会引导它先复现问题、再提出假设、再定位根因，而不是上来就乱改代码。
1.3 核心机制：SKILL.md 怎么让 AI"按流程办事"
SKILL.md 这个格式值得一提。它用 Markdown 的 YAML frontmatter 写元信息，包括技能名称（name）和描述（description），正文部分则是具体的操作步骤。智能体在对话中会根据用户请求的语义，结合 description 里的关键词，决定要不要加载某个技能文件。
举例来说，superpowers 里有个 skill 叫 tdd，它的 description 可能是"当任务涉及编写新功能时，使用测试驱动开发流程"。当你对 Codex 说"帮我给用户模块加一个注册接口"，Codex 扫描到"新功能"这个关键词，就会主动去读 tdd 的 SKILL.md，然后按照 RED-GREEN-REFACTOR 的循环来推进工作。
这套机制有几个好处：技能可以独立维护和扩展，你完全可以自己写一个 SKILL.md 放进目录里，马上生效；技能之间没有强依赖，用哪个读哪个，不会污染上下文；而且因为就是普通 Markdown，你随时可以打开文件查看智能体到底在按什么规则干活。透明、可控、可定制，这三点正是我对 AI 编程工具最看重的。
2. 安装前置准备与两种部署方式
2.1 环境要求与 Codex CLI 安装
安装 superpowers 之前，先把基础环境准备好。我用的是 macOS 环境，Node.js 和 npm 是必须的，Git 也要装好。
# 检查 Node.js 版本，建议 18 以上 node -v # 全局安装 Codex CLI npm install -g @openai/codex # 验证安装 codex --versionCodex CLI 装好后，第一次运行需要登录 OpenAI 账号并完成 API 配置。建议先用官方默认配置跑通一个最简单的任务，确认工具本身没问题，再引入 superpowers。不然到时候你分不清到底是 Codex 的问题还是技能包的问题。
2.2 方式一：把技能装到用户级目录
superpowers 支持全局安装，也就是把技能放到用户主目录下，这样所有项目都能用到。我推荐新用户先用这种方式，省心，而且能快速体验完整技能集。
# 克隆 superpowers 仓库 git clone https://github.com/obra/superpowers.git cd superpowers # 查看目录结构，确认 skills 目录存在 ls -la # 你会看到 skills/ 目录，里面按技能名称分子文件夹 # 创建用户级技能目录（Codex 会读取这个位置） mkdir -p ~/.codex/skills # 把技能复制过去 cp -r skills/* ~/.codex/skills/复制完成后可以看一眼目录结构，确认技能文件都到位了：
~/.codex/skills/ ├── tdd/ │ └── SKILL.md ├── webapp/ │ ├── SKILL.md │ └── steps/ │ ├── create-a-webapp.md │ ├── database-migrations.md │ └── debugging-browser-tools.md ├── debugging/ │ └── SKILL.md ├── brainstorming/ │ └── SKILL.md ├── writing-plans/ │ └── SKILL.md └── ...提示：不同版本的仓库目录结构可能略有差异，以你 clone 下来的实际结构为准。关键点是把各个技能文件夹放到 Codex 能找到的 skills 目录下。
2.3 方式二：项目级安装与 AGENTS.md 引用
如果你希望某个技能只在特定项目里生效，或者团队要统一规范，那项目级安装更合适。做法是在项目根目录下建一个.codex/skills目录，然后把技能放进去。
# 在项目根目录执行 mkdir -p .codex/skills cp -r ~/.codex/skills/* .codex/skills/光有技能文件还不够，你还要写一个AGENTS.md文件，让 Codex 知道"这个项目里有技能可以用，开工前先去看看"。
# AGENTS.md ## 项目说明 这是一个使用 superpowers 技能集的项目。 ## 工作流要求 - 在开始任何编码任务之前，先浏览 `.codex/skills` 或 `~/.codex/skills` 目录。 - 找到与当前任务匹配的 SKILL.md 文件后，严格遵循文件中的步骤执行。 - 如果存在多个相关技能，按技能文件给出的优先级顺序执行。这里解释一下为什么需要这一步。Codex CLI 默认会读取项目根目录下的AGENTS.md作为项目级指令，就像 Claude Code 读取CLAUDE.md一样。你在这个文件里明确告诉它"有技能可用、怎么用"，它才会主动去加载技能文件。如果跳过这一步，即使技能文件已经放进目录，Codex 也大概率不会主动发现它们。
2.4 验证技能是否被识别
装完不验证，等于白装。有一个简单的办法：直接在当前目录启动 Codex，问它一句"你能看到哪些 skills？"
codex然后在交互式终端里输入：
请列出你当前可用的 skills，以及各自的用途。如果 superpowers 安装生效，Codex 会按照 SKILL.md 里的 frontmatter 信息逐条列出技能名称和描述。如果它说"没有可用技能"，那就说明路径配置有问题，或者AGENTS.md没有被正确读取。我通常还会让它执行一个最简单的 TDD 任务来实测，比如"用 TDD 方式写一个 JavaScript 的 add 函数"，看它是否会先写测试再写实现。这一步能直接检验技能是否真正进入了工作流。
3. 核心技能逐个拆解：它们到底教 AI 做什么
3.1 TDD 技能：让 AI 先写测试再写实现
superpowers 里最有名也最常用的就是 TDD（测试驱动开发）技能。它把完整的 TDD 循环拆成了三个阶段，每个阶段有明确的目标和退出条件。
- RED：先写一个失败的测试。智能体要清楚描述"预期行为是什么"，并验证测试确实失败。
- GREEN：用最简方式让测试通过。允许写临时实现，目的是快速让绿灯亮起来。
- REFACTOR：在测试保护的条件下重构代码，消除重复，改善结构，确保测试依然全绿。
这套流程对 AI 的意义非常大。默认情况下，Codex 喜欢一口气生成"完美代码"，但"完美"往往是它自以为的。TDD 技能强制它先定义行为边界，再逐步实现，每一步都有测试兜底。实测下来，用 TDD 流程生成的代码，回归测试通过率明显高，后期维护也轻松很多。
有个细节值得注意：TDD 技能里通常还会要求智能体在每完成一个测试-实现循环后，主动跑一遍全量测试，确认没有破坏已有功能。这能在早期就发现回归问题，而不是等到最后集成时一起爆炸。
3.2 Web 应用构建技能：从脚手架到数据库迁移
如果你用 Codex 做 Web 开发，webapp 技能组是另一个高频使用的集合。它不是简单地说"帮我做一个网站"，而是拆成了一系列可执行步骤：
- 创建新 Web 应用：选择技术栈、初始化项目结构、配置构建工具、建立基础路由。
- 数据库迁移：先查看当前 schema，再生成迁移文件，而不是直接在代码里改模型。
- 调试浏览器工具：当页面表现异常时，引导智能体打开开发者工具、检查 Console 报错、分析 Network 请求。
这个技能组的核心价值在于"工序感"。智能体不再是一上来就写业务代码，而是先搭好骨架，再处理数据层，最后做联调。每一步的输出都符合工程惯例，生成的代码也更容易被团队成员接手。
举一个我实际遇到的场景：让 Codex 给一个 Express 应用加 PostgreSQL 存储。没有 superpowers 时，它可能会直接在路由里写 SQL 查询，代码冗余且不安全。用 webapp 技能后，它会先检查现有数据模型，设计迁移文件，再写数据库访问层，最后才接入路由。整个过程就像一个有经验的工程师在操作。
3.3 调试技能：把玄学变成科学
调试是最容易翻车的环节。没有明确流程时，AI 会基于猜测改代码，这次改对了，下次又不知道错哪了。superpowers 的 debugging 技能提供了一套系统化排查思路，我把它简化成四步：
- 复现问题：确定触发条件，记录输入、输出与预期差异。
- 提出假设：基于现象列出所有可能原因，不急着动手。
- 验证假设：通过最小化实验逐个去验证，缩小排查范围。
- 修复与回归：确认根因后修改，并补充测试防止复发。
这套流程看起来就是普通的调试方法论，但难的是让 AI "强制"遵守。有了 SKILL.md 文件，Codex 在遇到"bug""报错""崩溃"等关键词时，会主动按这个顺序走，而不是看到一个错误信息就立刻重写整个文件。我实测多次，按流程走的修复普遍比"盲猜式修复"更稳，而且你还能在对话里看到它是如何一步步定位根因的，过程透明可审查。
3.4 写作与规划技能：Brainstorming 和 Executing Plans
superpowers 里还有一类容易被忽略但很有用的技能，就是规划类。brainstorming 技能会在你抛出一个模糊想法时，引导 AI 先拆解需求、列出可选方案、分析利弊，然后再动手。writing-plans 技能则会把任务分解成可执行的步骤清单，标注优先级和依赖关系。
这类技能特别适合大型重构或者新功能设计。我经常遇到的情况是：任务范围太大，直接让 Codex 实现，它写到一半就迷失了。用 planning 类技能后，它会先输出一份实施计划，我确认无误后再让它进入编码阶段。相当于你在给它派活之前，先让它拿出施工图纸。
4. 实操记录：我如何在项目里跑通整个流程
4.1 一个真实的 TDD 会话实录
为了让你直观感受 superpowers 的作用，我记录了一次用 Codex CLI 实现"用户注册接口"的会话关键节点。
第一步，我在终端输入：
用 TDD 方式给 Express 应用新增一个 POST /register 接口，用户数据存内存即可。Codex 扫描技能目录后，没有直接写路由，而是先输出 RED 阶段内容：它用 supertest 写了一个预期返回 201 状态码的测试文件，并主动运行测试，确认当前是红灯（失败）。它在对话里说了一句类似"测试失败，符合预期，因为接口尚未实现"的话。过程严格按照技能文件要求执行。
第二步，Codex 进入 GREEN 阶段，实现最简路由和内存存储逻辑，让刚才失败的测试通过。它没有顺手加参数校验、没有加密码加密，因为技能文件要求"用最小改动使测试通过，不要提前扩展"。
第三步，REFACTOR 阶段，它开始审视代码结构，把路由处理函数拆成 controller 层，补充参数校验，并再次运行全量测试确认绿灯。整个过程逻辑清晰，每一步都有明确的验证节点。
这个体验和没有技能时的最大区别，就是"步骤可解释"。你能看到它为什么先写测试、为什么不做多余的事、为什么在重构时保持测试全绿。协作变得可控了。
4.2 用 superpowers 改造现有项目的经验
如果你已经有一个存量项目，并不需要推倒重来。我建议渐进式引入，而不是一下子把所有技能都铺上去。
我的做法是：先在项目根目录放好.codex/skills目录并复制需要的技能（初期我只放了 tdd 和 debugging），再写AGENTS.md声明工作流要求。然后挑一个小任务做试点，比如修一个低级 bug 或补几个单元测试。等团队习惯了这种协作方式，再逐步放开 webapp、planning 等更大范围的技能。
一个小建议：不要一次性塞太多技能给 Codex。技能文件本身会占用上下文空间，技能太多反而容易让它在选择时犹豫，甚至加载了不相关的内容。按项目实际需要来配，比追求"全家桶"更高效。
4.3 自定义一个属于你的 Skill
superpowers 最吸引我的一点是它的可扩展性。你可以为团队的特定规范写一个 SKILL.md，让 AI 自动遵守。
我举个具体例子：我的团队要求所有提交信息遵循 Conventional Commits 规范，并且提交前必须跑 lint 和全量测试。我创建了如下技能文件：
--- name: team-commit-workflow description: 当需要创建 commit 或合并请求时，使用团队规定的提交流程：先检查代码质量，再生成符合 Conventional Commits 规范的提交信息。 --- # 团队提交工作流 ## 第一步：质量检查 在生成提交信息之前，先运行 `npm run lint` 和 `npm test`，确保通过。 ## 第二步：提交信息格式 严格按照 Conventional Commits 规范生成提交信息： - `feat: 新增功能` - `fix: 修复 bug` - `refactor: 重构代码` - `docs: 文档变更` - `chore: 构建或辅助工具变更` ## 第三步：自检清单 - [ ] 提交信息的第一行不超过 72 个字符 - [ ] 类型后面有冒号和空格 - [ ] 如果涉及破坏性变更，在正文中标注 BREAKING CHANGE把它放到~/.codex/skills/team-commit-workflow/SKILL.md后，下次让 Codex "帮我提交代码"，它就会先跑 lint 和测试，再按规范生成提交信息。这套机制把团队约定变成了 AI 的肌肉记忆，非常实用。
4.4 多 Agent 共用配置的注意事项
superpowers 不只支持 Codex CLI。我试过把同一套技能目录同时配置给 Codex CLI 和 Claude Code，两个工具都能正常识别。具体做法是给 Claude Code 也建立对应的技能目录：
# Claude Code 读取的技能目录 mkdir -p ~/.claude/skills cp -r ~/.codex/skills/* ~/.claude/skills/不过要注意，Claude Code 使用的项目指令文件是CLAUDE.md，不是AGENTS.md。所以在多 Agent 共用时，你需要在项目里同时维护两份指令文件，或者让CLAUDE.md引用AGENTS.md的内容：
<!-- CLAUDE.md --> # 项目说明 本项目遵循 AGENTS.md 中的全部规则，包括 superpowers 技能的使用方式。 请先阅读 AGENTS.md，再开始任何编码任务。提示：多 Agent 共用一套技能时，建议先在小范围验证。不同工具对 SKILL.md 的解析方式略有差异，个别技能可能在某个工具上表现不同。
5. 常见问题与排查技巧实录
5.1 技能没生效？先查这三处
如果装完之后 Codex 完全没有按技能工作，大概率是这三处出了问题。
第一，技能目录路径不对。Codex 读取的是~/.codex/skills或项目下的.codex/skills，不是skills或Codex/skills这类名字。用ls ~/.codex/skills确认目录里真有 SKILL.md 文件。第二，缺少AGENTS.md指引。没有这个文件，Codex 不知道要去读技能，自然就不会用。第三，技能文件的 frontmatter 写错了。name和description是必填项，少了任何一个，Codex 都可能解析失败，直接跳过该技能。
排查顺序建议是：先看目录路径，再看指令文件，最后检查 SKILL.md 格式。
5.2 上下文膨胀：技能文件太多怎么办
SKILL.md 文件本身会被智能体读取，技能过多、文件过长确实会占用上下文窗口，影响对话质量。我见过有人把几十个第三方技能全部复制到全局目录，结果 Codex 在任务开始时扫描技能列表就消耗了大量 token。
我的经验是分层管理：全局目录只放最通用的核心技能（tdd、debugging、commit-workflow 这类），项目目录按需放业务相关技能。另外，技能文件正文尽量精简，把步骤写得明确但不啰嗦。如果单个技能文件超过了 300 行，建议拆分子步骤文件，只在主 SKILL.md 里留索引和关键判断点。
5.3 模型太"聪明"不按流程走怎么办
有时候你明明配好了 TDD 技能，Codex 却还是一口气生成完整代码，不按 RED-GREEN-REFACTOR 走。我碰到这种情况，通常不是因为技能没加载，而是因为提示词给了它太多"自由发挥"的空间。
解决办法是在任务描述里加上更明确的约束。比如把"帮我写用户注册接口"改成"严格按照 TDD 流程实现用户注册接口，先写失败测试，确认红灯后再实现，最后重构"。关键词"严格按照"能显著提高智能体对技能文件的遵循度。此外，在AGENTS.md中把语气写得更强制，比如"必须""不得"等措辞，效果也会不一样。
5.4 版本更新带来的坑
superpowers 迭代速度很快，我遇到过两次升级后技能目录结构变化的情况。一次是从旧版升级后，原来的某些技能被拆成了多个子技能；另一次是新增了依赖 Node.js 的辅助脚本，需要额外安装。
建议是：升级前先看仓库的 README 和 CHANGELOG，别直接git pull完就复制。如果项目依赖特定版本，最好在项目文档里记录当前使用的 commit 号，方便回滚。我一般会保持一个固定的稳定版本用于生产项目，另一个最新版用于体验新功能。
最后分享一个小技巧
用 superpowers 一段时间后，我发现最值钱的技能往往不是官方预置的那些，而是你根据自己的踩坑经历写出来的那一个。每当你发现 AI 在某个环节反复犯同样的错误，就把它提炼成一个 SKILL.md，下次它就不会再犯了。
我个人的习惯是每两周复盘一次和 Codex 的对话记录，把那些"如果一开始就告诉它正确流程，能省很多事"的场景写成新技能。这套玩法真正把 AI 编程从断断续续的对话，变成了一套不断沉淀团队经验的工作系统。你可以先跑通默认配置，再开始积累自己的技能库，用着用着你就会发现，superpowers 这个名字，起得确实贴切。
