企业官网建设流程全解析

AI 编程助手用久了，很多人会有一个相同的感觉：它写单点功能很快，但一放到真实项目里就容易“失控”。要么不写测试就急着交付，要么连需求都没问清楚就直接改了五个文件，要么重构完跑出一堆编译错误。superpowers 这个开源技能集，就是冲着这个痛点来的。

它不是一个传统意义上的插件，也不是某个 IDE 扩展，而是一套面向 Claude Code、Codex CLI 这类终端型 AI 编程助手的“工作协议”。安装之后，助手会被引导按一套资深工程师的作业流程干活：先澄清需求，再写实现计划，然后严格走测试驱动开发（TDD），最后才提交代码。这篇文章我会从零开始，讲清楚 superpowers 的底层逻辑、实际安装步骤、它在 Java 项目里的实战用法，以及我踩过的几个坑。无论你是刚听说这个名字，还是已经装了一半遇到问题，都能找到参考。

1. 先搞清楚：superpowers 不是插件，是一套“任务协议”

我第一次听说 superpowers 的时候，第一反应是去网上搜“superpowers 安装”，以为它是个 npm 包或者 VS Code 插件。装完才发现，这套东西的运作方式跟传统插件完全不一样。它不会给你界面按钮，也不会注册快捷命令，而是往你的 AI 助手的工作目录里塞了一批 Markdown 文件，这些文件就是“技能”。

1.1 技能文件的本质

每个技能本质上是一个目录，目录里有一个SKILL.md文件，外加若干辅助文档。SKILL.md的结构类似这样：

--- name: tdd description: 使用测试驱动开发流程编写代码，先写失败测试，再实现最小代码使其通过。 --- # TDD 技能说明 ## 核心步骤 1. RED：编写一个失败的测试 2. GREEN：用最小改动让测试通过 3. REFACTOR：在测试保护下重构 …… ## 注意事项 - 测试必须真实覆盖业务逻辑 - 禁止通过修改断言来“强迫”测试通过 ……

就是这个不起眼的文本文件，能让 AI 的行为发生质变。原因在于，Claude Code、Codex CLI 这类工具在启动时会扫描指定目录下的技能文件，把文件名、描述、正文内容注入到系统提示词里。AI 在回答问题时，会根据当前任务的语义自动匹配技能描述，然后按照技能文档里写的步骤来执行。

所以 superpowers 更像是一份“工作岗位说明书”。它不直接替 AI 写代码，而是规定了 AI 在什么场景下应该先做什么、后做什么、禁止做什么。

1.2 一套典型的“工程师 SOP”包含哪些环节

完整安装 superpowers 之后，技能库里通常包含几十个技能，它们彼此衔接，组成一个完整的软件交付闭环：

这一整套流程，其实就是把开发团队里“资深工程师带新人”的方法论，沉淀成了 AI 可读的规范文件。你不需要反复在提示词里强调“先写测试”，因为技能文件已经把这条规则写死，AI 每轮都会遵守。

1.3 它适合谁，不适合谁

如果你平时只用 AI 写一次性脚本、做算法题，或者生成点零散片段，superpowers 带来的收益不会很大——它引入的流程开销在那类场景里是纯负担。

但如果你在维护真实项目，特别是像 Java 这种强调工程规范、编译检查严格、回归成本高的代码库，那这套东西的价值会被放大。多人协作时，AI 按统一流程产出代码，Review 的体验能好很多。简单说，superpowers 追求的不是“AI 帮你写完功能”，而是“AI 按不会给团队添乱的方式写完功能”。

2. 动手装：两条路径，以及装完必须做的一次自检

安装这件事看起来简单——Git 克隆到某个目录而已。但我发现大部分人的问题都出在“路径选错”和“没有对工具侧做额外配置”上。接错了位置，技能文件根本不会被扫描，AI 还是一副“没有规矩”的老样子。

2.1 用户级安装 vs 项目级安装

先讲路径选择。superpowers 官方推荐的安装方式是把仓库克隆到 AI 工具对应的技能目录下。这里有两种范围：

如果你用的是 Claude Code，路径会对应变成~/.claude/skills/或.claude/skills/。不同工具读取的目录名不一样，核心逻辑是一致的：把技能文件放进工具启动时会去扫描的 skills 目录即可。

我的建议是：个人试用期用用户级，确认流程稳定之后再决定要不要把项目级配置提交到团队的 Git 仓库。项目级的好处很明显——新同事克隆代码后，AI 工具会自动加载团队约定的技能流程，不需要额外培训。

2.2 一个完整的安装示例

假设你的环境是 Codex CLI，操作步骤大致是这样的：

# 1. 进入技能目录 cd ~/.codex/skills # 2. 克隆 superpowers 仓库 git clone https://github.com/obra/superpowers.git # 3. 检查目录结构 ls ~/.codex/skills/superpowers/skills/

克隆完成后，你会看到仓库里有一堆子目录，每个目录对应一个技能。这里要特别注意：AI 工具扫描的通常是“技能目录”，而不是“仓库根目录”。如果工具支持递归扫描，那克隆到根目录就能直接识别；如果不支持，你可能需要把skills子目录里的内容复制到一级目录下。装完第一件事，不是急着写代码，而是做一次自检。

2.3 安装后的自检：确认 AI 真的“看见”了技能

怎么确认安装成功？很简单，直接在 AI 终端里问一句：

请列出你现在可用的技能，以及它们的核心用途。

如果安装成功，它会列出 brainstorming、writing-plans、tdd 等技能名。如果它回答“我没有技能”或者含糊其辞，基本可以断定技能目录没被扫描到。这时候逐项排查：

1. 确认技能目录路径是不是工具支持的默认路径；
2. 确认目录里是否真的有SKILL.md文件；
3. 确认工具版本是否支持技能功能（老版本 CLI 可能没有这个能力）；
4. 如果是用户级目录，确认当前项目没有用项目级目录把用户级覆盖掉。

还有一个值得做的验证是：触发一个具体技能，看它的行为有没有变化。比如你随口说“帮我想一个登录模块的设计方案”，如果它自动进入了类似“先问需求、列边界条件、再给方案”的状态，说明 brainstorming 技能已经接管了行为模式，这时候才算真正装好。

3. 技能库到底怎么驱动 AI：以 TDD 链路为例拆开看

理解了安装逻辑之后，更值得花心思研究的是技能库的驱动机制。superpowers 不是简单地把几十个技能文件堆在那里，它有明确的调用链和优先级。搞懂这条链路，你才知道什么时候该显式触发技能，什么时候该闭嘴让 AI 自己判断。

3.1 技能触发的真相：描述匹配 + 显式调用

技能文件的description字段有一个作用：当 AI 收到用户消息时，会把消息内容与技能描述做语义匹配。匹配度高的技能会被自动选中并加载到上下文里。

这意味着描述写得越具体，触发越精准。比如你只说“帮我处理一下这个模块”，AI 可能会触发 brainstorming，也可能会直接触发 executing-plans，这取决于它怎么理解“处理”这个词。为了避免误触发，superpowers 通常会在文档里要求 AI 在不确定时先问清楚，而不是自己瞎选。

除了自动匹配，你也可以在提示词里显式点名：

使用 tdd 技能，在这个 Java 模块里为 PaymentService 添加新功能。

显式调用相当于绕过了匹配环节，直接锁定技能。这种方式的优点是稳定，缺点是要求你对自己想要的流程有一定的理解。用多了你就会发现，显式调用更像“主动指挥”，自动匹配则像“放权给 AI”。

3.2 从需求到提交的完整技能编排

我以一次完整的功能开发为例，把技能链路拆开：

1. think / brainstorming：AI 先不写代码，而是把目标拆解清楚。它可能向你提问，确认用户角色、输入输出、边界条件。这一步的输出通常是一份简短的需求澄清记录。
2. writing-plans：需求确认后，AI 写一份实施计划。计划里包含要改哪些文件、每个文件的改动目标、测试策略、风险点。这份计划会保存为项目里的一个文档，方便后续对照执行。
3. executing-plans：按照计划动手，但不是“一口气改完”。它会逐步执行，每完成一步就停下来验证，而不是闷头输出一大段代码。
4. tdd / red-green-refactor：进入真正的编码环节。先写失败测试，运行确认是“红”，再写最小实现让它变“绿”，最后在测试保护下重构。
5. commit：代码通过测试后，由 AI 生成符合规范的提交信息，通常还要把相关变更按逻辑拆成多个 commit。

这一整套流程下来，AI 的工作方式从“一次性生成答案”变成了“多轮状态机推进”。每一步的产出都依赖上一步的结果，每一步都有检查点。这也是 superpowers 最厉害的地方——它让 AI 从“快”转向“稳”。

3.3 为什么是 Markdown，而不是代码

有一个问题经常被问到：为什么技能不用 JavaScript 或 Python 写，而是用 Markdown？我个人的理解是，Markdown 对 AI 模型的“可读性”更好。模型在训练阶段就见过海量 Markdown 文档，对这种格式的指令性内容理解最稳定。相比之下，代码逻辑容易被模型当成“需要推理的代码”，而不是“需要遵守的指令”，边界容易糊。

另一个现实原因是 Markdown 版本管理成本很低。团队想裁剪某个技能的步骤，直接改几行文字就能提交，不需要走编译发布流程。这意味着技能规范可以跟着项目一起演进，这是传统插件做不到的灵活度。

4. 实战带跑：Java 老项目里从需求到绿测的一次完整走查

理论说多了容易飘。接下来我拿一个典型的 Java 场景走一遍：一个基于 Spring Boot 的老项目，需要给OrderService增加一个“取消订单并回滚库存”的功能。这个场景我实测过多次，也是 superpowers 在新手身上最容易“翻车”的场景，因为老项目往往有历史包袱。

4.1 第一步：让 AI“想清楚”再动手

启动后我先不急着说功能，而是给 AI 一个短提示：

在 OrderService 里新增取消订单功能，要求回滚库存。 请先用 brainstorming 技能澄清需求，不要直接写代码。

它很快进入了追问模式，给我抛出一堆问题：取消订单是否只限待支付状态？库存回滚是直接加回去还是走异步消息？取消后优惠券要不要退还？已发货订单是否允许取消？这些问题有些我预设了答案，有些我没想到，比如“取消后如果原支付是组合支付，退款怎么处理”。

这个阶段输出的是一份简单的需求确认清单。Java 项目里这么做尤其有价值，因为老项目里各种隐含状态特别多，少问一个问题，后面改起来就是灾难。

4.2 第二步：生成实施计划

需求确认后，AI 切换到 writing-plans 技能，输出了一份计划：

1. 修改OrderService.cancelOrder方法，新增状态校验；
2. 在OrderRepository中新增按 ID 和状态查询方法；
3. 修改InventoryService，暴露rollbackStock接口；
4. 为上述改动编写单元测试；
5. 新增集成测试覆盖事务回滚行为。

整个过程它明确标注了“本阶段不写实现代码”。很多人第一次看这一步会觉得慢，但你会发现，等 AI 真的开始写代码的时候，它不再东翻西翻地找需求，也不会有“改到一半发现逻辑冲突再翻工”的情况了。

4.3 第三步：TDD 红绿循环在 Java 里的具体呈现

计划确认后，AI 进入编码环节。我观察到它严格遵循了 RED -> GREEN -> REFACTOR 的循环，而且有一个细节做得比很多手动开发者还到位：它会先跑一次测试确认失败信息符合预期，再开始写实现。

# 提示词示例（简化） 现在执行 tdd 技能，为 cancelOrder 方法编写测试。

它先在OrderServiceTest里新增了几个@Test方法，测试待支付订单取消成功、已发货订单取消被拒、库存回滚被调用等场景。然后运行mvn -Dtest=OrderServiceTest test，看到红，再补实现。补实现时也是最小改动原则——先让测试过，不提前引入缓存、不顺手重构。

Java 环境下这个循环特别流畅，因为 Maven/Gradle 的测试反馈链路短，JUnit 断言信息清晰。对比我见过的一些 Python 项目，常见的问题是“测试失败到底是因为功能缺失还是环境不对”，Java 项目很少犯这种迷糊。

4.4 潜在的坑：AI 判定“测试绿了”不等于“测试对”

在我多次带跑中，出现最多的问题是 AI 会在写测试时“手下留情”——断言写得不够狠，导致某个有 bug 的实现也能通过测试。比如测试里只断言返回结果为 null，不校验异常类型，或者只 verify 了一次 mock 调用，不校验具体参数。

后来我习惯在提示词里补一句：

测试必须保证：在实现缺失时失败一次；在实现错误时失败一次；在实现正确时通过。

superpowers 的 tdd 技能文档本身也有类似约束，但它更偏原则描述。实操中你要在巡检时多看一眼测试代码，不能因为是 AI 写的就放松警惕。我的经验是：把“测试是否正确”的检查点放在每次重构完成之后，由人工快速过一遍测试名称和关键断言。

5. 翻车记录：接入后最容易踩的五个坑

再好的流程，用起来也会遇到一些“跟技术文档无关”的坑。这节是我自己在多个项目中实际踩过的教训，写出来帮大家少走弯路。

5.1 坑一：批量克隆了所有技能，反而导致行为混乱

superpowers 默认技能集很大，全量加载到上下文后，AI 的提示词空间被占掉不少，模型在低上下文窗口下容易出现“选择性失明”——该触发的技能没触发，不该触发的反而赢了匹配。

解决办法是精简。装完第一个动作应该是删掉你用不到的一半技能，特别是那些描述与你的工作流重复度高的。我的习惯是留下 think、brainstorming、writing-plans、executing-plans、tdd、code-review、commit 这几个核心项，其他的按需再启。

5.2 坑二：显式调用和自动触发相互打架

当你已经自动进入了某个技能，又在对话里显式说“现在执行 xx 技能”，AI 有时会重新初始化流程，把前面已经完成的步骤推倒重来。最典型的是它已经处于 brainstorming，你又说“开始写吧”，它会跳过执行计划环节直接写代码。

对策是不要人为打断它的技能状态机。你想切换到下一个阶段，用更自然的方式表达，比如“需求已经确认完了，现在出一份实施计划”，让它在当前技能框架下推进，而不是重新触发一个新技能。

5.3 坑三：Java 多模块项目里提示词窗口不够用

superpowers 的工作流要求 AI 频繁读取多个文件的上下文，Java 项目一个模块动辄几十个类，提示词窗口很容易爆掉。窗口满之后的表现不是报错，而是 AI 开始“假装”它看过某些文件——它基于类名和常识写代码，最后编译报错一堆。

这种场景我建议做两步：一是把任务拆小，一次只让 AI 处理一个模块；二是给 AI 提供一份精简的代码地图，让它只需要主动读取关键文件，而不是靠扫描全部源码来猜。

5.4 坑四：依赖下载慢，AI 的耐心先耗尽了

Java 项目的 Maven 依赖首次构建动辄几分钟。superpowers 的 TDD 循环要求“写测试 -> 跑测试 -> 看到失败”，这本来是对的，但如果环境刷新一次要三分钟，AI 很容易在等结果时做多余操作，比如顺手改实现、或者直接猜测测试会通过。

我对策是提前预热：进入开发前先让 AI 跑一次mvn test确认所有依赖已就绪并缓存完毕，然后再进入 TDD 环节。同时把测试范围尽量圈定在单模块单类，避免每次任务都触发全量构建。

5.5 坑五：权限配置过宽，AI 乱改无关文件

superpowers 的执行流程会让 AI 频繁“自己动手”读取代码、修改文件、执行命令。如果终端工具的权限是放开“任意文件可写”，它会偶尔做出超范围的改动，比如顺手帮你把配置文件的格式改了、把某个测试方法的名称规范化了。

这个问题的根源是技能协议只约束“做什么”，没有约束“不做什么”。我建议接入后的第一件事，是在工作区里显式标注哪些目录是 AI 可以动的，哪些只能只读。比如多模块项目里，明确告诉它“本次只允许修改 order-service 模块”。

最后分享一点个人体会

我现在已经习惯在绝大多数项目里开着 superpowers 干活，但并不是因为它让 AI 更聪明了。说实话，模型还是那个模型，逻辑推理能力没有变强。变的是 AI 的工作习惯：它不再急着给答案，而是先确认需求、列计划、写测试、再实现。在 Java 这种强调可维护性和回归安全的工程环境里，这种“变慢”其实是巨大的净收益。我见过太多次 AI 一次性生成几百行代码、结果重构时根本改不动的场景，而 TDD 约束之下的代码，至少每一次改动都有测试兜底。

最后给你一个小技巧：如果你觉得某个技能的流程太啰嗦，别急着卸载它。试着打开对应的SKILL.md，把中间那些“为了引导模型而写的解释性文字”删掉，只保留步骤和禁止项。裁剪后的技能文件占用的上下文更少，触发速度更快，AI 反而更容易严格执行。这大概也是 superpowers 最让我喜欢的一点——它把“如何指挥 AI”的主动权交还给了你自己。