ngzz-mc/CLAUDE.md

MC 项目规则（Claude Code）

本文件约束 AI 助手在本仓库中的行为。 项目：用 Go 实现的类 Minecraft 体素沙盒游戏（可扩展、可 Mod）。

第一原则：先查文档，再动手

1. 任何任务开始前，先读 文档/索引.md（全部文档的唯一入口，书签式目录）。
2. 按索引 §7「决策树」定位相关文档，通读后再实现。
3. 文档与代码冲突时以文档为准；发现文档过时，先修文档再改代码。

文档速查（按任务定位）

任务类型	必读文档
Chunk 数据结构 / 异步生成 / 锁	文档/场景/区块管理.md
地形 / 噪声 / 洞穴 / 矿物	文档/场景/世界生成.md
生物群系 / 树 / 随机刻 / 液体	文档/场景/世界生态.md
渲染 / mesh / 图集 / GL 线程 / 光影包	文档/场景/渲染.md
材质包 / 光影包 / 内容包格式 / 默认回退	文档/设计.md §1.3、文档/场景/渲染.md §9
热更新 / 热重载 / 脚本引擎 / plugin	文档/场景/热更新.md、文档/设计.md §3.4
光照 / 火把 / relight	文档/场景/光照.md
物理 / 碰撞 / 移动	文档/场景/物理与碰撞.md
方块交互 / 破坏 / 耐久 / crack	文档/场景/方块交互与动画.md
红石 / 活塞 / 方块更新	文档/场景/红石与方块更新.md
实体 / AI / 寻路 / 掉落物	文档/场景/实体系统.md
物品 / 背包 / 配方 / 容器	文档/场景/物品与背包.md
工作台 / 合成表 / 配方匹配	文档/场景/工作台与合成表.md
挖矿 / 矿物 / 工具门槛 / 附魔	文档/场景/挖矿与矿物.md
动物 / 繁殖 / 驯服	文档/场景/动物体系.md
村庄 / 村民 / 建造房子 / 交易	文档/场景/村民系统.md
僵尸 / 敌对生物 / 村庄围攻	文档/场景/僵尸与敌对生物.md
UI / 拖拽 / 多语言 / 输入	文档/场景/UI与输入.md
UI 一比一还原 / 原版界面布局	文档/场景/UI还原.md
音频 / 3D 音效	文档/场景/音频.md
多人同步 / 防作弊	文档/场景/多人同步.md、文档/网络协议.md
存档 / 持久化 / diff	文档/场景/存档与持久化.md、文档/存档格式.md
性能 / GC / pprof	文档/场景/性能与内存.md
网络 / 多人	文档/网络协议.md、文档/设计.md §10
Mod	文档/Mod开发指南.md、文档/设计.md §3
测试 / CI	文档/测试与质量.md
构建 / 发布	文档/构建与发布.md
编码风格 / Git / 评审	文档/开发规范.md
规划 / 里程碑	文档/路线图.md

硬性规则

• 协议、存档格式、Mod API、场景算法等规范类改动：先更新对应文档，再改代码，并登记到 文档/索引.md。
• 新增文档必须登记到 文档/索引.md（对应层 + 主题索引 + 阅读路径 + 决策树）。
• 遵循 Go 编码规范（文档/开发规范.md）：错误带上下文、无 goroutine 泄漏、gofmt/go vet 零告警。
• 提交信息使用 Conventional Commits（如 feat(world): ...、fix(chunk): ...）。
• 禁止臆造项目不存在的目录 / 文件结构；以 文档/设计.md §1.1 为准。
• 场景专篇引用用相对链接（光照.md），引总纲用 ../设计.md。

常用命令

• 测试：go test -race ./...
• Lint：go vet ./...、golangci-lint run
• 基准：go test -bench=. -benchmem ./...
• 性能：go tool pprof http://localhost:6060/debug/pprof/heap（仅 debug 构建）