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

> **地位**：本文是文档写作的规范权威，与 `design/dev/code-conventions.md`（代码规范）对等；CLAUDE.md 只留导航指针，细则以本文为准。
> **适用范围**：`design/` 下一切现行文档、根目录 `active.md` 与 `roadmap.md`；概念建模与跨文档引用见 `design/dev/concept-conventions.md`。

## 0. 总纲

默认读者没读过项目历史——可能是半年后的你自己。先让人读懂，再谈结构整齐。

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

**读者测试是每个小节的验收标准**：只读这一节，回答三个问题——这节管的是谁/什么？在什么情况下？会发生什么？答不出来，就重写这一节，而不是给看不懂的地方补注释。

旧体系 lean 格式六条硬规则已停用，仅用于解读 `design/archive/` 旧文档（其表格占比口径为 30%）。`tools/gdd_lint.py` 现为现行文档机检三闸之一（gdd_lint / doc_link_audit / doc_term_audit，分级周期口径见 CLAUDE.md）；可读性仍是第一内容质量门，lint 是格式机检面，两者并行。旧模板留档 `.claude/docs/templates/`。

## 2. 白话写作规则

写文档像向朋友当面解释你的游戏：

1. **完整句子优先**：一段只说一件事，长句拆短句。
2. **禁止碎片笔记体**：不写压缩碎片，不把 `A→B→C` 箭头链当叙述（流程交给字符画，见第 3 节），不用只有作者自己懂的缩略语。
3. **每节人话开头**：每小节第一段先用白话说清"这是什么、为什么需要它"；只读各节第一段就能看懂全文故事线。
4. **术语首现即解释**：专业术语或项目概念首次出现用一句话解释；玩家可见专属名词（如"显影尘"）同样要说清。
5. **叙述优先于引用**：AC-x、F-x 等编号引用不进正文叙述，只出现在验收标准与附录。
6. **反面基准**：数据库条目、会议纪要、只有评审工具能"读懂"的表格堆。

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

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

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

## 4. 用语纪律（见名知意 · 所见即所得 · 禁自造黑话）

**正面总则**：见名知意——每个名字（概念名、术语、文档与目录名）本身就说清所指，起不出这样的名字多半是概念还没想清；所见即所得——字面意思就是规则的完整意思，有隐含前提就写进句子。两句管语义透明，不与第 8 节指路存根冲突。

文档、评审输出、日志与一切沟通中**禁止自造黑话**——比喻性生造词、只有作者自己懂的缩略语：

- 只能使用：（a）人人可懂的直白语言，或（b）游戏行业通用术语（如 flood fill、战争迷雾、连锁展开、结算、增益/减伤）。
- 指代新概念用直白描述性短语（正例："实测可推理率"）；确需命名时：首现处附一句白话定义，并登记 `design/registry` 术语条目。
- 唯一例外：玩家在游戏里也会看到的专属名词（道具名、界面用语）。文档内部的机制概念不得造词。

**自造词的三种固定形态（全部禁止）**：

| 形态 | 反例 | 正确写法 |
|---|---|---|
| 给工作包起代号 | "样张批""八型批" | 叙述名 = 日期 + 做什么 |
| 给机制、检查、基线、区域造名词 | "形象锚""判读口径""变异纹带" | 用行业通用词；长期复用的概念走登记通道（正常名字+白话定义+registry 登记） |
| 给流程步骤造动词 | "收口""落籍""在飞""随批""对拍""销账""正主""台账" | 用日常动词：完成 / 合并进 master / 执行中 / 顺带 / 与基线数据逐项比对 / 注销 / 定义所属的那份文档 / 状态记录 |

**通行检验标准**：读者是业内人但没读过项目历史——需要作者解释才懂的词不合格，必须展开成完整白话句（换新名词不算改，展开才算改）。**写后自查**：凡自己都要停顿才能想起意思的词，一律展开。

## 5. 结构纪律

| 规则 | 内容 |
|---|---|
| 树形文档体系 | 全部设计文档构成一棵树；文档增删必须同步根索引 `design/gdd/02-系统清单.md` |
| 架构事实唯一源 | `design/dev/architecture/architecture.md` 是架构事实的唯一权威（分层/模块归属/数据流/API 边界/测试与质量域）；禁建第二份架构文档；历史决策记录只进 git commit log |
| 一页纸节点 | 一节、一条规则 ≤一页纸（约 ≤80 行）；装不下就拆节 |
| 一系统一文档 | 不建 analysis 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文 |
| 正文只写现行规则 | 禁删除线、"（作废）"、"（日期+拍板）"式注记；审计信息入 `design/registry` 或附录 |
| 后置 ≠ 删除 | P1/P2 后置内容逐条列出；复活后置项 = 修订文档，禁静默加回 |

**数值纪律**：正文定规则、取值域、单位；平衡值进 `data/tables/`，provisional 必须标注；已锁数值事实源 = `data/tables/` 与 `design/registry/entities.yaml`。强制收口条款：

1. **双写失同步禁止**——任何数值变更必须同时同步引用该数值的 GDD 表格正文、registry `mvp_content`/`value_status`、相关待办清单现状——三类之一未更新即视为变更未完成。
2. **调参表锁数后删现行值列**——仅留 schema 模板与取值域，指路存根指向 `.tres` 与 `entities.yaml` 对应条目。
3. **覆盖范围** = 奖励/状态/敌人/技能/充能/护甲等级/区间掷点/难度曲线/D_ref 等所有数值字段。
4. **维护通道** = 「设计批 → 同步批」两段式；数值表改完不等于修订完成。
5. **压缩/换装批** = 「`.tres` 落批 + 切片 smoke 跑通 + GDD 表格指路化 + registry 指路化 + 待办清单刷新」五步全收才记版本号。

## 6. 文档类型与骨架

**顶层文档**：

| 文档 | 管什么 |
|---|---|
| `00-游戏概念.md` | 一句话概念、目标受众、世界观命名、术语层级 |
| `01-核心循环.md` | 玩家醒来→做什么→得到什么→又想做什么，一条线讲清 |
| `02-系统清单.md` | 根索引：循环 × 子系统总表 + 文档树导航 |
| `03-内容规模.md` | 几个关卡、几种敌人、几种道具——做多少砍多少 |
| `04-美术音频方向.md` | 参考图、参考游戏、风格关键词 |
| `05-不做清单.md` | 明确写：这些我不要 |
| `06-待办清单.md` | 流水线唯一登记处：条目=登记元数据标题＋四属性正文，状态随流水线段推进（格式与状态机见第 12.1 节）；各系统文档「待办」节只留指路存根 |
| `roadmap.md`（根目录） | 里程碑表＋迭代总表，一行一迭代，记录编排与实现进度（六列格式见第 12.2 节） |

**系统文档骨架**（`systems/` 下统一采用）：文首引言（一句话定位+状态+旧版链接）／设计目的（2-4 句白话）／系统范围（负责/不负责两表）／在核心循环中的位置（字符画一行+两句白话）／核心规则（领域章节 ×2–6，每节一页纸）／依赖与输出（表格；引用纪律见 concept-conventions）／P0 最小闭环与 P1·P2 后置／调参表（取值域+provisional 标注）／验收标准（可验证判据）／待办（指路存根）／版本历史（表格）。

**命名**：中文、见名知意；禁 a1_/b1_ 编号前缀；不留纯空目录。正文指代子系统一律用中文规范名；英文代号对照表见 `02-系统清单.md`，旧代号（a1–d6）仅限解读归档。

## 7–9. 概念封装 / 引用纪律 / 归档与事实源——已独立成文 `design/dev/concept-conventions.md`

## 10. 会话记录纪律

**active.md 定性：状态文件——状态记录，不是工作日志。** 根目录 `active.md` 是会话状态的唯一状态源，**每一行当下为真**；历史归 git 提交史。只许写三类：①当前状态快照（≤10 条滚动窗口）；②未决面（进行中批次/待人闸/待裁点指针）；③当前迭代滚动工作条目。禁止写入：已完结批次的历史叙述、待办裁决事项（归 06）、跨会话教训（归记忆库）；并行会话禁止整体复原/回退本文件。退役规则：**用户确认任务完成时清除当前会话写过的状态条目——状态清除即任务完成的证明**；条目完结判据=批次已入库+结论已进快照+未决面无条目指向；迭代收口兜底删除已完结条目，超过 30 条必须清。**机械闸**=`tools/audit_active_state.py`，判四条可机械测的膨胀签名（条目数上限、快照行数上限、条目编号重复、指向中间文档的死指针），随 `tools/run_all_gates.sh` 全量档跑并由合回闸强制——收口漏删旧条目，合回时会被拦下。

条目用完整白话句子写清结论本身，长度服从可读性（能看懂比字数少重要）；禁把定稿摘要、义务清单整段搬进条目（详情归权威文档）；第 4 节用语纪律对状态记录同等生效；条目记裁决结论本身，不记中间文档文件指针（见第 11 节）。

## 11. 文档生命周期：吸收即死

**活文档**=唯一事实源长期维护：GDD 树、art-bible 等定稿规范、registry、架构文档（`design/dev/architecture/architecture.md`）、本规范、06-待办清单、roadmap。**中间文档**=脚手架，寿命=迭代寿命：批需求卡片、机检/验收过程报告、调研/审计报告、模拟读数、迭代计划书、目检清单。为什么：了解游戏看 GDD，了解变更看 git；增量中间文档让版本管理失去意义，原始数据 dump 是化石不是证据。

| 规则 | 内容 |
|---|---|
| 吸收即死 | 中间文档结论写进权威文档（GDD 对应节/art-bible/registry）那一刻，文件即删 |
| 未决先迁再死 | 未决内容先迁现行事实源（06/roadmap 卡/GDD 对应节），然后文档即死 |
| 永不入库 | 迭代出口后中间产物一律删除且不许提交；迭代进行中可暂存工作区，出口批一并清 |
| 引用面口径 | 活文档对中间文档的指路阻塞删除：先改写指路句为结论内联或 git 提交号再删；active.md 状态记录引用不阻塞 |
| 状态记录记结论 | 条目记裁决结论本身不记中间文档指针；中间文档删除后不留死链指针 |
| sim-data 白名单 | 只留 README、日志、分析工具 .py、现行 MC 对拍锚、设计文档 md；可再生原始数据不入库 |
| 出口清理项 | 每迭代出口检查单必含：本迭代中间产物逐份核对（结论已吸收、未决已迁移）后删除 |
| 暂存地非档案库 | `design/research/` 与 `design/qa/` 是中间文档暂存地，入内文件默认到期即死 |
| 迭代实现报告 | 实现批收口的迭代级报告（各卡状态/代拍板追认单/GDD 反哺点清单），属中间文档，**落 `reports/` 不落 `design/`**（2026-10-17 用户裁：实现批禁写 `design/`，`reports/` 是其唯一可写目录）：反哺点裁决落文吸收后按「证据只留最新」退役 |
| 证据只留最新 | 测试证据只保留最新一次迭代或最新一轮同类审计版本；新证据落位后同批删上一份；待人清单过人闸后同规退役 |

**删除方式**：按 `design/dev/concept-conventions.md` 第 2 节删除概念 SOP 口径——先查引用面（grep 文件名于阻塞域），改写或删除指路句，再删文件，收尾跑死链检查全绿。

## 12. 流程文档格式

五段流水线（登记 → 文档设计／美术设计 → 写卡 → 迭代编排 → 实现，流程纪律见 `design/dev/process-conventions.md` §2）靠流程文档运转：06-待办清单登记要做的事，roadmap 记录迭代编排结果，artwork 目录承载美术在途素材。本节是这些流程文档的格式与状态机权威，也是流水线闸（`tools/pipeline_gate.py`，自动检查 06 与 roadmap 两文件格式及互相引用的机检闸）的判据依据。

### 12.1 06-待办清单条目格式与状态机

06-待办清单是流水线的唯一登记处：要做的事先登记一条，随流水线段推进改状态，做完整条删除。一条条目分两层——**标题=登记元数据**（何时登记、从哪来、走哪条设计轨，登记后不再变），**正文=四个属性**（随进程演进）。

标题格式（尖括号处按实际填写）：

```
#### <条目名>（<YYYY-MM-DD>登记，来源=<playnote／会话提及／审计发现／批次移交>，设计面=<文档轨／美术轨／双轨／工程直入／反哺点>）
```

正文四属性模板：

```
**现状**：现在缺什么、为什么是问题（关键处带 file:line 或文档指针）。工程直入条目必须在现状里指认证据（bug 证据或工程债条目）。
**缺口**：还差哪一次设计讨论／哪份设计产物才能写卡。仅当状态为 待文档设计/文档设计中/待美术设计/美术设计中 时此属性必须存在；轨闭合后必须删除。
**归属**：主责系统文档或线别。
**状态**：按状态机取词。
```

状态机按标题里的设计面分轨，状态一律取下例用词：

```
文档轨：待文档设计 → 文档设计中 → 文档设计已闭合
        （凭据=文档路径+版本号，例：文档设计已闭合（design/gdd/systems/xxx.md v1.2））
美术轨：待美术设计 → 美术设计中 → 美术设计已闭合
        （凭据=样张过审＋art-bible 条款版本）
双轨条目：两串状态用＋号并列（例：文档设计已闭合（…v0.6）＋美术设计中）
轨闭合后下游共用：待写卡 → 已写卡（design/research/ 下的卡片路径）→ 已编迭代 N → 完成即整条删除
```

三条特殊通道：

| 设计面 | 通道规则 |
|---|---|
| 工程直入 | 缺陷修复／工程债／测试基建／重构四类工程条目：登记即「待写卡」，凭现状里指认的证据跳过设计轨 |
| 反哺点专条 | 待裁决 → 已写入（落点=文档+版本）→ 删除 |
| 备选库条目 | 暂不排期、留在备选库的条目：状态词后缀「（备选）」 |

「已闭合」不带凭据不算合法状态词。特批标记见 12.4。

### 12.2 roadmap 迭代行格式

roadmap 由顶部里程碑表＋迭代总表组成，迭代总表一行一个迭代，回答一个问题：这个迭代编入了哪些卡、做到哪一步。迭代行六列：

```
| 迭代号 | 状态 | 需求卡片 | 编入时间 | 预计周期 | 实现报告 |
```

| 列 | 规则 |
|---|---|
| 迭代号 | 写「迭代 N」形态（N 为阿拉伯数字）；这是流水线闸交叉核匹配的依据 |
| 状态 | 待开工 ／ 进行中 ／ 已完成（YYYY-MM-DD）／ 已终止（YYYY-MM-DD） |
| 需求卡片 | 只写文件路径；一格内一行一卡，格内排列顺序=执行顺序；已退役填保留字「已退役（git 历史可考）」 |
| 编入时间 | YYYY-MM-DD（该迭代最近一次编入卡片的日期） |
| 预计周期 | ≈N 周（0.5 步进，N ≤ 2） |
| 实现报告 | `reports/iterN-实现报告-YYYY-MM-DD.md`；未完成=「—」；退役=「已退役（git 历史可考）」 |

迭代行禁入内容：事项说明、卡序叙述、T 段明细、读数、闸数字、裁点记录、门依赖。卡间依赖写在卡片自身，行内只放上表六列的事实。特批标记同样可用于 roadmap 格（须带日期，见 12.4）。

### 12.3 美术工作区目录与命名

美术素材走两条目录线：在途工作在 `artwork/`（整目录不入 git），定稿进 `game/assets/art/`（入包被游戏加载）。图片永不进 `design/`。

| 位置 | 规则 |
|---|---|
| `artwork/<YYYY-MM-DD-主题>/` | 批次工作区，一次美术批一个目录，整目录不入 git |
| `artwork/<批次工作区>/samples/` | 样张子目录 |
| `artwork/archive/<主题>-<日期>/` | 批次完结归档 |
| `game/assets/art/<用途子目录>/` | 终稿，入包被游戏加载 |

命名总则：全小写英文＋下划线，禁中文／空格／大写。

| 对象 | 文件名规则 |
|---|---|
| 终稿 | 三段式 `<对象>_<部位或状态>_<规格>.png`；终稿文件名=代码消费名——先定 ui_kit／资源路径常量，素材名跟它走，防断链 |
| 样张 | `sample_<屏名>_<版本>.png` |
| 同名迭代 | 直接覆盖，不留 v2 副本 |

美术内容不做机检，只保留命名与目录检查。

### 12.4 特批标记

特批标记是流程格式例外的唯一放行凭证：`〔用户特批 YYYY-MM-DD 跳过××〕`。只有用户明示才能给，用于 06 条目状态与 roadmap 格（见 12.1、12.2）。

执行技能一律两段式：

1. 对象已有内容 → 直接写入标记。
2. 对象没有任何内容 → 必须回呈实况，经用户再次确认后才写标记。

标记必须带日期，无日期=非法。流水线闸见合法特批标记放行对应判据。