Làm chủ Agent Teams trong Claude Code

Xử lý một dự án lớn bằng một agent đơn lẻ thường vấp phải hai giới hạn: cửa sổ ngữ cảnh (context window) cạn dần và mọi việc phải chạy tuần tự. Khi số file tăng lên, agent bắt đầu "quên" logic cũ hoặc sa lầy vào việc đọc-ghi từng file một cách chậm chạp. Agent team ra đời để giải quyết bài toán đó.

Về cơ bản, agent team là một hệ thống đa tác nhân (multi-agent) bản địa trong Claude Code, vận hành theo mô hình "một lead, nhiều teammate". Lead đóng vai trò điều phối: chia nhỏ roadmap thành các task và kích hoạt các teammate làm việc song song trong những context window độc lập. Khác với script automation thông thường, các agent trong team có thể nhắn tin trực tiếp cho nhau và đồng bộ trạng thái qua một danh sách tác vụ chung.

Agent team là gì và khác subagent ở đâu?

Cấu trúc cốt lõi của một agent team là "một lead, nhiều teammate". Lead giữ vai trò kiến trúc sư: lập kế hoạch và quản lý vòng đời (lifecycle). Teammate là những instance Claude Code độc lập, mỗi cái lo một phần việc chuyên biệt.

Điểm khác biệt lớn nhất nằm ở khả năng cộng tác và chia sẻ thông tin:

Trong agent team, teammate không phải công cụ thực thi vô tri: chúng chia sẻ phát hiện, thách thức giả thuyết của nhau và tự điều phối qua Mailbox mà không cần bạn can thiệp từng bước.

Khi nào nên dùng agent team, khi nào không?

Agent team phát huy giá trị khi công việc tách được thành nhiều hướng khám phá song song.

Nên dùng khi:

• Khám phá song song: làm cùng lúc trên nhiều domain — frontend, backend, infrastructure.
• Review đa chiều: một agent soi bảo mật, một agent lo hiệu năng, một agent kiểm tra test coverage để tránh thiên kiến (bias).
• Điều tra lỗi (competing hypotheses): spawn nhiều agent, mỗi bên theo đuổi một giả thuyết gây lỗi khác nhau cùng lúc.

Không nên dùng khi:

• Sửa cùng một file: rất dễ xung đột (file conflict).
• Hệ thống monolith: trong codebase nguyên khối, nhiều agent cùng sửa logic dễ gây xung đột merge nghiêm trọng. Agent team hợp với kiến trúc microservices hoặc các module tách biệt hơn.
• Tác vụ tuần tự: nếu task B phụ thuộc hoàn toàn vào task A, dùng team chỉ tốn thêm token và chi phí điều phối.

Bật và khởi tạo agent team như thế nào?

Đây là tính năng thực nghiệm, nên bạn phải bật nó trong phần env của settings.json (thường ở ~/.claude/settings.json):

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Sau khi khởi động lại, ra lệnh bằng ngôn ngữ tự nhiên: "Tạo một agent team để refactor module auth và cập nhật test. Dùng Opus cho lead, Sonnet cho teammate."

Lưu ý quan trọng về model: teammate không mặc định kế thừa model của lead. Muốn cấu hình, dùng lệnh /config và chỉnh mục Default teammate model. Bạn có thể chọn "Default (leader's model)" để đồng bộ, hoặc gán model riêng (ví dụ Haiku cho task đơn giản) để tiết kiệm chi phí.

Team lead, teammate và shared task list phối hợp ra sao?

• Team lead: lập kế hoạch, chia task, phê duyệt plan của teammate và tổng hợp kết quả. Lead là thực thể duy nhất bạn nên dùng để dọn dẹp (cleanup) tài nguyên.
• Teammate: thực thi task độc lập. Xong việc, teammate tự nhận (self-claim) task tiếp theo từ danh sách chung. Cơ chế file locking đảm bảo không hai agent nào nhận trùng một task.
• Shared task list: xem bằng Ctrl+T, lưu trạng thái pending, in progress và completed của toàn dự án.

Các agent liên lạc qua hệ thống Mailbox. Khi cần thông tin, teammate gửi tin nhắn trực tiếp. Lead nhận thông báo khi một task hoàn thành hoặc khi teammate rơi vào trạng thái chờ (idle).

Quy trình thực tế: từ issue đến pull request

1. Nhận spec: đưa link GitHub Issue cho lead.
2. Plan mode: yêu cầu lead lập kế hoạch chi tiết. Bắt buộc phê duyệt kế hoạch trước khi spawn teammate, tránh để các agent đi sai hướng và đốt token vô ích.
3. Spawn & execute: lead tạo teammate và giao việc theo kế hoạch đã duyệt.
4. Giám sát: theo dõi các teammate chạy song song; khi cần thì nhảy vào từng pane để điều chỉnh.
5. Synthesis: lead thu thập kết quả, kiểm tra chất lượng theo tiêu chuẩn (quality bar) bạn đặt ra.
6. Pull request: lead chuẩn bị PR sau khi mọi task đã xong.

Những cạm bẫy thường gặp và cách tránh

• Thiếu ngữ cảnh (context drift): teammate không biết lịch sử chat của lead. Hãy yêu cầu lead chèn các code pointer (con trỏ mã nguồn) và thông tin quan trọng thẳng vào mô tả task khi giao việc.
• Xung đột file: luôn hướng dẫn lead chia domain rõ ràng — ví dụ agent A chỉ làm trong /src/services, agent B trong /src/controllers.
• Quản lý vòng đời: đừng tắt thủ công các instance teammate. Hãy bảo lead "clean up the team" để giải phóng tài nguyên, tránh rò rỉ bộ nhớ hay session tmux còn sót lại.
• Bảo mật: cẩn thận với flag --dangerously-skip-permissions. Trong môi trường team, các yêu cầu cấp quyền dồn hết về lead nên rất dễ gây ức chế — nhưng bỏ qua toàn bộ quyền là một rủi ro bảo mật lớn. Thay vào đó, hãy dùng allow list trong settings.

Mẹo để làm chủ agent team

• Điểm ngọt (sweet spot): 3–5 teammate là con số lý tưởng. Nhiều hơn chỉ làm tăng gánh nặng điều phối và làm chậm cả hệ thống.
• Định mức task: giao khoảng 5–6 task nhỏ cho mỗi teammate. Task quá lớn khiến teammate đi lạc; task quá nhỏ thì chi phí điều phối lấn át lợi ích.
• Chế độ hiển thị: trong settings.json, đặt "teammateMode": "tmux". Nếu dùng iTerm2, cài thêm it2 CLI để bật split panes. Lưu ý: split panes không chạy trên Windows Terminal hay terminal tích hợp của VS Code.
• Tái dùng subagent definition: bạn có thể dùng lại các định nghĩa subagent sẵn có (ví dụ một chuyên gia bảo mật) làm teammate, chỉ cần gọi tên định nghĩa đó khi yêu cầu spawn team.

Các câu hỏi thường gặp

Claude Code có tự động tạo team không? Có. Với nhiệm vụ đủ phức tạp, Claude sẽ đề xuất tạo team, nhưng không tự ý làm nếu bạn chưa đồng ý.

Tôi có thể chat trực tiếp với teammate không? Có. Ở chế độ in-process, dùng Shift+Down để chuyển qua lại giữa các agent. Trong tmux hoặc iTerm2, chỉ cần click vào pane của teammate đó.

Agent team có chạy trong terminal của VS Code không? Có, nhưng chỉ ở chế độ in-process (hiển thị lần lượt). Muốn giao diện split panes, bạn bắt buộc dùng tmux hoặc iTerm2.

Làm sao để agent không tự ý sửa code lung tung? Yêu cầu teammate chạy ở chế độ read-only plan mode. Chúng chỉ đề xuất giải pháp và đợi lead (hoặc bạn) phê duyệt mới bắt đầu ghi file.

Tài liệu tham khảo

• Collaborating with Agent Teams in Claude Code — Heeki Park
• What Is Claude Code Agent Teams? — MindStudio
• Orchestrate Teams of Claude Code Sessions — Claude Code Docs
• 30 Tips for Claude Code Agent Teams — Push to Prod
• Claude Code's Agent Teams Are Insane — YouTube
• Learn 90% of Claude Code Agent Teams in 22 Minutes — YouTube
• How to Build Claude Agent Teams Better Than 99% of People — YouTube