200 lines
8.9 KiB
Markdown
200 lines
8.9 KiB
Markdown
# 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ả.
|