# Architetto Sirena: Competenza in Diagrammi e Documentazione > Genera diagrammi Sirena completi e documenti di progettazione con orchestrazione intelligente, conversione da codice a diagramma e utilità Python. Inizia a creare documentazione tecnica dettagliata in pochi secondi. - Canonical: https://nanoskill.ai/it/skills/mermaid-agent-skill - Markdown: https://nanoskill.ai/it/skills/mermaid-agent-skill.md - Author: SpillwaveSolutions - Published: 2026-05-26T01:25:42.765Z - Updated: 2026-07-19T03:48:37.206Z - Language: it - Source type: github - Popularity signal: 66 ## Sources - https://github.com/spillwavesolutions/design-doc-mermaid ## Install ```shell npx skills add https://github.com/spillwavesolutions/design-doc-mermaid ``` ## About La competenza Architetto Sirena consente a sviluppatori, architetti e redattori tecnici di creare e gestire in modo efficiente diagrammi Sirena completi e documenti di progettazione. Sfruttando l'orchestrazione intelligente e il caricamento delle guide su richiesta, questa competenza semplifica la visualizzazione di sistemi complessi, flussi di lavoro e strutture di codice. Aiuta gli utenti a generare diagrammi accurati e visivamente accattivanti, garantendo una comunicazione chiara e una documentazione aggiornata. Questa potente competenza Claude Code offre funzionalità avanzate come la generazione da codice a diagramma, consentendo di estrarre informazioni architetturali direttamente dalle applicazioni Spring Boot o FastAPI. Include anche un ricco insieme di utilità Python per estrarre, convalidare e convertire i diagrammi Sirena in formati immagine, semplificando l'integrazione con i flussi di lavoro di documentazione esistenti e strumenti come Confluence. Il sistema gerarchico garantisce un uso efficiente dei token e tempi di risposta rapidi, offrendo un'esperienza fluida. Che tu abbia bisogno di documentare un'API, visualizzare un'architettura di sistema o illustrare un processo aziendale, Architetto Sirena fornisce gli strumenti e i modelli per portare a termine il lavoro. Con il supporto per vari tipi di diagrammi, simboli semantici Unicode e stili ad alto contrasto, i tuoi diagrammi saranno sia informativi che accessibili. La competenza offre anche un percorso di apprendimento strutturato ed esempi per aiutare gli utenti a diventare rapidamente esperti nella creazione di documentazione tecnica dettagliata. ## Key features - **Generazione intelligente di diagrammi**: Crea vari diagrammi Mermaid, inclusi diagrammi di attività, distribuzione, architettura e sequenza, per flussi di lavoro, infrastrutture, componenti di sistema e flussi API. - **Conversione da codice a diagramma**: Genera automaticamente diagrammi da basi di codice esistenti (ad esempio, Spring Boot, FastAPI) o file di configurazione per visualizzare architettura, distribuzioni e flussi di sequenza. - **Creazione completa di documenti di progettazione**: Produce documenti di progettazione completi con diagrammi Mermaid incorporati utilizzando modelli predefiniti per architettura, API, funzionalità, database e progettazione di sistema. - **Simboli semantici Unicode e stile ad alto contrasto**: Migliora la chiarezza e l'accessibilità dei diagrammi con oltre 100 simboli Unicode significativi e schemi di colori ad alto contrasto per una migliore leggibilità. - **Utilità Python per la gestione dei diagrammi**: Utilizza script Python per estrarre, convalidare e convertire diagrammi Mermaid in immagini PNG/SVG, supportando l'elaborazione batch e l'integrazione con strumenti come Confluence. ## Use cases - **Visualizzare l'architettura software**: Sviluppatori e architetti possono generare diagrammi di architettura e distribuzione da codice o file di configurazione per comprendere i componenti di sistema e l'infrastruttura. - **Documentare flussi API e flussi di lavoro**: Redattori tecnici e ingegneri possono creare diagrammi di sequenza e attività dettagliati per illustrare interazioni API, processi aziendali e percorsi utente. - **Automatizzare la creazione di documenti di progettazione**: I team possono generare rapidamente documenti di progettazione strutturati per vari scopi (API, sistema, funzionalità) con diagrammi Mermaid incorporati automaticamente, risparmiando tempo e garantendo coerenza. - **Mantenere documentazione tecnica aggiornata**: Assicurarsi che la documentazione rimanga aggiornata generando diagrammi direttamente dal codice o dalla configurazione e convertendoli facilmente in formati immagine per la condivisione e la collaborazione. ## Result preview Guarda i diagrammi Sirena sul sistema per una piattaforma di consegna cibo generati da questa Competenza Agente. ![mermaid-architect-demo1](https://file.nanoskill.ai/mermaid-architect-demo1.jpg) ![mermaid-architect-demo-2](https://file.nanoskill.ai/mermaid-architect-demo-2.jpg) ![mermaid-architect-demo-3](https://file.nanoskill.ai/mermaid-architect-demo-3.jpg) ## Result walkthrough ### Passo 1：Installa Aggiungi la competenza al tuo agente. ![mermaid-architect-step-1](https://file.nanoskill.ai/mermaid-architect-step-1.jpg) ### Passo 2：Descrivi un processo Inserisci un flusso di lavoro, un sistema o una sequenza che desideri visualizzare. ![mermaid-architect-step-2](https://file.nanoskill.ai/mermaid-architect-step-2.jpg) ### Passo 3：Rivedi il Risultato Ottieni diagrammi Sirena generati in base alla descrizione del tuo processo. ![mermaid-architect-step-3](https://file.nanoskill.ai/mermaid-architect-step-3.jpg) ## Skill definition # 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](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/): ```bash skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid ``` ### Installazione manuale Clona direttamente nella tua directory delle competenze del Codice Claude: ```bash # 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: ```bash # 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: ```mermaid 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 ```bash # 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 ```bash # 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 ```bash # 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](https://github.com/SpillwaveSolutions/design-doc-mermaid) - [Elenco Mercato Skilz](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/) - [Documentazione ufficiale di Sirena](https://mermaid.js.org/) --- **Versione:** 2.0.0 **Aggiornato:** 2025-01-13 **Gestito da:** SpillwaveSolutions ## FAQ ### Quali tipi di diagrammi Mermaid può generare questa competenza? Questa competenza può generare diagrammi di attività, diagrammi di distribuzione, diagrammi di architettura e diagrammi di sequenza. Supporta la visualizzazione di flussi di lavoro, infrastrutture cloud, componenti di sistema e interazioni API. ### Come funziona la conversione da codice a diagramma? La competenza analizza il codice o i file di configurazione (ad esempio, application.yml di Spring Boot) e utilizza modelli e guide predefiniti per generare automaticamente i corrispondenti diagrammi Mermaid, come diagrammi di distribuzione o di sequenza. ### Posso creare documenti di progettazione completi con questa competenza? Sì, la competenza include modelli per vari documenti di progettazione (architettura, API, funzionalità, database, sistema). Può generare documenti completi con diagrammi Mermaid incorporati in base all'input fornito e al modello selezionato. ### Quali sono i vantaggi del sistema gerarchico per la generazione di diagrammi Mermaid? Il sistema gerarchico analizza in modo efficiente l'intento e carica solo le guide e i modelli necessari (tipicamente 2-5 KB) invece dell'intera documentazione della competenza. Ciò riduce significativamente l'uso di token e accelera i tempi di risposta. ### Sono incluse utilità Python con questa competenza? Sì, la competenza fornisce script Python per estrarre diagrammi Mermaid da file Markdown, convalidarne la sintassi e convertirli in formati immagine PNG o SVG. Queste utilità supportano anche l'elaborazione batch. ### Quali sono i requisiti per utilizzare le funzionalità di convalida e conversione delle immagini? Per la convalida dei diagrammi e la conversione delle immagini, è necessario avere \`mermaid-cli\` installato globalmente tramite npm (\`npm install -g @mermaid-js/mermaid-cli\`). Gli script Python richiedono Python 3.7+.