doc-ctr

用途

doc-ctr 用于在 SDD（规范驱动开发）工作流中创建数据契约（Data Contracts，CTR），这是可选的第 8 层产物，用于定义 API 契约、数据模式和接口规范。

上游依赖：BRD（第 1 层）、PRD（第 2 层）、EARS（第 3 层）、BDD（第 4 层）、ADR（第 5 层）、SYS（第 6 层）、REQ（第 7 层）。

下游产物：SPEC（第 9 层）、TSPEC（第 10 层）、TASKS（第 11 层）、代码（第 12 层）。

何时使用

已完成 BRD 至 REQ（第 1-7 层）
需要定义 API 契约或数据模式
多个团队/服务需要共享契约
构建微服务或分布式系统
REQ 第 3 节（接口规范）需要正式契约
该层为可选（第 8 层），若契约简单可跳过

主要能力

强制双文件格式

每个契约需要两个文件：

Markdown 文件（.md）：文档控制、契约概览、业务上下文、使用示例、可追溯性
YAML 文件（.yaml）：OpenAPI 3.0 或 JSON Schema、正式契约定义、验证规则、示例载荷

示例：

ai_dev_ssd_flow/08_CTR/CTR-01_data_validation.md
ai_dev_ssd_flow/08_CTR/CTR-01_data_validation.yaml

文档控制字段（9 个必填）

CTR ID、标题、状态（Draft/In Review/Active/Deprecated）、版本（语义化版本 Major.Minor.Patch）、创建日期、作者、负责人、最后更新日期、SPEC-Ready 评分（目标 ≥90%）。

必需章节（12 节 MVP 结构）

文档控制
上下文
契约定义
满足的需求
接口定义
错误处理
质量属性
版本策略
示例
验证
可追溯性
参考

可选附录：附录 A 备选方案、附录 B 实现说明。

元素 ID 格式

模式：CTR.{DOC_NUM}.{HASH}（3 段，点分隔）

接口：CTR.02.1601
数据模型：CTR.02.1701
契约条款：CTR.02.2001

已移除的旧格式：INT-XXX、MODEL-XXX、CLAUSE-XXX、IF-XXX、DM-XXX、CC-XXX。

YAML 契约格式

支持 OpenAPI 3.0（用于 API）和 JSON Schema（用于数据模型）。

契约版本管理

语义化版本 Major.Minor.Patch：

Major：破坏性变更（不兼容）
Minor：新功能（向后兼容）
Patch：缺陷修复（向后兼容）

SPEC-Ready 评分系统

用于衡量 CTR 成熟度和进入 SPEC 阶段的准备度。

评分与状态映射：

≥90%：Active
70-89%：In Review
<70%：Draft

评分标准：模式完整性（35%）、错误处理（25%）、质量属性（20%）、可追溯性（10%）、文档（10%）。

质量门：评分 <90% 会阻止 SPEC 产物创建。

按服务类型的目录组织

适用于大型项目（30+ 契约）：

CTR/
├── agents/              # 智能体间通信
├── mcp/                 # MCP 服务器契约
├── infra/               # 基础设施服务
└── shared/              # 横切契约

使用时机：<10 契约用扁平目录；10-30 可选子目录；30+ 强制子目录。

使用方式

前置条件

创建前必须列出已有上游产物：

ls docs/01_BRD/ docs/02_PRD/ docs/03_EARS/ docs/04_BDD/ docs/05_ADR/ docs/06_SYS/ docs/07_REQ/ 2>/dev/null

仅引用存在的文档，上游产物类型确实不存在时使用 null，禁止使用 BRD-XXX 或 TBD 等占位符，不要创建缺失的上游产物。

创建前需阅读：共享标准、上游 REQ（尤其第 3 节接口规范、第 4 节数据模式）、模板、创建规则、验证规则、验证脚本。

保留 ID 豁免（CTR-00_*）

保留 ID 000 的文档完全豁免验证，包括索引文档、可追溯性矩阵模板、词汇表、注册表、检查清单。

创建流程

阅读上游产物，聚焦 REQ 第 3 节和第 4 节
保留 ID 编号（从 2 位数字开始，如 CTR-01、CTR-99、CTR-102）
创建双格式 CTR 文件

嵌套文件夹规则（强制）：所有 CTR 文档必须使用嵌套文件夹。

位置：

标准：docs/08_CTR/CTR-NN_{slug}/CTR-NN_{slug}.md + .yaml
基于服务：docs/08_CTR/{service_type}/CTR-NN_{slug}/CTR-NN_{slug}.md + .yaml

创建目录：

mkdir -p docs/08_CTR/CTR-NN_{slug}/

可追溯性标签

第 8 层（CTR）必须包含第 1-7 层的标签，共 7 个标签：

@brd: BRD.01.0103
@prd: PRD.01.0702
@ears: EARS.01.2501
@bdd: BDD.01.1401
@adr: ADR-033, ADR-045
@sys: SYS.01.2601
@req: REQ.01.2703

验证检查

Tier 1 错误（阻断）：9 个必填文档控制字段、双文件格式、SPEC-Ready 评分格式、YAML 模式验证、累积标签（7-8 个）、元素 ID 格式。

Tier 2 警告（建议）：使用示例、错误处理、版本策略、验证规则。

Tier 3 信息：目录组织、消费者/提供者识别。

Pre-Commit 钩子

CTR 验证通过 pre-commit 钩子自动执行，包括核心验证器、质量门、SPEC-Ready 评分钩子。

适用场景

多团队/多服务共享 API 契约
微服务或分布式系统开发
需要正式化 REQ 第 3 节接口规范
大型项目（30+ 契约）需要按服务类型组织

限制

该层为可选，契约简单时可跳过
评分 <90% 会阻止 SPEC 产物创建
必须使用双文件格式（.md + .yaml）
必须使用嵌套文件夹
禁止使用旧版元素 ID 格式
禁止创建缺失的上游产物
保留 ID 000 的文档豁免验证