starmen1265/ChildHood
1
0
Fork 0
Code Issues 11 Pull Requests Actions Packages Projects 2 Releases Wiki Activity

docs(refs): 移动参考文档至.claude/refs并修复工作流10项逻辑问题

Browse Source 
- 移动 development-workflow.md, GIT-GUIDE.md, GIT-GUIDE-LITE.md 至 .claude/refs/
- 修复③引用执行案时序矛盾，改为引用全局设计案系统名
- 区分阶段级前置①②和版本级循环③-⑧的不可跳过声明
- 删除草案阶段'不需要质量门'的自相矛盾表述
- 全局设计案改为'当前阶段目标形态'，明确两阶段独立维护
- 文档同步改为⑧版本复盘：程序汇报→PM协调→策划更新
- PM质量门改为斜体注释行，不再与步骤并列
- 新增设计文档层级关系说明（定调→定骨架→填血肉）
- 三道质量门均新增'开发者最终裁决'仲裁机制
- 原型阶段⑤⑥⑦允许交替推进，放松严格串行约束
- 更新 CLAUDE.md 中 GIT-GUIDE-LITE.md 引用路径

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
starmen1265
2026-06-04 00:14:23 +08:00
parent cc0f66ac54
commit 2038cfb90e
4 changed files with 77 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/GIT-GUIDE-LITE.md
-102
View File
@@ -1,102 +0,0 @@
# Git 快速参考（AI 用）
> 从 [GIT-GUIDE.md](GIT-GUIDE.md) 精简。完整规范见原文。
---
## 分支策略
**轻量 Feature Branch** — 单人开发，`main` 永远可玩可编译。
| 分支 | 前缀 | 生命期 | 说明 |
|---|---|---|---|
| 主线 | `main` | 永久 | 稳定版本，不直接在上面开发 |
| 功能 | `feature/` | 合并后删 | 新系统、新功能 |
| 修复 | `fix/` | 合并后删 | Bug 修复 |
| 原型 | `prototype/` | 实验完即删 | 技术验证，随便写 |
| 发布 | `release/` | 永久 | 从 main 切出，版本标记 |
**命名规则：** `<类型>/<小写连字符描述>`
```
feature/player-movement fix/camera-clipping release/v0.1
```
**流程：**
1. 从 `main` 拉分支 → 2. 开发并提交 → 3. 测试通过后合并回 `main` → 4. 删除分支
---
## 提交规范
**格式：** `<type>(<scope>): <中文描述>`
- subject ≤ 50 字符，中文描述，技术术语保留英文
- body 可选，每行 ≤ 72 字符
**Type（必选）：**
| Type | 用途 |
|---|---|
| `feat` | 新功能 |
| `fix` | Bug 修复 |
| `art` | 美术资源 |
| `level` | 关卡/场景 |
| `audio` | 音效/音乐 |
| `bp` | 蓝图逻辑 |
| `refactor` | 重构（不改功能） |
| `config` | 项目/引擎配置 |
| `docs` | 文档 |
| `wip` | 进行中（未完成） |
**Scope（可选，常用）：**
`player` `enemy` `combat` `ui` `camera` `inventory` `dialogue` `quest` `save` `audio` `animation` `ai` `level` `vfx`
**示例：**
```
feat(player): 实现角色跳跃和二段跳
fix(camera): 修复穿墙时摄像机卡顿问题
bp(enemy): 实现巡逻-追击-攻击状态机
wip(crafting): 合成系统UI初步框架
config: 启用Nanite和Lumen
```
---
## UE5 注意事项
- 蓝图与 C++ 分开提交
- `.uasset` / `.umap` 无法 diff → commit message 必须写清改了什么
- 不提交 `Binaries/` `Intermediate/` `Saved/` `.vs/`
---
## 版本号
`v主版本.次版本.修订号` — 主版本=里程碑，次版本=新系统，修订号=小修
---
## 远程仓库
**SSH 地址**：`ssh://sc-gitea@micecola.top:2223/starmen1265/ChildHood.git`
> ⚠️ 用户名是 `sc-gitea`（非默认 `git`），端口是 `2223`（非默认 22）
**切换远程地址**：
```bash
git remote set-url origin ssh://sc-gitea@micecola.top:2223/starmen1265/ChildHood.git
```
**SSH config**（`~/.ssh/config`）：
```
Host gitea micecola.top
HostName micecola.top
Port 2223
User sc-gitea
IdentityFile ~/.ssh/id_ed25519_gitea
IdentitiesOnly yes
```
**内网地址**（家里用）：`ssh://sc-gitea@192.168.1.22:2223/starmen1265/ChildHood.git`
完整规范见 → [GIT-GUIDE.md](GIT-GUIDE.md)
docs/GIT-GUIDE.md
-336
View File
@@ -1,336 +0,0 @@
# ChildHood - Git 规范
> 本文档规定 ChildHood 项目的 Git 分支策略和提交规范。
> 适用场景：单人独立开发 + UE5.7.4
---
## 一、分支策略
采用**轻量级 Feature Branch 模型**，避免企业级复杂流程，保持 `main` 分支随时可玩。
### 1.1 分支总览
```
main ──────────────────────────────────────── 稳定主线
│
├── feature/player-movement ───→ 合并后删除
├── feature/inventory-system ──→ 合并后删除
├── fix/camera-clipping ───────→ 合并后删除
├── prototype/procedural-gen ──→ 实验完即删
└── release/v0.1 ──────────────→ 永久保留
```
### 1.2 分支类型
| 分支 | 前缀 | 用途 | 合并目标 | 生命周期 |
|---|---|---|---|---|
| 主线 | `main` | 稳定可玩版本，每次提交都能编译运行 | — | 永久 |
| 功能 | `feature/` | 新系统、新功能开发 | `main` | 完成后删除 |
| 修复 | `fix/` | Bug 修复 | `main` | 完成后删除 |
| 原型 | `prototype/` | 技术验证、玩法实验 | 合并或丢弃 | 实验完即删 |
| 发布 | `release/` | 版本发布标记，只从 `main` 切出 | — | 永久保留 |
### 1.3 命名规范
格式：`<类型>/<简短描述>`，全小写，用连字符分隔单词。
```
# ✅ 好的命名
feature/player-movement
feature/inventory-system
feature/dialogue-tree
fix/camera-clipping-through-walls
fix/enemy-ai-stuck-on-navmesh
prototype/procedural-dungeon
release/v0.1
# ❌ 不好的命名
my-new-feature
fix-bug
test
feature/AddPlayerMovement
```
### 1.4 工作流程
```
1. 开始新功能
git checkout main
git pull
git checkout -b feature/xxx
2. 开发过程中（随时提交）
git add .
git commit -m "wip(xxx): 进度描述"
3. 功能完成，测试通过
git checkout main
git merge feature/xxx
git branch -d feature/xxx # 删除已合并分支
4. 到达里程碑
git checkout main
git tag -a v0.1.0 -m "第一个可玩原型"
git checkout -b release/v0.1
git push origin release/v0.1
```
### 1.5 核心原则
- **`main` 永远可玩**：坏了就留在 feature 分支继续改，不要合并进 main
- **功能分支粒度**：一个分支做一件事，不要在一个分支里同时做多个系统
- **原型不怕乱**：`prototype/` 分支随便写，验证完再决定合并还是丢弃
- **定期清理**：已合并的 feature/fix 分支及时删除，避免分支堆积
---
## 二、提交规范
### 2.1 提交消息格式
```
<type>(<scope>): <subject>
<body>（可选，多行说明）
```
- **subject**：不超过 50 个字符，简明扼要
- **body**：每行不超过 72 个字符，解释"做了什么"和"为什么"
- 使用中文描述，技术术语保留英文
### 2.2 Type 类型标签
| Type | 含义 | 使用场景 |
|---|---|---|
| `feat` | 新功能 | 新增系统、机制、玩法 |
| `fix` | Bug 修复 | 修复已知问题 |
| `art` | 美术资源 | 模型、贴图、材质、动画导入 |
| `level` | 关卡/场景 | 关卡搭建、场景编辑 |
| `audio` | 音效/音乐 | BGM、SFX、语音导入 |
| `bp` | 蓝图逻辑 | 蓝图节点修改、逻辑调整 |
| `refactor` | 重构 | 不改变功能的结构优化 |
| `config` | 项目配置 | 引擎设置、插件配置、项目参数 |
| `docs` | 文档 | README、设计文档、注释 |
| `wip` | 进行中 | 未完成的工作进度保存 |
### 2.3 Scope 范围标签（可选）
按游戏系统或模块划分：
```
player 玩家角色
enemy 敌人/AI
combat 战斗系统
ui UI 界面
camera 摄像机
inventory 背包/物品
dialogue 对话系统
quest 任务系统
save 存档系统
audio 音频系统
animation 动画系统
ai AI 行为树/状态机
level 关卡
vfx 视觉特效
```
### 2.4 提交示例
```bash
# 新功能
git commit -m "feat(player): 实现角色跳跃和二段跳"
# 带 body 的详细提交
git commit -m "feat(combat): 实现基础连击系统
- 添加三段连击动画蒙太奇
- 实现动画通知触发伤害判定
- 连击窗口时间可配置"
# Bug 修复
git commit -m "fix(camera): 修复穿墙时摄像机卡顿问题"
# 美术资源
git commit -m "art(environment): 添加草地和树木模型"
# 蓝图修改
git commit -m "bp(enemy): 实现巡逻-追击-攻击状态机"
# 关卡搭建
git commit -m "level(chapter1): 第一章关卡白盒搭建完成"
# 进行中
git commit -m "wip(crafting): 合成系统UI初步框架"
# 项目配置
git commit -m "config: 启用Nanite和Lumen，设置画质预设"
# 重构
git commit -m "refactor(inventory): 拆分背包数据层与UI层"
```
### 2.5 提交粒度建议
| 操作 | 粒度 |
|---|---|
| 蓝图逻辑 | 按功能点提交，不要一次提交多个系统 |
| 关卡编辑 | 按区域/房间提交 |
| 美术资源导入 | 按类型/角色分批提交 |
| C++ 代码 | 按逻辑单元提交 |
| 材质/贴图 | 按材质组提交 |
### 2.6 UE5 特别注意
- **蓝图与 C++ 分开提交**：避免同一提交中混合两者，方便出问题时 revert
- **二进制文件提交**：`.uasset`、`.umap` 无法 diff，commit message 要写清楚改了什么
- **不要提交以下目录**（已被 .gitignore 排除）：
- `Binaries/`、`Intermediate/`、`Saved/`、`DerivedDataCache/`
- `.vs/`、`*.sln`（由引擎自动生成）
---
## 三、版本号规范
采用简化语义化版本：
```
v主版本.次版本.修订号
v0.1.0 ← 第一个可玩原型
v0.2.0 ← 核心玩法成型
v0.3.0 ← 内容填充阶段
...
v1.0.0 ← 正式发布
```
- **主版本**：重大里程碑（原型、Alpha、正式版）
- **次版本**：新系统/大功能完成
- **修订号**：Bug 修复、小调整
---
## 四、常用命令速查
```bash
# 查看当前状态
git status
git log --oneline --graph --all
# 开始新功能
git checkout -b feature/xxx
# 暂存当前工作（需要临时切分支时）
git stash
git stash pop
# 撤销上次提交（保留修改）
git reset --soft HEAD~1
# 强制同步远程（仅限个人项目）
git fetch origin
git reset --hard origin/main
```
---
## 五、远程仓库配置
### 5.1 服务器信息
| 项目 | 值 |
|---|---|
| 平台 | Gitea（自建） |
| HTTP 地址 | `http://192.168.1.22:8418/starmen1265/ChildHood.git` |
| SSH 地址 | `ssh://sc-gitea@192.168.1.22:2223/starmen1265/ChildHood.git` |
| SSH 端口 | `2223`（非默认 22） |
| SSH 用户名 | `sc-gitea`（非默认 `git`） |
### 5.2 SSH 配置
#### 生成密钥（ED25519，推荐）
```bash
ssh-keygen -t ed25519 -C "starmen1265@163.com" -f ~/.ssh/id_ed25519 -N ""
```
> ⚠️ 优先使用 ED25519 而非 RSA。部分 Git 服务器对 RSA 密钥兼容性较差。
#### 添加公钥到 Gitea
1. 查看公钥：`cat ~/.ssh/id_ed25519.pub`
2. 复制完整输出
3. 登录 Gitea Web UI → 设置 → SSH/GPG 密钥 → 添加密钥
4. 粘贴公钥内容，保存
#### 设置远程地址
```bash
# 查看当前远程地址
git remote get-url origin
# 切换到 SSH（注意用户名是 sc-gitea，端口是 2223）
git remote set-url origin ssh://sc-gitea@192.168.1.22:2223/starmen1265/ChildHood.git
```
### 5.3 常见问题排查
#### ❌ `Host key verification failed`
首次连接服务器需要信任主机密钥：
```bash
ssh-keyscan -p 2223 192.168.1.22 >> ~/.ssh/known_hosts
```
#### ❌ `Permission denied (publickey)`
排查步骤：
```bash
# 1. 测试 SSH 连接，查看详细日志
ssh -vvv -p 2223 sc-gitea@192.168.1.22 "exit"
# 2. 检查密钥是否被 offer
# 在日志中找 "Offering public key" 行
# 确认使用了 id_ed25519 而不是 id_rsa
# 3. 对比本地和服务器的密钥指纹
ssh-keygen -lf ~/.ssh/id_ed25519.pub
# 然后到 Gitea Web UI → 设置 → SSH/GPG 密钥 查看指纹是否一致
```
常见原因：
| 原因 | 解决方法 |
|---|---|
| 远程地址用了 `git@` 而非 `sc-gitea@` | 改用正确的用户名（见 5.1） |
| SSH 端口用了默认 22 而非 2223 | URL 中指定端口 `ssh://sc-gitea@host:2223/...` |
| RSA 密钥被服务器拒绝 | 重新生成 ED25519 密钥 |
| 公钥未添加到 Gitea | Web UI → 设置 → SSH/GPG 密钥 → 添加 |
| 公钥格式不完整 | 确保从 `ssh-ed25519` 复制到字符串末尾，无截断 |
#### ❌ `Authentication failed`（HTTP 方式）
HTTP 方式需要用户名密码认证，建议切换到 SSH：
```bash
git remote set-url origin ssh://sc-gitea@192.168.1.22:2223/starmen1265/ChildHood.git
```
#### 🔧 SSH 使用了错误的密钥
如果服务器同时有 RSA 和 ED25519 密钥，SSH 可能优先尝试 RSA。可以指定密钥：
```bash
# 单次指定
git -c core.sshCommand="ssh -i ~/.ssh/id_ed25519 -p 2223" push origin main
# 或全局配置（推荐）
# 编辑 ~/.ssh/config，添加：
Host 192.168.1.22
Port 2223
User sc-gitea
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
```
docs/development-workflow.md
-654
View File
@@ -1,654 +0,0 @@
# 游戏开发工作流
> 本文档定义游戏项目的开发阶段、版本开发流水线、角色职责、产出标准和质量检查规则。
> 所有开发工作必须遵循此工作流，不可跳过或并行阶段。
---
## 角色定义
| 角色 | 职责 | 产出位置 | PM 如何判断其进度 |
|------|------|----------|-------------------|
| **策划** (Design) | 玩法设计、数值平衡、叙事、系统机制 | `docs/design/`、`GameConfig/` | 扫描 `docs/design/` 和 `GameConfig/` 目录中的文件 |
| **程序** (Dev) | 系统实现、技术架构、Bug 修复 | `Source/`、`Content/`、`docs/technical/` | 扫描对应目录中的文件 |
| **美术** (Art) | 美术需求分析、资产规格、风格指南 | `docs/art/`、`Content/` | 扫描对应目录中的文件 |
| **PM** | 进度追踪、优先级决策、风险预警、流水线推进 | `docs/plans/` | 不产出设计文档、代码或美术资产 |
### 协作规则
- **策划先行**：设计文档是其他角色的需求源
- **程序读设计**：实现前必须先读取对应设计文档和配置表
- **文档即交接**：Agent 之间不直接通信，通过共享文档目录交接
- **冲突时策划说了算**：玩法/数值/叙事的最终决定权在策划角色
- **PM 是信息枢纽**：跨角色的信息同步和阻塞排查由 PM 负责
### 进度汇报规则
- 各 Agent 完成工作后汇报结果，**不自动勾选** `current.md`
- 开发者确认后，由 PM 统一更新进度文档
- PM 每次调用时主动扫描各目录，验证「汇报的进度」与「实际文件产出」是否一致
---
## 开发阶段
项目开发分为四个宏观阶段，每个阶段有不同的关注重点和流程重量。
```
草案阶段 ─── "这个游戏是什么？" ─── 轻量流程，每项目一次
↓
原型阶段 ─── "这个游戏好玩吗？" ─── 版本流水线（轻量），多版本迭代
↓
批量生产阶段 ─── "把游戏做完整" ─── 版本流水线（完整 + 生产工具），多版本迭代
↓
测试与发布阶段 ─── "把游戏做稳定" ─── Bug/反馈驱动
```
**阶段转换由开发者主观判断**，无硬性标准。PM 可建议，但最终决定权在开发者。
---
### 草案阶段
**目的**：确定游戏是什么——玩法方向、美术风格、技术可行性。
**范围**：每项目一次，在正式开发之前完成。
**关注问题**：这个游戏是什么？为什么要做？做不做得了？
#### 产出
**玩法草案文档**（`docs/design/concept.md`），包含以下 6 个字段：
1. **一句话描述** — 用一句话说清楚这是什么游戏
2. **玩家能做什么** — 玩家在游戏中的核心操作和活动
3. **游戏氛围与风格** — 情感基调、视觉风格、目标审美
4. **游戏核心循环** — 玩家在游戏中反复做什么、为什么持续玩
5. **游戏元素** — 世界观、角色、剧情、物品、怪物等关键元素概述
6. **参考** — 灵感来源（其他游戏、电影、书、某种经历）
**美术风格指南**（`docs/art/style-guide.md`）— 确定视觉方向。
**技术可行性评估** — 评估核心玩法在目标引擎/平台上的实现可行性。
#### 流程特点
- **极轻量**：不需要详细的系统设计，不需要执行案，不需要质量门
- **可以反复推翻重来**：草案阶段推翻设计成本最低
- **头脑风暴是核心方法**：通过讨论探索方向，确认后才进入文档产出
#### PM 检查要点
- 草案文档 6 个字段是否都已回答？
- 美术风格是否有明确方向？
- 技术上是否可行？
- 开发者是否明确表示"可以进入下一阶段"？
#### 完成标志
玩法草案文档产出且开发者确认。进入原型阶段后，草案文档不再修改（除非开发者决定推翻重来）。
---
### 原型阶段
**目的**：验证核心玩法可行性——从最核心功能开始，快速迭代。
**关注问题**：这个游戏好玩吗？核心循环跑得通吗？
#### 阶段路线图
原型阶段开始时，产出**阶段路线图**（`docs/plans/prototype-roadmap.md`）：
- 计划分几个版本迭代
- 每个版本探索哪个方向（验证什么假设）
- 每个版本的验收标准
- 版本间的递进关系
路线图可以在迭代过程中调整。
#### 多版本迭代
原型阶段包含**多个版本**，每个版本是版本开发流水线的一次循环。版本之间可以：
- 基于上一版本的反馈调整方向
- 增加新的系统验证
- 修改已有系统的行为规则
每个版本的流水线循环：**③版本设计 → ④执行案 → ⑤程序设计 → ⑥美术产出 → ⑦程序实现 → 同步文档**
①全局设计在阶段初期集中产出，后续版本可增量补充。②阶段路线图在阶段开始时产出。
#### 设计文档组织
原型阶段的所有设计案和执行案统一放在 `docs/design/prototype/` 目录下：
```
docs/design/prototype/
game-vision.md # 游戏愿景
player-controller.md # 设计案
player-controller-execution.md # 执行案（含迭代版本表头）
interaction-system.md
interaction-system-execution.md
...
```
**不按版本分子目录**——执行案通过文件内的迭代记录表头追踪各版本的变更。
#### 各流水线步骤的原型阶段要求
| 步骤 | 原型阶段要求 |
|------|-------------|
| ① 全局设计案 | 可以边做边补，不需要一开始就全部完成。新系统先产出简要设计再动手 |
| ② 阶段路线图 | 原型阶段开始时产出，可随迭代调整 |
| ③ 版本设计 | 明确本版本的验证目标和范围。允许粗粒度 |
| ④ 执行案 | 关注影响玩法体验的核心行为。边界情况、非核心反馈等细节可以先略过 |
| ⑤ 程序设计 | 可以用占位方案，不需要生产级架构。重点回答"怎么实现核心行为" |
| ⑥ 美术产出 | 允许占位资源、开发者自行处理。能用就行 |
| ⑦ 程序实现 | 允许硬编码、允许快速但不优雅的实现。先跑通再说 |
| PM 质量门 | 关注核心行为是否完整描述，不要求面面俱到 |
#### 文档同步（每个迭代完成后）
**每个版本迭代完成后，必须同步更新设计案和执行案**，使其与实际实现保持一致：
1. **实现完成** → 体验验证
2. **对照实现更新文档** — 设计案和执行案中与实际不符的内容要修正
3. **更新执行案迭代记录** — 在迭代版本表头中标记状态为 ✅ 已同步
4. **记录差异** — 如果实现与设计有偏差，记录偏差原因
> **为什么不迭代完就同步？** 文档是下一个迭代的起点。如果文档和实现不一致，下一个迭代的执行案会基于错误的假设，导致更多返工。
#### 阶段退出
- **退出标准**：开发者主观判断核心玩法已验证通过
- **退出时应有**：至少一个可玩的核心循环原型，核心系统的执行案已验证可行，文档已同步
- **退出后**：将 `prototype/` 最终版复制到 `production/`，`prototype/` 保留作为归档
---
### 批量生产阶段
**目的**：在核心玩法验证通过的基础上，完善外围系统，填充游戏内容与资产。
**关注问题**：怎么把游戏做完整？内容够不够？系统之间能不能协同？
#### 阶段路线图
批量生产阶段开始时，产出**阶段路线图**（`docs/plans/production-roadmap.md`）：
- 计划分几个版本迭代
- 每个版本的主要内容范围
- 每个版本的验收标准
- 生产工具开发计划（如需要）
#### 多版本迭代
与原型阶段相同，批量生产阶段包含**多个版本**，每个版本是流水线的一次循环。
#### 设计文档组织
批量生产阶段的所有设计案和执行案统一放在 `docs/design/production/` 目录下：
```
docs/design/production/
game-vision.md # 从 prototype/ 复制，作为起点
player-controller.md # 在原型基础上更新
player-controller-execution.md # 继续迭代，追加新的迭代记录
...
```
#### 各流水线步骤的批量生产阶段要求
| 步骤 | 批量生产阶段要求 |
|------|----------------|
| ① 全局设计案 | 应已完整。新增系统必须先产出全局设计再进入版本开发 |
| ② 阶段路线图 | 批量生产阶段开始时产出，可随迭代调整 |
| ③ 版本设计 | 明确本版本的内容范围和完成度要求。粒度更细 |
| ④ 执行案 | 所有细节必须补全：边界情况、非核心反馈、边缘体验、异常处理等 |
| ⑤ 程序设计 | 需要生产级架构，考虑扩展性和数据驱动。美术需求必须具体到尺寸和数量 |
| ⑥ 美术产出 | 正式资产，符合风格指南。不允许占位 |
| ⑦ 程序实现 | 不允许硬编码，数据应配置化。代码质量需达到发布标准 |
| PM 质量门 | 完整执行所有检查项，逐条对照 |
#### 文档同步（每个迭代完成后）
与原型阶段相同：每个版本迭代完成后必须同步更新设计案和执行案。
#### 生产工具
批量生产阶段可能需要在正式开发前先开发生产工具：
| 工具类型 | 目的 | 何时开发 |
|----------|------|----------|
| 数据配置工具 | 让策划能自行配置交互内容、NPC 对话、物品属性等 | 需要大量配置数据时 |
| 关卡编辑工具 | 快速搭建和调整场景布局 | 需要频繁调整场景时 |
| 批量资产生成工具 | 批量生成/导入美术资产 | 资产量大时 |
| 测试工具 | 自动化验证、数据校验 | 手动测试效率低时 |
工具开发本身也应遵循版本流水线（有执行案、有程序设计），但可以简化流程。
#### 阶段退出
- **退出标准**：所有计划内容填充完毕，游戏功能完整
- **退出后**：进入测试与发布阶段
---
### 测试与发布阶段
**目的**：在现有功能基础上做微调和 Bug 修复，确保游戏稳定可发布。
**关注问题**：有没有 Bug？体验够不够好？性能行不行？
#### 流程特点
- **不使用版本开发流水线**（①-⑦）
- **不增加大型新功能**——所有功能应已在上游阶段完成
- **以 Bug 和反馈驱动**
- **微调允许**：数值调整、文案修改、UI 微调、性能优化
#### 工作流程
```
收集 Bug/反馈 → 评估优先级 → 修复/微调 → 验证 → 发布
↑ │
└───────────────────────────────────────────┘
```
1. **收集**：从测试、体验、反馈中收集 Bug 和改进意见
2. **评估**：按严重程度和影响范围排优先级
3. **修复/微调**：针对性修改，不引入大的架构变动
4. **验证**：确认修复有效，未引入新问题
5. **发布**：构建发布版本
---
## 版本开发流水线
> 本流水线在**原型阶段**和**批量生产阶段**使用。两个阶段使用相同的流水线结构，但严格度和完整性要求不同（详见上方各阶段说明）。
每个版本的开发按以下流水线**严格顺序推进**：
```
① 全局设计案 → ② 阶段路线图 → ③ 当前版本设计 → ④ 执行案
↓
[PM 审查：执行案质量门]
↓
⑤ 程序设计
↓
[PM 审查：程序设计质量门]
↓
⑥ 美术产出
↓
[PM 审查：美术资产验收门]
↓
⑦ 程序实现
↓
[文档同步：更新设计案/执行案以匹配实现]
```
**每个阶段都是下一阶段的必要前置条件。不可跳过或并行。PM 审查不通过则退回重做，不可进入下一阶段。**
---
### ① 全局设计案（策划）
**目的**：定义整个游戏**最终形态**的全景图——有哪些系统、有哪些元素、它们大体上是什么关系。
**范围**：面向游戏的最终完成形态，不是某个版本。
**必须包含的内容**：
1. **系统清单**：游戏最终包含哪些系统
2. **元素清单**：游戏世界中的关键元素（角色、场景区域、收集品分类、NPC等）
3. **系统关系**：各系统之间如何关联和互相影响
4. **核心玩法循环**：玩家在游戏中做什么、为什么持续玩
5. **情感目标**：游戏要给玩家带来什么样的体验和情感
**产出形式**：
- 可以有多个文档，按系统或主题拆分
- 必须有一个**索引文档**把所有全局设计文档串联起来
- 产出位置：`docs/design/<阶段>/`（`prototype/` 或 `production/`）
**PM 检查要点**：
- 是否覆盖了游戏最终形态的所有主要系统？
- 系统关系是否清晰（谁依赖谁、谁独立）？
- 索引文档是否存在且能串联所有全局设计文档？
---
### ② 阶段路线图（PM 主导，策划配合）
**目的**：定义当前阶段（原型或批量生产）分几个版本推进，每个版本探索什么方向。
**必须包含的内容**：
1. **版本列表**：当前阶段有哪些版本
2. **每个版本的核心目标**：这个版本验证/实现什么
3. **每个版本的范围概述**：大致包含哪些系统和内容
4. **版本间的递进关系**：为什么先做这些后做那些
5. **每个版本的验收标准**：怎样算"这个版本做完了"
**产出位置**：`docs/plans/prototype-roadmap.md` 或 `docs/plans/production-roadmap.md`
**PM 检查要点**：
- 每个版本的范围是否与全局设计案对齐？
- 版本间是否有清晰的递进逻辑？
- 是否有版本范围过大的风险？
---
### ③ 当前版本设计（策划）
**目的**：针对最近要做的版本，明确这个版本的目标、范围、需要哪些元素和系统、做到什么程度。
**范围**：仅限当前版本，不涉及后续版本。
**必须包含的内容**：
1. **版本目标定位**：这个版本要做到什么程度——是最小能跑的原型、功能完整的可玩版本、还是经过打磨的体验版？
2. **内容范围**：本版本包含哪些内容，每种内容做到什么完成度（占位/初版/正式）
3. **版本验收标准**：怎样算"这个版本做完了"？验收标准必须明确、可检验
4. **本版本涉及的系统清单**：哪些系统需要在本版本实现（引用执行案）
**产出形式**：可以是阶段路线图中的详细展开，也可以是独立的版本设计文档。放在 `docs/design/<阶段>/` 目录下。
**PM 检查要点**：
- 版本目标定位是否明确？
- 内容范围是否清晰，每种内容的完成度是否定义？
- 验收标准是否明确、可检验？
- 范围是否与阶段路线图一致？
---
### ④ 执行案（策划）
**目的**：针对当前版本中的每个系统/元素，写出完整的**交互规则细节**，细到程序照着这个逻辑实现功能。
**范围**：仅限当前版本中需要实现的系统。
**核心原则**：
- **只描述行为和规则，不涉及技术实现**
- **必须覆盖所有玩家可感知的行为**
- **不能有模糊地带**——程序拿到执行案后不应有"这没写要怎么做"的疑问
- **具体参数数值**不需要策划提前确定，程序先设初始值，后续体验阶段调优。如有建议值标注"建议值，可调"
**执行案格式**：
每个执行案文件顶部必须包含**迭代记录表头**：
```markdown
# <系统名>执行案
## 迭代记录
| 迭代版本 | 修改日期 | 状态 | 说明 |
|----------|----------|------|------|
| v0.1 | 2026-06-10 | 📝 设计中 | 初始版本 |
> 状态标记：📝 设计中 | 🔄 开发中 | ✅ 已同步
---
## 系统概述
（描述该系统做什么、服务于什么体验目标）
## 行为规则
（当前最新状态的所有行为规则）
```
**必须包含的内容**：
1. **系统概述**：这个系统做什么、服务于什么体验目标
2. **完整的行为规则清单**：每个操作的触发条件、触发后表现、结束条件
3. **状态和状态转换**：系统有哪些状态、什么条件触发状态变化
4. **边界情况处理**：异常/极端情况下的系统行为（如多个交互物重叠、交互中移动等）
5. **与其他系统的交互**：本系统与其他系统的关联和影响
**不应包含的内容**：
- 用什么引擎组件实现
- 代码/脚本架构怎么组织
- 数据用什么格式存储
- 具体的参数精确值（调优参数标注"建议值，可调"）
**阶段差异**：
| 维度 | 原型阶段 | 批量生产阶段 |
|------|----------|-------------|
| 行为覆盖 | 核心行为必须完整，非核心行为可略过 | 所有行为必须完整覆盖 |
| 边界情况 | 影响核心玩法的必须处理，其余可略过 | 全部必须处理 |
| 系统间关联 | 核心关联必须说明 | 全部必须说明 |
**产出形式**：
- 每个系统一份执行案，放在 `docs/design/<阶段>/` 目录下
- 文件命名：`<系统名>-execution.md`（如 `player-controller-execution.md`）
- 不按版本分文件，通过迭代记录表头追踪变更
---
### PM 审查：执行案质量门
**触发时机**：策划完成执行案（④）后，进入程序设计（⑤）之前。
**审查人**：PM
**审查内容**：
1. **完整性**：是否覆盖了该系统所有玩家可感知的行为？每个操作是否明确了触发条件、触发后表现、结束条件？
2. **清晰性**：是否有模糊地带？行为描述是否无歧义？程序拿到后能否不问策划任何问题就实现功能？
3. **边界情况**：异常/极端情况下的系统行为是否都处理了？
4. **系统间关联**：与其他系统的关联和影响是否说明？
5. **技术越界检查**：是否误入了技术细节？精确参数值是否标注为"建议值，可调"？
**阶段差异**：
| 维度 | 原型阶段 | 批量生产阶段 |
|------|----------|-------------|
| 完整性 | 核心行为必须完整，非核心可略过 | 全部必须完整 |
| 边界情况 | 影响核心玩法的必须处理 | 全部必须处理 |
| 严格度 | 重点关注核心行为质量 | 逐条全面检查 |
**判定**：
- **通过** → 进入 ⑤ 程序设计
- **不通过** → 退回策划修改，列出具体问题清单
**产出**：PM 审查记录（记录在 `docs/plans/review-log.md`）
---
### ⑤ 程序设计（程序）
**目的**：程序读完策划的执行案后，设计具体的实现方案。
**前置条件**：执行案（④）已就绪，且 PM 审查通过。
**必须包含的内容**：
1. **实现方案**：针对执行案中的每条行为规则，说明打算如何实现
2. **类与组件架构**：需要哪些类/组件？继承关系？挂载方式？
3. **数据流**：数据从哪里来？系统之间如何通信？
4. **美术资源需求清单**：实现这个功能需要哪些美术资源（模型、动画、UI 等），具体到数量和尺寸
5. **技术风险和注意事项**：实现中可能遇到的技术难点
**阶段差异**：
| 维度 | 原型阶段 | 批量生产阶段 |
|------|----------|-------------|
| 架构 | 可以用占位方案，不需要生产级 | 需要生产级架构，考虑扩展性 |
| 数据流 | 允许硬编码 | 数据应配置化 |
| 美术需求 | 允许简化描述 | 必须具体到尺寸和数量 |
**产出位置**：`docs/technical/<系统名>-tech.md`
---
### PM 审查：程序设计质量门
**触发时机**：程序完成技术设计（⑤）后，进入美术产出（⑥）之前。
**审查内容**：
1. **执行案覆盖度**：程序设计是否完整回应了执行案中的每条行为规则？逐条对照
2. **美术资源需求**：需求是否列得具体？数量、尺寸、触发时机是否明确？
3. **类与组件架构**：继承关系和挂载方式是否清晰？
4. **数据流**：是否明确？
5. **技术风险**：是否识别？
**判定**：
- **通过** → 进入 ⑥ 美术产出
- **不通过** → 退回程序修改
---
### ⑥ 美术产出（美术）
**目的**：根据程序输出的美术资源需求清单，产出对应资产。
**前置条件**：程序设计（⑤）已就绪，且 PM 审查通过。
**阶段差异**：
| 维度 | 原型阶段 | 批量生产阶段 |
|------|----------|-------------|
| 资产质量 | 允许占位资源、开发者自行处理 | 正式资产，符合风格指南 |
| 完成度 | 能用就行 | 必须满足规格要求 |
**产出位置**：
- 资产放 `Content/` 对应目录
- 清单记录在 `docs/art/asset-manifest.md` 或直接在技术方案中更新
---
### PM 审查：美术资产验收门
**触发时机**：美术完成资产产出（⑥）后，进入程序实现（⑦）之前。
**审查内容**：
1. **需求覆盖度**：逐项对照美术资源需求清单
2. **资产到位确认**：资产文件是否已放置在对应目录？
3. **资产规格**：尺寸、格式等是否符合需求？
4. **缺失项处理**：未到位资产是否有明确处理方案？
---
### ⑦ 程序实现（程序）
**目的**：基于程序设计方案和美术资产，实际编写代码。
**阶段差异**：
| 维度 | 原型阶段 | 批量生产阶段 |
|------|----------|-------------|
| 代码质量 | 允许硬编码、快速实现 | 不允许硬编码，数据配置化，代码达发布标准 |
| 验证 | 核心流程跑通即可 | 每个系统独立验证 + 集成验证 |
**实现后必须执行文档同步**：对照实际实现更新设计案和执行案，确保文档与代码一致。
---
## 文档同步流程
**每个版本迭代完成后，必须同步更新设计案和执行案**。这是流水线的必要环节，不可跳过。
### 同步步骤
1. **体验验证**：实际体验实现结果，确认核心行为是否符合预期
2. **对照差异**：将实现结果与设计案/执行案对照，找出差异
3. **更新文档**：
- 设计案：更新与实际不符的系统描述
- 执行案：更新行为规则以匹配实际实现，在迭代记录中新增一行
4. **标记状态**：执行案迭代记录中该版本标记为 ✅ 已同步
### 为什么必须同步
- 文档是下一个迭代的起点。如果文档和实现不一致，下一个迭代会基于错误假设
- PM 的质量门审查基于文档。文档不准确会导致审查无效
- 程序在实现时可能发现设计的问题并做了调整，这些调整必须反映到文档中
---
## PM 诊断检查清单
PM 在每次 `/plan` 调用时，先判断宏观阶段，再针对**当前版本**逐项检查流水线状态。
### 宏观阶段判断
| 检查项 | 判断方式 | 结果 |
|--------|----------|------|
| 项目处于哪个开发阶段？ | 检查 `concept.md` → 检查核心玩法是否已有可玩原型 → 检查内容是否已完整 | 草案 / 原型 / 批量生产 / 测试发布 |
| 阶段信息是否记录在 `current.md`？ | 检查 `current.md` 中是否有阶段标注 | 如无则补充 |
### 版本流水线检查
| 检查项 | 检查方式 | 通过条件 |
|--------|----------|----------|
| ① 全局设计案是否存在且完整？ | 检查 `docs/design/<阶段>/` 中的全局设计文档和索引 | 覆盖所有主要系统，有索引串联 |
| ② 阶段路线图是否存在？ | 检查 `docs/plans/<阶段>-roadmap.md` | 版本列表、每版本目标、递进关系明确 |
| ③ 当前版本设计是否完整？ | 检查版本设计文档或路线图中的详细描述 | 回答了版本定位、内容范围、验收标准 |
| ④ 执行案是否齐全？ | 检查 `docs/design/<阶段>/` 对应执行案 | 每个涉及系统的核心行为规则都已明确 |
| **PM 审查**：执行案质量门 | 对照质量标准逐项检查（注意阶段严格度差异） | 完整性、清晰性、边界情况通过 |
| ⑤ 程序设计方案是否齐全？ | 检查 `docs/technical/` 对应文档 | 每个执行案都有对应技术方案 |
| **PM 审查**：程序设计质量门 | 执行案与技术方案逐条对照 | 行为规则全覆盖，美术需求具体 |
| ⑥ 美术资产是否就位？ | 检查资源需求清单 vs 实际资产 | 所有必需资产已产出或有处理方案 |
| **PM 审查**：美术资产验收门 | 需求清单 vs 实际资产逐项对照 | 每项需求都有对应产出 |
| ⑦ 程序实现是否完成？ | 检查实际文件 | 实现完成 |
| **文档同步** | 对照实现检查文档是否一致 | 设计案/执行案已同步更新 |
**遇到第一个未通过的即为当前应推进的阶段。**
**注意**：原型阶段的质量门检查允许在非核心维度上降低严格度，批量生产阶段必须逐条全面检查。
---
## 文档质量检查标准
以下标准对应流水线中的三道 PM 质量门。
### 执行案质量标准（对应「执行案质量门」）
**完整性检查**：
- [ ] 是否覆盖了该系统所有玩家可感知的行为？
- [ ] 每个操作是否明确了触发条件、触发后表现、结束条件？
- [ ] 边界情况是否都处理了？
- [ ] 与其他系统的关联是否说明？
**清晰性检查**：
- [ ] 是否有模糊地带？
- [ ] 行为描述是否无歧义？
- [ ] 程序拿到后能否不问策划任何问题就实现功能？
**边界检查**：
- [ ] 是否误入了技术细节？
- [ ] 精确参数值是否标注为"建议值，可调"而非固定值？
**迭代记录检查**：
- [ ] 迭代记录表头是否存在且填写完整？
- [ ] 已完成版本的文档是否已同步（✅ 已同步）？
### 程序设计质量标准（对应「程序设计质量门」）
- [ ] 是否完整回应了执行案中的每条行为规则？（逐条对照）
- [ ] 美术资源需求是否列得具体（尺寸、数量、触发时机）？
- [ ] 类与组件架构是否清晰？
- [ ] 数据流是否明确？
- [ ] 技术风险是否识别？
### 美术资产验收标准（对应「美术资产验收门」）
- [ ] 资源需求清单中的每一项是否都有对应的美术产出？（逐项对照）
- [ ] 资产文件是否已放置在对应目录？
- [ ] 资产路径是否记录清晰？
- [ ] 资产规格是否符合需求？
- [ ] 未到位资产是否有明确的处理方案？
---
## 单人独立开发的特殊考量
- **无法并行**——同一时间只能做一件事，选择更关键
- **精力有限**——避免一次性拆分太多并行任务
- **心流重要**——建议按「完整做完一个小系统」而非「同时推进多个系统」的方式工作
- **早期验证**——越早能跑起来看到东西，越不容易失去动力
- **文档交接**——Agent 之间通过文档交接，PM 是信息枢纽