Superpowers技能包：让AI编码代理遵循TDD与任务拆解高效工作

Superpowers 这个项目，名字起得相当直白——给 AI 编码代理“超能力”。如果你已经在用 Codex CLI、Claude Code 这类跑在终端里的 AI 编程工具，大概率会遇到同一个瓶颈：模型本身很聪明，但真让它独立完成一个有点复杂的任务时，往往不会“干活”——不拆需求、不写测试、改着改着就把上下文丢了，最后给你一坨能跑但很难维护的代码。Superpowers 就是冲着这个问题来的。它不是又一个代码生成模板，也不绑定特定厂商，而是一套以 SKILL.md 文件为载体的技能包。装上之后，AI 代理会按照一套被反复验证过的方法论来工作，比如测试驱动开发（TDD）、任务拆解、代码审查、文档阅读、复盘重构等。这篇内容我会从安装方式、配置细节、实际工作流和踩坑记录四个维度展开，给已经在用或准备用 Codex CLI、Trae 这类工具的人一份可以直接照着操作的手册。

1. Superpowers 是什么，解决 AI 编码代理“聪明但不会干活”的问题

1.1 先说痛点：模型很强，但缺少工作方法

我最早用 Codex CLI 的时候，感觉就像招了一个名校毕业但没有任何工作经验的新人：你问他某个 API 怎么用，他答得飞快；但你把一个完整的需求丢给他，他会给你一个“看起来合理”的方案，却从来不会先自己质疑需求、更不会主动写测试。更常见的情况是，你让他改一个函数，他直接把整个文件的逻辑重构了一遍，然后告诉你“我觉得这样更好”。单看结果可能还行，但你要 review 这样的改动，成本非常高。

这个问题的根源不在于模型能力，而在于我们根本没有给模型一套“做事方法”。普通的 prompt 技巧，比如“请先写测试再写实现”“请逐步思考”，有一定效果，但非常依赖你每次都记得写清楚；而且一旦任务复杂，模型很容易偏离最初的约束。Superpowers 的思路完全不同：它把“做事方法”固化成项目的技能文件，让代理在每次启动工作时先读取这些文件，再按里面定义好的步骤去执行。

1.2 Superpowers 的核心设计：SKILL.md 驱动的技能包

Superpowers 本质上是一个 GitHub 上的开源项目，里面按“技能（skill）”维度组织了一堆 Markdown 文件。每个技能对应一个 SKILL.md，文件里写清楚了：这个技能解决什么问题、在什么场景启用、具体的执行步骤是什么、有哪些质量要求和禁忌。模型读这个文件，本质上就是在“照章办事”。

这个设计最聪明的地方在于透明和可改。Prompt 是人写的一段话，写完了模型怎么理解你很难控制；但 SKILL.md 是文本文件，你可以打开看，也可以按自己的团队规范去改。比如 Superpowers 默认的 TDD 技能要求先写测试再写实现，但如果你维护的是一个测试覆盖本来就低的老项目，完全可以改造一下流程，让模型先做影响面分析，再决定要不要补测试。这种灵活性，是普通 prompt 模板给不了的。

默认技能集里比较常用的几个：TDD 工作流、任务拆解、代码审查、架构探索、深度研究、重构流程等。这些技能不是孤立存在的，Superpowers 有一套“启动流程”：代理先读主 SKILL.md，搞清楚当前目标，然后按需调用对应子技能，一步一步推进。所以它更像一个“工作操作系统”，而不是简单的命令集合。

2. 从零安装：Codex CLI 与 Trae 场景实测

2.1 准备工作：运行时与依赖

安装 Superpowers 的前提是你已经装好了对应的 AI 编码代理。以 Codex CLI 为例，它需要在本地有 Node.js 环境，通过 npm 全局安装：

npm install -g @openai/codex

装完之后用codex命令确认版本正常：

codex --version

同时需要确认git已安装，因为克隆仓库和后续更新都要用到。如果你打算在 Trae 的 Agent 模式里使用技能包，不需要额外的运行时，但需要能找到 Trae 的自定义技能目录，后面 2.4 会说。

2.2 官方仓库的几种安装方式

Superpowers 的官方仓库地址在 GitHub 上，项目名就叫 superpowers，维护者是 Jesse Vincent。安装方式大致分三种，我实际用下来分别适合不同场景：

我自己的做法是：第一台机器用脚本安装，快速跑通；跑通之后再手动改成 clone + 软链的形式，方便我后续加自己的私有技能。脚本安装本质上是把仓库克隆到本地目录，然后去~/.codex/skills、~/.claude/skills这类已知目录里建软链。

2.3 Codex CLI 安装 Superpowers 的关键步骤

如果你只打算给 Codex CLI 用，最简单的方式是手动操作，整个过程两三分钟：

# 1. 克隆仓库到本地，目录名保持 superpowers git clone https://github.com/jesse-vent/superpowers.git ~/.superpowers # 2. 如果项目有依赖，先装一下（官方仓库会带一个简单的 Node 脚本做安装） cd ~/.superpowers npm install npm run build # 3. 把 skills 目录软链到 Codex CLI 的配置目录 mkdir -p ~/.codex ln -s ~/.superpowers/skills ~/.codex/skills # 4. 确认软链生效 ls -la ~/.codex/skills

Codex CLI 在工作时会自动读取~/.codex/skills下的技能文件，前提是你所在的目录结构里配置了AGENTS.md，或者在启动对话时明确要求它先读主 SKILL.md。更稳妥的做法是：在项目的根目录放一个引用文件，内容指向 Superpowers 的主 SKILL.md：

<!-- AGENTS.md --> 请先阅读 `~/.superpowers/SKILL.md`，其中定义了完整的协作方式。每次开始任务前，按里面的启动流程执行。

这样一来，Codex 进入项目目录时会优先读取 AGENTS.md，然后顺着指引加载技能，不需要每次手动敲一大段 prompt。

2.4 Trae 工作区安装 Skill 的社区做法

Trae 这边的情况稍微有点不一样。Trae 的 Agent 模式本身支持自定义技能，社区里常见的做法是把 Superpowers 的 skill 目录复制到项目工作区的./trae/skills目录，或者在 Trae 的设置里指定自定义技能路径。

我在 Trae 里试过两种方式：

• 方式一：在项目根目录创建trae/skills/文件夹，把~/.superpowers/skills下的子技能目录整体复制进去。之后新建 Agent 会话时，在提示词里写明“请先阅读项目内 trae/skills/SKILL.md”，模型就会按流程走。
• 方式二：如果你用的是 Trae 的工作流（Workflow）功能，可以把 Superpowers 的 TDD 技能拆成“生成测试用例 -> 运行测试 -> 实现代码 -> 回归验证”四个节点，每个节点对应一个 skill 文件。这样不需要靠 prompt 提示，工作流本身就约束了执行顺序。

需要注意：Trae 对工作区技能的扫描策略可能随版本调整，我遇到过“明明复制进去了但 Agent 不读”的情况，大概率是 Trae 只扫描固定的AGENTS.md或skills目录，这时候在系统提示词里显式加一句“请阅读 xxx/SKILL.md”最管用。

3. 核心使用方式：Superpowers 是把“项目管理方法论”塞进了代理

3.1 理解 skill 的调用机制：不是插件，而是“工作要求”

很多第一次用 Superpowers 的人会问：这算不算一个插件？装上之后要不要点按钮激活？其实不是。Superpowers 的定位更像是“给代理看的入职培训手册”。它不劫持模型，不改变模型本身的推理能力，只是给模型提供了一套决策框架。

在 Codex CLI 里，你启动会话后，如果项目下有 AGENTS.md 且里面引用了主 SKILL.md，代理会自动加载技能定义。之后每一次任务，它都会先根据主 SKILL.md 的指导，判断当前属于什么类型的工作，再选择调用哪个子技能。这个过程类似你给新人一份 SOP，他遇到问题先查 SOP，而不是凭感觉来。

这里有个关键点：skill 文件本身不是代码，它对模型来说是“高优先级 prompt”。所以同一个模型，在没装 Superpowers 和装了之后，输出质量差异会非常大。我实测过同一个重构任务，没装技能时模型直接给了整文件替换方案；装了之后它会先列出影响面、写测试、再小步重构，最后还要我确认测试结果。过程繁琐一些，但每个 diff 都可 review，安全性完全不同。

3.2 最值得用的几个技能

Superpowers 默认带的技能不少，但说实话，日常开发里我高频用到的就几个：

• TDD 工作流：核心是 red-green-refactor。模型先写一个会失败的测试，再写最小实现让测试通过，最后重构。这个技能对提升代码质量非常明显，尤其适合新模块开发。
• 任务拆解（Breakdown）：把大需求拆成一个个可验证的小步骤。模型会给每个步骤标注依赖关系、完成标准和验证方式。这个技能帮我治好了“派活太模糊”的问题。
• 代码审查（Code Review）：让模型按照明确的维度去审查代码，比如安全性、可测试性、边界条件、性能等。比直接说“帮我 review 一下代码”强很多，因为它的审查标准是恒定的。
• 深度研究（Deep Research）：当遇到一个不熟悉的技术栈或框架时，让模型先阅读项目源码和相关文档，再给出结论。它在动手前会先建立“上下文地图”。

这些技能是可以组合的。比如一个新功能，可以先走任务拆解，拆出若干个任务；每个任务内部再走 TDD 流程；全部完成后走一次代码审查。整个过程不需要你反复写大段 prompt，只要你在一开始把目标说清楚，代理会自己带着“流程意识”走完。

3.3 实战示例：一个最小功能从拆解到交付

用一个小例子说明工作流长什么样。假设我让 Codex CLI 给一个 JavaScript 工具函数库增加“带缓存的 fetch 封装”：

codex

启动后在提示里写：

请用 project scope 模式处理以下需求： 为 utils 目录新增一个带缓存的 fetch 封装，缓存失效时间可配置。 请按 Superpowers 标准流程执行。

正常情况下，代理会先读取主 SKILL.md，然后输出任务拆解：

无需重新安装依赖。 根据标准流程，我先把任务拆成 3 步： 1. 写测试：定义缓存命中、缓存过期、缓存清理的行为 2. 实现：完成带 TTL 的 fetch 包装函数 3. 审查：检查并发请求是否会导致重复请求 现在开始第 1 步，先写会失败的测试。

接下来它会创建utils/__tests__/cachedFetch.test.js，里面是几个期望失败的测试用例；跑一遍确认是红色；然后写cachedFetch.js的实现，让测试变绿；最后可能还会主动提一句“可以考虑加一个防止缓存击穿的优化”。整个过程不需要你频繁打断，你只需要在关键节点审查 diff。

如果你用的是 Trae，类似的效果可以在工作流里配置：先让 Agent 写测试、跑测试、再实现。区别是 Trae 的界面会把每一步展示在面板里，你可以在中间插话修正方向。

4. 常见问题与避坑实录

4.1 代理根本不读 skill 怎么办

这是最多人遇到的问题。装完 Superpowers，启动会话后代理表现和以前完全一样，好像技能文件不存在。我排查这类问题的顺序是：

• 先确认软链有没有建对：ls -la ~/.codex/skills看目标是否存在且指向正确目录。
• 再确认项目里有没有 AGENTS.md：Codex CLI 默认只有在读取到 AGENTS.md 后，才会把里面的内容写进上下文。没有这个文件，代理根本不知道要去看主 SKILL.md。
• 如果都确认了，直接在对话里敲“请阅读 ~/.superpowers/SKILL.md 并执行其中的 process flow”，观察代理是否复述技能内容。如果它连文件都读不到，大概率是路径权限问题，改用cat ~/.superpowers/SKILL.md | codex的方式强制喂给它。

还有种隐蔽情况：代理把它当成普通文档，看了但没有按流程执行。这时候你需要在 AGENTS.md 里把引用写得更“强硬”一些，比如明确写“所有任务必须严格遵循该文件中定义的 TDD 流程，不得跳过测试步骤”。模型对命令式表述的遵从度明显更高。

4.2 路径、软链和权限问题

macOS 和 Linux 下用软链基本没问题，但 Windows 环境要注意：CMD 的ln -s需要管理员权限，或者用 Git Bash 执行。如果在 WSL 里面装，而 Codex CLI 装的是 Windows 原生版本，路径对不上，就会导致技能读了不生效。我的建议是：Windows 上尽量直接复制目录，不要用软链，省去后面一堆麻烦。

另外，Superpowers 仓库更新比较快，你如果通过软链引用，git pull 更新后所有代理会立即生效；但如果你复制到了多个项目目录，就需要手动同步。我一般只在团队共享的模板仓库里用复制方式，个人开发机一律用软链。

4.3 与团队现有规范冲突怎么处理

Superpowers 默认的工作流可能跟你团队现有的习惯冲突，最典型的是 TDD。很多老项目连测试框架都没有，硬让代理先写测试，代理会卡住或者假装写测试。这种场景我不建议硬上。解决办法很简单：改 SKILL.md。

我会把默认 TDD 技能里的“必须先从测试开始”改成“先判断模块是否已有测试框架；若有，按 TDD 流程；若没有，先做影响面分析，并建议是否值得引入测试”。模型读完这个改造后的文件，行为就会贴合你的项目现状。这也正是 Skill 文件比固定 prompt 更友好的地方——你要的不是“统一标准”，而是“可执行的流程”。

4.4 几个容易踩的坑和我的使用心得

我踩过最典型的坑是两个。第一，把技能包当成万能钥匙，任何任务都让对方跑完整套流程。结果一个“改个文案”的需求，模型花半天拆步骤写测试，浪费了大量 token。Superpowers 的 skill 应用应该有判断：简单任务可以直接跳过流程。现在我会在启动对话时明确给一个“复杂度等级”，比如“这是个 trivial change，不用走完整流程”，代理就会收敛很多。

第二个坑是过度信任流程的产物。Superpowers 让代理写出来的测试，不一定就是好测试。它可能写了个恒真断言，或者测试根本没覆盖到核心逻辑。这个问题的本质是：流程保证“做了”，但不保证“做对了”。所以 review 不能省，尤其是 agent 自认为“已通过”的测试，要抽查断言质量。

最后说一点个人体会：Superpowers 适合的人群，不是“不想写代码的人”，而是“想把 AI 协作过程变得可控的人”。它不会让模型智商变高，但能让它的交付方式更接近一个靠谱的同事。如果你正在用 Codex CLI 或 Trae，又苦于每次都要在 prompt 里重复“先写测试、拆小步、给解释”这类要求，那很值得花一个下午把 Superpowers 装起来，体验一次“代理自己按流程走”的感觉。