clanker25/diagrama

Diagramas têm função estrutural, não são decoração. Recorra a um apenas quando a prosa força o leitor a manter uma forma inteira na cabeça de uma só vez — então escolha a menor vista que permita enxergar a forma em vez de reconstruí-la a partir de frases. Tudo aqui é renderizado na conversa como blocos de texto ou Mermaid; no máximo um único arquivo de artefato é escrito.

O vocabulário

Escolha uma vista; no máximo duas. Mais que isso é ruído.

Pseudocódigo — lógica sem o ruído da linguagem. Reduz uma decisão à sua forma de ramificação:

on(request)
  if state file locked by another writer
    queue and return pending
  acquire lock
  write
  release

Árvore de chamadas — fluxo de controle em tempo de execução. A profundidade mostra quem detém o fluxo; anote onde está a aresta interessante:

acquireStateFileLockSync()
  resolveLockPath()
  openExclusive()
  writePid()

Árvore de componentes — estrutura de UI ou módulos, com os limites relevantes anotados inline:

<SettingsPage> (src/routes/settings)
  <SessionList> (faz seus próprios fetches)
  <DangerZone>
    <ConfirmButton> (desabilitado até confirmação digitada)

Árvore de arquivos — onde vive a responsabilidade; mantenha rasa, uma anotação por diretório:

src/
├── hooks/        # registro de hooks + tipos
├── tools/        # manipuladores de ferramentas MCP
└── workflow/     # registro + projeções

Mermaid — interação entre partes, fluxo de dados ou transições de estado:

sequenceDiagram
    participant CLI
    participant Hook
    participant State
    CLI->>Hook: PreToolUse
    Hook->>State: read mode
    Hook-->>CLI: allow / deny + facts

Diff — a forma de uma mudança quando a estrutura circundante já existe. Combine o diff com o tópico:

uma mudança em componente:

 <SettingsPage>
   <SessionList />
   <DangerZone>
+    <ConfirmButton />
   </DangerZone>

uma mudança na estrutura de arquivos:

 src/tools/
-└── state-tools.ts
+└── state-tools/
+   ├── handlers.ts
+   └── schema.ts

uma mudança no fluxo de controle:

 commit()
   stage()
     hashBlobs()
+  writeObject()
   updateRef()
+    acquireStateFileLock()

uma mudança em máquina de estados:

 on(request)
-  write immediately
+  if locked
+    queue and return pending
+  acquire lock
+  write
+  release

O bloco completo — quando a omissão esconderia quem é dono do quê ou a ordem de execução, mostre a unidade completa uma vez, copiável:

export function isRegistryEnabled(): boolean {
  const flag = process.env.OMC_WORKFLOW_REGISTRY;
  return flag !== '0' && flag !== 'false';
}

Quando o texto não basta

Um layout de UI, uma comparação antes/depois ou um conceito denso demais para Mermaid: escreva um único arquivo HTML focado — um diagrama, um infográfico ou alguns slides — estilizado com as cores, tipo e componentes do próprio produto, preenchido com rótulos e dados reais, funcionando em desktop e mobile. Abra-o com o abridor da plataforma (start no Windows, open no macOS, xdg-open no Linux) e pare por aí: um artefato, não uma galeria.

Disciplina

• Coloque cada visual diretamente ao lado das duas ou três frases que ele suporta.
• Carregue apenas as chamadas, arquivos, props, estados e limites que respondem à pergunta atual — cada nó extra é um imposto de decodificação para o leitor.
• Se a resposta honesta couber em uma frase, escreva a frase.