Worktrees

Worktrees（git worktree，把同一仓库 checkout 到多个独立目录的原生 git 能力）让 Agent 在隔离的 Git checkout 里工作。官方文档说明：每个任务都有自己的 files、dependencies 和 changes，你的 main checkout 不会被碰到。

阅读目标：读完本章，你应该能判断什么时候必须用 worktree，并能配置 .cursor/worktrees.json、清理策略和 Editor Window 中的 /worktree / /best-of-n。

1. 先看入口边界

官方页面先给了一个关键边界：

位置	怎么用 worktree
Agents Window	UI-native worktrees，只在 Agents Window 可用
Editor Window	使用 Worktree Skills commands，例如 `/worktree`、`/best-of-n`
Cursor CLI	可以读取 `.cursor/worktrees.json` 的 setup 配置

所以不要只问“Cursor 有没有 worktree”。要先看你处在哪个界面。

2. Worktree 解决什么

flowchart TD
  Main["Main checkout"] --> TaskA["Agent task A"]
  Main --> TaskB["Agent task B"]
  TaskA --> WTA["Worktree A"]
  TaskB --> WTB["Worktree B"]
  WTA --> ReviewA["Review / commit / PR A"]
  WTB --> ReviewB["Review / commit / PR B"]
  ReviewA --> MainDecision["Apply or merge intentionally"]
  ReviewB --> MainDecision

适合使用：

同一个 repo 上启动多个 agents。
风险重构，不想污染当前 checkout。
需要独立安装依赖、构建和测试。
想比较多个实现候选。
需要一个简单 cleanup path。

不适合省掉 review。Worktree 只是隔离，不是质量保证。最后仍然要看 diff、跑测试、决定 commit、PR 或 apply。

3. Agents Window 流程

官方说明：当你在 Agents Window 中把 agent 启动或移动到 worktree，Cursor 会为这个 agent 创建一个 separate checkout。任务在 worktree 里继续执行，变更不会进入 main checkout。

Agent 完成后，你可以：

在 Agents Window 中 review 结果。
继续在 worktree 里工作。
从这个 checkout 创建 commit 或 PR。
把结果带回 main workspace。

4. `.cursor/worktrees.json`

Cursor 会用 .cursor/worktrees.json 自定义 worktree setup。官方说明它会在这些地方创建 worktree 时检查该文件：Agents Window、Editor Window、Cursor CLI。

查找顺序：

worktree path。
project root path。

配置支持三个 setup key：

Key	用途
`setup-worktree-unix`	macOS / Linux 命令或脚本路径，优先于 generic fallback
`setup-worktree-windows`	Windows 命令或脚本路径，优先于 generic fallback
`setup-worktree`	所有系统的通用 fallback

每个 key 可以是 command array，也可以是相对 .cursor/worktrees.json 的 script filepath。

{
  "setup-worktree-unix": [
    "pnpm install",
    "cp $ROOT_WORKTREE_PATH/.env.local .env.local",
    "pnpm run build"
  ],
  "setup-worktree-windows": [
    "pnpm install",
    "copy %ROOT_WORKTREE_PATH%\\.env.local .env.local"
  ]
}

官方提醒：不建议把 dependencies symlink 到 worktree。这样可能影响 main worktree。更好的做法是用 fast package manager，例如 bun、pnpm 或 uv。

深读：为什么 setup 里复制 env 要谨慎

官方示例会复制 .env 或 .env.local，因为很多项目离开环境变量无法启动。但真实团队不能盲目把密钥复制到每个 worktree。

建议把可复制的本地开发 env 和生产密钥分开；worktree setup 只复制开发必需、可回收、低风险的配置。涉及客户数据、生产 token、付款后台 key 的文件不要自动扩散。

5. 调试和清理

如果 worktree setup 失败，官方建议打开 editor 的 Output panel，选择 Worktrees Setup。

Cursor 也可以自动清理旧 worktrees，减少磁盘占用。

{
  "cursor.worktreeCleanupIntervalHours": 6,
  "cursor.worktreeMaxCount": 20
}

设置	含义
`cursor.worktreeCleanupIntervalHours`	多久检查一次旧 worktrees
`cursor.worktreeMaxCount`	超过多少个 worktrees 后清理旧项

6. Editor Window 命令

Editor Window 中，用 Worktree Skills commands。

命令	作用
`/worktree`	在独立 checkout 中完成当前 chat 后续任务
`/apply-worktree`	把 worktree 里的结果带回 main checkout 测试
`/delete-worktree`	完成后删除隔离 checkout
`/best-of-n`	让多个模型用同一 prompt 并行产出候选

示例：

/worktree fix the failing auth tests and update the login copy

/best-of-n 会让每个候选 run 拿到自己的 worktree。它只负责比较 runs，不会自动 merge 回 main checkout。选出结果后，你可以在 worktree 中 commit/push，或用 /apply-worktree 带回 main。

7. 验收清单

Worktree 任务完成后检查：

git worktree list 能看清当前 worktrees。
每个任务有独立目标和验收方式。
setup 过程没有复制不该扩散的密钥。
依赖安装、build、test 都在 worktree 内完成。
diff 只包含该任务需要的文件。
选中候选后才 apply、commit、push 或 open PR。
旧 worktree 有清理策略。

本章自检

完成本章后，用这 3 个问题检查自己是否真正理解：

Agents Window 和 Editor Window 使用 worktrees 的入口有什么区别？
.cursor/worktrees.json 的三个 setup key 分别解决什么问题？
/best-of-n 为什么不能代替人工 review 和 merge？

通过标准：你能为一个多 Agent 并行任务设计 worktree 隔离、setup、验证和清理策略。

官方来源

Cursor Worktrees —— 官方说明 Agents Window worktrees、setup 配置、cleanup、Editor Window commands 和 /best-of-n。
Cursor CLI Worktrees —— 官方说明 CLI worktree 入口。