最近在开发者圈子里superpowers 这个词出现的频率明显高了起来。如果你在用 Codex 这类 AI 编程助手大概率会看到有人讨论如何给它装上“超能力”——说白了就是让 AI 不只是会聊天写代码还能真正接手一个完整的工程任务自动拆需求、改代码、跑测试、修报错甚至跨语言重构。这篇文章不打算讲那些花里胡哨的概念就围绕 superpowers 这个工具本身从安装到实战把能落地的用法捋一遍。无论你是刚接触 AI 编程的新手还是已经在用 Codex、Cursor 的老手都能找到可以直接抄作业的地方。1. 整体设计与思路拆解1.1 为什么需要 superpowers默认情况下绝大多数 AI 编程助手是问答式的。你给它一句“帮我写一个登录接口”它往往会直接吐出一段代码然后等你复制到项目里。如果只是写个小函数这样没问题可一旦涉及多文件改动比如加一个完整模块、修一个深层 bug、重构一段老代码这种一问一答的工作方式就会让人崩溃。你得反复把相关文件内容塞进对话提醒它别改错地方测试跑挂了还要把报错日志再喂一遍。整个过程充满了人工搬砖AI 更像一个“高级代码片段生成器”而不是真正意义上的协作者。superpowers 的设计目标就是把“任务式编程”这套流程固化下来。它会把常见的开发活动封装成一个个技能包比如“修 bug”“加接口”“写单元测试”“做代码审查”。每个技能包内部定义了 AI 应该怎么拆解任务、先做什么后做什么、每一步的验收标准是什么。你只需要给出一句话目标superpowers 负责把这句话翻译成可执行的任务清单然后调度 Codex 去完成。这样一来AI 不再是想到哪写到哪而是有流程、有纪律地干活。1.2 核心设计技能即代码superpowers 最核心的概念是“技能”skill。一个技能本质上不是一段提示词而是一个包含规则、脚本、模板的目录。它把“如何让 AI 完成某类任务”的经验变成可以复用、可以版本管理、可以分享给团队的东西。一个典型的技能目录长这样skills/ java-spring-boot/ SKILL.md scripts/ verify.sh templates/ controller.java.tpl constraints/ no_system_exit.txt其中 SKILL.md 是这个技能的“说明书”里面写着技能名称、适用场景、触发关键词、执行步骤、验收标准。scripts 目录放着一些预处理的脚本比如生成代码后自动跑测试、检查代码风格。templates 是代码模板AI 会基于这些模板生成具体的实现。constraints 是约束文件告诉 AI 哪些事情绝对不能做比如不能调用 System.exit。为什么要把技能写成文件而不是写成一大段 prompt因为 prompt 是提给模型的临时指令用完就没了而技能文件是持久化的资产。今天你花半小时打磨一个“代码审查”技能以后团队每个人都能用到而且还能继续迭代。这套思路类似软件工程里的“配置即代码”“文档即代码”本质是把经验沉淀下来。1.3 与 Codex 的协作关系需要明确一点superpowers 不是要替代 Codex恰恰相反它依赖 Codex 作为底层执行引擎。Codex 负责理解代码语义、生成代码、操作终端命令superpowers 则负责更高层的任务规划、上下文管理、质量门槛控制。打个比方Codex 是发动机superpowers 是变速箱加方向盘。发动机决定你跑得快不快变速箱和方向盘决定你怎么跑、往哪跑。没有 superpowers你也能开着发动机到处冲但有了它你才有清晰的路线图和换挡逻辑。实际使用中superpowers 会把一个复杂任务拆成若干小步骤每一步都走一次“读取上下文 - Codex 生成方案 - 执行修改 - 自动校验”的循环遇到问题就停下来询问你而不是闷头改完再说。2. 工具选型与环境准备2.1 环境依赖清单在动手安装之前先确认本机环境满足要求。以我日常使用下来的经验下面这份清单基本是底线依赖版本要求用途操作系统macOS 12 / Linux / Windows 10 (建议 WSL2)superpowers 的脚本大量使用 Unix 命令Windows 原生环境会频繁踩坑Node.js18.0.0 以上superpowers CLI 本身是通过 npm 分发的Git2.30 以上技能包获取、项目版本管理Codex CLI最新版底层 AI 执行引擎Java JDK11做 Java 项目时需要编译、运行测试、识别 Maven/Gradle 依赖为什么强制要求 Node.js 18因为 superpowers 的语法用到了较新的 Web Streams API 和 fetchNode 18 是第一个原生支持这些特性的 LTS 版本。如果你还在用 Node 16装完大概率会报“fetch is not defined”。如果你本机已经装了 Codex CLI可以直接通过 npm 安装 superpowers。没有的话也可以让 superpowers 在安装过程中帮你把 Codex 一起配置好不过我还是建议先单独装 Codex 并跑通一个简单对话再接入 superpowers排查问题会更简单。2.2 安装 superpowers安装命令很简单npm install -g superpowers/cli安装完成后先验证一下superpowers --version能看到版本号就说明装好了。如果提示 command not found通常是 npm 全局目录没有加到 PATH 里可以用npm bin -g查看目录再手动 export。接下来要做的是把 superpowers 和 Codex 集成起来。superpowers 提供了一个自动配置命令superpowers setup执行之后它会扫描你本机的 Codex 配置文件自动写入集成标记。如果你希望手动改也可以打开 Codex 的配置文件一般在~/.codex/config.toml加上一行integration superpowers注意集成标记不是让 Codex 变成 superpowers而是让 superpowers 能通过 Codex 的本地接口调用模型。两边各司其职。2.3 初始配置与目录结构第一次运行 superpowers 时建议先执行superpowers init这会在你的用户目录下生成一个.superpowers文件夹。默认结构如下~/.superpowers/ config.json skills/ general-task/ SKILL.md java-spring-boot/ SKILL.md templates/ scripts/ logs/config.json是全局配置文件里面有几个字段值得关注{ provider: codex, model: gpt-4o, workdir: ~/projects, defaultSkill: general-task, autoApprove: false, maxSteps: 20, ignorePatterns: [ **/node_modules/**, **/target/**, **/.git/** ] }解释一下provider指定底层执行引擎目前主要就是 codex。model指定模型名建议跟随 Codex 所在配置的模型不要单独改否则可能不一致。workdir默认工作目录superpowers 只会在这个目录下扫描和修改文件。autoApprove是否自动批准 AI 执行每一步。我强烈建议保持 false。让 AI 直接改文件这事前期还是需要你亲眼盯一盯等信任建立起来再开自动模式。maxSteps单个任务的最大执行步数。防止 AI 陷入死循环。默认 20 步复杂任务可以调到 50。ignorePatterns扫描文件时忽略的目录一定要把target、node_modules这类生成目录加进去否则上下文窗口很快就满了。实际使用中ignorePatterns几乎是必调项。我第一次跑 Java 项目的时候没配它superpowers 把整个target目录下的编译产物都读了一遍结果还没开始写代码上下文就超限了。这个坑后面会细说。3. 核心实操让 superpowers 跑起来3.1 用技能生成一个 Java Spring Boot 项目配置好环境之后找一个干净目录跑第一个真实任务。比如我想生成一个 Maven 管理的 Spring Boot 项目命令是superpowers run create a new Spring Boot project with Maven in ./demosuperpowers 会先解析这句话匹配到内置的java-spring-boot技能然后展示任务计划。我这次实际运行看到的计划分成了四步检查目录是否为空确认项目名称。生成pom.xml写入 Spring Boot 依赖和 Maven 插件。生成启动类、application.yml、一个基础的健康检查接口。执行mvn test验证项目能启动。执行完每一步之后superpowers 会短暂停留把改动过的文件列出来并问我是否继续。确认之后才会进入下一步。最终看到BUILD SUCCESS的时候这个项目就直接能跑了。这里有个小细节如果你本机没有 Maven 或者没有配置 MySQL 之类的连接串superpowers 生成的代码可能是“最保守”的版本比如内嵌 H2 数据库、无外部中间件依赖。这是为了保证验证能通过。如果你需要更复杂的配置比如接入 Redis、Kafka最好在命令里说清楚比如“用 Docker 启动一个 Redis 实例并让应用连接它”它会尝试把 Docker Compose 文件也生成出来。3.2 实际开发任务给项目增加 REST API生成新项目只是热身更常见的是在已有代码仓库里干活。我拿一个已经存在的 Spring Boot 项目做测试命令很简单superpowers run add a user login REST API to the existing Spring Boot project和刚才一样它先给出了执行计划扫描项目结构定位 User 实体和 UserRepository。检查现有 Controller 的代码风格保持新接口风格一致。生成 LoginRequest、LoginResponse DTO以及 UserController 中的 login 接口。补充密码校验逻辑返回 JWT token如果项目里有 JWT 依赖。运行mvn test并给出覆盖率变化。几步走下来代码风格确实和项目里原有的风格基本一致。因为它会先读取项目里已有 Controller 的写法再模仿同样的注解、包名、返回结构。这一点比自己复制粘贴到 ChatGPT 里问要靠谱得多因为上下文是实时的、项目级的。比较值得一提的是superpowers 在执行计划里加入了“确认”步骤。比如在第 4 步它发现项目里没有 JWT 库于是停下来问我“当前项目未引入 JWT 依赖是否添加jjwt依赖并生成 token还是先返回简单 token 字符串”这种交互非常关键它不会自作主张引入一个重量级依赖而是让你决定技术方案。如果你不想每一步都确认可以临时加一个参数superpowers run add a user login REST API --auto-approve-steps但我不建议在改动较大的任务里用这个参数一旦方向跑偏回滚的成本反而更高。3.3 与 WordBuddy 联动处理需求文档不少团队会拿 WordBuddy 管理需求文档和接口文档但 WordBuddy 本身不写代码。以前把文档里的需求转成代码全靠人脑翻译现在可以通过 superpowers 把这条链路打通。具体做法也不复杂。WordBuddy 支持导出 Markdown或者把文档内容复制出来存成本地 Markdown 文件。然后运行superpowers run --input-file requirement.md --skill java-spring-bootsuperpowers 会先读取requirement.md把里面的接口描述、字段定义、业务规则提取出来然后结合技能库生成任务计划。比如文档里写“用户登录时需要校验验证码”它就会在计划里加入验证码校验这一步如果文档里没有写异常处理的细节它会在执行时主动问你。这里有个经验文档越结构化和 AI 的配合越好。如果 WordBuddy 里的文档是整段叙述没有列表、没有明确的字段表格AI 就需要额外花精力去“猜”哪些是需求、哪些是背景描述。所以我一般会在导出之前把接口名、请求参数、响应码整理成表格哪怕只是简单的 Markdown 表格任务完成度都会有质的提升。这不是 superpowers 的局限而是所有 AI 编程工具的通性——你没给它看清楚的边界它就只能在边界附近瞎转悠。4. 常见问题与排查技巧实录4.1 命令找不到或版本过旧新手最容易碰到的问题就是安装完superpowers --version报 command not found。原因多半是 npm 全局目录不在 PATH 里。解决办法很简单先看目录npm bin -g把输出的目录加到 shell 配置里然后重开终端。如果之前装过旧版本记得先卸载npm uninstall -g superpowers/cli npm install -g superpowers/clilatest如果你不想全局安装也可以直接用 npxnpx superpowers/cli run your task不过 npx 每次启动都会检查最新版本速度会慢一些。我建议还是全局装一次省心。4.2 Java 项目识别不到依赖有次我在一个多模块 Maven 项目里跑任务superpowers 频繁报“找不到包”后来发现是它没识别到根pom.xml。原因是我把workdir配置到了某个子模块目录而 superpowers 只在当前目录向上找一层pom.xml压根没看到父工程的依赖管理。解决办法有两个。一是把workdir指向多模块项目的根目录二是在项目根目录运行superpowers scan让它重新生成项目索引。另外如果项目里用了 Lombok记得确保本机 Lombok 插件状态正常因为 AI 在读取编译错误信息时Lombok 生成的 getter/setter 报错很容易误导它让它以为是缺依赖。4.3 任务卡在“分析代码”阶段如果任务运行很久日志一直停在“analyzing repository”十有八九是文件扫描范围太大。默认的ignorePatterns只会忽略 target 和 node_modules但如果你项目里还有build、dist、.gradle、generated这类目录它们也会被一股脑读进去。我实际的调整方式是给每个项目建一个.superpowerignore文件内容类似target/ build/ dist/ generated/ *.class *.jar和.gitignore的语法一致。superpowers 读取上下文的时候会跳过这些目录任务速度能快好几倍。如果任务还是要处理特定源码目录可以在命令里显式指定superpowers run refactor service layer --focus src/main/java这样它只会扫描src/main/java不会去碰测试代码减少噪音。4.4 任务中断后如何恢复开发过程中难免会遇到手滑按了 CtrlC或者笔记本没电突然关机。这时候不要慌superpowers 会把任务的中间状态记录在.superpowers/state.json里。恢复命令是superpowers resume它会读取最近一次未完成的任务从断点继续执行。需要注意两点一是不要在当前目录做大量手动改动之后再恢复否则状态对不上二是恢复前最好先git status看下工作区确认没有被 AI 改过的文件和你自己的改动冲突。如果冲突了优先保留手动修改的部分让 superpowers 基于最新状态重新规划下一步。4.5 网络环境受限时的处理superpowers 本身是本地工具但它需要调用 Codex 背后的模型 API。如果运行环境在公司内网或者防火墙阻止了对 API 服务的访问任务通常会卡在第一步报超时或连接失败。这时候先不要急着调整 superpowers 配置先用 curl 测一下 API 服务是否通。如果确实不通需要联系网络管理员开通白名单或者确认所在网络是否允许访问外部 AI 服务。这是最合规的做法也不容易出现后续的安全问题。千万不要尝试绕过网络限制一方面违反多数公司的安全策略另一方面这类行为本身就存在很大风险。4.6 常见问题速查表问题可能原因解决方案npm 安装后 command not foundnpm 全局目录不在 PATH执行npm bin -g并 export版本太旧功能缺失全局缓存了旧版本卸载后重装 latestJava 项目找不到依赖workdir 没指到根目录改 workdir 或运行superpowers scan任务分析阶段特别慢扫描了 target/build 等目录配置.superpowerignore或--focus任务意外中断手动 CtrlC / 断电运行superpowers resumeAPI 超时网络环境受限联系管理员开通访问白名单5. 进阶扩展自建技能与团队复用5.1 技能目录与格式内置技能用起来再顺手也不如自己针对团队场景定制。superpowers 允许在~/.superpowers/skills下放自定义技能目录结构只要符合约定就能被自动加载。我拿一个“生成单元测试”的技能举例。目录如下~/.superpowers/skills/unit-test-generator/ SKILL.md scripts/generate.py constraints/no_mock_static.txtSKILL.md 的内容可以这样写--- name: unit-test-generator description: 为指定Java类生成JUnit 5单元测试 trigger: 生成单测, 写测试, unit test steps: - 定位待测类 - 分析依赖并创建 Mock - 生成测试代码 - 运行 mvn test validation: - 测试必须全部通过 - 核心逻辑覆盖率不低于 80% - 不允许使用 Mockito 私有方法 mock文件开头的name、description、trigger是元信息superpowers 会用它来做意图匹配。steps是给 AI 的执行指南validation是跑完任务的验收标准。这些内容写得越具体AI 的表现就越稳定。一份好的 SKILL.md几乎等价于团队里的工程规范文档。5.2 把技能发布到团队共享单人自定义技能是锦上添花团队共享才是效率放大器。做法很简单把自定义技能的目录放进一个 Git 仓库然后让团队成员把仓库克隆到本地再通过环境变量指向它。export SUPERPOWERS_PATH/path/to/team-skillssuperpowers 启动时会合并内置技能和SUPERPOWERS_PATH指向的技能目录。如果某个技能名重复了团队自定义技能会覆盖内置版本。团队共享的好处不只是复用还能让技能本身持续迭代。比如这个月大家发现“代码审查”技能的步骤里漏了“检查配置项是否硬编码”直接改 SKILL.md 提交到仓库全团队立刻生效。这种“经验实时同步”的效率是普通文档分享给不上的。5.3 踩过的坑技能别写成“正确的废话”我最初写“代码审查”技能时犯过一个典型错误。当时我在 SKILL.md 里写“检查所有代码异味给出改进建议”。结果 AI 执行起来又慢又空泛每段代码都能挑几条不痛不痒的毛病真正的问题却漏掉了。后来我把验收标准改成几条硬性规则方法体超过 50 行必须提示拆分禁止捕获异常后不打印日志禁止硬编码配置项公共方法必须有 TODO 或注释说明改成这种可验证的规则之后AI 的输出质量明显提升。这个经历说明一个核心原则技能描述越具体越好泛泛而谈的指令只能得到泛泛而谈的结果。你希望 AI 达到什么标准就得先把标准写清楚。最后聊一点个人体会。superpowers 这种工具的本质是把“你希望 AI 怎么干活”这件事变成可重复执行的资产。我实际用下来最明显的改变不是代码写得快而是返工率降下来了因为每一步都有明确验收标准AI 不再是自由发挥。如果你打算在团队里推这套东西我的建议是先从一个高频场景入手比如修单元测试或者生成接口文档跑通之后再把技能沉淀到 Git 仓库里。磨刀不误砍柴工这句话放在 AI 编程时代依然适用。