企业官网建设流程全解析

如果你最近在用 Codex CLI 辅助写代码，大概率已经体验过那种“聊得挺好，干起活来又差半口气”的感觉：它能理解需求，但面对一个多文件改造时，经常要来回追问好几轮，改着改着还会偏离方向。“superpowers”这个项目我第一次看到的时候，就觉得名字起得特别准——它给 Codex 装上了一组可复用的“超能力”斜杠命令，把 AI 从“随叫随到的问答助手”变成“会规划、能执行、懂自查的结对同事”。这篇文章是我从零部署、再到真实 Java 服务改造项目里跑完整流程的记录，适合正在用、或者正准备用 Codex CLI 做日常开发的工程师参考。

1. 为什么需要 superpowers：Codex 原生能力的最后一公里

1.1 从“能聊天”到“能干活”的差距

Codex CLI 本身已经具备很强的代码理解和生成能力，但原生的交互方式更偏“对话驱动”。你每次开一个新会话，都要重新交代一遍项目背景、代码规范、测试要求，甚至要反复强调“别动不相关的文件”。这种重复劳动在单文件小任务上还能忍，一旦碰上一个跨模块的改动，会话上下文会迅速膨胀，AI 的注意力反而被稀释。

我做第一个真实项目时，就吃过这方面的亏：让 Codex 给一个 Spring Boot 服务加新接口，它连续改了三个 Controller 文件，还把两个不该动的 Mapper 给“顺手优化”了。问题不在模型能力，而在于没有一个稳定的作业框架去约束它。superpowers 做的就是这件事：它把一套经过验证的作业流程固化成命令，让 Codex 每次开工前先想清楚“我要改什么、影响到谁、怎么验证”。

1.2 核心定位：把“约束”变成“资产”

superpowers 的设计思路，本质上是把“提示词工程”升级成“命令文件工程”。它利用 Codex CLI 的自定义斜杠命令机制，在~/.codex/commands/下挂载了一大批 Markdown 命令定义。每个命令文件都包含一段精心设计的指令模板，有的还会调用本地辅助脚本来做代码库扫描、生成结构化上下文。

用个生活类比：Codex 原生状态像一个聪明但没受过训练的新员工，你问一句他答一句，做事毫无章法；superpowers 就像给这个新员工发了一套标准作业指导书。它不是换一个人，而是让同一个人按照成熟的工作流去干活。每次调用/plan、/implement时，Codex 都会先读取对应的命令模板，按模板里的步骤执行，而不是凭直觉乱来。

1.3 命令是怎么被加载和执行的

这套机制的关键在于 Codex CLI 本身已经支持用户自定义 slash commands。你可以在~/.codex/commands/下放一个 Markdown 文件，文件名就是命令名，文件内容就是命令触发时注入给模型的提示词。superpowers 只不过把这套机制玩到了极致：它不是一两个命令，而是一整组互相配合的命令，还带共享脚本和配置。

安装之后，你进入 Codex 交互界面输入/help，会看到比原生多出一大串命令。这些命令有的负责“看”（代码扫描、影响分析），有的负责“想”（拆解任务、制定计划），有的负责“做”（改代码、跑测试），有的负责“查”（审查 diff、复盘问题）。命令与命令之间还有明确的输入输出关系，比如/analyze的产物可以直接喂给/plan，让整个会话像流水线一样推进。这也是为什么它叫 superpowers——单看每个命令可能不起眼，组合起来就是一套完整的工作流。

2. 安装与环境准备：从零跑通

2.1 前置条件检查

动手安装之前，先确认三样东西：Codex CLI 本体、Node.js 运行时、以及 Git。superpowers 本身不修改 Codex 的二进制，只依赖它的自定义命令机制，所以 Codex CLI 版本不能太老，建议至少是 0.3x 之后的版本，越新越好，因为自定义命令的解析能力一直在迭代。

Node.js 是用来跑辅助脚本的，建议 18 以上，20 更稳。Git 主要用于代码仓库操作，某些命令（比如生成 diff 报告、回滚改动）会依赖它。检查方式很简单：

codex --version node --version git --version

如果版本正常，就可以继续。这里有个小提醒：如果你之前给 Codex 配置过别的自定义命令，先备份一下~/.codex/commands/目录，避免安装过程覆盖掉你已有的东西。别问我怎么知道的——我第一台测试机上就有过一个自己写的daily命令，安装 superpowers 时没备份，直接被顶掉了。

2.2 安装步骤与方式选择

superpowers 的安装方式主要有两种，我推荐先用 npm 全局安装，省事，升级方便。

npm install -g codex-superpowers

安装完成后，执行初始化命令：

superpowers setup

它会自动检测 Codex CLI 的配置目录，把命令文件写入~/.codex/commands/，同时备份原有的配置文件。整个过程中你只需要确认几个 yes/no 的问题，基本无脑。

不想用 npm 的话，也可以从 GitHub 仓库直接拉源码：搜索codex-superpowers，clone 到本地后运行仓库里的install.sh（有的版本是make install）。源码安装的好处是你会得到一个完整的项目目录，方便自己改命令模板。缺点是升级时得手动拉代码再跑一次安装，不如 npm 干净。

以下是我实际测试后的选型参考：

2.3 验证安装与目录结构

安装结束后，我建议先跑一次验证，别直接上生产项目。进入一个空目录，启动 Codex：

codex

在交互界面输入/help，如果看到类似/analyze、/plan、/implement、/test、/review这些命令，说明安装成功。

再去看一眼目录结构：

~/.codex/commands/ ├── analyze.md ├── plan.md ├── implement.md ├── test.md ├── review.md ├── refactor.md ├── fix.md └── shared/ ├── scan.js └── context.js

shared/目录里的脚本是命令的“幕后工具”，负责扫描代码结构、提取上下文。重点在于：这些 Markdown 文件都是纯文本，你随时可以打开看，甚至直接改。也就是说，superpowers 的每个“超能力”你都能拆开研究，而不是黑盒。这一点对我后来做团队定制特别重要。

3. 核心命令拆解：把 Codex 变成真正的队友

3.1 命令的分层设计逻辑

我第一次看命令清单时有点懵，命令太多了。跑了几轮项目之后才摸清楚，它们的组织逻辑是“分析—规划—执行—检查—复盘”五个阶段。每个阶段的命令只负责一件事，且尽量不越界。这样设计的好处是：你可以只用一个阶段的命令，也可以全流程串起来用。

以/analyze为例，它只做代码理解和问题发现，不写任何代码；/plan只在拿到分析结果后做任务拆解；/implement才真正动手改代码。层级清晰，职责单一。真出了问题，你能快速定位是“分析错了”还是“执行错了”，不用去猜是整个流程哪里崩的。

3.2 分析类命令：先搞清楚现状再动手

/analyze是整套工作流的入口命令。它会扫描当前代码库，识别项目类型、依赖关系、模块边界，以及调用链上的关键文件。在 Java 项目里，它能识别出 Maven 或 Gradle 的结构，甚至能大致圈出 Spring Bean 的依赖方向，然后生成一份结构化摘要，告诉 Codex 代码库里有什么、哪些地方“碰了会出事”。

还有一个我常用的(/scan)变体，针对单个模块做快速体检，不会扫全库，适合改动范围明确的小任务。它的输出会收敛到“当前改动涉及的文件清单”和“潜在风险点”两项。这个命令是我每天用得最多的，因为它快，而且能让 Codex 在动手前先“对齐地图”，避免跑到无关目录里去。

3.3 规划与执行类命令：把任务拆到可落地的颗粒度

/plan是我认为整个工具链里最有价值的一个。它会把一个模糊需求（比如“给订单模块加一个导出功能”）拆解成具体的执行步骤，每一条都包含：改哪个文件、为什么要改、影响哪些调用的边界。拆完后它会请你确认，这等于在动手前先做了一次设计评审。

确认计划之后，就可以用/implement按计划执行。执行过程中如果遇到计划里没覆盖到的模糊点，它不会闷头瞎猜，而是回到/plan层补充计划再继续。这个“先补充计划再动手”的行为是模板里写死的，也是它比原生 Codex 靠谱的核心原因。

我实测有一个执行策略参数值得注意，叫--strategy（或者你版本里的--approach）：默认是balanced，稳妥优先；切到aggressive会更快推进，但偶尔会改出多余代码；conservative则每一步都要你确认，适合动核心模块。个人建议：核心代码选conservative，边缘模块用balanced，永远别在跑批量重构时选aggressive，除非你愿意事后逐行 review。

3.4 质量保障类命令：让 AI 自己给自己找毛病

/test命令会分析当前改动涉及的范围，自动定位相关单测，执行并汇总失败用例。它比你自己手敲mvn test然后翻日志要智能的地方在于：它会分析“为什么这个用例会挂”，把失败原因归纳成几条，而不是甩给你一坨堆栈。

/review命令专门用来检查尚未提交的改动。它会从“安全性、可读性、性能、边界条件”几个维度给 diff 打分，并逐文件给出改进建议。它不会替你改，只会提问题，相当于让 Codex 扮演一个“带枪的 code reviewer”。刚开始我用的时候，觉得有些建议很“学究”，但时间久了发现它能抓住不少真实问题，比如某个接口没做空指针防护、某条 SQL 没用参数绑定。

再往下还有/refactor，这个命令跟/implement最大的区别在于：目标是“不改变外部行为、只改善内部结构”。它做完之后会自动要求/test验证，防止重构引入回归。我一般只在有测试覆盖的代码上用它，没有测试的老代码块会先补测试再重构。

3.5 Java 场景实战：superpowers 怎么融入日常开发

说回 Java 开发。我之前拿一个真实的 Spring Boot 服务做实验，任务是“给用户模块增加一个批量查询接口”。完整流程是这样的：

第一轮，我用/analyze扫描整个服务，它识别出 Controller、Service、Mapper 三层结构，并且指出“批量查询如果直接拼 SQL 会有拼 SQL 风险，建议走 MyBatis 的foreach标签”。这个结论其实已经超过我原本的要求，但确实对。

第二轮，/plan把任务拆成了四步：新增 DTO 和 VO、改 Mapper 接口和 XML、改 Service 层、加 Controller 层入口。每一步都标注了影响面，包括需要改哪些测试数据。

第三轮，/implement按计划改完代码，然后调用/test跑了一遍相关模块的单测，第一次跑挂了两个用例——不是因为新代码逻辑错，而是它改动了一个@MapperScan的包路径，影响了旧测试的 bean 注入。这个过程让我很满意：没有命令约束的原生 Codex 不会主动发现这种连锁影响，而 superpowers 的流程会强迫它“做完后自查”，把风险暴露在测试阶段而不是上线后。

如果你用的不是 Spring 而是普通 Java 项目，或者你在写 Android 代码，命令模板本身没有任何 Java 框架预设，你只需要在AGENTS.md里写好“这是什么类型项目、测试用什么框架”，superpowers 的流程依然适用。这点后面单独说。

4. 实际项目中的工作流编排

4.1 一个典型任务从分析到交付的全流程

前面讲的是单命令的能力，真正磨合还在组合使用。我现在处理一个中大型任务的标准流程是这样的：

以我最近一个“给定时任务模块增加失败重试机制”的真实任务为例。/analyze跑完，先把五个相关类列出来了，还标出其中两个类的构造器有循环依赖，这直接影响了“重试逻辑应该放在哪一层”的决策。/plan基于这个分析，给出了“先抽一个重试策略接口，再按类型替换旧实现，最后改动注册中心调用”的路径，并且建议先写测试再重构——这个建议当时看有点保守，事后发现非常正确。

整个流程里我几乎没有手动改代码，只做了三件事：确认计划、看git diff、批准最终改动。一台 AI 编程工具能不能用在生产项目里，就看它能不能把主动权交回给你。

4.2 错误修正与回滚：别让 Codex 把问题越改越大

AI 写代码不是每次都能一步到位。我遇到最多的情况是：/implement改完代码，/test挂了，然后它尝试修复，修着修着波及范围越来越大。superpowers 里的/fix命令就是为了处理这种情况设计的。

/fix会把“当前失败信息 + 相关代码 + 已有改动”作为上下文重新分析，但它会先判断失败根因再动手，而不是像原生 Codex 那样“看到报错就改报错那一行”。这个差别很关键。之前我遇到一个空指针异常，原生 Codex 在第一处调用点加了个判空，结果第二个调用点又报错，循环补丁打了好几轮。用/fix之后，它先审视了整个对象创建链路，发现根因是某个 DTO 的属性没有在工厂方法里赋值，一处修改就解决了。

不过也得说实话，/fix不是万能药，当它连续两轮没找到根因时，我的习惯是手动回滚到上一个稳定点，重启一次分析。回滚操作我强烈建议由人来做，别让 AI 自己git checkout，否则容易出现不可控的连环操作。我的做法是：每次用 superpowers 做完一个阶段，先在本地提交一次，标注wip-superpowers前缀。这样出问题一键回滚，且不丢失阶段进度。

4.3 让 superpowers 适应你的团队习惯

superpowers 的命令模板看起来像是“别人的工作流”，但它最大的优点恰恰是可以改。每个.md文件都是纯文本，你对团队工作流有特殊要求，直接改模板就行。

举个例子，我们团队要求所有新增接口必须带 OpenAPI 注解、所有公共方法的注释必须包含示例，而且 Controller 层不允许写业务逻辑。这些要求早期全靠 code review 的时候人工提醒。后来我直接把/implement模板里的“完成标准”段落改成：“新增或修改的 Controller 方法必须包含 @Operation 注解；Service 层必须处理参数校验；Controller 方法只允许调用一个 Service 方法。”从那之后，Codex 交回来的代码基本没有违反过这些约定。

另外一个重要的团队配置是AGENTS.md文件。这是 Codex 生态通用的项目级说明文件，放在仓库根目录，Codex 启动时会自动读取。superpowers 命令模板会参考这个文件里的信息来做决策，所以你可以在里面写清楚“这个模块属于 XX 业务线”“测试跑命令是mvn test -Dtest=xxx”“禁止使用System.out.println输出日志”等约束。我把这文件称为“团队的面试题库”，因为它才是让 AI 真正融入团队协作的关键，superpowers 是一个严格的面试官，而AGENTS.md是你们团队给出的标准答案。

5. 常见问题与排查技巧实录

5.1 命令不生效或找不到命令

这是我被问得最多的问题，自己也踩过。先说排查顺序：先检查~/.codex/commands/下文件是否真的存在，再检查 Codex CLI 的版本，最后检查是不是同时装了新旧两套配置导致解析冲突。

有一个特别容易忽略的坑：不同版本的 Codex CLI 对自定义命令文件的 front-matter 解析要求不同。early 版本只认标题和正文，新版本支持 model、temperature、permission-mode 等元信息。如果你从旧版本升级后命令突然失效，八成是 front-matter 格式不兼容。解决办法是删掉~/.codex/commands/里的旧文件，重新跑一遍superpowers setup，让初始化脚本写入新格式。

5.2 权限与执行报错

superpowers 的辅助脚本有时会执行文件系统操作（比如扫描目录、读取配置），如果你的 Codex CLI 开了沙箱模式，脚本可能因为没有文件权限而跑不起来。报错通常会是一串 Node.js 的EACCES或EPERM。

解决方案有两个：一是在命令文件 front-matter 里给该命令指定permission-mode: bypassPermissions（只建议测试环境使用）；二是给沙箱配置加白名单，允许它读取项目目录和临时目录。我更推荐后者，因为本身跑代码生成就不应该放开所有文件权限，否则 AI 改到你系统配置文件你都不知道。

5.3 上下文超限与输出截断

长流程容易出现问题：分析结果太大，塞不进模型上下文窗口，导致/plan生成的计划质量暴跌，甚至直接截断。我自己遇到过/analyze扫描一个大型微服务仓库时，输出上下文超出窗口，后面的/plan只能看到一半的分析结果，计划做得一塌糊涂。

解决思路是“缩小边界”。/analyze命令通常支持指定目录范围，比如/analyze ./order-module，只分析订单模块。还可以在配置里关掉不必要的扫描深度，比如不分析测试目录、不读取构建日志。这本质上是控制信息量，让模型在有限的上下文里聚焦最重要的问题。

5.4 常见问题速查表

5.5 安全与 AGENTS.md 配置

最后必须聊安全。AI 编码工具权限越大，越要注意别让它越权。我见过有人为了让 Codex 干活顺畅，直接给它bypassPermissions，结果它顺手改了全局 npm 配置。这种事一旦发生，排查成本极高。

我的安全底线是：代码改动只允许发生在项目仓库内；读取操作可以放宽到项目依赖目录；写操作严格限制在工作区；凡是涉及密钥、配置中心、生产环境的路径，一律在AGENTS.md里明确禁止读取和修改。另外建议开启 Codex 的审计日志，每次 AI 执行过的命令都有记录，出问题能从日志里还原全过程。这不算麻烦，是责任问题。

还有一个容易被忽视的点：superpowers 的命令模板是用 Markdown 写的，但 Markdown 本身能嵌入命令。安装第三方命令文件之前，先打开看看里面有没有exec这种执行标记，确认没有恶意行为再投入使用。这个道理跟检查开源代码一样，环境安全永远大于效率。

我从这个项目里最大的收获，不是“能用 AI 写更多代码”，而是“AI 开始按流程做事了”。它不再是那个给一句话就冲出去乱撞的毛头小子，而是会先问清楚边界、列好计划、做完自查的同事。如果你手里也有一堆 Codex 用得不得劲的项目，我建议先花一下午把 superpowers 装上，拿一个小任务完整跑一遍流程。等你看完/plan生成的步骤清单，大概率会和我一样，把原生对话式写代码的方式彻底丢进回收站。