Subagents

Subagent là các “trợ lý” chuyên biệt mà agent chính (main agent) có thể giao việc, mỗi subagent chạy trong cửa sổ ngữ cảnh riêng, với system prompt, bộ tool và quyền hạn riêng — tách biệt hoàn toàn khỏi hội thoại chính.

Vì sao dùng Subagent

Tiết kiệm ngữ cảnh chính: một việc phụ (đọc hàng loạt log, tìm kiếm trong codebase lớn) nếu làm trực tiếp sẽ “ngập” hội thoại chính bằng nội dung bạn không cần xem lại. Giao cho subagent, nó tự đọc trong ngữ cảnh riêng, chỉ trả về kết quả tóm tắt.
Giới hạn quyền: subagent chỉ dùng được đúng tập tool bạn cho phép — ví dụ một subagent review code chỉ nên có quyền đọc, không có quyền sửa file.
Tái sử dụng: định nghĩa một lần ở cấp cá nhân (~/.claude/agents/), dùng lại ở mọi dự án.
Chuyên biệt hoá: một subagent “code-reviewer” chỉ tập trung review, một subagent “test-writer” chỉ tập trung viết test — mỗi subagent có system prompt riêng phù hợp vai trò.
Tiết kiệm chi phí: định tuyến việc đơn giản sang model rẻ, nhanh hơn (ví dụ Haiku) thay vì luôn dùng model mạnh nhất.

Claude dựa vào phần mô tả (description) của mỗi subagent để quyết định khi nào nên giao việc cho nó — vì vậy mô tả càng rõ ràng, Claude càng biết đúng lúc cần dùng.

Các subagent có sẵn

Claude Code đã tích hợp sẵn vài subagent, tự động được gọi khi phù hợp — bạn không cần tự định nghĩa những cái này:

Subagent	Vai trò
Explore	Tìm kiếm/phân tích codebase nhanh, chỉ đọc, không sửa gì
Plan	Nghiên cứu codebase để phục vụ plan mode
general-purpose	Việc phức tạp, nhiều bước, cần cả tìm hiểu lẫn chỉnh sửa

Tạo Subagent của riêng bạn

Cách nhanh nhất: nhờ Claude viết giúp, ví dụ:

Tạo một subagent cá nhân tên code-improver ở ~/.claude/agents/, quét file
và đề xuất cải thiện về khả năng đọc, hiệu năng, best practice. Nó chỉ cần
đọc file (không sửa), dùng model Sonnet.

Claude sẽ tạo ra một file markdown như sau:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Sau đó thử ngay: dùng subagent code-improver để rà soát dự án này.

Bạn cũng có thể tự viết file này bằng tay — chỉ cần một file markdown có frontmatter YAML (name, description, tools, model tuỳ chọn) và phần system prompt bên dưới.

Đặt Subagent ở đâu

Vị trí	Phạm vi
`.claude/agents/`	Dự án hiện tại — commit vào git để chia sẻ với team
`~/.claude/agents/`	Mọi dự án của riêng bạn
Cấu hình cấp tổ chức	Toàn tổ chức, do quản trị viên triển khai

Khi nhiều subagent trùng tên, vị trí có độ ưu tiên cao hơn (gần thư mục làm việc hơn) sẽ thắng.

Quản lý & giới hạn

/agents — xem danh sách và trạng thái subagent trong phiên hiện tại. (Ở các bản mới, /agents chỉ nhắc bạn chỉnh trực tiếp file trong .claude/agents/ hoặc nhờ Claude tạo/sửa giúp, thay vì mở trình hướng dẫn tương tác như trước.)
Muốn chặn Claude tự động giao việc cho subagent, thêm quy tắc từ chối tool Agent vào permissions.deny trong settings.json (xem Cấu hình).

Khi nào nên tạo Subagent riêng

Tạo subagent khi bạn thấy mình lặp lại cùng một loại yêu cầu nhiều lần (review code, viết docs, khảo sát codebase theo một cách cố định…) và muốn cấu hình cứng về: tool được phép dùng, phong cách trả lời, hoặc phạm vi trách nhiệm — thay vì phải nhắc lại yêu cầu đó mỗi lần trong hội thoại.