Toda vez que um agente de IA erra uma refatoração, a resposta automática é trocar de modelo. GPT para Claude, Claude para Gemini, Gemini para o mais novo lançamento. E, por uns dias, parece que funcionou — até o agente voltar a inventar um método que não existe ou editar o arquivo errado. O problema nunca foi o modelo. É o que você coloca na frente dele.
91% das empresas já adotaram pelo menos uma ferramenta de IA para codificar. Isso é quase unanimidade. E ainda assim, só 28% dos times com seis ou mais ferramentas de IA dizem confiar no próprio fluxo de trabalho. Tem gente usando IA todos os dias e não confiando no resultado. Essa conta não fecha se o problema for "modelo fraco". Fecha se o problema for contexto mal gerenciado.
O mito do modelo melhor
Eu caí nessa armadilha também. Passei meses achando que bastava esperar a próxima versão do modelo favorito para os agentes pararem de alucinar import, de reescrever função que já existia em outro arquivo, de ignorar o padrão de erro que o time usa há dois anos. Modelo novo chegou, ficou melhor em benchmark, e continuou cometendo o mesmo tipo de erro burro em repositório real.
Isso porque benchmark não é o seu código. Modelo de ponta sabe TypeScript genérico muito bem. Ele não sabe o seu TypeScript — como seu time nomeia hooks, onde ficam os tipos compartilhados, por que aquele serviço específico não pode fazer chamada síncrona. Essa lacuna não é de capacidade de raciocínio, é de informação. E informação é problema de contexto, não de modelo.
Contexto é recurso escasso, não depósito
A tentação é jogar o repositório inteiro na janela de contexto e deixar o modelo se virar. Parece generoso, mas é o oposto de ajuda. Janela de contexto grande não é pasta sem fundo — é memória de trabalho. Quanto mais você enche com coisa irrelevante, mais diluída fica a atenção do modelo para o que de fato importa naquela tarefa.
Isso explica um número que assusta: a duplicação de código subiu 4 vezes com a adoção de IA. Agente sem contexto direcionado não encontra a função que já resolve o problema — ele simplesmente escreve uma nova, porque nunca viu a antiga. E sem visibilidade das convenções de segurança do time, não é raro que 48% do código gerado por IA carregue alguma vulnerabilidade. Mais contexto bruto não resolve isso. Contexto certo resolve.
Pensar em contexto como recurso escasso muda a pergunta. Não é "quanto posso colocar aqui", é "o que esse agente precisa saber agora para dar o próximo passo certo". Isso é context engineering: curadoria deliberada, não despejo.
Contexto just-in-time: buscar, não pré-carregar
A prática que mudou meu fluxo foi parar de pré-carregar contexto e passar a buscar sob demanda. Em vez de anexar dez arquivos "pra garantir", deixo o agente fazer uma busca direcionada — grep, leitura de assinatura, navegação por referência — exatamente no momento em que precisa daquele dado específico.
É a diferença entre entregar uma biblioteca inteira para alguém resolver uma dúvida e indicar a página certa. O agente que busca just-in-time gasta menos tokens em ruído, mantém foco na tarefa e, coisa importante, erra menos porque o que está na cabeça dele naquele instante é relevante de verdade. Ferramentas de navegação de código — ir para definição, achar referências, ler só o trecho que importa — valem mais do que qualquer prompt mágico.
Documente convenções, não suposições
Aqui entra a parte que todo time deveria levar mais a sério: arquivos de instrução versionados, tipo CLAUDE.md ou AGENTS.md. Não é documentação de usuário, é um manual direto para o agente: como rodar os testes, qual padrão de nomenclatura o time usa, que biblioteca de data é proibida, onde ficam os tipos de domínio, qual o jeito certo de tratar erro numa API.
O modelo já sabe programar. O que ele não sabe é a sua decisão de arquitetura tomada numa sexta-feira há oito meses, a razão pela qual aquele módulo é tratado como legado, ou que ninguém mais deve criar novo endpoint REST porque o time migrou pra GraphQL. Isso só existe na cabeça do time — até alguém escrever.
Contexto versionado é playbook de time, não config pessoal
Um erro comum é tratar esse arquivo de instrução como ajuste pessoal, cada um com o seu, perdido num dotfile local. Isso é desperdício. Esse contexto deveria estar no repositório, versionado junto com o código, revisado em pull request como qualquer outra mudança de padrão.
Quando o contexto é commitado, ele vira conhecimento coletivo: todo agente que qualquer pessoa do time rodar naquele repositório parte do mesmo chão. Alguém descobre que o agente está confundindo dois serviços parecidos? Atualiza o arquivo, sobe o PR, resolvido para todo mundo — não só para quem bateu de frente com o problema. É o mesmo princípio de documentação de engenharia de sempre, só que agora o leitor principal também é uma IA.
O caso prático: refatoração cross-file
Peguei uma refatoração clássica para testar isso: renomear um campo usado em seis arquivos diferentes, com tipos compartilhados, validação e dois testes dependentes. Sem contexto direcionado, o agente tateava — abria arquivo por arquivo, lia trecho errado, editava e desfazia, facilmente trinta ou quarenta chamadas de ferramenta, muita delas redundantes, uns bons minutos de ida e volta.
Com o AGENTS.md apontando onde ficam os tipos de domínio e com busca just-in-time em vez de leitura cega, o mesmo agente resolveu em menos de dez chamadas de ferramenta, direto ao ponto: localizar referências, editar, confirmar teste. Minutos virou minuto e meio. Não troquei o modelo. Troquei o que ele via.
O que fazer a partir de hoje
Se seu agente está errando, resista ao impulso de trocar de modelo antes de perguntar: ele tem contexto suficiente e relevante, ou está tateando no escuro? Escreva um AGENTS.md de verdade, revise como código, prefira busca direcionada a pré-carregamento. O modelo já é bom. O trabalho que falta é seu: curar o que ele vê.
- Trate a janela de contexto como memória de trabalho escassa, não depósito.
- Prefira buscar informação sob demanda a empacotar o repositório inteiro.
- Escreva as convenções do time num arquivo de instrução versionado no git.
- Revise esse arquivo como qualquer outro artefato de engenharia, não como anotação pessoal.