Los diagramas de arquitectura tienden a envejecer rápido: se dibujan en una herramienta gráfica, se exportan y acaban olvidados en una carpeta de documentación. Para mantenerlos sincronizados con el código, una solución práctica es delegar su generación y actualización al propio agente del proyecto. Esa es la propuesta que describe un autor especializado en herramientas de desarrollo: conectar un MCP (protocolo de mensajería para editores) de Excalidraw con un agente que escriba, dibuje, revise y corrija el diagrama.
Qué cambia: del dibujo estático al fichero versionado
La novedad principal es integrar el proceso de dibujo en el flujo de desarrollo. En lugar de una imagen exportada que nadie actualiza, el diagrama pasa a formar parte del repositorio como un archivo vivo. El agente genera la representación en Excalidraw, la compara con el estado real del sistema, la corrige y guarda el resultado en el control de versiones. Así el diagrama obtiene historial, diffs claros y revisiones automatizables.
A quién afecta y por qué importa
- Equipos que mantienen servicios, microservicios o infraestructuras en evolución continua: evita la llamada «doc rot» (documentación que se pudre por abandono).
- Responsables de documentación y desarrolladores: reduce el tiempo perdido en actualizar diagramas manualmente tras cada refactor.
- Repositorios y pipelines CI: facilita renderizar diagramas en vistas o PDFs como parte del pipeline y revisar cambios con git.
Qué debe hacer el administrador o dueño de la web
Si se desea adoptar este enfoque se recomiendan pasos prácticos:
- Seleccionar una representación editable: Excalidraw permite guardar diagramas como JSON editables en el repositorio en lugar de imágenes estáticas.
- Conectar un agente o script al MCP de Excalidraw: el agente debe poder generar la estructura del diagrama (nodos y aristas), solicitar el render y aplicar correcciones.
- Integrar en el flujo de CI/CD: añadir pasos que validen y rendericen el diagrama, y que registren cambios como commits o merge requests.
- Adoptar Mermaid donde convenga: para diagramas sencillos en documentación (README, notas) Mermaid sigue siendo práctico porque produce diagramas a partir de texto y se versiona con git; sin embargo, su layout es automático y menos manipulable en lienzo.
El autor apunta que Mermaid sigue siendo la opción rápida y fiable para diagramas simples embebidos en Markdown, porque se editan como texto y aparecen en diffs. La combinación ideal depende del tipo de diagrama: Mermaid para diagramas textuales y reproducibles; Excalidraw + agente para diagramas visuales que deben conservar posición, colores y detalle del lienzo.
Limitaciones y consideraciones
No todos los proyectos justifican la complejidad añadida de un agente que gestione diagramas. Para proyectos pequeños, mantener diagramas en Mermaid o actualizarlos manualmente puede ser suficiente. Además, automatizar la conversión entre el estado del código y la representación gráfica requiere modelar qué componentes y relaciones se consideran «fuente de verdad».
En resumen, convertir los diagramas en ficheros vivos y gestionarlos desde el mismo repositorio reduce el mantenimiento invisible y hace que la documentación visual evolucione junto al código, mejorando trazabilidad y precisión.
Lee también:
- Omarchy 4.5 añade modo de escritorios flotantes y soporte para Apple Silicon
- Dokploy 0.31.0 añade transferencia de servicios entre servidores y otras mejoras clave
Fuente: atareao con Linux
