企业官网建设流程全解析

最近一直在折腾 Codex CLI，各种插件和扩展翻来覆去地试。其中一个叫 superpowers 的项目，算是真正用出感觉的。它不是那种加几个快捷键的小工具，而是把 Codex 从一个"你问我答"的聊天式编码助手，变成了一套能自己规划任务、拆解步骤、执行命令、回头审查的完整工作流。这篇文章就围绕它来写，把它的设计思路、安装过程、核心技能拆解、实操流程，以及我在真实项目里踩过的坑，一次讲清楚。

如果你正在用 Codex CLI 写业务代码，或者觉得现在的 AI 编码助手"只会改文件、不会干活"，那这个项目大概率能解决你的痛点。它适合两类人：一类是已经用上 Codex CLI、想让它更可靠的老手，另一类是刚接触 AI 编程、希望一开始就建立起规范工作流的开发者。下面内容没有平台专用术语，直接照着操作即可。

1. 先搞清楚：superpowers 是给 Codex CLI"加技能"的扩展包

1.1 为什么需要技能扩展

先明确一个前提：superpowers 不是独立的编码工具，它依附于 Codex CLI。Codex CLI 本身已经能做代码生成、文件修改和命令执行，但它在处理复杂任务时有个很明显的问题——"太听话，不思考"。你让它实现一个用户登录功能，它会直接把相关文件改了，但改完之后不会主动考虑单元测试、异常处理、数据库迁移这些周边环节。原因很简单：模型每轮对话的上下文有限，它倾向于在最短路径上完成任务，而不是在完整工程链上完成任务。

superpowers 做的就是在 Codex CLI 和模型之间插入一层"技能系统"。每个技能都包含具体的指令模板、执行规范和判断标准。当任务触发某个技能时，Codex 不再自由发挥，而是按照技能里定义的步骤一步步走。这样一来，同样的需求输入，输出质量稳定很多。

我打个比方：Codex CLI 原本像一个刚毕业的程序员，聪明、肯干，但做事情没有章法；superpowers 就是给他一套公司级开发规范，告诉他"先做方案、再拆分任务、然后逐个实现、最后回归测试"。程序员还是那个程序员，但有了流程约束之后，交出来的东西就靠谱得多。

1.2 技能系统和提示词的本质区别

很多人第一反应是："这不就是写个 prompt 模板吗？"确实有点像，但实际差别很大。普通提示词是一次性的，你把一大段要求粘贴到对话框里，模型读完就开始干活。而 superpowers 的每个技能是独立的 SKILL.md 文件，放在项目目录里，Codex 会根据任务内容自动匹配、动态加载。

举个例子，我在项目里输入"帮我排查一下用户模块的并发问题"。如果没有技能系统，Codex 可能直接打开文件开始改代码。有了 superpowers 之后，它先识别到这是 Debug 场景，然后加载 debug 技能，按技能要求先复现问题、再定位根因、接着修复、最后写回归测试。整个过程是分阶段的，每个阶段都有明确的输出物和验收标准。

更关键的区别在于：提示词是"说一次就完了"，技能是"每次遇到同类场景都会用"。普通提示词写再长，下一次对话模型还是会遗忘；而技能文件在项目里持久存在，每次触发都会生效。这也是我最终放弃自建 prompt 库、转向技能系统的根本原因——维护成本差了一个量级。

1.3 适用场景和人群

从实际使用经验看，superpowers 最适合以下几类场景：

• 涉及多个文件、多个步骤的模块级功能开发，比如"新增订单导出功能"这样的任务
• 需要严格遵循测试规范的项目，比如要求每次改动必须补充单元测试
• 新成员快速上手项目，可以让 Codex 先按技能梳理项目结构再动手
• 对接 CI/CD 流水线的自动化任务，比如自动修复测试失败并推送分支

不太适合的场景也有：纯探索性的代码实验、临时写一个几十行的脚本、已经非常成熟的脚手架项目。这类简单任务用技能系统反而显得笨重，直接对话反而更快。工具选型上的判断标准很简单——任务越复杂、涉及环节越多，技能系统的价值就越大。

2. 安装准备与两种安装方案

2.1 前置条件：先把运行环境理清楚

安装 superpowers 之前，Codex CLI 本身得先跑起来。我建议把 Codex CLI 升级到最新稳定版，因为技能系统依赖一些较新的命令执行和上下文管理接口，老版本会报错或者行为不一致。

操作系统方面，macOS 和 Linux 都行，Windows 用户需要通过 WSL 来做，原生支持目前还不大好。硬盘空间预留 500MB 左右即可，主要是技能模板和日志文件的占用，不会太大。另外，项目里最好已经初始化好 Git 仓库，因为很多技能在执行过程中需要做分支管理、暂存和回滚。

有两点需要特别注意。一是终端编码建议切到 UTF-8，否则技能文件里的中文描述可能乱码；二是保证 Codex CLI 有执行 shell 命令的权限，superpowers 的很多技能会主动调用 git、grep、find 这些基础命令，如果权限受限，后续会有各种诡异问题。

2.2 三种安装方式选哪种

我在不同环境里试过三种安装方式，各有优缺点，你们可以按实际情况选。

第一种，官方一键脚本安装。这种方式把技能模板复制到全局配置目录，并注入到 Codex CLI 的配置文件中，之后所有项目都能用到。优点是省事，缺点是全局生效，如果你同时维护多个风格差异很大的项目，技能之间可能会互相干扰。

第二种，单项目手动安装。把整个技能库 clone 或者下载到项目的.superpowers目录下，并在项目级配置里声明技能路径。这种方式隔离性最好，适合团队协作，每个项目用自己的技能集。缺点是你得在每个项目里重复操作，稍微麻烦一点。

第三种，从源码构建。适用于想二次开发技能系统的用户。源码构建的好处是可以改技能内部的执行逻辑，打造完全定制化的工具链，但对普通开发者来说成本偏高，我建议先把前面两种方式用熟再考虑。

以手动安装为例，标准流程是把技能文件放到项目根目录下的.superpowers/skills路径中，然后在 Codex CLI 的配置文件里设置技能目录的绝对路径。配置完成之后重启 Codex 会话，技能就会自动加载。如果发现技能未生效，优先检查路径是否写对、配置文件是否有语法错误。

2.3 验证安装是否成功

装完之后不能急着用，先验证一下。最直接的方式是启动 Codex CLI，输入一段能触发某个技能的命令，比如"帮我看看当前项目里有哪些未处理的 TODO"，如果代码里确实有 TODO 注释，而 Codex 没有直接回答，而是先输出一段"正在应用 scan 技能"之类的提示，说明技能加载成功。

另一个验证方法是查看技能目录里有没有生成日志文件。superpowers 默认会把每次技能调用记录下来，包括触发时间、技能名称和执行的命令。日志正常生成，说明从技能识别到命令执行这条链路已经通了。

这一步不能省。我见过不少人装了之后直接开工，结果 Codex 根本没加载技能，全程还是旧的自由模式，还反过来抱怨工具没作用。十分钟的验证能省掉后面一整天的困惑。

3. 核心技能包拆解与设计逻辑

3.1 SKILL.md 是技能的最小单位

superpowers 的技能体系，核心是一个个 SKILL.md 文件。这个设计非常像 Jekyll 或 Hugo 的 front matter 配置，文件开头是一段 YAML 格式的元信息，声明技能的名称、描述、适用场景和触发关键词；中间部分是执行步骤说明；最后是完成标准和自查清单。

这个结构最大的好处就是"人机共读"。人在 IDE 里打开 SKILL.md 可以直接看懂这个技能是干什么的、怎么用；Codex 在对话中也能通过文件内容理解技能的执行逻辑，不需要专门的解析器。你可以把它想象成一份既给 AI 看、也给人看的标准化操作手册。

我在实际使用中发现，SKILL.md 的元信息写得好不好，直接决定了技能触发准不准。描述里应该包含具体的动作词和对象词，比如"调试 Python 单元测试失败"，而不要只写"Python 相关"。动作词和对象词越具体，模型在任务识别阶段就越容易匹配到正确的技能。

3.2 常用技能逐一拆解

我项目里目前用得最多的技能集中在四个：规划、实现、审查、重构。它们可以单独使用，也能串成一条完整的工作流。

规划技能会在动手改代码之前先输出一份实施方案。方案里包括改动涉及的文件清单、每个文件改什么、改动顺序是什么、怎么验证改动是否正确。这份方案会先展示给我确认，而不是直接开始改文件。这个设计非常实用，因为 AI 编码最大的风险就是改错地方，有了规划环节，风险在动手之前就被拦截了一部分。

实现技能负责按规划执行编码。它和普通改文件的区别在于，实现技能会拆分任务列表，每完成一个小任务就自动运行测试，测试通过之后再进行下一个。这种"改一步、验一步"的模式大大降低了错误累积的概率。

审查技能会在代码完成后自动做一轮代码审查。审查范围不仅包括语法错误，还包括命名一致性、异常处理是否完整、有没有遗留的调试代码。它会把问题分为高、中、低三个等级，高中级问题会要求修复后再继续。

重构技能专门用来做结构优化。它跟实现技能最大的区别是"不改变功能只改变结构"，执行前会先自动跑一遍现有测试，确保重构前后行为一致。这个技能我在处理遗留项目时非常依赖，整体降低了重构的心理负担。

3.3 Java 专项与跨语言扩展

搜索热词里出现了"superpowers java"，这其实对应一个很有价值的专项技能包。Java 项目的构建体系、测试体系和代码规范跟 Python 或 JavaScript 差异很大，通用技能很难覆盖到位。Java 专项包的核心在于它理解 Maven 和 Gradle 的执行机制，能直接调用构建命令跑测试，并解析构建输出中的失败原因。

我现在一个 Spring Boot 项目里同时维护了三十多个模块，每个模块都是独立的 Maven 工程。以前让 Codex 改代码，改完它不知道要跑哪个模块的测试，经常整个仓库全量构建，一次要十几分钟。换成 Java 专项技能之后，它会先解析 Maven 的模块依赖关系，定位改动模块对应的测试范围，然后只跑相关模块的测试。速度提升非常明显，从十几分钟降到三分钟以内。

除了 Java，superpowers 还支持自定义语言专项。如果你用的是 Go、Rust 或者 PHP，完全可以仿照 Java 专项包的思路，为语言生态单独写一套技能。核心要做的就三件事：定义该语言的构建命令、测试命令、常用代码规范。这三个信息写进 SKILL.md，技能就能在这些约束下工作。

3.4 安全防护机制：不让 AI 乱碰危险命令

AI 执行命令的能力越强，潜在风险就越大。superpowers 里专门有一套安全防护机制，对危险操作做了分级控制。最典型的例子是git push --force这样的强制推送命令，默认会被拦截，除非你在技能中显式声明允许；删除文件的rm -rf命令也必须经过二次确认才会执行。

这个防护机制的实现思路很朴素：在命令执行层维护一份危险命令清单，匹配到清单里的命令时，Codex 会暂停操作并向用户请求确认。你可以在技能配置里调整策略，改成"静默拦截"或者"直接允许"。我的建议是默认保持拦截，等你对某个项目的安全性有足够信心之后，再针对性地放行部分命令。

不少人的第一反应是"太麻烦了，打断操作节奏"。但真实项目里，AI 误操作造成的损失远大于那点麻烦。我之前有一次让 Codex 清理无用文件，它没走清理技能，直接自由发挥执行了删除命令，好在我选择了让危险命令必须确认，否则那一堆删掉的文件就真的没了。安全机制不是用来限制效率的，是给你兜底的。

4. 完整实操：从需求到交付的一站式工作流

4.1 第零步：先让 Codex 理解项目

很多人在跟 Codex CLI 配合时犯的第一个错误，就是直接丢需求。技能系统再强，如果模型对项目背景一无所知，产出的方案也会跑偏。所以我的标准流程里会加一个"项目认知"步骤：在开始正式任务之前，先让 Codex 扫描一下项目结构，读取 README、依赖文件和最近的 Git 提交记录。

这个步骤很基础但极其有效。Codex 在理解项目背景之后，规划出来的方案会贴合项目的实际架构，而不是泛泛而谈的"标准答案"。比如一个使用了 MyBatis 的项目，Codex 在方案里会自然地包含 XML mapper 的改动，而不是像对待 JPA 项目那样去改 Repository 接口。

操作上不需要额外配置，只需在对话里明确要求"先做项目概览，输出项目技术栈和模块划分，再开始任务"。如果项目里已有可用的 SKILL.md，它会自动遵循技能里的规范执行，这就是技能系统的加持效果。

4.2 用 Plan 技能做方案论证

项目认知完成之后，我会把任务需求发给 Codex，并明确指定"使用规划技能，不实际改代码，只输出方案"。这一步是整个工作流里最值得认真对待的环节。方案出来之后，你得像评审同事的设计文档一样逐行看，发现不合理的地方马上指出来，让 Codex 修改方案，直到方案符合项目实际约束。

Plan 技能输出的方案一般包含改动范围、文件清单、实现顺序、风险点和验证方式。其中，验证方式是判断方案质量的分水岭——如果方案里只写了"修改代码"，完全没有提到"如何测试、如何验证、如何回滚"，这个方案就不能直接进入实现阶段，需要打回补充。

我通常会在方案确认后，让 Codex 把方案内容写成一个 markdown 文件放到项目 docs 目录里。这个文件既是实施的依据，也是后期 review 的对照清单。万一实现过程中出了偏差，对照方案一看就知道是哪一步偏离了预期。

4.3 用 Implement 技能执行并自动验证

方案确认后，切换到实现技能。这里有一个好消息和一个坏消息。好消息是，实现技能会严格按方案步骤执行，每完成一步就运行相关的测试命令，测试过了再继续下一步。坏消息是，测试可能很久——尤其是大型项目，全量测试可能跑到十几分钟。

所以我的建议是，在执行前先跟 Codex 约定测试范围，比如"只跑通过 Maven 的 -pl 参数指定的模块测试"，避免每一次小改动都触发全量构建。这个约定可以直接加在技能的配置里，也可以在当前对话里用自然语言下达。两种方式我都试过，最终选择了在技能配置文件里固定下来，因为这样每个项目成员的操作行为都是一致的。

实现过程中遇到测试失败，Codex 不会直接跳过，而是停下来分析失败原因，尝试修复，再重新跑测试。如果连续几次修复失败，它会主动向我汇报当前状态和尝试过的方案，而不是死磕下去。这个"主动求助"的机制减少了大量无效时间消耗。

4.4 用 Review 技能做人工监督的最后一道坎

实现完成、测试全绿之后，并不意味着可以收工。我会再做一次代码审查，让 Codex 以"不放过任何低质量问题"的标准，审视所有改动的 diff。审查重点包括：命名是否与项目代码风格一致，是否留下临时代码，异常处理是否完整，日志信息是否包含足够的诊断上下文。

审查报告出来之后，你不能直接照单全收。我的习惯是对照报告逐条做判断——有些建议是合理的，直接让 Codex 修掉；有些属于风格偏好问题，跟团队规范不一致的，我会保留意见并忽略。关键是让 Codex 在审查阶段"只提问题、不改代码"，把修改的决策权攥在自己手里。这样既利用了 AI 的检查覆盖能力，又保住了人的判断权。

整个流程下来，最有成就感的一点是：从需求输入到代码合入，中间不再需要我一句一句地指挥"改这里""跑一下测试""再看看那边"。我只需要在规划和审查两个环节把好关，其余的执行过程全部交给了技能系统。

4.5 实用小技巧：自定义一个业务专属技能

superpowers 最强的其实是自定义能力。当你在一个领域里反复做同样的任务时，把它固化成技能，收益非常可观。我带来一个实际案例：我们团队每周都要做数据库脚本的增量变更，流程是写 SQL 脚本、在预发布库执行、验证数据结果、出上线报告。以前每次都得人工操作，细节非常繁琐。

后来我按 SKILL.md 格式写了一个"数据库变更"技能，把这个流程的每一步都定义清楚。之后 Codex 在项目里遇到"数据库变更"相关的关键词，就会自动加载这个技能，按流程执行每一步。现在团队成员做数据库变更时，流程一致性明显提高了，原来容易遗漏的"验证数据结果"步骤再也没被跳过过。

写自定义技能的难点在于步骤细化程度。步骤太粗，Codex 的自由度太大，输出不稳定；步骤太细，又会让模型变得机械，遇到特殊情况不会变通。我摸索下来的平衡点大约在"每个步骤包含一个明确动作和一个明确验收标准"这个粒度，供你们参考。

5. 高频报错与排查方案

5.1 安装后技能不触发

这是最高频的问题：装完了，Codex 也启动了，但输入命令时完全看不出技能生效的迹象，行为跟之前一模一样。排查思路分三步。首先确认技能目录路径是否正确配置，最常见的问题是把相对路径写进了配置文件，而 Codex 在子目录启动时找不到技能文件；其次检查 SKILL.md 的 YAML 元信息格式，缩进错误会导致技能解析失败，而且通常不会报错；最后看日志文件，如果技能完全没有被扫描到，就是路径或格式的问题，如果扫描到了但没有触发，就是元信息里的关键词描述不够准确。

5.2 命令执行被安全机制误拦截

安全机制有时会挡住一些其实无害的命令，这很正常。我遇到过 Codex 在删除临时文件时触发了确认请求，原因只是命令里包含了rm关键词。处理方法是不建议全局关闭安全机制，而是按具体命令放行。你可以在配置里把例如rm temp_*这类明确安全的模式加入白名单，让安全机制只对高风险模式生效。

如果你用的是团队共享的配置，放行命令这个动作一定要经过讨论再执行，毕竟每个人的项目环境都不一样，你觉得安全的命令换到别的项目里可能就是灾难。安全机制宁可稍微严一点，也不能为了省一次确认去冒险。

5.3 与 CI/CD 集成时的环境差异

把 superpowers 接入 CI 流水线，会遇到跟本地完全不同的环境特征。最常见的问题是 CI 容器里没有安装 Git 或者 Java，而技能步骤里用到了这些工具，导致反复报错。解决方式很简单：在 CI 的镜像构建步骤里，把技能依赖的工具提前装好。

另一个坑是 CI 环境的默认工作目录跟本地不同，相对路径的技能文件会找不到。我建议在 CI 脚本里进入项目根目录后再启动 Codex，并且给技能配置里统一使用相对项目根路径，不要在技能步骤里写死绝对路径。还有一点，CI 是无人值守的，危险命令确认机制在 CI 里会直接导致任务卡死，需要提前把安全策略调整为静默模式，同时做好执行日志留存。

5.4 Token 消耗和上下文管理

技能系统带来的一个副作用就是 Token 消耗明显上升。每个技能加载时都要读取完整的 SKILL.md，执行过程中还会输出中间状态。如果你的账号 Token 额度有限，这会是一个现实的问题。我的应对方法是给技能文件"瘦身"：把元信息控制在最精简范围，把不必要的过程性描述删掉，只保留关键步骤和验收标准。

上下文管理方面，我建议每完成一个大阶段就开一个新的 Codex 会话，并把当前进度摘要用几句话传递过去。这个习惯可以避免上下文窗口被中间步骤占满，让模型在每个阶段都能专注于当前任务。实测下来，分阶段会话比长会话的稳定性和输出质量都要好。

下表整理了我在真实项目里遇到的四个典型问题以及解决思路：

6. 我的实际使用体会

6.1 一周高频使用后的真实评价

连续一周把日常开发任务全部切到 superpowers 工作流之后，我最大的感受是"原来 AI 编码工具可以做到这么可控"。在没用技能系统之前，Codex 的输出像开盲盒，有时候很惊艳，有时候很离谱；用了技能系统之后，输出质量进入了一个稳定区间，至少在规划和审查两个环节的约束下，它不会做出超预期的危险动作。

当然，它也不是银弹。技能系统的执行速度比自由对话慢，因为多了解析、规划和验证的环节。如果你的任务只是"把这段代码里的变量名改掉"，完全没有必要启动技能流程。我的原则是：简单任务走自由对话，复杂任务走技能流程，两种方式配合使用，效率才会最大化。

6.2 我在使用中踩过的三个坑

第一个坑是贪多嚼不烂。刚开始我一次性装了十几个技能包，结果每个技能都不深入，而且相同场景下多个技能竞争触发，Codex 经常选错。后来我把技能削减到跟当前项目最相关的四个，效果反而立刻提升。技能在精不在多，这个原则一定要记住。

第二个坑是忽视了技能与项目配套性。有些技能写得很通用，但项目本身没有对应的测试框架，技能执行到验证环节就会卡住。后来我在引入新技能之前，先检查项目里是否具备技能依赖的工具和框架，不具备就先补上，再让技能生效。

第三个坑是没有及时更新技能文件。AI 编码工具迭代速度极快，技能库里过时的执行规范会带来误导。我现在每两周维护一次技能文件，对照最新项目实践做增删改。技能的维护其实是项目文档工作的一部分，它不是一劳永逸的，需要持续投入时间。

6.3 值得关注的后续方向

从我自己的实践经验出发，superpowers 这类技能系统真正打开了一条路：它让"AI 编码规范"拥有了可执行、可版本化、可复制的载体。以前团队的编码规范写在 wiki 里，人都不一定看；现在规范写进 SKILL.md，Codex 每次干活都会自动遵循，实际的执行效果比文档好十倍。

团队协作方面，我觉得可以把技能目录纳入 Git 仓库管理。这样技能规范变更会留下历史记录，code review 时也能看到技能层面的调整。新成员加入后，拉取代码的同时就继承了整个项目的 AI 工作流，上手成本可以降得非常低。

最后再分享一个我这几天一直在用的技巧：把项目里反复出现的问题记录成新的技能。比如某个第三方 SDK 的调用总是容易忘参数，我会把正确的调用方式和易错点写成一个小技能，下次再遇到它，Codex 就会直接按正确方式执行。这个"经验沉淀"的过程，让 AI 工具越用越顺手，这是我最推荐大家尝试的玩法。