同一個 repo 並行多個 Claude Code session 的協調手冊

日期：2026-05-11 情境：你想同時叫 Claude Code 處理多件事，但又怕兩個 session 互撞

TL;DR

同 repo 開多個 Claude Code session 並行有三種方案：sub-agent（單 session 內派工）、手動多 session + worktree（你自己分工）、Agent Teams（官方新特性，自動協調）。除了 sub-agent 共用主 conversation 的視野，其他兩種「不知道對方存在」是預設值 — 風險不在檔案撞，在 package.json / schema / CLAUDE.md 這類共用 throat。協調靠三件事：worktree 做實體隔離 + 開場白告訴對方存在 + 指定共用檔案的 owner。

為什麼這是個問題

Claude Code 預設假設「我獨佔這個 repo」。一個 session 看不到另一個 session 開的 branch、改的檔案、跑的 yarn add。預設行為下：

兩個 session 同時改 package.json → 後 commit 的覆蓋前面的依賴
一個 session 在 main、另一個 git checkout feat/X → 第一個 session 下次 git status 看到陌生變動會驚慌或誤清理
共用的 CLAUDE.md 各自加段落 → merge 時撞

這些不會被 git 擋住 — 它們各自合法，撞在一起才壞。

三種並行方案

方案	誰主導	Context	適用場景	啟動方式
Sub-agent	主 Claude 派工，自己驗收	各自獨立 context window，sub 結束只回 final report	邊界清楚、不需要中途介入的子任務	主 session 內用 `Agent` tool
手動多 session + worktree	你主導，分別跟兩個 Claude 對話	兩個 session 完全獨立	兩件都需要你判斷、可能改方向的事	開新 terminal: `claude --worktree feat-X`
Agent Teams ⭐ 官方新特性	多個 Claude 自動協調，共用任務清單	多 session + 訊息傳遞	平行開發複雜功能、想自動化	看 Agent Teams 文件

判斷準則：你需要中途介入嗎？

不需要 → sub-agent（最輕，主 Claude 等結果）
需要 → 手動多 session（你切 terminal 操控）
兩個都需要彼此知道進度 → Agent Teams

主推方案：手動 worktree + 多 session

最常見、最直覺、最少官方魔法的方案。

# Session A：你已經有的 Claude session（cwd = ~/projects/repo, branch = main）

# Session B：開新 terminal
# 方法 1（推薦）：用 Claude Code 內建 flag，自動建 worktree 並起 session
claude --worktree feat-export

# 方法 2：先手動建 worktree，再 cd 進去起 session
git worktree add ../repo-feat-export -b feat/export
cd ../repo-feat-export
claude

兩個 session 各自獨立 context、共用同一個 .git，commit/push 互通但 working tree 完全隔離。

完工 cleanup：

git worktree remove ../repo-feat-export

開場白：告訴每個 Claude 「你不是唯一的」

預設情況下 Claude 不知道有另一個 session。明確告知能省下後續每次 git status 看到陌生 ref 的解釋成本。一段好的開場白涵蓋 5 件事：

講什麼	為什麼
「你不是這個 repo 唯一的 Claude」	預設值是「我獨占」，講了才會保守
對方在哪（路徑 / branch）	它看到 `git worktree list` 多出來的項目時不會去碰
你的範圍（檔案邊界）	限縮 scope，避免「順手」改到對方領地
共用檔案怎麼處理	`package.json` / `prisma/schema.prisma` / `CLAUDE.md` 等共用 throat 要指定 owner
commit / push 時機	講清楚什麼時候輪到誰 pull / rebase

範例

Session A 開場白：

我同時開了另一個 Claude session 在 ~/projects/repo-feat-export
（worktree, branch feat/export）處理匯出功能。

你的範圍是 main：
- 只動 src/server/ 跟 prisma/
- 不要碰 src/app/_components/stt/（對方領地）

共用檔案規則：
- package.json / yarn.lock：你 own，動之前我先發 Slack 給對方 session
- CLAUDE.md：append-only，不要刪別的段落
- prisma/schema.prisma：你 own

commit 前讓我 review；我 push 完會告訴你，到時請 git fetch。

Session B 開場白：

我同時開了另一個 Claude session 在 ~/projects/repo（main）處理 schema / backend。

你的範圍是 feat/export：
- 只動 src/app/_components/stt/ 跟相關 UI
- 不要碰 src/server/ 或 prisma/

共用檔案規則：
- 任何 schema 變更找 main session，不要自己改 prisma
- package.json：要加新套件先問我
- CLAUDE.md：append-only

PR 開出來前我會 rebase main。

共用 Throat：指定 Owner 是最有效的單一防線

並行最大風險不是檔案撞 — git 會擋你 — 而是這些檔案各自合法但組合起來壞掉：

檔案 / 區域	為什麼是 throat	建議 owner
`package.json` / `yarn.lock`	兩邊各自 `yarn add` 不同套件，merge 後可能版本衝突或缺套件	一個固定 session
`prisma/schema.prisma` + migrations	兩邊各自跑 `prisma migrate dev` 產生兩條獨立 migration → main 順序壞	schema 動作只能在一個 session
`CLAUDE.md` / 共用 doc	各自加段落、互相覆蓋	約定 append-only
共用的 router / service 入口	兩邊都會新增 endpoint，撞同一個檔案的話衝突高	拆檔或一個 owner
`.env.example`	兩邊各自加新 var	一個 owner

把這些「兩邊都會碰的」明確指定一個 session 負責，比訂一堆「先後順序」規則有效得多。

進階：`.claude/collab.md` 當共用「公佈欄」

兩個 session 都看得到的暫存協調區。在 repo 根加一個檔（不要 commit，加進 .gitignore）：

## 平行工作中（2026-05-11）

- Session A (main, ~/projects/repo): backend schema + tRPC router
  範圍: src/server/, prisma/
- Session B (worktree, ~/projects/repo-feat-export): export UI
  範圍: src/app/_components/stt/

共用檔案 owner:
- package.json / yarn.lock: Session A
- prisma/schema.prisma: Session A
- CLAUDE.md: append-only

最近事件:
- 14:30 Session A 升級了 prisma 到 7.8（含 lockfile）
- 15:10 Session B 加了 export button UI

開場白裡叫 Claude 先讀這個檔。每次有重要動作（升套件、schema 變更、push 到 main）就讓 Claude 加一筆。並行結束後刪掉。

也可以暫時寫在 CLAUDE.md 結尾用一個 ## 平行工作中 section，但記得結束時清掉 — 留著會誤導未來的 Claude session。

常見踩雷

❌ 兩個 session 同時試圖 checkout 同一條 branch

fatal: '<branch>' is already used by worktree at '<path>'

Git 會擋。這是 worktree 設計刻意防的 — 同一條 branch 不能在兩個 worktree 同時 checked out（避免兩邊 working tree 不一致）。解法：另一邊用 git checkout -b new-branch 開新 branch 或 detached HEAD。

❌ 一個 session 跑 `yarn add` 另一個沒同步

A session yarn add foo，B session 完全不知道 → B 寫的 code import foo 時跑不起來（本地 node_modules 沒裝）。解法：throat owner 講一聲，B 跑 yarn install。或者把 yarn add 的 commit push 完，B git pull && yarn install。

❌ Sub-agent 跑超過你預期的範圍

Sub-agent 收到模糊的 prompt → 自己決定要動什麼檔。給 sub-agent 的 prompt 要寫得像給陌生同事看的：明確檔案路徑、行號、預期輸出，不要寫「based on the analysis above, fix the bug」（sub-agent 看不到 analysis）。

❌ 兩個 session 各自 commit + push → 第二個被擋

預期之中。第二個 session 應該 git pull --rebase 或視情況 force push（如果在 PR feature branch 上）。如果撞到 yarn.lock 衝突，看上一篇 lockfile 衝突筆記。

學到的事

「Claude 不知道對方存在」是 Default。 不講對方就會用 default 行為。開場白成本低、報酬高。
隔離靠 worktree 不靠紀律。 講好「你只動 X」仍可能誤觸；worktree 把工作目錄實體分開，誤觸只能在自己領地內，影響範圍小。
Throat owner 比規則優先。 「動之前要問」這種規則 Claude 容易忘；「這個檔只有 Session A 能動」這種 ownership 簡單可執行。
Sub-agent vs 多 session 的核心差別是「中途介入需求」。 一錘子買賣用 sub-agent；要持續對話用多 session。
Agent Teams 是未來方向。 官方在推「多 session 自動協調」— 等成熟後人類做 throat owner 的工作可能會被自動化掉，但目前先用手動 worktree 模式比較穩。

參考資料

Claude Code: Run parallel sessions with worktrees — --worktree flag 與隔離原理的官方說法
Claude Code: Sub-agents — sub-agent 各自獨立 context 的官方確認
Claude Code: Agent Teams — 多 session 自動協調的新特性（實驗中）
Claude Code: How Claude Code works — Manage context with skills and subagents — context window 管理的整體架構
git worktree 官方文件 — worktree 的底層機制（同 branch 不能在多 worktree 同時 checked out 等限制）