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

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

但很多人追问下一层：

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

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

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

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

一句话：

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

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

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

2.1 适合多 Agent + Worktree 的场景

2.2 不适合的场景

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

命名规范（建议）：

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

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

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

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 的写法
- 使用 <script setup lang="ts">
- 复杂逻辑提取为 composables验收：
- 完成后跑 pnpm lint
- 列出改动文件清单和迁移要点

Agent B 模板（并行，换目录即可）：

 复制代码任务：将 src/views/product/ 下所有页面从 Options API 迁移到 Composition API。
（其余约束同 Agent A，范围换成 src/views/product/**）

Step 4：并行执行 + 人工监控

并行时你做三件事，不用盯着 Agent 写每一行：

1. 看进度：Agent 是否卡在 lint 报错循环
2. 看越界：有没有改到禁止清单里的文件（diff 预览）
3. 看模式：抽样 1～2 个文件，迁移风格是否一致

红旗信号——立刻叫停某个 Agent：

• 开始改 components/ 或 utils/ 公共文件
• 单次改动超过 Plan 约定的文件数 2 倍以上
• lint 报错超过 3 轮还没收敛
• 自行「优化」了不在范围内的逻辑

Step 5：Review + 合并

按 Code Review 文 的标准，每个 worktree 分支单独审，不要一次性全 merge。

 复制代码# 在对应 worktree 目录
git diff main...HEAD --stat
git diff main...HEAD# 逐分支合并
git checkout main
git merge migrate/order --no-ff
# 解决冲突 → 跑 pnpm lint && pnpm typecheck
git merge migrate/product --no-ff

合并后 统一格式化一遍（多 Agent 最容易出现风格漂移）：

 复制代码pnpm lint --fix
pnpm format   # 如有

四、实战案例：Vue Options API → Composition API 迁移

这是我在 Cursor 复盘 里做过的真实项目，完整复盘如下。

4.1 背景

4.2 任务拆分

 复制代码Agent A（worktree: migrate/order）  → src/views/order/**     （12 个页面）
Agent B（worktree: migrate/product）→ src/views/product/**   （15 个页面）
Agent C（串行，A/B 完成后）         → src/views/settings/**  （8 个页面）
人工                               → src/views/report/**    （含复杂图表，不敢交给 Agent）

为什么 report 没并行？ 含 ECharts 封装、自定义 Hooks，和公共层耦合重——这类模块宁可串行 + 人盯。

4.3 时间与质量

4.4 出现的问题与处理

五、任务拆分原则：切得好，才能并行得好

5.1 黄金法则

 复制代码按「目录边界」切，不按「文件数量」切
按「零共享写入」切，不按「谁写得快」切

5.2 拆分维度参考

5.3 共享依赖怎么处理？

典型做法：

1. Phase 0（串行）：人工或单 Agent 抽公共 composable / 类型
2. Phase 1（并行）：各 Agent 迁移自己目录，引用 Phase 0 成果
3. Phase 2（串行）：合并、统一格式化、补测试

六、和 Rules / Skills / 四模式的配合

多 Agent 并行的前置条件，是你已经建好约束体系：

建议在项目 Skill 里加一段 并行任务专用 SOP：

 复制代码## 多 Agent 并行迁移 SOP1. Plan 模式输出总方案和任务边界
2. 人审边界，确认无文件交叉
3. 每个 worktree 开独立 Agent，粘贴标准任务 Prompt
4. 禁止清单必须包含：components/、store/、router/、types/
5. 各分支完成后单独 Review，再合并
6. 合并后统一 pnpm lint --fix

七、踩坑指南

坑 1：没 Plan 直接开两个 Agent

后果：A 用 script setup，B 用 defineComponent；合并后像两个人写的代码。
对策：Plan 输出「唯一迁移模式」，写入每个 Agent Prompt。

坑 2：禁止清单太模糊

后果：Agent 改了公共组件，两个分支都受影响。
对策：用 目录级 禁止（不要改 src/components/**），不只写「不要改公共文件」。

坑 3：并行粒度太细

后果：开了 5 个 Agent 迁 5 个页面，合并和 Review 比串行还累。
对策：每个 Agent 至少覆盖 8～15 个文件 或 一个完整子模块。

坑 4：不做中间抽查

后果：Agent 跑了 2 小时，方向全错，worktree 白干。
对策：启动后 15～20 分钟看一次 diff，确认模式正确再继续。

坑 5：合并时不跑验证

后果：分支各自 lint 通过，合并后类型冲突。
对策：每个 merge 节点跑 pnpm typecheck && pnpm lint && pnpm test。

坑 6：worktree 忘了清理

后果：磁盘占满、分支混乱、不确定哪个目录是最新的。
对策：合并完成后立刻清理：

 复制代码git worktree remove ../project-order-migrate
git branch -d migrate/order

八、Worktree 单 Agent 场景：不一定非要并行

多 Agent 是 worktree 的 进阶用法。日常实验性改动，单 Agent + 单 worktree 就够用：

 复制代码git worktree add ../project-experiment -b experiment/new-state
# Cursor 在 experiment 目录打开 Agent 折腾
# 不行就：git worktree remove ../project-experiment

这比 git stash + 切分支更适合 Agent 场景——Agent 改动量大，stash 容易乱。

九、行动清单

1. 下一次 10+ 文件的大改动，先 Plan 出任务边界，判断能否并行
2. 创建 2 个 worktree，用标准 Prompt 模板分配 Agent
3. 在 Rules 里补一条 composable / 组件命名规范，防风格漂移
4. 合并前对每个分支单独做 Code Review 自查
5. 合并后跑全量 typecheck + lint + test
6. 清理 worktree 和临时分支，保持仓库整洁
7. 把本次并行的 Prompt 和踩坑记入项目 Skill，下次复制即用

结语

四模式选型 解决的是「这一步用什么模式」；Rules / Skills 解决的是「按什么规矩做」；多 Agent + Worktree 解决的是「大活怎么提速且不把 main 分支赌进去」。

它不是日常开发的默认选项，而是前端工程师的 「重型设备」——任务够大、边界够清、Review 跟得上的时候，收益非常明显。

记住三个关键词：Plan 定模式、目录切边界、合并必审查。做到这三点，大重构不用再赌一把。

系列延伸阅读

• 前端工程师的 AI 副驾驶：Cursor 一整年真实体验与避坑指南
• Cursor Rules / Skills 分层设计：让 Agent 像「团队新同事」
• Cursor 四模式选型指南：Ask / Plan / Agent / Debug 何时用哪个？
• AI 生成代码之后，前端 Code Review 审什么？
• 用 MCP 把 Figma、语雀、GitLab 串成一条前端工作流