amuluze阿慕路泽

SDD 规范驱动开发：从 Spec 到文档治理闭环的工程实践

在 AI 辅助编程日益普及的今天，团队真正要解决的，已经不是“能不能写代码”，而是“如何保证代码始终服务于真实需求”。Spec-Driven Development（SDD，规范驱动开发）是一种以规范为核心的工程协作范式：先定义规范，再组织实现；先明确约束，再生成代码；先建立验收标准，再讨论技术细节。

代码回答的是“系统现在怎么运行”，而 Spec 回答的是“系统为什么必须这样运行”。两者不是替代关系，而是约束与实现的关系。没有 Spec 的 AI 生成，往往只是放大产出；有 Spec、有追溯、有校验的 AI 协作，才能放大工程交付。

为什么 SDD 在 AI 时代更重要

传统开发里，需求歧义通常以返工、补丁和隐式知识的形式慢慢暴露；而在 AI 辅助开发里，这类问题会被进一步放大。原因很简单：AI 擅长补全“实现”，却不会天然理解业务边界、不变量和错误语义。

这也让 SDD 的几项原则重新变得关键：

Spec 优先：任何改变系统可观测行为的修改，都应先变更 Spec，再变更代码。
约束先于实现：Spec 描述“必须满足什么”，Plan 描述“准备怎么做”，代码只是其中一种落地形式。
验收必须客观：所有业务规则、边界条件和失败语义，都应存在可验证的验收方式。
歧义必须显式暴露：遇到 Spec 缺口时，应先补规范，而不是用代码分支偷偷决定业务。
AI 必须有边界：AI 可以生成实现、补齐文档、辅助检查，但不能越权发明领域规则。

从本质上说，SDD 不是“多写几份 Markdown”，而是把需求、设计、实现和验证拉回到同一个事实系统里。

三层文档模型

一个成熟的 SDD 系统，通常由三层结构共同支撑。下表概括了三者的核心差异：

层次	关注点	生命周期	典型路径	谁来维护
Domain Spec	长期必须成立的事实、状态、不变量、错误语义	长期，跨需求复用	`.specs/domain/*.md`	人工长期维护
Task Spec	单次需求的目标、范围、边界、验收	短，随需求产生和归档	`.specs/tasks/*.md`	需求方与实现方共建
Plan	实施拆分、顺序、风险、验证动作	与 Task Spec 配套	`.plans/*.md`	实现方起草，受 Spec 约束

要点只有一句话：Spec 定义应该满足什么，Plan 只描述准备怎样实现。 Plan 不能反向覆盖 Domain Spec，也不能替代 Task Spec 的验收定义。

目录架构：把规范、事实和实现分层隔离

当团队把 SDD 真正工程化时，目录结构本身就是一种约束表达。一个清晰的分层通常包含以下角色：

.specs/domain/：长期领域约束，只写行为、不变量、状态和错误语义。
.specs/tasks/：单次任务规范，描述目标、范围、验收和排除项。
.plans/：实施计划，记录拆解步骤、落地顺序和验证动作。
.docs/：实现侧文档，记录当前系统事实，例如架构、数据流、部署方式和模块边界。
源代码层：pages/、components/、composables/、data/ 等真正承载实现逻辑的目录。

这里需要特别强调：.docs/ 适合描述当前实现事实，而不是抽象的长期设计意图。长期约束应优先沉淀在 Domain Spec 中；.docs/ 更像是“系统已经怎样落地”的可审计快照。

协作入口：`AGENTS.md` 与 `CLAUDE.md`

在多 Agent 协作的项目里，团队级事实入口通常由两份文档承担：

AGENTS.md：AI 协作入口的事实来源，集中描述项目约定、目录职责、命令清单、约束边界和质量门禁。
CLAUDE.md：与 AGENTS.md 同步的副本入口，用于在不同 Agent 运行环境下提供一致的项目约定。

二者保持同步是项目治理的一部分：入口一旦漂移，AI 协作就会建立在错误的事实之上。

为什么需要文档治理系统

很多团队理解了 SDD 的思想却依旧落地失败，原因往往不是概念，而是缺少一套稳定的文档治理系统。只要 Spec、实现文档和协作入口依赖人工记忆维护，它们迟早会漂移。

把 SDD 做成可持续的工程实践，关键在于把“规范、说明、索引、审计、门禁”沉淀为一组长期稳定的产物。除了上面提到的目录之外，通常还需要一份 文档治理合同——例如 .docs/MANIFEST.yml：

声明必需文档和可选文档集合。
约束最小行数、必备标题和目标路径。
记录入口文档要求，例如 AGENTS.md / CLAUDE.md。
保留团队手工加入的 required 路径，避免后续被覆盖或删除。
成为结构校验、质量审计和发布门禁的共同事实来源。

换句话说，Manifest 不是“文档索引”，而是“文档治理合同”。

文档治理系统的三段式结构

一个足够稳健的文档治理系统，通常会表现出三段式特征：先做确定性的事实采集，再用 Manifest 收敛受管目标，最后才允许 AI 在受控范围内做增强。

确定性事实采集

第一段不依赖 LLM，只依赖工作区可观测事实：

项目入口和目录结构。
构建命令、部署脚本、CI 配置。
已存在的 .docs 文档与 AGENTS.md。
Domain Spec、Task Spec、Plan 等受管路径。
路由、模块、配置文件和导出结构等实现信号。

这一步的价值在于“可重复”和“可审计”。即使完全不依赖 AI，也应能基于当前工作区形成一版结构正确、事实可追溯的文档结果。

Manifest 驱动的覆盖治理

仅仅“发现文件”还不够。系统还需要知道哪些文档是必须存在、哪些章节必须包含、哪些目标属于受管范围。这正是 MANIFEST.yml 存在的意义：把覆盖目标从“文件系统事实”提升为“治理合同事实”。

借助 Manifest，可以做三件事：

结构校验：检查文档是否存在、最小行数和必备标题是否满足。
质量审计：检查内部链接、变更影响范围和覆盖缺口。
发布门禁：把文档质量纳入 CI 或发布前阻断。

AI 受控增强而非越权改写

在确定性阶段完成后，才适合引入 AI 做增强分析，例如补充架构解释、识别文档缺口、总结模块职责、提出领域约束建议。但这一步必须建立明确边界：

AI 只能基于当前工作区事实做分析，不能虚构模块和行为。
AI 的角色是补充说明、发现问题、生成候选内容，而不是改写长期领域真相。
Domain Spec 的长期语义，应以人工维护为准。
即便启用 AI，系统也应保留纯确定性的退化路径。

这类设计的关键不在“让 AI 写得更多”，而在“即使 AI 失效，系统也不失控”。

文档所有权：什么可以自动改，什么必须人工维护

文档系统一旦进入自动或半自动更新阶段，最大的风险不是写不出来，而是误覆盖人工内容。因此，一个健壮的治理体系必须显式区分文档所有权。

推荐的原则如下：

生成器拥有的文档：允许被确定性流程全量刷新。
人工维护的文档：不得被无条件覆盖，只能在受控区块内增补分析内容。
入口文档：如 AGENTS.md 与 CLAUDE.md，需要保持同步，但仍应保留人工审阅环节。
Domain Spec：首次接入时可以生成骨架，后续长期语义以人工维护为准。

自动化系统最理想的状态，是“精确识别受管范围，并在边界内安全更新”，而不是“全自动重写一切”。

代码、测试与 Spec 的双向追溯

SDD 的价值只有在“可追溯”时才成立。否则，Spec 最终会沦为一份漂亮但无人相信的说明书。

完整的追溯关系至少应覆盖三类锚点：

领域约束追溯：在 Domain Spec 中为关键规则定义稳定 ID，并在实现或审查中引用这些约束。
验收标准追溯：Task Spec 中的 Acceptance Criteria 应能映射到测试、检查命令或人工验收动作。
证据追溯：构建、类型检查、测试、生成、smoke check 等结果应成为“任务完成”的客观证据。

真正成熟的 SDD 流程，不会只说“这个需求已经完成”，而是会同时说清楚：

依据的是哪份 Task Spec。
受哪些 Domain Spec 约束。
对应哪些验收标准。
通过了哪些验证证据。

一个可落地的团队工作流

把 SDD 与文档治理系统结合起来后，一个典型的工作流通常如下：

新功能、复杂重构或非平凡 Bug，先补 .specs/tasks/<task-id>.md。
若需求触及长期业务边界，先修订 .specs/domain/*.md，而不是先改代码。
编写 .plans/<task-id>.md，只描述实施路径、风险与验证动作。
开始编码，并让实现、测试和提交都能回挂到对应 Spec。
同步刷新文档资产（.docs/、AGENTS.md、CLAUDE.md 与相关索引），使其重新对齐当前实现。
对文档执行结构检查、链接审计与覆盖确认，确保说明系统没有失真。
在 CI 或发布前把文档质量纳入正式门禁，避免实现先行、说明失效。

这条链路的核心不是工具数量，而是职责清晰：

Spec 管约束。
Plan 管执行。
Code 管实现。
Test 和 build 产物管证据。
文档治理系统负责把这些信息重新组织成可信的说明系统。

SDD 落地时最常见的误区

很多团队并不是反对 SDD，而是用错了 SDD。以下误区尤其常见：

把 Plan 当 Spec：实现步骤写得很细，但真正的行为约束和验收标准却非常模糊。
把 .docs/ 当领域真相：架构说明写了很多，却没有长期有效的不变量定义。
把 AI 当需求方：让 AI 根据代码“猜测规则”，生成看似合理但未经确认的约束。
缺少脱离 LLM 的退化路径：一旦外部 AI 不可用，整个文档体系就无法维持一致性。
没有文档门禁：团队口头说重视文档，但 CI 和审查流程里没有任何阻断机制。

SDD 真正要解决的，不是“文档太少”，而是“系统缺少一个可信、可验证、可维护的事实中心”。

结语

无论是单体应用、多端前端，还是复杂的微服务系统，SDD 的价值都不在于让团队写更多文档，而在于让需求、约束、实现和验证重新对齐。Spec 守住业务底线，Plan 组织落地路径，代码交付行为，而文档治理系统则把这些内容持续整理成不会快速腐烂的说明。

在 AI 能够高效生成代码的时代，稀缺的不再是“实现速度”，而是“约束清晰度”。谁能先把规范、追溯和门禁建立起来，谁就能真正掌控复杂度，而不是被复杂度反过来支配。