Arquiteto Sereia: Habilidade de Diagrama e Documentação

Arquiteto Mermaid - Habilidade Abrangente de Diagramas e Documentação

Versão 2.0 - Arquitetura hierárquica com orquestração inteligente

Uma poderosa habilidade do Claude Code para criar diagramas Mermaid e documentos de design usando carregamento de guias sob demanda, geração de código para diagramas e utilitários Python.

Instalação

Instalação com um clique via Skilz Marketplace

Instale esta habilidade instantaneamente do Skilz Marketplace:

skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid

Instalação Manual

Clone diretamente no diretório de habilidades do Claude Code:

# Navegue até o diretório de habilidades
cd ~/.claude/skills

# Clone o repositório
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git

Verificar Instalação

Após a instalação, verifique se a habilidade está disponível:

# Listar habilidades instaladas
ls ~/.claude/skills/design-doc-mermaid

# Ou pergunte ao Claude Code
# "Listar minhas habilidades instaladas"

O que esta habilidade faz

Geração Inteligente de Diagramas:

• Diagramas de atividades (fluxos de trabalho, processos, lógica de negócios)
• Diagramas de implantação (infraestrutura em nuvem, K8s, serverless)
• Diagramas de arquitetura (componentes de sistema, microsserviços)
• Diagramas de sequência (fluxos de API, interações de serviço)
• Documentos de design completos com diagramas incorporados

Conversão de Código para Diagrama:

• Extrair arquitetura de aplicações Spring Boot
• Gerar diagramas de implantação a partir de arquivos de configuração
• Criar diagramas de sequência a partir de chamadas de método
• Documentar pipelines ETL e fluxos de dados

Gerenciamento de Diagramas:

• Extrair diagramas Mermaid de arquivos Markdown
• Validar sintaxe do diagrama com mermaid-cli
• Converter diagramas para imagens PNG/SVG
• Processar diretórios inteiros em lote

Início Rápido

Criar um Diagrama de Atividades

Usuário: "Criar um diagrama de atividades para registro de usuário com verificação de e-mail"

A habilidade irá:

1. Carregar references/guides/diagrams/activity-diagrams.md
2. Usar o modelo de padrão de registro
3. Adicionar símbolos Unicode (🔐 para segurança, 📧 para e-mail, ✅ para sucesso)
4. Aplicar estilo de alto contraste
5. Gerar diagrama Mermaid completo

Gerar a partir de Código

Usuário: "Aqui está meu application.yml do Spring Boot - gere um diagrama de implantação"

A habilidade irá:

1. Analisar configuração (fonte de dados, cache, segurança)
2. Carregar references/guides/diagrams/deployment-diagrams.md
3. Carregar examples/spring-boot/README.md
4. Mapear configuração para recursos em nuvem
5. Gerar diagrama de implantação com especificações de recursos

Criar Documento de Design

Usuário: "Criar um documento de design de API para a API de contatos"

A habilidade irá:

1. Carregar assets/api-design-template.md
2. Carregar guias de diagrama relevantes (sequência, ER, arquitetura)
3. Gerar documento completo com diagramas incorporados
4. Salvar em docs/design/api-contacts-v1-2025-01-13.md

Estrutura

Organização Hierárquica

mermaid-architect/
├── SKILL.md                          # Orquestrador principal com árvore de decisão
├── README.md                         # Este arquivo
├── CLAUDE.md                         # Instruções do Claude Code
│
├── references/                       # Materiais de referência
│   ├── mermaid-diagram-guide.md     # Guia geral legado
│   └── guides/                       # Guias especializados (carregados sob demanda)
│       ├── diagrams/
│       │   ├── activity-diagrams.md      # ✅ Completo
│       │   ├── deployment-diagrams.md    # ✅ Completo
│       │   ├── architecture-diagrams.md  # ✅ Completo
│       │   └── sequence-diagrams.md      # ✅ Completo
│       ├── code-to-diagram/
│       │   └── README.md                 # ✅ Completo (guia mestre)
│       ├── unicode-symbols/
│       │   └── guide.md                  # ✅ Completo (mais de 100 símbolos)
│       └── troubleshooting.md        # ✅ Completo (28 erros comuns)
│
├── scripts/                          # Utilitários Python
│   ├── extract_mermaid.py           # ✅ Extrair e validar diagramas
│   └── mermaid_to_image.py          # ✅ Converter para PNG/SVG
│
├── examples/                         # Padrões específicos de linguagem
│   ├── spring-boot/                 # ✅ Completo
│   ├── fastapi/                     # ✅ Completo
│   ├── react/                       # ✅ Completo
│   ├── python-etl/                  # ✅ Completo
│   ├── node-webapp/                 # ✅ Completo
│   └── java-webapp/                 # ✅ Completo
│
└── assets/                           # Modelos de documento de design
    ├── architecture-design-template.md
    ├── api-design-template.md
    ├── feature-design-template.md
    ├── database-design-template.md
    └── system-design-template.md

Principais Funcionalidades

1. Símbolos Semânticos Unicode

Cada diagrama usa símbolos Unicode significativos:

graph TB
    User[👤 Cliente] --> Gateway[🌐 Gateway de API]
    Gateway --> Auth[🔐 Serviço de Autenticação]
    Gateway --> API[⚙️ Serviço de API]
    API --> DB[(💾 Banco de Dados)]
    API --> Cache[(⚡ Redis)]
    API --> Queue[📬 Fila de Mensagens]
    Queue --> Worker[⚙️ Trabalhador em Segundo Plano]

Categorias de Símbolos:

• Infraestrutura: ☁️ 🌐 🔌 📡 🗄️
• Computação: ⚙️ ⚡ 🔄 🚀 💨
• Dados: 💾 📦 📊 📈 🗃️
• Mensageria: 📨 📬 📤 📥 🐰
• Segurança: 🔐 🔑 🛡️ 🚪 👤
• Monitoramento: 📝 📊 🚨 ⚠️ ✅ ❌

2. Estilo de Alto Contraste

Todos os diagramas usam cores acessíveis e de alto contraste - veja SKILL.md para detalhes completos.

3. Utilitários Python

Extrair Diagramas

# Listar todos os diagramas em um arquivo
python scripts/extract_mermaid.py document.md --list-only

# Extrair para arquivos .mmd separados
python scripts/extract_mermaid.py document.md --output-dir diagrams/

# Validar todos os diagramas
python scripts/extract_mermaid.py document.md --validate

# Substituir diagramas por referências de imagem (para o Confluence)
python scripts/extract_mermaid.py document.md --replace-with-images \
  --image-format png --output-markdown output.md

Converter para Imagens

# Arquivo único
python scripts/mermaid_to_image.py diagram.mmd output.png

# Tema e tamanho personalizados
python scripts/mermaid_to_image.py diagram.mmd output.svg \
  --theme dark --background white --width 1200

# Converter diretório em lote
python scripts/mermaid_to_image.py diagrams/ output/ \
  --format png --recursive

# Da entrada padrão
echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png

Requisitos

Para Geração de Diagramas

• Sistema de habilidade Claude Code (automático)
• Guias e modelos (incluídos nesta habilidade)

Para Validação e Conversão de Imagens

# Instalar mermaid-cli globalmente
npm install -g @mermaid-js/mermaid-cli

# Verificar instalação
mmdc --version

Para Scripts Python

• Python 3.7+
• Nenhum pacote adicional necessário (usa apenas stdlib)

Trilha de Aprendizado

Novo em Diagramas Mermaid?

1. Comece com Diagramas de Atividades - Leia references/guides/diagrams/activity-diagrams.md
2. Aprenda Símbolos Unicode - Leia references/guides/unicode-symbols/guide.md
3. Experimente um Exemplo - Use padrões de examples/spring-boot/
4. Valide seu Trabalho - Execute python scripts/extract_mermaid.py --validate

Precisa Documentar Código Existente?

1. Identifique o Framework - Spring Boot, FastAPI, React, etc.
2. Carregue o Guia de Exemplo - Leia examples/{your-framework}/README.md
3. Combine Padrões - Encontre padrões de código similares nos exemplos
4. Gere Diagramas - Use modelos dos guias
5. Valide - Use scripts de validação

Criando Documentos de Design?

1. Escolha o Tipo de Modelo - Arquitetura, API, Funcionalidade, Banco de Dados ou Sistema
2. Carregue o Modelo - Leia de assets/{type}-design-template.md
3. Preencha as Seções - Substitua os espaços reservados pelo conteúdo real
4. Adicione Diagramas - Carregue guias de diagrama conforme necessário para cada seção
5. Use Símbolos - Aprimore com símbolos Unicode por todo
6. Salve - Coloque em docs/design/ com carimbo de data/hora

Como o Sistema Hierárquico Funciona

Abordagem Tradicional (Ineficiente)

• Carregar toda a documentação da habilidade (~50KB)
• A IA processa todos os modelos e exemplos
• Alto uso de tokens
• Tempo de resposta lento

Abordagem Hierárquica (Eficiente)

1. Usuário faz requisição → IA analisa a intenção
2. Árvore de decisão é ativada → Determina os guias necessários
3. Carrega apenas o necessário → Lê guia específico (~2-5KB)
4. Gera saída → Usa modelos direcionados
5. Eficiente em tokens → 10x menos contexto necessário

Exemplo de Fluxo

Usuário: "Crie um diagrama de implantação para minha configuração Docker Compose"

Árvore de Decisão:

1. Analisar: "diagrama de implantação" + "Docker Compose"
2. Determinar: deployment-diagrams.md necessário
3. Carregar: references/guides/diagrams/deployment-diagrams.md (2KB)
4. Encontrar padrão: existe modelo Docker Compose
5. Gerar: usando modelo + símbolos Unicode
6. Saída: diagrama completo em <30 segundos

Tokens Usados: ~2.000 (vs ~10.000 com a abordagem tradicional)

Status de Conclusão

✅ Completo:

• Orquestrador de árvore de decisão hierárquica
• Guia de diagrama de atividades com modelos
• Guia de diagrama de implantação (AWS, GCP, K8s, serverless, Docker)
• Guia de símbolos Unicode (mais de 100 símbolos)
• Script de extração Mermaid com validação
• Script de conversão Mermaid para imagem
• Exemplos de código para diagrama Spring Boot
• Modelos de documento de design (5 tipos)
• Sistema de estilo de alto contraste

🚧 Em Progresso:

• Exemplos FastAPI
• Exemplos de arquitetura de componentes React
• Exemplos de pipeline ETL Python

📋 Planejado:

• Guia de diagramas de arquitetura
• Guia de diagramas de sequência
• Guia mestre de código para diagrama
• Exemplos Node.js/Express
• Exemplos de aplicação web Java

Contribuindo

Para adicionar um novo guia de tipo de diagrama:

1. Crie o guia em references/guides/diagrams/{type}-diagrams.md
2. Inclua:
   • Quando usar
   • Sintaxe básica
   • Padrões comuns (3-5 modelos)
   • Exemplos de símbolos Unicode
   • Melhores práticas
3. Atualize a árvore de decisão em SKILL.md
4. Adicione exemplos com mapeamentos de código

Para adicionar um novo exemplo de linguagem:

1. Crie um diretório em examples/{framework}/
2. Adicione README.md com:
   • Visão geral do framework
   • Diagrama de arquitetura a partir da estrutura
   • Diagrama de implantação a partir da configuração
   • Diagrama de sequência a partir do código
   • Diagrama de atividade a partir da lógica
3. Atualize a tabela código-para-diagrama em SKILL.md

Licença

Parte das Habilidades Claude Code - Licença MIT

Habilidades Relacionadas

• confluence - Fazer upload de diagramas para o Confluence
• plantuml - Formato de diagrama alternativo

Links

• GitHub Repository
• Skilz Marketplace Listing
• Mermaid Official Documentation

Versão: 2.0.0 Atualizado: 2025-01-13 Mantido por: SpillwaveSolutions