嗨，我是辉哥，一个致力于使用 AI 技术搞副业的超级个体
Spec-Kit 拆解：最适合团队的 SDD 规格驱动开发范式
Spec-Kit 是 Claude Code 生态里规格驱动开发的工具集。它不写代码、不做调度、不定义开发流程，只做一件事：把模糊的自然语言需求，固化成结构化、可校验、可追溯的契约，让开发、测试、验收围绕同一个基准运转。
它是 AI 开发工作流的上游锚点。返工的根源几乎都是需求走样，Spec-Kit 从机制上把需求漂移的空间压到最低。
一、AI 开发最隐蔽的浪费：需求漂移
用 AI 做开发的人都绕不开一个问题：聊的时候感觉句句对齐，代码写出来才发现处处偏差，来回改几轮，返工时间远超开发本身。
这不是模型写代码的能力不行，是需求传递方式本身有缺陷。
1. 共识是软的，没有刚性边界
聊天里的对齐、零散的需求描述，本质都是软共识。上下文一拉长、任务一拆分，模型会不自觉地补全自己的理解、悄悄扩大范围、简化复杂边界，最后做出来的东西和最初的想法渐行渐远。没有明确的「做什么/不做什么」边界，AI 会按最省事的路径实现，而不是按你真正想要的路径。
2. 验收是模糊的，没有统一标尺
「做完了」和「做对了」是两回事。没有明确的验收标准，收尾阶段就会陷入拉扯：你觉得漏了异常处理，它觉得你没提过；你觉得边界场景要覆盖，它觉得正常流程能用就行。没有标尺的验收，永远扯不清。
3. 变更是失控的，没有追溯链路
需求一改，哪些代码要动、哪些测试要改、哪些逻辑受影响，全靠人记。改着改着就出现「改了A忘了B」的断层，逻辑补丁越打越多，代码熵增速度越来越快。没有追溯链的变更，最终一定会把项目堆成屎山。
靠追问、靠长文档、靠人工盯，只能缓解，不能根治------自然语言天生有歧义，散落在会话里的共识，撑不起严谨的开发基准。
Spec-Kit 的判断在这里：AI 开发的效率瓶颈早已不是写代码不够快，而是需求传递的损耗太高。把需求从「聊天共识」升级成「结构化规格契约」，让下游环节有唯一的真相源，才能真正减少返工。
二、三个底层支柱
Spec-Kit 的能力建立在三个设计上：结构化规格模型、声明式校验引擎、全链路溯源机制。三者合起来把需求从软约定变成硬标准。
结构化规格模型：让需求像代码一样无歧义
这是 Spec-Kit 的核心资产。规格不是自由书写的文档，而是有固定字段、固定语义、固定层级的结构化模型，每一项都有明确的定义和边界，没有自由发挥的空间。
一份标准规格包含六大固定模块：
- 基础信息：需求背景、业务目标、非目标（明确写出不做什么）
- 功能范围：按用户故事拆分的核心功能点，一一对应验收标准
- 边界条件：异常输入、错误处理、降级策略、边缘场景
- 非功能约束：性能要求、安全规则、兼容范围、依赖限制
- 影响范围：关联模块、数据变更、对外接口影响
- 验收口径：每条功能对应的可量化验收条件
这套设计强制把隐含假设显性化。普通人写需求天然只写正常路径，对异常、错误、边界、不做什么一笔带过，固定结构会把这些盲区全部补齐。和纯自然语言描述相比，结构化规格的理解偏差率明显下降------这是它减少返工的根本原因。
声明式校验引擎：像编译器一样查需求漏洞
规格写完不是直接能用，要先过校验关。Spec-Kit 内置了一套声明式校验规则体系，像代码 lint 一样自动扫描规格的完整性、一致性、合理性，输出问题清单。
校验覆盖四个维度：
- 完整性校验：检查是否遗漏验收标准、异常处理、边界场景，强制补全关键信息
- 一致性校验：检查不同模块的定义是否矛盾、前后描述是否冲突
- 可验证性校验：检查验收标准是否可量化、可落地，杜绝「体验更好」「性能更快」这类模糊表述
- 粒度校验：检查单个功能点是否过大，是否需要拆到可执行、可验收的最小单元
它不判断需求「好不好」，只判断需求「完不完整、自洽不自洽、能不能落地」。很多返工不是因为实现错了，是需求本身就有漏洞------校验引擎把这些坑消灭在开工前。
全链路溯源机制：每一行代码都有对应规格
这是规格驱动的灵魂。规格里的每一条功能点、每一项验收标准，都会生成稳定的唯一标识，后续生成的代码、测试、文档、变更记录，全部挂载对应标识，形成完整的追溯链。
带来三个价值：
- 变更可定位：需求变更时，能精准命中受影响的代码、测试、文档，不用全量扫描，变更成本大幅降低
- 验收可逐条：不用靠感觉判断完成度，逐条核对规格条目，做完多少、还差多少，清晰可见
- 决策可回溯：每个功能为什么这么设计、当时定了哪些边界，翻规格就能查到，不用翻几百页聊天记录
它把传统软件工程里「需求-开发-测试-验收」的追溯体系，用纯文本的方式轻量化落地到了 AI 开发工作流中。
三、源码架构：纯文本声明式的分层实现
Spec-Kit 全程基于纯文本构建，没有编译型代码、没有后端服务、没有黑盒逻辑，所有能力都通过 Markdown 声明、由模型自主解析执行。这和传统需求管理工具的代码化实现完全不同------它的架构从第一天起就是「模型原生」的，所有结构都服务于让大模型精准理解、稳定执行，而非适配程序运行逻辑。
整体采用五层分层架构，目录结构清晰，职责边界明确：
bash
spec-kit/
├── skills/ # 入口层：用户可调用的主命令
├── schemas/ # 模型层：规格元数据定义
├── validators/ # 规则层：声明式校验规则集
├── lib/ # 能力层：公共原子能力
└── templates/ # 输出层：标准化文档模板
3.1 入口层：薄Skill编排，厚能力下沉
所有用户可直接调用的命令全部放在 /skills 目录下，每个命令对应一个独立的 Markdown 文件，结构统一：角色定位、前置依赖、执行流程、输出规范四块。
设计上遵循「薄入口」原则：主 Skill 只做流程编排，不承载具体业务逻辑。比如 /create-spec、/refine-spec、/validate-spec 三个不同入口，都会复用同一份规格 Schema、同一套校验规则、同一组 ID 生成逻辑。既避免了重复定义导致的行为不一致，也让自定义新命令变得简单------只需要写编排逻辑，核心能力直接复用。
3.2 模型层：声明式规格元模型
规格的结构化能力，全部来自 /schemas/spec.schema.md 这份元模型定义。它不是代码里的结构体，而是用结构化 Markdown 声明的字段契约，明确定义了：
- 一级模块的必填项与可选项
- 每个字段的语义、类型、约束条件
- 字段之间的依赖关系与层级嵌套规则
- 不同场景下的裁剪规则（比如极简版/完整版）
这套设计完全可定制。团队不需要懂开发，只需要修改这份 Schema 文件，就能增减字段、调整结构、适配自己内部的需求文档规范，不需要改任何核心逻辑。传统工具的规格结构写死在代码里，改结构要发版；Spec-Kit 改结构就是改一行文本，成本几乎为零。
3.3 规则层：数据化的校验规则集
校验引擎没有一行硬编码的判断逻辑，所有规则都以数据化的形式存放在 /validators 目录下，按完整性、一致性、可验证性、粒度四个分类拆分。
每条校验规则采用标准化条目结构：
- 规则 ID：全局唯一标识
- 触发条件：规则生效的场景
- 判定逻辑：自然语言描述的判断标准
- 问题等级：提示/警告/阻塞
- 修复建议：对应的优化方向
比如完整性分类下的「用户故事必须对应验收标准」规则，就是一条独立的文本条目，模型执行校验时会逐条遍历匹配，输出问题清单。
这种设计让校验规则可以像代码一样被版本化管理、增量扩展。团队可以把自己的业务规范、踩过的坑，沉淀成专属校验规则，逐步形成自己的需求质量门禁。
3.4 能力层：原子化公共能力库
/lib 目录存放所有可复用的原子能力，以独立 Markdown 片段的形式存在，比如 ID 生成器、条目映射器、diff 比对器、格式转换器等。
这些能力是所有主命令的公共基座。全局统一的语义 ID 生成逻辑，确保规格、代码、测试里的标识规则一致，是全链路溯源的基础；标准化的条目映射逻辑，负责把规格条目和代码、测试片段做关联匹配；统一的 diff 比对算法，确保不同命令输出的变更报告格式一致。
原子化拆分保证了全工具的行为一致性------不会出现创建规格用一套 ID 规则，验证规格用另一套的情况。
3.5 输出层：可定制模板体系
所有对外交付的文档格式，都存放在 /templates 目录下，包括规格文档模板、验收报告模板、测试用例模板、变更对比模板等。
模板和业务逻辑完全分离，核心逻辑只负责生成内容，模板负责定义呈现格式。团队可以根据自己的文档规范修改模板，比如调整章节顺序、适配内部文档格式，完全不需要触碰核心执行逻辑。
溯源机制的纯文本实现
全链路溯源能力没有依赖任何外部数据库或工具链，完全通过纯文本标注实现：
- 规格生成时，为每条功能点、验收标准生成稳定的语义 ID
- 生成代码时，在对应函数/模块的注释中标注关联的规格 ID
- 生成测试时，在对应用例的注释中标注关联的规格 ID
- 验证、变更、回归时，通过 ID 匹配完成关联定位
全程都是纯文本标记，Git 天然支持全版本追溯，不需要额外安装任何工具，也没有数据同步的问题。这是它能轻量嵌入任何开发工作流的核心原因。
四、核心能力全景
Spec-Kit 的能力围绕规格的全生命周期展开，从创建、校验到落地、验收、变更，形成完整闭环。
| 大类 | 核心命令 | 定位 | 解决的问题 |
|---|---|---|---|
| 规格构建 | /create-spec、/refine-spec、/spec-from-chat | 从模糊想法到结构化规格 | 需求零散、缺项漏项、边界模糊 |
| 规格校验 | /validate-spec、/check-scope | 规格完整性与合理性体检 | 需求带缺陷开工、隐含假设没显性化 |
| 开发对齐 | /spec-to-code、/align-implementation | 基于规格驱动代码实现 | 实现走样、超范围开发、逻辑偏离 |
| 验收回归 | /verify-implementation、/spec-to-tests | 反向校验与测试生成 | 验收无标准、测试与需求脱节 |
| 变更管理 | /spec-diff、/update-spec、/impact-analysis | 版本对比与影响评估 | 需求变更乱、影响范围说不清 |
| 协作输出 | /export-spec、/sync-to-issues | 多端同步与对接 | 跨角色信息不一致、交付无依据 |
上手不用全学，核心主链路只有四步：创建规格 → 校验补全 → 驱动开发 → 验收核对，剩下的都是进阶场景补充。
新手三步入门：
- 先用
/validate-spec给现有需求文档做一次体检，感受常见的需求漏洞 - 再用
/create-spec给一个核心模块写正式规格，走完完整流程 - 最后用
/verify-implementation做一次反向验收，直观感受规格对齐的价值
五、核心能力深度拆解
从完整能力中选出最常用、最具代表性的 6 项，逐个讲透设计逻辑和解决的问题。
/create-spec：引导式生成，强制补全需求盲区
不是扔给你一张空白模板自己填，而是像专业产品经理一样，沿着固定框架分步引导，逐个模块确认信息，关键项缺失不会进入下一步。
它会强制你回答那些容易被忽略的问题：这个功能的边界在哪？哪些场景明确不做？异常情况怎么处理？性能和安全有什么约束？普通人写需求天然只关注正常流程，引导式生成用固定框架把所有隐性盲区全部挖出来，从源头减少后续返工。
/validate-spec：需求级 Lint，提前消灭规格缺陷
规格写完先别着急开发，跑一遍校验。它会输出结构化的问题清单：哪些验收标准不可验证、哪些边界没覆盖、哪些定义前后矛盾、哪些功能粒度过大。
它的价值不是挑刺，是提前对齐「合格的标准」。你觉得写清楚了，在机器视角里可能全是模糊表述。过一遍校验，把歧义、缺项、矛盾都消灭在开发前，远好过写一半再回头改。社区实践数据显示，经过完整校验的规格，后续开发的返工率有明显下降。
/spec-to-code：带着规格紧箍咒，绝不超范围实现
这是规格驱动开发的核心执行入口。它不让模型自由发挥写代码，而是严格对照规格条目生成实现，规则明确：只做规格里明确写了的，没写的绝对不加，没定义的绝不自行发挥。
AI 写代码有个通病：自作主张加功能、顺手优化、按自己的理解扩范围，美其名曰提升体验，实则悄悄扩大需求边界。/spec-to-code 用规格做刚性约束，每段代码对应哪条规格都标注清晰，从机制上杜绝「镀金式开发」。它不追求写得又快又多，追求写的每一行都在需求范围内。
/verify-implementation：反向校验，对抗上下文漂移
代码写完不是终点，反向校验才是最后一道闸门。它会逐条核对代码实现与规格条目，输出清晰的结果：哪些已完成、哪些未实现、哪些实现有偏差、哪些是规格外的额外功能。
这是对抗长会话上下文漂移最有效的手段。哪怕开发过程中模型悄悄偏了方向，最后这一步也能拉回来，不会等到上线才发现货不对板。长周期、多人协作的项目里，开发和需求不在同一段会话，反向校验是最靠谱的验收标尺。
/spec-to-tests：测试锚定需求，而非锚定实现
从规格条目直接生成对应的验收测试用例，测试范围和需求范围完全一致，不会漏测也不会多测。
普通 TDD 很容易陷入「测试跟着实现走」的误区------实现怎么写，测试就怎么测，最后测试全过但需求没满足。规格驱动的测试生成，测试的基准是需求规格，不是代码实现，从根源保证测试是在验证需求，而不是验证代码。生成的用例可以直接对接项目现有测试框架，无需额外改造。
/spec-diff：版本对比，变更范围精准量化
规格更新后，自动对比两个版本的差异，精准列出新增、修改、删除的条目，同时评估对应的代码影响范围。
需求变更不可怕，可怕的是变更范围说不清、影响估不准。spec-diff 把模糊的「需求改了一点」，变成清晰的「3条功能新增、2条边界修改、影响2个核心模块」，后续开发、测试、排期都有明确依据。配合溯源机制，甚至可以直接定位到需要修改的测试用例和代码文件，变更效率大幅提升。
六、设计哲学：为什么是规格，不是文档
契约优于共识
聊天里的共识是软的，理解可以有偏差、边界可以被模糊；规格契约是硬的，写清楚做什么、不做什么、怎么算做完，所有人都按同一个标准执行。AI 开发里最大的成本从来不是写代码，是对齐成本。用契约替代共识，就是把对齐成本降到最低。
结构优于描述
大段自然语言写得再详细，也免不了歧义。固定结构、固定字段、固定语义的规格，看起来死板，实则最可靠------它强制把模糊的想法拆成清晰的条目，消除了大部分解读空间。就像代码有语法规范才能稳定运行，需求有结构规范才能不走样。
单一真相源原则
开发看规格、测试看规格、验收看规格、变更也看规格。所有环节围着同一个基准转，不会出现各说各话的错位。很多项目越做越乱，本质就是真相源太多：聊天记录是一个版本、文档是一个版本、代码里又是一个版本。规格驱动就是把所有出口统一成一个。
增量优于全量
需求变更是常态，推翻重写是大忌。Spec-Kit 全链路支持增量操作：规格增量更新、diff 增量对比、代码增量对齐、测试增量补充。不用每次改需求就全部推倒重来，小步迭代，成本最低。
透明优于黑盒
所有规则、结构、逻辑都以纯文本形式存在，没有隐藏的黑盒逻辑。使用者可以看懂每一条规则的判定标准，可以修改每一处结构定义，可以沉淀自己的最佳实践。工具的价值是赋能，不是绑架。看得见、改得了、能沉淀，才是能长期用下去的好工具。
七、适用边界
Spec-Kit 的价值和需求的稳定性正相关。需求越确定、生命周期越长，收益越高；反之则会成为负担。
适合的场景：
- 核心业务模块、底层公共组件，生命周期长，后续会反复迭代
- 团队协作项目，需要统一的需求基准和验收标准
- 中长期维护的稳定项目，返工成本远大于规格编写成本
- 对外交付、外包协作，需要明确的交付标准和验收依据
不适合的场景：
- 快速原型验证、探索期项目，需求高频变动，写规格的速度赶不上变化的速度
- 一次性小脚本、临时工具，做完即废弃，不值得固化规格
- 高度不确定的创新功能，需要边做边试错，刚性规格会束缚探索
Spec-Kit 的核心创新不在提升写代码的速度，而在提升做对事情的概率。它用结构化契约把需求锁死，用校验和溯源把执行焊牢，让 AI 的快建立在「不跑偏」的基础上。比起追求更快的代码生成速度，把需求基准打牢、减少无效返工，才是 AI 开发真正的效率来源。