games-development-ai/.agents/workflows/ai-development-protocol.md

AI 驱动开发元流程

本文是造梦AI 项目承接任意任务的统一打法：从识别 → 分析 → 评审 → 执行 → 验证 → 沉淀的完整协议。所有 Agent / 工程师在本仓库做事都遵循它。 配套硬规则：../rules/engineering-conventions.md、../rules/security-and-reliability.md；事实蓝图：../knowledge/product-and-architecture.md；操作手册：../skills/；目录索引：../README.md。

---

1. 总流程

flowchart TD
  A[识别任务类型与复杂度] --> B[读 .agents/knowledge 与 docs、docs/memorys]
  B --> C{复杂 / 高风险?}
  C -- 否 --> S[简单路径: 目标→最小改动→验证→报告]
  C -- 是 --> D[Restate 理解: 目标/范围/事实/假设/影响面/风险/验证计划]
  D --> E[评审版 spec: docs/agent-specs/YYYY-MM-DD-topic-review.md]
  E --> F[两轮评审]
  F --> G[执行版 spec: docs/agent-specs/YYYY-MM-DD-topic-execution.md]
  G --> H{需要并行?}
  H -- 是 --> I[子代理拆分: 互不重叠职责 + 共享事实包]
  H -- 否 --> J[实施: 最小改动/复用既有/契约先行/中文注释]
  I --> J
  J --> K[验证: 单测/集成/类型/构建/冒烟]
  S --> K
  K --> L[沉淀回 .agents: 更新 knowledge/rules/skills + 同步 README]

编号步骤：

1. 识别任务类型与复杂度——先判断这是分析/评审/编码/调试/写作中的哪一类，是否复杂、高风险、跨模块、用户可见。
2. 取经验——先读 ../knowledge/ 与 docs/（架构原档）；若存在 docs/memorys/，先检索同类历史任务，避免重复劳动。
3. 复杂/高风险任务先 Restate——复述理解，声明：目标、范围边界、已验证事实、假设、影响面（blast radius）、风险、验证计划。
4. 评审版 spec——产出 docs/agent-specs/YYYY-MM-DD-topic-review.md：结论先行，只留背景/目标/非目标/推荐方案/关键权衡/影响面/风险兼容/验收标准/待确认项，多用 Mermaid，降低认知负荷，不写代码级细节。
5. 两轮评审——评审版经两轮评审确认后再进入执行。
6. 执行版 spec——产出 docs/agent-specs/YYYY-MM-DD-topic-execution.md：目标与范围边界、前置条件、涉及模块与文件路径、数据流与依赖、接口/数据契约、关键实现步骤、边界失败路径、验证方法、完成条件、回滚策略。不预写不可验证的代码细节。
7. （可选）子代理拆分执行——见 §4。
8. 实施——最小必要改动、复用既有模式、契约先行、全中文注释、可追溯日志。
9. 验证——见 §5；无证据不得声称完成。
10. 沉淀——见 §6，把有价值的产出回写 .agents 并同步索引。

简单、低风险、局部、易验证的任务走简单路径：目标 → 最小改动 → 验证 → 报告，不必走全套 spec 流程。

---

2. 任务类型分支

类型	打法	产出形态
分析	第一性原理 + 金字塔原理拆解；给出问题、边界、假设、风险、推荐路径	结论先行的分析结论
评审	按严重度排序，每条给：影响 / 根因 / 修复建议	问题清单（先严重后次要）
编码	最小改动 + 复用既有模式 + 中文注释 + 验证；禁止顺手重构无关代码	可编译可验证的变更
调试	症状 → 复现 → 观察 → 缩小范围 → 根因 → 针对性修复 → 验证 → 清理临时调试代码	根因 + 修复 + 验证证据
写作	可评审、可直接落地的内容，多用表格与清单	即可入库的文档

2.1 简单路径 vs 全流程的分流判据

命中任一下列信号即走全流程（Restate → 评审版 spec → 两轮评审 → 执行版 spec）；全部不命中才走简单路径：

信号	判据
跨模块	改动牵动 ≥ 2 个 game-module，或触达 -api 契约 / 事件 schema
用户可见	改变产品端/管理端行为、API 出入参、SDK 对外签名
高风险面	涉及鉴权、支付、合规门禁、沙箱、幂等、分布式一致性（见 ../rules/security-and-reliability.md）
数据结构	新增/变更 DO/表结构、Flyway 迁移、Redis/MQ 数据格式
不可逆	删除字段/接口、数据迁移、线上配置变更

简单路径仅适用：单文件局部改、纯文案/注释、补一个不改契约的单测、明确无副作用的 bugfix。拿不准时按全流程走。

2.2 本项目典型任务的落法（示例）

任务	类型	路径	关键动作
新增一个 game-module	编码	全流程	执行版 spec + 契约先行；落地照 ../skills/add-business-module.md
给 aigc 加一个生成失败错误码	编码	简单	在 -api 错误码段登记 + 单测，不动契约
排查"生成任务一直 QUEUED"	调试	简单→视根因	先查 Dify/MQ Consumer 日志复现，再定位
评估是否引入 ClickHouse	分析	全流程	第一性原理 + 评审版 spec，结论先行
审查一个支付回调 PR	评审	——	按严重度列问题；重点幂等/状态机/乐观锁

---

3. 证据规则

区分三种信息，不得混为一谈：

• 已验证事实——来自代码、文档、日志、测试、运行输出。
• 推断——基于上下文的合理判断，未直接验证，须标注"（推断）"。
• 假设——为推进临时采用，须后续确认。

铁律：

• 凡可只读核实的，先查代码/文档/配置/测试/日志，关键歧义仍在再问用户（只问影响决策的最小必要问题）。
• 没有验证证据，绝不声称"完成 / 修复 / 通过 / 无问题"。

---

4. 子代理使用规范

规则	说明
边界不重叠	拆分为互不重叠的文件 / 职责边界，避免写冲突（一个文件只由一个子代理负责）
共享事实包	为每个子代理提供同一份"事实包"（如 ../knowledge/ + 契约文件），保证多代理产出一致
并行前提	并行仅用于无共享状态、无顺序依赖的任务；有依赖的按序执行
模型档位	关键任务统一用 Opus Max，以最高标准最深推理完成

契约先行 + 各工位 mock 对方接口独立开发，是本项目并行解耦的基础，见 ../skills/contract-first-development.md。

---

5. 验证

收尾前跑最相关的验证，并在报告中给出证据：

• 改动行为的单元测试；涉及 DB/MQ 的集成测试（Testcontainers）。
• 类型检查 / lint / 构建（后端 mvn test/mvn verify，前端 pnpm test，SDK pnpm test:size 体积检查）。
• 必要的冒烟测试（核心链路）。
• 跑不了的，说明原因并给出下一步验证建议。

测试分层与覆盖率要求见 ../rules/engineering-conventions.md §7。

---

6. 与 .agents 的闭环沉淀

每次有价值的交付后，按"维护即收尾"原则回写：

1. 判断新增 vs 更新：全新主题 → 新增文件；已有主题补充/修正 → 更新现有文件（先查重，不造重复）。
2. 回写对应层：事实 → knowledge/；硬约束 → rules/；操作手册 → skills/；流程 → workflows/。
3. 同步索引：任何结构性变更（增/删/改名）同步更新 ../README.md 的文件清单与交叉链接（统一相对路径）。
4. 过时即处理：信息失效立即修正或删除；与代码/文档冲突时以已验证事实为准。
5. 询问是否落 memorys：关键任务信息按需持久化到 docs/memorys/YYYY-MM-DD-任务描述.md（描述 10–20 字），供同类任务复用。

---

7. 停止规则

• 能回答核心问题即止，不为润色措辞、堆砌细节、展示分析过程而扩张范围。
• 最小方案优先：够用就不引入更复杂设计；不为一次性代码建长期抽象。
• 关键证据缺失时，点明缺口；只有当它真会影响决策时，才问最小必要的问题。