Cursor Kuralları: Yapay Zekayı Kod Tabanınızla Nasıl Hizalı Tutarsınız

Cursor’da yeni bir sohbet açıp, daha önce yüz kere yapıştırdığınız talimat bloğunu yine yapıştırıyorsunuz. Yığınınız, adlandırma kurallarınız ve yapay zekânın sürekli yanlış anladığı klasör yapınız. Sonra da bir fonksiyonun yeteceği yerde, üç soyutlama katmanına sahip 40 satırlık bir sınıf üretiyor.

Bu kâbustan uyanma zamanı. Cursor kuralları, yapıştırmayı gereksiz kılan proje dosyalarıdır. Kurallarınızı bir kez yazın; yapay zekânın çıktısı, ona karşı savaşmak yerine kod tabanınızla uyumlu olsun.

Bu eğitim, FastAPI ve pytest kullanan bir Python web projesi için .mdc kural dosyaları seti oluşturuyor; proje bağlamı, kod sadeliği ve API hata biçimlendirmesini kapsayacak şekilde. Cursor’a yeniyseniz, önce Cursor ile Yazılım Geliştirme kursumuzu almanızı, ardından bir proje açıp adımları takip etmenizi öneririm.

Cursor Kuralları Nedir?

Cursor kuralları, projenizde .cursor/rules/ konumunda bulunan, MDC’ye özgü önbilgiler (frontmatter) içeren markdown dosyalarıdır. İsteminiz modele ulaşmadan önce, Cursor hangi kuralların eşleştiğini kontrol eder ve içeriklerini bağlam penceresinin başına ekler. Talimatlarınız her seferinde önce gelir.

Her .mdc dosyasında etkinleşmeyi kontrol eden üç önbilgi alanı vardır: description, globs ve alwaysApply. Bir kural her sohbette çalışabilir ya da yalnızca belirli dosyalar açıkken devreye girebilir. Üçüncü seçenek olan Akıllıca Uygula, ajanın açıklamayı okuyup kuralın ilgili olup olmadığına kendisinin karar vermesine olanak tanır. Bir sonraki bölümde her türü uygulamalı olarak ele alacağız.

Cursor dört kural kategorisini destekler:

Proje kuralları, kapsam veya meta veri içermeyen tek bir kök düzeyi dosya olan eski .cursorrules dosyasının yerini, önbilgili birden fazla .mdc dosyasına bölerek aldı.

AGENTS.md, glob kapsamına ihtiyaç duymayan projeler için daha basit bir alternatiftir. Cursor dışında da yapay zekâ ile kodlama araçları tarafından tanınan düz markdown’dur ve alt dizinlerdeki daha derin dosyalar, üstteki dosyaların üzerine yazar.

Ajan tabanlı iş akışlarının geliştirme sürecinize nasıl bağlandığı hakkında daha fazla bilgiyi Yapay Zekâ Ajanlarının Temelleri beceri yolumuzda bulabilirsiniz.

Cursor Proje Kurallarını Oluşturma ve Yapılandırma

Bu eğitimin geri kalanı, pytest kullanan bir FastAPI projesi için kural dosyaları oluşturur. Kalıplar herhangi bir yığına uyarlanabilir.

Kurallar dizinini ve dosyalarını ayarlama

Proje kökünüzde bir .cursor/rules/ dizini oluşturun. Buraya koyduğunuz her .mdc dosyası, Cursor’un anında algıladığı bir kurala dönüşür; yeniden başlatma gerekmez.

İlk kural dosyası olan project-context.mdc, yapay zekâya yığınıza ve klasör düzeninize dair kalıcı bir farkındalık kazandırır:

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

Bir Ajan sohbetinde /create-rule yazmak da başka bir giriş yoludur: Cursor, sohbet paneli üzerinden sizin için bir taslak çıkarır.

Önbilgideki alwaysApply: true ifadesi, bu kuralın her sohbette yükleneceği anlamına gelir. Dosyaları, konuya göre kebab-case ile adlandırın (project-context.mdc, simplicity.mdc, error-responses.mdc) ve her birini 500 satırın altında tutun. Şişkin bir kural dosyası, gerçek kodunuz ve istemleriniz için gereken bağlam penceresi alanını tüketir. .cursor/rules/ dizinini git’e ekleyin.

Doğru eşleşme için kural meta verisini yapılandırma

Yukarıdaki project-context.mdc kuralı alwaysApply: true kullanır; bu en basit moddur: hangi dosyalar üzerinde çalıştığınızdan bağımsız olarak her sohbete yüklenir. Proje genelindeki bağlam için doğru seçim budur.

Bazı kurallar yalnızca kod tabanının belirli bölümlerine uygulanır. alwaysApply: false olarak ayarlayın ve kapsamlamak için virgülle ayrılmış glob desenleri ekleyin. globs: app/routers/**/*.py içeren bir kural, yalnızca bağlamda eşleşen dosyalar (burada: app/routers/ veya alt klasörlerindeki Python dosyaları) göründüğünde tetiklenir; böylece API kuralları alakasız sohbetlere karışmaz.

Akıllıca Uygula, dosya desenlerini tamamen atlar. globs alanını boş bırakır ve bunun yerine ayrıntılı bir description yazarsınız; ajan da kuralın geçerli sohbete uygun olup olmadığına karar verir. Açıklama kalitesi önemlidir: "Error handling rules" ifadesi, ajanın güvenilir şekilde eşlemesi için fazla muğlaktır; ancak "Conventions for FastAPI error responses including HTTP status codes, error body structure, and exception handler patterns" gibi ifadeler net sinyaller taşır.

Globsuz, anlamlı açıklaması olmayan ve alwaysApply: false olan kurallar, yalnızca el ile çağrılan kurallar hâline gelir ve sohbette @rule-name yazarak yüklenir. İhtiyaç halinde başvurduğunuz referans materyalleri için uygundur.

Kural içeriği ve kısıtları yazma

Yumuşak dil ile yazılmış kurallar (“fonksiyonları küçük tutmaya çalışın”, “async uç noktaları tercih edin”) yapay zekâya bunları yok sayma izni verir. Bunun yerine komut yazın: “Fonksiyonlar 30 satırın altında olmalı. Tüm uç noktalar async olmalı.”

Girişte bahsedilen, üç soyutlama katmanına sahip 40 satırlık sınıf üretme davranışını durduran kural simplicity.mdc’dir:

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

Fark anında hissedilir. Yapay zekâ, tek bir uygulaması varken soyut temel sınıflara yönelmeyi bırakır ve iki durum olduğunda if ifadeleri kullanır.

Üçüncü kural olan error-responses.mdc, yalnızca API rota dosyalarıyla çalışırken tetiklenecek şekilde glob kapsamına alınmıştır:

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

Mümkün olduğunda, kurallara kod kopyalamak yerine kod tabanınızdaki mevcut dosyalara atıfta bulunun. “Örnek uç nokta yapısı için app/routers/users.py dosyasına bakın” gibi bir satır, kod geliştikçe geçerliliğini korur; kopyalanmış bir parça ise orijinal refaktör edilir edilmez bayatlar.

Kural eklenmesini test etme ve doğrulama

Cursor’da bir sohbette hangi kuralların etkin olduğunu gösteren yerleşik bir gösterge yoktur. Doğrulama, davranışı test ederek yapılır.

Yeni bir Ajan sohbeti açın ve kurallarınızdan birini tetiklemesi gereken bir istem yazın. error-responses.mdc için şunu deneyin: “app/routers/users.py içinde ID ile bir kullanıcıyı silmek için bir DELETE uç noktası ekleyin.” Üretilen hata işleme, kuralınızdaki JSON yapısına hiç benzemiyorsa ya da HTTPException ile detay sözlüğünü atlıyorsa, eşleşmede bir sorun vardır.

Glob kapsamlı kuralların, isteminizde atıf yapılan veya editörde açık olan bir eşleşen dosyaya ihtiyacı vardır. error-responses.mdc kuralını app/routers/ altında herhangi bir dosyadan bahsetmeden test etmek, kuralın hiç etkinleşmemesi demektir. 

“Akıllıca Uygula” kuralları ise konu bazlıdır: kuralın açıklamasıyla ilgili bir istem deneyin, sonra da alakasız bir tane yazıp çıktıları karşılaştırın. Ajanın ilkinde kuralı takip etmesi, ikincisinde yok sayması gerekir.

Cursor Kurallarınızı Etkili Tutma

Geçen ay işe yarayan kurallar, bir refaktörden ya da klasör adı değişikliğinden sonra yapay zekâyı yanlış yönlendirebilir.

Eşleşme hatalarını giderme

Bir kuralın tetiklenmemesinin en yaygın nedeni dosya uzantısıdır: kuralların .mdc uzantısında olması gerekir; .cursor/rules/ altındaki sıradan .md dosyalar sessizce yok sayılır.

Bunun ötesinde:

• **/*.py gibi aşırı geniş glob’lar, kuralı projedeki her Python dosyasına ekler. Kuralın yalnızca ait olduğu yerde tetiklenmesi için app/routers/**/*.py veya tests/**/*.py ile daraltın.

• Açıklama fazla genel olduğunda “Akıllıca Uygula” kurallarının bazı sohbetleri kaçırdığını fark edersiniz. Yukarıdaki meta veri bölümündeki iyi/kötü açıklama örnekleri burada da geçerlidir.

• Çakışan kurallar tespit edilmesi daha zordur. İki kural aynı dosyalar için çelişkili talimatlar veriyorsa, yapay zekâ birini seçer (genellikle en son yükleneni). Glob kapsamını daraltarak örtüşmeyi giderin ya da ilgili yönergeleri tek bir dosyada birleştirin.

Bilinmeye değer bir tuhaflık: .mdc dosyalarına yapılan değişiklikler bazen kaydedilmeden kaybolur. Düzenlemeleriniz kalmıyorsa, Cursor’u tamamen kapatın, kaydedilmemiş değişiklikler açılır penceresinde “Override” seçin ve yeniden açın.

Kuralları sohbet ortasında kalıcı kılma

Bir kural, sohbetin başında doğru şekilde tetiklenip beş mesaj sonra yok sayılabilir. Nedeni, bağlam penceresindeki yakınlık (recency) yanlılığıdır: sohbet uzadıkça model, en üste enjekte edilen talimatlar yerine son mesajlara öncelik verir. Bu, Cursor topluluğundaki en yaygın şikayettir ve bunu düzeltecek bir ayar yoktur.

Geçici çözüm pekiştirmedir. Çıktı kurallarınızdan sapmaya başladığında, bir sonraki isteminize “hata yanıtları için proje kurallarına uyun” gibi bir satır ekleyin. Bu, talimatı modelin yakın bağlamına geri taşır. 

Her yanıtta önemli olan kurallar (biçimlendirme, adlandırma) için, ayrıntılı paragraflara kıyasla daha kısa ve doğrudan ifadeler uzun sohbetler boyunca daha iyi dayanır.

Kod örnekleri içeren kurallar da yalnızca metinden oluşan talimatlara göre sapmaya karşı daha dirençlidir. “Hata işleme için erken dönüş kullanın” yazmak yerine, istediğiniz kalıbı gösteren kısa bir önce/sonra bloğu ekleyin. Model, özellikle bağlam büyüdükçe, düzyazı açıklamalardan ziyade gerçek koda daha güvenilir şekilde tutunur.

Kuralları sürdürme ve budama

Her büyük refaktör, bağımlılık yükseltmesi veya klasör yeniden yapılanmasından sonra kuralları gözden geçirin. Kullanımdan kalkmış API’lara ya da kaldırılmış dosyalara atıfta bulunan bir kural, yapay zekâya yanlış talimatlar verecektir. Eski glob’lar ise daha da sessizce başarısız olur: app/api/’yi app/routers/ olarak yeniden adlandırın; eski yola kapsamlanan bir kural, hiçbir uyarı olmadan tetiklenmeyi bırakır.

Budama, diğer yönde ilerler. Modeller geliştikçe, yaygın kuralları talimat verilmeksizin de uygular hâle gelirler. Yapay zekâ bir kuralın rehberliğini zaten kendiliğinden takip ediyorsa, kuralı silip belirteçleri geri kazanın. Sağlıklı bir kural seti zamanla yalnızca büyümez, küçülür de.

Ekip ortamlarında kuralları ölçeklendirme

Kurallara uygulama kodu gibi davranın. Değişiklikler çekme isteklerinden geçer ve .cursor/rules/ içine girmeden önce ekip kalıpta uzlaşır.

Business veya Enterprise planlarındaki kuruluşlar için Ekip Kuralları, yöneticilerin Cursor panosundan tüm üyeler genelinde kuralları zorunlu kılmasına imkân tanır. “Hemen etkinleştir”, bir kuralı varsayılan olarak etkin kılar ve kullanıcıların kapatmasına izin verir. “Bu kuralı zorunlu kıl” ise vazgeçme seçeneğini kaldırır; güvenlik uygulamaları ve uyumluluk gereklilikleri gibi pazarlık kabul etmeyen kuralları kapsar.

Sonuç

En sık düzelttiğiniz kalıplar için bir veya iki kuralla başlayın. Her oturumda aynı türde yapay zekâ çıktısını düzenlemeye devam ediyorsanız (yanlış hata formatı, gereksiz soyutlamalar), bu yazılmayı bekleyen bir kuraldır. Tekrarlayan hataları gördükçe yenilerini ekleyin ve yük taşımayanları budayın.

Bu eğitimdeki .mdc dosyaları bir FastAPI projesine uygundur. Sizinkiler bir Next.js ön yüzü ya da bir Rust CLI aracı için farklı görünecektir ve amaç da budur: bunlar, ekibinizin kurallarını kodlar; genel geçer en iyi uygulamaları değil. 

Cursor hakkında daha derine inmek isterseniz, Cursor 2.0 rehberimize göz atın. Diğer yapay zekâ ile kodlama asistanlarıyla karşılaştırması için şu yazıları okumanızı öneririm:

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