企业官网建设流程全解析

说实话，我第一次让 Codex CLI 跑真实业务代码的时候，体验并不好。它像那种特别热心但缺乏章法的实习生：给个模糊任务就冲，写出来的代码能跑，但根本不考虑边界情况，也不关心项目里的既有约定，更不会主动帮你跑测试。直到我接触了社区里那套被叫作 superpowers 的配置实践以后，才真正明白了一件事——AI 编码工具的上限，其实不取决于模型本身，而取决于你喂给它的“工作方法”。

这篇文章不聊虚的，就讲清楚三件事：superpowers 到底是什么、怎么把它装进你的开发环境、以及在一套真实 Java 项目里它是怎么替你把活干利索的。如果你是 Codex、Claude Code 这类 CLI 编码工具的日常用户，或者正在纠结“AI 写代码总是不靠谱”，这篇文章值得你花十分钟看完。

1. superpowers 是什么：不是工具，是 AI 的工作规矩

1.1 一个名字，三层能力

先破除一个可能的误解：superpowers 并不是某个独立的编译器、IDE 或者插件，它是一整套围绕 AI 编码引擎（最典型的是 Codex CLI）建立的“技能与约束体系”。社区里叫它 superpowers，意思很直白——给 AI 编码工具装上超级能力。

这套体系的核心由三层组成：

• 技能（Skills）：把常见任务固化成可复用的操作步骤。比如“写单元测试”“做代码审查”“排查构建失败”，每个技能都是一份结构化指令，告诉 AI 先做什么、再做什么、做到什么标准算完。
• 护栏（Guardrails）：明确规定 AI 不能做什么。比如不能随意删文件、不能跳过测试直接宣布完成、不能在未确认的情况下修改公共接口。
• 工作流（Workflows）：将多个技能编排成一条完整的任务流水线。从需求拆解、技术方案、编码实现到验证收尾，每一步都有检查点。

展开来说，这三层能力解决的是同一个问题：模型本身的泛化能力很强，但它不知道你的项目有什么规矩。superpowers 就是用文本规则，把“你的工程经验”翻译成“模型能执行的协议”。

1.2 为什么默认的 Codex 不够用

我见过很多朋友试完 Codex 的第一反应是“就这？”——它能写 LeetCode 题目，能写 demo，但一进真实仓库就露怯。这不是模型变笨了，而是默认状态下它缺少三个关键输入。

第一，缺少项目上下文。你不知道你的模块划分、命名规律、异常处理风格，模型就更不知道。它只能根据文件名和 import 猜测。

第二，缺少过程约束。默认状态下 AI 倾向于“直接把代码写完交差”，而不是“先列计划，确认边界，再动手”。前者看起来效率高，实际返工率高到吓人。

第三，缺少验收标准。它写完代码不会主动跑mvn test，不会检查有没有破坏既有接口，更不会做自检。它认为“代码写完”就是任务结束，而你认为“测试通过且符合规范”才算结束。

superpowers 这套实践，就是把这三个缺口用文本规则填上。本质上是在模型前面放了一张“工程流程清单”，让它从“单点回答”变成“流程执行”。

1.3 谁适合用、什么项目最受益

从我的使用经验来看，superpowers 不是所有场景的银弹。你可以按下面的维度判断自己是否需要它。

换句话说，如果你维护的是会长期演进的业务代码，不是一次性离线脚本，那这套东西非常值得投入。如果你是那种只管“能跑就行”的探索性项目，按默认方式用反而更轻快。

2. 安装与初始化实操：把 Codex CLI 调教成工程兵

2.1 前置环境准备

要做这套实践，你至少需要准备三样东西：Node.js 或 Rust 工具链（取决于你安装 Codex CLI 的方式）、一个可用的 Codex 账号，以及一个 Git 仓库。

安装 Codex CLI 本身很简单，我试过两种方式。如果你本机已经有 Node 环境，直接用 npm 全局装：

npm install -g @openai/codex codex --version

如果你更习惯脚本安装，官方也提供了 bootstrap 方式：

curl -fsSL https://codex.cli.openai.com/install | sh

装完之后第一次运行codex会引导你登录并选择模型。这里有个细节：建议直接把默认模型设成你账号下可用的最强推理模型，因为 superpowers 的规则解析和编排能力，在更强模型的加持下才会有明显收益。弱模型也能跑，但复杂任务的完成度会明显打折。

2.2 搭建目录结构：规则文件放哪

安装完 CLI 只是第一步，重头戏是搭配置目录。superpowers 风格的典型目录结构长这样：

your-project/ ├── AGENTS.md ├── .codex/ │ ├── config.toml │ └── skills/ │ ├── plan.md │ ├── verify.md │ └── debug.md

我来解释每个文件的角色。

AGENTS.md是 Codex 这类工具约定读取的角色规则文件。你可以把它理解成“给模型看的员工手册”，里面写了它的岗位职责、必须遵守的行为规范、项目里有哪些技术约束。这个文件通常放在仓库根目录，Codex 每次启动时会自动读取，不需要你手动指定。

.codex/config.toml是 Codex CLI 的配置文件，里面可以设置模型参数、环境变量、沙箱行为等。下面给一份我实际在用的最小配置：

model = "gpt-5-codex" project = "your-project" [model_provider] name = "openai" [history] id = "default" [sandbox] enabled = true network = false

需要说明的是，开启沙箱会让 Codex 在受限环境里执行命令，这对防止 AI 乱改系统文件很有用。代价是某些工具链命令（比如需要访问内网 Maven 私服的构建）可能需要额外配置网络白名单，这个我们放到后面“常见问题”里细说。

2.3 技能引导：让 AI 学会“先学规矩再干活”

目录和配置文件搭好后，还有一步关键的“技能引导”。社区里最常见的做法是，在AGENTS.md里写一条启动约定，让 Codex 每次接复杂任务时，先加载.codex/skills/下的技能文件，再开始工作。

我建议在AGENTS.md开头放这样一段话：

# AGENTS.md ## 工作总则 你是一名资深软件工程师。在开始任何复杂任务之前，必须按顺序执行以下步骤： 1. 阅读 `.codex/skills/plan.md`，理解任务拆解与规划要求。 2. 阅读 `.codex/skills/verify.md`，明确任务完成前的验收标准。 3. 搜索仓库中的相关代码，并在回复中列出你计划改动的文件清单。 4. 只有在用户明确确认计划后，才可开始编写代码。 ## 禁止行为 - 未经确认，不得删除或重命名已有文件。 - 不得修改与当前任务无关的模块。 - 不得在未运行测试的情况下声称任务完成。

这段规则本身不复杂，但它改变了 AI 的工作模式。默认情况下，Codex 收到“帮我加个功能”就会直接写代码；而有了这段规则，它必须先展示规划、等待确认，然后再动手。这个“先规划后执行”的动作，是 superpowers 实践中最核心的习惯。

2.4 各技能文件的基础写法

三个技能文件并不需要写得很玄，关键是结构化。我贴一个plan.md的骨架，你可以直接抄下来改成自己的：

# Skill: Plan ## 适用场景 当任务是新增功能、重构既有代码或修复复杂缺陷时，必须使用本技能。 ## 执行步骤 1. 背景确认：阅读任务描述，列出所有涉及的模块与技术点。 2. 代码勘察：用 grep/rg 搜索相关类名、方法名与配置项。 3. 风险评估：标注可能被影响的公共接口、数据库字段、第三方依赖。 4. 计划输出：以列表形式给出改动文件、改动原因与预计风险。 ## 输出格式 计划必须包含以下小节： - 目标 - 涉及文件 - 改动明细 - 风险 - 待确认问题

verify.md则定义“什么叫完成”。我的写法是这样：

# Skill: Verify ## 完成标准 - 相关单元测试已编写并通过。 - 全量测试命令已执行，无新增失败用例。 - 静态检查工具无新增告警（如果项目配置了 lint）。 - 变更文件列表与计划一致，无越界修改。 ## 强制检查清单 - [ ] mvn test 或对应测试命令已执行 - [ ] 代码格式符合项目规范 - [ ] 无 TODO / 调试输出遗留

这里有个现实问题：跑全量测试在大型项目里可能很慢，你可以在规则里补充“若全量测试超过 5 分钟，可运行与改动模块强相关的测试集，并明确说明”。保留灵活性，AI 执行起来反而更靠谱。

3. 核心机制拆解：技能、护栏与工作流到底怎么落地

3.1 Skills 的设计诀窍：写“怎么做”，不要写“是什么”

很多人在写技能文件时会犯一个毛病——把技能写成了概念解释。比如“写单元测试”这个技能，如果你写一堆“单元测试是验证最小代码单元的正确性”，模型根本不知道怎么执行。它需要的是操作步骤。

我在写 Skills 时的诀窍是：每次技能输出都要包含“触发条件—执行步骤—完成标志”三段式。触发条件告诉模型什么时候启用这个技能；执行步骤是可操作的命令和动作；完成标志是一个可验证的结果。

举个实际例子，为“排查测试失败”设计技能：

# Skill: DebugTestFailure ## 触发条件 当用户说“测试挂了”“跑测试报错”“某个用例失败”时，启用本技能。 ## 执行步骤 1. 先定位失败用例的完整类名与方法名。 2. 运行单条用例复现：mvn test -Dtest=类名#方法名 3. 查看日志堆栈中第一个报错位置，定位到具体代码行。 4. 分析是逻辑错误还是环境问题（如数据库连接、端口占用）。 5. 修复后先跑单条用例，再跑所属测试类，最后跑相关性最高的模块测试。 ## 完成标志 - 失败用例通过 - 给出失败根因和执行过的命令列表

这类技能文件写得越多，AI 在你项目里的行为就越像一个熟悉你代码库的老工程师，而不是一个什么都要现场猜的实习生。

3.2 Guardrails 的边界艺术：管住手脚，别管住脑

护栏机制是 superpowers 体系里最容易走极端的部分。有的人把规则写到“AI 每写一行代码都要先解释”的程度，结果任务慢得没法用；有的人又完全不设限，AI 乱删文件。

我的经验是护栏只管三件事：不可逆操作、范围之外的改动、未经验证的完成。

• 不可逆操作：禁止 AI 直接执行rm、git reset --hard、DROP TABLE这类命令。如果确实需要，先输出要执行的命令等待用户批准。
• 范围之外：要求 AI 在计划中列出的文件之外，不得擅自修改任何文件。这条对存量代码仓库尤其重要，能避免它顺手把无关代码格式化得面目全非。
• 未经验证的完成：明确禁止“我认为没问题”“应该能跑”这类无法验证的结论。要宣布完成，必须给出测试命令和输出截图。

把这三条写进AGENTS.md，就能挡住九成以上的失控。

3.3 多步骤工作流的编排：让命令可以一键交付

当 Skills 和 Guardrails 都就位，你就可以把多个技能串成工作流了。这里说的“编排”，本质上就是你在AGENTS.md里描述任务推进的流程顺序。

我用的流程是四步：

1. 规划态：加载 plan.md 技能，产出改动计划，等待用户确认。
2. 执行态：用户确认计划后，按计划改动代码。每完成一个文件，更新进度说明。
3. 验证态：加载 verify.md 技能，执行测试、lint，修复发现的问题。
4. 交付态：输出变更文件清单、测试结果、遗留风险点。

这个流程最妙的地方在于，它没有引入任何重型的项目管理工具，纯靠文本约定就让 AI 进入了“带状态工作”的模式。你随时可以打断它、纠正它，它不会因为中断就丢掉上下文——因为它每一步都在产出结构化状态。

4. 实战复盘：用 superpowers 在 Java 项目里落地一个功能

4.1 任务拆解：让 AI 先回答“怎么干”

光讲机制太抽象，我拿一个真实任务走一遍全流程。假设项目是一个 Spring Boot 订单服务，需求是：“给订单增加一个过期未支付自动关闭功能，要求并发安全、幂等，且不影响原下单接口。”

按规矩来，我在 Codex 里输入任务描述后，它先加载了plan.md，然后给出如下计划：

• 目标：新增订单自动过期关闭能力
• 涉及文件：
  • OrderService（新增关闭方法）
  • OrderMapper（增加按过期条件批量查询的 SQL）
  • OrderStatusEnum（确认已有关闭状态定义）
  • ScheduleConfig（新增定时任务入口）
• 风险：批量更新 SQL 需要考虑行锁与幂等；定时任务并发调度可能导致重复关闭。
• 待确认问题：关闭后是否需要发送通知？定时扫描间隔要求是多少？

这个过程大概花了两分钟。如果放在默认模式下，它可能已经直接开写了，但那样写出来的方案很容易漏掉定时任务幂等这个关键点。现在它先把风险列出来，我可以针对性地补充业务约束，避免后面大改。

4.2 执行与验证：每一步都落在可检查的结果上

确认计划后，我让它进入执行态。它按计划顺序修改了四类文件，并且在每个文件完成后做了简短说明。比如改OrderMapper时，它给出的 SQL 长这样：

SELECT id, order_no, status, created_at FROM t_order WHERE status = 'PENDING_PAYMENT' AND created_at < DATE_SUB(NOW(), INTERVAL 15 MINUTE) LIMIT 500 FOR UPDATE SKIP LOCKED

这里两条关键设计：LIMIT 500控制每批扫描量，避免一次性锁太多行；FOR UPDATE SKIP LOCKED解决多实例并发扫描时重复锁同一批订单的问题。这两个点都是它在 plan 阶段就声明“并发安全”后，自己主动补充的。如果你直接让它“写个任务把超时订单关掉”，大概率不会想到加SKIP LOCKED。

验证态也走得比较顺利。它先执行了相关的单测：

mvn test -Dtest=OrderServiceTest#testCloseExpiredOrder

结果有一个用例失败，原因是模拟订单时间时用了本地时间，而 SQL 用的是数据库时间，导致边界判断差了 8 小时。它定位到问题后，调整了测试里的时间构造方式，然后连跑三遍确认稳定后才宣布完成。

4.3 人工介入的三个检查点

即使流程跑得顺，我也不建议完全放手。整轮实操里我重点审查了三个地方：

• 计划阶段：确认 SQL 是否影响宽表数据量大的场景，索引有没有覆盖查询条件。
• 执行阶段：抽查改动文件，确认没有夹带格式化噪音（比如把其他人写的代码顺手重排了）。
• 验证阶段：除了看测试是否通过，我还跑了一次git diff --stat，确认改动文件数量和计划一致。

这三个点花不了十分钟，但能挡住绝大多数“看起来做完、实际上偏了”的情况。这也是 superpowers 实践强调的事：AI 负责把流程走完，你负责把方向锁死。

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

5.1 高频问题的速查表

我用这套配置跑了几个月，前前后后踩了不少坑。挑几个出现频率最高的整理成表，方便你直接对照。

5.2 两个容易被忽略的坑

第一个坑是规则文件写得太长。我最早把 AGENTS.md 写成了一篇五千字手册，结果发现模型越往后越容易丢失前面的规则。后来精简成按“核心规则—技能索引—项目约定”三段组织，加载效果明显更好。规则不是越多越好，而是高频重要的事项优先放前面。

第二个坑是技能文件与项目的强耦合。我最初把一套 superpowers 配置直接复制到另一个项目里，结果因为技术栈不同（前一个项目是 MyBatis，后一个项目是 JPA），技能里的 SQL 规范完全不适用。现在我会给每个项目单独维护.codex/skills/目录，跨项目只共享最基础的工作流逻辑，不共享技术细节。

6. 如何把你的实践沉淀成团队规范

如果你在自己项目里跑通后，觉得这套思路确实有成效，下一步自然会想到让团队一起用。我建议别直接扔给同事一份“配置文档”，而是先做三件小事。

第一，写一份“AI 辅助开发流程”说明，而不是教大家配文件。把“先计划、后执行、再验证”的工作流讲清楚，让团队先理解为什么要在 AI 面前设一道流程门槛。有了共识，工具配置就是水到渠成的事。

第二，把技能文件当成代码来 review。我见过团队里有人偷偷改掉 AGENTS.md 里的禁止项，理由是“这样 AI 跑得快”。建议把.codex/目录纳入 Git 审查范围，任何规则调整都要经过正常的 PR 流程。这能避免规则被悄悄弱化而无人察觉。

第三，设置一个“人机协作观察期”。刚开始用的时候，可以让 AI 在每条计划里标出“需要人工决策”的点，两周后把这些点归类，你会发现重复出现的类型基本就那几个。再把它们固化成新的技能或护栏，团队的协作质量会一版比一版稳。

我在实际使用中还有一个心得：不要指望配置一次就永远有效。项目在变，工具在变，模型也在变。固定每个季度回头看一下你的技能文件，删掉已经不适用的旧规则，补充这三个月里新踩到的坑。这套东西的价值，不在你第一天装好它的那刻，而在后面每一次跟着项目演化的过程里。