📄 MD vs HTML: Ne Zaman Hangisi?

📅 Tarih: 2025-11-18 | 🎯 Amaç: Markdown ve HTML kullanım kurallarını netleştirme | 📌 Versiyon: v3 (MD = TODO kuralı)

🎯 Temel Kural (Basit)

✅ HTML = RAPOR, ANALİZ, PLAN

Kullanıcı bir şeyi anlamak, görmek, incelemek istiyorsa → HTML oluştur!

Tetikleyiciler:
analiz incele rapor plan sunum gözat listele

✅ MD = TODO LİSTESİ

Kullanıcı yapılacaklar listesi istiyorsa → MD oluştur!

Tetikleyiciler:
todo todo oluştur todo listesi yapılacaklar checklist

📋 MD (Markdown) Kullanım Kuralları

🎯 MD = Sadece TODO!

Markdown dosyası SADECE ve SADECE kullanıcı TODO listesi istediğinde oluşturulur.

✅ MD Oluşturulacak Durumlar:

  • Kullanıcı "todo oluştur" derse
  • Kullanıcı "todo listesi hazırla" derse
  • Kullanıcı "yapılacaklar listesi" derse
  • Kullanıcı "checklist oluştur" derse
  • Kullanıcı "md dosyası oluştur" derse

❌ MD Oluşturulmaması Gereken Durumlar:

  • Analiz talebi → HTML oluştur (MD değil!)
  • Rapor talebi → HTML oluştur (MD değil!)
  • Plan talebi → HTML oluştur (MD değil!)
  • İnceleme talebi → HTML oluştur (MD değil!)
  • Sunum talebi → HTML oluştur (MD değil!)

📂 MD Dosya Konumu

readme/claude-docs/todo-YYYY-MM-DD-HH-MM-[konu].md Örnek: readme/claude-docs/todo-2025-11-18-14-30-blog-ai-fix.md readme/claude-docs/todo-2025-11-18-15-00-payment-integration.md

📋 MD İçeriği (Sadece TODO)

# Blog AI Fix - TODO ## Backend - [ ] `Modules/Blog/app/Services/BlogAIService.php` - Prompt düzeltme - [ ] `Modules/Blog/app/Jobs/GenerateBlogJob.php` - Queue timeout artır - [ ] Migration: `php artisan make:migration add_ai_status_to_blogs` ## Frontend - [ ] `resources/views/admin/blog/ai-panel.blade.php` - Progress bar ekle - [ ] Livewire component: AI status gösterme ## Test - [ ] Cache temizle: `php artisan view:clear` - [ ] Test: `curl https://ixtif.com/admin/blog/ai-panel` - [ ] Production deploy ## Notlar - OpenAI API timeout: 180 saniye - Queue worker restart gerekebilir

İçerik: Checkbox'lar, dosya path'leri, komutlar, teknik notlar

📊 HTML vs MD Karşılaştırması

Kullanıcı Talebi Ne Oluşturulur? Neden?
"Blog modülünü analiz et" HTML Analiz raporu → görsel sunum gerekiyor
"SEO planı hazırla" HTML Plan ve strateji → görsel rapor gerekiyor
"Modül yapısını incele" HTML İnceleme raporu → görsel sunum gerekiyor
"Tüm sayfaları listele" HTML Liste raporu → görsel tablo gerekiyor
"Detaylı sunum hazırla" HTML Sunum → görsel rapor gerekiyor
"TODO oluştur" MD Yapılacaklar listesi → checkbox markdown yeterli
"Yapılacaklar listesi hazırla" MD TODO listesi → checkbox markdown yeterli
"Checklist oluştur" MD Checklist → checkbox markdown yeterli

🤔 Karar Ağacı

Kullanıcı mesajı geldi │ ├─ "todo" kelimesi VAR mı? │ │ │ ├─ EVET → MD OLUŞTUR │ │ └─ readme/claude-docs/todo-YYYY-MM-DD-HH-MM-[konu].md │ │ │ └─ HAYIR → Tetikleyici kelime kontrolü │ │ │ ├─ Analiz/Rapor/Plan/Sunum kelimesi VAR mı? │ │ │ │ │ ├─ EVET → HTML OLUŞTUR │ │ │ └─ public/readme/YYYY-MM-DD/[konu]/v1/index.html │ │ │ │ │ └─ HAYIR → Direkt işlem yap (kod yaz/düzelt)

✅ Doğru Kullanım Örnekleri

Örnek 1: Analiz Talebi

Kullanıcı: "Blog modülünü analiz et, hangi iyileştirmeler yapılabilir?" Claude Aksiyon: 1. "analiz" kelimesi algılandı → HTML tetikleyici ✅ 2. HTML rapor oluşturulur: public/readme/2025-11-18/blog-analiz/v1/index.html 3. İçerik: Analiz raporu, iyileştirme önerileri, karşılaştırma tabloları 4. Kullanıcıya link: https://ixtif.com/readme/2025-11-18/blog-analiz/

Örnek 2: TODO Talebi

Kullanıcı: "Payment modülü için todo listesi oluştur" Claude Aksiyon: 1. "todo listesi" kelimesi algılandı → MD tetikleyici ✅ 2. MD dosyası oluşturulur: readme/claude-docs/todo-2025-11-18-14-30-payment-module.md 3. İçerik: Checkbox'lar, dosya path'leri, komutlar 4. Kullanıcıya path: readme/claude-docs/todo-2025-11-18-14-30-payment-module.md

Örnek 3: Plan Talebi (HTML, MD değil!)

Kullanıcı: "SEO iyileştirme planı hazırla" Claude Aksiyon: 1. "plan hazırla" kelimesi algılandı → HTML tetikleyici ✅ 2. ❌ MD OLUŞTURMA! (TODO değil, plan raporu!) 3. ✅ HTML rapor oluştur: public/readme/2025-11-18/seo-plani/v1/index.html 4. İçerik: Plan, stratejiler, adımlar, beklenen sonuçlar 5. Kullanıcıya link: https://ixtif.com/readme/2025-11-18/seo-plani/

❌ Yanlış Kullanım Örnekleri

Hata 1: Plan için MD oluşturmak

Kullanıcı: "Migration planı hazırla" ❌ YANLIŞ: MD dosyası oluşturmak ✅ DOĞRU: HTML rapor oluşturmak Neden? - "plan" kelimesi → HTML tetikleyici - Kullanıcı TODO istemiyor, PLAN istiyor - Plan = strateji, analiz, görsel sunum gerektirir - MD sadece checkbox listesi için kullanılır

Hata 2: Analiz için MD oluşturmak

Kullanıcı: "Mevcut modülleri analiz et" ❌ YANLIŞ: MD dosyası oluşturmak ✅ DOĞRU: HTML rapor oluşturmak Neden? - "analiz" kelimesi → HTML tetikleyici - Kullanıcı TODO istemiyor, ANALİZ istiyor - Analiz = rapor, görsel tablo, detaylı inceleme gerektirir - MD sadece checkbox listesi için kullanılır

🎯 Özet Kural Tablosu

Özellik HTML MD (Markdown)
Ne zaman? Analiz, rapor, plan, sunum, inceleme Sadece TODO listesi
Tetikleyici kelimeler analiz, incele, rapor, plan, sunum, gözat, listele... todo, yapılacaklar, checklist
İçerik tipi Görsel rapor, tablo, analiz, strateji Checkbox listesi, teknik adımlar
Konum public/readme/YYYY-MM-DD/[konu]/vX/ readme/claude-docs/todo-YYYY-MM-DD-HH-MM-[konu].md
Link tipi Web URL: https://ixtif.com/readme/... File path: readme/claude-docs/...
Versiyonlama ✅ Evet (v1, v2, v3...) ❌ Hayır (timestamp'li dosya)
Kullanım sıklığı Çok sık (analiz/rapor/plan) Az (sadece TODO)

📝 CLAUDE.md'ye Eklenecek Bölüm

### 🚨 4. MARKDOWN (MD) KULLANIMI **📝 MD = Sadece TODO!** #### 🎯 TETİKLEYİCİ KELİMELER (MD için): Sadece bu kelimeler kullanıcı mesajında geçerse → MD oluştur: - `todo` - `todo oluştur` - `todo listesi` - `yapılacaklar` - `yapılacaklar listesi` - `checklist` - `checklist oluştur` - `md dosyası oluştur` **❌ DİĞER TÜM DURUMLAR → HTML OLUŞTUR (MD değil!)** - "Plan hazırla" → HTML oluştur (MD değil!) - "Analiz et" → HTML oluştur (MD değil!) - "Rapor hazırla" → HTML oluştur (MD değil!) - "İncele" → HTML oluştur (MD değil!) #### 📂 MD Dosya Konumu: ``` readme/claude-docs/todo-YYYY-MM-DD-HH-MM-[konu].md ``` #### 📋 MD İçerik (Sadece TODO formatı): - ✅ Teknik todo listesi - ✅ Checkbox'lar (- [ ] format) - ✅ Dosya path'leri - ✅ Komutlar - ✅ Kod referansları - ✅ Teknik notlar **UNUTMA:** MD = Sadece TODO! Plan/Analiz/Rapor → HTML!