Los diagramas mueren por una razón aburrida: solo tienen una forma, y es la equivocada para al menos la mitad de lo que necesitas. Un dibujo es genial para quien lo lee e inútil en un pull request. Un bloque de código de diagrama se revisa de maravilla y no le comunica nada a una persona de negocio. Así que los equipos eligen uno, y la otra necesidad queda sin cubrir hasta que el diagrama se queda atrás y todo el mundo deja de confiar en él.
La solución no es elegir. Es mantener ambas formas y moverse libremente entre ellas. El código se convierte en diagrama cuando quieres verlo; el diagrama se convierte en código cuando quieres revisarlo o guardarlo. La IA suaviza el viaje en ambas direcciones, y la ida y vuelta es lo que hace que el diagrama perdure.
Dirección uno: del código al diagrama
Ya tienes texto que describe estructura, ya sea Mermaid, D2 o un artefacto como un archivo de Compose o un esquema SQL. Impórtalo y se convierte en formas reales y editables, ya organizadas. Ahora puedes hacer lo que el texto no puede: resaltar la ruta arriesgada, agrupar un contexto acotado, dejar una nota donde está la parte delicada.
graph LR
client --> api
api --> cache
api --> db
worker --> queue
Pégalo y no obtienes una imagen renderizada; obtienes un conjunto de cajas y flechas que puedes coger y mover. El código te dio la estructura gratis. Tus ediciones añaden el significado.
Dirección dos: exportar el diagrama a código
Ahora al revés. Has dado forma a un diagrama en el lienzo y lo quieres en el repositorio, junto al código que describe, donde se pueda revisar y versionar. Expórtalo de nuevo a Mermaid o D2 y haz commit del texto. La próxima vez que alguien abra un pull request que cambie el sistema, el código del diagrama cambia en la misma revisión, bajo los mismos ojos.
Dónde ayuda la IA en la ida y vuelta
Ambas direcciones se vuelven más fáciles con un modelo en el ciclo, pero no como sugiere el bombo publicitario. La IA no está ahí para sustituir el código ni el dibujo. Está para salvar los huecos más desordenados:
- De una entrada imprecisa a código limpio. Describe un flujo en una frase y obtén una primera versión de código de diagrama que puedes renderizar y refinar.
- De un diagrama desordenado a código ordenado. Pide que el texto exportado se simplifique o se reetiquete para que la versión que subes se lea bien.
- De la desviación a un borrador nuevo. Cuando el sistema ha cambiado, regenera desde la fuente actual y concilia, en lugar de parchear a mano una imagen vieja.
Dos formas de una misma verdad. El código la mantiene revisable; la imagen hace que se lea.
Por qué esto es mejor que elegir bando
El diagrama de una sola forma obliga a un mal intercambio. El diagrama como código por sí solo te da revisabilidad y una imagen que nadie disfruta leyendo. Un dibujo por sí solo te da una imagen amable que se aleja del código en silencio. Mantener ambos, con una ida y vuelta sencilla, te da la revisabilidad del texto y la claridad de un visual desde la misma fuente. Ninguno de los dos es ciudadano de segunda.
El hábito que vale la pena crear
Trata las dos formas como un único artefacto con dos vistas. Haz el borrador en la que sea más rápida en ese momento, bocetando visualmente o escribiendo la estructura, y luego haz la ida y vuelta para obtener la otra forma gratis. Hazlo de forma constante y el eterno problema del diagrama desactualizado casi desaparece, porque siempre hay un camino barato de vuelta a lo correcto.
Pega algo de código de diagrama y dale forma, o dibuja algo y exporta el código. Cuando hayas probado la ida y vuelta, mantener un diagrama al día deja de ser una tarea que te saltas.