Claude Code Agent Teams — Chay nhieu agent song song tren cung project

Khi project lớn dần, một agent duy nhất không thể xử lý mọi thứ trong thời gian hợp lý. Bạn cần frontend, backend và test chạy đồng thời. Claude Code Agent Teams cho phép bạn spawn nhiều sub-agent làm việc song song trên cùng codebase mà không xung đột.

Agent Teams là gì?

Agent Teams là khả năng của Claude Code cho phép một orchestrator agent phân chia công việc thành nhiều task độc lập, mỗi task được giao cho một sub-agent riêng biệt. Các sub-agent này làm việc đồng thời trên các git worktree riêng, tránh xung đột code và tăng tốc độ phát triển.

Thay vì một agent làm tuần tự: viết backend API, rồi frontend UI, rồi test — bạn có thể có ba agent làm ba việc này cùng lúc. Thời gian hoàn thành giảm từ tổng các task xuống chỉ còn bằng task dài nhất.

Các thành phần chính

• Orchestrator Agent: Agent chính phân tích yêu cầu, chia task và điều phối
• Sub-agents: Các agent con thực thi từng task cụ thể
• Git Worktrees: Mỗi sub-agent làm việc trên một worktree riêng, là bản sao của repo ở thư mục khác nhưng dùng chung git history
• Merge Strategy: Cách gộp kết quả từ các worktree về branch chính

Git Worktrees — Nền tảng của Agent Teams

Git worktree cho phép bạn có nhiều working directory từ cùng một repository. Mỗi worktree có thể ở một branch khác nhau, và thay đổi ở worktree này không ảnh hưởng worktree kia.

Tạo worktree thủ công

# Tao worktree moi tu branch hien tai
git worktree add ../my-project-feature-a -b feature-a

# Tao worktree tu mot branch cu the
git worktree add ../my-project-fix-api -b fix-api origin/main

# Liet ke cac worktree dang hoat dong
git worktree list

# Xoa worktree khi xong
git worktree remove ../my-project-feature-a

Mỗi worktree là một thư mục độc lập với đầy đủ source code. Bạn có thể chạy Claude Code trong mỗi thư mục đó mà không lo xung đột với các agent khác.

Tại sao worktree tốt hơn branch thông thường?

Với branch thông thường, bạn phải stash hoặc commit thay đổi trước khi switch. Với worktree, mỗi branch có thư mục riêng, cho phép nhiều agent làm việc đồng thời mà không cần đợi nhau. Đây là điều kiện tiên quyết để Agent Teams hoạt động hiệu quả.

Task Decomposition — Chia công việc đúng cách

Bước quan trọng nhất khi dùng Agent Teams là phân chia công việc. Một task tốt cho parallel execution cần thỏa mãn các điều kiện:

• Độc lập: Các task không sửa cùng một file hoặc chức năng
• Rõ ràng: Mỗi task có đầu vào và đầu ra xác định
• Có thể merge: Kết quả của các task có thể gộp lại mà không xung đột

Ví dụ phân chia task cho một feature CRUD

# Yeu cau: Xay dung chuc nang quan ly san pham

# Task 1 (Sub-agent A): Backend API
- Tao model Product voi Prisma
- Viet CRUD endpoints (GET, POST, PUT, DELETE)
- Viet validation logic
- File lien quan: src/models/, src/routes/products.ts, src/validators/

# Task 2 (Sub-agent B): Frontend UI
- Tao trang danh sach san pham
- Tao form them/sua san pham
- Tao component xoa voi confirmation dialog
- File lien quan: src/components/products/, src/pages/products/

# Task 3 (Sub-agent C): Tests
- Viet unit tests cho model va validation
- Viet integration tests cho API endpoints
- Viet E2E tests cho flow chinh
- File lien quan: tests/unit/products/, tests/integration/, tests/e2e/

Những trường hợp KHÔNG nên chia

Không phải lúc nào chia task cũng tốt. Tránh chia khi:

• Các task phụ thuộc lẫn nhau về logic (B cần kết quả của A)
• Nhiều task sửa cùng một file (sẽ gây merge conflict)
• Task quá nhỏ, overhead của việc tạo worktree lớn hơn thời gian tiết kiệm
• Task cần hiểu bối cảnh của toàn bộ codebase để quyết định

Orchestrator Pattern

Orchestrator là agent chính chịu trách nhiệm điều phối toàn bộ quy trình. Nó không trực tiếp viết code mà tập trung vào việc phân chia, giám sát và tổng hợp kết quả.

Quy trình của Orchestrator

1. Phân tích yêu cầu: Hiểu rõ feature cần xây dựng
2. Chia task: Xác định các task độc lập có thể chạy song song
3. Tạo worktrees: Mỗi task một worktree và branch riêng
4. Spawn sub-agents: Khởi chạy agent cho từng worktree với chỉ dẫn cụ thể
5. Giám sát: Theo dõi tiến độ của từng sub-agent
6. Merge: Gộp kết quả từ các branch về branch chính
7. Kiểm tra: Chạy test tổng hợp để đảm bảo mọi thứ hoạt động

Cấu hình orchestrator trong CLAUDE.md

# CLAUDE.md - Orchestrator Configuration

## Agent Teams Protocol

Khi nhan yeu cau phuc tap, hay:
1. Phan tich xem co the chia thanh cac task doc lap khong
2. Voi moi task, tao git worktree rieng
3. Spawn sub-agent cho moi worktree voi instructions cu the
4. Doi tat ca sub-agents hoan thanh
5. Merge cac branch va resolve conflicts
6. Chay full test suite

## Task Assignment Template
Moi sub-agent nhan:
- Mo ta cu the cong viec can lam
- Danh sach file duoc phep sua
- Conventions va patterns can tuan thu
- Tieu chi hoan thanh (definition of done)

Thực hành: Chạy Agent Teams cho full-stack feature

Hãy xem ví dụ cụ thể khi xây dựng chức năng "Dashboard Analytics" cho một ứng dụng SaaS.

Bước 1: Orchestrator phân tích và chia task

# Yeu cau: Xay dung Dashboard Analytics voi chart doanh thu,
# bieu do nguoi dung, va bang top san pham

# Orchestrator phan tich va quyet dinh chia 3 task:

# Task A - Backend (Sub-agent 1):
git worktree add ../project-dashboard-backend -b feat/dashboard-backend
# Instructions: Tao API endpoints:
# - GET /api/analytics/revenue?period=7d|30d|90d
# - GET /api/analytics/users?period=7d|30d|90d
# - GET /api/analytics/top-products?limit=10
# Dung aggregate queries, cache voi Redis 5 phut

# Task B - Frontend (Sub-agent 2):
git worktree add ../project-dashboard-frontend -b feat/dashboard-frontend
# Instructions: Tao Dashboard page voi:
# - Revenue chart (line chart, Recharts)
# - User growth chart (bar chart)
# - Top products table (sortable)
# Dung mock data truoc, se ket noi API sau khi merge

# Task C - Tests (Sub-agent 3):
git worktree add ../project-dashboard-tests -b feat/dashboard-tests
# Instructions: Viet test coverage:
# - Unit tests cho analytics service
# - API integration tests
# - Component tests cho charts

Bước 2: Sub-agents thực thi song song

Mỗi sub-agent làm việc độc lập trong worktree của mình. Orchestrator theo dõi trạng thái:

# Kiem tra trang thai cac worktree
git worktree list
# /home/user/project           abc1234 [main]
# /home/user/project-dashboard-backend   def5678 [feat/dashboard-backend]
# /home/user/project-dashboard-frontend  ghi9012 [feat/dashboard-frontend]
# /home/user/project-dashboard-tests     jkl3456 [feat/dashboard-tests]

# Kiem tra tien do tung branch
git log feat/dashboard-backend --oneline -5
git log feat/dashboard-frontend --oneline -5
git log feat/dashboard-tests --oneline -5

Bước 3: Merge và resolve conflicts

Khi tất cả sub-agents hoàn thành, orchestrator merge từng branch:

# Merge backend truoc (thuong it conflict nhat)
git checkout main
git merge feat/dashboard-backend --no-ff -m "feat: dashboard analytics API endpoints"

# Merge frontend (co the conflict o routing config)
git merge feat/dashboard-frontend --no-ff -m "feat: dashboard analytics UI"

# Neu co conflict:
# 1. Mo file conflict
# 2. Giu ca hai thay doi (backend route + frontend route)
# 3. git add . && git commit

# Merge tests cuoi cung
git merge feat/dashboard-tests --no-ff -m "test: dashboard analytics coverage"

# Don dep worktrees
git worktree remove ../project-dashboard-backend
git worktree remove ../project-dashboard-frontend
git worktree remove ../project-dashboard-tests

Xử lý Merge Conflicts

Merge conflict là thách thức lớn nhất khi dùng Agent Teams. Đây là các chiến lược giảm thiểu và xử lý conflict.

Phòng tránh conflict

• Phân chia file rõ ràng: Mỗi sub-agent chỉ sửa các file trong phạm vi của mình
• Shared files có quy ước: Nếu nhiều agent cần sửa cùng file (ví dụ router config), quy định mỗi agent thêm vào cuối file
• Interface contracts: Định nghĩa trước các interface/type chung trước khi chia task

Xử lý conflict khi xảy ra

# Khi merge gap conflict, Claude Code co the tu dong resolve:

# Truong hop 1: Ca hai them dong moi vao cung file
# -> Giu ca hai, sap xep lai cho hop ly

# Truong hop 2: Ca hai sua cung mot dong
# -> Can hieu context de chon dung, thuong uu tien
#    phien ban moi hon hoac hoi nguoi dung

# Truong hop 3: Structural conflict (rename/move file)
# -> Can resolve thu cong, kiem tra ca hai phia

# Lenh huu ich khi resolve conflicts:
git diff --name-only --diff-filter=U  # Liet ke file conflict
git checkout --theirs path/to/file    # Lay phien ban cua branch dang merge
git checkout --ours path/to/file      # Giu phien ban hien tai

Khi nào dùng Teams vs Single Agent?

Không phải lúc nào dùng nhiều agent cũng tốt hơn. Đây là bảng so sánh giúp bạn quyết định:

Nên dùng Agent Teams khi:

• Feature lớn có thể chia thành 3 phần trở lên độc lập
• Dự án có cấu trúc rõ ràng (backend/frontend/tests tách biệt)
• Deadline gấp, cần giảm thời gian tổng thể
• Các thành phần sử dụng công nghệ khác nhau (React + Python + DevOps)
• Việc song song hóa tiết kiệm ít nhất 40% thời gian so với làm tuần tự

Nên dùng Single Agent khi:

• Task nhỏ, hoàn thành trong 10-15 phút
• Các thay đổi liên kết chặt với nhau
• Cần hiểu bối cảnh toàn bộ để ra quyết định
• Chỉ sửa 1-2 file
• Bug fix đơn giản

Chi phí khi dùng Agent Teams

Mỗi sub-agent tiêu thụ token độc lập. Khi chạy 3 agent song song, chi phí API tăng tương ứng. Tuy nhiên, chi phí này thường xứng đáng vì:

• Thời gian developer: Giảm từ 3 giờ xuống 1 giờ cho developer
• Token cost: 3 agent x 50K tokens = 150K tokens, nhưng tiết kiệm 2 giờ làm việc
• Context window: Mỗi sub-agent chỉ cần context của phần mình, không cần load toàn bộ project

Tối ưu chi phí

# Strategies giam chi phi Agent Teams:

# 1. Chi dung worktree khi that su can
#    - Task duoi 10 phut: dung single agent
#    - Task 30+ phut co the chia: dung teams

# 2. Gioi han context cho moi sub-agent
#    - Chi cho sub-agent doc cac file lien quan
#    - Dung .claude/settings.json de gioi han scope

# 3. Dung model phu hop cho tung task
#    - Orchestrator: Opus (can suy nghi phuc tap)
#    - Code generation: Sonnet (can bang cost/quality)
#    - Simple tasks: Haiku (nhanh va re)

# 4. Cache ket qua trung gian
#    - Luu interface definitions de cac agent khong phai suy luan lai

Ví dụ thực tế: E-commerce Checkout Flow

Một ví dụ thực tế phức tạp hơn — xây dựng toàn bộ checkout flow cho e-commerce:

Orchestrator phân tích

# Feature: Checkout flow hoan chinh
# Thoi gian uoc tinh single agent: 4 gio
# Thoi gian uoc tinh voi teams: 1.5 gio

# === TASK A: Payment Backend (Sub-agent 1) ===
# Branch: feat/checkout-payment
# Scope:
# - Payment service integration (Stripe/VNPay)
# - Order creation API
# - Payment webhook handler
# - Transaction logging
# Files: src/services/payment/, src/routes/checkout.ts

# === TASK B: Checkout UI (Sub-agent 2) ===
# Branch: feat/checkout-ui
# Scope:
# - Multi-step checkout form (shipping -> payment -> confirm)
# - Address autocomplete component
# - Order summary sidebar
# - Responsive design
# Files: src/components/checkout/, src/pages/checkout/

# === TASK C: Cart & Inventory (Sub-agent 3) ===
# Branch: feat/checkout-cart
# Scope:
# - Cart state management (Zustand)
# - Inventory check before checkout
# - Stock reservation (15 phut hold)
# - Cart expiry handling
# Files: src/stores/cart.ts, src/services/inventory/

# === TASK D: Email & Notifications (Sub-agent 4) ===
# Branch: feat/checkout-notifications
# Scope:
# - Order confirmation email template
# - Payment receipt email
# - Shipping notification
# - Admin notification cho don hang moi
# Files: src/services/email/, src/templates/

Interface contracts định nghĩa trước

// types/checkout.ts — File nay duoc tao truoc khi spawn sub-agents
// Tat ca sub-agents deu doc file nay de dam bao tuong thich

interface CartItem {
  productId: string;
  variantId: string;
  quantity: number;
  price: number;
}

interface ShippingAddress {
  fullName: string;
  phone: string;
  address: string;
  ward: string;
  district: string;
  city: string;
}

interface Order {
  id: string;
  items: CartItem[];
  shipping: ShippingAddress;
  paymentMethod: 'stripe' | 'vnpay' | 'cod';
  subtotal: number;
  shippingFee: number;
  total: number;
  status: 'pending' | 'paid' | 'shipped' | 'delivered';
  createdAt: Date;
}

interface PaymentResult {
  success: boolean;
  transactionId: string;
  orderId: string;
  error?: string;
}

Việc định nghĩa interface contracts trước là bước cực kỳ quan trọng. Nó đảm bảo các sub-agent tạo ra code tương thích với nhau mà không cần giao tiếp trực tiếp.

Monitoring và Debugging Agent Teams

Khi nhiều agent chạy song song, việc theo dõi và debug trở nên phức tạp hơn. Đây là một số kỹ thuật hữu ích:

Log từng agent

# Moi sub-agent nen ghi log hoat dong:
# Worktree A: git log feat/checkout-payment --oneline
# abc1234 feat: add Stripe payment service
# def5678 feat: add payment webhook handler
# ghi9012 feat: add transaction logging

# Kiem tra tong quan nhanh:
for branch in feat/checkout-payment feat/checkout-ui feat/checkout-cart; do
  echo "=== $branch ==="
  git log $branch --oneline -3
  echo ""
done

Xử lý khi một sub-agent thất bại

Nếu một sub-agent gặp lỗi và không hoàn thành task:

• Các sub-agent khác vẫn tiếp tục làm việc bình thường
• Orchestrator có thể spawn agent mới cho worktree đó
• Hoặc chuyển task đó về single agent sau khi các task khác hoàn thành
• Git worktree vẫn giữ nguyên trạng thái, không mất code đã viết

Best Practices cho Agent Teams

1. Luôn định nghĩa interface trước

Trước khi spawn bất kỳ sub-agent nào, tạo các file type definitions, API contracts hoặc shared constants. Đây là "hợp đồng" giữa các agent.

2. Giới hạn phạm vi file

Mỗi sub-agent chỉ được phép sửa các file trong scope của mình. Viết rõ ràng trong instructions: "Chỉ sửa các file trong thư mục src/services/payment/. KHÔNG sửa bất kỳ file nào khác."

3. Merge theo thứ tự

Merge branch ít có khả năng conflict trước. Thường là: backend -> frontend -> tests. Nếu conflict xảy ra ở branch sau, bạn đã có base ổn định từ branch trước.

4. Chạy integration tests sau merge

Sau khi merge tất cả branch, luôn chạy full test suite. Code từng phần có thể đúng nhưng chưa chắc kết hợp lại sẽ hoạt động.

5. Dùng cho task đủ lớn

Overhead của việc tạo worktree, spawn agent và merge khoảng 5-10 phút. Chỉ dùng Agent Teams khi tổng thời gian tiết kiệm lớn hơn overhead này.

So sánh với các công cụ khác

Agent Teams khác với các phương pháp multi-agent khác:

• VS Code Multi-window: Mở nhiều cửa sổ VS Code với Claude Code — đơn giản nhưng không có orchestrator tự động
• CI/CD Parallel Jobs: Chạy test song song trong pipeline — chỉ cho test, không cho code generation
• Micro-services team: Mỗi người làm một service — Agent Teams giống cách này nhưng trên cùng codebase

Tóm tắt

Claude Code Agent Teams là công cụ mạnh mẽ khi bạn cần tăng tốc phát triển các feature phức tạp. Các điểm chính cần nhớ:

• Dùng git worktrees để tạo môi trường độc lập cho từng agent
• Chia task rõ ràng, đảm bảo tính độc lập giữa các task
• Định nghĩa interface contracts trước khi spawn sub-agents
• Merge theo thứ tự và luôn chạy integration tests sau đó
• Chỉ dùng khi task đủ lớn để bù đắp overhead

Tìm hiểu thêm về các kỹ thuật nâng cao của Claude Code tại Thư viện Nâng cao.