diff --git a/CLAUDE.md b/CLAUDE.md index fe473215..4500ddb3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,54 +1,54 @@ # Dungeon Sweeper（扫雷 × 自动战斗 闯关 Roguelike） 扫雷推理层 + 自动战斗结算的两段式回合 Roguelike。个人开发，MVP 优先管线。 -设计入口：`design/gdd/02-系统清单.md`（循环式新骨架根索引）· 概念：`design/gdd/00-游戏概念.md` · 旧版 GDD 归档（只读参考）：`design/archive/gdd-2026-09-14/` +设计入口：`design/gdd/02-系统清单.md`（根索引）· 概念：`design/gdd/00-游戏概念.md` · 旧版 GDD 归档（只读参考）：`design/archive/gdd-2026-09-14/` + +> 本文件只保留全局元信息与硬性红线；一切领域细则在子文档，动手前先查「规范导航」。 ## Technology Stack -- **Engine**: Godot 4.7.2 -- **Godot 可执行文件（本机固定路径，2026-09-15 登记）**：`D:\code\godot\Godot_v4.7.2-stable_win64_console.exe`（headless / 命令行一律用 console 版；编辑器版为同目录 `Godot_v4.7.2-stable_win64.exe`） -- **Language**: GDScript -- **Build System**: SCons (engine), Godot Export Templates -- **Asset Pipeline**: Godot Import System + custom resource pipeline - -## 运行与验证（垂直切片） - -工作目录 = 切片目录本身（含 `project.godot` 的那一层）： - -- 冒烟（全量 headless 断言）：`D:\code\godot\Godot_v4.7.2-stable_win64_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/level_monte_carlo.gd`（关卡期望扫描）· `--script res://smoke/reward_expectation.gd`（奖励获取期望） -- 交付前纪律：smoke + 全部场景探针全绿（见下方代码规范·测试条） +- **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 断言）：`…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/level_monte_carlo.gd`（关卡期望扫描）· `--script res://smoke/reward_expectation.gd`（奖励获取期望） +- 交付前验收 = smoke + 全部场景探针全绿（测试细则见 `docs/code-conventions.md`） + ## Project Layout -- `design/gdd/` — 现行设计文档（2026-09-14 重建的循环式新骨架）：6 份顶层文档（`00-游戏概念` / `01-核心循环` / `02-系统清单`〔根索引〕 / `03-内容规模` / `04-美术音频方向` / `05-不做清单`）+ `systems/` 按四个循环组织子系统文档（排雷循环 / 战斗循环 / 冒险循环 / 表现与支撑），子系统一律中文见名知意命名、不带编号前缀；文档增删必须同步 `02-系统清单.md` -- `design/archive/gdd-2026-09-14/` — 旧版 GDD 体系归档（只读参考，不再维护，不作事实引用） -- `design/registry/entities.yaml` — 跨系统事实登记表（已锁数值；仅 owner 文档可修订，冲突须显式提出） -- `production/` — stage、session-state、gate-checks -- `prototypes/` — `dungeon-sweeper-vertical-slice/` 垂直切片（概念 demo 已删除，验证报告留档 `docs/prototype-report-minesweeper-battle-concept.md`） -- `docs/` — 代码规范（`code-conventions.md`）· **文档写作规范（`doc-conventions.md`，写文档前必读）** · 架构与 ADR（`architecture/`）· 引擎参考（`engine-reference/`） +- `design/gdd/` — 现行设计文档树（根索引 `02-系统清单.md`；文档增删必须同步它） +- `design/archive/gdd-2026-09-14/` — 旧版 GDD 归档（只读参考，不作事实引用） +- `design/registry/` — 跨系统事实登记（术语规范名、已锁数值） +- `production/` — stage、session-state、gate-checks、qa +- `prototypes/dungeon-sweeper-vertical-slice/` — 垂直切片（概念 demo 已删，验证报告留档 `docs/prototype-report-minesweeper-battle-concept.md`） +- `docs/` — 规范与参考文档（权威清单见下方导航） -## Conventions（评审确立，勿违反） +## 规范导航（动手前先查表） -- **数值单一事实源**：全部玩法数值存 `data/tables/`（.tres），经 `ConfigDB` autoload 类型化单点读取；玩法代码禁止数值字面量与自建 `load()` 表路径（D2 Rule 1/2） -- **RNG 单点**：禁止 `randomize()`/自建 RandomNumberGenerator——随机只经 `RngService` 封闭命名流（D2 Rule 5） -- **Core 层零 UI 依赖**：完整战斗必须可 `godot --headless --script` 运行（D2 Rule 7） -- **fail-fast**：数据校验错误一律致命中止，无软回退（D2 Rule 6） -- **spec-AC 一致性**：规约与验收标准不得在同一输入上给出不同答案——D2 两轮评审确立的阻塞标准，所有 GDD 同尺度 -- GDD 评审纪律：`/design-review` 必须在独立会话跑（与 `/design-system` 隔离） -- **文档写作规范（2026-09-14 成文，写任何文档前必读）**：在编写、修改任何设计文档之前，必须先通读 `docs/doc-conventions.md`（全文权威——整合原用语纪律〔2026-09-09〕、文档形态纪律〔2026-09-13〕、两件套与树形文档体系纪律〔2026-09-14〕、新骨架过渡口径〔2026-09-14〕，并新增可读性第一纪律）。要点：**可读性第一**——读者测试三问（管的是谁/什么？什么情况下？会发生什么？）答不出就重写该节；白话完整句、散文讲道理、表格放数据；禁自造黑话（唯一例外 = 玩家可见专属名词）；树形文档体系，文档增删必须同步根索引 `design/gdd/02-系统清单.md`；节点一页纸以内；每个子系统一份设计文档、不建 analysis 推演件；正文只写现行规则，修订只进文末「版本历史」表；概念封装纪律（概念即对象 / 属性归属唯一 / 包含关系显式 / 状态用枚举 / 附加物独立成对象）见该文第 7 节，跨文档引用纪律（单点定义 / 规范名唯一 / 引用不转述 / 反向边登记 / 删除概念 SOP）见该文第 8 节；已锁数值事实源 = `design/registry/entities.yaml` 与 `data/tables/`。旧体系 lean 格式与 `gdd_lint` 门禁仅用于解读归档（`design/archive/gdd-2026-09-14/`），不约束现行文档。 +| 时机 | 权威文档 | +|---|---| +| **写代码 / 改代码前** | `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 行，详情外链 | -## 代码规范（写代码前必读，2026-09-11 用户拍板成文） +## 硬性红线（勿违反） -**在编写、修改任何代码之前，必须先通读 `docs/code-conventions.md`**——该文档由用户指出的真实陋习与缺陷逐条成文，含结构/契约/测试/语言/数值/流程六类硬性纪律与本项目反面案例对照表。摘要（全文以文档为准）： - -- **结构**：禁止上帝对象；功能以类封装；views →(信号)→ 组合根 →(写调用)→ core 依赖单向；核心写调用只在组合根发生 -- **命名**：领域命名，禁止系统 ID 前缀（a1_/b1_/c1_）进入文件名与类名（子系统中文规范名 ↔ 英文代号对照表见 `design/gdd/02-系统清单.md`）；核心文件头注必须带「实现 GDD」溯源行；禁止事实约定——未成文的约定当场补条文 -- **契约**：信号/事件契约成文，状态机每条迁移路径都必须发事件（缺事件 = 软锁）；跨层标识符语义单一（位置 ≠ 句柄）；模态覆盖层打开必须隐藏遮挡物 -- **测试**：每个可交互 UI 区域必须配套场景级探针（只有 core AC 不算有测试）；缺陷修复必须沉淀回归断言；提交前 smoke + 全部场景探针全绿 -- **数值**：期望值必须标明尺度（每格/每板/每战/每关）；调参先测量后复测；单尺度校准必须跨尺度推演；用户拍板外的细节零发挥，列"待拍板"等裁决 +- **数值单一事实源**：玩法数值只存 `data/tables/`（.tres），经 `ConfigDB` autoload 类型化单点读取；禁止数值字面量与自建 `load()` 表路径 +- **RNG 单点**：禁止 `randomize()` / 自建 RandomNumberGenerator——随机只经 `RngService` 封闭命名流 +- **Core 层零 UI 依赖**：完整战斗必须可 `--headless --script` 跑通 +- **fail-fast**：数据校验错误一律致命中止，无软回退 +- **spec-AC 一致性**：规约与验收标准不得在同一输入上给出不同答案（所有 GDD 同尺度） +- **评审隔离**：`/design-review` 必须在独立会话跑（与 `/design-system` 隔离） diff --git a/docs/architecture/architecture.md b/docs/architecture/architecture.md index 4d7ecb6c..87f6f07f 100644 --- a/docs/architecture/architecture.md +++ b/docs/architecture/architecture.md @@ -82,7 +82,7 @@ ## Module Ownership -> 命名遵循 `docs/code-conventions.md` + CLAUDE.md 代码规范：领域命名、禁 ID 前缀、头注溯源行（实现 GDD：design/gdd/…）。切片已按此规范完成领域命名批。 +> 命名遵循 `docs/code-conventions.md`：领域命名、禁 ID 前缀、头注溯源行（实现 GDD：design/gdd/…）。切片已按此规范完成领域命名批。 ### Foundation 层 diff --git a/docs/code-conventions.md b/docs/code-conventions.md index 765cc050..50786927 100644 --- a/docs/code-conventions.md +++ b/docs/code-conventions.md @@ -2,7 +2,7 @@ > 生效：2026-09-11 · 来源：用户在垂直切片评审中逐一指出的真实陋习与缺陷，全部成文。 > 每条规则附本项目真实反面案例（标注缺陷编号/日期）——规则不是抽象美德，是踩过的坑。 -> 约束范围：`prototypes/` 与正式 `production` 代码同尺度；与 CLAUDE.md「Conventions」节既有硬约束 +> 约束范围：`prototypes/` 与正式 `production` 代码同尺度；与 CLAUDE.md「硬性红线」节既有硬约束 > （数值表单点 / RNG 封闭流 / Core 零 UI / fail-fast / spec-AC 一致性）并行生效，冲突以用户裁决为准。 **写任何代码前必须通读本文件。** diff --git a/docs/doc-conventions.md b/docs/doc-conventions.md index f17b1840..0fe5770e 100644 --- a/docs/doc-conventions.md +++ b/docs/doc-conventions.md @@ -1,6 +1,6 @@ # 文档写作规范（写文档前必读） -> **地位**：本文是本项目文档写作的规范权威，与 `docs/code-conventions.md`（代码规范）对等——写代码前必读代码规范，写文档前必读本文。CLAUDE.md 只保留摘要与指针，细则以本文为准。 +> **地位**：本文是本项目文档写作的规范权威，与 `docs/code-conventions.md`（代码规范）对等——写代码前必读代码规范，写文档前必读本文。CLAUDE.md 只保留导航指针，细则以本文为准。 > **适用范围**：`design/` 下一切现行文档（顶层文档、`systems/` 系统文档、`design/ux/`、`design/art/`、`design/research/`）与 `production/` 会话记录；`docs/` 其他说明文档参照执行。 > **成文**：2026-09-14。整合来源：用语纪律（2026-09-09 评审确立）· 文档形态纪律（2026-09-13 评审确立）· 两件套与树形文档体系纪律（2026-09-14 用户拍板）· 新骨架过渡口径（2026-09-14 用户拍板）· 可读性纪律（2026-09-14 用户提出）· 引用纪律（2026-09-14 用户提出）· 概念封装纪律（2026-09-15 用户提出）。 diff --git a/production/session-state/active.md b/production/session-state/active.md index a657e87c..7ee5a32c 100644 --- a/production/session-state/active.md +++ b/production/session-state/active.md @@ -134,3 +134,5 @@ 50. **两批验收 + 收口批（2026-09-15，本会话）**：对 2026-09-15 两批（攻击/护甲命名统一 v0.5 + 攻击类型/奖励抽象分离 v0.6）做只读核对 + 文档层收口（零数值零机制改动；**不改 v0.7 文件**——战斗结算.md / 奖励道具经济.md 属 v0.7 格面资源批所有者、口径仍在移动，本批不动）。**核对**：9 项口径↔实现全闭合（charge_grants 键与值 / 甲效矩阵 9 格 / armor_type 三值 / hero_attack 分量字段 normal·pierce·magic / round_facts charge_counts·charge_points / 敌卡标签 / 明细行拆行文案 / 攻击类型定义不含来源 / 矩阵数值逐格不动）；残留旧名扫描仅命中批次注记原名与历史观测记录（一处 playtest 注记"现名 charge_pierce"陈旧，已订正为 charge_counts/charge_points）；来源-类型硬绑扫描确认代码只剩两处计数埋点（`_charge_counts["safe_cell"]` / `["flag_hit"]`）+ charge_grants 键 + 行 source_class 归因。**实跑**：冒烟 201 项 0 失败；四探针 exit=0 无 FAIL。**收口（③，落在 registry + README + 本文件，GDD 侧只报告不改）**：① 收益对照表充能当量覆盖缺口登记（候选口径 = Σ各桶点数 × 当轮目标护甲平均甲效倍率 ÷ 100，1 伤害 = 1 当量守条款①；补式 / 登记待拍板二选一待回填批）；② 两处已知落差登记（charge_grants 触发源扩展 vs 切片两处埋点；safe_cell/flag_hit 跨命名空间同名）；③ playtest 快照键注记订正。**口径移动注记**：本会话运行期间 **v0.7 格面资源批**已在 GDD（战斗结算 v0.7 / 奖励道具经济 v0.4）+ registry 落地（五段 / 10 行型 / 极性路由 / 可选类删除），切片代码未同步——registry 已注明"切片代码修改随新会话执行、指导已产出"；本批核对结论针对 v0.5/v0.6 两批语义，v0.7 代码同步为独立后置批。 51. **概念封装纪律入规范（2026-09-15，用户提出）**：`docs/doc-conventions.md` v5 新增第 7 节「概念封装纪律（概念对象化建模）」——概念即对象 / 属性归属唯一 / 包含关系显式写 / 概念状态用枚举 / 附加物独立成对象 / 关系不吸内容；原 7/8/9 节顺延为 8/9/10，第 6 节骨架表与 CLAUDE.md 摘要的章节指针同步改指第 7、8 节。 + +52. **CLAUDE.md 瘦身重组（2026-09-15，用户拍板）**：定桩 = 只装全局元信息（栈/运行验证/目录）+ 硬性红线（原 Conventions 五条 + 评审隔离，D2 旧代号标注清除、出处承接于 architecture.md）+ 「规范导航」表（写代码前 / 写文档前两条必读门 + 设计/架构/引擎/registry/会话记录七行）；文档写作规范巨型条目与代码规范摘要块整体下沉子文档（code-conventions.md 经逐条核对着实为超集，零信息丢失）；同步活引用三处（code-conventions.md「硬性红线」节名 / architecture.md 命名行去 CLAUDE.md 指涉 / doc-conventions.md 地位声明改"只保留导航指针"）。