企业官网建设流程全解析

最近几周我一直在折腾 Codex CLI，也就是 OpenAI 那个跑在终端里的 AI 编程助手。用了一段时间后，我的感受特别矛盾：它确实能写代码，但如果你直接丢一个大需求过去，它经常给你来一套"自认为很对"的流程——没有拆解、没有检查、没有编译验证，写出来的代码看着像模像样，一跑全是低级错误。

后来同事给我推荐了一个叫superpowers的开源项目，说这东西能直接给 Codex 这类终端 Agent 装上一套"技能系统"，让 AI 先想清楚再动手，干完活还会自己复查。我试了两周，效果非常明显。这篇文章就是把我的安装过程、核心玩法、实际改造 Java 项目的经验，以及踩过的坑一次性整理出来，给准备入手的你做个参考。

如果你已经在用代码类 AI 助手，但觉得"生成代码质量不稳定""每次都要反复纠正细节""团队规范没法落实到 AI 产出里"，那这个项目值得你好好研究一下。

1. superpowers 到底是什么，以及它想解决的问题

1.1 先说背景：Codex CLI 这类工具的尴尬

Codex CLI 是一个命令行编程工具，它会读取你本地仓库的文件，基于自然语言指令生成代码，还能直接执行命令、运行测试、查看报错信息，属于比较典型的"AI Agent"路线。它的能力上限很高，但问题在于：它默认没有一套稳定的工作习惯。

什么叫没有工作习惯？举个我实际遇到过的例子。我让它"给项目里所有的 REST 接口加上统一异常处理"，它直接把一个工具类生成出来了，代码本身没什么问题，但它忘了先看看项目里现在有没有类似的类，结果出现两个功能重叠的ExceptionHandler；它也没跑测试就宣布任务完成，等我手动编译才发现有个类名拼写错误。

这不是 Codex 一家的问题，而是所有 Agent 类工具的共性问题——大模型本身是"自由发挥"型的，给它一个目标，它倾向于直接跳到最终答案，而不愿意做过程管理。superpowers 这个项目，核心就是把**"过程"**这个缺失的部分补回来。

1.2 superpowers 的解决思路：技能包 + 工作流

superpowers 本质上是一个开源框架，它的做法非常像游戏里的"技能树"：把 AI 编程过程中常用的能力，拆成一个个独立的、可复用的Skill（技能包）。每个技能包都是一个包含指令、脚本、参考文档的目录，当 AI 判断当前任务命中某个技能时，就会加载这个技能，按照里面定义的步骤去执行。

举个例子，社区里常见的技能包有这些方向：

• plan-mode：先做需求分析、拆任务，不急着写代码
• test-first：先写测试再写实现
• code-review：写完代码后按检查清单逐项自审
• bug-hunting：通过二分法、日志定位和最小复现来修问题
• refactoring：做代码重构前先画依赖关系、定安全边界

你可能会说，这不就是把一些"提示词"整理好吗？对，也不对。提示词只是一段文本，而 superpowers 里的技能包是一个完整的目录结构，可以包含可执行的脚本、外部参考文档、子技能依赖，甚至能决定 AI 在某个阶段能调用哪些命令。它把"经验"从人脑里搬到了项目的文件系统里，是结构化的，不是靠 AI 运气发挥的。

1.3 它和裸用 Codex 的本质区别

我画了一个对比，能直观看出两者差异：

我在实际使用里感受最深的，是它把 AI 从"答题者"变成了"执行者"。直接问 Codex"帮我把这个模块重构成支持扩展的插件体系"，它可能会给一版方案然后问你行不行；但在 superpowers 的流程里，AI 会先加载设计技能，产出方案评估、影响面分析，再进入实施阶段，最后还有一次自检。这个差距非常大。

1.4 适合什么样的人折腾

我先说清楚，superpowers 不是那种开箱即用的普通软件，它使用过程中需要你具备基础的命令行能力和一点结构化思维。但它也远没有想象中那么难，我判断可以从这个项目里获得价值的人包括：

1. 主力语言是 Java、Python、Go 这类中大型项目开发，AI 写代码容易"只见树木不见森林"，需要一定的过程控制。
2. 已经在用 Codex CLI、Claude Code 这类终端 Agent，但对产出质量不满意，想提升稳定性。
3. 团队里有明确编码规范、提交规范、测试要求，想把这些规范固化成 AI 的行为准则。
4. 对 AI 编程有兴趣，想探索"提示工程"之上形态的开发者，superpowers 的 Skill 机制，其实已经接近"AI 时代的 IDE 插件生态"。

如果你是纯前端切图的日常，或者只是想让 AI 帮你写点一次性脚本，那这个项目带来的收益有限，不一定值得投入时间。

2. 安装与初始化：从零到让 AI 第一次"带技能干活"

2.1 环境准备

我的安装环境是 macOS + Node.js 20，项目要求 Node.js 18 以上，这个应该绝大多数人都满足。另外你需要先把 Codex CLI 装好并完成登录，因为 superpowers 在初始化时会扫描你本机的 Codex 配置，识别它的位置。如果你的核心工具不是 Codex，而是 Claude Code 或者其他 Agent，后面我也会提到怎么迁移思路，但第一步还是建议按它默认支持的 Codex 来体验。

在开始之前，我建议先看一眼自己有没有装好基础命令行工具：

node -v npm -v codex --version codex login

如果你已经能正常在终端里调用codex，并且登录过，那环境就准备好了。国内网络环境访问 OpenAI 的接口需要一些额外配置，这里就不展开了，重点说这个项目本身的安装。

2.2 克隆与安装

我安装的版本是从 GitHub 上直接 clone 下来的。具体的仓库地址不同镜像和版本会有差异，建议你在 GitHub 上搜索 "superpowers codex" 找到官方仓库，留意一下仓库的描述里是否包含 "skills for coding agents" 之类的关键词，避免装错同名项目。

安装流程是这样的：

# 1. 克隆仓库到本地 git clone https://github.com/你的仓库地址/superpowers.git cd superpowers # 2. 安装依赖 npm install # 3. 以非交互方式初始化，生成配置文件 npm run powerup

这里重点说一下powerup这一步。它会做几件事：在你的用户目录下创建.codex相关的配置目录，把 superpowers 默认推荐的技能包模板放进去，同时生成一个用于 Codex 的AGENTS.md文件——这个文件就是告诉 AI"你有哪些技能可用、遇到什么场景应该加载哪个技能"的关键配置文件。

如果你是第一次跑，它可能还会问你要不要自动下载社区推荐的默认技能集，我建议选 Yes，先体验自带技能的效果，后面再删减。我不太建议一开始就完全从零手写技能，那样你既不知道格式，也没有对比基准，后面排错会很痛苦。

2.3 验证安装是否成功

初始化完成后，你可以检查这样几个东西是否到位：

1. ~/.codex/skills/目录下是否出现了多个以技能名命名的文件夹，比如plan-model、code-review-o之类的。如果出现了，说明技能包本体已经就位。
2. Codex 项目目录下是否有AGENTS.md文件，文件里是否列出了可用技能的名单和触发说明。
3. 在任意一个 Git 项目里运行codex，然后输入一句话："请加载 plan 技能，帮我分析一下这个项目的模块结构"——如果它输出的内容里有"任务拆解""阶段划分"而不是直接开始写代码，说明初始化成功了。

我第一次初始化完成后，看到~/.codex/skills下多了一堆技能目录，第一反应是"这不就是个放 Markdown 文件的文件夹吗"。但实际用起来才发现，AI 是真的会去读这些 Markdown 文件，并且严格按照里面的流程执行。不要把技能目录和普通的文档目录混为一谈，它的核心在于文件结构决定了 AI 的思维路径。

2.4 跑通第一个带技能的示例项目

为了快速验证，我做了一个最小实验：新建一个空目录，初始化 Git，然后在里面写了三行AGENTS.md：

# 项目技能说明 当需要新增功能时，使用 plan 技能先输出任务拆解。 所有代码必须通过测试后才能标记完成。

随后我打开 Codex，让它"用 Python 写一个 Todo List 的命令行工具，支持增删改查，数据保存在本地 JSON 文件"。它给出的响应和裸用 Codex 时完全不同：

1. 最开始它没有写代码，而是先给出了"实现方案"，包括文件结构、命令设计、数据存储方式。
2. 然后它自己把任务拆成了创建项目结构 -> 实现数据层 -> 实现命令层 -> 编写测试 -> 手动执行验证五个步骤。
3. 中间每完成一步，它会打印"已完成 XX，下一步执行 YY"。
4. 最后它真的跑了一次python -m pytest，把测试结果贴了出来，才宣布任务完成。

这个初次体验给我留下的印象很深。因为它已经不是"你问我答"的交互模式，而是一个有流程、有验证、有输出记录的完整执行过程。

3. 核心玩法拆解：Skill 技能包的结构与自定义思路

3.1 一个 Skill 到底长什么样

技能包本质是一个目录，以我常用的code-review技能为例，它的目录结构大致是这样的：

code-review/ ├── SKILL.md # 技能主描述文件 ├── scripts/ │ └── extract_diff.py # 可选，辅助脚本 └── references/ ├── checklist.md # 审查清单 └── common_bugs.md # 常见问题参考

SKILL.md是整个技能包的核心，它决定了 AI 会不会加载这个技能、加载后会按什么顺序做哪些事。一个典型的SKILL.md包含两部分内容：

第一部分是 frontmatter 元信息，负责"匹配"：

--- name: code-review description: 在代码提交前或代码合并前执行审查时使用，识别潜在缺陷、安全问题和可维护性风险。 when_to_use: 当用户要求 review 代码、检查 PR、或说"帮我看看这段代码有没有问题" ---

第二部分是正文指令，负责"执行"：

# Code Review 流程 1. 查看变更范围，获取 diff 或改动文件列表。 2. 使用 references/checklist.md 中的清单逐项检查。 3. 对发现的问题按严重程度标记：Critical / Warning / Suggestion。 4. 输出审查报告，包含问题位置、原因说明、修改建议。 5. 禁止直接修改代码，除非用户明确要求。

这份文件和平时给 ChatGPT 用的提示词最大的区别在于，它明确告诉 AI"什么时候该用我、要怎么用、边界在哪里"。我后来把团队里 Java 项目的一些常见规范也写进了references/里，比如"Controller 层不能直接操作 Entity""日志必须带 traceId"，然后让 AI 按这个技能做 code review，效果确实比口头要求省心很多。

3.2 写一个自己的技能包：Java 代码审查实战

很多人看教程看到这里，可能还是不知道"我自己怎么写一个技能"。我拿一个最适合大部分人复刻的java-code-review来演示，整个过程只要十分钟。

先创建目录：

mkdir -p ~/.codex/skills/java-code-review/references

然后写SKILL.md。我的写法参考了官方模板，同时增加了一些自己的细节规则。这里分享一个技巧：不要把 SKILL.md 写得像长篇小说，AI 的上下文窗口是有限的，技能文件越简洁、越结构化，越容易被完整加载。我见过有人往技能里塞了上千行的规范文档，结果 AI 经常漏读后半部分，效果反而大打折扣。

我的SKILL.md精简版如下：

--- name: java-code-review description: 针对 Java 项目代码进行审查，重点检查异常处理、空指针、并发安全和 MyBatis 使用规范。 when_to_use: 当用户要求对 Java 代码进行审查、找 bug、评估代码质量时使用。 --- # Java Code Review 流程 1. 获取待审查代码列表，优先审查 Controller、Service、Mapper 层。 2. 逐项检查以下要点： - 异常处理：是否捕获了过宽的异常？是否吞掉了异常？ - 空指针：方法入参和查询结果是否有判空？Optional 是否使用正确？ - 并发安全：是否有共享可变状态？SimpleDateFormat 是否被多线程共用？ - 资源释放：IO 流、数据库连接是否正确关闭？是否使用 try-with-resources？ 3. 参考 references/checklist.md 中的详细清单逐条对照。 4. 输出报告，按影响程度排序，每条包含文件名、行号、问题描述、修改建议。 5. 修改必须经过用户同意，禁止自行改动代码。

再在references/checklist.md里补充详细清单，比如Controller 层不要直接返回 MyBatis 的 Entity，避免序列化字段暴露、批量插入必须使用 batch 方式而不是 for 循环单条插入、日志必须包含租户 ID 和操作人。这些内容完全来自你们团队的编码规范，每个团队都能沉淀出这么一份清单。

最后，在项目的AGENTS.md里加入这个技能的声明：

当用户提出代码审查相关需求时，默认加载 java-code-review 技能。

我把这套技能用了两个星期，过程中最大的感受是：AI 作为审查者并不是真的在"理解"代码质量，它是在"对照清单逐条找违规点"。所以清单的质量，直接决定了审查质量。如果你的团队规范本身很模糊，建议先自己总结，哪怕一开始只有十条，也比没有强。

3.3 技能的全局配置与项目隔离

superpowers 的技能可以放在两个层级，这一点很重要，很多新手会在这里搞混：

1. 全局级别：放在~/.codex/skills/下，所有项目都能用。
2. 项目级别：放在当前项目的.codex/skills/下，只对当前项目生效。

我建议把所有通用技能放在全局，把和具体业务相关的规范放在项目级。比如java-code-review这种通用技能放全局，而"支付模块必须走统一对账接口"这种业务约束放项目里，避免 A 项目的技能干扰 B 项目。

还有一点需要注意，全局技能太多会导致 AI 在启动时阅读大量技能描述，浪费上下文。我一开始把社区里二三十个技能全部启用了，结果发现 AI 经常在多个技能之间跳跃，甚至出现"既想用重构技能，又想用审查技能，最后哪个都没执行完整"的情况。后来我只保留四五个高频技能，其余按需动态启用，混乱问题基本消失。

4. 实战记录：用 superpowers 驱动一次 Java 项目改造

4.1 场景设定

为了验证 superpowers 在真实项目里的效果，我选了一个自己维护的旧 Java 项目做实验。这个项目是一个内部工具系统，原来用的是比较古老的 Servlet + JSP 架构，最近要做一次技术改造，把接口层迁移到 Spring Boot，并且引入统一的异常处理和参数校验。

这个需求如果丢给裸 Codex 去做，我的预期是它会把web.xml里的映射删掉，新建几个@RestController类，然后告诉我"迁移完成"。但它大概率不会关注旧的 filter 是否兼容、登录拦截器是否还能生效、前端调用的接口路径是否保持一致。这些都是改造里最容易出问题的地方。

所以我先做了准备，在项目里写了两个技能：spring-boot-migration和test-first。配置大致如下：

# spring-boot-migration 技能要点 - 迁移过程中必须保持原有 URL 路径不变，除非用户明确要求修改。 - 旧 Filter 的职责必须在新拦截器或 Spring 机制中找到对应实现。 - 每个接口迁移后，必须同步调整对应的前端调用文档。 - 启动项目并使用 curl 对迁移后的接口做冒烟验证。 # test-first 技能要点 - 每个迁移动手前，先基于原接口行为编写集成测试。 - 测试必须覆盖成功路径、参数校验失败路径、异常处理路径。 - 代码实现后执行 mvn test，保证测试全部通过才能标记任务完成。

可以看到，这些内容其实不是"提示词技巧"，而是一条条项目级的改造约束。把约束写进技能文件，AI 执行时就会带着这些约束做决策。我把这些技能放在项目的.codex/skills/目录下，并确保AGENTS.md里声明了它们。

4.2 任务拆解：AI 如何把大任务拆成子任务

一切就绪后，我给 Codex 输入了这样一句话：

"使用 spring-boot-migration 和 test-first 技能，完成接口层从 Servlet 到 Spring Boot 的迁移。"

它的处理过程让我印象很深。它并没有直接从第一个接口开始改，而是先输出了一个拆解计划：

阶段 1：摸底。扫描 web.xml、所有 Servlet 类、Filter、Listener，整理接口清单。 阶段 2：搭建骨架。创建 Spring Boot 入口类、基础配置类、统一返回体。 阶段 3：按模块迁移。先迁移用户模块接口，再迁移订单模块接口。 阶段 4：补充测试。为已迁移接口补充集成测试，覆盖正常、异常、参数错误场景。 阶段 5：整体验证。启动项目，使用 curl 验证核心路径，输出迁移报告。

这个拆解质量，和我手写的开发计划几乎没有差别。尤其是"摸底"阶段，它真的先去看这些 Servlet 类在项目里哪些地方被转发、被 include，避免迁移后出现调用链断裂的问题。

这里我要特别说一句：拆解能力不是 superpowers 自带的，而是它让 AI 在执行前先调用 plan 类技能，强制它先输出计划再动手。大模型本身是具备拆解能力的，只是默认情况下它不太会主动这么做。superpowers 最大的贡献，就是靠流程设计把这个能力稳定地激发出来。

4.3 执行过程中的自检与修复

在迁移第一个用户接口时，我盯着 AI 输出，注意到它做完代码修改之后，自动执行了这样几个操作：

1. mvn compile，确认没有编译错误。
2. 读取原 Servlet 里的@WebServlet("/user/detail")注解和web.xml里的映射，确认新接口路径仍然是/user/detail。
3. 运行了已有的测试类，发现一个测试的期望状态码是 500，但新代码返回了 400。它分析了原逻辑后发现旧代码在参数缺失时确实抛异常返回 500，而新代码因为加了校验注解提前抛MethodArgumentNotValidException，所以变成 400。

这是一个非常好的例子。这种情况如果没人管，AI 大概率会在测试报错后反复改测试来匹配新行为，而不是反过来审视代码是否符合原有 API 的语义。但因为在 skill 里写了"保持 URL 和基本行为不变"，并且要求自测时必须检查失败原因，它最终选择了保留旧行为，把新增的校验注解去掉，只保留对请求体基本字段的非空判断。

这一步之后的测试全部通过，而我的参与只是在最开始给了它一个任务描述。整个过程，它从拆解、编码、编译、测试到问题归因，几乎不需要人干预。我在旁边做的只是偶尔看一下执行日志，防止它误删文件。

4.4 改造后的收益复盘

整个过程耗时大约 40 分钟，迁移了四个模块的接口，补充了 12 个集成测试。如果我自己手动改，同样的工作量差不多需要一到两天，而且大概率还会漏掉一两个前端调用路径的同步调整。

对比裸用 Codex，带技能使用的差异体现在几个方面：

1. 明确的自测行为。不带技能时，Codex 也可能会跑测试，但概率不稳定；带技能后，只要 skill 里有"必须运行测试"这条，它就会稳定执行。
2. 对既有语义的尊重。我总是在 skill 里写"保持旧行为不变"，这让 AI 在遇到测试与预期不符时，会优先怀疑自己的代码，而不是怀疑测试，这个方向的改错概率大幅降低。
3. 阶段输出的可读性好。整个改造过程像在看一个开发者的工作日志，它每完成一个阶段就输出小结，我可以随时叫停或调整方向，而不是等它一口气写完所有代码再去 review，那种模式一旦方向错了，返工成本极高。

当然，它不是万能的。改造过程中我也遇到了一次 AI 把web.xml里一个 filter 误删的情况，原因是我给的技能描述里写了"旧 Filter 的职责必须在新机制中找到对应实现"，但并没有明确列出哪些 Filter 是核心的，于是 AI 把一个日志记录 filter 判断为"非必要"，直接删掉了。后来我在 skill 里补充了一条"删除任何 Filter 前必须先向用户确认"，这类问题就再没出现过。

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

5.1 装完后技能不被触发，AI 完全无视技能

这是我被问得最多的问题。很多人配置完技能后，发现 AI 依然我行我素，像没看到AGENTS.md一样，怎么排查？

我的排查路径是：

1. 打开AGENTS.md，检查技能描述里有没有明确的触发词。如果你的技能写的是"当合适的场景出现时使用"，那大概率不会触发，因为"合适"对大模型来说太模糊了，我建议改成"当用户提到代码审查、review、找 bug 这些关键词时使用"。
2. 检查技能是否放在了正确的目录。全局技能放在~/.codex/skills/，项目技能放在当前项目的.codex/skills/，不要放混。
3. 如果目录没问题，那就直接显式输入技能名："请使用 java-code-review 技能审查这段代码"。大部分情况下 AI 都能正确加载。如果显式输入都不生效，那大概率是工具本身对技能目录的支持有问题，可以检查版本或重新powerup初始化。

5.2 技能开着，但 AI 执行到一半"跑偏"了

这种情况也挺常见。比如我让 AI 用 plan 技能先输出任务拆解，它写了三行计划就直接跳进代码实现了，完全没有按技能文件里的完整流程走。

我的经验是，技能文件里的步骤太抽象，是跑偏的第一个原因。比如"分析项目结构"这种描述，AI 理解完可能觉得看一眼目录就够了，但你的本意是让它梳理清楚模块依赖关系。所以就别写"分析项目结构"，直接写：

1. 列出 src/main/java 下所有包名。 2. 读取每个模块的入口类。 3. 输出模块之间的调用关系图。

步骤越具体，AI 越不容易自由发挥。另外一个办法是在技能正文末尾加一句"如果遇到无法继续的情况，停下来向用户提问，不要自己假设"，这能有效避免 AI 在一个分支上越走越远。

5.3 全局技能太多，上下文被严重占用

superpowers 技能体系是基于 Markdown 文件加载的，理论上每个技能都会消耗上下文。如果你把社区里所有技能都塞进去，Codex 每次启动都要读一遍所有技能描述，还没开始写代码，上下文就已经耗掉一大截，实际代码生成质量会明显下降。

我的做法是，在~/.codex/skills/下建一个_disabled目录，把不常用的技能全部移进去。需要用时再移出来，或者直接用绝对路径指定。我实际保留在启用状态的技能不超过六个：

1. plan
2. test-first
3. code-review
4. debug-bug
5. git-commit-helper

其他的基本都是按项目临时启用。

5.4 不是 Codex CLI 用户，这个思路能迁移吗

能，而且我强烈建议你迁移。superpowers 最核心的资产不是代码，而是那套"技能包 + 触发条件 + 执行清单"的组织方式。我自己就用这种方式，在别的 AI 工具里也实现了类似效果。

比如有些团队用的是偏向提示词管理与工作流编排的辅助工具（像 Worbuddy 这类），思路完全可以借鉴：把 SKILL.md 的 frontmatter 当作工具里的"场景配置"，把正文章节当作"任务模板"。你在工具里新建一个"Java 代码审查"的工作流，把步骤填进去，触发关键词写上"审查 / review / 找 bug"，实际效果几乎等同于在 superpowers 里创建了一个技能。

另外像 Cursor 这类编辑器里的 rules 文件，本质上也是干这个的，只是表达能力弱一些。但思路是通用的：凡是你能给 AI 定义固定流程的地方，都值得用技能包的方式去沉淀。

5.5 多项目技能互相干扰怎么处理

最后讲一个项目管理上的坑。我一开始把所有技能都放在全局目录，结果在 A 项目写的"支付模块规范"技能，在 B 项目做代码审查时也被加载了，AI 开始用 A 项目的规范去审查 B 项目的代码，输出了一堆无效建议。

处理办法就是我前面说的项目级隔离。所有和业务绑定的规范类技能，一律放在当前项目的.codex/skills/下，绝不放进全局目录。全局目录只放与语言、框架无关的通用能力，比如 code-review、git-commit-helper。这样即使你还管理着五六个项目，每个项目的 AI 行为也能保持相对独立。

我在实际使用中的体会是：superpowers 这类技能框架，真正的价值不在于它让 AI "生成了更好的代码"，而在于它让 AI 的工作习惯变成了可以沉淀、可以复用、可以交给团队成员的项目资产。以前带新人，我得反复强调代码规范、测试要求、审查流程；现在把这些写进技能包，新人用 AI 干活时，AI 会先把这些问题挡下来。这套东西的后续想象空间也很大，比如把团队所有历史变更记录做成 references 参考文档，让 AI 在做设计决策前先检索旧方案，避免重复踩坑。我觉得这才是 AI 编程工具最终该有的形态——不是让它替你做决定，而是把这些年踩过坑沉淀下来的判断标准，原原本本地教给它。