Por que uma melhor documentação não vai corrigir as alucinações da IA

Um amigo meu passou seis horas depurando uma integração do Stripe Connect na semana passada.

Ele estava usando o Cursor. Ele estava usando o Claude 3.5 Sonnet. Ele estava usando uma das APIs mais bem documentadas do mundo.

Por seis horas, o modelo continuou inserindo um cabeçalho de webhook chamado X-Stripe-Connect-Signature em sua lógica de verificação. Ele o copiou. Ele testou. Ele leu a documentação. Ele leu novamente. Ele pediu ao modelo para "verificar a documentação oficial."

O modelo continuou fazendo isso.

O cabeçalho não existe.

A Stripe verifica webhooks do Connect com Stripe-Signature — o mesmo cabeçalho que usa para tudo o mais. A versão "Connect" foi algo que o modelo havia inventado silenciosamente em algum momento durante o ajuste fino, e agora cada agente em sua pilha estava reproduzindo isso com confiança sob demanda.

Ele não é um engenheiro júnior. Ele já lançou seis startups. Ele cometeu o mesmo erro que quase toda equipe que usa assistentes de codificação de IA está cometendo agora: ele assumiu que a documentação era o problema.

Não era. Quase nunca é.

O Diagnóstico Que Todos Erram

Entre em qualquer Slack de engenharia de IA agora e você ouvirá a mesma conversa se repetindo:

"Nossos agentes continuam alucinado nossa API. Precisamos melhorar a documentação."

Então as equipes melhoram a documentação. Elas reescrevem endpoints. Elas adicionam exemplos de código. Elas comissionam um Markdown melhor. Elas migram para frameworks de documentação mais sofisticados. Elas publicam um Notion. Elas publicam um OpenAPI. Elas publicam um llms.txt.

E as alucinações continuam acontecendo.

Porque o diagnóstico está errado.

APIs alucidadas não são um problema de escrita. Não são um problema de tom. Não são nem mesmo um problema de "a documentação está incompleta".

Elas são um problema de estrutura. A forma como a documentação é moldada na web é fundamentalmente hostil à maneira como os modelos realmente leem.

Como a Alucinação Realmente Se Parece em Produção

Abra a aba de rede na próxima vez que você usar qualquer assistente de codificação de IA contra a documentação de um produto real.

Você verá uma das três coisas:

1. O agente rastreou a raiz da documentação, pegou os primeiros 12 KB de HTML renderizado e chamou isso de dia.
2. O agente recuperou três ou quatro pedaços de um índice vetorial — geralmente os pedaços errados, porque o modelo de incorporação não tem ideia de que sua página de "Autenticação" é a fonte canônica para o comportamento do cabeçalho.
3. O agente não recuperou nada, porque a documentação é um aplicativo de página única em JavaScript e o rastreador não conseguiu ver além do carregador.

Em todos os casos, o modelo está sendo solicitado a responder a uma pergunta precisa, em nível de esquema — "qual cabeçalho eu uso para verificar este webhook?" — usando prosa escrita para humanos que devem ler a página de cima para baixo e entender o contexto a partir do layout, barra lateral e tom.

O modelo não entende layout. Ele não entende barra lateral. Ele não entende tom. Ele recebe um saco achatado de parágrafos com a maior parte do sinal estrutural removido.

Então ele preenche as lacunas. Ele faz o que os modelos de linguagem sempre fazem: produz algo que soa como um cabeçalho do Stripe, porque tudo em seus dados de treinamento diz que cabeçalhos existem e são nomeados de uma certa maneira.

Isso é alucinação. Não é uma falha de criatividade. É uma falha de estrutura.

Por Que "Documentos Melhores" Não Mudam a Situação

Imagine que você quisesse ensinar um novo engenheiro júnior a chamar sua API.

Você daria a eles:

• ✅ A especificação OpenAPI
• ✅ Uma coleção Postman
• ✅ O código-fonte do SDK
• ✅ Um exemplo executável

O que você não faria é dizer a eles: "Leia essas 400 páginas de Markdown e raciocine sobre qual é a canônica."

Essa segunda opção é exatamente o que estamos fazendo com os agentes de IA hoje.

Quando dizemos "melhorar a documentação", geralmente queremos dizer: escrever uma prosa melhor. Adicionar um parágrafo introdutório mais claro. Mover os avisos para cima. Adicionar outro exemplo de código.

Nada disso ajuda o modelo. O modelo já tinha sua prosa. Ele gerou um cabeçalho que não existia enquanto tinha sua prosa.

O que o modelo está perdendo é a estrutura que o agente pode indexar, versionar e chamar com precisão:

• Uma lista canônica de endpoints, não uma página HTML de endpoints
• Uma lista canônica de nomes de parâmetros e seus tipos — não parágrafos sobre eles
• Uma lista canônica de cabeçalhos, códigos e restrições — não "veja a seção acima"
• Uma maneira para o agente perguntar "qual é a versão mais recente deste endpoint?" em vez de ficar preso em qualquer HTML que ele rastreou há seis minutos

Isso não é um exercício de escrita. É um exercício de infraestrutura.

Markdown Foi Construído para Humanos. Agentes Precisam de Algo Diferente.

A versão honesta do problema: construímos toda a web de documentação para um leitor que é um humano com paciência, uma caixa Ctrl-F e bom julgamento.

Agentes não são nenhuma dessas coisas.

Um agente está mais próximo de um consumidor de API programável do que de um leitor humano. Ele precisa:

Nenhuma dessas são propriedades de um arquivo Markdown. Elas são propriedades de uma interface.

Até pararmos de fingir que a documentação é um bloco plano de prosa e começarmos a tratá-la como uma interface que os agentes chamam, continuaremos recebendo cabeçalhos inventados com confiança, endpoints obsoletos e integrações que parecem corretas no chat e quebram em produção.

Como é uma Camada de Documentação Nativa de IA

A forma da solução já está aparecendo nas pilhas de produção.

É chamada de Protocolo de Contexto do Modelo — MCP para abreviar. É um protocolo pequeno e simples que permite que um agente de IA converse com uma fonte de documentação da maneira que conversaria com qualquer outra ferramenta.

A versão moldada do MCP de "documentos" se parece com isto:

• Ferramentas, não páginas. Em vez de rastrear um site de 600 URLs, o agente chama search_docs, get_endpoint, list_versions, get_example.
• Esquemas, não capturas de tela. Cada ferramenta tem um contrato tipado. O agente sabe o que vem de volta antes de perguntar.
• Versionamento é de primeira classe. v1, v2, etc.