Kỹ Thuật Thiết Kế File .cursorrules Chuẩn Enterprise: Biến Cursor Thành Cỗ Máy Tuân Thủ Kiến Trúc | DevPrompt Lab

Mẫu cấu hình .cursorrules hoàn chỉnh cho dự án TypeScript / Next.js giúp toàn bộ team 50 engineers đồng nhất phong cách code.

Kỹ Thuật Thiết Kế File .cursorrules Chuẩn Enterprise: Biến Cursor Thành Cỗ Máy Tuân Thủ Kiến Trúc

File `.cursorrules` đặt tại thư mục gốc của dự án chính là "bản hiến pháp" mà Cursor AI Composer luôn đọc trước tiên khi thực hiện bất kỳ lệnh nào. Nếu không có file này, AI sẽ sinh code theo thói quen mặc định trên internet, dẫn đến tình trạng: một file viết functional, file khác viết class; chỗ dùng Axios, chỗ dùng Fetch.

---

Cấu Trúc File .cursorrules Mẫu Hoàn Chỉnh

# .cursorrules - Production Next.js 15 & TypeScript Enterprise Standards

## 1. VAI TRÒ & NGUYÊN TẮC CỐT LÕI
- Bạn là Principal Frontend Architect. Trả lời súc tích, đi thẳng vào giải pháp code, không giải thích dài dòng.
- Luôn ưu tiên: Type-safety tuyệt đối, hiệu năng render 60fps, accessibility WCAG AA.

## 2. QUY ĐỊNH BẮT BUỘC VỀ TYPESCRIPT
- Nghiêm cấm sử dụng kiểu 'any'. Luôn bật 'strict: true' và 'noUncheckedIndexedAccess'.
- Khi xử lý dữ liệu từ API bên ngoài, BẮT BUỘC dùng thư viện Zod để validate runtime schema.

## 3. KIẾN TRÚC REACT & NEXT.JS APP ROUTER
- Mặc định toàn bộ components là React Server Components (RSC). 
- Chỉ thêm directive 'use client' ở các lá ngoài cùng (leaf components) khi thực sự cần useState, useEffect hoặc sự kiện onClick.
- Mọi mutation dữ liệu phải dùng Server Actions kết hợp useActionState, không dùng API routes cũ trừ khi làm webhook công khai.

## 4. QUY TRÌNH KIỂM THỬ
- Mỗi khi tạo hoặc sửa đổi một hàm helper hoặc service, bạn BẮT BUỘC phải sinh file unit test tương ứng (*.test.ts) bằng Vitest.