企业官网建设流程全解析

如果你现在打开 Codex CLI，直接丢一句“帮我把这个支付模块重构成策略模式”，它能干，但大概率干完你还得自己重写一遍——因为它不知道你项目里有哪些约定，不理解你说的“重构底线”是什么，也没有“先补测试再动手”的肌肉记忆。这就是我最近半年重度使用 AI 编码代理后最真实的感受：模型很聪明，但默认状态下它就是个“聪明但失忆的实习生”。

所以当我在 GitHub 上看到 superpowers 这个项目，并且发现它的核心思路是“给 Codex 注入可复用的技能文件”时，我几乎是一瞬间就理解了它为什么能火。简单说，superpowers 是一套面向 Codex CLI 的开源技能框架，它把 TDD、代码评审、复盘、文档编写这些研发实践，编码成一个个 Markdown 格式的“技能包”，让 Codex 在动手之前先读技能、再按方法论执行。这篇内容就围绕 superpowers 的使用指南、安装方式、核心机制和自定义技能展开，适合正在用 Codex 写代码、但觉得 AI 输出“差点意思”的开发者，也适合想给团队 AI 协作流程立规矩的工程负责人。

1. superpowers 是什么：一个给 Codex CLI 注入“肌肉记忆”的技能框架

1.1 裸 Codex 的痛点：聪明但失忆的实习生

先说一个我自己的例子。有一段时间我每天用 Codex CLI 修小 bug，指令写得很清楚：“改这个函数、保持接口不变、补上错误处理”。Codex 每次都能改，但它从不主动问我“这个函数被哪些地方调用了”“错误处理的项目规范是什么”，更不会自觉补一个回归测试。结果就是：单看 diff 没什么大问题，但合并进去之后，下一次迭代立刻感受到技术债在堆积。

这不是模型能力不行，而是使用方式出了问题。Codex 默认是一个无状态的对话代理，你给它一个任务，它就从当前聊天的上下文里猜你的意图。你项目里沉淀的代码规范、测试策略、重构边界、评审清单，它一概不知。你可以把这些写成一大段 prompt 塞给它，但 prompt 会随着对话变长而稀释，而且每次新会话都要重新灌输一遍。

superpowers 解决的就是这个问题。它的核心思路特别朴素：把“有经验的工程师在动手前会做的那套动作”固化下来，变成 Codex 每次开工前都必须阅读的 Markdown 文件。这些文件被称作技能（skill），存放在项目的src/skills目录下，Codex 启动工作流时会先读技能、再干活，从根上改变“上来就写代码”的坏习惯。

1.2 superpowers 的解法：把方法论变成可复用的技能文件

superpowers 的作者是 Jesse Vincent，这人在 Perl 社区和自动化测试领域很有名。他做这个项目的出发点很直白：他不想每次都跟 Codex 重复解释“我们团队怎么做代码评审”“我们定义什么样的功能算完成”，而是想让 Codex 像一个入职三年的老员工，自己知道该按什么流程做事。

具体实现上，superpowers 被组织成一个 npm 包，你可以在项目里执行npx --yes superpowers@latest init把它装进项目。装完之后，项目下会出现src/skills目录，里面有一堆SKILL.md文件，每个文件就是一个技能。Codex 在处理任务前，先读相关技能文件，按里面的步骤和约束执行。

这套设计的高明之处在于：技能文件不是代码，而是纯文本的 Markdown，任何人都能读、能改、能写。你不需要会 Rust 或者学一套 DSL，只需要用自然语言把“怎么做一件事”的步骤写清楚，Codex 就能照着执行。这意味着技能库是活的，团队完全可以根据自己的工程实践沉淀独有的技能，而不是被工具厂商绑死。

1.3 适用人群与含金量判断

什么人适合用 superpowers？我觉得分三类。第一类是已经在用 Codex 写生产代码的开发者，你对 AI 输出质量不满意，但又说不出到底哪里不对，那 superpowers 能帮你把“质量预期”显式化。第二类是技术负责人，你希望团队里所有人都用同一套 AI 协作规范，而不是十个人有十种 prompt 风格，把技能文件放进仓库就能做到统一。第三类是搞工具链研究的工程师，你会对“怎么把工程方法论编码给 AI 执行”这个话题本身感兴趣。

不过我也要泼一盆冷水：superpowers 不是银弹，它不会让 Codex 突然拥有更强的推理能力。它的本质是行为约束和上下文注入，深度还是模型本身的深度。但同等模型条件下，有技能约束和没技能约束的输出质量差距，我用下来的感受是至少差一个档次。

2. 安装与初始化：5 分钟让 Codex 拥有技能库

2.1 前置环境准备

在开始安装之前，先确认环境是否满足条件。superpowers 是围绕 Codex CLI 设计的，所以第一步是装好 Codex CLI 并确保能正常对话。Codex CLI 的安装通常通过 npm 完成，安装后你要有可用的 API 密钥或认证方式，因为后续所有技能调用都发生在和 Codex 的会话里。

Node 版本方面，建议用 Node 18 以上，npm 版本别太旧。我自己在 Node 20 环境里跑得很稳。这里有一点容易踩坑：如果你之前装过旧版 Codex CLI，最好先确认版本是新的，因为 superpowers 的初始化脚本会调用 Codex 的某些配置能力，版本太老会出现技能文件写进去了但 Codex 不读取的诡异问题。

另外，建议在 git 仓库里操作。superpowers 初始化会在项目里生成src/skills目录并改动配置文件，这些改动最好通过 git 来追踪。如果你直接在一个已存在的生产项目里初始化，我建议先建分支再做，方便不满意就回滚。

2.2 安装 superpowers 的三种方式

第一种，也是最推荐的方式，直接用 npx 初始化：

npx --yes superpowers@latest init

执行后，脚本会检查当前目录，然后创建或更新src/skills目录，并写入默认技能包。命令跑完后你会发现多了几十个SKILL.md文件，包括 boot、docs、review、test-driven-development、refactoring、post-mortem 等。

第二种方式是全局安装 npm 包，适合你在多个项目里都要用的情况：

npm install -g superpowers superpowers init

第三种方式是把 superpowers 作为 git submodule 引入，适合团队统一维护技能库的场景。这种方式的好处是技能文件可以随项目仓库一起评审、迭代，坏处是更新起来比较麻烦，需要手动拉取子模块。我个人体验是：单人开发用第一种方式最省事，团队协作用第三种方式更规范。

2.3 初始化项目并验证技能生效

初始化完成后，最关键的一步是让 Codex 真的“看到”技能。superpowers 的设计里，Codex 默认不会主动读技能，需要你在会话中给出指令。最常见的启动方式是在新对话开头说一句话，比如：

请先阅读 src/skills 下的相关技能，然后按技能要求处理下面的任务：修复登录接口的超时问题。

Codex 在接下来的会话里会先读取src/skills目录里和任务相关的SKILL.md，比如test-driven-development或coding-agent，然后按照里面写的步骤来执行任务。

验证是否生效有个小技巧：你故意不提任何要求，只让 Codex “开始处理这个 bug”，如果它能主动问你要复现步骤、要相关测试、要先写失败用例，说明技能已经被正确加载了。如果它的行为和没装技能前一模一样，那就要检查技能文件路径和调用指令是否写对了。

提示：不要在初始化后直接问 Codex “你有哪些技能”，因为它不一定能完整列出。更可靠的方式是打开src/skills目录自己看文件列表。

3. 核心机制深度拆解：技能如何改变 Codex 的行为

3.1 SKILL.md 文件规范：frontmatter + 步骤化内容

理解 superpowers 的核心，就是理解SKILL.md文件格式。每个技能文件都是一个 Markdown 文档，最顶部是 YAML frontmatter，包含技能名称、描述和触发条件，后面才是正文。下面是一份标准技能文件的骨架：

--- name: test-driven-development description: 在实现任何功能之前，先编写失败的测试用例并确认其失败原因 --- # TDD 技能 ## 使用场景 - 新增功能 - 修复 bug - 重构代码 ## 执行步骤 1. 编写一个预期失败的测试用例 2. 运行测试并确认失败原因符合预期 3. 编写最小实现代码 4. 运行测试并确认通过 5. 重构并保持测试持续通过

注意看这里的关键设计：技能文件描述的不是模型能力，而是行为规范。Codex 读到这个文件后，会按照步骤 1 到 5 依次执行，而不是凭自己的“习惯”自由发挥。你完全可以把团队内部的编码规范、提交信息格式、接口设计约定写进SKILL.md，让 Codex 每次开工前都先复习一遍。

还有一点值得注意：技能文件里的描述越具体，Codex 执行得越准。比如“编写测试”这种描述是模糊的，“使用 pytest 编写测试，测试文件放在 tests/ 目录，覆盖正常路径和异常路径”这种描述才能稳定产出。这也是我用了一段时间后觉得最应该优化的方向——不是技能越多越好，而是每条技能的指令颗粒度是否够细。

3.2 子代理模式：让多个 Codex 并行协作

superpowers 里另一个很有想象力的机制是子代理（subagents）。它允许你在一次 Codex 会话里，让模型扮演多个角色并行推进任务。听起来很玄，实际实现也不复杂：你把一个任务拆解成多个子任务，每个子任务对应一段独立的对话上下文，Codex 在子代理之间切换时，各自保持各自的进度和信息。

举个具体例子。假设我要重构一个订单模块，我会让 Codex 同时开三个子代理：一个负责分析现有代码、画出依赖关系；一个负责编写迁移方案；一个负责补测试。三个代理互不干扰，最后我把三份结果合并起来做最终决策。这个模式解决了一个此前很头疼的问题：Codex 在长对话里会逐渐丢失早期上下文，而子代理相当于给每个任务开了独立的“窗口”，有效避免上下文污染。

不过子代理模式也有使用门槛。它需要你在技能文件里明确写出“什么时候该创建子代理”“子代理之间如何交接”，否则 Codex 会陷入选择困难。我在实践中发现，写出清晰的子代理分工比让 Codex 自己决定分工可靠得多。也就是说，子代理机制本身不是魔法，真正起作用的是你定义的组织方式。

3.3 内置技能库地图：从 boot 到 post-mortem

初始化 superpowers 之后，你会得到一套默认技能，我建议先通读一遍。下面是我实际用下来觉得最有价值的几个技能，以及它们各自解决什么问题：

拿boot来说，这个技能让 Codex 在和项目“初次见面”时先做侦察。它读 README、看 package.json 或 pom.xml、梳理目录结构，然后输出一份项目概览。有了这一步，后续任务的质量会明显提升，因为 Codex 至少知道自己在跟什么代码打交道。

post-mortem则是我觉得最有“团队味”的一个技能。它让 Codex 按一套固定的复盘框架去分析故障，而不是笼统地说“下次注意”。它会引导产出时间线、根因分析、影响范围、改进措施，甚至自动把改进项拆成可执行的任务。这个技能特别适合团队引入，因为复盘质量直接决定了一次事故到底只是事故，还是变成了组织资产。

4. 实操：构建你的第一个自定义技能

4.1 自定义技能的应用场景选择

很多人看完默认技能后的第一反应是“我能不能自己写一个”。答案是当然可以，而且我认为自定义技能才是 superpowers 真正拉开差距的地方。默认技能解决的是通用问题，而你的项目一定有默认技能覆盖不到的专属痛点。

我建议从高频且重复的痛点入手。比如你们项目规定：所有对外 API 必须包含版本前缀、所有数据库操作必须走仓储层、所有新功能必须有性能测试基线。这些约束如果你通过 prompt 每次手动说，一定会漏；但写进一个project-rules技能文件里，Codex 每次开工前都会看到。

另外一个好的候选场景是“错误处理规范”。很多 AI 生成的代码在错误处理上很随意：要么吞掉异常，要么到处 catch 打日志。你可以写一个技能，明确规定哪些异常应该抛出、哪些应该包装、错误消息的格式是什么。这类技能带来的提升，比让模型“更聪明”要直接得多。

4.2 手把手编写一份技能文件

写技能文件本身不需要代码能力，但需要你把脑子里的隐性知识显性化。下面我以一个 Java 项目中常用的“接口开发规范”为例，展示一份完整技能文件该长什么样。

文件放在src/skills/java-api-development/SKILL.md，内容如下：

--- name: java-api-development description: 在 Java 项目中开发新的 REST API 时，必须遵循的接口规范 --- # Java API 开发技能 ## 适用范围 - 新增接口 - 修改现有接口 - 重构接口调用逻辑 ## 必须遵守的约束 1. 所有接口路径必须包含 /api/v1 前缀 2. 请求和响应对象必须使用 record 类型 3. 禁止直接返回数据库实体 4. 错误响应必须使用统一错误码结构 5. 所有接口必须有 OpenAPI 注解 ## 执行步骤 1. 阅读现有 controller 代码，确认风格一致 2. 创建 request 和 response record 3. 在 service 层实现业务逻辑 4. 编写单元测试覆盖成功和失败路径 5. 运行相关测试确认全部通过

写完保存之后，这个技能就生效了。注意 frontmatter 里的description很重要，它决定了 Codex 在什么情况下会主动想起这个技能。描述写得越像“触发条件”，Codex 越能在合适的时候调用它。

4.3 在 Java 项目中调用技能的真实案例

下面是我实际跑过的一个案例。我用 Codex 处理一个 Java Spring Boot 项目的新增用户注册接口，在会话开头只给了它一句话：

请按 java-api-development 技能开发注册接口，输入是邮箱和密码，输出是用户信息。

Codex 读了技能文件之后的表现让我明显感觉到流程被“掰正”了。它没有直接开写 Controller，而是先说“按照技能要求，我会先看现有 controller 代码，确认风格”，然后真的去读了目录结构。等它开始写代码时，路径自动带上了/api/v1，请求和响应用了 record，没有把数据库实体直接扔出去，最后还补了成功和失败两个测试。

这个案例里最值钱的不是代码本身，而是它证明了一个道理：AI 编码代理能不能稳定产出，很大程度上取决于你有没有给它一套可执行的约束。你给它越清晰的边界，它给你的结果就越接近你想要的样子。自定义技能，就是把这些边界“焊”进工作流里的最有效手段。

5. 常见问题与排错实录

5.1 安装与调用高频问题速查表

我把自己和社区里经常遇到的问题整理成一张表，供你排查时快速定位：

如果你遇到“读了技能但行为没变化”的情况，我建议你直接查看 Codex 的会话日志，看它到底从技能文件里提炼出了什么。很多时候不是没读，而是它读了但觉得自己“不需要照做”。

5.2 让 superpowers 稳定发挥的五个使用习惯

最后分享几个我踩过坑之后总结出来的使用习惯，应该能帮你少走弯路。

第一，新会话必须重新触发技能读取。Codex 的上下文隔离性很强，上一个会话里读过的技能，这个会话默认不记得。所以每次新任务开始，我都固定用同一句开场白，把它写进自己的笔记里随时复制。第二，技能文件里少用“尽量”“可以”这类模糊词，多用“必须”“禁止”“唯一例外是”这种强约束表达。Codex 对强约束词的执行力比软约束高得多。

第三，不要让技能文件太长。单个技能最好能控制在 50 行以内，太长会稀释重点，Codex 会抓不住执行核心。如果需要表达复杂流程，拆成多个技能文件，通过子代理机制串联。第四，定期做“技能评审”。我会每隔一两周翻一次 src/skills，看看哪些技能实际用上了，哪些是摆设。摆设技能就该删掉，否则 Codex 每次都要读一堆不相关文件，浪费上下文窗口。

第五，也是我觉得最重要的一点：把技能文件当作代码来对待。它需要版本管理，需要 CR，需要测试。你不敢直接往主干上推一段没验证过的重构代码，那也不该把没验证过的工作流塞给团队的 AI 代理。技能文件维护得越谨慎，你从 superpowers 里得到的稳定性就越高。我自己已经把这套框架用成了每天的默认工作流，不是因为它的名字有多酷，而是它第一次让 AI 编码代理像“懂规矩的同事”，而不是每次都靠运气的自动补全工具。