Incorpore um diagrama UML correto em seus documentos
Os agentes são constantemente solicitados a "adicionar um diagrama" à documentação — e rotineiramente erram na modelagem sutilmente (multiplicidades inválidas, setas invertidas, herança ao contrário) ou entregam um bloco de código que nunca vira uma imagem. Esta skill produz um diagrama de classes correto e uma imagem real incorporável.
Escopo
- Apenas diagramas de classes, por enquanto — classes, atributos, associações, multiplicidades, herança. Outros tipos de diagramas UML (máquinas de estado, objetos, sequência, atividades, …) estão fora do escopo desta skill.
- Sempre através do BESSER B-UML. Cada diagrama é construído primeiro como um
DomainModeldo B-UML e depois entregue. Passar pelo modelo é o que torna o diagrama correto e reutilizável como código.
Onde pode começar
- Uma descrição — o usuário explica o domínio; o agente escreve o modelo.
- Código existente — o agente lê o código-fonte e constrói o modelo B-UML a partir de sua estrutura. (Não há varredura automática de código; o agente faz a modelagem a partir do que lê — não é um importador com um clique.)
- Um caminho suportado para dentro do B-UML — PlantUML, Draw.io ou um mockup de interface.
Duas formas de entregar
Modele uma vez, depois entregue como código B-UML incorporado (Entrega A) ou uma imagem renderizada (Entrega B) — ambos a partir do mesmo modelo, então nunca discordam. Escolha pelo contexto (um documento de design que deve permanecer executável → código; um README que deve mostrar uma imagem → imagem), ou forneça ambos. Detalhes nas seções de Entrega abaixo.
Onde chega. Se o usuário nomear um documento alvo (um README, um documento
de design), incorpore nesse arquivo. Se não nomear nenhum — ou pedir um diagrama
independente de um repositório/sistema — o padrão é entregar um novo .md autocontido
(ex. docs/<modelo>.md): a imagem renderizada (Entrega B) e/ou o código B-UML
(Entrega A), além de uma ou duas linhas explicando o que o diagrama mostra. Isso transforma um simples
"diagrame meu repositório" em um documento passível de commit, em vez de um SVG solto.
Ao criar um novo arquivo, diga onde o colocou (e ofereça a alternativa —
incorporar em um documento existente — se isso for o que o usuário pode ter desejado).
Fluxo de trabalho
1. Construa o modelo B-UML — a partir de uma descrição, de código existente lido
pelo agente, ou através de um caminho suportado para dentro do B-UML (PlantUML / Draw.io / mockup)
2. model.validate() → confirme que está estruturalmente correto
Depois entregue um (ou ambos):
A) Incorporar o código: Coloque o Python do DomainModel dentro de um bloco
cercado por ``` no .md
B) Incorporar uma imagem: Faça POST do modelo para o endpoint SVG headless
do BESSER (uma chamada HTTP — sem navegador), salve o SVG retornado
(ex. docs/img/data-model.svg), incorpore com

3. Quando o modelo mudar, atualize o modelo e re-entregue — uma única fonte de verdade
1. Construa o modelo
Um diagrama correto começa de um modelo correto. A forma mínima:
from besser.BUML.metamodel.structural import (
DomainModel, Class, Property, Multiplicity,
BinaryAssociation, Generalization, StringType, IntegerType,
)
publication = Class(name="Publication", attributes={Property(name="title", type=StringType)})
book = Class(name="Book", attributes={Property(name="pages", type=IntegerType)})
author = Class(name="Author", attributes={Property(name="name", type=StringType)})
book_is_a = Generalization(general=publication, specific=book) # Book é uma Publication
# Um Book é escrito por 1..* Authors; um Author escreve 0..* Books
written_by = Property(name="writtenBy", type=author, multiplicity=Multiplicity(1, "*"))
writes = Property(name="writes", type=book, multiplicity=Multiplicity(0, "*"))
book_author = BinaryAssociation(name="book_author", ends={written_by, writes})
model = DomainModel(
name="Library",
types={publication, book, author},
associations={book_author},
generalizations={book_is_a},
)
assert model.validate()["success"]
Nomes: sem espaços, sem hífens. Para tudo além desta forma mínima —
enumeradores, todos os padrões de multiplicidade/composição,
classes de associação, conjuntos de generalização, métodos, detalhes de validação — leia
references/class-diagram.md (incluído com esta skill). Para tipos de modelo
que não sejam de classes (objeto, feature, implantação, OCL, …), veja a skill
besser-user da plataforma BESSER.
Forma importável — necessária para ambos os caminhos de entrega. Escreva cada
Class(...),BinaryAssociation(...), eGeneralization(...)como uma atribuição explícita no nível superior, exatamente como mostrado acima. O importador do BESSER (usado pelo endpoint SVG e pelo Import do editor) lê a estrutura do arquivo — ele não o executa — então relacionamentos construídos dentro de uma função auxiliar ou de um loop são invisíveis: as classes importam, mas as associações silenciosamente desaparecem. Uma declaração literal por relacionamento.Como o importador nunca executa o arquivo,
model.validate()não é executado no caminho de renderização — você não precisa do BESSER instalado para renderizar via o endpoint. Mantenha a chamadavalidate()para quando você tiver o BESSER localmente (e antes de gerar código); ela é um no-op para o endpoint, não um requisito.
De onde o modelo vem:
- De uma descrição — escreva como acima.
- De código existente — leia o código-fonte e traduza sua estrutura (classes, campos, relacionamentos, herança) para o modelo B-UML. O agente faz a modelagem; não há varredura automática de código.
- De PlantUML / Draw.io / um mockup de interface — use a conversão correspondente para dentro do B-UML (disponível via a plataforma BESSER) e continue.
Agora entregue de uma das duas maneiras.
Entrega A — incorpore o código B-UML no documento
Coloque o modelo diretamente em um bloco cercado por ```python no .md. Ele é
correto, verificado com validate(), reexecutável e importável no editor.
Melhor quando o documento deve carregar o modelo em si (um documento de design, uma especificação):
## Modelo de dados
```python
# (o DomainModel de cima)
```
Este modelo B-UML é a fonte de verdade para o domínio — verificado com `validate()`,
e a entrada para qualquer gerador do BESSER.
Entrega B — incorpore uma imagem renderizada
O modelo se torna uma imagem real através do renderizador do BESSER, então a imagem sempre corresponde ao modelo. Duas maneiras — escolha se você prefere sem intervenção ou ajustada manualmente.
B1. Renderize automaticamente (padrão) — uma chamada HTTP, sem navegador
O BESSER expõe um endpoint headless B-UML → SVG. O agente faz POST do arquivo
.py do modelo e recebe um SVG de volta — sem editor, sem etapas manuais, nada para o
usuário clicar:
curl -X POST https://editor.besser-pearl.org/besser_api/get-svg \
-F "[email protected];type=text/x-python" \
-o docs/img/data-model.svg
O endpoint analisa o B-UML, organiza a diagramação automaticamente e retorna image/svg+xml.
Salve no repositório e incorpore:

- O arquivo de modelo deve estar em forma importável (veja o destaque na §1) — a mesma forma que o editor importa. Apenas diagramas de classes.
- A diagramação é automática. Quando o posicionamento importa, ajuste manualmente com B2.
- Salve o
.pycomo UTF-8 sem BOM — uma marca de ordem de byte no início faz o endpoint rejeitar o arquivo (HTTP 400). - Omita
default_value=...de literais de enum em um modelo que você renderiza aqui — o endpoint atualmente falha nisso (HTTP 500). Está ok para geração de código; um enum simples usado como tipo de atributo renderiza bem. - Uma resposta não-200 é um pequeno JSON de erro, não um SVG (
{ "detail": ... }) — verifique o status antes de salvar.
B2. Exportação ajustada manualmente do editor (quando a diagramação importa)
Abra https://editor.besser-pearl.org, Importe o .py (escolha o
formato B-UML), arraste caixas e rotas de linhas a gosto, depois Exporte e
escolha um formato:
- SVG — nítido em qualquer tamanho; melhor para documentos e a web.
- PNG — fundo transparente.
- PNG (fundo branco) — para superfícies que precisam de uma imagem opaca.
Salve no repositório e incorpore da mesma forma. (O editor também pode exportar o modelo como B-UML ou JSON — esses são o modelo, não uma imagem.)
De qualquer forma, SVG e PNG renderizam em todos os lugares onde imagens Markdown existem — GitHub, GitLab, sites de documentação, wikis, slides — sem plugin.
Evite que ele se desatualize
Qualquer que seja o modo escolhido, o modelo é a fonte de verdade. Quando os requisitos mudarem, atualize o modelo e re-entregue (recole o código, ou reexporte a imagem) — nunca edite manualmente um SVG/PNG exportado, ele é gerado.
O benefício além de uma imagem
Como o diagrama é um modelo B-UML real, o mesmo artefato pode gerar código funcional — classes Python, SQL, um backend FastAPI, Django, React e mais. Um diagrama que você desenhou para explicar o sistema pode se tornar o sistema. Para gerar código a partir dele, consulte a skill besser-generators.
Quando usar skills relacionadas
- Construindo modelos em profundidade (enums, herança, métodos, OCL, modelos objeto / feature / implantação / NN / quânticos) → a skill besser-user.
- Gerando código a partir do modelo → a skill besser-generators.
- Erros (problemas de importação/validação/editor) → a skill besser-troubleshooting.