29 KiB
文档写作规范（定文档方案前必读）
地位：本文是文档写作的规范权威，与
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. 白话写作规则
写文档像向朋友当面解释你的游戏：
- 完整句子优先：一段只说一件事，长句拆短句。
- 禁止碎片笔记体：不写压缩碎片，不把
A→B→C箭头链当叙述（流程交给图，见第 3 节），不用只有作者自己懂的缩略语。 - 每节人话开头：每小节第一段先用白话说清"这是什么、为什么需要它"；只读各节第一段就能看懂全文故事线。
- 术语首现即解释：专业术语或项目概念首次出现用一句话解释；玩家可见专属名词（如"显影尘"）同样要说清。
- 叙述优先于引用：AC-x、F-x 等编号引用不进正文叙述，只出现在验收标准与附录。
- 反面基准：数据库条目、会议纪要、只有评审工具能"读懂"的表格堆。
3. 表达分工：散文、表格、字符画、公式
| 内容 | 载体 | 纪律 |
|---|---|---|
| 规则的来龙去脉、行为逻辑 | 散文段 | 每段 ≤240 字，一段一件事 |
| 枚举、数值、边界、依赖 | 表格 | 表格只放可列举的事实；禁把需要解释的内容塞进单元格让读者自己拼 |
| 流程、状态流转、结构关系 | 文档内嵌 HTML/SVG（默认）· Mermaid（网页发布保底）· 字符画（无渲染环境保底） | 禁用散文逐步描述流程；默认在文档内嵌 HTML/SVG（表现力优先，本地预览即渲染，图体行数计入节点篇幅）；发布到会过滤内嵌 HTML 的网页端时改 Mermaid；无渲染查看环境用字符画 |
| 公式 | 结论先行 | 先一行加粗结论，再放公式代码块、变量表与验算表 |
| 体验锚点 | 关键词表 | 支柱/关键词/机制承诺 三列表，禁长篇情绪描述 |
节点内顺序：先人话，再表格枚举，再流程图（内嵌 HTML/SVG 或字符画），最后公式举证。规则两段式：先写"人话阶段"（作用于哪个系统、什么情况下、谁触发、触发后发生什么），再写"举证阶段"（逐效果给出计算方法；纯流程规则明写"无计算"）。规则名禁止纯名词短语（反面例："获取路由"）。
4. 用语纪律（见名知意 · 所见即所得 · 禁自造黑话）
正面总则：见名知意——每个名字（概念名、术语、文档与目录名）本身就说清所指，起不出这样的名字多半是概念还没想清；所见即所得——字面意思就是规则的完整意思，有隐含前提就写进句子。两句管语义透明，不与第 8 节指路存根冲突。
文档、评审输出、日志中禁止自造黑话——比喻性生造词、只有作者自己懂的缩略语（对话输出面的用语与证据规则归 AGENTS.md「回答风格规则」，不在本节范围）：
- 只能使用：（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 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文 |
| 正文只写现行规则 | 禁删除线、"（作废）"、"（日期+拍板）"式注记；审计信息入对应文档附录 |
| 禁实现内容 | 系统文档与概念文档全文禁写实现细节——代码路径（.gd／.py／.sh 与运行时文件路径）、测试文件名、断言名、类名／方法名／信号名／常量名／调试与遥测入口名、提交号一律不出现；唯一例外＝数据索引（game/data/tables/*.tres 与 game/data/schemas/ 的表路径与表名、表字段名与表内枚值、存档键、封闭词表标签）。实现事实归 architecture.md；验收标准只写玩家或系统可观测面。本行由文档域闸的能力审计机检两个可判死的面（带后缀路径、反引号调用形态），其余靠写卡段人工核对；闸件清单与域划分的唯一出处＝tools/run_all_gates.sh 头部 |
| 正文单点维护 | 一条规则句只写在定义它的那份文档（owner 文档）；其他文档要引用时写指针或语义概括，禁复制色值、尺寸、路径等可核对的具体值——上一句管不住数值之外的双写，本句补上。豁免面 = 执行侧文件必须带字面值才能工作时（生图提示词里的十六进制色、脚本参数），转写不算双写，但该文件头部必须写明"冲突时以 owner 文档为准" |
| 禁写变更记录 | 文档与代码文件内一律禁设「版本历史／修订记录／变更记录／修改记录／更新记录／更新日志」节或表格，禁逐版本叙述「改了哪些条款」；沿革与改动明细只进 git commit log。版本号可作为文档现行身份标记出现在文首状态行与正文引用中，但不得再挂变更表 |
| 后置 ≠ 删除 | P1/P2 后置内容逐条列出；复活后置项 = 修订文档，禁静默加回 |
| 活体清单不冻结计数 | 对会生长的清单（文档树构成、UI 层项、RNG 流词表等）不写死计数与枚举——写指针到 owner（根索引/常量表/实现文件），现状值由 owner 承载；历史计数只进 git 提交信息 |
数值纪律（概念/实现分界，2026-11-05 用户立）：GDD 概念文档只定概念、机制与规则——是什么、有什么、为什么；数量面（多大、多少、多大概率）与呈现实现细节不进概念文档正文。分工三处：取值域与字段契约归 game/data/schemas/*.gd（表结构定义＋域校验执法，provisional 随值标注）；现行值归 game/data/tables/*.tres；呈现实现规格（冻结公式、像素值、动效参数）居 design/gdd/ux/＝呈现实现设计规格层，豁免概念纯度约束。存量系统文档的旧调参表节由独立清扫批消化，消化期不作机检对象（现行闸无此项判据）。
登记处唯一性：design/registry/（entities.yaml／architecture.yaml）已注销删除，禁再建第二处事实登记——术语进 术语表、数值进 .tres、架构进 架构文档、影响面靠全仓搜索概念规范名得出。强制收口条款：
- 双写失同步禁止——任何数值变更必须同步受影响三处：概念文档正文中表述该数值的规则句（若有）、
data/tables/行值与 schema 校验域、相关待办清单现状——其一未更新即视为变更未完成。 - 锁数后概念文档不存现行值——概念文档参数契约节只留概念与意图，指针指向
.tres对应行键与 schema 域校验。 - 覆盖范围 = 奖励/状态/敌人/技能/充能/护甲等级/区间掷点/难度曲线/D_ref 等所有数值字段。
- 维护通道 = 「设计批 → 同步批」两段式；数值表改完不等于修订完成。
- 压缩/换装批 = 「
.tres落批 + 切片 smoke 跑通 + 概念文档参数契约节改为概念句与指针 + 待办清单刷新」四步全收才记版本号。
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 后置／参数契约（概念面：本系统有哪些参数、各自设计意图一句话；取值域与字段契约指路 game/data/schemas/，不进本文）／验收标准（玩家或系统可观测的判据，禁实现细节）／待办（指路存根）。
命名：中文、见名知意；禁 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 顶部「当前位」节；待办与待裁看 待办清单（唯一登记处）；批次过程与结论看 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 证据或工程债条目）。
**缺口**：还差哪一次设计讨论／哪份设计产物才能写卡。尚有未闭合设计段时此属性必须存在；设计线全部闭合后删除。
**改动面**＝文档／美术素材／游戏代码／工具代码 四档取多，多档用＋连接、禁重复、按上表次序排列。登记时即写，随进程若产出面变宽要补档。
**状态**：按状态机取词。
条目正文限长（2026-11-04 立）：正文四属性只写现行状态与证据指针；过程叙事（逐轮裁定追记、「某日用户裁…」式沿革叙述、设计讨论过程复述）禁入正文——沿革与裁定史由 git 提交信息承载（第 10 节同源）。长度硬上限双判据：正文（四属性全部内容，不含标题与空行）≤12 行，且去空白字符合计 ≤700 字；任一超限即须压缩，由流水线闸机检。行数判据抓清单行蔓延，字数判据抓单行堆砌，两条并用缺一不可（实证：单行堆砌型超长条目一行可塞 1500 字，只限行数拦不住）。压缩方向＝枚举与裁定细节迁 owner 文档或过程件（关联文档清单指过去），正文只留现行状态＋证据指针＋缺口。
改动面 四档的划线判据（按被改对象的路径归属，与闸的分域同口径）：
| 档 | 覆盖范围 |
|---|---|
| 文档 | 本仓库的 .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 条款版本、需求卡片路径、复核报告路径（「已写卡」段另须报这一项，2026-11-05 用户立规；对文件名日期 ≥2026-11-06 的卡生效，旧卡不回头改，核对由 tools/pipeline_gate.py 的卡片复核判据到卡正文做）、落点文档+版本——一律写在实况的关联文档清单里，由流水线闸到正文核对；已编迭代 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）。
执行技能一律两段式：
- 对象已有内容 → 直接写入标记。
- 对象没有任何内容 → 必须回呈实况，经用户再次确认后才写标记。
标记必须带日期，无日期=非法。流水线闸见合法特批标记放行对应判据。