# 多 subagent 产品迭代 loop 系统设计(v2) > 本文是顶层设计,回答"为什么这样设计";执行细节以实现文件为准(见文末「实现映射」)。v1 草稿见 git 历史。 ## 设计目标 1. **可靠**:每个步骤准确、不遗漏、可回溯; 2. **收敛**:循环有轮次预算、有终止条件、有升级路径,不会无限返工; 3. **进化**:用户质疑驱动角色升级,沉淀可迁移的方法论,而不是堆积场景补丁。 ## 执行模型(先讲清约束,再谈分工) 设计里的一切规则都由这四条约束推导,不套用人类团队隐喻: 1. **subagent 之间不能对话**:一切"协作/协助"必须建模为文档交接 + 主 agent 路由; 2. **subagent 无跨需求记忆**:经验只能沉淀进角色定义文件(即角色的 prompt),且要有执行钩子才会被用上; 3. **用户不一定在线**:默认全自动推进,用户停点是可选开关(默认不阻塞); 4. **文档即接口**:谁写、什么格式、下游读什么,必须事先固定;口头(聊天摘要)不算数。 ## 角色管道(顺序即依赖) 主 agent 是**编排者与项目经理**:立项、按序调度、执行门禁、路由返工、每阶段 git commit、汇总交付,不做各角色的专业工作、不代写角色文档。 | 阶段 | 执行者 | 产出 | 门禁 | | --- | --- | --- | --- | | 0 立项 | 主 agent | `00-request.md`(用户原话逐字)、`state.md` | - | | 1 需求分析 | pd-requirements-analyst | `10-analysis.md`(诉求# + 每条配验收口径) | - | | 2 产品设计 | pd-product-designer | `20-product.md`(功能#→诉求# 追溯矩阵) | 可退回 1 | | 3 UI/UX 原型 | pd-uiux-designer | `30-uiux.md` + `prototype/`(页面→功能#) | 可退回 2 | | 4 体验审查(门禁) | pd-experience-reviewer | `40-review.md` | 通过 / 返工→3(或 2) | | 5 后端 | pd-backend-developer | `50-backend.md`(接口契约)+ 代码 | 纯前端跳过 | | 6 前端 | pd-frontend-developer | `55-frontend.md` + 代码 | - | | 7 测试(门禁) | pd-qa-tester | `60-test.md` | 通过 / 返工→5/6 | | 8 验收(门禁) | pd-acceptance-reviewer | `70-acceptance.md` | 通过 / 不通过→定位阶段 | **后端先于前端(契约先行)**:前端的输入是接口契约,契约不存在就无从"对接";后端设计接口时以原型数据流清单为依据,联调问题写进文档由主 agent 路由,不存在"两个角色实时协作"。 ## 可靠性设计(对应"准确、不遗漏") 1. **锚点防传话走样**:用户原话逐字存入 `00-request.md`,主 agent 调度时不替角色转述需求;每个角色先读原话独立理解,再核对上游文档——分歧只用于发现问题,不授权私自改道。 2. **双向核对(每个角色必做)**:上游每条要求在本步有落点(防漏);本步每项产出可追溯到上游编号(防跑偏)。只做单向核对是 v1 的关键缺陷:只防了加戏,没防遗漏。 3. **追溯编号链**:诉求# → 功能# → 页面/原型落点 → 接口 → 测试用例 → 验收核对。门禁角色第一件事是机械核对断链,断链本身就是缺陷。 4. **机读结论**:每份文档头部「结论」行使用固定词表(通过 / 返工:退回X / 阻塞);门禁只认文档,不认 subagent 的聊天摘要。 5. **状态机与回溯**:`state.md` 只有主 agent 可写,记录阶段/轮次/结论;每阶段结束 git commit(消息 `pipeline(): 阶段N 第M轮 <角色> <结论>`)——多数文档覆盖写入,任何一轮的产出靠 commit 历史回溯。 6. **文档所有权**:一份文档只有一个作者角色,主 agent 对角色文档只读。 7. **复杂需求接 openspec**:涉及 ≥3 个页面/模块、前后端都动、或预计任务 ≥10 条时,阶段 4 通过后走 openspec change 管理任务清单,逐项勾选防漏。 ## 收敛性设计(loop 控制) 1. **轮次预算**:体验/测试门禁同一门禁最多 3 轮、验收 2 轮;超限停下,把遗留问题清单交用户裁决——自动化在预算耗尽时让位于人,绝不无限循环。v1 的"直到符合专业的产品需求为止"没有预算、裁判又是提出问题的同一角色,永不收敛。 2. **上游冲突统一裁决**:下游发现上游缺口——不改变上游结论、功能范围、数据契约的小缺口:自行补齐并在「上游核对」注明;大缺口:走返工路由重跑上游,禁止私自改道。 3. **阻塞不计轮次**:环境问题(服务没起、依赖缺失)由主 agent 修复后重调同一角色。 4. **用户停点**:原型通过体验审查后默认不阻塞(把原型路径通知用户即继续);用户事先声明"要等我确认"才停。 ## 进化设计(对应"总结方法论,不是补充场景") 质疑处理链:**逐字记台账(打模式标签)→ 归因(角色或编排层)→ 自省(git 历史为证据)→ 教训(硬标准)→ 入档观察 → 晋升进工作流程**。 1. **模式标签 = 复发检测的开关**:台账每条质疑打"问题模式"标签(受控词表,如 `画像-符号不匹配`、`契约-实现脱节`);新质疑命中旧标签即复发——复发既触发教训晋升,也要追责"上次的教训为什么没拦住"(教训本身的失效同样要归因:是写得太场景化,还是角色没执行)。 2. **教训方法论化硬标准**:每条教训必须写成「触发条件 + 检查动作 + 判定依据」,触发条件必须泛化到"类",场景词只能进括号举例。"下次注意音标"是场景补丁;"产出任何面向用户的符号系统(文字/图标/音标/缩写)→ 逐类核对画像的符号识别能力 → 每类有画像依据才算过"才是方法论。主 agent 按此标准把关,不合格打回重写。 3. **教训生命周期(入档→晋升)**:教训先进角色定义末尾「历史教训」段(观察期);同模式复发或被验证有效后,由主 agent **晋升**——改写成该角色「开工流程/怎么做」里的具体步骤,并从教训段删除。堆积不是进化,融进方法才是;教训段超过 10 条说明晋升不够勤。 4. **执行钩子**:每个角色开工第一步强制"读历史教训 → 相关条目列入自查清单 → 产出文档头部声明应用了哪几条"。教训必须在流程里跑,不能贴在墙上;声明行同时是复发追责的证据。 5. **编排层也要进化**:质疑指向流程本身(阶段顺序、门禁标准、调度转述走样、该问没问)时,主责是主 agent,教训写入 product-pipeline SKILL 的「历史教训」段——流程级错误不能没有归因去处。 ## 实现映射 | 设计点 | 落地文件 | | --- | --- | | 编排手册(阶段/门禁/commit/裁决/调度模板) | `.agents/skills/product-pipeline/SKILL.md` | | 质疑与进化(台账/教训标准/晋升/复发) | `.agents/skills/pipeline-feedback/SKILL.md` | | 8 个角色定义(含「历史教训」段与开工钩子) | `.cursor/agents/pd-*.md` | | 质疑台账与模式标签词表 | `tasks/pipeline/challenges.md` | | 每需求工作区(00→70 文档 + state.md) | `tasks/pipeline//` | | 孩子端专项门禁(AGENTS.md 既有约定) | `.cursor/agents/child-ux-tester.md` | ## 修订记录 - **v2(2026-09-02)**:修正前后端依赖顺序(契约先行,后端阶段 5 → 前端阶段 6);补循环收敛机制(轮次预算、统一冲突裁决、阻塞不计轮次、用户停点开关);补可靠性构件(原话锚点、双向核对、追溯编号链、机读结论、每阶段 git commit 回溯);进化机制方法论化(模式标签复发检测、教训三段式硬标准、入档→晋升生命周期、开工执行钩子、编排层归因通道);消除"必要时/理论上"等不可判定措辞;修正 v1 错别字("复刻金额"等)。 - **v1**:初稿(角色分工表 + 5 条要求),见 git 历史。