Aturan Cursor: Cara Menulis File .cursor/rules yang Benar-benar Berfungsi

Aturan Cursor: Cara Menulis File .cursor/rules yang Benar-benar Berfungsi

Setiap pengguna Cursor menghadapi hambatan yang sama. AI menghasilkan kode yang secara teknis berfungsi tetapi mengabaikan konvensi proyek Anda, jalur impor yang salah, pola usang, dan komponen yang strukturnya sama sekali berbeda dari sisa basis kode Anda. Aturan Cursor memperbaiki hal tersebut dengan memberikan konteks persisten kepada AI tentang bagaimana proyek Anda bekerja.

Apa Itu Aturan Cursor dan Mengapa Itu Penting?

Aturan Cursor adalah file markdown yang bertindak sebagai prompt sistem permanen yang disuntikkan sebelum setiap interaksi AI, obrolan, pelengkapan otomatis, atau pembuatan kode. Anggap saja ini sebagai dokumen orientasi untuk AI. Alih-alih mengoreksi kesalahan yang sama di setiap sesi, Anda menulis instruksi sekali dan itu akan tetap berlaku.

Pendekatan lama menggunakan satu file .cursorrules di root proyek Anda. Itu masih berfungsi, tetapi sudah tidak digunakan lagi (deprecated). Sistem saat ini menggunakan direktori .cursor/rules/ dengan file .mdc (Markdown Cursor) individual, masing-masing dibatasi untuk situasi tertentu. Ini adalah pengaturan yang jauh lebih baik karena Anda tidak memadatkan setiap instruksi ke dalam satu file raksasa; Anda memisahkan aturan berdasarkan kepentingan, dan Cursor hanya memuat aturan yang relevan dengan apa yang sedang Anda kerjakan saat ini.

Jika Anda pernah bekerja dengan rekayasa konteks untuk alat AI, konsepnya sudah familier: konteks input yang lebih baik menghasilkan output yang jauh lebih baik. Aturan adalah rekayasa konteks untuk seluruh alur kerja pengembangan Anda.

Menyiapkan File Aturan Pertama Anda

Buat direktori .cursor/rules/ di root proyek Anda:

mkdir -p .cursor/rules

Setiap aturan adalah file .mdc dengan frontmatter YAML diikuti oleh konten markdown. Berikut adalah kerangkanya:

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

Your instructions go here in plain markdown.

Tiga bidang frontmatter mengendalikan semuanya:

Anda juga dapat membuat aturan melalui Cursor itu sendiri, ketik /create-rule di obrolan dan jelaskan apa yang Anda inginkan. Namun, menulisnya secara manual memberi Anda kontrol lebih besar.

Empat Jenis Aturan Dijelaskan

Cara sebuah aturan diaktifkan bergantung pada konfigurasi frontmatter-nya. Ada empat mode, dan memilih yang tepat penting untuk anggaran jendela konteks Anda.

Selalu Terapkan (Always Apply)

---
alwaysApply: true
---

Dimuat ke dalam setiap permintaan AI. Gunakan ini dengan hemat, untuk fundamental lintas proyek seperti deklarasi tumpukan teknologi (tech stack) atau konvensi kritis yang berlaku di mana-mana. Setiap aturan yang selalu aktif memakan token dari setiap interaksi, apakah relevan atau tidak.

Terikat Otomatis (Berbasis Glob)

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

Hanya aktif ketika Anda mengedit file yang cocok dengan pola glob. Ini adalah jenis aturan andalan. Konvensi komponen React Anda dimuat saat Anda berada di file komponen, pola API Anda dimuat saat Anda berada di penangan rute (route handlers), dan aturan pengujian Anda dimuat saat Anda menulis tes.

Diminta Agen (Cerdas)

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

Tidak ada glob, tidak ada always-apply, hanya deskripsi. Agen Cursor membaca deskripsi dan memutuskan apakah aturan tersebut relevan dengan tugas saat ini. Jika Anda memintanya untuk menulis migrasi, ia akan menarik aturan ini. Jika Anda sedang menata gaya tombol, ia akan melewatkannya. Ini bekerja dengan sangat mengejutkan untuk aturan yang tidak terpeta rapi ke jalur file.

Manual

---
---

Tidak ada bidang frontmatter yang diatur (atau frontmatter kosong). Aturan ini hanya aktif ketika Anda secara eksplisit menyebutnya dengan @nama-aturan di obrolan. Bagus untuk instruksi yang jarang digunakan namun penting, seperti daftar periksa penyebaran atau panduan refaktoring yang hanya Anda butuhkan sesekali.

Pola Glob yang Benar-benar Berfungsi

Glob menentukan file mana yang memicu aturan terikat otomatis. Salah mengaturnya dan aturan Anda要么 tidak pernah berjalan要么 berjalan di mana-mana. Berikut yang berhasil:

# 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/**"]

Beberapa jebakan dari penggunaan nyata:

• src/* hanya mencocokkan satu tingkat direktori. Anda hampir selalu menginginkan src/**/* untuk pencocokan rekursif.
• *.js tidak akan mencocokkan file .jsx atau .ts. Bersikaplah eksplisit tentang ekstensi.
• Glob harus berupa daftar YAML. Sintaks kurung kurawal seperti {src,lib}/**/*.ts dapat gagal secara diam-diam, tetap gunakan entri daftar terpisah.
• Awalan ! mengecualikan pola, yang berguna untuk mengabaikan file yang dihasilkan atau kode warisan (legacy code).

Contoh Aturan Praktis

Di sinilah teori bertemu kenyataan. Ini adalah aturan yang dapat Anda masukkan ke dalam proyek dan segera melihat output AI yang lebih baik.

Aturan Dasar Seluruh Proyek (Selalu Terapkan)

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

Jaga ini di bawah 30 baris. Ini dimuat dengan setiap permintaan, jadi setiap kata menghabiskan token.

Aturan Komponen React (Terikat Otomatis)

---
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
// Ambil data langsung di komponen, tanpa 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

### Aturan API Python (Terikat Otomatis)

```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"}

### Aturan Layanan Go (Terikat Otomatis)

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

## Mengelola Beban Token

Ini adalah hal yang sering dilewatkan sebagian besar panduan Cursor: setiap aturan yang Anda tulis membutuhkan token. Proyek dengan 20 aturan selalu aktif mungkin menghabiskan **2.000+ token per permintaan** hanya untuk instruksi, sebelum AI bahkan melihat kode Anda.

Itu penting karena konteks obrolan Cursor sekitar 20.000 token dalam mode standar. Jika aturan Anda memakan 25% dari itu, Anda telah kehilangan seperempat "ruang berpikir" AI untuk pertanyaan aktual Anda. Anda akan melihat kualitas output yang lebih buruk saat aturan menumpuk, terutama dalam percakapan yang lebih panjang.

Tiga prinsip menjaga anggaran token Anda tetap sehat:

**1. Gunakan aturan terikat otomatis dan diminta agen secara agresif.** Hanya deklarasi tumpukan proyek Anda yang harus selalu aktif. Sisanya harus dimuat secara kondisional. Aturan komponen React itu? Itu tidak perlu berada dalam konteks saat Anda menulis migrasi SQL.

**2. Tulis padat, bukan bertele-tele.** Ganti "Sangat direkomendasikan bagi pengembang untuk menggunakan antarmuka TypeScript daripada alias tipe saat mendefinisikan kontrak API publik" dengan "Utamakan `interface` daripada `type` untuk API publik." AI tidak perlu dibujuk, ia membutuhkan instruksi.

**3. Terapkan Aturan Tiga.** Hanya kodifikasikan pola sebagai aturan setelah AI salah tiga kali. Jika Cursor sudah menangani konvensi penamaan Anda dengan benar tanpa aturan, lewati aturan tersebut. Setiap aturan yang tidak perlu adalah konteks yang terbuang.

Anda dapat memantau penggunaan token di bilah status di bagian bawah panel obrolan Cursor. Perhatikan jika mendekati 100%, itu adalah sinyal Anda untuk memangkas.

## Mengatur Aturan untuk Proyek Nyata

Proyek produksi biasanya membutuhkan 5-8 file aturan. Berikut adalah struktur yang bekerja dengan baik:

```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 semuanya ke kontrol versi kecuali personal.mdc. Dengan begitu, seluruh tim Anda mendapatkan perilaku AI yang sama, yang merupakan tujuan utamanya. Seperti kata seorang pengguna forum Cursor, aturan yang baik berarti "Anda menerima lebih banyak saran sebagaimana adanya, dengan output yang sesuai dengan konvensi Anda pada percobaan pertama."

Jika Anda bekerja dengan alat pengkodean AI lain bersama Cursor, konsepnya dapat ditransfer secara langsung. Claude Code menggunakan CLAUDE.md, GitHub Copilot memiliki file instruksi, dan Windsurf memiliki formatnya sendiri, tetapi prinsip dasarnya identik.

Cara Kerja Prioritas Aturan

Ketika beberapa aturan berlaku untuk file yang sama, Cursor mengikuti hierarki yang jelas:

Aturan Tim tersedia di paket Team dan Enterprise. Mereka diatur di dasbor Cursor oleh admin dan ditegakkan di seluruh organisasi, pengembang individu tidak dapat mematikannya.

Dalam aturan proyek, jika dua aturan berlaku untuk file yang sama dan berkonflik, perilakunya tidak didefinisikan secara ketat. Dalam praktiknya, aturan yang dimuat terakhir cenderung mengambil alih. Menomori file Anda (001-base.mdc, 002-components.mdc) memberi Anda urutan yang dapat diprediksi.

Kesalahan Umum dan Cara Memperbaikinya

Setelah membaca lusinan utas komunitas dan menguji aturan di berbagai proyek, berikut adalah kesalahan yang paling sering menjebak orang:

Menulis aturan yang terlalu samar. "Tulis kode yang bersih" tidak memberi tahu AI apa-apa. "Gunakan ekspor bernama, bukan ekspor default. Struktur komponen sebagai: impor, tipe, fungsi, sub-komponen" memberikannya sesuatu yang dapat ditindaklanjuti.

Membuat semuanya selalu diterapkan. Insting pertama Anda adalah mengatur alwaysApply: true pada setiap aturan. Tahanlah. Audit aturan Anda setiap kuartal, jika Anda memiliki lebih dari 2-3 aturan selalu aktif, Anda mungkin membuang-buang token.

Lupa menguji aturan. Setelah menulis aturan, buka file yang relevan dan minta Cursor untuk menghasilkan sesuatu yang harus mengikuti aturan tersebut. Jika tidak, pola glob Anda mungkin salah, atau instruksinya tidak cukup jelas.

Tidak mendokumentasikan anti-pola. Memberi tahu AI apa yang harus dilakukan adalah setengah dari pekerjaan. Memberi tahu apa yang tidak boleh dilakukan adalah setengah lainnya. Sertakan bagian "JANGAN PERNAH lakukan ini" di setiap aturan dengan contoh eksplisit dari pendekatan yang salah.

Mengabaikan penyimpanan aturan di UI. Sebuah bug yang diketahui menyebabkan editan aturan menghilang. Jika perubahan hilang, tutup Cursor sepenuhnya, pilih "Override" pada popup perubahan yang belum disimpan, dan buka kembali.

Aturan Cursor vs CLAUDE.md vs AGENTS.md

Cursor bukan satu-satunya alat yang menggunakan file instruksi. Berikut perbandingan format untuk siapa pun yang bekerja lintas beberapa asisten pengkodean AI:

Keunggulan Cursor adalah granularitasnya. CLAUDE.md dan AGENTS.md lebih sederhana, mereka memuat semuanya selalu. Cursor memungkinkan Anda memuat aturan yang tepat pada waktu yang tepat, yang penting sekali set instruksi Anda tumbuh melampaui beberapa ratus baris.

Untuk pandangan lebih dalam tentang bagaimana konteks membentuk output AI di alat-alat ini, panduan rekayasa konteks kami menguraikan prinsip-prinsip yang berlaku terlepas dari editor mana yang Anda gunakan.

FAQ

Apakah .cursorrules sudah tidak digunakan lagi?

Ya. File .cursorrules tunggal di root proyek Anda masih berfungsi, tetapi Cursor merekomendasikan migrasi ke file .cursor/rules/*.mdc. Format baru mendukung pola glob, pemuatan kondisional, dan organisasi yang lebih baik. Migrasikan dengan memecah file monolitik Anda menjadi aturan yang terfokus.

Ekstensi file apa yang harus saya gunakan, .mdc atau .md?

Gunakan .mdc untuk file yang menyertakan frontmatter YAML (deskripsi, globs, alwaysApply). File .md biasa juga berfungsi di direktori aturan tetapi tidak mendukung metadata frontmatter yang memungkinkan pemuatan kondisional.

Berapa banyak aturan yang harus dimiliki sebuah proyek?

Lima hingga delapan adalah titik optimal untuk sebagian besar proyek. Satu aturan dasar selalu aktif, tiga hingga empat aturan terikat otomatis yang dibatasi oleh tipe file, dan satu atau dua aturan manual untuk tugas khusus. Lebih dari 10 aturan biasanya berarti beberapa di antaranya dapat digabungkan atau dihapus.

Apakah aturan Cursor memengaruhi pelengkapan otomatis dan penyelesaian tab?

Aturan berlaku untuk obrolan dan interaksi agen. Aturan Pengguna tidak berlaku untuk pengeditan sebaris (Cmd/Ctrl+K), dan aturan umumnya tidak memengaruhi saran pelengkapan otomatis Cursor Tab. Mereka paling efektif dalam sesi obrolan dan Composer.

Bisakah saya berbagi aturan di beberapa proyek?

Ya, melalui fitur Remote Rules Cursor. Buka Cursor Settings > Rules, Commands, pilih "Remote Rule (GitHub)," dan tempelkan URL repositori. Aturan disinkronkan otomatis saat repo sumber diperbarui. Alternatifnya, pertahankan repo aturan bersama dan buat symlink ke setiap proyek.

Berapa panjang aturan maksimum yang direkomendasikan?

Dokumentasi Cursor menyarankan untuk menjaga aturan individual di bawah 500 baris. Dalam praktiknya, usahakan di bawah 100 baris per aturan. Aturan yang lebih pendek lebih mudah dikelola dan membutuhkan lebih sedikit token. Jika aturan melebihi 150 baris, pecah menjadi dua aturan yang terfokus.

Apakah aturan bekerja dengan semua model AI di Cursor?

Aturan bekerja dengan setiap model yang didukung Cursor, Claude, GPT-4o, Gemini, dan lainnya. Aturan disuntikkan sebagai konteks tingkat sistem terlepas dari model mana yang Anda pilih. Perilaku model mungkin bervariasi, tetapi aturan itu sendiri bersifat agnostik model.

Bagaimana cara men-debug aturan yang tidak berfungsi?

Pertama, verifikasi bahwa pola glob cocok dengan file Anda, buka file dan periksa apakah aturan muncul di panel konteks. Kedua, uji dengan pertanyaan langsung yang seharusnya memicu aturan tersebut. Ketiga, coba atur alwaysApply: true sementara untuk memastikan konten aturan itu sendiri berfungsi. Jika ya, masalahnya ada pada pola glob Anda.

Haruskah saya commit .cursor/rules ke git?

Tentu saja. Tujuan utama aturan proyek adalah konsistensi lintas tim. Commit semuanya di .cursor/rules/ kecuali file