如果你用过 Claude Code、Codex 这类 AI 编码助手大概率遇到过同一个问题模型很聪明但没规矩。让它写个函数唰唰两下就出来了让它排查一个线上问题却经常东一榔头西一棒子给出一个看似合理、实际经不起推敲的结论。superpowers 这个开源项目就是冲着这个痛点来的。它不是一个新模型也不是某个 IDE 插件而是一套面向 AI 编码助手的“技能系统”把系统化排查、测试驱动开发、需求澄清、计划拆解这类工程方法封装成一个又一个 Markdown 技能文件让 AI 在合适的场景下自动按流程办事。名字起得很直白——装上它助手才算真正有了超能力。这篇文章会从机制原理、安装配置一路讲到 Java 项目和 Codex 场景下的实战尽量把能踩的坑也一并说清楚。1. 先从“AI 有知识但没章法”说起superpowers 解决什么问题1.1 用过 AI 编程助手的人都懂那种失控感我最早接触 Claude Code 和 Codex 的时候感觉确实惊艳但用久了就发现一个尴尬的事实单次对话里让它修一个 bug效果很好让它从头到尾负责一个完整任务它就开始“自由发挥”了。比如我让它修一个 Java 空指针异常它会直接给出一段 try-catch 或者Optional.ofNullable的代码。代码本身没错但它没有先想清楚空指针到底是在哪一层产生的是上游传参没校验还是框架序列化的问题又或者是某个异步线程里丢了上下文AI 不是不知道这些可能性而是它默认选择了“最短路径”——直接改代码而不是先定位根因。这类问题的根源不在于模型能力不够而在于 AI 缺少一套稳定的“行为准则”。人写代码有规范、有流程、有 checklistAI 只有概率和上下文。superpowers 就是把这个空缺补上让 AI 不再凭第一反应行动而是像一个有经验的老工程师一样先在脑子里过一遍该做的事情。1.2 superpowers 到底是什么superpowers 是一个开源项目核心是一套“技能库skills”加上配套的加载机制。每一个技能都是一个 Markdown 文件里面写了这个技能的名字、适用场景、使用步骤和注意事项。AI 助手在对话中会读取这些技能判断当前任务是不是匹配某个技能匹配了就按照技能里的步骤执行。听起来很抽象举个例子。项目里有一个类似“systematic-approach”的技能它的核心思想是遇到复杂问题时不要急着给答案先收集信息、建立假设、设计验证、再动手。打开这个技能文件AI 会先问你要日志、要复现步骤、要最小测试用例而不是直接甩代码。这其实不是什么黑科技而是把人类工程师的思维过程显性化、文本化再喂给 AI。妙处在于技能文件是普通 Markdown谁都能看、谁都能改你可以把团队自己的 code review 规范、发布检查清单、公共库使用约定全部写成技能让 AI 也遵守。1.3 适合哪些人去用如果你是个人开发者用 Claude Code 或 Codex 写点小脚本、折腾点个人项目superpowers 能让你少踩不少“AI 自作主张”的坑。如果你在团队里做 AI 辅助开发天天要喂给 AI 一堆上下文、重复交代同样的规矩这套东西就更值得试试——把规矩沉淀成文件让 AI 自己读比每次手敲要好得多。我后面讲的安装和实战默认你已经有 Claude Code 或 Codex 的基本使用经验。如果还没有建议先随便做一个小项目跑通基础流程再回来看这篇文章不然同时接触的新概念太多容易乱。2. 技能Skill的工作机制一个 Markdown 文件如何改变 AI 行为2.1 技能文件长什么样一个技能本质上是一个目录目录里放一个SKILL.md文件文件名可能因平台略有差异但思路一致。文件开头是 YAML 格式的 frontmatter用来描述技能的元信息下面是正文用来写具体的操作步骤。我简化一个例子给你看看结构--- name: systematic-debugging description: 当用户报告一个 bug且原因不明确时使用。先收集信息和复现步骤再定位根因最后修复并验证避免直接猜测。 when_to_use: 适合处理偶发、难以复现、涉及多模块联调的问题 --- # 系统化排查流程 1. 让用户提供完整的错误信息和复现步骤不要先给修复代码。 2. 根据错误信息列出所有可能的原因按可能性排序。 3. 设计和运行最小实验逐项排除可能原因。 4. 确认根因后再讨论修复方案。 5. 修复后给出验证方法确保测试通过。 ...看到关键了吗description和when_to_use就是 AI 的“触发器”。AI 在对话中会定期扫一遍已加载的技能判断当前用户请求是否和某个技能的描述匹配。匹配了就加载这个技能的内容后面的回答就会按照技能里的步骤走。2.2 AI 是怎么决定调用哪个技能的这里有个很关键的机制AI 不是把所有技能文件全部塞进上下文那样内容太长既浪费 token 又分散注意力。实际做法是AI 助手维护一个技能索引——每个技能只保留名字、描述和适用场景需求量很小。每次对话时AI 把当前任务和这些索引做匹配只把命中的技能正文加载进来。所以你会发现技能文件的description写得清不清楚直接决定 AI 能不能在正确的时候用它。如果你写得太模糊比如“处理问题时使用”AI 几乎在所有场景都想调用它反而干扰正常对话如果你写得太具体比如“当用户输入 java.lang.NullPointerException 时使用”那换一种异常它就不认了。最稳妥的写法是描述“场景”而不是描述“关键词”。2.3 和写 prompt 有什么区别很多人会说这不就是把一段 prompt 提前存好吗我自己复制粘贴也一样。区别还挺大的。第一prompt 是你主动给的技能是 AI 主动触发的。你粘贴 prompt相当于每次都要记得“哦这种情况我得把排查流程发给 AI”但人类的记忆是最不可靠的。技能机制把“判断时机”这件事也交给了 AI虽然 AI 的判断偶尔不准但整体上比你全靠脑子记要可靠。第二技能可以组合。一个复杂任务往往不是只靠一个技能比如“先用到需求澄清技能再切到计划拆解技能最后用 TDD 技能写实现”。AI 可以按顺序加载多个技能形成一条完整的作业流水线。这比自己手写一大段混合 prompt 要灵活得多你不需要在写 prompt 时就想好所有排列组合。第三技能是结构化的可以团队共享、版本管理。代码仓库里放一份技能目录所有人 clone 下来就有同样的 AI 行为规范。你改了一版同事 pull 一下就同步了。Prompt 呢大概率散落在每个人的聊天记录和笔记里。2.4 技能的加载位置全局、项目、会话superpowers 这套体系里技能可以放在几个不同层级。全局技能目录也就是存在用户主目录下对所有项目生效。适合放通用技能比如系统化排查、代码审查、提交信息规范。项目级技能目录放在某个仓库内部只对本项目生效。适合放项目特有的规范比如“这个服务必须走某些 API 封装”“数据库表结构变更必须先生成迁移脚本”。会话级技能是在对话中临时指定或由 AI 动态生成的。有些任务很特殊比如“这次修复必须同时更新文档和单元测试”你不想为此专门建一个技能文件就可以在对话里把要求说清楚让 AI 把它当临时的行为准则。刚上手的时候我建议你只用一个全局目录把所有技能都丢进去。等用了一段时间发现某些技能只在特定项目里有意义再往项目目录里挪。3. 装好你的第一组技能安装、目录布局与验证3.1 先理解安装的本质superpowers 的安装方式看起来有好几种有一键脚本、有插件市场、有手动 clone但本质都一样——把技能文件放到 AI 助手能扫到的地方。搞明白这一点你就不会被各种安装命令搞晕。以 Claude Code 为例它有一套技能目录机制AI 启动时会扫描指定目录下的技能文件。以 Codex CLI 为例它也能读取用户目录下某个技能集合目录。你只要让 superpowers 仓库里的技能和这些目录建立关系就行。如果你愿意用官方推荐的方式去项目 README 里找对应的安装命令照着执行即可。我个人更推荐手动方式因为你能看清楚到底装到了哪里后面排查问题会方便很多。3.2 手动安装的通用步骤下面这套步骤不依赖某个特定平台的特殊命令只需要一个 Git 客户端把 superpowers 仓库克隆到本地某个目录比如~/superpowers。查看仓库结构找到存放技能的那个目录通常叫skills/或类似名字具体以仓库实际结构为准。在你的 AI 助手的技能配置目录下创建一个软链接指向刚才的技能目录。例如你的 AI 助手的技能目录是~/.claude/skills那就可以做这样一个链接mkdir -p ~/.claude/skills ln -s ~/superpowers/skills ~/.claude/skills/superpowers如果是 Codex CLI常见技能集合目录可能是~/.codex/skillsets那么mkdir -p ~/.codex/skillsets ln -s ~/superpowers/skills ~/.codex/skillsets/superpowers这里要提醒一句不同版本的 AI 助手技能目录的具体位置和命名会有差异。你不需要死记硬背路径关键是搞明白“我要把技能文件放到 AI 扫描的那个目录里”这个逻辑。官方文档里如果提到某个目录那就是它。3.3 目录布局技能和普通文件怎么共处装好之后你的技能目录大致会长这样skills/ ├── superpowers/ │ ├── brainstorming/ │ │ └── SKILL.md │ ├── systematic-debugging/ │ │ └── SKILL.md │ ├── test-driven-development/ │ │ └── SKILL.md │ └── ...每个子目录就是一个技能SKILL.md是它的主文件。有些技能可能还附带模板、示例代码、参考文档它们会放在同一个技能目录下AI 在加载技能的时候可以一并引用。这里容易出现一个误解以为技能文件越多越好。并不是。技能加载要消耗上下文空间虽然索引只读描述但当 AI 需要做匹配时描述文本也会占掉一部分注意力。装个几百个技能AI 可能连“在正确的场景调用正确的技能”都做不好。superpowers 仓库本身带的技能数量是经过权衡的你在此基础上做减法而不是无脑加。3.4 怎么验证技能真的生效了装完先别急着干活花两分钟验证一下。最简单的办法是直接问 AI 一句你手上有哪些技能可以调用如果 AI 能列出你刚装的那些技能名字和适用场景说明加载成功了。如果 AI 说“我没有技能”或者“我不太清楚”不用慌先检查几个地方技能文件有没有放在 AI 实际扫描的目录里软链接路径是否正确SKILL.md文件名拼写是否正确大小写是否敏感frontmatter 格式是不是合法的 YAML有没有多写或少写了冒号是不是修改完后没有重启 AI 会话部分助手只在启动时扫描一次目录。我自己第一次装的时候就是忘记重启会话折腾了半天以为自己装错了其实只要新开一个对话就好了。3.5 团队共享把技能放进 Git 仓库superpowers 很适合团队使用但没必要让每个人都在自己机器上手动跑一遍安装脚本。更省事的做法是把技能目录作为一个子模块或者直接把技能文件复制到你团队的代码仓库里放在.ai/skills之类的位置。然后在团队文档里写清楚AI 助手的技能目录指向仓库里的.ai/skills。新同事入职clone 完代码就顺带有了一整套 AI 行为规范不用额外配置。后续任何人更新了技能提交、评审、合并整个团队的 AI 行为就一起跟着升级了。要注意的是技能文件会被 AI 直接读取写的内容要尽量中性、客观别把个人偏好和情绪化的表达写进去。不然 AI 会把这些风格也学走回答问题时措辞变得很怪。4. 实战用技能解决真实的 Java 项目问题4.1 为什么 Java 场景特别能体现技能的价值很多编程语言里AI 犯点错影响不大但 Java 不太一样。它的项目结构复杂、框架多、编译链长一个 NullPointerException 的背后可能藏着 Spring 代理失效、序列化丢失、异步线程上下文缺失等各种原因。如果 AI 没有系统化排查的习惯很容易被异常堆栈的表面信息带偏。superpowers 的技能库里恰好有和排查、测试、设计相关的能力配合 Java 项目使用非常合适。我下面用三个具体场景来拆解你可以直接照着这个思路在你自己的项目里去试。4.2 场景一空指针异常先按住 AI 想改代码的手假设你给 AI 报了一个 bug线上某个接口偶发java.lang.NullPointerException堆栈指向某行user.getOrders()。没有技能加持的 AI大概率会回复你“可以在调用前加一个空判断使用Optional.ofNullable(user)。”不能说错但它没有回答最核心的问题user 是哪里来的为什么大部分请求都正常只有这一个偶发加载了 superpowers 里的系统化排查技能后AI 的回答路径会完全不一样。它会先向你索要以下信息完整异常堆栈而不只是出问题的那一行触发接口的入参样例该接口最近的变更记录是否只在特定流量、特定时间段出现有没有对应的 traceId能否把前后链路串起来。当你把这些信息给它它会列出几个假设可能是上游服务传参遗漏可能是缓存里存了过期对象也可能是并发场景下某个共享变量被置空。然后它会给每个假设配一个验证方法比如检查入参日志、看缓存 key 是否命中、压测复现。直到假设被验证它才会开始写修复代码。这个过程和我手动排查问题的思路一模一样。区别只在于以前我每次都要在 prompt 里长篇大论地教 AI 怎么做现在一个技能文件就全搞定了。4.3 场景二给 Java 老代码补测试靠 TDD 技能稳住质量给 AI 下“帮我给这段 Java 代码写单元测试”的指令很多 AI 会直接生成一堆 Mock 到底的测试断言写得天花乱坠但根本不能验证真实业务逻辑。superpowers 里的测试驱动开发相关技能会强制 AI 走另一条路先分析被测方法的输入边界、依赖项和异常路径明确每个测试用例要验证什么行为而不是为了覆盖率而写先写会失败的测试再写最小实现让测试通过最后重构并确保测试一直通过。举个具体例子。假设有一个计算订单折扣的方法public BigDecimal calculateDiscount(Order order) { if (order.getTotalAmount().compareTo(BigDecimal.valueOf(1000)) 0) { return order.getTotalAmount().multiply(BigDecimal.valueOf(0.1)); } return BigDecimal.ZERO; }普通 AI 可能直接给一个 happy path 测试就完事了。技能加持后的 AI 会先问你几个问题order为 null 时应该怎么表现totalAmount为 null 时会怎样折扣结果有没有四舍五入要求金额为负数时呢然后它会把这些边界条件全部整理成参数化测试再一起提交。这种“先明确行为再写测试最后补实现”的顺序就是 TDD 技能的核心价值。它不是让 AI 多写了几个测试而是让 AI 在动手之前把“这个代码到底要做什么”这件事给想清楚。4.4 场景三新功能从模糊需求到落地拆解Java 项目里接需求是家常便饭但那种“帮我在用户中心加一个订单导出功能”式的模糊需求最容易让 AI 翻车。你没有给它边界它就会自己脑补一个完整方案导出 CSV、增加查询接口、加权限校验、写定时任务清理临时文件……听着很全但跟你真正想要的可能完全不是一回事。superpowers 里有类似 brainstorming 和 planning 的技能专门治这种问题。AI 接到模糊需求后不会立刻写代码而是先列出一堆澄清问题导出数据的规模有多大几万条和几百万条的处理方案完全不同导出是同步返回文件还是异步生成后通知下载允许导出的数据范围是按角色过滤还是按用户自己选的条件导出格式是 CSV 还是 Excel需不需要按字段做本地化这个功能有多少优先级先出 MVP 还是直接做完善版你回答完这一轮它才进入方案设计阶段输出接口定义、数据流、任务拆分、实施顺序。最后才动手写代码。这样下来AI 生成的代码和你的预期高度一致返工率极低。4.5 Java 技能使用中的性能与上下文管理Java 项目往往涉及很多类、很多依赖AI 在加载技能之外还需要读取具体代码文件。这时候有个常见问题技能文件如果写得过于冗长会把上下文撑爆AI 反而没有空间去读你的业务代码。经验是技能正文控制在核心步骤和关键提醒把扩展资料放在附属文件里。比如SKILL.md里只写“1. 收集堆栈2. 列出假设3. 逐项排除4. 验证修复”把“JVM 线程 dump 怎么分析”“Spring 代理失效的典型场景”这样的详细内容放到同目录下的另一个 Markdown 文件里。AI 在需要的时候可以主动去读不需要的时候不用占用上下文。5. Codex 场景下的 superpowers 工作流5.1 Codex 和 Claude Code 使用技能的差异Codex 是 OpenAI 出的命令行编码助手它的工作方式和 Claude Code 接近但在技能加载上有些差异。最大的区别是Claude Code 对技能的“自动触发”做得更激进而 Codex 更像一个传统终端工具偏好明确指令。这就带来一个使用上的变化在 Codex 里用 superpowers不仅要装好技能文件还得主动要求 AI 启用某个技能。比如先输入一句“使用 systematic-debugging 技能排查这个问题”它才会按照技能的步骤走。而 Claude Code 里只要你有个描述写得很清楚的技能AI 往往会自动匹配。你不能说哪个更好只能说习惯问题。我喜欢在 Codex 里用更明确的方式控制流程反而觉得这更适合复杂任务每一步都是我自己主导的不会出现 AI 自作主张切换技能的情况。5.2 Codex 下的安装与软链接配置Codex 的技能集合目录通常和用户配置目录放在一起。你安装完 superpowers 之后可以确认一下技能文件有没有被 Codex 扫描到。稳妥的做法是在.codex目录下建立一个清晰的技能入口再验证一下ls -la ~/.codex/skillsets如果看到superpowers这个软链接或者目录就说明文件层面已经就位。接下来实际开一个会话问一句“你现在能识别到哪些技能”看输出结果是否符合预期。这里有一个小坑Codex 对技能文件的 frontmatter 字段识别比 Claude Code 更严格多一个空格、少一个字段它可能干脆忽略整个技能。我建议你从仓库里装好之后不要急着大改技能文件先试用一段时间确认格式和平台完全兼容再按自己的需求去调整内容。5.3 一个完整的 Codex 操作流程我通常在 Codex 里这样组织一个任务打开终端进入项目目录启动 Codex。明确指定要使用的技能比如“使用 test-driven-development 技能完成用户注册功能的单元测试”。先把需求和约束整理成一段话发给它不要直接让它写代码。AI 会按照技能步骤先列出测试用例清单再和你确认边界条件。确认无误后让 AI 按照清单逐步生成测试和生产代码。每完成一个阶段检查一下生成的代码然后继续下一个阶段。这样最大的好处是Codex 不会一次性给你堆一大堆代码而是拆成一个个可验证的小步骤。你可以在每个步骤之间插入检查发现问题随时纠正成本很低。5.4 没有图形界面时的纯终端用法Codex 本身就是命令行工具即使你只开一个终端不碰 IDE也能完整使用 superpowers。这对服务器上开发、远程调试这些场景特别有用。比如线上 Java 服务出了问题你本地没有完整代码只有服务器上的一份日志和一个只读代码仓库。你可以启动 Codex指定 trouble-shooting 技能然后把日志片段和堆栈贴进去。AI 会顺着技能步骤分析日志上下文、找规律、列假设并提示你应该去查看哪个类、哪个方法的代码。整个过程都在终端里完成不需要额外的图形环境。不过要提醒一点纯终端模式下Codex 读取代码仓库里的文件仍然很高效但你手动贴入的信息质量直接决定排查效率。最好把日志里的关键行、配置文件的差异、请求链路的 traceId 都尽量完整贴进去而不是只贴一个堆栈。6. 踩坑记录与调优建议6.1 技能不生效先按这几步定位技能装上没反应我遇到的情况里八成是下面几个原因没有重启会话。很多助手在会话启动时扫描技能目录中途新加的文件不会被识别。改完配置先新开一个对话再测试。目录结构不对。技能系统一般要求一层目录一个技能目录名和name字段最好一致。我之前试过把多个技能的 Markdown 文件直接平铺在一个目录里AI 完全不认。frontmatter 写错了。YAML 的冒号后面要加空格列表项缩进要一致。任何一个解析错误都可能导致整个技能被跳过。描述和实际行为不匹配。你把一个 TDD 技能的 description 写成“用于单元测试”AI 在“帮我修复这个问题”的场景里就不会调用它。描述必须围绕“什么情况下用”而不是“这个技能是什么”。这些问题九成通过“新开会话 检查文件结构 检查 frontmatter”就能解决。如果还不行就把技能目录改名成一个更简单的路径排除软链接和绝对路径的问题。6.2 上下文爆炸技能不是越多越好技能文件越写越多之后你会明显感觉到 AI 变“迟钝”了回答问题开始啰嗦或者抓不住重点。原因大概率是技能索引太大AI 在判断该用哪个技能时消耗了太多注意力。我的取舍原则是三个全局只留那些跨项目通用的技能比如系统化排查、测试驱动开发、代码审查。项目特有的事情写成项目级技能放在仓库里。那些“偶尔用一下”的临时技能不要落盘直接在对话里以普通指令形式给 AI不占用常驻技能位。按这个原则整理之后我自己全局技能保持在 10 个以内AI 的响应速度和准确率都回来了。6.3 模型对技能的遵循程度不一样不同模型对技能文件的“尊重程度”是有差异的。有的模型会严格按步骤走你说用技能它就用技能技能里没写的动作它一定不做。有的模型则比较随性技能步骤和用户指令冲突时它可能优先听用户临场的话。在实际使用中不要假设 AI 一定会完美执行技能。特别是关键任务比如发布、删数据、改权限我仍然会人工检查 AI 的输出而不是因为加载了技能就放心不管。技能可以显著降低出错概率但不能完全消除风险。我遇到过最典型的情况是一个技能要求 AI“修复后必须补充回归测试”但 AI 因为用户说了一句“快点搞定”就把这步跳过了。技能是文字不是硬编码AI 的推理路径有很强的随机性。所以团队在制定规范的时候不要把话说得太死要留出可以被验证的检查点比如“生成的代码必须通过 CI 才能提交”这样即使 AI 自己忘了流程也能兜住。6.4 技能文件的维护像维护代码一样维护技能技能文件是一种“给 AI 读的代码”它同样需要 review、测试和迭代。我见过很多团队把技能文件当成备忘录用写完一次就再也不动结果 AI 的行为和团队实际工作方式渐行渐远。比较好的维护节奏是每次在项目里发现 AI 反复犯同类错误就考虑把它写成一个技能或补进现有技能。每次团队流程改变比如引入了新的代码规范、新的发布流程同步更新相关技能。每个季度做一次技能清理删掉那些已经不再适用的内容。技能文件写完后至少要做一个“评审”让另一个人读一遍如果他看完不知道这个技能在什么场景下用、步骤是什么那 AI 也很可能搞不清楚。好的技能文件应该像一个高质量 SOP照着做就能得到稳定结果。6.5 渐进式采用不要第一天就全量铺开最后一点建议也是我踩过最大的坑不要第一天就把整个技能库全量加载进 AI。我一开始贪心把 superpowers 仓库里的技能一股脑全装上了结果 AI 的行为变得极其繁琐连“帮我格式化一下代码”这种小事都要走一套流程。后来我才意识到技能的意义是“该用时才用”而当时的 AI 把所有技能的匹配阈值都调得太低了。正确的做法是先挑两三个你最痛的能力比如“系统化排查”“测试驱动开发”“代码审查”装上用两周。等 AI 适应了、你也适应了 AI 的新行为模式再逐步增加技能。如果某个技能装上后两周内都没被触发过一次说明它的描述写得不够准或者你根本不需要它果断移除。我个人现在的做法是一直保持一套很小的核心技能集再根据当前项目的阶段动态调整。比如在项目上线前临时加一个“发布检查清单”技能项目稳定后再把它摘掉。这种动态增减比一次性装很多技能要高效得多。如果你正在被 AI 编码助手的“自由发挥”折磨不妨从最小的技能集开始试起。装上之后找一个你最近真实遇到过的复杂问题重新让 AI 排查一遍对比一下它前后的处理路径。你会发现它也许还是那个聪明的模型但做事的方式已经变得更像一个可靠的老工程师了。