企业官网建设流程全解析

1. 从“superpowers”说起：一套让编码智能体真正长出“超能力”的技能框架

第一次看到“superpowers”这个词，是在几个做智能体开发的朋友群里。有人甩出一句“想要安装superpowers”，底下立刻有人接“装完你就回不去了”。我当时的第一反应是：又一个营销味很重的名字。但真正把它的设计思路拆开看之后，我改主意了——它解决的是一个非常具体、非常痛的问题：编码智能体（coding agents）在真实项目里为什么总是“看起来聪明，干起来拉胯”。

superpowers 本质上是一套agentic skills framework（智能体技能框架），同时它背后还藏着一套software development methodology（软件开发方法论）。它要干的事情，是把智能体从“一个会聊天的代码生成器”变成“一个能按工程规范交付的协作伙伴”。核心手段就是composable skills（可组合技能）——把开发流程里的每一个动作拆成独立、可复用、可拼装的技能单元，让智能体在需要的时候自己调用、自己组合。

这套东西适合谁？如果你只是偶尔让智能体帮你写个正则、改个报错，那它对你意义不大。但如果你正在用编码智能体做完整的功能开发、维护一个持续迭代的代码库、或者带团队把智能体接入到日常研发流程里，那 superpowers 这套思路值得你花时间吃透。它不挑具体用哪个模型、哪个客户端，核心是一套“怎么组织智能体行为”的方法论加技能库。

我下面会从设计思路、核心机制、实操落地、踩坑排查几个角度，把 superpowers 这套框架掰开揉碎讲清楚。内容里涉及的具体技能清单和参数，我会基于常见的 agentic skills 实践来补全，并明确标注哪些是通用做法、哪些需要你按自己项目调整。

2. superpowers 到底在解决什么问题：智能体开发的三个断层

2.1 断层一：会写代码，但不会“按流程写代码”

大部分编码智能体的默认行为是“你问一句，它答一段”。你让它写个函数，它写得挺漂亮；你让它改个 bug，它也能定位。但一旦任务变成“给这个模块加一个带校验、带日志、带测试的新接口”，它就开始飘了——要么漏掉测试，要么日志格式跟项目里其他模块不一致，要么校验逻辑跟已有的工具函数重复造轮子。

这不是模型能力问题，是流程缺失。人类工程师接到这种任务，脑子里会自动跑一条流水线：先看现有代码风格，再找可复用的工具，然后写实现，接着补测试，最后自查一遍边界条件。智能体缺的就是这条被显式定义、可被调用的流水线。superpowers 的第一个价值，就是把这套流水线拆成一个个技能，让智能体在合适的时机调用合适的技能。

2.2 断层二：技能不可组合，每次都要从头教

你可能试过给智能体写很长的系统提示词，把“先做什么、再做什么”全塞进去。问题是，提示词越长，模型越容易在中途丢失上下文，而且这套提示词换个项目就不适用了。更麻烦的是，你没法把“写测试”这个能力单独拿出来，复用到另一个任务里。

composable skills 的思路正好相反：每个技能是一个独立单元，有自己的触发条件、输入输出和执行逻辑。智能体面对一个任务时，不是背一整本手册，而是像搭积木一样，把需要的技能拼起来。写接口这个任务，可能组合了“读取项目规范”“查找可复用工具”“生成实现”“生成测试”“自查边界”五个技能。下次做另一个任务，可能只需要其中三个。这种组合能力，才是“超能力”的真正含义。

2.3 断层三：交付质量靠运气，没有可复现的验收标准

我见过太多团队用智能体写完代码后，靠人工 review 兜底。review 通过了就合并，没通过就再让智能体改一轮。这个过程不可复现，换个人、换个时间，结果可能完全不同。

superpowers 在方法论层面强调的一点是：每个技能都要有可验证的输出。写测试的技能，输出必须是一组能跑通的测试用例；自查的技能，输出必须是一份检查清单和结论。这样一来，智能体的交付物不再是“一段看起来对的代码”，而是“一段通过了明确验收标准的代码”。质量从靠感觉变成了靠标准。

3. 核心机制拆解：composable skills 是怎么运转的

3.1 技能的定义：一个技能应该包含什么

在 superpowers 的语境里，一个技能不是一段提示词那么简单。我按常见实践整理了一个技能应该具备的要素，你可以对照检查自己写的技能是否完整：

这五个要素里，输入契约和输出契约是最容易被忽略的。很多人写技能只写“做什么”，不写“需要什么”和“产出什么”，结果就是技能之间没法组合——上一个技能的输出，下一个技能接不住。

3.2 技能的粒度：拆到多细才合适

这是实操中最难拿捏的一点。拆得太粗，一个技能干太多事，组合灵活性就没了；拆得太细，技能数量爆炸，智能体调用开销变大，还容易在技能之间丢失上下文。

我的经验是：一个技能对应一个可独立验收的动作。比如“生成实现代码”是一个技能，“生成单元测试”是另一个技能，这两个可以独立验收，所以分开。“读取项目规范”和“查找可复用工具”也可以分开，因为前者是信息收集，后者是信息筛选，验收标准不同。

但“打开文件”和“读取文件内容”就不该拆成两个技能，因为它们无法独立验收，合在一起才是一个完整动作。判断标准很简单：如果这个动作单独拿出来，你能说清楚它“做完了没有”，那它就可以是一个技能。

3.3 技能的编排：谁来决定调用顺序

superpowers 里技能的编排有两种模式，我分别说一下适用场景。

第一种是显式编排，也就是在任务定义里写清楚技能调用顺序。比如“加接口”这个任务，明确按“读规范 → 找工具 → 写实现 → 写测试 → 自查”的顺序执行。这种模式适合流程稳定、步骤明确的任务，可控性最强。

第二种是隐式编排，智能体根据当前上下文自己决定下一步调用哪个技能。这种模式灵活，但风险也大——智能体可能跳过关键技能，或者陷入循环调用。我的建议是：核心流程用显式编排兜底，边缘情况允许隐式编排补充。比如“写实现”之前必须显式调用“读规范”，但“读规范”之后要不要调用“找工具”，可以让智能体根据项目情况自己判断。

提示：隐式编排一定要设置最大调用轮数，否则智能体可能在两个技能之间反复横跳，消耗大量 token 还出不来结果。

4. 实操落地：从零搭一套可用的 superpowers 技能库

4.1 第一步：梳理你项目里的高频开发动作

不要一上来就想着搭一套大而全的技能库。先拿一个真实项目，把最近两周智能体帮你做过的任务列出来，然后归纳出重复出现的动作。我拿一个后端项目举例，梳理出来大概是这些：

• 读取项目代码规范和目录结构
• 查找已有的工具函数和公共组件
• 生成符合规范的实现代码
• 生成对应的单元测试
• 检查边界条件和异常处理
• 更新接口文档
• 生成变更说明

这七个动作里，前六个几乎每个功能开发都会用到，第七个只在需要发版时用。那你的第一批技能就做前六个，第七个后面再补。

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

我拿“生成单元测试”这个技能举例，展示一个完整的技能定义应该长什么样。注意，下面是通用结构，具体内容你要按自己项目的测试框架和规范来改。

skill: generate_unit_test trigger: - 当有新的实现代码需要测试覆盖时 - 当现有测试未覆盖新增分支时 input: - 实现代码文件路径 - 项目测试框架类型（如 pytest / jest / junit） - 项目测试规范文档路径 - 已有测试文件示例路径 steps: - 读取测试规范文档，提取命名约定、断言风格、mock 规则 - 读取已有测试文件示例，确认目录结构和导入方式 - 分析实现代码的公开函数和分支 - 为每个分支生成至少一个测试用例 - 为异常路径生成测试用例 output: - 测试文件路径 - 测试用例清单（函数名 + 覆盖分支） - 未覆盖分支说明（如有） acceptance: - 测试文件能被测试框架识别 - 所有生成的测试用例能通过 - 分支覆盖率不低于项目阈值

这个定义里，input 里的“已有测试文件示例路径”很关键。没有这个，智能体生成的测试风格可能跟项目里其他测试完全不一样，review 的时候会被打回来。这就是经验——文档里通常不会强调这一点，但实际用起来差别很大。

4.3 第三步：把技能接入你的编码智能体

技能定义写好了，怎么让智能体用起来？不同客户端的接入方式不一样，但核心逻辑是一样的：把技能定义作为可检索的知识库，让智能体在需要时检索并加载。

我试过两种接入方式。一种是把技能定义放在项目根目录的特定文件夹里，智能体启动时扫描这个文件夹，把技能索引加载到上下文里。另一种是把技能定义放在外部服务里，智能体通过工具调用去检索。前者简单，适合技能数量少的情况；后者灵活，适合技能多、需要版本管理的情况。

接入之后，你要做一次验证：给智能体一个真实任务，看它会不会主动调用相关技能。如果它不调用，检查两个地方——触发条件写得够不够明确，以及技能索引有没有被正确加载。我踩过的坑是触发条件写得太抽象，比如“当需要测试时”，智能体根本不知道什么叫“需要测试”。改成“当有新的实现代码文件且该文件没有对应测试文件时”，调用率立刻上来了。

4.4 第四步：建立技能的迭代机制

技能库不是写完就完事的。每次智能体交付质量不达标，你都要回溯是哪个技能出了问题，然后改技能定义，而不是改提示词。这是 superpowers 方法论里很重要的一点：把改进沉淀到技能里，而不是沉淀到一次性的对话里。

我建议给每个技能加一个版本号和变更记录。改了什么、为什么改、改完之后哪个任务的质量提升了，都记下来。时间长了，这套技能库就成了你们团队智能体开发的核心资产。

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

5.1 智能体不调用技能，或者调用错技能

这是最高频的问题。排查顺序我整理成了一张表：

我遇到过一次典型情况：智能体在“写实现”和“写测试”之间反复横跳，写了实现又去写测试，写完测试又回来改实现。查下来是“写测试”的触发条件写成了“当有实现代码时”，而“写实现”的输出正好触发了这个条件。改成“当有实现代码且该代码尚未被测试覆盖时”，循环就断了。

5.2 技能组合后上下文丢失

技能多了之后，智能体在技能之间传递信息时容易丢上下文。比如“读规范”技能读到的规范内容，到“写实现”技能时已经不在上下文里了。

解决办法有两个。一是显式传递，在技能的输出契约里明确要求把关键信息写到一个共享的上下文文件里，下游技能从文件读。二是压缩传递，不传原始内容，传摘要。比如规范文档很长，读规范技能输出一份“规范要点清单”，写实现技能只读这份清单。我一般用第二种，token 消耗小，效果也够用。

5.3 技能执行结果不稳定

同一个技能，同样的输入，两次执行结果不一样。这在用大模型做执行引擎时很常见。缓解办法是在技能定义里加约束：明确输出格式、明确必须包含的字段、明确禁止的行为。约束越具体，结果越稳定。

还有一个技巧是加自检步骤。让技能在执行完主要步骤后，自己对照验收标准检查一遍，不通过就重试。这个自检步骤本身也可以是一个独立技能，叫“技能输出自检”，所有技能执行完都可以调用它。

注意：自检步骤会增加 token 消耗和执行时间，不要对所有技能都开。我一般只对“写实现”“写测试”这种关键技能开自检。

5.4 技能库越来越大，维护成本高

技能数量超过二十个之后，维护就成了问题。我的做法是分层管理：核心技能（每个任务都会用的）放一层，领域技能（特定类型任务用的）放一层，实验技能（还在验证的）放一层。核心技能改动要谨慎，领域技能按需加载，实验技能定期清理。

另外，定期做技能审计。把最近一个月没被调用过的技能找出来，要么删掉，要么改触发条件。技能库不是越大越好，能被正确调用的技能才有价值。

6. 我对 superpowers 这套框架的实际体会

用了一段时间之后，我最大的感受是：它把智能体开发从“调提示词”变成了“做工程”。以前优化智能体表现，靠的是不断改提示词、试不同说法，效果不稳定还不可复现。现在优化的是技能定义、技能组合、验收标准，每一次改动都有明确的依据和可验证的结果。

另一个体会是，这套框架对团队协作特别友好。技能定义是显式的、可 review 的、可版本管理的。团队里谁改了哪个技能、为什么改，一目了然。新人接手的时候，看一遍技能库就知道智能体在这个项目里是怎么工作的，不用去翻一堆聊天记录。

最后分享一个小技巧：刚开始搭技能库的时候，不要追求完美。先把你最痛的那个任务拆成三到五个技能，跑通一遍，感受一下组合的效果。跑通之后你自然就知道下一个技能该做什么了。我见过太多人一上来就想设计一套完整的技能体系，结果卡在定义阶段就放弃了。先跑起来，再迭代，这套东西的生命力在于用，不在于设计得多漂亮。