Hướng dẫn cấu hình tệp CLAUDE.md

# Tên dự án

## Tổng quan dự án

[Mô tả ngắn gọn về mục đích dự án, chức năng cốt lõi và người dùng mục tiêu]

## Công nghệ sử dụng

- Frontend: [Framework và thư viện chính]
- Backend: [Ngôn ngữ và framework]
- Database: [Loại cơ sở dữ liệu]
- Deployment: [Nền tảng triển khai]

## Cấu trúc dự án

\```
project/
├── src/ # Mã nguồn
├── tests/ # Tệp kiểm thử
├── docs/ # Tài liệu
└── scripts/ # Tệp script
\```

## Quy tắc phát triển

[Quy tắc lập trình riêng cho dự án]

## Lưu ý

[Những lưu ý và giới hạn riêng cho dự án]

# CLAUDE.md - Tệp cấu hình dự án

## Quy tắc chung (tất cả dự án phải tuân thủ)

### Ngôn ngữ giao tiếp

- Luôn sử dụng tiếng Trung giản thể để suy nghĩ và đối thoại
- Chú thích mã sử dụng tiếng Anh, tài liệu sử dụng tiếng Trung

### Quản lý tài liệu

- Tài liệu chính thức ghi vào thư mục `docs/`
- Phương án thảo luận ghi vào thư mục `discuss/`
- README giữ ngắn gọn, tài liệu chi tiết lưu riêng

## Quy tắc kiến trúc mã

### Giới hạn kích thước tệp

- Python/JavaScript/TypeScript: mỗi tệp không quá 300 dòng
- Java/Go/Rust: mỗi tệp không quá 400 dòng
- Mỗi thư mục không quá 8 tệp
- Vượt quá giới hạn cần tái cấu trúc hoặc tách ra

### Chỉ số chất lượng mã

Tránh các code smell sau:

1. **Cứng nhắc**: Hệ thống khó thay đổi
2. **Dư thừa**: Quá nhiều mã lặp lại
3. **Phụ thuộc vòng tròn**: Các module phụ thuộc lẫn nhau
4. **Dễ vỡ**: Thay đổi gây ra vấn đề dây chuyền
5. **Mơ hồ**: Ý định của mã không rõ ràng
6. **Data clump**: Các mục dữ liệu luôn xuất hiện cùng nhau
7. **Thiết kế quá mức**: Độ phức tạp không cần thiết

## Ràng buộc công nghệ

### Công nghệ Frontend

- React 19+ (không sử dụng 18 hoặc thấp hơn)
- Next.js 15.4+ (không sử dụng 14 hoặc thấp hơn)
- Tailwind CSS v4 (không sử dụng v3)
- Ưu tiên TypeScript, tránh JavaScript
- Cấm sử dụng CommonJS, chỉ dùng ES Modules

### Công nghệ Backend

- Node.js 18+
- Sử dụng TypeScript
- Express/Fastify làm Web framework
- Prisma làm ORM

### Dự án Python

- Sử dụng uv để quản lý dependencies (không dùng pip/poetry/conda)
- Tên thư mục môi trường ảo: `.venv`
- Định nghĩa kiểu mạnh, tránh sử dụng dict
- Giữ thư mục gốc dự án gọn gàng

## Quy trình phát triển

### Quản lý script

- Tất cả script đặt trong thư mục `scripts/`
- Sử dụng script `.sh` để khởi động/dừng
- Không trực tiếp sử dụng lệnh npm/pnpm/python
- Lỗi script phải sửa ngay lập tức

### Quản lý log

- Xuất log từ tệp cấu hình
- Xuất thống nhất vào thư mục `logs/`
- Bao gồm timestamp và mức log
- Log lỗi lưu riêng

### Yêu cầu kiểm thử

- Độ bao phủ unit test > 80%
- Chức năng quan trọng phải có integration test
- Tệp test đặt trong thư mục `tests/`
- Sử dụng CI/CD tự động chạy test

## Quy tắc đặt tên

### Đặt tên tệp

- Component: PascalCase (như UserProfile.tsx)
- Hàm tiện ích: camelCase (như formatDate.ts)
- Tệp hằng số: UPPER_SNAKE_CASE (như API_CONSTANTS.ts)
- Tệp style: kebab-case (như user-profile.css)

### Đặt tên biến

- Biến/hàm: camelCase
- Hằng số: UPPER_SNAKE_CASE
- Class/interface: PascalCase
- Thuộc tính private: \_camelCase

## Quy trình Git

### Chiến lược nhánh

- main: mã môi trường production
- develop: mã môi trường development
- feature/\*: nhánh tính năng
- hotfix/\*: nhánh sửa lỗi khẩn cấp

### Quy tắc commit

- feat: tính năng mới
- fix: sửa lỗi
- docs: cập nhật tài liệu
- style: điều chỉnh định dạng mã
- refactor: tái cấu trúc mã
- test: liên quan đến test
- chore: thay đổi build/công cụ

## Quy tắc thiết kế API

### Nguyên tắc RESTful

- GET: lấy tài nguyên
- POST: tạo tài nguyên
- PUT: cập nhật tài nguyên (toàn bộ)
- PATCH: cập nhật tài nguyên (một phần)
- DELETE: xóa tài nguyên

### Định dạng phản hồi

\```json
{
"success": true,
"data": {},
"message": "操作成功",
"timestamp": "2024-01-01T00:00:00Z"
}
\```

### Xử lý lỗi

\```json
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "错误描述",
"details": {}
}
}
\```

## Quy tắc bảo mật

### Thông tin nhạy cảm

- Không hard-code khóa trong mã
- Sử dụng biến môi trường để quản lý cấu hình
- Tệp `.env` không commit vào Git
- Cập nhật dependencies định kỳ

### Xác thực dữ liệu

- Frontend và backend đều phải xác thực dữ liệu
- Sử dụng thư viện xác thực schema (như zod)
- Truy vấn SQL sử dụng tham số hóa
- Ngăn chặn tấn công XSS và CSRF

## Tối ưu hiệu suất

### Tối ưu Frontend

- Lazy loading hình ảnh
- Code splitting
- Chiến lược cache
- Virtual scrolling (danh sách lớn)

### Tối ưu Backend

- Tối ưu truy vấn database
- Sử dụng cache (Redis)
- Nén phản hồi API
- Kiểm soát đồng thời

## Cấu hình triển khai

### Biến môi trường

- development: môi trường phát triển
- staging: môi trường test
- production: môi trường sản xuất

### Container hóa

- Sử dụng Docker để triển khai
- Build đa giai đoạn để tối ưu kích thước image
- Sử dụng docker-compose để điều phối services

## Giám sát và Log

### Chỉ số giám sát

- Thời gian phản hồi API
- Tỷ lệ lỗi
- Tỷ lệ sử dụng tài nguyên
- Phân tích hành vi người dùng

### Mức log

- ERROR: thông tin lỗi
- WARN: thông tin cảnh báo
- INFO: thông tin chung
- DEBUG: thông tin debug

## Lưu ý đặc biệt

⚠️ **Nhắc nhở quan trọng**:

1. Phát hiện vấn đề mã ngay lập tức đề xuất
2. Không chắc chắn chủ động hỏi người dùng
3. Giữ mã sạch và dễ bảo trì
4. Tuân thủ quy tắc đã thiết lập của dự án

## Quy tắc dự án React/Next.js

### Quy tắc Component

- Sử dụng function component + Hooks
- Tệp component cùng tên với component
- Một tệp một component
- Props sử dụng interface TypeScript định nghĩa

### Quản lý state

- State đơn giản: useState
- State phức tạp: useReducer
- State toàn cục: Context API / Zustand
- State server: TanStack Query

### Phương án style

- Tailwind CSS v4 làm chính
- CSS Modules làm bổ sung
- Tránh inline style
- Ưu tiên responsive design

### Tối ưu hiệu suất

- Sử dụng React.memo tránh render không cần thiết
- useMemo/useCallback tối ưu tính toán
- Dynamic import thực hiện code splitting
- Hình ảnh sử dụng component next/image

## Quy tắc dự án Python

### Cấu trúc dự án

\```
project/
├── src/
│ ├── **init**.py
│ ├── main.py
│ ├── models/
│ ├── services/
│ └── utils/
├── tests/
├── .venv/
└── pyproject.toml
\```

### Quản lý dependencies

- Sử dụng uv quản lý tất cả dependencies
- pyproject.toml định nghĩa cấu hình dự án
- requirements.txt dùng cho triển khai production
- requirements-dev.txt dùng cho dependencies development

### Chú thích kiểu

- Tất cả hàm phải có chú thích kiểu
- Sử dụng dataclass định nghĩa cấu trúc dữ liệu
- Kết hợp mypy để kiểm tra kiểu
- Tránh sử dụng kiểu Any

### Lập trình bất đồng bộ

- Ưu tiên sử dụng async/await
- Sử dụng asyncio quản lý đồng thời
- Thao tác database sử dụng driver bất đồng bộ
- HTTP request sử dụng httpx

## Quy tắc kiến trúc Microservices

### Phân chia service

- Phân chia service theo domain nghiệp vụ
- Mỗi service triển khai độc lập
- Service giao tiếp qua API
- Mã chia sẻ thông qua quản lý package

### API Gateway

- Quản lý điểm vào thống nhất
- Xác thực và phân quyền
- Rate limiting và circuit breaking
- Định tuyến request

### Giao tiếp Service

- HTTP/REST: gọi đồng bộ
- Message queue: giao tiếp bất đồng bộ
- gRPC: kịch bản hiệu suất cao
- WebSocket: giao tiếp thời gian thực

### Quản lý dữ liệu

- Mỗi service database độc lập
- Tránh transaction cross-service
- Sử dụng event-driven duy trì tính nhất quán
- Triển khai thao tác idempotent

> /init