lms
ee1ff7f444
- 删除 01~05 旧中文教程目录 - 将 03 核心功能教程拆分为各 framework 模块的子文档 - 06 工具脚本移入 modules/frameworks/编辑器工具/UI工具/ - 非框架内容合并进 rules/20-开发规则.md 与 rules/40-工作流清单.md - 更新所有交叉链接与文档关联表 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
79 lines
3.9 KiB
Markdown
79 lines
3.9 KiB
Markdown
# 归档规则
|
||
|
||
> 本文档是 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 归档说明与本文件归档规则互相引用 | |