如果你用过Codex这类AI编程助手多少会有一种“它能写代码但写不出我要的工程”的憋屈感。代码片段倒是一套一套的可真放进项目里命名规范不统一、缺少异常处理、不考虑历史包袱改起来比手写还累。这就像发动机给你拉满但变速箱完全没接上。我后来花了两个多月给自己这套工作流起了个名字叫Superpowers本质是一层架在Codex之上的增强配置通过规则文件、任务拆解模板和自动化脚本来约束AI的行为让生成结果从“能用”变成“符合工程标准地好用”。这篇文章是完整的搭建记录包括安装步骤、核心用法、Java场景实战和好几处只有真正跑过才会踩到的坑给那些想让AI从“会写代码”进阶到“会干工程”的开发者做个参考。1. 为什么“会写代码”和“会干工程”之间差了一个Superpowers1.1 Codex直接把需求翻译成代码但代码不等于可维护的模块先说结论Codex本身是个优秀的“代码生成器”但它不是“工程生成器”。给它一个Controller需求它会按最常见的模板给你生成Rest接口可一旦放到真实项目里问题马上冒出来——DTO该放哪个包、事务边界要不要拆到Service层、异常是抛还是吞、日志打什么级别、参数校验是走注解还是手动校验。这些东西散落在你团队的历史代码和开发规范里Codex根本看不到它只能按“全网最大共识”来写。所以我最开始的做法就是把每个项目的编码规范整理成一份rules.md然后每次对话都贴给Codex。听起来简单但实际操作下来有两个问题一是提示词重复粘贴聊天窗口很快被撑满真正有用的任务信息反而挤掉了二是每次贴的措辞稍微不同Codex的理解就飘今天遵守了ResultVO统一返回明天又给你裸返回实体类。规则在没有结构约束的情况下只能算“建议”算不上“纪律”。1.2 我真正需要的是一套能把规范固化成“肌肉记忆”的方案我需要的是这样一套机制在项目根目录放好规则文件启动对话时自动加载不需要我手动复制任务进来时先拆成子任务清单而不是一股脑把完整需求丢给模型让它自由发挥代码生成后有一套检查点至少把最常见的低级错误挡在提交之前。这套机制最好还能用脚本一键初始化到新项目里让我从繁琐的“重复写提示词”中解放出来。Superpowers这个名字听起来宏大其实内核很简单规则注入、任务拆解、输出校验、上下文管理。这四个能力组合起来Codex才从“体外工具”变成了“团队里一个默认懂规矩的新同事”。这篇文章后面所有内容都围绕这四个方面展开。2. 从零安装Superpowers依赖、脚本与第一份规则文件2.1 安装前置条件别在Node和Java版本上栽跟头Superpowers本身是一组Shell脚本、Markdown规则模板和一个轻量的提示词生成器不依赖重型运行时。但如果你要在Java项目里使用那JDK版本必须提前确认。我实测下来OpenJDK 17和21都能顺畅跑而JDK 8会因为缺少很多语言特性导致Codex生成的代码动不动就编译失败——不是你配置的问题是生态版本差太多。另外Codex CLI的安装很简单一条npm install -g openai/codex就行国内外源都试过建议直接用npm官方源反而最稳。装完之后记得先登录一次把Credential配置好。Superpowers的所有脚本都是站在Codex已经可用的前提下做的所以这一步跳不过去。2.2 初始化脚本一条命令生成标准目录结构我习惯把所有写好的模板托管在Git仓库里然后用init-superpowers.sh一键复制到新项目。目录结构长这样project-root/ ├── .superpowers/ │ ├── rules.md # 全局编码规范 │ ├── task-template.md # 子任务拆解模板 │ ├── review-checklist.md │ └── scripts/ │ ├── inject-context.sh │ └── run-tests.sh └── SUPER_POWERS_PLAN.md # 当前进行中的任务计划重点在于rules.md必须放在项目内而不是放在用户目录。因为每个项目的规范不同放在项目内可以交给版本管理团队所有人都能同步放在用户目录的话一旦换机器或者多人协作规则就漂移了。执行初始化命令也简单chmod x .superpowers/scripts/*.sh ./.superpowers/scripts/inject-context.sh --project-root . --rules-file .superpowers/rules.md这个脚本做的事很朴素把rules.md内容包在一个固定格式的提示词块里和项目里的关键文件列表合并最后拼出一条启动Codex会话的指令。你不需要关心拼接细节只要知道它保证了“每次启动Codex规则一定在上下文里”。2.3 编写第一份规则文件从可量化的条目开始rules.md最忌讳写空话。比如“代码需具备良好的可读性”这种规则Codex无法执行因为它没有判定标准。我会把规则拆成机器可判定的表达所有REST接口必须在ResponseBody中返回统一封装类型ResultVOTService层禁止直接暴露实体类入参和出参必须使用DTO对象方法长度超过60行必须拆分拆分子方法命名需体现业务动作日志必须包含traceId禁止使用print输出所有外部接口调用必须设置超时时间和熔断兜底这样的规则Codex才能真正“遵守”。我见过很多人抱怨“AI生成的代码不符合团队规范”其实根子不在AI而是规则写得太抽象。Superpowers的规则模板里每条后面都留了一个“该规则对应的检查点”后面在代码审查阶段这些检查点会变成脚本里的grep关键词。3. 启动Singularity把需求拆成可执行的Superpowers任务流3.1 为什么不能把完整需求一次性丢给Codex有段时间我图省事把一个包括权限校验、分页查询、缓存更新、审计日志的四合一需求整段贴给Codex。结果是代码确实把四个功能都实现了但耦合度爆表缓存更新逻辑和权限校验放在同一层审计日志还重复写了两遍。后来我复盘核心问题在于上下文一次性承载了太多目标模型很容易把早期的决策带偏又无法在中途纠正。所以Superpowers强制规定任何需求进入Codex之前必须先用task-template.md拆成子任务。这个模板长这样## 子任务1定义DTO与VO 目标产出请求参数校验类、返回结果封装类 涉及文件dto/、vo/ 依赖项无 完成标准所有字段包含javax.validation注解 ## 子任务2Service层事务与业务规则 目标产出业务处理逻辑核心 涉及文件service/、service/impl/ 依赖项子任务1 完成标准包含事务注解异常处理集中在全局异常块拆子任务的意义不仅仅是让Codex分步生成代码更重要的是每一步都带着“完成标准”。完成标准通常是可以自动验证的比如“所有字段包含注解”让后续的检查脚本有东西可查也让提前拦截错误成为可能。3.2 用inject-context.sh生成带完整上下文的启动命令手动拆任务依然累所以我把拆解也半自动化了。做法是在初始化时生成一份SUPER_POWERS_PLAN.md然后从需求入手先写下粗糙的任务清单再用一条命令让Codex帮助细化清单。codex exec .superpowers/scripts/refine-plan.md 文件的指令根据以下需求细化任务清单${REQUIREMENT}这里refine-plan.md是一个特殊的提示词我让它扮演了“技术经理”的角色负责把模糊需求拆成可执行任务。它输出的结果会直接更新SUPER_POWERS_PLAN.md然后我人工审阅一遍确认任务边界、依赖关系、完成标准都没问题接下来才是让Codex按清单逐项实现。这一步是整个Superpowers工作流里最容易被跳过、也是最关键的一环。前期的任务设计决定了后面代码生成的流畅度。如果你发现Codex生成的代码总是跑偏先别急着换模型回头检查任务拆解颗粒度是否够小。3.3 子任务生成时保持会话连续性而不是每次都新开会话Superpowers的脚本里我特意加了一个会话历史的持久化逻辑每个子任务的结果都追加写入SUPER_POWERS_PLAN.md的“完成记录”区块。这样一来下一个子任务的上下文里就有了前一个任务的实际代码片段而不是像独立对话一样从干净的白纸开始。举个例子子任务1生成了UserCreateDTO子任务2生成Service时就知道引用UserCreateDTO而不是再发明一个同名类。这个“记忆”是靠工作区文件传递的不依赖Codex的上下文窗口大小。算是“外挂记忆”的一种虽然简陋但非常有效。实际用下来代码间的衔接率从40%提升到了85%左右。4. Java实战用一个Spring Boot用户模块跑通整个流程4.1 场景设定正经的需求别拿Hello World糊弄为了演示我拿一个真实项目里最常见的“会员注册”接口来跑一遍。需求不复杂但足够覆盖Controller、Service、Mapper、Transactional、参数校验和异常处理。原始的完整需求是“用户提交手机号、密码、昵称完成注册。手机号需唯一密码加密存储注册成功后返回用户基本信息如果手机号重复则抛出业务异常提示‘该手机号已注册’。”单看这句话Codex完全可以生成能用的代码。但我们按Superpowers流程走一遍你会发现最终代码和直接生成的结果在结构上差别明显。4.2 子任务拆解与生成过程实录按照模板我将需求拆分为定义UserCreateRequestDTO和UserVO返回对象加上基础校验定义UserMapper接口和XML文件包含插入用户和按手机号查询创建UserServiceImpl实现事务、密码加密、手机号重复校验创建UserController调用Service并统一返回ResultVO补充全局异常处理和消息常量然后依次让Codex执行每个子任务。每个子任务启动时我都会通过inject-context传给它当前项目的rules.md以及SUPER_POWERS_PLAN.md中前一个任务的“完成记录”。以第二个子任务为例Codex生成的Mapper方法长这样Mapper public interface UserMapper { int insertUser(UserDO userDO); UserDO selectByMobile(Param(mobile) String mobile); }这里有个细节我原本的规则要求所有查询都必须带ParamCodex遵守了。而如果直接丢完整需求给它它很可能只生成一个selectByMobile(String mobile)忘了加注解像我所在的团队mybatis参数如果没写Param在XML里会报“Parameter mobile not found”的坑。第三个子任务是核心实现Codex生成的事务逻辑和异常处理如下Transactional(rollbackFor Exception.class) public UserVO register(UserCreateRequest request) { UserDO exist userMapper.selectByMobile(request.getMobile()); if (exist ! null) { throw new BusinessException(MobileAlreadyRegisteredException); } UserDO user new UserDO(); BeanUtils.copyProperties(request, user); user.setPassword(passwordEncoder.encode(request.getPassword())); user.setStatus(1); userMapper.insertUser(user); return userConverter.toVO(user); }注意它使用了rollbackFor Exception.class而不是默认的RuntimeException这是我规则里明确要求的一项。实际项目里如果插入成功后出现后续异常默认事务不会回滚这是很严重的生产问题。这条规则救过我们一次后面会详细说。4.3 review-checklist脚本帮你拦住哪几类低级错误子任务全部完成后调用.superpowers/scripts/review-checklist.sh它会扫描生成的代码检查是否存在我定义的高频违规项。检测的逻辑很简单grep正则。支持场景有限但抓低级的“关键点错误”非常靠谱。以下是模拟的输出检查点1所有Service实现类是否包含Transactional注解检查点2Controller方法是否返回ResultVOT封装类型检查点3是否存在System.out.println等调试代码检查点4Mapper参数是否全部携带Param注解检查点5密码字段是否包含passwordEncoder加密调用脚本执行到第四个检查点时真的发现了问题。在第三个子任务生成的ServiceImpl中有一个查询用户的方法为了让日志便于排查临时写了一句System.out.println。代码独体看起来没问题但如果没人检查就会流到正式提交里。而脚本在那个瞬间直接高亮报错我当时心里“咯噔”一下然后默默感慨Superpowers这套检查机制的价值就在这儿不是在AI生成时要求完美而是生成后真的验证。5. 踩坑记录我在Superpowers实战中遇到的主要障碍5.1 “规则注入越多Codex越容易敷衍”刚开始写rules.md我总觉得写得越细越好。一口气写了80多条涵盖命名规范、注释风格、依赖注入方式、异常层次、日志格式、数据库命名等等。结果Codex生成代码时开始明显“变笨”——它为了同时满足所有规则生成了大量冗余代码甚至出现为了加个日志把原有逻辑拆得七零八落的情况。后来我把规则压到20条以内并按照“核心不可妥协项”和“建议项”做了分级。核心项才真正进rules.md参与检查建议项只在需要时通过/role临时提示。规则数量减少之后生成质量反而大幅回升。这印证了一个观点AI上下文里的规则再多也不如真正被强制执行、可以被脚本验证的那几条有效。5.2 上下文窗口溢出任务计划文件越写越大之后SUPER_POWERS_PLAN.md会记录每个子任务的完成情况包括代码片段。但项目一大子任务动辄十几二十个这个文件很快膨胀到几万字符。Codex的上下文窗口有限当你把整个计划文件作为上下文传入时前几个子任务的代码会占用大量Token导致后续任务可用上下文极小甚至出现“忘掉之前任务约定”的情况。我的解决方案上下文里只保留最近3个子任务的“完成记录”更早的记录单独存到archive/目录。需要追溯历史时用codex exec单独查询文件而不是每次都带全量。另外每条“完成记录”只保留核心结论和关键代码签名不要贴整段实现。这样计划文件体积能控制在合理范围内上下文占用也稳定得多。5.3 Java版本和Lombok兼容性引发的连锁反应规则里的“Service层禁止直接暴露实体类返回DTO”是好事但Codex在Java 17下生成代码时会主动使用record来定义DTO导致项目中如果还在用Lombok和传统POJO风格会出现混用。我不是说record不好而是团队代码风格需要统一。否则一个新人接手看到有些对象是record UserVO(...)、有些是带Data的class直觉上会觉得混乱。Superpowers的解决方式是在rules.md里显式声明“本项目DTO使用Lombok的Data注解不用record语法”。这条规则很细但实际作用比想象中大因为Codex在语法上很喜欢“依赖语言新特性”可工程上显然要优先尊重团队习惯。5.4 脚本注入的上下文与Codex新版本格式不兼容有一次Codex CLI更新之后我发现自己过滤出来的消息被它当作普通命令行文本处理而不是作为可忽略的上下文内容。查了更新日志才明白控制台参数中-p和--prompt的行为有所变化导致注入脚本拼接出的命令格式失效。修复方法倒不复杂把注入内容改成文件路径引用通过--prompt-file参数而不是字符串拼接绕开了转义和长度限制的问题。这也提醒了一个很好的习惯不要老是指望CLI工具的某个行为永不改变把上下文注入做成“文件传递式”而不是“文本交织式”抗变化能力会强很多。6. 进阶把Superpowers扩展成团队协同的标准工作流6.1 给不同角色定制不同的“视角文件”Superpowers不只是一个AI增强个人工具它同样适合放进团队协作流程。我给项目配置了三个不同的视角文件在特定场景下切换视角文件适用角色核心关注点architect-rules.md架构师模块依赖、接口边界、设计模式约束dev-rules.md开发者代码风格、单元测试覆盖率、变量命名reviewer-rules.md代码审查者重复代码、性能隐患、异常处理一致性例如做代码审查的时候我用reviewer-rules.md启动Codex让它重点盯“重复代码被复制粘贴的地方”尤其是生成器最常见的“复制-改参数”型代码片段。实测能抓出不少相似度超过90%的方法体提醒我该抽取公共方法。6.2 本地脚本与CI/CD的联动思路脚本的本质是“人肉可执行的检查点”那自然也能挂到CI里。我们目前的做法是review-checklist.sh在提交阶段跑一个简化版只检查被改动文件的违规项跑完结果和普通lint插件一样展示在控制台。如果未来有效果可以考虑接入SonarQube或CodeScene把规则迁移成自动化扫描规则。Superpowers在CI侧的目标不是替代SonarQube这类真扫描工具而是作为一层“预拦截”拦住那些只有团队才知道的、无法用通用静态分析覆盖的约定。比如“Controller必须继承父类接口”这种规则通用扫描器不认识但我们自己认可我们就自己救自己。6.3 哪些任务不该交给Superpowers我用半年时间得出的边界合成不等于万能Superpowers也有明确不适合的场景。我踩坑后梳理了一条判断标准适合结构化接CRUD、批量DTO/BO转换、常见设计模式落地、单元测试补全谨慎多轮技术方案推演、接口设计冲突协调、底层性能调优不适合涉及机密数据的脱敏逻辑、需要多人实时共识的架构决策把架构决策交给AI很危险因为它会给你一个方案但不会替你想清楚团队是不是能维护。这个边界不是Superpowers的局限性而是AI辅助开发的基本伦理——工具负责提速人负责踩刹车。写在最后我的Superpowers还在持续演进Superpowers不是某个遥远的技术平台它是我自己在一线开发中从上万次与Codex的交互里沉淀出来的一个“行为信封”。把规则、任务、检查、记忆封装好AI这股鹅毛巨力才能变成真正被驾驭的“超级力量”。现在的我已经没法想象回到“不给Codex注入上下文就直接写代码”的状态了。那感觉就像让一个经验丰富的工程师蒙着眼睛做架构不是他不行而是你给的环境太不尊重他。如果你也在被AI生成代码的工程适配问题困扰那么建议你从最小的一步做起建立一个rules.md放5条你真正在乎的约束然后接下来每一次让Codex干活前都把这份规则递给它。哪怕全面换用Superpowers工程量很大但这件事本身带来的改变就已经足够巨大。
Superpowers：让Codex从代码生成器变成工程助手
如果你用过Codex这类AI编程助手多少会有一种“它能写代码但写不出我要的工程”的憋屈感。代码片段倒是一套一套的可真放进项目里命名规范不统一、缺少异常处理、不考虑历史包袱改起来比手写还累。这就像发动机给你拉满但变速箱完全没接上。我后来花了两个多月给自己这套工作流起了个名字叫Superpowers本质是一层架在Codex之上的增强配置通过规则文件、任务拆解模板和自动化脚本来约束AI的行为让生成结果从“能用”变成“符合工程标准地好用”。这篇文章是完整的搭建记录包括安装步骤、核心用法、Java场景实战和好几处只有真正跑过才会踩到的坑给那些想让AI从“会写代码”进阶到“会干工程”的开发者做个参考。1. 为什么“会写代码”和“会干工程”之间差了一个Superpowers1.1 Codex直接把需求翻译成代码但代码不等于可维护的模块先说结论Codex本身是个优秀的“代码生成器”但它不是“工程生成器”。给它一个Controller需求它会按最常见的模板给你生成Rest接口可一旦放到真实项目里问题马上冒出来——DTO该放哪个包、事务边界要不要拆到Service层、异常是抛还是吞、日志打什么级别、参数校验是走注解还是手动校验。这些东西散落在你团队的历史代码和开发规范里Codex根本看不到它只能按“全网最大共识”来写。所以我最开始的做法就是把每个项目的编码规范整理成一份rules.md然后每次对话都贴给Codex。听起来简单但实际操作下来有两个问题一是提示词重复粘贴聊天窗口很快被撑满真正有用的任务信息反而挤掉了二是每次贴的措辞稍微不同Codex的理解就飘今天遵守了ResultVO统一返回明天又给你裸返回实体类。规则在没有结构约束的情况下只能算“建议”算不上“纪律”。1.2 我真正需要的是一套能把规范固化成“肌肉记忆”的方案我需要的是这样一套机制在项目根目录放好规则文件启动对话时自动加载不需要我手动复制任务进来时先拆成子任务清单而不是一股脑把完整需求丢给模型让它自由发挥代码生成后有一套检查点至少把最常见的低级错误挡在提交之前。这套机制最好还能用脚本一键初始化到新项目里让我从繁琐的“重复写提示词”中解放出来。Superpowers这个名字听起来宏大其实内核很简单规则注入、任务拆解、输出校验、上下文管理。这四个能力组合起来Codex才从“体外工具”变成了“团队里一个默认懂规矩的新同事”。这篇文章后面所有内容都围绕这四个方面展开。2. 从零安装Superpowers依赖、脚本与第一份规则文件2.1 安装前置条件别在Node和Java版本上栽跟头Superpowers本身是一组Shell脚本、Markdown规则模板和一个轻量的提示词生成器不依赖重型运行时。但如果你要在Java项目里使用那JDK版本必须提前确认。我实测下来OpenJDK 17和21都能顺畅跑而JDK 8会因为缺少很多语言特性导致Codex生成的代码动不动就编译失败——不是你配置的问题是生态版本差太多。另外Codex CLI的安装很简单一条npm install -g openai/codex就行国内外源都试过建议直接用npm官方源反而最稳。装完之后记得先登录一次把Credential配置好。Superpowers的所有脚本都是站在Codex已经可用的前提下做的所以这一步跳不过去。2.2 初始化脚本一条命令生成标准目录结构我习惯把所有写好的模板托管在Git仓库里然后用init-superpowers.sh一键复制到新项目。目录结构长这样project-root/ ├── .superpowers/ │ ├── rules.md # 全局编码规范 │ ├── task-template.md # 子任务拆解模板 │ ├── review-checklist.md │ └── scripts/ │ ├── inject-context.sh │ └── run-tests.sh └── SUPER_POWERS_PLAN.md # 当前进行中的任务计划重点在于rules.md必须放在项目内而不是放在用户目录。因为每个项目的规范不同放在项目内可以交给版本管理团队所有人都能同步放在用户目录的话一旦换机器或者多人协作规则就漂移了。执行初始化命令也简单chmod x .superpowers/scripts/*.sh ./.superpowers/scripts/inject-context.sh --project-root . --rules-file .superpowers/rules.md这个脚本做的事很朴素把rules.md内容包在一个固定格式的提示词块里和项目里的关键文件列表合并最后拼出一条启动Codex会话的指令。你不需要关心拼接细节只要知道它保证了“每次启动Codex规则一定在上下文里”。2.3 编写第一份规则文件从可量化的条目开始rules.md最忌讳写空话。比如“代码需具备良好的可读性”这种规则Codex无法执行因为它没有判定标准。我会把规则拆成机器可判定的表达所有REST接口必须在ResponseBody中返回统一封装类型ResultVOTService层禁止直接暴露实体类入参和出参必须使用DTO对象方法长度超过60行必须拆分拆分子方法命名需体现业务动作日志必须包含traceId禁止使用print输出所有外部接口调用必须设置超时时间和熔断兜底这样的规则Codex才能真正“遵守”。我见过很多人抱怨“AI生成的代码不符合团队规范”其实根子不在AI而是规则写得太抽象。Superpowers的规则模板里每条后面都留了一个“该规则对应的检查点”后面在代码审查阶段这些检查点会变成脚本里的grep关键词。3. 启动Singularity把需求拆成可执行的Superpowers任务流3.1 为什么不能把完整需求一次性丢给Codex有段时间我图省事把一个包括权限校验、分页查询、缓存更新、审计日志的四合一需求整段贴给Codex。结果是代码确实把四个功能都实现了但耦合度爆表缓存更新逻辑和权限校验放在同一层审计日志还重复写了两遍。后来我复盘核心问题在于上下文一次性承载了太多目标模型很容易把早期的决策带偏又无法在中途纠正。所以Superpowers强制规定任何需求进入Codex之前必须先用task-template.md拆成子任务。这个模板长这样## 子任务1定义DTO与VO 目标产出请求参数校验类、返回结果封装类 涉及文件dto/、vo/ 依赖项无 完成标准所有字段包含javax.validation注解 ## 子任务2Service层事务与业务规则 目标产出业务处理逻辑核心 涉及文件service/、service/impl/ 依赖项子任务1 完成标准包含事务注解异常处理集中在全局异常块拆子任务的意义不仅仅是让Codex分步生成代码更重要的是每一步都带着“完成标准”。完成标准通常是可以自动验证的比如“所有字段包含注解”让后续的检查脚本有东西可查也让提前拦截错误成为可能。3.2 用inject-context.sh生成带完整上下文的启动命令手动拆任务依然累所以我把拆解也半自动化了。做法是在初始化时生成一份SUPER_POWERS_PLAN.md然后从需求入手先写下粗糙的任务清单再用一条命令让Codex帮助细化清单。codex exec .superpowers/scripts/refine-plan.md 文件的指令根据以下需求细化任务清单${REQUIREMENT}这里refine-plan.md是一个特殊的提示词我让它扮演了“技术经理”的角色负责把模糊需求拆成可执行任务。它输出的结果会直接更新SUPER_POWERS_PLAN.md然后我人工审阅一遍确认任务边界、依赖关系、完成标准都没问题接下来才是让Codex按清单逐项实现。这一步是整个Superpowers工作流里最容易被跳过、也是最关键的一环。前期的任务设计决定了后面代码生成的流畅度。如果你发现Codex生成的代码总是跑偏先别急着换模型回头检查任务拆解颗粒度是否够小。3.3 子任务生成时保持会话连续性而不是每次都新开会话Superpowers的脚本里我特意加了一个会话历史的持久化逻辑每个子任务的结果都追加写入SUPER_POWERS_PLAN.md的“完成记录”区块。这样一来下一个子任务的上下文里就有了前一个任务的实际代码片段而不是像独立对话一样从干净的白纸开始。举个例子子任务1生成了UserCreateDTO子任务2生成Service时就知道引用UserCreateDTO而不是再发明一个同名类。这个“记忆”是靠工作区文件传递的不依赖Codex的上下文窗口大小。算是“外挂记忆”的一种虽然简陋但非常有效。实际用下来代码间的衔接率从40%提升到了85%左右。4. Java实战用一个Spring Boot用户模块跑通整个流程4.1 场景设定正经的需求别拿Hello World糊弄为了演示我拿一个真实项目里最常见的“会员注册”接口来跑一遍。需求不复杂但足够覆盖Controller、Service、Mapper、Transactional、参数校验和异常处理。原始的完整需求是“用户提交手机号、密码、昵称完成注册。手机号需唯一密码加密存储注册成功后返回用户基本信息如果手机号重复则抛出业务异常提示‘该手机号已注册’。”单看这句话Codex完全可以生成能用的代码。但我们按Superpowers流程走一遍你会发现最终代码和直接生成的结果在结构上差别明显。4.2 子任务拆解与生成过程实录按照模板我将需求拆分为定义UserCreateRequestDTO和UserVO返回对象加上基础校验定义UserMapper接口和XML文件包含插入用户和按手机号查询创建UserServiceImpl实现事务、密码加密、手机号重复校验创建UserController调用Service并统一返回ResultVO补充全局异常处理和消息常量然后依次让Codex执行每个子任务。每个子任务启动时我都会通过inject-context传给它当前项目的rules.md以及SUPER_POWERS_PLAN.md中前一个任务的“完成记录”。以第二个子任务为例Codex生成的Mapper方法长这样Mapper public interface UserMapper { int insertUser(UserDO userDO); UserDO selectByMobile(Param(mobile) String mobile); }这里有个细节我原本的规则要求所有查询都必须带ParamCodex遵守了。而如果直接丢完整需求给它它很可能只生成一个selectByMobile(String mobile)忘了加注解像我所在的团队mybatis参数如果没写Param在XML里会报“Parameter mobile not found”的坑。第三个子任务是核心实现Codex生成的事务逻辑和异常处理如下Transactional(rollbackFor Exception.class) public UserVO register(UserCreateRequest request) { UserDO exist userMapper.selectByMobile(request.getMobile()); if (exist ! null) { throw new BusinessException(MobileAlreadyRegisteredException); } UserDO user new UserDO(); BeanUtils.copyProperties(request, user); user.setPassword(passwordEncoder.encode(request.getPassword())); user.setStatus(1); userMapper.insertUser(user); return userConverter.toVO(user); }注意它使用了rollbackFor Exception.class而不是默认的RuntimeException这是我规则里明确要求的一项。实际项目里如果插入成功后出现后续异常默认事务不会回滚这是很严重的生产问题。这条规则救过我们一次后面会详细说。4.3 review-checklist脚本帮你拦住哪几类低级错误子任务全部完成后调用.superpowers/scripts/review-checklist.sh它会扫描生成的代码检查是否存在我定义的高频违规项。检测的逻辑很简单grep正则。支持场景有限但抓低级的“关键点错误”非常靠谱。以下是模拟的输出检查点1所有Service实现类是否包含Transactional注解检查点2Controller方法是否返回ResultVOT封装类型检查点3是否存在System.out.println等调试代码检查点4Mapper参数是否全部携带Param注解检查点5密码字段是否包含passwordEncoder加密调用脚本执行到第四个检查点时真的发现了问题。在第三个子任务生成的ServiceImpl中有一个查询用户的方法为了让日志便于排查临时写了一句System.out.println。代码独体看起来没问题但如果没人检查就会流到正式提交里。而脚本在那个瞬间直接高亮报错我当时心里“咯噔”一下然后默默感慨Superpowers这套检查机制的价值就在这儿不是在AI生成时要求完美而是生成后真的验证。5. 踩坑记录我在Superpowers实战中遇到的主要障碍5.1 “规则注入越多Codex越容易敷衍”刚开始写rules.md我总觉得写得越细越好。一口气写了80多条涵盖命名规范、注释风格、依赖注入方式、异常层次、日志格式、数据库命名等等。结果Codex生成代码时开始明显“变笨”——它为了同时满足所有规则生成了大量冗余代码甚至出现为了加个日志把原有逻辑拆得七零八落的情况。后来我把规则压到20条以内并按照“核心不可妥协项”和“建议项”做了分级。核心项才真正进rules.md参与检查建议项只在需要时通过/role临时提示。规则数量减少之后生成质量反而大幅回升。这印证了一个观点AI上下文里的规则再多也不如真正被强制执行、可以被脚本验证的那几条有效。5.2 上下文窗口溢出任务计划文件越写越大之后SUPER_POWERS_PLAN.md会记录每个子任务的完成情况包括代码片段。但项目一大子任务动辄十几二十个这个文件很快膨胀到几万字符。Codex的上下文窗口有限当你把整个计划文件作为上下文传入时前几个子任务的代码会占用大量Token导致后续任务可用上下文极小甚至出现“忘掉之前任务约定”的情况。我的解决方案上下文里只保留最近3个子任务的“完成记录”更早的记录单独存到archive/目录。需要追溯历史时用codex exec单独查询文件而不是每次都带全量。另外每条“完成记录”只保留核心结论和关键代码签名不要贴整段实现。这样计划文件体积能控制在合理范围内上下文占用也稳定得多。5.3 Java版本和Lombok兼容性引发的连锁反应规则里的“Service层禁止直接暴露实体类返回DTO”是好事但Codex在Java 17下生成代码时会主动使用record来定义DTO导致项目中如果还在用Lombok和传统POJO风格会出现混用。我不是说record不好而是团队代码风格需要统一。否则一个新人接手看到有些对象是record UserVO(...)、有些是带Data的class直觉上会觉得混乱。Superpowers的解决方式是在rules.md里显式声明“本项目DTO使用Lombok的Data注解不用record语法”。这条规则很细但实际作用比想象中大因为Codex在语法上很喜欢“依赖语言新特性”可工程上显然要优先尊重团队习惯。5.4 脚本注入的上下文与Codex新版本格式不兼容有一次Codex CLI更新之后我发现自己过滤出来的消息被它当作普通命令行文本处理而不是作为可忽略的上下文内容。查了更新日志才明白控制台参数中-p和--prompt的行为有所变化导致注入脚本拼接出的命令格式失效。修复方法倒不复杂把注入内容改成文件路径引用通过--prompt-file参数而不是字符串拼接绕开了转义和长度限制的问题。这也提醒了一个很好的习惯不要老是指望CLI工具的某个行为永不改变把上下文注入做成“文件传递式”而不是“文本交织式”抗变化能力会强很多。6. 进阶把Superpowers扩展成团队协同的标准工作流6.1 给不同角色定制不同的“视角文件”Superpowers不只是一个AI增强个人工具它同样适合放进团队协作流程。我给项目配置了三个不同的视角文件在特定场景下切换视角文件适用角色核心关注点architect-rules.md架构师模块依赖、接口边界、设计模式约束dev-rules.md开发者代码风格、单元测试覆盖率、变量命名reviewer-rules.md代码审查者重复代码、性能隐患、异常处理一致性例如做代码审查的时候我用reviewer-rules.md启动Codex让它重点盯“重复代码被复制粘贴的地方”尤其是生成器最常见的“复制-改参数”型代码片段。实测能抓出不少相似度超过90%的方法体提醒我该抽取公共方法。6.2 本地脚本与CI/CD的联动思路脚本的本质是“人肉可执行的检查点”那自然也能挂到CI里。我们目前的做法是review-checklist.sh在提交阶段跑一个简化版只检查被改动文件的违规项跑完结果和普通lint插件一样展示在控制台。如果未来有效果可以考虑接入SonarQube或CodeScene把规则迁移成自动化扫描规则。Superpowers在CI侧的目标不是替代SonarQube这类真扫描工具而是作为一层“预拦截”拦住那些只有团队才知道的、无法用通用静态分析覆盖的约定。比如“Controller必须继承父类接口”这种规则通用扫描器不认识但我们自己认可我们就自己救自己。6.3 哪些任务不该交给Superpowers我用半年时间得出的边界合成不等于万能Superpowers也有明确不适合的场景。我踩坑后梳理了一条判断标准适合结构化接CRUD、批量DTO/BO转换、常见设计模式落地、单元测试补全谨慎多轮技术方案推演、接口设计冲突协调、底层性能调优不适合涉及机密数据的脱敏逻辑、需要多人实时共识的架构决策把架构决策交给AI很危险因为它会给你一个方案但不会替你想清楚团队是不是能维护。这个边界不是Superpowers的局限性而是AI辅助开发的基本伦理——工具负责提速人负责踩刹车。写在最后我的Superpowers还在持续演进Superpowers不是某个遥远的技术平台它是我自己在一线开发中从上万次与Codex的交互里沉淀出来的一个“行为信封”。把规则、任务、检查、记忆封装好AI这股鹅毛巨力才能变成真正被驾驭的“超级力量”。现在的我已经没法想象回到“不给Codex注入上下文就直接写代码”的状态了。那感觉就像让一个经验丰富的工程师蒙着眼睛做架构不是他不行而是你给的环境太不尊重他。如果你也在被AI生成代码的工程适配问题困扰那么建议你从最小的一步做起建立一个rules.md放5条你真正在乎的约束然后接下来每一次让Codex干活前都把这份规则递给它。哪怕全面换用Superpowers工程量很大但这件事本身带来的改变就已经足够巨大。
