Superpowers 实战：用 Skills 与 Workflow 重塑 AI 编程助手

1. 为什么我盯上Superpowers：AI编程助手的两大痛点

先说说背景。我从去年开始重度使用 Codex 这类 AI 编程助手，最初的体验确实惊艳——让它写个工具函数、补个单元测试，基本属于"说句话就能干活"。但真正把它丢进企业级 Java 项目里，问题很快就暴露了：它往往只回答你问的那一个问题，却不会主动照顾整个项目的上下文。

你可能也遇到过类似场景：我让 Codex 加一个 REST 接口，它三下五除二生成了 Controller 代码，结果没有加参数校验，没有处理异常，也没有写单元测试。我再补一句"加上测试"，它倒是写了，但测试风格和项目里已有测试完全不一致——项目里用的是 JUnit 5 + AssertJ，它给的是 JUnit 4 + 一堆 Mockito 的旧写法。最后我花在"纠正 AI"上的时间，居然比我自己动手写还要多。

这个问题的根源，在于 AI 编程助手的本质是"单轮对话式生成"。你给它一个 prompt，它基于上下文给你一个回答，然后这个对话可能就终止了。它不会自觉地形成一个"需求分析 → 设计 → 编码 → 测试 → 代码审查 → 修复"的闭环。而真实项目的开发，恰恰需要这种闭环。

我试着用更详细的 prompt 去约束它，比如一次性把需求、规范、测试要求、目录结构全塞进去。刚开始还行，但 prompt 越长，AI 越容易遗漏关键约束，而且维护一堆一次性 prompt 本身就是沉重的负担。直到我注意到 GitHub 上这个叫 Superpowers 的项目——它的设计思路恰好解决了这个结构性问题：不是让 AI 靠临场发挥理解你的项目，而是让你把一个项目里所有隐性的规范、约定、工作流，变成一套 AI 可以理解并主动执行的"技能（Skills）"。

来聊聊我的实际体验。Superpowers 不是一个 IDE 插件这么简单，它对标的其实是"AI 协作规范基础设施"：你可以定义技能、定义工作流、定义 AI 在每个环节里应该遵守的行为准则。它和 Codex 配合使用时，会让 AI 从"被动回答问题"变成"按照既定流程办事"。听起来很玄？接下来我尽量用大白话讲清楚它的安装、核心机制和实战效果，包括我踩过的几个坑。

2. 安装前的准备：环境、版本与几个常见误区

2.1 运行环境与前置依赖

先明确一点：Superpowers 本身不是独立的 AI 引擎，它是挂接在现有 AI 编程工具之上的"能力增强层"。所以前置依赖有两类：一类是它自身的运行环境，另一类是你已经装好的 AI 工具链。

我自己实测下来比较省心的组合是：

• Node.js 18 或更新版本：Superpowers 的大部分命令行工具和脚本执行依赖 Node 运行时，低版本会直接报语法错误。
• Git：这个不用多说，源码安装和技能版本的更新都用得上。
• Codex CLI 或兼容命令：如果你用的是 Codex 的命令行版本，最好先确认它在终端里能正常运行，再装 Superpowers。因为 Superpowers 本质上是在调用你本机的 AI 命令行工具。
• 操作系统层面：Windows 用户建议用 WSL2 或 Git Bash 跑命令行脚本，纯 PowerShell 下部分 shell 脚本文本处理容易出幺蛾子。我团队里有同事在 Windows 上折腾了半天没成功，换到 WSL 后一次通过。

注意：Superpowers 对不同版本 Codex 的支持程度不完全一样。如果你同时装了多个版本的 AI 编程助手，务必确认最终在 PATH 里生效的是哪一个，否则会出现"Superpowers 调起的模型和我预期的不一样"这种尴尬问题。

2.2 三种安装路径：IDE 插件、CLI 脚本、源码构建

我体验下来，Superpowers 给不同使用习惯的人准备了三条安装路径（现在业界头部项目也基本都是这个套路）：

路径一：IDE 插件市场安装（最省事）

如果你是 JetBrains 系的重度用户，直接在插件市场搜索 Superpowers 就能找到官方插件。装好之后重启 IDE，插件会自动检测你本机的 Codex CLI，并完成基础的关联配置。这种方式对单文件、单模块的操作很友好，因为你不用离开 IDE 界面。

路径二：命令行脚本安装（推荐给日常大量使用 AI 的人）

我目前的主力路径就是 CLI 方式。官方提供了一行安装脚本，大致逻辑是克隆主仓库到用户目录下的特定位置，然后执行npm install安装依赖，再用一个交互式命令完成初始化配置。这个过程会在你的用户目录下生成一个隐藏配置目录，里面存放技能仓库、工作流定义和日志文件。

路径三：源码构建（适合想改底层行为的进阶玩家）

如果你对内置技能不满意，或者想研究 Superpowers 到底怎么解析技能定义，直接从源码构建更好。做法就是git clone主仓库，进入目录执行npm install再npm run build。构建出来的可执行文件会链接到你的系统命令目录里。源码构建的好处是你能看到所有技能的原始定义，后续拿来自定义时思路会清晰很多。

2.3 安装阶段最容易踩的三个坑

第一坑：装了插件但 Codex CLI 没在 IDE 设置的 PATH 里。JetBrains 系 IDE 默认不会继承你终端里的全部环境变量，尤其是 macOS 下面，图形界面启动的 IDE 经常找不到你放在/opt/homebrew/bin之类的命令。解决办法很简单：在 IDE 的"终端"设置里，把环境变量重新指一下，或者干脆在插件设置里手动写上 Codex CLI 的绝对路径。

第二坑：网络不好导致 npm 安装中断。Superpowers 的依赖数量不算少，在国内网络条件下经常出现一半就卡住的情况。建议先把 npm 的 registry 切到国内镜像源再装，装完依赖再切回来，这样最稳定。整个过程不需要任何额外操作，只要改 npm 配置即可。

第三坑：初始化配置被跳过。不少人在命令行装完后直接就开始用，结果发现 AI 完全没有按照技能工作。因为很多技能在首次启用时需要一个"注册"过程，有些类似在工作目录里生成一个技能清单文件。你跳过了初始化，Superpowers 自然不知道自己该在什么时候加载什么技能。

3. 核心玩法：Skills 机制到底是怎么运作的

3.1 Skills 的目录结构与配置逻辑

要理解 Superpowers，必须先理解一个概念模型：每个 Skill 就是一个"角色 + 行为准则 + 执行脚本"的完整封装。它不像普通插件那样只是给 AI 加几个工具函数，而是把某一类真实工作场景完整建模成 AI 可以遵循的流程。

说个具体例子。现在我在做 Java 项目，希望 AI 每次写 Spring MVC 的 Controller 时都严格遵守项目规范。于是我做了一个名为java-spring-controller的 Skill，它的目录结构大致是这样：

skills/ └── java-spring-controller/ ├── SKILL.md # 技能的说明书 ├── scripts/ # 可执行脚本 │ ├── validate-structure.sh │ └── generate-test.sh └── lib/ # 供 AI 调用的辅助函数

SKILL.md是这个技能的核心，里面的内容直接影响 AI 的行为方式。我写的不是"请遵守代码规范"这种模糊话，而是非常具体的约束：

• Controller 必须放在restapi/controller/包下，命名以Controller结尾
• 参数校验必须使用jakarta.validation注解，禁止手写 if 判空
• 方法必须返回ResponseEntity<T>，业务错误统一走异常处理器
• 每个新接口必须配套一个 MockMvc 测试，测试命名格式为XxxControllerTest

当 Codex 工作在这个目录下时，Superpowers 会把这些说明以系统指令的形式注入到 AI 的上下文中。**AI 不需要靠猜，它可以直接读取到你想让它遵守的每一项规则。**这比你在每一条 prompt 结尾重复"记住用 AssertJ"有效得多。

3.2 Workflow 机制：把多个 Skill 串起来

如果说 Skill 解决的是"AI 在某个环节怎么做"，那 Workflow 解决的就是"AI 该怎么走完整个流程"。Superpowers 的 Workflow 有点像流水线的排产单：先做什么、再做什么、每步的完成标准是什么。

我参考官方文档搭过一个"新接口开发"的 Workflow，大致逻辑是：

1. AI 先分析需求，输出接口设计和变更影响范围
2. 按java-spring-controller技能的要求生成代码
3. 自动运行mvn test跑测试
4. 如果测试失败，AI 根据失败信息定位并修复，重复直至通过

这个过程中，AI 不再是一个"只会答问题的对话机器人"，更像是一条"带质检和返工环节的生产线"。当然它绝不完美，有时候卡在第四步反复修不好会让人崩溃，但相比手动控制每一次对话的走向已经有质的提升了。

3.3 Superpowers 与 Codex 的实际协作模式

很多人对"Superpowers 调 Codex"有误解，以为它是在后台偷偷调用一个大模型 API。其实不是。它是通过在命令行层面包装 Codex CLI 来实现协作的：你在终端输入类似superpowers的命令进入交互模式，然后在会话中指定要执行的 Workflow，Superpowers 会负责生成一系列结构化的指令，按步骤调用 Codex CLI 来执行。

这个过程有点像"制片人"和"导演"的关系。Superpowers 是制片人，它决定整个工作流程怎么走、每一场戏拍什么；Codex 是导演，它负责在具体的镜头里发挥创作能力。制片人不会替导演写剧本，但导演必须按照制片人制定的全片计划来拍。

3.4 一个关键设计：人机协商而不是全自动执行

坦白说，我在入手之前最担心的是这东西会把代码改得面目全非。Superpowers 的理念在这点上倒是挺克制：它的许多 Workflow 里设计了"人在环上"的确认点。比如在生成代码之前，AI 会把实现计划列出来问我"是否按这个方案执行"；在删除或重命名文件之前，也会停下确认。

这种"协商式自动执行"的节奏，在代码生成类任务里非常实用。AI 全自动跑的后果一般是灾难性的，但每一步都让你点头的话又太啰嗦。Superpowers 把确认点放在关键决策节点上，那些重复性的、低风险的执行步骤全部自动过，体验会顺滑很多。

4. Java 项目实战：从需求到闭环的一次完整演示

4.1 一个真实的 Spring Boot 需求

为了把前面的概念落到实地上，我拿自己手头一个真实的 Spring Boot 项目场景说事。需求很简单：为一个订单系统新增一个"查询订单详情"的接口，返回订单基本信息、明细列表和当前状态。

放在以前，我给 Codex 的命令十有八九是一句话："帮我写个查询订单详情的接口。"然后它就给我写了一个只查主表、不查明细、没有任何校验的 Controller。现在有了 Superpowers，我的操作方式完全不同了。

我先在当前项目根目录下启动 Superpowers 交互模式，输入：

run workflow "orders-api-new-endpoint" with "新增订单详情查询接口，订单号参数必填，需要返回订单头信息和明细行"

Superpowers 收到这个指令后，会先解析出这个 Workflow 的执行计划，然后开始逐步执行。

4.2 技能让 AI 的代码输出脱胎换骨

这个 Workflow 里我预先挂了三枚技能：

• java-spring-controller：保证代码风格和包路径正确
• java-spring-dto：规定 DTO 字段类型、注解风格、序列化规则
• java-rest-api-test：强制生成接口测试

执行到"生成代码"这一步时，AI 就不只是埋头写一个 Controller 了。它会先看看项目里已有的 DTO 结构，推断出统一的返回格式；它知道订单明细子查询的性能敏感点，所以明确告诉我要不要用批量查询；它甚至会在生成代码后自己打开测试类，确认测试风格和项目现状一致。

最终生成的效果我相当满意：Controller 短小精悍，参数用了@RequestParam+ 手动校验；DTO 的命名和字段排列风格和项目其他类几乎一致；测试类用的是 MockMvc，断言风格符合项目惯例。最妙的是，它还在计划里主动提出了一个我没有明确要求的点——查询结果为空时应该返回 404 还是空对象，它在确认点停下来征求我的意见。

4.3 自动测试闭环：真正省时间的地方

代码生成完毕，Workflow 会自动跑mvn -Dtest=OrderDetailControllerTest test。这步之前我是完全手动执行的，每次切终端窗口、看测试报告、再回去改代码，来回折腾至少五分钟。现在 Workflow 一口气跑完，如果不是预期失败，AI 会根据 Maven 输出的错误堆栈自己定位问题并修复。

我印象最深的一次：测试报了MockHttpServletResponse.getContentAsString()的 JSON 解析错误，AI 三秒钟就分析出是 DTO 中一个 LocalDateTime 字段的序列化格式配置缺失，导致 JSON 里出现了数组而不是字符串。它没有像人一样傻乎乎地改断言，而是直接调整了项目里的Jackson配置类，补上了@JsonFormat注解，然后重新跑测试，一轮通过。

这种"根据错误信息自动归因"的能力，我不太确定是 Codex 模型本身具备的，还是因为 Workflow 里写清楚了测试与修复的迭代逻辑。但结果就是——我一杯水还没喝完，接口从开发到测试已经全走完了。

4.4 我观察到的一些边界

也得说点实话。这套流程在"需求明细清晰、项目结构规整、测试基建可靠"的模块上表现极好，但在处理历史遗留代码时就力不从心了。我有个老项目的 Service 层全是几千行的上帝类，AI 每次分析依赖关系都要花很长时间，偶尔还会给出与预期不符的重构方案。

原因很简单：Workflow 定义得再精妙，它执行的底层依赖仍然是模型对代码库的理解能力。项目代码越是腐烂，模型的"心智负担"越大，执行力也就越差。所以在引入 Superpowers 的同时，必要的模块边界治理还得跟上。

5. 我踩过的坑和完整排查链路

5.1 坑一：Skill 明明写了却不生效

第一次配置java-spring-controller技能后，我发现 Codex 生成的代码一点都没遵循技能里的约束——还是老一套的命名、老一套的注释风格。我第一反应是"技能加载失败"，于是重新执行初始化命令，又确认了工作目录正确，问题依旧。

后来我一步步排查，才意识到根本原因：我没有在技能名称前加上下文标识符。Superpowers 的 Skill 触发机制不是"当前目录下所有技能自动生效"，而是靠 Workflow 显式指定或会话中显式引用。也就是说，我在某个工作流里根本没挂载这个技能时，它就只是沉睡在技能仓库里，绝不会主动干预 AI 行为。

排查链路复盘一下：

1. 先看 Superpowers 的日志输出，确认技能是否被识别
2. 再看当前会话加载了哪些技能（命令里有一个list skills的调试命令）
3. 最后才意识到是 Workflow 定义里漏了依赖项

这个坑提醒我：技能和流程是两层东西，不要以为写了技能就等于启用了技能。

5.2 坑二：AI 陷入修 bug 的死循环

另一个让我几乎崩溃的问题是：AI 在"运行测试 → 失败 → 修复 → 再运行"的循环里出不来。有一次它连续改了四五版测试都没过，每次都是同一个失败点，但它像是"失忆"一样，每次都从同一个错误假设重新开始。

我观察了一个细节：每次修复时，AI 打开的文件、读取的日志内容都一样，说明它根本没有把前一次尝试的失败原因内化到上下文里。这是上下文管理的问题，不是 Superpowers 跑得不对。

我的解决思路有两步：

• 第一步，在 Workflow 里添加一个"失败分析"的 Step，让 AI 在每次修复前先输出"上一轮失败原因摘要"和"本轮改动假设"。这个要求会强制模型回顾刚才的失败，不再是无脑重试。
• 第二步，为测试执行环节设置最大重试次数（比如 3 次），超过次数后停止自动修复，回到人工确认点。这既保护了算力资源，也避免了 AI 在一堆错误方案里越陷越深。

加了这两个约束后，死循环的问题基本消失。我后来反思，这类问题并非 AI 能力不够，而是流程设计时没有考虑故障处理路径。任何工具、任何流程，只要没有"失败终止条件"，就会在异常场景下无休止地空转。

5.3 坑三：多项目切换时的"跨项目上下文污染"

我手上同时维护着两三个不同语言的项目：一个是 Java 后端，一个是 React 前端。某天我在 Java 项目里跑技能，生成出来的代码居然带了 TypeScript 的类型风格，还试图用.tsx扩展名写 Java 文件。这个现象一度让我怀疑是模型出现了幻觉。

但仔细排查后，发现是我自己的配置问题。Superpowers 的技能库是全局共享的，不同项目的专属技能如果带有完全相同的名称，后加载的那个会覆盖前一个。我当时没有给技能加上项目前缀命名，导致 AI 在加载"通用工具技能"时，把别的项目里的技能也混了进来。

解决办法有点笨但很有效：给所有项目级技能增加明确的项目前缀，例如java-orders-*、react-portal-*，同时在 Workflow 文件里显式声明该项目只允许引用哪些技能。这样就算技能库再大，AI 也不会拿错工具。

5.4 一个通用排查顺序

如果你也遇到"AI 行为完全不符合预期"的问题，我建议按这个顺序排查，大概率能快速定位：

1. 环境层：确认 Superpowers 版本与 AI CLI 的版本兼容，命令行能正常调用
2. 配置层：检查当前项目下是否有.superpowers配置文件，技能清单是否正确
3. 定义层：打开 Workflow 文件，确认当前任务挂载了哪些技能、技能名称是否拼错
4. 执行层：查看日志文件，确认是否在执行过程中抛了脚本错误
5. 上下文层：检查当前会话是否因为多项目切换混入了其他项目的技能

大多数"技能不生效"的问题，都出在第 3 层和第 4 层。少数情况是模型对技能说明的理解偏差，那就要回头在SKILL.md里写得更加具体。

6. 进阶玩法：把 Superpowers 真正变成自己的生产力工具

6.1 我的个人配置清单

用了大半年之后，我自己总结了一份相对稳定的配置思路，分享出来供你参考：

• 通用技能：只放那些跨项目都可用的。比如"写提交信息""检查 Git 冲突""格式化代码"这类。它们解决的是工作流层面的共性问题，不该绑定任何具体项目。
• 项目级技能：放在项目的skills/目录下，并在项目根目录的配置文件中显式引用。这样换电脑、拉新分支时也不用重新配置。
• Workflow 优先于手动指令：我现在的习惯是，任何重复性的开发任务都先想"这个能不能做成一个 Workflow"，而不是每次用大白话指挥 AI。初期搭建成本高，但一旦成型，后面每次执行都是纯收益。

下面是我常用的技能与 Workflow 的对应关系表：

6.2 团队协作：如何让队友也用起来

单人使用 Superpowers 是提升效率，团队普及才是真正的效率杠杆。我推行这套方式时遇到过不小的阻力，主要原因是小伙伴们的使用习惯差异很大，有人习惯 IDE 插件，有人依赖命令行。

我的做法是：

• 把技能定义和 Workflow 文件纳入 Git 仓库，放在项目目录下统一管理
• 在 README 里写明"建议安装"而不是"必须安装"，让工具自然渗透
• 定期组织简短的分享会，演示一次完整的 Workflow 执行过程，重点讲"它能帮你省哪些重复操作"

只要有一个人真正把 Workflow 用得顺手了，团队的接受度会很快上来。因为那种"自动跑测试、自动修 bug"的演示效果，比任何文档都更有说服力。

6.3 边界感：有些场景我不建议用 Superpowers

最后聊聊"不做什么"。

第一，不要试图让它接管所有代码审查。代码审查需要人的业务判断力和长期积累的直觉，这是 AI 工具目前最难替代的部分。Superpowers 可以帮你做静态检查、风格校验和变更影响分析，但"这个设计是否合理"这个问题，它回答不了。

第二，不要一上来就自动化重构成千上万行的老代码。无论是在老项目还是架构转型期，我都建议把重构的 Workflow 设计成"一步一步确认"的模式，而不是批量执行。AI 对大型代码库的全局理解和人的理解方式完全不同，一步走错，后果往往要花几倍时间收拾。

第三，不要把技能的描述写成"正确的废话"。比如"代码要高质量""遵循最佳实践"这类描述，对 AI 来说几乎等于没说。真正有效的技能描述，应该精确到命名规则、目录结构、错误处理方式、测试风格甚至工具版本。你在项目里积累的那些显性规范，才是技能文件里最宝贵的素材。

6.4 两条让技能更聪明的经验

如果你准备系统性使用 Superpowers，我再额外分享两个自己验证过的经验。

经验一：在技能里绑定实际例子。与其在SKILL.md中抽象描述"不要使用"和"要使用"的写法，不如直接放两个代码片段对比。AI 从具体例子中学习的有效性远高于抽象规则，这和人看文档的体验类似。

经验二：让技能里的脚本承担"结果验证"职责。不要只告诉 AI "应该怎么做"，还要让它能在完成后自我检查。我在技能里加过一个脚本，专门检查新生成的 DTO 字段是否都有序列化注解、测试类是否包含@WebMvcTest等。这些脚本不复杂，但能让 AI 在提交输出前多一道自我质检，整体质量还有明显提升。

写在最后的一点体会

在使用 Superpowers 的这小半年里，我最深的感受是：AI 编程工具的真正价值，也许不在于你 prompt 写得多花哨，而在于你为 AI 设计的一套可重复的生产流程是不是足够合理。Superpowers 把"Skill + Workflow"这两个概念做成了工程实践，让 AI 从"一个聪明的实习生"变成了"一个服从你流程的熟练执行者"。

我知道很多人对这类工具的第一反应是"又给 AI 套了一层壳"。但如果你连续几周在一个真实项目里依赖它开发新接口、排查测试、强制执行代码规范，你会发现这层"壳"恰恰是 AI 能力真正落地的关键。就像一台好相机，机身再强大，没有一套拍摄流程和镜头体系，同样拍不出好片子。

如果你也在用 Codex 或类似的 AI 编程助手，我建议你给自己的项目写一枚最刚需的技能试试。不用多，就挑一个你每周都要做、但每次都要重复交代的简单任务。等你体验到"一句话驱动完整开发流程"的顺畅感后，大概率会像我一样忍不住把所有重复性工作都逐步流程化。