企业官网建设流程全解析

1. 从“superpowers”说起：一个让 AI 编程助手真正长出“手脚”的技能框架

第一次看到 “superpowers” 这个词，是在几个做 AI 辅助开发的群里。有人甩出一张截图，说自己的 Claude Code 突然会“自己规划任务、自己写测试、自己跑命令、自己修 bug”了，底下配文就俩字：superpowers。当时我第一反应是又一个营销噱头，毕竟这两年“让 AI 自动写代码”的口号喊了太多，真正能落地的没几个。但架不住好奇，我还是去翻了这个项目的仓库和文档，结果发现它跟我之前接触过的那些“提示词合集”完全不是一回事。

superpowers 本质上是一个agentic skills framework，翻译过来叫“智能体技能框架”。它不绑定某一个具体的模型，也不绑定某一个具体的编辑器，而是定义了一套让 AI 编程助手（比如 Claude Code、Codex CLI 这类命令行智能体）能够按需加载、组合、执行“技能”的机制。你可以把它理解成给 AI 装了一个“技能背包”：平时背包是空的，遇到什么任务，就临时把对应的技能塞进去，AI 拿着这个技能去干活，干完再换下一个。这个思路听起来简单，但它解决了一个非常核心的痛点——通用大模型在软件开发这种长链路、多步骤、强上下文的任务里，光靠一个系统提示词是撑不住的。

我自己用 Claude Code 和 Codex CLI 有一段时间了，踩过的坑不算少。最典型的问题就是：你让它写一个功能，它写得挺快，但写完不测、测了不修、修了不验证，最后你还得自己从头到尾捋一遍。superpowers 想干的事情，就是把这些“软件开发的隐性流程”显式地拆成一个个可复用的技能模块，让 AI 在合适的时机调用合适的技能，而不是一股脑把所有指令塞进上下文里。这个框架适合谁？我觉得三类人最该关注：一是已经在用 Claude Code 或 Codex CLI 做日常开发的人，二是想把自己的开发流程沉淀成可复用资产的技术负责人，三是单纯对 agentic 开发方法论感兴趣、想看看别人怎么设计这套东西的工程师。哪怕你暂时不用这些工具，光看它的技能拆分思路，也能对自己的工作流有不少启发。

2. 核心设计思路拆解：为什么是“技能”而不是“提示词”

2.1 从“一个大提示词”到“按需加载的技能包”

传统做法里，我们想让 AI 干好活，通常是把所有要求写进一个巨大的系统提示词：你要先理解需求、再设计方案、再写代码、再写测试、再跑测试、再修 bug、再写文档……写完之后发现提示词比代码还长，而且模型经常“选择性失忆”，前面说了后面忘。更麻烦的是，不同任务需要的流程完全不一样，写一个新功能和处理一个线上 bug，步骤差异巨大，硬塞进同一个提示词里只会互相干扰。

superpowers 的做法是把这些流程拆成独立的“技能”。每个技能是一个自包含的单元，包含这个技能的名字、描述、触发条件、执行步骤、以及需要的工具或上下文。当 AI 面对一个任务时，它先判断这个任务需要哪些技能，然后按顺序加载并执行。这个机制的关键在于“按需加载”——上下文里只保留当前正在用的技能，用完就释放，避免上下文被无关指令撑爆。我实测下来，这个设计对长任务的稳定性提升非常明显，尤其是那种需要来回切换“写代码”和“跑测试”的场景。

2.2 技能框架和普通提示词模板的本质区别

很多人会把 superpowers 和网上那些“Claude Code 提示词模板”混为一谈，其实差别很大。普通提示词模板是静态的，你复制粘贴进去，模型照着做，做完就完了。而 superpowers 的技能是可组合、可编排、可条件触发的。举个例子，一个“写单元测试”的技能，它可能包含“先读被测代码”“识别边界条件”“生成测试用例”“运行测试”“如果失败则分析原因”这几个子步骤，而且这些子步骤之间是有状态传递的。更关键的是，技能可以被其他技能调用，比如“修复 bug”技能在执行过程中发现需要补测试，就可以动态调用“写单元测试”技能。这种嵌套和组合能力，是静态提示词做不到的。

从工程角度看，这其实借鉴了软件工程里“模块化”和“关注点分离”的思想。把一个大而全的流程拆成小颗粒度的技能，每个技能只负责一件事，做好一件事。这样不仅 AI 执行起来更稳，人类维护起来也更容易——哪个技能效果不好，单独改那个技能就行，不用动整个流程。

2.3 为什么这个框架对 Claude Code 和 Codex CLI 特别重要

Claude Code 和 Codex CLI 这类工具的本质是“命令行里的 AI 智能体”，它们能读文件、写文件、执行终端命令、查看输出。这个能力很强，但也很危险——如果 AI 没有一个清晰的执行框架，它很容易陷入“乱试”的状态，比如反复执行同一个失败命令，或者改了一个文件忘了改另一个。superpowers 提供的技能框架，相当于给这些智能体加了一层“行为约束层”：什么阶段该做什么、做完之后该验证什么、验证失败该回退还是继续，都有明确的技能定义。

我自己的体会是，没有技能框架的时候，Claude Code 更像一个“反应很快但有点莽的实习生”；有了技能框架之后，它更像一个“知道先看文档再动手、改完会自己跑测试的靠谱同事”。这个差别在简单任务上不明显，但在涉及多文件、多步骤、需要反复验证的任务上，差距是数量级的。

3. 核心技能类型全解析：superpowers 里到底有哪些 skills

3.1 规划类技能：让 AI 先想清楚再动手

规划类技能是整个框架的入口。我见过的典型技能包括“需求澄清”“任务拆解”“方案对比”“风险评估”。这些技能的核心作用是在写第一行代码之前，逼 AI 把问题想清楚。比如“任务拆解”技能，它会要求 AI 把一个大需求拆成若干可独立验证的小任务，每个小任务有明确的输入、输出和验收标准。这个步骤看起来简单，但实际用下来，它能挡掉至少一半的“方向性错误”。

我印象很深的一次，我让 Claude Code 帮我加一个“用户登录失败次数限制”的功能。没有规划技能的时候，它直接就开始改中间件代码了。用了规划技能之后，它先输出了一份拆解：第一步确认现有登录流程、第二步确定计数存储位置、第三步设计过期策略、第四步改中间件、第五步补测试。结果在第一步就发现现有登录流程里已经有一个类似的计数逻辑，只是没启用。如果直接改，很可能就重复造轮子了。这个技能的价值，就在于它强制 AI 在动手前先“看一眼全局”。

3.2 编码类技能：把“写代码”拆成可验证的小步

编码类技能通常包括“读上下文”“写实现”“写测试”“重构”“处理边界条件”等。这里面的关键设计是每一步都要有验证。比如“写实现”技能执行完之后，不是直接进入下一个功能，而是触发“写测试”技能，测试跑通之后才算这个技能完成。这种“小步验证”的思路，跟敏捷开发里的 TDD 很像，但执行者是 AI。

我实测下来，编码类技能里最有用的是“读上下文”这个看似不起眼的技能。它要求 AI 在改任何代码之前，先读相关的文件、理解现有的代码风格、找到类似的实现作为参考。这个技能能显著减少“AI 写出来的代码风格跟项目格格不入”的问题。以前我经常要花时间把 AI 写的代码改成项目风格，现在这个问题基本消失了。

3.3 验证类技能：跑测试、查日志、做回归

验证类技能是 superpowers 里我最看重的部分，包括“运行测试”“分析失败原因”“检查日志”“回归验证”等。这些技能的核心逻辑是：AI 不能自己说自己写对了，必须用外部信号来证明。跑测试是最直接的信号，但测试通过不代表没问题，所以还需要“检查日志”和“回归验证”来兜底。

这里有个细节值得说：验证类技能通常会定义“失败后的行为”。比如测试失败时，AI 应该先分析失败原因，判断是测试写错了还是实现写错了，而不是直接改实现去迎合测试。这个判断逻辑如果写得好，能避免很多“为了过测试而写错代码”的情况。我自己就遇到过 AI 把测试断言改弱来让测试通过的情况，加了验证技能之后，这种行为被明确禁止了。

3.4 协作类技能：提交、写文档、同步进度

协作类技能包括“写提交信息”“更新文档”“同步任务状态”等。这些技能在单人开发时容易被忽略，但在团队协作里非常重要。比如“写提交信息”技能，它会要求 AI 按照项目的提交规范来写，包含变更类型、影响范围、关联任务号等。这个技能看起来小，但能省掉很多后期整理提交历史的时间。

我个人的经验是，协作类技能的价值在“交接”场景下最明显。当你把一个 AI 辅助完成的任务交给同事时，如果提交信息清晰、文档更新到位，同事接手成本会低很多。反之，如果 AI 只改了代码没更新文档，同事可能得花半天时间才能搞明白改了什么。

4. 怎么把这些技能引入到 Claude Code 和 Codex CLI 里

4.1 引入前的环境准备：Claude Code 和 Codex CLI 的安装确认

在引入 superpowers 之前，得先确保你的 Claude Code 或 Codex CLI 能正常跑起来。Claude Code 的安装方式根据平台不太一样，Mac 和 Ubuntu 上通常是通过包管理器或者官方提供的安装脚本，Windows 上则需要注意 64 位兼容性问题，有些老版本会报“与 64 位版本的 Windows 不兼容”的错误，这种情况一般升级到最新版就能解决。安装完之后，用claude --version确认一下版本，再用claude进一次交互模式，确保能正常对话。

Codex CLI 的安装相对简单一些，但要注意它的命令集和 Claude Code 不完全一样。常用的命令包括/compact用来压缩上下文、/model用来切换模型、/resume用来恢复之前的会话。如果你要删除 Codex CLI，记得先退出所有会话，再执行卸载命令，否则可能会有残留进程。另外，如果你在 VS Code 里用 Claude Code 插件，需要在设置里配置好路径和模型参数，不然插件可能找不到 CLI。

提示：安装过程中如果遇到“your organization has disabled claude subscription access”这类提示，通常是账号权限或订阅状态的问题，跟 superpowers 本身无关，先确认账号状态再继续。

4.2 技能引入的三种方式：手动、脚本、配置化

引入 superpowers 技能的方式，我试过三种。第一种是手动引入，就是把技能定义文件复制到项目的特定目录下，然后在对话里显式告诉 AI “加载某某技能”。这种方式最直接，适合刚开始尝试、想先看看效果的人。第二种是脚本引入，写一个初始化脚本，在启动 Claude Code 或 Codex CLI 时自动把技能目录挂载进去。这种方式适合固定项目，一次配置长期使用。第三种是配置化引入，把技能配置写进项目的配置文件里，AI 启动时自动读取并按需加载。这种方式最灵活，但配置项也最多，需要花点时间理解。

我个人的建议是先从手动引入开始，跑通一两个技能，确认效果符合预期之后，再逐步过渡到脚本或配置化。一上来就搞全套配置，很容易因为某个细节没配对而卡住，反而打击积极性。

4.3 技能加载的触发机制：什么时候该用哪个技能

技能加载的触发机制是 superpowers 的核心之一。通常有两种触发方式：显式触发和隐式触发。显式触发就是你在对话里直接说“用某某技能来做这件事”，AI 会加载对应技能。隐式触发则是 AI 根据任务类型自动判断该用哪个技能。隐式触发更省心，但对技能描述的准确性要求很高——如果技能描述写得模糊，AI 可能该用的时候不用，不该用的时候乱用。

我自己的做法是：关键流程用显式触发，确保不会漏；辅助流程用隐式触发，减少手动干预。比如“写测试”和“跑测试”这两个技能，我会显式触发，因为漏掉测试的代价比较大。而“写提交信息”这种，隐式触发就够了，AI 判断该写的时候自然会写。

5. 实操过程：从零搭建一个带技能框架的开发流

5.1 第一步：确定你的项目需要哪些技能

不是所有项目都需要全套技能。我的经验是，先列出你日常开发里最重复、最容易出错、最耗时间的环节，这些环节就是最该技能化的。比如一个后端 API 项目，最重复的可能是“写接口”“写测试”“跑测试”“写文档”；一个前端项目，最重复的可能是“改组件”“调样式”“跑构建”。把这些环节列出来，再去 superpowers 的技能库里找对应的技能，或者自己写一个。

这里有个坑要注意：不要一开始就追求大而全。我见过有人一上来就配了二十多个技能，结果 AI 每次启动都要花时间判断该用哪个，反而变慢了。先从三到五个核心技能开始，跑顺了再逐步加。

5.2 第二步：配置技能目录和加载路径

技能目录的配置方式取决于你用的工具。Claude Code 通常会在项目根目录下找特定的配置目录，Codex CLI 则可能通过环境变量或命令行参数指定。我一般会在项目根目录建一个.skills目录，把技能定义文件放进去，然后在启动命令里加上路径参数。这样技能文件跟项目代码在一起，版本管理也方便。

配置的时候要注意路径的写法，Windows 和 Unix 系统的路径分隔符不一样，写错了会导致技能加载失败。另外，如果技能文件里有引用其他文件（比如模板、示例），要确保相对路径是对的，不然 AI 加载技能时会报“找不到文件”。

5.3 第三步：跑一个完整任务，观察技能调用链

配置好之后，找一个真实的小任务跑一遍，比如“给现有函数加一个参数校验”。跑的时候注意观察 AI 的调用链：它先用了哪个技能、中间有没有跳过该用的技能、验证环节有没有执行。我第一次跑的时候，发现 AI 跳过了“读上下文”技能，直接开始改代码，结果改出来的风格跟项目不一致。后来我把“读上下文”技能的触发条件写得更明确，这个问题就解决了。

观察调用链还有一个好处，就是能发现技能之间的衔接问题。比如“写实现”技能完成之后，应该自动触发“写测试”技能，但如果触发条件没配好，可能就断了。这种衔接问题在单个技能测试时看不出来，只有跑完整任务才会暴露。

5.4 第四步：根据实际效果调整技能定义

技能定义不是一次写好的，需要根据实际效果反复调。我一般会关注三个指标：任务完成率、返工率、人工干预次数。如果某个技能经常导致返工，说明它的步骤定义有问题；如果人工干预次数多，说明技能的自动化程度不够。调整的时候，优先改技能的执行步骤和触发条件，而不是改技能的名字或描述——名字和描述影响的是 AI 的判断，步骤影响的是 AI 的执行。

我自己的经验是，技能定义里的“失败处理”部分最值得花时间打磨。比如测试失败时，AI 是该重试、该回退、还是该报告给人，这个逻辑写清楚了，整个流程的稳定性会提升一大截。

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

6.1 技能加载失败：路径、权限、格式三大排查方向

技能加载失败是最常见的问题，排查顺序一般是：先看路径对不对，再看权限够不够，最后看格式有没有问题。路径问题最常见的是相对路径写错，尤其是在不同操作系统之间切换时。权限问题通常出现在技能文件放在系统目录下、当前用户没有读权限的情况。格式问题则多是 YAML 或 JSON 的缩进、引号、逗号写错了，这种错误往往有明确的报错信息，照着改就行。

我遇到过一次比较隐蔽的加载失败：技能文件本身没问题，但文件编码是 GBK 而不是 UTF-8，导致 AI 读出来是乱码，加载就失败了。这种问题没有明显报错，只能靠检查文件编码来发现。所以我现在养成了一个习惯，所有技能文件统一用 UTF-8 编码保存。

6.2 技能不触发：描述模糊和触发条件冲突

技能不触发的原因通常有两个：一是技能描述太模糊，AI 判断不出该不该用；二是多个技能的触发条件有冲突，AI 不知道该用哪个。解决第一个问题的办法是把描述写具体，包含“什么时候用”“解决什么问题”“输入输出是什么”。解决第二个问题的办法是给技能排优先级，或者在触发条件里加上更明确的区分条件。

我踩过的一个坑是：两个技能都写了“当需要修改代码时触发”，结果 AI 每次改代码都要纠结用哪个。后来我把其中一个改成“当需要修改已有代码时触发”，另一个改成“当需要新增代码时触发”，冲突就解决了。

6.3 技能执行中断：上下文超限和命令超时

技能执行到一半中断，最常见的原因是上下文超限或命令超时。上下文超限通常发生在长任务里，技能加载太多、对话历史太长，把上下文撑爆了。解决办法是用/compact压缩上下文，或者把大任务拆成小任务分批执行。命令超时则多发生在跑测试或构建的时候，尤其是项目比较大的情况。解决办法是调整超时时间，或者把耗时的命令放到后台执行。

我自己的做法是，对于超过两分钟的命令，一律不放在技能里同步执行，而是让 AI 启动命令后先继续做别的事，过一会儿再回来检查结果。这样既能避免超时，又能提高整体效率。

6.4 技能效果不稳定：模型差异和温度参数

同一个技能，在不同模型上效果可能差很多。比如 Claude 系列模型在“读上下文”和“写测试”上表现比较稳，而一些开源模型在“任务拆解”上可能更强。如果你用第三方 API 接入其他模型，比如通过 cc switch 接入 deepseek、qwen、glm 等，需要针对模型特点调整技能定义。温度参数也有影响，温度高的时候 AI 更发散，适合规划类技能；温度低的时候更收敛，适合编码和验证类技能。

我一般会在配置里给不同类型的技能设不同的温度，规划类设 0.7 左右，编码类设 0.2 左右，验证类设 0.1 左右。这个不是绝对标准，但实测下来比统一温度效果好不少。

6.5 常见问题速查表

7. 我踩过的坑和几条实在建议

第一个坑是技能定义写得太理想化。我一开始写的技能定义，步骤特别细，恨不得把每一步的操作都写死。结果 AI 执行的时候反而束手束脚，遇到定义里没覆盖的情况就卡住了。后来我把定义改成“目标 + 约束 + 验收标准”的结构，给 AI 留出判断空间，效果反而更好。技能定义不是越细越好，关键是说清楚“要什么”和“不要什么”。

第二个坑是忽略技能的维护成本。技能写多了之后，改一个流程可能要动好几个技能文件，改完还得重新测试。我现在的做法是，把技能按“核心”和“辅助”分级，核心技能严格维护，辅助技能允许一定程度的粗糙。这样既保证了关键流程的稳定，又不会在次要技能上花太多时间。

第三个坑是过度依赖隐式触发。隐式触发确实省心，但一旦 AI 判断错了，排查起来很麻烦。我现在对关键技能一律用显式触发，虽然多打几个字，但心里踏实。隐式触发只用在那些“用了更好、不用也行”的技能上。

最后分享一个小技巧：给技能加版本号。技能定义改来改去，有时候改坏了想回退，没有版本号就很难受。我现在每个技能文件里都写一个版本号，改之前先备份，改完记录改了什么。这个习惯看起来麻烦，但真出问题的时候能省很多时间。

这个框架后续还可以往几个方向扩展：一是把技能和项目的 CI/CD 流程打通，让 AI 提交代码后自动触发流水线；二是把技能和团队的知识库结合，让 AI 在写代码时能参考团队的历史决策；三是把技能做成可分享的包，团队之间互相复用。这些方向我自己也在摸索，有进展了再跟大家分享。