Archify: cómo revisar diagramas de arquitectura con IA
Un agente puede generar un diagrama de arquitectura en minutos: cajas, flechas y una imagen lista para acompañar un pull request. El problema aparece cuando alguien pregunta qué respalda una de esas conexiones y el diagrama no permite responderlo.
Un resultado visualmente convincente puede representar una relación que el sistema no tiene. Por eso, antes de utilizarlo en una revisión técnica, conviene comprobar qué información recibió el agente, qué supuestos incorporó y qué evidencia respalda lo dibujado.
En este artículo exploramos esa práctica con Archify, una herramienta de código abierto con licencia MIT. Usaremos dos ejemplos hipotéticos para distinguir qué valida la herramienta, qué debe revisar el equipo y qué información conviene conservar.
Validar un diagrama no equivale a auditar una arquitectura
Al revisar un diagrama generado con IA, conviene separar tres aspectos:
Un diagrama válido puede contener una relación incorrecta. Que el archivo pase los controles de la herramienta no demuestra que una conexión exista en el código o en la infraestructura.
Cuando se incorpora evidencia del código, Archify también puede verificar que los archivos y los rangos de líneas citados existan en un commit determinado. Aun así, corresponde al equipo evaluar si esas referencias justifican la relación y si la representación es adecuada para la revisión.
Qué hace Archify
Archify trabaja con un flujo de tres pasos:
- Generate: el agente crea un archivo JSON que describe el diagrama.
- Validate: la herramienta comprueba que el archivo cumple las reglas aplicables.
- Deliver: si supera los controles, genera un HTML autocontenido que puede abrirse sin servidor.
Para instalar la habilidad:
npx skills add tt-a1i/archify -gUna vez instalada en un agente compatible, se puede solicitar el diagrama desde su chat. No es necesario ejecutar manualmente los comandos para cada pedido. Las utilidades doctor, validate y deliver permiten diagnosticar problemas o integrar el flujo en otros procesos.
Las opciones de instalación dependen del entorno, por lo que conviene revisar la documentación del proyecto antes de comenzar.
Los ejemplos de este artículo se generaron el 7 de octubre de 2026 con Archify v3.0.1, commit 2ab3cae. Los diagramas se presentan aquí como imágenes estáticas.
Ejemplo básico: caché y base de datos
El primer ejemplo parte de un pedido breve incluido en el README de Archify:
Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.Se trata de un escenario hipotético con cuatro componentes: navegador, API, Redis y PostgreSQL.
El navegador llama a la API. La API consulta Redis y, si no encuentra el dato, consulta PostgreSQL.
Este ejemplo permite observar una primera decisión del agente. Aunque el pedido encadena Redis cache -> PostgreSQL fallback, el resultado conecta ambos componentes con la API.
Esa interpretación puede ser razonable para el escenario, pero sigue siendo una decisión que debe hacerse explícita y revisarse. Si el objetivo fuera documentar un sistema existente, habría que comprobar en su implementación quién realiza cada consulta.
La pregunta útil es: ¿esta conexión proviene de una fuente o de una interpretación del agente?
Checkout: representar un flujo sin inventar conexiones
El segundo ejemplo representa un checkout. También es hipotético y no corresponde a la arquitectura de un cliente.
Una instrucción demasiado abierta puede llevar al agente a incorporar conexiones que no queremos representar. Para delimitar el resultado, se utilizó este pedido:
Mapa de runtime del checkout. Máximo 12 nodos.
Clientes → gateway → orquestador. El orquestador publica al bus.
Participantes: stock, cobro, envío. Webhook de canales al orquestador.
No dibujes REST orquestador → cobro. JWT solo en gateway e orders.
Soporte en cards.En el diagrama, orders es el componente denominado “orquestador”. El pedido entra por el gateway y orders publica pedido.creado en el bus.
Para la lectura del ejemplo, stock, cobro y envío consumen ese mismo evento. Las etiquetas reservar, cobrar y enviar describen la acción de cada servicio; no representan tres eventos diferentes ni órdenes emitidas por el bus.
Vista parcial del checkout. No incluye confirmaciones, compensaciones ni la coordinación completa del proceso. Las conexiones JWT contienen un supuesto pendiente de confirmar, explicado más adelante.
Las líneas continuas representan llamadas directas. Las punteadas se utilizan para eventos, el webhook y relaciones de identidad; sus etiquetas permiten distinguirlas.
Una restricción central del ejemplo es que no exista una llamada REST directa de orders a payment. El webhook de los canales, por su parte, debe llegar a orders y no al gateway.
Cómo se revisó el resultado
El agente recibió el pedido anterior, sin acceso a código. Primero, Archify validó el artefacto. Después, se contrastaron algunas restricciones del pedido con las conexiones descritas en el JSON.
Estos objetos corresponden a tres conexiones del JSON. Se omiten los campos de posición de las etiquetas:
[
{
"id": "orders-bus",
"from": "orders",
"to": "bus",
"label": "pedido.creado",
"variant": "dashed"
},
{
"id": "bus-payment",
"from": "bus",
"to": "payment",
"label": "cobrar",
"variant": "dashed"
},
{
"id": "gateway-idp",
"from": "gateway",
"to": "idp",
"label": "JWT",
"variant": "security"
}
]Los fragmentos permiten inspeccionar esas conexiones. Para comprobar que no existe otra relación —como una llamada directa de orders a payment— es necesario revisar el archivo completo.
Qué confirmó el validador
La validación del archivo completo con el perfil showcase produjo el siguiente resultado resumido:
ok: true
command: validate
type: architecture
Controles reportados:
single_svg, finite_svg, orthogonal_arrows,
label_route_clearance, relationship_crossings,
relationship_corridors, container_border_runs,
route_rhythm, legend_clearance
Resultado de esos controles: ok: true
composition:
profile: showcase
status: pass
errors: 0
warnings: 0Este bloque resume la salida del validador; no reproduce literalmente su JSON.
Los controles comprueban aspectos de estructura y representación: por ejemplo, la geometría de las flechas y la separación entre etiquetas y recorridos. No verifican que las relaciones existan en un sistema real.
Para comprobar esa diferencia, se agregó manualmente al JSON una flecha REST orders → payment, expresamente prohibida en el pedido.
En esta prueba, el perfil standard aceptó el archivo con cero errores y una advertencia de composición. El perfil showcase lo rechazó por un solapamiento de etiquetas, no por contradecir la restricción arquitectónica.
La prueba muestra por qué la validación automática debe complementarse con una revisión de lo que significa cada conexión.
Un supuesto detectado: las conexiones JWT
El pedido indicaba “JWT solo en gateway y orders”, pero no definía el mecanismo de validación.
El agente dibujó una conexión desde cada componente hacia el proveedor de identidad, identificado como IdP. Esa representación puede interpretarse como una consulta al IdP, aunque la instrucción no especificaba ese comportamiento.
El diagrama tampoco permite determinar si los servicios validan el token localmente o realizan una consulta remota.
Por eso, el mecanismo se dejó como supuesto pendiente de confirmar. No se consideró validado por el simple hecho de que las flechas aparecieran en los componentes solicitados.
En un sistema real, esa duda debería resolverse consultando la implementación, la configuración o una decisión de arquitectura documentada. Mientras tanto, la incertidumbre debe permanecer visible para quien revise el mapa.
Qué demuestra esta revisión y qué queda pendiente
La revisión comprobó algunas relaciones contra el pedido original. No verificó su correspondencia con código ni con un sistema en ejecución.
Para avanzar hacia esa comprobación habría que revisar, entre otros puntos:
- Dónde y bajo qué condiciones
orderspublicapedido.creado. - Qué configuración o implementación demuestra que
paymentconsume ese evento. - Cómo se valida el token en el gateway y en
orders. - Qué ocurre cuando alguna etapa falla y cómo se coordina la continuidad del proceso.
El ejemplo sirve para practicar una revisión y detectar supuestos. No constituye una arquitectura de checkout lista para implementar.
Qué evidencia conviene guardar
Para que otra persona pueda repetir la revisión, conviene conservar junto al diagrama:
- El JSON completo, la versión de Archify utilizada y la salida del validador.
- El pedido original y las fuentes que recibió el agente.
- Las relaciones revisadas, indicando el archivo, configuración o decisión que respalda cada una.
- Los supuestos pendientes, claramente diferenciados de las relaciones comprobadas.
Cuando las fuentes sean archivos de un repositorio, identificar el commit permite conservar el contexto exacto de la revisión.
Cuándo conviene usar Archify
Archify puede resultar útil cuando el equipo necesita mantener una fuente editable del diagrama, revisar sus relaciones y conservar el resultado junto al código.
Para una vista de alto nivel, la documentación propone concentrarse en unos ocho a doce componentes y un recorrido principal. Es una orientación para facilitar la lectura, no una regla universal.
También permite comparar versiones de una arquitectura y representar cambios. Esa comparación no determina, por sí sola, el impacto operativo ni si una modificación es segura para producción.
Entre los límites de la versión utilizada:
- No interpreta automáticamente diagramas Mermaid.
- No ofrece un editor visual general ni alojamiento de los mapas.
- No inspecciona infraestructura en ejecución.
- El comando
guideorienta sobre el tipo de diagrama, pero no lo genera.
La elección del tipo de diagrama también importa. Arquitectura, workflow, secuencia, flujo de datos y ciclo de vida responden preguntas diferentes. Un mapa de componentes puede ser válido y, aun así, resultar insuficiente para explicar el orden de las llamadas.
Cómo se ubica frente a otras herramientas
La elección depende del artefacto que necesita el equipo:
Archify no reemplaza un modelo BPMN ni interpreta Mermaid. Su aporte debe evaluarse según el flujo de trabajo y el resultado que se busca.
En todos los casos existe trabajo humano de definición, revisión y mantenimiento. Este ejercicio no midió diferencias de costo entre las herramientas.
Qué debería llevarse el equipo
Un diagrama generado con IA es útil cuando permite explicar el sistema y revisar sus relaciones. Su apariencia no basta para confiar en él.
Archify valida el artefacto y puede apoyar la trazabilidad cuando se incorpora evidencia del código. El equipo sigue siendo responsable de comprobar que las fuentes respalden las conexiones y que la arquitectura tenga sentido en su contexto.
La práctica que conviene adoptar es concreta: identificar de dónde sale cada relación, revisar los supuestos y dejar visibles las dudas que todavía no se han resuelto.
Esta necesidad conecta con lo planteado en el artículo de Kranio sobre spec-driven coding con IA: cuando generar una implementación plausible se vuelve más rápido, la validación adquiere un papel central.
¿Tu equipo está incorporando agentes a sus revisiones de arquitectura? Conversemos sobre cómo aplicar esta práctica en tu organización.
Referencias
- Bizagi. (s.f.). Free: Getting started with Bizagi Modeler. Documentación de Bizagi Modeler.
- Bizagi. (2023, 27 de noviembre). Standards compatability. Documentación de Bizagi Modeler.
- Gonzáles, P. (2026, 1 de junio). Spec-driven coding con IA: guía práctica para equipos. Kranio.
- tt-a1i. (2026a). Archify \[Software\]. GitHub.
- tt-a1i. (2026b). Authoring cookbook. Documentación de Archify.
- Structurizr. (s.f.). Structurizr \[Software\]. GitHub.
Entradas anteriores
Patrones y antipatrones en pruebas unitarias con JUnit y Mockito
Descubre los principales patrones y antipatrones en pruebas unitarias con JUnit y Mockito para crear tests más limpios, mantenibles y confiables.
ETL vs ELT: Diferencias, Casos de Uso y Mejores Herramientas
¿ETL o ELT? Conoce sus diferencias, ventajas, mejores herramientas modernas y casos de uso prácticos explicados de forma clara y sin complicaciones.
