spec-driven-development

Spec-Driven Development - 规格驱动开发

技能概述

Spec-Driven Development 是一种在编码前先编写结构化规格文档的开发方法，通过四阶段门控工作流程（Specify → Plan → Tasks → Implement）确保需求明确、方案可行、任务可执行，将规格文档作为开发团队的共享事实源，避免因需求模糊导致的返工和误解。

适用场景

1. 启动新项目或重要功能开发

当开始一个新项目、新功能或需要做出重大架构变更时，使用规格驱动开发可以确保所有参与者对目标、技术栈、项目结构、代码风格、测试策略和边界约束达成共识。规格文档定义了要构建什么、为什么要构建以及如何知道已完成，是开发前不可或缺的准备步骤。

2. 需求模糊或不完整的场景

当需求只存在于模糊想法中、描述不清晰或存在歧义时，规格驱动开发强制你在编码前明确列出假设、澄清需求、定义成功标准。通过将模糊要求转化为具体的、可测试的条件（如"Dashboard LCP < 2.5s"而非"让 Dashboard 更快"），避免后期因理解偏差导致的返工。

3. 涉及多文件或多模块的复杂变更

当变更涉及多个文件、模块或需要做出架构决策时，规格文档帮助识别组件依赖、确定实现顺序、评估风险并定义验证检查点。这确保了复杂项目有清晰的技术实施计划，任务按依赖顺序执行，可并行与串行的部分得到合理划分。

核心功能

四阶段门控工作流程

规格驱动开发将开发过程分为四个严格的阶段，每个阶段必须经过人工审核验证后才能进入下一阶段：Specify（编写规格） → Plan（制定计划） → Tasks（分解任务） → Implement（实施）。这种门控机制防止在需求不明确时就开始编码，在计划未验证时就开始实施，确保每个阶段都有明确的目标和验收标准。

规格文档模板与成功标准

技能提供完整的规格文档模板，涵盖目标、技术栈、命令、项目结构、代码风格、测试策略和边界约束（Always/Ask First/Never）。特别强调将模糊需求转化为具体的成功标准，例如将"让 Dashboard 更快"转化为"Dashboard LCP < 2.5s on 4G、初始数据加载 < 500ms、CLS < 0.1"等可测试的条件，让开发有明确的完成标准。

活文档与项目规范

规格文档不是一次性文档，而是随着决策变化、范围调整、功能增减而持续更新的活文档，应提交到版本控制并在 PR 中引用。技能还定义了项目边界：哪些操作必须执行（如提交前运行测试）、哪些需要先询问（如修改数据库架构、添加依赖）、哪些永远不做（如提交密钥、删除失败的测试），为团队提供清晰的规范指导。

常见问题

什么是规格驱动开发？为什么要使用它？

规格驱动开发是一种在编写代码之前先创建结构化规格文档的开发方法。规格文档定义了要构建什么、为什么要构建以及如何知道已完成，是开发团队的共享事实源。使用规格驱动开发可以避免因需求模糊、假设未明确、架构决策未记录而导致的返工和误解——一个 15 分钟的规格规划可以避免数小时的调试和返工。

技术规格文档应该包含哪些内容？

规格文档应包含六个核心部分：1）目标——要构建什么及原因、用户是谁、成功标准是什么；2）技术栈——框架、语言、关键依赖及版本；3）命令——完整的构建、测试、Lint、开发命令；4）项目结构——源代码、测试、文档的目录布局；5）代码风格——命名规范、格式规则、代码示例；6）测试策略——使用什么框架、测试位置、覆盖率要求、测试层级。此外还应定义边界（Always/Ask First/Never）和开放问题。

小项目或简单任务也需要规格文档吗？

是的，但规格的长度应与任务复杂度相匹配。简单任务可能只需要两行规格（例如接受标准和边界），但仍需要明确的完成标准。只有单行修复、拼写纠错或需求明确且自包含的更改可以跳过规格。所有超过 30 分钟实现时间的任务、涉及多个文件的变更、或需要架构决策的工作都应先编写规格文档。