Criei um Gerador de llms.txt e Tive que Reescrever Tudo

Este é um acompanhamento do meu post anterior — eu lancei a v1, recebi feedback do criador do padrão e tive que repensar tudo.

Não vou fingir que tinha um plano. Eu não tinha.

Há um novo padrão chamado llms.txt — um arquivo que você coloca na raiz do seu site para ajudar agentes de IA a navegar seu conteúdo. Pense nisso como robots.txt para agentes de IA: em vez de dizer aos crawlers o que ignorar, ele diz aos agentes como entender seu site.

Eu vi outros geradores produzindo isso. Eu construí um também, lancei e pensei que havia terminado.

Então eu conversei com Jeremy Howard — o criador do padrão — e descobri que eu havia entendido fundamentalmente errado o que o llms.txt deveria ser. E então as coisas ficaram complicadas.

Versão 1: Copiando o que Todos os Outros Estavam Fazendo

O padrão que cada gerador estava produzindo:

- [Título da Página](https://example.com/page): resumo gerado por IA.
- [Outra Página](https://example.com/other): resumo gerado por IA.

Uma URL → um resumo. Eu fiz o mesmo. Eu chamei isso de Estratégia Plana e lancei. Ainda está no gerador porque as pessoas pedem por isso. Mas eu não acho mais que seja para isso que o llms.txt realmente serve.

A Conversa Que Mudou Tudo

Cerca de seis semanas após o lançamento, eu postei no Discord do llms.txt e perguntei diretamente a Jeremy Howard.

Eu:

Para um site como o Stripe com 4.000 páginas, como você equilibra curadoria vs completude? Se você curar para 20 páginas, um agente perguntando sobre tentativas de webhook não encontrará a resposta. Se você incluir tudo, é apenas ruído.

Jeremy Howard (fonte):

"Sim, na verdade é muito trabalho - não é apenas escrever um llms.txt, mas escrever documentos completos orientados a agentes. É basicamente como uma web paralela - uma projetada para IA! Um llms.txt é apenas a substituição do index.html da IA - contém links para outras páginas md, que por sua vez podem ter links."

E então a parte que realmente me pegou — ele não estava apenas descrevendo uma estrutura diferente. Ele estava dizendo que o llms.txt não deveria ser gerado automaticamente. Ele deveria ser cuidadosamente curado por humanos que entendem seu site.

Eu fiquei pensando nisso por um tempo.

Por um lado, ele está certo. Por outro lado — o Stripe tem 4.000 páginas. Ninguém está escrevendo aqueles arquivos MD à mão. E o weather.com tem 1.140.000 URLs. A matemática não funciona para curadoria humana em escala.

Então eu decidi tentar mesmo assim. Se não pode ser feito automaticamente, vamos ver quão perto podemos chegar.

Eu (fonte):

"Isso muda tudo. A tensão entre 'curadoria vs completude' que eu estava preocupado desaparece quando você tem divulgação progressiva através de uma hierarquia."

Então eu fui e construí a Versão 2.

O Que a Versão 2 Realmente Exigiu

A visão era simples: agrupar semanticamente páginas relacionadas, sintetizar cada grupo em um único arquivo MD. Um agente recebe 30 documentos focados em vez de 4.000 páginas individuais.

A realidade eram cinco problemas de engenharia separados, cada um escondido atrás do anterior.

Problema 1 — Janelas de contexto. Para agrupar páginas por significado, você precisa lê-las. 4.000 páginas de texto completo não cabem em nenhuma janela de contexto de LLM. Solução: embeddings + clustering k-means. Cada página se torna um vetor, páginas semelhantes se agrupam, o LLM vê apenas um cluster por vez.

Problema 2 — Dinheiro. Cada chamada de LLM estava enviando o mesmo conteúdo do cluster repetidamente como tokens de entrada. Para um cluster gerando 5 arquivos MD, eu estava pagando por aquelas páginas 5 vezes. Solução: Cache de Contexto Gemini. Carregue o conteúdo do cluster uma vez, reutilize a referência em cache para todas as chamadas subsequentes dentro daquele cluster.

Problema 3 — Camadas em diferentes velocidades. Crawling, embedding e resumo funcionam em velocidades completamente diferentes. Conectá-los de forma ingênua faz com que se bloqueiem mutuamente — o crawler acumula trabalho enquanto o resumidor fica sem trabalho. Solução: buffers em memória entre cada camada, com controle de concorrência independente por camada.

Problema 4 — O LLM é imprevisível. Em escala, tudo falha eventualmente. O Gemini retorna 429, 503, JSON válido com o número errado de itens, JSON inválido ou simplesmente expira após 4 minutos. Solução: hierarquia de exceções tipadas para falhas de LLM, fila AIMD com recuo adequado que lê os valores reais de retry-after da API do Google em vez de adivinhar.

Problema 5 — Espaços em alemão. Por razões que ainda não entendo completamente, o Gemini às vezes responde a conteúdo em alemão com uma resposta válida seguida de aproximadamente 2.000.000 espaços. Isso atinge os limites máximos de tokens e causa falhas. Solução: 3 tentativas, depois a tarefa é descartada — mas a ordem permanece no banco de dados e pode ser reiniciada a partir do frontend. Resultados intermediários são armazenados em cache no Redis, então reiniciar retoma de onde parou sem gastar tokens novamente.

Cada problema só se tornou visível após resolver o anterior. É assim que as coisas funcionam.

O Problema Não Resolvido: Sites Multilíngues

Quando comecei, a documentação do Stripe tinha ~3.500 URLs. Então eles adicionaram traduções em alemão e pulou para ~4.300. O gerador processou tudo e começou a produzir arquivos MD em alemão para o que deveria ser um site de documentação em inglês.

Não há uma lógica universal para detectar conteúdo canônico em uma única língua a partir de um sitemap. Cada site tem seu próprio esquema de URL. Correção planejada: um filtro de padrão de URL como um parâmetro de ordem — você especifica quais padrões incluir, o crawler respeita isso.

Uma Observação Sobre o Futuro

Enquanto construía isso, percebi algo: já existem ferramentas que geram sites de documentação completos e legíveis por humanos a partir de arquivos de origem markdown.

Isso abre um fluxo de trabalho interessante:

1. Gerar llms.txt + markdown estruturado (a camada de IA)
2. Gerar o site voltado para humanos a partir desses mesmos arquivos markdown

O markdown se torna a fonte da verdade. Escreva uma vez, publique duas — uma versão para humanos, uma para agentes de IA.

Epílogo

Eu não sei se isso algum dia me fará um dólar.

Mas desde que construí isso, as pessoas começaram a entrar em contato pelo LinkedIn. Convites para entrevistas começaram a chegar. Eu conversei com a Microsoft hoje.

E eu acho genuinamente engraçado quando recebo avaliações de codificação que me pedem para construir um serviço de notificação — código limpo, arquitetura escalável, design de banco de dados perfeito, dockerizado, totalmente testado — em 3 dias.

Eu passei vários meses construindo algo como o que você acabou de ler, e ainda não tenho certeza se acertei.

Aquelas avaliações de 3 dias me fazem rir.

*Quer entender como isso realmente funciona nos bastidores — embeddings, clustering, cache de contexto, a fila AIMD? Eu escrevi um mergulho técnico separado: link.