From 58586297196a4cb87050c46f50f556ddae3830b8 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Thu, 15 Oct 2026 15:38:16 +0800 Subject: [PATCH] =?UTF-8?q?docs(=E8=A7=84=E7=BA=A6):=20=E7=AC=AC=E4=BA=8C?= =?UTF-8?q?=E5=88=80=E6=8C=89=E7=9C=9F=E5=AE=9E=E8=8C=83=E6=9C=AC=E5=AF=86?= =?UTF-8?q?=E5=BA=A6=E5=8E=8B=E7=BC=A9=E2=80=94=E2=80=94CLAUDE.md=2067?= =?UTF-8?q?=E8=A1=8C=E7=A5=88=E4=BD=BF=E5=8F=A5=E4=BD=93+=E6=B5=81?= =?UTF-8?q?=E7=A8=8B=E7=BA=AA=E5=BE=8B=E7=8B=AC=E7=AB=8B=E6=88=90=E6=96=87?= =?UTF-8?q?=EF=BC=882026-10-15=20=E7=94=A8=E6=88=B7=E4=BB=A4=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 对照实测范本（anthropics/claude-code 40 行、openai/codex ≈250 行纯祈使句等七份）逐类清除叙事层： - CLAUDE.md 140→67：三段开发流程/批次清单/分支纪律/两入口与MC细则/像素纪律全部降级出主文件；红线压成一行一条祈使句+指路；呈报六问压缩为单条索引行 - 新增 process-conventions.md（86 行）：三段流程表格化+批次清单 14 条+两入口/MC 触发/分级周期/MC 档位/闸机轮次细则+像素结构件纪律——批次开工时加载 - 新增 code-conventions-cases.md（55 行）：全部反面案例+缺陷对照表迁入（不常驻加载）；code-conventions 148→92 行纯规则 - doc-conventions 149→120：总纲收一行、论证段压括注、骨架与生命周期条款表格全保 - 规则名全保（两入口铁规/文档同步闸/MC 触发细则等外部按名引用零断链，已全仓扫描核实） - 机械闸：七文件≤150 ✓ IMPORTANT=0 ✓ 日期残留=0 ✓ 主文件叙事残留=0 ✓ 熵增闸 PASS ✓ doc 两闸零波及 ✓ - 行为验证：全新上下文子代理六问导航 6/6 正确（新增流程/像素面全命中） --- CLAUDE.md | 153 +++++++-------------------- design/dev/code-conventions-cases.md | 55 ++++++++++ design/dev/code-conventions.md | 94 ++++------------ design/dev/doc-conventions.md | 131 +++++++++-------------- design/dev/process-conventions.md | 86 +++++++++++++++ 5 files changed, 251 insertions(+), 268 deletions(-) create mode 100644 design/dev/code-conventions-cases.md create mode 100644 design/dev/process-conventions.md diff --git a/CLAUDE.md b/CLAUDE.md index d1265348..5c36eaea 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -3,138 +3,65 @@ 扫雷推理层 + 自动战斗结算的两段式回合 Roguelike。个人开发，MVP 优先管线。 设计入口：`design/gdd/02-系统清单.md`（根索引）· 概念：`design/gdd/00-游戏概念.md` -> 本文件只保留全局元信息与硬性红线；一切领域细则在子文档，动手前先查「规范导航」。 +> 本文件只保留全局元信息与硬性红线索引；领域细则在子文档，动手前先查「规范导航」。 ## Technology Stack -- **Engine**: Godot 4.7.2 · **Language**: GDScript · **Build**: SCons（engine）+ Godot Export Templates · **资源管线**: Godot Import System + 自定义 resource pipeline -- **Godot 可执行文件（本机固定路径）**：`D:\code\godot\Godot_v4.7.2-stable_win64_console.exe`——headless / 命令行一律用 console 版；编辑器版为同目录 `Godot_v4.7.2-stable_win64.exe` +- **Engine**: Godot 4.7.2 · **Language**: GDScript · **Build**: SCons（engine）+ Export Templates · **资源管线**: Godot Import System + 自定义 resource pipeline +- **Godot 本机固定路径**：`D:\code\godot\Godot_v4.7.2-stable_win64_console.exe`（headless/命令行一律 console 版；编辑器版同目录） ## Engine Version Reference @design/dev/engine-reference/godot/VERSION.md -## 运行与验证（垂直切片） +## 运行与验证（工作目录 = 含 project.godot 的切片目录） -工作目录 = 切片目录本身（含 `project.godot` 的那一层）： - -- 冒烟（全量 headless 断言）：`python tools/run_smoke.py`。包装器三闸：退出码＋摘要失败数＋SCRIPT ERROR 扫描——脚本错误不计冒烟失败数，但会静默中断所在函数的剩余断言，读结果必须核对 SCRIPT ERROR 段。底层命令 = `…console.exe --headless --path . --script res://smoke/smoke_all.gd` -- 场景级探针（呈现层回归）：`…console.exe --headless --path . res://smoke/ui_probe.tscn`；另有 `ui_tune_probe.tscn`（调试浮窗，数值调整板在 debug_overlay 内）、`ui_click_probe.tscn`（合成鼠标事件行为探针） -- 调参期批量工具：`--script res://smoke/adventure_monte_carlo.gd`（全冒险期望扫描）· `--script res://smoke/reward_expectation.gd`（奖励获取期望）。通关率/难度类测量一律走全冒险，单关直入口口径已退役 -- 数值验证工具：`python tools/balance_verifier.py`（零强化冒险逐关条件通关率＋止步节点归因＋营地循环爬升战役——采集端 `--script res://smoke/verifier_batch.gd`，报告落 `design/qa/`；元进度换算率标定与曲线调参的自动化评判面）。直入口带判定暂停使用，重锚归曲线调参批 -- 交付前验收 = smoke + 全部场景探针全绿（测试细则见 `design/dev/test-conventions.md`） -- 结构审计闸（熵增闸）：`python tools/repo_structure_audit.py`——顶层目录/根文件/图像白名单/退役路径四查，违例 FAIL；新类别 = 同批修订 CLAUDE.md Project Layout + 脚本白名单，commit 留痕 +- 冒烟：`python tools/run_smoke.py`（三闸：退出码＋摘要失败数＋SCRIPT ERROR 扫描；脚本错误不计失败数但静默中断剩余断言，读结果必核对） +- 场景探针：`…console.exe --headless --path . res://smoke/ui_probe.tscn`（另有 ui_tune_probe / ui_click_probe） +- 调参批量：`--script res://smoke/adventure_monte_carlo.gd`（全冒险期望）· `res://smoke/reward_expectation.gd`（奖励期望）；通关率/难度类测量一律走全冒险 +- 数值验证：`python tools/balance_verifier.py`（采集端 `res://smoke/verifier_batch.gd`，报告落 `design/qa/`） +- 交付前验收 = smoke + 全部场景探针全绿；熵增闸 = `python tools/repo_structure_audit.py`（新类别 = 同批修订 Project Layout+白名单） ## Project Layout -- `design/gdd/` — 现行设计文档树（根索引 `02-系统清单.md`；文档增删必须同步它；`gdd/ux/` 战斗画面与交互规格） +- `design/gdd/` — 现行设计文档树（根索引 `02-系统清单.md`，文档增删必须同步；`gdd/ux/` 战斗画面与交互规格） - `design/registry/` — 跨系统事实登记（entities.yaml 术语与已锁数值、architecture.yaml 架构登记） -- `design/art/` — 美术**纯文档**：定稿规范 md（圣经/清单/提示词卡）+ `references/` 参考池；评估/调研 md 一律 `design/research/`；**不放任何图片** -- `design/dev/` — 工程规范：code-conventions / test-conventions / concept-conventions / doc-conventions / architecture(ADR) / engine-reference -- `design/qa/` — 验证报告 md（balance-verifier/playtest/等价证明；raw 数据归 `sim-data/`）＋QA 呈现产物图（目检预览拼图等） -- `design/research/` — 调研/提案/评估记录/历史验收/执行工单 -- `artwork/` — **在途图像素材唯一工作区**（三层归位：文档归文档/在途图归一处/终稿归游戏）：生图候选批次（每批一目录+每资产一目录+vN 命名）、像素稿、样张渲染、实机截图全在这里；**整目录不入 git——内容永久保留本地、永不提交（md 例外一并取消，.gitignore `artwork/` 强制）**；收口归档 `archive/` -- `game/assets/art/` — 已验收终稿（入包被游戏加载） -- `game/` — 游戏工程本体：代码三件套+`smoke/` 冒烟套件+`tests/` 单元/集成测试 -- `sim-data/` — 机器读数据产物：模拟试玩 CSV/JSON、verifier raw 基线、日志样例输出。**数据件不入 git（.gitignore 强制）——语义=MC 缓存层：最新一份 MC 锚+读数常驻留盘供分析直读，无数值调整禁重跑（细则见硬性红线「测试执行两入口铁规」MC 触发细则）；`iteration_log.md` 模拟批日志同目录留盘不入库。入库例外三件=`README.md`+`analyze.py`+`growth_model.py`（分析工具本体随 git）** -- `tools/` — python 工具脚本本体（验证/审计/像素化/仪表盘/日志分析） -- 根目录运行文件：`active.md`（会话状态唯一状态源——快照+未决面+当前迭代工作记录；状态文件非历史档案，历史归 git，退役规则见 `design/dev/doc-conventions.md` 第 10 节）、`roadmap.md`（里程碑）、`stage.txt`/`review-mode.txt`（运行开关） -- `archive/` — 收口归档 zip（gitignored） +- `design/art/` — 美术纯文档（圣经/清单/提示词卡 + references/）；评估调研归 `design/research/`；不放图片 +- `design/dev/` — 工程规范（五份规约 + architecture(ADR) + engine-reference） +- `design/qa/` — 验证报告 + QA 呈现产物图；`design/research/` — 调研/提案/评估/历史验收 +- `artwork/` — 在途图像素材唯一工作区（文档归文档/在途图归一处/终稿归游戏）；整目录不入 git（.gitignore 强制），收口归档 `archive/` +- `game/assets/art/` — 已验收终稿（入包被游戏加载）；`game/` — 游戏工程本体（代码 + smoke/ 冒烟 + tests/ 单元集成） +- `sim-data/` — 机器读数据产物；数据件不入 git（入库例外 = README+analyze.py+growth_model.py）；MC 锚与读数常驻留盘，无数值调整禁重跑 +- `tools/` — python 工具脚本；`archive/` — 收口归档 zip（gitignored） +- 根目录：`active.md`（会话状态唯一状态源，退役规则见 doc-conventions 第 10 节）、`roadmap.md`（里程碑）、`stage.txt`/`review-mode.txt`（运行开关） ## 规范导航（动手前先查表） | 时机 | 权威文档 | |---|---| -| **写代码 / 改代码前** | `design/dev/code-conventions.md`——结构 / 契约 / 语言 / 数值 / 流程五类硬纪律（含真实反面案例） | -| **写测试 / 改测试前** | `design/dev/test-conventions.md`——探针标配 / 回归断言 / 提交前全量验证 / 验收清单落码规范 | -| **写文档 / 改文档前** | `design/dev/doc-conventions.md`——可读性第一、白话写作、载体分工、用语纪律、结构与骨架、会话记录与文档生命周期 | -| **设计文档的概念切分与互链** | `design/dev/concept-conventions.md`——概念封装建模 / 跨文档引用纪律 / 归档与事实源 | -| 查系统设计 / 增删文档 | `design/gdd/02-系统清单.md`——根索引 + 中文规范名↔英文代号对照表 | +| 批次开工 / 流程纪律 | `design/dev/process-conventions.md`——worktree 铁律、三段开发流程、批次清单、测试两入口与 MC/闸机细则、像素纪律 | +| 写代码 / 改代码前 | `design/dev/code-conventions.md`——结构/契约/语言/数值/流程五类硬纪律（反例库 = 同目录 code-conventions-cases.md） | +| 写测试 / 改测试前 | `design/dev/test-conventions.md`——探针标配 / 回归断言 / 全量验证 / 验收清单落码 | +| 写文档 / 改文档前 | `design/dev/doc-conventions.md`——白话写作 / 载体分工 / 用语 / 结构骨架 / 会话记录与生命周期 | +| 概念切分与互链 | `design/dev/concept-conventions.md`——概念封装 / 跨文档引用 / 归档与事实源 | +| 系统设计 / 增删文档 | `design/gdd/02-系统清单.md`——根索引 + 中文规范名↔英文代号对照 | | 架构与决策记录 | `design/dev/architecture/architecture.md` + 同目录 `adr-*.md` | -| 引擎版本与参考 | `design/dev/engine-reference/godot/`（版本表已在上方 @ 引入） | | 术语、已锁数值 | `design/registry/entities.yaml`——仅 owner 文档可修订，冲突须显式提出 | -| 会话进度记录 | 根目录 `active.md`（状态文件：只记现在，每行当下为真）——快照节（≤10 条）+未决面+当前迭代状态记录；收口先改快照再记账，并删除已完结旧条目；历史归 git、待裁归 06、教训归记忆库；条目用完整白话句子写清结论，能看懂比短重要，详情归权威文档 | -| 工程路线图 | 根目录 `roadmap.md`——里程碑时间线与下一步顺序（批级视图；实时状态看快照节） | +| 会话进度 / 路线图 | 根 `active.md`（状态文件：只记现在，每行当下为真；快照+未决面+滚动条目）· 根 `roadmap.md` | -## 分支纪律（worktree 铁律） +## 硬性红线（勿违反；操作细则在 process-conventions.md 与各规约） -主工作区（本目录，`master` 检出）只作**合并落点与共享状态载体**，一切开发/设计改动不得直接发生在主工作区： - -1. **开工**：每个任务批次先建独立 worktree 分支再动手：`git worktree add ../g-plan2-<任务名> -b <任务分支>`。所有代码/文档/数值改动与验证跑测都在 worktree 内进行（注意：未跟踪文件不会出现在新 worktree，需手工搬运） -2. **收尾**：迭代 loop 批次在验证全绿（冒烟 + 场景探针；冒烟挂迭代开发完成后的出口/入库闸）后，在主工作区 `git merge --no-ff <任务分支>` 落回 master，然后 `git worktree remove` + 删分支；合并前先看 active.md 尾部状态记录，避免与并行会话撞号/漏捎带；收口时按 doc-conventions 第 10 节退役规则删除已完结旧条目（判据=已入库+结论进快照+无未决项指向）。非 loop 批次收口跑闸与否按「测试执行两入口铁规」（见硬性红线）：默认不跑，用户点名或当场问 -3. **豁免面（仅这两处允许主工作区直改）**：根目录 `active.md`（会话收口）与 `.zcode/`（钩子配置）——其余一律走 worktree；主工作区 `git commit` 会被钩子直接拦截 -4. 本铁律由 PreToolUse 钩子 `.zcode/hooks/worktree-guard.sh` 强制兜底；钩子只约束 agent 侧，用户本人手工改动不受限 - -## 三段开发流程 - -一切要做的东西按三段走：**设计 → 写需求卡片 → 实现**。段与段之间不自动流转，每段转进由用户发令；本节只立出入口与铁律，段内细则见规范导航各文档。 - -**第一段·设计**——产出 GDD 文档或 art-bible。 -- 触发：用户提起，或从 `design/gdd/06-待办清单.md` 取出讨论。 -- 会话内进行、用户主导，不可无监管自跑；经用户点头确认心智模型一致后，才允许落文档。 -- 设计完成的唯一判据 = 文档待裁点逐条清零；带未裁点的文档是讨论稿，不得转进下一段。 -- 设计完成不自动进入写卡段；写需求卡片须用户另行发令。 - -**第二段·写需求卡片**——产出需求卡片（实施指导文档，写作规范见用户级技能 req-card）。 -- 触发：设计定稿后由用户发令。**无设计前置的例外**：缺陷修复/工程债/测试基建/重构类工程需求，凭 bug 证据或 06 在册条目直接进入本段；新玩法/新系统/新内容类必须有设计定稿前置。 -- 质量门：卡片必经 grilling 多轮复核，裁决全落、零待裁点才算成立。 -- 登记：卡片入库后必在 `design/gdd/06-待办清单.md` 登记一条（卡片名/文件指针/状态：待编入/已编入/已开工/已入库）——防用户遗忘已写过的卡；卡片入库后按 06 退役规则销号。 -- 编入：卡片加入后续未完成的迭代（roadmap 迭代行）；没有可用迭代时与用户确认开新一轮。 - -**第三段·实现**——产出代码与配置文件，可运行的游戏。 -- 触发：需求卡片永不单独施工，统一由用户指定迭代号触发（=U0 开工令）；执行按 /iter 技能与下方批次工作流标准清单。 -- **设计权威文档（GDD/art-bible 等承载设计决定的文档）在实现批内一律不更新**——文档与用户想法等同对等，任何更新必须经用户同意；实现批只出迭代实现报告（见下方第 12 条文档同步闸）。 -- 收口人闸：实机目检清单＋代拍板追认单登记交用户即完成批内义务；真人检测不阻塞收口、不阻塞后续迭代开工，用户自行安排时间验收。 - -## 批次工作流标准清单 - -每个批次按以下链路执行——本清单主要承载第三段（实现段）与一切被批准批次的执行纪律，三段的出入口与转进规则见上节。本清单是总索引，各步细则散见上文各节与 `design/dev/` 子文档；与任一细则冲突时以细则为准，发现清单本身过时须同批修订。 - -**开工前** -1. **先检索后提问**——动手前先查在册记忆与权威文档，防止把已裁决事项当新问题重问，或重踩已记录的坑 -2. **需求卡片全列备选案**——批需求卡片里每个待拍板点列出全部备选方案与各自代价，交用户裁决，不在需求卡片内自行定夺 -3. **用户发开工令才动手**——需求卡片经用户批准（U0）后方开工 - -**环境与基线** -4. **独立 worktree + 拷导入缓存**——按分支纪律建 worktree；新 worktree 先拷主区 `.godot/` 目录与字体 `.import` 边车文件再跑测试，否则每套测试全量重新导入资源、近似卡死 -5. **改码前定基线三查**——记录改动前的冒烟全绿数目、单元测试套数、现行模拟基线读数是哪份；改完用同一口径对拍，红绿才能归因到本批改动 -6. **涉数值改动先采改前读数**——批次要改游戏数值的，改码前先采「改前」模拟读数（与改后同随机种子配对比较），并写明对拍口径；无数值改动禁跑模拟（触发细则见硬性红线） - -**实施** -7. **新功能必配新测试**——按需求卡片写码，新增玩法/机制必须配套新增测试套件进 `tests/run_all`；没有对应测试的变更不许合并 -8. **验收改动先行声明**——逻辑变更对应的验收变化（模拟基线换代、探针用例增改、旧断言改判）在需求卡片里预先写明，不事后补 - -**收口** -9. **批末四闸全绿才合并**——冒烟 + 单元测试 + 场景探针 + 改前改后读数对拍，四项全绿方可在主工作区合并 -10. **合并后主区全量复跑**——合并本身可能引入冲突或环境差异，落回 master 后再跑一遍全套验证 -11. **会话收口落记**——`active.md` 快照与状态记录更新（含删除已完结旧条目，退役规则见 `design/dev/doc-conventions.md` 第 10 节）；跨会话有效的教训写入记忆库 -12. **文档同步闸**——文档更新时间点分两层：**机械面文档**（roadmap 行换代、registry、active.md 记账、README/工具注）合并/入库前随批更新完毕方算收口；**设计权威文档**（GDD/art-bible 等承载用户设计决定的文档）实现批内一律不更新——文档与用户想法等同，更新必须经用户同意：实现批收口产出**迭代实现报告**（`design/qa/iter-实现报告-<日期>.md`，一个迭代一份，含各卡状态＋代拍板追认单＋**GDD 反哺点节**——实现与设计的差异/缺口逐条列明），反哺点收口时同步登记 `design/gdd/06-待办清单.md`，用户逐点裁决后另批落文（可随批捎带，窗口长短由用户控制）。反哺点未落文期间，相关 GDD 节按 06 登记视为待反哺状态——读该节做新设计/写新卡前先查 06，勿把旧文当现行事实。需求卡片仍必列「关联文档同步面」，同步义务按两层标注（机械面=随批更新；设计面=报告反哺） -13. **实机目检归用户，只登记不阻塞**——真人检测项由 agent 登记进迭代实现报告目检总清单与 07-体验验证清单，登记完毕批内义务即完成；自动化闸全绿即可合并收口，用户自行安排时间验收，结论按 07 清单回流路径回流；禁止把「等用户目检」当作停工理由或任务完成的必要前置 -14. **中间产物吸收即死**——结论先迁入权威文档（GDD/待办清单/路线图），中间文件即删且永不提交（细则见硬性红线「中间产物吸收即死」与 `design/dev/doc-conventions.md` 第 11 节） - -## 硬性红线（勿违反） - -- **worktree 铁律**：主工作区禁止直接改动与提交（细则见「分支纪律」节；并行会话各占 worktree 互不踩踏） -- **测试执行两入口铁规**：测试类执行——冒烟测试、单元测试（tests/run_all）、模拟验证（MC/verifier/调参批量工具）、场景探针等一切跑游戏的验证调用——只有两个触发入口：①**迭代 loop 开发**（冒烟挂迭代开发完成后的出口/入库闸，loop 内过程性验证属开发工作本身）；②**用户主动点名**。除此之外（问答/调研/文档/审查/零散小改等短小会话）一律零测试，不得擅自调用任何测试；确需测试支撑结论时先请示，以静态阅读/推理作答并注明未跑测 - - **MC/verifier 触发细则**：仅在**数值验证场景**触发（改数值前后取证）；normal 档为主、perfect 按需；**无数值改动的会话禁跑 MC**——结构位移类「存档锚」须先向用户请示定性再跑；需求卡片预设步骤的前提消失时（如「带值裁定后重锚」实际未投值）停问勿照字面执行 - - **分级周期口径**：轻闸（run_smoke 全量+ui_input_probe；触碰 presentation 加跑 ui_click_probe+ui_layout_probe）可随变更执行；**重闸=轻闸+probe_gate --click+probe_gate --full（ui_probe/ui_tune_probe/t17_defer_probe/fx_probe 四探针）+render_gate（窗口化渲染闸：shot_probe 七屏样张 A-D 断言+fx_shot/board_shot 取证+棋盘 golden 逐像素）+run_all 单元全套+doc 三闸（gdd_lint/doc_link_audit/doc_term_audit）+熵增闸（repo_structure_audit）**，属**周期执行**——统一在批次收口或固定周检跑，不进每次变更；真人实机目检仍归用户不进自动闸；MC 大扫描按上方 MC 触发细则（无数值改动零跑） -- **闸机轮次纪律**：①【孤立验证先行】任何新代码/新工具/新测试断言，进入全套闸轮换之前，必须先走通最小可运行路径的 standalone 验证（30 秒级：新断言=单独驱动函数直跑；新工具=最小参数全路径试车含产出落盘；新探针=单 .tscn 直跑），禁以全套闸首跑充当新码首验；②【调试期最窄确认】闸机出红→修复→确认只跑出红的最小单元（单探针/单套件/单函数），禁修一处跑全套——全套闸每个里程碑步（波/T 段）出口最多一次，红灯补跑只跑红件；例外：修的若为全部探针/套件共用的共享件（如冒烟包装器、闸机脚本本身），全套即最小充分单元，注记说明即可；③【长批试车】≥2 分钟的跑批（逐位对拍冻结/MC 批/批量模拟）发起前，先用最小参数把工具完整路径（含解析/落盘/写锚全链）跑通一遍再放长批；④【开工坑册扫描】每波/T 段开工前，按要触碰的面扫一遍在册坑（worktree 缓存三件套、--script 模式无 autoload、守卫文本匹配等），5 分钟预防性动作，禁运行期撞坑补课 -- **MC 采集档位细则**：MC 局数按用途四档硬闸（全表见 `sim-data/README.md`「MC 采集档位表」）：**一档·调研**=总量 >40，**只能由用户发起**——需求卡片/计划书/agent 均无权发起，非用户发起一律不构成一档授权；**二档·数值修改验证**=总量 ≤40、每档 ≤20；**三档·小调**=总量 ≤20、每档 ≤10（只测不判）；**四档·微量**=总量 ≤5（sanity 门，零统计判读）。四档仅承接 MC 触发细则的数值验证场景，两入口铁规不变；超档=停机呈报，禁在二/三/四档下带值结论（窗口不足如实挂起）。改前/改后锚同 seed0 配对、改前锚留盘禁补跑；对拍断言零新跑（复验用锚内子集 ≤20）；读数缺陷（零 gameplay/RNG 触碰）禁整套重跑、走事件流重构补算；≥60 局采集先 N=5 pilot 校验字段；二/三/四档会话累计 ≤20 分钟；零数值改动=零 MC -- **中间产物吸收即死**：中间文档（批需求卡片/机检报告/调研审计报告/模拟读数/迭代计划书/目检清单）寿命=迭代寿命——结论先吸收进权威文档、未决项先迁 `design/gdd/06-待办清单.md` 或 roadmap，然后文件即删，且永不提交 git；活文档=唯一事实源，git=变更记录。细则见 `design/dev/doc-conventions.md` 第 11 节 -- **用语红线**：面向用户的一切输出——文档、状态记录（active.md）、报告、清单、对话——禁止自造黑话与代号式命名；判据 = 业内读者没读过项目历史也能一遍看懂，需要作者解释才能懂的词必须展开成完整白话句（三种固定形态、反例全表与正确写法见 `design/dev/doc-conventions.md` 第 4 节） -- **呈报六问铁规**：向用户呈报一切事物——bug、需求、概念设计、提案——一律按六问结构顺序展开，确认后才动手实现：①**What 现状与差异**——现在是什么样（引用文件、行为等事实）+ 要做什么/改什么；②**Why 期望与动机**——目标态是什么样、为什么值得改，含「不做的代价」；③**How 怎么改**——修改路径，有备选案全部列出不私藏；④**Where 影响面**——改动波及哪些系统、文件、流程、既有裁决；⑤**怎么算改对了**——可判定的验收标准，不写模糊话；⑥**不确定的地方**——没把握、需要用户裁决的点，单列收尾不埋正文。**Who/When 不进呈报正文**——谁来执行、什么时候做由用户决定，由 roadmap 与需求卡片承接，呈报里最多一句话带过。**适用范围**——六问结构只用于**首次描述需求、bug 缺陷或相关方案**的呈报；同一方案的后续对答（追问、讨论、细化、执行汇报）不再套用六问结构，除非用户显式要求 -- **真人检测不阻塞**：一切需要真人检测/实机目检/人工验收的事项一律「只登记、不等待」——登记进 07-体验验证清单（或当批实现报告目检总清单）即完成 agent 侧义务；自动化闸全绿即可合并收口，后续迭代照常开工，验收时间由用户自行安排。禁止把等真人检测当作任务阻塞点、停工理由或收口必要条件，也禁止因往期遗留真人检测项而拦截新迭代开工 -- **文件头 = `##` 文档注释 ≤8 行白名单制**：代码文件文件头只许 `##` 文档注释、总行数 ≤8、内容限五类白名单；日期与变更叙事入黑名单；写法权威 = Google Python Style Guide §3.8 + PEP 257（不自造标准）；机器闸 = `tools/audit_file_headers.py`（static_scan S10）。白名单/黑名单全表见 `design/dev/code-conventions.md` §1.4.1 -- **数值单一事实源**：玩法数值只存 `data/tables/`（.tres），经 `ConfigDB` autoload 类型化单点读取；禁止数值字面量与自建 `load()` 表路径 -- **RNG 单点**：禁止 `randomize()` / 自建 RandomNumberGenerator——随机只经 `RngService` 统一流（单盐单计数器+用途标签+全事件日志，ADR-0007 裁丙） -- **Core 层零 UI 依赖**：完整战斗必须可 `--headless --script` 跑通 -- **fail-fast**：数据校验错误一律致命中止，无软回退 -- **spec-AC 一致性**：规约与验收标准不得在同一输入上给出不同答案（所有 GDD 同尺度） -- **评审隔离**：`/design-review` 必须在独立会话跑（与 `/design-system` 隔离） - -## 像素结构件工作纪律 - -1. **先抄后造**:画任何像素结构件前,先从参考素材裁同类结构放大逐像素描述,再实现同款;禁止凭印象/第一性原理发明像素结构(圣经 §8.5 参考核验的执行口径)。 -2. **验收口径写成像素级视觉判据**:开工前把合格标准写成"X 与 Y 同列收尾/无悬空/无突出"式句子;自检放大最差交界处逐行核像素,不只看整板观感。 -3. **±1px 一律坐标推导**:单像素级结构先写坐标推导(哪条线在哪列、谁与谁齐平)留档再写码;禁蒙数试错。 -4. **修复默认附前后对比图+像素审计**,不等用户索要。 +- 主工作区禁止直接改动与提交——一切改动走独立 worktree（豁免：active.md 会话收口、.zcode 钩子配置） +- 测试执行两入口铁规——只有迭代 loop 开发与用户点名两个触发入口；其余会话零测试，需测试支撑先请示并注明未跑测 +- MC/模拟：无数值改动零跑；档位硬闸见 `sim-data/README.md`「MC 采集档位表」，一档只能由用户发起 +- 闸机轮次纪律：新码先孤立验证 → 出红只跑红件最小单元 → 长批先最小参数试车 → 开工扫坑册（process-conventions §6） +- 中间产物吸收即死——结论先吸收进权威文档、未决先迁 06，文件即删且永不提交（doc-conventions 第 11 节） +- 用语红线——一切对用户输出禁自造黑话，需要作者解释的词必须展开成完整白话句（doc-conventions 第 4 节三形态表） +- 呈报六问——What 现状差异 / Why 动机与不做代价 / How 方案与全部备选 / Where 影响面 / 验收判据 / 不确定点单列收尾；Who/When 不进正文；仅首次描述需求/bug/方案适用 +- 真人检测只登记不阻塞——登记进 07 清单/实现报告即完成义务，禁以等目检为停工理由或收口前置 +- 文件头 = `##` 文档注释 ≤8 行白名单制（code-conventions §1.4.1；写法权威 = Google Python Style Guide §3.8 + PEP 257；机器闸 tools/audit_file_headers.py） +- 数值单一事实源——玩法数值只存 `data/tables/`（.tres）经 ConfigDB 单点读取；禁数值字面量与自建 `load()` 表路径 +- RNG 单点——禁 `randomize()`/自建 RandomNumberGenerator，随机只经 `RngService` 统一流（ADR-0007） +- Core 层零 UI 依赖——完整战斗必须可 `--headless --script` 跑通；fail-fast——数据校验错误一律致命中止，无软回退 +- spec-AC 一致性——规约与验收标准不得在同一输入上给出不同答案；评审隔离——`/design-review` 必须独立会话跑（与 `/design-system` 隔离） +- 像素结构件——先抄后造、验收写成像素级判据、±1px 坐标推导（process-conventions 第 7 节） diff --git a/design/dev/code-conventions-cases.md b/design/dev/code-conventions-cases.md new file mode 100644 index 00000000..171cb47f --- /dev/null +++ b/design/dev/code-conventions-cases.md @@ -0,0 +1,55 @@ +# 代码规范反面案例库（code-conventions 配套） + +> 本文件是 `code-conventions.md` 各条规则对应的真实反例，说明每条规则针对什么缺陷；规则本体以规约为准，规约与本文冲突时以规约为准。不随规约常驻加载——写码前不必通读，对某条规则的适用有疑义时再查。 + +## 1.1 上帝对象 + +main.gd 曾长到 ~1100 行——棋盘渲染、HUD、结算日志格式化、四种模态覆盖层、调整板、模拟器、关卡流程全部内联；后拆分为 9 个单一职责单元（views/ + hud_presenter），main 回到 ~430 行组合根。 + +## 1.2 裸函数堆 + +供给控制器曾以裸函数伪代码呈现被否；正式实现按私有组合件 RewardSupplyController 封装。 + +## 1.4 ID 前缀命名 + +ID 前缀是跟随 GDD 文档名的事实约定，从未成文；`config_db`/`rng_service` 无前缀与 A/B/C 系列并存——两套命名并行即规范缺失。 + +## 1.4.1 文件头失守 + +main.gd 头注曾累积 42 行——历次提交各自追加「本批做了什么」而全部闸静默放行；删掉叙事后仍剩 31 行，约 2/3 是对 code-conventions §1.3 与 ADR-0001 的整段复制、场景结构/生命周期机制描述（对规约与代码零新信息）。 + +## 2.1 信号契约缺失（软锁） + +旗动作花完末点 AP 后相位翻 Waiting 但不发 round_end，结算点依赖该事件 → 整局软锁；自动玩家不用旗，冒烟路径覆盖不全没抓住。 + +## 2.2 标识符语义错位 + +窗口选择契约 = 窗口条目位置，UI 却传库存数组句柄——未消耗时二者巧合相等；消耗一件后错位 → 选中件不消耗、邻件被误耗。 + +## 2.3 覆盖层不可达 + +数值调整板已实现，但打开时被不透明的开始覆盖层完全遮住 = "点击无反应"。功能存在 ≠ 功能可达。 + +## 2.4 状态字段语义隐式 + +spawn 把 hero 的 max_hp 设为入参 hero_hp——跨战斗携带 HP 时上限被压扁，恢复点/治疗包的满血守卫全部失效。 + +## 5.3 单尺度校准的关卡灾难 + +可选类 25% 格子配比在单战斗尺度校准（击杀需求 18/54），×"库存关内延续"× 5 张板复合后 = 每关 24.8 件、刀总伤 180 > Boss 130 HP——单尺度合理的参数在关卡尺度坐实灾难。 + +## 5.4 拍板范围外自行发挥 + +清图奖励被自行设计成入库刀，用户纠正为"一次性高额伤害不入库"。 + +## 缺陷-规范对照表 + +| 缺陷 | 现象 | 对应规则 | +|---|---|---| +| UI 抖动 / "第3轮"消失 | 悬停文案换行推挤侧栏，末行被挤出视口 | 1.1 拆分 + 视图定长槽 | +| Boss 战 AP 用完不结算（软锁） | 插旗耗尽末点 AP 后整局冻结 | 2.1 事件发射完整性 | +| 道具使用后不消失 | 选用件留存、邻件被误耗 | 2.2 标识符语义单一 | +| 调整板点击无反应 | 面板已实现但被开始层遮挡 | 2.3 层级规则 + test-conventions §2 | +| 上帝对象 | main.gd ~1100 行 | 1.1–1.3 | +| ID 前缀命名 | 两套命名并存 | 1.4–1.5 | +| 可选类每关 24.8 件 | 速杀退化、囤刀秒 Boss | 5.3 跨尺度推演 | diff --git a/design/dev/code-conventions.md b/design/dev/code-conventions.md index b24be849..3f75a418 100644 --- a/design/dev/code-conventions.md +++ b/design/dev/code-conventions.md @@ -1,7 +1,7 @@ # 代码规范（Dungeon Sweeper） > 约束范围：`game/` 代码同尺度；与 CLAUDE.md「硬性红线」节硬约束（数值表单点 / RNG 封闭流 / Core 零 UI / fail-fast / spec-AC 一致性）并行生效，冲突以用户裁决为准。 -> 分工：本文管结构 / 契约 / 语言 / 数值 / 流程五类；测试的编写与验收纪律见 `design/dev/test-conventions.md`。 +> 分工：本文管结构 / 契约 / 语言 / 数值 / 流程五类；测试的编写与验收见 `design/dev/test-conventions.md`；真实反例库见同目录 `code-conventions-cases.md`（不常驻加载，对规则适用有疑义时查）。 **写任何代码前必须通读本文件。** @@ -10,93 +10,46 @@ ## 1. 结构纪律——高内聚、低耦合 ### 1.1 禁止上帝对象 -一个类只承载一个职责。场景主脚本（main）= **组合根**：模式流转、信号接线、核心写调用的唯一出口； -渲染、文案拼装、状态装配一律拆分为独立视图/装配器类。单文件超过 ~400 行即触发审视。 - -> 反例：main.gd 曾长到 ~1100 行——棋盘渲染、HUD、结算日志格式化、四种模态覆盖层、调整板、 -> 模拟器、关卡流程全部内联；后拆分为 9 个单一职责单元（views/ + hud_presenter），main 回到 ~430 行组合根。 +一个类只承载一个职责。场景主脚本（main）= **组合根**：模式流转、信号接线、核心写调用的唯一出口；渲染、文案拼装、状态装配一律拆分为独立视图/装配器类。单文件超过 ~400 行即触发审视。 ### 1.2 一切功能以类封装，禁止裸函数堆 -设计稿与实现同尺度：功能 = 类（状态 + 行为 + 信号），类是封装的最小交付单位。 -工具性纯函数只允许挂在明确的宿主类下（静态装配器/工厂），不允许无主散落。 - -> 反例：供给控制器曾以裸函数伪代码呈现被否；正式实现按私有组合件 RewardSupplyController 封装。 +设计稿与实现同尺度：功能 = 类（状态 + 行为 + 信号），类是封装的最小交付单位。工具性纯函数只允许挂在明确的宿主类下（静态装配器/工厂），不允许无主散落。 ### 1.3 依赖单向，核心写调用收口 -依赖方向唯一：`views →（信号）→ 组合根 →（写调用）→ core`。 -视图零核心写调用（纯 setter / 信号外发优先）；"读核心状态 → 拼展示文案"集中于装配器（presenter）； -核心写接口（settle_batch / submit_window_selection / runner 推进）只允许在组合根出现。 +依赖方向唯一：`views →（信号）→ 组合根 →（写调用）→ core`。视图零核心写调用（纯 setter / 信号外发优先）；"读核心状态 → 拼展示文案"集中于装配器（presenter）；核心写接口（settle_batch / submit_window_selection / runner 推进）只允许在组合根出现。 ### 1.4 命名 = 领域命名，禁止系统 ID 前缀 -文件名与类名禁止 `a1_`/`b1_`/`c1_` 等系统 ID 前缀（`a1_board_generator.gd` → `board_generator.gd`）。 -设计追溯不靠前缀：每个核心实现文件头注必须带一行 -`# 实现 GDD：design/gdd/systems/<循环>/<系统文档>.md（系统 ID Xn）`；系统 ID 只作为文档与 registry 的追溯锚。 -豁免：D2 schema 类与 autoload（本就领域命名）；文档/夹具登记名（如 b4_golden）属文档层。 - -> 反例：ID 前缀是跟随 GDD 文档名的事实约定，从未成文；`config_db`/`rng_service` 无前缀与 A/B/C 系列 -> 并存——两套命名并行即规范缺失。 +文件名与类名禁止 `a1_`/`b1_`/`c1_` 等系统 ID 前缀（`a1_board_generator.gd` → `board_generator.gd`）。设计追溯不靠前缀：每个核心实现文件头注必须带一行 `# 实现 GDD：design/gdd/systems/<循环>/<系统文档>.md（系统 ID Xn）`；系统 ID 只作为文档与 registry 的追溯锚。豁免：D2 schema 类与 autoload；文档/夹具登记名（如 b4_golden）属文档层。 ### 1.4.1 文件头 = `##` 文档注释，≤8 行，白名单制 -文件头注释只用 `##` 文档注释（Godot 官方载体，进编辑器 F1 帮助），总行数 ≤8 行（不含空行， -从文件首个非空行到首个非注释代码行）。写法权威 = Google Python Style Guide §3.8 + PEP 257 -（GDScript 官方风格指南对文件头零条款，GDScript 语法近 Python，沿用其规范——不自造标准）。 +文件头注释只用 `##` 文档注释（Godot 官方载体，进编辑器 F1 帮助），总行数 ≤8 行（不含空行，从文件首个非空行到首个非注释代码行）。写法权威 = Google Python Style Guide §3.8 + PEP 257（GDScript 官方风格指南对文件头零条款，语法近 Python，沿用其规范——不自造标准）。 -白名单（只许写这五类，超出一类即违规）： -1. 一行职责摘要——这是什么； -2. 用途/验证问题一行——它为什么存在； -3. GDD 锚行（§1.4 格式）； -4. 硬使用约束——使用本文件前必须知道的禁令，每条一行； -5. 指路行——架构文档/ADR/契约文档的位置。 +白名单（只许五类，超出一类即违规）：①一行职责摘要——这是什么；②用途/验证问题一行——它为什么存在；③GDD 锚行（§1.4 格式）；④硬使用约束——使用本文件前必须知道的禁令，每条一行；⑤指路行——架构文档/ADR/契约文档的位置。 -黑名单（出现即违规）： -- 日期与变更叙事：任何日期、「XX批/T几/迭代N 做了什么」、迁移/改名/退役经过—— - 改动史查 `git log`/`git blame`，变更背景读对应迭代实现报告； -- 与 code-conventions、ADR、架构文档重复的段落——规范与架构各有唯一权威文档，文件头只指路不复制； -- 场景结构、生命周期等代码机制描述——"Never describe the code"（pyguide §3.8.5），读者读代码或架构文档。 +黑名单（出现即违规）：日期与变更叙事——改动史查 `git log`/`git blame`，变更背景读对应迭代实现报告；与 code-conventions、ADR、架构文档重复的段落——规范与架构各有唯一权威文档，文件头只指路不复制；场景结构、生命周期等代码机制描述——"Never describe the code"（pyguide §3.8.5）。 -机器闸：`tools/audit_file_headers.py`（static_scan S10：行数上限 + 黑名单机械可判子集； -信号契约成文位置见 §2.1）。存量头注按白名单清偿后挂入收口闸序列；此间新增/改动的文件头必须即合规。 - -> 反例：main.gd 头注曾累积 42 行——历次提交各自追加「本批做了什么」而全部闸静默放行；删掉叙事后 -> 仍剩 31 行，约 2/3 是对 code-conventions §1.3 与 ADR-0001 的整段复制、场景结构/生命周期机制描述 -> （对规约与代码零新信息）。全仓头注按白名单重写，机制事实归 design/dev/architecture。 +机器闸：`tools/audit_file_headers.py`（static_scan S10：行数上限+黑名单机械可判子集；信号契约成文位置见 §2.1）。存量头注按白名单清偿后挂入收口闸序列；此间新增/改动的文件头必须即合规。 ### 1.5 禁止事实约定 -任何"大家默认这么做"的惯例必须成文进本文件（或 CLAUDE.md）才算存在。 -写代码时发现未成文但必须遵守的约定 → 当场补条文，不许靠惯性延续。 +任何"大家默认这么做"的惯例必须成文进本文件（或 CLAUDE.md）才算存在。写代码时发现未成文但必须遵守的约定 → 当场补条文，不许靠惯性延续。 --- ## 2. 契约纪律——跨层/跨类调用的语义 ### 2.1 信号与事件契约成文 -每个跨类信号：参数语义、发送时点、消费方依赖，必须在发送方 `##` 文档注释成文，每信号一行 -（参照 A2 三事件面先例）；计入 §1.4.1 的 8 行上限，塞不下时迁契约文档并在文件头留指路行。 -状态机的每次迁移路径都必须发出对应事件——**缺一条路径的事件 = 消费方永久等待 = 软锁**。 - -> 反例：旗动作花完末点 AP 后相位翻 Waiting 但不发 round_end，结算点依赖该事件 → 整局软锁； -> 自动玩家不用旗，冒烟路径覆盖不全没抓住。 +每个跨类信号：参数语义、发送时点、消费方依赖，必须在发送方 `##` 文档注释成文，每信号一行；计入 §1.4.1 的 8 行上限，塞不下时迁契约文档并在文件头留指路行。状态机的每次迁移路径都必须发出对应事件——**缺一条路径的事件 = 消费方永久等待 = 软锁**。 ### 2.2 跨层标识符语义单一且成文 -位置（index）/ 句柄（handle）/ 键（key）是三种不同的东西。跨类传递标识符时， -传递方的语义必须与接收方契约逐字一致，禁止凭"当前恰好相等"传值。 - -> 反例：窗口选择契约 = 窗口条目位置，UI 却传库存数组句柄——未消耗时二者巧合相等； -> 消耗一件后错位 → 选中件不消耗、邻件被误耗。 +位置（index）/ 句柄（handle）/ 键（key）是三种不同的东西。跨类传递标识符时，传递方的语义必须与接收方契约逐字一致，禁止凭"当前恰好相等"传值。 ### 2.3 模态覆盖层层级规则 -覆盖层遮挡关系由场景树加入顺序决定。打开任何模态覆盖层时，必须显式隐藏会遮挡它的全屏层； -新增覆盖层必须登记其在 z 序中的位置，并提供"打开可见性"的场景断言。 - -> 反例：数值调整板已实现，但打开时被不透明的开始覆盖层完全遮住 = "点击无反应"。功能存在 ≠ 功能可达。 +覆盖层遮挡关系由场景树加入顺序决定。打开任何模态覆盖层时，必须显式隐藏会遮挡它的全屏层；新增覆盖层必须登记其在 z 序中的位置，并提供"打开可见性"的场景断言。 ### 2.4 状态字段语义显式 跨战斗/跨场景携带或恢复的状态字段，其语义来源必须显式（表值 / 明确入参），禁止用入参隐式定义。 -> 反例：spawn 把 hero 的 max_hp 设为入参 hero_hp——跨战斗携带 HP 时上限被压扁， -> 恢复点/治疗包的满血守卫全部失效。 - --- ## 3. 测试纪律 @@ -107,37 +60,28 @@ ## 4. 语言纪律——GDScript 4.x 实战坑（本项目踩实） -1. **多行 lambda 内禁止嵌套 match / 复杂控制流**（解析不可靠，报"Expected expression for match - pattern"）——信号处理体一律抽成命名方法 + `bind` 传状态。 +1. **多行 lambda 内禁止嵌套 match / 复杂控制流**（解析不可靠）——信号处理体一律抽成命名方法 + `bind` 传状态。 2. **Dictionary 取值返回 Variant，无类型推断**——参与算术或传参前显式声明类型（`var x: float = ...`）。 3. **RichTextLabel：`append_text()` 不回写 `text` 属性**——读可见文本用 `get_parsed_text()`。 4. **lambda 捕获循环变量按创建时值**——循环内先落地局部变量再捕获，或用 `bind`。 -5. **重命名脚本必须同步 `.uid` 文件**（资源身份稳定）；新增 `class_name` 后必须跑一次编辑器扫描 - 刷新全局类缓存，否则 `--headless --script` 模式解析失败。 -6. **`print` 格式占位符与实参类型必须匹配**（`%d` 配 String = 静默输出字面量）——工具输出错 - 等于没有输出。 +5. **重命名脚本必须同步 `.uid` 文件**；新增 `class_name` 后必须跑一次编辑器扫描刷新全局类缓存，否则 `--headless --script` 模式解析失败。 +6. **`print` 格式占位符与实参类型必须匹配**（`%d` 配 String = 静默输出字面量）。 --- ## 5. 数值与汇报纪律 ### 5.1 数值口径必须显式标注尺度 -任何期望值/均值汇报必须写明口径：**每格 / 每板 / 每战 / 每关**。混用口径 = 误导 -（"可选类 3.32"不加"每板"，会被读成每格期望 >1）。 +任何期望值/均值汇报必须写明口径：**每格 / 每板 / 每战 / 每关**。混用口径 = 误导。 ### 5.2 调参先测量，改后复测 -改任何玩法数值前，先用扫描工具产出基线（通关率/难度类读数走 `balance_verifier.py` 冒险段， -机制类读数走 `reward_expectation.gd` 等）；改完必须复测回填数据。禁止拍脑袋调参。 +改任何玩法数值前，先用扫描工具产出基线（通关率/难度类读数走 `balance_verifier.py` 冒险段，机制类读数走 `reward_expectation.gd` 等）；改完必须复测回填数据。禁止拍脑袋调参。 ### 5.3 数值设计必须跨尺度推演 -在单一尺度校准的数值，必须推演其在更大尺度的复合结果（每战合理 × 关内囤积 = 关卡灾难）。 - -> 反例：可选类 25% 格子配比在单战斗尺度校准（击杀需求 18/54），×"库存关内延续"× 5 张板复合后 -> = 每关 24.8 件、刀总伤 180 > Boss 130 HP——单尺度合理的参数在关卡尺度坐实灾难。 +在单一尺度校准的数值，必须推演其在更大尺度的复合结果（每战合理 × 关内囤积 = 关卡灾难；反例见 code-conventions-cases.md §5.3）。 ### 5.4 用户拍板的实现零发挥 拍板范围外的细节一律不自行补全——以"待办问题"清单列出等裁决。 -（反面案例：清图奖励被自行设计成入库刀，用户纠正为"一次性高额伤害不入库"。） --- diff --git a/design/dev/doc-conventions.md b/design/dev/doc-conventions.md index ea838ab3..639876f4 100644 --- a/design/dev/doc-conventions.md +++ b/design/dev/doc-conventions.md @@ -1,91 +1,78 @@ # 文档写作规范（写文档前必读） -> **地位**：本文是本项目文档写作的规范权威，与 `design/dev/code-conventions.md`（代码规范）对等——写代码前必读代码规范，写文档前必读本文。CLAUDE.md 只保留导航指针，细则以本文为准。 -> **适用范围**：`design/` 下一切现行文档（顶层文档、`systems/` 系统文档、`gdd/ux/`、`design/art/`、`design/research/`）、根目录 `active.md` 会话记录与 `roadmap.md`；概念建模与跨文档引用见 `design/dev/concept-conventions.md`。 +> **地位**：本文是文档写作的规范权威，与 `design/dev/code-conventions.md`（代码规范）对等；CLAUDE.md 只留导航指针，细则以本文为准。 +> **适用范围**：`design/` 下一切现行文档、根目录 `active.md` 与 `roadmap.md`；概念建模与跨文档引用见 `design/dev/concept-conventions.md`。 ## 0. 总纲 -文档是写给人看的：先让人读懂，再谈结构整齐。默认读者没有读过项目历史——可能是半年后的你自己，也可能是未来的协作者。下面所有规则都为这个读者服务。 +默认读者没读过项目历史——可能是半年后的你自己。先让人读懂，再谈结构整齐。 ## 1. 可读性第一（最高纪律） -**读者测试是每个小节的验收标准**：只读这一节，回答三个问题—— +**读者测试是每个小节的验收标准**：只读这一节，回答三个问题——这节管的是谁/什么？在什么情况下？会发生什么？答不出来，就重写这一节，而不是给看不懂的地方补注释。 -1. 这节管的是谁/什么？ -2. 在什么情况下？ -3. 会发生什么？ - -答不出来，就重写这一节，而不是给看不懂的地方补注释。 - -**与旧体系门禁的关系**：旧体系的 lean 格式六条硬规则已停用，仅用于解读 `design/archive/` 里的旧文档（解读时注意其表格占比口径为 30%）。`tools/gdd_lint.py` 现为现行文档机检三闸之一（gdd_lint / doc_link_audit / doc_term_audit——分级周期口径见 CLAUDE.md，对现行文档生效）；可读性仍是第一内容质量门，lint 是格式机检面，两者并行。旧模板文件留档 `.claude/docs/templates/` 备查。 +旧体系 lean 格式六条硬规则已停用，仅用于解读 `design/archive/` 旧文档（其表格占比口径为 30%）。`tools/gdd_lint.py` 现为现行文档机检三闸之一（gdd_lint / doc_link_audit / doc_term_audit，分级周期口径见 CLAUDE.md）；可读性仍是第一内容质量门，lint 是格式机检面，两者并行。旧模板留档 `.claude/docs/templates/`。 ## 2. 白话写作规则 -写文档像向朋友当面解释你的游戏。具体做法： +写文档像向朋友当面解释你的游戏： -1. **完整句子优先**：用完整的句子把话说完；一段只说一件事，长句拆短句。 -2. **禁止碎片笔记体**：正文不得写压缩碎片，不得把 `A→B→C` 箭头链当叙述（流程交给字符画，见第 3 节），不得使用只有作者自己懂的缩略语。 -3. **每节人话开头**：每个小节的第一段先用白话说清"这是什么、为什么需要它"，然后再展开细节。做到只读各节第一段，就能看懂整篇文档的故事线。 -4. **术语首现即解释**：专业术语或项目概念第一次出现时，用一句话（可以用括号）解释它是什么，之后才允许直接使用。玩家会看到的专属名词（如"显影尘"）同样要说清。 -5. **叙述优先于引用**：AC-x、F-x 等编号引用不进正文叙述，只出现在验收标准与附录；正文用直白语言把规则本身说出来。 -6. **反面基准**：数据库条目、会议纪要、只有评审工具能"读懂"的表格堆——都不是我们要的文档。 +1. **完整句子优先**：一段只说一件事，长句拆短句。 +2. **禁止碎片笔记体**：不写压缩碎片，不把 `A→B→C` 箭头链当叙述（流程交给字符画，见第 3 节），不用只有作者自己懂的缩略语。 +3. **每节人话开头**：每小节第一段先用白话说清"这是什么、为什么需要它"；只读各节第一段就能看懂全文故事线。 +4. **术语首现即解释**：专业术语或项目概念首次出现用一句话解释；玩家可见专属名词（如"显影尘"）同样要说清。 +5. **叙述优先于引用**：AC-x、F-x 等编号引用不进正文叙述，只出现在验收标准与附录。 +6. **反面基准**：数据库条目、会议纪要、只有评审工具能"读懂"的表格堆。 ## 3. 表达分工：散文、表格、字符画、公式 -不同内容用不同载体，各司其职： - | 内容 | 载体 | 纪律 | |---|---|---| | 规则的来龙去脉、行为逻辑 | 散文段 | 每段 ≤240 字，一段一件事 | -| 枚举、数值、边界、依赖 | 表格 | 表格只放可列举的事实；禁止把需要解释的内容塞进单元格让读者自己拼 | -| 流程、状态流转 | 字符画（代码块） | 禁止用散文逐步描述流程 | -| 公式 | 结论先行 | 先一行加粗结论，再放公式代码块、变量表与验算表；公式本体必须保留 | -| 体验锚点 | 关键词表 | 支柱/关键词/机制承诺 三列表，禁止长篇情绪描述 | +| 枚举、数值、边界、依赖 | 表格 | 表格只放可列举的事实；禁把需要解释的内容塞进单元格让读者自己拼 | +| 流程、状态流转 | 字符画（代码块） | 禁用散文逐步描述流程 | +| 公式 | 结论先行 | 先一行加粗结论，再放公式代码块、变量表与验算表 | +| 体验锚点 | 关键词表 | 支柱/关键词/机制承诺 三列表，禁长篇情绪描述 | -节点内顺序：先人话，再表格枚举，再字符流程图，最后公式举证。 - -**规则两段式**：核心规则先写"人话阶段"（作用于哪个系统、什么情况下、谁触发、触发后发生什么），再写"举证阶段"（逐效果给出计算方法或公式；纯流程规则明写"无计算"）。规则名禁止纯名词短语（反面例："获取路由"）。 +节点内顺序：先人话，再表格枚举，再字符流程图，最后公式举证。**规则两段式**：先写"人话阶段"（作用于哪个系统、什么情况下、谁触发、触发后发生什么），再写"举证阶段"（逐效果给出计算方法；纯流程规则明写"无计算"）。规则名禁止纯名词短语（反面例："获取路由"）。 ## 4. 用语纪律（见名知意 · 所见即所得 · 禁自造黑话） -**正面总则：见名知意，所见即所得。** 见名知意——用到的每个名字（概念名、术语、文档与目录名）本身就说清它指什么，读者看到名字、不用等解释就知道大概；起不出这样的名字，多半是概念还没想清，先想清再落笔。所见即所得——读者读到的字面意思就是规则的完整意思，不需要追问作者、翻查项目历史或脑补隐含前提才能还原真实含义；有隐含前提就写进句子，有言外之意就写成正文。这两句管的是把话说明白，不是要求把所有信息都塞进本文——该指路的地方仍按第 8 节指路。本节其余禁令说哪些写法不行，这两句说行的是什么。 +**正面总则**：见名知意——每个名字（概念名、术语、文档与目录名）本身就说清所指，起不出这样的名字多半是概念还没想清；所见即所得——字面意思就是规则的完整意思，有隐含前提就写进句子。两句管语义透明，不与第 8 节指路存根冲突。 -文档、评审输出、日志与一切沟通中**禁止自造黑话**——比喻性生造词、只有作者自己懂的缩略语。 +文档、评审输出、日志与一切沟通中**禁止自造黑话**——比喻性生造词、只有作者自己懂的缩略语： - 只能使用：（a）人人可懂的直白语言，或（b）游戏行业通用术语（如 flood fill、战争迷雾、连锁展开、结算、增益/减伤）。 -- 需要指代新概念时，用直白的描述性短语（正例："实测可推理率"——限定语与规范名绑定）。 -- 确需给新概念命名时：首次出现处必须附一句白话定义，并登记 `design/registry` 术语条目——不得让读者猜测比喻含义。 -- 唯一例外：玩家在游戏里也会看到的专属名词（道具名、界面用语，如"显影尘""探巢摆钟"）。文档内部的机制概念不得造词。 +- 指代新概念用直白描述性短语（正例："实测可推理率"）；确需命名时：首现处附一句白话定义，并登记 `design/registry` 术语条目。 +- 唯一例外：玩家在游戏里也会看到的专属名词（道具名、界面用语）。文档内部的机制概念不得造词。 -**自造词的三种固定形态（全部禁止）**——写的时候照着规避，读的时候见到即展开改写： +**自造词的三种固定形态（全部禁止）**： | 形态 | 反例 | 正确写法 | |---|---|---| -| 给工作包起代号 | "样张批""八型批""资产升档重产批" | 叙述名 = 日期 + 做什么，如"按新分辨率规格重做素材" | -| 给机制、检查、基线、区域造名词 | "形象锚""判读口径""暗淡记忆态""变异纹带" | 用行业通用词；确实要长期复用的概念走上面的登记通道（正常名字 + 首现白话定义 + registry 登记） | +| 给工作包起代号 | "样张批""八型批" | 叙述名 = 日期 + 做什么 | +| 给机制、检查、基线、区域造名词 | "形象锚""判读口径""变异纹带" | 用行业通用词；长期复用的概念走登记通道（正常名字+白话定义+registry 登记） | | 给流程步骤造动词 | "收口""落籍""在飞""随批""对拍""销账""正主""台账" | 用日常动词：完成 / 合并进 master / 执行中 / 顺带 / 与基线数据逐项比对 / 注销 / 定义所属的那份文档 / 状态记录 | -**通行检验标准**：读者是业内人士，但没读过本项目的历史。一个词如果需要作者另外解释才能懂，这个词就不合格，包含它的句子必须重写成完整的白话句——换一个新名词不算改，展开才算改。 - -**写后自查**：每写完一条状态记录、一篇文档，重读一遍——凡是自己都要停顿一下才能想起意思的词，一律展开成完整句子。 +**通行检验标准**：读者是业内人但没读过项目历史——需要作者解释才懂的词不合格，必须展开成完整白话句（换新名词不算改，展开才算改）。**写后自查**：凡自己都要停顿才能想起意思的词，一律展开。 ## 5. 结构纪律 | 规则 | 内容 | |---|---| | 树形文档体系 | 全部设计文档构成一棵树；文档增删必须同步根索引 `design/gdd/02-系统清单.md` | -| 一页纸节点 | 一节、一条规则的内容控制在一页纸内（约 ≤80 行）；装不下就拆节，禁止铺开 | -| 一系统一文档 | 每个子系统一份设计文档，不建 analysis 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文 | -| 正文只写现行规则 | 禁止删除线、"（作废）"、"（日期+拍板）"式注记；义务台账、拍板记录等审计信息入 `design/registry` 或附录，不入正文 | -| 后置 ≠ 删除 | P1/P2 后置的内容逐条列出；复活后置项 = 修订文档，禁止静默加回 | +| 一页纸节点 | 一节、一条规则 ≤一页纸（约 ≤80 行）；装不下就拆节 | +| 一系统一文档 | 不建 analysis 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文 | +| 正文只写现行规则 | 禁删除线、"（作废）"、"（日期+拍板）"式注记；审计信息入 `design/registry` 或附录 | +| 后置 ≠ 删除 | P1/P2 后置内容逐条列出；复活后置项 = 修订文档，禁静默加回 | **数值纪律**：正文定规则、取值域、单位；平衡值进 `data/tables/`，provisional 必须标注；已锁数值事实源 = `data/tables/` 与 `design/registry/entities.yaml`。强制收口条款： -1. **双写失同步禁止**——任何数值变更（压缩 / 换装 / 投值 / 区间平移 / 增减行）必须同时同步所有引用该数值的 GDD 表格正文、registry `entities.yaml` 的 `mvp_content` / `value_status`、相关待办清单现状——三类之一未更新即视为该变更**未完成**（反例：数值压缩批只动了 `.tres` 与切片代码，三类文档全部滞后）。 -2. **调参表锁数后删现行值列**——数值已锁定的调参表必须删除「现行值」列，仅保留 schema 模板与取值域，指路存根指向 `data/tables/.tres` 与 `registry/entities.yaml` 对应条目。 -3. **覆盖范围** = 奖励 / 状态 / 敌人 / 技能 / 充能 / 护甲等级 / 区间掷点 / 难度曲线 / D_ref 等所有数值字段。 -4. **维护通道** = 走「设计批 → 同步批」两段式——数值表改完不等于修订完成，须同步收口后方可记入版本历史。 -5. **压缩/换装批** = 一律走「`.tres` 落批 + 切片 smoke 跑通 + GDD 表格指路化 + registry mvp_content 指路化 + 待办清单现状刷新」五步全收才记版本号，缺步则版本号不增。 +1. **双写失同步禁止**——任何数值变更必须同时同步引用该数值的 GDD 表格正文、registry `mvp_content`/`value_status`、相关待办清单现状——三类之一未更新即视为变更未完成。 +2. **调参表锁数后删现行值列**——仅留 schema 模板与取值域，指路存根指向 `.tres` 与 `entities.yaml` 对应条目。 +3. **覆盖范围** = 奖励/状态/敌人/技能/充能/护甲等级/区间掷点/难度曲线/D_ref 等所有数值字段。 +4. **维护通道** = 「设计批 → 同步批」两段式；数值表改完不等于修订完成。 +5. **压缩/换装批** = 「`.tres` 落批 + 切片 smoke 跑通 + GDD 表格指路化 + registry 指路化 + 待办清单刷新」五步全收才记版本号。 ## 6. 文档类型与骨架 @@ -99,51 +86,35 @@ | `03-内容规模.md` | 几个关卡、几种敌人、几种道具——做多少砍多少 | | `04-美术音频方向.md` | 参考图、参考游戏、风格关键词 | | `05-不做清单.md` | 明确写：这些我不要 | -| `06-待办清单.md` | 全项目待办事项的唯一登记处；各系统文档的「待办」节只留指路存根 | +| `06-待办清单.md` | 全项目待办唯一登记处；各系统文档「待办」节只留指路存根 | -**系统文档骨架**（`systems/` 下统一采用）： +**系统文档骨架**（`systems/` 下统一采用）：文首引言（一句话定位+状态+旧版链接）／设计目的（2-4 句白话）／系统范围（负责/不负责两表）／在核心循环中的位置（字符画一行+两句白话）／核心规则（领域章节 ×2–6，每节一页纸）／依赖与输出（表格；引用纪律见 concept-conventions）／P0 最小闭环与 P1·P2 后置／调参表（取值域+provisional 标注）／验收标准（可验证判据）／待办（指路存根）／版本历史（表格）。 -| 章节 | 要求 | -|---|---| -| 文首引言 | 一句话定位 + 状态（已定稿/范围草案/待设计）+ 旧版参考链接 | -| 设计目的 | 2-4 句白话，为什么需要这个系统 | -| 系统范围 | 负责/不负责两张表；表前一段白话说明边界 | -| 在核心循环中的位置 | 处于哪一段、上下游是谁（字符画一行 + 两句白话） | -| 核心规则 | 领域章节 ×2–6，每节一页纸 | -| 依赖与输出 | 上游/下游/对外事件与接口（表格；引用纪律见 `design/dev/concept-conventions.md`） | -| P0 最小闭环 / P1·P2 后置 | MVP 最小集合与后置清单 | -| 调参表 | 参数名/取值域/现行值，provisional 标注 | -| 验收标准 | 可验证的判据 | -| 待办（可选） | 指路存根：条目单点登记 `06-待办清单.md`，本节不再逐条登记 | -| 版本历史 | 表格 | - -**命名**：中文、见名知意（如"游戏概念""棋盘生成"）；禁止 a1_/b1_ 编号前缀；不留纯空目录。正文中指代子系统一律用中文规范名；英文代号（供代码标识符与工具链）对照表见 `design/gdd/02-系统清单.md`，旧代号（a1–d6）仅限解读归档时使用，不得写进现行文档。 +**命名**：中文、见名知意；禁 a1_/b1_ 编号前缀；不留纯空目录。正文指代子系统一律用中文规范名；英文代号对照表见 `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 定性：状态文件——状态记录，不是工作日志。** 根目录 `active.md` 是会话状态的唯一状态源，**每一行当下为真**；历史归 git 提交史。只许写三类：①当前状态快照（≤10 条滚动窗口）；②未决面（进行中批次/待人闸/待裁点指针）；③当前迭代滚动工作条目。禁止写入：已完结批次的历史叙述、待办裁决事项（归 06）、跨会话教训（归记忆库）；并行会话禁止整体复原/回退本文件。退役规则：**用户确认任务完成时清除当前会话写过的状态条目——状态清除即任务完成的证明**；条目完结判据=批次已入库+结论已进快照+未决面无条目指向；迭代收口兜底删除已完结条目，超过 30 条必须清。 -`active.md` 每条进度用完整的白话句子写清结论本身；条目写多长以读者能看懂为准，不设行数上限（能看懂比字数少更重要——行数压缩曾迫使条目使用只有作者自己懂的自造缩略语）。仍然禁止的只有两件：把定稿摘要、义务清单整段搬进条目（详情归各权威文档，状态记录只记结论）；以及自造黑话——第 4 节用语纪律对状态记录同等生效。状态记录条目记裁决结论本身，不记中间文档文件指针（见第 11 节）。 +条目用完整白话句子写清结论本身，长度服从可读性（能看懂比字数少重要）；禁把定稿摘要、义务清单整段搬进条目（详情归权威文档）；第 4 节用语纪律对状态记录同等生效；条目记裁决结论本身，不记中间文档文件指针（见第 11 节）。 ## 11. 文档生命周期：吸收即死 -文档分两类。**活文档**是唯一事实源，长期维护：GDD 树、art-bible 等定稿规范、registry、本规范、`design/gdd/06-待办清单.md`、`roadmap.md`。**中间文档**是脚手架，寿命=迭代寿命，不是项目寿命：批需求卡片、机检/验收过程报告、调研/审计报告、模拟读数、迭代计划书、目检清单。 - -**为什么**：了解游戏看 GDD，了解变更过程看 git 变更记录（commit message 与规范文档的版本历史节）。若每次变更都另存一份增量中间文档，版本管理就没有意义；带种子的模拟逐位可复现，原始数据 dump 是化石不是证据；没有人会读开发中的中间文档来了解游戏。"已归档留底追溯"不成立。 +**活文档**=唯一事实源长期维护：GDD 树、art-bible 等定稿规范、registry、本规范、06-待办清单、roadmap。**中间文档**=脚手架，寿命=迭代寿命：批需求卡片、机检/验收过程报告、调研/审计报告、模拟读数、迭代计划书、目检清单。为什么：了解游戏看 GDD，了解变更看 git；增量中间文档让版本管理失去意义，原始数据 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-实现报告-<日期>.md`，一个迭代一份：各卡状态/代拍板追认单/GDD 反哺点节），属中间文档：GDD 反哺点未决先迁 `06-待办清单.md`，用户裁决落文吸收后按「证据只留最新」退役；替代原每卡出口报告 | -| 证据只留最新 | 测试证据（迭代实现报告/读数/截图/对比图）只保留最新一次迭代或最新一轮同类审计的版本——旧证据无参考作用，测试按状态不按历史；新证据落位后同批删除上一份；等人工检查的清单不受此限，过人闸后按本行退役 | +| 吸收即死 | 中间文档结论写进权威文档（GDD 对应节/art-bible/registry）那一刻，文件即删 | +| 未决先迁再死 | 未决内容先迁现行事实源（06/roadmap 卡/GDD 对应节），然后文档即死 | +| 永不入库 | 迭代出口后中间产物一律删除且不许提交；迭代进行中可暂存工作区，出口批一并清 | +| 引用面口径 | 活文档对中间文档的指路阻塞删除：先改写指路句为结论内联或 git 提交号再删；active.md 状态记录引用不阻塞 | +| 状态记录记结论 | 条目记裁决结论本身不记中间文档指针；中间文档删除后不留死链指针 | +| sim-data 白名单 | 只留 README、日志、分析工具 .py、现行 MC 对拍锚、设计文档 md；可再生原始数据不入库 | +| 出口清理项 | 每迭代出口检查单必含：本迭代中间产物逐份核对（结论已吸收、未决已迁移）后删除 | +| 暂存地非档案库 | `design/research/` 与 `design/qa/` 是中间文档暂存地，入内文件默认到期即死 | +| 迭代实现报告 | 实现批收口的迭代级报告（各卡状态/代拍板追认单/GDD 反哺点节），属中间文档：反哺点未决先迁 06，裁决落文吸收后按「证据只留最新」退役 | +| 证据只留最新 | 测试证据只保留最新一次迭代或最新一轮同类审计版本；新证据落位后同批删上一份；待人清单过人闸后同规退役 | -**删除方式**：按 `design/dev/concept-conventions.md` 第 2 节删除概念 SOP 的口径执行——先查引用面（grep 文件名于上表阻塞域），改写或删除指路句，再删文件，收尾跑死链检查全绿。 +**删除方式**：按 `design/dev/concept-conventions.md` 第 2 节删除概念 SOP 口径——先查引用面（grep 文件名于阻塞域），改写或删除指路句，再删文件，收尾跑死链检查全绿。 diff --git a/design/dev/process-conventions.md b/design/dev/process-conventions.md new file mode 100644 index 00000000..876b8145 --- /dev/null +++ b/design/dev/process-conventions.md @@ -0,0 +1,86 @@ +# 流程规范（Dungeon Sweeper） + +> 约束范围：一切批次的流程纪律——分支与 worktree、三段开发流程、批次工作流、测试执行细则、像素件工作纪律。 +> 分工：硬性红线的一句话索引在 CLAUDE.md「硬性红线」；本文承载其操作细则；批次开工前通读本文。 + +**开工任何批次前必须通读本文。** + +## 1. 分支纪律（worktree 铁律） + +主工作区（master 检出）只作合并落点与共享状态载体，一切开发/设计改动不得直接发生在主工作区： + +1. **开工**：每批次先建独立 worktree：`git worktree add ../g-plan2-<任务名> -b <任务分支>`；所有改动与验证都在 worktree 内进行（未跟踪文件不会出现在新 worktree，需手工搬运） +2. **收尾**：迭代 loop 批次验证全绿（冒烟+场景探针）后在主工作区 `git merge --no-ff <任务分支>`，再 `git worktree remove`+删分支；合并前先看 active.md 尾部状态记录，防并行会话撞号/漏捎带；收口按 doc-conventions 第 10 节退役规则删除已完结条目。非 loop 批次默认收口不跑闸（两入口铁规），用户点名或当场问 +3. **豁免面**：仅根目录 `active.md`（会话收口）与 `.zcode/`（钩子配置）允许主工作区直改；其余一律走 worktree，主工作区 git commit 被钩子拦截 +4. 本铁律由 PreToolUse 钩子 `.zcode/hooks/worktree-guard.sh` 强制兜底；钩子只约束 agent，用户手工改动不受限 + +## 2. 三段开发流程 + +一切要做的东西按三段走：设计 → 写需求卡片 → 实现。段间不自动流转，每段转进由用户发令。 + +| 段 | 产出 | 出入口铁律 | +|---|---|---| +| 一·设计 | GDD 文档或 art-bible | 用户提起或从 `06-待办清单` 取出；会话内进行、用户主导、禁无监管自跑；经用户点头确认心智一致才许落文档；完成判据=待裁点清零，带未裁点的是讨论稿；不自动进写卡段，写卡须用户另行发令 | +| 二·写需求卡片 | 需求卡片（写作规范见用户级技能 req-card） | 设计定稿后用户发令；例外=缺陷修复/工程债/测试基建/重构凭 bug 证据或 06 条目直接进入；新玩法/新系统/新内容必须有设计定稿前置；卡片必经 grilling 多轮复核、零待裁点才成立；入库必在 06 登记一条（防遗忘）；编入后续未完成迭代（roadmap 迭代行），无空位与用户确认开新一轮 | +| 三·实现 | 代码与配置，可运行的游戏 | 需求卡片永不单独施工，统一由用户指定迭代号触发（=U0 开工令），按 /iter 技能与本文 §3 执行；设计权威文档（GDD/art-bible）批内一律不更新，实现批只出迭代实现报告（见 §3 第 12 条）；收口人闸=实机目检清单+代拍板追认单登记交用户即完成批内义务 | + +## 3. 批次工作流标准清单 + +每个批次按以下链路执行（本清单是总索引，细则散见各规约；冲突以细则为准，发现清单过时须同批修订）： + +**开工前** +1. **先检索后提问**——先查在册记忆与权威文档，禁把已裁决事项当新问题重问或重踩在册坑 +2. **需求卡片全列备选案**——每个待拍板点列全部备选方案与代价交用户裁决，禁卡片内自行定夺 +3. **用户发开工令才动手**——需求卡片经用户批准（U0）后方开工 + +**环境与基线** +4. **独立 worktree+拷导入缓存**——按 §1 建 worktree；先拷主区 `.godot/` 目录与字体 `.import` 边车再跑测试，否则全量重导入资源近似卡死 +5. **改码前定基线三查**——记录冒烟全绿数目、单元测试套数、现行模拟基线读数；改完同口径对拍，红绿才能归因到本批 +6. **涉数值改动先采改前读数**——与改后同随机种子配对比较并写明对拍口径；无数值改动禁跑模拟 + +**实施** +7. **新功能必配新测试**——新增玩法/机制必须配套新测试套件进 `tests/run_all`；没有对应测试的变更不许合并 +8. **验收改动先行声明**——验收变化（基线换代/探针增改/旧断言改判）预先写进需求卡片，禁事后补 + +**收口** +9. **批末四闸全绿才合并**——冒烟+单元测试+场景探针+改前改后读数对拍 +10. **合并后主区全量复跑**——合并可能引入冲突或环境差异，落回 master 后再跑全套 +11. **会话收口落记**——active.md 快照与状态记录更新（含删除已完结旧条目，doc-conventions 第 10 节）；跨会话教训写入记忆库 +12. **文档同步闸**——机械面文档（roadmap 行/registry/active.md 记账/README 工具注）合并前随批更新完毕方算收口；设计权威文档批内不更新：实现批收口出迭代实现报告（`design/qa/iter-实现报告-<日期>.md`：各卡状态+代拍板追认单+GDD 反哺点节），反哺点同步登记 `06-待办清单`，用户逐点裁决后另批落文；反哺点未落文期间相关 GDD 节视为待反哺，读前先查 06；需求卡片必列「关联文档同步面」按两层标注 +13. **实机目检归用户，只登记不阻塞**——真人检测项登记进实现报告目检总清单与 07-体验验证清单即完成批内义务；禁把等目检当停工理由或收口前置 +14. **中间产物吸收即死**——细则见 CLAUDE.md 硬性红线与 doc-conventions 第 11 节 + +## 4. 测试执行两入口铁规（细则） + +测试类执行——冒烟、单元测试（tests/run_all）、模拟验证（MC/verifier/调参批量工具）、场景探针等一切跑游戏的验证——只有两个触发入口：①**迭代 loop 开发**（冒烟挂迭代出口/入库闸，loop 内过程性验证属开发工作本身）；②**用户主动点名**。其余会话（问答/调研/文档/审查/零散小改）一律零测试；确需测试支撑结论时先请示，以静态阅读/推理作答并注明未跑测。 + +**MC/verifier 触发细则**：仅在数值验证场景触发（改数值前后取证）；normal 档为主、perfect 按需；**无数值改动的会话禁跑 MC**；结构位移类「存档锚」须先向用户请示定性再跑；需求卡片预设步骤的前提消失时（如「带值裁定后重锚」实际未投值）停问勿照字面执行。 + +**分级周期口径**：轻闸（run_smoke 全量+ui_input_probe；触碰 presentation 加跑 ui_click_probe+ui_layout_probe）可随变更执行；重闸=轻闸+probe_gate --click+probe_gate --full（ui_probe/ui_tune_probe/t17_defer_probe/fx_probe 四探针）+render_gate（窗口化渲染闸：shot_probe 七屏样张 A-D 断言+fx_shot/board_shot 取证+棋盘 golden 逐像素）+run_all 单元全套+doc 三闸（gdd_lint/doc_link_audit/doc_term_audit）+熵增闸（repo_structure_audit）；重闸属周期执行——统一在批次收口或固定周检跑，不进每次变更；真人实机目检归用户不进自动闸。 + +## 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. **修复默认附前后对比图+像素审计**，不等用户索要