diff --git a/.claude/commands/plan.md b/.claude/commands/plan.md index a087d8c..5df3939 100644 --- a/.claude/commands/plan.md +++ b/.claude/commands/plan.md @@ -32,6 +32,295 @@ --- +## 版本开发流水线 + +每个版本的开发必须按以下流水线阶段**严格顺序推进**。PM 的核心职责是判断当前版本处于流水线的哪个阶段,并推动进入下一阶段。 + +### 流水线阶段总览 + +``` +① 策划:版本目标案 → ② 策划:系统设定案 → ③ 程序设计 → ④ 美术产出 → ⑤ 程序实现 +``` + +**每个阶段都是下一阶段的必要前置条件**。不可跳过或并行。 + +--- + +### ① 策划:版本目标案(一份) + +**目的**:明确这个版本在整体愿景中的定位——要做什么、做到什么程度、放进去什么内容。 + +**必须回答的问题**: + +1. **版本目标定位**:这个版本是要搭一个功能架子(能跑就行的最小原型),还是做出一个经过一定打磨的能正常运转的系统? +2. **内容范围**: + - **主角**:需要主角吗?临时占位模型(胶囊体/方块人)还是初版正式模型? + - **场景范围**:完整地图还是部分区域?如果是部分,具体哪几个区域? + - **场景搭建方式**:白模(BSP/基础几何体)?网上找免费资源凑?还是出初版正式模型? + - **场景布局**:物体先挨个码放测试,还是已经有布局规划需要按规划摆放? + - **交互物**:需要哪些交互物?全部还是先做几个验证系统? + - **UI**:需要哪些 UI?占位样式还是正式样式? +3. **版本验收标准**:怎样算"这个版本做完了"? + +**产出位置**:`docs/design/vXX-target.md`(如 `docs/design/v01-target.md`) + +**注意**:现有的 `v01-scope.md` 如果已经覆盖了以上内容,可以复用,不必重复产出。PM 需要检查已有文档是否充分回答了上述问题。 + +--- + +### ② 策划:系统设定案(每系统一份) + +**目的**:为每个涉及的系统出详细的**行为规则说明书**——系统"应该表现成什么样",但不涉及技术实现细节。 + +**必须回答的问题**: + +系统设定案需要明确的是**玩家可感知的行为**,而不是底层技术方案。例如: +- 角色移动:能不能跑?能不能蹲?按什么键?横移是侧身走还是转身跑?移动方向相对于什么(摄像机/世界)? +- 摄像机:能否手动旋转?能否拉远推近?角色静止时面朝哪?旋转有没有角度限制? +- 交互触发:多远触发?多个交互物重叠怎么办?交互中能否移动? +- 具体参数数值(速度、距离等)**不需要策划提前确定**,程序先设初始值,后续体验阶段调优。 + +**不需要回答的问题**(这些是程序设计阶段的事): +- 用 UE5 的什么组件实现 +- 代码架构怎么组织 +- 数据用什么格式存储 + +**产出位置**:`docs/design/systems/<系统名>.md` + +**PM 检查要点**: +- 系统设定案是否覆盖了该系统所有"玩家可感知的行为"? +- 是否有模糊地带(比如"移动"没说清横移行为)? +- 是否误入了技术细节(说了用什么 UE5 组件)?如果有,提醒策划聚焦行为层 + +--- + +### ③ 程序设计(每系统一份技术方案) + +**目的**:程序读完策划的系统设定案后,设计 UE5 中的具体实现方案。 + +**必须包含的内容**: + +1. **实现方案**:针对策划的每个行为规则,说明打算如何在 UE5 中实现 + - UE5 有现成功能的 → 说明用哪个功能、如何配置(如 Enhanced Input System、CharacterMovementComponent) + - UE5 没有直接对应的 → 说明自己如何实现,复杂系统需要单独出一份技术文档描述 +2. **类与组件架构**:需要哪些 C++ 类/蓝图?继承关系?组件挂载方式? +3. **数据流**:数据从哪里来(配置表/DataAsset/硬编码)?系统之间如何通信? +4. **美术资源需求清单**:实现这个功能需要哪些美术资源? + - 角色骨骼模型?绑定要求? + - 哪几个动画?每个动画的触发时机和参数? + - 哪几个交互物模型?尺寸参考? + - UI 需要哪些图?图标?背景?尺寸? + +**产出位置**:`docs/technical/<系统名>-tech.md` + +**PM 检查要点**: +- 程序设计是否完整回应了策划的系统设定案中的每条行为规则? +- 美术资源需求是否列得具体(不是"需要一些模型",而是"需要1个冰箱模型,约1.7m高")? + +--- + +### ④ 美术产出 + +**目的**:根据程序输出的美术资源需求清单,产出对应资产。 + +**产出内容**: +1. 美术资产(模型、贴图、UI 图等) +2. **资产清单**:哪个资源在哪个路径,方便程序引用 + +**产出位置**:资产放 `Content/` 对应目录,清单记录在 `docs/art/asset-manifest.md` 或直接在技术方案中更新 + +**当前阶段特殊说明**:v0.1 的美术资产可由开发者直接处理(使用占位模型/免费资源)。后续版本应建立 AI 生成流程(提示词 → 出图 → 出 3D 模型)。 + +--- + +### ⑤ 程序实现 + +**目的**:基于程序设计方案和美术资产,实际编写代码和蓝图。 + +**执行要求**: +- 实现前必须确认 ②③④ 的对应文档已就绪 +- 严格按照程序设计方案执行,如有偏差需记录原因 +- 实现完成后安排体验阶段,收集反馈调整参数 + +--- + +## 执行步骤 + +### 阶段 0:上下文读取 + +1. 读取 `docs/plans/current.md`,了解当前进度 +2. 读取 `docs/plans/roadmap.md`,了解里程碑规划 +3. 扫描 `docs/design/` 已有文档(策划产出) +4. 扫描 `GameConfig/` 已有配置(策划产出) +5. 扫描 `Source/` 和 `Content/` 已有代码/蓝图(程序产出) +6. 扫描 `docs/art/` 已有美术规格(美术产出) +7. 扫描 `docs/technical/` 已有技术方案(程序产出) + +### 阶段 1:流水线阶段判断(仅审查当前版本) + +针对**当前版本**(如 v0.1),判断其处于流水线的哪个阶段: + +**检查清单**(按顺序逐项判断,遇到第一个未通过的即为当前应推进的阶段): + +| 检查项 | 检查方式 | 通过条件 | +|--------|----------|----------| +| ① 版本目标案是否存在且完整? | 检查 `docs/design/vXX-target.md`(或已有的 scope 文档是否覆盖) | 回答了版本定位、内容范围、验收标准 | +| ② 系统设定案是否齐全? | 检查 `docs/design/systems/` 对应文档 | 每个涉及系统的行为规则都已明确,无模糊地带 | +| ③ 程序设计方案是否齐全? | 检查 `docs/technical/` 对应文档 | 每个系统设定案都有对应的技术方案,美术资源需求已列出 | +| ④ 美术资产是否就位? | 检查程序设计中的资源需求清单 vs 实际资产 | 所有必需资产已产出或开发者已确认自行处理 | +| ⑤ 程序实现是否完成? | 检查 `Source/`、`Content/` 中的实际文件 | 流水线 ③④ 产出均已就位,实现工作可启动或已完成 | + +### 阶段 2:任务审查(按角色分类) + +将当前版本的任务按角色分类,标注每项任务在流水线中的位置: + +**按角色列出**: +- **策划任务**:标注对应流水线阶段(①版本目标案 / ②系统设定案) +- **程序任务**:标注对应流水线阶段(③程序设计 / ⑤程序实现) +- **美术任务**:标注对应流水线阶段(④美术产出) + +**阻塞关系判断**: +- 如果当前流水线阶段的前置条件未满足 → 标记为「等待前置」 +- 如果当前阶段有可推进的工作 → 标记为「可启动」 + +### 阶段 3:风险检测 + +1. 设计文档中是否有行为定义模糊的地带(如移动没说清横移方式、摄像机没说能否手动旋转) +2. 是否有隐性依赖未在 current.md 中体现 +3. 是否有范围蔓延风险(版本目标之外的额外内容混入) +4. 策划案是否误入了技术实现细节(应该只描述行为,不描述技术方案) +5. 某角色产出是否成为瓶颈(流水线阻塞在某个阶段) + +### 阶段 4:优先级建议 + +1. 输出具体的下一步建议,**严格遵循流水线顺序** +2. 如果当前版本停留在流水线阶段 ①②(策划阶段),优先推动策划产出 +3. 如果当前版本停留在流水线阶段 ③(程序设计),优先推动程序设计方案 +4. 如果当前版本停留在流水线阶段 ④⑤,推动美术产出或程序实现 +5. 如果在阶段 ①② 发现现有文档不足,建议补齐后再推进下游 +6. 建议一个执行顺序(本次开发 session 该做什么) +7. 单人开发,建议一次只推进流水线中的一个阶段 + +### 阶段 5:互动讨论 + +1. 等待开发者反馈:同意 / 调整 / 追问 +2. 开发者可要求 PM 深入诊断某个方面(见「深入诊断」章节) +3. 根据反馈修正优先级 +4. 讨论结束后,根据确认结果更新 `current.md` 和/或 `roadmap.md` +5. 更新后展示变更内容,等待开发者最终确认 + +--- + +## 输出格式 + +每次 `/plan` 调用后,按以下结构输出: + +```markdown +## 📊 项目状态 + +**当前版本**: vX.X — [版本名称] +**流水线阶段**: ①②③④⑤ 中的哪个阶段 — [一句话描述] +**整体进度**: [已完成/总任务] ([百分比]) + +**各角色进度**: +- 策划: [完成度] — [简要说明] +- 程序: [完成度] — [简要说明] +- 美术: [完成度] — [简要说明] + +## 🔄 流水线检查 + +> 仅审查当前版本 + +| 阶段 | 状态 | 说明 | +|------|------|------| +| ① 版本目标案 | ✅完成 / ⚠️不完整 / ❌缺失 | [具体说明] | +| ② 系统设定案 | ✅完成 / ⚠️有模糊地带 / ❌缺失 | [列出缺失或模糊的系统] | +| ③ 程序设计 | ✅完成 / ⚠️部分完成 / ❌未开始 | [具体说明] | +| ④ 美术产出 | ✅完成 / ⚠️部分完成 / ❌未开始 | [具体说明] | +| ⑤ 程序实现 | ✅完成 / 🔄进行中 / ❌未开始 | [具体说明] | + +## 📋 任务清单(按角色) + +### 策划任务 +- [ ] 任务名 — 阶段①/② — [状态] + +### 程序任务 +- [ ] 任务名 — 阶段③/⑤ — [状态] + +### 美术任务 +- [ ] 任务名 — 阶段④ — [状态] + +## ⚠️ 风险提醒 + +[列出 1-3 个风险点。无风险时显示"当前无明显风险"] + +## 🎯 建议下一步 + +[1-2 个具体建议,附理由,严格遵循流水线顺序] + +--- +(等待开发者反馈或指示) +``` + +--- + +## 深入诊断 + +当开发者要求深入诊断时("帮我诊断一下"、"产出跟得上吗"、"各角色进度均衡吗"),PM 应执行以下分析: + +### 逐角色对比 + +对每个角色做三方对比: + +| 维度 | 说明 | +|------|------| +| **应有产出** | 当前流水线阶段该角色应该交付的内容 | +| **实际产出** | 扫描对应目录后发现的实际文件 | +| **标记进度** | `current.md` 中标记的完成/进行中/待开始状态 | + +### 文档质量检查 + +不仅检查文档是否存在,还要检查文档质量: + +- **版本目标案**:是否完整回答了版本定位、内容范围、验收标准? +- **系统设定案**:是否有行为定义模糊的地带?是否误入了技术细节? +- **程序设计方案**:是否完整回应了系统设定案中的每条行为规则?美术资源需求是否列得具体? + +### 不一致检测 + +- current.md 标记为进行中,但对应目录无实际文件 → 标记为「可能滞后」 +- current.md 标记为待开始,但对应目录已有实际文件 → 标记为「可能需要更新进度」 +- 某角色应有产出但目录为空 → 标记为「产出缺口」 +- 流水线阶段跳跃(下游已开始但上游未完成)→ 标记为「流程违规风险」 + +### 诊断输出格式 + +```markdown +## 🔍 深入诊断 + +### 流水线状态 +- 当前阻塞点: [流水线的哪个阶段没通过] +- 阻塞原因: [具体说明] + +### 策划 +- 应有产出: [列出] +- 实际产出: [列出发现的文件] +- 文档质量: [是否有模糊地带、是否误入技术细节] +- 进度标记: [从 current.md 读取] +- 诊断: [匹配/滞后/超前] — [具体说明] + +### 程序 +(同上格式) + +### 美术 +(同上格式) + +### 综合判断 +[整体诊断结论和建议] +``` + +--- + ## 游戏开发阶段知识 PM 必须理解游戏开发各阶段的特征和应有的交付物,用于诊断产出是否匹配: @@ -57,133 +346,3 @@ PM 必须理解游戏开发各阶段的特征和应有的交付物,用于诊 - 心流重要——建议按「完整做完一个小系统」而非「同时推进多个系统」的方式工作 - 早期验证——越早能跑起来看到东西,越不容易失去动力 - Agent 之间通过文档交接——PM 是信息枢纽 - ---- - -## 执行步骤 - -### 阶段 0:上下文读取 - -1. 读取 `docs/plans/current.md`,了解当前进度 -2. 读取 `docs/plans/roadmap.md`,了解里程碑规划 -3. 扫描 `docs/design/` 已有文档(策划产出) -4. 扫描 `GameConfig/` 已有配置(策划产出) -5. 扫描 `Source/` 和 `Content/` 已有代码/蓝图(程序产出) -6. 扫描 `docs/art/` 已有美术规格(美术产出) - -### 阶段 1:阶段诊断 + 产出匹配 - -1. 基于四个维度评估进度: - - **设计完成度**:策划文档和配置表的完成比例 - - **核心系统完成度**:程序基础系统的实现比例 - - **内容完成度**:场景、数据配置等内容的填充比例 - - **资产完成度**:美术资产的制作比例 -2. 对照当前阶段的应有交付物清单,检查是否有缺失 -3. 如有缺失,标记为风险项 -4. 一句话总结当前状态 - -### 阶段 2:关键路径分析 - -1. 从 current.md 的进行中/待开始任务中识别依赖关系 -2. 标注关键路径上的任务(阻塞其他任务的任务) -3. 标注可延后的任务 -4. 标注等待前置条件的任务 - -### 阶段 3:风险检测 - -1. 检查是否有任务描述过于模糊(缺少验收标准) -2. 检查是否有隐性依赖未在 current.md 中体现 -3. 检查是否有范围蔓延风险 -4. 检查是否有「看似简单但可能很复杂」的陷阱任务 -5. 检查某角色产出是否成为瓶颈 - -### 阶段 4:优先级建议 - -1. 输出具体的下一步建议 -2. 理由基于:关键路径 / 阻塞其他任务 / 尽早验证核心体验 / 风险规避 -3. 建议一个执行顺序(本次开发 session 该做什么) -4. 如果当前有多个并行任务,建议收束到 1-2 个 - -### 阶段 5:互动讨论 - -1. 等待开发者反馈:同意 / 调整 / 追问 -2. 开发者可要求 PM 深入诊断某个方面(见「深入诊断」章节) -3. 根据反馈修正优先级 -4. 讨论结束后,根据确认结果更新 `current.md` 和/或 `roadmap.md` -5. 更新后展示变更内容,等待开发者最终确认 - ---- - -## 输出格式 - -每次 `/plan` 调用后,按以下结构输出: - -```markdown -## 📊 项目状态 - -**当前阶段**: [阶段名称] — [一句话描述] -**整体进度**: [已完成/总任务] ([百分比]) - -**各角色进度**: -- 策划: [完成度] — [简要说明] -- 程序: [完成度] — [简要说明] -- 美术: [完成度] — [简要说明] - -## 🗺️ 关键路径 - -[按依赖顺序列出当前关键路径上的任务] - -## ⚠️ 风险提醒 - -[列出 1-3 个风险点。无风险时显示"当前无明显风险"] - -## 🎯 建议下一步 - -[1-2 个具体建议,附理由] - ---- -(等待开发者反馈或指示) -``` - ---- - -## 深入诊断 - -当开发者要求深入诊断时("帮我诊断一下"、"产出跟得上吗"、"各角色进度均衡吗"),PM 应执行以下分析: - -### 逐角色对比 - -对每个角色做三方对比: - -| 维度 | 说明 | -|------|------| -| **应有产出** | 当前阶段该角色应该交付的内容(来自阶段知识表) | -| **实际产出** | 扫描对应目录后发现的实际文件 | -| **标记进度** | `current.md` 中标记的完成/进行中/待开始状态 | - -### 不一致检测 - -- current.md 标记为进行中,但对应目录无实际文件 → 标记为「可能滞后」 -- current.md 标记为待开始,但对应目录已有实际文件 → 标记为「可能需要更新进度」 -- 某角色应有产出但目录为空 → 标记为「产出缺口」 - -### 诊断输出格式 - -```markdown -## 🔍 深入诊断 - -### 策划 -- 应有产出: [列出] -- 实际产出: [列出发现的文件] -- 进度标记: [从 current.md 读取] -- 诊断: [匹配/滞后/超前] — [具体说明] - -### 程序 -(同上格式) - -### 美术 -(同上格式) - -### 综合判断 -[整体诊断结论和建议] -``` diff --git a/docs/development-workflow.md b/docs/development-workflow.md new file mode 100644 index 0000000..c756542 --- /dev/null +++ b/docs/development-workflow.md @@ -0,0 +1,395 @@ +# 游戏开发工作流 + +> 本文档定义 ChildHood 项目的版本开发流水线、角色职责、产出标准和质量检查规则。 +> 所有开发工作必须遵循此工作流,不可跳过或并行阶段。 + +--- + +## 角色定义 + +| 角色 | 职责 | 产出位置 | PM 如何判断其进度 | +|------|------|----------|-------------------| +| **策划** (Design) | 玩法设计、数值平衡、叙事、系统机制 | `docs/design/`、`GameConfig/` | 扫描 `docs/design/` 和 `GameConfig/` 目录中的文件 | +| **程序** (Dev) | 蓝图/C++、系统实现、技术架构、Bug 修复 | `Source/`、`Content/Blueprints/`、`Content/Data/`、`docs/technical/` | 扫描 `Source/`、`Content/`、`docs/technical/` 目录中的文件 | +| **美术** (Art) | 美术需求分析、资产规格、风格指南、AI 图像 | `docs/art/`、`Content/` | 扫描 `docs/art/` 和 `Content/` 目录中的文件 | +| **PM** | 进度追踪、优先级决策、风险预警、流水线推进、任务依赖梳理 | `docs/plans/` | 不产出设计文档、代码或美术资产 | + +### 协作规则 + +- **策划先行**:设计文档是其他角色的需求源 +- **程序读设计**:实现前必须先读取对应设计文档和配置表 +- **文档即交接**:Agent 之间不直接通信,通过共享文档目录交接 +- **冲突时策划说了算**:玩法/数值/叙事的最终决定权在策划角色 +- **PM 是信息枢纽**:跨角色的信息同步和阻塞排查由 PM 负责 + +### 进度汇报规则 + +- 各 Agent 完成工作后汇报结果,**不自动勾选** `current.md` +- 开发者确认后,由 PM 统一更新进度文档 +- PM 每次调用时主动扫描各目录,验证「汇报的进度」与「实际文件产出」是否一致 + +--- + +## 版本开发流水线 + +每个版本的开发必须按以下流水线**严格顺序推进**: + +``` +① 全局设计案 → ② 版本Roadmap → ③ 当前版本设计文档 → ④ 执行案 + ↓ + [PM 审查:执行案质量门] + ↓ + ⑤ 程序设计 + ↓ + [PM 审查:程序设计质量门] + ↓ + ⑥ 美术产出 + ↓ + [PM 审查:美术资产验收门] + ↓ + ⑦ 程序实现 +``` + +**每个阶段都是下一阶段的必要前置条件。不可跳过或并行。PM 审查不通过则退回重做,不可进入下一阶段。** + +--- + +### ① 全局设计案(策划) + +**目的**:定义整个游戏**最终形态**的全景图——有哪些系统、有哪些元素、它们大体上是什么关系。 + +**范围**:面向游戏的最终完成形态,不是某个版本。 + +**必须包含的内容**: + +1. **系统清单**:游戏最终包含哪些系统(移动、交互、收集、小游戏、时间、NPC、经济、叙事等) +2. **元素清单**:游戏世界中的关键元素(角色、场景区域、收集品分类、NPC等) +3. **系统关系**:各系统之间如何关联和互相影响 +4. **核心玩法循环**:玩家在游戏中做什么、为什么持续玩 +5. **情感目标**:游戏要给玩家带来什么样的体验和情感 + +**产出形式**: +- 可以有多个文档,按系统或主题拆分 +- 必须有一个**索引文档**把所有全局设计文档串联起来 +- 产出位置:`docs/design/` + +**PM 检查要点**: +- 是否覆盖了游戏最终形态的所有主要系统? +- 系统关系是否清晰(谁依赖谁、谁独立)? +- 索引文档是否存在且能串联所有全局设计文档? + +**时间点**:项目初期集中产出,后续版本中可增量补充新系统的全局设计。 + +--- + +### ② 版本Roadmap(PM 主导,策划配合) + +**目的**:根据全局设计案,明确分几个版本推进,每个版本大致做哪些内容。 + +**必须包含的内容**: + +1. **版本列表**:从 v0.1 到 v1.0 有哪些版本 +2. **每个版本的核心目标**:这个版本验证什么、实现什么 +3. **每个版本的范围概述**:大致包含哪些系统和内容 +4. **版本间的递进关系**:为什么先做这些后做那些 +5. **预估时间**:粗略的时间预估(不需要精确到天) + +**产出位置**:`docs/plans/roadmap.md` + +**PM 检查要点**: +- 每个版本的范围是否与全局设计案对齐? +- 版本间是否有清晰的递进逻辑(先核心后扩展)? +- 是否有版本范围过大的风险? + +**时间点**:全局设计案基本成型后产出,随版本推进可调整。 + +--- + +### ③ 当前版本设计文档(策划) + +**目的**:针对最近要做的版本,明确这个版本的目标、范围、需要哪些元素和系统、做到什么程度。 + +**范围**:仅限当前版本,不涉及后续版本。 + +**必须包含的内容**: + +1. **版本目标定位**:这个版本要做到什么程度——是最小能跑的原型、功能完整的可玩版本、还是经过打磨的体验版? +2. **内容范围**:本版本包含哪些内容,每种内容做到什么完成度(占位/初版/正式) +3. **版本验收标准**:怎样算"这个版本做完了"?验收标准必须明确、可检验 +4. **本版本涉及的系统清单**:哪些系统需要在本版本实现(引用执行案) + +> **示例**:一个"场景漫游原型"版本的内容范围可能包括:主角使用占位胶囊体、场景用白盒几何体搭建其中3个区域、交互物先做5个验证核心流程、UI 用占位灰框。验收标准为"能在场景中自由移动并完成5个交互点的完整流程"。 + +**产出位置**:`docs/design/vXX-design.md`(如 `docs/design/v01-design.md`) + +**与执行案的关系**:本文档是"这个版本要做什么"的总纲,执行案是"怎么实现每个系统"的细节。本文档引用执行案。 + +**PM 检查要点**: +- 版本目标定位是否明确? +- 内容范围是否清晰,每种内容的完成度是否定义? +- 验收标准是否明确、可检验? +- 范围是否与 roadmap 中该版本的定义一致? + +--- + +### ④ 执行案(策划) + +**目的**:针对当前版本中的每个系统/元素,写出完整的**交互规则细节**,细到程序照着这个逻辑实现功能。 + +**范围**:仅限当前版本中需要实现的系统。 + +**核心原则**: + +- **只描述行为和规则,不涉及技术实现** +- **必须覆盖所有玩家可感知的行为** +- **不能有模糊地带**——程序拿到执行案后不应有"这没写要怎么做"的疑问 +- **具体参数数值**(速度、距离等)不需要策划提前确定,程序先设初始值,后续体验阶段调优。如果策划有初始建议值可以标注"建议值,可调" + +**必须包含的内容**: + +1. **系统概述**:这个系统做什么、服务于什么体验目标 +2. **完整的行为规则清单**:每个操作的触发条件、触发后表现、结束条件 +3. **状态和状态转换**:系统有哪些状态、什么条件触发状态变化 +4. **边界情况处理**:异常/极端情况下的系统行为(如多个交互物重叠、交互中移动等) +5. **与其他系统的交互**:本系统与其他系统的关联和影响 + +**不应包含的内容**: +- 用什么 UE5 组件实现 +- 代码/蓝图架构怎么组织 +- 数据用什么格式存储(JSON/CSV/DataAsset 等) +- 具体的参数精确值(如推镜 0.5 秒、文案延迟 0.2 秒等调优参数) + +**产出形式**: +- 每个系统一份执行案,按系统拆分 +- 产出位置:`docs/design/systems/<系统名>-execution.md`(如 `docs/design/systems/player-controller-execution.md`) +- 如果某系统的全局设计文档中恰好已经写清了当前版本的执行级细节,可以直接引用,但需确保满足执行案的完整性标准 + +**PM 检查要点**: +- 是否覆盖了该系统所有"玩家可感知的行为"? +- 是否有模糊地带(行为描述含"大概"、"可能"、"看情况"等词)? +- 是否误入了技术细节(说了用什么 UE5 组件、数据格式等)? +- 边界情况是否都处理了(多物体重叠、交互中断、异常状态等)? +- 程序拿到这份文档后,能否不问策划任何问题就实现功能? + +--- + +### PM 审查:执行案质量门 + +**触发时机**:策划完成执行案(④)后,进入程序设计(⑤)之前。 + +**审查人**:PM + +**审查内容**: + +1. **完整性**:是否覆盖了该系统所有玩家可感知的行为?每个操作是否明确了触发条件、触发后表现、结束条件? +2. **清晰性**:是否有模糊地带("大概"、"可能"、"看情况"等词)?行为描述是否无歧义?程序拿到后能否不问策划任何问题就实现功能? +3. **边界情况**:异常/极端情况下的系统行为是否都处理了(多物体重叠、交互中断、异常状态等)? +4. **系统间关联**:与其他系统的关联和影响是否说明? +5. **技术越界检查**:是否误入了技术细节(UE5 组件、数据格式、代码架构)?精确参数值是否标注为"建议值,可调"而非固定值? + +**判定**: +- **通过** → 进入 ⑤ 程序设计 +- **不通过** → 退回策划修改,列出具体问题清单,策划修正后重新提交审查 + +**产出**:PM 审查记录(附在执行案文档末尾或记录在 `docs/plans/review-log.md`) + +--- + +### ⑤ 程序设计(程序) + +**目的**:程序读完策划的执行案后,设计 UE5 中的具体实现方案。 + +**前置条件**:执行案(④)已就绪,且 PM 审查通过。 + +**必须包含的内容**: + +1. **实现方案**:针对执行案中的每条行为规则,说明打算如何在 UE5 中实现 + - UE5 有现成功能的 → 说明用哪个功能、如何配置(如 Enhanced Input System、CharacterMovementComponent) + - UE5 没有直接对应的 → 说明自己如何实现,复杂系统需单独出一份技术文档描述 +2. **类与组件架构**:需要哪些 C++ 类/蓝图?继承关系?组件挂载方式? +3. **数据流**:数据从哪里来(配置表/DataAsset/硬编码)?系统之间如何通信? +4. **美术资源需求清单**:实现这个功能需要哪些美术资源? + - 角色骨骼模型?绑定要求? + - 哪几个动画?每个动画的触发时机和参数? + - 哪几个交互物模型?尺寸参考? + - UI 需要哪些图?图标?背景?尺寸? +5. **技术风险和注意事项**:实现中可能遇到的技术难点 + +**产出位置**:`docs/technical/<系统名>-tech.md` + +**PM 检查要点**: +- 程序设计是否完整回应了执行案中的**每条**行为规则? +- 美术资源需求是否列得具体(不是"需要一些模型",而是"需要1个冰箱模型,约1.7m高")? +- 是否有执行案中的行为规则在技术方案中被遗漏? + +--- + +### PM 审查:程序设计质量门 + +**触发时机**:程序完成技术设计(⑤)后,进入美术产出(⑥)之前。 + +**审查人**:PM + +**审查内容**: + +1. **执行案覆盖度**:程序设计是否完整回应了执行案中的**每条**行为规则?逐条对照,不得有遗漏 +2. **美术资源需求**:需求是否列得具体(不是"需要一些模型",而是"需要1个冰箱模型,约1.7m高")?每个资源的数量、尺寸、触发时机是否明确? +3. **类与组件架构**:C++ 类/蓝图的继承关系和组件挂载方式是否清晰? +4. **数据流**:数据从哪里来?系统之间如何通信?是否明确? +5. **技术风险**:是否识别了实现中可能遇到的技术难点? + +**判定**: +- **通过** → 进入 ⑥ 美术产出 +- **不通过** → 退回程序修改,列出具体问题清单(如遗漏的行为规则、不够具体的美术需求等),程序修正后重新提交审查 + +**产出**:PM 审查记录(附在技术方案文档末尾或记录在 `docs/plans/review-log.md`) + +--- + +### ⑥ 美术产出(美术) + +**目的**:根据程序输出的美术资源需求清单,产出对应资产。 + +**前置条件**:程序设计(⑤)已就绪,且 PM 审查通过。 + +**产出内容**: + +1. **美术资产**(模型、贴图、UI 图等) +2. **资产清单**:哪个资源在哪个路径,方便程序引用 + +**产出位置**: +- 资产放 `Content/` 对应目录 +- 清单记录在 `docs/art/asset-manifest.md` 或直接在技术方案中更新 + +**PM 检查要点**: +- 程序资源需求清单中的每一项是否都有对应的美术产出? +- 资产路径是否记录清晰,程序能找到? + +**当前阶段特殊说明**:v0.1 的美术资产可由开发者直接处理(使用占位模型/免费资源)。后续版本应建立 AI 生成流程(提示词 → 出图 → 出 3D 模型)。 + +--- + +### PM 审查:美术资产验收门 + +**触发时机**:美术完成资产产出(⑥)后,进入程序实现(⑦)之前。 + +**审查人**:PM + +**审查内容**: + +1. **需求覆盖度**:逐项对照程序设计中的美术资源需求清单,每一项是否都有对应的美术产出? +2. **资产到位确认**:资产文件是否已放置在 `Content/` 对应目录?路径是否记录在资产清单中? +3. **资产规格**:模型尺寸、贴图尺寸等是否符合需求清单中的规格要求? +4. **缺失项处理**:如有未到位的资产,是否有明确的处理方案(开发者自行处理/使用占位/延期)? + +**判定**: +- **通过** → 进入 ⑦ 程序实现 +- **不通过** → 退回美术补齐,列出具体缺失项和规格不符项,美术修正后重新提交审查 + +**产出**:PM 审查记录(记录在 `docs/plans/review-log.md`) + +--- + +### ⑦ 程序实现(程序) + +**目的**:基于程序设计方案和美术资产,实际编写代码和蓝图。 + +**前置条件**: +- 执行案(④)已就绪,且 PM 审查通过 +- 程序设计方案(⑤)已就绪,且 PM 审查通过 +- 必需的美术资产(⑥)已就位,且 PM 审查通过(或开发者已确认自行处理占位方案) + +**执行要求**: +- 严格按照程序设计方案执行,如有偏差需记录原因 +- 实现完成后安排体验阶段,收集反馈调整参数 +- 每个系统实现后进行独立验证 + +**产出位置**:`Source/`(C++)、`Content/Blueprints/`(蓝图)、`Content/Data/`(DataAsset) + +--- + +## PM 诊断检查清单 + +PM 在每次 `/plan` 调用时,针对**当前版本**逐项检查流水线状态: + +| 检查项 | 检查方式 | 通过条件 | +|--------|----------|----------| +| ① 全局设计案是否存在且完整? | 检查 `docs/design/` 中的全局设计文档和索引 | 覆盖所有主要系统,有索引串联 | +| ② Roadmap 是否存在? | 检查 `docs/plans/roadmap.md` | 版本列表、每版本目标、递进关系明确 | +| ③ 当前版本设计文档是否完整? | 检查 `docs/design/vXX-design.md` | 回答了版本定位、内容范围、验收标准 | +| ④ 执行案是否齐全? | 检查 `docs/design/systems/` 对应执行案 | 每个涉及系统的行为规则都已明确,无模糊地带,无技术越界 | +| **PM 审查**:执行案质量门 | 对照执行案质量标准逐项检查 | 完整性、清晰性、边界情况、技术越界全部通过 | +| ⑤ 程序设计方案是否齐全? | 检查 `docs/technical/` 对应文档 | 每个执行案都有对应技术方案,美术资源需求已列出 | +| **PM 审查**:程序设计质量门 | 执行案与技术方案逐条对照,检查美术需求 | 行为规则全覆盖,美术需求具体 | +| ⑥ 美术资产是否就位? | 检查程序设计中的资源需求清单 vs 实际资产 | 所有必需资产已产出或开发者已确认自行处理 | +| **PM 审查**:美术资产验收门 | 美术需求清单 vs 实际资产逐项对照 | 每项需求都有对应产出,路径和规格符合 | +| ⑦ 程序实现是否完成? | 检查 `Source/`、`Content/` 中的实际文件 | 上游产出均已就位,实现工作可启动或已完成 | + +**遇到第一个未通过的即为当前应推进的阶段。PM 审查未通过的,退回对应角色修改后重新审查。** + +--- + +## 文档质量检查标准 + +以下标准对应流水线中的三道 PM 质量门。PM 审查时按对应清单逐项检查。 + +### 执行案质量标准(对应「执行案质量门」) + +**完整性检查**: +- [ ] 是否覆盖了该系统所有玩家可感知的行为? +- [ ] 每个操作是否明确了触发条件、触发后表现、结束条件? +- [ ] 边界情况是否都处理了? +- [ ] 与其他系统的关联是否说明? + +**清晰性检查**: +- [ ] 是否有模糊地带("大概"、"可能"、"看情况"等词)? +- [ ] 行为描述是否无歧义(如"移动"是否明确了参考系)? +- [ ] 程序拿到后能否不问策划任何问题就实现功能? + +**边界检查**: +- [ ] 是否误入了技术细节(UE5 组件、数据格式、代码架构)? +- [ ] 精确参数值是否标注为"建议值,可调"而非固定值? + +### 程序设计质量标准(对应「程序设计质量门」) + +- [ ] 是否完整回应了执行案中的**每条**行为规则?(逐条对照) +- [ ] 美术资源需求是否列得具体(尺寸、数量、触发时机)? +- [ ] 类与组件架构是否清晰? +- [ ] 数据流是否明确? +- [ ] 技术风险是否识别? + +### 美术资产验收标准(对应「美术资产验收门」) + +- [ ] 程序资源需求清单中的每一项是否都有对应的美术产出?(逐项对照) +- [ ] 资产文件是否已放置在 `Content/` 对应目录? +- [ ] 资产路径是否记录在资产清单中,程序能找到? +- [ ] 资产规格(模型尺寸、贴图尺寸等)是否符合需求? +- [ ] 未到位资产是否有明确的处理方案? + +--- + +## 游戏开发阶段知识 + +PM 必须理解游戏开发各阶段的特征,用于诊断产出是否匹配: + +| 阶段 | 特征 | 应有交付物 | 工作重点 | +|------|------|-----------|----------| +| **预制作** | 想清楚再动手 | 全局设计案、版本Roadmap、各系统执行案、美术风格指南 | 确保设计充分,避免后期返工 | +| **核心系统制作** | 先跑通最小可玩循环 | 角色控制器、核心交互系统、基础UI框架、白盒场景、占位模型 | 系统能跑起来比做得漂亮重要 | +| **内容填充** | 依赖核心系统稳定 | 场景细节、交互数据配置、正式美术资产、音效 | 核心系统锁定后再大规模填充 | +| **集成联调** | 多系统协同工作 | 系统集成测试记录、Bug列表、性能报告 | 暴露和解决集成问题 | +| **打磨发布** | 不加新功能 | Bug修复记录、平衡性调整、优化报告、构建版本 | 稳定性和品质 | + +**诊断判断**: +- 处于「预制作」但缺少关键设计文档 → 标记风险,建议补齐 +- 处于「核心系统制作」但执行案未完成 → 建议先收尾执行案再写代码 +- 处于「内容填充」但核心系统不稳定 → 建议先修复核心系统 +- 某角色产出明显落后于其他角色 → 标记为瓶颈 + +### 单人独立开发的特殊考量 + +- **无法并行**——同一时间只能做一件事,选择更关键 +- **精力有限**——避免一次性拆分太多并行任务 +- **心流重要**——建议按「完整做完一个小系统」而非「同时推进多个系统」的方式工作 +- **早期验证**——越早能跑起来看到东西,越不容易失去动力 +- **文档交接**——Agent 之间通过文档交接,PM 是信息枢纽 diff --git a/docs/plans/current.md b/docs/plans/current.md index 166bcf7..2e0d1b1 100644 --- a/docs/plans/current.md +++ b/docs/plans/current.md @@ -1,16 +1,19 @@ # 当前进度 -> 最后更新:2026-06-01 +> 最后更新:2026-06-02 > 代理完成工作后汇报结果,由开发者确认后才勾选 ✔ ## 当前里程碑:v0.1 场景漫游与环境交互 ### 进行中 -- [ ] 角色控制器(第三人称移动 + 摄像机) -- [ ] 交互系统实现(检测 + 提示 UI + 文本显示) +> 按优先级排列,建议从上到下依次完成 + +- [ ] 清理模板变体代码(归档 Variant_Combat/Platforming/SideScrolling) +- [ ] 角色控制器(第三人称移动 + 摄像机) ← 关键路径起点 - [ ] v0.1 场景白盒搭建(6个区域) -- [ ] 交互内容数据配置(25+ 观察点 + 10 拾取品) +- [ ] 交互系统实现(检测 + 提示 UI + 文本显示) +- [ ] 交互内容数据配置(25+ 观察点 + 10 拾取品,需策划先建 GameConfig 结构) - [ ] 收集计数系统 ### 待开始 @@ -54,7 +57,6 @@ ### 待产出 -- [ ] `docs/design/scene-world.md` — 场景与世界观详细设计 ✅ 已完成 - [ ] `docs/plans/roadmap.md` 更新 — 路线图更新为 v0.1-v1.0 详细版本规划 - [ ] `docs/design/economy-system.md` — 零花钱经济系统设计(v0.3 前产出即可) - [ ] `docs/design/time-system.md` — 一天时间循环系统设计(v0.3 前产出即可)