Diagramas Mermaid: como criamos diagramas nativos para IA para engenheiros

Quer um resumo?

Sou Hannah Knight, gerente de produto do Structured Diagrams with Mermaid na Miro. Quero mostrar o que são os diagramas Mermaid, por que acrescentamos suporte nativo a Mermaid na Miro e como usá‑los na prática hoje. Essa funcionalidade está em Beta público, então vou ser direta sobre o que funciona agora e o que ainda está por vir. Veja na prática: um único prompt mapeia um incidente inteiro diretamente da base de código, mostrando cada serviço e cada chamada entre eles. O time usa cores para indicar o que quebrou, comenta diretamente no diagrama para elaborar uma correção e então devolve para um agente, que redige toda a decisão como um pull request no GitHub. 

O que o Mermaid realmente é

Então, o que é um diagrama Mermaid? É um diagrama descrito inteiramente em texto. Você escreve algo como A --> B e obtém duas caixas, A e B, ligadas por uma seta. É só isso. Você pode usá‑lo para descrever quase qualquer tipo de diagrama: fluxogramas, diagramas de sequência, diagramas de classes, diagramas entidade‑relacionamento (ER) e outros.

Engenheiros usam o Mermaid há anos para manter diagramas no repositório de código, bem ao lado do código que descrevem. Mas ele ganhou nova vida recentemente por um motivo simples: modelos de linguagem de grande porte são muito bons em escrevê‑lo. Peça a um agente de codificação com IA para diagramar seu sistema e há boa chance de ele devolver a sintaxe Mermaid, porque esse é o formato que aprendeu a escrever bem.

Essa combinação, código que tanto pessoas quanto IA podem ler e escrever, é exatamente por isso que incorporamos suporte ao Mermaid diretamente na Miro.

O problema que eu continuava ouvindo

Antes de criarmos isso, o Mermaid aparecia repetidamente em chamadas com clientes e em entrevistas com usuários, sem que ninguém pedisse. Os engenheiros já tinham percebido que diagramas gerados por IA ficavam melhores quando pediam Mermaid em vez de uma imagem. Diagramas sempre foram essenciais para a forma como engenheiros explicam sistemas complexos de maneira simples e o Mermaid combinado com IA permitiu que gerassem diagramas de alta qualidade mais rápido do que conseguiriam fazer à mão.

A distinção de “diagrama como código, não apenas uma imagem” importa por duas razões. Se um diagrama existe apenas como imagem, um engenheiro não consegue acompanhar as alterações nele da mesma forma que acompanha as mudanças no código. Há também uma segunda razão, mais técnica: grandes modelos de linguagem entendem muito melhor texto linear do que imagens bidimensionais, por causa de como processam a informação. Quando o diagrama é código, um agente de IA pode editar de forma precisa e pontual em vez de regenerar tudo do zero.

Já vi engenheiros passar por esse mesmo cenário com as ferramentas antigas. A base de código muda e o diagrama fica desatualizado. Então eles abrem a Miro, arrastam manualmente formas e caixas para refletir o que mudou e depois documentam. Isso pode levar horas.

Agora, eles podem simplesmente pedir a um agente de codificação, como o Claude Code, para gerar um diagrama da base de código, e ele é renderizado automaticamente e fica bonito em um board da Miro. Se a base de código mudar rapidamente, eles podem até configurar uma skill agendada para manter o board atualizado regularmente.

Por que criamos os Diagramas estruturados com Mermaid

Structured Diagrams with Mermaid traz o diagrama como código diretamente para a Miro. Você escreve ou gera a sintaxe Mermaid, o diagrama é renderizado como formas reais da Miro, você e seu time iteram nele e o exportam de volta para código quando terminam. É um ciclo completo: um agente pode gerar um diagrama pelo servidor MCP da Miro, seu time colabora nele visualmente, e outro agente pode lê-lo novamente via MCP para manter sua base de código sincronizada.

Mermaid é a única fonte da verdade. Quando você edita um diagrama visualmente na Miro, o código Mermaid subjacente é atualizado junto, de modo que o código e o diagrama nunca ficam dessincronizados. Poderíamos ter rompido esse vínculo e tratado o diagrama como algo separado assim que fosse adicionado ao board, como algumas outras ferramentas fazem. Optamos por não fazer isso. Manter o Mermaid como a fonte da verdade significa que um agente de IA pode sempre entender seu diagrama e fazer edições precisas nele, e você pode exportá-lo para GitHub, VS Code, Obsidian ou qualquer outro lugar que suporte Mermaid.

Isso substitui por completo o antigo aplicativo Mermaid do Marketplace da Miro. Aquele aplicativo gerava formas livres, não Mermaid de verdade, e não permitia ida e volta: um agente podia gerar um diagrama, mas não conseguia ler suas edições. Diagramas estruturados com Mermaid faz ambos.

O que acontece quando você gera um diagrama

Em termos simples, é assim que funciona o ciclo de ida e volta: cole a sintaxe Mermaid em um board e o diagrama é renderizado na hora. Peça a um agente de IA, como Claude Code, Claude Cowork, Codex ou Cursor, para gerar um diagrama, e ele usa o servidor MCP da Miro para escrever essa mesma sintaxe Mermaid diretamente no seu board. De qualquer forma, o diagrama aparece renderizado e pronto, não como um rascunho que você precisa ajustar.

Quais tipos de diagrama são renderizados como formas nativas do Miro

Atualmente, quatro tipos de diagrama são renderizados como formas nativas do Miro:

• Fluxogramas mapeiam fluxos de trabalho, árvores de decisão e processos, para que você veja exatamente onde um processo pode travar.
• Diagramas de sequência mostram como sistemas ou componentes se comunicam ao longo do tempo, útil para a comunicação entre microserviços ou para a ordem das chamadas de API.
• Diagramas de classe visualizam objetos, seus atributos e como eles se relacionam.
• Diagramas entidade-relacionamento (ER) mapeiam o esquema do banco de dados e as relações entre tabelas.

Investimos muito para que esses quatro tenham boa aparência desde o primeiro momento, assim você obtém algo pronto para apresentação sem formatação extra.

O Mermaid também suporta muitos outros tipos de diagrama, incluindo gráficos de Gantt e diagramas C4 para arquitetura de sistemas. Atualmente esses são renderizados como SVGs do Mermaid.js em vez de formas nativas da Miro. Você ainda pode adicioná‑los ao seu board, editar com IA e exportá‑los, mas eles não ficam com visual pronto para apresentação, e não é possível clicar neles e editá‑los visualmente como no fluxograma. Se estiver avaliando isso para seu time, essa distinção importa: saiba quais diagramas terão edição nativa completa hoje e quais você usará principalmente para visualização e exportação.

Primeiros passos com diagramas Mermaid na Miro

Veja como funciona na prática:

1. Abra a barra de criação, selecione formatos, depois Diagrama e clique em "Criar com código".
2. Cole o código Mermaid que você já tem, escolha um template ou envie ao seu agente um prompt para gerar um diagrama diretamente da sua base de código, mapeando todos os serviços e todas as chamadas entre eles em segundos.
3. Veja-o renderizar como formas nativas da Miro, com um layout limpo e automático, para que você não precise posicionar manualmente as caixas e evitar que as linhas se cruzem.
4. Abra o diagrama no modo foco para editá‑lo. Você pode selecionar uma forma, uma linha ou uma etiqueta de texto e ajustá‑la diretamente, alterar a direção do layout (de cima para baixo, da esquerda para a direita etc.) ou ajustar o espaçamento, de estreito a amplo. Também é possível abrir o painel de código e editar a sintaxe Mermaid diretamente, ou colar o link do diagrama na sua ferramenta de IA e pedir ao seu agente para fazer a alteração. Seja qual for a forma de edição, o código Mermaid e o diagrama permanecem sincronizados.
5. Dê significado ao diagrama. Use cores para indicar um status ou incidente, ou peça ao seu agente para fazer a alteração. Quando um agente editar um diagrama, ele pode até adicionar uma legenda marcando o que adicionou, removeu ou alterou.
6. Convide seu time para comentar diretamente no diagrama, no contexto do status atual e da correção ou alteração que propõe, em vez de iniciar uma conversa separada em outro lugar.
7. Feche o ciclo. Copie a sintaxe Mermaid de volta para sua base de código, exporte o diagrama como imagem (JPG, SVG ou PDF), compartilhe um link do modo foco com colaboradores ou permita que seu agente leia o diagrama e os comentários do seu time por meio do MCP e redija um documento, como um registro de decisão de arquitetura pronto para abrir como pull request.

Se você já conhece a sintaxe do Mermaid, pode começar a escrevê-la imediatamente. Se nunca mexeu com o Mermaid antes, comece com um template, edite as formas visualmente ou simplesmente descreva o que quer para seu agente de IA e deixe-o escrever a sintaxe para você. Uma coisa importante para quem está no plano Enterprise: um Admin da empresa precisa ativar o Miro MCP antes que alguém do seu time possa conectar uma ferramenta de IA a ele.

Um erro que vejo as pessoas cometerem no início

As pessoas tentam arrastar formas livremente, como se faz em um canvas comum da Miro, e isso não funciona assim. Chamamos esses diagramas de "estruturados" porque são baseados em código e um dos benefícios reais é que a Miro os posiciona automaticamente. Se você realmente precisa de mais formas ou de movimento totalmente livre, pode mudar um diagrama para edição livre, mas saiba que é uma via de mão única: depois da mudança, o diagrama não fica mais sincronizado com o código Mermaid, e nem você nem seu agente poderão editá-lo via MCP. Se ainda não tiver certeza, comece explorando as diversas funcionalidades que oferecemos para Structured Diagrams ou transforme uma cópia para edição livre em vez de converter o original.

Também não existe uma única maneira "certa" de escrever Mermaid. Não complique demais seu primeiro diagrama. Coloque algo e depois itere — seja você editando, um colega do time refinando ou um agente retomando o trabalho.

Como isso se comporta em escala

Suportamos arquivos Mermaid de até 30.000 linhas de código e testamos diagramas com 500 ou mais nós em fluxogramas complexos sem queda de desempenho. Não existe um limite rígido para quantos diagramas Mermaid podem estar em um board.

Onde isso se encaixa nas suas ferramentas atuais

Se outra ferramenta exporta sintaxe Mermaid, você pode colá‑la diretamente em um board da Miro. Quer manter um diagrama sob controle de versão? Exporte como arquivo Markdown ou .mmd e faça commit no seu repositório, do mesmo modo que faria com qualquer outro código. Você pode até configurar um fluxo de trabalho em que seu agente gera o diagrama, exporta, faz commit e o atualiza conforme seu código muda, sem intervenção manual.

Exemplos e inspiração para diagramas Mermaid

Nada disso é útil no abstrato, então veja onde os times estão aplicando na prática:

Integração de arquitetura

Em vez de entregar a um novo engenheiro uma página da wiki desatualizada desde o último trimestre, peça ao seu agente para criar um diagrama da arquitetura de microsserviços atual diretamente da base de código. Dessa forma, terá algo que reflete o que está realmente em execução e não o que estava rodando há seis meses.

Revisar uma alteração no esquema

Antes de uma grande migração, gere um diagrama ER do novo esquema para que os revisores vejam a mudança estrutural de relance, em vez de tentar desvendá-la a partir de um diff de texto.

Revisão de incidente, do início ao fim

Gere um diagrama dos serviços afetados diretamente da base de código assim que algo quebrar. Aplique cores ou anotações para mostrar o que falhou e por quê, depois convide o time a comentar diretamente no diagrama para trabalhar na correção. Quando o time concordar, peça ao seu agente para ler o diagrama e os comentários pelo MCP e redigir a decisão como um documento, por exemplo um registro de decisão de arquitetura pronto para abrir como pull request.

Documentar uma API

Gere um diagrama de sequência das chamadas do seu serviço, mantenha o código Mermaid no seu repositório e peça ao seu agente para atualizá-lo sempre que a API mudar, em vez de redesenhá-lo manualmente a cada versão.

Mapear um modelo de dados antes de construir

Faça um esboço de um diagrama ER ou de classes cedo, enquanto o modelo de dados ainda é apenas uma ideia. É muito mais barato identificar uma relação incorreta no diagrama do que depois de escrever a migração.

Revisando um pull request

Ao revisar um pull request, peça ao seu agente para gerar um diagrama Mermaid mostrando o estado do código antes e depois, para agilizar o entendimento. Com IA, os engenheiros estão revisando muito mais mudanças de código do que nunca e as visualizações podem acelerar esse processo.

Melhores práticas para diagramas Mermaid

Deixe a IA escrever o primeiro rascunho

Se o seu agente já tiver o contexto, seja o código do projeto, um conjunto de requisitos ou um documento existente, peça para que ele gere o diagrama em vez de escrever a sintaxe Mermaid manualmente. Ajuste a partir daí.

Alinhe suas expectativas ao que é editável visualmente hoje

Atualmente, fluxogramas são o tipo de diagrama mais flexível. Diagramas de sequência, de classe e ER (entidade-relacionamento) são renderizados nativamente e têm boa aparência, mas trate-os como diagramas orientados a código até que a edição visual também esteja disponível para eles.

Mantenha o feedback no diagrama, não espalhado por aí

Comente diretamente no diagrama em vez de iniciar um thread paralelo no Slack ou enviar um e-mail. Assim, a decisão e o contexto ficam em um só lugar, e seu agente pode ler toda a conversa por meio do MCP.

Versione seus diagramas como versiona seu código

Exporte como Markdown ou .mmd e faça commit. É um hábito simples, e garante que o histórico do diagrama seja tão confiável quanto o histórico do código.

Diga quando algo estiver faltando

Se encontrar um problema de renderização ou precisar de um tipo de diagrama que ainda não seja editável visualmente, avise-nos. Este Beta existe especificamente para que esse tipo de feedback ainda possa moldar o que será lançado a seguir.

Sendo franco sobre o Beta

Este é um Beta público e quero ser franco sobre como as coisas estão. A edição visual funciona apenas para fluxogramas no momento; diagramas de sequência, de classe e ER são renderizados como formas nativas, mas ainda não suportam o mesmo fluxo visual de clicar para editar. A edição visual e o painel de código funcionam apenas em modo foco, não na visualização dividida do canvas. E o recurso de arrastar e soltar formas ainda está a caminho, então por enquanto você adiciona formas com o botão + em uma forma existente ou com copiar, colar e duplicar.

O que realmente me empolga a seguir:

• Gerar e iterar diagramas Mermaid diretamente com Assistentes de IA e Flows, incluindo ler diagramas em formato livre como Mermaid diretamente do board
• Edição visual para diagramas ER e de classe
• Exportar como arquivo Mermaid nativo
• Formas mais fáceis de encontrar e corrigir erros no código, além de uma experiência de escrita de código mais confortável
• Comentários e anotações que os agentes realmente conseguem ler
• Suporte a layouts mais amplo, incluindo raias

O panorama geral

Isso importa além dos diagramas. É um exemplo real de agentes de IA e pessoas trabalhando no mesmo canvas, em vez de um agente apenas entregar um resultado estático e ir embora. Como o Mermaid permanece portátil, qualquer edição que você fizer na Miro é algo que seu agente pode entender e aproveitar. O agente pode retomar o diagrama que você já refinou e fazer uma alteração precisa nele, em vez de gerar tudo de novo e perder os detalhes que você acrescentou.

Daqui a um ano, quero que todos os engenheiros usem a Miro como parte genuína do seu fluxo de trabalho para compartilhar, colaborar e aperfeiçoar a arquitetura técnica, e não apenas como um lugar para guardar a imagem criada uma vez.

Se você levar só uma coisa disto: depois de gerar um diagrama diretamente da sua base de código em segundos, você não vai querer voltar a desenhá-lo à mão.

Pronto para experimentar? Abra a Creation bar, selecione Diagramas e gere seu primeiro diagrama Mermaid hoje.