Archify: la skill para dibujar arquitectura verificada con Claude Code o Codex

Archify es una skill de agente —un paquete de instrucciones y herramientas que un agente como Claude Code puede leer e invocar— para dibujar diagramas de arquitectura, validados antes de mostrarse. Alcanza con pedirlo en una oración: es tan fácil de generar como pedir cualquier otra cosa en el chat, y sirve tanto para mostrar un sistema como para entenderlo de un vistazo, sin leerlo archivo por archivo. La mantiene tt-a1i (abre en una pestaña nueva) en un repositorio con licencia MIT: gratis, sin cuenta, sin clave de API. No es exclusiva de Claude: funciona igual con Codex CLI, Cursor y opencode.

El problema que resuelve es concreto. Pedirle a un agente “un diagrama Mermaid” es rápido, pero nada comprueba que lo que dibuja coincida con el código real: puede devolver una flecha entre dos servicios que ni siquiera se llaman entre sí, sin que eso sea una mentira a propósito —el agente escribió el diagrama igual que escribe cualquier respuesta, prediciendo qué forma tendría uno razonable para esa pregunta—. Archify separa ese paso en dos: el agente primero escribe una descripción tipada del sistema, y recién la dibuja después de que un validador la revisa.

Instalación

# Instalarla para siempre, en cualquier proyecto
npx skills add tt-a1i/archify -g

# Probarla una vez, sin instalar nada
npx skills use tt-a1i/archify@archify --agent codex

Con eso, el agente que uses puede invocarla apenas se lo pidas en el chat. Más abajo hay ejemplos concretos de qué escribirle.

Cómo funciona: nada se dibuja a mano

La diferencia con pedir “un diagrama Mermaid” está en qué pasa entre que lo pedís y que lo ves. Archify separa esa distancia en cinco pasos, y ninguno se salta:

El paso que cambia todo es el segundo. Antes de mostrarte nada, Archify comprueba que el JSON que escribió el agente cumple un esquema fijo, que el layout no deja nodos superpuestos ni flechas ambiguas, y que el HTML/SVG que va a salir es válido. Si algo falla, no te llega un diagrama roto: le llega al agente un JSON con el código de la regla que falló, qué nodo la rompió, y qué arreglos soporta. El agente corrige y vuelve a intentar, solo, sin que vos tengas que darte cuenta de que falló la primera vez.

El JSON tipado que hay detrás

Lo que el agente escribe en el paso 1 no es Mermaid ni un dibujo: es un documento JSON con una forma fija, que en la documentación de Archify llaman el IR (intermediate representation, representación intermedia). Cada tipo de diagrama tiene su propio esquema, y ese esquema es lo que el paso 2 valida.

Así arrancan los primeros componentes del archivo con el que Archify dibuja su propia arquitectura —es real, está en su repositorio, no es un ejemplo inventado para este artículo—:

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Archify",
    "subtitle": "Agent skill → JSON IR → typed renderers → standalone HTML"
  },
  "components": [
    { "id": "user", "type": "external", "label": "You", "sublabel": "NL or Mermaid" },
    { "id": "agents", "type": "frontend", "label": "Agent Hosts", "sublabel": "Claude · Codex · opencode" },
    { "id": "ir", "type": "messagebus", "label": "JSON IR", "sublabel": "schema_version: 1" }
  ],
  "connections": [
    { "from": "user", "to": "agents", "variant": "emphasis" },
    { "from": "agents", "to": "ir", "label": "write IR", "variant": "emphasis" }
  ]
}

Cada componente tiene una posición, un tamaño y un type que decide cómo se dibuja (external, frontend, backend, security, y varios más). Cada conexión declara de dónde a dónde va, y puede llevar una etiqueta o un variant que cambia el trazo —emphasis para el camino principal, dashed para algo secundario. Ninguno de esos campos es libre: si el agente escribe uno que el esquema no reconoce, la validación del paso 2 lo rechaza ahí mismo.

Así está armado el propio Archify

El archivo de arriba, ya completo y validado, genera este diagrama. Es la arquitectura real de la herramienta, contada con sus propias palabras:

Dos cosas quedan más claras mirando este diagrama que leyendo la lista de funciones: primero, que Archify no reemplaza a Claude Code ni a Codex, vive al lado y les da un lugar donde escribir en un formato verificable. Segundo, que el archivo final —el HTML que abrís en el navegador— no depende de nada más una vez generado: no llama a ningún servidor, no necesita conexión, se puede mandar por mail o subir a cualquier lado.

El de arriba es un ejemplo chico, a propósito, para que se lea de un vistazo. Con un sistema real y más grande el resultado sigue el mismo criterio: cada caja es un componente real, cada flecha una relación real, con límites y colores por tipo. Este es el diagrama que Archify entregó para un sistema de memoria de un agente de IA —un repositorio de Markdown como fuente de verdad, un motor de búsqueda híbrida, y una capa de habilidades encima—:

Mismos colores por tipo de componente, mismos límites punteados, la misma leyenda abajo a la izquierda. La única diferencia con el diagrama chico de arriba es la cantidad de piezas.

Generarlo no pide mucho más que eso: describís el sistema, el agente escribe el JSON, y se corrige lo que la validación marque. Lo probamos con el propio código de este blog —el que estás leyendo ahora—: en un par de rondas de corrección tuvimos un diagrama real de cómo está armado, con Supabase, el build de Cloudflare Pages y el disparador que manda el aviso por correo cuando alguien comenta. Ahí está el otro uso, además de mostrarlo: entender de un vistazo cómo encaja un sistema, en vez de leerlo archivo por archivo.

Los cinco tipos de diagrama

El esquema (y por lo tanto la validación) es distinto según qué estés describiendo. Archify reconoce cinco:

Tipo	Para qué sirve	Qué conviene contarle
Architecture	Componentes, servicios, almacenamiento, límites de confianza	El alcance, los componentes centrales, el camino principal
Workflow	CI/CD, aprobaciones, llamadas a herramientas, runbooks	Quién participa, en qué orden, qué ramas y excepciones hay
Sequence	Llamadas a una API, caída a caché, autenticación, trazas async	Quién llama, quién responde, qué devuelve y con qué tiempos
Data Flow	Pipelines de datos, linaje, dónde vive información sensible	Fuentes, transformaciones, dónde se guarda, quién lo consume
Lifecycle	Estados de algo, reintentos, esperas, salidas finales	Los estados, qué evento mueve de uno a otro, cómo se reintenta

Cuando el diagrama viene de un repositorio real

Hasta acá, todos los ejemplos parten de una descripción que vos le das al agente. Pero también se puede pedir lo contrario: que analice un repositorio existente y arme el diagrama a partir del código.

Ahí entra un detalle que vale la pena remarcar. Cuando Archify arma un nodo a partir de código real, lo marca con una etiqueta SRC n —n es la cantidad de referencias que encontró— y ese nodo queda enlazado al archivo y al rango de líneas exactos, fijados al commit en el que se generó el diagrama. Si el código cambia después, el enlace sigue apuntando a esa versión puntual, no a lo que haya en el archivo hoy. Es la diferencia entre “un diagrama que dice representar el código” y uno donde cada caja te lleva de vuelta a la línea que la generó.

Lo mismo pasa al comparar dos versiones del mismo sistema: Architecture Delta toma dos capturas ya validadas —antes y después— y arma un tercer diagrama que marca qué componente se agregó, cuál se sacó, cuál cambió de lugar. Sirve para revisar un cambio grande antes de aprobar un PR, con la misma garantía de que lo que ves salió de datos reales y no de una suposición.

Cómo pedirlo, en la práctica

No hace falta aprender la forma del JSON para usar Archify: eso lo escribe el agente. Alcanza con pedirlo en el chat, con la claridad de siempre. Sin repositorio, para algo que todavía no existe como código:

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

Con un repositorio ya escrito:

Analyze this repository, then use archify to create a high-level runtime
architecture diagram. Show 8–12 core components, one primary path, external
dependencies, and trust boundaries.

Y una vez que el primer diagrama está en pantalla, se ajusta charlando, igual que el resto de una conversación con el agente:

add Redis
move auth to the left
highlight the rollback path

Cada uno de esos pedidos vuelve a pasar por los cinco pasos completos: el agente reescribe el JSON, se valida de nuevo, y recién ahí cambia lo que ves. Nunca hay un dibujo que no haya pasado por ese filtro.