feat: add AI code review documentation, demonstration project, and update guidelines

Cach-Review-Code-Voi-AI.md

@@ -1,25 +1,46 @@
 # 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.
+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. [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. [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. AI Review Gate
+## 1. Vấn đề
 
-Đặt một cổng AI giữa "code xong" và "tạo PR".
+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.
 
-* **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.
+---
+
+## 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:
 
@@ -27,85 +48,103 @@ 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.
+* **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.
 
-> **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.
+**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.
 
 ---
 
-## 2. File rules
+## 4. File rules — bộ handbook cho AI
 
-Mã hóa convention + business logic vào một file, dùng lại ở mọi session.
+**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.
 
-* **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.
+Mỗi tool có file rules riêng, vai trò như nhau:
 
-**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 |
+| Tool | File rules |
+|------|-----------|
 | Claude Code | `CLAUDE.md` |
-| Cursor | `.cursor/rules/*.mdc` (Project Rules; `.cursorrules` là bản cũ) |
+| Cursor | `.cursor/rules/*.mdc` (hoặc `.cursorrules` cũ) |
 | Codex (OpenAI) | `AGENTS.md` |
-| Copilot / Gemini | file hướng dẫn repo của tool |
+| Copilot / Gemini | cấu hình 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ê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ự .
 
-**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*.
+**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*.
 ---
 
-## 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.
+## 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).
 
-## 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.
 
+---
+ 
+## 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.
+ 
 ---
 
-## 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.
+## 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 đề."**