最近在开发者圈子里“superpowers” 这个词被反复提起。说的不是美漫里的超能力而是一套给 AI 编码代理做技能增强的开源工具链。我花了两周时间把它的安装、初始化、日常任务流程完整跑了一遍还专门拉了一个 Java 后端项目试水。这篇不打算写成复制粘贴就完事的教程而是把它的核心机制、真实踩坑经历以及和 Codex 这类命令行编码工具搭配使用的思路一次讲清楚。如果你正在用 Codex、Claude Code 这类工具你大概率体会过一种很微妙的状态它们有时聪明得吓人三两句就能写出能跑的代码更多时候却手忙脚乱拿到需求直接开干不测试、不问边界、不写计划。superpowers 解决的核心问题一句话给代理装上一套可复用的工作方法让它们像资深工程师一样先规划、再动手、最后复盘。谁适合看这篇第一类已经在用编码代理但对结果随机性不满意的开发者第二类想把团队代码规范、测试策略真正落到 AI 辅助开发流程里的工程效率负责人。后面的操作细节我会尽量兼顾两类读者的需要。1. 先搞清楚superpowers 到底是给谁用的1.1 点破核心痛点AI 编码代理缺的不是算力是流程我用了很长一段时间的各种 AI 编程工具逐渐意识到一个规律大模型的单点能力确实强解释一段陌生代码、补一个工具函数、翻译报错信息它干得很漂亮。可一旦你给它一个需要拆解成多个步骤的任务它就开始飘。不是它学不会而是缺少稳定可靠的操作流程。举一个我实际遇到的例子。我让代理在一个 Java 项目里新增订单状态流转功能它不到十秒就吐出一大段代码状态机、事件、异常处理全都有。乍一看非常完整仔细一查问题全在流程上没有先确认状态流转规则直接把“已取消”和“已完成”之间也连了边没写测试异常路径没定义回退策略。它写出了一段语法正确、设计混乱的代码。问题出在哪大模型本质上是在做“最有可能的下一个 token”的续写代码补全、注释生成是它的舒适区但“按顺序做一件事的逐步流程”不是它的默认行为。你让它一口气实现它就顺着惯性把代码堆出来。superpowers 的做法很朴素把工程师的工作习惯写成技能文档让代理在合适的场景自动加载。文档里写明触发条件、执行步骤、检查清单代理照着走。这就好比新员工入职。新人智商没问题但没经验不知道什么时候该停下来问需求、什么时候该先写测试、什么时候该重构。superpowers 就是那份入职 SOP 手册。它不是教模型变聪明而是让模型每次都能按成熟流程办事把结果的不确定性压下来。1.2 核心机制拆解skills、initializers 与系统提示词我第一次看 superpowers 的目录结构有点懵文件不少。理清楚之后发现核心机制其实只有三个技能文件、初始化器、系统提示词注入。机制作用典型文件触发方式skills 技能文件定义某一类场景的完整工作流程brainstorming.md、tdd.md代理判断任务匹配描述时加载initializers 初始化器指导代理首次装配能力init-skills.md用户要求初始化时执行系统提示词注入让代理知道存在哪些能力CLAUDE.md / AGENTS.md每次会话启动时自动加载技能文件是核心。它一般用 Markdown 编写顶部带 YAML frontmatter写清楚技能名称和适用场景描述正文写步骤。为什么用 Markdown因为它既给机器读也给人读还能放进 git 做版本管理。团队里谁改了技能内容diff 一目了然比口头传递规范靠谱得多。初始化器是稍特殊的一类技能。它解决的场景是“代理第一次开工不知道怎么组织自己”。你在对话里要求初始化它会扫描当前环境、检查技能清单、把缺失的能力补全然后告诉你准备好了。这一步相当于给代理做了入职培训。系统提示词注入最容易被忽略但恰恰是最关键的一环。安装脚本会在代理配置里追加一句说明告诉代理“你拥有以下技能对应场景请主动使用”。没有这句话技能文件就算堆满目录代理也不知道何时调用。我调试过不少案例最后都是卡在“系统提示没写好”上。还有一个容易忽略的约束上下文窗口是有限的。技能文件如果写得又臭又长会挤占编码时真正需要的信息。所以 superpowers 体系里的技能全都要求精炼、结构化、直接可执行。2. 环境准备与安装5 分钟跑通 superpowers2.1 前置依赖确认Node、Git 与终端环境先说结论superpowers 对运行环境的要求不高。它本质上是一组 Markdown 文件和装配脚本不需要单独启动服务也没有数据库装完就像往抽屉里放进一份员工手册。你只要准备几样基础工具就行。Git 是必须的因为安装目前还是要从仓库拉代码。终端环境建议用 bash 或 zshWindows 下推荐 WSL 或 Git Bash纯 CMD 环境我不太建议折腾脚本行为不确定。如果你要接 Codex CLI 或 Claude Code那对应的 CLI 要先装好能跑起来。Node 不一定硬性需要但有些辅助脚本可能会用到装一个 LTS 版本不吃亏。我在实际操作前有个习惯先在一个临时目录里验证环境没问题再往主配置目录里写东西。你可以在终端敲git --version和curl --version能正常输出版本号前置就算过了。这一步花三十秒能省掉后面一堆“为什么装一半报错”的烦恼。2.2 安装脚本实操与目录结构说明我的安装过程是直接从官方仓库拉代码然后执行 setup 脚本。流程如下你可以直接抄git clone https://github.com/obra/superpowers.git cd superpowers ./scripts/setup.sh执行完以后安装脚本会把技能文件复制到当前用户的代理配置目录下。我这边装好之后的目录结构大致是~/.claude/ ├── CLAUDE.md └── skills/ ├── brainstorming.md ├── writing-plans.md ├── test-driven-development.md ├── debugging.md └── code-review.md如果你用的是 Codex 这类支持 AGENTS.md 的 CLI配置目录可能是~/.codex/或项目根目录下的.codex/。这里有个高频踩坑点不同代理读取技能文件的根目录不一样。安装脚本默认按自己的约定装你要根据自己的工具做调整。为了接 Codex我当时手动把技能文件复制到了 Codex 的配置目录并改了配置内容。注意项目更新后目录结构可能调整。安装前建议快速扫一眼仓库 README 的最新说明。我当初就是拿着旧文章里的路径去对结果对不上白折腾了十分钟。Windows 用户如果遇到Permission denied先检查脚本有没有执行权限用ls -l scripts/setup.sh看权限位没有 x 就补一下chmod x scripts/setup.sh。这个坑在 WSL 里特别常见。2.3 验证是否安装成功三项检查装完不要急着关终端做三个检查就能确认状态。第一看技能文件有没有落盘ls ~/.claude/skills/或者你对应的配置目录能看到一堆 .md 文件就算成功。如果文件一个都没有优先怀疑脚本没完整执行或者执行路径不对。第二看配置文件有没有写入说明打开 CLAUDE.md 或系统提示文件里面应该有一句类似“当你需要制定计划时使用 writing-plans 技能”的描述。没有这段说明后续代理不会主动调技能。第三启动代理问一句“你现在有哪些技能” 如果它能列出 brainstorming、TDD、code-review 这些名字说明技能已经进了上下文。这一步是性价比最高的验证因为很多问题最后都出在“文件装了但代理不知道”。3. 核心实操初始化能力并驱动 Codex 干活3.1 用初始化器给代理装“吃饭的本事”安装完只是第一步。真正让代理“学会”这套技能体系还要跑一次初始化。我最初犯的毛病就是装完就觉得完事了结果一问三不知折腾半天才发现少了初始化这步。初始化操作很自然在对话框里直接说“请使用 superpowers 初始化你的工作流。” 或者简单一点“你有 superpowers 技能吗有的话请初始化。”代理收到指令后会读取系统提示里关于 superpowers 的说明然后按初始化器的步骤走一遍。它会检查当前环境、确认技能清单、补全缺失能力最后告诉你准备好了。这个过程会消耗一些对话轮次因为代理需要把技能文件内容加载进上下文完成自我装配属于正常现象。我强烈建议初始化完成后让代理把当前可用技能列个清单给你自己留一份底。后面调试“某个技能为什么没触发”时这就是排查基准。没有这个基线你会陷入“到底是我指令不对还是它没装上”的混沌状态。初始化还有个作用它会纠正代理对自身能力的错误认知。有一次我初始化前问代理“你会不会 TDD”它答得模棱两可初始化之后再问它能直接给出 TDD 的标准循环红-绿-重构。这个变化让我确信初始化不是形式主义而是真正把代理拉进了正确的工作轨道。3.2 Java 场景实战让 superpowers 辅助写一个模块很多人搜“superpowers java”应该是想知道它在 Java 项目里怎么落地。我拿一个订单折扣计算模块的实际过程给你完整还原一遍你就能看出它的工作方式。第一步需求澄清。我在对话框输入“请使用 brainstorming 技能帮我梳理订单折扣计算模块的需求边界。重点讨论输入参数、折扣叠加规则、异常情况。”代理进入澄清模式不写代码先反问。它问的是折扣是否可以叠加满减和折扣券是否同时生效折扣率是否可能大于 1这些全是以前容易漏掉的细节。聊完之后需求边界被压缩到几句话输入是订单金额和折扣配置输出是实付金额规则是满减和折扣券不可同时使用异常输入抛出参数异常。第二步制定计划。我接着说“请使用 writing-plans 技能基于刚才讨论的需求输出一份实现计划包含模块划分、接口定义、测试策略。”代理产出了一份结构化计划测试策略拆到了方法级别。比如“金额小于等于 0 时抛异常”“满减阈值边界值测试”“折扣率等于 0 时跳过计算”。这一步的价值是给后续编码装上轨道代理不容易跑偏。第三步TDD 实现。这一步是整个流程的重头戏我会给出明确指令让代理严格遵守先测试、后实现的节奏“按 TDD 流程实现这个模块。先写失败测试再写实现最后跑通测试。”代理创建一个 JUnit 测试类先写一个失败的测试比如“原价 120 元满 100 减 20实付应为 100 元”然后补实现代码跑mvn test让它转绿。我特意在测试里加了一个例子原价 120、满 100 减 20、再打 9 折如果先满减后打折是 90 元如果先打折后满减是 88 元。代理在澄清阶段就把“先满减后打折”定成了规则所以实现时直接按这个顺序写。如果没有流程约束代理很可能会随手选一种将来上线才发现跟运营预期不一致。第四步自检复盘。测试跑通后我要求“请使用 code-review 技能审查刚才的代码指出潜在问题。”它会从并发、异常、可读性过一遍还真揪出过一个边界问题折扣率为 0 时要不要跳过计算逻辑。这个问题不是它编的是真实存在的我之前还真没注意。整个流程下来最大的感受是代理不再是想到哪写到哪每一步都有产出物而且过程可回放。这套流程不绑定 Java换成 Python、Go、前端节奏完全一致只是测试命令不同。3.3 组合拳Codex 配置与 superpowers 的协作要点再说“codex superpowers”这个组合。Codex CLI 本身的对话能力很强但要跟 superpowers 结合需要一点配置。核心思路是让 Codex 知道技能文件在哪、什么时候用。我手头版本的典型做法是把技能目录复制到 Codex 能读取的配置路径下然后在说明文件里写上技能清单。具体路径版本之间差异挺大有的读项目根目录的 AGENTS.md有的读用户主目录下的全局配置。我建议先用codex --help或者直接翻官方 README确认它的配置路径再决定复制到哪。如果你不想折腾目录映射还有另一个更稳的玩法直接把技能内容粘贴进对话。比如我遇到复杂需求就把 writing-plans 的步骤贴给代理要求它按流程执行。这种方式不优雅但存在感极强代理想忽略都难。适合临时用一次的场景。还有一点提醒Codex 的上下文窗口不是无限的。把十几个技能一股脑塞进去会挤占写代码时真正需要的信息。我的处理方式是按任务类型动态喂这轮写测试就喂 TDD下轮重构再喂 code-review。上下文利用率高了代理的输出也稳定很多。4. 常见问题排查真实踩坑实录4.1 命令找不到 / 权限不足先说最基础的跑完 setup 后执行命令报command not found: superpowers。大概率是脚本没有生成可执行文件或者生成了但没进 PATH。解法有两个一是找到安装目录做软链接到/usr/local/bin二是干脆不依赖全局命令直接用绝对路径执行。问题不大但特别容易吓到第一次接触的人。权限问题也很典型尤其从 Windows 切到 WSL 或 macOS脚本没有执行权限时报错是Permission denied。处理方式就是补权限chmod x scripts/setup.sh再跑一次。这类问题属于环境问题不是工具本身的问题排查方向别搞反。4.2 技能文件存在但代理不认更隐蔽的问题是文件明明在 skills 目录里代理就是不加载。我踩过一次原因是系统提示文件里没有提到这些技能。代理默认不会主动扫描技能目录它只按上下文里写明的规则行动。所以系统提示里的描述要写清楚触发条件比如“当用户要求制定实现计划时使用 writing-plans 技能”。还有一种情况是技能文件放到了代理根本不会读的目录。这种最坑表面看文件都在实际代理看不见。我的排查经验是直接问代理“你有哪几个技能”如果它一个都说不出来大概率是路径问题而不是技能内容写错了。别在技能正文上反复改先确认路径和系统提示。4.3 自定义技能的正确写法与调试方法掌握了别人的技能你大概率会想写自己的。自定义技能核心是 Markdown 格式我这儿给你一个通用模板--- name: api-design-review description: 当用户要求设计或审查 REST API 时使用 --- # API 设计审查 ## 步骤 1. 列出接口路径、方法、请求响应结构 2. 检查命名规范与 RESTful 风格 3. 确认鉴权、限流、幂等性设计 4. 输出问题清单和改进建议写完放进技能目录再在系统提示里追加一句“当用户要求设计或审查 API 时使用 api-design-review 技能”。调试时直接在对话里触发场景观察代理有没有调用。没调用就检查 frontmatter 拼写检查 description 是否容易被检索到。这个小循环相当于给技能做单元测试我建议正式用之前先在测试目录里跑一遍。下面是一个常见问题速查表方便你遇到问题时快速定位症状可能原因处理方式命令找不到可执行文件未进 PATH创建软链接或用绝对路径执行脚本权限不足文件没有执行权限chmod x 补权限代理不知道技能系统提示里没写技能清单在 CLAUDE.md/AGENTS.md 中补充说明技能文件在但不生效放错目录确认代理实际读取的配置路径自定义技能不触发frontmatter 或描述不准确检查 name/description精简触发条件5. 个人心得与后续扩展5.1 让我效率提升最明显的三个习惯两周体验下来我逐渐认同一个观点superpowers 不是那种装上就能变强十倍的神器它是那种逼着你和代理都变得有章法的工具。让我效率提升最明显的其实是三个习惯。第一个习惯强制先写计划再动手。以前让代理写模块它经常直接把代码糊上来现在我会先调 brainstorming 和 writing-plans把需求边界和测试策略聊透。表面看多花几分钟返工却少了一大截。这个算账方式值得每个团队算一遍。第二个习惯把团队规范沉淀成技能文件。我们团队有一份代码风格约定和发布检查清单以前靠人肉记现在写成技能放进共享仓库。谁用代理干活代理就会自动带上规范。这东西的价值比让代理多会几个技巧大得多因为它把团队经验变成了基础设施。第三个习惯给代理写负向提示。技能文件里除了“要做什么”我还写了一节“不要做什么”比如不要跳过测试直接写实现、不要在异常处理没确认前声称完成。负向约束比正向流程更能压低随机性这个我实测下来很稳。5.2 从 superpowers 出发的扩展玩法最后说说扩展。superpowers 的底层载体是 Markdown 和提示词这意味着它不绑定特定代理、不绑定特定语言。你只要找到一个支持自定义系统提示的工具就能沿用这套思路。我目前在做两个方向一是把技能仓库做成团队内部共享配合 CI 流程让代理自动生成变更记录、PR 描述甚至自动做初步代码审查二是把同一套技能文件用到本地小模型上。小模型推理能力弱但有了明确步骤输出质量提升非常明显。这个方向我认为比单纯追新模型更值得投入因为流程稳定性是模型能力之外的独立杠杆。最后分享一个小技巧不要一次性把全部技能都告诉代理。我会在项目开始时只暴露跟当前任务相关的三四个技能把上下文空间留给真正重要的代码信息。这个做法让我在长会话里的表现稳定了不少。说到底superpowers 这类工具真正的价值不是让代理多会几个技巧而是把工程经验从人脑转移到了可复用的文档里。你越是用它越会发现所谓超级能力不过是一群良好习惯的组合。如果你也在用编码代理建议先跑一遍初始化拿一个非核心模块试试这套流程再决定要不要深入。