鸭梨公共文档

主题

AI Agent 时代如何落地 SDD：从规范编写到运行时诊断的实践框架 ​

Spec-Driven Development（SDD）在 AI Agent 时代的价值，不是“多写几份文档”，而是把意图、约束、实现、验证和运维反馈放到同一条可追溯链路里。本文基于原文完整阅读后重写，目标是给出可执行、可推广、可度量的团队实践框架。

1 人机分工：先解决“谁做判断，谁做生成” ​

SDD 的第一原则是把“业务判断”与“机械实现”拆开。

  • AI 负责机械完整性：代码生成、测试补齐、边界覆盖、格式一致性。
  • 人类负责判断性决策：fail-open 或 fail-close、一致性或可用性、性能或成本。
  • 规范评审必须由人类把关，尤其是业务规则、抽象边界、用户体验与合规要求。

一个可直接使用的协作流程如下：

text
1. AI 起草 spec（保证结构和覆盖）
2. 人类评审业务意图与成功标准
3. AI 修订 spec / plan / tasks
4. 人类批准关键设计决策
5. AI 实现代码与测试
6. 人类做上线前风险确认

2 规范治理：把规范当成“代码级资产” ​

如果规范不进入版本管理，SDD 会很快退化为“会过期的说明文”。

2.1 版本管理最小纪律 ​

  • 每次 spec.md 更新都必须提交版本库。
  • 规范变更采用语义化粒度：major、minor、patch。
  • 规范修改走独立分支评审，不在主分支直接改写。
  • 保留可追溯链路，让 AI 可以通过 git diff 与 git blame 解释生成依据。

2.2 活文档更新触发器 ​

以下事件发生时，规范必须同步更新，而不是“代码先行、文档补票”：

  • 数据模型调整
  • API 合约变化
  • 性能压测暴露瓶颈
  • 安全审计新增规则
  • 集成联调发现接口不兼容

3 渐进采用：从单一服务试点，不做一刀切改造 ​

原文最值得借鉴的一点是“先试点验证价值，再组织扩散”。

  1. 试点阶段（1-2 个月）：选择新服务或重构服务，验证代码评审效率和集成返工率。
  2. 扩展阶段（3-6 个月）：扩展到相邻服务，建立跨团队规范共享与引用机制。
  3. 标准化阶段（6-12 个月）：沉淀模板、工具链、培训机制和度量看板。

与“行政推动全员上车”相比，“先让愿意尝试的团队跑通并形成示范”通常更有效。

4 知识资产化：规范是组织记忆，不只是开发输入 ​

SDD 的组织价值在于把隐性知识从“人脑”迁移到“规范库”。

  • 架构决策进入 constitution.md 与 plan.md。
  • 业务规则进入 spec.md，并映射到测试。
  • 集成约定以跨规范引用的方式显式表达。
  • 安全与合规规则前置到规范层，而不是上线前临时补丁。

为了提高可发现性，建议在规范中加入结构化元数据，例如 owner、depends-on、security-level、tags，使检索与影响分析可自动化。

5 上下文工程：控制上下文噪声，提升 Agent 命中率 ​

原文明确指出：大模型上下文窗口很大，但注意力资源有限。一次性灌入超长规范会导致注意稀释。

5.1 三层上下文架构 ​

  • 宪法层：不可违背的全局约束（安全、架构、合规）。
  • 共享层：跨模块规则（数据模型、性能基线、公共 API 约定）。
  • 功能层：当前任务的局部规范与实现细节。

5.2 三种注入策略 ​

  1. 渐进式加载：先约束，再功能，再实现。
  2. 检索增强：按任务关键词检索相关规范片段并限制 token 预算。
  3. 模块化提示词：每次任务只绑定必要上下文，避免“全量喂料”。

6 双层约束：隐式意图 + 显式验证 ​

SDD 的质量上限，来自“隐式约束”与“显式约束”的协同。

  • 隐式约束：业务目标、用户旅程、架构原则、安全红线。
  • 显式约束：类型系统、OpenAPI、测试用例、静态检查规则。

一个可执行的转换路径是：先用自然语言表达意图，再落地为可验证工件，让 AI 的“语义理解”最终接受自动化验证。

7 运行时闭环：把 SDD 延伸到诊断与修复 ​

原文的关键升级点是“从构建期规范走向运行期规范”。

  • 通过 MCP 暴露日志、指标和错误摘要给 AI。
  • 在 spec/runtime.md 中定义延迟、错误率、告警阈值与常见故障诊断路径。
  • 线上问题出现时，AI 结合运行时数据与规范给出根因分析、修复建议与回写项。

这让研发流程从线性过程升级为闭环系统：

text
设计规范 → 生成实现 → 运行监控 → 问题诊断 → 修复与回写规范 → 再验证

8 适用性判断：不是所有项目都要“全量 SDD” ​

8.1 强适用场景 ​

  • 多团队协作、生命周期长、业务复杂、合规压力大。
  • 典型场景：企业级 SaaS、金融科技、医疗健康、跨组织开源协作。

8.2 弱适用场景 ​

  • 快速原型、一次性脚本、探索性研究项目。
  • 这些场景更适合“轻量规范 + 实验记录”，先保证试错速度。

8.3 成熟度演进路径 ​

text
Level 0: 传统开发
Level 1: AI 辅助开发
Level 2: 规范增强（部分 SDD）
Level 3: 完整 SDD（Specify → Plan → Tasks → Implement）

9 团队落地模板：30 天可执行动作 ​

  1. 选择 1 个试点服务，定义明确边界和成功指标。
  2. 建立最小规范集：constitution、spec、plan、tasks。
  3. 明确人机边界：业务和架构关键决策必须人工批准。
  4. 规范变更强制入库，建立变更日志与分支评审。
  5. 加入一致性检查：规范、API、测试三方对齐。
  6. 建立跨规范依赖图，启用变更影响分析。
  7. 将关键运行时指标纳入规范，打通故障回写流程。
  8. 每两周复盘一次：评审时间、集成返工率、规范同步率。

10 总结 ​

在 AI Agent 时代，SDD 的本质不是“写得更像文档”，而是“让规范成为真实且可执行的系统事实来源（Single Source of Truth）”。

当团队完成三件事——规范版本化、约束可验证、运行时可回写——AI 才能从“会写代码”升级为“能稳定交付”。

参考链接 ​