Introduction to Subagents

#Subagent là gì

Subagent là trợ lý chuyên biệt mà Claude Code có thể delegate (ủy thác) tác vụ cho. Hình dung nó như một người giúp việc chuyên trách: nhận việc, chạy trong context window (cửa sổ ngữ cảnh) riêng của mình, làm xong thì trả về main thread một bản tóm tắt.

Điểm mấu chốt: mọi intermediate step (bước trung gian) — đọc file, search, tool call — ở lại trong context của subagent, không bao giờ làm bẩn hội thoại chính.

#Vì sao subagent quan trọng

Mỗi lần trò chuyện với Claude Code là mỗi lần cộng thêm vào main context window. Mọi tool call, mọi lần đọc file, mọi kết quả search đều được lưu ở đó. Không gian ấy hữu hạn — đầy rồi thì Claude bắt đầu mất dấu những phần trước của cuộc hội thoại.

Subagent giải quyết bằng cách mở một context window tách biệt. Subagent nhận đúng hai thứ:

• Custom system prompt — từ file cấu hình, định nghĩa vai trò và hành vi của subagent.
• Task description — do parent agent viết, dựa trên yêu cầu của người dùng.

Sau đó subagent tự làm việc: đọc file, chạy search, sửa code — bất cứ gì nó cần. Xong việc, chỉ summary quay về main conversation; toàn bộ hội thoại của subagent bị discard.

Nghĩa là main context giữ được sạch: có câu trả lời mà không có tiếng ồn của hành trình đi tìm nó. Tradeoff (đánh đổi): mất visibility — không thấy subagent đã lập luận thế nào để tới kết luận.

#Ví dụ thực tế

Giả sử đang khám phá một codebase lạ và muốn biết service nào xử lý refund.

#Tạo subagent bằng /agents

Cách dễ nhất là slash command /agents — giao diện quản lý subagent — rồi chọn Create new agent. Claude Code hỏi lần lượt:

1. Scope (phạm vi):

• Project-level — chỉ dùng được trong project hiện tại.
• User-level — dùng chung cho mọi project trên máy.

2. Creation method (cách tạo):

• Generate with Claude (khuyến nghị) — mô tả điều muốn subagent làm, Claude sinh ra name, description và system prompt.
• Manual configuration — tự viết config.

3. Tools — chọn nhóm tool subagent được truy cập: Read-only tools · Edit tools · Execution tools · MCP tools · Other tools.

Hãy cân nhắc subagent thực sự cần gì. Một code reviewer hầu như không cần edit tools — nó nên đọc và phân tích code, không sửa. Nhưng nên giữ execution tools để nó dễ nhận diện pending changes (thay đổi đang chờ).

4. Model — chọn mô hình chạy subagent:

5. Color — màu hiển thị trên UI để biết ngay subagent nào đang hoạt động. Chi tiết nhỏ, nhưng hữu ích khi chạy nhiều subagent.

#File config

Tạo xong, config được lưu vào project — thường ở .claude/agents/<tên-agent>.md:

---
name: code-quality-reviewer
description: Use this agent when you need to review recently written or modified code for quality, security, and best practice compliance.
tools: Bash, Glob, Grep, Read, WebFetch, WebSearch
model: sonnet
color: purple
---

You are an expert code reviewer specializing in quality assurance, security best practices, and
adherence to project standards. Your role is to thoroughly examine recently written or modified code
and identify issues that could impact reliability, security, maintainability, or performance.

Từng field:

• name — định danh duy nhất. Dùng để gọi subagent: hỏi Claude trực tiếp, hoặc gõ @agent code-quality-reviewer trong tin nhắn.
• description — điều khiển khi nào Claude quyết định dùng subagent. Bắt buộc một dòng (cần ngắt dòng thì dùng escape \n). Có thể đưa ví dụ hội thoại vào đây để Claude hiểu lúc nào nên delegate.
• tools — danh sách tool subagent được truy cập; khớp với lựa chọn lúc tạo, nhưng sửa lại được bất cứ lúc nào.
• model — sonnet · opus · haiku · inherit.
• color — màu nhận diện trên UI.

#Delegate tự động & test

Muốn Claude tự giao việc cho subagent mà không cần yêu cầu tường minh: đưa từ "proactively" vào field description.

description: Proactively suggest running this agent after major code changes...

Cũng nên thêm ví dụ hội thoại vào description — ví dụ càng cụ thể, Claude càng biết đúng lúc nào nên delegate.

Tạo xong thì test: sửa vài chỗ trong code rồi nhờ Claude review. Nếu subagent không được gọi như mong đợi → quay lại kiểm tra description, thêm ví dụ và trigger scenario cụ thể hơn.

#Config của subagent được dùng ra sao

Đây là cơ chế nền cần nắm trước khi tối ưu. Mỗi khi gửi tin nhắn cho main context window agent, name và description của MỌI subagent khả dụng đều được đưa vào system prompt của main agent. Đó chính là cách main agent quyết định launch subagent nào, khi nào. Muốn kiểm soát tốt hơn việc subagent có được trigger tự động hay không → chỉnh name + description.

description còn có vai trò thứ hai: khi main agent launch subagent, nó phải tự viết một input prompt để khởi động task — và nó dùng description làm kim chỉ nam để viết prompt đó. Nên description không chỉ quyết định khi nào subagent chạy, mà còn định hình subagent được bảo làm gì.

#Pattern 1 — Description định hình input prompt

Lấy code review subagent làm ví dụ. Với description chung chung, main agent có thể viết input prompt kiểu:

"use get diff to find the current changes"

Mơ hồ — subagent phải tự đoán file nào đáng quan tâm.

Sửa description, thêm vào:

"You must tell the agent precisely which files you want it to review"

Giờ main agent sẽ viết input prompt cụ thể hơn hẳn, liệt kê đúng các file cần review.

Kỹ thuật này dùng chéo được cho mọi loại subagent. Ví dụ: thêm "return sources that can be cited" vào description của một web search subagent → main agent tự đưa chỉ thị đó vào khi delegate.

#Pattern 2 — Định nghĩa output format

Đây là cải thiện quan trọng nhất có thể làm cho một subagent, và nó nằm trong system prompt. Nó làm hai việc:

• Tạo stopping point tự nhiên — subagent biết mình xong khi đã điền đủ mọi section của format.
• Ngăn subagent chạy quá dài — không có output định sẵn, subagent vật lộn để quyết định bao nhiêu research là đủ và thường chạy lâu hơn cần thiết.

Ví dụ output format có cấu trúc cho code review subagent:

Provide your review in a structured format:

1. Summary: Brief overview of what you reviewed and overall assessment
2. Critical Issues: Any security vulnerabilities, data integrity risks,
   or logic errors that must be fixed immediately
3. Major Issues: Quality problems, architecture misalignment, or
   significant performance concerns
4. Minor Issues: Style inconsistencies, documentation gaps, or
   minor optimizations
5. Recommendations: Suggestions for improvement, refactoring
   opportunities, or best practices to apply
6. Approval Status: Clear statement of whether the code is ready
   to merge/deploy or requires changes

Format này cho subagent một checklist rõ ràng để đi qua. Điền xong mọi section = biết được phép dừng.

#Pattern 3 — Báo cáo obstacle

Khi subagent phát hiện một workaround trong lúc làm việc — giải quyết một vấn đề dependency, hay phát hiện một lệnh cần flag đặc biệt — chi tiết đó phải xuất hiện trong summary nó trả về. Không thì main thread phải tự khám phá lại chính những giải pháp đó, tốn thời gian và token.

Những thứ nên được bắt báo cáo:

• Setup issue hoặc environment quirk (điểm dị của môi trường)
• Workaround phát hiện trong lúc làm task
• Lệnh cần flag hoặc cấu hình đặc biệt
• Dependency hoặc import gây trục trặc

Cách lấy thông tin này: yêu cầu tường minh trong output format. Thêm một section "Obstacles Encountered" vào template là nó được surface một cách đáng tin cậy.

7. Obstacles Encountered: Report any obstacles encountered during the
   review process. This can be: setup issues, workarounds discovered or
   environment quirks. Report commands that needed a special flag or
   configuration. Report dependencies or imports that caused problems.

#Pattern 4 — Giới hạn tool access

Không phải subagent nào cũng cần mọi tool. Hãy nghĩ xem subagent thực sự cần làm gì, rồi chỉ cấp tool cần cho việc đó. Việc này được hai điều: tránh side effect ngoài ý muốn, và làm rõ vai trò của từng subagent khi có nhiều subagent.

#Bốn đặc điểm của subagent hiệu quả

1. Description cụ thể — description điều khiển khi nào subagent được launch và nó nhận chỉ thị gì. Viết để lái cả hai.
2. Structured output — định nghĩa output format trong system prompt để subagent biết khi nào xong và trả về thông tin main thread dùng được.
3. Obstacle reporting — chừa một section cho workaround, quirk và vấn đề, để main thread khỏi khám phá lại.
4. Limited tool access — chỉ cấp tool thực sự cần: read-only cho research, Bash cho reviewer, Edit/Write chỉ cho subagent có nhiệm vụ đổi code.

Mỗi pattern tách ra thì đơn giản, nhưng gộp lại biến subagent từ thứ "cố gắng giúp một cách mơ hồ" thành một worker tập trung, dự đoán được, xong đúng hạn và báo cáo rõ ràng.

#Khi nào subagent toả sáng

Khác biệt nằm ở đúng một thứ: phần việc trung gian có quan trọng với main thread không.

Subagent chạy tốt nhất khi exploration tách rời được khỏi execution. Nếu mỗi bước trong task phụ thuộc vào phát hiện của bước trước → muốn việc đó ở main thread. Còn nếu chỉ cần một câu trả lời và không quan tâm hành trình → delegate.

Subagent xuất sắc ở các task mà:

• Cần một kết quả, không cần tường thuật từng nước đi.
• Phần việc thăm dò sẽ làm bẩn context của main thread.
• Task hưởng lợi từ góc nhìn tươi mới hoặc một custom system prompt.

#Research

Use case kinh điển. Ví dụ: điều tra cơ chế authentication trong một codebase lạ. Main thread cần biết JWT được validate ở đâu, chứ không cần thấy từng file đã search dọc đường.

Research subagent có thể đọc hàng chục file, trace qua các function call, khám phá nhiều code path — toàn bộ ở lại context của nó. Main thread nhận một summary sạch:

JWT validation happens in middleware/auth.js line 42,
called from the Express router in route/api.js

Subagent gánh phần nặng; main thread nhận đúng thứ cần để đi tiếp.

#Code review

Claude review code hiệu quả hơn khi code được trình bày như do người khác viết. Nếu xây một feature qua nhiều lượt với main thread rồi nhờ chính thread đó review, phản hồi thường yếu — Claude đã tham gia tạo ra nó nên khó nhìn bằng con mắt tươi mới.

Reviewer subagent thấy thay đổi trong context riêng: chạy git diff, đọc file đã sửa, áp tiêu chí review chuyên biệt — không mang theo lịch sử code được viết ra sao. Tách như vậy còn cho phép mã hoá chuẩn review riêng của project vào system prompt của subagent → tiêu chí review nhất quán cho cả team.

#Custom system prompt

System prompt mặc định của Claude Code nhấn mạnh phản hồi cô đọng, tập trung vào code. Tuyệt cho lập trình, nhưng không hợp mọi việc. Hai trường hợp custom system prompt làm subagent thực sự hơn hẳn main thread:

• Copywriting subagent — cho nó chỉ dẫn về tone, audience và style. Default prompt của Claude Code thiên về văn kỹ thuật cô đọng — không phải thứ cần cho landing page hay email campaign. Copywriting subagent mang chỉ dẫn hoàn toàn khác về voice và cấu trúc.
• Styling subagent — trỏ nó vào các file design system. Khi subagent chạy, những file đó tự nạp vào context của nó, nên nó biết color variable, quy ước spacing và component pattern trước cả khi bắt đầu viết CSS.

#Khi nào subagent gây hại

Chi phí của việc launch subagent — mất visibility vào việc nó làm và nén phát hiện thành summary — chỉ đáng trả khi subagent làm được điều main thread không làm được. Ba anti-pattern cần tránh:

#Expert claims

Subagent tự nhận chuyên gia hiếm khi giúp ích. Prompt kiểu "you are a Python expert" hay "you are a Kubernetes specialist" không thêm giá trị — Claude đã có sẵn kiến thức đó. Không có gì một "expert subagent" làm được mà main thread không làm trực tiếp được.

#Sequential pipelines

Pipeline subagent tuần tự sinh vấn đề. Ví dụ chuỗi ba agent: một để reproduce bug, một để debug, một để fix. Pipeline chỉ chạy được khi các task thực sự độc lập. Nó thất bại khi mỗi bước phụ thuộc vào phát hiện của bước trước — mà sửa bug thì gần như luôn như vậy. Thông tin bị mất ở khâu handoff (bàn giao) giữa các agent.

#Test runners

Test runner subagent hay giấu mất thông tin cần. Khi test fail, ta cần output đầy đủ để chẩn đoán. Một subagent chỉ trả về "tests failed" buộc ta phải viết thêm debug script để lấy lại chi tiết lẽ ra đã hiện ngay trong output trực tiếp. Thử nghiệm cho thấy test runner pattern cho kết quả tệ nhất trong tất cả cấu hình.

#Quy tắc quyết định

Khi phân vân có nên dùng subagent, hỏi đúng một câu: phần việc trung gian có quan trọng không?

• Không — chỉ cần kết quả cuối → delegate.
• Có — cần thấy và phản ứng theo những gì đang diễn ra dọc đường → giữ ở main thread.

#Áp dụng thực tế

Ở góc Delivery Manager, tôi đọc subagent như mô hình ủy thác trong team. Khi giao một dev đi điều tra "service nào xử lý refund", tôi không cần biết bạn ấy mở 15 file nào — tôi cần một câu trả lời và giữ đầu mình trống cho phần việc điều phối. Chi phí cũng giống hệt: giao xong thì mất khả năng kiểm chứng đường đi. Nên với việc tìm kiếm/khảo sát (kết luận dễ verify lại) tôi ủy thác thoải mái; với việc mà cách làm quan trọng ngang kết quả thì tôi giữ trong main thread để nhìn từng bước.

Viết config subagent thì đúng bằng viết JD cho một vị trí: description là phần "khi nào gọi người này vào" — thứ người phân việc đọc; system prompt mới là bản mô tả công việc — thứ người làm đọc. Đây cũng là lý do khi subagent không bao giờ được gọi, chỗ hỏng nằm ở description chứ không phải ở system prompt. Còn tools là cấp quyền theo vai trò: reviewer bị cắt edit tools nhưng vẫn giữ execution tools để nhìn được pending changes — cắt đúng chỗ, không cắt cho đủ chỉ tiêu an toàn.

Cả bốn anti-pattern/use case ở bài cuối quy về một câu tôi thấy đáng nhớ hơn cả decision rule: subagent là một cơ chế nén thông tin — chỉ delegate khi phần bị nén là rác. Research: 15 file đọc dọc đường là rác, nén thoải mái. Test runner: stack trace lúc test fail chính là thứ quý nhất, nén nó thành "tests failed" là nén nhầm chỗ — nên nó tệ nhất trong mọi cấu hình là hợp lý. Pipeline reproduce → debug → fix: cái bước sau cần là chi tiết thô của bước trước, mà giữa hai agent chỉ còn summary.

Riêng lý do tách reviewer thì đáng ngẫm với người làm review thật: nó không phải chuyện context sạch, mà là chuyện mắt tươi. Tự review PR của chính mình sau ba ngày viết thì ta không đọc code — ta đọc lại ý định của mình. Reviewer subagent thoát được bẫy đó vì nó không mang theo lịch sử feature này ra đời thế nào. Và chỗ này mới là đòn bẩy team: chuẩn review của project mã hoá vào system prompt thì mọi người review bằng cùng một bộ tiêu chí, thay vì tuỳ tâm trạng người review hôm đó.

Ba pattern còn lại thì đúng nghề quản lý delivery đến mức không cần dịch. description nằm trong system prompt của main agent, nghĩa là sửa nó là sửa tờ giấy mà người phân việc đang cầm — không phải huấn luyện lại người làm; đó là lý do một câu như "phải nói rõ chính xác file nào cần review" lại đổi được chất lượng đầu vào của subagent. Output format thì đúng bằng đưa template báo cáo thay vì bảo "viết báo cáo đi": không có tiêu chí xong thì không ai biết lúc nào dừng, và với subagent cái giá của việc không biết dừng trả bằng token. Còn "Obstacles Encountered" là chỗ tôi thấy đắt nhất: context của subagent bị discard, nên mọi thứ nó học được dọc đường sẽ bốc hơi trừ khi ta bắt viết vào summary — không có section đó, main thread giẫm lại đúng ổ gà cũ và trả tiền lần nữa.

#Từ khoá cần thuộc

🔴 Core: subagent · context window · delegate · summary · custom system prompt · task description · parent agent · main thread · /agents · description (quyết định khi nào delegate + định hình input prompt) · .claude/agents/<name>.md · proactively · output format · input prompt · limited tool access · decision rule: "does the intermediate work matter?" · expert claims · sequential pipelines · test runners

🟡 Important: General purpose subagent · Explore subagent · Plan subagent · plan mode · custom subagent · tool access · intermediate steps · discarded · YAML frontmatter · name · tools · model · color · project-level vs user-level · inherit · Generate with Claude vs Manual configuration · stopping points · Obstacles Encountered · structured output · Glob / Grep / Read · Bash · Edit / Write · git diff · exploration vs execution · fresh eyes · copywriting subagent · styling subagent · design system files · handoff · anti-pattern

🟢 Good-to-know: visibility tradeoff · configuration file · code reviewer / test writer / documentation generator · @agent <name> · Read-only / Edit / Execution / MCP / Other tools · pending changes · trigger scenarios · environment quirks · workarounds · Approval Status · Critical / Major / Minor Issues · side effects

Nguồn: Introduction to Subagents (Anthropic Academy) — Copyright Anthropic. Phần đề thi thử cho khoá này nằm ở tab "Đề thi thử".