# 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 构建）