企业官网建设流程全解析

1. 从“superpowers”这个词说起：它到底指什么

第一次看到“superpowers”这个标题，加上“agentic skills framework”“software development methodology”这几个关键词，我脑子里第一反应是：这不是某个具体工具的名字，而是一套给 AI 编程代理（agent）赋予“超能力”的方法论框架。换句话说，它讨论的不是“装哪个软件”，而是“怎么让 AI 代理在真实软件开发流程里真正干活、干得靠谱”。

我接触过不少团队在用 Claude Code、Codex CLI 这类命令行 AI 编程代理，大家的普遍困惑是：模型本身很强，但一到真实项目里就“翻车”——改错文件、跑偏需求、把好好的代码重构得面目全非。superpowers 这类框架想解决的，正是这个落差。它把“代理能力”拆成可训练、可复用、可组合的技能单元，再配上一套开发流程约束，让代理从“会聊天”变成“会交付”。

所以这篇内容适合三类人看：一是刚开始用 Claude Code / Codex CLI、还在摸索怎么让它稳定干活的新手；二是已经踩过坑、想系统化提升代理协作效率的开发者；三是团队里负责制定 AI 辅助开发规范的技术负责人。我会把框架思路、落地步骤、实操心得和常见坑都摊开讲，尽量让你看完就能上手。

需要先说明一点：superpowers 本身更偏向一套理念 + 技能组织方式，而不是一个开箱即用的安装包。网上很多热词把它和 Claude Code 安装、Codex CLI 配置混在一起，其实两者是“方法论”和“工具载体”的关系。下面我会先把这个关系理清楚，再讲具体怎么落地。

2. 代理能力框架的核心：把“会写代码”拆成可复用的技能

2.1 为什么单一提示词搞不定真实项目

大多数人用 AI 编程代理的方式是：打开终端，敲一句“帮我实现一个登录功能”，然后等着它输出。结果往往是——它确实写了代码，但和你项目里的目录结构、命名规范、依赖版本全对不上。问题不在于模型笨，而在于你把一个需要多步骤协作的工程任务，压缩成了一次性对话。

真实开发里，一个功能落地至少包含：理解需求、定位相关文件、设计改动方案、写代码、跑测试、处理报错、更新文档。这七八个环节里，任何一步信息缺失，后面就会连锁出错。superpowers 框架的核心洞察就是：代理的能力应该按“技能”来组织，而不是按“对话轮次”来组织。每个技能是一个边界清晰、输入输出明确、可独立验证的单元。

打个比方，传统用法像你雇了一个全能但没上过你公司培训的新人，直接让他上手核心项目；而技能框架像你先给他一套标准作业手册，每个手册对应一个具体动作，做完一个验收一个。后者显然更可控。

2.2 技能单元的四个必备要素

我在实际拆解自己项目里的代理技能时，总结出一个技能单元至少要包含四样东西，缺一个都会导致代理行为不稳定：

• 触发条件：什么情况下该调用这个技能。比如“当用户要求新增 API 接口时”或“当测试失败需要定位原因时”。触发条件写得越具体，代理越不容易乱用技能。
• 输入契约：这个技能需要哪些信息才能开始。比如文件路径、需求描述、现有代码片段。输入不明确，代理就会自己瞎猜。
• 执行步骤：具体做什么，按什么顺序。这一步要写成代理能理解的指令序列，而不是给人看的概述。
• 验收标准：怎么判断这个技能执行成功了。比如“测试全部通过”“lint 无报错”“生成的接口能被现有路由正确挂载”。

这四要素看起来简单，但真正写起来，最容易偷懒的是“验收标准”。很多人只写“完成功能”，结果代理交出来的东西根本没法用。我的经验是：验收标准必须能被自动化检查，哪怕只是跑一条命令看退出码。

2.3 技能之间怎么组合成完整工作流

单个技能再强，也只是零件。superpowers 真正有价值的地方在于技能的组合编排。一个完整的“新增功能”工作流，可能是这样的技能链：

1. 需求解析技能：把模糊需求转成结构化任务清单
2. 代码库探查技能：定位相关文件和现有实现模式
3. 方案设计技能：产出改动计划，标注影响范围
4. 编码技能：按计划写代码
5. 测试技能：生成并运行测试
6. 修复技能：根据测试结果迭代
7. 文档技能：更新相关说明

关键在于，每个技能的输出是下一个技能的输入，形成一条可追溯的链路。这样即使中间某步出错，你也能快速定位是哪个环节的问题，而不是面对一坨“它自己也不知道为什么变成这样”的代码。

我实测下来，用技能链方式组织代理任务，相比单次长对话，任务一次通过率能明显提升。原因很简单：每一步的上下文都被收窄了，代理不需要在一次推理里同时记住所有约束。

3. 在 Claude Code 和 Codex CLI 里落地这套框架

3.1 两个工具在框架里的角色差异

Claude Code 和 Codex CLI 都是命令行 AI 编程代理，但它们在落地 superpowers 这类框架时，定位略有不同。我自己的使用感受是：

Claude Code 的/compact、/model、/resume这些命令，本质上就是在管理代理的“工作记忆”。/compact把长对话压缩成摘要，/resume恢复之前的会话状态——这两个命令配合技能链使用，效果很好：每个技能执行完压缩一次，既保留关键结论，又不让上下文爆炸。

Codex CLI 则更适合把技能写成可复用的命令模板。比如你把“代码库探查”这个技能固化成一个带固定提示前缀的命令，每次调用时只替换目标路径，行为就稳定得多。

3.2 用项目内说明文件固化技能定义

Claude Code 有一个很实用的机制：它会读取项目根目录下的说明文件（比如 CLAUDE.md 之类），把里面的内容作为长期约束。这正好可以用来存放你的技能定义。

我的做法是在项目里建一个agent-skills/目录，每个技能一个 Markdown 文件，然后在主说明文件里引用它们。文件内容按前面说的四要素来写。这样代理每次进入项目，都会先“读一遍作业手册”，行为一致性提升非常明显。

这里有个细节要注意：说明文件不要写太长。我一开始把所有技能都塞进一个文件，结果代理经常“读了后面忘了前面”。后来拆成多个小文件，每个控制在几百字，反而更稳。这跟人看文档一个道理，一页纸能说清的事，别写成十页。

3.3 本地模型接入时的技能适配

有些朋友会用本地模型（比如通过 LM Studio 跑量化模型）来接 Claude Code 或 Codex CLI。这种情况下，技能定义要进一步简化。本地小模型的指令遵循能力通常弱于云端大模型，你写太复杂的多步技能，它执行到一半就乱了。

我的适配经验是：本地模型场景下，每个技能只保留“触发条件 + 执行步骤”两项，验收标准改成人工检查。步骤也尽量压到三步以内。宁可多拆几个技能，也不要让单个技能太复杂。另外，本地模型的上下文窗口往往更小，/compact要更频繁地用。

提示：本地模型接入时，先跑一个最简单的技能验证链路是否通，再逐步加复杂度。直接上完整技能链，大概率会在某个环节卡死，排查起来很痛苦。

4. 一套可复现的落地流程：从零搭起你的技能体系

4.1 第一步：盘点你项目里最高频的开发动作

别一上来就想搭大而全的框架。先拿一张纸，列出你最近两周在项目里重复做过五次以上的动作。比如：

• 新增一个 CRUD 接口
• 修复一个测试失败
• 给现有函数补单元测试
• 更新依赖版本并处理兼容问题
• 根据报错日志定位问题文件

这些高频动作，就是你第一批要固化的技能。频率越高、步骤越固定，越值得做成技能。反过来，那些一次性的、需要大量创造性判断的任务，先别急着技能化，让代理自由发挥反而更好。

我见过有人一上来就想把“架构设计”做成技能，结果写出来的技能又空又泛，代理执行时还是靠猜。架构设计这种高度依赖上下文和经验的活，现阶段更适合人来做，代理打下手。

4.2 第二步：为每个动作写技能卡

拿“新增 CRUD 接口”举例，一张技能卡大概长这样：

技能名称：新增 REST 接口 触发条件：用户明确要求为某个实体新增增删改查接口 输入契约： - 实体名称 - 字段列表及类型 - 现有路由文件路径 执行步骤： 1. 读取现有路由文件，识别路由注册模式 2. 按现有模式生成接口处理函数 3. 在路由文件中注册新路由 4. 生成对应的请求校验逻辑 验收标准： - 新接口能被路由正确挂载 - 请求校验对非法输入返回明确错误 - 现有测试全部通过

写这张卡的过程，其实就是在逼自己把“我脑子里觉得理所当然的步骤”显式化。很多坑就藏在这些“理所当然”里。比如“按现有模式生成”，如果不写清楚现有模式是什么，代理就会按它自己的习惯来，风格立刻跑偏。

4.3 第三步：小步验证，逐个技能调优

技能卡写完，不要一次性全上。一次只验证一个技能，跑通了再上第二个。验证时重点看两件事：一是代理有没有在正确的时机触发这个技能，二是执行结果符不符合验收标准。

我自己的调优记录里，最常见的问题是“触发条件写太宽”。比如“当用户要求改代码时”这种触发条件，几乎任何请求都会命中，导致代理动不动就套用这个技能。后来改成“当用户明确要求新增接口且给出了实体名称时”，精准多了。

另一个高频问题是“执行步骤里隐含了未声明的假设”。比如步骤写“生成接口处理函数”，但没说要复用现有的错误处理中间件，代理就可能自己造一套。解决办法是把这些隐含假设也写进步骤里，哪怕显得啰嗦。

4.4 第四步：把技能链串起来跑通一个完整需求

单个技能都验证通过后，开始串链。串链时最容易暴露的问题是技能之间的接口对不上。比如“方案设计技能”输出的改动计划格式，和“编码技能”期望的输入格式不一致，中间就断了。

解决办法是给技能之间的数据传递定一个简单约定。我一般用 Markdown 的固定小节标题来传递，比如方案设计技能必须输出一个## 改动文件清单小节，编码技能就从这个小节里读文件路径。格式固定了，链路就稳了。

串链跑通后，你会发现一个额外好处：整个开发过程变得可观测了。哪一步慢、哪一步容易错，一目了然。这比“黑盒式”地让代理一口气干完，排查效率高太多。

5. 实操中真正会咬人的那些坑

5.1 上下文污染：技能越用越“飘”的元凶

用了一段时间后，我发现代理执行技能时开始“夹带私货”——明明技能卡里没写的步骤，它自己加上了。排查下来，原因是上下文里残留了之前任务的无关信息。Claude Code 的/compact如果压缩得不干净，旧任务的结论会污染新任务的判断。

我的应对方法是：每切换一个不相关的任务，就开新会话，不要图省事在同一个会话里连着干。如果确实需要保留一些背景，就手动把关键信息摘出来，写进新会话的开头，而不是依赖自动压缩。这个习惯养成后，代理行为的稳定性提升很明显。

5.2 技能卡写太细反而限制发挥

这是个反直觉的坑。我一度把技能卡写得极其详细，每一步都规定死，结果代理变得非常死板，遇到技能卡没覆盖的边界情况就卡住不动。后来我调整策略：核心步骤写死，边界处理留白，并在技能卡末尾加一句“遇到未覆盖情况时，先说明情况再询问”。

这个改动让代理从“只会照章办事”变成“照章办事 + 遇到意外会求助”，实用性高了不少。框架的目的是约束，不是把代理变成机器人。

5.3 验收标准形同虚设的典型表现

前面强调过验收标准要可自动化检查，但实操中还有个隐蔽问题：验收标准写得太宽松，等于没写。比如“代码能运行”这种标准，代理随便写个能跑但逻辑错的版本也能过。

我的经验是，验收标准要尽量落到具体的命令和具体的输出上。比如不说“测试通过”，而说“运行npm test后退出码为 0 且无 failed 用例”。不说“接口正常”，而说“用给定请求体调用接口返回 200 且响应体包含 id 字段”。越具体，代理越难糊弄。

5.4 多工具混用时的技能同步问题

有些团队同时用 Claude Code 和 Codex CLI，技能定义放在两个地方，时间一长就不同步了。A 工具的技能卡更新了，B 工具的还是旧的，导致同一个任务在两个工具里表现不一致。

我的做法是技能卡只维护一份，放在项目仓库里，两个工具都通过引用同一份文件来读取。Claude Code 通过项目说明文件引用，Codex CLI 通过命令模板里的路径引用。这样改一处，两边都生效。虽然初期配置麻烦点，但长期省心。

6. 让框架真正产生复利的几个习惯

6.1 每次踩坑都回写技能卡

这是我认为最重要的一条。代理每次出错，不要只是当场修好就完事，要问自己：这个错能不能通过改技能卡来预防？如果能，就当场改。比如代理又一次忘了复用错误处理中间件，那就在编码技能的步骤里把“必须复用现有错误处理中间件”加粗写进去。

坚持这个习惯几个月后，你的技能卡会越来越“厚”，但代理犯同类错误的概率会越来越低。这就是框架的复利效应——你的经验被固化下来，不再依赖每次临场提醒。

6.2 定期清理过时技能

和回写相反的操作是清理。项目在演进，有些技能会过时。比如你换了 Web 框架，旧的接口生成技能就不适用了。过时的技能卡留在那里，代理偶尔还会误触发，反而添乱。

我一般每个月花半小时过一遍技能卡，把三个月没触发过的、或者触发后经常需要人工返工的，标记出来评估。该删的删，该改的改。技能体系保持精简，比堆一大堆用不上的技能更有价值。

6.3 把技能卡当成团队资产来维护

如果是一个团队在用，技能卡就不该只存在个人电脑里。放到团队仓库，走代码评审流程，谁改了技能卡大家都能看到。这样新成员加入时，直接读技能卡就能理解“我们团队期望代理怎么干活”，上手速度快很多。

而且团队评审能发现个人容易忽略的盲区。我自己写的技能卡，经常被同事指出“这里假设了某个环境变量存在，但新机器上不一定有”。这种问题个人很难自查出来。

6.4 给技能体系留一个“逃生通道”

最后分享一个我踩过大坑才总结出的习惯：永远保留手动接管的能力。代理执行技能链时，如果连续两次验收不通过，就自动停下来，把当前状态和问题抛给人，而不是无限重试。

我早期没设这个限制，结果代理在一个测试失败上反复折腾了十几轮，烧了一堆 token，最后还是得人工介入。后来在技能链里加了“连续失败两次即暂停”的规则，省心多了。框架再完善，也要承认代理有搞不定的时候，及时止损比硬撑重要。

这套东西说到底，核心不是某个工具或某段配置，而是把你在项目里积累的判断力，转化成代理能执行的显式规则。superpowers 这个词听起来玄乎，落地下来其实就是一件件具体的技能卡、一次次踩坑后的回写、一个个被验证过的验收标准。把这些做扎实了，代理才真的算有了“超能力”。