企业官网建设流程全解析

如果你用过一段时间 Codex CLI，大概率会有这种感觉：它在单次任务上确实聪明，可每次开工都像是在"重新教育"一个新同事。同一个项目里，测试规范、提交信息的写法、遇到报错时的排查步骤，全都得在对话里重讲一遍；讲得不够细，它给出的结果就飘。也就是在这个反复折腾的过程中，我注意到了 "superpowers" 这个项目——它做的事情很简单：把零散在对话里的工程经验，变成一套可以被 Codex 自动加载和调用的"技能"。装完之后，Codex 不再是一个只会接单的实习生，而是一个带着完整工作手册进场的工程师。

这项目不是给你替换 Codex 的，而是在 Codex CLI 之上加一层"方法论层"。你可以把它当成给编码代理配了一套 SOP：每周的开发规范、TDD 流程、调试思路、代码评审清单，全部写成技能文件，让代理在合适的场景自动套用。下面我把这几个月的使用过程、踩过的坑、以及我自己写技能的完整路径都整理出来，给正在折腾 codex superpowers 的朋友一个参考。

1. 从"能用"到"好用"：Codex CLI 的短板与我为什么盯上 superpowers

1.1 每次重复交代需求的痛苦

用 Codex CLI 跑真实的项目任务时，最大的问题不是它不会写代码，而是它每次都在"裸奔"。我举个例子：团队约定所有新代码必须有单测，而且测试要先写。这句话我在不同会话里至少说过三十遍。哪怕今天说了，明天新开一个会话，它又忘了。不是说 Codex 笨，而是对话式代理天然没有"长期肌肉记忆"。

你可能觉得，那我把规范写进项目根目录的AGENTS.md不就行了？确实能解决一部分问题，但AGENTS.md更像一个静态说明书，而真实开发里的场景是动态的：遇到编译错误时应该走哪套排查流程，写提交信息时应该按什么模板，上线前要做哪些检查。这些是"流程性知识"，不是"事实性知识"。把它们全塞进一个文档里，要么文档越长越没人看，要么代理分不清什么时候该用哪一段。

superpowers 恰好是冲着这个痛点来的。它把"流程性知识"拆成一个一个独立的技能文件，每个技能解决一个具体场景。代理在运行时根据任务类型去匹配技能，而不是把整个知识库一次性吞进去。这个设计思路，比单纯堆 prompt 要干净得多。

1.2 superpowers 到底解决什么问题

先说清楚：superpowers 不是 Codex 的平替，也不是某种新的编程语言，它是一套运行在代理侧的技能管理框架。核心做法是：把工程方法论写成 Markdown 文件，通过配置让 Codex 在会话启动时加载这些文件，并在对话过程中按需调用。

举个例子。默认技能库里有一个写提交信息的技能，它会要求代理先查看git diff和当前的提交历史，再按 Conventional Commits 的格式生成信息，并且在提交前明确说明改动的动机。我最开始觉得这功能平平无奇，直到有一次我故意不装技能跑了同样一个提交，Codex 给的信息就是一句"Update file"，而加载技能之后它会给出带范围的、解释为什么改的描述。差距就是这么大。

还有一个典型技能是调试。它的思路类似于"科学排错法"：代理必须先生成假设，再验证假设，而不是看见报错就乱改。这个技能对解决棘手的偶发 bug 尤其管用。说穿了，superpowers 是把我们这些老程序员脑子里的"套路"复制到了代理脑子里。

1.3 什么时候你不该用 superpowers

我不想把它吹成万能药。如果你只是拿 Codex 写一次性脚本、生成几行点对点的代码，不装 superpowers 完全没问题，甚至装了反而增加启动时的上下文开销，让回答变慢一点。它是一个面向"长期维护的项目"和"需要稳定工程质量"的场景的工具。

我现在的主要用法是：把手头项目的工程规范沉淀成技能，然后让 Codex 在每次开工时自动加载。这样无论会话怎么切换、模型怎么升级，团队的核心要求不会丢。它解决的是"一致性"问题，而不是"智能"问题。

2. 把方法论装进代理：superpowers 的技能机制拆解

2.1 一个技能文件长什么样

第一次打开 superpowers 的技能目录时，我有点意外：里面不是代码，几乎全是 Markdown。每个技能就是一个.md文件，文件头部有 frontmatter，里面写着名称、描述、适用场景，正文部分就是给代理看的完整指令。

我拆开过一个典型的测试技能文件，结构大致是：

--- name: pragmatic-unit-tests description: 在编写或修改代码后，生成覆盖核心逻辑的单测，避免过度 mock when: 用户要求写测试、或者在修改已有函数后未补充测试 --- # 编写务实的单元测试 - 先明确被测函数的行为边界 - 优先验证真实输入输出，而不是只验证函数被调用 - mock 只在涉及外部 IO 时使用 - 测试命名要说明场景和期望结果

这个 frontmatter 不是摆设，它是代理做"技能路由"的依据。当任务描述和某个技能的name、description匹配时，代理才会加载正文。也就是说，技能的加载不是无脑全量加载，而是按需匹配的。这也解释了为什么技能多了之后 Codex 的反应速度没有明显下降——不是因为它变聪明了，而是因为大部分技能在大部分时刻根本没被唤醒。

2.2 技能如何被"唤醒"

我一开始很担心一个问题：技能文件放在那里，代理凭什么在正确的时机调用它？后来看明白了，这套机制靠的是两个层面的配合。

第一层是启动时的索引。Codex 会话启动时，superpowers 会把技能目录里的所有文件名、描述信息汇总成一个索引，注入给代理。你可以把这个索引理解成一张"菜单"。代理知道有什么技能可用，但不知道每个技能的细节。

第二层是运行时匹配。当用户提出任务，代理先对照菜单，看看哪些技能和当前任务相关；如果相关，它再去读对应的 Markdown 文件，把详细指令加载进上下文。这种"先菜单后详情"的设计，明显是吸取了大模型 token 有限的教训——所有技能详情全部加载的话，一万字上下文就没了。

这其实和人类的工作方式很像。我进一个新公司时，不会一下记住所有规章制度的细节，但我知道有《请假流程》《报销规范》这些文档，用到哪份查哪份。superpowers 就是在给代理建一个这样的"知识文件柜"。

2.3 技能与 Codex 配置的衔接点

在实现层面，superpowers 和 Codex 的衔接主要靠两个入口：一个是 Codex 的全局配置文件（通常位于用户目录下），另一个是项目级的AGENTS.md。

superpowers 安装时会生成或修改配置，让 Codex 在启动时把技能目录的路径和索引说明加载进去。同时，它还建议在项目根目录放一个精简的AGENTS.md，里面不写具体方法论，只写"本项目的工程规范见技能库：xxx"。这种分工很有意思：项目级文档负责指路，技能库负责方法论细节。好处是，同样的技能可以在多个项目里复用，不需要每个项目都复制一份完整规范。

如果你要自己排查问题，搞清楚这两个入口非常重要。很多时候代理没有调用技能，不是技能写得不对，而是配置入口没接上，代理压根不知道有技能这回事。后面我会专门说排查方法。

3. 从零开始：安装、初始化与第一次验证

3.1 环境准备：codex CLI 与运行依赖

动手之前，先确认本机环境。superpowers 是架设在 Codex CLI 之上的，所以前提条件是：

• 本机已经装好 Node.js 18 以上（Codex CLI 本身依赖 Node 运行时）
• Codex CLI 能正常跑通最简单的对话
• 一个真实存在的 Git 项目，最好不是空的，方便验证效果

我自己使用的是 macOS 环境，路径上会和 Linux 略有差异，但整体逻辑一样。如果你在 Windows 上折腾，建议优先用 WSL，别在 PowerShell 里硬搞，路径问题和权限问题会省心很多。

这里多说一句：在安装任何工具之前，先跑一个简单的codex exec "test"之类的命令，确保 Codex 本身可用。很多人安装 superpowers 后发现问题，回头一查，其实是 Codex 本身没配好。这和装插件前先确认主程序能跑是一个道理。

3.2 安装与项目目录结构

安装 superpowers 我推荐用官方仓库里提供的安装脚本。大致步骤是：

# 先看一眼官方 README，拿到当前推荐的安装命令 curl -sSfL https://raw.githubusercontent.com/obra/superpowers/main/install.sh | bash

如果不想用管道执行远程脚本（我理解这种谨慎），也可以直接把仓库 clone 到本地，然后手动把技能目录链接过去：

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

安装完成后，你会在用户目录下看到类似这样的结构：

~/.codex/ ├── config.toml # Codex 的全局配置，superpowers 会往这里加技能路径 └── superpowers/ ├── skills/ │ ├── pragmatic-unit-tests.md │ ├── debug-with-scientific-method.md │ ├── write-good-commit-messages.md │ └── ... └── AGENTS.md # 技能库的索引说明

装完之后别急着用，先做一件事：用你习惯的编辑器打开config.toml，确认里面确实出现了 superpowers 相关的路径配置。很多安装失败都表现为"装完了但 Codex 没反应"，九成是因为这里没写进去。

3.3 跑一个真实的验证任务

装好之后，第一个验证任务不要选太复杂的。我的建议是：找一个最近提交过的项目，让 Codex 帮你写一条提交信息。

cd ~/your-project codex exec "帮我看一下最近的改动，并用 Conventional Commits 风格写一个提交信息"

如果你没装 superpowers，这条命令的运行结果可能就是一句笼统的提交信息；装了之后，你会看到代理先去执行git diff和git log，然后再组织语言。这其实就是技能被唤醒后的行为变化。

还有个更直接的验证方式：在对话里问 Codex"你现在有哪些技能可用"。如果加载成功，它会列出技能菜单；如果它一脸茫然，说明索引没注入，先去检查配置入口。

我第一次跑验证时，就遇到"索引没注入"的问题，折腾了半小时才发现是 Codex 版本更新后默认配置文件路径变了。这类问题很常见，也是我把安装章节单独拿出来写的原因——安装本身不难，难的是确认装没装上。

4. 写一个属于自己的技能：以"团队提交信息规范"为例

4.1 技能文件的骨架与 frontmatter 字段

superpowers 自带的技能库确实够用，但这个项目真正的价值在于自定义技能。只有把你团队自己的约定写进去，它才真正变成你的神器。

自定义技能的第一步，是理解 frontmatter 里每个字段的含义。我看过的技能文件一般包含四个关键字段：

• name：技能的唯一名称，英文短横线格式，代理靠它做路由
• description：一句话说明这个技能解决什么场景，尽量包含触发词
• when：明确告诉代理"什么情况下该用这个技能"
• avoid：告诉代理"什么情况下不要用这个技能"，这个字段容易被忽略，但其实是防止误触发的最好工具

我见过一个反例：有人写了一个"代码重构"技能，结果代理在每次改动代码时都觉得要重构，把简单任务搞复杂。后来加了avoid字段，限定只在"大规模结构调整、且用户明确提出重构意图"时启用，问题立刻消失。

所以写技能时，不要只写"这个技能是干嘛的"，要写"什么情况下用它、什么情况下不要用"。这就像给新同事布置任务，只说"有客户投诉你就处理"是不够的，还要告诉他哪些投诉可以自己处理、哪些必须上报。

4.2 指令正文怎么写才不会被 AI 忽略

技能正文是写给 AI 看的，不是写给同事看的。我写了很多版之后总结出一个规律：指令要"动作化"，不要"原则化"。

对比一下两种写法。原则化写法是"提交信息应当清晰、简洁、包含足够上下文"，这种话代理看了等于白看，因为它不知道怎么落地。动作化写法是：

# 写提交信息 1. 运行 `git diff --stat` 和 `git diff`，理解本次改动的文件与内容 2. 运行 `git log --oneline -10`，了解最近提交的风格 3. 按 Conventional Commits 格式组织：type(scope): subject 4. 在 subject 中说明"为什么改"，而不是只写"改了什么" 5. 如果改动涉及破坏性变更，在正文中增加 BREAKING CHANGE 说明

看到区别了吗？动作化写法每一步都是可执行的命令或可观察的行为。AI 不是不会执行，而是需要你把模糊的期望翻译成步骤。这也是我们这个职业里最核心的"需求拆解"能力，只不过换了个输出对象。

另外，技能的描述里可以加入少量示例。AI 非常吃"例子"这一套，一个对的比例子比十句抽象描述都管用。比如提交信息的技能里，我会放两个示例，一个优秀的、一个不合格的，代理在生成时会明显向优秀示例靠拢。

4.3 让技能进项目仓库并自动加载

自定义技能写好后，有两种落地方式。一种是放到全局技能目录~/.codex/superpowers/skills/，这样所有项目都能用；另一种是放在具体项目的.codex/skills/下，实现项目级隔离。

我的使用习惯是：通用方法论（测试、调试、提交信息）放全局；团队定制规则（某个模块的开发规范、特殊的目录结构约定）放项目级。这样既不影响其他项目，又能让特定项目的信息保持聚焦。

项目级技能的加载方式和全局技能略有不同，它往往要和项目根目录的AGENTS.md做配合。我在AGENTS.md里一般这样写：

# 项目说明 这个项目使用 superpowers 管理工程规范。 与支付模块相关的改动请严格遵守 "payment-module-rules" 技能。 所有新功能必须配套测试，参考 "pragmatic-unit-tests" 技能。

这样写的好处是，项目文档本身很短，不会占据大量上下文；代理遇到具体任务时再决定去读哪个技能。我之前见过有人把整篇规范塞进AGENTS.md，结果文档两千多行，每次对话都要把全量上下文带上，又慢又容易让代理抓错重点。把"原则"留在AGENTS.md，把"操作手册"放进技能目录，才是合适的分工。

5. 用了几周之后的真实感受与踩坑记录

5.1 最容易翻车的三个场景

第一个容易翻车的场景是"技能名和任务描述匹配不上"。我写过一个小技能，叫react-component-guide，描述里写的是"针对 React 组件的开发规范"。结果有几次我让 Codex 改一个纯工具函数，它也莫名其妙去套这个技能，导致代码风格变得很怪。后来我在描述里加了限制词，写成"仅当改动涉及 .tsx / .jsx 文件中的组件结构时使用"，误触发概率立刻下降。

第二个翻车点是"技能指令和当前项目的既有约定冲突"。比如我的全局提交信息技能要求用 Conventional Commits，但某个老项目一直在用简单的提交方式。如果全局技能优先于项目约定，代理会按全局技能来，反而破坏了项目历史风格。后来我学会在技能正文里加一句"如果项目已有自己的提交规范，以项目历史风格为准"，这样才避免了好心办坏事。

第三个比较隐蔽，是"技能文件更新了，但 Codex 用的是旧指令"。因为技能是在会话启动时注入的，如果你改了技能文件，而当前会话没有重启，代理会继续沿用旧版本的指令。我吃过一次亏：更新了技能描述，结果半天没生效，还以为是语法错了，最后重启会话就好了。如果你发现自己改了没效果，先别怀疑语法，重启会话再试。

5.2 调试技能时看哪里

技能不生效的时候，我一般按三步排查。第一步，确认技能文件在正确的目录下，并且文件名和后缀没有拼错。第二步，打开 Codex 的启动日志，看启动时索引有没有被读进去，重点搜技能目录的路径。第三步，直接在对话里问代理"你是否知道 xxx 技能"，或者让它复述技能要点，看它到底加载到没有。

这三步看起来简单，但能解决九成问题。最容易被忽略的是第二步：Codex 各版本的配置文件路径偶尔会变，安装脚本默认写入的路径和实际运行路径可能对不上。反正记住一点：代理没反应，先确认加载，再怀疑内容。

还有一个我常用的小技巧：在技能正文第一行写一句"如果正确加载了这个技能，请先回复'已加载'再继续执行"。这样你在对话里一眼就能看出技能是否被唤醒，省得猜。当然，这行字要在调试完成后删掉，不然每条对话都多一句废话。

5.3 什么项目适合引入 superpowers

用了三周之后，我逐渐摸清了它的适用边界。最适合引入的项目有两个特征：第一，有明确的、可沉淀的工程规范；第二，代理会频繁参与同一个仓库的改动。比如持续在开发的业务系统、有测试要求的开源库，这类项目把测试流程、提交规范、代码风格沉淀成技能，价值非常大。

不太适合的也有两类。一类是一次性脚本、原型验证这种"用完即弃"的任务，引入技能属于杀鸡用牛刀。另一类是团队规范还在剧烈变动期的项目，技能文件今天改一版明天改一版，光维护技能就得花不少时间，反而不如在对话里直接说清楚。

如果拿开车类比：Codex 默认状态是给你一台自动挡汽车，能跑但操控上限有限；superpowers 是给车加了一套辅助驾驶逻辑——前提是你得先想清楚自己要怎么开。没有明确的"方法论意识"的人，装了的感受就是"好像也没变强多少"；有方法论的人，会觉得终于有个工具能把脑子里的流程落地了。

5.4 持续维护技能库的方法

技能库不是装完就结束的东西，它需要持续维护。我现在养成一个习惯：每次在对话中给 Codex 重复交代同一件要求时，都会停下来想一想"这个要求值不值得沉淀成一个技能"。如果三天之内我需要第二次说同样的话，那它就值得。

维护技能库还有一个建议：定期做"技能瘦身"。技能文件会越积越多，而代理在启动时要扫描整个目录做索引，虽然它是按需加载详情，但数量过于庞大时，索引本身的 token 开销也不小。每两周我会有意识地合并重复的技能、删掉已经不再使用的技能，把技能数量控制在十个以内。三个高价值技能到位，比二十个低价值技能堆在那里更实用。

我个人在实际操作中的体会是，把技能库当成代码来治理——有版本管理、有命名规范、有废弃机制，而不是当成一个随手扔笔记的文件夹。superpowers 真正的上限，不取决于这个工具本身，而取决于你有没有把它当作一个长期维护的工程资产来对待。

最后分享一个小技巧，也是我最近才彻底用顺手的：不要只给 Codex 装别人的技能，一定要逼自己写一个。写第一个技能的过程，就是把你脑子里的隐性经验显性化的过程。等到你发现自己写的技能反复被代理调用，你就真正抓住这个工具的价值了。