第 15 天：SDD 四类契约——数据、行为、质量、可观测性

SDD + Harness 四周学习计划 · Week 3 · Day 15（工程化闭环第 1 课 / 全计划第 15 课）

今日主题：SDD 四类契约：数据契约（Schema）、行为契约（API 边界/异常）、质量契约（延迟/吞吐/准确性）、可观测性契约（日志/指标/追踪）

建议用时：60–90 分钟｜前置：Week 2 的 Harness 四大护栏 + 你的 Day5-spec-<功能名>.md

输出物：一张「四类契约速查卡」+ 给 Day 5 spec 验收标准做的契约分类标注

0. 一句话剧透

Week 2 你学到：Harness 把 AI 的执行管起来——规则、权限、验证、隔离四道护栏，让 AI 不跑偏。但「不跑偏」只是过程可控；Week 3 的主题是从「能跑」到「可控」——今天开门的四类契约，就是把「什么叫做好了」从一句句验收文字，升级成四类可以工程化落地、可被工具检查的边界。

记住 Week 2 的结论：SDD 告诉 AI 做什么，Harness 保证 AI 做对。 Week 3 在中间补上一句：契约告诉双方「做对了」长什么样。

1. 今日目标（学完你能做到）

能不看讲义说出四类契约的名称和各自管什么（数据 / 行为 / 质量 / 可观测性）
能为每类契约至少举出一个落地载体（如 JSON Schema、API 边界与异常、延迟指标、日志规范）
能说清四类契约与 Day 3 spec 验收标准的关系（契约 = 验收标准的工程化升级）
能用自己的话讲：为什么 Week 3 的主题是「从能跑到可控」
完成动手练：给 Day 5 spec 的验收标准逐条标注「属于哪类契约」

对应计划 Week 3 目标：掌握 SDD 四类契约与持续交付体系，端到端交付一个带证据链的功能——今天是第一步。

2. 学习动线（建议时间分配）

步骤	内容	用时
1	第 3 节：回顾 Week 2，接入 Week 3 主题	10 分钟
2	第 4 节：四类契约逐个拆（主菜）	30 分钟
3	第 5 节：契约与 spec 的关系 + RAG 三层落地	10 分钟
4	动手练（第 6 节）：分类标注 + 速查卡	20–30 分钟
5	自测（第 7 节）	10 分钟

3. 回顾 Week 2：Harness 把执行管起来了

Week 2 的核心一句话：AI 的执行不可信，所以要上护栏。 你学到的四大护栏是：

护栏	管什么	Week 2 对应课
CLAUDE.md + Skills	规则：告诉 AI 项目的规矩和可用技能	Day 8
Plan Mode + Permission	权限：先规划后执行，危险操作要授权	Day 8
Hooks	验证：事后自动检查（如 pre-commit hook）	Day 8
Subagents	隔离：上下文隔离，防止串扰	Day 8

再加上 sdd-harness 的落地形态：.ai/ 目录存放规则、pre-commit hook 强制「改了代码必须同时改 spec」（feat/* 分支改代码不碰 spec 会被拒绝，SH_SDD_SKIP=1 是显式例外）、以及 spec → story → implement → verify → review → release → phase-close 七命令循环。

但 Week 2 留了一个口子：hook 拦的是「你有没有动 spec」，它不检查「你写的 spec 够不够硬」。这正好是 Week 3 要补的——契约把 spec 的每一条验收变成可以被工具执行检查的东西。

4. 四类契约逐个拆（今天的主菜）

来源：腾讯云《SDD 规范驱动 + Harness：AI 全栈开发从「能跑」到「可控」》。四类契约的定义与载体均依据该文已核验素材；未覆盖处标「待核验」。

4.1 数据契约（Schema）——定义「数据长什么样」

管的是：数据结构与字段约束。上下游（前端/后端/模型/数据库）交换数据时，双方必须对「字段有哪些、类型是什么、哪个必填、取值范围多大」达成一致，否则一个字段名对不上就是线上事故。

落地载体（已核验）：JSON Schema / Protobuf / Avro / Pydantic。它们把「数据长什么样」写成可校验的声明，代码生成和数据校验都从这里来。

4.2 行为契约（API 边界/异常）——定义「接口怎么响应」

管的是：API 的预期行为、边界条件、异常处理。不只定义「正常时返回什么」，还要定义「输入越界时返回什么错误码、未登录返回什么、依赖挂了返回什么」。

数据契约管「数据形状」，行为契约管「接口行为」——一个管静态结构，一个管动态响应。

4.3 质量契约（延迟/吞吐/准确性）——定义「非功能性要求」

管的是：延迟、吞吐、准确性指标。功能对了还不够，「多快、多稳、多准」要提前写死。Day 7 你校准过 spec 里的数字量级（「快」→「≤500ms」），质量契约就是把这类数字固定下来、进入自动化监控。

4.4 可观测性契约（日志/指标/追踪）——定义「运行时能不能看清」

管的是：日志、指标、追踪的标准化。代码上线后出了事，能不能快速定位？要求所有服务按统一格式打日志、暴露统一指标、链路可追踪——这是「运维」阶段的可观测要求（呼应 Week 3 末的五阶段闭环里的「运维」）。

4.5 四类契约速查表

契约	管什么	典型载体	一句话记忆
数据契约	数据结构与字段约束	JSON Schema / Protobuf / Avro / Pydantic	数据长什么样
行为契约	API 预期行为 / 边界 / 异常	OpenAPI、契约测试	接口怎么响应
质量契约	延迟 / 吞吐 / 准确性	指标阈值、SLO	多快多稳多准
可观测性契约	日志 / 指标 / 追踪标准化	日志规范、Metrics、Tracing	出事能不能看清

5. 契约与 spec 的关系：验收标准的工程化升级

Day 3 你学的 spec 验收标准（AC），本质已经是「行为契约」的文字版：Given-When-Then + 数字。四类契约做的事是把它扩展成四类并工程化：

spec 里「数据校验规则」→ 数据契约（写进 Schema，代码和校验自动生成）
spec 里「接口怎么响应」→ 行为契约（写进 API 定义，契约测试来验）
spec 里「多快多稳」→ 质量契约（写成指标阈值，监控来验）
spec 里「出事了怎么查」→ 可观测性契约（写成日志/指标/追踪规范）

文中还给了 RAG 三层落地的示例（已核验）：API 契约层 / 模型行为规范层 / 质量门禁层——说明这套契约思想不止用于普通 API，AI 应用的「模型调用」同样可以套：API 层管输入输出格式，模型行为层管 Prompt 与回答规范，质量门禁层管效果指标。

一句话：Day 5 你写的是「人读的验收」，Week 3 你开始把它变成「机器能检查的契约」。

6. 动手练（约 20–30 分钟）

6.1 给 Day 5 spec 的验收标准分类（15 分钟）

拿出你的 Day5-spec-<功能名>.md，把每条验收标准（AC-1、AC-2…）按四类契约归类：

我的验收条款	属于哪类契约	理由（一句话）
AC-1：___	□ 数据 □ 行为 □ 质量 □ 可观测性	___
AC-2：___	□ 数据 □ 行为 □ 质量 □ 可观测性	___
AC-3：___	□ 数据 □ 行为 □ 质量 □ 可观测性	___

自检：如果你的 spec 里质量契约一条都没有（没有延迟/吞吐/准确性数字），说明 Day 7 的量级校准还没做透——回去补；这是 Day 18 转写 Gherkin 时的素材缺口。

6.2 填一张四类契约速查卡（10 分钟，给 Day 21 周复盘用）

数据契约：管____，载体____，我项目里的例子____
行为契约：管____，载体____，我项目里的例子____
质量契约：管____，载体____，我项目里的例子____
可观测性契约：管____，载体____，我项目里的例子____

7. 自测题

四类契约分别叫什么？各自管什么？
JSON Schema 和 Pydantic 解决的是哪一类契约的问题？
「接口 500ms 内返回、错误率 <0.1%」属于哪类契约？
数据契约和契约测试各属于哪一类契约的落地方式？
spec 的验收标准（AC）和四类契约是什么关系？
RAG 三层落地是哪三层？说明什么？
为什么说 Week 3 的主题是「从能跑到可控」？Week 2 和 Week 3 的分工差异在哪？

答案与提示：

数据（结构/字段约束）、行为（API 行为/边界/异常）、质量（延迟/吞吐/准确性）、可观测性（日志/指标/追踪）。

数据契约。

质量契约（非功能性指标）。

数据契约 → JSON Schema/Protobuf/Avro/Pydantic；行为契约 → 契约测试。

契约是验收标准的工程化升级：验收把「完成」写清楚，契约把「完成」变成可被工具检查的边界。

API 契约层 / 模型行为规范层 / 质量门禁层——说明契约思想同样适用于 AI 应用（模型调用也要立契约）。

Week 2 管「执行过程」（护栏防跑偏），Week 3 管「完成定义」（契约让完成可验证）——从「能跑」到「可控」。

SDD+Harness 四周学习计划 · Week 3 · Day 15