Architetto Sirena: Competenza in Diagrammi e Documentazione

Mermaid Architetto - Competenza completa per diagrammi e documentazione

Versione 2.0 - Architettura gerarchica con orchestrazione intelligente

Una potente competenza del Codice Claude per creare diagrammi Sirena e documenti di progettazione utilizzando il caricamento di guide su richiesta, la generazione da codice a diagramma e utilità Python.

Installazione

Installazione con un clic tramite Skilz Marketplace

Installa questa competenza istantaneamente dal Mercato Skilz:

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

Installazione manuale

Clona direttamente nella tua directory delle competenze del Codice Claude:

# Vai alla tua directory delle competenze
cd ~/.claude/skills

# Clona il repository
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git

Verifica dell'installazione

Dopo l'installazione, verifica che la competenza sia disponibile:

# Elenca le competenze installate
ls ~/.claude/skills/design-doc-mermaid

# O chiedi al Codice Claude
# "Elenca le mie competenze installate"

Cosa fa questa competenza

Generazione intelligente di diagrammi:

• Diagrammi di attività (flussi di lavoro, processi, logica di business)
• Diagrammi di deployment (infrastruttura cloud, K8s, senza server)
• Diagrammi di architettura (componenti di sistema, microservizi)
• Diagrammi di sequenza (flussi API, interazioni tra servizi)
• Documenti di progettazione completi con diagrammi incorporati

Conversione da codice a diagramma:

• Estrai l'architettura da applicazioni Avvio a molla
• Genera diagrammi di deployment da file di configurazione
• Crea diagrammi di sequenza da chiamate di metodo
• Documenta pipeline ETL e flussi di dati

Gestione dei diagrammi:

• Estrai diagrammi Sirena da file Markdown
• Convalida la sintassi del diagramma con mermaid-cli
• Converti i diagrammi in immagini PNG/SVG
• Elabora in batch intere directory

Avvio rapido

Crea un diagramma di attività

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

La competenza effettuerà:

1. Caricherà references/guides/diagrams/activity-diagrams.md
2. Utilizzerà il modello di pattern di registrazione
3. Aggiungerà simboli Unicode (🔐 per la sicurezza, 📧 per l'email, ✅ per il successo)
4. Applicherà uno stile ad alto contrasto
5. Produrrà un diagramma Sirena completo

Genera da codice

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

La competenza effettuerà:

1. Analizzerà la configurazione (origine dati, cache, sicurezza)
2. Caricherà references/guides/diagrams/deployment-diagrams.md
3. Caricherà examples/spring-boot/README.md
4. Mapperà la configurazione alle risorse cloud
5. Genererà un diagramma di deployment con specifiche delle risorse

Crea documento di progettazione

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

La competenza effettuerà:

1. Caricherà assets/api-design-template.md
2. Caricherà le guide per i diagrammi pertinenti (sequenza, ER, architettura)
3. Genererà un documento completo con diagrammi incorporati
4. Salverà in docs/design/api-contacts-v1-2025-01-13.md

Struttura

Organizzazione gerarchica

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

Caratteristiche principali

1. Simboli semantici Unicode

Ogni diagramma utilizza simboli Unicode significativi:

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]

Categorie di simboli:

• Infrastruttura: ☁️ 🌐 🔌 📡 🗄️
• Calcolo: ⚙️ ⚡ 🔄 🚀 💨
• Dati: 💾 📦 📊 📈 🗃️
• Messaggistica: 📨 📬 📤 📥 🐰
• Sicurezza: 🔐 🔑 🛡️ 🚪 👤
• Monitoraggio: 📝 📊 🚨 ⚠️ ✅ ❌

2. Stile ad alto contrasto

Tutti i diagrammi utilizzano colori accessibili ad alto contrasto - vedi SKILL.md per i dettagli completi.

3. Utilità Python

Estrai diagrammi

# 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

Converti in immagini

# 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

Requisiti

Per la generazione di diagrammi

• Sistema di competenze Codice Claude (automatico)
• Guide e modelli (inclusi in questa competenza)

Per la convalida e la conversione di immagini

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

# Verify installation
mmdc --version

Per gli script Python

• Python 3.7+
• Nessun pacchetto aggiuntivo richiesto (utilizza solo stdlib)

Percorso di apprendimento

Sei nuovo ai diagrammi Sirena?

1. Inizia con i diagrammi di attività - Leggi references/guides/diagrams/activity-diagrams.md
2. Impara i simboli Unicode - Leggi references/guides/unicode-symbols/guide.md
3. Prova un esempio - Usa i modelli da examples/spring-boot/
4. Convalida il tuo lavoro - Esegui python scripts/extract_mermaid.py --validate

Hai bisogno di documentare codice esistente?

1. Identifica il framework - Avvio a molla, API veloce, Reagire, ecc.
2. Carica la guida di esempio - Leggi examples/{your-framework}/README.md
3. Abbina i modelli - Trova modelli di codice simili negli esempi
4. Genera diagrammi - Usa i modelli dalle guide
5. Convalida - Usa gli script di convalida

Creare documenti di progettazione?

1. Scegli il tipo di modello - Architettura, API, Funzionalità, Database o Sistema
2. Carica il modello - Leggi da assets/{type}-design-template.md
3. Compila le sezioni - Sostituisci i segnaposto con contenuti reali
4. Aggiungi diagrammi - Carica le guide per i diagrammi secondo necessità per ogni sezione
5. Usa i simboli - Migliora con simboli Unicode ovunque
6. Salva - Inserisci in docs/design/ con timestamp

Come funziona il sistema gerarchico

Approccio tradizionale (inefficiente)

• Carica l'intera documentazione della competenza (~50KB)
• L'IA elabora tutti i modelli e gli esempi
• Uso elevato di token
• Tempo di risposta lento

Approccio gerarchico (efficiente)

1. L'utente fa una richiesta → L'IA analizza l'intento
2. L'albero decisionale si attiva → Determina le guide necessarie
3. Carica solo ciò che serve → Legge la guida specifica (~2-5KB)
4. Genera l'output → Utilizza modelli mirati
5. Efficiente in token → 10x meno contesto necessario

Flusso di esempio

Utente: "Crea un diagramma di deployment per la mia configurazione Docker Compose"

Albero decisionale:

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

Token utilizzati: ~2.000 (rispetto a ~10.000 con l'approccio tradizionale)

Stato di completamento

✅ Completato:

• Orchestratore dell'albero decisionale gerarchico
• Guida ai diagrammi di attività con modelli
• Guida ai diagrammi di deployment (AWS, GCP, K8s, senza server, Docker)
• Guida ai simboli Unicode (100+ simboli)
• Script per estrarre diagrammi Sirena con convalida
• Script di conversione da Sirena a immagine
• Esempi da codice a diagramma per Avvio a molla
• Modelli di documenti di progettazione (5 tipi)
• Sistema di stile ad alto contrasto

🚧 In corso:

• Esempi API veloce
• Esempi di architettura componenti Reagire
• Esempi di pipeline ETL Python

📋 Pianificato:

• Guida ai diagrammi di architettura
• Guida ai diagrammi di sequenza
• Guida principale da codice a diagramma
• Esempi Node.js/Express
• Esempi di applicazioni web Java

Contribuire

Per aggiungere una nuova guida per un tipo di diagramma:

1. Crea una guida in references/guides/diagrams/{type}-diagrams.md
2. Includi:
   • Quando usarlo
   • Sintassi di base
   • Modelli comuni (3-5 modelli)
   • Esempi di simboli Unicode
   • Buone pratiche
3. Aggiorna l'albero decisionale in SKILL.md
4. Aggiungi esempi con mappature di codice

Per aggiungere un nuovo esempio di linguaggio:

1. Crea una directory in examples/{framework}/
2. Aggiungi README.md con:
   • Panoramica del framework
   • Diagramma di architettura dalla struttura
   • Diagramma di deployment dalla configurazione
   • Diagramma di sequenza dal codice
   • Diagramma di attività dalla logica
3. Aggiorna la tabella da codice a diagramma in SKILL.md

Licenza

Parte di Competenze Codice Claude - Licenza MIT

Competenze correlate

• confluence - Carica diagrammi su Confluence
• plantuml - Formato di diagramma alternativo

Collegamenti

• Repository GitHub
• Elenco Mercato Skilz
• Documentazione ufficiale di Sirena

Versione: 2.0.0 Aggiornato: 2025-01-13 Gestito da: SpillwaveSolutions