Subagents trong Claude Code: hướng dẫn thực chiến (2026)

tác giả: Jasmine, dev dùng Claude Code và subagents mỗi ngày.

Subagents trong Claude Code là gì?

Subagent là một phiên bản Claude chuyên biệt mà agent chính có thể spawn ra để xử lý một tác vụ cụ thể, chạy trong cửa sổ ngữ cảnh (context window) riêng, với system prompt và bộ tool riêng, rồi báo cáo kết quả cô đọng về agent chính. Nói ngắn gọn: thay vì để một Claude "ôm" toàn bộ công việc trong cùng một khung hội thoại, bạn chia việc cho những trợ lý con - mỗi trợ lý là một AI agent chuyên biệt cho một vai trò.

Hãy hình dung agent chính như một tech lead. Khi gặp một việc lớn - ví dụ "review toàn bộ codebase về bảo mật" - tech lead không tự đọc hết mọi file trong đầu mình. Anh ta giao cho một chuyên gia security đọc, tổng hợp lại, rồi báo cáo. Subagent chính là chuyên gia đó: nó có mô tả nhiệm vụ (system prompt), được cấp một số quyền nhất định (tools), và khi xong việc chỉ trả về phần kết luận cần thiết.

Điểm khác biệt cốt lõi so với việc bạn tự gõ thêm yêu cầu vào cùng một phiên: Claude Code subagents có ngữ cảnh tách biệt. Toàn bộ đống thông tin trung gian mà subagent phải đọc để làm việc sẽ nằm trong "đầu" của nó, không tràn ngược vào phiên chính. Bạn khai báo mỗi subagent bằng một file Markdown đơn giản đặt trong thư mục .claude/agents/, và Claude Code tự động nhận ra chúng.

Subagents hoạt động thế nào? (context isolation)

Cơ chế đứng sau subagents gọi là context isolation - cách ly ngữ cảnh. Đây là lý do thật khiến subagents đáng dùng, chứ không phải chỉ là "gọi thêm một con AI cho oai".

Luồng chạy điển hình như sau:

1. Agent chính nhận yêu cầu của bạn và quyết định tác vụ nào nên giao cho subagent.
2. Nó spawn subagent tương ứng, kèm một mô tả nhiệm vụ cụ thể.
3. Subagent chạy trong cửa sổ ngữ cảnh riêng - một "hộp cách ly nhận thức". Nó tự đọc file, chạy lệnh, suy luận... tất cả trong không gian riêng.
4. Khi xong, subagent chỉ trả về kết quả cô đọng (tóm tắt, danh sách lỗi, đoạn code...), không đổ toàn bộ quá trình vào phiên chính.

Bạn
 └─► Agent chính (context chính, gọn)
 ├─► subagent: test-runner ──► trả về: 2 test fail
 ├─► subagent: security-scan ──► trả về: 1 lỗ hổng SQLi
 └─► subagent: style-checker ──► trả về: 5 cảnh báo lint
 (mỗi subagent = 1 cửa sổ ngữ cảnh riêng)

Vì subagent "nuốt" phần ngữ cảnh nặng nề (đọc hàng chục file, log dài) và chỉ nhả ra phần tinh, phiên chính của bạn giữ được context sạch và dài hơi hơn. Đây vừa là chuyện tiết kiệm token (context chính không phình ra), vừa là chuyện chất lượng: agent chính không bị nhiễu bởi rác trung gian nên suy luận sắc hơn. Chi tiết cơ chế và phạm vi (scope) được Anthropic mô tả trong tài liệu chính thức Claude Code Subagents (truy cập 08/2026).

Cần phân biệt rõ với việc bạn tự mở một tab chat mới. Khi bạn chat thủ công trong nhiều phiên, chính bạn là người copy kết quả qua lại - chậm và dễ sót. Với subagents, agent chính điều phối toàn bộ luồng: nó quyết định giao gì, cho ai, và ghép kết quả lại một cách tự động trong cùng một lượt làm việc. Bạn không phải rời khỏi terminal.

Một điểm hay bị hiểu lầm: cách ly ngữ cảnh không có nghĩa subagent "ngu" hơn. Nó vẫn là cùng một dòng model bạn chọn, chỉ khác là nó tập trung vào đúng một nhiệm vụ với đúng bộ tool cần thiết. Ràng buộc phạm vi thường làm kết quả tốt hơn chứ không kém đi - giống như giao một việc rõ ràng cho một chuyên gia thay vì bảo một người ôm mười việc cùng lúc.

Tạo subagent đầu tiên - file .claude/agents

Đây là phần thực hành cốt lõi. Có hai cách tạo subagent: dùng giao diện /agents (khuyến nghị cho lần đầu) hoặc viết file Markdown bằng tay. Cả hai đều ra cùng một kết quả - một file trong .claude/agents/.

Bước 1 - Mở trình quản lý agent

Trong một phiên Claude Code, gõ:

/agents

Giao diện sẽ hiện danh sách agent hiện có và cho phép bạn tạo mới, chọn scope, chọn model và giới hạn tool bằng menu. Nếu thích kiểm soát trực tiếp, bạn có thể bỏ qua bước này và tự tạo file - kết quả giống hệt.

Bước 2 - Chọn scope: project hay user

Có hai nơi đặt file agent, và chọn đúng nơi rất quan trọng:

• Project-level - .claude/agents/ trong thư mục dự án. Chỉ áp dụng cho dự án này, commit được vào Git để cả team dùng chung. Chọn cái này cho agent đặc thù dự án (ví dụ reviewer hiểu convention riêng).
• User-level - ~/.claude/agents/ trong home directory. Áp dụng cho mọi dự án của bạn. Chọn cái này cho agent dùng ở đâu cũng tiện (ví dụ một doc-writer chung).

Khi trùng tên, agent project-level sẽ ưu tiên hơn user-level.

Bước 3 - Viết file agent (ví dụ thật)

Tạo file .claude/agents/code-reviewer.md với nội dung sau. Phần đầu là frontmatter YAML, phần thân là system prompt của subagent:

---
name: code-reviewer
description: Review code về bug, bảo mật và maintainability. Dùng ngay sau khi vừa viết hoặc sửa code.
tools: Read, Grep, Glob
model: sonnet
---

Bạn là một reviewer code cấp senior. Nhiệm vụ:
- Đọc phần code vừa thay đổi (dùng Read/Grep/Glob, KHÔNG sửa file).
- Tìm bug logic, lỗ hổng bảo mật, và chỗ khó bảo trì.
- Xếp phát hiện theo mức độ: nghiêm trọng / nên sửa / gợi ý.
- Trả về danh sách ngắn gọn kèm đường dẫn file và số dòng.
Không chạy lệnh ghi, không commit, không đổi code.

Bước 4 - Xác minh

Chạy lại /agents để chắc chắn code-reviewer xuất hiện trong danh sách. Thế là xong - bạn vừa có subagent đầu tiên. Từ giờ khi bạn vừa sửa code, Claude có thể tự gọi nó, hoặc bạn gọi thẳng: "dùng subagent code-reviewer để soi lại phần vừa sửa".

Các trường frontmatter (name, description, tools, model)

Frontmatter quyết định subagent hành xử ra sao. Chỉ có bốn trường cần nhớ:

Hai mẹo đáng giá: (1) Viết description rõ ràng, có động từ và tình huống ("Dùng ngay sau khi..."), vì đây là căn cứ để Claude auto-gọi đúng lúc. (2) Với agent chỉ cần đọc, hãy giới hạn tools còn Read, Grep, Glob - subagent sẽ không thể lỡ tay sửa hay xoá file.

Gọi & quản lý subagents

Có ba cách kích hoạt một subagent:

1. Auto-delegation - Claude tự chọn subagent phù hợp dựa trên trường description. Bạn cứ làm việc bình thường, khi ngữ cảnh khớp (ví dụ vừa sửa code xong), Claude tự giao cho code-reviewer.
2. Gọi trực tiếp - nêu tên agent trong yêu cầu: "dùng subagent code-reviewer để kiểm tra module thanh toán". Cách này chắc chắn nhất khi bạn biết mình cần gì.
3. Quản lý qua /agents - mở giao diện để list, sửa, hoặc xoá agent; đổi model, thêm/bớt tool mà không cần mở file tay.

Nếu một subagent "mãi không được gọi" dù bạn nghĩ nó nên được gọi, thủ phạm gần như luôn là description quá mơ hồ. Viết lại cho cụ thể là fix được.

Chạy song song & orchestrate nhiều subagent

Đây là chỗ subagents thật sự tỏa sáng, và cũng là phần đa số hướng dẫn tiếng Việt bỏ qua. Vì mỗi subagent chạy trong ngữ cảnh riêng, agent chính có thể bung nhiều subagent cùng lúc trên cùng một codebase.

Ví dụ: ba subagent chạy song song

Giả sử bạn vừa hoàn thành một feature và muốn kiểm tra toàn diện trước khi mở PR. Thay vì làm tuần tự, yêu cầu:

Chạy song song 3 subagent trên nhánh hiện tại:
- test-runner: chạy full test suite, báo test nào fail
- security-scanner: soi lỗ hổng trong phần code vừa đổi
- style-checker: kiểm tra lint và convention
Gom kết quả của cả ba lại thành một báo cáo.

Ba agent chạy độc lập, mỗi cái tự đọc thứ nó cần, rồi agent chính tổng hợp ba báo cáo gọn. Bạn tiết kiệm cả thời gian lẫn context.

Về mặt token, hãy hiểu đúng cơ chế trước khi kỳ vọng "tiết kiệm bao nhiêu phần trăm". Cái được tiết kiệm không phải tổng token - chạy ba agent vẫn tốn token cho cả ba. Cái được tiết kiệm là token của phiên chính: toàn bộ log test, dấu vết quét bảo mật và cảnh báo lint nằm trong context của từng subagent, chỉ có kết luận vài dòng đi ngược về. Nhờ đó phiên chính không bị đầy sớm và bạn giữ được mạch làm việc dài hơn. Lợi ích thật là ở đó, không phải ở một con số phần trăm cố định.

Orchestration nhiều tầng

Nâng cao hơn: output của subagent này làm input cho subagent kế. Một luồng explore → plan → implement điển hình:

1) subagent "explorer": khảo sát codebase, trả về bản đồ module + chỗ cần đổi.
2) Đưa kết quả đó cho subagent "planner": lập kế hoạch từng bước.
3) Đưa kế hoạch cho subagent "implementer": thực thi theo từng bước.

Đây là mô hình điều phối (orchestrate) mạnh, nhưng phải hiểu một giới hạn quan trọng bên dưới.

Giới hạn phải biết

Các subagent không chia sẻ context trực tiếp với nhau và không "nói chuyện" ngang hàng. Chúng chỉ trả kết quả về agent chính, và chính agent chính mới chuyển tiếp thông tin sang subagent kế. Mỗi lần spawn là một round-trip token. Nghĩa là orchestration nhiều tầng có sức mạnh, nhưng cũng có cái giá của nó - đừng lạm dụng. Muốn hiểu rõ subagents khác Skills/Hooks/MCP ở đâu, xem bài phân biệt Skills, Subagents, Hooks, MCP.

Vài mẫu subagent đáng dùng ngay

Bốn template copy-paste, chỉnh nhẹ là dùng được:

1. Read-only reviewer (an toàn tuyệt đối)

---
name: safe-reviewer
description: Review code chỉ đọc, không bao giờ sửa file. Dùng để soi trước khi merge.
tools: Read, Grep, Glob
model: sonnet
---
Bạn chỉ đọc và nhận xét. Không chạy lệnh ghi. Trả về lỗi theo mức độ.

2. Test-runner

---
name: test-runner
description: Chạy test suite và tóm tắt test fail. Dùng sau khi sửa code.
tools: Bash, Read, Grep
model: haiku
---
Chạy test của dự án, đọc output, liệt kê test fail kèm nguyên nhân ngắn gọn.

3. Doc-writer

---
name: doc-writer
description: Viết/cập nhật tài liệu và docstring cho code mới.
tools: Read, Grep, Glob, Edit
model: sonnet
---
Đọc code, viết tài liệu rõ ràng, đúng phong cách repo. Không đổi logic code.

4. Explorer

---
name: explorer
description: Khảo sát codebase lạ, trả về bản đồ kiến trúc và điểm vào.
tools: Read, Grep, Glob
model: sonnet
---
Lập bản đồ module, luồng dữ liệu, và các file quan trọng. Chỉ đọc, không sửa.

Để ý cả bốn mẫu: agent nào không cần ghi thì không cấp quyền ghi. Đó là thói quen an toàn nên giữ.

Subagents khác gì Skills, Hooks, MCP?

Bốn khối này hay bị nhầm. Phân định nhanh:

Ngắn gọn: subagents chia việc, Skills dạy quy trình, Hooks tự động hoá sự kiện, MCP mở rộng kết nối. Bài phân biệt đầy đủ 4 khối đi sâu hơn nếu bạn còn lăn tăn nên dùng cái nào.

Lỗi thường gặp & giới hạn thật

Phần này ít blog nào chịu viết, nhưng lại là thứ giúp bạn dùng subagents đúng cách:

• Over-delegate. Tách một việc bé xíu (đổi một biến, sửa một dòng) thành subagent là phản tác dụng - round-trip token và độ trễ còn tốn hơn tự làm. Subagents hợp với việc "nặng ngữ cảnh, kết quả gọn".
• description mơ hồ → không được auto-gọi. Nếu mô tả chung chung, Claude không biết khi nào nên giao. Viết cụ thể tình huống dùng.
• Quên giới hạn tools. Một reviewer lẽ ra chỉ đọc nhưng được cấp quyền ghi có thể sửa nhầm file. Luôn cấp quyền tối thiểu.
• Ngốn token khi bung quá nhiều agent. Chạy song song 5-6 agent nghe thì oách nhưng mỗi cái là một phiên tính phí riêng. Bung có chủ đích.
• Khi nào KHÔNG nên tách: khi tác vụ cần đúng full context của cuộc hội thoại hiện tại (ví dụ đang debug một luồng dài mà mọi chi tiết trước đó đều liên quan). Subagent không thấy context chính, tách ra là mất ngữ cảnh.

Khỏi tự viết - 45 agent dựng sẵn của AgentKit

Viết một subagent tốt tốn công tinh chỉnh prompt và test đi test lại. Nếu bạn muốn có sẵn một thư viện agent chuyên biệt thay vì viết từ đầu, 45 agents dựng sẵn của AgentKit là một lối tắt tùy chọn. Đây là bộ kit cho Claude Code (không phải OpenAI AgentKit - trùng tên thôi), ship 45 agents = 17 Engineer + 28 Marketing cùng 108+ skills. Muốn xem danh mục agent trước khi quyết, đọc tổng quan 45 agent dựng sẵn của AgentKit. Engineer Kit giá $99 (trang không nêu phí định kỳ). Dù vậy, tự viết vài agent theo đúng convention repo của bạn vẫn là kỹ năng nền đáng học - kit chỉ giúp đi nhanh hơn.

Câu hỏi thường gặp (FAQ)

Subagents có tốn thêm tiền không?

Có, gián tiếp. Mỗi subagent là một phiên có ngữ cảnh riêng nên tiêu token riêng; chạy nhiều agent song song sẽ dùng nhiều token hơn một phiên đơn. Bù lại, nhờ context chính gọn hơn, tổng thể vẫn có thể hiệu quả với việc nặng ngữ cảnh.

Chạy được bao nhiêu subagent song song?

Bạn có thể bung nhiều subagent cùng lúc, nhưng nên giới hạn theo nhu cầu thật (thường 3-4 là hợp lý cho một tác vụ kiểm tra). Bung càng nhiều càng tốn token và khó theo dõi.

Subagent có nhớ hội thoại chính không?

Không. Mỗi subagent chạy trong cửa sổ ngữ cảnh cách ly, không thấy lịch sử phiên chính trừ phần agent chính chủ động truyền vào. Đó là điểm mạnh (context sạch) nhưng cũng là giới hạn cần nhớ.

Subagents khác Skills thế nào?

Subagents là AI con chuyên biệt được giao việc và chạy độc lập; Skills là gói hướng dẫn/quy trình nạp thêm cho Claude làm theo. Một cái "làm thay", một cái "dạy cách làm".

Nên đặt agent ở project-level hay user-level?

Đặt project-level (.claude/agents/) cho agent đặc thù dự án và muốn commit cho team dùng chung; đặt user-level (~/.claude/agents/) cho agent bạn muốn dùng ở mọi dự án. Khi trùng tên, project-level thắng.

Có cần Claude Code Pro không?

Subagents là tính năng của Claude Code; bạn dùng nó trong gói bạn đang có. Chi tiết các gói (Pro $20/tháng, Max...) xem thêm bài Claude Code là gì.

Kết luận + bước tiếp theo

Subagents biến Claude Code từ một trợ lý đơn thành một đội nhỏ: chia việc, chạy song song, giữ context sạch. Bắt đầu đơn giản với một code-reviewer read-only, rồi mở rộng dần sang orchestration khi bạn nắm được cả sức mạnh lẫn giới hạn của nó. Đọc tiếp Claude Code Skills là gì để ghép subagents với skills, hoặc bài phân biệt 4 khối để chọn đúng công cụ. Còn nếu muốn khỏi viết từ đầu, thử bộ kit AgentKit (giảm 20% qua link) với thư viện agent dựng sẵn.