Báo cáo phân tích sự cố Pipeline đa tác tử: 5 kiểu điều phối subagent đi sai (2026)

Giới thiệu #

Điều phối đa tác tử là mẫu hình mạnh mẽ nhất — và cũng âm thầm nguy hiểm nhất — trong Claude Code. Khi nó hoạt động, bạn quét toàn bộ codebase song song, nhận được rà soát độc lập, và xử lý những bài toán mà một cửa sổ ngữ cảnh không bao giờ chứa nổi. Khi nó hỏng, nó hỏng trong âm thầm: pipeline báo thành công, bạn ship, và con bug mà nó lẽ ra phải bắt được đã nằm sẵn trong production.

Đây là báo cáo phân tích sự cố về năm kiểu lỗi mà chúng tôi thực sự đã gặp khi vận hành pipeline tác tử trong production. Mỗi kiểu đi kèm triệu chứng bạn sẽ thấy, nguyên nhân gốc bên dưới, và cách khắc phục. Nếu bạn đã đọc Mẫu hình Subagent và Hướng dẫn tự viết Agent tùy chỉnh và giờ đang vận hành điều phối thật, thì đây là bài giúp bạn tránh sa hố.

Lỗi 1: Cái bẫy lòng tin #

Triệu chứng. Orchestrator của bạn báo “module auth đã được refactor, tất cả test đều pass.” Bạn ship. Runtime vỡ ngay lập tức trên một đường dẫn mà các “test đã pass” kia chưa bao giờ bao phủ.

Nguyên nhân gốc. Một subagent trả về một bản tóm tắt — mô tả về những gì nó định làm, không phải bằng chứng đã kiểm chứng về những gì nó đã làm. “Tất cả test đều pass” có thể nghĩa là nó đã chạy test, hoặc có thể nghĩa là nó tin rằng test sẽ pass. Orchestrator đã coi văn xuôi như sự thật cơ sở.

Cách khắc phục. Kiểm chứng dựa trên hiện vật, không bao giờ dựa trên bản tóm tắt. Sau khi một subagent tuyên bố một thay đổi, orchestrator đọc git diff thực tế, kiểm tra mã thoát của lệnh test, hoặc đọc lại file. Chúng tôi học bài này bằng cách trả giá đắt — và đó là lý do vì sao, khi chúng tôi viết một bài viết 4 ngôn ngữ bằng subagent dịch thuật, chúng tôi chạy npm run build như sự thật cơ sở thay vì tin vào câu “YAML hợp lệ: có” của tác tử. Bản tóm tắt là một lời tuyên bố. Lệnh build là bằng chứng.

Lỗi 2: Rò rỉ ngữ cảnh #

Triệu chứng. Hai subagent chạy song song. Phần chỉnh sửa của một con biến mất, hoặc file kết thúc với những đoạn merge dở dang lộn xộn từ cả hai.

Nguyên nhân gốc. Cả hai tác tử cùng ghi vào một file, hoặc mỗi con giả định một trạng thái working-tree mà con kia đã thay đổi bên dưới nó. Việc các bên ghi song song cùng chia sẻ một working tree là một race condition kèm thêm vài bước phức tạp.

Cách khắc phục. Phạm vi tách biệt và cô lập bằng worktree. Giới hạn tác tử A vào /auth/, tác tử B vào /payments/, không chồng lấn chút nào. Khi các tác tử thực hiện chỉnh sửa đáng kể, hãy giao cho mỗi con một git worktree riêng để chúng làm việc trên các checkout độc lập rồi bạn merge một cách có chủ đích về sau. Đừng bao giờ để hai bên ghi cùng chia sẻ một cây.

Lỗi 3: Fan-out mất kiểm soát #

Triệu chứng. Một lượt chạy lẽ ra chỉ tốn vài nghìn token lại tốn gấp 10 lần con số đó. Hoặc pipeline không bao giờ kết thúc — nó cứ tiếp tục sinh tác tử.

Nguyên nhân gốc. Việc sinh tác tử nằm bên trong một vòng lặp không có điều kiện hội tụ, hoặc fan-out ra nhiều worker hơn nhiều so với mức công việc đòi hỏi. Mỗi subagent ngốn cả một ngữ cảnh đầy token; fan-out theo phản xạ nhân chi phí lên rất nhanh.

Cách khắc phục. Một ngân sách và một điều kiện dừng. Giới hạn số tác tử mỗi giai đoạn. Với các vòng lặp khám phá (“tìm tất cả các bug”), hãy dùng “dừng sau K vòng liên tiếp không tìm thấy gì mới” thay vì “cứ chạy” không có điểm dừng. Hãy fan-out có chủ đích, với một con số bạn cố ý chọn. Điều này càng quan trọng gấp đôi khi bạn đang theo dõi chi phí — xem phép tính token thực sự hoạt động ra sao trước khi bạn mở rộng quy mô một pipeline.

Lỗi 4: Cắt cụt âm thầm #

Triệu chứng. Pipeline báo “kiểm toán bảo mật hoàn tất — không phát hiện vấn đề nào.” Một tuần sau, một con bug injection lộ liễu nổi lên trong đoạn mã mà cuộc kiểm toán cho là đã bao phủ.

Nguyên nhân gốc. Một tác tử dò tìm đã giới hạn kết quả ở top N, hoặc lấy mẫu thay vì quét toàn bộ bề mặt — và không ai ghi lại rằng có gì đó bị bỏ qua. Orchestrator trình bày 60% bao phủ như thể là 100%.

Cách khắc phục. Làm cho việc cắt cụt trở nên ồn ào. Nếu một tác tử giới hạn phạm vi bao phủ của mình — top-N, lấy mẫu, giới hạn thời gian — nó phải nói rõ điều đó trong báo cáo, một cách tường minh: “đã xem xét 18 trên 30 endpoint; 12 chưa kiểm tra.” Orchestrator nêu bật khoảng trống đó thay vì nuốt chửng nó. Kết quả từng phần được trình bày như thể đã hoàn chỉnh còn tệ hơn một lời thừa nhận trung thực “tôi chưa làm xong.”

Lỗi 5: Worktree mồ côi #

Triệu chứng. Các git worktree cũ chất đống. Tệ hơn: một tác tử sau đó đọc một worktree làm dở dang như thể đó là cây chính chuẩn, rồi xây tiếp trên một điều hư cấu.

Nguyên nhân gốc. Worktree được tạo để cô lập nhưng không bao giờ được đối xử như tài nguyên có phạm vi. Không dọn dẹp khi hoàn tất; không có quyền sở hữu rõ ràng về việc cây nào là chuẩn.

Cách khắc phục. Hãy coi mỗi worktree như một tài nguyên có vòng đời. Tự động dọn khi một tác tử không có thay đổi gì. Khi có thay đổi, hãy rà soát-và-merge hoặc loại bỏ một cách tường minh — đừng để nó lủng lẳng. Và đừng bao giờ để một tác tử ở hạ nguồn đọc worktree của tác tử khác như sự thật cơ sở; trạng thái chuẩn là cây chính, hết chuyện. (Chúng tôi đã đích thân dọn một worktree mồ côi giữa pipeline — đó là một lệnh git worktree remove mất năm giây mà tiết kiệm cả tiếng đồng hồ kiểu “tại sao file này lại sai.”)

Nguyên lý #

Mỗi lỗi trong số này đều chung một gốc rễ: coi lời tuyên bố của một tác tử như thể đó là hiện thực đã được kiểm chứng. Bản tóm tắt không được kiểm tra, phạm vi không được cô lập, vòng lặp không được giới hạn, việc cắt cụt không được ghi lại, worktree không có chủ. Điều phối đa tác tử không hỏng vì các tác tử ngu — nó hỏng vì orchestrator đã tin mà không kiểm chứng. Hãy cài kiểm chứng và các giới hạn tường minh vào mọi mối nối, và pipeline sẽ trở nên đáng tin cậy ngang với sức mạnh của nó.

Thiết lập Claude Code sẵn sàng cho production #

Pipeline đáng tin cậy cần hạ tầng không tự thêm lỗi của riêng nó:

1. Một máy chủ ổn định cho pipeline dài và cổng CI. Một phiên SSH bị rớt giữa lúc điều phối là một kiểu lỗi của riêng nó. HTStack — VPS Hồng Kông, truy cập Trung Quốc đại lục độ trễ thấp, BGP ổn định. Cùng IDC đang host dibi8.com, nơi chúng tôi chạy chính các pipeline này. 5-12 USD/tháng.

2. Dư địa đám mây cho fan-out song song. Khi bạn (có chủ đích, có ngân sách) fan-out các worker, CPU dư giúp chúng không tranh chấp. DigitalOcean — 200 USD tín dụng miễn phí trong 60 ngày, hơn 14 khu vực.

3. Một bộ skills. Tránh được năm lỗi này phần lớn là chuyện kỷ luật prompt — các bước kiểm chứng, điều kiện dừng, tài nguyên có phạm vi. Chúng tôi đã đóng gói năm skill đã qua thực chiến thành một bộ giá 19 USD trên Gumroad — xem CTA nổi ở góc màn hình — bao gồm cả các prompt orchestrator đã cài sẵn những mối nối kiểm chứng.

Đọc thêm #

• Mẫu hình Subagent — năm quy trình mà các lỗi này ẩn nấp bên trong.
• Hướng dẫn tự viết Agent tùy chỉnh — xây dựng các worker đáng tin cậy với hợp đồng đầu ra.
• Subagent vs MCP vs Skill — chọn đúng phần mở rộng để bạn không xây quá tay.
• Hóa đơn hàng tháng của AI Coding Agent — phép tính token đằng sau fan-out mất kiểm soát.

Phán quyết #

Điều phối đa tác tử đáng giá khi nhiệm vụ thực sự vượt quá một cửa sổ ngữ cảnh hoặc cần kiểm chứng độc lập — nhưng hãy với tới nó một cách có chủ đích, không theo phản xạ. Một tác tử đơn lẻ được prompt tốt luôn thắng một pipeline năm tác tử đầy lỗi. Khi bạn điều phối, sự khác biệt giữa sức mạnh và thảm họa nằm ở một thói quen: kiểm chứng mọi lời tuyên bố dựa trên sự thật cơ sở, và giới hạn mọi vòng lặp. Sự phức tạp bạn không kiểm chứng được còn tệ hơn sự đơn giản mà bạn kiểm chứng được.