Cách dùng Cursor Rules File (.mdc)

Cursor Rules là các file .mdc được đặt trong thư mục .cursor/rules/ của dự án. Mỗi file chứa hai phần: YAML frontmatter (kiểm soát khi nào rule được kích hoạt) và nội dung Markdown (hướng dẫn thực sự cho AI). Khi được thiết lập đúng, AI trong Cursor tự động đọc và tuân theo các quy tắc trong file mà không cần bạn nhắc lại mỗi lần.

Tóm tắt nội dung nhanh

1. Mở Cursor và dự án cần thiết lập rule
2. Mở hoặc tạo file .mdc trong thư mục .cursor/rules/
3. Kiểm tra YAML frontmatter hợp lệ (phần giữa hai dấu ---)
4. Đặt alwaysApply: true nếu muốn rule luôn hoạt động
5. Mở Chat (Cmd+L) hoặc Composer (Cmd+I) và làm việc bình thường
6. Cursor tự động áp dụng rule vào mọi phiên làm việc

Cursor Rules là gì và tại sao cần dùng?

• Mỗi phiên Chat hoặc Composer trong Cursor bắt đầu hoàn toàn từ đầu - AI không nhớ bạn dùng TypeScript strict mode, không nhớ convention đặt tên trong project, không nhớ bạn đã dặn "đừng bao giờ dùng any type". Kết quả là bạn phải nhắc đi nhắc lại cùng một context trong mọi phiên làm việc, như đang hướng dẫn một nhân viên mới bắt đầu mỗi buổi sáng.
• Cursor Rules giải quyết vấn đề đó: bạn viết các quy tắc, coding convention và ngữ cảnh dự án một lần, lưu vào file .mdc, và Cursor AI sẽ tự động đọc và tuân theo chúng trong mọi phiên làm việc sau đó - mà không cần bạn nhắc lại.
• Khác với file .cursorrules cũ (một file duy nhất áp dụng cho mọi thứ), hệ thống .cursor/rules/ mới cho phép tạo nhiều file rule với các phạm vi áp dụng khác nhau: một rule chỉ áp dụng cho file TypeScript, một rule khác chỉ cho file test, một rule khác chỉ khi AI chủ động yêu cầu. Đây là điểm mạnh cốt lõi so với cách tiếp cận một-file-cho-tất-cả.

Hướng dẫn từng bước: Tạo và sử dụng Cursor Rules File

Bước 1: Mở dự án trong Cursor

Khởi động ứng dụng Cursor trên máy tính, nhấn vào nút Open project (hoặc File > Open Folder) để bắt đầu mở dự án làm việc.

Bước 2: Chọn thư mục làm việc

Tìm đến thư mục chứa dự án của bạn (ví dụ trong ảnh là thư mục Test-QTM) và nhấn nút Select Folder để Cursor tiến hành nạp cấu hình và lập chỉ mục codebase.

Bước 3: Kích hoạt tạo thư mục cấu hình

Tại cột cây thư mục dự án bên tay phải (hoặc bên trái tùy giao diện), nhấn vào biểu tượng New Folder... (Tạo thư mục mới) ngay tại thư mục gốc.

Bước 4: Đặt tên thư mục hệ thống .cursor

Nhập tên thư mục là .cursor và ấn Enter. Sau đó, nhấp chuột phải vào thư mục .cursor vừa tạo để tạo tiếp một thư mục con bên trong đặt tên là rules.

Bước 5: Tạo tệp quy tắc .mdc mới

Nhấp chuột phải vào thư mục rules vừa tạo, chọn New File... và nhập tên tệp tin kèm theo đuôi mở rộng bắt buộc là .mdc (Ví dụ: base.mdc).

Bước 6: Tùy chỉnh chế độ áp dụng quy tắc (Scope)

Khi tệp .mdc mở ra, Cursor sẽ hiển thị giao diện UI cấu hình trực quan. Bạn bấm vào menu thả xuống ở góc trên cùng bên trái để chọn chế độ mong muốn (ví dụ: Chọn Always Apply để quy tắc luôn hoạt động trong mọi phiên chat, hoặc Apply to Specific Files nếu chỉ muốn áp dụng riêng cho một số định dạng tệp cụ thể).

Mẹo nâng cao: Ra lệnh cho AI tự động sinh file .mdc

Ngoài việc tạo thủ công, từ phiên bản v2026, bạn có thể tận dụng chế độ Agent trong khung Composer để tự tạo quy tắc tự động:

Bước 7: Sử dụng lệnh /create-rule trong Composer

Nhấn tổ hợp phím Cmd + I (hoặc Ctrl + I trên Windows) để mở cửa sổ Composer. Chuyển chế độ sang Agent ở góc dưới, gõ ký tự / và chọn lệnh /create-rule từ menu hệ thống.

Bước 8: Viết Prompt mô tả quy chuẩn coding mong muốn

Nhập đoạn Prompt mô tả các tiêu chuẩn bạn muốn ép AI tuân thủ bằng tiếng Việt hoặc tiếng Anh (ví dụ: Yêu cầu AI phản hồi bằng tiếng Việt, áp dụng các nguyên lý SOLID, bắt lỗi bằng try/catch...). Sau đó nhấn nút mũi tên Gửi (Arrow icon) để Agent bắt đầu phân tích và tự động viết mã cấu hình.

Bước 9: Kiểm tra cấu hình do AI tự tạo và Lưu lại

AI Agent sẽ tự động sinh ra tệp quy tắc mới nếu như tệp quy tắc bạn tạo chưa được hoàn chỉnh cho lắm (ví dụ: express-standards.mdc) nằm đúng trong thư mục .cursor/rules/ với đầy đủ phần YAML Frontmatter cấu hình chế độ kích hoạt và nội dung định dạng Markdown. Bạn chỉ cần kiểm tra lại các mục và nhấn Keep File để áp dụng.

Ví dụ thực tế: Template Cursor Rules cho dự án phổ biến

Rule cơ bản (base.mdc) - áp dụng mọi lúc:

---
   description: "Quy tắc chung cho dự án Next.js TypeScript"
  alwaysApply: true
  ---
  
  Bạn đang làm việc trong dự án Next.js 15 với TypeScript strict mode.
  
  - Dùng async/await, không dùng .then()
  - Tất cả component là Server Component theo mặc định
  - Ưu tiên named export thay vì default export
  - Luôn có error handling cho mọi async operation

Rule TypeScript (typescript.mdc) - tự động kích hoạt khi làm việc với .ts/.tsx:

---
   description: "Quy chuẩn TypeScript nghiêm ngặt"
  globs: ["**/*.ts", "**/*.tsx"]
  alwaysApply: false
  ---
  
  - Không dùng kiểu `any` trong bất kỳ trường hợp nào
  - Tất cả function export phải có kiểu trả về rõ ràng
  - Dùng `interface` cho object shapes, `type` cho union types
  - Bật strict null checks

Lỗi thường gặp và cách xử lý

Rule không hoạt động dù đã tạo file: Nguyên nhân phổ biến nhất là YAML frontmatter không hợp lệ - thiếu dấu --- đóng, lỗi cú pháp YAML, hoặc có khoảng trắng/ký tự lạ trước dấu --- đầu tiên. Thử đặt tạm alwaysApply: true để kiểm tra xem nội dung rule có hoạt động không - nếu có thì vấn đề nằm ở glob pattern hoặc điều kiện kích hoạt.

Agent mode bỏ qua rule: File .cursorrules cũ ở thư mục gốc bị Cursor Agent mode tự động bỏ qua từ 2026. Hãy chuyển sang định dạng .cursor/rules/*.mdc để rule hoạt động với cả Chat, Composer và Agent.

Rule Always Apply làm chậm phản hồi: Mỗi token trong rule alwaysApply: true được đưa vào mọi request. Nếu rule quá dài (trên 200 từ), bạn đang lãng phí context window. Giải pháp: cắt bớt nội dung, hoặc chuyển những phần không cần thiết trong mọi request sang chế độ Auto Attached hoặc Agent Requested.

Cấu trúc file .mdc: YAML frontmatter và nội dung rule

Mỗi file .mdc có hai phần rõ ràng:

Phần 1 - YAML Frontmatter (kiểm soát hành vi):

---
   description: "Quy tắc TypeScript cho dự án này"
  globs: ["**/*.ts", "**/*.tsx"]
  alwaysApply: false
  ---

Phần 2 - Nội dung Markdown (hướng dẫn thực tế cho AI):

# Quy chuẩn TypeScript

- Luôn dùng strict mode (tsconfig strict: true)
- Ưu tiên interface thay vì type alias cho object shapes
- Không dùng kiểu `any` trong bất kỳ trường hợp nào
- Tất cả function phải có kiểu trả về rõ ràng

Các trường trong YAML frontmatter:

• description - Mô tả ngắn về rule này làm gì. Bắt buộc nếu bạn muốn AI tự quyết định có dùng rule này không (chế độ Agent Requested).
• globs - Danh sách pattern file mà rule này áp dụng. Ví dụ: ["**/*.ts"] chỉ áp dụng khi làm việc với file TypeScript.
• alwaysApply - Nếu là true, rule được đưa vào context của mọi phiên Chat và Composer, bất kể file nào đang mở. Nếu là false, rule chỉ kích hoạt theo điều kiện khác.

Tổng hợp 4 chế độ kích hoạt của Cursor Rules

Đây là phần quan trọng nhất và thường bị hiểu nhầm. Cách rule kích hoạt phụ thuộc hoàn toàn vào sự kết hợp của các trường frontmatter:

• 1. Always Apply (Luôn áp dụng) alwaysApply: true - Rule được đưa vào context của mọi yêu cầu AI, bất kể đang làm gì. Dùng cho các convention cốt lõi của dự án. Lưu ý: mỗi token trong rule loại này được tải vào mọi request, nên hãy giữ rule loại này dưới 200 từ để tránh lãng phí context window.
• 2. Auto Attached (Tự động đính kèm) alwaysApply: false + globs: ["**/*.ts"] - Rule tự động kích hoạt khi file đang mở khớp với pattern glob. Không cần làm gì thêm. Phù hợp cho các rule theo ngôn ngữ hoặc thư mục cụ thể.
• 3. Agent Requested (AI chủ động yêu cầu) alwaysApply: false + description: "..." (không có globs) - AI đọc phần description và tự quyết định có dùng rule này không dựa trên ngữ cảnh hiện tại. Phù hợp cho các rule đặc biệt mà AI có thể biết khi nào cần dùng.
• 4. Manual (Thủ công) Không có alwaysApply, không có globs, không có description - Rule chỉ kích hoạt khi bạn chủ động gọi tên nó bằng cú pháp @tên-rule trong Chat hoặc Composer.

.cursorrules cũ vs .cursor/rules mới: Nên dùng cái nào?

• File .cursorrules (định dạng cũ): một file Markdown duy nhất ở thư mục gốc, không có frontmatter, áp dụng cho mọi thứ trong mọi phiên. Ưu điểm: đơn giản, dễ thiết lập. Nhược điểm: không có scope control, bị Agent mode bỏ qua hoàn toàn từ 2026, không thể tắt cho từng loại file.
• .cursor/rules/*.mdc (định dạng mới, khuyến nghị 2026): nhiều file, mỗi file có scope riêng, hoạt động với cả Chat, Composer và Agent mode. Phức tạp hơn một chút để thiết lập ban đầu nhưng linh hoạt và hiệu quả hơn nhiều về lâu dài.
• Kết luận: Nếu bạn đang dùng agentic workflow hoặc kế hoạch dùng trong tương lai, hãy chuyển sang định dạng .mdc ngay. Nếu chỉ dùng Chat cơ bản và không cần scope control, .cursorrules cũ vẫn hoạt động nhưng không được đảm bảo hỗ trợ dài hạn.

Câu hỏi thường gặp (FAQ)

Cursor Rules có ảnh hưởng đến tính năng autocomplete (Tab) không?

• Rules chỉ ảnh hưởng đến Chat và Composer. Cursor Tab autocomplete và Inline Edit (Cmd/Ctrl+K) không đọc rules.

Có thể commit file .cursor/rules/ lên Git để cả team dùng chung không?

• Hoàn toàn có, đây chính là mục đích thiết kế của hệ thống này - rules trong .cursor/rules/ được commit vào repo để đảm bảo toàn team dùng cùng một context AI. Nếu có rules cá nhân không muốn chia sẻ, thêm file đó vào .gitignore.

Bao nhiêu rule file là phù hợp?

• Theo kinh nghiệm thực tế, 5-8 file là tối ưu cho hầu hết dự án: một rule always-on cho quy tắc cơ bản, 3-4 rule auto-attached theo loại file, và 1-2 rule manual cho tác vụ đặc biệt. Nhiều hơn 10 rule thường là dấu hiệu có thể hợp nhất một số file lại.

Cursor có thể tự tạo file rule không?

• Bạn có thể yêu cầu Cursor Agent tạo rule file cho bạn bằng cách mô tả những gì bạn muốn. Cursor sẽ sinh ra file .mdc với frontmatter và nội dung phù hợp trong thư mục .cursor/rules/.