Cursor Rules Oluşturucu - Kapsamlı Dokümantasyon

Bu dokümantasyon, Gemini, OpenRouter, OpenAI API ve tüm modellerini destekleyen dinamik bir Cursor Rules oluşturucu uygulamasını detaylı olarak açıklamaktadır.

İçindekiler

Giriş
Cursor Rules Nedir?
Mimari Tasarım
Frontend Arayüzü
Backend Fonksiyonalitesi
LLM Entegrasyonu
Hugging Face Dağıtımı
Kurulum ve Çalıştırma
API Referansı
Örnekler
Sorun Giderme
Gelecek Geliştirmeler

Giriş

Cursor Rules Oluşturucu, Cursor editörü için kurallar oluşturmanıza yardımcı olan güçlü bir araçtır. Bu uygulama, farklı LLM (Large Language Model) sağlayıcılarını kullanarak dinamik ve özelleştirilebilir Cursor Rules oluşturmanıza olanak tanır.

Uygulama, kullanıcı dostu bir web arayüzü sunar ve Hugging Face Spaces üzerinde dağıtılabilir, böylece herkes tarafından kolayca erişilebilir.

Cursor Rules Nedir?

Cursor Rules, AI modellerine sistem düzeyinde rehberlik sağlamanıza olanak tanır. Projeleriniz veya kendiniz için bağlam, tercihler veya iş akışlarını kodlamanın kalıcı bir yoludur.

Büyük dil modelleri, tamamlamalar arasında bellek tutmaz. Kurallar, kalıcı, yeniden kullanılabilir bağlamı komut düzeyinde sağlayarak bu sorunu çözer.

Bir kural uygulandığında, içeriği model bağlamının başlangıcına dahil edilir. Bu, AI'ya kod oluştururken, düzenlemeleri yorumlarken veya bir iş akışına yardımcı olurken tutarlı rehberlik sağlar.

Kural Tipleri

Cursor Rules dört farklı tipte olabilir:

Always: Her zaman model bağlamına dahil edilir.
Auto Attached: Glob desenine uyan dosyalar referans alındığında dahil edilir.
Agent Requested: Kural AI'ya sunulur, dahil edilip edilmeyeceğine AI karar verir.
Manual: Yalnızca @ruleName kullanılarak açıkça belirtildiğinde dahil edilir.

MDC Formatı

Cursor Rules, MDC (Markdown with Context) formatında yazılır. Bu format, metadata ve içeriği tek bir dosyada birleştirir:

---
description: RPC Service boilerplate
globs: 
alwaysApply: false
---

- Use our internal RPC pattern when defining services
- Always use snake_case for service names.

@service-template.ts

Mimari Tasarım

Cursor Rules Oluşturucu, aşağıdaki ana bileşenlerden oluşan katmanlı bir mimariye sahiptir:

Genel Mimari Yapı

+----------------------------------+
|           Web Arayüzü            |
|  (HTML, CSS, JavaScript, React)  |
+----------------------------------+
                 |
                 v
+----------------------------------+
|         API Katmanı              |
|  (Flask/FastAPI, API Endpoint)   |
+----------------------------------+
                 |
                 v
+----------------------------------+
|       LLM Entegrasyon Katmanı    |
|  (Adaptörler, Fabrika Deseni)    |
+----------------------------------+
                 |
                 v
+----------------------------------+
|       Kural Oluşturma Motoru     |
|  (MDC Format, Şablonlar)         |
+----------------------------------+
                 |
                 v
+----------------------------------+
|       Depolama Katmanı           |
|  (Dosya Sistemi, Veritabanı)     |
+----------------------------------+

Katmanlar ve Sorumlulukları

Web Arayüzü: Kullanıcı etkileşimi için frontend arayüzü
- Kural oluşturma formu
- LLM sağlayıcı seçimi
- Kural tipi ve parametreleri yapılandırma
- Önizleme ve indirme fonksiyonları
API Katmanı: Frontend ve backend arasındaki iletişim
- HTTP endpoint'leri
- İstek/yanıt işleme
- Doğrulama ve hata yönetimi
LLM Entegrasyon Katmanı: Farklı LLM sağlayıcılarıyla iletişim
- Adaptör deseni ile sağlayıcı entegrasyonu
- API anahtarı yönetimi
- İstek formatı dönüşümleri
Kural Oluşturma Motoru: Cursor Rules oluşturma mantığı
- MDC format dönüşümü
- Şablon yönetimi
- Kural tipi işleme
Depolama Katmanı: Veri saklama ve erişim
- Oluşturulan kuralları saklama
- Şablonları yönetme
- Kullanıcı tercihlerini saklama

Tasarım Desenleri

Uygulama, aşağıdaki tasarım desenlerini kullanır:

Adaptör Deseni: Her LLM sağlayıcısı için ayrı bir adaptör sınıfı, ortak bir arayüz üzerinden erişim sağlar.
Fabrika Deseni: Kullanıcı seçimine göre doğru adaptörü oluşturan bir fabrika sınıfı.
Strateji Deseni: Farklı kural tipleri için farklı oluşturma stratejileri.
Singleton Deseni: Konfigürasyon yönetimi için tek bir örnek.

Frontend Arayüzü

Frontend arayüzü, kullanıcıların sezgisel olarak Cursor Rules oluşturabilmesi için tasarlanmıştır.

Ana Bileşenler

LLM Sağlayıcı Seçimi: Gemini, OpenRouter veya OpenAI seçimi
API Anahtarı Girişi: Seçilen sağlayıcı için API anahtarı
Model Seçimi: Seçilen sağlayıcının kullanılabilir modelleri
Kural Tipi Seçimi: Always, Auto Attached, Agent Requested veya Manual
Kural Açıklaması: Kuralın amacını açıklayan kısa bir açıklama
Kural İçeriği: Kuralın ana içeriği (metin editörü)
Ek Parametreler: Kural tipine göre değişen ek parametreler
Önizleme: Oluşturulan kuralın önizlemesi
İndirme: Oluşturulan kuralı indirme seçeneği

Teknolojiler

Frontend aşağıdaki teknolojileri kullanır:

HTML5: Sayfa yapısı
CSS3: Stil ve düzen
JavaScript (ES6+): Etkileşim ve dinamik içerik
Responsive Design: Mobil ve masaüstü uyumluluğu

Kullanıcı Deneyimi Akışı

Kullanıcı LLM sağlayıcısını seçer
API anahtarını girer ve doğrular
Kullanılabilir modeller yüklenir ve kullanıcı bir model seçer
Kullanıcı kural tipini seçer
Kullanıcı kural açıklaması ve içeriğini girer
Kullanıcı ek parametreleri yapılandırır
Kullanıcı "Önizle" düğmesine tıklar ve oluşturulan kuralı görür
Kullanıcı "İndir" düğmesine tıklayarak kuralı indirir

Backend Fonksiyonalitesi

Backend, uygulamanın çekirdeğini oluşturur ve LLM sağlayıcılarıyla iletişim kurarak Cursor Rules oluşturur.

Modüller

API Modülü: Frontend ile iletişim için RESTful API endpoint'leri
- /api/providers: Desteklenen LLM sağlayıcılarını listeler
- /api/rule-types: Desteklenen kural tiplerini listeler
- /api/validate-api-key: API anahtarlarını doğrular
- /api/models: Kullanılabilir modelleri listeler
- /api/generate-rule: Cursor Rule oluşturur
LLM Entegrasyon Modülü: LLM sağlayıcılarıyla iletişim
- adapter.py: Temel adaptör arayüzü
- gemini_adapter.py: Gemini adaptörü
- openai_adapter.py: OpenAI adaptörü
- openrouter_adapter.py: OpenRouter adaptörü
- factory.py: LLM fabrikası
Kural Oluşturma Motoru: Cursor Rules oluşturma
- rule_generator.py: Kural oluşturucu
- mdc_formatter.py: MDC format dönüştürücü
- templates.py: Şablon yöneticisi
Konfigürasyon Modülü: Uygulama ayarları
- settings.py: Konfigürasyon ayarları

Teknolojiler

Backend aşağıdaki teknolojileri kullanır:

Python 3.10+: Ana programlama dili
Flask: Web framework
Flask-CORS: Cross-Origin Resource Sharing desteği
Requests: HTTP istekleri için
Python-dotenv: Çevre değişkenleri yönetimi

LLM Entegrasyonu

Uygulama, üç farklı LLM sağlayıcısını destekler: Gemini, OpenRouter ve OpenAI.

Gemini API

Google tarafından sağlanan AI modelleri:

Modeller: Gemini 2.5 Pro, Gemini 2.0 Flash, Gemini 2.0 Flash-Lite
Özellikler: Metin, görüntü, video ve doküman anlama yetenekleri
Entegrasyon: google-genai kütüphanesi

OpenRouter API

Yüzlerce AI modelini tek bir endpoint üzerinden erişim:

Modeller: OpenAI, Anthropic, Google, Meta ve diğer sağlayıcıların modelleri
Özellikler: Otomatik yedekleme, maliyet-etkin model seçimi
Entegrasyon: OpenAI SDK uyumluluğu

OpenAI API

GPT modelleri ve diğer AI modellerine erişim:

Modeller: GPT-4o, GPT-4 Turbo, GPT-3.5 Turbo
Özellikler: Metin oluşturma, doğal dil işleme
Entegrasyon: openai kütüphanesi

Adaptör Deseni

Her LLM sağlayıcısı için ayrı bir adaptör sınıfı oluşturulmuştur. Tüm adaptörler ortak bir arayüzü uygular:

class LLMAdapter(ABC):
    @abstractmethod
    def initialize(self, api_key, **kwargs):
        pass
    
    @abstractmethod
    def generate_rule(self, model, rule_type, description, content, parameters=None):
        pass
    
    @abstractmethod
    def get_available_models(self):
        pass
    
    @abstractmethod
    def validate_api_key(self, api_key):
        pass

Hugging Face Dağıtımı

Uygulama, Hugging Face Spaces'e dağıtılabilir, böylece herkes tarafından kolayca erişilebilir.

Dağıtım Dosyaları

app.py: Gradio arayüzünü ve uygulama mantığını içeren ana dosya
requirements.txt: Gerekli Python paketlerini listeleyen dosya
README.md: Proje hakkında bilgi veren dosya
DEPLOYMENT.md: Dağıtım adımlarını açıklayan dosya

Gradio Arayüzü

Hugging Face dağıtımı için Gradio tabanlı bir arayüz oluşturulmuştur. Bu arayüz, web arayüzünün tüm özelliklerini Gradio bileşenleri kullanarak yeniden oluşturur:

LLM sağlayıcı seçimi
API anahtarı doğrulama
Model seçimi
Kural tipi yapılandırma
Kural oluşturma ve indirme

Dağıtım Adımları

Hugging Face hesabınızda yeni bir Space oluşturun
Space türünü "Gradio" olarak seçin
Huggingface klasöründeki dosyaları Space'e yükleyin
Gerekli çevre değişkenlerini Space ayarlarında tanımlayın
Space'i dağıtın

Kurulum ve Çalıştırma

Gereksinimler

Python 3.10 veya üzeri
pip (Python paket yöneticisi)
Node.js ve npm (isteğe bağlı, geliştirme için)

Kurulum

Depoyu klonlayın:

git clone https://github.com/yourusername/cursor-rules-generator.git
cd cursor-rules-generator

Bağımlılıkları yükleyin:
```
pip install -r requirements.txt
```

.env dosyasını oluşturun:

# App settings
DEBUG=True
PORT=5000

# API keys (optional)
GEMINI_API_KEY=your_gemini_api_key
OPENAI_API_KEY=your_openai_api_key
OPENROUTER_API_KEY=your_openrouter_api_key

Çalıştırma

Uygulamayı başlatın:
```
python app.py
```
Tarayıcınızda aşağıdaki adresi açın:
```
http://localhost:5000
```

Hugging Face Dağıtımı

Hugging Face dağıtımını çalıştırmak için:
```
cd huggingface
python app.py
```
Tarayıcınızda aşağıdaki adresi açın:
```
http://localhost:7860
```

API Referansı

`/api/providers`

Desteklenen LLM sağlayıcılarını listeler.

Metod: GET

Yanıt:

[
  {
    "id": "gemini",
    "name": "Google Gemini"
  },
  {
    "id": "openai",
    "name": "OpenAI"
  },
  {
    "id": "openrouter",
    "name": "OpenRouter"
  }
]

`/api/rule-types`

Desteklenen kural tiplerini listeler.

Metod: GET

Yanıt:

[
  {
    "id": "Always",
    "name": "Always",
    "description": "Always included in the model context"
  },
  {
    "id": "Auto Attached",
    "name": "Auto Attached",
    "description": "Included when files matching glob patterns are referenced"
  },
  {
    "id": "Agent Requested",
    "name": "Agent Requested",
    "description": "Rule is presented to the AI, which decides whether to include it"
  },
  {
    "id": "Manual",
    "name": "Manual",
    "description": "Only included when explicitly referenced using @ruleName"
  }
]

`/api/validate-api-key`

API anahtarını doğrular.

Metod: POST

İstek:

{
  "provider": "gemini",
  "api_key": "your_api_key"
}

Yanıt:

{
  "valid": true,
  "message": "API key is valid"
}

`/api/models`

Kullanılabilir modelleri listeler.

Metod: POST

İstek:

{
  "provider": "gemini",
  "api_key": "your_api_key"
}

Yanıt:

[
  {
    "id": "gemini-2.5-pro",
    "name": "Gemini 2.5 Pro"
  },
  {
    "id": "gemini-2.0-flash",
    "name": "Gemini 2.0 Flash"
  },
  {
    "id": "gemini-2.0-flash-lite",
    "name": "Gemini 2.0 Flash-Lite"
  }
]

`/api/generate-rule`

Cursor Rule oluşturur.

Metod: POST

İstek:

{
  "provider": "gemini",
  "api_key": "your_api_key",
  "model": "gemini-2.0-flash",
  "rule_type": "Always",
  "description": "Code style guide",
  "content": "- Use camelCase for variable names\n- Use PascalCase for class names",
  "parameters": {
    "globs": "",
    "referenced_files": "@style-guide.ts",
    "temperature": 0.7
  }
}

Yanıt:

{
  "rule": "---\ndescription: Code style guide\nalwaysApply: true\n---\n\n- Use camelCase for variable names\n- Use PascalCase for class names\n\n@style-guide.ts"
}

Örnekler

Örnek 1: Always Kural Tipi

---
description: Code style guide
alwaysApply: true
---

- Use camelCase for variable names
- Use PascalCase for class names
- Use UPPER_CASE for constants
- Use snake_case for file names

@style-guide.ts

Örnek 2: Auto Attached Kural Tipi

---
description: React component template
globs: *.tsx, src/components/*.tsx
alwaysApply: false
---

- Use functional components with hooks
- Export components as default
- Use PropTypes for type checking
- Follow the component structure:
  1. Imports
  2. Types
  3. Component
  4. Styles
  5. Export

@component-template.tsx

Örnek 3: Agent Requested Kural Tipi

---
description: Database query optimization
alwaysApply: false
---

- Use indexes for frequently queried columns
- Avoid SELECT * and specify required columns
- Use prepared statements for parameterized queries
- Add EXPLAIN before queries to analyze performance
- Consider using query caching for repeated queries

@query-optimization.sql

Örnek 4: Manual Kural Tipi

---
description: API error handling
alwaysApply: false
---

- Use standard HTTP status codes
- Return error responses in consistent format:
  ```json
  {
    "error": {
      "code": "ERROR_CODE",
      "message": "Human readable message",
      "details": {}
    }
  }

Log errors with correlation IDs
Handle validation errors separately from system errors

@error-handling.ts


## Sorun Giderme

### API Anahtarı Doğrulama Sorunları

**Sorun**: API anahtarı doğrulanamıyor.

**Çözüm**:
1. API anahtarının doğru olduğunu kontrol edin
2. İnternet bağlantınızı kontrol edin
3. LLM sağlayıcısının hizmet durumunu kontrol edin
4. API anahtarınızın kullanım limitlerini kontrol edin

### Model Yükleme Sorunları

**Sorun**: Modeller yüklenmiyor.

**Çözüm**:
1. API anahtarının doğrulandığından emin olun
2. Tarayıcı konsolunda hata mesajlarını kontrol edin
3. Ağ isteklerini tarayıcı geliştirici araçlarında inceleyin
4. Uygulamayı yeniden başlatın

### Kural Oluşturma Sorunları

**Sorun**: Kural oluşturulamıyor.

**Çözüm**:
1. Tüm gerekli alanların doldurulduğundan emin olun
2. API anahtarının ve modelin doğru seçildiğini kontrol edin
3. İçerik uzunluğunun model limitleri dahilinde olduğunu kontrol edin
4. Tarayıcı konsolunda hata mesajlarını kontrol edin

## Gelecek Geliştirmeler

1. **Kullanıcı Hesapları**: Kullanıcıların kurallarını kaydetmesi ve yönetmesi için hesap sistemi
2. **Kural Kütüphanesi**: Önceden hazırlanmış kurallar için bir kütüphane
3. **Kural Paylaşımı**: Kuralları diğer kullanıcılarla paylaşma özelliği
4. **Çoklu Dil Desteği**: Farklı diller için arayüz çevirileri
5. **Gelişmiş Şablonlar**: Daha fazla özelleştirme seçeneği sunan gelişmiş şablonlar
6. **Offline Modu**: İnternet bağlantısı olmadan çalışabilme özelliği
7. **Kural Doğrulama**: Oluşturulan kuralların doğruluğunu kontrol etme özelliği
8. **Kural Versiyonlama**: Kuralların farklı versiyonlarını yönetme özelliği
9. **Daha Fazla LLM Sağlayıcısı**: Daha fazla LLM sağlayıcısı desteği
10. **Performans Optimizasyonu**: Daha hızlı kural oluşturma ve önbelleğe alma