Hướng dẫn thiết lập Claude Code Agent Teams: Xây app với nhiều AI agent song song

Agent Teams là gì và tại sao đây là bước đột phá?

Ngày 5/2/2026, Anthropic ra mắt Claude Code Agent Teams — Research Preview cho phép nhiều AI agents làm việc đồng thời trên cùng một codebase. Thay vì một Claude xử lý từng việc tuần tự, giờ bạn có thể có team 4-5 agent chạy song song, mỗi agent sở hữu full 200K token context riêng và giao tiếp peer-to-peer với nhau.

Kết quả thực tế: developers báo cáo 2-3x speedup trên projects có từ 3+ independent modules. Một full-stack app với database layer, backend API, và frontend components — ba agent có thể build đồng thời thay vì tuần tự.

Agent Teams vs. Subagents: Khác nhau như thế nào?

Trước khi đi vào setup, hiểu rõ sự khác biệt để chọn đúng approach:

Rule of thumb: nếu bạn có 3+ phần độc lập cần làm song song → Agent Teams. Nếu chỉ cần delegate một task nhỏ → Subagents đơn giản hơn.

6 Core Tools của Agent Teams

Agent Teams vận hành qua 6 tools chuyên biệt:

• TeamCreate: Khởi tạo team, spawn teammates với roles cụ thể
• TaskCreate: Định nghĩa công việc kèm dependency specifications
• TaskUpdate: Claim task và update trạng thái (pending/in-progress/done)
• TaskList: Query tasks và current states — lead agent dùng để monitor
• SendMessage: Direct peer communication giữa agents
• TeamDelete: Cleanup resources khi done

Điều kiện tiên quyết

Trước khi bắt đầu, đảm bảo có:

• Claude Code CLI đã cài (claude command hoạt động)
• Claude subscription: Pro, Max, Teams, Enterprise, hoặc API
• macOS hoặc Linux với tmux hoặc iTerm2
• Git initialized trong project folder

Cài đặt từng bước

Bước 1: Cài tmux

tmux là terminal multiplexer — cho phép chạy nhiều terminal sessions đồng thời, là backbone của Agent Teams communication.

macOS:

brew install tmux
tmux -V  # Verify: tmux 3.x.x

Ubuntu/Debian:

sudo apt update && sudo apt install tmux

Fedora/RHEL:

sudo dnf install tmux

Bước 2: Cấu hình Claude Code

Tạo hoặc update file ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "preferences": {
    "teammateMode": "tmux"
  }
}

Lưu ý quan trọng: Có bug parsing settings.json trong Research Preview. Nếu split panes không xuất hiện, dùng CLI flag thay thế:

claude --teammate-mode tmux

Bước 3: Khởi động session

tmux new-session -s claude-work
cd your-project-folder
claude --teammate-mode tmux

Viết CLAUDE.md hiệu quả cho Agent Teams

Đây là bước quan trọng nhất mà nhiều người bỏ qua. CLAUDE.md là "Agent Operating Manual" — agents đọc file này để hiểu project. Thiếu CLAUDE.md tốt = agents làm sai ngay từ đầu.

CLAUDE.md cho Agent Teams cần có:

• Project description và objectives
• Technology stack với versions cụ thể
• Folder structure conventions (ví dụ: src/api/ cho backend routes)
• Coding standards và naming conventions
• File ownership map: agent nào sở hữu directory nào — cực kỳ quan trọng

"Two teammates editing the same file leads to overwrites. Break the work so each teammate owns a different set of files." — Muhammad Rashid Daha

Tạo Team: Ví dụ thực tế

Khi đã vào Claude, tạo team với role definitions rõ ràng:

Create a team with:
- db-engineer: Database schema, migrations, seed data (owns: src/db/)
- backend-dev: API routes, middleware, authentication (owns: src/api/)
- frontend-dev: React components, pages, routing, styling (owns: src/components/, src/pages/)
- integrator: Frontend-backend connection, CORS, environment setup (owns: src/config/)

Key: chỉ định file ownership ngay từ đầu. Hai agent cùng edit một file = conflict và overwrite.

Monitor tiến độ

Hỏi lead agent status update bất cứ lúc nào:

"Show me the current task list and status of all agents."

Navigate giữa các tmux panes:

• Switch panes: Ctrl+B rồi arrow key
• Zoom pane: Ctrl+B rồi z
• Xem pane numbers: Ctrl+B rồi q
• Scroll mode: Ctrl+B rồi [

Team size guidelines: 4-5 là practical maximum

Đây là insight quan trọng nhất từ community testing:

• Small project (1-2 modules): Single Claude Code session — đừng over-engineer
• Medium project (3-4 modules): 3-4 teammates + 1 lead
• Large project (5+ modules): 4-5 teammates maximum

Tại sao 4-5 là maximum? Quá 5 agents, coordination overhead (messaging, task sync, dependency tracking) ăn mất speed gains. Law of diminishing returns bắt đầu từ agent thứ 6.

Khi nào KHÔNG dùng Agent Teams?

Agent Teams không phải silver bullet. Tránh dùng khi:

• Tasks inherently sequential (mỗi bước phụ thuộc output bước trước)
• Code tightly coupled — không thể tách file ownership rõ ràng
• Small fixes hoặc single-file edits
• Token budget hạn chế: Teams tốn 3-4x tokens so với single session

Troubleshooting phổ biến

Tổng kết

Claude Code Agent Teams thay đổi cách tiếp cận development từ sequential → parallel. Với 2-3x speedup trên projects phù hợp, đây là tính năng đáng đầu tư thời gian học. Key success factors: CLAUDE.md rõ ràng, file ownership không overlap, team size ≤ 5.

Đọc thêm về MCP Servers để tăng sức mạnh cho Agent Teams, và cách orchestrate multi-agent với tmux nâng cao.

Nguồn tham khảo

• How to Set Up Claude Code Agent Teams — codewithmuh (tháng 2/2026)
• Claude Code Agent Teams — Anthropic Official Blog