Falhas de IA: como melhorar contexto sem criar ruído

Falhas de inteligência artificial em desenvolvimento não melhoram com uma coleção infinita de novas regras. Para melhorar contexto para IA, a equipe precisa descobrir qual informação faltou, onde ela deveria morar e qual orientação antiga precisa ser removida.

Uma falha vira aprendizado quando reduz ambiguidade para a próxima tarefa. Se ela apenas acrescenta mais uma frase ao prompt, provavelmente está transferindo o problema para a próxima revisão.

Separe falha pontual de contexto permanente

Nem toda falha precisa virar contexto permanente. A distinção importa porque uma correção mal posicionada pode transformar um erro localizado em instrução contraditória para agentes de IA.

Uma falha isolada pode pertencer apenas à tarefa. Um requisito foi mal escrito, um arquivo estava desatualizado, uma pessoa esqueceu de mencionar uma exceção. Corrigir isso no prompt global do agente pode contaminar tarefas futuras com uma regra que só fazia sentido naquele caso.

Já uma falha recorrente revela outra coisa: existe uma informação que a equipe espera que o agente use, mas que não está disponível, não está clara ou está no lugar errado. Aí sim vale tratar como melhoria de contexto.

A Anthropic define engenharia de contexto como a seleção e manutenção das informações disponíveis ao modelo durante a inferência, incluindo instruções, ferramentas, dados externos e histórico, dentro de uma janela limitada Anthropic. Essa definição ajuda a colocar a discussão no lugar certo. Contexto não é sinônimo de prompt longo. É o conjunto de informações que orienta uma execução.

O primeiro critério é perguntar: essa falha se repetiria em tarefas futuras se nada mudasse?

Se a resposta for não, trate como correção pontual. Se a resposta for sim, avance para o diagnóstico. Melhorar contexto para IA não é registrar tudo o que deu errado. É selecionar o que precisa ser reutilizado.

Essa disciplina também protege a revisão humana. A documentação do GitHub sobre agentes do Copilot descreve ambientes e permissões distintos e ressalta supervisão humana e revisão das saídas GitHub. Na prática, quanto mais ambíguo o contexto, mais a revisão tende a gastar tempo reconstruindo intenção em vez de avaliar escopo, risco e qualidade da mudança.

Localize a origem da falha antes de editar a instrução

A reação mais comum depois de uma falha é abrir a instrução do agente e escrever: “sempre faça X” ou “nunca faça Y”. Parece prudente. Muitas vezes é ruído.

Antes de editar qualquer instrução, classifique a origem provável da falha. A pergunta não é “o que o agente errou?”. A pergunta é “qual parte do sistema de contexto deveria ter evitado esse erro?”.

Algumas origens aparecem com frequência:

Falta de objetivo: a tarefa descrevia uma alteração, mas não explicava o resultado esperado.
Falta de restrição: o agente sabia o que mudar, mas não sabia até onde poderia ir.
Falta de padrão técnico: havia uma convenção no time, mas ela não estava documentada em local acessível.
Falta de exemplo: a regra existia, mas era abstrata demais para orientar uma alteração semelhante.
Falta de teste: a expectativa era verificável, mas não havia teste automatizado ou critério de aceite.
Falta de permissão: o agente realizou uma ação que deveria depender de autorização humana.

Cada causa aponta para um destino diferente. Uma falha por falta de objetivo deve melhorar a descrição da tarefa. Uma falha por falta de restrição pode virar regra de escopo. Uma falha por falta de padrão técnico talvez pertença ao README do repositório ou a uma decisão de arquitetura. Uma falha por falta de verificação provavelmente deve ir para teste, integração contínua ou checklist de revisão.

Essa separação evita um vício perigoso: transformar todo problema em instrução operacional. Prompts acumulam exceções rapidamente. Depois de algumas rodadas, ninguém sabe se vale “preservar o padrão atual”, “refatorar quando encontrar duplicação” ou “evitar mudanças fora do arquivo solicitado”. As três frases podem ser razoáveis. Juntas, sem condição, competem entre si.

Escolha o destino certo para a correção

O destino da melhoria importa tanto quanto a redação da regra. Quanto mais estável e verificável for a orientação, menos ela deve depender de um prompt solto.

Uma instrução do agente serve bem para comportamento operacional: como pedir autorização, quando interromper, que formato usar ao explicar riscos, que limites respeitar durante uma execução.

A documentação do repositório serve melhor para padrões duráveis: estrutura de módulos, convenções de nomes, comandos locais, organização de testes, escolhas recorrentes de implementação.

Uma decisão de arquitetura registra escolhas que não devem ser redescobertas a cada tarefa: por que um módulo não acessa diretamente outro, por que determinada dependência foi evitada, que fronteira precisa ser preservada.

Um checklist de revisão ajuda quando a verificação exige julgamento humano. Por exemplo: “confirmar se a mudança alterou comportamento público”, “verificar se a permissão solicitada condiz com a tarefa”, “avaliar se a alteração extrapolou o escopo aprovado”.

Um teste automatizado é o melhor destino quando a expectativa pode ser expressa como comportamento verificável. Se a regra pode falhar de forma objetiva, vale perguntar por que ela ficaria apenas escrita para o agente ler.

A integração contínua também entra nessa discussão. O DORA descreve integração contínua como integração frequente ao código principal, acompanhada de construção e testes automatizados, e afirma que corrigir uma construção quebrada deve ter prioridade sobre novas mudanças DORA. Esse ponto não transforma teste em solução para todo problema de contexto, mas lembra que algumas expectativas precisam sair da conversa e entrar no fluxo de verificação.

Há uma regra prática: se a orientação muda a cada tarefa, coloque na descrição da tarefa. Se vale para um repositório, coloque em documentação do repositório. Se expressa uma restrição de desenho, registre como decisão de arquitetura. Se pode ser verificada automaticamente, transforme em teste. Se depende de julgamento, leve para checklist de revisão. Se orienta o modo de agir do agente, mantenha como instrução operacional.

Esse raciocínio conversa com temas próximos, mas não os substitui. Especificações bem escritas ajudam a reduzir ambiguidade desde o início. A preparação do repositório torna padrões mais acessíveis. A revisão humana organiza a decisão final. Se você está estruturando essa base, vale conectar este artigo ao guia sobre como criar uma estratégia de inteligência artificial conectada ao negócio, porque contexto técnico sem decisão de negócio tende a virar burocracia elegante.

Substitua regras antigas em vez de empilhar exceções

A melhoria de contexto mais negligenciada é a remoção.

Quando uma falha acontece, a equipe procura a regra que faltou. Mas raramente procura a regra que ficou velha, vaga ou contraditória. Esse é o ponto em que o contexto começa a degradar.

Imagine uma instrução existente: “prefira mudanças pequenas e localizadas”. Depois de uma falha, alguém acrescenta: “refatore sempre que encontrar duplicação”. As duas orientações podem conviver, mas só se houver condição. Sem condição, o agente pode justificar tanto uma mudança mínima quanto uma refatoração ampla. A revisão humana fica discutindo interpretação, não qualidade da solução.

A revisão deve responder: a nova regra substitui, limita ou complementa uma regra antiga?

Se substitui, remova a anterior. Se limita, escreva a condição. Se complementa, explique em qual situação cada uma vale.

Uma regra nova que não elimina ambiguidade não é melhoria. É dívida de contexto.

Essa dívida aumenta o tempo gasto para entender por que uma instrução existe. O problema não é ter documentação. O problema é ter documentação que exige arqueologia antes de qualquer mudança.

Para evitar isso, cada atualização de contexto deveria carregar cinco informações mínimas:

qual falha ela corrige;
onde foi aplicada;
qual regra anterior remove, substitui ou limita;
como será verificada;
quando deve ser revista.

Não precisa virar um ritual pesado. Pode ser um comentário em uma pull request, uma entrada curta em um arquivo de instruções, uma atualização no registro de decisões ou um item em checklist. O importante é criar rastreabilidade suficiente para que a próxima pessoa entenda por que aquela orientação existe.

Uma falha de escopo que não deve virar regra geral

Considere um exemplo fictício. Uma equipe pede a um agente que corrija um bug simples na tela de cadastro de projetos. A expectativa era ajustar uma validação. O agente altera a validação, modifica um componente compartilhado e toca em um módulo de permissões. A mudança passa parcialmente nos testes, mas a revisão humana identifica que o escopo ficou maior do que a tarefa justificava.

A resposta ruim seria acrescentar ao prompt: “não mexa em muitos arquivos”.

Essa regra parece clara, mas não é. Muitos arquivos são quantos? Um arquivo central pode ser mais arriscado do que cinco arquivos de teste. Uma correção legítima pode exigir atravessar mais de um módulo. A regra cria uma sensação de controle sem critério operacional.

Uma resposta melhor seria transformar a falha em limite verificável de escopo:

Para correções classificadas como simples, alterar apenas os arquivos diretamente ligados ao defeito descrito.
Se a correção exigir mudança em mais de um módulo funcional, interromper a execução.
Ao interromper, explicar a dependência encontrada, listar os módulos afetados e pedir nova autorização.
Não modificar permissões, autenticação ou contratos de API sem menção explícita na tarefa.

Esse contexto reduz ambiguidade porque define uma condição de parada. Ele também dá à revisão humana um ponto claro de autorização antes da expansão da mudança.

Mas ainda falta escolher o destino. Parte dessa orientação pode morar na instrução operacional do agente, especialmente a regra de interromper e pedir autorização. Outra parte pode entrar no checklist de revisão: “a alteração cruzou módulos funcionais sem autorização?”. Se permissões e contratos de API são áreas sensíveis naquele produto, essa restrição talvez também pertença à documentação do repositório.

O efeito esperado não deve ser tratado como resultado garantido. A hipótese a medir é que a regra de parada tornará mais visível quando uma tarefa simples deixou de ser simples. Se isso acontecer, a equipe poderá decidir melhor quando dividir a mudança, quando envolver uma pessoa responsável por arquitetura ou quando recusar automação naquele trecho.

Teste a melhoria em lote pequeno antes de consolidar

Depois de ajustar o contexto, existe outra tentação: aplicar a nova regra a todos os agentes, repositórios e fluxos. É compreensível. Se a regra parece boa, por que não padronizar?

Porque mudanças amplas de contexto também podem falhar de forma ampla.

O DORA recomenda unidades de trabalho pequenas, independentes e testáveis para obter retorno sobre mudanças e revisar hipóteses mais cedo. A orientação também alerta para a dificuldade de revisar e integrar grandes mudanças geradas com IA DORA. Aplicado ao contexto, isso sugere uma postura prudente: teste a melhoria em uma unidade pequena antes de espalhar.

Esse teste não precisa ser sofisticado. Escolha uma tarefa parecida com a falha original, aplique a nova orientação e observe se ela ajuda a tomar decisão mais cedo. A pergunta não é apenas se o agente “acertou”. A pergunta é se a nova regra reduziu interpretação humana desnecessária.

Critérios úteis para essa avaliação:

A regra ajudou o agente a interromper quando deveria?
A revisão humana ficou mais objetiva?
A regra conflitou com alguma instrução existente?
A orientação gerou cautela excessiva em tarefas simples?
O destino escolhido foi adequado ou a regra deveria virar teste, documentação ou checklist?

Se a melhoria só funciona quando alguém explica novamente o contexto a cada tarefa, ela ainda não está pronta. Se ela evita uma classe de ambiguidade sem bloquear alterações legítimas, pode ser consolidada.

Esse cuidado fica mais importante quando agentes passam a atuar em repositórios, revisões e automações do fluxo de desenvolvimento. Um roadmap de IA só ganha qualidade quando separa adoção de capacidade operacional. Da mesma forma, uma instrução de agente só ganha maturidade quando deixa claro o que deve decidir, o que deve verificar e o que deve escalar para uma pessoa.

Critérios para atualizar contexto sem acumular contradições

Use este checklist quando uma falha aparecer na revisão, no teste ou na integração. Ele não substitui julgamento técnico. Ele organiza a conversa para que a equipe não transforme toda exceção em prompt permanente.

A falha se repetiria em tarefas futuras? Se não, trate como correção pontual. Se sim, considere atualizar contexto.
A causa foi falta de informação, falta de limite ou falta de verificação? Falta de informação tende a ir para documentação ou exemplo. Falta de limite tende a ir para instrução de escopo. Falta de verificação tende a ir para teste, revisão ou integração contínua.
A nova regra contradiz alguma instrução existente? Se contradiz, substitua a regra anterior ou registre a exceção com condição clara.
A regra é estável o bastante para virar contexto permanente? Se depende apenas de uma tarefa, coloque na descrição da tarefa. Se vale para o repositório ou para a equipe, mova para um artefato mais durável.
Existe uma forma objetiva de verificar a melhoria? Prefira teste automatizado, checklist de revisão ou critério de aceite. Se a regra não pode ser verificada, ela provavelmente precisa ser reescrita.
A melhoria reduz o trabalho humano de interpretação? Se exige que a pessoa explique a exceção toda vez, o contexto ainda não melhorou. Ele apenas mudou de lugar.

O checklist é mais útil quando usado perto da falha, antes que a equipe esqueça o raciocínio. Depois de alguns dias, a tendência é lembrar apenas do erro visível, não da condição que o produziu.

Também vale conectar esse exercício a uma avaliação mais ampla de maturidade. Nem toda organização precisa do mesmo grau de automação, nem todo repositório está pronto para agentes atuarem com o mesmo nível de autonomia. O artigo sobre maturidade em IA ajuda a olhar para capacidades, limites e governança antes de escalar práticas.

Feche a falha com uma decisão rastreável

Uma falha bem fechada não termina com “prompt atualizado”. Termina com uma decisão que alguém consegue revisar depois.

A decisão deve dizer se a correção entrou em uma instrução operacional, regra de escopo, decisão de arquitetura, teste automatizado, exemplo de referência, checklist de revisão ou descrição da tarefa. Também deve dizer qual orientação perdeu validade.

Esse ponto muda a qualidade da aprendizagem. Em vez de criar um arquivo cada vez maior de conselhos ao agente, a equipe passa a manter um sistema de contexto. Algumas informações entram. Outras saem. Algumas viram teste. Outras ficam como restrição humana. Algumas não viram nada permanente porque pertenciam apenas àquela tarefa.

Na próxima falha, não escreva uma nova regra antes de escolher o destino da correção. Classifique a causa, remova a ambiguidade anterior, teste em um recorte pequeno e registre como a melhoria será verificada.

Se quiser discutir essa decisão no contexto da sua empresa, converse com a dooop.

Leituras para continuar

Fontes

Para continuar esta leitura

Como planejar uma refatoração assistida por IA

PRÓXIMA DECISÃO

Conversar sobre a aplicação na empresa

Conversa sobre o contexto da empresa de software

Conteúdo de dooop. O cadastro permite relacionar esta pauta à jornada do leitor e acompanhar o interesse pelo tema.