Quy tắc Cursor: Cách giữ AI phù hợp với mã nguồn của bạn

Bạn mở một cuộc trò chuyện mới trong Cursor và dán lại cùng một khối hướng dẫn đã dán cả trăm lần trước. Ngăn xếp công nghệ, quy ước đặt tên, và cấu trúc thư mục thì AI cứ làm sai mãi. Rồi nó tạo ra một lớp 40 dòng với ba tầng trừu tượng cho một việc chỉ cần một hàm.

Đã đến lúc tỉnh khỏi cơn ác mộng này. Quy tắc Cursor là các tệp dự án giúp bạn không cần dán lặp lại. Viết quy ước một lần, và đầu ra của AI sẽ khớp với codebase của bạn thay vì chống lại nó.

Hướng dẫn này xây dựng một bộ tệp quy tắc .mdc cho dự án web Python dùng FastAPI và pytest, bao gồm ngữ cảnh dự án, sự đơn giản của mã, và định dạng lỗi API. Nếu bạn mới dùng Cursor, tôi khuyên nên học khóa Phát triển phần mềm với Cursor trước, sau đó mở một dự án và làm theo.

Cursor Rules là gì?

Quy tắc Cursor là các tệp markdown với frontmatter đặc thù MDC nằm trong dự án của bạn tại .cursor/rules/. Trước khi lời nhắc của bạn đến mô hình, Cursor kiểm tra quy tắc nào khớp và ghép nội dung của chúng vào đầu cửa sổ ngữ cảnh. Hướng dẫn của bạn luôn xuất hiện trước, mỗi lần đều như vậy.

Mỗi tệp .mdc có ba trường frontmatter điều khiển kích hoạt: description, globs và alwaysApply. Một quy tắc có thể kích hoạt trong mọi cuộc trò chuyện hoặc chỉ khi một số tệp nhất định đang mở. Tùy chọn thứ ba, Áp dụng thông minh, cho phép tác tử đọc phần mô tả và tự quyết định liệu quy tắc có liên quan hay không. Phần tiếp theo sẽ thực hành từng loại.

Cursor hỗ trợ bốn danh mục quy tắc:

Quy tắc dự án đã thay thế tệp .cursorrules cũ, một tệp duy nhất ở cấp gốc không có phạm vi hay metadata, bằng cách tách thành nhiều tệp .mdc với frontmatter.

AGENTS.md là lựa chọn đơn giản hơn cho các dự án không cần phạm vi theo glob. Đây là markdown thuần được các công cụ AI viết mã ngoài Cursor nhận diện, và các tệp sâu hơn trong thư mục con sẽ ghi đè tệp ở thư mục cha.

Bạn có thể tìm hiểu thêm về cách quy trình làm việc dựa trên tác tử kết nối với quy trình phát triển của bạn trong lộ trình kỹ năng Kiến thức nền tảng về AI Agent của chúng tôi.

Tạo và cấu hình Quy tắc Dự án của Cursor

Phần còn lại của hướng dẫn này xây dựng các tệp quy tắc cho dự án FastAPI dùng pytest. Mẫu này có thể áp dụng cho mọi ngăn xếp.

Thiết lập thư mục và tệp quy tắc

Tạo thư mục .cursor/rules/ ở thư mục gốc dự án. Mọi tệp .mdc bạn đặt vào đây sẽ trở thành một quy tắc mà Cursor nhận ngay lập tức, không cần khởi động lại.

Tệp quy tắc đầu tiên, project-context.mdc, giúp AI luôn nắm rõ ngăn xếp và bố cục thư mục của bạn:

---
description: ""
alwaysApply: true
globs:
---
 
# Project Context
 
This is a FastAPI web application with pytest for testing.
 
## Tech Stack
- Python 3.12, FastAPI, Pydantic v2, SQLAlchemy 2.0
- pytest with pytest-asyncio for async test support
- Alembic for database migrations
 
## Project Structure
- app/main.py: FastAPI application entry point
- app/routers/: API route handlers
- app/models/: SQLAlchemy models
- app/schemas/: Pydantic request/response schemas
- tests/: pytest test files mirroring app/ structure
 
## Patterns
- All endpoints are async
- Use dependency injection for database sessions
- Response models are always Pydantic schemas, not raw dictsĐược hỗ trợ bởi

Gõ /create-rule trong một cuộc trò chuyện với Agent là một cách khác: Cursor sẽ soạn thảo giúp bạn qua một bảng trò chuyện.

Phần frontmatter alwaysApply: true nghĩa là quy tắc này được tải trong mọi cuộc trò chuyện. Đặt tên tệp theo kebab-case theo từng mối quan tâm (project-context.mdc, simplicity.mdc, error-responses.mdc) và giữ mỗi tệp dưới 500 dòng. Tệp quy tắc cồng kềnh sẽ ngốn không gian cửa sổ ngữ cảnh mà bạn cần cho mã và lời nhắc thực tế. Hãy commit thư mục .cursor/rules/ vào git.

Cấu hình metadata của quy tắc để khớp chính xác

Quy tắc project-context.mdc ở trên dùng alwaysApply: true, chế độ đơn giản nhất: mọi cuộc trò chuyện đều tải nó bất kể bạn đang làm việc với tệp nào. Đây là lựa chọn đúng cho ngữ cảnh cấp dự án.

Một số quy tắc chỉ áp dụng cho một số phần của codebase. Đặt alwaysApply: false và thêm các mẫu glob dạng danh sách phân tách bằng dấu phẩy để giới hạn phạm vi. Một quy tắc với globs: app/routers/**/*.py chỉ kích hoạt khi các tệp khớp (ở đây: các tệp Python trong app/routers/ hoặc thư mục con) xuất hiện trong ngữ cảnh, tránh đưa quy ước API vào những cuộc trò chuyện không liên quan.

Áp dụng thông minh bỏ qua hoàn toàn mẫu tệp. Bạn để trống globs và viết một description chi tiết, rồi tác tử quyết định liệu quy tắc có liên quan đến cuộc trò chuyện hiện tại hay không. Chất lượng mô tả rất quan trọng: "Error handling rules" quá mơ hồ để tác tử ghép khớp đáng tin cậy, nhưng "Conventions for FastAPI error responses including HTTP status codes, error body structure, and exception handler patterns" có tín hiệu rõ ràng.

Các quy tắc không có glob, không có mô tả có ý nghĩa và alwaysApply: false sẽ trở thành chế độ thủ công, được tải khi bạn gõ @rule-name trong chat. Hữu ích cho tư liệu tham khảo bạn muốn kéo vào khi cần.

Viết nội dung và ràng buộc của quy tắc

Các quy tắc viết bằng ngôn ngữ mềm mỏng ("cố gắng giữ hàm nhỏ", "ưu tiên endpoint async") sẽ cho phép AI bỏ qua. Hãy viết mệnh lệnh thay vì gợi ý: "Hàm phải dưới 30 dòng. Tất cả endpoint phải là async."

Phần mở đầu đề cập việc AI tạo ra một lớp 40 dòng với ba tầng trừu tượng. Quy tắc ngăn hành vi đó là simplicity.mdc:

---
description: ""
alwaysApply: true
globs:
---
 
# Code Simplicity
 
Write the simplest code that solves the problem. Every abstraction must earn its place.
 
## Constraints
- No base classes with one child class
- No interfaces or abstract classes with one implementation
- No factory or strategy patterns when an if statement works
- No wrapper functions that just call another function
- No configurable parameters that nothing passes
- No "just in case" error handling for impossible conditions
 
## When modifying existing code
- Match the patterns already in the codebase
- Do not refactor surrounding code unless asked
- Do not add type annotations to unchanged code
- Do not add docstrings to unchanged functions
 
## Code size
- Functions under 30 lines
- If a function needs a comment explaining what a block does, extract that block into a named function insteadĐược hỗ trợ bởi

Sự khác biệt là ngay lập tức. AI ngừng tìm đến các lớp cơ sở trừu tượng khi chỉ có một hiện thực, và dùng câu lệnh if khi chỉ có hai trường hợp.

Quy tắc thứ ba, error-responses.mdc, được giới hạn bằng glob để chỉ kích hoạt khi làm việc với các tệp route API:

---
description: "Standard error response format for all API endpoints"
alwaysApply: false
globs: app/routers/**/*.py
---
 
# API Error Responses
 
All error responses must follow this structure:
 
{
  "detail": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "field": "optional_field_name"
}
 
## Rules
- Never return raw exception messages to clients
- Use HTTPException with a detail dict matching the structure above
- 400 for validation errors, 404 for missing resources, 409 for conflicts
- Log the full traceback server-side before returning the sanitized responseĐược hỗ trợ bởi

Khi có thể, hãy trỏ đến các tệp hiện có trong codebase thay vì sao chép mã vào quy tắc. Một dòng như "Xem app/routers/users.py để biết cấu trúc endpoint chuẩn" sẽ luôn chính xác khi mã tiến hóa, trong khi đoạn mã sao chép sẽ lỗi thời ngay khi ai đó refactor bản gốc.

Kiểm thử và xác minh quy tắc được đính kèm

Cursor không có chỉ báo tích hợp cho biết quy tắc nào đang hoạt động trong một cuộc trò chuyện. Bạn xác minh bằng cách kiểm thử hành vi.

Mở một cuộc trò chuyện với Agent mới và viết một prompt đáng lẽ sẽ kích hoạt một trong các quy tắc của bạn. Với error-responses.mdc, hãy thử: "Thêm endpoint DELETE để xóa người dùng theo ID trong app/routers/users.py." Nếu xử lý lỗi được tạo ra không giống cấu trúc JSON trong quy tắc của bạn hoặc bỏ qua HTTPException với detail dict, thì có gì đó sai trong phần khớp.

Các quy tắc giới hạn bằng glob cần có tệp khớp được tham chiếu trong prompt của bạn hoặc đang mở trong trình chỉnh sửa. Kiểm thử error-responses.mdc mà không nhắc tới tệp nào dưới app/routers/ nghĩa là quy tắc sẽ không bao giờ kích hoạt. 

Các quy tắc "Áp dụng thông minh" dựa trên chủ đề: hãy thử một prompt liên quan tới mô tả của quy tắc, rồi một prompt không liên quan, và so sánh kết quả. Tác tử nên tuân theo quy tắc ở prompt đầu và bỏ qua ở prompt sau.

Giữ cho Quy tắc Cursor hiệu quả

Các quy tắc hoạt động tháng trước có thể gây hiểu nhầm cho AI sau một lần refactor hoặc đổi tên thư mục.

Khắc phục sự cố khi khớp thất bại

Lý do phổ biến nhất khiến quy tắc không kích hoạt là phần mở rộng tệp: quy tắc phải dùng .mdc, và các tệp .md thuần trong .cursor/rules/ sẽ bị bỏ qua trong im lặng.

Ngoài ra còn có:

• Glob quá rộng như **/*.py gắn quy tắc vào mọi tệp Python trong dự án. Hãy thu hẹp thành app/routers/**/*.py hoặc tests/**/*.py để quy tắc chỉ kích hoạt ở nơi cần.

• Bạn sẽ nhận thấy các quy tắc "Áp dụng thông minh" bỏ sót cuộc trò chuyện khi mô tả quá chung chung. Các ví dụ mô tả tốt/xấu từ phần metadata ở trên cũng áp dụng tại đây.

• Các quy tắc xung đột khó phát hiện hơn. Khi hai quy tắc đưa ra hướng dẫn mâu thuẫn cho cùng tệp, AI sẽ chọn một (thường là quy tắc được tải sau). Khắc phục bằng cách thu hẹp phạm vi glob để các quy tắc không chồng lấp, hoặc hợp nhất hướng dẫn liên quan vào một tệp duy nhất.

Một điểm lạ đáng biết: thay đổi trong các tệp .mdc đôi khi biến mất mà không được lưu. Nếu chỉnh sửa không lưu lại, hãy đóng hẳn Cursor, chọn "Override" trên cửa sổ bật lên về thay đổi chưa lưu, rồi mở lại.

Giữ quy tắc hiệu lực giữa cuộc trò chuyện

Một quy tắc có thể kích hoạt đúng ở đầu cuộc trò chuyện nhưng vẫn bị phớt lờ sau năm tin nhắn. Nguyên nhân là thiên lệch gần đây của cửa sổ ngữ cảnh: khi cuộc trò chuyện dài ra, mô hình ưu tiên các thông điệp gần đây hơn so với hướng dẫn được chèn ở đầu. Đây là phàn nàn phổ biến nhất trong cộng đồng Cursor, và không có cài đặt nào khắc phục triệt để.

Cách xử lý là củng cố. Khi đầu ra bắt đầu lệch khỏi quy tắc, thêm một dòng kiểu "hãy tuân thủ các quy tắc dự án cho phản hồi lỗi" vào prompt tiếp theo của bạn. Điều đó đưa hướng dẫn trở lại vào ngữ cảnh gần đây của mô hình. 

Với các quy tắc quan trọng ở mọi phản hồi (định dạng, đặt tên), cách diễn đạt ngắn gọn, trực diện sẽ bền vững hơn các đoạn mô tả dài trong những cuộc trò chuyện dài.

Các quy tắc có ví dụ mã cũng chống trôi tốt hơn hướng dẫn chỉ bằng văn bản. Thay vì viết "dùng early return để xử lý lỗi", hãy kèm một khối trước/sau ngắn thể hiện mẫu bạn muốn. Mô hình bám vào mã thực tế đáng tin cậy hơn mô tả bằng lời, đặc biệt khi ngữ cảnh dày lên.

Duy trì và cắt giảm quy tắc

Rà soát quy tắc sau mọi lần refactor lớn, nâng cấp phụ thuộc, hoặc tái cấu trúc thư mục. Một quy tắc tham chiếu API đã bỏ hoặc tệp đã xóa sẽ cung cấp hướng dẫn sai cho AI. Glob lỗi thời còn âm thầm hơn: đổi tên app/api/ thành app/routers/ và một quy tắc giới hạn theo đường dẫn cũ sẽ chỉ lẳng lặng ngừng kích hoạt.

Cắt giảm cũng đi theo chiều ngược lại. Khi mô hình cải thiện, chúng tự nắm bắt các quy ước phổ biến mà không cần được nhắc. Nếu AI đã tuân theo hướng dẫn của một quy tắc mà không cần nhắc, hãy xóa quy tắc đó để lấy lại token. Một bộ quy tắc lành mạnh sẽ nhỏ dần theo thời gian, chứ không chỉ phình to.

Mở rộng quy tắc cho môi trường làm việc nhóm

Hãy đối xử với quy tắc như mã ứng dụng. Thay đổi đi qua pull request, và nhóm thống nhất mẫu trước khi đưa vào .cursor/rules/.

Với các tổ chức dùng gói Business hoặc Enterprise, Quy tắc Nhóm cho phép quản trị viên áp dụng quy tắc cho tất cả thành viên từ bảng điều khiển Cursor. "Bật ngay" khiến quy tắc hoạt động theo mặc định nhưng vẫn cho phép người dùng tắt. "Buộc áp dụng quy tắc này" loại bỏ khả năng từ chối, phù hợp với các quy ước không thể thương lượng như thực hành bảo mật và yêu cầu tuân thủ.

Kết luận

Bắt đầu với một hoặc hai quy tắc cho các mẫu bạn thường xuyên phải sửa nhất. Nếu bạn cứ phải chỉnh cùng một kiểu đầu ra AI mỗi phiên (định dạng lỗi sai, trừu tượng thừa), đó là một quy tắc đang chờ được viết. Thêm dần khi phát hiện lỗi lặp lại, và loại bỏ những quy tắc không còn hữu ích.

Các tệp .mdc trong hướng dẫn này phù hợp với dự án FastAPI. Dự án của bạn sẽ trông khác với frontend Next.js hoặc công cụ dòng lệnh Rust, và đó chính là mục đích: chúng mã hóa quy ước của nhóm bạn, không phải các thông lệ chung chung. 

Nếu bạn muốn tìm hiểu sâu hơn về Cursor, hãy xem hướng dẫn Cursor 2.0 của chúng tôi. Để so sánh với các trợ lý viết mã AI khác, tôi khuyên đọc các bài so sánh sau:

• Cursor và GitHub Copilot
• Claude Code và Cursor
• Cline và Cursor
• Cursor và Windsurf