最近在折腾 Codex CLI 的时候我总有一种感觉AI 写代码是挺快但质量完全看运气。让它写个函数它一次性给你甩出两百行没有测试、没有增量、没有中间验证出了 bug 你还得自己从头捋。后来在 GitHub 上刷到 superpowers 这个项目装上之后整个工作流完全变了——AI 不再是一口气写完整段代码的“快枪手”而是会先拆任务、先写测试、再小步实现、最后自己复盘。这篇就围绕 superpowers 的实际安装、核心技能和使用心得展开给所有想把 AI 编程助手调教成“靠谱队友”的朋友做个完整参考。先说清楚一个容易误解的点superpowers 不是一个模型也不是新的 CLI 工具而是一套精心设计的 markdown 技能包skills。它的原理是通过向 Codex CLI、Claude Code、Trae 这类编程代理注入结构化的指令文件让模型切换到更接近真实工程师的工作模式。通俗点说默认状态下 AI 是个“实习生长答模式”你问什么它答什么装上 superpowers 之后它更像一个遵循工程流程的开发者先规划、再测试、后实现、最后自检。这套东西对日常用 AI 写代码、做重构、搞调试的人来说价值非常直接。我这篇不会写得像官方文档那样干巴巴而是把安装步骤、核心技能拆解、实战流程、常见坑都揉在一起说重点放在“为什么这样装”“为什么这些技能有效”以及我实际踩过的坑。无论你是刚接触 Codex CLI 的新手还是已经在用 AI 编程助手的老手都能直接照着操作。1. 先搞清楚 superpowers 到底是什么1.1 它不是新模型而是一套“技能包”superpowers 本质上是一堆 markdown 文件和安装脚本的集合。你可以把它理解成给 AI 编程助手上的一门“职业培训课”。默认的 Codex CLI 或 Claude Code 虽然聪明但它缺乏工程实践的约束力。它们是纯生成式系统给定 prompt生成最可能的回答而不是“以正确的方式完成软件开发任务”。举个例子你让默认的 AI 写一个“解析 CSV 文件并统计每列空值”的脚本它大概率直接给你全部代码。这在简单场景下没问题但遇到涉及多个文件、需要和现有代码风格保持一致、或者需要保证正确性的任务时“直接生成”就成了灾难代码可能能用但不可维护、没有测试、不遵循项目结构。superpowers 的思路就是塞给 AI 一整套“行为准则”和“技能定义”。每个技能是一份 markdown 文件里面包含技能的触发条件、执行步骤、输出要求、以及大量来自真实工程实践的技巧。当 AI 加载这些技能后它在面对编程任务时会按照技能定义的方式来行动。比如“每当你开始一个编码任务你应该先创建一个 plan 文件列出步骤然后逐步执行每一步完成后都要运行测试”。这种思路没有任何黑科技纯粹是提示词工程和流程管理的胜利。但效果却非常显著因为它改变了 AI 的默认行为路径。1.2 为什么要用技能包来“驯化” AI 程序员我刚开始接触 Codex CLI 的时候最大的挫败感来源于“不可控”。明明是一个小需求AI 兴致来了直接重构了半个项目更常见的是让它改一个函数它把整个文件的逻辑都打乱重新生成一遍review 起来要命。后来我才意识到并不是模型不行而是我没有给它足够的约束。真实工程师写代码是有节奏的先理解需求再拆解任务然后写一个失败测试运行确认失败再实现运行确认通过重构再运行如此循环。superpowers 做的就是把这种节奏编写成技能文件把“怎么成为一个靠谱开发者”这件事显式地告诉模型。这也是我推荐所有人都试试 superpowers 的原因。它不挑模型只要你的 agent 支持读取自定义技能目录即可。装上之后你面对的是一个懂得“先写测试再写代码”的 AI而不是一个只会输出代码片段的生成器。2. 安装前的环境准备2.1 需要准备哪些基础环境在安装 superpowers 之前你至少需要保证下面几样东西是就绪的一个可以运行终端的环境Windows 下推荐使用 PowerShell 或 Windows TerminalmacOS/Linux 直接用系统终端。Git因为 superpowers 是从 GitHub 仓库拉下来的安装脚本也会用到 git 命令。Node.js 环境安装脚本大多是 Node 写的运行时会依赖 npm 或 npx。如果没有 Node装一个 LTS 版本就行。一个支持自定义技能目录的 AI 编程客户端常见的包括 Codex CLI、Claude Code以及新兴的 Trae 等。这些环境装好之后终端里分别输入git --version、node --version验证一下。版本太老的话建议先升级否则后续安装脚本可能跑不起来。2.2 获取项目文件获取 superpowers 项目文件的方式很简单直接从 GitHub 把仓库克隆到本地。以我之前实践为例git clone https://github.com/仓库作者/superpowers.git cd superpowers这里我故意没有写死仓库地址的完整内容因为项目作者和仓库地址可能会变动建议直接去 GitHub 搜索“superpowers”开源项目找到 star 数最高、最近还在维护的那一个。克隆下来之后仓库里一般会有一个 README 文件安装步骤都写在里面。我的建议是先把 README 通读一遍避免漏掉版本要求或特殊说明。这里补一句我踩过的坑不要直接下载 ZIP 再解压尽量用 git clone。原因有两个第一后续更新技能包时git pull最方便第二有些安装脚本会检查仓库状态解压包容易缺文件或者权限不对。2.3 一键安装脚本做了什么大多数情况下superpowers 仓库里会提供一个安装脚本运行方式一般是./install.sh或者npm run setup脚本运行的细节每个版本不太一样但核心动作基本一致先检测当前系统是否安装了 Codex CLI 或 Claude Code。找到对应的配置目录一般是~/.codex或~/.claude。在配置目录下创建skills文件夹并把仓库里的技能文件复制进去。在AGENTS.md或CLAUDE.md这类全局指令文件里追加一条“加载 skills 目录”的指令。整个过程一般不需要你手动改配置但你要注意脚本输出的日志。我见过不少人安装失败就是没看日志脚本因为缺少权限或找不到目录报错了自己还不知道。安装过程中如果出现“permission denied”之类的提示可以先试试给脚本加执行权限chmod x install.sh然后再运行。这个权限问题在 macOS/Windows WSL 环境里特别常见。3. 给不同客户端安装 superpowers3.1 Codex CLI 安装步骤如果你用的是 Codex CLI网上最热门的用法就是把 superpowers 的技能文件放进~/.codex/skills目录下。安装脚本会自动处理大部分工作但如果你想手动安装也可以这么做mkdir -p ~/.codex/skills cp -r superpowers/skills/* ~/.codex/skills/随后打开 Codex 的配置文件~/.codex/AGENTS.md把下面这行加进去skills 目录已加载请所有技能按需自动生效。严格来说语法不一定是这样但意图很明确让 Codex 在每次会话启动时读取该目录下的技能文件。装完之后启动 Codex CLI输入一个简单的任务比如“写一个计算斐波那契数列的函数要求先写测试”观察它的行为。如果它开始主动创建计划、写测试文件说明 superpowers 已经生效。这里有个非常重要的细节Codex CLI 有版本差异老版本可能读取的是~/.codex/instructions或config.toml。最靠谱的做法还是以项目 README 为准或者安装脚本检测到目录后会给出提示跟着提示走就行。3.2 Trae 等 IDE 类工具安装步骤Trae 作为新一代 AI IDE也支持自定义 skill。搜索热词里出现的“trae work cn 安装 superpowers skill”指的就是把同一套技能包安装到 Trae 环境里。流程和 Codex 类似但目录不同。以常见的 Trae 版本为例技能目录一般在用户目录下的.trae/skills。你可以这样操作mkdir -p ~/.trae/skills cp -r superpowers/skills/* ~/.trae/skills/然后启动 Trae在设置或规则配置里添加对 skill 目录的引用。不同版本界面位置不一样一般叫“自定义指令”“Agent 规则”或“技能管理”。把技能目录路径填进去或者直接把superpowers/skills里的关键文件内容粘贴到全局规则里。Trae 这类 IDE 的好处是你在写代码时能实时看到 AI 的行为变化安装是否成功也更容易感知。唯一麻烦的是版本更新快目录路径和设置入口变化频繁遇到找不到入口的情况直接问 Trae 的官方文档或用编辑器内的文件搜索功能搜一下“skills”关键词。3.3 验证是否安装成功不管装到哪个客户端安装完都要验证一下。我的验证方法很简单让 AI 完成一个需要“多步骤测试”的任务然后看它有没有表现出技能驱动的行为。比如我会输入请实现一个 Python 模块包含一个函数 is_valid_email(email)要求先做计划再写测试最后实现。运行测试并展示结果。正常情况下未安装 superpowers 的 Codex 会直接给代码安装成功的话它会先输出一个计划文件然后创建测试文件运行测试显示失败再实现代码再运行测试显示通过。这个过程清晰可见。另外可以检查技能目录下是否有 .md 文件ls ~/.codex/skills/应当看到若干 markdown 文件文件名通常包含 skills 的功能描述比如 plan.md、test-driven-development.md、debugging.md 等。4. 核心技能拆解这些超能力到底改了什么4.1 TDD 技能让 AI 先写测试再写代码superpowers 里最核心的一个技能就是 TDDTest-Driven Development也就是测试驱动开发。这个技能文件会明确要求 AI 在任何生产代码开发之前先编写一个失败的测试用例运行测试确认失败然后写最小实现再运行测试直到通过。这个习惯对 AI 来说意义很大。默认模型的训练目标是最小化预测误差它倾向于直接生成高概率正确的代码但在复杂系统中高概率正确不等于真的正确。TDD 给 AI 提供了一条“可验证”的路径每一步都有测试在把关。实际使用中TDD 技能带来的另一个好处是AI 不再一上来就写大段代码。因为要“先写测试”它必须先想清楚接口和行为这天然地引导它进行任务分析和设计。输出质量提升非常明显。4.2 增量开发技能别再一次性甩出 500 行默认状态下你让 AI 写一个完整功能它会尽可能一次性产出全部代码。这在面对小功能时没问题但当你需要它“在现有代码库中新增功能”时这种模式极度危险因为上下文太长模型容易忽略局部约束。superpowers 里的增量开发技能会强制 AI 把改动拆成小块。它要求在动手前先确认当前代码状态、梳理文件列表和调用关系然后每次只改一个模块改完立刻验证确认无误再进入下一步。从我实际体验来看这个技能在重构老项目时尤其好用。以前我让 AI 帮我加一个字段它可能会憋着劲把相关文件都重写一遍。现在它会先明确“这次改动只涉及 A 文件里的 B 函数”然后改一步验证一步review 的压力小了很多。4.3 调试与重构技能处理存量代码的关键superpowers 还内置了调试和重构相关的技能。调试技能的工作流一般是复现问题、获取堆栈和日志、提出假设、验证假设、定位根因、修复、回归测试。这套流程对 AI 来说其实就是一份“调试 SOP”它可以严格按步骤执行而不是一上来就盲猜哪里错了。重构技能的思路类似它会先分析现有代码的坏味道、建议保持行为不变的前提下进行结构调整然后小幅重构、每步运行测试。这解决了一个常见问题——AI 在重构时总喜欢顺手改掉不该改的逻辑。技能文件里会明确要求“只改变结构不改变行为”并且在重构结束后对比行为是否一致。4.4 规划与任务分解技能先想清楚再动手最后一个我认为价值很大的技能是规划。superpowers 要求 AI 在处理复杂任务时先创建一个 markdown 计划文件把任务拆解成步骤标注每一步的输入、输出和验证方式然后才允许开始写代码。这看起来多了一步实际上极大减少了那种“AI 写到一半跑偏”的问题。因为计划文件本身是在和用户对齐预期你可以在它动手前就纠正方向而不是等它生成完 500 行代码再返工。对我这种经常用 AI 做复杂需求的人来说这一步节省的时间比多写几个测试多得多。5. 实战演示一次完整的 superpowers 工作流5.1 第一步描述需求与上下文光说不练没用我实际演示一个场景。假设我想让 AI 在现有 Python 项目里增加一个 URL 解析工具函数并输出测试结果。没有 superpowers 时我的 prompt 可能是“写一个函数解析 URL”AI 会直接给我代码有 superpowers 时它启动后会先读计划、测试相关技能。我的输入是当前项目是一个小型爬虫工具入口在 src/url_utils.py测试在 tests/ 目录。请新增一个 normalize_url(url) 函数要求先计划、先测试再实现。注意我补充了项目结构信息和明确要求这会帮助 superpowers 的技能更好被触发。5.2 第二步AI 进入计划阶段随后 AI 会输出一份计划类似这样计划 1. 阅读 src/url_utils.py了解现有代码风格。 2. 阅读 tests/ 目录确认测试框架。 3. 编写测试用例normalize_url 应处理默认协议、去掉末尾斜杠、保留查询参数。 4. 运行测试确认失败。 5. 实现函数。 6. 运行测试确认通过。 7. 检查是否有 lint 或类型错误。这一步就是规划技能在起作用。它不会先写代码而是先告诉你它准备怎么做。这时候你可以纠正计划比如“不需要去掉查询参数”它就会在动手前调整方向。5.3 第三步TDD 循环执行计划确认后AI 开始在测试文件里追加测试代码def test_normalize_url_default_scheme(): assert normalize_url(example.com/path) https://example.com/path然后运行测试由于函数还没实现自然报错。它立刻执行最小实现def normalize_url(url: str) - str: if :// not in url: url https:// url return url.rstrip(/)再跑测试测试通过之后它还会补几个边界用例。整个过程看起来就像两个程序员结对编程一个负责写测试一个负责实现而且节奏非常稳。5.4 第四步复盘与提交功能完成后superpowers 中的某些技能还会驱动 AI 进行自我复盘。它会回顾刚才的实现检查是否有重复代码、是否需要类型标注、测试覆盖是否足够。如果它发现某些边缘情况没处理会主动提出修改建议。最后它可能还会提示你使用git diff查看改动、运行完整测试套件、再考虑提交。这种流程在很多团队里都是“标准动作”但默认状态的 AI 几乎不会主动做。装完 superpowers 后AI 在这些流程上的表现提升了不止一个档次。6. 常见问题与排查技巧6.1 技能没有生效AI 还是老样子这是最常遇到的问题。你明明把技能文件放进去了但 AI 行为没有任何变化。原因通常是配置文件里没有正确引用 skills 目录。就像是你把新员工的工牌做好了但没带他进办公室他自然不知道自己的岗位职责。解决办法是回到配置文件AGENTS.md或CLAUDE.md确认有没有加载 skills 目录的指令。另一个原因可能是技能文件里的触发条件没被当前任务满足。superpowers 的技能通常会在开头写明“when to use”如果任务描述太模糊AI 可能会跳过技能。此时可以把需求说得更结构化或者直接在 prompt 里点明“请遵循 test-driven-development 技能”。6.2 命令找不到或安装脚本报错如果你运行./install.sh时报错什么“command not found”大概率是脚本权限问题或依赖缺失。检查两件事一是是否给脚本加了执行权限二是 Node/npm 是否在 PATH 里。在 Windows 环境下建议使用 WSL 或 Git Bash 来运行 Linux 风格的脚本直接双击运行大概率会失败。如果脚本报错说找不到~/.codex或~/.claude目录说明你的客户端还没初始化过。先手动运行一次 Codex CLI 或者 Claude Code 生成配置目录再重试安装脚本。6.3 上下文过长模型招架不住superpowers 的缺点之一是它会增加 token 消耗。每个技能文件内容都不短当多个技能同时被加载进上下文时留给实际任务的 token 空间变小模型有时候会“忘记”后面的步骤。表现为开头还在执行 TDD后面写着写着就变成直接生成代码了。我的解决方法是按需裁剪技能文件。不要把仓库里所有技能都塞进去只保留你日常最需要的三四个比如 plan、test-driven-development、incremental-development。这样上下文负担小技能执行也更稳定。6.4 与其他配置冲突了怎么办如果你之前已经有一套自定义指令比如在CLAUDE.md里写了“永远直接输出答案”这个指令可能会和 superpowers 的“先计划再执行”产生冲突。模型面对冲突指令时未必会报错但行为会变得不可预测。排查方法很简单打开你的全局配置文件和技能文件把明显冲突的规则删掉或改掉。优先保留 superpowers 的流程性指令因为它是经过设计的完整体系零散指令很难和它完美兼容。保留少量你自己的风格要求是没问题的但不要留那种会改变任务执行路径的规则。7. 一些使用心得和边界7.1 什么时候该用什么时候不该用对我来说superpowers 最适合的场景是重构、调试、需要在现有代码库里增加功能的场景。这类任务对流程的要求很高有了技能约束AI 出错率明显下降。但如果是纯探索性的问题比如“Python 3.13 的 match 语句怎么和模式匹配配合使用”这种场景就没必要让技能介入直接问就好。技能包不是越多越好它是给需要稳定质量的开发工作准备的不是给对话聊天准备的。根据任务场景灵活切换普通模式和 superpowers 模式才是正确的用法。7.2 如何根据自己的需求裁剪技能包官方仓库提供的技能往往比较全但每个人的工作流不一样。比如我自己主要写 Python 后端对前端调试技能的需求很低我就会把那些技能文件移出目录只保留 plan、TDD、增量开发、调试等几个核心技能。做法很简单在 skills 目录里删除不需要的 markdown 文件就行。但注意不要改动文件里的格式和特殊标记否则可能导致技能无法被正确识别。建议保留一份原始仓库备份随时可以恢复。7.3 最后的小建议如果你打算长期使用我强烈建议把 superpowers 仓库 clone 到你常用的工作目录而不是下载一次解压就完事。这样每次上游更新你可以git pull拉最新版技能再同步到对应的 skills 目录始终保持和社区同步。我自己就是这样维护的基本每两周更新一次技能文件里的经验技巧确实在持续改善。还有一个小技巧安装完成后可以把“要求 AI 先创建计划文件”这个习惯固化成你自己的默认 prompt 后缀。比如在每次复杂任务描述结尾加上一句“先做计划再写测试最后实现”。即使某一天你切换了客户端、技能没来得及配置这个习惯也会让你和 AI 的协作质量维持在一个比较高的水平。