YAML, Markdown, JSON: o sweet spot para LLM

O formato certo
→ pro artefato certo.

Os três formatos parecem intercambiáveis até você usar o errado. Aí o LLM se perde no ruído ou o parsing quebra. Cada formato tem um trabalho, e casar formato com artefato evita as duas dores.

3 formatosYAML, Markdown, JSON

1 regracasar o formato com o trabalho do artefato

0 ruídoformato certo não polui o contexto

Legenda de coresOs 3 formatos e o erro

YAML

Markdown

JSON

Sweet spot

Ruído

Mapa da aula

Use este mapa para entender a sequência da aula antes de entrar nos detalhes.

Legenda de coresOs 3 formatos e o erro

YAMLconfig e dados que humano edita

Markdownprosa e instrução que o LLM lê

JSONtroca entre máquinas, schema estrito

Sweet spotformato casado com o artefato

Ruídoformato errado quebra parsing ou polui

Cada formato tem um trabalho

Formato não é gosto, é função. YAML é feito pra config legível. Markdown é feito pra texto. JSON é feito pra troca estrita. Usar fora do trabalho gera ruído pro LLM ou erro de parsing.

A regra que sustenta a aulaPergunte qual é o trabalho do artefato antes de escolher o formato. Se é config que humano edita e o LLM lê, é YAML. Se é prosa ou instrução, é Markdown. Se é troca entre sistemas com schema estrito, é JSON. Errar o formato custa ruído de contexto ou parsing quebrado.

Formato por hábito

JSON pra config que humano edita na mão.
Markdown pra dados estruturados que precisam ser parseados.
YAML aninhado fundo pra dado de troca entre sistemas.
Mistura tudo e deixa o LLM adivinhar a estrutura.

Formato por trabalho

YAML pra config: legível, sem ruído de aspas e vírgulas.
Markdown pra prosa e instrução que o LLM lê como texto.
JSON pra troca estrita entre máquinas.
Cada artefato no formato que o trabalho dele pede.

O caminho da aula

Três movimentos: entender o trabalho de cada formato, ver o caso do formato errado que gerou ruído, e escolher o formato dos seus artefatos.

Os 3 movimentos

1. O trabalho de cada formatoYAML, Markdown e JSON e o que cada um faz bem.

2. O formato erradoo caso do JSON de config que virou fonte de erro.

3. Escolher por critériocasar o formato com cada artefato do projeto.

[ a ] Você vai sair sabendo

O trabalho que cada formato faz bem e mal.
Por que o formato errado gera ruído ou parsing quebrado.
O critério para escolher entre YAML, Markdown e JSON.

[ b ] Você vai sair fazendo

A escolha de formato para cada artefato do seu projeto, justificada por critério.

Cluster 1 / 3cada formato tem um trabalho · YAML config, Markdown prosa, JSON troca · formato errado gera ruído

Você tem o mapa. Agora vê o caso de um formato errado que custou caro.

Caso Real

O JSON de config que virou fonte de erro

Uma config que humano editava na mão estava em JSON. Vírgula a mais, aspas faltando, e o parsing quebrava toda semana. Trocar para YAML acabou com a classe inteira de erro.

Trocar o formato matou a classe de erro

JSON é ótimo entre máquinas e péssimo na mão humana. Cada vírgula e aspas é uma chance de quebrar o parsing.

Rota · action

Começou comoConfig editada na mão por humanos, guardada em JSON estrito.

VirouA mesma config em YAML, legível, sem ruído de aspas e vírgulas.

ProvaA classe de erro de parsing por vírgula ou aspas faltando sumiu.

LiçãoConfig que humano edita pede YAML. JSON estrito é para troca entre máquinas.

SituaçãoUm projeto guardava config que pessoas editavam à mão em JSON. Toda semana alguém esquecia uma vírgula ou aspas e o parsing quebrava.

DecisãoMigrar a config para YAML, que é legível, tolera comentários e não exige aspas em tudo.

EvidênciaEm aula-07, o time mostra o sweet spot: YAML para config humana, JSON para interchange entre sistemas.

Mensagem ao alunoQuando humano edita, YAML. Quando é troca entre máquinas com schema estrito, JSON. Não troque os papéis.

ContextoEm aula-07, o framing técnico do sweet spot mostra cada formato no seu trabalho e o custo de errar.

Percepção-chaveJSON não tem comentário, exige aspas em tudo e quebra com uma vírgula sobrando. Isso é ótimo para máquina e hostil para humano. YAML inverte isso.

DecisãoUsar YAML onde humano edita, Markdown onde é prosa, JSON onde é troca estrita entre sistemas.

1Sintomaparsing da config quebra toda semana.

2Diagnósticohumano edita JSON estrito, vírgula e aspas viram erro.

3Trocamigra a config para YAML, legível e tolerante.

4Resultadoa classe de erro de parsing por sintaxe some.

0 vírgulasYAML não cobra aspas e vírgulas em tudo

ComentáriosYAML aceita comentário, JSON não

Classe mortao erro de parsing por sintaxe sumiu

Adequação de cada formato por tipo de artefato

Config humana em YAML
95%
Config humana em JSON
40%
Troca entre máquinas em JSON
95%
Instrução longa em Markdown
90%

Cluster 2 / 3JSON de config quebrava · YAML para edição humana · formato mata classe de erro

Você viu o custo do formato errado. Agora a técnica: o trabalho de cada formato e o critério de escolha.

Trilogia

WHY / WHAT / HOW do sweet spot

As 3 camadas que transformam a escolha de formato de gosto em critério.

WHY - Formato errado vira ruído

O LLM lê o que você dá. Formato fora do trabalho dele adiciona ruído (sintaxe que o humano erra) ou quebra o parsing (estrutura que a máquina não fecha). O custo aparece como erro ou alucinação.

WHYruído

WHAT - Cada formato no seu trabalho

YAML para config e dados que humano edita e o LLM lê. Markdown para prosa, instrução e documentação. JSON para troca entre máquinas e schema estrito.

WHATtrabalho do formato

HOW - Pergunte o trabalho do artefato

Antes de escolher, pergunte: quem edita e quem consome? Humano editando é YAML. Texto pra ler é Markdown. Máquina trocando com schema é JSON. A resposta nomeia o formato.

HOWquem edita, quem consome

Os 3 formatos por dentro

Cada formato com o que faz bem, o que faz mal e o artefato típico. A grade que você consulta ao decidir.

YAML◇ signal

Legível, aceita comentário, sem ruído de aspas. Ótimo pra config e dados que humano edita.

Markdown✦ insight

Texto com estrutura leve. Ótimo pra prosa, instrução e documentação que o LLM lê.

JSON▲ bench

Estrito, sem comentário, exige sintaxe perfeita. Ótimo pra troca entre máquinas e schema.

FormatoFaz bemFaz malArtefato típico

YAML

Faz bemconfig legível, comentários

Faz maldado profundo de máquina

Artefato típicocore-config, frontmatter, content.yaml

Markdown

Faz bemprosa e instrução

Faz maldado estruturado parseável

Artefato típicoCLAUDE.md, docs, prompts

JSON

Faz bemtroca estrita, schema

Faz maledição humana na mão

Artefato típicoAPI, interchange, registry

A sequência de escolha

Os passos concretos para escolher o formato de um artefato sem cair no hábito.

◇▶ signal_plus_action

Escolher o formato de um artefato

Use ao criar qualquer arquivo novo no projeto.

quem-edita→quem-consome→estrutura→decidir

quem-edita — Humano edita na mão ou só máquina escreve?
quem-consome — O LLM lê como texto, ou um sistema parseia com schema?
estrutura — É prosa, é config tabular, ou é troca estrita?
decidir — Humano + config = YAML. Texto = Markdown. Máquina + schema = JSON.

Da pergunta ao formato

Quem edita?

humano na mão ou máquina.

É prosa?

se é texto pra ler, Markdown.

É config humana?

se humano edita estrutura, YAML.

É troca estrita?

se máquina troca com schema, JSON.

Não confunda os papéis

Três confusões que levam ao formato errado e ao ruído que vem junto.

Não confundaYAML para humano, não JSON para humano

JSON parece mais sério e estruturado.

Esclareça: JSON é hostil para edição humana: sem comentário, aspas em tudo, quebra com uma vírgula. YAML é o formato de config humana.

Não confundaMarkdown para prosa, não para dado tabular

Markdown parece organizar tudo com tabelas.

Esclareça: Tabela Markdown não é parseável de forma confiável. Dado estruturado vai pra YAML ou JSON, não pra tabela de texto.

Não confundaJSON para máquinas, não para config editável

JSON é universal entre sistemas.

Esclareça: Entre máquinas, perfeito. Quando humano precisa editar, ele vira fonte de erro de sintaxe.

Humano edita config

formato = YAML.

Texto e instrução pra ler

formato = Markdown.

Troca estrita entre sistemas

formato = JSON.

Cluster 3 / 3trilogia do sweet spot · grade dos 3 formatos · sequência de escolha

Você tem a técnica. Agora a prática: escolha o formato de cada artefato do seu projeto.

Prática

Prática: escolha o formato dos seus artefatos

Liste os artefatos do seu projeto e escolha o formato de cada um por critério, não por hábito.

aula.yaml8 linhas

01# Escolha por criterio, nao por habito. Uma entrada por artefato.02artefatos: 03  - artefato: "{nome do arquivo ou tipo}"04    quem_edita: "{humano | maquina}"05    quem_consome: "{llm-como-texto | sistema-com-schema}"06    estrutura: "{prosa | config | troca-estrita}"07    formato: "{yaml | markdown | json}"08    justificativa: "{por que esse formato}"

Portão da aulaAntes de seguir para a próxima aula: você listou 5 artefatos do seu projeto e escolheu o formato de cada um com justificativa por critério. Se algum artefato editado por humano ficou em JSON, reveja antes de passar.

Liste os artefatos: Escreva 5 artefatos do seu projeto: configs, docs, dados, arquivos de troca.
Quem edita cada um: Para cada artefato, diga se humano edita na mão ou só máquina escreve.
Quem consome cada um: Diga se o LLM lê como texto ou um sistema parseia com schema.
Escolha o formato: Humano + config = YAML. Texto = Markdown. Máquina + schema = JSON.
Justifique: Escreva uma frase por artefato explicando por que esse formato e não outro.

Glossário

Os termos desta aula em uma frase cada.

Sweet spot do formato

O ponto em que o formato casa com o trabalho do artefato: YAML config, Markdown prosa, JSON troca.

YAML

Formato legível para config e dados que humano edita. Aceita comentário, dispensa aspas em tudo.

Markdown

Formato de texto com estrutura leve. Para prosa, instrução e documentação lida pelo LLM.

JSON

Formato estrito para troca entre máquinas e schema. Hostil para edição humana.

Ruído de contexto

O custo de um formato fora do seu trabalho: sintaxe que humano erra ou parsing que a máquina não fecha.

Próxima aulaVocê escolhe o formato certo para cada artefato. Com o setup operacional fechado (janela, faxina e formato), M3 entra no ciclo SDC: como o trabalho de fato roda no AIOX.