Archify genera diagramas de arquitectura desde Claude Code y compara dos versiones del mismo diagrama para mostrarte qué cambió. Ninguna otra herramienta del área hace esa segunda parte.
Y esa es la parte que importa. Generar un diagrama bonito a partir de una descripción ya lo hacen varias herramientas, y en yoDEV cubrimos diagram-design y GitDiagram hace poco. Lo que no existía era un diff de arquitectura que puedas dejar adjunto en un pull request.
¿Qué es Archify?
Archify es un sistema de renderizado y validación escrito en Node.js, con licencia MIT. Funciona como agent skill: tu agente escribe un JSON tipado (el IR, o representación intermedia) y Archify lo compila de forma determinista en un archivo HTML interactivo y autocontenido.
Ese JSON es un archivo plano con estas claves de primer nivel: schema_version, diagram_type, meta, layout, components, boundaries, connections y cards. Vale la pena que lo tengas presente, porque las dos versiones que vas a comparar más adelante no son otra cosa que dos de estos archivos.
El repositorio iba en 63.1K estrellas al 15 de septiembre de 2026, y sube rápido, así que esa cifra envejece en días.
¿Qué tipos de diagrama genera?
Cinco, y cada uno tiene un nombre que vas a usar como argumento en la línea de comandos:
architecture— componentes, servicios, almacenamiento y límitesworkflow— CI/CD, aprobaciones, llamadas a herramientas, runbookssequence— llamadas a APIs, fallback de caché, trazas asíncronasdataflow— pipelines, linaje, límites de consumolifecycle— estados, reintentos, esperas y resultados terminales
Exporta a PNG, SVG, WebM y una tarjeta para compartir de 1200×630.
¿Cómo instalar Archify en Claude Code?
Una línea. La misma sirve para opencode:
npx skills add tt-a1i/archify -g
Cursor y Codex CLI no usan ese mismo comando. Si trabajas ahí, son estos:
npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes
npx skills use tt-a1i/archify@archify --agent codex
Para verificar que quedó bien instalado, y para generar un set de ejemplos:
archify doctor
archify demo [directorio-de-salida]
¿Por qué sirve que un diagrama se valide solo?
Porque el diagrama roto no llega a existir. Antes de escribir el artefacto, Archify corre chequeos de esquema, de layout, de ruteo y de separación de etiquetas. Si algo falla no recibes una imagen con flechas cruzadas: recibes un JSON con códigos de regla y con indicaciones de reparación, que el agente puede leer y corregir sin que intervengas.
Hay dos perfiles de calidad, standard y showcase. Un pase en showcase tiene que reportar los 9 chequeos de artefacto con 0 errores de composición y 0 advertencias. Un recibo básico trae solo 4 chequeos y no alcanza el criterio de aceptación de showcase.
archify validate <tipo> <input.json> --json --quality showcase
archify deliver <tipo> <input.json> <output.html> --json --quality showcase
¿Cómo comparar dos versiones de un diagrama de arquitectura?
Con el comando compare, pasándole los dos archivos JSON:
archify compare architecture <base.json> <head.json> [output.html] \
[--receipt ruta] [--json] [--quality standard|showcase] [--repo-root ruta]
Invocado directamente desde el directorio de la skill, como lo muestra el README del proyecto:
node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json
base.json y head.json son archivos IR normales, los mismos que consumen validate y deliver. El flujo entonces es directo: generas el IR en main, lo generas otra vez en tu rama, y comparas los dos.
Archify escribe el HTML y su recibo como un par: si la escritura falla, revierte los archivos anteriores en lugar de dejarte a mitad de camino.
La limitación que no está documentada
compare acepta architecture y nada más. Si le pasas workflow o sequence, sale con el bloque de uso y no hace nada.
Esto no aparece en el README, ni en el SKILL.md, ni en la guía ni en la página de inicio del proyecto: está en el binario. Lo verificamos leyendo el código al momento de publicar esta nota, en septiembre de 2026, así que es posible que cambie más adelante. Por ahora, si tu caso es comparar un flujo de CI o una secuencia de llamadas, esta parte de la herramienta no te sirve.
¿Qué te dice el recibo de la comparación?
El repositorio trae un ejemplo trabajado: una plataforma de checkout que incorpora un módulo antifraude. El resumen del recibo queda así:
"summary": {
"components": { "added": 1, "changed": 1, "evidenceChanged": 0, "removed": 1, "moved": 1 },
"connections": { "added": 1, "changed": 2, "removed": 1, "rerouted": 1 },
"boundaries": { "added": 0, "changed": 2, "removed": 0, "geometryChanged": 0 }
}
Cada elemento lleva un estado — added, removed, changed, evidence-changed, moved, rerouted, geometry-changed — más sus clasificaciones (topology, semantic, scope, evidence, geometry) y los campos exactos que cambiaron, con el nivel de detalle de /sublabel. En la vista renderizada aparecen marcados como +, −, ~, ↔ y E.
El detalle que convierte esto en algo revisable de verdad: el recibo guarda rawSha256 y semanticSha256 de cada versión. Dos diagramas pueden diferir byte a byte y ser idénticos en significado. El segundo hash es el que te permite distinguir un cambio real de arquitectura de un simple reformateo, y es el campo que hace que esto se pueda automatizar en CI.
¿Puedes reutilizar tus diagramas de Mermaid?
Sí, pero no como esperas. El proyecto declara que el parseo automático de Mermaid está fuera de alcance, y al mismo tiempo el SKILL.md instruye al agente para que lea Mermaid buscando topología y significado, y después escriba JSON de Archify desde cero. No se re-renderiza tu Mermaid: se reinterpreta.
El mapeo es este: flowchart y graph van a workflow, o a architecture si lo que quieres es un mapa de componentes; sequenceDiagram va a sequence; stateDiagram va a lifecycle.
¿Cuándo no conviene usar Archify?
Cuando lo que buscas es un editor de dibujo. El proyecto es explícito: el parseo automático de Mermaid, el auto-layout de propósito general, el hosting compartido y la edición WYSIWYG están deliberadamente fuera de alcance. Si quieres pegar Mermaid y obtener el mismo diagrama con mejor tema visual, esta no es la herramienta.
Un punto que conviene mencionar porque a un equipo con criterio de seguridad le va a saltar: Archify puede hacer un GET al manifiesto estable para mostrar un recordatorio opcional de actualización. No descarga ni instala nada. Está declarado en el README y se desactiva así:
ARCHIFY_UPDATE_CHECK_DISABLED=1
¿Qué te llevas de todo esto?
La deriva de arquitectura es invisible en un diff de código. Los componentes se mueven, las conexiones se reencaminan y el diagrama del wiki sigue mostrando el sistema de hace ocho meses. Archify convierte ese cambio en un artefacto que alguien puede revisar, con la salvedad de que hoy solo funciona sobre uno de los cinco tipos.
Instálalo, apúntalo a un repositorio real y genera el IR dos veces: una en main y otra en tu rama. La primera vez que veas el Before/Delta/After de un cambio que creías menor vas a entender para qué sirve.