企业官网建设流程全解析

“superpowers”这个词最近在 AI 编程圈子的热度很高，我最初是从 Codex 相关的讨论里看到它的——一个叫 Superpowers 的开源项目，专门给 Codex CLI 加装“技能”（skills）系统。简单说，它解决的是 AI 编程助手“什么都会一点，但什么都不精”的问题：默认的 Codex 更像一个有求必应的实习生，而装上 Superpowers 之后，它更像一个带项目规范和最佳实践的老师傅。这篇文章我会从安装、原理、实际工作流和踩坑记录四个角度，把 Superpowers 的使用指南从头到尾捋一遍，适合正在用 Codex 写代码、但觉得默认输出质量不稳定的人参考。

1. Superpowers 是什么：给 Codex 装上一套“技能书架”

1.1 我为什么要折腾这个项目

先说背景。我大概从 Codex CLI 早期版本就开始用了，最初的体验是“惊艳”，但用久了会暴露一个很尴尬的问题：同一个任务，今天问它可能给你一套思路清晰的方案，明天换个说法问，输出的质量就忽上忽下。尤其是在“按规范写测试、按团队约定做提交、排查复杂 bug”这些需要固定流程的场景里，默认行为的随机性让人很头疼。

后来在 GitHub 上看到 obra 的 Superpowers 项目，思路一下就戳中我了：它没有去改 Codex 的底层模型，而是在 Codex 外面加了一层“技能”系统。说白了，就是用一批结构化的 Markdown 文档，把那些“老师傅会按规矩做的事”提前写好，让 AI 在处理对应任务时先读这些文档，再动手。因为 Codex 本身支持读取外部文件作为上下文，这套方案实现起来轻巧，也不依赖特定模型版本，官方仓库更新也比较勤。

1.2 技能（Skill）与普通提示词的本质区别

可能有人会说，这不就是“把提示词存成文件”吗？一开始我也是这么想的，实际用了才发现区别很大。

普通提示词是一段一次性的话，你塞给 AI 之后它用完就忘了，下次还得重新组织语言。技能则是一个有结构、有触发条件、有执行步骤的系统。一个技能文件通常包含：这个技能是干什么的（name/description）、什么时候该用（trigger）、具体怎么做（步骤清单）、以及一些“不要做”的边界约定。Codex 接到的不是一个模糊的“帮我写测试”，而是一套完整的行为规范：先看需求、再列测试用例、先写失败用例、再实现、最后重构。

另一个关键点是技能可以组合。Superpowers 里可以同时加载多个技能，AI 会在处理复杂任务时“查阅”相关的几篇，按次序执行。这就像你给实习生配了一本《项目开发手册》，而不是一句“你看着办”。

1.3 它的适用范围与限制

先说适用范围：只要是 Codex CLI 支持的开发场景，基本都能用——写新功能、补测试、改 bug、重构、写提交信息、查文档、甚至一些重复性的运维操作都可以。语言方面没有限制，官方技能库里有不少是语言无关的，Java、Python、JavaScript 项目我都实际跑过。

限制也要说清楚：Superpowers 不是魔法，它不能凭空提高模型的能力上限。它的价值在于把“稳定可靠的执行流程”固定下来，减少随机性。如果模型本身推理就是错的，技能也救不回来。另外，技能文件写得越具体、越贴近你的真实项目，效果越好；直接用别人的通用技能，体验会打个折扣——这一点在后面讲自定义技能时会展开。

2. 安装 Superpowers：一次干净的从零配置

2.1 前置环境准备

我以 macOS + Codex CLI 的环境为例，Windows 和 Linux 的差异后面单独说。需要准备的东西其实很少：

• Codex CLI 已经装好并能正常使用（codex命令能跑起来）
• Git（用来拉取仓库）
• 一个顺手用的终端

不需要额外安装 Node、Python 之类的运行时，这一点和很多命令行工具不太一样，因为 Superpowers 本质上就是一个“Markdown 文档 + 少量胶水脚本”的集合，不依赖特定语言运行时，这对 Java 开发者来说尤其省心。

2.2 安装主程序与技能库

我当时的做法是直接把仓库克隆到用户目录下，方便统一管理：

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

克隆完之后，目录里会看到skills文件夹、plugins文件夹，以及一堆文档。skills里就是一个个技能文件，plugins里则是更复杂一点的插件包，本质上是技能的集合，可以整体安装和卸载。

官方通常还提供一个初始化脚本，用来把技能目录和你本地的 Codex 配置关联起来。如果你不想跑脚本，也可以手动处理，方法见下一节。两种方式选一种就行，我推荐第一次先跑官方脚本，跑通了再改成手动配置，方便理解原理。

2.3 让 Codex 识别技能目录

这里有一个很关键的点：默认情况下，Codex 并不知道 Superpowers 的存在。它之所以能使用技能，是因为你在 Codex 的配置里让它“看到一个技能说明书”，说明书里写明了技能放在哪里、什么时候需要去翻。

具体来说，Superpowers 提供一个引导插件（bootstrap plugin），你要确保 Codex 在启动时会加载到这个插件。不同版本 Codex 的配置位置不太一样，有些在~/.codex/config.toml，有些通过项目内的AGENTS.md来声明，建议以你当前 Codex 版本的文档为准，官方 README 里通常有对应的配置片段可以抄。

配置完成之后，可以直接问 Codex 一句：“你的技能库里有哪些技能？”如果它列出了一堆技能名，说明加载成功了；如果它一脸茫然，说明引导插件没生效，去检查配置路径，我见过的大部分安装失败案例都是卡在这一步。

2.4 Java 开发环境的额外配置

搜“superpowers java”的朋友应该不少，我单独说下 Java 场景。

Superpowers 本身的技能和语言无关，真正要处理的是 Codex 在 Java 项目里的“上下文感知”问题。我的建议是三件事：

第一，在项目根目录放一个AGENTS.md（或者 Codex 支持的等价说明文件），把构建工具（Maven 还是 Gradle）、JDK 版本、测试框架（JUnit 5 还是 TestNG）、包结构约定写清楚。这样 AI 在调用技能时，能结合项目实际情况执行，而不是套用泛泛的步骤。

第二，如果团队有固定规范，比如“接口必须先写 Controller 再写 Service”、或者“所有 public 方法必须有 javadoc”，把它写成一个自定义技能文件，放进技能目录。这一步我后面会详细演示。

第三，Java 项目的编译反馈比较慢，用 Superpowers 跑 TDD 流程时，建议把“运行测试的命令”明确告诉 AI（比如mvn test -Dtest=xxx），避免它默认猜一个不存在的命令，否则你会在“等它跑完一次错误命令”上浪费大量时间。

3. 核心机制拆解：一个技能文件是如何被 AI 执行的

3.1 技能文件的结构

先看一个典型的技能文件长什么样。以“测试驱动开发”技能为例，它的 Markdown 大致骨架是：

# 测试驱动开发（TDD） ## Description 在开始编写实现代码之前，先编写失败的测试用例，然后逐步实现并保持测试通过。 ## When to use - 用户明确要求进行 TDD - 新功能需要保证可测试性 - 修复 bug 时希望先有回归测试 ## Steps 1. 理解需求，列出关键行为 2. 为每个行为编写一个失败的测试用例 3. 运行测试，确认用例失败且失败原因符合预期 4. 编写最小实现，让测试通过 5. 运行全部测试，确认无回归 6. 重构，并保证测试始终通过 ## Boundaries - 不要一次性写大量测试而不实现 - 不要跳过失败验证步骤 - 不要改动与本次需求无关的代码

你没看错，就是这么朴素。关键是 Description 和 When to use 这两段——Codex 靠它们来判断“当前任务要不要调用这个技能”。Steps 是给 AI 的执行指南，Boundaries 则是约束它别乱来。写技能文件的人如果在这两部分偷懒，那这个技能基本就等于没有。

3.2 技能的调用与选择逻辑

理解技能调用逻辑，是能不能用好 Superpowers 的分水岭。

当你在 Codex 里提出一个任务时，Codex 会结合当前对话上下文和技能库目录里的文件，判断哪些技能和当前任务相关。如果匹配，它会主动去读取对应的技能文件内容，然后按照里面的步骤来执行。这意味着技能文件本身需要写得“可被检索”——描述里要包含用户可能使用的关键词，触发条件要明确。

这里有个实用的技巧：技能文件不要写“万能式”的废话，而是要写清楚触发条件。比如“当用户提到测试”这种触发条件太宽泛，会导致 AI 频繁调用技能、做事拖沓；改成“当用户明确要求先写测试，或者任务涉及修复回归 bug”就会精准很多。

还有一个常见的误区：以为技能文件里写的内容会被 AI“记住”。实际上，技能文件的加载是基于对话上下文的，每次会话开始时 AI 并不会自动把所有技能都读一遍，而是按需读取。所以技能文件不能太长，否则 AI 在读到的时候会消耗大量上下文，影响后续执行质量。控制在 50 行以内、步骤清晰是最舒服的，我自己写技能时也遵循这个原则。

3.3 自己动手写一个简单技能

教大家写一个实用的小技能。拿我团队的情况举例：我们有个约定，所有提交信息必须遵循 Conventional Commits 规范。默认 Codex 生成的提交信息太随意，我就写了一个“提交信息助手”技能：

# 规范提交信息生成 ## Description 按照 Conventional Commits 规范生成 git 提交信息。 ## When to use - 用户要求生成提交信息或 commit message - 用户执行 git commit 前需要建议 ## Steps 1. 查看 git status 和 git diff --stat，了解改动范围 2. 判断本次改动的类型：feat / fix / refactor / docs / test / chore 3. 主题行不超过 50 个字符，动词用现在时 4. 正文说明改动原因和影响，不要列举代码细节 5. 如果关联了需求编号，在 footer 中注明 ## Boundaries - 不要把多个不相关的改动合并到一条提交信息里 - 不要写“update code”这种无信息量的主题

把文件保存为skills/commit-message.md，然后重新打开 Codex。实测下来，从那以后它生成的提交信息几乎不用改。这个例子也说明了一件事：Superpowers 最有价值的地方，不是官方那几十个内置技能，而是你在实际项目中沉淀出的“项目专属技能”——这正是它在搜索引擎里被频繁搜“使用教程”却很少被讲透的部分。

4. 实战工作流：把 Superpowers 真正用进日常开发

4.1 TDD 流程：先写失败测试，再让 Codex 补实现

装好 Superpowers 之后，我第一个改造的流程就是 TDD。

以前的流程是：“帮我写一个用户注册接口”，然后 Codex 直接给你甩一堆代码，里面可能带着测试，也可能没有，质量全看运气。现在的流程是：我在需求里明确说“用 TDD 技能来实现”，Codex 会自动加载 TDD 技能文件，然后一步一步来：先列行为用例，再写失败测试，运行测试确认失败，写最小实现，再跑全量测试。

这个过程最爽的一点是，AI 的行为可预测了。它不是“一股脑完成需求”，而是“按规范一步步推进”。实测下来，测试覆盖率和代码质量都稳定了很多，尤其适合对工程质量有要求的团队。如果你在用 Java 写业务代码，这个流程的价值会更明显，因为 Java 项目更容易出现“写完不测直接交付”的情况，有了 TDD 技能等于给 Codex 上了一道保险。

有一个细节值得单独提醒：TDD 技能默认假设你能快速运行测试。如果你的项目测试跑得慢（比如大型 Java 单体应用），建议在技能文件里加一条“运行单测时只跑相关模块，命令是 xxx”，否则 AI 可能会傻乎乎地跑全量测试，一次五分钟，效率全没了。

4.2 调试场景：从“看代码”到“做实验”

另一个我常用的场景是调试。默认情况下，Codex 遇到 bug 倾向于“盯着代码看”，然后凭感觉给出一个修复方案。这种方式对简单问题有效，但对复杂问题经常翻车。

Superpowers 的调试类技能会改变这个行为：先让你复现问题，再缩小范围，通过二分法定位，每一步都基于观察而不是猜测。比如遇到一个偶发崩溃，AI 会先问你要日志、要复现步骤，然后建议在关键位置加日志，逐步缩小排查范围。整个流程非常像一位有经验的工程师，而不是一个瞎猜的实习生。

这里我踩过一个坑：如果技能文件里写着“查看日志”，而你的项目日志分散在多台机器上，AI 会卡住不知道去哪看。我的解决方案是在项目级说明文件里补上“日志统一输出到 /var/log/app 目录，先看 error.log”。说白了，技能提供流程，而项目说明提供环境上下文，两者配合才有完整效果——这也是我在 2.4 节强调 Java 项目要放 AGENTS.md 的原因。

4.3 团队协作中的用法

Superpowers 也很适合团队协作。你可以把整个~/.superpowers目录（或者其中的skills文件夹）纳入版本管理，或者把自定义技能放到团队仓库的某个目录里，让大家通过相同的初始化脚本统一安装。

这样带来的好处很直接：团队的开发规范不再是“墙上贴着的文档”，而是会真实影响 Codex 行为的规则。新同事加入时，只需要跑一遍安装脚本，就获得了和团队一致的 AI 协作体验，不会再出现“AI 生成的代码和团队规范不一致”的问题。我见过不少团队辛辛苦苦写了厚厚一本开发规范，结果 AI 助手完全不知道，代码风格照样乱飞，Superpowers 恰好把这块补上了。

我个人的建议是：通用的官方技能保持默认，团队内部的规范技能一定要自己维护。因为这些技能是你们项目特有的知识沉淀，也是 Superpowers 性价比最高的部分——别人用公共技能只能做到 70 分，你们用自己沉淀的技能能做到 95 分。

5. 踩坑记录与排查思路

5.1 技能加载不生效

先说最常见的坑：配置完了，Codex 依然不理技能。我的排查思路是这样的（按顺序执行）：

第一步，确认技能文件在正确目录。检查~/.superpowers/skills/下有没有对应的.md文件，文件名和内容格式是否正确。很多人把文件放错了层级，放在skills/skills/里，自然加载不到。

第二步，确认引导插件加载成功。重启 Codex，问一句“你可以使用哪些技能”，如果回答不出来，说明引导插件没有进入对话上下文。去看 Codex 的配置文件和 AGENTS.md，确认指向 skills 目录的路径没写错。我印象里最深的一次折腾，是花了一晚上发现配置里路径少写了一个s。这种问题没有捷径，就是按步骤排查。

第三步，检查版本兼容性。Superpowers 迭代速度不算慢，Codex 的配置格式也在变，如果升级了 Codex 之后技能突然失效，大概率是格式不兼容，去项目仓库看看有没有针对新版 Codex 的更新说明。我遇到过两次，都是升级 Codex 后技能不工作了，去仓库看一眼 issue 就找到了解决办法。

5.2 与不同语言/框架的兼容问题

虽然技能是语言无关的，但实际用起来，不同语言项目的“体质”差异还是会带来一些摩擦。

比如 Python 项目，测试运行器可能是 pytest，代码风格是 PEP8；Java 项目可能用 Maven 或 Gradle，有 Checkstyle 检查；前端项目又有 ESLint 和 TypeScript 编译这一层。如果你的技能文件里写的是泛泛的“运行测试”四个字，AI 大概率会猜一个命令，猜错率不低。

解决办法很简单：在技能文件的 Steps 里写清楚当前项目的具体命令，或者在项目里维护一个“AI 工作手册”（AGENTS.md），把这些信息集中放好。我见过的很多问题，本质上不是 Superpowers 的问题，而是“AI 缺少项目上下文”的问题。这也是为什么我一直强调：别把技能当成万能药，它需要和项目级配置配合使用。

5.3 一些个人建议

最后说几点经验。

第一，刚开始不要贪多。先装官方核心技能，用熟了再逐步加，一次装太多技能，AI 选择困难，反而降低效率。我从三个技能起步，用了两周才逐步扩展到十几个。

第二，技能要持续迭代。每次发现 AI 在某类任务上表现不稳定，都可以去反思：是不是技能文件描述不够具体？触发条件太宽？还是漏了边界约束？把反思沉淀回技能文件，就是这项工具最大的价值——它其实是一个不断变好的过程，而不是装完就完事的一次性配置。

第三，不要把全部希望都寄托在技能上。Superpowers 提升的是 AI 行为的稳定性和规范性，不是模型的推理能力。遇到反直觉的复杂问题，该人工介入就人工介入，技能文件只能约束流程，不能替代人的判断。

我现在的习惯是每周花十几分钟维护一遍技能文件——根据这周的使用情况，调整触发条件、补充新的边界说明、删掉不常用的技能。这个项目解决的不是“让 AI 更聪明”的问题，而是“让 AI 每次用同样的方式把事情做对”的问题。如果你也在用 Codex，又受够了输出质量的随机性，花一个下午把 Superpowers 装上，折腾完你大概率会觉得这半天值。