Archify é uma skill de agente open-source que transforma qualquer codebase ou descrição de sistema em um diagrama de arquitetura polido e interativo — um único arquivo HTML autossuficiente, validado antes de renderizar. Funciona com Claude Code, Cursor, Codex CLI e OpenCode, instala-se com um único comando npx, é agnóstico em relação ao modelo e está no topo do GitHub Trending com mais de 30.000 estrelas. Se os diagramas da sua equipe ficam desatualizados duas semanas depois de desenhados, esta é a solução mais direta disponível.
Por que diagramas de arquitetura são um gargalo
A maioria dos diagramas de arquitetura está errada em poucas semanas. Alguém desenha o caminho feliz uma vez, o código evolui, e o diagrama silenciosamente se torna um artefato histórico que ninguém ousa atualizar. O Archify ataca o problema na origem: em vez de renderizar uma descrição escrita à mão, o agente lê o repositório real, gera uma representação intermediária JSON tipada e só então o Archify compila deterministically essa IR em um diagrama. O pipeline é fail-closed — se uma validação de schema, layout de nó, rótulo ou aresta falhar, você recebe o erro específico e a correção permitida, não uma imagem bonita que mente sobre o seu sistema.
Como funciona: IR em JSON, validação e só depois renderização
O Archify separa “entender” de “desenhar” — as duas coisas que costumam dar errado juntas. O agente cuida do entendimento: lê seu código, identifica componentes e relacionamentos e produz JSON tipado seguindo o schema do Archify. Em seguida, o Archify aplica regras determinísticas: valida a estrutura, checa layout, rótulos e conflitos de arestas, e rejeita tudo o que não passar. Uma fatia mínima dessa IR se parece com isto:
{
"type": "architecture",
"theme": "dark",
"nodes": [
{ "id": "browser", "label": "Browser", "kind": "client" },
{ "id": "api", "label": "API Gateway", "kind": "service" },
{ "id": "cache", "label": "Redis Cache", "kind": "store" },
{ "id": "db", "label": "PostgreSQL", "kind": "store" }
],
"edges": [
{ "from": "browser", "to": "api", "label": "HTTPS" },
{ "from": "api", "to": "cache", "label": "read/write" },
{ "from": "api", "to": "db", "label": "fallback" }
]
}Somente depois de a IR passar pela validação o Archify renderiza um arquivo HTML/SVG autossuficiente que você pode abrir em qualquer navegador: nós pesquisáveis, caminhos rastreáveis entre quaisquer dois nós, visões de upstream/downstream, temas claro e escuro e exportação para PNG, SVG, WebM e cards de compartilhamento. Cinco tipos de diagrama são suportados — arquitetura, workflow, sequência, fluxo de dados e ciclo de vida — além de três presets visuais (Classic, Signal Flow, Blueprint). Essa filosofia de verificação primeiro reflete para onde as boas ferramentas de agente estão convergindo, o mesmo pensamento por trás das checagens de alucinação de fonte zero na saída de agentes.
Instale com um comando
O Archify é distribuído como uma skill de agente padrão, então a configuração é uma linha:
npx skills add tt-a1i/archify -gEle se encaixa nos diretórios de skills que seu agente já lê: ~/.claude/skills para o Claude Code, ~/.agents/skills para o Codex CLI e o gerenciador de skills do Cursor. Sem chaves de API, sem serviço em nuvem, sem servidor para rodar — tudo renderiza localmente.
Seu primeiro diagrama: um prompt, um arquivo HTML
Abra um repositório que você precisa entender e peça ao agente:
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. Put supporting detail in cards instead of adding more edges.Delimitar o pedido importa mais do que parece. A formulação “8–12 componentes, um caminho primário, limites de confiança” impede que o agente despeje todos os arquivos na imagem — essa é a diferença entre um diagrama que as pessoas leem e um papel de parede. Se você já conhece a forma do sistema e só quer um fluxo limpo, descreva-o diretamente:
Use archify to draw this login flow: Browser -> Web App -> API -> JWT validation -> Redis session lookup -> PostgreSQL fallback. Keep the cache-miss path secondary.Vá além: deltas para revisão de PR
O recurso mais subestimado é a visão delta. O Archify pode comparar dois snapshots validados e renderizar o resultado como Antes / Delta / Depois, marcando exatamente quais nós foram adicionados, removidos, alterados, movidos ou redirecionados. Isso transforma o diagrama de arquitetura de um artefato pontual em algo que participa do code review — execute-o na branch base e na branch do PR, e depois examine o diff em vez de reler o sistema inteiro. Se você está conectando agentes ao seu pipeline de entrega, combine-o com o AI-Native SDLC Playbook para construir fluxos de CI e revisão amigáveis a agentes, e leia o guia de estado durável de agentes quando seus agentes de código começarem a executar tarefas de longa duração que precisam de checkpointing.
Dicas práticas
- Sempre peça uma visão delimitada. Prompts sem limites do tipo “desenhe tudo” produzem grafos ilegíveis.
- Faça commit do HTML gerado no repositório e regenere a cada merge — trate-o como documentação que precisa estar sempre atualizada.
- Use a visão delta para revisões de PR; ela destaca exatamente o que mudou entre duas versões.
- Onde houver suporte, fixe os nós a arquivos-fonte verificados por revisão, para que o diagrama carregue evidências em vez de achismos.
O Archify não é um monitor de runtime e não pode provar que o diagrama corresponde ao estado de produção — a precisão ainda depende do código que ele lê, do seu prompt e da análise do agente. Mas como ferramenta para transformar um codebase frio e desconhecido em um mapa de sistema navegável em minutos, é a melhor opção open-source hoje.
FAQ
P: Quais agentes de código o Archify suporta?
R: Claude Code, Cursor, Codex CLI e OpenCode. Instala-se como uma skill padrão com npx skills add tt-a1i/archify e funciona com qualquer modelo por baixo.
P: O Archify é apenas um Mermaid mais bonito?
R: Não. O Mermaid renderiza texto que você escreve; o Archify valida uma IR JSON tipada antes de renderizar, falha de forma fechada com entradas inválidas e adiciona interatividade pesquisável, além de comparações Antes/Delta/Depois para revisão de PR.
P: O diagrama gerado reflete o sistema em produção?
R: Não automaticamente. O Archify não é uma ferramenta de monitoramento; a corretude depende do código que ele lê, do seu prompt e da análise do agente. Execute-o em código atual e regenere a cada merge.
Recursos: Archify no GitHub · Registro OpenAgentSkill
