1. 結論先行：同一個 repo，不等於同一個工作目錄
來源事實：Orca 自稱 worktree-native；每個任務會取得真正的 Git worktree，並擁有自己的 branch、磁碟檔案與 Agent terminals。Git 官方則把 linked worktree 定義為掛在同一 repository 上的額外 working tree，其 HEAD、index 等工作樹狀態分開，但底層 repository 仍共享。
AI 工程判讀：最重要的心智模型是「一份 Git 歷史，多個獨立施工現場」。Agent A 在自己的 worktree 修改檔案時，不會即時改到 Agent B 的檔案；兩者也各自有 staging index，因此不會因為同時執行 git add 而互相污染。
但這只是第一層安全。branches 與多數 refs 仍屬於共同 repository；fetch、push、branch 建立與刪除，以及預設 repository config，會影響其他 worktree 可觀察到的狀態。更重要的是，port、database、Docker daemon、測試帳號、雲端 sandbox 與第三方 API 根本不在 Git worktree 的隔離範圍內。
AI 建議：把 Orca 當成「平行施工場管理器」，而不是「自動避免所有衝突的合併器」。若任務邊界、外部資源與整合責任沒有設計，多開 Agent 只會把等待時間改造成重工時間。
Worktree 之間哪些狀態隔離、哪些仍共享
FIGURE 01 / MATRIX| 項目 | 每個 worktree 獨立 | 同一 repository 共享 | Git 之外仍需自行隔離 |
|---|---|---|---|
| 原始碼與暫存狀態 | working files、HEAD、index、未追蹤檔案 | objects、commits、多數 refs、預設 config | 無 |
| 分支與同步 | 各自 checkout 不同 branch | branch ref、remote-tracking refs、fetch 結果 | Git hosting 權限與 branch protection |
| 執行環境 | 在各目錄內建立的 node_modules、venv、build 輸出 | 可選擇共享套件快取或 Git object store | port、DB schema、container 名稱、測試帳號、雲端資源 |
| Agent 工作階段 | Orca 的終端、編輯器、browser 與 diff 都綁定 worktree | 同一 Orca runtime 可看見任務與訊息 | 模型帳號、rate limit、外部憑證與服務配額 |
2. Orca 在 Git worktree 之上多做了什麼
來源事實：Orca 的工作流程把建立、工作、檢視、提交與刪除串成同一個介面。建立時可選 base ref、local branch、commit SHA 或 remote branch；工作期間的 terminal、editor、browser 與 diff 都以 worktree 為範圍；完成後可在同一處 commit、push、開 PR、等待 checks，再封存或刪除。
官方原始碼顯示，Orca 實際呼叫 git worktree add，並額外保存 worktree 建立時的 base lineage。它也會在更新 local base ref 前檢查 fast-forward 條件與 owner worktree 是否乾淨，避免把有未提交變更的 base checkout 靜默往前移。這些保護降低操作失誤，但不取代專案自己的合併政策。
Git 本身通常拒絕把同一 local branch 同時 checkout 到另一個 worktree，除非明確使用 force。這是好事：每個 Agent 應有唯一 branch，不應靠兩個工作目錄共同推進同一 branch。若需要共享成果，應透過 commit、rebase、merge 或 cherry-pick 傳遞，而不是直接共寫 branch。
AI 建議：建立 worktree 時，把 start-from 固定成同一個已記錄 SHA，而不只口頭說「都從 main 開」。當任務時間拉長，origin/main 可能繼續前進；用 SHA 才能分辨差異是 Agent 策略不同，還是起跑點不同。
3. 第一個決策：你是在競速，還是在協作
來源事實：Orca 官方的新手流程與 recipe 主要示範「同題競速」：三個 worktree 從同一 start-from ref 開始，三個 Agent 接到同一 prompt，最後比較 diff、選一個 winner、提交 winner，刪除其餘兩個 worktree。
AI 工程判讀：同題競速與互補協作是兩種不同拓樸。競速的輸出彼此替代，原則上只合併一個；協作的輸出彼此相依，目標是把多個 branch 整合成同一個交付。若沒有先講清楚，團隊很容易把三個競速結果全部拼在一起，或讓三個協作 Agent 重複設計同一層。
同題競速適合規格清楚、驗收可自動化、解法空間大的任務，例如修一個可重現 bug、重構一個純函式、比較三種 selector 策略。互補協作適合可以切成穩定契約的功能，例如 API contract、backend implementation、frontend integration、tests 與 migration。
限制：官方 recipe 認為不同 Agent 的分歧能暴露難點，這是實用的操作假說，不等於每次多跑幾個 Agent 都會提高正確率。若驗收條件模糊，三個錯誤答案也可能彼此一致。
同題競速與互補協作不可混用
FIGURE 02 / MATRIX| 項目 | 同題競速 | 互補協作 |
|---|---|---|
| 目標 | 同一問題產生多個候選解 | 不同工作包共同完成一個交付 |
| 輸入 | 相同 prompt、相同 base SHA、相同 tests | 不同 spec、明確 dependencies、共享 contract |
| 整合 | 選一個 winner；其他結果只供參考 | 依依賴順序合併多個 branch |
| 主要風險 | 評選標準不客觀、浪費算力 | 契約漂移、重疊 ownership、語意衝突 |
| 完成定義 | 候選通過同一驗收集且 diff 可比較 | 每個工作包有 commit、測試、介面與 handoff 摘要 |
4. 多 Agent 任務切分：先切契約與依賴，再切檔案
AI 建議：最差的分工是「你改前端、你改後端、你補測試」但不先定義介面。這種切法看似沒有重疊檔案，實際上每個 Agent 會自行猜測 request shape、錯誤碼、欄位命名與 loading state，最後產生跨檔案的語意衝突。
較穩健的順序是先建立 contract task：確認 API schema、type、event、database boundary、feature flag 與 acceptance tests。後續 Agent 只能在 contract 的允許範圍內實作；需要改 contract 時，必須提出 decision gate，而不是各自偷偷調整。
檔案 ownership 仍然有用，但它是第二道防線。請列出 shared hot files，例如 package.json、lockfile、router registry、central schema、migration index、generated client 與 global CSS；這些檔案最好指定單一 owner，或在整合階段集中重建。
依賴圖應盡量是有向無環圖。若 Agent B 必須等 Agent A 的 contract 才能開始，就不要假裝兩者完全平行；可先讓 A 產生最小 contract commit，B 從該 commit 建 child worktree，或由 coordinator 明確 dispatch 第二階段。
建議的協作式任務拓樸
FIGURE 03 / FLOW鎖定共同起點與驗收基線
定義 schema、types、acceptance tests 與禁止變更區
在契約後方平行實作 UI、service 或 adapter
依 contract 建立測試，不依賴某個實作細節
依序合併、重建生成物、跑完整 CI
5. Worktree 沒有隔離 port、DB、Docker 與測試帳號
AI 工程推論：Git worktree 只管理 repository 與 working tree。兩個 Agent 即使修改不同目錄，只要同時啟動預設 port 3000、共用同一個本機 database、重用同一個 container name，或對同一個測試租戶寫資料，仍會互相干擾。
每個 worktree 應有可推導的 namespace，例如以 worktree ID 或 branch slug 產生 APP_PORT、DB_SCHEMA、COMPOSE_PROJECT_NAME、CACHE_PREFIX 與 ARTIFACT_DIR。對外部 sandbox 也應分配獨立 tenant 或至少獨立 test data prefix。
套件快取可以共享以節省空間，但可寫入的 build output、node_modules、Python virtualenv 與 test report 應留在各 worktree。若工具會把絕對路徑寫進 cache，跨 worktree 共用反而可能產生難以重現的錯誤。
AI 建議：在 Agent 開始之前，由 bootstrap script 產生 `.env.worktree`，並在測試啟動時印出 namespace。沒有 namespace 的外部副作用任務，不應被平行 dispatch。
常見共享資源與隔離手段
FIGURE 04 / MATRIX| 項目 | 衝突症狀 | 建議隔離鍵 | 整合或清理方式 |
|---|---|---|---|
| 開發伺服器 port | EADDRINUSE、預覽到另一個 Agent 的版本 | APP_PORT=基準值+工作樹序號 | 關閉 terminal 時釋放 process |
| Database | migration 互踩、測試資料互相刪除 | 獨立 schema、database 或 transaction namespace | 整合時由 migration owner 重建乾淨 DB |
| Docker Compose | container/network 名稱相撞 | COMPOSE_PROJECT_NAME=<worktree-slug> | 以同一 project name 執行 down |
| Cache 與 artifact | 讀到舊 build、report 被覆寫 | CACHE_PREFIX、ARTIFACT_DIR | 只共享唯讀或 content-addressed cache |
| 外部測試帳號 | 狀態被另一個 Agent 改掉、rate limit | 獨立 tenant、測試資料前綴 | 測試結束執行可重跑 cleanup |
6. 任務有 ownership 或 dependency 時，使用 Orchestration，不要只群發 prompt
來源事實：Orca Orchestration 是實驗性功能，提供 persistent messages、tasks、dispatches 與 decision gates。官方文件明確區分：一次性的 terminal input 可用 terminal send；需要追蹤 ownership、dependencies 或 worker completion 的工作應使用 orchestration。
Task 有 pending、ready、dispatched、completed、failed 與 blocked 等狀態；dispatch 代表某一次具體指派。完成權限綁定 active dispatch，因此 worker 回報時應同時帶 taskId 與 dispatchId，避免舊的 retry 誤把新 dispatch 標成完成。
Worker contract 要求 worker_done 僅送一次、附上完成摘要、長工時送 heartbeat，遇到阻塞問題使用 ask，而不是停在 Agent 自己的互動式 TUI 等人回答。這讓 coordinator 能區分「還在做」、「等待決策」、「已失敗」與「已完成但有殘留風險」。
AI 建議：Orchestration 解決的是協調狀態，不是程式碼合併。task completed 應只表示 worker 已交付可整合成果；真正的完成仍需 integrator 驗證 commit、diff、tests 與相依契約。
7. 整合是序列化臨界區：指定一個 Integrator
AI 工程判讀：多個 Agent 可以平行產生 commits，但合併到共享基線的動作本質上是一段序列化臨界區。若每個 Agent 都自行 rebase、改 lockfile、解 migration conflict 並推同一個 integration branch，Worktree 的物理隔離會在最後一步全部失效。
指定單一 integrator 或 merge queue。它先確認每個 handoff 的 commit SHA 與測試證據，再按 dependency order 合併：contract 先、implementation 次、generated artifacts 與 lockfile 最後集中重建。每納入一個 branch 就跑最小相關測試，全部完成後再跑完整 CI。
獨立且小的修正可 cherry-pick 原子 commits；需要保留一組內部歷史的功能可 merge branch；rebase 只應由 branch owner 或 integrator 對該 branch 執行。不要在多人共用的 branch 上任意改寫歷史。
來源事實：Orca 的一般 Push 不會在 branch 落後時靜默 force-push；需要改寫遠端歷史時，介面把 force push with lease 做成明確、獨立動作。這符合多 Agent 環境的安全原則：任何歷史改寫都必須是顯式決策。
建議的整合佇列
FIGURE 05 / FLOW記錄 branch、commit SHA、tests 與 assumptions
檢查 drift；由 owner 或 integrator rebase／merge
依 dependency order cherry-pick 或 merge
lint、typecheck、unit、contract 與 migration checks
lockfile、client、schema snapshot 由單一 owner 產生
再開 PR；失敗時只回退最近一個整合步驟
8. 最危險的不是 merge conflict，而是 Git 看不見的語意衝突
AI 工程判讀：Git 能偵測的是文字層級重疊，不能理解兩個不同檔案是否對同一 API、schema 或 business rule 做出矛盾假設。多 Agent 專案最常在「合併完全乾淨」之後才失敗。
第一類是契約衝突：frontend 假設欄位叫 expiresAt，backend 實作 expiry；兩個 branch 沒改同一行，Git 不會警告。第二類是順序衝突：兩個 Agent 各自新增 migration 編號或 registry entry，文字可合併但執行順序錯誤。第三類是生成物衝突：lockfile、API client、snapshot 與 codegen output 由不同基線生成，手工合併通常比重建更危險。
第四類是測試盲點：每個 Agent 只在自己的 branch 跑綠色測試，但整合後的組合路徑沒有 coverage。第五類是外部狀態衝突：一個 Agent 建立資料，另一個 Agent 的 cleanup 把它刪掉。這些都需要 contract tests、integration tests 與 namespaced sandbox，而不是更強的文字 merge 工具。
AI 建議：對 shared hot files 建立「禁止平行修改」清單；對跨模組契約建立 machine-readable schema 與 consumer tests；對生成物採「來源檔合併後重建」，不要讓 integrator 手工修出一份看似合理的 lockfile。
衝突類型與應對控制
FIGURE 06 / MATRIX| 項目 | Git 是否通常可見 | 典型例子 | 主要控制 |
|---|---|---|---|
| 文字衝突 | 可見 | 同一檔案同一區塊被改動 | 縮小 commits、指定 owner、人工 resolve |
| 契約衝突 | 通常不可見 | 不同檔案對欄位、錯誤碼或事件名稱假設不同 | schema、contract tests、decision gate |
| 順序衝突 | 不一定可見 | migration、router registry、feature flag rollout | 單一 owner、序號保留、整合後重跑 |
| 生成物衝突 | 可能只顯示大量文字差異 | lockfile、generated client、snapshot | 合併來源後集中 regenerate |
| 環境衝突 | 不可見 | port、DB、container、測試帳號互踩 | per-worktree namespace 與 cleanup |
| 行為衝突 | 不可見 | 各自測試通過，整合路徑失敗 | integration/E2E tests 與真實驗收情境 |
9. 一個可重複的 Orca 多 Agent Runbook
AI 建議：把每次多 Agent 執行當成小型變更列車，而不是開三個聊天視窗。開始前先建立 run manifest；執行中只透過 commits、task messages 與 decision gates 交換狀態；結束後保留可追溯的 integration log。
Step 1：更新 remote refs，記錄 base SHA、目標 branch 與驗收命令。Step 2：選 topology：race 或 collaboration。Step 3：為每個 worktree 指派唯一 branch、ownership 與環境 namespace。Step 4：先跑 baseline tests，確保起跑點不是紅色。
Step 5：dispatch 後禁止任意擴張 scope；遇到 shared contract 必須升級決策。Step 6：worker 以 atomic commits 交付，附上 tests、assumptions、files modified 與 remaining risks。Step 7：integrator freeze 每個 commit SHA，依賴序整合並逐步驗證。
Step 8：PR 通過後刪除或封存 worktrees。Git 官方建議用 git worktree remove；直接刪資料夾可能留下 administrative metadata，之後才需要 prune。長期離線或放在可移除裝置的 worktree 可 lock，避免 metadata 被清理。
- Start gate：共同 base SHA、乾淨 baseline、可重跑 acceptance tests
- Dispatch gate：唯一 branch、唯一 owner、明確 may-read／must-not-modify
- Handoff gate：固定 commit SHA、測試證據、assumptions、remaining risks
- Integration gate：一次只納入一個 branch，先 focused checks，再 full CI
- Cleanup gate：確認 branch 已合併或可丟棄，再由 Orca 或 git worktree remove 清理
10. 常見失敗模式與復原方法
AI 工程判讀：多 Agent 失敗通常不是因為 Agent 數量太多，而是 worktree 活太久、基線漂移、shared hot files 無 owner，或外部環境沒有隔離。這些問題可以透過較短的工作包與明確恢復路徑降低成本。
Base drift：工作超過數小時或主線高頻更新時，先讓 integrator 評估 ahead／behind，再決定 merge main、rebase 或重建 worktree。不要讓每個 Agent自行選不同策略。Dirty base：主 worktree 有未提交變更時，不要把它當可信起點；Orca 原始碼也特別避免在 owner worktree dirty 時自動 fast-forward local base。
Stale worktree：資料夾被手動移動或刪除，使用 git worktree list、repair 或 prune 恢復 metadata，不要直接重建同名 branch 造成歧義。Shared branch：發現兩個工作階段在同一 branch 上時，立刻停止寫入，分別固定 commits，為其中一方建立新 branch，再由 integrator 重排。
Submodule：Git 官方仍警告 multiple checkout 對 submodule 支援不完整，不建議對 superproject 建立多重 checkout。若 repo 大量依賴 submodules，應先做小規模驗證，或改用完整 clone／容器作為更強隔離邊界。
Long-lived worktree：分支活得越久，整合成本通常越高。把任務切到一個可獨立 review 的最小改動；若架構仍未確定，先讓單一 Agent 做 spike 或 contract，不要用多 Agent 同時發明架構。
11. 什麼情況不值得開多個 Agent
AI 建議：平行化不是免費加速。它增加模型成本、環境成本、review 面積與整合負荷。當 critical path 不能拆、驗收不可自動化，或大部分變更集中在同一個 hot file 時，單 Agent 逐步完成通常更快。
不適合的情境包括：只改一兩行的小 bug；需要先釐清架構的探索工作；全程依賴同一份 migration 或 schema；沒有 sandbox 的破壞性外部操作；build／test 太昂貴而無法在每個 worktree 重跑；以及 reviewer 沒有能力比較多份 diff。
評估是否值得時，不要只看 Agent 執行時間。應同時記錄 wall-clock completion、總模型與運算成本、人工 review 時間、整合失敗次數、重工 commits、CI retry 與 escaped defect。多 Agent 只有在交付時間下降且總驗證成本可控時才算成功。
實務起點可以是兩個 Agent：一個實作、一個以相同 contract 建 tests 或 review。確認整合流程可重複後，再把 max concurrency 往上調；不要從十個 Agent 開始，最後才發現 merge queue 只能一次處理一個。
12. 資深工程師版使用心法：把隔離、協調與整合分成三個控制面
AI 綜合建議：Orca 最有價值的地方，是把 worktree、Agent terminal、diff review 與 orchestration 放在同一個操作面；真正決定成果的，仍是你是否把三個控制面分開設計。
隔離面回答「誰能寫哪些檔案與資源」：一 Agent 一 worktree 一 branch，外加 per-worktree port、DB 與 sandbox namespace。協調面回答「誰在做什麼、依賴誰、何時需要決策」：用 task、dispatch、heartbeat、worker_done 與 decision gate 留下狀態。整合面回答「哪些 commits 以什麼順序進主線」：由單一 integrator、merge queue 與 CI gate 序列化處理。
最值得記住的規則是：main 是協調基準，不是多人共寫的施工現場；branch 是交付單位，不是聊天紀錄；tests 是驗收契約，不是 Agent 自我感覺良好的證明；worker_done 是 handoff，不是 production done。
不確定性：Orca 迭代速度快，Orchestration 目前仍標示 Experimental，CLI 旗標與功能入口可能變動。實際導入時，請以當下官方文件、orca status --json 與專案 Git 版本為準，並先在非關鍵 repo 做完整演練。