太长不看版
- claude --worktree（短写 -w）会让会话直接跑在 .claude/worktrees/<name> 的全新副本里，对应分支叫 worktree-<name>。
- 在别的终端再启动一次就是并行——每个会话只改自己的目录，共享同一套 Git 历史和远端。
- 子代理同样能用 worktree：自然语言说一句就行，或在 .claude/agents/*.md 的 frontmatter 里写 isolation: worktree 一劳永逸。
- 退出时，干净的匿名 worktree 会自动删除，有改动的会询问保留还是删除；成果用普通的 git merge worktree-<name> 合回主线。
Claude Code Worktrees in 7 Minutes
频道：Developers Digest7:10
I'm using claude --worktree for everything now
频道：Matt Pocock7:57
Worktrees — official documentation
官方文档：code.claude.com/docs
本页的每一个 flag、路径和清理行为，都对照官方 worktrees 文档核实过；上面的视频是画面与事实来源，退出时的保留/删除提示和误推 main 的坑都出自实测演示。
截图版权归各自创作者所有，并深链到对应时间点；未使用任何人脸镜头。
Claude Code worktrees 分步走查
第 1 部分 — 跑通第一个隔离会话
- 1
准备一个至少有一次提交的 Git 仓库
worktree 是从已有历史分出来的，所以这个功能要求目录是真正的 Git 仓库。新文件夹里先 git init，建一个文件（演示里就是 touch index.html），再 commit 一下。跳过这步，Claude Code 就没有可分支的起点。
git init 加 touch index.html——只要有一次提交，claude --worktree 就能跑起来。跳到 1:06 观看 - 2
先弄清 worktree 到底是什么
Git worktree 是第二个工作目录：有自己的文件和当前分支，却与主仓库共享同一套历史和远端。和切分支不同，这里不需要 stash——主目录和每个 worktree 同时可用，这正是并行 agent 需要的形态。
一个仓库，多个工作目录：../main、../feature1、../feature2 同时各自停在自己的分支上。跳到 0:30 观看 - 3
用 --worktree 启动 Claude Code
在仓库里运行 claude --worktree（或短写 claude -w）。Claude Code 会在 .claude/worktrees/<name> 建好副本，你没起名字就自动生成一个（比如 bright-tumbling-rabbit），并让会话直接落在副本里。桌面端则是在新建会话时勾选 worktree 选项。
欢迎横幅显示会话工作目录已在 .claude/worktrees 里——从这一刻起，一切都发生在副本中。跳到 1:22 观看 - 4
为第二个任务再开一个会话
在另一个终端再跑一次 claude --worktree。不带名字会得到另一个独立 worktree；两次传同一个名字则会重开同一个 worktree。两个 agent 之所以能同时改同一个项目，就是因为各自只看得到自己的目录。
第 2 部分 — 文件与命令都落在哪
- 5
看看 .claude/worktrees 下的完整副本
用文件管理器打开看：每个 worktree 都是一份完整检出——有自己的 index.html、自己的 .claude/settings.local.json、自己的 git 文件；只有重量级的对象库仍共享在主目录的 .git 里。所以再开一份副本几乎零成本。
磁盘上的两个 worktree——clever-munching-toast 和 spicy-napping-otter——各自带着完整的 git 目录和 index.html。跳到 1:50 观看 - 6
确认命令只在 worktree 内生效
第一个会话用浏览器打开页面时，权限提示里的路径指向 .claude/worktrees/clever-munching-toast，而不是你的主目录。Claude Code 还会阻止子代理直接改主检出，其中有一条命令形态检查关不掉。
批准对话框写明了确切的 worktree 路径——会话一碰不到主目录，只碰自己的副本。跳到 1:42 观看 - 7
给 worktree 命名，或直接从 PR 建副本（可选）
claude --worktree feature-auth 会建一个名字可预期的 worktree，下次传同名会直接重开而不是重复建。也可以传带引号的 PR 编号（claude --worktree "#1234"）或 GitHub/GitLab 的 PR 链接，得到 .claude/worktrees/pr-<number> 的 PR 副本。
第 3 部分 — 并行子代理与清理
- 8
一句话要来带 worktree 隔离的并行子代理
隔离不止于终端。一句"spawn 五个子代理，做五个不同版本，全部用 git worktree 隔离"，Claude Code 就会并行派出 Task agent，各自待在自己的隔离 worktree 里同时改同一个仓库，互不打架。
五个 Task agent 并行启动，每一条都注明跑在各自隔离的 git worktree 里。跳到 2:42 观看 - 9
盯着每个 agent 在自己的车道上跑
任务列表把五个变体的工具调用数和 token 消耗列在一起，不用开五个终端也能掌握进度。子代理的记录不占主线程上下文，调度会话保持轻量，重活全在各自 worktree 里干。
五个子代理同时进行——Variation 1 已在 50.3k token 时完成，其余还在各自 worktree 里读文件。跳到 3:42 观看 - 10
比较各版本，合回赢的那一个
agent 跑完后，Claude Code 会列出每个变体的 .claude/worktrees/agent-<id>/ 路径，浏览器里并排打开就能比较。选中意的用普通 git merge 合它的 worktree 分支（或走 PR）；真有冲突，就按平时 Git 冲突那样解。
汇总列出了每个变体及其 .claude/worktrees 路径，右侧同时打开了一个渲染结果。跳到 4:22 观看 - 11
把隔离固化成可复用的子代理
想让隔离成为默认行为，直接说："建一个 front-end developer 子代理，模型用 Haiku，并让它启用 worktree 隔离。"Claude Code 会先查自己的 agent 文档，然后在 .claude/agents/ 下写出新文件。
自然语言就够了——写文件前，Claude Code 先查了自己关于自定义 agent 格式的文档。跳到 5:42 观看 - 12
检查 frontmatter 里的 isolation: worktree
生成的 frontend-dev.md 带着 name、description、model: haiku、工具白名单，以及最关键的一行 isolation: worktree。此后这个子代理每次运行都在临时 worktree 里，若结束时没有改动，worktree 会被自动移除。
frontmatter 第 8 行的 isolation: worktree，就是这个子代理每次都有独立 worktree 的原因。跳到 6:42 观看 - 13
合并完，清理交给 Claude
退出会话时，Claude Code 会检查 worktree：干净的匿名 worktree 自动删除；有内容的会问你保留还是删除——选保留会给出 claude --worktree <name> --resume 命令方便下次接着干。无头 -p 运行从不自动清理，这类要手动 git worktree remove。
Claude Code worktrees 与手动 git worktree add 的差别
worktree 在 Git 里存在多年了——新鲜的是 Claude Code 把整个生命周期管了起来。真正有差别的五点：
- 1创建方式：手动要 git worktree add ../project-feature -b feature、cd 进去、再启动 Claude；claude --worktree 一步到位，会话直接落在 .claude/worktrees/<name> 里，名字自动生成或你指定。
- 2起点选择：worktree.baseRef 控制从哪分叉——fresh（默认）从远端默认分支起；head 会带上你还没 push 的本地提交。flag 不能指定任意分支，官方文档明说这种情况要用手动 git worktree add。
- 3点文件：项目根目录的 .worktreeinclude 文件（.gitignore 语法）会把 .env 这类被忽略的文件复制进每个新 worktree；手动建的 worktree 没有这个待遇。
- 4清理：退出时 Claude Code 会检查 worktree，干净的匿名副本自动删，有进度的先问你，还会定期清扫被遗弃的子代理 worktree；手动建的完全靠你自己负责。
- 5护栏：隔离检查会拦住子代理改主检出的尝试，resume 会把会话送回它的 worktree；裸的 git worktree add 没有这些保护。
底子里它还是普通 Git：VS Code 的源代码管理面板会逐个列出 worktree 和各自改动，合并就是常规 git merge，手动建的与 Claude 建的 worktree 也能在同一个仓库里共存——按任务挑工具即可。
worktree 不听话时
大部分坑其实是 Git 基本功浮出水面，不是功能本身的 bug。这五个几乎覆盖所有常见问题：
- 1push 推到了 main。新建的 worktree 分支会跟踪远端默认分支，不带分支名的 git push 可能直接推上 main。请显式 git push origin worktree-<name>，并给 main 加分支保护。
- 2文件或工具缺失。被 gitignore 的文件（.env、vendor 目录）和仓库本地过滤器（如 LFS）不会自动进新 worktree。把它们写进 .worktreeinclude，或在 worktree 里手动跑 git lfs pull 和初始化命令。
- 3启动报 trust 错误。在未信任目录里 claude --worktree 会报错并提示先接受工作区信任——同意后重跑即可（非交互的 -p 会跳过这项检查）。
- 4两个 worktree 在合并时冲突。如果两个任务改了同一个文件——routes、侧边栏、package.json——合并时照样要解冲突。worktree 消除的是过程中的互相干扰，不是需求上的重叠。
- 5无头运行留下残骸。-p 运行从不自我清理；用 git worktree remove 手动删（被锁的先 git worktree unlock）。
把会话正在用的 worktree 删掉也不致命：下次 resume 会退回启动目录，绑定自动解除，会话本身不会坏。