Cursor Kuralları ile Projenize Özel Yapay Zekâ: .cursor/rules ve .mdc Dosyaları

Kurallar neden gerekli?

Cursor her yeni sohbette projenizin geleneklerini bilmez: PDO mu kullanıyorsunuz, hangi klasör ne işe yarıyor, açıklamalar Türkçe mi yazılıyor? Bunları her seferinde tekrar anlatmak yerine kurallar tanımlarsınız. Kurallar, yapay zekâya otomatik eklenen kalıcı talimatlardır.

Kural türleri

• Proje kuralları: Proje kökündeki .cursor/rules/ klasöründe .mdc uzantılı dosyalar olarak saklanır ve depoyla birlikte ekibe paylaşılır.
• Kullanıcı kuralları: Cursor ayarlarına yazılır, tüm projelerinizde geçerlidir (ör. "yanıtları Türkçe ver").
• Eski projelerde görülen tek dosyalık .cursorrules hâlâ okunabilir; yeni projelerde .cursor/rules yapısı önerilir.

.mdc dosyasının yapısı

Her kural dosyası, ne zaman uygulanacağını belirten kısa bir üst bilgi (frontmatter) ve ardından Markdown talimatlardan oluşur:

---
description: PHP ve veritabanı kodu yazarken uyulacak kurallar
globs: "**/*.php"
alwaysApply: false
---

- Veritabanı erişiminde yalnız PDO ve hazırlanmış ifadeler kullan; SQL'e değişken birleştirme.
- Kullanıcıya gösterilen her değeri htmlspecialchars ile kaçışla.
- Yeni tablo ya da sütun için migrations/ altına numaralı bir SQL dosyası ekle.
- Fonksiyon ve değişken adları Türkçe, açıklamalar kısa ve Türkçe olsun.
- Örnek desen için @src/Depo/UrunDeposu.php dosyasına bak.

Üst bilgideki alanlar kuralın nasıl devreye gireceğini belirler:

• alwaysApply: true – her istekte eklenir. Yalnız gerçekten her yerde geçerli, kısa kurallar için kullanın.
• globs – eşleşen dosyalar bağlamdayken otomatik eklenir (ör. yalnız *.php).
• description – Agent, açıklamaya bakarak kuralın gerekli olup olmadığına kendisi karar verebilir.
• Hiçbiri otomatik değilse kuralı sohbette @ ile adıyla çağırırsınız.

Örnek kural seti

Orta ölçekli bir web projesi için kurallarınızı konulara bölün:

.cursor/rules/
├── genel.mdc          # alwaysApply: proje özeti, dil ve stil
├── php-veritabani.mdc # globs: **/*.php
├── arayuz.mdc         # globs: **/*.{html,css,js}
└── test.mdc           # description: test yazarken

genel.mdc dosyası kısa tutulmalıdır:

---
description: Proje geneli
alwaysApply: true
---

Bu proje PHP 8.2 + MySQL ile yazılmış bir fatura uygulamasıdır.
Giriş noktası public/index.php; iş kuralları src/ altında.
Kod değiştirmeden önce kısa bir plan yaz; testleri composer test ile çalıştır.

Kuralların etkisini test edin

Kural ekledikten sonra basit bir istekle deneyin: "Ürünleri kategoriye göre listeleyen bir fonksiyon yaz." Yanıt PDO ve hazırlanmış ifade kullanıyorsa kural çalışıyordur. Kullanmıyorsa kuralın globs alanını ve dosya konumunu kontrol edin.

İpuçları

• Kurallar talimat gibi yazılmalı: "şunu yap / şunu yapma". Uzun açıklamalar yerine maddeler kullanın.
• Örnek dosyaya başvurun (@dosya); bir örnek, paragraflarca açıklamadan daha etkilidir.
• Kuralları kod incelemesinde gördüğünüz tekrar eden hatalardan türetin.

Sık yapılan hatalar

• Her şeyi alwaysApply: true yapmak; gereksiz bağlam hem yanıtı yavaşlatır hem dağıtır.
• Birbiriyle çelişen kurallar yazmak (bir dosyada "İngilizce adlandır", diğerinde "Türkçe adlandır").
• Kuralları bir kez yazıp güncellememek; proje değiştikçe kurallar da güncellenmeli.

Özet

.cursor/rules altındaki .mdc dosyaları, Cursor'un projenizi sizin gibi yazmasını sağlar. Kısa genel bir kural, dosya türüne göre otomatik eklenen kurallar ve gerektiğinde çağrılan özel kurallar dengeli bir yapı oluşturur. Sonraki adım olarak projenizin en sık tekrar eden üç kod inceleme yorumunu kurala dönüştürün.