HTMX propõe Markdown em /src como especificação executável

Markdown como código-fonte

Carson Gross, professor da Montana State University e criador do htmx, argumenta que Markdown está se tornando código-fonte, e não documentação - e que ele deveria ser versionado em /src, ao lado do código que produz. O código e os testes, propõe ele, deveriam ser derivados desse Markdown, e não de sessões de prompt efêmeras. Ao citar o ensaio "Markdown is the new source code", de Hartley Brody, que descreve a lógica do aplicativo sendo definida em Markdown enquanto o código gerado pelo agente vira um detalhe de implementação, Gross se mostra ambivalente sobre código gerado por IA, mas observa que as organizações com que consulta seguem nessa direção rapidamente.

O problema do código-fonte ausente

Uma analogia comum compara LLMs a compiladores: não precisamos ler o código gerado, como não lemos código de máquina. Gross discorda parcialmente; a razão relevante aqui é que fluxos de compilador preservam o código-fonte original, enquanto fluxos de LLM normalmente não. Hoje, código gerado por prompts efêmeros acaba sendo a única "veridade de base" da funcionalidade no repositório - tickets, wikis e threads de Slack existem, mas não vivem junto do código.

Proposta de captura

Gross defende aceitar que código derivado de sessões efêmeras não é ideal e mover o trabalho para Markdown persistido em /src. O Markdown tem propriedades de código: é texto puro (diffável, greppable, revisável em pull requests), LLMs leem e escrevem nativamente, e humanos editam sem ferramentas. Ele já funciona como fonte de alguma forma em AGENTS.md, especificações e TASK.md - o que falta é padronizar a captura. A sugestão é promover esses arquivos a um diretório /src/md, contendo decisões arquiteturais, de código-fonte e de baixo nível, mais próximo de uma especificação (ainda que não uma) do que de um documento de design tradicional.

Localidade e divisão com testes

Colocar Markdown em /src traz vantagens de localidade: os módulos passam a incluir o que explica a intenção do código, eliminando o "specification at a distance" espalhado em Notion ou Jira, e o mesmo arquivo é consumível por humanos e agentes. Wikis e ferramentas de issues continuariam existindo para documentação de alto nível e fluxos de processo. Quanto aos testes, Gross reconhece o argumento de que "testes são a nova especificação", mas acha que eles são ruins para interação humano-agente: cerimônia demais, nível baixo demais e sem espaço para diagramas como Mermaid. A divisão proposta: Markdown em /src como especificação(ish); testes em /test, derivados do Markdown, como confirmação automatizada.

Estrutura e ressalvas

O Markdown em /src/md tem um orçamento de complexidade e exigirá gestão cuidadosa. Desenvolvedores precisarão sincronizar Markdown e código derivado - mudanças restritivas feitas diretamente no código gerado podem precisar voltar para o Markdown. Gross recomenda que agentes não gerem conteúdo nesse diretório: ele deve ser mantido principalmente por humanos. Ele admite que a convenção proposta (README.md como índice, TODO.md, OVERVIEW.md e subpastas opcionais de features, data, api e infrastructure) é a parte mais fraca do ensaio, pois a ideia é nova e pouco testada, e espera que o pensamento evolua.

Conclusão

Se o código fica barato de gerar, o que permanece valioso é a intenção: o que o código faz, por que faz e o que não deve fazer. Essa intenção hoje se perde em sessões de prompt ou se dispersa em wikis e tickets. A sugestão final é capturá-la em Markdown versionado em /src, onde humanos e agentes possam encontrá-lo - com a ressalva explícita de que, apesar da analogia, LLMs não são compiladores.