企业官网建设流程全解析

1. 先搞清楚：superpowers 到底解决的是什么问题

1.1 为什么"提示词技巧"解决不了效率问题

我差不多每天都泡在 AI 编程助手里，从补全代码到自动改 bug、重构模块，甚至写 commit message。用久了你会发现一个尴尬的事实：同样一个助手，在别人手里是"超级工程师"，在我手里就是个"听话但健忘的小实习生"。你说一步它做一步，稍微绕一点就断片，同一个错误能犯三遍。

一开始我以为是模型不够聪明，于是开始疯狂囤提示词模板。什么 "act as a senior engineer"、什么 "think step by step"、什么 "explain your reasoning before coding"，效果有，但很有限。原因是这些提示词只是一时的"状态注入"，换个会话、换个项目，它又忘了。你不可能把几十个项目的工程经验都塞进一段咒语里，而且上下文窗口也不允许。

后来我在社区里看到一个叫 superpowers 的开源项目，它的思路完全不一样：不靠更长的提示词，而是把"干活的经验"做成一个个可复用的技能文件，让 AI 助手在需要的时候自己去读、去调用。这个概念一下就点醒了我——我们要给助手的不该是鞭子，而是它自己的工具箱。这篇内容我想围绕它的实际安装、技能清单和引入方式，把我自己的使用心得完整摊开来讲。

1.2 superpowers 的核心思路：把经验编译成可调用的技能

所谓 "superpowers"，你可以理解为一组"技能包"或者"能力插件"，专门用来增强 AI 编程助手的稳定性。它的基本假设是：人在写代码的时候会依靠"经验模式"，比如遇到线上 bug 先复现、再定位、再修复、最后回归；但 AI 助手每次都是"从零开始推理"，没有这种模式记忆。如果能把这个模式写下来，让助手在开工前先读一遍，它的行为会立刻变得专业不少。

这个项目本质上就是一堆 Markdown 文件，每个文件描述一个特定的任务流程：如何对代码做架构分析、如何拆解复杂任务、如何写可验证的测试、如何在改完代码后做自检……但是它的厉害之处在于组织方式。它不是让你把所有规则都堆在系统提示词里，而是提供了一套"按需加载"机制：助手根据用户当前的任务，主动去翻对应的技能文件，只把相关的那几段内容放到上下文中。

从工程角度讲，这其实是在做"外部记忆 + 工作流管理"。AI 助手本来上下文有限，你没法让它同时记住一百条规矩，但你可以让它知道"有本手册在某处，遇到什么问题就翻哪一章"。这就好比一个新手厨师不必背下整本菜谱，只需要知道"红烧肉"在菜谱第 12 页，做的时候翻到那一页照着做就行。

2. 打开技能清单：它内置了哪些有用的 skills

拿到 superpowers 之后，我第一件事就是去看它到底有哪些 skills。很多人和我一样，装上就想玩，结果一股脑全启用，上下文立刻爆炸。所以先弄清每个技能的职责，比急着安装更重要。

2.1 规划与分解类技能

这类技能解决的是"面对一个模糊的大需求，怎么拆成可以逐步执行的子任务"。比如brainstorming（头脑风暴）用于在正式动手前生成多个候选方案，planning（规划）则把选中的方案细化成带验证步骤的实施计划，task-breakdown（任务分解）负责把计划拆成 AI 能在单次会话中完成的小步操作。

我实际用下来，最常用的是planning。以前我说"帮我实现一个用户登录模块"，助手会直接甩一堆代码出来，结果往往和项目现有结构脱节。引入 planning 技能后，它会先花二十秒问我要需求细节，然后输出一个步骤清单，每步都带验收条件。这一步相当于让助手从"埋头写代码"切换到了"先当架构师，再当程序员"，整体翻车率低了很多。

2.2 代码修改与审查类技能

这类技能负责让改动更稳妥。code-review（代码审查）用来对已完成的 diff 做同行评审，refactoring（重构）着重在保持行为不变的前提下改进结构，bug-fixing（缺陷修复）则定义了从复现到根因分析再到回归验证的标准流程。

如果你用过 AI 修 bug，一定体会过"改一处坏一处"的滋味。bug-fixing这个 skill 的流程特别接地气：第一步是找最小复现路径，第二步是定位根因而不是修表象，第三步才是动手改，改完还要跑相关测试。表面上看这些步骤多花了一点时间，但它能帮你把"碰运气式修复"变成"确定性修复"。

2.3 调试与跟进类技能

再往下是debugging（调试）和test-writing（测试编写）。debugging专门用来应对跑起来报错但不清楚原因的场景，它会引导 AI 先收集错误信息和调用栈，再针对性地插入日志，逐步缩小范围。test-writing则不是简单生成单测，而是遵循一个"先写失败用例，再实现，再让用例通过"的 TDD 流程。

这两个技能配合起来效果很好。我处理过一个诡异的内存泄漏，之前助手只会建议我"检查一下循环引用"，听起来像玄学。后来启用debugging技能，它先让我用--prof跑一遍压测，收集内存曲线，再二分注释可疑模块，最终定位到我在缓存清理时的边界条件写错了，问题直接指向那一行。这种"有流程"的调试方式，比随机猜测靠谱得多。

2.4 文件与文档处理类技能

还有一批技能和代码关系不大，但非常实用。比如documentation（文档生成）用来维护 README、架构说明和 API 文档的时效性；commit-message（提交信息）负责把改动拆成符合规范的多条 commit；pr-description（拉取请求描述）可以自动生成给团队看的 PR 说明，包含背景、改动点、测试结果和风险提示。

这类技能的共同特点是"输出结构化信息"。以前让 AI 写 commit message，它总是一股脑写一行 "fix bugs"，没有逻辑。现在 superpowers 会为每次改动生成类型分明、带影响范围的提交说明，甚至能自动判断是 feat、fix 还是 refactor。对我们这种需要维护多个分支的团队来说，这一项就省了至少半小时的整理时间。

3. 实际安装步骤与"引入技能"的几种方式

这一节聊大家都关心的：到底怎么安装、怎么把技能真正引入到你的编辑器或终端里。市面上的教程大多只给一条命令，但实际使用中你会发现有不同的安装需求，我把最常见的三种路线列出来，你可以根据自己的情况选。

3.1 环境准备：Node.js 与 Git

在开始之前，先确认你的机器上有 Node.js 18+ 和 Git。一般日常开发环境都满足，但如果你用的是精简镜像或者远程开发机，很可能缺这一步。我踩过这个坑：项目拉到一半提示git: command not found，而 superpowers 的安装脚本依赖 Git 来拉取仓库。检查命令很简单：

node -v git --version

如果 node 版本低于 18，建议先升级；如果 git 没有，就先把基础工具装好。这里不需要什么花哨配置，版本满足即可。另外，安装过程不需要管理员权限，也不改全局系统路径，这一点比较友好。整个工具会装在你当前用户的目录下，对于公司电脑或者容器环境来说，权限问题少很多。

3.2 方式A：用脚手架一次性安装

如果你是想在项目里整个启用 superpowers，最省事的方式是用它的安装脚本。在项目根目录执行：

npx @superpowers/cli init

这个命令会做几件事：检查当前目录是不是 Git 仓库、下载官方 skills 库、在项目下生成.superpowers文件夹和配置文件。执行过程中它会问你要启用哪些技能包，你可以先选"全部"看看效果，也可以在后面的配置文件里随时增删。

装完之后，需要在助手的配置里指向这个项目目录。以我的使用习惯为例，我通常在 VS Code 的 AI 对话插件中补充一句系统指令："当任务涉及架构分析时，先查看项目根目录下 .superpowers/skills 中的相关技能。"这样助手才会知道去哪里找技能。如果你用的是终端类助手，也可以把这句话加进项目级说明文件里，保证每次会话都能看到。

3.3 方式B：手动 clone 来引入

有些场景你不希望用 npx，比如公司内网环境没有公共 npm 源，或者你想直接基于源码进行二次改造。这时候手动 clone 反而更可控：

git clone https://github.com/superpowers-org/superpowers.git .superpowers

然后自己写一个配置文件，指向你 clone 下来的技能目录。手动方式的好处是：你可以只保留自己需要的技能，删除不用的，甚至可以直接修改技能的 Markdown 内容。坏处是后续官方更新你需要自己去合并。如果你对 Git 比较熟，我推荐这种方式，因为你会对这个工具的内部结构有更清晰的理解——后续写自定义技能的时候特别有用。

3.4 方式C：只引入个别技能（按需安装）

如果你不想为整个框架增加复杂度，也可以只把单个技能文件复制到你的项目里。比如我只需要bug-fixing这个技能，那就直接从 skills 目录里把它单独拷出来，放到.superpowers/skills/bug-fixing.md。然后在你的助手系统提示词里说明"若任务涉及缺陷修复，优先参考 bug-fixing 技能"。

这种方式很轻量，适合已经有一套成熟工作流、只想要某一环补强的团队。缺点是失去了技能之间的协作性——像planning和task-breakdown单独用效果远不如组合起来。我的建议是：先全量安装感受整体流程，再逐步按需瘦身。一上来就只引入单个技能，很容易因为上下文不足而体验不到它的威力。

4. 引入技能后的正确使用姿势

安装只是开始，真正能拉开体验差距的是"怎么用"。我发现很多人装上 superpowers 之后觉得没用，往往不是因为工具不行，而是命令方式不对，或者期望它自动生效。技能文件本质上是一份"说明书"，你得让它有机会被读到，并且在合适的时机被触发。

4.1 技能是怎么被调用的

superpowers 的调用方式不是"告诉 AI 去用技能"，而是把技能文件的内容暴露给 AI 的上下文读取机制。一般有三种路径：

• 自动触发：当助手检测到任务关键词（比如"修复 bug"）时，自动去技能目录里找匹配文件。
• 显式引用：你在提问时直接写"参考 bug-fixing 技能完成修复"，助手会打开对应文件遵循流程。
• 项目级常驻：把常用技能的核心要点写进项目的.ai规则文件里，让助手每次都在这些原则下工作。

我实测下来，最稳定的是显式引用。因为自动触发依赖关键词匹配，很容易出现"提到了 bug 但想让你加功能"这种误判。而如果你在每次涉及关键操作时，都明说"按某个技能来做"，效果会立竿见影。不要担心这句话啰嗦，AI 助手很吃这一套，你等于是在给它指路。

4.2 给技能传递上下文：别忘了写"背景说明"

技能文件是通用的，但你的项目是特殊的。比如planning技能只能指导助手"如何做计划"，它不自动知道你的项目是前端还是后端、用的是 Vue 还是 React、测试框架是 Jest 还是 Vitest。所以你在触发技能的同时，得把必要的背景信息一起交给 AI。

老实说，这是很多人的误区。他们启动planning之后，AI 输出的计划还是泛泛而谈，因为缺少了"项目背景"输入。我现在习惯的做法是：在提问的开头先用两三句话交代当前项目技术栈和本次目标，再引技能。举个例子：

我们这是一个基于 Next.js 15 的电商后台，数据库用的 PostgreSQL，迁移工具是 Prisma。请参考 planning 技能，帮我设计"订单批量导出"功能的实现步骤，需要包含数据量限制和异步处理方案。

同样是调用planning，有背景和没背景出来的计划质量完全两个级别。技能负责"怎么思考"，背景负责"往哪个方向思考"，两者缺一不可。

4.3 什么时候不要用技能

这一点可能比"怎么用"更重要。superpowers 里的技能是面向复杂任务的，但不意味着所有任务都要走一遍重流程。比如改一个按钮颜色，你非要用planning技能做三步拆解，纯属给自己添堵。我自己的判断标准是"这段操作是否可能造成不可逆影响"：

• 改样式、调文案、写简单函数：直接用，不要让 AI 走完整流程。
• 重构模块、修改数据层、调整核心逻辑：必须用技能。
• 处理线上故障：优先用bug-fixing/debugging，并且明确跳过头脑风暴环节。

另外，如果当前会话的上下文已经很长，接近模型上下文上限，这时候再让 AI 去读一个几千字的技能文件，大概率会丢失前面的重要信息。我一般在会话超过十轮之后，会手动清理无用的历史消息，或者开一个新会话并把关键背景摘要带过去，再让 AI 触发技能。这不是 superpowers 的问题，而是所有长上下文场景的共同坑。

5. 我在实际使用中踩过的坑：路径、优先级和上下文失控

任何工具都是在踩坑中才能真正上手的。下面这几个问题我花了两个礼拜才摸透，分享出来，希望能帮你省掉这部分时间。

5.1 技能文件的路径解析错位

第一次我用方式 B 手动 clone 的时候，把仓库放在了项目根目录的.superpowers下，但配置里写成了相对路径.superpowers/skills，导致某些技能死活加载不出来，也没有任何报错。后来才发现，AI 助手的工作目录可能和终端不一致，特别是使用项目级配置文件时，路径会被解析为相对于某个子目录的位置。

解决方法是：在配置里优先使用绝对路径，或者统一约定所有文件都放在项目根目录下，并在助手的配置文件中显式声明工作目录。我个人的习惯是写一条规则："所有技能文件位于 /workspace/.superpowers/skills 目录下，以 Markdown 格式存储。"虽然看起来不够优雅，但绝对不会有歧义。对于动态项目目录，可以靠环境变量拼路径，但一定要注意拼接方向。

5.2 多个技能同时命中的优先级问题

你会遇到这种情况：任务描述是"重构订单模块并且修复一个 bug"，此时refactoring和bug-fixing两个技能都可能被触发。如果两个技能的内容同时灌入上下文，AI 会左右为难，输出的方案既不像重构也不像修复，反而更容易出错。

我现在的处理方式是在显式引用时指定主技能。如果是"先修 bug 再重构"，就明确说"先按照 bug-fixing 技能完成修复，再按照 refactoring 技能评估重构方案"。如果确实需要多个技能协作，我会把它们串成一个流程，而不是并行。本质上，一次聚焦一个核心目标，AI 的完成度会高很多。实在要同时处理，不如拆成两次会话，减少认知负荷。

5.3 上下文被技能描述刷爆

superpowers 的每个技能文件都有相当篇幅，包含了背景、步骤、示例和检查清单。如果你一次触发三个技能，可能语音助手还没开始写代码，上下文窗口已经用了上万 token。这会把主要任务的空间挤占掉，导致输出质量下降。

对这个坑，我做了两个改进。第一是在技能说明里手动删减不需要的示例部分，只保留步骤和关键提示。第二是在触发时告诉 AI："请只提炼技能的核心步骤，不需要复述示例。"实验下来，这样能省掉 40% 左右的上下文。尤其是项目整体能力已经稳定之后，冗余的示例反而是噪音。

5.4 技能对仓库行为的预估失灵

技能文件是静态的，但你的仓库是动态的。有时候refactoring技能建议的步骤依赖某些重构工具（比如适用的 codemod），而你的项目并没有安装这个工具。这时候 AI 会按照记忆中的"推荐工具"给你命令，结果自然是报错。

遇到这种情况，我的做法是：在技能文件里增加一个前置检查步骤，明确要求 AI 在动手前先验证依赖是否存在。你可以改技能模板，也可以在与 AI 对话时强调"所有推荐的命令必须先做可行性确认，再真正执行"。这其实反映了技能生态的一个重要原则：技能是指导原则，不是银弹，它必须结合你仓库的真实情况来调整。

6. 把手上的经验沉淀成你自己的 skill

用了一段时间 superpowers 之后，我最大的感受是：它提供的技能很好，但真正的价值在于给我搭了一个框架，让我能把团队内部的经验也结构化保存下来。这一节聊聊怎么写一个自己的 skill。

6.1 一个最小技能的结构

一个技能文件并不神秘，说白了就是一份有固定结构的 Markdown。我的最小模板是这样：

--- name: api-field-migration description: 当你需要迁移或调整 API 字段时使用本技能，避免破坏历史调用。 when_to_use: 涉及接口字段增删改、模型序列化变更时 --- ## 执行步骤 1. 梳理当前 API 的所有调用方和服务端定义 2. 列出字段变更清单，标记 breaking change 与非破坏性变更 3. 按先服务端兼容、再客户端切换、最后清理废弃字段的顺序执行 4. 显式编写迁移测试，验证旧字段在过渡期仍可用 ## 检查清单 - [ ] 是否修改了对外文档 - [ ] 是否更新了 mock 数据 - [ ] 是否保留了至少一个版本的兼容

头部用 YAML 定义元信息，正文字干净利落。把这样一个文件放进.superpowers/skills目录，然后给 AI 一句提示："当任务涉及 API 字段变更时，请先参考 api-field-migration 技能。"从此以后，团队新成员用 AI 助手也不会踩同样的坑了。

6.2 避免"假技能"：可验证与可撤销

写技能最忌讳的是"正确的废话"。比如"确保代码质量""注意边界情况"这种描述，AI 看了和没看一样，因为它没法执行。一个真正有用的技能应该包含两类内容：一是可验证的中间产物，二是可回滚的兜底方案。

我自己的检查标准是：如果按照技能执行完，你拿不出一个"验收结果"来证明做对了，那这就不是技能，只是一条建议。比如上面我的 api-field-migration 技能，验收结果是"迁移测试通过 + 文档已更新 + 旧字段兼容"，三条都满足才算完成。同时我要求 AI 在动手前先确认 Git 有干净的提交记录，这样出问题能随时回退。可撤销性非常重要，AI 执行多步骤任务时难免跑偏，有一个退路会让人安心很多。

6.3 版本管理：技能也是代码

最后强调一个容易被忽略的点：技能文件本身也是项目资产，需要做版本管理。我见过不少人直接往.superpowers/skills里扔了一堆 Markdown，不写 commit，不写变更记录。等到某天技能被改得面目全非，再想查"原来的规则是什么样的"就完全无从下手了。

最好的做法是把.superpowers目录纳入 Git 跟踪，每次修改技能之后，用一句 commit 描述变更原因。如果团队里有多个角色使用 AI 助手，还可以用分支来维护不同方向的技能集，稳定之后再合并。如果你定义了比较通用的流程，也欢迎把它抽离成独立仓库，分享给其他项目甚至社区。一旦开始写自定义技能，你会发现这其实是在建立一个"团队的集体经验库"，越积累越值钱。

说实话，superpowers 并不是什么黑魔法，它只是把那些优秀工程师脑子里"理所当然"的经验显性化了。安装它、使用它、然后改造它，这个过程中最受益的其实不是 AI，而是你自己——你会被迫去思考自己平时到底是怎么解决问题的。愿意把这种思考落到文档里的人，无论用不用这个工具，写出来的代码都不会差。