企业官网建设流程全解析

规范驱动开发这两年重新火起来，不是因为大家突然爱上了写文档，而是因为 AI 编码助手把"需求描述"这件事的杠杆率放大了十倍。以前你写一份模糊的 spec，最多是同事多问你两句；现在你写一份模糊的 spec，AI 会自信满满地给你生成三百行看起来能跑、实际上边界条件全错的代码。所以问题从"要不要写规范"变成了"用什么样的工具链来写规范、管理规范、让规范真正驱动开发和验证"。

Spec Kit、Superpowers、OpenSpec 这三个名字最近在工程社区里被反复提起，我把它们放在一起称为"规范驱动开发三剑客"。它们不是同一层的东西，也不是互相替代的关系，但很多人第一次接触时会混淆：有人以为都是 prompt 模板库，有人以为都是文档生成器，还有人直接拿其中一个去套另一个的场景，结果用得很别扭。这篇内容我会从设计哲学、核心机制、目录结构、实操流程、适用边界几个维度把它们拆开讲清楚，最后给出一套可落地的选型判断方法。适合正在把 AI 编码引入团队流程的工程师、技术负责人，以及想搞清楚"规范驱动"到底怎么落地的人。

1. 三剑客到底在解决什么问题

1.1 从"提示词工程"到"规范工程"的转变

早期大家用 AI 写代码，靠的是一段精心打磨的 prompt，把需求、约束、示例塞进去，然后祈祷模型输出符合预期。这种做法在单文件、单函数级别还能凑合，一旦涉及多模块协作、跨会话迭代、多人共享上下文，就立刻崩盘。原因很简单：prompt 是一次性的、易失的、无法版本化的，而软件需求是持续的、演进的、需要追溯的。

规范驱动开发的核心主张是：把"给 AI 的输入"从临时 prompt 升级为持久化的、结构化的、可版本控制的规范文档。这份规范不只是给人看的说明书，更是 AI 生成代码、生成测试、做代码审查时的唯一事实来源。Spec Kit、Superpowers、OpenSpec 都在这个理念下工作，但各自切入的角度完全不同。

我打个比方：如果把规范驱动开发比作盖房子，Spec Kit 更像是给你一套标准化的施工图纸模板和验收清单，Superpowers 像是给施工队配了一套能自动理解图纸并分阶段作业的工头系统，OpenSpec 则像是把图纸、变更记录、验收标准统一进一个可查询的档案库。三者可以共存，但解决的问题层次不一样。

1.2 三个工具的核心定位差异

先把定位说清楚，后面展开才不会乱。

Spec Kit 关注的是"规范长什么样、怎么从需求推导出可执行任务"；Superpowers 关注的是"AI 拿到规范后按什么技能、什么顺序去干活"；OpenSpec 关注的是"规范怎么存、怎么改、怎么追溯"。理解了这个分层，你就不会拿 OpenSpec 去做任务拆解，也不会拿 Spec Kit 去做变更归档。

1.3 为什么现在值得认真对待

一个现实原因是 AI 编码的上下文窗口虽然在变大，但"有效上下文"并没有同比提升。你把整个代码库塞进去，模型反而更容易迷失重点。规范的作用就是做上下文压缩：把"这个系统应该怎么工作"提炼成一份高信噪比的文档，让 AI 每次只需要读规范加相关代码片段，就能做出正确决策。

另一个原因是团队协作。当多个开发者各自用 AI 生成代码时，如果没有统一的规范约束，代码风格、接口约定、错误处理策略会迅速发散。规范驱动开发把"约定"前置到文档层，AI 生成时自动对齐，review 时也有据可依。这三个工具本质上都在降低"AI 自由发挥"带来的熵增。

2. Spec Kit 深度拆解：规范模板与任务推导

2.1 设计哲学：把需求变成可执行的任务链

Spec Kit 的核心思路是"规范即任务源"。它不满足于让你写一份描述性文档，而是要求你把规范写成可以被逐步拆解为任务的形式。它的典型工作流是：先写一份高层级的 spec，描述系统要做什么、边界在哪、验收标准是什么；然后基于这份 spec 生成任务清单；最后每个任务对应一次具体的实现动作。

这种设计的精妙之处在于，它强制你在写规范时就考虑"这件事怎么被验证"。很多团队的规范文档之所以没用，就是因为写得太虚，全是"系统应该高效稳定"这种无法验证的话。Spec Kit 的模板会逼你回答：输入是什么、输出是什么、异常情况怎么处理、怎么判断做完了。这些问题回答清楚了，AI 生成代码的准确率会显著提升。

2.2 目录结构与文件组织

Spec Kit 通常会在项目里建立一个专门的规范目录，按功能模块或特性划分。一个常见的组织方式是这样的：

specs/ features/ 001-user-auth/ spec.md # 需求规范 plan.md # 实现计划 tasks.md # 任务清单 ># 技能名称：新增 REST 端点 ## 触发条件 - 任务涉及创建新的 HTTP 接口 - 涉及路由注册和请求处理 ## 前置检查 - 确认是否已有相似端点可复用 - 确认认证和权限要求 ## 执行步骤 1. 在路由文件中注册路径和方法 2. 创建处理函数，遵循项目错误处理约定 3. 定义请求和响应的数据结构 4. 补充输入校验 5. 编写单元测试和集成测试 ## 完成定义 - 端点可被调用并返回预期结构 - 异常输入返回正确错误码 - 测试覆盖正常和异常路径 ## 常见错误 - 忘记处理空输入 - 错误码与项目约定不一致 - 缺少权限校验

写技能包的关键是"可执行"。每一条都要是具体动作，不能是"注意代码质量"这种空话。我建议技能包由团队里最熟悉这块的人来写，写完让 AI 实际跑一遍，看它能不能按步骤执行，跑不通就说明描述不够具体。

3.3 工作流编排与阶段衔接

Superpowers 的另一个重点是编排。单个技能解决单点问题，但真实开发是多个技能串联的。比如一个完整的功能开发可能是：需求分析技能 → 数据建模技能 → 接口设计技能 → 实现技能 → 测试技能 → 文档技能。Superpowers 允许你定义这些技能的触发顺序和衔接条件。

这里有个设计取舍：编排太松，AI 会跳步；编排太紧，遇到特殊情况无法变通。我的经验是给关键节点设强制检查，比如"测试未通过不得进入文档阶段"，其他环节允许 AI 根据实际情况调整顺序。强制检查点不要超过三个，否则流程会变得僵硬。

3.4 实操心得与边界

Superpowers 最适合的场景是重复性高、标准明确的开发任务。比如 CRUD 接口、数据迁移、测试补充，这些用技能包约束后，AI 的输出质量会稳定很多。但它不适合探索性任务，比如架构设计、性能调优，这些需要灵活判断，硬套技能反而限制发挥。

还有一个实际问题是技能包的维护成本。项目演进后，原来的技能可能过时了，如果不及时更新，AI 会按老套路生成代码。我的做法是每个季度做一次技能包审查，结合最近的 bug 记录看哪些技能需要修订。这个投入是值得的，因为技能包一旦写好，团队所有人的 AI 输出都会受益。

4. OpenSpec 深度拆解：规范与变更的集中治理

4.1 设计哲学：规范是一等公民，变更是可追溯事件

OpenSpec 的定位最偏"治理"。它把规范当作项目的核心资产来管理，强调规范的版本化、变更的可追溯、以及规范与代码的对应关系。如果说 Spec Kit 关注"怎么写规范"，Superpowers 关注"怎么按规范干活"，那 OpenSpec 关注的是"规范怎么长期活下去"。

它的核心机制是"变更提案"。任何对系统的修改，都要先提一份变更提案，说明改什么、为什么改、影响哪些规范、怎么验证。提案通过后才进入实现。这个流程听起来像重型流程，但 OpenSpec 把它做得足够轻，不至于拖慢开发。

4.2 规范库的组织与检索

OpenSpec 通常维护一个集中的规范库，按领域或子系统组织。和 Spec Kit 按特性分文件夹不同，OpenSpec 更强调规范的稳定标识和交叉引用。一个规范条目有唯一 ID，可以被其他规范、变更提案、代码注释引用。

openspec/ specs/ auth/ SPEC-AUTH-001.md # 登录流程规范 SPEC-AUTH-002.md # 权限模型规范 order/ SPEC-ORDER-001.md changes/ 2024-001-add-sso/ proposal.md impact.md tasks.md archive/ 2023-012-remove-legacy-auth/

这种结构的价值在于检索和追溯。当你想知道某个规范为什么是现在这样，可以顺着变更记录一路回溯。当你要改某个规范，能立刻看到它被哪些地方引用，评估影响范围。

4.3 变更提案的完整流程

OpenSpec 的变更流程一般是这样走的：

1. 提出提案：写清楚动机、目标、非目标、影响范围。
2. 影响分析：列出受影响的规范条目、代码模块、接口契约。
3. 规范修订：更新相关规范文档，标注变更点。
4. 任务拆解：把实现工作拆成可执行任务。
5. 实现与验证：按任务实现，对照规范验证。
6. 归档：变更完成后，提案移入归档，规范成为新基线。

这个流程的关键是"影响分析"这一步。很多团队改需求时只想着新功能，忽略了它对既有规范的冲击，结果改完之后系统内部不一致。OpenSpec 强制你做影响分析，虽然多花点时间，但省下了后期排查不一致的成本。

4.4 适用场景与落地建议

OpenSpec 适合规范数量多、变更频繁、需要多人协作的中大型项目。小项目用它可能觉得重，因为提案流程本身有开销。判断标准是：如果你经常遇到"这个规范什么时候改的、为什么改"这类问题，就说明需要 OpenSpec 了。

落地时我建议渐进式推进。先选一个子系统试点，把它的规范整理进 OpenSpec，跑几个变更周期，看看流程是否顺畅。顺畅了再推广到其他子系统。一上来就全量迁移，很容易因为流程不熟而卡住。

5. 三剑客的协同与选型决策

5.1 三者能否共存，怎么组合

完全可以共存，而且组合使用往往效果更好。一个常见的组合是：用 Spec Kit 做需求到任务的推导，用 Superpowers 约束 AI 的执行过程，用 OpenSpec 管理规范的长期演进。三者各管一段，衔接点是规范文档本身。

具体来说，Spec Kit 产出的 spec.md 可以作为 OpenSpec 规范库的输入，经过规范化后入库。Superpowers 的技能包在执行时读取 OpenSpec 里的规范作为约束。变更发生时，OpenSpec 的提案流程触发 Spec Kit 的任务重新推导，Superpowers 按新任务执行。这样形成闭环。

5.2 选型判断的四个维度

选型不要看哪个火，要看你的实际痛点。我总结四个判断维度：

如果你的核心问题是"不知道怎么把需求讲清楚给 AI"，先上 Spec Kit。如果是"AI 每次生成的东西都不一样"，先上 Superpowers。如果是"规范越积越多、没人知道哪份是最新的"，先上 OpenSpec。

5.3 渐进式引入的实操路径

我的建议是分三步走。第一步，先用 Spec Kit 把当前最痛的一个特性的规范写清楚，跑通"规范到任务到实现"的链路，建立信心。第二步，针对这个特性里重复性最高的开发动作，写两三个 Superpowers 技能包，观察 AI 输出的一致性是否提升。第三步，当规范数量超过十份、开始出现版本混乱时，引入 OpenSpec 做集中管理。

每一步之间留出至少两周的观察期，收集实际使用中的问题。不要三个一起上，那样出了问题你分不清是哪个环节的锅。渐进式引入的另一个好处是团队适应成本低，每次只学一个新东西。

5.4 常见误区与避坑清单

第一个误区是把规范驱动当成"写更多文档"。规范驱动的目标是减少无效沟通和返工，如果文档量增加了但返工没减少，说明方向错了。第二个误区是追求规范的大而全，一上来就想把所有东西都规范掉，结果规范本身成了负担。应该从最痛的点切入，逐步扩展。

第三个误区是忽略规范的执行验证。规范写了但没人检查代码是否符合，那规范就是摆设。要把规范符合性纳入 review 和 CI，比如用 lint 规则检查接口命名是否符合规范约定。第四个误区是工具选型跟风，看别人用 OpenSpec 就上 OpenSpec，结果自己项目根本没那么多变更要管，白白增加流程开销。

6. 落地中的问题排查与经验沉淀

6.1 规范与代码不一致怎么排查

这是最常见的问题。排查思路是先从代码反推规范，看代码实际行为是什么，再对照规范看差异在哪。如果差异是代码错了，修代码；如果差异是规范过时了，修规范。关键是建立"发现不一致就立即处理"的机制，不要攒着。

我通常会在 CI 里加一个检查：对关键接口，用规范里定义的契约生成测试用例，跑不过就说明代码和规范不一致。这个检查能拦住大部分漂移。

6.2 AI 不按规范执行的应对

有时候规范写得很清楚，AI 还是不按规范来。原因通常有三个：规范太长，关键约束被淹没；规范表述有歧义；规范没有在合适的时机被喂给 AI。对应的解法是：把关键约束前置到规范开头；用具体例子替代抽象描述；在技能包里显式引用规范条目。

我实测下来，把规范里的"必须"和"禁止"用加粗标出来，AI 的遵守率会明显提升。另外，规范条目尽量短，一条只说一件事，长条目拆开。

6.3 团队协作中的规范冲突

多人协作时，不同人对规范的理解可能不一致，导致冲突。解法是建立规范评审机制，重要规范变更需要至少一人 review。评审时重点看：变更动机是否合理、影响范围是否分析清楚、是否有遗漏的关联规范。

还有一个技巧是给规范加"负责人"字段，每条规范有明确的维护者。出问题时能找到人，也避免规范无人维护而腐化。

6.4 长期维护的节奏建议

规范库需要定期维护，否则会变成技术债。我建议的节奏是：每周花半小时处理本周发现的规范问题；每月做一次规范一致性检查；每季度做一次规范库整体审查，清理过时条目，合并重复内容。

这个投入看起来不少，但相比规范腐化后带来的沟通成本和返工成本，是划算的。规范库健康了，AI 生成的代码质量才稳定，团队协作才顺畅。

最后分享一个我自己的体会：规范驱动开发最难的不是工具，而是习惯。团队要习惯"先写规范再动手"，要习惯"改代码同步改规范"，要习惯"用规范而不是记忆来对齐"。工具能降低习惯养成的门槛，但习惯本身得靠人坚持。三剑客里，Spec Kit 帮你起步，Superpowers 帮你稳定，OpenSpec 帮你持久，选哪个先上，取决于你现在最缺哪一环。