Worktrees、長任務與平行工作

14.1 什麼時候該用 worktree

一般小修可以留在同一個工作區：改一兩個檔、跑測試、送 PR。該用 git worktree 的時機，是你需要同時保留多個分支的真實檔案狀態，例如一個 Gemini session 正在修 API bug，另一個 session 要補文件，第三個 session 要研究測試失敗。worktree 的價值是讓每個任務有自己的 checkout、自己的 untracked files、自己的 build cache 與自己的 Gemini 對話脈絡。

不要把 worktree 當成「讓很多代理一起亂改」的開關。平行工作要先拆清楚邊界：一個任務負責後端 API，一個任務負責文件，一個任務只讀程式碼做研究。只要兩個 session 會改同一批檔案，就應該改成序列化，或先由人決定誰是 owner。

# 在主工作區確認基準分支乾淨後，建立獨立工作區
git worktree add -b feat/gemini-auth-review ../repo-auth-review main
git worktree add -b docs/gemini-workflows ../repo-docs-workflows main

# 每個終端機進入不同 worktree，再啟動自己的 Gemini CLI session
cd ../repo-auth-review
gemini

這種純手動流程的好處是完全不依賴 Gemini CLI 本身的版本：git worktree 是 Git 內建功能，運作方式不會因為你裝的是哪一版 CLI 而改變，就算換一套 AI 工具也照樣能用。下一節會介紹官方另外做的原生整合，能把上面兩三個步驟壓成一行指令——但骨子裡動的還是同一個 git worktree，出狀況時的排除邏輯是共通的。

14.2 官方原生 --worktree 旗標

14.1 示範的是完全不靠 CLI 支援、自己手動組裝的流程。如果不想每次都手打 add、-b、cd 三步，Gemini CLI 官方文件有一條更短的路：內建的 --worktree 旗標。這項功能官方標得很清楚是實驗性，預設關閉🧪實驗性，要先自己打開。

啟用方式二選一：互動介面打開 /settings，找到「Enable Git Worktrees」切換成開；或直接在 settings.json 寫：

{
  "experimental": {
    "worktrees": true
  }
}

開啟之後，gemini --worktree <name>（簡寫 -w）會一口氣做完 14.1 那三個步驟：建一個以 name 命名的分支、把 worktree 放進 .gemini/worktrees/<name>，再直接把你帶進那個新資料夾開始對話。不給名稱也可以，CLI 會自動生一個。

gemini --worktree feature-search
gemini -w feature-search

# 不給名稱，讓 CLI 自動命名
gemini --worktree

要接續某個 worktree 的工作，直接 cd 進那個資料夾，再用 gemini --resume 接上次的對話——14.3 節有具體示範。

還有一個容易漏掉的地方：worktree 是一個全新的資料夾，Gemini CLI 第一次在裡面工作，一樣會跑過第 1 章介紹過的資料夾信任機制。用原生 --worktree 旗標建立、CLI 直接把你帶進新目錄時，通常會照常跳出信任詢問；但如果你是用 /directory add 把另一個 worktree 加進目前 session、或手動 cd 過去再啟動，有時不會自動觸發那個對話框，功能卻悄悄受限。遇到存取卡卡的，直接手動信任：

/permissions trust ../repo-auth-review

第 7 章列過「不信任」具體擋掉的四件事：專案設定不生效、.env 讀不到、Extensions 裝不了、自動核准全部失效。worktree 目錄踩到其中任何一項，通常都是這裡漏了一步。

unable to create '<主 repo 路徑>/.git/worktrees/<worktree 名稱>/index.lock'

這是一個已知回報（GitHub issue #16940）🌐社群：有人試過自訂 seatbelt profile、settings.json 的 includeDirectories、--include-directories 旗標都沒解決，官方最後判定不修。老實說目前沒有官方 workaround；務實的做法是那次牽涉到 worktree 底層 git 操作的指令先移出 sandbox 執行，或換一個較寬鬆的 profile（第 7 章 SEATBELT_PROFILE 那段）。

14.3 多個 Gemini CLI sessions 的隔離方式

每個 session 都應綁定一個明確目標、一個 branch、一個 worktree 目錄與一段可丟進 prompt 的任務說明。終端機分頁名稱也要改清楚，例如 auth-review、docs-workflow、research-ci。如果團隊使用 GEMINI.md 或專案記憶，請讓每個 session 都讀同一份專案規則，但任務 prompt 要明確限制可修改的路徑。

任務：修正登入逾時錯誤
工作區：../repo-auth-timeout
分支：fix/auth-timeout
可修改：src/auth/**、tests/auth/**
不可修改：docs/**、package lock、部署設定
交付：最小修補、測試結果、風險說明
先做：閱讀錯誤 log 與相關測試，提出計畫後再改檔

每個 worktree 資料夾底下的 Gemini session，對話歷史是分開累積的——這是第 8 章提過的 session 續接機制自然而然的結果：session 存檔依工作目錄路徑分開，不同資料夾就是不同的歷史。這代表你可以放心把某個 worktree 的 session 暫停幾天，回來時直接接上，不會撿到別條任務的對話：

cd .gemini/worktrees/feature-search
gemini --resume

不確定要接哪一條，互動指令 /resume 會列出這個資料夾裡所有歷史 session，通常會列時間與第一則訊息內容，方便你認出正確的那個——完整用法第 8 章已經講過，這裡不重複，差別只在於你現在是先 cd 到對的 worktree，再接續，用錯資料夾接續會接到另一條任務的歷史，不會有警告告訴你接錯了。

如果只是想讓目前這個 session 順手看一眼另一個 worktree 裡的檔案做個比較，不需要整個切換過去——第 4 章介紹過的 /directory add ../repo-docs-workflows 可以把那個資料夾臨時加進目前工作區，看完就好，不必真的走過去改分支。

14.4 分支命名與任務手冊

分支名稱要讓 reviewer 一眼看出來源與意圖。建議用短 prefix 加明確名詞：fix/auth-timeout、docs/gemini-ci-notes、refactor/order-service-split、research/payment-flake。如果是 AI 協作任務，可在 PR 描述標註「Gemini-assisted」，但分支名稱仍以產品或程式變更為主，不要只叫 gemini-task-1。

分支命名撞名之外，還有一個更直接的坑：同一個分支不能同時被兩個 worktree checkout。這個錯誤訊息長什麼樣、怎麼解，收在 14.14 節的常見錯誤表。

14.5 長任務交接 notes

長任務不應只存在於聊天紀錄。每次 session 停下來前，請留下交接 notes：目標、目前狀態、已改檔案、已跑命令、失敗點、未決問題、下一步。notes 可以放在 PR 描述、issue comment、團隊任務系統，或一個不含秘密的臨時 markdown 檔；若放進 repository，確認它不是會污染正式文件的暫存內容。

## Handoff
- Goal: fix auth timeout when refresh token expires
- Branch/worktree: fix/auth-timeout / ../repo-auth-timeout
- Changed: src/auth/session.ts, tests/auth/session.test.ts
- Verified: npm test -- tests/auth/session.test.ts
- Current state: unit test passes; integration test still failing on fixture setup
- Risks: token refresh path may affect silent login
- Next: inspect integration fixture, then run full auth test suite
- Secrets: no tokens, keys, env dumps, customer data, or logs with credentials included

14.6 Checkpoint / review loop

長任務要用短循環收斂。每完成一個可理解的小步驟，就看 diff、跑最小測試、寫 checkpoint commit 或至少保存 patch。Gemini 可以協助整理 diff 與測試失敗，但人要決定 checkpoint 是否值得留下。這個節奏比一次改完十幾個檔更容易 review，也比較容易丟掉錯誤方向。

git diff --stat
git diff
npm test -- tests/auth/session.test.ts

git add src/auth/session.ts tests/auth/session.test.ts
git commit -m "checkpoint: handle expired refresh token"

review loop 的 prompt 可以很短：「只根據目前 diff，列出高風險變更、缺少測試、可能誤刪的行為。不要再改檔。」如果結論合理，再讓下一輪 session 實作。若 diff 已經跨太多領域，先停止新增功能，把分支拆小或回到人工設計。

這裡講的「checkpoint」是你自己手動決定、手動 commit 的節奏，跟第 7 章介紹的 Gemini CLI 內建 checkpointing（核准寫入動作時自動存快照、用 /restore 復原）是兩個不同層次的機制，名字很像，容易搞混。內建 checkpointing 保的是「這一步工具呼叫改壞了，退回上一步」，救援粒度很細但不進你自己的 Git 歷史；這裡的 commit checkpoint 保的是「這一段小範圍改動，我確認過了，正式留下記錄」。兩者不互斥，長任務裡通常會同時用到：內建機制當作每一步的安全網，手動 commit 當作階段性的正式存檔。

14.7 長任務怎麼撐過中斷、逾時與斷線

前面幾節處理的是「怎麼把任務切乾淨」；這一節處理的是另一個問題：任務本身要跑很久，中間可能撞到系統設下的各種上限，或單純因為你關掉了終端機視窗而被砍掉。這些風險跟平行與否無關，一個 session 單獨跑很久一樣會遇到，只是開了多條 worktree 之後，你等於同時在累積好幾組會踩到這些雷的長 session。

撞到輪數上限，不是這一條 worktree 特有的問題

第 12 章已經完整講過 model.maxSessionTurns 與退出碼 53 的細節：這個設定控制一個 session 最多能有幾輪來回，預設 -1 不限制，調太低的話長任務容易半路就被攔下來，還有一個違反直覺的已知狀況是設成 1 反而可能讓 session 整個重啟而不是乾淨停下。這裡不重複那些機制，只提醒一件跟本章主題有關的事：多開幾條平行 worktree，代表你也在同時累積好幾組「可能撞到輪數上限」的長 session，遇到某條任務忽然沒頭沒尾地停掉，先想到這個，而不是每次都當成任務本身的邏輯出錯在找。

對話拉長之後：與其信任壓縮，不如主動記一筆

第 5 章介紹過 /compress 與自動壓縮機制：對話用量超過門檻，CLI 會自動把舊對話摘要成結構化摘要省 token，GEMINI.md 內容與 /memory add 加進去的條目不受影響，其他部分會被摘要、細節精度會下降。長任務特別容易撞到這個機制，因為對話輪數本來就多；如果你發現任務跑到後段，模型好像「忘記」前面談過的細節，很可能不是它真的忘記，是那段被自動摘要掉了。

關掉終端機視窗＝殺掉任務：tmux／psmux，以及「背景任務」目前真正的邊界

第 12 章的 headless 模式解決的是「從一開始就設計成無人值守的腳本化任務」；如果你要的是「我現在互動做到一半，想讓它繼續跑、自己先去忙別的」，這是不一樣的需求。Gemini CLI 目前沒有內建功能做到這件事——社群提過類似 /task start ... --background、/task status 這類「丟到背景、之後回來看結果」的請求，官方標成 backlog／p3 之後關閉（GitHub issue #5941）🌐社群，不是一個現成功能，不要預期能直接這樣用。

務實的做法是靠終端機本身的工具，讓一個長任務撐過你把視窗關掉這件事：macOS／Linux 上用 tmux，把整個 session detach 而不是直接關視窗；Windows 上也有對應的原生終端多工工具，例如 psmux。

tmux new -s feature-search
cd .gemini/worktrees/feature-search
gemini

# 工作到一半要離開，按 Ctrl+B 再按 D 把它 detach（不是關閉視窗）
# 回來時重新 attach：
tmux attach -t feature-search

每個 worktree 開一個對應名稱的 tmux session，跟資料夾、分支一樣一一對應，之後要接哪一條、該用哪個視窗，看名字就知道，不用回想。真正需要無人值守、排程觸發的自動化，走的是完全不同的路徑：第 12 章的 headless 模式，用 -p／--output-format json 搭配退出碼判斷成敗，不依賴一個一直開著、有人互動過的終端機視窗。

14.8 全自動核准與收尾迴圈：長任務容易踩的兩個雷

--yolo 沒搭 sandbox，風險不是只在 CI 才會發生

長任務、平行 worktree 一多，手動一直核准每一步很累，很自然會想開 --yolo 圖方便。第 12 章談過一起 CVSS 10 滿分的資安公告（GHSA-wpqr-6v78-jr5g）：舊版 headless 模式疊上自動信任工作區、加上 --yolo 會繞過 settings.json 工具允許清單，讓無人看管的 CI 管線被 prompt injection 誘發任意 shell 指令。那個案例的場景是自動化管線，但背後的風險邏輯不限於 CI：長任務、平行 worktree 同樣是「沒人一直盯著畫面」的情境，--yolo 單獨開、沒有第 7 章介紹的 sandbox 搭配，代表模型每一步的判斷錯誤都會直接、真實地發生在你的檔案系統上，沒有任何緩衝。

另外，密集連續用上兩三個小時，付費方案的用量上限也可能被撞到——這是第 15 章的主題，這裡只提醒一句：規劃長時間、多條平行任務的排程時，quota 是跟輪數上限、context 壓縮同一類、常被低估的實務限制。

任務明明做完了，卻卡在自問自答不停

另一種讓長任務「看起來卡住」的狀況，跟前面幾種都不一樣：工作其實已經做完，但 CLI 卡在類似「confirming solution」「analysing completion」這類收尾狀態反覆自問自答，甚至用 Yes/No 問句問自己問個沒完，社群多起回報都提到這個現象（如 issue #4829、#6561、#12044 等多起回報），最久有人等了快一小時才手動中斷。

14.9 用 Subagent 做角色分工

Worktree 解決的是檔案層的隔離：不同任務有自己的資料夾、自己的分支。如果任務本身可以拆成幾個角色分明的子步驟，第 11 章介紹過的 Subagent 解決的是另一個層次的隔離——同一個 session 裡，把特定子任務的注意力、context 與工具權限單獨切開，不讓它污染主對話。這一節不重複第 11 章怎麼寫一個 subagent，而是講在長任務與平行工作的情境下，怎麼用已經定義好的 subagent。

一個具體的習慣：長任務、尤其是要動一個不熟的大型 repo 之前，先用 @codebase_investigator 把架構摸清楚，比讓主 agent 邊做邊探路省 token，也比較準——第 6 章提過這是 Plan Mode 少數預設放行的內建 subagent 之一，不需要額外授權設定就能用。

@codebase_investigator 在動手改之前，先說明 auth middleware、session store 與這次要動的 refresh token 邏輯彼此的呼叫關係。

如果多個 worktree 平行進行，每一條分支想給的權限不一樣，第 7 章的 Policy Engine 也能收得更細——規則的條件可以指定 subagent，讓某個特定 subagent 有主 session 沒有的權限，而不是整個專案一起放寬：

[[rule]]
toolName = "run_shell_command"
commandPrefix = "git push"
decision = "allow"
priority = 100
subagent = "pr-creator"

subagent 這個欄位的確切寫法請以你當下的官方 Policy Engine 文件為準；這裡示範的是概念——多數 session 與 subagent 維持保守權限，只有負責收尾、確定要推分支的那一個特別放寬，而不是整個專案一起開放 git push。

如果你已經在用 worktree 手動協調好幾條平行任務，覺得「誰負責哪一塊、誰能寫哪些檔案」光靠自己記很累，Google 團隊維護了一個官方以外的擴充套件 Conductor，示範了一套形式化的多代理平行協作流程：先由一個「Lead Architect」角色把任務按領域切成不重疊的區塊，接著各個 worker 可以讀全部檔案，但只能寫自己負責的那一塊——別人的檔案與協調用的 metadata 都是唯讀，最後靠一個「Sync Gate」收斂各分支、合併回主線並更新進度。就算不直接裝這個擴充套件，它劃分權限邊界的方式也值得參考。

14.10 平行研究 vs 平行改檔

平行研究通常安全：多個 session 可以讀不同模組、整理 logs、比較官方文件、草擬測試策略，最後由一個人或一個實作 session 合併結論。平行改檔則有成本：兩個 session 可能同時調整同一個 public API、同一份設定、同一段文件，最後在 merge 時互相覆蓋。實務上，平行研究可以寬，平行 edits 要窄。

14.11 避免跨 session 檔案衝突

每個任務開始前先指定「可修改路徑」與「不可修改路徑」。共用檔案如 lockfile、schema、全域設定、README、CHANGELOG、package manifest，要列為 protected files；需要改時，先暫停其他 session。若兩個分支都需要同一個基礎改動，先做一個小的 shared branch，合併後再從新的 main 或 base branch 開 worktree。

衝突處理不要交給正在衝突的兩個 session 自己猜。先由人看兩邊 diff，保留語意正確的一邊，再要求 Gemini 只針對已決定的方向補測試或整理文件。merge conflict 是產品決策與程式語意問題，不只是文字合併問題。

這裡還有一個容易被忽略的邊界：worktree 只隔離了工作目錄與分支本身，資料庫、環境變數、正在跑的本機服務或連接埠，這些共用資源並不會因為開了 worktree 就自動分開。如果其中一條平行任務會動到資料庫 schema、佔用固定 port，另一條任務即使檔案完全不衝突，也可能被悄悄影響——這不是 worktree 機制會幫你擋的部分，得自己額外規劃（例如各自用獨立的資料庫連線字串，或把會動共用資源的任務排除在平行範圍外）。

14.12 Secrets 與本機設定

worktree 會讓同一個 repo 出現多個資料夾，這也代表秘密很容易被複製到錯的地方。不要把 .env、service account key、API token、客戶 log、私有憑證放進 worktree 目錄。需要本機設定時，使用未追蹤且已被 ignore 的檔案，或讓工具從安全的系統 keychain、secret manager、shell profile 讀取。交接 notes、prompt、artifact 與測試輸出都不應含秘密。

# 檢查目前登記的 worktrees
git worktree list

# 確認沒有把秘密或暫存檔 staged
git diff --cached --name-only

14.13 清理與回收

任務完成後，不要把 worktree 永久堆在磁碟上。PR merge 或分支放棄後，先確認沒有未保存變更，再移除 worktree、刪掉本地 branch，必要時 prune 已失效紀錄。清理是一個安全步驟：可以減少舊 build cache、舊設定與過期 notes 被下一個 session 誤讀。

git worktree list
git worktree remove ../repo-auth-review
git branch -d feat/gemini-auth-review
git worktree prune

如果 git worktree remove 抱怨還有未提交的變更、拒絕執行，這是 git 自己的保護機制，不是指令用錯——它不會讓你不小心把還沒存的工作弄丟。先跑 git status 看一眼，確認真的可以丟棄再加 --force；還想留著就先 commit 或搬到別的分支。

git status
git worktree remove ../repo-auth-review --force

用 14.2 節的原生 --worktree 旗標建立的 worktree，同樣不會在你離開時自動清掉——這是官方刻意的設計，不是遺漏，清理習慣跟純手動流程完全一樣，一樣要自己跑 remove 加 branch -d。

平行 worktree 開多了，還有一個容易低估的成本：每個 worktree 預設都是獨立的 node_modules（或其他語言生態圈的等價物），開三四條平行任務，等於重複裝了三四次依賴，同時吃磁碟跟時間。如果這個成本已經開始困擾你，可以換一套支援跨 worktree 共享套件快取的套件管理工具（例如 pnpm、yarn berry），或單純克制一點，同時開的 worktree 數量別超過你真的在忙的任務數。

14.14 常見錯誤與排除

worktree 疊上 Gemini CLI 之後，有幾個症狀特別容易讓人誤以為是自己設定錯了，其實是已知的行為或已知的坑。整理在這裡方便查——版本變動快，實際錯誤訊息與行為仍以你當下的 git 與 CLI 版本為準。

本章小結

git worktree 是讓多個 Gemini CLI session 安全並行的基礎，官方後來也做了實驗性的原生 --worktree 旗標把手動流程壓成一行，但兩者背後是同一套機制，出錯時的排除邏輯共通。每個任務一個 worktree、一個 branch、一份清楚 prompt；接續舊任務靠 --resume，走錯方向靠第 8 章的 /rewind，這兩個機制在 worktree 情境下用法完全一樣，差別只在於要先 cd 到對的資料夾。研究任務可以平行，改檔任務要用路徑和 owner 收窄；長任務除了要靠 checkpoint／review loop 控制風險，還要留意輪數上限、context 壓縮與終端機斷線這幾個容易被忽略的中斷點；平行工作規模一大，Subagent 與 Policy Engine 能把權限切得更細。secrets、lockfile、schema 與全域設定要特別保護，worktree 本身也不會隔離資料庫或連接埠這類共用資源。完成後記得清理 worktree 與分支，原生旗標一樣不會幫你自動收尾。

動手試試

1. 如果你的 Gemini CLI 版本支援，先在 settings.json 打開 experimental.worktrees，用 gemini --worktree 建一個具名 worktree，跟 14.1 的純手動流程比較兩者差在哪裡。
2. 替任務寫一段 prompt，明確列出可修改路徑、不可修改路徑與交付格式。
3. 完成一個小改動後，跑 git diff --stat、最小測試與 checkpoint commit。
4. 離開這個 worktree 的 session 前，先跑一次 /resume save 存一個具名 checkpoint；重開終端機後，練習從對應資料夾用 --resume 接回去。
5. 寫一份 handoff notes，確認不含 API key、token、客戶資料或機密 log。
6. 合併或放棄任務後，練習 git worktree remove（留意未提交變更會被擋）與 git worktree prune。