game-group/gplan-2
2
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

merge master（改动四类与两层模型）＋手工合四文件：格式换代与新状态词并轨

Browse Source
This commit is contained in:
DKChan committed 2026-10-25 07:44:25 +08:00
2 parents 4e8ff1f0fa 14cea94623
commit c550654896
10 files changed
+440 -933
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

design/engineering/doc-conventions.md
+241 -239
View File
@@ -1,239 +1,241 @@
# 文档写作规范（写文档前必读）
> **地位**：本文是文档写作的规范权威，与 `design/engineering/code-conventions.md`（代码规范）对等；AGENTS.md 只留导航指针，细则以本文为准。
> **适用范围**：`design/` 下一切现行文档与根目录 `roadmap.md`；概念建模与跨文档引用见 `design/engineering/concept-conventions.md`。
## 0. 总纲
默认读者没读过项目历史——可能是半年后的你自己。先让人读懂，再谈结构整齐。
## 1. 可读性第一（最高纪律）
**读者测试是每个小节的验收标准**：只读这一节，回答三个问题——这节管的是谁/什么？在什么情况下？会发生什么？答不出来，就重写这一节，而不是给看不懂的地方补注释。
`tools/gdd_lint.py` 现为现行文档机检三闸之一（gdd_lint / doc_link_audit / doc_term_audit，分级周期口径见 AGENTS.md）；可读性是第一内容质量门，lint 是格式机检面，两者并行。
## 2. 白话写作规则
写文档像向朋友当面解释你的游戏：
1. **完整句子优先**：一段只说一件事，长句拆短句。
2. **禁止碎片笔记体**：不写压缩碎片，不把 `A→B→C` 箭头链当叙述（流程交给字符画，见第 3 节），不用只有作者自己懂的缩略语。
3. **每节人话开头**：每小节第一段先用白话说清"这是什么、为什么需要它"；只读各节第一段就能看懂全文故事线。
4. **术语首现即解释**：专业术语或项目概念首次出现用一句话解释；玩家可见专属名词（如"显影尘"）同样要说清。
5. **叙述优先于引用**：AC-x、F-x 等编号引用不进正文叙述，只出现在验收标准与附录。
6. **反面基准**：数据库条目、会议纪要、只有评审工具能"读懂"的表格堆。
## 3. 表达分工：散文、表格、字符画、公式
| 内容 | 载体 | 纪律 |
|---|---|---|
| 规则的来龙去脉、行为逻辑 | 散文段 | 每段 ≤240 字，一段一件事 |
| 枚举、数值、边界、依赖 | 表格 | 表格只放可列举的事实；禁把需要解释的内容塞进单元格让读者自己拼 |
| 流程、状态流转 | 字符画（代码块） | 禁用散文逐步描述流程 |
| 公式 | 结论先行 | 先一行加粗结论，再放公式代码块、变量表与验算表 |
| 体验锚点 | 关键词表 | 支柱/关键词/机制承诺 三列表，禁长篇情绪描述 |
节点内顺序：先人话，再表格枚举，再字符流程图，最后公式举证。**规则两段式**：先写"人话阶段"（作用于哪个系统、什么情况下、谁触发、触发后发生什么），再写"举证阶段"（逐效果给出计算方法；纯流程规则明写"无计算"）。规则名禁止纯名词短语（反面例："获取路由"）。
## 4. 用语纪律（见名知意 · 所见即所得 · 禁自造黑话）
**正面总则**：见名知意——每个名字（概念名、术语、文档与目录名）本身就说清所指，起不出这样的名字多半是概念还没想清；所见即所得——字面意思就是规则的完整意思，有隐含前提就写进句子。两句管语义透明，不与第 8 节指路存根冲突。
文档、评审输出、日志与一切沟通中**禁止自造黑话**——比喻性生造词、只有作者自己懂的缩略语：
- 只能使用：（a）人人可懂的直白语言，或（b）游戏行业通用术语（如 flood fill、战争迷雾、连锁展开、结算、增益/减伤）。
- 指代新概念用直白描述性短语（正例："实测可推理率"）；确需命名时：首现处附一句白话定义，并登记进 `design/gdd/术语表.md`。
- 唯一例外：玩家在游戏里也会看到的专属名词（道具名、界面用语）。文档内部的机制概念不得造词。
**自造词的三种固定形态（全部禁止）**：
| 形态 | 反例 | 正确写法 |
|---|---|---|
| 给工作包起代号 | "样张批""八型批" | 叙述名 = 日期 + 做什么 |
| 给机制、检查、基线、区域造名词 | "形象锚""判读口径""变异纹带" | 用行业通用词；长期复用的概念走登记通道（正常名字+白话定义+登记进 术语表） |
| 给流程步骤造动词 | "收口""落籍""在飞""随批""对拍""销账""正主""台账" | 用日常动词：完成 / 合并进 master / 执行中 / 顺带 / 与基线数据逐项比对 / 注销 / 定义所属的那份文档 / 状态记录 |
**通行检验标准**：读者是业内人但没读过项目历史——需要作者解释才懂的词不合格，必须展开成完整白话句（换新名词不算改，展开才算改）。**写后自查**：凡自己都要停顿才能想起意思的词，一律展开。
**词表冻结**：doc_term_audit 与术语表「用语规范」节的禁用词表不再扩充；扩表唯一入口＝用户实读反馈并经用户裁决，由非迭代批写入，禁 agent 自行增词。
## 5. 结构纪律
| 规则 | 内容 |
|---|---|
| 树形文档体系 | 全部设计文档构成一棵树；文档增删必须同步根索引 `design/gdd/02-系统清单.md` |
| 架构事实唯一源 | `design/engineering/architecture/architecture.md` 是架构事实的唯一权威（分层/模块归属/数据流/API 边界/测试与质量域）；禁建第二份架构文档；历史决策记录只进 git commit log |
| 一页纸节点 | 一节、一条规则 ≤一页纸（约 ≤80 行）；装不下就拆节 |
| 一系统一文档 | 不建 analysis 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文 |
| 正文只写现行规则 | 禁删除线、"（作废）"、"（日期+拍板）"式注记；审计信息入对应文档附录 |
| 正文单点维护 | 一条规则句只写在定义它的那份文档（owner 文档）；其他文档要引用时写指针或语义概括，禁复制色值、尺寸、路径等可核对的具体值——上一句管不住数值之外的双写，本句补上。豁免面 = 执行侧文件必须带字面值才能工作时（生图提示词里的十六进制色、脚本参数），转写不算双写，但该文件头部必须写明"冲突时以 owner 文档为准" |
| 禁写变更记录 | 文档与代码文件内一律禁设「版本历史／修订记录／变更记录／修改记录／更新记录／更新日志」节或表格，禁逐版本叙述「改了哪些条款」；沿革与改动明细只进 git commit log。版本号可作为文档现行身份标记出现在文首状态行与正文引用中，但不得再挂变更表 || 后置 ≠ 删除 | P1/P2 后置内容逐条列出；复活后置项 = 修订文档，禁静默加回 |
**数值纪律**：正文定规则、取值域、单位；平衡值进 `data/tables/`，provisional 必须标注；已锁数值事实源 = `game/data/tables/*.tres`（现行值）与 owner 文档正文（规则、取值域、单位）。
**登记处唯一性**：`design/registry/`（`entities.yaml`／`architecture.yaml`）已注销删除，禁再建第二处事实登记——术语进 术语表、数值进 `.tres`、架构进 架构文档、影响面靠全仓搜索概念规范名得出。强制收口条款：
1. **双写失同步禁止**——任何数值变更必须同时同步引用该数值的 GDD 表格正文、`data/tables/` 行值与 schema 校验域、相关待办清单现状——三类之一未更新即视为变更未完成。
2. **调参表锁数后删现行值列**——仅留 schema 模板与取值域，指针指向 `.tres` 对应行键。
3. **覆盖范围** = 奖励/状态/敌人/技能/充能/护甲等级/区间掷点/难度曲线/D_ref 等所有数值字段。
4. **维护通道** = 「设计批 → 同步批」两段式；数值表改完不等于修订完成。
5. **压缩/换装批** = 「`.tres` 落批 + 切片 smoke 跑通 + GDD 表格改为只留取值域与 `.tres` 指针 + 待办清单刷新」四步全收才记版本号。
## 6. 文档类型与骨架
**顶层文档**：
| 文档 | 管什么 |
|---|---|
| `00-游戏概念.md` | 一句话概念、目标受众、世界观命名、术语层级 |
| `01-核心循环.md` | 玩家醒来→做什么→得到什么→又想做什么，一条线讲清 |
| `02-系统清单.md` | 根索引：循环 × 子系统总表 + 文档树导航 |
| `03-内容规模.md` | 几个关卡、几种敌人、几种道具——做多少砍多少 |
| `04-美术音频方向.md` | 参考图、参考游戏、风格关键词 |
| `05-不做清单.md` | 明确写：这些我不要 |
| `待办清单.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/engineering/concept-conventions.md`
## 10. 会话状态——仓库根不设状态文件
**根目录 `active.md` 连同「会话状态唯一状态源」这条规矩一起废除。** 判据来自对 869 个历史会话的读写统计：整文件被读 448 次、平均每次 14 KB 进上下文，但会话里关于它的思考九成花在「追加条目前先查尾部编号防撞号」与「并行会话同时改它导致的合并冲突与丢弃」上，明确写「从它所载内容得知某事实」的只有 20 个会话；文件 45 KB 里约 95% 是别处已有权威源的重复说法、已失真陈述或已完结批次的历史叙述。体量闸只能测条目数与死链，测不出语义失真：10-15 清到 8.6 KB／3 条，10-17 已回到 40 KB，用户为「只写不删」连续三次发火，规矩照样失效。
废除后的分工：**现在做什么**看根目录 `roadmap.md` 顶部「当前位」节；**待办与待裁**看 [待办清单](../../待办清单.md)（唯一登记处）；**批次过程与结论**看 git 提交信息与 `reports/`；**跨会话教训**看记忆库。禁止在仓库根新建同类状态文件，也禁止在任何文档里另设「当前状态快照」节——两处记同一件事必然漂移，这正是本次统计查出七条失实陈述的成因。
## 11. 文档生命周期：吸收即死
**活文档**=唯一事实源长期维护：GDD 树、art-bible 等定稿规范、术语表、架构文档（`design/engineering/architecture/architecture.md`）、退役内容留底（`design/content-archive/`，2026-10-20 用户裁新立：只装「内容已退役、留底供日后重新过准入」的档案，落内文件须在文档头写明所属线）、本规范、待办清单、roadmap。**中间文档**=脚手架，寿命=迭代寿命：批需求卡片（死期=所属迭代实现批合回 master 那一刻；roadmap 对应行的卡片/报告列改填「已退役（git 历史可考）」保留字，凭据语义从文件指针换代为状态标记）、机检/验收过程报告、调研/审计/提案/需求澄清过程稿、模拟读数、迭代计划书、目检清单。为什么：了解游戏看 GDD，了解变更看 git；增量中间文档让版本管理失去意义，原始数据 dump 是化石不是证据。
| 规则 | 内容 |
|---|---|
| 吸收即死 | 中间文档结论写进权威文档（GDD 对应节/art-bible/术语表）那一刻，文件即删 |
| 未决先迁再死 | 未决内容先迁现行事实源（待办清单/roadmap 卡/GDD 对应节），然后文档即死 |
| 永不入库 | 迭代出口后中间产物一律删除且不许提交；迭代进行中可暂存工作区，出口批一并清 |
| 引用面口径 | 活文档对中间文档的指路阻塞删除：先改写指路句为结论内联或 git 提交号再删 |
| 删除不留死链 | 中间文档删除后，任何现行文档禁止再留指向它的文件路径；改指结论或提交号 |
| sim-data 白名单 | 只留 README、日志、分析工具 .py、现行 MC 对拍锚、设计文档 md；可再生原始数据不入库 |
| 出口清理项 | 每迭代出口检查单必含：本迭代中间产物逐份核对（结论已吸收、未决已迁移）后删除 |
| 暂存地非档案库 | 中间文档唯一暂存地＝`reports/`（需求卡片＋迭代产出物＋调研/审计/提案/需求澄清过程稿）。**`design/research/` 已退役（2026-10-21 用户裁）**：`design/` 全目录只放持久化设计文档与规范，过程件一律不进，禁止再在 `design/` 下另设过程件目录（熵增闸退役路径清单已收 `design/research`，目录再现即判红）。禁止文件在自身页眉自称「常驻／已追认／不受吸收即死约束」之类的豁免——豁免只写进规约正文，本条就是不给；确实要长期留用的退役内容走 `design/content-archive/`（活文档身份，落内文件头部写明所属线）。跨会话交接文件（会话提示/handoff/任务书/试运行报告）禁止入库——给另一个会话的开工输入在会话里交付即可（与仓库根禁设会话状态文件同族判据，见第 10 节）。根目录 `playnote.md`=用户本人试玩随手记，只由用户本人增删，不属于任何文档族、不受吸收即死管辖，不进 §11 任何一格。图像载体不进 `design/` 各子目录、也不进 `reports/`——图一律留 `artwork/`（2026-09-27 用户裁「审图只看一处」），结论写进待办清单或需求卡片后图像即弃；`.html`／`.json` 这类报告渲染件允许作为报告的一种（2026-10-21 用户裁）；只有需要机器逐像素比对的基线图长期入库，落 `game/tests/golden/` |
| 落档必写接收方 | 新报告落档时头部必须写明接收方——`待办清单.md` 第几条，或哪张需求卡片。写不出接收方的不落文件，内容在会话里交付即可 |
| 迭代实现报告 | 实现批收口的迭代级报告（各卡状态/代拍板追认单/GDD 反哺点清单），属中间文档，**落 `reports/` 不落 `design/`**（实现批禁写 `design/`，`reports/` 是其唯一可写目录）：反哺点裁决落文吸收后按「证据只留最新」退役 |
| 证据只留最新 | 测试证据只保留最新一次迭代或最新一轮同类审计版本；新证据落位后同批删上一份；待人清单过人闸后同规退役 |
**删除方式**：按 `design/engineering/concept-conventions.md` 第 2 节删除概念 SOP 口径——先查引用面（grep 文件名于阻塞域），改写或删除指路句，再删文件，收尾跑死链检查全绿。执行入口=项目技能 batch-closure（批后收尾与中间文档退役）。
## 12. 流程文档格式
五段流水线（登记 → 文档设计／美术设计 → 写卡 → 迭代编排 → 实现，流程纪律见 `design/engineering/process-conventions.md` §2）靠流程文档运转：待办清单登记要做的事，roadmap 记录迭代编排结果，artwork 目录承载美术在途素材。本节是这些流程文档的格式与状态机权威，也是流水线闸（`tools/pipeline_gate.py`，自动检查待办清单与 roadmap 两文件格式及互相引用的机检闸）的判据依据。
### 12.1 待办清单条目格式与状态机
待办清单是流水线的唯一登记处：要做的事先登记一条，随流水线段推进改状态，做完整条删除。一条条目分两层——**标题=登记元数据**（何时登记、从哪来、紧急度，登记后不再变），**正文=四个属性**（随进程演进）。四个属性各管一件事：`实况` 管凭据，`缺口` 管这条的**输入**（还缺哪一次设计），`改动面` 管这条的**产出**（要动哪些面），`状态` 管这条走到流水线哪一段。
标题格式（尖括号处按实际填写，方括号内为可选段）：
```
#### <条目名>（<YYYY-MM-DD>登记，来源=<playnote／会话提及／审计发现／批次移交>[，优先级＝<P0／P1／P2>]）
```
`优先级` 是紧急度标记，可选，规则三条：不写＝默认档 P2；只有用户明示才写，会话不得自行给任何条目定档；P0 最高、P2 最低。它只服务阅读时的排序，不参与开工门、编排四查与状态机。`P0/P1/P2` 这组记号在本仓库只指待办紧急度，新文档禁另立别义。
正文四属性模板：
```
**实况**＝关联文档清单，一行一件：它是什么（设计定稿／需求卡片／相关文档）＋文件路径＋版本号与日期（闭合类文件必带）；必要时在清单前配一句实际情况说明。机制解释与论证过程不写在这里，归权威文档。路径用普通文本或行内代码书写，机器可搜索。工程形态条目必须在实况里指认证据（bug 证据或工程债条目）。
**缺口**：还差哪一次设计讨论／哪份设计产物才能写卡。尚有未闭合设计段时此属性必须存在；设计线全部闭合后删除。
**改动面**＝文档／美术素材／游戏代码／工具代码 四档取多，多档用＋连接、禁重复、按上表次序排列。登记时即写，随进程若产出面变宽要补档。
**状态**：按状态机取词。
```
`改动面` 四档的划线判据（按被改对象的路径归属，与闸的分域同口径）：
| 档 | 覆盖范围 |
|---|---|
| 文档 | 本仓库的 .md 权威文档：`design/` 设计文档与 `design/engineering/` 规约、`design/art/art-bible`、根流程件（roadmap／待办清单／体验验证清单） |
| 美术素材 | 本条目要出的图：`artwork/` 在途样张与 `game/assets/art/` 终稿 |
| 游戏代码 | `game/` 全部：脚本与场景、`data/tables/*.tres` 数值表、`tests/`、`probe/`、`sim/`——表值直接改变游戏运行结果，归本档 |
| 工具代码 | `tools/` 与仓库根 python 脚本（含各验证闸件）＋流水线技能件 `.zcode/skills/`、`.qoder/skills/`（技能改的是流水线行为，与闸件同类） |
只写本条目自己交付的产出面，不预写下游实现批要动的面。`reports/` 下的需求卡片与批次产出物属过程件（第 11 节管辖），不计入 `文档` 档。四档与 AGENTS.md 硬红线的「改动四类」对应关系：`游戏代码`＝需求改动（走写卡与编排段）、`工具代码`／`文档`／`美术素材` 三档各自对应工程改动／文档设计改动／美术素材改动三类直改通道；一条条目可以同时含多档。
状态段用词自带所属设计线——`待文档设计`／`文档设计中`／`文档设计已闭合` 是文档线，`待美术设计`／`美术设计中`／`美术设计已闭合` 是美术线，不需要在标题另行声明走哪条线。状态一律取下例用词。状态行按**状态段累积制**书写：条目每推进一段，就把新状态段接在状态行末尾，段与段用＋号连接，书写顺序=推进顺序；跨线的段一律保留、禁删（同一设计线内只留最新一段），下游段一旦写下不回收——状态履历供编排四查与开工核验比对。每段各自按状态词白名单校验，＋号只作状态段连接符。
```
各设计线推进序列（同条目两条线并列推进时，两段各写各的）：
文档线：待文档设计 → 文档设计中 → 文档设计已闭合
美术线：待美术设计 → 美术设计中 → 美术设计已闭合
下游共用序列：待写卡 → 已写卡 → 已编迭代 N → 完成即整条删除
累积示例：文档设计已闭合＋待美术设计＋已写卡
```
设计线段与下游段同条并存是合法形态：状态行里出现过的**每条设计线各自留最新一段**，跨线依赖不阻塞本条推进（文档线闭合后写卡、美术线仍未出图，就把 `文档设计已闭合` 与 `待美术设计` 并写）。「写卡前本条要落的那条设计线必须已闭合」是实现侧的执行义务，由编排段查卡片凭据核对，不靠标题声明——闸只查同线并现多段。
状态行只写状态词：去掉特批标记与「（备选）」后缀后，残留任何括号即违规。闭合类状态词（文档设计已闭合／美术设计已闭合／已写卡／已写入）的证据——设计定稿路径+版本、art-bible 条款版本、需求卡片路径、落点文档+版本——一律写在实况的关联文档清单里，由流水线闸到正文核对；已编迭代 N 段的交叉核依据＝实况清单里的需求卡片路径。
两种条目形态与一种后缀：
| 形态 | 规则 |
|---|---|
| 工程形态 | 缺陷修复／工程债／测试基建／重构四类工程条目：状态首段直接落「待写卡」、整行不含设计段，凭实况里指认的证据跳过设计线 |
| 反哺点专条 | 状态取 待裁决 → 已写入 → 删除，不走设计线也不走下游序列 |
| 备选库条目 | 暂不排期、留在备选库的条目：状态词后缀「（备选）」 |
特批标记见 12.4。
### 12.2 roadmap 迭代行格式
roadmap 由顶部里程碑表＋迭代总表组成，迭代总表一行一个迭代，回答一个问题：这个迭代编入了哪些卡、做到哪一步。迭代行六列：
```
| 迭代号 | 状态 | 需求卡片 | 编入时间 | 预计周期 | 实现报告 |
```
| 列 | 规则 |
|---|---|
| 迭代号 | 写「迭代 N」形态（N 为阿拉伯数字）；这是流水线闸交叉核匹配的依据 |
| 状态 | 待开工 ／ 进行中 ／ 已完成（YYYY-MM-DD）／ 已终止（YYYY-MM-DD） |
| 需求卡片 | 只写文件路径；一格内一行一卡，格内排列顺序=执行顺序；已退役填保留字「已退役（git 历史可考）」；历史迭代不可考填「—」（早期无卡片制的迭代） |
| 编入时间 | YYYY-MM-DD（该迭代最近一次编入卡片的日期）；历史迭代不可考填「—」 |
| 预计周期 | 所选卡估时区间**中值**求和，单位工作日，写精确值不取整，形态「≈N 个工作日」（1 周＝5 个工作日）；5–10 为常规区间；超过 10 须随带日期的用户特批标记（格式见 12.4），流水线闸见标记放行、无标记判红；低于 5 或超过 20 均判红（硬下限/硬上限，2026-10-21 用户裁定：特批标记也不放行）；历史迭代不可考填「—」 |
| 实现报告 | `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 跳过××〕`。只有用户明示才能给，用于待办清单条目状态与 roadmap 格（见 12.1、12.2）。
执行技能一律两段式：
1. 对象已有内容 → 直接写入标记。
2. 对象没有任何内容 → 必须回呈实况，经用户再次确认后才写标记。
标记必须带日期，无日期=非法。流水线闸见合法特批标记放行对应判据。
# 文档写作规范（写文档前必读）␍
␍
> **地位**：本文是文档写作的规范权威，与 `design/engineering/code-conventions.md`（代码规范）对等；AGENTS.md 只留导航指针，细则以本文为准。␍
> **适用范围**：`design/` 下一切现行文档与根目录 `roadmap.md`；概念建模与跨文档引用见 `design/engineering/concept-conventions.md`。␍
␍
## 0. 总纲␍
␍
默认读者没读过项目历史——可能是半年后的你自己。先让人读懂，再谈结构整齐。␍
␍
## 1. 可读性第一（最高纪律）␍
␍
**读者测试是每个小节的验收标准**：只读这一节，回答三个问题——这节管的是谁/什么？在什么情况下？会发生什么？答不出来，就重写这一节，而不是给看不懂的地方补注释。␍
␍
`tools/gdd_lint.py` 现为现行文档机检三闸之一（gdd_lint / doc_link_audit / doc_term_audit，分级周期口径见 AGENTS.md）；可读性是第一内容质量门，lint 是格式机检面，两者并行。␍
␍
## 2. 白话写作规则␍
␍
写文档像向朋友当面解释你的游戏：␍
␍
1. **完整句子优先**：一段只说一件事，长句拆短句。␍
2. **禁止碎片笔记体**：不写压缩碎片，不把 `A→B→C` 箭头链当叙述（流程交给字符画，见第 3 节），不用只有作者自己懂的缩略语。␍
3. **每节人话开头**：每小节第一段先用白话说清"这是什么、为什么需要它"；只读各节第一段就能看懂全文故事线。␍
4. **术语首现即解释**：专业术语或项目概念首次出现用一句话解释；玩家可见专属名词（如"显影尘"）同样要说清。␍
5. **叙述优先于引用**：AC-x、F-x 等编号引用不进正文叙述，只出现在验收标准与附录。␍
6. **反面基准**：数据库条目、会议纪要、只有评审工具能"读懂"的表格堆。␍
␍
## 3. 表达分工：散文、表格、字符画、公式␍
␍
| 内容 | 载体 | 纪律 |␍
|---|---|---|␍
| 规则的来龙去脉、行为逻辑 | 散文段 | 每段 ≤240 字，一段一件事 |␍
| 枚举、数值、边界、依赖 | 表格 | 表格只放可列举的事实；禁把需要解释的内容塞进单元格让读者自己拼 |␍
| 流程、状态流转 | 字符画（代码块） | 禁用散文逐步描述流程 |␍
| 公式 | 结论先行 | 先一行加粗结论，再放公式代码块、变量表与验算表 |␍
| 体验锚点 | 关键词表 | 支柱/关键词/机制承诺 三列表，禁长篇情绪描述 |␍
␍
节点内顺序：先人话，再表格枚举，再字符流程图，最后公式举证。**规则两段式**：先写"人话阶段"（作用于哪个系统、什么情况下、谁触发、触发后发生什么），再写"举证阶段"（逐效果给出计算方法；纯流程规则明写"无计算"）。规则名禁止纯名词短语（反面例："获取路由"）。␍
␍
## 4. 用语纪律（见名知意 · 所见即所得 · 禁自造黑话）␍
␍
**正面总则**：见名知意——每个名字（概念名、术语、文档与目录名）本身就说清所指，起不出这样的名字多半是概念还没想清；所见即所得——字面意思就是规则的完整意思，有隐含前提就写进句子。两句管语义透明，不与第 8 节指路存根冲突。␍
␍
文档、评审输出、日志与一切沟通中**禁止自造黑话**——比喻性生造词、只有作者自己懂的缩略语：␍
␍
- 只能使用：（a）人人可懂的直白语言，或（b）游戏行业通用术语（如 flood fill、战争迷雾、连锁展开、结算、增益/减伤）。␍
- 指代新概念用直白描述性短语（正例："实测可推理率"）；确需命名时：首现处附一句白话定义，并登记进 `design/gdd/术语表.md`。␍
- 唯一例外：玩家在游戏里也会看到的专属名词（道具名、界面用语）。文档内部的机制概念不得造词。␍
␍
**自造词的三种固定形态（全部禁止）**：␍
␍
| 形态 | 反例 | 正确写法 |␍
|---|---|---|␍
| 给工作包起代号 | "样张批""八型批" | 叙述名 = 日期 + 做什么 |␍
| 给机制、检查、基线、区域造名词 | "形象锚""判读口径""变异纹带" | 用行业通用词；长期复用的概念走登记通道（正常名字+白话定义+登记进 术语表） |␍
| 给流程步骤造动词 | "收口""落籍""在飞""随批""对拍""销账""正主""台账" | 用日常动词：完成 / 合并进 master / 执行中 / 顺带 / 与基线数据逐项比对 / 注销 / 定义所属的那份文档 / 状态记录 |␍
␍
**通行检验标准**：读者是业内人但没读过项目历史——需要作者解释才懂的词不合格，必须展开成完整白话句（换新名词不算改，展开才算改）。**写后自查**：凡自己都要停顿才能想起意思的词，一律展开。␍
␍
**词表冻结**：doc_term_audit 与术语表「用语规范」节的禁用词表不再扩充；扩表唯一入口＝用户实读反馈并经用户裁决，由工程/文档设计改动批写入，禁 agent 自行增词。␍
␍
## 5. 结构纪律␍
␍
| 规则 | 内容 |␍
|---|---|␍
| 树形文档体系 | 全部设计文档构成一棵树；文档增删必须同步根索引 `design/gdd/02-系统清单.md` |␍
| 架构事实唯一源 | `design/engineering/architecture/architecture.md` 是架构事实的唯一权威（分层/模块归属/数据流/API 边界/测试与质量域）；禁建第二份架构文档；历史决策记录只进 git commit log |␍
| 一页纸节点 | 一节、一条规则 ≤一页纸（约 ≤80 行）；装不下就拆节 |␍
| 一系统一文档 | 不建 analysis 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文 |␍
| 正文只写现行规则 | 禁删除线、"（作废）"、"（日期+拍板）"式注记；审计信息入对应文档附录 |␍
| 正文单点维护 | 一条规则句只写在定义它的那份文档（owner 文档）；其他文档要引用时写指针或语义概括，禁复制色值、尺寸、路径等可核对的具体值——上一句管不住数值之外的双写，本句补上。豁免面 = 执行侧文件必须带字面值才能工作时（生图提示词里的十六进制色、脚本参数），转写不算双写，但该文件头部必须写明"冲突时以 owner 文档为准" |␍
| 禁写变更记录 | 文档与代码文件内一律禁设「版本历史／修订记录／变更记录／修改记录／更新记录／更新日志」节或表格，禁逐版本叙述「改了哪些条款」；沿革与改动明细只进 git commit log。版本号可作为文档现行身份标记出现在文首状态行与正文引用中，但不得再挂变更表 || 后置 ≠ 删除 | P1/P2 后置内容逐条列出；复活后置项 = 修订文档，禁静默加回 |␍
␍
**数值纪律**：正文定规则、取值域、单位；平衡值进 `data/tables/`，provisional 必须标注；已锁数值事实源 = `game/data/tables/*.tres`（现行值）与 owner 文档正文（规则、取值域、单位）。␍
␍
**登记处唯一性**：`design/registry/`（`entities.yaml`／`architecture.yaml`）已注销删除，禁再建第二处事实登记——术语进 术语表、数值进 `.tres`、架构进 架构文档、影响面靠全仓搜索概念规范名得出。强制收口条款：␍
␍
1. **双写失同步禁止**——任何数值变更必须同时同步引用该数值的 GDD 表格正文、`data/tables/` 行值与 schema 校验域、相关待办清单现状——三类之一未更新即视为变更未完成。␍
2. **调参表锁数后删现行值列**——仅留 schema 模板与取值域，指针指向 `.tres` 对应行键。␍
3. **覆盖范围** = 奖励/状态/敌人/技能/充能/护甲等级/区间掷点/难度曲线/D_ref 等所有数值字段。␍
4. **维护通道** = 「设计批 → 同步批」两段式；数值表改完不等于修订完成。␍
5. **压缩/换装批** = 「`.tres` 落批 + 切片 smoke 跑通 + GDD 表格改为只留取值域与 `.tres` 指针 + 待办清单刷新」四步全收才记版本号。␍
␍
## 6. 文档类型与骨架␍
␍
**顶层文档**：␍
␍
| 文档 | 管什么 |␍
|---|---|␍
| `00-游戏概念.md` | 一句话概念、目标受众、世界观命名、术语层级 |␍
| `01-核心循环.md` | 玩家醒来→做什么→得到什么→又想做什么，一条线讲清 |␍
| `02-系统清单.md` | 根索引：循环 × 子系统总表 + 文档树导航 |␍
| `03-内容规模.md` | 几个关卡、几种敌人、几种道具——做多少砍多少 |␍
| `04-美术音频方向.md` | 参考图、参考游戏、风格关键词 |␍
| `05-不做清单.md` | 明确写：这些我不要 |␍
| `待办清单.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/engineering/concept-conventions.md`␍
␍
## 10. 会话状态——仓库根不设状态文件␍
␍
**根目录 `active.md` 连同「会话状态唯一状态源」这条规矩一起废除。** 判据来自对 869 个历史会话的读写统计：整文件被读 448 次、平均每次 14 KB 进上下文，但会话里关于它的思考九成花在「追加条目前先查尾部编号防撞号」与「并行会话同时改它导致的合并冲突与丢弃」上，明确写「从它所载内容得知某事实」的只有 20 个会话；文件 45 KB 里约 95% 是别处已有权威源的重复说法、已失真陈述或已完结批次的历史叙述。体量闸只能测条目数与死链，测不出语义失真：10-15 清到 8.6 KB／3 条，10-17 已回到 40 KB，用户为「只写不删」连续三次发火，规矩照样失效。␍
␍
废除后的分工：**现在做什么**看根目录 `roadmap.md` 顶部「当前位」节；**待办与待裁**看 [待办清单](../../待办清单.md)（唯一登记处）；**批次过程与结论**看 git 提交信息与 `reports/`；**跨会话教训**看记忆库。禁止在仓库根新建同类状态文件，也禁止在任何文档里另设「当前状态快照」节——两处记同一件事必然漂移，这正是本次统计查出七条失实陈述的成因。␍
␍
## 11. 文档生命周期：吸收即死␍
␍
**活文档**=唯一事实源长期维护：GDD 树、art-bible 等定稿规范、术语表、架构文档（`design/engineering/architecture/architecture.md`）、退役内容留底（`design/content-archive/`，2026-10-20 用户裁新立：只装「内容已退役、留底供日后重新过准入」的档案，落内文件须在文档头写明所属线）、本规范、待办清单、roadmap。**中间文档**=脚手架，寿命=迭代寿命：批需求卡片（死期=所属迭代实现批合回 master 那一刻；roadmap 对应行的卡片/报告列改填「已退役（git 历史可考）」保留字，凭据语义从文件指针换代为状态标记）、机检/验收过程报告、调研/审计/提案/需求澄清过程稿、模拟读数、迭代计划书、目检清单。为什么：了解游戏看 GDD，了解变更看 git；增量中间文档让版本管理失去意义，原始数据 dump 是化石不是证据。␍
␍
| 规则 | 内容 |␍
|---|---|␍
| 吸收即死 | 中间文档结论写进权威文档（GDD 对应节/art-bible/术语表）那一刻，文件即删 |␍
| 未决先迁再死 | 未决内容先迁现行事实源（待办清单/roadmap 卡/GDD 对应节），然后文档即死 |␍
| 永不入库 | 迭代出口后中间产物一律删除且不许提交；迭代进行中可暂存工作区，出口批一并清 |␍
| 引用面口径 | 活文档对中间文档的指路阻塞删除：先改写指路句为结论内联或 git 提交号再删 |␍
| 删除不留死链 | 中间文档删除后，任何现行文档禁止再留指向它的文件路径；改指结论或提交号 |␍
| sim-data 白名单 | 只留 README、日志、分析工具 .py、现行 MC 对拍锚、设计文档 md；可再生原始数据不入库 |␍
| 出口清理项 | 每迭代出口检查单必含：本迭代中间产物逐份核对（结论已吸收、未决已迁移）后删除 |␍
| 暂存地非档案库 | 中间文档唯一暂存地＝`reports/`（需求卡片＋迭代产出物＋调研/审计/提案/需求澄清过程稿）。**`design/research/` 已退役（2026-10-21 用户裁）**：`design/` 全目录只放持久化设计文档与规范，过程件一律不进，禁止再在 `design/` 下另设过程件目录（熵增闸退役路径清单已收 `design/research`，目录再现即判红）。禁止文件在自身页眉自称「常驻／已追认／不受吸收即死约束」之类的豁免——豁免只写进规约正文，本条就是不给；确实要长期留用的退役内容走 `design/content-archive/`（活文档身份，落内文件头部写明所属线）。跨会话交接文件（会话提示/handoff/任务书/试运行报告）禁止入库——给另一个会话的开工输入在会话里交付即可（与仓库根禁设会话状态文件同族判据，见第 10 节）。根目录 `playnote.md`=用户本人试玩随手记，只由用户本人增删，不属于任何文档族、不受吸收即死管辖，不进 §11 任何一格。图像载体不进 `design/` 各子目录、也不进 `reports/`——图一律留 `artwork/`（2026-09-27 用户裁「审图只看一处」），结论写进待办清单或需求卡片后图像即弃；`.html`／`.json` 这类报告渲染件允许作为报告的一种（2026-10-21 用户裁）；只有需要机器逐像素比对的基线图长期入库，落 `game/tests/golden/` |␍
| 落档必写接收方 | 新报告落档时头部必须写明接收方——`待办清单.md` 第几条，或哪张需求卡片。写不出接收方的不落文件，内容在会话里交付即可 |␍
| 迭代实现报告 | 实现批收口的迭代级报告（各卡状态/代拍板追认单/GDD 反哺点清单），属中间文档，**落 `reports/` 不落 `design/`**（实现批禁写 `design/`，`reports/` 是其唯一可写目录）：反哺点裁决落文吸收后按「证据只留最新」退役 |␍
| 证据只留最新 | 测试证据只保留最新一次迭代或最新一轮同类审计版本；新证据落位后同批删上一份；待人清单过人闸后同规退役 |␍
␍
**删除方式**：按 `design/engineering/concept-conventions.md` 第 2 节删除概念 SOP 口径——先查引用面（grep 文件名于阻塞域），改写或删除指路句，再删文件，收尾跑死链检查全绿。执行入口=项目技能 batch-closure（批后收尾与中间文档退役）。␍
␍
## 12. 流程文档格式␍
␍
五段流水线（登记 → 文档设计／美术设计 → 写卡 → 迭代编排 → 实现，流程纪律见 `design/engineering/process-conventions.md` §2）靠流程文档运转：待办清单登记要做的事，roadmap 记录迭代编排结果，artwork 目录承载美术在途素材。本节是这些流程文档的格式与状态机权威，也是流水线闸（`tools/pipeline_gate.py`，自动检查待办清单与 roadmap 两文件格式及互相引用的机检闸）的判据依据。␍
␍
### 12.1 待办清单条目格式与状态机␍
␍
待办清单是流水线的唯一登记处：要做的事先登记一条，随流水线段推进改状态，做完整条删除。一条条目分两层——**标题=登记元数据**（何时登记、从哪来、紧急度，登记后不再变），**正文=四个属性**（随进程演进）。四个属性各管一件事：`实况` 管凭据，`缺口` 管这条的**输入**（还缺哪一次设计），`改动面` 管这条的**产出**（要动哪些面），`状态` 管这条走到流水线哪一段。␍
␍
标题格式（尖括号处按实际填写，方括号内为可选段）：␍
␍
```␍
#### <条目名>（<YYYY-MM-DD>登记，来源=<playnote／会话提及／审计发现／批次移交>[，优先级＝<P0／P1／P2>]）␍
```␍
␍
`优先级` 是紧急度标记，可选，规则三条：不写＝默认档 P2；只有用户明示才写，会话不得自行给任何条目定档；P0 最高、P2 最低。它只服务阅读时的排序，不参与开工门、编排四查与状态机。`P0/P1/P2` 这组记号在本仓库只指待办紧急度，新文档禁另立别义。␍
␍
正文四属性模板：␍
␍
```␍
**实况**＝关联文档清单，一行一件：它是什么（设计定稿／需求卡片／相关文档）＋文件路径＋版本号与日期（闭合类文件必带）；必要时在清单前配一句实际情况说明。机制解释与论证过程不写在这里，归权威文档。路径用普通文本或行内代码书写，机器可搜索。工程形态条目必须在实况里指认证据（bug 证据或工程债条目）。␍
**缺口**：还差哪一次设计讨论／哪份设计产物才能写卡。尚有未闭合设计段时此属性必须存在；设计线全部闭合后删除。␍
**改动面**＝文档／美术素材／游戏代码／工具代码 四档取多，多档用＋连接、禁重复、按上表次序排列。登记时即写，随进程若产出面变宽要补档。␍
**状态**：按状态机取词。␍
```␍
␍
`改动面` 四档的划线判据（按被改对象的路径归属，与闸的分域同口径）：␍
␍
| 档 | 覆盖范围 |␍
|---|---|␍
| 文档 | 本仓库的 .md 权威文档：`design/` 设计文档与 `design/engineering/` 规约、`design/art/art-bible`、根流程件（roadmap／待办清单／体验验证清单） |␍
| 美术素材 | 本条目要出的图：`artwork/` 在途样张与 `game/assets/art/` 终稿 |␍
| 游戏代码 | `game/` 全部：脚本与场景、`data/tables/*.tres` 数值表、`tests/`、`probe/`、`sim/`——表值直接改变游戏运行结果，归本档 |␍
| 工具代码 | `tools/` 与仓库根 python 脚本（含各验证闸件）＋流水线技能件 `.zcode/skills/`、`.qoder/skills/`（技能改的是流水线行为，与闸件同类） |␍
␍
只写本条目自己交付的产出面，不预写下游实现批要动的面。`reports/` 下的需求卡片与批次产出物属过程件（第 11 节管辖），不计入 `文档` 档。四档与 AGENTS.md 硬红线的「改动四类」对应关系：`游戏代码`＝需求改动（走写卡与编排段）、`工具代码`／`文档`／`美术素材` 三档各自对应工程改动／文档设计改动／美术素材改动三类直改通道；一条条目可以同时含多档。␍
␍
状态段用词自带所属设计线——`待文档设计`／`文档设计中`／`文档设计已闭合` 是文档线，`待美术设计`／`美术设计中`／`美术设计已闭合` 是美术线，不需要在标题另行声明走哪条线。状态一律取下例用词。状态行按**状态段累积制**书写：条目每推进一段，就把新状态段接在状态行末尾，段与段用＋号连接，书写顺序=推进顺序；跨线的段一律保留、禁删（同一设计线内只留最新一段），下游段一旦写下不回收——状态履历供编排四查与开工核验比对。每段各自按状态词白名单校验，＋号只作状态段连接符。␍
␍
```␍
各设计线推进序列（同条目两条线并列推进时，两段各写各的）：␍
文档线：待文档设计 → 文档设计中 → 文档设计已闭合␍
美术线：待美术设计 → 美术设计中 → 美术设计已闭合␍
下游共用序列（需求改动）：待写卡 → 已写卡 → 已编迭代 N → 完成即整条删除␍
直改序列（工程改动／文档设计改动／美术素材改动）：登记 → 待执行 → 完成即整条删除（经设计讨论的可前置闭合段，如「文档设计已闭合＋待执行」）␍
累积示例：文档设计已闭合＋待美术设计＋已写卡␍
```␍
␍
设计线段与下游段同条并存是合法形态：状态行里出现过的**每条设计线各自留最新一段**，跨线依赖不阻塞本条推进（文档线闭合后写卡、美术线仍未出图，就把 `文档设计已闭合` 与 `待美术设计` 并写）。「写卡前本条要落的那条设计线必须已闭合」是实现侧的执行义务，由编排段查卡片凭据核对，不靠标题声明——闸只查同线并现多段。␍
␍
状态行只写状态词：去掉特批标记与「（备选）」后缀后，残留任何括号即违规。闭合类状态词（文档设计已闭合／美术设计已闭合／已写卡／已写入）的证据——设计定稿路径+版本、art-bible 条款版本、需求卡片路径、落点文档+版本——一律写在实况的关联文档清单里，由流水线闸到正文核对；已编迭代 N 段的交叉核依据＝实况清单里的需求卡片路径。␍
␍
三种条目形态与一种后缀：␍
␍
| 形态 | 规则 |␍
|---|---|␍
| 需求性工程条目（需求改动） | 缺陷修复／重构等改游戏行为的条目：状态首段直接落「待写卡」、整行不含设计段，凭实况里指认的证据跳过设计线；改动面必含 `游戏代码` |␍
| 直改类条目（工程改动／文档设计改动／美术素材改动） | 不动游戏行为的配套改动：登记即「待执行」，用户发令直改，不走写卡与编排段；改动面取 `工具代码`／`文档`／`美术素材` 三档 |␍
| 反哺点专条 | 状态取 待裁决 → 已写入 → 删除，不走设计线也不走下游序列 |␍
| 备选库条目 | 暂不排期、留在备选库的条目：状态词后缀「（备选）」 |␍
␍
特批标记见 12.4。␍
␍
### 12.2 roadmap 迭代行格式␍
␍
roadmap 由顶部里程碑表＋迭代总表组成，迭代总表一行一个迭代，回答一个问题：这个迭代编入了哪些卡、做到哪一步。两层口径（2026-10-25 用户立）：需求卡片＝需求单位的实施文档，任何工作量皆可写、皆可编入迭代；工作量限制只属迭代层——迭代估时总量 <5 个工作日＝冻结不可开工。迭代行六列：␍
␍
```␍
| 迭代号 | 状态 | 需求卡片 | 编入时间 | 预计周期 | 实现报告 |␍
```␍
␍
| 列 | 规则 |␍
|---|---|␍
| 迭代号 | 写「迭代 N」形态（N 为阿拉伯数字）；这是流水线闸交叉核匹配的依据 |␍
| 状态 | 待开工 ／ 冻结待凑批 ／ 进行中 ／ 已完成（YYYY-MM-DD）／ 已终止（YYYY-MM-DD） |␍
| 需求卡片 | 只写文件路径；一格内一行一卡，格内排列顺序=执行顺序；已退役填保留字「已退役（git 历史可考）」；历史迭代不可考填「—」（早期无卡片制的迭代） |␍
| 编入时间 | YYYY-MM-DD（该迭代最近一次编入卡片的日期）；历史迭代不可考填「—」 |␍
| 预计周期 | 所选卡估时区间**中值**求和，单位工作日，写精确值不取整，形态「≈N 个工作日」（1 周＝5 个工作日）；5–10 为常规区间；超过 10 须随带日期的用户特批标记（格式见 12.4），流水线闸见标记放行、无标记判红；低于 5 的迭代行状态必须为「冻结待凑批」（2026-10-25 两层模型：小卡可编入，迭代总量不足即冻结、禁止处待开工/进行中）；超过 20 判红（硬上限，特批标记也不放行）；历史迭代不可考填「—」 |␍
| 实现报告 | `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 跳过××〕`。只有用户明示才能给，用于待办清单条目状态与 roadmap 格（见 12.1、12.2）。␍
␍
执行技能一律两段式：␍
␍
1. 对象已有内容 → 直接写入标记。␍
2. 对象没有任何内容 → 必须回呈实况，经用户再次确认后才写标记。␍
␍
标记必须带日期，无日期=非法。流水线闸见合法特批标记放行对应判据。␍
design/engineering/process-conventions.md
+92 -92
View File
@@ -1,92 +1,92 @@
# 流程规范（Dungeon Sweeper）
> 约束范围：一切批次的流程纪律——分支与 worktree、五段流水线、批次工作流、测试执行细则、像素件工作纪律。
> 分工：硬性红线的一句话索引在 AGENTS.md「硬性红线」；本文承载其操作细则；批次开工前通读本文。
**开工任何批次前必须通读本文。**
## 1. 分支纪律（worktree 铁律）
主工作区（master 检出）只作合并落点，一切开发/设计改动禁止直接发生在主工作区：
1. **开工**：每批次先建独立 worktree：`git worktree add ../g-plan2-<任务名> -b <任务分支>`；所有改动与验证都在 worktree 内进行（未跟踪文件不会出现在新 worktree，需手工搬运）
2. **收尾**：批次收口顺序固定为**冻结 → 件核 → 并 master → 跑一次域闸 → 合回**——代码与断言改完即冻结，全仓件核 grep 查残留；master 已被别的批次推进时先 `git merge master` 解冲突（必须在跑闸之前，闸跑完再并＝那次闸白跑），然后按本批改动域跑**一次** `tools/run_all_gates.sh`（见 §3.9：纯文档批跑 `--docs`），全绿后在主工作区 `git merge --no-ff <任务分支>`，再 `git worktree remove`+删分支。闸后 `game/` 面不得再改一个字节（回执作废须重跑），只允许追加 `reports/`、`design/` 等非 `game/` 提交。非 loop 批次同此顺序；游戏类测试（冒烟/单测/MC/探针）对它默认零执行（两入口铁规，见 §4），用户点名或当场问才跑
3. **豁免面**：仅 `.zcode/`（钩子与配置）与 `.qoder/`（本机 harness 配置）允许主工作区直改——两份实测均不入 git（走 worktree 反而带不进去，改动只对本机生效）；其余一律走 worktree，主工作区 git commit 被钩子拦截
4. 本铁律由 PreToolUse 钩子 `.zcode/hooks/worktree-guard.sh` 强制兜底；钩子只约束 agent，用户手工改动不受限
## 2. 五段流水线
一切要做的东西按五段流水线走：**登记 → 文档设计／美术设计（两条设计线）→ 写需求卡片 → 迭代编排 → 实现**。段间不自动流转，每段转进由用户发令；每段一个技能入口（五者均装于项目 `.zcode/skills/`：doc-design／asset-ingest／req-card／iter-plan／iter），登记不立技能（条目格式由流水线闸强制）。设计工作在会话内进行、用户主导、禁无监管自跑。
| 段 | 入口技能 | 产出 | 出入口铁律 |
|---|---|---|---|
| 一·登记 | 无（闸管格式） | 待办清单条目 | 条目=标题登记元数据（日期/来源/可选优先级）＋正文四属性（实况/缺口/改动面/状态）；标题登记后不再变，正文随进程演进。格式与状态机权威=doc-conventions 第 12 节 |
| 二·文档设计／美术设计 | doc-design（文档线，兼任反哺点写入）／asset-ingest（美术录入；样张素材由用户主导产出） | GDD 文档或 art-bible／过审样张素材 | 用户提起或从待办清单取出；会话内进行、用户主导、禁无监管自跑；经用户点头确认心智一致才许写入文档；完成判据=待裁点清零，带未裁点的是讨论稿；设计线闭合凭据记入待办清单实况清单（文档线=文档路径+版本号，美术线=art-bible 条款版本）；缺哪条线写在缺口属性，闭合与否写在状态段 |
| 三·写需求卡片 | req-card | 需求卡片 | 设计线闭合后用户发令；新玩法/新系统/新内容必须有设计定稿前置，例外=工程形态四类（缺陷修复/工程债/测试基建/重构）凭证据跳过设计线；卡片必经 grilling 多轮复核、零待裁点才成立；写完在待办清单状态记「已写卡」，卡片路径记入实况清单（防遗忘） |
| 四·迭代编排 | iter-plan | roadmap 迭代行 | 编排四查：①每卡卡片文件存在 ②每卡设计闭合凭据齐（或工程形态的证据指认）③总估时三条线——所选卡估时按区间**中值**求和（单位工作日、写精确值不取整）：低于 5 个工作日不得编（硬下限，2026-10-21 用户立：不希望单迭代编太少）；5–10 个工作日为常规区间、直接编；超过 10 个工作日须经用户确认（确认前呈报整批/拆批两案等裁，禁自行拆分或塞入），确认后迭代行随带日期特批标记；超过 20 个工作日不得编（硬上限，2026-10-21 用户立：用户确认也不放行，必须拆批）④写完 roadmap 行后跑流水线闸确认绿；编入未完成迭代，新开迭代行经用户确认 |
| 五·实现 | iter | 代码与配置，可运行的游戏 | 需求卡片永不单独施工，统一由用户指定迭代号触发（=U0 开工令），按 iter 技能与本文 §3 执行；**本段是代码实现批：禁写 `design/` 与根规则文件，产出物只落 `reports/`（见 §3 第 12 条）**；设计权威文档（GDD/art-bible）批内一律不更新；完成人闸=实机目检清单+代拍板追认单登记交用户即完成批内义务 |
**实现段零裁断**：实现段的输入在编排段出口已锁死（卡片零待裁点＋设计闭合凭据齐＋编排四查过）。实现中冒出卡片没写清的分歧=上游缺陷——停该卡、待办清单状态回退＋缺口补记，退回上游；禁自答、禁内联提问求裁断；该卡停摆不阻塞同迭代其他卡。环境故障与测试红走异常分级（自救重试／记录继续／停机呈报）。代拍板白名单保留：授权发生在卡片审问阶段，实现只执行预授权；批后追认单=备案确认。
**流水线闸**：`tools/pipeline_gate.py` 机检待办清单与 roadmap 两文件的格式与互相引用；已注册进 `run_all_gates.sh` 文档域。流程文档的条目格式、迭代行格式与状态机细则见 doc-conventions 第 12 节。
## 3. 批次工作流标准清单
每个批次按以下链路执行（本清单是总索引，细则散见各规约；冲突以细则为准，发现清单过时须同批修订）：
**开工前**
1. **先检索后提问**——先查在册记忆与权威文档，禁把已裁决事项当新问题重问或重踩在册坑
2. **需求卡片全列备选案**——每个待拍板点列全部备选方案与代价交用户裁决，禁卡片内自行定夺
3. **用户发开工令才动手**——需求卡片经用户批准（U0）后方开工
**环境与基线**
4. **独立 worktree+拷导入缓存**——按 §1 建 worktree；先拷主区 `.godot/` 目录与字体 `.import` 边车再跑测试，否则全量重导入资源近似卡死。检出工作区零测试，直接开工（2026-10-22 频率规则）
5. **涉数值改动先采改前读数**——与改后同随机种子配对比较并写明逐项比对口径；无数值改动禁跑模拟
**实施**
6. **新功能必配新测试**——新增玩法/机制必须配套新测试套件进 `tests/run_all`；没有对应测试的变更不许合并；并按 test-conventions §8 挂进改动—验收对照表，没有对照表行的行为改动同样不许合并
7. **验收改动先行声明**——验收变化（基线换代/探针增改/旧断言改判）预先写进需求卡片，禁事后补
**完成**
8. **批末按域验收才合并**——在任务 worktree 内跑 `tools/run_all_gates.sh`，**按本批改动域选档**：本批改动触及 `game/`（游戏工程代码、测试、探针、场景）→ `--code`；不触及 `game/` 的一切改动（`design/`、根规则文件、`tools/` 工具脚本、`.zcode/` 配置等）→ `--docs`；同批混触 `game/` 与文档面 → 全量档不带参数。所选域全绿才合回 master。合回前独立验收审计通过（iter 技能第 5 步），未过不合回。该脚本是全部验证闸的**唯一入口、唯一清单与唯一域划分**，闸件增减、分域调整都只改它；**本文与其他文档禁另列闸件清单**（清单散落多处正是 iter27 漏跑 `probe_gate --full` 的成因）。跑完写回执 `game/tests/.gates/receipt.json`（含 `domain` 与 `dirty_game` 字段），合回时由 worktree-guard 按 diff 路径推域强制校验（六况拦截：缺回执／quick 模式／回执未覆盖分支尖＝回执 commit 之后 `game/` 又有改动、或跑闸时 `game/` 带着未提交改动（`dirty_game`）／域不覆盖本次改动／含新增红／master HEAD 非回执 commit 祖先＝合并将产出未测内容）。回执与分支尖的对齐判据是**代码面**不是 commit 号：回执之后只追加 `reports/`、`design/` 等非 `game/` 提交，回执照样有效，不构成复跑理由。闸件（`tools/` 下机检脚本与闸壳）自身的改动不占合回全量——其质量义务＝落批时人工确认闸可跑通且判据口径未变，闸真崩溃时合回闸 fail-closed（跑不出回执即拦），不以合回全量为兜底
9. **合并后主区零复跑**（2026-10-24 用户裁：合回重跑验的是与回执同一份字节，零信息）——合回落地后 code 批只做两件秒级事：`--editor --quit` 重刷类名缓存（在册坑：.godot 缓存不入 git，与合并后代码失配会假红假绿）＋冒烟启动确认可开机（合计约 1 分钟）；docs 批零动作。全量验证**每批跑一次**＝worktree 批末按域闸，顺序是「先并入 master、再跑闸」（§1 第 2 条）；只有两种情形允许把这次跑作废重来——① 闸红且修法动了 `game/`，② 闸已开跑后 master 又被推进（合并将产出未测内容，由合回闸祖先判定拦下，§3.9 第六况）。「跑都跑了再跑一遍保险」「闸后顺手改点 `game/` 再补一跑」都不构成复跑理由；master 上永不跑全量
10. **批次完成后的登记义务**——合回 master 后按 doc-conventions §12.1 推进待办清单条目状态（做完整条删除），涉及迭代编排的在 roadmap 迭代总表与顶部「当前位」节换代——执行入口=项目技能 batch-closure（批后收尾与中间文档退役），跨会话教训写记忆库。批次过程与结论由 git 提交信息承载，禁止再写会话状态文件（见 doc-conventions 第 10 节）。`design/` 与根规则文件（`AGENTS.md`/`roadmap.md`/`待办清单.md`/`体验验证清单.md`）实现批禁写，见 §12
11. **文档同步闸（实现批禁写文档）**——实现批**禁写 `design/` 整个目录与根规则文件**，要往外交代的东西一律落 `reports/`：实现报告 `reports/iter<N>-实现报告-<日期>.md`（各卡状态+实机目检总清单+遗留读数义务）、代拍板追认单 `reports/iter<N>-代拍板-<日期>.md`、GDD 反哺点清单 `reports/iter<N>-反哺点-<日期>.md`（每条写清哪个文件哪一节、改成什么、依据是什么）。设计权威文档（GDD/art-bible）**任何批都不直改**：用户在会话中逐点裁决后，由非迭代批（工具/规则/文档批）写入 `design/`（执行入口=doc-design 技能），并把反哺条目从 `reports/` 清掉（吸收即死；退役执行=batch-closure 技能）。机械面文档（roadmap 行/术语表/README 工具注）同样归非迭代批在合并前更新。反哺点未落地期间相关 GDD 节视为待反哺，读前先查 `reports/` 与待办清单；需求卡片必列「关联文档同步面」按两层标注
12. **实机目检归用户，只登记不阻塞**——真人检测项登记进实现报告目检总清单与体验验证清单即完成批内义务；禁把等目检当停工理由或完成前置
13. **中间产物吸收即死**——细则见 AGENTS.md 硬性红线与 doc-conventions 第 11 节
14. **改动级验收闭合**——写卡期列需求侧对照表，实现期补实际对照表（测试文件:行），每个行为改动做撤销证明；合回前独立验收审计。细则=test-conventions §8
## 4. 测试执行两入口铁规（细则）
测试类执行——冒烟、单元测试（tests/run_all）、模拟验证（MC/verifier/调参批量工具）、场景探针等一切跑游戏的验证——只有两个触发入口：①**迭代 loop 开发**（冒烟挂迭代出口/入库闸，loop 内过程性验证属开发工作本身）；②**用户主动点名**。其余会话（问答/调研/文档/审查/零散小改）一律零测试；确需测试支撑结论时先请示，以静态阅读/推理作答并注明未跑测。
**MC/verifier 触发细则**：仅在数值验证场景触发（改数值前后取证）；normal 档为主、perfect 按需；**无数值改动的会话禁跑 MC**；结构位移类「存档锚」须先向用户请示定性再跑；需求卡片预设步骤的前提消失时（如「带值裁定后重锚」实际未投值）停问勿照字面执行。
**分级周期口径**：全部验证闸收编在 `tools/run_all_gates.sh` 一个入口下（**脚本即清单，且即域划分的唯一出处**），分三档——`--code`／`--docs` 按本批改动域只跑该域闸（闸件清单与域划分只写在脚本头部注释，本文不重列）；`--quick` 是全量档的中段自检形态（跳过渲染闸与静态扫描）；**不带参数＝两域全量**，用于一次改动同批混触 `game/` 与文档面。完成出库按所选域全绿，回执由合回闸按 diff 推域强制校验。真人实机目检归用户不进自动闸。
## 5. MC 采集档位细则
四档硬闸（全表与统计精度见 `sim-data/README.md`「MC 采集档位表」）：
| 档 | 用途 | 上限 | 触发权 |
|---|---|---|---|
| 一档·调研 | 调研/数值分析 | 总量 >40 | **只能由用户发起**——需求卡片/计划书/agent 均无权授权 |
| 二档·数值修改验证 | 改数值前后取证 | 总量 ≤40、每档 ≤20 | 数值验证场景 |
| 三档·小调 | 只测不判 | 总量 ≤20、每档 ≤10 | 数值验证场景 |
| 四档·微量 | sanity 门，零统计判读 | 总量 ≤5 | 数值验证场景 |
配套纪律：超档=停机呈报，窗口不足如实挂起，禁在二/三/四档下带值结论；改前/改后锚同 seed0 配对、改前锚留盘禁补跑；逐项比对断言零新跑（复验用锚内子集 ≤20）；读数缺陷（零 gameplay/RNG 触碰）禁整套重跑、走事件流重构补算；≥60 局采集先 N=5 pilot 校验字段；二/三/四档会话累计 ≤20 分钟；零数值改动=零 MC；四档仅承接数值验证场景，两入口铁规不变。
## 6. 闸机轮次纪律
1. **孤立验证先行**——新代码/新工具/新断言进全套闸之前，先走通最小可运行路径的 standalone 验证（30 秒级：新断言=单独驱动函数直跑；新工具=最小参数全路径试车含产出落盘；新探针=单 .tscn 直跑）；禁以全套闸首跑充当新码首验
2. **调试期最窄确认**——出红→修复→确认只跑出红的最小单元（单探针/单套件/单函数）；全套闸每个里程碑步（波/T 段）出口最多一次，红灯补跑只跑红件；修的是全部探针/套件共用的共享件（冒烟包装器、闸机脚本本身）时全套即最小充分单元，注记说明即可
3. **长批试车**——≥2 分钟的跑批（逐位逐项比对冻结/MC 批/批量模拟）发起前，先用最小参数把工具完整路径（含解析/落盘/写锚全链）跑通一遍再放长批
4. **开工坑册扫描**——每波/T 段开工前，按要触碰的面扫一遍在册坑（worktree 缓存三件套、--script 模式无 autoload、守卫文本匹配等）
## 7. 像素结构件工作纪律
1. **先抄后造**——画像素结构件前，先从参考素材裁同类结构放大逐像素描述，再实现同款；禁凭印象/第一性原理发明像素结构（art-bible §8.5 参考核验的执行口径）
2. **验完成径写成像素级视觉判据**——开工前把合格标准写成"X 与 Y 同列收尾/无悬空/无突出"式句子；自检放大最差交界处逐行核像素，不只看整板观感
3. **±1px 一律坐标推导**——单像素级结构先写坐标推导（哪条线在哪列、谁与谁齐平）留档再写码；禁蒙数试错
4. **修复默认附前后对比图+像素审计**，不等用户索要
# 流程规范（Dungeon Sweeper）␍
␍
> 约束范围：一切批次的流程纪律——分支与 worktree、五段流水线、批次工作流、测试执行细则、像素件工作纪律。␍
> 分工：硬性红线的一句话索引在 AGENTS.md「硬性红线」；本文承载其操作细则；批次开工前通读本文。␍
␍
**开工任何批次前必须通读本文。**␍
␍
## 1. 分支纪律（worktree 铁律）␍
␍
主工作区（master 检出）只作合并落点，一切开发/设计改动禁止直接发生在主工作区：␍
␍
1. **开工**：每批次先建独立 worktree：`git worktree add ../g-plan2-<任务名> -b <任务分支>`；所有改动与验证都在 worktree 内进行（未跟踪文件不会出现在新 worktree，需手工搬运）␍
2. **收尾**：批次收口顺序固定为**冻结 → 件核 → 并 master → 跑一次域闸 → 合回**——代码与断言改完即冻结，全仓件核 grep 查残留；master 已被别的批次推进时先 `git merge master` 解冲突（必须在跑闸之前，闸跑完再并＝那次闸白跑），然后按本批改动域跑**一次** `tools/run_all_gates.sh`（见 §3.9：纯文档批跑 `--docs`），全绿后在主工作区 `git merge --no-ff <任务分支>`，再 `git worktree remove`+删分支。闸后 `game/` 面不得再改一个字节（回执作废须重跑），只允许追加 `reports/`、`design/` 等非 `game/` 提交。非 loop 批次同此顺序；游戏类测试（冒烟/单测/MC/探针）对它默认零执行（两入口铁规，见 §4），用户点名或当场问才跑␍
3. **豁免面**：仅 `.zcode/`（钩子与配置）与 `.qoder/`（本机 harness 配置）允许主工作区直改——两份实测均不入 git（走 worktree 反而带不进去，改动只对本机生效）；其余一律走 worktree，主工作区 git commit 被钩子拦截␍
4. 本铁律由 PreToolUse 钩子 `.zcode/hooks/worktree-guard.sh` 强制兜底；钩子只约束 agent，用户手工改动不受限␍
␍
## 2. 五段流水线␍
␍
**需求改动**（游戏代码，含随逻辑写/改的测试）按五段流水线走：**登记 → 文档设计／美术设计（两条设计线）→ 写需求卡片 → 迭代编排 → 实现**；工程／文档设计／美术素材三类改动不走写卡与编排段，走「登记 →（如需设计讨论）→ 用户发令直改 → 按改动域跑闸 → 完成删条目」。两层口径（2026-10-25 用户立）：需求卡片＝需求单位的实施文档，任何工作量皆可写、皆可编入迭代；工作量限制只属迭代层——迭代估时总量 <5 个工作日＝「冻结待凑批」，不可开工。段间不自动流转，每段转进由用户发令；每段一个技能入口（五者均装于项目 `.zcode/skills/`：doc-design／asset-ingest／req-card／iter-plan／iter），登记不立技能（条目格式由流水线闸强制）。设计工作在会话内进行、用户主导、禁无监管自跑。␍
␍
| 段 | 入口技能 | 产出 | 出入口铁律 |␍
|---|---|---|---|␍
| 一·登记 | 无（闸管格式） | 待办清单条目 | 条目=标题登记元数据（日期/来源/可选优先级）＋正文四属性（实况/缺口/改动面/状态）；标题登记后不再变，正文随进程演进。格式与状态机权威=doc-conventions 第 12 节 |␍
| 二·文档设计／美术设计 | doc-design（文档线，兼任反哺点写入）／asset-ingest（美术录入；样张素材由用户主导产出） | GDD 文档或 art-bible／过审样张素材 | 用户提起或从待办清单取出；会话内进行、用户主导、禁无监管自跑；经用户点头确认心智一致才许写入文档；完成判据=待裁点清零，带未裁点的是讨论稿；设计线闭合凭据记入待办清单实况清单（文档线=文档路径+版本号，美术线=art-bible 条款版本）；缺哪条线写在缺口属性，闭合与否写在状态段 |␍
| 三·写需求卡片 | req-card | 需求卡片 | 设计线闭合后用户发令；新玩法/新系统/新内容必须有设计定稿前置，例外=需求性工程条目（缺陷修复／重构等改游戏行为）凭实况里的证据指认跳过设计线；配套维护类（工程债/测试基建/工具维护，不动游戏行为）＝工程改动直改类，不走本段，登记后「待执行」由用户发令直改；卡片必经 grilling 多轮复核、零待裁点才成立；写完在待办清单状态记「已写卡」，卡片路径记入实况清单（防遗忘） |␍
| 四·迭代编排 | iter-plan | roadmap 迭代行 | 编排四查：①每卡卡片文件存在 ②每卡设计闭合凭据齐（或需求性工程条目的证据指认）③估时与冻结线——所选卡估时按区间**中值**求和（单位工作日、写精确值不取整）：**卡片任何工作量均可编入**（2026-10-25 用户立：工作量限制属迭代层、非卡片层）；编入后迭代总量 <5 个工作日＝迭代行状态「冻结待凑批」、不可开工，凑批 ≥5 后由编排段改「待开工」（迭代体量偏好，2026-10-21 用户立、2026-10-25 改冻结制）；5–10 个工作日为常规区间；超过 10 个工作日须经用户确认（确认前呈报整批/拆批两案等裁，禁自行拆分或塞入），确认后迭代行随带日期特批标记；超过 20 个工作日禁止编（硬上限，用户确认也不放行，必须拆批）④写完 roadmap 行后跑流水线闸确认绿；编入未完成迭代，新开迭代行经用户确认 |␍
| 五·实现 | iter | 代码与配置，可运行的游戏 | 需求卡片永不单独施工，统一由用户指定迭代号触发（=U0 开工令），按 iter 技能与本文 §3 执行；**本段是代码实现批：禁写 `design/` 与根规则文件，产出物只落 `reports/`（见 §3 第 12 条）**；设计权威文档（GDD/art-bible）批内一律不更新；完成人闸=实机目检清单+代拍板追认单登记交用户即完成批内义务 |␍
␍
**实现段零裁断**：实现段的输入在编排段出口已锁死（卡片零待裁点＋设计闭合凭据齐＋编排四查过）。实现中冒出卡片没写清的分歧=上游缺陷——停该卡、待办清单状态回退＋缺口补记，退回上游；禁自答、禁内联提问求裁断；该卡停摆不阻塞同迭代其他卡。环境故障与测试红走异常分级（自救重试／记录继续／停机呈报）。代拍板白名单保留：授权发生在卡片审问阶段，实现只执行预授权；批后追认单=备案确认。␍
␍
**流水线闸**：`tools/pipeline_gate.py` 机检待办清单与 roadmap 两文件的格式与互相引用；已注册进 `run_all_gates.sh` 文档域。流程文档的条目格式、迭代行格式与状态机细则见 doc-conventions 第 12 节。␍
␍
## 3. 批次工作流标准清单␍
␍
每个批次按以下链路执行（本清单是总索引，细则散见各规约；冲突以细则为准，发现清单过时须同批修订）：␍
␍
**开工前**␍
1. **先检索后提问**——先查在册记忆与权威文档，禁把已裁决事项当新问题重问或重踩在册坑␍
2. **需求卡片全列备选案**——每个待拍板点列全部备选方案与代价交用户裁决，禁卡片内自行定夺␍
3. **用户发开工令才动手**——需求卡片经用户批准（U0）后方开工␍
␍
**环境与基线**␍
4. **独立 worktree+拷导入缓存**——按 §1 建 worktree；先拷主区 `.godot/` 目录与字体 `.import` 边车再跑测试，否则全量重导入资源近似卡死。检出工作区零测试，直接开工（2026-10-22 频率规则）␍
5. **涉数值改动先采改前读数**——与改后同随机种子配对比较并写明逐项比对口径；无数值改动禁跑模拟␍
␍
**实施**␍
6. **新功能必配新测试**——新增玩法/机制必须配套新测试套件进 `tests/run_all`；没有对应测试的变更不许合并；并按 test-conventions §8 挂进改动—验收对照表，没有对照表行的行为改动同样不许合并␍
7. **验收改动先行声明**——验收变化（基线换代/探针增改/旧断言改判）预先写进需求卡片，禁事后补␍
␍
**完成**␍
8. **批末按域验收才合并**——在任务 worktree 内跑 `tools/run_all_gates.sh`，**按本批改动域选档**：本批改动触及 `game/`（游戏工程代码、测试、探针、场景）→ `--code`；不触及 `game/` 的一切改动（`design/`、根规则文件、`tools/` 工具脚本、`.zcode/` 配置等）→ `--docs`；同批混触 `game/` 与文档面 → 全量档不带参数。所选域全绿才合回 master。合回前独立验收审计通过（iter 技能第 5 步），未过不合回。该脚本是全部验证闸的**唯一入口、唯一清单与唯一域划分**，闸件增减、分域调整都只改它；**本文与其他文档禁另列闸件清单**（清单散落多处正是 iter27 漏跑 `probe_gate --full` 的成因）。跑完写回执 `game/tests/.gates/receipt.json`（含 `domain` 与 `dirty_game` 字段），合回时由 worktree-guard 按 diff 路径推域强制校验（六况拦截：缺回执／quick 模式／回执未覆盖分支尖＝回执 commit 之后 `game/` 又有改动、或跑闸时 `game/` 带着未提交改动（`dirty_game`）／域不覆盖本次改动／含新增红／master HEAD 非回执 commit 祖先＝合并将产出未测内容）。回执与分支尖的对齐判据是**代码面**不是 commit 号：回执之后只追加 `reports/`、`design/` 等非 `game/` 提交，回执照样有效，不构成复跑理由。闸件（`tools/` 下机检脚本与闸壳）自身的改动不占合回全量——其质量义务＝落批时人工确认闸可跑通且判据口径未变，闸真崩溃时合回闸 fail-closed（跑不出回执即拦），不以合回全量为兜底␍
9. **合并后主区零复跑**（2026-10-24 用户裁：合回重跑验的是与回执同一份字节，零信息）——合回落地后 code 批只做两件秒级事：`--editor --quit` 重刷类名缓存（在册坑：.godot 缓存不入 git，与合并后代码失配会假红假绿）＋冒烟启动确认可开机（合计约 1 分钟）；docs 批零动作。全量验证**每批跑一次**＝worktree 批末按域闸，顺序是「先并入 master、再跑闸」（§1 第 2 条）；只有两种情形允许把这次跑作废重来——① 闸红且修法动了 `game/`，② 闸已开跑后 master 又被推进（合并将产出未测内容，由合回闸祖先判定拦下，§3.9 第六况）。「跑都跑了再跑一遍保险」「闸后顺手改点 `game/` 再补一跑」都不构成复跑理由；master 上永不跑全量␍
10. **批次完成后的登记义务**——合回 master 后按 doc-conventions §12.1 推进待办清单条目状态（做完整条删除），涉及迭代编排的在 roadmap 迭代总表与顶部「当前位」节换代——执行入口=项目技能 batch-closure（批后收尾与中间文档退役），跨会话教训写记忆库。批次过程与结论由 git 提交信息承载，禁止再写会话状态文件（见 doc-conventions 第 10 节）。`design/` 与根规则文件（`AGENTS.md`/`roadmap.md`/`待办清单.md`/`体验验证清单.md`）实现批禁写，见 §12␍
11. **文档同步闸（实现批禁写文档）**——实现批**禁写 `design/` 整个目录与根规则文件**，要往外交代的东西一律落 `reports/`：实现报告 `reports/iter<N>-实现报告-<日期>.md`（各卡状态+实机目检总清单+遗留读数义务）、代拍板追认单 `reports/iter<N>-代拍板-<日期>.md`、GDD 反哺点清单 `reports/iter<N>-反哺点-<日期>.md`（每条写清哪个文件哪一节、改成什么、依据是什么）。设计权威文档（GDD/art-bible）**任何批都不直改**：用户在会话中逐点裁决后，由工程/文档设计改动批（直改类）写入 `design/`（执行入口=doc-design 技能），并把反哺条目从 `reports/` 清掉（吸收即死；退役执行=batch-closure 技能）。机械面文档（roadmap 行/术语表/README 工具注）同样归工程/文档设计改动批在合并前更新。反哺点未落地期间相关 GDD 节视为待反哺，读前先查 `reports/` 与待办清单；需求卡片必列「关联文档同步面」按两层标注␍
12. **实机目检归用户，只登记不阻塞**——真人检测项登记进实现报告目检总清单与体验验证清单即完成批内义务；禁把等目检当停工理由或完成前置␍
13. **中间产物吸收即死**——细则见 AGENTS.md 硬性红线与 doc-conventions 第 11 节␍
14. **改动级验收闭合**——写卡期列需求侧对照表，实现期补实际对照表（测试文件:行），每个行为改动做撤销证明；合回前独立验收审计。细则=test-conventions §8␍
␍
## 4. 测试执行两入口铁规（细则）␍
␍
测试类执行——冒烟、单元测试（tests/run_all）、模拟验证（MC/verifier/调参批量工具）、场景探针等一切跑游戏的验证——只有两个触发入口：①**迭代 loop 开发**（冒烟挂迭代出口/入库闸，loop 内过程性验证属开发工作本身）；②**用户主动点名**。其余会话（问答/调研/文档/审查/零散小改）一律零测试；确需测试支撑结论时先请示，以静态阅读/推理作答并注明未跑测。␍
␍
**MC/verifier 触发细则**：仅在数值验证场景触发（改数值前后取证）；normal 档为主、perfect 按需；**无数值改动的会话禁跑 MC**；结构位移类「存档锚」须先向用户请示定性再跑；需求卡片预设步骤的前提消失时（如「带值裁定后重锚」实际未投值）停问勿照字面执行。␍
␍
**分级周期口径**：全部验证闸收编在 `tools/run_all_gates.sh` 一个入口下（**脚本即清单，且即域划分的唯一出处**），分三档——`--code`／`--docs` 按本批改动域只跑该域闸（闸件清单与域划分只写在脚本头部注释，本文不重列）；`--quick` 是全量档的中段自检形态（跳过渲染闸与静态扫描）；**不带参数＝两域全量**，用于一次改动同批混触 `game/` 与文档面。完成出库按所选域全绿，回执由合回闸按 diff 推域强制校验。真人实机目检归用户不进自动闸。␍
␍
## 5. MC 采集档位细则␍
␍
四档硬闸（全表与统计精度见 `sim-data/README.md`「MC 采集档位表」）：␍
␍
| 档 | 用途 | 上限 | 触发权 |␍
|---|---|---|---|␍
| 一档·调研 | 调研/数值分析 | 总量 >40 | **只能由用户发起**——需求卡片/计划书/agent 均无权授权 |␍
| 二档·数值修改验证 | 改数值前后取证 | 总量 ≤40、每档 ≤20 | 数值验证场景 |␍
| 三档·小调 | 只测不判 | 总量 ≤20、每档 ≤10 | 数值验证场景 |␍
| 四档·微量 | sanity 门，零统计判读 | 总量 ≤5 | 数值验证场景 |␍
␍
配套纪律：超档=停机呈报，窗口不足如实挂起，禁在二/三/四档下带值结论；改前/改后锚同 seed0 配对、改前锚留盘禁补跑；逐项比对断言零新跑（复验用锚内子集 ≤20）；读数缺陷（零 gameplay/RNG 触碰）禁整套重跑、走事件流重构补算；≥60 局采集先 N=5 pilot 校验字段；二/三/四档会话累计 ≤20 分钟；零数值改动=零 MC；四档仅承接数值验证场景，两入口铁规不变。␍
␍
## 6. 闸机轮次纪律␍
␍
1. **孤立验证先行**——新代码/新工具/新断言进全套闸之前，先走通最小可运行路径的 standalone 验证（30 秒级：新断言=单独驱动函数直跑；新工具=最小参数全路径试车含产出落盘；新探针=单 .tscn 直跑）；禁以全套闸首跑充当新码首验␍
2. **调试期最窄确认**——出红→修复→确认只跑出红的最小单元（单探针/单套件/单函数）；全套闸每个里程碑步（波/T 段）出口最多一次，红灯补跑只跑红件；修的是全部探针/套件共用的共享件（冒烟包装器、闸机脚本本身）时全套即最小充分单元，注记说明即可␍
3. **长批试车**——≥2 分钟的跑批（逐位逐项比对冻结/MC 批/批量模拟）发起前，先用最小参数把工具完整路径（含解析/落盘/写锚全链）跑通一遍再放长批␍
4. **开工坑册扫描**——每波/T 段开工前，按要触碰的面扫一遍在册坑（worktree 缓存三件套、--script 模式无 autoload、守卫文本匹配等）␍
␍
## 7. 像素结构件工作纪律␍
␍
1. **先抄后造**——画像素结构件前，先从参考素材裁同类结构放大逐像素描述，再实现同款；禁凭印象/第一性原理发明像素结构（art-bible §8.5 参考核验的执行口径）␍
2. **验完成径写成像素级视觉判据**——开工前把合格标准写成"X 与 Y 同列收尾/无悬空/无突出"式句子；自检放大最差交界处逐行核像素，不只看整板观感␍
3. **±1px 一律坐标推导**——单像素级结构先写坐标推导（哪条线在哪列、谁与谁齐平）留档再写码；禁蒙数试错␍
4. **修复默认附前后对比图+像素审计**，不等用户索要␍
design/engineering/test-conventions.md
+1
View File
@@ -2,6 +2,7 @@
> 约束范围：`game/probe/ 与 game/sim/`、`game/tests/` 与一切场景探针的编写与验收。
> 分工：测试**执行许可**（什么时候允许跑测试）归 AGENTS.md「硬性红线·测试执行两入口铁规」；**跑什么闸、什么顺序**归 `tools/run_all_gates.sh`（脚本即清单，本文与 AGENTS.md 均不另列）；本文管测试怎么写、怎么算合格。每件测试工具**是什么、判什么、怎么单独跑、什么时候适合单独用**——见 `game/tests/README.md`（测试工具手册），本文不重复工具介绍。
> 归属：随游戏逻辑写/改的测试＝需求改动的一部分（随需求卡片同批落地）；不伴随逻辑改动的纯测试维护＝工程改动（不写卡，用户发令直改）。
**写任何测试前必须通读本文。**