Mermaid Architect: Umiejętność diagramowania i dokumentacji

Mermaid Architect - Kompleksowa Umiejętność Tworzenia Diagramów i Dokumentacji

Wersja 2.0 - Hierarchiczna architektura z inteligentną orkiestracją

Potężna umiejętność Claude Code do tworzenia diagramów Mermaid i dokumentów projektowych przy użyciu ładowania przewodników na żądanie, generowania diagramów z kodu oraz narzędzi w Pythonie.

Instalacja

Instalacja jednym kliknięciem przez Skilz Marketplace

Zainstaluj tę umiejętność natychmiast z Skilz Marketplace:

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

Instalacja ręczna

Sklonuj bezpośrednio do katalogu umiejętności Claude Code:

# Przejdź do katalogu umiejętności
cd ~/.claude/skills

# Sklonuj repozytorium
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git

Weryfikacja instalacji

Po instalacji sprawdź, czy umiejętność jest dostępna:

# Wyświetl zainstalowane umiejętności
ls ~/.claude/skills/design-doc-mermaid

# Lub zapytaj Claude Code
# "Wyświetl moje zainstalowane umiejętności"

Co robi ta umiejętność

Inteligentne generowanie diagramów:

• Diagramy aktywności (przepływy pracy, procesy, logika biznesowa)
• Diagramy wdrożeniowe (infrastruktura chmurowa, K8s, serverless)
• Diagramy architektury (komponenty systemu, mikroserwisy)
• Diagramy sekwencji (przepływy API, interakcje serwisów)
• Kompletne dokumenty projektowe z osadzonymi diagramami

Konwersja kodu na diagram:

• Wyodrębnianie architektury z aplikacji Spring Boot
• Generowanie diagramów wdrożeniowych z plików konfiguracyjnych
• Tworzenie diagramów sekwencji z wywołań metod
• Dokumentowanie potoków ETL i przepływów danych

Zarządzanie diagramami:

• Wyodrębnianie diagramów Mermaid z plików Markdown
• Walidacja składni diagramów za pomocą mermaid-cli
• Konwersja diagramów do obrazów PNG/SVG
• Przetwarzanie wsadowe całych katalogów

Szybki start

Tworzenie diagramu aktywności

Użytkownik: "Utwórz diagram aktywności dla rejestracji użytkownika z weryfikacją e-mail"

Umiejętność:

1. Załaduje references/guides/diagrams/activity-diagrams.md
2. Użyje szablonu wzorca rejestracji
3. Doda symbole Unicode (🔐 dla bezpieczeństwa, 📧 dla e-maila, ✅ dla sukcesu)
4. Zastosuje stylistykę wysokiego kontrastu
5. Wygeneruje kompletny diagram Mermaid

Generowanie z kodu

Użytkownik: "Oto mój plik application.yml z Spring Boot - wygeneruj diagram wdrożeniowy"

Umiejętność:

1. Przeanalizuje konfigurację (źródło danych, cache, bezpieczeństwo)
2. Załaduje references/guides/diagrams/deployment-diagrams.md
3. Załaduje examples/spring-boot/README.md
4. Zmapuje konfigurację na zasoby chmurowe
5. Wygeneruje diagram wdrożeniowy ze specyfikacjami zasobów

Tworzenie dokumentu projektowego

Użytkownik: "Utwórz dokument projektowy API dla API kontaktów"

Umiejętność:

1. Załaduje assets/api-design-template.md
2. Załaduje odpowiednie przewodniki po diagramach (sekwencji, ER, architektury)
3. Wygeneruje kompletny dokument z osadzonymi diagramami
4. Zapisze do docs/design/api-contacts-v1-2025-01-13.md

Struktura

Organizacja hierarchiczna

mermaid-architect/
├── SKILL.md                          # Główny orkiestrator z drzewem decyzyjnym
├── README.md                         # Ten plik
├── CLAUDE.md                         # Instrukcje Claude Code
│
├── references/                       # Materiały referencyjne
│   ├── mermaid-diagram-guide.md     # Stary ogólny przewodnik
│   └── guides/                       # Specjalistyczne przewodniki (ładowane na żądanie)
│       ├── diagrams/
│       │   ├── activity-diagrams.md      # ✅ Ukończone
│       │   ├── deployment-diagrams.md    # ✅ Ukończone
│       │   ├── architecture-diagrams.md  # ✅ Ukończone
│       │   └── sequence-diagrams.md      # ✅ Ukończone
│       ├── code-to-diagram/
│       │   └── README.md                 # ✅ Ukończone (główny przewodnik)
│       ├── unicode-symbols/
│       │   └── guide.md                  # ✅ Ukończone (100+ symboli)
│       └── troubleshooting.md        # ✅ Ukończone (28 typowych błędów)
│
├── scripts/                          # Narzędzia w Pythonie
│   ├── extract_mermaid.py           # ✅ Wyodrębnianie i walidacja diagramów
│   └── mermaid_to_image.py          # ✅ Konwersja do PNG/SVG
│
├── examples/                         # Wzorce specyficzne dla języka
│   ├── spring-boot/                 # ✅ Ukończone
│   ├── fastapi/                     # ✅ Ukończone
│   ├── react/                       # ✅ Ukończone
│   ├── python-etl/                  # ✅ Ukończone
│   ├── node-webapp/                 # ✅ Ukończone
│   └── java-webapp/                 # ✅ Ukończone
│
└── assets/                           # Szablony dokumentów projektowych
    ├── architecture-design-template.md
    ├── api-design-template.md
    ├── feature-design-template.md
    ├── database-design-template.md
    └── system-design-template.md

Kluczowe cechy

1. Semantyczne symbole Unicode

Każdy diagram używa znaczących symboli Unicode:

graph TB
    User[👤 Klient] --> Gateway[🌐 API Gateway]
    Gateway --> Auth[🔐 Serwis Auth]
    Gateway --> API[⚙️ Serwis API]
    API --> DB[(💾 Baza danych)]
    API --> Cache[(⚡ Redis)]
    API --> Queue[📬 Kolejka wiadomości]
    Queue --> Worker[⚙️ Pracownik tła]

Kategorie symboli:

• Infrastruktura: ☁️ 🌐 🔌 📡 🗄️
• Compute: ⚙️ ⚡ 🔄 🚀 💨
• Dane: 💾 📦 📊 📈 🗃️
• Komunikacja: 📨 📬 📤 📥 🐰
• Bezpieczeństwo: 🔐 🔑 🛡️ 🚪 👤
• Monitorowanie: 📝 📊 🚨 ⚠️ ✅ ❌

2. Styl wysoki kontrast

Wszystkie diagramy używają dostępnych, wysoko kontrastowych kolorów - szczegóły w SKILL.md.

3. Narzędzia w Pythonie

Wyodrębnianie diagramów

# Lista wszystkich diagramów w pliku
python scripts/extract_mermaid.py document.md --list-only

# Wyodrębnij do osobnych plików .mmd
python scripts/extract_mermaid.py document.md --output-dir diagrams/

# Zweryfikuj wszystkie diagramy
python scripts/extract_mermaid.py document.md --validate

# Zastąp diagramy odwołaniami do obrazów (dla Confluence)
python scripts/extract_mermaid.py document.md --replace-with-images \
  --image-format png --output-markdown output.md

Konwersja do obrazów

# Pojedynczy plik
python scripts/mermaid_to_image.py diagram.mmd output.png

# Niestandardowy motyw i rozmiar
python scripts/mermaid_to_image.py diagram.mmd output.svg \
  --theme dark --background white --width 1200

# Przetwarzanie wsadowe katalogu
python scripts/mermaid_to_image.py diagrams/ output/ \
  --format png --recursive

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

Wymagania

Do generowania diagramów

• System umiejętności Claude Code (automatyczny)
• Przewodniki i szablony (dołączone do umiejętności)

Do walidacji i konwersji obrazów

# Zainstaluj mermaid-cli globalnie
npm install -g @mermaid-js/mermaid-cli

# Sprawdź instalację
mmdc --version

Dla skryptów w Pythonie

• Python 3.7+
• Nie są wymagane dodatkowe pakiety (używa tylko stdlib)

Ścieżka nauki

Nowy w diagramach Mermaid?

1. Zacznij od diagramów aktywności - Przeczytaj references/guides/diagrams/activity-diagrams.md
2. Poznaj symbole Unicode - Przeczytaj references/guides/unicode-symbols/guide.md
3. Spróbuj przykładu - Użyj wzorców z examples/spring-boot/
4. Zweryfikuj swoją pracę - Uruchom python scripts/extract_mermaid.py --validate

Potrzebujesz udokumentować istniejący kod?

1. Zidentyfikuj framework - Spring Boot, FastAPI, React itp.
2. Załaduj przewodnik przykładowy - Przeczytaj examples/{twój-framework}/README.md
3. Dopasuj wzorce - Znajdź podobne wzorce kodu w przykładach
4. Generuj diagramy - Użyj szablonów z przewodników
5. Weryfikuj - Użyj skryptów walidacyjnych

Tworzenie dokumentów projektowych?

1. Wybierz typ szablonu - Architektura, API, Funkcja, Baza danych lub System
2. Załaduj szablon - Przeczytaj z assets/{typ}-design-template.md
3. Wypełnij sekcje - Zastąp placeholder'y rzeczywistą treścią
4. Dodaj diagramy - Załaduj przewodniki po diagramach według potrzeb dla każdej sekcji
5. Użyj symboli - Wzbogać symbolami Unicode w całym dokumencie
6. Zapisz - Umieść w docs/design/ ze znacznikiem czasu

Jak działa system hierarchiczny

Tradycyjne podejście (nieefektywne)

• Ładowanie całej dokumentacji umiejętności (~50KB)
• AI przetwarza wszystkie szablony i przykłady
• Wysokie zużycie tokenów
• Wolny czas odpowiedzi

Podejście hierarchiczne (efektywne)

1. Użytkownik zgłasza żądanie → AI analizuje intencję
2. Aktywuje się drzewo decyzyjne → Określa potrzebne przewodniki
3. Ładuje tylko potrzebne → Odczytywanie konkretnego przewodnika (~2-5KB)
4. Generuje wynik → Używa ukierunkowanych szablonów
5. Efektywne tokenowo → 10x mniej potrzebnego kontekstu

Przykładowy przepływ

Użytkownik: "Utwórz diagram wdrożeniowy dla mojej konfiguracji Docker Compose"

Drzewo decyzyjne:

1. Analiza: "diagram wdrożeniowy" + "Docker Compose"
2. Ustalenie: potrzebny deployment-diagrams.md
3. Załadowanie: references/guides/diagrams/deployment-diagrams.md (2 KB)
4. Znalezienie wzorca: szablon Docker Compose istnieje
5. Generowanie: Używanie szablonu + symboli Unicode
6. Wyjście: Kompletny diagram w <30 sekund

Zużyte tokeny: ~2 000 (vs ~10 000 przy tradycyjnym podejściu)

Status ukończenia

✅ Ukończone:

• Hierarchiczny orkiestrator z drzewem decyzyjnym
• Przewodnik po diagramach aktywności z szablonami
• Przewodnik po diagramach wdrożeniowych (AWS, GCP, K8s, serverless, Docker)
• Przewodnik po symbolach Unicode (100+ symboli)
• Skrypt wyodrębniania Mermaid z walidacją
• Skrypt konwersji Mermaid na obraz
• Przykłady konwersji kodu na diagram dla Spring Boot
• Szablony dokumentów projektowych (5 typów)
• System stylistyki wysokiego kontrastu

🚧 W toku:

• Przykłady dla FastAPI
• Przykłady architektury komponentów React
• Przykłady potoków ETL w Pythonie

📋 Planowane:

• Przewodnik po diagramach architektury
• Przewodnik po diagramach sekwencji
• Główny przewodnik konwersji kodu na diagram
• Przykłady dla Node.js/Express
• Przykłady dla aplikacji webowych w Javie

Wkład

Aby dodać nowy przewodnik typu diagramu:

1. Utwórz przewodnik w references/guides/diagrams/{typ}-diagrams.md
2. Dołącz:
   • Kiedy używać
   • Podstawowa składnia
   • Wspólne wzorce (3-5 szablonów)
   • Przykłady symboli Unicode
   • Najlepsze praktyki
3. Zaktualizuj drzewo decyzyjne w SKILL.md
4. Dodaj przykłady z mapowaniem kodu

Aby dodać nowy przykład językowy:

1. Utwórz katalog w examples/{framework}/
2. Dodaj README.md z:
   • Przeglądem frameworka
   • Diagramem architektury ze struktury
   • Diagramem wdrożeniowym z konfiguracji
   • Diagramem sekwencji z kodu
   • Diagramem aktywności z logiki
3. Zaktualizuj tabelę konwersji kodu na diagram w SKILL.md

Licencja

Część Claude Code Skills - Licencja MIT

Powiązane umiejętności

• confluence - Przesyłanie diagramów do Confluence
• plantuml - Alternatywny format diagramu

Linki

• Repozytorium GitHub
• Wpis na Skilz Marketplace
• Oficjalna dokumentacja Mermaid

Wersja: 2.0.0 Zaktualizowano: 2025-01-13 Utrzymywane przez: SpillwaveSolutions