用途:在既有代码库上采用 DDD 时,评估遗留文档债务、为存量代码生成覆盖率报告,或准备从非 DDD 迁移到 DDD 治理的开发计划。当 ddd-book 初始化发现已有代码缺少 DDD 覆盖时也可调用。不适用于无既有代码的全新项目(用 ddd-book 初始化)、已受 DDD 治理的代码(用 ddd-verify 做一致性检查)或单次变更的合规检查(用 ddd-verify)。
主要能力:核心原则是既有代码已有行为,未被文档化的行为即为缺口,缺口必须可见。流程分六步:一、扫描代码库,读取 project-context.yaml(不存在则用 ddd-book 创建),识别源码目录结构、统计符号数量、按架构层(domain、application、infrastructure、UI)分类目录、识别入口点与公共 API 及边界穿越。二、从代码提取行为声明,每个声明初始 status: unknown 且 sources 为空。三、将声明与现有文档匹配,检索 ADR、CONTEXT.md、README、wiki、代码注释与 JSDoc/docstrings、测试名称与描述,更新来源引用并设置状态为 known-and-supported、unsupported 或 unknown。四、标记缺口与矛盾,产出审计报告,含覆盖率、按严重度排序的缺口、代码行为与文档行为的矛盾、遗留债务。五、生成 Book 草稿,包括 book.yaml、knowledge-map.yaml、claims.yaml、trace-matrix.yaml 及针对 unknown/unsupported 声明的例外。六、按 P0 至 P3 排定整改优先级:P0 为关键安全/数据完整性缺口与代码文档矛盾,P1 为核心领域逻辑高严重度缺口与缺失 ADR,P2 为中等严重度缺口与内部工具缺文档,P3 为非关键代码低严重度缺口。
使用方式与增量采用:分阶段推进,先修复全部 P0 缺口,为关键声明创建证据或例外;随后审计区域的新变更纳入 DDD 治理,存量代码保持豁免;当变更触及存量代码时将其纳入 DDD 范围;定期重新审计以跟踪覆盖率增长与债务减少。
限制与注意:部分审计会造成虚假信心,未审计代码的缺口未知,应全部审计或明确标记为 grandfathered;将一切标记为 grandfathered 会违背初衷;无矛盾不代表代码正确,需将代码状态机与 ADR、测试行为与文档契约对照。规范参考 SPEC.md §17.3、§17.4、§18.1、§14。具体命令与安装方式暂未提供。