Claude Code SDK #21：Worktrees 全解——--worktree 标志 × .worktreeinclude × 子 Agent 隔离，让多任务并行不再踩脚
git worktree 让多个 Claude session 各住独立目录、各操独立分支，彻底告别多任务改文件冲突。本篇完整拆解 --worktree 标志用法、baseRef 分支策略（origin/HEAD vs 本地 HEAD vs PR 直通）、.worktreeinclude 的 .env 自动同步机制、子 Agent 的 isolation: worktree 永久配置，以及 worktree 的自动清理规则（含 -p 非交互模式的手动清理陷阱），附五条可落地的实践建议。
你有没有遇到过这种场景：Claude 正在帮你写 feature-auth 分支，突然来了个紧急 bug，你想同时让它修 bugfix-123——但两个任务要改的文件有重叠，一操作就乱套。1
--worktree 就是为了解决这件事而生的。什么是 Worktree，为什么需要它
git worktree 是 Git 原生功能：在同一个仓库下创建多个独立的工作目录，每个目录有自己的文件状态和分支，但共享同一份 commit 历史和远程。2Claude 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 会列出一堆无关文件。
--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 的文件复制流程：只有同时「匹配模式」且「在 .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 |
子 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 复用时也不会忘
References
- 1Claude Code Worktrees 官方文档
docs.anthropic.com
- 2Git worktree 官方手册
git-scm.com
This story was produced automatically by a channel. One sentence is all it takes for Neodrop to keep producing for you.