document-sync-review

文档同步审查

先审查文档与当前项目是否一致，再决定是否更新。

更新日期：2026-04-11

工作流程

1. 明确本次要检查的文档范围。
2. 阅读相关文档和对应的当前仓库内容。
3. 提炼出“文档描述”和“仓库实际状态”的差异。
4. 当发现文档某一块内容大范围不匹配，或本次需要补充很多新增内容时，可结合文档上次更新时间，检查当前分支在该时间之后的相关 Git 提交，作为理解变化来源的辅助信息。
5. 根据任务复杂程度进行分轮自我审查，检查差异结论、影响判断和建议修改方向是否合理。
6. 只有在自我审查后认为内容已经足够准确、完整、合适时，才向用户展示差异清单和建议修改方向。
7. 在用户明确同意前，不直接改写文档。
8. 用户确认后，再基于最新仓库状态更新文档。
9. 修改文档时，同步补充或更新该文档中的更新日期。
10. 修改完成后，说明本次同步了哪些点、保留了哪些未改项。

适用对象

• 只适用于 docs/ 下的项目文档

审查重点

• 文件路径是否仍然存在，命名是否一致。
• 目录结构描述是否仍与当前仓库相符。
• 模块职责、插件边界、入口文件描述是否失真。
• 文档是否漏掉新增加的目录、文件或工作流。
• 文档是否误把生成物、IDE 配置、临时产物当成主源码结构。
• 文档中的规则是否与当前项目实际约束冲突。
• 文档是否缺少更新日期，或更新日期未随本次修改同步更新。

差异分析要求

• 差异要按“文档当前写法”与“仓库实际情况”成对描述。
• 能落到具体路径时，尽量给出具体文件或目录路径。
• 区分“事实性差异”和“表达建议”。
• 如果只是措辞风格问题，不要混入事实性错误列表。
• 如果差异来自用户刚刚手动修改的文档或代码，先重新读取最新内容再判断。

自我评审机制

• 在向用户展示差异前，先进行自我评审，不要拿未经审查的初步结论直接询问用户。
• 简单任务，例如单个文档的小范围差异或措辞修正，至少进行 1 轮自审。
• 中等任务，例如一个文档中涉及多个段落、多个路径或多处规则同步，至少进行 2 轮自审。
• 复杂任务，例如跨多个文档或存在规则冲突与适用范围分歧时，至少进行 3 轮自审；如仍不确定，应继续审查后再展示。
• 每轮自审至少检查：事实是否准确、引用路径是否正确、差异是否完整、建议是否过度、是否遗漏冲突点、是否需要先向用户确认范围。
• 只有在自审后认为结论合理、表达清晰、影响可说明时，才进入向用户展示的步骤。

修改前必须做的事

• 先告诉用户发现了哪些不一致。
• 先说明建议如何更新。
• 先询问用户是否要修改。
• 用户没有明确确认前，只做分析，不直接落笔。

询问模板

可按下面这种结构向用户汇报：

• 发现了哪些文档与当前仓库不一致。
• 每一项差异对应的实际路径是什么。
• 建议修改哪些文件。
• 是否现在按这些差异更新文档。

检索与比对规则

• 先读目标文档，再读对应的源码或目录结构，不要只看一边。
• 涉及项目结构时，优先参考 docs/project-file-structure.md，但必须再核对仓库实际状态。
• 文件检索优先用 rg --files，文本检索优先用 rg。
• 当文档某块内容差异较大，或明显遗漏了一整批新内容时，可根据文档的上次更新时间，查看当前分支在该时间之后与该主题相关的 Git 提交，用来辅助判断变化脉络。
• Git 提交只能作为辅助线索，不能替代对当前文件、当前目录结构和当前实现的直接核对。
• IDE 配置、编译产物目录应该避免误写进核心结构说明。
• 如果文档与仓库冲突，以仓库当前状态为准，但不要自动覆盖文档，先汇报用户。

不要做的事

• 不要在未确认前直接修改文档。
• 不要把猜测当成差异结论。
• 不要基于过期上下文更新文档。
• 不要把临时文件、构建垃圾或本地环境差异当成项目事实。
• 不要为了“顺手”重写整篇文档，只修改已确认的差异范围。

输出要求

• 差异说明优先简洁、准确、可操作。
• 明确指出“建议更新”与“已执行更新”的区别。