Diagramas Mermaid: cómo creamos diagramación nativa con IA para ingenieros

¿No tienes tiempo?

Soy Hannah Knight, gerente de producto de Structured Diagrams with Mermaid en Miro. Quiero mostrarte qué son los diagramas Mermaid, por qué integramos soporte nativo de Mermaid en Miro y cómo usarlo hoy. Esta función está en Beta pública, así que seré sincera contigo sobre lo que funciona ahora mismo y lo que aún está por venir. Míralo en acción: una instrucción genera un mapa de todo un incidente directamente desde la base de código, mostrando cada servicio y cada llamada entre ellos. El equipo lo marca con colores para indicar qué falló, agrega comentarios directamente en el diagrama para trabajar en la solución y luego se lo entrega a un agente, que redacta toda la decisión como un pull request en GitHub. 

Qué es exactamente Mermaid

Entonces, ¿qué es un diagrama Mermaid? Es un diagrama descrito completamente en texto. Escribes algo como A --> B, y obtienes dos cuadros, A y B, conectados por una flecha. Eso es todo. Puedes usarlo para describir casi cualquier tipo de diagrama: diagramas de flujo, diagramas de secuencia, diagramas de clases, diagramas entidad-relación y más.

Los ingenieros han usado Mermaid durante años para mantener los diagramas en su base de código, justo junto al código que describen. Pero recientemente ha cobrado nueva vida por una razón simple: los modelos de lenguaje a gran escala son muy buenos generándolo. Pídele a un agente de IA que genere el diagrama de tu sistema, y es muy probable que te devuelva sintaxis Mermaid, porque ese es el formato que ha aprendido a escribir bien.

Esa combinación, código que tanto las personas como la IA pueden leer y escribir, es precisamente por eso que incorporamos soporte para Mermaid directamente en Miro.

El problema que seguía escuchando

Antes de que incorporáramos esto, Mermaid surgía una y otra vez en llamadas con clientes y en entrevistas con usuarios, de forma espontánea. Los ingenieros ya habían descubierto que los diagramas generados por la IA salían mejor cuando pedían Mermaid en lugar de una imagen. Los diagramas siempre han sido clave para que los ingenieros expliquen sistemas complejos de forma sencilla, y la combinación de Mermaid con la IA les permitía generar diagramas de alta calidad más rápido que si los hicieran a mano.

Esa distinción de "diagrama como código, no solo una imagen" importa por dos razones. Si un diagrama existe únicamente como imagen, un ingeniero no puede rastrear sus cambios de la misma manera que rastrea los cambios en el código. Y hay una segunda razón, más técnica: los modelos de lenguaje a gran escala entienden mucho mejor el texto unidimensional que las imágenes bidimensionales, por cómo procesan la entrada. Cuando un diagrama es código, un agente de IA puede hacer una edición precisa y dirigida en vez de regenerar todo desde cero.

He visto a ingenieros vivir exactamente este escenario con las herramientas antiguas. Su base de código cambia y ahora su diagrama está desactualizado. Entonces abren Miro, arrastran manualmente formas y cuadros para que coincidan con lo que realmente cambió, y luego lo documentan. Eso puede llevar horas.

Ahora pueden pedirle a un agente de codificación como Claude Code que genere un diagrama de la base de código, y se renderiza automáticamente en un tablero de Miro.

Por qué creamos Diagramas estructurados con Mermaid

Structured Diagrams with Mermaid introduce el diagrama como código directamente en Miro. Escribes o generas la sintaxis de Mermaid, se representa como formas nativas de Miro, tú y tu equipo la iteran juntos y la exportas de nuevo a código cuando terminas. Es un ciclo completo: un agente puede generar un diagrama a través del servidor MCP de Miro, tu equipo colabora en él visualmente, y otro agente puede leerlo de nuevo mediante MCP para mantener tu base de código sincronizada.

Mermaid es la fuente de verdad. Cuando editas un diagrama de forma visual en Miro, el código Mermaid subyacente se actualiza, de modo que el código y el diagrama nunca se desincronizan. Podríamos haber roto ese vínculo y tratar al diagrama como algo aparte una vez que aparece en el tablero, como hacen algunas otras herramientas. Decidimos no hacerlo. Mantener a Mermaid como la fuente de verdad significa que un agente de IA siempre puede entender tu diagrama y hacer ediciones precisas en él, y que puedes exportarlo a GitHub, VS Code, Obsidian o a cualquier otro lugar que lea Mermaid.

Esto reemplaza por completo la antigua app de Mermaid del Marketplace de Miro. Esa app generaba formas libres, no Mermaid real, y no permitía el ciclo de ida y vuelta: un agente podía generar un diagrama, pero no podía leer tus ediciones. Diagramas estructurados con Mermaid hace ambas cosas.

Qué ocurre cuando generas un diagrama

En términos sencillos, así es como se ve el ciclo de ida y vuelta: pega sintaxis Mermaid en un tablero de Miro y el diagrama se renderiza al instante. Pídele a un agente de IA, como Claude Code, Claude Cowork, Codex o Cursor, que genere un diagrama, y este usa el servidor MCP de Miro para escribir esa misma sintaxis Mermaid directamente en tu tablero. De cualquier modo, el diagrama aparece ya renderizado y listo, no como un boceto que tengas que retocar.

Qué tipos de diagrama se representan como formas nativas de Miro

Por ahora, cuatro tipos de diagrama se representan como formas nativas de Miro:

• Diagramas de flujo trazan flujos de trabajo, árboles de decisión y procesos, para que puedas ver exactamente dónde podría atascarse un proceso.
• Diagramas de secuencia muestran cómo los sistemas o componentes se comunican a lo largo del tiempo, lo cual es útil para la comunicación entre microservicios o el orden de llamadas a la API.
• Diagramas de clases visualizan objetos, sus atributos y cómo se relacionan entre sí.
• Diagramas entidad-relación (ER) representan el esquema de tu base de datos y las relaciones entre las tablas.

Hemos invertido mucho para que estos cuatro se vean bien desde el primer momento, de modo que obtengas algo listo para presentar sin trabajo de formato adicional.

Mermaid también admite muchos otros tipos de diagramas, incluidos los diagramas de Gantt y los diagramas C4 para arquitectura de sistemas. Estos actualmente se renderizan como SVGs de Mermaid.js en vez de como formas nativas de Miro. Aún puedes agregarlos a tu tablero, editarlos con IA y exportarlos, pero no lucen listos para presentación y no puedes entrar en ellos con un clic ni editarlos de forma visual como sí puedes con el diagrama de flujo. Si estás evaluando esto para tu equipo, esa distinción importa: debes saber qué diagramas podrán editarse de forma totalmente nativa hoy, y cuáles usarás principalmente para verlos y exportarlos.

Empieza con diagramas Mermaid en Miro

Así se ve esto en la práctica:

1. Abre la Creation bar, selecciona formatos, luego Diagram y haz clic en "Build with code".
2. Pega el código Mermaid que ya tengas, elige una plantilla o envía a tu agente una instrucción para generar un diagrama directamente desde tu base de código, mapeando cada servicio y cada llamada entre ellos en cuestión de segundos.
3. Obsérvalo renderizarse como formas nativas de Miro, con un diseño automático y ordenado, para que no tengas que espaciar manualmente las cajas y evitar que las líneas se crucen.
4. Abre el diagrama en modo sin distracciones para editarlo. Puedes seleccionar una forma, una línea o una etiqueta de texto y ajustarla directamente, cambiar la dirección del diseño (de arriba hacia abajo, de izquierda a derecha, etc.), o ajustar el espaciado de estrecho a amplio. También puedes abrir el panel de código y editar directamente la sintaxis Mermaid, o pegar el enlace del diagrama en tu herramienta de IA y pedirle a tu agente que haga el cambio por ti. De cualquier manera que lo edites, el código Mermaid y el diagrama se mantienen sincronizados.
5. Dale significado al diagrama. Usa colores para mostrar un estado o un incidente, o pídele a tu agente que haga el cambio. Cuando un agente edita un diagrama, incluso puede añadir una leyenda que marque lo que agregó, eliminó o cambió.
6. Invita a tu equipo a dejar comentarios directamente sobre el diagrama, en el contexto del estado actual y de la solución o cambio que propones, en lugar de iniciar un hilo aparte.
7. Cierra el ciclo. Copia la sintaxis de Mermaid de vuelta en tu base de código, exporta el diagrama como imagen (JPG, SVG o PDF), comparte un enlace de modo sin distracciones con tus colaboradores, o permite que tu agente lea el diagrama y los comentarios de tu equipo a través de MCP y redacte un documento, por ejemplo un registro de decisiones de arquitectura listo para abrir como pull request.

Si ya conoces la sintaxis de Mermaid, puedes empezar a escribirla de inmediato. Si nunca has usado Mermaid, comienza con una plantilla, edita las formas de forma visual, o simplemente descríbele a tu agente de IA lo que quieres y deja que escriba la sintaxis por ti. Algo que debes saber si estás en un plan Enterprise: un admin de empresa debe habilitar Miro MCP antes de que alguien de tu equipo pueda conectar una herramienta de IA.

Un error común al empezar

La gente intenta arrastrar las formas libremente, como lo harías en un lienzo normal de Miro, y no funciona así. Llamamos a estos "diagramas estructurados" porque están respaldados por código, y uno de sus principales beneficios es que Miro los organiza automáticamente. Si realmente necesitas más formas o movimiento totalmente libre, puedes cambiar un diagrama a edición libre, pero ten en cuenta que es una vía de no retorno: una vez que lo cambias, ese diagrama ya no está sincronizado con el código de Mermaid, y ni tú ni tu agente podrán editarlo a través de MCP. Si aún no estás seguro, empieza explorando las múltiples funciones que tenemos para los diagramas estructurados, o trabaja con una copia en modo libre en lugar de convertir el original.

Tampoco existe una única forma "correcta" de escribir Mermaid. No pienses demasiado en tu primer diagrama. Haz algo y luego itera, ya sea que lo edites tú, que un compañero de equipo lo perfeccione, o que un agente lo retome.

Código a gran escala, ¿cómo aguanta esto?

Soportamos archivos Mermaid de hasta 30 000 líneas de código, y hemos probado diagramas con 500 o más nodos en diagramas de flujo complejos sin pérdida de rendimiento. No hay un límite estricto en la cantidad de diagramas Mermaid que puedes tener en un tablero.

Cómo encaja con tus herramientas actuales

Si otra herramienta exporta sintaxis Mermaid, puedes pegarla directamente en un tablero de Miro. ¿Quieres mantener un diagrama bajo control de versiones? Expórtalo como archivo Markdown o .mmd y súbelo a tu repositorio, igual que versionarías cualquier otro código. Incluso puedes configurar un flujo de trabajo en el que tu agente genere el diagrama, lo exporte, lo suba al repositorio y lo actualice cada vez que cambie tu código, todo sin que tengas que tocarlo manualmente.

Ejemplos e inspiración de diagramas Mermaid

Nada de esto es útil en abstracto; a continuación, ejemplos de cómo los equipos lo están usando:

Onboarding de arquitectura.

En lugar de darle a un nuevo ingeniero una página de la wiki que está desactualizada desde el trimestre pasado, pídele a tu agente que diagrame la arquitectura actual de microservicios directamente desde la base de código. Así obtiene algo que refleje lo que realmente se está ejecutando, no lo que se ejecutaba hace seis meses.

Revisa un cambio en el esquema.

Antes de una migración importante, genera un diagrama ER del nuevo esquema para que los revisores puedan ver el cambio estructural de un vistazo, en lugar de desenredarlo a partir de un diff de texto.

Revisa un incidente, de principio a fin.

Diagrama los servicios afectados directamente desde la base de código en cuanto algo falle. Codifícalo por colores o añádele anotaciones para mostrar qué falló y por qué, luego invita a tu equipo a comentar directamente en el diagrama para trabajar en la solución. Cuando el equipo llegue a un acuerdo, pídele a tu agente que lea el diagrama y los comentarios a través de MCP y redacte la decisión como un documento, por ejemplo, un registro de decisiones de arquitectura listo para abrirse como pull request.

Documenta una API.

Genera un diagrama de secuencia de las llamadas de tu servicio, guarda el código Mermaid en tu repositorio y pídele a tu agente que lo actualice cada vez que la API cambie, en lugar de redibujarlo manualmente en cada versión.

Mapea el modelo de datos antes de construirlo.

Bosqueja un diagrama ER o de clases desde el inicio, mientras el modelo de datos sigue siendo solo una idea. Sale mucho más barato detectar una relación errónea en un diagrama que hacerlo después de haber escrito la migración.

Revisar un pull request.

Al revisar un pull request, pídele a tu agente que genere un diagrama Mermaid que muestre el estado del código antes y después para acelerar la incorporación. Con la IA, los ingenieros revisan muchos más cambios de código que antes, y las visualizaciones pueden acelerar este proceso.

Prácticas recomendadas para diagramas Mermaid

Deja que la IA escriba el primer borrador.

Si tu agente ya tiene el contexto, ya sea tu base de código, un conjunto de requisitos o un documento existente, pídele que genere el diagrama en lugar de escribir la sintaxis de Mermaid a mano. Refina a partir de ahí.

Ajusta tus expectativas a lo que se puede editar visualmente hoy.

Los diagramas de flujo son el tipo de diagrama más flexible en este momento. Los diagramas de secuencia, de clases y ER se representan de forma nativa y se ven bien, pero considéralos primero como código hasta que la edición visual también esté disponible para ellos.

Mantén los comentarios en el diagrama, no dispersos.

Comenta directamente en el diagrama en vez de iniciar un hilo paralelo en Slack o por correo electrónico. Así la decisión y el contexto quedan en un solo lugar, y tu agente puede leer toda la conversación a través de MCP.

Versiona tus diagramas como versionas tu código.

Exporta como Markdown o .mmd y haz commit. Es un hábito pequeño, y significa que el historial de tu diagrama es tan confiable como el historial de tu código.

Cuéntanos cuando falte algo

Si encuentras un problema de renderizado, o necesitas un tipo de diagrama que aún no se puede editar visualmente, dínoslo. Esta Beta existe precisamente para que comentarios como ese todavía puedan darle forma a lo que entregamos después.

Hablemos claro sobre la Beta

Esta es una Beta pública, y quiero ser transparente sobre en qué punto estamos. La edición visual funciona solo para diagramas de flujo por ahora; los diagramas de secuencia, de clase y ER se renderizan como formas nativas pero aún no admiten ese mismo flujo visual de edición mediante clic. La edición visual y el panel de código solo funcionan en el modo sin distracciones, no en la vista dividida del lienzo. Y la función de arrastrar y soltar para formas aún está en camino, así que por ahora agregas formas con el botón + en una forma existente, o usando copiar, pegar y duplicar.

Esto es lo que más me entusiasma a continuación:

• Generar e iterar diagramas Mermaid directamente a través de compañeros de IA y flujos, incluyendo leer diagramas en formato libre como Mermaid directamente desde el tablero
• Edición visual para diagramas ER y de clases
• Exportar como archivo Mermaid nativo
• Formas más sencillas de detectar y corregir errores en tu código, además de una experiencia de escritura de código más cómoda
• Comentarios y anotaciones que los agentes puedan leer
• Mayor soporte de diseño, incluidos los carriles

El panorama general

Esto importa más allá de los diagramas. Es un ejemplo real de agentes de IA y personas trabajando sobre el mismo lienzo, en lugar de que un agente te entregue un resultado estático y se vaya. Como Mermaid sigue siendo portátil, cualquier edición que hagas en Miro es algo que tu agente puede entender y sobre lo que puede trabajar. Puede retomar el diagrama que ya afinaste y hacerle un cambio preciso, en vez de volver a generar todo y perder los detalles que añadiste.

Dentro de un año, quiero que todos los ingenieros usen Miro como parte integral de su flujo de trabajo para compartir, colaborar y refinar la arquitectura técnica, no solo como un lugar para guardar una imagen creada una sola vez.

Si solo te llevas una cosa de esto: una vez que generes un diagrama directamente desde tu código en segundos, no querrás volver a dibujarlo a mano.

¿Listo para probarlo? Abre la barra de creación, selecciona Diagramas y genera tu primer diagrama Mermaid hoy.