企业官网建设流程全解析

1. 从“会用AI”到“会用superpowers”：先搞懂它解决什么问题

这几年AI编程工具层出不穷，今天换这个明天换那个，但你会发现一个尴尬的事实：同一个模型，在不同人手里表现差距巨大。有人能用它半小时搞定一个模块，有人折腾一上午还在跟上下文窗口搏斗。问题不在模型本身，而在“你怎么跟它协作”。superpowers这个项目，就是冲着这个痛点去的。

1.1 痛点：AI编程助手能力不稳定的根源

先说一个我自己的经历。之前用某款AI编码工具写Java服务，同一个需求，我换了一种描述方式，结果代码质量天差地别。第一次它规规矩矩按项目现有风格补全逻辑，第二次它自作主张引入了一堆我根本没见过的依赖。你可能会说“提示词写清楚点不就行了”，但真实项目里，提示词根本覆盖不了所有规则。

比如项目里有这么一条隐形约定：所有对外接口的返回结构必须统一为Result<T>，异常不能直接往外抛。这种约定写在文档里、写在不显眼的Wiki里，但AI读不到。你每次都要在对话里重新强调一遍，累不累？更麻烦的是，团队里每个人强调的方式还不一样，AI今天听张三的，明天听李四的，代码风格越来越乱。

superpowers解决的就是这个问题：把那些“应该让AI自动遵守的规则”固化成文件，项目一加载，AI天然就能读到。它不依赖你每次对话时临场发挥，而是把规则前置、流程前置，让AI从“凭感觉干活”变成“按规矩干活”。

1.2 规则驱动：给AI立规矩的正确姿势

superpowers的核心不是某个神奇的算法，也不是什么黑科技，而是一套“规则驱动”的协作模式。它的设计思路其实特别朴素：既然AI工具默认是“通用助理”，那我们就给它灌入“项目专属的领域知识”和“团队专属的工作习惯”，把它变成“懂这个项目的助理”。

这个项目我琢磨了很久，它最聪明的地方在于分层设计。最底层是规则文件，用Markdown写成，描述项目的技术栈、代码规范、目录结构、常见约束；中间层是技能包，把某类任务的完整流程固化成可复用的指令模板；最上层是具体的执行工具，比如Codex CLI、Claude Code这类命令行编码助手。规则定义“不能做什么、必须怎么做”，技能包定义“这类任务应该按什么步骤做”，工具负责真正动手写代码。

用生活里的例子来类比：superpowers就像是给AI一本“新员工入职手册”，里面写了公司的考勤制度、代码规范、上线流程、常见坑位，而不是每次开会时口头叮嘱一遍。这个手册随项目走，谁接手项目，谁就能获得同样的协作体验。

2. 上手实操：5分钟搭起superpowers工作区

聊完原理，直接上手。superpowers的安装和配置不需要你懂什么高深的东西，只要你的开发环境里有Node.js和Git，就能在几分钟内跑起来。我用的是macOS环境，Windows和Linux的流程基本一致，差别只在于路径写法。

2.1 安装与目录结构：.superpowers、规则、技能包

安装方式很简单，官方推荐用npm全局安装，然后通过CLI初始化项目。我建议你在项目根目录执行初始化，而不是全局初始化，这样每个项目都能有自己的规则集。

npm install -g superpowers cd your-project superpowers init

执行完superpowers init之后，项目根目录会多出一个.superpowers文件夹，里面是默认的目录骨架。你还会看到一个AGENTS.md文件，这个文件是整个规则体系的入口，AI工具加载项目时会优先读取它。

整个目录结构大致长这样：

your-project/ ├── .superpowers/ │ ├── rules/ # 细分规则，比如 java.mdc、git.mdc │ ├── skills/ # 技能包，比如 task.md、boomerang.md │ ├── commands/ # 命令注册，供AI调用具体技能 │ └── templates/ # 任务模板，标准化某类请求 ├── AGENTS.md # 规则声明入口 └── .superpowers.json # 配置文件（可选）

第一次看到这么多文件不用慌，真正需要你维护的核心只有两个：AGENTS.md和.superpowers/rules/下的规则文件。技能包默认会带一批，直接能用，后面你想自定义再改。

2.2 技能包拆解：从task到pr-review

superpowers默认内置了不少技能包，我挑几个高频的讲一下，方便你快速度过“不知道它能干嘛”的阶段。

task技能包定义的是“接手一个任务”的标准流程：先读取项目README和AGENTS.md，再定位相关代码，最后才动手修改。这看起来像是废话，但AI默认并不这么做。很多AI上来就写代码，写完才发现改了不该改的地方。

boomerang技能包解决的是“AI进行到一半被打断”的场景。它会把当前进度、已完成部分、剩余工作、待验证项记录到一个状态文件里，下次交互时自动恢复。这个对实际开发太重要了——尤其当AI跑了一个长任务，中途你切出去开会，回来想接着干，没有状态记录的话，上下文基本废了。

pr-review技能包是代码审查的专属流程：检查diff、检查提交信息格式、检查是否有调试残留、检查边界条件。它不依赖人肉提醒AI“请先看git diff”，AI会自动按这个流程执行。

每个技能包本质上都是一份精细的Markdown提示词，里面包含了该场景下的步骤拆解和约束条件。你完全可以打开文件看它的实现，这本身就是很好的学习材料。

2.3 第一步验证：让AI按你的节奏干活

装好环境之后，先别急着上复杂项目，用一个最简单的场景验证superpowers是否生效。我在一个测试项目里写了一条规则：所有方法必须写Javadoc注释，然后让AI生成一个工具类。

没配superpowers之前，AI生成的代码经常只有稀疏的几行注释；配好规则之后，AI会老老实实每个public方法都补上Javadoc，甚至还会在类头写上作者和版本信息。看到这个变化，你就可以确定规则管道已经通了。

有一个细节需要注意：不同AI工具对规则文件的读取策略不同。Codex CLI和Claude Code都会读AGENTS.md，但Claude Code还支持.claude目录下的.mdc规则文件。为了让superpowers在多个工具之间通用，规则声明里不要写死某个特定工具专属的指令。我自己踩过这个坑，在规则里写了“你是一个使用Claude Code的助手”，结果切到Codex时行为就变得很奇怪。

3. 核心细节解析：规则文件与技能包的工作原理

很多人以为superpowers只是“把提示词存成文件”，这理解太浅了。它的价值在于设计了一个“规则通路”：从仓库根目录的AGENTS.md出发，层层引用到具体的规则文件和技能包，让AI在处理不同任务时，能自动加载对应的约束。这里面有几个关键机制值得展开讲。

3.1 .mdc规则文件到底怎么写才生效

规则文件的格式是Markdown，但它的生效依赖“前置描述块”（frontmatter）。一个标准的.mdc文件长这样：

--- description: Java项目必须遵守的代码规范 globs: *.java, src/main/java/** alwaysApply: false --- # Java编码规范 1. 所有DTO类必须使用record或final class，禁止使用可变POJO。 2. 所有对外接口返回统一Result<T>结构。 3. 禁止catch异常后吞掉，必须记录日志并抛出业务异常。

frontmatter里的description很重要，AI工具会用它来决定“什么情况下需要读取这个规则”。globs用于限定规则适用的文件范围。alwaysApply如果设为true，表示这个规则在所有场景下都生效；如果为false，AI会按照description的描述来判断“当前任务是否涉及该规则”。

我建议你把高频的硬性约束（比如不允许使用System.out.println、不允许引入未在pom.xml声明的依赖）设为alwaysApply: true；把低频但重要的规范（比如“变更数据库表结构时必须先生成迁移脚本”）设为alwaysApply: false，这样AI不会被一堆规则压得喘不过气，又能按需加载。

这里面有个容易踩的坑：规则文件不是越详细越好。我也曾试图把所有编码规范都塞进规则里，结果AI在简单任务上反而更啰嗦了，因为它要“遵守”太多约束而频繁中断操作。实际测试下来，一份规则文件控制在一个主题、十个要点以内，效果最好。

3.2 结合Java开发：superpowers在项目里的落地

Java项目天然适合用superpowers，因为Java项目的结构相对规整，团队规范也多。我的一个Spring Boot项目里，规则文件是这样组织的：

java.mdc负责基础编码规范，包括命名风格、异常处理、Lombok使用边界。spring.mdc专门约束Spring的用法，比如禁止在Controller里写业务逻辑、Service接口必须有实现类、依赖注入必须用构造器方式。db.mdc管理数据库相关规则，比如所有SQL必须走Mapper接口、批量操作必须分批提交、禁止使用SELECT *。

技能包方面，我改了一个task技能包，让它适配Java开发流程：先用Maven编译并跑完单元测试，确认当前基线是绿色的，再进行功能开发；开发完成后，再次跑测试，并检查是否有新增的编译警告。

这套组合用下来，AI生成的代码在“合规性”上明显提高。之前它经常在Controller里直接new一个Service，被规则约束后它会乖乖走构造器注入。规则不只是在“输出端”限制AI，还是在“行为端”引导AI：它会让AI先检查现有代码再动手，而不是凭空发挥。

3.3 参数与配置：控制AI行为的边界

.superpowers.json这个配置文件可能被很多人忽略，它其实是控制AI行为边界的“总闸”。我常用的几个配置项：

{ "mode": "strict", "maxConsecutiveEdits": 5, "requireCheckpoint": true, "ignorePatterns": ["target/", "node_modules/"] }

mode字段可设为strict或normal，strict模式下AI必须遵循所有标记为“MUST”的规则；maxConsecutiveEdits限制了AI连续编辑文件的次数，防止它一口气改动十几个文件导致review困难；requireCheckpoint要求AI在长任务执行途中主动汇报进度。

我个人强烈建议打开requireCheckpoint，尤其是在做跨多个文件的重构时。没有它，AI可能埋头改了一大堆，等你去review的时候已经不知道它动了什么。打开后，AI每完成一个阶段就会输出当前状态和下一步计划，相当于给了你一个“中途干预”的机会。

4. 实战过程：用superpowers完成一次Java代码审查

理论说再多，不如跑一遍流程。这一节我完整记录一次实际操作，让大家看到superpowers在具体任务里是怎么运作的。

4.1 需求定义与技能选择

场景：我负责的一个支付模块提交了一次MR，改动涉及PaymentService、PaymentController和PaymentMapper三个文件。我让AI先做一个自审，重点检查事务边界、异常处理和SQL注入风险。

在superpowers框架下，对应的交互方式是调用pr-review技能：

@superpowers pr-review --focus=transaction,exception,sql-injection

这里的--focus参数会传递给技能包，引导AI审查时把注意力集中在指定维度。其余维度的检查（代码风格、命名规范）也不会被跳过，只是在汇报时会区分“重点问题”和“一般问题”。

4.2 完整操作流程记录

AI收到指令后的执行轨迹大致如下：

第一步，读取规则。AI先加载AGENTS.md，然后根据任务类型读取了rules/java.mdc和rules/spring.mdc，确认了项目里“事务注解必须放在public方法上”“禁止捕获通用异常”“Mapper参数必须使用@Param注解”三条硬性规则。

第二步，获取代码变更。AI调用git命令拿到MR的diff，同时读取了PaymentService的完整文件内容，因为它需要了解上下文而不仅仅是变更行。

第三步，逐项审查。AI按技能包里的检查清单逐项过：先看类结构、方法签名是否符合项目风格；再查事务边界——发现PaymentService.refund()方法上加了@Transactional，但方法内部调用了PaymentCallback.notify()这个远程接口调用，这会导致事务长时间占用数据库连接。接着查异常处理——发现PaymentController里有一段catch块仅仅做了日志打印，没有抛出业务异常，违反“禁止吞异常”规则。

第四步，输出审查报告。AI生成的报告分三块：问题列表、严重级别、修改建议。表述很明确，没有模棱两可。

4.3 效果对比：有规则和没规则的差别

同样的MR，我在另一个未配置superpowers的仓库里让AI审查过，差别非常明显。没有规则时，AI只会泛泛地指出代码风格问题，比如“方法命名不够清晰”（其实问题不大）；有规则时，它的审查能够触及项目特有的约定，而不是“AI味”很重的内容。

最关键的一点是，配置规则后，AI审查的注意力范围被重构了：它不再海撒网似地扫描所有能看到的代码问题，而是聚焦于团队真正关心的问题域。pr-review技能包把“审查”这个宽泛任务拆成了有优先级的清单，AI按清单逐项执行，不会因为上下文过长而遗漏关键检查项。

这种体验让我觉得很踏实，它意味着AI的能力不再依赖“这次对话里用户有没有把规则说全”，而是取决于“团队是否把规范沉淀了下来”。规范沉淀得越精细，AI输出越稳定。

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

用superpowers的过程中，我踩过不少坑。下面挑几个典型问题，按“现象—原因—解决”的方式整理出来，供大家对照排查。

5.1 规则不生效怎么办

这是最常遇到的问题。你明明写了规则，AI却视而不见。我遇到过的原因大致有三种。

第一种，AGENTS.md里没引用对应的规则文件。很多人在rules/目录下写了java.mdc，但在AGENTS.md里没有加上“本仓库的Java代码规范见.superpowers/rules/java.mdc”这句话。AI工具默认只读AGENTS.md，不扫描整个.superpowers目录。加上明确的引用后，规则才进入AI的加载列表。

第二种，globs配置写得太宽或太窄。我吃过亏的配置是把globs写成*.java，但项目实际在src/main/java下，AI在读取特定文件时可能匹配不到规则。改成src/main/java/**/*.java后效果好多了。这个字段的匹配严格程度与工具的实现有关，建议用**通配而不是*。

第三种，规则内容与任务无关。AI不会在每次对话中都把全部规则加载进来，它只会加载与当前任务相关的规则。如果你给AI的任务是“写一个README”，它不会主动去读Java编码规范。判断规则是否被加载，可以在规则文件里加一行“如果有疑问，请先向用户确认是否适用本规则”，如果AI照做了，说明规则已被读取。

5.2 模型被规则“锁死”了？

规则设得过严，AI确实会变“愣”。比如我在一个项目里设了“所有方法必须写Javadoc，包括getter和setter”，结果AI在生成批量代码时，每个简单的getter都配了一大段注释，代码行数膨胀了30%，阅读起来反而更吃力。

解决思路是给规则加“豁免条件”：明确“简单POJO类中不强制要求注解，但核心业务类和接口必须写”。或者利用alwaysApply: false，把适用于大多数场景的规则设为默认加载，把“重型”规范（比如“每个类必须描述设计意图”）设为按需加载。

另外，规则语言不要用“尽量”“最好”这种模糊表述。AI面对模糊指令时，往往会重复确认或选择最保守的执行方式，导致任务效率下降。要用“禁止”“必须”“允许”这类明确约束词。

5.3 多语言项目中的规则冲突与复用

一个仓库里同时有Java和Python代码的情况很常见。如果规则文件里写了“包名必须为com.xxx”，Python代码也会被这个规则困扰。解决办法是按子目录拆分规则：

rules/ ├── java.mdc # globs: src/main/java/**/*.java └── python.mdc # globs: src/python/**/*.py

但要注意，AGENTS.md里不要写只在单一语言下成立的全局规则。例如“禁止使用System.out.println”只在Java规则里写，“禁止使用print”只在Python规则里写，不要写成“禁止使用控制台输出语句”这种笼统规则，AI可能把它解读成禁止一切输出操作。

关于复用，我的习惯是把通用规则（提交信息格式、分支命名、代码评审要求）单独抽出来，放到.superpowers/rules/common.mdc里，被alwaysApply: true；把语言专属规则放到对应语言的规则文件里。这样新项目初始化时，只要复制整个.superpowers目录，微调一下就行，不用从头写。

用superpowers这几个月下来，我最大的感受是：AI编程的下半场拼的不是谁的模型更强，而是谁更会用规则约束模型。这个框架把团队经验、项目规范、工作流沉淀成了可复用的资产，新人接手项目时，AI助手直接就是“老员工”状态。如果你也觉得现在的AI编程助手总是“差那么点意思”，不妨从规则文件入手，给它立好规矩再放手干活。