# 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/agent-specs/` 的收口报告与总账 §6 执行记录（留痕层 `docs/plans/`(旧 memorys 已删,git 可查) 为早期遗留、已停增）。
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" | 调试 | 简单→视根因 | 先查 RocketMQ 异步 gen 队列消费者 / cheap-worker（AgentScope）Service 日志复现，再定位 |
| 评估是否引入 ClickHouse | 分析 | 全流程 | 第一性原理 + 评审版 spec，结论先行 |
| 审查一个支付回调 PR | 评审 | —— | 按严重度列问题；重点幂等/状态机/乐观锁 |

### 2.3 agentic 设计/评审任务的强制过尺（2026-07-05，创始人拍定）

凡设计或评审生成运行时的 **agent 席位划分、context 装配、prompt 结构、工具面、多 agent 协作、goal-loop 自治交付、创作者交互面**，必须按 [`../skills/agentic-seat-context-design.md`](../skills/agentic-seat-context-design.md) §8 检查单过尺：设席八问 / 注入五查 / 场景四要素 / "规范进 prompt"先问模板与门。评审此类设计档时，把该检查单当评审尺逐条对；设计档内〔提案〕机制落地前须逐条验证可行性（该 skill 是需求基线，不是架构 SoT）。**全新 agentic 子系统首次设计前，若尚无需求基线，先按该 skill §10 探针方法跑一轮第一人称需求探针产基线再设计**（2026-07-06 立 W-PROBE；默认建议、升强制与否待创始人拍；探针对象排期唯一登记处 = 作战清单 W-PROBE 单）。

---

## 3. 证据规则

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

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

铁律：

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

---

## 4. 子代理使用规范

| 规则 | 说明 |
|---|---|
| 边界不重叠 | 拆分为**互不重叠的文件 / 职责边界**，避免写冲突（一个文件只由一个子代理负责） |
| 共享事实包 | 为每个子代理提供同一份"事实包"（如 [`../knowledge/`](../knowledge/) + 契约文件），保证多代理产出一致 |
| 并行前提 | 并行**仅用于无共享状态、无顺序依赖**的任务；有依赖的按序执行 |
| 模型档位 | **按裁量点三档分流（硬性成本规则，2026-06-11）**：零裁量机械类→**Haiku**（固定配方执行/轮询盘点/证据搬运，结果可便宜验证）；有裁量的开发/设计/评审/调试→**Opus**（子代理默认档）；仅最高复杂度→**Fable**（架构裁决/主 spec 终裁/跨模块疑难根因；其新 tokenizer 同内容多 ~30% token，实际成本 ≈ Opus 2.6 倍）。**派发子代理/Workflow `agent()` 必须显式传 `model`，禁止静默继承主会话档位**（主会话为 Fable，继承=全员烧最贵档）；拿不准或涉契约/不可逆操作升一档，由验证门兜底低档错误；Sonnet 为中间档（Haiku 质量不够且 Opus 过杀时用） |

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

### 4.1 Fable 档适用清单（本项目具体映射，2026-06-11）

> 上表「模型档位」行是通用判据；本节把"哪些建设对象必须升 Fable"落到本项目具体功能/实现（Doc B T-id 可溯）。**注意区分**：本节只管**开发期**模型分流；产品侧（生产调用链）档位红线另见 [`../knowledge/tech-decisions.md`](../knowledge/tech-decisions.md) §4「生成模型档位」——生产主链路禁旗舰档，两者勿混。

**① 架构单行门——设计终裁必须 Fable（实现仍 Opus）**。共同特征 = 裁量大 × 错了不可逆 × 跨模块：

| 对象 | 涉及（Doc B） | 不可逆点 |
|---|---|---|
| 资金域整体 | trade T-TRD-01..12 + pay 接线 + 广告计费反作弊正式项（Doc B §11 📌注记） | 钱 + 对抗域，分账/对账/打款错了直接资损 |
| 多渠道统一转译引擎 | T-RT-26 + 渠道矩阵 T-RT-21..24/31/32 | 渠道格式 = 外部硬契约，引擎定错全渠道返工 |
| agentic 编排引擎 | T-STU-05/10 + T-AGC-18 DAG | ~~全项目最重自研框架~~ **已终裁不自研（HJ-AGI-001→HJ-AGI-002→**2026-06-25 框架收敛覆盖**：生成框架统一收敛 AgentScope、三档按 AI 参与深度分（引擎随复杂度选 LittleJS / Phaser）；SAA / dify / coze 降为最低优先级，留作远期可插拔适配验证；Fable 只设计五资产契约边界与适配层；T-AGC-18 自研 DAG 引擎作废）** |
| 商用授权链域模型 | T-IP-02/03 + T-CMP-12 锁风门聚合语义 | 资产积累后数据模型无法重构，且与法务耦合 |
| 推荐 + A/B 实验框架 | T-FED-12/13（增长期） | 离线/在线一致性、数据闭环正确性 = 护城河承重墙 |
| 一次性架构事件 | monorepo→三仓拆分、MySQL→ClickHouse 迁移、沙箱安全边界对抗评审（T-RT-04/05/14 + T-CMP-26） | 全仓级影响 / 安全边界 |

**② master-spec 终审票**：两轮评审中的**最后一票**在高危波次用 Fable——M4 变现波、转译引擎波、推荐波、biz 真实化波（电子签章/CRM/报价等外部契约对接）。反例：黄金模板克隆波（如 Wave4 community/biz 骨架）Opus 评审即可。

**③ 跨模块疑难根因（按需升档，不预算）**：症状横跨 ≥3 层（前端/桥/后端/构建链）或 Opus 两轮取证无果才升（先例 = 回包链路 v-for ref 全断案）；例外直升：并发/幂等/MQ 重复消费类数据一致性 bug（错果不可逆）。

**④ 生产数据→Fable 离线分析→系统升级（常设用法，最高杠杆）**：Fable 不进生产调用链，按"波次收口/批次/决策点"节奏喂生产数据做横切归因，产出必须蒸馏回 `.agents`/contracts/prompts（闭合 §6 复利沉淀）：

- 生成失败横切归因（batch 产物 + T-TEL-17 失败聚合）→ prompt registry / 模板 schema / 校验规则升级——成功率 80%→90% 爬坡主引擎（agent-loop QA 闭环/C6.1 对抗评审的正式化）；
- 质量分/推荐审计（T-TEL-20 解读层）→ 排序权重 w1..w6 的劣化与可刷性分析 → 调参建议；
- 单位经济复盘（new-api 成本账 + eCPM/分成实测）→ 迭代 `docs/mvp/单位经济敏感性模型.md` 与定价/档位决策；
- 反作弊态势（AnomalyFilter 拦截日志）→ 对抗者视角找绕过路径 → 规则升级；
- 模型评估矩阵争议样本终裁（judge 通道）。

前提红线：喂数前先**聚合 + 脱敏**（守 T-CMP-30 日志脱敏、T-CMP-33 最小化采集）。

**升档触发判据（命中任一即升 Fable）**：① 决策锁死 ≥3 模块或外部硬契约/资金/法务；② 错误不可逆（资损/数据模型固化/安全边界）；③ Opus 两轮取证无果的机制级疑难；④ 高危波次 master-spec/对抗评审终审票；⑤ 生产数据横切归因分析。

**明确不升档**：模板克隆、CRUD/admin 页面、渠道 adapter 批量复制（引擎定稿后）、批量验证、UI 走查执行——Opus/Haiku 照常，显式传 `model` 红线不变。

### 4.2 执行子代理的产出验证纪律（SDD 实录，2026-07-02）

派子代理执行编码任务、尤其走 subagent-driven-development 时，子代理回报的 DONE 是**未验证声称**，controller 不得据以标记完成。一次实录：子代理报「测试 8/8、已提交 commit 6837c8ee」，实际测试是 2 failed，那个 commit 在 git 里根本不存在——改动只落在工作树、从未提交。

五条硬纪律：

- **每个报 DONE 的 commit 自验**：`git rev-parse HEAD` 与回报的 hash 对得上，真跑关键测试（不信回报的通过数），红线级改动亲读 diff。
- **生成 review 包时的 hash 校验是造假第一道自动拦网**：编造的 commit hash 不在 git 里，一 `git` 就报错。把「生成 review 包 / diff」放在标 complete 之前当强制步，能第一时间撞破。
- **造假子代理弃用、不 resume**：它带着「我已做完」的错误认知，resume 容易再造假；换 fresh 子代理，只补 controller 诊断出的精确缺口，prompt 里明写诚实红线（回传真实 HEAD 与原样测试输出，没全绿一律报 BLOCKED 而非 DONE）。
- **fix 子代理让其自证**：要求「删掉修复→缺陷用例必红」这类反向验证，证明测试真在测行为而非桩自证，controller 再复核一遍。
- **关键 hash 一律主代理独立重算，绝不抄子代理报的值**：不止 commit hash——`runtime-tree.json` 的 sha256、`artifacts.sha256`、baseline 的 `promptBodySha256` 这类产物/基线 hash，子代理报的长度或值也可能是错的（一实录：子代理报 runtime-tree hash 为 62 位却称 64 位）。主代理对这些 hash 必须自己 `sha256sum` / `git rev-parse` 重算比对，不直接采信报值；`git rev-parse` 验 commit hash 存在是反造假第一道（第一条），产物 hash 同理——报得出 ≠ 算得对。

---

## 5. 验证

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

- 改动行为的**单元测试**；涉及 DB/MQ 的**集成测试**（Testcontainers）。
- **类型检查 / lint / 构建**（后端 `mvn test`/`mvn verify`；前端一律 **`npm run build`**——`vue-tsc --noEmit` 为假门禁不得作验证依据，mini-desktop 构建 game-studio 必须 `--mode staging`，详见 [`../skills/staging-ops.md`](../skills/staging-ops.md) §4；SDK `pnpm test:size` 体积检查）。
- 必要的**冒烟测试**（核心链路）。
- 跑不了的，**说明原因并给出下一步验证建议**。

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

---

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

> **波次收口走唯一清单**：[`../skills/wave-close-checklist.md`](../skills/wave-close-checklist.md)（总账+表头 / 作战清单+归档 / 回填 / `.agent` / 蒸馏 / 索引 / 编排资产入库，七步）。本节是其中"蒸馏"一步的细则。

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

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

---

## 7. 停止规则

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