Imported from mahavira/weapon-demo (AGENTS.md). Install upstream with npx skills add mahavira/weapon-demo. Copyright stays with the author.

AGENTS.md

Project Overview

• 这是一个 Cocos Creator 3.8.8 + TypeScript 项目。

Rule Priority

• AI 修改代码时，规则优先级如下：
  1. AGENTS.md
  2. 当前代码现状
• 如果代码现状与 AGENTS.md 冲突，优先向规则收敛。

Tech Stack

• Cocos Creator 3.8.8
• TypeScript
• npm
• Node 内置测试框架 node:test

Coding Rules

必须做

• 修改前先读相关文件，不允许只凭文件名猜。
• 优先做最小修改，不顺手重构无关代码。
• 保持现有命名风格：
  • 类名 PascalCase
  • 变量和函数 camelCase
  • 节点名用语义化英文
• 公共概念命名必须统一，同一概念只保留一套主命名。
• 优先用业务语义，不优先用实现细节语义。
• 每个文件/类/函数职责尽量单一，命名要直接表达职责。
• 清理模型边界，让“配置语义”和“行为语义”一致。
• 如果一个类同时承担两种业务职责，优先拆职责，再决定是否改名。
• 如果发现旧字段名、旧接口名、旧配置名不符合当前主命名：
  • 小范围改动：本次顺手收敛
  • 大范围改动：先说明影响范围，再集中收敛
• 以下情况优先带后缀说明真实类型：
  • Node 引用字段用 xxxNode
  • 世界坐标字段用 xxxWorldPos
  • 运行时上下文字段用 xxxContext
• 如果本次目标本身就是“语义化 / 清理职责 / 提高可读性”，允许在同一业务链路内做成组重构，但范围不能扩散到无关模块。

禁止做

• 不要删除看起来无用但未确认用途的代码。
• 不要新增“看起来通用，实际上绑死某个武器/功能”的抽象。
• 不要只改名字，不处理内部混杂行为。
• 不要把调试逻辑和正式业务逻辑长期放在同一个组件里。
• 不要把武器专属逻辑放进通用投射物基类。
• 不要把配置层的概念偷偷塞进运行时行为类里。
• 不要在新代码里为同一概念引入第二套别名。
• 不要新增模糊命名：
  • data
  • info（除非它本身就是明确的数据模型，如 DamageInfo）
  • manager（除非它真的是管理器职责）
  • utils（除非是明确的纯工具模块）

Scene / Asset Rules

• 修改前必须先确认节点是“场景静态节点”还是“代码动态创建节点”。
• 不要随意改资源路径、场景文件名、脚本文件名、.meta 文件。
• 修改 .scene / .prefab / .meta 前，先确认：
  • 当前改动是在改字段，还是改节点结构
  • 是否有场景脚本挂载依赖
  • 是否有 Inspector 拖拽引用
  • 是否有资源 UUID / __id__ 关联
• 能不改场景结构，就不要改场景结构。
• 如果必须改场景结构，优先做最小追加式修改，不要随意重排已有序列化块。
• 不要为了修复引用删除 .meta 重建。
• 移动或重命名资源时，优先保留原 .meta，避免 UUID 变化导致引用断裂。

Collaboration Rules

必须做

• AI 在动手前，先说明：
  • 理解到的需求
  • 第一轮要看的文件或链路
• 如果改动较大，先给修改方案或修改范围，再落代码。

禁止做

• 不要只因为“现在能跑”就保留模糊命名。
• 不要为了少改几行，继续沿用已经确认不好的术语。
• 不要把“猜方法是否存在”当成长期能力建模方案；能显式契约就显式契约。
• 不要为了图省事手改复杂 scene 结构块。

After Editing

1. 再读一遍受影响文件，确认没有顺手改出额外行为。
2. 运行能确认的最低检查：
   • npm test
3. 如果新增或删除脚本文件，确认 .meta 一并正确处理。
4. 如果改了场景/UI/资源，检查是否会出现：
   • 重复节点
   • 丢失脚本挂载
   • 丢失 Inspector 引用
   • .meta / UUID 关联断裂
5. 提交说明里写清楚：
   • 改了哪一层
   • 是否动了场景/资源
   • 跑了什么验证
   • 哪些信息仍未确认