diff --git a/CLAUDE.md b/CLAUDE.md index f49fb3b4..e4cbff61 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -47,7 +47,7 @@ | 时机 | 权威文档 | |---|---| | **写代码 / 改代码前** | `design/dev/code-conventions.md`——结构 / 契约 / 测试 / 语言 / 数值 / 流程六类硬纪律 + 反面案例对照表 | -| **写文档 / 改文档前** | `design/dev/doc-conventions.md`——可读性第一、白话写作、概念封装、引用纪律、文档骨架 | +| **写文档 / 改文档前** | `design/dev/doc-conventions.md`——可读性第一、白话写作、概念封装、引用纪律、文档骨架、文档生命周期(吸收即死) | | 查系统设计 / 增删文档 | `design/gdd/02-系统清单.md`——根索引 + 中文规范名↔英文代号对照表 | | 架构与决策记录 | `design/dev/architecture/architecture.md` + 同目录 `adr-*.md` | | 引擎版本与参考 | `design/dev/engine-reference/godot/`(版本表已在上方 @ 引入) | @@ -67,6 +67,7 @@ ## 硬性红线(勿违反) - **worktree 铁律**:主工作区禁止直接改动与提交(细则见上节;并行会话各占 worktree 互不踩踏) +- **中间产物吸收即死(2026-10-01 立规)**:中间文档(批任务书/机检报告/调研审计报告/模拟读数/迭代计划书/目检清单)寿命=迭代寿命——结论先吸收进正主文档、未决项先迁 `design/gdd/06-待办清单.md` 或 roadmap,然后文件即删,且永不提交 git;活文档=唯一事实源,git=变更记录。细则见 `design/dev/doc-conventions.md` 第 11 节 - **数值单一事实源**:玩法数值只存 `data/tables/`(.tres),经 `ConfigDB` autoload 类型化单点读取;禁止数值字面量与自建 `load()` 表路径 - **RNG 单点**:禁止 `randomize()` / 自建 RandomNumberGenerator——随机只经 `RngService` 统一流(单盐单计数器+用途标签+全事件日志,ADR-0007 裁丙 2026-09-27) diff --git a/design/dev/doc-conventions.md b/design/dev/doc-conventions.md index 62fa1e4c..13edc98d 100644 --- a/design/dev/doc-conventions.md +++ b/design/dev/doc-conventions.md @@ -1,7 +1,7 @@ # 文档写作规范(写文档前必读) -> **地位**:本文是本项目文档写作的规范权威,与 `docs/code-conventions.md`(代码规范)对等——写代码前必读代码规范,写文档前必读本文。CLAUDE.md 只保留导航指针,细则以本文为准。 -> **适用范围**:`design/` 下一切现行文档(顶层文档、`systems/` 系统文档、`design/ux/`、`design/art/`、`design/research/`)与 `production/` 会话记录;`docs/` 其他说明文档参照执行。 +> **地位**:本文是本项目文档写作的规范权威,与 `design/dev/code-conventions.md`(代码规范)对等——写代码前必读代码规范,写文档前必读本文。CLAUDE.md 只保留导航指针,细则以本文为准。 +> **适用范围**:`design/` 下一切现行文档(顶层文档、`systems/` 系统文档、`design/ux/`、`design/art/`、`design/research/`)、根目录 `active.md` 会话记录与 `roadmap.md`。 > **成文**:2026-09-14。整合来源:用语纪律(2026-09-09 评审确立)· 文档形态纪律(2026-09-13 评审确立)· 两件套与树形文档体系纪律(2026-09-14 用户拍板)· 新骨架过渡口径(2026-09-14 用户拍板)· 可读性纪律(2026-09-14 用户提出)· 引用纪律(2026-09-14 用户提出)· 概念封装纪律(2026-09-15 用户提出)。 ## 0. 总纲 @@ -150,7 +150,26 @@ ## 10. 会话记录纪律 -`production/session-state/active.md` 每条进度 ≤3 行(粗体键 + 短句);详情一律外链到对应文档或报告,禁止把定稿摘要、义务清单整段塞进条目。 +根目录 `active.md`(会话快照+批次台账)每条进度 ≤3 行(粗体键 + 短句);详情一律外链到对应文档或报告,禁止把定稿摘要、义务清单整段塞进条目。台账条目记裁决结论本身,不记中间文档文件指针(见第 11 节)。 + +## 11. 文档生命周期:吸收即死(2026-10-01 用户立规) + +文档分两类。**活文档**是唯一事实源,长期维护: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` 台账引用不阻塞(台账=历史变更记录) | +| 台账记结论 | 台账条目记裁决结论本身,不记中间文档文件指针;中间文档删除后不留死链指针 | +| sim-data 白名单 | `sim-data/` 只保留 README、日志、分析工具 .py、现行 MC 对拍锚(显式清单)、设计文档 md;可再生原始数据(runsum/raw jsonl/逐局 CSV/report txt/样例输出)不入库 | +| 出口清理项 | 每迭代出口检查单必含清理项:本迭代中间产物逐份核对(结论已吸收、未决已迁移)后删除 | +| 暂存地非档案库 | `design/research/` 与 `design/qa/` 是中间文档的暂存地,不是永久档案库;入此两处的文件默认按本节规则到期即死 | + +**删除方式**:按第 8 节删除概念 SOP 的口径执行——先查引用面(grep 文件名于上表阻塞域),改写或删除指路句,再删文件,收尾跑死链检查全绿。 ## 版本历史 @@ -164,3 +183,4 @@ | v6 | 2026-09-16 | 待拍板收编批:第 8 节引用纪律新增「待拍板单点登记」(待拍板事项单点登记 `design/gdd/06-待拍板清单.md`,系统文档只留指路存根,新增条目直接登记清单);第 6 节顶层文档表补入 `06-待拍板清单.md`,骨架表「待拍板」行改为指路存根口径 | | v7 | 2026-09-16 | 06 清单改版(用户拍板):「待拍板」术语全仓改「待办」,清单更名 `design/gdd/06-待办清单.md`;清单内格式由四列表格改为「循环 → 系统 → 条目(四级标题)+ 粗体属性段(现状 / 归属 / 状态)」,条目解决后状态改"已解决(日期)"留痕;第 6 节顶层文档表与骨架表、第 8 节「待办单点登记」同步改指 | | v8 | 2026-09-30 | **概念落位与口径携带条款(微光口径事故后补成,用户拍板)**:第 7 节概念封装纪律增「落位五要素」行(定义/作用对象与范围/生命周期/关联/状态缺一不立)与「无正主,不下定义」段(概念未落正主前,任何文档不得替它下定义,只许 06 登记「待落位」);第 8 节「引用不转述」行扩口径携带纪律(作用对象/范围/生命周期随句写全或显式指路,禁裸形容词复述) | +| v9 | 2026-10-02 | **文档生命周期条款(2026-10-01 用户立规「吸收即死」落文)**:新增第 11 节——中间文档寿命=迭代寿命,结论吸收进正主即删、未决先迁再死、永不入库、引用面口径、台账记结论不记指针、sim-data 白名单、迭代出口清理项、design/research 与 design/qa 为暂存地非档案库;第 10 节补台账记结论口径;文首地位/适用范围两处过期路径修正(`docs/`→`design/dev/`、`production/` 会话记录→根 `active.md`) |