UnityAI/rules/30-模块登记规则.md

# 模块登记规则

模块入口、分类和状态统一维护在 [模块索引](../modules/模块索引.md)，其他文档不复制模块清单。

## 分类

- **核心框架**：运行时系统，例如 UI、资源、事件、实体、对象池和场景。
- **编辑器工具**：Unity Editor 内的生成器、窗口、菜单和 MCP Bridge。
- **业务参考**：外部项目案例，仅用于说明框架如何被使用。

## 状态

- **未识别**：尚无稳定实现线索。
- **已识别**：已发现路径或入口，未完成系统梳理。
- **初步梳理**：职责、路径或基本数据流已记录，仍有待确认项。
- **待验证**：文档已有结论，尚未通过 Unity、运行时、生成器或日志闭环。
- **已完成**：当前文档与实现已经验证，后续随代码演进维护。
- **未发现实现**：按目录和关键词检查后暂未发现实现。

## 文档结构

- 轻量模块使用一个 `README.md`。
- API 和业务调用较多时增加 `使用指南.md` 或 `开发指南.md`。
- 特殊限制写入 `注意事项.md`，不创建计划、进度或任务文件。
- 模块发生大改时，讨论保留在对话中；实现后的稳定结论直接更新现有文档。
- 模块新增、删除、重命名或状态变化时更新模块索引。

### 量化标准

| 维度 | 使用一个 README | 增加使用/开发指南 | 增加注意事项 |
|---|---|---|---|
| 核心类/接口数 | ≤3 个 | ≥5 个公共方法或 ≥3 个配置项 | — |
| 状态机/生命周期复杂度 | 无复杂状态机 | 存在多阶段调用顺序 | — |
| 公共 API 数量 | ≤5 个 | >5 个 | — |
| 必须遵守的禁忌/性能约束 | ≤1 条 | — | ≥2 条 |
| 典型使用示例必要性 | 一句话可描述 | 需要完整调用链示例 | 存在特殊边界场景 |

`README.md` 只保留模块定位、核心组成、使用规则和导航链接；具体 API、调用链、架构图、最佳实践写入 `使用指南.md` 或 `开发指南.md`。

## 登记规则

- 框架模块放入 `modules/frameworks/`。
- 编辑器工具放入 `modules/frameworks/编辑器工具/`。
- 外部业务案例放入 `business-reference/<project>/`，不作为框架规范。
- 文档路径反映模块职责，不按一次性任务名称建立目录。
- 一个模块的职责和入口由 README 完整定义，索引只保存摘要和链接。

## 文档关联

| 文档 | 关联原因 |
|---|---|
| [模块索引](../modules/模块索引.md) | 模块清单和状态的唯一事实来源 |
| [架构说明](10-架构说明.md) | 模块分类与代码分层 |
| [文档同步规则](50-文档同步规则.md) | 模块变化的同步条件 |
| [模块文档模板](../modules/模块文档模板.md) | 新模块文档结构 |