Codex CLI 折腾了大概半个月之后，我基本把日常的终端 AI 编程工作流整个迁移到了 superpowers 上。这个项目严格来说不是一个“插件”，也不是一个“框架”，它更像是一套给 AI 编程助手用的“技能扩展包 + 协作方法论”。如果你现在还在用对话式一问一答的方式让 Codex 帮你写代码，那你大概率会遇到同一个瓶颈：它在单步任务上很强，但一涉及多文件、多步骤、需要前后一致性的活，马上就拉胯。superpowers 就是冲着这个问题来的。

我最初是在 Twitter 上看到不少人把 superpowers 和 codex 放在一起讨论，后来搜了搜发现相关的使用教程、安装指南已经形成了一个小生态。它解决的痛点是真实存在的：AI 编程助手如果只是“你问一句它答一句”，那本质上就是一个高级补全工具；而如果你让它按照一套可复用、可编排的“技能( skill )”来工作，它就能像一个真正的初级工程师那样，按任务清单推进、主动写测试、自己修复报错、甚至完成跨多个文件的重构。这篇就从头到尾聊清楚 superpowers 是什么、怎么安装、怎么用、以及我这一路踩过的坑。无论你是刚听说这个项目还是已经在 GitHub 上看过一眼，这篇应该都能给你省下不少时间。

我个人会尽量用“实操过后的经验”来写，而不是把 README 翻译一遍。文里会有不少我自己的使用习惯和取舍，不是标准答案，但你可以直接抄作业。

1. 先搞清楚：superpowers 到底解决了什么问题

1.1 原生 Codex 会话模式的天然短板

先聊一个大家可能都经历过的事。你用 Codex CLI 让它“写一个 Java 的 REST 服务”，它确实能写；但如果你追加一句“顺便把单元测试补上，再跑一遍构建”，它就开始犯浑了：要么忘记你前面的目录结构，要么生成的测试跟实现驴唇不对马嘴，要么在同一个会话里反复横跳，一会儿说“好的我改”，一会儿又“按照之前的设计，我们应该……”。

这不是模型不行，而是会话模式本身缺少“结构性约束”。一次开发任务往往包含需求分析、任务拆分、骨架搭建、具体实现、测试、联调、修复、重构等十几个环节，每个环节对模型的上下文要求不一样。如果你不加约束地全塞在一个对话流里，模型很难维持清晰的边界感，更别说让它在断点之后恢复工作了。

superpowers 的基本思路就是：把开发过程拆成一个个带明确目标、明确输入输出、明确验收标准的“技能”。这些技能不是模型自己随机发挥出来的，而是你通过配置文件和提示词模板预先定义好的。Codex 要做的，只是按照技能脚本去执行——有点像你把一个实习生要做的事情写成标准作业程序( SOP )，然后让 AI 照着走。

1.2 superpowers 的解题思路：技能不是提示词，是流程

很多所谓的“提示词工程”只是把一大堆指令塞给模型，本质上还是“一次性发挥”。superpowers 的做法不一样，它把流程变成可复用的技能包。每个技能包含几个要素：

• 技能名称和触发条件，比如“create-ts-project”负责创建 TypeScript 项目骨架；
• 一个结构化的任务清单，步骤之间前后依赖，逐步推进；
• 对应的执行脚本或命令，比如调用 git、运行测试、生成文件等；
• 明确的验收标准，做完之后要检查哪些东西，不满足就循环修复。

这种设计相当于给你的 AI 助手配了一整套“工具箱”和“使用手册”。它不再是自由发挥，而是按你定义好的最优路径来干活。如果你给它一个复杂的需求，它会主动调用多个技能，按顺序组装成一个完整的工作流。

从实际效果看，这种结构的最大收益是可重复性和可调试性。以前 AI 写崩了，你只能对着聊天记录复盘；现在它执行了哪个技能、跑到了哪一步、哪一步的验收没过，全都一目了然。出了问题，改对应的技能定义即可，而不是重新调一轮对话。

1.3 为什么偏偏是“superpowers”这个项目

其实类似思路的工具不少，像 GitHub 的 Copilot Workspace，或者各种 Agent 框架，都在往“多步骤自主执行”方向上走。但 superpowers 有一点很不一样：它的切入点非常轻量，就是基于 Codex CLI 的能力，做了一层标准和流程的封装，不重不复杂，你完全能看清每一步在干什么。

有些人可能会问，直接用原版 Codex 再配一个经典的大 prompt 不就行了吗？实测下来还真不行。Prompt 再长，模型还是会跑偏，因为缺少“结构性反馈”——它不知道当前做的这步是不是符合预期，更不知道要不要停下来修正。而 superpowers 通过技能内部的自检逻辑，让模型在当前技能未达到验收标准时不能往下走，形成了一个“小闭环”。这个“技能内闭环”是它效果好于纯 prompt 的本质原因。

所以我的建议是：不要把它当成一个“提示词合集”，要当成一个“流程框架”来理解。理解到这个层次，你后续使用才会顺手，改起来才有方向。

2. 安装部署与核心概念拆解

2.1 环境准备：先把 Codex CLI 跑通

在动 superpowers 之前，你机器上得先有一个正常的 Codex CLI 环境。这块我踩过一次坑，就是 Codex CLI 的登录态和网络问题——如果你在本地连代理都没配好就急着装 superpowers，后面会遇到一堆莫名其妙的报错。这里不展开讲代理细节，但至少要保证：先用原版 Codex 跑通一个简单对话，确认它能正常发送请求。

具体环境要求有几点：

• Node.js 版本建议 18 以上，有些技能脚本用到了较新的原生 API，版本太老会报错；
• Git 必须可用，很多技能的第一步都是git init或者读当前仓库状态；
• 操作系统方面，macOS 和 Linux 都行，Windows 的话建议直接用 WSL2，原生 PowerShell 里不少 shell 命令会出问题；
• 如果你准备让 AI 跑 Java 项目，那 JDK 和 Maven/Gradle 也得是能直接从命令行调用的状态。

提示：安装完 Codex CLI 之后，先在一个空白目录里跟它随便聊两句，确认命令行交互正常。不要跳过这一步，否则后面你会分不清问题是出在 superpowers 还是 Codex 本身。

2.2 安装 superpowers 的具体步骤

superpowers 的安装分两部分：一个是它的核心代码仓库和配套技能脚本，另一个是它需要初始化生成的配置目录。以我这次实操为例，整个过程分三步：

第一步，从 GitHub 把项目 clone 下来。我习惯把它放在~/.superpowers这样的目录里，方便统一管理：

git clone https://github.com/obra/superpowers.git ~/.superpowers

第二步，安装依赖并初始化配置。项目里有现成的安装脚本：

cd ~/.superpowers npm install npm run setup

这一步会干几件事：在~/.codex目录下生成或更新config.toml，写入一些 codex CLI 的推荐配置；同时把 skills 相关的配置目录结构建好。装完建议看一眼终端输出，确认没有权限类报错。

第三步，验证安装。在任意项目目录里启动 codex，输入“你有哪些可用技能”，正常情况下它应该能列出 superpowers 自带的那些技能名称。如果它回答不了，多半是 AGENTS.md 没有生效或者配置目录没写对。

注意：如果你之前已经改过~/.codex/config.toml，跑npm run setup之前建议先备份一份。这个脚本会自动追加配置，万一跟你已有的自定义项冲突，还能回滚。

2.3 三个必须先弄懂的核心概念：技能、代理、工作区协议

安装很容易，但会用又是另一回事。我建议在动手之前，先弄懂三件事。

技能( Skills )：这是 superpowers 的原子单位。一个技能就是一套“目标 + 步骤 + 验收标准”。sills 目录下都是 markdown 文件，内容本质上就是写给人看的提示词，但结构非常严格。frontmatter里会写明技能的 name、description、触发场景，正文里则包含workflow、steps、acceptance criteria这些小节。Codex 读这些 markdown 的时候，会把它当成“工作指导书”来执行。

代理( Agents )：技能可以组合成代理。比如说你可以定义一个“fullstack-dev”代理，它内部调用“ts-project-scaffold”技能来搭项目，再调用“api-design”技能来设计接口，再调用“test-generation”技能去补测试。代理是一个更高层的概念，适合你把一整个角色或者一整套工作流绑定到一起。

工作区协议( Workspace Protocols )：这个不难理解，就是 AGENTS.md 文件怎么去链接到技能定义。superpowers 的项目里有一个AGENTS.md，里面会指引 Codex 去读取skills/目录下的内容。当你新起一个项目时，也需要在项目根目录放一个AGENTS.md，告诉 Codex 项目的工作流约定和可用的技能入口。

这三个概念之间的关系，你可以这样理解：技能是“最小可执行单元”，代理是“多个技能的组合编排”，而 AGENTS.md 是“触发这些编排的入口”。Codex 每次启动的时候，会先读 AGENTS.md，然后按里面的指引去加载技能，再根据你的指令选择合适的技能开始干活。

3. 实操：用 superpowers 驱动一个真实项目

3.1 案例背景：从零做一个 Java 后端服务

为了把流程说透，我用一个贴近常见工作的场景来演示：做一个简单的用户管理 REST 服务，Java + Spring Boot，包含用户注册、查询列表、删除用户三个接口，写单元测试，最后本地构建通过。

这个场景是我专门挑了来对应“superpowers java”这个热词的，里面会涉及多文件生成、接口设计、测试补齐、构建修复等多次上下文切换，正好能展示 superpowers 的编排能力。

项目初始化之前，我先在本地建了一个空目录，放好 AGENTS.md，内容大概是：

# Project Context This is a Java Spring Boot project for user management. ## Skills Refer to the skills defined in ~/.superpowers/skills for implementation guidance. Preferred skills: java-service, test-generation, error-debugging.

这段内容的意义在于告诉 Codex：这是一个 Java 项目、应该参考哪些技能、优先级是什么。有了这段声明，后面所有会话都会自动加载对应的技能少，少走很多弯路。

3.2 从需求到实现：一个典型的多技能工作流

我把需求发给 Codex，原话大概是：“我要一个用户管理服务，基于 Spring Boot，提供用户注册、列表查询、删除接口，然后补单元测试，最后 mvn test 全绿。”

如果是在原生 Codex 里这么问，它大概率会一顿输出，能不能达到“全部测试通过”的结果，要看运气。但在 superpowers 的框架下，它不会直接闷头开写，而是会把需求拆分，然后按技能顺序来。下面是我观察到的实际执行序列：

第一步，调用类似“planning”的技能，把需求拆成任务清单，并为每个任务标注验收标准。它生成的清单大致是：

• 创建 Maven 项目结构（pom.xml、application.yml、主启动类）；
• 实现用户实体和内存存储仓库；
• 实现 UserController 和 UserService；
• 编写针对 service 层的单元测试；
• 执行 mvn test，修复报错直到全绿。

第二步，进入 java-service 技能，创建项目结构和核心代码。这一步它会逐文件写入，每写一个类就停下来检查是否符合该技能定义的代码风格。

第三步，调用 test-generation 技能，补测试。这个技能执行的时候，它会先读取已有的代码文件，分析哪些方法需要测试、边界条件是什么，然后生成对应的 JUnit 测试。关键点是：它不只是“写几行测试意思意思”，而是真的会给每个方法覆盖正常路径和异常路径。

第四步，进入 error-debugging 技能，跑mvn test，如果失败就一遍遍读报错信息、修复、重跑，直到通过。这一步我统计过大概花了四轮循环，主要原因是我故意在需求里埋了个“用户 ID 由调用方传入”的设计歧义，导致 service 层和 controller 层对 ID 生成逻辑理解不一致。这类跨层不一致的问题，在纯对话模式里最容易翻车，但通过技能定义里的“验收标准”环节，Codex 能很快意识到测试失败，并主动定位到是哪一层的问题。

整个流程跑完，项目目录结构大约长这样：

user-service/ ├── AGENTS.md ├── pom.xml └── src/ ├── main/java/com/example/userservice/ │ ├── UserServiceApplication.java │ ├── controller/UserController.java │ ├── service/UserService.java │ └── model/User.java └── test/java/com/example/userservice/ ├── UserServiceTest.java └── UserControllerTest.java

我在旁边的终端记录了一下，从发出需求到 mvn test 全绿，整个过程大约持续了几分钟，中间没有人工干预。这个结果如果放到没有 superpowers 的 Codex 里，很难一次跑通，原因前面已经说过了：缺少流程约束。

3.3 关键细节：为什么“测试驱动”在这里如此重要

细心的朋友可能注意到，整个工作流里我最强调测试环节。这一点我想单独拎出来说，因为它直接决定了这套方案的可靠度。

superpowers 的很多技能里把写测试放到了写实现之后、修复循环之前，这跟传统 TDD 的顺序不完全一样，但目的是一致的：给 AI 的工作结果一个“客观判定标准”。模型自己判断代码好不好，本质上是主观的、可忽悠的；跑一遍测试，通过就是通过，不通过就是不通过，没有任何商量余地。

我见过有的用户试图跳过测试环节，直接用“代码写完就行”这种说法，结果就是 AI 生成了大量表面上完美、实际上根本无法编译的代码。一旦你用mvn test或者npm test这种硬性验收命令卡住 AI，它的错误率会明显下降。原因也很朴素：模型在生成代码时，知道下一步会被测试验证，所以生成时会更谨慎，会更注意方法签名、包名、依赖版本这些容易被忽略的细节。

所以我的强烈建议是：自定义技能时一定要带一个“验证命令”步骤，越硬越好。没有验收的技能就像没有及格线的考试，AI 怎么发挥都算对，那效果就完全不可控了。

3.4 如何定义自己的技能：以“java-service”为例

如果你不想只依赖项目自带的那些通用技能，完全可以自己定义一个。我把自定义技能的方法说一下，不难，但有几个注意点。

在 superpowers 项目里，技能就是一个 markdown 文件，放在合适目录里就行。比如我自定义了一个“java-service”技能，文件名是java-service.md，结构大致如下：

--- name: java-service description: Create a Java Spring Boot service skeleton with standard package layout. --- ## Overview This skill generates a new Java Spring Boot service. ## Steps 1. Read the current project structure. 2. Create a Maven project with standard src/main/java and src/test/java layout. 3. Generate pom.xml with spring-boot-starter-web dependency. 4. Create the main application class, controller, service, and model classes. 5. Generate JUnit tests for service layer. 6. Run mvn test locally and fix any failures. ## Acceptance Criteria - The project can be built with `mvn test`. - All tests pass. - The generated class packages match the configured base package.

这里最关键的一点是 Steps 要写得足够具体，不能写“实现用户接口”这样模糊的话，而要把“做什么”“按什么顺序做”“做完怎么验证”全部写清。模型不是人，它不会脑补隐含步骤。

另外一个很容易犯的错是：把多个技能揉在一个 markdown 里。我一开始图省事，把所有 Java 相关的东西全塞在一个大文件里，结果模型执行时经常出现步骤错乱。后来拆成java-service、test-generation、error-debugging三个独立技能，配合代理来组合调用，效果一下子就好了。

从我的经验来看，一个技能文件最好只解决一个焦点问题。如果一个技能的操作步骤超过 8 步，就说明它该拆了。技能拆得越小，复用性越高，Codex 的把握也越大。

4. 常见问题与排查技巧实录

4.1 问题速查表：我遇到过的 6 个高频问题

装和使用 superpowers 的过程中，我整理了一批高频问题。这些问题不是官方 FAQ 里能找到的，而是实际动手才会遇到的，列出来给大家避雷。

4.2 排查思路一：为什么我的技能没生效

这是被问得最多的一个问题。很多人装完 superpowers，输入“你有哪些技能”得到一长串回答，看起来一切正常，但真正干起活来时，Codex 的行为跟没装一样，完全不听技能的约束。这个情况我遇到过两次，排查后又两个结论。

第一是工作目录里没有 AGENTS.md。很多人习惯在全局配置里设置了技能路径，就以为所有项目都能自动生效。实际上 Codex 对项目上下文的加载是基于当前工作目录的，没有 AGENTS.md 文件，技能目录再完整也触发不了。解决办法很简单：在项目根目录放一个 AGENTS.md，里面显式声明要加载的技能。

第二是 AGENTS.md 里的技能描述方式有问题。如果只是简单写一句“Use the skills”，模型可能理解不到“必须按照技能里的步骤来执行”这个强度。我的建议是在 AGENTS.md 里写清楚“Follow the workflow steps defined in the skill; do not improvise”。措辞上的细微差别，对模型行为的约束力影响很大。

4.3 排查思路二：代码质量不稳定时的三板斧

如果用了 superpowers 之后发现代码质量时好时坏，别急着换工具，先做三个检查。

检查技能文件最近的改动。技能文件就是“程序”，你的任何调整都可能影响输出质量。我每次改了技能，都会去跑一个预置的验证任务看结果是否回归，避免改坏了没发现。

检查是否混入了多个互相冲突的技能。比如我曾在同一个项目里让一个技能负责“创建项目”，另一个也负责“创建项目”，结果两个技能轮番上阵，搞出来两套目录结构。遇到冲突时，最省事的办法是把职责重叠的技能合并或者禁用一个。

检查验收标准是否真的“硬”。如果技能的验收标准只是“代码看起来没问题”，那模型大概率会给自己放水。把验收标准改成命令和断言，比如“运行mvn test且失败数为 0”，模型就知道没有糊弄空间了。

4.4 关于 Token 消耗和资源占用，我有一些实在话

superpowers 的每个技能都会让模型多跑一些步骤，Token 消耗比“直接问答”高不少，尤其是跑测试修复循环时，每次失败都会重新读一轮错误信息。以 Java 项目为例，一次完整的多技能开发流程，Token 消耗大概是直接问答模式的三到五倍。如果你用的是付费 API，这个成本要提前有数。

然后我实际体验下来，这笔消耗是值得的。因为直接问答模式看似便宜，但代码返工率高，前后算总账并不划算。真想在预算内跑更多次数，更省的办法是：把技能设计得更收敛一些，每个技能只做分内的事，不要动不动就全局扫描项目。另一种是开发时先跑一个最小规模的技能子集，等逻辑稳定后再跑完整流程。

5. 我的使用经验与进一步扩展思路

5.1 渐进式引入是最好的上手方式

如果你刚开始接触 superpowers，我强烈建议不要一上来就改一堆自定义技能。我自己的路径是先直接用项目自带的技能跑了两三个项目，搞明白内置技能的执行逻辑和长处短处之后，才开始动手写自己的技能。这个过程有点像你先用别人的工具干活，干顺手了，你自然知道工具哪里不好用、哪里需要改进。

具体节奏可以这么安排：第一周只装好环境，使用默认技能做小型任务；第二周开始尝试用代理组合多个技能，解决中型项目；第三周再修改内置技能，加入你自己的项目规范和验收标准。每加一个自定义技能，先在一个临时项目里单独验证，别直接投产到正式项目里。

5.2 为团队统一 AI 工作流的可能性

我后来还给团队做了一套统一的 AI 开发规范，把 AGENTS.md 和技能模板都放进了项目的 templates 仓库里。新成员拉下来一个项目，Codex 会自动加载团队预设的技能流程，写出来的代码风格、命名习惯、测试覆盖要求都能对齐。

这件事的价值比想象中大。以前团队引入 AI 编程，每个人都用自己的一套 prompt，代码风格五花八门，评审的时候很痛苦。有了 superpowers 做底座，你甚至可以像写工序卡一样，把团队的编码规范固化进技能里。AI 不再是“会用但没法管”的工具，它可以被纳入工程化体系。

5.3 关于未来：技能生态会成为新的插件体系

最后聊一点我的个人预判。superpowers 这类项目的出现，让 AI 编程从“模型能力竞争”逐渐转向“流程工程竞争”。模型本身的能力会越来越同质化，但你怎么定义流程、怎么组织技能、怎么设计验收标准，将会成为每个团队差异化的部分。

这可能真的会成为 AI 时代的“插件体系”——就像当年的 IDE 插件一样，技能会变成一个可以被分享、被复用、被交易的东西。今天你手写的 java-service 技能，明天可能就会有人把它打包成“Java 后端开发包”发布到某个共享平台。到那时候，拼的不只是谁会用模型，更是谁定义的标准更高效。

在这之前，我建议你先把自己的技能积累起来，不管是本地的 markdown 文件还是团队的模板仓库。这个积累本身就是一种长期资产，以后不管底层模型怎么换，这套工作流设计都还能用。