Cómo Documentar la Arquitectura de Software con Archify

Última actualización: noviembre 21, 2026
Autor: Isaac
  • Archify transforma descripciones técnicas o código en diagramas interactivos mediante un proceso de generación, validación y entrega.
  • Permite realizar un seguimiento preciso de los cambios arquitectónicos mediante la comparación de versiones (diff) de archivos JSON.
  • La herramienta integra la trazabilidad del código permitiendo vincular nodos del diagrama con commits y líneas específicas de un repositorio.

Desarrollador diseñando un diagrama de flujo conceptual de arquitectura de software en una tablet digital con código de programación de fondo

Imagina que puedes plasmar la estructura de tu sistema en cuestión de minutos, obteniendo una imagen impecable para adjuntar a un pull request. Suena genial, pero aquí es donde muchos equipos meten la pata: un dibujo bonito no significa que el sistema funcione así en la realidad. El riesgo de las IA es que pueden inventarse conexiones que no existen, creando una ilusión de orden que puede llevar a errores graves en una revisión técnica si no se cuestiona qué hay detrás de cada flecha.

Para solucionar este caos, entra en juego Archify, una joya de código abierto con licencia MIT que no se limita a dibujar cajas. Lo que hace especial a esta herramienta es que introduce un flujo de trabajo riguroso donde la validación es la prioridad, asegurando que el artefacto final sea coherente y, sobre todo, revisable por humanos que sepan dónde mirar para no dejarse engañar por el agente.

El funcionamiento interno de Archify

Ingeniero de software analizando diagramas de flujo y wireframes de arquitectura en una pizarra blanca en una oficina moderna

La magia de Archify ocurre en tres etapas muy claras. Primero está la fase de Generate, donde el agente de IA redacta un archivo JSON que sirve como representación intermedia (IR) del diagrama. Luego viene el Validate, un paso crítico donde la herramienta comprueba que el JSON cumpla con reglas estrictas de estructura y diseño. Finalmente, el proceso de Deliver convierte todo aquello en un archivo HTML interactivo que puedes abrir en cualquier navegador sin necesidad de montar un servidor.

Para ponerlo en marcha, basta con ejecutar un comando sencillo como npx skills add tt-a1i/archify -g. Una vez que el agente tiene la habilidad, puedes pedirle el diagrama directamente en el chat. Además, cuenta con utilidades como archify doctor para diagnosticar fallos o archify demo para ver ejemplos reales de lo que puede hacer.

  Corregir el error runtimebroker exe y el alto problema de uso de cpu memoria y disco

Tipos de diagramas y su utilidad

Programador trabajando con doble monitor revisando un plan de desarrollo de software en un entorno profesional

No todo es arquitectura de componentes; Archify es versátil y ofrece diez tipos de mapas distintos según lo que necesites explicar. Para el mapa de servicios y almacenamiento usamos el modo architecture, mientras que para flujos de CI/CD o runbooks es mejor el modo workflow. Si necesitas detallar llamadas a APIs y trazas asíncronas, el modo sequence es el indicado.

También existen opciones más específicas: dataflow para el linaje de datos, lifecycle para gestionar estados y reintentos, e incluso ERD para esquemas de bases de datos con sus claves y cardinalidades. Para organizar jerarquías de módulos se usa el modo Tree, y para analizar incidentes o historiales de despliegue, los modos Timeline y Waterfall permiten ver exactamente dónde se fue el tiempo en una petición.

La importancia de validar frente a auditar

Equipo de desarrolladores colaborando en una oficina tecnológica moderna, representando la auditoría y revisión de arquitectura

Hay que tener muy claro que pasar los controles de Archify no significa que tu arquitectura esté bien diseñada. La herramienta valida que el archivo sea técnicamente correcto (que las flechas no se crucen feamente o que las etiquetas tengan espacio), pero no puede saber si esa conexión existe en tu código real. Es aquí donde el equipo debe intervenir para auditar la arquitectura, comprobando si las referencias a los archivos y líneas de código citadas realmente justifican la relación dibujada.

Un ejemplo claro es cuando el agente asume que un token JWT se valida consultando un proveedor de identidad externo (IdP) solo porque se lo pediste. El diagrama lo dibujará, pero es responsabilidad del desarrollador confirmar el supuesto revisando la implementación real. Si no se hace esto, el diagrama es solo una hipótesis visual, no un documento técnico fiable.

  Resuelve tus Problemas de Rendimiento en Servidor Windows 10

Comparación de versiones y el «Diff» arquitectónico

Primer plano de un editor de código en un monitor profesional, simbolizando la implementación real que Archify ayuda a documentar

Una de las funciones más potentes y que lo diferencia de cualquier otra herramienta es el comando compare. En lugar de tener un wiki desactualizado que nadie lee, Archify te permite comparar dos archivos JSON (por ejemplo, uno de la rama principal y otro de tu rama de trabajo). Esto genera un delta de arquitectura que muestra exactamente qué componentes se añadieron, cuáles se borraron y qué conexiones cambiaron de rumbo.

Lo más brillante es que utiliza hashes semánticos. Esto significa que si el agente solo cambia la posición de una caja pero la lógica sigue siendo la misma, el hash semántico no cambia, evitando que pierdas tiempo revisando cambios cosméticos que no afectan al sistema. Eso es oro puro para automatizar revisiones en pipelines de CI.

Integración con el ecosistema de IA y Mermaid

Archify se integra perfectamente con agentes como Claude Code, Cursor y Codex CLI. Aunque no es un editor visual donde arrastras cajas, su enfoque es el spec-driven development. Sobre Mermaid, es importante notar que Archify no es un simple renderizador de temas; lo que hace es reinterpretar la topología de Mermaid para convertirla en su propio formato JSON y así poder aplicar sus reglas de validación y comparación.

Para quienes se preocupan por la seguridad, la herramienta es muy transparente. Solo realiza una petición GET ocasional para avisar de actualizaciones, pero puedes desactivarlo totalmente con una variable de entorno. No es una herramienta para dibujar a mano, sino para convertir la intención técnica en un artefacto de comunicación preciso y basado en evidencias.

El uso de Archify transforma la documentación de un tedio manual a un proceso dinámico y verificable. Al centrarse en la representación intermedia en JSON y la validación automática, permite que los equipos de software mantengan sus mapas actualizados y vinculados al código real, eliminando la brecha entre lo que se diseña y lo que se implementa mediante la detección de supuestos y la comparación de versiones.

  Consejos y trucos de powerpoint online para crear mejores presentaciones

Preguntas frecuentes

¿Qué diferencia hay entre validar y auditar un diagrama en Archify?

La validación comprueba que el archivo JSON cumpla las reglas estructurales y visuales de la herramienta, mientras que la auditoría es la revisión humana para confirmar que las conexiones representadas existen realmente en el código.

¿Cómo se instalan las habilidades de Archify en un agente de IA?

Se puede instalar mediante el comando npx skills add tt-a1i/archify -g para la mayoría de agentes, aunque existen comandos específicos según si se utiliza Cursor o Codex CLI.

¿Es posible comparar dos versiones de una arquitectura con Archify?

Sí, la herramienta permite usar el comando compare para analizar dos archivos JSON y generar un HTML que resalte los cambios semánticos y estructurales entre versiones.

¿Archify puede convertir automáticamente diagramas de Mermaid?

No realiza una conversión directa de renderizado, sino que instruye al agente para que lea la topología de Mermaid y redacte desde cero un archivo JSON compatible con Archify.

¿Qué tipos de diagramas puede generar esta herramienta?

Puede crear diez tipos diferentes, incluyendo arquitectura, flujos de trabajo, secuencias, flujos de datos, ciclos de vida, ERD, diagramas de clases, árboles, líneas de tiempo y cascadas.

¿Cómo se vincula el diagrama con el código fuente real?

Archify permite incluir evidencia del código marcando nodos con referencias a commits y rangos de líneas específicos, los cuales pueden abrirse directamente en tarjetas de fuente.

Isaac

Isaac

Apasionado de la tecnología con años de experiencia analizando el ecosistema digital, especializado en hardware, optimización de software y seguridad informática. Mi trayectoria me ha permitido dominar desde la versatilidad de Linux y Windows hasta las particularidades de los entornos Mac e iOS, ayudando a los usuarios a maximizar el rendimiento de sus dispositivos.

Dedicado a la creación de tutoriales detallados y análisis profundos sobre aplicaciones, navegadores y consolas como Playstation, mi objetivo es transformar conceptos técnicos complejos en guías accesibles para mejorar la experiencia tecnológica de toda la comunidad.