# 任务拆分与多 Agent 协同规则

当用户提出一个较大的需求、项目级目标或模糊想法时，AI 必须先判断是否需要拆分，而不是直接进入实现。

## 1. 入口选择

按以下顺序判断使用哪个工作流：

| 场景 | 推荐入口 |
| :--- | :--- |
| 架构不明确、方案有多种可能 | `/arch-design` |
| 需求明确但工作量较大 | `/plan` |
| 跨多个阶段、需要多天推进或多次恢复 | `/mission` |
| 已有多个互不依赖任务 | `/parallel` |
| 单个清晰小任务 | `/start-task` |
| 已完成实现，需要收口 | `/ship` |

如果用户只给出大目标，例如“实现会员系统”“重构设计器”“接入 OpenPencil PRD 能力”，AI 应先输出拆分判断，再选择入口。

## 2. 拆分原则

- 每个任务必须能在一个独立上下文中完成。
- 每个任务必须有明确输入、输出、验收标准。
- 优先按模块边界、接口边界、数据流阶段、风险等级拆分。
- 架构决策、数据模型、公共接口、迁移方案应先于具体 UI 或业务实现。
- 测试、验证、文档发布不能遗漏，应作为显式任务或验收标准。
- 任务粒度应适合一次 `/start-task` 到 `/ship` 闭环；过大的任务继续拆分。

## 3. 并行判断

依赖独立不等于文件系统可安全并行。进入 `/parallel` 后还必须执行隔离预检，并将批次解析为：全只读 `shared`、写入范围明确且互斥的 `locked`、需要独立工作区的 `worktree`，或存在共享写入的 `serial`。

满足以下条件时，任务可以并行：

- 修改不同模块或不同目录，且没有共享写入文件。
- 只读调研、验证、文档整理可以与实现任务并行。
- 上游接口契约已经明确，多个实现方只消费契约，不同时修改契约。
- 每个任务有独立验收标准和可隔离上下文包。

以下情况默认串行：

- 多个任务会修改同一文件、同一配置、同一数据库迁移或同一公共类型。
- 一个任务依赖另一个任务的代码输出、接口签名或数据结构。
- 架构方案尚未确认。
- 需要同一运行环境的独占资源，例如设备、远程机器、数据库迁移窗口。
- 失败会影响多个后续任务的 P0/P1 基础能力。

同一文件或共享契约写入不能通过 worktree 变成可并行任务；必须串行或重新拆分。worktree 只隔离独立写入任务的工作目录和运行状态。

## 4. 子 Agent 分工

| 任务类型 | 推荐 Agent |
| :--- | :--- |
| 需求澄清、方案拆解、依赖图 | `planner` |
| 技术调研、竞品/库评估、未知代码探索 | `researcher` |
| 功能实现、测试编写、修复 | `implementer` |
| 架构/质量/安全审查 | `code-reviewer` |
| 文档、发布说明、开发者指南 | `documenter` |
| 长期任务编排、恢复、里程碑状态 | `coordinator` |

主 Agent 负责总控：确认任务边界、分发上下文、收集结果、处理冲突、统一 `/ship`。

## 5. 拆分输出要求

使用 `.agent/resources/templates/task-breakdown.md` 输出拆分预览。每个任务至少包含：

- 任务 ID
- 优先级
- 目标
- 涉及模块 / 文件范围
- 输入上下文
- 预期产出
- 验收标准
- 依赖关系
- 是否可并行
- 推荐 Agent
- 风险与阻断条件

## 6. 冲突与收口

- 并行前必须列出批次和每批原因。
- 并行后必须检查是否有文件冲突、接口契约漂移、重复实现。
- 多个子 Agent 的输出不能直接视为完成；必须通过 `/ship` 或对应验证流程收口。
- 若任务产生新的项目知识，先 `/update-refs`；若影响开发者文档，再 `/publish-docs`。