企业官网建设流程全解析

如果你最近也在折腾 Codex CLI，那多半会刷到superpowers这个名字。我第一次看到它时以为是某种提示词模板，直到把整套技能目录 clone 下来、让 Codex 真正跑了一轮"先写测试再实现功能"之后，我才意识到这不是花架子，而是一套把资深工程师工作方式固化下来的行为规则。简单说，superpowers是一个开源项目，通过一堆结构化的 Markdown 技能文件改变 AI 编程助手的做事流程，而不是让模型变得更聪明。它解决的是"Codex 能写代码但不会干活"的问题，适合所有在用 Codex CLI 做真实项目、又苦于它动不动就把代码改成一坨的人。

1. 先说我为什么需要一个"技能包"：Codex 会写代码，但不会干活

1.1 你让 Codex 改代码时，它到底缺什么

裸 Codex CLI 给我的感觉很像一个脑子转得很快、但完全没受过职业训练的实习生。你让它"给这个函数加个参数"，它能立刻改完；可你让它"重构一下这个模块，保持对外行为不变"，它就开始自由发挥了：删掉测试、顺手改了接口、把另一处调用一起带崩。它不是不聪明，是没有任何稳定的做事方法。正常情况下，一个有经验的工程师接手重构任务，会先弄清楚现有测试在哪、跑一遍基线、列出行为契约、然后才动手。

这些流程不是天赋，是职业习惯。问题在于，模型上下文里塞再多的个人偏好也很难维持这种习惯，因为每轮对话它都在"重新开始"。superpowers想解决的，恰恰是这件事。

1.2 superpowers 不是新模型，而是一套"行为规则"

superpowers在 GitHub 上是一个开源仓库，核心资产是skills目录——里面按主题放了大量SKILL.md文件，比如测试驱动开发、重构、调试、写计划书、代码审查等。每个文件用固定的格式描述"什么时候该用这个技能"和"用的时候按什么步骤做"。Codex CLI 启动时会去扫描这些技能文件，你把任务描述发给它，它根据技能里的description判断该调用哪个技能，然后把对应的 Markdown 内容读进上下文，照着里面的步骤执行。

打个比方：裸 Codex 是你临时拉来救火的外包工程师，superpowers是把那个工程师变成"带着 SOP、工具箱和检查清单的驻场专家"。模型本身没变，变的是一套可复用的工作流程。

1.3 适用人群与成果预期

我觉得下面几类人会从superpowers里得到最大收益：

• 已经在用 Codex CLI / ChatGPT 编程，但对"让它做完整功能"没信心的人；
• 团队希望统一 AI 编程规范，而不是靠每个人在提示词里临时说"你要先写测试"的人；
• 维护 Java、Python、前端等长期项目，需要 AI 在已有代码库里保持行为约束的人。

它不是什么灵丹妙药。装完之后 Codex 不会突然通过图灵测试，但你会明显感觉到它的产出结构变了：先列步骤再动手，先写测试再实现，重构之前会先跑基线。对于一个每天要交给它大量琐事的人来说，这一点变化就已经值回安装成本。

2. 落地第一步：安装 Codex 并让 superpowers 的技能被扫描到

2.1 前置依赖清单

在装superpowers之前，你的机器上得先有这些基础环境：

• Node.js 18 或更高版本。我建议直接用 LTS，避免 Codex CLI 运行时报一些奇怪的版本兼容问题；
• Codex CLI 已经可用。全局安装很简单：npm install -g @openai/codex，装完在终端敲codex --version能输出版本号就行；
• 有效的 OpenAI 账号登录态或 API Key。这部分按 Codex 官方文档执行，登录后它会把凭证存在本地配置里。

这些准备通常十分钟内能搞定。千万别跳过最后一步去调技能配置，否则你会发现 Codex 连基础对话都跑不通，到时候很难判断是配置问题还是登录问题。

2.2 克隆 superpowers 并把 skills 放进 Codex 的读取范围

superpowers仓库本身是个普通 Git 仓库，不需要编译，也不用安装依赖。把它 clone 下来就行：

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

真正有用的东西全在~/superpowers/skills目录里。接下来要做的是让 Codex CLI 在每次启动时认识这个目录。我用的是 Codex 的config.toml文件，通常位于~/.codex/config.toml。在文件里加上类似下面的配置：

# 不同版本字段名可能略有差别，用 codex --help 或文档确认 experimental_extra_skill_roots = [ "~/superpowers/skills", ]

如果你更想把技能固定到某个项目而不是全局生效，也可以在工作目录的.codex/config.toml里写同样的内容。这样这个项目里的 Codex 会话会自动加载这些技能，而其他项目不受影响。

2.3 用 10 分钟做一个最小验证

装完别急着跑大任务，先做一个最小的验证。我常用的验证方式是直接问一句：

codex > 你现在能读取哪些技能？请列举三条与测试驱动开发相关的技能，并说明它们的适用场景。

如果配置生效，Codex 会像模像样地列出技能名称和描述，比如test-driven-development、writing-tests之类。如果它问你"什么是技能"或者表示不清楚，那大概率是技能目录没被扫描到。

这时候逐个排查：config.toml里路径写的是不是绝对路径或~展开；目录层级是否正确——技能根目录下面应该是各个能力簇的子目录，子目录里是SKILL.md，而不是skills目录本身被当成单一技能；Codex 版本是否支持该配置字段。

2.4 我实际习惯的目录组织方式

官方仓库的skills目录很全，但我不会把整套都塞进每个项目。我的习惯是建一个"基础技能 + 项目专属技能"的组合：

~/skills/ base/ # 稳定通用的技能，长期不变 java-projects/ # 只在 Java 项目里才需要加载 docs/ # 写作和评审类技能

然后在项目的.codex/config.toml里只引用base和java-projects，避免让 Codex 每次都要扫描一大堆无关技能，既省 token，也降低选错技能的概率。

3. 拆开内核：SKILL.md 技能文件是如何被 Codex 读到的

3.1 一个最简 SKILL.md 的结构

SKILL.md是超能力体系的细胞。它的结构非常克制，核心就两部分：YAML 开头的元信息，加上正文的 Markdown 步骤。我摘一个简化到极致的例子：

--- name: test-driven-development description: 当用户要求实现一个新功能或修复一个已有代码的 bug，并且该项目包含可运行的测试环境时，使用此技能。核心流程是红灯、绿灯、重构。 --- # 测试驱动开发 1. 明确测试入口。先找到项目的测试框架配置，确认如何运行单个测试文件。 2. 写一个会失败的测试，描述期望行为。确保失败原因是我们预期的，而不是环境错误。 3. 运行测试，确认红灯。 4. 用最小代码改动让测试通过，确认绿灯。 5. 重构。在不改变行为的前提下清理实现，并再次运行全部测试。

这个文件被 Codex 读到之后，等于把一个完整的工作 SOP 放在了模型的上下文里。它不再凭空猜测"什么叫先写测试"，而是照着清单一步步执行。

3.2 目录树与 description：为什么描述写得差，技能就废了

superpowers的目录结构不是平铺的，通常按能力簇分目录：

skills/ testing/ test-driven-development/ SKILL.md writing-tests/ SKILL.md refactoring/ safe-refactoring/ SKILL.md

Codex 不可能把每个技能文件都完整读进上下文，模型会先扫一遍所有技能的name和description，形成一个"技能清单索引"。真正决定它在某个任务里会不会使用某个技能的，就是那两句description。

我见过很多自定义技能失效的案例，原因都是description写得太泛。比如写"用于代码质量改进"，那碰到重构任务时，模型可能同时匹配到五个技能，最后随机选一个；写得太窄比如"仅当用户提到 JUnit 5 且使用 Maven 时才使用"，那模型基本永远不会主动用。好的description应该像一条精确的检索语句，既覆盖触发场景，也排除相似场景。

3.3 技能之间可以互相调用

superpowers另一个值得学习的设计是技能可以引用技能。test-driven-development技能里可以写一句"如果需要编写测试用例，参考writing-tests技能"，这样 Codex 在执行 TDD 流程时会自动去把测试相关的技能也加载进来。这种嵌套让技能不用重复造轮子，也让整套体系能组合出非常复杂的行为。

对你的启发是：不要试图写一个几千行的大技能涵盖所有场景，拆成小技能、互相引用、按需加载，模型用起来反而更稳定。

4. 实跑一轮：用 superpowers 驱动 Codex 完成"先测试后实现"

4.1 任务设计与提示词写法

看再多原理都不如实际跑一轮。我挑一个非常典型的任务给你演示：给一个 Python 项目新增一个"统计文本单词频次并按频次排序"的函数，并且要求全程走 TDD。

提示词我一般会这么写：

使用 test-driven-development 技能，为分析模块新增一个函数： 输入一段英文文本，返回按出现次数降序排列的单词频次列表。 项目测试框架是 pytest，测试目录在 tests/analysis/ 下。 请先确认测试运行方式，再开始。

注意几个细节。第一，我明确点名了使用的技能名，而不是只描述需求，这能显著降低技能匹配的随机性；第二，我把测试框架和测试目录告诉它，省得它自己猜测；第三，我要求"先确认测试运行方式再开始"，相当于给了它一个启动步骤，避免它跳进代码里就开始瞎写。

4.2 真实工作流的交付形态

接下来 Codex 的工作流程大致是这样：

1. 读取项目结构，定位到tests/analysis/，查看已有测试风格；
2. 加载test-driven-development技能，输出执行计划；
3. 先写一个失败的测试，比如把空字符串传进去，断言返回空列表；
4. 运行pytest，确认红灯；
5. 实现函数，再次运行测试，确认绿灯；
6. 条件允许时，再扫一遍代码做简化。

如果你熟悉 TDD，会发现这完全就是一个人类工程师的做事顺序。区别只在于，这套顺序不是你在一大段提示词里苦口婆心交代的，而是技能文件自动给的。我在实际操作中最直观的感受是：之前让 Codex 写功能，我要盯着它每一步说了什么；现在我可以让它一口气做到测试全绿，再集中做代码审查。

4.3 为什么它比裸 Codex 靠谱

裸 Codex 在处理这类任务时常犯的毛病是：先写实现，顺手补一个"看起来很对"的测试，而那个测试甚至根本没跑过。superpowers的意义不在于让模型变得更聪明，而在于强制它先建立可验证的基线，再做改动。

这背后的逻辑很简单：模型生成的代码是否正确的唯一可信证据，是测试真的跑绿了。没有这条约束，模型的"自信"越高，破坏力越大。技能包做的事情，就是把"跑测试"从"可选项"变成"步骤清单上的硬性要求"。我个人认为，这是它最有价值的地方。

5. Java 项目及其他入口：superpowers 的通用化适配

5.1 Java 世界也能用：语言无关但案例偏 Python，需要自己补

很多人会问superpowers java这种问题，担心这套技能是不是只服务 Python 项目。答案是否定的。技能文件里写的是自然语言命令和通用工程步骤，跟具体语言无关——"先写测试再实现"放哪个语言都成立。但实操中你会发现，仓库里默认技能给出的示例、命令、路径大多以 Python/JS 为主，Java 项目直接套用会卡在细节上。

最典型的问题是构建工具。Python 项目用pytest，Java 项目可能是 Maven 的mvn test，也可能是 Gradle 的./gradlew test。如果技能里只写了pytest tests/，Codex 在 Java 项目里就不知道该怎么跑测试。解决办法是自定义配套技能，把项目自己的构建命令写清楚。

5.2 写一个 Java 专属技能的骨架

我在 Java 项目里维护过一个极简的构建测试技能，供参考：

--- name: java-maven-test-flow description: 当项目使用 Maven 且需要运行或编写 Java 测试时使用。识别常见的 Maven 生命周期，确保测试命令正确。 --- # Java Maven 测试流程 1. 确认存在 pom.xml，检查 test 目录位置，默认 src/test/java。 2. 先运行 `mvn -q test -DskipITs` 确认基线状态。 3. 编写 JUnit 测试，新测试类放在对应包路径下。 4. 只运行单个测试类：`mvn -q test -Dtest=ClassName#method`。 5. 全部通过后，运行 `mvn -q verify` 做完整校验。

把它放到项目的技能目录后，Codex 在 Java 项目里的行为就会立刻规范起来。这个思路可以复制到 Spring 项目、Android 项目、多模块仓库，本质上就是把你团队里"老手才知道的那些命令"沉淀成技能。

5.3 把同一份技能接到更多工具入口

还有人问"某个基于 Codex 的图形工具/工作台怎么用 superpowers"。答案比想象中简单：只要那个工具的底层是 Codex CLI，并且允许你指定配置或工作目录，它就会读取同一个config.toml和同一份技能目录。你在终端里配好的技能，在那些入口里同样生效。

所以我的建议是：把技能库当成一个独立资产来维护，而不是绑死在某个终端上。你可以把它放进 Git 仓库，在团队里共享；也可以在不同的机器上同步同一份配置。凡是能调用 Codex CLI 的地方，superpowers都能成为它的行为底座。

6. 用了大半年，我踩过的和预见到的坑

6.1 Codex 版本迭代与配置字段漂移

Codex CLI 更新很快，config.toml里的技能相关字段在不同版本间改过名，我之前配置时用的是一个带experimental_前缀的字段，后来升级版本后字段变化，技能就静默失效了。最坑的是它不会报错，只是不再扫描技能目录。

排查方式很简单：升级 Codex 后，先跑一次"你能读取哪些技能"的验证；如果失效，用codex --help或官方文档重新确认字段名。别省这一步，我在这个坑上浪费过一个下午。

6.2 技能太多会稀释匹配精度

技能不是越多越好。一次加载 30 个技能，Codex 在匹配时很容易选错，甚至把多个技能步骤混在一起执行。我后来只保留一个基础技能目录，外加按项目划分的专属技能目录。数量控制在 10 个以内，匹配稳定性明显提升。

另外，description要定期维护。如果你发现某个技能从来没被触发过，大概率不是模型不行，而是描述写得不够精确。反过来，如果某个技能的触发频率异常地高，也要怀疑它是不是描述得太宽，抢走了其他技能的活。

6.3 权限与安全边界

superpowers的技能体系会让 Codex 更主动地执行终端命令、读写文件。这本是好事，但也意味着一旦技能写得不好，模型可能在错误的时间做了危险操作。比如一个技能里写了"运行项目的清理命令"，它可能会把产物目录删掉；如果技能里写了"修复所有 lint 错误"，它可能顺手改动几十个文件。

我的原则是：技能正文里涉及破坏性命令时，必须加上"先确认没有未提交变更"之类的条件；涉及文件批量修改时，要求它先输出改动计划再执行。不要相信模型会自动克制，要靠流程约束。

6.4 把技能当成项目规范来维护

用superpowers半年后，我的心态发生了变化：它不再只是一个提升 Codex 效率的工具，更像一个项目规范的载体。团队的编码约束、提交信息格式、测试要求、发布检查清单，全都可以写成技能文件，让 AI 和新人共用同一套标准。

每次踩到一个值得记录的坑，我都会反问自己：这个坑能不能通过加一条技能步骤来避免？如果可以，就写进技能文件。这么做有一个额外的好处：技能库的 Git 历史就是团队工程文化演进的日志，比什么文档都有说服力。

我个人现在维护着三份技能目录：一份基础通用技能，一份 Java 项目技能，一份文档撰写技能。每次新项目加入，第一件事就是 clone 技能库并配置好路径，然后才让 Codex 开始干活。这个习惯帮我省下了大量重复解释的精力，也让 AI 编程从"看运气"慢慢变成了"走流程"。如果你打算入坑，我的建议是先从三五个技能开始小步验证，等摸清了匹配逻辑和 token 消耗，再逐步扩充你自己的技能库。