git worktree + CLI Agent 并行工作模式

git worktree + CLI Agent 并行工作模式

基础概念

git worktree 是 Git 自带的子命令，让一份 .git 仓库可以同时检出多个分支到多个独立的工作目录。换句话说，原本"切分支必须先 stash、还得当心 build 产物"的痛点，被它彻底拆开了：每个分支住自己的目录，互不打扰，但底层共享同一份 .git/objects 和 .git/refs，磁盘成本几乎只有一份。

这个能力在 IDE 时代用处有限——人就一个，再多 worktree 也只能一只手敲键盘。但到了 CLI Agent 时代，情况完全反过来：你可以同时启动 3-10 个 Claude Code / Codex / Gemini CLI 进程，每个 Agent 在自己的 worktree 里独立改代码、跑测试、调工具，彼此完全不打架。Anthropic 自己工程师反复说他们日常会同时挂 10-15 个并行 Claude 会话；社区的 ceiling 经验值是 3-5 个 worktree 比较舒服，再多人脑就跟不上了。

为什么 worktree 是 CLI Agent 的天作之合？三句话讲清楚：

1. Agent 长在终端里：CLI Agent 启动时把 cwd 当工作区，cd 到不同目录就是不同的世界，天然适配多 worktree。
2. Agent 改文件是真的会冲突：两个 Agent 在同一个目录里乱编辑，索引会被互相覆盖，git status 会乱成一锅粥。worktree 把"工作目录"这层物理隔开就解决了。
3. Agent 跑测试/装依赖是真的会撞：node_modules、.venv、target/ 这些 build artifact 全是 per-worktree，Agent A 不会把 Agent B 的依赖装挂掉。

2026 年 11 月 Claude Code CLI 直接把这个模式做成了内建能力：claude --worktree（简写 -w）启动时自动建一个 worktree、跑在隔离环境里；subagent frontmatter 加 isolation: worktree 就能让每个子 Agent 自动获得独立 worktree，结束时若没改动会自动清理。这不是社区拼装出来的脏 trick，而是被官方收编的一等公民工作流。

核心要素

worktree + 多 Agent 拓扑

每个 Agent 看到的"项目"都是完整的代码 + 完整的 git log + 自己的依赖；提交进 .git 后其他 worktree 立即能看到。对 Agent 而言，根本感知不到自己是"并行多开"的——它只看见一个普通的 Git 仓库，这是 worktree 模型最优雅的地方。

基础用法

下面以一个典型场景演示完整生命周期：主仓在 ~/code/myapp，要同时让 3 个 Claude Code 实例并行做"加登录功能 / 修个 bug / 重构 API"。

1. 创建 worktree

# 推荐把所有 worktree 集中放在主仓同级的 .worktrees/ 目录下
# 这样既不污染主目录，也不会被 .gitignore 误伤
cd ~/code/myapp
mkdir -p ../myapp-worktrees

# 1) 新建一个全新分支并 checkout 到 worktree
git worktree add -b feature-login ../myapp-worktrees/feature-login

# 2) 基于已有远端分支创建（追踪 origin/fix-bug-2031）
git worktree add ../myapp-worktrees/fix-bug-2031 origin/fix-bug-2031

# 3) detach 模式（只想看一眼某个 commit，不开分支）
git worktree add --detach ../myapp-worktrees/inspect-v1.2 v1.2.0

git worktree list 验证：

$ git worktree list
/Users/me/code/myapp                                a1b2c3d [main]
/Users/me/code/myapp-worktrees/feature-login        e4f5g6h [feature-login]
/Users/me/code/myapp-worktrees/fix-bug-2031         h7i8j9k [fix-bug-2031]
/Users/me/code/myapp-worktrees/inspect-v1.2         k1l2m3n (detached HEAD)

2. 在每个 worktree 里起一个 Agent 会话

最朴素的写法是开三个终端窗口，每个 cd 到对应 worktree 后跑 claude。但更工程化的做法是用 tmux / zellij 自动化：

# 用 tmux 一次开 3 个 pane，每个 pane 跑一个独立的 Claude Code 会话
tmux new-session -d -s agents -n login \
  "cd ~/code/myapp-worktrees/feature-login && claude"
tmux new-window -t agents:1 -n bugfix \
  "cd ~/code/myapp-worktrees/fix-bug-2031 && claude"
tmux new-window -t agents:2 -n refactor \
  "cd ~/code/myapp-worktrees/refactor-api && claude"
tmux attach -t agents
# Ctrl-b 1 / 2 / 3 在三个 Agent 之间切换

如果用 Claude Code 自己内建的 worktree 模式（CLI 0.x 起支持），可以直接：

# 一行启动：自动建 worktree + 自动起会话
claude --worktree feature-login
# 等价于在 .claude/worktrees/feature-login/ 起一个隔离的 Claude 会话
# 加 --tmux 还会顺便丢进 tmux 会话
claude --worktree fix-bug-2031 --tmux

如果用 subagent 派活，把 worktree 隔离写进 frontmatter 即可：

---
name: parallel-refactor
description: 并行重构多个模块
isolation: worktree   # ← 关键
---
你的任务是同时重构 auth、billing、notifications 三个模块……

主 Agent 派出去的每个子 Agent 自动获得独立 worktree，结束时没改动的会自动清理，有改动的会保留供你 review。

3. 合并回 main

每个 worktree 就是一个普通的 git 工作目录，提交、push、开 PR 都和单仓一模一样：

cd ~/code/myapp-worktrees/feature-login
git add .
git commit -m "feat: add login form"
git push -u origin feature-login
gh pr create --fill

如果走"小步快跑直接合 main"的本地化流程，可以写一个收尾脚本：

#!/usr/bin/env bash
# scripts/wt-merge.sh —— 把指定 worktree 的分支 merge 回 main 并清理
set -euo pipefail

BRANCH=$1
ROOT=~/code/myapp
WT=~/code/myapp-worktrees/$BRANCH

# 1) worktree 内必须 clean
cd "$WT"
if [[ -n "$(git status --porcelain)" ]]; then
  echo "❌ $BRANCH 还有未提交修改，请先处理"; exit 1
fi

# 2) 主仓拉一下，merge --no-ff 保留分支语义
cd "$ROOT"
git fetch --all --prune
git checkout main && git pull
git merge --no-ff "$BRANCH" -m "merge: $BRANCH"
git push origin main

# 3) 清理 worktree 与本地分支
git worktree remove "$WT"
git branch -d "$BRANCH"
echo "✅ $BRANCH 已合入 main 并清理"

跑一次：./scripts/wt-merge.sh feature-login。

4. 清理 worktree

# 正常移除（要求 clean）
git worktree remove ../myapp-worktrees/feature-login

# 强制移除（worktree 内还有未提交修改时）
git worktree remove -f ../myapp-worktrees/inspect-v1.2

# 手动 rm -rf 后用 prune 清理孤立元数据
rm -rf ../myapp-worktrees/old-experiment
git worktree prune -v

# 看一眼有没有要 prune 的（dry-run）
git worktree prune -n

预期输出：

$ git worktree list
/Users/me/code/myapp                          a1b2c3d [main]
/Users/me/code/myapp-worktrees/refactor-api   x1y2z3w [refactor-api]

孤立 worktree 不主动清理会一直占着 .git/worktrees/<name>/ 元数据，定期 git worktree prune 是个好习惯。

同类工具对比

核心区别一句话：stash + 切分支是给"一个人"用的快捷键；worktree是给"多个人或多个 Agent"用的真并行；多次 clone是把"多个仓库"当"一份代码"维护，commit 同步成本高；容器隔离提供的是 OS 级别的安全沙箱，量级和 worktree 不在一个层面。对 CLI Agent 并行场景，worktree 几乎是唯一兼顾"轻量 + commit 共享 + 真隔离"的答案。

常见误区

优劣势分析

思考题

#!/usr/bin/env bash
# 限制最多 5 个并行 worktree
COUNT=$(git worktree list --porcelain | grep -c '^worktree ')
if [[ $COUNT -ge 6 ]]; then  # +1 是主 worktree
  echo "❌ 已有 5 个并行 worktree，先清理再开新的"
  git worktree list
  exit 1
fi
git worktree add -b "$1" "../$(basename $PWD)-worktrees/$1"
# 顺手把 .env 同步过去
cp .env "../$(basename $PWD)-worktrees/$1/.env" 2>/dev/null || true

# scripts/wt-stale-check.sh
NOW=$(date +%s)
git worktree list --porcelain | awk '/^worktree /{print $2}' | while read -r WT; do
  LAST=$(git -C "$WT" log -1 --format=%ct 2>/dev/null || echo 0)
  AGE=$(( (NOW - LAST) / 86400 ))
  if (( AGE > 3 )); then
    echo "⚠️  $WT 已 $AGE 天没活动"
  fi
done

# scripts/wt-cleanup-merged.sh
gh pr list --state merged --json headRefName -q '.[].headRefName' | while read -r BRANCH; do
  WT=$(git worktree list --porcelain | awk -v b="$BRANCH" '
    /^worktree /{path=$2} /^branch /{if($2=="refs/heads/"b) print path}')
  [[ -n "$WT" ]] && git worktree remove "$WT" && git branch -d "$BRANCH"
done
git worktree prune -v

参考资料

1. Git 官方文档 - git-worktree：https://git-scm.com/docs/git-worktree（查询日期 2026-04-22）
2. Anthropic Claude Code 官方常用工作流（含 --worktree、subagent isolation）：https://code.claude.com/docs/en/common-workflows
3. Claude Code 内建 worktree 支持发布说明（Threads）：https://www.threads.com/@boris_cherny/post/DVAAnexgRUj/introducing-built-in-git-worktree-support-for-claude-code-now-agents-can-run-in
4. Mastering Git Worktrees with Claude Code for Parallel Development（Medium，Dogukan Uraz Tuna）：https://medium.com/@dtunai/mastering-git-worktrees-with-claude-code-for-parallel-development-workflow-41dc91e645fe
5. Parallel Claude Code Sessions with Git Worktrees: The Production Setup（Code With Seb）：https://www.codewithseb.com/blog/parallel-claude-code-sessions-git-worktrees-guide
6. pnpm + Git Worktrees for Multi-Agent Development（pnpm 官方文档）：https://pnpm.io/11.x/git-worktrees
7. workmux - git worktrees + tmux windows for zero-friction parallel dev：https://github.com/raine/workmux
8. parallel-code - Run Claude Code, Codex, and Gemini side by side in their own worktrees：https://github.com/johannesjo/parallel-code
9. Git Worktree Isolation in Claude Code（Towards AI，Rick Hightower，2026-03）：https://medium.com/@richardhightower/git-worktree-isolation-in-claude-code-parallel-development-without-the-chaos-262e12b85cc5