0 Fork 0

Files

T

DKChan b27e4710b6 feat(闸): 验证闸按改动域分跑 + 迭代批禁写 design/ + 新建 reports/ 收实现批产出物

用户裁定（2026-10-17）五条：①代码批只跑代码闸、文档批只跑文档闸；②迭代批是代码实现批，
禁写 design/，文档只读、是实现批写测试与代码的输入依据；③迭代实现报告不写在 design/ 内；
④不设文档编写 skill——文档由用户在会话中讨论后落地；⑤本批属工具/规则面，不占迭代号。

一、tools/run_all_gates.sh（域划分唯一出处）
- 新增 `--code`（01 冒烟/02 单元/03 探针 --click/04 探针 --full/05 渲染闸/09 静态扫描/11 回放对拍）
  与 `--docs`（06 gdd_lint/07 doc_link/08 doc_term/08b active.md 体量）；10 熵增闸两域都含
  （文档批新增或挪动 .md 同样会绊它，且纯文本秒级）；不带参数＝全量，改闸件本身或跨两域时用。
- 域外闸不入 NAMES，不产生假变化；同时修「基线绿 → 现 SKIP」被误判为闸况变化（--quick 回执
  此前永远自带三条假红）。
- 回执增 domain 与 not_run 字段。
- 导出 PYTHONIOENCODING=utf-8：GBK 控制台下 06/10 两闸打印 ✅/✗ 直接崩（假红）、09 的 FAIL 行
  写成乱码字节致指纹漂移（假「红项清单变化」）、末尾汇总自身崩打不出结论——2026-10-16 实踩。
- 新增代码域素材齐盘预检：game/assets/art/** 与一切 *.import 边车都不入 git（2026-09-29 裁定），
  worktree 冷检出必空盘 → main_theme.tres 解析失败 → 冒烟 V1 七项假红。缺位即拒跑并列缺哪件，
  附处置命令（cp 主区素材 + --editor --quit 刷导入；--import 不生成新素材边车）。

二、tools/render_gate.sh（空跑判绿改判红）
- 棋盘/菜单两段 golden 在素材缺位时原为 SKIP，而闸末照样打印「全绿」exit 0——一个像素都没比
  却报通过。2026-10-16 菜单废基线事故正是靠这个信号盲区混过 worktree 自检的。现改判红。

三、reports/ 新顶层目录（实现批唯一可写目录）
- 收迭代实现报告/代拍板追认单/GDD 反哺点清单；repo_structure_audit.py TOP_DIRS 与 CLAUDE.md
  Project Layout 两处白名单同批改齐（熵增闸自陈的强制口径）；reports/README.md 立范围与生命周期。

四、规则文本五处同步
- CLAUDE.md：验收口径改按域；硬性红线新增「两类批」条（迭代批禁写 design/ 与根规则文件、
  产出只落 reports/、只跑代码域闸；非迭代批不占迭代号）；Project Layout 登记 reports/。
- process-conventions：§3.10 批末按域验收；§3.12 补 active.md 例外（会话状态唯一源，钩子本就
  豁免）；§3.13 重写为「实现批禁写文档、产出物落 reports/、反哺点由文档批裁决后写入」；
  §4 分级周期口径改三档；§2 三段流程「三·实现」行加禁写面。
- doc-conventions 载体分工表：迭代实现报告落位由 design/qa/ 改 reports/。
- architecture.md「测试与质量域」：新增「改动域划分」节（域表＋唯一出处声明＋素材预检缘由），
  本表是现状登记非第二份清单。
- 06-待办清单：登记本批两处代拍板（active.md 例外读法、reports/ 新顶层目录）与旧实现报告
  iter27/iter28 两份仍在 design/qa/ 未迁位的欠账。

五、连带（不在本仓库，gitignored 本地 harness 配置）
- .zcode/hooks/worktree-guard.sh：合回校验由「不碰 game/ 即全免」改为按 diff 路径推定所需域、
  要求回执 domain 覆盖之；未登记路径按最严处理，禁默认放行。旧豁免的漏洞：改闸件本身反而零验证。
- ~/.zcode/skills/iter/SKILL.md：顶部加批性质与闸域两条强制声明；批末重闸移出 doc 三闸；
  总收口产出物改落 reports/、roadmap 换代移出本批；定义面入库注明是搬运非撰写。

验证：--docs 域全绿（06 由基线红改善为绿，因 fcb8c3f8 已补 01 篇流程图）；素材预检反例实测
（移走 button_stone.png → 拒跑 exit 1，还原后正常）；渲染闸缺盘反例实测（exit 1 并报 FAIL）；
--code --docs 互斥与非法参数 exit 2；guard 内嵌 python 编译通过并按 docs 域回执放行 docs 批。

2026-10-17 00:40:53 +08:00

12 KiB

Raw Blame History

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

地位：本文是文档写作的规范权威，与 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. 白话写作规则

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

完整句子优先：一段只说一件事，长句拆短句。
禁止碎片笔记体：不写压缩碎片，不把 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`
架构事实唯一源	`design/dev/architecture/architecture.md` 是架构事实的唯一权威（分层/模块归属/数据流/API 边界/测试与质量域）；禁建第二份架构文档；历史决策记录只进 git commit log
一页纸节点	一节、一条规则 ≤一页纸（约 ≤80 行）；装不下就拆节
一系统一文档	不建 analysis 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文
正文只写现行规则	禁删除线、"（作废）"、"（日期+拍板）"式注记；审计信息入 `design/registry` 或附录
后置 ≠ 删除	P1/P2 后置内容逐条列出；复活后置项 = 修订文档，禁静默加回

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

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

6. 文档类型与骨架

顶层文档：

文档	管什么
`00-游戏概念.md`	一句话概念、目标受众、世界观命名、术语层级
`01-核心循环.md`	玩家醒来→做什么→得到什么→又想做什么，一条线讲清
`02-系统清单.md`	根索引：循环 × 子系统总表 + 文档树导航
`03-内容规模.md`	几个关卡、几种敌人、几种道具——做多少砍多少
`04-美术音频方向.md`	参考图、参考游戏、风格关键词
`05-不做清单.md`	明确写：这些我不要
`06-待办清单.md`	全项目待办唯一登记处；各系统文档「待办」节只留指路存根

系统文档骨架（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 KiB Raw Blame History Unescape Escape