From c3c10a9fcbd6e9fbce4ce60f18c3faf7934821ae Mon Sep 17 00:00:00 2001 From: starmen1265 Date: Mon, 8 Jun 2026 16:03:24 +0800 Subject: [PATCH] =?UTF-8?q?refactor(skills):=20Agent=E6=9E=B6=E6=9E=84?= =?UTF-8?q?=E9=87=8D=E6=9E=84=E2=80=94=E2=80=94=E5=8E=BB=E9=98=B6=E6=AE=B5?= =?UTF-8?q?/=E5=8E=BB=E6=AD=A5=E9=AA=A4=E5=8F=B7/=E5=AE=A1=E6=9F=A5?= =?UTF-8?q?=E7=BA=AFIssue=E5=8C=96/=E5=B7=A5=E4=BD=9C=E6=B5=81=E6=8B=86?= =?UTF-8?q?=E6=8A=80=E8=83=BD/=E7=9B=AE=E5=BD=95=E6=89=81=E5=B9=B3?= =?UTF-8?q?=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - game-reviewer: 删除本地审查记录，仅Issue评论 - quality-gate-review: 删除审查记录/步骤号/阶段标准 - game-dev: 删除阶段感知节，4个工作流详情拆到技能 - game-designer: 删除原型/批量生产阶段，执行案规范拆到技能 - game-pm: 去掉节号和步骤号 - 全局去掉步骤标号（①-⑧/步骤1-5/1.4.X/第一步-第四步） - 新建技能: code-implementation/deviation-report/design-execution - 原型目录扁平化: docs/design/prototype/* → docs/design/ - requirements-analysis及子文件去步骤号和阶段引用 - stage-iteration/sketch/roadmap去任务编号 - 更新所有docs/design/路径引用 --- .claude/agents/game-designer.md | 114 +++------------ .claude/agents/game-dev.md | 135 ++++-------------- .claude/agents/game-pm.md | 22 +-- .claude/agents/game-reviewer.md | 22 ++- .claude/refs/development-workflow.md | 28 ++-- .claude/skills/code-implementation/SKILL.md | 66 +++++++++ .claude/skills/design-execution/SKILL.md | 83 +++++++++++ .claude/skills/deviation-report/SKILL.md | 47 ++++++ .claude/skills/gitea-collab/SKILL.md | 3 - .claude/skills/gitea-pm/SKILL.md | 1 - .claude/skills/level-builder/SKILL.md | 12 +- .claude/skills/project-initializer.md | 10 +- .claude/skills/quality-gate-review.md | 71 ++------- .claude/skills/requirements-analysis/SKILL.md | 34 +++-- .../references/diagram-guide.md | 12 +- .../references/examples.md | 2 +- .../references/output-template.md | 11 +- .claude/skills/stage-iteration.md | 50 +++---- .claude/skills/stage-roadmap.md | 26 ++-- .claude/skills/stage-sketch.md | 4 +- ChildHood.uproject | 2 +- docs/design/README.md | 99 ++++++++----- docs/design/prototype/README.md | 74 ---------- docs/design/{prototype => }/v01-范围.md | 0 docs/design/{prototype => }/主角设计.md | 0 .../design/{prototype => }/交互系统-执行案.md | 0 docs/design/{prototype => }/交互系统.md | 0 .../关卡-v01-城郊小街-执行案.md | 0 docs/design/{prototype => }/关卡设计工作流.md | 0 docs/design/{prototype => }/叙事框架.md | 0 .../{prototype => }/场景-v01-城郊小街.md | 0 docs/design/{prototype => }/场景与世界观.md | 0 .../头脑风暴-2026-06-01-愿景支柱与世界观.md | 0 .../头脑风暴-2026-06-04-时代与科技灵感.md | 0 .../头脑风暴-2026-06-05-怀旧文化.md | 0 docs/design/{prototype => }/小游戏系统.md | 0 .../design/{prototype => }/收集系统-执行案.md | 0 docs/design/{prototype => }/收集系统.md | 0 docs/design/{prototype => }/游戏愿景.md | 0 .../{prototype => }/玩家控制器-执行案.md | 0 docs/design/{prototype => }/玩家控制器.md | 0 docs/technical/交互系统-技术方案.md | 5 +- docs/technical/收集系统-技术方案.md | 5 +- docs/technical/玩家控制器-技术方案.md | 5 +- 44 files changed, 435 insertions(+), 508 deletions(-) create mode 100644 .claude/skills/code-implementation/SKILL.md create mode 100644 .claude/skills/design-execution/SKILL.md create mode 100644 .claude/skills/deviation-report/SKILL.md delete mode 100644 docs/design/prototype/README.md rename docs/design/{prototype => }/v01-范围.md (100%) rename docs/design/{prototype => }/主角设计.md (100%) rename docs/design/{prototype => }/交互系统-执行案.md (100%) rename docs/design/{prototype => }/交互系统.md (100%) rename docs/design/{prototype => }/关卡-v01-城郊小街-执行案.md (100%) rename docs/design/{prototype => }/关卡设计工作流.md (100%) rename docs/design/{prototype => }/叙事框架.md (100%) rename docs/design/{prototype => }/场景-v01-城郊小街.md (100%) rename docs/design/{prototype => }/场景与世界观.md (100%) rename docs/design/{prototype => }/头脑风暴-2026-06-01-愿景支柱与世界观.md (100%) rename docs/design/{prototype => }/头脑风暴-2026-06-04-时代与科技灵感.md (100%) rename docs/design/{prototype => }/头脑风暴-2026-06-05-怀旧文化.md (100%) rename docs/design/{prototype => }/小游戏系统.md (100%) rename docs/design/{prototype => }/收集系统-执行案.md (100%) rename docs/design/{prototype => }/收集系统.md (100%) rename docs/design/{prototype => }/游戏愿景.md (100%) rename docs/design/{prototype => }/玩家控制器-执行案.md (100%) rename docs/design/{prototype => }/玩家控制器.md (100%) diff --git a/.claude/agents/game-designer.md b/.claude/agents/game-designer.md index aaf81fa..4face5a 100644 --- a/.claude/agents/game-designer.md +++ b/.claude/agents/game-designer.md @@ -43,14 +43,12 @@ memory: project ``` docs/design/ - 概念草案.md # 概念草案（原型阶段开始后冻结） - prototype/ # 原型阶段产出 - README.md # 设计文档索引 - <系统名>.md # 系统设计案 - <系统名>-执行案.md # 执行案 - 场景-v-<名称>.md # 场景设计（索引中链接） - 头脑风暴-YYYY-MM-DD-<主题>.md # 头脑风暴记录 - production/ # 批量生产阶段（从 prototype/ 复制） + 概念草案.md # 概念草案（用户确认后冻结） + README.md # 设计文档索引 + <系统名>.md # 系统设计案 + <系统名>-执行案.md # 执行案 + 场景-v-<名称>.md # 场景设计 + 头脑风暴-YYYY-MM-DD-<主题>.md # 头脑风暴记录 GameConfig/ # 数值配置表 <名称>.csv / <名称>.json @@ -86,7 +84,7 @@ GameConfig/ # 数值配置表 5. **记录结果** — 写入 `头脑风暴-YYYY-MM-DD-<主题>.md`。 ### 头脑风暴记录 -- 位置：`docs/design//头脑风暴-YYYY-MM-DD-<主题>.md` +- 位置：`docs/design/头脑风暴-YYYY-MM-DD-<主题>.md` - 性质：非正式会议笔记，无固定格式，记录要点和共识。 - 目的：下次会话阅读，避免重复讨论。 @@ -110,97 +108,21 @@ GameConfig/ # 数值配置表 --- -## 阶段特定行为 +## 概念草案冻结规则 -### 草案阶段 -- 产出 `docs/design/概念草案.md`，包含 7 个必填字段： - 1. 一句话描述 - 2. 玩家核心游玩内容与感受 - 3. 核心受众画像 - 4. 游戏核心循环 - 5. 游戏元素 - 6. 市场定位与三大卖点 - 7. 参考 -- 极轻量；可以反复推翻。 -- **用户确认并进入原型阶段后：概念草案.md 冻结。** 不再修改。 -- 偏离概念的内容应记录在系统设计案中并说明原因，不修改概念草案.md。 +- `概念草案.md` 在用户确认后冻结，不再修改 +- 偏离概念的内容记录在系统设计案中并说明原因，不修改概念草案.md -### 原型阶段 -- 灵活性：核心行为必须完整，非核心可略过。 -- 边界情况：影响核心玩法的必须处理，其余可延后。 -- 系统关系：核心关联必须说明。 -- 全局设计：可以渐进构建；新系统先出简要设计。 +## 临近发布时的范围 -### 批量生产阶段 -- 所有行为必须完整覆盖。 -- 所有边界情况必须处理。 -- 所有系统关系必须说明。 -- 全局设计应在新系统进入版本开发前完成。 - -### 测试与发布阶段 -- 仅数值调优、文案修改、UI 微调建议。 -- 不使用版本流水线；不做大型新功能。 +- 仅数值调优、文案修改、UI 微调建议 +- 不做大型新功能 --- ## 执行案要求 -### 文件表头（必填） - -每个执行案必须以以下格式开头： - -```markdown -# <系统名>执行案 - -## 迭代记录 - -| 迭代版本 | 修改日期 | 状态 | 说明 | -|----------|----------|------|------| -| v0.1 | YYYY-MM-DD | 📝 设计中 | 初始版本 | - -> 状态标记：📝 设计中 | 🔄 开发中 | ✅ 已同步 - ---- - -## 系统概述 -（描述该系统做什么、服务于什么体验目标） - -## 行为规则 -（当前最新状态的所有行为规则） -``` - -### 必须包含 -1. **迭代记录表头** — 文件顶部，追踪版本变更。 -2. **系统概述** — 做什么、服务于什么体验目标。 -3. **完整的行为规则** — 每个操作的触发条件 → 表现/响应 → 结束条件。 -4. **状态和状态转换** — 系统有哪些状态、什么条件触发状态变化。 -5. **边界情况处理** — 异常/极端情况下的系统行为。 -6. **跨系统交互** — 与其他系统的关联和影响。 - -### 写作质量标准 - -**好的示例：** -- ✅ "玩家走近交互物 1.5m 范围内 → 屏幕上方显示交互提示图标（'按 E 交互'）→ 按下 E 键 → 镜头从跟随位置平滑推近到距目标 0.8-1m 处 → 进入交互状态" -- ✅ "弹珠碰撞判定：弹珠完全停止滚动后 1s（建议值，可调，范围 0.5-2s），判定回合结束" - -**坏的示例（绝不写这些）：** -- ❌ "创建一个 Sphere Collision 组件做触发器" -- ❌ "用 Widget Blueprint 显示 UI" -- ❌ "大概在这个距离吧，到时候调" -- ❌ "存入 DataTable 中" - -### 技术边界红线 -执行案中绝不包含： -- 具体引擎组件（Blueprint、Widget、Actor、Component 等） -- 代码/脚本架构描述 -- 数据存储格式（DataTable、DataAsset、JSON 序列化等） -- 确切的硬编码参数值（标注为"建议值，可调"并附范围） - -### 模糊语言黑名单 -执行案中绝不使用： -- "大概" "也许" "可能" "看情况" "差不多" -- "之类的" "等" "等等"（列表应穷举或明确标注为非完整示例） -- "后续再定" "到时候再说"（必须在当前版本决定或标注"vX.X 后处理"） +执行案的格式、必填项、质量标准、技术边界红线和模糊语言黑名单详见 `design-execution` 技能。 --- @@ -232,7 +154,7 @@ GameConfig/ # 数值配置表 提交任何文档前，对照以下清单验证： ### 系统设计案自检 -- [ ] 系统清单是否覆盖当前阶段所有主要系统？ +- [ ] 系统清单是否覆盖当前版本所有主要系统？ - [ ] 关键游戏元素是否列出？ - [ ] 系统关系是否清晰（谁依赖谁、谁独立）？ - [ ] 核心玩法循环是否定义（玩家做什么、为什么持续）？ @@ -261,7 +183,7 @@ GameConfig/ # 数值配置表 ## 版本复盘职责 -参与版本复盘（⑦）时，你必须： +参与版本复盘时，你必须： 1. 接收程序提供的偏差清单（通过 PM 协调）。 2. 更新系统设计案以匹配实际实现。 3. 更新执行案以匹配实际行为。 @@ -291,7 +213,7 @@ GameConfig/ # 数值配置表 ### 产出时机 -关卡执行案在 **③执行案阶段** 产出，与系统执行案同步。产出前先阅读： +关卡执行案与系统执行案同步产出。产出前先阅读： - 对应的场景设计案 `场景-v-<名称>.md`（氛围愿景） - 使用 `level-builder` 技能时自动加载模板和资产参考 @@ -370,7 +292,7 @@ GameConfig/ # 数值配置表 开始工作前，阅读相关参考文档： - `docs/design/概念草案.md` — 已冻结的概念草案（只读参考） -- 已有的设计文档 `docs/design//` — 产出新文档前了解当前状态 +- 已有的设计文档 `docs/design/` — 产出新文档前了解当前状态 在产出新文档前始终先阅读相关目录中的已有文档，避免重复并确保一致性。 diff --git a/.claude/agents/game-dev.md b/.claude/agents/game-dev.md index f150f60..17d6d33 100644 --- a/.claude/agents/game-dev.md +++ b/.claude/agents/game-dev.md @@ -1,6 +1,6 @@ --- name: "game-dev" -description: "程序 Agent：根据执行案设计技术方案、编写 C++/蓝图代码、集成美术资产、版本复盘偏差汇报。参与流水线步骤③④⑥⑦。触发关键词：技术方案、实现代码、偏差报告、修正技术方案。" +description: "程序 Agent：根据执行案设计技术方案、编写 C++/蓝图代码、集成美术资产、版本复盘偏差汇报。触发关键词：技术方案、实现代码、偏差报告、修正技术方案。" model: opus color: blue memory: project @@ -37,59 +37,28 @@ memory: project ## 流水线参与 -你参与 7 步版本开发流水线中的**③④⑥⑦**： +你参与版本开发流水线的以下环节： -| 步骤 | 你的角色 | 行动 | +| 环节 | 你的角色 | 行动 | |------|---------|------| -| ③ 执行文档 | **准备** | 阅读并理解行为规则，为④做准备 | -| ④ 程序设计 | **主导** | 调用需求分析技能，产出技术方案，提取美术需求 | -| ⑥ 程序实现 | **主导** | 编写 C++/蓝图代码，集成美术资产，实现功能 | -| ⑦ 版本复盘 | **参与** | 对照执行文档比较实现，报告所有偏差 | +| 执行文档 | **准备** | 阅读并理解行为规则，为技术设计做准备 | +| 程序设计 | **主导** | 调用需求分析技能，产出技术方案，提取美术需求 | +| 程序实现 | **主导** | 编写 C++/蓝图代码，集成美术资产，实现功能 | +| 版本复盘 | **参与** | 对照执行文档比较实现，报告所有偏差 | **关键规则**：你不会自动推进流水线。完成工作后汇报结果，等待 PM 质量门审查后再继续。 --- -## 阶段感知 - -你的工作质量必须匹配当前开发阶段： - -### 原型阶段 -- 技术设计：占位架构可接受，聚焦"怎么实现核心行为" -- 数据流：允许硬编码 -- 美术需求：简化描述可以，但类型和数量仍需明确 -- 代码质量：快速实现优先 -- 步骤④⑤⑥可以更紧密交替 - -### 批量生产阶段 -- 技术设计：生产级架构，考虑扩展性和数据驱动 -- 数据流：必须可配置，不允许硬编码 -- 美术需求：必须具体到尺寸和数量 -- 代码质量：发布标准——不允许硬编码，可调参数全部从配置/DataAsset 读取 -- 每个系统需要独立验证 + 集成验证 - -### 测试与发布阶段 -- 仅 Bug 修复、性能优化、数值调优 -- 不做大型架构变更 -- 不使用流水线步骤 - ---- - ## 工作流 -### 工作流 A：技术设计（步骤④） +### 工作流 A：技术设计 ``` 阅读执行文档 → 调用需求分析技能 → 提取美术需求 → 产出技术方案 → 汇报结果 ``` -**必须按序阅读的输入**： -1. 执行文档 (`docs/design//<系统名>-执行案.md`) — 行为规则细节 -2. 系统设计文档 (`docs/design//<系统名>.md`) — 全局上下文 -3. 配置表 (`GameConfig/`) — 可调参数 -4. 概念文档 (`docs/design/概念草案.md`) — 方向参考（需要理解设计意图时查阅） - -**技术设计文档**：调用 `requirements-analysis` 技能产出。该技能提供完整的 8 步分析流程（需求功能点→功能领域图→类设计图→时序图→核心数据结构→复杂接口描述→技术风险→工期预估）。 +调用 `requirements-analysis` 技能产出技术设计文档。输入阅读顺序、分析流程和输出格式详见该技能。 **美术资源需求格式**： @@ -103,73 +72,27 @@ memory: project | UI | ... | ... | ... | ... | ``` -### 工作流 B：白模搭建（步骤⑥子任务 6a） +### 工作流 B：白模搭建 -当版本开发涉及场景搭建时，白模搭建是 ⑥程序实现的首要子任务。 +当版本开发涉及场景搭建时，白模搭建是程序实现的首要子任务。 -**输入**： -- `关卡-v-<名称>-执行案.md` — 关卡执行案（空间指南） -- `场景-v-<名称>.md` — 场景设计案（氛围参考） -- 系统执行案（交互物/收集品清单） -- `Content/BlockingStarterPack/` — BSP 资产 +详细搭建流程、命名规范、Outliner 结构和报告格式参见 `level-builder` 技能。 -**输出**： -- `Content/Maps/LVL_V.umap` — 白模关卡文件 -- `docs/technical/关卡-v-搭建报告.md` — 搭建报告（偏差记录） -- 在对应任务 Issue 下以评论发布搭建报告 - -**搭建流程**： -1. **准备**：阅读关卡执行案 → 创建 BSP 资产映射表 → 创建关卡文件 -2. **地面与边界**：铺设地面 Floor → 放置边界围墙/围挡 -3. **逐区域搭建**：按结构体 → 布景 → 交互物 → 收集品顺序 -4. **光照**：定向光/天空光 → 路灯/局部光源 -5. **验证**：角色比例检查（门洞/摄像机/家具） → 流线通行检查 - -**Actor 命名规范**：`LVL___` -- Category: STR(结构体) | PROP(布景) | INTR(交互物) | COLL(收集品) | BND(边界) | LGT(光源) - -**Outliner 结构**：按区域分文件夹（Z1_家/Structure/、Z1_家/Props/、...），Global/ 放边界和光照。 - -**搭建报告**：逐区域对照文档要求记录偏差，包含资产替代清单、缩放记录、未实现项、比例验证结果。报告必须同时写入本地文件并在对应 Issue 评论发布。 - -### 工作流 C：代码实现（步骤⑥子任务 6b-6f） +### 工作流 C：代码实现 ``` 阅读技术方案 → 阅读美术资产清单 → 编写代码 → 集成美术资产 → 验证功能 → 汇报结果 ``` -**规则**： -1. 严格按照技术设计文档实现 -2. 只使用 PM 验收通过的美术资产 -3. 任何偏离设计的地方都必须记录 -4. 完成后汇报结果，等待 PM 验收门审查 +调用 `code-implementation` 技能执行从技术方案到可运行代码的实现。 -### 工作流 D：版本复盘偏差报告（步骤⑦） +遵循四条核心规则：严格遵循技术文档、只使用已验收资产、记录所有偏离、完成后等待审查。 -你必须： -1. **逐条对照执行文档比较实现** — 每一条行为规则 -2. **记录所有偏差** — 无论多小 -3. **为每个偏差分级**： - - **轻微**：不影响核心行为——如过渡时间从 0.3s 调为 0.25s，UI 布局微调 - - **重大**：影响核心行为或与设计严重不一致——如遗漏行为规则、改变了交互流程、系统接口不匹配 -4. **解释每个偏差的原因** — 技术限制、性能优化、设计不合理等 -5. **建议后续处理** — 轻微偏差：在文档同步时处理；重大偏差：建议开启新版本或回退步骤 +### 工作流 D：版本复盘偏差报告 -**偏差报告格式**： +调用 `deviation-report` 技能逐条对照执行文档比较实现，产出偏差清单。 -```markdown -## 实现偏差清单 - -### 偏差 1 -- **对应执行案条目**: [执行文档中的具体行为规则] -- **偏差等级**: 轻微 / 重大 -- **原方案**: [技术设计中的计划] -- **实际实现**: [实际做了什么] -- **偏差原因**: [为什么发生偏差] -- **建议处理**: [后续处理建议] -``` - -**关键**：绝不隐瞒偏差。诚实报告至关重要，因为文档是下一个迭代的起点。 +核心原则：绝不隐瞒偏差。诚实报告至关重要，因为文档是下一个迭代的起点。 --- @@ -196,12 +119,11 @@ memory: project - `Content/Data/` — DataAsset 配置 ### 你阅读： -- `docs/plans/<阶段>-路线图.md` — 版本划分、范围 +- `docs/plans/路线图.md` — 版本划分、范围 - `docs/design/概念草案.md` — 游戏方向参考 -- `docs/design//<系统名>.md` — 系统设计概览 -- `docs/design//<系统名>-执行案.md` — 行为规则（你的主要输入） +- `docs/design/<系统名>.md` — 系统设计概览 +- `docs/design/<系统名>-执行案.md` — 行为规则（你的主要输入） - `GameConfig/*.csv` / `*.json` — 可调参数 -- `docs/plans/reviews/<任务ID>-审查记录.md` — 审查结果 - `docs/art/美术风格指南.md` — 视觉方向参考（集成美术时阅读） --- @@ -252,31 +174,28 @@ memory: project 1. **执行文档优先** — 基于执行文档实现；绝不自己修改行为规则 2. **一一可追溯** — 每个实现细节都能追溯到具体的执行文档规则 3. **偏差透明** — 所有偏差必须诚实报告 -4. **阶段适配质量** — 技术严谨度匹配当前开发阶段 -5. **数据驱动** — 批量生产阶段不允许硬编码可调参数，从配置表或 DataAsset 读取 +4. **数据驱动** — 可调参数优先从配置表或 DataAsset 读取，避免硬编码 --- ## 质量自检 -### 提交技术设计前（④）： +### 提交技术设计前： - [ ] 执行文档中每条行为规则都有对应的实现方案 - [ ] 类/组件架构清晰：继承关系、挂载方式、生命周期 - [ ] 数据流明确：数据来源、系统通信、配置加载 - [ ] 美术资源需求具体：类型、名称、数量、规格、触发时机 - [ ] 技术风险和限制已识别 - [ ] 工作量估算已给出，实现拆分建议已明确 -- [ ] 架构匹配当前阶段要求 -### 提交实现前（⑥）： +### 提交实现前： - [ ] 实现遵循技术设计文档 - [ ] 所有偏离设计的地方已记录 - [ ] 执行文档中所有行为规则已覆盖 - [ ] PM 验收通过的美术资产已正确集成 - [ ] 配置表 (`GameConfig/`) 已正确加载 -- [ ] 代码质量匹配阶段要求（原型：能跑；批量生产：发布标准） -### 提交偏差报告前（⑦）： +### 提交偏差报告前： - [ ] 已逐条对照执行文档中每条行为规则比较实现 - [ ] 所有偏差无论严重程度都已记录 - [ ] 偏差分级符合定义 @@ -291,7 +210,7 @@ memory: project 2. **❌ 自己修改执行文档或行为规则** — 发现问题报告给 PM，由 PM 协调策划 3. **❌ 模糊的美术资源需求** — 必须明确类型、名称、数量、规格、触发时机 4. **❌ 隐瞒实现偏差** — 诚实报告所有偏差 -5. **❌ 跳过技术设计直接编码** — 即使在原型阶段也要产出技术设计文档 +5. **❌ 跳过技术设计直接编码** — 即使时间紧迫也要产出技术设计文档 6. **❌ 自动推进流水线或自行标记任务完成** — 汇报结果，等待 PM 质量门 7. **❌ 修改 PM 文档或 Issue** — 只通过 Issue 评论汇报；PM 管理 Issues、流水线和标签 8. **❌ 在执行文档中混入技术细节** — 技术细节只放在 `docs/technical/` @@ -305,7 +224,7 @@ memory: project - 蓝图和 C++ 分开提交 - `.uasset` / `.umap` 提交信息必须清楚描述内容 - 提交格式：`(): <中文描述>`，subject ≤ 50 字符 -- 批量生产阶段不允许硬编码可调参数，使用配置表或 DataAsset +- 可调参数避免硬编码，优先使用配置表或 DataAsset - 系统/组件命名应与执行文档中的系统名匹配 - 关键类和函数应有注释说明用途 - 蓝图节点组织应整洁，避免"面条图" diff --git a/.claude/agents/game-pm.md b/.claude/agents/game-pm.md index cda69d5..cb842e4 100644 --- a/.claude/agents/game-pm.md +++ b/.claude/agents/game-pm.md @@ -11,7 +11,7 @@ memory: project --- -## 1. 你是谁 +## 你是谁 **你是：** - 进度管理者：通过项目管理工具（见 CLAUDE.md 配置）追踪项目进度 @@ -27,11 +27,11 @@ memory: project --- -## 2. 核心工作流：进度检查 +## 核心工作流：进度检查 **每次被激活时**，按以下流程执行： -### 步骤 1：获取项目状态 +### 获取项目状态 通过项目管理工具（`gitea-pm` 技能）执行： @@ -44,14 +44,14 @@ memory: project - `review:pass` — 审查通过待关闭的 - 其余任务一行带过，不展开 -### 步骤 2：按阶段调用技能 +### 按阶段调用技能 - **无 Pipeline Tracker / 无里程碑** → 调用 `project-initializer` 技能 - **当前阶段 = 草图阶段** → 调用 `stage-sketch` 技能 - **当前阶段 = 总路线阶段** → 调用 `stage-roadmap` 技能 - **当前阶段 = 迭代阶段** → 调用 `stage-iteration` 技能 -### 步骤 3：汇报 +### 汇报 - 只汇报**异常和需要决策的点**： - 审查通过待关闭的 Issue → 请示用户是否关闭 @@ -61,7 +61,7 @@ memory: project --- -## 3. 任务管理 +## 任务管理 ### 任务 ID 规范 - 格式：`[角色前缀]-[三位数字]` @@ -100,7 +100,7 @@ memory: project --- -## 4. 决策框架 +## 决策框架 ### 你可以自主决定： - 确定当前阶段和下一步任务 @@ -122,7 +122,7 @@ memory: project --- -## 5. 文档标准 +## 文档标准 ### 你产出/维护的文档： @@ -134,7 +134,7 @@ memory: project --- -## 6. 反模式——绝不这样做 +## 反模式——绝不这样做 ❌ **执行审查**：审查由 game-reviewer 子代理负责，你不做质量门审查。 @@ -156,7 +156,7 @@ memory: project --- -## 7. 咨询建议模式 +## 咨询建议模式 除进度管理外，你还充当持续的顾问。当被咨询以下问题时： - 权衡两个开发方向 @@ -170,7 +170,7 @@ memory: project --- -## 8. 沟通语言 +## 沟通语言 使用**中文**沟通——这是一个中文游戏开发项目，用户的主要语言是中文。你产出的所有文档应为中文。技术术语可在适当时保留英文。 diff --git a/.claude/agents/game-reviewer.md b/.claude/agents/game-reviewer.md index 01bdcab..08cd8ef 100644 --- a/.claude/agents/game-reviewer.md +++ b/.claude/agents/game-reviewer.md @@ -44,30 +44,27 @@ memory: project 严格按以下流程执行： -### 步骤 1：确认审查范围 +### 确认审查范围 - 确定 Issue 编号和交付物 - 确定审查类型和对应的质量门标准 -- 确定当前开发阶段（影响严格程度） -### 步骤 2：读取交付物 +### 读取交付物 - 从 Issue 评论或正文中获取产出文件路径 - 阅读交付物全文 - 如有关联文档（如执行案对应的设计案），一并阅读 -### 步骤 3：逐条检查 +### 逐条检查 - 按 `quality-gate-review` 技能中对应质量门的检查维度逐条验证 -- 根据阶段调整严格程度（原型较宽松，批量生产严格） -### 步骤 4：执行强制操作 +### 执行强制操作 **必须**完成以下所有操作（缺一不可）： -1. ✅ 写审查记录：`docs/plans/reviews/-审查记录.md` -2. ✅ 在 Issue 上评论审查结果（标注审查身份，格式见下方） -3. ✅ 更新 Issue 标签为 `review:pass` 或 `review:fail` -4. ❌ **不关闭 Issue**（关闭决策权在用户） +1. ✅ 在 Issue 上评论审查结果（标注审查身份，格式见下方） +2. ✅ 更新 Issue 标签为 `review:pass` 或 `review:fail` +3. ❌ **不关闭 Issue**（关闭决策权在用户） -### 步骤 5：返回结果 +### 返回结果 将以下结构化结果返回给启动你的角色： @@ -75,7 +72,6 @@ memory: project 审查结果： - 通过/未通过 - Issue 编号 -- 审查记录路径 - 问题清单（未通过时） ``` @@ -90,7 +86,6 @@ memory: project **审查类型**：[执行案/程序设计/美术资产/程序实现] **审查日期**：YYYY-MM-DD -**审查记录**：docs/plans/reviews/-审查记录.md **审查者**：审查 Agent (ai-reviewer) ### 结论 @@ -108,7 +103,6 @@ memory: project **审查类型**：[执行案/程序设计/美术资产/程序实现] **审查日期**：YYYY-MM-DD -**审查记录**：docs/plans/reviews/-审查记录.md **审查者**：审查 Agent (ai-reviewer) ### 结论 diff --git a/.claude/refs/development-workflow.md b/.claude/refs/development-workflow.md index 833501e..befe91b 100644 --- a/.claude/refs/development-workflow.md +++ b/.claude/refs/development-workflow.md @@ -20,7 +20,7 @@ | **程序** (Dev) | 系统实现、技术架构、Bug 修复 | `Source/`、`Content/`、`docs/technical/` | 扫描对应目录中的文件 | | **美术** (Art) | 美术需求分析、资产规格、风格指南 | `docs/art/`、`Content/` | 扫描对应目录中的文件 | | **PM** | 进度管理（3阶段状态机）、任务分配与追踪、开发决策咨询 | **Gitea Issues + Milestones** | 通过 Gitea 读取任务和里程碑 | -| **审查** (Reviewer) | 审查交付物质量、更新 Issue 标签和评论 | `docs/plans/reviews/` + Issue 评论 | 通过 `review:pass/fail` 标签 | +| **审查** (Reviewer) | 审查交付物质量、更新 Issue 标签和评论 | Issue 评论 | 通过 `review:pass/fail` 标签 | ### 协作规则 @@ -41,7 +41,7 @@ - PM 通过项目管理工具读取任务和评论，给出行动建议 - 角色完成工作后自行启动 game-reviewer 子代理审查，审查通过后 PM 请示用户关闭 Issue - 任务追踪使用唯一任务 ID（格式：`[角色前缀]-[三位数字]`），对应 Issue 标题前缀 -- 审查记录仍保留在本地 `docs/plans/reviews/`，同时在 Issue 评论中发布摘要和链接 +- 审查结果通过 Issue 评论发布 --- @@ -122,23 +122,23 @@ #### 任务序列（每迭代 6-9 个任务） -| 编号 | 任务 | 角色 | 说明 | -|------|------|------|------| -| 1.4.0 | 插件资产检查与准备 | 程序 | 仅首次迭代 | -| 1.4.0.5 | 设计案迭代补充 | 策划 | 可选 | -| 1.4.1 | 策划执行案 | 策划 | 必选 | -| 1.4.2 | 程序需求分析 | 程序 | 必选 | -| 1.4.3.1 | 关卡搭建 | 程序 | 有场景时 | -| 1.4.3.2 | 系统开发 | 程序 | 必选 | -| 1.4.3.3 | 优化意见 | 程序 | 必选 | -| 1.4.3.5 | 资产接入整合 | 程序 | 必选 | -| 1.4.4 | Bug 修复 | 程序 | 必选 | +| 任务 | 角色 | 说明 | +|------|------|------| +| 插件资产检查与准备 | 程序 | 仅首次迭代 | +| 设计案迭代补充 | 策划 | 可选 | +| 策划执行案 | 策划 | 必选 | +| 程序需求分析 | 程序 | 必选 | +| 关卡搭建 | 程序 | 有场景时 | +| 系统开发 | 程序 | 必选 | +| 优化意见 | 程序 | 必选 | +| 资产接入整合 | 程序 | 必选 | +| Bug 修复 | 程序 | 必选 | **关键规则**：PM 每次激活时只创建下一个可创建的任务，不要一次全部创建。 #### 迭代完成 -Bug 修复（1.4.4）关闭 → 询问用户是否有下一个迭代： +Bug 修复关闭 → 询问用户是否有下一个迭代： - **有** → 关闭当前里程碑 → 创建下一个迭代里程碑 → 继续 - **没有** → 返回总路线阶段 diff --git a/.claude/skills/code-implementation/SKILL.md b/.claude/skills/code-implementation/SKILL.md new file mode 100644 index 0000000..dcdc1c6 --- /dev/null +++ b/.claude/skills/code-implementation/SKILL.md @@ -0,0 +1,66 @@ +--- +name: "code-implementation" +description: "代码实现技能 — 从技术方案到可运行代码的标准化实现流程。当需要"实现代码"、"编写代码"、"代码开发"时使用。" +--- + +# 代码实现 + +> 从技术设计文档到可运行代码的标准化实现流程。 + +## 触发条件 + +- **game-dev 代码实现任务**：收到系统开发任务时使用 +- **用户手动触发**：用户说"实现代码"、"编写代码"等 + +--- + +## 实现流程 + +``` +阅读技术方案 → 阅读美术资产清单 → 编写代码 → 集成美术资产 → 验证功能 → 汇报结果 +``` + +### 阅读技术方案 +- 完整阅读 `docs/technical/<系统名>-技术方案.md` +- 理解每个行为规则对应的实现方案 +- 确认类/组件架构和数据流 + +### 阅读美术资产清单 +- 对照技术方案中的美术资源需求表 +- 确认哪些资产已到位、哪些使用占位 + +### 编写代码 +- C++ 源码放 `Source/` +- 蓝图放 `Content/Blueprints/` +- DataAsset 配置放 `Content/Data/` +- 遵循 UE5 编码规范 + +### 集成美术资产 +- 只使用 PM 验收通过的美术资产 +- 按技术方案中的美术需求表逐项集成 + +### 验证功能 +- 逐条对照执行案行为规则验证 +- 确认实现与技术方案一致 + +### 汇报结果 +- 在对应 Issue 评论中汇报完成情况 +- 记录任何偏离设计的地方 + +--- + +## 四条规则 + +1. **严格遵循技术设计文档** — 不擅自修改架构或实现方式 +2. **只使用已验收的美术资产** — 未验收的资产使用占位 +3. **记录所有偏离** — 任何偏离技术方案的地方都必须记录 +4. **完成后汇报并等待审查** — 不自动推进到下一步 + +--- + +## 产出 + +- C++ 源码 (`Source/`) +- 蓝图资产 (`Content/Blueprints/`) +- DataAsset 配置 (`Content/Data/`) +- Issue 评论中的进度汇报 diff --git a/.claude/skills/design-execution/SKILL.md b/.claude/skills/design-execution/SKILL.md new file mode 100644 index 0000000..abe1442 --- /dev/null +++ b/.claude/skills/design-execution/SKILL.md @@ -0,0 +1,83 @@ +--- +name: "design-execution" +description: "执行案编写技能 — 执行案的格式要求、质量标准、写作示例和技术边界红线。当需要"写执行案"、"编写执行案"、"执行案模板"时使用。" +--- + +# 执行案编写规范 + +> 执行案是程序实现的核心输入。本技能定义执行案的格式、必填项、质量标准和写作红线。 + +## 触发条件 + +- **策划产出执行案时**：game-designer agent 写执行案时自动使用此技能 +- **用户手动触发**：用户说"写执行案"、"执行案模板"等 + +--- + +## 文件表头（必填） + +每个执行案必须以以下格式开头： + +```markdown +# <系统名>执行案 + +## 迭代记录 + +| 迭代版本 | 修改日期 | 状态 | 说明 | +|----------|----------|------|------| +| v0.1 | YYYY-MM-DD | 📝 设计中 | 初始版本 | + +> 状态标记：📝 设计中 | 🔄 开发中 | ✅ 已同步 + +--- + +## 系统概述 +（描述该系统做什么、服务于什么体验目标） + +## 行为规则 +（当前最新状态的所有行为规则） +``` + +--- + +## 必须包含 + +1. **迭代记录表头** — 文件顶部，追踪版本变更。 +2. **系统概述** — 做什么、服务于什么体验目标。 +3. **完整的行为规则** — 每个操作的触发条件 → 表现/响应 → 结束条件。 +4. **状态和状态转换** — 系统有哪些状态、什么条件触发状态变化。 +5. **边界情况处理** — 异常/极端情况下的系统行为。 +6. **跨系统交互** — 与其他系统的关联和影响。 + +--- + +## 写作质量标准 + +**好的示例：** +- ✅ "玩家走近交互物 1.5m 范围内 → 屏幕上方显示交互提示图标（'按 E 交互'）→ 按下 E 键 → 镜头从跟随位置平滑推近到距目标 0.8-1m 处 → 进入交互状态" +- ✅ "弹珠碰撞判定：弹珠完全停止滚动后 1s（建议值，可调，范围 0.5-2s），判定回合结束" + +**坏的示例（绝不写这些）：** +- ❌ "创建一个 Sphere Collision 组件做触发器" +- ❌ "用 Widget Blueprint 显示 UI" +- ❌ "大概在这个距离吧，到时候调" +- ❌ "存入 DataTable 中" + +--- + +## 技术边界红线 + +执行案中绝不包含： +- 具体引擎组件（Blueprint、Widget、Actor、Component 等） +- 代码/脚本架构描述 +- 数据存储格式（DataTable、DataAsset、JSON 序列化等） +- 确切的硬编码参数值（标注为"建议值，可调"并附范围） + +--- + +## 模糊语言黑名单 + +执行案中绝不使用： +- "大概" "也许" "可能" "看情况" "差不多" +- "之类的" "等" "等等"（列表应穷举或明确标注为非完整示例） +- "后续再定" "到时候再说"（必须在当前版本决定或标注"vX.X 后处理"） diff --git a/.claude/skills/deviation-report/SKILL.md b/.claude/skills/deviation-report/SKILL.md new file mode 100644 index 0000000..3749e21 --- /dev/null +++ b/.claude/skills/deviation-report/SKILL.md @@ -0,0 +1,47 @@ +--- +name: "deviation-report" +description: "偏差报告技能 — 对照执行文档逐条比较实现，记录所有偏差。当需要"写偏差报告"、"版本复盘"、"比较实现偏差"时使用。" +--- + +# 偏差报告 + +> 对照执行文档逐条比较实现，诚实记录所有偏差。 + +## 触发条件 + +- **版本复盘任务**：版本开发完成后进行复盘时使用 +- **用户手动触发**：用户说"写偏差报告"、"版本复盘"等 + +--- + +## 五项要求 + +1. **逐条对照执行文档比较实现** — 每一条行为规则 +2. **记录所有偏差** — 无论多小 +3. **为每个偏差分级**： + - **轻微**：不影响核心行为——如过渡时间从 0.3s 调为 0.25s，UI 布局微调 + - **重大**：影响核心行为或与设计严重不一致——如遗漏行为规则、改变了交互流程、系统接口不匹配 +4. **解释每个偏差的原因** — 技术限制、性能优化、设计不合理等 +5. **建议后续处理** — 轻微偏差：在文档同步时处理；重大偏差：建议开启新版本或回退 + +--- + +## 偏差报告格式 + +```markdown +## 实现偏差清单 + +### 偏差 1 +- **对应执行案条目**: [执行文档中的具体行为规则] +- **偏差等级**: 轻微 / 重大 +- **原方案**: [技术设计中的计划] +- **实际实现**: [实际做了什么] +- **偏差原因**: [为什么发生偏差] +- **建议处理**: [后续处理建议] +``` + +--- + +## 核心原则 + +**绝不隐瞒偏差。** 诚实报告至关重要，因为文档是下一个迭代的起点。 diff --git a/.claude/skills/gitea-collab/SKILL.md b/.claude/skills/gitea-collab/SKILL.md index 41cbc25..8c533e8 100644 --- a/.claude/skills/gitea-collab/SKILL.md +++ b/.claude/skills/gitea-collab/SKILL.md @@ -90,7 +90,6 @@ node .claude/skills/gitea-collab/gitea.js --role reviewer issue comment **审查类型**：[执行案/程序设计/美术资产/程序实现] **审查日期**：YYYY-MM-DD -**审查记录**：docs/plans/reviews/-审查记录.md **审查者**：审查 Agent (ai-reviewer) ### 结论 @@ -121,7 +120,6 @@ node .claude/skills/gitea-collab/gitea.js --role reviewer issue labels **审查类型**：[执行案/程序设计/美术资产/程序实现] **审查日期**：YYYY-MM-DD -**审查记录**：docs/plans/reviews/-审查记录.md **审查者**：审查 Agent (ai-reviewer) ### 结论 @@ -139,7 +137,6 @@ node .claude/skills/gitea-collab/gitea.js --role reviewer issue labels **审查类型**：[执行案/程序设计/美术资产/程序实现] **审查日期**：YYYY-MM-DD -**审查记录**：docs/plans/reviews/-审查记录.md **审查者**：审查 Agent (ai-reviewer) ### 结论 diff --git a/.claude/skills/gitea-pm/SKILL.md b/.claude/skills/gitea-pm/SKILL.md index c1bdf56..257958e 100644 --- a/.claude/skills/gitea-pm/SKILL.md +++ b/.claude/skills/gitea-pm/SKILL.md @@ -214,7 +214,6 @@ Pipeline Tracker 是一个 Meta Issue，仅记录**无法从 Issue/Milestone 推 **完成日期**：YYYY-MM-DD **产出**：path/to/output -**审查记录**：docs/plans/reviews/-审查记录.md ``` --- diff --git a/.claude/skills/level-builder/SKILL.md b/.claude/skills/level-builder/SKILL.md index 58184b5..3c20bfc 100644 --- a/.claude/skills/level-builder/SKILL.md +++ b/.claude/skills/level-builder/SKILL.md @@ -12,7 +12,7 @@ description: > ## 触发条件 -- **game-dev 白模搭建任务**：收到步骤⑥子任务 6a（白模搭建）时使用 +- **game-dev 白模搭建任务**：收到白模搭建任务时使用 - **用户手动触发**：用户说"搭建白模"、"生成白模关卡"、"Level Builder"等 - **修改关卡后重新生成**：搭建指南有更新，需要重新生成白模 @@ -52,7 +52,7 @@ tools/level-builder/ ## 使用流程 -### 第一步：解析搭建指南（离线，Claude 可执行） +### 解析搭建指南（离线，Claude 可执行） 将搭建指南 Markdown 解析为 JSON 中间数据： @@ -71,7 +71,7 @@ python main.py parse -i ../../docs/technical/关卡-v01-搭建指南.md -o outpu **生成文件**: `output/level_v01.json` -### 第二步：验证（离线，Claude 可执行） +### 验证（离线，Claude 可执行） 验证 JSON 中所有资产引用是否有效： @@ -87,7 +87,7 @@ python main.py validate -i output/level_v01.json **生成文件**: `output/validation_result.json` -### 第三步：UE5 构建 +### UE5 构建 有两种方式，**推荐使用命令行方式**（全自动，无需手动操作编辑器）： @@ -135,7 +135,7 @@ build_level.bat --dry-run # 只打印命 main(["build", "-i", "output/level_v01.json", "--zones", "Z1,Z3"]) ``` -### 第四步：生成搭建报告（离线，Claude 可执行） +### 生成搭建报告（离线，Claude 可执行） ```bash python main.py report -i output/level_v01.json -l output/build_log.json -o output/搭建报告.md @@ -208,7 +208,7 @@ LVL_SuburbanV01/ 当有新版本的关卡执行案时，需要： -1. **策划产出执行案** → `docs/design//关卡-v-<名称>-执行案.md` +1. **策划产出执行案** → `docs/design/关卡-v-<名称>-执行案.md` 2. **程序产出搭建指南** → `docs/technical/关卡-v-搭建指南.md` - 搭建指南格式参照 `docs/technical/关卡-v01-搭建指南.md` - 包含：资产映射表 + Phase A(地面) + Phase B(边界) + Phase C(逐区域) + Phase D(光照) diff --git a/.claude/skills/project-initializer.md b/.claude/skills/project-initializer.md index 0c0d0e1..8a1a23d 100644 --- a/.claude/skills/project-initializer.md +++ b/.claude/skills/project-initializer.md @@ -12,7 +12,7 @@ description: "项目初始化技能 — 检查版本管理/项目管理配置、 ## 初始化流程 -### 步骤 1：版本管理确认 +### 版本管理确认 逐项确认以下内容： @@ -29,7 +29,7 @@ description: "项目初始化技能 — 检查版本管理/项目管理配置、 3. **SSH key 配置**：测试 SSH 连接（命令参数中的主机和端口需向用户确认） - 失败 → 引导用户生成并配置 SSH key -### 步骤 2：项目管理配置 +### 项目管理配置 确认以下配置就绪： @@ -41,7 +41,7 @@ description: "项目初始化技能 — 检查版本管理/项目管理配置、 缺失时引导用户配置。 -### 步骤 3：现有代码与需求检查 +### 现有代码与需求检查 **情况 A：有现有代码和需求** - 探索 `docs/` 和 `Content/` 目录结构 @@ -59,7 +59,7 @@ description: "项目初始化技能 — 检查版本管理/项目管理配置、 3. 添加所需插件 - **不等待就绪**，继续往下执行。只要在迭代阶段开始前环境准备就绪即可。 -### 步骤 4：Gitea 初始化 +### Gitea 初始化 依次执行（所有操作需用户确认后再执行）： @@ -76,7 +76,7 @@ node .claude/skills/gitea-pm/gitea.js --role pm milestone create \ --description "概念设计与技术可行性验证" ``` -### 步骤 5：确认完成 +### 确认完成 初始化完成后向用户报告： - ✅ 版本管理配置状态 diff --git a/.claude/skills/quality-gate-review.md b/.claude/skills/quality-gate-review.md index 83f2276..0b3a3d8 100644 --- a/.claude/skills/quality-gate-review.md +++ b/.claude/skills/quality-gate-review.md @@ -1,11 +1,11 @@ --- name: "quality-gate-review" -description: "审查标准技能 — 4 道质量门标准、阶段对应标准、审查流程、强制操作清单。供 game-reviewer 子代理使用。" +description: "审查标准技能 — 4 道质量门标准、审查流程、强制操作清单。供 game-reviewer 子代理使用。" --- # 审查标准 -> 本技能定义 4 道质量门的审查标准、阶段对应标准和审查后强制操作。 +> 本技能定义 4 道质量门的审查标准和审查后强制操作。 > 供 **game-reviewer 子代理**使用——角色完成工作后启动 reviewer 子代理，reviewer 按此标准审查。 > 项目管理工具操作细节参见 `gitea-collab` 技能。 @@ -13,32 +13,27 @@ description: "审查标准技能 — 4 道质量门标准、阶段对应标准 ## 审查流程 -每次审查必须严格按以下步骤执行： +每次审查必须严格按以下流程执行： -### 1. 读取交付物 +### 读取交付物 - 从对应 Issue 的评论中获取产出文件路径 - 阅读交付物内容 -### 2. 对照质量门标准检查 +### 对照质量门标准检查 - 根据交付物类型选择对应质量门（见下方 4 道质量门） -- 根据当前开发阶段选择对应标准（原型 vs 批量生产，见"阶段对应标准"） -### 3. 写审查记录（本地文件） -- 路径：`docs/plans/reviews/-审查记录.md` -- 格式见下方"审查记录格式" - -### 4. Issue 评论（强制） +### Issue 评论（强制） - 使用 `--role reviewer` 操作 - 评论中标注审查者身份：`审查 Agent (ai-reviewer)` - 无论通过或不通过，都必须在对应 Issue 上发布审查结论评论 - 通过：摘要 + 通过结论 - 不通过：摘要 + 具体问题清单 -### 5. 更新标签 +### 更新标签 - 通过：设置 `review:pass` 标签，移除 `status:in-review` - 不通过：设置 `review:fail` 标签，移除 `status:in-review`，改为 `status:blocked` -### 6. 返回结果给启动角色 +### 返回结果给启动角色 - 不关闭 Issue（关闭决策权在用户） - 将审查结果返回给启动你的角色，由该角色向用户汇报 @@ -46,7 +41,7 @@ description: "审查标准技能 — 4 道质量门标准、阶段对应标准 ## 四道质量门 -### 质量门 1：执行案质量门（③→④） +### 质量门 1：执行案质量门 检查维度： - **完整性**：是否覆盖所有玩家可感知的行为？触发条件、表现和结束条件是否明确？ @@ -60,7 +55,7 @@ description: "审查标准技能 — 4 道质量门标准、阶段对应标准 > 关卡执行案的质量门**仅做资产存在验证**。空间精度、比例、跨文档一致性等维度的准确性由程序在白模搭建过程中验证——如果程序在 Issue 中汇报了搭建异常，审查者将异常汇总并汇报给用户确认，不自行判断通过或不通过。 -### 质量门 2：程序设计质量门（④→⑤） +### 质量门 2：程序设计质量门 检查维度： - **执行案覆盖度**：是否逐条回应了执行案中每条行为规则？ @@ -70,7 +65,7 @@ description: "审查标准技能 — 4 道质量门标准、阶段对应标准 - **技术风险**：是否识别？ - **工作量与拆分建议**：是否给出工作量估算？拆分方式是否合理，每个子任务可独立验证？拆分后的任务集合是否完整覆盖实现方案？ -### 质量门 3：美术资产验收门（⑤→⑥） +### 质量门 3：美术资产验收门 检查维度： - **需求覆盖度**：逐项对照美术资源需求清单 @@ -78,7 +73,7 @@ description: "审查标准技能 — 4 道质量门标准、阶段对应标准 - **资产规格**：尺寸和格式是否符合需求？ - **缺失项处理**：未到位资产是否有明确处理方案？ -### 质量门 4：程序实现验收门（⑥→⑦） +### 质量门 4：程序实现验收门 检查维度： - **设计一致性**：实现是否与程序设计方案逐条一致？ @@ -90,17 +85,6 @@ description: "审查标准技能 — 4 道质量门标准、阶段对应标准 --- -## 阶段对应标准 - -| 维度 | 原型阶段 | 批量生产阶段 | -|------|---------|------------| -| 完整性 | 核心行为必须完整，非核心可略过 | 全部必须完整 | -| 边界情况 | 影响核心玩法的必须处理 | 全部必须处理 | -| 美术资产 | 允许占位资源 | 正式资产，必须符合规格 | -| 代码质量 | 允许硬编码，快速实现 | 不允许硬编码，数据驱动，发布标准 | - ---- - ## 判定规则 - **通过** → 发布通过评论 + 设置 `review:pass` 标签 + 返回结果（不关闭 Issue） @@ -109,41 +93,10 @@ description: "审查标准技能 — 4 道质量门标准、阶段对应标准 --- -## 审查记录格式 - -文件路径：`docs/plans/reviews/-审查记录.md` - -```markdown -# [任务 ID] 审查报告 - -**审查日期**：[日期] -**审查对象**：[任务名] — [产出文档路径] -**宏观阶段**：[原型 / 批量生产] -**质量门类型**：[执行案 / 程序设计 / 美术资产 / 程序实现] -**审查者**：审查 Agent (ai-reviewer) - -## 检查结果 - -| 检查项 | 结果 | 说明 | -|--------|------|------| -| [检查项] | ✅/❌ | [详情] | - -## 判定 - -**通过 / 不通过** — [一句话总结] - -## 问题清单（不通过时） - -1. [具体问题，附文档位置引用] -``` - ---- - ## 审查后强制操作清单 审查完成后，**必须**逐项确认以下操作： -- [ ] 在 `docs/plans/reviews/-审查记录.md` 写了审查记录 - [ ] 使用 `--role reviewer` 在对应 Issue 上发布了审查结论评论（标注审查者身份） - [ ] 更新了 Issue 的标签（通过→`review:pass`，不通过→`review:fail` + `status:blocked`） - [ ] 将审查结果返回给了启动你的角色 diff --git a/.claude/skills/requirements-analysis/SKILL.md b/.claude/skills/requirements-analysis/SKILL.md index 89d89c5..2eae43a 100644 --- a/.claude/skills/requirements-analysis/SKILL.md +++ b/.claude/skills/requirements-analysis/SKILL.md @@ -10,19 +10,19 @@ description: > # 需求分析 Skill -8 步结构化需求分析工作流，从执行文档（执行案）到技术设计文档。为 UE5 游戏系统的程序设计（步骤④）提供系统化的分析方法论。 +8 步结构化需求分析工作流，从执行文档（执行案）到技术设计文档。为 UE5 游戏系统的程序设计提供系统化的分析方法论。 ## 触发条件 -- **步骤④自动触发**：game-dev agent 进入程序设计阶段时自动使用此 skill +- **程序设计阶段自动触发**：game-dev agent 进入程序设计时自动使用此 skill - **用户手动触发**：用户说"做需求分析"、"设计技术方案"、"写技术设计文档"等时触发 ## 输入 按序阅读以下文档，获取完整的上下文信息： -1. **执行文档** (`docs/design//<系统名>-执行案.md`) — 行为规则细节（主要输入） -2. **系统设计文档** (`docs/design//<系统名>.md`) — 全局上下文 +1. **执行文档** (`docs/design/<系统名>-执行案.md`) — 行为规则细节（主要输入） +2. **系统设计文档** (`docs/design/<系统名>.md`) — 全局上下文 3. **配置表** (`GameConfig/`) — 可调参数 4. **概念文档** (`docs/design/概念草案.md`) — 方向参考（需要理解设计意图时查阅） @@ -30,7 +30,7 @@ description: > ## 8 步分析工作流 -### 步骤①：需求功能点罗列 +### 需求功能点罗列 从执行文档中提取每个行为规则作为功能点，按实现方式分为两大类： @@ -51,7 +51,7 @@ description: > 以表格形式输出，每个功能点标注对应的执行案条目编号。分类原则：UE 内置能力覆盖 80% 以上需求且行为一致 → UE 内置；否则 → 自定义实现。 -### 步骤②：功能领域图 +### 功能领域图 识别当前系统由哪些功能模块组成，以及模块之间的交互关系。 @@ -63,7 +63,7 @@ description: > - 虚线 `-.->` 表示事件通知 / 异步通信 - 配合模块职责说明表格 -### 步骤③：类设计图 +### 类设计图 将功能领域图细化为具体的类设计。展示每个类的关键数据成员和关键接口，以及类之间的关系。 @@ -79,7 +79,7 @@ description: > 同时提供新增类表格、修改类表格、新增蓝图表格。类命名遵循 UE5 前缀规范（`A`/`U`/`I`/`F`/`E`）。 -### 步骤④：时序图（条件性） +### 时序图（条件性） > ⚠️ 仅当特性满足以下任一条件时绘制：涉及 3+ 个系统协调、有条件分支或循环流程、跨层级通信（UI ↔ 逻辑 ↔ 数据）。简单特性跳过。 @@ -90,7 +90,7 @@ description: > - 使用 `activate`/`deactivate` 展示调用栈深度 - 标注关键判断分支 -### 步骤⑤：核心数据结构 +### 核心数据结构 定义系统所需的枚举、结构体、配置数据。 @@ -101,7 +101,7 @@ description: > - 每个字段提供中文注释说明和合理的默认值 - 区分"配置参数"和"运行时状态" -### 步骤⑥：复杂接口描述（条件性） +### 复杂接口描述（条件性） > ⚠️ 仅当接口有 5+ 个决策分支或协调多个子系统状态时需要。简单接口（纯数据查询、简单赋值）跳过。 @@ -112,7 +112,7 @@ description: > 描述时必须包含：前置检查（快速失败）→ 核心逻辑 → 异步操作标注 → 边界情况处理。 -### 步骤⑦：技术难点/风险 +### 技术难点/风险 识别并评估实现过程中可能遇到的技术难点和风险： @@ -120,7 +120,7 @@ description: > - 每个风险包含：风险描述、详细说明、缓解措施 - 特别关注：UE5 限制、性能瓶颈、跨系统时序问题、数据一致性 -### 步骤⑧：工期预估 +### 工期预估 给出工作量和实现拆分建议： @@ -138,9 +138,7 @@ description: > 文档必须遵循 `references/output-template.md` 中定义的标准模板结构。8 步分析的结果整合到模板的对应章节中，同时保留现有的必要章节（美术资源需求、数据流、可调参数汇总、文件结构）。 -**阶段适配**： -- 原型阶段：步骤②④⑥可适度简化，允许占位描述 -- 批量生产阶段：所有步骤必须完整、详细 +**简化规则**：时序图和复杂接口描述可根据复杂度判定跳过（见条件步骤判定速查）。 --- @@ -148,8 +146,8 @@ description: > | 步骤 | 激活条件 | 跳过条件 | |------|---------|---------| -| ④ 时序图 | 3+ 系统协调 / 有分支循环 / 跨层级通信 | 单系统内部 / 纯配置 | -| ⑥ 复杂接口描述 | 5+ 决策分支 / 协调多子系统 / 有异步等待 | 简单查询 / 2-4 分支简单逻辑 | +| 时序图 | 3+ 系统协调 / 有分支循环 / 跨层级通信 | 单系统内部 / 纯配置 | +| 复杂接口描述 | 5+ 决策分支 / 协调多子系统 / 有异步等待 | 简单查询 / 2-4 分支简单逻辑 | 详细判定启发式参见 `references/diagram-guide.md` 第 3 节。 @@ -161,4 +159,4 @@ description: > |------|------|---------| | `references/diagram-guide.md` | Mermaid 语法速查、项目约定、复杂度判定 | 绘制任何图表前查阅 | | `references/output-template.md` | 完整技术设计文档模板 | 开始写文档前查阅，确保结构完整 | -| `references/examples.md` | 各步骤的注释示例（来自现有技术文档） | 需要参考输出效果时查阅 | +| `references/examples.md` | 需求分析的注释示例（来自现有技术文档） | 需要参考输出效果时查阅 | diff --git a/.claude/skills/requirements-analysis/references/diagram-guide.md b/.claude/skills/requirements-analysis/references/diagram-guide.md index 9869364..e3b10c3 100644 --- a/.claude/skills/requirements-analysis/references/diagram-guide.md +++ b/.claude/skills/requirements-analysis/references/diagram-guide.md @@ -6,7 +6,7 @@ ## 1. Mermaid 语法速查 -### 1.1 功能领域图（步骤②） +### 1.1 功能领域图 使用 `flowchart` 展示功能模块及其交互关系。模块级抽象，不涉及类级别细节。 @@ -57,7 +57,7 @@ flowchart TD --- -### 1.2 类设计图（步骤③） +### 1.2 类设计图 使用 `classDiagram` 展示类的关键数据、接口和关系。 @@ -131,7 +131,7 @@ classDiagram --- -### 1.3 时序图（步骤④） +### 1.3 时序图 使用 `sequenceDiagram` 追踪复杂特性的跨系统调用流程。 @@ -188,7 +188,7 @@ sequenceDiagram --- -### 1.4 流程图 / 鲁棒图（步骤⑥） +### 1.4 流程图 / 鲁棒图 使用 `flowchart` 描述复杂接口的决策分支和执行流程。 @@ -254,7 +254,7 @@ flowchart TD ## 3. 复杂度判定启发式 -### 3.1 何时需要时序图（步骤④） +### 3.1 何时需要时序图 时序图为条件性步骤，仅在特性满足以下任一条件时需要绘制： @@ -266,7 +266,7 @@ flowchart TD | 仅涉及单系统内部配置 | 不需要 | SpringArm 参数调整（纯配置） | | 仅 2 个系统简单调用 | 可选 | Character 设置 flag → Movement 检查 flag | -### 3.2 何时需要复杂接口描述（步骤⑥） +### 3.2 何时需要复杂接口描述 复杂接口描述为条件性步骤，仅在接口满足以下任一条件时需要： diff --git a/.claude/skills/requirements-analysis/references/examples.md b/.claude/skills/requirements-analysis/references/examples.md index 7292f8b..74acd05 100644 --- a/.claude/skills/requirements-analysis/references/examples.md +++ b/.claude/skills/requirements-analysis/references/examples.md @@ -1,4 +1,4 @@ -# 需求分析各步骤示例 +# 需求分析示例 本文档从项目现有技术设计文档中提取注释示例，展示每步分析的实际输出效果。 diff --git a/.claude/skills/requirements-analysis/references/output-template.md b/.claude/skills/requirements-analysis/references/output-template.md index 21d6085..0c56077 100644 --- a/.claude/skills/requirements-analysis/references/output-template.md +++ b/.claude/skills/requirements-analysis/references/output-template.md @@ -7,12 +7,11 @@ ## 模板 ```markdown -# <系统名称> 技术设计文档（<版本号> <阶段>） +# <系统名称> 技术设计文档（<版本号>） > 任务ID: <任务编号> -> 对应执行案: `docs/design//<系统名>-执行案.md` +> 对应执行案: `docs/design/<系统名>-执行案.md` > 关联系统: <上游/下游/平行系统列表> -> 阶段: 原型 / 批量生产 / 测试 > 日期: --- @@ -245,7 +244,7 @@ function (): |----------|------|------|------|---------------| | <3D模型/动画/UI/2D图标/音效> | <名称> | <数量> | <尺寸/格式/时长> | <何时使用> | -> v0.1 原型阶段允许占位资源，但类型和数量必须明确。 +> 类型和数量必须明确，允许占位资源。 --- @@ -319,7 +318,7 @@ Content/ ### 实现拆分建议 -供步骤⑥（程序实现）参考的推荐拆分方式，每个子任务可独立验证： +供程序实现参考的推荐拆分方式，每个子任务可独立验证： | 子任务 | 内容 | 预估时间 | 依赖 | 验证方式 | |--------|------|---------|------|---------| @@ -334,4 +333,4 @@ Content/ 2. **条件性章节**（第 4 节时序图、第 6 节复杂接口描述）：根据复杂度判定决定是否包含 3. **Mermaid 图表**：在 markdown 渲染器中会自动生成可视化图表 4. **保持一一映射**：每条执行文档行为规则都必须在第 6 节有对应实现方案 -5. **阶段适配**：原型阶段允许简化描述，批量生产阶段需要完整覆盖所有章节 +5. **完整覆盖**：所有章节需按模板结构填写，条件性章节按复杂度判定 diff --git a/.claude/skills/stage-iteration.md b/.claude/skills/stage-iteration.md index f47f539..1dab162 100644 --- a/.claude/skills/stage-iteration.md +++ b/.claude/skills/stage-iteration.md @@ -27,23 +27,23 @@ description: "迭代阶段技能 — 版本迭代开发管理。插件检查→ ### 任务列表（按创建顺序） -| 编号 | 任务名称 | 角色 | 前置依赖 | 首次迭代 | -|------|---------|------|---------|---------| -| 1.4.0 | 插件资产检查与准备 | 程序 | 无 | 仅首次 | -| 1.4.0.5 | 设计案迭代补充 | 策划 | 1.4.0（首次）或无 | 可选 | -| 1.4.1 | 策划执行案 | 策划 | 1.4.0.5 | 必选 | -| 1.4.2 | 程序需求分析 | 程序 | 1.4.1 | 必选 | -| 1.4.3.1 | 关卡搭建 | 程序 | 1.4.2 | 有场景时 | -| 1.4.3.2 | 系统开发 | 程序 | 1.4.2 | 必选 | -| 1.4.3.3 | 优化意见 | 程序 | 1.4.3.1 + 1.4.3.2 | 必选 | -| 1.4.3.5 | 资产接入整合 | 程序 | 1.4.3.3 | 必选 | -| 1.4.4 | Bug 修复 | 程序 | 1.4.3.5 | 必选 | +| 任务名称 | 角色 | 前置依赖 | 首次迭代 | +|---------|------|---------|---------| +| 插件资产检查与准备 | 程序 | 无 | 仅首次 | +| 设计案迭代补充 | 策划 | 插件资产检查（首次）或无 | 可选 | +| 策划执行案 | 策划 | 设计案迭代补充 | 必选 | +| 程序需求分析 | 程序 | 策划执行案 | 必选 | +| 关卡搭建 | 程序 | 程序需求分析 | 有场景时 | +| 系统开发 | 程序 | 程序需求分析 | 必选 | +| 优化意见 | 程序 | 关卡搭建 + 系统开发 | 必选 | +| 资产接入整合 | 程序 | 优化意见 | 必选 | +| Bug 修复 | 程序 | 资产接入整合 | 必选 | --- ### 各任务详细说明 -#### 1.4.0 插件资产检查与准备（仅首次迭代） +#### 插件资产检查与准备（仅首次迭代） ```bash --title "P-XXX 插件资产检查与准备" @@ -78,7 +78,7 @@ description: "迭代阶段技能 — 版本迭代开发管理。插件检查→ --assignees "ai-programmer" ``` -#### 1.4.0.5 设计案迭代补充（可选） +#### 设计案迭代补充（可选） ```bash --title "D-XXX 设计案迭代补充 — <版本号>" @@ -102,7 +102,7 @@ description: "迭代阶段技能 — 版本迭代开发管理。插件检查→ --assignees "ai-designer" ``` -#### 1.4.1 策划执行案 +#### 策划执行案 ```bash --title "D-XXX 策划执行案 — <版本号>" @@ -130,7 +130,7 @@ description: "迭代阶段技能 — 版本迭代开发管理。插件检查→ --assignees "ai-designer" ``` -#### 1.4.2 程序需求分析 +#### 程序需求分析 ```bash --title "P-XXX 程序需求分析 — <版本号>" @@ -160,7 +160,7 @@ docs/technical/<系统名>-tech.md" --assignees "ai-programmer" ``` -#### 1.4.3.1 关卡搭建（有场景时） +#### 关卡搭建（有场景时） ```bash --title "P-XXX 关卡搭建 — <版本号>" @@ -179,7 +179,7 @@ docs/technical/<系统名>-tech.md" --assignees "ai-programmer" ``` -#### 1.4.3.2 系统开发 +#### 系统开发 ```bash --title "P-XXX 系统开发 — <版本号>" @@ -198,7 +198,7 @@ docs/technical/<系统名>-tech.md" --assignees "ai-programmer" ``` -#### 1.4.3.3 优化意见 +#### 优化意见 ```bash --title "P-XXX 优化意见 — <版本号>" @@ -218,7 +218,7 @@ docs/technical/<系统名>-tech.md" --assignees "ai-programmer" ``` -#### 1.4.3.5 资产接入整合 +#### 资产接入整合 ```bash --title "P-XXX 资产接入整合 — <版本号>" @@ -237,7 +237,7 @@ docs/technical/<系统名>-tech.md" --assignees "ai-programmer" ``` -#### 1.4.4 Bug 修复 +#### Bug 修复 ```bash --title "P-XXX Bug修复 — <版本号>" @@ -264,20 +264,20 @@ docs/technical/<系统名>-tech.md" 1. **读取当前迭代任务状态**：`issue list --milestone "迭代-vX.X" --state open` 2. **判断当前焦点**： - - 按 1.4.0 → 1.4.0.5 → 1.4.1 → 1.4.2 → 1.4.3.1/2 → 1.4.3.3 → 1.4.3.5 → 1.4.4 顺序 + - 按上述任务列表顺序 - 找到第一个未完成的步骤 → 建议：启动对应角色完成该步骤 - 如果某步骤的依赖未完成 → 建议：先完成依赖任务 3. **只创建下一个可创建的任务**： - 已有任务进行中 → 不创建新任务 - 所有前置依赖已完成 → 创建下一个任务并设为 `status:ready` 4. **检查完成条件**： - - 1.4.4 (Bug修复) 已关闭 → 触发迭代转换 + - Bug 修复任务已关闭 → 触发迭代转换 --- ## 迭代转换 -**前置条件**：Bug 修复任务（1.4.4）已关闭。 +**前置条件**：Bug 修复任务已关闭。 **询问用户**：是否有下一个迭代版本？ @@ -292,8 +292,8 @@ node .claude/skills/gitea-pm/gitea.js --role pm milestone create \ --title "迭代-vX.X" \ --description "第 N 个迭代版本：<简要描述>" -# 3. 从 1.4.0.5（设计补充）或 1.4.1（执行案）开始 -# 非首次迭代跳过 1.4.0（插件检查） +# 3. 从设计案迭代补充或策划执行案开始 +# 非首次迭代跳过插件资产检查 # 4. 更新 Pipeline Tracker ``` diff --git a/.claude/skills/stage-roadmap.md b/.claude/skills/stage-roadmap.md index fec944f..4724ffb 100644 --- a/.claude/skills/stage-roadmap.md +++ b/.claude/skills/stage-roadmap.md @@ -33,7 +33,7 @@ description: "总路线阶段技能 — 全面设计文档产出与版本路径 --- -**任务 1：设计总索引文档** (D-XXX) +**设计总索引文档** (D-XXX) ```bash --title "D-XXX 设计总索引文档" @@ -55,7 +55,7 @@ description: "总路线阶段技能 — 全面设计文档产出与版本路径 --assignees "ai-designer" ``` -**任务 2：世界观设计文档** (D-XXX) — 可占位 +**世界观设计文档** (D-XXX) — 可占位 ``` --title "D-XXX 世界观设计" @@ -64,7 +64,7 @@ description: "总路线阶段技能 — 全面设计文档产出与版本路径 --labels "stage:roadmap,role:design,status:ready" ``` -**任务 3：剧情设计文档** (D-XXX) — 可占位 +**剧情设计文档** (D-XXX) — 可占位 ``` --title "D-XXX 剧情设计" @@ -73,7 +73,7 @@ description: "总路线阶段技能 — 全面设计文档产出与版本路径 --labels "stage:roadmap,role:design,status:ready" ``` -**任务 4：角色设计文档** (D-XXX) — 可占位 +**角色设计文档** (D-XXX) — 可占位 ``` --title "D-XXX 角色设计" @@ -82,7 +82,7 @@ description: "总路线阶段技能 — 全面设计文档产出与版本路径 --labels "stage:roadmap,role:design,status:ready" ``` -**任务 5：系统设计文档** (D-XXX) — ⚠️ 必须完整 +**系统设计文档** (D-XXX) — ⚠️ 必须完整 ``` --title "D-XXX 系统设计" @@ -91,7 +91,7 @@ description: "总路线阶段技能 — 全面设计文档产出与版本路径 --labels "stage:roadmap,role:design,status:ready" ``` -**任务 6：关卡设计文档** (D-XXX) — ⚠️ 必须完整 +**关卡设计文档** (D-XXX) — ⚠️ 必须完整 ``` --title "D-XXX 关卡设计" @@ -100,7 +100,7 @@ description: "总路线阶段技能 — 全面设计文档产出与版本路径 --labels "stage:roadmap,role:design,status:ready" ``` -**任务 7：UI 设计文档** (D-XXX) — 可占位 +**UI 设计文档** (D-XXX) — 可占位 ``` --title "D-XXX UI设计" @@ -109,7 +109,7 @@ description: "总路线阶段技能 — 全面设计文档产出与版本路径 --labels "stage:roadmap,role:design,status:ready" ``` -**任务 8：音频设计文档** (D-XXX) — 可占位 +**音频设计文档** (D-XXX) — 可占位 ``` --title "D-XXX 音频设计" @@ -118,7 +118,7 @@ description: "总路线阶段技能 — 全面设计文档产出与版本路径 --labels "stage:roadmap,role:design,status:ready" ``` -**任务 9：版本路径图** (D-XXX) +**版本路径图** (D-XXX) ``` --title "D-XXX 版本路径图" @@ -132,12 +132,12 @@ description: "总路线阶段技能 — 全面设计文档产出与版本路径 ### 依赖关系 ``` -任务 1（总索引）→ 先完成 -任务 2-8（各设计文档）→ 1 完成后可并行创建，建议按序执行 -任务 9（版本路径图）→ 依赖 2-8，最后完成 +设计总索引 → 先完成 +各设计文档（世界观/剧情/角色/系统/关卡/UI/音频）→ 索引完成后可并行创建，建议按序执行 +版本路径图 → 依赖所有设计文档，最后完成 ``` -设置依赖：`issue block <任务9> <任务2>` ~ `issue block <任务9> <任务8>` +设置依赖：`issue block <版本路径图> <世界观>` ~ `issue block <版本路径图> <音频>` --- diff --git a/.claude/skills/stage-sketch.md b/.claude/skills/stage-sketch.md index f0ef059..0624039 100644 --- a/.claude/skills/stage-sketch.md +++ b/.claude/skills/stage-sketch.md @@ -29,7 +29,7 @@ description: "草图阶段技能 — 概念设计与技术可行性验证。管 ### 需要创建的任务（共 2 个） -**任务 1：概念设计** (D-XXX) +**概念设计** (D-XXX) ```bash node .claude/skills/gitea-pm/gitea.js --role pm issue create \ @@ -56,7 +56,7 @@ node .claude/skills/gitea-pm/gitea.js --role pm issue create \ --assignees "ai-designer" ``` -**任务 2：技术可行性报告** (P-XXX) +**技术可行性报告** (P-XXX) ```bash node .claude/skills/gitea-pm/gitea.js --role pm issue create \ diff --git a/ChildHood.uproject b/ChildHood.uproject index 0b05642..d314f66 100644 --- a/ChildHood.uproject +++ b/ChildHood.uproject @@ -39,4 +39,4 @@ ] } ] -} +} \ No newline at end of file diff --git a/docs/design/README.md b/docs/design/README.md index cbf03b1..d637539 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -1,58 +1,87 @@ # docs/design/ — 策划文档索引 > 策划 Agent 的输出目录。所有玩法设计、系统机制、剧情叙事文档存放于此。 +> 最后更新：2026-06-08 -## 目录结构 +--- -``` -docs/design/ - concept.md # 草案阶段产出（项目初期） - README.md # 本索引文件 - prototype/ # 原型阶段设计（设计案 + 执行案 + 头脑风暴） - production/ # 批量生产阶段设计（从 prototype/ 复制，作为起点） -``` - -## 原型阶段文档 (`prototype/`) - -### 全局设计 +## 核心锚点 | 文档 | 说明 | |------|------| -| [game-vision.md](prototype/game-vision.md) | 游戏愿景、核心情感、三大支柱、游戏世界 | -| [scene-world.md](prototype/scene-world.md) | 场景与世界观详细设计 | -| [protagonist-character.md](prototype/protagonist-character.md) | 主角角色设计 | -| [narrative-framework.md](prototype/narrative-framework.md) | 叙事框架（事件链、多支线结局、角色关系） | +| [游戏愿景.md](游戏愿景.md) | 游戏愿景、核心情感、三大支柱——所有设计决策的锚点 | -### 系统设计 +--- + +## 系统设计案 + +| 文档 | 说明 | 当前版本覆盖 | +|------|------|-------------| +| [玩家控制器.md](玩家控制器.md) | 玩家角色控制——移动、摄像机、动画蓝图 | v0.1 ✅ | +| [交互系统.md](交互系统.md) | 环境交互系统——交互组件、检测、UI 提示 | v0.1 ✅ | +| [收集系统.md](收集系统.md) | 收集系统——拾取、进度追踪、图鉴（v0.1 基础版 → v0.4 完整版） | v0.1 ✅ v0.2+ 待补 | +| [小游戏系统.md](小游戏系统.md) | 小游戏体系——弹珠、拍洋画、四驱车等千禧年童年游戏 | v0.2 待补执行案 | +| [叙事框架.md](叙事框架.md) | 叙事框架——暑假结构、事件设计、角色系统 | v0.3-v0.4 待补 | + +--- + +## 场景与角色 | 文档 | 说明 | |------|------| -| [player-controller.md](prototype/player-controller.md) | 玩家控制（移动、摄像机） | -| [interaction-system.md](prototype/interaction-system.md) | 交互系统（观察、拾取、使用） | -| [collection-system.md](prototype/collection-system.md) | 收集系统（四类收集品、展示、世界反馈） | -| [minigame-system.md](prototype/minigame-system.md) | 小游戏体系（弹珠、四驱车、FC/街机等） | +| [场景与世界观.md](场景与世界观.md) | 完整场景与世界观设计（城市主场景 + 乡下场景） | +| [场景-v01-城郊小街.md](场景-v01-城郊小街.md) | v0.1 白盒场景具体内容——6 区域布局、交互点位置 | +| [主角设计.md](主角设计.md) | 主角角色描述——美术设计的核心参考 | -### 版本相关 +--- + +## 执行案 + +| 文档 | 对应系统 | 版本 | 状态 | +|------|---------|------|------| +| [玩家控制器-执行案.md](玩家控制器-执行案.md) | 角色控制 | v0.1.1 | 📝 设计中 | +| [交互系统-执行案.md](交互系统-执行案.md) | 交互系统 | v0.1.2 | 📝 设计中 | +| [收集系统-执行案.md](收集系统-执行案.md) | 收集系统 | v0.1.1 | 📝 设计中 | +| [关卡-v01-城郊小街-执行案.md](关卡-v01-城郊小街-执行案.md) | 关卡（城郊小街白盒） | v0.1 | 📝 设计中 | + +--- + +## 版本范围 | 文档 | 说明 | |------|------| -| [v01-scope.md](prototype/v01-scope.md) | v0.1 范围定义 | -| [scene-v01-suburban.md](prototype/scene-v01-suburban.md) | v0.1 场景设计（城郊结合区） | +| [v01-范围.md](v01-范围.md) | v0.1 功能边界、验收标准、开发优先级 | -### 头脑风暴 +--- + +## 关卡设计工作流 | 文档 | 说明 | |------|------| -| [brainstorm-2026-06-01-vision-pillars-world.md](prototype/brainstorm-2026-06-01-vision-pillars-world.md) | 愿景探索、三大支柱深挖、场景世界观、版本范围 | +| [关卡设计工作流.md](关卡设计工作流.md) | 策划-程序关卡交接规范、坐标体系、命名约定 | -### 待产出 +--- -| 文档 | 说明 | -|------|------| -| `v01-design.md` | v0.1 版本设计文档（总纲） | -| `player-controller-execution.md` | 玩家控制器执行案 | -| `interaction-system-execution.md` | 交互系统执行案 | -| `collection-system-execution.md` | 收集系统 v0.1 执行案 | +## 头脑风暴记录 + +| 文档 | 日期 | 主题 | +|------|------|------| +| [头脑风暴-2026-06-01-愿景支柱与世界观.md](头脑风暴-2026-06-01-愿景支柱与世界观.md) | 2026-06-01 | 愿景三大支柱 + 世界观确认 | +| [头脑风暴-2026-06-04-时代与科技灵感.md](头脑风暴-2026-06-04-时代与科技灵感.md) | 2026-06-04 | 千禧年时代技术灵感（随身听、小霸王、街机等） | +| [头脑风暴-2026-06-05-怀旧文化.md](头脑风暴-2026-06-05-怀旧文化.md) | 2026-06-05 | 千禧年怀旧文化灵感（电视剧、广播体操、广场舞等） | + +--- + +## 外部关联 + +| 文档 | 位置 | 说明 | +|------|------|------| +| 概念草案 | [概念草案.md](概念草案.md) | 已冻结，只读参考 | +| 原型路线图 | [../plans/原型阶段-路线图.md](../plans/原型阶段-路线图.md) | v0.1–v0.4 版本规划 | +| 技术可行性评估 | [../technical/技术可行性评估.md](../technical/技术可行性评估.md) | 系统的技术评估 | +| 程序设计方案 | [../technical/](../technical/) | 程序设计文档 | + +--- ## 待产出的全局设计文档 @@ -67,7 +96,5 @@ docs/design/ - Markdown 格式 - 每个系统/角色/场景一个独立文件 -- 文件名使用小写英文 + 连字符：`player-controller.md` -- 设计案和执行案按阶段放在 `prototype/` 或 `production/` 目录下，不按版本分子目录 - 执行案文件顶部必须包含迭代记录表头 -- 头脑风暴文件名格式：`brainstorm-YYYY-MM-DD-<讨论目标>.md` +- 头脑风暴文件名格式：`头脑风暴-YYYY-MM-DD-<讨论目标>.md` diff --git a/docs/design/prototype/README.md b/docs/design/prototype/README.md deleted file mode 100644 index aae21a0..0000000 --- a/docs/design/prototype/README.md +++ /dev/null @@ -1,74 +0,0 @@ -# 原型阶段设计文档索引 - -> 最后更新：2026-06-06 -> 阶段：原型阶段 | 版本范围：v0.1–v0.4 - ---- - -## 核心锚点 - -| 文档 | 说明 | -|------|------| -| [game-vision.md](game-vision.md) | 游戏愿景、核心情感、三大支柱——所有设计决策的锚点 | - ---- - -## 系统设计案 - -| 文档 | 说明 | 当前版本覆盖 | -|------|------|-------------| -| [player-controller.md](player-controller.md) | 玩家角色控制——移动、摄像机、动画蓝图 | v0.1 ✅ | -| [interaction-system.md](interaction-system.md) | 环境交互系统——交互组件、检测、UI 提示 | v0.1 ✅ | -| [collection-system.md](collection-system.md) | 收集系统——拾取、进度追踪、图鉴（v0.1 基础版 → v0.4 完整版） | v0.1 ✅ v0.2+ 待补 | -| [minigame-system.md](minigame-system.md) | 小游戏体系——弹珠、拍洋画、四驱车等千禧年童年游戏 | v0.2 待补执行案 | -| [narrative-framework.md](narrative-framework.md) | 叙事框架——暑假结构、事件设计、角色系统 | v0.3-v0.4 待补 | - ---- - -## 场景与角色 - -| 文档 | 说明 | -|------|------| -| [scene-world.md](scene-world.md) | 完整场景与世界观设计（城市主场景 + 乡下场景） | -| [scene-v01-suburban.md](scene-v01-suburban.md) | v0.1 白盒场景具体内容——6 区域布局、交互点位置 | -| [protagonist-character.md](protagonist-character.md) | 主角角色描述——美术设计的核心参考 | - ---- - -## 执行案 - -| 文档 | 对应系统 | 版本 | 状态 | -|------|---------|------|------| -| [player-controller-execution.md](player-controller-execution.md) | 角色控制 | v0.1.1 | 📝 设计中 | -| [interaction-system-execution.md](interaction-system-execution.md) | 交互系统 | v0.1.2 | 📝 设计中 | -| [collection-system-execution.md](collection-system-execution.md) | 收集系统 | v0.1.1 | 📝 设计中 | -| [level-v01-suburban-execution.md](level-v01-suburban-execution.md) | 关卡（城郊小街白盒） | v0.1 | 📝 设计中 | - ---- - -## 版本范围 - -| 文档 | 说明 | -|------|------| -| [v01-scope.md](v01-scope.md) | v0.1 功能边界、验收标准、开发优先级 | - ---- - -## 头脑风暴记录 - -| 文档 | 日期 | 主题 | -|------|------|------| -| [brainstorm-2026-06-01-vision-pillars-world.md](brainstorm-2026-06-01-vision-pillars-world.md) | 2026-06-01 | 愿景三大支柱 + 世界观确认 | -| [brainstorm-2026-06-04-era-tech-inspirations.md](brainstorm-2026-06-04-era-tech-inspirations.md) | 2026-06-04 | 千禧年时代技术灵感（随身听、小霸王、街机等） | -| [brainstorm-2026-06-05-nostalgia-culture.md](brainstorm-2026-06-05-nostalgia-culture.md) | 2026-06-05 | 千禧年怀旧文化灵感（电视剧、广播体操、广场舞等） | - ---- - -## 外部关联 - -| 文档 | 位置 | 说明 | -|------|------|------| -| 概念草案 | [../concept.md](../concept.md) | 已冻结，只读参考 | -| 原型路线图 | [../../plans/prototype-roadmap.md](../../plans/prototype-roadmap.md) | v0.1–v0.4 版本规划 | -| 技术可行性评估 | [../../technical/feasibility-assessment.md](../../technical/feasibility-assessment.md) | 10 个系统的技术评估 | -| 程序设计方案 | [../../technical/](../../technical/) | v0.1 程序设计文档 | diff --git a/docs/design/prototype/v01-范围.md b/docs/design/v01-范围.md similarity index 100% rename from docs/design/prototype/v01-范围.md rename to docs/design/v01-范围.md diff --git a/docs/design/prototype/主角设计.md b/docs/design/主角设计.md similarity index 100% rename from docs/design/prototype/主角设计.md rename to docs/design/主角设计.md diff --git a/docs/design/prototype/交互系统-执行案.md b/docs/design/交互系统-执行案.md similarity index 100% rename from docs/design/prototype/交互系统-执行案.md rename to docs/design/交互系统-执行案.md diff --git a/docs/design/prototype/交互系统.md b/docs/design/交互系统.md similarity index 100% rename from docs/design/prototype/交互系统.md rename to docs/design/交互系统.md diff --git a/docs/design/prototype/关卡-v01-城郊小街-执行案.md b/docs/design/关卡-v01-城郊小街-执行案.md similarity index 100% rename from docs/design/prototype/关卡-v01-城郊小街-执行案.md rename to docs/design/关卡-v01-城郊小街-执行案.md diff --git a/docs/design/prototype/关卡设计工作流.md b/docs/design/关卡设计工作流.md similarity index 100% rename from docs/design/prototype/关卡设计工作流.md rename to docs/design/关卡设计工作流.md diff --git a/docs/design/prototype/叙事框架.md b/docs/design/叙事框架.md similarity index 100% rename from docs/design/prototype/叙事框架.md rename to docs/design/叙事框架.md diff --git a/docs/design/prototype/场景-v01-城郊小街.md b/docs/design/场景-v01-城郊小街.md similarity index 100% rename from docs/design/prototype/场景-v01-城郊小街.md rename to docs/design/场景-v01-城郊小街.md diff --git a/docs/design/prototype/场景与世界观.md b/docs/design/场景与世界观.md similarity index 100% rename from docs/design/prototype/场景与世界观.md rename to docs/design/场景与世界观.md diff --git a/docs/design/prototype/头脑风暴-2026-06-01-愿景支柱与世界观.md b/docs/design/头脑风暴-2026-06-01-愿景支柱与世界观.md similarity index 100% rename from docs/design/prototype/头脑风暴-2026-06-01-愿景支柱与世界观.md rename to docs/design/头脑风暴-2026-06-01-愿景支柱与世界观.md diff --git a/docs/design/prototype/头脑风暴-2026-06-04-时代与科技灵感.md b/docs/design/头脑风暴-2026-06-04-时代与科技灵感.md similarity index 100% rename from docs/design/prototype/头脑风暴-2026-06-04-时代与科技灵感.md rename to docs/design/头脑风暴-2026-06-04-时代与科技灵感.md diff --git a/docs/design/prototype/头脑风暴-2026-06-05-怀旧文化.md b/docs/design/头脑风暴-2026-06-05-怀旧文化.md similarity index 100% rename from docs/design/prototype/头脑风暴-2026-06-05-怀旧文化.md rename to docs/design/头脑风暴-2026-06-05-怀旧文化.md diff --git a/docs/design/prototype/小游戏系统.md b/docs/design/小游戏系统.md similarity index 100% rename from docs/design/prototype/小游戏系统.md rename to docs/design/小游戏系统.md diff --git a/docs/design/prototype/收集系统-执行案.md b/docs/design/收集系统-执行案.md similarity index 100% rename from docs/design/prototype/收集系统-执行案.md rename to docs/design/收集系统-执行案.md diff --git a/docs/design/prototype/收集系统.md b/docs/design/收集系统.md similarity index 100% rename from docs/design/prototype/收集系统.md rename to docs/design/收集系统.md diff --git a/docs/design/prototype/游戏愿景.md b/docs/design/游戏愿景.md similarity index 100% rename from docs/design/prototype/游戏愿景.md rename to docs/design/游戏愿景.md diff --git a/docs/design/prototype/玩家控制器-执行案.md b/docs/design/玩家控制器-执行案.md similarity index 100% rename from docs/design/prototype/玩家控制器-执行案.md rename to docs/design/玩家控制器-执行案.md diff --git a/docs/design/prototype/玩家控制器.md b/docs/design/玩家控制器.md similarity index 100% rename from docs/design/prototype/玩家控制器.md rename to docs/design/玩家控制器.md diff --git a/docs/technical/交互系统-技术方案.md b/docs/technical/交互系统-技术方案.md index c04b0f8..431f08a 100644 --- a/docs/technical/交互系统-技术方案.md +++ b/docs/technical/交互系统-技术方案.md @@ -1,8 +1,7 @@ -# 交互系统 技术设计文档（v0.1 原型） +# 交互系统 技术设计文档（v0.1） -> 对应执行案: `docs/design/prototype/interaction-system-execution.md` (v0.1.2) +> 对应执行案: `docs/design/交互系统-执行案.md` (v0.1.2) > 关联系统: 角色控制系统、物品系统、收集系统 -> 阶段: 原型 > 日期: 2026-06-07 --- diff --git a/docs/technical/收集系统-技术方案.md b/docs/technical/收集系统-技术方案.md index 6cf068c..581d45d 100644 --- a/docs/technical/收集系统-技术方案.md +++ b/docs/technical/收集系统-技术方案.md @@ -1,9 +1,8 @@ -# 收集系统 技术设计文档（v0.1 原型） +# 收集系统 技术设计文档（v0.1） > 任务ID: P-009 -> 对应执行案: `docs/design/prototype/collection-system-execution.md` (v0.1.1) +> 对应执行案: `docs/design/收集系统-执行案.md` (v0.1.1) > 关联系统: 物品系统（上游单向接收）、交互系统（间接，通过物品系统委托） -> 阶段: 原型 > 日期: 2026-06-07 --- diff --git a/docs/technical/玩家控制器-技术方案.md b/docs/technical/玩家控制器-技术方案.md index 8a6d3f0..b7492c8 100644 --- a/docs/technical/玩家控制器-技术方案.md +++ b/docs/technical/玩家控制器-技术方案.md @@ -1,9 +1,8 @@ -# 角色控制技术设计文档（v0.1 原型） +# 角色控制技术设计文档（v0.1） > 任务ID: P-007 -> 对应执行案: `docs/design/prototype/player-controller-execution.md` +> 对应执行案: `docs/design/玩家控制器-执行案.md` > 关联系统: 交互系统（输入互斥 + 摄像机控制权交接）、场景系统（碰撞体 + 出生点） -> 阶段: 原型 > 日期: 2026-06-07 ---