企业官网建设流程全解析

最近在折腾AI编程工具的时候，圈子里好几个朋友都在聊 superpowers。一开始我还以为是某个新出的IDE插件，仔细一看才发现，这压根儿不是插件，而是一整套面向编码助手的技能包（skills）和工作流框架。简单说，它把“让AI帮你写代码”这件事，从一锤子买卖的问答式对话，变成了一套有规划、有步骤、可追溯的工程流程。如果你正在用 Codex、Claude Code 这类命令行编程助手，又觉得AI生成的代码总是改一步崩两步、缺东少西，那这篇文章就是给你准备的。我会从安装配置讲到核心工作流，再讲怎么自己扩展技能包，最后把实操中踩过的坑一并列出来，内容偏实战，不整虚的。

1. superpowers 的核心思路：把AI从“问答机器人”变成“项目协作者”

1.1 为什么“让AI写代码”经常翻车

先说一个大家都能共鸣的场景。你丢给 Codex 一句“帮我把这个React组件加上导出CSV的功能”，它唰唰写出一段代码，看起来没问题，一运行就报错，原因可能是没处理编码、没考虑大数据量、甚至把现有逻辑改坏了。问题出在哪？不是你不会提问，而是这种一次性问答式的交互方式，天然缺少两个东西：上下文和流程。

上下文是指AI对你整个项目的了解程度，它不知道你这套代码的历史包袱、模块边界和潜在约束。流程是指从需求到落地的完整路径，它没有“先梳理方案、再写计划、最后按计划执行和验证”的概念。直接跳到编码，等于让一个实习生不看需求文档就动手改生产代码。

superpowers 要解决的，就是给编码助手补上这两块缺失：通过结构化的技能包，引导AI一步一步完成“理解需求 → 设计方案 → 制定计划 → 执行编码 → 验证复盘”的完整闭环。这听起来不复杂，但在实践里效果却非常明显，因为AI的推理能力是随着问题被拆解而提升的，你把任务拆得越细、每一步约束越清晰，它出错的概率就越低。

1.2 技能包（Skills）机制是怎么运作的

superpowers 本质上是一套 Markdown 技能文件的集合，每个技能文件就是一份高度结构化的“操作指令书”。当你在对话中要求调用某个技能时，编码助手会读取对应文件，然后严格按照里面的步骤、规则和验收标准去执行。

我举个具体的例子。在 superpowers 里有一个很核心的技能叫“brainstorming”，它的作用是引导AI在动手写代码之前，先围绕需求进行发散与收敛。你告诉它一个模糊的想法，它不会直接开写，而是会反过来问你一系列问题：这个功能的核心用户是谁？边界条件有哪些？性能要求是什么？有没有兼容性约束？等这些信息对齐以后，它才会输出几个候选方案，并给出推荐项。对使用者来说，这个过程就像有一个经验丰富的同事坐在旁边帮你把关。

技能包的价值在于“可复用”，你不需要每次从零开始写prompt，只需要调用对应的技能，AI就会按照既定流程走。而且技能文件本身是开源的、可以自定义的，你觉得某个流程不适合自己的项目，直接改文件就行。这种灵活性让它区别于市面上那些“一键生成CRUD”的封闭工具。

1.3 与“预设prompt”或“提示词插件”有什么区别

很多AI增强工具不过是把一堆提示词模板打包起来，本质上还是“你说一句，它答一句”，仍然停留在单轮问答的层面。superpowers 的差异在于它引入了“状态”和“产物”这两个概念。

所谓状态，是指skill的执行过程会在项目里留下文件痕迹，比如 plans 目录下会生成一份份计划文档，进度记录会持续更新，AI并不会“失忆”。所谓产物，则是指每一次技能调用都会产出可检查的结果，比如需求分析文档、实施计划、代码提交记录，这些产物成为后续工作的依据。这已经非常接近“人在环路”的项目管理流程了。对于个人开发者或小团队来说，这相当于免费获得了一个懂流程的项目经理。

更关键的是它的增量式执行思路：把一个大需求拆成若干个小步骤，每个步骤都有明确的目标和验收标准，AI每完成一步，就停下来、汇报进度、接受检查。一旦出问题，可以精准回滚到前一步，而不是把整个改动推倒重来。这种“小步快跑、步步留痕”的模式，正是工程化开发里最核心的经验，被 superpowers 巧妙地固化到了技能包里。

2. 安装与项目结构：半小时跑通基础环境

2.1 环境准备清单

在动手装 superpowers 之前，先把基础环境准备好。它依赖的是 Node.js 生态和任一主流代码AI工具（官方推荐 OpenAI Codex CLI，但 Claude Code、Gemini CLI 这类工具同样可以接入）。我个人建议 Node.js 版本在 18 以上，太老的环境跑起来会有兼容性问题。

需要说明的是，superpowers 本身不是一个传统意义上的“软件包”，而更像一个“知识库/技能库仓库”，所以你不需要执行什么复杂的编译流程。安装的本质就是把这套技能文件克隆到本地，并让AI工具能在对话里找到它们。这一步对新手非常友好，全程不需要写代码。

准备清单大致如下：

• Node.js 18+（检查办法：node -v）
• Codex CLI 或其他兼容的编码Agent工具
• Git（用来克隆 superpowers 仓库）
• 一个已经初始化过的项目目录（空项目也行）

2.2 安装步骤：从零到可用的完整命令

我实测下来，整个安装过程大约十分钟就能搞定（网络状态好的话更快）。先把 Codex CLI 装上，如果你是 macOS 或 Linux，打开终端执行：

npm install -g @openai/codex

安装完成后，用codex --version验证是否成功。接着是克隆 superpowers 仓库，这里我建议把它放到一个独立目录，而不是直接塞进项目里，方便日后统一更新：

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

克隆完成后，进入目录确认文件结构完整。

然后最关键的一步：把 superpowers 的路径挂载到 Codex 的配置里。Codex CLI 会读取~/.codex/config.toml，你需要在里面增加一个指令文件的引入。大概效果是这样的：

[instructions] files = [ "~/superpowers/superpowers.md", ]

这个文件相当于一个入口，它会把所有技能包的索引和调用说明注入到对话上下文中。改完配置保存，重新打开 Codex，输入“/help”或者在对话里问到“有哪些技能可用”，如果能看到技能清单，就说明已经挂载成功。

如果用的是 Claude Code，路径配置也类似，只不过配置文件的位置和字段名稍有差异，但思路完全一样：让工具知道去哪里读技能文件。

2.3 目录结构解读：每个文件夹是干什么的

clone 下来以后，你会看到一堆目录和文件，我建议花几分钟把结构理清，后面用起来会顺手很多。默认的结构大致包含 skills、plans、notes、scripts 这几个核心目录。

skills 目录是整个系统的核心，里面按主题存放着各种技能文档，比如 brainstorming、writing-plans、executing-plans、review 等。每个子目录里通常有一个SKILL.md文件，里面定义了技能的调用方式、前置条件和执行步骤。这是AI实际会读取的内容。

plans 目录用于存放AI在执行任务时生成的实施计划，每跑一个任务就会产生一份带时间戳和任务编号的计划文件。notes 目录则用来维护项目笔记，AI会在这里记录需求变更、技术决策、排查记录等长期记忆。scripts 目录则放着一些自动化脚本，用于辅助生成技能模板、管理任务状态等操作。

我自己的经验是，不要一上来就想着把每个文件都读完，你只需要理解一个核心循环：调用技能、生成计划、执行计划、更新笔记。这个循环是superpowers的心脏，其他文件都是为它服务的。

2.4 IDE 与 CLI 的使用体验对比

有朋友问过，superpowers 是不是只能在终端里用？其实不是，它同样可以配合支持 Codex 的 IDE 插件使用。但从我个人的实操体会来看，命令行模式下反而更顺手，原因是技能调用本身是通过自然语言指令完成的，比如在Codex里输入“请调用brainstorming技能，帮我梳理一下这个需求”，终端交互非常直接。

当然，如果你更习惯在编辑器里工作，把同样的配置挂到IDE插件上也能生效。区别在于：终端模式下输出更纯粹，不会有自动补全、光标控制这些交互元素的干扰；而IDE模式下则可以顺手查看代码上下文，两者各有优势。我的建议是日常开发在IDE里用，遇到复杂需求或者重构类任务，专门开一个终端窗口跑superpowers工作流，这样互不干扰。

3. 核心工作流实操：用一次完整开发演示讲透每一步

3.1 场景设定：给一个React项目增加CSV导出功能

理论知识再多，不如走一遍实际流程。我模拟一个非常典型的开发场景：假设我手上有一个 React + TypeScript 的报表项目，现在新的需求是，要把前端表格里的数据导出成 CSV 文件。这个需求听起来简单，但坑其实不少：中文表头乱码问题、大数据量内存溢出问题、字段中包含逗号或换行的转义问题。如果直接让AI写代码，大概率只能覆盖“能导出”这个最低标准。

我决定用 superpowers 的完整工作流来走一遍，看看它能不能帮我把这些隐藏风险都考虑到。整个过程我会分为“需求梳理、方案设计、计划制定、代码执行、结果复盘”五个阶段，每个阶段都会调用不同的技能。

3.2 第一步：调用 brainstorming 技能，把模糊需求变清晰

我启动 Codex 后，输入：

请调用 brainstorming 技能。我的场景是：React报表需要增加一个导出CSV的功能，数据在前端表格中，表头是中文，数据量可能有几万条。

注意，我并没有直接说“给我写个导出函数”，而是让AI先进入需求分析模式。Codex 读取了 brainstorming 技能文件后，并没有立刻输出代码，而是连续向我提了几个关键问题，比如：用户是点击按钮触发导出还是自动导出？表格组件本身有没有内置的导出能力？数据是否全部在内存中，还是需要异步分批拉取？表头与字段名的映射关系是什么？

这些问题问完，我已经能感受到这套工作流的用处了，它逼着我把需求边界想清楚，避免“我以为AI懂了”的误会。对齐完需求后，AI给出了两个方案：方案A是在前端直接用Blob方式生成CSV并触发下载，实现简单，适合万级以下数据量；方案B是用papaparse这类库处理序列化，配合分页拉取，适合超大数据的场景。

最终它推荐了方案A，同时明确写出了风险点：中文表头会受Excel默认编码影响乱码，需要在导出时加入\ufeffBOM 头；字段值里如果含逗号、换行符和双引号，必须做标准转义。这些细节如果直接问“怎么写导出CSV”，很多模型是不会主动给出的。

3.3 第二步：调用 writing-plans 技能，把方案变成可执行计划

需求对齐、方案选定之后，接着调用第二个核心技能：

请调用 writing-plans 技能，基于刚才确定的方案A，为“CSV导出功能”制定一份实施计划。

这一步非常关键，因为我发现AI很快就在项目里的plans/目录下生成了一个计划文件，内容结构非常像真实开发中的技术方案文档。它包含背景描述、技术选型、改动范围、逐步任务列表、每个任务的验收标准，甚至还有风险预案和回滚策略。

比如它把任务拆分成了：新增utils/exportCsv.ts工具函数、编写表头映射配置、在表格组件中新增导出按钮及事件绑定、增加 BOM 与字段转义处理、针对空数据和大数据量的边界测试。每个任务后面都标注了验收标准，比如“当表格数据超过三万条时，页面渲染不应出现卡死”。有了这样一份计划，后续的编码工作就变成了“照着单子干活”，AI不会遗漏步骤，你也能在每一步之间做审查。

3.4 第三步：调用 executing-plans 技能，逐项实现并验证

计划落地后，进入执行阶段：

请调用 executing-plans 技能，开始执行当前计划，每次完成一个任务后先暂停，等我的确认反馈。

这是整个工作流里最让我“放心”的部分。AI 不会一口气把代码全丢给我，而是每完成一个任务就停下来，说明它做了什么、验证了什么、还有哪些需要注意的地方。比如它写完exportCsv.ts后，会主动展示测试样例，验证字段转义逻辑：“某单元格内容是 你好,世界" 且带换行，导出时是否正确用双引号包裹并转义内部引号”。

我在中间挑过一处毛病：BOM头的添加位置不对。AI 立刻承认错误并修复，然后重新执行了上一个任务的验收。这种“边执行边确认”的模式，让问题在最早的时间暴露，而不是等到代码全写完再集中调试。

3.5 第四步：调用 review 技能做代码审查与收尾

代码全部执行完毕，工作流还不会结束，AI 会建议调用 review 技能对改动做一次全面审查。审查内容包括：是否有没被计划覆盖到的边缘情况、是否符合项目的代码风格、是否存在性能隐患、有没有引入多余依赖。

在这次demo中，review 阶段还真发现了一个小问题：导出按钮没有加 loading 状态，如果用户连续点击多次，会生成多个下载任务，导致浏览器异常。这一点在我原本的需求里完全没考虑到，是由 review 技能主动补上的。到这里才算一次完整的闭环。整个流程走完以后，我最大的感受是：AI不再是一个“快问快答”的工具，而是一个有章法的结对程序员。

4. 把 superpowers 的威力发挥到极限：自定义技能与团队协作进阶

4.1 通过 notes 和 plans 构建AI的“项目记忆”

superpowers 最容易被低估的功能，是它的长期记忆机制。传统的AI对话一开始就是一张白纸，你每次都不得不把项目背景从头讲一遍。而 superpowers 会引导你在notes/目录下持续维护项目笔记，包括技术决策记录、遗留问题、命名约定、部署信息等。

实际操作上，每当AI完成一个重要任务，它会自动更新笔记，把本次的改动概要、关键决策和需要注意的坑写进去。下一次你打开新会话启动 Codex，它会主动读取这些笔记，然后告诉你“当前项目状态已经了解，需要处理什么？”这就是“AI记得住项目上下文”的效果。

我在连续几天处理同一个项目时，明显感受到沟通成本在下降，群里的朋友也有同样的反馈。把工程经验沉淀成文本、再由AI在需要时取用，这远比停靠在单次对话的多轮上下文里要可靠得多。因为对话会关闭，而文件不会丢。

4.2 自定义技能：把一个团队的开发规范“教”给AI

superpowers 的强大之处在于它不是封闭的，任何人都可以添加自定义技能。我举一个真实场景：我们团队在开发后端Java服务时，要求所有对外接口必须维护一份 OpenAPI 文档，并且响应结构要统一。以前这个约束得靠人肉提醒，新人经常忘。后来我把这条规范写成了一个自定义skill，放在skills/java-service-guard/目录下，内容包括接口定义时的检查清单、OpenAPI注释格式示例、常见的响应结构模板。

然后在开发时只需要说“先调用 java-service-guard 技能，再开始写这个接口”，AI就会按着规范输出，并且主动提醒我是否漏掉了文档。一个几十行的Markdown文件，就把一条团队约定固化成了AI的行为准则，效果可能比一次代码评审还好。这个思路可以用在各行各业，关键是把你重复强调的东西结构化。

自定义技能的模板也不复杂，本质上就是一个带固定格式的 Markdown 文件，开头用 YAML frontmatter 写明技能名称、描述、适用场景，正文按照“步骤、规则、示例”的层次来写。文件里还可以引用项目中现有的脚本，让AI在对应节点去执行。

4.3 团队共享、版本管理与 Codex 深度集成

如果你在团队里推广 superpowers，有一个天然的优势：它就是一个Git仓库，你完全可以把自定义技能和团队规范以PR的形式统一维护。每个成员 clone 同一套技能库，AI的行为范式就是一致的，这比口头约定靠谱得多。

配合 Codex 这类工具时，还可以启用自动化模式。比如让AI在接受任务后自动创建todo.md、每次提交时自动生成规范的 commit message、在关键任务完成后自动跑一遍测试。这些都可以通过写脚本挂在技能文件的执行步骤里，实现一定程度的自动化流水线。

我个人的建议是，最开始不要把流程搞得过于复杂，先把核心循环跑顺，确认 AI 的输出质量显著提升之后，再逐步添加自定义技能和自动化逻辑。否则，如果你的技能文件写得比项目代码还多，那就本末倒置了。

5. 常见问题与排查技巧实录：这些坑我都帮你踩过了

5.1 技能没生效、读不到仓库、执行跳步，怎么办

我在实际使用和帮朋友排查的过程中，整理了一批最高频的问题，直接做成一个速查表，方便你对号入座。

5.2 我把这些坑趟平之后，总结出的几条经验

第一，不要一个技能调用到底。很多人以为调用了一个技能就能解决所有事情，其实 superpowers 的设计哲学是“一个阶段一个技能”，需求分析、计划、执行、审查应该分开。混在一起，AI的推理路径会模糊，效果大打折扣。我自己一开始就是因为贪快，跳过planning阶段直接执行，结果代码质量和直接问AI没啥区别。

第二，善于要求AI“先读文件，再回答问题”。在对话开始的时候，可以说：“请先读取项目的notes/内容和plans/目录，然后告诉我当前状态。”这一句话能显著减少AI的猜测性回答，它会把文件里的真实信息作为回答的基础，而不是凭空想象。这很像真实开发里“先看代码再说话”的习惯。

第三，编写自定义技能时，尽量给出“反例”。AI对正例的学习能力很强，但同样容易出现教条式理解，所以我会在技能文档里专门列一段：哪些做法不要做。比如“不要在服务层直接返回数据库实体”“不要在循环里执行查询”。写明反例之后，AI遵守边界的效果要好很多。

第四，不要忽视 review 技能的威力。我一开始觉得已经有计划了，还有必要做专门审查吗？实际跑下来发现，每次 review 几乎都能抓住一到两个计划阶段遗漏的边界问题。如果你赶时间，至少也要让 AI 在完成后问自己一句“是否还有风险没覆盖”，这是一个成本极低、收益很高的习惯。

5.3 关于如何选择模型版本，给你一个参考

很多朋友问我：superpowers 是不是只有用最高端的模型才有意义？我的理解是，它本身是一个工作流框架，模型的智商决定了下限，而流程的规范程度决定了上限。用较弱模型时，你会发现它对长指令的遵循能力确实会打折，在这种情况下，我会把技能文件里的步骤拆得更细、约束写得更死，让每一步都简单到模型不容易犯错。等换更强力的模型时，再恢复默认的简洁指令，体验会更好。

我在实际开发里试过几种配置，给一个参考建议：日常小需求用非推理模型加完整流程；复杂重构或者新功能开发，尽量启用推理模型。原因很简单，推理模型在多步规划、代码审查阶段，逻辑深度明显更好，它更不容易放过那些需要跨文件理解的隐藏依赖。

这套工具我现在基本每天都用，已经习惯了让AI先分析再动手的节奏。虽然它解决不了所有问题，过程也需要人在关键节点把把关，但至少让我在跟AI协作时多了一分掌控感。如果你手里正好有 Codex 或者类似工具，不妨按这篇文章的思路跑通一次完整流程，再根据自己的习惯慢慢调整。最后再分享一个小技巧：给AI下指令的时候，先别急着加各种细节，只告诉它目标，让它自己通过技能引导来追问你。你会发现，很多时候它比你自己更清楚下一步该问什么。