# Quy Trình Code Review Với AI (Claude Code)

Tài liệu này hướng dẫn phương pháp sử dụng AI để tự rà soát mã nguồn (code review) trước khi gửi yêu cầu phê duyệt, tập trung vào việc tối ưu hóa độ chính xác và hạn chế tối đa các cảnh báo sai lệch.

---

## 1. Quy trình 3 bước (3-Gate Workflow)

Mục tiêu: Đảm bảo mã nguồn sạch trước khi bàn giao, giúp người phê duyệt tập trung vào kiến trúc và logic nghiệp vụ chính thay vì các lỗi cú pháp nhỏ.

```
Mã nguồn hoàn thiện
       │
       ▼
 [Gate 1] AI Review  ──►  Sửa lỗi
       │
       ▼
 [Gate 2] Tự rà soát  ──►  Sửa lỗi
       │
       ▼
 [Gate 3] Phê duyệt (Human Review)  ──►  Hợp nhất (Merge)
```

* **Gate 1 - AI Review:** Chạy lệnh `/code-review` trên nhánh hoặc PR hiện tại để phát hiện các lỗi cú pháp, lỗi logic hiển nhiên và vi phạm quy ước (conventions).
* **Gate 2 - Tự rà soát:** Lập trình viên tự kiểm tra lại mã nguồn hoặc chạy AI lần hai sau khi sửa đổi để đảm bảo không phát sinh lỗi mới.
* **Gate 3 - Phê duyệt (Human Review):** Người phê duyệt thực hiện đánh giá kiến trúc hệ thống, giải pháp thiết kế và tính đúng đắn về mặt nghiệp vụ.

---

## 2. Nguyên lý hoạt động của lệnh `/code-review`

Đây là plugin chính thức của Claude Code. Cơ chế cốt lõi là giới hạn phạm vi kiểm tra trong phạm vi thay đổi (git diff) của Pull Request thay vì toàn bộ mã nguồn, giúp hạn chế các cảnh báo ngoài phạm vi (out of scope).

Quy trình xử lý chi tiết:

1. **Sàng lọc:** Bỏ qua các PR nháp (draft), PR đã đóng, thay đổi không đáng kể hoặc đã được rà soát trước đó.
2. **Chuẩn bị ngữ cảnh:** Thu thập thông tin từ file `CLAUDE.md` liên quan và phần mô tả PR để hiểu rõ mục tiêu thay đổi.
3. **Phân tích song song:** Sử dụng các tác nhân độc lập để thực hiện hai nhiệm vụ:
   - Kiểm tra mức độ tuân thủ quy tắc (`CLAUDE.md` trong phạm vi thư mục).
   - Phát hiện lỗi logic, lỗ hổng bảo mật trực tiếp trên phần thay đổi (diff).
4. **Xác minh lỗi:** Một tác nhân khác sẽ kiểm tra chéo các vấn đề được phát hiện để đảm bảo tính chính xác.
5. **Loại bỏ cảnh báo sai:** Lọc và loại bỏ các lỗi không đủ độ tin cậy.
6. **Xuất kết quả:** Hiển thị trên terminal hoặc gửi phản hồi trực tiếp dưới dạng bình luận trên PR bằng tùy chọn `--comment`.

### Hướng dẫn sử dụng

```bash
# Hiển thị kết quả đánh giá trên terminal
/code-review

# Gửi kết quả đánh giá dưới dạng bình luận trên GitHub PR
/code-review --comment
```

*Yêu cầu hệ thống: Dự án sử dụng GitHub, đã cài đặt và cấu hình GitHub CLI (`gh auth login`), và đã thiết lập file `CLAUDE.md`.*

---

## 3. Cơ chế hạn chế cảnh báo sai lệch

Công cụ tích hợp 4 cơ chế chống lạc đề và báo lỗi ngoài phạm vi:

1. **Giới hạn phạm vi (Diff Lock):** Chỉ phân tích vùng mã nguồn có sự thay đổi, bỏ qua các lỗi cũ đã tồn tại trước đó.
2. **Nhận diện mục tiêu:** Đưa thông tin tiêu đề và mô tả của PR vào ngữ cảnh để AI hiểu rõ mục đích của các thay đổi.
3. **Phân cấp quy tắc:** Áp dụng file `CLAUDE.md` theo cấu trúc thư mục để đảm bảo các quy tắc nghiệp vụ chỉ có hiệu lực ở những khu vực phù hợp.
4. **Kiểm định hai lớp:** Kết hợp xác minh chéo giữa các tác nhân và áp dụng danh sách loại trừ cụ thể.

### Các trường hợp được bỏ qua (Không cảnh báo)

* Lỗi đã tồn tại từ trước trong hệ thống.
* Các đoạn mã nhìn giống lỗi nhưng thực tế hoạt động đúng theo thiết kế.
* Các góp ý nhỏ nhặt, mang tính chủ quan (nitpick).
* Lỗi đã được phát hiện bởi các công cụ linter.
* Vấn đề bảo mật hoặc chất lượng chung chung (trừ khi được quy định rõ trong `CLAUDE.md`).
* Các dòng mã đã có chú thích bỏ qua linter (lint-ignore).

> [!NOTE]
> **Ngưỡng độ tin cậy:** Chỉ báo cáo các vấn đề có độ chính xác cao (high-signal), ví dụ: lỗi cú pháp, lỗi biên dịch, logic gây sai lệch kết quả đầu ra, hoặc vi phạm trực tiếp các điều khoản ghi trong `CLAUDE.md`.

---

## 4. Tối ưu hóa chất lượng đánh giá

Chất lượng kết quả review phụ thuộc vào cách giới hạn ngữ cảnh:

* **Thiết lập `CLAUDE.md` đúng phân cấp:** Đặt các quy tắc vào đúng thư mục cần áp dụng để tránh chồng chéo (xem thêm [Hướng dẫn CLAUDE.md](file:///home/smartgiftailab/MyDrive/Projects/claude-code-docs/README-claude-md.md)).
* **Mã hóa logic nghiệp vụ rõ ràng:** Ghi lại các quy định nghiệp vụ đặc thù trong file quy tắc thay vì để AI tự suy luận.
* **Mô tả PR chi tiết:** Viết tiêu đề và nội dung PR rõ nghĩa để AI nắm bắt được mục đích.
* **Chia nhỏ PR:** Các PR có dung lượng thay đổi nhỏ giúp quá trình đánh giá nhanh và chính xác hơn.

---

## 5. Hướng dẫn áp dụng

**Nên thực hiện:**
* Duy trì và cập nhật liên tục file `CLAUDE.md`.
* Sử dụng kết quả review từ AI làm cơ sở tham khảo ban đầu trước khi rà soát thủ công.
* Thực hiện trên tất cả các PR quan trọng.

**Trường hợp không cần thiết:**
* PR nháp, PR đã đóng hoặc các thay đổi quá nhỏ (hệ thống sẽ tự động bỏ qua).
* Các bản vá khẩn cấp (hotfix) cần triển khai ngay.

---

## 6. So sánh với các công cụ khác

| Tiêu chí | Claude Code `/code-review` | Các công cụ điển hình khác (Cursor/Codex/Antigravity) |
|---|---|---|
| **Kiến trúc** | Nhiều tác nhân song song + tầng kiểm định | Thường là một lượt prompt trực tiếp trên diff |
| **Lọc cảnh báo sai** | Tầng validation riêng + danh sách loại trừ | Phụ thuộc vào prompt, ít tầng lọc |
| **Nguồn quy tắc** | `CLAUDE.md` phân cấp theo thư mục | Cấu hình quy tắc riêng của từng công cụ |
| **Phạm vi** | Giới hạn trong diff của PR | Tùy thuộc vào phương thức gọi |

> *Lưu ý: Bảng so sánh dựa trên nguyên lý thiết kế tại thời điểm hiện tại. Tính năng của các công cụ có thể thay đổi theo các phiên bản cập nhật.*