25 KiB
文档写作规范（写文档前必读）
地位：本文是本项目文档写作的规范权威，与
design/dev/code-conventions.md（代码规范）对等——写代码前必读代码规范，写文档前必读本文。CLAUDE.md 只保留导航指针，细则以本文为准。 适用范围：design/下一切现行文档（顶层文档、systems/系统文档、design/ux/、design/art/、design/research/）、根目录active.md会话记录与roadmap.md。 成文：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术语条目——不得让读者猜测比喻含义。 - 唯一例外：玩家在游戏里也会看到的专属名词（道具名、界面用语，如"显影尘""探巢摆钟"）。文档内部的机制概念不得造词。
自造词的三种固定形态（2026-10-04 黑话审计后补成，全部禁止）：审计发现本仓自造词几乎都长成下面三种样子，写的时候照着规避，读的时候见到即展开改写：
| 形态 | 反例（本仓真实案例） | 正确写法 |
|---|---|---|
| 给工作包起代号 | "样张批""八型批""资产升档重产批" | 叙述名 = 日期 + 做什么，如"2026-10-01 按新分辨率规格重做素材" |
| 给机制、检查、基线、区域造名词 | "熵增闸""形象锚""判读口径""暗淡记忆态""变异纹带" | 用行业通用词；确实要长期复用的概念走上面的登记通道（正常名字 + 首现白话定义 + registry 登记） |
| 给流程步骤造动词 | "收口""落籍""在飞""随批""对拍""销账""正主""台账" | 用日常动词：完成 / 合并进 master / 执行中 / 顺带 / 与基线数据逐项比对 / 注销 / 定义所属的那份文档 / 工作日志 |
通行检验标准：读者是业内人士，但没读过本项目的历史。一个词如果需要作者另外解释才能懂，这个词就不合格，包含它的句子必须重写成完整的白话句——换一个新名词不算改，展开才算改。
写后自查：每写完一条工作日志、一篇文档，重读一遍——凡是自己都要停顿一下才能想起意思的词，一律展开成完整句子。
5. 结构纪律
| 规则 | 内容 |
|---|---|
| 树形文档体系 | 全部设计文档构成一棵树；文档增删必须同步根索引 design/gdd/02-系统清单.md |
| 一页纸节点 | 一节、一条规则的内容控制在一页纸内（约 ≤80 行）；装不下就拆节，禁止铺开 |
| 一系统一文档 | 每个子系统一份设计文档，不建 analysis 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文 |
| 正文只写现行规则 | 禁止删除线、"（作废）"、"（日期+拍板）"式注记；修订只进文末「版本历史」表；义务台账、拍板记录等审计信息入 design/registry 或附录，不入正文 |
| 后置 ≠ 删除 | P1/P2 后置的内容逐条列出；复活后置项 = 修订文档，禁止静默加回 |
| 数值纪律 | 正文定规则、取值域、单位；平衡值进 data/tables/，provisional 必须标注；已锁数值事实源 = data/tables/ 与 design/registry/entities.yaml。强制收口条款（2026-09-17 数值压缩批后补成）：① 双写失同步禁止——任何数值变更（压缩 / 换装 / 投值 / 区间平移 / 增减行）必须同时同步所有引用该数值的 GDD 表格正文、registry entities.yaml 的 mvp_content / value_status、相关待办清单现状——三类之一未更新即视为该变更未完成（先例：2026-09-17 整体数值压缩批只动了 .tres 与切片代码，未同步 地图战斗资源.md / 增益状态.md 正文表格、entities.yaml mvp_content、06-待办清单.md 的 heal 负向直伤 条目，造成文档滞后）；② 调参表锁数后删现行值列——数值已锁定的调参表必须删除「现行值」列（敌人系统 v0.6 先例），仅保留 schema 模板与取值域，指路存根指向 data/tables/<file>.tres 与 registry/entities.yaml 对应条目；③ 覆盖范围 = 奖励 / 状态 / 敌人 / 技能 / 充能 / 护甲等级 / 区间掷点 / 难度曲线 / D_ref 等所有数值字段；④ 维护通道 = 走「设计批 → 同步批」两段式——数值表改完不等于修订完成，须同步收口后方可记入版本历史；⑤ 压缩/换装批 = 一律走「.tres 落批 + 切片 smoke 跑通 + GDD 表格指路化 + registry mvp_content 指路化 + 待办清单现状刷新」五步全收才记版本号，缺步则版本号不增 |
6. 文档类型与骨架
顶层文档：
| 文档 | 管什么 |
|---|---|
00-游戏概念.md |
一句话概念、目标受众、世界观命名、术语层级 |
01-核心循环.md |
玩家醒来→做什么→得到什么→又想做什么，一条线讲清 |
02-系统清单.md |
根索引：循环 × 子系统总表 + 文档树导航 |
03-内容规模.md |
几个关卡、几种敌人、几种道具——做多少砍多少 |
04-美术音频方向.md |
参考图、参考游戏、风格关键词 |
05-不做清单.md |
明确写：这些我不要 |
06-待办清单.md |
全项目待办事项的唯一登记处；各系统文档的「待办」节只留指路存根 |
系统文档骨架（systems/ 下统一采用）：
| 章节 | 要求 |
|---|---|
| 文首引言 | 一句话定位 + 状态（已定稿/范围草案/待设计）+ 旧版参考链接 |
| 设计目的 | 2-4 句白话，为什么需要这个系统 |
| 系统范围 | 负责/不负责两张表；表前一段白话说明边界 |
| 在核心循环中的位置 | 处于哪一段、上下游是谁（字符画一行 + 两句白话） |
| 核心规则 | 领域章节 ×2–6，每节一页纸 |
| 依赖与输出 | 上游/下游/对外事件与接口（表格；引用纪律见第 8 节） |
| P0 最小闭环 / P1·P2 后置 | MVP 最小集合与后置清单 |
| 调参表 | 参数名/取值域/现行值，provisional 标注 |
| 验收标准 | 可验证的判据 |
| 待办（可选） | 指路存根：条目单点登记 06-待办清单.md（见第 8 节「待办单点登记」），本节不再逐条登记 |
| 版本历史 | 表格 |
命名：中文、见名知意（如"游戏概念""棋盘生成"）；禁止 a1_/b1_ 编号前缀；不留纯空目录。正文中指代子系统一律用中文规范名；英文代号（供代码标识符与工具链）对照表见 design/gdd/02-系统清单.md，旧代号（a1–d6）仅限解读归档时使用，不得写进现行文档。
7. 概念封装纪律（概念对象化建模）
动笔之前先做概念建模：像写代码划分对象那样，把设计切成分界清晰的概念——每个概念有自己的规范名、自己的属性、自己的规则，概念之间靠显式关系（包含、挂载、引用）连接，而不是把所有内容揉进一个概念里。揉团的代价雾格事故已经付过一次（见第 8 节反例对照）：概念没有边界，删除修改就得全仓翻找。
| 规则 | 内容 |
|---|---|
| 概念即对象 | 核心概念各自独立成体，有规范名、有属性、有规则边界；下笔前先能用一句"它是谁、它管什么"说清，说不清就是还没想完 |
| 属性归属唯一 | 每个属性只归一个概念——离开 A 就没有意义的属性写在 A 名下，禁止上提给容器、也不下压给成员 |
| 包含关系显式写 | 容器与成员的关系明文写出谁是容器、谁是成员、一对几（例：棋盘包含多个格）；禁止让读者从散文里反推结构 |
| 概念状态用枚举 | 概念的类型与状态写成封闭枚举并列全成员（例：格的类型 = 安全格 / 雷格，格的状态 = 未开 / 已开）；禁止用散文形容词零散罗列状态 |
| 附加物独立成对象 | 挂在概念上的附加内容若自己有一组属性或规则要写（例：格上的奖励/惩罚 = 格面资源），就是独立对象——父概念只保留挂载位（如"有无资源资格"），禁止把附加物摊平成父概念的一堆属性字段 |
| 关系不吸内容 | 概念间关系只写"有没有关系、是什么关系"；对方的属性与规则留在对方名下——与第 8 节"引用不转述"同源 |
| 落位五要素 | 概念的正主文档必须写全五要素：定义（它是什么）/ 作用对象与范围（作用在谁、什么范围内有效）/ 生命周期（何时出现、何时变化、何时消失、怎么重置）/ 关联（与谁衔接、边界归谁、哪些指路别处）/ 状态（已定稿/待实施/已退役）。缺任何一项都是半成品概念，如同对象缺了构造函数（2026-09-30 微光口径事故后补成） |
切分正例（现行排雷循环即按此切分）：棋盘是地图级对象，包含多个格；格是成员对象，雷格/安全格是它的枚举属性；格上可能挂的奖励或惩罚（格面资源）是独立对象，本体与规则归地图战斗资源与战斗结算，格只保留"有无资源资格"一个挂载位。反面基准：把奖励的类型、数值、极性全摊开写成格子的属性字段——奖励规则一改，棋盘文档就得跟着改，这便是没封装。
无正主，不下定义：一个概念还没有正主文档时，任何其他文档都不得替它下定义——只能引用概念名，并在 06-待办清单登记「待落位」；谁先立正主，谁拿走全部定义权。（2026-09-30 微光事故：类型微光长期无正主文档，art-bible 复述、06 登记、任务书摘要三处各自给出口径，范围限定词在层层复述中丢失，最终放大成「全板常显」的错误事实。）
落盘载体：概念对象登记 design/registry/entities.yaml（owner 与 referenced_by 由此机械维护）；文档里概念怎么切，registry 就怎么登记，代码里的对象划分与之同构。
与引用纪律的关系：本节管单个概念的边界与归属（概念级封装），第 8 节管概念之间、文档之间的引用（跨文档解耦）——先有封装，第 8 节的单点定义、反向边与删除 SOP 才有干净的作用对象。
8. 引用纪律（跨文档高内聚低耦合）
目标：修改或删除一个概念时，只改它的 owner 文档；引用方最多删掉一个链接。反例对照 = 2026-09-14 雾格删除事故——雾格/迷雾/fog 三名并存、雾机制被织进多份文档的规则正文，导致全仓几十处文字修改与大量事后一致性复查。
| 规则 | 内容 |
|---|---|
| 单点定义 | 每个概念只在 owner 文档里定义一次，registry 术语条目登记其规范名 |
| 规范名唯一 | 正文只准用规范名，禁止别名散开——否则删除时 grep 搜不全 |
| 引用不转述 | 跨文档引用 = 规范名 + 链接，禁止复述对方的规则细节、公式、数值与口径；确需携带口径时，作用对象/范围/生命周期必须随句写全或显式指路——禁止只复述形容词，「常显」「恒亮」这类词不带范围就是半句话（2026-09-30 微光口径事故的直接形态）；若发现自己需要一条规则，那是自己的概念，先立正主再定义 |
| 引用落到对外承诺 | 跨文档链接只锚到对方文档明示的对外内容（事件、接口、规则条目），不锚其内部细节 |
| 依赖逐条列出 | 系统文档的「依赖与输出」节逐条列出本系统依赖的他人概念（规范名 + 链接）——这份清单就是删除概念时的影响面清单 |
| 引用必登记反向边 | 引用他系统概念时，在被引方的 registry 条目 referenced_by 里登记——影响面靠它机械列出，不靠全仓搜 |
| 链接断了也好读 | 引用处的句子在链接失效后仍通顺完整（写"变异规则见《地形变异》"，不把半截语义挂在链接里） |
| 待办单点登记 | 全项目待办事项单点登记于 design/gdd/06-待办清单.md：系统文档的「待办」节只留指路存根，不得自建条目表；新增待办条目直接登记清单，裁决后改「状态」列留痕、不删条目 |
引用格式：一律 Markdown 相对链接，指向文件、必要时带节锚点（例：[地形变异 · 变异类型](systems/排雷循环/地形变异.md#变异类型)）——机械可查，死链可被工具检出。
删除概念 SOP：① 查 registry 该条目的 referenced_by，得到影响面清单 → ② owner 文档删除概念 → ③ 纯引用方删链接即完事；机制被织入对方规则的，按清单逐处修订 → ④ 收尾跑一遍死链检查，全绿即干净。
诚实边界：机制耦合无法靠删链接消灭——别人的规则真的因你的概念而改变时，改内容不可避免。引用纪律保证的是：这类修改有一份现成清单（反向边 + 依赖节），不用事后全仓搜索。
9. 归档与事实源
- 旧文档里的概念写进现行文档时，必须翻译成现行术语与现行决策口径（例：雾格已从设计中移除，不得作为现行机制引用）。
- registry 中 owner 仍指向旧 GDD 路径的条目，在对应新系统文档定稿后逐条改指新路径。
10. 会话记录纪律
根目录 active.md（会话快照+批次台账）每条进度用完整的白话句子写清结论本身；条目写多长以读者能看懂为准，不设行数上限（2026-10-04 用户立规：能看懂比字数少更重要，原「每条 ≤3 行」约束废除——该约束曾迫使台账压缩成只有作者自己懂的自造缩略语，是文档黑话的繁殖地）。仍然禁止的只有两件：把定稿摘要、义务清单整段搬进条目（详情归各正主文档，台账只记结论）；以及自造黑话——第 4 节用语纪律对台账同等生效。台账条目记裁决结论本身，不记中间文档文件指针（见第 11 节）。
11. 文档生命周期：吸收即死（2026-10-01 用户立规）
文档分两类。活文档是唯一事实源，长期维护：GDD 树、art-bible 等定稿规范、registry、本规范、design/gdd/06-待办清单.md、roadmap.md。中间文档是脚手架，寿命=迭代寿命，不是项目寿命：批任务书、机检/验收过程报告、调研/审计报告、模拟读数、迭代计划书、目检清单。
为什么：了解游戏看 GDD，了解变更过程看 git 变更记录（commit message 与规范文档的版本历史节）。若每次变更都另存一份增量中间文档，版本管理就没有意义；带种子的模拟逐位可复现，原始数据 dump 是化石不是证据；没有人会读开发中的中间文档来了解游戏。"已归档留底追溯"不成立。
| 规则 | 内容 |
|---|---|
| 吸收即死 | 中间文档的结论写进正主文档（GDD 对应节/art-bible/registry）的那一刻，文件即删 |
| 未决先迁再死 | "还没完成/还有未决项"不是留的理由：未决内容先迁正主（06-待办清单.md/roadmap 卡/GDD 对应节），然后文档即死 |
| 永不入库 | 迭代出口（总结归档）后，本迭代中间产物一律删除，且不允许提交进 git；迭代进行中可暂存工作区（未跟踪或 gitignored），出口批一并清 |
| 引用面口径 | 活文档（design/gdd+design/art+design/dev+design/registry+roadmap.md+tools/）对中间文档的指路阻塞删除：先把指路句改写为结论内联或 git 提交号，再删文件；根 active.md 台账引用不阻塞（台账=历史变更记录） |
| 台账记结论 | 台账条目记裁决结论本身，不记中间文档文件指针；中间文档删除后不留死链指针 |
| sim-data 白名单 | sim-data/ 只保留 README、日志、分析工具 .py、现行 MC 对拍锚（显式清单）、设计文档 md；可再生原始数据（runsum/raw jsonl/逐局 CSV/report txt/样例输出）不入库 |
| 出口清理项 | 每迭代出口检查单必含清理项：本迭代中间产物逐份核对（结论已吸收、未决已迁移）后删除 |
| 暂存地非档案库 | design/research/ 与 design/qa/ 是中间文档的暂存地，不是永久档案库；入此两处的文件默认按本节规则到期即死 |
| 证据只留最新（2026-10-09 用户立规） | 测试证据（出口报告/读数/截图/对比图）只保留最新一次迭代或最新一轮同类审计的版本——旧证据无参考作用，测试按状态不按历史；新证据落位后同批删除上一份；等人工检查的清单不受此限，过人闸后按本行退役 |
删除方式：按第 8 节删除概念 SOP 的口径执行——先查引用面（grep 文件名于上表阻塞域），改写或删除指路句，再删文件，收尾跑死链检查全绿。
版本历史
| 版本 | 日期 | 说明 |
|---|---|---|
| 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 摘要的章节指针同步改指 |
| v6 | 2026-09-16 | 待拍板收编批：第 8 节引用纪律新增「待拍板单点登记」（待拍板事项单点登记 design/gdd/06-待拍板清单.md，系统文档只留指路存根，新增条目直接登记清单）；第 6 节顶层文档表补入 06-待拍板清单.md，骨架表「待拍板」行改为指路存根口径 |
| v7 | 2026-09-16 | 06 清单改版（用户拍板）：「待拍板」术语全仓改「待办」，清单更名 design/gdd/06-待办清单.md；清单内格式由四列表格改为「循环 → 系统 → 条目（四级标题）+ 粗体属性段（现状 / 归属 / 状态）」，条目解决后状态改"已解决（日期）"留痕；第 6 节顶层文档表与骨架表、第 8 节「待办单点登记」同步改指 |
| v8 | 2026-09-30 | 概念落位与口径携带条款（微光口径事故后补成，用户拍板）：第 7 节概念封装纪律增「落位五要素」行（定义/作用对象与范围/生命周期/关联/状态缺一不立）与「无正主，不下定义」段（概念未落正主前，任何文档不得替它下定义，只许 06 登记「待落位」）；第 8 节「引用不转述」行扩口径携带纪律（作用对象/范围/生命周期随句写全或显式指路，禁裸形容词复述） |
| v9 | 2026-10-02 | 文档生命周期条款（2026-10-01 用户立规「吸收即死」落文）：新增第 11 节——中间文档寿命=迭代寿命，结论吸收进正主即删、未决先迁再死、永不入库、引用面口径、台账记结论不记指针、sim-data 白名单、迭代出口清理项、design/research 与 design/qa 为暂存地非档案库；第 10 节补台账记结论口径；文首地位/适用范围两处过期路径修正（docs/→design/dev/、production/ 会话记录→根 active.md） |
| v10 | 2026-10-04 | 台账去压缩条款（用户立规）：第 10 节废除「每条 ≤3 行」——能看懂比字数少更重要；条目改用完整白话句子写结论，长度服从可读性；第 4 节黑话禁令对台账同等生效。起因：2026-10-04 黑话审计证实 ≤3 行压缩压力迫使台账条目使用自造缩略语（收口/落籍/在飞等约 15 个流程动词、530 条自造短语），并渗入正式文档；CLAUDE.md 规范导航表「会话进度记录」行同步改写 |
| v11 | 2026-10-04 | 第 4 节补强：自造词三形态禁令（用户令，黑话审计后）：新增自造词三种固定形态禁令表（工作包代号 / 机制造词 / 流程造词，各带本仓真实反例与正确写法）+ 通行检验标准（读者 = 业内人但没读过项目历史，需要作者解释的词即不合格，展开才算改）+ 写后自查动作；同批 CLAUDE.md 硬性红线新增「用语红线」一行。起因：原第 4 节禁令过于抽象、执行失效（全仓 530 条自造短语），且未明确覆盖对话输出与工作日志命名 |
| v12 | 2026-10-09 | §9 摘除 design/archive/gdd-2026-09-14/ 归档列项（目录已删，2026-10-09 用户令旧档引用全量摘除）；旧概念翻译与 registry 改指两条维持 |
| v13 | 2026-10-09 | §11 新增「证据只留最新」行（2026-10-09 用户立规——qa 存量清理批随批落文）：测试证据只保留最新迭代/最新一轮审计版本，新证据落位即删上一份；待人清单过闸后同规退役 |