ai-sdd-rebuild

AI-SDD 文档重建

定位

当文档漂移过大，逐条修补不如重写时使用。从代码重新生成 .ai/doc/ 规范文档，严格遵循质量规则。

前置检查

与 /ai-sdd-check 相同：

1. 检查 .ai/ 是否存在
2. 检查 .ai/doc/ 是否存在且有内容

执行流程

步骤 1：执行漂移检测

按照 /ai-sdd-check 的流程，执行完整的四维度漂移检测。

步骤 2：展示诊断结果

输出检测报告，列出所有漂移项。

步骤 3：逐文件重建

对每个需要重建的 doc 文件，执行以下流程：

1. 读取代码：不参考现有文档内容，纯粹从代码梳理
2. 确定文件角色：这个 doc 文件应该写什么？（参考下方文件角色表）
3. 按角色生成：严格遵循该文件的角色定义组织内容
4. 质量检查：重建完成后，对照质量规则自检

步骤 4：更新 project-log.md

在 .ai/project-log.md 的变更时间线中记录：

### [日期] 文档重建
**触发原因**：[漂移描述]
**重建范围**：[哪些文件被重建]
**依据**：以真实代码为准，不参考过时文档

---

文件角色表

以下为 .ai/doc/ 中四个文件的完整角色定义。重建时必须严格遵守。

文件	角色	读者	应该写什么	不该出现的内容
00-架构.md	系统整体架构	所有人	模块划分、模块间依赖关系图、数据流、外部依赖、技术债务	需求细节、API 契约、实现代码
01-需求.md	功能需求定义	产品/人类决策者	功能列表（F-XXX 编号）、功能描述、验收标准、RFC 2119 行为约束	实现细节、API 路径、数据库字段
02-技术选型.md	技术选型理由	开发者/架构师	技术栈总览、候选方案对比、关键依赖清单、构建/测试/部署现状	需求描述、API 细节、业务逻辑
03-详细设计/xxx.md	模块详细设计	AI（执行会话）	数据模型、API 契约、核心业务流程、状态机	需求动机、全局架构、选型理由

---

重建质量规则

规则 1：以真实代码为准

• 不参考现有文档内容（它已经过时了）
• 一切以代码实际行为为准
• 不确定的标注"待确认"，不瞎编

规则 2：以"创建心态"书写

• 不追加内容到文件末尾
• 当作首次编写该文件——通读代码后，从头组织内容
• 每次更新必须重读全文理解结构

规则 3：结构化表述

• 精确性 > 完整性（少而准）
• 用表格、列表、Mermaid 图、代码块
• 不要出现大量原始代码——用结构化描述代替
• 每个章节有明确标题，读者通过标题即可判断相关性

规则 4：尊重文件角色

• 每个文件有明确的角色定义（见上方文件角色表）
• 只写属于该角色的内容
• 发现内容放错了文件 → 拆分到正确的文件

规则 5：不放实现过程

• 不记录"讨论了 A 和 B，选了 A" → 直接写"选择 A，理由：[...]"
• 被否决的方案不写入规范文档
• 设计文档像"合同"，不像"会议纪要"

---

重建 Prompt（内部使用）

对每个需要重建的文件，使用以下思维框架：

我需要为 [模块名] 重新生成 [文件角色]。

要求：
1. 不参考现有的 [文件路径]——它已经过时
2. 纯粹从代码梳理，以真实代码为准
3. 这个文件的角色是 [角色描述]，只写属于该角色的内容
4. 用结构化格式（表格、列表），不要大段叙述
5. 不要出现大量原始代码
6. 不确定的标注"待确认"