我把几个搜索热词里真正有价值的信息抽出来——superpowers 安装、使用指南、跟 Codex 的配合、Java 环境适配——然后按照“先搞懂项目是干嘛的再动手装再设计工作流最后排坑”的顺序来讲。内容全部基于这几个月在一线折腾和反复调整的真实经验尽量少讲虚的多给能直接抄作业的操作。1. 项目拆解superpowers 到底解决了什么问题1.1 先搞清楚 superpowers 不是“又一个 AI 工具”而是一套工作方式先说结论superpowers 不是一个开箱即用的单文件程序它更像是一组“技能包 工作流规范 CLI 自动化脚本”的组合。名字叫 superpowers意思就是给开发者尤其是重度使用 AI 编码助手的开发者叠加一层额外的能力把你日常反复在做的事情比如创建分支、跑测试、整理提交信息、调用 MCP 工具、让 AI 助手按照固定流程改代码全都变成一条条可复用、可触发的命令。如果你用过 Codex CLI、Claude Code 这类终端里的 AI 编程助手应该能感受到一个痛点每次跟 AI 对话你都要重新解释一遍项目结构、编码规范、测试命令、错误处理偏好。哪怕助手记忆能力再强换一个会话、换一个任务又得从头再来。superpowers 的核心思路就是把这类“上下文”和“操作流程”固化成文件放在项目的.superpowers目录或者全局的~/.superpowers目录里让 AI 助手每次启动都能自动读取并且通过定义好的命令直接执行多步操作。我自己的理解是如果说 AI 助手是一个聪明但缺乏记忆的新员工那 superpowers 就是你给这个新员工准备的“岗位手册 快捷指令集”。没有它你每次都要教一遍有了它你只需要说“按我们的规范处理”剩下的全部自动化。1.2 核心需求永远是“减少重复解释 让流程可沉淀”我试过很多种方式来解决这个痛点包括手写很长的 system prompt、用 shell alias 包装命令、甚至写 Python 脚本来自动拼 prompt。这些方法都能解决一部分问题但都败在一个点上不结构化。别人拿不到你的配置你换台电脑也拿不回来迭代了一版之后自己都忘了哪条规则是干嘛用的。superpowers 选择了一条更聪明的路子用目录结构管理一切。每个“能力”就是一个文件夹里面有说明文档、模板、可执行脚本以及给 AI 看的规则文件。比如你想让 AI 助手在修改 Java 代码时严格遵守某种错误处理风格那就定义一个java-code-review能力里面写明检查步骤、必须遵守的规范、常见反例。之后不管在哪个项目里你只需要说一句“使用 java-code-review 技能检查这段代码”AI 就会自动按照文件夹里的规则一步步执行。这套设计最妙的地方在于流程图不重要目录结构才是真相。你不需要画一张复杂的架构图来向团队成员解释某个工作流怎么运转直接把.superpowers目录扔进 Git 仓库所有人 clone 下来就拥有了同样的能力。项目交接、新人上手、跨机器同步全都变得非常自然。1.3 应用的场景远不止写代码但写代码是最典型的“第一站”从热词里能看到“codex superpowers”、“superpowers java”这种组合说明目前的主流用法确实是围绕 AI 编程助手展开的。我实际用下来下面几类场景收益最明显新项目初始化一键创建完整的项目骨架、Git 分支、README、初始提交全程按团队规范执行。测试驱动开发循环AI 助手自动“先写失败测试 → 运行测试 → 根据报错信息改代码 → 再跑测试”直到全绿才提交。代码审查预处理把待审查文件喂给 AI让它按照团队规则先过一遍标注问题点审查人只需要看摘要。繁琐的 Git 操作生成规范提交信息、自动合并主干、处理冲突提示全部封装成超级命令。坦白讲这些场景用裸的 Codex CLI 也能做但区别在于裸用的结果是“这次做对了”而用 superpowers 的结果是“每次都按同一套标准做对”。时间拉长以后后者积累出来的代码质量和效率差距非常明显。1.4 适合什么人先上手如果你是纯新手一点命令行都不会那我不建议你第一周就折腾 superpowers。它需要你至少熟悉基本的终端操作、Git 工作流、懂一点环境变量配置。反过来如果你已经用了一段时间 Codex CLI 或类似工具而且开始觉得每次对话前的“背景说明”很浪费时间那你就正好是 superpowers 的目标用户。我接触到的用户群体大致分三类独立开发者、小团队技术负责人、喜欢折腾工具链的技术爱好者。独立开发者看重的是个人效率翻倍小团队看重的是规范统一技术爱好者则纯粹觉得这套东西可玩性很高。2. 环境准备与安装从零搭好 superpowers 运行基座2.1 安装前需要准备哪些基础环境superpowers 本身不挑操作系统Linux、macOS、WindowsWSL 环境体验更好都能跑。但因为它依赖终端 AI 助手作为“执行大脑”所以你需要先装好一个支持的 CLI 工具目前社区用得最多的是 Codex CLI。以 Ubuntu 环境为例我建议的顺序是# 1. 先确认 Node.js 版本superpowers 生态大部分包要求 18 或以上 node -v # 2. 全局安装 Codex CLI npm install -g openai/codex # 3. 验证安装 codex --version如果你主要写 Java还要确保 JDK 版本和项目管理工具就绪java -version mvn -v # 或者 gradle -v我的经验是先把底层助手跑通一次最小对话再上 superpowers不然出了问题很难区分是助手本身的问题还是 superpowers 配置的问题。2.2 获取 superpowers 核心文件与目录初始化社区里已经有一些公开的 superpowers 配置仓库你可以 clone 下来直接参考也可以从零开始建自己的目录。我的建议是先从克隆开始跑通一遍再看文件内容比自己盲写要快得多。# 克隆一份主流的 superpowers 配置集举例具体仓库可按社区推荐选择 git clone https://github.com/your-reference/superpowers.git ~/.superpowers # 进入项目目录初始化超级能力全局级 cd ~/.superpowers ./install.shinstall 脚本做的事情很简单本质上就是创建目录结构、写入默认配置文件、设置环境变量别名。执行完以后你应该能看到这样的目录结构~/.superpowers/ ├── skills/ # 技能包每个子目录一个能力 │ ├── code-review/ │ ├── init-project/ │ └── tdd-loop/ ├── templates/ # 模板文件项目脚手架用的原型 ├── config/ # 全局配置 │ ├── config.json │ └── aliases.sh # shell 别名 └── logs/ # 操作日志如果你不想用别人的配置也可以手动创建这个结构。目录结构本身不复杂但一定要保持稳定因为后面所有技能、模板、日志都依赖它的存在。2.3 按需配置环境变量与别名安装完成后需要把 superpowers 的可执行脚本路径加到 shell 环境中。在.bashrc或.zshrc里追加export SUPERPOWERS_HOME$HOME/.superpowers export PATH$SUPERPOWERS_HOME/bin:$PATH # 常用别名这是我自己的习惯 alias spsuperpowers alias sp-listsuperpowers list alias sp-runsuperpowers run然后source ~/.bashrc让配置生效。这里有个很重要的细节环境变量是 superpowers 和底层 AI 助手之间的“传话通道”。AI 助手执行技能脚本时需要读取SUPERPOWERS_HOME才知道技能包在哪里。如果你发现某个技能“找不到命令 ”先检查环境变量是否在当前 shell 会话里生效。2.4 安装后的连通性自检清单装完之后不要急着写技能先把自检流程跑一遍。我一般按下面这个清单来检查项执行命令预期结果Codex CLI 可用codex --version输出版本号无报错superpowers 可执行sp --help打印帮助信息技能列表已加载sp-list能看到至少 3 个预设技能默认配置存在cat ~/.superpowers/config/config.json文件存在且为合法 JSON一个技能的 dry-runsp-run code-review --dry-run打印执行计划不会真正改动文件这五个检查全部通过说明你的运行基座是健康的。我在另一台机器上踩过坑Codex 明明能跑但 sp 命令在新建的终端里失效排查半天才发现是.bashrc没加载新路径属于非常低级但很常见的错误。3. 工作流设计与技能开发让 superpowers 真正干活3.1 一个技能包的完整构成规则、模板、脚本、说明前面说过superpowers 的能力核心是skills目录下的一个个技能包。一个标准的技能包至少要包含四个文件skills/code-review/ ├── SKILL.md # 技能主定义告诉 AI 这是干什么的、怎么执行 ├── rules.md # 规则文件代码审查时必须检查的具体条目 ├── templates/ # 输出模板审查报告的格式 │ └── report.md └── scripts/ └── extract_diff.sh # 配套脚本比如自动提取待审查代码SKILL.md是整个技能包的大脑。它不像普通文档那样给人读而是给 AI 助手读的。里面要用清晰、命令式的语言说明技能的目的、触发方式、执行步骤、可用参数。写得好不好直接决定了 AI 执行时靠不靠谱。我在写SKILL.md时总结了三个原则把执行步骤写到原子级例如“运行mvn test -DtestUserServiceTest”而不是“运行相关测试”。明确告诉 AI 什么情况下是“技能执行成功”以及必须输出什么样的结果。把异常处理写进去例如“如果测试失败读取失败日志提取堆栈信息回到第 3 步最多两次”。3.2 Java 场景实战设计一个自动测试循环技能热词里有“superpowers java”我就以 Java 项目中最高频的“测试循环”为例讲一下技能包怎么设计。先想一下没有技能时你手动怎么跑一个 TDD 循环写测试 → 跑测试 → 看报错 → 改实现 → 再跑测试。每一次和 AI 交互你都要说一遍“现在跑一下 UserServiceTest”“看下编译错误”“再跑一次”。有了 superpowers我们可以把这个循环封装成一个叫tdd-loop的技能。skill.md 的核心内容我会写成这样# Skill: tdd-loop 用于驱动一个完整的测试驱动开发循环。 ## 输入 - targetClass: 要实现的类名例如 UserService - testClass: 对应的测试类名例如 UserServiceTest ## 执行步骤 1. 读取当前项目中的 src/main/java 和 src/test/java 目录结构。 2. 如果测试类不存在先创建测试类骨架写入针对目标类的基本边界测试。 3. 运行 testClass 对应的测试命令mvn test -Dtest{testClass} 4. 等待命令执行完毕并读取输出。 5. 如果测试失败提取 Maven 输出中的 ERROR 摘要和堆栈信息根据失败原因修改目标类实现。 6. 重新运行测试命令如果仍然失败且修改次数达到 2 次停止并总结问题报告。 7. 如果测试全部通过输出简洁的测试结果摘要并建议可以执行下一条 Git 提交流程。 ## 输出格式 - 测试通过返回一行 PASS 摘要包含用例数、耗时、修改的文件列表。 - 测试失败返回诊断报告包含失败用例、首次出现的异常消息、已尝试的修改动作。注意这些命令 AI 助手是可以直接执行的因为底层 CLI 有执行权限。但你要防着一个问题AI 自己改坏了代码。所以我特别加入了“修改次数上限”和“停止并总结”的逻辑避免它在同一个错误上来回兜圈子。3.3 全局配置与项目级配置如何协同superpowers 支持两级配置全局配置和项目配置。全局配置放在~/.superpowers/config/影响所有项目。项目配置放在.superpowers/目录里只影响当前项目。两者自动合并项目配置优先。比如我在全局会设置默认的 Java 构建工具为 Maven默认代码风格检查工具为 Checkstyle但在某个用 Gradle 的项目里.project 配置里就会覆盖为 Gradle。这样既不用每个项目重复写公共规则又保留了特定项目的定制空间。合并规则的优先级一定要记牢否则你在一个项目里改了配置却发现不生效多半就是被全局配置盖住了。3.4 用别名和组合技能串联整个上线流程单个技能解决单点问题真正让 superpowers 产生“超能力”感觉的是把多个技能组合成一个流程。我的日常开发流程会用别名直接串联sp-run init-branch --name feature/payment sp-run tdd-loop --target PaymentService sp-run code-review --scope staged sp-run commit --type feat --message implement payment service with tests这四条命令执行下来完成的是过去需要二十分钟手动操作加大量提示词的同一套工作。这里的关键是“组合”而不是“流程编排”。superpowers 不会像 CI 工具那样去严格定义哪一步必须连接哪一步它更信任“人按顺序触发技能”。你完全可以只跑其中两步灵活度很高。3.5 通过“反馈笔记”让技能越用越准技能包跑完以后AI 会在结果里附上一些内部执行信息包括它读取了哪些文件、做了哪些决定。我会定期从日志目录里翻出这些记录把执行效果不好、容易误解的规则摘出来直接修改对应技能包里的rules.md文件。这套方法论比任何自动化优化都管用因为只有你最清楚到底哪里不符合预期。我最近一次调整是在code-review技能里加了一条“禁止检查 IDE 生成的 iml 文件”。原因是上个月的日志里AI 连续在五个项目里对这些文件给出无效建议浪费了大量审查时间。加入规则后这类无效工作直接归零。这种“反馈 → 调整 → 再验证”的循环才是我眼里 superpowers 最有价值的长期收益。4. 实际使用超级命令的完整过程演示4.1 场景从零初始化一个 Java 项目并跑通测试为了把前面的概念串起来我这里演示一次完整操作。假设我们要创建一个简单的 Java 库项目并立刻跑通一个测试。第一步使用init-project技能生成项目骨架。sp-run init-project --name demo-lib --package com.example --build maven执行过程中AI 会先读取项目模板目录然后生成 pom.xml、目录结构、主类和测试类骨架最后运行一次mvn compile确认代码可编译。我在模板里预设了 Maven 编译器插件版本和 Java 17 的release配置省去了每次手工补版本号的操作。第二步使用tdd-loop技能驱动实现一个业务方法。sp-run tdd-loop --target Calculator --test CalculatorTestAI 会按照技能定义先确保测试类存在然后运行mvn test -DtestCalculatorTest。第一次运行肯定失败因为Calculator.add方法还不存在。AI 读取报错信息生成最小实现再次运行测试。最终输出PASS: CalculatorTest - 3 tests, 73ms, modified files: Calculator.java整个过程不到两分钟而过去手动做同样的事至少需要五分钟外加多次粘贴命令。这里我需要特意说明你看到技能输出越简洁说明技能定义写得更成熟。如果输出信息特别啰嗦、步骤混乱多半需要回炉修改。4.2 场景review 代码并生成结构化报告代码写完后我会执行code-review技能sp-run code-review --scope staged这个技能先触发内部的extract_diff.sh脚本把 Git 暂存区里的改动文件提取出来交给 AI 按 rules.md 逐项检查。检查结果会生成一个标记格式的审查报告按严重程度分组列出问题和修改建议。它和人工 review 最大的不同是它会把耗时的“读代码找规则”这部分全做完人只需要盯着报告做最终判断。我实测下来一次中等规格的 MR审查时间从一小时压缩到十五分钟左右。4.3 场景处理繁琐的 Git 提交流程提交代码时我经常想给不同文件分配不同提交信息比如fix(api): adjust timeout和test: add coverage for timeout。手动处理这种拆分提交非常痛苦superpowers 的技能可以按变更类型自动分组sp-run commit --strategy semantic --split portable技能的脚本会分析每个文件的改动幅度与路径特征提出提交分组方案确认后自动执行git add和git commit。这个技能我第一次用时觉得“太工具化”但连续用了两周后真的回不去手动拆分提交了。4.4 实操现场记录一次完整的“超级命令”执行日志我保留了一段真实的执行日志做了简化处理可以帮助你理解这个系统的运行节奏$ sp-run code-review --scope staged --- Superpowers Skill: code-review --- 1. Resolve repository root: /home/dev/projects/demo-lib 2. Extract staged changes: 4 files changed, 128 insertions, 23 deletions 3. Load rule set: ~/.superpowers/skills/code-review/rules.md 4. Load review report template: templates/report.md 5. Reviewing changes by rule groups: - Naming conventions: 0 violations - Error handling: 2 warnings - Security scanning: 0 issues 6. Generate final report - /home/dev/projects/demo-lib/.superpowers/logs/review-20250614-1023.md 7. PASS: review complete, 2 warnings, see report file注意看第 2 步脚本自动提取了变更范围。没有这步的话AI 助手通常会按自己理解去读文件结果经常漏掉新文件或读了无关文件。这正是技能把脚本与语言模型结合起来的价值脚本负责“精确获取事实”语言模型负责“判断和执行规则”。5. 常见问题与排查技巧实录5.1 命令找不到、权限异常、环境变量未生效这是新手区最高频的问题。症状是执行sp-run时提示“command not found”或者技能执行到一半提示无法读取某个目录。我的排查顺序固定如下先确认当前 shell 确实加载了 superpowers 的 PATHecho $SUPERPOWERS_HOME如果没有输出说明.bashrc里的 export 没生效source ~/.bashrc或重开终端。如果路径存在再确认 bin 目录下是否有可执行文件ls -la ~/.superpowers/bin检查权限chmod x ~/.superpowers/bin/sp权限问题在 macOS 上尤其常见新克隆的脚本默认没有执行权限chmod 一下就好。5.2 技能执行结果不符合预期AI 不按规则行动这种情况通常不是“ AI 不听话”而是技能包的定义文件太模糊。例如你在SKILL.md里写“请保证代码质量”AI 不知道“质量”的具体含义。正确做法是给出可操作的检查清单。我常用的修改策略是把 output 模板和 rules 写得更绝对。在rules.md里明确写“禁止使用 catch(Exception e) 后不输出日志”“所有 public 方法必须有单元测试”这种硬性规则配合 AI 执行效果远好于“请写好日志”“请保证覆盖率”。5.3 技能之间互相干扰、日志文件越攒越多当你创建了十几个技能后可能发现某个技能执行时意外调用了另一个技能的内容或者日志目录膨胀得厉害。我的做法是为高频技能设置独立的输出目录并在技能定义开头加一行“禁用无关技能读取”日志通过 cron 每周清理三十天前的旧文件避免磁盘被撑爆。5.4 快速排查工具一个 table 解决 90% 的启动问题我把日常踩坑经验整理成一个速查表分享给你直接用症状最可能原因推荐处理sp 命令不存在PATH 未配置或未 source检查 SUPERPOWERS_HOME 并 source 配置技能列表空白技能目录路径不对确认 skills 目录真实存在且有子目录AI 不执行命令权限配置缺失检查 AI 助手的命令执行等待授权时间Java 项目编译失败JDK 版本与 Maven 配置不匹配统一用 .mvn/jvm.config 固定版本审查报告为空暂存区没有文件先 git add 再执行技能日志不输出log 目录不存在或写保护mkdir -p 并确认 owner 权限这些排查经验对我自己帮助很大尤其是肉眼看不见的“目录结构不对”这类问题直接导致一切技能失效没有经验的话很难快速定位。6. 效率提升的隐藏技巧workbuddy 这类辅助脚本要善用6.1 把“辅助脚本”纳入 superpowers 体系搜索热词里出现了 “worbuddy 怎么用 superpowers”我理解这里提到的 workbuddy 是一类辅助脚本工具用于简化日常开发操作。它可以作为 superpowers 技能的内部调用工具使用。比如在SKILL.md的执行步骤里指定先调用 workbuddy 生成某个配置文件再由 AI 助手读取并继续处理。这类组合模式的核心价值在于辅助脚本负责解决“确定性的重复劳动”——生成项目配置、格式化文件、批量重命名、同步依赖版本AI 负责解决“需要判断力的工作”——解读报错、设计代码结构、写测试用例。把两者结合起来superpowers 的技能包能覆盖更多真实世界开发中的复杂任务。6.2 通过技能定义控制辅助脚本的输入输出我自己在使用辅助脚本时有一个很深的教训一定要在技能定义里明确输入和输出的格式。我知道有些人直接把辅助脚本的原始输出全盘塞给 AI导致 AI 被无关日志干扰反而忽略了真正重要的信息。正确做法是裁剪输出只保留 AI 决策真正需要的部分例如文件清单、错误行号、版本号。后来我在每个涉及辅助脚本的技能里都加上一条“将脚本输出精简为纯文本摘要不包含进度条与装饰性字符”这一个小改动让整个技能的执行准确率提升了不少。6.3 懒人但可靠的日常用法如果你不想写技能包也完全可以手动调用辅助脚本 Codex CLI 的组合先跑脚本完成确定性操作再打开 AI 对话让它继续处理。我在时间不充裕时会用这条捷径效果依然比纯手动高效但缺点是无法沉淀流程。等你发现某个辅助脚本 AI 的组合在四周内重复使用了三次以上就是把它封装成 superpowers 技能的最佳时机。我在实际操作中最大的体会是superpowers 的价值不是一开始就显现的而是随着你不断把工作习惯“文件化”慢慢爆发出来的。刚装好那天你可能觉得它只是个目录结构但用了一个月后再回头看你已经积累了一套真正属于自己团队的、可迁移的开发流程资产。这也是我最想推荐你先从一个小技能开始封装的原因——不要贪多选一个每星期都会做三次以上的操作花半小时把它变成你的第一个超级能力之后你就会自动开始第二个、第三个直到整个工作流都跑在这套体系上。