企业官网建设流程全解析

1. 从“superpowers”说起：这套 agentic skills framework 到底在解决什么问题

第一次看到 “superpowers” 这个词，是在几个做 AI 编程工具链的群里。有人甩出一句“装完 superpowers 之后，Claude Code 才算真正能干活了”，底下立刻一堆人追问怎么装、支不支持 Codex CLI、能不能接本地模型。我当时的反应是：又一个包装概念？但把它的设计思路捋了一遍之后，我改主意了——这东西确实戳中了当前 AI 编程工具最尴尬的一个痛点。

先说清楚它是什么。superpowers 本质上是一套 agentic skills framework，也就是“智能体技能框架”。它不绑定某一个具体的模型或 CLI，而是定义了一套让 AI 编程助手（比如 Claude Code、Codex CLI 这类终端里的 agent）能够调用“技能”的规范。你可以把它理解成给 AI 装了一本《员工手册》加一套《标准作业流程》：以前你让 AI 改个 bug，它可能东一榔头西一棒子；现在它知道先读需求、再定位文件、再写测试、再改代码、最后跑验证，每一步都是一个可复用的 skill。

它解决的问题很具体。用过 Claude Code 或者 Codex CLI 的人都有体会：这些工具单轮对话能力很强，但一旦任务跨多个文件、需要多轮迭代，就容易“失忆”或者“跑偏”。你让它重构一个模块，它改到一半忘了最初的约束；你让它按 TDD 流程走，它写着写着就把测试跳过了。superpowers 的价值就在于把这些“工程纪律”固化成了框架层面的技能，让 agent 在长任务里保持行为一致。

适合谁来参考？三类人最该看：一是已经在用 Claude Code、Codex CLI 做日常开发，但觉得“还不够顺手”的工程师；二是想把这套方法论迁移到自己团队内部工具链的技术负责人；三是刚接触 agentic 编程、想搞清楚“AI 编程到底怎么落地”的入门者。哪怕你暂时不装，理解它的设计逻辑，对你用好任何一个 AI 编程工具都有帮助。

我下面会从设计思路、核心机制、实操落地、踩坑排查四个层面把它拆开讲，尽量做到你看完能自己动手复现一套。

2. 核心设计思路拆解：为什么是“技能框架”而不是“又一个插件”

2.1 从“提示词工程”到“技能工程”的范式转移

早期大家用 AI 编程，靠的是把提示词写得又长又细。我见过有人维护一个两千字的 system prompt，里面塞满了“你要先思考再回答”“你要写单元测试”“你不要删掉原有注释”。这种做法的天花板很低：提示词越长，模型越容易忽略中间部分，而且换个项目就得重写一遍。

superpowers 的思路是把这些约束从“提示词”里抽出来，变成结构化的技能定义。一个 skill 通常包含几个要素：触发条件（什么时候用这个技能）、执行步骤（具体做什么）、输入输出约定（需要哪些上下文、产出什么）、验证标准（怎么算做完了）。这跟传统软件工程里的“函数”很像——有明确的入参、出参和职责边界。

提示：理解这一点很关键。superpowers 不是让模型变聪明，而是让模型的行为变得可预测、可复用。它的假设是“模型能力已经够用，缺的是流程约束”。

为什么这个转移重要？因为提示词是“一次性”的，技能是“可积累”的。你今天写了一个“安全重构”的 skill，明天写了一个“接口兼容性检查”的 skill，这些技能可以组合、可以版本管理、可以跨项目复用。这才是工程化的样子。

2.2 与 Claude Code、Codex CLI 的关系定位

很多人搞混的一点是：superpowers 和 Claude Code、Codex CLI 不是竞争关系，而是上下层关系。Claude Code 和 Codex CLI 是“执行器”，负责跟模型通信、读写文件、跑终端命令；superpowers 是“调度层”，负责决定什么时候该调用哪个技能、按什么顺序调用。

打个比方：Claude Code 像是一个手脚麻利的实习生，能听懂话、能动手；superpowers 像是给这个实习生配的 SOP 手册和 checklist。实习生再聪明，没有 SOP 也会漏步骤；有了 SOP，哪怕换个实习生，产出质量也稳定。

这也解释了为什么 superpowers 要强调“framework”而不是“tool”。它不提供模型，不提供 CLI，它提供的是一套让 agent 行为标准化的中间层。你可以在 Claude Code 里用，也可以在 Codex CLI 里用，甚至理论上可以接到自己写的 agent 上。

2.3 方案选型背后的三个取舍

设计这样一套框架，绕不开三个取舍，我结合自己的理解说一下。

第一个取舍：技能粒度多细合适？太粗，一个 skill 干十件事，复用性差；太细，一个 skill 只干一件事，调度开销大。superpowers 的做法是围绕“开发活动”来切分，比如“需求澄清”“代码定位”“测试编写”“重构执行”“结果验证”，每个 skill 对应一个明确的开发阶段。这个粒度我觉得是合理的，因为它跟人做事的节奏对得上。

第二个取舍：技能是声明式还是命令式？声明式只描述“要达成什么”，命令式描述“怎么做”。superpowers 偏向声明式加少量命令式约束。原因是模型本身有推理能力，你给它太多命令式步骤反而限制它发挥；但关键节点（比如“改代码前必须先跑测试”）又必须命令式锁死，防止它偷懒。

第三个取舍：要不要绑定特定模型？不绑定。这是它比很多同类方案聪明的地方。因为模型迭代太快了，今天 Claude 最强，明天可能是别的。框架层保持模型无关，才能活得久。实际用的时候，你通过 Claude Code 或 Codex CLI 去接具体模型，superpowers 只管流程。

3. 核心机制与实操要点：技能是怎么被组织和调用的

3.1 技能目录结构与文件组织

一套 superpowers 的技能库，落地到文件系统上通常长这样（这是基于常见实践的合理还原，具体目录名可能因版本而异）：

superpowers/ skills/ requirement-clarify/ SKILL.md examples/ code-locate/ SKILL.md test-first/ SKILL.md templates/ refactor-safe/ SKILL.md verify-result/ SKILL.md config/ routing.yaml README.md

每个技能一个目录，核心是那个SKILL.md。这个文件用 Markdown 写，但里面嵌了结构化的元数据（通常用 YAML front matter）。我见过的一个典型写法是这样的：

--- name: test-first trigger: 当任务涉及新增或修改业务逻辑时 inputs: - 目标文件路径 - 预期行为描述 outputs: - 测试文件 - 测试运行结果 --- ## 执行步骤 1. 先根据预期行为写出失败的测试 2. 运行测试，确认它确实失败 3. 编写最小实现让测试通过 4. 重构，保持测试绿色

这种结构的妙处在于：元数据部分给调度器读，正文部分给模型读。调度器根据 trigger 决定要不要加载这个技能，模型根据正文知道具体怎么做。职责分离得很干净。

注意：SKILL.md 的正文不要写得太啰嗦。我踩过的坑是，一开始把技能写得像教科书，结果模型加载后反而抓不住重点。后来精简到“步骤 + 一个正例 + 一个反例”，效果明显更好。

3.2 技能路由：什么时候该用哪个技能

路由是整套框架里最考验设计的部分。superpowers 的路由逻辑一般分两层：规则匹配 + 模型判断。

规则匹配负责快速筛选。比如用户输入里出现“重构”“优化结构”，就优先加载refactor-safe；出现“报错”“不工作”，就优先加载排查类技能。这层是确定性的，快且省 token。

模型判断负责兜底。当规则匹配不出明确技能时，把技能列表的 name 和 trigger 喂给模型，让它选。这层灵活但慢一点。

实际配置里，路由规则通常写在一个 YAML 里：

routes: - pattern: ["重构", "优化结构", "提取函数"] skill: refactor-safe - pattern: ["测试", "TDD", "单元测试"] skill: test-first - pattern: ["报错", "异常", "不工作"] skill: debug-trace

我自己的经验是，规则匹配的命中率能到七成以上，剩下的交给模型判断就够了。不要试图用规则覆盖所有情况，那样规则会膨胀到没法维护。

3.3 上下文注入：让技能拿到它需要的信息

技能要干活，得知道当前项目的状态。superpowers 在调用技能前，会做一次上下文注入，把必要信息塞进去。常见的信息包括：当前工作目录、最近修改的文件、git 状态、相关代码片段。

这里有个细节值得说：上下文不是越多越好。我试过把整个仓库的文件列表都塞进去，结果模型被淹没了，反而找不到重点。后来改成“只注入与当前任务相关的文件”，命中率立刻上来了。

具体做法通常是先用一个轻量的检索步骤（比如基于文件名和最近修改时间）圈定候选文件，再把候选文件的内容注入。这个检索步骤本身也可以是一个 skill，叫code-locate。

3.4 技能组合：单个技能不够用怎么办

真实任务很少只用一个技能。比如“给这个模块加个新接口”，可能要串起requirement-clarify→code-locate→test-first→verify-result四个技能。superpowers 支持技能组合，方式有两种：串行链和条件分支。

串行链就是按顺序执行，前一个的输出作为后一个的输入。条件分支则是根据中间结果决定下一步走哪个技能，比如测试失败就走debug-trace，测试通过就走verify-result。

组合的配置一般写在任务模板里：

workflow: add-feature steps: - skill: requirement-clarify - skill: code-locate - skill: test-first - skill: verify-result on_failure: debug-trace

这套组合机制是 superpowers 真正区别于“单点提示词”的地方。它让 AI 编程从“一问一答”变成了“按流程走”。

4. 完整实操落地：从零搭一套可用的技能框架

4.1 环境准备与工具链确认

在动手之前，先把基础环境理清楚。你需要的东西不多，但每一样都得确认版本。

Node 版本这块我要多嘴一句。很多人装 Codex CLI 很慢或者装完跑不起来，八成是 Node 版本太老。建议直接用 nvm 管理 Node 版本，切到 18 或 20 的 LTS，能省掉一堆莫名其妙的兼容问题。

# 用 nvm 安装并切换 Node nvm install 20 nvm use 20 node -v # 确认输出 v20.x.x

如果你用的是 Claude Code，安装方式通常是全局 npm 包或者官方提供的安装脚本。装完之后先跑一次claude --version确认能正常输出。Codex CLI 同理，装完跑codex --version。

提示：如果你在 VS Code 里用 Claude Code 插件，记得在设置里确认插件指向的是你刚装好的 CLI 路径，否则会出现“插件装了但用不了”的情况。

4.2 技能库的初始化与目录搭建

环境好了，开始搭技能库。我建议不要一上来就写十个技能，先从三个最核心的开始：定位、修改、验证。这三个覆盖了八成的日常开发场景。

mkdir -p superpowers/skills/{code-locate,refactor-safe,verify-result} mkdir -p superpowers/config touch superpowers/config/routing.yaml

然后给每个技能写 SKILL.md。以code-locate为例：

--- name: code-locate trigger: 需要定位与任务相关的代码文件时 inputs: - 任务描述 - 项目根目录 outputs: - 相关文件路径列表 - 每个文件的相关性说明 --- ## 执行步骤 1. 从任务描述中提取关键词（类名、函数名、业务术语） 2. 用关键词在项目内做文件名和内容检索 3. 按最近修改时间和引用关系排序 4. 输出前 5 个最相关的文件路径及理由 ## 反例 不要一次性返回整个目录树，那会让后续步骤失去焦点。

写技能的时候有个心法：把你自己做这件事的思考过程写下来。你平时怎么找代码？先看目录结构，再搜关键词，再顺着引用链找。把这个过程拆成步骤，就是技能。

4.3 路由配置与第一次跑通

技能写好了，配路由。routing.yaml里先写最基础的几条：

routes: - pattern: ["定位", "找一下", "在哪"] skill: code-locate - pattern: ["重构", "优化", "提取"] skill: refactor-safe - pattern: ["验证", "测试", "跑一下"] skill: verify-result

配好之后，在 Claude Code 或 Codex CLI 里发起一个简单任务测试，比如“帮我找一下处理用户登录的代码在哪”。观察它有没有加载code-locate技能，输出是不是按你定义的格式来的。

第一次跑大概率不会完美。可能路由没命中，可能技能加载了但模型没按步骤走。这都正常，调优的过程本身就是理解框架的过程。

4.4 参数计算与阈值选择

框架里有些地方需要设阈值，设不好会明显影响体验。我列几个关键的。

检索返回文件数：默认 5 个。太少可能漏掉关键文件，太多会稀释上下文。我的经验是，中小项目 5 个够用，大项目可以放宽到 8 个，但不要超过 10 个。

技能链最大长度：默认 5 步。超过 5 步的链，中间出错概率会显著上升，而且 token 消耗大。如果任务确实复杂，拆成两个子任务分别跑。

上下文 token 预算：给技能注入的上下文，建议控制在模型上下文窗口的 30% 以内。比如 200K 窗口，注入不要超过 60K。留足空间给模型推理和输出。

这些数字不是死的，你可以根据自己项目的规模和模型能力调整。但一定要有明确的数字，不要让它“自动”，否则出问题时你连从哪查起都不知道。

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

5.1 安装与配置阶段的典型坑

问题一：Node 装 Codex CLI 特别慢或者卡住。这通常是 npm 源的问题。换成国内镜像源能明显改善：

npm config set registry https://registry.npmmirror.com

换完再装，速度一般能快好几倍。如果还是慢，检查一下是不是网络代理配置有冲突。

问题二：Claude Code 提示当前地区不可用。这类提示通常跟账号和网络环境有关。我的建议是先把官方文档的账号要求看清楚，确认自己的使用方式符合官方规定，不要走非正规渠道。合规使用是底线。

问题三：VS Code 插件装了但连不上 CLI。九成是路径问题。在插件设置里手动指定 CLI 的绝对路径，比如/usr/local/bin/claude或~/.nvm/versions/node/v20/bin/codex。指定完重启 VS Code。

问题四：想接本地模型（比如通过 LM Studio 起的服务）。思路是把 CLI 的模型端点指向本地服务的地址。具体配置项因工具而异，一般在 CLI 的配置文件里改 base URL 和 model name。注意本地模型的上下文窗口通常比云端小，技能注入的上下文要相应调小。

5.2 运行阶段的排查速查表

这张表是我自己踩坑踩出来的，基本覆盖了八成以上的常见问题。遇到新问题，先对照这张表过一遍，能省不少时间。

5.3 几个不外传的实操心得

心得一：技能要“小步快跑”地迭代。不要一次写完十个技能再测。写一个，测一个，改一个。我一开始贪多，写了八个技能，结果互相干扰，排查了两天才理清楚。后来改成一次只动一个技能，效率反而高。

心得二：给技能加“反例”比加“正例”更有用。模型很容易理解“要做什么”，但容易忽略“不要做什么”。在 SKILL.md 里明确写一条反例，比如“不要一次性返回整个目录树”，能显著减少跑偏。

心得三：定期清理失效技能。项目在变，有些技能会过时。我每个月会过一遍技能库，把三个月没被调用过的技能归档。技能库不是越大越好，保持精简才能保证路由准确。

心得四：把技能库纳入 Git 管理。技能是会演进的，改坏了要能回滚。用 Git 管理技能库，每次调整都提交，出问题能快速定位是哪次改动引入的。

6. 技能框架的扩展方向与个人体会

6.1 从个人用到团队用的扩展

一个人用 superpowers，技能库怎么组织都行。但要推广到团队，就得考虑几个新问题。

技能的所有权。谁写的技能谁维护，还是统一由一个小组维护？我的建议是核心技能（定位、验证）统一维护，业务相关技能由各业务线自己维护。这样既保证基础能力一致，又给业务灵活性。

技能的评审机制。技能改动会影响所有人的产出质量，所以改动应该走评审。评审重点看两点：触发条件是否清晰、执行步骤是否可验证。这两点不过关的技能，不要合入主干。

技能的使用统计。哪些技能被调用得多，哪些几乎没人用，这些数据能指导技能库的优化。可以在调度层加一个轻量的日志，记录每次技能调用。数据不用复杂，能看出趋势就行。

6.2 与现有工具链的融合

superpowers 不是孤岛，它得跟你现有的工具链配合。几个常见的融合点：

与 CI 的融合。把verify-result技能的输出接到 CI 里，让 AI 改完代码后自动跑一遍流水线。这样人工只需要看最终结果，不用盯着中间过程。

与代码评审的融合。AI 改完的代码，可以让它自己先生成一份变更说明，附在 PR 描述里。评审的人看说明就能快速理解改动意图，效率高很多。

与文档的融合。技能库本身就是一份“团队怎么用 AI 编程”的文档。新人入职，读一遍技能库，就知道团队的 AI 编程规范是什么。这比写一堆文字规范管用。

6.3 我个人的几点体会

用了几个月下来，我最大的感受是：superpowers 这类框架的价值，不在于让 AI 更聪明，而在于让 AI 更可控。模型能力会一直涨，但“可控”这件事，永远需要工程手段来解决。

另一个体会是，不要指望框架能解决所有问题。有些任务就是不适合 AI 做，比如需要大量领域知识判断的架构决策。框架能帮 AI 把重复性工作做好，但判断性的工作还得人来。把 AI 放在它擅长的位置上，比逼它做所有事更明智。

最后分享一个小技巧：如果你刚开始搭技能库，不妨先把你最近一周做过的重复性工作列出来，挑三个最烦的，各写一个技能。这三个技能跑顺了，你对整套框架的理解就到位了。剩下的，就是慢慢积累的事。