Claude Code 嘅 Subagent + Worktree pattern：點解一個 AI agent 唔夠用

🛠️ 一個 chief agent 同時改三個 repo，個 context window 唔會爆，但個 git index 一定會。

呢句係 AgentOS 跑咗兩個月 multi-agent dev workflow 之後最具體嘅一條 lesson。下面講三件事：點解 chief agent 唔應該自己寫 code、點解 git worktree 係 parallel @dev 嘅必要條件、background mode 點解唔係 nice-to-have。

Chief agent 唔應該自己寫 code

AgentOS 嘅 topology 好簡單：一隻 chief（阿貓）負責 routing + review，五隻 specialist（dev / writer / researcher / librarian / chief）各自有 own working dir 同 identity file。最初嘅版本，chief 會自己落手改細嘢，name it「one-line edit, config tweak」。

唔得。實際情況係：

Chief 嘅 context 已經塞滿咗 routing rules、daily memory、Telegram thread mapping、最近七日嘅 session history。再叫佢 read + edit 一個 800 行嘅 module，佢嘅 working memory 就會被代碼上下文擠走 routing logic。下一次 Vincent send DM，chief 嘅 reply 質量會明顯跌。
Chief 嘅 system prompt 教佢做 COO，唔係 senior engineer。佢識 review，但下手寫 production code 嘅時候會 hedge、會寫多餘嘅 comment、會無端 refactor 你冇叫佢改嘅嘢。

正路係：standalone code change 一律 spawn @dev（阿犬），用 Agent tool 傳 brief，等佢返結果，chief 只負責 review + ship。CLAUDE.md 入面寫得好白：

Must delegate (spawn agent):
- Standalone code change / new feature / refactor → @dev

唯一例外係 interactive debug。Vincent 喺 chat 度逐步 feedback 嗰種，多輪 turn 唔值得 spawn 新 agent，chief 自己 handle。

Worktree 唔係 over-engineering

派一隻 @dev 冇事。派兩隻同時做嘢，先見真章。

2026-05-06 第一次試 parallel：三隻 @dev 同時做同一個 woof100 repo 三條 parallel feature PR，全部跑同一個 ~/Projects/<project>/ working dir。表面睇好快，實際 commits 撞晒：admin 嘅 untracked files 混入 qbank branch，daily 嘅 commit graft 到 admin branch 之上，要花成個鐘頭 salvage 到 salvage/* branch 再重派。

問題唔係 agent 蠢，係 git 本身設計 single working tree。.git/index 只有一份，三個 process 同時 git add 必定撞。

解決方法係 git 自己提供嘅 worktree：

# Chief spawn 三隻 @dev 之前，先為每隻開獨立 worktree
git worktree add ../project-wt-a  feature/a
git worktree add ../project-wt-b  feature/b
git worktree add ../project-wt-c  feature/c

# 每隻 @dev brief 寫明：
#   cwd = ../project-wt-<tag>
#   branch = feature/<tag>
#   完成後 chief 統一 merge

# 收工
git worktree remove ../project-wt-a --force

一個 repo，三個獨立 checkout，三個獨立 .git/index，完全唔會踩腳跡。三隻 @dev 喺各自 worktree 開 branch / commit / push，最後 chief 一條一條 merge 入 main。

唔記得開 worktree，後果係 silent corruption。PR 表面睇 OK，差咗條 file 入錯 branch 要 git reflog 救返。Worktree 嘅成本只係多打一條命令。

Background mode：parallel ≠ 唔阻塞

第二個 trap 更隱蔽。三隻 @dev 落 worktree，spawn 落去之後，chief 個 turn 仲會被 block。

2026-05-08 嘅事：chief 同時 spawn 兩隻 foreground @dev 改兩個內部 bot 嘅 README，兩條都跑大約 3-5 分鐘。期間 Vincent send DM 問點解 chief 唔回應，因為 Agent tool 嘅 foreground call 會 block 到 child agent 完成為止。即係話 chief 表面 parallel spawn，實際上係兩個 foreground wait 串起黎，Vincent 嘅 chat 完全 unresponsive。

正解係 run_in_background: true：

Spawn @dev:
  description: 內部 bot README rewrite
  prompt: <brief>
  run_in_background: true

Background mode 即刻 return control 畀 chief，agent 喺 background 跑，完成時 push notification 入 chief 嘅 next turn。Vincent 嘅 DM 唔再卡住。

CLAUDE.md 嘅規則：

Project topic dev tasks → run_in_background:true by default
Foreground only when agent output is literal input to chief's next turn

實際 throughput

呢個 pattern 喺 2026-05-14 跑咗一個 concrete test：一個內部 bot 一晚出咗三條 PR（同一 sub-system、互相 dependency-free），三隻 @dev parallel + background + worktree，chief 期間繼續處理 Vincent 嘅 DM、跑 knowledge digest follow-up、ack 兩個 cross-project ticket。如果係 single-agent serial，呢晚最多得一條 PR。

3x throughput 嘅前提係三條 brief 真係 independent，唔可以有 A 等 B 條 PR 嘅 dependency。Chief 嘅 routing decision 就係決定條條 task 食唔食得切片。

Stance

Multi-agent 唔係 trendy，係 git 同 LLM context window 嘅自然推論：一個 working dir 一個 chief 一個 context，做唔到 parallel；分頭做，先有 throughput。

Subagent、worktree、background 三件事疊埋一齊，唔複雜，但唔係其中一件就唔 work。