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 里能找到的而是实际动手才会遇到的列出来给大家避雷。现象大概率原因解决方案启动 Codex 后技能列表为空AGENTS.md 没有生效或技能目录路径配错检查~/.codex/config.toml里的 extra 配置确认 skills 目录路径正确技能执行到一半就停了技能 markdown 里的步骤有歧义模型不知道下一步把步骤改得更结构化每步加明确输出物频繁出现重复操作或死循环技能的验收标准太模糊模型不知道“何时算完”在验收标准中加入可量化的命令和条件比如“mvn test 全绿”代码里出现跨层设计不一致缺少设计规划技能直接进入了实现阶段在代理中先调用 planning 技能生成任务拆解和设计说明安装脚本报 npm 权限错误Node 版本太旧或 npm 全局权限异常升级 Node.js或改用 npx 方式运行脚本Codex 不按流程走自由发挥会话上下文太长AGENTS.md 被忽略新开会话或拆分任务不要在一次对话里塞太多需求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 文件还是团队的模板仓库。这个积累本身就是一种长期资产以后不管底层模型怎么换这套工作流设计都还能用。
