Por qué los diagramas de tu IA te están mintiendo
Los agentes de IA a menudo mienten al mapear tu base de código. Pídele a un agente de codificación que diagrame un repositorio y podrías ver Kafka, Redis o una puerta de enlace de API que en realidad no existe. Estos diagramas suelen parecer plausibles, pero alucinan componentes, lo que hace que toda la imagen sea poco confiable e inútil para el desarrollo en el mundo real. No puedes confiar en imágenes nacidas de la ficción.
Archify aborda este problema de frente. Su agente de IA no dibuja nada; en cambio, describe el sistema como un JSON tipado y estructurado. Este cambio fundamental separa la descripción precisa del sistema de su representación visual. Archify luego valida este JSON rigurosamente antes de que aparezca cualquier diagrama, asegurando la precisión desde cero.
Piensa en Archify como LLVM para mapas de sistemas. El agente de codificación de IA actúa como el frontend, generando la descripción inicial del sistema. Esa descripción se convierte en una Representación Intermedia (IR) JSON validada, que debe adherirse a esquemas estrictos. Solo después de pasar estas comprobaciones, un compilador local convierte la IR en el HTML interactivo final, garantizando una salida verificable de múltiples etapas en lugar de conjeturas.
De JSON a la confianza: El pipeline de validación
Archify no solo permite que una IA "dibuje" un diagrama. En cambio, exige que el agente de IA genere una Representación Intermedia (IR) JSON estructurada y tipada. Esta IR entra luego en un pipeline de validación riguroso y determinista. Archify la verifica contra esquemas estrictos y puertas atómicas para garantizar su integridad, asegurando que la descripción del sistema sea sólida.
Fundamentalmente, un JSON incorrecto no se convierte mágicamente en un diagrama defectuoso. Si el gráfico no es válido, Archify detiene el proceso, proporcionando diagnósticos claros y códigos de regla. Esto significa que obtienes mensajes de error sobre los que puedes actuar, en lugar de confiar en una representación visual que es silenciosamente incorrecta. Este enfoque de "fallo cerrado" construye una fiabilidad fundamental.
A continuación, Archify añade una potente capa de prueba verificable con su función Repo Evidence. Los nodos en un diagrama pueden mostrar una insignia "SRC". Haz clic en ella y saltarás directamente al código específico, al commit e incluso al rango de líneas exacto dentro de tu repositorio que demuestra la existencia del componente. Por lo tanto, la arquitectura es demostrablemente verdadera, no solo plausible.
Considera herramientas como Mermaid: puedes escribir código de diagrama sintácticamente correcto, pero aun así podría generar un diagrama que sea lógicamente defectuoso o que incluya componentes que no se encuentran en tu base de código real. La capa de validación integral de Archify, junto con su evidencia de enlace directo al código, añade una dimensión crítica de confianza semántica de la que otras herramientas simplemente carecen.
Más que una imagen: Un mapa de sistema interactivo
Después de que el compilador de Archify valida el JSON, produce un archivo HTML autónomo. Esto no es una imagen estática; es un mapa de sistema interactivo que ofrece una utilidad genuina. Puedes buscar cualquier servicio, revelando al instante sus dependencias ascendentes y descendentes. Luego, rastrea interactivamente flujos complejos, como seguir una ruta de "fallo de caché" a través de todo tu sistema, paso a paso, en lugar de solo mirar un diagrama estático.
Para las solicitudes de extracción (pull requests), la función de comparación de arquitectura (architecture diffing) proporciona una ventaja crucial. Archify compara dos instantáneas validadas de tu sistema, generando una comparación visual de "Antes, Delta, Después". Esto destaca claramente cada cambio arquitectónico: qué componentes se agregaron, eliminaron o redirigieron, haciendo que las revisiones de código sean mucho más robustas y evitando cambios no deseados.
Aunque el archivo HTML interactivo es el artefacto principal y la característica más fuerte de Archify, también ofrece capacidades de exportación robustas. Puede generar fácilmente imágenes estáticas en formatos como PNG, JPEG, WebP, SVG y WebM. También crea prácticas tarjetas para compartir de 1200x630 para una comunicación rápida. Pero tenga en cuenta que estas exportaciones son secundarias; el verdadero valor está en el HTML dinámico y explorable. Para profundizar en las capacidades de Archify, visite su repositorio de GitHub: tt-a1i/archify: Agent skill for beautiful, verifiable architecture, workflow, sequence, data-flow, and lifecycle diagrams—self-contained HTML with motion and crisp export. - GitHub.
¿Te está gustando? Recibe uno así en tu bandeja cada mañana.
un correo al día · date de baja en dos clics · sin rastreadores de terceros
Dominando Archify: Prompts, trampas y PRs
Archify destaca cuando le haces preguntas específicas y delimitadas. Evita instrucciones vagas como "mapea este repositorio"; eso suele devolver un montón de basura. En su lugar, haz una pregunta precisa, como "Diagrama el flujo de autenticación de usuario para un fallo de caché", limitándolo quizás a 8-12 nodos para mayor claridad y enfoque. Este enfoque dirigido garantiza un resultado significativo y validado.
Sin embargo, Archify no es una solución universal. No es ideal para diagramas simples incrustados directamente en archivos README de GitHub, ya que GitHub no renderiza su salida HTML interactiva. La herramienta también requiere un AI agent workflow existente que utilice plataformas como Claude Code o Cursor, integrándose como una habilidad de agente en lugar de una aplicación independiente.
Para situaciones de alto riesgo, Archify realmente brilla. Su salida validada e interactiva crea verifiable artifacts para etapas cruciales de desarrollo. Estos incluyen:
- Generar diagramas de arquitectura para revisiones de PR, ofreciendo un delta claro de los cambios.
- Arquitectar nuevas características dentro de documentos de diseño.
- Establecer una source of truth confiable y lista para confirmar para los componentes del sistema en su repositorio.
Este enfoque transforma los diagramas de imágenes estáticas en mapas de sistema confiables y editables, convirtiéndolos en una parte indispensable de su proceso de ingeniería.
Preguntas frecuentes
¿Qué es Archify?
Archify es una habilidad de agente de código abierto que permite a los agentes de codificación de IA como Claude generar diagramas de arquitectura interactivos y verificables. Funciona haciendo que el agente produzca una representación JSON estructurada de un sistema, que Archify luego valida y compila en un archivo HTML autónomo.
¿Cómo evita Archify los diagramas inexactos?
En lugar de dejar que una IA 'dibuje' una imagen, Archify aplica un estricto proceso de validación. La IA debe generar un gráfico JSON tipado que se adhiera a un esquema. Si el JSON no es válido o describe un estado imposible, el proceso falla con diagnósticos claros, evitando la creación de un diagrama engañoso.
¿Qué agentes de IA funcionan con Archify?
Archify está diseñado como una habilidad de agente y se integra con varios asistentes de codificación populares, incluidos Claude Code, Cursor, Codex CLI, OpenCode y DeepSeek Harness.
¿Es Archify un reemplazo para Mermaid?
Para diagramas generados por IA, interactivos y verificables utilizados en PRs o revisiones de diseño, Archify ofrece características superiores. Sin embargo, para diagramas simples incrustados directamente en un archivo README de GitHub, Mermaid suele ser una opción más sencilla, ya que su salida es renderizada de forma nativa por GitHub.