Fan out subagent trong Claude Code, rồi kiểm tra những gì trả về

Mọi người gõ "claude fan out subagents" vào Google, và khá nhiều người thêm "command" ở cuối, như thể có một công tắc để bật. Có một cách làm, và cũng có một lệnh. Chúng tôi đã kiểm tra cả hai trên Claude Code 2.1.301 và đối chiếu với tài liệu của Anthropic vào ngày 16 tháng 10 năm 2026.

Rồi đến phần tài liệu nói rất ít, cũng là lý do chúng tôi viết bài này: làm gì với kết quả. Chúng tôi chạy một đợt fan-out mỗi đêm. Sáu subagent dịch mỗi bài mới của blog này sang mười bảy ngôn ngữ, và phiên chính gộp công việc của chúng lại. Subagent nào cũng báo rằng nó đã tuân thủ quy tắc. Bước kiểm tra chúng tôi viết trước khi khởi chạy chúng vẫn tìm ra vấn đề.

Câu trả lời ngắn

Fan out nghĩa là một phiên chia công việc thành các phần không phụ thuộc vào nhau, giao mỗi phần cho một subagent, để chúng chạy cùng lúc, rồi gộp những gì trả về. Trong Claude Code, bạn có ba cách làm.

Phần còn lại của trang này đi qua từng cách, rồi đến các bước kiểm tra chúng tôi chạy trên đợt fan-out của chính mình.

Subagent thấy được gì và không thấy được gì

Ba sự thật trong tài liệu quyết định cách bạn chia công việc.

Mỗi subagent bắt đầu trắng trơn. Nó chạy trong cửa sổ ngữ cảnh riêng, với system prompt, công cụ và quyền hạn riêng. Nó không thấy cuộc trò chuyện của bạn, các skill bạn đã dùng hay các tệp Claude đã đọc. Mọi thứ nó cần biết phải nằm trong brief của nó.

Kết quả quay về cuộc trò chuyện chính. Phần dài dòng trong công việc của subagent ở lại trong ngữ cảnh của nó, chỉ kết quả mới quay về. Nhưng nhiều subagent gửi về những báo cáo dài vẫn có thể làm đầy ngữ cảnh chính của bạn, và mỗi cái tiêu token của riêng nó trong lúc chạy.

Có giới hạn. Mặc định, 20 subagent có thể chạy cùng lúc trong một phiên. Cái thứ 21 thất bại với Concurrent subagent limit reached, và lỗi này bảo Claude không thử lại. Bạn có thể tăng hoặc giảm giới hạn bằng CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. Subagent có thể khởi chạy subagent của riêng nó, sâu tối đa ba tầng bên dưới cuộc trò chuyện chính, và tổng số trong một phiên không bị giới hạn.

Cách 1: yêu cầu bằng lời thường

Đợt fan-out đơn giản nhất chỉ là một câu. Ví dụ trong tài liệu của Anthropic:

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

Mỗi subagent khám phá khu vực của mình, rồi Claude viết một bản tổng hợp. Tài liệu bổ sung điều kiện quan trọng: cách này hiệu quả nhất khi các hướng nghiên cứu không phụ thuộc vào nhau. Nếu câu hỏi về cơ sở dữ liệu cần câu trả lời của câu hỏi về auth, bạn không có ba phần việc, bạn có một chuỗi tuần tự.

Dùng lời thường là để Claude tự quyết. Nếu bạn đã định nghĩa một subagent tùy chỉnh trong .claude/agents/, việc @-mention nó đảm bảo nó sẽ chạy cho tác vụ đó. Trang của chúng tôi về subagent của Claude Code giải thích cách các tệp đó hoạt động.

Cách 2: /batch, thứ gần nhất với một lệnh fan-out

/batch là một skill đi kèm Claude Code. Bạn đưa cho nó một chỉ dẫn:

/batch migrate src/ from JavaScript to TypeScript

Nó khảo sát mã nguồn, chia công việc thành 5 đến 30 đơn vị độc lập và cho bạn xem một kế hoạch. Khi bạn duyệt, nó khởi chạy một subagent nền cho mỗi đơn vị, mỗi cái trong một git worktree tách biệt. Mỗi subagent triển khai đơn vị của mình, chạy kiểm thử và công bố thay đổi của nó. Bạn cần một kho git, hoặc một hook WorktreeCreate tạo worktree cho một hệ thống quản lý phiên bản khác.

Kế hoạch là lúc nên chậm lại. Đó là nơi cách chia việc được quyết định, và cách chia việc là tất cả: hai đơn vị cùng sửa một tệp, hoặc một đơn vị cần kết quả của đơn vị khác, sẽ không gộp lại gọn gàng dù từng subagent giỏi đến đâu. Hãy đọc danh sách đơn vị như cách bạn đọc một kế hoạch chuyển đổi mã do đồng nghiệp viết.

Cách 3: một vòng lặp trên claude -p

Khi công việc là một danh sách tệp và bạn muốn kiểm soát từng lần gọi, phần thực hành tốt nhất của Anthropic mô tả một vòng lặp. Trước tiên, nhờ Claude viết danh sách (list all 2,000 Python files that need migrating and save the list to files.txt). Sau đó:

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

Ba chi tiết trong ví dụ đó đáng để chép lại.

• Câu trả lời đọc được bằng máy. "Return OK or FAIL" nghĩa là script của bạn có thể đếm số lần thất bại mà không cần đọc văn xuôi.
• Quyền hạn được quyết định từ trước. --allowedTools cho phép đúng những gì đợt chuyển đổi cần, còn --permission-mode dontAsk từ chối mọi thứ khác thay vì chờ một người không có mặt.
• Bạn bắt đầu với hai hoặc ba tệp. Tài liệu nói thẳng: hãy chỉnh prompt dựa trên những gì sai ở các tệp đầu tiên, rồi mới chạy cả danh sách.

Như đang viết, vòng lặp chạy từng tệp một. Chạy nhiều lần gọi cùng lúc là việc shell bình thường, nhưng mỗi lần gọi là một phiên đầy đủ trên máy của bạn và trên hạn mức của bạn. Chúng tôi đã đo chuyện gì xảy ra khi nhiều agent cùng khởi chạy một lệnh nặng trong cùng một phút trong bài viết này, và ở đây cũng vậy: hãy bắt đầu với ít lần gọi song song.

Với CI, tài liệu khuyên thêm --bare, cờ này bỏ qua hook, skill, máy chủ MCP và CLAUDE.md để máy nào cũng có cùng một lần chạy. Chế độ bare không dùng đăng nhập gói thuê bao của bạn: nó cần ANTHROPIC_API_KEY.

Cách chúng tôi fan out mỗi đêm

Đây là đợt fan-out chúng tôi thực sự chạy. Đội SEO ban đêm của chúng tôi viết tay mỗi bài mới bằng tiếng Anh và tiếng Pháp. Sau đó một agent thứ hai dịch bài sang mười bảy ngôn ngữ khác bằng subagent của Claude Code, và tạo bản tiếng Trung phồn thể từ tiếng Trung giản thể bằng một script thay vì dịch. Mười một bài đã đi qua quy trình này kể từ ngày 13 tháng 9 năm 2026, mỗi bài ra thành hai mươi tệp.

Các phần việc

Sáu subagent, mỗi cái ba ngôn ngữ (cái cuối cùng hai): tiếng Tây Ban Nha, tiếng Bồ Đào Nha và tiếng Ý; tiếng Đức, tiếng Hà Lan và tiếng Ba Lan; tiếng Nga, tiếng Ukraina và tiếng Thổ Nhĩ Kỳ; tiếng Nhật, tiếng Hàn và tiếng Trung; tiếng Thái, tiếng Việt và tiếng Indonesia; tiếng Ả Rập và tiếng Hindi. Không ngôn ngữ nào phụ thuộc vào ngôn ngữ khác, và chính điều đó làm nên một đợt fan-out gọn gàng.

Mỗi brief mang cùng năm thứ, vì subagent không thấy gì khác:

• bản nguồn tiếng Anh, và bản tiếng Pháp làm tham chiếu cho giọng văn và thuật ngữ sản phẩm;
• với mỗi ngôn ngữ, các câu đã được đăng trên trang web bằng ngôn ngữ đó, để subagent dùng lại những từ trang web đang dùng thay vì tự nghĩ ra từ mới;
• các quy tắc cứng: tên thương hiệu và tên sản phẩm giữ nguyên, mã giữ nguyên đến từng byte, không dùng gạch ngang dài (em dash);
• script kiểm tra, kèm chỉ dẫn chạy lại cho đến khi nó báo OK;
• yêu cầu báo lại mọi điều đáng ngờ nó thấy, bên trong hay bên ngoài phần việc của mình.

Bước kiểm tra được viết trước khi khởi chạy

Bước kiểm tra là một script, không phải ý kiến của một subagent. Với mỗi ngôn ngữ, nó so sánh tệp với bản nguồn tiếng Anh:

• cùng slug và ngày, tiêu đề trùng với H1;
• cùng số lượng mục, mục con, hình ảnh, liên kết và hàng trong bảng, và số câu trả lời FAQ trong phần thân bằng số câu hỏi trong siêu dữ liệu;
• liên kết giống hệt đến từng byte, các đoạn mã giống hệt đến từng byte;
• tên thương hiệu được đếm, không bao giờ ít hơn trong tiếng Anh;
• độ dài nằm trong giới hạn được hiệu chỉnh cho từng ngôn ngữ, vì tiếng Trung nói cùng một điều với khoảng 36 % số ký tự mà tiếng Anh cần, còn tiếng Nhật khoảng một nửa;
• có dấu ở những ngôn ngữ có dấu (tiếng Ba Lan, tiếng Thổ Nhĩ Kỳ, tiếng Việt).

Subagent nào cũng kết thúc bằng một biến thể của "xong rồi, mọi bước kiểm tra đều đạt". Phán quyết duy nhất chúng tôi dựa vào để hành động là chính script đó, được phiên chính chạy lại, trên tất cả các tệp cùng một lúc.

Những gì bước kiểm tra trung tâm bắt được mà các bản tự báo cáo không thấy

Mã bị dịch trong một bảng. Ngày 13 tháng 9, khoảng một nửa số subagent đã dịch những từ đứng sau một lệnh bên trong cùng cặp backtick của một bảng. Mỗi cái đều đã làm theo brief của mình như nó hiểu. Cách sửa nằm ở brief, không phải ở các subagent: một đoạn mã chỉ chứa lệnh, còn những từ theo sau nằm ngoài backtick.

Chính bước kiểm tra của chúng tôi sai. Ngày 6 tháng 9, một bước kiểm tra độ dài được hiệu chỉnh theo câu cũ mà chúng tôi đang thay thế đã gắn cờ 11 subagent trên 17. Cả 11 đều đúng: văn bản mới vốn phải dài hơn. Khi được hiệu chỉnh theo bản tiếng Pháp đã sửa, nó không gắn cờ cái nào. Một bước kiểm tra trung tâm cũng có thể sai, và cách để thấy điều đó là chạy nó trước trên một lần bàn giao mà bạn đã biết là tốt.

Tính nhất quán giữa các phần việc. Ngày 15 tháng 10, trên một trang tính năng mới được dịch theo cùng cách, bước kiểm tra khi gộp xác nhận rằng chỉ những câu dự kiến mới thay đổi trên 90 tệp. Nhưng các subagent tiếng Nhật, tiếng Hàn và tiếng Trung mỗi cái lại chọn cho "You may also like" một tiêu đề khác với tiêu đề mà ngôn ngữ của nó đã dùng trên một trang bên cạnh. Mỗi lựa chọn đều là một bản dịch đúng. Không cái nào nhất quán với trang web. Không subagent nào có thể thấy điều đó từ bên trong phần việc của mình: chỉ một lượt rà soát trên kết quả đã gộp mới thấy.

Một từ sai vượt qua mọi bước kiểm tra cấu trúc. Có lần một ngôn ngữ của trang web gọi các agent AI là cửa hàng bán ô tô, và nó nằm trên mạng suốt nhiều tháng. Cùng độ dài, cùng dấu câu, có tên thương hiệu: mọi phép đếm đều xanh. Thứ duy nhất bắt được nó là một danh sách có tên gồm những từ sai đã biết, danh sách này chặn mọi lần triển khai và dài thêm một dòng mỗi khi chúng tôi tìm ra một từ mới.

Những báo cáo ngoài phần việc. Ngày 15 tháng 10, subagent phụ trách tiếng Thổ Nhĩ Kỳ báo rằng trang web viết "ajans", nghĩa là hãng dịch vụ, cho từ "agent" trong 97 câu hiện có. Nó không động vào các câu đó, vì brief của nó cấm làm vậy. Chúng tôi mở một ticket và bản sửa được phát hành ngay hôm sau. Hỏi subagent xem chúng đã thấy gì, chứ không chỉ hỏi chúng đã làm gì, tốn rất ít mà lợi nhiều.

Việc gộp diễn ra ở một nơi

Các subagent không ghi trực tiếp vào kho mã. Mỗi cái trả về các tệp của mình, một script gộp chúng lại, rồi so sánh kết quả với phiên bản trước theo từng câu: chỉ những câu chúng tôi yêu cầu mới được phép thay đổi. Sau đó, các bước kiểm tra của kho mã và bản build trang web chạy một lần, trên kết quả đã gộp. Chạy build một lần cho mỗi subagent sẽ chậm hơn và sẽ kiểm thử những trạng thái gộp dở dang không bao giờ được phát hành.

Khi nào không nên fan out

• Các phần việc phụ thuộc vào nhau. Nếu phần B cần kết quả của phần A, hãy chạy chúng theo thứ tự.
• Công việc nhỏ. Mỗi subagent bắt đầu trắng trơn và đọc lại những gì nó cần. Với một tác vụ mười phút, các lần bắt đầu lại tốn nhiều hơn những gì chúng tiết kiệm được.
• Bạn không viết được bước kiểm tra. Nếu không có cách nào phân biệt một phần việc tốt với một phần việc tồi mà không tự đọc hết, thì việc gộp sẽ là chỗ bạn tiêu tốn thời gian.
• Hạn mức eo hẹp. Mỗi subagent tiêu token của riêng nó. Fan out mua được thời gian và một ngữ cảnh chính gọn gàng, chứ không làm hóa đơn nhỏ lại.

AgentsRoom nằm ở đâu

Subagent sống bên trong một phiên Claude Code duy nhất. Bạn thấy kết quả của chúng, không thấy quá trình làm việc, và bạn không thể điều hướng một cái giữa chừng. Khi bạn muốn mỗi phần việc là một agent mà bạn có thể theo dõi, trả lời và review riêng, hãy chạy các phiên riêng biệt: mỗi ticket trong git worktree riêng của nó, và Agent Teams khi các phần việc chuyển giao công việc cho nhau. Một bước của team có thể mang theo một lệnh kiểm tra, và chính mã thoát của lệnh đó, chứ không phải lời khẳng định của agent, quyết định lần chạy có đi tiếp hay không. Đó là cùng quy tắc ở trên, được bộ chạy thực thi. Cách này hoạt động với Claude Code, Codex và các CLI agent khác mà AgentsRoom hỗ trợ.

Nếu bạn vẫn đang phân vân giữa subagent và Agent Teams, bài so sánh này giải thích mỗi thứ dùng để làm gì.