# 工作流：用 git worktree 并行开发

> 用 claude --worktree 为每个任务创建独立检出和分支，让多个会话同时开发互不覆盖，并说明依赖安装、环境文件、清理和基线分支的注意点。

## 适用场景

一个终端里 Claude 正在做新功能，另一个紧急 bug 又来了。如果两个会话在同一份工作目录里改文件，改动会互相覆盖，分支也会搞混。

git worktree 让同一个仓库同时拥有多个独立的工作目录，每个目录一个分支，共享同一份 Git 历史和远端。Claude Code 把这件事做成了一个命令行参数，每个会话在自己的目录里工作，互不干扰。

## 模板

```bash
# 前提：仓库至少有一次提交；首次在该目录运行过 claude 并接受了信任提示

# 一次性：把 worktree 目录排除出版本控制
echo ".claude/worktrees/" >> .gitignore

# 终端 A：开发新功能（默认创建 .claude/worktrees/feature-auth/，分支 worktree-feature-auth）
claude --worktree feature-auth

# 终端 B：同时修一个 bug，名字不同就是另一个独立会话
claude -w bugfix-login

# 想基于某个 PR 的代码继续（引号避免 # 被 shell 当成注释）
claude --worktree "#1234"

# 退出后想回到保留下来的 worktree 会话
claude --worktree feature-auth --resume

# 不用 Claude 的参数，手动管理也行
git worktree add ../myproj-feature-a -b feature-a
git worktree list
git worktree remove ../myproj-feature-a
```

需要把被忽略的本地文件（如 `.env`）带进每个新 worktree，在仓库根目录创建 `.worktreeinclude`，语法同 `.gitignore`：

```text
.env
.env.local
config/secrets.json
```

## 怎么用 / 怎么改

1. **每个 worktree 是全新检出。** 依赖没装、构建产物没有。让 Claude 在里面执行安装命令，或者把初始化步骤写进项目的 CLAUDE.md。
2. **`.worktreeinclude` 只复制既匹配、又被 gitignore 的文件。** 已跟踪的文件不会被重复复制。
3. **基线分支是哪一个。** 默认从远端的默认分支（通常是 main）切出，也就是「fresh」，不带你当前本地未推送的提交。想基于当前 HEAD 分出去，在设置里写 `"worktree": { "baseRef": "head" }`。注意这个设置不能写成某个分支名；要从指定分支开始，用 `git worktree add` 手动创建。
4. **子智能体也能隔离。** 对 Claude 说「让子智能体用 worktree」，或在自定义子智能体的 frontmatter 里加 `isolation: worktree`，并行编辑就不会冲突。
5. **想一屏看多个会话。** 官方还提供了后台智能体视图（运行 `claude agents`），属于研究预览功能，细节以文档为准。

## 常见问题或注意事项

- **退出时的清理逻辑。** 工作区干净的未命名会话，worktree 和分支会被自动删除；有改动时会询问你保留还是删除，删除会连同其中的工作一起丢掉。命名过的会话即使干净也会先问你。用 `-p` 的非交互运行不会自动清理，需要手动 `git worktree remove`。
- **别把它当 git 分支的替代。** 保留 worktree 的目的是继续工作；合并后记得清理，避免磁盘里堆积很多目录。
- **审批规则是共享的。** 在 worktree 里选择「是，且不再询问」保存的 Bash 规则，会写入主检出目录的 `.claude/settings.local.json`，对主目录和其他 worktree 都生效。
- **hook 的路径变量不跟随。** 进入 worktree 后，`${CLAUDE_PROJECT_DIR}` 仍指向启动会话的项目根目录，hook 想拿到当前 worktree 路径，要读输入 JSON 里的 `cwd`。
- **Git LFS 文件可能只是指针。** 如果用了 `git lfs install --local`，新 worktree 里需要手动执行 `git lfs pull`。
- **隔离只管文件，不管语义冲突。** 两个会话改了同一个函数的不同部分，合并时仍要你来处理。合并前让评审会话看一遍整体 diff。