escrita-markdown-mermaid

Escrita em Markdown e Mermaid

Visão Geral

Esta habilidade ensina — e impõe um padrão para — a criação de documentação científica usando markdown com diagramas Mermaid incorporados como formato canônico padrão.

A aposta central: uma relação expressa como diagrama Mermaid dentro de um arquivo .md é mais valiosa do que qualquer imagem. É texto, então diffs de forma limpa no git. Não requer etapa de build. Renderiza nativamente no GitHub, GitLab, Notion, VS Code e em qualquer visualizador de markdown. Usa menos tokens do que uma descrição em prosa da mesma relação. E sempre pode ser convertido para uma imagem polida depois — mas a versão em texto permanece a fonte da verdade.

"Quanto mais você colocar seus relatórios e arquivos em .md em texto simples regular, o que mermaid também é como uma 'linguagem de script' simples. Isso ajuda em qualquer renderização downstream e especialmente imagens geradas por IA (usando mermaid em vez de apenas texto longo para descrever relações < tokens). Além disso, mermaid pode renderizar junto com markdown para uso fácil em quase qualquer lugar por humanos ou IA."

— Clayton Young (@borealBytes), K-Dense Discord, 2026-02-19

Quando Usar Esta Habilidade

Use esta habilidade quando:

• Criar qualquer documento científico — relatórios, análises, manuscritos, seções de métodos
• Escrever qualquer documentação — READMEs, tutoriais, registros de decisão, documentação de projeto
• Produzir qualquer diagrama — fluxos de trabalho, pipelines de dados, arquiteturas, linhas do tempo, relacionamentos
• Gerar qualquer saída que será versionada — se vai para o git, deve ser markdown
• Trabalhar com qualquer outra habilidade — esta habilidade define a camada de documentação que envolve todas as outras saídas
• Alguém pedir para "adicionar um diagrama" ou "visualizar a relação" — Mermaid primeiro, sempre

NÃO comece com Python matplotlib, seaborn ou geração de imagem por IA para diagramas estruturais ou relacionais. Essas são Fase 2 e Fase 3 — usadas apenas quando Mermaid não consegue expressar o necessário (por exemplo, gráficos de dispersão com dados reais, imagens fotorrealistas).

🎨 A Filosofia do Formato Fonte

Por que diagramas baseados em texto vencem

O que importa	Mermaid em Markdown	Python / Imagem de IA
Diff legível no git	✅	❌ blob binário
Editável sem regenerar	✅	❌
Eficiente em tokens vs. prosa	✅ menor	❌ maior
Renderiza sem etapa de build	✅	❌ precisa de hospedagem
Interpretável por IA sem visão	✅	❌
Funciona em GitHub / GitLab / Notion	✅	⚠️ se hospedado
Acessível (leitores de tela)	✅ accTitle/accDescr	⚠️ precisa de texto alternativo
Conversível para imagem depois	✅ a qualquer momento	— já é imagem

O fluxo de trabalho em três fases

flowchart LR
    accTitle: Fluxo de Trabalho de Documentação em Três Fases
    accDescr: A Fase 1 Mermaid em markdown é sempre obrigatória e é a fonte da verdade. As Fases 2 e 3 são conversões downstream opcionais para saída polida.

    p1["📄 Fase 1<br/>Mermaid em Markdown<br/>(SEMPRE — fonte da verdade)"]
    p2["🐍 Fase 2<br/>Gerado por Python<br/>(opcional — gráficos de dados)"]
    p3["🎨 Fase 3<br/>Visuais Gerados por IA<br/>(opcional — polimento)"]
    out["📊 Entregável Final"]

    p1 --> out
    p1 -.->|"quando necessário"| p2
    p1 -.->|"quando necessário"| p3
    p2 --> out
    p3 --> out

    classDef required fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
    classDef optional fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    classDef output fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d

    class p1 required
    class p2,p3 optional
    class out output

A Fase 1 é obrigatória. Mesmo que você prossiga para a Fase 2 ou 3, o código-fonte Mermaid permanece versionado.

O que Mermaid pode expressar

Mermaid abrange 24 tipos de diagrama. Quase toda relação científica se encaixa em um:

Caso de uso	Tipo de diagrama	Arquivo
Fluxo de trabalho experimental / lógica de decisão	Fluxograma	references/diagrams/flowchart.md
Interações de serviço / chamadas de API / mensagens	Sequência	references/diagrams/sequence.md
Modelo de dados / esquema	Diagrama ER	references/diagrams/er.md
Máquina de estados / ciclo de vida	Estado	references/diagrams/state.md
Linha do tempo do projeto / roteiro	Gantt	references/diagrams/gantt.md
Proporções / composição	Pizza	references/diagrams/pie.md
Arquitetura de sistema (níveis de zoom)	C4	references/diagrams/c4.md
Hierarquia de conceitos / brainstorming	Mapa mental	references/diagrams/mindmap.md
Eventos cronológicos / história	Linha do tempo	references/diagrams/timeline.md
Hierarquia de classes / tipos de relacionamento	Classe	references/diagrams/class.md
Jornada do usuário / mapa de satisfação	Jornada do Usuário	references/diagrams/user_journey.md
Comparação de dois eixos / priorização	Quadrante	references/diagrams/quadrant.md
Rastreabilidade de requisitos	Requisito	references/diagrams/requirement.md
Magnitude de fluxo / distribuição de recursos	Sankey	references/diagrams/sankey.md
Tendências numéricas / gráficos de barras + linhas	Gráfico XY	references/diagrams/xy_chart.md
Layout de componentes / arranjo espacial	Bloco	references/diagrams/block.md
Status de item de trabalho / colunas de tarefas	Kanban	references/diagrams/kanban.md
Infraestrutura em nuvem / topologia de serviço	Arquitetura	references/diagrams/architecture.md
Comparação multidimensional / radar de habilidades	Radar	references/diagrams/radar.md
Proporções hierárquicas / orçamento	Mapa de árvore	references/diagrams/treemap.md
Protocolo binário / formato de dados	Pacote	references/diagrams/packet.md
Ramificação git / estratégia de merge	Grafo Git	references/diagrams/git_graph.md
Sequência estilo código (sintaxe de programação)	ZenUML	references/diagrams/zenuml.md
Padrões de composição de múltiplos diagramas	Exemplos Complexos	references/diagrams/complex_examples.md

💡 Escolha o tipo certo, não o mais fácil. Não use fluxogramas para tudo por padrão. Uma linha do tempo vence um fluxograma para eventos cronológicos. Uma sequência vence um fluxograma para interações de serviço. Varra a tabela e combine.

---

🔧 Fluxo de trabalho principal

Etapa 1: Identificar o tipo de documento

Verifique se existe um modelo antes de escrever do zero:

Tipo de documento	Modelo
Registro de pull request	templates/pull_request.md
Issue / bug / solicitação de funcionalidade	templates/issue.md
Sprint / quadro do projeto	templates/kanban.md
Decisão de arquitetura (ADR)	templates/decision_record.md
Apresentação / briefing	templates/presentation.md
Artigo de pesquisa / análise	templates/research_paper.md
Documentação do projeto	templates/project_documentation.md
Tutorial / guia prático	templates/how_to_guide.md
Relatório de status	templates/status_report.md

Etapa 2: Ler o guia de estilo

Antes de escrever qualquer arquivo .md: leia references/markdown_style_guide.md.

Regras principais a internalizar:

• Um H1 por documento — o título. Nunca mais.
• Emoji apenas em cabeçalhos H2 — um emoji por H2, nenhum em H3/H4
• Cite tudo — toda afirmação externa recebe uma nota de rodapé [^N] com URL completo
• Negrito com moderação — máximo 2-3 termos em negrito por parágrafo, nunca frases completas
• Linha horizontal após cada </details> — obrigatório
• Tabelas em vez de prosa para comparações, configurações, dados estruturados
• Diagramas em vez de paredes de texto — se descreve fluxo, estrutura ou relacionamentos, adicione Mermaid

Etapa 3: Escolher o tipo de diagrama e ler seu guia

Antes de criar qualquer diagrama Mermaid: leia references/mermaid_style_guide.md.

Em seguida, abra o arquivo de tipo específico (por exemplo, references/diagrams/flowchart.md) para o exemplo, dicas e modelo copiável.

Regras obrigatórias para cada diagrama:

accTitle: Nome Curto 3-8 Palavras
accDescr: Uma ou duas frases explicando o que este diagrama mostra.

• Sem diretivas %%{init} — quebra o modo escuro do GitHub
• Sem style inline — use apenas classDef
• Máximo um emoji por nó — no início do rótulo
• IDs de nó em snake_case — corresponda ao rótulo

Etapa 4: Escrever o documento

Comece pelo modelo. Aplique o guia de estilo de markdown. Coloque diagramas inline com o texto relacionado — não em uma seção separada de "Figuras".

Etapa 5: Commitar como texto

O arquivo .md com Mermaid incorporado é o que é commitado. Se você também gerou um PNG ou imagem de IA, estes são suplementares — o markdown é a fonte.

---

⚠️ Armadilhas comuns

Sintaxe do gráfico de radar (radar-beta)

ERRADO:

radar
title Exemplo
x-axis ["A", "B", "C"]
"Série" : [1, 2, 3]

CORRETO:

radar-beta
title Exemplo
axis a["A"], b["B"], c["C"]
curve series["Série"]{1, 2, 3}
max 3

• Use radar-beta não radar (a palavra-chave simples não existe)
• Use axis para definir dimensões, não x-axis
• Use curve para definir séries de dados, não rótulos entre aspas com dois pontos
• Sem accTitle/accDescr — radar-beta não suporta anotações de acessibilidade; sempre adicione um parágrafo descritivo em itálico acima do diagrama

Confusão entre Gráfico XY e Radar

Diagrama	Palavra-chave	Sintaxe do eixo	Sintaxe dos dados
Gráfico XY (barras/linhas)	xychart-beta	x-axis ["Label1", "Label2"]	bar [10, 20] ou line [10, 20]
Radar (teia/aranha)	radar-beta	axis id["Label"]	curve id["Label"]{10, 20}

Esquecer accTitle/accDescr em tipos suportados

Apenas alguns tipos de diagrama suportam accTitle/accDescr. Para aqueles que não suportam, sempre coloque um parágrafo descritivo em itálico diretamente acima do bloco de código:

Gráfico de radar comparando três métodos em cinco dimensões de desempenho. Nota: Gráficos de radar não suportam accTitle/accDescr.

radar-beta
...

---

🔗 Integração com outras habilidades

Com scientific-schematics

scientific-schematics gera imagens de qualidade de publicação geradas por IA (PNG). Use o diagrama Mermaid como o briefing para o esquema:

Fluxo de trabalho:
1. Crie o conceito como Mermaid em .md (esta habilidade — Fase 1)
2. Descreva o mesmo conceito para scientific-schematics para um PNG polido (Fase 3)
3. Commite ambos — o .md como fonte, o PNG como figura suplementar

Com scientific-writing

Quando scientific-writing produzir um manuscrito, todos os diagramas e figuras estruturais devem usar os padrões desta habilidade. A habilidade de escrita lida com prosa e citações; esta habilidade lida com estrutura visual.

Fluxo de trabalho:
1. Use scientific-writing para redigir o manuscrito
2. Para cada figura que mostra um fluxo de trabalho, arquitetura ou relacionamento:
   - Substitua o espaço reservado por um diagrama Mermaid seguindo o guia desta habilidade
3. Use scientific-schematics apenas para figuras que realmente precisam de renderização complexa/fotorrealista

Com literature-review

Literature review produz resumos com muitos dados de relacionamento. Use esta habilidade para:

• Criar mapas conceituais (Mapa Mental) do panorama da literatura
• Mostrar linhas do tempo de publicação (Linha do Tempo ou Gantt)
• Comparar metodologias (Quadrante ou Radar)
• Diagramar fluxos de dados descritos em artigos (Sequência ou Fluxograma)

Com qualquer habilidade que produza documentos de saída

Antes de finalizar qualquer documento de qualquer habilidade, aplique a lista de verificação desta habilidade:

• O documento usa um modelo? Se sim, comecei pelo modelo correto?
• Todos os diagramas estão em Mermaid com accTitle + accDescr?
• Sem %%{init}, sem style inline, apenas classDef?
• Todas as afirmações externas citadas com [^N]?
• Um H1, emoji apenas no H2?
• Linhas horizontais após cada </details>?

---

📚 Índice de referência

Guias de estilo

Guia	Caminho	Linhas	O que cobre
Guia de Estilo Markdown	references/markdown_style_guide.md	~733	Cabeçalhos, formatação, citações, tabelas, integração Mermaid, modelos, lista de verificação de qualidade
Guia de Estilo Mermaid	references/mermaid_style_guide.md	~458	Acessibilidade, conjunto de emojis, classes de cores, neutralidade de tema, seleção de tipo, níveis de complexidade

Guias de tipo de diagrama (24 tipos)

Cada arquivo contém: exemplo de qualidade de produção, dicas específicas para aquele tipo e um modelo copiável.

references/diagrams/ — architecture, block, c4, class, complex_examples, er, flowchart, gantt, git_graph, kanban, mindmap, packet, pie, quadrant, radar, requirement, sankey, sequence, state, timeline, treemap, user_journey, xy_chart, zenuml

Modelos de documento (9 tipos)

templates/ — decision_record, how_to_guide, issue, kanban, presentation, project_documentation, pull_request, research_paper, status_report

Exemplos

assets/examples/example-research-report.md — um relatório de pesquisa científica completo demonstrando hierarquia de cabeçalhos adequada, múltiplos tipos de diagrama (fluxograma, sequência, gantt), tabelas, citações em notas de rodapé, seções recolhíveis e todas as regras do guia de estilo aplicadas.

---

📝 Atribuição

Todos os guias de estilo, guias de tipo de diagrama e modelos de documento nesta habilidade são portados do repositório SuperiorByteWorks-LLC/agent-project sob a Licença Apache-2.0.

• Fonte: https://github.com/SuperiorByteWorks-LLC/agent-project
• Autor: Clayton Young / Superior Byte Works, LLC (@borealBytes)
• Licença: Apache-2.0

Esta habilidade (como parte de scientific-agent-skills) é distribuída sob a Licença MIT. O conteúdo incluso sob Apache-2.0 é compatível para uso downstream com atribuição retida, conforme preservado nos cabeçalhos dos arquivos ao longo desta habilidade.

---