一次让两个 Claude Code 会话同时工作，各自在独立分支上修改文件，互不干扰——这就是 Worktrees 的核心价值。本文是官方 Worktrees 文档的完整中文整理，覆盖 --worktree 标志、基础分支配置、.worktreeinclude、Subagent 隔离、清理和手动管理的每个细节。
什么是 Worktree？
Git Worktree 是一个独立的工作目录，有自己的文件和分支，但与主检出共享同一个 Repository 历史和远端。
在 Claude Code 语境里的价值：在一个终端里让 Claude 开发新功能，同时在另一个终端里让 Claude 修复 Bug——两个会话编辑不同分支上的文件，没有冲突。
主检出（main） Worktree A Worktree B
├── src/ .claude/worktrees/ .claude/worktrees/
│ ├── app.ts feature-auth/ bugfix-123/
│ └── auth.ts ├── src/ ├── src/
│ │ ├── app.ts │ ├── app.ts
│ │ └── auth.ts │ └── auth.ts
└── (branch: worktree- └── (branch: worktree-
feature-auth) bugfix-123)
Desktop App 的行为：Desktop App 为每个新会话自动创建 Worktree，无需手动配置。
并行方式对比：
| 方式 | 隔离级别 | 适用场景 |
|---|---|---|
| Worktrees | 文件系统隔离（不同分支） | 同时处理多个功能/Bug |
| Subagents | 上下文隔离（独立会话） | 主会话委托子任务 |
| Agent teams | 跨会话协调 | 协调多个 Claude 实例 |
三者可以组合使用：Worktrees 负责文件隔离，Subagents 负责任务委托。
启动 Worktree 会话
基本用法
# 创建命名 Worktree，在其中启动 Claude
claude --worktree feature-auth默认在 .claude/worktrees/feature-auth/ 创建 Worktree，分支名为 worktree-feature-auth。
短标志：-w 等同于 --worktree
# 在另一个终端启动第二个并行会话
claude --worktree bugfix-123省略名称（自动生成）：
claude --worktree
# 自动生成名称，如 bright-running-fox在会话内启动：也可以在会话中告诉 Claude "在 worktree 里工作"，Claude 会使用 EnterWorktree 工具自动创建。
首次使用注意：在一个目录里第一次使用 --worktree 之前，必须先运行一次 claude（接受工作区信任对话框）。否则 --worktree 会报错并提示运行 claude 。
.gitignore 设置：把 .claude/worktrees/ 添加到 .gitignore，避免 Worktree 内容显示为主检出的未追踪文件。
选择基础分支
Worktree 默认从 origin/HEAD（远端默认分支）创建，确保从干净的远端状态开始。如果没有配置远端或获取失败，回退到本地 HEAD。
始终从本地 HEAD 分支（适合需要包含未推送提交的场景）：
// settings.json
{
"worktree": {
"baseRef": "head"
}
}只接受 "fresh"（默认，从远端）或 "head"（从本地 HEAD）。
从特定 PR 创建 Worktree（Week 19 新增）：
# 传入 PR 号（# 前缀）
claude --worktree "#1234"
# 或完整 GitHub PR URL
claude --worktree "https://github.com/org/repo/pull/1234"Claude Code 从 origin 获取 pull/1234/head，在 .claude/worktrees/pr-1234/ 创建 Worktree。
完全自定义：配置 WorktreeCreate Hook 替换默认的 git worktree 逻辑，实现任意创建行为。
.worktreeinclude：复制被 Gitignore 的文件
Worktree 是全新检出，所以主检出里的 .env、.env.local 等未追踪文件不会出现。使用 .worktreeinclude 文件自动复制它们。
创建 .worktreeinclude 文件（项目根目录）：
# .worktreeinclude
# 语法同 .gitignore
.env
.env.local
config/secrets.json
规则：只复制同时满足"匹配 .worktreeinclude 模式"且"被 .gitignore 忽略"的文件。已追踪的文件不会被复制。
影响范围：--worktree 创建的 Worktree、Subagent Worktree、Desktop App 的并行会话——全部生效。
在 Subagent 里使用 Worktree 隔离
让 Subagent 在各自的 Worktree 里运行，避免并行编辑冲突。
临时启用：在会话中告诉 Claude "为你的 Agent 使用 Worktree"。
永久启用（在自定义 Subagent 定义里）：
---
name: my-parallel-agent
description: 并行工作的独立 Agent
isolation: worktree
---
你的任务：实现...isolation: worktree 让每个 Subagent 获得独立的临时 Worktree。Subagent 完成且没有变更时，自动删除该 Worktree。
清理 Worktree
退出 Worktree 会话时，清理行为取决于是否有变更：
| 状态 | 清理行为 |
|---|---|
| 无未提交变更 + 无未追踪文件 + 无新 commit | 自动删除 Worktree 和分支（如果会话有名称则先询问） |
| 有未提交变更、未追踪文件或新 commit | 询问：保留或删除。保留：目录和分支留下，可以回来继续。删除：丢弃所有内容 |
非交互模式（--worktree + -p） | 不自动清理，需手动 git worktree remove |
崩溃/中断后的孤立 Worktree：
启动时自动清理超过 cleanupPeriodDays 设置天数的孤立 Subagent Worktree（前提是没有未提交变更/未追踪文件/未推送 commit）。
--worktree 手动创建的 Worktree 不在自动清理范围内。
手动管理 Worktree
需要更精确控制 Worktree 位置或分支时，直接用 Git 操作：
# 创建新分支的 Worktree
git worktree add ../project-feature-a -b feature-a
# 从已有分支创建 Worktree
git worktree add ../project-bugfix bugfix-123
# 在 Worktree 里启动 Claude
cd ../project-feature-a && claude
# 列出所有 Worktree
git worktree list
# 完成后删除
git worktree remove ../project-feature-a重要：每个新 Worktree 都是全新检出，记得初始化开发环境（安装依赖、设置虚拟环境等）。
非 Git VCS 支持
默认行为依赖 Git。对于 SVN、Perforce、Mercurial 等，配置 WorktreeCreate 和 WorktreeRemove Hook 提供自定义逻辑。
SVN 示例（WorktreeCreate Hook）：
{
"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 名称，检出 SVN 工作副本，打印目录路径供 Claude Code 用作工作目录。
注意：使用 WorktreeCreate Hook 时，.worktreeinclude 不会被处理（Hook 替换了默认 Git 行为）。在 Hook 脚本里手动复制本地配置文件。
实战并行工作流
工作流 1：新功能 + Bug 修复同时进行
# 终端 1：开发新特性
claude --worktree feature-payment
> 实现完整的支付模块，包含 Stripe 集成和测试
# 终端 2：同时修复 Bug
claude --worktree bugfix-login-timeout
> 修复用户反映的登录超时问题，根本原因在 auth.ts
# 两个 Claude 会话完全独立，文件不冲突
# 完成后各自创建 PR，再合并到 main工作流 2：代码审查 + 实现同时进行
# 终端 1：审查当前 PR
claude --worktree "#234"
> /review 审查这个 PR，找出安全和性能问题
# 终端 2：同时继续开发新特性
claude --worktree feature-notification
> 实现通知系统的后端部分工作流 3：测试隔离（最常用）
# 主会话：正常开发
claude
> 给 auth 模块添加 OAuth2 支持
# 隔离会话：跑全量测试，不污染主会话
claude --worktree test-run -p "运行完整测试套件并报告结果"
# -p 非交互模式，测试完自动退出
# 不会因为测试输出污染主会话的上下文常见问题
Q：Worktree 里的 CLAUDE.md 有效吗？
A：有效。Worktree 有独立的文件系统，Claude Code 在 Worktree 目录里正常发现并加载 CLAUDE.md。
Q：.env 文件会在 Worktree 里有吗？
A：使用 .worktreeinclude 文件可以自动复制。或者在 Worktree 创建后手动 cp .env .claude/worktrees/my-tree/.env。
Q：Worktree 会消耗额外 Token 吗？
A：每个 Worktree 会话有独立的上下文窗口，和普通会话一样消耗 Token。
Q：baseRef: head 和 baseRef: fresh 区别？
A：fresh（默认）从远端 origin/HEAD 创建，你本地未推送的 commit 不会进入 Worktree。head 从本地 HEAD 创建，本地 commit 会带进去。Subagent 需要基于当前进行中的工作时，用 head。
来源：Claude Code 官方文档 - Run parallel sessions with worktrees | 整理：ClaudeEagle