Quartz 4

Tech--Spec Coding

28 min read

规范驱动开发（Specification-Driven Development, SDD） 是

一种将软件开发组织在 “单一规格中心” 的过程模型：团队首先协作产出结构化规格 - 领域模型、API Contract、质量约束等，再由此反向驱动设计、实现、测试与运维

说人话，Spec Coding 是指从 “凭感觉编码” 到 “看规范说话”，构建可预测、可维护、可验证的 AI 辅助软件工程体系，从而可靠的 AI Coding

引言 - 何为 Spec Coding

原理上，SDD 将 Design by Contract 的契约视角与 Specification by Example 的可执行 Spec 结合. 这要求 spec 既可被工具消费，又能作为业务、测试与运维共享的“通用语言”

SDD 典型实践模式我们其实并不陌生：以规范为变更入口和合规依据的 API 设计优先流程，在 CI 中自动审计，以及从同一份规范派生文档、SDK、契约测试和监控配置等，人类的生产过程广泛采用这种实践

随着 AI Coding 的普及，SDD 因能够系统性约束“vibe coding”带来的漂移与不一致，常被视为 spec-first / documentation-first 对 vibe coding 的替代路径

当代 SDD 的代表性项目包括 Spec Kit、OpenSpec 围绕 AWS Kiro 和 Specmatic 构建的各类 SDD 示例仓库等。当然，还有比较大的探索空间 。

是什么 - 结构化 AI 协同

在 LLM 驱动的 AI Coding 时代，Vibe Coding 迅速流行。

“开发者” 通过一系列模糊的 prompt 引导 AI 生成代码，修修补补，直到 “感觉对了” 为止。对于快速原型和小型项目或许有效，但面对严肃的、生产级的软件系统，其弊端便显露：质量参差不齐、逻辑难以追溯、后期维护成本高昂。

为了解决这些问题，**规格驱动开发（Spec-Driven Development, SDD）**走入大众视野。SDD 并非重拾过去繁重的 “瀑布式” 文档，而是倡导在编码之前，通过编写结构化、以行为为中心的自然语言 “规格”（Spec），为人类开发者和 AI 编码智能体（AI Coding Agent）提供一个清晰、一致且可验证的纲领。

可以说，它结合了传统软件工程的严谨性与现代 AI 的高效，旨在将开发过程从依赖直觉的艺术，转变为有章可循。

好的 spec 会像是你为明天失忆的自己留下的笔记。

为什么 - SDD 能解决大的 AI Coding 痛点

AI 编码工具极大地提升了开发效率，但也带来了新的挑战

  • 质量一致性难题：AI 生成的代码质量高度依赖于提示的质量和上下文的完备性，导致输出结果不稳定

  • 可维护性黑洞：缺乏明确的设计意图，使得后续开发者（无论是人还是 AI）难以理解和修改既有代码

  • 团队协作障碍：当团队成员都依赖各自的 Vibe 与 AI 互动时，难形成统一的技术愿景和实现标准

  • 交付可验证性缺失：如果需求本身就模糊，如何验证最终交付的软件 “正确”？

SDD 正是应对这些挑战的有力武器。它将 Spec 定位为 AI 协同开发的核心，扮演两大关键角色 ↓

原理 - 核心理念与原则

两个关键角色

  • “可执行” 的上下文：一份好的 Spec 应该为 AI 提供了完成任务所需的所有背景信息、约束条件和验收标准，使其能更精确、更可靠地生成代码，减少来回修改的次数

  • 对齐与协作的契约：Spec 成为产品、开发、测试等所有相关方共同遵守的 “单一事实来源”（Single Source of Truth），确保人类与 AI、人类与人类之间的目标对齐。

SDD 通过一套 “文档” 和 “文档维护” 原则来构建

这里不用多说，当我们自发用一套文档描述项目，并要求 Agent “遵循” 文档中的流程和规范，并进行检查和校准时，就已经在使用 Spec Coding 的相关原理了。相信大部分人在 Vibe 时，也有这样的经历。

当然，SDD 的精髓不在于文档本身，而在于其背后的一系列指导原则：

  • 提供项目契约

    • 目标为中心：Spec 描述的关键，应该是 “系统应该做什么”。相对而言 “系统应该怎么实现” 的重要程度稍低

    • 面向用户故事：每个功能点都应与具体的用户场景和明确的验收条件挂钩（如 Given-When-Then 格式）

  • 明确约束与边界：通过清晰定义 contract、领域模型、边界条件和异常处理，提供可执行的上下文。（这些都是 AI Coding 的幻觉重灾区）

  • **面向验收标准：**设计时，提供验收标准 (Gate)，聚焦于可观测的外部行为和业务成果，易于理解和测试。流程上，重点要求检查和准出的规范化

  • 活文档 (Living Document): Spec 不是一次性的产物，它应随着项目的演进而持续更新、可追踪、可验证，与代码保持同步。相信我，这一点非常重要。

p.s. Gate 是个挺优雅的词

虽然是通用的，但它包含了 “规范”、“通过后才准出”、“程序化检查”、“TDD” 的意味。在 coding 这个场景下，由于 SPEC 本身的存在，也属于很精准的魔法词。

且 spec-kit 的模版里的说法是 ## Delivery Workflow & Quality Gates: a. 足够的知名度 b. 被抄因而扩散 c. 混进 coding 类训练数据，没准 “验收” 类的任务你用 gate 在 PE 中也有奇效

p.s. 的 p.s “人不读、但 AI 会读” 的 AI Friendly 技巧其实也是个很有意思的话题

Spec Coding 是既有实践的发展而非替代

SDD 并非凭空创造的概念，它与当前人类的工程实践一脉相承，目的是融合了 AI 能力的同时保证质量。所以，相对传统的开发范式，SDD 是一种 “集大成” 的发展者，而非对抗者。

  • BDD/TDD/SBE: 行为驱动开发（BDD）、测试驱动开发（TDD）和以实例为规格（Specification by Example, SBE）都强调通过具体的例子和测试来定义需求。SDD 继承了这一思想，并将由这些例子构成的 “规格” 作为驱动 AI 编码的核心输入。

  • API-First & Contract Testing: API-First 方法论强调先设计和约定 API 契约（如 OpenAPI/GraphQL Schema）。SDD 将此契约作为规格的关键组成部分，并可以进一步结合契约测试（Contract Testing）工具（如 Pact）来确保服务间的交互符合约定。

可以认为，SDD 是这些优秀实践在 AI 时代的一次现代化 “打包升级”，它提供了一个更统一的框架，将需求定义、设计、编码、测试和文档等环节串联起来，并以 AI 智能体作为核心的执行引擎。

工作流程简介 - 端到端 Spec Coding 实践的感性认识

我们先看一个传统的开发流程例子

Specify / Spec主理人们 (PM&RD) 将模糊的需求 PRD，提炼成结构化的特性 SPEC (借助问答是种很好的方式)
Review & Sign-off所有相关方对 Spec 进行评审，达成共识后视为标准，并形成版本记录
AI Generate将 Spec 作为高质量上下文，喂给 AI Coding Agent，生成技术设计、代码框架甚至完整实现
Gate / Verify根据 Spec 中的验收标准，选择合适的校验手段，比如单元测试、端到端测试、必要时人来承担
Version Management任何对需求的变更首先要体现在 Spec 的更新上，且 Spec 本身与代码一同纳入版本控制
Measure & Improve持续度量 Spec 质量和 AI 生成代码的对齐度，不断优化 Spec 模板和 Prompt 策略 （最重要）

所以 Spec 天然存在。

但是人在开发时都是有容错的，随着开发也能发现问题和解决，同时也不断有场外的输入。因此在执行流程时，未必需要严谨。而 AI 的容错就差得多了。

传统的规范驱动，就是写好文档，人来开发，好无趣好无聊。

AI coding 中的 SDD 的新实践，就是在传统的 SDD 的基础上，将开发流程进一步的结构化和规范化。并站在人和 AI 的共同视角回答一个问题：如何 Spec 每个环节做到尽量清晰、可准出、可复现。

示例工作流：使用 GitHub Spec Kit 与 AI 编码智能体

以 github/spec-kit 为例，它提供了一个命令式的 SDD 流程，Cross Agent 的设计，可以使得多种 AI 编码智能体

如 Codex, Claude Code, Gemini CLI）基于 Spec 协同工作

这个流程就是最好的演示之一：

核心在于，开发者需要想清楚 “AI 应该做什么”，并将其转变为通过维护一份高质量的 Spec。

AI 则围绕这份 Spec 自主完成从设计、编码到测试的大部分工作。

理论上来说，随着模型迭代，理论上在不远的将来可以做到 好的Spec = 成品项目

基于模版和 init 的 Sub Command 实现，很聪明的设计

# 1. 初始化项目并创建 spec, AI 会生成一份初始的 `spec.md`
/specify "Create a coupon service API with endpoints for creating, retrieving, and applying coupons."
# 2. 细化 Spec (迭代), 手动编辑 spec.md，添加业务规则、数据模型、验收标准等细节
/refine "Add a validation rule that coupons cannot be applied to already discounted items."
# 3. 生成执行计划, AI 会分析 spec.md，生成一个详细的实现步骤清单，比如需要创建哪些文件、修改哪些函数
/plan
# 4. 执行计划, AI 根据计划开始生成和修改代码
/implement
# 5. 验证实现, AI 根据 spec.md 中的验收标准生成测试用例，并运行测试来验证代码是否符合预期
/verify

OpenSpec 也类似

常见工具选择

目前，SDD 的工具生态正在快速发展，主要有几类代表：

  • Kiro: 一个 “Agentic” IDE，将 Spec 作为一等公民，提供从原型到生产的全流程 SDD 体验。应该说，Kiro 作为较早的 spec 标准实践者，将 spec 的规范化带入了大众视野。希望获得端到端、高度集成化开发环境的团队。

  • GitHub spec-kit: 一个开源、轻量级的命令行工具集，可以灵活地集成到现有的开发流程和 IDE 中。它适合希望渐进式引入 SDD、保持工具链灵活性的团队。如果感到 spec-kit 的结构过于复杂，可以尝试 openspec

  • 各类 Agent OS

好的 Spec - 组成与范式

Spec 的通常层级

在复杂的项目中，规格并非单一文档，而是一个分层的体系，确保从宏观战略到微观实现的一致性。

和面向人的开发一样，好的体系应包含一些横切面来确保按预期运行。

比如：观测，在追踪人的做事精准度时，往往没有那么重要，或许只是匹配一下 “人员”、“需求”、“技术实现” 等，统计意义大于实践指导。而对于几十上百的基于一份 spec 就跑飞的 Agent 而言，情况则完全变了。因此，我们可能需要设计观测方法，确保代码变更都能追溯到具体的 Spec 定义，每个特性规格都能对齐到产品目标。

在这样的背景下 Gate，不再是一个代码质量准出的概念，而会影响到整个开发过程的方方面面，是个更大的话题，按下不表。

一个研发视角的结构

高质量的规格通常结构化，且需确保信息完备且无歧义；以一个较为典型的技术设计来说，可能长成这样

组成部分核心内容
目标与需求目标与范围 (Goal & Scope)简述本次变更要解决的核心问题、业务价值，以及明确的 “做” 与 “不做” 范围。
技术标准用户场景与业务规则 (User Scenarios & Business Rules)描述典型用户如何与系统交互，以及背后必须遵守的业务逻辑。
接口/数据模型 (API / Data Models)定义 API 端点、请求/响应格式、数据结构、字段约束等。
状态与错误处理 (State & Error Handling)定义系统可能存在的状态，以及在各种异常情况下应如何响应。
依赖与约束 (Dependencies & Constraints)列出对外部系统、特定技术栈或环境的依赖和限制。
非功能需求 (NFRs)性能（延迟、吞吐量）、安全性、可用性、合规性等要求。
准出与观测验收标准 (Acceptance Criteria / Gate)使用 Given-When-Then 或类似格式，列出所有需要被满足的、可测试的条件。
迁移与回滚计划 (Migration & Rollback)对于涉及数据结构或重大架构变更的功能，需要有明确的上线和回滚策略。

当然，实际创建时，应该取舍。可以参考以下实践

如何落地

可能会持续补充？

建立和维护 - 你会给团队端什么菜

建立 spec 的金口诀，就是把 agents 当成一个团队而非工具

先想清楚角色与职责

可以从团队角色的协同角度来理解 SDD 的构建

  • 产品经理: 负责提供清晰的业务目标和用户故事，并参与验收标准的定义。

  • 开发工程师: 主导规格的编写，将业务需求转化为技术上可执行的细节，并监督 AI 的实现过程。

  • 测试工程师: 确保规格中的验收标准是可测试的，并负责构建自动化验证框架。

  • 架构师: 评审规格中的技术方案、接口设计和非功能需求，确保其符合整体架构蓝图。

当然，这些角色大多数可以由 AI 替代。

搭建 Spec 的一定程度上类似通过制定规范让 Agent 能够在更多角色上替代人。

当 AI 无法替代的剩余部分可以由一个人完全 cover 时，也就是一人团队了。我认为团队协作的模式，将快速的由工种配合过渡到 “上下文” 配合，每个人独特的价值大多数来自于他的上下文。

变更流程版本化

将规格视为代码（Docs-as-Code）是关键。所有规格文档都应存储在 Git 仓库中，与对应的源代码放在一起。

任何对规格的重大变更都应遵循正式的流程，如发起一个 RFC (Request for Comments) 或 ADR (Architecture Decision Record)，经过评审和批准后才能合并。这确保了所有决策都是透明和可追溯的。

这两句是 AI 写的，我大概也是这个意思，感觉版本管理的重要性应该无需多言了

具体操作 - 提防反模式

在推行 SDD 时，需要警惕的常见陷阱

过度设计

  • 避免过度文档化：规格应聚焦于 “刚好” 的细节，避免陷入无休止的文档编写，失去了敏捷性。以我个人的经验来说，Spec 往往是在过程中迭代的，这恰恰是当前 spec 系统都处理的不太好的地方

Gate 粗糙

  • 避免描述偏差：实际描述过程中，偏差很常见，一开始就引入 Agent 对规范进行复述是一种比较好的校验方式。另外，不但要描述清楚直接目标，也要说明背后的目的，这一点和给人描述需求是比较类似的。

  • 提供清晰的 Gate：量化诸如 “系统应该运行得很快” 这类模糊的标准是无用的。标准必须是具体的、可量化的。毕竟评测才是一切。

Spec 腐败

  • 避免腐坏：代码实现后要立刻更新 Spec，且要祭出 “彻底实现，并删除旧文件，不遗留任何 todo” 这样的清理型指令。缺乏维护的 spec 很快就会变得毫无价值，甚至可能成为开发过程中的阻碍。

  • 避免僵化：避免把规格当 “最终真理”，在实现过程中一定会发现存在问题的 spec，应该及时更新规格并要求 Agent 重读。

思路 - 探索中要持续回答的问题

底层逻辑还是做好 Context Engineering，还是如何压缩、索引、动态加载，让 spec 变得更好执行

如何控制 Spec 的粒度？

遵循 “刚好够用” 原则，spec 的详细程度应与功能的复杂性和风险成正比。这里有点像做架构，虽说有基本原则，但是妙到毫巅处是法无定法。

对于简单的 UI 调整，你甚至不需要搞什么 spec；对于复杂的计费逻辑，你直接把状态机、错误处理、代码实现描述清楚也不为过。

其实也说明了 AI Coding / PE 的 “手艺” 一定程度上不会过时，因为 spec 的边界定义和描述方式，很多时候取决于你的手感。

如何让 AI 严格遵循？

  • 首先，提供高质量、结构化的 Spec 是前提，尤其避免规则相互冲突导致混乱。不做检查很可能导致这种问题。

  • 其次，通过多轮次的提示来修正 AI 的偏差，这过程通常需要注意：是否出现脏掉的上下文，是否出现不合适当前 AI 执行的任务（即时换 Agent、拆分任务、或提供工具），是否出现 spec 偏差等。

  • 建立 Gate，尤其是程序化的 Gate。最有效的永远是 TDD，提供强大而聪明的的护栏尤为关键。当然利用基于规格生成的自动化测试来创建，从结果上保证了AI 生成的代码对规格的遵循。

如何避免过度设计？

尤其是 初创项目 / 快速迭代 环境下

  • 区分主干和枝节

    • 主干：在快速迭代的场景下，重点关注 spec 中 “稳定” 的部分（如核心业务规则和 API Contracts）和 “高风险” 的部分（如与数据、安全相关的逻辑）

    • 枝节：对于可以接受一定精度丢失、易变的部分（如 UI 布局），可以保持较低的 spec 粒度

  • 留出变更空间: 要容忍可控的模糊，避免过拟合

  • 主动迭代: 说清楚的标准，在迭代中未必会被遵循；一定的开放性也可能会带来意想不到的好结果；应该提前就对这些情况保持开放的心态，设想可能发生的情况，及时发现并更新 spec。

如何做快速迭代？

SDD 并不排斥探索，但要聪明的协调

  • 试试原型: 发挥 AI 能够快速产出大量实现的特性，对于不确定性的任务，可以先进行一个有时间限制的 冲刺 阶段。一方面，过程中可能会有一些 insight，另一方面，基于你的具体任务，看看 AI 是否擅长，或者哪个 AI 更加擅长。

  • Top Down: 修改代码时，主动要求先更新文档（如果多级，遵循自上而下的结构），确保文档符合预期，没有矛盾再更新具体实现。

  • 产出 Spec: 产出不是代码，而是一份更清晰的规格。然后基于这份新规格进入正式的 SDD 流程。

从 Vibe Coding 到 SDD 的最简步骤

全面转型到 SDD 可能需要时间，可以采用分阶段的迁移策略

  • 构建最简单的 spec: 为新功能引入一个极简的 spec，至少只包含 目标、关键的 Contracts 和 Gate。没错，可以直接用 Ai 来总结，甚至比创建一份 Agent.md 还简单。

  • 用 Spec 的方式开发增量的关键特性: 选择项目中新的、核心的或复杂的功能，创建 Spec，强制要求进行完整的规格编写和评审，这个阶段可以引入一些诸如 Open Spec 的工具，但要删繁就简，聚焦于效果实现。

  • 重构和规格治理: 找到或建立起心水的规范后，推广到整个项目，建立完善的 Spec，并将其作为团队的默认工作方式。通常通过一次重构完成。

开放话题

更进一步的讨论 (留个引子，不在这儿写）

  • 从 Spec Coding 的视角出发，“Vibe” 还能/适合干什么

  • 如何打磨项目，提升完成度，各个阶段有什么技巧 80% → 95% → 99% → 99.9% ⇒ +

  • 做 AI 算法优化和用 AI Coding 之间的有趣关联

  • 和人协作的部分聊完了，非人类的 AI Coding 方式有哪些

小结

Spec 驱动，通过将开发的核心从模糊的 Vibe 转移到明确的 Spec，我们能够构建出更可靠、更易于维护、更能适应变化的系统。

进一步的说，这逻辑也不是仅仅用在软件开发上，其根本是人与 AI 的高效协同提供了一条清晰的路径。换言之 Spec XXX 是一整套 不再是一种选择，而是高效构建系统的必经之路。

Graph View