我先说个挺真实的现象现在很多人用 Codex、Cline 这类 AI 编程工具前期觉得真香越用却越觉得它们不稳。同一个调试逻辑上午教过一次下午它又按老思路给你来一遍你反复交代过的代码规范换个会话它就失忆。我一度以为是模型变笨了后来才发现问题不在模型在于我压根没有给 AI 一个长期记忆的接口。最近在 GitHub 上折腾的 superpowers就是冲着这个痛点来的。superpowers 可以理解为给 AI 编程助手加装的一套技能系统。它用 Markdown 管理 AI 可以调用的提示词手册再通过语义检索在合适的时机自动注入到 AI 的上下文中让 AI 不再每次都以萌新状态面对你的项目。这篇文章我就把自己从安装、配置到实际嵌入 Java 项目工作流的完整过程拆给你看包括我到目前踩过的坑。1. 为什么 AI 编码工具越用越像金鱼脑superpowers 想解决的原始痛点1.1 明明调好的 AI换个会话又回归萌新先还原一个真实场景。我之前用 Codex CLI 调试一个 Spring Boot 项目里的内存溢出问题费了不少口舌让它先拉堆 dump、再分析 GC 日志、最后定位到某个缓存配置不合理。当时它表现得很懂事修完后我还特意总结了一套排查流程给它。结果第二天开新会话它又在同一个路口迷路了还是先建议加大堆内存这种治标不治本的做法。这不是个别现象。CLI 类的 AI 工具每一次会话都是独立的上下文窗口它没有跨会话的长期记忆。你在上一个会话里沉淀的排查思路、团队规范、接口设计约定到了下一个会话统统清零。于是你每天都在重复调教AI今天教的明天就忘效率反而被拉低了。1.2 AI 不是变笨了是缺一个经验库的接口后来我意识到一个点模型的推理能力是固定的但经验这部分本来就不该靠模型自己记住。人在团队里是怎么协作的靠文档、靠规范、靠 review 沉淀。AI 也应该有同样的输入方式——你不应该每次口头叮嘱它而应该给它一份随时可以查阅的团队手册。superpowers 做的事情就是把这份手册结构化。它鼓励你把调试过程、代码规范、架构约定写成 Markdown 文档命名为技能skill存放在项目目录下。AI 在处理任务时会基于对用户意图的语义理解自动检索相关技能并把内容带入上下文。换句话说你不告诉它该看哪篇文档它自己知道该看哪篇。1.3 它在 AI 编程生态里的定位不是替代者而是增强层需要先说清楚边界superpowers 不是 Codex、不是 IDE 插件也不替代任何一个具体模型。它更像一个提示词管理与编排层——跑在 AI 客户端前面负责在用户和模型之间加一道检索 组装 编排的工序。你甚至可以把它的定位类比成给游戏装上 Mod底层引擎没变但游戏体验被玩家自定义的规则改变了很多。我选择从 Codex CLI 切入也是因为它的命令行工作流非常适合这套技能机制。你在终端里描述任务superpowers 在后台完成理解需求 → 找到技能 → 拼装上下文 → 交给 Codex → 返回结果这一整条链路。整个使用过程依然是在终端里完成没有多余的图形界面要学。2. 拆开 superpowers 的引擎盖技能、检索与管道2.1 技能Skills用 Markdown 写给 AI 看的手册superpowers 里最核心的单元叫技能。听起来玄乎其实本质就是一个带固定 front-matter 的 Markdown 文档。文档里写的是什么情况下应该用这个技能、AI 应该遵循哪些步骤、有哪些禁忌、最终产出长什么样。我自己给团队写过一个接口返回统一格式的技能文档里面就定义了 Result 包装类的结构、错误码分段规则、异常处理时该记录哪些日志字段。之前这些话我要在每个会话里反复嘱咐 AI现在它只要检索到生成 Controller 接口这个需求就会自动把这些规则带进上下文生成结果一步到位不用我来回纠正。2.2 语义检索为什么比手动加载提示词更符合实际操作习惯有人可能会问那我不如直接在系统提示词里写规则或者每次会话开头粘贴一段话何必多此一举这就是 superpowers 最聪明的地方——它引入了语义检索机制。传统做法本质上是全量注入或手动指定。全量注入的问题是提示词越堆越长消耗 token 且稀释重点手动指定的问题是你经常忘记该给 AI 看哪份文档而且一旦遇到跨领域的复杂任务你很难判断 AI 需要的究竟是哪几个技能的组合。superpowers 的做法是把技能文档转成向量索引然后根据当前用户请求的语义相似度做主动召回。用户不需要知道技能文件叫什么名字AI 会自己判断该参考什么。2.3 提示词管道把一次请求拆成可编排的流水线我实际观察过 superpowers 对一次请求的处理流程它的设计不是简单的检索到就拼进去而是一套管道机制。大体上可以分为几个阶段先是意图识别判断用户这次任务是写代码、查问题还是做解释然后做技能召回从技能库里选出最相关的一到多个文档接着是上下文组装把用户输入、技能内容、项目文件结构、相关代码片段按优先级拼装最后才把组装好的完整提示词交给模型。这个管道的好处在于每一个环节都可以单独调试和优化。你觉得技能召回过宽了可以调整检索配置你觉得 AI 生成完没有自动做格式校验可以在管道尾部加一步后处理规则。这种可拆解的思路比把一堆提示词塞在配置文件里可维护得多。2.4 一个标准技能文档的内部结构我自己常用的是这个结构照着写基本不会出错--- name: spring-controller-basics description: 当用户需要编写 Spring MVC Controller 接口时使用 version: 1.2.0 tags: [java, spring, web] --- # Spring Controller 编写规范 当任务涉及创建或修改 Controller 时必须遵守以下约定 1. 所有接口返回 ResultT 包装对象禁止直接返回实体类 2. 分页接口统一使用 PageResult 结构参数名使用 pageNo 和 pageSize 3. Controller 层不写业务逻辑只做参数校验和路由转发 4. 异常统一使用全局异常处理器禁止在 Controller 内 catch 5. 日志中必须包含 traceId方便链路追踪这里最关键的字段是name和description。description写得越精确语义检索的命中率就越高。我见很多人技能不生效八成是 description 写得太泛比如处理 Java 问题——这种描述在检索时根本无法和具体任务建立有效关联。3. 从零开始安装 superpowers 并让 Codex 跑起来3.1 前置条件哪些环境必须先准备好在装 superpowers 之前你需要先确认自己已经有可用的 Codex CLI 或者同类支持外部增强的 AI 编程终端。我没有细数所有兼容工具但就我的经验而言只要你的命令行 AI 工具支持在配置层引入自定义系统提示词或 MCP 能力基本都可以和 superpowers 配合。另外因为 superpowers 的安装和技能索引构建依赖 Node.js 运行时所以我建议先确认 node 和 npm 版本足够新。常见的坑是 node 版本太老导致安装脚本跑不起来报错信息还不直观容易让人以为是工具本身的问题。3.2 安装 superpowers 的两种常用方式我安装的时候主要尝试了两种方式原理差不多。一种是直接通过 npm 以全局命令的方式安装装完会在系统层面多出一个superpowers命令另一种是从 GitHub 仓库 clone 代码到本地然后在项目目录里跑它的安装脚本。两种方式我更推荐用包管理器全局安装理由是后续升级方便而且和项目解耦。仓库方式适合你想顺手读源码、改内部逻辑的场景——我自己有一台开发机就是仓库方式方便调试它内部的检索逻辑但要作为日常主力配置还是全局安装省心。需要提醒的是不同版本对 Codex CLI 的支持方式略有差异安装前花两分钟看一眼官方 README 的流程说明能少踩很多坑。3.3 初始化项目目录生成技能库骨架安装完成后进入你的实际项目目录执行初始化命令它会自动生成一个存放技能的目录以及配置文件。初始化完成之后项目里大致会多出这么一套结构your-project/ ├── .superpowers/ │ ├── skills/ │ │ ├── conventional-commit.md │ │ └── spring-controller-basics.md │ ├── config.json │ └── index/这个结构本身就很开发者友好技能文件直接存放在仓库里意味着它可以走 Git 版本管理改动可追溯、可回滚、可评审。而index/目录是本地生成的向量索引缓存不需要提交到 Git重新构建索引时会自动刷新。3.4 写第一个技能让 AI 遵守团队的 Git 提交规范技能库搭好之后我建议你不要急着写一堆高深规则先从高频、稳定、容易验证的规范开始。我选的第一个技能是 Git 提交信息规范因为这个规则很明确AI 很容易判断自己有没有遵守验证成本也低。技能内容大致这样--- name: conventional-commit description: 在生成 Git 提交信息时必须遵循约定式提交规范 version: 1.0.0 --- # 约定式提交规范 生成提交信息时必须以 type(scope): subject 的格式组织 - type 取值feat、fix、docs、style、refactor、test、chore - scope 一般对应模块名例如 auth、order、payment - subject 不超过 50 个字符不使用句号结尾 示例 feat(auth): 增加登录验证码接口 fix(order): 修复超卖场景下库存负数问题写完保存后直接在 Codex 里说一句帮我提交一下今天的改动它生成的提交信息就会自动符合这套规范。这个小小的正反馈特别重要你会立刻理解技能这个概念的实际价值。然后你才会有动力去沉淀更多复杂场景。4. 把 superpowers 融入日常一次 Java 项目实战复盘4.1 为什么拿 Java 项目做实验田superpowers 本身不挑语言Git 规范这种技能跟语言完全无关。但我选择拿 Java 项目做深度验证因为它是我日常开发的主战场也更贴合很多人遇到的实际痛点。Java 项目相比脚本语言项目有一个非常明显的特点样板代码多、架构约定重。接口要分 Controller、Service、Mapper 三层要做统一异常处理要写参数校验要加日志埋点。这些约定对资深开发者来说是肌肉记忆但对 AI 来说每次都是全新的。这正是技能的用武之地——把这些约定固化下来AI 生成代码的一次通过率会有肉眼可见的提升。4.2 把一次痛苦的调试沉淀成可复用技能我印象最深的一次是排查一个并发环境下数据不一致的问题。当时我和 AI 来回周折了快一个小时最后定位到是事务边界放置错误导致部分操作没有落在同一个事务里。如果故事到这里就结束那只是又一段普通的 debug 经历。但用了 superpowers 之后我在复盘阶段把整个排查链路整理成了技能文档内容包括遇到并发数据不一致问题时建议先查事务注解的传播行为、再查隔离级别配置、然后看缓存和数据库之间的数据回源顺序每一步该通过什么命令或日志来验证。写完后我把它存成transaction-race-condition-debug.md。隔了两周另一个项目里出现了类似的症状我在对话里只描述了一句订单状态偶尔错乱怀疑是并发问题description 没有把话说死AI 就自动检索出了这份调试技能第一轮排查直接顺着当初的链路走省掉了大量试探性提问。4.3 让技能在代码审查、需求实现中自动发挥作用技能不只用于修复 Bug对日常开发任务同样有效。我团队有一套代码审查的清单接口是否做了幂等、敏感字段是否有脱敏、事务嵌套是否合理、日志中是否包含 traceId。之前这些全靠人工逐条检查现在我把它做成一个code-review-checklist技能。当我在 Codex 里输入审查一下这段订单接口代码时superpowers 会检索到这份技能AI 的审查输出就不再是泛泛而谈而是逐条对照我们的团队清单。它变成了一位提前读过团队规范的代码审查员。在实现新需求时也一样技能里写明的分层原则和命名规范会持续约束生成代码不用你反复提醒。4.4 建立和维护自己的技能库目录结构技能数量上来之后管理就是一个新的问题。我给技能文件做了一套分组standards/团队编码规范、提交规范、接口设计约定debugging/按问题域分类的排错链路如 JVM 调优、事务问题、内存泄漏workflows/多步骤流程如上线检查清单、数据库迁移流程reviews/代码审查清单、安全审查清单这套结构反映的是技能的四种使用时机。写代码时命中的是 standards查问题时命中的是 debugging要执行流程时命中的是 workflows。分类清晰的好处是后期做检索调优和技能清理时你不会面对一堆散落的文件无从下手。5. 团队落地把个人技能变成组内资产5.1 技能文件本身就在仓库里天然适合做代码评审如果你的项目团队已经习惯了代码评审流程那 superpowers 的落地几乎不需要额外引入管理成本。技能文件就是普通 Markdown存放在仓库目录里任何改动都会走 Merge Request 流程。我发现这个特性价值很大——以前沉淀经验这件事做着做着就烂尾了因为经验和代码分离改起来没有纪律可言。现在技能的改动和代码改动在同一套流程里流转每个人都能定期 review 技能库里的内容过期规范能被及时发现。5.2 共享技能仓库的两种组织方式我们团队里现在有几十份技能文档如果全部塞进每个项目的.superpowers目录里维护负担会很大。更合理的做法是区分通用技能和项目专属技能。通用技能只维护一份放在一个独立的公共技能仓库里包括 Git 规范、代码审查清单、安全要求这类跨项目通用的规则。项目专属技能再放到各自项目目录下比如某项目特有的数据埋点约定、某个遗留系统的错误码规则。配置层面可以把公共技能仓库和项目目录都挂到检索范围里这样既能享受集中管理的便利又能保留项目特有规则的灵活性。5.3 更新技能的时机别在功能开发正忙的时候改技能关于团队协作我有一条很实际的体会技能更新应该遵循独立提交原则不要和功能代码混在一起提交。开发功能时的语境是完成需求改技能时的语境是沉淀规范两者混在一起既影响代码评审的专注度又容易让技能改动被忽略。我尝试过的有效节奏是每个迭代结束后单独花半小时复盘这个迭代里 AI 频繁踩坑的点把对应的技能文档更新一版再单独提一个 MR。这种做法坚持两轮之后团队对技能库的心态会从形式主义文档转为真正被使用的工具。如果你也想在团队里推这套方案这个节奏值得参考。6. 我踩过的坑和边界问题的处理6.1 技能写了但没生效先查检索再查路径用了一周之后我碰到一个很打击人的问题辛辛苦苦写了一份技能文档结果对话里提到相关需求AI 完全没反应仿佛这份技能不存在。我复盘了一下问题出在 skill 的 description 和触发场景之间缺少语义关联。比如我把一份关于统一响应结构的技能文档描述写成了处理 Controller 返回结果结果实际对话里用户表达是帮我封装一下这个查询接口的返回。单看这两个文本语义距离确实有点远检索召回不到技能自然就不生效。后来我把 description 改成包含返回结构、Result、统一封装、错误码这类关键词命中率明显提升。6.2 技能过多时AI 也会信息过载技能库膨胀到一定规模之后新的问题浮出水面检索命中太准也不行。有一次处理一个支付相关需求AI 同时召回了支付超时排查、接口幂等设计、异常日志规范、数据库事务设置四份技能上下文里塞满了规则反而导致核心代码片段的空间变小生成质量下降。这个问题的解法不是关掉语义检索而是精简技能的粒度。我给自己定了一条规则单份技能文档只解决一个主题描述尽量聚焦不要出现顺便提一下别的规范这种贪多心态。技能文件贵在边界清晰而不在内容丰富。6.3 不要把 superpowers 当成需求分析器这里要说一个认知边界superpowers 解决的是已知经验的复用而不是未知需求的推导。它可以把你沉淀好的调试链路、代码规范、审查清单高效注入给 AI但它不会帮你做需求分析也不会替你想清楚产品逻辑。我见过有的同学试图把整个业务逻辑都写进技能文档里期望 AI 自动变成领域专家。这是一个不切实际的使用姿势。技能文档应该写的是怎么做的规则而不是做什么的需求。需求分析靠人规则沉淀靠技能这两种角色的分工不能混淆。6.4 技能里的安全边界不要把敏感信息写进去团队在用的时候一定要注意技能文档是存放在仓库里的而且是会跟随项目分发的。不要让技能里出现数据库连接串、内部服务地址、密钥这类敏感信息。我们内部做过一次自查发现有人为了方便把生产环境排查手册直接写进了技能里面带着内网跳板机地址。这个问题的严重性可能当时看不出来一旦仓库权限外泄这些信息就跟着出去了。后来我们补充了一条硬性规则技能里只写原则和步骤凡是涉及具体环境敏感信息的一律用占位符替代。6.5 和直接写系统提示词、AGENTS.md 的差异可能有人会问这跟直接在AGENTS.md里写规则有多大区别我自己的理解是AGENTS.md适合放这个项目是什么、整体如何构建、常用命令有哪些这类全局性信息内容量小、需要 AI 始终知道。而 superpowers 适合放在某个特定场景下才需要遵循的深入规则内容量大、需要按需加载。如果你的项目规则只有三五条用AGENTS.md就够了。但当规则多到影响 AI 上下文窗口、或不同任务的规则相互干扰时技能系统这套按需检索的价值就体现出来了。两者不冲突甚至可以同时配置让超级技能管深规则AGENTS 管基本盘。说到这我还想强调一点对我影响最大的体会技术工具的使用体验最终由使用者的习惯决定。我开始用 superpowers 之后最大的变化反而不是 AI 生成得更准了而是我开始养成了把经验写下来再复用的习惯。过去调完一个 bug 就过去了现在我会多花十分钟想这段排查思路能不能固化下来这个步骤是不是可以标准化这种习惯带来的长期收益比工具本身还要可观。最后分享一个我从同事那里学来的小技巧如果你不确定一份技能在真实对话里会怎样触发就先在 Codex 里用几个你平时会用的自然说法去提问然后看它检索到了哪些文档即使生成结果不那么满意这一步判断的准确性也会直接影响你的后续优化方向。工具本身是死的怎么调、怎么用、怎么沉淀才是每个人手里的超能力。