项目文档一致性检查与修复

工作目标

确保项目中所有文档之间一致：没有冲突、没有矛盾、没有过时的引用。一个文档中的变更必须在相关文档中同步体现。

这些文档将被交给另外的 AI 工具，由其独立完成整个产品的开发。因此文档的一致性直接决定了开发的正确性。

文档发现

运行时自动扫描项目根目录下所有 .md 文件（排除 .claude/、node_modules/、.git/），列出全部待检文档。

文档层级与检查力度

不同文档承载不同使命，不能用同一个力度去对齐。根据文档的性质分为以下层级：

Tier 0 — 产品规格源（最终权威）

定义"做什么"。一切以此为准。

典型文档：PRD.md

Tier 1 — 技术设计源

定义"怎么做"。必须可追溯到 Tier 0。

典型文档：DESIGN.md

Tier 2 — 实施计划源

定义"按什么顺序做"。必须可追溯到 Tier 0 和 Tier 1。

典型文档：DEVELOPMENT_PLAN.md

Tier 3 — 衍生/说明文档

面向人类读者的概览、入口、使用说明。从规格源派生，不要求包含全部细节，但其中出现的事实性内容（名称、版本、功能列表、技术栈等）必须准确。

典型文档：README.md、CHANGELOG.md、LICENSE 等

层级判定规则

首次运行时，对自动发现的每个文档执行以下判定：

1. 读取文档前 30 行，识别其标题、定位声明、目录结构
2. 按以下特征归类：

3. 如果无法判定，通过 AskUserQuestion 询问用户

检查维度（按层级组合）

Tier 0 ↔ Tier 1 ↔ Tier 2：规格级检查（全面 7 维度）

这是核心检查链。三者构成严格的上下游追溯关系。

1. 跨文档一致性：同一个功能、模块、接口、数据模型在多个文档中的描述是否完全一致？
2. 完整性：Tier 1 是否覆盖了 Tier 0 中的每一个需求？Tier 2 是否覆盖了 Tier 1 中的每一个设计要素？
3. 冲突检测：是否存在矛盾（同一功能的不同规格描述、技术选型不一致、时间线不兼容）？
4. 可追溯性：Tier 0 中的每个需求能否追溯到 Tier 1 中的设计章节和 Tier 2 中的开发任务？
5. 术语一致性：是否使用了统一的术语？同一个概念是否用了不同的名称？
6. 过时引用：某个文档是否引用了另一个文档中已被删除或重命名的功能/章节？
7. 范围对齐：范围是否一致？Tier 1/2 中是否包含了 Tier 0 范围之外的内容？Tier 0 中是否有遗漏未被覆盖？

Tier 3 ↔ Tier 0/1/2：事实级检查（轻量 3 维度）

Tier 3 是概览性文档，不承担规格职责。只检查其中出现的显式事实是否准确。

1. 事实准确性：产品名称、版本号、技术栈、功能列表、依赖版本等是否与规格源一致？
2. 过时内容：是否引用了已废弃的功能、旧版架构、已删除的模块？
3. 范围误导：Tier 3 中是否描述了规格源中不存在的功能（幻觉功能）？是否遗漏了核心卖点？

不检查的项目（Tier 3 豁免）：

• 不要求 Tier 3 包含完整的接口定义、数据模型、状态机等技术细节
• 不要求 Tier 3 与 Tier 1/2 在措辞上完全一致
• 不要求 Tier 3 具备可追溯性矩阵
• 不对 Tier 3 的写作风格、详略程度做一致性约束

Tier 3 ↔ Tier 3：同级文档间（最低限度）

如果存在多个 Tier 3 文档，只检查：

• 产品名称、版本号是否一致
• 是否存在互相矛盾的使用说明

迭代循环

交替执行 Task A（审查） 和 Task B（修复），直到收敛。

最大轮次：$ARGUMENTS（未指定时默认6轮）。

Task A：全面审查

对所有文档进行从零开始的、独立的、全面深入的审查。每一轮都必须重新阅读和验证所有内容，不得依赖之前轮次的审查结论。

审查流程

1. 文档发现与分级：扫描所有 .md 文件，判定每个文档的层级
2. 按层级组合执行检查：
   • 对所有 Tier 0/1/2 文档对，执行规格级 7 维度检查
   • 对所有 Tier 3 文档，执行事实级 3 维度检查（对照 Tier 0/1/2）
   • 对多个 Tier 3 文档间，执行同级最低限度检查
3. 输出审查报告

审查报告格式

## 第 N 轮审查 — 汇总

- 发现问题总数：X
- 新增问题：Y
- 上轮已修复并确认关闭的问题：Z

### 文档层级清单
| 文档 | 层级 | 说明 |
|------|------|------|
| PRD.md | Tier 0 | 产品规格源 |
| DESIGN.md | Tier 1 | 技术设计源 |
| ... | ... | ... |

## 问题清单

### [ISSUE-001] 检查类型：[规格级|事实级|同级]
- **涉及文档**：PRD.md §X.X / DESIGN.md §Y.Y
- **涉及层级**：Tier 0 ↔ Tier 1
- **检查维度**：[一致性|完整性|冲突|可追溯性|术语|过时引用|范围|事实准确性|范围误导]
- **问题描述**：[具体什么不一致或有问题]
- **严重程度**：[严重|重要|轻微]
- **建议修复方案**：[应在何处做什么修改]

审查结果判定

• 如果发现 0 个新问题：宣布收敛，流程结束。
• 如果发现新问题：进入 Task B。

Task B：应用修复

根据 Task A 的审查报告，更新受影响的文档。

修复规则

1. 按严重程度依次修复所有问题：严重 → 重要 → 轻微。
2. 修复方向：
   • Tier 0/1/2 之间的冲突：以 Tier 0 为权威，向下游同步
   • Tier 3 与 Tier 0/1/2 的冲突：以规格源为准，更新 Tier 3
   • 如果 Tier 0 本身有误（产品决策层面），标记为需产品经理决策
3. 修复时必须更新所有受影响的文档，确保修复一个文档不会破坏与其他文档的一致性。
4. 完成所有编辑后，进行一次快速自查：重新阅读被修改的章节，确认修复正确且未引入新的不一致。
5. 记录变更内容：

## 第 N 轮修复 — 汇总

### [ISSUE-001] — 已修复
- 变更内容：[简述在哪些文档中做了什么修改]

### [ISSUE-002] — 部分修复
- 变更内容：[...]
- 遗留问题：[...]

### [ISSUE-003] — 跳过
- 原因：[需产品经理决策 / 范围不明确 / 其他]

Task B 完成后，返回 Task A 进行下一轮审查。

何时询问产品经理

通过 AskUserQuestion 询问用户（产品经理）的场景：

• 冲突涉及产品决策（哪个功能行为是正确的、优先级取舍、范围裁剪决策）。
• 需求存在歧义，不同解读会影响多个文档的内容。
• 发现两个同样有效但互不一致的规格描述，需要产品经理选择。
• 无法判定某个文档属于哪个层级。

不要向产品经理询问的事项：

• 技术实现细节、架构选择、代码层面的问题。
• 技术章节如何重组或措辞——直接处理即可。
• Tier 3 文档的写作风格或详略程度。

收敛与完成

当 Task A 在某一轮发现 0 个新问题时：

1. 输出最终汇总：总轮次、发现问题总数、已修复问题数。
2. 列出所有文档及其层级，确认一致性状态。
3. 结束。

非收敛停止条件

以下情况停止并报告：

• 达到最大轮次仍未收敛。
• 同一个问题在 2 轮以上持续存在（说明存在更深层的问题，需要标记出来）。
• 某个问题需要产品经理决策但尚未得到解决。