From fa430f25844d48b0025b9cd43e12f0bfe990d685 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Sat, 10 Oct 2026 02:08:16 +0800 Subject: [PATCH] =?UTF-8?q?docs(rules):=20=E4=B8=89=E6=AE=B5=E5=BC=80?= =?UTF-8?q?=E5=8F=91=E6=B5=81=E7=A8=8B=E7=AB=8B=E8=A7=84+=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E5=90=8C=E6=AD=A5=E9=97=B8v2=E2=80=94=E2=80=94?= =?UTF-8?q?=E8=AE=BE=E8=AE=A1/=E5=86=99=E5=8D=A1/=E5=AE=9E=E7=8E=B0?= =?UTF-8?q?=E4=B8=89=E6=AE=B5=E5=87=BA=E5=85=A5=E5=8F=A3=EF=BC=882026-10-1?= =?UTF-8?q?0=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 - CLAUDE.md 新增「三段开发流程」节：设计（用户点头心智模型一致才落文档+裁点清零才算完成）→写需求卡片（grilling 多轮复核零待裁+入库必登记 06）→实现（迭代号 U0+设计正主文档批内一律不更新）；批次工作流清单引言同步改指 - CLAUDE.md 批次工作流第 12 条改 v2：机械面文档（roadmap 行/registry/active.md/README/工具注）合并前随批同步不变；GDD/art-bible 等设计正主改走迭代实现报告反哺制——收口出迭代级实现报告（design/qa/iter-实现报告-<日期>.md，含各卡状态+代拍板追认单+GDD 反哺点节），反哺点收口时登记 06，用户逐点裁决后另批落文 - doc-conventions §11 新增「迭代实现报告」行+「证据只留最新」措辞换代+版本历史 v15：实现报告属中间文档，替代原每卡出口报告 背景：武器锻造取证确认「迭代」曾被当作一切批次容器（迭代18卡③设计提案混进迭代通道）致「迭代完成了但游戏里没有」口径错位；用户立规依据=文档与用户想法等同对等，文档修改必须经用户同意，只出报告、同意后再更新。纯文档批零代码零测试（两入口铁规） --- CLAUDE.md | 25 +++++++++++++++++++++++-- design/dev/doc-conventions.md | 4 +++- 2 files changed, 26 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3e1cf664..0d037882 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -63,9 +63,30 @@ 3. **豁免面（仅这两处允许主工作区直改）**：根目录 `active.md`（会话收口）与 `.zcode/`（钩子配置）——其余一律走 worktree；主工作区 `git commit` 会被钩子直接拦截 4. 本铁律由 PreToolUse 钩子 `.zcode/hooks/worktree-guard.sh` 强制兜底；钩子只约束 agent 侧，用户本人手工改动不受限 +## 三段开发流程（2026-10-10 用户立规） + +一切要做的东西按三段走：**设计 → 写需求卡片 → 实现**。段与段之间不自动流转，每段转进由用户发令；本节只立出入口与铁律，段内细则见规范导航各文档。背景：2026-10-10 武器锻造取证确认「迭代」曾被当作一切批次的容器（设计提案混进迭代通道），导致「迭代完成了但游戏里没有」的口径错位——本节为此立规。 + +**第一段·设计**——产出 GDD 文档或 art-bible。 +- 触发：用户提起，或从 `design/gdd/06-待办清单.md` 取出讨论。 +- 会话内进行、用户主导，不可无监管自跑；经用户点头确认心智模型一致后，才允许落文档。 +- 设计完成的唯一判据 = 文档待裁点逐条清零；带未裁点的文档是讨论稿，不得转进下一段。 +- 设计完成不自动进入写卡段；写需求卡片须用户另行发令。 + +**第二段·写需求卡片**——产出需求卡片（实施指导文档，写作规范见用户级技能 req-card）。 +- 触发：设计定稿后由用户发令。**无设计前置的例外**：缺陷修复/工程债/测试基建/重构类工程需求，凭 bug 证据或 06 在册条目直接进入本段；新玩法/新系统/新内容类必须有设计定稿前置。 +- 质量门：卡片必经 grilling 多轮复核，裁决全落、零待裁点才算成立。 +- 登记：卡片入库后必在 `design/gdd/06-待办清单.md` 登记一条（卡片名/文件指针/状态：待编入/已编入/已开工/已落籍）——防用户遗忘已写过的卡；卡片落籍后按 06 退役规则销号。 +- 编入：卡片加入后续未完成的迭代（roadmap 迭代行）；没有可用迭代时与用户确认开新一轮。 + +**第三段·实现**——产出代码与配置文件，可运行的游戏。 +- 触发：需求卡片永不单独施工，统一由用户指定迭代号触发（=U0 开工令）；执行按 /iter 技能与下方批次工作流标准清单。 +- **设计正主文档（GDD/art-bible 等承载设计决定的文档）在实现批内一律不更新**——文档与用户想法等同对等，任何更新必须经用户同意；实现批只出迭代实现报告（见下方第 12 条文档同步闸）。 +- 收口人闸：实机目检清单＋代拍板追认单交用户；后置不阻塞收口，用户验完才算真完。 + ## 批次工作流标准清单（2026-10-06 用户确认固化） -每个开发/设计批次按以下十三条链路执行。本清单是总索引，各步细则散见上文各节与 `design/dev/` 子文档；与任一细则冲突时以细则为准，发现清单本身过时须同批修订。 +每个批次按以下链路执行——本清单主要承载第三段（实现段）与一切被批准批次的执行纪律，三段的出入口与转进规则见上节。本清单是总索引，各步细则散见上文各节与 `design/dev/` 子文档；与任一细则冲突时以细则为准，发现清单本身过时须同批修订。 **开工前** 1. **先检索后提问**——动手前先查在册记忆与正主文档，防止把已裁决事项当新问题重问，或重踩已记录的坑 @@ -85,7 +106,7 @@ 9. **批末四闸全绿才合并**——冒烟 + 单元测试 + 场景探针 + 改前改后读数对拍，四项全绿方可在主工作区合并 10. **合并后主区全量复跑**——合并本身可能引入冲突或环境差异，落回 master 后再跑一遍全套验证 11. **会话收口落记**——`active.md` 快照与工作日志更新（含删除已完结旧条目，退役规则见 `design/dev/doc-conventions.md` §10）；跨会话有效的教训写入记忆库 -12. **文档同步闸（2026-10-09 用户立规）**——需求卡片必列「关联文档同步面」（本批实现影响到的文档清单+每项同步义务）；合并/落籍前同步面所列文档更新完毕方算收口——实现与文档同批进闸，防「迭代更新只改自己段落」造成的跨节语义过期（文档正确性审查批配套约束；写卡规范见用户级技能 taskbook） +12. **文档同步闸 v2（2026-10-10 用户改立，替代 2026-10-09 版）**——文档更新时间点分两层：**机械面文档**（roadmap 行换代、registry、active.md 记账、README/工具注）合并/落籍前随批更新完毕方算收口（原口径不变）；**设计正主文档**（GDD/art-bible 等承载用户设计决定的文档）实现批内一律不更新——文档与用户想法等同，更新必须经用户同意：实现批收口产出**迭代实现报告**（`design/qa/iter-实现报告-<日期>.md`，一个迭代一份，含各卡状态＋代拍板追认单＋**GDD 反哺点节**——实现与设计的差异/缺口逐条列明），反哺点收口时同步登记 `design/gdd/06-待办清单.md`，用户逐点裁决后另批落文（可随批捎带，窗口长短由用户控制）。反哺点未落文期间，相关 GDD 节按 06 登记视为待反哺状态——读该节做新设计/写新卡前先查 06，勿把旧文当现行事实。需求卡片仍必列「关联文档同步面」，同步义务按两层标注（机械面=随批更新；设计面=报告反哺） 13. **实机目检归用户**——真机人闸由用户执行，用户亲口确认才算验收通过 14. **中间产物吸收即死**——结论先迁入正主文档（GDD/待办清单/路线图），中间文件即删且永不提交（细则见硬性红线） diff --git a/design/dev/doc-conventions.md b/design/dev/doc-conventions.md index b4b128d0..744f8c60 100644 --- a/design/dev/doc-conventions.md +++ b/design/dev/doc-conventions.md @@ -181,7 +181,8 @@ | sim-data 白名单 | `sim-data/` 只保留 README、日志、分析工具 .py、现行 MC 对拍锚（显式清单）、设计文档 md；可再生原始数据（runsum/raw jsonl/逐局 CSV/report txt/样例输出）不入库 | | 出口清理项 | 每迭代出口检查单必含清理项：本迭代中间产物逐份核对（结论已吸收、未决已迁移）后删除 | | 暂存地非档案库 | `design/research/` 与 `design/qa/` 是中间文档的暂存地，不是永久档案库；入此两处的文件默认按本节规则到期即死 | -| 证据只留最新（2026-10-09 用户立规） | 测试证据（出口报告/读数/截图/对比图）只保留最新一次迭代或最新一轮同类审计的版本——旧证据无参考作用，测试按状态不按历史；新证据落位后同批删除上一份；等人工检查的清单不受此限，过人闸后按本行退役 | +| 迭代实现报告（2026-10-10 立规，随三段开发流程） | 实现批收口的迭代级报告（`design/qa/iter-实现报告-<日期>.md`，一个迭代一份：各卡状态/代拍板追认单/GDD 反哺点节），属中间文档：GDD 反哺点未决先迁 `06-待办清单.md`，用户裁决落文吸收后按「证据只留最新」退役；替代原每卡出口报告 | +| 证据只留最新（2026-10-09 用户立规） | 测试证据（迭代实现报告/读数/截图/对比图）只保留最新一次迭代或最新一轮同类审计的版本——旧证据无参考作用，测试按状态不按历史；新证据落位后同批删除上一份；等人工检查的清单不受此限，过人闸后按本行退役 | **删除方式**：按第 8 节删除概念 SOP 的口径执行——先查引用面（grep 文件名于上表阻塞域），改写或删除指路句，再删文件，收尾跑死链检查全绿。 @@ -203,3 +204,4 @@ | v12 | 2026-10-09 | §9 摘除 design/archive/gdd-2026-09-14/ 归档列项（目录已删，2026-10-09 用户令旧档引用全量摘除）；旧概念翻译与 registry 改指两条维持 | | v13 | 2026-10-09 | §11 新增「证据只留最新」行（2026-10-09 用户立规——qa 存量清理批随批落文）：测试证据只保留最新迭代/最新一轮审计版本，新证据落位即删上一份；待人清单过闸后同规退役 | | v14 | 2026-10-09 | §1「与旧体系门禁的关系」段与现实对齐（文档正确性审查批·独立复核）——原文「gdd_lint 门禁已停用、现行文档不跑 lint」与现状矛盾：gdd_lint 现为机检三闸之一（与 doc_link_audit/doc_term_audit 并列，分级周期口径见 CLAUDE.md，2026-10-03 起分域批在役）；lean 六条硬规则本身维持停用仅用于解读旧档；「可读性是第一内容质量门」定位不变，lint 定性为格式机检面 | +| v15 | 2026-10-10 | **迭代实现报告条款（2026-10-10 用户立规三段开发流程随批）**：§11 新增「迭代实现报告」行——实现批收口出迭代级一份实现报告（各卡状态/代拍板追认单/GDD 反哺点节），属中间文档，反哺点未决先迁 06、裁决落文后按「证据只留最新」退役，替代原每卡出口报告；「证据只留最新」行措辞同步换代。配套：GDD/art-bible 等设计正主文档实现批内一律不更新（文档更新必须经用户同意），反哺点经用户裁决另批落文——总规见 CLAUDE.md「三段开发流程」节与批次工作流第 12 条 v2 |