Cursor Rules: Cara Menjaga AI Tetap Selaras dengan Codebase Anda

Anda membuka chat baru di Cursor dan menempelkan blok instruksi yang sama seperti ratusan kali sebelumnya. Stack Anda, konvensi penamaan Anda, dan struktur folder yang terus salah dipahami AI. Lalu AI menghasilkan kelas 40 baris dengan tiga lapisan abstraksi untuk sesuatu yang sebenarnya hanya butuh sebuah fungsi.

Saatnya bangun dari mimpi buruk ini. Aturan Cursor adalah file proyek yang membuat kegiatan menempelkan instruksi menjadi tidak perlu. Tulis konvensi Anda sekali, dan output AI akan selaras dengan codebase Anda alih-alih melawannya.

Tutorial ini membangun serangkaian file aturan .mdc untuk proyek web Python menggunakan FastAPI dan pytest, mencakup konteks proyek, kesederhanaan kode, dan pemformatan kesalahan API. Jika Anda baru di Cursor, saya sarankan mengikuti kursus Software Development with Cursor kami terlebih dahulu, lalu buka sebuah proyek dan ikuti langkah-langkahnya.

Apa Itu Aturan Cursor?

Aturan Cursor adalah file markdown dengan frontmatter khusus MDC yang berada di proyek Anda pada .cursor/rules/. Sebelum prompt Anda mencapai model, Cursor memeriksa aturan mana yang cocok dan menambahkan kontennya ke awal context window. Instruksi Anda selalu mendarat terlebih dahulu.

Setiap file .mdc memiliki tiga field frontmatter yang mengontrol aktivasi: description, globs, dan alwaysApply. Sebuah aturan bisa aktif di setiap percakapan atau hanya ketika file tertentu terbuka. Opsi ketiga, Apply Intelligently, memungkinkan agen membaca deskripsi dan memutuskan sendiri apakah aturan relevan. Bagian berikut membahas tiap jenis secara praktis.

Cursor mendukung empat kategori aturan:

Aturan proyek menggantikan file lama .cursorrules, sebuah file tunggal di level root tanpa cakupan atau metadata, dengan memecah aturan menjadi beberapa file .mdc yang memiliki frontmatter.

AGENTS.md adalah alternatif yang lebih sederhana untuk proyek yang tidak memerlukan cakupan glob. Ini adalah markdown biasa yang dikenali oleh alat pengodean AI di luar Cursor, dan file yang lebih dalam di subdirektori akan menimpa file induknya.

Anda dapat mempelajari lebih lanjut tentang bagaimana workflow berbasis agen terhubung ke proses pengembangan Anda dalam jalur keterampilan AI Agent Fundamentals kami.

Membuat dan Mengonfigurasi Aturan Proyek Cursor

Sisa tutorial ini membuat file aturan untuk proyek FastAPI menggunakan pytest. Polanya dapat diterapkan ke stack apa pun.

Menyiapkan direktori dan file aturan

Buat direktori .cursor/rules/ di root proyek Anda. Setiap file .mdc yang Anda letakkan di sini akan menjadi aturan yang langsung diambil oleh Cursor, tanpa perlu restart.

File aturan pertama, project-context.mdc, memberi AI kesadaran persisten tentang stack dan tata letak folder Anda:

---
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

Mengetik /create-rule di chat Agent adalah cara lain: Cursor akan membuat draf untuk Anda melalui panel chat.

Frontmatter alwaysApply: true berarti aturan ini dimuat di setiap percakapan. Namai file dalam kebab-case berdasarkan bahasan (project-context.mdc, simplicity.mdc, error-responses.mdc) dan jaga setiap file di bawah 500 baris. File aturan yang gemuk memakan ruang context window yang Anda butuhkan untuk kode dan prompt sebenarnya. Commit direktori .cursor/rules/ ke git.

Mengonfigurasi metadata aturan untuk pencocokan yang akurat

Aturan project-context.mdc di atas menggunakan alwaysApply: true, mode paling sederhana: setiap percakapan memuatnya terlepas dari file apa yang sedang Anda kerjakan. Itu pilihan yang tepat untuk konteks tingkat proyek.

Beberapa aturan hanya berlaku untuk bagian tertentu dari codebase. Setel alwaysApply: false dan tambahkan pola glob sebagai daftar dipisahkan koma untuk membatasi cakupannya. Aturan dengan globs: app/routers/**/*.py hanya aktif ketika file yang cocok (di sini: file Python di app/routers/ atau subfoldernya) muncul dalam konteks, sehingga konvensi API tidak mengganggu chat yang tidak terkait.

Apply Intelligently melewati pola file sepenuhnya. Anda membiarkan globs kosong dan menulis description yang terperinci, lalu agen memutuskan apakah aturan relevan untuk percakapan saat ini. Kualitas deskripsi penting: "Error handling rules" terlalu samar untuk dicocokkan secara andal oleh agen, tetapi "Conventions for FastAPI error responses including HTTP status codes, error body structure, and exception handler patterns" memiliki sinyal yang jelas.

Aturan tanpa glob, tanpa deskripsi bermakna, dan alwaysApply: false menjadi hanya manual, dimuat saat Anda mengetik @rule-name di chat. Cocok untuk materi referensi yang Anda panggil sesuai kebutuhan.

Menulis konten dan batasan aturan

Aturan yang ditulis dengan bahasa lunak ("usahakan fungsi tetap kecil," "lebih suka endpoint async") memberi AI izin untuk mengabaikannya. Tulis perintah sebagai gantinya: "Fungsi harus di bawah 30 baris. Semua endpoint harus async."

Pendahuluan menyebutkan AI yang menghasilkan kelas 40 baris dengan tiga lapisan abstraksi. Aturan yang menghentikan perilaku itu adalah 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

Perbedaannya langsung terasa. AI berhenti memilih abstract base class ketika hanya ada satu implementasi, dan menggunakan if-statement ketika hanya ada dua kasus.

Aturan ketiga, error-responses.mdc, dibatasi dengan glob agar hanya aktif saat bekerja dengan file 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

Bila memungkinkan, arahkan ke file yang sudah ada di codebase Anda alih-alih menyalin kode ke dalam aturan. Kalimat seperti "Lihat app/routers/users.py untuk struktur endpoint baku" akan tetap akurat seiring kode berkembang, sementara cuplikan yang disalin akan usang begitu seseorang me-refactor aslinya.

Menguji dan memverifikasi keterikatan aturan

Cursor tidak memiliki indikator bawaan yang menunjukkan aturan mana yang aktif dalam percakapan. Anda memverifikasinya dengan menguji perilaku.

Buka chat Agent baru dan tulis prompt yang seharusnya memicu salah satu aturan Anda. Untuk error-responses.mdc, coba: "Tambahkan endpoint DELETE untuk menghapus pengguna berdasarkan ID di app/routers/users.py." Jika penanganan kesalahan yang dihasilkan tidak mirip dengan struktur JSON aturan Anda atau melewatkan HTTPException dengan detail dict, ada sesuatu yang keliru dalam pencocokan.

Aturan yang dibatasi glob memerlukan file yang cocok disebutkan dalam prompt Anda atau terbuka di editor. Menguji error-responses.mdc tanpa menyebut file apa pun di bawah app/routers/ berarti aturan tersebut tidak pernah aktif. 

Aturan "Apply Intelligently" berbasis topik: cobalah prompt yang terkait dengan deskripsi aturan, lalu yang tidak terkait, dan bandingkan outputnya. Agen seharusnya mengikuti aturan pada yang pertama dan mengabaikannya pada yang kedua.

Menjaga Aturan Cursor Tetap Efektif

Aturan yang berhasil bulan lalu bisa menyesatkan AI setelah refactor atau penggantian nama folder.

Mengatasi kegagalan pencocokan

Alasan paling umum sebuah aturan tidak aktif adalah ekstensi file: aturan harus menggunakan .mdc, dan file .md biasa di .cursor/rules/ akan diabaikan tanpa pemberitahuan.

Selain itu:

• Glob yang terlalu luas seperti **/*.py akan menautkan aturan ke setiap file Python di proyek. Persempit ke app/routers/**/*.py atau tests/**/*.py, sehingga aturan hanya aktif di tempat yang semestinya.

• Anda akan melihat aturan "Apply Intelligently" sering terlewat dalam percakapan ketika deskripsinya terlalu generik. Contoh deskripsi baik/buruk dari bagian metadata di atas berlaku di sini juga.

• Aturan yang saling bertentangan lebih sulit dikenali. Saat dua aturan memberikan instruksi yang berlawanan untuk file yang sama, AI akan memilih salah satunya (biasanya yang dimuat terakhir). Perbaiki dengan mempersempit cakupan glob agar aturan tidak tumpang tindih, atau gabungkan panduan terkait ke dalam satu file.

Satu keunikan yang patut diketahui: perubahan pada file .mdc kadang menghilang tanpa tersimpan. Jika suntingan tidak tersimpan, tutup Cursor sepenuhnya, pilih "Override" pada pop-up perubahan yang belum disimpan, lalu buka kembali.

Membuat aturan tetap diikuti di tengah percakapan

Sebuah aturan bisa aktif dengan benar di awal percakapan namun tetap diabaikan lima pesan kemudian. Bias konteks terhadap pesan terbaru adalah penyebabnya: seiring percakapan bertambah panjang, model memprioritaskan pesan terbaru dibanding instruksi yang disuntikkan di bagian atas. Ini adalah keluhan paling umum di komunitas Cursor, dan tidak ada pengaturan yang bisa memperbaikinya.

Solusinya adalah penguatan. Ketika output mulai melenceng dari aturan Anda, tambahkan kalimat seperti "ikuti aturan proyek untuk respons error" ke prompt berikutnya. Itu memindahkan instruksi kembali ke konteks terbaru model. 

Untuk aturan yang penting di setiap respons (formatting, penamaan), frasa yang lebih singkat dan langsung lebih tahan terhadap percakapan panjang daripada paragraf detail.

Aturan dengan contoh kode juga lebih tahan terhadap penyimpangan dibanding instruksi berbasis teks saja. Alih-alih menulis "gunakan early return untuk penanganan error," sertakan blok sebelum/sesudah yang pendek yang menunjukkan pola yang Anda inginkan. Model lebih mudah berlabuh pada kode nyata daripada deskripsi prosa, terutama saat konteks bertambah.

Memelihara dan memangkas aturan

Tinjau aturan setelah refactor besar, peningkatan dependensi, atau restrukturisasi folder. Aturan yang merujuk API usang atau file yang dihapus akan memberi AI instruksi yang salah. Glob yang usang bahkan lebih senyap kegagalannya: ganti nama app/api/ menjadi app/routers/ dan aturan yang dibatasi ke path lama akan berhenti aktif tanpa peringatan.

Pemangkasan juga berlaku sebaliknya. Seiring model membaik, model mulai menangkap konvensi umum tanpa perlu diberi tahu. Jika AI sudah mengikuti panduan sebuah aturan tanpa dipicu, hapus aturannya dan rebut kembali token. Kumpulan aturan yang sehat cenderung menyusut seiring waktu, bukan hanya bertambah.

Menskalakan aturan untuk lingkungan tim

Perlakukan aturan seperti kode aplikasi. Perubahan melalui pull request, dan tim menyepakati pola sebelum mendarat di .cursor/rules/.

Untuk organisasi pada paket Business atau Enterprise, Team Rules memungkinkan admin menegakkan aturan di seluruh anggota dari dasbor Cursor. "Enable immediately" membuat aturan aktif secara default sambil mengizinkan pengguna menonaktifkannya. "Enforce this rule" menghapus opsi keluar, yang mencakup konvensi tak bisa ditawar seperti praktik keamanan dan persyaratan kepatuhan.

Kesimpulan

Mulailah dengan satu atau dua aturan untuk pola yang paling sering Anda koreksi. Jika Anda terus mengedit jenis output AI yang sama di setiap sesi (format error yang salah, abstraksi yang tidak perlu), itu adalah aturan yang menunggu untuk ditulis. Tambahkan lebih banyak saat Anda melihat kesalahan berulang, dan pangkas yang tidak lagi memberikan manfaat.

File .mdc dalam tutorial ini cocok untuk proyek FastAPI. Punya Anda akan terlihat berbeda untuk frontend Next.js atau alat CLI Rust, dan itulah intinya: file tersebut merekam konvensi tim Anda, bukan praktik terbaik generik. 

Jika Anda ingin mendalami Cursor, lihat panduan Cursor 2.0 kami. Untuk perbandingan dengan asisten pengodean AI lainnya, saya sarankan membaca artikel perbandingan kami:

• Cursor vs GitHub Copilot
• Claude Code vs Cursor
• Cline vs Cursor
• Cursor vs. Windsurf