如果你用过Codex这类AI编程助手，多少会有一种“它能写代码，但写不出我要的工程”的憋屈感。代码片段倒是一套一套的，可真放进项目里，命名规范不统一、缺少异常处理、不考虑历史包袱，改起来比手写还累。这就像发动机给你拉满，但变速箱完全没接上。我后来花了两个多月，给自己这套工作流起了个名字叫Superpowers，本质是一层架在Codex之上的增强配置：通过规则文件、任务拆解模板和自动化脚本来约束AI的行为，让生成结果从“能用”变成“符合工程标准地好用”。这篇文章是完整的搭建记录，包括安装步骤、核心用法、Java场景实战和好几处只有真正跑过才会踩到的坑，给那些想让AI从“会写代码”进阶到“会干工程”的开发者做个参考。
1. 为什么“会写代码”和“会干工程”之间，差了一个Superpowers
1.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中返回统一封装类型
ResultVO<T> - Service层禁止直接暴露实体类，入参和出参必须使用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注解 ## 子任务2：Service层事务与业务规则 目标产出：业务处理逻辑核心 涉及文件：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); }这里有个细节：我原本的规则要求所有查询都必须带@Param，Codex遵守了。而如果直接丢完整需求给它，它很可能只生成一个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注解 - 检查点2：Controller方法是否返回
ResultVO<T>封装类型 - 检查点3：是否存在
System.out.println等调试代码 - 检查点4：Mapper参数是否全部携带
@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工程量很大，但这件事本身带来的改变，就已经足够巨大。
