Notas

Uma nota é um recado preso a uma caixa, ou solto num diagrama. É onde vivem o risco conhecido, a decisão tomada, a dúvida em aberto e o aviso de operação.

Não existe entidade “risco” nem entidade “decisão” no formato. Um risco é uma nota com kind: risk, e o vocabulário de tipos é aberto — quem modela declara os que fizerem sentido.

Escrever uma nota

model/reservas/notas.yaml

notes:
  - target: api
    kind: risk
    text: Ponto unico de falha para confirmar uma reserva.
    meta:
      levantadoPor: arquitetura

  - target: sincronizador
    kind: decisao
    text: A sincronizacao e assincrona de proposito — a reserva vale mesmo se a agenda estiver fora do ar.

  # Sem `target`: um adesivo solto, so no diagrama de containers.
  - scope: containers
    kind: info
    text: Desenho congelado para a revisao de arquitetura de 2026-Q1.

Os campos

Campo	Obrigatório	O que faz
text	sim	o texto da nota
target	não	a caixa a que ela se prende
scope	não	o diagrama a que ela se restringe
kind	não	o tipo. Padrão: info
meta	não	pares chave/valor livres

target e scope decidem onde a nota aparece:

target	scope	Onde aparece
uma caixa	ausente	naquela caixa, em todo diagrama que a mostra
uma caixa	um diagrama	naquela caixa, só naquele diagrama
ausente	um diagrama	como um adesivo solto naquele diagrama
ausente	ausente	em lugar nenhum — o cfour check avisa e a nota é descartada

Os tipos que vêm de fábrica

kind	Rótulo	Marca
risk	Risco	R, vermelho
blocker	Bloqueio	!, vermelho forte
warning	Atenção	!, laranja
question	Dúvida	?, roxo
info	Informação	i, azul
tip	Nota	estrela, verde

Um tipo desconhecido não some: ele vira um distintivo neutro carregando a chave crua, e o cfour check avisa. Criar um tipo novo é uma entrada em workspace.yaml — veja Aparência da modelagem.

Onde escrever

Num arquivo só de notas, como no exemplo acima. É a forma mais legível quando as notas são revisadas juntas.

Dentro do documento do elemento. Num documento singular (kind: element), uma lista notes: aninhada tem o target implícito:

model/reservas/api.yaml

kind: element
id: api
name: API de Reservas
parent: reservas

notes:
  - kind: risk
    text: Ponto unico de falha para confirmar uma reserva.

Dentro do documento do diagrama. Ali o scope é implícito — a nota fica confinada àquele desenho:

model/reservas/containers-diagrama.yaml

kind: diagram
id: containers
scope: reservas

notes:
  - kind: info
    text: Desenho congelado para a revisao de arquitetura de 2026-Q1.

Por que a nota se prende ao elemento, e não ao desenho

Uma nota presa a uma caixa acompanha aquela caixa em todo diagrama onde ela apareça. Isso é o oposto de escrever um comentário num desenho: o risco da API é do sistema, e não da folha de papel em que alguém o anotou primeiro.

Use scope quando o recado é mesmo sobre aquele desenho — “aqui omitimos o legado de propósito” — e não sobre a caixa.

Encontrar as notas depois

cfour note list
cfour note list --target api
cfour find "ponto unico"

Um agente conectado ao servidor MCP faz a mesma pergunta com a ferramenta cfour_notes, filtrando por tipo.

Próximo passo

Fluxos — contar o que acontece, e em que ordem.