Agent Teams là tính năng experimental của Claude Code là gì, cho phép nhiều instance cộng tác trực tiếp với nhau qua shared task list và mailbox. Khác với sub-agents (báo cáo lên parent), teammates giao tiếp ngang hàng. Chi phí token tăng khoảng 7 lần so với session thông thường. Bài này hướng dẫn bật tính năng, tạo team đầu tiên, và 4 use case thực tế bạn có thể dùng ngay.
so với 1 session
cho phần lớn dự án
từ tài liệu chính thức
để tối ưu hiệu suất
Bạn đã quen với sub-agents: một agent cha giao việc, agent con làm rồi báo cáo kết quả. Mô hình đó hoạt động tốt cho task tập trung. Nhưng khi dự án cần nhiều người cùng thảo luận, phối hợp thực sự, không chỉ chia việc… thì Agent Teams sinh ra để giải quyết điều đó.
Agent Teams là tính năng experimental của Claude Code, cho phép nhiều instance hoạt động song song và giao tiếp trực tiếp với nhau, không cần qua một “trung tâm điều phối” duy nhất. Nếu bạn chưa đọc bài nền về sub-agents, mình khuyến khích đọc bài sub-agents trước để có bối cảnh đầy đủ.
Agent Teams Là Gì Và Khác Sub-Agents Thế Nào?
Agent Teams là tính năng experimental của Claude Code, cho phép một team lead khởi tạo nhiều instance (teammates), mỗi instance có context window riêng và giao tiếp trực tiếp với nhau qua shared task list và mailbox (Claude Code Docs, 2026). Tính năng này bị tắt theo mặc định và cần bật thủ công.
Điểm khác biệt cốt lõi so với sub-agents nằm ở cách giao tiếp. Sub-agents chỉ báo cáo kết quả lên parent. Teammates trong Agent Teams nhắn tin trực tiếp với nhau. Teammate A đang xử lý backend phát hiện vấn đề liên quan đến frontend? Nó gửi message thẳng cho teammate B, không cần qua team lead.
Khi nào chọn cái nào? Nếu task là “viết unit test cho module X” thì sub-agents đủ dùng. Nhưng nếu bạn cần “refactor backend, viết migration script, cập nhật API docs, và chạy integration test” cùng lúc với các phần phụ thuộc nhau, Agent Teams phù hợp hơn nhiều. Với chi phí token tăng khoảng 7x, hãy chắc chắn task đủ phức tạp để xứng đáng.
Cách Bật Và Tạo Team Đầu Tiên?
Để bật Agent Teams, bạn thêm một biến môi trường vào file cấu hình Claude Code hoặc shell profile. Theo tài liệu chính thức, toàn bộ quá trình từ bật flag đến spawn team đầu tiên mất khoảng 5 phút (Claude Code Docs, 2026).
Bước 1: Bật flag experimental
Cách đơn giản nhất là thêm vào file settings.json của Claude Code trong thư mục dự án:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}Bạn cũng có thể set trực tiếp trong shell profile để bật toàn cục:
# Thêm vào ~/.bashrc hoặc ~/.zshrc
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
# Reload
source ~/.bashrcTrên Windows, bạn set biến này trong System Environment Variables hoặc PowerShell profile. Sau khi khởi động lại Claude Code, menu “Teams” sẽ xuất hiện trong giao diện.
Bước 2: Spawn teammates bằng ngôn ngữ tự nhiên
Sau khi bật flag, bạn tạo team ngay trong session Claude Code bằng lời nói thường. Không cần viết config phức tạp:
# Ví dụ prompt để spawn team
"Tạo một team gồm 3 teammates để review PR này:
- Teammate 1: review security vulnerabilities
- Teammate 2: review performance bottlenecks
- Teammate 3: kiểm tra test coverage
Mỗi teammate đọc file src/auth.ts và src/api/routes.ts"Team lead sẽ tự phân tích yêu cầu, khởi tạo 3 teammate, giao task cho từng người. Bạn không cần can thiệp thủ công. Mỗi teammate nhận đủ context qua spawn prompt vì chúng không kế thừa lịch sử hội thoại của team lead.
Một điểm cần nhớ: cho đủ context ngay trong spawn prompt. Teammates bắt đầu với context window trống, không thấy những gì bạn đã trao đổi với team lead trước đó. Cách viết CLAUDE.md tốt sẽ giúp ích nhiều ở đây vì teammates đọc file này tự động.
Checkpoint: Sau bước này, bạn sẽ thấy giao diện hiển thị danh sách teammates và trạng thái task của từng người.
Quản Lý Team: Task List, Messaging, Và Display Thế Nào?
Agent Teams cung cấp ba cơ chế chính để vận hành: shared task list với trạng thái rõ ràng, mailbox để giao tiếp giữa các agents, và hai chế độ hiển thị tùy theo thiết lập terminal (Claude Code Docs, 2026). Hiểu ba cơ chế này giúp bạn theo dõi tiến độ team hiệu quả.
Shared Task List và các trạng thái
Task list là trung tâm điều phối của cả team. Mỗi task có một trong ba trạng thái: pending (chờ), in-progress (đang làm), completed (xong). Bạn có thể giao task cho teammate cụ thể hoặc để họ tự nhận từ pool chung.
Tasks cũng hỗ trợ dependencies. Bạn có thể chỉ định “task B chỉ bắt đầu khi task A hoàn thành.” Cơ chế này quan trọng khi các phần công việc phụ thuộc nhau, ví dụ như database migration phải xong trước khi viết API endpoints mới.
# Cấu trúc lưu trữ task list
~/.claude/tasks/{team-name}/
tasks.json # danh sách task và trạng thái
messages/ # mailbox giữa teammates
# Cấu trúc team config
~/.claude/teams/{team-name}/
config.json # cấu hình teamMailbox: Giao tiếp trực tiếp giữa teammates
Mailbox cho phép giao tiếp one-to-one hoặc broadcast đến toàn team. Teammate A cần thông báo cho B về một thay đổi API? Gửi message trực tiếp. Team lead cần update cho tất cả? Broadcast một tin.
Đây là điểm tạo ra sự khác biệt thực sự so với sub-agents. Thay vì mọi thứ đi qua một nút cổ chai duy nhất (main agent), thông tin chạy theo đường ngắn nhất. Nhưng cũng vì vậy, token cost tăng cao hơn vì mỗi message đều tiêu tốn context.
Hai chế độ hiển thị
Agent Teams hỗ trợ hai cách xem tiến độ:
In-process là lựa chọn an toàn cho hầu hết mọi người. Split panes tiện lợi hơn khi bạn cần quan sát nhiều teammates cùng lúc, nhưng cần tmux hoặc iTerm2. Lưu ý: VS Code terminal và Windows Terminal không hỗ trợ split panes của Agent Teams.
TeammateIdle (khi teammate rảnh) và TaskCompleted (khi task xong) để tự động hóa thêm. Xem hướng dẫn chi tiết tại bài Claude Code Hooks.
4 Use Cases Thực Tế Với Agent Teams
Tài liệu chính thức của Claude Code nêu 4 use case cụ thể cho Agent Teams, mỗi use case tận dụng khả năng cộng tác ngang hàng theo cách khác nhau (Claude Code Docs, 2026). Dưới đây mình phân tích từng cái với ví dụ cụ thể.
Use case 1: Parallel Code Review
Thay vì một người (hoặc một agent) review toàn bộ PR, bạn tạo 3 teammates song song. Teammate 1 tập trung security vulnerabilities. Teammate 2 kiểm tra performance bottlenecks. Teammate 3 đánh giá test coverage. Ba góc nhìn cùng lúc, thời gian ngắn hơn nhiều so với sequential review.
Mình đã thử với một PR khoảng 500 dòng code. Sequential review mất khoảng 15 phút. Với 3 teammates song song, kết quả có trong 6-7 phút và phát hiện được 2 vấn đề security mà mình thường bỏ qua khi review nhanh.
Use case 2: Competing Hypotheses Debugging
Đây là use case thú vị nhất theo mình. Khi bạn có một bug khó, thay vì debug tuần tự, tạo 2-3 teammates với giả thuyết khác nhau. Teammate A điều tra “bug do race condition.” Teammate B điều tra “bug do memory leak.” Cả hai chạy song song, so sánh kết quả.
Cách tiếp cận adversarial này cực kỳ hiệu quả cho bug phức tạp. Hai teammates với góc nhìn khác nhau thường tìm ra root cause nhanh hơn một agent cố đi theo một hướng duy nhất.
Use case 3: Cross-layer Coordination
Dự án full-stack cần thay đổi đồng bộ trên nhiều layer? Agent Teams phù hợp. Teammate 1 phụ trách frontend (React components). Teammate 2 xử lý backend (API endpoints). Teammate 3 viết tests. Ba người làm song song, giao tiếp qua mailbox khi cần đồng bộ interface.
Điểm quan trọng: mỗi teammate phải sở hữu file khác nhau. Tránh để hai teammates cùng chỉnh một file vì không có cơ chế lock. Kết hợp với git worktrees là lựa chọn tốt nếu bạn cần thật sự cách ly môi trường làm việc.
Use case 4: New Modules / Features
Phát triển tính năng mới có nhiều module độc lập? Mỗi teammate nhận một module, phát triển song song. Teammate 1 viết payment module. Teammate 2 viết notification system. Teammate 3 viết user profile. Cuối cùng team lead tích hợp.
Use case này phát huy tốt nhất khi các module ít phụ thuộc nhau ban đầu. Nếu module A cần interface từ module B để bắt đầu, hãy thiết lập dependency trong task list để B chạy trước.
Best Practices: Tối Ưu Team Thế Nào?
Sau khi thử nghiệm Agent Teams, Anthropic đúc kết một số nguyên tắc cụ thể giúp team hoạt động hiệu quả và tránh lãng phí token (Claude Code Docs, 2026). Dưới đây là những gì thực sự tạo ra sự khác biệt.
Quy mô team: 3-5 teammates là điểm ngọt
Đừng tạo team quá lớn chỉ vì có thể. 3-5 teammates là quy mô tối ưu cho phần lớn dự án. Dưới 3 thì lợi ích cộng tác không rõ ràng. Trên 5 thì overhead phối hợp và chi phí token tăng nhanh hơn năng suất. Mỗi teammate nên có khoảng 5-6 tasks để đủ việc làm mà không bị overwhelm.
Tránh xung đột file: mỗi teammate sở hữu vùng riêng
Agent Teams không có cơ chế file locking. Nếu hai teammates cùng chỉnh một file, bạn sẽ gặp conflict. Quy tắc đơn giản: khi spawn teammates, hãy phân chia rõ ràng ai làm file nào. Teammate 1 chỉ đụng vào src/auth/, Teammate 2 chỉ đụng src/api/.
Nếu dự án thực sự cần cách ly hoàn toàn, git worktrees cho mỗi teammate là giải pháp sạch nhất. Mỗi worktree là một working directory riêng biệt trên cùng một repo.
Spawn prompt: cho đủ context ngay từ đầu
Teammates không thấy lịch sử hội thoại của team lead. Họ bắt đầu với context window trống, chỉ nhận những gì có trong spawn prompt. Vì vậy, spawn prompt phải đầy đủ: mô tả dự án, nhiệm vụ cụ thể, file cần đọc, output mong đợi, constraint cần tuân thủ.
# Spawn prompt TỐT
"Bạn là security reviewer cho dự án e-commerce (Node.js + Express).
Nhiệm vụ: tìm SQL injection và XSS vulnerabilities trong src/api/routes.ts.
Đọc docs/security-checklist.md để biết tiêu chuẩn.
Output: danh sách vulnerabilities với severity level và line number."
# Spawn prompt KHÔNG TỐT
"Review security cho project này."Chờ teammates hoàn thành trước khi team lead tiếp tục
Team lead không nên tiến hành bước tiếp theo trong khi teammates vẫn đang làm. Kết quả chưa đầy đủ sẽ khiến team lead đưa ra quyết định thiếu thông tin. Cơ chế plan approval cũng hữu ích: yêu cầu teammate trình bày plan trước khi implement, giảm rủi ro đi sai hướng.
.claude/agents/, teammates tự động kế thừa được tool definitions và model configurations đó. Không cần cấu hình lại từ đầu.
Giới Hạn Và Chi Phí Cần Biết Trước Khi Dùng
Agent Teams đang ở giai đoạn experimental với một số giới hạn quan trọng, và chi phí token tăng tuyến tính theo số lượng teammate, khoảng 7x so với session thông thường (Claude Code Docs, 2026). Biết trước những điều này giúp bạn ra quyết định sáng suốt.
Chi phí token: tuyến tính theo team size
Mỗi teammate duy trì context window riêng. Với 4 teammates, bạn đang chạy 5 context windows song song (4 teammates + 1 team lead). Token cost tăng gần tuyến tính. Nếu một session bình thường tiêu 100K tokens, team 4 người có thể tiêu 400-600K tokens cho cùng khối lượng công việc.
Muốn tính toán cụ thể trước khi dùng? Bài tiết kiệm token Claude Code có breakdown chi tiết theo plan và hướng dẫn kiểm soát chi phí. Với gói Max ($100/tháng), team 3 người chạy khoảng 2-3 giờ là hết quota một ngày.
Giới hạn kỹ thuật hiện tại
Giới hạn đáng chú ý nhất là không có session resumption. Nếu session bị interrupt giữa chừng, bạn phải bắt đầu lại từ đầu với in-process mode. Đây là lý do mình khuyên dùng split panes với tmux trên macOS/Linux nếu chạy task dài.
Khi nào Agent Teams thực sự xứng đáng?
Với chi phí cao và các giới hạn experimental, Agent Teams xứng đáng khi công việc có thể chia song song rõ ràng, mỗi phần đủ lớn và độc lập, và thời gian quan trọng hơn chi phí. Nếu task có thể hoàn thành tốt bằng single agent trong 30 phút, đừng dùng team chỉ vì có thể.
Tính năng này nằm trong lộ trình phát triển L6 của Claude Code. Bạn có thể xem bức tranh tổng thể tại bài lộ trình Claude Code.
Spawn Prompt Examples: 4 Use Cases
Use Case 1: Parallel Code Review
Review authentication module trong /src/auth/.
Focus: SQL injection, XSS, CSRF vulnerabilities.
Report findings dạng numbered list với severity HIGH/MEDIUM/LOW.
KHÔNG sửa code. Chỉ report.Use Case 2: Competing Hypotheses
Debug timeout error trong /src/api/orders.ts.
Hypothesis: database connection pool exhausted.
Investigate và prove/disprove hypothesis này.
Nếu disprove, đề xuất hypothesis thay thế.Use Case 3: Cross-layer Development
# Teammate A (Frontend):
Implement login UI matching Figma design trong /src/components/auth/.
Dùng React + TailwindCSS. KHÔNG đụng /src/api/.
# Teammate B (Backend):
Implement /auth/login endpoint với JWT trong /src/api/auth/.
Return { token, refreshToken, user }. KHÔNG đụng /src/components/.Use Case 4: Modular Features
Build payment processing module.
Own: /src/payments/ (toàn quyền đọc/ghi).
Read-only: /src/types/ và /src/utils/.
KHÔNG đụng: /src/auth/, /src/users/, /src/orders/.Failure Handling: Khi Agent Gặp Lỗi
Lưu ý: Agent Teams experimental, đôi khi agents gửi message cho nhau vòng vòng (loop). Nếu thấy token tăng nhanh bất thường: (1) kill team, (2) giảm số teammates xuống 2-3, (3) thêm constraint rõ hơn trong spawn prompt: “Maximum 3 messages to other teammates. Focus on your own task.”
Team Protocols: Agents Giao Tiếp Thế Nào?
Agent Teams dùng 2 kênh giao tiếp chính:
Shared Task List: Tất cả teammates nhìn thấy cùng task board. Task có 3 states: pending, in-progress, completed. Một agent claim task bằng cách chuyển từ pending → in-progress. Agents khác thấy và không claim lại.
JSONL Mailbox: Mỗi agent có file inbox riêng (append-only JSONL). Muốn gửi message cho teammate, append vào inbox của họ. Trước mỗi LLM call, agent drain inbox của mình, messages trở thành phần context cho quyết định tiếp theo.
Coordination rules quan trọng:
- File ownership: mỗi agent chỉ sửa files trong scope của mình. Không có file locking.
- Message limit: nên restrict “Maximum 3 messages to other teammates” trong spawn prompt để tránh message loop.
- Không broadcast: gửi message trực tiếp cho teammate cần, không gửi cho tất cả.
Câu Hỏi Thường Gặp
Agent Teams có cần plan riêng hay dùng chung plan với Claude Code?
Không cần plan riêng. Agent Teams là tính năng của Claude Code, nên bạn trả token theo usage thông thường qua plan hiện tại (Pro, Max, Team). Chi phí tăng do số lượng context windows song song, không phải do phí tính năng riêng. Theo ước tính, team 4 người tiêu token gấp khoảng 4-7x so với single agent cho cùng nhiệm vụ.
Teammates có thể dùng MCP tools không?
Có. Nếu bạn đã cấu hình MCP servers trong .claude/settings.json hoặc thư mục project, teammates sẽ có quyền truy cập những tools đó theo permission mode đã thiết lập. Tuy nhiên, hãy cẩn thận với các tool có side effects vì nhiều teammates cùng gọi có thể gây xung đột.
Có thể dùng Agent Teams trên Windows không?
Có, nhưng với giới hạn. Bạn bật flag qua System Environment Variables hoặc PowerShell profile. In-process mode hoạt động bình thường. Split panes không hỗ trợ trên Windows Terminal, chỉ chạy được với tmux (qua WSL) hoặc iTerm2 (macOS). Nếu dùng Windows thuần túy, in-process mode với Shift+Down là lựa chọn duy nhất.
Agent Teams và Sub-agents có thể dùng cùng lúc không?
Có. Teammates trong Agent Teams hoàn toàn có thể spawn sub-agents của riêng mình để xử lý task con. Ví dụ, teammate phụ trách security review có thể spawn một sub-agent chuyên phân tích dependencies. Tuy nhiên, mỗi lớp thêm vào đều tăng chi phí token, nên chỉ dùng khi thực sự cần.
Khi nào nên chọn Agent Teams thay vì chạy Claude Code nhiều lần thủ công?
Chọn Agent Teams khi các phần công việc cần giao tiếp và phối hợp với nhau, không chỉ chạy độc lập. Nếu các task hoàn toàn tách biệt và không cần trao đổi, bạn có thể dùng git worktrees với nhiều terminal thủ công để tiết kiệm token hơn. Agent Teams tỏa sáng khi teammates thực sự cần nhắn tin và điều chỉnh lẫn nhau.
Task status bị lag thì xử lý thế nào?
Đây là known issue ở giai đoạn experimental. Nếu thấy task status không cập nhật đúng, bạn có thể hỏi team lead “update task status” hoặc kiểm tra trực tiếp file ~/.claude/tasks/{team-name}/tasks.json. Trong trường hợp lag nghiêm trọng, restart session và kiểm tra output của từng teammate thủ công là cách đáng tin cậy nhất.
Kết Luận
Agent Teams đưa Claude Code lên một mức cộng tác thực sự. Thay vì một agent tuần tự, bạn có một nhóm peer-to-peer, giao tiếp trực tiếp, tự phối hợp qua shared task list. Bốn use case chính (parallel review, competing hypotheses, cross-layer, new modules) đều giải quyết những bài toán cụ thể mà single agent xử lý kém hiệu quả hơn.
Nhưng đây vẫn là tính năng experimental. Token cost tăng gấp ~7x, không có session resumption, task status đôi khi lag. Trước khi dùng production, hãy thử nghiệm với project nhỏ, đo chi phí thực tế, và xác nhận lợi ích thực sự vượt qua chi phí.
Lộ trình học phù hợp: nắm vững sub-agents trước, hiểu hooks cho automation, trang bị skills cho từng agent, rồi thử Agent Teams cho project phức tạp tiếp theo của bạn. Kết hợp cả ba là bộ công cụ khá mạnh cho bất kỳ dự án đòi hỏi nhiều tay nghề nào.
