# 文档同步规则

文档同步的目标是保存长期有效的框架知识，不是记录每次任务过程。

## 必须同步的变化

- 公共 API、参数、返回值或调用顺序变化。
- 框架分层、源码位置、生成目录或依赖方向变化。
- Prefab、资源、配置或构建产物的稳定结构变化。
- Editor 工具、CopyToX、AssetBundle、分包、热更新等生成流程变化。
- 平台路径、下载策略、失败回退或兼容性规则变化。
- 模块新增、删除、重命名、状态或入口变化。

## 通常不写入长期文档

- 不改变公开行为的局部 Bug 修复。
- 临时断点、调试日志、截图和排错过程。
- 一次性测试数据或仅服务当前任务的文件列表。
- 可以直接从代码读出的私有实现细节。
- 尚未确认的讨论结论和未来计划。

## 同步位置

| 变化 | 写入位置 |
|---|---|
| 跨模块规则和工作方式 | `rules/` 中对应唯一规则 |
| 模块职责、架构和数据流 | 模块 `README.md` |
| 业务调用和公共 API | 模块 `使用指南.md` 或开发指南 |
| 模块入口或状态 | `modules/模块索引.md` |
| 外部项目案例 | `business-reference/` 对应项目 |

重大变更的讨论和任务过程文档规则以 [工作流清单](40-工作流清单.md) 为准；实现后的稳定结论直接进入上述长期文档。

## 单一事实来源

- 一个事实只在一个文档完整定义。
- 其他文档只写任务所需的最短摘要并链接到事实来源。
- 修改事实来源后，检查所有引用是否仍然成立；不要复制整段内容同步维护。
- 模块索引只保存入口、职责摘要和状态，不承载完整使用说明。

## 检查方式

任务完成后运行：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File hooks/workflow-check.ps1 `
  -UnityProjectRoot <Unity工程路径>
```

脚本只输出工作树、源码/生成代码关系、建议验证和可能需要同步的文档，不自动修改文件。最终是否更新文档按本规则判断。

## 文档关联

| 文档 | 关联原因 |
|---|---|
| [项目规则入口](项目规则入口.md) | 引用文档同步原则 |
| [工作流清单](40-工作流清单.md) | 定义同步发生的任务阶段 |
| [模块登记规则](30-模块登记规则.md) | 模块文档结构和状态口径 |
| [共享检查](../hooks/Hook共享层.md) | 提供只读检查脚本 |