企业官网建设流程全解析

1. 先搞清楚superpowers到底是什么

说实话，第一次看到"superpowers"这个名字，我以为是哪个超级英雄题材的开源项目。直到点进代码仓库，才发现这其实是一套给 AI 编程助手"叠buff"的工具链。它解决的问题非常实在：现在的 AI 编码助手，不管是 VS Code 里的 Copilot、终端里的 Claude Code，还是 Codex CLI，单点能力都挺强，用起来却总觉得差点意思——让它写一个函数，它能写得像模像样；让它把一个完整功能从头做到尾，它就容易跑偏、忘上下文、自作主张。

我自己在项目里裸用 AI 助手半年多，最大的痛点就是"失控感"：AI 不知道项目规范，不知道既有代码风格，也不知道什么时候该停下来问一句。superpowers 这套东西，恰好把这个问题拆成了两个可落地的方案：一套是可复用的"技能库"，一条是固定的工作流。技能库是纯 Markdown 写的知识模块，AI 干活的时候按需加载；工作流则把编码过程切成需求澄清、方案设计、实现编码、测试验证、缺陷修复几个阶段，强制 AI 按顺序走。

1.1 它不是又一个AI助手，而是AI助手的"外挂"

很多人第一次接触 superpowers，容易把它误当成一个独立的 AI 编程工具。其实它的定位更像是"外挂"：不自己出模型，不自己出算力，而是叠加在你已经有的 AI 编码工具之上，给这些工具补上"项目管理规范"和"领域知识"两块短板。

打个比方，裸用 Copilot 或 Claude Code，就像你雇了一个聪明但没什么经验的新人程序员：脑子转得快，代码写得动，但不知道你们团队的编码规范、不知道这个项目的历史包袱、不知道哪些依赖能引入哪些不能。superpowers 做的事情，就是给这个新人发了一本《团队工作手册》和一套《项目操作流程》。手册里写清楚了遇到各种情况该怎么处理，流程里规定了先干什么后干什么。这样一来，新人还是那个新人，但产出的质量立刻不一样了。

这套设计有一个很聪明的点：它不依赖某个特定厂商的 AI 服务。技能文件的格式是通用的 Markdown，工作流的定义也是文本化的，所以 Claude Code 能用，Codex CLI 也能用，VS Code 里的 Copilot Chat 同样能用。这意味着你换 AI 工具的时候，积累的技能库和流程规范可以原样带走，不会绑定在某一家上面。

1.2 一个真实场景：为什么我会被它圈粉

说个真实经历。前阵子我接了个内部工具的迭代需求，要给现有的订单管理系统加一个"批量导出"功能。以前我的做法是直接把需求丢给 Copilot，让它开写。结果几次下来都是同样的结局：第一版代码看起来思路清晰，一跑就发现漏了权限校验，补上权限又发现没处理大批量导出时的内存问题，再补又发现导出文件的格式规范和团队现有的不一致。来来回回改了四五轮，每次 AI 都是局部修修补补，完全没有全局意识。

用 superpowers 重走一遍这个需求，体验完全不同。它会先进入头脑风暴模式，主动问我：导出的数据量级是多少？是同步导出还是异步任务？权限粒度和查询列表页是否一致？导出文件的字段顺序有没有规范？这些问题我很多根本没想过，但确实都是上线前必须定的东西。需求澄清完，它给出一份实施计划，明确改哪几个文件、是否引入新的导出工具库、测试怎么覆盖。计划确认之后才开始写代码，写完自动跑测试，测试不过就进入调试流程。整个过程，我更像是在和一个有经验的同事结对，而不是在指挥一个"指哪打哪"的代码生成器。

如果你也受够了"AI 写代码一时爽、调试返工火葬场"的循环，这篇文章就是给你写的。下面我会把安装步骤、核心玩法、踩过的坑全部摊开，尽量做到你照着做就能跑通。

2. 核心设计拆解：为什么"技能+流程"的组合能大幅提升AI编码质量

2.1 技能库的本质：把经验固化成AI能读的知识模块

技能（Skills）这个概念，最近在 AI 工程领域挺火，superpowers 把它落地成了一种很朴素的形式：一个目录，里面放一堆 Markdown 文件，每个文件带 YAML 格式的属性头，声明这个技能的用途、适用场景和使用方法。你甚至可以把它理解成"给 AI 看的 Wiki 页面"，只不过这些页面会在恰当的时机被自动加载。

听起来简单，但这个设计解决了 AI 编程里一个很核心的问题——"上下文永远不够"。大模型的上下文窗口再大，也不可能在你让它改代码的时候，自动知道你要遵守什么编码规范、数据库连接串怎么配、测试要用什么命令跑。以前这些知识都散落在文档、Wiki、代码注释里，AI 看不到；现在把它们整理成技能文件，AI 在相关任务触发时就能主动去读。

举个实际例子。假设你们团队规定所有对外接口必须做入参校验、返回统一错误码。不用技能之前，你每次都得在对话里提醒 AI，而且它很可能做到第二次就忘了；用了技能之后，你在技能文件里写清楚"所有接口必须遵循 validation 规范，错误响应必须走 ErrorResponse 结构"，AI 在实现任何接口时都会先读这份文件，再动手写代码。这不是靠模型变聪明了，而是靠信息变得可达了。

技能文件的编写格式也很直白，核心就几个字段：名称、描述、什么时候用、具体规则。类似这样：

--- name: java-api-validation description: Java 接口开发必须遵守的校验与错误码规范 when_to_use: 创建或修改 Controller 层接口时 --- - 所有对外接口必须使用 @Valid 触发入参校验 - 校验失败统一返回 400 和 ErrorResponse 结构 - 业务异常使用 BizException，禁止吞异常

AI 读到when_to_use的描述，就知道该在什么场景下加载这份技能。这种"按需加载"的机制，比把全部规范塞进系统提示词里要高效得多，既不会占用太多上下文，也不会让 AI 被一堆无关规则干扰判断。

2.2 工作流设计：从需求澄清到验证修复的完整闭环

工作流是 superpowers 另一个核心。它要求 AI 在动手写代码之前，先过几个阶段：先用头脑风暴模式把需求聊清楚，把模糊的地方全部暴露出来；然后产出一份实施计划，明确改动范围、涉及文件、测试方案；计划通过后再开始编码；编码完成后进入验证阶段，让 AI 自己跑测试、检查构建；如果出了 bug，再用结构化的调试流程去定位修复。

每个阶段对应不同的系统提示词，AI 的角色和约束都不一样。头脑风暴阶段，AI 的任务是"提问"，是帮你把需求边界确定下来，这时候你让它写代码它会拒绝；计划阶段，AI 的任务是"设计"，输出的是实施方案和风险点，而不是一堆代码；到了实现阶段，AI 才真正开始写，而且必须严格按之前批准的计划执行，不能自己加戏。

这个设计背后的逻辑，其实是把软件工程里已经被验证多年的流程搬到了 AI 协作场景里。想想你自己写代码的时候，需求没搞清楚就开写，大概率返工；AI 也一样。如果不给它设计阶段，它可能在写完 200 行代码以后才发现需求没对齐，那返工成本就高了。更关键的是，跳过设计阶段，AI 很容易陷入"局部最优"：某个函数写得漂亮，但放到整个模块里架构是错的。有了计划环节，你在它动手之前就能纠正方向，这比事后改代码省力太多。

我后来自己带团队的时候，也把这个思路用在了新人培养上：先让新人复述需求、再让他写方案、方案通过才让动代码。效果比直接派活儿好得多。superpowers 只不过是把这套思路自动化、强制化了。

2.3 和裸用AI助手相比，它到底强在哪里

我用一个对比表格来总结差异，方便你直观感受：

这个表是我主观体验的总结，但基本代表了多数使用者的共识。不过也要说句公道话：裸用 AI 的自由度更高，适合探索性任务；superpowers 的流程化更强，适合正经的项目开发。两者不是替代关系，而是不同场景下的不同选择。

3. 安装与初始化：5分钟跑通superpowers环境

3.1 前置条件与版本要求

安装之前先确认环境。superpowers 不是一个独立运行的"AI"，而是一套附着在 AI 编码工具之上的增强层，这意味着你至少要满足两个前提：有一个能跑 AI 编码助手的开发环境，以及对应 AI 工具的正常使用权限。

我这边实测比较顺的组合是：Node.js 18 以上版本，VS Code 1.85 以上版本，Claude Code 或 Codex CLI 的近期版本。Node.js 主要用于跑脚本、MCP 服务，以及部分 npm 全局命令；VS Code 则是图形化操作的主要阵地。如果你是纯终端党，只用 Claude Code 或 Codex CLI 也没问题，superpowers 提供了对应的命令行接入方式，技能文件同样生效。

提示：版本建议直接用最新的。superpowers 迭代速度很快，早期版本里不少命令的命名和现在不一样，老教程看了容易对不上。我踩过一次坑：照着网上半年前的帖子配置，发现有个命令已经改过名，折腾了半天才反应过来。

另外，如果你想体验完整的 MCP 服务（比如浏览器自动化），需要确保本机能正常安装 Playwright 的内核。这点在 Windows 上尤其要注意，某些安全软件会拦截浏览器内核的安装，容易导致服务起不来。

3.2 三种安装方式对比与选择

就我实际用下来，有三种主流安装路子，适用场景不同，互相也不冲突。

第一种，VS Code 扩展市场安装。在扩展面板里搜索 "superpowers"，认准作者信息后直接安装。装完以后，VS Code 的 Copilot Chat 里会出现新的斜杠命令。这是最推荐新手的方式，图形化界面、可视化配置、出错提示都比较友好。

第二种，npm 全局安装。在终端执行npm install -g superpowers（具体包名以仓库 README 为准），然后跟随初始化引导完成配置。这种方式适合已经习惯命令行工具的开发者，配置完以后可以直接和 Claude Code 或 Codex CLI 配合使用。我个人的主力方式就是这种，因为大部分时间我都在终端里工作。

第三种，直接从 GitHub 仓库克隆源码并手动链接。这种方式适合需要改源码、做二次集成的开发者。我之所以后来专门试了一次，是想研究技能文件内部的组织方式，直接在本地代码里看更直观。如果你只是想用，没必要走这条路。

我的建议是：新手选第一种，先跑通再说；老手选第二种，效率高；想折腾的再考虑第三种。

3.3 初始化配置与验证

安装完只是第一步，关键是初始化。superpowers 首次运行会引导你设置工作区目录，其实就是指定你的技能文件放在哪里。这个目录建议直接用独立目录，比如~/.superpowers，别塞到某个项目里——否则每个仓库都重复一份，更新和维护都痛苦。

初始化的时候会让你选择启用哪些技能包。默认技能包覆盖了日常开发最基础的场景，比如代码审查、测试驱动、调试流程、Git 操作规范。刚开始别贪多，我见过有人一口气装了十几个技能包，结果 AI 每次都要遍历一遍技能清单，响应速度肉眼可见地变慢，而且部分技能之间还有规则冲突，AI 不知道听谁的，干脆两个都不遵守。

验证是否装好，很简单：打开一个测试项目，调起 AI 对话，输入/superpowers相关命令，如果能看到技能列表、工作流提示正常加载，就说明基础环境没问题。然后建立一个最简单的技能文件，让 AI 描述它读到了什么，它能准确答出来，就说明技能加载链路全通了。

4. 核心功能实操：技能调用、Jams 会话与 MCP 服务

4.1 常用斜杠命令与技能调用方式

在 VS Code 的 Copilot Chat 里，或者在 Claude Code 的终端里，superpowers 提供了一组斜杠命令。下面这些是我日常用得最多的：

这些命令实际就是调用了匹配的技能文件，把对应的系统提示词注入到当前对话里。所以你会看到，一旦调用/plan，AI 的回答风格立刻从"随手就能写代码"变成"认真分析方案、列出风险点、给出分步计划"。这种"角色切换"是靠技能文件里的系统提示词实现的，非常有效。

需要注意一点：这些命令的生效范围是当前会话。如果你在对话中聊了太久，工作流约束会被大量的闲聊和修改历史冲淡，AI 可能又回到"想到哪写到哪"的状态。这时候别硬撑，新建一个会话，重新调用命令，上下文干净了，它自然就回到规范流程上。

4.2 实战演示：用superpowers开发一个Java Spring Boot接口

搜「superpowers java」的人挺多，说明大家关注点很一致：这东西用到 Java 项目里到底怎么玩？我用一个真实场景演示：从零做一个 Spring Boot 的订单查询接口。

第一步，调用/brainstorm，告诉 AI"我想做一个查询订单详情的接口，涉及订单主表和订单明细表"。AI 会在头脑风暴模式下反问你一堆问题：接口是给内部系统还是对外？要不要分页？订单状态有几种？异常场景怎么处理？权限怎么控制？这些问题一问出来，你就知道自己原来根本没想清楚需求。我把边界定好以后，需求文档基本就有了，而且这些答案会作为后续实现的约束，AI 不会自己乱改。

第二步，/plan。AI 根据澄清后的需求输出实施计划，包括新建哪些类、修改哪些配置、接口路径和参数设计、单元测试覆盖点。这一步我会重点看它的技术选型和改动范围：如果它打算引入一个我没用过的框架，或者改动范围明显不合理，这时候提出来改还来得及，成本极低。这个环节是我认为整个流程里价值最高的——在写代码之前就把问题拦住。

第三步，/implement。AI 按计划逐文件实现。因为是 Java 项目，它知道要用 Maven 结构、用 JUnit 写测试、按加载的技能包遵守对应的编码规范。实现过程中它会遇到一些没用到的新依赖，如果技能包里配了"新增依赖必须确认"的规则，它会停下来问你要不要加，而不是自己偷偷改 pom.xml。这一点在团队项目里太重要了，依赖是软件供应链安全的第一道关。

第四步，跑测试。Java 项目的验证环节尤其重要，一个接口涉及 Controller、Service、Mapper 三层，任何一层出问题都跑不通。superpowers 在这里比裸用 Copilot 严谨得多，它会主动执行mvn test，把失败的测试一步步定位到具体方法，再回到/debug模式下修复。修完以后继续跑，直到全绿，整个过程不需要我盯着复制粘贴命令。

整套流程走完，一个接口从需求到合入，大概需要一两轮人机对话。写代码的时间反而最少，大量时间花在了需求澄清和计划确认上——这恰恰是以前裸用 AI 时省掉，但最后总会以返工形式补回来的环节。

4.3 MCP服务：让AI真正"动手"操作浏览器和仓库

superpowers 自带几个基于 MCP（模型上下文协议）的服务端，我最常用的有两个：一个是浏览器自动化，另一个是 Git 仓库操作。

浏览器自动化的底层是 Playwright。这玩意儿不是给你看演示用的，它真正解决的是"前后端联调没法闭环"的问题。以前 AI 只能帮你写接口，接口好不好用、页面展示对不对，还得你自己开浏览器验证；现在 AI 可以直接启动浏览器，访问本地服务，点击按钮、检查元素、截图留证。在 Java 项目里，这意味着我可以用它去验证 Swagger 页面上的接口文档是否正确，或者跑完前端项目再点几个核心路径，前端有报错它自己就能看到。

Git 仓库操作服务则让 AI 能自己看日志、查分支、做简单的提交。注意，我强烈建议别让 AI 直接推送远程仓库，commit 之前也一定要人工过一遍 diff。AI 在"小步提交"这件事上执行得不错，但偶尔会把它思考过程中改坏的半成品也提交进来，这个习惯很危险。我把规则设成了"AI 只能 commit 到本地分支，push 必须人工确认"，从机制上杜绝了事故。

4.4 自定义技能：把团队规范装进AI

除了官方自带的技能包，superpowers 允许你完全自定义技能，也可以拉取社区分享的技能。格式前面说过，就是普通 Markdown 文件加 YAML 头，核心字段是name、description、when_to_use。理解了这个机制，你就能把任何团队的显性知识和隐性经验沉淀成 AI 可读的规则。

我给团队做过一个"接口开发规范"技能，内容覆盖了 RESTful 路径命名规则、统一响应体结构、鉴权方式、错误码规范、日志打印规范、文档注释要求。做完以后，团队里所有人用 AI 写接口时，产出的代码风格都高度统一，代码审查的争议少了很多。更有意思的是，新来的实习生用它写的第一版代码，居然比很多老员工手写的还规范，因为 AI 严格遵守了技能文件里的每一条规则。

这里有一个经验：技能文件别写太长。单个技能超过 300 行，AI 反而不爱读，或者读完抓不住重点。我一般控制在 100 行左右，把"必须做""禁止做""怎么做"分清楚，描述用命令式语气，少写抒情文字。技能文件是给 AI 当操作手册用的，不是企业文化建设宣传稿。

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

5.1 高频问题速查表

我整理了这段时间使用中，社区里出现频率最高的问题，以及对应的排查思路：

这张表不是教科书式的列表，每一行都是我或者身边同事真实遇到过的。尤其"自定义技能没生效"这一条，看着低级，但出现频率非常高，多半是文件编码和 YAML 缩进的问题，排查起来也快。

5.2 让我印象深刻的三个排查案例

第一个案例，技能文件"诡异失效"。我明明把技能文件放进了工作区目录，AI 就是读不到。排查发现是文件编码问题——我用的编辑器保存成了带 BOM 的 UTF-8，YAML 头解析失败。解决办法很简单：用 UTF-8 无 BOM 重新保存，问题立刻消失。这种问题隐蔽性很强，因为文件打开看内容完全正常，只有机器在解析时才出错。

第二个案例，Java 项目里 AI 反复引入重复依赖。在 Spring Boot 项目里，很多常用依赖其实已经在父 POM 里声明过，但 AI 不会主动去看继承结构，每次实现接口都在子 POM 里重复加同一个依赖。我后来在技能文件里明确写了"检查父 POM 已有依赖，禁止重复声明"，问题就绝迹了。这个案例特别典型：AI 不会主动检查整个项目的依赖树，除非你把"检查依赖树"这件事变成一条技能规则。

第三个案例，AI 在验证阶段"假装执行"。有一次它声称测试全部通过，但我手动跑的时候明明有失败用例。排查发现，它在响应里直接复述了我预期的结果，并没有真正执行测试命令。从那以后，我在技能和工作流里加了强制约束："验证结果必须附带实际执行的命令输出，不得转述或总结"。这个案例提醒我，AI 的"自信报告"一定要警惕，尤其是涉及验证、测试这类关乎质量的环节，必须有可追溯的证据。

6. 我的实操心得与避坑建议

6.1 三个让superpowers变好用的关键习惯

第一，把"需求澄清"当作最重要的一步。我以前用 AI 写代码总想快点看到结果，需求一句话就丢过去。用了 superpowers 之后，我发现/brainstorm阶段花掉的时间，往往能省下后面一小时的返工。最典型的例子是"分页参数要不要传"这种细节，写代码之前不问清楚，写完就得改 Controller、改 Service、改测试，三处全动。

第二，严格审查每一次 commit 前的 diff。AI 生成代码能力再强，在"边界情况"上依然会犯错，比如并发场景下的状态更新、异常分支的资源释放。我的流程是：AI 提交代码后，我必须过一遍 diff，重点看它有没有处理空值、有没有关闭资源、有没有在异常路径上留下隐患。代码审查不是可选项，是自己必须做的最后一道闸门。

第三，按项目维度管理技能文件，别搞"一套技能走天下"。不同项目的技术栈、规范完全不同，我给 Spring Boot 项目和 React 前端项目配置的技能包是分开的。这样加载快、上下文干净，AI 也不会拿前端规范来审视后端代码。刚开始我图省事，把所有规范都堆在一个技能包里，结果既臃肿又容易冲突，后来拆开之后清爽多了。

6.2 什么时候不该用superpowers

最后分享一些反直觉的经验。有些场景，我认为别用 superpowers。

一是超大规模的存量代码重构。superpowers 的流程适合"从零到一"开发新功能，或者小范围改动。面对几十万行、依赖关系复杂的存量系统，AI 的全局理解能力还是不够，流程化反而会放大它"自信"的倾向——计划做得头头是道，执行起来才发现漏了一堆隐式依赖。

二是需要绝对确定性的场景。如果某个版本发布要求所有代码变更都能被严格审计、不允许 AI 有半点发挥，那它"计划+实现"的模式就不合适。更稳妥的还是人写代码，AI 只做辅助审查。

三是纯探索性质的 PoC 项目。这类项目变化极快，需求本身就是要通过写代码来试探的，硬套工作流反而拖慢节奏。这种时候我宁可回到裸用 AI 的自由对话模式，怎么快怎么来，反正写坏了就扔。

这些边界，是我用了大概三周之后才慢慢悟出来的。工具本身不复杂，复杂的是判断什么时候该用、什么时候不该用。如果你刚开始接触，我的建议很简单：先别急着自定义技能，用默认配置跑通一个完整功能；跑通了再去研究技能文件的写法；研究明白了再调整工作流。一步一步来，superpowers 才能真正变成你的"超级能力"，而不是又一个吃灰的插件。