Agentes de IA leem texto. Se uma documentação só existe como HTML renderizado no browser, depende de javascript, efeitos visuais, tabelas dinamicas e etc, para o agente ela simplesmente não existe. Aqui está o que fizemos para resolver isso — e o que você pode replicar.
A cena
Provavelmente você já viveu isso: pede ao Agente de IA para integrar emissão de NFS-e, o agente inventa um parâmetro que não existe, chama um endpoint depreciado, e gera código que compila limpo mas estoura em produção com um 422 sem mensagem útil.
Dois a três dias de debug perdidos para uma implementação que deveria levar um dia.
Quando percebemos que isso estava acontecendo com desenvolvedores tentando integrar a nossa própria API, decidimos entender o problema de verdade — e mudar alguma coisa. O resultado está em nfe.io/docs. Este post explica as decisões que tomamos.
O problema não é o agente. Nunca foi. Agentes de IA leem documentação da mesma forma que leem qualquer texto: precisam de texto limpo, estruturado, sem depender de JavaScript para existir. Quando a doc só vive no browser, o agente não tem com o que trabalhar — e aí a alucinação começa.
O que acontece quando o agente tenta ler sua doc
LLMs como Claude, GPT-5 e outros modelos que rodam nas principais IDEs de desenvolvimento (Cursor, Windsurf, Claude Code, Github Copilot e etc) integram APIs lendo documentação. Não assistindo tutoriais, não interagindo com playgrounds — lendo texto. O processo é simples: o agente faz um fetch() na URL, recebe o conteúdo, e tenta entender o contrato da API.
O problema começa quando a documentação é uma Single Page Application (SPA). O agente busca a URL e recebe algo assim:
<!– Conteúdo renderizado por JavaScript –>
<div id=”app”></div>
<script src=”/bundle.js”></script>
Para o agente, a documentação está vazia. Ele não executa JavaScript. Não abre o browser. Não espera o React montar a página. Ele vê um div vazio e tenta adivinhar o restante — que é exatamente o momento em que a alucinação começa.
- O agente vê → doc como SPA
HTML vazio. Conteúdo que depende de JS para renderizar. Parâmetros que só existem no browser. Resultado: código inventado.
- O agente vê → doc em Markdown puro
Texto limpo. Tipos reais da spec OpenAPI. Exemplos que rodam. Resultado: código coerente na primeira tentativa.
O que mudamos — e por quê cada decisão importa
Há cerca de 8 meses, alguém no time fez a pergunta certa: “Se um agente tentasse ler nossa doc hoje, o que ele veria?”
A resposta era ruim. Tabs que só funcionam com JavaScript. Iframes de vídeo. Imagens com paths relativos que não resolvem fora do browser. Uma doc perfeita para humanos, inútil para qualquer coisa que não seja o Chrome.
Tomamos cinco decisões a partir daí. Nenhuma delas foi pensada como “estratégia de AI-readiness” — foram decisões de engenharia de documentação decente. O que descobrimos é que as duas coisas são a mesma coisa.
Decisão 1 — Servir cada página em Markdown puro por URL direta
Redesenhamos toda nossa documentação para ela existir em dois formatos. O HTML visual para quem abre no browser, e uma versão em arquivo de texto markdown puro e limpo, acessível por URL direta ao .md. Sem javascript, sem componentes visuais, sem paths relativos de imagem.
Também preparamos nossa infraestrutura para entender quando um agente de IA requisita ler nossa documentação, informando diretamente nos cabeçalhos http que o conteúdo solicitado pode ser entregue em text-markdown.
O resultado: 417 páginas de documentação que qualquer parser — humano ou máquina — entende sem dependência externa.
Decisão 2 — Um clique para copiar tudo
Ter os arquivos .md servidos não adianta se ninguém sabe que eles existem. Adicionamos um botão em 100% das páginas da documentação que faz o fetch do arquivo Markdown e joga no clipboard.
Um clique. O dev cola no prompt. O agente recebe conteúdo limpo.
Por que isso importa
A diferença entre “o dev seleciona texto que vem com estrutura de HTML” e “o dev clica um botão e o agente recebe Markdown limpo” é a diferença entre integração em 20 minutos e integração em 2 dias. Fricção pequena, impacto grande.
Decisão 3 — CLAUDE.md no SDK
A doc resolve metade do problema. A outra metade é o SDK.
Publicamos um arquivo CLAUDE.md de no root do repositório nfe/client-nodejs. Ele explica ao agente o que precisa saber antes de tocar qualquer código: quais pastas existem, qual é a convenção, quais arquivos são gerados automaticamente e nunca devem ser editados, qual método usar para cada cenário.
Quando um desenvolvedor instala o SDK da NFE.io, o agente lê esse arquivo primeiro. Já sabe o que fazer. Já sabe o que não tocar. O dev não precisa explicar a arquitetura toda vez.
# Exemplo do que está no CLAUDE.md
## Arquivos que nunca devem ser editados manualmente
src/generated/ # auto-gerado das specs OpenAPI via npm run generate
## Método recomendado para emissão
# Use createAndWait() — resolve o 202 assíncrono automaticamente
const nota = await nfe.serviceInvoices.createAndWait(empresaId, {
borrower: { federalTaxNumber: 12345678901 },
servicesAmount: 1500.00
});
Decisão 4 — OpenAPI como fonte única de verdade
Temos 14 especificações OpenAPI públicas, uma para cada produto: NFS-e, NF-e, NFC-e, CNPJ, CPF, cálculo de impostos, e outros. Cada recurso do SDK TypeScript é gerado automaticamente dessas especificações.
Isso cria uma garantia que documentação escrita à mão não consegue oferecer: é impossível o SDK divergir do contrato real da API. Se a spec muda, os tipos mudam. Se os tipos mudam, o build verifica.
Para o agente, isso significa que ao ler a spec ele tem o contrato exato — não uma versão aproximada que pode estar desatualizada.
Decisão 5 — Cobertura de municípios em tempo real
A NFE.io cobre mais de 4.000 municípios brasileiros com documentação gerada dinamicamente. Quando uma prefeitura integra NFS-e, a documentação é atualizada automaticamente.
Para o desenvolvedor que precisa emitir nota em qualquer cidade do Brasil, e para o agente que está ajudando ele a fazer isso, a informação está lá. Atualizada. Sem precisar abrir ticket de suporte para perguntar se aquele município já foi integrado.
- 417 páginas em Markdown puro
- 14 specs OpenAPI públicas
- 4k+ municípios documentados
- SDK que o agente de IA entende
O teste — 30 segundos
Não acredite na nossa palavra. Teste agora:
- Abrahttps://nfe.io/docs
- Abra qualquer página de documentação
- Clique em “Copiar Markdown da Página”
- Cole no seu agente preferido
- Peça para integrar
O agente vai ter o contexto certo, sem alucinação. Não porque o agente é melhor, porque a documentação que ele recebeu é a melhor.
Uma coisa que aprendemos
Engenharia de documentação decente e preparação para agentes de IA são a mesma coisa. Ambas exigem conteúdo em formato parseable, tipos que vêm de uma fonte canônica, exemplos que compilam, e contexto explícito. A diferença entre quem faz isso e quem não faz não é uma feature, é disciplina de engenharia.
