Denizkızı Mimarı: Diyagram ve Dokümantasyon Becerisi

Mermaid Mimarı - Kapsamlı Diyagram ve Dokümantasyon Becerisi

Sürüm 2.0 - Akıllı orkestrasyonlu hiyerarşik mimari

İsteğe bağlı kılavuz yükleme, kod-diyagram dönüşümü ve Python araçları kullanarak Mermaid diyagramları ve tasarım dokümanları oluşturmak için güçlü bir Claude Code becerisi.

Kurulum

Skilz Pazarı Üzerinden Tek Tıkla Kurulum

Bu beceriyi anında Skilz Pazarı'ndan kurun:

skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid

Manuel Kurulum

Doğrudan Claude Code beceriler dizinine klonlayın:

# Navigate to your skills directory
cd ~/.claude/skills

# Clone the repository
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git

Kurulumu Doğrulayın

Kurulumdan sonra, becerinin mevcut olduğunu doğrulayın:

# List installed skills
ls ~/.claude/skills/design-doc-mermaid

# Or ask Claude Code
# "List my installed skills"

Bu Beceri Ne Yapar?

Akıllı Diyagram Oluşturma:

• Etkinlik diyagramları (iş akışları, süreçler, iş mantığı)
• Dağıtım diyagramları (bulut altyapısı, K8s, sunucusuz)
• Mimari diyagramları (sistem bileşenleri, mikroservisler)
• Sıralama diyagramları (API akışları, servis etkileşimleri)
• Gömülü diyagramlarla eksiksiz tasarım dokümanları

Kod-Diyagram Dönüşümü:

• Spring Boot uygulamalarından mimari çıkarma
• Yapılandırma dosyalarından dağıtım diyagramları oluşturma
• Yöntem çağrılarından sıralama diyagramları oluşturma
• ETL boru hatlarını ve veri akışlarını belgeleme

Diyagram Yönetimi:

• Markdown dosyalarından Mermaid diyagramları çıkarma
• mermaid-cli ile diyagram sözdizimini doğrulama
• Diyagramları PNG/SVG görüntülerine dönüştürme
• Tüm dizinleri toplu olarak işleme

Hızlı Başlangıç

Bir Etkinlik Diyagramı Oluşturun

User: "Create an activity diagram for user registration with email verification"

Beceri şunları yapacak:

1. references/guides/diagrams/activity-diagrams.md dosyasını yükle
2. kayıt deseni şablonunu kullan
3. Unicode sembolleri ekle (güvenlik için 🔐, e-posta için 📧, başarı için ✅)
4. yüksek kontrastlı stil uygula
5. tamamlanmış Mermaid diyagramını çıktı olarak ver

Koddan Oluştur

User: "Here's my Spring Boot application.yml - generate a deployment diagram"

Beceri şunları yapacak:

1. yapılandırmayı analiz et (veri kaynağı, önbellek, güvenlik)
2. references/guides/diagrams/deployment-diagrams.md dosyasını yükle
3. examples/spring-boot/README.md dosyasını yükle
4. yapılandırmayı bulut kaynaklarına eşle
5. kaynak özellikleriyle dağıtım diyagramı oluştur

Tasarım Dokümanı Oluştur

User: "Create an API design document for the contacts API"

Beceri şunları yapacak:

1. assets/api-design-template.md dosyasını yükle
2. ilgili diyagram kılavuzlarını yükle (sıralama, ER, mimari)
3. gömülü diyagramlarla eksiksiz doküman oluştur
4. docs/design/api-contacts-v1-2025-01-13.md konumuna kaydet

Yapı

Hiyerarşik Organizasyon

mermaid-architect/
├── SKILL.md                          # Main orchestrator with decision tree
├── README.md                         # This file
├── CLAUDE.md                         # Claude Code instructions
│
├── references/                       # Reference materials
│   ├── mermaid-diagram-guide.md     # Legacy general guide
│   └── guides/                       # Specialized guides (load on-demand)
│       ├── diagrams/
│       │   ├── activity-diagrams.md      # ✅ Complete
│       │   ├── deployment-diagrams.md    # ✅ Complete
│       │   ├── architecture-diagrams.md  # ✅ Complete
│       │   └── sequence-diagrams.md      # ✅ Complete
│       ├── code-to-diagram/
│       │   └── README.md                 # ✅ Complete (master guide)
│       ├── unicode-symbols/
│       │   └── guide.md                  # ✅ Complete (100+ symbols)
│       └── troubleshooting.md        # ✅ Complete (28 common errors)
│
├── scripts/                          # Python utilities
│   ├── extract_mermaid.py           # ✅ Extract & validate diagrams
│   └── mermaid_to_image.py          # ✅ Convert to PNG/SVG
│
├── examples/                         # Language-specific patterns
│   ├── spring-boot/                 # ✅ Complete
│   ├── fastapi/                     # ✅ Complete
│   ├── react/                       # ✅ Complete
│   ├── python-etl/                  # ✅ Complete
│   ├── node-webapp/                 # ✅ Complete
│   └── java-webapp/                 # ✅ Complete
│
└── assets/                           # Design document templates
    ├── architecture-design-template.md
    ├── api-design-template.md
    ├── feature-design-template.md
    ├── database-design-template.md
    └── system-design-template.md

Temel Özellikler

1. Unicode Anlamsal Semboller

Her diyagram anlamlı Unicode sembolleri kullanır:

graph TB
    User[👤 Client] --> Gateway[🌐 API Gateway]
    Gateway --> Auth[🔐 Auth Service]
    Gateway --> API[⚙️ API Service]
    API --> DB[(💾 Database)]
    API --> Cache[(⚡ Redis)]
    API --> Queue[📬 Message Queue]
    Queue --> Worker[⚙️ Background Worker]

Sembol Kategorileri:

• Altyapı: ☁️ 🌐 🔌 📡 🗄️
• Hesaplama: ⚙️ ⚡ 🔄 🚀 💨
• Veri: 💾 📦 📊 📈 🗃️
• Mesajlaşma: 📨 📬 📤 📥 🐰
• Güvenlik: 🔐 🔑 🛡️ 🚪 👤
• İzleme: 📝 📊 🚨 ⚠️ ✅ ❌

2. Yüksek Kontrastlı Stil

Tüm diyagramlar erişilebilir, yüksek kontrastlı renkler kullanır - tam ayrıntılar için SKILL.md'ye bakın.

3. Python Araçları

Diyagramları Çıkar

# List all diagrams in a file
python scripts/extract_mermaid.py document.md --list-only

# Extract to separate .mmd files
python scripts/extract_mermaid.py document.md --output-dir diagrams/

# Validate all diagrams
python scripts/extract_mermaid.py document.md --validate

# Replace diagrams with image references (for Confluence)
python scripts/extract_mermaid.py document.md --replace-with-images \
  --image-format png --output-markdown output.md

Görüntülere Dönüştür

# Single file
python scripts/mermaid_to_image.py diagram.mmd output.png

# Custom theme and size
python scripts/mermaid_to_image.py diagram.mmd output.svg \
  --theme dark --background white --width 1200

# Batch convert directory
python scripts/mermaid_to_image.py diagrams/ output/ \
  --format png --recursive

# From stdin
echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png

Gereksinimler

Diyagram Oluşturma İçin

• Claude Code beceri sistemi (otomatik)
• Kılavuzlar ve şablonlar (bu beceriye dahildir)

Doğrulama ve Görüntü Dönüştürme İçin

# Install mermaid-cli globally
npm install -g @mermaid-js/mermaid-cli

# Verify installation
mmdc --version

Python Betikleri İçin

• Python 3.7+
• Ek paket gerektirmez (sadece stdlib kullanır)

Öğrenme Yolu

Mermaid Diyagramlarında Yeni misiniz?

1. Etkinlik Diyagramları ile Başlayın - references/guides/diagrams/activity-diagrams.md dosyasını okuyun
2. Unicode Sembollerini Öğrenin - references/guides/unicode-symbols/guide.md dosyasını okuyun
3. Bir Örnek Deneyin - examples/spring-boot/ dizinindeki desenleri kullanın
4. Çalışmanızı Doğrulayın - python scripts/extract_mermaid.py --validate komutunu çalıştırın

Mevcut Kodu Belgelerne İhtiyacınız Var mı?

1. Çerçeveyi Belirleyin - Spring Boot, FastAPI, React, vb.
2. Örnek Kılavuzu Yükleyin - examples/{your-framework}/README.md dosyasını okuyun
3. Desenleri Eşleştirin - Örneklerde benzer kod desenlerini bulun
4. Diyagramlar Oluşturun - Kılavuzlardaki şablonları kullanın
5. Doğrulayın - Doğrulama betiklerini kullanın

Tasarım Dokümanları mı Oluşturuyorsunuz?

1. Şablon Türünü Seçin - Mimari, API, Özellik, Veritabanı veya Sistem
2. Şablonu Yükleyin - assets/{type}-design-template.md dosyasından okuyun
3. Bölümleri Doldurun - Yer tutucuları gerçek içerikle değiştirin
4. Diyagramlar Ekleyin - Her bölüm için gerektiğinde diyagram kılavuzlarını yükleyin
5. Semboller Kullanın - Unicode sembolleriyle zenginleştirin
6. Kaydedin - Zaman damgasıyla docs/design/ dizinine yerleştirin

Hiyerarşik Sistem Nasıl Çalışır?

Geleneksel Yaklaşım (Verimsiz)

• Tüm beceri dokümantasyonunu yükle (~50KB)
• YZ tüm şablonları ve örnekleri işler
• Yüksek token kullanımı
• Yavaş yanıt süresi

Hiyerarşik Yaklaşım (Verimli)

1. Kullanıcı istek yapar → YZ amacı analiz eder
2. Karar ağacı etkinleşir → Gerekli kılavuzları belirler
3. Yalnızca gerekeni yükle → Belirli kılavuzu okur (~2-5KB)
4. Çıktı oluştur → Hedeflenmiş şablonları kullanır
5. Token açısından verimli → 10 kat daha az bağlam gerekir

Örnek Akış

Kullanıcı: "Docker Compose kurulumum için dağıtım diyagramı oluştur"

Karar Ağacı:

1. Analyze: "deployment diagram" + "Docker Compose"
2. Determine: deployment-diagrams.md needed
3. Load: references/guides/diagrams/deployment-diagrams.md (2KB)
4. Find pattern: Docker Compose template exists
5. Generate: Using template + Unicode symbols
6. Output: Complete diagram in <30 seconds

Kullanılan Token: ~2.000 (geleneksel yaklaşımda ~10.000'e karşı)

Tamamlanma Durumu

✅ Tamamlandı:

• Hiyerarşik karar ağacı orkestratörü
• Şablonlu etkinlik diyagramı kılavuzu
• Dağıtım diyagramı kılavuzu (AWS, GCP, K8s, sunucusuz, Docker)
• Unicode sembolleri kılavuzu (100+ sembol)
• Doğrulamalı Mermaid betiği çıkarma
• Mermaid'i görüntüye dönüştürme betiği
• Spring Boot kod-diyagram örnekleri
• Tasarım dokümanı şablonları (5 tür)
• Yüksek kontrastlı stil sistemi

🚧 Devam Ediyor:

• FastAPI örnekleri
• React bileşen mimarisi örnekleri
• Python ETL boru hattı örnekleri

📋 Planlanan:

• Mimari diyagramları kılavuzu
• Sıralama diyagramları kılavuzu
• Kod-diyagram ana kılavuzu
• Node.js/Express örnekleri
• Java web uygulaması örnekleri

Katkıda Bulunma

Yeni bir diyagram türü kılavuzu eklemek için:

1. references/guides/diagrams/{type}-diagrams.md yolunda kılavuz oluşturun
2. Şunları içermeli:
   • Ne zaman kullanılır
   • Temel sözdizimi
   • Yaygın desenler (3-5 şablon)
   • Unicode sembol örnekleri
   • En iyi uygulamalar
3. SKILL.md karar ağacını güncelleyin
4. Kod eşlemeleriyle örnekler ekleyin

Yeni bir dil örneği eklemek için:

1. examples/{framework}/ dizininde bir dizin oluşturun
2. Şunları içeren bir README.md ekleyin:
   • Çerçeve genel bakış
   • Yapıdan mimari diyagramı
   • Yapılandırmadan dağıtım diyagramı
   • Koddan sıralama diyagramı
   • Mantıktan etkinlik diyagramı
3. SKILL.md kod-diyagram tablosunu güncelleyin

Lisans

Claude Code Becerilerinin bir parçası - MIT Lisansı

İlgili Beceriler

• confluence - Diyagramları Confluence'a yükle
• plantuml - Alternatif diyagram formatı

Bağlantılar

• GitHub Deposu
• Skilz Pazarı Listesi
• Mermaid Resmi Dokümantasyonu

Sürüm: 2.0.0 Güncellendi: 2025-01-13 Tarafından sürdürülüyor: SpillwaveSolutions