---
description: 项目开发规范——AI 生成代码强制标准（OOP、注释、无兜底、性能、资源、动画）
alwaysApply: true
---

# 开发规范（生成代码必遵）

完整版：`docs/开发规范.md`。生成或修改 TS 代码前须全局思考，查阅 `docs/项目说明.md` 与相关 `需求-*` / `方案-*` 文档。

## 素养与范围

- 以资深工程师标准：架构、可复用、可扩展、可靠、安全；**临时修 Bug 也须全局评估**。
- 面向对象：功能在 **类/接口** 中；**禁止新增业务全局函数**。
- **禁止屎山**；代码简洁。不随意新增 TS 文件/变量；数据结构合并到类型文件。
- **禁止任何形式的静默兜底**；可 `warn` 暴露问题，不得猜默认值掩盖错误。
- **需求不明确必须问用户**；未授权不得自行发挥（通用惯例如特效细节除外）；不得擅自改策划。

## 命名与注释

- 简化驼峰，名称简短易懂。
- **接口、类、枚举、每个枚举项、字段、函数** 必须有简洁 JSDoc。
- **框架代码**（`assets/mx/`）不写逐步逻辑注释。

## 函数与语法

- 函数 **参数不换行**（同一行写完形参列表）。
- **禁止在函数内定义函数**；回调/闭包改为 **类方法**，生命周期内注册/注销。
- 新代码 **禁止 Set/Map** 等小游戏不稳定结构；遵循 Cocos 推荐 ES 版本。
- **禁止** `[...map.keys/values/entries()]`、`[...map]`、`Array.from(map.keys())`：H5 构建会编成 `concat(iterator)`。用 `mapKeysToArray` / `mapValuesToArray` / `membershipToArray` / `forEach`。
- 引擎 API **严格按 Cocos Creator 官方文档**（本项目 3.8.8）。

## 性能、动画、资源、内存

- 考虑时间/空间复杂度；`update`/战斗 tick 热路径优化；**能分帧则分帧，能延迟则延迟**。
- **内存**：能复用则复用；对象池出池须 **完整重置状态**，归还无泄漏，不得因池化引入脏数据 Bug。
- 可释放的字段、引用、监听、定时器在生命周期结束时 **安全释放**；不得因过早释放引入崩溃。
- 动画（tween/插值/Spine/Animation）：异步生命周期完整——停止、清除回调、`onDestroy` 取消；禁止销毁后仍执行回调。
- 资源：加载/持有/释放与 `BundleLifecycle`、`AssetService` 一致；校验 `isValid`；**禁止释放后仍渲染**；考虑断网与玩家异常操作。

## 记忆

- 不依赖单会话上下文；结合 `docs/` 与全项目架构做整体分析；架构决策写入 `docs/`。