本教程面向需要在同一仓库中同时运行多个Claude Code会话的开发者。你将掌握Git Worktree的核心原理、Claude Code原生--worktree标志的用法、Agent View多会话管理、以及parallel-code多工具并行编排。适合有一定Claude Code使用经验、追求并行开发效率的中高级开发者。
学习目标：在一个Monorepo中同时启动3个以上Claude Code Agent，每个在独立Worktree中工作，互不干扰，最终合并产出。
git worktree命令）claude --version）假设你正在开发一个Next.js全栈项目。早晨开工时，你有三件事要做：
如果你只用一个Claude Code会话，它只能在一个分支上工作。切换任务意味着git stash、切分支、恢复——频繁中断，容易出错。
更糟的是：如果两个Agent在同一工作目录修改不同文件，Git不知道这些更改属于哪个上下文，合并时产生混乱。
Git Worktree允许你从同一个仓库检出多个工作目录，每个目录对应不同的分支：
图表 1
关键特性：
- 所有Worktree共享同一个.git目录（共享对象数据库）
- 每个Worktree有独立的工作目录和索引
- 不同Worktree不能检出同一个分支
- 创建Worktree不需要完整克隆，几乎瞬间完成
# 检查Git版本（需要2.5+）
git --version
# 输出示例: git version 2.43.0
# 检查Claude Code版本
claude --version
# 输出示例: claude/1.0.x
# 进入你的项目目录
cd ~/projects/my-nextjs-app
# 确认是Git仓库
git status
--worktree标志Claude Code内置了--worktree标志，启动时自动创建一个隔离的Worktree环境：
# 在fix/login分支上启动Claude Code，自动创建Worktree
claude --worktree fix/login
执行流程：
图表 2
预期输出：
Creating worktree at .worktrees/fix-login on branch fix/login...
Worktree created. Working directory: /home/user/projects/my-nextjs-app/.worktrees/fix-login
╭─────────────────────────────────────╮
│ Claude Code (fix/login worktree) │
╰─────────────────────────────────────╯
在已启动的Claude Code会话中，可以直接请求创建Worktree：
用户: 请在一个worktree中工作，帮我修复登录Bug
Claude Code将自动调用EnterWorktree工具，创建隔离环境
或者在命令行使用/worktree命令（如果已配置为slash command）。
完全手动控制，适合需要精确配置的场景：
# 1. 手动创建Worktree
git worktree add .worktrees/fix-login -b fix/login
# 2. 进入Worktree目录
cd .worktrees/fix-login
# 3. 正常启动Claude Code
claude
# 4. 工作完成后回到主目录
cd ../..
| 特性 | --worktree标志 |
EnterWorktree工具 | 手动创建 |
|---|---|---|---|
| 自动化程度 | 全自动 | 半自动 | 手动 |
| 分支命名 | 自动或指定 | 自动生成 | 完全自定义 |
| 目录位置 | .worktrees/下 |
.claude/worktrees/下 |
自定义 |
| 适用场景 | 快速启动 | 会话中切换 | 精细控制 |
| 清理方式 | 退出时可选清理 | 会话结束提示清理 | 手动git worktree remove |
# 克隆示例项目（或使用你自己的项目）
git clone https://github.com/example/nextjs-dashboard.git
cd nextjs-dashboard
# 确认主分支干净
git status
# 输出: nothing to commit, working tree clean
打开三个终端窗口（或tmux pane），分别执行：
终端1 - Bug修复（紧急）：
claude --worktree fix/login-bug
在Claude Code会话中输入：
请分析 src/app/login/page.tsx 和 src/lib/auth.ts，
修复用户报告的"登录后session丢失"问题。
重点关注cookie设置和JWT token刷新逻辑。
终端2 - 数据库重构（重构）：
claude --worktree refactor/db-schema
在Claude Code会话中输入：
重构 src/lib/db/schema.ts，将用户表和订单表分离为独立模块。
使用Drizzle ORM的模式定义方式。确保迁移文件正确。
不要修改任何API路由，只改schema层。
终端3 - 新功能（支付API）：
claude --worktree feat/payment-api
在Claude Code会话中输入：
在 src/app/api/stripe/ 下创建新的支付API。
包括：创建checkout session、webhook处理、订阅状态查询。
参考现有API的结构风格。
此时你的项目目录结构如下：
nextjs-dashboard/
├── .git/ # 共享Git对象数据库
├── .worktrees/
│ ├── fix-login-bug/ # Worktree 1: Bug修复
│ │ ├── src/
│ │ ├── package.json
│ │ └── ...
│ ├── refactor-db-schema/ # Worktree 2: 重构
│ │ ├── src/
│ │ ├── package.json
│ │ └── ...
│ └── feat-payment-api/ # Worktree 3: 新功能
│ ├── src/
│ ├── package.json
│ └── ...
├── src/ # 主工作目录（main分支）
├── package.json
└── ...
每个Worktree都是完整的项目副本，可以独立运行npm install和npm run dev。
使用claude agents命令查看所有活跃会话：
# 在另一个终端中运行
claude agents
Agent View界面（2026年5月发布的功能）：
╭───────────────────────────────────────────────────╮
│ Claude Code Agent View │
├───────────────────────────────────────────────────┤
│ │
│ ● fix/login-bug [running] 2m 34s │
│ ↳ Fixing session persistence in auth.ts │
│ ↳ Modified: 2 files │
│ │
│ ● refactor/db-schema [running] 5m 12s │
│ ↳ Separating user and order schemas │
│ ↳ Modified: 4 files │
│ │
│ ● feat/payment-api [running] 1m 08s │
│ ↳ Creating Stripe checkout endpoint │
│ ↳ Modified: 1 file │
│ │
╰───────────────────────────────────────────────────╯
你也可以在会话中使用/bg命令将当前会话移到后台，然后用claude agents切回Agent View统一管理。
在项目根目录的.claude/settings.json中配置：
{
"worktree": {
"directory": ".worktrees",
"autoCleanup": true,
"defaultBranchPrefix": "claude/"
}
}
directory：Worktree存放目录（相对于项目根目录）autoCleanup：会话结束时是否自动提示清理defaultBranchPrefix：自动创建分支时的前缀.gitignore配置将Worktree目录加入.gitignore：
# 添加到 .gitignore
echo ".worktrees/" >> .gitignore
echo ".claude/worktrees/" >> .gitignore
git add .gitignore
git commit -m "chore: ignore worktree directories"
对于Turborepo或Nx管理的Monorepo：
图表 3
部分检出（Sparse Checkout）：
# 创建Worktree后配置稀疏检出
git worktree add .worktrees/web-only -b feat/web-redesign
cd .worktrees/web-only
git sparse-checkout init --cone
git sparse-checkout set apps/web packages/ui
# 现在这个Worktree只包含web相关文件
# Claude Code在这个Worktree中工作时，不会看到API目录的文件
# Bug修复完成，在Worktree中提交
cd .worktrees/fix-login-bug
# Claude Code已自动创建了commit
git log --oneline -3
# abc1234 fix: resolve session persistence issue
# def5678 fix: update cookie settings
# 9ab0123 (HEAD -> fix/login-bug) ...
# 切回主仓库合并
cd ../..
git merge fix/login-bug --no-ff -m "merge: fix login session bug"
# 清理Worktree
git worktree remove .worktrees/fix-login-bug
git branch -d fix/login-bug
当两个Worktree修改了同一文件的不同部分：
# 尝试合并重构分支
git merge refactor/db-schema
# 如果出现冲突
# Auto-merging src/lib/db/index.ts
# CONFLICT (content): Merge conflict in src/lib/db/index.ts
使用Claude Code解决冲突：
# 启动Claude Code解决冲突
claude
在会话中：
当前有合并冲突。请检查 src/lib/db/index.ts 中的冲突标记，
分析两个分支的修改意图，生成正确的合并结果。
保留两个分支的所有功能变更。
Claude Code会读取冲突文件，分析<<<<<<</=======/>>>>>>>标记，生成合并后的代码。
图表 4
最佳实践：
1. 每个Agent的任务尽量限定在互不重叠的文件范围内
2. 给Claude Code明确的指令："只修改src/lib/auth/目录下的文件"
3. 共享配置文件（如package.json）的修改放在最后串行处理
4. 频繁从main分支拉取更新：每个Worktree定期git rebase main
johannesjo/parallel-code是一个开源桌面工具，可以在独立Worktree中同时运行Claude Code、Codex CLI、Gemini CLI等多个AI编程工具：
# 克隆并安装
git clone https://github.com/johannesjo/parallel-code.git
cd parallel-code
npm install
npm run build
# 或者下载预编译版本
# 从 GitHub Releases 页面下载对应平台的二进制文件
# parallel-code.yaml - 项目配置文件
agents:
- name: claude-code-bugfix
tool: claude
worktree: .worktrees/claude-fix
branch: fix/claude-login
prompt: "修复登录页面的session持久化问题"
- name: codex-refactor
tool: codex
worktree: .worktrees/codex-refactor
branch: refactor/codex-schema
prompt: "重构数据库schema，分离用户和订单模块"
- name: gemini-feature
tool: gemini
worktree: .worktrees/gemini-payment
branch: feat/gemini-payment
prompt: "添加Stripe支付API端点"
settings:
maxConcurrent: 3
autoCommit: true
cleanupOnExit: true
# 启动并行会话
parallel-code run --config parallel-code.yaml
parallel-code会为每个Agent创建独立Worktree，启动对应工具，并在一个统一界面中展示进度：
╭─────────────────────────────────────────────────────╮
│ parallel-code Dashboard │
├──────────┬──────────┬──────────┬────────────────────┤
│ Agent │ Tool │ Status │ Progress │
├──────────┼──────────┼──────────┼────────────────────┤
│ bugfix │ Claude │ ● Done │ 3 commits, 5 files │
│ refactor │ Codex │ ◐ Active │ 2 commits, 3 files │
│ feature │ Gemini │ ● Done │ 4 commits, 8 files │
╰──────────┴──────────┴──────────┴────────────────────╯
# 查看各Worktree的变更
for wt in .worktrees/*/; do
echo "=== $(basename $wt) ==="
cd "$wt"
git log --oneline main..HEAD
git diff --stat main..HEAD
cd - > /dev/null
done
一个基于Next.js 15 + Supabase的SaaS仪表盘，需要同时处理5个任务：
| 任务ID | 类型 | 涉及文件 | 优先级 |
|---|---|---|---|
| T1 | Bug修复 | src/app/auth/* |
P0 |
| T2 | 性能优化 | src/lib/query/* |
P1 |
| T3 | 新API | src/app/api/analytics/* |
P1 |
| T4 | UI重构 | src/components/Dashboard/* |
P2 |
| T5 | 测试补充 | __tests__/* |
P2 |
图表 5
执行策略： - 第一批（并行）：T1 + T2 - 第二批（并行）：T3 + T4（T3依赖T1，T4依赖T2） - 第三批：T5（依赖T1和T3）
终端1 - T1 Bug修复：
claude --worktree fix/auth-session
修复src/app/auth/callback.ts中的session回调问题。
用户报告：OAuth登录后，callback中未正确处理Supabase的code exchange。
请检查supabase auth helper的用法，确保codeVerifier正确传递。
完成后运行 npm run build 验证无编译错误。
终端2 - T2 性能优化：
claude --worktree perf/query-optimization
优化src/lib/query/下的数据查询函数。
当前问题：Dashboard页面加载时触发了15次单独查询。
请使用batch query和React Suspense重构。
目标：减少到3次并行查询。
使用 npm run build 验证。
# 先合并批次一的成果到main
git merge fix/auth-session --no-ff
git merge perf/query-optimization --no-ff
# 清理已完成的工作树
git worktree remove .worktrees/fix-auth-session
git worktree remove .worktrees/perf-query-optimization
终端1 - T3 新API：
claude --worktree feat/analytics-api
在src/app/api/analytics/下创建3个端点：
1. GET /api/analytics/overview - 总览数据
2. GET /api/analytics/trends?range=7d - 趋势数据
3. GET /api/analytics/top-pages - 热门页面
使用Supabase client查询，参考现有src/app/api/的代码风格。
添加Zod schema验证query参数。
终端2 - T4 UI重构：
claude --worktree refactor/dashboard-ui
重构src/components/Dashboard/下的组件。
将大组件拆分为小组件（每个<100行）。
使用React Server Components和数据获取模式。
参考shadcn/ui的设计模式。
# 合并批次二
git merge feat/analytics-api --no-ff
git merge refactor/dashboard-ui --no-ff
# 清理
git worktree remove .worktrees/feat-analytics-api
git worktree remove .worktrees/refactor-dashboard-ui
# 启动最终任务
claude --worktree test/comprehensive-tests
为以下模块补充测试：
1. src/lib/auth/ - 单元测试（mock Supabase）
2. src/app/api/analytics/ - API路由测试
3. src/components/Dashboard/ - 组件渲染测试
使用vitest + @testing-library/react。
测试文件放在对应目录的__tests__/下。
运行 npx vitest run 确保全部通过。
# 合并最后的测试分支
git merge test/comprehensive-tests --no-ff
# 清理所有Worktree
git worktree remove .worktrees/test-comprehensive-tests
# 删除已合并的分支
git branch -d fix/auth-session perf/query-optimization
git branch -d feat/analytics-api refactor/dashboard-ui
git branch -d test/comprehensive-tests
# 验证最终状态
git worktree list
# 应该只剩下一个worktree（主工作目录）
# 完整构建验证
npm run build && npm run test
fatal: 'fix/login-bug' is already checked out at '.worktrees/fix-login-bug'
原因：Git不允许同一个分支同时在两个Worktree中检出。
解决：
# 方案1：使用不同的分支名
claude --worktree fix/login-bug-v2
# 方案2：先移除旧Worktree
git worktree remove .worktrees/fix-login-bug
claude --worktree fix/login-bug
原因：某些包管理器在Worktree中运行时可能遇到符号链接问题。
解决：
cd .worktrees/fix-login-bug
# 方案1：清除缓存后重装
rm -rf node_modules
npm install
# 方案2：使用pnpm（对Worktree更友好）
pnpm install
# 方案3：从主目录运行安装，然后软链接
cd ../..
npm install
ln -s ../../node_modules .worktrees/fix-login-bug/node_modules
# 查看所有Worktree及占用空间
git worktree list
du -sh .worktrees/*
# 清理已合并的Worktree
git worktree prune # 清理已删除目录的引用
# 批量清理
for wt in $(git worktree list --porcelain | grep "^worktree" | cut -d' ' -f2); do
if [ "$wt" != "$(pwd)" ]; then
branch=$(git --work-tree="$wt" branch --show-current)
if git branch --merged main | grep -q "$branch"; then
echo "Cleaning merged: $wt ($branch)"
git worktree remove "$wt"
git branch -d "$branch"
fi
fi
done
VSCode和其他IDE可能不会自动识别Worktree中的项目配置：
# 在VSCode中打开Worktree作为独立窗口
code .worktrees/fix-login-bug
# 或使用VSCode的多根工作区
# 创建 my-project.code-workspace 文件：
{
"folders": [
{ "path": ".", "name": "main" },
{ "path": ".worktrees/fix-login-bug", "name": "fix/login" },
{ "path": ".worktrees/feat-payment-api", "name": "feat/payment" }
]
}
图表 6
| 原则 | 说明 |
|---|---|
| 文件隔离 | 每个Agent任务限定在非重叠的文件范围内 |
| 显式指令 | 给Claude Code明确的文件路径和修改范围 |
| 批次执行 | 有依赖的任务串行批次，无依赖的并行 |
| 即时合并 | 完成一个Worktree后立即合并，减少漂移 |
| 构建验证 | 每个Agent完成后执行npm run build验证 |
| 及时清理 | 合并后立即删除Worktree，释放磁盘空间 |
| 共享配置延后 | package.json等共享文件的修改放在最后统一处理 |
| 维度 | 评估 |
|---|---|
| 适合训练营 | 进阶训练营（需要有Git和Claude Code基础） |
| 教学时长 | 2-3小时（含实操练习） |
| 实操占比 | 70%（大量动手创建Worktree和并行操作） |
| 前置课程 | Claude Code入门 + Git进阶 |
| 难度评级 | ★★★★☆（需要并行思维和Git分支管理经验） |
| 推荐人数 | 10-20人小班（需要导师协助调试Worktree冲突） |
--worktree标志和Agent隔离[!tip] 51学通信知识星球 星主：爱卫生（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 星球定位：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 当前规模：5200 篇主题 / 990 个回答，198 元/年。 加入福利：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 AI 加持：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。
