0 Fork 0

Files

T

DKChan ec0bdde7e0 docs: 攻击/护甲命名统一与类型-奖励抽象分离，落地格面资源批并补验收收口

- 命名统一：攻击类型 {base,dmg_a,dmg_b}->{normal,pierce,magic}；护甲 {none,a,b}->{light,ward,heavy}

- 抽象分离：攻击类型=伤害属性轴，充能投桶归奖励定义 charge_grants（开格/标中旗/踩雷/清图仅作触发源）

- 格面资源批（文档+registry）：段序七->五、行型 15->10、极性路由取代固定兑付、可选类道具删除

- 验收收口：registry/README/active 登记充能当量折算缺口与两处落差；playtest 陈旧键名注记订正

- 实跑：冒烟 201 项 0 失败，四探针 exit=0 无 FAIL

2026-09-15 23:17:40 +08:00

14 KiB

Raw Blame History

文档写作规范（写文档前必读）

地位：本文是本项目文档写作的规范权威，与 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 用户提出）。

0. 总纲

文档是写给人看的：先让人读懂，再谈结构整齐。默认读者没有读过项目历史——可能是半年后的你自己，也可能是未来的协作者。下面所有规则都为这个读者服务。

1. 可读性第一（最高纪律）

读者测试是每个小节的验收标准：只读这一节，回答三个问题——

这节管的是谁/什么？
在什么情况下？
会发生什么？

答不出来，就重写这一节，而不是给看不懂的地方补注释。

与旧体系门禁的关系：旧体系的 lean 格式六条硬规则与 tools/gdd_lint.py 门禁已随 2026-09-14 归档停用（PostToolUse 钩子同批停用，工具本体留 tools/ 备查），此后仅用于解读 design/archive/ 里的旧文档（解读时注意其表格占比口径为 30%，2026-09-14 由 60% 放宽）。现行文档不跑 lint；可读性是唯一的内容质量门。旧模板文件留档 .claude/docs/templates/ 备查。

2. 白话写作规则

写文档像向朋友当面解释你的游戏。具体做法：

完整句子优先：用完整的句子把话说完；一段只说一件事，长句拆短句。
禁止碎片笔记体：正文不得写压缩碎片，不得把 A→B→C 箭头链当叙述（流程交给字符画，见第 3 节），不得使用只有作者自己懂的缩略语。
每节人话开头：每个小节的第一段先用白话说清"这是什么、为什么需要它"，然后再展开细节。做到只读各节第一段，就能看懂整篇文档的故事线。
术语首现即解释：专业术语或项目概念第一次出现时，用一句话（可以用括号）解释它是什么，之后才允许直接使用。玩家会看到的专属名词（如"显影尘"）同样要说清。
叙述优先于引用：AC-x、F-x 等编号引用不进正文叙述，只出现在验收标准与附录；正文用直白语言把规则本身说出来。
反面基准：数据库条目、会议纪要、只有评审工具能"读懂"的表格堆——都不是我们要的文档。

3. 表达分工：散文、表格、字符画、公式

不同内容用不同载体，各司其职：

内容	载体	纪律
规则的来龙去脉、行为逻辑	散文段	每段 ≤240 字，一段一件事
枚举、数值、边界、依赖	表格	表格只放可列举的事实；禁止把需要解释的内容塞进单元格让读者自己拼
流程、状态流转	字符画（代码块）	禁止用散文逐步描述流程
公式	结论先行	先一行加粗结论，再放公式代码块、变量表与验算表；公式本体必须保留
体验锚点	关键词表	支柱/关键词/机制承诺三列表，禁止长篇情绪描述

节点内顺序：先人话，再表格枚举，再字符流程图，最后公式举证。

规则两段式：核心规则先写"人话阶段"（作用于哪个系统、什么情况下、谁触发、触发后发生什么），再写"举证阶段"（逐效果给出计算方法或公式；纯流程规则明写"无计算"）。规则名禁止纯名词短语（反面例："获取路由"）。

4. 用语纪律（禁自造黑话）

文档、评审输出、日志与一切沟通中禁止自造黑话——比喻性生造词、只有作者自己懂的缩略语（历史反例："非雾腿""双闸"）。

只能使用：（a）人人可懂的直白语言，或（b）游戏行业通用术语（如 flood fill、战争迷雾、连锁展开、结算、增益/减伤）。
需要指代新概念时，用直白的描述性短语（正例："实测可推理率"——限定语与规范名绑定）。
确需给新概念命名时：首次出现处必须附一句白话定义，并登记 design/registry 术语条目——不得让读者猜测比喻含义。
唯一例外：玩家在游戏里也会看到的专属名词（道具名、界面用语，如"显影尘""探巢摆钟"）。文档内部的机制概念不得造词。

5. 结构纪律

规则	内容
树形文档体系	全部设计文档构成一棵树；文档增删必须同步根索引 `design/gdd/02-系统清单.md`
一页纸节点	一节、一条规则的内容控制在一页纸内（约 ≤80 行）；装不下就拆节，禁止铺开
一系统一文档	每个子系统一份设计文档，不建 analysis 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文
正文只写现行规则	禁止删除线、"（作废）"、"（日期+拍板）"式注记；修订只进文末「版本历史」表；义务台账、拍板记录等审计信息入 `design/registry` 或附录，不入正文
后置 ≠ 删除	P1/P2 后置的内容逐条列出；复活后置项 = 修订文档，禁止静默加回
数值纪律	正文定规则、取值域、单位；平衡值进 `data/tables/`，provisional 必须标注；已锁数值事实源 = `data/tables/` 与 `design/registry/entities.yaml`

6. 文档类型与骨架

顶层六文档：

文档	管什么
`00-游戏概念.md`	一句话概念、目标受众、世界观命名、术语层级
`01-核心循环.md`	玩家醒来→做什么→得到什么→又想做什么，一条线讲清
`02-系统清单.md`	根索引：循环 × 子系统总表 + 文档树导航
`03-内容规模.md`	几个关卡、几种敌人、几种道具——做多少砍多少
`04-美术音频方向.md`	参考图、参考游戏、风格关键词
`05-不做清单.md`	明确写：这些我不要

系统文档骨架（systems/ 下统一采用）：

章节	要求
文首引言	一句话定位 + 状态（已定稿/范围草案/待设计）+ 旧版参考链接
设计目的	2-4 句白话，为什么需要这个系统
系统范围	负责/不负责两张表；表前一段白话说明边界
在核心循环中的位置	处于哪一段、上下游是谁（字符画一行 + 两句白话）
核心规则	领域章节 ×2–6，每节一页纸
依赖与输出	上游/下游/对外事件与接口（表格；引用纪律见第 8 节）
P0 最小闭环 / P1·P2 后置	MVP 最小集合与后置清单
调参表	参数名/取值域/现行值，provisional 标注
验收标准	可验证的判据
待拍板（可选）	冲突、缺口、设计变更失义条目
版本历史	表格

命名：中文、见名知意（如"游戏概念""棋盘生成"）；禁止 a1_/b1_ 编号前缀；不留纯空目录。正文中指代子系统一律用中文规范名；英文代号（供代码标识符与工具链）对照表见 design/gdd/02-系统清单.md，旧代号（a1–d6）仅限解读归档时使用，不得写进现行文档。

7. 概念封装纪律（概念对象化建模）

动笔之前先做概念建模：像写代码划分对象那样，把设计切成分界清晰的概念——每个概念有自己的规范名、自己的属性、自己的规则，概念之间靠显式关系（包含、挂载、引用）连接，而不是把所有内容揉进一个概念里。揉团的代价雾格事故已经付过一次（见第 8 节反例对照）：概念没有边界，删除修改就得全仓翻找。

规则	内容
概念即对象	核心概念各自独立成体，有规范名、有属性、有规则边界；下笔前先能用一句"它是谁、它管什么"说清，说不清就是还没想完
属性归属唯一	每个属性只归一个概念——离开 A 就没有意义的属性写在 A 名下，禁止上提给容器、也不下压给成员
包含关系显式写	容器与成员的关系明文写出谁是容器、谁是成员、一对几（例：棋盘包含多个格）；禁止让读者从散文里反推结构
概念状态用枚举	概念的类型与状态写成封闭枚举并列全成员（例：格的类型 = 安全格 / 雷格，格的状态 = 未开 / 已开）；禁止用散文形容词零散罗列状态
附加物独立成对象	挂在概念上的附加内容若自己有一组属性或规则要写（例：格上的奖励/惩罚 = 格面资源），就是独立对象——父概念只保留挂载位（如"有无资源资格"），禁止把附加物摊平成父概念的一堆属性字段
关系不吸内容	概念间关系只写"有没有关系、是什么关系"；对方的属性与规则留在对方名下——与第 8 节"引用不转述"同源

切分正例（现行排雷循环即按此切分）：棋盘是地图级对象，包含多个格；格是成员对象，雷格/安全格是它的枚举属性；格上可能挂的奖励或惩罚（格面资源）是独立对象，本体与规则归奖励道具经济与战斗结算，格只保留"有无资源资格"一个挂载位。反面基准：把奖励的类型、数值、极性全摊开写成格子的属性字段——奖励规则一改，棋盘文档就得跟着改，这便是没封装。

落盘载体：概念对象登记 design/registry/entities.yaml（owner 与 referenced_by 由此机械维护）；文档里概念怎么切，registry 就怎么登记，代码里的对象划分与之同构。

与引用纪律的关系：本节管单个概念的边界与归属（概念级封装），第 8 节管概念之间、文档之间的引用（跨文档解耦）——先有封装，第 8 节的单点定义、反向边与删除 SOP 才有干净的作用对象。

8. 引用纪律（跨文档高内聚低耦合）

目标：修改或删除一个概念时，只改它的 owner 文档；引用方最多删掉一个链接。反例对照 = 2026-09-14 雾格删除事故——雾格/迷雾/fog 三名并存、雾机制被织进多份文档的规则正文，导致全仓几十处文字修改与大量事后一致性复查。

规则	内容
单点定义	每个概念只在 owner 文档里定义一次，registry 术语条目登记其规范名
规范名唯一	正文只准用规范名，禁止别名散开——否则删除时 grep 搜不全
引用不转述	跨文档引用 = 规范名 + 链接，禁止复述对方的规则细节、公式与数值；若发现自己需要一条规则，那是自己的概念，就地定义
引用落到对外承诺	跨文档链接只锚到对方文档明示的对外内容（事件、接口、规则条目），不锚其内部细节
依赖逐条列出	系统文档的「依赖与输出」节逐条列出本系统依赖的他人概念（规范名 + 链接）——这份清单就是删除概念时的影响面清单
引用必登记反向边	引用他系统概念时，在被引方的 registry 条目 `referenced_by` 里登记——影响面靠它机械列出，不靠全仓搜
链接断了也好读	引用处的句子在链接失效后仍通顺完整（写"变异规则见《地形变异》"，不把半截语义挂在链接里）

引用格式：一律 Markdown 相对链接，指向文件、必要时带节锚点（例：[地形变异 · 变异类型](systems/排雷循环/地形变异.md#变异类型)）——机械可查，死链可被工具检出。

删除概念 SOP：① 查 registry 该条目的 referenced_by，得到影响面清单 → ② owner 文档删除概念 → ③ 纯引用方删链接即完事；机制被织入对方规则的，按清单逐处修订 → ④ 收尾跑一遍死链检查，全绿即干净。

诚实边界：机制耦合无法靠删链接消灭——别人的规则真的因你的概念而改变时，改内容不可避免。引用纪律保证的是：这类修改有一份现成清单（反向边 + 依赖节），不用事后全仓搜索。

9. 归档与事实源

design/archive/gdd-2026-09-14/ 是旧版 GDD 体系的只读归档：不维护、不修改，禁止作为事实引用。
旧文档里的概念写进现行文档时，必须翻译成现行术语与现行决策口径（例：雾格已从设计中移除，不得作为现行机制引用）。
registry 中 owner 仍指向旧 GDD 路径的条目，在对应新系统文档定稿后逐条改指新路径。

10. 会话记录纪律

production/session-state/active.md 每条进度 ≤3 行（粗体键 + 短句）；详情一律外链到对应文档或报告，禁止把定稿摘要、义务清单整段塞进条目。

版本历史

版本	日期	说明
v1	2026-09-14	首版成文：整合用语纪律、文档形态纪律、两件套与树形文档体系、新骨架过渡口径，新增可读性第一纪律与系统文档骨架
v2	2026-09-14	新增第 7 节引用纪律（跨文档高内聚低耦合：单点定义 / 规范名唯一 / 引用不转述 / 反向边登记 / 删除概念 SOP），原 7/8 节顺延为 8/9
v3	2026-09-15	命名纪律补充：现行文档代号清偿完毕，子系统统一以中文规范名指代；英文代号对照表落盘 `design/gdd/02-系统清单.md`，旧代号仅限解读归档
v4	2026-09-15	用语纪律正例去雾：第 4 节正例"剔除雾格后的可推理率"改为现行指标"实测可推理率"（原指标随雾格移除已删）；规则文字与历史反例"非雾腿"、第 8 节雾格移除去向说明均不动
v5	2026-09-15	新增第 7 节概念封装纪律（概念对象化建模：概念即对象 / 属性归属唯一 / 包含关系显式写 / 概念状态用枚举 / 附加物独立成对象 / 关系不吸内容），原 7/8/9 节顺延为 8/9/10，第 6 节骨架表与 CLAUDE.md 摘要的章节指针同步改指

14 KiB Raw Blame History Unescape Escape