如果你现在还在把 AI 编程助手当聊天框用——问一句、粘一段代码、再手动编译测试——那这篇文章就是为你写的。我最近把 GitHub 上一套叫 Superpowers 的技能库真正装进了日常开发环境配合 Claude Code 和 Codex 一起用最大的感受是以前我是在指挥一个聪明的实习生现在更像是在给一个靠谱的工程师下发任务。它解决的恰恰是 AI 编程最让人头疼的问题——不是模型不会写代码而是它没有工程流程意识想到哪写到哪写出来的东西能用但不敢上线。Superpowers 是一套开源的 AI 编程助手技能库核心思路非常简单把问答窗口升级成会做事的代理人。它通过一系列结构化技能文件让 AI 在写代码之前先拆需求、做计划、写测试在出问题之后按证据链排查而不是拍脑袋乱改。这篇文章我会从它的工作原理讲起完整走一遍安装流程逐个拆解核心技能再用一个 Spring Boot 的 Java 项目演示实际落地最后把我踩过的坑整理成排查手册。无论你用的是 Claude Code、Codex 还是类似的 CLI 编程助手这套方法都值得花半小时试一试。1. Superpowers 到底是什么给 AI 编程助手装上工作流大脑1.1 一个技能的本质是一份操作手册很多人第一次听说 Superpowers会误以为它是一个新模型或者新的 AI 框架其实完全不是。这套系统里的每个技能本质上就是一份 Markdown 文档里面用结构化指令写清楚某个场景下 AI 应该收集哪些信息、按什么顺序执行、输出什么格式、有哪些红线不能碰。AI 助手在运行时读取这些文档就像新员工入职拿到公司 SOP 一样照着流程干活。跟你在对话框里手写一长串提示词相比技能文件最大的优势是沉淀和复用。提示词是一次性的每次都要重新组织语言还经常因为表达不清楚被 AI 理解偏技能则是一次写好、处处生效。更关键的是技能可以设计成由事件触发比如 AI 意识到自己即将修改代码时会先自动激活写测试的流程而不是等你提醒你还没写测试呢。这个机制彻底改变了 AI 的工作惯性。1.2 为什么这能实打实提升代码质量直接对比一下效果最直观。没有技能的时候你让 AI给订单模块加个缓存它会非常热情地给你写一个 ConcurrentHashMap 或者 Redis 工具类然后就没有然后了——没有压测数据、没有并发边界分析、没有缓存一致性方案你得自己逐条追问。有技能的时候它会先进入 Brainstorming 阶段向你确认缓存是本地还是分布式、TTL 多久、哪些数据允许丢失、是否需要预热确认完再生成任务清单按先写测试、再写实现、最后重构的顺序推进。这套固定顺序的价值在于它给了 AI 一个操作闭环。我实际用了半个多月最明显的感受是 AI 给我写的代码里补全变少了。以前它经常漏掉异常处理、漏掉边界判断现在这些检查项被内置在技能流程里不通过检查它不会宣告完成。相当于把高级工程师脑子里的那些隐性规范显式地塞进了 AI 的执行逻辑里。1.3 技能库的目录结构长什么样装好之后你会看到一套很有规律的目录组织通常长这样.claude/skills/ ├── brainstorming/ │ └── SKILL.md ├── creating-a-plan/ │ └── SKILL.md ├── debugging/ │ └── SKILL.md ├── tdd/ │ └── SKILL.md └── writing-commits/ └── SKILL.md每个子目录代表一个技能SKILL.md是技能本体。你可以完全照着这套格式写自己的技能比如把团队代码规范、发布检查清单、安全评审要点都写成内部技能AI 就能按你们的规矩干活。我觉得这是整套系统最值钱的设计它没有把你锁死在固定功能里而是给了你一套教 AI 干活的标准格式。2. 安装与初始化把技能库接进 Claude Code / Codex2.1 安装前先想清楚你改的是行为不是模型我见过不少人在这一步犯迷糊到处搜Superpowers 模型下载其实方向从一开始就错了。Superpowers 不改变底层大模型它改变的是 AI 助手的工作方式。所以你不需要重新部署任何 AI 服务也不需要换 API只需要在现有编程助手的配置目录里加入技能文件就行。这意味着你现有的项目和工具链完全不用动卸载的时候删掉技能目录就干净了没有任何残留。我在 macOS 和 Ubuntu 上都跑过行为表现基本一致。Windows 用户建议用 WSL 环境不是不能直接用而是路径里的反斜杠和大小写问题容易出幺蛾子统一用 Linux 路径会省很多事。这里多提一句技能目录既可以放在用户级全局目录也可以放在项目级.claude目录下前者所有项目生效后者只对当前项目生效两者并存时项目级优先后面的排查环节我会细说这个坑。2.2 两种获取方式克隆复制 vs 插件管理第一种方式最直接从 GitHub 克隆仓库到本地。这一步不需要任何额外依赖机器上有 Git 就行git clone https://github.com/obra/superpowers.git克隆下来之后把里面的skills目录复制到你项目或者用户主目录的.claude/skills/下。目录不存在就自己创建。这是最朴素也最可控的方式没有黑盒逻辑团队内部分发也很方便——本质上就是把一套文档放进指定位置。第二种方式是走 AI 助手自带的插件机制。现在 Claude Code 有 plugin 命令Codex 也支持类似的扩展配置。用插件方式的好处是升级方便、版本清晰坏处是插件版本迭代频繁偶尔会跟你本地的手动修改发生冲突。我个人的建议是自己一个人用克隆加复制最省心如果要团队统一管理再考虑用配置锁定版本。两种方式的差别我整理成了表格方式优点缺点适用场景克隆 复制目录完全可控、无隐藏依赖、可离线分发升级需要手动合并个人使用、内网环境插件机制安装一键升级、版本清晰可能覆盖本地修改、依赖市场版本团队统一管理2.3 安装完怎么验证三个探针问题装完之后别急着写业务代码先花两分钟确认环境正常。我一般用三个问题做探针启动你的 CLI 编程助手直接问你现在有哪些技能可以用正常情况下它会列出 brainstorming、planning、tdd、debugging 等一整套技能名。如果它说没有先别慌看下面排查章节。再下一个具体指令请用 brainstorming 技能帮我分析这个需求观察它是否进入结构化提问模式——会一条一条问你业务约束和边界条件而不是立刻开写代码。如果它完全没反应大概率是技能目录路径不对或者 CLI 版本太老不支持技能加载。我遇到过一次很隐蔽的情况全局配置和项目级配置同时存在项目级把全局的加载路径覆盖掉了导致技能一个都没生效。这种问题看启动日志里技能加载的实际路径一般一眼就能定位。3. 核心技能逐个拆解这些超能力具体怎么用3.1 Brainstorming从帮我做个功能到先回答十个问题Brainstorming 是我使用频率最高的技能没有之一。它的工作方式初看很反直觉不让你直接说方案而是逼你先说清楚你究竟要解决什么问题。比如你说我想给订单系统加个优惠券功能它会连环追问券的类型有几种满减还是折扣能否叠加过期怎么处理跟现有支付流程如何衔接是否要做防刷限制这些问题问完我对需求的理解往往比我自己写 PRD 的时候更清晰。以前我甩给 AI 的需求其实很多都是伪需求边界条件根本没过脑子。现在我会主动先用 Brainstorming 过一轮收集齐约束再谈实现。而且这个技能生成的问题清单可以直接拿去当需求评审的提纲用对跨团队协作特别有帮助。3.2 计划与任务清单让 AI 自己管理执行进度Brainstorming 结束之后技能流程会引导你进入创建计划阶段。AI 会把大目标拆成一份带 checkbox 的任务清单每个任务都写明验收标准然后按依赖关系排序。我在一个支付模块重构里亲测过一共 27 个任务AI 先做接口抽象再做实现迁移最后统一清理旧代码。每个任务做完它会自己勾掉然后汇报结果和下一步计划。这里面有个细节极其关键任务清单不是写给我看的是写给 AI 自己看的。它把本来说过就忘的上下文变成了落盘的持久化状态。哪怕对话中断、进程崩溃、重新开会话只要加载这份计划文件AI 就知道活干到哪了、还剩哪些。这解决了我过去最大的痛点——以前 AI 跑一半崩了重开之后它完全失忆得把上下文重新喂一遍。现在有状态文件在恢复成本非常低。3.3 TDD 循环把红-绿-重构变成 AI 的肌肉记忆TDD 技能把经典的红-绿-重构循环固化成了 AI 的执行流程。使用的时候AI 会根据你描述的行为先写一个失败的测试然后运行它确认确实失败再写最小实现让它通过最后停下来做重构。每一步都有明确的输出要求比如贴测试运行结果、说明覆盖了哪些分支、列出重构改动点。在 Java 项目里这套特别顺手因为 JUnit Maven 的命令行集成非常成熟。AI 会自己调mvn test -Dtest某些测试类读取测试报告根据失败信息反推代码问题。我以前写 Java 最怕的就是测试全绿但线上出问题本质是测试覆盖的维度不对。现在 AI 在写实现的时候就会主动问边界值、问分支覆盖而不是代码写完再补测试这完全是两个世界的工作方式。3.4 Debugging 检查清单治好了我随手改代码的毛病Debugging 技能本质上是一张强制执行的检查清单逼着 AI也逼着我按证据链排查问题而不是拍脑袋猜。它规定的流程是先复现、再缩小范围、再定位、再修复、最后回归验证。而且在改任何代码之前必须先写下当前假设和验证方法。我遇到过一个并发下订单重复创建的疑难问题以前肯定是直接把相关代码丢给 AI 让它猜。用了 Debugging 技能之后AI 第一步让我提供完整的复现步骤和异常日志第二步梳理调用链上每个环节的状态变化第三步确认问题出在幂等校验的时序上才让我考虑改状态机还是加唯一约束。整个过程中它反复提示没有证据支撑不要改代码。这套流程治好了我多年随手改代码的毛病强烈建议所有习惯先改一下再说的人试试。4. Java 项目实战Superpowers 在 Spring Boot 里怎么落地4.1 从零搭建订单服务AI 按计划干活的全过程以一个 Spring Boot 的订单服务为例实际操作一遍完整流程。启动助手之后第一句不要是帮我建一个订单服务而是使用 brainstorming 技能拆解需求。AI 会先输出一批问题支付幂等策略是什么订单状态怎么流转要不要分布式事务消息队列用哪种你逐条回答之后它会生成一份计划文件里面列好了 Maven 项目结构、依赖清单、测试策略和执行顺序。接下来执行计划时AI 会先做环境检查JDK 版本是否满足、Maven 是否安装、8080 端口有没有被占用。这些检查项都是技能内置的一环不是 AI 临时起意。我的实测数据从空项目到第一个接口的 MockMvc 测试跑通大概十几分钟而且每一个阶段都有 Git 提交记录随时能回退到任意节点。这种有据可查的推进方式比让 AI 一次性生成整个工程然后 review 要安全得多。4.2 技能如何理解 Java 生态Maven、Gradle、JUnit 的适配Superpowers 本身跟语言无关但它在设计上特别适合 Java 生态原因很简单Java 的工具链命令行非常成熟依赖声明、编译、测试、覆盖率检查都有标准化的 CLI 接口。AI 技能强调可执行验证而 Maven 和 Gradle 恰恰提供了这种验证手段让先写测试再写实现的循环真正落得了地。这里有一个建议技能文件里可能会有一些默认配置比如它默认你用 Maven、默认 groupId 是com.example。实际接手项目时最好把这些信息写进项目说明文件或者直接改技能里的默认值。否则 AI 生成的 pom.xml 可能跟你团队的私服地址、依赖版本规范对不上。我自己吃过这个亏AI 生成的依赖版本是它自己认为的最新稳定版跟公司统一版本平台差了好几个小版本后来我把项目实际依赖清单写进说明文件这个问题就再没出现。4.3 结合 Codex CLI 使用长任务场景下的体验很多人用 Codex 是因为它可以在终端里独立跑长任务不占用编辑器。把 Superpowers 接进 Codex 之后它的行为风格也会跟着技能走接到需求先拆解再建计划最后动手。我在 Codex 里跑过一次数据库迁移脚本的重写它先确认源库和目标库的版本再列出每个脚本的变更内容然后才动代码全程没有直接操作数据表。不过要注意一个细节Codex 对技能目录的读取方式和 Claude Code 并不完全一致。如果你先装的是 Claude Code 版本再切到 Codex最好检查两边的配置目录有没有串。我的做法是单独维护一份共享的技能目录在两个工具里分别通过配置指向它。这样既能保证两边行为一致技能更新的时候也只改一处省心很多。5. 常见问题与排查技巧实录5.1 技能列表为空三个典型原因和排查思路技能不生效通常逃不出三个原因目录名写错、SKILL.md 文件名大小写不一致、配置被项目级目录覆盖。排查的时候我一般按这个顺序来先在项目根目录跑find . -name SKILL.md看看实际路径是否存在再看 CLI 启动输出里加载的配置目录指向哪里最后对比全局配置和项目级配置确认没有互相覆盖。这套流程走完大部分问题都能定位。具体来说目录名是skills不是skill文件必须叫SKILL.md不能叫skill.md这都是踩过的血泪教训。还有一次是我在全局配了技能路径又在项目里建了.claude目录但忘了放技能文件结果项目级配置把全局的覆盖了技能全军覆没。这种问题直接看日志最快别靠猜。5.2 技能触发了但行为不对收紧触发条件另一种更隐蔽的问题技能确实加载了AI 也认了但执行起来变味。比如你让它用 TDD 技能结果它还是一股脑把全部代码写完最后补了一个测试假装走完了流程。我分析下来多半是技能文件里的触发条件写得太宽泛AI 把它理解成了如果方便就走流程不方便就跳过。解决办法很简单把技能开头何时使用的说明改得严格比如明确写只有在用户请求包含 tdd、测试优先、红绿重构等关键词时才激活。指令措辞尽量用必须禁止这类强指令不要用建议可以考虑这种弱表达。AI 对弱指令的遵守程度比你想的低得多。5.3 自定义技能把团队经验变成机器强制流程写自定义技能其实没什么门槛照着现有SKILL.md的格式抄就行。我积累了几个经验第一每个技能只做一件事别想着把十个检查项塞进一个文件AI 处理长技能文档时容易漏掉后面的内容第二技能里明确写出你期望收集的输入信息避免 AI 自由发挥第三凡是不能接受的行为直接写成禁止条款比避免有效十倍。一个很实用的方向是把团队的代码评审清单或者发布流程写成技能。比如 AI 每次提交代码前自动检查是否有未处理的 TODO、是否补了测试、是否写了变更说明。等于把资深工程师脑子里的经验变成了每次提交都强制执行的流程。这套东西越早沉淀团队受益越早。5.4 版本管理坑别让 git pull 冲掉你的定制技能库迭代还是挺快的上游经常有更新。但如果你直接从克隆的仓库里改了技能文件下一次git pull很可能把你的定制覆盖掉。我踩过一次改了 TDD 技能的触发条件还没来得及提交一个 pull 全没了又花半小时改回来。我的解决方案是把技能目录独立放到一个自己的 Git 仓库里上游仓库作为 remote 添加进来。需要更新时用 cherry-pick 或者手动合并的方式把上游变更合进来自己的定制永远保留。这个习惯虽然前期多花几分钟但能避免无数次我的配置怎么不见了的崩溃。新手第一次用技能库极容易在这个坑上栽跟头提前做好准备就不慌。最后说一点这半个多月用下来的个人体会。Superpowers 带给我的最大改变不是 AI 生成的代码质量突然突飞猛进而是我自己的开发习惯被它带着越来越规范了。以前接到需求我习惯直接开写边写边想边界条件漏了后面再补现在 AI 会在动手前反问我一堆边界问题逼着我把思路理清。如果你想尝试别贪多先把 brainstorming、planning、tdd 这三个技能用熟形成肌肉记忆再慢慢探索其他技能。等你习惯了这种先想清楚再动手的工作方式大概就再也回不去原来那种边写边猜的状态了。