SDD / Spec Kit 规范驱动开发（Vibe Coding 升级范式）

• 理解 SDD 与 TDD/BDD/PDD 的区别
• 需求文档到可执行契约的转换
• 各范式的适用边界

SDD 是"先写 spec（预期行为契约），再据此生成实现与测试"的范式，spec 是中心产物。TDD 以"测试先行"驱动实现，测试即规范；BDD 以"行为描述"（Given-When-Then）驱动，强调用业务语言表达行为；PDD（Plan-Driven）以预定的计划/文档驱动，偏重过程管控。差异：SDD 把"可执行契约"（spec）作为独立的一等产物，可与测试、实现、文档分离生成；TDD 的规范藏在测试里，BDD 的规范藏在行为描述里。转换边界：需求文档（自然语言、模糊）→ 人工提炼为"可执行契约"（spec，结构化、可验证）→ 由 spec 生成测试与实现。SDD 不适合"需求完全模糊、无法固化为契约"的探索型场景，而适合"需求可明确、可验收"的生产场景。

SDD 的核心是"把需求固化为可执行契约"，从而让 AI 生成有客观验收标准。它与 TDD/BDD/PDD 的差异在于"契约是一等公民、可由 spec 直接生成实现与测试"，边界在于"需求能否固化为可执行契约"。

• 了解三大 SDD 框架
• 对比 spec 模板、validator、task 生成
• 工程取舍

三大框架都围绕"spec 驱动生成"设计，但取向不同：Spec Kit（GitHub 开源）——提供 spec 模板与 validator，侧重"规范化的 spec 结构 + 校验 + 生成可执行 task"，与 Claude Code 等 AI 工具集成，适合希望"轻量、可自定义、与 AI 编码联动"的团队；OpenSpec——强调"可执行的 spec 变更集"，用结构化 spec 驱动任务生成与验证，偏重"spec 变更管理"；Kiro——侧重"多 agent 协作 + 自动化 SDD 流程"，把 spec 编写到任务拆解到执行做编排。取舍：选型看①spec 模板——是否匹配团队结构；②validator——是否够强（类型、必填、约束）；③生成 task——能否把 spec 可靠转化为可执行任务；④生态——与现有 AI 工具/CI 的集成。工程取舍是"模板灵活"与"校验严格"、'"轻量"与"流程重"的平衡。

三大框架是"spec 驱动的工程化工具"，差异在模板、校验与任务生成的取向。选型要结合团队对"模板规范、校验强度、自动化程度、AI 集成"的偏好，避免功能堆叠。

• 认识迁移痛点
• spec 粒度与维护责任
• 同步漂移治理

过渡痛点：①spec 写多细——写太细则 spec bloat（维护负担重、扼杀实现灵活性），写太粗则变 vague spec（无法指导实现与验收），需要找到"足够验收、不过度约束"的粒度；②谁来维护——spec 需持续维护，否则随需求演进过期，需明确"spec 是代码一部分、由开发者与需求方共同维护"；③同步漂移——spec 与代码实现易脱节（改了代码没改 spec，或反之），导致 spec 失去约束力。缓解：把 spec 纳入版本控制与 CI 校验，用"spec 变更与代码变更联动"的流程（改 spec 必须触发实现与测试更新），用自动化检查 spec 与实现的符合度。核心是"让 spec 成为可维护、可验证的活文档"。

迁移痛点的本质是"spec 治理的复杂度"。粒度、维护、同步三者互为因果，需用"纳入版本控制 + CI 校验 + 变更联动"使 spec 成为活文档，才能避免 SDD 从"提质"沦为"新负担"。

• 理解 Skills 体系
• Skills 与 spec 的关系
• 协作方式

Skills 是把"专家知识/流程"封装为可复用的、可调用的指令集，供 AI 在特定场景调用。它本质上是一种"过程性规范"——规定了"怎么做、按什么标准"，与 spec 的"结果性规范"（规定"要交付什么"）互补。所以"Skill 就是 spec 的一种"不完全准确：Skill 更像"操作契约/方法论封装"，spec 更像"结果契约/验收标准"。协作方式：SDD 用 spec 定义"要达成什么"（验收标准），Skills 定义"如何达成"（专家流程、标准、注意点）；IDE 中可把 spec 相关规范（如领域规则、编码标准）封装为 Skill，让 AI 在生成时既遵循 spec 又遵循专家流程。二者结合，形成"SDD 定目标、Skills 定方法"的协作。

Skills 与 spec 是"方法与结果"的双轨。Skill 封装专家流程（过程规范），spec 定义验收标准（结果规范），二者互补而非等同；协作上"spec 定目标、Skills 定方法"，让 AI 生成既达标又合规。

• 理解 Spec 先行与 TDD 的关系
• 互补方式
• 边界划分

互补：SDD 的"Spec 先行"定义"系统应该具备什么行为"（验收契约），TDD 的"测试先行"把验收标准转化为可运行的测试用例，驱动实现。两者是"目标"与"手段"的关系——spec 提供验收标准，TDD 用测试把这些标准落地为可验证的约束。边界：SDD 偏"需求层"（定义要交付什么行为、用什么契约），TDD 偏"实现层"（用测试驱动具体实现与重构）。SDD 的 spec 面向"需求与验收"，TDD 的测试面向"实现细节与行为验证"。实践中先写 spec（定义验收），再由 spec 生成测试（TDD 落地），实现通过测试即满足 spec，形成"spec 定目标、测试做验证"的协同。

Spec 先行与 TDD 是"验收标准"与"验证手段"的互补。spec 定义"什么是对的"，TDD 用测试证明"实现了对的"，边界在"需求层"与"实现层"；二者结合让"契约"既有目标又有验证。

• 理解 monorepo 与多团队场景
• spec 一致性、版本化、回滚
• 协作机制

大型 monorepo 与多团队下，spec 治理要点：①一致性——用统一的 spec 模板与规范，由 CI 校验所有 spec 结构一致，避免各团队格式漂移；通过"所有权"划分 spec 的归属（谁能改哪个模块的 spec），并建立跨团队 spec 的评审与协调机制；②版本化——spec 纳入版本控制，与代码同仓库同版本，spec 变更需评审与审批，记录变更历史；③回滚——spec 与代码作为一个整体可回滚（spec 版本与实现版本绑定），回滚时保证 spec、实现、测试三者一致；④漂移检测——用 CI 校验 spec 与实现是否同步，防止多团队维护导致漂移。核心是"统一规范 + 所有权 + 版本绑定 + 变更审批"。

多团队下的 spec 治理难点是"一致性"与"漂移"。通过统一模板、CI 校验、所有权划分、版本绑定与变更审批，使 spec 在规模化的 monorepo 中保持可控、可回滚、可同步。

• 理解 SDD 与 CI/CD 对接
• 设计完整链路
• 门禁与评审

完整链路：①spec 验证——CI 中先校验 spec 结构、格式、约束（validator），不符合则阻断；②自动 code-gen——由 spec 自动生成实现骨架、测试与契约（如接口、DTO、mock），可人工或 AI 辅助；③diff 评审——生成的代码与既有代码做 diff，人工评审 diff 是否合理（是否破坏既有逻辑、是否引入多余变更）；④merge——评审通过后合并，并跑既有测试与门禁。工程设计要点：把 spec 验证作为 CI 前置门禁；code-gen 可复现（同一 spec 生同样结果）；diff 评审聚焦"生成 vs 手写"的差异；merge 前跑完整测试与静态扫描。目标是让"spec 驱动"自动化、可门禁、可追溯。

SDD 与 CI/CD 对接的本质是"把 spec 作为流水线的输入"。验证、生成、评审、合并四步构成"spec 驱动"的工程链路，让 spec 从"文档"变成"流水线的一部分"，实现可门禁、可复现、可追溯。

• 理解 AI Agent 编排框架
• 全自动 SDD 流程
• 自验证与人工兜底

用 BMAD（面向 AI 的模块化架构驱动）或 GSD（并发/自驱动开发）等框架编排全自动 SDD：①spec 编写——由主 Agent 或人工基于需求生成结构化 spec；②任务拆解——编排框架把 spec 拆解为可并行/可执行的任务，依赖关系明确；③多 Agent 编码——派发多个 Agent 分别实现不同任务，各自遵循 spec 与规范；④自验证——每个 Agent 生成后运行测试与校验，验证是否符合 spec 与契约，失败则自修；⑤整合——各 Agent 产出合并，跑完整测试与门禁，最后人工评审与兜底。要点：编排框架负责"任务分配、依赖管理、状态同步、自验证循环"，但"最终验收与责任"仍由人工把关，避免全自动失控。

编排框架让 SDD 从"人工推动"走向"Agent 协作自动化"。核心价值是"任务拆解 + 多 Agent 并行 + 自验证闭环"，但需人工兜底最终验收与责任，防止"全自动"带来的质量与一致性风险。

• 了解各 spec 模板
• 适用场景
• 选型考量

各模板适用场景不同：OpenAPI——REST/HTTP API 契约，字段、路径、参数、响应定义完整，生态成熟；AsyncAPI——异步消息/事件驱动接口契约，描述 topic/事件/payload；JSON Schema——通用 JSON 数据结构与校验，与 HTTP 无关，可内嵌；Zod——TypeScript 运行时校验库，schema 即校验即类型，适合 TS 全栈类型安全；protobuf——高性能二进制序列化，适合 RPC/gRPC 与强类型跨语言。选型考量：①协议——REST 用 OpenAPI、消息用 AsyncAPI、RPC 用 protobuf；②语言——TS 团队偏好 Zod/JSON Schema，跨语言用 protobuf；③校验与类型——需要运行时校验选 Zod，仅需数据形状选 JSON Schema；④生态与工具链——考虑 codegen、文档、mock 支持。没有万能模板，按"协议 + 语言 + 校验需求 + 生态"组合选型。

spec 模板选型本质是"按工程场景匹配"。OpenAPI/AsyncAPI/protobuf 对应协议，JSON Schema/Zod 对应数据与校验，需结合协议、语言、类型安全与生态做组合决策，避免"用错模板"导致契约失真。

• 批判性评估 SDD 的"过度"问题
• 识别高 ROI 领域
• 判断适用边界

"spec 是源代码、代码是 spec 的衍生品"是一种极端的契约驱动理念，在大部分场景是"过度"的——因为很多业务逻辑无法/不值得完全固化为 spec，且维护 spec 与实现的同步成本高，过度 spec 化会扼杀实现灵活性与探索。SDD 高 ROI 的领域：①接口/契约密集型——API、消息、数据模型明确定义，spec 能直接生成契约、mock 与测试，收益显著；②可验证、规则明确的业务——如结算、规则引擎、配置校验，行为可固化为 spec；③需要大量重复样板生成的领域——如 CRUD、DTO、接口层，spec 能减少重复；④多团队/多语言协作——契约统一降低沟通成本。低 ROI：探索性、需求模糊、强交互体验、实现自由度高的领域。判断标准是"需求能否清晰固化为可验证契约 + 生成化收益是否大于维护成本"。

"spec 是源代码"是理想化理念，现实中需理性评估。SDD 高 ROI 在"契约清晰、可验证、生成化收益高"的领域，而探索性/模糊需求领域 ROI 低；判断标准是"固化收益 vs 维护成本"。

• 认识 spec bloat 与 vague spec
• 找到合适的粒度
• 落地经验

两个极端：spec bloat——spec 过度详细，约束到实现细节（如内部变量、算法步骤），导致①维护负担重（改实现细节要改 spec）、②扼杀实现灵活性、③spec 与代码难同步；vague spec——spec 过度抽象，如"实现用户模块"这种无约束描述，导致①无法指导实现、②无法做验收、③生成结果不可控。真实边界：spec 应描述"外部可观察的行为与契约"（输入、输出、规则、边界、验收标准），而不应描述"内部实现细节"（算法、变量、内部结构）。判断标准：一个 spec 是否足够"据此生成可验收实现"且"不约束内部实现"。落地经验是"先薄后补"——先写可验收的薄 spec，验证生成与验收后再细化，避免一开始就写死。

边界在于"描述行为契约 vs 描述实现细节"。spec 管"外部行为与验收"，不管"内部实现"，这样既避免 bloat（不约束实现）又避免 vague（可验收）；"先薄后补"是规避早期踩坑的实践。

• 用规范文档生成测试骨架
• 生成 Mock
• 减少人工翻译错误

做法：①从规范文档（如 OpenAPI、JSON Schema、protobuf）自动提取接口、字段、类型、约束；②用 codegen 工具生成测试骨架（测试文件、方法签名、参数结构）与 Mock（按 schema 生成符合类型与约束的 mock 数据）；③测试断言可基于规范中的期待行为（如状态码、响应结构）生成；④人工只需补充"业务规则"类断言与边界，而非重复"翻译"接口与数据结构。这样减少人工翻译错误——因为接口、字段、类型、mock 都由规范机器生成，避免人工手写导致的拼写、类型、结构不一致。要点是"规范作为单一事实来源，人工只补业务断言"。

用规范生成骨架与 Mock 的核心是"规范即单一事实来源"。接口、数据、mock 由机器生成消除了人工翻译错误，人工聚焦业务断言，既提效又降错，是 SDD 降低工程保真成本的关键。

• 设计 spec 版本管理与审批
• 明确修改权限
• 保证同步

版本管理：spec 纳入版本控制，与代码同仓库同版本，变更记录在案，支持回滚；变更审批：明确"谁有权改 spec"——通常由需求方/架构/接口负责人（spec 所有者）审批，按模块划分所有权，跨模块变更需评审；同步保证：①流程联动——改 spec 必须触发对应实现与测试更新，改实现若偏离 spec 需先改 spec；②CI 校验——用自动化检查 spec 与实现的符合度（如接口是否匹配、字段是否一致），不符则阻断；③评审——spec 变更与代码变更走同一 PR 评审，记录关联。核心是"spec 是受控资产，变更需审批、实现需同步、CI 需校验"。

Spec 同步的关键是"把 spec 当代码一样治理"。版本化、所有权、变更审批保障"谁改、改什么"，CI 符合度校验保障"实现不漂移"，流程联动保障"改 spec 必改实现"，三者使 spec 成为可信的活文档。

• 理解 Spec 先行
• 理解验收驱动
• 核心价值

核心是"先定义可验收的契约，再据此实现"。Spec 先行：先写清楚"系统要具备什么行为、满足什么验收标准"，再生成实现与测试，避免"先写代码再补需求"的偏离；验收驱动：spec 定义了"什么算完成"，实现是否合格由"是否满足验收标准"决定，测试与门禁都围绕验收展开。价值在于：①把"需求"固化为"可验证的契约"，让 AI 生成有客观目标；②发布前有明确的验收依据，避免"代码能跑但没做对"；③需求、实现、测试三者围绕同一份 spec 对齐，减少歧义。核心机制是"spec 定目标、验收做裁判"。

Spec 先行确立"目标"，验收驱动确立"裁判"。二者构成 SDD 的核心闭环——先写契约、再实现、用验收判断是否达标，使 AI 时代的开发"有据可依、有验收可判"。

• 了解 Spec Kit 工具链
• 规格、生成、验证三环节
• 工程应用

Spec Kit（GitHub 开源）围绕三环节：①规格（Spec）——提供结构化的 spec 模板与规范，让团队以统一格式定义需求契约；②生成（Generate）——从 spec 生成可执行任务（tasks）、实现骨架、测试与文档，供 AI 或人工在执行时遵循；③验证（Validate）——提供 validator 校验 spec 的结构与约束，检测 spec 是否合法、是否满足模板要求，并可在 CI 中作为门禁。工程应用：用 Spec Kit 把"需求"标准化为 spec，再生成任务与产物，用 validator 在 CI 中把关，形成"定义-生成-验证"的规约驱动闭环。

Spec Kit 把 SDD 落到"可操作的工具链"。规格标准化输入、生成产出、验证把关，三位一体让 spec 从"文档"变成"可执行的工程产物"，且可与 CI 集成形成门禁。

• 理解两者关系
• 互补方式
• 边界

SDD 与 TDD 是"目标与手段"的互补关系。SDD 的 spec 定义"系统的行为与验收标准"（要达成什么目标），TDD 的测试把这些标准转化为可运行、可验证的用例（如何验证达成）。互补：SDD 提供"验收契约"，TDD 提供"验证手段"，二者结合——先写 spec 定义验收，再按 spec 生成测试（TDD 落地），实现通过测试即满足 spec。边界：SDD 偏"需求/验收层"，TDD 偏"实现/验证层"；SDD 管"做什么对"，TDD 管"怎么证明对"。实践中 SDD 可在更高层（spec）驱动，TDD 在实现层驱动，二者协同使"目标"与"验证"统一。

SDD 与 TDD 不冲突，而是"定义目标"与"验证达成"的互补。SDD 的 spec 给 TDD 提供验收依据，TDD 的测试为 spec 提供落地验证，二者分层协同，让开发"有目标、可验证"。

• 理解落地关键
• 文档的设计
• 评审机制

SDD 团队落地要点：①文档——spec 是活文档，需结构清晰、纳入版本控制、与代码同仓库；规范文档（spec 模板、编写指南、验收标准示例）帮助团队统一写法；②评审——spec 变更与代码变更走评审，spec 由"所有者"审批，跨模块变更需协调；③评审重点是"spec 是否可验收、粒度是否合适、是否与实现同步"；④落地步骤——先试点（选一个契约清晰的模块跑通 SDD），沉淀模板与最佳实践，再推广；⑤培训与文化——让团队理解"spec 是契约而非文档负担"，避免形式化。核心是"文档定规范、评审保质量、试点再推广"。

团队落地靠"文档支撑 + 评审把关 + 试点推广"。文档统一 spec 写法，评审保障 spec 质量与同步，试点降低风险，三者结合让 SDD 从"理念"落地为"团队实践"，避免沦为形式主义。