merge: 三段开发流程立规+文档同步闸v2（rules-3stage-workflow fa430f2，2026-10-10 用户令）
This commit is contained in:
DKChan committed
commit
b56a7b87fb
2 files changed
+26
-3
No files matched your search
@@ -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<N>-实现报告-<日期>.md`，一个迭代一份，含各卡状态＋代拍板追认单＋**GDD 反哺点节**——实现与设计的差异/缺口逐条列明），反哺点收口时同步登记 `design/gdd/06-待办清单.md`，用户逐点裁决后另批落文（可随批捎带，窗口长短由用户控制）。反哺点未落文期间，相关 GDD 节按 06 登记视为待反哺状态——读该节做新设计/写新卡前先查 06，勿把旧文当现行事实。需求卡片仍必列「关联文档同步面」，同步义务按两层标注（机械面=随批更新；设计面=报告反哺）
|
||||
13. **实机目检归用户**——真机人闸由用户执行，用户亲口确认才算验收通过
|
||||
14. **中间产物吸收即死**——结论先迁入正主文档（GDD/待办清单/路线图），中间文件即删且永不提交（细则见硬性红线）
|
||||
|
||||
|
||||
@@ -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<N>-实现报告-<日期>.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 |
|
||||
Reference in new issue
Block a user