Subagent như một cửa sổ chú ý riêng biệt

1. Subagent là gì và tại sao chúng ta cần nó

Subagent là một trợ lý chuyên biệt mà Claude Code giao nhiệm vụ cho: nó làm việc trong cửa sổ ngữ cảnh của riêng mình và gửi về phiên của bạn một bản tóm tắt ngắn. Các lần đọc tệp, tìm kiếm và gọi công cụ đều nằm lại trong ngữ cảnh của nó.

Vì sao lại cần vậy: khi làm việc trong phiên chính, tin nhắn, các tệp đã đọc và kết quả lệnh đều chiếm chỗ trong cùng một cửa sổ, mà dung lượng của nó thì có hạn. Khi cửa sổ đầy dần, Claude Code rút gọn lịch sử, và một phần chi tiết có thể bị mất. Subagent cho phép bạn đưa phần việc trung gian sang một cửa sổ riêng, còn trong cuộc trò chuyện chính chỉ giữ lại kết quả của nó.

Subagent đơn giản nhất

Để chạy lần đầu, chỉ cần một tin nhắn bình thường trong Claude Code: hãy yêu cầu rõ ràng việc gọi subagent và mô tả nhiệm vụ của nó. Không cần tạo trước tệp vai trò của riêng bạn, với việc như thế này trợ lý có sẵn là đủ dùng. Ví dụ:

Gọi subagent để đọc tệp index.html.
Để subagent lập một bản đồ ngắn của tệp: các phần chính
và mỗi phần làm gì. Sau đó viết bản tóm tắt ngắn
nội dung trong 3-5 câu.
Không thay đổi tệp. Trả lại câu trả lời của subagent vào phiên này.

Tác nhân chính sẽ chuyển nhiệm vụ cho trợ lý, và khi trợ lý làm xong, sẽ hiển thị câu trả lời của nó trong cuộc trò chuyện của bạn. Khi chạy nền, ở phía dưới, dưới trường nhập liệu, sẽ xuất hiện một thanh có tên của subagent và trạng thái công việc của nó. Nhấp vào nó để mở phiên subagent và xem những gì nó đang đọc và làm. Trong lúc chạy, hãy kiểm tra xem đã có một lần chạy subagent riêng hay chưa: yêu cầu bằng lời thường chỉ định hướng lựa chọn của Claude, tự nó không đảm bảo việc ủy thác sẽ xảy ra.

Subagent nhận được gì

Nếu bạn cần lặp lại cùng một nhiệm vụ với các quy tắc cố định, bạn có thể mô tả vai trò riêng của mình trong một tệp. Khi bắt đầu, một subagent do người dùng tùy chỉnh như vậy có hai đầu vào, không gì hơn:

• hướng dẫn vai trò từ tệp cấu hình của bạn - chuyên môn và quy tắc hành vi;
• mô tả nhiệm vụ, mà tác nhân chính soạn dựa trên yêu cầu của bạn.

Trên sơ đồ chỉ có một điều quan trọng: subagent thực hiện nhiệm vụ trong cửa sổ của nó và trả bản tóm tắt về cuộc trò chuyện chính. Tác nhân chính không phải nạp mọi lần đọc và tìm kiếm trung gian. Tuy vậy, bản thân bản tóm tắt cũng chiếm chỗ trong ngữ cảnh chính.

Cách chia này có mặt trái: bản tóm tắt không cho thấy toàn bộ con đường dẫn tới kết luận. Nhìn vào nó, bạn có thể không nhận ra trợ lý đã thiếu dữ liệu gì hoặc bỏ sót chưa kiểm tra điều gì. Vì vậy câu trả lời cần có căn cứ và giới hạn, còn kết luận của trợ lý thì nên kiểm tra lại.

Tại sao Claude không nhớ tất cả

Cửa sổ ngữ cảnh - những thông tin mà mô hình có trong tay khi chuẩn bị câu trả lời tiếp theo: hướng dẫn, phần lịch sử trò chuyện còn truy cập được, mã đã đọc, kết quả lệnh. Chính nhờ vậy mà tác nhân có thể dựa vào quyết định bạn đã bàn từ vài tin nhắn trước. Cửa sổ có giới hạn; nó không lưu mãi toàn bộ cuộc trò chuyện với đầy đủ chi tiết.

Trong ảnh chụp, lệnh /context hiển thị 4k/200k tokens (2%): đã dùng khoảng 4 nghìn trong số 200 nghìn token khả dụng. Token là một đoạn nhỏ của văn bản: một từ, một phần của từ hoặc một ký hiệu. Do đó, 200 nghìn token không bằng 200 nghìn từ. Đây là kích thước cửa sổ của phiên được hiển thị; nó có thể khác nhau với mô hình hoặc cấu hình khác.

Dưới đây bạn có thể thấy những gì chiếm chỗ: System prompt - hướng dẫn hệ thống, Memory files - tệp bộ nhớ và quy tắc được tải, Skills - thông tin về các skill, Messages - tin nhắn. Ở đây gần như chưa có trao đổi nào, nhưng một phần cửa sổ đã bị hướng dẫn chiếm. Dòng Free space: 196k (98.0%) cho thấy chỗ trống còn lại. Chỗ trống này hao dần khi bạn trò chuyện, đọc tệp và chạy lệnh.

Tiếp theo, chúng ta sẽ xem cơ chế này qua một reviewer tự tạo để đọc mã: nó nhận được thông tin gì và cách tạo tệp vai trò cho nó. Ở đây ta nói về một lần chạy mới bình thường; các cách tiếp tục công việc cũ hay chuyển bản sao lịch sử không cần đến trong ví dụ này.

2. Reviewer biết gì về dự án

Ngữ cảnh riêng không có nghĩa là trợ lý không biết gì. Nó có hướng dẫn ban đầu và quyền truy cập dự án. Đây là những nguồn thông tin của reviewer tự tạo trong ví dụ của chúng ta:

CLAUDE.md - tệp chứa hướng dẫn chung cho Claude Code: ví dụ, mã nguồn nằm ở đâu và dự án theo những quy ước nào. Không cần tạo riêng tệp này chỉ để phục vụ lần kiểm tra này.

Lịch sử cuộc trò chuyện của bạn không được chuyển tự động. Nếu tác nhân chính đã đọc app.js, nội dung của lần đọc đó sẽ không tự xuất hiện ở reviewer. Nhưng tệp thì vẫn còn đó: trợ lý có thể mở lại.

Với các quyết định trong cuộc trò chuyện cũng vậy. Giả sử bạn đã bàn rằng hai tên giống nhau trong danh sách vẫn phải là hai món hàng riêng. Với việc kiểm tra thao tác xóa, đây là yêu cầu quan trọng. Nó sẽ đến được reviewer nếu tác nhân chính đưa nó vào nhiệm vụ hoặc trợ lý đọc tài liệu có ghi nó.

3. Tạo tệp vai trò

Ta sẽ đặt vai trò vào .claude/agents/reviewer.md bên trong dự án. Thư mục người dùng ~/.claude/agents/ cũng có thể chứa các vai trò dùng chung cho nhiều dự án; ký hiệu ~ là thư mục home của người dùng. Lúc này bản trong dự án là đủ.

Bạn có thể nhờ Claude Code tạo tệp:

Tạo .claude/agents/reviewer.md để kiểm tra mã trang
mà không sửa gì. Chỉ cho phép Read, Grep, Glob.
Reviewer trả về các phát hiện có căn cứ, phạm vi đã kiểm tra
và các giới hạn; không có phát hiện nào cũng được chấp nhận.
Cho xem tệp đã tạo.

Kết quả phải là một tệp văn bản bình thường. Không có phép màu nào cả. Dưới đây là phiên bản làm sẵn: bạn có thể đối chiếu câu trả lời của tác nhân với nó hoặc tự lưu nó. Nếu bạn đã có vai trò trùng tên, hãy xem nội dung của nó trước để không ghi đè mất hướng dẫn cần thiết.

---
name: reviewer
description: Kiểm tra mã của trang đã làm xong để tìm lỗi hành vi và trả về báo cáo có căn cứ. Dùng khi được yêu cầu review trang mà không sửa.
tools: Read, Grep, Glob
---
Đọc kỹ mã của các tệp được chỉ định theo các yêu cầu đã cho.
Không thay đổi tệp. Đừng hứa chạy trang: bạn chỉ có quyền đọc và tìm kiếm.
Với mỗi phát hiện, hãy nêu vị trí, hành vi mong đợi, căn cứ của kết luận,
điều kiện kiểm tra và mức ảnh hưởng. Nếu thiếu dữ liệu, hãy ghi rõ điều đó.
Liệt kê riêng những gì đã kiểm tra và những gì chưa kiểm tra.
Nếu không tìm thấy vấn đề theo các tiêu chí đã cho, hãy nói thẳng như vậy.

Khối giữa hai dòng --- được gọi là frontmatter: phần thiết lập ở đầu tệp Markdown. Ở đây name đặt tên vai trò, description giải thích cho tác nhân chính khi nào chọn nó, và tools liệt kê các công cụ có sẵn. Bên dưới là các hướng dẫn bằng lời bình thường.

Ba công cụ trong ví dụ làm đúng những gì cần để xem mã: Read đọc tệp, Grep tìm kiếm theo nội dung, Glob tìm tệp theo tên hoặc đường dẫn. Vì vậy reviewer sẽ tìm được hàm xóa và đọc nó, nhưng sẽ không chạy trang trong trình duyệt hoặc thực thi lệnh trong terminal.

Dòng "không thay đổi tệp" mô tả nhiệm vụ. Trường tools giới hạn phương tiện để thực hiện nó. Nếu chỉ để lời dặn trong văn bản mà không giới hạn công cụ, trợ lý vẫn có thể còn quyền ghi. Trong ví dụ làm sẵn, cả hai phần đều đã có, không cần thêm giới hạn về sau.

Tệp vai trò trông giống skill: phần thiết lập và văn bản hướng dẫn. Rất dễ nhầm. Nhưng ở đây ta đang thiết lập một lần chạy riêng để kiểm tra. Skill thường thêm một quy trình lặp lại được vào cuộc trò chuyện hiện tại, dù skill cũng có thể chạy trong ngữ cảnh riêng. Hãy chọn theo cách công việc cần được thực hiện, chứ không theo việc hai tệp trông giống nhau.

4. Kiểm tra và gọi reviewer

Tệp nằm trên đĩa là kết quả đầu tiên. Giờ hãy kiểm tra xem phiên có nhìn thấy nó không. Mở tệp và xem tên reviewer, mô tả, dòng công cụ và phần văn bản: trong đó có lời hứa chạy trình duyệt hay sửa lỗi ngay không.

Trong ô nhập của Claude Code, gõ @ và chọn reviewer có nhãn agent. Cần đúng vai trò, chứ không phải mục trông giống nhưng có đường dẫn tệp. Chọn từ danh sách giúp bạn chỉ định rõ trợ lý cho nhiệm vụ này.

Nếu không thấy vai trò, trước tiên hãy kiểm tra đường dẫn: tệp phải nằm trong .claude/agents/ của dự án đang mở. Sau đó đến frontmatter: đủ cả hai dòng phân cách, tên và mô tả. Bạn cũng có thể nhờ Claude Code kiểm tra chính tệp định nghĩa.

Theo tài liệu Claude Code, thay đổi trong một thư mục đang được theo dõi sẽ được nhận trong vài giây. Nếu thư mục agents mới xuất hiện lần đầu sau khi phiên đã bắt đầu, cần khởi động lại. Hãy kết thúc phiên hiện tại, rồi trong terminal bình thường, từ chính thư mục dự án đó, chạy:

claude --continue

Lệnh này tiếp tục cuộc trò chuyện gần nhất trong thư mục hiện tại. Sau khi khởi động, hãy kiểm tra lại danh sách @. Lệnh khởi động Claude được gõ trong terminal sau khi đã thoát, không phải bên trong cuộc trò chuyện đang chạy.

Với nhiệm vụ đầu tiên, ta lấy trang danh sách mua sắm: markup trong index.html, logic trong app.js, cả hai tệp nằm ở gốc dự án. Trong dự án của bạn, hãy thay đường dẫn và hành vi mong đợi bằng của mình. Sau khi chọn reviewer từ danh sách, hãy viết thêm đoạn sau vào sau lượt nhắc tên:

Đọc kỹ index.html và app.js ở gốc dự án.
Kiểm tra việc thêm và xóa mục: bộ đếm phải khớp
với số mục còn lại, xóa một mục không được
xóa luôn mục khác trùng tên.
Không thay đổi tệp. Trả về kết luận về mã và những gì cần kiểm tra trong trình duyệt.

Ở đây đã có đủ mọi thứ cho một lần kiểm tra hẹp: tìm ở đâu, điều gì phải xảy ra và cần kết quả gì. Không cần một bản brief riêng thành tệp. Tác nhân chính sẽ soạn nhiệm vụ cho reviewer đã chọn; việc chọn qua @ quyết định ai thực hiện, chứ không có nghĩa tin nhắn của bạn được chuyển nguyên văn.

5. Kết quả trả về ra sao

Sau khi gửi yêu cầu, hãy xem lần chạy reviewer đã xuất hiện chưa. Trong một phiên tương tác bình thường, việc này có thể chạy nền: bạn thấy nó trên panel và vẫn tiếp tục trò chuyện được. Lệnh /tasks giúp xem các tác vụ, kể cả những tác vụ vừa hoàn thành.

Khi kiểm tra xong, tác nhân chính sẽ nhận kết quả và báo lại cho bạn. Nếu phần thuật lại quá ngắn, hãy yêu cầu: "Đưa nguyên văn toàn bộ báo cáo cuối cùng của reviewer". Như vậy dễ giữ được cách diễn đạt chính xác của phát hiện và các giới hạn của lần kiểm tra.

Ví dụ, một báo cáo mẫu về bộ đếm có thể trông như thế này:

Đã kiểm tra việc thêm và xóa trong app.js.
Trong removeItem() danh sách được vẽ lại, nhưng không thấy lời gọi updateCounter()
trên nhánh này. Mong đợi: bộ đếm hiển thị số
mục còn lại.
Kiểm tra trong trình duyệt: thêm một mục, xóa nó,
so bộ đếm với danh sách rỗng.
Chưa kiểm tra riêng việc xóa các mục trùng tên.
Chưa chạy trong trình duyệt.

Đây là ví dụ về hình thức câu trả lời, không phải lời hứa sẽ tìm thấy đúng lỗi này trên trang của bạn. Reviewer của chúng ta chỉ có quyền đọc mã, nên dòng cuối mô tả trung thực khả năng của nó. Kết luận dựa trên mã có thể có căn cứ ngay cả khi không chạy, nhưng căn cứ đó cần được kiểm tra: ví dụ, liệu có hàm nào khác cập nhật bộ đếm trên cùng nhánh đó không.

Hãy mở chỗ được chỉ ra hoặc lặp lại các thao tác đã mô tả trong trình duyệt. Nếu vấn đề được xác nhận, bạn có thể giao việc sửa cho tác nhân chính. Nếu không, hãy báo lại điều bạn quan sát được và yêu cầu kiểm tra lại kết luận. Một báo cáo trình bày đẹp vẫn chưa quyết định được chính xác cần sửa gì.

Câu trả lời "theo các tiêu chí đã cho, không tìm thấy vấn đề" cũng chấp nhận được, nếu rõ là đã kiểm tra những gì. Còn "không tìm thấy tệp chứa logic xóa" nghĩa là kết quả mới được một phần: trước hết cần làm rõ đường dẫn. Không cần nhồi phỏng đoán vào báo cáo chỉ cho có số lượng.

Nhân tiện, trong danh sách bạn có thể gặp các vai trò có sẵn Explore và Plan. Chúng dùng được mà không cần tạo tệp vai trò riêng.

6. Khi nào nên ủy thác

Sau lần kiểm tra thành công đầu tiên, rất dễ muốn có một trợ lý riêng cho mỗi thao tác. Cám dỗ này dễ hiểu. Nhưng một lần chạy mới phải mang lại điều gì đó: một góc nhìn độc lập, hoặc một phần việc tự làm được mà diễn biến chi tiết của nó không cần có trong cuộc trò chuyện chính.

Nhiều bước phụ thuộc nhau cũng có thể gộp thành một nhiệm vụ cho subagent. Tìm hàm xử lý, kiểm tra các chỗ gọi nó và rút ra kết luận - đó là một nhiệm vụ trọn vẹn bình thường. Chỉ không nên chia mỗi bước cho một trợ lý riêng, nếu sau đó bạn lại phải giải thích lại cho từng trợ lý kết quả của bước bên cạnh.

Có thể chỉ định mô hình riêng cho subagent bằng trường model. lúc này thì chưa cần: trước hết nên có một vai trò rõ ràng và một kết quả kiểm chứng được. Bản thân lần chạy riêng không có nghĩa là mô hình mạnh hơn hay yếu hơn.

Vai trò thứ hai phải kiểm tra thứ khác

Giả sử ngoài reviewer bạn cần thêm một playtester để kiểm tra kịch bản người dùng. Chép lại hướng dẫn cũ với tên mới thì gần như chẳng thay đổi được gì. Trước hết hãy phân biệt đối tượng công việc và kết quả:

Ví dụ, vai trò có thể chỉ xét việc xóa một trong hai món hàng trùng tên: sau thao tác phải còn lại một mục, và bộ đếm phải hiển thị 1. Đây là một nhiệm vụ đo lường được. Còn "Đánh giá xem trang có tốt không" thì để lại quá nhiều chỗ cho những lời khuyên theo khẩu vị.

Giờ hãy đối chiếu nhiệm vụ với công cụ. Chỉ có đọc và tìm kiếm như reviewer của chúng ta, trợ lý sẽ không thực hiện được thao tác trong trình duyệt. Nó có thể soạn kịch bản kiểm tra hoặc phân tích những quan sát bạn đã ghi lại. Đó là chuẩn bị hoặc phân tích kiểm tra, không phải một lần playtest nó tự làm.

Soạn kịch bản kiểm tra việc xóa một trong hai món hàng
trùng tên. Với mỗi bước, hãy nêu thao tác
và kết quả mong đợi. Không sửa mã, không khẳng định đã chạy.
Sau khi có quan sát của tôi, hãy so sánh kết quả mong đợi với thực tế
và liệt kê những dữ liệu còn thiếu.

Để trợ lý tự chạy được, cần có một công cụ làm việc với trình duyệt và cách kiểm chứng rằng lần chạy thực sự đã diễn ra. Chỉ riêng cái tên playtester thì chưa đủ. Trước hết hãy chọn cách kiểm tra, sau đó mô tả trong vai trò khi nào gọi nó và nó có thể trung thực trả về kết quả gì.

7. Trong phiên của bạn trông thế nào

Giờ bạn đã có một tệp vai trò mà phiên nhìn thấy, và một lần kiểm tra ngắn có thể giao cho nó. Thế là đủ để bắt đầu. Không cần gom sẵn cả chục reviewer na ná nhau.

Tiếp theo, hãy sửa đúng lớp nơi vấn đề lộ ra. Chưa chuyển một điều kiện quan trọng - bổ sung vào nhiệm vụ. Nhận được kết luận đáng ngờ - kiểm tra căn cứ. Reviewer thường xuyên trả lời quá chung chung - làm rõ hướng dẫn của vai trò. Tệp sẽ ở lại trong dự án, và lần kiểm tra sau bạn sẽ bắt đầu luôn với những quy tắc này.

Với các nhiệm vụ lặp lại, brief cho reviewer sẽ có ích. Khi bạn đã nhận được câu trả lời, hãy chuyển sang kiểm tra các phát hiện và chọn cách sửa.