企业官网建设流程全解析

最近在折腾 AI 编程助手的时候，发现一个很有意思的现象：大家把太多精力放在选模型、堆参数上，却很少想过一个问题——同样拿着 Codex CLI、Trae 这类工具，为什么别人能让 AI 老老实实走完“设计-开发-测试-修复”的完整流程，而我的 AI 动不动就自作主张，改一处崩三处？

我试了一圈下来，发现差距往往不在模型，而在“调教方式”。最近这套叫superpowers的技能包，确实把这层窗户纸捅破了。它不是给 AI 装什么外挂，而是一整套用 Markdown 写成的技能提示词体系，能让 AI 编程助手从“你说一句、它写一段”的被动执行模式，切换成“先规划、再动手、自测完再交付”的工程化工作流。尤其配合 Codex CLI 这类命令行工具，效果比我预想的要明显得多。

这篇文章就是我自己的完整折腾记录，从 superpowers 到底是什么、为什么能起作用，到在 Codex CLI、Trae Work 里具体怎么装、怎么配、怎么改，再到我实际跑项目时踩过的坑和排查思路，一次性全写清楚。无论你是刚接触 AI 编程助手，还是已经用了一段时间但觉得输出不稳定，这篇都值得你花十分钟看完。

1. 先搞清楚：superpowers 到底给 AI 加了什么“超能力”

先说结论：superpowers 本质是一套分层清晰的提示词技能集合，它把 AI 编程助手的思考过程拆成了几个固定阶段，每个阶段对应一组极其具体的规则和动作。或者说，它像是给 AI 配了一本内部工作手册。

1.1 为什么 AI 编程助手总是不按套路出牌

用过 Codex CLI 或者同类工具的朋友应该都有体会：模型本身的写代码能力已经很强，但它在项目管理这件事上非常“自由散漫”。你让它“实现一个用户登录功能”，它可能上来就写路由、写数据库、写前端页面，中间跳过异常处理，不写测试，最后交付的东西看着能跑，一上线全是洞。

这背后的原因不复杂。大模型训练时见过海量代码，它能“模仿”出很像样的代码，但它没有你项目的上下文，不知道你的编码规范、不知道你要求测试覆盖率、不知道你“先出设计再动手”的习惯。如果你不在提示词里把这些规则讲清楚，模型就会按照训练数据里的“最大公约数”来干活——而那个公约数，通常就是最短路径、最省事的做法。

superpowers 解决的就是这个问题。它用流程约束 + 规则注入 + 清单校验的方式，把“一名合格工程师在真实项目里会怎么工作”这个过程，变成 AI 能理解和执行的显式指令。

1.2 核心技能包：“规划-构建-测试-修复”的闭环

整套 superpowers 体系里最核心的，是四个环环相扣的技能：

这四个技能不是互相独立的，它们是按顺序被 workflow 调用的一条流水线。AI 接到你的指令后，会先读 workflow 技能，规划出 Step 1、Step 2、Step 3……然后每一步执行时再调用 build 技能，做完一段就触发 test 技能检查，出了问题才进入 fix 流程。

这种设计的最大价值在于，它把“质量检查”从人的身上转移到了流程本身。以前你需要在对话里反复提醒“记得写测试”“先看看有没有破坏其他功能”，现在不用了，技能会替你做这些事。

1.3 和 AGENTS.md、CLAUDE.md 这类配置的定位差异

之前我也折腾过 CLAUDE.md、AGENTS.md 这类项目记忆文件，它们的作用是给 AI 输入项目背景、代码结构、常用命令。但坦白说，这类文件管的是“静态知识”，AI 接没接住、执行到哪一步该用哪条规则，它没法自动判断。

superpowers 的思路不太一样。它把技能文件放在项目特定目录里，依赖 AI 在每次执行任务时主动扫描、加载。真正的关键在于，它的提示词写得极其具体，不是“请写高质量代码”这种正确的废话，而是“先查看现有测试命令，如果没有测试，先创建一个基础的测试框架再继续”这种可以直接执行的指令。

所以你可以这样理解：AGENTS.md 是给 AI 的“项目简介”，superpowers 是给 AI 的“工作守则”。两者配合使用，效果才会最大化。后面我在自定义技能的部分会专门演示这种配合方式。

2. 安装 superpowers 的两种主流方式（含 Codex CLI 配置细节）

superpowers 的安装方式有好几种，我实际用下来，最常见的两种是npm 包安装和传统手动放置。这节我把具体步骤、命令和校验方法都写出来，你可以直接照着操作。

2.1 方式一：npm 全局安装，一行命令搞定

如果你和我一样用 Codex CLI，而且 Node.js 环境比较干净，我推荐直接用 npm 安装。在终端里执行：

npm install -g @superpowers/skills

安装完成之后，需要确认全局 node_modules 的路径。这一点很容易被忽略——很多朋友装完说“找不到技能”，其实就是因为 npm 全局安装目录不在系统 PATH 里，或者安装路径跟 Codex CLI 的默认配置对不上。

可以用下面的命令查看全局根目录：

npm root -g

以我目前的机器为例，输出是类似/usr/local/lib/node_modules这样的路径。记下这个路径，一会儿配置 AGENTS.md 时要用。

2.2 配置 Codex CLI 的 AGENTS.md 来加载技能

Codex CLI 的配置模型有点特殊，它默认会读取项目根目录下的AGENTS.md文件作为上下文的一部分。superpowers 的技能要生效，就得在这里把技能目录引用进去。

我用的配置方式是在项目根目录新建一个AGENTS.md，内容大致如下：

# 项目说明 这是一个基于 TypeScript 的 CLI 工具项目，使用 pnpm 作为包管理器。 ## 技能加载 每次任务开始时，先读取以下技能文件： - /usr/local/lib/node_modules/@superpowers/skills/workflow/SKILL.md - /usr/local/lib/node_modules/@superpowers/skills/build/SKILL.md - /usr/local/lib/node_modules/@superpowers/skills/test/SKILL.md - /usr/local/lib/node_modules/@superpowers/skills/fix/SKILL.md

这里有两个关键点：

第一，路径一定要写成绝对路径，不要用~或者环境变量简写。我在实际操作中发现，Codex CLI 对相对路径和 shell 风格路径的处理不算稳定，有时候能加载有时候不能，排查起来很头大。用绝对路径一次性解决。

第二，如果你的 npm 全局路径里有空格（比如 Windows 下常见的C:\Users\Your Name\AppData\Roaming\npm\node_modules），一定要用引号把路径括起来，不然解析会出错。

2.3 在 Trae Work 中安装 superpowers 的特别说明

Trae Work 是字节跳动出的 AI IDE，它本身也支持类似 Claude Code 的 skills 机制。superpowers 在 Trae Work 里的安装逻辑跟 Codex CLI 略有不同。

先说结论：Trae Work 可以读取项目目录下的.agents/skills文件夹。所以如果你在项目根目录创建.agents/skills/workflow/SKILL.md、.agents/skills/build/SKILL.md这种结构，Trae 里也能识别并加载。

但要注意，Trae 的默认上下文管理跟 Codex CLI 不太一样。它不会自动读取AGENTS.md，需要你在.trae/rules里配置，或者通过对话中的“添加规则”功能。我建议你在 Trae Work 的项目设置里，把技能目录和一个说明文件关联起来，让 IDE 每次会话都先扫描一遍.agents/skills目录。

另外，Trae Work 对技能文件名的识别比较严格：必须叫SKILL.md，用其他名字会出现“技能存在但无法触发”的玄学问题。这一点我在实际工程里踩过，后面排查表里会再提到。

2.4 传统安装方式：手动放置技能文件

如果你不想装 npm 包，或者项目对依赖管理有强制要求，手动放置是最直接的办法。操作也很简单：

1. 从 superpowers 的官方仓库下载最新 release 的 zip 包，或者直接把仓库里的skills目录完整克隆下来。
2. 在项目根目录创建.agents/skills文件夹。
3. 把下载的技能子文件夹复制进去，最终目录结构像这样：

.agents/ └── skills/ ├── workflow/ │ └── SKILL.md ├── build/ │ └── SKILL.md ├── test/ │ └── SKILL.md └── fix/ └── SKILL.md

这种方式的优势是完全可控。你可以随意修改技能文件里的提示词，不受 npm 包版本更新影响。缺点是后续官方如果更新了技能逻辑，你需要手动同步，否则容易版本漂移。

我在一些需要严格供应链管理的团队项目里，更倾向这种手动放置的方式，因为可以把技能文件提交到 git 仓库里，团队所有人共享同一套规则，code review 时也能直接看到改了什么。

2.5 安装后怎么确认技能被正确加载

装完别急着干活，先做一次“加载验证”。方法很简单：在 Codex CLI 或者 Trae Work 里发一句指令，例如：

先读取 workflow 技能，然后帮我梳理一下当前项目里有哪些待办任务。

如果 AI 的回答里出现了类似“我先按照流程规划，然后逐个执行……”这样的结构化输出，说明 workflow 技能已经生效。如果它直接开始列代码、给建议，八成是没读到技能文件，优先检查路径和文件名。

更硬核的验证方式，是直接在技能文件里临时加一行“如果读到这段话，说明技能加载成功，请在回复开头回复‘收到’”，然后看 AI 回不回。这个方法笨但很有效，排查配置问题时能省下大量时间。

3. 核心技能拆解：workflow、build、test、fix 到底在改 AI 的什么行为

安装只是开始。真正有价值的部分在于理解这些技能文件里到底写了什么、为什么这么写。我花了不少时间逐行研读 superpowers 的技能提示词，下面这节算是我自己的“阅读理解”。

3.1 workflow：让 AI 先长出“项目思维”

workflow 技能是所有技能里最宏观的一个，它要求 AI 在接到任务后，不要急着写代码，先做三件事：

• 分析需求，明确目标、约束条件、交付产物。
• 查看项目现有结构、已有测试命令、代码风格。
• 生成有序的任务清单，并在执行过程中边做边更新清单状态。

听起来很简单？但就是这简单的三步，能改变 AI 的整个行为模式。没有这套流程时，AI 接到“给登录模块加个验证码”这种需求，可能直接就把图片验证码组件、后端接口、数据库字段全写了。有了 workflow，它会先问你验证码类型、有效期、是否需要滑块校验，然后列出一个包含 6-8 个小步骤的清单，每完成一步就用task done标记，让你随时能看见进度。

从实现层面讲，workflow 技能的关键，是把“清单驱动”写进了规则。它不只是建议 AI“可以考虑列个计划”，而是明确要求“每一步完成后，跟用户报告进度，然后再继续下一步”。这种强制性是它区别于一般提示词的核心。

3.2 build：把“小步快跑”写进编码规则

build 技能是针对编码阶段的行为约束。核心规则我记得非常清楚：

• 每次只做一个小任务，不要一次性写出一个 500 行的巨大变更。
• 编写的代码要符合项目现有风格和规范。
• 完成每一个小任务后，先确认没有引入破坏性变更，再继续下一步。
• 如果发现当前方案不如预期，及时向用户提出，而不是硬着头皮写完。

这里最反直觉的一点，是它刻意限制 AI 的输出规模。很多人觉得 AI 一次性生成大段代码才是“强大”，但实际工程里，一次改动越大，review 越困难，出问题的概率越高，出了问题也不好回滚。superpowers 让 AI 学会“增量交付”，这种模式在我们做 code review 时体验尤其明显——每个 diff 都很小，逻辑清晰，出了问题能快速定位到具体提交。

3.3 test：用“无情的测试覆盖检查”逼出可交付代码

test 是我最欣赏的一个技能。它不再简单说“请写测试”，而是要求 AI：

• 先查看项目现有的测试命令和测试框架。
• 针对当前改动，识别出哪些是新功能逻辑、哪些是修改的既有逻辑。
• 给出测试覆盖建议，对于没有测试覆盖的新增代码，明确标注“未覆盖”。
• 如果项目里没有测试框架，建立一个最小的测试环境再继续。

这个技能背后对应了一个很实际的痛点：AI 生成代码时，如果提示词没说“测”，它就默认不测。superpowers 的做法是把它从“可选项”变成“强制项”，并且在交付完成前，先输出一段测试覆盖报告，让你看到哪些函数测了、哪些没测。有了这种明确的输出格式，开发者对 AI 交付质量的信任度能提升一大截。

3.4 fix：给 AI 的“反复横跳”按下暂停键

用过 AI 编程助手的人一定遇过这个场景：某个测试挂了，AI 改了一次，另一个测试又挂了，它再改，结果把原来好好的功能也改坏了，陷入死循环。fix 技能就是专门来收拾这个局面的。

它规定，在修复 bug 时，AI 最多尝试几次（我记得默认是三次），如果三次之内仍未解决，就停止操作，把当前状态、已尝试的方案、失败原因全部汇报，等待人工介入。它还要求 AI 在修复前先复现问题，确认根因，而不是凭感觉乱改。

这个设计对项目安全性的保障非常实际。它承认了 AI 不是万能的，并且用流程机制守住“不能无限破坏”的底线。在团队协作场景里，这等于给 AI 装了一个熔断器，避免它把好好的代码库搞得一团糟。

3.5 这套技能组合的价值，在于“边界清晰”

单独看每个技能，似乎都是“正常工程师会做的事”。但当它们组合在一起，价值就体现出来了：AI 的行为从不可预测变成了可预测，从一次性交付变成了有节奏的迭代。

我自己最直观的感受是，在没有 superpowers 之前，我每次让 AI 改完代码，都要自己再跑一遍测试、看一遍 diff，心理负担很重。用了这套技能之后，AI 会自己把改动拆成小块，配套测试和检查，我只需要在它停下来报告时做最终确认。这种“AI 干活、人来验收”的协作方式，才真正符合我对 AI 编程助手的预期。

4. 不止于内置：如何自定义 skill，让 AI 真正适配你的团队

superpowers 的第二层价值，是它提供了一整套可复制的技能格式。也就是说，你完全可以不局限于内置的 workflow、build 这些技能，而是按照同样的格式，写你自己的技能。这部分对团队落地特别有帮助。

4.1 skill 的标准结构：一个文件夹加一个 SKILL.md

每个 superpowers 技能就是一个独立的文件夹，文件夹里至少有一个SKILL.md文件。这个文件使用 Markdown 格式，头部带一段 YAML frontmatter，主要声明技能的元信息：

--- name: review description: 当需要做代码审查时使用。重点检查安全性、性能、可维护性，并逐条输出问题清单。 ---

然后是正文，正文就是提示词的完整内容。这里有个核心技巧：description 一定要写清楚触发场景，越具体越好。因为 AI 在收到用户请求时，就是靠 description 来决定要不要加载这个技能。如果你写得太宽泛，AI 可能永远想不起来用它。

4.2 实例：给团队写一个“commit 规范”技能

以我自己的团队为例，我们要求所有 commit message 必须遵循 Conventional Commits 规范，并且必须关联 Jira 单号。以前这个规则靠人肉提醒，经常有人漏掉。后来我写了一个commit技能：

--- name: commit description: 当用户要求提交代码、生成 commit message 时使用。严格遵守 Conventional Commits 规范，并以 Jira 单号为前缀。 --- # Commit 规范 1. commit message 格式： type(scope): subject 例如：feat(auth): add login captcha 2. type 只能使用以下取值： - feat: 新功能 - fix: 修复 bug - docs: 文档变更 - style: 格式调整 - refactor: 重构 - test: 测试相关 3. 如果用户没有提供 Jira 单号，主动询问。 4. 禁止直接使用 git commit -m "update" 这种无意义信息。

把这个文件放到.agents/skills/commit/SKILL.md目录下，然后在 AGENTS.md 里加一行引用。从此以后，团队里任何人用 Codex CLI 提交代码，AI 会自动按规范生成 commit message。这种“把团队规范变成 AI 默认行为”的能力，是 superpowers 最被低估的价值。

4.3 在 AGENTS.md 和 CLAUDE.md 里引用自定义技能的注意事项

如果你同时用 Codex CLI 和 Claude Code 这类工具，注意它们的记忆文件名不同，一个是AGENTS.md，一个是CLAUDE.md。最好的做法是让两份文件内容保持一致，并且都指向同一个技能目录，比如.agents/skills。这样无论 AI 助手走哪个入口，加载的技能逻辑都是一样的。

实际操作里有个细节：两个工具对技能目录层级的要求不完全一致。Codex CLI 能直接扫描整个.agents/skills目录，但 Claude Code 更倾向于在CLAUDE.md里明确列出要使用的技能文件路径。所以，建议你在AGENTS.md里写“遍历目录自动加载”，在CLAUDE.md里写“列出具体路径按序加载”，这样能尽量规避兼容性问题。

4.4 技能开发的两个原则：一次只做一件事，规则要能被执行

最后分享两个写技能时很重要的原则，也是我在反复修改技能文件过程中总结出来的。

第一个原则是技能职责单一。一个技能只处理一类场景，别试图写一个“万能技能”把什么都管了。比如 commit 技能就别管代码风格，code review 技能就别管环境部署。混在一起会让 AI 在决定“该不该加载”时疑惑，触发准确率下降。

第二个原则是每条规则都能被 “检查”。也就是说，不要写“保证代码质量”“注意性能”这种抽象的表述，而要写“如果新增逻辑，必须附上对应的测试用例”“如果查询数据量可能超过 1000 条，必须加上分页”。AI 对抽象要求没有执行力，但对可验证的指令有很高的遵循率。一条技能规则好不好，就看你能不能照着它设计一个 checklist 来验收。

5. 使用 superpowers 一段时间后的心得与常见问题排查

最后这部分，我把自己实际使用中遇到的典型问题、排查过程和一些个人体会整理出来，希望能帮你少走弯路。

5.1 问题排查速查表：按现象找方案

5.2 经验技巧：把技能文件纳入版本管理，统一团队基线

我强烈建议把.agents/skills和AGENTS.md一起提交到 git 仓库里。这样做有几个好处：一是团队所有成员共享同一套 AI 工作规范，不会出现你配了一套、同事配了另一套的混乱；二是技能文件的变更可追溯，哪天 AI 行为突然变了，可以跑git diff查看是谁改了什么；三是新成员加入项目后，只要拉代码就能无缝获得全部规则，不用单独培训。

我们团队在实际使用中还做了一层扩展，就是把已经验证过的好用技能同步到公司内部的模板仓库里。新项目一律从模板创建，天然带上这套技能配置，等于所有项目从第一天起就站在同一个质量基线上。

5.3 避坑指南：不要把 superpowers 当成“免死金牌”

需要强调的一点是，superpowers 不能替代代码审查，更不能替代开发者对代码的最终责任。它只是把 AI 的行为从“自由发挥”拉回到“有流程约束”，但 AI 生成的东西依然可能有逻辑漏洞、性能问题、安全隐患。我在团队里推广时反复强调：技能加载、测试通过、流程完整，不等于产品可上线，该做的 review、该做的性能测试、该做的安全扫描，一步都不能少。

另外，也别天真地以为装了固定技能就可以把所有型号的模型套上去。我在实际测试中发现，不同模型对技能提示词的遵循率差异很大。逻辑能力强的模型（比如 Claude 系列、GPT-5 系列）执行得比较到位，轻量模型有时候会在流程中“跳步”。所以如果你发现某台设备上效果不佳，不要先怀疑技能，先检查模型本身的输出能力。

5.4 最后再分享一个我最近的扩展玩法

前面说的都是让别人写的技能，最近我开始尝试把团队的代码评审规范和部署检查清单也做成技能。做法就是把那些原本写在 Notion 文档里的规则，一条条改写成可执行的指令，放进.agents/skills目录。这样无论是谁用 AI 写代码，AI 都会在交付前自动对照这些规则做一轮自我检查。

目前实测下来，这个方法对团队规范落地的帮助非常明显。以前新人的代码要反复 review 才能符合规范，现在 AI 在生成阶段就按规范走，review 的负担小了很多。我也慢慢意识到，superpowers 这套东西最值钱的地方，不在于那几个默认技能，而在于它给了你一个“把经验沉淀成技能”的标准格式。你团队里十条鲜活的踩坑经验，一旦变成技能文件，就能在每次 AI 工作时自动替你提醒自己和队友，这份复利，比任何提示词技巧都来得实在。