Đổi tên các file hướng dẫn sang Tiếng Việt

2026-06-25 15:46:34 +07:00
parent f7992bfd71
commit 7f99c55963
4 changed files with 204 additions and 314 deletions
@@ -0,0 +1,111 @@
 # 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.
@@ -0,0 +1,93 @@
 # Hướng Dẫn Viết & Duy Trì CLAUDE.md
 `CLAUDE.md` là **bộ luật ngắn gọn** Claude Code nạp vào context khi làm việc. Nó quyết định Claude hiểu dự án đến đâu và là nguồn rule chính cho `/code-review`. Nguyên tắc số một: đây là **bộ luật, không phải tài liệu** — mỗi dòng thừa làm loãng tín hiệu và khiến AI dễ lạc đề.
 ---
 ## Mục lục
 1. [Ba loại CLAUDE.md — đặt ở đâu, dùng cho gì](#1-ba-loai-claudemd)
 2. [Phân cấp & scope](#2-phan-cap--scope)
 3. [Cấu trúc chuẩn (8 phần)](#3-cau-truc-chuan-8-phan)
 4. [Tự động cập nhật (ít sửa tay)](#4-tu-dong-cap-nhat)
 5. [Cập nhật thủ công](#5-cap-nhat-thu-cong)
 ---
 ## 1. Ba loại CLAUDE.md
 | Loại | Vị trí | Phạm vi | Theo git? |
 |------|--------|---------|-----------|
 | **Cá nhân (global)** | `~/.claude/CLAUDE.md` | Mọi dự án trên máy bạn | Không |
 | **Dự án (root)** | `./CLAUDE.md` (gốc repo) | Cả dự án đó | Có (cả team thấy) |
 | **Thư mục con** | `<module>/CLAUDE.md` | Chỉ code trong thư mục đó | Có |
 ### a) Cá nhân — `~/.claude/CLAUDE.md`
 * **Dùng cho:** phong cách & nguyên tắc làm việc của *riêng bạn*, áp cho mọi dự án (ví dụ: nguyên tắc Karpathy, "ưu tiên dùng skill", "lập kế hoạch & hỏi trước khi code").
 * **KHÔNG để:** lệnh build/test hay business rule riêng của một dự án — vì nó áp cho tất cả.
 * **Lưu ý:** chỉ tồn tại trên máy bạn, không đi theo repo nên đồng đội không thấy.
 ### b) Dự án — `./CLAUDE.md` ở gốc repo
 * **Dùng cho:** mọi thứ thuộc về dự án — tổng quan, lệnh build/test/lint, convention, **business rules**, do/don't.
 * **Đặt ở gốc repo** (không phải trong `.claude/`), được commit nên cả team clone về là có.
 * Đây là vị trí **chắc chắn được nạp** và quan trọng nhất cho chất lượng `/code-review`.
 ### c) Thư mục con — `<module>/CLAUDE.md`
 * **Dùng cho:** rule chỉ đúng cho một phần (ví dụ `src/payment/CLAUDE.md`: rule về idempotency, xử lý refund).
 * **Vì sao quan trọng:** `/code-review` chỉ áp rule có **cùng path hoặc thư mục cha** của file đang xét. Đặt rule đúng chỗ → review đúng trọng tâm, không lôi rule chỗ khác vào.
 > Lưu ý về `.claude/` trong dự án: thư mục này chứa `settings.json`, `commands/`, `agents/` — **không** phải nơi để file memory. File memory của dự án để ở **gốc repo** (`./CLAUDE.md`). Vị trí global đáng tin là `~/.claude/CLAUDE.md` (trong home).
 > Các file được **cộng dồn**: khi làm trong một thư mục con, Claude nạp đồng thời CLAUDE.md cá nhân + gốc dự án + thư mục con.
 ---
 ## 2. Phân cấp & scope
 * **Rule chung** → gốc repo (`./CLAUDE.md`).
 * **Rule riêng module** → `<module>/CLAUDE.md`. Đừng nhồi hết vào root.
 * **Rule cá nhân, mọi dự án** → `~/.claude/CLAUDE.md`.
 * `/code-review` xét rule theo **scope phân cấp** — đặt sai chỗ thì hoặc bị bỏ qua, hoặc áp nhầm sang code không liên quan.
 ---
 ## 3. Cấu trúc chuẩn (8 phần)
 Phần 1, 2, 4, 5, 6 là cốt lõi; 3, 7 tùy dự án; 8 tự lớn theo thời gian. (File **cá nhân** chủ yếu dùng phần 4 + 6; file **dự án** dùng đủ; file **thư mục con** chỉ phần liên quan module.)
 * **[1] Tổng quan dự án** *(bắt buộc):* tên, mô tả ngắn, tech stack, env. 3–5 dòng.
 * **[2] Lệnh hay dùng** *(bắt buộc):* build / test / lint / dev / deploy — để Claude chạy đúng thay vì đoán.
 * **[3] Cấu trúc thư mục** *(tùy chọn):* chỉ ghi thư mục dễ nhầm (ví dụ: logic ở `services/`, không ở `api/`).
 * **[4] Quy ước code** *(bắt buộc):* naming, pattern, error handling — những rule linter không bắt được.
 * **[5] Business rules** *(bắt buộc):* logic nghiệp vụ AI không thể tự đoán (ví dụ: không cancel order đã "shipped"). **Quan trọng nhất để /code-review không báo sai.**
 * **[6] Do / Don't** *(bắt buộc):* dạng cấm rõ ràng, ngắn, dứt khoát (ví dụ: KHÔNG commit `.env`).
 * **[7] References** *(tùy chọn):* import file ngoài bằng `@docs/....md` để giữ file chính gọn.
 * **[8] Learned patterns** *(tự cập nhật):* phần Claude tự ghi sau mỗi phiên, kèm ngày.
 > Mẹo giữ gọn: phần dài thì tách ra file riêng rồi `@import` (ví dụ `@KarpathyCodeGuidelines.md`). Dùng import cho cả file cá nhân lẫn dự án.
 > Thứ tự viết lần đầu: làm 1, 2, 6 trước (~30 phút), rồi bổ sung 4, 5 dần theo lúc thấy Claude làm sai. Không cần hoàn hảo ngay.
 ---
 ## 4. Tự động cập nhật
 Claude Code **không** tự viết lại CLAUDE.md hoàn toàn — và đó là điều tốt, vì file tự phình rác sẽ làm hỏng `/code-review`. Mục tiêu là *gần như không phải sửa tay*:
 * **Phím `#` (ít ma sát nhất):** gõ tin nhắn bắt đầu bằng `#`, ví dụ `# luôn dùng dayjs thay vì moment` → Claude tự ghi vào memory và hỏi bỏ vào file nào (cá nhân / dự án / thư mục con).
 * **Lệnh `/update-memory` (tự tạo):** tạo `.claude/commands/update-memory.md` yêu cầu Claude rà `git log` + phiên gần đây, đề xuất rule high-signal cho bạn duyệt. Chạy cuối ngày hoặc sau mỗi feature.
 * **Hook (tùy chọn):** gắn hook sự kiện `Stop` để *nhắc* cập nhật. ⚠️ Đừng để hook tự ghi không qua duyệt — dễ tạo vòng lặp và làm file rác.
 ---
 ## 5. Cập nhật thủ công
 * **`/init`:** quét codebase sinh CLAUDE.md nháp. Nếu đã có file, nó **bổ sung chứ không ghi đè**, nhưng có thể sắp xếp lại — nên `git commit` trước khi chạy để dễ rollback. Hợp cho lúc khởi tạo / làm mới toàn diện.
 * **`/memory`:** liệt kê các file memory và mở ra sửa trực tiếp; dùng khi muốn dọn/sắp xếp lại.
 * **Sửa file như thường:** CLAUDE.md chỉ là markdown — mở editor sửa, lưu, lần sau Claude tự đọc lại (không cần restart).
 * **Giữ gọn:** thêm rule mới thì xóa rule lỗi thời; mỗi rule một dòng; phần dài thì tách file rồi `@import`.
 > Quy trình khuyên dùng: `/init` (1 lần) → dùng `#` bắt rule trong lúc làm → chạy `/update-memory` định kỳ & duyệt.
 > Lưu ý về session dài: context đầy dần sẽ làm rule bị "loãng" và Claude dễ quên — chia nhỏ session (`/clear` sau mỗi task) và giữ file ngắn giúp rule "nặng ký" hơn.
 > Chi tiết sản phẩm có thể thay đổi theo phiên bản — đối chiếu tại https://docs.claude.com/en/docs/claude-code/overview
@@ -1,199 +0,0 @@
 # Hướng Dẫn Viết & Duy Trì CLAUDE.md
 `CLAUDE.md` là bộ quy tắc ngắn gọn được nạp vào mọi ngữ cảnh (context) khi làm việc với Claude Code. Đây là cơ sở để Claude hiểu dự án và là nguồn quy tắc chính cho lệnh `/code-review`.
 > [!IMPORTANT]
 > CLAUDE.md là bộ quy tắc thực thi, không phải tài liệu hướng dẫn thông thường. Mỗi dòng thừa đều làm loãng ngữ cảnh và tăng tỷ lệ cảnh báo sai (false positive). Cần giữ file luôn ngắn gọn và súc tích.
 ---
 ## 1. Cấu trúc CLAUDE.md chuẩn
 Cấu trúc chuẩn của một file `CLAUDE.md` bao gồm 8 phần. Trong đó, các phần 1, 2, 4, 5, 6 là bắt buộc; các phần 3, 7 là tùy chọn; phần 8 tự động cập nhật theo thời gian.
 ### [1] Tổng quan dự án (Bắt buộc)
 Cung cấp thông tin ngắn gọn (khoảng 3–5 dòng) về loại dự án, công nghệ sử dụng và môi trường hoạt động.
 ```markdown
 # [Tên dự án]
 [Mô tả ngắn: mục tiêu dự án]
 Tech stack: [ngôn ngữ, framework, DB, cloud...]
 Team size: [số người] | Env: [dev/staging/prod]
 ```
 ### [2] Các lệnh thông dụng (Bắt buộc)
 Định nghĩa các lệnh thực thi cơ bản để AI có thể chạy trực tiếp thay vì tự suy đoán.
 ```markdown
 ## Commands
 Build:   npm run build
 Test:    npm test -- --coverage
 Lint:    npm run lint
 Dev:     npm run dev
 Deploy:  ./scripts/deploy.sh [env]
 ```
 ### [3] Cấu trúc thư mục (Tùy chọn)
 Chỉ áp dụng khi dự án có cấu trúc thư mục đặc thù hoặc dễ gây nhầm lẫn.
 ```markdown
 ## Structure
 src/
  api/        # route handlers, no business logic
  services/   # business logic
  models/     # DB models (Prisma)
  utils/      # pure functions, no side effects
 tests/        # mirror src/ structure
 ```
 ### [4] Quy ước lập trình (Bắt buộc)
 Quy định các quy tắc viết mã nguồn mà các công cụ kiểm tra lỗi tự động (linter) không thể phát hiện.
 ```markdown
 ## Conventions
 Naming:
 - camelCase đối với function, PascalCase đối với class
 - Tiền tố hook: "use" (ví dụ: useAuth, useCart)
 - Tiền tố boolean: "is/has" (ví dụ: isLoading, hasError)
 Patterns:
 - Xác thực đầu vào (validation) tại Service layer, không thực hiện tại Controller
 - Sử dụng thư viện dayjs thay vì moment hoặc date-fns
 - Tránh sử dụng kiểu dữ liệu `any` trong TypeScript, thay bằng `unknown` nếu cần
 Error handling:
 - Thực hiện ghi log trước khi ném ra lỗi (throw error)
 - Sử dụng class AppError(message, statusCode) cho các lỗi HTTP
 ```
 ### [5] Quy tắc nghiệp vụ (Business Rules - Bắt buộc)
 Chứa các logic nghiệp vụ đặc thù mà AI không thể tự suy luận từ mã nguồn. Đây là cơ sở quan trọng nhất để tránh các lỗi cảnh báo sai khi chạy `/code-review`.
 ```markdown
 ## Business rules
 Auth:
 - Người dùng chưa xác thực email chỉ có quyền đọc (read-only)
 - JWT hết hạn sau 15 phút, refresh token hết hạn sau 7 ngày
 Order:
 - Không được phép hủy đơn hàng đã chuyển sang trạng thái "shipped"
 - Mỗi mã giảm giá chỉ áp dụng tối đa 1 lần / người dùng / chiến dịch
 Payment:
 - Đảm bảo tính nhất quán (idempotent) bằng cách sử dụng idempotency-key trên mọi yêu cầu thanh toán
 - Xử lý hoàn tiền dưới dạng không đồng bộ (async) qua hàng đợi (queue)
 ```
 ### [6] Nên / Không nên (Do / Don't - Bắt buộc)
 Danh sách các hành động được khuyến khích hoặc nghiêm cấm cụ thể.
 ```markdown
 ## Do / Don't
 DO:
 - Viết unit test cho tất cả các hàm tại Service layer
 - Sử dụng cơ chế transaction khi cập nhật nhiều bảng cơ sở dữ liệu cùng lúc
 - Đặt tên file migration theo định dạng timestamp: 20240101_add_col.sql
 DON'T:
 - Không commit các file chứa cấu hình nhạy cảm (.env, khóa bảo mật)
 - Không sử dụng console.log trong môi trường production (thay thế bằng thư viện logger)
 - Không gọi trực tiếp API bên ngoài từ Model layer
 ```
 ### [7] Tài liệu tham chiếu ngoài (Tùy chọn)
 Liên kết đến các tài liệu chi tiết khác bằng ký tự `@` để giữ cho file `CLAUDE.md` luôn ngắn gọn.
 ```markdown
 ## References
@docs/api-conventions.md
@docs/db-schema.md
@.github/CONTRIBUTING.md
 ```
 ### [8] Learned Patterns (Tự động cập nhật)
 Phần ghi nhận các mẫu hành vi tự học được sau mỗi phiên làm việc. Phần này được cập nhật tự động khi chạy lệnh `/update-memory`.
 ```markdown
 ## Learned patterns
 - [2024-06-10] Sử dụng zod để kiểm tra dữ liệu đầu vào (đã sửa đổi 3 lần)
 - [2024-06-12] Định dạng khóa Redis: "{entity}:{id}:{field}"
 - [2024-06-14] Sử dụng Playwright cho kiểm thử E2E, không dùng Jest cho trình duyệt
 ```
 ---
 ## 2. Phân cấp và phạm vi áp dụng
 File `CLAUDE.md` có thể được thiết lập ở nhiều cấp độ khác nhau để áp dụng cho các phạm vi tương ứng:
 | File | Phạm vi áp dụng |
 |---|---|
 | `/CLAUDE.md` | Áp dụng cho toàn bộ dự án (đặt ở thư mục gốc) |
 | `/[thư-mục]/CLAUDE.md` | Chỉ áp dụng cho mã nguồn nằm trong thư mục đó |
 | `~/.claude/CLAUDE.md` | Quy tắc cá nhân, áp dụng toàn cục trên thiết bị |
 > [!NOTE]
 > Lệnh `/code-review` chỉ áp dụng các quy tắc nằm trong cùng thư mục hoặc thư mục cha của file đang được kiểm tra. Tránh đặt các quy tắc đặc thù của dự án vào file cấu hình cá nhân toàn cục (`~/.claude/CLAUDE.md`).
 ---
 ## 3. Khởi tạo nhanh
 Chạy lệnh sau trong Claude Code để tự động quét mã nguồn và tạo bản nháp `CLAUDE.md`:
 ```bash
 /init
 ```
 *Lưu ý: Cần rà soát và lược bỏ các nội dung thừa sau khi khởi tạo để đảm bảo file luôn tinh gọn.*
 ---
 ## 4. Cơ chế cập nhật tự động
 Việc cập nhật cần có sự kiểm soát của lập trình viên để tránh file bị phình to hoặc chứa thông tin rác, ảnh hưởng đến chất lượng review.
 * **Ghi nhớ nhanh bằng ký tự `#`:** Gõ tin nhắn bắt đầu bằng dấu `#` (ví dụ: `# luôn dùng dayjs thay vì moment`). AI sẽ tự động ghi nhớ và gợi ý vị trí lưu trữ phù hợp.
 * **Sử dụng lệnh `/update-memory` định kỳ:**
  Tạo file cấu hình `.claude/commands/update-memory.md` để tự động hóa quy trình rà soát lịch sử git và đề xuất cập nhật CLAUDE.md:
  ```markdown
  ---
  description: Rà soát phiên gần đây và cập nhật CLAUDE.md
  allowed-tools: Bash(git log:*), Bash(git diff:*), Read, Edit
  ---
  Cập nhật bộ nhớ dự án (CLAUDE.md) dựa trên những gì vừa học được.
  1. Đọc CLAUDE.md hiện tại (gốc + các thư mục liên quan).
  2. Xem `git log --oneline -20` và diff gần đây để nắm thay đổi mới.
  3. Rà lại phiên này để phát hiện các quy ước mới, lệnh build/test mới, hoặc quy tắc nghiệp vụ mới xuất hiện.
  4. Chỉ đề xuất quy tắc có giá trị cao (high-signal), lặp lại nhiều lần.
  5. Đặt mỗi quy tắc vào đúng file CLAUDE.md theo phạm vi thư mục.
  6. Hiển thị danh sách đề xuất thay đổi để phê duyệt trước khi ghi đè.
  7. Giữ file CLAUDE.md luôn ngắn gọn.
  ```
  Chạy lệnh `/update-memory` sau mỗi tính năng hoặc cuối ngày để duyệt các thay đổi.
 ⚠️ **Lưu ý:** Không tự động hóa hoàn toàn việc ghi đè file `CLAUDE.md` thông qua các hook sự kiện (như `Stop`) để tránh lỗi đệ quy hoặc ghi các thông tin không chính xác.
 ---
 ## 5. Cập nhật thủ công
 * **Sử dụng lệnh `/memory`:** Liệt kê và mở trực tiếp các file quy tắc để chỉnh sửa hoặc sắp xếp lại.
 * **Chỉnh sửa trực tiếp:** File `CLAUDE.md` là định dạng Markdown thông thường, có thể chỉnh sửa bằng bất kỳ trình soạn thảo nào. Thay đổi sẽ có hiệu lực ngay lập tức trong phiên làm việc tiếp theo của Claude Code.
 * **Nguyên tắc duy trì:**
  - Loại bỏ các quy tắc lỗi thời khi thêm quy tắc mới.
  - Định nghĩa ngắn gọn, mỗi quy tắc nằm trên một dòng riêng biệt.
  - Tách các nội dung dài thành file riêng và tham chiếu bằng cú pháp `@docs/...`.
 ---
 ## 6. Quy trình khuyến nghị
 ```
 Khởi tạo (/init)  ──►  Ghi nhận nhanh (#)  ──►  Rà soát & Duyệt (/update-memory)
 ```
 Quy trình này giúp giữ file `CLAUDE.md` luôn tinh gọn dưới sự kiểm soát của lập trình viên, đảm bảo lệnh `/code-review` hoạt động chính xác và hiệu quả.
@@ -1,115 +0,0 @@
 # 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.*