Bạn vừa nhờ Claude Code “tìm chỗ nào trong repo gọi API thanh toán”. Năm phút sau, khung chat đầy kết quả grep, tên file, đoạn log — và câu hỏi ban đầu của bạn chìm đâu đó ở giữa. Muốn sửa tiếp một lỗi nhỏ mà phải cuộn qua hàng trăm dòng nhiễu.
Subagent Claude Code sinh ra đúng cho tình huống này: một agent phụ chạy trong context riêng, làm phần việc nhiễu đó rồi trả về duy nhất một bản tóm tắt. Context chính của bạn sạch, subagent ôm hết phần bừa bộn. [1]
Đây là bài thứ chín trong series Claude Code. Bài trước đã nói về skills Claude Code — cách gói quy trình lặp lại. Bài này chỉ cho bạn khi nào nên tạo subagent, viết file agent đúng chuẩn, siết quyền tool cho an toàn, và chọn model để không cháy quota.
Tóm tắt nhanh
- Subagent Claude Code là một agent phụ có context window riêng: nó làm việc độc lập rồi trả về tóm tắt — giúp context chính không bị ngập kết quả tìm kiếm hay log. [1]
- Claude Code có sẵn subagent Explore (tìm hiểu codebase, read-only), Plan (research khi plan mode) và general-purpose cho task nhiều bước.
- Subagent tự tạo là một file Markdown có YAML frontmatter trong
.claude/agents/(project) hoặc~/.claude/agents/(mọi project). [1] - Siết an toàn bằng
tools,disallowedTools,permissionModevàisolation: worktree— không nên cho subagent toàn quyền mặc định. - Kiểm soát chi phí bằng
model: haikucho việc nhẹ; mọi request của subagent đều tính vào cùng quota với phiên chính. [1][5]
Subagent trong Claude Code là gì?
Subagent là một AI assistant chuyên biệt chạy trong context window riêng: nhận một task từ phiên chính, tự thực thi với system prompt và quyền tool riêng, rồi trả về kết quả dạng tóm tắt. Claude tự quyết định có ủy quyền hay không dựa trên trường description bạn viết trong file định nghĩa subagent. [1]
- Context window riêng
- Mỗi subagent có một cửa sổ hội thoại tách biệt. Nó có thể đọc hàng trăm file, chạy hàng chục lệnh — nhưng chỉ phần tóm tắt cuối cùng quay về phiên chính của bạn.
- System prompt riêng
- Subagent chỉ nhận system prompt bạn viết trong file định nghĩa cộng thông tin môi trường cơ bản như thư mục làm việc — nó không thừa hưởng toàn bộ system prompt của Claude Code.
- Delegation (ủy quyền)
- Cơ chế Claude chính giao task cho subagent qua công cụ Agent. Khi yêu cầu của bạn khớp
description, Claude tự giao việc; bạn cũng có thể ép bằng cách nhắc tên subagent.
Bốn lý do chính để dùng subagent Claude Code: giữ context chính sạch, giới hạn tool cho từng loại việc, tái sử dụng cấu hình giữa các project, và route việc nhẹ xuống model rẻ hơn để tiết kiệm chi phí. [1]
Một lưu ý quan trọng về chi phí: subagent gửi request riêng và mọi request đó tính vào cùng hạn mức sử dụng với phiên chính. Nói cách khác, chia việc không có nghĩa là chia bill — phần kiểm soát chi phí ở cuối bài sẽ nói rõ hơn.
Bạn đang đọc bài thuộc chuyên mục Lập trình của VietnamTutor — nơi mình chia sẻ cách dùng AI trong engineering có kiểm soát.
Claude Code có sẵn subagent nào?
Có bốn nhóm: Explore chuyên tìm hiểu codebase ở chế độ read-only, Plan research khi bạn ở plan mode, general-purpose xử lý task nhiều bước cần cả đọc lẫn sửa, và vài helper nhỏ như claude-code-guide trả lời câu hỏi về chính Claude Code. [1]
| Subagent | Tool | Claude dùng khi |
|---|---|---|
Explore | Chỉ đọc: Write và Edit bị cấm | Cần tìm file, hiểu codebase mà không sửa gì |
Plan | Chỉ đọc: Write và Edit bị cấm | Bạn đang ở plan mode, cần research trước khi lên kế hoạch |
general-purpose | Toàn bộ tool dành cho subagent | Task nhiều bước, cần vừa tìm hiểu vừa chỉnh sửa |
claude-code-guide | Tool tối thiểu, chạy model Haiku | Bạn hỏi về tính năng của Claude Code |
Điểm thú vị của subagent Claude Code: bạn gần như không cần gọi các agent này bằng tay. Khi bạn hỏi “file nào định nghĩa model User?”, Claude tự giao cho Explore — và bạn chỉ thấy một dòng Explore(Tìm model User) trong transcript kèm kết quả gọn. Đó là lý do context chính của bạn đỡ bị ngập dù repo vài trăm nghìn dòng.
Nếu không thích hành vi mặc định, bạn có thể ghi đè: tạo một subagent tự đặt tên trùng Explore để thay thế bản built-in, cấm riêng từng subagent bằng permissions.deny với cú pháp Agent(Explore), hoặc chặn toàn bộ ủy quyền bằng cách deny chính tool Agent. [1]
Tạo subagent đầu tiên trong 3 bước
Một subagent Claude Code chỉ là file Markdown có YAML frontmatter đặt trong .claude/agents/ hoặc ~/.claude/agents/ — bạn có thể nhờ Claude viết hộ, hoặc tự viết rồi gọi thử. [1][2]
Bước một, nhờ Claude tạo. Mô tả rõ subagent làm gì, đặt ở đâu, cho dùng tool nào và chạy model nào:
Create a project subagent in .claude/agents/ that reviews code after changes. It should be read-only (Read, Grep, Glob only), use Sonnet, and report issues grouped by severity: security, correctness, style.
Bước hai, kiểm tra file được tạo — ví dụ .claude/agents/code-reviewer.md. Chỉ hai trường bắt buộc là name và description; phần Markdown bên dưới frontmatter chính là system prompt của subagent:
--- name: code-reviewer description: Review code sau mỗi lần thay đổi. Dùng khi cần kiểm tra bảo mật, tính đúng đắn và style trước khi commit. tools: Read, Grep, Glob model: sonnet --- Bạn là reviewer cẩn thận. Với mỗi vấn đề tìm thấy: nêu file và dòng, giải thích rủi ro, đề xuất cách sửa ngắn gọn. Nhóm kết quả theo mức độ: bảo mật, tính đúng đắn, style. Không sửa file — chỉ báo cáo.
Ba điều đáng nhớ ở đây. Một, description là tiêu chí duy nhất Claude dùng để quyết có giao việc cho subagent không — viết kiểu “dùng khi X” càng cụ thể càng tốt, giống cách viết description cho skill. Hai, mẹo từ docs chính thức: thêm cụm “use proactively” vào description nếu muốn Claude chủ động giao việc thay vì đợi bạn nhắc. [1] Ba, tổng description của mọi subagent đều chiếm context lúc khởi động — vượt 15.000 token thì Claude Code cảnh báo, nên giữ description ngắn và đẩy chi tiết xuống phần body.
Bước ba, gọi thử. Bạn có thể nói thẳng “Use the code-reviewer subagent to check my latest changes”, hoặc chỉ cần hỏi “review giúp mình đoạn vừa sửa” và để Claude tự ủy quyền. Trong transcript, lần gọi hiện ra một dòng kiểu code-reviewer(Review thay đổi) — đó là dấu hiệu subagent đang chạy độc lập.
Đặt subagent ở đâu: project, user hay cả tổ chức?
Subagent dùng riêng cho một repo đặt trong .claude/agents/ và commit vào git; subagent dùng chung mọi project đặt trong ~/.claude/agents/; cấp tổ chức thì phát qua managed settings hoặc plugin. Khi hai subagent trùng tên, nơi có độ ưu tiên cao hơn sẽ thắng. [1]
| Vị trí | Phạm vi | Ưu tiên |
|---|---|---|
| Managed settings | Toàn tổ chức | 1 (cao nhất) |
--agents CLI flag | Session hiện tại (truyền JSON khi khởi động) | 2 |
.claude/agents/ | Project hiện tại — commit để team dùng chung | 3 |
~/.claude/agents/ | Mọi project trên máy bạn | 4 |
Plugin agents/ | Nơi plugin được bật | Thấp nhất |
Thư mục agents/ được quét đệ quy, nên bạn có thể chia subfolder kiểu agents/review/ hay agents/research/ cho gọn — danh tính subagent chỉ phụ thuộc trường name, không phụ thuộc đường dẫn. [1]
Hai cạm bẫy nhỏ cần biết. Một, subagent của plugin không hỗ trợ các trường hooks, mcpServers và permissionMode — cần mấy thứ này thì chép file vào .claude/agents/. Hai, MCP server khai báo inline trong agent file của project chỉ được nạp sau khi bạn trust folder chứa file đó — tính năng bảo mật chứ không phải bug.
Chia việc an toàn: siết tool, quyền và môi trường
Đừng để subagent thừa hưởng toàn bộ tool mặc định — khai báo tools cho đúng việc, dùng disallowedTools để cấm thêm, đặt permissionMode khi cần siết quyền, và bật isolation: worktree nếu subagent được quyền sửa code. [1][4]
Nguyên tắc đầu tiên là quyền tối thiểu. Subagent Claude Code cho việc review chỉ cần Read, Grep, Glob; subagent research web chỉ cần thêm WebFetch, WebSearch. Nếu bỏ trống trường tools, subagent thừa hưởng mọi tool dành cho subagent — bao gồm cả Write, Edit và Bash. Một subagent “đọc log phân tích lỗi” không có lý gì phải cầm quyền ghi file.
Nguyên tắc hai là biết trước tool nào subagent không bao giờ có. Claude Code loại AskUserQuestion khỏi mọi subagent — nghĩa là subagent không thể quay lại hỏi bạn giữa chừng, nên prompt giao việc phải đủ thông tin ngay từ đầu. Subagent chạy nền còn bị rút thêm nhiều built-in tool nữa; chỉ giữ bộ tool cốt lõi như đọc file, tìm kiếm, shell và web. [1]
Nguyên tắc ba — và đây là phần “an toàn” trong tiêu đề bài — là cô lập môi trường khi subagent được sửa code:
--- name: refactor-worker description: Refactor một module cụ thể theo hướng dẫn trong prompt. Dùng khi được giao refactor có phạm vi rõ. tools: Read, Grep, Glob, Edit, Bash(npm test *) isolation: worktree maxTurns: 30 --- Bạn refactor đúng phạm vi được giao, chạy test sau khi sửa, và báo cáo danh sách file đã đổi kèm kết quả test.
Ba dòng đáng tiền trong ví dụ này. isolation: worktree cho subagent một bản copy repo trong git worktree tạm — nó sửa thoải mái trên nhánh riêng, không đụng vào working tree đang mở của bạn; nếu không đổi gì thì worktree tự dọn. tools: ...Bash(npm test *) chỉ cho chạy test chứ không mở shell tự do. maxTurns: 30 chặn subagent chạy vòng lặp vô tận — hết lượt thì kết quả trả về kèm cờ “partial” và bạn có thể resume để nó làm tiếp. [1][3]
Còn một lớp nữa nếu bạn muốn chặn từ phía session: thêm subagent vào permissions.deny trong settings, ví dụ "deny": ["Agent(Explore)"], hoặc chạy claude --disallowedTools "Agent(Explore)". Nếu đã là fan của checkpoint trong Claude Code, hãy kết hợp cả hai — checkpoint cho bạn đường lùi, còn siết tool ngay từ đầu giảm hẳn lý do phải lùi. Cơ chế quyền chi tiết hơn nữa nằm ở bài permission mode.
Chọn model và kiểm soát chi phí cho subagent
Mặc định subagent Claude Code chạy cùng model với phiên chính; đặt model: haiku cho việc đơn giản lặp nhiều, sonnet cho việc thường, inherit khi muốn khóa chặt theo model cha — và nhớ rằng request của subagent vẫn tính vào quota của bạn. [1][5]
Thứ tự Claude Code chọn model cho subagent: tham số Claude truyền lúc gọi, rồi trường model trong file, rồi biến môi trường CLAUDE_CODE_SUBAGENT_MODEL nếu bạn set, cuối cùng mới tới model của phiên chính. Muốn ép mọi subagent chạy một model duy nhất — kể cả Explore — set biến môi trường đó trong settings là xong. [1][5]
Quy tắc ngón tay về tiền: Explore và các subagent nghiệp vụ nhẹ như “đếm file”, “tìm pattern” chạy Haiku vẫn rất ổn; review code hay refactor thì để Sonnet; chỉ việc thật khó mới đáng Opus. Đây là một trong những cách thực tế nhất để giảm chi phí phiên làm việc — mình đã phân tích kỹ hơn trong bài về kiểm soát chi phí token với dynamic workflows.
Hai cơ chế nâng cao đáng biết thêm. skills cho nạp sẵn toàn bộ nội dung một skill vào context của subagent lúc khởi động — tiện khi subagent cần quy trình chuẩn, nhưng nhớ là nội dung đầy đủ chứ không chỉ description. memory: user|project|local cấp cho subagent một thư mục nhớ xuyên session, để reviewer nhớ dần pattern của codebase qua nhiều lần chạy. [1]
Khi nào nên tạo subagent — và khi nào không?
Tạo subagent Claude Code khi một loại việc lặp lại và sinh nhiều nhiễu cho context chính, khi cần giới hạn tool cho một vai trò cụ thể, hoặc khi muốn route phần việc nhẹ xuống model rẻ. Đừng tạo cho việc một lần, việc cần hỏi bạn giữa chừng, hay thứ subagent built-in đã lo.
| Nên tạo subagent | Chưa cần |
|---|---|
| Review code, research, phân tích log lặp hằng ngày | Task một lần rồi thôi — cứ giao thẳng general-purpose |
| Việc sinh nhiều output nhiễu: grep cả repo, đọc log dài | Việc một lệnh xong — Claude chính làm nhanh hơn |
| Vai trò cần quyền riêng: read-only auditor, deploy runner | Việc phải hỏi ý kiến bạn giữa chừng — subagent không có AskUserQuestion |
Team cần chung một cách kiểm tra — commit vào .claude/agents/ | Quy trình lặp lại không cần context riêng — đó là việc của skill |
Dòng cuối bảng đáng nói thêm một chút, vì đây là chỗ hay nhầm nhất: skill và subagent khác nhau ở context. Skill nhét hướng dẫn vào phiên chính khi được gọi; subagent chạy hẳn một hội thoại riêng. Muốn “dạy Claude làm đúng quy trình” thì viết skill; muốn “đuổi việc nhiễu sang phòng khác” thì viết subagent. Nhiều team dùng cả hai cùng lúc — và với context: fork, một skill còn có thể tự chạy bên trong một subagent.
Nếu bạn đã quen subagent đơn lẻ và muốn điều phối nhiều subagent cùng lúc, đó là chủ đề của bài dynamic workflows và Agent Teams — từ chia một việc sang điều phối cả một đội.
Nguồn tham khảo
- Claude Code Docs — Create custom subagents
- Claude — How and when to use subagents in Claude Code
- Claude Code Docs — Subagents in the Agent SDK
- DevHunt — Claude Code Subagents: Setup, Frontmatter Reference and Example Agents
- Caprock — Claude Code subagents: how to create them, when Claude uses them, and what they cost
Các câu hỏi thường gặp
Subagent Claude Code khác gì skill?
Skill nạp hướng dẫn vào phiên chính khi được gọi — nó dạy Claude làm theo quy trình. Subagent chạy một hội thoại riêng có context riêng — nó ôm việc nhiễu và chỉ trả tóm tắt về. Dùng skill để chuẩn hóa quy trình, dùng subagent khi cần tách context hoặc giới hạn tool cho một vai trò.
Subagent có tự động chạy hay phải gọi bằng tay?
Cả hai. Claude đọc trường description của mọi subagent lúc khởi động và tự ủy quyền khi yêu cầu của bạn khớp mô tả. Muốn Claude chủ động hơn, thêm “use proactively” vào description. Muốn gọi tay, nói thẳng “Use the [tên] subagent” hoặc nhắc tên subagent trong yêu cầu.
Subagent có đọc được CLAUDE.md của project không?
Có — subagent tự tạo nạp cả CLAUDE.md cấp user, project và local trừ khi bạn đặt omitClaudeMd: true. Hai subagent built-in là Explore và Plan ngoại lệ: chúng khởi động không có CLAUDE.md để giữ research nhanh và rẻ.
Dùng subagent có tốn thêm tiền không?
Subagent gửi request riêng và tính vào cùng hạn mức với phiên chính — chia việc không phải chia bill. Nhưng bạn có thể giảm chi phí bằng cách đặt model: haiku cho subagent việc nhẹ như tìm file hay đọc log, thay vì để mọi thứ chạy model đắt của phiên chính.
Làm sao cấm một subagent không cho Claude dùng?
Thêm tên subagent vào permissions.deny trong settings theo cú pháp Agent(ten-subagent), ví dụ “deny”: [“Agent(Explore)”]. Chặn luôn mọi ủy quyền thì deny chính tool Agent. Với file agent riêng, chỉ cần xóa hoặc đổi tên file trong .claude/agents/.
Subagent có spawn được subagent khác không?
Có — nếu tool Agent nằm trong danh sách tools của subagent Claude Code đó và chưa chạm giới hạn độ sâu, nó spawn được subagent con riêng. Với agent chạy làm main session qua claude –agent, bạn siết thêm bằng cú pháp Agent(worker, researcher) để chỉ cho spawn đúng loại được liệt kê.
Subagent Claude Code biến “một agent làm hết” thành “một đội chia việc có kiểm soát”: mỗi agent phụ một context, một vai trò, một bộ quyền vừa đủ. Mình khuyên bạn bắt đầu với một subagent read-only đơn giản — code-reviewer hay log-analyzer — rồi mới siết dần permission khi đã quen tay. Bạn đang định giao việc gì cho subagent đầu tiên? Kể mình nghe ở comment nhé, và nếu muốn điều phối nhiều subagent cùng lúc thì đón đọc bài về dynamic workflows tiếp theo trong series.
