先说结论：Superpowers不是一个能直接装进IDE的插件，也不是OpenAI或者Anthropic官方出的东西。它是一个开源项目，核心资产是一整套经过大量实战打磨的系统提示词、技能文件和工作流约定。你把它接入ChatGPT、Claude或者Codex之后，AI的行为方式会发生肉眼可见的改变——从“你问我一句它答一段”变成“先理解任务、再列计划、后动手实现、最后自己写测试验证”。这个改变，就是项目名字里powers的来源。

如果你只是偶尔让AI生成个正则表达式，那Superpowers对你来说可能偏重。但如果你像我一样，要拿AI去维护一个几万行的Java老工程，或者让AI和你在同一个代码库上持续迭代几周，那这套提示词带来的体验不是“换了个聊天风格”，而是“换了个队友”。下面这篇内容，我会尽量少讲虚的，多讲实际接入和使用过程中踩过的坑，尤其是接入Codex CLI、Claude Project以及拿它写Java工具的具体过程。

1. 先搞清楚Superpowers是什么：它不是插件，是一套AI编程工作流

1.1 为什么普通AI写代码总差一口气：从“问答模式”说起

很多人第一次用ChatGPT写代码的感受是：哇，好厉害；第二次的感受是：嗯，能跑；第三次的感受是：怎么又要从头解释一遍需求。问题不在模型本身，而在使用方式。默认状态下，你打开一个AI对话窗口，本质上是在和一个“知识量很大但记忆很短”的问答机器人打交道。它没有项目上下文，不知道你之前定了什么技术选型，不理解你为什么在A文件里用了这种风格而在B文件里用了另一种，更不会主动去验证它写出来的代码能不能编译、测试能不能通过。

所以大多数AI辅助编程的痛点可以归结为四句话：上下文存不住、计划容易丢、技能不可复用、写完了不负责。所谓不负责，就是它给你一段代码就收工了，编译报错？测试挂了？它不知道，因为没有人要求它知道。Superpowers要解决的，就是把一个“问答机器人”重新训练成“结对编程搭档”，核心手段不是微调模型，而是用系统提示词和工作流文件给AI立规矩。

1.2 Superpowers项目长什么样：核心文件与目录拆解

这个项目在GitHub上以仓库形式存在，作者是Jesse Vincent（网上常见ID是obra）。我拿到仓库后第一反应是：东西不多，但每一行都有讲究。整体结构大致是几个核心Markdown文件加若干目录，核心文件负责定义AI的“角色和操作守则”，目录里面放的是可加载的技能包、计划模板和示例项目。

引用一段我实际对照过的目录布局思路：

• 根目录的系统提示词文件，这是整个工作流的发动机，规定了AI在不同阶段必须做什么、不能做什么；
• skills目录，存放一个一个独立技能，比如“写Java单元测试”“分析Maven依赖冲突”“整理Git提交信息”，每个技能对应一个SKILL.md文件；
• plans目录，存放AI制定的行动计划，AI会把大任务拆成多步并写入计划文件；
• 剩余的examples目录，用来展示在真实项目里怎么落地这套约定。

很多人误以为Superpowers是某个具体的工具App，其实它在不同AI环境里形态不同。在ChatGPT里可能只是一段Custom Instructions；在Claude里是Project Instructions；在Codex里则变成AGENTS.md文件。它不绑定任何大模型平台，设计哲学是：哪套AI能看懂Markdown，它就能跑在哪套上。

1.3 它给AI补上了哪四块短板

用自己的话总结，Superpowers的核心贡献是四件事。

第一，上下文管理。它要求AI在开始干活前，先读项目里已有的说明文件，比如README、架构文档、依赖清单，把项目信息统一收拢到自己的“工作记忆”里，而不是每次对话都等着用户重新解释。

第二，任务规划。它强制AI在多步骤任务开始前输出一份计划，把目标分解成可验证的小步骤，而不是一口气生成几百行代码然后祈祷它能跑。

第三，技能复用。把工作中反复出现的场景，比如“给这段Java代码写Mockito测试”“用jstack排查线程问题”，固化成技能文件。下次遇到同类问题，AI直接加载技能而不是从头摸索。

第四，自我校验。它让AI在写完代码后主动执行编译、运行测试、检查静态分析结果，甚至扮演一个挑剔的Code Reviewer来审自己的代码。这四件事叠加起来，AI的干活方式就从“写代码”变成了“交付功能”。

2. 核心机制拆解：为什么一套提示词能让AI脱胎换骨

2.1 角色与流程约束：把AI从“实习生”变成“老工程师的思路”

系统提示词的本质是“约束”，约束越多，AI的行为越可控。Superpowers对AI的角色定义很有意思：它不让AI当“全能专家”，而是让AI当“结对编程中的合作者”。这个定位有一个实际好处——AI不会再为了显得专业而一本正经地胡编，遇到不确定的地方它会主动说需要确认。

在流程层面，它用了一套类似软件开发流程的阶段划分：理解需求、澄清假设、制定计划、实现、测试、修复、复盘。每次交互都按这套流程走。我自己做技术负责人时经常跟新人说“你先别写代码，把思路讲出来”，Superpowers对AI做的也是这件事。它在提示词里明确写：开始编码前，必须复述你对任务的理解，列出不确定点，并且输出计划。这一下就把AI从“答题机器”变成了“能说清楚自己打算怎么干的工程师”。

角色与流程约束最容易被忽略的细节是“必须在计划中注明验证方式”。Superpowers要求AI在计划阶段就明确“我做完这一步之后怎么证明自己做对了”，可能是一条测试命令，可能是一个接口返回数据的核对。这一步对漫长的多文件改造尤其重要，因为验证方式一旦提前定死，AI后面就没法偷懒跳过收尾工作。

2.2 Skills技能卡：让AI“会的东西”变成可加载的文件

我对Skills这个机制的评价是：它才是Superpowers真正值钱的地方。系统提示词再好，也不可能把所有领域的知识都写进去，token消耗也不允许。所以项目设计了一套技能加载机制：把特定任务的执行方法、注意事项、代码范式写进一个SKILL.md文件，当AI判断当前任务命中技能描述时，就去读取对应文件，按文件里的规范工作。

举个例子。我给它准备了一个“Java Spring Boot接口开发”技能，里面写了项目的包结构规范、Controller层和Service层的划分方式、异常处理的统一封装模板、以及写接口测试时需要Mock哪些依赖。以前AI写Controller时会在四五个风格之间随机切换，加载这个技能之后，它产出的代码风格基本稳定，review成本大幅降低。

技能文件还有触发阈值设定。AI会根据用户提问判断是否读取技能，判断依据完全靠技能文件开头那段“适用场景描述”写得好不好。所以如果发现自己加载了技能却没什么效果，大概率是那段描述写得模糊，AI没意识到当前任务属于这个技能的管辖范围。这是一个需要反复调优的细活。

2.3 Plans行动计划：AI怎么做到先想清楚再动手

Superpowers对长任务的解法是“写计划，保存计划，按计划执行，更新计划”。AI在接到复杂需求时，先在对话里生成一个阶段性的计划，包含目标、步骤、验证方式、风险和依赖，然后把它保存为项目内的工作文件。

这个机制解决了一个特别实际的问题：大模型的上下文窗口再大也是有限的，一个五天的改造任务根本不可能一直塞在对话里。有了计划文件，就算中途关闭对话、切换模型、或者上下文被token截断，AI都不至于完全失忆。它每次开工只需要先读取计划文件，就知道项目进行到哪一步了。

实际体验下来，计划文件对人也同样有价值。以前我同时会开三五个AI对话来推进不同模块，经常搞混哪个需求在哪个窗口里。现在每个项目根目录有一份plan.md，AI会同步更新进度，我打开文件就能看到当前状态。这相当于给了我一个免费的“项目管理仪表盘”，而且是AI自动维护的。

2.4 自我反思循环：AI写完代码为什么还要自己打脸

这一条是Superpowers和其他普通提示词拉出差距的地方。它明确要求AI在完成实现之后进入反思阶段：编译过了吗？测试过了吗？有没有边界条件没覆盖？我写的这个类职责是否过于臃肿？随后AI要主动把这些反思结果和修复动作追加到工作记录中。

我第一次看到AI自己指出来“我刚刚实现的这个方法有一个并发隐患”时，说实话有点恍惚。原来不是模型不会发现问题，而是它默认你不要求它反思。一旦把“自我质疑”写进工作流程，大模型在逻辑层面的推理能力就会真正被用在代码审查上。

这个机制也改变了我的使用习惯。以前我拿到AI写的代码，第一件事是自己跑测试，跑挂了再回来贴报错让它修；现在我会在提示词里直接要求AI交付时附带“我已经执行了哪些验证命令以及结果”，它拿不出来就说明没干活。效率提升是其次，更关键的是信任感建立起来了，我敢让它独立完成更多模块。

3. 接入实践：在Codex CLI和Claude里装好Superpowers

3.1 不同AI工具接入方式一目了然

很多朋友卡在第一步：项目看懂了，但不知道怎么往自己的工具里装。这里给一张我实际验证过的对照表，不同AI产品接入方式差异挺大，搞错了容易白折腾。

3.2 Codex CLI完整接入步骤

Codex是OpenAI的命令行编程智能体，现在的Codex可以读取仓库里的AGENTS.md作为行为约束。我的接入过程大致是这样的。

第一步，安装Codex CLI并完成认证，这一步官方文档写得很清楚，直接装就行。第二步，在项目根目录创建AGENTS.md，里面用一段简短的引用语句指向Superpowers的核心系统提示词文件。我习惯直接复制核心提示词进来，不搞目录引用，省得工具不支持跨目录读取导致AI“睁眼瞎”。

第三步，在项目里创建skills目录，把自己准备的技能文件放进去，同时在AGENTS.md里明确告诉Codex：遇到某类任务时需要去查阅对应技能文件。第四步，跑一个最简单的验证任务，让AI解释当前项目结构，看它能不能准确说出项目里有哪些模块、用了什么框架。如果它回答得像没读过代码一样，检查AGENTS.md路径对不对。

接入完成之后的日常用法很简单：直接在这个目录下启动Codex，用自然语言下需求。它会按Superpowers的流程走一遍计划、实现、验证的循环。我目前的经验是，工作流体积越大、涉及文件越多，Codex+Superpowers的配合就越值。

3.3 Claude Project接入步骤

如果你主力用的是Claude，接入原理一样但渠道不同。在Claude的Project里，右侧项目配置有一个Instructions区域，Superpowers的系统提示词全文就贴在这里。然后新建一个skills专用目录，把SKILL.md逐个上传为项目知识文件，Claude会自动把它们当成参考文档。

需要注意的坑是：Claude项目知识库的检索是向量化匹配，不是每次对话都把所有文件都读一遍。所以你描述的技能“适用场景”影响很大，描述写得泛泛，AI就认为当前任务和它没关系。我后来把技能描述改成了带项目真实术语的触发词，比如“定时任务”“Quartz”“Cron表达式”这种强行挂钩，命中率才上来。

还有一个建议：Claude项目本身有上下文长度限制，Superpowers完整提示词加技能文件会占掉很多上下文空间。实际项目中我只保留核心提示词和当前阶段真正需要的两三个技能文件，其他技能放一个存档目录，等要用时再手动拖进来。这样既保住了工作流，又不至于让AI被太多背景信息拖慢响应。

3.4 最小可用配置：5分钟跑通一个项目

如果不想一上来就搞全套，可以按最小可用配置先体验。做法很简单：复制核心系统提示词，粘贴进你的AI工具；不挂任何技能文件；在项目根目录丢一个最简AGENTS.md，里面只写一句话——“用Superpowers工作流处理本项目需求，详细规则见系统提示词”。

这个配置下AI已经会表现得不一样。它会主动复述需求、列出计划、先写测试再写实现。我先是用这个最小配置跑了几个小项目，确认工作流符合预期之后，才逐步加技能、加计划文件。缓和一点的好处是，出问题时容易定位——工作流没生效是提示词没粘贴对，技能没生效是技能文件本身的问题，不会互相甩锅。

跑通后可以进一步验证：把同一个任务分别用默认模式和Superpowers模式各跑一遍，对比一下AI交付物。我在Java项目上做过这个对比，默认模式给了一坨“看起来差不多但一跑就挂”的代码，Superpowers模式则在我指出编译错误前就自己跑了mvn test并把失败用例修好了。这个差异化体验就是对工作流价值最好的证明。

4. 实战记录：我用Superpowers写了一个Java工具

4.1 第一步：把项目背景喂给AI

为了写这篇博客，我专门用Superpowers搭了一个Java命令行小工具，需求是这样的：读取一个CSV格式的银行流水文件，按支出分类汇总，最后打印分类金额和占比。技术约束是Java 17、Maven构建、不允许引入重量级框架、需要单元测试。

我没有直接丢需求给AI开写，而是先把项目背景整理成了一段上下文：代码仓库位置、构建方式、CSV样例字段、期望输出格式。然后在项目根目录放好AGENTS.md，启动了Codex。第一次提问我故意问“这个项目现在是什么状态”，AI正确读取了README和pom.xml并给出了结构摘要，说明上下文注入成功。

接下来我提出了核心需求，AI没有立刻甩代码，而是先输出了一段“需求理解”：它复述了CSV解析、分类逻辑、统计输出三部分，并且列出了两个待确认问题——分类关键字是用预设规则还是配置文件？金额字段精度用BigDecimal还是double？这两个问题问得非常准，直接决定了后面代码的形态。我回答了“预设规则用枚举”和“金额用BigDecimal”，它才开始进入计划阶段。

4.2 第二步：AI给出的实施计划长什么样

AI输出的计划分成了四个阶段：准备阶段、解析实现阶段、统计实现阶段、测试收尾阶段。每个阶段下面都标注了具体文件和验证命令，比如“实现TransactionParser，验证命令：mvn -Dtest=TransactionParserTest test”。它还主动提出用OpenCSV库来做CSV解析，并标注了要在pom.xml里添加的依赖坐标。

最让我满意的是它主动写了风险项：CSV文件可能出现空行、非法金额、未知分类，这些情况需要容错处理。它在计划里明确把这些边界情况作为测试用例列出，而不是写完再说。这一步很像一个正经工程师在排期时的思考方式。

计划落地后，我把它保存为plan.md放在项目根目录，方便后续对话继续加载。这种把“思考内容”落盘的方式是Superpowers工作流和普通AI对话最大的区别之一——AI的思考过程不再一次性蒸发，而是变成了可追溯的项目资产。

4.3 第三步：代码生成、测试与迭代完整过程

进入实现阶段后，AI先写了pom.xml，加入了Maven Surefire插件、JUnit 5依赖、OpenCSV依赖。然后写了CSV解析类，我注意到它的类设计分了三层：模型层、解析层、统计层，并没有把所有逻辑堆在一个类里。这在AI生成代码里挺难得，很大程度得益于提示词里对“单一职责”的强制要求。

关键代码片段的封装风格如下，这是AI实现的解析方法开头：

public Transaction parse(String line) { String[] fields = line.split(","); if (fields.length != 4) { throw new IllegalArgumentException("非法流水行: " + line); } BigDecimal amount = new BigDecimal(fields[2].trim()); ... }

它写完后没有直接说“完成”，而是自己跑了mvn test，生成了五个测试用例，覆盖了正常解析、空行跳过、金额格式错误、未知分类、边界值等场景。第一次运行发现有一个用例因为时间日期格式解析失败而红，AI立刻读取了报错信息，定位到是SimpleDateFormat线程安全问题，然后把解析器改成了Java 17的DateTimeFormatter，重新跑全绿。

整个迭代过程大约持续了二十分钟，我基本只在旁边看它“自驱循环”。最终产物除了工具本体之外，还包括一份简短的README和一组测试数据文件，后者是它自己生成用来验证分类统计结果的。这个交付完整度，远不是普通对话模式能达到的。

4.4 这轮实战的收益与槽点

收益很直观：我拿到了一份能运行、有测试、有文档的小工具，而且整个过程的协作体验像在带一个“尽管经验一般但态度极好”的初级工程师。它的自我验证习惯帮我省去了大量往返“贴报错”的沟通成本。

但槽点也得说。整个过程消耗的token是普通模式的几倍，因为AI每次都要先读计划文件、复述理解、再列计划，一套流程走下来确实“说话多”。另外它对大型工具库的版本选择偶尔会保守，比如OpenCSV依赖它选了旧版本，还是我后来手动升的。所以Superpowers不是银弹，它更像一个“流程放大器”：模型本身如果基础能力不行，加了流程约束只会让糟糕的代码被包装得更完整，使用时还得自己盯质量。

5. 常见问题与排查技巧实录

5.1 Token消耗暴涨怎么控制

几乎每个刚开始用Superpowers的人都会问：为什么我的对话这么快就超限了？原因很简单，系统提示词本身就是一笔固定开销，再加上AI每次回复都会输出更多“过程性内容”——计划、复述、反思，token消耗自然成倍上升。我在Java项目的实战中大约估算过，同样的功能需求，Superpowers模式消耗的token是默认模式的4倍左右。

控制方式有几个。第一，精简提示词，把与自己项目无关的段落删掉，只保留角色定义、流程约束、验证要求三块。第二，技能文件按需加载，不要一股脑把所有技能都塞进上下文。第三，把大任务拆小，比如先让AI完成数据层再完成接口层，而不是一个指令要求它把整个系统都写完。第四，如果你的工具支持，可以关闭AI的“幕布式思考输出”，只让它输出结论和计划摘要，能省不少钱。

5.2 AI不按套路出牌怎么办

有时候你明明把提示词都配置好了，AI却还是像失忆了一样直接回答，不走流程。这个问题的排查顺序很固定。第一，确认提示词是否真的被加载——在对话里直接问“你现在需要遵守的规则是什么”，看它能不能复述出关键流程。第二，确认有没有其他系统级别指令与Superpowers冲突，尤其是IDE类工具内置的默认提示词，优先级可能比你自定义的高。第三，确认项目根目录的AGENTS.md是不是被工具忽略了，有些工具只认特定路径下的规则文件。排到第三步时才考虑模型本身问题，不要一上来就怀疑模型不行。

还有一种常见情况是AI“假流程”——嘴上说着复述需求、列出计划，实际却跳过测试直接给最终代码。这种属于提示词里的软约束被模型钻空子。我的对策是在系统提示词里把验证动作写成硬性输出要求：“在回复的末尾附上你执行的验证命令和输出结果，如果没有执行验证，明确写‘未验证’”。一旦有这个硬要求，AI很难继续假装。

5.3 技能文件不生效是什么原因

技能文件加载不上，先自己检查三个地方。一是文件命名，Superpowers约定技能文件名就是SKILL.md，放在以技能命名的子目录里，目录名不要用中文和空格。二是描述与触发词，技能文件开头需要用明确场景描述当前技能解决什么问题，AI要靠这段描述判断何时加载，写得太模糊就永远加载不上。三是工具本身的检索机制，Claude项目知识库和Codex仓库读取方式不同，前者是向量匹配，后者是关键词检索，技能描述要根据平台微调。

如果确认以上三点都没问题还是读取不到，可以做一个直接的验证命令：“你拥有哪些技能？请逐一列出。若没有请说明原因。”AI如果回答“当前环境未提供任何技能”，那大概率是提示词里对技能库路径的引用写错了，检查AGENTS.md里的目录路径是否和实际仓库结构一致。

5.4 什么时候该果断放弃Superpowers

不是所有任务都适合上Superpowers。我自己的判断标准是：任务越接近“探索性提问”，越不该用完整工作流。比如你想让AI解释一段陌生代码的逻辑、临时写一个一次性脚本、或者做几个技术方案的优劣对比，这些场景开普通模式就够了。Superpowers的流程约束在这种轻任务里只会增加回复长度，不会增加信息量。

另外，如果你的模型是使用量受限的免费档，token消耗就是现实瓶颈。我在轻量任务上尝过强行使用Superpowers的苦头——AI把大量上下文花在“列计划”和“写反思”上，真正的有效输出反而不够。这时候果断切回普通模式，不是打脸，是合理的工具选择。

6. 使用一段时间后的大实话：好用的地方、坑、以及我的建议

6.1 适合谁用，不适合谁用

用了大约两个月之后，我对适用人群有了比较清晰的判断。适合的人主要有三类：一是要维护多文件项目的开发者，上下文断裂问题被计划文件机制治得服服帖帖；二是需要AI产出高质量交付物的团队，测试先行和自我校验能显著提高代码的可信度；三是经常和AI进行长周期协作的技术负责人，Superpowers把AI变成了可追溯的协作对象，而不是一个每次都要重新培养的临时工。

不适合的人也有三类：完全不了解自己代码库的新手，AI输出计划时连验证命令都看不懂，收益无从谈起；追求“一句话生成整个应用”的玩家，Superpowers强调分步骤交付，体验反而觉得冗长；以及每次任务都控制在十分钟内的轻量用户，流程开销大于收益。

6.2 我的固定工作流模板

经过反复调试，我现在稳定的工作流是这样的：项目初始化时，让AI在根目录生成AGENTS.md和plan.md，AGENTS.md包含Superpowers核心规则，plan.md记录项目目标和当前进度。每天开工先让AI读一遍plan.md，然后基于今日任务输出更新后的子计划，代码实现和测试同步进行，每个功能点完成后由AI跑一次全量测试并更新计划文件。

这个模板在Java后端项目里运转得最顺，因为Maven和JUnit提供了稳定的“验证命令基础”，AI很容易获取反馈信号。在纯前端项目里效果也不错，但前端构建工具链的配置碎片化严重，AI经常要把更多精力花在处理构建上。如果你做的是数据科学类的Notebook脚本，体验反差比较大，一套流程下来可能大部分token都花在环境解释上，建议按实际场景裁剪。

6.3 最后分享三个让我效率翻倍的小技巧

第一个技巧：给AI喂“坏例子”。技能文件里不要只写“应该怎么做”，还要写“这个项目里曾经踩过的坑”。我把真实遇到过的并发问题、时区问题写进技能文件后，AI在生成代码时就会主动避开这些雷区，效果远好于抽象规范。

第二个技巧：把AI当成代码审查者而不是代码生成器。Superpowers模式下我会经常让AI“review一下我同事最近提交的这段代码，指出潜在问题并给出修改建议”。这种用法比让AI写新代码更能发挥它的知识面优势，而且不消耗修改代码所需的“试错预算”。

第三个技巧：每个重要决策让AI给出“如果不这么做会怎样”的后果分析。Superpowers提示词里鼓励AI多角度分析，用起来之后我再也没有遇到“AI拍脑袋选技术方案”的情况。它会自动列出放弃备选方案的风险点，让我在决策前看到完整的信息面。

总的来说，Superpowers给我的最大改变不是“AI写的代码变好了”，而是“AI的做事过程变得可见、可控、可复盘”。这份过程性价值，在复杂项目里比代码本身更珍贵。如果你也想找一个稳定的AI协作方式，从把核心提示词粘进你的项目开始，很快就能感受到差别。