FlowBoardMermaid slop: cómo revisar y corregir los diagramas que te genera la IA antes de publicarlos
Equipo de FlowBoardRedactado con asistencia de IA16 min de lecturaEn resumen:
- "Mermaid slop" es el nombre que se ha popularizado en 2026 para los diagramas generados por IA que son válidos en sintaxis pero ilegibles o directamente falsos; el término salió del proyecto Diagram Design, que se presentaba con el lema "no Figma, no generic rounded boxes, no Mermaid-slop" y que ya superaba las 11.000 estrellas en GitHub en agosto de 2026 (explainX, 16-08-2026).
- El problema creció con la distribución: VS Code 1.121 (20-05-2026) renderiza Mermaid de forma nativa en la vista previa de Markdown, sin extensión, y los asistentes lo generan por defecto (Visual Studio Code).
- Un modelo optimiza validez gramatical, no corrección del sistema: el
.mmdparsea, pero duplica nodos, se deja la rama "no" de una decisión o invierte la dirección del dato. - Revisar un diagrama leyendo líneas de
-->no funciona: los defectos que importan son topológicos y solo se ven dibujados. - El ciclo que sí funciona: importar el
.mmda un lienzo, reordenar por capas, anotar lo dudoso con enlace al código o al ticket que lo demuestra, corregir a mano y volver a exportar para que la versión corregida sea la que entra al repositorio.
Desde mediados de 2026, la pregunta en los equipos de ingeniería ya no es cómo generar un diagrama, sino quién responde de él. Los agentes escriben Mermaid al vuelo, GitHub y VS Code lo pintan sin configuración y el resultado entra en el README con la misma naturalidad con que entra un bloque de código. Lo que falta es la capa de auditoría. Este artículo recorre los defectos típicos, el motivo técnico por el que aparecen y un ciclo de revisión reproducible que se cierra en un lienzo visual —en nuestro caso, FlowBoard, la pizarra infinita para diagramas de AIsToHire, que importa y vuelve a exportar Mermaid— para que el diagrama que se publica sea el corregido y no el primero que escupió el modelo.

¿Qué es exactamente el "Mermaid slop"?
Mermaid slop es un diagrama generado por IA que compila sin errores y aun así no sirve: cajas redondeadas idénticas para conceptos distintos, flechas sin etiqueta o con etiquetas vagas, colores por defecto que no dicen nada y una generación reflexiva —se dibuja porque se pidió, no porque haga falta—. La definición la fija el repaso de explainX sobre el término (16-08-2026), que lo rastrea hasta el proyecto Diagram Design de Cathryn Lavery.
El matiz importante es que hay dos capas de "slop" y se confunden a menudo:
| Capa | Qué falla | Se detecta | Coste de arreglarlo |
|---|---|---|---|
| Estética | Formas genéricas, paleta por defecto, todo igual | A simple vista | Bajo: tema, formas, agrupación |
| Semántica | El diagrama describe un sistema que no existe | Solo comparando con el código real | Alto: hay que reabrir el repositorio |
La conversación pública de 2026 se ha centrado casi toda en la primera. Las herramientas que han aparecido —desde las skills de diagramado editorial hasta los generadores que producen elementos nativos de Excalidraw en vez de texto Mermaid— atacan sobre todo el aspecto. La segunda capa, la que hace que un diagrama mienta sobre tu arquitectura, sigue siendo trabajo humano.
¿Por qué un LLM produce Mermaid perfecto en sintaxis y pobre en semántica?
Porque son dos objetivos distintos y solo uno tiene señal de entrenamiento abundante. La gramática de Mermaid es cerrada, pequeña y está masivamente representada en GitHub: un modelo la reproduce casi sin fallar. La corrección del diagrama, en cambio, depende de un sistema concreto que el modelo normalmente no ha leído entero, así que rellena los huecos con la forma más frecuente de un diagrama de arquitectura, no con la tuya.
A eso se suman tres efectos prácticos:
- El prompt es la única fuente. Si describes el sistema en tres frases, el agente devuelve un diagrama con la granularidad de tres frases y lo adorna hasta que parezca completo. Como resume la propia Mermaid al hablar de vibe diagramming, "un diagrama generado a partir de un prompt vago reflejará la vaguedad del prompt" (Mermaid, 24-03-2026).
- No hay compilador semántico. Un test rojo te avisa; un diagrama incorrecto renderiza igual de bonito que uno correcto. No existe el equivalente de
tscpara "este servicio no existe". - El layout lo decide el motor, no el autor. Mermaid coloca los nodos con su algoritmo y no te ofrece una forma cómoda de corregir la disposición después de renderizar. Si la jerarquía real no coincide con lo que el auto-layout dibuja, pierdes la discusión con la herramienta.
Y el contexto del sector dice que la verificación no es opcional. La encuesta a desarrolladores 2026 de Stack Overflow (publicada el 06-10-2026, más de 30.000 respuestas en 169 países) encontró que cerca de la mitad confía en la salida de la IA solo cuando puede verificarla con facilidad, y que apenas un 6,6 % la daría por buena para decisiones importantes. Un diagrama de arquitectura en la documentación oficial es, casi por definición, una decisión importante.
Los siete defectos recurrentes de un diagrama generado por IA
Estos son los siete que aparecen una y otra vez al auditar .mmd generados por agentes. Todos parsean; todos están mal. El patrón común es que el modelo rellena estructura plausible donde le falta información del dominio.

| # | Defecto | Síntoma en el .mmd | Consecuencia |
|---|---|---|---|
| 1 | Nodos duplicados | Dos IDs distintos con etiquetas parecidas para el mismo servicio | Parece que hay dos componentes donde hay uno |
| 2 | Decisión sin rama "no" | Un rombo con una sola arista de salida | El camino de error queda indocumentado |
| 3 | Flujo sin terminador | Cadenas que acaban en un nodo de proceso | No se sabe cuándo termina el caso de uso |
| 4 | Dirección invertida | La flecha apunta al origen del dato | Se invierte quién llama a quién |
| 5 | Caja genérica | Un único nodo "Base de datos" | Oculta tres almacenes con garantías distintas |
| 6 | Profundidad falsa | Capas o subgraph que no existen en el código | Da autoridad a una arquitectura inventada |
| 7 | Etiquetas del prompt | Los nodos repiten tus palabras, no el vocabulario del dominio | El diagrama no es buscable ni reconocible |
1. Nodos duplicados que son el mismo servicio
El modelo ha visto "auth" y "servicio de autenticación" en dos frases distintas y ha creado dos nodos.
flowchart LR
API[API Gateway] --> AUTH[Auth]
API --> AUTHSVC[Servicio de autenticacion]
AUTH --> DB[(Base de datos)]
AUTHSVC --> DB
Corregido: un nodo, un ID, el nombre que usa el equipo.
flowchart LR
API[API Gateway] --> AUTH[auth-service]
AUTH --> USERS[(postgres: users)]
2. Decisiones sin rama "no"
flowchart TD
REQ[Peticion] --> Q{Token valido?}
Q -->|Si| OK[Procesar]
Un rombo con una sola salida no es una decisión: es un adorno. Toda condición necesita sus dos caminos y el camino de error necesita destino.
flowchart TD
REQ[Peticion] --> Q{Token valido?}
Q -->|si| OK[Procesar]
Q -->|no| R401[Responder 401]
OK --> FIN([Fin])
R401 --> FIN
3. Flechas que invierten la dirección del dato
Clásico con colas y webhooks: el modelo dibuja la jerarquía organizativa en lugar del flujo real.
flowchart LR
WORKER[Worker] --> QUEUE[Cola de trabajos]
El worker no empuja a la cola: consume de ella. Dibujar mal este sentido convierte un diseño pull en uno push, que es otro sistema con otras garantías.
flowchart LR
API[API] -->|encola| QUEUE[Cola de trabajos]
QUEUE -->|consume| WORKER[Worker]
4. La caja genérica "Base de datos"
Es el defecto más caro, porque desaparece exactamente la información por la que alguien abre el diagrama. Un nodo [(Base de datos)] que en realidad son Postgres para transacciones, Redis para sesiones y S3 para adjuntos no documenta: oculta. La regla práctica: si dos almacenes tienen garantías de durabilidad distintas, son dos nodos.
5, 6 y 7: capas inventadas y etiquetas prestadas
Los subgraph llamados "Capa de presentación", "Capa de negocio" y "Capa de datos" suelen ser plantilla mental del modelo, no estructura de tu repositorio. Igual que las etiquetas: si el nodo se llama "módulo de procesamiento de pagos" y en el código es billing-worker, nadie podrá cruzar el diagrama con el proyecto. Y si falta el terminador, el lector no sabe si el flujo acaba ahí o el modelo se quedó a medias.
¿Por qué revisar un diagrama en texto no funciona?
Porque los defectos que importan son topológicos y el texto no los expone. Leyendo una lista de líneas A --> B puedes verificar que cada arista es plausible una por una, pero no vas a ver que dos flechas se cruzan, que un nodo quedó huérfano, que la jerarquía está invertida o que hay un ciclo de tres saltos. Esas propiedades solo son visibles cuando el grafo está dibujado y colocado.

Hay un segundo motivo, más sutil: al leer el .mmd revisas lo que el autor escribió; al mirar el render revisas lo que el lector va a entender. Son cosas distintas. Un diagrama con quince aristas correctas y un auto-layout que las amontona está técnicamente bien y comunicativamente roto, y es precisamente lo que un revisor de pull request aprueba sin mirar porque "el bloque mermaid está bien formado".
La propia industria se ha movido en esa dirección. Anthropic lanzó Claude Whiteboards en beta el 10-11-2026: un lienzo en tiempo real donde el asistente convierte una discusión en un tablero, agrupa notas por tema y permite llevarlo después a Lucid, Miro o Vani de Zoho (unite.ai). Y Miro, en su evento Canvas 26, declaró que ya "no está en el negocio de las pizarras" y que quiere ser "la capa de toma de decisiones colaborativa para la empresa agéntica" (Forrester, 01-06-2026). La salida natural de la IA se está volviendo el lienzo, no el bloque de texto. Para quien audita diagramas, eso es una buena noticia: la revisión pertenece al sitio donde se ve la forma.
El ciclo de revisión: del .mmd al lienzo y de vuelta al .mmd
El ciclo tiene cinco pasos y su propiedad clave es que cierra: lo que entra al repositorio es el diagrama corregido en el lienzo, no el original del agente. Si la corrección se queda en una captura de pantalla o en un comentario del pull request, el .mmd erróneo sobrevive y vuelve a alimentar al siguiente agente.

- Importar. Pega el
.mmdque te dio el agente en un lienzo visual, o cárgalo como archivo. Objetivo: separar la revisión del editor de código, donde la tentación es leer en vez de mirar. - Repartir y reordenar. Coloca los nodos en capas horizontales por responsabilidad (entrada, orquestación, dominio, almacenamiento). Casi todos los defectos de dirección y de profundidad falsa se delatan aquí: una flecha que sube dos capas suele ser una flecha invertida.
- Marcar lo dudoso. Cada nodo o conector que no puedas confirmar leyendo el código se anota, y la anotación lleva enlace a la prueba: el fichero, el ticket, el ADR. Un diagrama auditado no es uno sin dudas, es uno donde las dudas están etiquetadas y trazadas.
- Corregir a mano. Unificar nodos duplicados, partir la caja genérica en los almacenes reales, añadir la rama "no", cerrar con terminador, cambiar el tipo de forma para que un rombo sea rombo y un almacén sea cilindro, y reanclar los conectores a los puntos correctos.
- Exportar de vuelta. Volcar el resultado a
.mmdy sustituir el fichero original en el repositorio, en el mismo commit que la revisión. Ese es el paso que la mayoría de equipos se salta y el que evita que el error se reintroduzca.
En la práctica, el paso 3 es el que convierte esto en un proceso de ingeniería y no en una sesión de maquetado. Una nota lateral con un enlace al fichero concreto que demuestra que el worker consume de la cola es documentación verificable; "creo que esta flecha está al revés" en un hilo de Slack, no.
Checklist: 10 comprobaciones antes de hacer merge de un diagrama generado por IA
Lista cerrada, pensada para pegar en la plantilla de pull request. Si alguna falla, el diagrama no entra.
- Unicidad: ningún componente real aparece como dos nodos. Un ID por servicio, el nombre del repositorio o del despliegue.
- Decisiones completas: todo rombo tiene al menos dos aristas de salida, etiquetadas, y la rama de error tiene destino.
- Terminadores: todo camino acaba en un nodo terminal explícito; no hay cadenas que se corten en un paso de proceso.
- Dirección del dato: cada flecha va en el sentido en que viaja la información, no en el de la jerarquía organizativa. Revisa especialmente colas, webhooks y polling.
- Almacenes desagregados: ninguna caja genérica tipo "Base de datos", "Servicios" o "Infraestructura". Un nodo por almacén con tecnología y contenido.
- Capas reales: cada
subgraphcorresponde a un límite que existe (un despliegue, un repositorio, una cuenta, una red), no a una abstracción de manual. - Vocabulario del dominio: las etiquetas usan los nombres que el equipo escribe en el código y en los tickets, no las palabras de tu prompt.
- Sin huérfanos ni cruces evitables: ningún nodo desconectado, y los cruces que queden están justificados y no se arreglan reordenando.
- Legible al tamaño en que se publica: se entiende en el ancho del
READMEo del portal de documentación, no solo con zoom. - Trazabilidad: cada elemento no obvio tiene una nota con enlace al código, al ticket o al ADR que lo respalda; y el
.mmddel repositorio es el exportado tras la corrección.
Spec-driven development: si el diagrama está mal, el código hereda el error
Esta es la razón por la que la auditoría dejó de ser cosmética en 2026. En el desarrollo dirigido por especificación, la especificación en Markdown —con sus diagramas Mermaid de arquitectura y de secuencia— es el artefacto del que el agente genera la implementación, no un comentario sobre ella. Un diagrama incorrecto dentro de esa especificación ya no es documentación desactualizada: es una entrada defectuosa en un generador de código.
El planteamiento está recogido en el propio Spec Kit de GitHub, cuya tesis es que "las especificaciones no sirven al código; el código sirve a las especificaciones", y los planes de implementación que produce incluyen diagramas de arquitectura y de secuencia en Mermaid junto al modelo de datos y los modos de fallo.
Traducido al día a día: un rombo sin rama "no" en la especificación es, con bastante probabilidad, un caso de error sin implementar en el código generado. Una flecha invertida entre API y cola es un diseño push donde querías pull. Y una caja "Base de datos" que tapaba Postgres, Redis y S3 se convierte en un repositorio único con tres responsabilidades. El diagrama pasó de ser la foto del sistema a ser parte del plano, y los planos se revisan.
Preguntas frecuentes
¿Qué significa "Mermaid slop"?
Es un diagrama generado por IA con sintaxis Mermaid válida pero sin valor comunicativo: formas genéricas e idénticas, paleta por defecto, flechas mal etiquetadas y, en los casos peores, componentes o relaciones que no existen en el sistema. El término se popularizó a partir del proyecto Diagram Design y lo documenta el repaso de explainX de agosto de 2026.
¿Se puede validar automáticamente un diagrama Mermaid generado por IA?
Solo en parte. Un linter o el propio parser detecta errores de sintaxis, y se pueden automatizar comprobaciones estructurales: nodos huérfanos, rombos con una sola salida, caminos sin terminador o IDs con etiquetas sospechosamente parecidas. Lo que ninguna herramienta puede verificar sola es si el diagrama describe tu sistema; eso exige cruzarlo con el código, y por eso el checklist de este artículo mezcla comprobaciones automatizables con revisión humana.
¿Por qué no basta con revisar el bloque mermaid en el pull request?
Porque en el diff lees aristas una a una y los defectos relevantes son del grafo completo: cruces, jerarquías invertidas, ciclos, nodos aislados, densidad ilegible. Además, al leer el texto evalúas la intención del autor y no lo que verá el lector del render. La revisión útil se hace sobre el diagrama dibujado.
¿Qué herramienta uso para corregir un diagrama Mermaid a mano?
Necesitas un lienzo que haga el viaje completo: importar el .mmd, dejarte mover y cambiar formas y conectores, anotar elementos y exportar otra vez a Mermaid. Ese último paso es el que descarta la mayoría de visores, que renderizan pero no devuelven el código corregido. FlowBoard cubre el ciclo: importa Mermaid desde archivo o pegando el código, reparte el diagrama en un lienzo infinito con zoom y desplazamiento, permite corregir formas, conectores y anclajes a mano con magnetismo a los puntos de anclaje, añadir notas laterales con enlaces por elemento y exportar de vuelta a Mermaid.
¿Cuánto tarda auditar un diagrama generado por IA?
Depende del tamaño, pero el orden de magnitud para un diagrama de 15-25 nodos es de 20 a 40 minutos la primera vez, y bastante menos cuando el equipo ya tiene el checklist interiorizado y los nombres del dominio fijados. Comparado con el coste de que una arquitectura equivocada entre en la documentación oficial —o, en un flujo dirigido por especificación, en el código generado—, es barato.
¿Hay que dejar de usar IA para hacer diagramas?
No. Generar el primer borrador con un agente ahorra el trabajo tedioso de teclear nodos y aristas, y para explorar un sistema desconocido es útil. Lo que no debe saltarse es el paso siguiente: ningún diagrama generado por IA se publica sin pasar por el lienzo y por el checklist. La IA hace el borrador; la responsabilidad del diagrama sigue siendo del equipo que lo firma.
Cierre: el diagrama que publicas es el que has auditado
El cambio de 2026 no es que la IA dibuje diagramas, es que los dibuja más rápido de lo que los revisamos. Mientras VS Code los pinta sin configuración, Claude los convierte en tableros y las especificaciones en Markdown alimentan generadores de código, el único control de calidad que queda es el humano: mirar la forma, marcar lo que no se puede demostrar y devolver al repositorio la versión corregida. Diez comprobaciones y un ciclo que cierra bastan para que un diagrama vuelva a ser documentación fiable en lugar de decoración plausible.
Ese ciclo necesita un sitio donde ocurrir. En AIsToHire lo resolvemos con FlowBoard, nuestra pizarra infinita para diagramas: se pega o se importa el .mmd del agente, se reparte en un canvas infinito, se recolocan formas —rectángulos, elipses, rombos de decisión, documentos, notas adhesivas y texto— y conectores con flechas rectas u ortogonales, se ancla cada conexión con magnetismo a los puntos de los elementos, se anota lo dudoso con notas laterales y enlaces de verificación, y se exporta de vuelta a Mermaid. El tablero se guarda solo, así que la auditoría queda registrada y se puede retomar.
Abre FlowBoard, pega el .mmd que te dio el agente y audita el diagrama donde se ve de verdad: reordena por capas, corrige formas y conectores a mano, anota lo dudoso con enlaces de verificación y expórtalo de vuelta a Mermaid. Empieza tu primer tablero gratis.
Abre FlowBoard, pega el .mmd que te dio el agente y audita el diagrama donde se ve de verdad: reordena por capas, corrige formas y conectores a mano, anota lo dudoso con enlaces de verificación y expórtalo de vuelta a Mermaid. Empieza tu primer tablero gratis.Sigue leyendo
Ver todos los artículos →
Símbolos de un diagrama de flujo: qué significa cada uno y cómo dibujar el tuyo paso a paso

Discutir por WhatsApp o hablarlo en persona: qué dice la ciencia sobre los conflictos de pareja por mensajes

Mapa mental, mapa conceptual y esquema: diferencias y cuándo usar cada uno
