用 AI 做开发的人经常遇到一个问题：聊的时候感觉句句对齐，代码写出来才发现处处偏差，来回改几轮，返工时间远超开发本身。

这不是模型写代码的能力不行，而是需求传递方式本身有缺陷。聊天里的对齐和零散的需求描述，本质都是软共识。上下文一拉长、任务一拆分，模型会不自觉地补全自己的理解、悄悄扩大范围、简化复杂边界。没有明确的「做什么/不做什么」边界，AI 会按最省事的路径实现，而不是按你真正想要的路径。

Spec-Kit 是 Claude Code 生态中规格驱动开发的工具集。它不写代码、不做调度、不定义开发流程，只做一件事：把模糊的自然语言需求，固化成结构化、可校验、可追溯的契约，让开发、测试、验收围绕同一个基准运转。

一、AI 开发最隐蔽的浪费：需求漂移

AI 开发的效率瓶颈早已不是写代码不够快，而是需求传递的损耗太高。问题主要体现在三个方面：

共识是软的，没有刚性边界——没有明确的边界，AI 会按最省事的路径实现，而不是按你真正想要的路径。

验收是模糊的，没有统一标尺——「做完了」和「做对了」是两回事。没有明确的验收标准，收尾阶段就会陷入拉扯。

变更是失控的，没有追溯链路——需求一改，哪些代码要动、哪些测试要改，全靠人记。没有追溯链的变更，最终一定会把项目堆成一团混乱的代码。

Spec-Kit 的判断是：把需求从「聊天共识」升级成「结构化规格契约」，让下游环节有唯一的真相源，才能真正减少返工。

二、三个底层支柱

Spec-Kit 的能力建立在三个设计上：结构化规格模型、声明式校验引擎、全链路溯源机制。

结构化规格模型：让需求像代码一样无歧义

这是 Spec-Kit 的核心资产。规格不是自由书写的文档，而是有固定字段、固定语义、固定层级的结构化模型。一份标准规格包含六大固定模块：

• 基础信息：需求背景、业务目标、非目标
• 功能范围：按用户故事拆分的核心功能点，一一对应验收标准
• 边界条件：异常输入、错误处理、降级策略、边缘场景
• 非功能约束：性能要求、安全规则、兼容范围、依赖限制
• 影响范围：关联模块、数据变更、对外接口影响
• 验收口径：每条功能对应的可量化验收条件

这套设计强制把隐含假设显性化。和纯自然语言描述相比，结构化规格的理解偏差率明显下降。

声明式校验引擎：像编译器一样查需求漏洞

规格写完要先过校验关。Spec-Kit 内置了声明式校验规则体系，像代码 lint 一样自动扫描规格的完整性、一致性、合理性。

校验覆盖四个维度：

• 完整性：检查是否遗漏验收标准、异常处理、边界场景
• 一致性：检查不同模块的定义是否矛盾、前后描述是否冲突
• 可验证性：检查验收标准是否可量化、可落地
• 粒度：检查单个功能点是否过大，是否需要拆分

它不判断需求「好不好」，只判断需求「完不完整、自不自洽、能不能落地」。很多返工不是因为实现错了，而是需求本身就有漏洞——校验引擎把这些坑消灭在开工前。

全链路溯源机制：每一行代码都有对应规格

规格里的每一条功能点和验收标准，都会生成稳定的唯一标识。后续生成的代码、测试、文档、变更记录，全部挂载对应标识，形成完整的追溯链。这带来三个价值：

• 变更可定位：需求变更时精准命中受影响的代码、测试、文档
• 验收可逐条：逐条核对规格条目，完成度清晰可见
• 决策可回溯：每个功能为什么这么设计，翻规格就能查到

三、源码架构：纯文本声明式的分层实现

Spec-Kit 全程基于纯文本构建，没有编译型代码、没有后端服务、没有黑盒逻辑，所有能力都通过 Markdown 声明、由模型自主解析执行。整体采用五层分层架构：

入口层（/skills）

用户可直接调用的命令，遵循「薄入口」原则：主 Skill 只做流程编排，不承载具体业务逻辑。/create-spec、/refine-spec、/validate-spec 等入口都复用同一份规格 Schema、同一套校验规则、同一组 ID 生成逻辑。

模型层（/schemas）

规格的结构化能力来自 /schemas/spec.schema.md 元模型定义。它用结构化 Markdown 声明字段契约，明确定义了一级模块的必填项、每个字段的语义、类型、约束条件，以及字段之间的依赖关系。团队只需要修改这份 Schema 文件，就能增减字段、调整结构、适配内部需求文档规范，不需要改任何核心逻辑。

规则层（/validators）

校验引擎没有硬编码的判断逻辑，所有规则都以数据化形式存放在 /validators 目录下，按完整性、一致性、可验证性、粒度四个分类拆分。每条校验规则采用标准化条目结构，包含规则 ID、触发条件、判定逻辑、问题等级和修复建议。团队可以把自己的业务规范沉淀成专属校验规则。

能力层（/lib）

存放所有可复用的原子能力，以独立 Markdown 片段形式存在，如 ID 生成器、条目映射器、diff 比对器、格式转换器等。这些能力是所有主命令的公共基座，确保全工具的行为一致性。

输出层（/templates）

所有对外交付的文档格式，包括规格文档模板、验收报告模板、测试用例模板、变更对比模板等。模板和业务逻辑完全分离，团队可以根据自己的文档规范修改模板。

四、核心能力全景

Spec-Kit 的能力围绕规格的全生命周期展开：

新手三步入门：先用 /validate-spec 给现有需求文档做体检，再用 /create-spec 给核心模块写正式规格，最后用 /verify-implementation 做一次反向验收。

五、核心能力深度拆解

/create-spec：引导式生成，强制补全需求盲区

像专业产品经理一样沿着固定框架分步引导，逐个模块确认信息，关键项缺失不会进入下一步。强制回答那些容易被忽略的问题：功能边界在哪？哪些场景明确不做？异常情况怎么处理？

/validate-spec：需求级 Lint，提前消灭规格缺陷

规格写完先跑一遍校验，输出结构化问题清单：哪些验收标准不可验证、哪些边界没覆盖、哪些定义前后矛盾。社区实践数据显示，经过完整校验的规格，后续开发的返工率有明显下降。

/spec-to-code：带着规格紧箍咒，绝不超范围实现

严格对照规格条目生成实现，只做规格里明确写了的，没写的绝对不加。从机制上杜绝「镀金式开发」，每段代码对应哪条规格都标注清晰。

/verify-implementation：反向校验，对抗上下文漂移

逐条核对代码实现与规格条目，输出清晰的结果：哪些已完成、哪些未实现、哪些实现有偏差、哪些是规格外的额外功能。这是对抗长会话上下文漂移最有效的手段。

/spec-to-tests：测试锚定需求，而非锚定实现

从规格条目直接生成对应的验收测试用例，测试范围和需求范围完全一致，不会漏测也不会多测。从根源保证测试是在验证需求，而不是验证代码。

/spec-diff：版本对比，变更范围精准量化

规格更新后自动对比两个版本的差异，精准列出新增、修改、删除的条目，同时评估对应的代码影响范围。把模糊的「需求改了一点」变成清晰的「3条功能新增、2条边界修改」。

六、设计哲学：为什么是规格，不是文档

• 契约优于共识——聊天里的共识是软的，规格契约是硬的，写清楚做什么、不做什么、怎么算做完
• 结构优于描述——固定结构、固定字段、固定语义的规格，强制把模糊的想法拆成清晰的条目
• 单一真相源原则——开发看规格、测试看规格、验收看规格、变更也看规格，所有环节围着同一个基准转
• 增量优于全量——全链路支持增量操作，不用每次改需求就全部推倒重来
• 透明优于黑盒——所有规则、结构、逻辑都以纯文本形式存在，看得见、改得了、能沉淀

七、适用边界

Spec-Kit 的价值和需求的稳定性正相关。适合的场景包括核心业务模块、团队协作项目、中长期维护的稳定项目、对外交付协作。不适合快速原型验证、一次性小脚本、高度不确定的创新功能。

Spec-Kit 的核心创新不在提升写代码的速度，而在提升做对事情的概率。它用结构化契约把需求锁死，用校验和溯源把执行焊牢，让 AI 的快建立在「不跑偏」的基础上。