企业官网建设流程全解析

过去半年，我把大部分代码工作都交给了终端里的 AI 助手，最常用的两个是 Claude Code 和 Codex。说实话，单论单次回答，这些模型已经很聪明了，可一旦任务变成"一个功能、五个文件、三处依赖改动"，它们的表现就开始飘：要么漏掉需求，要么中途改主意，要么自己悄悄缩水。直到我装了一整套叫 superpowers 的技能包，情况才真正稳定下来。

这篇文章不是官方文档的翻译，而是我自己从安装到实战的一线记录。我会先讲清楚 superpowers 解决的是哪一类问题，再给出完整安装流程、核心技能拆解、一个 Java 项目的真实执行轨迹，最后把踩过的坑和取舍心得都翻出来。适合那些正在用 Claude Code / Codex 做真实项目、并且受够了 AI 发挥不稳定的人。

1. 为什么大模型已经这么强，还需要一套 superpowers：显式技能与隐式能力的区别

1.1 原生 Agent 的能力天花板不在模型，在调用方式

模型很强，这没什么好争论的。但终端 Agent 的日常使用方式，本质上是"每次请求都把任务临时丢给模型，让它零样本发挥"。你可以把这种情况想成一个聪明但没受过训练的新人：单点问题它答得很漂亮，可一旦任务变成"一个功能要动五个文件、还要兼容旧数据、还要补测试"，它的每一步决策都在临时碰运气。普通 prompt 往往第一步还行，到第三步就开始和第二步冲突，第五步干脆把最初的需求忘了。

superpowers 做的就是把这些稳定流程写成技能文件。它不是让模型变得更聪明，而是让模型在正确的场景里，按照已经被验证过的流程去执行，减少自由发挥的空间。我对"能力天花板"的理解也因此改变了：模型的基础智力早就够用，缺的是调用方式。就像同一个员工，给他一份清晰的 SOP 和让他每次都临场发挥，产出的稳定性完全不同。

1.2 技能的本质：一段带触发条件的 Markdown 操作手册

superpowers 里的"技能"（skill），本质上就是一个带 frontmatter 的 Markdown 文件。frontmatter 里的name和description是模型判断什么时候该触发它的关键，正文是具体的执行步骤。下面是一个简化版的技能文件结构：

--- name: brainstorm_plan description: 当需求不明确、存在多个实现方案、或者需要先做方案设计再开始写代码时使用 when_to_use: 在动手编码之前，如果我不确定怎么做，先运行这个技能 version: 1.0.0 --- ## 执行步骤 1. 收集所有已知约束和验收条件 2. 列出至少 3 个候选方案，禁止只给一个答案 3. 对每个方案做优劣势对比，标记风险 4. 选型并输出分步实施计划

这里有一个容易被忽略的细节：CLAUDE.md 里通常只放技能索引，完整技能文件是按需读取的。这非常关键。如果一开始就把几百行步骤塞进系统提示，每轮对话都会白白烧掉大量 token；而按需加载既省上下文，又让技能文件可以随意扩充。description写得好不好，直接决定 AI 会不会在正确的时机调用它。我见过太多技能不生效的案例，最后查下来都是 description 太空泛，模型根本判断不出"该用"。

1.3 和 prompt 模板、IDE 插件的区别

很多人会把 superpowers 理解成一个"高级 prompt 模板库"或"IDE 插件"，其实都不是。它们之间有本质区别，我用一张表说明：

superpowers 更贴近 Agent 的工作方式：它不是给人类看的文档，也不是给 IDE 的插件，而是给模型自己在运行时读取和执行的"技能操作系统"。这也是为什么它能同时被 Claude Code、Codex 这类终端 Agent 复用，而 IDE 插件往往换一个编辑器就废了。

2. 安装 superpowers：十分钟跑起来的完整过程

2.1 前置条件：终端 Agent 已经能正常工作

安装 superpowers 之前，请先确认你的终端 Agent 环境是好的。我假设你已经装好了 Claude Code 或 Codex，并且登录账号能正常对话。如果这一步还没搞定，先去把 CLI 跑通，否则后面排查起来会很痛苦。

另外建议检查一下 Node.js 版本，一般 18 以上就没问题。执行node -v确认。还有一个小建议：第一次安装时先在一个干净的项目目录里做，不要一上来就在公司老项目里折腾，避免现有 CLAUDE.md 和 superpowers 的说明互相干扰，把安装问题和工作问题混在一起。

2.2 获取技能包并规划目录

把仓库克隆到本地，我习惯放在~/.superpowers：

git clone https://github.com/obra/superpowers.git ~/.superpowers

然后你需要把里面的技能文件放到正确的位置。这里有两个选择：

• 全局目录：~/.claude/skills/，所有项目都能用，适合个人通用技能。
• 项目级目录：<your-project>/.claude/skills/，跟随仓库提交，适合团队协作时统一行为。

我的习惯是项目级优先。团队场景下，技能库应该像代码一样走 review、走版本管理，这样才能保证每个人拿到的是同一套 AI 工作流。全局目录只放那些我在任何项目里都想用的通用技能，比如 brainstorm_plan。目录结构大概长这样：

<your-project>/.claude/ ├── CLAUDE.md └── skills/ ├── brainstorm_plan.md ├── research.md ├── subagent.md └── implement.md

如果你用的是 Codex，情况稍微不同：Codex 没有原生.claude/skills这个约定，但可以通过 AGENTS.md 注册，具体我放到后面"跨工具兼容"那节细说。

2.3 在 CLAUDE.md / AGENTS.md 里"告诉模型技能存在"

这一步最容易被跳过，但恰恰是最关键的。技能文件放在目录里不会自己生效，你必须在 CLAUDE.md（或 Codex 的 AGENTS.md）里明确告诉模型：这里有 superpowers 技能，什么时候该去读取。

我一般会在 CLAUDE.md 的靠前位置写这么一段：

# superpowers 使用说明 本环境安装了以下技能，存放在 .claude/skills/ 目录： - brainstorm_plan：当需求不明确、存在多个方案、需要先设计方案时使用。 - research：当需要调查代码、依赖、或外部信息时使用。 - subagent：当任务较大、需要拆分成独立子任务并行处理时使用。 - implement：当计划已确定、需要按步骤落地代码时使用。 当用户请求适合某个技能时，先读取对应技能文件的完整内容，再严格按步骤执行。不要在不需要时主动加载所有技能。

为什么要放靠前位置？因为模型读取项目说明时通常按文件顺序逐段处理，前面的内容权重更高。如果你把这段说明埋在 CLAUDE.md 后半部分，模型很可能在真正决策时已经"忽略"了它。Codex 环境同理，写在 AGENTS.md 开头。

2.4 验证安装：先触发一次轻量技能验证链路

安装完成后先别急着做正式任务，花两分钟验证链路是否通。启动 Claude Code，直接问：

根据 CLAUDE.md，你能使用哪些 superpowers 技能？各自应该在什么时候使用？

如果一切正常，模型应该能准确列出技能名称和触发场景。如果它说"我没有这些技能"，按这个顺序排查：

1. 技能文件是否真的放在.claude/skills/下，文件名拼写有没有错。
2. CLAUDE.md 里的技能说明是否被其他内容覆盖或截断。
3. 当前会话是不是从旧对话继续的，如果是，先开启新会话。

验证完索引，再实际触发一次轻量技能。比如输入：

请使用 brainstorm_plan 技能，帮我分析当前目录结构，规划如何新增一个健康检查接口。

观察模型行为：它应该先读取技能文件，然后按照技能里的步骤输出候选方案和计划，而不是直接甩给你一段代码。到这里，安装就算真正完成了。

3. 核心技能逐个拆解：plan、research、subagent、implement 的配合逻辑

3.1 brainstorm_plan：需求模糊时先穷举再收敛

我用的最多的技能是 brainstorm_plan。它解决的是"需求说不清楚"的问题。以前直接让 AI 写代码，它总喜欢第一个想到的方案；而 brainstorm_plan 强制它先做发散：收集约束、列出至少三个候选方案、对比优劣势、标记风险，最后才输出计划。

这个设计很反直觉，但有实际价值。模型默认倾向于"给一个答案"，可真正好的方案往往藏在那些被淘汰的选项里。技能通过强制步骤让模型把"为什么选这个而不选那个"说清楚，相当于逼它把自己的思路暴露出来，你才能有机会纠正方向。我通常会在 prompt 里直接点名：

使用 brainstorm_plan 技能，帮我对“订单备注”功能做方案设计。 约束：数据库是 MySQL，接口需要兼容旧客户端，备注长度不超过 500 字。

3.2 research：先查清楚再动手

research 技能解决的是"不懂装懂"的问题。让 AI 直接改代码时，它经常凭训练数据里的印象猜测 API、依赖项、项目结构，结果改出来的东西根本编译不过。research 技能要求它在给出结论前，先列出需要确认的事实清单，然后逐个通过文件检索、搜索等手段验证，并附上出处。

这个技能很适合接手陌生代码库。老项目里经常有各种历史包袱：某个字段叫status但取值范围是 0 到 3，某个接口要兼容五年前的客户端。如果 AI 没做 research 就直接动手，几乎必然出错。我在实战中发现，research 的输出质量取决于你给它的调查范围。提示词越具体，它的调查越聚焦，比如"帮我查一下 OrderMapper 里现有的 update 方法叫什么、参数是什么"就比"查一下项目的数据库操作方式"要好得多。

3.3 subagent：用独立上下文跑子任务，避免主线程注意力被稀释

subagent 是我认为整个超能力体系里最巧妙的设计。当一个任务要改多个模块时，如果让主线程从头到尾包办，它到了后期往往记不住前期的决策，上下文也越来越乱。subagent 的做法是：把任务拆成几个子任务，每个子任务用独立上下文执行，最后再把结构化结果汇报给主线程。

类比一下：一个项目经理不会自己去写所有代码，而是把清晰的任务分派给几个工程师，每个人只关注自己那一亩三分地，最后汇总。子代理之间互不干扰，主线程也只接收总结，大大降低了上下文爆炸的风险。但 subagent 对任务拆分质量要求很高：边界不清的子任务，汇总时会出现重复和冲突。我后面在实战案例里会具体讲到这个问题。

3.4 implement：把计划落地成代码，而不是边写边编

implement 技能负责把已经确定的计划变成代码。它的核心要求是按步骤执行、每实现一步就对照验收条件，遇到偏差要么调整计划要么明确告诉用户，而不是默默改写需求。很多 AI 越写越偏，就是因为缺少这一步的自我校验。

在实际使用中，implement 通常不是孤立的。它会接收 brainstorm_plan 输出的计划，结合 research 的调研结果，最后执行代码变更。如果只是让 AI 直接写代码，它大概率会在实现过程中"灵机一动"加了点新逻辑；而走了 implement 流程后，它会严格对照计划清单，改动范围变得可控。

3.5 它们不是固定流水线，而是一套可组合的决策表

这些技能并不是必须按顺序执行才能生效，它们更像是一套积木，模型根据任务类型决定组合方式。我总结了一个简单的决策表：

模型通常会自己判断，但你也可以在 prompt 里指名调用，减少不确定性。我一般会在重要任务开始时用一句话"用 brainstorm_plan 先做方案"，这就相当于给 AI 上了个保险。

4. 实战案例：用 superpowers 在一个 Java 项目里新增 REST 接口

4.1 任务描述与环境

光讲理论不落地很容易虚，我拿一个真实做过的 Java 项目案例来说。项目背景是 Spring Boot 3.2 + MyBatis-Plus 的订单服务，代码库里已经有Order实体、OrderMapper、OrderController这些类。需求是新增一个"更新订单备注"的接口：PATCH /orders/{id}/remark，请求体是 JSON 格式的{"remark":"..."}，备注最长 500 字，需要更新数据库的 remark 字段，并且补上单元测试。

这个需求看起来很小，但涉及实体变更、DTO、Controller、Service、Mapper、单测六个文件，如果不做任何规划直接让 AI 写，经常会出现"改了 Controller 忘了实体"这类问题。

4.2 执行轨迹：plan -> research -> subagent -> implement

第一步，我触发了 brainstorm_plan：

使用 brainstorm_plan 技能，为“更新订单备注”接口设计方案。 约束：使用 Spring Boot 3.2；兼容旧客户端；需要单测。

技能输出的方案表里给了三个候选：A 是新增 DTO + Service 方法，B 是直接在 Controller 里 set 字段，C 是做一个通用 update 接口。最终推荐 A，并标出了风险点：旧版客户端如果传了 null，会把备注清空，这需要你在计划里明确"null 到底算不算合法输入"。这个风险点我确实没想到，是技能强制发散后才暴露出来的。

第二步，触发 research。我先让 AI 查几件事：Order实体里是否已经有 remark 字段、OrderMapper现有 update 方法、Controller 统一返回结构、项目里单测的写法。这一步输出的结论是：实体没有 remark 字段，需要加；Mapper 有现成的updateById；单测用的是 MockMvc。这些事实让后续 subagent 不需要再浪费时间猜测。

第三步，拆 subagent。我把任务拆成了三个：

• subagent A：改Order实体和OrderMapper。
• subagent B：新增UpdateRemarkRequestDTO、OrderController接口、OrderService方法。
• subagent C：写 MockMvc 单测。

每个 subagent 我都明确要求了边界："只改 src/main/java，不要动 pom.xml，不要动其他 Controller 的接口。"这个边界声明非常关键，少了它子代理就会自由发挥。

第四步，implement 合并。三个子代理各自产出了 diff，我合并后跑了一次mvn test。第一次测试果然挂了：DTO 上忘记加@Size(max=500)校验注解，导致超长文本没有被拦截。AI 根据报错日志修正了代码，最终实现的 Controller 长这样：

@PatchMapping("/{id}/remark") public Result<Void> updateRemark(@PathVariable Long id, @RequestBody @Valid UpdateRemarkRequest request) { orderService.updateRemark(id, request.getRemark()); return Result.ok(); }

4.3 实测中最花时间的不是写代码，而是"边界澄清"

整个流程下来，真正花时间的不是 AI 写代码那几分钟，而是边界澄清。我在这个项目里踩到了三个坑：subagent A 越过了边界改了 pom.xml，虽然只是加了一个依赖，但如果不是我及时看 diff，后面排查依赖冲突会非常痛苦；plan 阶段没有定义"remark 传空字符串是否允许"，导致写单测的子代理和改实体的子代理用了两种理解；两个子代理用了相同的测试数据，合并时发生了冲突。

superpowers 并没有神奇地消除这些问题，但它把问题提前暴露在了 plan 阶段。更重要的是，它让 AI 在遇到模糊点时不再瞎猜，而是会回到计划里检查甚至直接问用户。我的建议是：在 brainstorm_plan 输出计划后，花两分钟手动补上那些你不希望 AI 自行决策的边界条件，再进入 implement。一次投入，后面少走很多弯路。

5. 踩坑记录：技能不触发、上下文爆炸、跨工具兼容

5.1 技能不触发：先检查 description，再检查目录

技能不触发是我见过最多的问题。排查顺序很重要，我的经验是：

1. 先确认会话是否读取了正确的 CLAUDE.md / AGENTS.md，直接让 AI 复述内容。
2. 再确认技能目录位置、文件名和 CLAUDE.md 中的描述是否一致。
3. 检查description是否写得足够具体。
4. 想想当前任务是不是简单到模型判断"不需要技能"。
5. 最后重启 CLI、开启新会话再试一次。

我遇到过最典型的案例：某个技能的 description 写得笼统，只写了"Use this skill for planning anything"，结果模型把什么请求都当成 planning，频繁误触发；改成"当需求不明确或存在多个实现方案时使用"后，触发率才恢复正常。description 就像技能的门牌号，门牌号写错了，模型当然找不到门。

5.2 技能文件太多导致上下文爆炸

有人觉得技能越多越好，结果把几十个技能文件全塞进项目，然后在 CLAUDE.md 里把每个技能的完整内容都贴出来。这是很常见的反面教材。技能说明占用的上下文空间会在每轮对话中被重复计算，token 消耗暴增，同时模型的注意力也会被稀释，反而开始忽略关键指令。

正确做法是：CLAUDE.md 只放技能索引，完整技能文件按需读取；核心技能控制在 10 到 15 个以内；不常用的技能归档到子目录，需要用的时候再让模型去读。我在项目里维持 8 个技能左右，运行明显比 30 个技能时稳定。

5.3 Codex 与 Claude Code 的兼容差异

很多人问"superpowers 是不是只能用在 Claude Code 上"，我在 Codex 里也试过。两者确实有差异，主要体现在约定上：

我在 Codex 项目里的做法是，在 AGENTS.md 里写清楚：

# superpowers 使用说明 本环境有一套技能目录 .claude/skills/，包含 brainstorm_plan、research 等技能。 当任务类型匹配技能描述时，先执行 `cat .claude/skills/<skill_name>.md` 读取完整内容，再按照技能步骤执行。

这样 Codex 就能通过显式指令找到技能文件。所以如果你同时用多个终端 Agent，完全可以共用一套技能文件，只需要分别为入口文件补一份说明。

5.4 模型升级后技能失效

这是比较隐蔽的坑：模型升级后，对长文本指令的遵循方式可能变化，导致原来描述精确的技能开始不起作用。我遇到过新版本模型对 frontmatter 的解析粒度变化，技能文件本身没动，但触发率明显下降。

我的应对方案是给技能文件加version字段，然后在模型大版本升级后跑一遍冒烟测试：用一个最简单的小任务走完技能流程，看它是否正常触发。不通过就微调 description 的措辞，而不是怀疑整个方案。技能库是需要持续维护的资产，不是装完就一劳永逸。

6. 我的使用心得：什么场景值得用，什么场景别硬套

6.1 我用它最多的地方

现在我的主力场景有三个：跨模块重构、新功能从想法到落地、接手陌生代码库之前的调研。这三个场景有个共同点：任务复杂到"先想清楚再做"的价值远大于"快点动手"。以前让 AI 直接写 API，十个里有四个会漏参数校验和错误处理；现在只要先走一遍 plan + research，基本不会漏，因为技能强制它在动手前把边界过一遍。

另外我还做了一次实践：把团队里反复出现的"数据库迁移 review"流程固化成了一个自定义技能，AI 在检测到迁移脚本时会自动检查索引缺失、超大表风险、回滚方案等问题。这个效果比任何口头提醒都稳定，计算机不会忘记执行步骤。

6.2 别硬套的场景

superpowers 也不是万能的。碰到单行 bug、快速验证、聊天式答疑这种小任务，我会直接让 AI 改，不走技能流程。原因很简单：技能加载本身就有一段说明和读取过程，小任务硬套技能，会在流程上浪费大量 token，模型也显得啰嗦。

怎么判断？如果这个任务五句话能讲清楚，就不值得启动技能链；如果一件事要改三个以上文件、影响多个模块、或者需求还说不清楚，那就老老实实用 superpowers。判断标准应该是"任务复杂度"而非"项目规模"。

6.3 最后分享一个小习惯

我现在每次开新项目，第一件事就是把 superpowers 装好，但第一时间会删掉一半用不上的技能。技能不是越多越好，而是要跟项目形态匹配。后来我逐渐养成了一个习惯：每次遇到"AI 表现得特别好"的流程，就把它固化成一个新的技能文件，放进项目里共享给团队。看着 AI 稳定地执行着自己沉淀下来的流程，再想想以前每次都要在 prompt 里反复解释的时光，我觉得当初花几十分钟研究安装和配目录，非常值。