Worktree 隔离开发：
Claude Code 并行编码无冲突方案

一、传统开发的痛点：上下文切换噩梦

想象这样一个场景：你正在用 Claude Code 深度重构一个核心模块，思路已经打通，Claude 对整个代码库的理解也达到了峰值状态。这时候——产品突然说有个线上 Bug 需要紧急修复。

于是你不得不：git stash → git checkout main → 修复 Bug → git checkout feature-branch → git stash pop → 重新向 Claude 解释当前的重构背景……

这个过程不只是浪费你的时间。更关键的是，你打断了 Claude Code 积累的深层上下文。切换分支再回来后，Claude 需要重新理解你的代码、意图和进度，通常需要 10–15 分钟才能恢复到之前的状态。

Git Worktree 就是解决这个问题的利器。它允许同一个仓库同时在多个独立目录中工作，每个目录检出不同分支，共享同一份 Git 历史，但文件完全物理隔离。

二、Git Worktree 核心原理

Git Worktree 的架构如下：

同一个 Git 仓库（.git 唯一，共享）
│
├── ~/projects/my-app/              ← 主工作区（main 分支）
│     .git/  ← 唯一的 Git 数据库
│     src/
│     package.json
│
├── ~/projects/my-app-auth/         ← Worktree 1（feature/auth 分支）
│     src/   ← 物理隔离，独立文件
│     package.json
│
└── ~/projects/my-app-hotfix/       ← Worktree 2（hotfix/login 分支）
      src/   ← 物理隔离，独立文件
      package.jsonTREE

核心特性：

• 共享 Git 历史：所有 worktree 共用同一个 .git 目录，commit、branch、remote 全部同步
• 文件物理隔离：每个 worktree 有自己的工作目录，文件互不影响
• 独立 HEAD：每个 worktree 可检出不同分支，互不干扰；同一分支不能被多个 worktree 同时检出
• 秒级创建，无拷贝开销：不像克隆仓库那样复制整个 .git 数据，创建和删除都极快

三、环境准备：前提条件检查

在开始之前，确认环境满足以下要求：

• Git 2.5 或以上版本（worktree 是 Git 2.5 引入的特性）
• Claude Code CLI 已安装并登录（claude --version 可正常输出）
• 已有至少一次 commit 的 Git 仓库（空仓库无法创建 worktree）
• 建议将 .claude/worktrees/ 加入 .gitignore（避免污染 git status）

git --version
# 预期输出：git version 2.5.0 或更高BASH

brew install gitBASH

claude --version
# 预期输出：claude 1.x.x 或更高BASH

npm install -g @anthropic-ai/claude-codeBASH

echo ".claude/worktrees/" >> .gitignore
git add .gitignore
git commit -m "chore: ignore claude worktrees directory"BASH

四、创建你的第一个 Worktree

掌握了原理，来看实际操作。Git Worktree 的核心命令非常简单：

# 基于已有分支创建 worktree
git worktree add ../my-project-feature feature-branch

# 同时创建新分支并生成 worktree（最常用）
git worktree add -b feature/new-login ../my-project-login

# 基于特定提交创建 worktree（用于调试历史版本）
git worktree add ../my-project-v1 abc1234BASH

命令格式：git worktree add [-b <新分支>] <路径> <基础分支或提交>

# 进入主项目目录
cd ~/projects/my-app

# 创建新分支 + 新 worktree（目录会自动创建）
git worktree add -b feature/auth ../my-app-auth

# 验证创建成功
git worktree listBASH

# 预期输出：
/Users/you/projects/my-app       abc1234 [main]
/Users/you/projects/my-app-auth  def5678 [feature/auth]OUTPUT

# 再创建一个用于紧急修复的 worktree
git worktree add -b hotfix/login-bug ../my-app-hotfix

# 查看全部 worktree 及其状态
git worktree list --porcelainBASH

# 方法一：删除目录后执行 prune（推荐）
rm -rf ../my-app-auth
git worktree prune

# 方法二：直接用 remove 命令（Git 2.17+）
git worktree remove ../my-app-authBASH

五、配合 Claude Code 并行编码实战

现在来看最精华的部分：如何让 Claude Code 在多个 worktree 中同时工作。

方案一：手动在各 Worktree 启动 Claude Code

最直接的方式：为每个 worktree 开一个终端窗口，分别启动 Claude Code：

# 终端 1：在主工作区继续原有工作
cd ~/projects/my-app
claude

# 终端 2：在 auth 功能 worktree 中工作
cd ~/projects/my-app-auth
claude

# 终端 3：处理紧急 bug 修复
cd ~/projects/my-app-hotfix
claudeBASH

三个 Claude Code 实例完全独立，各自维护对所在分支的深层理解，互不干扰。每个实例都知道自己所在的代码库状态，无需重新解释背景。

方案二：使用 Claude Code 内置 --worktree 标志

Claude Code 最新版本内置了 --worktree 标志，可以从项目根目录直接创建并进入隔离的 worktree 环境：

# 从主项目目录启动，自动创建 worktree
claude --worktree feature-auth

# Claude Code 会自动：
# 1. 在 .claude/worktrees/ 下创建隔离目录
# 2. 检出对应分支（或创建新分支）
# 3. 在该目录启动 Claude 会话BASH

方案三：Subagent 配置 isolation: worktree

如果你在使用 Claude Code 的多代理功能，可以在 agent 配置文件的 frontmatter 中声明 isolation: worktree，让每次 agent 运行都在独立的 worktree 中执行：

---
name: feature-developer
description: 负责新功能开发的子代理
isolation: worktree
---

你是一个功能开发专家。收到任务后，在当前 worktree 中实现对应功能并提交代码。YAML

配置了 isolation: worktree 的 subagent，每次被调用时都会自动获得一个全新的隔离 worktree，运行完毕后可选择保留（已有修改）或自动清理（无修改）。这是实现"并行多 agent 开发"的核心技术。

实战场景：三条线同时并行推进

真实场景：你同时需要处理三个任务：

• Feature A：实现用户认证系统（预计 3 小时）
• Feature B：重构数据库访问层（预计 2 小时）
• Hotfix：修复线上登录超时问题（紧急，1 小时）

传统串行方式约需 6 小时，而用 Worktree + 并行 Claude 实例：

# 创建三个 worktree
git worktree add -b feature/auth    ../my-app-auth
git worktree add -b refactor/db     ../my-app-db
git worktree add -b hotfix/timeout  ../my-app-hotfix

# 用 tmux 同时开启三个 Claude Code 会话
tmux new-session -d -s auth    -c ~/projects/my-app-auth    'claude'
tmux new-session -d -s db      -c ~/projects/my-app-db      'claude'
tmux new-session -d -s hotfix  -c ~/projects/my-app-hotfix  'claude'

# 切换到各会话
tmux attach-session -t auth   # 查看认证功能进度
tmux attach-session -t hotfix # 关注紧急修复BASH

三条线同时推进，总耗时约等于最长任务的时间（3 小时），而不是各任务的加总（6 小时）。

六、自动化工作流：脚本与 tmux 技巧

手动逐条执行命令效率有限。将创建 worktree + 启动 Claude Code 的流程脚本化，可以一键启动完整的并行开发环境。

通用 Worktree 启动脚本

在项目根目录创建 scripts/worktree-start.sh：

#!/bin/bash
# scripts/worktree-start.sh
# 用法: ./scripts/worktree-start.sh  [base-branch]

set -e

BRANCH_NAME=$1
BASE_BRANCH=${2:-main}

if [ -z "$BRANCH_NAME" ]; then
  echo "Usage: $0  [base-branch]"
  echo "Example: $0 feature/auth main"
  exit 1
fi

REPO_ROOT=$(git rev-parse --show-toplevel)
REPO_NAME=$(basename "$REPO_ROOT")
PARENT_DIR=$(dirname "$REPO_ROOT")
SAFE_NAME="${BRANCH_NAME//\//-}"
WORKTREE_PATH="$PARENT_DIR/${REPO_NAME}-${SAFE_NAME}"

echo "🌿 创建 Worktree..."
echo "   Branch: $BRANCH_NAME"
echo "   Path:   $WORKTREE_PATH"

# 如果分支已存在则直接检出，否则从 base branch 新建
if git show-ref --verify --quiet "refs/heads/$BRANCH_NAME"; then
  git worktree add "$WORKTREE_PATH" "$BRANCH_NAME"
else
  git worktree add -b "$BRANCH_NAME" "$WORKTREE_PATH" "$BASE_BRANCH"
fi

echo "✅ Worktree 已创建: $WORKTREE_PATH"

# 在 tmux 中启动（若当前在 tmux 会话内）
if command -v tmux &> /dev/null && [ -n "$TMUX" ]; then
  tmux new-window -n "$SAFE_NAME" -c "$WORKTREE_PATH" "claude; bash"
  echo "✅ 已在新 tmux 窗口启动 Claude Code（窗口: $SAFE_NAME）"
else
  cd "$WORKTREE_PATH"
  claude
fiBASH

# 赋予执行权限
chmod +x scripts/worktree-start.sh

# 使用示例
./scripts/worktree-start.sh feature/auth
./scripts/worktree-start.sh hotfix/login-bug hotfix-baseBASH

批量并行启动脚本

需要同时启动多个任务时，使用以下脚本一键拉起全部会话：

#!/bin/bash
# scripts/parallel-start.sh

# 定义要并行处理的任务分支
TASKS=(
  "feature/user-auth"
  "refactor/db-layer"
  "hotfix/login-timeout"
)

BASE_BRANCH="main"
REPO_ROOT=$(git rev-parse --show-toplevel)
REPO_NAME=$(basename "$REPO_ROOT")
PARENT_DIR=$(dirname "$REPO_ROOT")
SESSION_NAME="parallel-dev"

tmux new-session -d -s "$SESSION_NAME" -x 220 -y 50

FIRST=true
for BRANCH in "${TASKS[@]}"; do
  SAFE_NAME="${BRANCH//\//-}"
  WORKTREE_PATH="$PARENT_DIR/${REPO_NAME}-${SAFE_NAME}"

  # 创建 worktree（如果目录不存在）
  if [ ! -d "$WORKTREE_PATH" ]; then
    git worktree add -b "$BRANCH" "$WORKTREE_PATH" "$BASE_BRANCH" 2>/dev/null \
      || git worktree add "$WORKTREE_PATH" "$BRANCH"
  fi

  # 在 tmux 中创建窗口并启动 Claude Code
  if $FIRST; then
    tmux rename-window -t "$SESSION_NAME:0" "$SAFE_NAME"
    tmux send-keys -t "$SESSION_NAME:$SAFE_NAME" "cd $WORKTREE_PATH && claude" Enter
    FIRST=false
  else
    tmux new-window -t "$SESSION_NAME" -n "$SAFE_NAME" -c "$WORKTREE_PATH"
    tmux send-keys -t "$SESSION_NAME:$SAFE_NAME" "claude" Enter
  fi

  echo "✅ 已启动: $BRANCH → $WORKTREE_PATH"
done

echo ""
echo "🎉 所有会话已启动！"
echo "   tmux attach-session -t $SESSION_NAME"
tmux attach-session -t "$SESSION_NAME"BASH

Worktree 清理脚本

定期清理已合并的 worktree，保持仓库整洁：

#!/bin/bash
# scripts/worktree-clean.sh

echo "🧹 扫描可清理的 Worktree..."

git worktree list --porcelain | awk '/^worktree /{path=$2} /^branch /{branch=$2; gsub("refs/heads/","",branch); print path, branch}' | \
while read -r WT_PATH WT_BRANCH; do
  # 跳过主 worktree
  [ "$WT_PATH" = "$(git rev-parse --show-toplevel)" ] && continue

  # 检查分支是否已合并到 main
  if git merge-base --is-ancestor "refs/heads/$WT_BRANCH" "refs/heads/main" 2>/dev/null; then
    echo "  可清理: $WT_PATH（分支 $WT_BRANCH 已合并）"
    read -p "  删除? [y/N] " confirm
    if [[ $confirm =~ ^[Yy]$ ]]; then
      git worktree remove "$WT_PATH" --force
      echo "  ✅ 已删除"
    fi
  fi
done

git worktree prune
echo "✅ 清理完成"BASH

七、常见问题与解决方案