Mermaid frente a un lienzo de diagramas: cuándo funcionan los diagramas como código y cuándo no

Pocos debates sobre herramientas duran tanto en los equipos de ingeniería como este. Algunos quieren cada diagrama como código, en Mermaid, revisado en pull requests. Otros quieren un lienzo donde mover cajas y ver el sistema. Los dos bandos tienen razón, pero sobre diagramas distintos.

Esta guía compara Mermaid y un lienzo de diagramas con honestidad: qué hace bien cada uno, dónde falla cada uno, una tabla de decisión para los casos habituales y el mismo sistema pequeño dibujado de las dos formas.

Lo que Mermaid hace bien

Mermaid convierte unas pocas líneas de texto en un diagrama. Eso tiene ventajas reales:

• Vive junto al código. Un diagrama en un archivo Markdown cambia en el mismo pull request que el código que describe, y quienes revisan ven el diff.
• Se renderiza donde ya están los ingenieros. GitHub y GitLab renderizan los bloques de código Mermaid en archivos Markdown, issues y pull requests, y herramientas como Notion y Obsidian también los muestran.
• Sin herramientas ni cuentas extra. Cualquiera que pueda editar el archivo puede editar el diagrama.
• Los diagramas de secuencia son excelentes. Para un flujo de peticiones entre cuatro servicios, la sintaxis de secuencia de Mermaid es difícil de superar.
• Los asistentes de IA lo escriben con soltura. Pide a cualquier asistente de chat un diagrama de flujo en Mermaid y la mayoría de las veces obtendrás una sintaxis válida.

Dónde se queda corto Mermaid

• No controlas el layout. Mermaid coloca los nodos automáticamente. Añade una conexión y la imagen puede reorganizarse sola, y a partir de un par de docenas de nodos se vuelve difícil de leer.
• Los diffs de texto ocultan los cambios visuales. Un cambio de una línea en un pull request puede mover medio diagrama, y quienes revisan solo ven la línea.
• El vocabulario se queda corto para la infraestructura. Las formas del diagrama de flujo son genéricas. Existen tipos de diagrama más nuevos para arquitectura y C4, pero están menos maduros que los diagramas de flujo y de secuencia.
• Quienes no son ingenieros rara vez lo editan. Los product managers, diseñadores y equipos de soporte pueden leer el resultado, pero normalmente no cambian el código fuente.
• No hay una sesión compartida en vivo. Editas texto en tu editor; no hay cursores, ni revisión en vivo, ni nadie viendo cómo llega un cambio.

Lo que un lienzo hace bien

• El layout es tuyo. La posición transmite significado: el borde de una zona de confianza, el flujo de una petición de izquierda a derecha, el clúster del centro.
• Nodos tipados y marcos. En un lienzo como Archboard, un Service de Kubernetes o un contenedor C4 es un nodo con puertos, y los namespaces o las VPC son marcos que agrupan su contenido.
• Todos pueden editar. Quien nunca abre el repositorio puede igualmente corregir una etiqueta o añadir una nota.
• Colaborar y compartir en vivo. Varias personas, y también agentes de IA, editan a la vez con cursores, y un enlace en vivo o un embebido mantiene a cada lector en la versión actual.

Dónde se queda corto un lienzo

• Se desvía del código a menos que actualizarlo forme parte de tu flujo de trabajo. Por defecto, un lienzo no está en el pull request.
• Algunos formatos son opacos. Un PNG o un archivo propietario no se pueden comparar con un diff ni generar. Archboard lo mitiga con la exportación JSON y un JSON Schema publicado, pero un documento JSON sigue sin ser un bloque Markdown de diez líneas.
• Necesita una herramienta. Los lectores pueden ver un enlace para compartir sin cuenta, pero quienes editan sí la necesitan.

Una tabla de decisión

El patrón: Mermaid gana cuando el diagrama pertenece a un cambio y vive en el código. Un lienzo gana cuando el diagrama pertenece al equipo y sobrevive a cualquier cambio concreto.

El mismo sistema, de las dos formas

Este es un sistema pequeño en Mermaid:

flowchart LR
  user([Customer]) -->|HTTPS| web
  subgraph shop [Online shop]
    web[Web app] -->|JSON| api[Orders API]
    api -->|SQL| db[(Orders DB)]
    api -->|OrderPlaced| q[[order-events]]
    q --> worker[Email worker]
  end
  worker -->|SMTP| mail[Email provider]

Es legible, sus diffs se leen bien y GitHub lo renderiza. Ahora, el mismo diagrama de flujo en un lienzo. Se lo dimos a un agente de IA conectado a Archboard por MCP, con una correspondencia entre los ids de Mermaid y los tipos de nodo: user a una persona C4, web, api y worker a contenedores C4, db a Postgres, q a un Tema (topic), mail a un sistema externo. El agente lo dibujó en un paso, y un segundo paso lo organizó en dos filas:

El subgraph se convirtió en un marco, los nodos en nodos tipados con puertos, y el resultado es un punto de partida que ahora puedes organizar, anotar y compartir como cualquier otro diagrama.

Usa los dos, de forma deliberada

Un reparto que funciona para la mayoría de los equipos:

1. Mermaid para los diagramas que pertenecen a un cambio: diagramas de secuencia en documentos de diseño y pull requests, máquinas de estados junto al código, diagramas de flujo pequeños en los README.
2. Un lienzo para los diagramas que pertenecen al equipo: visiones generales del sistema, infraestructura, revisiones de seguridad, onboarding.
3. Conéctalos. Parte de Mermaid cuando ya lo tengas: un agente conectado a Archboard por MCP puede convertir un diagrama de flujo Mermaid en un diagrama de lienzo con tipos de nodo reales. Exporta el lienzo como JSON al repositorio cuando quieras revisarlo junto con el código, y enlaza el diagrama en vivo desde el README.

Preguntas frecuentes

¿Puedo pegar Mermaid en el editor de Archboard? Hoy no directamente. Un agente de IA conectado por MCP puede dibujar un diagrama de flujo Mermaid, subgraphs incluidos, como un diagrama de lienzo con tipos de nodo reales. Los demás tipos de diagrama de Mermaid, como los diagramas de secuencia, no se convierten.

¿Un diagrama de lienzo aparece en los pull requests? No por sí solo. Expórtalo como JSON o SVG al repositorio si quieres que se revise junto con el código, o enlaza el diagrama en vivo desde el pull request.

¿Los diagramas como código están siempre más actualizados? Solo si alguien los actualiza. Un bloque Mermaid que nadie toca se queda desactualizado tan rápido como un lienzo; la diferencia es que está más cerca del cambio que debería actualizarlo.

¿Y PlantUML o Structurizr? Las mismas ventajas y desventajas. PlantUML destaca en UML y diagramas de secuencia; Structurizr está pensado para modelos C4 como código. Elige según quién edita el diagrama y cuánto tiempo tiene que vivir.

¿Cuál manejan mejor los asistentes de IA? Los dos. Los asistentes escriben Mermaid con soltura y, mediante MCP, un agente también puede editar un lienzo directamente, donde las personas ven el cambio en vivo y pueden deshacerlo.

Empieza gratis — un puesto, sin tarjeta de crédito.