Subagent của Claude Code: cô lập ngữ cảnh, orchestrator và reviewer, khi nào không cần

Subagent của Claude Code là gì

Subagent là một thể hiện agent khác mà agent chính khởi chạy để làm một tác vụ riêng. Nó có cửa sổ ngữ cảnh riêng, system prompt riêng và danh sách công cụ được phép riêng. Agent chính đưa cho nó mô tả tác vụ, subagent tự làm việc — đọc tệp, chạy lệnh — rồi trả về cho agent chính chỉ một thông điệp kết quả.

Từ khóa ở đây là cô lập. Mọi thứ subagent đọc trên đường đi — hàng chục tệp, đầu ra test dài, các giả thuyết ngõ cụt — đều nằm trong ngữ cảnh của nó và không lọt vào ngữ cảnh của phiên chính. Agent chính chỉ thấy kết quả ngắn gọn: «lỗi nằm ở hàm X, nguyên nhân là thế này, có ba chỗ bị ảnh hưởng».

Subagent của Claude Code là một trường hợp riêng của ý tưởng chung về hệ thống nhiều agent: thay vì một vòng lặp «suy nghĩ — làm — kiểm tra», xuất hiện một đồ thị gồm nhiều nút, mỗi nút có vai trò và trách nhiệm riêng.

Vì sao cần cô lập ngữ cảnh

Cửa sổ ngữ cảnh là tài nguyên chính của agent. Trong đó đồng thời chứa chỉ dẫn từ CLAUDE.md, lịch sử hội thoại, code đã đọc và đầu ra lệnh. Khi agent mất nửa tiếng tìm nguyên nhân một lỗi, ngữ cảnh bị lấp đầy bởi rác: các tệp hóa ra không liên quan và log trong đó chỉ có một dòng quan trọng.

Hệ quả quen thuộc với ai làm việc với agent lâu dài: mô hình bắt đầu giữ quy tắc dự án kém hơn, nhầm lẫn chi tiết, và khi lịch sử được nén tự động thì mất đi những điều quan trọng. Subagent giải quyết điều này ở mức cấu trúc: công việc nặng nhọc được làm trong một ngữ cảnh riêng, và ngữ cảnh đó bị bỏ đi sau khi trả lời.

• Tìm kiếm và khảo sát. «Tìm mọi nơi gọi hàm thanh toán và mô tả cách chúng hoạt động» — tác vụ điển hình để giao cho subagent.
• Kiểm tra nhiều đầu ra. Chạy test và phân tích những test đã hỏng — giao cho subagent, nhận lại danh sách nguyên nhân.
• Đọc tài liệu lớn. Một đặc tả hàng trăm trang chỉ cần vài thông tin — để subagent trích xuất chúng.

Thiết lập subagent: thư mục .claude/agents

Một subagent tùy chỉnh được mô tả bằng tệp Markdown có phần đầu YAML. Tệp của dự án nằm trong .claude/agents/ của repository và cả nhóm dùng được qua git; tệp cá nhân nằm trong ~/.claude/agents/ và hoạt động trong mọi dự án của bạn. Có thể tạo và sửa subagent một cách tương tác bằng lệnh /agents trong Claude Code.

---
name: code-reviewer
description: Kiểm tra thay đổi code về lỗi và vi phạm quy tắc dự án. Dùng sau khi hoàn thành tác vụ, trước khi commit.
tools: Read, Grep, Glob, Bash
---
Bạn là reviewer code. Bạn không cần sửa bất cứ thứ gì.

1. Xem các thay đổi: git diff.
2. Kiểm tra từng thay đổi về lỗi logic, xử lý lỗi,
   bảo mật (SQL, escape đầu ra, bí mật).
3. Đối chiếu với quy tắc trong AGENTS.md.
4. Trả về danh sách nhận xét: tệp, dòng, vấn đề, vì sao quan trọng.
   Nếu không có nhận xét nào — hãy nói rõ như vậy.

Ý nghĩa các trường:

Phần thân tệp là system prompt của subagent. Nó không thấy lịch sử hội thoại của bạn, nên mọi điều nó cần biết về vai trò và định dạng trả lời phải có trong prompt hoặc trong tác vụ mà agent chính giao.

Cách gọi subagent

Agent chính có thể tự chọn subagent nếu tác vụ khớp với description của nó. Đáng tin hơn là yêu cầu rõ ràng: «Dùng subagent code-reviewer để kiểm tra các thay đổi». Các cụm như «dùng chủ động» trong mô tả làm tăng khả năng agent gọi nó mà không cần nhắc, nhưng không đảm bảo điều đó.

Subagent khảo sát

Tệp thứ hai nên có trong hầu hết dự án là subagent khảo sát chỉ đọc. Nó trả lời các câu hỏi về code và không thay đổi gì.

---
name: explorer
description: Tìm trong codebase câu trả lời cho các câu hỏi về việc cái gì nằm ở đâu và hoạt động thế nào. Dùng khi cần đọc nhiều tệp để có kết luận ngắn.
tools: Read, Grep, Glob
---
Bạn khảo sát code và không thay đổi gì.
Trả về: câu trả lời ngắn cho câu hỏi, danh sách tệp kèm dòng
làm căn cứ, và những điều không kiểm chứng được.

Subagent này đặc biệt hữu ích ở đầu tác vụ: agent chính nhận được bản đồ các chỗ cần quan tâm mà không phải tốn ngữ cảnh để đọc toàn bộ, rồi làm việc tiếp với các tệp cụ thể.

Mô hình «orchestrator và worker»

Mô hình nhiều agent phổ biến nhất: một agent orchestrator giữ kế hoạch và bức tranh tổng thể, còn các bước cụ thể được giao cho worker. Orchestrator không tự đọc toàn bộ code — nó đặt tác vụ, nhận kết quả và quyết định bước tiếp theo.

1. Orchestrator chia tác vụ thành các phần độc lập và viết cho mỗi phần một chỉ dẫn tự đủ: mục tiêu, tìm ở đâu, coi là xong khi nào, trả về dưới dạng nào.
2. Worker thực hiện chỉ dẫn trong ngữ cảnh của chúng.
3. Orchestrator thu thập kết quả, kiểm tra các phần có khớp nhau không, rồi chạy bước tiếp theo hoặc quay lại bước trước.

Điểm yếu của mô hình này là việc giao tác vụ. Subagent chỉ biết những gì được viết cho nó. Chỉ dẫn «sửa lỗi mà chúng ta đã bàn» là rỗng với nó: nó không thấy cuộc bàn bạc. Một chỉ dẫn tốt phải đọc như việc giao cho một đồng nghiệp mới, lần đầu mở repository.

Worker cần trả về gì

Hãy định dạng câu trả lời trước: danh sách tệp, đầu ra, nguyên nhân tìm được, những gì chưa kiểm chứng được. Câu trả lời ngắn và có cấu trúc tiết kiệm ngữ cảnh cho orchestrator, còn mục «chưa kiểm chứng» bảo vệ khỏi sự tự tin giả — worker, như mọi agent khác, có xu hướng báo cáo thành công.

Reviewer riêng: vì sao tách giám khảo khỏi người thực thi

Khi cùng một agent vừa viết code vừa tự kiểm tra, giám khảo và bị cáo dùng chung một đầu. Agent nhớ nó định làm gì và thấy trong code ý đồ của mình chứ không phải điều đã được viết. Hơn nữa, nó có động cơ muốn hoàn thành, nên kiểm tra dễ thành hình thức.

Reviewer trong ngữ cảnh riêng tránh được những vấn đề này. Nó không biết lịch sử quyết định, chỉ thấy diff và quy tắc dự án, và đánh giá kết quả với con mắt mới. Đây là nguyên tắc y như trong một nhóm thật: tác giả không tự duyệt pull request của mình.

• Chỉ cấp cho reviewer công cụ đọc và chạy kiểm tra — không có quyền sửa tệp. Khi đó nó sẽ không «lặng lẽ sửa» thay vì báo cáo vấn đề.
• Nêu rõ tiêu chí kiểm tra: thế nào là lỗi, quy tắc dự án nào là bắt buộc.
• Quyết định xử lý nhận xét để lại cho orchestrator hoặc con người. Reviewer tìm ra vấn đề, worker sửa.

Reviewer không thay thế các kiểm tra máy móc. Test, linter và kiểm tra kiểu là các nút tất định, đáng tin hơn mọi mô hình. Reviewer bắt những điều cơ chế không thấy: logic sai, vi phạm thỏa thuận, độ phức tạp thừa.

Chạy song song subagent

Claude Code có thể chạy nhiều subagent cùng lúc. Điều này tăng tốc công việc khi các phần của tác vụ thật sự độc lập: nghiên cứu ba module, kiểm tra thay đổi từ ba góc độ (bảo mật, hiệu năng, test), thu thập thông tin từ nhiều nguồn.

Song song hoạt động tốt với đọc và kém với ghi. Nếu hai worker cùng lúc sửa cùng một tệp, chúng ghi đè thay đổi của nhau và không ai biết điều đó. Trong thuật ngữ đồ thị agent, đây là trạng thái chung không có quy tắc hợp nhất. Các quy tắc thực tế:

• Song song cho khảo sát, phân tích, review. Tuần tự cho các thay đổi trên những tệp trùng nhau.
• Nếu worker vẫn ghi song song, hãy chia vùng: mỗi worker chỉ làm trong tệp của mình hoặc trong bản sao repository riêng (ví dụ một git worktree riêng).
• Tổng hợp kết quả là việc của một nút — orchestrator — chứ không phải của các worker với nhau.

Khi nào không cần subagent

Mô hình nhiều agent có giá của nó: nhiều token hơn, nhiều thời gian hơn, nhiều chỗ thông tin bị mất khi chuyển giao. Subagent của Claude Code không phải lúc nào cũng đáng giá.

Trước khi xây đồ thị từ nhiều agent, hãy trả lời vài câu hỏi đơn giản: ai sở hữu mục tiêu chung, ai có quyền phủ quyết và hoàn tác thay đổi, những chỉ số nào được coi là thành công. Nếu không có câu trả lời, nhiều agent chỉ nhân đôi sự rối rắm.

Lỗi thường gặp với subagent

Mô tả mơ hồ

Mô tả «trợ lý cho code» không giúp agent chính chọn lúc nào nên gọi nó. Hãy viết điều kiện kích hoạt: «sau thay đổi trong thư mục api/, trước khi commit».

Chỉ dẫn thiếu ngữ cảnh

Subagent nhận tác vụ không có đường dẫn, không có tiêu chí hoàn thành và không có ràng buộc — và nó dành nửa công việc để đoán điều bạn muốn. Cách khắc phục là một khuôn mẫu chỉ dẫn: mục tiêu, dữ liệu đầu vào, ràng buộc, định dạng trả lời.

Quyền quá rộng

Subagent khảo sát và reviewer không cần quyền sửa tệp. Giới hạn tools là cách rẻ để biến vai trò thành cơ chế, chứ không chỉ là một yêu cầu trong prompt.

Tin báo cáo mà không kiểm tra

«Tất cả test đều chạy qua» trong câu trả lời của subagent là một khẳng định, không phải sự thật. Orchestrator phải dựa vào thứ kiểm chứng được: đầu ra lệnh, mã trả về, các dòng code cụ thể.

Tóm lại

Subagent của Claude Code là công cụ cho ba việc: giữ ngữ cảnh chính sạch, tách kiểm tra khỏi thực thi và chia nhỏ công việc độc lập để làm song song. Chúng được mô tả bằng các tệp Markdown ngắn trong .claude/agents/, và chất lượng làm việc của chúng gần như hoàn toàn phụ thuộc vào mô tả vai trò, bộ công cụ và mức độ tự đủ của chỉ dẫn. Khi tác vụ nhỏ hoặc gắn chặt với hội thoại, một agent vẫn tốt hơn. Việc chuyển từ một vòng lặp sang hệ thống gồm các nút, cạnh và trạng thái chung được giải thích và thực hành chi tiết trong khóa học.