Cursor 多 Agent 与 Worktree：大重构不再赌运气

Cursor 多 Agent 与 Worktree：大重构不再赌一把

在 四模式选型指南 里，我提过：大重构 / 实验性改动，用 Agent + worktree，别直接在 main 上改。

但很多人追问下一层：

在 Cursor 一年复盘 里，我做过一次「Options API → Composition API」批量迁移：两个 Agent 并行，核心迁移从一周压到 2～3 天。代价也真实存在——合并冲突、风格不一致、某个 Agent 擅自改了公共组件。

这篇文章是一份 前端大改动并行实战手册：什么时候该开多 Agent、worktree 怎么隔离、任务怎么切、合并怎么审，以及我踩过的坑。

---

一、先搞清楚：Worktree 和多 Agent 各解决什么？

很多人把两者混为一谈。其实它们是 两层隔离：

能力	解决什么问题	类比
Git Worktree	同一仓库多份工作目录，互不干扰	两个工位各干各的，不抢同一张桌子
多 Agent 并行	多个 Agent 会话同时跑，各自独立上下文	两个实习生同时接单，各写各的模块

一句话：

 复制代码Worktree = 物理隔离（文件系统层面）
多 Agent = 执行隔离（对话和任务层面）

两者配合，才能放心让 Agent 「放手干」——干砸了直接删 worktree，主分支一行没动。

---

二、什么时候该用？什么时候别用？

2.1 适合多 Agent + Worktree 的场景

场景	为什么适合并行	拆分维度
框架迁移（Options API → Composition API）	模块间耦合低，模式统一	按 views/ 子目录
批量重命名 / 路径调整	改动模式重复	按目录或文件类型
多页面 UI 统一改版	页面互不依赖	按 page / route
实验性架构验证	可能全盘推翻	独立 worktree，不合并
大仓库多 feature 并行	减少互相等待	按 feature 模块

2.2 不适合的场景

场景	原因	替代方案
改 1～2 个文件	开 worktree 比改动本身还重	单 Agent 或直接 Tab
强耦合公共层重构	多 Agent 必然抢同一文件	单 Agent + Plan，或先抽公共层
涉及数据库迁移	并行难以协调顺序	串行 Agent，严格 Plan
你不熟悉这块代码	拆任务都拆不对	先 Ask 摸底

2.3 决策清单

满足 3 条及以上，再开多 Agent：

• 总改动涉及 10+ 文件 或 3+ 模块
• 已在 Plan 模式 对齐过总体方案和迁移模式
• 任务可按 目录 / 模块 切分，且 无共享文件交叉
• 已配置 Rules，约束输出风格
• 你有时间做 合并后的人工 Review（不是丢给 Agent 就 merge）

---

三、标准工作流：五步走完大重构

Step 1：Plan 模式——先对齐「迁移模式」，再拆任务

千万别跳过这步。 多 Agent 翻车的第一大原因，是各 Agent 用了不同的迁移模式。

 复制代码【Plan 模式，不要写代码】目标：将 src/views/ 下 Options API 页面迁移到 Composition API。请输出：
1. 统一迁移模式（script setup? 组合式函数提取?）
2. 参考实现：@src/views/dashboard/index.vue（已是 Composition API）
3. 按目录拆分的任务边界（哪些文件夹可并行、哪些有共享依赖）
4. 禁止改动的文件清单（公共组件、store、router）
5. 每个子任务的验收标准（lint 通过、页面可渲染）不要写代码。

Plan 输出后，人审三件事：

1. 边界有没有重叠？ 两个 Agent 不能改同一个文件
2. 参考实现是不是项目里真正在用的模式？
3. 禁止清单是否包含 components/、utils/、store/ 等公共层？

Step 2：创建 Worktree

Cursor 支持通过 /worktree 命令创建隔离工作区。手动方式也常用：

 复制代码# 从 main 创建两个并行 worktree
git worktree add ../project-order-migrate -b migrate/order
git worktree add ../project-product-migrate -b migrate/product

方式	优点	缺点
Cursor /worktree	和 Agent 集成好，一键隔离	需熟悉 Cursor 命令
git worktree add	标准 Git 操作，可控	需手动开 Cursor 窗口

命名规范（建议）：

 复制代码分支名：migrate/<模块名>
目录名：../<项目名>-<模块名>-migrate

Step 3：分配任务——每个 Agent 一份「合同」

每个 Agent 的 Prompt 必须包含 五要素：

要素	说明	示例
范围	只改哪些目录	src/views/order/**
禁止	明确不能碰的文件	不要改 components/、store/
模式	引用 Plan 对齐的迁移模式	按 dashboard/index.vue 风格
验收	完成标准	pnpm lint 通过
约束	Rules 引用	遵循 .cursor/rules/

Agent A 模板：

 复制代码【Agent 模式】任务：将 src/views/order/ 下所有页面从 Options API 迁移到 Composition API。范围：
- 只改 src/views/order/** 下的 .vue 文件
- 可新增 src/views/order/composables/ 存放提取的逻辑禁止：
- 不要改 src/components/、src/store/、src/router/
- 不要改 src/views/order/ 以外的任何文件
- 不要 git commit模式：
- 严格参考 @src/views/dashboard/index.vue 的写法
- 使用