gplan-2/CLAUDE.md

Dungeon Sweeper（扫雷 × 自动战斗 闯关 Roguelike）

扫雷推理层 + 自动战斗结算的两段式回合 Roguelike。个人开发，MVP 优先管线。 设计入口：design/gdd/02-系统清单.md（根索引）· 概念：design/gdd/00-游戏概念.md · 旧版 GDD 归档（只读参考）：design/archive/gdd-2026-09-14/

本文件只保留全局元信息与硬性红线；一切领域细则在子文档，动手前先查「规范导航」。

Technology Stack

• Engine: Godot 4.7.2 · Language: GDScript · Build: SCons（engine）+ Godot Export Templates · 资源管线: Godot Import System + 自定义 resource pipeline
• Godot 可执行文件（本机固定路径）：D:\code\godot\Godot_v4.7.2-stable_win64_console.exe——headless / 命令行一律用 console 版；编辑器版为同目录 Godot_v4.7.2-stable_win64.exe

Engine Version Reference

@docs/engine-reference/godot/VERSION.md

运行与验证（垂直切片）

工作目录 = 切片目录本身（含 project.godot 的那一层）：

• 冒烟（全量 headless 断言）：python tools/run_smoke.py（包装器三闸：退出码＋摘要失败数＋SCRIPT ERROR 扫描——脚本错误不计冒烟失败数且静默中断所在函数剩余断言，2026-09-19 台账 84 立闸）。底层命令 = …console.exe --headless --path . --script res://smoke/smoke_all.gd
• 场景级探针（呈现层回归）：…console.exe --headless --path . res://smoke/ui_probe.tscn；另有 ui_tune_probe.tscn（数值调整板）、ui_click_probe.tscn（合成鼠标事件行为探针）
• 调参期批量工具：--script res://smoke/adventure_monte_carlo.gd（全冒险期望扫描）· --script res://smoke/reward_expectation.gd（奖励获取期望）——单关直入口口径已退役（2026-09-23 用户拍板），通关率/难度类测量一律走全冒险（原 level_monte_carlo/level_debug 已删）
• 数值验证工具：python tools/balance_verifier.py（零强化冒险逐关条件通关率＋止步节点归因＋营地循环爬升战役——采集端 --script res://smoke/verifier_batch.gd，报告落 production/qa/；元进度换算率标定与曲线调参的自动化评判面，2026-09-22 数值验证工具批；直入口带判定随口径退役暂停，带重锚归曲线调参批）
• 交付前验收 = smoke + 全部场景探针全绿（测试细则见 docs/code-conventions.md）

Project Layout

• design/gdd/ — 现行设计文档树（根索引 02-系统清单.md；文档增删必须同步它）
• design/archive/gdd-2026-09-14/ — 旧版 GDD 归档（只读参考，不作事实引用）
• design/registry/ — 跨系统事实登记（术语规范名、已锁数值）
• design/art/ — 美术纯文档：定稿规范 md（圣经/清单/提示词卡）+ references/ 参考池；评估/调研 md 一律 design/research/；不放任何图片
• artwork/ — 在途图像素材唯一工作区（2026-09-27 用户三层裁定：文档归文档/在途图归一处/终稿归游戏）：生图候选批次（每批一目录+每资产一目录+vN 命名）、像素稿、样张渲染、实机截图全在这里；图不入 git（md 指引例外）；收口归档 archive/
• production/ — 过程产物区：stage、session-state、roadmap、gate-checks、qa、执行工单；不放图片
• game/assets/art/ — 已验收终稿（入包被游戏加载）
• game/ — 游戏工程本体（垂直切片转正 2026-09-24 结构批；概念 demo 已删，验证报告留档 docs/prototype-report-minesweeper-battle-concept.md）
• docs/ — 规范与参考文档（权威清单见下方导航）

规范导航（动手前先查表）

时机	权威文档
写代码 / 改代码前	docs/code-conventions.md——结构 / 契约 / 测试 / 语言 / 数值 / 流程六类硬纪律 + 反面案例对照表
写文档 / 改文档前	docs/doc-conventions.md——可读性第一、白话写作、概念封装、引用纪律、文档骨架
查系统设计 / 增删文档	design/gdd/02-系统清单.md——根索引 + 中文规范名↔英文代号对照表
架构与决策记录	docs/architecture/architecture.md + 同目录 adr-*.md
引擎版本与参考	docs/engine-reference/godot/（版本表已在上方 @ 引入）
术语、已锁数值	design/registry/entities.yaml——仅 owner 文档可修订，冲突须显式提出
会话进度记录	production/session-state/active.md——顶部「当前状态快照」节 + 批次台账；收口先改快照再记账，每条 ≤3 行，详情外链
工程路线图	production/roadmap.md——里程碑时间线与下一步顺序（批级视图；实时状态看快照节）

分支纪律（worktree 铁律，2026-09-19 用户立规）

主工作区（本目录，master 检出）只作合并落点与共享状态载体，一切开发/设计改动不得直接发生在主工作区：

1. 开工：每个任务批次先建独立 worktree 分支再动手：git worktree add ../g-plan2-<任务名> -b <任务分支>。所有代码/文档/数值改动与验证跑测都在 worktree 内进行（注意：未跟踪文件不会出现在新 worktree，需手工搬运）
2. 收尾：验证全绿（冒烟 + 场景探针）后，在主工作区 git merge --no-ff <任务分支> 落回 master，然后 git worktree remove + 删分支；合并前先看 active.md 尾部台账，避免与并行会话撞号/漏捎带
3. 豁免面（仅这两处允许主工作区直改）：production/session-state/（会话收口）与 .zcode/（钩子配置）——其余一律走 worktree；主工作区 git commit 会被钩子直接拦截
4. 本铁律由 PreToolUse 钩子 .zcode/hooks/worktree-guard.sh 强制兜底；钩子只约束 agent 侧，用户本人手工改动不受限

硬性红线（勿违反）

• worktree 铁律：主工作区禁止直接改动与提交（细则见上节；并行会话各占 worktree 互不踩踏）

• 数值单一事实源：玩法数值只存 data/tables/（.tres），经 ConfigDB autoload 类型化单点读取；禁止数值字面量与自建 load() 表路径

• RNG 单点：禁止 randomize() / 自建 RandomNumberGenerator——随机只经 RngService 封闭命名流

• Core 层零 UI 依赖：完整战斗必须可 --headless --script 跑通

• fail-fast：数据校验错误一律致命中止，无软回退

• spec-AC 一致性：规约与验收标准不得在同一输入上给出不同答案（所有 GDD 同尺度）

• 评审隔离：/design-review 必须在独立会话跑（与 /design-system 隔离）

像素结构件工作纪律(2026-09-26,高墙批转角三返工复盘用户令落档)

1. 先抄后造:画任何像素结构件前,先从参考素材裁同类结构放大逐像素描述,再实现同款;禁止凭印象/第一性原理发明像素结构(圣经 §8.5 参考核验的执行口径)。
2. 验收口径写成像素级视觉判据:开工前把合格标准写成"X 与 Y 同列收尾/无悬空/无突出"式句子;自检放大最差交界处逐行核像素,不只看整板观感。
3. ±1px 一律坐标推导:单像素级结构先写坐标推导(哪条线在哪列、谁与谁齐平)留档再写码;禁蒙数试错。
4. 修复默认附前后对比图+像素审计,不等用户索要。