Dejé de dibujar diagramas a mano

Si llevas tiempo construyendo software conoces esta molestia: pasas un par de horas acomodando cajitas en Figma o en draw.io, queda precioso, y dos semanas después el código cambia. El diagrama no queda desactualizado. Queda mintiendo, que es bastante peor.

Llevo años viendo el mismo ciclo en equipos distintos. Alguien dibuja la arquitectura para un design review, el review pasa, y el diagrama se queda en una carpeta de Drive envejeciendo en silencio hasta que un dev nuevo lo abre y construye su modelo mental sobre algo que ya no existe.

Hace poco me crucé con Archify buscando cómo conectar mis agentes con la generación de documentación visual, y cambió lo suficiente mi flujo diario como para que valga la pena escribirlo.

El problema no es dibujar, es mantener

Vale la pena separar las dos cosas, porque casi todas las herramientas atacan la primera y ninguna la segunda.

Dibujar es barato. Lo caro es que el dibujo siga siendo verdad. Cada editor visual que he usado optimiza para que la primera versión salga bonita, y ninguno para que la versión número doce siga correspondiendo con el repositorio.

Qué es Archify

Es un agent skill: se instala en Cursor, Claude Code, Codex CLI u OpenCode y le da a tu agente la capacidad de generar diagramas. Le describes el sistema en lenguaje natural y devuelve un HTML interactivo y autocontenido.

Por dentro no salta del texto al dibujo. Compila a una representación intermedia en JSON tipado, la valida, y desde ahí renderiza de forma determinista. Eso importa más de lo que suena: significa que la misma descripción produce el mismo diagrama, y que un JSON inválido falla en vez de inventarse una caja.

Soporta cinco tipos:

• Arquitectura: componentes, servicios, almacenamiento y límites de confianza.
• Workflow: pipelines de CI/CD, aprobaciones, llamadas a herramientas.
• Secuencia: llamadas a APIs, fallback de caché, trazas asíncronas.
• Flujo de datos: pipelines, linaje, seguimiento de PII.
• Ciclo de vida: estados, reintentos, esperas y desenlaces terminales.

De salida entrega HTML autocontenido, PNG (incluida una tarjeta de 1200x630 para compartir), SVG y WebM.

Lo que me hizo quedarme

No fue que genere diagramas limpios. Eso ya lo hacen varias herramientas.

Fue que un nodo puede marcarse como SRC y abrir el archivo real del repositorio, verificado contra git y fijado a un commit concreto. El diagrama deja de ser una interpretación de la arquitectura y pasa a apuntar a la evidencia que la sostiene.

Hay una segunda cosa que no esperaba: compara dos snapshots, antes y después, y emite un recibo legible por máquina con lo que se agregó, se quitó, cambió, se movió o se re-enrutó. Eso es exactamente lo que quiero leer en la descripción de un PR que toca la arquitectura, y es justo lo que nadie escribe a mano.

Las capturas de este post salen del repositorio del proyecto, que es MIT.

Cómo lo integré

Instalarlo me tomó menos de un minuto. Lo agregué como skill global para todos mis agentes:

# Instalación global
npx skills add tt-a1i/archify -g

# O probarlo sin instalar nada, directo con Codex CLI
npx skills use tt-a1i/archify@archify --agent codex

Ahora, cuando estoy diseñando una API nueva o refactorizando un módulo, se lo pido al agente en el mismo chat donde ya estoy trabajando:

Archify: genera un diagrama de secuencia para el flujo de autenticación JWT, incluyendo el cliente React, el API Gateway en Node, el servicio de Auth y la caché de Redis para tokens revocados.

Y devuelve esto:

La diferencia real no es la velocidad. Es que el diagrama vive donde vive el código, y regenerarlo cuesta una frase en vez de una tarde.

Lo que todavía no resuelve

Nada de esto lo hace automático. El diagrama sale tan bueno como la descripción que le des, y describir bien un sistema sigue siendo el trabajo difícil. Si tu prompt es vago obtienes un diagrama vago y bien renderizado, que es una trampa peor que no tener diagrama.

Tampoco lee tu repositorio y deduce la arquitectura solo. El enlace al código lo pones tú cuando pides evidencia. Sigue habiendo un humano decidiendo qué importa.

Y es un proyecto joven. Lo estoy usando para diagramas del día a día y para documentar PRs. Todavía no lo pondría como única fuente de verdad de la arquitectura de una plataforma completa.

Conclusión

Me devolvió el tiempo que perdía moviendo cajitas y flechas. Pero lo que de verdad me interesa es otra cosa: por primera vez el diagrama está lo bastante cerca del código como para que actualizarlo no sea una tarea que se posterga.

Un diagrama desactualizado es deuda técnica que nadie registra en el backlog. Cualquier herramienta que baje el costo de mantenerlo vivo me parece que vale la pena mirar.