Diagrama de arquitetura com Claude IA: tutorial completo com Cocoon-AI
TL;DR: O Cocoon-AI Architecture Diagram Generator é uma skill gratuita para Claude.ai que gera diagramas de arquitetura dark-themed em HTML via prompt de linguagem natural. Você instala em 3 minutos, descreve sua stack em texto e exporta um arquivo HTML pronto para abrir em qualquer navegador. Neste tutorial mostro como instalar, usar e gero o diagrama do meu próprio sistema de agentes como exemplo real.
Gerar um diagrama de arquitetura com Claude IA leva menos tempo do que abrir o Lucidchart. Mas a maioria das pessoas ainda não sabe que isso é possível.
Documentar arquitetura é chato. Todo mundo sabe que precisa fazer, ninguém gosta de fazer, e o diagrama fica desatualizado na semana seguinte.
Já perdi conta de quantas vezes abri um Lucidchart, arrastei alguns boxes, me distraí ajustando seta, e fechei sem terminar. A ferramenta fica no caminho do pensamento.
O problema não é falta de disciplina. É que as ferramentas de diagrama foram pensadas para quem gosta de design, não para quem quer comunicar arquitetura rápido.
Semana passada encontrei uma abordagem diferente: Cocoon-AI Architecture Diagram Generator, uma skill para o Claude.ai que gera diagramas profissionais a partir de uma descrição em texto. Instalei, testei com o meu próprio sistema de agentes, e o resultado foi bom o suficiente para virar o meu padrão.
Aqui está o tutorial completo.
O que é o Cocoon-AI Architecture Diagram Generator?
O Cocoon-AI Architecture Diagram Generator é uma skill open source para Claude.ai que recebe uma descrição em linguagem natural da sua arquitetura e gera um diagrama dark-themed como arquivo HTML autossuficiente. O HTML inclui SVG, CSS e tipografia embutidos, sem dependências externas.
A ferramenta usa codificação semântica de cores: frontend em ciano, backend em esmeralda, banco de dados em violeta, serviços de nuvem em âmbar, segurança em rosa. O resultado é legível, profissional e abre em qualquer navegador moderno.
O repositório está disponível gratuitamente no GitHub do Cocoon-AI. A skill em si não custa nada. O único requisito é uma assinatura paga do Claude (Pro, Max, Team ou Enterprise).
Como instalar a skill de diagrama de arquitetura no Claude.ai
O processo tem quatro passos e leva menos de 3 minutos.
Passo 1: Acesse o repositório no GitHub e baixe o arquivo architecture-diagram.zip.
Passo 2: No Claude.ai, abra as configurações (ícone no canto inferior esquerdo).
Passo 3: Vá em Capabilities → Skills e clique em + Add.
Passo 4: Selecione Upload a skill e faça o upload do arquivo .zip. Ative o toggle para habilitar.
Pronto. A skill fica disponível em todas as conversas enquanto o toggle estiver ativo.
Se você usa Claude Code CLI, tem uma alternativa: extraia o conteúdo do zip para ~/.claude/skills/ e a skill fica disponível automaticamente no terminal.
# Para usuários do Claude Code CLI
unzip architecture-diagram.zip -d ~/.claude/skills/
Como descrever sua arquitetura para o Claude gerar um diagrama útil?
Para gerar um diagrama de arquitetura com o Claude IA, liste os componentes em texto puro, agrupados por camada: frontend, backend, banco de dados, serviços externos. Inclua o nome do componente, a tecnologia usada e como os componentes se conectam. Quanto mais específico, melhor o resultado.
Do texto ao diagrama em 3 passos
O prompt segue um padrão simples:
Use your architecture diagram skill to create a diagram from this description:
[sua descrição aqui]
Depois que o Claude gerar o primeiro diagrama, você itera no chat: "adiciona um Redis cache entre a API e o banco" ou "separa o frontend mobile do web". Cada ajuste atualiza o HTML em tempo real.
Exemplo básico: web app com auth
React frontend, Node.js/Express API, PostgreSQL database, Redis cache for sessions, JWT authentication, deployed on AWS EC2
Exemplo: serverless na AWS
CloudFront CDN → API Gateway → Lambda functions → DynamoDB (primary) + S3 (assets) + Cognito (auth)
Como fica o diagrama de um sistema de agentes real gerado pelo Claude?
Para testar, usei o próprio sistema de conteúdo que roda este blog: Claude Code CLI dispara um orquestrador, que aciona writers em paralelo e um revisor em sequência, e os posts chegam ao Next.js como arquivos .md. O Claude gerou o HTML completo em menos de 30 segundos a partir de uma descrição em texto.
O sistema usa Claude Code como orquestrador central. A descrição que passei para o Claude:
Content generation system for ThiagoThomaz.com:
Entry point: Claude Code CLI (terminal)
Orchestrator agent: interprets content requests, dispatches subagents
Writer agent (runs in parallel, N instances):
- WebSearch tool (research)
- Write tool (saves .md files)
- Output: markdown post
Reviewer agent:
- Read tool (reads post)
- Edit tool (applies corrections)
- Output: reviewed post
Blog infrastructure:
- Next.js blog
- _posts/*.md files → /posts/[slug] routes
- Automatic deploy on file change
Connections:
- CLI → Orchestrator (prompt)
- Orchestrator → Writer agent (parallel dispatch via AgentTool)
- Orchestrator → Reviewer agent (sequential, after writer)
- Writer/Reviewer → Blog (_posts/ directory)
O Claude gerou o HTML em menos de 30 segundos. O diagrama mostrou o fluxo completo: entrada pelo CLI, orquestrador no centro, writers em paralelo, revisor em sequência, e o blog Next.js como destino final. A codificação de cores funcionou bem: CLI em âmbar (infraestrutura), agentes em esmeralda (backend), blog em ciano (frontend).
Para iterar, pedi: "separa as tools de cada agente como componentes filhos". O Claude atualizou o diagrama e adicionou WebSearch e Write como nós conectados ao Writer, Read e Edit conectados ao Reviewer.
O segundo diagrama que gerei cobre a arquitetura completa do blog: reading flow e newsletter flow em uma só visão:
Se quiser entender melhor como esse sistema funciona por dentro, tenho um post sobre como o contexto se comporta em sistemas multi-agente e outro sobre o custo real de rodar agentes em produção.
Exportar e compartilhar o diagrama
O output é um arquivo HTML único. Salve assim:
- Na resposta do Claude, copie o bloco de código HTML completo
- Cole em um arquivo
diagrama.htmlno seu editor - Abra no navegador, ou compartilhe o arquivo diretamente
Para versionar junto ao código:
# Cria pasta de documentação no repositório
mkdir -p docs/architecture
# Move o HTML gerado
mv diagrama.html docs/architecture/sistema-conteudo.html
O HTML não tem dependências externas, então funciona offline, em qualquer sistema operacional, sem instalar nada.
Cocoon-AI vs. alternativas: qual ferramenta de diagrama de arquitetura escolher?
Para diagramas pontuais e rápidos, o Cocoon-AI (via Claude skill) é a opção mais ágil: sem sintaxe para aprender, resultado pronto em segundos. Para documentação versionada em repositório, o Mermaid ainda é mais prático. Para modelos C4 de longo prazo com múltiplas visões, use o Structurizr.
| Ferramenta | Melhor para | Limitação | |---|---|---| | Cocoon-AI (Claude skill) | Diagramas visuais rápidos, dark-themed, sem setup | Precisa de Claude pago, não editável vetorialmente | | Mermaid | Diagramas embutidos em Markdown, versionáveis em Git | Sintaxe própria para aprender, sem legendas automáticas | | D2 | Diagramas complexos com layouts automáticos | Menos adoção, ecossistema menor | | draw.io | Diagramas detalhados com controle total de layout | Processo manual, atualização trabalhosa | | Structurizr | Documentação C4 de arquitetura em produção | Curva de aprendizado, modelo mais complexo |
Para equipes que já usam Mermaid no README, pesquisa do GitHub Octoverse registrou crescimento de 47% na adoção de diagram-as-code desde 2021, e times que adotam essa abordagem são 2.4x mais propensos a manter documentação atualizada continuamente.
O Cocoon-AI não substitui Mermaid ou Structurizr para documentação técnica profunda. Ele ocupa um espaço diferente: quando você quer um visual bonito e claro para apresentar para stakeholder, explicar um sistema novo para um colega, ou documentar algo que existe há meses sem diagrama nenhum.
Já vi contexto parecido no post sobre como o Claude Code construiu este blog: às vezes a solução certa é a que remove atrito, não a mais completa.
Quando vale usar e quando não vale
Vale usar quando:
- Você precisa de um diagrama em menos de 10 minutos
- O público é não-técnico (gestores, clientes, investidores)
- O sistema muda frequentemente e você quer regravar rápido
- Quer visual dark-themed sem configurar tema em ferramenta gráfica
Não vale usar quando:
- Precisa de diagramas UML formais (use PlantUML)
- A documentação precisa ficar versionada junto ao código e ser editável como texto (use Mermaid)
- Precisa de múltiplas visões do mesmo sistema em diferentes níveis de abstração (use Structurizr com C4)
- Não tem assinatura paga do Claude
Uma limitação real: o diagrama gerado é HTML estático. Se o sistema mudar, você refaz o processo. Para sistemas que mudam toda semana, Mermaid no repositório faz mais sentido porque você edita o texto diretamente. Para sistemas estáveis ou apresentações pontuais, o Cocoon-AI ganha em velocidade e visual.
Vale a pena adotar no dia a dia?
Vale. A combinação de linguagem natural com output HTML autossuficiente resolve o principal atrito: o diagrama não precisa de software especial para abrir, não fica preso em uma conta de ferramenta e não demora 40 minutos para ficar apresentável.
Não é uma solução para tudo. Para documentação técnica versionada, Mermaid ainda ganha. Para arquitetura C4 de longo prazo, Structurizr é mais adequado. Mas para a maioria dos casos do dia a dia, o Cocoon-AI cobre bem.
Se quiser ir além dos diagramas e entender como construir sistemas de agentes com Claude Code, publico tutoriais sobre isso regularmente. Segue no blog ou nas redes para não perder.
Perguntas Frequentes
O Cocoon-AI Architecture Diagram Generator é gratuito?
A skill é open source e gratuita. O requisito é ter uma assinatura paga do Claude (Pro, Max, Team ou Enterprise). Planos gratuitos do Claude não suportam skills.
Preciso saber programar para usar a skill?
Não. O processo inteiro é em linguagem natural: você descreve sua arquitetura em texto, o Claude gera o HTML. O único passo técnico opcional é usar o CLI do Claude Code, mas o fluxo pelo claude.ai não exige nenhum conhecimento técnico.
Posso editar o diagrama depois de gerado?
O arquivo HTML gerado não é editável vetorialmente como um draw.io ou Figma. Para ajustes, você pede ao Claude no chat. "Adiciona um load balancer antes da API" ou "muda a cor do banco para violeta" funcionam bem. Para mudanças grandes, refaça a descrição.
O diagrama funciona em apresentações do PowerPoint ou Google Slides?
Não diretamente como arquivo HTML. Você pode abrir o HTML no navegador, tirar um screenshot e importar a imagem. Outra opção é hospedar o HTML em qualquer servidor estático e embedar via iframe se a ferramenta suportar.
Qual é a diferença entre usar a skill no Claude.ai e no Claude Code CLI?
No claude.ai, a skill fica disponível em qualquer conversa após o upload. No Claude Code CLI, você extrai o zip em ~/.claude/skills/ e a skill fica disponível nos agentes. A diferença prática é o contexto de uso: claude.ai para geração manual e pontual, Claude Code para automação dentro de sistemas de agentes.