ai-sdd-check

AI-SDD 漂移检测

定位

只读操作，不修改任何文件。检测 .ai/doc/ 中的规范文档与实际代码之间的一致性。

前置检查

1. 检查 .ai/ 是否存在 → 如不存在，提示先运行 /ai-sdd-init
2. 检查 .ai/doc/ 是否存在 → 如不存在，提示先运行 /ai-sdd-reverse 或手动创建
3. 检查 .ai/doc/ 下是否有 doc 文件 → 如为空，提示无文档可检查

执行流程

步骤 1：读取所有规范文档

扫描 .ai/doc/ 下的所有文件，记录：

• 模块列表（从 00-架构.md）
• 功能列表（从 01-需求.md）
• API 契约（从 03-详细设计/*.md）
• 文档结构（是否符合角色定义）

步骤 2：读取对应代码

根据 doc 文件中描述的模块和功能，读取对应的源代码。

步骤 3：逐文件对比

按四个维度检测：

维度 1：架构漂移

• 00-架构.md 中的模块列表 vs 代码中的实际模块目录
• 检测：模块新增、删除、重命名

维度 2：需求漂移

• 01-需求.md 中的功能列表 vs 代码中的 API 路由/UI 组件
• 检测：功能新增、功能废弃

维度 3：设计漂移

• 03-详细设计/<模块名>.md 中的 API 契约 vs 代码中的实际实现
• 检测：参数变更、返回值变更、错误码变更

维度 4：结构漂移

• doc 文件的组织方式是否符合角色定义
• 检测：追加式更新（内容堆在末尾）、内容混乱（实现细节混入需求文档）、大量原始代码

步骤 4：生成报告

=== AI-SDD 健康检查报告 ===

[文件路径]
  [状态] [描述]（失效类型：[类型]）

状态说明：
  ✅ 一致     — 文档与代码匹配
  ⚠️ 轻微漂移 — 小的过时（如缺少新增参数）
  ❌ 严重漂移 — 文档与代码根本对不上
  📭 缺失     — 代码中有模块但没有对应 doc
  🗂️ 结构问题 — 追加式更新、内容混乱、角色不符

失效类型（对应 S06 失效模式）：
  文档腐烂 — 内容与事实不符
  文档质量退化 — 内容正确但组织混乱
  规范过度设计 — 文档比实现还重
  上下文泄漏 — 实现偏离了最终设计

覆盖范围说明：
  本 skill 覆盖 S06 七种失效模式中可自动检测的 4 种（上表）。
  另外 3 种属于人类行为模式，需要开发者自评：
  - 模式僵化 → 每季度反思"流程本身是否需要调整"
  - AI 盲从过时文档 → 通过"需求漂移"维度间接发现
  - 人类橡皮图章化 → 每 5-10 个任务做一次深度审查

总结：X 个一致，Y 个轻微漂移，Z 个严重漂移，W 个缺失，V 个结构问题

[如有漂移] 建议：运行 /ai-sdd-rebuild 修复严重漂移和结构问题

三级审计模式

用户可通过触发词选择审计深度：

模式	触发词（举例）	检查范围
快速检查	"快速检查文档"	仅检查架构漂移（维度 1），5 分钟
标准检查（默认）	"检查文档漂移"	四维度全查
深度审计	"深度审计文档"	四维度 + 结构漂移逐文件详细分析 + 生成修复建议清单

保鲜检查操作（供功能完成后的例行保鲜使用）

1. 重新读取相关 doc 文件全文，理解其结构和当前内容
2. 对照代码实际行为逐条核对文档描述是否仍然准确
3. 记录差异：将不一致处写入 .ai/project-log.md 的「待同步文档」区段
4. 发现文档与代码不符时：立即标记 → 报告人类 → 不要假装文档是对的

注意事项

• 本 skill 不修改任何文件
• 对于"轻微漂移"，可以在报告中简要说明修复建议
• 对于"严重漂移"和"结构问题"，建议用户运行 /ai-sdd-rebuild