Dùng định dạng .cursor/rules/*.mdc hiện đại, không dùng file .cursorrules cũ. Mỗi mối quan tâm nên được đặt trong file riêng. Giữ các file tập trung và phạm vi hóa bằng globs để AI chỉ thấy các rules liên quan đến code đang xử lý.

Tại sao Cursor rules quan trọng

Không có rules, AI của Cursor không biết gì cụ thể về dự án của bạn. Nó áp dụng kiến thức chung về TypeScript, React, hay bất kỳ ngôn ngữ nào nó phát hiện ra — và những suy đoán đó thường sai. Nó gợi ý các pattern mà bạn đã loại bỏ từ quý trước, đặt tên biến sai convention, hoặc bỏ qua auth wrapper mà toàn bộ API của bạn phụ thuộc vào.

Với rules, AI biết các ràng buộc của bạn trước khi viết một dòng code. Nó dùng wrapper withAuth mà không cần nhắc. Nó tuân theo naming conventions của bạn. Nó tránh các anti-pattern mà team đã quyết định cấm sau một sự cố trên production.

Sự khác biệt không nhỏ. Dự án với rules được phạm vi hóa tốt cho ra kết quả phù hợp mà không cần chỉnh sửa. Dự án không có rules cho ra kết quả cần làm lại mỗi lần.

Bài viết này dành cho ai

Những developer đang dùng Cursor mà nhận được output chung chung và nghi ngờ rules của mình không hoạt động — hoặc developer đang setup dự án mới muốn làm đúng ngay từ đầu. Nếu bạn chưa cài Cursor, hãy đọc đánh giá Cursor 2026 của chúng tôi trước; rules là chủ đề nâng cao, nên quay lại sau khi đã dùng được một tuần.

Hai định dạng

Cursor hỗ trợ hai định dạng rule, và chúng hoạt động khác nhau.

Cũ: .cursorrules

Một file duy nhất ở thư mục gốc của dự án, không có frontmatter. Cursor vẫn đọc file này — nó KHÔNG bị bỏ qua âm thầm trong Agent mode. Nhưng nó có một hạn chế đáng lưu ý: nó là một monolith. Mọi rule trong đó đều được tải cho mọi ngữ cảnh, dù có liên quan hay không. Với dự án mới, đừng bắt đầu với nó.

Hiện đại: .cursor/rules/*.mdc

Định dạng thư mục .cursor/rules/*.mdc là tiêu chuẩn hiện tại. Một thư mục chứa các file rule có phạm vi, mỗi file có YAML frontmatter. Mỗi file có thể nhắm đến các ngữ cảnh khác nhau, các loại file khác nhau, hoặc các chế độ kích hoạt khác nhau. Đây là thứ bạn nên dùng.

Chi tiết quan trọng: extension phải là .mdc. Các file .md trong .cursor/rules/ bị bỏ qua âm thầm. Không được tải kèm cảnh báo, không được tải một phần — bỏ qua hoàn toàn. Đặt tên file *.mdc nếu không chúng không tồn tại.

Bốn loại rule

Mỗi file .mdc có ba trường frontmatter kiểm soát cách Cursor quyết định có đưa nó vào hay không:

Trường	Kiểu	Tác dụng
`alwaysApply`	boolean	Nếu `true`, được đưa vào mọi phiên Agent/Chat
`globs`	string	Được gắn khi các file khớp đang mở hoặc được chỉnh sửa (chế độ Apply to Specific Files)
`description`	string	AI đọc trường này để quyết định tính liên quan trong chế độ Apply Intelligently

Các trường này ánh xạ đến bốn loại rule hiển thị trong giao diện Cursor:

Always Apply

---
alwaysApply: true
---

Được đưa vào mọi phiên Agent/Chat. Dùng cho ngữ cảnh toàn dự án — dự án là gì, dùng stack nào, những điều team không thể thỏa hiệp là gì. Giữ ngắn. Nếu mọi thứ đều được always-apply, không có gì thực sự quan trọng.

Apply to Specific Files

---
alwaysApply: false
globs: src/**/*.ts, src/**/*.tsx
---

Cursor tự động gắn rule này khi bạn làm việc với các file khớp glob pattern. Bạn không cần suy nghĩ về nó. Phù hợp cho các framework conventions, linting preferences, hoặc naming patterns chỉ quan trọng ở một số phần nhất định của codebase.

globs nhận một chuỗi các pattern phân cách bằng dấu phẩy. Cú pháp glob chuẩn hoạt động: ** cho bất kỳ độ sâu nào, *.ts cho TypeScript files, src/api/** cho một nhánh thư mục.

Apply Intelligently

---
alwaysApply: false
description: "Use when working with database migrations or schema changes"
---

Không có globs, không có alwaysApply. AI của Cursor đọc trường description và quyết định rule này có liên quan đến tác vụ hiện tại hay không. AI tự phán xét; bạn không kiểm soát trực tiếp. Viết description là một câu đơn, chính xác về khi nào rule này áp dụng. Description mơ hồ (“general coding standards”) bị bỏ qua hoặc áp dụng không nhất quán.

Apply Manually

---
---

Không có metadata. Rule này chỉ được tải khi bạn đưa nó vào rõ ràng bằng @ruleName trong prompt. Dùng cho ngữ cảnh cần dùng không thường xuyên — migration playbooks, deployment checklists, hoặc onboarding scripts mà bạn muốn có sẵn nhưng không muốn làm ô nhiễm mọi phiên.

Ví dụ thực tế

Dưới đây là bốn file .mdc bao gồm các trường hợp dùng phổ biến nhất.

Ngữ cảnh dự án (Always Apply)

---
alwaysApply: true
---

# project-context

Đây là SaaS billing dashboard xây dựng với Next.js 14 (App Router), TypeScript, và Prisma trên PostgreSQL.

**Không thể thỏa hiệp:**
- Mọi thay đổi DB đều qua Prisma migrations — không có raw SQL trong application code
- Dates luôn là UTC trong DB; format để hiển thị ở UI layer
- Lỗi hiển thị cho user qua toast notifications, không phải console.log

**Cấu trúc repository:**
- `src/app` — Next.js App Router pages và layouts
- `src/components` — shared UI components
- `src/lib` — utilities, DB client, type definitions
- `prisma/` — schema và migrations

Rule này cho AI biết ngay lập tức nó đang làm việc trong môi trường nào. Mọi phiên Agent đều bắt đầu với thông tin này.

Framework conventions (Apply to Specific Files)

---
alwaysApply: false
globs: src/**/*.tsx, src/**/*.ts
---

# typescript-conventions

**Imports:** Dùng `@/` path aliases — không bao giờ dùng relative paths từ `src/`.

**Types:** Explicit return types trên tất cả exported functions. `interface` cho object shapes, `type` cho unions và intersections. Không dùng `any` mà không có comment giải thích tại sao không tránh được.

**Components:** Một component mỗi file. Tên file khớp với tên component được export ở dạng PascalCase. Props interface được định nghĩa ngay trên component.

**State management:** `useState` cho component-local state. Zustand cho cross-component state. Không có Redux — nó không có trong dự án này.

File này tự động tải khi TypeScript files đang mở. Developer viết code, AI đã biết conventions.

Anti-patterns cần tránh (Apply Intelligently)

---
alwaysApply: false
description: "Use when asked to implement API endpoints, handle authentication, or work with user data"
---

# api-safety-rules

**Không được làm:**
- Đừng tin client-supplied IDs mà không xác minh quyền sở hữu với session của người dùng đã xác thực
- Đừng log raw request bodies — chúng có thể chứa secrets hoặc PII
- Đừng trả về thông báo lỗi database chi tiết cho client — dùng thông báo chung và log chi tiết ở server-side
- Đừng bỏ qua rate limiting trên mutation endpoints

**Luôn phải làm:**
- Validate input tại route handler với Zod trước khi đưa vào service layer
- Dùng wrapper `withAuth` từ `src/lib/auth` — đừng tự viết session check
- Trả về 404 (không phải 403) khi resource tồn tại nhưng user hiện tại không thể xem — đừng xác nhận sự tồn tại

AI tải file này khi phát hiện tác vụ liên quan đến API. Các security rules không làm ô nhiễm các phiên không liên quan.

Agent workflow (Apply Manually)

---
---

# deploy-checklist

Trước khi deploy lên production:

1. `pnpm prisma migrate status` — xác nhận tất cả migrations đã áp dụng trong staging
2. `pnpm test:e2e` — bộ end-to-end test phải pass
3. Cập nhật `CHANGELOG.md` với bản tóm tắt release
4. Tag release: `git tag -a v<X.Y.Z> -m "release: <summary>"`

Rule này chỉ dành cho deploy workflow. Load bằng `@deploy-checklist` khi thực hiện deployment.

Bạn gõ @deploy-checklist run the deployment workflow trong Agent. Không có gì khác tải file này theo mặc định.

Các lỗi thường gặp

Dùng .md thay vì .mdc. Cursor âm thầm bỏ qua .md files trong .cursor/rules/. Nếu một rule có vẻ không làm gì, kiểm tra extension trước.

Viết một file .mdc khổng lồ. File rules monolithic làm mất đi mục đích của định dạng thư mục. Bạn không thể phạm vi hóa nó. Mọi thứ tải khắp nơi. Hãy tách ra: một file cho project context, một file cho mỗi domain (API, UI, DB), một file cho mỗi workflow bạn muốn tự động hóa.

Trường description mơ hồ. “Coding standards and best practices” không phải là description mà AI có thể hành động dựa trên đó. Hãy cụ thể: “Use when implementing REST endpoints or working with Prisma queries.” AI dùng trường này để đưa ra quyết định include/exclude nhị phân.

Đặt ý kiến của team vào alwaysApply. Nếu bạn đặt mọi thứ thành alwaysApply: true, bạn đang quay lại vấn đề monolith. Dành Always Apply cho những thông tin AI cần trong mọi phiên — project identity, stack, các invariants quan trọng. Đặt các preferences có quan điểm vào Apply to Specific Files hoặc Apply Intelligently rules được phạm vi hóa ở nơi chúng quan trọng.

Rules xung đột mà không có cách giải quyết. Nếu rule toàn cục nói “dùng camelCase cho biến” và backend rule nói “khớp với tên cột database,” AI sẽ chọn một hoặc dao động. Hãy để rule cụ thể hơn thắng bằng cách rõ ràng: “Khớp tên cột chính xác khi đọc hoặc ghi DB; camelCase ở những nơi khác.”

Kỳ vọng rules hoạt động trong Cmd+K. Chúng không hoạt động. Theo tài liệu Cursor, rules chỉ áp dụng cho Agent và Chat modes. Cmd/Ctrl+K (Inline Edit) không tải rules của bạn. Tab (autocomplete) cũng vậy. Nếu bạn nhận được hành vi không nhất quán, kiểm tra xem bạn đang ở mode nào.

Viết instructions mà AI không thể thực hiện. “Write clean code” không thể thực hiện được. “Functions must not exceed 40 lines; extract helpers with descriptive names if they would” thì có thể. Rule càng cụ thể, càng được áp dụng nhất quán.

Không version-control rules của bạn. .cursor/rules/ nằm trong repo. Commit nó. Team của bạn có cùng hành vi AI. Người mới không cần reverse-engineer conventions. Rules cải thiện qua code review như bất kỳ file nào khác.

Để rules trở nên lỗi thời. Một rule mô tả kiến trúc năm ngoái còn tệ hơn không có rule — nó chủ động đánh lừa AI. Hãy xem rules như documentation: khi bạn refactor một module, cập nhật rule đề cập đến nó. Rule sai có thể khó debug hơn rule thiếu vì AI tự tin làm điều sai thay vì dùng defaults của mình.

Giữ files quá dài. Không có giới hạn ký tự cứng được Cursor ghi lại. Giới hạn thực tế hữu ích là khoảng 200 dòng mỗi file; vượt quá đó, focus có xu hướng bị phân tán. Nếu file TypeScript conventions của bạn đang phình to hơn 200 dòng, nó có thể chứa nhiều mối quan tâm riêng biệt — component patterns, state management, API access — mỗi cái đáng có file được phạm vi hóa riêng.

Template bắt đầu nhanh

Nếu bạn đang bắt đầu từ đầu, đây là setup tối giản với ba file:

.cursor/rules/
├── project-context.mdc     ← alwaysApply: true
├── code-conventions.mdc    ← globs: src/**/*.ts, src/**/*.tsx
└── api-safety.mdc          ← description: "when working with API or auth code"

project-context.mdc:

---
alwaysApply: true
---

# project-context

Một đoạn: dự án này là gì, chạy trên stack nào, và một hoặc hai điều AI không bao giờ được làm ở đây.

code-conventions.mdc:

---
alwaysApply: false
globs: src/**/*.ts, src/**/*.tsx
---

# code-conventions

Danh sách bullet các conventions đặc thù cho TypeScript/framework của bạn. Ba đến năm bullet tối đa — AI đọc file này mỗi khi chạm vào file `.ts`.

api-safety.mdc:

---
alwaysApply: false
description: "Use when working with API routes, authentication, or data access"
---

# api-safety

Danh sách bullet các security rules mà team bạn quan tâm nhất. Input validation, auth checks, error handling.

Bắt đầu với ba file này. Thêm file khi bạn nhận thấy AI làm sai trong các khu vực cụ thể.

Đang làm việc với AI-assisted development tooling? toolchew đưa tin về Cursor vs Claude Code, Cursor vs GitHub Copilot, và phần còn lại của AI dev-tool stack. Đăng ký để nhận bài viết thực tế — công cụ đã được kiểm thử, đánh giá trung thực.