企业官网建设流程全解析

如果你最近在用 Codex CLI 干活，八成已经在 GitHub 或技术社区刷到过 superpowers 这个项目。star 涨得飞快，评论区清一色是“装完之后 Codex 像换了个人”。我一开始觉得这名字营销味太重，但真正照着 README 装了一遍、跑了两三个完整功能之后，我的结论是：这名字不虚。它不是给 Codex 加了一两个花哨功能，而是把一套完整的工程师工作方法，直接注入到 AI 编码代理的行为里，让 Agent 从“能写代码”变成“会做项目”。这篇文章就把我这几周的实操过程、踩坑经验、技能拆解全部写出来，覆盖安装、配置、核心技能、完整实战流程和问题排查，适合所有在用 Codex CLI、或者想让 AI 编程更可控更规范的开发者参考。

1. superpowers 到底是什么：给 Codex CLI 装上一套“工程师思维”

简单说，superpowers 是一个开源的“技能包”项目，专门给 OpenAI 的 Codex CLI 设计。GitHub 上的仓库地址是 obra/superpowers，作者是 Jesse Vincent。它的核心不是训练一个新模型，也不是写了一个更聪明的提示词模板，而是提供了一整套结构化的技能文件，告诉 Codex 在什么场景下应该怎么思考、怎么规划、怎么动手写代码。

1.1 从“能写代码”到“会做项目”

Codex CLI 默认的行为模式，说好听点是“快”，说难听点是“莽”。你给它一个需求，它通常会立刻打开文件开始改，改完告诉你“完成了”。小任务这么干没问题，但一旦落到真实项目里——多文件、老代码、有测试、有历史包袱——它就容易犯三类错误：第一，没搞清楚需求就开始动手，做出来的东西和你心里想的完全是两回事；第二，直接改核心文件，不留余地、不补测试，改完整个项目跑不起来；第三，不会规划，东一榔头西一棒子，改到哪算哪。

superpowers 的思路是：模型本身已经足够强，缺的是“过程约束”。它通过一整套技能文件，把工程师日常的工作流——需求澄清、方案设计、编写计划、测试驱动开发、代码评审、安全审查——变成 Agent 可以随时调用的“行为准则”。装上之后，你再让 Codex 做一个功能，它不会再上来就改代码，而是先问清楚需求，再写一份计划，然后按计划逐步实现，每一步都带着测试走。说白了，就是给一个能力很强但没什么耐心的年轻程序员配了一位经验丰富的导师。

1.2 典型应用场景与适合人群

我实测下来，最值得用 superpowers 的场景有三个。一是新项目从零搭建，brainstorm 技能会帮你在动手前把需求、边界、用户故事全部理清，避免“第一版就写歪”。二是老项目加功能，planning 技能会先生成一份包含数据模型、接口、测试策略在内的实施计划，你确认了它才动手，大大降低了改崩老代码的概率。三是重构和 Debug，专门的调试技能会引导它系统化定位问题，而不是靠瞎猜。

适合的人群也很明确：已经装了 Codex CLI、但觉得默认效果不够稳定的开发者；团队里想统一 AI 编码流程、让 Agent 行为可控的工程负责人；还有对 AI 编程感兴趣、想理解“技能（Skills）机制”到底能做什么的学习者。如果你只是偶尔用 Codex 改一行配置、写一个脚本，那 superpowers 可能有点重；但只要你认真拿它写真实项目，这套流程带来的收益会非常明显。

2. 为什么需要 superpowers：拆解技能机制背后的设计思路

在讲安装和用法之前，我建议你先理解 Codex CLI 的技能机制。这不是背景知识，而是你后面排查问题、自定义技能时必须用到的基础。

2.1 Codex CLI 的技能机制是怎么运作的

Codex CLI 支持从目录加载“技能”。一个技能本质上是一个文件夹，里面有一个核心文件叫 SKILL.md，用 Markdown 编写，带一段 YAML frontmatter 定义了技能的名称和描述。Codex 启动时会扫描技能目录，把每个技能的描述加载到上下文里；当你的请求触发了某个技能描述对应的场景，它就会读取完整的技能文件，按照里面的指令行动。

技能目录默认放在~/.codex/skills/，也可以放在项目目录下实现团队级共享。除了按需激活，某些技能还可以设置为“始终可用（always-on）”，也就是每次会话都把完整内容加载进来，适合那些希望 Agent 逢事必守的规则，比如“所有代码必须先有测试”。

这个机制的精妙之处在于：技能就是纯文本，完全透明、可编辑。Agent 的行为出了偏差，你不用去调“神秘参数”，直接打开技能文件看是哪条指令写得不够清楚，改一行就能见效。这比传统的“调提示词”要可维护得多。

2.2 superpowers 的核心设计：先思考、再计划、后实现、必测试

superpowers 的整个技能体系，围绕一条工程主线展开：先思考，再计划，后实现，必测试。这条主线不是口号，而是被拆成了一个个可独立调用的技能。

第一个环节是“先思考”。brainstorm 技能要求 Codex 在动手前先和你来回对话，把需求、约束条件、非目标、用户故事全部问清楚。它甚至会让 Agent 先复述一遍你的需求，确认理解一致才进入下一步。第二个环节是“再计划”。writing-plans 技能会把讨论结果转成一份结构化实施计划，包含背景、技术方案、分步任务、验收标准、风险点。这份计划本身就是一份可评审的文档，你点头它才能继续。第三个环节是“后实现，必测试”。test-driven-development 技能规定实现必须走红-绿-重构循环，先写测试看到失败，再写最小实现让测试通过，最后重构收尾。除此之外还有 code-review、security-review、debugging 等一系列辅助技能，覆盖开发全流程。

这套设计的高明之处在于，它把“经验”变成了“文件”。项目里的任何一个人，甚至一个新加入的 AI 代理，只要加载了 superpowers，就等于站在同一位资深工程师的肩膀上干活。团队协作时，你不用再苦口婆心地告诉 AI“你要先写计划”，技能本身就替你说了。

3. 安装与基础配置：从零开始启用 superpowers

下面进入实操环节。我以 macOS 终端为例，Windows 和 Linux 的原理一致，只是路径略有差异。

3.1 安装前置条件

首先保证本机已经装好 Codex CLI 并且能正常登录调用模型。安装 Codex CLI 通常用 npm 或 Homebrew，装完在终端执行codex能正常交互即可。其次你需要 git，因为安装过程本质上是从 GitHub 拉取技能文件。最后，确认终端网络可以正常访问 GitHub 和 npm 源，这一步是后续所有操作的前提。

我建议安装前先把 Codex 版本更新到比较新的版本，技能机制在早期版本里有过不少变化，老版本可能缺失相关命令。升级方式一般是重新执行当初安装 Codex 的命令，再codex --version确认。

3.2 通过 codex install 安装技能包

superpowers 的 README 提供了专门的安装命令。以我当时安装的版本为例：

codex install github.com/obra/superpowers

执行后，Codex 会从 GitHub 拉取仓库，并把技能目录安装到本机技能目录。如果命令提示找不到，可以先 clone 仓库到本地再指定路径安装：

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

提示：这个工具迭代很快，安装命令的细节将来可能调整。你只需要记住一条原则——安装动作就是把整个skills目录里的内容放到 Codex 能扫描到的技能目录。遇到命令变了，到仓库 README 里找最新写法即可。

安装完成后，codex install 通常还会输出一段后续指引，提示你在 Codex 会话里激活 superpowers。不同版本的提示不完全一样，但核心是让你在 Codex 里输入类似“Use the superpowers skill to help me get set up”这样的指令，让它引导你完成初始化流程。这个初始化很重要，它会检查技能是否被正确识别，并且帮助你生成后续会话要用的上下文配置。

3.3 验证安装与查看技能列表

装完不是就结束了，一定要验证。最简单的方式是直接问 Codex 自己：

codex

然后在会话里输入“请列出你现在可用的 skills，并告诉我 superpowers 是否已经加载”。如果它回答中提到了 brainstorm、writing-plans、test-driven-development 等技能，说明安装成功。

更直接的办法是查看本机技能目录：

ls ~/.codex/skills/

正常情况下你会看到 superpowers 下的各个技能子文件夹，每个文件夹里都有一个 SKILL.md。我还建议检查一下配置文件~/.codex/config.toml，确认是否有和 superpowers 相关的配置项。部分版本要求在配置里声明技能可用，类似下面的结构（字段名请以你本机 Codex 版本为准）：

[always_available_skills] superpowers = true

这条配置会把 superpowers 的技能描述常驻上下文，让 Codex 随时知道它们存在。缺点是会多占用一些上下文空间，如果你只在大任务时用 superpowers，不设置 always-on 也行。

3.4 在 Trae 中复用 superpowers 技能

热词里有人提到“trae work cn 安装 superpowers skill”，我在实践里也试过。Trae 这类 AI IDE 本身支持自定义技能或自定义 Agent 指令，机制和 Codex 的 SKILL.md 非常像。所以复用方式很直接：把 superpowers 仓库里的技能文件夹拷贝到 Trae 的技能目录，或者通过 Trae 的设置面板手动创建技能粘贴内容。

以 Trae 国内版为例，在设置中找到“技能”或“自定义指令”入口，新建技能时填入技能名称、描述，然后把对应 SKILL.md 正文复制进去即可。我试过把 brainstorm 和 test-driven-development 两个技能导入到 Trae 里，实测它在 IDE 里也能按技能要求先提问再动手。如果你直接使用 Trae 的 CLI 工具，部分版本也支持类似codex install的技能导入命令，但兼容性不如手动粘贴稳定。

4. 核心技能逐项拆解与实操要点

superpowers 不是单一技能，而是十几个技能的集合。我挑几个最常用、最核心的逐项拆解，每一个都告诉你它是干什么的、怎么触发、有什么坑。

4.1 brainstorm：动手编码前的需求澄清

这是我觉得价值最高的一个技能。没有它，Codex 默认遇到一个需求就直接脑补细节然后开工；有了它，Codex 第一个动作是提问。

触发方式很简单，你在会话里直接说：

Use the brainstorm skill to help me design the tag feature.

这个技能会指导 Codex 做几件事：先用自己的话复述需求，确认理解一致；然后针对需求中的模糊地带提问——使用者是谁、边界条件是什么、哪些功能明确不做、有没有性能要求、是否需要兼容旧数据。它甚至会把讨论结果整理成包含用户故事和验收标准的文档。

实操要点：你不需要在第一次提问时就把所有需求说清楚，这恰恰是 brainstorm 的价值——它是“对话式”的。我踩过的坑是，有些开发者装完 superpowers 后还是习惯一口气把所有细节砸给 Codex，结果 Codex 反而不知道从哪里开始。正确姿势是给一个大方向，让它逐步提问，你逐步回答，信息密度更高。

4.2 writing-plans：输出一份可执行的实施计划

brainstorm 讨论清楚了，下一步让 Codex 写计划。这个技能的触发指令类似：

Now use the writing-plans skill to create an implementation plan based on our discussion.

它会输出一份结构完整的 Markdown 计划文档，包含背景与目标、技术方案选型、数据模型设计、接口定义、分步实施任务、测试策略、验收标准、风险与回滚方案。每步任务都会被描述得非常具体，比如“修改 models.py 中 Todo 模型，新增 tags 多对多关系，并新增一条数据库迁移”。

这里有个关键点：计划写完后，你应该要求 Codex 把计划保存成项目里的一个文件，比如docs/plans/tags-feature.md。好处有两个，一是后续会话可以随时引用这份文件，不用把计划重复塞进上下文；二是你可以在文件里直接批注修改，让 Codex 按你的意见调整。

我的经验是，在让 Codex 动手实现前，一定要花五分钟仔细读计划。计划里的技术选型如果不对，改计划只需要几十秒；但你直接让它开写，改代码可能就是几个小时。计划阶段是所有 AI 编码流程里性价比最高的审阅点。

4.3 test-driven-development：让测试驱动开发真正落地

这是 superpowers 里约束力最强的一个技能，也是让代码质量产生质变的关键。触发方式：

Use the test-driven-development skill while implementing the plan.

技能会要求 Codex 严格遵循循环：先写一个会失败的测试，运行确认失败，写最小实现代码让测试通过，运行确认通过，然后重构。并且要求每个逻辑单元都独立提交，提交信息里说明这一步为什么这么做。

实操中你会看到 Codex 的行为明显变化——它不再一口气改十个文件，而是改一个测试、跑一次、改一段实现、再跑一次。这个过程虽然显得“慢”，但每一步都有反馈，出问题立刻知道在哪。

坑也有。最大的坑是，当项目里已有大量没有测试的老代码时，技能可能会要求你为所有老代码补测试，这会非常耗时。我的做法是在计划阶段就明确测试范围，告诉 Codex“只对新增功能写测试，老代码只做回归验证”，技能其实是允许你通过对话调整范围的，关键是你要主动提。

4.4 元技能：writing-skills 与自定义技能

superpowers 里有一类特殊技能，是用来“制造技能”的，这就是 writing-skills。它教 Codex 如何把一个重复性工作流封装成标准技能文件。技能文件的格式如下：

--- name: 技能名称 description: 在什么场景下使用这个技能 --- # 技能说明 这里写具体的操作步骤和规范，使用 Markdown 标题组织内容。

比如你发现团队每次提交代码都要遵循一套特殊的 commit 规范，你可以让 Codex 用 writing-skills 写一个conventional-commits技能，以后每次提交前它会自动按规范生成提交信息。

这个元技能把 superpowers 从“一个工具”变成了“一套工具制造系统”，也是我认为最值得投入时间研究的功能。

4.5 辅助技能：debugging、code-review、security-review 等

除了主线技能，superpowers 还附带了不少辅助技能。debugging 技能引导 Codex 按“复现—定位—修复—验证”的流程来排查问题，而不是瞎猜。code-review 技能让 Codex 以代码评审者的视角审查改动，找逻辑错误、边界问题、可维护性问题。security-review 技能专门扫描安全风险，比如硬编码密钥、注入漏洞、越权访问。我在功能完成后习惯让 Codex 运行一轮 code-review，凭经验说，它能发现不少我自己没注意到的边界错误。

下面这个表是我目前最常用的几个技能及触发场景，方便你快速索引：

5. 完整实操流程：一个功能从想法到落地的全过程

理论讲再多，不如完整走一遍。下面我用一个真实场景演示：给一个已有的 Node.js TODO 应用增加“标签”功能。

5.1 场景设定与准备工作

假设项目已经存在，技术栈是 Express + SQLite，前端是简单的 HTML 页面，没有测试框架。我进入项目目录，启动 Codex CLI。由于项目里没有 AGENTS.md，我先让它读取项目结构，对代码有个基本了解。这一步很重要，Codex 对项目的理解程度直接影响后续计划质量。

5.2 第一步：激活 brainstorm 技能

输入：

Use the brainstorm skill to help me design a tagging feature for this todo app.

Codex 没有立刻打开文件，而是开始提问。它先复述了自己的理解：“你想给每个 todo 添加一个或多个标签，用于分类和筛选”，然后问我几个问题：标签和 todo 是一对多还是多对多；标签需不需要独立管理页面；筛选时是要精确匹配还是模糊搜索；旧的 todo 数据是否需要兼容标签为空的情况。

我逐条回答后，它输出了一份简短的讨论纪要，里面包含用户故事：“作为一个使用者，我可以给 todo 添加多个标签，并按标签筛选 todo 列表。”以及明确列出的“非目标”：暂不做标签管理页面。到这里，第一个环节结束，我对需求的边界已经有了明确共识。

5.3 第二步：生成并评审实施计划

接着输入：

Use the writing-plans skill to create a detailed implementation plan from our brainstorm notes.

Codex 生成了计划文档，核心内容大概是这样：

# 标签功能实施计划 ## 背景 TODO 应用需要支持给每条待办添加多个标签，并支持按标签筛选。 ## 数据模型 - 新增 tags 表：id, name - 新增 todo_tags 关联表：todo_id, tag_id - 每条 todo 可关联 0..n 个标签 ## 接口设计 - POST /api/todos/:id/tags 添加标签 - DELETE /api/todos/:id/tags/:tagId 移除标签 - GET /api/todos?tag=xxx 按标签筛选 ## 实施步骤 1. 创建数据库迁移，新增 tags 和 todo_tags 表 2. 更新数据访问层，支持标签读写 3. 新增标签相关 API 路由 4. 前端增加标签展示和筛选控件 5. 补充接口测试与基础回归测试 ## 验收标准 - 能通过 API 为 todo 添加和移除标签 - 能通过 tag 参数筛选出包含该标签的 todo - 无标签的旧数据访问不受影响

我检查后觉得接口设计合理，唯一修改是把“前端增加标签展示”步骤调整为“先加 API 和测试，前端最后做”，然后让 Codex 更新计划。确认无误后，我要求它把计划保存为docs/plans/tags-feature.md。

5.4 第三步：按 TDD 流程实现

输入：

Use the test-driven-development skill to implement the plan. Start with step 1 and 2.

Codex 开始按计划推进。它先搭建了一个最小测试框架，然后为数据访问层写出测试，运行失败，再实现迁移和查询逻辑，运行通过。整个过程每一步都有输出，我能清楚看到它先写哪个文件、为什么写。中途遇到过一个问题：SQLite 的测试需要清空数据库避免数据污染，Codex 在计划里没有预见到。它没有擅自跳过，而是停下来向我说明情况，并建议在测试初始化时重建内存数据库。我同意后它继续执行。这个细节是我觉得整个流程最像“真人工程师”的时刻——遇到与计划偏差的问题先沟通，而不是闷头硬改。

5.5 第四步：验证、评审并沉淀自定义技能

API 和前端全部完成、测试通过后，我又运行了两次技能：

Use the code-review skill to review all changes. Use the security-review skill to check the new API endpoints.

code-review 帮我发现了一个筛选接口的分页边界问题，security-review 则提示新增接口缺少输入长度校验。修复这两处后，我又让 Codex 用 writing-skills 把这套“新功能开发流程”封装成一个团队技能，以后项目里任何新功能都可以复用这套规范。整个流程下来，功能完成、测试齐备、文档齐全，这是我用 Codex 默认模式很难达到的完成度。

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

用的时间长了，总会遇到各种问题。我把踩过的坑和排查思路整理成速查表，希望能帮你少走弯路。

6.1 排查技能加载问题的通用方法

如果你怀疑某个技能没被加载，最直接的排查方法是让 Codex 自己描述它当前能做什么：“请列出你已经读取的所有技能名称和描述。”如果它列出的技能缺少了你要用的那个，要么是目录没扫到，要么是 SKILL.md 的 frontmatter 写错了。注意技能描述要足够具体，描述写得模糊，模型很难在正确时机触发它。

6.2 上下文管理的经验

superpowers 的技能文件合计起来内容不少，如果全部设为 always-on，Codex 的上下文会被大量占用，留给实际代码的注意力就不够了。我的经验是：坚持“按需激活”原则，只在任务开始时点名需要的技能。长任务做到一半感觉 Codex 反应迟钝，就开一个新会话，把已有的计划文档路径告诉它，让它读取计划后继续，而不是在一个越来越臃肿的会话里硬扛。

6.3 关于技能安全的提醒

最后必须提醒一句：技能文件本质上是可执行的“行为指令”，它可以让 Codex 运行命令、修改文件、甚至执行脚本。所以最好不要从不可信的来源随意安装技能包，安装后也值得花几分钟打开 SKILL.md 读一遍，确认里面没有要求执行可疑操作的指令。用 superpowers 这类开源项目前，先看看它的 issues 和代码质量，这也是一个工程师的基本素养。

我自己在实际使用中最深的体会是：AI 编程工具的上限，从来不只取决于模型多聪明，还取决于你愿不愿意给它一套好流程。superpowers 的价值，不是让 Codex 写出更花哨的代码，而是让每一次编码都变成可控的、可评审的、可复盘的工程行为。装完之后你可能会发现，真正“开挂”的不是 Codex，是你自己——因为你终于有了一套监督和驾驭 AI 的方法。