Chương 7: Code Review

Code review là một cổng kiểm soát chất lượng — không phải là hình thức, không phải là màn trình diễn, và không phải là nghi lễ xã hội. Superpowers xem code review là một hoạt động kỹ thuật nghiêm túc với các giao thức rõ ràng cho cả việc yêu cầu và nhận phản hồi.

Phần 1: Yêu Cầu Code Review

Tại Sao Cấu Trúc Quan Trọng

Một yêu cầu code review không có cấu trúc ("này bạn có thể review cái này không?") tạo ra phản hồi không có cấu trúc. Người review không biết code được cho là làm gì, nó giải quyết vấn đề gì, hoặc những đánh đổi nào đã được thực hiện. Kết quả là những nhận xét bề mặt bỏ lỡ các vấn đề quan trọng.

Một yêu cầu có cấu trúc cung cấp cho người review mọi thứ họ cần để cho bạn phản hồi thực sự hữu ích.

Chuẩn Bị Context

Trước khi điều phối người review, hãy chuẩn bị ba thông tin sau:

WHAT — Thay đổi này làm gì? Viết 2–4 câu mô tả:

Vấn đề đang được giải quyết
Cách tiếp cận đã thực hiện
Bất kỳ quyết định thiết kế quan trọng nào và lý do bạn đưa ra chúng
Những gì bạn không làm và tại sao

PLAN — Kế hoạch implementation là gì? Liên kết đến hoặc tóm tắt kế hoạch đã hướng dẫn công việc này. Điều này cho phép người review xác minh rằng implementation khớp với ý định.

BASE_SHA → HEAD_SHA — Phạm vi commit chính xác đang được review:

# Lấy base (nơi branch của bạn phân kỳ từ main)
git merge-base main HEAD

# Lấy HEAD hiện tại
git rev-parse HEAD

Điều này đảm bảo người review xem xét đúng diff — không phải các commit không liên quan, không phải toàn bộ lịch sử.

Điều Phối Subagent Reviewer

Với context đã chuẩn bị, hãy điều phối một subagent code review với cấu trúc sau:

REVIEW REQUEST
--------------
WHAT: [Mô tả 2-4 câu về thay đổi]

PLAN: [link hoặc tóm tắt kế hoạch implementation]

DIFF RANGE: [BASE_SHA]..[HEAD_SHA]

FOCUS AREAS: [tùy chọn: các khu vực cụ thể bạn muốn xem xét kỹ lưỡng]

Subagent sẽ kiểm tra diff, kiểm tra theo kế hoạch, chạy các test liên quan, và trả về phản hồi có cấu trúc.

Xử Lý Phản Hồi Review Theo Mức Độ Nghiêm Trọng

Không phải tất cả phản hồi đều có cùng mức độ khẩn cấp. Xử lý mỗi cấp độ nghiêm trọng khác nhau:

Mức Độ	Định Nghĩa	Hành Động
Critical	Bug, vấn đề bảo mật, rủi ro mất dữ liệu, hợp đồng bị phá vỡ	Chặn hoàn thành. Sửa ngay lập tức trước bất kỳ công việc nào khác.
Important	Vấn đề chất lượng đáng kể, test bị thiếu, vấn đề hiệu suất	Sửa trước khi bắt đầu nhiệm vụ tiếp theo. Đừng tích lũy.
Minor	Sở thích phong cách, đề xuất đặt tên, cải tiến tùy chọn	Ghi lại. Tạo một ticket follow-up. Đừng làm hoàn hảo hóa PR hiện tại.

Lỗi phổ biến nhất là xem tất cả phản hồi như nhau về mức độ khẩn cấp. Các vấn đề Critical thì chặn. Các vấn đề Minor được ghi lại. Nhầm lẫn chúng gây ra hoặc trì hoãn về phản hồi phong cách tầm thường hoặc bác bỏ các bug thực sự.

Phần 2: Nhận Code Review

Vấn Đề Cốt Lõi: Đồng Ý Mang Tính Hình Thức

AI agent — và nhiều lập trình viên — có xu hướng đồng ý mang tính hình thức trong code review. Đây là khi người review đề xuất điều gì đó, và người thực hiện ngay lập tức nói "Bạn hoàn toàn đúng! Tôi sẽ sửa ngay!" và thực hiện thay đổi mà không thực sự đánh giá xem đề xuất có đúng không.

Đồng ý mang tính hình thức có hại vì:

Nó áp dụng các đề xuất không chính xác vào code đang hoạt động
Nó đào tạo người review để mong đợi sự tuân thủ vô điều kiện
Nó làm suy giảm chất lượng code theo thời gian thông qua các đề xuất xấu tích lũy
Nó cung cấp sự tự tin giả rằng review đang bắt được các vấn đề thực sự

Ngôn Ngữ Bị Cấm

Các cụm từ sau cho thấy sự đồng ý mang tính hình thức và không được phép:

Bị Cấm	Tại Sao	Thay Thế Bằng
"Bạn hoàn toàn đúng!"	Xác nhận mà không đánh giá	"Đã sửa. Thay đổi X thành Y vì [lý do]."
"Phát hiện hay!"	Tán dương xã hội, không có nội dung	"Đã xác minh. Vấn đề là Z."
"Tôi sẽ sửa ngay"	Cam kết trước khi hiểu	"Đang đọc cái này bây giờ."
"Điều đó hoàn toàn có ý nghĩa"	Đồng ý mà không phân tích	"Tôi hiểu mối quan tâm. Đây là đánh giá của tôi: ..."
"Bạn đúng, tôi lẽ ra phải..."	Tự hạ thấp bản thân mà không có hành động	"Đã thực hiện. Đây là những gì đã thay đổi."

Ngôn ngữ thay thế tập trung vào sự thật: những gì đã thay đổi, tại sao nó thay đổi, và những gì đã được xác minh.

Mô Hình Phản Hồi Đúng

Khi bạn nhận được một nhận xét code review, hãy tuân theo trình tự này một cách chính xác:

ĐỌC → HIỂU → XÁC MINH → ĐÁNH GIÁ → PHẢN HỒI → THỰC HIỆN

ĐỌC: Đọc toàn bộ nhận xét, bao gồm bất kỳ code hoặc tài liệu tham khảo nào được đề cập. Đừng phản hồi trong khi đọc.

HIỂU: Bạn có thể giải thích mối quan tâm của người review bằng lời của bạn không? Nếu không, hãy hỏi một câu hỏi làm rõ. Đừng đoán ý định.

XÁC MINH: Kiểm tra xem mối quan tâm có hợp lệ không bằng cách xem xét code thực tế. Chạy các test liên quan nếu có thể. Nhìn vào hành vi thực, không phải mô hình tinh thần của bạn về nó.

ĐÁNH GIÁ: Áp dụng kiểm tra YAGNI (You Aren't Gonna Need It — Bạn Sẽ Không Cần Nó):

Thay đổi này có cần thiết cho các yêu cầu hiện tại không?
Nó có giải quyết một vấn đề thực sự, đã được chứng minh không?
Nó có thêm sự phức tạp mà codebase hiện không cần không?
Đây có phải là best practice hợp lệ hay sở thích phong cách cá nhân không?

PHẢN HỒI: Viết phản hồi dựa trên đánh giá của bạn, không phải bản năng đồng ý.

THỰC HIỆN: Nếu đề xuất hợp lệ, hãy thực hiện nó. Nếu không hợp lệ, hãy giải thích lý do của bạn.

Kiểm Tra YAGNI Với Đề Xuất Của Người Review

Một người review đề xuất "bạn nên thêm caching ở đây" hoặc "bạn nên trừu tượng hóa điều này thành một generic interface" có thể đúng — nhưng kiểm tra YAGNI phải được áp dụng:

Yêu cầu hiện tại có thực sự cần caching không? Có bằng chứng đo lường về vấn đề hiệu suất không?
Có nhiều hơn một use case cụ thể cho sự trừu tượng hóa ngay bây giờ không?

Nếu câu trả lời là không, phản hồi đúng là: "Đã ghi nhận như một cải tiến tiềm năng trong tương lai. Đối với các yêu cầu hiện tại, cách tiếp cận đơn giản hơn là đủ. Tôi đã ghi lại nó như một mục follow-up."

Các Tình Huống Phản Đối Hợp Lệ

Bạn không chỉ được phép phản đối phản hồi review — bạn được yêu cầu làm vậy khi:

Đề xuất giới thiệu một bug. Chứng minh bằng test hoặc ví dụ cụ thể tại sao thay đổi được đề xuất tạo ra hành vi không chính xác.
Đề xuất vi phạm kế hoạch đã thiết lập. Nếu kế hoạch implementation đã được review và phê duyệt, các sai lệch yêu cầu phê duyệt lại rõ ràng, không phải thay đổi đơn phương trong code review.
Đề xuất nằm ngoài phạm vi. Đề xuất có thể tốt, nhưng nó thuộc về một nhiệm vụ riêng biệt. Thực hiện nó bây giờ mở rộng phạm vi, trì hoãn giao hàng, và tạo ra các commit có mục đích hỗn hợp.
Đề xuất là sở thích phong cách không có tác động đến tính đúng đắn. Các sở thích phong cách thuộc về cấu hình linter, không phải phản hồi code review. Nếu nó không thể được tự động hóa, nó có lẽ không đáng để chặn một PR.
Bạn đã xác minh code đúng và người review nhầm. Cung cấp bằng chứng của bạn một cách rõ ràng và tôn trọng. Bạn có thể sai — nhưng bạn phải đưa ra trường hợp.

Mẫu Phản Đối

Khi phản đối, hãy sử dụng cấu trúc này:

Tôi đã đánh giá đề xuất này. Đánh giá của tôi:

CONCERN: [Diễn đạt lại mối quan tâm của người review một cách chính xác]
INVESTIGATION: [Những gì tôi đã kiểm tra để đánh giá nó]
FINDING: [Những gì tôi tìm thấy]
DECISION: [Thực hiện / Ghi lại cho sau / Không đồng ý vì...]
EVIDENCE: [Output test, tài liệu tham khảo, hoặc ví dụ cụ thể]

Điều này làm cho lý luận của bạn có thể kiểm tra và giữ cuộc trò chuyện review tập trung vào các sự kiện.

Tóm Tắt

Code review được thực hiện tốt là một trong những công cụ chất lượng mạnh mẽ nhất hiện có. Code review được thực hiện kém — dù là cao su đóng dấu hay diễn màn tuân thủ — tệ hơn không có review gì cả vì nó tiêu tốn thời gian mà không tạo ra chất lượng.

Giao thức Superpowers đảm bảo rằng cả hai phía của một review đều nghiêm túc: người review nhận được context họ cần, và người thực hiện đánh giá phản hồi với sự trung thực kỹ thuật hơn là sự tuân thủ xã hội.