Zeemeermin Architect: Diagram & Documentatievaardigheid

Mermaid Architect - Uitgebreide diagram- & documentatievaardigheid

Versie 2.0 - Hiërarchische architectuur met intelligente orchestratie

Een krachtige Claude Code-vaardigheid voor het maken van Mermaid-diagrammen en ontwerpdocumenten met behulp van on-demand gidslading, code-naar-diagramgeneratie en Python-hulpprogramma's.

Installatie

Eén-klik installatie via de Skilz Marketplace

Installeer deze vaardigheid direct vanuit de Skilz Marketplace:

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

Handmatige installatie

Kloon direct naar je Claude Code-vaardighedenmap:

# Navigeer naar je vaardighedenmap
cd ~/.claude/skills

# Kloon de repository
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git

Verifieer de installatie

Controleer na de installatie of de vaardigheid beschikbaar is:

# Lijst geïnstalleerde vaardigheden
ls ~/.claude/skills/design-doc-mermaid

# Of vraag aan Claude Code
# "List mijn geïnstalleerde vaardigheden"

Wat deze vaardigheid doet

Intelligente diagramgeneratie:

• Activiteitendiagrammen (workflows, processen, bedrijfslogica)
• Implementatiediagrammen (cloudinfrastructuur, K8s, serverless)
• Architectuurdiagrammen (systeemcomponenten, microservices)
• Sequentiediagrammen (API-stromen, service-interacties)
• Complete ontwerpdocumenten met ingesloten diagrammen

Code-naar-diagramconversie:

• Extraheer architectuur uit Spring Boot-applicaties
• Genereer implementatiediagrammen vanuit configuratiebestanden
• Maak sequentiediagrammen vanuit methodeaanroepen
• Documenteer ETL-pipelines en gegevensstromen

Diagrambeheer:

• Extraheer Mermaid-diagrammen uit Markdown-bestanden
• Valideer diagramsyntaxis met mermaid-cli
• Converteer diagrammen naar PNG-/SVG-afbeeldingen
• Batchverwerking van volledige mappen

Snelle start

Maak een activiteitendiagram

Gebruiker: "Maak een activiteitendiagram voor gebruikersregistratie met e-mailverificatie"

De vaardigheid zal:

1. references/guides/diagrams/activity-diagrams.md laden
2. De registratiepatroonsjabloon gebruiken
3. Unicode-symbolen toevoegen (🔐 voor beveiliging, 📧 voor e-mail, ✅ voor succes)
4. Styling met hoog contrast toepassen
5. Compleet Mermaid-diagram uitvoeren

Genereer vanuit code

Gebruiker: "Hier is mijn Spring Boot application.yml - genereer een implementatiediagram"

De vaardigheid zal:

1. Configuratie analyseren (datasource, cache, beveiliging)
2. references/guides/diagrams/deployment-diagrams.md laden
3. examples/spring-boot/README.md laden
4. Configuratie toewijzen aan cloudbronnen
5. Implementatiediagram genereren met resourcespecificaties

Maak ontwerpdocument

Gebruiker: "Maak een API-ontwerpdocument voor de contacten-API"

De vaardigheid zal:

1. assets/api-design-template.md laden
2. Relevante diagramhulpgidsen laden (sequentie, ER, architectuur)
3. Compleet document genereren met ingesloten diagrammen
4. Opslaan in docs/design/api-contacts-v1-2025-01-13.md

Structuur

Hiërarchische organisatie

mermaid-architect/
├── SKILL.md                          # Hoofdorchestrator met beslisboom
├── README.md                         # Dit bestand
├── CLAUDE.md                         # Claude Code-instructies
│
├── references/                       # Referentiemateriaal
│   ├── mermaid-diagram-guide.md     # Oude algemene gids
│   └── guides/                       # Gespecialiseerde gidsen (laden op aanvraag)
│       ├── diagrams/
│       │   ├── activity-diagrams.md      # ✅ Compleet
│       │   ├── deployment-diagrams.md    # ✅ Compleet
│       │   ├── architecture-diagrams.md  # ✅ Compleet
│       │   └── sequence-diagrams.md      # ✅ Compleet
│       ├── code-to-diagram/
│       │   └── README.md                 # ✅ Compleet (hoofdgids)
│       ├── unicode-symbols/
│       │   └── guide.md                  # ✅ Compleet (100+ symbolen)
│       └── troubleshooting.md        # ✅ Compleet (28 veelvoorkomende fouten)
│
├── scripts/                          # Python-hulpprogramma's
│   ├── extract_mermaid.py           # ✅ Diagrammen extraheren en valideren
│   └── mermaid_to_image.py          # ✅ Converteren naar PNG/SVG
│
├── examples/                         # Taalspecifieke patronen
│   ├── spring-boot/                 # ✅ Compleet
│   ├── fastapi/                     # ✅ Compleet
│   ├── react/                       # ✅ Compleet
│   ├── python-etl/                  # ✅ Compleet
│   ├── node-webapp/                 # ✅ Compleet
│   └── java-webapp/                 # ✅ Compleet
│
└── assets/                           # Sjablonen voor ontwerpdocumenten
    ├── architecture-design-template.md
    ├── api-design-template.md
    ├── feature-design-template.md
    ├── database-design-template.md
    └── system-design-template.md

Belangrijkste kenmerken

1. Unicode semantische symbolen

Elk diagram gebruikt betekenisvolle Unicode-symbolen:

graph TB
    Gebruiker[👤 Klant] --> Gateway[🌐 API Gateway]
    Gateway --> Auth[🔐 Auth-service]
    Gateway --> API[⚙️ API-service]
    API --> DB[(💾 Database)]
    API --> Cache[(⚡ Redis)]
    API --> Queue[📬 Berichtenwachtrij]
    Queue --> Worker[⚙️ Achtergrondwerker]

Symboolcategorieën:

• Infrastructuur: ☁️ 🌐 🔌 📡 🗄️
• Compute: ⚙️ ⚡ 🔄 🚀 💨
• Gegevens: 💾 📦 📊 📈 🗃️
• Berichten: 📨 📬 📤 📥 🐰
• Beveiliging: 🔐 🔑 🛡️ 🚪 👤
• Monitoring: 📝 📊 🚨 ⚠️ ✅ ❌

2. Styling met hoog contrast

Alle diagrammen gebruiken toegankelijke kleuren met hoog contrast - zie SKILL.md voor volledige details.

3. Python-hulpprogramma's

Diagrammen extraheren

# Lijst alle diagrammen in een bestand
python scripts/extract_mermaid.py document.md --list-only

# Extraheer naar afzonderlijke .mmd-bestanden
python scripts/extract_mermaid.py document.md --output-dir diagrams/

# Valideer alle diagrammen
python scripts/extract_mermaid.py document.md --validate

# Vervang diagrammen door afbeeldingsverwijzingen (voor Confluence)
python scripts/extract_mermaid.py document.md --replace-with-images \
  --image-format png --output-markdown output.md

Naar afbeeldingen converteren

# Eén bestand
python scripts/mermaid_to_image.py diagram.mmd output.png

# Aangepast thema en grootte
python scripts/mermaid_to_image.py diagram.mmd output.svg \
  --theme dark --background white --width 1200

# Batchconversie van map
python scripts/mermaid_to_image.py diagrams/ output/ \
  --format png --recursive

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

Vereisten

Voor diagramgeneratie

• Claude Code-vaardighedensysteem (automatisch)
• Gidsen en sjablonen (inbegrepen in deze vaardigheid)

Voor validatie & afbeeldingsconversie

# Installeer mermaid-cli globaal
npm install -g @mermaid-js/mermaid-cli

# Verifieer de installatie
mmdc --version

Voor Python-scripts

• Python 3.7+
• Geen extra pakketten vereist (gebruikt alleen stdlib)

Leerpad

Nieuw met Mermaid-diagrammen?

1. Begin met activiteitendiagrammen - Lees references/guides/diagrams/activity-diagrams.md
2. Leer Unicode-symbolen - Lees references/guides/unicode-symbols/guide.md
3. Probeer een voorbeeld - Gebruik patronen uit examples/spring-boot/
4. Valideer je werk - Voer python scripts/extract_mermaid.py --validate uit

Bestaande code documenteren?

1. Identificeer framework - Spring Boot, FastAPI, React, enz.
2. Laad voorbeeldgids - Lees examples/{your-framework}/README.md
3. Match patronen - Vind vergelijkbare codepatronen in voorbeelden
4. Genereer diagrammen - Gebruik sjablonen uit gidsen
5. Valideer - Gebruik validatiescripts

Ontwerpdocumenten maken?

1. Kies sjabloontype - Architectuur, API, Feature, Database of Systeem
2. Laad sjabloon - Lees uit assets/{type}-design-template.md
3. Vul secties in - Vervang placeholders door daadwerkelijke inhoud
4. Voeg diagrammen toe - Laad diagramgidsen indien nodig voor elke sectie
5. Gebruik symbolen - Verbeter met Unicode-symbolen door het hele document
6. Opslaan - Plaats in docs/design/ met timestamp

Hoe het hiërarchische systeem werkt

Traditionele aanpak (inefficiënt)

• Volledige vaardigheidsdocumentatie laden (~50KB)
• AI verwerkt alle sjablonen en voorbeelden
• Hoog tokenverbruik
• Langzame responstijd

Hiërarchische aanpak (efficiënt)

1. Gebruiker doet verzoek → AI analyseert intentie
2. Beslisboom wordt actief → Bepaalt benodigde gidsen
3. Laad alleen wat nodig is → Leest specifieke gids (~2-5KB)
4. Genereer uitvoer → Gebruikt doelgerichte sjablonen
5. Token-efficiënt → 10x minder context nodig

Voorbeeldstroom

Gebruiker: "Maak een implementatiediagram voor mijn Docker Compose-setup"

Beslisboom:

1. Analyseer: "implementatiediagram" + "Docker Compose"
2. Bepaal: deployment-diagrams.md nodig
3. Laad: references/guides/diagrams/deployment-diagrams.md (2KB)
4. Vind patroon: Docker Compose-sjabloon bestaat
5. Genereer: Met sjabloon + Unicode-symbolen
6. Uitvoer: Compleet diagram in <30 seconden

Gebruikte tokens: ~2.000 (vs ~10.000 met traditionele aanpak)

Voltooiingsstatus

✅ Voltooid:

• Hiërarchische beslisboom-orchestrator
• Activiteitendiagramgids met sjablonen
• Implementatiediagramgids (AWS, GCP, K8s, serverless, Docker)
• Unicode-symbolengids (100+ symbolen)
• Mermaid-extractiescript met validatie
• Script voor Mermaid-naar-afbeelding conversie
• Spring Boot code-naar-diagram voorbeelden
• Sjablonen voor ontwerpdocumenten (5 types)
• Stylingsysteem met hoog contrast

🚧 In uitvoering:

• FastAPI-voorbeelden
• React-componentarchitectuurvoorbeelden
• Python ETL-pipelinevoorbeelden

📋 Gepland:

• Architectuurdiagramgids
• Sequentiediagramgids
• Code-naar-diagram hoofdgids
• Node.js/Express-voorbeelden
• Java-webapp-voorbeelden

Bijdragen

Om een nieuw type diagramgids toe te voegen:

1. Maak een gids in references/guides/diagrams/{type}-diagrams.md
2. Voeg toe:
   • Wanneer te gebruiken
   • Basissyntax
   • Veelvoorkomende patronen (3-5 sjablonen)
   • Unicode-symboolvoorbeelden
   • Best practices
3. Update de beslisboom in SKILL.md
4. Voeg voorbeelden toe met codetoewijzingen

Om een nieuw taalspecifiek voorbeeld toe te voegen:

1. Maak een map in examples/{framework}/
2. Voeg README.md toe met:
   • Frameworkoverzicht
   • Architectuurdiagram vanuit structuur
   • Implementatiediagram vanuit configuratie
   • Sequentiediagram vanuit code
   • Activiteitendiagram vanuit logica
3. Update de code-naar-diagramtabel in SKILL.md

Licentie

Onderdeel van Claude Code Skills - MIT-licentie

Gerelateerde vaardigheden

• confluence - Upload diagrammen naar Confluence
• plantuml - Alternatief diagramformaat

Links

• GitHub Repository
• Skilz Marketplace-vermelding
• Officiële Mermaid-documentatie

Versie: 2.0.0 Bijgewerkt: 2025-01-13 Onderhouden door: SpillwaveSolutions