Esta Ferramenta Open-Source Faz o Claude Criar Diagramas de Arquitetura

PortuguêsالعربيةDeutschEnglishEspañolFrançaisहिन्दीBahasa Indonesia日本語한국어Русский中文
BBetter Stack
Computing/Software

Transcript

00:00:00Peça aos nossos agentes de código para mapear um repositório e acabamos com um Kafka, Redis ou API gateway que nem existe.
00:00:07Os diagramas geralmente parecem decentes, mas deixam muita coisa de fora.
00:00:10Apresento o Archify, onde o agente não desenha absolutamente nada.
00:00:14Ele gera um gráfico tipado, o Archify o valida e, em seguida, renderiza o diagrama.
00:00:19Esta pode ser uma das melhores formas de visualizar a nossa arquitetura.
00:00:23Vamos descobrir já a seguir.
00:00:30Ora, o nosso modelo provavelmente nem deveria estar a desenhar o diagrama.
00:00:33O funcionamento do Archify baseia-se em descrever o sistema como JSON estruturado e tipado.
00:00:37Isso é validado e só depois é que um compilador local o transforma no HTML final.
00:00:42Se o gráfico for inválido, ocorre uma falha.
00:00:45Este é o Archify, que conquistou 44.000 estrelas em poucos meses por se integrar diretamente no Cloud Code, Cursor e Codex.
00:00:53Por isso, quero testá-lo a fundo.
00:00:54Vou instalar o Archify, apontá-lo para um repositório e fazê-lo responder a uma pergunta sobre arquitetura.
00:01:00Depois, veremos se conseguimos utilizar este resultado num PR.
00:01:03E há casos de uso em que eu definitivamente não usaria isto, mas vamos falar sobre eles em breve.
00:01:08Se gostas de ferramentas de programação que aceleram o teu fluxo de trabalho, subscreve o canal.
00:01:11Temos vídeos novos a toda a hora.
00:01:13Muito bem, a instalação resume-se a este único comando aqui.
00:01:17E não se trata de uma aplicação que estou a configurar.
00:01:19Na verdade, é uma competência de agente.
00:01:22Após a instalação, posso usar a mesma competência a partir do Cloud Code ou de qualquer outra ferramenta que mencionei antes,
00:01:28sem precisar de mudar de editor ou sequer do meu fluxo de trabalho.
00:01:32Agora posso enviar-lhe uma tarefa a sério.
00:01:34Não lhe vou pedir para desenhar a arquitetura de todo este repositório.
00:01:37Isso até parece bem.
00:01:39Mas, no fim de contas, isso só nos devolveria uma pilha de lixo.
00:01:42Por isso, vou fazer uma pergunta concreta.
00:01:45Usa o Archify, diagrama de arquitetura com 8 a 12 nós no máximo.
00:01:49O que acontece numa falha de cache neste serviço?
00:01:52Inclui apenas caixas que existam neste repositório.
00:01:54Se não conseguires provar um componente, omite-o.
00:01:58Fornece um HTML autossuficiente.
00:02:00É tipo um plano, uma pergunta.
00:02:02Aproximadamente 8 a 12 nós.
00:02:04Porque se pedirmons a um agente para mapear toda a nossa base de código, será que simplificamos alguma coisa ou
00:02:08tornámos tudo mais difícil de entender?
00:02:10Agora acabei de transformar a árvore do meu repositório num fluxograma.
00:02:14O agente escreve a arquitetura em formato JSON.
00:02:16Depois, o Archify valida-a.
00:02:18Também posso executar essa validação diretamente, tal como vou fazer aqui.
00:02:23Esta é, na verdade, uma funcionalidade espetacular que descobri nisto.
00:02:27Os nós também podem incluir evidências do repositório associadas a um commit e a um intervalo específico de linhas.
00:02:32Se essa prova não estiver lá, o nó não recebe um emblema SRC só porque parece
00:02:37convincente na resposta.
00:02:39Muito bem.
00:02:39Agora, de que forma é que isto está a ajudar?
00:02:41Isto parece um diagrama de arquitetura.
00:02:43Sim, claro, mas não tens de o utilizar estritamente como tal.
00:02:46Posso procurar um serviço específico dentro dele.
00:02:50Posso clicar nele e ver imediatamente o que está a montante e a jusante.
00:02:55Depois, posso reproduzir essa rota e seguir o caminho da falha de cache através do sistema.
00:02:59Portanto, em vez de olhar para 10 setas e tentar rastreá-las mentalmente, agora posso percorrê-las
00:03:05passo a passo.
00:03:06E para além disso, posso exportá-lo.
00:03:08Posso copiar um PNG ou gerar um cartão de partilha de 1200 por 36.
00:03:13A verdadeira diferença aqui é o Mermaid, certo?
00:03:17A ferramenta Mermaid é normalmente algo que leio.
00:03:20Isto é algo a que posso colocar perguntas e fazer confrontos.
00:03:23E o movimento não está a ser usado para esconder uma estrutura fraca; exporta o diagrama como imagem estática
00:03:28e o significado continua lá para subsistir.
00:03:31E há um segundo caso de uso que pode ser ainda mais útil, certo?
00:03:35O que é que achas?
00:03:36Bem, estou a pensar na revisão de código.
00:03:38Digamos que este é o sistema antes de uma alteração.
00:03:41Depois, adiciono um worker de tentativas já existente.
00:03:44Posso dizer ao agente para atualizar a arquitetura sem inventar coisas do nada.
00:03:49O Archify consegue comparar os dois instantâneos validados: adicionado, removido, movido, reencaminhado.
00:03:54Portanto, em vez de obter dois diagramas gerados, consigo ver o que mudou efetivamente.
00:03:59E o editor continua a ser apenas o chat.
00:04:02Mas se quiser que esta arquitetura sobreviva para a próxima sessão do agente, faço commit do JSON.
00:04:07Neste ponto do jogo, a forma mais fácil de entender o Archify é esta.
00:04:11Para a VM de HTML de mapas de sistema, o agente de código funciona como a interface.
00:04:15O JSON é a representação intermédia.
00:04:19O HTML é o resultado compilado.
00:04:21E essa camada intermédia está a fazer grande parte do trabalho.
00:04:24O JSON segue esquemas rigorosos.
00:04:26Campos desconhecidos podem chumbar na validação.
00:04:28E existem cinco modos de diagrama.
00:04:30Arquitetura, fluxo de trabalho, sequência, fluxo de dados e ciclo de vida.
00:04:34Mas uma das decisões mais interessantes é o que o modelo não controla.
00:04:38O layout.
00:04:39O modelo descreve o sistema.
00:04:41Ele não decide exatamente onde cada caixa vai ficar colocada.
00:04:44Eles tentaram usar o Mermaid com temas e layout automático por graus.
00:04:48Não era melhor do que o Mermaid normal.
00:04:51E a validação também falha de forma restrita.
00:04:54JSON incorreto nunca se transforma num diagrama bonito.
00:04:58Recebes diagnósticos, códigos de regras e reparações suportadas.
00:05:02Ora, de tudo isto, aqui está talvez onde eu não usaria o Archify.
00:05:06Se precisas de um diagrama diretamente dentro do teu ficheiro readme, talvez não.
00:05:10Pode demorar algum tempo.
00:05:11O GitHub renderiza-o.
00:05:12O HTML do Archify não.
00:05:15O Archify está a resolver um tipo de problema muito diferente.
00:05:18Já existe um agente no processo.
00:05:20Esse agente está a produzir um artefacto de arquitetura.
00:05:23Talvez vá parar a um PR.
00:05:25Talvez vá parar a uma revisão de design.
00:05:27É aí que o output validado começa a importar.
00:05:30No geral, há muita coisa de que gostei nisto.
00:05:32Vive dentro de ferramentas que já usamos todos os dias.
00:05:35Posso exportar o resultado.
00:05:38As evidências do repositório dão-me algo concreto para verificar de facto.
00:05:41E como a arquitetura é estruturada, posso continuar a editá-la sem que as coisas mudem do nada ao longo do tempo.
00:05:46Também tem um aspeto suficientemente bom para eu provavelmente não sentir necessidade de o redesenhar no Figma ou noutra ferramenta do género.
00:05:53Mas convém dizer que, ao mesmo tempo, o Archify não conhece a tua arquitetura.
00:05:58Um gráfico pode ser perfeitamente válido e continuar a descrever o sistema errado.
00:06:02Ainda tens de o ler.
00:06:03Como sabemos, um modelo fraco muitas vezes criará JSON que funciona, mas que continua a ter um mau aspeto.
00:06:08E se o destino final do teu diagrama for um readme, o Mermaid ainda poderá ser melhor opção.
00:06:13Com o Archify, provavelmente estás a fazer commit do JSON e HTML ou a exportar uma imagem.
00:06:18E há um erro que eu evitaria a todo o custo.
00:06:21Não o apontes a um repositório gigante a dizer para mapear tudo.
00:06:25Acho que consegues adivinhar como é que isso vai correr, porque provavelmente só vais receber lixo de volta.
00:06:29Mas isso não é propriamente uma falha do Archify.
00:06:32É mais uma pergunta mal feita.
00:06:34Se já trabalhas com agentes de código e crias regularmente diagramas que vais consultar no futuro ou que outros possam consultar, isto faz todo o sentido.
00:06:42Revisões de PR, documentos de design, eu provavelmente usaria isto.
00:06:47Eu não instalaria isto só porque quero uma versão mais bonita de algo que já temos, como o Mermaid por exemplo.
00:06:52E definitivamente não esperaria que fizesse engenharia inversa de nada por mim.
00:06:55A barreira para experimentar é mínima.
00:06:58Um comando NPX, Node na máquina.
00:07:00Não há pesos de modelos aqui.
00:07:02O meu M4 Pro é basicamente irrelevante nisto.
00:07:05Mas há uma regra que eu manteria.
00:07:07Uma pergunta por ficheiro.
00:07:08Se não consegues dizer claramente que pergunta o diagrama está a responder, não o geres.
00:07:14Sou o Josh da BetterStack.
00:07:15Se gostas de dicas e truques de programação como este, não deixes de subscrever o canal.
00:07:19Vemo-nos num próximo vídeo.
00:07:20Vemo-nos num próximo vídeo.

Key Takeaway

O Archify transforma repositórios de código em diagramas interativos de arquitetura através de representações intermediárias em JSON validado e HTML compilado localmente.

Highlights

  • O Archify substitui a geração direta de diagramas por modelos de IA por um fluxo baseado em JSON estruturado, tipado e validado localmente.

  • Os nós gerados pelo Archify podem incluir evidências do repositório vinculadas a um commit e a um intervalo específico de linhas.

  • O compilador local do Archify suporta cinco modos de diagrama: arquitetura, fluxo de trabalho, sequência, fluxo de dados e ciclo de vida.

  • O Archify compara instantâneos validados antes e depois de alterações para mostrar visualmente adições, remoções e redirecionamentos numa revisão de código.

  • A ferramenta não executa o layout automático dos diagramas através do modelo, delegando a estruturação visual ao compilador local.

Timeline

Funcionamento e problemas dos diagramas gerados por IA

  • Os agentes de código criam frequentemente diagramas imprecisos com componentes inexistentes ao mapear repositórios inteiros.
  • O Archify utiliza um sistema em que o modelo descreve o sistema em JSON estruturado, que é validado antes de ser compilado num HTML local.
  • A ferramenta integra-se diretamente em editores e ferramentas de desenvolvimento como Cloud Code, Cursor e Codex.

Os agentes tradicionais geram diagramas visuais diretamente que muitas vezes omitem detalhes críticos ou inventam elementos como gateways de API inexistentes. O Archify resolve esta falha ao exigir que o modelo produza um gráfico tipado em JSON estruturado. Esse formato passa por uma validação estrita antes que um compilador local gere o HTML final, impedindo que dados incorretos passem inadvertidamente.

Instalação e criação de diagramas orientados por perguntas

  • A instalação executa-se através de um único comando baseado em competências de agente, sem exigir configuração de aplicações complexas.
  • Perguntas delimitadas a 8 a 12 nós evitam a criação de volumes excessivos de dados inúteis a partir de bases de código completas.
  • Os nós incorporam emblemas SRC baseados em evidências reais do repositório associadas a commits e linhas específicas.

A configuração da ferramenta resume-se a um comando simples que adiciona a competência ao ambiente de trabalho existente. Em vez de solicitar o mapeamento de todo o repositório, formular perguntas restritas garante um fluxograma gerenciável. Os nós gerados incluem validação de evidências do código fonte, garantindo que nenhum componente seja incluído apenas por parecer convincente na resposta do modelo.

Interação, exportação e comparação de alterações

  • Os utilizadores podem clicar em serviços específicos no diagrama interativo para rastrear caminhos a montante e a jusante.
  • O Archify compara dois instantâneos JSON validados para destacar visualmente adições, remoções e reencaminhamentos em revisões de código.
  • O processo utiliza cinco modos distintos: arquitetura, fluxo de trabalho, sequência, fluxo de dados e ciclo de vida.

A interface interativa permite acompanhar fluxos complexos passo a passo, substituindo a leitura mental de múltiplas setas. Durante revisões de código, a ferramenta analisa o estado do sistema antes e depois de uma modificação para exibir exatamente o que mudou entre os instantâneos. O layout visual é determinado por um compilador dedicado e não pelas decisões de posicionamento do modelo de linguagem.

Limitações e cenários de utilização inadequados

  • O Archify não foi concebido para inserção direta em ficheiros readme do GitHub devido ao formato HTML autossuficiente.
  • Um gráfico perfeitamente válido pode continuar a descrever incorretamente a arquitetura se o modelo interpretador falhar na lógica.
  • A aplicação de perguntas a repositórios gigantes sem filtros adequados resulta em dados irrelevantes.

A ferramenta destina-se primariamente a artefactos de arquitetura gerados por agentes em revisões de PR ou documentos de design, e não a documentação estática em Markdown renderizada diretamente pelo GitHub. Embora o JSON gerado passe na validação estrutural, a verificação lógica do conteúdo ainda depende da análise humana. Restringir a utilização a uma pergunta específica por ficheiro otimiza os resultados obtidos.

Community Posts

No posts yet. Be the first to write about this video!

Write about this video