Nem todo documento de repositório pertence ao Markdown

Seu time passou duas semanas no plano para colocar agentes de IA em três squads. Donos, riscos, um pedido de orçamento, e uma decisão de seguir ou não seguir que o VP precisa assinar. O plano vive no repositório de código compartilhado, então alguém salvou como um arquivo de texto simples, o plan.md. O VP abre, rola seiscentas linhas de títulos e bullets, e responde: "vamos discutir na próxima reunião."

O plano não falhou porque estava errado. Ele falhou porque ninguém conseguiu lê-lo até uma decisão. O conteúdo estava todo lá. O meio enterrou.

Minha posição: markdown virou padrão para documento de repositório porque é um ótimo formato de fonte. Isso não é a mesma coisa que ser um bom formato de leitura. No instante em que o trabalho de um documento é fazer um humano decidir, o formato em que você escreveu vira parte de se ele consegue.

Fonte e artefato são dois trabalhos diferentes

Existe uma distinção que a maioria dos times junta numa coisa só: o formato em que você escreve e o formato em que alguém lê não precisam ser a mesma coisa.

Um formato de fonte é feito para as pessoas e ferramentas que produzem e mantêm um documento. Ele faz diff limpo, é revisado num pull request, um agente consegue ingerir, um engenheiro consegue ler sem abrir o navegador. O Markdown é quase perfeito nisso. É por isso que ele virou o padrão, e ele merece o padrão.

Um formato de leitura é feito para a pessoa que consome o documento, uma vez, para fazer um julgamento. Ele tem uma hierarquia que diz ao olho o que importa mais. Ele tem uma ordem de leitura. A decisão é a coisa em que você aterrissa, não o décimo quarto bullet embaixo do quarto título.

A maioria dos documentos de repositório só precisa do primeiro trabalho. Um README orienta um desenvolvedor. Um runbook ajuda um operador a se recuperar. Uma regra de agente precisa ser curta o suficiente para o modelo não passar batido pela invariante. O Markdown é excelente para cada um desses, porque o leitor é técnico, o documento é referência, e ler o texto cru funciona bem.

O problema começa com os documentos que têm o outro trabalho.

O Markdown te disse o que ele é, e o GitHub também

Volte para o que o Markdown era. John Gruber, que criou o Markdown, foi explícito sobre o trabalho que ele faz:

O Markdown permite que você escreva num formato de texto simples fácil de ler e fácil de escrever, e depois o converta em HTML estruturalmente válido.

Leia de novo. O Markdown nunca foi o formato de leitura. Ele sempre foi a fonte, e o HTML era a coisa que o leitor recebia. A conversão é o ponto inteiro.

O GitHub, que fez mais do que ninguém para tornar o .md a língua universal de repositório, traça a mesma fronteira na própria ferramenta. Quando ele renderiza o seu Markdown, o HTML é sanitizado, removendo de forma agressiva coisas como tags de script, estilos embutidos, e atributos de class ou id. É o GitHub se recusando a deixar todo README fingir que é um site. A plataforma que normalizou Markdown em todo lugar limita de propósito quanta experiência de leitura você consegue espremer dele. Se você se pega brigando com o sanitizador para deixar um documento bonito, o documento está te dizendo que queria ser um artefato, não um README.

O mesmo plano, como algo que um humano consegue aprovar

Pegue o plano de adoção de volta e não mude nada do conteúdo. Mesmos donos, mesmos riscos, mesmo orçamento, mesma decisão. Mude só o meio.

Agora o status de cada frente é algo que o olho pega numa passada, não uma palavra enterrada numa frase. A tabela de riscos rola dentro do próprio contêiner em vez de quebrar virando ruído. A única coisa que precisa de assinatura é visualmente a mais alta da página. As premissas que o VP está de fato aprovando ficam no próprio bloco, não intercaladas com notas de implementação feitas para um engenheiro.

O VP aprova em quatro minutos, porque pela primeira vez o documento faz o único trabalho para o qual existia: produzir uma decisão.

Repare no que não aconteceu. Ninguém jogou o Markdown fora. A fonte do plano pode continuar em texto simples no repositório, revisada num pull request, com diff linha a linha. O que mudou é que a superfície de leitura deixou de ser a fonte crua. É esse o movimento inteiro: manter o formato de fonte, e parar de forçá-lo a ser também o formato de leitura.

Se você está brigando com o Markdown para deixar um documento aprovável, você não tem um problema de escrita. Você tem um documento fazendo um trabalho para o qual o formato dele nunca foi feito.

"Mas tudo deveria ser texto simples no git"

Aqui está a objeção mais forte, e ela é boa. O movimento docs-as-code, bem descrito pelo Write the Docs, defende que você deveria escrever documentação com as mesmas ferramentas do código: controle de versão, marcação em texto simples, code review, testes automatizados. Um purista lê isso como: então todo documento é Markdown, fim de papo. Adicionar uma segunda via de renderização é inchaço de ferramenta, um segundo frontend que ninguém pediu.

Eu levo isso a sério, porque o custo é real. Um artefato HTML avulso é mais caro de revisar, fazer diff e manter do que um arquivo .md. Recorra a ele sem critério e você cria exatamente a bagunça contra a qual a objeção avisa.

Mas docs-as-code é uma afirmação sobre o fluxo de trabalho, não sobre a superfície de leitura. Fonte no git, revisada, testada. Nada disso exige que o leitor consuma a fonte crua. Os sistemas de documentação maduros provam: o livro do Rust é escrito em Markdown e renderizado num livro navegável pelo mdBook, que literalmente se descreve como um jeito de criar um livro a partir de arquivos Markdown. MDX, Docusaurus, e ferramentas como elas existem justamente para manter uma fonte revisada em texto simples e ainda entregar um artefato de leitura de verdade. Fonte contra artefato não é uma violação do docs-as-code. É o docs-as-code levado até o fim.

Tem até um motivo de performance para manter os dois separados, e não é "HTML rápido, Markdown lento." A pergunta de verdade é onde a conversão de Markdown para HTML acontece. Faça uma vez, antes da hora, do jeito que a geração estática do Next.js monta o HTML antes de a requisição chegar, e o leitor não paga nada por isso. Faça a cada visita de página, no servidor ou pior no navegador do leitor, e você moveu trabalho de documentação para dentro do tráfego dos usuários. Fonte barata pode virar, em silêncio, leitura cara.

A regra que eu uso agora

Eu não colocaria HTML em todo lugar. Essa é a armadilha do segundo frontend, e a objeção tem razão sobre ela. A regra é sobre trabalhos, não sobre formatos.

Mantenha o Markdown como fonte e como superfície de leitura para tudo cujo leitor seja uma máquina, um desenvolvedor, ou um code review:

• READMEs, regras de agente, e configs de ferramenta.
• specs duráveis, ADRs, runbooks, e documentos de conceito.
• qualquer coisa que um agente ingere ou um engenheiro lê como referência.

Renderize um artefato voltado para humano quando o leitor é uma pessoa fazendo um julgamento e a experiência de leitura é o entregável:

• planos e briefs de estratégia que um stakeholder precisa aprovar.
• relatórios para executivos e para clientes.
• relatórios de QA visual e artefatos de design.

E uma restrição é inegociável: o artefato precisa ser semântico e acessível, não uma pilha bonita de caixas aninhadas. A orientação de acessibilidade da MDN é o comprovante chato aqui, títulos de verdade, rótulos, texto de link, e estrutura alcançável pelo teclado. Um artefato semântico que um leitor de tela consegue navegar é o entregável. Um inacessível é só um PDF com passos a mais.

Isso importa mais conforme os times ficam AI-native, não menos. Agentes geram mais documentos, não menos. Toda execução quer contexto, todo plano quer critério de aceite, todo review quer evidência, todo handoff quer um retrato do momento. O movimento barato é despejar tudo isso em Markdown porque Markdown é barato de produzir. Mas o loop em que o trabalho AI-native de fato roda é: a máquina rascunha, o humano decide, a máquina age, o humano verifica. Os dois passos humanos são passos de leitura. Se cada um deles for uma parede de fonte crua, você otimizou para quem escreve e taxou quem decide.

Markdown é um formato de fonte. Peça para ele ser a fonte e ele é a melhor ferramenta que você tem. Peça para ele ser também o artefato que um humano assina, e você está usando uma chave de fenda como martelo. Funciona, até o dia em que a decisão realmente importa.