Multi Agent Collaboration

SKILL.md

---
name: multi-agent-collaboration
description: 当用户想用多个 AI/Agent 协作完成产品开发、内容生产、代码修改、MVP 迭代或复杂任务交付时使用本技能。适用于搭建“人在回路”的 Multi-agent Collaboration 工作流：用户/Owner 负责方向和验收，一个 AI 负责需求澄清、方案拆解、任务编排与审查，另一个或多个执行 Agent 负责按原子任务执行。尤其适用于非工程师、产品经理、独立开发者、小团队和创作者，希望把模糊想法拆成可执行任务、控制 Agent 改动范围、降低返工、沉淀技术债/决策记录、形成可复用协作包的场景。不要用于完全无人监督的自动执行；不要让执行 Agent 承担开放式产品判断。
---

# Multi-agent Collaboration：人在回路的 AI 协作开发方法

本技能用于把一个模糊需求转成可控、可验收、可沉淀的多 Agent 协作流程。

核心原则：**人决定方向，编排型 AI 拆任务和控范围，执行 Agent 只做明确小任务，最后由人验收。**

## 角色分工

| 角色 | 职责 | 不负责 |
|---|---|---|
| Owner / 用户 | 定方向、给约束、确认方案、做真实验收、决定是否收口 | 不需要亲自写完整代码或读完整大 diff |
| 编排型 AI | 澄清需求、拆方案、评估工作量、写原子任务、审查执行结果、维护沉淀 | 不在用户未确认时直接推动大改 |
| 执行 Agent | 按任务单改代码/产出内容/跑检查/返回摘要 | 不做开放式探索、不顺手重构、不扩大范围 |

如果只有一个 AI，也要在流程上拆分“编排阶段”和“执行阶段”，避免同一个上下文里边想边改导致范围失控。

## 标准工作流

```text
1. 用户提出需求 / bug / 想法
2. 编排型 AI 判断任务类型
3. 编排型 AI 做澄清、诊断或方案对比
4. 用户确认方案或最小目标
5. 编排型 AI 写原子任务
6. 执行 Agent 按任务单执行
7. 执行 Agent 返回修改列表、摘要、自测结果和风险
8. 编排型 AI 做 review
9. 用户做真实环境验收
10. 通过则收口；不通过则补小任务；必要时登记技术债/决策
```

不要跳过第 4、8、9 步。它们是人在回路的安全边界。

## 先判断任务类型

| 类型 | 编排方式 | 产出 |
|---|---|---|
| 新需求 / 想法 | 拆模块，列 2～3 个方案，评估 XS/S/M/L、风险、扩展性 | 推荐方案 + 待确认 |
| Bug / 异常 | 先无代码诊断，列可能原因和低成本验证步骤 | 根因判断 + 小补丁任务 |
| 执行结果 / diff | 做 code review，标必改/建议/可选/通过 | 审查表 + 后续任务 |
| 技术债 | 判断是否影响当前目标；能不顺手做就先记录 | 技术债条目或独立任务 |
| 数据/配置维护 | 精确到 ID、字段、文件、校验命令 | 小范围修改任务 |
| 文档/方法论沉淀 | 抽象为通用模板，去掉项目私有细节 | 协作文档/模板/Skill |

## 工作量分级

| 规模 | 判断标准 | 推荐处理 |
|---|---|---|
| XS | 1～10 行或单点文案/逻辑修复 | 可直接给原子任务 |
| S | 10～50 行，局部逻辑或小功能 | 明确验收路径后执行 |
| M | 50～150 行，跨文件或交互链路 | 先给方案，再拆成多个任务 |
| L | 150 行以上、跨模块或架构变更 | 必须拆分；不要一次交给执行 Agent |

预估 diff 超过 50 行时，先解释思路，再拆任务。

## 原子任务写法

给执行 Agent 的任务必须包含：

1. 任务背景与目标
2. 修改范围：只允许修改哪些文件/模块
3. 禁止范围：明确不要修改什么
4. 具体修改要求：精确到函数、字段、组件、段落或数据 ID
5. 限制与注意事项：不重构、不扩大、不顺手改
6. 验收标准：可人工验证
7. 自测命令或检查方式
8. 输出要求：只输出摘要，不贴完整大文件

可直接使用：[原子任务模板](references/task-template.md)。

## Review 规则

执行 Agent 交付后，先不要直接收。

编排型 AI 应按以下顺序审查：

1. 是否只改指定范围。
2. 是否引入无关重构。
3. 是否影响主链路。
4. 是否改动数据、配置、权限或外部接口。
5. 是否兼容旧数据/旧路径。
6. 是否有空值、并发、状态恢复、边界输入问题。
7. 是否跑了必要自测。
8. 是否给了真实验收路径。

建议输出表格：

```markdown
| # | 位置 | 等级 | 问题 | 建议 |
|---|---|---|---|---|
| 1 | 文件/函数/段落 | 必改/建议/可选/通过 | 说明问题 | 给出建议 |
```

详细清单见：[Review 清单](references/review-checklist.md)。

## 技术债处理规则

技术债可以记录，但不要在业务任务中顺手重构。

处理原则：

- 当前目标不依赖的技术债，先登记。
- CSS 合并、数据拆分、架构调整等中风险任务必须单独开。
- “代码更好看”不等于今天要做。
- 每次处理完技术债，要更新状态和验收结果。

建议状态：`待处理`、`观察中`、`已处理`、`放弃`。

## 文件沉淀建议

对长期项目，建议在业务仓库外或独立知识目录维护协作包，避免流程文件被业务构建、发布或审核误处理。

最小协作包：

| 文件 | 用途 |
|---|---|
| `AGENTS.md` | 给 AI/Agent 的项目协作规则 |
| `TASK_TEMPLATE.md` | 原子任务模板 |
| `REVIEW_CHECKLIST.md` | 审查清单 |
| `TECH_DEBT.md` | 技术债清单 |
| `DECISIONS.md` | 决策记录 |
| `PROJECT_CONTEXT.md` | 项目上下文 |

如果项目不适合建文件，也可以沉淀到 iWiki、Notion、飞书文档或其他团队知识库。

## 不要做什么

- 不要让执行 Agent “看看怎么改最好”。
- 不要把多个需求塞进一条任务。
- 不要在用户未确认方案时直接进行大范围修改。
- 不要把技术债和业务需求混做。
- 不要只看自动检查结果就跳过真实验收。
- 不要把项目私有路径、密钥、内部系统信息写进通用 Skill。

## 输出风格

默认使用中文，结构化输出。

- 方案对比用表格。
- 原子任务用代码块。
- Review 用表格。
- 结论先说，再给细节。
- 对执行 Agent 的指令要短、准、可验收。

## 典型触发后的响应策略

当用户提出一个想法时：先拆解模块，给 2～3 个方案和工作量，不直接写任务。

当用户贴 bug 或截图时：先做无代码诊断，给低成本验证，再决定是否写小补丁任务。

当用户说“开始”“就按这个做”时：输出一条原子任务，不夹带多个目标。

当用户贴执行结果时：做 code review，判断通过/必改/建议，并给下一步。

当用户要求沉淀方法论时：抽象通用原则，去掉项目私有细节，输出可复用模板。