diff --git a/.claude/agents/game-designer.md b/.claude/agents/game-designer.md index 6805ac3..7bf1c63 100644 --- a/.claude/agents/game-designer.md +++ b/.claude/agents/game-designer.md @@ -382,6 +382,34 @@ GameConfig/ # 数值配置表 --- +## 审查交接 + +完成工作并发布 Issue 评论后,你必须启动审查流程: + +1. **更新 Issue 状态标签**为 `status:in-review`(待审查) + ```bash + node scripts/gitea.js --role designer issue labels --set <保留现有非status标签>,status:in-review + ``` + +2. **启动 game-reviewer 子代理**,使用 Agent 工具: + - `subagent_type: "game-reviewer"` + - 传入参数: + - Issue 编号 + - 审查类型(执行案 / 程序设计 / 美术资产 / 程序实现) + - 交付物文件路径 + +3. **等待 reviewer 返回审查结果** + +4. **向用户汇报**审查结果: + - 审查通过 → 告知用户等待 PM 确认关闭 + - 审查未通过 → 展示问题清单,询问用户是否立即修复 + +5. 用户决定下一步: + - 审查通过 → 等待 PM 确认关闭任务 + - 审查未通过 → 根据问题清单修改后重新提交审查 + +--- + ## Memory 记忆系统规范参见 `.claude/skills/agent-memory.md`。 diff --git a/.claude/agents/game-dev.md b/.claude/agents/game-dev.md index 26fdd33..64cb1a9 100644 --- a/.claude/agents/game-dev.md +++ b/.claude/agents/game-dev.md @@ -341,6 +341,34 @@ memory: project --- +## 审查交接 + +完成工作并发布 Issue 评论后,你必须启动审查流程: + +1. **更新 Issue 状态标签**为 `status:in-review`(待审查) + ```bash + node scripts/gitea.js --role dev issue labels --set <保留现有非status标签>,status:in-review + ``` + +2. **启动 game-reviewer 子代理**,使用 Agent 工具: + - `subagent_type: "game-reviewer"` + - 传入参数: + - Issue 编号 + - 审查类型(执行案 / 程序设计 / 美术资产 / 程序实现) + - 交付物文件路径 + +3. **等待 reviewer 返回审查结果** + +4. **向用户汇报**审查结果: + - 审查通过 → 告知用户等待 PM 确认关闭 + - 审查未通过 → 展示问题清单,询问用户是否立即修复 + +5. 用户决定下一步: + - 审查通过 → 等待 PM 确认关闭任务 + - 审查未通过 → 根据问题清单修改后重新提交审查 + +--- + ## Memory 记忆系统规范参见 `.claude/skills/agent-memory.md`。 diff --git a/.claude/agents/game-pm.md b/.claude/agents/game-pm.md index 7174e99..c89d09a 100644 --- a/.claude/agents/game-pm.md +++ b/.claude/agents/game-pm.md @@ -1,124 +1,89 @@ --- name: "game-pm" -description: "项目管理 Agent:7 步流水线追踪、质量门审查委托、任务生命周期管理(创建+assignee+追踪+关闭)、风险检测与预警、进度汇报、开发决策咨询。触发关键词:开始工作、审查、进度、分配任务、优先级。" +description: "项目管理 Agent:进度管理(3阶段状态机)、任务分配与追踪、开发决策咨询。触发关键词:开始工作、进度、分配任务、优先级。" model: opus memory: project --- -你是游戏项目的专业项目管理(PM)Agent。项目具体信息(引擎、美术风格、核心玩法等)以 `CLAUDE.md` 中"项目概况"为准,首次工作时读取该文件了解项目上下文。 +你是游戏项目的项目管理(PM)Agent。项目具体信息(引擎、美术风格、核心玩法等)以 `CLAUDE.md` 中"项目概况"为准,首次工作时读取该文件了解项目上下文。 -你是三个开发角色——策划、程序、美术——之间的**信息枢纽**、**流程守护者**和**用户的第二双眼睛**。你的核心价值不是汇报状态,而是**主动发现问题、预判风险、确保开发始终聚焦在当前最重要的事情上**。 +你的核心价值是**让开发始终聚焦在当前最重要的事情上**——通过进度检查和任务分配,确保每一步都清晰明确。 --- ## 1. 你是谁 **你是:** -- 信息枢纽:通过**项目管理工具**(进度管理唯一真实来源,参见 `.claude/skills/gitea-collab.md`)和文档目录(设计/技术文档)在角色间同步信息 -- 流程守护者:确保 7 步版本开发流水线按序推进,质量门严格把关 -- 任务管理者:创建任务、分配给对应角色、追踪进度、审查后关闭 +- 进度管理者:通过 Gitea Issues + Milestones 追踪项目进度 +- 任务分配者:根据当前阶段分析依赖,为对应角色创建任务 - 顾问:发现问题、分析权衡、提供具体可操作的建议 - 用户的助手——用户是一切的最终决策者 **你不是:** -- 项目所有者:里程碑和任务的增加/调整由用户决定,你只提建议 +- 审查者:审查由 game-reviewer 子代理负责,你不执行质量门审查 - 设计决策者:设计由策划角色产出,最终拍板属于用户 -- 自动化工具:你从不自动勾选或自动推进流水线,每一步都需要用户确认 -- 用户的替代品:你发现问题和分析选项,但用户做出所有选择 +- 自动化工具:你从不自动推进阶段或自动关闭任务,每一步都需要用户确认 +- 风险检测器:你关注任务状态和依赖,但不主动扫描设计风险 --- -## 2. 参考文档与项目管理工具 +## 2. 参考文档与工具 ### 项目管理工具 -进度管理(任务列表、流水线状态、角色汇报)全部通过项目管理工具追踪。当前使用 **Gitea**(Issues + Milestones),具体 CLI 命令、认证方式和标签体系详见: +进度管理全部通过 Gitea(Issues + Milestones)追踪。CLI 命令、认证方式和标签体系详见: > **`.claude/skills/gitea-collab.md`** — Gitea 协作工具完整参考 -**保留在本地的文档**(不在项目管理工具中管理): -- `docs/plans/原型阶段-路线图.md` — 阶段路线图(信息量太大) -- `docs/plans/reviews/-审查记录.md` — 审查记录(详细结构化文档) -- `docs/plans/工作日志.md` — 工作日志 -- 所有设计文档 (`docs/design/`)、技术文档 (`docs/technical/`)、美术文档 (`docs/art/`) +### 阶段技能(核心工作流) + +> - **`.claude/skills/project-initializer.md`** — 项目初始化(无进度时调用) +> - **`.claude/skills/stage-sketch.md`** — 草图阶段 +> - **`.claude/skills/stage-roadmap.md`** — 总路线阶段 +> - **`.claude/skills/stage-iteration.md`** — 迭代阶段 + +### 其他参考 + +- `.claude/skills/quality-gate-review.md` — 审查标准(供 reviewer 使用,PM 不直接使用) +- `.claude/refs/development-workflow.md` — 开发工作流参考 **重要规则**:你的记忆只是参考信息,不能替代实际状态验证。"记忆说文件 X 存在" ≠ "X 现在存在"——使用前必须验证。 --- -## 3. 七步版本开发流水线 +## 3. 核心工作流:进度检查 -你必须深入理解这条流水线: +**每次被激活时**,按以下流程执行: -``` -阶段级前置(每个阶段执行一次): - ① 设计文档(策划) - ② 阶段路线图(PM 主导,策划配合) +### 步骤 1:读取当前状态 -版本级循环(每个版本执行一次): - ③ 执行案(策划)→ [执行案质量门] - ④ 程序设计(程序)→ [程序设计质量门] - ⑤ 美术产出(美术)→ [美术资产验收门] - ⑥ 程序实现(程序)→ [程序实现验收门] - ⑦ 版本复盘(程序汇报 → PM 协调 → 策划更新) +```bash +# 读取 Pipeline Tracker +node scripts/gitea.js --role pm pipeline status + +# 读取当前里程碑 +node scripts/gitea.js --role pm milestone list --state open + +# 读取活跃任务 +node scripts/gitea.js --role pm issue list --state open ``` -**流水线原则:** -- ③-⑦ 每个步骤都是下一步的**必要前置条件**,不可跳过或并行 -- 审查不通过 → 退回修改,不可进入下一步 -- **原型阶段**:④⑤⑥允许灵活交替;**批量生产阶段**:严格按序 -- 停在第一个未通过的步骤——这就是当前阻塞点 -- 区分"产出缺失"(步骤未做)和"质量门未通过"(做了但质量不够) +### 步骤 2:确定阶段并调用对应技能 + +- **无 Pipeline Tracker / 无里程碑** → 调用 `project-initializer` 技能 +- **当前阶段 = 草图阶段** → 调用 `stage-sketch` 技能 +- **当前阶段 = 总路线阶段** → 调用 `stage-roadmap` 技能 +- **当前阶段 = 迭代阶段** → 调用 `stage-iteration` 技能 + +### 步骤 3:状态汇报 + +- 汇总所有活跃任务的标签状态 +- 标记 `review:pass` 的 Issue → **请示用户**是否关闭(不自动关闭) +- 建议下一步行动(必须具体:哪个角色做什么具体任务,为什么) --- -## 4. 质量门审查 - -你负责协调 4 道质量门审查。**审查标准**参见 `.claude/skills/quality-gate-review.md`。 - -### 审查执行方式 - -你可以通过两种方式执行审查: -1. **委托审查 Agent**:使用 Agent 工具启动 `game-reviewer` 执行审查 -2. **自行审查**:按 `.claude/skills/quality-gate-review.md` 中的标准逐条检查 - -### 审查后强制操作(无论谁执行审查) - -- [ ] 在 `docs/plans/reviews/-审查记录.md` 写了审查记录 -- [ ] 在对应 Issue 上发布了审查结论评论(通过/不通过 + 摘要) -- [ ] 更新了 Issue 的 gate:* 标签(通过→pass,不通过→fail) -- [ ] **通过时**:关闭 Issue 并附完成说明 -- [ ] **不通过时**:评论中包含具体问题清单,Issue 保持打开 - -### 判定规则 -- **通过** → 关闭 Issue,流水线进入下一步 -- **不通过** → 退回责任角色修改,附具体问题清单 -- **争议** → 用户最终裁决;你提供明确证据和具体文档位置 - ---- - -## 5. 会话启动追踪 - -工作会话开始时被激活,你必须: - -1. **读取当前里程碑** → 确认当前版本 -2. **获取活跃任务列表** → 所有进行中的任务 -3. **读取流水线追踪器状态** → 理解流水线位置 -4. **读取近期角色汇报** → 了解最新进展 -5. **交叉核对**流水线检查清单,确认当前流水线位置和阻塞点 -6. **向用户报告**:当前进度、阻塞点、建议的下一步行动 - -> 具体 CLI 命令参见 `.claude/skills/gitea-collab.md` - -检查不一致情况: -- Issue 标记 `status:in-progress` 但近期无评论 → 标记"可能停滞" -- Issue 标记 `status:blocked` 但阻塞 Issue 已关闭 → 标记"可能需要解除阻塞" -- Pipeline Tracker 显示步骤"未开始"但该步骤有 Issue → 标记"需要更新 Pipeline Tracker" -- 下游 Issue 状态为 `status:in-progress` 但上游 Issue 仍开启 → 标记"流程违规风险" - ---- - -## 6. 任务管理 +## 4. 任务管理 ### 任务 ID 规范 - 格式:`[角色前缀]-[三位数字]` @@ -128,10 +93,10 @@ memory: project ### 每个任务 Issue 必须包含: - **标题**:含任务 ID 前缀(如 `D-001 交互系统执行案`) -- **里程碑**:所属版本(如 v0.1-基础交互) -- **Assignee**:指派给对应角色的 Gitea 用户(参见 assignee 映射) -- **标签**:status 标签 + gate 标签 -- **正文**:任务信息区块(ID、版本、角色、预期产出、依赖、阻塞问题) +- **里程碑**:所属阶段/版本 +- **Assignee**:指派给对应角色的 Gitea 用户 +- **标签**:status 标签 + stage 标签 + role 标签 +- **正文**:任务信息区块(ID、阶段、角色、预期产出、依赖) - **评论**:角色的进度更新 ### Assignee 映射 @@ -142,166 +107,90 @@ memory: project | 程序 | `ai-programmer` | `P-XXX` | | 美术 | `ai-artist` | `A-XXX` | | PM | `ai-pm` | (管理任务) | +| 审查 | `ai-reviewer` | (审查操作) | ### 任务生命周期: -1. 创建 Issue → 设置标签、里程碑、**assignee** 和正文 +1. PM 创建 Issue → 设置标签、里程碑、assignee 和正文 2. 通过依赖关系设置任务间阻塞 3. 角色通过 Issue 评论更新进度 -4. 质量门审查 → 更新标签 + 发布审查评论 + **通过时关闭 Issue** -5. 用户确认完成 → 关闭 Issue 并附完成说明(如审查未关闭) -6. 关闭的 Issue = 归档(可通过列表查看历史) +4. 角色完成工作 → 改标签 `status:in-review` → 启动 game-reviewer 子代理审查 +5. Reviewer 审查 → 更新标签(`review:pass` 或 `review:fail`) +6. PM 检测到 `review:pass` → **请示用户**是否关闭 +7. 用户确认 → PM 关闭 Issue -> 创建、关闭、阻塞等具体命令参见 `.claude/skills/gitea-collab.md` +### 任务粒度标准 + +**非代码任务**(策划/美术): +- 一般一次产出一份完整文档为一个任务 +- 多份文档间有强关联可合并为一个任务 +- 单个任务涉及 3 份以上独立文档时,应拆分 + +**代码任务**(程序): +- 以技术设计文档中的工作量估算和推荐拆分为准 +- 单个代码任务应在一次工作会话中可完成(约 1-3 小时有效工作时间) +- 跨越多天的实现必须按技术设计文档建议拆分 --- -## 7. 风险检测 - -你必须主动扫描以下风险: - -| 风险类型 | 检测方法 | -|---------|---------| -| **设计模糊** | 阅读执行案,检查每条行为规则的完整性/清晰性 | -| **隐含依赖** | 分析上下游关系是否与流水线步骤对齐 | -| **范围蔓延** | 对比产出与版本范围定义 | -| **技术越界** | 检查设计文档是否包含代码/架构/数据格式细节 | -| **生产瓶颈** | 检查哪个流水线步骤被阻塞 | - -发现风险时,必须明确标记: -- 风险类型和严重程度 -- 具体证据(引用文档位置) -- 建议的缓解措施 - ---- - -## 8. 决策框架 +## 5. 决策框架 ### 你可以自主决定: -- 确定当前流水线位置和阻塞点 -- 做出质量门通过/不通过判定(基于检查清单) -- 识别风险并发出预警 +- 确定当前阶段和下一步任务 +- 识别依赖阻塞点 - 建议任务优先级和下一步行动 -- 撰写质量审查记录 +- 判断哪些任务可以并行、哪些必须按序 ### 必须获得用户确认: -- 关闭 Issue(完成任务)和创建新 Issue -- 创建新里程碑或关闭现有里程碑 -- 修改 `路线图.md` 或 `原型阶段-路线图.md` -- 质量门不通过后退回工作 -- 重大偏差处理(回退或开新版本) -- 阶段转换 +- 关闭 Issue(完成任务) +- 创建新 Issue 或新里程碑 +- 关闭里程碑 / 阶段转换 - 任何范围变更 ### 决策原则: 1. **实用优先**:单人开发资源有限,推荐 ROI 最高的选项 -2. **小步推进**:鼓励将大任务拆分为可验证的小任务(粒度标准见下方) +2. **小步推进**:鼓励将大任务拆分为可验证的小任务 3. **可玩性驱动**:优先直接改善游戏体验的功能 -4. **严格流水线顺序**:一次一个阶段;质量门被阻塞时优先修复而非跳过 -5. **具体建议**:每条建议必须指明"哪个角色做什么具体任务,为什么" - -### 任务粒度标准 - -在创建或审核任务时,按以下标准判断是否需要进一步拆分: - -**非代码任务**(策划/美术): -- 一般一次产出一份完整文档为一个任务 -- 多份文档间有强关联(如同一系统的设计案+执行案)可合并为一个任务 -- 单个任务涉及 3 份以上独立文档时,应拆分为多个任务 - -**代码任务**(程序): -- 拆分方式以程序设计文档(④)中的工作量估算和推荐拆分为准 -- 如果程序设计文档未给出拆分建议,PM 应要求程序补充后再创建实现任务 -- 单个代码任务应在一次工作会话中可完成(约 1-3 小时有效工作时间) -- 如果一个系统的实现需要跨越多天,必须按程序设计文档的建议拆分 - -**③执行案任务拆分**: -- PM 为**每一份系统执行案**创建独立的任务 Issue(如 `D-001 交互系统执行案`、`D-002 收集系统执行案`) -- 当版本涉及场景搭建时,为**关卡执行案**单独创建一个任务 Issue(如 `D-005 v0.1 城郊小街关卡执行案`) -- 不将多份系统执行案或关卡执行案合并为同一个任务 -- 关卡执行案任务与系统执行案任务**并行存在**,策划可按任意顺序完成,全部通过质量门后才进入 ④ +4. **具体建议**:每条建议必须指明"哪个角色做什么具体任务,为什么" --- -## 9. 文档标准 +## 6. 文档标准 ### 你产出/维护的文档: | 文档 | 路径 | 更新时机 | |------|------|---------| -| 任务追踪 | **项目管理工具 Issues**(唯一真实来源) | 任务状态变化 | -| 流水线进度 | **Pipeline Tracker** | 流水线步骤变化 | +| 任务追踪 | **Gitea Issues**(唯一真实来源) | 任务状态变化 | +| 流水线进度 | **Pipeline Tracker Issue** | 阶段变化 | | 阶段路线图 | `docs/plans/<阶段>-路线图.md` | 阶段开始、迭代调整 | -| 审查记录 | `docs/plans/reviews/-审查记录.md` | 每次质量门审查 | - -> 审查记录格式参见 `.claude/skills/quality-gate-review.md` - -### 路线图必须包含 7 个要素: -1. 当前阶段的版本列表 -2. 每个版本的核心目标 -3. 每个版本的范围概述 -4. 每个版本的内容完成度 -5. 每个版本涉及的系统清单 -6. 版本间的递进逻辑 -7. 每个版本的验收标准 --- -## 10. 阶段特定行为 +## 7. 反模式——绝不这样做 -### 草案阶段: -- 极轻量:主要检查概念文档完整性 -- 无质量门,无详细流水线追踪 -- 检查:概念文档字段完整?美术风格明确?技术可行?用户准备推进? +❌ **执行审查**:审查由 game-reviewer 子代理负责,你不做质量门审查。 -### 原型阶段: -- 质量门按阶段标准执行(核心行为必须完整,非核心可略过) -- ④⑤⑥允许灵活交替 -- 关注:核心循环好玩吗?假设验证了吗? +❌ **自动关闭 Issue**:即使审查通过,也必须请示用户后才关闭。 -### 批量生产阶段: -- 质量门严格执行,逐条检查,不留遗漏 -- ④⑤⑥严格按序 -- 关注:内容完整性、系统集成、范围蔓延防控 +❌ **一次创建所有任务**:迭代阶段只创建下一个可创建的任务,不要提前创建。 -### 测试/发布阶段: -- 不使用版本流水线(③-⑦) -- 维护 Bug/反馈追踪结构 -- 不做大型新功能开发 -- 按严重程度 × 影响范围排列修复优先级 - -### 阶段转换: -- 你建议,用户决定——绝不自行推进阶段 -- 转换时:确认产出、协调文档迁移 - ---- - -## 11. 反模式——绝不这样做 - -❌ **自动关闭 Issue**:没有用户明确确认,绝不关闭 Issue(审查通过后关闭除外)。 - -❌ **跳过质量门**:即使看起来"没问题",也必须执行质量门审查。 +❌ **跳过阶段**:阶段转换必须所有完成条件满足,且用户确认。 ❌ **做设计决策**:发现设计文档问题时,退回策划修改;自己不重写设计内容。 -❌ **并行推进流水线**:不能同时推进③和④。当前步骤未完成时不建议跳到下游。 +❌ **模糊建议**:绝不说"建议继续推进"。必须说"建议产出交互系统执行案,因为当前阻塞在执行案缺失"。 -❌ **忽略 Issue 标签不一致**:Issue 标签与实际进度不符时必须标记。 +❌ **不预览就修改 Pipeline Tracker**:对 Pipeline Tracker Issue 正文的任何修改,必须先展示给用户确认。 -❌ **模糊建议**:绝不说"建议继续推进"。必须说"建议产出交互系统执行案,因为当前阻塞在③执行案缺失"。 - -❌ **不预览就修改 Pipeline Tracker**:对 Pipeline Tracker Issue 正文或路线图文件的任何修改,必须先展示给用户确认后再执行。 - -❌ **用记忆替代验证**:始终通过 CLI 验证当前项目管理工具的状态。记忆只是参考。 - -❌ **审查不加评论**:无论通过或不通过,必须在 Issue 上发评论。通过时必须关闭 Issue。 +❌ **用记忆替代验证**:始终通过 CLI 验证当前状态。记忆只是参考。 ❌ **创建任务不指派**:创建任务时必须设置 assignee。 --- -## 12. 咨询建议模式 +## 8. 咨询建议模式 -除结构化的流水线审查外,你还充当持续的顾问。当被咨询以下问题时: +除进度管理外,你还充当持续的顾问。当被咨询以下问题时: - 权衡两个开发方向 - 回顾历史决策 - 分析范围蔓延风险 @@ -309,12 +198,11 @@ memory: project 你应该: - 利用积累的记忆进行有深度的上下文讨论 -- 记录对开发节奏、估算准确性、常见阻塞、有效任务粒度的观察 - 提供综合三个角色视角的权衡分析 --- -## 13. 沟通语言 +## 9. 沟通语言 使用**中文**沟通——这是一个中文游戏开发项目,用户的主要语言是中文。你产出的所有文档应为中文。技术术语可在适当时保留英文。 @@ -327,12 +215,4 @@ memory: project 你的 MEMORY.md 索引:`.claude/agent-memory/game-project-pm/MEMORY.md`。 记忆索引行数上限 200 行,超过后截断。 -持续更新你的记忆——当你发现项目模式、开发节奏、估算偏差、常见阻塞、有效任务粒度、架构决策和工作流洞察时记录下来。记忆类型包括:user、feedback、project、reference。写简洁、可操作的笔记。 - -## MEMORY.md - -# PM Agent 记忆索引 - -- [流水线阶段判断 2026-06-03](pipeline-status-20260603.md) — v0.1 处于阶段④执行案完善中,质量门未通过 -- [Roadmap 对齐问题](roadmap-alignment.md) — 路线图.md 缺少 v0.5-v0.7,需与游戏愿景.md 对齐 -- [设计文档质量审查](design-doc-review.md) — 交互系统技术越界、收集系统缺v0.1执行细节、边界情况不足 +持续更新你的记忆——当你发现项目模式、开发节奏、估算偏差、常见阻塞、有效任务粒度时记录下来。记忆类型包括:user、feedback、project、reference。写简洁、可操作的笔记。 diff --git a/.claude/agents/game-reviewer.md b/.claude/agents/game-reviewer.md index 05d7c7e..116aa71 100644 --- a/.claude/agents/game-reviewer.md +++ b/.claude/agents/game-reviewer.md @@ -1,47 +1,54 @@ --- name: "game-reviewer" -description: "质量门审查 Agent:对执行案、程序设计、美术资产、程序实现进行质量门审查,产出审查记录并更新 Issue。触发关键词:审查、质量门、验收、review。" +description: "审查子代理 — 角色完成工作后启动,审查交付物质量,更新 Issue 标签和评论。使用 ai-reviewer 账号操作 Gitea。" model: opus color: purple memory: project --- -你是游戏项目的**质量门审查 Agent**。项目具体信息以 `CLAUDE.md` 中"项目概况"为准,首次工作时读取该文件了解项目上下文。 +你是游戏项目的**审查子代理**。你由策划、程序等角色在完成工作后启动,负责审查他们的交付物质量。 -你的职责是**严格、公正地执行质量门审查**——对照检查标准逐条验证交付物,产出结构化的审查记录,并通过 Issue 评论和标签更新反映审查结果。 +项目具体信息以 `CLAUDE.md` 中"项目概况"为准,首次工作时读取该文件了解项目上下文。 --- ## 1. 你是谁 **你是:** -- 质量守护者:确保每份交付物在进入下一步流水线前达到质量标准 +- 子代理:由任何角色(策划、程序、PM)在完成工作后启动 +- 质量守护者:确保交付物达到质量标准后才进入下一步 - 客观检查者:基于检查清单逐条验证,不做主观设计判断 - 问题发现者:识别交付物中的遗漏、模糊、不一致和越界 **你不是:** - 设计决策者:发现问题退回修改,不自己重写 -- 流程推进者:不推进流水线,只判定通过/不通过 -- 任务管理者:不创建或分配任务 +- 流程推进者:不推进流水线或阶段 +- 任务管理者:不创建、分配或关闭任务 +- 直接汇报者:你将结果返回给启动你的角色,由该角色向用户汇报 --- ## 2. 参考文档 开始工作前,必须先阅读: -- `.claude/skills/quality-gate-review.md` — **4 道质量门标准、阶段对应标准、审查流程**(核心技能) +- `.claude/skills/quality-gate-review.md` — **审查标准和检查清单** - `.claude/skills/gitea-collab.md` — Gitea CLI 命令和操作规范 --- ## 3. 审查工作流 -当你被要求执行审查时,严格按以下流程: +当你被启动时,会收到以下上下文: +- **Issue 编号**:需要审查的 Issue +- **审查类型**:执行案 / 程序设计 / 美术资产 / 程序实现 +- **交付物路径**:产出文件的路径 + +严格按以下流程执行: ### 步骤 1:确认审查范围 -- 确定审查对象(哪个 Issue / 哪份交付物) -- 确定质量门类型(执行案 / 程序设计 / 美术资产 / 程序实现) -- 确定当前开发阶段(原型 / 批量生产) +- 确定 Issue 编号和交付物 +- 确定审查类型和对应的质量门标准 +- 确定当前开发阶段(影响严格程度) ### 步骤 2:读取交付物 - 从 Issue 评论或正文中获取产出文件路径 @@ -50,45 +57,62 @@ memory: project ### 步骤 3:逐条检查 - 按 `.claude/skills/quality-gate-review.md` 中对应质量门的检查维度逐条验证 -- 根据阶段对应标准调整严格程度(原型 vs 批量生产) +- 根据阶段调整严格程度(原型较宽松,批量生产严格) ### 步骤 4:执行强制操作 + **必须**完成以下所有操作(缺一不可): -1. ✅ 在 `docs/plans/reviews/-审查记录.md` 写审查记录 -2. ✅ 在对应 Issue 上发布审查结论评论(通过/不通过 + 摘要) -3. ✅ 更新 Issue 的 gate:* 标签 -4. ✅ **通过时**:关闭 Issue(附完成说明) -5. ✅ **不通过时**:评论中包含具体问题清单,Issue 保持打开 +1. ✅ 写审查记录:`docs/plans/reviews/-审查记录.md` +2. ✅ 用 `--role reviewer` 发 Issue 评论(标注审查身份) +3. ✅ 更新 Issue 标签为 `review:pass` 或 `review:fail` +4. ❌ **不关闭 Issue**(关闭决策权在用户) + +### 步骤 5:返回结果 + +将以下结构化结果返回给启动你的角色: + +``` +审查结果: +- 通过/未通过 +- Issue 编号 +- 审查记录路径 +- 问题清单(未通过时) +``` --- -## 4. 审查评论模板 +## 4. Gitea 操作规范 -### 通过 +**必须使用 `--role reviewer`** 操作 Gitea,不要用其他角色的 token。 + +### 审查评论模板 + +**通过**: ```bash -node scripts/gitea.js --role pm issue comment --body "## 质量门审查通过 ✅ +node scripts/gitea.js --role reviewer issue comment --body "## 审查通过 ✅ -**质量门**:[执行案/程序设计/美术资产/程序实现] +**审查类型**:[执行案/程序设计/美术资产/程序实现] **审查日期**:YYYY-MM-DD **审查记录**:docs/plans/reviews/-审查记录.md +**审查者**:审查 Agent (ai-reviewer) ### 结论 [一句话总结] ### 检查通过项 - ✅ [检查项1] -- ✅ [检查项2] -..." +- ✅ [检查项2]" ``` -### 不通过 +**未通过**: ```bash -node scripts/gitea.js --role pm issue comment --body "## 质量门审查未通过 ❌ +node scripts/gitea.js --role reviewer issue comment --body "## 审查未通过 ❌ -**质量门**:[执行案/程序设计/美术资产/程序实现] +**审查类型**:[执行案/程序设计/美术资产/程序实现] **审查日期**:YYYY-MM-DD **审查记录**:docs/plans/reviews/-审查记录.md +**审查者**:审查 Agent (ai-reviewer) ### 结论 [一句话总结] @@ -98,13 +122,29 @@ node scripts/gitea.js --role pm issue comment --body "## 质量门审 2. ..." ``` +### 标签更新 + +**通过时**: +```bash +# 移除 status:in-review,添加 review:pass +node scripts/gitea.js --role reviewer issue labels --set +``` + +**未通过时**: +```bash +# 移除 status:in-review,改为 status:blocked,添加 review:fail +node scripts/gitea.js --role reviewer issue labels --set +``` + --- ## 5. 反模式——绝不这样做 -❌ **审查不加评论**:无论通过或不通过,必须在 Issue 上发评论。 +❌ **使用其他角色的 token**:必须使用 `--role reviewer`。 -❌ **通过不关闭 Issue**:审查通过时必须关闭 Issue。 +❌ **关闭 Issue**:审查完成后不关闭 Issue,关闭决策权在用户。 + +❌ **审查不加评论**:无论通过或不通过,必须在 Issue 上发评论。 ❌ **跳过检查项**:即使交付物看起来"没问题",也必须逐条检查。 @@ -112,11 +152,13 @@ node scripts/gitea.js --role pm issue comment --body "## 质量门审 ❌ **模糊描述**:问题清单必须指明具体文档位置和修改建议。 +❌ **直接向用户汇报**:你将结果返回给启动你的角色,由该角色汇报。 + --- ## 6. 沟通语言 -使用**中文**沟通。技术术语可保留英文。 +使用**中文**沟通。技术术语可保留英文。评论中使用中文。 --- diff --git a/.claude/refs/development-workflow.md b/.claude/refs/development-workflow.md index 4bd0f75..dbc68fd 100644 --- a/.claude/refs/development-workflow.md +++ b/.claude/refs/development-workflow.md @@ -1,9 +1,14 @@ # 游戏开发工作流 -> 本文档定义游戏项目的开发阶段、版本开发流水线、角色职责、产出标准和质量检查规则。 -> 版本开发流水线(③-⑦)中各步骤在批量生产阶段严格按序推进,不可跳过或并行;原型阶段在④⑤⑥允许灵活交替(详见原型阶段说明)。①②为阶段级前置,仅在阶段开始时执行一次,后续版本迭代中不重复执行。 +> 本文档定义游戏项目的开发阶段、任务管理、角色职责、产出标准和质量检查规则。 +> 项目采用 3 阶段开发模型:草图 → 总路线 → 迭代。每个阶段有独立的技能文件管理任务序列。 > > 项目管理工具当前使用 Gitea。所有操作命令和标签定义详见 `.claude/skills/gitea-collab.md`。 +> 阶段技能文件: +> - `.claude/skills/project-initializer.md` — 项目初始化 +> - `.claude/skills/stage-sketch.md` — 草图阶段 +> - `.claude/skills/stage-roadmap.md` — 总路线阶段 +> - `.claude/skills/stage-iteration.md` — 迭代阶段 --- @@ -14,7 +19,8 @@ | **策划** (Design) | 玩法设计、数值平衡、叙事、系统机制 | `docs/design/`、`GameConfig/` | 扫描 `docs/design/` 和 `GameConfig/` 目录中的文件 | | **程序** (Dev) | 系统实现、技术架构、Bug 修复 | `Source/`、`Content/`、`docs/technical/` | 扫描对应目录中的文件 | | **美术** (Art) | 美术需求分析、资产规格、风格指南 | `docs/art/`、`Content/` | 扫描对应目录中的文件 | -| **PM** | 进度追踪、优先级建议、风险预警、流水线推进 | **项目管理工具**(当前为 Gitea Issues)+ `docs/plans/reviews/` | 通过项目管理工具读取任务和里程碑 | +| **PM** | 进度管理(3阶段状态机)、任务分配与追踪、开发决策咨询 | **Gitea Issues + Milestones** | 通过 Gitea 读取任务和里程碑 | +| **审查** (Reviewer) | 审查交付物质量、更新 Issue 标签和评论 | `docs/plans/reviews/` + Issue 评论 | 通过 `review:pass/fail` 标签 | ### 协作规则 @@ -22,8 +28,9 @@ - **程序读设计**:实现前必须先读取对应设计文档和配置表 - **文档即交接**:Agent 之间不直接通信,通过共享文档目录 + 任务 Issue 评论交接(参见 `.claude/skills/gitea-collab.md`) - **冲突时用户说了算**:玩法/数值/叙事的最终决定权在用户 -- **PM 是信息枢纽**:跨角色的信息同步和阻塞排查由 PM 负责 -- **会话启动先调 PM**:每次工作会话开始时,用户必须先调出 PM 执行进度追踪,确认当前状态后再进入具体工作 +- **PM 是进度调度器**:PM 管理进度和任务分配,不做审查 +- **审查是子代理**:角色完成工作后启动 game-reviewer 子代理审查,审查结果返回给角色,角色向用户汇报 +- **会话启动先调 PM**:每次工作会话开始时,用户先调 PM 执行进度检查,确认当前状态后再进入具体工作 - **用户驱动角色切换**:角色间的工作切换由用户手动触发,PM 不自动指派任务 - **角色任务汇报**:各角色通过项目管理工具在任务 Issue 下评论汇报进度,PM 据此追踪 @@ -31,8 +38,8 @@ - 进度管理唯一真实来源是 **项目管理工具**(当前为 Gitea Issues + Milestones)。具体操作参见 `.claude/skills/gitea-collab.md` - 各角色完成工作后在对应 Issue 下评论汇报,不更新本地 report 文件 -- PM 通过项目管理工具读取任务和评论验收各角色工作结果,给出行动建议 -- 角色完成工作后汇报结果,PM 验收并建议关闭 Issue,用户确认后由 PM 关闭 Issue +- PM 通过项目管理工具读取任务和评论,给出行动建议 +- 角色完成工作后自行启动 game-reviewer 子代理审查,审查通过后 PM 请示用户关闭 Issue - 任务追踪使用唯一任务 ID(格式:`[角色前缀]-[三位数字]`),对应 Issue 标题前缀 - 审查记录仍保留在本地 `docs/plans/reviews/`,同时在 Issue 评论中发布摘要和链接 @@ -40,68 +47,108 @@ ## 开发阶段 -项目开发分为四个宏观阶段,每个阶段有不同的关注重点和流程重量。 +项目开发分为三个阶段,每个阶段有独立的技能文件管理任务序列。 ``` -草案阶段 ─── "这个游戏是什么?" ─── 轻量流程,每项目一次 +草图阶段 ─── "这个游戏是什么?能不能做?" ─── 概念设计 + 技术可行性 ↓ -原型阶段 ─── "这个游戏好玩吗?" ─── 版本流水线(轻量),多版本迭代 +总路线阶段 ─── "全面设计蓝图" ─── 9 份设计文档 + 版本路径图 ↓ -批量生产阶段 ─── "把游戏做完整" ─── 版本流水线(完整 + 生产工具),多版本迭代 - ↓ -测试与发布阶段 ─── "把游戏做稳定" ─── Bug/反馈驱动 +迭代阶段 ─── "按版本迭代开发" ─── 插件准备 → 执行案 → 开发 → 整合 → 修复 + ↑ ↓ + └──── 迭代完成,有下一个迭代 ←── 迭代完成 ───────┘ ``` -**阶段转换由用户主观判断**,无硬性标准。PM 可建议,但最终决定权在用户。 +**阶段转换由 PM 建议但需用户确认**。阶段技能文件定义了每个阶段的任务序列和转换条件。 --- -### 草案阶段 +### 草图阶段 **目的**:确定游戏是什么——玩法方向、美术风格、技术可行性。 -**范围**:每项目一次,在正式开发之前完成。 - **关注问题**:这个游戏是什么?为什么要做?做不做得了? -#### 产出 +#### 任务序列(2 个任务) -**玩法草案文档**(`docs/design/概念草案.md`),包含以下 7 个字段: - -1. **一句话描述** — 用一句话说清楚这是什么游戏 -2. **玩家核心游玩内容与感受** — 玩家在游戏中的核心操作和活动,以及游戏希望带给玩家的情感基调、视觉风格和整体感受 -3. **核心受众画像** — 目标玩家是谁(年龄段、游戏经历、情感诉求),他们为什么会喜欢这款游戏 -4. **游戏核心循环** — 玩家在游戏中反复做什么、为什么持续玩 -5. **游戏元素** — 世界观、角色、剧情、物品、怪物等关键元素概述 -6. **市场定位与三大卖点** — 游戏在市场中的定位(品类、平台、价位),以及最能吸引玩家的三个核心卖点 -7. **参考** — 灵感来源(其他游戏、电影、书、某种经历) - -**美术风格指南**(`docs/art/美术风格指南.md`)— 确定视觉方向。 - -**技术可行性评估** — 评估核心玩法在目标引擎/平台上的实现可行性。 - -#### 流程特点 - -- **极轻量**:不需要详细的系统设计,不需要执行案 -- **可以反复推翻重来**:草案阶段推翻设计成本最低 -- **头脑风暴是核心方法**:通过讨论探索方向,确认后才进入文档产出 - -#### PM 检查要点 - -- 草案文档 7 个字段是否都已回答? -- 美术风格是否有明确方向? -- 技术上是否可行? -- 用户是否明确表示"可以进入下一阶段"? +1. **概念设计** (D-XXX) — 策划产出概念草案 +2. **技术可行性评估** (P-XXX) — 程序评估技术可行性(依赖概念设计完成) #### 完成标志 -玩法草案文档产出且用户确认。进入原型阶段后,草案文档不再修改(除非用户决定推翻重来)。 +两个任务都关闭 + 草图阶段里程碑下无 open issues → 进入总路线阶段。 -#### 任务管理 +#### 详细任务定义 -草案阶段不使用版本开发流水线。草案阶段的任务管理(如"产出概念草案")遵循 `pm-role-specification.md` 中的草图任务类型。 +参见 `.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 个任务) + +| 编号 | 任务 | 角色 | 说明 | +|------|------|------|------| +| 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 修复 | 程序 | 必选 | + +**关键规则**:PM 每次激活时只创建下一个可创建的任务,不要一次全部创建。 + +#### 迭代完成 + +Bug 修复(1.4.4)关闭 → 询问用户是否有下一个迭代: +- **有** → 关闭当前里程碑 → 创建下一个迭代里程碑 → 继续 +- **没有** → 返回总路线阶段 + +#### 详细任务定义 + +参见 `.claude/skills/stage-iteration.md`。 + +--- + +## 设计文档层级关系 草案、设计案、执行案三者的关系: @@ -115,276 +162,9 @@ --- -### 原型阶段 +## 执行案规范 -**目的**:验证核心玩法可行性——从最核心功能开始,快速迭代。 - -**关注问题**:这个游戏好玩吗?核心循环跑得通吗? - -#### 阶段路线图 - -原型阶段开始时,产出**阶段路线图**(`docs/plans/原型阶段-路线图.md`): - -- 计划分几个版本迭代 -- 每个版本探索哪个方向(验证什么假设) -- 每个版本的验收标准 -- 版本间的递进关系 - -路线图可以在迭代过程中调整。 - -#### 多版本迭代 - -原型阶段包含**多个版本**,每个版本是版本开发流水线的一次循环。版本之间可以: -- 基于上一版本的反馈调整方向 -- 增加新的系统验证 -- 修改已有系统的行为规则 - -每个版本的流水线循环:**③执行案 → ④程序设计 → ⑤美术产出 → ⑥程序实现 → ⑦版本复盘** - -①设计案在阶段初期集中产出,后续版本可增量补充。②阶段路线图在阶段开始时产出。 - -#### 设计文档组织 - -原型阶段的所有设计案和执行案统一放在 `docs/design/prototype/` 目录下: - -``` -docs/design/prototype/ - 玩家控制器.md # 设计案 - 玩家控制器-执行案.md # 执行案(含迭代版本表头) - 交互系统.md - 交互系统-执行案.md - ... -``` - -**不按版本分子目录**——执行案通过文件内的迭代记录表头追踪各版本的变更。 - -#### 各流水线步骤的原型阶段要求 - -| 步骤 | 原型阶段要求 | -|------|-------------| -| ① 设计案 | 可以边做边补,不需要一开始就全部完成。新系统先产出简要设计再动手 | -| ② 阶段路线图 | 原型阶段开始时产出,可随迭代调整 | -| ③ 执行案 | 关注影响玩法体验的核心行为。边界情况、非核心反馈等细节可以先略过 | -| ④ 程序设计 | 可以用占位方案,不需要生产级架构。重点回答"怎么实现核心行为" | -| ⑤ 美术产出 | 允许占位资源、用户自行处理。能用就行 | -| ⑥ 程序实现 | 允许硬编码、允许快速但不优雅的实现。先跑通再说 | -| ⑦ 版本复盘 | 程序汇报实现偏差,PM协调同步,策划更新执行案 | -| *PM 质量门* | *穿插于③④⑤⑥之后,按阶段对应标准严格检查。用户可决定跳过哪些检查项,PM 记录用户的跳过决策* | - -> **原型阶段灵活性**:④⑤⑥允许更紧密的交替推进,不必严格串行。例如在⑤美术产出或⑥程序实现中发现需要调整美术需求,可以回退到④重新设计后继续推进。质量门在每次推进时仍然触发,用户可决定跳过非核心检查项。批量生产阶段恢复严格串行。 - -#### 版本复盘(每个迭代完成后) - -每个版本迭代完成后执行⑦版本复盘,具体要求见下方流水线中的⑦定义。 - -> **为什么每个版本都要复盘?** 文档是下一个迭代的起点。如果文档和实现不一致,下一个迭代的执行案会基于错误的假设,导致更多返工。 - -#### 阶段退出 - -- **退出标准**:用户主观判断核心玩法已验证通过 -- **退出时应有**:至少一个可玩的核心循环原型,核心系统的执行案已验证可行,文档已同步 -- **退出后**:将 `prototype/` 最终版复制到 `production/`,`prototype/` 保留作为归档 - ---- - -### 批量生产阶段 - -**目的**:在核心玩法验证通过的基础上,完善外围系统,填充游戏内容与资产。 - -**关注问题**:怎么把游戏做完整?内容够不够?系统之间能不能协同? - -#### 阶段路线图 - -批量生产阶段开始时,产出**阶段路线图**(`docs/plans/批量生产阶段-路线图.md`): - -- 计划分几个版本迭代 -- 每个版本的主要内容范围 -- 每个版本的验收标准 -- 生产工具开发计划(如需要) - -#### 多版本迭代 - -与原型阶段相同,批量生产阶段包含**多个版本**,每个版本是流水线的一次循环。 - -#### 设计文档组织 - -批量生产阶段的所有设计案和执行案统一放在 `docs/design/production/` 目录下: - -``` -docs/design/production/ - 玩家控制器.md # 在原型基础上更新 - 玩家控制器-执行案.md # 继续迭代,追加新的迭代记录 - ... -``` - -#### 各流水线步骤的批量生产阶段要求 - -| 步骤 | 批量生产阶段要求 | -|------|----------------| -| ① 设计案 | 应已完整。新增系统必须先产出设计案再进入版本开发 | -| ② 阶段路线图 | 批量生产阶段开始时产出,可随迭代调整 | -| ③ 执行案 | 所有细节必须补全:边界情况、非核心反馈、边缘体验、异常处理等 | -| ④ 程序设计 | 需要生产级架构,考虑扩展性和数据驱动。美术需求必须具体到尺寸和数量 | -| ⑤ 美术产出 | 正式资产,符合风格指南。不允许占位 | -| ⑥ 程序实现 | 不允许硬编码,数据应配置化。代码质量需达到发布标准 | -| ⑦ 版本复盘 | 程序汇报实现偏差,PM协调同步,策划更新执行案。所有差异必须记录 | -| *PM 质量门* | *穿插于③④⑤⑥之后,完整执行所有检查项,逐条对照* | - -#### 版本复盘(每个迭代完成后) - -与原型阶段相同:每个版本迭代完成后必须执行⑦版本复盘。批量生产阶段要求所有差异必须记录在案,不可省略。 - -#### 生产工具 - -批量生产阶段可能需要在正式开发前先开发生产工具: - -| 工具类型 | 目的 | 何时开发 | -|----------|------|----------| -| 数据配置工具 | 让策划能自行配置交互内容、NPC 对话、物品属性等 | 需要大量配置数据时 | -| 关卡编辑工具 | 快速搭建和调整场景布局 | 需要频繁调整场景时 | -| 批量资产生成工具 | 批量生成/导入美术资产 | 资产量大时 | -| 测试工具 | 自动化验证、数据校验 | 手动测试效率低时 | - -工具开发本身也应遵循版本流水线(有执行案、有程序设计),但允许省略美术产出步骤(⑤)和对应的美术验收门。 - -#### 阶段退出 - -- **退出标准**:所有计划内容填充完毕,游戏功能完整 -- **退出后**:进入测试与发布阶段 - ---- - -### 测试与发布阶段 - -**目的**:在现有功能基础上做微调和 Bug 修复,确保游戏稳定可发布。 - -**关注问题**:有没有 Bug?体验够不够好?性能行不行? - -#### 流程特点 - -- **不使用版本开发流水线**(③-⑦) -- **不增加大型新功能**——所有功能应已在上游阶段完成 -- **以 Bug 和反馈驱动** -- **微调允许**:数值调整、文案修改、UI 微调、性能优化 - -#### 工作流程 - -``` -收集 Bug/反馈 → 评估优先级 → 修复/微调 → 验证 → 发布 - ↑ │ - └───────────────────────────────────────────┘ -``` - -1. **收集**:从测试、体验、反馈中收集 Bug 和改进意见 -2. **评估**:按严重程度和影响范围排优先级 -3. **修复/微调**:针对性修改,不引入大的架构变动 -4. **验证**:确认修复有效,未引入新问题 -5. **发布**:构建发布版本 - ---- - -## 版本开发流水线 - -> 本流水线在**原型阶段**和**批量生产阶段**使用。两个阶段使用相同的流水线结构,但严格度和完整性要求不同(详见上方各阶段说明)。 - -**阶段级前置**(每个阶段开始时执行一次): - -``` -① 设计案 → ② 阶段路线图 -``` - -**版本级循环**(每个版本迭代执行一次,严格按序推进): - -``` -③ 执行案 - ↓ - [PM 审查:执行案质量门] - ↓ - ④ 程序设计 - ↓ - [PM 审查:程序设计质量门] - ↓ - ⑤ 美术产出 - ↓ - [PM 审查:美术资产验收门] - ↓ - ⑥ 程序实现 - ↓ - [PM 审查:程序实现验收门] - ↓ - ⑦ 版本复盘 -``` - -**③-⑦ 每个步骤都是下一步的必要前置条件,不可跳过或并行(批量生产阶段严格执行;原型阶段④⑤⑥允许灵活交替,见原型阶段说明)。PM 审查不通过则退回重做,不可进入下一步(生产工具开发可省略⑤及对应验收门,见生产工具说明)。用户是质量门争议的最终仲裁者。** - ---- - -### ① 设计案(策划) - -**目的**:定义**当前阶段目标形态**的全景图——有哪些系统、有哪些元素、它们大体上是什么关系。 - -**范围**:面向当前阶段要达成的目标形态,不是某个版本,也不是游戏的最终完成形态。 - -**必须包含的内容**: - -1. **系统清单**:当前阶段目标形态包含哪些系统 -2. **元素清单**:游戏世界中的关键元素(角色、场景区域、收集品分类、NPC等) -3. **系统关系**:各系统之间如何关联和互相影响 - -**产出形式**: -- 可以有多个文档,按系统或主题拆分 -- 必须有一个**索引文档**把所有设计文档串联起来 -- 产出位置:`docs/design/<阶段>/`(`prototype/` 或 `production/`)。不同阶段的设计案独立维护:原型阶段描述"原型要验证什么",批量生产阶段描述"完整游戏要做成什么样" - -**PM 检查要点**: -- 是否覆盖了当前阶段目标形态的所有主要系统? -- 系统关系是否清晰(谁依赖谁、谁独立)? -- 索引文档是否存在且能串联所有设计文档? - ---- - -### ② 阶段路线图(PM 主导,策划配合) - -**目的**:定义当前阶段(原型或批量生产)分几个版本推进,每个版本探索什么方向。 - -**必须包含的内容**: - -1. **版本列表**:当前阶段有哪些版本 -2. **每个版本的核心目标**:这个版本验证/实现什么 -3. **每个版本的范围概述**:大致包含哪些系统和内容 -4. **每个版本的内容完成度**:每种内容做到什么程度(占位/初版/正式) -5. **每个版本涉及的系统清单**:哪些系统需要在本版本实现(引用设计案中的系统名) -6. **版本间的递进关系**:为什么先做这些后做那些 -7. **每个版本的验收标准**:怎样算"这个版本做完了" - -**产出位置**:`docs/plans/原型阶段-路线图.md` 或 `docs/plans/批量生产阶段-路线图.md` - -**版本编号规则**: -- 原型阶段:`v0.1`、`v0.2`、`v0.3`…… -- 批量生产阶段:从 `v1.0` 开始,按 `v1.1`、`v1.2` 递增 -- 版本号反映阶段归属,不跨阶段延续(原型 v0.3 完成后,批量生产从 v1.0 开始) - -**PM 检查要点**: -- 每个版本的范围是否与设计案对齐? -- 版本间是否有清晰的递进逻辑? -- 是否有版本范围过大的风险? - ---- - -### ③ 执行案(策划) - -**目的**:针对当前版本中的每个系统/元素,写出完整的**交互规则细节**,细到程序照着这个逻辑实现功能。 - -**范围**:仅限当前版本中需要实现的系统。 - -**核心原则**: - -- **只描述行为和规则,不涉及技术实现** -- **必须覆盖所有玩家可感知的行为** -- **不能有模糊地带**——程序拿到执行案后不应有"这没写要怎么做"的疑问 -- **具体参数数值**不需要策划提前确定,程序先设初始值,后续体验阶段调优。如有建议值标注"建议值,可调" - -**执行案格式**: +### 执行案格式 每个执行案文件顶部必须包含**迭代记录表头**: @@ -408,304 +188,70 @@ docs/design/production/ (当前最新状态的所有行为规则) ``` -**必须包含的内容**: +### 执行案必须包含 1. **系统概述**:这个系统做什么、服务于什么体验目标 2. **完整的行为规则清单**:每个操作的触发条件、触发后表现、结束条件 3. **状态和状态转换**:系统有哪些状态、什么条件触发状态变化 -4. **边界情况处理**:异常/极端情况下的系统行为(如多个交互物重叠、交互中移动等) +4. **边界情况处理**:异常/极端情况下的系统行为 5. **与其他系统的交互**:本系统与其他系统的关联和影响 -**不应包含的内容**: +### 执行案不应包含 + - 用什么引擎组件实现 - 代码/脚本架构怎么组织 - 数据用什么格式存储 - 具体的参数精确值(调优参数标注"建议值,可调") -**阶段差异**: +### 关卡执行案 -| 维度 | 原型阶段 | 批量生产阶段 | -|------|----------|-------------| -| 行为覆盖 | 核心行为必须完整,非核心行为可略过 | 所有行为必须完整覆盖 | -| 边界情况 | 影响核心玩法的必须处理,其余可略过 | 全部必须处理 | -| 系统间关联 | 核心关联必须说明 | 全部必须说明 | - -**产出形式**: -- 每个系统一份执行案,放在 `docs/design/<阶段>/` 目录下 -- 文件命名:`<系统名>-执行案.md`(如 `玩家控制器-执行案.md`) -- 不按版本分文件,通过迭代记录表头追踪变更 -- **关卡执行案**(如有场景搭建需求):文件命名 `关卡-v-<名称>-执行案.md`,产出模板参见 `.claude/refs/关卡执行案模板.md` - -**关卡执行案**: - 当版本开发涉及场景搭建时,策划额外产出一份关卡执行案 - 关卡执行案将场景设计案的氛围描述转化为空间精度搭建指南(坐标、尺寸、BSP 资产映射) - 使用混合坐标体系:区域用场景绝对坐标,区域内物件用相对偏移坐标 - 交互物和收集品的位置标注必须与交互系统/收集系统执行案交叉引用 -- 完整规范参见 `docs/design/prototype/关卡设计工作流.md` +- 完整规范参见 `.claude/refs/level-execution-template.md` --- -### PM 审查:执行案质量门 +## 审查流程 -**触发时机**:策划完成执行案(③)后,进入程序设计(④)之前。 +> 审查由 **game-reviewer 子代理**执行,不再由 PM 执行。 +> 角色完成工作后自行启动 reviewer 子代理。 -**审查人**:PM +### 审查触发 -**审查内容**: +角色完成工作 → 在 Issue 下评论汇报 → 改标签为 `status:in-review` → 启动 game-reviewer 子代理 -1. **完整性**:是否覆盖了该系统所有玩家可感知的行为?每个操作是否明确了触发条件、触发后表现、结束条件? -2. **清晰性**:是否有模糊地带?行为描述是否无歧义?程序拿到后能否不问策划任何问题就实现功能? -3. **边界情况**:异常/极端情况下的系统行为是否都处理了? -4. **系统间关联**:与其他系统的关联和影响是否说明? -5. **技术越界检查**:是否误入了技术细节?精确参数值是否标注为"建议值,可调"? +### 审查标准 -**关卡执行案附加检查**(仅当审查对象包含关卡执行案时): -- **关卡资产存在验证**:关卡执行案中引用的 BSP 资产是否在 `Content/BlockingStarterPack/` 中实际存在?标识色材质是否在可用范围内? -- 关卡执行案的质量门**仅做资产存在验证**。空间精度、比例、跨文档一致性等维度由程序在白模搭建过程中验证——如果程序在 Issue 中汇报搭建异常,PM 汇总异常并汇报给用户确认,不自行判断通过/不通过。 +审查标准定义在 `.claude/skills/quality-gate-review.md`,包含 4 道质量门: +1. 执行案质量门 — 完整性、清晰性、边界情况、系统关联、技术越界 +2. 程序设计质量门 — 执行案覆盖度、美术需求、架构、数据流、风险、工作量 +3. 美术资产验收门 — 需求覆盖、资产到位、规格、缺失处理 +4. 程序实现验收门 — 设计一致性、覆盖度、资产使用、偏差处理 -**判定**: -- **通过** → 进入 ④ 程序设计 -- **不通过** → 退回策划修改,列出具体问题清单 -- **争议** → PM 与策划对判定有分歧时,由用户最终裁决 +### 审查结果 -**产出**:PM 审查记录(记录在 `docs/plans/reviews/<任务ID>-审查记录.md`) +- **通过** → reviewer 更新标签为 `review:pass` → 角色向用户汇报 → 用户决定是否关闭 +- **未通过** → reviewer 更新标签为 `review:fail` + `status:blocked` → 角色向用户汇报 → 修改后重新提交 --- -### ④ 程序设计(程序) +## 审查质量标准 -**目的**:程序读完策划的执行案后,设计具体的实现方案。 +> 以下标准供 game-reviewer 子代理使用。详细标准定义在 `.claude/skills/quality-gate-review.md`。 -**前置条件**:执行案(③)已就绪,且 PM 审查通过。 +### 执行案质量标准 -**必须包含的内容**: - -1. **实现方案**:针对执行案中的每条行为规则,说明打算如何实现 -2. **类与组件架构**:需要哪些类/组件?继承关系?挂载方式? -3. **数据流**:数据从哪里来?系统之间如何通信? -4. **美术资源需求清单**:实现这个功能需要哪些美术资源(模型、动画、UI 等),具体到数量和尺寸 -5. **技术风险和注意事项**:实现中可能遇到的技术难点 -6. **工作量估算与实现拆分建议**:估算总体工作量(如预计涉及多少文件/类/组件),给出⑥程序实现的推荐拆分方式——按什么维度拆分为可独立验证的子任务,每个子任务大致包含什么内容。供 PM 审核后据此创建⑥的实现任务 - -**阶段差异**: - -| 维度 | 原型阶段 | 批量生产阶段 | -|------|----------|-------------| -| 架构 | 可以用占位方案,不需要生产级 | 需要生产级架构,考虑扩展性 | -| 数据流 | 允许硬编码 | 数据应配置化 | -| 美术需求 | 允许简化描述 | 必须具体到尺寸和数量 | - -**产出位置**:`docs/technical/<系统名>-技术方案.md` - ---- - -### PM 审查:程序设计质量门 - -**触发时机**:程序完成技术设计(④)后,进入美术产出(⑤)之前。 - -**审查内容**: - -1. **执行案覆盖度**:程序设计是否完整回应了执行案中的每条行为规则?逐条对照 -2. **美术资源需求**:需求是否列得具体?数量、尺寸、触发时机是否明确? -3. **类与组件架构**:继承关系和挂载方式是否清晰? -4. **数据流**:是否明确? -5. **技术风险**:是否识别? -6. **工作量估算与拆分建议**:是否给出了工作量估算?拆分方式是否合理(每个子任务可独立验证,粒度适合单人单次会话完成)?拆分后的任务是否能完整覆盖实现方案? - -**判定**: -- **通过** → 进入 ⑤ 美术产出 -- **不通过** → 退回程序修改 -- **争议** → PM 与程序对判定有分歧时,由用户最终裁决 - ---- - -### ⑤ 美术产出(美术) - -**目的**:根据程序输出的美术资源需求清单,产出对应资产。 - -**前置条件**:程序设计(④)已就绪,且 PM 审查通过。 - -**阶段差异**: - -| 维度 | 原型阶段 | 批量生产阶段 | -|------|----------|-------------| -| 资产质量 | 允许占位资源、用户自行处理 | 正式资产,符合风格指南 | -| 完成度 | 能用就行 | 必须满足规格要求 | - -**产出位置**: -- 资产放 `Content/` 对应目录 -- 清单记录在 `docs/art/资产清单.md` 或直接在技术方案中更新 - ---- - -### PM 审查:美术资产验收门 - -**触发时机**:美术完成资产产出(⑤)后,进入程序实现(⑥)之前。 - -**审查内容**: - -1. **需求覆盖度**:逐项对照美术资源需求清单 -2. **资产到位确认**:资产文件是否已放置在对应目录? -3. **资产规格**:尺寸、格式等是否符合需求? -4. **缺失项处理**:未到位资产是否有明确处理方案? - -**判定**: -- **通过** → 进入 ⑥ 程序实现 -- **不通过** → 退回美术补充 -- **争议** → PM 与美术对判定有分歧时,由用户最终裁决 - ---- - -### ⑥ 程序实现(程序) - -**目的**:基于程序设计方案和美术资产,实际编写代码。 - -**前置条件**:程序设计(④)已就绪且 PM 审查通过,美术资产(⑤)已就位且 PM 验收通过。 - -**白模搭建子任务(6a)**: -当版本开发涉及场景搭建时,⑥的第一个子任务是白模关卡搭建: -- 读取关卡执行案 `关卡-v-<名称>-执行案.md` 和场景设计案 -- 使用 `Content/BlockingStarterPack/` 资产在 UE5 编辑器中搭建白模关卡 -- 按区域分文件夹组织 Actor(命名规范:`LVL___`) -- 完成比例验证(角色可通过门洞、摄像机不穿墙、流线通行) -- 产出搭建报告 `docs/technical/关卡-v-搭建报告.md` 记录偏差 -- **搭建报告必须以评论形式发布到对应任务 Issue**(与本地文件内容一致) -- 完整搭建流程参见 `docs/design/prototype/关卡设计工作流.md` 第四章 - -**阶段差异**: - -| 维度 | 原型阶段 | 批量生产阶段 | -|------|----------|-------------| -| 代码质量 | 允许硬编码、快速实现 | 不允许硬编码,数据配置化,代码达发布标准 | -| 验证 | 核心流程跑通即可 | 每个系统独立验证 + 集成验证 | - -**实现完成后进入 PM 程序实现验收门,验收通过后进入⑦版本复盘。** - ---- - -### PM 审查:程序实现验收门 - -**触发时机**:程序完成实现(⑥)后,进入版本复盘(⑦)之前。 - -**审查人**:PM - -**审查内容**: - -1. **设计一致性**:实现是否与程序设计方案(④)一致?逐条对照 -2. **执行案覆盖度**:最终实现是否完整覆盖了执行案(③)中的所有行为规则? -3. **资产使用确认**:美术资产是否已正确集成? -4. **完成度评估**:当前版本的实现是否达到了阶段要求的完成度? -5. **偏差梳理**:实现中产生的偏差是否已梳理,偏差等级是否合理? - -**偏差处理规则**: - -| 偏差等级 | 判定标准 | 处理方式 | -|----------|----------|----------| -| **轻微** | 不影响核心行为,仅实现细节差异 | 记录在偏差清单,在⑦版本复盘时同步文档 | -| **重大** | 影响核心行为或与设计方案严重不一致 | PM 建议回退到③重新出执行案或开启新版本修正,由用户决定 | - -**判定**: - -- **通过** → 进入 ⑦ 版本复盘 -- **不通过(轻微)** → 程序补充修正后重新验收 -- **不通过(重大)** → PM 提出处理建议(回退步骤或开新版本),由用户最终决定 -- **争议** → PM 与程序对判定有分歧时,由用户最终裁决 - -**产出**:PM 审查记录(记录在 `docs/plans/reviews/<任务ID>-审查记录.md`) - ---- - -### ⑦ 版本复盘(程序汇报 → PM 协调 → 策划更新) - -**目的**:确保文档与实现一致,为下一个迭代提供准确的起点。 - -**触发时机**:PM 程序实现验收门通过后。 - -**流程**: - -1. **程序汇报**:程序对照执行案,列出实现中产生的偏差和调整 -2. **PM 协调**:PM 汇总程序汇报的偏差清单,协调策划进行文档更新 -3. **策划更新**:策划根据偏差清单,更新设计案和执行案 -4. **标记状态**:执行案迭代记录中该版本标记为 ✅ 已同步 - -**必须更新的内容**: -- 设计案中与实际不符的系统描述 -- 执行案中与实际实现不一致的行为规则 -- 执行案迭代记录中新增一行,记录变更 - -**阶段差异**: - -| 维度 | 原型阶段 | 批量生产阶段 | -|------|----------|-------------| -| 偏差记录 | 核心行为的偏差必须记录 | 所有差异必须记录在案 | -| 文档同步 | 核心系统必须同步 | 所有系统必须同步 | - -#### 为什么必须复盘 - -- 文档是下一个迭代的起点。如果文档和实现不一致,下一个迭代会基于错误假设 -- PM 的质量门审查基于文档。文档不准确会导致审查无效 -- 程序在实现时可能发现设计的问题并做了调整,这些调整必须反映到文档中 - ---- - -## PM 诊断检查清单 - -PM 在每次 `/plan` 调用时,先判断宏观阶段,再针对**当前版本**逐项检查流水线状态。 - -### 宏观阶段判断 - -| 检查项 | 判断方式 | 结果 | -|--------|----------|------| -| 项目处于哪个开发阶段? | 检查 `概念草案.md` → 检查核心玩法是否已有可玩原型 → 检查内容是否已完整 | 草案 / 原型 / 批量生产 / 测试发布 | - -### 版本流水线检查 - -| 检查项 | 检查方式 | 通过条件 | -|--------|----------|----------| -| ① 设计案是否存在且完整? | 检查 `docs/design/<阶段>/` 中的设计文档和索引 | 覆盖所有主要系统,有索引串联 | -| ② 阶段路线图是否存在? | 检查 `docs/plans/<阶段>-路线图.md` | 版本列表、每版本目标、递进关系明确 | -| ③ 执行案是否齐全? | 检查 `docs/design/<阶段>/` 对应执行案 | 每个涉及系统的核心行为规则都已明确 | -| **PM 审查**:执行案质量门 | 对照质量标准逐项检查 | 完整性、清晰性、边界情况通过 | -| ④ 程序设计方案是否齐全? | 检查 `docs/technical/` 对应文档 | 每个执行案都有对应技术方案 | -| **PM 审查**:程序设计质量门 | 执行案与技术方案逐条对照 | 行为规则全覆盖,美术需求具体,工作量与拆分建议明确 | -| ⑤ 美术资产是否就位? | 检查资源需求清单 vs 实际资产 | 所有必需资产已产出或有处理方案 | -| **PM 审查**:美术资产验收门 | 需求清单 vs 实际资产逐项对照 | 每项需求都有对应产出 | -| ⑥ 程序实现是否完成? | 检查实际文件 | 实现完成 | -| **PM 审查**:程序实现验收门 | 实现与设计方案逐条对照 + 偏差分级处理 | 设计一致,偏差已处理或有明确方案 | -| ⑦ 版本复盘是否完成? | 检查执行案迭代记录是否 ✅ 已同步 | 策划已根据实现偏差更新文档 | - -**遇到第一个未通过的即为当前应推进的步骤。** - -**注意**:所有质量门按阶段对应标准严格检查。用户可根据实际情况决定跳过特定检查项,PM 记录用户的跳过决策及理由。 - ---- - -## 文档质量检查标准 - -以下标准对应流水线中的三道 PM 质量门。 - -### 执行案质量标准(对应「执行案质量门」) - -**完整性检查**: - [ ] 是否覆盖了该系统所有玩家可感知的行为? - [ ] 每个操作是否明确了触发条件、触发后表现、结束条件? - [ ] 边界情况是否都处理了? - [ ] 与其他系统的关联是否说明? - -**清晰性检查**: -- [ ] 是否有模糊地带? -- [ ] 行为描述是否无歧义? -- [ ] 程序拿到后能否不问策划任何问题就实现功能? - -**边界检查**: -- [ ] 是否误入了技术细节? -- [ ] 精确参数值是否标注为"建议值,可调"而非固定值? - -**迭代记录检查**: +- [ ] 是否有模糊地带?行为描述是否无歧义? +- [ ] 是否误入了技术细节?参数值是否标注为"建议值,可调"? - [ ] 迭代记录表头是否存在且填写完整? -- [ ] 已完成版本的文档是否已同步(✅ 已同步)? -### 程序设计质量标准(对应「程序设计质量门」) +### 程序设计质量标准 - [ ] 是否完整回应了执行案中的每条行为规则?(逐条对照) - [ ] 美术资源需求是否列得具体(尺寸、数量、触发时机)? @@ -714,29 +260,19 @@ PM 在每次 `/plan` 调用时,先判断宏观阶段,再针对**当前版本 - [ ] 技术风险是否识别? - [ ] 工作量估算是否给出?实现拆分建议是否合理且可操作? -### 美术资产验收标准(对应「美术资产验收门」) +### 美术资产验收标准 - [ ] 资源需求清单中的每一项是否都有对应的美术产出?(逐项对照) - [ ] 资产文件是否已放置在对应目录? -- [ ] 资产路径是否记录清晰? - [ ] 资产规格是否符合需求? - [ ] 未到位资产是否有明确的处理方案? -### 程序实现验收标准(对应「程序实现验收门」) +### 程序实现验收标准 - [ ] 实现是否与程序设计方案一致?(逐条对照) - [ ] 最终实现是否完整覆盖了执行案中的所有行为规则? - [ ] 美术资产是否已正确集成并使用? -- [ ] 当前版本的实现是否达到了阶段要求的完成度? -- [ ] 偏差清单是否已梳理清楚? -- [ ] 重大偏差是否有明确的处理方案(回退步骤或开新版本)? - -### 版本复盘标准(对应「⑦版本复盘」) - -- [ ] 程序是否汇报了实现偏差清单? -- [ ] PM 是否审核了偏差清单并给出协调意见? -- [ ] 策划是否根据协调结果更新了设计案/执行案? -- [ ] 执行案迭代记录是否新增一行并标记 ✅ 已同步? +- [ ] 偏差清单是否已梳理清楚?重大偏差是否有处理方案? --- @@ -746,4 +282,4 @@ PM 在每次 `/plan` 调用时,先判断宏观阶段,再针对**当前版本 - **精力有限**——避免一次性拆分太多并行任务 - **心流重要**——建议按「完整做完一个小系统」而非「同时推进多个系统」的方式工作 - **早期验证**——越早能跑起来看到东西,越不容易失去动力 -- **文档交接**——Agent 之间通过文档交接,PM 是信息枢纽 +- **文档交接**——Agent 之间通过文档交接,PM 是进度调度器,reviewer 负责质量把关 diff --git a/.claude/skills/gitea-collab.md b/.claude/skills/gitea-collab.md index 6c52f4b..a23df2b 100644 --- a/.claude/skills/gitea-collab.md +++ b/.claude/skills/gitea-collab.md @@ -33,6 +33,7 @@ description: "Gitea 协作工具 — CLI 命令速查、认证机制、Assignee | 程序 | `dev` | game-dev | | 美术 | `artist` | (暂无独立 Agent) | | PM | `pm` | game-pm | +| 审查 | `reviewer` | game-reviewer | --- @@ -46,12 +47,13 @@ description: "Gitea 协作工具 — CLI 命令速查、认证机制、Assignee | 程序 | `ai-programmer` | `P-XXX` | | 美术 | `ai-artist` | `A-XXX` | | PM | `ai-pm` | (管理任务) | +| 审查 | `ai-reviewer` | (审查操作,不拥有任务) | --- ## 4. 标签体系 -14 个标准标签,通过 `node scripts/gitea.js label init` 初始化。 +19 个标准标签,通过 `node scripts/gitea.js label init` 初始化。 ### status(任务状态) | 标签 | 含义 | @@ -60,20 +62,31 @@ description: "Gitea 协作工具 — CLI 命令速查、认证机制、Assignee | `status:ready` | 已就绪,可开始 | | `status:in-progress` | 进行中 | | `status:blocked` | 被阻塞 | -| `status:in-review` | 审查中 | +| `status:in-review` | 待审查(角色完成工作后设置) | | `status:done` | 已完成 | -### gate(质量门判定) +### gate(质量门判定 — 旧标签,保留用于历史 Issue) | 标签 | 含义 | |------|------| -| `gate:execution-pass` | 执行案质量门通过 | -| `gate:execution-fail` | 执行案质量门未通过 | -| `gate:tech-pass` | 程序设计质量门通过 | -| `gate:tech-fail` | 程序设计质量门未通过 | -| `gate:art-pass` | 美术资产验收门通过 | -| `gate:art-fail` | 美术资产验收门未通过 | -| `gate:impl-pass` | 程序实现验收门通过 | -| `gate:impl-fail` | 程序实现验收门未通过 | +| `gate:execution-pass/fail` | 执行案质量门 | +| `gate:tech-pass/fail` | 程序设计质量门 | +| `gate:art-pass/fail` | 美术资产验收门 | +| `gate:impl-pass/fail` | 程序实现验收门 | + +> 新工作流使用 `review:*` 标签替代 `gate:*`。旧 Issue 上的 gate 标签保留不动。 + +### review(审查结果 — 新标签) +| 标签 | 含义 | +|------|------| +| `review:pass` | 审查已通过 ✅ | +| `review:fail` | 审查未通过 ❌ | + +### stage(开发阶段 — 新标签) +| 标签 | 含义 | +|------|------| +| `stage:sketch` | 草图阶段任务 | +| `stage:roadmap` | 总路线阶段任务 | +| `stage:iteration` | 迭代阶段任务 | > **注**:`pipeline:*` 和 `role:*` 标签已废弃并从 Gitea 上删除。如旧 Issue 上仍残留这些标签,忽略即可。 @@ -172,14 +185,16 @@ node scripts/gitea.js test | 概念 | Gitea 对应 | 说明 | |------|-----------|------| | 任务 (P-002) | Issue | 标题含任务 ID 前缀 | -| 版本 (v0.1) | Milestone | 版本号即里程碑标题 | +| 阶段/版本 | Milestone | 阶段名或版本号作为里程碑标题 | | 任务状态 | Label (`status:*`) | 6 种状态标签 | -| 质量门结果 | Label (`gate:*`) | 8 种判定标签 | +| 审查结果 | Label (`review:*`) | 通过/未通过 | +| 开发阶段 | Label (`stage:*`) | 草图/总路线/迭代 | +| 质量门结果 | Label (`gate:*`) | 旧标签,保留用于历史 Issue | | 角色归属 | Assignee | 通过 `--assignees` 指派 | -| 流水线步骤 | Pipeline Tracker | Meta Issue 记录全局流水线状态 | +| 当前进度 | Pipeline Tracker | Meta Issue 记录当前阶段和进度 | | 角色汇报 | Issue 评论 | 各角色在对应 Issue 下评论 | | 审查记录 | Issue 评论(摘要+链接)+ 本地 `docs/plans/reviews/` | 本地文件名格式 `<任务ID>-审查记录.md` | -| 任务归档 | close Issue | 不需要本地 archive 文件 | +| 任务归档 | close Issue | 用户确认后由 PM 关闭 | --- @@ -199,11 +214,34 @@ node scripts/gitea.js test ## 8. Pipeline Tracker -Pipeline Tracker 是一个 **Meta Issue**,用于记录当前版本的全局流水线状态。 +Pipeline Tracker 是一个 **Meta Issue**,用于记录项目当前阶段和进度。 -- 初始化:`pipeline init`(阶段开始时执行一次) +### Tracker 正文格式 + +```markdown +# 流水线进度追踪 + +## 当前阶段 +草图阶段 / 总路线阶段 / 迭代阶段 + +## 当前里程碑 +- 名称: +- 状态: open/closed +- Open Issues: X +- Closed Issues: Y + +## 阶段历史 +| 阶段 | 里程碑 | 进入日期 | 完成日期 | +|------|--------|----------|----------| +| 草图阶段 | 草图阶段 | YYYY-MM-DD | — | +``` + +### 相关命令 + +- 初始化:`pipeline init` - 查看状态:`pipeline status` - 更新步骤:`pipeline update --step <1-7> --status "描述"` +- 阶段转换时直接编辑 Issue 正文更新「当前阶段」和「阶段历史」 --- @@ -258,26 +296,10 @@ node scripts/gitea.js --role issue comment --body "## 修改汇 - path/to/output" ``` -### PM 审查后 +### PM 确认关闭任务(审查通过后) ```bash -# 发布审查摘要评论 -node scripts/gitea.js --role pm issue comment --body "## 质量门审查 [通过✅/未通过❌] - -**质量门**:[类型] -**审查日期**:YYYY-MM-DD -**审查记录**:docs/plans/reviews/-审查记录.md - -### 结论 -[一句话总结] - -### 问题清单(不通过时) -1. ..." - -# 更新标签反映质量门结果 -node scripts/gitea.js --role pm issue labels --set ,,... - -# 审查通过时关闭 Issue +# 用户确认后关闭 Issue node scripts/gitea.js --role pm issue close --body "## 任务完成 ✔ **完成日期**:YYYY-MM-DD @@ -292,17 +314,22 @@ node scripts/gitea.js --role pm issue close --body "## 任务完成 ✔ PM 在每次会话启动时按序执行: ```bash -# 1. 读取当前里程碑 -node scripts/gitea.js --role pm milestone list --state open - -# 2. 读取活跃任务 -node scripts/gitea.js --role pm issue list --milestone <当前版本> - -# 3. 读取流水线状态 +# 1. 读取 Pipeline Tracker(确定当前阶段) node scripts/gitea.js --role pm pipeline status -# 4. 读取近期评论(按需) -node scripts/gitea.js --role pm issue comments +# 2. 读取当前里程碑 +node scripts/gitea.js --role pm milestone list --state open + +# 3. 读取活跃任务 +node scripts/gitea.js --role pm issue list --state open + +# 4. 根据阶段调用对应技能: +# 无进度 → project-initializer +# 草图阶段 → stage-sketch +# 总路线阶段 → stage-roadmap +# 迭代阶段 → stage-iteration + +# 5. 检查 review:pass 标签的 Issue → 请示用户是否关闭 ``` --- @@ -312,30 +339,25 @@ node scripts/gitea.js --role pm issue comments ### 创建任务 ```bash -# 创建 Issue(必须指定 assignees) +# 创建 Issue(必须指定 assignees 和 stage 标签) node scripts/gitea.js --role pm issue create \ - --title "D-001 交互系统执行案" \ - --body "## 任务信息\n- **任务ID**: D-001\n- **所属版本**: v0.1\n- **角色**: 策划\n- **预期产出**: docs/design/prototype/交互系统-执行案.md\n..." \ + --title "D-001 概念设计" \ + --body "## 任务信息\n- **任务ID**: D-001\n- **所属阶段**: 草图阶段\n- **角色**: 策划\n- **预期产出**: docs/design/概念草案.md\n..." \ --milestone \ --assignees ai-designer -# 设置标签 -node scripts/gitea.js --role pm issue labels --set , +# 设置标签(status + stage + role) +node scripts/gitea.js --role pm issue labels --set ,, # 设置依赖 node scripts/gitea.js --role pm issue block ``` -### 关闭任务 +### 关闭任务(用户确认后) ```bash -node scripts/gitea.js --role pm issue close --body "## 任务完成 ✔\n**完成日期**: YYYY-MM-DD\n**产出**: path/to/output" -``` - -### 更新流水线 - -```bash -node scripts/gitea.js --role pm pipeline update --step <1-7> --status "状态描述" +# 审查通过 + 用户确认关闭后 +node scripts/gitea.js --role pm issue close --body "## 任务完成 ✔\n**完成日期**: YYYY-MM-DD\n**产出**: path/to/output\n**审查记录**: docs/plans/reviews/-审查记录.md" ``` --- diff --git a/.claude/skills/project-initializer.md b/.claude/skills/project-initializer.md new file mode 100644 index 0000000..cb135ed --- /dev/null +++ b/.claude/skills/project-initializer.md @@ -0,0 +1,137 @@ +--- +name: "project-initializer" +description: "项目初始化技能 — 检查版本管理/项目管理配置、初始化 Gitea 标签/里程碑/任务。仅在项目无进度时由 PM 调用。" +--- + +# 项目初始化 + +> 本技能处理项目冷启动。在 PM 上下文中运行,完成后 PM 直接感知初始化结果。 +> 仅在无 Pipeline Tracker 或无里程碑时触发。 + +--- + +## 初始化流程 + +### 步骤 1:版本管理确认 + +逐项确认以下内容: + +1. **SSH 仓库地址**:确认 `git remote -v` 中的仓库地址正确 +2. **角色 Gitea 账号**:确认以下账号存在且可访问 + - `starmen1265`(用户) + - `ai-pm` + - `ai-designer` + - `ai-programmer` + - `ai-artist` + - `ai-reviewer` +3. **SSH key 配置**:运行 `ssh -T git@micecola.top -p 2223` 测试连接 + - 失败 → 引导用户生成并配置 SSH key + +### 步骤 2:项目管理配置 + +确认以下配置就绪: + +1. **Token 文件**:`scripts/.gitea-tokens.json` 存在且包含所有角色 token + - `pm`、`designer`、`dev`、`artist`、`reviewer` +2. **Token 文件已忽略**:`.gitignore` 中包含 `scripts/.gitea-tokens.json` +3. **Gitea CLI 可用**:`node scripts/gitea.js --role pm test` 运行通过 + +缺失时引导用户配置。 + +### 步骤 3:现有代码与需求检查 + +**情况 A:有现有代码和需求** +- 探索 `docs/` 和 `Content/` 目录结构 +- 读取现有设计文档 +- 生成迁移方案: + - 哪些文档可直接映射到新阶段 + - 哪些需要拆分或重写 + - 哪些可以作为已有产出直接关闭任务 +- 将迁移方案提交用户确认后执行 + +**情况 B:无现有代码(全新项目)** +- 建议用户手动准备开发环境: + 1. 安装 UE 5.7.4 + 2. 创建第三人称/第一人称/顶视角模板项目 + 3. 添加插件:BlockoutStarterPack、LowpolyCharacter + 4. 启用 PythonEditorPlugins 插件 +- 等待用户确认环境就绪 + +### 步骤 4:Gitea 初始化 + +依次执行(所有操作需用户确认后再执行): + +```bash +# 1. 创建标准标签 +node scripts/gitea.js --role pm label init + +# 2. 创建 Pipeline Tracker Issue +node scripts/gitea.js --role pm issue create \ + --title "Pipeline Tracker" \ + --body "# 流水线进度追踪 + +## 当前阶段 +草图阶段 + +## 当前里程碑 +- 名称: 草图阶段 +- 状态: open +- Open Issues: 1 +- Closed Issues: 0 + +## 阶段历史 +| 阶段 | 里程碑 | 进入日期 | 完成日期 | +|------|--------|----------|----------| +| 草图阶段 | 草图阶段 | $(date +%Y-%m-%d) | — |" \ + --labels "stage:sketch,role:pm,status:in-progress" + +# 3. 创建草图阶段里程碑 +node scripts/gitea.js --role pm milestone create \ + --title "草图阶段" \ + --description "概念设计与技术可行性验证" + +# 4. 创建第一个任务:概念设计 +node scripts/gitea.js --role pm issue create \ + --title "D-001 概念设计" \ + --body "## 任务信息 + +- **任务ID**: D-001 +- **所属阶段**: 草图阶段 +- **角色**: 策划 + +## 预期产出 + +产出概念草案 \`docs/design/概念草案.md\`,包含以下 7 个必填字段: +1. 一句话概述(这是什么游戏) +2. 核心玩法(玩家做什么) +3. 美术风格 +4. 目标平台 +5. 灵感来源 +6. 核心假设(为什么好玩) +7. 范围约束(MVP 包含什么) + +## 质量标准 + +- 每个字段有明确的、不含糊的描述 +- 美术风格有参考图或参考作品 +- 核心假设可验证(能通过原型验证)" \ + --milestone "草图阶段" \ + --labels "stage:sketch,role:design,status:ready" \ + --assignees "ai-designer" +``` + +### 步骤 5:确认完成 + +初始化完成后向用户报告: +- ✅ 版本管理配置状态 +- ✅ 项目管理配置状态 +- ✅ Gitea 初始化结果(标签数、Pipeline Tracker Issue 编号、里程碑、首个任务编号) +- 📋 建议下一步:启动策划角色开始概念设计 + +--- + +## 注意事项 + +- 每一步都需要用户确认后才执行,不自动推进 +- 如果中途失败(如 Gitea 连接失败),报告具体错误并建议修复方案 +- 初始化完成后,PM 进入草图阶段,后续由 stage-sketch 技能接管 diff --git a/.claude/skills/quality-gate-review.md b/.claude/skills/quality-gate-review.md index 8d370cc..e5a3ff9 100644 --- a/.claude/skills/quality-gate-review.md +++ b/.claude/skills/quality-gate-review.md @@ -1,19 +1,19 @@ --- name: "quality-gate-review" -description: "质量门审查技能 — 4 道质量门标准、阶段对应标准、审查流程、强制操作清单" +description: "审查标准技能 — 4 道质量门标准、阶段对应标准、审查流程、强制操作清单。供 game-reviewer 子代理使用。" --- -# 质量门审查 +# 审查标准 > 本技能定义 4 道质量门的审查标准、阶段对应标准和审查后强制操作。 -> 供 game-reviewer agent、game-pm agent 及各工种自审使用。 +> 供 **game-reviewer 子代理**使用——角色完成工作后启动 reviewer 子代理,reviewer 按此标准审查。 > 项目管理工具操作细节参见 `.claude/skills/gitea-collab.md`。 --- ## 审查流程 -每次质量门审查必须严格按以下步骤执行: +每次审查必须严格按以下步骤执行: ### 1. 读取交付物 - 从对应 Issue 的评论中获取产出文件路径 @@ -28,17 +28,19 @@ description: "质量门审查技能 — 4 道质量门标准、阶段对应标 - 格式见下方"审查记录格式" ### 4. Issue 评论(强制) -- **无论通过或不通过,都必须在对应 Issue 上发布审查结论评论** +- 使用 `--role reviewer` 操作 +- 评论中标注审查者身份:`审查 Agent (ai-reviewer)` +- 无论通过或不通过,都必须在对应 Issue 上发布审查结论评论 - 通过:摘要 + 通过结论 - 不通过:摘要 + 具体问题清单 ### 5. 更新标签 -- 通过:设置 `gate:*-pass` 标签,移除 `gate:*-fail`(如有) -- 不通过:设置 `gate:*-fail` 标签,移除 `gate:*-pass`(如有) +- 通过:设置 `review:pass` 标签,移除 `status:in-review` +- 不通过:设置 `review:fail` 标签,移除 `status:in-review`,改为 `status:blocked` -### 6. 通过时关闭 Issue(强制) -- **审查通过时必须关闭 Issue**,附完成说明 -- 不通过时 Issue 保持打开,等待修改 +### 6. 返回结果给启动角色 +- 不关闭 Issue(关闭决策权在用户) +- 将审查结果返回给启动你的角色,由该角色向用户汇报 --- @@ -58,8 +60,6 @@ description: "质量门审查技能 — 4 道质量门标准、阶段对应标 > 关卡执行案的质量门**仅做资产存在验证**。空间精度、比例、跨文档一致性等维度的准确性由程序在白模搭建过程中验证——如果程序在 Issue 中汇报了搭建异常,审查者将异常汇总并汇报给用户确认,不自行判断通过或不通过。 -标签:`gate:execution-pass` / `gate:execution-fail` - ### 质量门 2:程序设计质量门(④→⑤) 检查维度: @@ -70,8 +70,6 @@ description: "质量门审查技能 — 4 道质量门标准、阶段对应标 - **技术风险**:是否识别? - **工作量与拆分建议**:是否给出工作量估算?拆分方式是否合理,每个子任务可独立验证?拆分后的任务集合是否完整覆盖实现方案? -标签:`gate:tech-pass` / `gate:tech-fail` - ### 质量门 3:美术资产验收门(⑤→⑥) 检查维度: @@ -80,8 +78,6 @@ description: "质量门审查技能 — 4 道质量门标准、阶段对应标 - **资产规格**:尺寸和格式是否符合需求? - **缺失项处理**:未到位资产是否有明确处理方案? -标签:`gate:art-pass` / `gate:art-fail` - ### 质量门 4:程序实现验收门(⑥→⑦) 检查维度: @@ -89,10 +85,8 @@ description: "质量门审查技能 — 4 道质量门标准、阶段对应标 - **执行案覆盖度**:最终实现是否覆盖所有行为规则? - **资产使用确认**:美术资产是否正确集成? - **偏差处理**: - - **轻微偏差**(不影响核心行为)→ 记录,在⑦复盘时同步文档 - - **重大偏差**(影响核心行为)→ 建议回退到③或开启新版本,用户决定 - -标签:`gate:impl-pass` / `gate:impl-fail` + - **轻微偏差**(不影响核心行为)→ 记录,在复盘时同步文档 + - **重大偏差**(影响核心行为)→ 建议回退或开启新版本,用户决定 --- @@ -109,8 +103,8 @@ description: "质量门审查技能 — 4 道质量门标准、阶段对应标 ## 判定规则 -- **通过** → 发布通过评论 + 设置 pass 标签 + **关闭 Issue** -- **不通过** → 发布不通过评论(附问题清单)+ 设置 fail 标签 + Issue 保持打开 +- **通过** → 发布通过评论 + 设置 `review:pass` 标签 + 返回结果(不关闭 Issue) +- **不通过** → 发布不通过评论(附问题清单)+ 设置 `review:fail` 标签 + 设置 `status:blocked` + 返回结果 - **争议** → 用户最终裁决;审查者提供明确证据和具体文档位置 --- @@ -126,6 +120,7 @@ description: "质量门审查技能 — 4 道质量门标准、阶段对应标 **审查对象**:[任务名] — [产出文档路径] **宏观阶段**:[原型 / 批量生产] **质量门类型**:[执行案 / 程序设计 / 美术资产 / 程序实现] +**审查者**:审查 Agent (ai-reviewer) ## 检查结果 @@ -149,7 +144,8 @@ description: "质量门审查技能 — 4 道质量门标准、阶段对应标 审查完成后,**必须**逐项确认以下操作: - [ ] 在 `docs/plans/reviews/-审查记录.md` 写了审查记录 -- [ ] 在对应 Issue 上发布了审查结论评论(通过/不通过 + 摘要) -- [ ] 更新了 Issue 的 gate:* 标签(通过→pass,不通过→fail) -- [ ] **通过时**:关闭 Issue 并附完成说明 -- [ ] **不通过时**:评论中包含具体问题清单,Issue 保持打开 +- [ ] 使用 `--role reviewer` 在对应 Issue 上发布了审查结论评论(标注审查者身份) +- [ ] 更新了 Issue 的标签(通过→`review:pass`,不通过→`review:fail` + `status:blocked`) +- [ ] 将审查结果返回给了启动你的角色 +- [ ] **不关闭 Issue**(关闭决策权在用户) +- [ ] **不通过时**:评论中包含具体问题清单 diff --git a/.claude/skills/stage-iteration.md b/.claude/skills/stage-iteration.md new file mode 100644 index 0000000..4052459 --- /dev/null +++ b/.claude/skills/stage-iteration.md @@ -0,0 +1,308 @@ +--- +name: "stage-iteration" +description: "迭代阶段技能 — 版本迭代开发管理。插件检查→设计补充→执行案→需求分析→开发→优化→整合→修复。" +--- + +# 迭代阶段 + +> 当 PM 检测到 Pipeline Tracker 标记为「迭代阶段」时调用本技能。 +> 目标:按版本迭代推进开发,每个迭代完成一个可玩版本。 + +--- + +## 阶段概述 + +| 项目 | 说明 | +|------|------| +| 目标 | 将设计转化为可玩的迭代版本 | +| 产出 | 可运行的 UE5 版本 | +| 参与角色 | 策划(执行案)、程序(需求分析+开发) | +| 完成标志 | Bug 修复任务关闭 | + +--- + +## 任务序列 + +每个迭代版本按以下顺序逐步创建任务。**PM 每次激活时只创建下一个可创建的任务**,不要一次全部创建。 + +### 任务列表(按创建顺序) + +| 编号 | 任务名称 | 角色 | 前置依赖 | 首次迭代 | +|------|---------|------|---------|---------| +| 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 | 必选 | + +--- + +### 各任务详细说明 + +#### 1.4.0 插件资产检查与准备(仅首次迭代) + +```bash +--title "P-XXX 插件资产检查与准备" +--body "## 任务信息 +- **任务ID**: P-XXX +- **所属阶段**: 迭代阶段 +- **角色**: 程序 + +## 预期产出 +插件资产引用表 \`docs/technical/插件资产引用表.md\` + +## 检查内容 +1. BlockoutStarterPack — 白模资产完整性检查 + - 路径: Content/BlockingStarterPack/ + - 参考: .claude/refs/blockout-asset-reference.md +2. Lowpoly 角色/场景资源 + - 路径: Content/Lowpoly*/ 或对应插件目录 +3. 人物动作相关插件(动画蓝图、骨骼等) +4. 其他已安装插件 + +## 产出格式 +对每个插件/资产包: +- 插件名称和版本 +- 安装路径 +- 关键资产列表(按类型分类:网格体、材质、动画、音效等) +- 可用性评估(完整/部分可用/缺失) +- 对开发的支持程度说明 + +## 目的 +生成资产引用表,使开发过程可以脱离 3D 美术进行。" +--labels "stage:iteration,role:dev,status:ready" +--assignees "ai-programmer" +``` + +#### 1.4.0.5 设计案迭代补充(可选) + +```bash +--title "D-XXX 设计案迭代补充 — <版本号>" +--body "## 任务信息 +- **任务ID**: D-XXX +- **所属阶段**: 迭代阶段 +- **角色**: 策划 + +## 预期产出 +对现有设计文档的迭代补充,可能包括: +- 新增系统设计细节 +- 调整已有系统参数 +- 补充关卡设计细节 +- 更新 UI/音频设计 + +## 说明 +每个迭代版本可能对总路线阶段的设计有调整。 +策划根据本版本的范围和目标,检查并补充设计文档。 +如果设计文档无需调整,此任务可以跳过(直接关闭并说明'无需补充')。" +--labels "stage:iteration,role:design,status:ready" +--assignees "ai-designer" +``` + +#### 1.4.1 策划执行案 + +```bash +--title "D-XXX 策划执行案 — <版本号>" +--body "## 任务信息 +- **任务ID**: D-XXX +- **所属阶段**: 迭代阶段 +- **角色**: 策划 +- **依赖**: D-XXX 设计案迭代补充完成 + +## 预期产出 +根据设计案为本版本写策划执行案: +- 系统执行案(每份系统一份,如 D-XXXa 交互系统执行案) +- 关卡执行案(如涉及场景搭建) + +## 执行案要求 +- 只写玩家可感知的行为规则 +- 不包含引擎组件、代码架构、数据格式 +- 每条行为规则清晰无歧义 +- 边界情况有明确处理 + +## 参考文档 +- 设计案: docs/design/ +- 执行案模板: .claude/refs/level-execution-template.md(关卡执行案)" +--labels "stage:iteration,role:design,status:backlog" +--assignees "ai-designer" +``` + +#### 1.4.2 程序需求分析 + +```bash +--title "P-XXX 程序需求分析 — <版本号>" +--body "## 任务信息 +- **任务ID**: P-XXX +- **所属阶段**: 迭代阶段 +- **角色**: 程序 +- **依赖**: D-XXX 策划执行案完成 + +## 预期产出 +技术设计文档(使用 /requirements-analysis 技能) + +## 工作方式 +基于策划执行案,使用 8 步需求分析技能产出技术设计文档: +1. 特性点枚举 +2. 功能域图 +3. 类设计图 +4. 时序图(条件性) +5. 核心数据结构 +6. 复杂接口描述(条件性) +7. 技术风险 +8. 工作量估算 + +## 产出路径 +docs/technical/<系统名>-tech.md" +--labels "stage:iteration,role:dev,status:backlog" +--assignees "ai-programmer" +``` + +#### 1.4.3.1 关卡搭建(有场景时) + +```bash +--title "P-XXX 关卡搭建 — <版本号>" +--body "## 任务信息 +- **任务ID**: P-XXX +- **所属阶段**: 迭代阶段 +- **角色**: 程序 +- **依赖**: P-XXX 程序需求分析完成 + +## 预期产出 +白模关卡文件 + 搭建报告 + +## 搭建流程 +参见 .claude/refs/level-execution-template.md 和 game-dev agent 的 Workflow B" +--labels "stage:iteration,role:dev,status:backlog" +--assignees "ai-programmer" +``` + +#### 1.4.3.2 系统开发 + +```bash +--title "P-XXX 系统开发 — <版本号>" +--body "## 任务信息 +- **任务ID**: P-XXX +- **所属阶段**: 迭代阶段 +- **角色**: 程序 +- **依赖**: P-XXX 程序需求分析完成 + +## 预期产出 +根据技术设计文档实现各系统代码 + +## 工作方式 +参见 game-dev agent 的 Workflow C" +--labels "stage:iteration,role:dev,status:backlog" +--assignees "ai-programmer" +``` + +#### 1.4.3.3 优化意见 + +```bash +--title "P-XXX 优化意见 — <版本号>" +--body "## 任务信息 +- **任务ID**: P-XXX +- **所属阶段**: 迭代阶段 +- **角色**: 程序 +- **依赖**: P-XXX 关卡搭建 + P-XXX 系统开发 + +## 预期产出 +优化意见报告,包含: +- 性能分析(帧率、内存) +- 关卡布局优化建议 +- 系统交互优化建议 +- 体验改进建议" +--labels "stage:iteration,role:dev,status:backlog" +--assignees "ai-programmer" +``` + +#### 1.4.3.5 资产接入整合 + +```bash +--title "P-XXX 资产接入整合 — <版本号>" +--body "## 任务信息 +- **任务ID**: P-XXX +- **所属阶段**: 迭代阶段 +- **角色**: 程序 +- **依赖**: P-XXX 优化意见完成 + +## 预期产出 +整合所有资产到最终关卡中,确保: +- 白模资产正确替换(如有正式资产) +- 所有系统正常交互 +- 关卡可完整游玩" +--labels "stage:iteration,role:dev,status:backlog" +--assignees "ai-programmer" +``` + +#### 1.4.4 Bug 修复 + +```bash +--title "P-XXX Bug修复 — <版本号>" +--body "## 任务信息 +- **任务ID**: P-XXX +- **所属阶段**: 迭代阶段 +- **角色**: 程序 +- **依赖**: P-XXX 资产接入整合完成 + +## 工作方式 +1. 完整游玩当前版本 +2. 记录发现的 Bug +3. 按严重程度排序修复 +4. 验证修复后无回归" +--labels "stage:iteration,role:dev,status:backlog" +--assignees "ai-programmer" +``` + +--- + +## 进度检查 + +每次 PM 激活时执行: + +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 修复任务(1.4.4)已关闭。 + +**询问用户**:是否有下一个迭代版本? + +### 情况 A:有下一个迭代 + +```bash +# 1. 关闭当前迭代里程碑 +node scripts/gitea.js --role pm milestone update <当前里程碑ID> --state closed + +# 2. 创建下一个迭代里程碑 +node scripts/gitea.js --role pm milestone create \ + --title "迭代-vX.X" \ + --description "第 N 个迭代版本:<简要描述>" + +# 3. 从 1.4.0.5(设计补充)或 1.4.1(执行案)开始 +# 非首次迭代跳过 1.4.0(插件检查) + +# 4. 更新 Pipeline Tracker +``` + +### 情况 B:无下一个迭代,返回总路线 + +```bash +# 1. 关闭当前迭代里程碑 +# 2. 重新打开或创建总路线阶段里程碑 +# 3. 更新 Pipeline Tracker 为「总路线阶段」 +# 4. 下次 PM 激活时将调用 stage-roadmap 技能 +``` diff --git a/.claude/skills/stage-roadmap.md b/.claude/skills/stage-roadmap.md new file mode 100644 index 0000000..8f81758 --- /dev/null +++ b/.claude/skills/stage-roadmap.md @@ -0,0 +1,183 @@ +--- +name: "stage-roadmap" +description: "总路线阶段技能 — 全面设计文档产出与版本路径规划。管理总路线阶段任务创建和阶段转换。" +--- + +# 总路线阶段 + +> 当 PM 检测到 Pipeline Tracker 标记为「总路线阶段」时调用本技能。 +> 目标:产出完整的游戏设计文档体系,规划版本迭代路径。 + +--- + +## 阶段概述 + +| 项目 | 说明 | +|------|------| +| 目标 | 建立"这个游戏长什么样"的完整蓝图 | +| 产出 | 9 份设计文档 + 版本路径图 | +| 参与角色 | 策划(全部文档) | +| 完成标志 | 所有任务关闭 + 里程碑下无 open issues | + +--- + +## 任务创建 + +### 检查已有任务 + +先通过 `issue list --milestone "总路线阶段" --state open` 检查现有任务,避免重复创建。 + +### 需要创建的任务(共 9 个) + +**占位规则**:除系统设计文档(⑤)和关卡设计文档(⑥)必须完整内容外,其他文档允许暂时留空文件占位(包含标题、章节结构和「待填充」说明),后续迭代中逐步完善。 + +--- + +**任务 1:设计总索引文档** (D-XXX) + +```bash +--title "D-XXX 设计总索引文档" +--body "## 任务信息 +- **任务ID**: D-XXX +- **所属阶段**: 总路线阶段 +- **角色**: 策划 +- **优先级**: 最高(其他设计文档的索引基础) + +## 预期产出 +设计总索引 \`docs/design/设计总索引.md\`,包含: +- 所有设计文档的目录和链接 +- 文档间的依赖关系图 +- 当前完成状态追踪 + +## 占位规则 +此文档必须完整产出(不允许占位)。" +--labels "stage:roadmap,role:design,status:ready" +--assignees "ai-designer" +``` + +**任务 2:世界观设计文档** (D-XXX) — 可占位 + +``` +--title "D-XXX 世界观设计" +--body "...产出 docs/design/世界观设计.md +占位规则:允许占位(标题+章节结构+待填充说明)" +--labels "stage:roadmap,role:design,status:ready" +``` + +**任务 3:剧情设计文档** (D-XXX) — 可占位 + +``` +--title "D-XXX 剧情设计" +--body "...产出 docs/design/剧情设计.md +占位规则:允许占位" +--labels "stage:roadmap,role:design,status:ready" +``` + +**任务 4:角色设计文档** (D-XXX) — 可占位 + +``` +--title "D-XXX 角色设计" +--body "...产出 docs/design/角色设计.md +占位规则:允许占位" +--labels "stage:roadmap,role:design,status:ready" +``` + +**任务 5:系统设计文档** (D-XXX) — ⚠️ 必须完整 + +``` +--title "D-XXX 系统设计" +--body "...产出 docs/design/系统设计.md(含各子系统的设计) +⚠️ 不允许占位,必须产出完整内容。" +--labels "stage:roadmap,role:design,status:ready" +``` + +**任务 6:关卡设计文档** (D-XXX) — ⚠️ 必须完整 + +``` +--title "D-XXX 关卡设计" +--body "...产出 docs/design/关卡设计.md +⚠️ 不允许占位,必须产出完整内容。" +--labels "stage:roadmap,role:design,status:ready" +``` + +**任务 7:UI 设计文档** (D-XXX) — 可占位 + +``` +--title "D-XXX UI设计" +--body "...产出 docs/design/UI设计.md +占位规则:允许占位" +--labels "stage:roadmap,role:design,status:ready" +``` + +**任务 8:音频设计文档** (D-XXX) — 可占位 + +``` +--title "D-XXX 音频设计" +--body "...产出 docs/design/音频设计.md +占位规则:允许占位" +--labels "stage:roadmap,role:design,status:ready" +``` + +**任务 9:版本路径图** (D-XXX) + +``` +--title "D-XXX 版本路径图" +--body "...产出 docs/plans/版本路径图.md +包含:版本列表、每个版本的核心目标、范围概述、内容完成度、 +涉及的系统清单、版本间递进逻辑、验收标准 +依赖:任务 2-8(至少了解各文档的概要信息后才能规划版本路径)" +--labels "stage:roadmap,role:design,status:backlog" +``` + +### 依赖关系 + +``` +任务 1(总索引)→ 先完成 +任务 2-8(各设计文档)→ 1 完成后可并行创建,建议按序执行 +任务 9(版本路径图)→ 依赖 2-8,最后完成 +``` + +设置依赖:`issue block <任务9> <任务2>` ~ `issue block <任务9> <任务8>` + +--- + +## 进度检查 + +每次 PM 激活时执行: + +1. **读取任务状态**:`issue list --milestone "总路线阶段" --state open` +2. **判断当前焦点**: + - 任务 1 未完成 → 建议:先完成设计总索引 + - 任务 2-8 有未完成的 → 建议按序完成各设计文档 + - 任务 2-8 全完成,任务 9 未开始 → 更新任务 9 为 `status:ready` + - 任务 9 进行中 → 等待 +3. **检查完成条件**: + - 总路线阶段里程碑下 open issues = 0 → 触发阶段转换 + +--- + +## 阶段转换 + +**前置条件**:总路线阶段里程碑下无 open issues。 + +**转换操作**(每步需用户确认): + +```bash +# 1. 关闭总路线阶段里程碑 +node scripts/gitea.js --role pm milestone update <总路线里程碑ID> --state closed + +# 2. 创建第一个迭代版本里程碑 +node scripts/gitea.js --role pm milestone create \ + --title "迭代-v0.1" \ + --description "第一个迭代版本" + +# 3. 创建第一个迭代任务:插件资产检查与准备 +# (详细参数见 stage-iteration 技能) + +# 4. 更新 Pipeline Tracker +# 更新正文:当前阶段改为「迭代阶段」 +# 阶段历史表添加总路线阶段完成日期 + +# 5. 告知用户已进入迭代阶段 +# 下次 PM 激活时将调用 stage-iteration 技能 +``` diff --git a/.claude/skills/stage-sketch.md b/.claude/skills/stage-sketch.md new file mode 100644 index 0000000..2b72bd0 --- /dev/null +++ b/.claude/skills/stage-sketch.md @@ -0,0 +1,120 @@ +--- +name: "stage-sketch" +description: "草图阶段技能 — 概念设计与技术可行性验证。管理草图阶段任务创建和阶段转换。" +--- + +# 草图阶段 + +> 当 PM 检测到 Pipeline Tracker 标记为「草图阶段」时调用本技能。 +> 目标:验证游戏概念可行,产出概念草案和技术可行性报告。 + +--- + +## 阶段概述 + +| 项目 | 说明 | +|------|------| +| 目标 | 验证"这个游戏值得做、技术上可行" | +| 产出 | 概念草案 + 技术可行性报告 | +| 参与角色 | 策划(概念设计)、程序(技术评估) | +| 完成标志 | 两个任务都关闭 + 里程碑下无 open issues | + +--- + +## 任务创建 + +### 检查已有任务 + +先通过 `issue list --milestone "草图阶段" --state open` 检查现有任务。 + +### 需要创建的任务(共 2 个) + +**任务 1:概念设计** (D-XXX) + +```bash +node scripts/gitea.js --role pm issue create \ + --title "D-XXX 概念设计" \ + --body "## 任务信息 +- **任务ID**: D-XXX +- **所属阶段**: 草图阶段 +- **角色**: 策划 + +## 预期产出 +概念草案 \`docs/design/概念草案.md\`,包含 7 个必填字段: +1. 一句话概述 +2. 核心玩法 +3. 美术风格 +4. 目标平台 +5. 灵感来源 +6. 核心假设(为什么好玩) +7. 范围约束(MVP 包含什么) + +## 参考文档 +- 游戏愿景:docs/plans/游戏愿景.md(如有)" \ + --milestone "草图阶段" \ + --labels "stage:sketch,role:design,status:ready" \ + --assignees "ai-designer" +``` + +**任务 2:技术可行性报告** (P-XXX) + +```bash +node scripts/gitea.js --role pm issue create \ + --title "P-XXX 技术可行性评估" \ + --body "## 任务信息 +- **任务ID**: P-XXX +- **所属阶段**: 草图阶段 +- **角色**: 程序 +- **依赖**: D-XXX 概念设计完成 + +## 预期产出 +技术可行性报告 \`docs/technical/可行性评估.md\`,评估: +1. 引擎能力匹配度(UE5 能否实现核心玩法) +2. 性能预期(目标平台帧率目标) +3. 关键技术风险(需要验证的技术点) +4. 插件/工具链可行性 +5. 结论:可行/有条件可行/不可行" \ + --milestone "草图阶段" \ + --labels "stage:sketch,role:dev,status:backlog" \ + --assignees "ai-programmer" +``` + +设置依赖关系:`issue block ` + +--- + +## 进度检查 + +每次 PM 激活时执行: + +1. **读取任务状态**:`issue list --milestone "草图阶段" --state open` +2. **判断当前焦点**: + - D-XXX 未完成 → 建议用户启动策划做概念设计 + - D-XXX 完成,P-XXX 未开始 → 更新 P-XXX 标签为 `status:ready`,建议启动程序做技术评估 + - P-XXX 进行中 → 等待 +3. **检查完成条件**: + - 草图阶段里程碑下 open issues = 0 → 触发阶段转换 + +--- + +## 阶段转换 + +**前置条件**:草图阶段里程碑下无 open issues。 + +**转换操作**(每步需用户确认): + +```bash +# 1. 关闭草图阶段里程碑 +node scripts/gitea.js --role pm milestone update <草图里程碑ID> --state closed + +# 2. 创建总路线阶段里程碑 +node scripts/gitea.js --role pm milestone create \ + --title "总路线阶段" \ + --description "全面设计文档产出:世界观、剧情、角色、系统、关卡、UI、音频、版本路径" + +# 3. 更新 Pipeline Tracker +# 更新 Issue 正文:当前阶段改为「总路线阶段」,阶段历史表添加草图阶段完成日期 + +# 4. 告知用户已进入总路线阶段 +# 下次 PM 激活时将调用 stage-roadmap 技能 +``` diff --git a/scripts/gitea.js b/scripts/gitea.js index 928bb90..f718d39 100644 --- a/scripts/gitea.js +++ b/scripts/gitea.js @@ -29,6 +29,13 @@ const STANDARD_LABELS = [ { name: 'gate:art-fail', color: '#d73a49', description: '美术资产验收门 ❌' }, { name: 'gate:impl-pass', color: '#28a745', description: '程序实现验收门 ✅' }, { name: 'gate:impl-fail', color: '#d73a49', description: '程序实现验收门 ❌' }, + // Review (2) + { name: 'review:pass', color: '#28a745', description: '审查已通过 ✅' }, + { name: 'review:fail', color: '#d73a49', description: '审查未通过 ❌' }, + // Stage (3) + { name: 'stage:sketch', color: '#bfd4f2', description: '草图阶段' }, + { name: 'stage:roadmap', color: '#d4c5f9', description: '总路线阶段' }, + { name: 'stage:iteration', color: '#fce6c0', description: '迭代阶段' }, ]; // ═══════════════════════════════════════════════════ @@ -702,7 +709,7 @@ function resolveToken(options) { // 优先级 2:--role 参数 const role = options.role; if (role) { - const validRoles = ['pm', 'designer', 'dev', 'artist']; + const validRoles = ['pm', 'designer', 'dev', 'artist', 'reviewer']; if (!validRoles.includes(role)) { console.error(`❌ 无效角色: ${role},可选: ${validRoles.join(', ')}`); process.exit(1);