最近我把自己的 Codex CLI 从“裸奔”状态升级成了一套带 superpowers 的配置，说实话，效果比我预期猛不少。以前我用命令行 AI 编程助手，最烦的就是它做着做着就断片，要么忘了前面改了什么，要么在一个小问题上反复横跳，最后还得我自己把代码拉回来修。装上 superpowers 这套 GitHub 上的开源技能包之后，Codex 像是突然有了“项目思维”，会先拆任务、再动手改、改完还知道自查，整个流程终于像是一个靠谱的结对程序员，而不只是一个能生成片段的代码提示器。
这篇文章我不打算念官方 README，而是把我在实际项目中安装、配置、调用 superpowers 的过程完整记录下来，包括哪些技能最常用、怎么和 Codex CLI 配合、实战里会遇到哪些坑、什么时候该信它、什么时候必须拉闸。如果你正在用 Codex CLI、Trae 这类 AI 编程工具，又觉得默认行为太“愣头青”，那这套东西值得你花一个下午折腾一下。
1. 为什么 AI 编程助手需要“超能力”技能包
1.1 原生 AI 助手的三大短板
先说结论：现在的命令行 AI 编程助手，本质是一个“很聪明但记性不好”的实习生。你用自然语言给它一个任务，它能写出一段像模像样的代码，但一旦任务跨度拉长，问题就暴露出来了。
第一个短板是上下文窗口的物理限制。模型一次性能看到的内容是有限的，几千行代码塞进去之后，前面的设计意图往往会丢失。你让 AI 改一个跨三个文件的功能，它经常只顾着最后一个文件，完全忘了前面约定好的接口名和数据结构。
第二个短板是任务规划能力弱。给一句“帮我实现登录功能”，原生行为往往是直接在一个文件里开干，不会先问你用 JWT 还是 Session，也不会考虑要不要写测试、要不要更新文档。这就像让实习生去办一件事，他拿到手就冲，结果方向全错。
第三个短板是缺少自检闭环。很多 AI 改完代码就觉得自己完成了，不会主动跑测试、不会检查语法、不会确认是否影响了其他调用方。在命令行环境里，这个问题尤其明显，因为缺少 IDE 的实时校验，AI 容易把错误代码生产得理直气壮。
Superpowers 这个项目想解决的就是这三件事：把任务拆细、把上下文管好、把执行和审查分开。
1.2 技能包的工作原理
听到“技能包”这个词，可能有人觉得是给 AI 灌了一堆“咒语”。实际上它的本质是“带状态的提示词模板加执行流程”。通俗一点说，就是给 AI 准备了一整套标准作业流程的说明书，遇到什么类型的任务，就让它按照对应说明书的分步操作去执行。
我自己理解下来，superpowers 和普通自定义 system prompt 最大的区别是：它不是一段固定的指令，而是一组可以被动态调用、互相组合的“工作流模块”。比如plan技能负责把大任务拆成小任务，implement技能负责按计划逐项修改，review技能负责回头检查代码质量。每个技能都有自己的输入输出格式，AI 在执行不同阶段时会先切换对应技能，再开始干活。
这里面有一个很聪明的设计：通过技能隔离上下文。当 AI 在做research阶段时，它不需要一次性把所有代码变更都塞进上下文，只需要保存一份精简的任务描述；等真正进入implement阶段，再加载当前需要修改的具体文件。这相当于给 AI 装了一个外置工作记忆，不让它在主对话里背着一座仓库乱跑。
这种思路和团队管理很像。项目经理不会记住每一行代码，但他知道当前该叫哪个工程师、该分配什么任务。Superpowers 就是在给 AI 编程助手做这一层“管理能力”补充。
2. 安装前的准备与整体思路
2.1 需要准备什么
如果你打算跟我一样在本地折腾，先把环境确认好。我当前的运行环境是 macOS + Node.js 20 + 最新版 Codex CLI，这套组合跑 superpowers 很稳。Windows 和 Linux 也能用，但后面会说一些平台差异带来的坑。
具体来说，你需要准备这几样：
- Node.js 18 或更高版本，建议直接用 20 LTS，因为技能脚本会依赖一些比较新的标准库
- Git 命令行工具
- 一个能正常工作的 Codex CLI 环境，已经登录并能在项目中执行基础会话
- 如果用的是 Trae，需要桌面版支持 Agent/Skill 模式，不同版本入口略有差异
在动手之前，我建议你先跑一个最小验证：随便进入一个项目目录，执行codex，在会话里让它写一个 hello world 脚本。这样能确认 CLI 网络、鉴权、模型调用都正常，避免后面出了问题分不清是 superpowers 的问题还是基础环境的问题。
2.2 用 Git 安装 Superpowers
Superpowers 的安装方式和大多数开源 CLI 工具一样，核心就两步：把仓库拉到本地，再执行安装脚本。
我用的命令是这样的：
git clone https://github.com/obra/superpowers.git ~/.superpowers cd ~/.superpowers ./install.shinstall.sh脚本会检查本地是否有 Codex CLI，然后把技能目录复制到 Codex 运行时能找到的位置，同时写入一些基础配置。如果你用的版本和我不同，命令可能略有出入，建议以仓库 README 为准。我的经验是，安装完最好把终端重启一下，让新配置生效。
补充一点：我在执行脚本时遇到过权限报错，如果提示Permission denied，先给脚本加执行权限：
chmod +x install.sh ./install.sh安装完成之后，可以看一眼技能目录里有什么，正常情况下应该有一堆描述各类工作流的 Markdown 文件。这些文件就是 superpowers 给 AI 准备的“说明书”。
2.3 在 Codex CLI 中挂载技能
安装脚本通常会把路径配置好，但我还是建议手动理解一下挂载方式，方便排查问题。Codex CLI 在启动时会读取项目目录下或用户目录下的AGENTS.md文件，这个文件用来描述当前环境的规则和可用能力。Superpowers 做的事情，本质上是把这个文件里加入一段“技能索引”，告诉 AI 什么时候应该去哪个技能文件里查流程。
如果你需要手动配置，可以在~/.codex/AGENTS.md中加入类似这样的内容：
当用户请求的任务比较复杂时，先查看 ~/.superpowers/skills/ 目录下的技能说明。 根据任务类型选择使用 plan、research、implement、review 等技能。这个配置不是官方强制的规范，但它能显著提高 AI 调用技能的主动性。因为模型如果不知道有这套技能存在，它就算读过一堆文件也不知道什么时候该用。你需要在系统提示里专门给它一个触发条件。
在 Trae 里思路类似，一般是把技能文件放入项目中.trae/skills或用户目录下的技能配置位置，然后在 Agent 设置里启用外部技能。不同版本界面差异比较大，我建议按你使用的版本官方文档为准，核心原理仍然是“让 AI 知道技能文件在哪 + 什么场景用哪个技能”。
3. 核心技能模块精讲
3.1 技能总览表
安装好之后，我第一反应是看看 superpowers 到底提供了哪些技能。我把一些我实际用过的技能整理成了表格，方便你快速知道每个技能在什么场景下用：
| 技能名称 | 核心作用 | 典型使用场景 |
|---|---|---|
| plan | 把大任务拆解为可执行步骤，输出任务清单 | 新功能开发、重构前设计 |
| research | 在代码库里搜索并汇总相关事实 | 搞清现有实现、定位 bug 根因 |
| implement | 按既定计划修改文件，逐步落实任务 | 功能开发、修 bug、小范围改动 |
| review | 对已改代码做自查，发现问题清单 | 提交前检查、代码审查辅助 |
| commit | 生成规范化的提交信息和差异摘要 | git 提交前的信息整理 |
| fix | 针对报错和测试失败做定向修复 | 测试挂了、编译不过 |
| trace | 跟踪一个变量或调用链在代码中的流转 | 排查跨文件逻辑问题 |
| wrap-up | 对已完成工作做总结，生成变更说明 | 写 PR 描述、工作汇报 |
这张表不需要背，关键是建立印象：superpowers 提供的不是某个具体业务功能，而是一整套“干活流程”。你在会话里触发哪个技能，AI 就会切换到对应的工作状态。
3.2 高频技能用法演示
我实际用得最多的三个技能是plan、research和implement。演示一下最基础的调用方式。在 Codex CLI 会话中，你可以直接输入“使用 plan 技能帮我分析……”这样的自然语言，也可以用@plan的格式：
@plan 我想给当前项目增加一个用户登录接口，使用 JWT 认证，请先输出实施计划AI 会先读取 plan 技能文件的说明，然后按照格式输出一个任务清单。它通常包含背景分析、涉及文件、改动点、验证方式。这一步最大的价值是把模糊需求“结构化”，让你在动手前就能发现问题。比如它可能会在计划里写“需要在requirements.txt中新增 pyjwt 依赖”，如果你不打算引入第三方库，这时候提出来修改成本比后面返工低得多。
research技能的用法类似。当我对一个旧项目不熟时，会这样触发：
@research 我需要知道当前项目里用户认证是怎么实现的，相关的表结构和中间件有哪些AI 会主动去翻代码、读配置，最后返回一份结构化摘要。它和普通问答的区别在于，research 技能会带着“我要找什么”的目标去搜索，而不是漫无目的地生成一段猜测。
implement技能是真正负责改代码的。我通常在确认完 plan 之后执行：
@implement 按照刚才的计划开始实现登录接口，每改完一个文件都做一次 git diff 摘要它会一个文件一个文件地推进，而不是一次性把全部代码吐出来，这样每一步你都能随时打断。
3.3 技能叠加用法
单个技能好用，真正爽的是把多个技能串起来。比如我处理一个不太熟的功能需求时，会一口气说：
先 @research 摸清当前项目的认证逻辑，再 @plan 设计登录接口方案，最后 @implement 实现并跑通测试这样 AI 会先进入调研状态，把事实摸清；然后进入规划状态，输出设计；最后进入执行状态，按方案落地。整个过程像流水线一样，每次只打开一个上下文窗口，但最终输出是连续且一致的任务。
需要提醒的是，技能叠加时最好分阶段确认。不要真的一句话把所有事丢给它，因为research的结果会直接影响plan的方向，如果你不中途看一眼，AI 可能会按自己的理解跑偏。我的习惯是让它先做 research，输出摘要后我快速过一遍，点个头再进入下一步。
4. 实战：用 Superpowers 完成一个登录 API
4.1 任务背景
光说概念没用，我拿一个最近实际的例子讲。我手头有个 FastAPI 项目，当前没有任何用户认证功能。我的需求是：新增一个POST /login接口，使用 JWT 返回 token，同时加上单元测试和 API 文档说明。
这是很典型的一个中量级开发任务，最适合用来验证 superpowers 能不能从“单点生成”升级成“全流程交付”。
4.2 规划阶段实操
我先在项目根目录启动 Codex CLI，然后输入：
@plan 给项目新增一个登录接口。当前项目使用 FastAPI，数据库用 SQLite，还没有用户表。请先规划需要创建哪些文件、修改哪些文件，以及测试方案。AI 返回的计划大致分成四步：新建用户模型和数据库迁移、新增密码哈希工具函数、实现登录路由和 JWT 签发逻辑、补充单元测试。计划里还注明了每个步骤的验收标准，比如“调用 /login 时返回 200 且包含 access_token”。
我看了下计划，发现它把密码哈希方案默认选成了 pbkdf2，而我想用 bcrypt。于是我在确认前追加了一句：“密码哈希改用 bcrypt。”AI 自动更新了计划里的依赖和实现细节。这个阶段的人工介入成本很低，但效果很好，因为方向在写代码之前就被纠正了。
4.3 执行阶段与人工介入点
确认计划之后，我输入：
@implement 按计划开始实现，注意每完成一个文件后输出一次 git diff --statAI 开始逐个创建文件并修改现有路由。在实现过程中我也不是当甩手掌柜，而是盯着它的每一步输出。有一个关键介入点是在它创建用户表时，我的表结构其实希望使用username作为唯一键，但 AI 默认用了email。我看到它输出的建表代码后，直接打断说：“我们用 username 作为登录账号，不需要 email 字段。”
这个修改如果用传统方式，可能要到写完接口甚至跑测试时才发现，但因为有逐文件输出和 diff 摘要，我在第一步就能看出来，成本非常低。superpowers 并没有让 AI 变得万能，而是让 AI 的每一步动作都更透明，方便人及时纠偏。
4.4 结果验收
所有文件改完后，我用三件事验收：
git diff --stat pytest tests/ git diff --name-only添加和修改的文件数量符合计划预期，测试全部通过。我再跑了一下@review技能，让它检查当前未提交的代码变更：
@review 请检查未提交的登录接口代码，重点看安全和边界情况AI 给出了几个建议，比如 JWT 过期时间设置太短、缺少用户名不存在的统一错误信息。我采纳了能改的部分，让它继续修改，最后再跑一次测试确认没有回归。
整体感受是：从需求到可提交的代码，中间的人力干预主要集中在方向决策上，而不是重复劳动。我不用自己手写模板代码，也不用担心 AI 漏掉测试，因为这些流程被技能拆成了固定的“关卡”。
5. 常见问题和踩坑记录
5.1 问题速查表
用了一个多月，我把新手容易遇到的问题整理成一张表：
| 问题现象 | 常见原因 | 解决方法 |
|---|---|---|
| 输入 @plan 没反应 | 技能文件路径没有正确挂载 | 检查 AGENTS.md 里的技能索引路径 |
| 技能调用了但回答很敷衍 | 模型没理解技能格式要求 | 重新声明“严格按照技能文件步骤执行” |
| 上下文还是溢出 | 单次任务太大，没有拆分阶段 | 强制先 @plan，再分步 implement |
| AI 改了无关文件 | 任务描述太宽泛，缺乏范围约束 | 在计划里明确涉及文件和不允许改的文件 |
| 测试一直跑不过 | AI 自测时没有真正执行命令 | 指定让它运行 pytest 并读取输出 |
| Windows 下技能文件识别失败 | 路径反斜杠问题 | 统一用绝对路径，并在 AGENTS.md 里使用正斜杠 |
这张表是我自己排查时最常用的一组对照，很多问题并不是 superpowers 本身坏了，而是配置细节没对上。
5.2 我踩过的三个坑
第一个坑是安装脚本没加执行权限。第一次执行./install.sh，系统直接提示 Permission denied，我一紧张以为是脚本写得有问题，后来才发现就是最简单的权限问题。在多数 Linux 和 macOS 环境下，从 GitHub 克隆下来的文件默认没有执行权限，必须先chmod +x。
第二个坑是 Windows 路径分隔符引起的。我在一台 Windows 机器上配置时，AGENTS.md 里写了~\superpowers\skills\plan.md这样的路径，AI 始终读不到技能文件。后来把路径改成正斜杠的绝对路径，问题立刻解决。跨平台工具在这方面依旧很敏感，不要想当然。
第三个坑是过度信任 AI 的自我验证。有一次它告诉我测试全过，我后来手动执行pytest才发现它根本没跑，只是根据代码推断应该能过。从那以后我不管 AI 怎么说，验收阶段一定自己执行一遍命令。这不是 superpowers 的弱点，而是所有 AI 编程助手都需要有的心理预设：它可以辅助你，但最终验证必须由你完成。
5.3 使用边界
Superpowers 适合的场景，我总结下来有三类：一是重构老代码，可以用 research 先摸清结构再动手；二是补测试和文档，这类重复性很强且需要流程化执行的活；三是明确的 bug 修复，只要你能把问题触发条件描述清楚，AI 按 fix 流程通常能快速定位。
不适合的场景也很明确：第一是高风险的架构决策，比如重新设计数据模型、服务拆分，这些需要大量人的判断，不能全靠 AI；第二是直接在生产环境上改代码，即使再强的技能也没法保证不出错；第三是涉及大量历史遗留问题的代码库，AI 很容易被旧的坏模式带偏。
我的原则是：开一个独立分支，所有 AI 改动先提交到临时 commit，一旦发现方向不对就 reset 回退，保住安全网再继续试。
6. 一些个人实践心得
6.1 效果对比
装上 superpowers 前后，最直观的区别是 AI 的“连续性”变强了。以前裸用 Codex CLI，一个复杂任务经常执行到一半就忘了初衷，需要我反复提醒“我们最初的需求是什么”。现在通过 plan 技能把目标固化成文本，implement 阶段每次都回看计划，AI 很少再跑偏。
另一个明显提升是代码质量。review 技能强制它在提交前做一轮自查，很多低级错误在这个阶段就被拦住了。这个机制很像给 AI 装了一个“提交门禁”，没有检查就不允许宣布完成。长期用下来，代码 commit 的平均质量比我手动写的时候还稳定。
6.2 更进一步：写一个自己的技能
最后分享一个小技巧：superpowers 并不限制你只能用内置技能，你完全可以按照同样的格式写一个自定义技能文件，放到技能目录里。
比如我写了一个“commit-style”技能，专门用来规范提交信息。技能文件内容很简单，告诉 AI 必须按照type(scope): subject的格式组织 commit message，并且 subject 保持动词开头。这样我在会话里触发@commit-style 帮我提交本次修改，它就会按我的团队规范来生成提交信息，省去了我每次手动改写的麻烦。
根据我的经验，自定义技能的价值不在“新增知识”，而在于“固化流程”。任何一个你反复执行、又有明确步骤的任务，都值得固化成技能。今天你花半小时写一个技能文件，明天可能就省下一整周重复劳作的时间。这就是 superpowers 带给我最大的启发：让 AI 变强，不是给它更多知识，而是给它更清晰的做事方法。
