Cursor Rules là gì? Cách viết rules để AI code đúng chuẩn dự án

Agent trong Cursor cứ quên quy ước dự án? Bài này giải thích Cursor Rules là gì, 4 kiểu áp dụng rule trong .cursor/rules, cách chuyển từ .cursorrules, kèm 3 rule mẫu cho Next.js + TypeScript + Tailwind và so sánh với CLAUDE.md, AGENTS.md, Copilot instructions.

Bạn giao cho Agent trong Cursor một task nhỏ: thêm một API route. Nó làm nhanh, code chạy được, nhưng validate bằng tay thay vì zod như cả dự án, trả lỗi theo một format khác, và thêm một file CSS trong khi team chỉ dùng Tailwind. Bạn sửa, lần sau nó lại mắc đúng những lỗi đó.

Model không kém. Claude Opus 5.5 hay GPT-6.1 Sol đều code tốt, nhưng không model nào tự biết quy ước riêng của dự án bạn. Mỗi phiên chat bắt đầu từ con số không. Cursor Rules là cách ghi những quy ước đó ra file để Agent đọc lại mỗi lần, thay vì bạn phải nhắc trong từng prompt.

Bài này đi vào cơ chế cụ thể theo docs hiện tại của Cursor: rule nằm ở đâu, viết frontmatter thế nào, 4 kiểu áp dụng khác nhau ra sao, file .cursorrules cũ còn dùng được không, và 3 file rule mẫu cho một dự án Next.js + TypeScript + Tailwind. Nếu bạn chưa quen Cursor, đọc trước bài Cursor là gì.

Cursor Rules là gì

Theo docs của Cursor, rules là chỉ dẫn ở cấp hệ thống dành cho Agent. LLM không giữ trí nhớ giữa các lần trả lời, nên rules đóng vai trò ngữ cảnh bền vững: khi một rule được áp dụng, nội dung của nó được đưa vào đầu context của model.

Hai điểm cần biết ngay từ đầu:

• Theo trang trợ giúp của Cursor, rules chỉ áp dụng cho Agent (Chat). Chúng không ảnh hưởng tới Tab completion, Inline Edit (Cmd/Ctrl+K) hay Bugbot khi review PR. Nếu bạn thấy Tab gợi ý code "sai chuẩn", đó không phải lỗi rule.
• Rule là ngữ cảnh, không phải luật cứng. Agent đọc và cố làm theo, nhưng không có gì bảo đảm tuyệt đối. Thứ bắt buộc phải đúng (format code, lỗi type) vẫn nên để linter, tsc và CI kiểm.

4 loại rules trong Cursor

Khi các nguồn mâu thuẫn nhau, thứ tự ưu tiên là Team Rules → Project Rules → User Rules. Tất cả rule phù hợp được gộp lại, nguồn đứng trước thắng khi hai chỉ dẫn xung đột.

User Rules hợp với những thứ như "trả lời ngắn gọn, bằng tiếng Việt". Với Team Rules, admin có thể bật Enforce để thành viên không tắt được.

Project Rules: file .mdc và frontmatter

Project Rules nằm trong thư mục .cursor/rules/. Một chi tiết hay bị nhầm: rule phải có đuôi .mdc. File .md thường đặt trong .cursor/rules/ sẽ bị hệ thống rules bỏ qua, vì nó không có frontmatter để khai báo cách áp dụng. Muốn viết markdown thuần thì dùng AGENTS.md.

.cursor/rules/
  project-core.mdc        # được nhận là rule
  api-routes.mdc          # được nhận là rule
  api-guidelines.md       # bị bỏ qua (sai đuôi)
  frontend/               # có thể chia thư mục con
    components.mdc

Docs trợ giúp của Cursor khuyên giữ cấu trúc phẳng cho dễ quản lý, dù thư mục con vẫn hoạt động.

Ba trường frontmatter

Mỗi file .mdc gồm phần frontmatter ở đầu và nội dung rule bên dưới. Có đúng ba trường:

• alwaysApply: true hoặc false.
• description: mô tả ngắn để Agent tự quyết định có cần rule này không.
• globs: pattern đường dẫn file, nhiều pattern thì ngăn cách bằng dấu phẩy.

Trong editor có dropdown chọn kiểu rule và nó tự đổi ba trường này, nhưng hiểu cơ chế sẽ giúp bạn debug khi rule "không chạy".

4 kiểu áp dụng rule

Một rule kiểu Apply Intelligently trông như sau:

---
description: Quy ước viết và cập nhật email template gửi cho người dùng
alwaysApply: false
---

- Template đặt trong `src/emails/`, mỗi email một file
- Mọi text hiển thị lấy từ file dịch, không hard-code

Với kiểu này, description quyết định rule có được dùng đúng lúc hay không, nên viết cụ thể rule dành cho việc gì.

Vài pattern globs thường dùng, lấy từ docs:

File .cursorrules cũ: còn dùng được không?

File .cursorrules ở gốc dự án là cách cấu hình kiểu cũ. Docs trợ giúp của Cursor ghi rõ nó là legacy và sẽ bị deprecate. Cursor hướng dẫn chuyển đổi theo 4 bước:

1. Mở Command Palette (Ctrl+Shift+P trên Windows/Linux, Cmd+Shift+P trên Mac), tìm "New Cursor Rule".
2. Copy nội dung .cursorrules vào file rule mới.
3. Đặt kiểu rule là Always Apply (giống hành vi cũ).
4. Xóa file .cursorrules ở gốc dự án.

Sau khi chuyển, bạn nên tách tiếp: phần nào chỉ liên quan tới một vùng code thì đưa sang rule theo globs, để rule Always Apply chỉ còn những thứ thật sự áp cho mọi task.

Cách tạo rule

Có vài cách, tùy bạn thích gõ hay bấm:

• /create-rule trong chat Agent: mô tả thứ bạn muốn, Agent tự sinh file với frontmatter đúng và lưu vào .cursor/rules. Cách này tiện nhất khi Agent vừa mắc một lỗi: bảo nó tạo rule để lần sau không lặp lại.
• Customize → Rules → Add Rule: tạo file rule mới, đồng thời xem được toàn bộ rule và trạng thái của chúng.
• Command Palette → "New Cursor Rule": đặt tên, viết nội dung, chọn kiểu áp dụng.
• Cursor CLI: lệnh /rules để tạo và sửa rule. CLI dùng chung hệ thống rules với editor, và đọc thêm AGENTS.md, CLAUDE.md ở gốc dự án.

Docs còn gợi ý tag @cursor trên GitHub issue hoặc PR để Agent cập nhật rule giúp bạn. Dù dùng cách nào, hãy đọc lại file Agent sinh ra trước khi commit. Rule sai còn tệ hơn không có rule, vì nó được áp đi áp lại.

3 file rule mẫu cho Next.js + TypeScript + Tailwind

Giả sử một dự án Next.js App Router, TypeScript strict, Tailwind, dùng pnpm. Các đường dẫn như src/lib/auth.ts dưới đây là ví dụ, bạn thay bằng đường dẫn thật của dự án mình.

Rule 1: quy ước chung, luôn áp dụng

.cursor/rules/project-core.mdc

---
alwaysApply: true
---

# Project core

- Stack: Next.js App Router, TypeScript strict, Tailwind CSS. Package manager: pnpm.
- Trước khi báo xong việc: chạy `pnpm lint` và `pnpm tsc --noEmit`, sửa hết lỗi.
- Server Components là mặc định. Chỉ thêm "use client" khi cần state, effect hoặc event handler.
- Không dùng `any`. Type dùng chung đặt trong `src/types/`.
- Styling chỉ dùng Tailwind class. Gộp class có điều kiện bằng `cn()` trong `src/lib/utils.ts`. Không tạo file CSS mới.
- Không sửa file trong `src/generated/` (sinh tự động từ schema).
- Khi không chắc cách làm, đọc code liên quan trước khi đề xuất thay đổi.

Để ý những gì không có trong file: không giải thích React là gì, không liệt kê mọi lệnh npm, không dán cả style guide. Rule chỉ nên chứa thứ riêng của dự án.

Rule 2: chỉ áp cho API route

.cursor/rules/api-routes.mdc

---
globs: src/app/api/**/route.ts
alwaysApply: false
---

# API route handlers

- Validate body và query bằng zod ở đầu handler. Schema đặt trong `src/lib/validators/`.
- Lỗi trả về một format duy nhất: `{ error: { code, message } }` kèm status đúng (400, 401, 404, 500).
- Không trả stack trace hay message lỗi gốc của database ra client.
- Kiểm tra session bằng `getSession()` từ `src/lib/auth.ts` trước khi đọc hoặc ghi dữ liệu người dùng.
- Truy cập database qua các hàm trong `src/server/db/`, không gọi ORM trực tiếp trong route.
- Cấu trúc chuẩn xem file mẫu: @src/app/api/_template/route.ts

Rule này chỉ vào context khi Agent làm việc với file route.ts trong src/app/api/. Khi bạn sửa một component giao diện, nó không chiếm chỗ.

Rule 3: workflow gọi thủ công

.cursor/rules/new-dashboard-page.mdc

---
alwaysApply: false
---

# Checklist thêm trang mới trong dashboard

1. Tạo `src/app/(dashboard)/<ten-trang>/page.tsx`, là Server Component.
2. Lấy dữ liệu qua hàm trong `src/server/queries/`, không fetch trong client component.
3. Thêm `loading.tsx` và `error.tsx` cùng thư mục (`error.tsx` phải có "use client" vì error boundary là Client Component).
4. Thêm link vào `src/components/layout/sidebar-nav.tsx`.
5. Viết test cho hàm query mới.
6. Chạy `pnpm lint && pnpm tsc --noEmit && pnpm test`, sau đó tóm tắt các file đã đổi.

Không có description, không có globs, nên rule này chỉ chạy khi bạn gọi: "Thêm trang Báo cáo doanh thu theo @new-dashboard-page". Kiểu Apply Manually hợp với những quy trình bạn dùng vài lần mỗi tuần, không cần nạp mọi lúc.

Nếu một workflow dài dần ra, nhiều bước và có script đi kèm, Cursor có cơ chế riêng tốt hơn là Skills (file .cursor/skills/<tên-skill>/SKILL.md). Theo docs Cursor, rule dành cho chỉ dẫn ngắn và ràng buộc, còn skill dành cho quy trình nhiều bước. Agent tự dùng skill khi thấy liên quan (trừ khi skill đặt disable-model-invocation: true), hoặc bạn gọi trực tiếp bằng /tên-skill. Lệnh /migrate-to-skills chuyển các rule và slash command phù hợp sang skill.

AGENTS.md và AGENTS.md lồng nhau

AGENTS.md là file markdown thuần, không frontmatter, đặt ở gốc dự án. Cursor coi nó là lựa chọn đơn giản thay cho .cursor/rules khi bạn không cần kiểm soát lúc nào rule được áp dụng.

Cursor hỗ trợ cả AGENTS.md lồng nhau trong thư mục con. File ở thư mục nào sẽ tự áp dụng khi Agent làm việc với file trong thư mục đó hoặc thư mục con của nó, gộp với chỉ dẫn từ thư mục cha, và chỉ dẫn cụ thể hơn được ưu tiên:

project/
  AGENTS.md              # chỉ dẫn chung
  frontend/
    AGENTS.md            # riêng cho frontend
    components/
      AGENTS.md          # riêng cho components
  backend/
    AGENTS.md            # riêng cho backend

Cursor còn đọc CLAUDE.md giống cách đọc AGENTS.md, và CLAUDE.md luôn được áp dụng cho mọi phiên, bất kể frontmatter. Điều này giúp dự án dùng song song Claude Code và Cursor, nhưng cũng có nghĩa là nội dung CLAUDE.md luôn nằm trong context của Agent Cursor.

Với team dùng nhiều công cụ, một cách tổ chức hợp lý: quy ước chung viết vào AGENTS.md (Copilot và Claude Code cũng đọc được), còn những rule cần scope theo file thì để trong .cursor/rules/.

So sánh với CLAUDE.md, AGENTS.md và Copilot instructions

Vài chi tiết đáng chú ý khi dùng chung:

• Claude Code đọc AGENTS.md khi dự án không có CLAUDE.md (cần v2.1.277 trở lên). Nếu có cả hai, mặc định nó chỉ đọc CLAUDE.md. Cách docs Claude Code gợi ý là đặt dòng @AGENTS.md ở đầu CLAUDE.md để dùng chung một nguồn.
• Copilot đọc AGENTS.md ở bất kỳ đâu trong repo, và file AGENTS.md gần nhất trong cây thư mục được ưu tiên.
• Cursor là công cụ duy nhất trong bảng cho phép một file rule được model tự chọn dựa trên description. Ở Claude Code và Copilot, cơ chế tương tự nằm ở skills.

Muốn so sánh rộng hơn về ba công cụ, xem bài Cursor vs Copilot vs Claude Code.

Best practices từ docs Cursor

Docs của Cursor tóm lại: rule tốt là rule tập trung, làm được và có phạm vi rõ. Cụ thể:

• Giữ mỗi rule dưới 500 dòng. Rule lớn thì tách thành nhiều rule nhỏ, mỗi file một chủ đề: styling, testing, API.
• Viết như tài liệu nội bộ rõ ràng, kèm ví dụ cụ thể. "Viết code sạch" thì Agent không biết làm gì, còn "Lỗi API trả về { error: { code, message } }" thì làm theo được.
• Tham chiếu file thay vì copy nội dung. Ghi @đường-dẫn-file trong rule để chỉ cho Agent file mẫu, rule vừa ngắn vừa không lỗi thời khi code đổi. Lưu ý nội dung file không được chèn sẵn vào prompt: Agent tự đọc file khi cần. Thứ gì bắt buộc luôn có trong context thì viết thẳng vào rule.
• Bắt đầu đơn giản. Chỉ thêm rule khi thấy Agent lặp lại cùng một lỗi. Đừng tối ưu trước khi hiểu pattern của mình.
• Commit rules vào git để cả team hưởng lợi, và cập nhật rule mỗi khi Agent sai.

Docs cũng liệt kê những thứ không nên đưa vào rule: copy cả style guide (dùng linter), liệt kê mọi lệnh có thể dùng (Agent đã biết npm, git, pytest), chỉ dẫn cho edge case hiếm gặp, và code đã có sẵn trong codebase (trỏ tới ví dụ chuẩn thay vì copy).

Nguyên tắc này khớp với tư duy context engineering: mỗi dòng trong rule Always Apply chiếm chỗ trong context của mọi phiên chat, nên chỉ những dòng thật sự cần mới đáng ở đó.

Sai lầm thường gặp

• Mọi rule đều Always Apply. Rule về API bị nạp cả khi bạn chỉ sửa CSS. Rule nào gắn với một vùng code thì dùng globs.
• Quên description cho rule muốn Apply Intelligently. Thiếu cả description lẫn globs thì rule thành Apply Manually, chỉ chạy khi bạn @-mention. Đây là điểm đầu tiên cần kiểm tra khi rule "không chạy".
• Glob không khớp đường dẫn thật. Viết app/api/** trong khi code nằm ở src/app/api/. Kiểm tra lại cấu trúc thư mục trước khi kết luận rule hỏng.
• Rule mâu thuẫn giữa các nguồn. CLAUDE.md nói dùng npm, rule Cursor nói pnpm, User Rule lại nói yarn. Cursor luôn nạp CLAUDE.md, nên hai file này dễ mâu thuẫn nhau nhất. Định kỳ rà lại toàn bộ.
• Dựa vào rule cho bảo mật. Ngay cả với Team Rules bị Enforce, docs Cursor vẫn lưu ý rule không nên là lớp kiểm soát bảo mật duy nhất. "Không commit secret" viết trong rule là tốt, nhưng secret scanning trong CI mới là thứ chặn được.

Tóm lại

Cursor Rules giải quyết một vấn đề cụ thể: Agent không nhớ quy ước dự án giữa các phiên. Cách dùng hiệu quả khá gọn: một rule Always Apply ngắn cho quy ước chung, các rule theo globs cho từng vùng code, rule Apply Manually hoặc skill cho workflow, và chuyển hẳn khỏi .cursorrules. Nếu team dùng nhiều công cụ, đưa phần chung vào AGENTS.md.

Rule tốt đến từ việc bạn hiểu rõ dự án của mình: biết quy ước nào quan trọng, biết Agent hay sai ở đâu, và nhận ra khi code nó sinh ra lệch chuẩn. Nếu bạn làm frontend và muốn có nền React đủ chắc để viết rule sắc và review code AI tự tin, khóa React PRO của HoleTex được thiết kế cho mục tiêu đó. Còn nếu muốn rèn tư duy giải quyết vấn đề, thử luyện thuật toán trên HoleTex Algo.

Bài liên quan

• Cursor là gì và dùng sao cho hiệu quả
• Context engineering là gì: cách "nuôi" ngữ cảnh cho AI agent code đúng
• Claude Code nâng cao: subagents, hooks, skills
• Cursor vs Copilot vs Claude Code
• Prompt cho lập trình: cách viết prompt để AI code đúng ý

Nguồn tham khảo: Rules (cursor.com), Rules help (cursor.com), Skills (cursor.com), Skills help (cursor.com), error.js (nextjs.org), Customize Cursor (cursor.com), Using Agent in CLI (cursor.com), Cursor CLI changelog Jan 2026 (cursor.com), Claude Code memory (code.claude.com), Copilot repository instructions (docs.github.com). Cập nhật 2026-10-08.