企业官网建设流程全解析

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

说实话，第一次在开源社区刷到“superpowers”这个词的时候，我以为是哪个游戏MOD或者效率工具合集。直到我真正在AI编程工作流里把它跑起来，才意识到这是一套完全不同的东西。

简单说，superpowers是一套基于开源社区常见的Agent Skills规范构建的AI技能包，核心是让AI助手（目前主要适配Claude Code这类终端型AI编程工具）从“能聊天的聪明人”变成“有工作方法的老工程师”。它解决的最大痛点不是AI不懂某个知识点，而是AI拿到任务后经常直接开干、缺乏结构化拆解、做完不验证、改了代码不跑测试——这些问题在小任务上不明显，一旦面对真实项目，就会被无限放大。

这套技能体系把人类工程师的工作习惯拆成了一个个可复用的SKILL.md文件。每个技能文件里不是几行prompt提示词，而是一套完整的操作流程：什么时候触发、先做什么、后做什么、每一步有哪些检查清单、遇到什么情况要停下来问人。就好比你把一个三年经验工程师的思考过程，完完整整写成了SOP，然后让AI照着执行。

我推荐以下三类人重点看看这个项目：

• 刚接触AI编程工具、想让AI真正参与项目开发，而不只是生成代码片段的开发者
• 已经在用Claude Code等终端AI工具，但总觉得AI输出质量不稳定的重度用户
• 负责团队AI工具落地、想把团队编码规范沉淀成可复用资产的技术负责人

下面我会从安装、核心技能拆解、引入方式、实战组合、问题排查这几个维度，把我这两个多月的使用经验完整分享出来。

2. 安装与初始配置：10分钟跑起来，别跳过前置检查

2.1 安装前置条件：先确认你的环境够不够新

很多人在安装这一步就卡住了，大部分原因是环境版本太老。superpowers的安装器依赖较新的Node.js运行时和配套的CLI环境，这几个条件缺一不可：

• Node.js版本需要较新（建议22及以上，至少不低于20）
• 已安装Claude Code或其他支持Agent Skills能力的终端AI工具，一般需要通过官方渠道安装并登录
• 系统已安装git，且当前用户对目标目录有写权限
• 终端可以正常访问GitHub（安装过程需要拉取仓库）

我的建议是安装前先跑一遍版本检查，别凭感觉：

node -v git --version

如果你发现node版本偏低，建议先通过nvm这类版本管理工具切换。切完之后记得重启终端，否则PATH不会刷新。

注意：不要用sudo强行装到系统目录，除非你明确知道自己在做什么。权限问题导致安装半途失败的情况，我见了太多次。

2.2 一键安装流程：merge后直接setup，就这么简单

环境确认无误后，安装流程本身非常轻量。思路是这样的：先获取一个基础的项目骨架，然后运行项目自带的setup脚本，由脚本自动完成依赖下载、技能文件生成等步骤。

git clone https://github.com/obra/superpowers.git cd superpowers npm run setup

setup脚本会询问你几个问题，比如技能安装到什么位置、是否需要启用全部技能。新手阶段直接选默认选项就行，后面可以随时调整。整个过程大概一两分钟，取决于你的网络状况。

装完之后，脚本会在你的用户目录或项目目录生成一个skills文件夹（具体位置取决于安装时选的模式）。打开这个文件夹，你会看到每个技能对应一个子目录，每个子目录里有一份SKILL.md和若干辅助文件。SKILL.md就是我们前面说的核心SOP文件，用Markdown写成，打开就能看懂。

2.3 装完之后怎么确认：不是看版本号，而是看技能列表

安装器不会输出一大串版本号让你兴奋一下，但你可以通过一条很简单的命令确认技能是否注册成功。在Claude Code会话中直接输入：

skills

AI会返回当前可用的技能列表，包括技能名称和一句简短说明。如果能列出完整清单，说明安装和配置都成功了。

如果你用的是CLI模式，也可以直接在命令行里检查技能目录结构：

ls -la skills/

正常情况下你能看到类似这样的目录：

skills/ ├── brainstorming/ ├── writing-plans/ ├── implementing/ ├── debugging/ ├── test-driven-development/ ├── subagent-driven-development/ ├── taking-breaks/ └── root-cause/

看到这8个目录，就可以放心进行下一步了。

3. 有哪些skills——把每个技能拆开看，别再当成黑箱

很多人在这一步犯的错误是：技能装好了，但完全不知道每个技能是干什么的，遇到问题时也不知道该让AI启用哪一个，结果又退回到原始的“直接提问”模式。这一节我按用途分类，把核心技能逐个讲清楚。

3.1 规划与拆解类：brainstorming和writing-plans

这两个技能解决的是“动手之前先想清楚”的问题。我在实际使用中发现，AI直接开干导致返工的概率非常高，尤其是需求本身模糊的时候。brainstorming的思路类似一次结构化的头脑风暴：AI会先忽略具体实现，引导你明确目标、约束条件、成功标准，然后给出多个候选方案并对比优缺点，最后和你确认选哪个方向。

writing-plans就更进一步了。它要求AI在真正动手写代码之前，先把实现计划落成文档：要改哪些文件、每个文件里做什么改动、改动顺序是什么、需要哪些测试来覆盖、哪些风险需要关注。这份计划会作为后续所有编码工作的基准。听起来麻烦，但实际用下来，它对大型改动非常有效。一次涉及十几个文件的改动，如果没有writing-plans，AI很可能改着改着就偏离了主线，最后代码能跑但架构已经乱了。

3.2 编码执行类：implementing和核心代码逻辑

implementing是真正写代码的技能。它有别于普通生成代码的地方在于，它要求AI按计划逐文件实现，而不是一口气把所有代码都吐出来。实现过程中AI会自己检查：这个函数依赖什么模块、导入路径是否正确、有没有把注释写进生产代码、改动是否和既定计划一致。我实测下来，逐文件实现加上每步自查，比一次性生成全部代码的出错率低得多。

implementing还有一个隐藏能力：它会主动检查代码风格一致性。比如项目里规定了使用错误码而不是异常，AI会在实现时遵守这个约定。这种细节在普通对话中往往要你反复提醒，但在技能约束下它会当成检查清单项严格执行。

3.3 质量保障类：test-driven-development和debugging

test-driven-development可能是整个superpowers中最有门槛、但收益最大的技能。它把TDD流程完整搬进了AI的工作方式：先写测试、跑测试确认失败（RED阶段）、写最小实现让测试通过（GREEN阶段）、重构保持测试全绿（REFACTOR阶段）。AI会自己维护一个工作清单，明确当前处于哪个阶段，而不是一次性把所有代码和测试全写完。

debugging技能则解决另一个头疼的问题：代码报错但不知道根因。它和普通“把错误信息丢给AI”的差异在于，debugging有一个明确的问题定位流程：先复现问题，再检查代码逻辑中最可疑的点，通过二分法缩小范围，修复后必须补一个回归测试防止复发。我以前遇到AI反复给出相同错误修复方案的情况，引入debugging技能后，AI会先停下来收集更多上下文，而不是又扔一个猜测性的补丁出来。

3.4 流程协作类：subagent-driven-development和taking-breaks

subagent-driven-development是一个偏高级的用法，适合改动范围大、上下文窗口不够用的场景。它的思想很直接：把任务拆成多个子任务，每个子任务交给独立的子agent执行，主agent负责拆解、验收和整合。这有点类似团队里一个架构师把模块分给不同开发者的做法。代价是需要消耗更多算力和token，所以我只在多文件改动时启用。

taking-breaks这个技能容易被低估，它的作用是让AI在长时间工作中主动停下来做阶段性总结，重新审视已完成的部分和目标是否仍然一致。它不会真的让AI“休息”，而是触发一次重新聚焦：回顾计划、检查已做改动、更新待办清单。我自己的体验是，连续进行大量改动后AI经常忘了最初的约束条件，taking-breaks就像一个检查点，降低这种“跑偏”的概率。

4. 怎么引入这些技能到日常流程——三种方式一次讲透

4.1 按项目引入：让整个项目的AI协作都遵守同一套规范

最推荐的引入方式是项目级安装。在项目根目录配置好skills文件夹后，AI的所有会话都会自动加载这些技能，不需要每次手动提起。这样团队成员在协作时，也能共用同一套AI工作规范。

我的做法是在项目根目录建一个skills目录，团队内部约定，所有和自动化编码、自动化审查相关的技能统一放这里，随代码仓库一起走。新成员clone下项目后，AI工具的技能配置自动生效，不需要额外安装。

如果你平时会用到GitHub的AI能力，也可以把技能文件提交到仓库的.agents/skills或对应目录下，让云端和本地保持一致。

4.2 按会话引入：一次对话里临时启用，用完即走

有些技能有副作用，比如debugging或taking-breaks会显著增加对话轮数，不适合全局常驻。这种情况建议按会话触发。

触发方式可以很自然，直接在对话中对AI说：

用subagent-driven-development的方式处理这个任务

或者更精准一点，只要求它在某个阶段切换模式：

先把改动分成三个独立子任务，每个子任务单独检查，最后我来复核

AI如果能识别到已加载的技能，就会切换到对应的执行流程。如果AI明确表示没有这个技能，多半是技能未注册成功，回到前面确认步骤。

提示：不要在一句话里同时触发多个流程型技能。我会建议你每次只启用一个主导技能，比如“先用brainstorming理清需求，再进入implementing实现”，而不是无脑叠加，否则AI的处理流程会互相冲突，输出反而更混乱。

4.3 自定义技能：把团队的规范沉淀成SKILL.md

这是superpowers最值得投入的部分。它不只是一堆别人写好的技能，更是一套自定义技能的标准格式。团队完全可以把自己的代码审查规范、发布流程、接口命名规范等写成新的SKILL.md，让AI严格执行。

一个标准的SKILL.md文件大概长这样：

--- name: frontend-code-review description: 在提交前端代码前执行，重点检查组件拆分、依赖引用、样式规范 --- ## 触发条件 - 用户要求检查前端代码 - 用户准备提交PR ## 执行步骤 1. 检查组件是否拆分过重，超过200行需要提醒 2. 检查是否直接引用node_modules内部路径 3. 检查样式是否使用CSS变量而非硬编码色值 4. 输出检查清单，标记通过/不通过项 ## 禁止事项 - 不修改代码，只输出检查结果 - 不在检查过程中调用其他工具修改文件

关键的格式要求有两处：开头用YAML格式声明技能名称和description，正文是Markdown写的执行流程。description很重要，它是AI判断何时触发技能的依据，所以尽量写清楚触发场景，别写得太宽泛。

我自己写技能的经验是：先记录你平时反复给AI强调的那些规则，比如“接口要用错误码不要抛异常”、“变量命名不要缩写”，这些就是最好的技能素材。整理成SKILL.md后，AI不用你每次重复，它会自动照着执行。

5. 实战经验：我用了两个月的组合打法、踩坑记录和优化建议

5.1 最推荐的工作流组合：按阶段切换技能

我跑了大量项目实践后，目前最顺手的工作流是分三阶段走：

第一阶段，需求不明确时，启用brainstorming。让AI不急着写代码，先展示它对问题的理解，列出实现方案，我从中判断它有没有跑偏。这个阶段通常只有几句话的来回，但能省掉后期大量返工。

第二阶段，方案定了但改动大，启用writing-plans让AI产出详细计划。我会盯着计划里有没有遗漏约束条件——比如“不改变现有数据结构”、“保持对外API兼容”，这些在实际写代码时极容易漏掉。

第三阶段，进入varied开发，启用implementing，配合test-driven-development低频使用。如果是功能明确的小改动，直接implementing；涉及核心模块的改动，我会强制走一遍TDD流程，先看测试再放行代码。

这里有一个我踩过的坑：很多人一上来就把所有技能都启用，以为功能越多越好。实际测试后发现，技能过多意味着AI每一轮对话都要扫描大量规则文件，响应速度变慢，而且不同技能之间可能给出互相矛盾的建议。我现在只保持必要的常驻技能，其他全部按需触发，效果反而更稳。

5.2 几个容易被忽略的注意事项

第一，版本兼容性问题。superpowers迭代很快，如果你之前装过其他Agent Skills的包，可能因为目录结构不同产生冲突。我碰到过一次两个技能包都定义了触发条件“代码完成后执行自检”，AI不知道怎么选择，最后执行了错误的那个。解决方案是在安装前清理旧的skills目录，或者用全局模式安装时指定覆盖。

第二，端侧依赖问题。如果你的项目生成代码时需要调用编译工具或包管理器，确保AI工具会话启动时的环境中这些命令可用。之前有个项目依赖pnpm，但AI默认用npm去装依赖，导致锁文件冲突。这种情况不是在技能文件里能解决的，需要你在项目配置里显式声明包管理器。

第三，上下文长度问题。启用subagent-driven-development这类重流程技能时，对话轮数显著增加，如果项目本身很大，很容易塞满上下文。我的做法是把大任务拆成几次会话，每次会话只处理一个子模块，通过进度文档衔接上下文。虽然多花了一点手动操作，但换来了每轮对话专注度的大幅提升。

5.3 一个实用的优化建议：阶段性自检，别让AI一口气跑到黑

不管启用哪个技能，我建议你在关键节点插入一个明确的检查指令：

做完当前这一步，先停下来，对照你最初的计划，列出已完成和未完成的部分，评估是否有偏离

这句话会强制AI做一次阶段性复盘，相当于给长跑加了一个折返点。我实际对比过，加入这句话之后，AI在多步骤任务中的完成度明显更高，尤其是那种涉及多个文件、多个步骤的复杂改动。

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

把这段时间在社区里遇到的高频问题整理成了一张速查表，并按排查思路给出建议。这部分的灵感来自我自己安装、使用的真实经历。

除了表格里的内容，我再补充三个排查方向。

如果你遇到的报错信息比较反常，第一件事是把完整日志贴出来，而不是只看最后一行。很多所谓“玄学失败”，最后发现都是环境变量缺失或网络代理问题。

如果技能内容加载正常但执行效果不理想，排查思路是打开SKILL.md文件看看描述里的触发条件。描述写得越具体，AI越容易在该触发时触发、不该触发时不触发。我见过一个团队拿superpowers跑前端代码审查，但AI总是拒绝执行，原因就是技能描述里用了“检查代码”这类过于宽泛的表述，AI在判断“这个场景是否适用”时始终犹豫。

如果你把技能文件做了自定义修改之后发现AI行为异常，先别急着改回去。你看看是不是把步骤之间的依赖关系写坏了。SKILL.md里的步骤是顺序执行的，如果我在第一步就要求“先运行全部测试”，但测试命令在项目里根本不存在，那AI就会卡在第一步原地打转。写自定义技能时，一定要在“执行步骤”里加上条件判断，比如“如果项目中没有test目录，跳过测试步骤并说明”。

最后再分享一个小技巧：建议你在熟悉这套体系之前，先拿一个玩具项目练手。找一个只有几百行代码的小项目，把所有技能跑一遍，感受每个技能的触发方式和输出风格。等你在小项目上摸清了规律，再拿真实项目实践，你会非常清晰地感受到，这个工具真正改变的不只是AI的输出质量，而是你整个研发流程的确定性——任务拆解有章法，执行过程有检查点，最终交付有验证。这套“把个人经验转写成结构化技能”的思路，用熟了之后，它就不只是一个AI插件，而是一套可复用的团队工作方法论。