ChildHood/.claude/refs/development-workflow.md

# 游戏开发工作流

> 本文档定义游戏项目的开发阶段、任务管理、角色职责、产出标准和质量检查规则。
> 项目采用 3 阶段开发模型：草图 → 总路线 → 迭代。每个阶段有独立的技能文件管理任务序列。
>
> 项目管理工具当前使用 Gitea。PM 操作详见 `gitea-pm` 技能，通用协作详见 `gitea-collab` 技能。
> 阶段技能文件：
> - `.claude/skills/project-initializer.md` — 项目初始化
> - `.claude/skills/stage-sketch.md` — 草图阶段
> - `.claude/skills/stage-roadmap.md` — 总路线阶段
> - `.claude/skills/stage-iteration.md` — 迭代阶段

---

## 角色定义

| 角色 | 职责 | 产出位置 | PM 如何判断其进度 |
|------|------|----------|-------------------|
| **策划** (Design) | 玩法设计、数值平衡、叙事、系统机制 | `docs/design/`、`GameConfig/` | 扫描 `docs/design/` 和 `GameConfig/` 目录中的文件 |
| **程序** (Dev) | 系统实现、技术架构、Bug 修复 | `Source/`、`Content/`、`docs/technical/` | 扫描对应目录中的文件 |
| **美术** (Art) | 美术需求分析、资产规格、风格指南 | `docs/art/`、`Content/` | 扫描对应目录中的文件 |
| **PM** | 进度管理（3阶段状态机）、任务分配与追踪、开发决策咨询 | **Gitea Issues + Milestones** | 通过 Gitea 读取任务和里程碑 |
| **审查** (Reviewer) | 审查交付物质量、更新 Issue 标签和评论 | Issue 评论 | 通过 `review:pass/fail` 标签 |

### 协作规则

- **策划先行**：设计文档是其他角色的需求源
- **程序读设计**：实现前必须先读取对应设计文档和配置表
- **文档即交接**：Agent 之间不直接通信，通过共享文档目录 + 任务 Issue 评论交接（参见 `gitea-collab` 技能）
- **冲突时用户说了算**：玩法/数值/叙事的最终决定权在用户
- **PM 是进度调度器**：PM 管理进度和任务分配，不做审查
- **审查是子代理**：角色完成工作后启动 game-reviewer 子代理审查，审查结果返回给角色，角色向用户汇报
- **会话启动先调 PM**：每次工作会话开始时，用户先调 PM 执行进度检查，确认当前状态后再进入具体工作
- **用户驱动角色切换**：角色间的工作切换由用户手动触发，PM 不自动指派任务
- **角色任务汇报**：各角色通过项目管理工具在任务 Issue 下评论汇报进度，PM 据此追踪

### 进度汇报规则

- 进度管理唯一真实来源是 **项目管理工具**（当前为 Gitea Issues + Milestones）。具体操作参见 `gitea-pm` / `gitea-collab` 技能
- 各角色完成工作后在对应 Issue 下评论汇报，不更新本地 report 文件
- PM 通过项目管理工具读取任务和评论，给出行动建议
- 角色完成工作后自行启动 game-reviewer 子代理审查，审查通过后 PM 请示用户关闭 Issue
- 任务追踪使用唯一任务 ID（格式：`[角色前缀]-[三位数字]`），对应 Issue 标题前缀
- 审查结果通过 Issue 评论发布

---

## 开发阶段

项目开发分为三个阶段，每个阶段有独立的技能文件管理任务序列。

```
草图阶段 ─── "这个游戏是什么？能不能做？" ─── 概念设计 + 技术可行性
    ↓
总路线阶段 ─── "全面设计蓝图" ─── 9 份设计文档 + 版本路径图
    ↓
迭代阶段 ─── "按版本迭代开发" ─── 插件准备 → 执行案 → 开发 → 整合 → 修复
    ↑                                              ↓
    └──── 迭代完成，有下一个迭代 ←── 迭代完成 ───────┘
```

**阶段转换由 PM 建议但需用户确认**。阶段技能文件定义了每个阶段的任务序列和转换条件。

---

### 草图阶段

**目的**：确定游戏是什么——玩法方向、美术风格、技术可行性。

**关注问题**：这个游戏是什么？为什么要做？做不做得了？

#### 任务序列（2 个任务）

1. **概念设计** (D-XXX) — 策划产出概念草案
2. **技术可行性评估** (P-XXX) — 程序评估技术可行性（依赖概念设计完成）

#### 完成标志

两个任务都关闭 + 草图阶段里程碑下无 open issues → 进入总路线阶段。

#### 详细任务定义

参见 `.claude/skills/stage-sketch.md`。

---

### 总路线阶段

**目的**：建立完整的游戏设计蓝图，规划版本迭代路径。

**关注问题**：游戏长什么样？有哪些系统？分几个版本做？

#### 任务序列（9 个任务）

1. **设计总索引** (D-XXX) — 必须完整
2. **世界观设计** (D-XXX) — 允许占位
3. **剧情设计** (D-XXX) — 允许占位
4. **角色设计** (D-XXX) — 允许占位
5. **系统设计** (D-XXX) — ⚠️ 必须完整
6. **关卡设计** (D-XXX) — ⚠️ 必须完整
7. **UI 设计** (D-XXX) — 允许占位
8. **音频设计** (D-XXX) — 允许占位
9. **版本路径图** (D-XXX) — 必须完整（依赖 2-8）

**占位规则**：除系统设计和关卡设计外，其他文档允许空文件占位（标题+章节+「待填充」），后续迭代完善。

#### 完成标志

所有任务关闭 + 里程碑下无 open issues → 进入迭代阶段。

#### 详细任务定义

参见 `.claude/skills/stage-roadmap.md`。

---

### 迭代阶段

**目的**：按版本迭代推进开发，每个迭代完成一个可玩版本。

**关注问题**：这个版本做什么？做到什么程度？Bug 修了没？

#### 任务序列（每迭代 6-9 个任务）

| 任务 | 角色 | 说明 |
|------|------|------|
| 插件资产检查与准备 | 程序 | 仅首次迭代 |
| 设计案迭代补充 | 策划 | 可选 |
| 策划执行案 | 策划 | 必选 |
| 程序需求分析 | 程序 | 必选 |
| 关卡搭建 | 程序 | 有场景时 |
| 系统开发 | 程序 | 必选 |
| 优化意见 | 程序 | 必选 |
| 资产接入整合 | 程序 | 必选 |
| Bug 修复 | 程序 | 必选 |

**关键规则**：PM 每次激活时只创建下一个可创建的任务，不要一次全部创建。

#### 迭代完成

Bug 修复关闭 → 询问用户是否有下一个迭代：
- **有** → 关闭当前里程碑 → 创建下一个迭代里程碑 → 继续
- **没有** → 返回总路线阶段

#### 详细任务定义

参见 `.claude/skills/stage-iteration.md`。

---

## 设计文档层级关系

草案、设计案、执行案三者的关系：

| 层级 | 定位 | 比喻 | 特点 |
|------|------|------|------|
| **草案** (概念草案.md) | 给游戏**定调** | 灵魂 | 回答"这个游戏是什么"，简略但方向明确 |
| **设计案** | 给游戏**定骨架** | 骨架 | 基于草案的原则展开系统设计，定义有哪些系统、系统关系、核心行为 |
| **执行案** | 给游戏**填血肉** | 血肉 | 细化到程序可直接实现的交互规则和行为细节 |

设计案初始基于草案的原则进行设计。在后续迭代中遇到具体问题时，可以灵活调整或替换草案中的元素——草案是方向指引，不是硬性约束。

---

## 执行案规范

### 执行案格式

每个执行案文件顶部必须包含**迭代记录表头**：

```markdown
# <系统名>执行案

## 迭代记录

| 迭代版本 | 修改日期 | 状态 | 说明 |
|----------|----------|------|------|
| v0.1 | 2026-06-10 | 📝 设计中 | 初始版本 |

> 状态标记：📝 设计中 | 🔄 开发中 | ✅ 已同步

---

## 系统概述
（描述该系统做什么、服务于什么体验目标）

## 行为规则
（当前最新状态的所有行为规则）
```

### 执行案必须包含

1. **系统概述**：这个系统做什么、服务于什么体验目标
2. **完整的行为规则清单**：每个操作的触发条件、触发后表现、结束条件
3. **状态和状态转换**：系统有哪些状态、什么条件触发状态变化
4. **边界情况处理**：异常/极端情况下的系统行为
5. **与其他系统的交互**：本系统与其他系统的关联和影响

### 执行案不应包含

- 用什么引擎组件实现
- 代码/脚本架构怎么组织
- 数据用什么格式存储
- 具体的参数精确值（调优参数标注"建议值，可调"）

### 关卡执行案

- 当版本开发涉及场景搭建时，策划额外产出一份关卡执行案
- 关卡执行案将场景设计案的氛围描述转化为空间精度搭建指南（坐标、尺寸、BSP 资产映射）
- 使用混合坐标体系：区域用场景绝对坐标，区域内物件用相对偏移坐标
- 交互物和收集品的位置标注必须与交互系统/收集系统执行案交叉引用
- 完整规范参见 `.claude/refs/level-execution-template.md`

---

## 审查流程

> 审查由 **game-reviewer 子代理**执行，不再由 PM 执行。
> 角色完成工作后自行启动 reviewer 子代理。

### 审查触发

角色完成工作 → 在 Issue 下评论汇报 → 改标签为 `status:in-review` → 启动 game-reviewer 子代理

### 审查标准

审查标准定义在 `.claude/skills/quality-gate-review.md`，包含 4 道质量门：
1. 执行案质量门 — 完整性、清晰性、边界情况、系统关联、技术越界
2. 程序设计质量门 — 执行案覆盖度、美术需求、架构、数据流、风险、工作量
3. 美术资产验收门 — 需求覆盖、资产到位、规格、缺失处理
4. 程序实现验收门 — 设计一致性、覆盖度、资产使用、偏差处理

### 审查结果

- **通过** → reviewer 更新标签为 `review:pass` → 角色向用户汇报 → 用户决定是否关闭
- **未通过** → reviewer 更新标签为 `review:fail` + `status:blocked` → 角色向用户汇报 → 修改后重新提交

---

## 审查质量标准

> 以下标准供 game-reviewer 子代理使用。详细标准定义在 `.claude/skills/quality-gate-review.md`。

### 执行案质量标准

- [ ] 是否覆盖了该系统所有玩家可感知的行为？
- [ ] 每个操作是否明确了触发条件、触发后表现、结束条件？
- [ ] 边界情况是否都处理了？
- [ ] 与其他系统的关联是否说明？
- [ ] 是否有模糊地带？行为描述是否无歧义？
- [ ] 是否误入了技术细节？参数值是否标注为"建议值，可调"？
- [ ] 迭代记录表头是否存在且填写完整？

### 程序设计质量标准

- [ ] 是否完整回应了执行案中的每条行为规则？（逐条对照）
- [ ] 美术资源需求是否列得具体（尺寸、数量、触发时机）？
- [ ] 类与组件架构是否清晰？
- [ ] 数据流是否明确？
- [ ] 技术风险是否识别？
- [ ] 工作量估算是否给出？实现拆分建议是否合理且可操作？

### 美术资产验收标准

- [ ] 资源需求清单中的每一项是否都有对应的美术产出？（逐项对照）
- [ ] 资产文件是否已放置在对应目录？
- [ ] 资产规格是否符合需求？
- [ ] 未到位资产是否有明确的处理方案？

### 程序实现验收标准

- [ ] 实现是否与程序设计方案一致？（逐条对照）
- [ ] 最终实现是否完整覆盖了执行案中的所有行为规则？
- [ ] 美术资产是否已正确集成并使用？
- [ ] 偏差清单是否已梳理清楚？重大偏差是否有处理方案？

---

## 单人独立开发的特殊考量

- **无法并行**——同一时间只能做一件事，选择更关键
- **精力有限**——避免一次性拆分太多并行任务
- **心流重要**——建议按「完整做完一个小系统」而非「同时推进多个系统」的方式工作
- **早期验证**——越早能跑起来看到东西，越不容易失去动力
- **文档交接**——Agent 之间通过文档交接，PM 是进度调度器，reviewer 负责质量把关