Subagents — Lớp phân công: chia việc cho đội trợ lý AI

Một agent chính không nên ôm tất cả mọi việc — giống như một công ty không thể có một người vừa làm CEO, vừa kế toán, vừa pháp chế, vừa marketing, vừa dev, vừa QA. Khi để một agent duy nhất vừa đọc log, vừa chạy test, vừa viết code, vừa nghiên cứu tài liệu, ngữ cảnh của nó nhanh chóng đầy ắp thông tin nhiễu, và chất lượng đi xuống.

Subagents là lời giải: chia việc cho các agent con, mỗi cái có ngữ cảnh riêng, công cụ riêng, quyền riêng và nhiệm vụ riêng. Agent chính giữ vai điều phối; các subagent xử lý phần chuyên sâu. Đây chính là tư duy tổ chức đội nhóm trong kỷ nguyên AI.

Subagent là gì

Một subagent là một instance Claude riêng, chạy trong một context window RIÊNG, với system prompt riêng, quyền truy cập tool riêng và permission riêng. Khi một task khớp với description của subagent, agent chính tự ủy thác (delegate); subagent làm việc độc lập rồi chỉ trả về bản tóm tắt kết quả cho luồng chính (Anthropic — Subagents in Claude Code).

Điểm mấu chốt nằm ở câu in đậm: subagent làm việc trong cửa sổ ngữ cảnh riêng. Kết quả tìm kiếm, log, các file đọc để khám phá — tất cả không bao giờ chạm vào cuộc hội thoại chính (Claude Docs — Subagents). Đây là lý do subagent bảo vệ ngữ cảnh cực tốt.

Bốn lợi ích chính

1. Bảo toàn ngữ cảnh — cô lập thao tác tạo nhiều output (đọc log, quét codebase) vào subagent để luồng chính không bị "ngập".
2. Ép ràng buộc — giới hạn tool của subagent (ví dụ chỉ đọc, không được ghi) để nó không thể làm điều ngoài phạm vi.
3. Tái sử dụng & chuyên biệt hóa — định nghĩa một lần, dùng lại nhiều dự án; mỗi subagent có "tính cách" và chuyên môn riêng.
4. Kiểm soát chi phí — định tuyến subagent sang mô hình rẻ hơn (ví dụ Haiku) cho các việc đơn giản.

Claude Code có sẵn vài subagent dựng sẵn, ví dụ Explore (chỉ đọc — tìm/hiểu codebase) và Plan (nghiên cứu trong chế độ lập kế hoạch). Chúng cố tình bỏ qua một số bước để chạy nhanh và rẻ.

Định nghĩa subagent: file Markdown + frontmatter

Một subagent là một file .md đặt trong .claude/agents/ (phạm vi dự án) hoặc ~/.claude/agents/ (phạm vi cá nhân) (Claude Docs — Subagents):

---
name: code-reviewer
description: Rà soát chất lượng và bảo mật code. Dùng chủ động sau khi
  viết xong một thay đổi lớn.
tools: Read, Glob, Grep
model: sonnet
---

Bạn là một reviewer code. Khi được gọi, phân tích thay đổi và đưa phản
hồi cụ thể về chất lượng, bảo mật và best practice. Chỉ đọc, không sửa.

• Bắt buộc: name (chữ thường + gạch nối) và description (mô tả khi nào nên ủy thác).
• Tùy chọn: tools, disallowedTools, model (sonnet/opus/haiku/inherit), permissionMode, maxTurns, skills, mcpServers, hooks, memory...
• Phần thân = system prompt của subagent.

Một điều rất quan trọng và hay bị hiểu sai: subagent chỉ nhận system prompt này cộng thông tin môi trường cơ bản. Nó không nhận system prompt đầy đủ của Claude Code, và không thấy lịch sử hội thoại chính. Nó bắt đầu mới tinh (fresh) và chỉ nhận một "task message" do Claude chính soạn (Claude Docs — Subagents).

Khi trùng name, thứ tự ưu tiên theo vị trí: managed (cao nhất) → CLI → project → user → plugin (thấp nhất).

Cách gọi subagent

• Tự động: dựa trên description; thêm cụm như "dùng chủ động" để khuyến khích ủy thác.
• Gọi tên tự nhiên trong prompt, hoặc @-mention để chắc chắn đúng subagent chạy.
• Cả phiên dưới một subagent: claude --agent <name>.

Viết description tốt là chìa khóa: đó là căn cứ để agent chính quyết định ủy thác. Mô tả mơ hồ → hoặc không bao giờ được gọi, hoặc bị gọi sai lúc.

Fan-out: chạy song song nhiều subagent

Sức mạnh lớn nhất cho việc quy mô là fan-out: agent chính sinh nhiều subagent độc lập chạy song song, rồi tổng hợp kết quả. Ví dụ: rà soát một codebase lớn bằng cách giao mỗi module cho một subagent; hoặc nghiên cứu một chủ đề bằng cách cho nhiều subagent tra cứu các nguồn khác nhau cùng lúc rồi gom lại (Claude Docs — Workflows).

Các mẫu dùng phổ biến:

• Review code: một subagent chỉ-đọc kiểm tra chất lượng/bảo mật.
• Chạy test: một subagent chạy test và chỉ báo cáo phần fail.
• Nghiên cứu song song: nhiều subagent tra cứu đồng thời.
• Chuỗi tuần tự: reviewer → optimizer (agent này nối tiếp agent kia).

Best practices

• Mô tả chính xác + phạm vi tool hẹp. Bắt đầu bằng quyền chỉ-đọc, chỉ mở thêm khi cần.
• Prompt tập trung. Phần thân nên nói rõ vai trò và giới hạn, vì subagent không có ngữ cảnh chính.
• Cô lập output lớn. Đọc log, quét file — đẩy vào subagent để giữ luồng chính gọn.
• Commit phạm vi dự án. Đặt subagent trong .claude/agents/ và commit để cả team dùng chung.

Giới hạn & cạm bẫy

• Ngữ cảnh mới tinh đôi khi tốn thời gian gom lại bối cảnh — subagent không hợp cho việc cần lặp qua lại nhiều lần với người dùng.
• Độ sâu lồng nhau có giới hạn. Trong Claude Agent SDK, subagent có thể lồng tới 5 tầng; còn trong Claude Code, theo tài liệu cộng đồng tiếng Việt (AZDIGI), một subagent không gọi được subagent khác — nên xác nhận theo ngữ cảnh sản phẩm bạn dùng.
• Với agent do PLUGIN cung cấp: một số cấu hình như hooks, mcpServers, permissionMode không được hỗ trợ (vì lý do bảo mật).
• Không dùng được các tool cần tương tác UI trong subagent.

Một hiểu lầm quan trọng

Nhiều người tưởng subagent "thấy mọi thứ" của phiên chính. Thực tế ngược lại: nó bắt đầu fresh và chỉ nhận task message. Điều này vừa là điểm mạnh (bảo vệ ngữ cảnh, phân quyền) vừa là điểm cần lưu ý (phải mô tả task đủ rõ, vì subagent không tự "biết" bối cảnh chính).

Phân biệt nhanh với các lớp khác: **Skill đổi hành vi, Subagent bảo vệ ngữ cảnh và phân quyền, MCP thêm năng lực, Hook đảm bảo hành động tất định.** Bốn lớp bổ trợ nhau, không thay thế nhau.

Tóm tắt & bước tiếp theo

Subagents là lớp phân công: mỗi subagent là một Claude riêng với ngữ cảnh, tool và quyền riêng, được định nghĩa bằng file Markdown trong .claude/agents/, ủy thác theo description, và mạnh nhất khi fan-out song song. Chúng giữ luồng chính gọn và cho phép bạn dựng cả một "đội" AI.

Đến đây bạn đã có bốn lớp: bộ nhớ (CLAUDE.md), chuyên môn (Skills), kiểm soát (Hooks), phân công (Subagents). Nhưng làm sao chia sẻ toàn bộ cấu hình này cho cả đội, thay vì mỗi người tự dựng lại? Đó là vai trò của Plugins — Bài 5.

Nguồn tham khảo

• Anthropic — How and when to use subagents in Claude Code: https://claude.com/blog/subagents-in-claude-code
• Claude Docs — Create custom subagents: https://docs.claude.com/en/docs/claude-code/sub-agents
• Claude Docs — Subagents in the SDK: https://docs.claude.com/en/docs/claude-code/sdk/subagents
• Claude Docs — Orchestrate subagents with dynamic workflows: https://code.claude.com/docs/en/workflows
• AZDIGI — Hướng dẫn dùng Subagents (tiếng Việt): https://azdigi.com/blog/tri-tue-nhan-tao/huong-dan-dung-subagents-trong-claude-de-tao-doi-tro-ly-ai-thong-minh

Bài 4/7 trong chuỗi "Bộ công cụ phát triển Agent với Claude". Nội dung diễn giải lại từ tài liệu gốc của Anthropic. Trước ← Bài 3: Hooks · Tiếp theo → Bài 5: Plugins & Marketplace.