企业官网建设流程全解析

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

第一次看到 “superpowers” 这个词，是在几个做 AI 编程工具链的朋友群里。有人甩了个链接，配文是“终于有人把 agentic skills framework 这件事讲明白了”。点进去看完之后，我的第一反应是：这东西本质上不是又一个“提示词合集”，而是一套软件研发方法论的工程化封装。

说得再直白一点，superpowers 想做的事情，是把“一个资深工程师在接到需求之后，怎么拆任务、怎么选工具、怎么验证结果、怎么沉淀经验”这一整套思维流程，变成 AI 编程助手可以稳定复用的技能模块。它面向的不是“让 AI 帮我写个快排”这种一次性需求，而是“让 AI 像一个有纪律的工程团队成员一样，持续参与真实项目的开发”。

这就引出了它和 Claude Code、Codex CLI 这类工具的关系。Claude Code 和 Codex CLI 是“执行器”，它们负责在终端里读文件、改代码、跑命令；而 superpowers 更像是“操作系统层”的东西，它定义了这些执行器在什么场景下该调用什么技能、按什么顺序执行、产出什么样的中间产物。你可以把它理解成给 AI 编程助手装了一套“职业素养培训体系”。

为什么这件事值得单独拿出来聊？因为过去大半年，我见过太多人装完 Claude Code 之后，第一反应是“哇它能直接改我代码”，第二反应是“但它改得乱七八糟”。问题不在于模型能力不够，而在于缺少一套约束机制——什么时候该先读文档、什么时候该先写测试、什么时候该停下来问人。superpowers 这类框架的价值，恰恰在于把这些“工程直觉”显式化、模块化。

这篇文章适合三类人看：一是已经在用 Claude Code 或 Codex CLI，但觉得输出质量不稳定、想找一套方法论来兜底的开发者；二是正在评估要不要把 AI 编程助手引入团队工作流的技术负责人；三是对 agentic skills framework 这个概念感兴趣，想搞清楚它和普通 prompt engineering 区别在哪的人。我会尽量把安装配置、核心机制、实操踩坑都讲透，让你看完能直接上手试。

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

2.1 从提示词工程到技能工程的关键跃迁

大部分人接触 AI 编程的路径是这样的：先学会写 prompt，然后发现 prompt 越写越长，最后变成一个几百行的“系统提示词”。这种做法在单次任务里还行，一旦任务变复杂、步骤变多，就会暴露两个致命问题：上下文漂移和技能不可复用。

上下文漂移是指，当对话轮次变多，模型会逐渐“忘记”最初设定的规则。你在一开始写了“所有代码必须带类型注解”，聊到第十轮它就开始写无类型代码了。技能不可复用是指，你为 A 项目精心调教的提示词，换到 B 项目几乎要重写一遍，因为项目结构、技术栈、团队规范都不一样。

superpowers 的设计思路，是把“提示词”升级成“技能”。一个技能不是一段文字，而是一个有明确输入输出、有触发条件、有验证标准的模块。比如“写单元测试”这个技能，它的输入是“一个待测试的函数”，输出是“一组覆盖边界条件的测试用例”，触发条件是“用户要求实现新功能或修改现有逻辑”，验证标准是“测试能跑通且覆盖率达标”。

这种设计带来的直接好处是：技能可以被组合、被替换、被版本管理。你可以今天用 A 技能写测试，明天换成 B 技能，只要接口一致，上层工作流不用改。这跟微服务架构的思路是一模一样的——把能力拆成独立单元，通过标准协议通信。

2.2 为什么选择与 Claude Code、Codex CLI 深度绑定

有人可能会问：为什么不做一个独立的 IDE 插件，非要绑定终端工具？我的理解是，终端是 AI 编程助手最自然的栖息地。原因有三：

第一，终端能直接访问文件系统和命令行，这是 AI 改代码、跑测试、查日志的基础能力。IDE 插件受限于编辑器 API，很多操作要绕弯。第二，终端工具天然支持“人在回路”的交互模式，AI 执行一步、人确认一步，这比全自动改代码安全得多。第三，Claude Code 和 Codex CLI 都已经解决了“模型怎么调用工具”这个底层问题，superpowers 只需要在上面定义“什么时候调用什么工具”。

从实际使用体验来看，Claude Code 的/compact、/model、/resume这些命令，本质上就是给技能框架预留的“控制接口”。/compact用来压缩上下文，防止漂移；/model用来切换模型，应对不同复杂度任务；/resume用来恢复会话，支持长周期项目。这些命令单独看很普通，但放在技能框架里，就变成了工作流的控制节点。

2.3 技能模块的粒度设计：多大算一个技能

这是我在实际使用中踩过的最大的坑。一开始我把技能切得太细，比如“读文件”“写文件”“跑命令”各算一个技能，结果发现调度开销比执行开销还大。后来又把技能切得太粗，一个“实现功能”技能包打天下，结果又回到了提示词工程的老路。

比较合理的粒度是按“工程活动”来切。一个工程活动通常包含多个原子操作，但有明确的起止点和交付物。比如：

这个粒度下，每个技能大概对应 5 到 15 分钟的 AI 工作时间，人可以在每个技能结束后介入检查，既不会太频繁打断，也不会让错误累积到不可收拾。

3. 环境准备与工具链搭建：从零到能跑通第一个技能

3.1 Claude Code 的安装与基础配置

先说 Claude Code 的安装。官方文档给的路径是最稳的，但国内网络环境下经常会遇到note: claude code might not be available in your country这类提示。我的建议是先把基础环境准备好，再处理账号和网络问题。

在 macOS 上，最省事的方式是用 npm 全局安装：

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

装完之后跑claude --version确认版本。如果提示命令找不到，检查 npm 全局 bin 目录有没有加到 PATH 里。Ubuntu 上的步骤类似，但要注意 Node.js 版本不能太低，建议 18 以上。我试过在 Ubuntu 22.04 上用 Node 16 装，跑起来各种奇怪的报错，换成 Node 20 之后一切正常。

Windows 用户要注意一个坑：claude code 由于与64位版本的windows不兼容这个报错，通常是因为装了 32 位的 Node.js。去官网重新下 64 位安装包覆盖安装就行。另外 Windows 上建议用 WSL2 而不是原生 PowerShell，文件路径和权限问题会少很多。

配置方面，核心是两件事：模型接入和权限控制。模型接入默认走官方账号，如果你有第三方 API 或者想接本地模型（比如通过 LM Studio 跑的模型），需要配置ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个环境变量。这里不展开具体服务商，只说配置方法：

export ANTHROPIC_BASE_URL="你的服务地址" export ANTHROPIC_API_KEY="你的密钥"

权限控制是很多人忽略的。Claude Code 默认会问你“是否允许执行这个命令”，如果你嫌烦可以配置白名单，但我的建议是前期不要开全自动，至少用一周时间观察它都会执行哪些命令，心里有数之后再逐步放开。

3.2 Codex CLI 的安装与命令体系

Codex CLI 的安装更简单，它是个独立的二进制文件，从官方仓库下载对应平台的版本就行。装完之后核心要掌握的命令不多，但每个都要用熟：

• /compact：压缩当前会话上下文。当你感觉 AI 开始“忘事”或者响应变慢时，跑一下这个，它会总结之前的对话并丢弃冗余信息。
• /model：切换模型。简单任务用小模型省钱，复杂任务切大模型保质量。
• /resume：恢复之前的会话。长周期项目必备，不用每次从头解释背景。
• /clear：清空当前会话。跟/compact的区别是它不保留摘要，彻底重来。

删除 Codex CLI 也很简单，找到安装目录直接删掉二进制文件，再把 PATH 里的相关配置清理掉就行。但删之前建议把~/.codex目录下的配置和会话记录备份一下，里面可能有你调教好的技能配置。

3.3 VS Code 集成：让编辑器成为技能框架的前端

claude code for vs code这个插件我用了大概两个月，最大的价值不是“在编辑器里聊天”，而是它能把当前打开的文件、选中的代码片段、终端输出自动作为上下文传给 Claude Code。这省掉了大量“复制粘贴给 AI 看”的操作。

配置步骤不复杂：在 VS Code 扩展市场搜 Claude Code，安装后重启，然后在设置里填 API 配置。如果遇到your organization has disabled claude subscription access for claude code这个提示，说明你的账号类型不支持，需要换成 API 计费模式或者用第三方接入。

VS Code 插件的使用技巧有几个：一是用Cmd+Shift+P调出命令面板，搜 “Claude” 能看到所有可用命令；二是选中代码后右键可以直接“发送到 Claude”；三是终端里跑的 Claude Code 会话，插件能自动同步上下文。这三点用熟了，效率提升非常明显。

4. 核心技能模块的实操拆解：以“功能实现”技能为例

4.1 技能定义文件的结构与编写要点

superpowers 框架里，每个技能通常用一个 Markdown 文件定义，放在项目的.skills目录下。文件结构一般包含四个部分：元信息、触发条件、执行步骤、验证标准。

元信息部分写技能名称、版本、依赖的其他技能。触发条件用自然语言描述“什么情况下该用这个技能”，写得越具体越好。执行步骤是核心，要拆到“AI 能一步步跟着做”的粒度。验证标准是很多人会漏掉的，但它恰恰是保证质量的关键——没有验证标准的技能，AI 做完之后你不知道对不对。

我拿“功能实现”技能举个例子，实际文件大概长这样：

--- name: implement-feature version: 1.2 depends: [clarify-requirement, design-solution] --- ## 触发条件 用户要求实现一个已经过需求澄清和方案设计的功能点。 ## 执行步骤 1. 读取方案设计文档，确认本次要实现的任务编号 2. 读取相关现有代码，理解代码风格和依赖关系 3. 编写实现代码，遵循项目现有的命名和注释规范 4. 编写或更新对应的单元测试 5. 在本地运行测试，确认全部通过 6. 输出变更摘要，包括修改的文件列表和测试结果 ## 验证标准 - 所有新增和修改的测试用例通过 - 代码通过项目的 lint 检查 - 变更摘要中明确列出每个文件的修改原因

这个文件看起来简单，但每一条都是踩坑踩出来的。比如“读取相关现有代码”这一步，一开始我没写，结果 AI 写出来的代码风格跟项目完全不搭，review 的时候被同事吐槽“像两个人写的”。加上这一步之后，风格一致性问题基本消失了。

4.2 技能链的编排：多个技能如何串起来

单个技能好用，但真正的威力在于技能链。一个完整的功能开发流程，通常是这样串的：

需求澄清 → 方案设计 → 功能实现 → 代码审查 → 问题排查（如果有 bug）

每个箭头代表一次技能切换，切换的触发条件由上一个技能的输出来决定。比如“方案设计”技能输出了一份任务列表，“功能实现”技能就逐个任务执行，每完成一个任务就回到技能链的起点判断下一步。

这里有个实操细节：技能切换时要不要清空上下文。我的经验是，如果两个技能共享大量背景信息（比如都在同一个模块里工作），就保留上下文用/compact压缩；如果跨度很大（比如从后端跳到前端），就/clear重来，避免旧上下文干扰。

还有一个坑是技能循环。我遇到过“功能实现”做完之后，“代码审查”发现问题，又回到“功能实现”修改，改完再审查，来回好几轮。这本身是正常的，但要设置一个上限，比如三轮之后还没通过，就停下来人工介入。不然 AI 会在两个技能之间无限循环，烧 token 不说，还可能把代码改得越来越乱。

4.3 与本地模型配合：用 LM Studio 跑私有技能

claude code 调用 lmstudio 的本地模型这个需求，我实测下来是可行的，但有几个前提。LM Studio 要开启 OpenAI 兼容的 API 服务，然后在 Claude Code 里把ANTHROPIC_BASE_URL指向 LM Studio 的地址。模型选择上，建议至少 14B 参数以上，不然复杂技能的执行质量会明显下降。

本地模型跑技能框架的优势是数据不出本地，适合处理敏感项目。劣势是速度和稳定性不如云端，尤其是长上下文场景，本地模型容易崩。我的折中方案是：需求澄清、方案设计这类需要强推理的技能用云端模型，功能实现、代码格式化这类确定性高的技能用本地模型。

配置的时候注意一点：LM Studio 的 API 默认不支持 Claude Code 用的一些高级参数，需要在配置里关掉对应的功能开关。具体是哪些参数，看 LM Studio 的日志报错就行，它会明确告诉你哪个字段不支持。

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

5.1 安装与配置阶段的典型报错

这个阶段的问题占了我在群里看到提问的一半以上。整理成表格方便对照：

这里重点说一个：很多人装完之后跑claude没反应，也不报错，就是卡住。这种情况九成是网络问题，Claude Code 启动时会尝试连接服务端，连不上就静默等待。解决办法是在配置里加超时设置，或者先用curl测试一下服务端地址通不通。

5.2 技能执行中的“翻车”场景与补救

技能执行翻车主要有三种表现：改错文件、改坏代码、陷入循环。

改错文件通常是因为技能定义里没写清楚“只修改哪些文件”。补救方法是在技能定义里加一条“修改前先列出将要修改的文件清单，等待确认”。这个确认步骤看起来多余，但能避免 90% 的误操作。

改坏代码的补救靠版本控制。我的习惯是，每次让 AI 执行技能之前，先git commit一次，这样出问题直接git checkout回滚。不要指望 AI 自己改回来，它越改越乱的概率更大。

陷入循环前面提过，设置轮次上限是最简单的办法。另外可以在技能定义里加“如果连续两次修改同一个问题仍未解决，停止并输出当前状态”，给人工介入留出空间。

5.3 性能与成本优化的实操经验

用技能框架跑项目，token 消耗比单次对话高不少，因为每个技能都要读上下文、写中间产物。优化方向有三个：

一是技能粒度要合理，前面讲过，太细调度开销大，太粗质量不稳定。二是善用/compact，我一般每完成两到三个技能就压缩一次，能省 30% 左右的 token。三是模型分级，简单技能用便宜模型，复杂技能用贵模型，整体成本能降一半。

还有一个容易被忽略的点：技能定义文件本身要精简。我见过有人把技能定义写成两千字，每次执行都要读一遍，纯属浪费。技能定义控制在 500 字以内，把详细说明放到单独的文档里，需要时再读。

6. 把技能框架接入真实项目：一个完整案例的复盘

6.1 项目背景与技能链设计

上个月我接了个小项目，给一个内部工具加数据导出功能。需求不复杂，但涉及后端接口、前端按钮、导出格式三个部分，正好适合用技能框架跑一遍。

技能链设计是这样的：需求澄清（确认导出格式和字段）→ 方案设计（确定用 CSV 还是 Excel，接口怎么设计）→ 功能实现（分三个子任务：后端接口、前端按钮、格式转换）→ 代码审查 → 联调测试。

每个技能我都提前写好了定义文件，放在项目根目录的.skills文件夹里。这里有个小技巧：技能定义文件也纳入 git 管理，这样团队其他人能复用，也能追溯每次修改的原因。

6.2 执行过程中的关键决策点

执行到“方案设计”技能时，AI 给出了两个方案：一是后端直接生成 CSV 返回，二是后端返回 JSON 前端生成 CSV。我让它把两个方案的优缺点列出来，然后人工选了第一个，因为数据量不大，后端生成更简单。

这个决策点很关键。如果完全让 AI 决定，它可能会选一个“技术上更优雅但实际不必要”的方案。技能框架的价值不是替代人做决策，而是把决策点显式暴露出来，让人在关键节点介入。

执行到“功能实现”时，AI 第一次写的后端接口没有处理空数据的情况，测试的时候报错了。“问题排查”技能介入，定位到是边界条件没覆盖，回到“功能实现”补上。整个过程大概花了 40 分钟，比我自己写快不了太多，但代码规范性和测试覆盖率明显更好。

6.3 复盘：哪些技能好用，哪些需要改

跑完这个项目，我对技能定义做了几处修改。一是“功能实现”技能里加了“必须处理空数据和异常输入”的检查项，二是“代码审查”技能里加了“检查是否有硬编码的配置项”，三是给技能链加了“每个技能结束后输出一句话摘要”的要求，方便回溯。

不好用的技能也有。“需求澄清”技能在需求本身比较明确的时候显得多余，后来我加了个判断条件：如果需求描述超过 200 字且包含明确的验收标准，就跳过澄清直接进设计。

这套东西用下来，我最大的体会是：技能框架不是让 AI 更聪明，而是让 AI 更稳定。它不会帮你写出惊艳的代码，但能保证每次输出的质量都在及格线以上，这对工程团队来说比偶尔的惊艳重要得多。

7. 技能框架的扩展与团队协作

7.1 自定义技能的编写规范

写自定义技能，我总结了一个“三要三不要”原则。三要：要写清楚触发条件，要定义验证标准，要控制篇幅。三不要：不要写模糊的步骤（比如“优化代码”这种），不要依赖未定义的技能，不要在技能里硬编码项目路径。

触发条件这块特别重要。我见过有人写“当需要写代码时触发”，这等于没写。好的触发条件应该是“当用户要求实现一个已经在任务列表中的功能点，且该功能点的依赖任务都已完成时触发”。条件越具体，误触发的概率越低。

验证标准要可量化。“代码质量好”不是验证标准，“通过 lint 检查且测试覆盖率不低于 80%”才是。可量化的标准还有个好处，就是能自动化检查，不用人肉判断。

7.2 团队共享技能的版本管理

团队用技能框架，最大的挑战是技能定义的版本一致性。A 同学改了“功能实现”技能，B 同学不知道，还在用旧版本，结果两人产出的代码风格不一致。

解决办法是把技能定义当成代码来管理：放 git 仓库，改动用 PR，合并前 review。另外给技能定义加版本号，技能链里引用的时候指定版本，避免“上游改了导致下游崩”的情况。

还有个实操细节：技能定义里的“项目特定配置”（比如代码规范、目录结构）应该抽出来放到单独的配置文件里，技能定义本身保持通用。这样换项目的时候只需要改配置，不用改技能。

7.3 从个人工具到团队基础设施的演进路径

我观察到的演进路径大概是这样的：第一阶段，个人用技能框架提升自己的效率；第二阶段，把好用的技能分享给团队，大家各自用；第三阶段，团队统一技能定义和技能链，形成标准工作流；第四阶段，技能框架和 CI/CD 打通，AI 产出的代码自动进入审查和测试流程。

大部分团队卡在第二阶段到第三阶段之间，因为统一技能定义意味着统一工作习惯，这比技术问题难多了。我的建议是先从“代码审查”和“问题排查”这两个技能开始统一，因为它们对个人习惯的依赖最小，最容易达成共识。

走到第四阶段的话，技能框架就不只是“AI 编程助手”了，而是团队研发流程的一个执行层。这时候要考虑的东西更多，比如技能执行的审计日志、失败重试策略、和现有工单系统的集成。这些我还在摸索，有进展再单独写一篇。

8. 一些零散但重要的实操心得

8.1 关于模型选择的经验

不同技能对模型能力的要求差异很大。“需求澄清”和“方案设计”需要强推理，建议用大模型；“功能实现”和“代码格式化”确定性高，中小模型就够；“代码审查”介于两者之间，看项目复杂度。

切换模型用/model命令，但要注意切换模型会丢失部分上下文。我的做法是在技能切换的间隙切模型，不要在技能执行中途切。

8.2 关于上下文管理的经验

上下文管理是技能框架里最容易被低估的部分。我的经验是：每个技能执行前，只加载该技能需要的上下文。比如“功能实现”技能只需要当前任务描述和相关代码文件，不需要整个项目的架构文档。加载过多上下文不仅浪费 token，还会干扰模型判断。

/compact的时机也有讲究。我一般在技能链完成一个完整循环（比如“实现→审查→修复”走完一轮）之后压缩一次，而不是每个技能结束都压缩。压缩太频繁会丢失有用的中间信息。

8.3 关于错误恢复的经验

AI 执行技能出错是常态，关键是快速恢复。我的标准流程是：出错后先git diff看改了什么，判断是局部问题还是全局问题。局部问题让 AI 修，全局问题直接git checkout回滚重来。

回滚重来的时候，把出错的信息作为“负面示例”加到技能定义里，避免下次再犯。这个习惯坚持下来，技能定义的健壮性会越来越高。

8.4 关于学习曲线的经验

从零开始用技能框架，前两周是最痛苦的，因为要同时学工具用法、写技能定义、适应新的工作流。我的建议是先从单个技能开始，比如只用“代码审查”技能，用熟了再加第二个。不要一上来就搭完整技能链，那样挫败感太强。

另外，前期不要追求技能定义的完美。先写个能用的版本，在实际使用中迭代。我现在的技能定义文件，跟第一版比起来几乎重写了三遍，但每一版都是被实际问题逼出来的，比一开始就“设计完美”要实用得多。

8.5 关于工具边界的经验

最后说一个认知层面的东西：技能框架不能替代工程判断。它能保证 AI 按流程做事，但流程本身对不对、某个决策该怎么做，还是要人来定。我见过有人把技能框架当成“全自动开发机”，结果产出代码一堆逻辑问题，因为 AI 根本不知道业务背景。

正确的定位是：技能框架是放大器，它放大的是你已有的工程能力。你工程能力强，它让你更快；你工程能力弱，它让你更快地写出烂代码。所以用这套东西之前，先把基本功打扎实，不然工具越好，翻车越快。