AI Agent 辅助工具学习 --- SDD 开发与实践

SDD：概念摘要与开发实践

SDD 是什么

SDD（Specification-Driven Development，规格驱动开发） 是一种软件研发取向：把规格说明当作首要工件与真相来源 ，让实现计划与代码成为规格的生成物与表达，而不是反过来让规格永远追赶代码。在 AI 能理解与实现复杂规格的前提下，团队通过可版本化的 PRD、实现计划、合约与任务列表，把「意图 → 实现」做成可重复、可校验的流程。方法论原文见 GitHub 上的 spec-driven.md。

下面是对该文公开内容的要点摘要 ；文档后半部分是团队落地时的开发实践补充。

要点摘要（基于 spec-driven.md）

核心观念：权力倒置

传统做法里，规格说明服务于代码，代码是「真相」；规格往往落后、与实现脱节。
SDD 把关系反过来：规格是源头，代码是规格的表达与生成物。 维护软件 = 演进规格；调试 = 修正会生成错误代码的规格与实现计划；重构 = 为清晰而重组。意图用自然语言、设计资产与原则表达，代码是最后一公里。

为何现在重要

AI 已能把足够清晰的规格可靠地变成可运行代码（放大开发者能力，而非简单替代）。
系统复杂度 使仅靠人工对齐「意图 vs 实现」越来越难。
需求变化更快，SDD 把转向变成「系统性再生」而非手工全链路透传。

工作流要点

从模糊想法出发，通过与 AI 迭代对话形成完整 PRD（澄清问题、边界、验收标准）。
研究型智能体 在写规格过程中补全技术、性能、安全、组织约束等上下文。
从 PRD 生成实现计划 ，把需求映射到技术与架构决策，并做持续一致性检查（歧义、矛盾、缺口）。
规格与计划足够稳定后即可生成代码；早期生成也可以是探索性的。
生产侧反馈（指标、事故、运维经验）回流到规格，形成持续演进。

六条原则（文档中的 Core Principles）

规格为通用语言；规格要可执行 （足够精确以生成系统）；持续精炼 ；研究驱动上下文 ；双向反馈 ；支持分支探索多种实现路径。

实践工具链

文档建议组合：AI 辅助写规格、研究智能体、代码生成、适合「规格优先」的版本控制、以及对规格文档的 AI 一致性检查。

Spec Kit 三条命令（概念层面）

/speckit.specify ：从功能描述生成结构化规格、分支与目录（如 specs/.../spec.md）。
/speckit.plan：基于规格产出实现计划、数据模型、合约、研究笔记、quickstart 等。
/speckit.tasks ：从 plan.md 等推导可执行任务列表（含可并行项）。

文档用「15 分钟聊天功能示例」对比传统大量写文档的流程，强调结构 + 自动化带来的速度与一致性。

模板如何约束 LLM 质量

规格层强调 WHAT/WHY ，避免过早写 HOW。
强制 [NEEDS CLARIFICATION]，减少瞎猜。
清单自检（需求完整、可测、成功标准可度量等）。
实现计划模板里的 Phase -1 门控（简洁性、反过度抽象等）。
层次化细节 （复杂内容拆到 implementation-details/ 等）。
测试优先的文件创建顺序（合约 → 测试 → 实现）。
抑制「可能将来要」的臆测功能。

Constitution（宪法）与九条中的重点

文档以 memory/constitution.md 为架构 DNA，举例包括：

库优先：功能先以可复用库形态存在。
CLI 约束：库通过 CLI 暴露能力，便于观测与测试（含 JSON）。
测试优先（硬性）：先写测试、确认失败（红），再写实现。
简洁与少抽象：项目数量上限、直接用框架能力等。
集成优先测试：倾向真实环境、合约测试等。

宪法原则可修订，但需记录理由、评审与兼容性评估。

结语

SDD 的目标不是消灭开发者创造力，而是把「从意图到代码」的机械翻译自动化 ，让规格、研究与代码在迭代中一起进化，从而缩小并消除规格与实现之间的结构性鸿沟。

开发实践（落地）

在「规格驱动、代码服从规格」的前提下，团队日常可以怎样协作、产出哪些工件、用什么节奏校验质量，见下文。

1. 推荐节奏：规格 → 计划 → 任务 → 实现

与 Spec Kit 思路一致，把一条需求拆成可版本化、可评审的四段：

阶段	产出物（示例）	实践要点
Specify	功能规格：`spec.md`（用户故事、验收标准、非功能约束）	只写 WHAT / WHY ；技术栈与目录结构延后到 plan；歧义用 `[NEEDS CLARIFICATION]` 标出，禁止静默猜测。
Plan	`plan.md`、可选 `data-model.md`、`contracts/`、`research.md`、`quickstart.md`	每项技术选型写明对应哪条需求；复杂细节拆到子文档，主计划保持可读。
Tasks	`tasks.md`（可执行、可标 `[P]` 并行）	任务粒度以「半天～两天能完成」为宜；依赖关系写清，避免大块不可验证的「实现整个模块」。
Implement	代码 + 测试 + 必要时更新规格	需求变更时先改规格/计划，再改实现；避免「代码已改、文档永远落后」。

下表从文档视角概括三份主文档各自要回答的问题、应写内容与建议上限（避免互相抢戏）：

文档	核心问题	主要内容	不该写太多的内容
`spec.md`	我们到底要交付什么？	目标、用户场景、需求、验收标准、非目标。	过多技术选型细节。
`plan.md`	这件事技术上怎么实现？	架构、模块划分、技术栈、依赖、数据模型、约束、验证方式。	重复写业务目标或把任务拆得太细。
`tasks.md`	现在具体先做哪几步？	可执行步骤、顺序、每步产物、完成定义、实施分期。	再讨论「为什么做」或大段架构设计。

小步提交：每个阶段都可以在独立分支上评审合并，而不是等「全写完」再一次性 PR。

2. 规格层的日常习惯

验收标准可测：每条需求都能对应到「Given-When-Then」或等价检查清单；避免「体验要好」这类不可验证表述。
持续消掉澄清项 ：开迭代第一件事可以是扫 [NEEDS CLARIFICATION]，能定的定下来，不能定的写清假设与风险。
非功能需求显式化：性能、安全、可观测性、兼容性、发布与回滚------在规格里占一小节，避免实现阶段临时拍脑袋。
研究笔记单独放 ：库对比、PoC 结论放在 research.md（或等价位置），别把长论证塞进 spec.md 冲淡业务叙事。

3. 实现计划层的门控（Gates）

在写第一行业务代码前，用简短清单自问（可与项目「宪法」或架构原则对齐）：

简洁性：是否可以用更少服务/模块满足当前验收？新增复杂度是否有记录理由？
少抽象：是否优先使用框架/标准库直接能力，而非过早封装？
合约先行 ：对外 API、事件、错误模型是否已有 contracts/ 或等价描述？
测试策略 ：合约测试 / 集成测试 / E2E 的边界是否和 quickstart 里的关键场景一致？

未通过门控时，在计划里开 「Complexity Tracking」（或等价小节）写明：为何需要例外、何时可简化。

4. 与 AI 协作时的实践

上下文顺序 ：先贴 spec.md 关键段落与 contracts/，再让模型写代码；减少「凭空实现」导致的返工。
一次只推进一个垂直切片 ：按 tasks.md 一条条来，每完成一条就跑对应测试与 quickstart 场景。
生成后必做 diff 审阅：重点看是否引入规格未要求的特性、是否弱化错误处理与可观测性。
把线上反馈写回规格 ：事故根因、性能瓶颈、安全补丁 → 变成新的约束或验收项，形成 SDD 所说的双向反馈。

5. 常见反模式（避免）

规格里堆满框架与类名，需求一变全文失效。
只有 PRD 没有可执行的验收标准，AI 与人类都对「完成」各有一套理解。
计划无限膨胀却从不生成 tasks.md，执行时仍靠口头分工。
代码先行、规格后补，最后规格沦为「说明书写给外人看」，与真实行为不一致。

6. 最小可行落地（无 Spec Kit 命令时）

即使未安装 github/spec-kit 的 /speckit.* 命令，也可在仓库中自建目录约定，例如：

text 复制代码

specs/<feature-branch-or-id>/
  spec.md
  plan.md
  tasks.md
  contracts/        # 可选
  research.md       # 可选
  quickstart.md     # 可选

流程不变：规格评审通过 → 计划评审通过 → 任务拆解 → 按任务开发与测试 → 合并时检查规格与代码是否仍一致。

7. 延伸阅读

SDD 方法论原文：spec-driven.md
与「文档驱动开发」结合时，可对照本仓库技能 doc-driven-dev-workflow（需求 → 设计 → 测试用例 → 实现 → 单测）做裁剪合并。