在Claude Code中fan out subagent，再檢查返回的結果

很多人在Google裡輸入「claude fan out subagents」，還有不少人在後面加上「command」，好像有個開關可以一撥就開。其實有一種做法，也有一個命令。我們在2026年10月16日用Claude Code 2.1.301和Anthropic的文件核對了這兩者。

還有一部分是文件很少提到的，也是我們寫這篇文章的原因：拿到結果之後該怎麼辦。我們每晚都執行一次fan out。六個subagent把這個部落格的每篇新文章翻譯成十七種語言，主會話再合併它們的工作。每一個subagent都報告說自己遵守了規則。可我們在啟動前寫好的檢查，仍然會發現問題。

簡短的回答

fan out指的是一個會話把一項工作拆成互不依賴的分片，把每個分片交給一個subagent，讓它們同時執行，再合併返回的內容。在Claude Code中有三種做法。

本文接下來逐一介紹每種做法，然後介紹我們在自己的fan out上執行的檢查。

subagent能看到什麼，看不到什麼

文件中的三個事實決定了你該怎麼拆分工作。

每個subagent都從零開始。 它在自己的上下文視窗中執行，有自己的系統提示詞、工具和權限。它看不到你的對話，看不到你已經用過的技能，也看不到Claude已經讀過的檔案。它需要知道的一切，都必須寫在它的任務簡報裡。

結果會回到主對話。 subagent工作中冗長的部分留在它自己的上下文裡，只有結果會返回。但如果很多subagent都返回很長的報告，仍然可能塞滿你的主上下文，而且每個subagent在執行時都消耗自己的令牌。

有上限。 預設情況下，一個會話中同時最多執行20個subagent。第21個會以Concurrent subagent limit reached失敗，而且這個錯誤會告訴Claude不要重試。你可以用CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS調高或調低這個上限。subagent可以啟動自己的subagent，最多到主對話下方三層，一個會話中的總數沒有限制。

做法一：直接用自然語言要求

最簡單的fan out就是一句話。Anthropic文件中的例子：

Research the authentication, database, and API modules in parallel using separate subagents

每個subagent探索自己的部分，然後Claude寫出一份綜合結論。文件補充了關鍵的條件：調研路線互不依賴時效果最好。如果關於資料庫的問題需要先知道關於auth的答案，那你手裡的不是三個分片，而是一個先後順序。

用自然語言要求時，由Claude來決定。如果你在.claude/agents/中定義了自定義subagent，用@提到它，就能保證它在這個任務中執行。這些檔案如何工作，見我們關於Claude Code subagents的頁面。

做法二：/batch，最接近fan out命令的東西

/batch是Claude Code內建的一個技能。你給它一條指令：

/batch migrate src/ from JavaScript to TypeScript

它會研究程式碼庫，把工作拆成5到30個獨立單元，並給你看一份計劃。你批准後，它為每個單元啟動一個後台subagent，每個都在隔離的git worktree中。每個subagent實現自己的單元，執行測試，併發布自己的改動。它需要一個git儲存庫，或者一個為其他版本控制系統建立worktree的WorktreeCreate鉤子。

計劃這一步要放慢。拆分就是在這裡決定的，而拆分就是全部：兩個改動同一個檔案的單元，或者一個需要另一個單元輸出的單元，不管每個subagent多出色，都無法乾淨地合併。讀這份單元清單時，要像讀一位同事寫的遷移計劃那樣。

做法三：用claude -p迴圈

當工作是一份檔案清單、而你想掌控每一次呼叫時，Anthropic的最佳實踐介紹了一種迴圈。先讓Claude寫出清單（list all 2,000 Python files that need migrating and save the list to files.txt）。然後：

for file in $(cat files.txt); do
  claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)" \
    --permission-mode dontAsk
done

這個例子裡有三個細節值得照搬。

• 回答讓機器來讀。 「Return OK or FAIL」意味著你的腳本不用讀文字就能統計失敗數。
• 權限提前定好。 --allowedTools只批准遷移所需的操作，--permission-mode dontAsk拒絕其餘一切，而不是等一個不在場的人。
• 先從兩三個檔案開始。 文件說得很直白：根據前幾個檔案出的問題改進提示詞，再跑完整清單。

按原樣寫，這個迴圈是一個檔案接一個檔案處理的。同時執行多個呼叫只是普通的shell操作，但每次呼叫都是一個完整的會話，佔用你的機器和你的配額。我們在這篇文章裡測量過多個代理在同一分鐘啟動同一條重型命令時會發生什麼，這裡也是同樣的道理：並行呼叫先從少量開始。

對於CI，文件建議加上--bare，它會跳過鉤子、技能、MCP伺服器和CLAUDE.md，讓每台機器都得到相同的執行結果。bare模式不使用你訂閱的登入：它需要ANTHROPIC_API_KEY。

我們每晚如何fan out

下面是我們真正在執行的fan out。我們的夜間SEO團隊手工用英文和法文撰寫每篇新文章。接著第二個代理用Claude Code的subagent把它翻譯成另外十七種語言，並用腳本從簡體中文生成繁體中文，而不是重新翻譯。自2026年9月13日以來，已有十一篇文章走過這個流程，每篇最終是二十個檔案。

分片

六個subagent，每個負責三種語言（最後一個負責兩種）：西班牙語、葡萄牙語和義大利語；德語、荷蘭語和波蘭語；俄語、烏克蘭語和土耳其語；日語、韓語和中文；泰語、越南語和印尼語；阿拉伯語和印地語。沒有任何一種語言依賴另一種，這正是它成為一次乾淨fan out的原因。

每份任務簡報都包含同樣的五樣東西，因為subagent看不到別的：

• 英文原文，以及作為語氣和產品術語參考的法文版；
• 每種語言在網站上已經發布的句子，讓subagent沿用網站已有的用詞，而不是自己發明新詞；
• 硬性規則：品牌名和產品名保持原樣，程式碼逐位元組不變，不用長破折號；
• 檢查腳本，並要求一直執行到它返回OK為止；
• 要求它報告看到的任何可疑之處，無論在自己的分片之內還是之外。

檢查在啟動前寫好

檢查是一個腳本，而不是某個subagent的意見。它把每種語言的檔案與英文原文對比：

• slug和日期相同，標題與H1一致；
• 章節、小節、圖片、連結和表格行數相同，正文中的FAQ回答數與後設資料中的問題數相同；
• 連結逐位元組相同，程式碼片段逐位元組相同；
• 統計品牌名出現次數，絕不能少於英文；
• 長度在為每種語言校準的範圍內，因為中文說同樣的內容大約只需要英文36%的字元，日文大約一半；
• 有重音符號的語言要帶上重音符號（波蘭語、土耳其語、越南語）。

每個subagent最後都會說一句類似「完成，所有檢查透過」的話。我們唯一據以行動的判定，是由主會話對所有檔案一次性重新執行的同一個腳本。

中央檢查發現了、而自我報告沒有提到的問題

表格裡的程式碼被翻譯了。 9月13日，大約一半的subagent把表格中與命令放在同一對反引號裡的後續文字翻譯了。每個都按自己理解的方式遵循了任務簡報。修正落在任務簡報上，而不是subagent上：程式碼片段裡只放命令，後面的文字放到反引號外面。

我們自己的檢查錯了。 9月6日，一個按我們要替換的舊句子校準的長度檢查，在17個subagent中標記了11個。這11個都是對的：新文字本來就應該更長。改為按已修正的法文校準後，一個都沒有被標記。中央檢查也可能出錯，發現它的辦法是先在一份你已知沒問題的交付物上執行它。

分片之間的一致性。 10月15日，在一個用同樣方式翻譯的新功能頁面上，合併檢查確認90個檔案中只有預期的句子發生了變化。但日語、韓語和中文的subagent，各自為「You may also like」選了一個標題，與它們的語言在相鄰頁面上已經使用的不同。每個選擇都是正確的翻譯。沒有一個與網站一致。沒有哪個subagent能從自己的分片裡看到這一點：只有對合並結果做一遍檢查才能看到。

一個錯詞能透過所有結構檢查。 網站的某種語言曾經把AI代理稱作汽車經銷商，而且線上上掛了好幾個月。長度相同，標點相同，品牌名也在：所有計數都是綠色。唯一能抓住它的，是一份列出已知錯詞的清單，它會攔下每一次部署，每發現一個新錯詞就增加一行。

分片之外的報告。 10月15日，負責土耳其語的subagent報告說，網站在97個現有句子裡把「agent」寫成了「ajans」，也就是代理機構。它沒有去改，因為任務簡報不允許。我們開了一個工單，修復在第二天上線。問subagent看到了什麼，而不只是做了什麼，代價很小，回報不錯。

合併在一個地方完成

subagent不直接寫入儲存庫。每個都交回自己的檔案，由腳本合併，然後逐句把結果與上一個版本比較：只有我們要求修改的句子才允許變化。之後，儲存庫的檢查和網站的建置只在合併後的結果上執行一次。每個subagent各跑一次建置會更慢，而且測試的是永遠不會上線的半合併狀態。

什麼時候不要fan out

• 分片之間互相依賴。 如果分片B需要分片A的輸出，就按順序執行。
• 工作量很小。 每個subagent都從零開始，重新讀取它需要的內容。對一個十分鐘的任務來說，重新開始的成本比省下的還多。
• 你寫不出檢查。 如果不親自全部讀一遍就無法區分好分片和壞分片，你的時間就會花在合併上。
• 配額很緊。 每個subagent都消耗自己的令牌。fan out換來的是時間和乾淨的主上下文，而不是更少的帳單。

AgentsRoom的位置

subagent活在一個Claude Code會話的內部。你看到的是它們的結果，而不是它們的工作過程，也無法在中途引導其中某一個。如果你希望每個分片都是一個可以單獨觀察、回覆和審查的代理，那就改為執行獨立的會話：每個工單在自己的git worktree裡，分片之間需要交接工作時用Agent Teams。團隊中的一個步驟可以帶上一條檢查命令，決定這次執行能否繼續的，是它的退出碼，而不是代理自己的說法。這和上面是同一條規則，由執行器來執行。它適用於Claude Code、Codex以及AgentsRoom支援的其他代理CLI。

如果你還在subagent和Agent Teams之間猶豫，這篇對比解釋了它們各自適合做什麼。