Hướng dẫn khi nào nên dùng sub-Agent
Trong Claude Code có Agent tool, cho phép khởi chạy sub-Agent độc lập ngay giữa cuộc hội thoại. Sub-Agent có context riêng, làm xong việc thì trả kết quả về cho Agent chính.
Nghe thì mạnh mẽ, nhưng thực tế dùng thì đa số trường hợp bạn không cần đến nó. Bài này nói rõ: khi nào tách sub-Agent thực sự có ích, khi nào chỉ thêm rắc rối.
Bạn không thể gọi trực tiếp Agent tool trong CLAUDE.md hay slash command — đó là tool nội bộ mà Claude Code tự quyết định có dùng hay không. Nhưng bạn có thể tác động đến quyết định của nó thông qua prompt.
Cách sub-Agent hoạt động:
Đặc điểm quan trọng:
- Context độc lập: Sub-Agent không thấy lịch sử hội thoại chính, chỉ thấy prompt được truyền vào lúc khởi chạy
- Nén kết quả: Dù sub-Agent đọc bao nhiêu file, chạy bao nhiêu lệnh, trả về cho Agent chính chỉ là một đoạn tóm tắt
- Chạy song song được: Nhiều sub-Agent có thể khởi chạy đồng thời
Đây là kịch bản điển hình nhất. Bạn nhờ Claude Code điều tra một vấn đề cần kiểm tra nhiều hướng cùng lúc.
Ví dụ bạn hỏi: "Cơ chế xác thực trong dự án này được triển khai thế nào?"
Không tách Agent thì Claude Code sẽ chạy tuần tự: đọc auth controller → đọc middleware → đọc routes → đọc model → đọc config… từng bước một, chậm.
Tách thành sub-Agent:
Khởi chạy đồng thời 3 sub-Agent:
- Agent 1: Kiểm tra logic xác thực ở tầng controller và middleware
- Agent 2: Kiểm tra thiết kế user và session ở tầng model
- Agent 3: Kiểm tra cấu hình xác thực trong file config và biến môi trường
Ba hướng chạy cùng lúc, kết quả tổng hợp lại. Bạn có thể hướng dẫn trong CLAUDE.md như sau:
## Nhiệm vụ nghiên cứu
Khi cần điều tra vấn đề liên quan đến nhiều module,
ưu tiên khởi chạy song song nhiều sub-Agent để nghiên cứu từng hướng,
sau đó tổng hợp kết luận.
Context window của Claude Code có giới hạn. Nếu một sub-task cần đọc rất nhiều file nhưng cuối cùng chỉ cần một kết luận, sub-Agent giúp giữ "rác quá trình" ngoài context chính.
Ví dụ điển hình:
Đặc điểm chung của các task này: đầu vào lớn, đầu ra nhỏ. Sub-Agent tiêu hóa lượng thông tin khổng lồ bên trong, chỉ trả về phần tinh túy.
Có những task bạn không chắc có làm hỏng không. Dùng sub-Agent với tham số isolation: "worktree", nó sẽ làm việc trong một git worktree riêng biệt. Có hỏng cũng không ảnh hưởng thư mục làm việc hiện tại.
## Refactoring rủi ro cao
Với các task refactoring quy mô lớn, sử dụng sub-Agent có cách ly worktree.
Xác nhận kết quả chính xác rồi mới merge.
Kịch bản phù hợp:
- Refactoring thử nghiệm: không chắc phương án có khả thi không, để sub-Agent thử trước
- So sánh phương án song song: triển khai hai cách cùng lúc, so sánh kết quả
- Code generation: sinh nhiều boilerplate code, review xong mới merge
"Đổi tên hàm này từ camelCase sang snake_case" — cứ làm thẳng. Overhead của việc khởi chạy sub-Agent (xây dựng context, chờ kết quả, parse kết quả) còn chậm hơn làm trực tiếp.
Tiêu chí: Nếu một Grep + một Edit là xong, đừng tách Agent.
"Đọc config trước → sửa code theo config → cập nhật test theo thay đổi"
Kiểu task chuỗi như này, mỗi bước phụ thuộc vào kết quả bước trước. Tách thành sub-Agent thì phải truyền kết quả trung gian qua prompt qua lại — vừa phiền vừa dễ mất thông tin. Chạy tuần tự cho rồi.
Sub-Agent trả về đoạn text tóm tắt, không phải dữ liệu có cấu trúc. Nếu bạn cần sub-Agent thực hiện sửa đổi chính xác (ví dụ chèn đoạn code cụ thể vào dòng 47), để Agent chính làm đáng tin hơn.
Sub-Agent hợp với "nghiên cứu rồi đưa kết luận", không hợp với "thực thi sửa đổi chính xác".
Nếu cuộc hội thoại mới bắt đầu, context window còn trống, không cần tách Agent để "bảo vệ context". Đợi đến khi hội thoại dài ra, Agent chính bắt đầu nén lịch sử tin nhắn, lúc đó mới cân nhắc dùng sub-Agent cho việc nặng.
Lấy ví dụ một kịch bản thực: điều tra tất cả controller dùng before_action trong dự án Rails, phân tích pattern triển khai xác thực và phân quyền.
Không dùng sub-Agent:
Claude Code sẽ đọc từng file controller, mỗi file đọc đều chiếm context chính. Nếu có 20 controller, riêng nội dung file đã có thể ngốn rất nhiều token. Khi cuối cùng đưa ra phân tích, những chi tiết đọc trước đó có thể đã bị nén và mất.
Dùng sub-Agent:
Khởi chạy sub-Agent: "Đọc tất cả controller trong app/controllers/,
tìm tất cả callback before_action, phân tích pattern xác thực và phân quyền,
đưa ra tổng hợp theo phân loại."
Sub-Agent đọc hết file trong context riêng, trả về bản tóm tắt gọn gàng. Context của Agent chính gần như không bị tiêu tốn, nhận kết luận xong là tiếp tục được ngay.
Bạn không thể ép Claude Code dùng hay không dùng sub-Agent, nhưng có thể đưa ra preference qua CLAUDE.md:
## Preference sử dụng Agent
### Task nên tách sub-Agent
- Nghiên cứu xuyên module (kiểm tra 3+ thư mục cùng lúc)
- Tìm kiếm và thống kê code quy mô lớn
- Refactoring khám phá (dùng cách ly worktree)
### Task không nên tách sub-Agent
- Sửa đổi đơn file
- Thao tác nhiều bước có dependency tuần tự
- Bug fix đã rõ vị trí cần sửa
"Quá trình" của task này có lớn hơn nhiều so với "kết luận" không?
Nếu có — dùng sub-Agent, để nó tiêu hóa quá trình và chỉ trả về kết luận.
Nếu không — làm trực tiếp, đừng thêm lớp trung gian.
Sub-Agent không phải càng nhiều càng tốt. Đây là công cụ quản lý context, không phải framework lập trình đồng thời. Dùng đúng cách, Claude Code giữ được sự tỉnh táo trong dự án lớn. Dùng sai, chỉ lãng phí thời gian khởi chạy.