# Cách Review Code Với AI

Hướng dẫn cách dùng AI để **tự review code với AI trước khi tạo PR**, áp dụng cho mọi tool (Claude Code, Cursor, Codex, Copilot, Antigravity...). Tài liệu tập trung vào **cách làm và tư duy**, không phụ thuộc một công cụ cụ thể — vì nguyên tắc giống nhau ở tất cả, chỉ khác tên lệnh và file cấu hình.

---

## Mục lục
1. [Vấn đề: AI review nhưng vẫn sai](#1-van-de)
2. [Tư tưởng: Context tốt > Prompt tốt](#2-context-tot)
3. [AI Review Gate — review trước khi tạo PR](#3-ai-review-gate)
4. [File rules — bộ luật cho AI](#4-file-rules)
5. [Cách review đúng (5 nguyên tắc)](#5-cach-review-dung)
6. [Persona agents — nhiều agent thay vì một AI](#6-persona-agents)
7. [/code-review của Claude Code](#7-code-review)
8. [Các tool & cách kích hoạt](#8-cac-tool)
9. [Demo: Before vs After](#9-demo)
10. [Tóm lại](#10-tom-lai)

---

## 1. Vấn đề

Dùng AI hỗ trợ code lâu nay, nhưng kết quả thường lệch theo những kiểu quen thuộc:
 
* **Code sai yêu cầu** — tự suy diễn phần thiếu, làm lệch mục tiêu ban đầu.
* **Viết lại hàm đã có** — đẻ hàm mới trùng chức năng với hàm đã có.
* **Báo lỗi rác** — sai business logic, báo các lỗi không liên quan.
* **Không hỏi trước khi code** — lao vào làm ngay, không xác nhận ý định của người dùng.
> Gốc rễ: AI không thấy đúng thứ cần thấy, và không bị buộc dừng lại đúng lúc.

---

## 2. Context tốt > Prompt tốt

**Cùng một model — khác nhau ở cách mình đưa context và đóng khung bài toán trong câu lệnh.**

Lưu ý quan trọng: context tốt nghĩa là **ĐÚNG và SẠCH, không phải NHIỀU**. Nhồi cả repo còn làm AI loãng tín hiệu và dễ lạc đề hơn. Cả tài liệu này xoay quanh việc đưa context đúng cho việc review.

---

## 3. AI Review Gate

**Tư duy cốt lõi:** đặt một "AI Gate" xen giữa *code xong* và *tạo PR*. Mục tiêu là code sau phiên của bạn đã sạch, để người review chỉ tốn sức cho kiến trúc, business, đánh đổi thiết kế — chứ không phải dò lỗi vặt.

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:** soi diff để bắt lỗi logic, convention, hàm viết trùng.
* **Gate 2 – Tự review / AI Review lần 2:** review thủ công; hoặc chạy AI lại sau khi fix để chắc không phát sinh lỗi mới.
* **Gate 3 – Người khác review:** chỉ còn tập trung vào những thứ mà AI không đánh giá và review được.

**Vì sao đáng làm:** chi phí cho gate AI rất rẻ nhưng cắt được phần lớn vòng lặp "sếp comment → sửa → review lại".

> **Nguyên tắc số 1:** mỗi lần review một **phạm vi rõ ràng** (diff/commit/PR), không đổ cả repo vào. Phạm vi hẹp = AI chính xác, đỡ lạc đề, đỡ tốn token.

---

## 4. File rules — bộ handbook cho AI

**Tư duy cốt lõi:** AI review chỉ tốt khi có **chuẩn để đối chiếu và đánh giá**. File rules là nơi bạn thông tin, quy ước, business logic của dự án một lần rồi dùng về sau cho dự án đó, và cả team đều có thể sử dụng chung, không cần phải giải thích lại mỗi lần cho dự án.

Mỗi tool có file rules riêng, vai trò như nhau:

| Tool | File rules |
|------|-----------|
| Claude Code | `CLAUDE.md` |
| Cursor | `.cursor/rules/*.mdc` (hoặc `.cursorrules` cũ) |
| Codex (OpenAI) | `AGENTS.md` |
| Copilot / Gemini | cấu hình hướng dẫn repo của tool |

**Nên ghi gì:** quy ước code (naming, pattern, error handling), **business rules** (những logic AI không tự đoán được hoặc những đặc trưng riêng của doanh nghiệp), và liệt kê những viết nên làm và tuyệt đối không làm cụ thể, dứt khoát. Hoặc các hướng dẫn như luôn kiểm tra xem hàm trong diff có bị trùng chức năng với hàm đã có không. Phong cách code phải ngắn gọn, có thể tái sử dụng nhiều lần cho cả dự .

**Hai tư duy quan trọng:**
* **Bộ luật, không phải tài liệu:** giữ cho file luôn ngắn. File dài làm loãng context, khiến AI dễ bị sai.
* **Scope phân cấp:**
  * Rule cá nhân (dùng cho mọi project) → ở `.claude` (hoặc tương tự cho mỗi tool).
  * Rule chung → ở root dự án.
  * Rule riêng của từng module → ở thư mục con.

> Chi tiết cách viết & duy trì: xem tài liệu *Hướng dẫn viết & maintain các file AGENTS.md*.
---

## 5. Nhiều persona agent > một AI đơn lẻ
 
**Một AI không thể ôm hết context của dự án → phải chú ý dàn mỏng. Chia vai → mỗi agent đào sâu một lăng kính** (như một hội đồng review). Chọn persona theo loại thay đổi, không cần dùng hết:
 
| Persona | Soi gì |
|---------|--------|
| **Security** | Injection, phân quyền, secret, validate input |
| **Performance** | N+1 query, vòng lặp tốn kém, cache |
| **Maintainability** | Trùng lặp, đặt tên, độ phức tạp |
| **Business logic** | Khớp đúng yêu cầu/spec, edge case |
| **Test & reliability** | Coverage code mới, xử lý lỗi |
| **Tổng hợp & lọc** | Gom kết quả, loại trùng, xếp ưu tiên |
 
> **Cách làm:** Claude Code định nghĩa mỗi persona là subagent trong `.claude/agents/`; tool khác thì chạy nhiều lượt prompt theo persona. Sau cùng luôn có **bước tổng hợp** để gom/loại trùng. Lưu ý: tốn token hơn (dành cho PR quan trọng), và **đừng để agent vừa viết code tự review chính nó**.

---
 
## 6. 5 nguyên tắc để review chuẩn hơn
 
* **Học theo tư duy của sếp:** cung cấp rõ context cho AI trước khi bắt nó làm việc.
* **Khóa review vào diff:** AI chỉ soi phần code có thay đổi → không đụng lỗi cũ của người khác.
* **Cho biết ý định:** nói rõ PR này định làm gì → AI không bị đoán mò mục tiêu của mình.
* **Có các file rule đúng scope:** AI dựa vào thông tin có sẵn về dự án thay vì tự đoán mò.
* **Luôn kiểm tra kết quả review:** đừng tin tưởng, dựa dẫm hoàn toàn vào AI — phải luôn double check dù kết quả chạy được. AI rất hay lấp liếm kết quả bằng cách này hay cách khác.
> "Sai" gồm hai kiểu cần chặn: **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).


---
 
## 7. /code-review của Claude Code
 
Pipeline có **kiến trúc multi-agent + tầng kiểm định** — chính là tư duy persona agent ở mục 5 đã được làm sẵn:
 
```
Sàng lọc → Ngữ cảnh (CLAUDE.md) → Multi-agent song song → Kiểm định lại issue → Lọc false positive → Kết quả
```
 
> Nó **cố tình khóa vào diff**, đối chiếu `CLAUDE.md` theo scope, và **kiểm định lại từng issue** → chỉ giữ lỗi chắc chắn, ít false positive.
 
---
 
## 8. Review với các tool khác
 
Nguyên tắc giống nhau — khác tên lệnh & file rules:
 
| Tool | File rules | Kích hoạt review |
|------|-----------|------------------|
| Claude Code | `CLAUDE.md` | `/code-review` hoặc hỏi agent |
| Cursor | `.cursor/rules/*.mdc` | `/bugbot` hoặc hỏi agent trong editor |
| Codex (OpenAI) | `AGENTS.md` | `/review` của Codex hoặc hỏi agent |
| GitHub Copilot | cấu hình repo | Copilot review trên PR |
| Antigravity (Google) | `gemini.md` | agent-first, tự review |
 
> ⚠️ Các tính năng của tools bây giờ phát triển rất nhanh — mình cần theo dõi, đọc docs và patch notes để cập nhật.
 
---

## 9. Tóm lại
 
Chất lượng review quyết định bởi 3 điều:
 
1. **Gate trước khi tạo PR** — dùng AI Review TRƯỚC khi tạo PR.
2. **File rules tốt** — bộ quy ước, thông tin ngắn, đúng scope, có business logic.
3. **Ép AI review đúng** — 5 nguyên tắc + dùng nhiều persona agent.
> **"Cùng một model, khác ở cách đưa AI context để xử lý vấn đề."**
