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

Si es la primera vez que encuentras Archify, piensa en él como una Agent Skill para generar diagramas de arquitectura a partir de código o de una descripción del sistema.

No es un AI Coding Agent independiente. Se instala en herramientas como Cursor, Claude Code, Codex CLI u OpenCode y añade una capacidad específica: analizar un proyecto, representar su arquitectura y generar un diagrama interactivo.

El flujo básico es:

Código o descripción → Agent → JSON IR → validación → diagrama interactivo

Esta guía explica cómo instalar Archify, generar el primer diagrama, comprobar las relaciones con el código y utilizar las funciones de exportación y comparación.

Si antes quieres saber si Archify merece la pena, cómo se compara con Mermaid y Draw.io o cuáles son sus principales limitaciones, puedes leer nuestro análisis completo de Archify.

Qué necesitas antes de empezar

Hay dos requisitos principales.

Node.js 18 o superior.

Puedes comprobar la versión instalada desde la terminal:

node --version

Un AI Coding Agent compatible.

Archify está diseñado para utilizarse con Agents como Cursor, Claude Code, Codex CLI y OpenCode. También existe un plugin comunitario para DeepSeek Harness.

Una Agent Skill es, en esencia, un conjunto de instrucciones y herramientas que añade una capacidad concreta al Agent. En Archify, esa capacidad está orientada a la generación y validación de diagramas.

Cómo instalar Archify

La instalación básica se realiza con un único comando:

npx skills add tt-a1i/archify -g

Ejecuta el comando desde PowerShell en Windows o desde Terminal en macOS y Linux.

La opción -g instala la Skill de forma global.

Después puedes utilizar Archify desde un Agent compatible sin abrir una aplicación independiente.

Dónde se instala la Skill

La ubicación depende del Agent que utilices:

• Claude Code: ~/.claude/skills/ o .claude/skills/ dentro del proyecto.

• Codex CLI: ~/.agents/skills/ o .agents/skills/.

• OpenCode: ~/.config/opencode/skills/, .opencode/skills/ o .agents/skills/.

Si utilizas Cursor

En Cursor puede ser más cómodo utilizar una instalación explícitamente no interactiva:

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

Si Cursor no detecta la Skill inmediatamente, inicia una nueva sesión del Agent.

Probar Archify sin instalarlo permanentemente

También existe una opción para utilizar la Skill de forma puntual:

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

Esto puede ser útil si primero quieres comprobar cómo funciona antes de incorporarlo a tu entorno habitual.

Casos especiales

En Claude.ai, la versión web de Claude, la Skill se puede cargar manualmente. El proceso consiste en descargar archify.zip desde la sección Releases del proyecto y subirlo desde Settings → Capabilities → Skills.

Para DeepSeek Harness existe un plugin comunitario:

dsh plugin --profile web add @tt-a1i/archify-dsh@0.1.0

Cómo comprobar la instalación

Archify incluye un CLI que permite realizar algunas comprobaciones básicas.

Por ejemplo:

node bin/archify.mjs doctor

El comando doctor comprueba el entorno.

También puedes generar un ejemplo:

node bin/archify.mjs demo /tmp/archify-demo

Y existe un comando guide para obtener una recomendación sobre el tipo de diagrama:

node bin/archify.mjs guide "Muestra checks de CI/CD, aprobación, despliegue y rollback"

demo es especialmente útil para comprobar la instalación sin analizar todavía un repositorio real.

Cómo generar tu primer diagrama

Una vez instalada la Skill, no necesitas aprender una sintaxis específica.

Abre tu proyecto con el AI Coding Agent y describe lo que quieres generar.

Para una arquitectura sencilla:

Usa Archify para dibujar:

Navegador → API → caché Redis → PostgreSQL como fallback.

Para un repositorio existente, es mejor empezar con un alcance limitado:

Analiza este repositorio y usa Archify para crear un diagrama de arquitectura de alto nivel.

Muestra entre 8 y 12 componentes principales, la ruta principal,
las dependencias externas y los límites de confianza.

Mantén los detalles secundarios fuera del diagrama principal.

Esta segunda forma suele ser más práctica que pedir al Agent que represente todo el repositorio de una vez.

Un proyecto grande puede contener cientos de archivos, módulos y dependencias. Intentar incluirlos todos en el primer diagrama suele producir una visualización difícil de leer.

Es mejor empezar por la arquitectura general y después profundizar.

Los cinco tipos de diagramas

Archify trabaja actualmente con cinco categorías principales:

• Architecture: servicios, componentes y relaciones entre ellos.

• Sequence: secuencias de llamadas e interacciones.

• Data Flow: movimiento de datos entre sistemas.

• Workflow: procesos como CI/CD, aprobaciones y automatizaciones.

• Lifecycle: estados y transiciones durante el ciclo de vida de un objeto o proceso.

Para tu primer intento, Architecture suele ser la opción más sencilla.

Después puedes utilizar Sequence para estudiar una llamada concreta o Data Flow cuando quieras seguir el recorrido de determinados datos.

Cómo leer un diagrama de Archify

Cuando aparezca el primer diagrama, no te limites a comprobar si visualmente parece correcto.

Hay cuatro elementos que conviene revisar.

Nodos

Los nodos representan componentes del sistema.

Pueden ser:

• Frontends.

• APIs.

• Servicios backend.

• Bases de datos.

• Cachés.

• Colas.

• Servicios externos.

En conjunto forman una vista del inventario principal de la arquitectura.

Conexiones

Las conexiones muestran cómo se relacionan los componentes.

Por ejemplo:

Usuario → Web → API → Service → Database

Seguir una ruta de este tipo permite entender rápidamente cómo atraviesa el sistema una determinada petición.

Relaciones upstream y downstream

Selecciona un componente y revisa qué otros componentes dependen de él y a cuáles llama.

Por ejemplo, en un servicio de pedidos puedes seguir la ruta hacia:

API → Order Service → Redis → Database

y también comprobar qué componentes llegan hasta Order Service.

Esto es especialmente útil cuando estás entrando en un repositorio que no conoces bien.

Evidencia del código

Cuando el diagrama se genera a partir de un repositorio, algunos nodos pueden incluir referencias al código fuente.

Estas referencias permiten comprobar el archivo y la línea asociados a un componente o relación.

Esta comprobación es importante porque un diagrama generado por IA puede representar una arquitectura plausible sin que todas sus relaciones existan realmente en el código.

Archify intenta reducir este problema proporcionando trazabilidad entre la representación visual y el código.

Cómo refinar el primer diagrama

No necesitas acertar con el prompt perfecto en el primer intento.

Una vez generado el diagrama puedes pedir cambios concretos, por ejemplo:

Añade Redis y muestra qué servicios lo utilizan.

o:

Muestra únicamente las dependencias entre la API y los servicios internos.

También puedes pedir una vista más sencilla:

Reduce el diagrama a los componentes principales y elimina las conexiones secundarias.

Para proyectos grandes, este proceso incremental suele ser más útil que intentar generar una representación completa desde el principio.

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

Una de las funciones más interesantes es Architecture Delta, basada en las vistas Before / Delta / After.

Imagina una arquitectura inicial:

Frontend → API → Order Service → MySQL

Después de una refactorización:

Frontend → API → Order Service → Redis → MySQL

Un segundo diagrama muestra el nuevo estado, pero todavía tienes que comparar ambos manualmente.

La vista Delta está pensada precisamente para este tipo de cambios.

Puede mostrar elementos:

• Añadidos.

• Eliminados.

• Modificados.

• Desplazados.

• Redirigidos.

Esto puede ser útil durante una refactorización, una migración o una revisión de código con cambios importantes en la arquitectura.

No sustituye al Code Review. Su función es facilitar la visualización de lo que cambió.

Utilizar Archify durante un Code Review

Una forma práctica de incorporarlo al flujo de desarrollo es generar una representación antes y después de un cambio arquitectónico.

Por ejemplo:

Antes del PR → modificar código → generar nueva arquitectura → comparar Delta

Esto permite responder preguntas como:

• ¿Se añadió un nuevo servicio?

• ¿Cambió el recorrido de una petición?

• ¿Apareció una nueva dependencia?

• ¿Se eliminó algún componente?

• ¿Cambió la conexión con una base de datos?

• ¿Se introdujo una nueva capa intermedia?

Para cambios pequeños probablemente no sea necesario. En refactorizaciones grandes puede ahorrar bastante tiempo de lectura.

Cómo exportar y compartir un diagrama

El resultado de Archify puede utilizarse como un HTML autocontenido.

Esto resulta útil cuando quieres compartir el diagrama sin depender de una instalación local o de un servicio externo.

También puedes exportarlo a diferentes formatos, entre ellos:

• PNG

• SVG

• WebM

• Tarjeta de 1200 × 630

Antes de exportarlo como imagen, merece la pena utilizar la versión HTML para explorar el sistema.

Puedes buscar nodos, seguir relaciones y revisar las rutas entre componentes.

Por ejemplo, si quieres averiguar por qué una operación de autenticación termina accediendo a una base de datos, puedes localizar el componente de autenticación y seguir sus relaciones downstream.

Consejos para empezar con Archify

Empieza con un proyecto pequeño

Si es tu primera prueba, utiliza un repositorio que conozcas.

Así podrás detectar rápidamente si el Agent ha interpretado correctamente los componentes y las relaciones.

No intentes representar todo el repositorio

Empieza con una arquitectura de alto nivel.

Después puedes pedir diagramas más específicos para:

• Autenticación.

• Procesamiento de pagos.

• API.

• Pipeline CI/CD.

• Flujo de datos.

• Un servicio concreto.

Comprueba las relaciones importantes

Que un diagrama tenga buen aspecto no significa que todas sus conexiones sean correctas.

Cuando una relación sea importante, vuelve al código y comprueba la referencia correspondiente.

Utiliza Delta después de refactorizaciones grandes

Si vas a cambiar la arquitectura de forma significativa, generar un diagrama antes y después puede resultar más útil que intentar reconstruir manualmente el impacto de cada modificación.

No lo trates como un simple generador de imágenes

La principal utilidad de Archify está en combinar AI Coding Agent + representación estructurada + validación + visualización + trazabilidad.

El diagrama es el resultado visible, pero el flujo que hay detrás es la parte más interesante.

Preguntas frecuentes sobre Archify

¿Qué es Archify?

Archify es una Agent Skill open source para AI Coding Agents. Puede utilizar un repositorio o una descripción de un sistema para generar diagramas de arquitectura, secuencia, workflow, flujo de datos y ciclo de vida.

¿Archify es un AI Coding Agent?

No.

Cursor, Claude Code, Codex CLI y OpenCode son ejemplos de entornos o Agents de programación con IA.

Archify es una Skill que añade capacidades de generación y validación de diagramas a estos entornos.

¿Archify puede analizar un proyecto de GitHub?

Sí, siempre que el Agent tenga acceso al código del proyecto.

Puedes abrir el repositorio en tu entorno de AI Coding y pedirle que analice la arquitectura utilizando Archify.

Por ejemplo:

Analiza este repositorio y genera con Archify un diagrama
de arquitectura de alto nivel.

Muestra los principales servicios, dependencias externas,
bases de datos y flujo principal de las peticiones.

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

Sí.

La instalación general es:

npx skills add tt-a1i/archify -g

Para Cursor puede ser conveniente utilizar la variante explícita:

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

También existe un plugin comunitario para DeepSeek Harness.

¿Los diagramas generados por Archify son fiables?

Conviene no interpretar la validación como una garantía absoluta de exactitud.

El Agent sigue siendo responsable de interpretar el código y puede equivocarse.

Archify añade una capa de validación sobre la representación generada y permite relacionar determinados elementos con el código fuente. Esto facilita detectar y comprobar errores, pero no elimina por completo las posibles interpretaciones incorrectas del modelo.

¿Puedo exportar un diagrama a PNG?

Sí.

Archify admite exportación a PNG, SVG y WebM, además de una tarjeta de 1200 × 630.

También puedes compartir el HTML autocontenido.

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

Sí.

No necesitas aprender una sintaxis específica para empezar. Puedes describir el sistema en lenguaje natural y dejar que el Agent genere la estructura inicial.

Si no estás seguro de qué tipo de diagrama utilizar, el comando guide puede ayudarte:

node bin/archify.mjs guide "Muestra checks de CI/CD, aprobación, despliegue y rollback"

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

Las tres herramientas tienen enfoques diferentes.

Mermaid utiliza una sintaxis de texto para definir diagramas. Draw.io está orientado a la edición visual mediante arrastrar y soltar. Archify utiliza un AI Coding Agent para interpretar código o lenguaje natural y generar una representación estructurada que después pasa por su proceso de validación.

Por eso Archify tiene más sentido dentro de un flujo de desarrollo asistido por IA que como sustituto general de un editor visual.

Para una comparación más detallada puedes consultar nuestro análisis completo de Archify.

¿Archify sincroniza automáticamente el código y el diagrama?

No.

Cuando cambia la arquitectura, necesitas volver a ejecutar el Agent para generar o actualizar la representación.

La ventaja del enfoque es que puedes regenerar el diagrama a partir del estado actual del código en lugar de mantener manualmente cada elemento visual.

¿Qué debería probar después de mi primer diagrama?

Un buen recorrido sería:

Instalar Archify → generar una arquitectura general → comprobar las referencias al código → explorar una ruta concreta → modificar el código → volver a generar el diagrama → comparar Before / Delta / After.

Después puedes utilizar el mismo proceso para analizar servicios concretos, flujos de datos, secuencias de API o pipelines CI/CD.

Conclusión

Archify resulta más fácil de entender cuando se utiliza sobre un proyecto real.

En lugar de abrir un editor y dibujar manualmente cada componente, puedes pedirle a tu AI Coding Agent que analice el código, genere una representación de la arquitectura y la convierta en un diagrama interactivo.

Sus puntos más interesantes no están únicamente en el resultado visual. La combinación de JSON IR, validación, trazabilidad al código y Architecture Delta hace que encaje especialmente bien con tareas de ingeniería como explorar un repositorio, documentar una arquitectura o revisar una refactorización.

Eso tampoco significa que sustituya a Mermaid o Draw.io.

Si quieres editar cada elemento manualmente, una herramienta visual tradicional puede ser más adecuada. Si ya trabajas con Cursor, Claude Code, Codex CLI u OpenCode y quieres una forma más automatizada de entender y documentar tus proyectos, Archify tiene bastante más sentido.

El mejor punto de partida es sencillo: instálalo, pruébalo con un repositorio pequeño y comprueba las relaciones importantes directamente en el código.

A partir de ahí podrás decidir si encaja realmente en tu flujo de AI Coding.