Diagnosticar se o erro da IA vem do prompt ou do contexto

Quando um assistente de IA erra em produção, a correção depende da camada onde o erro nasceu: o dado que não entrou na conversa, o dado que entrou soterrado, a instrução de sistema que não pedia o comportamento ou a ferramenta mal descrita. Quem responde pelo assistente deve triar hoje 20 erros reais com o prompt do guia.

Reescrever a instrução de sistema é trabalho de horas. Refazer o material que entra na conversa a cada chamada é trabalho de trimestre, com mais de um dono. Quando a equipe aprova a reescrita sem saber a camada, a semana passa e o indicador fica onde estava, porque três das quatro camadas ficam fora do prompt.

O teste que separa as camadas cabe numa tarde e exige a requisição bruta aberta na tela, ou seja, o pacote exato que o modelo recebeu naquela chamada, com instruções, ferramentas, documentos e histórico. Sem esse registro, qualquer discussão de causa vira opinião.

Engenharia de contexto (context engineering) é, na definição da Anthropic de 29/09/2025, o conjunto de estratégias para escolher e manter o melhor conjunto de tokens (pedaços de palavra que o modelo lê e cobra) em cada chamada. A engenharia de prompt fica com a parte menor: escrever bem a instrução. O artigo lista o que disputa a janela de contexto, isto é, tudo o que o modelo lê de uma vez, como a pasta entregue ao conselho antes da reunião.

O termo ganhou força em junho de 2025. Tobi Lütke, presidente da Shopify, escreveu que preferia context engineering a prompt engineering, por descrever melhor a habilidade de dar ao modelo todo o contexto para a tarefa ser plausível de resolver. Andrej Karpathy respondeu chamando a prática de arte e ciência de encher a janela com a informação certa, como registrou Simon Willison em 27/06/2025.

Em 2024, o defeito típico era a instrução mal escrita. Em 2026, com janelas de 1 milhão de tokens e agentes que acumulam resultados de ferramentas, o defeito típico é material demais ou material errado. A Anthropic chama a perda de precisão com a janela cheia de context rot (o contexto que apodrece com o volume), medida pela Chroma em 18 modelos e detalhada no próximo capítulo. Antes de pedir janela maior, corte o que não serve à pergunta.

Como cinco componentes escapam de quem escreve o prompt, a reescrita de prompt corrige só uma parte dos erros. Toda falha em produção cai numa de quatro camadas, e cada uma se confirma com uma leitura da requisição e tem um dono diferente.

O caso que mais engana é o da ferramenta. Um agente de atendimento passa a abrir reembolso quando o cliente só pergunta onde está o pedido, embora o prompt de sistema mande reembolsar apenas diante de pedido explícito de estorno. A descrição da ferramenta promete cuidar de atrasos, e essa frase compete com a instrução em toda chamada. Normalizar o texto do cliente, reescrever o prompt ou trocar de modelo deixa a causa intacta.

A ordem do diagnóstico importa porque cada passo descarta uma camada com uma única leitura, e o ticket sai com dono antes de alguém estimar esforço.

Cada camada tem um conserto conhecido. Para recuperação, a Anthropic recomenda a busca sob demanda (just-in-time retrieval): o agente guarda identificadores leves, como caminhos de arquivo e consultas salvas, e carrega o dado só quando precisa. Para volume, limpe resultados antigos de ferramentas e compacte o histórico; no anúncio de 29/09/2025, a edição de contexto sozinha elevou o desempenho em 29% numa avaliação interna de busca com agente, e em 39% somada à ferramenta de memória. Instrução e descrição de ferramenta se corrigem no texto, com dono e versão.

As quatro camadas valem em qualquer fornecedor. Mudam o tamanho da janela, o preço do contexto longo e o peso que cada documentação dá à ordem do material e à descrição de ferramenta. Janela maior adia o limite sem anular o context rot, que a Chroma mediu em todas as famílias testadas, então use a tabela para saber quanto custa encher a janela e onde cada fornecedor pede cuidado.

Os mesmos quatro sintomas aparecem em setores diferentes. Nos três exemplos ilustrativos abaixo, a primeira proposta da equipe foi reescrever o prompt, e só num deles a camada era a instrução.

A triagem caso a caso cabe num prompt. Ele recebe a frase do defeito e a requisição bruta, devolve camada, evidência literal, dono e medida, e usa só texto e tags XML (marcadores como etiquetas de pasta), o que o deixa portátil entre Claude, GPT, Gemini e Grok.

Traga o contexto da sua empresa

Se a dificuldade é aplicar o conteúdo a uma situação real, envie o caso pelo formulário de contato. Informe a tarefa, os dados disponíveis e a decisão que precisa tomar.

Faça hoje

Peça a quem opera o assistente 20 requisições brutas do erro mais citado nos últimos 30 dias, rode o prompt de triagem em cada uma e consolide com o segundo prompt, em cerca de 40 minutos. Deu certo quando o ticket sai com uma camada dominante, um dono nomeado e uma medida para conferir em 14 dias. Se ninguém consegue exportar a requisição bruta, a primeira correção é passar a registrá-la.