# SDD 流程与规格索引

SDD 是 Software Design Document（软件设计文档）；本项目以版本化设计契约驱动开发。需求说明“做什么”，设计说明“如何实现”，测试证据说明“是否做到”。

## 分级与最小产物

按最高影响定级，不以代码行数定级。

| 级别 | 范围 | 实施前产物 |
| --- | --- | --- |
| S0 | 文案、格式、无行为变化的文档纠错 | 明确范围和检查方式，无需单独规格 |
| S1 | 恢复已批准行为的缺陷修复、契约内重构 | 任务记录中的问题、依据、不变量、验收步骤 |
| S2 | 新功能、API/IPC/配置/数据模型及跨模块行为变更 | 使用 [_template.md](_template.md) 创建或修订功能规格并评审 |
| S3 | 权限、安全、迁移、删除数据、生产部署 | S2 + 风险、兼容、审计/观测（按产品边界）、发布与恢复方案 |

规格保存在 `docs/specs/<domain>/<slug>.md`。持续开发同一能力时修订已有规格，不重复创建。小功能可将需求与设计分节写在同一文件；大型需求可单独成文并引用。不适用项写明原因。

## 工作流与权限

1. 调研：读取实际代码、适用规则、测试和未提交改动；区分事实、假设、提案。
2. 需求：定义范围、非目标、用户场景、FR/NFR 及 AC；未知指标标待确认。
3. 设计：明确边界、接口、数据、失败路径与测试预期，再评审。
4. 实现：依据已批准版本实施，允许自主选择契约内实现细节。
5. 验证：将每条 AC 映射至实现位置和测试证据，记录未运行项。
6. 交付：报告差异、结果和剩余问题，不把构建成功等同功能验收。

S2/S3 的业务行为和契约在实施前需要明确批准依据。已有明确授权覆盖该设计版本与范围时，记录原授权，不重复询问。Agent 不得将“需求看起来清楚”视为自行批准新设计的依据。
阻塞问题只暂停依赖它的实现，其他调研、设计和独立工作可继续。

## 版本与状态

- 设计状态：Draft → In Review → Approved → Superseded。
- 实现状态单独记录：Not Started / In Progress / Implemented / Verified。
- 批准记录包含版本、批准人、日期和可追溯依据；模板不预填批准人。
- 冻结代表版本受控。改变接口、数据语义、权限或验收预期时，先记录旧/新差异及影响，新版本重新评审；批准旧版本不等于批准新版本。
- 现有代码只能作为“待评审现状基线”，不能直接标为已批准设计。
- 文档更正但不改变契约时记录更正即可；不得借文档修订掩盖实现偏差。

## 契约归属与完成条件

SDD 明确接口、Schema、迁移及依赖锁文件的权威路径和版本，不复制多份字段表。当前代码与设计冲突时先判断是缺陷还是设计变更；不能自动以代码覆盖设计。
仓库规范不覆盖适用的系统/工具限制；后续明确用户指令导致契约变化时应同步修订，不静默执行旧设计。

测试场景和预期结果在实现前定义，测试代码可随实现完成。覆盖受影响的成功、边界、失败、权限和兼容行为。
所有 AC 有通过证据且实现与契约一致，才可标 Verified。Blocked/Not Run 不算通过；记录命令/环境/日期或人工步骤及结果，不能仅写“已检查”。
本文件是工作约定，不代表已启用 CI 或分支保护；需要强制禁止合并时须另行配置仓库门禁。

## 规格索引

当前仅建立流程与模板，尚无已批准功能规格。

| 规格 | 版本 | 设计状态 | 实现状态 | 批准依据 |
| --- | --- | --- | --- | --- |