Director Mode repository workflow：多 agent 工作不等於多份混亂 diff

這裡的 Director Mode 是一種 repository 編排模式，不是 Git 或 GitHub 官方產品名稱：主協調者保留需求、架構、scope 與完成判斷，把互不衝突的探索/實作交給 agents，最後以 shared evidence 整合。速度來源是平行處理獨立問題，不是讓多人同時改同一檔案。 截至 2026-07-29，Git 官方 worktree 能讓一個 repository 同時 checkout 多個 branches；GitHub Pull Request/Status Checks 提供 diff review 與最新 commit 的 automated validation。Director workflow 應依這些可觀察原語建立，而不是依 agent 的「完成」訊息。 實作步驟 第一步建立 task brief：使用者結果、in/out of scope、acceptance criteria、source of truth、protected files、verification 與 remote action policy。先跑 git status --short ，記錄既有 dirty files，所有人都不得回退別人的工作。 第二步畫 ownership map。可平行的 subtask 必須有清楚檔案/模組責任與 interface，例如 Agent A owns database migration，B owns UI component，C 做 read-only audit/tests。若兩個 task 都需改 shared types/package lock，由主協調者 serial integration 或指定單一 owner。 需要隔離時使用 linked worktree，每個 branch 一個絕對 path；共享同一 worktree 時則同步訊息並避免格式化整 repo。 git status --short git worktree add ../project-auth -b feat/auth git worktree add ../project-content -b feat/content git worktree list 第三步維護 scope ledger：task、owner、files、dependency、status、evidence、blocker。Agent 回報必須含變更檔、tests 與未解風險，不只摘要。探索 agent read-only，實作 agent不能順便重構 unrelated surface。 第四步定義 interface before parallelism。先決定 schema/API/component props、error contract 與 migration sequence，讓各分支對同一邊界開發。遇到新資訊改 interface 時，主協調者一次通知所有 dependent owners。 第五步整合按 dependency：migration/types → service → UI → cross-surface tests。每次 merge/cherry-pick 前看 diff與 conflicts，之後跑 affected tests；不要等所有 changes 疊完才第一次 build。共用 worktree則不 cherry-pick 已經可見的 files。 第六步做多層 review：owner self-review、另一個 reviewer檢查 correctness/security、主協調者驗 acceptance。GitHub draft PR 可先分享進度；ready 後 required checks 必須針對最新 commit SHA。skipped check 可能顯示成功，因此 workflow trigger 本身也要測。 第七步完成判斷以證據為準：clean diff check、type/lint/test/build、integration/E2E、migration dry-run、preview/live（若要求）。UI renovation 要看所有重要 route 與 mobile，不以單頁 screenshot 代替。Production task 要 remote read/live response，不以 push/deploy success 代替。 失敗與復原 若 agents 同改一檔，先停止其中一方，保存兩份 patch，由 owner依 interface手動整合；不要 checkout -- 或 hard reset shared worktree。衝突解完重新跑兩邊 tests。 若 subtask 宣稱完成但缺 evidence，狀態保持 in review，不推測成功。主協調者要求精確 command/output或自行跑 gate。若 test failure 已存在，要以 baseline 證明；不能混入「可能原本就壞」。 若 branch 長期 drift，先 rebase/merge target 到 isolated worktree，再解衝突與測試；不要在 integration 最後一刻把整個 branch強推 main。遠端 destructive action仍需 task scope與確認，不因 Director Mode 擴權。 若 context/agent 中斷，handoff 包含 goal、done/not done、files、commands/results、current git state、next exact action；新 agent從最新 verified state繼續，不重做已完成 work。 驗證指令 git status --short git diff --check git diff --stat npm run type-check npm run test:run npm run build 整合報告把每個 acceptance criterion映射到 artifact/test/live evidence，列出未解 caveat。確認 latest commit SHA 對應 CI checks，PR diff沒有 unrelated files，worktree/branches 可追溯，rollback commit/artifact存在。 官方來源 Git worktree documentation GitHub Pull requests GitHub Status checks 延伸閱讀 在 技術文章 查看 production stack 與 agent permissions。 從 課程總覽 練習 branch、CI 與 review gate。 大型 repository 工作可查看 顧問服務 。