Cách giao công việc review cho subagent và kiểm tra báo cáo

Yêu cầu "Kiểm tra trang này" để lại cho người review khá nhiều quyết định: tìm lỗi trong hành vi, đánh giá cách trình bày hay đề xuất một cách viết mã khác. Kết quả có thể là một danh sách nhận xét gọn gàng nhưng gần như không giúp gì cho nhiệm vụ của bạn. Chúng ta sẽ xem cách giao cho subagent của Claude Code một yêu cầu rõ ràng, rồi kiểm tra xem nó đã được thực hiện chưa.

Nếu reviewer chưa được cấu hình, trước tiên hãy tạo vai trò và chạy nó lần đầu. Ở đây chúng ta tập trung vào chính yêu cầu và độ đầy đủ của câu trả lời.

1. Điều cần giao cho người review

Người review kiểm tra công việc của người khác và trả về nhận xét kèm cơ sở. Trong các ví dụ của chúng ta, đó là một subagent tùy chỉnh đã được cấu hình với tên reviewer, chỉ được đọc và tìm kiếm trong tệp: Read, Grep, Glob. Nó đọc mã nhưng không sửa và không mở trang trong trình duyệt. Cái tên reviewer không tự động tạo ra vai trò như vậy: giả định rằng vai trò này đã được cấu hình trong dự án của bạn.

Khi được chạy mới theo cách thông thường, subagent như vậy không tự động nhận toàn bộ lịch sử cuộc trò chuyện của bạn. Agent chính, tức agent mà bạn đang trò chuyện, soạn cho nó một nhiệm vụ riêng. Vì vậy, một yêu cầu quan trọng như "hai món hàng cùng tên được coi là hai bản ghi khác nhau" phải có trong yêu cầu hoặc trong tài liệu mà người review được giao đọc. Cơ chế này được mô tả trong tài liệu về ngữ cảnh của subagent; ở đây ta nói về việc chạy một vai trò tùy chỉnh, không phải fork có bản sao cuộc trò chuyện.

Hãy so sánh "Xem qua dự án" và "Kiểm tra việc xóa bản ghi và cập nhật bộ đếm; không sửa mã". Ở câu thứ hai đã rõ cần nhìn vào đâu và bạn không muốn hành động nào. Chỉ còn phải làm rõ thế nào là kết quả đúng.

Với một lần kiểm tra ngắn, làm một lần, một tin nhắn là đủ. Nếu có nhiều tiêu chí hoặc việc kiểm tra sẽ lặp lại sau khi sửa, tiện hơn là lưu một brief: mô tả ngắn về nhiệm vụ, đặt cạnh dự án. Không phải một bản đặc tả riêng dài mười trang. Chỉ vài điều kiện mà thiếu chúng thì người review sẽ phải đoán.

Không thể lường trước mọi câu hỏi, và cũng không cần. Khi thiếu dữ liệu đầu vào, người review cần ghi rõ chỗ trống đó trong báo cáo. Agent chính có thể hỏi lại bạn về nó. Một yêu cầu tốt giảm bớt những cách hiểu khác nhau nhưng không đảm bảo câu trả lời tốt: mô hình vẫn có thể sai ngay cả khi nhiệm vụ rõ ràng.

2. Bốn phần của yêu cầu

Mục tiêu trả lời câu hỏi cần kiểm tra hành vi nào. Với trang danh sách mua sắm, đó là thêm, xóa và bộ đếm bản ghi. "Làm cho dự án tốt hơn" thì quá rộng: không rõ lúc này cải thiện điều gì mới quan trọng.

Đầu vào chỉ ra các tệp và hành vi mong đợi. Chỉ có đường dẫn tới app.js là chưa đủ nếu từ mã không thể biết có cho phép các tên trùng nhau hay không. Quyết định sản phẩm này cần được nói rõ. Tiện thể ghi luôn cách kiểm tra: ở ví dụ của chúng ta chỉ là đọc mã, không dùng trình duyệt.

Ranh giới tách lần kiểm tra này khỏi các nhiệm vụ bên cạnh. Ví dụ, lúc này không xét giao diện, bản hiển thị trên di động và việc lưu danh sách giữa các phiên. không sửa tệp nào. Nếu thiếu tệp cần thiết, dừng phần kiểm tra phụ thuộc vào tệp đó và báo lại, chứ không tự nghĩ ra nội dung của nó.

Kết quả mô tả bạn muốn nhận được gì: phạm vi đã kiểm tra, các phát hiện có cơ sở và các giới hạn. Đừng bắt buộc phải tìm ra năm lỗi. Khuyến nghị của Claude Code về review có nói riêng về rủi ro của cách đặt vấn đề như vậy: yêu cầu tìm khuyết điểm sẽ đẩy người review đưa ra nhận xét ngay cả ở chỗ công việc đã làm đúng.

Mỗi nhánh bổ sung điều mà các nhánh khác không cho: đường dẫn tệp không nói hành vi mong đợi, còn mục tiêu không đặt ra lệnh cấm sửa. Hãy gom các điều kiện này lại để người review có thể đối chiếu chúng khi kiểm tra.

Vậy, thay cho "Kiểm tra trang danh sách mua sắm", ta sẽ giao yêu cầu dưới đây. Có thể gửi nó bằng tin nhắn hoặc lưu vào REVIEW_BRIEF.md ở thư mục gốc của dự án:

# Kiểm tra danh sách mua sắm
Mục tiêu: kiểm tra qua mã việc thêm, xóa và bộ đếm.
Đầu vào: index.html và app.js ở thư mục gốc dự án.
Mong đợi: mục vừa thêm xuất hiện trong danh sách;
bộ đếm bằng số mục; xóa một bản ghi
không xóa bản ghi khác có cùng tên.
Ranh giới: không sửa tệp; giao diện, bản di động và việc lưu
danh sách giữa các phiên không thuộc lần kiểm tra này.
Nếu thiếu tệp hoặc yêu cầu cần thiết, hãy ghi rõ chỗ trống,
đừng tự nghĩ thêm và trả kết quả cho phần có được.
Kết quả: theo định dạng của reviewer; ghi rõ đã kiểm tra gì
và còn gì chưa kiểm tra. Không có phát hiện nào cũng được.

Định dạng của reviewer sẽ được bàn ngay bên dưới. Nếu vai trò của bạn chưa có định dạng cố định, có thể đưa nó vào chính tin nhắn một lần này. Tên các trường không bắt buộc: quan trọng là thông tin mà chúng giúp bạn không bỏ sót.

Yêu cầu "trong báo cáo, trước hết hãy nêu ba phát hiện quan trọng nhất" giới hạn độ dài câu trả lời chứ không giới hạn độ sâu của việc kiểm tra. Nếu cần giới hạn như vậy, hãy yêu cầu nói riêng xem còn phát hiện nào khác không. Không được dừng lại sau nhận xét thứ ba rồi tuyên bố nhiệm vụ đã kiểm tra xong.

3. Điều cần lưu trong tệp

Điều kiện của từng nhiệm vụ cụ thể thì thay đổi: hôm nay kiểm tra bộ đếm, ngày mai kiểm tra việc lưu danh sách. Chúng nằm trong brief. Còn yêu cầu chỉ ra vị trí lỗi và cơ sở thì hầu như lần review nào cũng cần. Tiện hơn là ghi nó một lần trong hướng dẫn của vai trò.

Output contract, hay hợp đồng kết quả, ở đây nghĩa là định dạng câu trả lời đã thống nhất. Nghe có vẻ to tát hơn thực tế: đó chỉ là các chỉ dẫn bình thường cho người review, không phải một thiết lập đặc biệt của Claude Code và cũng không phải cơ chế tự động kiểm tra chất lượng. Định dạng giúp tìm thông tin cần thiết trong báo cáo, nhưng không làm cho thông tin đó đáng tin hơn.

Hai nhánh trên lo những việc khác nhau: brief quy định nội dung kiểm tra, còn hướng dẫn của vai trò quy định, trong số những thứ khác, hình thức báo cáo. Để người review dùng brief đã lưu, hãy giao cho nó đọc tệp. Tự nó sẽ không mở tệp đó ra. Ở phía dưới là một bản báo cáo mà cơ sở và độ đầy đủ của nó vẫn cần được bạn đánh giá.

Dưới đây là một mục có thể thêm vào phần văn bản của tệp vai trò đã có .claude/agents/reviewer.md, sau phần thiết lập của nó:

## Định dạng kết quả
Nêu các tệp và tiêu chí đã kiểm tra.
Với mỗi phát hiện: vị trí, hành vi mong đợi, cơ sở,
điều kiện kiểm tra và ảnh hưởng; giải thích mức ưu tiên.
Tách điều đã được mã xác nhận khỏi giả định chưa kiểm tra.
Nêu riêng các giới hạn và dữ liệu còn thiếu.
Nếu không thấy vấn đề nào theo các tiêu chí, hãy nói rõ như vậy.

Đây là một đoạn trong hướng dẫn, không phải toàn bộ tệp subagent. Vai trò của chúng ta chỉ được đọc và tìm kiếm, nên nó không cần trường cố định "các tệp đã thay đổi". Trong một báo cáo rộng hơn, thông tin về thay đổi phải phản ánh đúng thực tế: không được quy định trước dòng "tệp đã thay đổi: không" bất kể điều gì đã xảy ra.

Khi brief đã được lưu, hãy gửi cho agent chính yêu cầu như sau:

Giao cho reviewer đọc REVIEW_BRIEF.md ở thư mục gốc dự án
và kiểm tra các tệp được nêu theo tiêu chí trong đó.
Trả về toàn bộ báo cáo cuối cùng.

Ta đã nói rõ là phải đọc tài liệu, chứ không chỉ nhắc tên nó. Nhưng bản thân tệp không đảm bảo điều gì: người review vẫn có thể bỏ sót một điều kiện. Brief đã lưu tiện ở chỗ có thể đối chiếu kết quả với nó và lặp lại việc kiểm tra. Khi yêu cầu thay đổi, hãy cập nhật tài liệu trước, nếu không lượt tiếp theo sẽ đánh giá theo nhiệm vụ cũ.

4. Cách kiểm tra báo cáo

Trước hết, hãy xem điều gì thực sự đã được kiểm tra. Brief có thêm, xóa, bộ đếm và tính độc lập của các bản ghi cùng tên. Nếu báo cáo chỉ nói về bộ đếm, đó chưa phải là kết quả cho toàn bộ nhiệm vụ. Kể cả khi phát hiện duy nhất đó hoàn toàn đúng.

Cách tiện là đối chiếu từng tiêu chí của brief với câu trả lời. Ví dụ, với một báo cáo mẫu chưa đầy đủ, kết quả như sau:

Không có dòng nào về các tên giống nhau không có nghĩa là không có lỗi. Đồng thời, một phát hiện có cơ sở về bộ đếm không bù được phần nhiệm vụ bị bỏ sót. Hãy trả báo cáo lại kèm yêu cầu làm rõ cụ thể:

Brief có yêu cầu xóa một trong hai bản ghi cùng tên.
Báo cáo không đề cập đến tiêu chí này. Hãy kiểm tra nó bằng những cách hiện có
và nêu cơ sở của kết quả, hoặc lý do vì sao không kiểm tra được.
Không cần nhắc lại các kết luận khác nếu không có gì thay đổi. Không sửa mã.

Ngoài ra, hãy đánh giá riêng độ tin cậy của các phát hiện quan trọng: đối chiếu vị trí được nêu, yêu cầu và cơ sở của kết luận. Ví dụ chi tiết có trong bài viết về cách đọc báo cáo review. Ở đây cần cả hai phép kiểm tra: phạm vi bao phủ yêu cầu và cơ sở của kết quả. Một kịch bản chạy thử được đề xuất không phải là một bài test đã thực hiện.

Ở ngã rẽ thứ nhất, ta quyết định phạm vi đã kiểm tra có đủ cho nhiệm vụ của mình không. Nếu không, ta yêu cầu phần còn thiếu hoặc chỉ nhận phần đã kiểm tra, sau khi cũng đánh giá cơ sở của nó. Ở ngã rẽ thứ hai, ta tách kết luận có cơ sở khỏi kết luận còn tranh cãi và kết luận sai. Cơ sở chưa rõ thì nên hỏi lại; nhận xét đã chứng minh là sai hoặc lời khuyên không đúng nhiệm vụ thì có thể bác bỏ.

Báo cáo không có phát hiện nào cũng có thể vượt qua bước kiểm tra này. Ví dụ: "Đã kiểm tra luồng thêm và xóa, tính độc lập của các bản ghi giống nhau và việc cập nhật bộ đếm trong index.html và app.js. Theo các tiêu chí này tôi không thấy vấn đề; chưa chạy trong trình duyệt". Kết luận như vậy không hứa rằng dự án không còn lỗi nào. Nó báo kết quả trong phạm vi đã nêu, và nếu cần, bạn tự đối chiếu các luồng chính.

Còn "Không tìm thấy app.js theo đường dẫn đã cho, không kiểm tra được hành vi xóa" có nghĩa là thiếu dữ liệu, chứ không phải là không có lỗi. Lúc này cần đưa đường dẫn đúng và tiếp tục kiểm tra. Một câu trả lời ngắn mà trung thực có ích hơn một báo cáo dài giấu đi chỗ trống.

Chấp nhận báo cáo không có nghĩa là giao sửa mọi thứ được liệt kê. Bạn công nhận kết quả kiểm tra là có cơ sở; còn lúc này sửa những gì thì bạn quyết định riêng.

5. Khi nào cần thêm một lượt

Nếu báo cáo thiếu cơ sở, không nhất thiết phải review lại từ đầu. Hãy trả lại đúng chỗ trống cụ thể. Ví dụ, bản rút gọn của phát hiện về bộ đếm chỉ có tên lỗi, không phân tích các lời gọi hàm. Khi đó, yêu cầu gửi agent chính có thể như sau:

Trả báo cáo lại cho reviewer để làm rõ: phát hiện về bộ đếm
chưa chỉ ra luồng cập nhật bộ đếm sau khi xóa.
Hãy để nó kiểm tra luồng này và bổ sung cơ sở cho kết luận.
Không sửa mã.

Nếu hóa ra việc cập nhật đã diễn ra trong một hàm khác, nhận xét đó cần được rút lại. Không cần tìm nhận xét khác thay thế chỉ để giữ nguyên số mục như trước. Nếu lỗi được xác nhận, bạn có thể giao việc sửa cho agent chính bằng một yêu cầu riêng, nêu rõ phát hiện cụ thể và phạm vi thay đổi được phép.

Sau khi sửa, nên chạy thêm một lượt theo cùng brief đó:

Giao cho reviewer đọc lại REVIEW_BRIEF.md và kiểm tra
mã xóa và bộ đếm hiện tại. Phát hiện trước đó:
sau khi xóa, bộ đếm không được cập nhật.
Hãy để nó nêu rõ vấn đề đã được khắc phục chưa và kết luận dựa trên gì,
đồng thời kiểm tra xem tính độc lập của các bản ghi
cùng tên có bị ảnh hưởng không. Không sửa mã.

Giờ ta tìm câu trả lời cho một câu hỏi cụ thể: vấn đề đã được khắc phục chưa và bản sửa có làm hỏng hành vi lân cận mà nó có thể chạm tới không. Để xác nhận hành vi trên trang, hãy lặp lại đúng kịch bản đó trong trình duyệt. Nếu lượt review lại chỉ dựa trên mã, giới hạn này vẫn phải có trong báo cáo mới.

Báo cáo có thể ngắn hơn, dài hơn hoặc không có phát hiện mới. Thành công không nằm ở đó. Điều quan trọng là lỗi cũ đã được khắc phục, kết luận dựa trên mã hiện tại, và những phần chưa kiểm tra vẫn được thấy rõ. Bạn quyết định hoãn việc sửa? Khi đó hãy lưu lại phát hiện đã xác nhận và lý do hoãn; review lại mã chưa đổi chỉ để nhận một câu trả lời mới thì không cần.

6. Từ yêu cầu đến kết quả đã kiểm chứng

Khi làm việc với Claude Code, brief giúp giữ nguyên kỳ vọng của bạn trong lúc agent chính chuyển nhiệm vụ cho người review. Định dạng cố định giúp đọc câu trả lời dễ hơn. Nhưng bạn vẫn phải tham gia, cụ thể là:

• agent chính soạn yêu cầu và chuyển cho vai trò phù hợp; bạn đặt ra hành vi mong đợi và ranh giới;
• người review đọc các tệp và trả về cơ sở của các kết luận; còn phạm vi và các phát hiện quan trọng thì bạn kiểm tra;
• agent chính có thể làm rõ báo cáo hoặc sửa lỗi đã xác nhận theo một yêu cầu riêng; bạn quyết định sửa gì và xác nhận kết quả bằng cách nào.

Với danh sách mua sắm, kết quả không chỉ là lời khuyên "thêm lời gọi hàm", mà là một lời giải thích đã được kiểm chứng: con số bị lỗi thời sau thao tác nào, việc cập nhật bị hỏng ở đâu và điều gì đã thay đổi sau khi sửa. Với kết quả như vậy thì đã có thể làm việc.