Communitygithub.com

diagrama-de-arquitetura

Diagramas de arquitetura como texto, nas próprias palavras do leitor. Bloços como caixa-preta, a interface em cada costura com suas operações, tipos de dados e um exemplo do que a cruza, um estado ou vários comparados (como-está, um alvo, uma proposta); texto primeiro, depois LikeC4 quando é para outros. Use quando o usuário pedir para desenhar, diagramar ou visualizar como código ou sistemas se encaixam, ou o que uma mudança faz em sua estrutura.

O que é diagrama-de-arquitetura?

Esta habilidade permite que um agente de IA crie diagramas de arquitetura de software como texto estruturado, focando nas palavras e na compreensão do leitor. O objetivo é que o diagrama 'encaixe' no conhecimento existente do leitor, usando seus próprios termos para descrever blocos (caixas-pretas com responsabilidades definidas), suas interfaces (operações, tipos de dados e exemplos concretos do que cruza cada costura) e estados (como está, alvo, proposta) para comparação. A habilidade é útil para esclarecer dúvidas sobre como o código ou os sistemas se encaixam, o impacto de uma mudança, ou para visualizar a estrutura atual e futura. Ela suporta três formas de saída: forma de chat (até 78 colunas com tabelas e blocos de código), forma de tela (página HTML estática com diagramas largos para múltiplos estados) e forma C4 (diagramas LikeC4 interativos para compartilhar com outros). O fluxo de trabalho é guiado por etapas: coletar o vocabulário do leitor, fazer perguntas direcionadoras, catalogar blocos e interfaces em listas, definir o nível de abstração, escolher a forma de saída, desenhar usando scripts auxiliares e verificar a consistência, referências e layout. A habilidade é executada pelo agente de IA (como Claude Code, Cursor, ou Codex) para gerar documentação de arquitetura precisa e centrada no leitor.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NG-Bullseye/architecture-diagram-skill/tree/HEAD/skills/architecture-diagram

Perguntar na sua IA favorita

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

Documentação

Diagrama de Arquitetura

Um diagrama é compreendido quando o que ele mostra se encaixa no que o leitor já sabe. Um desenvolvedor sênior o lê para o fluxo de alto nível e para as costuras. Um bloco é uma caixa-preta: seu padrão de design, pelo que é responsável, quem o possui, e seu interior oculto. O que um bloco oferece a outro através de uma costura é sua interface: operações com tipos de parâmetro e retorno, erros, os tipos de dados que a cruzam com seus campos, e um exemplo do que exatamente cruza e como se parece. O transporte (REST, OPC UA, uma inicialização de processo) é um atributo de uma interface e nunca a substitui.

Leia EXAMPLE.md antes de desenhar: uma mudança, completa, em ambas as formas.

Etapas

1. As palavras do leitor

Um novo termo não se ancora em nada. Antes de qualquer outra coisa, colete as palavras que o leitor já tem: de suas mensagens nesta conversa, dos documentos que escreveu (instruções do projeto, páginas de arquitetura, glossários, tabelas de nomenclatura), e de cada modelo com o qual o diagrama é comparado. Escreva a lista de palavras: a coisa, a palavra do leitor para ela, a palavra de cada outra parte que lerá o diagrama, o nome no código, e a palavra que o diagrama usa.

  • Rotule cada bloco e interface com a palavra do leitor; o nome do código fica ao lado.
  • Onde duas palavras colidirem, ou uma palavra for usada para a coisa errada, escolha uma, diga o porquê na lista de palavras, e nomeie a outra ao lado uma vez.
  • Não cunhe nada. Uma interface sem um nome no código é chamada por suas duas extremidades, Frontend -> Backend.
  • Comece pela imagem que o leitor já tem, seu próprio diagrama com seus níveis e nomes, e coloque o que é novo dentro dele.

Feito quando cada rótulo no diagrama vem da lista de palavras, e cada termo novo para o leitor está no glossário ao lado da palavra conhecida à qual pertence.

2. Perguntas

Escreva as perguntas do leitor, uma linha cada. Eles escolhem as visões.

PerguntaVisão
Quais são as partes, pelo que cada uma é responsável, quem a possui, quem chama quem?visão de blocos de construção
Qual interface une duas partes, e o que exatamente a cruza?a interface, seus tipos de dados e um exemplo em cada costura
O que acontece, em qual ordem, no cenário que importa?visão de tempo de execução: uma sequência
Onde cada parte é executada?host: em cada bloco; uma visão de implantação quando redes ou limites de confiança são a questão
O que uma mudança faz, ou como dois designs diferem?cada estado na mesma forma, depois as diferenças

Feito quando cada visão tem sua pergunta e a pergunta está acima dela como sua legenda.

3. Catálogo

Preencha quatro listas a partir das fontes antes de qualquer desenho.

  • Blocos: a palavra do leitor e o nome no código, estereótipo, uma frase de responsabilidade, proprietário, host.
  • Interfaces, uma por costura: provedor, consumidores, cada operação como uma assinatura nome(parâmetro: Tipo) -> Tipo, erros, transporte.
  • Tipos de dados: cada tipo que uma assinatura nomeia, com seus campos, unidades e padrões.
  • Exemplos, um por interface: uma mensagem como ela cruza, chamada e resposta em seu formato real: uma linha de comando com sua saída, um corpo JSON, uma linha de tabela. Tire-o de uma execução, uma gravação, um fixture ou os dados. Um exemplo montado a partir do código diz isso em sua primeira linha.

Cada entrada carrega sua origem: uma referência de código caminho:linha, ou uma tag (abaixo). Um estado desenhado por outra pessoa, um arquivo de modelo ou um esboço, é reproduzido como está e em suas próprias palavras; o que ele omite é marcado como [indefinido], e o que você adiciona vai para um estado próprio.

Feito quando cada bloco tem sua frase, cada costura uma interface cujas assinaturas são copiadas do código ou marcadas, cada tipo em uma assinatura seus campos, cada interface seu exemplo, e cada entrada uma referência ou uma tag.

4. Nível

Os blocos de um estado são pares: unidades que são implantadas, possuídas ou substituídas por conta própria, de cinco a nove delas. Arquivos, funções e as etapas dentro de um bloco são seu interior. Um zoom é um diagrama adicional um nível abaixo, desenhado para o bloco sobre o qual a pergunta é.

Feito quando nenhum bloco de um estado está dentro de outro, e cada zoom nomeia a pergunta que o justifica.

5. Forma

  • Forma de chat, até 78 colunas: a visão de blocos de construção com o nome da interface e sua assinatura principal em cada aresta, depois o catálogo como tabelas e os exemplos como blocos de código. Para um estado ou uma pequena mudança.
  • Forma de tela, uma página HTML estática de diagramas de texto tão largos quanto necessário: ao lado de cada aresta sua interface completa, o exemplo, e os tipos de dados com seus campos. Para vários estados, ou quando mais de três costuras são mostradas por completo. A página é construída por um script gerador que fica ao lado dela; a resposta do chat nomeia o arquivo, diz em algumas frases o que a comparação mostra e lista as decisões em aberto.
  • Forma C4, o mesmo modelo desenhado com LikeC4 em uma página com uma guia por estado, caixas para clicar e ampliar. Os diagramas de texto são seu protótipo: estabeleça palavras, blocos, interfaces e exemplos lá primeiro, depois renderize. Para um resultado que outras pessoas abrirão. Leia LIKEC4.md.

6. Desenhe

Desenhe com os três arquivos nesta pasta, para que as caixas se alinhem e nenhuma linha seja mais larga que sua tela. O docstring de cada arquivo é seu manual, e executá-lo imprime uma demonstração.

ArquivoFornece
grid.pyGrid (caixas com compartimentos, linhas, setas), sequence (uma visão de tempo de execução), table
canvas.pyglance (cada estado em uma linha), overview (estados lado a lado, uma linha por nível), panel (um estado: blocos, interfaces com exemplos, tipos de dados)
page.pyhtml_page: a página ao redor dos diagramas, com as cores e os links entre ids
likec4/para a forma C4: template.c4, build.sh, a página de guias index.html com tabs.js, e clicktest.py

Uma página vai da imagem de dez segundos ao detalhe: de relance, a lista de palavras, o guia de leitura, a visão geral, um painel por estado, as diferenças por costura como uma tabela, as decisões em aberto, glossário, fontes.

7. Verifique

  • Cada caixa é um bloco do catálogo, cada aresta uma interface, cada caixa de tipo um tipo de dado; uma entrada omitida de um diagrama é omitida de propósito.
  • Cada referência de código se resolve: o arquivo existe e a linha mostra o nome.
  • O mesmo bloco está no mesmo lugar em todos os estados. Um bloco que um estado não tem é uma caixa pontilhada lá.
  • Capturas de tela da página inteira, lidas bloco por bloco: bordas se encontram, nada é cortado, as cores carregam seu significado.
  • As fontes nomeiam o que foi lido, em qual commit, quais exemplos são reais, e o que não foi lido.

Estados

Um estado é o código como ele é, um alvo que alguém desenhou, ou uma proposta. Compare estados por posição: o mesmo bloco na mesma coluna de glance e na mesma linha de overview, para que as lacunas de dois estados mostrem onde eles se complementam.

Uma costura tem um id de uma letra para seu estado e um número, (I4). Uma interface ou tipo de dado definido em uma costura é referenciado por esse id em todos os outros lugares; seus campos são escritos uma vez.

As diferenças são uma tabela com uma linha por costura e uma coluna por estado. As decisões em aberto são uma tabela: a pergunta, as opções, quem decide.

Tags e estereótipos

TagSignificado
[código]existe no código; a referência está ao lado
uma tag de fonte, ex. [c4]declarado por um modelo fonte; nomeie a tag no guia de leitura
[proposto]proposto aqui, não existe em nenhum lugar ainda
[novo] [alterado] [movido]o que uma mudança faz, quando há apenas como-está e para-ser
[indefinido]o estado deixa em aberto
[?1]uma decisão em aberto, listada com seu número

Estereótipos nomeiam o padrão de design que um bloco desempenha: <<ui>>, <<cliente>>, <<gateway>>, <<fachada>>, <<serviço>>, <<porta>>, <<adaptador>>, <<repositório>>, <<externo>>. Use um onde o código desempenha esse papel; um bloco sem estereótipo é melhor do que um com o errado. Uma porta é uma interface que o consumidor possui e o provedor implementa: <<porta>> está na interface, <<adaptador>> no bloco que a implementa. Os tipos próprios de um modelo fonte são citados como ele os escreve.

Dispositivos de explicação

Cada um destes ganha seu lugar ao responder algo que o leitor teria que perguntar de outra forma. Use-os com moderação.

  • Guia de leitura: um pequeno diagrama que mostra como um painel é lido, e as tags.
  • Referências de código: em cada interface e tipo de dado, para que o leitor possa consultá-las.
  • Textos curtos: um parágrafo acima de um estado que diz a única coisa a ver nele; uma nota dentro de uma caixa de interface onde o leitor perguntaria por quê.
  • Glossário: os termos que a lista de palavras não cobre, uma linha cada.
  • Cor: apenas para as tags, os ids, e um ou dois nomes chave que permanecem os mesmos em todos os estados. A cor marca o que os estados compartilham e onde diferem; nada mais é colorido.

O texto em prosa está no idioma da conversa. Nomes do código e de modelos fonte são literais.

Habilidades Relacionadas