UnityAI/rules/50-文档同步规则.md

文档同步规则

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

必须同步的变化

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

通常不写入长期文档

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

同步位置

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

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

单一事实来源

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

检查方式

任务完成后运行：

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

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

文档关联

文档	关联原因
项目规则入口	引用文档同步原则
工作流清单	定义同步发生的任务阶段
模块登记规则	模块文档结构和状态口径
共享检查	提供只读检查脚本