CommunityImagemgithub.com

diagramas-c4

Acionado ao criar, revisar, atualizar ou explicar diagramas de arquitetura de software usando o modelo C4 (Contexto do Sistema Nível 1, Container Nível 2, Componente Nível 3, Código Nível 4, Paisagem do Sistema, Diagramas Dinâmicos ou de Implantação), especialmente em Markdown/Mermaid.

O que é diagramas-c4?

Esta skill capacita agentes de IA a criar, revisar e explicar diagramas de arquitetura C4 com rigor e consistência. Baseada no modelo C4 de Simon Brown, ela estabelece regras claras para abstrações (Pessoa, Sistema de Software, Container, Componente, Código) e seus respectivos níveis de zoom, evitando as falhas comuns de diagramas ad-hoc como falta de legenda, abstrações misturadas ou setas sem rótulo. A skill fornece templates prontos para Mermaid (flowchart, sequenceDiagram) para os diagramas principais: Contexto do Sistema (L1), Container (L2), Componente (L3), Código (L4), Paisagem do Sistema, Dinâmico e de Implantação. Ela também aborda padrões especiais como filas/tópicos e microsserviços, garantindo que cada relacionamento seja unidirecional e rotulado com ação e protocolo. Compatível com arc42 e UML, a skill enfatiza a pureza de abstração e a inclusão de uma legenda em todos os diagramas. Suporta as principais plataformas de agentes (Claude Code, Cursor, Codex) e ferramentas de edição Markdown, sendo ideal para documentar, revisar e comunicar arquiteturas de software em equipes técnicas e não técnicas.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/fsodano/writing-skills/tree/HEAD/skills/c4-diagrams

Installed? Explore more Imagem skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Diagramas C4

Fonte: o modelo C4 oficial em https://c4model.com/. Aplique estas regras ao desenhar, revisar ou explicar um diagrama C4. Carregue também a skill writing quando a saída incluir prosa (ADRs, docs, descrições de PR).

1. Propósito

C4 é um conjunto de "mapas do seu código" em quatro níveis de zoom: Contexto, Containers, Componentes, Código. Simon Brown o criou, inspirado por UML e pelo modelo de visão 4+1, para substituir diagramas ad-hoc de caixas e linhas. Falhas típicas que ele corrige: sem legenda, abstrações misturadas, setas não rotuladas, falta de tecnologia e rótulos vagos como "lógica de negócio".

C4 é independente de notação e de ferramenta. As abstrações e as regras abaixo importam; as formas não.

2. Abstrações

Hierarquia: Pessoa -> Sistema de Software -> Container -> Componente -> Código. Cada nível amplia um elemento do nível superior.

AbstraçãoDefiniçãoExemplos
PessoaUm usuário humano, ator, papel ou persona do sistemaCliente, Agente de Suporte, Administrador
Sistema de SoftwareNível mais alto de abstração; entrega valor aos usuários. Tipicamente propriedade e construção de uma única equipe. Não é um domínio de produto, contexto delimitado, tribo ou squadPlataforma de Ingressos, Sistema de Pagamentos
ContainerUma aplicação ou armazenamento de dados executável/implantável de forma independente dentro de um sistema de softwareAplicação web no servidor, SPA, aplicação desktop, aplicação mobile, função serverless, aplicação batch/console, API de microsserviço, esquema de banco de dados, bucket S3/blob store, CDN, sistema de arquivos, script de shell
ComponenteUm agrupamento de funcionalidades relacionadas por trás de uma interface bem definida, dentro de um container. Não é implantável separadamente: todos os componentes de um container compartilham um único espaço de processoOrderController, PaymentService, EmailSender
CódigoClasses, interfaces, funções ou tabelas de BD dentro de um componenteclass OrderValidator, tabela pedidos

Regras de Container (FAQ C4)

  • Um container C4 não é Docker. É uma aplicação ou armazenamento de dados executável/implantável, independentemente do empacotamento.
  • Uma aplicação HTML renderizada no servidor é 1 container. Um servidor mais um SPA ou cliente mobile são 2 containers se comunicando por uma API remota.
  • JARs, DLLs, assemblies e módulos não são containers. Eles organizam o código dentro de um container.
  • Serviços de dados gerenciados (S3, RDS, CDN) são containers dentro do limite do seu sistema quando você possui ou controla os buckets ou esquemas. Eles não são sistemas externos.

Regras de Componente

  • Um componente não é uma pasta, pacote ou JAR. É um agrupamento funcional com uma interface.
  • Componentes não são implantáveis independentemente. Se implanta separadamente, é um container.

Adaptando a terminologia

As equipes podem substituir nomes idiomáticos da linguagem (por exemplo, Módulo ou Função em código funcional) quando definirem o termo explicitamente no diagrama ou em sua documentação. Não invente níveis de abstração extras a menos que cada um seja estritamente definido.

3. Padrões especiais de modelagem

Filas e tópicos

  • Errado: um único "Barramento de Mensagens" gigante no meio com todos os serviços conectados (hub-and-spoke). Isso esconde quem produz e quem consome o quê.
  • Opção 1 (preferida): modele cada fila ou tópico como seu próprio container (um armazenamento de dados de mensagens). Produtores escrevem nele, consumidores leem ou assinam dele.
  • Opção 2: para acoplamento ponto-a-ponto direto, omita a caixa de fila e rotule o relacionamento como "Publica eventos de pedido via Fila pedidos [AMQP]". Opcionalmente, estilize essas linhas de forma diferente de chamadas HTTP (explique na legenda).

Por exemplo: Order API --"Publica OrderPlaced em [Kafka]"--> [(tópico pedidos)] --"Lê OrderPlaced de [Kafka]"--> Fulfilment Worker.

Microsserviços (Regra da Lei de Conway)

  • Uma equipe é dona de todo o sistema de software: modele cada microsserviço como um grupo de containers dentro do limite desse sistema (container de API mais seu próprio container de esquema de banco de dados, ou um único container Lambda sem estado).
  • Equipes separadas são donas de cada serviço: promova cada serviço com propriedade independente para seu próprio Sistema de Software, cada um com seus próprios diagramas de Contexto do Sistema e Container. Declare a propriedade de filas/tópicos explicitamente entre os limites do sistema.

4. Catálogo de diagramas

Níveis estáticos principais

NívelDiagramaRecomendadoEscopoPúblicoMostrar / omitir
1Contexto do SistemaSim1 sistema de softwareTécnico e não técnicoPessoas e sistemas externos ao redor do sistema. Omita tecnologia e protocolos de baixo nível
2ContainerSim1 sistema de softwareTécnico, operaçõesPrincipais escolhas tecnológicas e protocolos entre processos. Omita clustering, balanceadores de carga, failover
3ComponenteNão: apenas quando agregar valor claro, idealmente automatizado1 containerArquitetos, desenvolvedoresComponentes dentro de um container e suas interações
4CódigoNão: gere sob demanda na IDE1 componenteDesenvolvedoresDiagrama de classes UML ou ERD

Diagramas de suporte

DiagramaRecomendadoUso
Paisagem do SistemaSim, para organizações e portfóliosMapa empresarial ou departamental de todos os sistemas e pessoas. Um diagrama de Contexto sem um único sistema focal
DinâmicoNão: use com moderaçãoColaborações complexas em tempo de execução. Estilo de colaboração numerada ou estilo de sequência UML
ImplantaçãoSim1 ambiente (prod, staging, dev). Nós de implantação aninhados (físico, VM, Docker, Kubernetes, runtime) contendo instâncias de sistema/container, mais nós de infraestrutura (DNS, balanceadores de carga, firewalls)

Compatibilidade

  • arc42: Contexto e Escopo -> L1; Nível de Bloco de Construção 1 -> L2; Nível de Bloco de Construção 2 -> L3; Nível de Bloco de Construção 3 -> L4.
  • UML: complemente C4 com diagramas UML de estado, sequência e ERD para fluxos de trabalho, máquinas de estado e modelos de dados.

Regra de escala

Quando um diagrama ficar poluído, não amontoe dezenas de caixas em uma única tela. Divida no mesmo nível de abstração por área de negócio, contexto delimitado, funcionalidade ou foco em um único serviço (o serviço focal mais seus vizinhos de entrada e saída).

5. Regras de notação

Diagrama

  • O título declara o tipo de diagrama e o escopo: Diagrama de Container para Sistema de Checkout.
  • Sempre inclua uma chave/legenda explicando formas, cores, bordas, tipos de linha, pontas de seta e siglas.
  • Mantenha pureza estrita de abstração: nunca misture níveis de abstração (por exemplo, nenhuma caixa Componente dentro de um diagrama L2 de Container), e nunca coloque protocolos ou etapas de implementação interna ([HTTPS], pacote mascarado, tool_runner) dentro de um diagrama L1 de Contexto do Sistema.
  • Ao comparar arquiteturas concorrentes ou históricas, rotule os títulos dos limites explicitamente (Opção A (Substituída) vs. Opção B (Atual)) e atualize todos os diagramas no documento sempre que requisitos ou suposições mudarem.

Elemento

  • Nome, tipo de elemento explícito (Pessoa, Sistema de Software, Container, Componente, Banco de Dados, Nó de Implantação) e uma descrição concisa de responsabilidade.
  • Tecnologia explícita em cada container, componente e nó de implantação.

Relacionamento

  • Apenas setas unidirecionais. Nunca <-->. Se os dados fluírem em ambos os sentidos, mostre a direção do iniciador e descreva a resposta no rótulo.
  • Rótulos com verbos de ação específicos. Nunca um "Usa" genérico. Escreva Submete pedidos para, Lê mapa de assentos de.
  • Protocolo/tecnologia em relacionamentos entre containers: [JSON/HTTPS], [SQL], [gRPC], [AMQP].

6. Mermaid em Markdown

Prefira flowchart (flowchart TB ou LR), não o C4Context/C4Container nativo do Mermaid. A sintaxe C4 nativa é experimental e frequentemente falha ao renderizar em visualizadores Markdown. Emita-a apenas se o usuário pedir explicitamente e confirmar suporte do renderizador.

Convenções de flowchart:

  • subgraph para o limite do sistema (Containers/Componentes) ou nós de implantação.
  • [(...)] para bancos de dados, armazenamentos de dados, filas e tópicos.
  • Rótulos HTML entre aspas: "<b>Nome</b><br/>«Container: Tech»<br/>Responsabilidade curta".
  • Setas com rótulos entre aspas: A -->|"Ação [Protocolo]"| B.
  • Um classDef por tipo de elemento, aplicado consistentemente.
  • Um subgraph Legenda compacto (nós não conectados, ancorado na parte inferior com um link invisível bottomNode ~~~ Legenda quando Dagre o coloca no topo) é necessário sempre que cores, formas de cilindro ou múltiplos estilos de linha forem usados; coloque um título como cabeçalho ou linha Título: ... diretamente acima do bloco de código.
  • Diagramas dinâmicos: sequenceDiagram, ou um flowchart com rótulos de seta numerados (1. Submete pedido [JSON/HTTPS]).
  • Diagramas de implantação: subgraphs aninhados em um flowchart.
  • Sempre coloque entre aspas rótulos que contenham parênteses, colchetes ou dois-pontos.
  • Nunca coloque ponto e vírgula (;) sem escape dentro de rótulos de sequenceDiagram ou stateDiagram-v2 (o Mermaid trata ; como terminador de instrução e divide o texto restante em estados ou erros de análise); envolva blocos Note longos em sequenceDiagram com <br/> para que o texto nunca seja cortado na borda do viewport.

Template: L1 Contexto do Sistema

Título: Diagrama de Contexto do Sistema para Plataforma de Ingressos

flowchart TB
    cliente["<b>Cliente</b><br/>«Pessoa»<br/>Compra ingressos para eventos"]
    plataforma["<b>Plataforma de Ingressos</b><br/>«Sistema de Software»<br/>Permite que clientes naveguem por eventos e comprem ingressos"]
    pagamentos["<b>Provedor de Pagamento</b><br/>«Sistema de Software, externo»<br/>Cobra cartões"]
    email["<b>Serviço de Email</b><br/>«Sistema de Software, externo»<br/>Entrega emails de confirmação"]

    cliente -->|"Navega por eventos e compra ingressos usando"| plataforma
    plataforma -->|"Solicita cobranças de cartão de"| pagamentos
    plataforma -->|"Envia emails de confirmação usando"| email
    email -->|"Entrega emails de confirmação para"| cliente

    classDef person fill:#08427b,stroke:#052e56,color:#fff
    classDef system fill:#1168bd,stroke:#0b4884,color:#fff
    classDef external fill:#999,stroke:#6b6b6b,color:#fff
    class cliente person
    class plataforma system
    class pagamentos,email external

    subgraph Legenda
        direction LR
        l1["Pessoa"]:::person
        l2["Sistema de Software (no escopo)"]:::system
        l3["Sistema de Software (externo)"]:::external
    end

Template: L2 Container (com container de fila)

Título: Diagrama de Container para Plataforma de Ingressos

flowchart TB
    cliente["<b>Cliente</b><br/>«Pessoa»<br/>Compra ingressos para eventos"]
    pagamentos["<b>Provedor de Pagamento</b><br/>«Sistema de Software, externo»<br/>Cobra cartões"]

    subgraph limite["Plataforma de Ingressos [Sistema de Software]"]
        spa["<b>App Web</b><br/>«Container: React SPA»<br/>UI de navegação e checkout"]
        api["<b>API de Pedidos</b><br/>«Container: Java, Spring Boot»<br/>Valida e coloca pedidos"]
        db[("<b>BD de Pedidos</b><br/>«Container: PostgreSQL»<br/>Armazena pedidos e ingressos")]
        topico[("<b>tópico pedidos</b><br/>«Container: Tópico Kafka»<br/>Eventos OrderPlaced")]
        worker["<b>Worker de Fulfillment</b><br/>«Container: Python»<br/>Emite ingressos e envia emails"]
    end

    cliente -->|"Navega e compra usando [HTTPS]"| spa
    spa -->|"Submete pedidos para [JSON/HTTPS]"| api
    api -->|"Escreve pedidos em [SQL/TCP]"| db
    api -->|"Publica OrderPlaced em [Kafka]"| topico
    worker -->|"Lê OrderPlaced de [Kafka]"| topico
    worker -->|"Atualiza status do ingresso em [SQL/TCP]"| db
    api -->|"Solicita cobranças de cartão de [JSON/HTTPS]"| pagamentos

    classDef person fill:#08427b,stroke:#052e56,color:#fff
    classDef container fill:#438dd5,stroke:#2e6295,color:#fff
    classDef store fill:#2e6da4,stroke:#1b4f72,color:#fff
    classDef external fill:#999,stroke:#6b6b6b,color:#fff
    class cliente person
    class spa,api,worker container
    class db,topico store
    class pagamentos external

    subgraph Legenda
        direction LR
        l1["Pessoa"]:::person
        l2["Container"]:::container
        l3[("Armazenamento de dados / fila / tópico")]:::store
        l4["Sistema externo"]:::external
    end

Nota da legenda: setas apontam do iniciador para o destino. O rótulo indica a ação e [protocolo].

Template: Implantação

Título: Diagrama de Implantação para Plataforma de Ingressos (Produção)

flowchart TB
    usuarios["<b>Navegador do Cliente</b><br/>«Nó de Implantação: Chrome»"]

    subgraph aws["AWS «Nó de Implantação: Cloud, us-east-1»"]
        dns["<b>Route 53</b><br/>«Nó de Infraestrutura: DNS»"]
        lb["<b>Balanceador de Carga</b><br/>«Nó de Infraestrutura: ALB»"]
        subgraph eks["EKS «Nó de Implantação: Cluster Kubernetes»"]
            subgraph pod["pod order-api «Nó de Implantação: Docker, x3»"]
                api["<b>API de Pedidos</b><br/>«Instância de Container: Java, Spring Boot»"]
            end
        end
        subgraph rds["RDS «Nó de Implantação: PostgreSQL 16»"]
            db[("<b>BD de Pedidos</b><br/>«Instância de Container: Esquema PostgreSQL»")]
        end
    end

    usuarios -->|"Resolve nome de host usando [DNS]"| dns
    usuarios -->|"Envia requisições para [HTTPS]"| lb
    lb -->|"Encaminha requisições para [HTTP]"| api
    api -->|"Lê e escreve pedidos em [SQL/TCP]"| db

Adicione um subgraph Legenda se usar cores ou estilos além dos padrão.

Template: Dinâmico (Sequência)

Título: Diagrama Dinâmico (estilo sequência) para Checkout de Pedido na Plataforma de Ingressos

sequenceDiagram
    autonumber
    actor cliente as Cliente
    participant spa as App Web (React SPA)
    participant api as API de Pedidos (Spring Boot)
    participant pagamentos as Provedor de Pagamento
    participant db as BD de Pedidos (PostgreSQL)
    participant topico as tópico pedidos (Kafka)

    cliente->>spa: Clica "Finalizar Pedido"
    spa->>api: POST /orders [JSON/HTTPS]
    api->>pagamentos: Cobra cartão [JSON/HTTPS]
    pagamentos-->>api: Pagamento autorizado
    api->>db: Insere linha de pedido [SQL/TCP]
    api->>topico: Publica OrderPlaced [Kafka]
    api-->>spa: 201 Criado (confirmação do pedido)
    spa-->>cliente: Mostra recibo do pedido

Mantenha os rótulos de participantes e mensagens de sequenceDiagram livres de barras não entre aspas, ponto e vírgula (;, que o Mermaid analisa como terminadores de instrução) ou novas linhas brutas para máxima compatibilidade com visualizadores Markdown.

7. Dicas de estilo Mermaid

  • Cores: use cores acessíveis (contraste suficiente, sem vermelho e verde exclusivos para daltônicos). Cores sugeridas: Pessoas azul escuro (#08427b), Containers azul médio (#438dd5), Sistemas azul mais claro (#1168bd), Armazenamentos azul marinho (#2e6da4), Externos cinza (#999).
  • Bordas: mantenha bordas sólidas de tom mais escuro.
  • Formas: pessoas são retângulos com cantos arredondados, containers são retângulos retos, armazenamentos de dados são cilindros ([( )]).
  • Tamanho da fonte: mantenha o tamanho padrão do Mermaid ou defina fontSize: 14 no classDef.
  • Legenda: sempre inclua se forem usadas cores ou formas não padrão. Use um subgraph separado.

8. Revisão e garantia de qualidade

Ao revisar um diagrama C4, verifique:

  • O título corresponde ao tipo e escopo do diagrama.
  • Legenda presente, atualizada e cobrindo todas as formas, cores e tipos de linha.
  • Sem abstrações misturadas (por exemplo, sem Componente dentro de L2).
  • Cada elemento tem tipo e tecnologia/descrição.
  • Setas são unidirecionais com rótulos de ação e protocolo quando aplicável.
  • Nomes de elementos consistentes entre diagramas (mesmo nome = mesmo elemento).
  • Nenhuma abreviação ou sigla não explicada.
  • Diagramas ficam legíveis sem zoom extremo (divida se mais de ~15 caixas).
  • flowchart é preferido em vez de C4Context/C4Container do Mermaid.
  • A legenda está ancorada na parte inferior quando necessário.
  • Rótulos com caracteres especiais estão entre aspas.

9. Exemplos de prompts

  • "Desenhe um diagrama de Contexto do Sistema L1 para um sistema de processamento de pedidos."
  • "Converta esta descrição de arquitetura em um diagrama de Container L2 usando Mermaid."
  • "Adicione um diagrama de Implantação mostrando serviços implantados no EKS com bancos de dados RDS."
  • "Revise este diagrama C4 em busca de violações de pureza de abstração."
  • "Atualize o diagrama de Container para refletir a adição de uma fila de mensagens."

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Habilidades Relacionadas