# 归档规则

> 本文档是 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](项目规则入口.md) | 归档规则是项目规则入口索引的关键规则 |
| [rules/40-工作流清单.md](40-工作流清单.md) | 任务分类、提交前检查与归档触发互相引用 |
| [rules/60-新特性工作流.md](60-新特性工作流.md) | OpenSpec 归档流程与本文件归档规则互相引用 |
| [specs/openspec/OpenSpec归档.md](../specs/openspec/OpenSpec归档.md) | OpenSpec 归档说明与本文件归档规则互相引用 |