企业官网建设流程全解析

1. 拆解 superpowers：它到底想解决什么问题

第一次看到 “superpowers” 这个词，很多人会以为是某个超级英雄题材的游戏或者插件合集。但如果你最近在 Claude Code、Codex CLI 这些终端智能体工具的圈子里泡过，就会发现大家嘴里的 superpowers 其实指向一个很具体的东西：一套给 AI 编程助手用的agentic skills framework，翻译过来就是“智能体技能框架”。它的核心主张很朴素——不要让 AI 每次从零开始猜你的项目该怎么写，而是把一套经过验证的软件开发方法论，拆成一个个可复用的“技能包”，让 AI 在需要的时候自己调用。

我最初接触这个概念是在给一个中型 Node.js 项目做重构的时候。当时我用 Claude Code 做主力，Codex CLI 做交叉验证，结果发现同一个需求，两个工具给出的代码风格、目录结构、甚至错误处理方式都不一样。问题不在于模型能力，而在于我没有给它们一套统一的“行为准则”。superpowers 想解决的正是这个痛点：它不绑定具体模型，也不绑定具体 CLI 工具，而是定义了一套技能描述规范，让 Claude Code、Codex CLI 甚至你本地跑的模型都能按同一套方法论干活。

这套框架适合谁？如果你只是偶尔用 AI 补全几行代码，那确实用不上。但如果你已经把 Claude Code 或 Codex CLI 当成日常开发环境的一部分，每天要处理多个文件、多个模块、甚至多个仓库的改动，那 superpowers 这类技能框架就值得认真研究。它本质上是在做一件事：把“资深工程师的做事习惯”从人脑里抽出来，变成 AI 可以读取和执行的技能文件。接下来我会从设计思路、核心细节、实操落地和问题排查四个层面，把这套东西拆开讲清楚。

1.1 为什么是“技能框架”而不是“提示词模板”

很多人第一次听到 skills framework，会下意识觉得这不就是高级一点的 prompt template 吗？我一开始也这么想，直到我把一个真实的重构任务分别用纯提示词和技能框架跑了一遍，才发现差别很大。纯提示词的问题在于，它是一次性的、上下文绑定的。你写了一段很长的提示词告诉 AI 要怎么组织代码，但换一个会话、换一个项目，这段提示词就失效了，你得重新写。而且提示词越长，模型越容易在中途丢失重点。

技能框架的思路完全不同。它把“怎么做”拆成独立的技能单元，每个技能单元有自己的触发条件、输入输出定义和执行步骤。比如“重构一个函数”是一个技能，“为新模块写测试”是另一个技能，“检查依赖冲突”又是另一个技能。当 AI 遇到对应场景时，它自己去匹配技能，而不是靠你每次手动投喂提示词。这就像你带新人，你不是每次遇到问题都给他讲一遍完整方法论，而是给他一本操作手册，告诉他遇到什么情况翻哪一页。

从工程角度看，这种设计还有一个隐藏好处：技能文件是可以版本控制的。你可以把技能定义放进 Git 仓库，团队里每个人用的都是同一套标准。今天你优化了“代码审查”这个技能，明天所有人用 Claude Code 做 review 时都会自动受益。这是提示词模板做不到的，因为提示词散落在每个人的聊天记录里，根本没法统一管理。

1.2 和 Claude Code、Codex CLI 的关系到底是什么

这里需要澄清一个常见的误解。superpowers 不是 Claude Code 的插件，也不是 Codex CLI 的扩展包。它更像是一套“约定”，一套放在项目目录里的技能描述文件。Claude Code 和 Codex CLI 作为终端智能体，本身具备读取项目文件、执行命令、修改代码的能力。superpowers 做的事情是给这些能力加上“行为约束”和“流程指引”。

举个例子，Claude Code 默认情况下你让它“优化这个模块”，它可能会直接开始改代码。但如果你在项目里放了 superpowers 的技能定义，它可能会先读取技能文件，发现“优化模块”这个任务应该先做依赖分析、再做影响范围评估、最后才动代码。这个顺序不是模型自己决定的，而是技能文件里写死的。Codex CLI 同理，它支持读取项目内的配置文件，你可以把技能定义放在它能够识别的位置。

我实测下来，Claude Code 对这类技能文件的响应更自然一些，因为它本身就强调“项目上下文感知”。Codex CLI 更偏向命令式交互，你需要显式告诉它去读取某个技能文件。但两者都能用，只是接入方式略有差异。后面我会分别讲怎么配置。

2. 核心细节解析：技能文件里到底写了什么

要理解 superpowers 的实际价值，得先看它的技能文件长什么样。虽然不同实现细节会有差异，但核心结构是相通的：每个技能包含触发条件、前置检查、执行步骤、输出规范和回退策略五个部分。这五个部分不是随便定的，它们对应的是资深工程师在动手之前脑子里会过一遍的流程。

触发条件决定这个技能什么时候被激活。比如“当用户要求新增一个 API 端点时”或者“当检测到测试覆盖率低于阈值时”。前置检查是动手之前必须确认的事情，比如依赖是否安装、环境变量是否配置、当前分支是否干净。执行步骤是具体的操作序列，可以包含命令、代码模板、文件路径规则。输出规范定义结果应该长什么样，比如“所有新增函数必须有 JSDoc 注释”或者“提交信息必须遵循 Conventional Commits”。回退策略是出错时怎么办，比如“如果依赖安装失败，回退到上一个可用版本并记录日志”。

2.1 触发条件的设计技巧

触发条件写得好不好，直接决定技能会不会在错误的时机被调用。我踩过的一个坑是：把触发条件写得太宽泛。比如我写了一个“代码格式化”技能，触发条件写的是“当用户提到格式化时”。结果有一次我在跟 Claude Code 讨论格式化策略，并没有让它执行格式化，它却直接开始改文件了。后来我把触发条件改成“当用户明确要求执行格式化操作，且当前工作目录存在配置文件时”，误触发就少了很多。

另一个技巧是给触发条件加优先级。有些技能是互斥的，比如“快速修复”和“完整重构”不应该同时激活。你可以在技能文件里加一个 priority 字段，数值高的优先。Claude Code 在解析多个技能时，会按优先级排序。Codex CLI 目前对优先级的支持弱一些，需要你在命令里显式指定用哪个技能。

还有一个容易被忽略的点：触发条件里最好包含“否定条件”。比如“当用户要求优化性能，但未明确要求改变外部接口时”。这样能避免 AI 在优化内部实现的时候，顺手把 API 签名也改了，导致调用方崩溃。这个技巧是我在一个线上事故之后总结出来的，当时 AI 把一个大函数的参数顺序调整了，虽然逻辑没问题，但所有调用点都得跟着改，review 成本极高。

2.2 前置检查为什么不能省

很多人写技能文件时喜欢跳过前置检查，觉得这是浪费时间。但我的经验是，前置检查省下来的时间，远比它消耗的时间多。原因很简单：AI 执行任务时如果环境不对，它不会像人一样停下来问你，而是会尝试“绕过”问题。比如依赖没装，它可能会去改 import 路径；分支不干净，它可能会把未提交的改动一起提交上去。这些行为在事后排查时非常痛苦。

前置检查的典型内容我整理了一个清单，你可以直接参考：

这个表格里的每一项都是我实际遇到过问题的。特别是 Git 状态检查，有一次 AI 在未提交的改动上继续叠加修改，最后我想回滚都找不到干净的基点。从那以后，我把 Git 状态检查加进了所有涉及文件修改的技能里。

2.3 执行步骤的粒度控制

执行步骤写多细，是一个需要权衡的问题。写得太粗，AI 自由发挥的空间太大，结果不可控；写得太细，技能文件会变得极其冗长，维护成本高，而且 AI 可能会因为步骤太碎而丢失整体目标。

我的经验法则是：一个执行步骤对应一个可验证的中间状态。比如“新增 API 端点”这个技能，我会拆成：定义路由 -> 定义控制器 -> 定义服务层 -> 写单元测试 -> 更新接口文档。每一步做完，都有一个明确的东西可以检查。路由定义完，我可以看路径对不对；控制器定义完，我可以看参数校验有没有；服务层定义完，我可以看业务逻辑是否完整。这样即使中间某一步出错，我也能快速定位。

另外，执行步骤里要避免写具体的代码内容。技能文件应该是“方法论”，不是“代码库”。比如你写“使用 express.Router() 创建路由”，这是可以的；但如果你把整个路由文件的代码贴进去，那就变成模板了，失去了技能框架的灵活性。模板适合固定场景，技能适合变化场景。superpowers 的定位是后者。

2.4 输出规范与回退策略的配合

输出规范定义的是“做完之后应该是什么样”，回退策略定义的是“做砸了怎么办”。这两者必须配合使用，否则技能就是不完整的。我见过一些技能文件只写输出规范，不写回退策略，结果 AI 遇到错误时要么卡住不动，要么胡乱尝试修复，把问题搞得更复杂。

输出规范的常见内容包含：代码风格要求、注释要求、测试覆盖率要求、提交信息格式、文档更新要求。回退策略的常见内容包含：依赖安装失败时的降级方案、测试不通过时的最大重试次数、文件冲突时的处理方式、网络请求失败时的重试间隔。

我一般会在回退策略里加一条“最大尝试次数”，默认是 3 次。超过 3 次还没成功，就停止并输出当前状态，让人来介入。这个数字不是随便定的，是我观察了很多次 AI 调试过程后总结的。大部分问题在前 2 次尝试内能解决，第 3 次还不行，通常说明问题不在执行层面，而在需求理解或环境配置层面，继续让 AI 试只是浪费 token。

3. 实操落地：从零搭建一套可用的技能框架

理论讲完了，接下来是动手环节。我会以 Claude Code 为主、Codex CLI 为辅，走一遍完整的搭建流程。这套流程我在 Ubuntu 和 macOS 上都跑过，Windows 下用 WSL 也没问题。前提是你已经装好了 Claude Code 或 Codex CLI，如果还没装，先去看官方文档把基础环境配好，这里不展开安装步骤。

3.1 目录结构与文件命名

技能文件放哪里，不同工具有不同的约定。Claude Code 会扫描项目根目录下的.claude文件夹，Codex CLI 默认读取.codex文件夹。为了两边都能用，我建议在项目根目录建一个skills文件夹，然后在.claude和.codex里分别放一个软链接或者配置文件指向它。这样技能定义只有一份，维护起来方便。

目录结构大概长这样：

project-root/ ├── skills/ │ ├── refactor-module.md │ ├── add-api-endpoint.md │ ├── write-tests.md │ └── review-code.md ├── .claude/ │ └── skills -> ../skills └── .codex/ └── skills -> ../skills

文件命名我习惯用“动词-名词”的格式，比如refactor-module.md、add-api-endpoint.md。这样在列表里一眼就能看出每个技能是干什么的。避免用skill1.md、skill2.md这种命名，过两天你自己都忘了哪个是哪个。

3.2 写第一个技能：以“重构模块”为例

我们拿“重构模块”这个场景来写一个完整的技能文件。假设你有一个utils目录，里面堆了几十个函数，你想让 AI 帮你按职责拆分。技能文件内容如下：

# Skill: Refactor Module ## Trigger 当用户要求重构某个模块，且明确指定了目标目录时激活。 ## Pre-checks - 确认目标目录存在且包含至少一个 .js 或 .ts 文件 - 确认 Git 工作区干净，无未提交改动 - 确认项目根目录存在 package.json ## Steps 1. 读取目标目录下所有文件，列出每个文件的导出函数和依赖关系 2. 按功能内聚性将函数分组，每组生成一个建议的新文件名 3. 输出分组方案，等待用户确认 4. 用户确认后，创建新文件并迁移函数 5. 更新所有引用旧路径的 import 语句 6. 运行现有测试，确认无回归 ## Output Rules - 每个新文件顶部必须有模块级注释，说明该模块职责 - 迁移后的函数保持原有签名不变 - 所有 import 路径使用相对路径，不使用别名 ## Fallback - 如果测试失败，回退到重构前状态并输出失败用例 - 如果用户未确认分组方案，不执行任何文件操作 - 最大重试次数：2

这个技能文件写完之后，你在 Claude Code 里输入“帮我重构 utils 目录”，它就会自动匹配到这个技能，按步骤执行。注意第 3 步“等待用户确认”很关键，它把控制权交还给人，避免 AI 自作主张。我一开始没加这一步，结果 AI 把函数拆得太碎，每个文件只有一两个函数，反而更难维护。加了确认环节之后，我可以调整分组方案再让它执行。

3.3 在 Claude Code 中调用技能

Claude Code 调用技能的方式比较自然，它会在处理任务时自动扫描.claude/skills目录。你不需要显式说“使用某个技能”，只要你的需求描述和技能的触发条件匹配，它就会激活。但这里有个细节：Claude Code 默认只扫描一层目录，如果你的技能文件放在子文件夹里，需要在配置里加递归扫描的选项。

我实测下来，Claude Code 对技能文件的解析速度很快，基本不影响响应时间。但如果你放了太多技能文件（超过 20 个），它匹配的准确率会下降。我的建议是保持技能数量在 10 到 15 个之间，覆盖最常用的场景就行。不常用的场景，临时用提示词解决。

还有一个技巧：你可以在技能文件里加一个examples字段，放一两个输入输出示例。Claude Code 对示例的敏感度很高，有示例的技能匹配准确率明显更高。比如在“重构模块”技能里加一个示例，说明输入是“重构 utils 目录”，输出是分组方案表格。这样它就不会把“重构”理解成“重写”。

3.4 在 Codex CLI 中调用技能

Codex CLI 的调用方式更偏命令式。你需要用--skill参数显式指定技能文件路径，或者在.codex/config里配置默认技能目录。我一般会在项目根目录放一个codex.md文件，里面列出当前项目可用的技能和简要说明，然后让 Codex CLI 读取这个文件。

Codex CLI 的一个优势是它对命令执行的控制更细。你可以在技能文件里写具体的 shell 命令，它会逐条执行并返回结果。比如“运行测试”这个步骤，你可以写npm test -- --coverage，Codex CLI 会直接跑这条命令，然后把覆盖率报告返回给你。Claude Code 也能执行命令，但它的输出更偏向自然语言总结，Codex CLI 更偏向原始输出。两者各有优劣，看你习惯哪种。

需要注意的是，Codex CLI 对技能文件的格式要求更严格。Markdown 的标题层级必须正确，否则解析会出错。我遇到过因为二级标题写成三级标题导致技能无法识别的情况，排查了半天才发现是格式问题。所以写完技能文件后，最好用 Markdown lint 工具检查一遍。

3.5 本地模型接入的注意事项

有些朋友想在本地跑模型来配合这套技能框架，比如用 LM Studio 加载一个开源模型，然后通过 API 接入 Claude Code 或 Codex CLI。这个思路可行，但有几个坑要提前知道。

第一，本地模型对长上下文的理解能力普遍弱于云端模型。技能文件如果太长，本地模型可能会丢失中间步骤。我的建议是把技能文件控制在 500 行以内，超过的部分拆成多个技能。

第二，本地模型的指令遵循能力参差不齐。有些模型对 Markdown 格式的解析很好，有些则会把技能文件当成普通文本忽略掉。你需要实测一下你用的模型对结构化文本的敏感度。如果发现它不按技能步骤走，可以尝试把技能文件转成 JSON 格式，结构化程度更高，模型更容易解析。

第三，本地模型的执行速度受硬件限制。如果你用消费级显卡跑，生成速度可能只有每秒几个 token，执行一个完整技能要等很久。这种情况下，建议只把技能框架用于关键任务，日常小改动还是用云端模型。

4. 常见问题与排查技巧实录

这套东西用久了，总会遇到各种奇怪的问题。我把过去几个月踩过的坑整理成了一张速查表，覆盖了大部分常见故障。你可以先看表，再看后面的详细说明。

4.1 技能不触发怎么办

这是最常见的问题。你明明写了技能文件，但 AI 就是不用。排查顺序是这样的：先确认技能文件在正确的目录下，Claude Code 看.claude/skills，Codex CLI 看.codex/skills。然后确认文件扩展名是.md，有些工具只识别 Markdown 格式。接着检查触发条件里的关键词，是不是和你实际输入的需求描述对不上。比如你写的是“重构模块”，但你输入的是“整理一下这个文件夹”，那肯定匹配不上。

如果以上都没问题，那可能是技能数量太多导致匹配优先级混乱。你可以临时把其他技能文件移走，只留一个，看能不能触发。能触发的话，就是优先级问题，需要给技能加 priority 字段。不能触发的话，可能是工具版本问题，检查一下 Claude Code 或 Codex CLI 是不是最新版。

4.2 前置检查被静默忽略

这个问题比较隐蔽。你写了前置检查，但 AI 执行时直接跳过了，你也不知道它检查了没有。Claude Code 默认会把前置检查的结果放在日志里，但不会在对话界面显示。你需要打开详细日志模式才能看到。Codex CLI 会在终端输出检查结果，但如果你用了--quiet参数，输出会被抑制。

我的做法是在技能文件里加一条规则：前置检查失败时，必须输出明确的错误信息，并且停止执行。这样即使日志没开，你也能在对话里看到问题。另外，前置检查的每一项都要有明确的通过/失败判断标准，不能写“检查依赖是否正常”这种模糊表述，要写“检查 node_modules 目录是否存在且包含 express 包”。

4.3 执行到一半停止的排查思路

AI 执行技能到一半突然停了，通常是因为回退策略被触发。你需要看它停在哪一步，以及那一步的错误信息是什么。常见原因包括：命令执行超时、文件权限不足、网络请求失败、测试用例不通过。如果是超时，可以在技能文件里调整超时阈值；如果是权限问题，检查一下当前用户对目标目录是否有写权限；如果是网络问题，看是不是需要配置代理或者换源。

我遇到过一次比较诡异的情况：AI 在执行“运行测试”步骤时停了，日志显示测试进程被信号中断。排查后发现是测试用例里有一个死循环，把内存吃满了，系统触发了 OOM killer。这种问题技能文件本身解决不了，需要先修复测试用例。所以回退策略只能处理“可预期”的错误，对于代码本身的 bug，还是得人来修。

4.4 输出格式不符合规范的调整方法

输出规范写了但没生效，通常是因为规则太抽象。比如你写“代码要有良好的注释”，AI 不知道什么叫“良好”。你要写“每个导出函数必须有 JSDoc 注释，包含 @param 和 @return”。规则越具体，执行越准确。

另一个原因是技能文件里没有示例。Claude Code 和 Codex CLI 都对示例很敏感。你在输出规范下面加一个“示例输出”小节，放一段符合规范的代码片段，AI 就会照着这个格式来。我试过在“写测试”技能里加一个 Jest 测试用例的示例，之后生成的测试代码风格统一多了。

4.5 多技能冲突的优先级设置

当你的需求同时匹配多个技能时，冲突就出现了。比如你输入“重构这个模块并补充测试”，它既匹配“重构模块”又匹配“写测试”。这时候如果没有优先级设置，AI 可能会随机选一个，或者两个都执行但顺序混乱。

解决方法是在技能文件里加 priority 字段，数值越大优先级越高。我一般把“前置性质”的技能设高优先级，比如“环境检查”优先级 100，“重构模块”优先级 50，“写测试”优先级 30。这样 AI 会先做环境检查，再做重构，最后补测试。顺序对了，结果才可控。

4.6 本地模型不读技能文件的处理

本地模型不读技能文件，大概率是模型对 Markdown 结构化文本的解析能力不足。你可以先做一个简单测试：把技能文件的内容直接粘贴到对话里，看模型能不能按步骤执行。如果能，说明是文件加载的问题；如果不能，说明是模型本身的问题。

文件加载问题通常是路径配置不对，检查一下 Claude Code 或 Codex CLI 的技能目录配置。模型本身的问题，可以尝试换一个对结构化文本支持更好的模型。如果换不了，就把技能文件转成 JSON 格式，JSON 的结构化程度更高，大部分模型都能解析。转换的时候注意保持字段名一致，否则技能逻辑会乱。

5. 我个人的使用体会与几个实用建议

这套技能框架我用到现在，最大的感受是它把“AI 编程”从“碰运气”变成了“可管理”。以前我用 Claude Code 做重构，每次结果都不一样，有时候很好，有时候得全部推翻重来。现在有了技能文件，至少流程是固定的，结果的下限提高了不少。当然它也不是银弹，技能文件写得好不好，直接决定效果。我见过有人把技能文件写成了一本小说，AI 根本读不完；也有人写得过于简略，AI 完全靠猜。

如果你刚开始尝试，我的建议是从一个技能开始，就选你最常用的那个场景。把它写出来，跑通，再写第二个。不要一上来就搞十几个技能，那样调试成本太高。另外，技能文件要跟着项目一起进版本控制，每次调整都提交，这样你能看到哪些改动提升了效果，哪些没有。我现在的习惯是每两周回顾一次技能文件，把不再适用的规则删掉，把新踩的坑补进去。

还有一个容易被忽略的点：技能文件里的语言要和你平时跟 AI 对话的语言一致。如果你用中文写技能文件，但用英文跟 AI 交流，匹配准确率会下降。Claude Code 对中英文混合的容忍度还可以，Codex CLI 更偏向单一语言。所以要么全中文，要么全英文，别混着来。

最后分享一个我最近在用的技巧：给技能文件加一个“版本”字段，记录这个技能最后一次修改的时间和修改人。当团队多人共用一套技能时，这个字段能帮你快速定位问题。比如某个技能突然不生效了，你看一下版本记录，发现昨天有人改了触发条件，那就知道该找谁确认了。这个习惯是从代码 review 里借鉴过来的，用在技能管理上同样有效。