game-group/gplan-2
2
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6c2dbc37c12eae600bcd4bced0b9542cb0e081e9
gplan-2/CLAUDE.md
T
DKChan 6c2dbc37c1 docs: ADR 体系废除 + architecture.md 确立为架构唯一事实源（2026-10-15 用户令：决策记录归 git commit log，不另存决策文档） 
- 删除 design/dev/architecture/adr-0001~0007 共 7 份文件（内容留 git 历史可查）
- architecture.md：删「ADR 审计」「ADR 立项清单」两节；清除全文 ADR-000X 注记、QQ 表/S 表 ADR 引用；未决表关闭已落定项（QQ-01/02/03），立项清单在途事项转登记 QQ-11~14；补 A1 生成姿态事实、autoload 四件清单、board_generator 性能姿态；文档状态立「事实源地位」条
- CLAUDE.md：恢复 RNG 单点硬性红线（去 ADR-0007 引用）；新增「架构事实唯一源」红线；规范导航架构行标注唯一事实源
- doc-conventions：§5 增「架构事实唯一源」行；§11 活文档清单补架构文档
- registry：architecture.yaml 删 18 处 adr 字段、autoload_set 补 SaveManager/MetaProgression、board_rending 更新为 Node2D 已落地事实；entities.yaml 12 处引用清除
- game/ 代码注释约 60 处清 ADR-000X 引用（事实与日期保留）；豁免标记 ADR-0007-exempt → rng-seed-exempt（main.gd/static_scan.sh/architecture.md/06/iter27 五处同步）
- GDD/qa 实现报告/research 卡片/roadmap/tests README 引用全清；死链校验 1206 链接 0 死链、gdd_lint 0 不通过
- 代码中 adr/adr5 等为 adventure_runner 既有局部变量名（非 ADR 引用），未动
2026-10-15 23:52:30 +08:00

7.3 KiB
Raw Blame History

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）+ Export Templates · 资源管线: Godot Import System + 自定义 resource pipeline
  • Godot 本机固定路径：D:\code\godot\Godot_v4.7.2-stable_win64_console.exe（headless/命令行一律 console 版；编辑器版同目录）

Engine Version Reference

@design/dev/engine-reference/godot/VERSION.md

运行与验证（工作目录 = 含 project.godot 的切片目录）

  • 交付前验收 = 跑 tools/run_all_gates.sh（不带 --quick），全绿才合回 master——它是全部验证闸的唯一入口与唯一清单，闸件增减只改它，文档禁另列清单。跑完写回执 game/tests/.gates/receipt.json，合回时由 worktree-guard 校验（缺回执／quick 模式／回执 commit ≠ HEAD／含红项四况一律拦截）
  • 单件直跑（调试期最窄确认用，不构成验收）：冒烟 python tools/run_smoke.py · 场景探针 …console.exe --headless --path . res://smoke/ui_probe.tscn · 单元 … --script res://tests/run_all.gd
  • 调参批量：--script res://smoke/adventure_monte_carlo.gd（全冒险期望）· res://smoke/reward_expectation.gd（奖励期望）；通关率/难度类测量一律走全冒险
  • 数值验证：python tools/balance_verifier.py（采集端 res://smoke/verifier_batch.gd，报告落 design/qa/）
  • 熵增闸（新类别 = 同批修订 Project Layout + 白名单）：python tools/repo_structure_audit.py

Project Layout

  • design/gdd/ — 现行设计文档树（根索引 02-系统清单.md，文档增删必须同步；gdd/ux/ 战斗画面与交互规格）
  • design/registry/ — 跨系统事实登记（entities.yaml 术语与已锁数值、architecture.yaml 架构登记）
  • design/art/ — 美术纯文档（圣经/清单/提示词卡 + references/）；评估调研归 design/research/；不放图片
  • design/dev/ — 工程规范（五份规约 + architecture + engine-reference）
  • design/qa/ — 验证报告 + QA 呈现产物图；design/research/ — 调研/提案/评估/历史验收
  • artwork/ — 在途图像素材唯一工作区（文档归文档/在途图归一处/终稿归游戏）；整目录不入 git（.gitignore 强制），收口归档 archive/
  • game/assets/art/ — 已验收终稿（入包被游戏加载）；game/ — 游戏工程本体（代码 + smoke/ 冒烟 + tests/ 单元集成）
  • sim-data/ — 机器读数据产物；数据件不入 git（入库例外 = README+analyze.py+growth_model.py）；MC 锚与读数常驻留盘，无数值调整禁重跑
  • tools/ — python 工具脚本；archive/ — 收口归档 zip（gitignored）
  • 根目录：active.md（会话状态唯一状态源，退役规则见 doc-conventions 第 10 节）、roadmap.md（里程碑）、stage.txt/review-mode.txt（运行开关）

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

时机 权威文档
批次开工 / 流程纪律 design/dev/process-conventions.md——worktree 铁律、三段开发流程、批次清单、测试两入口与 MC/闸机细则、像素纪律
写代码 / 改代码前 design/dev/code-conventions.md——结构/契约/语言/数值/流程五类硬纪律（反例库 = 同目录 code-conventions-cases.md）
写测试 / 改测试前 design/dev/test-conventions.md——探针标配 / 回归断言 / 全量验证 / 验收清单落码 / 变异验证
写文档 / 改文档前 design/dev/doc-conventions.md——白话写作 / 载体分工 / 用语 / 结构骨架 / 会话记录与生命周期
概念切分与互链 design/dev/concept-conventions.md——概念封装 / 跨文档引用 / 归档与事实源
系统设计 / 增删文档 design/gdd/02-系统清单.md——根索引 + 中文规范名↔英文代号对照
架构（唯一事实源） design/dev/architecture/architecture.md——历史决策沿革查 git commit log，不另设决策文档
术语、已锁数值 design/registry/entities.yaml——仅 owner 文档可修订，冲突须显式提出
会话进度 / 路线图 根 active.md（状态文件：只记现在，每行当下为真；快照+未决面+滚动条目）· 根 roadmap.md

硬性红线（勿违反；操作细则在 process-conventions.md 与各规约）

  • 主工作区禁止直接改动与提交——一切改动走独立 worktree（豁免：active.md 会话收口、.zcode 钩子配置）
  • 测试执行两入口铁规——只有迭代 loop 开发与用户点名两个触发入口；其余会话零测试，需测试支撑先请示并注明未跑测
  • 交付前验收 = 跑 tools/run_all_gates.sh 全绿（唯一入口与唯一闸清单，禁在文档另列清单）；合回 master 由 worktree-guard 校验回执强制（process-conventions §3）
  • MC/模拟：无数值改动零跑；档位硬闸见 sim-data/README.md「MC 采集档位表」，一档只能由用户发起
  • 闸机轮次纪律：新码先孤立验证 → 出红只跑红件最小单元 → 长批先最小参数试车 → 开工扫坑册（process-conventions §6）
  • 变异验证——新增/改写验收函数必须变异变红才算验收成立；无变异红记录只写「已实现，拦截能力未证」（test-conventions §6）
  • 中间产物吸收即死——结论先吸收进权威文档、未决先迁 06，文件即删且永不提交（doc-conventions 第 11 节）
  • 用语红线——一切对用户输出禁自造黑话，需要作者解释的词必须展开成完整白话句（doc-conventions 第 4 节三形态表）
  • 呈报六问——What 现状差异 / Why 动机与不做代价 / How 方案与全部备选 / Where 影响面 / 验收判据 / 不确定点单列收尾；Who/When 不进正文；仅首次描述需求/bug/方案适用
  • 真人检测只登记不阻塞——登记进 07 清单/实现报告即完成义务，禁以等目检为停工理由或收口前置
  • 文件头 = ## 文档注释 ≤8 行白名单制（code-conventions §1.4.1；写法权威 = Google Python Style Guide §3.8 + PEP 257；机器闸 tools/audit_file_headers.py）
  • 数值单一事实源——玩法数值只存 data/tables/（.tres）经 ConfigDB 单点读取；禁数值字面量与自建 load() 表路径
  • RNG 单点——禁 randomize()/自建 RandomNumberGenerator，随机只经 RngService 统一流
  • 架构事实唯一源——架构事实只认 design/dev/architecture/architecture.md；禁立第二架构文档或决策文档体系，历史决策记录只进 git commit log
  • Core 层零 UI 依赖——完整战斗必须可 --headless --script 跑通；fail-fast——数据校验错误一律致命中止，无软回退
  • spec-AC 一致性——规约与验收标准不得在同一输入上给出不同答案；评审隔离——/design-review 必须独立会话跑（与 /design-system 隔离）
  • 像素结构件——先抄后造、验收写成像素级判据、±1px 坐标推导（process-conventions 第 7 节）
Reference in new issue View Git Blame Copy Permalink