AI 编程助手用久了很多人会有一个相同的感觉它写单点功能很快但一放到真实项目里就容易“失控”。要么不写测试就急着交付要么连需求都没问清楚就直接改了五个文件要么重构完跑出一堆编译错误。superpowers 这个开源技能集就是冲着这个痛点来的。它不是一个传统意义上的插件也不是某个 IDE 扩展而是一套面向 Claude Code、Codex CLI 这类终端型 AI 编程助手的“工作协议”。安装之后助手会被引导按一套资深工程师的作业流程干活先澄清需求再写实现计划然后严格走测试驱动开发TDD最后才提交代码。这篇文章我会从零开始讲清楚 superpowers 的底层逻辑、实际安装步骤、它在 Java 项目里的实战用法以及我踩过的几个坑。无论你是刚听说这个名字还是已经装了一半遇到问题都能找到参考。1. 先搞清楚superpowers 不是插件是一套“任务协议”我第一次听说 superpowers 的时候第一反应是去网上搜“superpowers 安装”以为它是个 npm 包或者 VS Code 插件。装完才发现这套东西的运作方式跟传统插件完全不一样。它不会给你界面按钮也不会注册快捷命令而是往你的 AI 助手的工作目录里塞了一批 Markdown 文件这些文件就是“技能”。1.1 技能文件的本质每个技能本质上是一个目录目录里有一个SKILL.md文件外加若干辅助文档。SKILL.md的结构类似这样--- name: tdd description: 使用测试驱动开发流程编写代码先写失败测试再实现最小代码使其通过。 --- # TDD 技能说明 ## 核心步骤 1. RED编写一个失败的测试 2. GREEN用最小改动让测试通过 3. REFACTOR在测试保护下重构 …… ## 注意事项 - 测试必须真实覆盖业务逻辑 - 禁止通过修改断言来“强迫”测试通过 ……就是这个不起眼的文本文件能让 AI 的行为发生质变。原因在于Claude Code、Codex CLI 这类工具在启动时会扫描指定目录下的技能文件把文件名、描述、正文内容注入到系统提示词里。AI 在回答问题时会根据当前任务的语义自动匹配技能描述然后按照技能文档里写的步骤来执行。所以 superpowers 更像是一份“工作岗位说明书”。它不直接替 AI 写代码而是规定了 AI 在什么场景下应该先做什么、后做什么、禁止做什么。1.2 一套典型的“工程师 SOP”包含哪些环节完整安装 superpowers 之后技能库里通常包含几十个技能它们彼此衔接组成一个完整的软件交付闭环技能类别典型技能解决的问题前期规划brainstorming、think、writing-plansAI 不了解需求就动手开发执行tdd、red-green-refactor、executing-plansAI 跳过测试、跳步实现质量保障code-review、debugging、root-cause修 bug 靠猜、不找根因收尾归档commit、release提交信息混乱、发布无章法这一整套流程其实就是把开发团队里“资深工程师带新人”的方法论沉淀成了 AI 可读的规范文件。你不需要反复在提示词里强调“先写测试”因为技能文件已经把这条规则写死AI 每轮都会遵守。1.3 它适合谁不适合谁如果你平时只用 AI 写一次性脚本、做算法题或者生成点零散片段superpowers 带来的收益不会很大——它引入的流程开销在那类场景里是纯负担。但如果你在维护真实项目特别是像 Java 这种强调工程规范、编译检查严格、回归成本高的代码库那这套东西的价值会被放大。多人协作时AI 按统一流程产出代码Review 的体验能好很多。简单说superpowers 追求的不是“AI 帮你写完功能”而是“AI 按不会给团队添乱的方式写完功能”。2. 动手装两条路径以及装完必须做的一次自检安装这件事看起来简单——Git 克隆到某个目录而已。但我发现大部分人的问题都出在“路径选错”和“没有对工具侧做额外配置”上。接错了位置技能文件根本不会被扫描AI 还是一副“没有规矩”的老样子。2.1 用户级安装 vs 项目级安装先讲路径选择。superpowers 官方推荐的安装方式是把仓库克隆到 AI 工具对应的技能目录下。这里有两种范围安装范围路径以 Codex CLI 为例适用场景用户级~/.codex/skills/所有项目都能用适合个人日常开发项目级.codex/skills/项目根目录下只对当前项目生效适合团队统一规范如果你用的是 Claude Code路径会对应变成~/.claude/skills/或.claude/skills/。不同工具读取的目录名不一样核心逻辑是一致的把技能文件放进工具启动时会去扫描的 skills 目录即可。我的建议是个人试用期用用户级确认流程稳定之后再决定要不要把项目级配置提交到团队的 Git 仓库。项目级的好处很明显——新同事克隆代码后AI 工具会自动加载团队约定的技能流程不需要额外培训。2.2 一个完整的安装示例假设你的环境是 Codex CLI操作步骤大致是这样的# 1. 进入技能目录 cd ~/.codex/skills # 2. 克隆 superpowers 仓库 git clone https://github.com/obra/superpowers.git # 3. 检查目录结构 ls ~/.codex/skills/superpowers/skills/克隆完成后你会看到仓库里有一堆子目录每个目录对应一个技能。这里要特别注意AI 工具扫描的通常是“技能目录”而不是“仓库根目录”。如果工具支持递归扫描那克隆到根目录就能直接识别如果不支持你可能需要把skills子目录里的内容复制到一级目录下。装完第一件事不是急着写代码而是做一次自检。2.3 安装后的自检确认 AI 真的“看见”了技能怎么确认安装成功很简单直接在 AI 终端里问一句请列出你现在可用的技能以及它们的核心用途。如果安装成功它会列出 brainstorming、writing-plans、tdd 等技能名。如果它回答“我没有技能”或者含糊其辞基本可以断定技能目录没被扫描到。这时候逐项排查确认技能目录路径是不是工具支持的默认路径确认目录里是否真的有SKILL.md文件确认工具版本是否支持技能功能老版本 CLI 可能没有这个能力如果是用户级目录确认当前项目没有用项目级目录把用户级覆盖掉。还有一个值得做的验证是触发一个具体技能看它的行为有没有变化。比如你随口说“帮我想一个登录模块的设计方案”如果它自动进入了类似“先问需求、列边界条件、再给方案”的状态说明 brainstorming 技能已经接管了行为模式这时候才算真正装好。3. 技能库到底怎么驱动 AI以 TDD 链路为例拆开看理解了安装逻辑之后更值得花心思研究的是技能库的驱动机制。superpowers 不是简单地把几十个技能文件堆在那里它有明确的调用链和优先级。搞懂这条链路你才知道什么时候该显式触发技能什么时候该闭嘴让 AI 自己判断。3.1 技能触发的真相描述匹配 显式调用技能文件的description字段有一个作用当 AI 收到用户消息时会把消息内容与技能描述做语义匹配。匹配度高的技能会被自动选中并加载到上下文里。这意味着描述写得越具体触发越精准。比如你只说“帮我处理一下这个模块”AI 可能会触发 brainstorming也可能会直接触发 executing-plans这取决于它怎么理解“处理”这个词。为了避免误触发superpowers 通常会在文档里要求 AI 在不确定时先问清楚而不是自己瞎选。除了自动匹配你也可以在提示词里显式点名使用 tdd 技能在这个 Java 模块里为 PaymentService 添加新功能。显式调用相当于绕过了匹配环节直接锁定技能。这种方式的优点是稳定缺点是要求你对自己想要的流程有一定的理解。用多了你就会发现显式调用更像“主动指挥”自动匹配则像“放权给 AI”。3.2 从需求到提交的完整技能编排我以一次完整的功能开发为例把技能链路拆开think / brainstormingAI 先不写代码而是把目标拆解清楚。它可能向你提问确认用户角色、输入输出、边界条件。这一步的输出通常是一份简短的需求澄清记录。writing-plans需求确认后AI 写一份实施计划。计划里包含要改哪些文件、每个文件的改动目标、测试策略、风险点。这份计划会保存为项目里的一个文档方便后续对照执行。executing-plans按照计划动手但不是“一口气改完”。它会逐步执行每完成一步就停下来验证而不是闷头输出一大段代码。tdd / red-green-refactor进入真正的编码环节。先写失败测试运行确认是“红”再写最小实现让它变“绿”最后在测试保护下重构。commit代码通过测试后由 AI 生成符合规范的提交信息通常还要把相关变更按逻辑拆成多个 commit。这一整套流程下来AI 的工作方式从“一次性生成答案”变成了“多轮状态机推进”。每一步的产出都依赖上一步的结果每一步都有检查点。这也是 superpowers 最厉害的地方——它让 AI 从“快”转向“稳”。3.3 为什么是 Markdown而不是代码有一个问题经常被问到为什么技能不用 JavaScript 或 Python 写而是用 Markdown我个人的理解是Markdown 对 AI 模型的“可读性”更好。模型在训练阶段就见过海量 Markdown 文档对这种格式的指令性内容理解最稳定。相比之下代码逻辑容易被模型当成“需要推理的代码”而不是“需要遵守的指令”边界容易糊。另一个现实原因是 Markdown 版本管理成本很低。团队想裁剪某个技能的步骤直接改几行文字就能提交不需要走编译发布流程。这意味着技能规范可以跟着项目一起演进这是传统插件做不到的灵活度。4. 实战带跑Java 老项目里从需求到绿测的一次完整走查理论说多了容易飘。接下来我拿一个典型的 Java 场景走一遍一个基于 Spring Boot 的老项目需要给OrderService增加一个“取消订单并回滚库存”的功能。这个场景我实测过多次也是 superpowers 在新手身上最容易“翻车”的场景因为老项目往往有历史包袱。4.1 第一步让 AI“想清楚”再动手启动后我先不急着说功能而是给 AI 一个短提示在 OrderService 里新增取消订单功能要求回滚库存。 请先用 brainstorming 技能澄清需求不要直接写代码。它很快进入了追问模式给我抛出一堆问题取消订单是否只限待支付状态库存回滚是直接加回去还是走异步消息取消后优惠券要不要退还已发货订单是否允许取消这些问题有些我预设了答案有些我没想到比如“取消后如果原支付是组合支付退款怎么处理”。这个阶段输出的是一份简单的需求确认清单。Java 项目里这么做尤其有价值因为老项目里各种隐含状态特别多少问一个问题后面改起来就是灾难。4.2 第二步生成实施计划需求确认后AI 切换到 writing-plans 技能输出了一份计划修改OrderService.cancelOrder方法新增状态校验在OrderRepository中新增按 ID 和状态查询方法修改InventoryService暴露rollbackStock接口为上述改动编写单元测试新增集成测试覆盖事务回滚行为。整个过程它明确标注了“本阶段不写实现代码”。很多人第一次看这一步会觉得慢但你会发现等 AI 真的开始写代码的时候它不再东翻西翻地找需求也不会有“改到一半发现逻辑冲突再翻工”的情况了。4.3 第三步TDD 红绿循环在 Java 里的具体呈现计划确认后AI 进入编码环节。我观察到它严格遵循了 RED - GREEN - REFACTOR 的循环而且有一个细节做得比很多手动开发者还到位它会先跑一次测试确认失败信息符合预期再开始写实现。# 提示词示例简化 现在执行 tdd 技能为 cancelOrder 方法编写测试。它先在OrderServiceTest里新增了几个Test方法测试待支付订单取消成功、已发货订单取消被拒、库存回滚被调用等场景。然后运行mvn -DtestOrderServiceTest test看到红再补实现。补实现时也是最小改动原则——先让测试过不提前引入缓存、不顺手重构。Java 环境下这个循环特别流畅因为 Maven/Gradle 的测试反馈链路短JUnit 断言信息清晰。对比我见过的一些 Python 项目常见的问题是“测试失败到底是因为功能缺失还是环境不对”Java 项目很少犯这种迷糊。4.4 潜在的坑AI 判定“测试绿了”不等于“测试对”在我多次带跑中出现最多的问题是 AI 会在写测试时“手下留情”——断言写得不够狠导致某个有 bug 的实现也能通过测试。比如测试里只断言返回结果为 null不校验异常类型或者只 verify 了一次 mock 调用不校验具体参数。后来我习惯在提示词里补一句测试必须保证在实现缺失时失败一次在实现错误时失败一次在实现正确时通过。superpowers 的 tdd 技能文档本身也有类似约束但它更偏原则描述。实操中你要在巡检时多看一眼测试代码不能因为是 AI 写的就放松警惕。我的经验是把“测试是否正确”的检查点放在每次重构完成之后由人工快速过一遍测试名称和关键断言。5. 翻车记录接入后最容易踩的五个坑再好的流程用起来也会遇到一些“跟技术文档无关”的坑。这节是我自己在多个项目中实际踩过的教训写出来帮大家少走弯路。5.1 坑一批量克隆了所有技能反而导致行为混乱superpowers 默认技能集很大全量加载到上下文后AI 的提示词空间被占掉不少模型在低上下文窗口下容易出现“选择性失明”——该触发的技能没触发不该触发的反而赢了匹配。解决办法是精简。装完第一个动作应该是删掉你用不到的一半技能特别是那些描述与你的工作流重复度高的。我的习惯是留下 think、brainstorming、writing-plans、executing-plans、tdd、code-review、commit 这几个核心项其他的按需再启。5.2 坑二显式调用和自动触发相互打架当你已经自动进入了某个技能又在对话里显式说“现在执行 xx 技能”AI 有时会重新初始化流程把前面已经完成的步骤推倒重来。最典型的是它已经处于 brainstorming你又说“开始写吧”它会跳过执行计划环节直接写代码。对策是不要人为打断它的技能状态机。你想切换到下一个阶段用更自然的方式表达比如“需求已经确认完了现在出一份实施计划”让它在当前技能框架下推进而不是重新触发一个新技能。5.3 坑三Java 多模块项目里提示词窗口不够用superpowers 的工作流要求 AI 频繁读取多个文件的上下文Java 项目一个模块动辄几十个类提示词窗口很容易爆掉。窗口满之后的表现不是报错而是 AI 开始“假装”它看过某些文件——它基于类名和常识写代码最后编译报错一堆。这种场景我建议做两步一是把任务拆小一次只让 AI 处理一个模块二是给 AI 提供一份精简的代码地图让它只需要主动读取关键文件而不是靠扫描全部源码来猜。5.4 坑四依赖下载慢AI 的耐心先耗尽了Java 项目的 Maven 依赖首次构建动辄几分钟。superpowers 的 TDD 循环要求“写测试 - 跑测试 - 看到失败”这本来是对的但如果环境刷新一次要三分钟AI 很容易在等结果时做多余操作比如顺手改实现、或者直接猜测测试会通过。我对策是提前预热进入开发前先让 AI 跑一次mvn test确认所有依赖已就绪并缓存完毕然后再进入 TDD 环节。同时把测试范围尽量圈定在单模块单类避免每次任务都触发全量构建。5.5 坑五权限配置过宽AI 乱改无关文件superpowers 的执行流程会让 AI 频繁“自己动手”读取代码、修改文件、执行命令。如果终端工具的权限是放开“任意文件可写”它会偶尔做出超范围的改动比如顺手帮你把配置文件的格式改了、把某个测试方法的名称规范化了。这个问题的根源是技能协议只约束“做什么”没有约束“不做什么”。我建议接入后的第一件事是在工作区里显式标注哪些目录是 AI 可以动的哪些只能只读。比如多模块项目里明确告诉它“本次只允许修改 order-service 模块”。最后分享一点个人体会我现在已经习惯在绝大多数项目里开着 superpowers 干活但并不是因为它让 AI 更聪明了。说实话模型还是那个模型逻辑推理能力没有变强。变的是 AI 的工作习惯它不再急着给答案而是先确认需求、列计划、写测试、再实现。在 Java 这种强调可维护性和回归安全的工程环境里这种“变慢”其实是巨大的净收益。我见过太多次 AI 一次性生成几百行代码、结果重构时根本改不动的场景而 TDD 约束之下的代码至少每一次改动都有测试兜底。最后给你一个小技巧如果你觉得某个技能的流程太啰嗦别急着卸载它。试着打开对应的SKILL.md把中间那些“为了引导模型而写的解释性文字”删掉只保留步骤和禁止项。裁剪后的技能文件占用的上下文更少触发速度更快AI 反而更容易严格执行。这大概也是 superpowers 最让我喜欢的一点——它把“如何指挥 AI”的主动权交还给了你自己。