Cách review code thông qua agent

Hãy tưởng tượng một trang danh sách mua sắm: trang mở ra, các mục được thêm vào, các nút trông bình thường. Nhưng màn hình chạy được chưa có nghĩa là mã đã được suy nghĩ kỹ. Các nhà phát triển tổ chức riêng một bước xem mã để tìm những lỗi bị bỏ sót và thảo luận các giải pháp. Việc này có thể giao cho agent, và nó sẽ làm rất tốt. Chỉ cần giải thích nhiệm vụ cho nó.

1. Cách nhóm review code

Trong một nhóm nhỏ, một nhà phát triển nhận được nhiệm vụ: làm một danh sách mua sắm có thể thêm mục và xóa từng mục một. Anh ấy viết mã, thử thêm bánh mì và sữa, xóa bánh mì. Mọi thứ đều chạy. Trước khi chuyển công việc đi tiếp, nhà phát triển đọc lại các thay đổi của mình một lần nữa: bỏ một đoạn quên xóa, sửa một cái tên khó hiểu. Đó là tự kiểm tra.

Sau đó, anh ấy nhờ một đồng nghiệp xem mã. Đồng nghiệp biết ngôn ngữ lập trình và đọc xem phần thêm mục được viết thế nào, chương trình chọn mục cần xóa ra sao, phần còn lại của danh sách thì sao. Việc xem mã như vậy gọi là review code, hay đánh giá mã, còn người xem mã gọi là reviewer.

Đồng nghiệp nhận thấy: chương trình chọn mục cần xóa theo tên. Nếu danh sách có hai mục "Sữa", bấm xóa một mục có thể xóa cả hai. Tác giả đã thử với bánh mì và sữa. Chỉ là anh ấy chưa gặp trường hợp như vậy.

Reviewer để lại bình luận ngay cạnh đoạn mã tương ứng: "Hiện tại mọi mục có tên này đều bị xóa. Chúng ta có cho phép các mục trùng tên không? Nếu có, chỉ nên xóa mục được chọn". Tác giả làm rõ yêu cầu: các mục trùng tên được phép, vì chúng có thể được thêm cho những người khác nhau. Sau khi thảo luận, anh ấy đổi cách chọn mục. Đồng nghiệp xem lại bản sửa và xác nhận rằng nhận xét đã được xử lý.

Sơ đồ cho thấy một vòng review có nhận xét: mã đi từ tác giả sang đồng nghiệp, rồi quay lại để sửa. Nếu sau lần xem lại vẫn còn câu hỏi, việc thảo luận và sửa được lặp lại. Khi không còn nhận xét đáng kể, đồng nghiệp duyệt thay đổi.

Đây là vòng làm việc bình thường: viết, đưa cho người khác xem, nhận nhận xét, thảo luận, sửa. Có khi nhận xét nhiều, có khi không có cái nào. Cũng có lúc tác giả giải thích lý do chọn cách làm và đồng nghiệp rút lại câu hỏi. Review không bắt buộc phải đồng ý với mọi bình luận.

Khi xem mã như vậy, mọi người cũng bàn về độ dễ hiểu của mã: người phát triển tiếp theo có hiểu được không, có phải sửa cùng một quy tắc ở nhiều chỗ không. Đồng thời đồng nghiệp cũng biết phần mới của chương trình được xây dựng ra sao. Hiểu biết về dự án dần được chia sẻ giữa nhiều người, chứ không chỉ nằm trong đầu tác giả.

Ở đây dễ nhầm review với kiểm thử. Khi một người thêm hai mục rồi bấm nút, họ đang kiểm tra hành vi của chương trình đang chạy. Khi họ đọc mã xóa và tìm hiểu xem nó sẽ chọn những mục nào, đó là review. Trong lúc review vẫn có thể chạy chương trình để kiểm chứng một phỏng đoán. Hai cách này bổ sung cho nhau.

2. Cách giao việc review cho agent

Bây giờ hãy tưởng tượng danh sách mua sắm do Claude Code viết theo mô tả của bạn. Bạn giải thích được trang cần hoạt động thế nào, nhưng không đọc được logic chương trình của nó. Phần kỹ thuật của việc review cũng có thể giao cho agent: nó sẽ đọc các tệp và giải thích các nhận xét bằng lời lẽ thông thường.

Các vai trò trong câu chuyện của nhóm vẫn giữ nguyên. Có tác giả của mã và có người kiểm tra được giao một nhiệm vụ riêng. Trong Claude Code, bạn có thể dùng subagent cho việc này: một trợ lý được agent chính giao một việc cụ thể. Trong ví dụ này, nó đọc mã và trả về các nhận xét.

Nhờ tác giả tự kiểm tra lại công việc của mình cũng có ích. Một reviewer riêng mang lại góc nhìn khác: nhiệm vụ của nó là đánh giá kết quả. Hãy đưa cho nó các yêu cầu, để nó hiểu những giải pháp nào chấp nhận được. Ví dụ, cấm các mục trùng tên thì về hình thức sẽ hết lỗi xóa, nhưng lại thay đổi hành vi mà trang được thiết kế để có.

Các khuyến nghị của Claude Code về review đề xuất dùng một người kiểm tra riêng và các tiêu chí rõ ràng. Tài liệu đó cũng khuyên tập trung vào những nhận xét ảnh hưởng đến việc chương trình chạy đúng và đáp ứng yêu cầu. Hãy áp dụng điều này cho một phần nhỏ của dự án.

Để tổ chức review, bạn không cần làm nhiều: mô tả hành vi mong muốn và chọn những vấn đề đã xác nhận nào cần sửa. Việc đọc logic chương trình, tìm nguyên nhân và xử lý các phản biện kỹ thuật có thể giao cho các agent.

Sơ đồ có ba vai trò: bạn đặt ra yêu cầu và chọn điều cần sửa, agent chính tổ chức công việc và sửa mã, còn những người kiểm tra xem xét mã và các nhận xét. Agent chính chuyển cho họ những tài liệu cần thiết và gửi kết quả lại cho bạn. Nếu không có vấn đề nào được xác nhận, các bước sửa sẽ được bỏ qua. Dưới đây ta sẽ đi hết trình tự này bằng ba yêu cầu.

Kết quả là bạn có một lời giải thích dễ hiểu về vấn đề, kết quả kiểm tra lại vấn đề đó và báo cáo về bản sửa. Còn nếu nhận xét hóa ra sai, bạn vẫn được một kết quả có ích: tránh được một lần sửa không cần thiết.

Nếu bạn muốn thiết lập một trợ lý cố định cho những lần xem mã như vậy, bài viết về cách tạo và chạy subagent sẽ có ích. Cách chuẩn bị cho nó một bản giao việc chi tiết hơn được trình bày trong bài viết về brief và định dạng kết quả.

Yêu cầu 1. Kiểm tra mã đã viết

Khởi chạy Claude Code trong thư mục dự án. Gửi ba yêu cầu tiếp theo vào phiên chính: agent chính sẽ tự chuyển việc cho các trợ lý. Từ đây trở đi, ta dùng danh sách mua sắm làm ví dụ; với dự án của bạn, hãy thay phần mô tả hành vi.

Giao cho một subagent riêng việc review code danh sách mua sắm
trong dự án hiện tại. Kiểm tra phần thêm và xóa mục.
Yêu cầu: cho phép tên trùng nhau; chỉ xóa đúng mục được chọn;
không được thêm mục trống.

Đọc mã hiện tại và các phần liên quan của dự án.
Tìm những lỗi vi phạm các yêu cầu này.
Không sửa mã. Không thêm tính năng mới.
Với mỗi nhận xét, giải thích bằng lời đơn giản:
điều gì có thể sai, khi thực hiện thao tác nào và vì sao bạn kết luận như vậy.
Chỉ ra vị trí trong mã để một agent khác kiểm tra tiếp.
Nếu không tìm thấy vấn đề, hãy nói rõ như vậy. Liệt kê những gì đã kiểm tra
và những gì vẫn chưa rõ. Lưu báo cáo vào REVIEW_REPORT.md.
Tôi không biết ngôn ngữ lập trình: hãy giải thích kết quả sao cho tôi không cần đọc mã.

Tệp REVIEW_REPORT.md sẽ là một báo cáo văn bản bình thường. Tên này do ta tự chọn, đặt tên khác cũng được: nó cần để ở yêu cầu tiếp theo biết rõ phải kiểm tra lại những nhận xét nào. Yêu cầu "không sửa mã" tách việc xem mã khỏi việc sửa; còn việc ghi báo cáo thì vẫn được phép.

Trong ví dụ của ta, một câu trả lời hữu ích có thể như sau: "Nếu thêm hai mục trùng tên, xóa một mục sẽ xóa cả hai. Mã chọn mục theo tên, nên cả hai mục trùng đều bị ảnh hưởng". Đây là câu trả lời minh họa, không phải kết quả kiểm tra dự án của bạn.

Hậu quả thì bạn hiểu ngay: người dùng sẽ mất một mục mà họ định giữ lại. Tên tệp và vị trí trong mã là để agent tiếp theo tìm ra nguyên nhân. Bạn không cần tự đi phân tích đoạn mã đó.

3. Cách kiểm tra lại các nhận xét

Agent-reviewer cũng có lúc sai. Ví dụ, nó viết: "Có thể thêm một mục trống vào danh sách". Nghe rất thuyết phục. Nhưng bước kiểm tra dữ liệu nhập trống đã có ở một phần khác của chương trình mà nó không đọc tới. Nhận xét mô tả một vấn đề không hề tồn tại.

Một khẳng định chắc nịch nhưng bịa ra như vậy thường được gọi là ảo giác (hallucination) của AI. Trong review, nó đặc biệt phiền: agent có thể đề xuất một bản sửa, và bạn sẽ mất thời gian thay đổi đoạn mã vốn đang chạy đúng. Vì thế nên kiểm tra lại cả mã sau khi viết lẫn các nhận xét về nó.

Bước đầu tiên ta đã làm: giao cho một người xem lại công việc của tác giả. Giờ ta đưa báo cáo đó, cùng với dự án hiện tại, cho một người kiểm tra khác. Nhiệm vụ của nó: xác định xem từng nhận xét có đúng hay không. Nó được phép không đồng ý với reviewer thứ nhất.

Yêu cầu 2. Kiểm tra báo cáo của reviewer

Giao cho một subagent khác kiểm tra lại REVIEW_REPORT.md
dựa trên mã hiện tại của dự án và các yêu cầu trong lần nhắn trước.
Chuyển rõ ràng các yêu cầu đó cho nó.

Với mỗi nhận xét, xác định xem vấn đề được mô tả có thật sự tồn tại không.
Kiểm tra các phần mã liên quan: có thể phần xử lý cần thiết đã có sẵn.
Không coi báo cáo đầu tiên là bằng chứng. Nếu cần chạy thử mới kết luận được,
hãy chạy bằng những công cụ sẵn có.
Không sửa mã của dự án.

Với mỗi mục, ghi rõ: đã xác nhận, đã bác bỏ
hoặc chưa xác định được. Giải thích căn cứ bằng lời dễ hiểu.
Tách riêng kết luận rút ra từ việc đọc mã và kết quả của những lần kiểm tra đã chạy.
Không trình bày một lần kiểm tra chưa chạy như thể đã chạy.
Lưu kết quả vào REVIEW_CHECK.md và giải thích ngắn gọn cho tôi.

Sau bước này, bạn sẽ có REVIEW_CHECK.md với kết quả kiểm tra lại. Trong ví dụ minh họa của ta, agent thứ hai có thể xác nhận vấn đề trùng tên và bác bỏ nhận xét về dữ liệu nhập trống: "Chuỗi rỗng bị từ chối trước khi mục được thêm vào. Reviewer thứ nhất đã bỏ sót bước kiểm tra này".

Đến đây đã dễ chọn bước tiếp theo hơn. Vấn đề xóa có thể chuyển sang sửa. Phần xử lý dữ liệu nhập trống thì không cần thay đổi vì nhận xét này. Nếu agent viết "chưa xác định được", hãy nhờ nó giải thích còn thiếu dữ liệu gì. Đôi khi đó là câu hỏi dành cho bạn: chẳng hạn, các mục trùng tên nên được tính là một món hay hai món.

Kiểm tra lại giúp lọc bớt các nhận xét bịa đặt, nhưng không đảm bảo chúng biến mất hoàn toàn. Hai agent có thể mắc cùng một lỗi. Vì thế câu trả lời cần có căn cứ: người kiểm tra đã tìm thấy chính xác điều gì trong dự án, hoặc nhận được kết quả gì khi chạy thử. Chỉ một câu "đồng ý với agent trước" là không đủ.

4. Sửa và review lại

Bây giờ hãy chọn điều cần sửa. Để chọn, chỉ cần hiểu vấn đề ảnh hưởng thế nào đến cách trang được thiết kế để hoạt động. Trong ví dụ của ta, việc xóa nhầm thêm một mục rõ ràng gây phiền, nên ta chọn mục này. Đề xuất thêm tính năng sắp xếp có thể để sau. dù sao nó cũng chẳng liên quan gì đến việc sửa lỗi xóa.

Hãy chuyển nguyên văn nhận xét đã chọn cho agent, để nó không phải đoán "sửa lỗi đầu tiên" của bạn là lỗi nào. Yêu cầu nó kiểm tra lại kết quả sau khi sửa. Đây chính là phần tiếp của câu chuyện trong nhóm: đồng nghiệp xem phiên bản đã sửa.

Yêu cầu 3. Sửa và kiểm tra kết quả

Sửa vấn đề đã được xác nhận trong REVIEW_CHECK.md:
khi xóa một mục mua sắm, mọi mục cùng tên đều biến mất.
Chỉ được xóa đúng mục được chọn. Cho phép tên trùng nhau.
Tạm thời chưa áp dụng các đề xuất khác trong bản review.

Sau khi sửa, hãy dùng những công cụ sẵn có để kiểm tra việc thêm
và xóa mục, bao gồm cả trường hợp hai mục trùng tên.
Sau đó giao cho một subagent riêng review lại mã đã sửa:
nguyên nhân đã được loại bỏ chưa và việc thêm, xóa có còn chạy đúng không.
Chuyển cho nó các yêu cầu ban đầu và mô tả vấn đề đang được sửa.

Giải thích cho tôi bằng lời đơn giản: đã thay đổi gì, đã chạy
những kiểm tra nào và lần review lại cho thấy điều gì.
Nếu có gì chưa kiểm tra được, hãy nêu riêng.
Không mở rộng nhiệm vụ bằng các cải tiến mới.

Với dự án của bạn, hãy thay đoạn nói về mua sắm bằng nhận xét đã được xác nhận trong báo cáo của bạn. Phần còn lại của trình tự có thể giữ nguyên: sửa, kiểm tra, xem riêng kết quả.

Một kết quả tốt phải nói ra điều cụ thể: "Giờ mỗi mục được xóa riêng. Lần kiểm tra với hai mục trùng tên cho thấy mục thứ hai vẫn còn nguyên. Lần review lại không còn thấy nguyên nhân lỗi cũ". Chỉ có thể viết như vậy sau khi đã chạy các kiểm tra tương ứng. Nếu agent chỉ đọc mã, nó phải nói rõ điều đó.

Bạn cũng có thể mở trang và thử những thao tác quen thuộc. Việc này không cần biết ngôn ngữ lập trình. Đây là bước kiểm tra thêm phần kết quả nhìn thấy được; còn phần review kỹ thuật cho bản sửa vẫn do agent làm. Nếu nó không đủ khả năng chạy thử, báo cáo sẽ ghi rõ giới hạn đó, chứ không phải lời hứa "mọi thứ chắc chắn chạy".

Không nhất thiết phải biến mỗi vòng review thành một cuộc sửa đổi không hồi kết. Nếu vấn đề đã chọn được khắc phục, đã được kiểm tra và lần xem lại không phát hiện lỗi liên quan, bạn có thể kết thúc nhiệm vụ này. Thế thôi. Những mong muốn mới đáng được bàn riêng.