DKChan
18e22f1b44
- CLAUDE.md 137→140：日期注记全清；文件头红线收敛为指针（全表唯一权威=code-conventions §1.4.1）；测试两入口/闸机轮次/MC 档位超长红线拆子条目（MC 精度数字收敛为 sim-data/README 档位表指针）；规范导航补 test-conventions/concept-conventions 两行 - code-conventions 210→148：§3 测试纪律拆出独立成文；缺陷对照表与版本历史表退役（历史归 git）；反面案例去日期化；与 §1.5 重复的流程条目合并 - doc-conventions 210→149：概念封装/引用纪律/归档三节拆出 concept-conventions.md（原 §7–9 合并桩节标注）；§10/§11 保号——active.md 与 tools 脚本存量引用零断链；数值纪律强制收口条款移出表格单元格 - 新增 test-conventions.md（49 行）：探针标配/回归断言/提交前全量验证/验收清单落码规范 - 新增 concept-conventions.md（54 行）：概念封装建模/跨文档引用纪律/归档与事实源 - 机械闸：五文件行数≤150 ✓ IMPORTANT=0 ✓ 日期残留=0 ✓ 熵增闸 PASS ✓ doc 三闸（gdd_lint/doc_link_audit/doc_term_audit）对改动文件零波及（存量 GDD 基线失败与本批无关） - 行为验证：全新上下文只读子代理五问导航 5/5 正确（含两份新文档命中与 §10/§11 交叉印证）
15 KiB
文档写作规范（写文档前必读）
地位：本文是本项目文档写作的规范权威，与
design/dev/code-conventions.md（代码规范）对等——写代码前必读代码规范，写文档前必读本文。CLAUDE.md 只保留导航指针，细则以本文为准。 适用范围：design/下一切现行文档（顶层文档、systems/系统文档、gdd/ux/、design/art/、design/research/）、根目录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. 白话写作规则
写文档像向朋友当面解释你的游戏。具体做法：
- 完整句子优先：用完整的句子把话说完；一段只说一件事，长句拆短句。
- 禁止碎片笔记体：正文不得写压缩碎片，不得把
A→B→C箭头链当叙述（流程交给字符画，见第 3 节），不得使用只有作者自己懂的缩略语。 - 每节人话开头：每个小节的第一段先用白话说清"这是什么、为什么需要它"，然后再展开细节。做到只读各节第一段，就能看懂整篇文档的故事线。
- 术语首现即解释：专业术语或项目概念第一次出现时，用一句话（可以用括号）解释它是什么，之后才允许直接使用。玩家会看到的专属名词（如"显影尘"）同样要说清。
- 叙述优先于引用：AC-x、F-x 等编号引用不进正文叙述，只出现在验收标准与附录；正文用直白语言把规则本身说出来。
- 反面基准：数据库条目、会议纪要、只有评审工具能"读懂"的表格堆——都不是我们要的文档。
3. 表达分工：散文、表格、字符画、公式
不同内容用不同载体，各司其职：
| 内容 | 载体 | 纪律 |
|---|---|---|
| 规则的来龙去脉、行为逻辑 | 散文段 | 每段 ≤240 字，一段一件事 |
| 枚举、数值、边界、依赖 | 表格 | 表格只放可列举的事实；禁止把需要解释的内容塞进单元格让读者自己拼 |
| 流程、状态流转 | 字符画（代码块） | 禁止用散文逐步描述流程 |
| 公式 | 结论先行 | 先一行加粗结论，再放公式代码块、变量表与验算表；公式本体必须保留 |
| 体验锚点 | 关键词表 | 支柱/关键词/机制承诺 三列表，禁止长篇情绪描述 |
节点内顺序：先人话，再表格枚举，再字符流程图，最后公式举证。
规则两段式：核心规则先写"人话阶段"（作用于哪个系统、什么情况下、谁触发、触发后发生什么），再写"举证阶段"（逐效果给出计算方法或公式；纯流程规则明写"无计算"）。规则名禁止纯名词短语（反面例："获取路由"）。
4. 用语纪律（见名知意 · 所见即所得 · 禁自造黑话）
正面总则：见名知意，所见即所得。 见名知意——用到的每个名字（概念名、术语、文档与目录名）本身就说清它指什么，读者看到名字、不用等解释就知道大概；起不出这样的名字，多半是概念还没想清，先想清再落笔。所见即所得——读者读到的字面意思就是规则的完整意思，不需要追问作者、翻查项目历史或脑补隐含前提才能还原真实含义；有隐含前提就写进句子，有言外之意就写成正文。这两句管的是把话说明白，不是要求把所有信息都塞进本文——该指路的地方仍按第 8 节指路。本节其余禁令说哪些写法不行，这两句说行的是什么。
文档、评审输出、日志与一切沟通中禁止自造黑话——比喻性生造词、只有作者自己懂的缩略语。
- 只能使用：（a）人人可懂的直白语言，或（b）游戏行业通用术语（如 flood fill、战争迷雾、连锁展开、结算、增益/减伤）。
- 需要指代新概念时，用直白的描述性短语（正例："实测可推理率"——限定语与规范名绑定）。
- 确需给新概念命名时：首次出现处必须附一句白话定义，并登记
design/registry术语条目——不得让读者猜测比喻含义。 - 唯一例外：玩家在游戏里也会看到的专属名词（道具名、界面用语，如"显影尘""探巢摆钟"）。文档内部的机制概念不得造词。
自造词的三种固定形态（全部禁止）——写的时候照着规避，读的时候见到即展开改写：
| 形态 | 反例 | 正确写法 |
|---|---|---|
| 给工作包起代号 | "样张批""八型批""资产升档重产批" | 叙述名 = 日期 + 做什么，如"按新分辨率规格重做素材" |
| 给机制、检查、基线、区域造名词 | "形象锚""判读口径""暗淡记忆态""变异纹带" | 用行业通用词；确实要长期复用的概念走上面的登记通道（正常名字 + 首现白话定义 + registry 登记） |
| 给流程步骤造动词 | "收口""落籍""在飞""随批""对拍""销账""正主""台账" | 用日常动词：完成 / 合并进 master / 执行中 / 顺带 / 与基线数据逐项比对 / 注销 / 定义所属的那份文档 / 状态记录 |
通行检验标准：读者是业内人士，但没读过本项目的历史。一个词如果需要作者另外解释才能懂，这个词就不合格，包含它的句子必须重写成完整的白话句——换一个新名词不算改，展开才算改。
写后自查：每写完一条状态记录、一篇文档，重读一遍——凡是自己都要停顿一下才能想起意思的词，一律展开成完整句子。
5. 结构纪律
| 规则 | 内容 |
|---|---|
| 树形文档体系 | 全部设计文档构成一棵树；文档增删必须同步根索引 design/gdd/02-系统清单.md |
| 一页纸节点 | 一节、一条规则的内容控制在一页纸内（约 ≤80 行）；装不下就拆节，禁止铺开 |
| 一系统一文档 | 每个子系统一份设计文档，不建 analysis 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文 |
| 正文只写现行规则 | 禁止删除线、"（作废）"、"（日期+拍板）"式注记；义务台账、拍板记录等审计信息入 design/registry 或附录，不入正文 |
| 后置 ≠ 删除 | P1/P2 后置的内容逐条列出；复活后置项 = 修订文档，禁止静默加回 |
数值纪律：正文定规则、取值域、单位；平衡值进 data/tables/，provisional 必须标注；已锁数值事实源 = data/tables/ 与 design/registry/entities.yaml。强制收口条款：
- 双写失同步禁止——任何数值变更（压缩 / 换装 / 投值 / 区间平移 / 增减行）必须同时同步所有引用该数值的 GDD 表格正文、registry
entities.yaml的mvp_content/value_status、相关待办清单现状——三类之一未更新即视为该变更未完成（反例：数值压缩批只动了.tres与切片代码，三类文档全部滞后）。 - 调参表锁数后删现行值列——数值已锁定的调参表必须删除「现行值」列，仅保留 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，每节一页纸 |
| 依赖与输出 | 上游/下游/对外事件与接口（表格；引用纪律见 design/dev/concept-conventions.md） |
| P0 最小闭环 / P1·P2 后置 | MVP 最小集合与后置清单 |
| 调参表 | 参数名/取值域/现行值，provisional 标注 |
| 验收标准 | 可验证的判据 |
| 待办（可选） | 指路存根：条目单点登记 06-待办清单.md，本节不再逐条登记 |
| 版本历史 | 表格 |
命名：中文、见名知意（如"游戏概念""棋盘生成"）；禁止 a1_/b1_ 编号前缀；不留纯空目录。正文中指代子系统一律用中文规范名；英文代号（供代码标识符与工具链）对照表见 design/gdd/02-系统清单.md，旧代号（a1–d6）仅限解读归档时使用，不得写进现行文档。
7–9. 概念封装 / 引用纪律 / 归档与事实源——已独立成文 design/dev/concept-conventions.md
10. 会话记录纪律
active.md 定性：状态文件——它是状态记录，不是工作日志。 根目录 active.md 是会话状态的唯一状态源，每一行都必须在当下为真；它不是历史档案——历史变更一律以 git 提交史为准（删除条目不销毁任何记录：active.md 自身的每个历史提交版本都完整可查）。只许写入三类内容：①当前状态快照（≤10 条滚动窗口）；②未决面（进行中批次/待人闸/待裁点的指针）；③当前迭代的滚动工作条目。禁止写入：已完结批次的历史叙述（归 git 与各权威文档）、待办裁决事项（归 06-待办清单.md）、跨会话教训（归记忆库）；并行会话禁止将本文件整体复原/回退。退役规则：用户确认任务完成时，清除当前会话写过的状态条目——状态清除即任务完成的证明，不留执行中痕迹；条目完结判据=批次已入库+结论已进快照+未决面无条目指向它；迭代收口兜底删除已完结条目，状态记录超过 30 条必须清。
active.md 每条进度用完整的白话句子写清结论本身；条目写多长以读者能看懂为准，不设行数上限（能看懂比字数少更重要——行数压缩曾迫使条目使用只有作者自己懂的自造缩略语）。仍然禁止的只有两件：把定稿摘要、义务清单整段搬进条目（详情归各权威文档，状态记录只记结论）；以及自造黑话——第 4 节用语纪律对状态记录同等生效。状态记录条目记裁决结论本身，不记中间文档文件指针（见第 11 节）。
11. 文档生命周期：吸收即死
文档分两类。活文档是唯一事实源，长期维护：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 状态记录引用不阻塞（状态记录=当前状态与最近批次的记录；历史变更一律以 git 提交史为准） |
| 状态记录记结论 | 状态记录条目记裁决结论本身，不记中间文档文件指针；中间文档删除后不留死链指针 |
| sim-data 白名单 | sim-data/ 只保留 README、日志、分析工具 .py、现行 MC 对拍锚（显式清单）、设计文档 md；可再生原始数据（runsum/raw jsonl/逐局 CSV/report txt/样例输出）不入库 |
| 出口清理项 | 每迭代出口检查单必含清理项：本迭代中间产物逐份核对（结论已吸收、未决已迁移）后删除 |
| 暂存地非档案库 | design/research/ 与 design/qa/ 是中间文档的暂存地，不是永久档案库；入此两处的文件默认按本节规则到期即死 |
| 迭代实现报告 | 实现批收口的迭代级报告（design/qa/iter<N>-实现报告-<日期>.md，一个迭代一份：各卡状态/代拍板追认单/GDD 反哺点节），属中间文档：GDD 反哺点未决先迁 06-待办清单.md，用户裁决落文吸收后按「证据只留最新」退役；替代原每卡出口报告 |
| 证据只留最新 | 测试证据（迭代实现报告/读数/截图/对比图）只保留最新一次迭代或最新一轮同类审计的版本——旧证据无参考作用，测试按状态不按历史；新证据落位后同批删除上一份；等人工检查的清单不受此限，过人闸后按本行退役 |
删除方式：按 design/dev/concept-conventions.md 第 2 节删除概念 SOP 的口径执行——先查引用面（grep 文件名于上表阻塞域），改写或删除指路句，再删文件，收尾跑死链检查全绿。