第6章 Worktree 与隔离环境

创建安全的沙盒环境,放心让 AI 大胆改代码,不影响你的主工作区

6.1 什么是 Worktree?

Git Worktree 是 Git 的一个功能,让你可以同时 checkout 同一个仓库的不同分支到不同目录

Claude Code 的 Worktree 功能就是在 Git Worktree 基础上加了一层封装,让 AI 在隔离的副本中工作。

主工作区 (/home/you/project)
  └── 你正在写的代码,干干净净

Worktree 副本 (.claude/worktrees/ai-sandbox/)
  └── AI 在这里大改特改,不影响主工作区

6.2 为什么要用 Worktree?

和 AI 协作时,最大的心理障碍是:「万一它改坏了怎么办?」

Worktree 解决了这个问题:

6.3 使用 Worktree 的两种方式

方式一:手动 Git Worktree(适合老手)

# 创建一个新的 worktree
git worktree add ../ai-experiment -b experiment-ai

# Claude 在这个目录中工作
cd ../ai-experiment
claude

# 如果结果满意,合并回来
git merge experiment-ai

# 清理
git worktree remove ../ai-experiment
git branch -d experiment-ai

方式二:Claude Code 内置 Worktree(推荐)

# 在 Claude Code 对话中直接说:
"开启一个 worktree,我想让你在一个隔离环境中做实验"

# Claude 会自动调用 EnterWorktree 创建隔离环境
# 你会在通知中看到新的 worktree 路径
# 完成实验后,满意就合并,不满意就删掉
内置 Worktree 的优势:Claude 知道自己在 worktree 中,会自动调整行为——比如不改动原项目的配置文件。

6.4 实践:在 Worktree 中做实验性重构

练习 1:安全的实验环境

假设你想让 AI 尝试重构一个复杂模块,但不确定结果如何:

# 在 Claude Code 中:
"请创建一个 worktree,然后在其中重构 src/services/payment.ts。
把回调风格改成 async/await,但别动主工作区的代码。
完成后告诉我改了什么,我来审查。"

Claude 会:

  1. 创建一个 worktree
  2. 在其中重构代码
  3. 列出改动摘要
  4. 等你确认后再决定是否合并

6.5 worktree 的生命周期

阶段操作说明
创建EnterWorktree基于当前 HEAD 创建隔离副本
工作正常使用 Claude Code所有改动在 worktree 中
保留ExitWorktree(action="keep")退出 worktree,保留改动
清理ExitWorktree(action="remove")退出 worktree,删除所有改动
合并git merge worktree-branch手动将改动合并回主分支
重要:worktree 中未提交的改动在 remove 时会丢失。discard_changes=true 会强制删除。确认要丢弃前检查好。

6.6 Worktree 的典型使用场景

  1. 实验性重构:不确定 AI 的方案好不好→在 worktree 中试试看
  2. 多任务并行:一个 worktree 修 bug,一个 worktree 写新功能
  3. 代码审查:在 worktree 中看 PR 代码,随便改不污染本地
  4. 学习探索:让 AI 在 worktree 中随意探索代码库结构
  5. 依赖升级:在隔离环境升级依赖,测试通过再合并

6.7 实践:多 worktree 并行开发

练习 2:同时做两件事

# 在 Claude Code 对话中:
"帮我做两件事,分别在独立的 worktree 中:

Worktree A:修复 src/auth/login.ts 中的 token 过期处理 bug
Worktree B:给 src/api/users.ts 添加分页查询参数支持

两个任务并行进行,完成后分别告诉我改了什么"

两个 worktree 互不干扰,可以并行工作。

6.8 Worktree + 子代理:最强组合

把 worktree 和子代理结合起来,威力翻倍:

"帮我用子代理并行探索三个不同的重构方案,每个子代理在
独立的 worktree 中工作。完成后对比三个方案的结果。"

这个组合让你可以实现「多方案并行实验」

6.9 常见问题

Q: Worktree 占用多少磁盘空间?

很小。Git 使用硬链接和共享对象库,worktree 只额外存储工作目录的文件,通常几十 MB。

Q: 能同时创建多少个 worktree?

没有硬性限制。但每个 worktree 占一个分支名,注意分支命名不要冲突。