Cursor Rules: Gerçekten İşe Yarayan .cursor/rules Dosyaları Nasıl Yazılır

Her Cursor kullanıcısı eninde sonunda aynı sorunla karşılaşır. Yapay zekâ teknik olarak çalışan kod üretir, ama projenizin kurallarını tamamen görmezden gelir — yanlış içe aktarma yolları, güncelliğini yitirmiş desenler, kod tabanınızın geri kalanıyla hiç benzerlik taşımayan bileşenler. Cursor Rules, yapay zekâya sizin projenizin nasıl çalıştığına dair kalıcı bir bağlam sağlayarak bu sorunu çözer.

Cursor Rules Nedir ve Neden Önemlidir?

Cursor Rules, her yapay zekâ etkileşiminden önce enjekte edilen kalıcı bir sistem istemi görevi gören Markdown dosyalarıdır — sohbet, otomatik tamamlama, kod üretimi, hepsi. Bunları yapay zekâ için işe alım belgeleri gibi düşünün. Her oturumda aynı hataları düzeltmek yerine talimatı bir kez yazarsınız ve kalıcı olur.

Eski yaklaşım, proje kök dizininde tek bir .cursorrules dosyasıydı. Bu hâlâ çalışıyor ancak artık önerilmiyor. Güncel sistem, belirli durumlara göre kapsamlandırılmış bireysel .mdc (Markdown Cursor) dosyalarından oluşan bir .cursor/rules/ dizinini kullanıyor. Bu çok daha iyi bir yapı, çünkü tüm talimatları tek bir dev dosyaya doldurmak zorunda kalmıyorsunuz — kuralları sorumluluk alanlarına göre bölüyorsunuz ve Cursor yalnızca şu an yaptığınızla ilgili olanları yüklüyor.

Yapay zekâ araçları için context engineering konusunda deneyiminiz varsa kavram tanıdık gelecektir: daha iyi girdi bağlamı çok daha iyi çıktı üretir. Kurallar, tüm geliştirme iş akışınız için context engineering'dir.

İlk Kural Dosyanızı Oluşturma

Proje kök dizininizde .cursor/rules/ dizinini oluşturun:

mkdir -p .cursor/rules

Her kural, YAML frontmatter'ı ardından Markdown içerik gelen bir .mdc dosyasıdır. İşte temel yapı:

---
description: "Bu kuralın ne zaman uygulanması gerektiği"
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

Talimatlarınız burada düz Markdown formatında.

Her şeyi üç frontmatter alanı kontrol eder:

Kuralları Cursor üzerinden de oluşturabilirsiniz — sohbette /create-rule yazın ve ne istediğinizi açıklayın. Ama elle yazmak size daha fazla kontrol sağlar.

Dört Kural Türü Açıklandı

Bir kuralın nasıl etkinleşeceği frontmatter yapılandırmasına bağlıdır. Dört mod bulunur ve doğrusunu seçmek bağlam penceresi bütçeniz için önem taşır.

Her Zaman Uygula

---
alwaysApply: true
---

Her yapay zekâ isteğine eklenir. Bunu dikkatli kullanın — tech stack bildirimi veya her yerde geçerli olan kritik kurallar gibi proje genelinde temel bilgiler için. Her zaman açık kural, ilgili olsun olmasın her etkileşimde token harcıyor.

Otomatik Eklenen (Glob Tabanlı)

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

Yalnızca glob desenlerine uyan dosyaları düzenlediğinizde etkinleşir. En çok kullanılan kural türü budur. React bileşen kurallarınız bileşen dosyalarında çalışırken yüklenir, API kurallarınız rota yöneticilerinde, test kurallarınız test yazarken.

Ajan Tarafından İstenen (Akıllı)

---
description: "Drizzle ORM ile veritabanı migrasyon desenleri"
alwaysApply: false
---

Glob yok, always-apply yok — sadece bir açıklama. Cursor'ın ajanı açıklamayı okur ve kuralın mevcut görev için uygun olup olmadığına karar verir. Migrasyon yazmasını isterseniz bu kuralı yükler. Bir düğme stillendiriyorsanız geçer. Bu, dosya yollarıyla düzgün eşleşmeyen kurallar için şaşırtıcı biçimde iyi çalışır.

Manuel

---
---

Frontmatter alanı tanımlanmamış (veya boş frontmatter). Bu kurallar yalnızca sohbette @kural-adı şeklinde açıkça bahsettiğinizde etkinleşir. Nadiren kullanılan ama önemli talimatlar için uygundur — dağıtım kontrol listeleri veya ara sıra ihtiyaç duyduğunuz yeniden yapılandırma kılavuzları gibi.

Gerçekten İşe Yarayan Glob Desenleri

Glob desenleri, otomatik eklenen kuralları hangi dosyaların tetikleyeceğini belirler. Yanlış yapılandırırsanız kurallarınız ya hiç tetiklenmez ya da her yerde tetiklenir. İşe yarayanlar şunlar:

# src içindeki tüm TypeScript dosyaları
globs: ["src/**/*.ts", "src/**/*.tsx"]

# Yalnızca bileşen dosyaları
globs: ["**/components/**/*.tsx"]

# Python dosyaları, testler hariç
globs: ["**/*.py", "!**/test_*.py"]

# Birden fazla belirli dizin
globs: ["src/api/**", "src/services/**"]

Gerçek kullanımdan birkaç dikkat edilmesi gereken nokta:

• src/* yalnızca bir dizin seviyesiyle eşleşir. Özyinelemeli eşleşme için neredeyse her zaman src/**/* isteyeceksiniz.
• *.js, .jsx veya .ts dosyalarıyla eşleşmez. Uzantılar konusunda açık sözlü olun.
• Glob'lar bir YAML listesi olmalıdır. {src,lib}/**/*.ts gibi küme parantezi sözdizimi sessizce başarısız olabilir — ayrı liste girişlerini tercih edin.
• ! öneki desenleri hariç tutar; bu, üretilen dosyaları veya eski kodu yok saymak için kullanışlıdır.

Pratik Kural Örnekleri

Teori burada gerçeklikle buluşuyor. Bir projeye ekleyip anında daha iyi yapay zekâ çıktısı görebileceğiniz kurallar bunlar.

Proje Genelinde Temel Kural (Her Zaman Uygula)

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

Bunu 30 satırın altında tutun. Her istekle birlikte yükleniyor, dolayısıyla her kelime token harcar.

React Bileşen Kuralı (Otomatik Eklenen)

---
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
// Fetch directly in the component — no 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

### Python API Kuralı (Otomatik Eklenen)

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

### Go Servis Kuralı (Otomatik Eklenen)

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

## Token Maliyetini Yönetmek

Çoğu Cursor rehberinin atladığı bir şey şu: yazdığınız her kural token harcar. 20 daima açık kuralı olan bir proje, yalnızca talimatlar için her istekte **2.000'den fazla token** yakabilir — yapay zekâ kodunuza bakmadan önce bile.

Bu önemli, çünkü Cursor'ın sohbet bağlamı standart modda yaklaşık 20.000 token. Kurallarınız bunun %25'ini yiyorsa, yapay zekânın asıl sorunuz için "düşünme alanı"nın dörtte birini kaybettiniz. Kurallar biriktikçe çıktı kalitesinin düştüğünü fark edeceksiniz, özellikle uzun konuşmalarda.

Token bütçenizi sağlıklı tutan üç ilke:

**1. Otomatik eklenen ve ajan tarafından istenen kuralları bol bol kullanın.** Yalnızca proje stack bildirimi daima açık olmalı. Geri kalanı koşullu yüklenmeli. O React bileşen kuralı? SQL migrasyonu yazarken bağlamda olmasına gerek yok.

**2. Yoğun yazın, sözü uzatmayın.** "Genel API sözleşmelerini tanımlarken geliştiricilerin tür takma adları yerine TypeScript arayüzleri kullanması önemle tavsiye edilir" yerine "Prefer `interface` over `type` for public APIs" yazın. Yapay zekânın ikna edilmesi gerekmiyor — talimata ihtiyacı var.

**3. Üç Kez Kuralı'nı uygulayın.** Bir deseni yalnızca yapay zekâ üç kez hata yaptıktan sonra kural olarak kodlayın. Cursor adlandırma kurallarınızı zaten kuralsız doğru yapıyorsa kuralı atlayın. Her gereksiz kural israf edilmiş bağlamdır.

Token kullanımını Cursor'ın sohbet panelinin alt kısmındaki durum çubuğunda izleyebilirsiniz. %100'e yaklaştığında budama zamanının geldiğini anlayın.

## Gerçek Bir Proje İçin Kuralları Düzenlemek

Bir üretim projesi genellikle 5-8 kural dosyasına ihtiyaç duyar. İyi çalışan bir yapı şöyle görünür:

```text
.cursor/rules/
  base.mdc            # Tech stack, always-apply (< 30 satır)
  components.mdc      # React/Vue desenleri, bileşen dizinlerine glob
  api.mdc             # Backend kuralları, API dizinlerine glob
  database.mdc        # ORM desenleri, models/migrations'a glob
  testing.mdc         # Test kuralları, test dosyalarına glob
  deployment.mdc      # CI/CD desenleri, manuel tetikleme
  personal.mdc        # Kişisel tercihleriniz (gitignored)

personal.mdc dışında her şeyi sürüm kontrolüne ekleyin. Bu sayede ekibinizin tamamı aynı yapay zekâ davranışını alır — ki asıl amaç budur. Bir Cursor forum kullanıcısının ifadesiyle, iyi kurallar "ilk denemede kurallarınıza uyan çıktılarla daha fazla öneriyi olduğu gibi kabul etmenizi" sağlar.

Cursor'ın yanı sıra başka yapay zekâ kodlama araçları da kullanıyorsanız kavramlar doğrudan aktarılabilir. Claude Code, CLAUDE.md kullanır, GitHub Copilot'un talimat dosyaları vardır ve Windsurf'ün kendi formatı bulunur — ama altta yatan ilke aynıdır.

Kural Önceliği Nasıl Çalışır

Aynı dosyaya birden fazla kural uygulandığında, Cursor net bir hiyerarşi izler:

Team Rules, Team ve Enterprise planlarında mevcuttur. Cursor panosunda yöneticiler tarafından belirlenir ve tüm kuruluşa uygulanır — bireysel geliştiriciler bunları kapatamaz.

Proje kuralları arasında, iki kural aynı dosyaya uygulanıp çakışırsa davranış kesin olarak tanımlanmamıştır. Pratikte sonradan yüklenen kurallar öncelik kazanma eğilimindedir. Dosyalarınızı numaralandırmak (001-base.mdc, 002-components.mdc) öngörülebilir bir sıra sağlar.

Yaygın Hatalar ve Çözümleri

Onlarca topluluk başlığını okuyup çeşitli projelerde kuralları test ettikten sonra, insanları en çok tökezleten hatalar şunlar:

Çok belirsiz kurallar yazmak. "Temiz kod yazın" yapay zekâya hiçbir şey söylemez. "Adlandırılmış dışa aktarım kullanın, varsayılan değil. Bileşenleri şu sırayla yapılandırın: içe aktarmalar, türler, işlev, alt bileşenler" ona uygulanabilir bir şey verir.

Her şeyi always-apply yapmak. İlk içgüdü her kurala alwaysApply: true koymaktır. Buna direniş gösterin. Kurallarınızı üç ayda bir denetleyin — 2-3'ten fazla daima açık kuralınız varsa muhtemelen token boşa harcıyorsunuz.

Kuralları test etmeyi unutmak. Bir kural yazdıktan sonra ilgili bir dosyayı açın ve Cursor'dan kurala uyması gereken bir şey üretmesini isteyin. Uymuyorsa, glob deseniniz yanlış olabilir veya talimat yeterince net değildir.

Anti-desenleri belgelememek. Yapay zekâya ne yapacağını söylemek işin yarısıdır. Ne yapmaması gerektiğini söylemek diğer yarısıdır. Her kurala yanlış yaklaşımın açık örnekleriyle birlikte bir "ASLA yapma" bölümü ekleyin.

Arayüzdeki kural kaydetme sorununu görmezden gelmek. Bilinen bir hata, kural düzenlemelerinin kaybolmasına neden olabilir. Değişiklikler kaybolursa Cursor'ı tamamen kapatın, kaydedilmemiş değişiklikler açılır penceresinde "Geçersiz Kıl"ı seçin ve yeniden açın.

Cursor Rules vs CLAUDE.md vs AGENTS.md

Cursor, talimat dosyaları kullanan tek araç değildir. Birden fazla yapay zekâ kodlama asistanıyla çalışan herkes için formatların karşılaştırması:

Cursor'ın avantajı ayrıntı düzeyidir. CLAUDE.md ve AGENTS.md daha basittir — her şeyi her zaman yüklerler. Cursor, doğru kuralları doğru zamanda yüklemenizi sağlar; bu, talimat setiniz birkaç yüz satırı aştığında önem kazanır.

Bu araçlarda bağlamın yapay zekâ çıktısını nasıl şekillendirdiğine derin bir bakış için context engineering rehberimiz, hangi editörü kullandığınızdan bağımsız olarak geçerli prensipleri açıklar.

Yol haritanızda yapay zeka özellikleri varsa, uzmanlık alanımız tam olarak bu: Techsy'nin yapay zeka entegrasyon ekibi LLM sistemlerini prototipten üretime taşıyor. Mevcut kurulumunuz için ikinci bir görüş isterseniz ücretsiz danışmanlık alın.

Sıkça Sorulan Sorular

.cursorrules kullanımdan kalktı mı?

Evet. Proje kök dizinindeki tek .cursorrules dosyası hâlâ çalışıyor, ancak Cursor .cursor/rules/*.mdc dosyalarına geçiş yapılmasını öneriyor. Yeni format glob desenlerini, koşullu yüklemeyi ve daha iyi organizasyonu destekliyor. Tek parça dosyanızı odaklanmış kurallara bölerek geçiş yapın.

Hangi dosya uzantısını kullanmalıyım — .mdc mi yoksa .md mi?

YAML frontmatter içeren dosyalar için .mdc kullanın (description, globs, alwaysApply). Düz .md dosyaları da rules dizininde çalışır, ancak koşullu yüklemeyi sağlayan frontmatter meta verilerini desteklemez.

Bir projede kaç kural olmalı?

Çoğu proje için beş ile sekiz arası ideal. Bir daima açık temel kural, dosya türüne göre üç ile dört otomatik eklenen kural ve özel görevler için bir veya iki manuel kural. 10'dan fazla kural genellikle bazılarının birleştirilebileceğine veya kaldırılabileceğine işaret eder.

Cursor Rules otomatik tamamlamayı ve sekme tamamlamayı etkiler mi?

Kurallar sohbet ve ajan etkileşimlerine uygulanır. Kullanıcı Kuralları satır içi düzenlemelere (Cmd/Ctrl+K) uygulanmaz ve kurallar genellikle Cursor Tab otomatik tamamlama önerilerini etkilemez. Sohbet ve Composer oturumlarında en etkili şekilde çalışırlar.

Kuralları birden fazla proje arasında paylaşabilir miyim?

Evet, Cursor'ın Remote Rules özelliği aracılığıyla. Cursor Settings > Rules, Commands bölümüne gidin, "Remote Rule (GitHub)" seçeneğini seçin ve bir depo URL'si yapıştırın. Kaynak depo güncellendiğinde kurallar otomatik olarak senkronize edilir. Alternatif olarak, paylaşılan bir kurallar deposu tutabilir ve her projeye sembolik bağlantı oluşturabilirsiniz.

Önerilen maksimum kural uzunluğu nedir?

Cursor'ın belgeleri bireysel kuralları 500 satırın altında tutmayı öneriyor. Pratikte her kural için 100 satırın altını hedefleyin. Daha kısa kuralların bakımı daha kolaydır ve daha az token harcar. Bir kural 150 satırı geçiyorsa onu iki odaklanmış kurala bölün.

Kurallar Cursor'daki tüm yapay zekâ modelleriyle çalışıyor mu?

Kurallar, Cursor'ın desteklediği her modelle çalışır — Claude, GPT-4o, Gemini ve diğerleri. Kurallar, seçtiğiniz modelden bağımsız olarak sistem düzeyinde bağlam olarak enjekte edilir. Model davranışı farklılık gösterebilir, ancak kuralların kendisi model bağımsızdır.

Çalışmayan bir kuralı nasıl hata ayıklarım?

Önce glob deseninin dosyanızla eşleşip eşleşmediğini doğrulayın — dosyayı açın ve kuralın bağlam panelinde görünüp görünmediğini kontrol edin. Ardından kuralı tetiklemesi gereken doğrudan bir soruyla test edin. Sonra kural içeriğinin kendisinin çalıştığını onaylamak için geçici olarak alwaysApply: true ayarlamayı deneyin. Çalışıyorsa sorun glob desendedir.

.cursor/rules'u git'e eklemeli miyim?

Kesinlikle. Proje kurallarının amacı ekip genelinde tutarlılıktır. Kişisel tercih dosyaları dışında .cursor/rules/ içindeki her şeyi ekleyin. Herkese uygulanmaması gereken bireysel ayarlar için personal.mdc'yi .gitignore'a ekleyin.

Cursor Rules'u MCP sunucularıyla birlikte kullanabilir miyim?

Evet, ve birbirlerini güzel tamamlıyorlar. Kurallar yapay zekânın kodu nasıl yazması gerektiğini tanımlarken, MCP sunucuları yapay zekâya harici araçlara ve verilere erişim sağlar. Bir kural "her zaman dahili API istemcimizi kullan" diyebilirken, bir MCP sunucusu yapay zekânın geliştirme sırasında o API'yi gerçekten sorgulamasına olanak tanır.

Kaynaklar

• Cursor Rules Belgeleri
• Trigger.dev — Harika Cursor Rules Nasıl Yazılır
• Cursor Forum — MDC Kuralları En İyi Uygulamalar ve Sorun Giderme
• Peakvance — Cursor Rules Rehberi: Token Maliyeti
• GitHub'da awesome-cursor-rules-mdc