Quy tắc Cursor: Cách viết tệp .cursor/rules hoạt động hiệu quả

Quy tắc Cursor: Cách viết tệp .cursor/rules hoạt động hiệu quả

Mọi người dùng Cursor đều gặp phải cùng một rào cản. AI tạo ra mã về mặt kỹ thuật thì chạy được nhưng lại bỏ qua các quy ước của dự án, sử dụng đường dẫn import sai, áp dụng các mẫu lỗi thời, hoặc cấu trúc thành phần hoàn toàn khác với phần còn lại của codebase. Quy tắc Cursor khắc phục điều này bằng cách cung cấp cho AI ngữ cảnh liên tục về cách dự án của bạn vận hành.

Quy tắc Cursor là gì và tại sao chúng quan trọng?

Quy tắc Cursor là các tệp markdown đóng vai trò như một lời nhắc hệ thống (system prompt) vĩnh viễn, được chèn vào trước mọi tương tác với AI, dù là chat, tự động hoàn thành hay tạo mã. Hãy coi chúng như tài liệu hướng dẫn nhập môn dành cho AI. Thay vì phải sửa cùng một lỗi trong mỗi phiên làm việc, bạn viết hướng dẫn một lần và nó sẽ được áp dụng mãi.

Cách tiếp cận cũ là sử dụng một tệp .cursorrules duy nhất trong thư mục gốc của dự án. Cách này vẫn hoạt động nhưng đã bị phản đối (deprecated). Hệ thống hiện tại sử dụng thư mục .cursor/rules/ chứa các tệp .mdc (Markdown Cursor) riêng lẻ, mỗi tệp được giới hạn cho các tình huống cụ thể. Đây là cách thiết lập tốt hơn nhiều vì bạn không nhồi nhét mọi hướng dẫn vào một tệp khổng lồ; thay vào đó, bạn chia nhỏ quy tắc theo mối quan tâm, và Cursor chỉ tải những quy tắc phù hợp với những gì bạn đang làm tại thời điểm đó.

Nếu bạn đã làm việc với kỹ thuật ngữ cảnh cho các công cụ AI, khái niệm này khá quen thuộc: ngữ cảnh đầu vào tốt hơn tạo ra kết quả đầu ra tốt hơn đáng kể. Quy tắc chính là kỹ thuật ngữ cảnh cho toàn bộ quy trình phát triển của bạn.

Thiết lập tệp quy tắc đầu tiên của bạn

Tạo thư mục .cursor/rules/ tại thư mục gốc của dự án:

mkdir -p .cursor/rules

Mỗi quy tắc là một tệp .mdc với phần frontmatter YAML theo sau là nội dung markdown. Dưới đây là khung cơ bản:

---
description: "When this rule should apply"
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

Your instructions go here in plain markdown.

Ba trường frontmatter kiểm soát mọi thứ:

Bạn cũng có thể tạo quy tắc trực tiếp thông qua Cursor, gõ /create-rule trong cửa sổ chat và mô tả những gì bạn muốn. Tuy nhiên, viết thủ công mang lại cho bạn quyền kiểm soát nhiều hơn.

Giải thích bốn loại quy tắc

Cách một quy tắc được kích hoạt phụ thuộc vào cấu hình frontmatter của nó. Có bốn chế độ, và việc chọn đúng chế độ rất quan trọng đối với ngân sách cửa sổ ngữ cảnh của bạn.

Luôn áp dụng (Always Apply)

---
alwaysApply: true
---

Được tải vào mọi yêu cầu AI duy nhất. Hãy sử dụng chế độ này một cách tiết kiệm, dành cho các nguyên tắc nền tảng trên toàn dự án như khai báo ngăn xếp công nghệ (tech stack) hoặc các quy ước quan trọng áp dụng ở mọi nơi. Mọi quy tắc luôn bật đều tiêu tốn token từ mọi tương tác, bất kể có liên quan hay không.

Tự động đính kèm (Dựa trên Glob)

---
globs: ["src/api/**/*.ts", "src/routes/**/*.ts"]
alwaysApply: false
---

Chỉ kích hoạt khi bạn đang chỉnh sửa các tệp khớp với các mẫu glob. Đây là loại quy tắc chủ lực. Các quy ước về thành phần React của bạn sẽ được tải khi bạn làm việc với các tệp thành phần, các mẫu API của bạn sẽ được tải khi bạn làm việc với các bộ xử lý tuyến đường (route handlers), và các quy tắc kiểm thử sẽ được tải khi bạn viết test.

Yêu cầu bởi Tác nhân (Thông minh)

---
description: "Database migration patterns using Drizzle ORM"
alwaysApply: false
---

Không có globs, không luôn áp dụng, chỉ có mô tả. Tác nhân của Cursor đọc mô tả và quyết định xem quy tắc có liên quan đến nhiệm vụ hiện tại hay không. Nếu bạn yêu cầu nó viết một bản migration, nó sẽ kéo quy tắc này vào. Nếu bạn đang tạo kiểu cho một nút bấm, nó sẽ bỏ qua. Cách này hoạt động tốt đến ngạc nhiên đối với các quy tắc không ánh xạ neatly vào đường dẫn tệp.

Thủ công (Manual)

---
---

Không có trường frontmatter nào được đặt (hoặc frontmatter trống). Các quy tắc này chỉ kích hoạt khi bạn đề cập rõ ràng đến chúng bằng cú pháp @tên-quy-tắc trong chat. Phù hợp cho các hướng dẫn hiếm khi dùng nhưng quan trọng, như danh sách kiểm tra triển khai hoặc hướng dẫn tái cấu trúc mà bạn chỉ cần thỉnh thoảng.

Các mẫu Glob hoạt động hiệu quả

Globs xác định những tệp nào kích hoạt các quy tắc tự động đính kèm. Nếu đặt sai, quy tắc của bạn sẽ không bao giờ chạy hoặc chạy ở khắp mọi nơi. Dưới đây là những gì hoạt động:

# All TypeScript files in src
globs: ["src/**/*.ts", "src/**/*.tsx"]

# Only component files
globs: ["**/components/**/*.tsx"]

# Python files, excluding tests
globs: ["**/*.py", "!**/test_*.py"]

# Multiple specific directories
globs: ["src/api/**", "src/services/**"]

Một số lưu ý từ thực tế sử dụng:

• src/* chỉ khớp với một cấp thư mục. Bạn hầu như luôn muốn src/**/* để khớp đệ quy.
• *.js sẽ không khớp với các tệp .jsx hoặc .ts. Hãy chỉ định rõ phần mở rộng.
• Globs phải là một danh sách YAML. Cú pháp dấu ngoặc nhọn như {src,lib}/**/*.ts có thể thất bại âm thầm, hãy sticking với các mục danh sách riêng biệt.
• Tiền tố ! loại trừ các mẫu, hữu ích để bỏ qua các tệp được tạo tự động hoặc mã legacy.

Ví dụ quy tắc thực tế

Đây là nơi lý thuyết gặp thực tiễn. Đây là những quy tắc bạn có thể thêm vào dự án và ngay lập tức thấy chất lượng đầu ra của AI tốt hơn.

Quy tắc nền tảng toàn dự án (Luôn áp dụng)

---
alwaysApply: true
---

# Project: Acme Dashboard

## Tech Stack
- Next.js 15 (App Router only — no Pages Router)
- TypeScript strict mode
- Tailwind CSS v4
- Drizzle ORM with PostgreSQL
- pnpm for package management

## Critical Conventions
- All components are React Server Components by default
- Use "use client" only when the component needs interactivity
- Import paths use @/ alias mapped to src/
- Error handling: wrap async operations in try/catch, never use .catch()
- No default exports except for pages and layouts

Giữ quy tắc này dưới 30 dòng. Nó được tải với mọi yêu cầu, nên mỗi từ đều tiêu tốn token.

Quy tắc thành phần React (Tự động đính kèm)

---
description: "React component patterns and conventions"
globs: ["src/components/**/*.tsx", "src/app/**/*.tsx"]
alwaysApply: false
---

# React Component Rules

## Structure
Every component file follows this order:
1. Imports
2. Type definitions (Props interface)
3. Component function (named export)
4. Sub-components (if any)

## Patterns

Use named exports, not default:
- YES: `export function Button({ label }: ButtonProps)`
- NO: `export default function Button()`

For data fetching in Server Components:
```tsx
// Fetch directly in the component, no useEffect
export async function UserProfile({ id }: { id: string }) {
  const user = await db.query.users.findFirst({
    where: eq(users.id, id)
  });
  return <div>{user.name}</div>;
}

Anti-Patterns (NEVER do these)

• No useEffect for data fetching in Server Components
• No CSS modules — use Tailwind exclusively
• No barrel exports (index.ts re-exports)
• No prop drilling beyond 2 levels — use context or composition

### Quy tắc API Python (Tự động đính kèm)

```yaml
---
description: "FastAPI endpoint conventions and patterns"
globs: ["src/api/**/*.py", "src/routes/**/*.py"]
alwaysApply: false
---

# FastAPI Conventions

## Endpoint Structure
- Use APIRouter for route grouping
- Type all request/response models with Pydantic v2
- Dependency injection for database sessions

## Pattern
```python
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession

router = APIRouter(prefix="/users", tags=["users"])

@router.get("/{user_id}", response_model=UserResponse)
async def get_user(
    user_id: int,
    db: AsyncSession = Depends(get_db)
) -> UserResponse:
    user = await db.get(User, user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return UserResponse.model_validate(user)

Error Handling

• Always use HTTPException, not raw Response objects
• Log errors with structlog before raising
• Return consistent error shapes: {"detail": "message"}

### Quy tắc dịch vụ Go (Tự động đính kèm)

```yaml
---
description: "Go service patterns and error handling"
globs: ["**/*.go", "!**/*_test.go"]
alwaysApply: false
---

# Go Conventions

## Error Handling
- Always handle errors immediately — no _ for error returns
- Wrap errors with fmt.Errorf("context: %w", err)
- Use sentinel errors for expected failure cases

## Project Layout
- cmd/ for entrypoints
- internal/ for private packages
- pkg/ for public libraries

## Pattern
```go
func (s *UserService) GetByID(ctx context.Context, id string) (*User, error) {
    user, err := s.repo.Find(ctx, id)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
        }
        return nil, fmt.Errorf("fetching user %s: %w", id, err)
    }
    return user, nil
}

## Quản lý "Thuế Token"

Đây là điều mà hầu hết các hướng dẫn về Cursor bỏ qua: mọi quy tắc bạn viết đều tiêu tốn token. Một dự án với 20 quy tắc luôn bật có thể đốt cháy **hơn 2.000 token mỗi yêu cầu** chỉ cho các hướng dẫn, trước khi AI thậm chí nhìn vào mã của bạn.

Điều này quan trọng vì ngữ cảnh chat của Cursor khoảng 20.000 token ở chế độ tiêu chuẩn. Nếu các quy tắc của bạn ăn mất 25% con số đó, bạn đã mất một phần tư "không gian suy nghĩ" của AI dành cho câu hỏi thực tế của mình. Bạn sẽ nhận thấy chất lượng đầu ra kém đi khi các quy tắc chồng chất, đặc biệt trong các cuộc hội thoại dài.

Ba nguyên tắc giúp giữ ngân sách token của bạn lành mạnh:

**1. Sử dụng tích cực các quy tắc tự động đính kèm và yêu cầu bởi tác nhân.** Chỉ khai báo ngăn xếp dự án của bạn nên được đặt là luôn bật. Mọi thứ khác nên được tải có điều kiện. Quy tắc thành phần React kia? Nó không cần nằm trong ngữ cảnh khi bạn đang viết các bản migration SQL.

**2. Viết cô đọng, không dài dòng.** Thay thế "Khuyến nghị mạnh mẽ rằng các nhà phát triển sử dụng interface TypeScript thay vì type aliases khi định nghĩa các hợp đồng API công khai" bằng "Ưu tiên `interface` hơn `type` cho các API công khai." AI không cần sự thuyết phục, nó cần hướng dẫn.

**3. Áp dụng Quy tắc Ba.** Chỉ mã hóa một mẫu thành quy tắc sau khi AI hiểu sai nó ba lần. Nếu Cursor đã xử lý đúng các quy ước đặt tên của bạn mà không cần quy tắc, hãy bỏ qua quy tắc đó. Mỗi quy tắc không cần thiết là ngữ cảnh lãng phí.

Bạn có thể theo dõi việc sử dụng token trong thanh trạng thái ở cuối bảng chat của Cursor. Hãy chú ý khi nó tiến gần 100%, đó là tín hiệu để bạn cắt giảm.

## Tổ chức quy tắc cho một dự án thực tế

Một dự án sản xuất thường cần 5-8 tệp quy tắc. Dưới đây là cấu trúc hoạt động tốt:

```text
.cursor/rules/
  base.mdc            # Tech stack, always-apply (< 30 lines)
  components.mdc      # React/Vue patterns, glob to component dirs
  api.mdc             # Backend conventions, glob to API dirs
  database.mdc        # ORM patterns, glob to models/migrations
  testing.mdc         # Test conventions, glob to test files
  deployment.mdc      # CI/CD patterns, manual trigger
  personal.mdc        # Your preferences (gitignored)

Commit mọi thứ vào hệ thống kiểm soát phiên bản ngoại trừ personal.mdc. Bằng cách đó, toàn bộ nhóm của bạn có cùng hành vi AI, đó chính là mục đích chính. Như một người dùng trên diễn đàn Cursor nói, các quy tắc tốt nghĩa là "bạn chấp nhận nhiều đề xuất hơn ngay lập tức, với đầu ra khớp với các quy ước của bạn ngay từ lần thử đầu tiên."

Nếu bạn đang làm việc với các công cụ lập trình AI khác bên cạnh Cursor, các khái niệm này chuyển giao trực tiếp. Claude Code sử dụng CLAUDE.md, GitHub Copilot có các tệp hướng dẫn, và Windsurf có định dạng riêng, nhưng nguyên lý cơ bản là giống hệt nhau.

Cách hoạt động của thứ tự ưu tiên quy tắc

Khi nhiều quy tắc áp dụng cho cùng một tệp, Cursor tuân theo một hệ thống phân cấp rõ ràng:

Quy tắc nhóm có sẵn trên các gói Team và Enterprise. Chúng được quản trị viên thiết lập trong bảng điều khiển Cursor và được thực thi trên toàn tổ chức, các nhà phát triển cá nhân không thể tắt chúng.

Trong các quy tắc dự án, nếu hai quy tắc áp dụng cho cùng một tệp và xung đột, hành vi không được định nghĩa chặt chẽ. Trong thực tế, các quy tắc được tải sau có xu hướng được ưu tiên. Đánh số các tệp của bạn (001-base.mdc, 002-components.mdc) giúp bạn có thứ tự dự đoán được.

Lỗi phổ biến và cách khắc phục

Sau khi đọc qua hàng chục luồng thảo luận cộng đồng và thử nghiệm các quy tắc trên nhiều dự án, đây là những lỗi khiến mọi người gặp khó khăn nhất:

Viết các quy tắc quá mơ hồ. "Viết mã sạch" không nói cho AI điều gì cả. "Sử dụng named exports, không phải default exports. Cấu trúc thành phần theo thứ tự: imports, types, function, sub-components" cung cấp cho nó điều gì đó có thể hành động.

Biến mọi thứ thành luôn áp dụng. Bản năng đầu tiên của bạn là đặt alwaysApply: true cho mọi quy tắc. Hãy kháng cự lại điều đó. Kiểm toán các quy tắc của bạn hàng quý, nếu bạn có nhiều hơn 2-3 quy tắc luôn bật, có lẽ bạn đang lãng phí token.

Quên kiểm thử quy tắc. Sau khi viết quy tắc, hãy mở một tệp liên quan và yêu cầu Cursor tạo ra thứ gì đó phải tuân theo quy tắc. Nếu nó không làm vậy, mẫu glob của bạn có thể sai, hoặc hướng dẫn chưa đủ rõ ràng.

Không ghi lại các anti-pattern. Nói với AI những gì cần làm chỉ là nửa công việc. Nói với nó những gì không nên làm là nửa còn lại. Bao gồm một phần "KHÔNG BAO GIỜ làm những điều này" trong mỗi quy tắc với các ví dụ rõ ràng về cách tiếp cận sai.

Bỏ qua việc lưu quy tắc trong giao diện người dùng. Một lỗi đã biết khiến các chỉnh sửa quy tắc biến mất. Nếu các thay đổi biến mất, hãy đóng hoàn toàn Cursor, chọn "Override" trên popup thay đổi chưa lưu và mở lại.

Quy tắc Cursor so với CLAUDE.md so với AGENTS.md

Cursor không phải là công cụ duy nhất sử dụng các tệp hướng dẫn. Dưới đây là cách so sánh các định dạng cho bất kỳ ai làm việc trên nhiều trợ lý lập trình AI:

Lợi thế của Cursor là độ chi tiết. CLAUDE.md và AGENTS.md đơn giản hơn, chúng tải mọi thứ luôn luôn. Cursor cho phép bạn tải đúng quy tắc vào đúng thời điểm, điều này quan trọng một khi bộ hướng dẫn của bạn vượt quá vài trăm dòng.

Để tìm hiểu sâu hơn về cách ngữ cảnh định hình đầu ra AI trên các công cụ này, hướng dẫn kỹ thuật ngữ cảnh của chúng tôi phân tích các nguyên tắc áp dụng bất kể bạn sử dụng trình soạn thảo nào.

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

.cursorrules có bị phản đối không?

Có. Tệp .cursorrules duy nhất tại thư mục gốc dự án của bạn vẫn hoạt động, nhưng Cursor khuyến nghị chuyển sang các tệp .cursor/rules/*.mdc. Định dạng mới hỗ trợ mẫu glob, tải có điều kiện và tổ chức tốt hơn. Hãy di chuyển bằng cách tách tệp đơn khối của bạn thành các quy tắc tập trung.

Tôi nên sử dụng phần mở rộng tệp nào, .mdc hay .md?

Sử dụng .mdc cho các tệp bao gồm YAML frontmatter (description, globs, alwaysApply). Các tệp .md thuần túy cũng hoạt động trong thư mục quy tắc nhưng không hỗ trợ siêu dữ liệu frontmatter cho phép tải có điều kiện.

Một dự án nên có bao nhiêu quy tắc?

Năm đến tám là điểm ngọt cho hầu hết các dự án. Một quy tắc nền tảng luôn bật, ba đến bốn quy tắc tự động đính kèm được giới hạn theo loại tệp, và một hoặc hai quy tắc thủ công cho các nhiệm vụ đặc biệt. Nhiều hơn 10 quy tắc thường có nghĩa là một số quy tắc có thể được hợp nhất hoặc loại bỏ.

Quy tắc Cursor có ảnh hưởng đến tự động hoàn thành và tab completion không?

Quy tắc áp dụng cho chat và tương tác tác nhân. Quy tắc người dùng không áp dụng cho các chỉnh sửa nội tuyến (Cmd/Ctrl+K), và các quy tắc nói chung không ảnh hưởng đến các đề xuất tự động hoàn thành Cursor Tab. Chúng hiệu quả nhất trong các phiên chat và Composer.

Tôi có thể chia sẻ quy tắc giữa nhiều dự án không?

Có, thông qua tính năng Remote Rules của Cursor. Đi tới Cursor Settings > Rules, Commands, chọn "Remote Rule (GitHub)," và dán URL kho lưu trữ. Các quy tắc sẽ tự động đồng bộ khi repo nguồn cập nhật. Ngoài ra, hãy duy trì một repo quy tắc chung và tạo symlink vào mỗi dự án.

Độ dài quy tắc tối đa được khuyến nghị là bao nhiêu?

Tài liệu của Cursor gợi ý giữ các quy tắc riêng lẻ dưới 500 dòng. Trong thực tế, hãy nhắm đến dưới 100 dòng mỗi quy tắc. Các quy tắc ngắn hơn dễ bảo trì hơn và tiêu tốn ít token hơn. Nếu một quy tắc vượt quá 150 dòng, hãy chia nó thành hai quy tắc tập trung.

Quy tắc có hoạt động với tất cả các mô hình AI trong Cursor không?

Quy tắc hoạt động với mọi mô hình mà Cursor hỗ trợ, Claude, GPT-4o, Gemini và các mô hình khác. Các quy tắc được chèn vào như ngữ cảnh cấp hệ thống bất kể bạn đã chọn mô hình nào. Hành vi của mô hình có thể khác nhau, nhưng bản thân các quy tắc thì độc lập với mô hình.

Làm thế nào để gỡ lỗi một quy tắc không hoạt động?

Thứ nhất, xác minh mẫu glob khớp với tệp của bạn, mở tệp và kiểm tra xem quy tắc có xuất hiện trong bảng ngữ cảnh không. Thứ hai, kiểm tra với một câu hỏi trực tiếp lẽ ra phải kích hoạt quy tắc. Thứ ba, thử đặt tạm thời alwaysApply: true để xác nhận nội dung quy tắc hoạt động. Nếu có, vấn đề nằm ở mẫu glob của bạn.

Tôi có nên commit .cursor/rules vào git không?

Chắc chắn rồi. Toàn bộ điểm của quy tắc dự án là sự nhất quán trên toàn nhóm. Commit mọi thứ trong .cursor/rules/ ngoại trừ các tệp sở thích cá nhân. Thêm personal.mdc vào .gitignore cho các cài đặt cá nhân không nên áp dụng cho mọi người.

Tôi có thể sử dụng quy tắc Cursor cùng với các máy chủ MCP không?

Có, và chúng bổ sung cho nhau rất tốt. Quy tắc định nghĩa cách AI nên viết mã, trong khi máy chủ MCP cung cấp cho AI quyền truy cập vào các công cụ và dữ liệu bên ngoài. Một quy tắc có thể nói "luôn sử dụng client API nội bộ của chúng tôi," trong khi máy chủ MCP cho phép AI thực sự truy vấn API đó trong quá trình phát triển.

Nếu các tính năng AI nằm trong lộ trình của bạn, đó là chuyên môn của chúng tôi: đội ngũ tích hợp AI của Techsy đưa các hệ thống LLM từ nguyên mẫu đến sản xuất. Muốn có ý kiến thứ hai về ngăn xếp của bạn? Nhận tư vấn miễn phí.

Nguồn

• Tài liệu Quy tắc Cursor
• Trigger.dev, Cách viết Quy tắc Cursor tuyệt vời
• Diễn đàn Cursor, Thực hành tốt nhất và Khắc phục sự cố Quy tắc MDC
• Peakvance, Hướng dẫn về Quy tắc Cursor: Thuế Token
• awesome-cursor-rules-mdc trên GitHub