企业官网建设流程全解析

1. 从“superpowers”说起：这套技能框架到底在解决什么问题

第一次看到superpowers这个词，是在一个做 AI 辅助开发的群里。有人甩了张截图，终端里敲了一行命令，然后 Claude Code 就像被“开了光”一样，开始按一套固定流程拆需求、写方案、跑测试、做复盘。当时我的第一反应是：这不就是把软件工程那套方法论，硬塞进 AI 编程工具里吗？后来自己上手折腾了两周，才发现事情没那么简单。

superpowers本质上是一套agentic skills framework，翻译过来叫“智能体技能框架”。它不绑定某一个具体的 AI 编程工具，而是通过一套结构化的技能定义，让 Claude Code、Codex CLI 这类命令行 AI 助手，能够按照预设的软件工程方法论去工作。你可以把它理解成给 AI 装了一本“操作手册”——不是教它写代码，而是教它怎么像一个有经验的工程师那样思考和组织工作。

这套东西解决的核心痛点很明确：默认状态下的 AI 编程助手，你问一句它答一句，上下文一长就忘，任务一复杂就乱。你让它改个 bug，它可能顺手把旁边的功能重构了；你让它加个接口，它可能连测试都不写。superpowers通过技能（skills）的形式，把“需求分析、方案设计、编码实现、测试验证、代码审查”这些环节固化下来，让 AI 在每一步都有明确的输入、输出和质量标准。

适合谁来参考？三类人最值得花时间研究。第一类是日常用 Claude Code 或 Codex CLI 写代码的开发者，尤其是那种已经过了“哇 AI 能写代码”的新鲜期、开始被 AI 的不可控性折磨的人。第二类是技术团队负责人，想给团队定一套 AI 辅助开发的规范，但又不想自己从零造轮子。第三类是对 agentic 工作流感兴趣的技术爱好者，想看看当前开源社区是怎么把软件工程方法论“翻译”成 AI 能执行的技能定义的。

我自己的使用场景比较典型：一个中等规模的 TypeScript 项目，后端 Node.js，前端 React，用 Claude Code 做日常开发。没上superpowers之前，我每次都要在 prompt 里重复交代“先写测试”“别动无关文件”“改完跑一遍 lint”，说多了自己都烦。上了之后，这些约束变成了技能定义的一部分，AI 自己会按流程走，我只需要在关键节点做决策。这个体验差异，后面会详细展开。

2. 核心设计思路拆解：为什么是“技能”而不是“提示词”

2.1 技能框架与普通提示词的本质区别

很多人第一次接触superpowers，会把它当成一套“高级提示词模板”。这个理解不能说错，但不够准确。普通提示词是你每次对话时临时写给 AI 的指令，用完就散；而superpowers里的技能是持久化、可组合、可版本管理的资产。

我打个比方。普通提示词像是你每次做饭前口头告诉厨师“少放盐、多放葱”；技能框架则是你给厨师一本菜谱，菜谱里写清楚了每道菜的标准流程、用料比例、火候控制，厨师照着做就行，而且这本菜谱还能不断修订、增补新菜。

具体到技术实现上，一个 skill 通常包含几个部分：触发条件（什么情况下启用这个技能）、输入要求（需要哪些上下文信息）、执行步骤（按什么顺序做什么事）、输出规范（产出物长什么样）、质量检查点（怎么判断做完了、做对了）。这套结构让 AI 的行为从“随机应变”变成“有章可循”。

2.2 为什么选择 Claude Code 和 Codex CLI 作为主要载体

superpowers目前最主要的两个落地载体是 Claude Code 和 Codex CLI。这个选择背后有很实际的考量。

Claude Code 的优势在于它的工具调用能力和上下文管理。它原生支持读写文件、执行命令、搜索代码库，这些能力是技能框架能跑起来的基础。你让一个只能聊天的 AI 去执行“先跑测试再改代码”的流程，它做不到，因为它没有执行测试的工具。Claude Code 有，所以技能定义里的“执行步骤”才能真正落地。

Codex CLI 则是另一个路数。它更轻量，更偏向命令行原生体验，适合那些不想离开终端、喜欢用管道和脚本串联工作流的开发者。superpowers在 Codex CLI 上的实现，更多是利用它的非交互式执行能力，把技能定义成可以在 CI/CD 流水线里调用的命令。

我两个都试过。Claude Code 上的体验更“重”，适合复杂的多步骤任务；Codex CLI 上的体验更“轻”，适合快速、重复性的检查类任务。选哪个，取决于你的工作习惯和任务类型。

2.3 软件工程方法论的“技能化”翻译

superpowers最核心的价值，在于它把软件工程里那些“老生常谈”的方法论，翻译成了 AI 能执行的技能定义。这个翻译过程不是简单的文字转换，而是需要解决几个关键问题。

第一个问题是粒度。方法论说“要做代码审查”，但代码审查具体查什么？superpowers会把它拆成：检查命名规范、检查错误处理、检查边界条件、检查测试覆盖、检查文档更新。每个检查项都有明确的判断标准，AI 才能执行。

第二个问题是顺序依赖。方法论说“先设计后编码”，但 AI 怎么知道设计做完了？superpowers通过产出物检查来解决：设计阶段的产出是一份设计文档，文档里必须包含接口定义、数据流图、异常处理策略，缺一项就不算完成，不能进入编码阶段。

第三个问题是回退机制。如果编码阶段发现设计有问题怎么办？superpowers允许技能定义里包含“回退到上一阶段”的指令，而不是硬着头皮往下走。这个设计很关键，因为 AI 很容易“将错就错”，有了回退机制才能保证质量。

2.4 技能组合与工作流编排

单个技能解决单个问题，但真实开发任务是多个问题的组合。superpowers支持技能的组合调用，形成一个完整的工作流。

比如一个“实现新功能”的工作流，可能包含这些技能：需求澄清技能、方案设计技能、测试先行技能、编码实现技能、代码审查技能、文档更新技能。每个技能有自己的触发条件和完成标准，前一个技能完成后自动触发下一个。

这个编排能力是superpowers区别于零散提示词的关键。它让 AI 的工作从“单点响应”变成“流程执行”，从“你问我答”变成“任务驱动”。

3. 安装与配置实操：从零把环境跑起来

3.1 Claude Code 的安装与基础配置

先说 Claude Code 的安装。不同系统下的步骤略有差异，我分别说一下我实际操作过的路径。

在 macOS 或 Linux 上，最直接的方式是通过 npm 全局安装。前提是你本地有 Node.js 环境，建议版本在 18 以上。命令很简单：

npm install -g @anthropic-ai/claude-code

装完之后，在终端输入claude就能启动。第一次启动会引导你做认证配置，按提示走就行。

Windows 上的情况稍微复杂一点。原生 Windows 终端对某些命令行工具的支持不够好，我实测下来最稳的方案是用 WSL2。在 WSL2 的 Ubuntu 环境里，安装步骤和 Linux 完全一致。如果你非要在 PowerShell 里跑，也不是不行，但可能会遇到路径分隔符、权限之类的小问题，排查起来费时间。

Ubuntu 上还有一个坑：某些版本的 npm 默认安装路径不在 PATH 里。装完之后如果提示command not found，检查一下~/.npm-global/bin或者/usr/local/bin是否在 PATH 中。这个不是 Claude Code 的问题，是 npm 配置的问题，但很多人第一次装会卡在这里。

VSCode 里用 Claude Code 的话，推荐装官方插件，然后在 VSCode 的集成终端里启动。这样文件路径和编辑器上下文能自动同步，体验比在外部终端好很多。

3.2 Codex CLI 的安装与常见报错处理

Codex CLI 的安装方式取决于你用的版本。开源社区维护的 Codex CLI 通常通过 npm 或直接下载二进制文件安装。npm 方式：

npm install -g @openai/codex

装完之后输入codex验证。如果报错unable to locate the codex cli binary or required runtime components，大概率是两个原因：一是 npm 全局 bin 目录没在 PATH 里，二是缺少运行时依赖（比如某些系统库）。

排查思路是这样的：先which codex看看能不能找到可执行文件。找不到的话，npm config get prefix看看全局安装路径，然后手动把这个路径加到 PATH。找得到但运行报错的话，用ldd（Linux）或otool -L（macOS）检查动态库依赖，缺什么补什么。

Windows 上装 Codex CLI，同样推荐 WSL2。如果坚持用原生 Windows，注意把终端换成 Windows Terminal，并且确保 PowerShell 的执行策略允许运行脚本。codex cli如何更新这个问题也常被问到，npm 安装的话npm update -g @openai/codex就行，二进制安装的话重新下载覆盖。

3.3 superpowers 的安装与技能目录结构

superpowers本身的安装，取决于你用的是哪个发行版。社区里比较活跃的几个版本，安装方式大同小异：要么是通过包管理器装，要么是手动把技能定义文件放到指定目录。

手动安装的话，核心是搞清楚技能目录的位置。Claude Code 默认会从几个位置加载技能：项目根目录下的.claude/skills/、用户主目录下的.claude/skills/、以及通过环境变量指定的额外路径。superpowers的技能文件通常是一堆 Markdown 或 YAML 文件，每个文件定义一个技能。

我建议的做法是：项目级技能放项目目录，通用技能放用户目录。项目级的技能可以跟着代码库一起版本管理，团队共享；用户级的技能是你个人的工作习惯，不跟项目走。这个分层策略后面会详细说。

安装完成后，验证是否生效的方法很简单：启动 Claude Code，输入一个触发技能的关键词，看它是否按技能定义的流程响应。比如你装了一个“测试先行”技能，输入“帮我加个函数”，它应该先问你测试怎么写，而不是直接给实现。

3.4 验证安装与最小可用示例

装完不验证，等于没装。我习惯用一个最小示例来确认整套东西跑通了。

找一个空目录，初始化一个最简单的项目，比如一个只有index.js的 Node 项目。然后启动 Claude Code，输入：“用 superpowers 的流程帮我给这个项目加一个加法函数”。

如果技能框架生效，你应该看到 AI 不是直接写代码，而是先做需求澄清（问你这个函数要不要处理非数字输入）、再写测试、再实现、最后跑测试验证。整个过程有明确的阶段划分，而不是一口气输出一堆代码。

这个最小示例能帮你确认三件事：技能是否被正确加载、工作流是否按预期编排、工具调用是否正常。任何一环出问题，都能在这个简单场景里暴露出来，比在复杂项目里排查容易得多。

4. 核心技能解析与实操要点

4.1 需求澄清技能：把模糊需求变成可执行任务

需求澄清是superpowers工作流的第一个环节，也是最容易被忽视的环节。很多人用 AI 写代码，上来就说“帮我做个登录功能”，然后 AI 给了一堆代码，结果发现跟自己想要的完全不一样。问题不在 AI，在需求本身就没说清楚。

superpowers的需求澄清技能，核心是让 AI主动提问而不是被动执行。它会从几个维度去澄清：功能边界（做什么、不做什么）、输入输出（接收什么、产出什么）、异常情况（出错怎么办）、性能要求（响应时间、并发量）、兼容性要求（跟现有系统怎么对接）。

我实操下来的感受是，这个环节能省掉后面大量的返工。有一次我让 AI 做一个“数据导出”功能，它先问了我五个问题：导出格式是 CSV 还是 JSON、数据量大概多大、要不要支持筛选、导出是同步还是异步、失败要不要重试。这五个问题问完，实现方案基本就清晰了，后面写代码一气呵成。

注意：需求澄清技能的关键是“问对问题”。如果 AI 问的问题太泛（比如“你有什么要求”），说明技能定义的质量不够，需要补充更具体的提问模板。

4.2 方案设计技能：先画图纸再动工

需求澄清完，进入方案设计。这个技能要求 AI 产出一份设计文档，而不是直接写代码。设计文档的内容包括：模块划分、接口定义、数据结构、关键流程、异常处理策略、测试策略。

为什么非要先设计？因为 AI 的上下文是有限的，直接写代码容易“只见树木不见森林”。先设计相当于先画一张地图，后面写代码时随时可以对照地图，不容易跑偏。

我自己的经验是，方案设计阶段最值得花时间的是接口定义。把函数签名、参数类型、返回值类型定清楚，后面实现就是填空。如果接口没定好，实现阶段改来改去，测试也得跟着改，效率反而低。

设计文档的格式不用太正式，Markdown 就行。关键是内容要具体，不能写“设计一个合理的接口”，而要写“接口接收 userId 和 dateRange，返回一个包含 records 数组和 total 计数的对象，records 里每条记录包含 id、timestamp、amount 三个字段”。

4.3 测试先行技能：让 AI 自己给自己出考卷

测试先行是superpowers里我最喜欢的技能。它的逻辑很简单：写实现之前先写测试，测试通过了实现才算完成。

这个技能的价值在于，它给 AI 提供了一个自我验证的闭环。没有测试的时候，AI 写完代码说“完成了”，你也不知道对不对，得自己跑一遍。有了测试，AI 写完代码自己跑测试，跑不过就继续改，改到跑过为止。你拿到的是一个已经验证过的实现，而不是一个“看起来对”的实现。

实操中要注意的是测试的粒度。测试太粗，覆盖不到边界情况；测试太细，维护成本高。我的经验是，每个函数至少覆盖：正常输入、边界输入（空值、极值）、异常输入（类型错误、越界）。这三类覆盖到了，基本就够用了。

还有一个坑：AI 写的测试有时候会“迎合”实现，就是实现怎么写它就怎么测，失去了测试的意义。避免这个问题的方法是，在技能定义里明确要求“测试用例必须基于需求文档，而不是基于实现代码”。这样 AI 写测试时会参考需求，而不是参考自己刚写的代码。

4.4 代码审查技能：AI 审 AI 的代码

代码审查技能是让 AI 用“审查者”的视角重新看一遍自己写的代码。这个环节能发现很多实现阶段忽略的问题：命名不一致、重复代码、错误处理缺失、注释过期、性能隐患。

我实测下来，AI 审查自己代码的效果，比审查别人代码要差一些，因为它有“作者偏见”。但即便如此，还是能抓到不少问题。尤其是那些“写的时候觉得没问题、回头看才发现不对”的地方，审查环节经常能发现。

提高审查效果的一个技巧是：让审查技能使用不同的提示词模板。实现阶段用的是“实现者”视角，关注“怎么把功能做出来”；审查阶段用的是“审查者”视角，关注“这样做有没有问题”。视角切换了，发现问题的概率就高了。

审查技能的产出通常是一份问题清单，每个问题标注严重程度（阻塞、重要、建议）和修改建议。AI 根据这份清单决定是直接修改还是回退到设计阶段。这个决策逻辑也要在技能定义里写清楚，否则 AI 容易“自作主张”。

4.5 技能组合与工作流编排实战

单个技能用熟了之后，就可以玩组合了。superpowers的工作流编排，本质上是把多个技能串成一条流水线。

我常用的一个工作流是这样的：需求澄清 → 方案设计 → 测试先行 → 编码实现 → 代码审查 → 文档更新。每个环节的产出物是下一个环节的输入，任何一个环节不通过就回退。

这个工作流跑一个中等复杂度的功能（比如一个带分页和筛选的列表接口），大概需要 15 到 20 轮对话。听起来不少，但考虑到它把需求、设计、实现、测试、审查全包了，而且每步都有产出物，实际效率比我自己从头写要高。

编排的时候要注意技能之间的衔接。比如需求澄清的产出是一份需求文档，方案设计技能要能读取这份文档作为输入。这要求技能定义里明确写清楚“输入来源”和“输出格式”，否则 AI 在切换技能时会丢失上下文。

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

5.1 安装类问题速查

这张表是我踩坑之后整理的，基本覆盖了 90% 的安装问题。其中“技能不生效”是最常见的，多数情况是技能文件放错了目录，或者文件格式不对（比如 YAML 缩进错了）。

5.2 技能加载失败的排查思路

技能加载失败的表现是：AI 不按技能定义的流程走，还是老样子一问一答。排查步骤分三层。

第一层，确认技能文件存在且格式正确。Markdown 文件检查标题层级，YAML 文件检查缩进和语法。我遇到过好几次是 YAML 里用了 Tab 而不是空格，导致解析失败。

第二层，确认技能目录被正确加载。Claude Code 启动时会在日志里输出加载了哪些技能，如果日志里没有你的技能，说明目录配置有问题。检查环境变量和配置文件里的路径设置。

第三层，确认技能触发条件匹配。有些技能定义了特定的触发关键词，如果你的输入不包含这些关键词，技能不会被激活。这个设计是为了避免技能“过度触发”，但有时候也会导致“该触发的时候没触发”。解决办法是在技能定义里放宽触发条件，或者手动指定使用某个技能。

5.3 工作流中断与上下文丢失的处理

工作流跑到一半中断，是另一个高频问题。表现是 AI 突然“忘了”之前的设计，开始自由发挥。原因通常是上下文窗口满了，早期的对话被截断了。

处理这个问题有两个思路。一是控制单个技能的上下文消耗，把大段的代码和文档放到外部文件里，技能定义里只引用文件路径，不把内容全塞进对话。二是在关键节点做检查点，把当前状态（需求文档、设计文档、测试结果）保存到文件里，中断后可以从检查点恢复。

我自己的做法是，每个技能完成后，让 AI 把产出物写入一个固定的文件，比如.superpowers/state/current-design.md。下一个技能启动时先读这个文件，而不是依赖对话历史。这样即使对话被截断，工作流也能继续。

5.4 技能冲突与优先级问题

装了多个技能之后，可能会遇到技能冲突：两个技能都想处理同一个输入，或者一个技能的产出被另一个技能覆盖。

解决冲突的核心是优先级定义。在技能定义里可以指定优先级数值，数值高的先执行。或者用更明确的触发条件，让每个技能只在自己擅长的场景下激活。

我遇到过一个典型冲突：一个“快速修复”技能和一个“完整流程”技能，都响应“修 bug”这个输入。快速修复直接改代码，完整流程走需求澄清到代码审查。两个同时触发就乱了。解决办法是给它们不同的触发词，比如“快速修一下”触发前者，“按流程修”触发后者。

5.5 性能优化与资源占用控制

superpowers跑起来之后，资源占用主要来自两个方面：AI 的推理调用和本地工具的执行。推理调用是主要开销，尤其是工作流长的时候，一轮下来可能几十次调用。

优化思路有几个。一是合并技能，把一些简单的、经常连续出现的技能合并成一个，减少切换开销。二是缓存中间结果，需求文档、设计文档这些产出物缓存起来，避免重复生成。三是按需加载技能，不是所有技能都需要常驻，用不到的技能不加载，减少启动时的解析开销。

实测下来，一个中等复杂度的工作流，优化前跑一轮大概 3 到 5 分钟，优化后能压到 2 分钟左右。提升不算巨大，但日积月累下来差别明显。

6. 进阶玩法：把 superpowers 接入现有开发流程

6.1 与版本控制的结合

superpowers的产出物（需求文档、设计文档、测试文件、实现代码）都应该纳入版本控制。我的做法是，每个工作流跑完，让 AI 自动生成一个 commit，commit message 里包含工作流的阶段信息。

这样做的好处是，工作流的历史可追溯。哪天发现某个功能的实现有问题，可以顺着 commit 历史往回查，看是需求阶段就错了，还是设计阶段跑偏了，还是实现阶段引入了 bug。

技能定义文件本身也应该版本控制。团队共享的技能放在项目仓库里，个人技能放在 dotfiles 仓库里。技能更新了，团队成员拉一下代码就能同步。

6.2 在 CI/CD 流水线中调用技能

Codex CLI 的非交互式执行能力，让它很适合在 CI/CD 里跑。比如在 PR 提交时，自动触发一个“代码审查”技能，把审查结果作为评论贴到 PR 上。

这个玩法的关键是技能的输出格式要机器可读。审查结果不能是一段自然语言，而应该是结构化的 JSON 或 Markdown 表格，方便 CI 系统解析和展示。

我试过在 GitHub Actions 里跑一个简化版的审查技能，效果还不错。它不能替代人工审查，但能抓到一些明显的规范问题，减少人工审查的负担。

6.3 团队协作中的技能共享与定制

团队用superpowers，最大的价值是统一工作标准。大家用同一套技能定义，产出物的格式和质量标准就一致了，代码审查和交接的成本都降低了。

但统一不等于一刀切。不同项目、不同技术栈，需要的技能可能不一样。我的建议是：基础技能团队共享，项目技能项目自定，个人技能个人自定。三层结构，既保证了一致性，又保留了灵活性。

技能共享的载体可以是 Git 仓库，也可以是内部的包管理服务。关键是版本管理要做好，技能更新了要通知到使用的人，避免有人用旧版本踩坑。

6.4 技能定义的迭代与维护

技能定义不是写完就完了，需要持续迭代。迭代的驱动力来自两个方面：一是使用中发现的不足，比如某个技能总是漏掉某个检查项；二是工作流程的变化，比如团队引入了新的测试框架，测试先行技能需要更新。

我自己的迭代节奏是：每跑完一个完整工作流，花五分钟回顾一下，哪个环节卡住了、哪个产出物质量不够、哪个技能触发不顺畅。攒够几个问题，就集中改一次技能定义。

技能定义的修改也要走版本控制，每次修改记录改了什么、为什么改。这样过一段时间回头看，能清楚看到工作流的演进过程。

7. 我踩过的坑与实操心得

7.1 不要一上来就追求全自动

我刚开始用superpowers的时候，恨不得把所有环节都自动化，从需求到部署一条龙。结果发现，全自动的代价是失控。AI 在某个环节做了个错误决策，后面全跟着错，等你发现的时候已经跑偏很远了。

后来我改成半自动：关键决策点（需求确认、设计评审、审查结果处理）由我手动确认，其他环节自动跑。这样既保留了效率，又保证了方向可控。实测下来，半自动的总体效率反而比全自动高，因为返工少了。

7.2 技能定义要“具体到能执行”

写技能定义最容易犯的错误是太抽象。比如写“检查代码质量”，AI 不知道检查什么。要写成“检查函数命名是否符合 camelCase、检查每个函数是否有错误处理、检查是否有未使用的变量”，这样 AI 才能执行。

我的经验是，技能定义里的每一条指令，都要能回答“AI 具体做什么动作”。如果一条指令需要 AI“理解”或“判断”，那就要补充判断标准。标准越具体，执行越稳定。

7.3 上下文管理比技能定义更重要

用了一段时间之后我发现，工作流跑得顺不顺，很大程度上取决于上下文管理，而不是技能定义本身。技能定义得再好，上下文丢了，AI 还是抓瞎。

所以我现在花在上下文管理上的时间，比花在技能定义上的还多。具体做法包括：产出物落盘、关键信息摘要、对话历史定期清理、外部文件引用代替内容内联。这些做法看起来琐碎，但效果立竿见影。

7.4 给 AI 留“说不”的空间

最后一个心得，可能有点反直觉：不要逼 AI 在所有情况下都按流程走。有些任务就是很简单，走完整流程反而浪费时间。有些任务就是很模糊，强行澄清也澄清不出什么。

我在技能定义里加了一个“跳过”机制：如果 AI 判断当前任务不适合走完整流程，可以提议跳过某些环节，由我确认。这个机制让工作流更灵活，不会为了流程而流程。

superpowers这套东西，说到底是个工具。工具的价值在于用的人怎么用。我见过有人把它当银弹，装完就指望 AI 全自动写代码；也见过有人把它当脚手架，根据自己的习惯裁剪改造。后者才是正确的打开方式。技能框架提供的是结构和约束，真正的效率提升来自于你在这个结构里找到适合自己的节奏。