企业官网建设流程全解析

1. 为什么“会写代码”的 AI 助手，依然干不好一个完整项目

很多人第一次用 AI 编程助手，都会经历一个相似的兴奋期：让它写个排序算法、补个正则、生成一段 CRUD，响应又快又准，感觉效率直接翻倍。但只要你把任务放大一点——比如“帮我给这个项目加一个带权限校验的导出功能”——结果往往就开始失控：它可能只改了 controller 没动 service，可能漏掉了数据库迁移脚本，可能把测试文件写在了错误的目录，甚至在你没注意的时候删掉了一段看起来“没用”的旧代码。

问题不在于模型不够聪明，而在于我们一直在用“对话”的方式驱动一个本该用“工程流程”驱动的任务。软件工程这门学科发展了几十年，沉淀下来的需求分析、任务拆解、接口约定、测试先行、代码评审、回归验证，本质上都是为了对抗同一件事：复杂系统里人的认知负荷和随意性。AI 助手再强，如果每次都是“你问一句它答一句”，那它继承的恰恰是人类最随意的那一面，而不是工程最严谨的那一面。

Superpowers 这个框架想解决的，就是这个错位。它不是一个新模型，也不是一个 IDE 插件，而是一套给 AI 编程助手套上“软件工程套路”的约束层。核心思路是把 agent 的工作方式从“自由对话”改造成“按技能（skills）编排的流水线”：每个 skill 是一段被明确定义的能力单元，有输入、有输出、有触发条件、有验收标准，agent 在框架的调度下按顺序或按条件调用它们，而不是凭感觉自由发挥。

关键词里反复出现的agent、skills、agent 框架与编排、agent 开发，其实都指向同一个问题域：怎么让一个概率性的语言模型，表现出确定性的工程行为。Superpowers 给出的答案不是“祈祷模型更聪明”，而是“用结构约束它”。这套思路对前端开发、Python 软件工程、甚至软件工程课程设计都适用，因为工程流程本身是跨语言的。

这篇文章我会从实际落地的角度，把 Superpowers 的骨架拆开讲清楚：它到底约束了什么、skills 是怎么设计的、agent 编排的调度逻辑长什么样、安装和上手时最容易踩哪些坑，以及为什么“让 AI 按套路干活”这件事，比单纯换一个更强的模型更值得投入。适合已经用过 AI 编程助手、但被它的不稳定性折磨过的开发者，也适合正在做 agent 开发、想理解 skills 机制的人。

2. Superpowers 到底约束了 agent 的哪些行为

2.1 从“自由对话”到“技能流水线”的本质区别

要理解 Superpowers，先要理解普通 AI 编程助手的工作模式。你给它一个任务，它内部其实经历了一个隐式的规划过程：理解意图、回忆相关知识、生成代码、自我检查。这个过程是黑盒的，而且每一步都可能被上下文里的无关信息干扰。你前面聊了十句关于日志格式的话，它可能就把日志风格带进了完全不相关的模块里。

Superpowers 的做法是把这条隐式链路显式化。它定义了一组 skills，每个 skill 对应工程流程里的一个明确环节。比如“需求澄清”是一个 skill，“接口设计”是一个 skill，“写测试”是一个 skill，“实现”是一个 skill，“验证”又是一个 skill。agent 不再一次性把活干完，而是被框架引导着一个环节一个环节地推进，每个环节有明确的产出物。

这个区别听起来很抽象，但实际效果差异巨大。我拿一个真实场景对比过：让普通助手“给用户表加一个软删除字段”，它通常会直接给你一段 migration 加一段 model 改动，看起来没问题。但用 Superpowers 的流程走，它会先触发需求澄清 skill，问你“软删除后唯一索引怎么处理”“历史数据要不要回填”“查询默认过滤还是显式过滤”，然后才进入设计环节。这些问题是工程上必须回答的，但自由对话模式下模型几乎不会主动问，因为它被训练成“尽量给出答案”而不是“先确认边界”。

2.2 skills 的四个必备要素：触发、输入、动作、验收

skills 是 Superpowers 的核心抽象，但很多人一开始会把它理解成“提示词模板”，这是最大的误解。提示词模板是静态的文本，而一个合格的 skill 是一个带契约的能力单元。根据我在实际项目里的拆解，一个能稳定工作的 skill 至少要包含四个要素。

第一是触发条件。什么情况下这个 skill 应该被调用？是用户明确要求，还是前置 skill 完成后自动流转？触发条件写不清楚，agent 就会在错误的时机调用它，比如还没搞清楚需求就开始写实现。

第二是输入契约。这个 skill 需要哪些前置信息才能工作？比如“写测试”这个 skill，输入必须是已经确定的行为描述和接口签名，如果输入是模糊的“加个功能”，它产出的测试就是垃圾。

第三是动作定义。具体做什么，步骤是什么，有没有必须遵守的约束。这里最容易出问题的是约束写得太松，比如“生成符合规范的代码”，什么叫符合规范？模型会自己脑补一套。

第四是验收标准。这个 skill 的产出怎么算合格？是测试通过，还是人工确认，还是满足某个静态检查？没有验收标准的 skill，等于没有终点线。

我用一个表格把普通提示词和合格 skill 的差异列出来，这个对比是我自己在迁移旧提示词时总结的，非常直观：

2.3 为什么“约束”反而让 agent 更强

这里有个反直觉的点值得展开：给 agent 加约束，直觉上会限制它的能力，但实际结果是它在复杂任务上的成功率大幅提升。原因在于语言模型的失败模式不是“不会”，而是“不稳定”。同一个任务跑十次，可能有六次是对的，四次在某个环节跑偏。约束的作用是把那四次跑偏的概率压下去。

打个比方，一个技术很好的自由职业者，你让他直接上手一个大项目，他可能凭经验做得不错，但也可能漏掉关键环节。而一个成熟的工程团队，靠的是流程和 checklist，把“凭经验”变成“按步骤”。Superpowers 对 agent 做的事，就是给它配了一套 checklist 和流转规则。模型的能力没变，但它的行为被收敛到了工程上可预期的范围内。

这也是为什么关键词里“agent 安全”会和 skills 一起出现。一个不受约束的 agent，在自主执行时可能做出危险操作，比如误删文件、覆盖配置、执行破坏性命令。而 skills 的验收环节和显式契约，天然形成了一道检查网。你不能指望模型永远不犯错，但你可以让它在犯错之前被流程拦住。

3. 拆解一个 skill 的完整生命周期

3.1 触发阶段：什么时候该调用哪个 skill

skill 的触发是整个流水线的入口，也是最容易设计错的地方。我见过不少人的 skill 库，触发条件写得非常模糊，比如“当需要写代码时触发实现 skill”。问题是，agent 怎么判断“需要写代码”？它可能在你只是想讨论方案的时候就触发了实现，直接给你一堆代码，把讨论带偏。

比较可靠的做法是用前置产出物作为触发信号，而不是用模糊的意图判断。比如“实现 skill”的触发条件应该是“设计 skill 已产出接口签名和行为描述”，而不是“用户想写代码”。这样触发就变成了一个确定性的状态检查，而不是概率性的意图识别。

在 Superpowers 的编排里，触发通常有三种模式。第一种是显式触发，用户直接点名要某个 skill，适合调试和单点使用。第二种是链式触发，前一个 skill 完成后自动流转到下一个，这是流水线的核心。第三种是条件触发，满足某个条件才触发，比如“测试失败时触发修复 skill”。三种模式混用，才能覆盖真实项目的复杂度。

提示：设计触发条件时，尽量依赖“可验证的状态”而不是“语义判断”。状态是确定的，语义判断是概率的，后者会让你的流水线时灵时不灵。

3.2 执行阶段：skill 内部该怎么组织步骤

skill 被触发后，内部执行的组织方式决定了它的稳定性。我的经验是，一个 skill 内部的步骤不要超过五步，超过就拆成两个 skill。因为步骤越多，模型在中途丢失上下文或跳步的概率越高。

每个步骤应该包含三样东西：做什么、为什么做、做完的产出是什么。第三样最容易被忽略，但它恰恰是链式触发的基础。如果“需求澄清 skill”的产出只是一段对话，那下一个 skill 拿不到结构化的输入，流水线就断了。所以产出最好是结构化的，比如一份带字段的清单、一个接口签名、一组测试用例。

还有一个实操细节：skill 内部要显式声明“禁止行为”。比如实现 skill 里应该写明“禁止修改未在设计中提及的文件”“禁止删除已有测试”。这些禁止项看起来是常识，但模型在追求“完成任务”时经常会越界。显式写出来，能挡掉相当一部分意外操作。

3.3 验收阶段：怎么判断这个 skill 干完了

验收是 skill 生命周期里最被低估的环节。很多人设计 skill 时把精力全放在“怎么让它干活”上，验收随便写一句“检查结果是否正确”。结果就是 agent 自己觉得干完了，实际上产出根本不能用。

有效的验收要满足两个条件：可自动判定和有明确的失败处理。可自动判定意味着验收标准不能是“代码质量好”这种主观描述，而应该是“测试全部通过”“静态检查无错误”“接口签名与设计一致”这类机器能判断的条件。有明确的失败处理意味着验收不通过时，agent 知道该回退到哪一步，而不是硬着头皮往下走。

我自己的做法是给每个 skill 配一个验收清单，清单项要么是布尔判断，要么是数值阈值。比如“测试覆盖率不低于设计文档中列出的关键路径数”，这就是可判定的。验收不通过时，触发回退逻辑，通常是回到上一个 skill 重新产出，或者把问题抛给人工确认。

4. agent 编排：让多个 skill 协同工作的调度逻辑

4.1 串行、并行与条件分支的取舍

单个 skill 再强，也只能解决一个环节的问题。真正的价值在于把多个 skill 编排成一条能处理完整任务的流水线。编排的核心是调度逻辑，而调度逻辑无非三种：串行、并行、条件分支。

串行是最简单的，A 完成接 B，B 完成接 C。适合有严格先后依赖的环节，比如“需求澄清 → 设计 → 实现 → 测试”。串行的好处是逻辑清晰，坏处是慢，而且一旦中间某步卡住，整条线都停。

并行适合相互独立的环节。比如“前端实现”和“后端实现”在接口约定好之后可以并行推进，“写文档”和“写测试”也可以并行。并行的难点在于汇合点的处理，两个并行分支都完成后，怎么合并产出、怎么解决冲突，需要额外的合并 skill。

条件分支适合有判断逻辑的场景。比如“如果测试失败，走修复分支；如果通过，走部署分支”。条件分支的关键是条件本身要可判定，不能是“如果代码看起来有问题”这种模糊判断。

实际项目里这三种往往是混用的。一条典型的流水线可能是：需求澄清（串行）→ 设计（串行）→ 前后端实现（并行）→ 汇合验证（串行）→ 测试（串行）→ 失败则修复分支（条件）。编排的复杂度就体现在这些组合上。

4.2 上下文在 skill 之间怎么传递

编排里最隐蔽的坑是上下文传递。每个 skill 执行完都会产生一堆信息，下一个 skill 需要哪些、不需要哪些，如果不加控制，上下文会迅速膨胀，最后模型被无关信息淹没，行为开始漂移。

我的做法是只传递结构化产出，不传递过程对话。比如设计 skill 产出的是一份接口文档，那传给实现 skill 的就只有这份文档，设计过程中讨论过的备选方案、被否决的思路，全部丢弃。这样每个 skill 拿到的输入都是干净、聚焦的。

另一个技巧是给上下文设大小上限。当传递的内容超过某个阈值时，强制做一次摘要压缩。这个阈值需要根据模型的实际表现调，我一般从比较保守的值开始试，观察 skill 的产出质量，质量下降就说明上下文被稀释了，需要收紧。

注意：上下文传递是流水线稳定性的命门。我踩过的最大的坑就是让所有 skill 共享一个全局上下文，结果跑到第五六个 skill 时，模型开始把前面讨论过的废弃方案又捡回来用。后来改成显式传递结构化产出，问题立刻消失。

4.3 失败重试与人工介入的边界

再好的流水线也会失败，关键是失败之后怎么办。无脑重试是最差的选择，因为如果失败原因是输入有问题，重试一百次还是失败，只是浪费 token。

合理的策略是区分可重试失败和不可重试失败。可重试的比如网络抖动、临时性的格式错误，重试一两次通常能过。不可重试的比如需求本身矛盾、设计有逻辑漏洞，这种必须回退到上游 skill 或者交给人工。

人工介入的边界也要提前定好。我的原则是：涉及不可逆操作、涉及关键决策、连续失败超过阈值，这三种情况必须暂停等人工确认。不可逆操作比如删数据、改配置；关键决策比如技术选型、架构调整；连续失败比如同一个 skill 三次没过验收。把这三条写进编排规则里，能避免 agent 在错误方向上越走越远。

5. 上手 Superpowers 时最容易踩的几个坑

5.1 把 skills 写成“万能提示词”

新手最容易犯的错，是把 skill 写成一个包罗万象的提示词，恨不得一个 skill 解决从需求到部署的所有事。这种 skill 看起来强大，实际完全不可控，因为它的行为空间太大，模型在里面怎么发挥都有可能。

正确的做法是一个 skill 只干一件事，而且这件事要小到能被清晰验收。“写一个函数”比“实现一个模块”好，“实现一个模块”比“完成一个功能”好。skill 越小，触发条件越明确，验收越容易，复用性也越高。我现在的习惯是，如果一个 skill 的描述超过一屏，就说明它该拆了。

5.2 忽略 skill 之间的依赖声明

第二个坑是不写依赖声明，导致 skill 被乱序调用。比如实现 skill 依赖设计 skill 的产出，但你没声明这个依赖，编排器可能在设计还没完成时就触发了实现，结果实现 skill 拿不到接口签名，只能瞎猜。

依赖声明要显式写出来，包括依赖哪个 skill、依赖它的哪个产出、依赖不满足时怎么办。这三样缺一不可。依赖不满足时的处理通常是阻塞等待或者报错，绝对不能让它“尽力而为”，因为尽力而为的结果就是产出不可用。

5.3 验收标准写得太“软”

第三个坑是验收标准写得太软，比如“代码应该清晰易读”“测试应该覆盖主要场景”。这种标准机器没法判定，最后只能靠人肉看，流水线就退化成了半自动。

验收标准要往硬里写。“清晰易读”改成“通过项目的 lint 规则且无警告”，“覆盖主要场景”改成“设计文档中列出的每个行为都有对应的测试用例且全部通过”。硬标准的好处是 agent 能自己判断过没过，不过就自动回退，不需要人盯着。

5.4 一开始就追求全自动

最后一个坑是新手总想一步到位搞全自动流水线，结果每个环节都不稳，整条线跑十次失败八次，最后放弃。我的建议是从半自动开始，先让每个 skill 单独跑通，再逐步串联。

具体路径是：先手动触发单个 skill，确认它的产出质量稳定；然后把两个有依赖关系的 skill 串起来，确认上下文传递没问题；再逐步加长流水线，每加一个环节就压测一轮。这个过程慢，但每一步都扎实。等流水线稳定了，再考虑加条件分支和并行。跳过这个渐进过程直接上全自动，基本都会翻车。

6. 从软件工程视角看 skills 设计的几条硬规则

6.1 单一职责在 skill 上的落地

软件工程里的单一职责原则，放到 skill 设计上同样成立，而且更重要。因为 skill 是 agent 的行为单元，一个 skill 承担太多职责，它的触发条件、输入契约、验收标准都会变得模糊，最终导致整个流水线不可控。

落地的时候，判断一个 skill 是否职责单一，可以问三个问题：它能不能用一句话说清楚做什么？它的输入是不是来自单一来源？它的验收是不是单一判定？三个都是“是”，才算合格。有一个“否”，就该考虑拆分。

拆分的方向通常是按产出物类型拆，而不是按步骤拆。比如“生成代码”和“生成测试”是两个产出物，应该拆成两个 skill，而不是把“写代码然后写测试”塞进一个 skill。按产出物拆的好处是每个 skill 的验收标准天然清晰。

6.2 接口契约先于实现

这条规则来自软件工程的接口先行思想。在 Superpowers 里，意味着设计 skill 的产出必须先于实现 skill 的执行，而且设计产出要是结构化的、可被机器解析的契约，不能是一段散文式的描述。

契约的形式可以是接口签名、数据结构定义、行为清单。关键是它要足够精确，精确到实现 skill 不需要再做任何语义解读就能直接干活。如果实现 skill 还需要“理解”设计产出，那说明契约不够精确，中间还有信息损失。

我自己的做法是让设计 skill 产出一份带字段的清单，每个字段对应一个行为或一个接口。实现 skill 逐字段消费，消费完一个标记一个。这样既保证了契约的精确性，也让进度可追踪。

6.3 可测试性是 skill 的准入条件

最后一个硬规则是：一个 skill 如果没法被测试，就不该进入流水线。这里的测试不是指测试代码，而是指这个 skill 的产出能不能被自动验证。不能自动验证的 skill，等于流水线上的一个黑盒，你不知道它什么时候会出问题。

可测试性的前提是产出结构化。一段自由文本很难测试，但一份带字段的清单、一组测试用例、一个接口签名，都是可测试的。所以设计 skill 时，要优先考虑“产出能不能被下一个环节自动消费和验证”，而不是“产出读起来顺不顺”。

这条规则还有个延伸：skill 本身也应该有回归测试。当你修改一个 skill 的定义时，应该有一组固定的输入和期望产出，用来验证修改没有破坏原有行为。这在 skill 库变大之后尤其重要，否则改一个 skill 可能悄悄影响整条流水线。

7. 我在实际项目里跑通流水线后的几点体会

真正把 Superpowers 这套东西跑起来之后，最大的感受是：AI 编程助手的瓶颈从来不在模型能力，而在我们怎么组织它的工作。同一个模型，自由对话模式下干复杂任务的成功率可能只有一半，套上 skills 流水线之后能稳定到八成以上。这个提升不是模型变强了，而是它的行为被工程流程收敛了。

另一个体会是，skill 库是需要持续维护的资产。一开始你可能只有五六个 skill，跑着跑着会发现某些场景反复出问题，那就该补一个新 skill 或者改一个旧 skill。这个过程很像团队里沉淀 checklist 和规范文档，越用越厚，越厚越稳。别指望一次设计到位，迭代才是常态。

还有个很实际的点：不要追求 skill 的通用性，要追求它的场景适配性。我早期总想设计一个“什么项目都能用”的实现 skill，结果它对哪个项目都不好用。后来改成针对具体技术栈、具体项目结构设计 skill，虽然复用范围窄了，但每个 skill 的稳定性大幅提升。通用性交给编排层去解决，skill 层就该专注把一件事做到极致。

最后分享一个小技巧：给每个 skill 加一个**“自检问题”字段**，让 agent 在执行完 skill 后自己回答几个问题，比如“我有没有修改设计之外的文件”“我的产出是否满足验收清单的每一项”。这个自检动作成本很低，但能挡掉不少低级错误。我加了这个字段之后，流水线的返工率明显下降。