Emre Taştutan
Emre Taştutan
TastutanLabs · Mühendislik & AI Notları
Ana Sayfa/Yapay Zeka & Gelecek
Yapay Zeka & Gelecek·20 Ekim 2026·10 dk okuma

Cursor IDE Agent Modu ve .cursor/rules (.mdc) Mimarisi: Üretim Kalitesini 10 Katına Çıkaran En Popüler 10 Mühendislik Skill’i

Tekil .cursorrules dosyasının yerini alan modüler .cursor/rules/*.mdc kural motoru, 4 aktivasyon modu (Always, Auto Attached Globs, Agent Requested, Manual) ve Figma'dan koda dönüşüm, atomik çoklu dosya refactoring ile N+1 ORM koruyucu dahil en popüler 10 üretim skill şablonunun teknik analizi.

Emre Taştutan
Emre TaştutanGeliştirici & AI Meraklısı
1 okunma
Cursor IDE Agent Modu ve .cursor/rules (.mdc) Mimarisi: Üretim Kalitesini 10 Katına Çıkaran En Popüler 10 Mühendislik Skill’i

Monolitik .cursorrules Dosyasından Modüler .cursor/rules/*.mdc Mimarisine Geçiş

Yapay zeka destekli yazılım geliştirme ortamlarında (AI-native IDEs) en sık karşılaşılan mühendislik problemi bağlam penceresi seyrelmesi (context dilution) olgusudur. Projenin hem React/Next.js arayüz kurallarını, hem Java/Go/Python arka uç standartlarını, hem SQL göç (migration) kısıtlamalarını hem de güvenlik politikalarını kök dizindeki tek bir .cursorrules dosyasına yığmak; modelin her basit görevde binlerce satırlık ilgisiz talimatı okumasına neden olur. Örneğin bir CSS animasyonu düzenlenirken veritabanı indeksleme kurallarının sistem isteminde (system prompt) yer kaplaması, hem token maliyetini artırır hem de modelin talimat takip keskinliğini düşürür.

Cursor IDE resmi dokümantasyonunda tanımlanan .cursor/rules/*.mdc (Markdown Cursor) mimarisi, bu sorunu koşullu ve semantik bağlam yönlendirmesi ile çözer. Her kural kendi bağımsız .mdc dosyasında yaşar ve başındaki YAML Frontmatter bloğu sayesinde Agent Modunun bu kuralı ne zaman bağlama dahil edeceği deterministik olarak belirlenir.

Cursor .mdc Kural Motorunun 4 Aktivasyon Modu

Bir .mdc dosyası; description, globs ve alwaysApply olmak üzere üç temel üst veri alanıyla kontrol edilir ve dört farklı tetikleme modundan birinde çalışır:

  1. Always Apply (alwaysApply: true): Her sohbet ve Agent oturumunda koşulsuz olarak sistem istemine eklenir. Yalnızca tüm depoyu ilgilendiren en temel kurallar (örneğin temel teknoloji yığını, paket yöneticisi tercihi ve sıfır harici CDN ilkesi) için kullanılmalıdır.
  2. Auto Attached (globs: ["..."], alwaysApply: false): Geliştirici veya Agent, belirtilen dosya deseniyle (glob pattern) eşleşen bir dosyayı açtığında, düzenlediğinde veya bağlama eklediğinde otomatik olarak devreye girer.
  3. Agent Requested (description: "...", globs boş, alwaysApply: false): Varsayılan olarak bağlama yüklenmez; ancak Agent Modu tüm Agent Requested kuralların description alanlarını tarar ve yürütülen görevle semantik olarak eşleştiğine karar verdiğinde ilgili .mdc dosyasını otonom olarak çalışma belleğine çeker.
  4. Manual (alwaysApply: false, globs ve description boş): Yalnızca geliştirici sohbet penceresinde @kural-adi şeklinde açıkça etiketlediğinde yüklenir.
text 
.cursor/
└── rules/
    ├── 00-core-architecture.mdc      # Always Apply: Temel proje ilkeleri
    ├── 01-frontend-ui-globs.mdc      # Auto Attached: src/components/**/*.tsx
    ├── 02-design-to-code.mdc         # Agent Requested: Figma / UI dönüşümü
    ├── 03-atomic-refactoring.mdc     # Agent Requested: Çoklu dosya refactoring
    ├── 04-version-lock.mdc           # Auto Attached: package.json, pom.xml
    ├── 05-test-generation.mdc        # Auto Attached: **/*.test.ts, **/*Test.java
    ├── 06-auth-security-guard.mdc    # Auto Attached: src/auth/**, **/security/**
    ├── 07-clean-architecture.mdc     # Auto Attached: src/domain/**, src/application/**
    ├── 08-error-telemetry.mdc        # Auto Attached: src/api/**, **/controllers/**
    ├── 09-orm-performance.mdc        # Auto Attached: prisma/**, **/repositories/**
    └── 10-openapi-doc-sync.mdc       # Agent Requested: API & dokümantasyon güncelleme

Üretkenliği 10 Katına Çıkaran En Popüler 10 Cursor Agent Skill’i ve .mdc Şablonları

Aşağıda kurumsal yazılım ekiplerinde Agent Modunu otonom bir kıdemli mühendis seviyesine çıkaran 10 temel skill ve doğrudan .cursor/rules/ dizinine eklenebilecek .mdc kod şablonları yer almaktadır.

1. Dosya Desenine Göre Otomatik Devreye Giren Glob Kuralları (01-auto-attached-globs.mdc)

Agent bir arka uç denetleyicisine (controller) dokunduğunda yalnızca API kurallarının, bir React bileşenine dokunduğunda ise yalnızca arayüz kurallarının yüklenmesini sağlar. Ayrıca .mdc gövdesi içinde @file sözdizimi kullanılarak referans şema dosyaları doğrudan kurala bağlanabilir.

markdown 
---
description: Next.js App Router sunucu bileşenleri ve uç nokta standartları
globs: ["src/app/**/*.tsx", "src/app/api/**/*.ts"]
alwaysApply: false
---

# App Router & API Route Kuralları
- Tüm bileşenler varsayılan olarak React Server Component (RSC) olmalıdır; yalnızca tarayıcı API'si veya React Hook gerektiğinde en alt yaprak bileşene `"use client"` eklenir.
- API Route Handler dosyalarında gelen gövde (payload) mutlaka Zod şeması ile doğrulanmalıdır.
- Harici CDN üzerinden script veya stil dosyası çekilmesi kesinlikle yasaktır; tüm varlıklar yerel olarak (`'self'`) sunulmalıdır.

2. Figma MCP ve Tasarım Görselinden Birebir Üretim Koduna Dönüşüm (02-design-to-code.mdc)

Cursor Agent Modu, Figma Model Context Protocol (MCP) sunucusuyla veya doğrudan sohbete yüklenen ekran görüntüleriyle çalışırken sıklıkla rastgele sabit renk kodları (#3b82f6 yerine bg-[#3b82f6]) veya kırılgan mutlak konumlandırmalar (position: absolute) üretme eğilimindedir. Bu skill, görselden koda dönüşümü tasarım sistemine kilitler:

markdown 
---
description: Figma tasarımlarını, ekran görüntülerini veya UI maketlerini üretim kalitesinde bileşen koduna dönüştürürken kullanılır.
alwaysApply: false
---

# Tasarımdan Üretim Koduna (Design-to-Code) Dönüşüm Protokolü
1. **Token Eşleme:** Sabit hex renkleri veya keyfi piksel (`w-[347px]`) değerleri kullanma; tüm renk, boşluk ve tipografi değerlerini projedeki tasarım tokenlarıyla eşle.
2. **Esnek Yerleşim:** Sabit koordinatlar yerine CSS Grid ve Flexbox (`gap`, `items-center`, `justify-between`) mimarisini kullan.
3. **Durum Tamlığı:** Yalnızca ideal görünümü (happy path) değil; yükleme (`skeleton`), boş durum (`empty state`), hata ve uzun metin taşma (`truncate` / `line-clamp`) durumlarını eksiksiz uygula.

3. Çoklu Dosya (Multi-File) Atomik Refactoring (03-atomic-refactoring.mdc)

Bir veri transfer nesnesi (DTO), servis imzası veya paylaşılan arayüz değiştirildiğinde Agent bazen yalnızca açık olan dosyayı güncelleyip projedeki diğer 15 çağrı noktasını (call sites) kırık bırakabilir. Bu Agent Requested skill, çoklu dosya dönüşümlerini atomik bir işlem (transaction) disiplinine bağlar:

markdown 
---
description: Birden fazla dosyayı etkileyen arayüz, sınıf, fonksiyon imzası veya modül taşıma (refactoring) işlemlerinde kullanılır.
alwaysApply: false
---

# Çoklu Dosya Atomik Refactoring Kuralları
1. Değişikliğe başlamadan önce sembolün tüm referanslarını (`grep` / kod tabanı araması ile) eksiksiz listele.
2. Geriye dönük uyumluluk kırılıyorsa tüm tüketici dosyaları (servisler, denetleyiciler, testler ve istemci tipleri) aynı görev içinde güncelle.
3. İşlem tamamlandığında terminalde tip kontrolünü ve derleyiciyi (`tsc --noEmit` veya `mvn test-compile`) çalıştırarak sıfır derleme hatası olduğunu doğrula.

4. Halüsinasyon Önleyici Kütüphane ve Sürüm Sabitleme (04-version-lock.mdc)

Dil modelleri, eğitim kesim tarihlerinden ötürü sıklıkla eski kütüphane sürümlerine ait kaldırılmış (deprecated) sözdizimlerini üretir. Bu kural, bağımlılık bildirim dosyalarını bağlama zorunlu tutar:

markdown 
---
description: Yeni paket eklerken veya harici kütüphane API'lerini kullanırken sürüm halüsinasyonlarını önler.
globs: ["package.json", "pom.xml", "pyproject.toml", "src/**/*"]
alwaysApply: true
---

# Sürüm Sabitleme ve Halüsinasyon Önleme
- Herhangi bir çerçeve veya kütüphane kodu yazmadan önce projedeki gerçek sürümü (`package.json`, `pom.xml` veya `pyproject.toml`) kontrol et.
- Projede mevcut olmayan bir üçüncü parti kütüphaneyi açık onay olmadan içe aktarma (`import`).
- Tailwind v4, Next.js 15/16, Spring Boot 3.4+ veya Pydantic v2 gibi ana sürüm geçişlerinde eski sürüm API'lerini kesinlikle kullanma.

5. Otomatik Birim ve Entegrasyon Testi Yazıcı (05-test-generator.mdc)

Sadece tüm bağımlılıkları sahteleyen (mock) ve gerçekte hiçbir iş mantığını doğrulamayan "yeşil ama işlevsiz" testleri engeller:

markdown 
---
description: Birim (unit) ve entegrasyon testleri yazılırken veya güncellenirken uygulanır.
globs: ["**/*.test.ts", "**/*.spec.ts", "**/*Test.java", "tests/**/*.py"]
alwaysApply: false
---

# Test Mühendisliği Standardı (Arrange-Act-Assert)
- Her test metodu net bir şekilde **Arrange (Hazırlık)**, **Act (Eylem)** ve **Assert (Doğrulama)** bölümlerine ayrılmalıdır.
- Yalnızca başarılı senaryoyu değil; geçersiz girdi, sınır değerleri (null/boş koleksiyon), yetkisiz erişim ve eşzamanlılık durumlarını test et.
- Test dosyası yazıldıktan sonra terminalde ilgili test koşucusu çalıştırılarak testin gerçekten geçtiği kanıtlanmalıdır.

6. Güvenli Kimlik Doğrulama ve Yetkilendirme Denetçisi (06-auth-security-guard.mdc)

Üretim sistemlerinde en sık yaşanan güvenlik açıkları, kimlik doğrulaması (Authentication) yapılmasına rağmen kaynak sahipliği kontrolünün (Authorization / IDOR) unutulması ve arayüzde test amaçlı sabit kimlik bilgilerinin bırakılmasıdır:

markdown 
---
description: Kimlik doğrulama, oturum yönetimi, ödeme/yetki doğrulaması ve korumalı API uç noktalarında uygulanır.
globs: ["**/auth/**", "**/security/**", "**/api/**", "**/controllers/**"]
alwaysApply: false
---

# Güvenlik, OIDC/JWT ve IDOR Koruması
- **Sıfır Sabit Kimlik Bilgisi:** Kod tabanında veya UI formlarında test şifresi, sabit API anahtarı veya "Demo Girişi" butonu bulunamaz.
- **IDOR / BOLA Koruması:** İstemciden gelen `userId` veya `tenantId` parametresine asla doğrudan güvenilmez; kaynak sahipliği her zaman doğrulanmış JWT/oturum bağlamındaki kimlikle eşleştirilir.
- **Yerel Bayraklara Güvenmeme:** İstemci tarafındaki `localStorage` bayrakları yetki kanıtı sayılamaz; abonelik ve yetki durumu sunucu tarafında doğrulanır.

7. Temiz Mimari (Clean Architecture) Katman Koruyucu (07-clean-architecture.mdc)

Zamanla iş mantığı sınıflarının içine sızan HTTP istek nesneleri (HttpServletRequest, NextRequest) veya veritabanı ORM anotasyonları mimariyi çürütür. Glob tabanlı bu kural katman sınırlarını korur:

markdown 
---
description: Clean Architecture ve Hexagonal Architecture katman sınırlarını korur.
globs: ["**/domain/**", "**/application/**", "**/usecases/**"]
alwaysApply: false
---

# Katman İzolasyonu ve Bağımlılık Yönü
- **Domain Katmanı Saflığı:** `domain` dizini altındaki varlıklar ve değer nesneleri hiçbir web çerçevesine, ORM kütüphanesine veya altyapı (Infrastructure) paketine bağımlı olamaz.
- **Bağımlılıkların Tersine Çevrilmesi (DIP):** `application` katmanı dış servislerle yalnızca `domain` veya `application/ports` içinde tanımlanan arayüzler (interfaces) üzerinden konuşur.

8. Yapısal Hata Yakalama ve OpenTelemetry Standardizasyonu (08-error-telemetry.mdc)

Üretim ortamında kök neden analizini imkansız kılan boş catch (e) {} bloklarını ve standart dışı hata yanıtlarını engeller:

markdown 
---
description: Hata yönetimi, istisna fırlatma ve dağıtık izleme (logging/tracing) işlemlerinde devreye girer.
globs: ["src/api/**", "src/services/**", "**/controllers/**"]
alwaysApply: false
---

# Hata Yakalama ve Gözlemlenebilirlik (Observability)
- İstisnaları sessizce yutan boş `catch` blokları kesinlikle yasaktır.
- Dış dünyaya dönen tüm HTTP hata yanıtları **RFC 9457 (Problem Details for HTTP APIs)** şemasına (`type`, `title`, `status`, `detail`, `instance`) uymalıdır; iç yığın izleri (stack trace) istemciye sızdırılamaz.
- Log kayıtları düz metin yerine `traceId`, `spanId` ve `service` alanlarını içeren yapısal JSON formatında üretilmelidir.

9. Veritabanı ORM Performans ve N+1 Sorgu Koruyucu (09-orm-performance.mdc)

Veritabanı darboğazlarının en büyük kaynağı olan döngü içi sorguları (N+1) ve belleği tüketen sınırsız tablo okumalarını daha kod yazılırken önler:

markdown 
---
description: Veritabanı şemaları, Prisma/Hibernate/SQLAlchemy sorguları ve repository sınıflarında uygulanır.
globs: ["prisma/**", "**/repositories/**", "**/dao/**", "**/*.sql"]
alwaysApply: false
---

# Veritabanı ve ORM Performans Kuralları
- **Sıfır N+1 Sorgusu:** Bir koleksiyon üzerinde döngü kurup her adımda veritabanı sorgusu çalıştırmak yasaktır; `WHERE id IN (...)` toplu sorgusu veya açık `include` / `JOIN FETCH` kullanılmalıdır.
- **Zorunlu Sayfalama ve Projeksiyon:** Liste sorgularında üst sınır (`take` / `LIMIT`) olmadan okuma yapılamaz; tüm sütunları (`SELECT *`) çekmek yerine yalnızca gerekli alanlar seçilmelidir.

10. Otomatik Dokümantasyon ve OpenAPI Şema Güncelleyici (10-openapi-doc-sync.mdc)

Kod değiştikçe güncelliğini yitiren API belgelerini ve mimari diyagramları kodla eşzamanlı tutar:

markdown 
---
description: API uç noktaları, DTO şemaları veya genel modül arayüzleri değiştirildiğinde dokümantasyonu senkronize eder.
alwaysApply: false
---

# Canlı Dokümantasyon ve OpenAPI Senkronizasyonu
- Bir REST/GraphQL uç noktasının istek veya yanıt şeması değiştirildiğinde, aynı görev içinde OpenAPI (`openapi.yaml` / Swagger anotasyonları) ve ilgili istemci SDK tipleri güncellenir.
- Mevcut kod içi açıklamalar ve mimari yorum blokları (JSDoc / Javadoc / Python docstring) silinmez; yeni davranışla uyumlu hale getirilir.

En Popüler 10 Cursor .mdc Skill’i — Mimari Karşılaştırma Matrisi

Aşağıdaki tablo, incelenen 10 .mdc kuralının aktivasyon modlarını, hedef dosya desenlerini ve mühendislik çıktılarını özetlemektedir:

# Kural Dosyası (.cursor/rules/) Aktivasyon Modu Hedef globs / Tetikleyici Önlediği Temel Mühendislik Riski
01 01-auto-attached-globs.mdc Auto Attached src/app/**/*.tsx, src/app/api/** İlgisiz kuralların bağlam penceresini şişirmesi (Context Pollution)
02 02-design-to-code.mdc Agent Requested Semantik description (Figma/UI) Sabit piksel/renk kodları, eksik yükleme/hata durumları ve FOUC
03 03-atomic-refactoring.mdc Agent Requested Semantik description (Refactor) Çoklu dosya değişikliklerinde kırık kalan import ve tip imzaları
04 04-version-lock.mdc Always Apply alwaysApply: true + package.json Kaldırılmış (deprecated) eski sürüm API'lerinin halüsinasyonu
05 05-test-generator.mdc Auto Attached **/*.test.ts, **/*Test.java Sadece mock doğrulayan işlevsiz testler ve eksik sınır durumları
06 06-auth-security-guard.mdc Auto Attached **/auth/**, **/api/** IDOR/BOLA yetki aşımı, sabit şifreler ve güvensiz yerel bayraklar
07 07-clean-architecture.mdc Auto Attached **/domain/**, **/application/** Domain çekirdeğine sızan ORM ve HTTP çerçevesi bağımlılıkları
08 08-error-telemetry.mdc Auto Attached src/api/**, **/controllers/** Boş catch blokları, sızan stack trace'ler ve izlenemeyen hatalar
09 09-orm-performance.mdc Auto Attached prisma/**, **/repositories/** Döngü içi N+1 sorguları ve belleği tüketen sınırsız SELECT * çağrıları
10 10-openapi-doc-sync.mdc Agent Requested Semantik description (API/DTO) Kod ile OpenAPI şeması ve istemci tipleri arasındaki sözleşme kayması

Mimari Değerlendirme

Cursor IDE’nin .cursor/rules/*.mdc mimarisi, yapay zeka asistanını belirsiz istemlere (prompts) bağımlı olmaktan çıkarıp deterministik bir yazılım mimarisi koruyucusuna dönüştürmektedir. Always Apply modunun yalnızca en kritik çekirdek kurallar için tutumlu kullanılması, katman/modül kurallarının Auto Attached (globs) ile dosya desenlerine bağlanması ve görev odaklı iş akışlarının Agent Requested (description) olarak tanımlanması; hem bağlam penceresi verimliliğini maksimize etmekte hem de kurumsal kod standartlarını sürüm kontrolü (git) altında kalıcı hale getirmektedir.

Konu Etiketleri
#Software Architecture#Agentic Coding#Cursor IDE#MDC Rules#Clean Architecture
Emre Taştutan
Emre TaştutanGeliştirici & AI Meraklısı

Yazılım mimarisi, mikroservis ekosistemleri ve üretken yapay zeka uygulamaları üzerine çalışıyorum. TastutanLabs çatısı altında geliştirici araçları ve SaaS ürünleri inşa ediyorum.

@tastutanlabs • Instagram Mini-Blog

Bu analizin 6 kartlık görsel özetini Instagram'da inceleyin ve kaydedin

Her gün yazılım mimarisi, Java/JVM ve yapay zeka gelişmelerini kendi başına okunabilen 6 slaytlık Mini-Blog serileri halinde paylaşıyoruz.

Instagram'da Takip Et →
Bu Yazıyı Paylaş:

Yorumlar (0)

Düşüncelerinizi Paylaşın

Henüz yorum yapılmamış. İlk yorumu siz yapın!

Bu Kategorideki Diğer İncelemeler

Yapay Zeka & Gelecek

Google Gemini Antigravity (AGY) Mimarisi: .agents/skills/SKILL.md Hiyerarşisi ve Üretkenliği 10 Katına Çıkaran En Popüler 10 Mühendislik Skill’i

Google DeepMind’ın ajan-öncelikli geliştirme platformu Antigravity (AGY) üzerinde Progressive Disclosure ilkesiyle çalışan .agents/skills/SKILL.md mimarisi, otonom alt ajan orkestrasyonu, 4 kanallı E2E QA, savunma amaçlı pentest ve sıfır token maliyetli Reactive Wakeup dahil en popüler 10 üretim skill’inin derinlemesine rehberi.

Emre TaştutanEmre Taştutan
9 dk