# AI 驱动开发元流程

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

---

## 1. 总流程

```mermaid
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/`](../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`](../rules/security-and-reliability.md)） |
| 数据结构 | 新增/变更 DO/表结构、Flyway 迁移、Redis/MQ 数据格式 |
| 不可逆 | 删除字段/接口、数据迁移、线上配置变更 |

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

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

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

---

## 3. 证据规则

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

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

铁律：

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

---

## 4. 子代理使用规范

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

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

---

## 5. 验证

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

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

> 测试分层与覆盖率要求见 [`../rules/engineering-conventions.md`](../rules/engineering-conventions.md) §7。

---

## 6. 与 .agents 的闭环沉淀

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

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

---

## 7. 停止规则

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