Add and update CLAUDE.md and Code Review guidelines with consistent style

2026-06-23 15:40:24 +07:00
parent 771c1b3d66
commit f7992bfd71
2 changed files with 314 additions and 0 deletions
@@ -0,0 +1,199 @@
 # 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ả.
@@ -0,0 +1,115 @@
 # 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.*