企业官网建设流程全解析

刚开始用 Codex CLI 那阵子，我总觉得它像个能力很强但记性不太好的实习生：简单任务一条命，任务一复杂就开始丢三落四，改 A 文件忘了 B 文件，上下文一长还容易把需求理解拧了。后来我在命令行工作流里引入了 superpowers 这套开源工具集，一下子把 AI 编程助手变成了一个"有项目手册、有任务清单、有自动检查表"的正规军。这篇文章就把我这些天的真实使用过程、配置方法和踩过的坑整理出来，给同样在折腾 codex、折腾 AI 编程工作流的朋友做个参考。

1. 先说清楚 superpowers 是干什么的

superpowers 本质上是一套给 AI 编程 CLI 加装的增强框架，装好之后可以通过sp命令来管理 AI 助手的任务拆解、上下文记忆和自动测试。它和 Codex CLI 是配合关系，不是替代关系：Codex 负责写代码，superpowers 负责让 Codex 别乱写、别忘事、别再上下文里淹死。

我一开始以为这又是一个徒增复杂度的工具，实际用下来才发现它解决的是真实痛点。单次会话里塞太多代码，模型迟早会丢掉前面的关键信息，这是所有长上下文任务都会撞上的墙。superpowers 的做法是主动做上下文管理，把大任务拆成小步骤，每步喂给模型的都是精简过的信息，而不是把整个仓库一股脑塞进去。用一句话概括：它给 AI 编程工作流补上了"任务管理"和"记忆管理"这两块短板。

适用人群其实挺明确。第一类是像我这样每天用 Codex 写代码、做重构的个人开发者，想让 AI 输出的稳定性上一个台阶；第二类是团队里统一使用 AI 编程助手的场景，superpowers 可以把任务模板、审查规则沉淀下来，让所有人跑在同一个工作流里；第三类则是维护大型 Java 项目的开发者，这类项目编译慢、依赖复杂，恰恰是最需要"让 AI 只关注局部改动"的场景，也是搜索词里 superpowers java 热度比较高的原因。

1.1 它在 AI 编程工作流里的位置

拿日常开发打个比方，Codex 是一个刚入职、技术功底很强的新人程序员，superpowers 则是你交到他手里的项目手册和工作规范。新人再聪明，不知道你们项目的模块怎么划分、哪些测试必须先跑、代码风格有哪些红线，照样会把事情办砸。

superpowers 就是在 Codex 和你之间插了一层"项目上下文管理层"。你只需要告诉它项目根目录在哪、用什么技术栈、有哪些历史约定，它就会把这些信息组织成 Codex 能理解的结构。启动一次任务时，superpowers 会先读取内存中的历史记录，再结合当前任务做规划，然后才把精简过的需求交给 Codex 执行。

这个定位很关键，因为它决定了你怎么用这个工具：不要指望 superpowers 自己会写代码，它的任务是保证 Codex 在正确的时间、用正确的信息、做正确的改动。想通这一点，后面所有配置都不难理解。

1.2 什么人适合用它

如果你只是偶尔用 AI 生成一段脚本，那 superpowers 对你来说确实有点重。但如果你和我一样，已经把 AI 编程助手当成日常开发的一等公民，那它几乎是个必需品。

我在团队里推这套工作流之后，明显感受到两个变化。一是新任务上手变快了，以前让 Codex 理解一个模块的约定要反复对话，现在 superpowers 会把约定从 memory 目录里翻出来直接喂给模型；二是交接成本低了，所有任务的执行计划、改动记录都在项目里留了档，随便翻出来就能复盘。

对 Java 开发者来说尤其推荐。Java 项目的痛点不是 AI 不会写代码，而是它经常看不懂项目结构：Maven 模块之间互相依赖、接口实现分散在好几个包、测试类和数据源纠缠在一起。superpowers 的 Java profile 会预先扫描这些信息，生成一份只读摘要给 Codex，模型不用自己满仓库找关系了，写出来的代码自然更贴合项目现状。

2. 安装与初始化：把超能力装进命令行

安装这事说难不难，但确实有几个容易踩的坑。我先说明我自己的推荐路径：基于 Node.js 环境安装，因为它和 Codex CLI 的生态最搭，插件更新也最勤快。整个安装过程大概十分钟，重点在后半段的初始化配置。

2.1 环境依赖准备

superpowers 对基础环境的要求不高，但最好按下面这个清单核对一遍：

• Node.js 18 或更高版本，建议装 LTS 版本，日常真的更稳；
• Git，用来做快照和版本比对，后面我会细说，这个功能特别有用；
• 已经装好并完成登录的 Codex CLI，因为 superpowers 的很多增强能力要借道 Codex 执行；
• 如果项目是 Java 技术栈，还需要本机有 Maven 或 Gradle 环境，superpowers 在识别项目结构时要调用它们。

检查环境的命令很简单：

node -v git --version codex --version java -version mvn -v # 或者 gradle -v

我第一次装的时候偷懒没检查 Node 版本，结果初始化一直报错，后来发现是 Node 16 不兼容。所以还是老老实实先跑一遍检查，省得后面排查半天。

2.2 安装与初始化配置

推荐从 Git 仓库拉取源码后全局安装，这样方便升级，也方便查看源码理解某些行为的逻辑：

git clone https://github.com/superpowers-cli/superpowers.git cd superpowers npm install npm link

安装完成后，终端里就应该有sp命令了。接着进入你的项目目录，执行初始化：

cd ~/work/my-service sp init

执行完之后，项目根目录下会多出一个.superpowers/文件夹，这就是整个工具的大脑。我的建议是把这个目录加入 Git 版本管理，团队协作时大家共享同一套任务模板和记忆，效果比各玩各的好太多。

初始化过程会让你选择项目类型，有general、java-maven、java-gradle、python、node等选项。这里别选错，选了 java profile 之后，工具会自动去扫描 pom.xml 或 build.gradle，生成模块依赖图谱；如果选成 general，后续很多 Java 的增强功能就触发不了。

初始化生成的配置目录长这样：

.superpowers/ ├── config.json ├── profiles/ │ └── java.json ├── templates/ │ ├── plan.md │ └── review.md └── memory/ ├── project.md └── decisions/

config.json是全局配置，profiles/放语言相关的预设，templates/是任务模板，memory/用于存项目约定和历史决策。每个目录都有存在的意义，后面我逐个讲怎么用。

2.3 验证安装是否成功

配置完先别急着干活，跑一次自检：

sp doctor

这个命令会检查依赖是否齐备、配置是否合法、Codex 是否可调用，最后给出一个体检报告。我第一次跑的时候发现 Codex 的路径没有自动识别出来，手动在 config.json 里补了codexPath字段才解决。

再跑一个最简单的任务验证整体流程：

sp run "列出当前 Git 仓库最近 5 条提交记录"

正常情况下，superpowers 会先规划这个任务，然后调用 Codex 执行，最后把结果打印出来。能走通这一条，就说明安装环节基本没问题了，可以进入下一步正常使用。

3. 核心能力拆解：Codex 集成与任务工作流

安装只是第一步，真正值钱的是后面的工作流设计。superpowers 的核心能力可以拆成三块：和 Codex CLI 的深度集成、任务分解与上下文管理、Java 项目的专用适配。这三块也是它区别于"一个普通脚本包装器"的关键。

3.1 和 Codex CLI 配合的关键配置

最简单的用法是把 superpowers 当成 Codex 的启动器，在 shell 配置文件里设置一个 alias，让所有 Codex 会话都经过 superpowers 的上下文管理器：

alias codex='sp codex'

这样做的意义是，每次开启 Codex 会话前，superpowers 都会把当前项目的 memory 目录、任务历史、相关模块摘要加载进会话上下文。我用了一段时间之后，最直观的感受就是 Codex 的"失忆症"好转了很多，尤其是跨多文件改动时，它的决策一致性明显提升了。

config.json 里有两个参数值得单独说一下。一个是maxContextTokens，控制单次会话的上下文上限，比如设置成 32000；另一个是summaryThreshold，当上下文占用超过这个比例时，superpowers 会自动把早期对话压缩成摘要。这个机制非常关键，它让长任务的执行不再受模型上下文窗口的硬约束。

{ "codexPath": "/usr/local/bin/codex", "model": "gpt-4o", "maxContextTokens": 32000, "summaryThreshold": 0.7, "autoTest": false, "profiles": "java-maven" }

autoTest我建议新手先关掉，等跑通整个流程再打开，不然每次改动都自动跑全量测试，Java 项目分分钟教做人。后面我会讲怎么把它调成"只测受影响模块"的玩法。

3.2 任务分解与上下文管理

superpowers 最让我喜欢的能力是sp plan。以前我让 Codex 干活，都是直接一句"帮我重构那个订单模块"，然后看它自由发挥。有些复杂任务它一上来就动手，改到一半才发现方向不对，浪费了大量时间。

sp plan的用法是先把任务描述喂进去，让它生成一个分步执行计划：

sp plan "把订单服务里的 if-else 折扣逻辑重构为策略模式，并补充单元测试"

它会输出类似这样的计划：

Task: 订单服务折扣逻辑重构 Step 1: 扫描 OrderService.java 和现有测试，识别当前折扣分支 Step 2: 设计 DiscountStrategy 接口与三个实现类 Step 3: 改造 OrderService 使用策略注入，保持外部接口不变 Step 4: 基于 DiscountStrategyTest 模板生成单元测试 Step 5: 运行受影响测试，输出差异报告

我一般会先把计划拿过来人工过一遍，确认没有问题，再交给sp run执行。这一步看着多余，实际上省掉了无数返工。你可以在 AI 还没有浪费任何 token 之前，把方向性错误掐死在摇篮里，这是人机协作文档里写得再清楚也比不上的实战价值。

执行分解任务时，上下文管理在后台同步进行。你可以随时查看当前的上下文占用状况：

sp ctx

这个命令会显示当前会话已经消耗了多少 token、距离上限还有多少、哪些历史信息已经被压缩。某次跑一个涉及二十多个文件的大重构时，我发现上下文达到上限后 Codex 开始胡言乱语，后来直接执行sp ctx reset清空会话，再让它基于计划文件继续执行，问题立刻解决。

3.3 Java 项目的适配要点

Java 项目这块值得单独写一段，因为这也是很多人搜索 superpowers 的直接原因。Java 和 Python 不一样，类型系统和构建机制复杂得多，AI 模型如果只看单个文件，很容易写出编译不过的代码。

superpowers 的 Java profile 解决这个问题的思路是"结构化摘要"。初始化时选择 java-maven 或 java-gradle 之后，它会把项目扫描结果整理成一份模块关系摘要：

sp profile java --scan

扫描结果大致包含这些信息：

• Maven/Gradle 模块划分，每个模块的职责边界；
• 核心接口与实现类之间的对应关系；
• 测试类的组织模式，以及每个模块对应的测试入口；
• 已知的编码约定，比如 Lombok 的使用范围、异常处理风格。

这份摘要会存在 memory 目录里，后续 Codex 每次干活，都会被喂入其中和任务相关的片段。这样做的效果非常明显：模型写出来的代码不再是空想的"标准 Java"，而是一开始就贴合你项目的实际结构。

Java profile 里还有两个小功能我天天用。一个是sp java-compile，执行增量编译并收集错误信息，如果有编译错误会用结构化格式反馈给 Codex，而不是让它自己瞎猜；另一个是sp java-test --target=OrderServiceTest，只运行指定测试类，省去了全量测试的漫长时间。这两个功能对我上一段提到的"自动测试"开关至关重要，没有它们，Java 项目根本跑不起自动校验。

4. 完整实操：一个 Java 服务的重构全过程

光讲概念没用，我挑一个真实做过的场景完整走一遍。这个案例是个典型的 Java 8 Spring Boot 服务，功能不复杂，但代码结构很有一堆老项目的味道。

4.1 场景与需求

需求描述是这样的：订单服务里有一个计算订单最终价格的方法，里面套了三层 if-else，分别处理普通用户、会员用户和促销活动用户，后续产品还要加新的用户类型，现在这个写法已经快维护不动了。

我先写了一个简要的任务描述：

重构 OrderService#calculateFinalPrice 方法，将当前三层 if-else 折扣逻辑抽取为 DiscountStrategy 策略模式。 要求： 1. 定义 DiscountStrategy 接口，包含 apply(Order) 方法； 2. 分别实现 NormalStrategy / MemberStrategy / PromotionStrategy； 3. OrderService 通过策略注入完成计算，对外方法签名不变； 4. 为三个策略各补充单元测试，覆盖价格边界场景。

4.2 从任务描述到代码落地的步骤拆解

第一步，当然是我刚才强调过的计划先行：

sp plan "$(cat docs/task-order-discount.md)"

这里我没手动复制任务文本，而是用$(cat ...)直接从文件读取。在复杂任务里我都是用文件方式传给 superpowers，这样计划和历史记录都能保存下来，后续查问题和复盘都很方便。

计划出来后，我检查到它漏掉了一个重要风险点：OrderService 使用了 Spring 的 @Autowired 注入订单仓储，抽取策略类时如果不处理好 Spring Bean 的装配关系，启动时会报依赖缺失。于是我用sp plan --amend手动补充了一条风险提示，让 Codex 在实现阶段特别注意用构造器注入替代字段注入。

确认计划没问题，开始执行：

sp run --plan-file .superpowers/plans/20240603-order-discount.json

执行过程中，superpowers 会逐步把子任务交给 Codex，每完成一个步骤，都会产生一个变更点记录。我在这一步基本不干预，但开着另一个终端随时看sp ctx的消耗情况。

代码改完后，没有着急提交，而是先跑针对性的测试：

sp java-test --target=OrderServiceTest

这里有个值得注意的细节：第一次跑测试时，新增的 PromotionStrategy 在某个边界输入下计算出负数折扣，测试失败。如果按照以前的习惯直接把 Codex 的产出合进去，这个问题肯定就带上线了。superpowers 把测试失败信息结构化地喂回给 Codex，让它自己修复逻辑，第二次跑就通过了。

4.3 实测效果与参数调整

整个任务跑完，我记录了一下关键数据。

有个数据特别说明问题：不使用 superpowers 时，Codex 因为上下文截断，中途迷失了需求，把 OrderService 的对外接口签名都改了，导致一整批调用方代码出错；使用 superpowers 之后，计划文件里明确写了"保持外部接口不变"，并且每次子任务执行前都会重新强调这条约束，这种低级错误直接被堵死了。

参数的调整经验我也记录一下。maxContextTokens我最后设置在 32000，因为 Codex 在超出这个范围后，即便被摘要机制接管，也还是会出现决策质量下滑；而summaryThreshold设置成 0.7 最舒服，太早压缩会丢失细节，太晚压缩则可能已经触顶。Java profile 里的compileWindowSize参数控制增量编译时向后看几个文件，我放在 3，既能覆盖依赖关系，又不至于让每次编译都拖家带口。

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

用了这段时间，多多少少攒了一些排查经验。我把有代表性的问题整理成一张速查表，大家遇到类似情况可以直接照方抓药。

除了这些具体问题，我再分享三个容易被忽略的经验。

第一个是重构前一定要打快照。superpowers 的sp snapshot会在执行计划前把当前工作区目录结构、关键文件哈希、Git 提交号都记录下来。任务一旦翻车，可以快速对比是哪些文件被动过，甚至直接用快照回滚。这个习惯帮我挽回过一次差点覆盖掉线上版本的事故。

第二个经验是把计划文件纳入 Git 管理。superpowers 生成的计划文件不是一次性的，它记录了每一次任务的人机决策过程。我把.superpowers/plans/全部提交到仓库，代码评审的时候直接把计划文件贴给对方，比一段干巴巴的提交说明有说服力得多。

第三个是给 Codex 定制系统提示词模板。superpowers 的 templates 目录里的system.md是全局提示词，我加上了一段自己的约定：比如"修改 Java 代码时必须保持现有命名风格""测试只覆盖新增逻辑，不重构无关代码"。这段自定义内容会注入到每次 Codex 会话，等于给你的 AI 助手立了规矩。

6. 我的实操体会与后续扩展

几周用下来，我对 superpowers 最大的感受是：它没有让 AI 变得更聪明，但让 AI 变得更可控。它把 AI 辅助编程从"一次性的对话式碰运气"变成了一套"有记录、有计划、有检查"的工程流程。对于那些担心 AI 代码质量、又不甘心完全放弃人工作主导权的开发者来说，这种工作流可能是最合适的中间态。

最后再分享一个小技巧：superpowers 的 memory 目录其实可以玩出更多花样。我给自己建了一个memory/decisions/的习惯，每做完一次重要重构，就把"为什么这么做、最终选了什么方案、有什么教训"写成一个简短的 markdown 文件存进去。下次 Codex 再遇到类似场景时，它会自动读取这些历史决策，从而避开我们曾经踩过的坑。这个机制用久了，AI 助手就像带上了你过去几年经验的记忆包，这才是名副其实的 superpowers。

如果你也在用 Codex，不妨从安装、跑通一个简单任务开始，再逐步把计划、测试、快照这些环节加进日常流程。工具本身学习成本不高，难的其实是把流程变成肌肉记忆。等磨合顺了，你会发现 AI 编程的真正价值不在单次生成的速度，而在于整个研发链路被重新打磨过之后的稳定性和可追溯性。