diff --git a/docs/GIT-GUIDE-LITE.md b/.claude/refs/GIT-GUIDE-LITE.md similarity index 100% rename from docs/GIT-GUIDE-LITE.md rename to .claude/refs/GIT-GUIDE-LITE.md diff --git a/docs/GIT-GUIDE.md b/.claude/refs/GIT-GUIDE.md similarity index 100% rename from docs/GIT-GUIDE.md rename to .claude/refs/GIT-GUIDE.md diff --git a/docs/development-workflow.md b/.claude/refs/development-workflow.md similarity index 83% rename from docs/development-workflow.md rename to .claude/refs/development-workflow.md index d4fef0b..73931b9 100644 --- a/docs/development-workflow.md +++ b/.claude/refs/development-workflow.md @@ -1,7 +1,7 @@ # 游戏开发工作流 > 本文档定义游戏项目的开发阶段、版本开发流水线、角色职责、产出标准和质量检查规则。 -> 所有开发工作必须遵循此工作流，不可跳过或并行阶段。 +> 版本开发流水线（③-⑧）中各步骤严格按序推进，不可跳过或并行。①②为阶段级前置，仅在阶段开始时执行一次，后续版本迭代中不重复执行。 --- @@ -73,7 +73,7 @@ #### 流程特点 -- **极轻量**：不需要详细的系统设计，不需要执行案，不需要质量门 +- **极轻量**：不需要详细的系统设计，不需要执行案 - **可以反复推翻重来**：草案阶段推翻设计成本最低 - **头脑风暴是核心方法**：通过讨论探索方向，确认后才进入文档产出 @@ -88,6 +88,18 @@ 玩法草案文档产出且开发者确认。进入原型阶段后，草案文档不再修改（除非开发者决定推翻重来）。 +#### 设计文档层级关系 + +草案、设计案、执行案三者的关系： + +| 层级 | 定位 | 比喻 | 特点 | +|------|------|------|------| +| **草案** (concept.md) | 给游戏**定调** | 灵魂 | 回答"这个游戏是什么"，简略但方向明确 | +| **设计案** | 给游戏**定骨架** | 骨架 | 基于草案的原则展开系统设计，定义有哪些系统、系统关系、核心行为 | +| **执行案** | 给游戏**填血肉** | 血肉 | 细化到程序可直接实现的交互规则和行为细节 | + +设计案初始基于草案的原则进行设计。在后续迭代中遇到具体问题时，可以灵活调整或替换草案中的元素——草案是方向指引，不是硬性约束。 + --- ### 原型阶段 @@ -114,7 +126,7 @@ - 增加新的系统验证 - 修改已有系统的行为规则 -每个版本的流水线循环：**③版本设计 → ④执行案 → ⑤程序设计 → ⑥美术产出 → ⑦程序实现 → 同步文档** +每个版本的流水线循环：**③版本设计 → ④执行案 → ⑤程序设计 → ⑥美术产出 → ⑦程序实现 → ⑧版本复盘** ①全局设计在阶段初期集中产出，后续版本可增量补充。②阶段路线图在阶段开始时产出。 @@ -145,18 +157,16 @@ docs/design/prototype/ | ⑤ 程序设计 | 可以用占位方案，不需要生产级架构。重点回答"怎么实现核心行为" | | ⑥ 美术产出 | 允许占位资源、开发者自行处理。能用就行 | | ⑦ 程序实现 | 允许硬编码、允许快速但不优雅的实现。先跑通再说 | -| PM 质量门 | 关注核心行为是否完整描述，不要求面面俱到 | +| ⑧ 版本复盘 | 程序汇报实现偏差，PM协调同步，策划更新执行案 | +| *PM 质量门* | *穿插于④⑤⑥之后，关注核心行为是否完整描述，不要求面面俱到* | -#### 文档同步（每个迭代完成后） +> **原型阶段灵活性**：⑤⑥⑦允许更紧密的交替推进，不必严格串行。例如程序设计时发现需要调整美术需求，可以回退到⑤补充后继续。批量生产阶段恢复严格串行。 -**每个版本迭代完成后，必须同步更新设计案和执行案**，使其与实际实现保持一致： +#### 版本复盘（每个迭代完成后） -1. **实现完成** → 体验验证 -2. **对照实现更新文档** — 设计案和执行案中与实际不符的内容要修正 -3. **更新执行案迭代记录** — 在迭代版本表头中标记状态为 ✅ 已同步 -4. **记录差异** — 如果实现与设计有偏差，记录偏差原因 +每个版本迭代完成后执行⑧版本复盘，具体要求见下方流水线中的⑧定义。 -> **为什么不迭代完就同步？** 文档是下一个迭代的起点。如果文档和实现不一致，下一个迭代的执行案会基于错误的假设，导致更多返工。 +> **为什么每个版本都要复盘？** 文档是下一个迭代的起点。如果文档和实现不一致，下一个迭代的执行案会基于错误的假设，导致更多返工。 #### 阶段退出 @@ -208,11 +218,12 @@ docs/design/production/ | ⑤ 程序设计 | 需要生产级架构，考虑扩展性和数据驱动。美术需求必须具体到尺寸和数量 | | ⑥ 美术产出 | 正式资产，符合风格指南。不允许占位 | | ⑦ 程序实现 | 不允许硬编码，数据应配置化。代码质量需达到发布标准 | -| PM 质量门 | 完整执行所有检查项，逐条对照 | +| ⑧ 版本复盘 | 程序汇报实现偏差，PM协调同步，策划更新执行案。所有差异必须记录 | +| *PM 质量门* | *穿插于④⑤⑥之后，完整执行所有检查项，逐条对照* | -#### 文档同步（每个迭代完成后） +#### 版本复盘（每个迭代完成后） -与原型阶段相同：每个版本迭代完成后必须同步更新设计案和执行案。 +与原型阶段相同：每个版本迭代完成后必须执行⑧版本复盘。批量生产阶段要求所有差异必须记录在案，不可省略。 #### 生产工具 @@ -267,10 +278,16 @@ docs/design/production/ > 本流水线在**原型阶段**和**批量生产阶段**使用。两个阶段使用相同的流水线结构，但严格度和完整性要求不同（详见上方各阶段说明）。 -每个版本的开发按以下流水线**严格顺序推进**： +**阶段级前置**（每个阶段开始时执行一次）： ``` -① 全局设计案 → ② 阶段路线图 → ③ 当前版本设计 → ④ 执行案 +① 全局设计案 → ② 阶段路线图 +``` + +**版本级循环**（每个版本迭代执行一次，严格按序推进）： + +``` +③ 当前版本设计 → ④ 执行案 ↓ [PM 审查：执行案质量门] ↓ @@ -284,18 +301,18 @@ docs/design/production/ ↓ ⑦ 程序实现 ↓ - [文档同步：更新设计案/执行案以匹配实现] + ⑧ 版本复盘 ``` -**每个阶段都是下一阶段的必要前置条件。不可跳过或并行。PM 审查不通过则退回重做，不可进入下一阶段。** +**③-⑧ 每个步骤都是下一步的必要前置条件，不可跳过或并行。PM 审查不通过则退回重做，不可进入下一步。开发者是质量门争议的最终仲裁者。** --- ### ① 全局设计案（策划） -**目的**：定义整个游戏**最终形态**的全景图——有哪些系统、有哪些元素、它们大体上是什么关系。 +**目的**：定义**当前阶段目标形态**的全景图——有哪些系统、有哪些元素、它们大体上是什么关系。 -**范围**：面向游戏的最终完成形态，不是某个版本。 +**范围**：面向当前阶段要达成的目标形态，不是某个版本，也不是游戏的最终完成形态。 **必须包含的内容**： @@ -308,7 +325,7 @@ docs/design/production/ **产出形式**： - 可以有多个文档，按系统或主题拆分 - 必须有一个**索引文档**把所有全局设计文档串联起来 -- 产出位置：`docs/design/<阶段>/`（`prototype/` 或 `production/`） +- 产出位置：`docs/design/<阶段>/`（`prototype/` 或 `production/`）。不同阶段的全局设计案独立维护：原型阶段描述"原型要验证什么"，批量生产阶段描述"完整游戏要做成什么样" **PM 检查要点**： - 是否覆盖了游戏最终形态的所有主要系统？ @@ -349,7 +366,7 @@ docs/design/production/ 1. **版本目标定位**：这个版本要做到什么程度——是最小能跑的原型、功能完整的可玩版本、还是经过打磨的体验版？ 2. **内容范围**：本版本包含哪些内容，每种内容做到什么完成度（占位/初版/正式） 3. **版本验收标准**：怎样算"这个版本做完了"？验收标准必须明确、可检验 -4. **本版本涉及的系统清单**：哪些系统需要在本版本实现（引用执行案） +4. **本版本涉及的系统清单**：哪些系统需要在本版本实现（引用全局设计案中的系统名） **产出形式**：可以是阶段路线图中的详细展开，也可以是独立的版本设计文档。放在 `docs/design/<阶段>/` 目录下。 @@ -452,6 +469,7 @@ docs/design/production/ **判定**： - **通过** → 进入 ⑤ 程序设计 - **不通过** → 退回策划修改，列出具体问题清单 +- **争议** → PM 与策划对判定有分歧时，由开发者最终裁决 **产出**：PM 审查记录（记录在 `docs/plans/review-log.md`） @@ -498,6 +516,7 @@ docs/design/production/ **判定**： - **通过** → 进入 ⑥ 美术产出 - **不通过** → 退回程序修改 +- **争议** → PM 与程序对判定有分歧时，由开发者最终裁决 --- @@ -531,6 +550,11 @@ docs/design/production/ 3. **资产规格**：尺寸、格式等是否符合需求？ 4. **缺失项处理**：未到位资产是否有明确处理方案？ +**判定**： +- **通过** → 进入 ⑦ 程序实现 +- **不通过** → 退回美术补充 +- **争议** → PM 与美术对判定有分歧时，由开发者最终裁决 + --- ### ⑦ 程序实现（程序） @@ -544,24 +568,36 @@ docs/design/production/ | 代码质量 | 允许硬编码、快速实现 | 不允许硬编码，数据配置化，代码达发布标准 | | 验证 | 核心流程跑通即可 | 每个系统独立验证 + 集成验证 | -**实现后必须执行文档同步**：对照实际实现更新设计案和执行案，确保文档与代码一致。 +**实现完成后进入⑧版本复盘**。 --- -## 文档同步流程 +### ⑧ 版本复盘（程序汇报 → PM 协调 → 策划更新） -**每个版本迭代完成后，必须同步更新设计案和执行案**。这是流水线的必要环节，不可跳过。 +**目的**：确保文档与实现一致，为下一个迭代提供准确的起点。 -### 同步步骤 +**触发时机**：程序实现（⑦）完成后。 -1. **体验验证**：实际体验实现结果，确认核心行为是否符合预期 -2. **对照差异**：将实现结果与设计案/执行案对照，找出差异 -3. **更新文档**： - - 设计案：更新与实际不符的系统描述 - - 执行案：更新行为规则以匹配实际实现，在迭代记录中新增一行 +**流程**： + +1. **程序汇报**：程序对照执行案，列出实现中产生的偏差和调整 +2. **PM 协调**：PM 审核偏差清单，判断哪些需要回写文档、哪些是合理的实现优化 +3. **策划更新**：策划根据 PM 的协调结果，更新设计案和执行案 4. **标记状态**：执行案迭代记录中该版本标记为 ✅ 已同步 -### 为什么必须同步 +**必须更新的内容**： +- 设计案中与实际不符的系统描述 +- 执行案中与实际实现不一致的行为规则 +- 执行案迭代记录中新增一行，记录变更 + +**阶段差异**： + +| 维度 | 原型阶段 | 批量生产阶段 | +|------|----------|-------------| +| 偏差记录 | 核心行为的偏差必须记录 | 所有差异必须记录在案 | +| 文档同步 | 核心系统必须同步 | 所有系统必须同步 | + +### 为什么必须复盘 - 文档是下一个迭代的起点。如果文档和实现不一致，下一个迭代会基于错误假设 - PM 的质量门审查基于文档。文档不准确会导致审查无效 @@ -594,7 +630,7 @@ PM 在每次 `/plan` 调用时，先判断宏观阶段，再针对**当前版本 | ⑥ 美术资产是否就位？ | 检查资源需求清单 vs 实际资产 | 所有必需资产已产出或有处理方案 | | **PM 审查**：美术资产验收门 | 需求清单 vs 实际资产逐项对照 | 每项需求都有对应产出 | | ⑦ 程序实现是否完成？ | 检查实际文件 | 实现完成 | -| **文档同步** | 对照实现检查文档是否一致 | 设计案/执行案已同步更新 | +| ⑧ 版本复盘是否完成？ | 检查执行案迭代记录是否 ✅ 已同步 | 策划已根据实现偏差更新文档 | **遇到第一个未通过的即为当前应推进的阶段。** @@ -643,6 +679,13 @@ PM 在每次 `/plan` 调用时，先判断宏观阶段，再针对**当前版本 - [ ] 资产规格是否符合需求？ - [ ] 未到位资产是否有明确的处理方案？ +### 版本复盘标准（对应「⑧版本复盘」） + +- [ ] 程序是否汇报了实现偏差清单？ +- [ ] PM 是否审核了偏差清单并给出协调意见？ +- [ ] 策划是否根据协调结果更新了设计案/执行案？ +- [ ] 执行案迭代记录是否新增一行并标记 ✅ 已同步？ + --- ## 单人独立开发的特殊考量 diff --git a/CLAUDE.md b/CLAUDE.md index 638ec56..2503639 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -83,7 +83,7 @@ Source/ # C++ 源代码 ## Git 规范 -详见 [docs/GIT-GUIDE-LITE.md](docs/GIT-GUIDE-LITE.md)。核心要点： +详见 [.claude/refs/GIT-GUIDE-LITE.md](.claude/refs/GIT-GUIDE-LITE.md)。核心要点： - `main` 永远可玩可编译 - 分支: `feature/` `fix/` `prototype/` `release/`