Làm chủ subagents trong Claude Code

Subagents là các thực thể AI chuyên biệt, vận hành trong những cửa sổ ngữ cảnh (context window) cô lập để xử lý từng tác vụ cụ thể thay vì nhồi mọi thứ vào luồng chat chính

. Chúng giải quyết hai thách thức lớn nhất của hệ thống agentic: kiểm soát sự bùng nổ ngữ cảnh và độ chính xác khi chọn công cụ. Thay vì để một agent duy nhất gánh mọi yêu cầu, bạn phân rã công việc thành các luồng độc lập — tăng cả hiệu suất lẫn độ tin cậy cho toàn bộ quy trình phát triển.

Về mặt kiến trúc, subagents giữ cho luồng chat chính tinh gọn vì nó chỉ nhận về kết quả tóm tắt cuối cùng. Cách này chặn đứng "context bloat" — thủ phạm chính kéo tụt chất lượng đầu ra khi cửa sổ ngữ cảnh bị lấp đầy bởi kết quả tìm kiếm, log hoặc nội dung file thô không cần cho bước suy luận tiếp theo.

Sơ đồ kiến trúc điều phối: luồng chính (orchestrator) giao việc cho ba subagent chuyên biệt, mỗi subagent chạy trong cửa sổ ngữ cảnh riêng và trả về bản tóm tắt.

Subagents trong Claude Code là gì và tại sao nên dùng?

Subagents là các trợ lý chuyên biệt, có system prompt riêng, danh sách công cụ (tools) và quyền hạn độc lập. Trong Claude Code, luồng chat chính đóng vai "orchestrator" (bộ điều phối): nó giao việc cho subagents và thu thập kết quả trả về.

Subagents mang lại bốn lợi ích kỹ thuật cốt lõi:

Quản lý ngữ cảnh: chất lượng đầu ra của mô hình ngôn ngữ lớn (LLM) bắt đầu giảm khi ngữ cảnh đạt khoảng 30–50% dung lượng cửa sổ (context bloat). Subagent xử lý các tác vụ tốn tài nguyên trong cửa sổ riêng và chỉ trả về bản tóm tắt, nhờ đó luồng chính luôn sạch.
Chuyên môn hóa: khi giới hạn số công cụ và tập trung vào một system prompt hẹp, subagent chọn đúng tool với xác suất cao hơn hẳn một agent tổng quát đang ôm quá nhiều công cụ.
Tối ưu chi phí: bạn có thể cấu hình subagent dùng model Haiku cho tác vụ research hoặc tìm kiếm code đơn giản thay vì Sonnet, giảm đáng kể lượng token tiêu thụ.
Cô lập: mỗi subagent khởi đầu với ngữ cảnh hoàn toàn mới, loại bỏ nhiễu từ lịch sử hội thoại của luồng chính.

Khi nào nên giao việc cho subagent (và khi nào không)?

Lạm dụng subagent cho mọi tác vụ nhỏ chỉ gây lãng phí vì chi phí khởi tạo (overhead). Hãy phân loại như sau.

Bảng so sánh khi nào nên giao việc cho subagent (nghiên cứu diện rộng, tác vụ tạo output lớn, chạy song song) và khi nào nên giữ ở luồng chính (việc đơn giản một bước, phụ thuộc tuần tự chặt, cần tương tác liên tục).

Nên giao cho subagent:

Nghiên cứu diện rộng: quét toàn bộ repository để tìm mẫu code, lỗ hổng bảo mật hoặc audit thư viện.
Tác vụ tạo output lớn: chạy test suite, fetch tài liệu kỹ thuật hoặc xử lý file log khổng lồ.
Chuyên môn hóa sâu: việc cần một persona kỹ thuật cụ thể, ví dụ chuyên gia bảo mật hoặc kiến trúc sư.
Chạy song song: thử đồng thời nhiều hướng giải quyết để so sánh kết quả.

Nên giữ ở luồng chính:

Tác vụ cực đơn giản: việc chỉ cần một lần gọi tool, ví dụ đọc một file cấu hình.
Chuỗi phụ thuộc chặt: bước sau bám sát từng suy luận của bước trước.
Cần tương tác liên tục: việc buộc bạn phải chỉnh hướng thường xuyên qua phản hồi chat.

Claude Code có sẵn những subagent nào?

Claude Code tích hợp sẵn các subagent được tối ưu cho từng giai đoạn phát triển:

Ba subagent tiêu chuẩn của Claude Code: Explore dùng model Haiku và chỉ đọc, Plan chỉ đọc dùng khi lập kế hoạch, và General-purpose có toàn quyền công cụ.

Subagent	Model mặc định	Quyền truy cập công cụ	Mục đích
Explore	Haiku	Read-only (chỉ đọc)	Tìm kiếm file, khám phá codebase nhanh và rẻ.
Plan	Kế thừa / Sonnet mặc định	Read-only (chỉ đọc)	Dùng trong Plan Mode để thu thập ngữ cảnh trước khi lập kế hoạch.
General-purpose	Kế thừa / Sonnet mặc định	Toàn quyền (all tools)	Xử lý các tác vụ đa bước phức tạp, gồm cả chỉnh sửa code.

Làm thế nào để tạo và cấu hình subagent của riêng bạn?

Dùng lệnh /agents để mở giao diện quản lý. Tại đây bạn tạo subagent mới ở:

Project scope: lưu tại .claude/agents/ (chỉ áp dụng cho dự án hiện tại, nên đưa vào Git).
User scope: lưu tại ~/.claude/agents/ (áp dụng cho mọi dự án trên máy cá nhân).

Ví dụ cấu hình YAML cho một subagent rà soát bảo mật:

yaml

---
name: security-auditor
description: Dùng để rà soát mã nguồn tìm lỗ hổng bảo mật, SQL injection hoặc lộ secret.
tools: [bash, read_file, grep]
model: sonnet
memory: project
isolation: worktree
color: red
---
Bạn là một kỹ sư bảo mật cao cấp. Hãy rà soát code và tìm các lỗ hổng tiềm ẩn.

Các thông số kỹ thuật quan trọng:

isolation: worktree: subagent chạy trên một git worktree tạm thời, cô lập hoàn toàn thay đổi file system khỏi nhánh bạn đang làm.
Memory scopes:
- project: lưu tại .claude/agent-memory/, kiến thức chia sẻ giữa các thành viên qua Git.
- local: lưu tại .claude/agent-memory-local/, kiến thức của dự án nhưng không commit.
- user: lưu tại ~/.claude/agent-memory/, subagent ghi nhớ thông tin xuyên suốt mọi dự án bạn tham gia.

Có những mẫu phối hợp subagent nào hiệu quả?

Sơ đồ mẫu phối hợp ba giai đoạn pm-spec, architect-review, implementer-tester chạy song song để quét toàn bộ codebase.

Mô hình 3 giai đoạn (PubNub pattern)

Quy trình: pm-spec (viết spec) → architect-review (viết ADR — Architecture Decision Record) → implementer-tester (viết code và test). Cách tách bạch này đảm bảo code chỉ được triển khai dựa trên một thiết kế đã qua kiểm duyệt.

Nghiên cứu song song

Bạn có thể gọi nhiều agent cùng lúc để tăng tốc. Cú pháp CLI ví dụ: "Can you kick off 10 @security-auditor agents to scan all modules for vulnerabilities?" Chạy song song 5–10 agent giúp quét toàn bộ codebase trong thời gian ngắn mà không làm tràn ngữ cảnh của orchestrator.

Tự động hóa với Hooks

Bạn có thể cấu hình để subagent tự đề xuất bước tiếp theo qua tệp .claude/settings.json. Ví dụ một hook SubagentStop:

json

{
  "hooks": [
    {
      "event": "SubagentStop",
      "agent_type": "architect-review",
      "command": "echo 'Suggested next step: Use @implementer-tester subagent on this feature.'"
    }
  ]
}

Những sai lầm thường gặp khi dùng subagent là gì?

Output của Hook không hiển thị: đảm bảo script in kết quả ra STDOUT. Nếu in ra /dev/tty, Claude không đọc được output để hiển thị trong transcript.
Lỗi "No next-step suggestion": xảy ra khi hàng đợi trạng thái không được cập nhật đúng (ví dụ từ READY_FOR_ARCH sang READY_FOR_BUILD), khiến hook không kích hoạt được lệnh gợi ý.
Tràn lan công cụ (tool sprawl): nếu không giới hạn tool trong YAML, subagent kế thừa toàn bộ tool của luồng chính, gây nhiễu cho việc chọn công cụ.
Mất ngữ cảnh: đừng ép subagent nối tiếp việc của một agent khác mà không truyền đầy đủ tham số đầu vào, vì mỗi subagent (trừ fork) đều khởi đầu với bộ nhớ trống.

Bắt đầu với subagents như thế nào?

Để dựng hệ thống đầu tiên, làm theo năm bước:

Khởi tạo: dùng lệnh /agents và chọn "Create new agent".
Cấu hình: thiết lập tệp .md, chọn model (Haiku cho research, Sonnet cho logic).
Quyền hạn: giới hạn tool ở mức tối thiểu cần thiết để tăng độ chính xác.
Chạy thử: dùng cú pháp @tên-agent <nhiệm vụ> ngay trong chat.
Phê duyệt (human-in-the-loop): subagent gợi ý thay đổi qua Hook, bạn nhấn Enter để xác nhận cho luồng chính thực thi.

Các câu hỏi thường gặp

Subagent có thể gọi subagent khác không? Không. Subagent bị chặn gọi lồng nhau để tránh vòng lặp vô hạn. Tuy nhiên, bạn có thể cho orchestrator gọi chúng tuần tự (chaining) dựa trên kết quả trả về.

Làm sao xem lại transcript của subagent? Mọi chi tiết được lưu trong tệp .jsonl tại ~/.claude/projects/{project}/{sessionId}/subagents/.

Fork khác gì với subagent định danh? Fork kế thừa toàn bộ lịch sử chat hiện tại để xử lý việc phát sinh, còn subagent định danh khởi đầu với ngữ cảnh sạch dựa trên cấu hình tệp .md.