企业官网建设流程全解析

如果你最近在捣鼓 Codex CLI，多半会在终端里感受到一种微妙的分裂感：同一个需求丢给它，今天它先写测试再写实现，明天它撸起袖子直接写业务代码，后天又变成先画目录结构再动手。单看每一次对话，它都挺聪明，但拉通看，过程完全不可控。我抓到的问题就是——AI 很强，但它没有一套“稳定可复用的工作方法”。直到我把 Superpowers 这个技能框架接到 Codex CLI 上，才终于摆脱了这种抽盲盒式的人机协作。

Superpowers 解决的核心问题很直接：把“随缘发挥”的 AI 编程助手，改造成“按手册施工”的工程师。它本身是一个开源技能框架，核心机制叫Skill（技能），说白了就是一叠 Markdown 写成的“岗位说明书”，你用这些说明书指挥 Codex CLI 做需求拆解、代码生成、测试驱动、代码审查之类的事。它不是语言级框架，所以 JavaScript 能用，Java 也能用，.NET、Python 都能套。这篇文章我把自己从安装、配置、写技能到实际塞进 Java 项目里的完整过程整理出来，有步骤，有翻车记录，也有不少靠时间才能踩出来的经验。

1. Superpowers 是什么：它到底给 Codex CLI 加了什么

先说清楚一件事：Superpowers 不是 Codex CLI 的替代品，也不是 IDE 插件，它是跑在 Codex CLI 之上的“方法论层”。你原本用codex命令能完成的事，现在通过技能文件给它加一套固定的执行流程。

1.1 为什么 Codex CLI 需要 Superpowers

Codex CLI 本身已经很强了，它能在终端里读文件、写代码、执行命令，相当于给大模型装了手和脚。但它有个天然缺陷——太“裸”。对话时它确实会遵循你的指令，可是指令的颗粒度完全取决于你怎么写。同样一句“给我写个订单模块”，你写了三行上下文它敢直接开干，你写三十行它才可能先列方案。这种依赖人为堆上下文的模式有个致命问题：不可复制。你这次对话里灌输给它的方法论，下一场对话它全忘了。

Superpowers 的思路就是把 AI 工作流做成了“可版本管理的项目资产”。它允许你定义若干技能文件，每个文件描述一个完整的工作流程，包括输入要求、执行步骤、质量标准和输出格式。Codex CLI 接到任务后，不是直接凭感觉回答，而是先加载对应技能，按技能里写的步骤一步步来。我自己用过之后的体会是：它像给一个高智商但没纪律的员工发了一本 SOP，你会发现它的产出质量从“时高时低”变成了“稳定在合格线以上”。

另外值得注意，它解决的另一个痛点是复用。你团队里花了不少精力在 PR 描述上总结了代码审查要点，过去要复制粘贴到每次对话里，现在做进一个 code-review 技能，所有成员人人可用，还不会写歪。

1.2 技能机制的底层逻辑：授人以渔

说句可能有点重的话，Superpowers 代表的是“把提示词工程升级为技能工程”。常规的 prompt 是一条条临时指令，而技能文件是一个个小型的“AI 工作流应用”。每个技能文件的本质是一组机器可读、人类可读、AI 可执行的步骤说明书。

拆开看，一份技能通常包含这几块信息：

• 元信息：技能名称、描述、适用场景、触发条件，这相当于给技能做了索引，方便 Codex CLI 在需要时自动匹配。
• 输入契约：明确这个技能需要哪些输入，比如目标文件、需求描述、代码库路径。输入不清，AI 很容易跑偏。
• 执行步骤：把任务拆成有序的操作步骤，每一步用自然语言精确描述“做什么、做到什么程度”。
• 禁忌与约束：规定哪些事绝对不能做，比如“不要修改测试文件”“不要自动安装依赖”，这一步能拦住 AI 乱伸手。
• 输出格式：要求它以固定结构输出，比如按严重程度分级的审查意见表格。

这套机制最大的价值是把“经验”变成了可分发、可演进、可审计的东西。以前培养一个新人要靠师傅带，现在你把技能文件交给 Codex CLI，它就能像新人一样按手册办事，而且不会遗漏步骤。你可以把一份代码审查技能从 A 项目拷到 B 项目，可以 Git 提交后和同事 review，也可以在团队里沉淀成公共技能库。这是普通 prompt 根本做不到的。

2. 安装前准备与快速部署

这个框架装上本身不难，但想用得顺，环境要提前弄干净。我特意把它独立成一章，是因为实际翻车的人大多不是死在安装命令上，而是死在环境不对、版本不匹配、技能目录找不到这种事上。

2.1 环境检查清单：动手前先看这四条

Superpowers 要吃 Codex CLI 的老底子，所以前置条件基本上都围绕 Codex CLI 展开。按我复盘完的经验，至少满足下面四条才能流畅跑：

• Node.js LTS 版本：建议不低于 18，最好用 20 或 22。你可以在终端执行node -v查版本，版本太老会导致 Codex CLI 装不上或者启动报错。
• Codex CLI 已安装可用：Superpowers 是以 Codex CLI 为宿主，codex命令必须先存在。还没有的话先用npm install -g @openai/codex装上，装完跑一下codex --version。
• Git 环境正常：因为技能安装通常是从 GitHub 仓库拉取或克隆，所以需要 Git 能连上远程仓库，SSH key 配好。
• 一个真实项目目录：别在空目录里测。Superpowers 的技能调度最理想的是在项目根目录下运行，它要能读到项目的 A 代码、测试文件、目录结构才有意义。

我在自己的机器上踩过一个坑：一开始 Node 版本是 16，装 Codex CLI 时提示成功，但跑任何命令都静默退出，排查了半天才发现是版本不兼容。换到 Node 20 后一切正常。所以这个环境检查别跳步。

2.2 快速安装与配置：按这个顺序来

安装有两个环节：先把 Superpowers 本体拉下来，再把它的技能目录让 Codex CLI 知道。为了方便说明，下面命令格式是我当前环境里验证过的常用方式，具体以你安装的框架版本 README 为准。

第一步，从 GitHub 把仓库克隆到本地：

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

第二步，执行它的安装脚本。这一步通常会做几件事：把技能模板复制到你的用户级或项目级技能目录、生成默认配置文件、输出部署说明。以我接触过的版本为例，安装命令类似：

./install.sh

执行完它会提示你把技能目录配置写进AGENTS.md。AGENTS.md是 Codex CLI 在项目下必读的“宪法”文件，里面写的是项目背景和 AI 行为规范。你在项目根目录创建或追加这个文件，内容大致是：

# 项目说明 - 本仓库使用 Superpowers 技能框架管理 AI 工作流。 - 执行任务前，先看技能列表，匹配对应技能再动手。 - 涉及新增功能时，先调用项目规划技能，再进入编码技能。

这一步很关键。如果没有在AGENTS.md里声明技能使用策略，Codex CLI 不会主动去找技能目录，等于 Superpowers 白装了。

第三步，验证安装是否成功。这时候在项目目录下运行：

codex superpowers list

如果能看到一份技能清单，比如项目规划、代码实现、代码审查、测试驱动开发这类名字，就说明框架已经激活。我这里装完第一次跑的时候列表是空的，后来才发现技能目录路径没对上，这个问题我放到第 5 章细说。

2.3 安装后的目录结构搞明白，少踩一半坑

装完不是立刻写技能，先把它的家底摸清楚。Superpowers 的技能文件一般分布在两层目录中：

• 用户级目录：通常是~/.codex/skills/或~/.superpowers/skills/，存的是全局通用技能，任何项目都能引用。
• 项目级目录：通常是.codex/skills/，存的是只对这个仓库生效的技能，适合团队项目里沉淀业务特有规则。

我个人的习惯是把偏工程的通用技能放用户级，比如代码审查、测试驱动、架构规划；把业务定制的流程放项目级，比如“支付模块上线前检查”“订单接口契约核对”。这种分层的好处是换项目不漏掉通用能力，又不会用别的仓库的私有流程污染当前仓库。

另外，技能文件本身是 Markdown 格式，可以在编辑器里直接打开学习。我不建议把技能文件理解成代码里的“黑盒插件”，它本质上是高密度、强结构的文档，你在里面能看到每一步提示词是怎么写的，这也意味着团队里任何人都能参与维护。

3. 核心实操：用技能、调技能、写技能

装好只是入门，真正让 Codex CLI 变成“纪律员工”的是你对技能的控制力。这一章我会先把开箱技能讲清楚，再教你从零写一个自己的技能，最后给一组日常调用的语感。

3.1 开箱技能库一览：你这个工具箱里有什么

不同版本预置的技能会有差别，但常用的几类基本固定。我把自己最常用的几张“牌”列出来，你拿到手可以先拿它们热身：

• planner（项目规划）：把需求拆解成子任务，明确依赖关系、改动的文件和验证方式。我现在每次接新需求都会先跑它，而不是上来就让 AI 写代码。
• coder（代码实现）：按规划去写实现代码，它会更关注代码结构和编译结果。
• code-review（代码审查）：阅读代码并输出审查意见，按严重程度分组。它不是简单说“这代码有问题”，而是给出具体原因和修改建议。
• test-driven（测试驱动）：强制先写失败测试，再写实现，再跑测试。这个技能对 Java 这类强类型语言特别友好。
• documenter（文档生成）：生成或更新 README、接口文档、架构说明，强调与代码同步。

调用方式通常是这样：

# 查看可用技能 codex superpowers list # 查看某个技能的使用说明 codex superpowers show planner # 指定技能执行任务 codex superpowers run planner --target "给订单服务增加超时订单查询接口"

你写完run后面的技能名，再给一句任务输入，Codex CLI 会先把技能文件内容加载进上下文，然后按技能的步骤走。这就是它和普通对话最大的差别：普通对话是你现场指挥，它现场发挥；技能调用是你下命令，它按流程执行。

3.2 从零写一个技能：拿“测试先行”练手

自己写技能没有想象中复杂，它难的是怎么把流程描述到 AI 能精确理解。我拿一个极简的“测试先行”技能举例，你保存为.codex/skills/test-first.md就能用：

--- name: test-first description: 严格采用测试驱动开发方式实现一个功能。先写失败测试，再写最小实现，最后重构。 inputs: - target: 要实现的功能描述 - test_file: 测试文件路径 - impl_file: 实现文件路径 steps: 1. 阅读功能描述，确认输入输出边界。 2. 在 test_file 中编写覆盖主流程与异常分支的测试。 3. 运行测试，确认测试因缺少实现而失败。 4. 在 impl_file 中编写最小实现，只求让测试通过。 5. 再次运行测试，确认全部通过。 6. 识别重复代码和坏味道，做最小重构，并保证测试仍然通过。 constraints: - 第 3 步之前禁止编写实现代码。 - 不得跳过测试直接写实现。 - 不要修改与本次任务无关的文件。 output: 依次输出：测试摘要、测试运行结果、实现代码改动说明、重构内容说明。 ---

写这类文件真正吃功夫的是steps 的颗粒度。你要是只写“写测试、写实现、重构”，AI 大概率会把步骤并在一起顺手做完，过程中该停的地方不停，该验证的环节不验证。但如果你把“先确认测试失败再写实现”拆成独立步骤并配约束，AI 就真的会一步步来。这背后的原因是大模型对“步骤”比“意图”更敏感，你把它要执行的走路轨迹画出来，它就能走得稳。

另外一个诀窍是给技能写ChatOps 风格的触发描述。我自己在写 description 时，会刻意带上“什么时候该用、输入需要什么”这类信息，原因是 Codex CLI 需要在上下文里做技能匹配，描述写得具体，自动匹配的准确率会上一个台阶。

3.3 日常开发中的调用节奏：什么时候上技能，什么时候别上

用了一段时间之后，我对“何时用技能”有了明确判断。一般来说，任务边界越清晰、步骤规律性越强，越适合交给技能处理。比如“实现一个查询接口”“做一轮代码审查”“生成一份接口文档”，这些都是高重复、步骤明确的事，不用技能反而亏。

反过来，探索性很强的任务——比如“这个 bug 到底怎么定位，需要看日志、改数据、加监控”，这种要求 AI 边做边调整策略的，技能反而会限制它。我自己在这种场景下更倾向直接进 Codex CLI 对话，让 AI 自由探索，等找到根因后再切到技能去完成后续的修改和验证。

还有一个组合使用的技巧：我也是从第二次大项目里才悟出来的。拿到一个复杂需求，先跑planner把任务拆好，接着针对每个子任务挂对应技能执行，实现完统一跑一遍code-review。相当于让 Superpowers 做流程管理，Codex CLI 做具体执行，各干各擅长的事。

4. 实际项目中的工作流实践：从单机折腾到团队协作

工具好不好用，最终要看它在真实项目里的表现。这里我用一个 Java 项目作为背景，讲讲实际接入的过程和效果，顺便聊聊团队层面怎么玩才不翻车。

4.1 把 Superpowers 嵌入团队的日常开发流程

单机使用时一切都是本地文件，爱怎么调都行。但你打算让团队一起用，就得定几条规矩。

首先，把技能文件纳入版本管理。项目级的.codex/skills/目录直接提交到 Git 仓库，这样新成员拉下代码就拥有了同一套 AI 工作流，不会出现“我的 Codex 很聪明，你的 Codex 很傻”的割裂感。技能文件参与 code review，谁改了技能，就等于改了团队的 AI 执行规范，要在 PR 描述里说清楚。

其次，在 AGENTS.md 里写清技能使用红线。比如“涉及核心支付逻辑，必须先用 planner 规划再动代码”“任何代码改动必须运行mvn test之后才能提交”。Codex CLI 每次对话都会加载 AGENTS.md，这个文件相当于全局约束，比每个人现场叮嘱可靠得多。

最后，做好技能效果的复盘。团队用了两周后，我习惯组织一次小回顾：哪些技能是大家高频在用的，哪些技能叫了等于没叫，哪些技能产生的代码质量比预期差。结论直接反馈到技能文件迭代上。你会发现技能不是一次性写死的，它是会生长的资产。

4.2 一个 Java 需求的完整流程示例：从拆解到审查

我在一个实际的支付项目里做过一次完整实验，需求是这样的：

给订单服务增加一个“查询已超时未支付订单”的接口，超时阈值由调用方传入，必须校验阈值范围。

这个需求如果直接丢给裸的 Codex CLI，它大概率会一次性写出一堆代码，但未必覆盖边界条件，更不会主动写测试。而我在 Superpowers 的指挥下，走了这么一条链路：

先跑planner技能，让它拆解任务。它很快输出：新增服务接口、定义请求响应 DTO、编写业务逻辑、补单元测试、更新接口文档。这一步已经把任务切成了独立子任务，而且标出了需要改动的类与文件位置。

接着跑test-first技能，传入测试文件路径和实现文件路径。Codex CLI 先写了OrderTimeoutQueryServiceTest，覆盖了阈值上限、阈值下限、订单状态校验几个用例。我按提示运行mvn test，看到因为实现缺失而失败——这一步符合预期。随后它才开始写实现，再跑测试，全部通过。

最后跑code-review技能，让它对刚生成的代码做严格检查。它给出了一条很有价值的意见：查询超时订单时只过滤了状态和时间，但没有按“订单创建时间”建立索引提示，这个在大数据量下会有性能隐患。这条提醒直接来自技能里预设的“性能审视”步骤，普通对话里 AI 大概率不会主动关注这个点。

整个流程下来，我没有像以前那样写十几行需求描述，也没有在中途重复提醒“你先写测试”。过程完全由技能拖拽着往前走，生产效率和结果一致性都比裸 Codex CLI 高太多。

4.3 效果评估与边界：什么场景值得用，什么场景别硬用

如果只给个定性结论，Superpowers 让我在任务边界清晰的项目里，交付节奏稳了很多。尤其 Java 这种结构规整的工程，类与类之间边界清晰，技能的执行步骤可以写得很具体，效果就格外明显。以前我要花不少时间在 Codex CLI 对话里做“过程管理”，现在这部分由技能接管了，我能腾出精力看需求和做设计。

但它不是万能遥控器。我遇到过几个场景，硬上技能反而添乱：

• 依赖外部系统联调的接口开发：技能只能约束本地代码行为，控制不了下游环境。这种情况下，技能执行完之后，还有大量人工联调工作要做。
• 高度依赖隐含业务知识的任务：团队里很多业务规则写在人脑子里，技能文件不可能全部覆盖。这时 AI 按技能写出来的代码，表面合规，业务上可能是错的。
• 需要反复试探的疑难问题：定位线上 bug 时，思路是发散的，步骤是探索性的。技能把路径定死了，反而妨碍它找到真相。

我的原则是：技能管流程，人工管判断。它把重复劳动固化成标准动作，但项目的成败还是得靠人去把握方向。

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

最后这部分，我把自己和身边朋友用 Superpowers 时踩过的坑集中整理出来。如果你上手后遇到问题，可以先来这层翻一翻。

5.1 技能加载失败：列表里空空如也

症状：执行codex superpowers list时，输出为空，或者提示找不到技能目录。我首次安装就出现了这个问题，当时第一反应是安装脚本没跑成功，后来排查才发现是技能目录的读取路径和我的用户目录不在同一层级。

排查思路是分三步走。第一步，确认技能文件确实落盘了，到~/.codex/skills/或项目.codex/skills/下看看有没有.md文件。第二步，检查命令读取的是哪个目录，如果你不确定，直接看框架的配置文件里是否有skills_path之类的字段，把它改成技能文件实际的存放位置。第三步，检查AGENTS.md里有没有声明技能目录的挂载方式，有些版本需要在这里显式写路径。

经验提醒：改完配置记得重开一个终端会话再跑命令。Codex CLI 对配置文件的读取有时只在会话启动时加载一次。

5.2 自定义技能不生效：AI 就是不按套路出牌

症状：技能文件写得很详细，调用也不报错，但 Codex CLI 的输出行为和普通对话没差别，完全没体现技能里的步骤。这个问题的根源大概率出在技能的“可执行性”上。

我自己反复验证后总结出三个高频原因。第一，描述太模糊，比如只写“审查代码”，AI 不知道你要审查哪一部分，或者说判断标准是空的。第二，步骤之间颗粒度失衡，两步之间跳跃太大，AI 只能自行脑补执行细节。第三，约束区与动作区混在一起写，AI 分不清什么必须先做、什么不能做，最后它选了最省事的那条路。

把这三个问题修掉，技能马上就“有骨气”了。我还有一个技巧：技能文件写完后，自己在脑子里推一遍——把 AI 当作一个完全不懂业务但绝对服从命令的新手，看步骤能不能走通。走不通就继续拆。

5.3 与 Codex CLI 版本兼容性问题：升级后就失灵

这个坑属于所有 CLI 工具的通病。Codex CLI 升级后，部分旧语法、配置读取方式会变，Superpowers 如果没跟上，轻则警告重则命令失效。我遇到过的情况是：升级 Codex CLI 后，原有的codex superpowers子命令直接提示不识别。

应对策略比较保守但有效：别盲目追新。如果你是重度用户，给 Codex CLI 和 Superpowers 都固定版本，升级前先看看新版 release notes 有没有提到破坏性变更，再决定要不要升。开发环境里测试通过后再升生产环境，这是老传统了，但总有跳过的。

如果不小心已经升挂了，处理方式也不复杂：用 npm 或 git 回退到旧版本，等 Superpowers 发布适配版再跟上。我自己一度保守到在项目里写清楚“本仓库锁定 Codex CLI 1.x 版本”，这样团队里的成员不至于各升各的然后互相踩雷。

5.4 提高技能执行质量的小技巧

最后补一些沉淀出来的写法经验，都是文档里不会教你的。

• 技能里加“完成定义”：不要只写步骤，还要写清楚“什么算做完”。比如测试技能里写“所有新用例通过才算完成”，审查技能里写“所有阻断级意见都处理后再结束”。这能有效防止 AI 提前收工。
• 步骤数量控制在 5 到 7 步：超过这个数字，AI 容易丢失前后一致性。如果流程实在复杂，就把技能拆成多个子技能，让一个技能只专注一个阶段。
• 给技能写“不做什么”清单：AI 容易把任务范围外的东西顺手改掉。明确写“不得修改 pom.xml”“不得动数据库迁移文件”这类约束，能省去不少 review 惊吓。
• 定期迭代技能文件：技能不是一次成型，而是随着你对任务理解的加深不断演进。我每次发现 AI 在某一步质量波动大，就会回到技能那一步去补细节，这种微调比重写一个大 prompt 有效得多。

我个人在实际操作中的体会是：Superpowers 真正的价值不在于它把多个提示词打包了，而在于它逼着你把 AI 协作从“随性聊天”扭转到“流程管理”。以前写提示词，我总是担心自己少交代了什么背景，让 AI 理解偏了。现在技能文件把该说的话说透，每次对话反而节省了大量上下文，Codex CLI 的响应稳定性也提升了。

最后再分享一个小技巧：如果你刚上手不知道从哪类技能开始，我建议先写一个“今日任务规划”技能，输入是一堆杂乱的待办事项，输出是排好优先级、标注依赖路径的执行清单。它最简单、最容易见效，又能让你快速理解技能文件的写法习惯。从这个小技能开始，你会发现把思考过程固化下来这件事，对人和对 AI 都适用。