企业官网建设流程全解析

最近一两年，AI 编程助手几乎成了我写代码的标配，但说实话，很长一段时间我对它们的感觉是又爱又恨。让它写个工具类、补个单元测试，它挺利索；可一旦涉及多文件、跨模块的改造，它就特别容易自嗨：方案没对齐就动手，测试没跑完就宣布胜利，出了问题又习惯性甩锅。直到我接触了superpowers这个给编程助手加技能的开源项目，情况才开始真正改观。

这篇内容不聊 PPT 式的理论，全部围绕superpowers的安装、核心技能拆解、在 Java 工程里的实际用法，以及怎么把它平移到 Codex 这类工具上。适合已经被 AI 的"乱拳"打过、想让助手按章法干活的同学参考。我尽量把那些装完又删、删完又装的折腾过程也写出来，你照着走能少踩几个坑。

1. Superpowers 到底是什么：给 AI 编程助手装上"章法"

1.1 它不是插件，而是一套可加载的技能文档

我第一次看到superpowers这个名字时，以为是那种给你补一堆 IDE 快捷键的插件，或者一个把提示词塞满上下文的库。用完之后才发现，它做的事其实很朴素：把"人类工程师的工作方法"写成一份份结构化的 Markdown 技能文件，让 AI 在需要的时候按需读取，照着这套流程工作。

这些技能文件不是普通的提示词，它们更接近一份"操作手册"。比如brainstorming这个技能，里面详细规定了 AI 在讨论方案时应该先做什么、后做什么、哪些问题必须问清楚、哪些结论必须输出。它不告诉 AI"你要聪明一点"，而是告诉它"你现在扮演一个技术方案评审人，先列出候选方案，再写出每个方案的代价和风险，最后才给出推荐"。

在 Claude Code 这类支持 Skills 机制的工具里，这些技能文件被放在固定目录下，工具会在对话中根据任务自动决定是否加载。你用自然语言说"我想对这个模块做一次重构"，它如果判断这个动作符合某个技能的触发条件，就会把对应的 SKILL.md 内容注入上下文，然后按流程执行。

1.2 它解决了我三个具体的痛点

第一个痛点是上下文被闲聊冲散。AI 助手很容易在长对话里忘掉目标，聊着聊着就从"重构接口"跑偏到"顺手优化一下配置"。技能文档相当于给对话加了一根锚，让 AI 随时知道自己正在执行哪个阶段的任务，下一步该干什么。

第二个痛点是方案随意、动手太快。以前让 AI 帮我设计一个新模块，它经常直接开始写第一版的类，写到一半发现方向错了。但有了 brainstorming 这类技能之后，它会在写代码之前强制进入"讨论模式"，先跟你确认业务范围、性能目标、兼容性约束，再输出设计方案。

第三个痛点是调试毫无章法。遇到 bug，AI 最常见的操作是瞪着眼睛看代码，然后猜一个原因，直接改掉。运气好能蒙对，运气不好就是连环踩雷。systematic-debugging技能教它先收集证据、再形成假设、验证假设、最后才动手，这套流程对我这种老项目维护者来说太重要了。

1.3 和普通提示词、插件模板的区别

很多人会觉得，那我把一段话写进系统提示词不就行了？还真不一样。我自己试过把"请按步骤思考、先分析再回答"写进提示词，效果不稳定：开始的几轮还有用，聊深了规则就被稀释了。

技能文件的优势在于"按需加载"。它的描述信息很短，平时不占上下文，只有 AI 判断任务匹配时才会完整加载。而普通提示词是常驻的，长了浪费上下文窗口，短了又没有约束力。插件模板则更偏工具集成，负责改 IDE 行为，不负责改造 AI 的工作方式。superpowers恰好补上了中间这段：不管底层是 Claude、Codex 还是本地模型，只要它能读懂 Markdown 文档、能调用工具，这套技能体系就能跑起来。

2. 安装：标准脚本和手动布置两条路

2.1 标准安装脚本：一条命令装完

superpowers官方提供的是install_superpowers.sh这个脚本，我在 macOS 的终端里跑了一下，过程比想象中顺利。基本的安装方式是通过 curl 拉取脚本并执行，命令长这样：

bash -c "$(curl -fsSL https://raw.githubusercontent.com/obra/superpowers/main/install_superpowers.sh)"

具体的下载地址以仓库 README 为准，因为版本更新可能会调整路径。脚本干的事情说白了也不复杂：拉取技能仓库、逐个技能目录复制到 Claude Code 的 skills 目录下、输出一份安装汇总。执行完之后，终端会列出已经被识别的技能列表，我看到里面有brainstorming、systematic-debugging、test-driven-development、code-review等，排列得整整齐齐。

装完之后我特意去看了一眼技能目录，位置在~/.claude/skills/下面，每个技能一个子目录，里面至少有一个SKILL.md文件。这个文件就是技能的核心，头部用 YAML 写名称和描述，正文写具体的执行流程和步骤。你完全可以把它理解成一个小型的"工作流模板库"。

2.2 手动安装：自制技能目录

如果你用的工具不是 Claude Code，或者你想把技能放在项目里跟着仓库走，脚本安装就不够灵活了。这时候就得手动建目录。我的做法是在项目根目录建一个.claude/skills/文件夹，然后把需要的技能按相同结构复制进去。

每个技能目录下至少要有SKILL.md，里面分两块：头部 metadata 和正文。头部 metadata 里最重要的是description，它会决定 AI 什么时候触发这个技能，所以不能写得太泛。比如我自建了一个叫database-migration的技能，描述写的是"当用户要求修改数据库表结构、数据迁移或索引调整时使用"，而不是笼统的"数据库相关操作"。

正文则按步骤写清楚流程：第一步做什么、第二步收集什么信息、第三步产出什么文档。这个格式跟官方技能保持一致，工具才能正确解析。手动安装不要求你一次就把所有官方技能都搬过去，用什么搬什么，目录反而更干净。

2.3 装完第一件事：确认技能真的被加载了

很多同学装完就跑，结果半天没触发，就说项目没用。我建议装完之后先做一次冒烟测试。打开支持 skills 的对话工具，输入一句跟某个技能强相关的请求，比如直接说"用 brainstorming 的方式帮我想想这个功能的实现方案"。

正常情况下的表现是：AI 会先读技能文档，然后严格按照里面的流程反问问题，而不是直接甩给你一段代码。如果它还在照旧自由发挥，那就多半是技能没被识别。这时候先检查目录结构，是不是把SKILL.md放错层级了，再看 metadata 的 YAML 格式是不是有缩进问题。这两个是最容易出错的地方。

另一个容易被忽略的点：技能文件是启动时扫描的，有些工具改完目录之后需要重启会话或者手动刷新技能列表。我第一次改完没重启，死活加载不进来，重启之后立刻就好了。别在这种小地方浪费时间。

3. 我最常用的三个技能：从头脑风暴到系统化排错

3.1 brainstorming：动手前先对齐目标和约束

brainstorming是superpowers里我最常用的技能，没有之一。它的核心思路很简单：AI 在动手写代码之前，必须先跟你确认四个问题——你要解决的核心问题是什么？有没有什么约束条件？成功的标准是什么？你更倾向于哪种方向？

听起来像是废话对吧？但你去观察 AI 平时写代码的状态，就知道这四个问题有多少时候被直接跳过了。我举一个真实例子：之前我想给一个 Java 服务加个缓存，以前直接让 AI 写，它马上就给我整了个 Caffeine + Redis 双缓存方案，还要改一堆配置。但用 brainstorming 技能走了一遍之后，它先问我"缓存一致性要求多高""QPS 大概多少""数据是冷热分明还是均匀分布"，最后聊出来的方案变成了只加 Caffeine 单机缓存，因为业务量根本不需要 Redis。

这就是技能带来的价值：它不是让 AI 变成一台只会执行的机器，而是让它先做一个合格的需求沟通者。流程上，brainstorming 通常分两轮，第一轮发散收集所有可能的方案，第二轮收敛做对比分析。AI 在每轮结束时会输出一份简短的结论，你在聊天里确认过，它才会继续往下走。这个过程很费对话轮数，但比写错代码返工省太多时间。

3.2 systematic-debugging：让 AI 按证据推因而不是猜

第二个让我印象深刻的技能是systematic-debugging。它的方法论其实是我们老一辈程序员排查问题的标准流程：先复现、收集证据、检查错误信息、形成假设、验证假设、修改、回归验证。

以前我把一个诡异的偶发超时报错丢给 AI 解析，它瞄了一眼代码，非常笃定地说"这是线程池配置问题，你改一下参数"。结果我改了，问题第二天还在。用systematic-debugging技能之后，AI 的行为完全变了。它先让我提供完整的错误日志、复现步骤、最近改动记录；然后列出可能导致超时的三个假设，分别是数据库连接池耗尽、HTTP 客户端超时配置过短、上游服务响应变慢；接着给出验证每个假设的具体手段，连带日志命令都帮我写好了。

这套"先证明、后修改"的流程，本质上是在防守 AI 最致命的毛病：过度自信。它可能因为训练数据里见过类似代码片段，就锁定了一个错误答案，而技能会强制它走完证据链。对于生产环境出的问题，这个技能相当于给 AI 戴上了一个"必须检查再下结论"的紧箍咒。

3.3 code-review：让 AI 挑刺，而不是夸你

code-review技能我是在一次合并请求前无意间用上的。当时我让 AI"帮我看看这次改动有没有问题"，它居然开始夸我逻辑清晰、注释到位。我当场就皱眉了，这哪是评审，分明是捧场。后来切成 code-review 技能重新跑了一遍，它输出的就是完全不同的东西了：列出的问题包括一个事务边界过大的隐患、一个资源未关闭的路径、一个空指针的潜在触发点，还按严重程度排了序。

这个技能的机制其实很朴素：它给 AI 设定了一个明确的角色和检查清单，要求 AI 在代码中寻找特定类型的缺陷，而不是泛泛地总结代码做了什么。检查清单包括安全漏洞、边界条件、并发问题、异常处理、可读性等等。它输出的报告也很有结构，每条问题都带文件位置、风险等级、修改建议。

在 Java 项目里我特别喜欢它的并发检查能力，因为很多 AI 写的代码单看没错，但放到高并发环境下就有共享状态污染问题。技能会盯着这一点反复检查，比我肉眼 review 靠谱得多。现在我的合并请求都会先过一遍这个技能，基本能滤掉六成低级问题，剩下的人工再抽时间细看。

3.4 触发方式小结

这几个技能在日常使用中不需要你手动切换。只要对话里提到了"设计""方案""优化"这类词，AI 就可能自动加载brainstorming；提到"报错""超时""崩溃"，就自动加载systematic-debugging。如果它没触发，你也可以用自然语言直接点名："请使用 brainstorming 技能来讨论这个问题"，它就一定会去读对应的 SKILL.md。

有一次我试着把两个技能叠加使用——先用 brainstorming 讨论重构方案，再用 TDD 技能指导我为重构后的代码写测试——AI 全程没有跑偏。它的对话结构变成：方案讨论输出文档，测试策略输出测试清单，最后才进入编码阶段。这种"章法感"是我以前从未在 AI 编程助手上体验过的。

4. 在 Java 工程里的实战：用它改一个老 API 模块

4.1 项目背景：一个常年没人敢动的模块

为了讲清楚superpowers在真实项目里的作用，我拿自己维护的一个 Java 17 + Spring Boot 3.2 的老订单查询 API 举例。这个模块大概有两千行代码，核心接口是"根据用户 ID 查订单列表"，线上平均响应 800 毫秒，高峰期经常飙到两秒以上，超时告警隔三差五就响。前任维护者留了一句注释："不要轻易动这个方法，里面逻辑全耦合在一起。"

这种代码最麻烦的还不是 SQL 写得烂，而是它同时承担了权限校验、状态流转判断、多类型订单分类、分页过滤好几件事。任何一处改动都可能影响其他逻辑，所以团队默认这个模块"只能加参数，不能改结构"。我也抱着这种心态混了很久，直到那次响应时间差一点触发了 SLO 红线，才决定认真处理。

4.2 用 brainstorming 技能产出改造方案

我打开 Claude Code，对着项目目录输入了改造需求，并点名要求使用 brainstorming 技能。AI 读了技能文档之后，没有一上来就甩代码，而是先问我几个关键问题：这个接口的响应时间目标是多少？当前 QPS 峰值是多少？数据库用的是 MySQL 还是 PostgreSQL？下游依赖的服务是否可以接受异步化？

我回答了之后，它输出了三套候选方案：第一套是保持接口同步逻辑不变，只对订单表加索引并优化 SQL；第二套是引入本地缓存，按用户维度缓存订单摘要；第三套是把订单列表拆成快照表，用事件异步更新。每套方案都带上了代价评估：方案一改造成本最低、收益有限；方案二收益中等、缓存一致性有风险；方案三收益最大，但要做数据迁移和事件补偿，牵涉面很广。

这个过程的收获不在于 AI 给了我什么神仙答案，而在于它逼着我想清楚了约束条件：我不能改接口协议、不能加新的中间件、必须在一周内上线。基于这些约束，讨论很快收敛到了方案一加部分方案二：先做 SQL 优化和索引调整，再针对高频用户加一个短 TTL 的 Caffeine 缓存。这个方案如果真的让我直接拍脑袋，大概率会选错方向，因为我在不带约束的情况下总是倾向于"功能越强越好"。

4.3 用 TDD 技能把测试补起来

方案定了，接下来就是执行。照以前的工作方式，我会让 AI 直接改代码，改完了再补测试。这次我特意先加载了 TDD 技能，让 AI 按"红-绿-重构"的流程走。

这个技能把测试从"可选动作"提升成了"第一个动作"。AI 先基于老的返回结构和预期行为，写了一批描述性的测试用例，涵盖了正常查询、无订单、分页参数异常、用户无权限这几种场景。其中几个测试在改造之前就应该是通过的，因为它们描述的其实是现有正确行为，这相当于给老模块拍了一张行为快照，后续改动如果破坏了任何已知行为，测试会第一时间喊停。

改造过程中 AI 确实踩了一个坑：新加的索引在本地数据库还没同步，测试一直报查询超时。换成别的助手，可能就直接改测试的断言来"适应"新逻辑了。但因为 TDD 技能明确写了规则——测试失败时首先要判断是行为变更还是实现错误，AI 停下来问我，说测试和环境不一致，而不是悄悄把断言改掉。这一点让我非常感慨，没有这套规则约束，AI 绝对会为了"让测试通过"而进行自我欺骗。

模块上线之后，我把新旧版本的响应时间数据拉出来做了对比。接口平均响应从 800 毫秒降到了 240 毫秒，P99 从两秒降到了 500 毫秒出头。更让我安心的是，那次改动跑了快一个月，没有再出现超时告警。

4.4 复盘：superpowers 发挥了什么作用

整个改造流程走下来，我最大的感受是：superpowers真正改变的不是 AI 的能力上限，而是它工作的下限。以前 AI 可能在方案没对齐时就写了五百行代码，这次写上第一行代码之前，AI 已经产出了完整的需求文档、测试计划和风险评估。

我一直觉得，AI 编程工具的真正用法不是让它"替我做"，而是让它"陪着我想清楚再动手"。brainstorming 负责想清楚，TDD 负责别跑偏，systematic-debugging 负责出事时不慌。三件事各管一段，正好是资深工程师在带新人的时候最强调的那套方法论。

5. 把 Superpowers 平移到 Codex：技能文档的一物多用

5.1 为什么需要平移

superpowers一开始是围绕 Claude Code 的 skills 机制设计的，但技能文件本质上是 Markdown 文档，并不绑定某个具体的 AI 产品。我平时还会用 OpenAI Codex 处理一些脚本类任务，所以就琢磨着能不能把同一套技能搬过去用。

结论是可以，但需要一点改造。Claude Code 能直接识别~/.claude/skills/下的技能目录，并在对话中自动注入，而 Codex 的上下文加载方式和技能触发机制不太一样，它更依赖项目根目录下的AGENTS.md来获取长期指导信息。所以我换了一种思路：不追求百分百的自动触发，而是把关键技能的核心步骤压缩成规则片段，写进项目的AGENTS.md里。

5.2 我在 Codex 里的挂载方式

我的做法是，给 Codex 项目准备一份精简版的AGENTS.md，里面把最常用的两个技能——brainstorming 和 code-review——的要义提炼成几条硬规则。比如 brainstorming 那段就写了"动手写代码前，必须先列出候选方案和约束条件，等待用户确认"，code-review 那段就写了"评审时只列具体风险和文件位置，不做泛泛总结和夸奖"。

这不算是完整版本的superpowers，但执行效果很接近。我在一个内部命令行工具的开发中实测过，Codex 在改代码之前会主动问我完全约束条件，不再直接开写。它读的是我写进去的规则，而这些规则的逻辑来自superpowers的技能文档，所以我把它称为"技能文档的一物多用"。

如果你用的是带 Agents 功能的 Codex，也可以直接让它"读skills/brainstorming/SKILL.md并照做"，它同样能理解这份 Markdown 文档的含义。核心技巧就一条：不要试图让所有工具用同一种方式加载技能，而是顺着工具的上下文机制去适配。

5.3 不同模型之间调教的差异

平移的时候要注意，不同模型对技能文档的服从度不一样。Claude 系模型对流程型指令的遵循能力比较强，我让 Claude Code 严格执行 brainstorming 的轮次结构，它基本能做到；Codex 在某些场景下会更"直接"，所以光让 AI 写到"等用户确认"是不够的，我还会额外补充一句"没有确认之前不允许输出代码"。

本地部署的模型则更麻烦，上下文窗口小，技能文档稍微长一点就会被截断。我给本地模型用的技能文件都是特别精简过的，只保留最关键的检查项，每条不超过三句话。所以如果你手头有多种 AI 工具，建议按模型能力做减法，而不是一套技能文件走天下。

这个思路反过来也能用在日常文档上：我把每个月写技术方案时要用的检查清单，整理成一份progress-review技能，放进项目的技能目录。不管是 Claude、Codex 还是别的助手处理同一个仓库，只要它能读到这份文档，工作的起点就统一了。

6. 踩坑记录与一条值得养成的习惯

6.1 坑：技能文件太贪长，上下文直接溢出

我最开始接触superpowers时有个坏毛病，喜欢把官方技能原封不动全部搬进项目里，觉得越多越保险。结果有一次对话刚开始，AI 就把五个技能文件全加载了，上下文中 Markdown 原文比代码还多，对话进行到一半模型就开始"失忆"，把前面的结论忘得一干二净。

后来我才理解，技能机制设计成"按需加载"是有道理的。每个技能在 metadata 中有一段精炼描述，AI 是根据描述去判断要不要读取全文的。如果描述写得太宽泛，比如"任何代码修改都可以使用此技能"，那 AI 就很容易激进加载。我的解决办法是给每个技能文件瘦身，把正文压缩到最多八十行，并且把描述写窄。比如把code-review的描述改成"仅在用户要求 code review 时使用"，而不是"检查所有代码问题"。

6.2 坑：技能版本与工具版本脱节

superpowers迭代速度不慢，而我的 Claude Code 可能一两个月才升一次级，偶尔会出现技能文档里写了某个新命令，但当前工具根本不支持的尴尬。我遇到过最典型的一个问题：技能要求 AI 调用一个memory相关工具来记录关键决策，但我的工具版本里压根没有这个工具，AI 只能在对话里假装调用，输出一些假的中间结果。

这就是典型的版本脱节。现在我养成了一个小习惯：每更新一次superpowers，就带它跑一遍冒烟测试清单，确认各个技能描述中的工具名在当前环境里存在。如果某个技能依赖的底层能力没跟上，我会直接暂时移除这个技能，宁缺毋滥。

6.3 一条新习惯：把技能当成团队新人手册来写

用了一段时间之后，我发现superpowers最大的价值已经不再是那个开源项目本身了，而是它给我提供了一种"和 AI 协作的结构化方法"。我现在自己写团队文档的时候，也会用技能文件这个格式——有触发条件、有步骤、有输出物。团队的新人接手一个模块时，我告诉他的第一件事不是去看代码，而是去读项目里的技能文档。

比如上个月我给支付模块写了一个refund-check技能，里面写清了退款前必须检查的六项条件、每项条件不满足时的处理动作、最终输出报告的结构。这个技能本身没几行字，但无论是让 AI 辅助处理退款工单，还是让新人照着做人工审核，都能用。一份文档喂两个群体，效率翻倍。

回头看，我折腾superpowers的最大收获并不是让 AI 从六十分变成了八十分，而是让我重新理解了"把流程写成文档"这件事的价值。以前我们写文档是给同事看的，现在文档还要给 AI 看。让 AI 按章法干活，有时候不需要更聪明的模型，只需要把章法写得足够清楚。如果你也在跟这些问题搏斗，不妨从一个小技能开始，把你最常做的一件事整理成 SKILL.md，然后看看你的 AI 助手会不会突然变得靠谱起来。