FlowBoardFlowBoard

Mermaid slop: como revisar e corrigir os diagramas gerados pela IA antes de publicá-los

Equipa de FlowBoardRedigido com assistência de IA15 min de leitura

Em resumo:

  • "Mermaid slop" é o nome que se popularizou em 2026 para os diagramas gerados por IA que são válidos em sintaxe, mas ilegíveis ou diretamente falsos; o termo surgiu do projeto Diagram Design, que era apresentado com o lema "sem Figma, sem caixas arredondadas genéricas, sem Mermaid-slop" e que já superava as 11.000 estrelas no GitHub em agosto de 2026 (explainX, 16-08-2026).
  • O problema cresceu com a distribuição: VS Code 1.121 (20-05-2026) renderiza Mermaid de forma nativa na pré-visualização de Markdown, sem extensão, e os assistentes o geram por padrão (Visual Studio Code).
  • Um modelo otimiza validade gramatical, não correção do sistema: o .mmd faz o parsing, mas duplica nós, deixa a ramificação "não" de uma decisão ou inverte a direção do dado.
  • Revisar um diagrama lendo linhas de --> não funciona: os defeitos que importam são topológicos e só aparecem desenhados.
  • O ciclo que funciona: importar o .mmd para uma tela, reorganizar por camadas, anotar o duvidoso com link para o código ou para o ticket que o demonstra, corrigir manualmente e reexportar para que a versão corrigida seja a que entra no repositório.

Desde meados de 2026, a pergunta nas equipes de engenharia já não é como gerar um diagrama, mas quem é responsável por ele. Os agentes escrevem Mermaid em tempo real, GitHub e VS Code o pintam sem configuração e o resultado entra no README com a mesma naturalidade com que entra um bloco de código. O que falta é a camada de auditoria. Este artigo percorre os defeitos típicos, o motivo técnico pelo qual aparecem e um ciclo de revisão reproduzível que se fecha em uma tela visual —no nosso caso, FlowBoard, a tela infinita para diagramas de AIsToHire, que importa e reexporta Mermaid— para que o diagrama que é publicado seja o corrigido e não o primeiro que foi gerado pelo modelo.

Diagrama gerado por IA ilegível em uma tela em frente ao mesmo diagrama reorganizado por camadas em uma tela visual
Diagrama gerado por IA ilegível em uma tela em frente ao mesmo diagrama reorganizado por camadas em uma tela visual

O que é exatamente o "Mermaid slop"?

Mermaid slop é um diagrama gerado por IA que compila sem erros e ainda assim não serve: caixas arredondadas idênticas para conceitos distintos, flechas sem etiqueta ou com etiquetas vagas, cores padrão que não dizem nada e uma geração reflexiva —é desenhado porque foi solicitado, não porque é necessário—. A definição é estabelecida pela revisão de explainX sobre o termo (16-08-2026), que o rastreia até o projeto Diagram Design de Cathryn Lavery.

O matiz importante é que há duas camadas de "slop" e elas se confundem frequentemente:

CamadaO que falhaÉ detectadoCusto para corrigir
EstéticaFormas genéricas, paleta padrão, tudo igualÀ primeira vistaBaixo: tema, formas, agrupamento
SemânticaO diagrama descreve um sistema que não existeSomente comparando com o código realAlto: é necessário reabrir o repositório

A conversa pública de 2026 se concentrou quase toda na primeira. As ferramentas que surgiram —desde as skills de diagramação editorial até os geradores que produzem elementos nativos de Excalidraw em vez de texto Mermaid— atacam principalmente o aspecto. A segunda camada, a que faz com que um diagrama minta sobre sua arquitetura, continua sendo trabalho humano.

Por que um LLM produz Mermaid perfeito em sintaxe e pobre em semântica?

Porque são dois objetivos distintos e apenas um tem sinal de treinamento abundante. A gramática de Mermaid é fechada, pequena e está massivamente representada no GitHub: um modelo a reproduz quase sem falhar. A correção do diagrama, por outro lado, depende de um sistema concreto que o modelo normalmente não leu por completo, então preenche as lacunas com a forma mais frequente de um diagrama de arquitetura, não com a sua.

A isso se somam três efeitos práticos:

  • O prompt é a única fonte. Se você descreve o sistema em três frases, o agente retorna um diagrama com a granularidade de três frases e o adorna até parecer completo. Como resume a própria Mermaid ao falar de vibe diagramming, "um diagrama gerado a partir de um prompt vago refletirá a vaguidade do prompt" (Mermaid, 24-03-2026).
  • Não há compilador semântico. Um teste vermelho te avisa; um diagrama incorreto renderiza tão bonito quanto um correto. Não existe o equivalente de tsc para "este serviço não existe".
  • O layout é decidido pelo motor, não pelo autor. Mermaid coloca os nós com seu algoritmo e não oferece uma forma conveniente de corrigir a disposição após a renderização. Se a hierarquia real não coincide com o que o auto-layout desenha, você perde a discussão com a ferramenta.

E o contexto do setor diz que a verificação não é opcional. A pesquisa de desenvolvedores 2026 do Stack Overflow (publicada em 06-10-2026, mais de 30.000 respostas em 169 países) descobriu que quase metade confia na saída da IA somente quando pode verificá-la facilmente, e que apenas 6,6% a consideraria boa para decisões importantes. Um diagrama de arquitetura na documentação oficial é, quase por definição, uma decisão importante.

Os sete defeitos recorrentes de um diagrama gerado por IA

Estes são os sete que aparecem repetidamente ao auditar .mmd gerados por agentes. Todos fazem parsing; todos estão errados. O padrão comum é que o modelo preenche uma estrutura plausível onde falta informação do domínio.

Seis quadrinhos com os defeitos recorrentes dos diagramas gerados por IA: nós duplicados, decisão sem ramo não, fluxo sem terminador, setas invertidas, caixa genérica que oculta vários armazéns e camadas inventadas
Seis quadrinhos com os defeitos recorrentes dos diagramas gerados por IA: nós duplicados, decisão sem ramo não, fluxo sem terminador, setas invertidas, caixa genérica que oculta vários armazéns e camadas inventadas
#DefeitoSintoma no .mmdConsequência
1Nós duplicadosDois IDs distintos com rótulos parecidos para o mesmo serviçoParece que há dois componentes onde há um
2Decisão sem ramo "não"Um losango com uma única aresta de saídaO caminho de erro fica indocumentado
3Fluxo sem terminadorCadeias que terminam em um nó de processoNão se sabe quando termina o caso de uso
4Direção invertidaA seta aponta para a origem do dadoInverte quem chama quem
5Caixa genéricaUm único nó "Banco de dados"Oculta três armazéns com garantias distintas
6Profundidade falsaCamadas ou subgraph que não existem no códigoDá autoridade a uma arquitetura inventada
7Rótulos do promptOs nós repetem suas palavras, não o vocabulário do domínioO diagrama não é pesquisável nem reconhecível

1. Nós duplicados que são o mesmo serviço

O modelo viu "auth" e "serviço de autenticação" em duas frases distintas e criou dois nós.

flowchart LR
  API[API Gateway] --> AUTH[Auth]
  API --> AUTHSVC[Serviço de autenticação]
  AUTH --> DB[(Banco de dados)]
  AUTHSVC --> DB

Corrigido: um nó, um ID, o nome que a equipe usa.

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

2. Decisões sem ramo "não"

flowchart TD
  REQ[Pedido] --> Q{Token válido?}
  Q -->|Sim| OK[Processar]

Um losango com uma única saída não é uma decisão: é uma decoração. Toda condição precisa de seus dois caminhos e o caminho de erro precisa de destino.

flowchart TD
  REQ[Pedido] --> Q{Token válido?}
  Q -->|sim| OK[Processar]
  Q -->|não| R401[Responder 401]
  OK --> FIM([Fim])
  R401 --> FIM

3. Setas que invertem a direção do dado

Clássico com filas e webhooks: o modelo desenha a hierarquia organizacional em vez do fluxo real.

flowchart LR
  WORKER[Trabalhador] --> QUEUE[Fila de trabalhos]

O trabalhador não empurra para a fila: consome dela. Desenhar mal esse sentido transforma um design pull em um push, que é outro sistema com outras garantias.

flowchart LR
  API[API] -->|encola| QUEUE[Fila de trabalhos]
  QUEUE -->|consume| WORKER[Trabalhador]

4. A caixa genérica "Banco de dados"

É o defeito mais caro, porque desaparece exatamente a informação pela qual alguém abre o diagrama. Um nó [(Banco de dados)] que na verdade são Postgres para transações, Redis para sessões e S3 para anexos não documenta: oculta. A regra prática: se dois armazéns têm garantias de durabilidade distintas, são dois nós.

5, 6 e 7: camadas inventadas e rótulos emprestados

Os subgraph chamados "Camada de apresentação", "Camada de negócio" e "Camada de dados" costumam ser uma template mental do modelo, não a estrutura do seu repositório. Assim como os rótulos: se o nó se chama "módulo de processamento de pagamentos" e no código é billing-worker, ninguém poderá cruzar o diagrama com o projeto. E se faltar o terminador, o leitor não sabe se o fluxo termina ali ou se o modelo ficou pela metade.

Por que revisar um diagrama em texto não funciona?

Porque os defeitos que importam são topológicos e o texto não os expõe. Lendo uma lista de linhas A --> B você pode verificar que cada aresta é plausível uma por uma, mas não vai ver que duas setas se cruzam, que um nó ficou órfão, que a hierarquia está invertida ou que há um ciclo de três saltos. Essas propriedades só são visíveis quando o grafo está desenhado e colocado.

Comparação entre revisar um diagrama lendo linhas de código e vê-lo desenhado, onde se apreciam as setas cruzadas e um nó duplicado
Comparação entre revisar um diagrama lendo linhas de código e vê-lo desenhado, onde se apreciam as setas cruzadas e um nó duplicado

Há um segundo motivo, mais sutil: ao ler o .mmd você revisa o que o autor escreveu; ao olhar o render você revisa o que o leitor vai entender. São coisas distintas. Um diagrama com quinze arestas corretas e um auto-layout que as amontoa está tecnicamente bem e comunicativamente quebrado, e é precisamente isso que um revisor de pull request aprova sem olhar porque "o bloco mermaid está bem formado".

A própria indústria se moveu nessa direção. A Anthropic lançou Claude Whiteboards em beta em 10-11-2026: uma tela em tempo real onde o assistente converte uma discussão em um quadro, agrupa notas por tema e permite levá-lo depois para Lucid, Miro ou Vani da Zoho (unite.ai). E o Miro, em seu evento Canvas 26, declarou que já "não está no negócio de quadros brancos" e que quer ser "a camada de tomada de decisões colaborativa para a empresa ágil" (Forrester, 01-06-2026). A saída natural da IA está se tornando a tela, não o bloco de texto. Para quem audita diagramas, isso é uma boa notícia: a revisão pertence ao local onde se vê a forma.

O ciclo de revisão: do .mmd para a tela e de volta ao .mmd

O ciclo tem cinco etapas e sua propriedade chave é que fecha: o que entra no repositório é o diagrama corrigido na tela, não o original do agente. Se a correção ficar em uma captura de tela ou em um comentário do pull request, o .mmd incorreto sobrevive e volta a alimentar o próximo agente.

Ciclo de cinco etapas para auditar um diagrama: importar o código, distribuí-lo na tela, reorganizar por camadas, anotar o duvidoso e exportar de volta
Ciclo de cinco etapas para auditar um diagrama: importar o código, distribuí-lo na tela, reorganizar por camadas, anotar o duvidoso e exportar de volta
  1. Importar. Cole o .mmd que o agente te deu em uma tela visual, ou carregue-o como arquivo. Objetivo: separar a revisão do editor de código, onde a tentação é ler em vez de olhar.
  2. Distribuir e reorganizar. Coloque os nós em camadas horizontais por responsabilidade (entrada, orquestração, domínio, armazenamento). Quase todos os defeitos de direção e de profundidade falsa se delatam aqui: uma seta que sobe duas camadas costuma ser uma seta invertida.
  3. Marcar o duvidoso. Cada nó ou conector que você não puder confirmar lendo o código é anotado, e a anotação leva link para a prova: o arquivo, o ticket, o ADR. Um diagrama auditado não é aquele sem dúvidas, é aquele onde as dúvidas estão etiquetadas e rastreadas.
  4. Corrigir manualmente. Unificar nós duplicados, dividir a caixa genérica nos armazéns reais, adicionar o ramo "não", fechar com terminador, mudar o tipo de forma para que um losango seja losango e um armazém seja cilindro, e reanclar os conectores aos pontos corretos.
  5. Exportar de volta. Jogar o resultado para .mmd e substituir o arquivo original no repositório, no mesmo commit que a revisão. Esse é o passo que a maioria das equipes ignora e o que evita que o erro seja reintroduzido.

Na prática, o passo 3 é o que transforma isso em um processo de engenharia e não em uma sessão de maquetagem. Uma nota lateral com um link para o arquivo específico que demonstra que o trabalhador consome da fila é documentação verificável; "acho que esta seta está ao contrário" em um thread do Slack, não.

Checklist: 10 verificações antes de fazer merge de um diagrama gerado por IA

Lista fechada, pensada para colar no template de pull request. Se alguma falhar, o diagrama não entra.

  1. Unicidade: nenhum componente real aparece como dois nós. Um ID por serviço, o nome do repositório ou da implantação.
  2. Decisões completas: todo losango tem pelo menos duas arestas de saída, etiquetadas, e o ramo de erro tem destino.
  3. Terminadores: todo caminho termina em um nó terminal explícito; não há cadeias que se cortem em um passo de processo.
  4. Direção dos dados: cada seta vai na direção em que viaja a informação, não na da hierarquia organizacional. Revise especialmente filas, webhooks e polling.
  5. Armazéns desagregados: nenhuma caixa genérica tipo "Banco de dados", "Serviços" ou "Infraestrutura". Um nó por armazém com tecnologia e conteúdo.
  6. Camadas reais: cada subgraph corresponde a um limite que existe (uma implantação, um repositório, uma conta, uma rede), não a uma abstração de manual.
  7. Vocabulário do domínio: as etiquetas usam os nomes que a equipe escreve no código e nos tickets, não as palavras do seu prompt.
  8. Sem órfãos nem cruzamentos evitáveis: nenhum nó desconectado, e os cruzamentos que restarem estão justificados e não se resolvem reorganizando.
  9. Legível no tamanho em que é publicado: é compreensível na largura do README ou do portal de documentação, não apenas com zoom.
  10. Rastreabilidade: cada elemento não óbvio tem uma nota com link para o código, para o ticket ou para o ADR que o respalda; e o .mmd do repositório é o exportado após a correção.

Desenvolvimento orientado por especificação: se o diagrama estiver errado, o código herda o erro

Esta é a razão pela qual a auditoria deixou de ser cosmética em 2026. No desenvolvimento orientado por especificação, a especificação em Markdown —com seus diagramas Mermaid de arquitetura e de sequência— é o artefato do qual o agente gera a implementação, não um comentário sobre ela. Um diagrama incorreto dentro dessa especificação já não é documentação desatualizada: é uma entrada defeituosa em um gerador de código.

A abordagem está registrada no próprio Spec Kit do GitHub, cuja tese é que "as especificações não servem ao código; o código serve às especificações", e os planos de implementação que produz incluem diagramas de arquitetura e de sequência em Mermaid junto ao modelo de dados e os modos de falha.

Traduzido para o dia a dia: um losango sem ramo "não" na especificação é, com bastante probabilidade, um caso de erro não implementado no código gerado. Uma seta invertida entre API e fila é um design push onde você queria pull. E uma caixa "Banco de dados" que cobria Postgres, Redis e S3 se torna um repositório único com três responsabilidades. O diagrama passou de ser a foto do sistema a ser parte do plano, e os planos são revisados.

Perguntas frequentes

O que significa "Mermaid slop"?

É um diagrama gerado por IA com sintaxe Mermaid válida, mas sem valor comunicativo: formas genéricas e idênticas, paleta padrão, setas mal rotuladas e, nos piores casos, componentes ou relações que não existem no sistema. O termo se popularizou a partir do projeto Diagram Design e é documentado pela revisão do explainX de agosto de 2026.

É possível validar automaticamente um diagrama Mermaid gerado por IA?

Somente em parte. Um linter ou o próprio parser detecta erros de sintaxe, e verificações estruturais podem ser automatizadas: nós órfãos, losangos com uma única saída, caminhos sem terminador ou IDs com rótulos suspeitos. O que nenhuma ferramenta pode verificar sozinha é se o diagrama descreve seu sistema; isso exige cruzá-lo com o código, e por isso a lista de verificação deste artigo mistura verificações automatizáveis com revisão humana.

Por que não é suficiente revisar o bloco mermaid no pull request?

Porque no diff você lê arestas uma a uma e os defeitos relevantes são do grafo completo: cruzamentos, hierarquias invertidas, ciclos, nós isolados, densidade ilegível. Além disso, ao ler o texto você avalia a intenção do autor e não o que o leitor verá no render. A revisão útil é feita sobre o diagrama desenhado.

Que ferramenta uso para corrigir um diagrama Mermaid manualmente?

Você precisa de uma tela que faça a viagem completa: importar o .mmd, permitir mover e mudar formas e conectores, anotar elementos e exportar novamente para Mermaid. Esse último passo é o que descarta a maioria dos visualizadores, que renderizam, mas não devolvem o código corrigido. FlowBoard cobre o ciclo: importa Mermaid de arquivo ou colando o código, distribui o diagrama em uma tela infinita com zoom e rolagem, permite corrigir formas, conectores e âncoras manualmente com magnetismo aos pontos de ancoragem, adicionar notas laterais com links por elemento e exportar de volta para Mermaid.

Quanto tempo leva para auditar um diagrama gerado por IA?

Depende do tamanho, mas a ordem de magnitude para um diagrama de 15-25 nós é de 20 a 40 minutos na primeira vez, e bastante menos quando a equipe já tem a lista de verificação interiorizada e os nomes do domínio fixados. Comparado ao custo de uma arquitetura errada entrar na documentação oficial —ou, em um fluxo dirigido por especificação, no código gerado—, é barato.

É preciso parar de usar IA para fazer diagramas?

Não. Gerar o primeiro rascunho com um agente economiza o trabalho tedioso de digitar nós e arestas, e para explorar um sistema desconhecido é útil. O que não deve ser pulado é o passo seguinte: nenhum diagrama gerado por IA é publicado sem passar pela tela e pela lista de verificação. A IA faz o rascunho; a responsabilidade do diagrama continua sendo da equipe que o assina.

Fechamento: o diagrama que você publica é o que você auditou

A mudança de 2026 não é que a IA desenhe diagramas, é que os desenha mais rápido do que os revisamos. Enquanto o VS Code os pinta sem configuração, Claude os transforma em quadros e as especificações em Markdown alimentam geradores de código, o único controle de qualidade que resta é o humano: olhar a forma, marcar o que não pode ser demonstrado e devolver ao repositório a versão corrigida. Dez verificações e um ciclo que se fecha são suficientes para que um diagrama volte a ser documentação confiável em vez de decoração plausível.

Esse ciclo precisa de um lugar onde acontecer. No AIsToHire, resolvemos isso com FlowBoard, nosso quadro infinito para diagramas: cola ou importa o .mmd do agente, distribui em um canvas infinito, reposiciona formas —retângulos, elipses, losangos de decisão, documentos, notas adesivas e texto— e conectores com setas retas ou ortogonais, ancla cada conexão com magnetismo aos pontos dos elementos, anota o duvidoso com notas laterais e links de verificação, e exporta de volta para Mermaid. O quadro é salvo automaticamente, assim a auditoria fica registrada e pode ser retomada.

Abra o FlowBoard, cole o .mmd que o agente lhe deu e audite o diagrama onde ele realmente aparece: reorganize por camadas, corrija formas e conectores manualmente, anote o que parecer duvidoso com links de verificação e exporte de volta para o Mermaid. Comece seu primeiro painel grátis.

Abra o FlowBoard, cole o .mmd que o agente lhe deu e audite o diagrama onde ele realmente aparece: reorganize por camadas, corrija formas e conectores manualmente, anote o que parecer duvidoso com links de verificação e exporte de volta para o Mermaid. Comece seu primeiro painel grátis.

↑ Voltar ao topo