# Archify: cómo hacer diagramas de arquitectura con Claude Code y comparar dos versiones **URL:** \ **Category:** AI Dev Tools — General\ **Tags:** diagramas-arquitectura, open-source, claude-code, code-review, agent-skills\ **Created:** [15 Septiembre, 2026 16:08 UTC](https://www.yodev.dev/t/archify-como-hacer-diagramas-de-arquitectura-con-claude-code-y-comparar-dos-versiones/5343 "2026-09-15T16:08:55Z")\ **Posts on this page:** 1\ **Page:** 1
**Author:** ![Team](https://yyz1.discourse-cdn.com/flex009/user_avatar/www.yodev.dev/team/32/2092_2.png) [@Team](https://www.yodev.dev/u/Team)\ **Post date:** [15 Septiembre, 2026 16:08 UTC](https://www.yodev.dev/t/archify-como-hacer-diagramas-de-arquitectura-con-claude-code-y-comparar-dos-versiones/5343/1 "2026-09-15T16:08:55Z")
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](https://www.yodev.dev/t/adios-a-los-diagramas-genericos-de-mermaid/4382) y [GitDiagram](https://www.yodev.dev/t/pega-una-url-y-entende-el-repo-gitdiagram-genera-diagramas-de-arquitectura-instantaneamente/3443) 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ímites - `workflow` — CI/CD, aprobaciones, llamadas a herramientas, runbooks - `sequence` — llamadas a APIs, fallback de caché, trazas asíncronas - `dataflow` — pipelines, linaje, límites de consumo - `lifecycle` — 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: ```bash npx skills add tt-a1i/archify -g ``` Cursor y Codex CLI **no** usan ese mismo comando. Si trabajas ahí, son estos: ```bash 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: ```bash 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`. ```bash archify validate --json --quality showcase archify deliver --json --quality showcase ``` ## ¿Cómo comparar dos versiones de un diagrama de arquitectura? Con el comando `compare`, pasándole los dos archivos JSON: ```bash archify compare architecture [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: ```bash 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í: ```json "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í: ```bash 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. > **[GitHub - tt-a1i/archify: Agent skill for beautiful, verifiable...](https://github.com/tt-a1i/archify)** > > Agent skill for beautiful, verifiable architecture, workflow, sequence, data-flow, and lifecycle diagrams—self-contained HTML with motion and crisp export.