这两年我用过不少 AI 编程助手最烦的一个问题不是它不会写代码而是它老“忘事”。同一个对话框里早上刚跟它确认过的项目结构下午就当成不存在让它改一个横跨五六个文件的逻辑改到第三个文件就开始自说自话。后来我接触了一个叫 superpowers 的开源项目配合 codex、claude 这类编码工具用恰好解决的就是这个问题。它最近在技术社区里的热度非常高“superpowers 使用指南”“superpowers java”“codex superpowers”这些关键词被反复搜说明大家真正想要的不是另一个聊天机器人而是让 AI 能像有经验的组员一样有流程、有判断力、能自己拆任务。这篇东西我会把从安装、配置、实战到踩坑的完整过程都写出来适合那些已经在用 AI 写代码、但总觉得差点意思的开发者。1. 从“一问一答”到“按流程干活”superpowers 到底补上了什么1.1 闲聊式对话的尽头传统的 AI 编程助手默认工作方式是“对话补全”你问一句它答一段。这种方式对单点问题很管用比如“这个函数为什么会报空指针”“帮我写个正则”。但凡是超过三个文件、需要多个步骤、依赖前置决策的任务对话补全就露出疲态了。我举个自己踩过的真实例子。有次我让 AI 给一个 Java 服务补日志它的回答确实加了日志但顺手把我一个专门做请求追踪的过滤器也给改了。原因是它在生成代码时只盯着当前上下文完全忘了项目里已经有一套统一日志规范。这就是典型的“金鱼记忆”——AI 不是不聪明是它天生没有“持续记忆”和“流程意识”。superpowers 的核心思路恰恰是绕开这个天然缺陷不指望 AI 通过一次对话就理解整个项目而是给它一套“技能库”让它在正确的时间、按正确的步骤去处理正确的任务。简单说就是把人类开发者的工作方法教给 AI。1.2 把方法变成技能把技能变成文件superpowers 最核心的概念是“技能”。一个技能就是一个 Markdown 文件文件里写清楚这个技能解决什么问题、什么时候触发、具体分几步执行、每步应该输出什么。比如plan技能要求 AI 在写代码之前先制定详细实施计划test-driven-development技能要求 AI 先写失败测试再写实现代码。这个设计最妙的地方在于技能不是代码是文档。人类开发者怎么读文档就怎么读技能文件人类怎么 review 文档就怎么 review 技能。不需要编译不需要部署git 仓库本身就能管理版本。我在团队里分享技能时直接把文件丢到群里对方拉下来放到对应目录就能用比以往写“AI 使用规范文档”要落地得多。1.3 和普通提示词的本质区别有人会问这不就是把一段很长的提示词存下来复用吗还真不是。提示词是一次性的“口信”技能是可进化的“标准作业程序”。提示词的缺陷在于没有结构你写“请认真分析需求、阅读相关代码、再制定计划”AI 读到这些字但不会真正把它当成一个流程来执行。技能文件则不同它带明确的触发条件、步骤顺序、输出要求还能嵌套调用别的技能。更关键的是提示词没法递归调用自己而技能可以。我打个比方。提示词是老师傅在工位上口头叮嘱“你看着办多想想再做。”技能是贴在生产线的作业指导书每条工序写清楚动作、顺序、质量要求。后者随时可修正修正之后所有人所有 AI 会话立刻生效这是质的差别。2. 上手前先搞清边界安装 superpowers 的几种姿势2.1 前置环境要求想跑 superpowers你得先有一个“宿主”工具。它本身不是独立 IDE也不自带模型更像是一个技能系统挂靠在 Claude Code、Codex CLI 这类 AI 编程终端上。所以我建议先确认三点。第一你的电脑上已经装好 Node.js 环境因为底层 CLI 大多跑在 Node 上。第二你至少有一个能正常使用的 AI 编程终端并且已经配置好模型 API 权限。第三你的工作目录是一个真实的代码项目而不是空文件夹。第三点我特别提一下因为技能系统很多动作要读写文件、跑测试空目录会让技能在第一步就“无米下锅”。如果你只是装了 ChatGPT 网页版或 Claude 网页版那暂时用不了这份技能库。superpowers 走的是“工具调用”路线必须让 AI 能执行命令、操作文件系统才有意义。2.2 最稳妥的方式git clone 后手动接入我最开始用的是最“笨”的方式——直接 clone 仓库到本地这样能看清文件结构出了问题也好排查。git clone https://github.com/obra/superpowers.git ~/.superpowersClone 下来之后里面主要是skills目录以及各种说明文档。接下来要做的就是让 AI 编程终端知道技能库在哪。不同终端配置方式不太一样以我手头的 Claude Code 为例支持通过/plugin系列命令把本地目录加进来。我的习惯是先看一下自带 README 里的安装说明因为项目迭代比较快安装命令偶尔会调整。用 git clone 的好处正在这里你可以随时git pull拉最新版也能方便地查看升级日志。2.3 更省事的方式通过插件市场安装如果你日常已经在用 Claude Code 的插件市场marketplace那更推荐用市场方式安装。核心逻辑是“先把仓库地址加为市场再从市场安装插件”。不同版本的宿主管道命令会有差异我常用的是在交互式会话里直接输入斜杠命令操作。大致路径是/plugin marketplace add 仓库地址 /plugin install superpowers这类命令的好处是自动化程度高它会帮我们处理目录位置、依赖关系、后续升级。缺点是如果网络不太好或者仓库结构变化报错信息会比较抽象。我遇到过几次“marketplace add 成功但 plugin install 失败”的情况最终都回到 git clone 方式解决。所以如果你第一次装就卡住别死磕换个姿势。2.4 装完先别急着写业务代码验证是否生效安装完成后我会做一次“冒烟测试”。最简单的方式是进入一个测试用的小项目然后问宿主终端一句你当前加载了哪些技能请直接列出所有可用的技能名称。正常的输出里会出现plan、debugging、test-driven-development、code-review等技能名。如果 AI 只是说“我没有技能”或者“不知道你在说什么”那基本可以判断技能库没有被真正加载此时再回查配置路径。另外一个检查点是技能目录权限。Linux/Mac 系统下如果目录权限不对宿主终端可能读取不了。我当时的排查过程是ls -la ~/.superpowers/skills确认每个技能的目录至少是755权限。2.5 目录结构到底长什么样当你真正打开 superpowers 的目录时看到的结构大概是这样的~/.superpowers/ ├── skills/ │ ├── plan/ │ │ └── SKILL.md │ ├── test-driven-development/ │ │ └── SKILL.md │ ├── debugging/ │ │ └── SKILL.md │ └── code-review/ │ └── SKILL.md └── README.md每个技能都单独占一个目录目录里至少有一个SKILL.md文件。有些技能还会附带自己的模板文件或示例代码。以后你自己写技能也按照这个模式来组织一个目录配一个SKILL.md必要时再放辅助文件。这种“一技能一目录”的约定让整个技能库极其容易被 git 管理也方便多人协作。3. 拆开一个技能看原理SKILL.md 是怎么指挥 AI 干活的3.1 一个最小可用的 SKILL.md要理解 superpowers 的能量最直接的办法是亲手写一个极简技能。下面这个文件来自我本地调过的简化版plan技能--- name: plan description: 当用户要求实现一个比较复杂的功能时先制定实施计划在用户确认后再开始写代码。 --- # Plan ## 目标 在动手编码前产出一份结构清晰的实施计划避免 AI 盲目修改代码。 ## 执行步骤 1. 向用户确认需求列出需求要点。 2. 阅读项目结构找出与需求相关的文件和关键函数。 3. 分析可能影响的范围列出涉及修改的文件。 4. 输出实施计划并按步骤拆解任务。 5. 等待用户确认。用户未确认前禁止进入编码阶段。 ## 输出格式 - 需求要点列表 - 涉及文件列表 - 任务拆解每个任务包含目标、改动点、验证方式这个文件的要点很清晰开头用了 Markdown 的 frontmatter 格式写name和description这两个字段的用途有点类似“索引”。当 AI 收到用户需求时会先在内部比对各技能的description判断当前任务命中哪个技能。3.2 description 是触发开关不是摆设很多人写技能时会忽略description的重要性或者随便填一句“处理复杂任务”。这会导致两个后果该触发时不触发不该触发时乱触发。因为这个字段实质上是给 AI 做语义匹配用的它需要足够具体最好包含触发场景、任务类型、典型关键词。比如说ban 一个技能是“处理用户请求”那 AI 几乎每次对话都会命中它其他技能就被架空了。一个合理的 description 应该类似“当用户请求新增功能、重构代码或修复复杂缺陷且任务涉及多个文件时先制定实施计划”。定义越精确技能调度就越稳定。我见过一些社区技能库description 写得好AI 在对话里几乎感觉不到技能的存在但行为明显变得有序。3.3 子代理和递归调用技能也能调用技能superpowers 真正有价值的设计是技能之间可以互相调用。plan技能在输出计划后下一步行动可能不是“开始写代码”而是调用test-driven-development技能让整个编码过程按 TDD 节奏走debugging技能在处理一个偶发 bug 时也可能调用plan技能先生成排查方案。这种“技能嵌套”能力是单个长提示词做不到的。因为单个长提示词是线性执行的没法根据中间结果动态切换流程。技能系统则不同每一步都可以根据当前状态决定下一个动作是什么本质上是一个可编程的行为树。不过要注意技能嵌套也容易过度。我自己的经验是嵌套深度控制在三层以内否则 AI 会在多个技能文件之间反复横跳输出越来越长反而拖慢效率。我自己有一次 debug 场景plan 调 debugdebug 又调 plan来回好几轮最后 token 消耗翻了一倍。后来我在技能里加了约束同一个会话内同一技能最多重复触发两次。3.4 靠“先读后写”对抗上下文遗忘AI 编程时的“忘事”问题不能靠硬记解决得靠流程兜底。superpowers 的技能里有一个高频指令叫“先读后写”要求 AI 在执行修改动作之前先读取指定文件并输出关键信息。比如代码审查技能会强制 AI 列出“涉及到的入口函数、数据结构、调用关系”这些信息一旦写进上下文后续步骤就不容易跑偏。同时技能本身也是一种上下文压缩手段。如果不用技能你需要在对话里重复粘贴一堆流程要求会占用大量上下文窗口。用了技能之后这些流程逻辑被“外部化”到了文件里会话上下文只保留当前项目相关的关键信息token 消耗反而降下来了。我在实际使用中跑一个完整功能开发token 使用量比裸用 AI 对话大概省了三分之一。4. 实战用 superpowers 给一个 Java 项目加一个 REST 接口4.1 热身为什么拿 Java 举例这里我特意选 Java 场景因为“superpowers java”是高频搜索词。我平时不少工作是在 Spring Boot 项目上这类项目的工程结构相对规整——controller、service、repository 分层清晰特别适合验证技能系统能不能照着流程走。如果你平时写的是 Go、Python思路完全可以平移只是项目结构和测试命令不同。先说需求给一个已有的用户管理模块加一个GET /api/users接口返回用户列表要求只返回非禁用用户并按创建时间倒序。这是很典型的小需求但依然横跨 controller、service、repository、DTO 四层。4.2 第一件事不是写代码先跑 plan 技能我直接对宿主终端说需求新增 GET /api/users 接口返回非禁用用户列表按创建时间倒序。请按你的技能流程处理。触发plan技能后AI 没有急着写接口而是先输出需求要点然后主动去读了项目里的UserController.java、UserService.java、UserRepository.java最后给出实施计划。计划大概是这样的涉及文件 - UserController.java新增 GET /api/users 端点 - UserService.java新增 listActiveUsers() 方法 - UserRepository.java新增按状态和创建时间排序的查询方法 - UserDto.java新增或复用返回 DTO 实施步骤 1. 在 UserRepository 中添加查询方法条件为 status ! disabled排序为 createdAt desc 2. 在 UserService 中调用仓库方法并做空列表处理 3. 在 UserController 中暴露 GET /api/users 4. 编写单元测试覆盖正常返回、空列表、禁用用户过滤 5. 运行测试验证说实话单看这份计划并没有超出我一个高级开发者的认知范围。但它带来一个直观的好处AI 先读了代码再开口比凭空生成接口靠谱得多。计划出来之后我需要确认AI 才会进入下一步。4.3 红灯阶段TDD 技能让 AI 先写会失败的测试确认计划后AI 自动把test-driven-development技能加载进来。TDD 技能的核心指令是先写测试运行并确认测试失败再写实现最后运行确认测试通过。我第一次看到 AI 真的这么干时还挺意外的。它先写了UserControllerTest.java测试方法里断言响应码是 200、返回列表里不包含禁用用户。然后运行mvn test测试果然失败因为GET /api/users端点还不存在。这一步看起来是“白费功夫”实际上极为关键它保证了后面写实现时有一个明确的验收标准。Test void shouldReturnActiveUsersOnly() throws Exception { mockMvc.perform(get(/api/users)) .andExpect(status().isOk()) .andExpect(jsonPath($.length()).value(2)) .andExpect(jsonPath($[0].username).value(alice)); }4.4 绿灯阶段实现代码并让测试通过测试失败后AI 开始按计划写实现。它先改UserRepository.java加了一个类似这样的查询方法Query(select u from User u where u.status DISABLED order by u.createdAt desc) ListUser findActiveUsersOrderByCreatedAtDesc();再改UserService.java对空列表做了防御性处理避免把null直接抛给前端。最后改UserController.java暴露端点。整个过程里AI 每改一个文件都会输出改动摘要相当于随时告诉我“我改了什么、为什么这么改”。所有改动完成后再跑一次mvn test测试从红变绿。整个过程比我预期顺利很多因为 TDD 技能天然把“验证”嵌进了流程AI 不会再出现那种“代码写完但根本没跑过”的情况。4.5 收尾阶段让代码审查技能再查一遍测试通过不代表任务结束。我触发code-review技能让 AI 以审查者身份重新看这次改动。它会按技能里的检查清单逐项核对接口是否遵循 REST 命名规范、有没有浪费数据库查询、异常处理是否合理、有没有硬编码魔法值。这个技能给过一个相当中肯的建议查询方法里的 DISABLED字符串应该抽成常量避免三个文件里各写一遍。我接受了建议改完后再跑一次测试依然全绿。这就完成了一个比较标准的 superpowers 工作流计划、写测试、实现、审查、回归。4.6 翻车记录执行到一半断掉怎么办当然不是每次都这么顺。我有一次让 AI 跑 TDD 流程它在“红灯”阶段运行测试时发现编译错误然后停下来说“测试无法运行因为缺少依赖”接下来就开始跟我解释原因而不是进入修复流程。这明显是技能步骤没有覆盖“编译失败”这个分支。我的处理方式是给test-driven-development技能补了一条规则当测试无法运行时先读取编译错误日志定位缺失依赖或语法问题修复后继续本轮流程不要停下来向用户解释。改完技能文件后再重新触发AI 就正常多了。这件事给我的启发是技能系统不是装完就完事的它需要在使用中持续打磨就像维护一套测试用例一样维护技能库。5. 接入 Codex 和其他 CLI同一套技能库的复用与兼容5.1 为什么技能可以跨工具复用很多人搜索“codex superpowers”是因为以为 superpowers 只能配 Claude Code 用。其实按照它的设计技能文件是模型无关、工具无关的纯文档。宿主终端做的事情只是“读取技能、理解技能、按技能执行工具调用”。只要宿主终端支持文件读写、命令执行、子代理理论上就能接入同一套技能库。这对做多模型开发的团队价值很大。同一个项目今天用 Claude Code 跑明天切到 Codex CLI不需要重新写一套技能直接指向同一个技能目录即可。代码审查、TDD、计划这些流程在不同工具间表现略有差异但大方向一致。5.2 Codex CLI 的接入实操我这边的 Codex 接入方式主要是通过它的配置文件指定技能目录。以我用的版本为例Codex 允许在配置里加一段skills_dirs或plugin_dirs指向~/.superpowers/skills。{ skills_dirs: [~/.superpowers/skills] }配置完成后重启 Codex 会话用“列出你的技能”来验证。如果输出里没有技能名多半是路径没展开或者配置文件没生效。Codex 对路径写法比较敏感我建议用绝对路径而不是~有次我图省事写了波浪号结果技能没加载排查了半天才发现是路径展开的问题。5.3 模型差异带来的坑跨工具之后“同技能不同命”的情况非常常见。Claude Code 底下的模型对长文档理解强技能里写十来个步骤它基本能一步步执行到了 Codex CLI如果底层是别的模型它对超长指令的遵循度会下降尤其是当技能里同时包含“步骤”和“输出格式”时AI 容易忽略后半部分。我的解决办法是把技能步骤粒度调细。原计划里的第 2 步“阅读项目结构找出相关文件”在 Codex 场景下拆成两步“列出项目根目录结构只列出与需求相关的目录层”和“打开候选文件记录核心类名与职责”。看着啰嗦但实际效果稳定很多。技能本来就是给机器看的流程文档宁可多几步指令也不要靠模型“领悟”。另外不同模型的“确认时机”也不一样。在 Claude 上plan 技能中间要求用户确认它会把控制权交回来在部分 Codex 版本里AI 可能会忽略这个等待动作直接继续执行。解决办法是在技能文件里写得更绝对“用户未明确回复‘继续’之前禁止执行下一步任何工具调用。若用户未回答重复当前问题。”5.4 权限和安全的底线技能给了 AI 自动执行复杂任务的能力权限边界就必须同步收紧。superpowers 本身不含权限系统权限控制完全依赖宿主终端。我的建议是至少做到三点。第一技能库目录应该是只读的。AI 可以读取SKILL.md并按其执行但不应该被允许修改技能库文件本身除非它明确收到“编辑技能”的指令。第二对执行命令做白名单约束尤其是rm、git push --force、DROP TABLE这类高风险命令在真实生产项目里要格外谨慎。第三涉及生产环境的凭据访问一律不给 AI 工具权限。我在自己的技能模板里专门加了一段“安全红线”章节明确列出禁止执行的操作。6. 沉淀自己的技能库命名、模板与团队共享6.1 技能命名的基本功很多东西用得久了就会沉淀出自己的一套规矩。目前我的技能命名都遵循“动词 对象”的结构比如review-code、debug-build、write-test、plan-feature。这样做有两个原因。一是触发匹配更容易。描述字段里写着“当用户要求 review 代码时”AI 直接命中review-code技能不产生歧义。二是文件系统排序更清晰。按动词开头整个技能目录看起来像操作手册的目录哪个技能管哪类任务一目了然。反之如果叫java-api这种表面看是按领域归类的实际上 AI 很难判断什么时候该用它。6.2 从个人仓库到团队共用技能库一旦达到十几个技能就值得纳入 git 管理了。我把整个~/.superpowers仓库放到团队内部的代码托管平台同事 clone 下来就能用。技能文件的修改走 PRreview 的人看的就是 Markdown diff门槛比看代码 diff 低得多。这里有个值得注意的点技能是“组织经验”的高价值载体但也很容易夹带个人偏好。团队共享时最好在技能模板里加一个“适用范围”字段明确这个技能是适用于所有项目还是只针对某个特定技术栈。比如我们团队就有两个debug相关技能一个针对 Java 构建问题一个针对前端打包问题靠description里的关键词区分。6.3 自定义技能的脚手架模板如果你准备自己写技能我建议从下面这个模板起步比从零写更不容易漏东西--- name: 技能名称动词 对象 description: 在什么场景下触发面对什么任务时使用 --- # 技能名称 ## 技能目标 这个技能要达成什么效果 ## 触发边界 什么情况下不应该使用本技能 ## 执行步骤 1. 第一步做什么 2. 第二步做什么 3. 验证动作是什么 ## 输出格式 要求 AI 在每一步之后输出什么内容 ## 安全红线 哪些操作明确禁止 ## 适用范围 哪些项目、哪些技术栈适用我特别想提醒的是“触发边界”和“安全红线”这两个小节一开始很容易被省略但它们恰恰是技能稳定性的关键。没有边界AI 就会过度使用没有红线AI 可能在错误场景里越权操作。6.4 什么时候不该加技能技能不是越多越好。我在使用过程中形成的判断标准是如果一个动作我每周至少做三次而且每次的操作路径高度一致那它就值得做成技能。如果一个月都用不了一次那还不如直接写提示词。技能库的过度膨胀会带来维护成本也会影响调度准确率。技能数量超过二十个以后AI 在匹配description时会出现相近意图互抢的情况。我曾有两个技能分别叫check-code和review-code作用几乎重叠结果是 AI 经常随机挑一个执行。后来我下定决心合并成一个review-code调了几次触发词才恢复稳定。所以定期删减技能和新增技能一样重要。最后一个自己用下来的心得不要试图把 superpowers 变成“全自动写代码机器”。它真正擅长的是把那些已经成熟的、可重复的工程流程固化下来让 AI 在这些流程里干活减少随机发挥。刚开始用的时候我只保留了plan、test-driven-development、review-code三个技能并且每个都反复调过好几遍确认稳定之后才慢慢扩充。这个过程有点像带新人开始你说得越细后面它才越不需要你操心。