5.8 KiB
项目开发规范（强制遵守）
以下规范在所有开发活动中强制生效，不限于单次会话。创建、命名、放置任何脚本 / ScriptableObject / 预制体 / 场景 / 场景物体 / 目录前，必须先对照规范。
1. 命名与目录规范
创建/命名任何资产、脚本、预制体、场景、目录时，必须遵守 Docs/Standards/ 下的规范：
Docs/Standards/AssetFolderSpec.md— 目录结构与命名（_Game/父目录、各类资产的前缀与路径，如EVT_/PLY_/ENM_/WPN_/SKL_/CHM_/MAP_/UI_/SET_/ICN_等；场景命名Persistent.unity/MainMenu.unity/Room_{Region}_{NN}.unity/Boss_{Name}.unity）Docs/Standards/AddressablesLabelSpec.md— Addressable 地址（AddressKeys.cs常量，禁止硬编码字符串）与标签规范Docs/Standards/LayerSpec.md— 物理层 / 排序层（Sorting Layer）规范
2. 必须用 Editor 脚手架创建（不裸建）
创建场景物体 / UI / 预制体 / SO 资产时，优先用 Assets/_Game/Scripts/Editor 下的脚手架（编辑器扩展），由工具保证路径、命名、Addressables 注册、组件引用绑定符合规范。不要用裸 new GameObject / AddComponent / 手动 CreateAsset 直接搭建。
主要脚手架（菜单 / 静态方法均可经 MCP 调用）：
- 场景结构：
SceneScaffoldTools.ScaffoldPersistentScene/ScaffoldMainMenuScene/ScaffoldGameRoom - UI：
HUDScaffoldWizard.ScaffoldHUDCanvas、InventoryHubScaffoldWizard.ScaffoldInventoryHub - 场景物体：
SceneObjectPlacerTool.Place*（Player/SavePoint/Enemy/CameraArea 等，自动绑事件频道与碰撞层） - 预制体：
WeaponHitBoxWizard、SkillHitBoxWizard - SO 资产：
CreateEventChannelAssets.CreateAll、ProjectAssetSetup.CreateAll、CharacterWizardWindow、DataHubWindow - Addressables：
CoreSceneRegistrar.RegisterCoreScenes、AddressableManagerWindow、AddressKeyValidator
若某类资产没有对应脚手架，应先补脚手架（参考现有脚手架的 AssignReference/AssignAsset 绑定模式），再用它创建——使后续创建都走规范路径。
3. 创建后自检
完成创建后，运行项目验证工具确认合规：
BaseGames/Tools/Validation/Validate All ScriptableObjects（SOValidationRunner）BaseGames/Addressables/Validate Address Keys（AddressKeyValidator）BaseGames/Tools/Maintenance/Physics2D Layer Matrix/Check（LayerSpec 校验）
4. 代码命名与注释：禁止引用其他游戏
编写或修改任何 C# 代码时，命名（变量名/方法名/类名）、注释（//、///）、[Tooltip]、[Header] 字段标签 中均不得出现其他游戏的专有名称、专属机制/道具名称，或"对齐/仿/参考/类比 XX 游戏"等措辞。完整规则、对照表与允许保留的通用术语见 .github/skills/no-game-references/SKILL.md。
- ❌ 禁止：
// 对齐空洞骑士手感、[Tooltip("HK ~0.12s")]、ApplyHKComposerDefaults(...) - ✅ 替换为只描述功能特点：
// 下落比上升更快，手感紧实、[Tooltip("推荐 0.12s")]、ApplyComposerDefaults(...) - 允许保留的通用业界术语：
Pogo、Charm、platformer/横版平台游戏、Metroidvania、手感/风格。
5. 及时 Git 提交
完成一个可独立工作的改动后（功能、修复、重构、文档等），应及时 git 提交，不要积压大量未提交改动：
- 每完成一个逻辑单元就提交一次，保持提交粒度小、可回溯。
- 提交信息遵循现有风格（中文 + 类型前缀，如
feat(ui):/refactor:/docs:/fix:）。 - 提交示例：
git add ... && git commit -m "..."。
6. 根因修复，禁止下游兜底掩盖问题
修复任何问题时，必须定位并修复根因，使功能在正常路径上如预期正确运行；禁止用兜底 / 回退 / 容错分支在下游把症状盖住、让问题表面上"不再出现"。
- ❌ 禁止：在消费端加 fallback 自动补一个默认值/默认对象来掩盖上游漏配（例：探测器发现交互物没有提示子节点，就运行时自动实例化一个默认提示——这掩盖了"创建链路没产出正确对象"的真问题）。
- ❌ 禁止：用
try/catch吞异常、?? 默认值、if(null) return等手段让错误静默通过，而不修产生该错误的源头。 - ✅ 正确：让创建链路（脚手架）本身产出完整正确的对象；已存在的错误数据，直接修正为正确状态（如把误置的物理层改回规范层、补齐漏绑的引用），而不是在运行时绕过。
- ✅ 正确：源头无法即时修复时，应显式报错 / 校验失败（写入自检工具、抛出明确异常），把问题暴露出来，而非隐藏。
- 判据：问"如果去掉这段代码，问题会不会暴露出来？"——若答案是"会，且暴露的是真问题"，那这段就是在掩盖问题，应删除并改修根因。
- 兜底/默认值仅允许用于合法的业务缺省（如可选配置留空有明确语义），不得用于遮盖本应正确配置却没配好的情况。
7. 文档分区：开发文档与长期文档
开发过程中产生的文档，按用途分放两处：
Docs_Dev/— 开发过程中的临时性 / 阶段性文档：实现计划、开发笔记、验证清单、评估报告、调试记录、一次性任务的 spec 等（会随开发推进而过时的文档）。Docs/— 项目长期文档：指导手册（Docs/Guides/）、架构设计、命名/目录/规范（Docs/Standards/）等需要长期维护、对项目持续有效的文档。
判据：问"这份文档在对应功能开发完成后是否还需要长期查阅？"——需要长期查阅（手册、架构、规范）放 Docs/；只服务于当前开发阶段的放 Docs_Dev/。