FlowBoardFlowBoard

Mermaid slop: come rivedere e correggere i diagrammi generati dall'IA prima di pubblicarli

Team di FlowBoardRedatto con l'assistenza dell'IA15 min di lettura

In sintesi:

  • "Mermaid slop" è il nome che si è diffuso nel 2026 per i diagrammi generati da IA che sono validi in sintassi ma illeggibili o direttamente falsi; il termine è nato dal progetto Diagram Design, che si presentava con il motto "no Figma, no generic rounded boxes, no Mermaid-slop" e che aveva già superato le 11.000 stelle su GitHub nell'agosto del 2026 (explainX, 16-08-2026).
  • Il problema è cresciuto con la distribuzione: VS Code 1.121 (20-05-2026) rende Mermaid nativamente nell'anteprima di Markdown, senza estensione, e gli assistenti lo generano per default (Visual Studio Code).
  • Un modello ottimizza validità grammaticale, non correzione del sistema: il .mmd viene analizzato, ma duplica nodi, lascia il ramo "no" di una decisione o inverte la direzione del dato.
  • Controllare un diagramma leggendo linee di --> non funziona: i difetti che contano sono topologici e si vedono solo disegnati.
  • Il ciclo che funziona: importare il .mmd su una tela, riordinare per strati, annotare il dubbio con un link al codice o al ticket che lo dimostra, correggere a mano e ri-esportare affinché la versione corretta sia quella che entra nel repository.

Dalla metà del 2026, la domanda nei team di ingegneria non è più come generare un diagramma, ma chi ne è responsabile. Gli agenti scrivono Mermaid al volo, GitHub e VS Code lo dipingono senza configurazione e il risultato entra nel README con la stessa naturalezza con cui entra un blocco di codice. Ciò che manca è il livello di audit. Questo articolo esplora i difetti tipici, il motivo tecnico per cui appaiono e un ciclo di revisione riproducibile che si chiude su una tela visiva —nel nostro caso, FlowBoard, la lavagna infinita per diagrammi di AIsToHire, che importa e ri-esporta Mermaid— affinché il diagramma pubblicato sia quello corretto e non il primo che ha generato il modello.

Diagramma generato da IA illeggibile su uno schermo di fronte allo stesso diagramma riordinato per strati su una tela visiva
Diagramma generato da IA illeggibile su uno schermo di fronte allo stesso diagramma riordinato per strati su una tela visiva

Cos'è esattamente il "Mermaid slop"?

Mermaid slop è un diagramma generato da IA che compila senza errori eppure non serve: scatole arrotondate identiche per concetti diversi, frecce senza etichetta o con etichette vaghe, colori di default che non dicono nulla e una generazione riflessiva —viene disegnato perché richiesto, non perché necessario—. La definizione è stabilita dalla revisione di explainX sul termine (16-08-2026), che lo rintraccia fino al progetto Diagram Design di Cathryn Lavery.

Il punto importante è che ci sono due livelli di "slop" e spesso si confondono:

LivelloCosa fallisceSi rilevaCosto per correggerlo
EsteticoForme generiche, palette di default, tutto ugualeA colpo d'occhioBasso: tema, forme, raggruppamento
SemanticoIl diagramma descrive un sistema che non esisteSolo confrontando con il codice realeAlto: bisogna riaprire il repository

La conversazione pubblica del 2026 si è concentrata quasi interamente sul primo. Gli strumenti che sono emersi —dalle skills di diagrammazione editoriale ai generatori che producono elementi nativi di Excalidraw invece di testo Mermaid— colpiscono soprattutto l'aspetto. Il secondo livello, quello che fa sì che un diagramma mentisca sulla tua architettura, rimane lavoro umano.

Perché un LLM produce Mermaid perfetto in sintassi e povero in semantica?

Perché sono due obiettivi distinti e solo uno ha segnale di addestramento abbondante. La grammatica di Mermaid è chiusa, piccola ed è massivamente rappresentata su GitHub: un modello la riproduce quasi senza errori. La correzione del diagramma, invece, dipende da un sistema concreto che il modello normalmente non ha letto interamente, così riempie i vuoti con la forma più frequente di un diagramma di architettura, non con la tua.

A questo si aggiungono tre effetti pratici:

  • Il prompt è l'unica fonte. Se descrivi il sistema in tre frasi, l'agente restituisce un diagramma con la granularità di tre frasi e lo adorna fino a farlo sembrare completo. Come riassume la stessa Mermaid parlando di vibe diagramming, "un diagramma generato a partire da un prompt vago rifletterà la vaghezza del prompt" (Mermaid, 24-03-2026).
  • Non esiste un compilatore semantico. Un test rosso ti avvisa; un diagramma errato si rende ugualmente bello quanto uno corretto. Non esiste l'equivalente di tsc per "questo servizio non esiste".
  • Il layout lo decide il motore, non l'autore. Mermaid colloca i nodi con il suo algoritmo e non ti offre un modo comodo per correggere la disposizione dopo il rendering. Se la gerarchia reale non corrisponde a ciò che il layout automatico disegna, perdi la discussione con lo strumento.

E il contesto del settore dice che la verifica non è opzionale. La sondaggio per sviluppatori 2026 di Stack Overflow (pubblicata il 06-10-2026, più di 30.000 risposte in 169 paesi) ha trovato che quasi la metà si fida dell'output dell'IA solo quando può verificarlo facilmente, e che solo il 6,6 % lo considererebbe valido per decisioni importanti. Un diagramma di architettura nella documentazione ufficiale è, quasi per definizione, una decisione importante.

I sette difetti ricorrenti di un diagramma generato da IA

Questi sono i sette che compaiono ripetutamente durante l'audit dei .mmd generati da agenti. Tutti vengono analizzati; tutti sono errati. Il modello riempie una struttura plausibile dove manca informazione di dominio.

Sei vignette con i difetti ricorrenti dei diagrammi generati da IA: nodi duplicati, decisione senza ramo no, flusso senza terminatore, frecce invertite, scatola generica che nasconde diversi magazzini e strati inventati
Sei vignette con i difetti ricorrenti dei diagrammi generati da IA: nodi duplicati, decisione senza ramo no, flusso senza terminatore, frecce invertite, scatola generica che nasconde diversi magazzini e strati inventati
#DifettoSintomo nel .mmdConseguenza
1Nodi duplicatiDue ID distinti con etichette simili per lo stesso servizioSembra che ci siano due componenti dove ce n'è uno
2Decisione senza ramo "no"Un rombo con un'unica arista di uscitaIl percorso di errore rimane non documentato
3Flusso senza terminatoreCatene che terminano in un nodo di processoNon si sa quando termina il caso d'uso
4Direzione invertitaLa freccia punta all'origine dei datiSi inverte chi chiama chi
5Scatola genericaUn unico nodo "Database"Nasconde tre magazzini con garanzie diverse
6Profondità falsaStrati o subgraph che non esistono nel codiceConferisce autorità a un'architettura inventata
7Etichette del promptI nodi ripetono le tue parole, non il vocabolario del dominioIl diagramma non è ricercabile né riconoscibile

1. Nodi duplicati che sono lo stesso servizio

Il modello ha visto "auth" e "servizio di autenticazione" in due frasi diverse e ha creato due nodi.

flowchart LR
  API[API Gateway] --> AUTH[Auth]
  API --> AUTHSVC[Servizio di autenticazione]
  AUTH --> DB[(Database)]
  AUTHSVC --> DB

Corretto: un nodo, un ID, il nome utilizzato dal team.

flowchart LR
  API[API Gateway] --> AUTH[auth-service]
  AUTH --> USERS[(postgres: users)]

2. Decisioni senza ramo "no"

flowchart TD
  REQ[Richiesta] --> Q{Token valido?}
  Q -->|Sì| OK[Processare]

Un rombo con un'unica uscita non è una decisione: è un ornamento. Ogni condizione ha bisogno dei suoi due percorsi e il percorso di errore ha bisogno di una destinazione.

flowchart TD
  REQ[Richiesta] --> Q{Token valido?}
  Q -->|sì| OK[Processare]
  Q -->|no| R401[Rispondere 401]
  OK --> FIN([Fine])
  R401 --> FIN

3. Frecce che invertano la direzione dei dati

Classico con code e webhook: il modello disegna la gerarchia organizzativa invece del flusso reale.

flowchart LR
  WORKER[Lavoratore] --> QUEUE[Code di lavoro]

Il lavoratore non spinge nella coda: consuma da essa. Disegnare male questo senso trasforma un design pull in uno push, che è un altro sistema con altre garanzie.

flowchart LR
  API[API] -->|in coda| QUEUE[Code di lavoro]
  QUEUE -->|consuma| WORKER[Lavoratore]

4. La scatola generica "Database"

È il difetto più costoso, perché scompare esattamente l'informazione per cui qualcuno apre il diagramma. Un nodo [(Database)] che in realtà sono Postgres per transazioni, Redis per sessioni e S3 per allegati non documenta: nasconde. La regola pratica: se due magazzini hanno garanzie di durabilità diverse, sono due nodi.

5, 6 e 7: strati inventati e etichette prese in prestito

I subgraph chiamati "Strato di presentazione", "Strato di business" e "Strato di dati" sono spesso un modello mentale del modello, non la struttura del tuo repository. Così come le etichette: se il nodo si chiama "modulo di elaborazione pagamenti" e nel codice è billing-worker, nessuno potrà incrociare il diagramma con il progetto. E se manca il terminatore, il lettore non sa se il flusso finisce lì o se il modello è rimasto a metà.

Perché rivedere un diagramma in testo non funziona?

Perché i difetti che contano sono topologici e il testo non li espone. Leggendo un elenco di linee A --> B puoi verificare che ogni arista è plausibile una per una, ma non vedrai che due frecce si incrociano, che un nodo è rimasto orfano, che la gerarchia è invertita o che c'è un ciclo di tre salti. Queste proprietà sono visibili solo quando il grafo è disegnato e posizionato.

Confronto tra rivedere un diagramma leggendo linee di codice e vederlo disegnato, dove si apprezzano le frecce incrociate e un nodo duplicato
Confronto tra rivedere un diagramma leggendo linee di codice e vederlo disegnato, dove si apprezzano le frecce incrociate e un nodo duplicato

C'è un secondo motivo, più sottile: leggendo il .mmd rivedi ciò che l'autore ha scritto; guardando il rendering rivedi ciò che il lettore capirà. Sono cose diverse. Un diagramma con quindici ariste corrette e un auto-layout che le ammucchia è tecnicamente corretto e comunicativamente rotto, ed è precisamente ciò che un revisore di pull request approva senza guardare perché "il blocco mermaid è ben formato".

L'industria stessa si è mossa in questa direzione. Anthropic ha lanciato Claude Whiteboards in beta il 10-11-2026: una tela in tempo reale dove l'assistente trasforma una discussione in una bacheca, raggruppa note per tema e permette di portarlo successivamente a Lucid, Miro o Vani di Zoho (unite.ai). E Miro, nel suo evento Canvas 26, ha dichiarato che non è più "nel business delle lavagne" e che vuole essere "lo strato di decisione collaborativa per l'azienda agentica" (Forrester, 01-06-2026). L'uscita naturale dell'IA sta diventando la tela, non il blocco di testo. Per chi audita diagrammi, questa è una buona notizia: la revisione appartiene al luogo dove si vede la forma.

Il ciclo di revisione: da .mmd alla tela e di nuovo a .mmd

Il ciclo ha cinque fasi e la sua proprietà chiave è che chiude: ciò che entra nel repository è il diagramma corretto sulla tela, non l'originale dell'agente. Se la correzione rimane in uno screenshot o in un commento della pull request, il .mmd errato sopravvive e torna a nutrire il prossimo agente.

Ciclo di cinque fasi per auditare un diagramma: importare il codice, distribuirlo sulla tela, riordinare per livelli, annotare ciò che è dubbio ed esportare di nuovo
Ciclo di cinque fasi per auditare un diagramma: importare il codice, distribuirlo sulla tela, riordinare per livelli, annotare ciò che è dubbio ed esportare di nuovo
  1. Importare. Incolla il .mmd che ti ha dato l'agente in una tela visiva, o caricalo come file. Obiettivo: separare la revisione dall'editor di codice, dove la tentazione è leggere anziché guardare.
  2. Distribuire e riordinare. Posiziona i nodi in livelli orizzontali per responsabilità (ingresso, orchestrazione, dominio, archiviazione). Quasi tutti i difetti di direzione e di profondità falsa si rivelano qui: una freccia che sale di due livelli è spesso una freccia invertita.
  3. Contrassegnare ciò che è dubbio. Ogni nodo o connettore che non puoi confermare leggendo il codice viene annotato, e l'annotazione porta link alla prova: il file, il ticket, l'ADR. Un diagramma auditato non è uno senza dubbi, è uno dove i dubbi sono etichettati e tracciati.
  4. Correggere a mano. Unificare nodi duplicati, dividere la scatola generica nei veri archivi, aggiungere il ramo "no", chiudere con terminatore, cambiare il tipo di forma affinché un rombo sia rombo e un archivio sia cilindro, e riancorare i connettori ai punti corretti.
  5. Esportare di nuovo. Scaricare il risultato in .mmd e sostituire il file originale nel repository, nello stesso commit della revisione. Questo è il passo che la maggior parte dei team salta e quello che evita che l'errore venga reintrodotto.

Nella pratica, il passo 3 è quello che trasforma questo in un processo di ingegneria e non in una sessione di impaginazione. Una nota laterale con un link al file specifico che dimostra che il worker consuma dalla coda è documentazione verificabile; "penso che questa freccia sia al contrario" in un thread di Slack, no.

Checklist: 10 controlli prima di unire un diagramma generato da IA

Lista chiusa, pensata per essere incollata nel modello di pull request. Se qualcosa fallisce, il diagramma non entra.

  1. Unicità: nessun componente reale appare come due nodi. Un ID per servizio, il nome del repository o del deployment.
  2. Decisioni complete: ogni rombo ha almeno due spigoli di uscita, etichettati, e il ramo di errore ha una destinazione.
  3. Terminatori: ogni percorso termina in un nodo terminale esplicito; non ci sono catene che si interrompono in un passo di processo.
  4. Direzione dei dati: ogni freccia va nella direzione in cui viaggia l'informazione, non in quella della gerarchia organizzativa. Controlla specialmente code, webhook e polling.
  5. Archivi disaggregati: nessuna scatola generica tipo "Database", "Servizi" o "Infrastruttura". Un nodo per archivio con tecnologia e contenuto.
  6. Livelli reali: ogni subgraph corrisponde a un confine che esiste (un deployment, un repository, un account, una rete), non a un'astrazione da manuale.
  7. Vocabolario del dominio: le etichette utilizzano i nomi che il team scrive nel codice e nei ticket, non le parole del tuo prompt.
  8. Nessun orfano né incroci evitabili: nessun nodo disconnesso, e gli incroci che rimangono sono giustificati e non si risolvono riordinando.
  9. Leggibile alla dimensione in cui viene pubblicato: si capisce nella larghezza del README o del portale di documentazione, non solo con zoom.
  10. Tracciabilità: ogni elemento non ovvio ha una nota con link al codice, al ticket o all'ADR che lo supporta; e il .mmd del repository è quello esportato dopo la correzione.

Sviluppo guidato da specifiche: se il diagramma è errato, il codice eredita l'errore

Questa è la ragione per cui l'audit ha smesso di essere cosmetico nel 2026. Nello sviluppo guidato da specifiche, la specifica in Markdown —con i suoi diagrammi Mermaid di architettura e di sequenza— è l'artefatto da cui l'agente genera l'implementazione, non un commento su di essa. Un diagramma errato all'interno di quella specifica non è più documentazione obsoleta: è un'entrata difettosa in un generatore di codice.

L'approccio è raccolto nel Spec Kit di GitHub, la cui tesi è che "le specifiche non servono al codice; il codice serve alle specifiche", e i piani di implementazione che produce includono diagrammi di architettura e di sequenza in Mermaid insieme al modello di dati e ai modi di fallimento.

Tradotto nella vita quotidiana: un rombo senza ramo "no" nella specifica è, con buona probabilità, un caso di errore non implementato nel codice generato. Una freccia invertita tra API e coda è un design push dove volevi pull. E una scatola "Database" che copriva Postgres, Redis e S3 diventa un repository unico con tre responsabilità. Il diagramma è passato dall'essere la foto del sistema a essere parte del piano, e i piani vengono revisionati.

Domande frequenti

Cosa significa "Mermaid slop"?

È un diagramma generato da IA con sintassi Mermaid valida ma senza valore comunicativo: forme generiche e identiche, palette predefinite, frecce mal etichettate e, nei casi peggiori, componenti o relazioni che non esistono nel sistema. Il termine è diventato popolare a partire dal progetto Diagram Design e viene documentato dal riassunto di explainX di agosto 2026.

È possibile validare automaticamente un diagramma Mermaid generato da IA?

Solo in parte. Un linter o il parser stesso rilevano errori di sintassi, e possono essere automatizzate verifiche strutturali: nodi orfani, rombi con una sola uscita, percorsi senza terminatore o ID con etichette sospettosamente simili. Ciò che nessuno strumento può verificare da solo è se il diagramma descrive il tuo sistema; questo richiede di incrociarlo con il codice, ed è per questo che il checklist di questo articolo mescola controlli automatizzabili con revisione umana.

Perché non basta rivedere il blocco mermaid nella pull request?

Perché nel diff leggi gli archi uno a uno e i difetti rilevanti sono del grafo completo: incroci, gerarchie invertite, cicli, nodi isolati, densità illeggibile. Inoltre, leggendo il testo valuti l'intenzione dell'autore e non ciò che vedrà il lettore del render. La revisione utile si fa sul diagramma disegnato.

Quale strumento uso per correggere un diagramma Mermaid a mano?

Hai bisogno di una tela che faccia il viaggio completo: importare il .mmd, permetterti di muovere e cambiare forme e connettori, annotare elementi ed esportare di nuovo in Mermaid. Quest'ultimo passaggio è quello che scarta la maggior parte dei visualizzatori, che renderizzano ma non restituiscono il codice corretto. FlowBoard copre il ciclo: importa Mermaid da file o incollando il codice, distribuisce il diagramma su una tela infinita con zoom e scorrimento, consente di correggere forme, connettori e ancoraggi a mano con magnetismo ai punti di ancoraggio, aggiungere note laterali con link per elemento ed esportare di nuovo in Mermaid.

Quanto tempo ci vuole per auditare un diagramma generato da IA?

Dipende dalle dimensioni, ma l'ordine di grandezza per un diagramma di 15-25 nodi è di 20-40 minuti la prima volta, e molto meno quando il team ha già interiorizzato il checklist e i nomi del dominio sono fissati. Rispetto al costo di avere un'architettura errata nella documentazione ufficiale —o, in un flusso guidato da specifiche, nel codice generato—, è economico.

Bisogna smettere di usare IA per fare diagrammi?

No. Generare la prima bozza con un agente risparmia il lavoro noioso di digitare nodi e archi, ed è utile per esplorare un sistema sconosciuto. Ciò che non deve essere saltato è il passo successivo: nessun diagramma generato da IA viene pubblicato senza passare per la tela e per il checklist. L'IA fa la bozza; la responsabilità del diagramma rimane comunque del team che lo firma.

Chiusura: il diagramma che pubblichi è quello che hai auditato

Il cambiamento del 2026 non è che l'IA disegni diagrammi, è che li disegna più velocemente di quanto li rivediamo. Mentre VS Code li dipinge senza configurazione, Claude li trasforma in bacheche e le specifiche in Markdown alimentano generatori di codice, l'unico controllo di qualità che rimane è quello umano: guardare la forma, segnare ciò che non può essere dimostrato e restituire al repository la versione corretta. Dieci controlli e un ciclo che si chiude sono sufficienti affinché un diagramma torni ad essere documentazione affidabile invece di decorazione plausibile.

Questo ciclo ha bisogno di un luogo dove avvenire. In AIsToHire lo risolviamo con FlowBoard, la nostra bacheca infinita per diagrammi: si incolla o si importa il .mmd dell'agente, si distribuisce su un canvas infinito, si riorganizzano forme —rettangoli, ellissi, rombi decisionali, documenti, note adesive e testo— e connettori con frecce rette o ortogonali, si ancorano ogni connessione con magnetismo ai punti degli elementi, si annota ciò che è dubbio con note laterali e link di verifica, e si esporta di nuovo in Mermaid. La bacheca si salva da sola, quindi l'audit rimane registrato e può essere ripreso.

Apri FlowBoard, incolla il .mmd fornito dall'agente e controlla il diagramma dove si vede realmente: riordina per livelli, correggi forme e connettori a mano, annota i dubbi con link di verifica ed esportalo di nuovo in Mermaid. Inizia la tua prima board gratuitamente.

Apri FlowBoard, incolla il .mmd fornito dall'agente e controlla il diagramma dove si vede realmente: riordina per livelli, correggi forme e connettori a mano, annota i dubbi con link di verifica ed esportalo di nuovo in Mermaid. Inizia la tua prima board gratuitamente.

Continua a leggere

Vedi tutti gli articoli →

↑ Torna su