Claude Code PR review: rà soát diff trước review nhanh hơn và an toàn hơn

Tại sao thời gian review PR lại kéo dài

Việc review PR hiếm khi tốn thời gian vì mã “khó”. Nó kéo dài vì reviewer phải tái dựng ý định, rủi ro và ảnh hưởng từ một diff chỉ cho thấy các thay đổi, không phải toàn bộ câu chuyện.

Một sửa nhỏ có thể chạm tới các phụ thuộc ẩn: đổi tên trường và báo cáo bị hỏng, thay mặc định và hành vi thay đổi, tinh chỉnh điều kiện và xử lý lỗi biến đổi. Thời gian review tăng khi reviewer phải click tìm ngữ cảnh, chạy app cục bộ, và hỏi hỏi lại chỉ để hiểu PR nhằm làm gì.

Còn có một vấn đề về thói quen con người. Mọi người đọc lướt diff theo những cách dễ đoán: chúng ta tập trung vào thay đổi “chính” và bỏ qua những dòng nhàm chán nơi lỗi ẩn (kiểm tra biên, xử lý null, logging, dọn dẹp). Chúng ta cũng có xu hướng đọc những gì mong đợi thấy, nên lỗi copy-paste và điều kiện đảo ngược có thể lọt qua.

Một pre-review tốt không phải là phán quyết. Nó là một cặp mắt thứ hai nhanh và có cấu trúc, chỉ ra nơi con người nên chậm lại. Kết quả tốt nhất là:

• một tóm tắt bằng tiếng thường về những gì đã thay đổi
• các điểm rủi ro cụ thể (file, hàm, giả định)
• ghi chú về khả năng đọc (đặt tên, luồng điều khiển khó hiểu)
• lo ngại về độ đúng (logic, xử lý lỗi, nhất quán dữ liệu)
• các trường hợp biên đáng thử (đầu vào, thời gian, quyền, trạng thái rỗng)

Những gì nó không nên làm: “phê duyệt” PR, bịa đặt yêu cầu, hoặc đoán hành vi runtime khi không có bằng chứng. Nếu diff không cung cấp đủ ngữ cảnh (đầu vào mong đợi, ràng buộc, hợp đồng caller), pre-review nên nói rõ và liệt kê chính xác những gì thiếu.

Trợ giúp AI mạnh nhất với các PR cỡ vừa chạm vào business logic hoặc refactor nơi ý nghĩa dễ bị mất. Nó yếu hơn khi câu trả lời đúng phụ thuộc vào kiến thức tổ chức sâu (hành vi legacy, quirks hiệu năng production, quy tắc bảo mật nội bộ).

Ví dụ: một PR “chỉ cập nhật phân trang” thường ẩn off-by-one, kết quả rỗng, và sắp xếp không khớp giữa API và UI. Một pre-review nên nêu những câu hỏi đó trước khi con người mất 30 phút tái khám phá.

Nên yêu cầu Claude làm gì trong một pre-review

Hãy coi Claude như một reviewer vòng đầu nhanh và khó tính, không phải người quyết định PR có được phát hành không. Mục tiêu là phát hiện vấn đề sớm: mã khó hiểu, thay đổi hành vi ẩn, thiếu test, và những edge case bạn quên khi quá gần thay đổi.

Cung cấp cho nó những gì một reviewer con người công bằng cần:

• mục tiêu của PR (1–3 câu)
• những gì không được phá vỡ (shape API, tương thích ngược, ngân sách hiệu năng, luật bảo mật)
• bất kỳ ràng buộc hay đánh đổi đặc biệt (deadline, rollout từng phần)
• các hunks diff liên quan, với đủ code xung quanh để hiểu ý định

Nếu PR chạm vào vùng rủi ro cao đã biết, nói rõ ngay (auth, billing, migrations, concurrency).

Rồi yêu cầu các đầu ra bạn có thể hành động. Một yêu cầu mạnh nhìn như:

• Tóm tắt những gì đã thay đổi bằng tiếng thường.
• Gắn cờ vấn đề khả năng đọc (tên, cấu trúc, ngạc nhiên, pattern không nhất quán).
• Xác định rủi ro độ đúng (xử lý null, đường dẫn lỗi, off-by-one, mismatch shape dữ liệu).
• Liệt kê các trường hợp biên và chế độ lỗi cần thử (timeout, retry, input rỗng, cập nhật từng phần).
• Gợi ý test thiếu và mỗi test chứng minh điều gì.
• Tạo một checklist ngắn cho reviewer và 5–10 câu “cần hỏi” trước khi merge.

Giữ con người làm chủ bằng cách buộc rõ chỗ không chắc chắn. Yêu cầu Claude gắn nhãn phát hiện là “chắc chắn từ diff” hoặc “cần xác nhận”, và trích chính xác các dòng đã kích hoạt mỗi lo ngại.

Chuẩn bị diff và ngữ cảnh trước khi prompt

Claude chỉ tốt bằng những gì bạn cung cấp. Nếu bạn dán một diff khổng lồ mà không có mục tiêu hay ràng buộc, bạn sẽ nhận lời khuyên chung chung và bỏ qua rủi ro thực.

Bắt đầu với mục tiêu cụ thể và tiêu chí thành công. Ví dụ: “PR này thêm rate limiting cho endpoint login để giảm lạm dụng. Nó không được thay đổi shape của response. Nó phải giữ latency trung bình dưới 50 ms.”

Tiếp theo, chỉ bao gồm những gì quan trọng. Nếu 20 file thay đổi nhưng chỉ 3 file chứa logic, tập trung vào 3 file đó. Bao gồm ngữ cảnh xung quanh khi một đoạn trích sẽ gây hiểu lầm, như chữ ký hàm, kiểu dữ liệu then chốt, hoặc config thay đổi hành vi.

Cuối cùng, rõ ràng về kỳ vọng test. Nếu bạn muốn unit test cho các edge case, test tích hợp cho đường dẫn quan trọng, hay chạy thủ công UI, hãy nói rõ. Nếu test thiếu có chủ ý, nêu lý do.

Một “gói ngữ cảnh” đơn giản hoạt động tốt:

• Mục tiêu PR: thay đổi gì, người dùng thấy gì, cải thiện ra sao
• Các hunks diff liên quan: chỉ file chính, với đủ code xung quanh
• Ràng buộc cứng: ngân sách hiệu năng, yêu cầu tương thích, luật bảo mật/riêng tư
• Kỳ vọng test: phải bao phủ gì, đã thêm gì, cách chạy
• Những thứ “không được thay đổi”: hợp đồng API công khai, schema DB, hành vi UX, định dạng logging/auditing

Bước một: luồng pre-review có thể lặp lại

Một Claude Code PR review tốt là vòng lặp ngắn: cung cấp vừa đủ ngữ cảnh, nhận ghi chú có cấu trúc, rồi biến chúng thành hành động. Nó không thay thế con người. Nó bắt được lỗi dễ trước khi đồng đội phải dành thời gian dài đọc.

Luồng 5 bước

Dùng cùng các lượt kiểm tra mỗi lần để kết quả ổn định:

1. Giải thích thay đổi bằng ngôn ngữ đơn giản. Yêu cầu Claude tóm tắt PR làm gì, file nào thay đổi, và lý do khả dĩ. Nếu nó không giải thích được đơn giản, có lẽ PR cần mô tả rõ hơn hoặc scope nhỏ hơn.
2. Kiểm tra độ đúng trước. Tìm lỗi logic, giả định bị phá vỡ, và thay đổi hành vi im lặng (mặc định, xử lý lỗi, quyền, timezone, off-by-one).
3. Quét các trường hợp thiếu. Nghĩ như người dùng và như production: input rỗng, null, retry, thất bại từng phần, concurrency, tương thích ngược.
4. Đánh giá khả năng đọc và bảo trì. Xác định tên khó hiểu, hàm dài, logic trùng lặp, comment mơ hồ, và những refactor nhỏ giúp giảm thời gian review tương lai.
5. Soạn comment review với chỉ dẫn. Gom comment theo file và kèm tên hàm hoặc trích đoạn đã quote để người kiểm tra tìm nhanh.

Sau khi nhận ghi chú, biến chúng thành một cổng merge ngắn:

Checklist merge (ngắn gọn):

• Tests bao phủ hành vi mới và ít nhất một edge case
• Lỗi được xử lý nhất quán (và được log nếu cần)
• Không có breaking change nếu không có đường di trú rõ ràng
• Đặt tên và cấu trúc khớp code xung quanh
• Các phần rủi ro có kế hoạch rollback

Kết thúc bằng việc yêu cầu 3–5 câu hỏi thúc đẩy sự rõ ràng, như “Điều gì xảy ra nếu API trả về danh sách rỗng?” hoặc “Điều này an toàn dưới các request đồng thời không?”.

Dùng một rubric đơn giản (khả năng đọc, độ đúng, edge cases)

Claude hữu ích nhất khi bạn cho nó một thấu kính cố định. Nếu không có rubric, nó có xu hướng bình luận những gì xuất hiện trước (thường là style nits) và có thể bỏ qua trường hợp biên rủi ro.

Một rubric thực tế:

• Khả năng đọc: tên rõ ràng, luồng đơn giản, hàm nhỏ, comment giải thích lý do, không có dead code hay debug còn sót.
• Độ đúng: bất biến chính được đảm bảo, lỗi được xử lý nhất quán, null/giá trị rỗng an toàn, biên đúng (off-by-one, làm tròn).
• Edge cases: input rỗng/khổng lồ, trường optional thiếu, timezone và daylight savings, retry gây double-write, race condition.
• Bảo mật và riêng tư: kiểm tra auth đúng chỗ, không để secrets trong code/log, logs không lộ token hay payload nhạy cảm.
• Tương thích và an toàn khi rollout: client cũ và dữ liệu đã lưu không vỡ, migration an toàn, có kế hoạch rollback.

Khi prompt, yêu cầu một đoạn ngắn cho mỗi hạng mục và nhờ “vấn đề rủi ro nhất trước.” Thứ tự đó giữ con người tập trung.

Mẫu prompt giúp sinh ghi chú review hữu ích

Dùng một prompt cơ bản tái sử dụng để kết quả giống nhau qua các PR. Dán mô tả PR, rồi diff. Nếu hành vi hướng tới người dùng, thêm đoạn kỳ vọng 1–2 câu.

You are doing a pre-review of a pull request.

Context
- Repo/service: <name>
- Goal of change: <1-2 sentences>
- Constraints: <perf, security, backward compatibility, etc>

Input
- PR description:
<...>
- Diff (unified diff):
<...>

Output format
1) Summary (max 4 bullets)
2) Readability notes (nits + suggested rewrites)
3) Correctness risks (what could break, and why)
4) Edge cases to test (specific scenarios)
5) Reviewer checklist (5-10 checkboxes)
6) Questions to ask the author before merge (3-7)

Rules
- Cite evidence by quoting the relevant diff lines and naming file + function/class.
- If unsure, say what info you need.

Đối với các thay đổi rủi ro cao (auth, payments, permissions, migrations), thêm suy nghĩ rõ ràng về thất bại và rollback:

Extra focus for this review:
- Security/privacy risks, permission bypass, data leaks
- Money/credits/accounting correctness (double-charge, idempotency)
- Migration safety (locks, backfill, down path, runtime compatibility)
- Monitoring/alerts and rollback plan
Return a “stop-ship” section listing issues that should block merge.

Với refactor, đặt “không đổi hành vi” là quy tắc cứng:

This PR is a refactor. Assume behavior must be identical.
- Flag any behavior change, even if minor.
- List invariants that must remain true.
- Point to the exact diff hunks that could change behavior.
- Suggest a minimal test plan to confirm equivalence.

Nếu bạn muốn skim nhanh, thêm giới hạn như “Answer in under 200 words.” Nếu cần sâu, yêu cầu “up to 10 findings with reasoning.”

Biến kết quả thành checklist cho reviewer

Ghi chú của Claude hữu dụng khi bạn chuyển chúng thành một checklist ngắn mà con người có thể đóng. Đừng lặp lại diff. Ghi lại rủi ro và quyết định.

Tách mục thành hai nhóm để thread không biến thành tranh luận về sở thích:

Must-fix (chặn merge)

• Độ đúng: kết quả mong đợi được viết trong một câu và khớp ticket
• Edge cases: input null/rỗng và đường dẫn lỗi được xử lý rõ ràng (hoặc bị từ chối)
• An toàn dữ liệu: ghi và migration an toàn cho dữ liệu hiện có và code cũ
• Tests: ít nhất một test cho hành vi chính và một test cho failure rủi ro nhất
• Observability: logs/metrics đủ để debug nhanh (request id, user id, job id)

Nice-to-have (theo dõi sau)

• Khả năng đọc: đổi tên identifier gây nhầm hoặc thêm comment “tại sao” ngắn
• Tính nhất quán: khớp pattern hiện có với lỗi, tên, layout file
• Hiệu năng: chú ý đường nóng và liệu có ảnh hưởng ở scale hiện tại
• Docs: cập nhật docs inline nếu thêm option/flag mới

Cũng ghi sẵn readiness khi rollout: thứ tự deploy an toàn nhất, điều gì cần theo dõi sau phát hành, và cách hoàn nguyên thay đổi.

Các câu hỏi cần hỏi trước khi merge

Một pre-review chỉ giúp khi kết thúc bằng vài câu hỏi nhỏ buộc sự rõ ràng.

Hành vi và độ đúng

• Thay đổi gì nhìn thấy với người dùng, và gì phải giữ nguyên?
• Nếu là “không đổi hành vi”, bằng chứng nào cho thấy outputs giống nhau?
• Thất bại production khả dĩ nhất là gì, và nó xuất hiện ở đâu (UI, API, dữ liệu)?
• Code giả định gì về input, thứ tự, thời gian, hay các cuộc gọi mạng?
• Có lỗi nào bị nuốt hay chuyển thành mặc định im lặng không?

Edge cases, tests, và vận hành

• Input tồi tệ nhất là gì (rỗng, khổng lồ, malformed, duplicate), và nên xảy ra gì?
• Luồng phổ biến nào có thể kích hoạt lại (retry, double-click, background job), và có an toàn không?
• Test nào chứng minh hành vi chính, và test nào che phủ edge case rủi ro nhất?
• Nếu thiếu test, việc viết test khó hay code khó để test?
• Ops cần gì: logs hữu ích, metrics, cảnh báo, defaults config, và bước rollback?

Nếu bạn không thể trả lời bằng lời rõ ràng, tạm dừng merge và thu hẹp scope hoặc thêm bằng chứng.

Bẫy thường gặp (và cách tránh)

Hầu hết lỗi là vấn đề quy trình, không phải model.

• Dán diff khổng lồ không có trọng tâm. Yêu cầu review 1–3 vùng rủi ro và dán những hunks liên quan cộng với các chữ ký họ phụ thuộc.
• Bỏ qua ý định và hành vi mong đợi. Không có goal, review bị trôi. Thêm hai dòng: thay đổi gì và gì không được thay đổi.
• Tin vào dự đoán tự tin. Yêu cầu trích dẫn lại từ diff. Nếu không trích được bằng chứng, coi đó là giả thuyết cần kiểm tra.
• Lãng phí vào style. Yêu cầu phân rõ “Must-fix” vs “Nice-to-have”, và giới hạn ghi chú style.
• Bỏ qua chuẩn đội. Nếu team có quy ước (early returns, loại lỗi, format logging), đưa vào.

Nếu PR thêm endpoint checkout mới, đừng dán toàn bộ service. Dán handler, validation, DB write, và schema thay đổi. Rồi nói: “Goal: tránh double charges. Non-goals: refactor đặt tên.” Bạn sẽ nhận ít comment hơn, và những comment nhận được dễ xác minh.

Ví dụ thực tế: pre-review một PR nhỏ

Một PR nhỏ, cảm giác thực tế: thêm trường “display name” vào màn hình settings. Nó chạm validation (server) và text UI (client). Nó đủ nhỏ để lý luận, nhưng vẫn đầy nơi ẩn lỗi.

Đây là những snippet diff bạn sẽ dán (cộng 2–3 câu ngữ cảnh như hành vi mong đợi và ticket liên quan):

- if len(name) == 0 { return error("name required") }
+ if len(displayName) < 3 { return error("display name too short") }
+ if len(displayName) > 30 { return error("display name too long") }

- <TextInput label="Name" value={name} />
+ <TextInput label="Display name" value={displayName} helperText="Shown on your profile" />

Những phát hiện mẫu bạn muốn nhận lại:

• Khả năng đọc: “displayName” và “name” bị trộn trong các file. Chọn một thuật ngữ để các thay đổi tương lai không phải dịch nghĩa trong đầu.
• Độ đúng: server validate độ dài, nhưng client thì không. Người dùng có thể nhập 1–2 ký tự và chỉ thấy lỗi sau submit.
• Edge case: chuỗi chỉ toàn khoảng trắng vẫn vượt len(displayName) nhưng trông rỗng. Trim trước khi validate.

Biến điều đó thành checklist:

• Tên nhất quán trên API, field DB và label UI.
• Kiểm tra phía client khớp với quy tắc server (min/max, required).
• Input được trim (và hành vi Unicode/emoji chấp nhận được).
• Thông báo lỗi rõ và đồng bộ giữa server và UI.

Kiểm tra nhanh, đo lường và bước tiếp theo

Một Claude Code PR review hiệu quả khi kết thúc bằng vài kiểm tra nhanh:

• Hành vi: người dùng thay đổi gì, và gì phải giữ nguyên
• Tests: đã bao phủ gì, thiếu gì, có flake không
• Logs và lỗi: thất bại rõ ràng và thông điệp hữu dụng
• Hiệu năng: vòng lặp mới, N+1 queries, payload lớn, cuộc gọi mạng thêm
• Bảo mật: validation, kiểm tra auth, secrets, mặc định rủi ro

Để xem nó có hiệu quả, theo dõi hai chỉ số đơn giản trong 2–4 tuần: thời gian review (từ mở tới review ý nghĩa đầu tiên, và từ mở tới merge) và sửa lại (commit follow-up sau review, hay bao nhiêu comment yêu cầu thay đổi mã).

Chuẩn hóa đánh bại prompt hoàn hảo. Chọn một template, yêu cầu một block ngắn ngữ cảnh (thay đổi gì, tại sao, cách test), và thống nhất thế nào là “xong”.

Nếu team bạn phát triển tính năng qua chat-based development, bạn có thể áp workflow tương tự trong Koder.ai: sinh thay đổi, xuất source, rồi đính kèm checklist pre-review vào PR để review con người vẫn tập trung vào phần rủi ro cao nhất.