documentation.md

# 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

1. [Giriş](#giriş)
2. [Cursor Rules Nedir?](#cursor-rules-nedir)
3. [Mimari Tasarım](#mimari-tasarım)
4. [Frontend Arayüzü](#frontend-arayüzü)
5. [Backend Fonksiyonalitesi](#backend-fonksiyonalitesi)
6. [LLM Entegrasyonu](#llm-entegrasyonu)
7. [Hugging Face Dağıtımı](#hugging-face-dağıtımı)
8. [Kurulum ve Çalıştırma](#kurulum-ve-çalıştırma)
9. [API Referansı](#api-referansı)
10. [Örnekler](#örnekler)
11. [Sorun Giderme](#sorun-giderme)
12. [Gelecek Geliştirmeler](#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:

1. **Always**: Her zaman model bağlamına dahil edilir.
2. **Auto Attached**: Glob desenine uyan dosyalar referans alındığında dahil edilir.
3. **Agent Requested**: Kural AI'ya sunulur, dahil edilip edilmeyeceğine AI karar verir.
4. **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ı

1. **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ı

2. **API Katmanı**: Frontend ve backend arasındaki iletişim
   - HTTP endpoint'leri
   - İstek/yanıt işleme
   - Doğrulama ve hata yönetimi

3. **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

4. **Kural Oluşturma Motoru**: Cursor Rules oluşturma mantığı
   - MDC format dönüşümü
   - Şablon yönetimi
   - Kural tipi işleme

5. **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:

1. **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.
2. **Fabrika Deseni**: Kullanıcı seçimine göre doğru adaptörü oluşturan bir fabrika sınıfı.
3. **Strateji Deseni**: Farklı kural tipleri için farklı oluşturma stratejileri.
4. **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

1. **LLM Sağlayıcı Seçimi**: Gemini, OpenRouter veya OpenAI seçimi
2. **API Anahtarı Girişi**: Seçilen sağlayıcı için API anahtarı
3. **Model Seçimi**: Seçilen sağlayıcının kullanılabilir modelleri
4. **Kural Tipi Seçimi**: Always, Auto Attached, Agent Requested veya Manual
5. **Kural Açıklaması**: Kuralın amacını açıklayan kısa bir açıklama
6. **Kural İçeriği**: Kuralın ana içeriği (metin editörü)
7. **Ek Parametreler**: Kural tipine göre değişen ek parametreler
8. **Önizleme**: Oluşturulan kuralın önizlemesi
9. **İ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ışı

1. Kullanıcı LLM sağlayıcısını seçer
2. API anahtarını girer ve doğrular
3. Kullanılabilir modeller yüklenir ve kullanıcı bir model seçer
4. Kullanıcı kural tipini seçer
5. Kullanıcı kural açıklaması ve içeriğini girer
6. Kullanıcı ek parametreleri yapılandırır
7. Kullanıcı "Önizle" düğmesine tıklar ve oluşturulan kuralı görür
8. 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

1. **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

2. **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ı

3. **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

4. **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:

```python
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ı

1. Hugging Face hesabınızda yeni bir Space oluşturun
2. Space türünü "Gradio" olarak seçin
3. Huggingface klasöründeki dosyaları Space'e yükleyin
4. Gerekli çevre değişkenlerini Space ayarlarında tanımlayın
5. 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

1. Depoyu klonlayın:
   ```bash
   git clone https://github.com/yourusername/cursor-rules-generator.git
   cd cursor-rules-generator
   ```

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

3. `.env` dosyasını oluşturun:
   ```bash
   # 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

1. Uygulamayı başlatın:
   ```bash
   python app.py
   ```

2. Tarayıcınızda aşağıdaki adresi açın:
   ```
   http://localhost:5000
   ```

### Hugging Face Dağıtımı

1. Hugging Face dağıtımını çalıştırmak için:
   ```bash
   cd huggingface
   python app.py
   ```

2. 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**:
```json
[
  {
    "id": "gemini",
    "name": "Google Gemini"
  },
  {
    "id": "openai",
    "name": "OpenAI"
  },
  {
    "id": "openrouter",
    "name": "OpenRouter"
  }
]
```

### `/api/rule-types`

Desteklenen kural tiplerini listeler.

**Metod**: GET

**Yanıt**:
```json
[
  {
    "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**:
```json
{
  "provider": "gemini",
  "api_key": "your_api_key"
}
```

**Yanıt**:
```json
{
  "valid": true,
  "message": "API key is valid"
}
```

### `/api/models`

Kullanılabilir modelleri listeler.

**Metod**: POST

**İstek**:
```json
{
  "provider": "gemini",
  "api_key": "your_api_key"
}
```

**Yanıt**:
```json
[
  {
    "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**:
```json
{
  "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**:
```json
{
  "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