最近好多人在聊 superpowers 这个开源项目。我第一次看到这个名字第一反应是又一个花里胡哨的 AI 插件直到在自己的项目里完整跑完一遍才意识到这东西是真的把 AI 编程助手的上限拉高了一大截。简单来说superpowers 是一套给 Codex CLI 这类终端型 AI 编码助手设计的技能增强层它通过预置的 skills 规范让 AI 不再直接甩代码而是先拆任务、先写规格、先写测试再动手实现并且自己调用命令行工具跑测试验证。如果你受够了 AI 补代码时那种看起来能用、跑起来全是坑的状态这篇文章应该能帮你少走不少弯路。我会把安装、配置、典型工作流以及踩过的坑全写出来看完基本可以直接开跑。1. 先搞清楚 superpowers 到底是什么解决什么问题1.1 终端型 AI 编码助手的通病之前在本地用 Codex CLI最深的感受是它像一个特别敢写但不太靠谱的实习生。你让它写一个用户登录模块它啪一下给你输出两百行代码乍一看结构完整、注释齐全仔细一查全是问题——依赖没装、错误处理落在了奇怪的位置、没有测试、连项目里实际用的框架版本都没对上。这时候你就得当人肉编译器和代码审查员来回喂上下文、不断纠正一个下午就这么没了。很多人的第一反应是多给点 prompt 不就行了但实际试下来问题不在 prompt 不够长而是缺少一个强制性的执行框架。AI 并不知道你的项目里什么叫完成什么叫可验收。它默认认为自己输出代码就算完成任务剩下的验证责任全部甩给你。这种模式在小脚本、一次性实验里还行一旦到了真实交付场景就会变成灾难。1.2 superpowers 的解法用规范流程给 AI 上纪律superpowers 的设计目标很直接把让 AI 干活这件事从输出代码升级成交付可验证的结果。它实现这个目标的方法是给 Codex CLI 预置一套写在 Markdown 文件里的 skills——你可以把 skills 理解成AI 的行为工作流手册。每个 skill 定义了一类任务该怎么拆解、怎么落笔、怎么验证AI 在执行时会按手册一步步来而不是自由发挥。我印象最深的是它的 TDD 工作流。以前我让 AI写一个函数并且保证正确它大概率直接甩实现装上 superpowers 之后AI 会先询问需求边界、写规格说明、再生成失败的测试用例最后才去写让它通过的实现代码。等于 AI 自己给自己定了验收标准然后亲手把标准跑通。听起来绕但对经常被 AI 代码坑过的人来说这个流程反而才是真正省时间的部分。1.3 对谁最有用对谁不划算如果你属于下面这几类人superpowers 值得花一个晚上认真试试个人开发者维护多个小项目没精力给每个仓库写详细开发文档习惯用 Codex CLI 或终端编码助手写脚本、做原型但每次都花大量时间在验证和返工上以及对 TDD 有认同感、又不想自己手写大部分测试的人。它带来的收益本质上是用 AI 的自验证换你的时间。坦率说它不适合那种就想要 AI 一分钟给我补个函数的轻量场景。打开一个文件、写十行代码、马上要结果直接开普通对话就完事了硬拉一套完整的 skills 反而显得重。把工具用在该用的场景里才是聪明用法。2. 从零到能跑安装与初始化完整步骤2.1 前置依赖准备动手之前先把依赖理清楚。superpowers 本身是基于 Node.js 的工具官方推荐 Node.js 18 或更高版本终端编码代理部分我用的 Codex CLI通过 npm 全局安装即可。另外你需要一个可用的模型服务配置——本文假设你已经能正常使用 Codex CLI 的基础功能。如果连 codex 都没跑通过建议先回到它的官方 README 把基础打通再来看 superpowers否则后面所有问题会混在一起很难排查。还有一个小建议准备一个干净的空目录用来做实验。superpowers 的初始化会在当前目录生成一些配置和 skill 文件放到现成项目里倒也能用但对第一次上手的人来说先在空目录里把流程跑通再迁移到真实项目心里会更有底。2.2 安装步骤安装流程不复杂我按实践顺序列一下完整步骤。先把仓库 clone 到本地git clone superpowers 官方仓库地址 cd superpowers仓库地址以你搜索到的最新官方地址为准这个项目迭代很快不同 fork 版本的功能会有差异。进入目录后安装依赖npm install依赖装好后执行初始化命令node superpowers.js init初始化脚本会在你的用户目录下创建核心配置并把 skills 目录拷到项目或用户目录里。之后把 superpowers 的 bin 目录加入 PATH方便后续直接用 superpowers 命令。当前 shell 临时生效可以这样export PATH$PWD/bin:$PATH想永久生效就把这行写入 ~/.zshrc 或 ~/.bashrc。提示如果你 clone 的不是官方主线版本或者装完后 README 里的命令和网上教程对不上一律以仓库自带 README 为准。这类工具的命令名变更很常见我刚装的那版和现在线上文档里的入口命令都不一样。2.3 模型与基础配置安装完成后需要配置模型接口密钥。Codex CLI 本身已经有自己的配置机制superpowers 一般会复用你不用重复填。但有几个模型相关参数值得注意比如模型名称、温度、单次执行超时时间。保守的做法是全部保持默认先跑通一条最小任务再根据实际表现逐步调整。初始化完毕后可以先用一条命令验证环境是否正常superpowers skill list如果能看到一串 skill 名字说明安装成功。看不到就检查 PATH 上一步的配置以及初始化时有没有报错。我第一次跑这个命令就遇到了 command not found后来才发现是 bin 目录没有正确加入 PATH。2.4 初始化后值得花五分钟做的事初始化完成后你会看到用户目录下多了一个 superpowers 配置目录里面最核心的是 skills 子目录和 config 文件。skills 目录里全是 Markdown 文件文件名基本就是 skill 名config 文件控制模型默认行为。我建议你把 skills 目录里的文件挨个扫一遍因为你对这些工作流手册的理解越深后面写 prompt 就越精准。很多人在初始化后纠结要不要手动改 config我的建议是第一个星期什么都别改就按默认跑。等你熟悉了工作流的节奏再考虑调温度、上下文长度这些参数不然你很难判断行为差异到底来自配置调整还是来自 prompt 的变化。3. 核心工作流实操AI 自己写测试、自己验证3.1 实战示例做一个命令行待办事项管理器装好不是终点真正有价值的是跑通一条完整工作流。我挑一个很小的示例说明整个过程。假设我在空目录里想用 Codex CLI 做一个待办事项管理器的第一个版本需求是支持 add 一条待办并且能打印列表。没有 superpowers 的时候我大概会直接输入写一个待办管理器支持添加和列表然后看它自由发挥。现在我会这样发起会话codex 用 superpowers 的 skill 体系来工作为当前目录添加一个 CLI 待办管理器先规划再按 TDD 流程实现 add 和 list 两个命令。接下来 AI 的行为会明显不同。它不会立刻写代码而是先调用规划 skill输出一份简短的实施计划接着创建 spec 目录写下add 命令应该符合什么行为、list 命令应该符合什么行为的规格然后生成测试文件此时测试是失败的再用实现类 skill 写业务代码最后在终端里执行测试命令把 stdout 和退出码反馈给我。整个过程中我只需要在几个关键节点确认方向没了之前那种无限来回修改的疲惫感。3.2 日常最常用的几条命令日常用得比较多的是这几条。superpowers skill list查看当前可用 skill判断 AI 是否具备某类能力。superpowers skill add往项目里增加新 skill比如代码评审依赖升级。如果你有重复性任务可以把这些命令直接组合进自己的脚本或 CI 流程里。我还有一个习惯在每次大的对话开始时先让 AI 用 plan skill 输出实施步骤由我批准后再执行。它相当于给 AI 的工作加了一道审批闸门防止它埋头干错方向。这里想强调一点superpowers 的价值并不在于多了几条命令而是改变了人和 AI 协作的时序。以前是人先下命令、AI 执行、人验收现在是 AI 先给方案、人确认、AI 一步一步执行并自测。这个顺序的调整才是真正省时间的根本原因。3.3 Java 项目里的 superpowers 怎么用热词里有 superpowers java说明很多人在关注 Java 场景。我在一个基于 Spring Boot 的小项目里试过核心流程和 Node 项目一致但有三个 Java 特有的坑提前知道可以省不少事。第一是构建工具感知。AI 在 Maven 项目里如果没有被明确告知很可能生成 Gradle 的目录结构。解决方法是让 AI 先读项目的 pom.xml并且在需求里直接写清楚这个项目是 Maven使用 JUnit 5测试用 mvn test 执行。第二是测试类路径问题。JUnit 测试最常见的失败原因是包名和目录不一致或者测试类没有放在 src/test/java 对应目录下。superpowers 的 TDD skill 会强制 AI 先列出项目结构再动笔能很大程度减少这类问题但你还是应该在项目初始化时把目录约定写清楚。第三是依赖下载和构建耗时。Java 项目首次构建往往很慢AI 执行 mvn test 时可能因为超时而误判构建失败。我的建议是给 AI 设置更长的执行超时参数并且在需求中写明首次构建允许 3-5 分钟避免它反复重试同一个几乎成功的命令。实测下来的体感是Java 项目的收益甚至比 Node 项目更明显因为编译期和测试期能暴露很多 AI 代码的隐藏问题而 superpowers 正好把AI 自己编译自己测试做成了默认流程。3.4 进阶把多个 skill 串成一条流水线superpowers 的进阶玩法是把多个 skill 串联起来。比如开发一个新功能模块时可以让 AI 先执行 plan skill再执行 spec skill再执行 tdd skill。你可以在 prompt 里按顺序点名也可以把整条流程写进一个自定义 skill 定义文件以后一条命令就触发。我自己写了一个叫 weekly-report 的 skill专门让 AI 读取 git log、按日期分组、提炼本周改动并生成汇报文档。这个 skill 我用了好几周稳定可靠。同样的思路可以复用到代码评审、CHANGELOG 生成、依赖升级等重复劳动上。你需要的不是更多 prompt而是把流程沉淀下来变成以后可以直接调用的固定资产。4. 高概率踩坑清单实用排查速查表4.1 初始化与权限类问题第一次初始化时最容易遇到两类问题命令找不到和权限不足。command not found 一般是 PATH 没配好重新检查 export 行即可如果是执行脚本时提示 EACCES需要先确认文件是否有执行权限chmod x bin/superpowers另外如果你之前用 npm 全局安装过旧版本要注意新旧命令是否冲突可以用which superpowers查一下当前命中的是哪个路径。很多时候你以为自己在跑新版本实际 bash 调用的还是旧版这种问题最迷惑人。4.2 网络与依赖安装问题npm install 卡住很常见尤其在网络环境波动比较大的时候。我的排查顺序是先确认 npm 仓库源是否可达再看本地是否有损坏的缓存必要时把 registry 临时切到常见的公共镜像装完再切回来。这里不需要任何额外网络操作纯粹是 npm 源本身的问题。还有一个容易忽略的点如果你在代理环境里工作记得先确认 npm 的配置文件和系统环境变量是否一致否则会出现命令行能连通、npm 一直超时的诡异情况。4.3 模型行为异常不按流程走怎么办有些时候模型可能无视 TDD skill 直接输出实现代码。我遇到这种情况先检查两件事一是当前对话是否真的加载了对应 skill让 AI 用 skill list 自报一下二是看 prompt 里的指令是否足够明确。AI 有很强的赶紧完成任务倾向如果你的表述是优化一下某个功能而没强调流程它会走捷径。最有效的纠正方式不是让它重新写而是让它解释刚才违反了哪一条 skill 规则、下一步应该怎么做。通常一轮纠偏之后就能回到正轨。这种让 AI 自述违规的方法比反复说不行按流程来好使得多。4.4 上下文过长与记忆丢失superpowers 的 skills 本质上会占用不少上下文因为 AI 要把工作流手册读进来。长任务跑到一半可能会看到 token 超限或者它突然忘了之前的决定。这时的解决方案是让 AI 定期做状态整理把已完成步骤、未完成步骤和验收标准写到一个 progress 文档里下次开启新会话时直接引用。这个技巧来自社区试过之后长任务的稳定性提升非常明显。下面把高频问题整理成一张速查表方便日后对照排查。现象大概率原因处理办法command not foundPATH 未配置或配置失效重新 export PATH确认 bin 目录存在EACCES 权限不足脚本没有执行权限chmod x 对应文件skill list 为空skills 目录未正确拷贝重新执行 init检查用户目录配置模型直接输出代码未加载技能或指令不够明确检查当前 skill明确要求按 TDD 流程执行npm install 卡死源不稳定 / 缓存损坏切换公共镜像源清理 npm 缓存后重试token 超限上下文占用过大压缩对话上下文或写 progress 文档mvn test 超时Java 项目首次构建过慢调长执行超时参数写明允许构建时长5. 我自己的使用心得怎么用最舒服、还能怎么扩展5.1 最佳使用节奏按我这段时间的体验superpowers 最适合的运行粒度是边界明确的中小型任务加一个接口、修一个 bug、重构一个模块。任务越明确流程优势越明显。反过来如果需求本身模糊得像优化一下项目整体质量AI 会陷入无休止的规划这时候你需要在最开始就把范围切小甚至拆成多个独立会话。另外我强烈建议别把 superpowers 当成无人值守工具。它更适合异步协作——你下发任务去喝杯水或者忙点别的回来验收中间产物。但又不能完全放手不管至少在规格和测试生成之后花两分钟读一读它计划怎么验证能省掉后面一大轮返工。它像一个结构化思维很强的同事反而需要你更早介入纠偏。5.2 一个让我惊喜的扩展方向如果手头任务相对固定我会把常用任务固化成自己的 skill 文件写清楚触发条件、执行步骤和验收标准最后放进 skills 目录。前面提到的 weekly-report 就是一个例子现在它已经是我每周五下午的固定流程。你可以把这个思路复制到团队里的代码评审模板、CHANGELOG 生成、依赖升级流程等重复劳动上。我最近还在尝试把 superpowers 接进本地 CI让 AI 在提交前自己先跑一遍测试并把失败原因整理成可读的报告。目前还在实验阶段但方向是可行的。如果你也在摸索类似工具建议从那些一周至少重复三次的小任务开始等习惯了这种人定规则、AI 执行和自证的节奏你会慢慢发现自己的角色已经从写代码的人变成了给 AI 定规则和验收的人——这大概才是 superpowers 真正的超能力所在。