Meerjungfrau-Architekt: Diagramm- & Dokumentationsfähigkeit

Mermaid Architect - Umfassende Diagramm- & Dokumentationsfähigkeit

Version 2.0 - Hierarchische Architektur mit intelligenter Orchestrierung

Eine leistungsstarke Claude-Code-Fähigkeit zur Erstellung von Mermaid-Diagrammen und Designdokumenten mit bedarfsgesteuertem Laden von Leitfäden, Code-zu-Diagramm-Generierung und Python-Dienstprogrammen.

Installation

Ein-Klick-Installation über den Skilz-Marktplatz

Installieren Sie diese Fähigkeit sofort vom Skilz-Marktplatz:

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

Manuelle Installation

Klonen Sie direkt in Ihr Claude-Code-Fähigkeiten-Verzeichnis:

# Navigieren Sie zu Ihrem Fähigkeiten-Verzeichnis
cd ~/.claude/skills

# Repository klonen
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git

Installation überprüfen

Überprüfen Sie nach der Installation, ob die Fähigkeit verfügbar ist:

# Installierte Fähigkeiten auflisten
ls ~/.claude/skills/design-doc-mermaid

# Oder fragen Sie Claude Code
# „Liste meine installierten Fähigkeiten auf“

Was diese Fähigkeit macht

Intelligente Diagrammgenerierung:

• Aktivitätsdiagramme (Arbeitsabläufe, Prozesse, Geschäftslogik)
• Bereitstellungsdiagramme (Cloud-Infrastruktur, K8s, serverlos)
• Architekturdiagramme (Systemkomponenten, Microservices)
• Sequenzdiagramme (API-Abläufe, Dienstinteraktionen)
• Vollständige Designdokumente mit eingebetteten Diagrammen

Code-zu-Diagramm-Konvertierung:

• Architektur aus Spring-Boot-Anwendungen extrahieren
• Bereitstellungsdiagramme aus Konfigurationsdateien generieren
• Sequenzdiagramme aus Methodenaufrufen erstellen
• ETL-Pipelines und Datenflüsse dokumentieren

Diagrammverwaltung:

• Mermaid-Diagramme aus Markdown-Dateien extrahieren
• Diagrammsyntax mit mermaid-cli validieren
• Diagramme in PNG-/SVG-Bilder konvertieren
• Gesamte Verzeichnisse stapelweise verarbeiten

Schnellstart

Ein Aktivitätsdiagramm erstellen

Benutzer: „Erstelle ein Aktivitätsdiagramm für die Benutzerregistrierung mit E-Mail-Verifizierung“

Die Fähigkeit wird:

1. references/guides/diagrams/activity-diagrams.md laden
2. Die Registrierungsmustervorlage verwenden
3. Unicode-Symbole hinzufügen (🔐 für Sicherheit, 📧 für E-Mail, ✅ für Erfolg)
4. Styling mit hohem Kontrast anwenden
5. Vollständiges Mermaid-Diagramm ausgeben

Aus Code generieren

Benutzer: „Hier ist meine Spring-Boot-Anwendung.yml – generiere ein Bereitstellungsdiagramm“

Die Fähigkeit wird:

1. Konfiguration analysieren (Datenquelle, Cache, Sicherheit)
2. references/guides/diagrams/deployment-diagrams.md laden
3. examples/spring-boot/README.md laden
4. Konfiguration auf Cloud-Ressourcen abbilden
5. Bereitstellungsdiagramm mit Ressourcenspezifikationen generieren

Designdokument erstellen

Benutzer: „Erstelle ein API-Designdokument für die Kontakte-API“

Die Fähigkeit wird:

1. assets/api-design-template.md laden
2. Relevante Diagrammleitfäden laden (Sequenz, ER, Architektur)
3. Vollständiges Dokument mit eingebetteten Diagrammen generieren
4. In docs/design/api-contacts-v1-2025-01-13.md speichern

Struktur

Hierarchische Organisation

mermaid-architect/
├── SKILL.md                          # Hauptorchestrator mit Entscheidungsbaum
├── README.md                         # Diese Datei
├── CLAUDE.md                         # Claude-Code-Anweisungen
│
├── references/                       # Referenzmaterialien
│   ├── mermaid-diagram-guide.md      # Legacy-allgemeiner Leitfaden
│   └── guides/                       # Spezialisierte Leitfäden (bei Bedarf geladen)
│       ├── diagrams/
│       │   ├── activity-diagrams.md      # ✅ Vollständig
│       │   ├── deployment-diagrams.md    # ✅ Vollständig
│       │   ├── architecture-diagrams.md  # ✅ Vollständig
│       │   └── sequence-diagrams.md      # ✅ Vollständig
│       ├── code-to-diagram/
│       │   └── README.md                 # ✅ Vollständig (Hauptleitfaden)
│       ├── unicode-symbols/
│       │   └── guide.md                  # ✅ Vollständig (100+ Symbole)
│       └── troubleshooting.md        # ✅ Vollständig (28 häufige Fehler)
│
├── scripts/                          # Python-Dienstprogramme
│   ├── extract_mermaid.py           # ✅ Diagramme extrahieren & validieren
│   └── mermaid_to_image.py          # ✅ In PNG/SVG konvertieren
│
├── examples/                         # Sprachspezifische Muster
│   ├── spring-boot/                 # ✅ Vollständig
│   ├── fastapi/                     # ✅ Vollständig
│   ├── react/                       # ✅ Vollständig
│   ├── python-etl/                  # ✅ Vollständig
│   ├── node-webapp/                 # ✅ Vollständig
│   └── java-webapp/                 # ✅ Vollständig
│
└── assets/                           # Designdokumentvorlagen
    ├── architecture-design-template.md
    ├── api-design-template.md
    ├── feature-design-template.md
    ├── database-design-template.md
    └── system-design-template.md

Hauptmerkmale

1. Unicode-semantische Symbole

Jedes Diagramm verwendet aussagekräftige Unicode-Symbole:

graph TB
    User[👤 Client] --> Gateway[🌐 API-Gateway]
    Gateway --> Auth[🔐 Auth-Dienst]
    Gateway --> API[⚙️ API-Dienst]
    API --> DB[(💾 Datenbank)]
    API --> Cache[(⚡ Redis)]
    API --> Queue[📬 Nachrichtenwarteschlange]
    Queue --> Worker[⚙️ Hintergrundarbeiter]

Symbolkategorien:

• Infrastruktur: ☁️ 🌐 🔌 📡 🗄️
• Rechnen: ⚙️ ⚡ 🔄 🚀 💨
• Daten: 💾 📦 📊 📈 🗃️
• Nachrichtenübermittlung: 📨 📬 📤 📥 🐰
• Sicherheit: 🔐 🔑 🛡️ 🚪 👤
• Überwachung: 📝 📊 🚨 ⚠️ ✅ ❌

2. Styling mit hohem Kontrast

Alle Diagramme verwenden zugängliche, kontrastreiche Farben – siehe SKILL.md für vollständige Details.

3. Python-Dienstprogramme

Diagramme extrahieren

# Alle Diagramme in einer Datei auflisten
python scripts/extract_mermaid.py document.md --list-only

# In separate .mmd-Dateien extrahieren
python scripts/extract_mermaid.py document.md --output-dir diagrams/

# Alle Diagramme validieren
python scripts/extract_mermaid.py document.md --validate

# Diagramme durch Bildreferenzen ersetzen (für Confluence)
python scripts/extract_mermaid.py document.md --replace-with-images \
  --image-format png --output-markdown output.md

In Bilder konvertieren

# Einzelne Datei
python scripts/mermaid_to_image.py diagram.mmd output.png

# Benutzerdefiniertes Thema und Größe
python scripts/mermaid_to_image.py diagram.mmd output.svg \
  --theme dark --background white --width 1200

# Verzeichnis stapelweise konvertieren
python scripts/mermaid_to_image.py diagrams/ output/ \
  --format png --recursive

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

Anforderungen

Für die Diagrammgenerierung

• Claude-Code-Fähigkeitssystem (automatisch)
• Leitfäden und Vorlagen (in dieser Fähigkeit enthalten)

Für Validierung & Bildkonvertierung

# mermaid-cli global installieren
npm install -g @mermaid-js/mermaid-cli

# Installation überprüfen
mmdc --version

Für Python-Skripte

• Python 3.7+
• Keine zusätzlichen Pakete erforderlich (verwendet nur die Standardbibliothek)

Lernpfad

Neu bei Mermaid-Diagrammen?

1. Mit Aktivitätsdiagrammen beginnen – Lesen Sie references/guides/diagrams/activity-diagrams.md
2. Unicode-Symbole lernen – Lesen Sie references/guides/unicode-symbols/guide.md
3. Ein Beispiel ausprobieren – Verwenden Sie Muster aus examples/spring-boot/
4. Ihre Arbeit validieren – Führen Sie python scripts/extract_mermaid.py --validate aus

Müssen Sie vorhandenen Code dokumentieren?

1. Framework identifizieren – Spring Boot, FastAPI, React usw.
2. Beispiel-Leitfaden laden – Lesen Sie examples/{your-framework}/README.md
3. Muster abgleichen – Ähnliche Code-Muster in den Beispielen finden
4. Diagramme generieren – Vorlagen aus Leitfäden verwenden
5. Validieren – Validierungsskripte verwenden

Erstellen Sie Designdokumente?

1. Vorlagentyp wählen – Architektur, API, Feature, Datenbank oder System
2. Vorlage laden – Lesen Sie aus assets/{type}-design-template.md
3. Abschnitte ausfüllen – Platzhalter durch tatsächlichen Inhalt ersetzen
4. Diagramme hinzufügen – Je nach Bedarf Diagrammleitfäden für jeden Abschnitt laden
5. Symbole verwenden – Durchgehend mit Unicode-Symbolen anreichern
6. Speichern – In docs/design/ mit Zeitstempel ablegen

Wie das hierarchische System funktioniert

Traditioneller Ansatz (ineffizient)

• Gesamte Fähigkeitendokumentation laden (~50 KB)
• KI verarbeitet alle Vorlagen und Beispiele
• Hohe Token-Nutzung
• Langsame Antwortzeit

Hierarchischer Ansatz (effizient)

1. Benutzer stellt Anfrage → KI analysiert Absicht
2. Entscheidungsbaum aktiviert → Bestimmt benötigte Leitfäden
3. Nur das Nötige laden → Liest spezifischen Leitfaden (~2-5 KB)
4. Ausgabe generieren → Verwendet zielgerichtete Vorlagen
5. Token-effizient → 10x weniger Kontext benötigt

Beispielablauf

Benutzer: „Erstelle ein Bereitstellungsdiagramm für mein Docker-Compose-Setup"

Entscheidungsbaum:

1. Analysieren: „Bereitstellungsdiagramm" + „Docker Compose"
2. Bestimmen: deployment-diagrams.md erforderlich
3. Laden: references/guides/diagrams/deployment-diagrams.md (2 KB)
4. Muster finden: Docker-Compose-Vorlage vorhanden
5. Generieren: Mithilfe von Vorlage + Unicode-Symbolen
6. Ausgabe: Vollständiges Diagramm in <30 Sekunden

Verwendete Token: ~2.000 (im Vergleich zu ~10.000 mit traditionellem Ansatz)

Fertigstellungsstatus

✅ Vollständig:

• Hierarchischer Entscheidungsbaum-Orchestrator
• Aktivitätsdiagramm-Leitfaden mit Vorlagen
• Bereitstellungsdiagramm-Leitfaden (AWS, GCP, K8s, serverlos, Docker)
• Unicode-Symbole-Leitfaden (100+ Symbole)
• Mermaid-Extraktionsskript mit Validierung
• Mermaid-zu-Bild-Konvertierungsskript
• Spring-Boot-Code-zu-Diagramm-Beispiele
• Designdokumentvorlagen (5 Typen)
• Styling-System mit hohem Kontrast

🚧 In Arbeit:

• FastAPI-Beispiele
• React-Komponentenarchitektur-Beispiele
• Python-ETL-Pipeline-Beispiele

📋 Geplant:

• Architekturdiagramme-Leitfaden
• Sequenzdiagramme-Leitfaden
• Code-zu-Diagramm-Hauptleitfaden
• Node.js/Express-Beispiele
• Java-Web-App-Beispiele

Mitwirken

Um einen neuen Diagrammtyp-Leitfaden hinzuzufügen:

1. Erstellen Sie einen Leitfaden in references/guides/diagrams/{type}-diagrams.md
2. Enthalten Sie:
   • Wann zu verwenden
   • Grundlegende Syntax
   • Häufige Muster (3-5 Vorlagen)
   • Unicode-Symbol-Beispiele
   • Bewährte Verfahren
3. Aktualisieren Sie den Entscheidungsbaum in SKILL.md
4. Fügen Sie Beispiele mit Code-Zuordnungen hinzu

Um ein neues Sprachbeispiel hinzuzufügen:

1. Erstellen Sie ein Verzeichnis in examples/{framework}/
2. Fügen Sie README.md hinzu mit:
   • Framework-Übersicht
   • Architekturdiagramm aus der Struktur
   • Bereitstellungsdiagramm aus der Konfiguration
   • Sequenzdiagramm aus Code
   • Aktivitätsdiagramm aus Logik
3. Aktualisieren Sie die Code-zu-Diagramm-Tabelle in SKILL.md

Lizenz

Teil von Claude Code Skills - MIT-Lizenz

Verwandte Fähigkeiten

• confluence – Diagramme in Confluence hochladen
• plantuml – Alternatives Diagrammformat

Links

• GitHub-Repository
• Skilz-Marktplatz-Eintrag
• Mermaid Offizielle Dokumentation

Version: 2.0.0 Aktualisiert: 2025-01-13 Wartung durch: SpillwaveSolutions