Archify Starter Guide: crea tu primer diagrama de arquitectura con IA

Si es la primera vez que escuchas hablar de Archify, la forma más sencilla de entenderlo es esta: permite que un AI Coding Agent aprenda a generar diagramas de arquitectura a partir de un código real o de una descripción del sistema.

Archify es un Agent Skill que puede utilizarse con Cursor, Claude Code, Codex CLI, OpenCode y otras herramientas de AI Coding. El Agent analiza el repositorio o la descripción proporcionada, identifica sus componentes y relaciones y utiliza Archify para generar un diagrama de sistema interactivo.

Actualmente admite cinco tipos de diagramas: Architecture, Workflow, Sequence, Data Flow y Lifecycle.

Su principal utilidad no es simplemente “dibujar diagramas”, sino ayudarte a entender cómo funciona un proyecto que todavía no conoces.

Por ejemplo, si acabas de recibir un proyecto web y no quieres pasar horas recorriendo carpetas, buscando APIs y siguiendo llamadas a la base de datos, puedes pedirle al AI Agent que analice el código y utilice Archify para representar visualmente relaciones como:

Frontend → API → Service → Database

Eso convierte la arquitectura en una forma mucho más rápida de explorar el funcionamiento real del proyecto.

¿Qué es Archify?

Archify no es un chatbot de IA convencional ni un programa tradicional de diagramación como Draw.io.

La definición más precisa es que se trata de un Agent Skill.

Un Agent Skill puede entenderse, de forma sencilla, como un paquete de capacidades que añade una función específica a un AI Coding Agent.

Un AI convencional puede decirte:

“Este proyecto tiene un frontend en React, un backend en Node.js y una base de datos PostgreSQL”.

Con Archify instalado, puedes pedirle al Agent algo más:

“Analiza este proyecto y utiliza Archify para generar un diagrama de arquitectura general”.

El Agent se encarga de comprender el código y las relaciones entre los componentes, mientras que Archify convierte esa información estructurada en un diagrama interactivo y validado.

La documentación oficial define Archify como un Agent-facing Skill. Por eso, un usuario normal no necesita aprender su JSON Schema ni ejecutar manualmente los comandos internos de renderizado.

Esto lo hace especialmente útil para:

• Entender un repositorio desconocido.

• Analizar la arquitectura existente.

• Comprender las relaciones entre módulos y servicios.

• Crear documentación técnica.

• Entender el sistema antes de modificar código.

• Explicar la estructura de un proyecto a otros desarrolladores.

¿Qué necesitas saber antes de usar Archify por primera vez?

No necesitas estudiar primero la teoría de los Agents.

Lo importante es entender una diferencia:

Un Prompt convencional indica a la IA cómo responder; un Agent Skill añade al Agent una capacidad que puede ejecutar.

Cursor, Claude Code, Codex CLI y OpenCode son AI Coding Agents. Pueden leer archivos, analizar código y ejecutar comandos.

Archify añade otra capacidad: permite que el Agent transforme el análisis del proyecto en un diagrama de arquitectura.

Por eso Archify no funciona normalmente como una ventana de chat independiente.

El flujo habitual es:

Cursor / Claude Code / Codex / OpenCode → Archify → diagrama de arquitectura

El README oficial incluye actualmente Cursor, Claude Code, Codex CLI y OpenCode, junto con las ubicaciones correspondientes para instalar el Skill.

Cómo instalar Archify

Comprueba el entorno

La documentación actual de Archify requiere Node.js 18 o superior.

Para la mayoría de usuarios no es necesario instalar manualmente las dependencias del proyecto Node.js de Archify. La opción recomendada es instalar el Skill mediante npx skills.

Primero comprueba la versión de Node.js:

node -v

Si tienes la versión 18 o posterior, puedes continuar.

Instala el Skill

El comando de instalación global recomendado actualmente es:

npx skills add tt-a1i/archify -g

Si utilizas Cursor, puedes especificarlo directamente:

npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

Cuando termine la instalación, vuelve a abrir el AI Coding Agent correspondiente para que cargue el nuevo Skill.

Si solo quieres probar Archify antes de instalarlo de forma permanente, también puedes utilizar:

npx skills use tt-a1i/archify@archify --agent codex

Esta opción resulta especialmente útil para una primera prueba.

Cómo generar tu primer diagrama con Archify

Para empezar, no es recomendable utilizar un proyecto con cientos de miles de líneas de código.

Es mejor elegir un proyecto web pequeño que conozcas relativamente bien. Por ejemplo:

React + Node.js API + PostgreSQL

Abre el proyecto en Cursor, Claude Code, Codex u OpenCode.

Después puedes utilizar un Prompt sencillo:

Analyze this repository and use Archify to create a high-level
runtime architecture diagram.
Show the frontend, API, services, database,
external dependencies, and the primary request path.

No necesitas describir manualmente todos los módulos.

Si el Agent puede acceder al repositorio, deja que encuentre la estructura directamente en el código.

También puedes utilizar Archify sin proporcionar un repositorio. Por ejemplo:

Use Archify to draw:
Browser -> API -> Redis cache -> PostgreSQL fallback.

La documentación oficial contempla ambas posibilidades: análisis de un código real y generación a partir de una descripción del sistema.

La diferencia es sencilla:

Si tienes el código → deja que el Agent encuentre la estructura real.

Si no tienes el código → describe mediante texto el sistema que quieres representar.

Cómo interpretar tu primer diagrama

Cuando aparezca el primer diagrama, no te centres únicamente en si visualmente resulta atractivo.

Primero busca cuatro elementos.

1. Los nodos

Los nodos representan normalmente elementos como el frontend, servicios backend, bases de datos, cachés, colas de mensajes o servicios externos.

2. Las conexiones

Las conexiones representan las relaciones entre los componentes.

Por ejemplo:

Usuario → Web → API → Service → Database

Este tipo de representación permite entender mucho más rápido por dónde pasa una petición que simplemente recorriendo la estructura de carpetas.

3. Las relaciones upstream y downstream

Si seleccionas un Service, puedes analizar qué componentes están conectados con él.

Puedes preguntarte:

¿Quién llama a este servicio?

Y después:

¿A qué componentes llama este servicio?

Archify permite buscar nodos, explorar relaciones y seguir recorridos concretos upstream y downstream.

4. El origen de la información

Cuando la arquitectura necesita estar respaldada por el código, los nodos pueden asociarse con ubicaciones concretas del código fuente que han sido verificadas.

Esto es importante porque el diagrama deja de ser simplemente una explicación generada por IA. Puedes volver al código real y comprobar de dónde procede una determinada relación.

Esta es una de las diferencias conceptuales más interesantes de Archify frente a un simple “generador de diagramas con IA”:

un buen diagrama de arquitectura debería ayudarte a entender el código real, no hacer que la IA invente una arquitectura que simplemente parece razonable.

Qué puedes hacer con el diagrama

Una vez generado, no hace falta exportarlo inmediatamente como imagen.

Es más útil utilizarlo primero como un mapa interactivo del código.

Por ejemplo, imagina que estás intentando averiguar por qué una operación de inicio de sesión termina accediendo a la base de datos.

Puedes buscar los nodos relacionados con la autenticación y seguir las conexiones para descubrir el recorrido de la petición.

Si estás investigando un determinado Service, puedes seguir el flujo hacia arriba:

¿Quién lo llama?

Y después hacia abajo:

¿Qué componentes utiliza?

Si el objetivo es añadir el diagrama a un README o a documentación técnica, puedes cambiar entre los temas Dark y Light y exportarlo en formatos como PNG o SVG.

La versión estable actual también admite WebM y Share Card de 1200×630, entre otras opciones de salida.

Archify ofrece cinco tipos principales de diagramas:

• Architecture: para representar componentes, servicios y sus relaciones.

• Sequence: para analizar el recorrido de una llamada o interacción.

• Data Flow: para visualizar cómo circulan los datos entre sistemas.

• Workflow: para procesos como CI/CD, aprobaciones y llamadas a herramientas.

• Lifecycle: para estados, reintentos y cambios a lo largo del ciclo de vida.

Para empezar, solo necesitas aprender uno:

Architecture.

Cómo utilizar Archify para entender los cambios del código

Una de las funciones más interesantes para un flujo de AI Coding es Architecture Delta.

Imagina que antes de una refactorización tienes:

Frontend → API → Order Service → MySQL

Y después del cambio tienes:

Frontend → API → Order Service → Redis → MySQL

Si simplemente generas otro diagrama, todavía tendrás que comparar manualmente ambas versiones.

Archify puede comparar dos snapshots validados mediante una vista Before / Delta / After, mostrando elementos añadidos, eliminados, modificados, desplazados o redirigidos.

La documentación oficial presenta esta función como una herramienta para comparar cambios arquitectónicos, especialmente útil durante el diseño y las revisiones de Pull Requests.

Como principiante no necesitas memorizar todavía los comandos específicos.

Lo importante es entender el concepto:

Archify no solo puede mostrarte cómo es el sistema ahora; también puede ayudarte a entender qué cambió en la arquitectura después de modificar el código.

Esto resulta especialmente interesante para refactorizaciones, cambios importantes y Code Review.

Consejos para tu primera experiencia con Archify

Para empezar, utiliza un proyecto pequeño que conozcas bien. Si el Agent interpreta incorrectamente alguna relación, podrás detectarlo fácilmente.

No intentes analizar todo un repositorio enorme desde el principio. Empieza con un diagrama de arquitectura de alto nivel y después profundiza en módulos concretos.

Cuando encuentres un nodo importante, intenta seguir una ruta real, por ejemplo:

Petición del usuario → Controller → Service → Database

No te quedes solo con la representación visual. Vuelve al código y comprueba que las relaciones realmente existen.

Antes de realizar una refactorización importante, puedes generar un diagrama de arquitectura. Después de terminar los cambios, genera otro y compara la evolución del sistema.

Y hay una idea especialmente importante:

No pienses en Archify como un simple generador de diagramas bonitos.

Su verdadero valor está en convertir el diagrama de arquitectura en una forma interactiva de comprender el código y el sistema.

Preguntas frecuentes sobre Archify

¿Qué es Archify?

Archify es un Agent Skill diseñado para AI Coding Agents. Puede convertir un repositorio o una descripción de un sistema en diagramas interactivos de arquitectura, workflows, secuencias, flujos de datos y ciclos de vida.

¿Archify es un AI Coding Agent?

No.

Cursor, Claude Code, Codex CLI y OpenCode son AI Coding Agents. Archify es una capacidad que estos Agents pueden utilizar para analizar y representar la arquitectura de un sistema.

¿Archify puede analizar un proyecto de GitHub?

Puede analizar cualquier código al que el AI Coding Agent tenga acceso.

En la práctica, normalmente abres el proyecto en tu AI Coding Agent y le pides que analice el repositorio y utilice Archify. El ejemplo oficial sigue precisamente este enfoque: analizar el repository actual y generar un runtime architecture diagram.

¿Archify funciona con Cursor, Claude Code, Codex y OpenCode?

Sí. El README oficial incluye actualmente estos cuatro Agents y proporciona las ubicaciones correspondientes para instalar el Skill.

¿Los diagramas generados por Archify son fiables?

No existe una garantía de que un análisis generado por IA sea siempre correcto.

La fiabilidad también depende de cómo el Agent interprete el código. Sin embargo, Archify utiliza un typed JSON IR, Schema y procesos de validación deterministas. Además, su enfoque busca que las relaciones interactivas procedan de una topología generada y validada, en lugar de inventar conexiones arbitrarias.

Por eso conviene utilizar el diagrama como una herramienta de exploración y verificar las relaciones importantes en el código fuente.

¿Puedo exportar los diagramas a PNG?

Sí.

La versión estable actual admite formatos como PNG, SVG y WebM, además de formatos para compartir como Share Card.

¿Puedo utilizar Archify si no sé crear diagramas de arquitectura?

Sí.

De hecho, este es uno de los principales atractivos del modelo Agent Skill. No necesitas aprender el Schema de Archify ni saber diseñar manualmente un diagrama.

Puedes simplemente decirle al Agent qué sistema quieres entender y dejar que analice el código.

¿Cuál es la diferencia entre Archify, Mermaid y Draw.io?

La diferencia principal no está en qué herramienta dibuja mejor, sino en cómo se crea el diagrama.

Mermaid y Draw.io están más orientados a que el usuario describa, diseñe o edite directamente el diagrama.

Archify está pensado para que un AI Coding Agent analice una descripción o un repositorio, identifique la estructura y genere un diagrama validado a partir de ese análisis.

La propia documentación también deja claro que Archify no pretende ser un editor WYSIWYG general ni un tema de Mermaid.

¿Qué hacer después de tu primer diagrama?

Para empezar con Archify no necesitas aprender demasiadas cosas.

Puedes seguir este recorrido:

Instalar Archify → probarlo con un proyecto pequeño → generar la arquitectura general → explorar las relaciones entre módulos → seguir un flujo real de datos → modificar el código → generar de nuevo la arquitectura → comparar Before / Delta / After → utilizarlo como apoyo para Code Review.

Con el tiempo, Archify deja de parecer simplemente una herramienta para generar AI architecture diagrams.

Su función más interesante es convertirse en una especie de mapa del sistema dentro del flujo de AI Coding: te ayuda a entender la arquitectura antes de modificar el código, observar el impacto mientras trabajas y comprobar después qué ha cambiado realmente.

Lo más importante de Archify no es aprender a generar tu primer diagrama, sino aprender a convertir la arquitectura en una parte habitual de tu flujo de trabajo con AI Coding.