UnityAI/rules/50-归档规则.md

归档规则

本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。

“归档”是指任务完成后，通过归档 hook / 归档检查判断是否需要把本次任务产生的长期信息同步回项目文档。

归档 hook / 归档检查每个任务都要执行；归档不是写流水账，也不是每次都改所有文档。只更新和本次任务相关的文档。

什么时候必须更新文档

• 新增模块、拆分模块、调整模块职责。
• 修改架构、目录结构、依赖方向。
• 新增或改变生成流程。
• 完成一个 spec、计划、功能阶段或里程碑。
• 修改提交、构建、验证、发布规则。
• 用户明确要求记录进度。
• 旧模块修复改变了模块状态、关键流程、后续任务或长期约定。

简单修复如何归档

简单修复也必须执行归档 hook / 归档检查。

如果只是查询、解释、无长期影响的小修，可以不改文档，但最终回复中应说明没有长期文档需要更新。

如果简单修复改变了长期规则、模块状态或后续任务，需要补充对应文档。

归档内容

按需更新，并保持文档之间的关联关系一致：

文档	更新时机	必须同步更新的关联文档
specs/ 或 specs/openspec/<change>/	每个 Spec 任务完成后	相关模块 README/progress/tasks、架构说明、模块索引
modules/<module>/业务参考总入口.md	模块职责/入口/结构变化时	模块索引、模块登记规则、架构说明、相关功能/框架模块文档
modules/<module>/progress.md	阶段状态变化时	同一模块的 README、tasks、相关 spec
modules/<module>/tasks.md	下一步任务变化时	同一模块的 progress、plans（如涉及跨模块计划）
rules/10-架构说明.md	架构/目录/依赖方向变化时	模块索引、相关模块 README
rules/30-模块登记规则.md	新增/拆分/调整模块时	架构说明、模块索引、相关模块 README
rules/项目规则入口.md	项目规则入口内容变化时	ai/AI接入入口.md、相关规则文件、AGENTS.md/CLAUDE.md/RULES.md
RULES.md	仅当重定向目标变化时	无需单独维护内容，保持指向 rules/项目规则入口.md

关联更新原则

• 一处定义，多处引用：如果一个事实出现在多个文档中，修改时必须同步所有地方。
• 新增模块必须登记：新增或拆分模块后，必须更新 modules/模块索引.md；如分类、状态定义或登记口径变化，再更新 rules/30-模块登记规则.md。
• 已有模块变更必须留痕：修改某个模块的入口、数据流或关键类时，同步更新该模块的 progress.md，并在相关 spec/change 中记录。
• 避免孤儿文档：不要创建没有从索引/注册表链接过去的模块或 spec 文档。

归档格式

建议每次记录：

• 日期。
• 本次目标。
• 影响范围。
• 已完成。
• 未完成/TODO。
• 验证情况。
• 相关代码或文档链接。

归档前检查

• 不把临时讨论写成长久事实。
• 不把所有模块细节写进总入口。
• 不重复记录已经能从代码直接看出的内容。
• 不记录密钥、账号、机器私有路径。

---

文档关联

当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。

文档	关联原因
rules/项目规则入口.md	归档规则是项目规则入口索引的关键规则
rules/40-工作流清单.md	任务分类、提交前检查与归档触发互相引用
rules/60-新特性工作流.md	OpenSpec 归档流程与本文件归档规则互相引用
specs/openspec/OpenSpec归档.md	OpenSpec 归档说明与本文件归档规则互相引用