1. 从聪明但缺乏经验的新人说起Superpowers到底解决了什么问题先说一个我自己的真实感受。用Codex这类AI编程助手用久了你会发现一个很有意思的现象它很聪明语法、算法、框架调用都难不倒它但有时候又像个刚入职、脑子转得快却没什么实操经验的实习生——你让它写一段重构代码它写得漂漂亮亮你让它处理一个涉及项目历史包袱、团队约定、特定目录规范的任务它就有点有劲使不上。问题不在AI本身在于我们给它的上下文太一次性了。你每次对话都在临时告诉它这个项目用Java 17异常处理要统一走Result封装DTO放哪个包它能记住但仅仅记住这一会儿。换一个新的会话来同样的话又得说一遍。日积月累这其实是在重复消耗token、重复消耗你自己的耐心。Superpowers就是奔着这个痛点来的。它本质上是一套给AI编程助手尤其以Codex为主要目标扩展技能包的框架。这里的技能不是我们常说的那种让GPT调用某个工具而是一套结构化、可复用、带明确工作流指引的领域操作手册。你可以把每一个技能理解成一份标准作业程序它告诉AI在什么场景下该做什么、按什么顺序做、做完之后怎么自检、有哪些坑绝对不能踩。这样说可能还不太好想象。打个比方吧你请了一位很厉害的私人助理但这助理不认识你的公司、不了解你的行业、不知道你老板的脾气。你每交代一件事都要从头解释背景。某天你干脆给助理整理了一个收纳盒里面全是客户投诉处理流程给老板写周报的格式规范报销单怎么贴最快这类卡片。之后你只需要说按流程处理一下这封投诉邮件它翻卡片就知道全套动作了。Superpowers就是那个收纳盒而里面的每一张卡片就是一个Skill。自从我把项目里的常用技能做成Superpowers的技能包之后最直观的变化是新的Codex会话不再需要我在开头写一大段项目背景。我只需要说用标准重构流程处理这个模块它就知道去读对应的技能卡按上面的步骤一步步干活。省掉的重复描述还是小事关键是输出质量的稳定性明显上来了——它不再凭感觉发挥而是真的在按流程走。所以这篇文章我打算从头到尾讲清楚几件事Superpowers的安装和基础配置、技能文件的结构和编写逻辑、怎么在Java项目里实际落地以及我跑了一段时间之后遇到的那些坑和感受。对已经受够了每次重复上下文、想让AI助手真正带经验上岗的开发者来说这套东西值得花半天时间搭起来。2. 安装和跑通比想象中简单但有几个坑不提前说会卡你半小时2.1 前置依赖检查先别急着敲命令。Superpowers本身是个轻量框架但它运行在AI编程助手之上所以你至少得有下面几样东西一个可用的AI编程助手命令行工具。目前社区里用得最多的是Codex CLI如果你用的是其他兼容工具原项目README里一般有对应说明思路完全一致。Node.js环境版本建议16以上。老版本不是不能用但一些依赖包对旧版Node不太友好实测翻车率挺高。Git这个不用说拉取项目本身要用。我在Ubuntu和macOS上都跑过Windows的话建议用WSL免得在路径和权限上折腾。2.2 安装流程以最常见的Codex CLI配合Superpowers为例安装步骤大概是这样的# 1. 安装 Codex CLI npm install -g openai/codex # 2. 拉取 Superpowers 项目到本地 git clone https://github.com/obra/superpowers.git cd superpowers # 3. 安装项目依赖 npm install # 4. 构建 npm run build构建成功之后把Superpowers的技能目录路径配置到你的Codex配置里。不同版本的Codex配置方式略有差异但核心都是告诉它技能库的位置在哪里。一般是在配置文件里加一个指向skills目录的字段比如{ skills_dir: /你的路径/superpowers/skills }具体字段名以你手头版本的文档为准别照抄我这条版本不同名字可能会变。配置好之后重启Codex会话试着问它一句列出你当前可用的技能。如果一切正常它会按技能清单挨个报名字和用途。我这边看到的技能包括代码审查、重构流程、编写技术文档、TDD工作流、调试排错流程等等基本覆盖了日常开发的高频场景。2.3 安装环节的常见坑这一节说的坑全是我自己踩过的网上教程一般不写这些第一个坑npm install阶段网络卡住。如果你所在网络环境拉取GitHub和npm源比较慢建议提前配好镜像源不然会长时间停在某个依赖包上然后超时中断。第二个坑构建产物路径和配置文件对不上。有些教程让你直接指定项目根目录当skills_dir但实际上编译后的技能文件在dist目录里。我一开始图省事指向了源码目录结果技能加载了一大半有些读取异常。后来发现正确做法是指向构建后的目录或者按照项目的安装脚本自动配置。第三个坑和旧版本Codex的兼容性。如果你用的是很早之前的Codex版本可能会遇到技能加载解析报错原因是新版框架用了更新的Markdown解析特性。建议把Codex升级到当前最新版再跑。这些坑单看都不大但叠加在一起足够让你在命令行前面耗掉半小时。我把它们写出来就是希望你不用再走这条弯路。3. 技能文件的解剖一套能稳定复现的工作流长什么样跑通之后我做的第一件事不是急着用现成技能而是打开技能目录看看里面到底装了什么。这一步非常值得做因为只有理解了技能文件的结构你才能自己动手写符合项目需求的技能。3.1 SKILL.md核心入口每个技能都对应一个独立的文件夹里面最重要的文件叫SKILL.md。这个文件是整个技能的主脑。打开任何一个SKILL.md你都会看到它的结构非常清晰frontmatter部分用YAML格式写技能的名称、简短描述。正文部分详细描述这个技能适用的场景、具体的工作流程、需要遵守的规则、以及完成后的自检清单。举个例子一个叫重构的技能它的SKILL.md里会写什么时候应该启动这个技能、重构前需要检查哪些前置条件、推荐的分解步骤、每一步如何验证、重构完成后要跑什么测试、有哪些绝对不能做的事情。这本质上就是把一个资深工程师脑子里那套怎么做才算把活干好的经验变成了AI可读取、可执行的文本。3.2 scripts和reference辅助力量除了SKILL.md不少技能还会带两个辅助目录scripts目录放的是可以被AI调用的小脚本比如解析AST、批量替换、生成模板等。AI在跑流程的时候遇到需要精确操作的部分会直接调用脚本而不是自己凭空写代码。reference目录放一些参考文档、代码片段、约定说明相当于技能的背景资料库AI在需要查证细节的时候会到这里找。这样一套组合拳下来一个技能就不只是一句提示词了而是一套完整的、可扩展的工作流包。3.3 为什么这比写提示词更可靠你可能要问这些内容我直接写在系统提示词里效果不是一样吗我一开始也这么想实际用下来发现差得远。提示词是一次性的。你塞进上下文AI这轮记住了下一轮新会话又得重新塞而且超长提示词本身就会挤压任务空间影响生成质量。技能是按需加载的。AI先判断你这个请求属于哪个场景再去读对应技能平时不占用上下文。你需要的是哪个领域的经验就只加载哪份互不干扰。另外技能的更新是独立的。发现某个流程有遗漏直接改对应的SKILL.md就行不需要改全局提示也不影响其他会话。这一点在团队协作里价值很大老手把经验沉淀成技能文件新手用AI的时候自动获得这些经验整个团队的产出质量下限被拉高了。4. 动手写一个Java项目技能从设计到落地的全过程光看现成技能不够真正让Superpowers发挥价值的地方是把你项目里的专属约定沉淀成自己的技能。这一节我拿Java项目为例完整走一遍设计流程。4.1 先在纸面上回答三个问题写技能之前我会先逼自己回答三个问题什么样的任务最常被交代给AI高频场景优先先别贪多。这个任务里有哪些是AI光靠聪明做不好的或者说有哪些是这个项目的特殊约定、特殊约束如果一位老同事被问起这事怎么做才对他会怎么回答拿Java项目来说我遇到的高频任务是写一个Controller接口。听起来简单但真正做过企业级Java项目的人都知道这里面水很深接口入参要不要封装成DTO还是直接收实体项目里有约定。返回值必须走统一的Result 结构还是允许裸对象异常怎么处理抓了之后怎么包装错误码哪里定义接口路径的命名风格是restful的还是传统的动词式有没有统一的参数校验方式比如JSR 303注解还是手写校验逻辑这些约定AI不可能凭空知道它只会猜一个最常见的方案而这往往不是你项目里的方案。4.2 把答案写成技能文件一旦想清楚了上面这些问题就可以把这些约定写成结构化的技能文件了。我随手写个精简版的SKILL.md框架你可以参考这个思路--- name: java-rest-controller description: 在Java Spring项目中创建符合团队规范的REST接口 --- # 什么时候使用 当需要新增或修改REST API接口时先加载本技能。 # 开发前必须确认 1. 确认目标Controller所在模块。 2. 确认入参是否需要新建DTO如果已有则复用。 3. 确认返回类型使用统一ResultT包装。 # 编码规范 1. 入参校验使用 javax.validation 注解禁止手写if校验。 2. Controller层禁止写业务逻辑只做参数绑定和结果包装。 3. 异常抛出使用 自定义BusinessException禁止new RuntimeException。 # 编码完成后的自检清单 - [ ] 是否使用了Result包装返回 - [ ] 是否所有入参都加了校验注解 - [ ] 是否没有import任何业务Service到Controller - [ ] 接口路径命名是否符合团队规范写完之后把这个文件放到Superpowers的技能目录下路径按照技能名/SKILL.md的规则组织再重启会话让框架重新扫描一遍。4.3 实际效果AI的行为真的不一样了技能文件建好之后我重新开了一个会话输入帮我写一个用户注册接口接收手机号和验证码。再和之前的对话对比行为差异立刻就能看出来。之前它大概率会给我一个看起来很对但拿回去要返工的版本Controller里塞业务代码、直接new异常、返回值裸奔、校验靠手写。加载技能之后的版本是先声明入参DTO并加上校验注解、Controller调用Service、返回Result包装、异常抛BusinessException。整体看下来几乎就是团队里一个老手写的水平基本可以直接提交评审。这就是技能文件的价值——它把团队潜规则变成了AI的显式约束。你不需要每次开会都在那边强调规范了因为AI在动手之前就已经被规范约束住了。4.4 一个Java多模块场景的进阶玩法再往深一步说如果你手里是个多模块的Maven项目每个模块的代码规范还不一样比如core模块要求严格对外网关模块要求宽松你甚至可以为不同模块分别写技能然后在描述里写明当任务涉及core模块时优先使用此技能。AI读到任务之后会自己判断匹配哪个。我自己试过把这种模块化的技能场景配上之后在跨模块改造时省了很多来回对话。原来你得在提示词里反复强调你在改的是core模块注意它的规范,现在技能描述里写清楚适用范围就够了。5. 实测JSON输出与技能加载机制的几个边界问题5.1 技能命中率不是百分之百说实话不能对技能加载机制抱有万能幻想。我实测下来AI在判断要不要加载某个技能时靠的是技能描述和你当前请求之间的语义匹配。描述写得越精准命中率越高描述写得太泛像这个技能用于Java开发AI大概率不会主动触发。所以写技能描述时我建议遵循做什么事在什么条件下用的结构。比如当需要新建REST接口或修改现有接口时使用明显比用于Java Web开发要容易被命中。另外有些AI助手在对话轮次多了之后会逐渐偏离初始技能约束。我的办法是重要约束在技能文件的末尾再加一遍自检清单并且在会话中明确要求AI在交付前逐项核对清单。实测下来这个二次强调能把遵守率拉高一大截。5.2 格式化和JSON输出之间的矛盾排错的时候我遇到过几次技能里要求严格按JSON格式输出但AI在同一段回答里又想给人读的说明文字。这个矛盾在两个环节之间尤其明显技能文件本身解析时和AI生成内容里嵌JSON时。后来我的解决方式是在技能文件里约定好所有结构化输出统一放在Markdown代码块中并标注为json,同时在补充说明里写清楚只要涉及需要机器读取的结果必须单独输出一段干净的JSON不要夹杂任何说明。双管齐下之后解析出错的情况明显变少了。5.3 多个技能之间的优先级问题还有一个使用中的实际问题某个任务可能同时匹配两个技能比如重构和代码审查都沾边。这时候AI怎么选我实测下来的经验是它倾向于选描述更具体的那一个或者先加载描述更具体的技能。如果你的两个技能确实会在某些边界场景发生冲突建议在各自的SKILL.md里互相写清楚边界。比如重构技能里注明涉及代码审查的部分请引用审查技能流程让AI自己串起来。这个做法比强行依赖加载排序要可靠得多。6. 用了这段时间谈谈我的真实感受和取舍6.1 收益最大的三个场景跑了一阵子Superpowers之后我复盘了一下收益最大的使用场景第一是跨会话的长期项目维护。以前换会话意味着把项目背景重讲一遍现在技能文件就是项目的活文档新会话直接加载技能就能恢复到特定任务的上下文里。第二是团队规范的强制执行。以前代码评审时总要在格式不对命名不对这种问题上反反复复提意见现在大部分规范被前置到了AI写代码的阶段评审的负担轻了不少。尤其是Controller层、DTO层这种模板化程度高的代码生效特别明显。第三是复杂任务的结构化。比如代码审查以前让AI审查代码它只会东一句西一句地挑毛病。配置好审查技能以后它按维度输出正确性问题、性能风险、安全漏洞、可维护性建议、命名与规范清晰得可以直接贴到PR评论里。6.2 现在机制的边界和我的取舍当然这玩意儿不是没有代价的。技能的维护本身需要投入而且技能写得太细、太多会加重AI的负担因为它要花时间读技能文件才能决定怎么执行。我自己现在奉行的原则是只沉淀那些重复出现、且确实有固定套路可循的任务别把所有事情都做成技能。还有一点就是技能质量是持续迭代出来的。第一版往往是想当然的用几次之后你会发现哦原来这个场景还需要补充一条约束随手在SKILL.md里加一句技能会越用越顺手。这个迭代过程本身就是团队经验沉淀的过程。抛砖引玉说了这么多最后就一个建议别一上来就追求把工作流写得多完善先挑一个你日常最烦、AI最常犯错的场景写一个最简单的技能跑起来、用起来然后再慢慢打磨。用上之后你会感受到让AI带经验上岗和临时抱佛脚之间体验差距真的很大。