Cursor Rules Nedir? Proje Kurallarını AI Kod Ajanına Aktarma

Cursor Rules Nedir?

Cursor, yapay zekâ destekli bir kod editörü. İçindeki AI ajanı, siz kod yazarken veya sohbet ederken projenizin bağlamını anlamaya çalışır. Ancak varsayılan olarak ajan, sizin ekip standartlarınızı, tercih ettiğiniz kütüphaneleri veya mimari kararlarınızı bilemez. İşte bu noktada Cursor Rules devreye giriyor.

Cursor Rules, proje kök dizinine yerleştirdiğiniz bir yapılandırma dosyası aracılığıyla AI kod ajanına kalıcı talimatlar vermenizi sağlar. Bu talimatlar; kod stili, dosya yapısı, kullanılacak paketler, kaçınılması gereken yaklaşımlar gibi konuları kapsar. Amaç, ajanın her seferinde aynı soruları sormasını engellemek ve ürettiği kodun projeye daha ilk denemede uyumlu olmasını sağlamaktır.

Resmî dokümantasyona göre Cursor, proje bazlı kurallar için .cursorrules dosyasını (veya daha yeni sürümlerde .cursor/rules dizinini) destekler. Bu dosya düz metin formatındadır ve ajan tarafından otomatik olarak okunur.

Cursor Rules Neden Gerekli?

Bir AI kod ajanı, genel amaçlı bir modeldir. Sizin projenizdeki özel kararları bilmez. Örneğin:

• State yönetimi için Redux mu, Zustand mı kullanıyorsunuz?
• API çağrılarında fetch mi, axios mu tercih ediyorsunuz?
• Test dosyalarınız hangi isimlendirme kuralına uyuyor?
• Hata yönetiminde özel bir sarmalayıcı fonksiyon var mı?

Bu soruların cevaplarını her seferinde sohbet penceresine yazmak yerine, bir kez .cursorrules dosyasına kaydedersiniz. Ajan, o projede çalışırken bu kuralları dikkate alır. Böylece daha az düzeltme, daha tutarlı kod ve daha hızlı geliştirme elde edersiniz.

Cursor Rules Dosyası Nasıl Oluşturulur?

Projenizin kök dizininde .cursorrules adında bir dosya oluşturmanız yeterli. İçeriği tamamen size bağlı. İsterseniz Markdown benzeri başlıklar kullanabilir, isterseniz düz maddeler halinde yazabilirsiniz. Cursor, bu dosyayı otomatik olarak algılar ve AI ajanına bağlam olarak sunar.

Daha modüler bir yapı isteyenler için .cursor/rules dizini altında birden fazla kural dosyası da tanımlanabilir. Bu sayede frontend, backend ve test kurallarını ayrı ayrı yönetebilirsiniz. (Bu özelliğin tam kapsamı için Cursor'ın resmî dokümantasyonuna başvurun.)

Örnek .cursorrules İçeriği

Aşağıda, bir Next.js projesi için hazırlanmış örnek bir kural dosyası görebilirsiniz:

# Proje Kuralları

## Genel
- TypeScript kullan, JavaScript dosyası oluşturma.
- Tüm fonksiyonlar için dönüş tipi belirt.
- `any` tipini kullanma; gerekiyorsa `unknown` tercih et.

## Bileşenler
- Fonksiyonel bileşenler ve arrow function kullan.
- Stil için Tailwind CSS sınıflarını tercih et.
- Her bileşen için ayrı bir dosya oluştur.

## API Çağrıları
- `fetch` yerine projedeki `apiClient` sarmalayıcısını kullan.
- Hata durumlarında `toast` ile kullanıcıya bildirim göster.

## Test
- Test dosyalarını `__tests__` dizini altında tut.
- Test isimleri `should ...` ile başlasın.

Bu dosya sayesinde AI ajanı, yeni bir bileşen yazarken otomatik olarak TypeScript, arrow function ve Tailwind kullanacak; API çağrılarında sizin sarmalayıcınızı tercih edecektir.

Etkili Cursor Rules Yazma İpuçları

• Net ve kısa olun: Uzun paragraflar yerine maddeler halinde yazın. Ajan, kısa ve kesin talimatları daha iyi uygular.
• Örnek verin: "Şu formatta yaz" demek yerine, küçük bir kod parçası ekleyin.
• Kaçınılacakları belirtin: "Asla `var` kullanma" gibi olumsuz talimatlar da etkilidir.
• Güncel tutun: Proje büyüdükçe kuralları gözden geçirin. Kullanılmayan paketler için yazılmış kurallar kafa karıştırabilir.
• Takım içinde paylaşın: `.cursorrules` dosyasını sürüm kontrolüne ekleyin; böylece tüm ekip aynı kurallarla çalışır.

Uygulanabilir Adımlar

1. Proje kök dizininde .cursorrules dosyası oluşturun.
2. Projenizin teknoloji yığınına uygun maddeleri ekleyin.
3. Cursor'ı yeniden başlatın veya yeni bir sohbet başlatın; ajan dosyayı okuyacaktır.
4. AI'ya bir görev verin (örneğin "yeni bir kullanıcı kartı bileşeni oluştur") ve çıktının kurallara uyup uymadığını kontrol edin.
5. Gerekirse kuralları güncelleyin ve süreci tekrarlayın.

Sonuç

Cursor Rules, yapay zekâ kod ajanını projenize adapte etmenin en pratik yollarından biridir. Doğru yazılmış bir .cursorrules dosyası, hem kod kalitesini artırır hem de geliştirici deneyimini iyileştirir. Unutmayın: Ajan sizin talimatlarınızla şekillenir; ne kadar net olursanız, o kadar isabetli sonuç alırsınız.