Claude Code Worktree 实战：一个仓库同时跑多个 AI 任务的正确姿势

你有没有遇到过这种情况：

• 让 Claude 改一个功能改到一半，突然要修一个线上 bug，只能 stash 或者硬着头皮 commit 一堆半成品
• 想同时让 Claude 做两件事——一个写新功能，一个补测试——但两个会话操作同一份代码，改着改着就冲突了
• 想做一次大胆的实验性重构，又怕搞砸了回不去

这些问题的本质是：一个工作目录只能承载一个进行中的任务。你切分支可以隔离 Git 记录，但文件系统只有一份，两个 Claude 会话还是会踩到同一块地盘。

Claude Code 的 --worktree（简写 -w）模式就是为解决这个问题而生的。它把 Git Worktree 的能力直接集成进了 Claude Code，让你用一条命令就能在隔离的工作目录中启动新的 Claude 会话。

一、Git Worktree 基础：一个仓库，多个工作目录

在讲 Claude Code 的 worktree 模式之前，先快速理解 Git Worktree 本身。如果你已经熟悉这个概念，可以直接跳到下一节。

1.1 传统工作流的痛点

通常一个 Git 仓库对应一个工作目录。当你需要在不同分支间切换时：

# 正在 feature-a 上开发，突然要修 bug
git stash                    # 先存起来
git checkout hotfix-branch   # 切过去
# ... 修完 bug ...
git checkout feature-a       # 切回来
git stash pop                # 恢复之前的工作

这个流程有几个问题：stash 容易忘记 pop、切换分支可能导致 node_modules 等依赖需要重新安装、而且全程你只能做一件事。

1.2 Git Worktree 的解法

Git Worktree 允许你从同一个仓库检出多个工作目录，每个目录对应一个独立分支，但共享底层的 .git 仓库数据：

# 在当前仓库旁边创建一个新的工作目录
git worktree add ../project-hotfix -b hotfix-branch

# 现在你有两个目录，各自独立
# /project/           -> feature-a 分支
# /project-hotfix/    -> hotfix-branch 分支

两个目录拥有各自独立的文件状态，互不影响。你可以在一个目录里写代码，同时在另一个目录里跑测试，不用 stash，不用切分支。

1.3 核心命令速查

理解了这个基础，Claude Code 的 worktree 模式就很好懂了——它帮你自动完成了上面这些操作，并加上了会话管理。

二、Claude Code –worktree 模式详解

2.1 基本用法

最简单的方式，给 worktree 指定一个名字：

# 创建名为 "feature-auth" 的 worktree 并启动 Claude
claude -w feature-auth

这条命令会：

1. 在 <仓库根目录>/.claude/worktrees/feature-auth/ 创建一个新的工作目录
2. 从默认远程分支（通常是 main）新建一个名为 worktree-feature-auth 的分支
3. 在这个隔离的工作目录中启动 Claude Code 会话

如果你懒得起名字，也可以让 Claude 自动生成一个：

# 自动生成随机名称，比如 "bright-running-fox"
claude -w

2.2 在会话中创建 Worktree

你也可以在一个已启动的 Claude Code 会话中，通过自然语言让 Claude 创建 worktree：

> 在一个新的 worktree 里帮我做这个功能
> start a worktree for this task

Claude 会自动处理 worktree 的创建并切换到隔离环境中工作。

2.3 目录结构

所有通过 claude -w 创建的 worktree 都存放在统一的位置：

my-project/
├── .claude/
│   └── worktrees/
│       ├── feature-auth/      # worktree: feature-auth
│       │   ├── src/
│       │   ├── package.json
│       │   └── ...            # 完整的项目文件副本
│       └── bugfix-123/        # worktree: bugfix-123
│           ├── src/
│           ├── package.json
│           └── ...
├── src/                       # 主工作目录
├── package.json
└── ...

建议在 .gitignore 中添加以下规则，避免 worktree 内容出现在主仓库的 git status 中：

.claude/worktrees/

2.4 自动清理机制

退出 worktree 会话时，Claude Code 会根据是否有变更来决定如何处理：

• 没有任何改动：自动删除 worktree 和对应的分支，干干净净
• 有未提交的改动或已提交的 commit：Claude 会提示你选择保留还是删除。保留则目录和分支都在，下次可以通过 --resume 继续；删除则清理一切，包括未提交的改动和已有的 commit

这个设计非常合理——实验性改动如果没价值就自动回收，有价值的工作不会被误删。

2.5 手动管理 Worktree

如果你需要更精细的控制，比如把 worktree 放在仓库外面，或者检出一个已有的远程分支，可以用 Git 原生命令：

# 在仓库外创建 worktree
git worktree add ../project-feature-a -b feature-a

# 检出已有的远程分支
git worktree add ../project-bugfix bugfix-123

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

# 用完后清理
git worktree remove ../project-feature-a

三、实战场景

场景一：并行开发多个功能

这是最典型的场景。你手头有两个独立的任务，想让 Claude 同时做：

# 终端 1：让 Claude 写用户认证模块
claude -w feature-auth
> 帮我实现 OAuth2 登录功能，参考现有的 auth 模块

# 终端 2：让 Claude 优化数据库查询
claude -w optimize-queries
> 分析 src/db/queries.ts 中的 N+1 查询问题并修复

两个 Claude 会话各自在独立的文件系统中工作，互相看不到对方的改动，不会出现代码冲突。

场景二：实验性重构

想尝试一个激进的架构改动，但不确定效果？

# 在 worktree 里大胆实验
claude -w experiment-new-arch
> 把现有的 MVC 架构重构为事件驱动架构，先从 order 模块开始

实验成功了，把改动合并回主分支。失败了，退出时选择删除，一切回到原样。主工作目录全程不受影响。

场景三：代码审查与修复

收到一个 PR 需要审查，同时不想打断当前的开发工作：

# 在 worktree 里审查和修复 PR
claude -w review-pr-456
> 审查 PR #456 的改动，检查安全问题和性能隐患

# 主目录继续你手头的开发

场景四：多实例协作模式

一些团队采用"规划者 + 执行者"的双 Claude 协作模式：

• Claude A（主目录）：负责代码分析、方案设计、任务拆分
• Claude B（worktree）：负责具体的代码实现

这种模式下，规划者在主目录里读代码、出方案，执行者在 worktree 里按方案写代码，两者上下文完全隔离，不会互相污染。关于多 Agent 协作的更多玩法，可以参考Claude 多 Agent 协作实践。

四、使用技巧和最佳实践

4.1 命名规范

给 worktree 起个有意义的名字，方便在 /resume 会话列表中快速识别：

# 好的命名：一看就知道在做什么
claude -w feat-oauth-login
claude -w fix-memory-leak
claude -w refactor-db-layer

# 不好的命名
claude -w test1
claude -w tmp

4.2 记得安装依赖

新的 worktree 拥有完整的项目文件，但 node_modules、虚拟环境等不在 Git 管理范围内的东西需要重新安装：

# 启动 worktree 后，先让 Claude 安装依赖
> 先运行 npm install，然后再开始开发

或者在 CLAUDE.md 中加一条规则：

## Worktree 规范
- 在新的 worktree 中开始工作前，先运行 `npm install` 安装依赖

4.3 环境变量处理

.env 文件通常在 .gitignore 中，所以新 worktree 不会自动包含。两种解决方案：

方案 A：手动复制

cp .env .claude/worktrees/feature-auth/.env

方案 B：在启动时告诉 Claude

> 先把根目录的 .env 文件复制到当前目录，然后开始工作

4.4 及时清理

养成用完就清理的习惯。长期积累的 worktree 不仅占磁盘空间，还会让 git worktree list 输出变得混乱：

# 查看当前所有 worktree
git worktree list

# 手动清理不用的 worktree
git worktree remove .claude/worktrees/old-feature

4.5 结合 –resume 使用

Worktree 中的 Claude 会话和普通会话一样，支持通过 /resume 或 --resume 恢复。会话选择器会显示同一 Git 仓库下所有 worktree 的会话，方便你在不同任务间切换。

五、Worktree 模式 vs 直接切分支

简单结论：如果你只是顺序处理任务（做完一个再做下一个），切分支就够了。如果你想让多个 Claude 会话同时干活，或者想做无风险的实验，worktree 是更好的选择。

六、实战案例：团队如何用 Worktree 提速

incident.io 团队分享了他们使用 Claude Code + Git Worktree 的经验：

• 效率提升显著：一个 JavaScript 编辑器功能增强，原本预估 2 小时，用 worktree 并行开发只花了 10 分钟
• 4-5 个 Claude 实例并行：团队成员日常同时运行 4-5 个 Claude 会话，每个在独立的 worktree 中
• 搭配 Plan Mode：在执行前先用 Plan Mode 审查方案，让并行开发更安全可控
• 渐进式采用：从实验性使用到全面推广，用了大约四个月时间

他们封装了一个简单的 bash 函数 w，进一步降低使用门槛：

# 一行命令：创建 worktree + 启动 Claude
w myproject new-feature claude

这个案例说明，worktree 模式不仅适合个人开发者，在团队协作中同样能发挥很大价值。

七、FAQ

Q1：Worktree 和 git clone 有什么区别？

Worktree 共享同一个 .git 仓库，不需要重新下载代码，创建速度更快，分支操作也更直接。Clone 是完全独立的仓库副本，适合需要完全隔离的场景（比如不同的远程配置）。

Q2：能在 worktree 里提交代码吗？

可以。Worktree 里的 commit 和在主目录里提交完全一样，会反映在同一个仓库的 Git 历史中。你可以在 worktree 里提交、推送、创建 PR。

Q3：两个 worktree 能在同一个分支上吗？

不能。Git 不允许两个 worktree 同时检出同一个分支。这也是为什么 claude -w feature-auth 会自动创建一个新分支 worktree-feature-auth。

Q4：worktree 里的改动怎么合回主分支？

和普通分支一样，通过 merge 或 rebase：

# 在主目录里
git merge worktree-feature-auth
# 或者创建 PR

Q5：Worktree 占的磁盘空间大吗？

Worktree 只复制工作文件，不复制 .git 目录（所有 worktree 共享同一个）。实际占用约等于项目源码大小。但如果你对每个 worktree 都执行 npm install，依赖目录会额外占空间。

Q6：退出 Claude 后 worktree 还在吗？

取决于是否有改动。无改动时自动清理；有改动时 Claude 会询问你是否保留。手动清理可以用 git worktree remove <path>。

Q7：能和 Hooks 配合使用吗？

可以。Hooks 配置对 worktree 中的 Claude 会话同样生效。比如你在 Hooks 配置 中设置了自动格式化或文件保护规则，这些规则在 worktree 会话中也会自动执行。

总结

Claude Code 的 --worktree 模式把 Git Worktree 的隔离能力和 AI 编程工作流无缝结合。核心价值就一句话：让你在同一个仓库里安全地并行多个 AI 任务。

要点回顾：

1. claude -w <name> 一条命令搞定 worktree 创建和 Claude 启动
2. Worktree 存放在 .claude/worktrees/ 下，记得加到 .gitignore
3. 退出时自动清理无改动的 worktree，有改动的会提示你选择
4. 适合并行开发、实验性修改、代码审查等需要隔离环境的场景
5. 手动管理用 git worktree add/remove，精细控制用 Git 原生命令

如果你还在用一个终端、一个目录、一个 Claude 会话串行工作，不妨试试 worktree 模式。当你看到两三个 Claude 同时在不同任务上推进时，就回不去了。

相关阅读：

• Claude Code Hooks 实战指南 – 用 Hooks 让 AI 自动守规矩
• Claude Code vs Codex CLI 深度对比 – 两大 AI 编程工具的全方位对决
• Claude 多 Agent 协作实践 – 多 Claude 实例的协作模式
• Claude Code 浏览器自动化实战 – 用 Claude Code 驱动浏览器测试