企业官网建设流程全解析

不知道你第一次听说“superpowers”这个词是在什么场景下，反正我是在一次被 Codex CLI 默认行为逼疯的下午，顺手刷到一个技能包，名字就叫 superpowers。当时心里还犯嘀咕：一个给命令行 AI 助手用的技能集，也敢起这么中二的代号？结果装上跑通之后，我承认是我草率了。它解决的问题非常具体：默认状态下，AI 代码助手更像一个“应答型选手”，你问一句它答一句，改文件也是一次一个。而 superpowers 做的事情，是把 AI 的思考流程拆成可复用的步骤，比如自动规划、测试驱动开发、重构前梳理影响面，然后让 Codex CLI 按这套流程去执行。说白了，就是把“随手写”变成“按章法打”。

如果你也在用 Codex CLI，并且觉得 AI 给出的改动经常不完整、没有全局观，或者想让它真正像个有经验的工程师一样分步骤推进任务，那这篇文章就是写给你参考的。我会从技能加载原理讲起，覆盖 Codex CLI 与 Trae Work CN 环境下的三种安装方式，再加上我实际跑了几个任务之后踩过的坑和调校建议，通篇都是可以直接照着操作的内容。

1. 先搞清楚：Superpowers 到底是什么玩意

1.1 一个让我改变工作流的发现

先说我自己的使用场景。我负责一个中等规模的前端项目，代码量不大，但模块之间引用关系复杂。以前用 Codex CLI，最让我难受的一点是：它处理“改一个函数”这种小需求很利索，但一旦任务变成“把这个模块的请求逻辑全部迁移到新 API 上”，它就会东一榔头西一棒子，改完 A 文件忘了 B 文件，甚至改出循环依赖。

后来我同事甩给我一个链接，说有一个叫 superpowers 的技能集，专门治这种“局部聪明、全局短视”的问题。我装上之后第一次试运行，明显感觉到它的行为逻辑不同：它先自己列了一个计划，然后逐个步骤确认，每个步骤里还会主动跑测试验证。那一刻我理解了，superpowers 本身不是一个模型，也不是一个第三方 API，而是一套预先写好的 prompt 工程和技能脚本，通过 Codex CLI 的技能加载机制，把大任务拆解成有纪律的执行流程。

1.2 superpowers 的本质：一套让 AI 助手"动起来"的技能包

说实话，从技术架构上看，superpowers 并没有多么玄幻。它本质上就是一组结构化的技能文件，通常放在 Codex CLI 约定的技能目录里。每个技能包含一套明确的指令模板，告诉 AI 在什么场景下应该采用什么工作流。比如它内部常见的技能分类就有计划规划、测试驱动开发、代码重构、影响面分析、文件批量操作等等。

你可以把它理解为：给 AI 助手配了一本“标准作业手册”。比如你提出“升级某个依赖并修复破坏性变更”，如果没有技能包，AI 可能直接开干，用它的直觉去猜测。而有技能包时，它会调用计划技能先做影响面分析，再调用重构技能逐个模块推进，每步跑测试，最后汇总变更。这种流程化能力，正好弥补了大模型在长任务上的注意力漂移问题。

1.3 为什么默认 Codex 不够用，这个包能补什么

我见过很多刚接触 Codex CLI 的人抱怨：为什么 AI 总是答非所问？其实不全是模型的问题，而是你没有一个机制去约束它的行为。默认的 Codex CLI 就像一个聪明的实习生，能力有，但没人告诉他公司的代码规范、测试流程、提交规则，他只能自由发挥。

superpowers 的价值恰恰在这里。它在 AI 和代码仓库之间加了一层“项目执行规范”，让 AI 遵循固定的 SOP。比如它会要求 AI 在动手前先列计划，要求 AI 用 TDD 思路先写失败用例，再写实现代码，要求 AI 在重构时保留旧接口的兼容层。这些规则单独看都很朴素，但组合在一起，就是把“野生 AI”驯化成“规规矩矩的团队协作者”。所以我的判断是：你在考虑把它装进 Codex 之前，应该先想清楚自己到底缺什么。缺的不是更多模型能力，而是更稳的执行方式。

2. 装之前先看懂 Codex CLI 的技能加载机制

2.1 Codex CLI 的版本与技能目录

在动手装 superpowers 之前，我建议你先花五分钟确认一下自己的 Codex CLI 版本和信息，否则后面很容易出现“装了但没生效”的情况。因为我一开始就在这上面吃过亏：技能文件放进去了，但 Codex 完全没识别到，最后发现是目录放错了。

不同时期的 Codex CLI 对技能目录的默认路径略有差异。以我手头这个版本为例，它约定的技能目录是在用户主目录下的.codex/skills文件夹里。每个技能是一个独立的子文件夹，技能说明文档通常叫SKILL.md，里面用结构化格式描述技能的用途、使用场景、调用参数和具体步骤。

你可以用一条命令快速确认目录结构：

ls -la ~/.codex/skills

如果这个目录还不存在，没关系，手动创建就好：

mkdir -p ~/.codex/skills

需要特别注意的是，Codex 加载技能时非常依赖文件夹命名和文件命名。我之前把技能文件夹命名为superpowers-main（从压缩包解压出来的默认名），结果 Codex 直接无视了它。后来把文件夹重命名成superpowers，重新加载才正常。所以命名规范不是小事。

2.2 AGENTS.md 在技能加载中扮演的角色

还有一个容易忽略的文件叫AGENTS.md。如果你在自己的项目根目录放了这个文件，Codex CLI 每次运行时会优先读取它，把它当作项目级上下文。superpowers 这类技能集，往往也会建议你在AGENTS.md里声明需要启用哪些技能。

打个比方，技能文件本身是“工具”，而AGENTS.md是“工具使用说明书”加“现场调度员”。例如我项目里的AGENTS.md会写明：

• 本项目的测试命令是npm test
• 提交流程必须通过 lint 检查
• 修改公共接口前需要先搜索所有调用方

当 Codex 有了这些信息，再叠加 superpowers 里的执行流程，AI 才会真正像一个熟悉这个项目的老手。如果少了这一步，即使技能装在全局目录里，它也缺少关键的项目约束，执行结果仍然是“通用答案”。

2.3 仓库来源与本地备份的准备

superpowers 这类的技能集通常会托管在公开的代码仓库上，安装前需要确保你的终端具备拉取该仓库的网络条件。我个人的习惯是先克隆到本地，检查一下目录里的文件结构，确认包含SKILL.md之后再进行复制或软链接，这样比较稳妥。

git clone <superpowers技能集仓库地址> ~/downloads/superpowers

克隆完成后，看一眼它的目录结构，常见的形态是这样的：

superpowers/ ├── SKILL.md ├── skills/ │ ├── plan/ │ ├── refactor/ │ └── tdd/ └── README.md

我建议在安装前先备份自己原有的技能目录。因为技能包迭代速度不快，但偶尔也会覆盖同名文件，备份能让你在出问题时快速回滚：

cp -r ~/.codex/skills ~/.codex/skills.bak.$(date +%Y%m%d)

3. 三种安装姿势，按场景选

3.1 最省事：Codex CLI 一键引入技能目录

如果你用的是较新版本的 Codex CLI，最简单的方式是利用它自身的 skill 命令。例如有些版本支持类似codex skill add的指令，可以直接从仓库把技能安装到默认目录。

我在实际使用中更多地采用手动方式，因为各个版本的 CLI 对子命令的支持不太一致。如果你不确定自己的版本支不支持，可以先执行：

codex --help

看看输出里有没有 skill 相关子命令。如果有，直接按提示安装即可；如果没有，就使用备选方案：将技能目录复制到~/.codex/skills/下。

cp -r ~/downloads/superpowers/skills/* ~/.codex/skills/

复制完之后，重新打开一个 Codex 会话，让它重新扫描技能目录。正常情况下，它会自动加载。

3.2 Trae Work CN 环境下安装 skill 的路径差异

有一部分读者是在 Trae Work CN 这类桌面工作区里使用 Codex CLI 的，安装路径会和纯命令行环境有区别。Trae Work CN 本质上把 Codex CLI 嵌进了一个可视化界面，但它读取技能目录的逻辑仍然是读取用户目录下的配置，而不是读取项目目录。

我在 Trae Work CN 里踩到过的坑是：它有时候会缓存旧的技能列表。即使你已经把 superpowers 放进了~/.codex/skills，在界面里依然看不到。解决方法并不复杂，找到工作区设置，清掉技能缓存或者直接重启工作区，让它重新扫描。

如果你在 Trae Work CN 设置里看到了“技能路径”或“Skills Path”之类的选项，记得把它指向你实际放置技能的目录。有些版本默认指向的是内置目录，而不是用户目录，所以安装不生效时优先检查这个配置项。

3.3 离线/手动安装：拷贝文件目录

还有一种常见场景是离线安装，比如内网开发环境，或者你的网络拉取不了外网仓库。这种情况下，只要你能拿到技能包的文件压缩包，安装方式反而最简单。

解压之后，把里面包含SKILL.md的顶层文件夹复制到~/.codex/skills目录下。这里有几个细节要注意：

• 解压出来的文件夹如果是superpowers-main，强烈建议改名为superpowers
• 不要多套一层目录，也就是说~/.codex/skills/superpowers/SKILL.md这个路径才是正确的
• 检查SKILL.md文件是否损坏，最简单的办法是用文本编辑器打开，确认里面有内容而不是空文件

离线安装完成后，同样是重启会话或者运行扫描命令让 Codex 识别。识别成功的标志是，你可以在一个新的会话中直接提到“使用 plan 技能分析这个任务”，看它是否按照技能要求执行。

4. 安装后别急着用：先做这三件事

4.1 验证技能是否被正确识别

很多人装上技能包就直接开始干活，结果发现 AI 行为和以前一模一样，就断定“没用”。实际上大部分情况是技能根本没被加载，或者加载了但没被触发。

我自己的验证方法是用一个极简会话去测试：

请列出你当前可用的技能，并说明你将如何在以下任务中使用它们：重构这个项目里的 utils 模块。

如果 superpowers 生效，AI 的回复通常会说它打算先分析 utils 模块的影响面，再制定重构计划，最后分步骤实施。如果它的回复依然是那种“好的，我准备开始改代码了”的状态，说明技能没有激活。

这时候我一般会检查两个地方，一是技能目录里是否有重复的文件夹导致加载冲突，二是项目根目录的AGENTS.md是否写入了启用声明。另外，部分版本还支持在会话中手动执行/skills这样的命令来查看技能状态，具体以你本机版本的帮助信息为准。

4.2 给超级权限划好边界

superpowers 名字听着霸气，但你要清楚，它给了 AI 更多的自主操作空间，也就意味着你需要给权限设好边界。我见过有人把技能包装好后，顺手开启了自动执行所有文件的权限，结果 AI 一次性格式化了多个非目标文件，虽然项目有版本控制没有造成实质损失，但还是吓出一身冷汗。

我的建议是分三步设置权限：

1. 在 Codex CLI 里保持默认的“每次操作前询问”模式，不要图省事开启全自动
2. 在AGENTS.md里明确哪些目录 AI 不能动，比如docs/下的人工维护文档、scripts/下的构建脚本等
3. 第一次在实际项目上使用前，找一个临时分支做全流程试跑，确认它在技能驱动下的行为在一个可接受的范围内

技能包只是给了 AI 方法，真正决定它能不能在你的项目里安全工作的，是你划定的边界。

4.3 用一条真实任务感受前后的差异

验证完技能加载和权限设置，我建议你找一条真实但风险低的小任务，感受一下安装前后的差别。不要一上来就让它做大型重构，因为你还需要时间适应它的节奏。

我当时选的任务是：把一个工具函数从utils/format.js迁移到utils/string/format.js，同时更新所有引用它的文件。

在未安装 superpowers 时，AI 的做法大概率是直接搜索字符串然后批量替换，它不会告诉你它搜到了哪些文件，也不会做 import 路径的验证。而安装之后，它调用重构技能，输出结果里有明显的步骤感：先扫描所有 import 来源，再逐文件修改，最后跑测试和构建验证。这个过程给我的感觉是：它终于像一个需要对我负责的同事，而不是一个只知道执行当前指令的终端。

跑完这个任务，你基本就能判断自己是否需要进一步调整技能包的配置了。

5. 实际跑起来：典型场景与翻车记录

5.1 多文件重构：从"各自为战"到"全局联动"

我最有体感的多文件重构场景，是把一个老模块从回调风格改造成 async/await 风格。这个任务牵涉到十几个文件，调用链长，而且各个文件的改动顺序有依赖关系。

如果用传统方式直接让 Codex 做，它经常会陷入“见一个改一个”的状态。改到中间遇到一个异常分支，它可能就停下来问你是想换种写法，还是继续按原计划。不是它能力不行，而是缺少一个全局计划框架的时刻约束。

superpowers 的 plan 技能会在最开始生成一个多步骤计划，并将这个计划注入到会话上下文中。后续每一步，AI 都会回顾这个计划，标注当前进度，然后继续推进。哪怕中间被打断，你也可以让它重新加载计划，它会回到正确的进度节点而不是从头再来。这个“进度标注”机制，是我认为它最值钱的设计之一。

5.2 TDD 模式带来的工作方式变化

另一个让我印象深刻的技能是 TDD 模式的引入。说实话，我平时自己写业务代码，并不算一个严格的 TDD 信徒，但用 superpowers 跑过一次测试驱动开发之后，我开始重新审视它的价值。

当你在 Codex 会话里要求它按 TDD 执行一个功能开发时，它的行为顺序会变成这样：先根据你的需求描述，列出需要覆盖的测试用例；再为这些用例编写测试代码；然后运行测试，确认它们是失败的；接着再写实现代码让测试通过；最后跑一次完整测试套件确认没有回归。

这套流程跑下来，最大的变化是 AI 生成的代码边界意识更强了。它不会为了实现一个函数而顺手改掉另一个函数的逻辑，因为测试用例已经把预期的行为钉死了。虽然这个过程比直接让它写代码要慢一些，但对于那些你不想后面返工的核心模块，慢即是快。

5.3 我的踩坑记录：权限拒绝、路径冲突、版本不一致

有收获，自然也有翻车。我遇到的第一个坑是权限拒绝。在某次运行中，AI 试图修改一个只读目录下的文件，由于我的权限设置是询问模式，它停下来问我是否要提升权限。这里我没注意，一路敲了 yes，结果它把只读目录里一个配置文件也给改了，后面排查了很久才发现是那次误操作。所以现在我的策略是：询问模式下每一次权限申请都看清楚路径再确认，不要习惯性回车。

第二个坑是路径冲突。我在项目里同时保留了skills目录和~/.codex/skills，但两者内容版本不一致，导致 Codex 在会话中加载了旧版技能，产生了一些莫名其妙的行为。排查方法也很原始：逐个环境变量检查，最后发现是项目根目录下隐藏的技能配置优先级更高。去掉项目内的重复技能目录之后，行为恢复正常。

第三个坑是版本兼容。superpowers 的技能文件如果有更新，而你的 Codex CLI 比较老，可能无法理解新技能里的某些字段。这种情况通常会表现为技能加载失败但没有任何报错，只是行为退化成默认状态。解决方案是看技能仓库的 README，里面一般会写明最低支持的 Codex 版本。

6. 如何真正用好它：几个关键心法

6.1 技能包不是越大越好

新手刚接触 superpowers 这类东西，很容易产生一个误解：技能越多，AI 越强。实际上完全不是这样。技能太多会让 AI 在多个流程之间摇摆，本来一个简单的任务，它非要套一个重型的计划流程，输出变得非常啰嗦，效率反而更低。

我现在只保留了项目最常用的几个技能：计划、重构、TDD 和影响面分析。其他不常用的技能统统从技能目录移走，需要的时候再临时放进去。这个思路类似收纳的“断舍离”，保持技能目录的克制，会让 AI 对已启用技能的响应更准确。

6.2 写清需求边界，比会装更值钱

装完技能包之后，我最大的体会是：技能包解决的是“怎么干活”，但“干什么活”还是得你想清楚。如果你给 AI 的需求本身含糊不清，比如“优化一下这个项目”，即使有 superpowers 在手，它也只能列出一些泛泛的优化点，最后挑一个它觉得合理的去执行，而这个“它觉得合理”不一定是你想要的。

我现在会在需求描述里强制自己写清楚三件事：背景、范围、完成标准。背景告诉 AI 为什么要做这件事；范围告诉 AI 哪些文件、哪些模块算在这个任务内；完成标准告诉 AI 做到什么程度可以算结束。大多数情况下，需求描述越清晰，superpowers 里那些技能流程发挥的作用越大。

6.3 版本回溯与后续更新

最后说下技能包的更新问题。我在前文提到安装前会做备份，其实更重要的是形成“更新前先备份”的习惯。因为技能包通常更新不频繁，但每次更新可能调整核心流程，如果你不备份，更新后发现新版本的行为反而和你的项目习惯冲突，想回滚就只能靠记忆了。

我的做法是在技能目录里保留一个versions/文件夹，里面存着每次更新前的压缩包。遇到新版本出问题时，直接解压覆盖回去，一条命令都不用多想。更新之后，我会重新跑一遍第 4.3 节里的真实任务，用同样的需求验证新版本有没有行为回退。

越依赖这套技能流程，我越意识到一个事实：superpowers 的价值不是让 AI 从笨变聪明，而是让它从不稳定变得稳定。它把你验证过的执行策略固化下来，让 AI 每次执行都保持同样的水准。我在实际项目中体验到的效率提升，不只是来自 AI 写代码的速度，更来自它少犯的那些低级错误。如果你已经被 Codex CLI 默认行为折磨过几次，不妨按照上面的步骤装上试试，然后选一个你项目里最常见的场景，用同一根需求分别跑一次有技能和没技能的版本，对比一下过程与结果。我相信你会回来感谢那个下午，花了半个小时读懂了这套技能包。