112 lines
7.0 KiB
Markdown
112 lines
7.0 KiB
Markdown
# Cách Review Code Với AI
|
||
|
||
Hướng dẫn dùng AI tự review code trước khi giao cho người khác. Áp dụng cho mọi tool (Claude Code, Cursor, Codex, Copilot, Antigravity). Nguyên tắc chung như nhau, chỉ khác tên lệnh và file cấu hình.
|
||
|
||
---
|
||
|
||
## Mục lục
|
||
1. [AI Review Gate — review trước khi tạo PR](#1-ai-review-gate)
|
||
2. [File rules — bộ luật cho AI](#2-file-rules)
|
||
3. [Cách review đúng (không bị sai)](#3-cach-review-dung)
|
||
4. [Mẹo & tư duy khi review](#4-meo--tu-duy)
|
||
5. [Các tool & cách kích hoạt](#5-cac-tool)
|
||
|
||
---
|
||
|
||
## 1. AI Review Gate
|
||
|
||
Đặt một cổng AI giữa "code xong" và "tạo PR".
|
||
|
||
* **Trước:** code xong đẩy thẳng PR → người review gánh cả lỗi vặt lẫn lỗi logic → nhiều vòng comment–sửa.
|
||
* **Sau:** AI quét diff trước, lỗi rõ ràng được sửa ngay → người review chỉ còn xét kiến trúc & business.
|
||
* **Lợi ích:** giảm vòng lặp review, rút ngắn thời gian merge, người review dành sức cho việc giá trị cao.
|
||
|
||
Quy trình 3 gate:
|
||
|
||
```
|
||
Code xong → [Gate 1] AI review → Fix → [Gate 2] Tự review / AI review lần 2 → Fix → [Gate 3] Người review → Fix & merge
|
||
```
|
||
|
||
* **Gate 1 – AI review:** quét diff/commit, bắt lỗi logic, cú pháp, vi phạm convention, hàm viết trùng.
|
||
* **Gate 2 – Tự review / AI lần 2:** đọc lại bằng mắt người; hoặc chạy AI lại sau khi fix để chặn lỗi mới phát sinh.
|
||
* **Gate 3 – Người review:** chỉ còn xử lý cái máy không phán được.
|
||
|
||
> **Nguyên tắc nền:** mỗi lần review một phạm vi rõ ràng (diff/commit/PR), không đổ cả repo. Phạm vi hẹp = chính xác hơn, ít lạc đề, ít tốn token.
|
||
|
||
---
|
||
|
||
## 2. File rules
|
||
|
||
Mã hóa convention + business logic vào một file, dùng lại ở mọi session.
|
||
|
||
* **Trước:** mỗi session phải giải thích lại convention; AI tự đoán business logic → code sai yêu cầu, viết hàm trùng chức năng.
|
||
* **Sau:** rule nằm sẵn trong file, nạp tự động mỗi lần; AI bám chuẩn dự án.
|
||
* **Lợi ích:** hết lặp lại chỉ dẫn; đề xuất khớp codebase ngay lần đầu; giảm sửa đi sửa lại.
|
||
|
||
**Xu hướng hiện tại — hội tụ về một chuẩn chung:** `AGENTS.md` là định dạng mở, ví như "README cho agent", được nhiều coding agent cùng đọc. Một `AGENTS.md` thay cho nhiều file riêng lẻ.
|
||
|
||
| Phạm vi | File rules |
|
||
|---------|-----------|
|
||
| Chuẩn chung (nhiều agent) | `AGENTS.md` — định dạng mở, đa tool |
|
||
| Claude Code | `CLAUDE.md` |
|
||
| Cursor | `.cursor/rules/*.mdc` (Project Rules; `.cursorrules` là bản cũ) |
|
||
| Codex (OpenAI) | `AGENTS.md` |
|
||
| Copilot / Gemini | file hướng dẫn repo của tool |
|
||
|
||
> Hợp nhất nhiều tool: giữ một `AGENTS.md` làm nguồn chân lý, cho file riêng của tool trỏ tới (symlink hoặc `@import` `CLAUDE.md` → `AGENTS.md`) — mức hỗ trợ tùy tool, cần kiểm tra.
|
||
|
||
**Nội dung nên có:** quy ước code (naming, pattern, error handling), business rules (logic AI không tự đoán được), do/don't dứt khoát. Loại bỏ thứ hiển nhiên hoặc linter tự bắt.
|
||
|
||
**Hai nguyên tắc:**
|
||
* **Bộ luật, không phải tài liệu:** giữ ngắn. File dài làm loãng tín hiệu, tăng báo sai.
|
||
* **Scope phân cấp:** rule chung ở gốc repo; rule riêng module ở thư mục con. AI áp đúng rule cho đúng vùng code → review đúng trọng tâm.
|
||
|
||
> Chi tiết viết & duy trì file rules: xem *Hướng Dẫn Viết & Duy Trì CLAUDE.md*.
|
||
|
||
---
|
||
|
||
## 3. Cách review đúng
|
||
|
||
"Sai" gồm hai kiểu: **lạc trọng tâm** (báo lỗi ngoài phần đang làm) và **báo lỗi không đúng** (false positive, hiểu sai business logic).
|
||
|
||
* **Trước:** AI soi cả code cũ, hiểu sai ý định thay đổi, đẩy ra hàng loạt false positive → báo cáo mất niềm tin, tốn công sàng lọc.
|
||
* **Sau:** chỉ còn lỗi high-signal, đúng phạm vi, đúng business.
|
||
* **Lợi ích:** báo cáo đáng tin, dùng được ngay; thời gian dồn vào sửa lỗi thật.
|
||
|
||
Năm điều kiện cần đảm bảo — đúng cho mọi tool:
|
||
|
||
* **Khóa review vào diff:** chỉ soi code vừa thay đổi → bỏ lỗi pre-existing của người khác.
|
||
* **Cung cấp ý định:** ghi rõ title/description hoặc mục tiêu thay đổi → không báo ngược lại điều cố tình làm.
|
||
* **File rule đúng scope:** AI dựa vào sự thật dự án thay vì đoán → tránh báo sai convention/business.
|
||
* **Lọc false positive:** yêu cầu chỉ báo lỗi chắc chắn; bỏ nitpick, lỗi linter tự bắt, vấn đề chung chung trừ khi rule yêu cầu.
|
||
* **Ngưỡng tin cậy cao:** thà bỏ sót vài lỗi nhỏ còn hơn ngập báo cáo sai.
|
||
|
||
> Một số tool (ví dụ `/code-review` của Claude Code) cài sẵn các cơ chế này: khóa diff, kiểm định lại từng issue, danh sách "không flag". Tool chưa có thì đưa các yêu cầu trên vào prompt hoặc file rules.
|
||
|
||
---
|
||
|
||
## 4. Mẹo & tư duy
|
||
|
||
* **Chia PR nhỏ:** diff gọn → review chính xác, nhanh. PR lớn làm loãng tín hiệu.
|
||
* **Review bằng subagent độc lập:** agent vừa viết code thường thiên vị, mặc định code mình đúng. Dùng subagent "reviewer" riêng (Claude Code: `.claude/agents/`; Cursor/Codex có cơ chế tương tự) hoặc session mới để có góc nhìn khách quan.
|
||
* **Kết quả AI là điểm khởi đầu, không phải phán quyết:** vẫn cần mắt người ở Gate 2.
|
||
* **Audit toàn cục khác review diff:** kiểm tra tính đồng bộ module/UI/DB cần chia theo từng mối quan tâm, cấp "bản đồ" kiến trúc trước, dùng subagent riêng theo lăng kính (DB, UI, API) — không soi cả source một lần.
|
||
* **Rule "luôn áp dụng" để trong file rules, không để trong prompt:** prompt dễ trôi trong session dài; file rules nạp lại mỗi lần.
|
||
|
||
---
|
||
|
||
## 5. Các tool
|
||
|
||
| Tool | Kích hoạt review |
|
||
|------|------------------|
|
||
| Claude Code | `/code-review` (PR/diff; multi-agent + lọc false positive) |
|
||
| Cursor | Bugbot (review PR trên GitHub) hoặc agent review trong editor |
|
||
| Codex (OpenAI) | tính năng review của Codex; đọc `AGENTS.md` |
|
||
| GitHub Copilot | Copilot code review trên Pull Request |
|
||
| Gemini Code Assist | review PR tự động trên GitHub |
|
||
| Antigravity (Google) | IDE agent-first — giao agent tự review |
|
||
|
||
**Khác biệt chính:** đa số tool chạy một lượt prompt trên diff; Claude Code có kiến trúc multi-agent + tầng kiểm định để lọc false positive. Dù tool nào, chất lượng review vẫn quyết định bởi ba yếu tố: gate đúng lúc, file rules tốt, ép review đúng.
|
||
|
||
> ⚠️ Tính năng và tên lệnh các tool thay đổi nhanh, một số mới hơn mốc kiến thức tài liệu (đặc biệt Cursor Bugbot, Codex, Antigravity) — kiểm chứng tại trang chính thức trước khi trình bày.
|