Git Worktree：让 AI Agent 真正并行工作的利器

Git Worktree 让"分支"从一个抽象概念变成了真实存在的目录，AI Agent 可以像操作普通文件系统一样工作，互不干扰。

🎯 它解决了什么问题？

你有没有遇到过这种情况：

这些问题的根源都一样：一个仓库同一时刻只能有一个工作目录。

Git Worktree 就是来解决这个问题的。

---

🧠 原理：共享对象库，独立工作目录

普通 git clone 的方式，每个副本都有独立的 .git/ 目录，会完整复制所有的 Git 对象（历史记录、文件内容），浪费空间。

Worktree 的做法不一样——所有 worktree 共享同一个 .git/objects/，但各自有独立的工作文件和 HEAD：

~/project/myapp/              ← 主仓库
├── .git/
│   ├── objects/    ← 所有 worktree 共享（提交、文件内容）
│   ├── refs/       ← 所有 worktree 共享（分支、tag）
│   └── worktrees/  ← 每个额外 worktree 的元数据
│       └── myapp-feat/
│           ├── HEAD      ← 该 worktree 独立的当前分支
│           └── index     ← 该 worktree 独立的暂存区
└── src/...

~/project/myapp-feat/         ← 另一个工作目录
├── .git  ← 这是一个文件（不是目录！）
│          内容：gitdir: ../myapp/.git/worktrees/feat
└── src/...

关键点：

所以 worktree 比克隆省空间，创建速度也极快。

---

⚙️ 基本操作

# 查看当前所有 worktree
git worktree list

# 创建新 worktree，同时新建分支（基于 develop）
git worktree add ../myapp-feat -b feat/my-feature origin/develop

# 删除 worktree
git worktree remove ../myapp-feat

# 清理失效的引用
git worktree prune

目录位置建议：放在主仓库的同级目录，不要放在主仓库内部：

~/project/myapp/          ← 主目录
~/project/myapp-feat/     ← worktree ✅
~/project/myapp/feat/     ← 不推荐 ❌

---

⚠️ 一个关键限制

同一个分支不能同时被两个 worktree 检出。

主目录   → main ✅
worktree → develop ✅
worktree → feat/xxx ✅

主目录   → main ✅
worktree → main ❌  报错：'main' is already checked out

这个限制直接影响到工作流设计——主目录最好固定在 main 上，所有开发都在 worktree 里做。

---

🚀 配合 AI Agent 的最佳实践

方式一：Cursor Background Agent（自动管理）

Cursor 的 Background Agent 会自动创建和销毁 worktree，你不需要手动操作。AI 在隔离的 worktree 里工作，完成后让你 review，互不干扰。

方式二：手动创建 + 新窗口（日常推荐）

# 1. 基于最新 develop 创建 AI 工作区
git fetch origin
git worktree add ../myapp-ai -b feat/my-task origin/develop

# 2. 在新 Cursor 窗口打开
cursor ../myapp-ai

# 3. 在新窗口里让 AI 干活，你在主窗口继续开发
# 4. AI 完成，review，/ship

方式三：多 Agent 并行

git worktree add ../proj-feat-auth -b feat/auth origin/develop
git worktree add ../proj-feat-payment -b feat/payment origin/develop
git worktree add ../proj-bugfix -b fix/crash origin/main

三个 Agent 同时工作，互不影响，共享同一个 Git 对象库。

---

🔍 配合 PR 工作流的完整生命周期

merge PR 后通常会自动删除特性分支并切回 base branch（develop 或 main）。配合 worktree 后：

git worktree add ../myapp-ai -b feat/xxx origin/develop
         ↓
   在 worktree 里开发
         ↓
   PR 创建 + merge + 分支删除
         ↓
   自动切回 develop（worktree 的 HEAD）
         ↓
   ┌─────────────────────────────────────────┐
   │ 还有任务？                               │
   │  → git checkout -b feat/next origin/develop │
   │ 没任务了？                              │
   │  → git worktree remove ../myapp-ai      │
   └─────────────────────────────────────────┘

注意：如果主目录也在 develop 分支，切换时会报错：

error: 'develop' is already checked out at '/Users/.../myapp'

所以主目录保持在 main，这个问题就不存在了。

---

📝 总结

核心一句话：worktree 让你的工作目录和分支解耦，主目录跟 main，所有任务在独立的 worktree 里完成，完事合并删除，干净利落。