archify: o mapa clicável do código que o Claude te escreveu

O que é e porque importa

O Claude escreveu-te um projeto inteiro. Funciona, mas três semanas depois já não sabes o que mexe em quê: que ficheiro fala com a base de dados, o que arriscas se mudares aquela função.

O archify é uma skill, ou seja, um pacote de instruções e scripts que o Claude usa quando é preciso. Pedes o mapa com uma frase: o Claude lê os ficheiros do projeto e o archify desenha um ficheiro HTML, com as partes principais em caixas e as ligações em setas. Antes de o entregar verifica se setas e etiquetas se aguentam; se uma verificação falhar, o Claude corrige.

É gratuito e open source (licença Apache 2.0), com mais de 90.000 estrelas no GitHub no fim de outubro. É para quem constrói sozinho com o Claude Code e quer perceber o próprio projeto ou explicá-lo a um cliente. Também funciona com Codex, Cursor e OpenCode.

1. Instala-o no Claude Code

Precisas do Claude Code com o Node.js no computador. No claude.ai, no navegador, depende de a sandbox ter acesso ao Node.js: foi pensado para o Claude Code. Na pasta do projeto, cola a frase oficial:

Install Archify for me by reading https://raw.githubusercontent.com/tt-a1i/archify/main/llms.txt

O Claude lê as instruções, diz-te o que vai correr e pergunta-te se o queres em todos os projetos (global) ou só neste. Depois instala e corre a verificação doctor: o archify só está pronto se passar.

No terminal é uma linha só. --copy copia os ficheiros em vez de os ligar, --yes salta as perguntas; sem --global só vale na pasta onde a corres:

npx -y skills@latest add https://archify.si --skill archify --agent claude-code --global --copy --yes

Depois a verificação, com o caminho que o instalador te mostra no fim (no Claude Code normalmente ~/.claude/skills/archify):

node ~/.claude/skills/archify/bin/archify.mjs doctor

2. O mapa do teu projeto

Na pasta do projeto, copia este pedido. É o oficial, traduzido:

Analisa este repositório e depois usa o archify para criar um diagrama de alto nível da arquitetura em execução. Mostra de 8 a 12 componentes principais, um percurso principal, as dependências externas e as fronteiras de confiança. Põe os detalhes em fichas em vez de acrescentar mais setas.

As dependências externas são os serviços que não são teus: base de dados na cloud, pagamentos, email. As fronteiras de confiança são onde os dados passam para uma parte que não controlas, como do navegador para o teu servidor. E 8 a 12 partes é o essencial: 40 caixas ninguém as lê.

O Claude segue quem chama quem, desde a entrada do projeto até onde os dados entram, saem ou são guardados. No fim dá-te o link para o ficheiro, guardado também na pasta .archify do projeto.

Se o projeto é público no GitHub, acrescenta «liga cada componente aos ficheiros e às linhas que o provam»: as caixas ficam marcadas com SRC e abrem o código de onde vêm. Faz o commit antes: o archify cita o último commit, não as alterações por guardar.

3. Sem código: parte de uma ideia

Não precisas de repositório: basta uma ideia, um plano, um processo. O Claude só precisa de uma pasta qualquer onde escrever o ficheiro.

Usa o archify para transformar esta descrição num diagrama de arquitetura de alto nível: [quem usa o produto, as partes principais, o percurso principal, os serviços externos]. Não há repositório. Pergunta-me só os factos que mudam mesmo o diagrama, marca como desconhecido o que não sabes e mantém um percurso principal claro.

Para o experimentar em dez segundos: «Usa o archify para desenhar: Browser -> API -> cache Redis -> PostgreSQL se a cache não tiver o dado». Depois continuas, uma alteração por mensagem:

• «Acrescenta a autenticação.»
• «Destaca o percurso quando a cache não tem o dado.»
• «Passa a autenticação para a esquerda.»
• «Muda para o tema claro.»

4. Uma só página para quem não programa

Às vezes a pergunta é «como funciona isto». O archify também faz uma só página: primeiro a resposta, depois um painel por pergunta. Os passos ficam ao lado do diagrama e, enquanto lês, acendem as partes de que falam.

Usa o archify para responder com uma só página, para enviar a um cliente que não programa: como funciona [o pagamento] na minha app, desde o clique do utilizador até [ao recibo]? Primeiro a conclusão, depois os passos ao lado do diagrama do percurso. Palavras simples, sem jargão.

Também é um ficheiro HTML: exporta-se como imagem longa ou imprime-se em PDF.

5. As teclas para explorar o mapa

Abre o ficheiro no navegador do computador. A partir daqui o archify já não é preciso: está tudo dentro do ficheiro.

• Clique numa parte: acendem-se as partes ligadas e abre-se a sua ficha, com o que entra e o que sai. Esc fecha-a.
• Upstream e Downstream, na ficha: tudo o que leva àquela parte, ou tudo o que parte dali, passo a passo.
• R: o percurso. Clicas na partida e na chegada, o archify mostra o caminho mais curto ao longo das setas e podes pô-lo a correr.
• /: procura uma parte pelo nome. ?: o guia do mapa, com as ações que esse ficheiro permite.
• E: exportar. T: tema claro ou escuro. S: mudar de estilo. F: apresentação, com o mapa a ocupar a janela toda, prático numa chamada.
• + e - para o zoom, 0 para voltar à vista inicial. Live anima as setas, Still para-as.

As setas são as que o Claude escreveu no mapa: Upstream e Downstream seguem essas, não o programa a correr. Dizem-te onde olhar, não o impacto de uma alteração: o código relês tu.

6. Envia-o a um cliente

O mapa é um ficheiro só. Envias por email ou numa conversa, quem o recebe abre-o no navegador e tem tudo, sem instalar nada. Só os links externos, como os do código no GitHub, precisam de ligação.

Para uma imagem a pôr num diapositivo, carrega em E:

• O mapa inteiro em PNG para a área de transferência, ou para descarregar em PNG, JPEG, WebP, SVG e como vídeo WebM animado.
• Route Share Card: depois de traçares um percurso com R, uma imagem de 1200×630 com esse percurso em destaque e o resto do mapa à volta.
• Reach Share Card: a mesma coisa, depois de Upstream ou Downstream.

As imagens não se clicam: se o cliente tiver de explorar, envia-lhe o HTML. E antes relê etiquetas e fichas: podem ter detalhes do teu código que não queres mostrar.

Os erros mais comuns

• Pedir «desenha o projeto todo»: sai um mapa que não se lê. Pede 8 a 12 partes e um percurso, ou uma funcionalidade de cada vez.
• Tomar as setas como verdade: as verificações do archify dizem que o desenho está bem feito, não que o programa se comporta assim.
• Abrir o mapa no telemóvel: não foi pensado para ecrãs pequenos. Usa o computador.
• Procurar um link para o partilhar online: o archify não aloja os mapas. Envias o ficheiro ou uma imagem.

Checklist

• Instalei o archify e a verificação doctor passou
• Pedi o mapa do meu projeto com 8 a 12 partes e um percurso
• Cliquei numa parte e experimentei Upstream e Downstream
• Tracei um percurso com R e exportei a sua Share Card
• Enviei o ficheiro HTML a alguém e abriu-o sem instalar nada

Perguntas frequentes