企业官网建设流程全解析

1. 从“想到哪写到哪”到“先立规矩再动手”：SDD 到底在解决什么问题

如果你带过三人以上的研发小组，大概率经历过这种场面：需求评审会上大家点头如捣蒜，散会之后各写各的代码，等到联调那天才发现，前端理解的“用户中心”和后端实现的“用户中心”压根不是同一个东西。接口字段对不上、状态码各玩各的、边界条件全靠猜。最后只能拉个群，一边吵架一边改，改完还没人记得当初为什么这么定。

Spec-kit就是冲着这个场景来的。它是一套围绕SDD（Spec-Driven Development，规范驱动开发）理念打造的工程化工具，核心形态是一个CLI命令行工具。你可以把它理解成“给研发流程装了一个规范编译器”：先把需求、接口、数据模型、验收标准写成结构化的规范文件，再由工具去校验、生成、串联，让规范从“文档里的摆设”变成“流程里的硬约束”。

它适合谁？我梳理了三类人。第一类是中小团队的技术负责人，人不多但项目杂，急需一套轻量又不失严谨的流程把大家拧成一股绳；第二类是独立开发者或外包接单的兄弟，一个人要顶一个团队，最怕需求反复横跳，规范能帮你把变更成本压下来；第三类是刚入行的工程师，还没形成工程化思维，跟着 Spec-kit 的规范走一遍，比看十篇“如何写好代码”的文章都管用。

这篇文章我不打算复述官方文档，而是按我实际落地的顺序，把 Spec-kit 的设计思路、核心细节、实操流程和踩过的坑，一层层拆给你看。看完你至少能做到两件事：知道 SDD 为什么值得投入，以及能用 Spec-kit 在自己的项目里跑通一条最小闭环。

2. 内容整体设计与思路拆解：为什么是“规范驱动”而不是“文档驱动”

2.1 文档驱动开发为什么总是烂尾

先说个扎心的事实：绝大多数团队的“文档”活不过两周。需求文档写完就锁进网盘，接口文档靠 Swagger 自动生成但没人维护注释，设计文档更是评审完就再也没人打开。问题不在于大家懒，而在于文档和代码之间没有强制关联——文档写错了不影响编译，代码改了不更新文档也没人报警。这种“弱耦合”注定文档会腐烂。

SDD 的思路完全不同。它把规范（Spec）当成一等公民，和代码放在同一个仓库里，用同一套版本控制管理，并且通过工具链让规范具备“可校验、可生成、可追溯”的能力。换句话说，规范不再是给人看的散文，而是机器也能读的结构化契约。Spec-kit 就是把这套理念工程化的那双手。

我打个比方。传统文档像贴在墙上的“施工须知”，工人爱看不看；SDD 的规范像建筑施工图上的尺寸标注，你砌墙的时候必须对着它来，偏了一厘米监理就能查出来。Spec-kit 扮演的就是那个“监理+绘图仪”的角色。

2.2 Spec-kit 的三层结构设计

我把 Spec-kit 的体系拆成三层来理解，这样你在选型和落地时不容易迷路。

第一层是规范定义层。这一层解决“规范长什么样”。Spec-kit 通常约定用 YAML 或 JSON 这类结构化格式来描述实体、接口、字段、约束和验收条件。为什么不用 Markdown？因为 Markdown 对人友好但对机器不友好，你没法可靠地从一段自然语言里提取出“这个字段必填且长度不超过 32”。结构化格式虽然写起来啰嗦一点，但换来的是可校验、可 diff、可生成。

第二层是校验与生成层。这是 Spec-kit 作为 CLI 工具的核心价值。它读取规范文件，做一致性校验（比如接口引用的实体是否存在、字段类型是否冲突），然后按模板生成代码骨架、类型定义、接口桩、测试用例甚至数据库迁移脚本。这一层把“规范”翻译成了“可执行的产物”。

第三层是流程集成层。规范校验和生成要嵌入到日常研发动作里，比如提交代码前跑一次校验、CI 流水线里加一道规范检查、代码评审时对比规范变更。没有这一层，Spec-kit 就只是个玩具；有了这一层，它才真正成为工程化工具。

2.3 为什么选 CLI 而不是 IDE 插件或 Web 平台

热词里CLI出现频率很高，这不是偶然。Spec-kit 选择 CLI 形态，我认为有三个务实考量。

一是可组合性。CLI 天然适合管道操作和脚本编排，你可以把spec-kit validate塞进 Git hooks，把spec-kit generate接在 CI 的构建步骤里，这种灵活性是 IDE 插件给不了的。二是低侵入性。团队里有人用 VS Code，有人用 JetBrains，有人就爱 Vim，CLI 对编辑器中立，不会绑架你的工具链。三是易自动化。任何需要“人手动点一下”的环节，在工程化里都是隐患，CLI 让规范检查变成无人值守的流水线环节。

提示：如果你团队已经在用 codex cli、claude cli 这类 AI 辅助命令行工具，Spec-kit 的 CLI 形态能和它们很好地共存——一个负责规范约束，一个负责代码生成建议，分工明确不打架。

2.4 方案选型时我踩过的认知坑

我一开始觉得 SDD 太重，小项目没必要。后来发现恰恰相反：项目越小、人越少，越经不起需求变更的折腾。大团队有专职 PM 和架构师兜底，小团队全靠个人记忆，规范就是那个“外置的大脑”。

另一个坑是“规范要写得多细”。我的经验是：规范写到能生成代码骨架和校验接口契约就够了，别试图把业务逻辑也写进去。规范管的是“形状”和“约束”，不是“算法”。把规范写成伪代码，维护成本会爆炸。

3. 核心细节解析与实操要点：规范文件到底怎么写才不返工

3.1 规范文件的目录组织

Spec-kit 落地第一步是定目录结构。我推荐按“领域-模块”两级来组织，而不是按“前端/后端”这种技术维度切。原因很简单：规范描述的是业务契约，业务契约不该因为技术栈变化而重写。

一个我实际用过的结构长这样：

specs/ user/ entity.yaml # 用户实体定义 api.yaml # 用户相关接口契约 acceptance.yaml # 验收条件 order/ entity.yaml api.yaml acceptance.yaml shared/ types.yaml # 公共类型与枚举 errors.yaml # 统一错误码

shared目录很关键。很多团队规范写崩，就是因为每个模块各定义一套“状态枚举”，最后status: 1在不同接口里含义不同。把公共类型抽出来统一管理，是避免规范内耗的第一道防线。

3.2 实体定义的关键字段与约束

实体定义是规范的基石。我以用户实体为例，讲清楚哪些字段必须写、为什么。

entity: User description: 平台注册用户 fields: - name: id type: string format: uuid required: true immutable: true - name: email type: string required: true unique: true pattern: "^[^@]+@[^@]+\\.[^@]+$" - name: nickname type: string required: true minLength: 2 maxLength: 32 - name: status type: enum ref: shared.UserStatus required: true default: active - name: createdAt type: datetime required: true immutable: true

这里有几个细节值得展开。immutable: true标记不可变字段，Spec-kit 在生成更新接口时会自动排除这些字段，避免你手滑写出“允许修改 id”这种接口。ref引用公共枚举，保证状态值全局一致。pattern用正则约束格式，校验阶段就能拦住脏数据。

注意：正则里的反斜杠在 YAML 里要转义，写成\\.。我第一次写的时候没转义，校验直接报解析错误，排查了半小时才发现是 YAML 语法问题，不是 Spec-kit 的锅。

3.3 接口契约的写法与常见误区

接口契约是规范里最容易写歪的部分。我的原则是：只描述契约，不描述实现。看个例子。

api: CreateUser method: POST path: /api/v1/users request: body: ref: user.UserCreateInput response: success: code: 201 body: ref: user.User errors: - ref: shared.ValidationError - ref: shared.DuplicateEmailError

误区一：把 HTTP 状态码和业务错误码混为一谈。我建议code只放 HTTP 语义状态，业务错误用errors里的错误码表达，两者分离，前端处理起来才清晰。

误区二：响应体直接内联字段而不引用实体。内联会导致同一个实体在十个接口里重复定义十遍，改一个字段要改十处。用ref引用，一处修改全局生效。

误区三：忽略错误契约。很多团队只写成功响应，错误全靠口头约定。Spec-kit 的校验能强制你声明错误类型，这逼着团队提前想清楚“失败了怎么办”，价值极大。

3.4 验收条件的结构化表达

验收条件（acceptance）是 SDD 区别于普通接口文档的灵魂。它把“这个功能算不算做完”变成可校验的条目。

acceptance: CreateUser scenarios: - name: 正常创建 given: 邮箱未被注册 when: 提交合法用户信息 then: 返回 201 且用户状态为 active - name: 邮箱重复 given: 邮箱已存在 when: 提交相同邮箱 then: 返回 DuplicateEmailError - name: 昵称过短 given: 昵称为 1 个字符 when: 提交请求 then: 返回 ValidationError

这种 Given-When-Then 结构看着像测试用例，实际上它就是。Spec-kit 可以基于这些场景生成测试骨架，你只需要填充断言细节。规范写得好，测试就完成了一半，这是我用下来最爽的一点。

3.5 规范版本与代码版本的绑定策略

规范改了，代码没跟上怎么办？我的做法是规范文件和代码同仓库、同分支、同 PR。任何修改接口的代码提交，必须同时修改对应规范文件，否则 CI 的规范校验会失败。这条规则听起来严，但执行两周后团队就习惯了，而且再也没出现过“接口偷偷改了没通知前端”的事故。

具体实现上，在 CI 里加一步：对比本次提交的代码变更路径和规范变更路径，如果代码动了api相关目录但规范没动，直接 fail。这个检查用几十行脚本就能写，收益极高。

4. 实操过程与核心环节实现：从零跑通一条最小闭环

4.1 环境准备与 CLI 安装

Spec-kit 作为 CLI 工具，安装方式通常走包管理器。以常见的 Node 生态为例，全局安装后即可在任意目录调用。

npm install -g spec-kit spec-kit --version

如果你在 Mac 上，用 Homebrew 或 npm 都行，我实测 npm 版本更新更及时。安装完先跑spec-kit init，它会在当前目录生成一个specs/骨架和一份spec.config.yaml配置文件。

spec-kit init --template standard

--template参数决定生成的规范模板风格，standard适合大多数业务系统，minimal适合快速验证。我建议第一次用standard，把模板里的注释都读一遍，比看文档快。

提示：如果你同时装了 codex cli 或 claude cli，注意别让它们的全局命令和 spec-kit 冲突。我遇到过 PATH 顺序问题导致spec-kit调到了别的工具，用which spec-kit确认一下路径就好。

4.2 编写第一份规范并校验

初始化完成后，编辑specs/user/entity.yaml，写入上一节讲的用户实体。然后跑校验：

spec-kit validate specs/user/entity.yaml

校验通过会输出类似OK: 1 entity, 0 errors, 0 warnings。如果报错，它会精确指出行号和问题类型，比如line 12: field 'status' references unknown enum 'shared.UserStatus'。这时候你就知道该去shared/types.yaml里补枚举定义了。

校验这一步我强烈建议每写几行就跑一次，别攒一大堆再校验。规范文件的错误往往有连锁反应，早发现早修，比最后一次性排错省时间。

4.3 生成代码骨架与类型定义

校验通过后，进入生成环节：

spec-kit generate --target typescript --out ./src/generated

这条命令会根据规范生成 TypeScript 类型定义、接口桩和校验函数。生成的类型定义直接对应实体字段，接口桩里已经带好了请求/响应的类型约束。你不需要手写这些样板代码，也就不会出现“类型定义和接口文档不一致”的经典问题。

生成产物我建议纳入版本控制但标记为 generated，在文件头加注释说明“此文件由 Spec-kit 生成，请勿手动修改”。这样既方便 code review 时看到变更，又避免有人手改后被下次生成覆盖。

4.4 接入 CI 流水线

最小闭环的最后一步是自动化。在 CI 配置里加两个步骤：

steps: - name: validate specs run: spec-kit validate specs/ --strict - name: check spec-code sync run: spec-kit check-sync --code ./src --spec ./specs

--strict让警告也变成错误，适合成熟项目。check-sync检查代码里引用的类型和规范是否一致，防止有人绕过规范直接改代码。这两步加上去，规范就从“自觉遵守”变成了“强制约束”。

4.5 参数计算：规范覆盖率怎么量化

工程化讲究可度量。我给团队定了一个规范覆盖率指标：被规范覆盖的接口数除以总接口数。计算方式很简单，Spec-kit 的stats命令能直接输出。

spec-kit stats --format json

输出里会有coveredApis、totalApis、coverage三个字段。我们的目标是核心业务接口覆盖率 100%，边缘接口 80% 以上。这个指标每周在站会上过一遍，比空喊“大家要写规范”有用得多。

注意：覆盖率不是越高越好。有些一次性脚本、内部调试接口没必要写规范，硬写反而增加维护负担。把精力集中在会被多方依赖的接口上。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

5.1 规范校验通过但生成代码报错

这是最常见的问题。原因通常是规范语义正确但生成模板不兼容。比如你用了某个自定义类型，校验阶段只检查类型是否存在，但生成阶段模板不认识这个类型，就会报错。

排查思路：先看生成器的日志，它会指出哪个模板、哪一行失败。然后检查你的自定义类型是否在生成器的类型映射表里。Spec-kit 一般允许在spec.config.yaml里配置类型映射：

generator: typeMapping: datetime: string uuid: string decimal: number

把自定义类型映射到目标语言的基础类型，问题基本就解决了。

5.2 团队抵触写规范怎么办

我见过太多团队推规范推不动。根因往往不是“规范没用”，而是规范写起来太痛苦。解决办法有两个：一是把规范模板做得足够简单，新人十分钟能上手；二是让规范带来即时好处，比如“写完规范自动生成接口桩和测试骨架，省你半天写样板代码的时间”。

我的经验是，先在一个小模块试点，让两三个人的小组尝到甜头，再逐步推广。强行全员铺开，只会收获一堆敷衍了事的规范文件。

5.3 规范与现有代码冲突的处理

存量项目接入 Spec-kit，最头疼的是现有代码和规范对不上。我的策略是渐进式对齐：先给现有接口补规范，允许规范暂时“描述现状”而不是“描述理想”。等规范覆盖到一定程度，再逐步收紧约束，把不合理的现状改掉。

千万别一上来就按理想状态写规范，然后发现几百个接口全要改，团队直接崩溃。工程化是马拉松，不是百米冲刺。

5.4 常见问题速查表

5.5 独家避坑技巧

第一个技巧：规范文件里加owner字段，标记每个规范的责任人。规范出问题能直接找到人，避免“三不管”地带。第二个技巧：规范变更单独走 PR，和代码变更分开评审，这样规范的历史演进清晰可查。第三个技巧：定期跑spec-kit lint，它会检查规范里的坏味道，比如字段命名不一致、错误码重复定义，相当于给规范做体检。

我在实际使用中发现，Spec-kit 最大的价值不是省了多少写代码的时间，而是把“沟通成本”变成了“校验成本”。以前接口对不上要开会扯皮，现在 CI 直接告诉你哪一行不一致。这种从“人对人”到“机器对规范”的转变，才是工程化真正的意义。

最后再分享一个小技巧：把spec-kit validate挂到 Git 的 pre-commit hook 里，本地提交前就拦住规范错误，别等到 CI 才报。配置很简单，在.git/hooks/pre-commit里加一行spec-kit validate specs/ --strict就行。这个动作能让你的 CI 流水线干净很多，谁用谁知道。