企业官网建设流程全解析

一开始我在本地把 superpowers 装进 Codex CLI，纯粹是因为受不了默认对话模式反复返工。你让 Codex 改一个 Java 方法，它改了实现却忘了按约定跑测试，你提醒一次它才补上，补完之后又把无关的格式动了一堆。与其说这是在协作，不如说是在盯人。后来我把 superpowers 作为一套技能目录挂到 Codex 的技能加载路径里，情况才真正好转：它开始自己拆任务、先写测试、再实现、再重构，像一个有基本职业素养的同事，而不是一个只会接话的聊天窗口。

这篇算是一份个人实测记录，不是官方文档。我会把安装方式、目录规划、Java 项目实战和踩坑排查都写清楚，适合那些已经在用 Codex CLI、想进一步规范 AI 工作流的开发者。如果你主要写 Java，第 4 和第 5 节可以直接当作业指导来用。

1. 先搞清楚：Superpowers 到底给 Codex 加的是什么能力

1.1 一个反直觉的结论：它不是插件，而是“技能包”

很多人一听“给 Codex 装 superpowers”，会下意识以为是个 VSCode 插件、MCP 服务或者 npm 包。我最初也这么想，结果 clone 下来一看，项目里最多的东西是.md文件。

Superpowers 本质上是一套“工作流指令集”。它通过 Markdown 文件定义各种技能，每个技能文件里写清楚了：这个技能在什么场景下触发、执行时先做什么后做什么、中间要输出什么中间产物、最后用什么样的验收标准来判断完成。Codex 作为 Agent 读取这套技能之后，相当于拿到了一本非常细的作业手册。

你可以把它理解成给实习生写的 S.O.P。实习生聪明，反应快，但不知道你公司的代码规范是先写测试再写实现，不知道重构前后要跑完整套用例，不知道改完接口还要顺手更新调用方。S.O.P 把这些流程固化成文本，Agent 每次开工前先读一遍，行为就从“自由发挥”变成了“按流程执行”。

这也是为什么它叫 superpowers：Codex 本身的能力天花板没有变，但使用方式被重新组织之后，产出质量明显提升。注意，它不是黑魔法，它改变的是工作流，不是模型智商。

1.2 为什么 Codex 原生对话做不到这些

直接和 Codex 对话时，它会根据上下文即兴决定下一步。如果用户不提测试，它就默认你不需要测试；如果用户说“帮我重构一下”，它可能只改了一个文件，剩下的地方靠猜。原生对话模式的问题不是模型能力不足，而是缺少“强制步骤”。

Superpowers 解决的是这个“缺少强制步骤”的问题。它的技能文件里会明确要求：开始写业务代码前，必须先写一个失败测试；测试跑红之后才允许进入实现阶段；实现通过后再进入重构阶段。每一步都有明确的输入输出，Codex 不能跳过“跑测试”这个动作直接给你交代码。

我试过在同样一台机器上，用同一个 Codex 模型处理同一个 Java 需求。不开 Superpowers 时，它给出的代码能编译，但单元测试覆盖率只有 30%，而且没有按项目里既有的异常处理风格来写。开了 Superpowers 并加载 TDD 技能后，它先自己建了src/test/java目录，写了完整的边界测试，再实现主类，最后跑mvn test，还主动把 Integer 运算改成了 BigDecimal。

差距就在流程。

1.3 Superpowers 替你跑起来的三条核心工作流

我实际用得最多的是三条工作流。

第一条是 TDD（测试驱动开发）。这个技能会要求 AI 严格按“红灯-绿灯-重构”来走。红灯阶段只写测试不写实现，绿灯阶段用最简代码让测试通过，重构阶段清理重复代码和命名问题。

第二条是任务拆解。面对一个比较大的需求，比如“给现有模块加一个消息队列消费者”，Superpowers 会先把这个需求拆成若干子任务，每个子任务有明确的交付物和验收条件，然后逐个执行。这个能力在长任务里特别重要，因为 Codex 一旦上下文被拉长，很容易忘记最初目标。

第三条是自动代码审查。完成实现后，技能会要求 Codex 自己扮演 reviewer，检查潜在 bug、并发问题、异常处理漏洞和测试盲区。它会输出问题清单，再根据清单逐条修复。

这三条工作流可以单独用，也可以串起来。我通常把三条串在一起使用：先拆任务，再对每个子任务执行 TDD，最后做一轮 review。效果比单独开任何一条都要稳。

2. 安装前必须想明白的目录规划与版本选择

2.1 先检查你的本地环境

在动手装之前，我建议你先跑一遍环境检查。以下三个命令分别确认 Codex CLI、Git 和构建工具的状态：

codex --version git --version mvn --version

如果你用的是 Gradle 项目，就把最后一个换成gradle --version。这里有个容易忽略的点：Codex CLI 本身是通过 npm 安装的，所以 Node.js 环境也需要是正常的，但只在安装阶段用到，运行时不一定依赖 Node。

我遇到过一个情况：Codex 版本太老，技能加载路径还不稳定，导致软链接过去了也读不到。后来升级到新版本才恢复正常。所以如果你之后遇到“明明配置了却不起作用”的怪问题，先怀疑版本，再怀疑配置。

2.2 用户级、项目级、全局：三种安装位置的取舍

安装 Superpowers 之前要决定放哪里。这个决定影响范围很大，我见过不少人直接散装到一堆项目里，最后每个项目都要维护一份，很痛苦。

用户级安装是把技能目录放到~/.codex/skills/下面，所有项目都能用。单个开发者自己用，我推荐这种方式。项目级安装则是放到某个仓库的.codex/skills/或.agents/skills/目录下，会随仓库走，团队提交代码时能一起同步。全局安装是把它当作系统级指令放到 PATH 或公共配置目录里，适合公司内部统一推行的场景，但维护成本最高。

你可以先按一张表来判断：

从我自己的经验看，绝大多数开发者从用户级开始就够了。等你在团队里验证了某条工作流确实有用，再把它下沉到项目级，让每一个克隆仓库的同事都能自动拿到。

2.3 我推荐的目录布局

目录布局不复杂，但有个结构问题值得提前想好：Superpowers 自带的技能是公用的，你自己后加的技能是私有的。如果混在一个目录里，升级 Superpowers 时可能会把自定义内容覆盖掉。

我是这么组织的：

~/.codex/ ├── config.toml ├── AGENTS.md └── skills/ ├── superpowers/ # 官方技能 ├── team/ # 团队私有技能 └── personal/ # 个人私有技能

这样升级 Superpowers 时只需要替换superpowers这一个子目录，team和personal完全不受影响。Codex 加载技能是读取整个skills目录的，所以不同来源之间不会冲突，只要技能命名唯一就行。

3. 挂载 Superpowers 到 Codex CLI：两条实测可行的路线

3.1 路线一：软链接到 Codex 全局技能目录

我先说我自己最常用的方式。它基于用户级安装，好处是升级方便、回滚方便，而且不会把第三方代码散落到项目仓库里。

第一步，把 Superpowers 仓库克隆到一个固定位置：

git clone https://github.com/obra/superpowers.git ~/superpowers

第二步，在 Codex 的技能目录里创建一个软链接：

mkdir -p ~/.codex/skills ln -s ~/superpowers/skills ~/.codex/skills/superpowers

这里有一个细节：链接目标不是~/superpowers本身，而是它内部的skills目录。因为 Codex 期望的是“技能目录下面直接放技能文件”，而不是“技能目录下面再套一层仓库结构”。我第一次犯过这个错误，链接到仓库根目录，结果加载时一个技能都识别不到。

第三步，如果你是新版本 Codex，通常还需要在配置里确认启用了 Agent Skills。在~/.codex/config.toml里加入：

[skills] enabled = true

不同版本的配置字段名可能不一样。最稳妥的办法是运行codex --help查看当前版本是否包含 skills 相关参数。如果没找到，也不用慌，很多版本会在检测到技能目录后自动加载。

3.2 路线二：放进项目级 .agents 目录

如果你的团队成员都会 clone 同一个仓库，项目级安装更合适。Codex 在项目目录下会读取.agents/skills/或者.codex/skills/，具体看版本。你可以直接复制，也可以用子模块引入。

用 git submodule 的方式是：

cd your-project mkdir -p .agents/skills git submodule add https://github.com/obra/superpowers.git .agents/skills/superpowers

然后用一条软链接再处理一层，让技能文件位于.agents/skills/superpowers下面一层。如果直接 clone 到.agents/skills/superpowers，你需要确认这里面直接是 Markdown 技能文件，而不是又包含一个skills子目录。

项目级安装最大的好处是“开箱即用”。新人 clone 仓库之后，Codex 自动就带上了全部技能，不用每个人手动去配。它的代价就是仓库里多了第三方代码，如果你不喜欢 submodule，也可以用脚本在初始化时自动 clone 和软链。

3.3 修改配置与验证加载

配置除了开关 skills，还有一个容易被忽略的文件：AGENTS.md。Codex 在开始任务前会自动读取当前目录和用户目录下的AGENTS.md，你可以用它来声明技能加载规则。

我习惯在用户级~/.codex/AGENTS.md里写这么一段：

# Agent Instructions - 开始任务前，检查 ~/.codex/skills/ 下是否有与任务匹配的技能。 - 如果存在匹配技能，必须按技能文件中的步骤执行，不能跳过任何步骤。 - 涉及测试代码时，优先遵循 TDD 技能的“红灯-绿灯-重构”流程。

这段文本的作用是让 Codex 别偷懒。技能文件是“储备”，AGENTS.md是“启动器”。两者配合，Codex 才会真的去翻技能，而不是你每次手动在对话里要求它读文件。

验证是否加载成功，我提供一个最简单的办法：直接在 Codex 里问他“你当前有哪些可用的技能，请列出技能名称和用途”。如果它正确说出了 Superpowers 里的几项技能，说明加载链路已经通了。如果它一脸茫然，就去查~/.codex/skills/目录结构和配置文件，八成是路径套多了一层。

4. 真刀真枪：在 Java 项目里让 Superpowers 驱动 TDD

4.1 先准备一个不会干扰 AI 的最小 Java 工程

很多人在这一步就栽跟头：工程里有一堆历史遗留代码、多模块依赖、自定义 parent POM，Codex 一启动就被上下文塞满，后面根本跑不起来。

我建议你用一个“最小可复现工程”来验证 Superpowers，而不是直接扔一个大仓库。最小工程要满足三个条件：

• 只有一个模块，构建工具用 Maven 或 Gradle，依赖尽量少
• src/main/java和src/test/java目录结构明确
• 测试框架用 JUnit 5，不要引入 Mockito、MockMvc 这类容易分散注意力的东西

我用一个金额计算器来做实验。需求很简单：支持金额的加法、减法、乘法，且不能出现浮点精度问题。这类需求足够触发一次完整的 TDD 循环，又不会让 AI 花太多时间在业务背景上。

工程目录结构大概是：

money-calc/ ├── pom.xml └── src/ ├── main/java/com/example/money/ │ └── Money.java └── test/java/com/example/money/ └── MoneyTest.java

注意，初始状态只保留 Maven 配置和一个空模块，两个 Java 类都不用写，交给 Codex 来生成。

4.2 用一句话需求触发完整工作流

在 Codex 里输入一句话：

“在这个 Maven 工程里新增一个 Money 类，金额用分存储，支持加、减、乘，要求所有运算不丢精度。请按照 TDD 技能执行。”

如果你已经正确加载了 Superpowers，Codex 的第一步不会是直接创建Money.java，而是先检查测试目录里有没有测试文件。发现没有后，它会先创建MoneyTest.java。这个测试文件会覆盖至少五种情况：

• 金额加法正常进位
• 金额减法出现负数
• 乘法结果四舍五入到分
• 大数相加不溢出
• 字符串转金额时处理非法输入

然后它才创建Money.java的实现类，用long类型的字段保存“分”，而不是用double。实现完成后再跑一次mvn test，确认全部测试通过。

这是不是看着很简单？是的。但注意，在没挂 Superpowers 之前，同一句话进 Codex，它大概率会先给你一个Money类，里面用BigDecimal，然后告诉你“用 BigDecimal 就不会丢精度”。它不会先写测试，也不会验证边界。两种输出的差别就是技能流程带来的。

4.3 我对输出产物的验收标准

让 Codex 干完活之后，我不会只看“测试通过”就收工。我有一套自己的验收清单，针对 Java 项目重点检查以下项目：

• 领域类的核心状态是不是用了原始类型或不可变对象，避免自动拆箱问题
• 金额输入是否在构造函数里做了校验，负数、null、非数字字符串有没有被拦截
• 测试是否覆盖了“边界值”，比如等于 0、正好进位、超过 Long 最大值
• 是否遵循了项目既有的异常设计，比如统一抛出IllegalArgumentException
• 是否在实现阶段引入了不必要的外部库，比如为了一个加法把整个 Guava 拉进来

Superpowers 的 TDD 技能会让 AI 在“红灯”阶段先写失败测试，这本身就保证了大多数边界会被覆盖。但 AI 不会替你决定业务规则，比如“金额是否允许为负数”，这事必须由你在需求里讲清楚。你在对话里说“金额不能为负”，它就会把校验逻辑放进实现里；你不说，它可能就漏掉。

4.4 如果第一步没跑通，先查这四件事

如果你像我一样满怀期待地输入需求，结果 Codex 还是直接生成实现类，完全没走 TDD，先别急着怀疑工具炸了。按顺序排查：

第一，技能是否真的被加载。回到第 3 章最后说的验证方法，问一次“当前可用的技能”。

第二，AGENTS.md是否生效。如果你只配置了技能文件，但没在AGENTS.md里声明“必须按技能执行”，Codex 很可能会忽略它，因为对它来说技能只是“可用参考”，不是“必须流程”。

第三，当前工作目录对不对。如果你从~目录启动 Codex，而不是从项目目录启动，它可能读不到项目级配置，也不会认为这是 Maven 工程。

第四，模型上下文窗口是否被塞满。如果刚才的对话已经很长了，技能文件的加载会被截断，工作流自然就走不完整。新开一个会话，再试一次。

我遇到的绝大多数问题都能靠“新开会话 + 明确让 AI 使用 TDD 技能”解决。

5. Codex + Superpowers 跑 Java 时我踩过的四个坑

5.1 坑一：Maven 还是 Gradle——AI 自己换了构建工具

有一次我在一个 Maven 工程里让 Codex 完成一个模块开发，结果它生成了一堆build.gradle文件，还自作聪明地把目录结构调整成了 Gradle 布局。原因是我在自然语言里提了一句“用你熟悉的构建方式”，它就直接选择了 Gradle。

这很麻烦。因为 CI、IDE、同事的本地环境全是以 Maven 为准，AI 擅自切换构建工具会导致整个分支不可用。

根因是技能文件里只定义了 TDD 流程，并没有限定“当前项目必须识别既有构建配置”。解决办法是在项目内AGENTS.md里写死：

# 构建规范 - 本项目使用 Maven，禁止生成或新增 Gradle 相关文件。 - 所有新代码必须位于 src/main/java 和 src/test/java。 - 构建命令一律使用 mvn，不使用 gradle。

这条规则加进去之后，Codex 不会再自由发挥。类似地，如果你项目里用的是 Kotlin，最好也把语言版本和构建命令写清楚。

5.2 坑二：误删手写测试的问题

挂上 Superpowers 之后，AI 的任务拆解能力变强，但它对“哪些是它生成的、哪些是手写的”并没有可靠判断。某次重构时，它把一批手写测试删掉了，理由是“这些测试覆盖场景与生成的测试重复”。

我回过神之后发现，它其实不是真的想删，而是技能的 review 环节要求它清理“冗余测试”，它把“覆盖逻辑重复”和“直接删除”划了等号。这是 Agent 常见的过度总结。

解决思路有两个。第一，在手写的测试文件顶部加注释，说明该文件是人工维护，AI 只能追加不能删除，例如：

// IMPORTANT: Manually maintained test. Do not delete or rewrite. Only append.

第二，在AGENTS.md里增加一条硬性规则：“任何删除测试文件的操作必须经过用户明确批准，不能自行判断。”这两条加进去之后，我再没遇到过误删。

5.3 坑三：技能文件被带进 git 提交

项目级安装 Superpowers 后，如果你把它放进了.agents/skills/，很容易在提交代码时不小心把整个技能仓库一并提交。我自己有一回发现提交记录里多了几百个 Markdown 文件，全是第三方技能内容，把仓库搞得又臭又大。

这并不是说不能放项目级，而是要在.gitignore里明确排除，或者用 submodule 而不是直接复制文件。如果你想让技能随项目走，我建议用 submodule，并在仓库文档里写清楚如何初始化和更新；如果你不想让技能进仓库，就把它放进用户级目录，项目内只通过AGENTS.md引用。

我最终的选择是：官方 Superpowers 放用户级，团队私有技能放独立私有仓库，项目只保留一份AGENTS.md引用指南。这样仓库干净，升级也灵活。

5.4 坑四：上下文太长导致工作流中断

Superpowers 的工作流步骤不少，每一步都会产生大量输出。Codex 的上下文窗口虽然不小，但在一个超过千行的 Java 工程里，再叠加多轮对话，很容易出现“后半段工作流被截断”的情况。表现是：红灯测试还在，绿灯实现已经结束了，重构步骤直接消失。

我的处理方式很简单：一个任务只做一件事。不要让 Codex 在一个会话里同时完成需求分析、代码生成、测试、重构、文档更新。把任务拆小之后再用 Superpowers 的技能逐个执行。你可以手动拆，也可以让它先执行“任务拆解”技能，给你一份子任务清单，然后你在新会话里逐个发起。

这个习惯我非常推荐。不只解决上下文问题，也让 Codex 每一步的变更都更可控，代码 review 更容易。

6. 从“能用”到“好用”：把 Superpowers 变成团队规范

6.1 把团队规范写进自定义 skill

Superpowers 自带的技能面向通用开发场景，但每个团队都有自己的规矩：数据库访问必须走某个封装类，日志必须带 traceId，接口返回必须包一层 Result。这些规矩如果只靠口头交代，Codex 永远学不会。

你应该做的是写自己的技能文件。放在~/.codex/skills/team/目录下，命名如java-project-standards.md，里面用步骤条形式写清团队规范。比如：

# Java Project Standards 当处理 Java 代码时，必须遵循以下规范： 1. 所有对外接口的返回类型必须是 Result<T>，禁止直接返回裸对象。 2. 日志必须包含 traceId，禁止使用 logger 输出敏感字段。 3. 新增依赖前先检查 pom.xml 中是否已有相同功能依赖。 4. 异常处理统一使用 BizException，禁止在业务代码里吞异常。 5. 单元测试类命名为 XxxTest，所有公开方法必须有覆盖。

写完之后，Codex 每次在这个目录下启动都会自动读取，相当于团队规范被标准化成了 Agent 可以直接执行的指令。这比写在 wiki 里等着被人翻阅有效得多。

6.2 设置可验证的完成标准

Superpowers 的“技能化”思路很好，但 AI 判断“完成”的标准和人类不完全一致。你觉得完成是“测试通过 + 代码走查 + 无新增依赖”，AI 可能觉得“编译通过”就是完成。

在团队内推行 Superpowers 时，我建议把完成标准作为一个独立技能文件固定下来。比如definition-of-done.md，里面写：

# Definition of Done 只有同时满足以下条件，一个子任务才能标记为完成： - 相关单元测试全部通过，且覆盖关键分支。 - 代码符合团队编码规范（参见 java-project-standards）。 - 没有新增未使用的依赖。 - 没有修改与当前任务无关的文件。 - 没有删除或重命名既有测试。

这个文件一旦被 Codex 读取，它的“完成”判断就有了明确边界，不会出现“我觉得写完了”这种模糊状态。我们在团队里加了这条之后，AI 生成代码的返工率降了大约三成。

6.3 多 skill 共存时的优先级

技能文件多了之后，会出现冲突。比如通用 TDD 技能要求“先写失败测试”，团队规范技能要求“所有公开方法必须有测试”，这两者方向一致；但另一个技能要求“禁止使用 Mockito”，而 Codex 生成测试代码时却经常顺手用 Mockito，冲突就来了。

Codex 加载多个技能时，并没有严格的优先级设计。它会把所有可用技能都视作参考，然后根据上下文自行组合。所以我们做了一件简单而有效的事：在AGENTS.md里明确写了“技能加载优先级”。

例如：

# Priority Rules 当多个技能对同一个问题给出不同指导时，优先级从高到低为： 1. definition-of-done 2. java-project-standards 3. superpowers 内置的 TDD 技能 4. 其他通用技能

这一行看起来简单，但能省掉大量来回“掰扯”。Agent 不再随机选择规范，而是有一个明确的冲突裁决顺序。

6.4 团队共享与维护

最后说一句维护的事。Superpowers 这一类技能方案不是“装完就不管了”。技能是文本，文本就需要定期更新。

我们团队的做法是每月抽半天，把最近被 AI 踩过的坑整理成新的技能条目，比如“禁止用 stream 处理大列表”、“生成接口文档时必须同步修改 OpenAPI 文件”。这些条目积累在团队私有技能仓库里，新人直接用，老手也省得反复强调。

如果你一个人开发，也可以做这件事，不用等别人。每次遇到 Codex 在项目里犯的重复性错误，就把它改成一条技能规则，下一次它就不会再犯。这种体验带点“驯养个人助手”的感觉，也正是 Superpowers 真正值钱的地方：它不只是在给 AI 加能力，更像是在帮团队把经验沉淀成一堆高密度的文本资产。

我现在每天开 Codex 之前，都会顺手看一眼技能目录里有没有新增内容。这种习惯说不上多高级，但用了几个月之后，Codex 产出的代码质量明显比之前更稳定，当初那种“盯着它别乱来”的感觉也减轻了。如果你也被默认对话模式里的来回拉扯折磨过，不妨照着这个流程试一次。