Điều phối agent team

Chú ý

Agent team là tính năng experimental, mặc định tắt. Bật bằng cách đặt CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 trong settings.json hoặc biến môi trường. Không có biến này, không team nào được thiết lập, Claude không tự spawn hay đề xuất teammate. Agent team có một số giới hạn đã biết quanh việc resume session, điều phối task, và tắt phiên - xem Giới hạn.

Agent team cho phép bạn phối hợp nhiều phiên Claude Code cùng làm việc. Một phiên đóng vai lead, điều phối công việc, giao task, tổng hợp kết quả. Các teammate (thành viên) làm việc độc lập, mỗi cái có context window riêng, và giao tiếp trực tiếp với nhau.

Khác với subagent - chạy trong một phiên và chỉ báo cáo về main agent - bạn có thể tương tác trực tiếp với từng teammate mà không cần qua lead.

Khi nào nên dùng agent team

Agent team hiệu quả nhất khi việc khám phá song song thực sự có giá trị:

• Nghiên cứu và review: nhiều teammate điều tra các khía cạnh khác nhau của một vấn đề đồng thời, rồi chia sẻ và thách thức phát hiện của nhau
• Module/tính năng mới: mỗi teammate sở hữu một phần riêng, không giẫm chân nhau
• Debug với nhiều giả thuyết cạnh tranh: các teammate kiểm chứng các giả thuyết khác nhau song song, hội tụ về đáp án nhanh hơn
• Phối hợp đa tầng: thay đổi trải dài frontend, backend, test - mỗi phần một teammate sở hữu

Agent team tốn nhiều token hơn đáng kể so với một phiên đơn. Chúng hoạt động tốt nhất khi teammate có thể làm việc độc lập. Với việc tuần tự, sửa cùng file, hoặc nhiều phụ thuộc chằng chịt, một phiên đơn hoặc subagent hiệu quả hơn.

So với subagent

	Subagent	Agent team
Context	Context window riêng; kết quả trả về caller	Context window riêng; hoàn toàn độc lập
Giao tiếp	Chỉ báo cáo về main agent	Teammate nhắn tin trực tiếp cho nhau
Điều phối	Main agent quản lý toàn bộ	Task list dùng chung, tự điều phối
Phù hợp cho	Việc tập trung, chỉ quan tâm kết quả	Việc phức tạp cần thảo luận, hợp tác
Chi phí token	Thấp hơn: kết quả tóm tắt về main context	Cao hơn: mỗi teammate là một phiên Claude riêng

Bật agent team

settings.json

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

Team đầu tiên của bạn

Sau khi bật, mô tả việc cần làm và các teammate bạn muốn bằng ngôn ngữ tự nhiên:

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.

Claude sẽ điền vào task list dùng chung, spawn teammate cho mỗi góc nhìn, cho họ khám phá vấn đề, rồi tổng hợp phát hiện khi xong.

Ghi chú

Claude đôi khi dùng subagent thay vì tạo team thật. Subagent xuất hiện trong cùng panel với teammate, nên chỉ nhìn panel không xác nhận được team đã hình thành. Nếu Claude spawn subagent thay vì team, hỏi lại và yêu cầu rõ ràng “agent team”.

Terminal của lead liệt kê teammate trong panel agent bên dưới ô prompt: mũi tên lên/xuống để chọn, Enter để mở transcript và nhắn trực tiếp, Escape để ngắt lượt hiện tại.

Điều khiển agent team

Chọn chế độ hiển thị

• In-process (mặc định): mọi teammate chạy trong terminal chính. Dùng mũi tên để chọn, Enter để xem và gõ để nhắn trực tiếp. Hoạt động trên mọi terminal, không cần thiết lập gì thêm.
• Split panes: mỗi teammate có pane riêng, thấy output mọi người cùng lúc. Yêu cầu tmux hoặc iTerm2.

Đổi mặc định bằng setting teammateMode trong ~/.claude/settings.json, hoặc cho một phiên bằng flag --teammate-mode.

Chỉ định teammate và model

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

Teammate không kế thừa /model của lead theo mặc định - đặt Default teammate model trong /config để đổi. Teammate kế thừa effort level của lead.

Yêu cầu duyệt kế hoạch trước khi làm

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

Teammate làm việc ở chế độ plan mode (chỉ đọc) cho đến khi lead duyệt kế hoạch. Nếu bị từ chối kèm phản hồi, teammate ở lại plan mode, chỉnh sửa dựa trên phản hồi, rồi nộp lại.

Nói chuyện trực tiếp với teammate

Mỗi teammate là một phiên Claude Code đầy đủ, độc lập - bạn có thể nhắn trực tiếp để hướng dẫn thêm, hỏi tiếp, hoặc điều chỉnh hướng đi. Model và fast mode của teammate cố định khi spawn; /model, /fast chỉ đổi setting của lead, còn /effort vẫn áp dụng cho các lượt sau của teammate đang xem.

Giao và nhận task

Task list dùng chung điều phối công việc: lead tạo task, teammate làm dần. Task có ba trạng thái: pending, in progress, completed, và có thể phụ thuộc lẫn nhau - task pending có phụ thuộc chưa xong thì chưa claim được. Lead có thể giao trực tiếp, hoặc teammate tự claim task tiếp theo sau khi xong việc.

Tắt teammate

Ask the researcher teammate to shut down

Lead gửi yêu cầu shutdown, teammate có thể chấp nhận (thoát êm) hoặc từ chối kèm giải thích. Thư mục dùng chung của team được dọn tự động khi phiên kết thúc.

Dùng hook để đảm bảo chất lượng

• TeammateIdle: chạy khi teammate sắp idle. Exit code 2 để gửi phản hồi, giữ teammate tiếp tục làm.
• TaskCreated: chạy khi task đang được tạo. Exit code 2 để ngăn tạo và gửi phản hồi.
• TaskCompleted: chạy khi task đang được đánh dấu hoàn thành. Exit code 2 để ngăn hoàn thành.

Cách hoạt động

Agent team hình thành khi teammate đầu tiên được spawn, phiên chính đóng vai lead. Có hai cách teammate được spawn: bạn yêu cầu trực tiếp, hoặc Claude tự đề xuất khi thấy việc phù hợp cho song song hoá (bạn luôn phải xác nhận).

Kiến trúc

Thành phần	Vai trò
Team lead	Phiên Claude Code chính, spawn teammate và điều phối
Teammate	Các phiên Claude Code riêng, mỗi cái làm task được giao
Task list	Danh sách việc dùng chung mà teammate claim và hoàn thành
Mailbox	Hệ thống nhắn tin giữa các agent

Team và task được lưu local dưới tên bắt nguồn từ session ID (session- + 8 ký tự đầu). Team config chứa state runtime (session ID, tmux pane ID…) - đừng chỉnh tay, nó bị ghi đè ở lần update tiếp theo. Muốn định nghĩa vai trò teammate tái sử dụng, dùng subagent thay vì chỉnh team config.

Permission

Teammate khởi động với permission setting của lead - nếu lead chạy --dangerously-skip-permissions, mọi teammate cũng vậy. Sau khi spawn bạn có thể đổi mode từng teammate riêng, nhưng không đặt được mode riêng ngay lúc spawn. Permission prompt của teammate xuất hiện ở phiên lead, nên bạn duyệt ở đó.

Chi phí token

Agent team tốn token nhiều hơn đáng kể so với một phiên đơn - mỗi teammate là một context window riêng, chi phí tăng theo số teammate đang hoạt động. Với việc nghiên cứu, review, tính năng mới, token phụ trội thường đáng giá. Với việc thường ngày, một phiên đơn tiết kiệm hơn.

Ví dụ tình huống dùng

Review code song song

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

Điều tra với các giả thuyết cạnh tranh

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

Cấu trúc “tranh luận” chống lại thiên kiến anchoring: nếu điều tra tuần tự, một giả thuyết được khám phá trước sẽ lệch hướng những điều tra sau. Với nhiều điều tra viên độc lập chủ động bác bỏ lẫn nhau, giả thuyết “sống sót” nhiều khả năng là nguyên nhân thật.

Best practices

• Cho teammate đủ ngữ cảnh: teammate tự load CLAUDE.md, MCP server, skill - nhưng không kế thừa lịch sử hội thoại của lead. Nêu chi tiết cụ thể trong prompt spawn.
• Chọn quy mô team hợp lý: bắt đầu với 3–5 teammate cho hầu hết workflow. Khoảng 5–6 task mỗi teammate giữ mọi người bận rộn hiệu quả.
• Chia task vừa phải: quá nhỏ thì chi phí điều phối vượt lợi ích; quá lớn thì teammate làm quá lâu không check-in, tăng rủi ro công sức lãng phí.
• Đợi teammate hoàn thành: nếu thấy lead tự làm thay vì chờ, nhắc rõ “Wait for your teammates to complete their tasks before proceeding”.
• Bắt đầu với nghiên cứu/review: việc có ranh giới rõ, không cần viết code - review PR, nghiên cứu thư viện, điều tra bug.
• Tránh xung đột file: chia sao cho mỗi teammate sở hữu tập file riêng.
• Theo dõi và điều hướng: kiểm tra tiến độ, điều chỉnh hướng không hiệu quả, tổng hợp phát hiện khi chúng đến.

Giới hạn

Agent team đang là experimental với các giới hạn:

• Không resume in-process teammate: /resume, /rewind không khôi phục teammate in-process. Sau khi resume, lead có thể cố nhắn teammate không còn tồn tại - bảo lead spawn lại.
• Trạng thái task có thể trễ: teammate đôi khi quên đánh dấu task hoàn thành, chặn các task phụ thuộc.
• Shutdown có thể chậm: teammate hoàn thành request/tool call hiện tại trước khi tắt.
• Một team mỗi phiên: không tạo thêm team đặt tên khác hay chia sẻ team giữa các phiên.
• Không có team lồng nhau: teammate không tự spawn teammate của riêng nó.
• Không có subagent nền từ teammate in-process: teammate không thể chạy subagent chạy nền.
• Lead cố định: phiên chính là lead suốt vòng đời - không đổi lead giữa chừng.
• Permission đặt lúc spawn: mọi teammate bắt đầu với permission mode của lead.
• Split pane yêu cầu tmux hoặc iTerm2: chế độ in-process mặc định hoạt động trên mọi terminal.

Mẹo

CLAUDE.md hoạt động bình thường: teammate đọc file CLAUDE.md từ working directory của chúng - dùng để cung cấp hướng dẫn theo dự án cho toàn team.

Bước tiếp theo

• Subagent: giao việc nhẹ nhàng hơn cho agent phụ trong cùng phiên, phù hợp việc không cần phối hợp liên-agent.
• Worktree: chạy nhiều phiên Claude Code song song thủ công, không cần điều phối team tự động.

Nguồn

Dịch và biên soạn từ Orchestrate teams of Claude Code sessions.