Hướng dẫn viết Cursor Rule cho người mới bắt đầu

Hướng dẫn chi tiết cách viết Cursor Rule cho người mới bắt đầu, giúp bạn hiểu rõ vì sao phải dùng rule, cách cấu trúc đúng, cách tránh các lỗi AI hay mắc, và cách tối ưu workflow trong Cursor Editor. Bài viết giải thích từng bước dựa trên logic kỹ thuật, kèm lý do tại sao phải làm như vậy, giúp bạn tạo ra bộ rule ổn định, hạn chế AI phá project, giữ code đồng nhất và phù hợp với version của dự án. Đây là tài liệu nền tảng dành cho người mới dùng Cursor AI nhưng cần độ chính xác cao.

1. Vì sao phải viết Cursor Rule?

1.1. Để AI hiểu đúng cách bạn muốn nó làm việc

Khi không có rule, AI đoán phong cách, chất lượng và mục tiêu theo thói quen chung → dễ sai, mơ hồ, hoặc không phù hợp với dự án.
Rule giúp cố định cách AI hành động, không bị lệch dù prompt thay đổi.

1.2. Để giữ chất lượng đầu ra ổn định

Khi làm team, nhiều người dùng AI cho chung một dự án. Không có rule → mỗi người cho ra một kiểu.
Có rule → kết quả ổn định, “giống một người viết”.

1.3. Để tiết kiệm thời gian

Không phải lặp lại các yêu cầu cố định như coding style, cấu trúc file, cấm/tắt tính năng…
Rule giúp giảm 50–80% thời gian bạn cần để “định hướng” AI.

1.4. Để chống lỗi và giảm rủi ro

AI không tự biết giới hạn của dự án.
Rule giúp chặn:

• Sai kiến trúc
• Viết sai chuẩn coding
• Phát sinh thư mục rác
• Tự ý tạo file không có trong dự án
• Sử dụng công nghệ dự án không hỗ trợ

2. Cấu trúc cần có của một Cursor Rule

2.1. Mục “alwaysApply”: để rule luôn được kích hoạt

alwaysApply: true

Nếu không bật, rule chỉ hoạt động khi bạn chọn thủ công → vô dụng. Bật lên để toàn bộ dự án luôn tuân theo một chuẩn.

2.2. Mục mô tả (description): để ghi rõ mục đích

description: |
  Quy tắc dùng khi làm việc với dự án X.

Đây là phần giúp AI hiểu bối cảnh tổng quát. Nếu không có, AI dễ “đi lạc” sang phong cách khác.

2.3. Danh sách rules (rules[]): để kiểm soát từng hành vi

Một rule có các thành phần cơ bản:

rules:
  - name: "Quy tắc đặt tên file"
    pattern: "*.js"
    description: |
      Tất cả file phải dùng camelCase.
    examples:
      good: ["userService.js"]
      bad: ["User_service.JS"]

Giải thích từng phần:

2.4. Mục cấm / hạn chế (do/dont)

Ví dụ:

intent:
  - "Không tự tạo file mới nếu người dùng không yêu cầu."

AI hay tự sinh file → gây rác → ảnh hưởng cấu trúc dự án → không kiểm soát được.
Rule này khóa hành vi đó.

2.5. Định nghĩa style coding (coding conventions)

  - name: "Code style"
    description: |
      Viết code theo chuẩn PSR-12.

Nếu không chốt style → mỗi lần AI tạo code là mỗi lần thay đổi format → khó review, khó merge.

3. Quy trình viết một Cursor Rule chuẩn

Bước 1 — Xác định mục tiêu dự án

Bạn phải trả lời: “Tôi muốn AI hỗ trợ cái gì?”

Không biết mục tiêu → rule lan man, dài, không hiệu quả → AI rối.

Bước 2 — Ghi rõ giới hạn dự án

Ví dụ:

• PHP version: 7.4
• Framework: Laravel 8
• Không dùng TypeScript
• Không tạo file migration mới

Giới hạn càng rõ → AI càng ít sai.
Không có giới hạn → AI rất hay dùng công nghệ mới, sai version, sai API.

Bước 3 — Xác định những hành vi AI hay sai nhất

Ví dụ:

• Tự sinh file linh tinh
• Viết import sai
• Sử dụng syntax của version mới
• Tạo code không phù hợp folder structure

Đây là những điểm tạo ra rule quan trọng nhất. Tập trung 20% rule để sửa 80% lỗi.

Bước 4 — Viết rule bằng ngôn ngữ đơn giản, không mơ hồ

Ví dụ sai: “Viết code sạch” → AI không hiểu.
Ví dụ đúng: “Không dùng biến một ký tự như i, j, k.”

AI không hiểu từ trừu tượng.
Muốn AI làm đúng → phải mô tả hành vi cụ thể.

Bước 5 — Bổ sung ví dụ tốt/xấu

Đây là phần cực quan trọng nhưng rất nhiều người bỏ qua.

AI học theo ví dụ mạnh hơn theo mô tả.
Chỉ 2–3 ví dụ tốt/xấu đã giúp giảm lỗi 60–70%.

Bước 6 — Test rule bằng một tác vụ thật

Ví dụ: “Tạo controller UserController.”

Rule chỉ có giá trị khi được test trong thực tế.
Không test → rule chỉ là lý thuyết.

4. Mẫu Cursor Rule đơn giản cho người mới

alwaysApply: true

description: |
  Quy tắc hỗ trợ viết mã PHP, Laravel 8 cho dự án cũ.

rules:
  - name: "Không dùng syntax Laravel mới"
    description: |
      Laravel trong dự án là bản 8. Không dùng các API của Laravel 9+.
    examples:
      bad: ["Route::controller(...)"]
      good: ["Route::get(...)", "Route::post(...)"]

  - name: "Không tự tạo file"
    description: |
      Chỉ tạo file khi người dùng yêu cầu.

  - name: "Style code"
    description: |
      Tất cả code phải tuân theo PSR-12.

Kết luận

Viết Cursor Rule không phải để “làm màu”, mà để:

• Giữ AI chạy đúng đường.
• Giảm lỗi.
• Tăng tốc độ phát triển.
• Chuẩn hóa output trong team.
• Tạo ra môi trường làm việc ổn định.

Muốn viết rule tốt → phải hiểu vấn đề, hiểu dự án, và hiểu AI dễ sai ở đâu.