Claude Code SDK #21：Worktrees 全解——--worktree 标志 × .worktreeinclude × 子 Agent 隔离，让多任务并行不再踩脚

你有没有遇到过这种场景：Claude 正在帮你写 feature-auth 分支，突然来了个紧急 bug，你想同时让它修 bugfix-123——但两个任务要改的文件有重叠，一操作就乱套。1

--worktree 就是为了解决这件事而生的。

什么是 Worktree，为什么需要它

git worktree 是 Git 原生功能：在同一个仓库下创建多个独立的工作目录，每个目录有自己的文件状态和分支，但共享同一份 commit 历史和远程。2

Claude Code 的 --worktree 在此基础上多做了一层封装：

自动创建分支：每次 --worktree <name> 都在 .claude/worktrees/<name>/ 新建一个 worktree，同时在仓库里创建名为 worktree-<name> 的分支
隔离文件编辑：两个 Claude session 各住一个 worktree，互相改文件不会踩到对方
session 级别隔离而非进程级别：每个 worktree 是一个真实的目录，不是内存沙箱

和「在同一目录里跑两个 Claude 终端」的最大区别就在这里——后者改的是同一份文件，冲突几乎无法避免。

基础用法：三条命令

# 最常见用法：指定 worktree 名称
claude --worktree feature-auth

# 同时在另一个终端开第二个
claude --worktree bugfix-123

# 懒得起名？Claude 自动生成随机名（如 bright-running-fox）
claude --worktree

首次在某个目录用 --worktree 之前，需要先单独运行一次 claude（接受 workspace trust 对话框）。非交互的 -p 模式跳过了信任检查，claude -p --worktree 可以直接用。

记得把 .claude/worktrees/ 加进 .gitignore，否则 git status 会列出一堆无关文件。

.claude/worktrees/ 目录结构：项目根目录下分出 feature-auth、bugfix-123、bright-running-fox 三个独立 worktree 目录 — `--worktree` 创建的目录结构示意（AI 生成图）

基础分支策略：从哪个 commit 出发？

新 worktree 默认从 origin/HEAD（远程默认分支）创建，拿到干净的远程最新状态。这对"基于稳定主干开任务"场景很合适。

有时你需要带上本地未推送的改动——比如正在开发中的 feature 分支，让子 Agent 在它基础上做子任务。这时在 settings 里把 worktree.baseRef 设为 "head"：1

{
  "worktree": {
    "baseRef": "head"
  }
}

该字段只接受 "fresh"（默认，从 origin/HEAD）和 "head"（从当前本地 HEAD）两个值，不支持任意 git ref。

还有一个场景：直接基于某个 PR 开 worktree：

# 基于 PR #1234 创建 worktree
claude --worktree "#1234"

Claude Code 会自动 fetch pull/1234/head 并在 .claude/worktrees/pr-1234/ 建立 worktree。对于 code review 过程中需要本地验证改动的场景非常便利。

.worktreeinclude：把 .env 带进新 worktree

新 worktree 是一个全新 checkout，.env、.env.local、config/secrets.json 这些在 .gitignore 里的文件不会自动过来——这意味着 Claude 到新 worktree 里可能跑不起来项目。

解决方案是在项目根目录创建 .worktreeinclude，语法和 .gitignore 一致：

.env
.env.local
config/secrets.json

有个重要限制：只有「匹配该模式」且「已经在 .gitignore 里」的文件才会被复制。已追踪（tracked）的文件不受影响，不会被意外复制。

这个机制对三种情况都生效：--worktree 交互会话、子 Agent 的 worktree（下面会讲）、桌面端的并行 session。

.worktreeinclude 机制：主仓库中标记为 gitignored 的 .env 文件，在新 worktree 创建时被自动复制过去 — `.worktreeinclude` 的文件复制流程：只有同时「匹配模式」且「在 .gitignore 里」的文件才会被复制（AI 生成图）

子 Agent × Worktree：让并行任务不互相踩脚

前面说的是手动在终端里同时跑多个 Claude 会话。更进一步：让 Claude 自己派发多个子 Agent，各自住在独立 worktree 里。

两种触发方式：

临时指定：在会话中告诉 Claude「用 worktree 隔离你的 agents」
永久配置：在自定义子 Agent 的 frontmatter 里加 isolation: worktree

配置了 isolation: worktree 的子 Agent 每次被启动都会自动获得一个临时 worktree。任务完成后，如果这个 worktree 里没有任何改动（无未提交文件、无新文件、无新 commit），它会被自动删除，保持仓库干净。

子 Agent 的 worktree 同样遵守 worktree.baseRef 设置——设了 "head" 时，子 Agent 也会从当前本地 HEAD 出发，继承你主分支上还没推的改动。

清理：谁来管 worktree 的生命周期

退出 worktree session 时，行为取决于你改了什么：

情况	自动处理
无未提交改动、无新文件、无新 commit	自动删除 worktree 及对应分支
上面条件加上 session 有名称	Claude 会先询问是否保留
有未提交改动或新 commit	提示你选择保留还是删除
`-p` 非交互模式	不自动清理，需手动 `git worktree remove`

Worktree 清理决策树：无改动自动删除、有改动提示保留或删除、-p 非交互模式必须手动清理 — 退出 session 时 worktree 的清理路径（AI 生成图）

子 Agent 和后台 session 的 worktree 有一个自动清理机制：超过 cleanupPeriodDays 设置的天数，且没有未提交改动、新文件、未推 commit 时，自动清除。通过 --worktree 手动创建的 worktree 不受这个自动清扫影响。

运行中的 Agent 会调用 git worktree lock 锁住自己的 worktree，防止并发清理意外删掉正在用的目录；Agent 结束后自动解锁。

强制手动清理：

git worktree remove ../project-feature-a
# 有未提交改动时加 --force
git worktree remove --force ../project-feature-a

手动管理：更精细的控制

如果需要把 worktree 放在仓库目录之外，或者 checkout 已有分支，就直接用 Git 命令：

# 新分支 + 指定位置
git worktree add ../project-feature-a -b feature-a

# 已有分支
git worktree add ../project-bugfix bugfix-123

# 进入后启动 Claude
cd ../project-feature-a && claude

# 查看所有 worktree
git worktree list

每个新 worktree 是独立的目录，进入后要重新初始化项目环境：装依赖、建虚拟环境、跑 setup 脚本。这是 git worktree 本身的特性，与 Claude Code 无关。

非 git 项目：通过 Hook 扩展

--worktree 默认使用 git 实现。SVN、Perforce、Mercurial 等项目可以通过配置 WorktreeCreate 和 WorktreeRemove Hook 完全替换默认逻辑：1

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

Hook 从 stdin 读取 worktree name，执行完后把目录路径 print 到 stdout，Claude Code 把这个路径作为 session 的工作目录。注意：使用自定义 Hook 时，.worktreeinclude 的文件复制逻辑不再执行——需要在 Hook 脚本里自己处理环境变量文件的拷贝。

五条实践建议

默认用 origin/HEAD，需要继承本地改动再切 head——baseRef 设置直接决定 Claude 看到的代码快照，弄错了很难察觉
把 .claude/worktrees/ 加进 .gitignore 是必做项，不然 git status 噪音会干扰你和 Claude 对仓库状态的判断
.worktreeinclude 比手动拷贝 .env 更可靠——每次新建 worktree 自动同步，不会因为忘了复制而让 Claude 跑不起项目
-p 模式的 worktree 必须手动清理——CI/CD 脚本里跑完记得加 git worktree remove，否则会积累大量孤立目录
子 Agent frontmatter 加 isolation: worktree，而不是每次口头提醒——永久配置比临时口头约束更可靠，Agent 复用时也不会忘