Por que os diagramas da sua IA estão mentindo para você
Agentes de IA frequentemente mentem ao mapear sua base de código. Peça a um agente de codificação para diagramar um repositório e você poderá ver Kafka, Redis ou um gateway de API que não existe de fato. Esses diagramas geralmente parecem plausíveis, mas alucinam componentes, tornando todo o visual indigno de confiança e inútil para o desenvolvimento no mundo real. Você não pode confiar em visuais nascidos da ficção.
O Archify enfrenta esse problema de frente. Seu agente de IA não desenha nada; em vez disso, ele descreve o sistema como um JSON tipado estruturado. Essa mudança fundamental separa a descrição precisa do sistema de sua representação visual. O Archify então valida esse JSON rigorosamente antes que qualquer diagrama apareça, garantindo precisão desde o início.
Pense no Archify como um LLVM para mapas de sistema. O agente de codificação de IA atua como o frontend, gerando a descrição inicial do sistema. Essa descrição se torna uma Representação Intermediária (IR) JSON validada, que deve aderir a esquemas rígidos. Somente após passar por essas verificações é que um compilador local transforma a IR no HTML interativo final, garantindo uma saída verificável em várias etapas, em vez de suposições.
Do JSON à confiança: O pipeline de validação
O Archify não permite apenas que uma IA "desenhe" um diagrama. Em vez disso, ele exige que o agente de IA gere uma Representação Intermediária (IR) JSON estruturada e tipada. Essa IR entra então em um pipeline de validação rigoroso e determinístico. O Archify a verifica contra esquemas rígidos e portões atômicos para garantir a integridade, assegurando que a descrição do sistema se sustente.
Crucialmente, um JSON ruim não se torna magicamente um diagrama falho. Se o gráfico for inválido, o Archify interrompe o processo, fornecendo diagnósticos claros e códigos de regra. Isso significa que você recebe mensagens de erro sobre as quais pode agir, em vez de confiar em uma representação visual que está silenciosamente errada. Essa abordagem de "falha fechada" constrói uma confiabilidade fundamental.
Em seguida, o Archify adiciona uma camada poderosa de prova verificável com seu recurso Repo Evidence. Os nós em um diagrama podem exibir um selo "SRC". Clique nele e você será levado diretamente ao código específico, ao commit e até mesmo ao intervalo exato de linhas dentro do seu repositório que comprova a existência do componente. A arquitetura é, portanto, comprovadamente verdadeira, não apenas plausível.
Considere ferramentas como o Mermaid: você pode escrever código de diagrama sintaticamente correto, mas ele ainda pode gerar um diagrama que é logicamente falho ou inclui componentes não encontrados em sua base de código real. A camada de validação abrangente do Archify, combinada com sua evidência de vinculação direta ao código, adiciona uma dimensão crítica de confiança semântica que outras ferramentas simplesmente não possuem.
Mais do que uma imagem: Um mapa de sistema interativo
Após o compilador do Archify validar o JSON, ele produz um arquivo HTML autônomo. Isso não é uma imagem estática; é um mapa de sistema interativo que oferece utilidade genuína. Você pode pesquisar qualquer serviço, revelando instantaneamente suas dependências upstream e downstream. Em seguida, rastreie fluxos complexos de forma interativa, como seguir um caminho de "cache miss" por todo o seu sistema, passo a passo, em vez de apenas olhar para um diagrama estático.
Para pull requests, o recurso de comparação de arquitetura (architecture diffing) oferece uma vantagem crucial. O Archify compara dois snapshots validados do seu sistema, gerando uma comparação visual de "Antes, Delta, Depois". Isso destaca claramente cada mudança arquitetural: quais componentes foram adicionados, removidos ou redirecionados, tornando as revisões de código muito mais robustas e evitando mudanças não intencionais.
Embora o arquivo HTML interativo seja o artefato principal e o recurso mais forte do Archify, ele também oferece recursos robustos de exportação. Você pode gerar facilmente imagens estáticas em formatos como PNG, JPEG, WebP, SVG e WebM. Ele também cria cartões de compartilhamento práticos de 1200x630 para comunicação rápida. Mas entenda, essas exportações são secundárias; o verdadeiro valor está no HTML dinâmico e explorável. Para um mergulho mais profundo nas capacidades do Archify, visite seu repositório no 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.
Gostando do artigo? Receba um assim na sua caixa de entrada toda manhã.
um e-mail por dia · cancele em dois cliques · sem rastreadores de terceiros
Dominando o Archify: Prompts, Armadilhas e PRs
O Archify se destaca quando você faz perguntas específicas e delimitadas. Evite instruções vagas como "mapeie este repositório"; isso geralmente retorna um monte de lixo. Em vez disso, faça uma pergunta precisa, como "Diagramar o fluxo de autenticação do usuário para uma falha de cache", talvez limitando-o a 8-12 nós para clareza e foco. Essa abordagem direcionada garante um resultado significativo e validado.
No entanto, o Archify não é uma solução universal. Ele não é ideal para diagramas simples incorporados diretamente em READMEs do GitHub, pois o GitHub não renderiza sua saída HTML interativa. A ferramenta também requer um AI agent workflow existente usando plataformas como Claude Code ou Cursor, integrando-se como uma habilidade de agente em vez de um aplicativo independente.
Para situações de alto risco, o Archify realmente brilha. Sua saída validada e interativa cria artefatos verificáveis para estágios cruciais de desenvolvimento. Estes incluem:
- Geração de diagramas de arquitetura para revisões de PR, oferecendo um delta claro de mudanças.
- Arquitetar novos recursos dentro de documentos de design.
- Estabelecer uma fonte de verdade confiável e pronta para commit para componentes do sistema em seu repositório.
Essa abordagem transforma diagramas de imagens estáticas em mapas de sistema confiáveis e editáveis, tornando-os uma parte indispensável do seu processo de engenharia.
Perguntas Frequentes
O que é o Archify?
Archify é uma habilidade de agente de código aberto que permite que agentes de codificação de IA, como o Claude, gerem diagramas de arquitetura interativos e verificáveis. Ele funciona fazendo com que o agente produza uma representação JSON estruturada de um sistema, que o Archify então valida e compila em um arquivo HTML independente.
Como o Archify evita diagramas imprecisos?
Em vez de deixar uma IA 'desenhar' uma imagem, o Archify impõe um pipeline de validação rigoroso. A IA deve gerar um grafo JSON tipado que adere a um esquema. Se o JSON for inválido ou descrever um estado impossível, o processo falha com diagnósticos claros, evitando a criação de um diagrama enganoso.
Quais agentes de IA funcionam com o Archify?
O Archify foi projetado como uma habilidade de agente e se integra a vários assistentes de codificação populares, incluindo Claude Code, Cursor, Codex CLI, OpenCode e DeepSeek Harness.
O Archify é um substituto para o Mermaid?
Para diagramas gerados por IA, interativos e verificáveis usados em PRs ou revisões de design, o Archify oferece recursos superiores. No entanto, para diagramas simples incorporados diretamente em um README do GitHub, o Mermaid é frequentemente uma escolha mais direta, já que sua saída é renderizada nativamente pelo GitHub.