docs: 概念封装纪律入写作规范 + CLAUDE.md 瘦身重组为导航式门文件
- doc-conventions v5:新增第 7 节「概念封装纪律(概念对象化建模)」六条(概念即对象 / 属性归属唯一 / 包含关系显式写 / 概念状态用枚举 / 附加物独立成对象 / 关系不吸内容),原 7/8/9 节顺延为 8/9/10,文内章节指针同步 - CLAUDE.md 重组:只装全局元信息 + 硬性红线 + 规范导航表(字符量 3535→2423);文档写作规范巨型条目与代码规范摘要块整体下沉子文档(code-conventions.md 逐条核对为超集,零信息丢失);D2 旧代号标注清除、出处承接于 architecture.md - 活引用同步:code-conventions.md「硬性红线」节名 / architecture.md 命名行去 CLAUDE.md 指涉 / doc-conventions.md 地位声明改「只保留导航指针」 - active.md 记第 51、52 条
This commit is contained in:
1 parent
ec0bdde7e0
commit
e250279536
5 files changed
+42
-40
No files matched your search
@@ -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` 隔离)
|
||||
@@ -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 层
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
> 生效:2026-09-11 · 来源:用户在垂直切片评审中逐一指出的真实陋习与缺陷,全部成文。
|
||||
> 每条规则附本项目真实反面案例(标注缺陷编号/日期)——规则不是抽象美德,是踩过的坑。
|
||||
> 约束范围:`prototypes/` 与正式 `production` 代码同尺度;与 CLAUDE.md「Conventions」节既有硬约束
|
||||
> 约束范围:`prototypes/` 与正式 `production` 代码同尺度;与 CLAUDE.md「硬性红线」节既有硬约束
|
||||
> (数值表单点 / RNG 封闭流 / Core 零 UI / fail-fast / spec-AC 一致性)并行生效,冲突以用户裁决为准。
|
||||
|
||||
**写任何代码前必须通读本文件。**
|
||||
|
||||
@@ -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 用户提出)。
|
||||
|
||||
|
||||
@@ -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 地位声明改"只保留导航指针")。
|
||||
Reference in new issue
Block a user