Claude Code原生Git Worktree实战：用子代理隔离并行开发任务

1. 并行开发踩过的坑为什么单分支跑多个子代理一定会冲突如果你正在用 Claude Code 做多任务开发大概率遇到过这种场景一个会话里让 Claude 同时改登录模块、加暗黑模式、顺手修一个支付回调的 bug。前十分钟看起来一切顺利等到要提交的时候发现三个功能的改动全缠在同一个分支上git diff里几百行混在一起想单独回滚其中一个功能都做不到。更糟的是只要其中一个功能有编译错误整个分支就被卡住另外两个本来能跑的功能也一起被拖下水。这个问题的本质不是 Claude 不够聪明而是工作目录只有一个。所有子代理共享同一份文件系统、同一个 HEAD、同一个暂存区。Claude Code 的子代理机制本身是支持并行的但如果没有隔离层多个代理写同一个文件时后写的会覆盖先写的Git 索引也会互相干扰。我试过在一个会话里让三个子代理分别处理三个 feature结果两个代理同时改了package.json合并的时候依赖版本直接对不上。Git Worktree 就是为解决这个问题设计的。它不是克隆一个新仓库而是在同一个.git对象库之上挂载多个独立的工作目录。每个 worktree 有自己的分支、自己的 HEAD、自己的工作文件但它们共享同一份提交历史和对象存储。打个比方主项目是你的办公桌worktree 就是同一间办公室里加的第二张、第三张桌子——每张桌子上有自己的纸和笔但文件柜是同一个。对 Claude Code 来说这意味着每个子代理可以在自己的 worktree 里独立改文件、独立提交、独立跑测试互不干扰。Claude Code 从 v2.1.50 开始原生支持 worktree通过--worktree标志就能启动。它把原本需要手动git worktree add、切目录、起会话的流程压缩成一条命令并且子代理配置里加一行isolation: worktree就能自动隔离。这篇内容会从零演示怎么创建 worktree、怎么把子代理绑定到独立 worktree、怎么验证并行任务真的没有互相踩脚以及踩过的几个典型报错怎么排查。适合正在用 Claude Code 做多 feature 并行、或者团队里多人多代理协作的开发者。2. 前置准备TaoToken 接入与 Claude Code 环境检查在动 worktree 之前得先把 Claude Code 的模型通道跑通。我这边用的是 TaoToken 的 API 接入Base URL 指向https://taotoken.net/api模型 ID 按你订阅的套餐选比如claude-sonnet-4-6这类。如果你还没配先拿到 API Key再写进 Claude Code 的配置里。Claude Code 读取配置的位置通常是项目级.claude/settings.json或用户级~/.claude/settings.json。我建议项目级配置这样团队里每个人拉下来就能用同一套通道。配置片段长这样{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-6 } }注意ANTHROPIC_BASE_URL后面不要带斜杠也不要加/v1Claude Code 会自己拼路径。Key 从 TaoToken 控制台的 API Keys 页面生成生成后只显示一次记得存好。模型 ID 要和你订阅的套餐匹配写错了会报 404 或者 model not found。配完之后验证一下环境。先确认 Claude Code 版本claude --version如果低于 v2.1.50跑claude update升级。然后确认你的项目已经初始化 Git 并且主分支至少有一个提交git log --oneline如果这条命令报fatal: your current branch main does not have any commits yet说明你还没提交过先git add . git commit -m init做一个初始提交。worktree 依赖 Git 对象库没有提交就没法创建。再检查一下当前有没有残留的 worktreegit worktree list正常应该只看到主工作目录一行。如果之前手动创建过 worktree 没清理这里会列出来建议先git worktree prune清掉失效记录。最后确认 TaoToken 通道能通。在项目根目录起一个 Claude Code 会话随便问一句claude进入交互后输入你好确认一下模型通道如果能正常回复说明 Base URL、Key、Model ID 三件套都对了。如果报 401检查 Key 有没有复制完整如果报 connection error检查 Base URL 是不是写成了https://taotoken.net/api/带了尾斜杠。这一步跑通再往下否则 worktree 建好了模型调不通也是白搭。3. 可复制配置worktree 创建与子代理绑定这一节是核心操作。我会分三块命令行直接起 worktree、子代理配置里声明 isolation、以及非 Git 项目的钩子方案。3.1 命令行启动 worktree 会话最简单的用法是加--worktree标志简写-wclaude --worktree feature/dark-mode这条命令做三件事在.claude/worktrees/feature-dark-mode/下创建一个新工作目录、签出一个名为feature/dark-mode的新分支、在该目录里启动 Claude 会话。你的主分支完全不受影响。如果不指定名字Claude 会随机生成一个比如dreamy-puzzling-codd。单次用还行同时跑多个的时候随机名根本分不清谁是谁所以强烈建议显式命名。想直接进入 worktree 目录而不是从项目根启动加--dirclaude --worktree feature/dark-mode --dir关闭会话后想恢复再跑一次同样的命令Claude 会拾取该 worktree 的会话上下文claude --worktree feature/dark-mode查看当前所有 worktreegit worktree list输出会列出主工作目录和每个链接 worktree 的路径与分支名。确认无误后就可以在里面干活了。3.2 子代理配置声明 isolation如果你在项目里定义了自定义子代理可以在代理文件头部加isolation: worktree这样每次调用该代理都会自动分配独立 worktree不用手动加标志。在.claude/agents/feature-builder.md里写--- name: feature-builder model: claude-sonnet-4-6 isolation: worktree --- 你是一个功能开发专家。当分配功能时完全构建它编写测试并验证它工作后再完成。始终在小的、集中的提交中工作。这个 frontmatter 里的isolation: worktree是关键。有了它主会话里指示 Claude 启动子代理时每个子代理自动拿到自己的 worktree 和分支。比如你在主会话里说使用 worktree 为你的代理。并行构建 feature/dark-mode、feature/local-storage 和 feature/edit-todos每个都在自己的分支上。确保每个代理在打开 PR 之前测试其更改。Claude 会启动三个子代理各自在独立 worktree 里跑互不阻塞。一个完成了你可以单独审查合并不用等另外两个。3.3 非 Git 项目的钩子方案如果你的项目用 SVN 或 Mercurial没法直接用 Git worktree但可以通过.claude/settings.json里的钩子模拟隔离效果{ hooks: { WorktreeCreate: [ { command: jj workspace add \$(cat /dev/stdin | jq -r .name)\ } ], WorktreeRemove: [ { command: jj workspace forget \$(cat /dev/stdin | jq -r .worktree_path)\ } ] } }这里用jjJujutsu作为例子它本身支持 workspace 概念。WorktreeCreate钩子在 Claude 创建 worktree 时触发WorktreeRemove在删除时触发。命令从 stdin 读 JSON用jq解析出 name 和 worktree_path。你需要把命令换成自己版本控制工具对应的 workspace 操作。注意钩子里的命令要保证幂等重复创建同名 workspace 不能报错中断。另外jq得提前装好cat /dev/stdin在某些 shell 下行为不一致建议在 CI 环境里先测一遍。3.4 清理与 pruneworktree 用完要清理否则.claude/worktrees/下会堆一堆目录。删除单个git worktree remove .claude/worktrees/feature-dark-mode如果有未跟踪的改动想强制删git worktree remove --force .claude/worktrees/feature-dark-mode批量清理失效记录git worktree prune养成合并后 prune 的习惯不然git worktree list会越来越长。4. 验证请求并行子代理真的隔离了吗配置写完得验证。这一节给你一套可跟做的验证步骤确认三个子代理确实在各自 worktree 里跑、文件没串、提交独立。4.1 启动并行任务在主 Claude 会话里输入使用 worktree 为你的代理。并行构建三个功能feature/dark-mode 在 src/theme 下加暗黑模式切换feature/local-storage 在 src/storage 下加本地持久化feature/edit-todos 在 src/todos 下加内联编辑。每个都在自己的分支上完成后各自跑测试。Claude 会启动三个子代理。你可以在另一个终端跑git worktree list应该看到类似输出/path/to/project abc1234 [main] /path/to/project/.claude/worktrees/feature-dark-mode def5678 [feature/dark-mode] /path/to/project/.claude/worktrees/feature-local-storage ghi9012 [feature/local-storage] /path/to/project/.claude/worktrees/feature-edit-todos jkl3456 [feature/edit-todos]三个 worktree 各自签出不同分支路径独立。这就是隔离生效的直接证据。4.2 检查文件隔离进入其中一个 worktree 看文件cd .claude/worktrees/feature-dark-mode ls src/theme你应该只看到暗黑模式相关的改动。再进另一个cd ../feature-local-storage ls src/storage两个目录的文件互不重叠。如果发现某个 worktree 里出现了别的功能的文件说明子代理没绑定到正确 worktree检查isolation: worktree有没有写对。4.3 验证提交独立在每个 worktree 里分别看提交cd .claude/worktrees/feature-dark-mode git log --oneline -3每个 worktree 的提交历史是独立的HEAD 指向各自分支。主分支main上不会有这些提交直到你主动合并。4.4 用 CtrlW 查看会话在任意 Claude Code 会话里按CtrlW会列出项目里所有活动会话包括每个 worktree 对应的会话。你可以在这里快速跳转看每个代理在干什么。这是验证并行状态最直观的方式。4.5 合并与清理三个功能都完成后逐个合并。先切回主目录cd /path/to/project git merge feature/dark-mode git merge feature/local-storage git merge feature/edit-todos因为每个功能改的文件不重叠合并不会冲突。合并完清理 worktreegit worktree remove .claude/worktrees/feature-dark-mode git worktree remove .claude/worktrees/feature-local-storage git worktree remove .claude/worktrees/feature-edit-todos git worktree prune跑一遍git worktree list应该只剩主工作目录。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节列几个我实际踩过的报错和排查路径。每个都给出报错原文、原因、修复命令。5.1 401 Unauthorized报错原文API error: 401 Unauthorized - invalid api key原因通常是 TaoToken 的 Key 没配、配错位置、或者复制时带了空格。检查.claude/settings.json里的ANTHROPIC_API_KEY是否完整。注意 Claude Code 会优先读环境变量如果你 shell 里 export 了一个旧的ANTHROPIC_API_KEY会覆盖配置文件。跑echo $ANTHROPIC_API_KEY如果输出和配置文件不一致在 shell 里 unset 掉或者统一用配置文件。修复后重启 Claude Code 会话。5.2 local proxy failed报错原文Error: local proxy failed to start: listen tcp 127.0.0.1:xxxx: bind: address already in use这是 Claude Code 内部代理端口被占用。常见于上次会话没正常退出端口没释放。先找占用进程lsof -i :端口号杀掉后重试。或者直接换端口在 settings.json 里加{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api } }如果还不行重启终端。这个报错和 worktree 本身无关但并行跑多个会话时端口冲突概率会变高所以列在这里。5.3 reading choices 报错报错原文Error: reading choices: unexpected end of JSON input这是模型返回的响应体不完整通常是网络中断或者 Base URL 指向了一个返回非标准 JSON 的端点。检查ANTHROPIC_BASE_URL是不是https://taotoken.net/api不要写成https://taotoken.net/api/v1或者带尾斜杠。另外确认模型 ID 拼写正确写错模型名有些网关会返回 HTML 错误页而不是 JSON导致解析失败。5.4 OAuth 相关报错报错原文OAuth error: invalid_grant - token expired如果你用的是 OAuth 方式登录而不是 API Keytoken 过期会报这个。Claude Code 里跑claude logout claude login重新走一遍授权。但如果你走的是 TaoToken API Key 通道不应该触发 OAuth 流程。如果同时配了 OAuth 和 API KeyClaude Code 可能优先走 OAuth导致冲突。检查~/.claude/下有没有残留的 credentials 文件有的话删掉强制走 API Key。5.5 worktree 创建失败报错原文fatal: feature/dark-mode is already checked out at /path/to/project/.claude/worktrees/feature-dark-mode同一个分支不能被两个 worktree 同时签出。要么换个分支名要么先删掉旧 worktreegit worktree remove .claude/worktrees/feature-dark-mode如果删不掉提示有未提交改动加--force。删完再重新创建。5.6 子代理没隔离现象三个子代理跑完发现改动全在主分支上worktree 目录是空的。原因通常是子代理配置里isolation: worktree没写或者写在了错误的位置。检查.claude/agents/下每个代理文件的 frontmatter确保isolation: worktree在---之间且没有拼写错误。另外主会话里指示启动子代理时要明确说使用 worktree否则 Claude 可能默认不开隔离。6. 把 worktree 用进日常接入文档与 Coding Planworktree 跑通之后日常开发里几个场景特别适合用。大型代码库迁移时可以给每个文件夹分配一个子代理各自在独立 worktree 里改最后批量开 PR。独立功能并行开发时三个 feature 同时跑谁先完成谁先合并不用互相等。线上 bug 修复时起一个 worktree 专门修 bug另一个 worktree 继续做新功能分支互不污染。代码审查时起一个 worktree 拉 PR 分支不影响你当前的工作目录。如果你还没配 TaoToken 通道接入文档里有完整的 Base URL、Key 获取、模型 ID 对照说明照着配一遍就能跑。想先验证模型对话是否正常可以在控制台里直接发一条测试请求确认返回格式和延迟。长期做编码和 Agent 协作的话Coding Plan 套餐在并发会话和 token 额度上更适合多 worktree 并行场景具体额度对照控制台里的套餐说明。我自己的习惯是每个 feature 一个 worktree命名用feature/xxx或fix/xxx合并后立刻git worktree remove加git worktree prune。子代理配置里统一加isolation: worktree这样主会话里只要说并行构建这几个功能Claude 自动分配隔离环境不用每次手动加标志。跑一段时间后你会发现并行开发的瓶颈从等分支稳定变成了想清楚要拆几个任务这才是多代理协作该有的样子。