企业官网建设流程全解析

如果你最近在折腾 Codex，应该也遇到过这种情况：单文件小任务它处理得又快又稳，可一旦任务跨三五个文件、涉及既有业务逻辑，它就开始“自由发挥”——改错类名、改完不跑测试、问它为什么这么改，它还能一本正经给出个错误解释。我一开始以为是模型能力不够，试来试去才发现，问题多半出在工作流上。后来我把社区里流行的 superpowers 引入 Codex 日常使用，算是真正解决了这个问题。

别误会，这不是什么超级英雄题材的 Mod，而是开发者圈子里给 AI 编码代理准备的一套“能力增强方案”。它不换模型、不调 API，靠的是流程、提示词和上下文纪律，把散漫的编程代理变成“先计划、再执行、勤验证”的靠谱搭档。这篇文章我会把整个使用过程写出来，包括安装配置、核心机制拆解、Java 项目实战，以及我用了一个多月踩出来的坑。

1. 为什么不升级模型，我先给 Codex 装了一套 superpowers

1.1 裸 Codex 的最大短板不是聪明，而是“记性”和“惯性”

Codex 本身的水准并不低，单看代码生成质量，在同类工具里算第一梯队。但实际接到中型项目里，它的表现会迅速下滑，典型症状有三个。

第一个是“只见树木不见森林”。让它改一个模块的接口，它会盯着当前文件猛改，完全忘了这个接口在别处还有三个调用方。改完之后调用方编译失败，它一脸无辜地反问：“我只改了接口文件呀，别的地方报错不是我造成的吧？”

第二个是“改完不验证”。它给你输出一段代码，你问它跑过测试没有，它会说“逻辑上应该没问题”。可在真正的工程里，“应该没问题”等于有问题。裸 Codex 默认不主动执行测试，也不主动编译，这是流程缺失，不是能力缺失。

第三个是“跨会话失忆”。你上午让它梳理了项目结构，下午新开一个对话让它继续改，它又从头开始看代码，你上午反复叮嘱的“这个模块不要动”它已经完全忘了。

这些问题其实都能归到一句话：编码代理缺少一套结构化的“操作手册”。它能理解自然语言，但它不知道你希望它按什么步骤工作。superpowers 就是为了补上这一层。

1.2 superpowers 到底干了一件什么事

我理解的 superpowers，本质是一层“方法论配置层”。它通过几个机制来约束编码代理的行为：

• 项目规则文件（比如 AGENTS.md / WORKSPACE.md），里面写明项目结构、代码风格、命令规范、禁区事项；
• 分阶段工作流，把任务拆成“计划阶段”和“执行阶段”，避免 AI 跳过确认直接动手；
• 落地在磁盘上的持续上下文文件，把当前进度、改动记录、下一步计划写下来，跨会话也能接上；
• 验证闭环，每次改动之后强制要求跑编译、跑测试，并把结果写回上下文。

换句话说，它给一个聪明但莽撞的新员工发了一本《团队操作手册》，告诉它：开工前先读规则，改动前列计划，改完先跑测试，出错先看日志再动手。

这听起来像是一堆提示词，但实际用起来，差别非常大。同样的 Codex 模型，加载了 superpowers 之后，代码改动路径明显更稳，中途返工次数大幅减少。我经常开玩笑说，这不是给 Codex 加超能力，是给它装了个“项目管理器”。

2. superpowers 安装与启用：最容易卡住的三个环节

2.1 环境准备

先说我本机的情况：macOS，Node.js 18 LTS，git 可用，Codex CLI 已经完成登录并且能正常跑通“写一个 hello world”级别的基础任务。

安装 superpowers 之前，我建议你先确认这几个环境项，别装到一半才发现前置条件不满足：

安装本身不复杂。我用的是从 GitHub 拉取源码到本地、再跑安装脚本的方式，过程大致是：

git clone <superpowers 的仓库地址> ~/.superpowers cd ~/.superpowers npm install

具体仓库地址我建议你直接去 GitHub 搜索 codex-superpowers 选一个 star 多、更新频率高的版本。这类项目迭代很快，不同 fork 之间的差别也不小，选的时候重点看两条：一是是否支持你正在用的 Codex 版本，二是 README 里有没有写明配置文件的结构。我最早选了一个很久没更新的版本，装上之后规则文件一直加载不进去，换了新的 fork 才正常。

2.2 让 Codex 每次会话都自动加载它

这一步是最容易出问题的。superpowers 装好了不代表 Codex 会用，关键是要让它在你每次启动会话时自动把规则文件读进上下文。

我的做法是分三步：

1. 把 superpowers 里默认的 AGENTS.md 复制到项目根目录，按自己的项目情况改一遍；
2. 在 Codex 的配置里指定项目启动时要读取这个 AGENTS.md 文件，或者在项目根目录保留一个稳定的固定路径，让 Codex 默认就能发现它；
3. 如果项目里已经有多个规范文件，建议用 imports 的方式把 superpowers 的工作流说明引入，而不是把上万字的规则直接堆进 AGENTS.md。

我见过不少人在这一步失败，原因很简单：AGENTS.md 写了一大堆，但 Codex 没有在每次会话启动时主动加载它，规则根本没进来，superpowers 形同虚设。验证方法也很简单，新开一个对话，直接问 Codex：“请告诉我当前项目的 AGENTS.md 里要求的操作流程是什么。”如果能准确复述出“先分析、列计划、确认后再执行”，说明加载成功。

2.3 离线也能先看说明书，别急着“一键全自动”

刚开始用的时候，我一度想把所有流程都自动化，让 Codex 自己读规则、自己定计划、自己执行、自己验证，一站式跑完。后来发现这样反而容易失控。

更稳妥的用法是先手动跑一轮：你自己手动读一遍 AGENTS.md，手动触发一次“计划生成”，看看输出是否符合预期，再让它进入执行阶段。这相当于先走一遍流程，确认配置没问题，后面再逐步放开自动化。

尤其是涉及 Java 项目的 Maven 构建、文件路径调整这种有副作用的操作，前期手动确认能减少很多意外。

3. 核心机制拆解：它到底在后台做了什么

3.1 分阶段工作流：先计划，后执行

superpowers 最核心的机制，是把一次任务拆成两个阶段。

第一个阶段是计划阶段。编码代理只做分析：读项目结构、理解需求、列出改动点清单、评估影响范围，然后以一份计划的形式输出给用户。这个阶段不写任何实际代码。

第二个阶段是执行阶段。用户确认计划之后，它才按计划逐项修改，并且每一处改动都对应到计划的某一条，避免“顺手多改”。

我用生活化的方式理解这件事：你让一个外卖员去取餐，如果没有“先报路线再出发”的机制，他可能自己规划了一条绕远路，你到家一看饭都凉了。有了计划阶段，他先把路线给你看一遍，你说“不对，走东门更快”，他再出发。整个过程可纠正、可干预。

实际用下来，这个机制最大的好处不是“让 Codex 更听话”，而是让作为人类的我能及时发现它的理解偏差。很多时候我不确认计划，根本不知道 Codex 把需求理解成了什么样。确认计划这个动作，等于加了一道安全闸门。

3.2 持续上下文记录：把“记忆”写进文件

superpowers 另一个让我印象深刻的设计，是把状态写进磁盘。

它会在项目里维护一份类似 PROGRESS.md 的文件，里面记录：

• 当前任务是什么；
• 已经完成了哪些步骤；
• 改动了哪些文件；
• 遇到过什么坑；
• 下一步计划是什么。

这份文件最大的价值体现在跨会话续接。以前我用裸 Codex，上午的对话关了，下午新开一个会话讲“继续”，它基本要从头再来。现在有了 PROGRESS.md，新会话一开始先读它，几句话就能恢复到上午的状态。

我建议你把这份文件纳入 git 管理。好处是每次进度变化都有 commit 记录，万一 AI 改乱了，可以快速回退到上一个进度点。坏处是 commit 会变多，但只要项目是你个人主导，这个成本完全可以接受。

3.3 验证闭环：改完必须证明“能用”

superpowers 的流程里，执行阶段之后还有一个验证阶段。它要求编码代理运行相关测试或至少让项目编译通过，然后把验证结果写回上下文。

这一点我特别看重。因为裸 Codex 非常容易陷入“代码生成出来就觉得完工了”的误区，它不会主动跑测试，也不会主动编译。superpowers 把这个动作固化成流程：改完代码之后，下一步就是跑测试；测试失败就根据日志修，修完再跑。

这里有一个执行细节：验证命令的范围不要一上来就全量跑。后端项目尤其明显，一个中型 Spring Boot 项目全量跑测试可能要几分钟，如果 AI 每次小改动都全量跑一次，效率会低到让人崩溃。正确的做法是在 AGENTS.md 里限定“优先运行与改动模块相关的测试类”，只有最后收尾时才做全量构建。

4. Java 项目实战：让 superpowers 帮我加一个接口

4.1 任务背景

为了让这套东西不那么抽象，我拿一个真实场景演示。

项目是一个 Maven 管理的 Spring Boot 服务，包名结构大致是：

com.example.user ├── controller/UserController.java ├── service/UserService.java ├── mapper/UserMapper.java └── entity/User.java

需求是：新增一个GET /api/users/{id}接口，返回用户基本信息，并且要求补充单元测试，接口风格要跟现有代码保持一致。

如果是在裸 Codex 下直接下发这个需求，它大概率会直接生成一堆代码，然后你可能要花时间检查它有没有用对现有的 DTO、有没有遵循现有的统一返回结构。这次我特意改成 superpowers 流程来做。

4.2 我给 Codex 的指令

我在 Codex 对话里输入的内容是这样：

请使用 superpowers 流程处理这个需求：新增 GET /api/users/{id} 接口，查询用户基本信息。要求先进入计划阶段，分析项目结构、现有接口风格、数据库访问方式，并输出改动计划。在我确认计划之前，不要修改任何代码文件。

这句话看起来平平无奇，但背后有一个关键点：我明确指定了“先进入计划阶段”，并且给出了计划阶段需要分析的具体内容。这样 Codex 不会被需求里的技术细节带偏，而是先去做信息收集。

4.3 完整过程记录

第一阶段，Codex 输出了如下计划摘要：

• 分析 UserController 现有接口的返回值封装，确认是否使用统一 Result 结构；
• 检查 UserService 是否已有按 id 查询的方法，避免重复实现；
• 检查 UserMapper 及对应 XML，确认 SQL 写法；
• 新增 UserController.getUserById 方法；
• 新增 UserService 对应方法，若已有则复用；
• 在 UserMapper 中补充 selectById 方法或确认已有方法可用；
• 编写 Controller 层的单元测试，mock Service 层。

我确认计划后，它开始执行。每一步改动我都能从 PROGRESS.md 里看到记录，比如“已确认 Result 结构为 ApiResponse ，新增 UserController 方法时使用了该返回类型”。这个反馈非常重要，说明它读取了现有代码风格，而不是自创一套。

执行过程中还出现了一个小插曲。Codex 在改 UserMapper 时，发现项目里已经存在一个selectByPrimaryKey方法，它询问我是否可以直接复用，还是新增一个命名更贴切的selectById。这个问题在裸 Codex 场景下它通常不会主动问，而是自作主张选了其中一个。现在它能停下来确认，是因为 AGENTS.md 里写了“涉及复用与新增之间的选择时，先与用户确认”。

验证阶段它执行了下面的命令：

mvn test -Dtest=UserControllerTest

第一次运行测试失败，原因是测试代码里 mock 的方法名和实际 Service 方法名不一致。Codex 读取了测试失败日志，定位到是方法名不匹配，然后修正了测试代码，再次运行直到通过。

整个任务从下发到全部测试通过，大概花了十几分钟。同类需求我用裸 Codex 做过，看起来更快，因为它直接生成代码，但你得额外花时间 review 各种细节。superpowers 模式虽然多了一道“确认计划”的步骤，但整体返工次数明显下降，拉通算下来反而更省时间。

4.4 Java 项目的特别注意事项

Java 项目在 superpowers 流程下有几件容易被忽略的事。

第一，包名与目录结构必须写清楚。Java 的包名和目录路径是强绑定的，如果 AGENTS.md 里没有给出完整的包名规则，AI 很容易新建文件时把包名写错，放在错误目录下。

第二，DTO 与 Entity 的边界要提前固定。很多 Java 项目里 Controller 层不允许直接返回 Entity，要转成 VO/DTO。如果规则文件里不写，AI 很可能把 Entity 直接序列化出去，后面再来一轮大改。

第三，Maven 构建日志很长，验证环节要引导 AI 只看关键部分。我在 AGENTS.md 里专门加了一条：测试失败时，先提取日志里的 “Failures” 和 “Errors” 区域，不要整段输出日志。这一点既节省了上下文空间，也提高了排错效率。

5. 实测一个月，我踩过的几个坑

5.1 上下文文件越攒越大

superpowers 会维护 PROGRESS.md 这类持续上下文文件，用久了文件会变得很大，每次会话都加载它，会白白占掉大量上下文空间。

我最初没在意，在同一个项目里连续跑了三周，PROGRESS.md 涨到接近三百行。Codex 的回答开始变“飘”，经常忘记最近几步的结论，我一度以为是模型出了问题。后来才发现是 PROGRESS.md 太臃肿，早期任务的历史信息挤占了宝贵的上下文。

解决办法很简单：每完成一个大任务，就让 Codex 把 PROGRESS.md 里已经完成的内容归档到 docs/history 里，当前文件只保留本次任务的信息。这相当于给 AI 定期“清理内存”。

5.2 自动执行命令时的权限问题

superpowers 的验证闭环意味着它一定会主动执行命令，比如mvn test、npm test、git diff。大多数情况下这是好事，但你要小心那些有副作用的命令，尤其是git push、npm publish、rm -rf这类。

我遇到过几次差点出事的情况：Codex 在验证完代码后，居然尝试执行git push origin main，想把改动直接推到远端。幸好我在 AGENTS.md 里提前写了“push 操作必须征得用户同意”，它停下来问了我一句，我才及时发现。

建议你在 AGENTS.md 里明确列出“禁止自动执行”的命令清单，并写明原因。这不是对 AI 不信任，而是在给它划定安全边界。

5.3 不同底层模型的执行质量差异很大

superpowers 是一套流程配置，它对不同模型的“约束力”不一样。同样是“计划阶段不要改代码”这条规则，Codex 自己的模型执行得很好；但如果把这一套接到某些小参数模型上，模型表面上答应了，实际还是会一边“分析”一边偷偷改文件。

这不是 superpowers 的问题，而是模型的指令遵循能力差异。所以别指望一套配置在所有模型上通吃。如果你在某个模型下发现流程形同虚设，先检查是不是模型本身的问题，而不是怀疑 superpowers 坏了。

5.4 项目结构越乱，superpowers 越难发挥作用

superpowers 依赖规则文件来约束行为，但如果项目本身没有清晰的模块边界、没有测试、依赖关系混乱，它能做的其实很有限。它再强，也不能把一个完全没有测试的遗留系统变成质量标杆。

所以我的建议是：引入 superpowers 之前，先花点时间把项目的基本结构理清，至少做到有明确的模块目录、有少量关键测试。这样 AI 才能在一个相对健康的地基上干活。

6. 把 superpowers 用成自己的“能力库”：延伸建议

6.1 把流程沉淀到团队规范里

我现在不光自己用 superpowers，还把它的核心流程整理成了团队的编码代理规范。核心就三条：动手前先看规则；改动前先给计划；改完必须给验证结果。这三条不限于 Codex 或 superpowers，换成任何编码代理工具都适用。

团队使用的收益在于统一的交互方式。以前每个人给 AI 下指令的风格千奇百怪，有的人直接丢需求，有的人提供大量上下文，AI 的表现也因此忽好忽坏。规范统一后，至少所有人都会先要求 AI 列出计划，再确认执行。

6.2 与 CI 流程结合，把“验证闭环”做成硬约束

superpowers 在本地要求 AI 改完跑测试，但这个环节其实是“软约束”，AI 有可能跳过。如果你希望强制生效，可以在 CI 里加入对应的检查，比如 push 前必须通过单元测试和构建。这样即使本地 AI 流程跑偏了，CI 也会兜底拦住问题。

我目前的实践是：本地用 superpowers 管工作流，CI 管质量门禁。两者各管一层，AI 负责高效产出，CI 负责最终把关。

6.3 个人项目上的“轻量用法”

如果你觉得完整配置太重，完全可以只借用 superpowers 的核心理念：一个 AGENTS.md 文件 + 一个“计划确认”习惯。我个人的经验是这一步就能解决八成的问题。

不需要把所有技能都堆进规则文件里。AGENTS.md 越精简越好，只写那些“不写就会出问题”的事项。比如测试命令、禁止操作、关键目录结构、风格约束。写得太多，AI 记不住，反而会把重要的部分淹没。

我现在维护了好几个项目的 AGENTS.md，每个都不超过一百行，但每一行都是踩过坑之后沉淀下来的。

6.4 把它当成一个持续迭代的规则库

最后分享一个我实际的体会：superpowers 不是装完就一劳永逸的。它更像一个规则库，得跟着项目情况持续迭代。每踩一个新的坑，就往 AGENTS.md 里补一条规则；每发现某条规则让 AI 变啰嗦了，就把它删掉或简化。

我大概每两周会回头过一遍 AGENTS.md，删掉一些已经不适用或者从未触发过的规则，补上最近踩坑记录里的经验。这个过程本身，比安装 superpowers 更有价值。因为真正让你获得“超能力”的，从来不是某个工具，而是你围绕这个工具建立起来的、适合自己的稳定流程。