多代理、平行工作流與自動化管線

先給結論：高手不是常態開 swarm；高手是知道哪些未知數適合平行查、哪些決策必須留在同一條主線，以及什麼時候該把 writer 搬進獨立 worktree。

14.1 為什麼 Claude subagent 愛用者可能覺得 Claude 比較順？

這種感受不奇怪，而且可以用產品設計解釋，不必急著化約成「哪個模型比較強」。Claude Code 把兩種心智模型直接拆開：具名 subagent 預設從 fresh context 開始；/subtask 則 fork 既有對話。CLI 另有 --worktree，custom agent 也能選配 isolation: worktree。✅Claude 官方 對已習慣 CLAUDE.md、Markdown agent 定義與 /agents 管理的人，整條路徑可能更像同一套文法。🧪使用感推論

Codex 現在也有內建 explorer／worker、自訂 TOML agents、context fork、/agent thread 檢視、App managed worktree／Handoff 與 CLI /review。✅Codex 官方 「Claude 比較順」可能與 discoverability、肌肉記憶、agent 定義的組織方式及 CLI worktree 摩擦有關；目前沒有公平 benchmark 能把這種感受升格成速度、品質或成本優勢。 🧪比較推論

14.2 Codex 現在到底有什麼？先畫清楚邊界

現行 Codex releases 預設啟用 subagent workflows。你可以直接要求委派，也可以讓適用的 AGENTS.md 或 Skill 指示觸發；CLI 用 /agent 查看、切換 agent threads，主線最後收集與整合結果。每條子線會做自己的 model 與 tool work，所以 token 通常高於可比的單 agent run。✅官方

最重要的一句：agent thread 是 context／責任分線；worktree 才是 checkout 分線。目前公開的本機 V2 實作顯示 agents 共用 container、filesystem 與 cwd，一條線的修改會立刻被其他線看到。這也是為什麼官方建議從 read-heavy 工作 fan-out，對 write-heavy 並行更保守。✅公開文件 🧪官方 repo 實作快照

14.3 決策框架：fan-out 還是維持單 agent？

別用「任務看起來很大」當 fan-out 的理由。真正的判準是：能否把它拆成互不阻塞、各自有 done criteria、結果能低成本合併的子題。

OpenAI 的 Subagents 文件把 exploration、tests、triage、summarization、log analysis 列為平行起點，並警告 write-heavy workflow 的衝突與 coordination overhead。Symphony 團隊也明說，模糊、需要高度判斷的工作仍適合直接交給一條互動式 Codex。✅官方

Simon Willison 的實務則更像一句檢查碼：平行研究，序列整合。他的 scout 可以只交「相關檔案、限制、可能方案」，不期待 patch；真正的大改仍受限於人類一次能認真驗幾份 diff。👤Simon Willison，2025-10-05

30 秒 fan-out 檢查

1. 至少有兩個子題能同時開始嗎？
2. 每條線能寫出自己的「完成定義」嗎？
3. 其中一條失敗時，其他線的結果仍有價值嗎？
4. 它們不會同時改同一個 write set／shared state 嗎？
5. 主代理能用摘要與證據整合，不必重讀每條完整 log 嗎？

五題只要有兩題答「不確定」，先維持單 agent，或先派一條 explorer 把未知數降下來。這是實務決策法，不是官方效能公式。🧪綜合推論

14.4 用對角色：explorer、worker、default 與 custom agents

官方把 explorer 稱為 read-heavy，不是「權限上一定不能寫」。若你真的要機械式唯讀，委派前先把 parent turn 的 permission mode 選成唯讀，custom agent 也設 sandbox_mode = "read-only"；parent 的 live runtime override 會在 spawn 時重新套用，所以不要只看 TOML 就假設有效。✅官方

Context：Claude 的 fresh，不等於 Codex 的預設

Codex 公開產品文件保證子代理在自己的 thread 工作、主線收摘要；2026-07-26 的官方 repo V2 實作另顯示 fork_turns 可為 none、all 或正整數 N，省略時是 all。目前 fork 也不是複製全部內部內容：tool calls、tool results、hidden reasoning 與 agent 間訊息會被過濾。🧪官方 repo 實作快照

14.5 自訂 agent：用 TOML 鎖角色，不靠長篇人格扮演

個人 agent 放 ~/.codex/agents/；專案共享 agent 放 .codex/agents/。standalone 檔案公開必填只有 name、description、developer_instructions，並可覆寫一般 session config，例如 model、reasoning、sandbox、MCP 與 Skills。✅官方

這是一個以唯讀為預設、只交證據的專案 explorer（委派前仍要確認 parent turn permission）：

name = "evidence_explorer"
description = "Read-only explorer that traces code and returns file:line evidence."
sandbox_mode = "read-only"
model_reasoning_effort = "medium"

developer_instructions = """
Stay read-only. Never modify, create, rename, or delete files.
Answer only the assigned question.
Trace the real execution path and cite file:line evidence.
Separate confirmed facts, inferences, and unknowns.
Return concise findings; do not propose a patch unless asked.
"""

全域多代理設定則放在一般 config 的 [agents] 段：

[agents]
enabled = true

# 教學示例值，不是官方預設：
max_concurrent_threads_per_session = 3
default_subagent_reasoning_effort = "medium"
interrupt_message = true

agents.enabled 預設為 true；未設定併發上限時，由 Codex 選擇預設。舊 agents.max_threads 只是 legacy alias。Config basics 也仍列出 Stable、預設 true 的 [features].multi_agent；兩者都是公開設定，本章不武斷推測它們的內部組合語意。✅官方

custom agent 可提供 model／effort；未設定值會依當前 config／spawn precedence 解析。由於 full-history fork 與 override 行為仍可能受 surface／rollout 影響，寫 automation 前要核對當下 schema 與子線 status，不把單一固定 commit 的 precedence 寫成永久 contract。🧪rollout-sensitive 實作

14.6 一份好 brief 要寫什麼？Goal 不夠，還要有交付合約

官方 Subagents 文件要求說清楚：工作怎麼分、主代理要不要等、子線要回什麼；Best practices 再補 Goal、Context、Constraints、Done when。具名實務者的公開 workflow 則反覆出現 ownership、non-goals、proof command 與 blocked escape hatch。✅官方 👤具名第一手實踐

九格 brief 合約

1. 角色／任務：explorer、worker 還是 reviewer？
2. 目標：只寫一個可驗收結果。
3. 輸入與 source of truth：issue、spec、檔案、branch。
4. 允許讀取範圍：避免全 repo 漫遊。
5. 唯一 ownership：精確到檔案／module／worktree。
6. Constraints／non-goals：介面、不變條件、明確不做什麼。
7. 完成證據：file:line、URL、command、exit code、rendered evidence。
8. 交付格式：摘要、檔案、風險、未驗證項。
9. 阻塞合約：何時停、向誰回報，禁止怎麼繞過 gate。

Prompt A：三條唯讀研究線，主代理唯一寫入

使用 3 個唯讀 subagents 並行研究以下互不重疊的問題：
1. 〈研究題 A〉
2. 〈研究題 B〉
3. 〈研究題 C〉

共通規則：
- 子代理不得修改、建立或刪除任何檔案。
- 每條線只處理自己的題目，不重做其他線。
- 只採〈允許的來源種類〉。
- 回傳：結論、file:line 或 URL 證據、日期、未驗證項、排除項。
- 主代理等三條全部完成再綜合。
- 只有主代理可修改〈精確檔案清單〉。
- 完成後跑〈checks〉，再對整體 diff 做唯讀 review。

Prompt B：唯讀 explorer

你是唯讀 explorer。不要修改、建立或刪除任何檔案。

目標：
回答〈具體問題〉。

只讀範圍：
〈repo／目錄／檔案〉

必須交付：
1. 涉及的檔案與行號
2. 現行行為與限制
3. 2–3 個可行方案及取捨
4. 風險、未知與需要主代理決定之處
5. 建議的最小驗證命令

找不到證據時標記 UNVERIFIED，不要猜。

Prompt C：有 ownership 的 worker

目標：
〈單一、可驗收的結果〉

唯一 source of truth：
〈spec／issue／plan 路徑〉

你的 ownership：
只可修改〈精確檔案〉。
若有其他並行 writer，你必須在〈專屬 worktree〉的〈專屬 branch〉
另開〈專屬頂層 session〉；缺任何一項就不要平行寫入。

既有介面／不變條件：
〈API、schema、design token、相依輸出〉

Non-goals：
〈明確列出不做事項〉

完成證據：
執行〈精確命令〉並回報 exit code；UI 改動附 rendered evidence。

阻塞合約：
若 gate 失敗、需要跨出 ownership、共享介面未定或遇到其他 agent 衝突，
立即停止並回報；不可繞過驗證，也不可改別人的檔案。

輸出：
變更摘要、檔案清單、驗證結果、剩餘風險。

Prompt D：只找可行動問題的 reviewer

你是唯讀 reviewer，不要修檔。

審查範圍：
〈branch／diff／commit／spec〉

依序檢查：
1. 是否符合 source of truth 與 scope
2. 正確性、回歸與邊界案例
3. 測試是否真的覆蓋本次行為
4. 是否誤改共享介面或其他 agent 的 ownership
5. 是否有未證明的聲稱

輸出：
MUST_FIX、SHOULD_FIX、NO_ACTION。
每項附檔案／行號、理由與最小重現或驗證方式。
若無可行動發現，明確寫「no actionable findings」。

14.7 平行寫入的鐵律：不要讓兩個 writer 共用同一 checkout

多代理最常見的概念錯誤，是以為「不同 agent thread」自然等於「不同檔案世界」。在現行本機 Codex，多條 agent 線共用 cwd／filesystem；即使 brief 寫得再客氣，檔案、branch、generated artifacts、dev server 與 port 仍可能撞在一起。🧪官方 repo 實作快照

本站安全預設：一個 checkout，一位 writer

1. 多條 explorer／reviewer 線保持唯讀。
2. 主代理彙整證據、凍結 interface 與最小修改方案。
3. 只讓主代理或一位 worker 寫目前 checkout。
4. 完成後序列跑 checks、整體 diff review、rendered proof。

這不是保守到不用多代理；它其實把最適合平行的「找未知數」放大，同時把最容易互砸的「整合」保留單一 owner。

真的需要多 writer：專屬 worktree＋branch＋頂層 session

Codex desktop app 能替 independent chats 建 managed worktrees；預設是 detached HEAD，完成後可 Handoff 回 Local 或另走 Git 流程整合。CLI 目前沒有同等的官方 managed-worktree 旗標；用原生 Git 建 checkout 與 branch，再各開一個獨立頂層 Codex session。✅官方

git worktree add ../myapp-feature-a -b feature/a
git worktree add ../myapp-feature-b -b feature/b
git worktree list

接著在兩個目錄各開一個頂層 session，brief 明寫 branch、owned paths、shared interface 與 proof。不要在一條本機 subagent session 裡假裝 cwd 已自動分裂。

Jesse Peplinski 的 Codex App worktree 實務特別強調：worktree 不會取代 build、test、smoke 與 merge check，也不會自動替你分配 port。這是具名作者的個人流程，不是效能保證，但很適合拿來補「Git 只隔離檔案世界」的盲點。👤Jesse Peplinski，2026-05-18

14.8 高手怎麼用：不是一種流派，而是三種工作形狀

形狀一：Scout → 主線定案 → 單 writer

Simon Willison 把 agent 當 scout：它可以接受難題，找出相關檔案、約束與可行方案，但不預期直接合併它的 code。主線拿到地圖後凍結 spec，再交一位 owner 寫。這個模式特別適合 root cause 不明的 bug、陌生 codebase 與設計選項尚未收斂的重構。👤Simon Willison

形狀二：Issue DAG → 獨立 workspace → Human Review

OpenAI 的 Symphony 參考實作把 issue tracker 當 control plane，每張 issue 有 deterministic workspace，只派已解除阻塞的 DAG 節點，並記錄 bounded concurrency、retry／backoff、turn／token telemetry 與 human-review 狀態。重點不是範例一次開幾位 agent，而是未解依賴不派、狀態可恢復、驗收是獨立 gate。✅官方團隊第一手 🧪preview spec

形狀三：把 repo 變成 agent 能自己證明的環境

OpenAI Codex 團隊的 Harness engineering 經驗，是讓每個 worktree 都能獨立啟動 app、看 logs／metrics、操作 browser，並把命名、架構與品質規則逐步變成 lint、結構測試與工具。AGENTS 保持成短導覽，詳細規格進版本化文件。✅官方團隊第一手 這提醒你：增加 agent 數量不會自行補救一個無法測試、無法觀測、規則只存在人口相傳的 repo。 🧪綜合推論

14.9 驗收：子代理說「完成」不等於 PASS

多代理工作流最危險的捷徑，是把每條線的自述拼起來就交付。主代理必須重新建立一條可追溯證據鏈：

1. Scope check：changed files 是否都在 ownership？有沒有漏做 non-goal 邊界？
2. Integration check：先看整體 git diff，確認 shared interface 與合併順序。
3. Mechanical gates：跑最小能證明行為的 tests、lint、format、typecheck、build。
4. Behavior proof：能啟動就跑 smoke／E2E；UI 改動量 overflow、console、viewport，並留 screenshot／baseline。
5. Independent review：用唯讀 reviewer 或 CLI /review 找 correctness、regression、security、test gaps。
6. Human judgment：審查真正的 diff 與風險；不要只看 agent 摘要。

在 Codex CLI，/review 會啟動 dedicated reviewer，可選 base branch、未提交變更、commit 或 custom instructions，回 prioritized actionable findings，而且不改 working tree。App／IDE 的 review chat／Detached 行為要依各自 surface 文件看，不能直接套用這四個 CLI 選項。它們都是一雙獨立眼睛，不是測試 runner，也不是核可權的替代品。✅官方

等所有 workers 結束後：
1. 主代理先檢查整體 git diff 與 ownership。
2. 執行〈tests／lint／typecheck／build／rendered checks〉。
3. 二擇一：另開唯讀 custom reviewer，或在 CLI 執行 /review；
   每項發現必須附 file reference 或重現步驟。
4. 只有高風險變更才做兩層獨立審查，並預先限制修正迴圈。
5. 不得把 worker 自述、測試檔存在或 reviewer 沒回報，單獨視為 PASS。

四值驗證，不要把沒測過塗成綠色

Simon Willison 的「交付你已證明能運作的 code」實務，要求 automated tests 之外仍要人工示範；視覺變更要有 screenshot。這不是 Codex 專屬功能，但正好補上 agent 自我宣告最容易漏掉的一段。👤Simon Willison，2025-12-18

14.10 成本控制：fan-out 是用 token 買平行與乾淨 context

可跨版本保守引用的核心成本事實是：每個 subagent 都有自己的 model／tool work，所以可比情境下會比單 agent 多用 token。✅官方 目前沒有公開、穩定、可泛化的「N 個 agent 就精確 N 倍」公式；較便宜的單次模型是否因重工、re-review 而提高總成本，也缺同條件對照。🧪研究邊界／推論

可以用這個心智帳本估算，但它不是計費公式：

總成本 ≈ 主線決策
       + Σ（每條子線的 context + reasoning + tool work）
       + 整合重讀
       + 驗證與 reviewer
       + 衝突／錯誤造成的返工

六個真正有用的控制桿

1. 先限制 agent 數：第一次從 2–3 條獨立唯讀線開始，不追求滿載。
2. 限制 concurrency：用 max_concurrent_threads_per_session 設上限；這是容量上限，不是目標。
3. 按風險路由 model／effort：封閉的探索用較快／較省的可用模型與 low／medium；跨檔推理、security、reviewer 才升高。
4. 縮小帶入 context：能寫自足 brief 就別無意義搬完整 parent 對話歷史；若工具暴露 fork_turns，再依當前 schema 選 none／最近 N turns。
5. 只回 distilled findings：結論、證據、未知、下一步；不要把 raw logs 全回灌主線。
6. 限制 review loop：例如最多兩輪；仍有爭議就回主代理／人類裁決，不讓 reviewer ping-pong 無限繁殖。

最多使用 3 個 subagents，只 fan-out 彼此獨立的讀取工作。
探索線使用較快、較省的可用 model 與 medium／low effort；
只有需要跨檔推理的 reviewer 使用 high。

若兩條線會修改同一檔、依賴前一條結論，
或無法定義各自 done criteria，維持單 agent。
每條線只回 distilled findings，不附完整 logs。
reviewer 修正迴圈最多 2 輪；仍有爭議時交回主代理／人類。

第三方公開 workflow 也提醒：小模型若需要更多回合、更多 re-review 或最後仍要強模型重做，總成本不一定較低。這是合理的實務風險，不是官方 benchmark。🌐公開 workflow／issue

14.11 Claude → Codex：最低摩擦的遷移路線

四階段遷移，不要第一天就複製整隊

1. 階段 1：一主多讀——主代理做所有決策與寫入，只讓 1–3 條 explorer 找證據。
2. 階段 2：角色化——把反覆出現的 explorer／reviewer brief 寫成 project custom agents，必要時設唯讀 sandbox。
3. 階段 3：單一 worker——spec 凍結後，讓一位 worker 擁有明確 paths 與 proof command；主代理整合。
4. 階段 4：隔離多 writer——只有 ownership、interface 與驗收都能預先切開時，才讓每位 writer 以專屬 branch、專屬 worktree 與專屬頂層 session 工作。

這條路線刻意保留 Claude 使用者熟悉的「主線做判斷、子線做封閉任務、另一條線審查」，只把 agent 定義、thread 操作與 worktree 入口換成 Codex 的現行 surface。它是遷移建議，不是兩個產品性能等價的宣告。🧪綜合推論

14.12 版本清場：本章修掉哪些過時說法？

spawn_agents_on_csv 的移除有不可變官方 commit 與 0.145.0 release 可核對；不是「暫時找不到文件」。max_depth 與 shared cwd 則以當日官方 repo 實作快照補公開文件的細節。✅官方 release／commit 🧪實作快照

小結

• ✅ Claude 使用者覺得較順，可能與 fresh／fork 心智模型、CLI worktree、agent 管理 UX 與肌肉記憶有關；沒有公平公開 benchmark 能把感受升格成客觀勝負。
• ✅ Codex 現行有預設開啟的 subagents、/agent、default／worker／explorer、custom TOML agents、context fork、App worktree／Handoff 與 CLI /review。
• ✅ fan-out 優先用在互不依賴的探索、測試、triage、log 與 review；小改、同檔、循序決策與高互動任務保留單 agent。
• ✅ brief 要有 goal、source of truth、ownership、constraints、non-goals、proof、交付格式與 blocked contract。
• ✅ subagent thread 不隔離 checkout；本站安全預設是多讀一寫。多 writer 時，每位 owner 都要有專屬 worktree、專屬 branch 與專屬頂層 session。
• ✅ 主代理要重看整體 diff、跑 gates、做 runtime／rendered proof，再交唯讀 reviewer 或 CLI /review；子代理自述不是 PASS。
• ✅ 成本同時受 agent 數、context、model／effort、tool work、review loop 與返工影響；併發上限不是應開數。
• ✅ 本章已移除 CSV fan-out、固定 max_threads=6、max_depth=1、job runtime 與 standalone nickname_candidates 等過時教學。

動手試試

1. 挑一個陌生模組，用 14.6 的 Prompt A 開兩到三條唯讀研究線；要求 file:line、未驗證項與排除項，主代理不要讓任何子線寫檔。
2. 建立 .codex/agents/evidence-explorer.toml，設 sandbox_mode = "read-only"；委派前把 parent permission 選成唯讀，再用 /agent 檢查子線是否真的以你預期的角色工作。
3. 拿一個近期小改套 14.3 的五題檢查。若不值得 fan-out，刻意用單 agent 完成，記下省掉哪些委派／整合成本。
4. 挑一個能切開的雙模組任務，先只寫 brief：owned paths、shared interface、proof command、port ownership、blocked contract，以及兩套專屬 worktree／branch／頂層 session。沒有全答出來前，不要開第二位 writer。
5. 完成一個 change 後，先跑最小 checks，再用 Prompt D 或 CLI /review 做唯讀審查；最後以 PASS／FAIL／N/A／UNVERIFIED 回報。

來源與查證邊界