Quy tắc và cấu hình Cursor

Giúp Cursor thông minh hơn vĩnh viễn

🔄 Trong Bài học 5, bạn đã học về chế độ Agent — mạnh mẽ nhưng hay quên. Mỗi cuộc hội thoại mới bắt đầu từ đầu. Agent không nhớ rằng bạn thích các thành phần chức năng, ghét dấu chấm phẩy, hay luôn sử dụng Tailwind CSS.

Các quy tắc và cấu hình khắc phục điều này. Chúng là lớp ngữ cảnh bền vững — những hướng dẫn áp dụng cho mọi tương tác AI trong dự án của bạn, mà không cần bạn phải lặp lại chúng.

File quy tắc: Sổ tay AI của dự án

Các quy tắc cho Cursor biết cách hoạt động trong dự án của bạn. Chúng là các file văn bản mà AI đọc trước mỗi tương tác.

Cách tiếp cận hiện đại: .cursor/rules/

Tạo thư mục .cursor/rules/ trong thư mục gốc của dự án. Mỗi file .mdc xử lý một chủ đề cụ thể:

📍 Nơi dán: Mở ChatGPT (chat.openai.com), Claude (claude.ai) hoặc Gemini (gemini.google.com) và bắt đầu một cuộc hội thoại mới.

📋 Cách sao chép prompt này: Nhấp vào bất kỳ đâu bên trong khối màu xám, nhấn Cmd+A rồi Cmd+C (Mac) hoặc Ctrl+A rồi Ctrl+C (Windows). Hoặc sử dụng biểu tượng sao chép xuất hiện.

.cursor/rules/
├── general.mdc          # Quy ước chung của dự án
├── testing.mdc          # Cách viết bài test
├── api-patterns.mdc     # Cấu trúc và mẫu API
└── component-style.mdc  # Quy ước về thành phần giao diện người dùng

✏️ ​​Cách điền thông tin chi tiết của bạn: Thay thế mỗi dấu ngoặc vuông [] và trình giữ chỗ trong ngoặc bằng thông tin cụ thể từ tình huống thực tế của bạn. Thông tin đầu vào mơ hồ sẽ tạo ra kết quả mơ hồ — hãy cụ thể.

👀 Những gì bạn sẽ thấy: Trong vòng vài giây, AI sẽ trả về một phản hồi có cấu trúc dựa trên prompt ở trên. Hãy đọc kỹ và coi đó là bản nháp, không phải câu trả lời cuối cùng.

📌 Cách xử lý kết quả: Lưu phản hồi vào file Notes. Chọn đề xuất có hiệu quả cao nhất và thực hiện ngay trong tuần này — đừng cố gắng làm tất cả cùng một lúc.

⚠️ Nếu kết quả không ổn: Nếu các đề xuất có vẻ chung chung, hãy dán nội dung sau: "Hãy cụ thể hơn với ngữ cảnh thực tế của tôi. Bỏ qua những lời khuyên chung chung." Nếu bỏ qua các chi tiết quan trọng bạn đã cung cấp, hãy hỏi: "Bạn đã bỏ sót [X] trong ngữ cảnh của tôi — hãy thực hiện lại với điều đó làm ràng buộc chính."

Ví dụ general.mdc:

# Quy ước dự án

- Sử dụng chế độ Strict của TypeScript cho tất cả các file
- Ưu tiên các thành phần chức năng hơn những thành phần lớp
- Sử dụng xuất có tên, không phải xuất mặc định
- Thông báo lỗi nên thân thiện với người dùng, không mang tính kỹ thuật
- Không bao giờ sử dụng console.log trong code sản xuất — hãy sử dụng dịch vụ ghi nhật ký
- Tất cả các phản hồi API đều tuân theo cấu trúc { data, error, meta }

Ví dụ testing.mdc:

# Quy tắc test

- Sử dụng Vitest, không phải Jest
- Mỗi hàm mới cần ít nhất một bài test
- File test nằm cạnh file nguồn: foo.ts → foo.test.ts
- Sử dụng tên test mô tả: "nên trả về 404 khi không tìm thấy người dùng"
- Giả lập các dịch vụ bên ngoài, không bao giờ gọi API thực trong các bài test

Định dạng cũ: .cursorrules

Bạn sẽ thấy các tham chiếu đến .cursorrules — một file duy nhất ở thư mục gốc của dự án. Nó vẫn hoạt động nhưng đã lỗi thời. Nếu bạn đã có sẵn một file cấu hình, cứ tiếp tục sử dụng nó. Đối với các dự án mới, hãy sử dụng .cursor/rules/*.mdc.

Thực tiễn tốt nhất cho các quy tắc

Giữ các quy tắc tổng cộng dưới 500 dòng. Trí tuệ nhân tạo (AI) có ngữ cảnh hạn chế. Các quy tắc quá dài sẽ làm lu mờ ngữ cảnh code thực tế.

Hãy đưa ra các ví dụ thực tế. Đừng chỉ nói "hãy tuân theo các mẫu RESTful". Hãy đưa ra một ví dụ hoàn chỉnh về một endpoint được cấu trúc tốt. AI bắt chước các ví dụ tốt hơn là tuân theo những hướng dẫn trừu tượng.

Thêm các quy tắc một cách dần dần. Bắt đầu với một thư mục quy tắc trống. Khi AI mắc cùng một lỗi hai lần — sai kiểu nhập, sai framework test, sai cách xử lý lỗi — hãy thêm một quy tắc cho lỗi đó. Đừng cố gắng dự đoán mọi thứ ngay từ đầu.

Chia sẻ với nhóm của bạn. Commit .cursor/rules/ vào kho lưu trữ của bạn. Giờ đây, mọi thành viên trong nhóm đều có được hành vi nhất quán của AI.

✅ Kiểm tra nhanh: Nhóm của bạn có một quy tắc nói rằng "Sử dụng các lớp CSS của Tailwind, không bao giờ viết CSS tùy chỉnh." Nhưng bạn vừa yêu cầu Cursor tạo kiểu cho một thành phần và nó vẫn viết CSS tùy chỉnh. Vấn đề có khả năng xảy ra nhất là gì?

Câu trả lời: File quy tắc có thể không nằm đúng vị trí (thư mục .cursor/rules/), hoặc file quy tắc có thể có lỗi cú pháp. Kiểm tra xem file .mdc đã được lưu đúng cách và Cursor đã lập chỉ mục cho nó chưa (bạn có thể xem các quy tắc đang hoạt động trong bảng Composer). Ngoài ra, các quy tắc chỉ là hướng dẫn, không phải là ràng buộc cứng nhắc — việc cụ thể hơn trong quy tắc ("Luôn sử dụng các lớp tiện ích Tailwind như className='flex items-center gap-2'") sẽ cho kết quả tốt hơn.

Quy tắc toàn hệ thống

Một số tùy chọn áp dụng cho tất cả các dự án của bạn, không chỉ một dự án. Thiết lập những tùy chọn này trong Settings > General > Rules for AI.

Các quy tắc toàn hệ thống tốt:

• "Luôn sử dụng tiếng Anh cho các bình luận code"
• "Ưu tiên code ngắn gọn hơn code dài dòng"
• "Giải thích lý do của bạn khi đưa ra các lựa chọn không rõ ràng"

Các quy tắc toàn hệ thống kết hợp với những quy tắc dự án. Các quy tắc dự án sẽ ghi đè lên những quy tắc toàn cục khi chúng xung đột.

Notepad: Các gói ngữ cảnh có thể tái sử dụng

Notepad nằm trong thanh bên AI. Chúng là các khối văn bản đã lưu có thể chứa những tham chiếu @, hướng dẫn và ví dụ code.

Khi nào Notepad phát huy hiệu quả:

• Đánh giá code định kỳ: Tạo một Notepad với danh sách kiểm tra và tiêu chuẩn đánh giá của bạn. Tham chiếu đến nó bất cứ khi nào bạn yêu cầu Cursor đánh giá code.
• Tạo thành phần: Một Notepad với các mẫu thành phần của hệ thống thiết kế của bạn, được tham chiếu khi tạo những thành phần mới.
• Tài liệu API: Một Notepad mô tả cấu trúc API, xác thực và hình dạng phản hồi của bạn.

Cách tạo:

1. Mở thanh bên AI.
2. Chuyển đến tab Notepads.
3. Tạo một Notepad mới với tên mô tả.
4. Thêm nội dung của bạn, bao gồm cả các tham chiếu @.

Cách sử dụng:

Trong bất kỳ cuộc trò chuyện nào, hãy nhập tên Notepad (Cursor tự động gợi ý). Toàn bộ ngữ cảnh của Notepad sẽ được đưa vào cuộc trò chuyện.

Điểm khác biệt chính so với quy tắc:

Quy tắc được áp dụng tự động cho mọi tương tác của AI. Notepad chỉ được áp dụng khi bạn tham chiếu chúng một cách rõ ràng. Sử dụng quy tắc cho các hướng dẫn "luôn luôn làm điều này". Sử dụng Notepad cho ngữ cảnh "làm điều này khi tôi yêu cầu".

Tài liệu tùy chỉnh

Bạn có thể cho Cursor biết về tài liệu của bất kỳ thư viện, framework hoặc API nào:

1. Vào Settings > Features > Docs
2. Nhấp vào Add new doc
3. Dán URL của tài liệu
4. Cursor sẽ thu thập thông tin và lập chỉ mục

Bây giờ, khi bạn nhập @Docs trong khung chat, tài liệu đó sẽ xuất hiện dưới dạng tùy chọn. AI sẽ tham chiếu đến tài liệu thực tế thay vì dựa vào dữ liệu huấn luyện có thể đã lỗi thời.

Thêm tài liệu cho:

• Các thư viện mà dự án của bạn phụ thuộc (đặc biệt là những thư viện ít phổ biến hơn)
• API và dịch vụ nội bộ mà nhóm của bạn duy trì
• Tài liệu framework cho phiên bản bạn đang sử dụng

MCP: Kết nối các công cụ bên ngoài

MCP (Model Context Protocol) là một hệ thống plugin mở rộng khả năng của Cursor Agent với các chức năng bên ngoài.

MCP cho phép: Agent có thể tương tác với cơ sở dữ liệu, công cụ quản lý dự án, nền tảng thiết kế, dịch vụ đám mây — bất cứ thứ gì có MCP server.

Cấu hình: Tạo .cursor/mcp.json trong thư mục gốc dự án của bạn (dành riêng cho dự án) hoặc ~/.cursor/mcp.json (toàn hệ thống):

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server"],
      "env": {
        "SUPABASE_URL": "url-dự-án-của-bạn",
        "SUPABASE_KEY": "key-của-bạn"
      }
    }
  }
}

Bây giờ, Agent có thể truy vấn cơ sở dữ liệu Supabase của bạn, đọc thông tin schema và viết các truy vấn dựa trên cấu trúc dữ liệu thực tế của bạn.

Các MCP server phổ biến: Trình kết nối cơ sở dữ liệu (Supabase, PostgreSQL), nền tảng đám mây (AWS, Azure), công cụ thiết kế (Figma), quản lý dự án (Linear, Jira) và công cụ tài liệu (Notion, Google Drive).

✅ Kiểm tra nhanh: Bạn có 20 quy tắc trải rộng trên 4 file .mdc với tổng cộng 800 dòng. Hệ thống đang bắt đầu bỏ qua một số quy tắc của bạn. Điều gì có thể đang xảy ra? Quá nhiều quy tắc. AI có ngữ cảnh hạn chế, và 800 dòng quy tắc khiến cho ngữ cảnh code thực tế bị hạn chế. Hãy cắt giảm xuống còn 10-15 quy tắc quan trọng nhất (tổng cộng dưới 500 dòng). Loại bỏ các quy tắc mà AI đã tuân theo một cách tự nhiên, và kết hợp những quy tắc dư thừa. Chất lượng hơn số lượng.

Những điểm chính cần ghi nhớ

• Các quy tắc dự án (.cursor/rules/*.mdc) giúp Cursor tự động tuân theo những tiêu chuẩn lập trình của bạn — trong mọi tương tác, không cần nhắc nhở
• Giữ các quy tắc dưới 500 dòng, thêm dần dần, bao gồm những ví dụ code thực tế
• Notepad là các gói ngữ cảnh có thể tái sử dụng — tham chiếu chúng khi cần, không giống như những quy tắc luôn được áp dụng
• Tài liệu tùy chỉnh (Settings > Docs) cho phép Cursor tham chiếu tài liệu thư viện thực tế thay vì đoán mò
• MCP server kết nối Agent với các công cụ bên ngoài: cơ sở dữ liệu, API, nền tảng thiết kế, quản lý dự án
• Commit file .cursor/rules/ vào kho lưu trữ của bạn để toàn bộ nhóm có được hành vi AI nhất quán