gplan-2/CLAUDE.md

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

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

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

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

@design/dev/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（调试浮窗——2026-10-04 迭代 14.5 起原数值调整板收进 debug_overlay）、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，报告落 design/qa/；元进度换算率标定与曲线调参的自动化评判面，2026-09-22 数值验证工具批；直入口带判定随口径退役暂停，带重锚归曲线调参批）
• 交付前验收 = smoke + 全部场景探针全绿（测试细则见 design/dev/code-conventions.md）
• 结构审计闸（熵增闸）：python tools/repo_structure_audit.py——顶层目录/根文件/图像白名单/退役路径四查，违例 FAIL；新类别 = 同批修订 CLAUDE.md Project Layout + 脚本白名单，commit 留痕（2026-09-27 立闸）

Project Layout

• design/gdd/ — 现行设计文档树（根索引 02-系统清单.md；文档增删必须同步它；gdd/ux/ 战斗画面与交互规格）
• design/registry/ — 跨系统事实登记（entities.yaml 术语与已锁数值、architecture.yaml 架构登记）
• design/art/ — 美术纯文档：定稿规范 md（圣经/清单/提示词卡）+ references/ 参考池；评估/调研 md 一律 design/research/；不放任何图片
• design/dev/ — 工程规范：code-conventions / doc-conventions / architecture(ADR) / engine-reference
• design/qa/ — 验证报告 md（balance-verifier/playtest/等价证明；raw 数据归 sim-data/）＋QA 呈现产物图（目检预览拼图等——2026-09-29 迭代 5 返工批收编图像白名单）
• design/research/ — 调研/提案/评估记录/历史验收/执行工单
• artwork/ — 在途图像素材唯一工作区（2026-09-27 用户三层裁定：文档归文档/在途图归一处/终稿归游戏）：生图候选批次（每批一目录+每资产一目录+vN 命名）、像素稿、样张渲染、实机截图全在这里；整目录不入 git——2026-10-02 用户裁：内容永久保留本地、永不提交（md 例外一并取消，.gitignore artwork/ 强制）；收口归档 archive/
• game/assets/art/ — 已验收终稿（入包被游戏加载）
• game/ — 游戏工程本体：代码三件套+smoke/ 冒烟套件+tests/ 单元/集成测试（2026-09-27 根 tests/ 并入）
• sim-data/ — 机器读数据产物：模拟试玩 CSV/JSON、verifier raw 基线、日志样例输出。数据件不入 git（2026-10-03 用户立规：.gitignore 强制）——语义=MC 缓存层：最新一份 MC 锚+读数常驻留盘供分析直读，无数值调整禁重跑（细则见「测试执行两入口铁规」MC 触发细则）；iteration_log.md 模拟批日志同目录留盘不入库。入库例外三件（2026-10-03 二裁）=README.md+analyze.py+growth_model.py（分析工具本体随 git）
• tools/ — python 工具脚本本体（验证/审计/像素化/仪表盘/日志分析）
• 根目录运行文件：active.md（会话状态唯一状态源——快照+未决面+当前迭代工作记录；状态文件非历史档案，历史归 git，退役规则见 design/dev/doc-conventions.md §10）、roadmap.md（里程碑）、stage.txt/review-mode.txt（运行开关）
• archive/ — 收口归档 zip（gitignored）

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

时机	权威文档
写代码 / 改代码前	design/dev/code-conventions.md——结构 / 契约 / 测试 / 语言 / 数值 / 流程六类硬纪律 + 反面案例对照表
写文档 / 改文档前	design/dev/doc-conventions.md——可读性第一、白话写作、概念封装、引用纪律、文档骨架、文档生命周期（吸收即死）
查系统设计 / 增删文档	design/gdd/02-系统清单.md——根索引 + 中文规范名↔英文代号对照表
架构与决策记录	design/dev/architecture/architecture.md + 同目录 adr-*.md
引擎版本与参考	design/dev/engine-reference/godot/（版本表已在上方 @ 引入）
术语、已锁数值	design/registry/entities.yaml——仅 owner 文档可修订，冲突须显式提出
会话进度记录	根目录 active.md（状态文件，2026-10-09 立宪：只记现在，每行当下为真）——快照节（≤10 条）+未决面+当前迭代状态记录；收口先改快照再记账，并删除已完结旧条目；历史归 git、待裁归 06、教训归记忆库；条目用完整白话句子写清结论，能看懂比短重要（2026-10-04 用户立规），详情归权威文档
工程路线图	根目录 roadmap.md——里程碑时间线与下一步顺序（批级视图；实时状态看快照节）

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

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

1. 开工：每个任务批次先建独立 worktree 分支再动手：git worktree add ../g-plan2-<任务名> -b <任务分支>。所有代码/文档/数值改动与验证跑测都在 worktree 内进行（注意：未跟踪文件不会出现在新 worktree，需手工搬运）
2. 收尾：迭代 loop 批次在验证全绿（冒烟 + 场景探针；冒烟挂迭代开发完成后的出口/入库闸）后，在主工作区 git merge --no-ff <任务分支> 落回 master，然后 git worktree remove + 删分支；合并前先看 active.md 尾部状态记录，避免与并行会话撞号/漏捎带；收口时按 doc-conventions §10 退役规则删除已完结旧条目（判据=已入库+结论进快照+无未决项指向）。非 loop 批次收口跑闸与否按「测试执行两入口铁规」（见硬性红线）：默认不跑，用户点名或当场问
3. 豁免面（仅这两处允许主工作区直改）：根目录 active.md（会话收口）与 .zcode/（钩子配置）——其余一律走 worktree；主工作区 git commit 会被钩子直接拦截
4. 本铁律由 PreToolUse 钩子 .zcode/hooks/worktree-guard.sh 强制兜底；钩子只约束 agent 侧，用户本人手工改动不受限

三段开发流程（2026-10-10 用户立规）

一切要做的东西按三段走：设计 → 写需求卡片 → 实现。段与段之间不自动流转，每段转进由用户发令；本节只立出入口与铁律，段内细则见规范导航各文档。背景：2026-10-10 武器锻造取证确认「迭代」曾被当作一切批次的容器（设计提案混进迭代通道），导致「迭代完成了但游戏里没有」的口径错位——本节为此立规。

第一段·设计——产出 GDD 文档或 art-bible。

• 触发：用户提起，或从 design/gdd/06-待办清单.md 取出讨论。
• 会话内进行、用户主导，不可无监管自跑；经用户点头确认心智模型一致后，才允许落文档。
• 设计完成的唯一判据 = 文档待裁点逐条清零；带未裁点的文档是讨论稿，不得转进下一段。
• 设计完成不自动进入写卡段；写需求卡片须用户另行发令。

第二段·写需求卡片——产出需求卡片（实施指导文档，写作规范见用户级技能 req-card）。

• 触发：设计定稿后由用户发令。无设计前置的例外：缺陷修复/工程债/测试基建/重构类工程需求，凭 bug 证据或 06 在册条目直接进入本段；新玩法/新系统/新内容类必须有设计定稿前置。
• 质量门：卡片必经 grilling 多轮复核，裁决全落、零待裁点才算成立。
• 登记：卡片入库后必在 design/gdd/06-待办清单.md 登记一条（卡片名/文件指针/状态：待编入/已编入/已开工/已入库）——防用户遗忘已写过的卡；卡片入库后按 06 退役规则销号。
• 编入：卡片加入后续未完成的迭代（roadmap 迭代行）；没有可用迭代时与用户确认开新一轮。

第三段·实现——产出代码与配置文件，可运行的游戏。

• 触发：需求卡片永不单独施工，统一由用户指定迭代号触发（=U0 开工令）；执行按 /iter 技能与下方批次工作流标准清单。
• 设计权威文档（GDD/art-bible 等承载设计决定的文档）在实现批内一律不更新——文档与用户想法等同对等，任何更新必须经用户同意；实现批只出迭代实现报告（见下方第 12 条文档同步闸）。
• 收口人闸：实机目检清单＋代拍板追认单登记交用户即完成批内义务；真人检测不阻塞收口、不阻塞后续迭代开工，用户自行安排时间验收（2026-10-12 用户立规，替代旧「用户验完才算真完」口径）。

批次工作流标准清单（2026-10-06 用户确认固化）

每个批次按以下链路执行——本清单主要承载第三段（实现段）与一切被批准批次的执行纪律，三段的出入口与转进规则见上节。本清单是总索引，各步细则散见上文各节与 design/dev/ 子文档；与任一细则冲突时以细则为准，发现清单本身过时须同批修订。

开工前

1. 先检索后提问——动手前先查在册记忆与权威文档，防止把已裁决事项当新问题重问，或重踩已记录的坑
2. 需求卡片全列备选案——批需求卡片里每个待拍板点列出全部备选方案与各自代价，交用户裁决，不在需求卡片内自行定夺
3. 用户发开工令才动手——需求卡片经用户批准（U0）后方开工

环境与基线 4. 独立 worktree + 拷导入缓存——按分支纪律建 worktree；新 worktree 先拷主区 .godot/ 目录与字体 .import 边车文件再跑测试，否则每套测试全量重新导入资源、近似卡死 5. 改码前定基线三查——记录改动前的冒烟全绿数目、单元测试套数、现行模拟基线读数是哪份；改完用同一口径对拍，红绿才能归因到本批改动 6. 涉数值改动先采改前读数——批次要改游戏数值的，改码前先采「改前」模拟读数（与改后同随机种子配对比较），并写明对拍口径；无数值改动禁跑模拟（触发细则见硬性红线）

实施 7. 新功能必配新测试——按需求卡片卡片写码，新增玩法/机制必须配套新增测试套件进 tests/run_all；没有对应测试的变更不许合并 8. 验收改动先行声明——逻辑变更对应的验收变化（模拟基线换代、探针用例增改、旧断言改判）在需求卡片里预先写明，不事后补

收口 9. 批末四闸全绿才合并——冒烟 + 单元测试 + 场景探针 + 改前改后读数对拍，四项全绿方可在主工作区合并 10. 合并后主区全量复跑——合并本身可能引入冲突或环境差异，落回 master 后再跑一遍全套验证 11. 会话收口落记——active.md 快照与状态记录更新（含删除已完结旧条目，退役规则见 design/dev/doc-conventions.md §10）；跨会话有效的教训写入记忆库 12. 文档同步闸 v2（2026-10-10 用户改立，替代 2026-10-09 版）——文档更新时间点分两层：机械面文档（roadmap 行换代、registry、active.md 记账、README/工具注）合并/入库前随批更新完毕方算收口（原口径不变）；设计权威文档（GDD/art-bible 等承载用户设计决定的文档）实现批内一律不更新——文档与用户想法等同，更新必须经用户同意：实现批收口产出迭代实现报告（design/qa/iter<N>-实现报告-<日期>.md，一个迭代一份，含各卡状态＋代拍板追认单＋GDD 反哺点节——实现与设计的差异/缺口逐条列明），反哺点收口时同步登记 design/gdd/06-待办清单.md，用户逐点裁决后另批落文（可随批捎带，窗口长短由用户控制）。反哺点未落文期间，相关 GDD 节按 06 登记视为待反哺状态——读该节做新设计/写新卡前先查 06，勿把旧文当现行事实。需求卡片仍必列「关联文档同步面」，同步义务按两层标注（机械面=随批更新；设计面=报告反哺） 13. 实机目检归用户，只登记不阻塞——真人检测项由 agent 登记进迭代实现报告目检总清单与 07-体验验证清单，登记完毕批内义务即完成；自动化闸全绿即可合并收口，用户自行安排时间验收，结论按 07 清单回流路径回流；禁止把「等用户目检」当作停工理由或任务完成的必要前置（2026-10-12 用户立规，替代原「用户验完才算验收通过」口径） 14. 中间产物吸收即死——结论先迁入权威文档（GDD/待办清单/路线图），中间文件即删且永不提交（细则见硬性红线）

硬性红线（勿违反）

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

• 测试执行两入口铁规（2026-10-02 用户立规）：测试类执行——冒烟测试、单元测试（tests/run_all）、模拟验证（MC/verifier/调参批量工具）、场景探针等一切跑游戏的验证调用——只有两个触发入口：①迭代 loop 开发（冒烟挂迭代开发完成后的出口/入库闸，loop 内过程性验证属开发工作本身）；②用户主动点名。除此之外（问答/调研/文档/审查/零散小改等短小会话）一律零测试，不得擅自调用任何测试；确需测试支撑结论时先请示，以静态阅读/推理作答并注明未跑测。MC/模拟验证触发细则（2026-10-02 用户确认，2026-10-03 补落文——出处：迭代 9 出口批 81000 锚误跑质询）：MC/verifier 仅在数值验证场景触发（改数值前后取证）；normal 档为主、perfect 按需；无数值改动的会话禁跑 MC——结构位移类「存档锚」须先向用户请示定性再跑；需求卡片预设步骤的前提消失时（如「带值裁定后重锚」实际未投值）停问勿照字面执行。分级周期口径（2026-09-26 用户裁定，2026-10-03 自 06-待办清单收编；重闸定义随迭代 19 卡①需求卡片 Q1 裁决扩容 2026-10-08）：轻闸（run_smoke 全量+ui_input_probe；触碰 presentation 加跑 ui_click_probe+ui_layout_probe）可随变更执行；重闸自此批末=轻闸+probe_gate --click+probe_gate --full（ui_probe/ui_tune_probe/t17_defer_probe/fx_probe 四探针）+render_gate（窗口化渲染闸：shot_probe 七屏样张 A-D 断言+fx_shot/board_shot 取证+棋盘 golden 逐像素）+run_all 单元全套+doc 三闸（gdd_lint/doc_link_audit/doc_term_audit）+熵增闸（repo_structure_audit），属周期执行——统一在批次收口或固定周检跑，不进每次变更；真人实机目检仍归用户不进自动闸（07⑮ 目检半不销号）；MC 大扫描仍按上方 MC 触发细则（无数值改动零跑）

• 闸机轮次纪律（2026-10-14 用户立规，起因=迭代 27 T0/T1 实证全套闸白跑 4-5 轮）：①【孤立验证先行】任何新代码/新工具/新测试断言，进入全套闸轮换之前，必须先走通最小可运行路径的 standalone 验证（30 秒级：新断言=单独驱动函数直跑；新工具=最小参数全路径试车含产出落盘；新探针=单 .tscn 直跑），禁以全套闸首跑充当新码首验；②【调试期最窄确认】闸机出红→修复→确认只跑出红的最小单元（单探针/单套件/单函数），禁修一处跑全套——全套闸每个里程碑步（波/T 段）出口最多一次，红灯补跑只跑红件；例外：修的若为全部探针/套件共用的共享件（如冒烟包装器、闸机脚本本身），全套即最小充分单元，注记说明即可；③【长批试车】≥2 分钟的跑批（逐位对拍冻结/MC 批/批量模拟）发起前，先用最小参数把工具完整路径（含解析/落盘/写锚全链）跑通一遍再放长批；④【开工坑册扫描】每波/T 段开工前，按要触碰的面扫一遍在册坑（worktree 缓存三件套、--script 模式无 autoload、守卫文本匹配等），5 分钟预防性动作，禁运行期撞坑补课

• MC 采集档位细则（2026-10-03 用户四档立规，承接 MC 触发细则）：MC 局数按用途四档硬闸（表见 sim-data/README.md「MC 采集档位表」）：一档·调研=总量 >40（100+ 为常用锚量级；60/档=结构回归、100=95% CI ±9.8pp、170=±7.5pp=15pp 带半宽、400 满档=±4.9pp 贴边裁决；normal 独立满档 ~8 分钟同属一档）只能由用户发起——需求卡片/计划书/agent 均无权发起，非用户发起一律不构成一档授权；二档·数值修改验证=总量 ≤40、每档 ≤20（仅 ≥~40pp 结构位移可判，同种子配对下 ~30pp）；三档·小调=总量 ≤20、每档 ≤10（只测不判）；四档·微量=总量 ≤5（sanity 门，零统计判读）。四档仅承接 MC 触发细则的数值验证场景，两入口铁规不变；超档=停机呈报，禁在二/三/四档下带值结论（窗口不足如实挂起）。改前/改后锚同 seed0 配对、改前锚留盘禁补跑；对拍断言零新跑（复验用锚内子集 ≤20）；读数缺陷（零 gameplay/RNG 触碰）禁整套重跑、走事件流重构补算；≥60 局采集先 N=5 pilot 校验字段；二/三/四档会话累计 ≤20 分钟；零数值改动=零 MC

• 中间产物吸收即死（2026-10-01 立规）：中间文档（批需求卡片/机检报告/调研审计报告/模拟读数/迭代计划书/目检清单）寿命=迭代寿命——结论先吸收进权威文档、未决项先迁 design/gdd/06-待办清单.md 或 roadmap，然后文件即删，且永不提交 git；活文档=唯一事实源，git=变更记录。细则见 design/dev/doc-conventions.md 第 11 节

• 用语红线（2026-10-04 用户立规，黑话审计后落文）：面向用户的一切输出——文档、状态记录（active.md）、报告、清单、对话——禁止自造黑话与代号式命名；判据 = 业内读者没读过项目历史也能一遍看懂，需要作者解释才能懂的词必须展开成完整白话句（三种固定形态、本仓反例全表与正确写法见 design/dev/doc-conventions.md 第 4 节）

• 呈报六问铁规（2026-10-07 用户立规）：向用户呈报一切事物——bug、需求、概念设计、提案——一律按六问结构顺序展开，确认后才动手实现：①What 现状与差异——现在是什么样（引用文件、行为等事实）+ 要做什么/改什么；②Why 期望与动机——目标态是什么样、为什么值得改，含「不做的代价」；③How 怎么改——修改路径，有备选案全部列出不私藏；④Where 影响面——改动波及哪些系统、文件、流程、既有裁决；⑤怎么算改对了——可判定的验收标准，不写模糊话；⑥不确定的地方——没把握、需要用户裁决的点，单列收尾不埋正文。Who/When 不进呈报正文——谁来执行、什么时候做由用户决定，由 roadmap 与需求卡片承接，呈报里最多一句话带过。适用范围（2026-10-08 用户补立）——六问结构只用于首次描述需求、bug 缺陷或相关方案的呈报；同一方案的后续对答（追问、讨论、细化、执行汇报）不再套用六问结构，除非用户显式要求

• 真人检测不阻塞（2026-10-12 用户立规）：一切需要真人检测/实机目检/人工验收的事项一律「只登记、不等待」——登记进 07-体验验证清单（或当批实现报告目检总清单）即完成 agent 侧义务；自动化闸全绿即可合并收口，后续迭代照常开工，验收时间由用户自行安排。禁止把等真人检测当作任务阻塞点、停工理由或收口必要条件，也禁止因往期遗留真人检测项而拦截新迭代开工

• 文件头零工作日志（2026-10-15 用户立规）：代码文件（.gd 等）文件头注释只承载现在时——文件职责、接口契约、设计权威（GDD）锚；禁止写任何形式的变更日志/工作日志：带日期条目、批次号叙事段（「XX批/T几/迭代N 做了什么」）、迁移与退役经过叙述一律不得进文件头。变更叙事唯一归宿 = commit message 与迭代实现报告；「注释描述现在、历史归版本控制」是工程基线，不依赖本仓规范另行授权——规范未提及不构成许可。存量 17 文件已随本令同批清偿（2026-10-15）

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

• RNG 单点：禁止 randomize() / 自建 RandomNumberGenerator——随机只经 RngService 统一流（单盐单计数器+用途标签+全事件日志，ADR-0007 裁丙 2026-09-27）

• 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. 修复默认附前后对比图+像素审计,不等用户索要。