说实话第一次听说superpowers这个词的时候我以为是某个前端框架的新花活。结果仔细一扒才发现这东西压根不是个框架而是一套专门给AI编程助手比如Codex、Worbuddy这类工具做能力增强的配置方案与工具集。说白了它就是给AI编程助手装上外挂让原本只能动嘴皮子的AI真正变成能动手干活的资深工程师。如果你手头有Codex或者Worbuddy用过之后大概率会有一种感觉它确实能聊天、能写代码片段但真要让它独立处理一个完整的项目任务比如跨模块改造、重构老代码、统一改一堆相似的逻辑它就很容易跑偏——要么上下文太长直接断片要么改了一半忘了项目约定。superpowers解决的正是这个痛点通过一整套系统化的上下文管理、项目档案注入、任务流程拆分和执行策略把AI编程助手的干活能力拉满。这篇文章我会从项目设计思路、安装配置、核心玩法、实战流程、问题排查这几个维度把superpowers这套东西掰开揉碎讲清楚。适合已经在用或准备用AI编程助手的开发者尤其是做Java这类工程化项目的朋友读完可以直接照着落地。1. superpowers到底是什么它解决的核心问题1.1 从会聊天到能干活AI编程助手的最后一公里先聊一个大家都有体感的场景。你用Codex/Worbuddy这类工具时让它帮我写一个工具类、帮我修个bug它往往表现不错。但如果你想让它帮我看看这个老项目里所有TODO标记的遗留问题评估一下影响面再按优先级出一份改造方案——它就很容易抓瞎。为什么会抓瞎我总结下来有三个原因上下文太短多数AI编程助手在对话窗口里的有效上下文有限项目一大代码一多它根本记不住你整个项目的结构、依赖关系、编码规范。缺乏项目背景知识它不知道你的项目是干什么的、数据库长什么样、部署方式是什么、有没有历史包袱。你指望它理解意图它只能靠猜。执行链太浅AI助手生成一段代码容易但让它读代码→改代码→跑测试→复盘影响面这套完整链路它往往只能做前两步后面就撂挑子了。superpowers就是在这个背景下出现的。它不是某个单一的库或插件而是一套把项目信息和AI助手能力桥接起来的方案通过结构化的项目档案、精心设计的Prompt模板、以及一套可复用的任务执行流程让AI助手在干活前先吃透项目干活中有章法干活后能自查。用我同事的话说装上superpowers之后AI助手从实习生变成了熟练工。1.2 为什么叫superpowers定位与设计哲学这个名字很直白就是给AI编程助手赋予超能力。但我实际用下来觉得它的设计哲学其实可以拆成三句话先读后写一切修改必须基于对项目现状的充分理解不做无根据的猜测。流程可拆把复杂的开发任务拆解成建档→分析→设计→实施→验证几步每一步都有对应的Prompt策略。上下文复用一次建好的项目档案之后每次对话都可以复用不用反复教AI你的项目背景。这套思路和我之前折腾过的各种给GPT写Prompt技巧完全不是一个量级。那些是教你怎么问问题superpowers是教你搭一套AI干活的工作流。它不是玄学是一套可以被复制、被版本化的工程实践。提示严格来说superpowers的核心交付物是一系列指令文档 配置文件 工作流模板你不需要写一行代码就能用起来。这一点对非纯技术背景的朋友尤其友好。2. 安装与初始化先把环境跑通2.1 安装前的环境准备在动手装之前有几个前置条件建议先确认好不然容易在第一步就卡住。检查项建议要求备注AI编程助手Codex或Worbuddy任一可用账号superpowers的指令主要面向这两类工具设计网络环境能正常访问AI服务的API这个不用多说终端环境macOS/Linux的bash或zshWindows建议装Git Bash因为安装过程要用到curl和脚本执行项目代码本地已clone好目标项目建议先用中小型项目试水代码托管不强制但建议有Git仓库方便回滚和版本对比我在Windows上折腾过一次直接用CMD跑安装脚本会报错。后来换成了Git Bash才顺利跑通。如果你用Windows别在CMD或PowerShell里硬刚直接上Git Bash最省事。2.2 安装步骤两条路看你怎么选superpowers的安装方式我试过两种一种叫快速安装另一种叫手动安装。前者适合绝大多数人后者适合你想自己改源码的情况。方式一快速安装在终端里执行安装脚本它会自动把superpowers的核心文件下载到指定目录并把配置写入你的AI助手配置文件里。大概的命令长这样curl -fsSL https://install.superpowers.example/install.sh | bash执行完之后终端会输出一行提示告诉你配置文件写到了哪里。正常情况下是~/.superpowers/目录。注意上面这个命令里的域名是我举例用的实际地址以项目的官方文档为准。安装脚本本质上只做三件事下载文件、生成配置、输出使用说明。如果你不放心完全可以先下载脚本看一下内容再执行。方式二手动安装手动安装其实就是把仓库clone下来然后把关键文件放到指定位置git clone https://github.com/your-user/superpowers.git ~/.superpowers然后打开你的AI助手配置文件在合适的位置把superpowers的指令文件路径引入进去。具体的引入方式要看你的助手支持什么格式有的是include指令有的直接粘贴文本。我个人的建议是第一次用快速安装跑通之后再决定要不要手动调整。2.3 初始化配置三个关键参数别乱填装完后不是直接就能用还需要初始化。初始化时会问你几个问题我挑三个关键的说说项目语言/框架你用Java、Python还是Node框架是Spring Boot还是Next.js这个信息会决定superpowers生成的项目档案模板侧重哪些维度。选错问题不大后续可以改但选对能省很多事。项目构建命令比如Java的mvn clean install、Python的pip install -r requirements.txt。这一步非常关键因为后续AI执行验证时要靠这个命令跑构建。测试命令mvn test还是pytestAI改完代码后要跑什么来确认没改坏就靠这个参数。不夸张地说如果构建命令和测试命令不填superpowers的效果至少打个五折。因为它的核心逻辑里有一环是自动验证而验证的入口就是这两个命令。初始化完成后它会生成一个类似.superpowers/project.md的文件这就是项目的档案。我第一次打开这个文件的时候有点震惊——里面连项目的目录结构、核心模块职责、常见操作命令、编码约定都整理好了而且真的是从我本地项目里提炼出来的不是空模板。3. 核心玩法拆解Codex/Worbuddy的超能力是怎么运作的3.1 项目档案让AI先读懂你的项目我前面反复提到项目档案这是superpowers最核心的机制。它不是一个静态的README而是一份给AI看的项目说明书。拿一个Java项目举例project.md里通常会包含项目简介这个系统是干什么的面向什么用户核心业务流程是什么。技术栈清单Spring Boot版本、数据库类型、ORM框架、构建工具、Java版本等。目录结构地图src/main/java下每个包是干什么的resources里放了什么配置有没有多模块。关键业务模块说明比如用户模块、订单模块各自的核心类和它们之间的关系。代码约定项目里有没有统一的异常处理、日志规范、命名风格。常用操作命令启动命令、测试命令、打包命令、数据库迁移命令。有了这份档案AI助手在动手改代码之前就不是两眼一抹黑地猜而是先读档案、理解项目背景再去看具体代码。这个顺序非常重要——先有上下文再谈生成。我第一次用的时候还特意对比过同样让Codex改一个支付模块的bug没用superpowers时它直接开始改改了三次都没改对用了之后它先是列出支付模块相关类然后定位到具体异常抛出的位置还顺带指出了我日志里的一个隐患。这个差距不是一点半点。3.2 任务流程引擎把写代码变成走流程superpowers的另一个杀招是它的任务流程。它不是让你直接把需求甩给AI而是让你按它预设的流程走完一遍通常包含这几步建档确认项目档案是否最新必要时先更新档案。分析让AI读相关代码输出它对需求的理解、影响面分析、备选方案。设计确认AI提出的方案让AI细化改动点列出要改哪些文件、每个文件大概怎么改。实施分步执行修改每改一个文件或一个模块停下来说明改动内容和原因。验证跑构建、跑测试把结果反馈给AI让它根据失败信息自纠。复盘AI总结改动内容、可能的副作用、遗留问题。这套流程听着简单但真正执行起来AI的靠谱程度会有质的提升。原因在于prompt里的思考链能力被流程化、工程化了。你不需要每次手写一大段先分析再动手的promptsuperpowers已经把这一步做成了标准动作。3.3 多语言适配Java等工程化项目尤其受益为什么说Java项目尤其受益我自己的感受是Java项目普遍代码量大、依赖复杂、规范化程度高恰恰是最需要先读后写的场景。C/Python项目相对灵活AI乱写的代价小一些Java项目里一个类被十几个地方引用改错了影响面非常大。superpowers在Java场景下有几个细节做得不错自动识别pom.xml或build.gradle里的依赖遇到需要新增依赖的情况会先问你要不要动pom。对于Map、List、Optional这类Java常用类型它的指令模板里有明确约定避免AI生成过于Python风格的代码。跑测试时优先用mvn -DskipTestsfalse这类明确指令而不是笼统的跑一下测试。当然它对Python、Go、TypeScript的支持也没问题只是我个人认为在Java这种重工程项目上收益更明显。4. 实战流程拿一个真实的Java改造需求走一遍4.1 场景设定老项目里的一个历史遗留改造为了让你直观感受superpowers的用法我拿一个实际做过的场景举例。背景是这样的一个老Java服务用的Spring Boot 2.x数据库是MySQL核心业务是订单管理。需求是——把原先散落在各个Service里的订单状态变更逻辑统一收敛到一个OrderStateMachine类里方便后续做状态流转的审计和扩展。这个需求听起来不难但实际改动涉及5个Service类里散落的7处状态变更逻辑。1个OrderStatus枚举需要补充几个中间状态。Order实体类的status字段涉及数据库存量数据的兼容。至少20个测试用例会受到影响。如果用老方式我得自己先花半小时翻代码确认每个改动的点再花半小时手动改最后跑一遍全量测试看看哪里炸了。用superpowers走一遍流程大概是这样的。4.2 完整操作流程从输入指令到验证通过第一步我给Codex发指令明确需求。借助superpowers我不会直接说帮我改而是按它的规范把需求加进去。请基于项目档案分析订单状态变更逻辑统一收敛到OrderStateMachine这个需求的改造方案。 重点 1. 列出当前所有直接修改订单状态的代码位置。 2. 评估每个位置是否可以直接替换为调用OrderStateMachine。 3. 指出存量数据中已有状态是否需要迁移处理。这里用到的是superpowers的分析流程。Codex会先读项目档案再根据档案索引去定位代码。我记得它大概用了两三分钟输出了一张表列出来8处位置其中5处可以直接替换2处需要先补充枚举状态1处涉及老数据兼容需要单独处理。第二步审核它的方案。这一步千万别跳。我大概看了下它列出的位置有两处是我自己都没注意到的它指出来了。确认没问题后让它进入实施阶段。第三步分步实施。superpowers的玩法是让它一次只改一个文件改完停下来说明。比如它会说正在修改OrderServiceImpl.java把第128行的order.setStatus(OrderStatus.PAID)替换为对OrderStateMachine的调用现有逻辑保持不变。我印象很深的是它在改到第三处的时候主动停下来问我这里修改后原来调用方的日志记录逻辑需要保留吗这种主动确认在之前的裸用过程中从来没出现过。第四步自动验证。实施完成后它会自己跑mvn compile和mvn test。第一次跑挂了两个测试它根据报错信息定位到是测试用例里直接构造了OrderStatus.SHIPPED状态但新的状态机里该状态的口径变了。于是它又改了两处测试代码的构造逻辑重新跑全部通过。整个流程走下来我实际动手的时间大概只有开头确认方案那几分钟。剩下的活AI干得明明白白。4.3 实战中的三个关键细节方案确认环节不要省AI的分析方案大概率有参考价值但你一定要自己过一遍。尤其是涉及数据库迁移、公共接口变更的部分AI的直觉不一定适配你的业务语境。存量兼容要单独问像上面提到的老数据兼容问题如果不明确提出来AI很容易忽略。建议在需求描述里主动加上一句注意存量数据和线上兼容。测试跑挂不等于白干很多朋友一看测试挂了就觉得AI不行。其实恰恰相反测试挂了AI能自己看日志、定位问题、修复这才是superpowers最有价值的环节。如果跑了第一次就全绿反而要警惕是不是测试覆盖不够。5. 常见问题与排查实录5.1 安装阶段脚本执行失败、目录权限报错安装失败最常见的原因有两个一是网络问题下载脚本或文件失败二是权限问题脚本往/usr/local这类目录写文件时没有权限。网络问题确认你的终端能正常访问目标站点如果公司网络有代理限制先配置好代理环境变量。权限问题执行chmod x install.sh或者用sudo跑安装命令。但我个人不太建议直接sudo更推荐把安装目录改成当前用户有权限的位置。另外如果你之前装过一次再跑安装脚本时提示目录已存在可以先把~/.superpowers备份后删掉再重新装。5.2 使用阶段AI助手不读取项目档案这个问题我踩过坑。装好之后发现Codex完全无视project.md还是一副没预习就来考试的样子。排查后发现我根本没有在对话里引用它。superpowers的原理不是自动注入上下文而是提供一套指令让你在对话开头指示AI去读取档案。如果你没有在指令里明确说先读取项目档案或者按superpowers流程执行AI自然不会主动去看。正确的做法是在对话开头先把superpowers的指令喂给AI或者通过工具的System Prompt配置把它加载进去然后再说你的需求。装完superpowers后首次使用它会提示你把一段激活词放到AI助手的配置里。这一步懒不得。5.3 效果不稳定同一个需求时好时坏我会遇到同一个需求上午跑得好好的下午再跑结果就不对的情况。这不是superpowers本身的问题而是AI模型本身有随机性。几个降低波动的技巧温度参数调低如果工具支持的话设置在0.2以下输出的确定性会好很多。需求描述里把验收标准写清楚比如所有修改必须不影响现有接口签名、测试必须全绿。如果AI的思路偏了不要直接在它的错误结果上继续让它改而是用CtrlC打断重新描述需求并强调基于项目档案重新分析。5.4 太长了一次流程跑到一半上下文爆炸superpowers的流程本身比较长分析实施一步不落跑个大型需求很容易把上下文窗口占满。我的做法是分阶段对话。比如分析阶段在一个对话里完成拿到方案后新开一个对话用实施指令把方案摘要带过去让AI继续干。project.md可以反复读所以新对话里AI依然能快速进入状态。提示如果某个需求涉及多个模块建议不要指望一个对话搞定。拆成每个模块一个对话每个对话都从读取项目档案开始这样上下文始终干净效果反而好。6. 我的心得体会什么时候该用、什么时候不该用6.1 适合的场景跨模块重构比如把散落的逻辑统一收敛、抽取公共组件、调整包结构。这类需求最考验AI的全局理解能力也正是superpowers的强项。老代码维护项目交接后上手慢让AI先读档案、梳理模块结构相当于免费请了一个熟悉项目的导读员。技术债清理一次性把项目里所有TODO、FIXME、Deprecated调用梳理出来并给出整改建议。这种低难度但繁琐的活AI干起来比人快得多。6.2 不适合的场景全新项目的从0到1项目还没建立档案AI的优势发挥不出来。这时候直接让它帮你讨论方案、写初始框架反而更自由。性能调优涉及底层JVM参数、极端并发场景的调优AI的建议往往流于表面。它把代码改了但性能问题是否真正解决还得靠你自己压测。需求本身模糊不清如果你自己都不知道要做什么AI再强也白搭。6.3 一点扩展思路project.md这个机制其实可以被玩出很多花样。比如你可以在里面追加部署手册、常见异常排查表、SQL约定让AI在写代码时自动遵守这些约定。我甚至见过有人把团队的代码Review清单写进去让AI提交代码前先自查一遍。从这个角度看superpowers不只是一个工具更像是一种用文档驱动AI的工作范式。你用得越久档案越完善AI干活的准确率就越高。我现在的习惯是每完成一个模块的改造就把变更的摘要回写到project.md里让档案跟着项目一起进化。如果在使用过程中遇到什么新的坑或者好玩的使用方式欢迎回来交流。工具是死的用法是活的多折腾几次你会找到最适合自己团队的那套节奏。
superpowers：给AI编程助手装上外挂，从会聊天到能干活
说实话第一次听说superpowers这个词的时候我以为是某个前端框架的新花活。结果仔细一扒才发现这东西压根不是个框架而是一套专门给AI编程助手比如Codex、Worbuddy这类工具做能力增强的配置方案与工具集。说白了它就是给AI编程助手装上外挂让原本只能动嘴皮子的AI真正变成能动手干活的资深工程师。如果你手头有Codex或者Worbuddy用过之后大概率会有一种感觉它确实能聊天、能写代码片段但真要让它独立处理一个完整的项目任务比如跨模块改造、重构老代码、统一改一堆相似的逻辑它就很容易跑偏——要么上下文太长直接断片要么改了一半忘了项目约定。superpowers解决的正是这个痛点通过一整套系统化的上下文管理、项目档案注入、任务流程拆分和执行策略把AI编程助手的干活能力拉满。这篇文章我会从项目设计思路、安装配置、核心玩法、实战流程、问题排查这几个维度把superpowers这套东西掰开揉碎讲清楚。适合已经在用或准备用AI编程助手的开发者尤其是做Java这类工程化项目的朋友读完可以直接照着落地。1. superpowers到底是什么它解决的核心问题1.1 从会聊天到能干活AI编程助手的最后一公里先聊一个大家都有体感的场景。你用Codex/Worbuddy这类工具时让它帮我写一个工具类、帮我修个bug它往往表现不错。但如果你想让它帮我看看这个老项目里所有TODO标记的遗留问题评估一下影响面再按优先级出一份改造方案——它就很容易抓瞎。为什么会抓瞎我总结下来有三个原因上下文太短多数AI编程助手在对话窗口里的有效上下文有限项目一大代码一多它根本记不住你整个项目的结构、依赖关系、编码规范。缺乏项目背景知识它不知道你的项目是干什么的、数据库长什么样、部署方式是什么、有没有历史包袱。你指望它理解意图它只能靠猜。执行链太浅AI助手生成一段代码容易但让它读代码→改代码→跑测试→复盘影响面这套完整链路它往往只能做前两步后面就撂挑子了。superpowers就是在这个背景下出现的。它不是某个单一的库或插件而是一套把项目信息和AI助手能力桥接起来的方案通过结构化的项目档案、精心设计的Prompt模板、以及一套可复用的任务执行流程让AI助手在干活前先吃透项目干活中有章法干活后能自查。用我同事的话说装上superpowers之后AI助手从实习生变成了熟练工。1.2 为什么叫superpowers定位与设计哲学这个名字很直白就是给AI编程助手赋予超能力。但我实际用下来觉得它的设计哲学其实可以拆成三句话先读后写一切修改必须基于对项目现状的充分理解不做无根据的猜测。流程可拆把复杂的开发任务拆解成建档→分析→设计→实施→验证几步每一步都有对应的Prompt策略。上下文复用一次建好的项目档案之后每次对话都可以复用不用反复教AI你的项目背景。这套思路和我之前折腾过的各种给GPT写Prompt技巧完全不是一个量级。那些是教你怎么问问题superpowers是教你搭一套AI干活的工作流。它不是玄学是一套可以被复制、被版本化的工程实践。提示严格来说superpowers的核心交付物是一系列指令文档 配置文件 工作流模板你不需要写一行代码就能用起来。这一点对非纯技术背景的朋友尤其友好。2. 安装与初始化先把环境跑通2.1 安装前的环境准备在动手装之前有几个前置条件建议先确认好不然容易在第一步就卡住。检查项建议要求备注AI编程助手Codex或Worbuddy任一可用账号superpowers的指令主要面向这两类工具设计网络环境能正常访问AI服务的API这个不用多说终端环境macOS/Linux的bash或zshWindows建议装Git Bash因为安装过程要用到curl和脚本执行项目代码本地已clone好目标项目建议先用中小型项目试水代码托管不强制但建议有Git仓库方便回滚和版本对比我在Windows上折腾过一次直接用CMD跑安装脚本会报错。后来换成了Git Bash才顺利跑通。如果你用Windows别在CMD或PowerShell里硬刚直接上Git Bash最省事。2.2 安装步骤两条路看你怎么选superpowers的安装方式我试过两种一种叫快速安装另一种叫手动安装。前者适合绝大多数人后者适合你想自己改源码的情况。方式一快速安装在终端里执行安装脚本它会自动把superpowers的核心文件下载到指定目录并把配置写入你的AI助手配置文件里。大概的命令长这样curl -fsSL https://install.superpowers.example/install.sh | bash执行完之后终端会输出一行提示告诉你配置文件写到了哪里。正常情况下是~/.superpowers/目录。注意上面这个命令里的域名是我举例用的实际地址以项目的官方文档为准。安装脚本本质上只做三件事下载文件、生成配置、输出使用说明。如果你不放心完全可以先下载脚本看一下内容再执行。方式二手动安装手动安装其实就是把仓库clone下来然后把关键文件放到指定位置git clone https://github.com/your-user/superpowers.git ~/.superpowers然后打开你的AI助手配置文件在合适的位置把superpowers的指令文件路径引入进去。具体的引入方式要看你的助手支持什么格式有的是include指令有的直接粘贴文本。我个人的建议是第一次用快速安装跑通之后再决定要不要手动调整。2.3 初始化配置三个关键参数别乱填装完后不是直接就能用还需要初始化。初始化时会问你几个问题我挑三个关键的说说项目语言/框架你用Java、Python还是Node框架是Spring Boot还是Next.js这个信息会决定superpowers生成的项目档案模板侧重哪些维度。选错问题不大后续可以改但选对能省很多事。项目构建命令比如Java的mvn clean install、Python的pip install -r requirements.txt。这一步非常关键因为后续AI执行验证时要靠这个命令跑构建。测试命令mvn test还是pytestAI改完代码后要跑什么来确认没改坏就靠这个参数。不夸张地说如果构建命令和测试命令不填superpowers的效果至少打个五折。因为它的核心逻辑里有一环是自动验证而验证的入口就是这两个命令。初始化完成后它会生成一个类似.superpowers/project.md的文件这就是项目的档案。我第一次打开这个文件的时候有点震惊——里面连项目的目录结构、核心模块职责、常见操作命令、编码约定都整理好了而且真的是从我本地项目里提炼出来的不是空模板。3. 核心玩法拆解Codex/Worbuddy的超能力是怎么运作的3.1 项目档案让AI先读懂你的项目我前面反复提到项目档案这是superpowers最核心的机制。它不是一个静态的README而是一份给AI看的项目说明书。拿一个Java项目举例project.md里通常会包含项目简介这个系统是干什么的面向什么用户核心业务流程是什么。技术栈清单Spring Boot版本、数据库类型、ORM框架、构建工具、Java版本等。目录结构地图src/main/java下每个包是干什么的resources里放了什么配置有没有多模块。关键业务模块说明比如用户模块、订单模块各自的核心类和它们之间的关系。代码约定项目里有没有统一的异常处理、日志规范、命名风格。常用操作命令启动命令、测试命令、打包命令、数据库迁移命令。有了这份档案AI助手在动手改代码之前就不是两眼一抹黑地猜而是先读档案、理解项目背景再去看具体代码。这个顺序非常重要——先有上下文再谈生成。我第一次用的时候还特意对比过同样让Codex改一个支付模块的bug没用superpowers时它直接开始改改了三次都没改对用了之后它先是列出支付模块相关类然后定位到具体异常抛出的位置还顺带指出了我日志里的一个隐患。这个差距不是一点半点。3.2 任务流程引擎把写代码变成走流程superpowers的另一个杀招是它的任务流程。它不是让你直接把需求甩给AI而是让你按它预设的流程走完一遍通常包含这几步建档确认项目档案是否最新必要时先更新档案。分析让AI读相关代码输出它对需求的理解、影响面分析、备选方案。设计确认AI提出的方案让AI细化改动点列出要改哪些文件、每个文件大概怎么改。实施分步执行修改每改一个文件或一个模块停下来说明改动内容和原因。验证跑构建、跑测试把结果反馈给AI让它根据失败信息自纠。复盘AI总结改动内容、可能的副作用、遗留问题。这套流程听着简单但真正执行起来AI的靠谱程度会有质的提升。原因在于prompt里的思考链能力被流程化、工程化了。你不需要每次手写一大段先分析再动手的promptsuperpowers已经把这一步做成了标准动作。3.3 多语言适配Java等工程化项目尤其受益为什么说Java项目尤其受益我自己的感受是Java项目普遍代码量大、依赖复杂、规范化程度高恰恰是最需要先读后写的场景。C/Python项目相对灵活AI乱写的代价小一些Java项目里一个类被十几个地方引用改错了影响面非常大。superpowers在Java场景下有几个细节做得不错自动识别pom.xml或build.gradle里的依赖遇到需要新增依赖的情况会先问你要不要动pom。对于Map、List、Optional这类Java常用类型它的指令模板里有明确约定避免AI生成过于Python风格的代码。跑测试时优先用mvn -DskipTestsfalse这类明确指令而不是笼统的跑一下测试。当然它对Python、Go、TypeScript的支持也没问题只是我个人认为在Java这种重工程项目上收益更明显。4. 实战流程拿一个真实的Java改造需求走一遍4.1 场景设定老项目里的一个历史遗留改造为了让你直观感受superpowers的用法我拿一个实际做过的场景举例。背景是这样的一个老Java服务用的Spring Boot 2.x数据库是MySQL核心业务是订单管理。需求是——把原先散落在各个Service里的订单状态变更逻辑统一收敛到一个OrderStateMachine类里方便后续做状态流转的审计和扩展。这个需求听起来不难但实际改动涉及5个Service类里散落的7处状态变更逻辑。1个OrderStatus枚举需要补充几个中间状态。Order实体类的status字段涉及数据库存量数据的兼容。至少20个测试用例会受到影响。如果用老方式我得自己先花半小时翻代码确认每个改动的点再花半小时手动改最后跑一遍全量测试看看哪里炸了。用superpowers走一遍流程大概是这样的。4.2 完整操作流程从输入指令到验证通过第一步我给Codex发指令明确需求。借助superpowers我不会直接说帮我改而是按它的规范把需求加进去。请基于项目档案分析订单状态变更逻辑统一收敛到OrderStateMachine这个需求的改造方案。 重点 1. 列出当前所有直接修改订单状态的代码位置。 2. 评估每个位置是否可以直接替换为调用OrderStateMachine。 3. 指出存量数据中已有状态是否需要迁移处理。这里用到的是superpowers的分析流程。Codex会先读项目档案再根据档案索引去定位代码。我记得它大概用了两三分钟输出了一张表列出来8处位置其中5处可以直接替换2处需要先补充枚举状态1处涉及老数据兼容需要单独处理。第二步审核它的方案。这一步千万别跳。我大概看了下它列出的位置有两处是我自己都没注意到的它指出来了。确认没问题后让它进入实施阶段。第三步分步实施。superpowers的玩法是让它一次只改一个文件改完停下来说明。比如它会说正在修改OrderServiceImpl.java把第128行的order.setStatus(OrderStatus.PAID)替换为对OrderStateMachine的调用现有逻辑保持不变。我印象很深的是它在改到第三处的时候主动停下来问我这里修改后原来调用方的日志记录逻辑需要保留吗这种主动确认在之前的裸用过程中从来没出现过。第四步自动验证。实施完成后它会自己跑mvn compile和mvn test。第一次跑挂了两个测试它根据报错信息定位到是测试用例里直接构造了OrderStatus.SHIPPED状态但新的状态机里该状态的口径变了。于是它又改了两处测试代码的构造逻辑重新跑全部通过。整个流程走下来我实际动手的时间大概只有开头确认方案那几分钟。剩下的活AI干得明明白白。4.3 实战中的三个关键细节方案确认环节不要省AI的分析方案大概率有参考价值但你一定要自己过一遍。尤其是涉及数据库迁移、公共接口变更的部分AI的直觉不一定适配你的业务语境。存量兼容要单独问像上面提到的老数据兼容问题如果不明确提出来AI很容易忽略。建议在需求描述里主动加上一句注意存量数据和线上兼容。测试跑挂不等于白干很多朋友一看测试挂了就觉得AI不行。其实恰恰相反测试挂了AI能自己看日志、定位问题、修复这才是superpowers最有价值的环节。如果跑了第一次就全绿反而要警惕是不是测试覆盖不够。5. 常见问题与排查实录5.1 安装阶段脚本执行失败、目录权限报错安装失败最常见的原因有两个一是网络问题下载脚本或文件失败二是权限问题脚本往/usr/local这类目录写文件时没有权限。网络问题确认你的终端能正常访问目标站点如果公司网络有代理限制先配置好代理环境变量。权限问题执行chmod x install.sh或者用sudo跑安装命令。但我个人不太建议直接sudo更推荐把安装目录改成当前用户有权限的位置。另外如果你之前装过一次再跑安装脚本时提示目录已存在可以先把~/.superpowers备份后删掉再重新装。5.2 使用阶段AI助手不读取项目档案这个问题我踩过坑。装好之后发现Codex完全无视project.md还是一副没预习就来考试的样子。排查后发现我根本没有在对话里引用它。superpowers的原理不是自动注入上下文而是提供一套指令让你在对话开头指示AI去读取档案。如果你没有在指令里明确说先读取项目档案或者按superpowers流程执行AI自然不会主动去看。正确的做法是在对话开头先把superpowers的指令喂给AI或者通过工具的System Prompt配置把它加载进去然后再说你的需求。装完superpowers后首次使用它会提示你把一段激活词放到AI助手的配置里。这一步懒不得。5.3 效果不稳定同一个需求时好时坏我会遇到同一个需求上午跑得好好的下午再跑结果就不对的情况。这不是superpowers本身的问题而是AI模型本身有随机性。几个降低波动的技巧温度参数调低如果工具支持的话设置在0.2以下输出的确定性会好很多。需求描述里把验收标准写清楚比如所有修改必须不影响现有接口签名、测试必须全绿。如果AI的思路偏了不要直接在它的错误结果上继续让它改而是用CtrlC打断重新描述需求并强调基于项目档案重新分析。5.4 太长了一次流程跑到一半上下文爆炸superpowers的流程本身比较长分析实施一步不落跑个大型需求很容易把上下文窗口占满。我的做法是分阶段对话。比如分析阶段在一个对话里完成拿到方案后新开一个对话用实施指令把方案摘要带过去让AI继续干。project.md可以反复读所以新对话里AI依然能快速进入状态。提示如果某个需求涉及多个模块建议不要指望一个对话搞定。拆成每个模块一个对话每个对话都从读取项目档案开始这样上下文始终干净效果反而好。6. 我的心得体会什么时候该用、什么时候不该用6.1 适合的场景跨模块重构比如把散落的逻辑统一收敛、抽取公共组件、调整包结构。这类需求最考验AI的全局理解能力也正是superpowers的强项。老代码维护项目交接后上手慢让AI先读档案、梳理模块结构相当于免费请了一个熟悉项目的导读员。技术债清理一次性把项目里所有TODO、FIXME、Deprecated调用梳理出来并给出整改建议。这种低难度但繁琐的活AI干起来比人快得多。6.2 不适合的场景全新项目的从0到1项目还没建立档案AI的优势发挥不出来。这时候直接让它帮你讨论方案、写初始框架反而更自由。性能调优涉及底层JVM参数、极端并发场景的调优AI的建议往往流于表面。它把代码改了但性能问题是否真正解决还得靠你自己压测。需求本身模糊不清如果你自己都不知道要做什么AI再强也白搭。6.3 一点扩展思路project.md这个机制其实可以被玩出很多花样。比如你可以在里面追加部署手册、常见异常排查表、SQL约定让AI在写代码时自动遵守这些约定。我甚至见过有人把团队的代码Review清单写进去让AI提交代码前先自查一遍。从这个角度看superpowers不只是一个工具更像是一种用文档驱动AI的工作范式。你用得越久档案越完善AI干活的准确率就越高。我现在的习惯是每完成一个模块的改造就把变更的摘要回写到project.md里让档案跟着项目一起进化。如果在使用过程中遇到什么新的坑或者好玩的使用方式欢迎回来交流。工具是死的用法是活的多折腾几次你会找到最适合自己团队的那套节奏。
