Proteções para agentes de programação com IA vencem modelos mais inteligentes

Um revisor examinou meu código e encontrou um bug. Uma rota retornava um erro 500 quando deveria ter retornado um 404. Ele relatou o problema com clareza, indicando o arquivo e a linha.

Meu agente corrigiu aquela rota. Exatamente aquela.

Cinco outras rotas tinham o mesmo bug. Elas ficaram lá, intocadas, enquanto o agente informou que o trabalho estava concluído — e ele não estava mentindo. Tinha corrigido aquilo que lhe mostraram. Só nunca pensou em perguntar em quantos outros lugares o mesmo erro estava escondido.

Passei um tempo achando que esse era um problema do modelo e que um modelo melhor o resolveria. Descobri que estava errado, e a solução que funcionou era mais burra do que eu esperava. Proteções para agentes de programação com IA não servem para tornar o modelo mais inteligente. Elas servem para dar a ele um lugar onde registrar as coisas.

Onde agentes de programação com IA erram sem fazer alarde

As falhas que mais me custaram tempo não tinham nada em comum do ponto de vista técnico. Estruturalmente, tinham uma coisa em comum: em todos os casos, algo importante estava sendo mantido na cabeça em vez de ser registrado.

“Ele disse que terminou. Não tinha terminado.”

Você recebe uma mensagem de conclusão. A lista de tarefas está toda marcada. Então você olha e encontra um TODO onde deveria estar a lógica, uma função que retorna uma lista vazia ou uma subtarefa que foi discretamente ignorada.

Esta é a parte que demorei demais para perceber. O agente não está blefando. Ele confere o próprio trabalho com base na lembrança que tem daquilo que acabou de escrever, e essa lembrança é realmente convincente. Testes verdes somados a uma recordação nítida de ter escrito o código dão exatamente a sensação de trabalho concluído.

Registre isso em outro lugar: nada conta como concluído sem evidências que você possa examinar. Não uma afirmação de que passou. A saída real, o arquivo real, a linha real.

“Ele mudou meu teste em vez de corrigir o código.”

Essa dói, porque o agente está fazendo o que você pediu. Você mandou fazer os testes passarem. Há duas maneiras de fazer um teste que falha passar, e uma delas é muito mais fácil.

Registre isso em outro lugar: escreva os critérios antes de o trabalho começar e, depois disso, trate-os como somente leitura. Se o resultado não corresponde a eles, o resultado está errado. Não os critérios. Isso parece óbvio até o momento em que é você quem se sente tentado a mover o alvo um centímetro.

Por que um CLAUDE.md mais longo faz os agentes ignorarem instruções

Meu primeiro instinto foi igual ao de todo mundo. Registrar tudo em CLAUDE.md. Cada falha virava uma regra nova, e o arquivo crescia.

As coisas pioraram. Não de forma drástica — apenas constante, de um jeito difícil de atribuir a qualquer causa. As regras começaram a se contradizer de maneiras que eu não conseguia ver, e o modelo escolhia silenciosamente uma interpretação sem nunca apontar o conflito. E, quando pesquisadores de fato testaram arquivos de contexto de repositório em problemas reais, esses arquivos não melhoraram em nada a taxa de sucesso das tarefas. Eles aumentaram em mais de 20% o custo de inferência. A conclusão foi manter o arquivo de contexto reduzido aos requisitos mínimos.

Esse é o problema inteiro em miniatura. Um arquivo de regras longo equivale a dizer a um sistema esquecido que se esforce mais para lembrar. É mais coisa para manter na cabeça, não menos.

O framework que acabei adotando tem uma regra que pareceu errada quando a li e certa depois que convivi com ela: cada regra nova precisa excluir uma antiga ou se fundir com ela. A quantidade de regras não pode crescer. Quando isso força uma escolha difícil, a escolha difícil é justamente o objetivo — você descobre de quais regras realmente dependia.

Cinco lugares onde registrar as coisas

Esta é a ideia toda. Cada linha mostra algo que falha quando uma cabeça precisa guardá-lo e o lugar onde isso deve ser registrado.

Mantido na cabeça	Registrado em algum lugar
O que “concluído” deveria significar	Critérios escritos antes do trabalho
Se foi realmente verificado	Evidências que você pode examinar
Se o seu próprio trabalho é bom	Um modelo diferente para verificá-lo
O que você decidiu três horas atrás	Um arquivo no disco
Se é seguro realizar esta ação	Uma barreira que para diante de um humano

Três desses pontos precisam de uma breve explicação.

“Ainda acabo revisando tudo sozinho.”

Se você deixou de confiar na saída, agora é o gargalo, e não obteve nenhuma vantagem do agente.

Pedir ao agente que confira o próprio trabalho não ajuda, e vale a pena refletir sobre o motivo: foi o mesmo contexto que produziu o erro, então ele recorre às mesmas razões. Vai defender o trabalho em vez de testá-lo.

Registre isso em outro lugar: encaminhe a revisão a um modelo diferente, de preferência de outro fornecedor. Treinamento diferente, pontos cegos diferentes. O modelo que encontrou meu bug em cinco rotas não foi o que o escreveu, e isso não é coincidência.

“Alguma coisa aprovou a si mesma, e não fui eu.”

Os agentes leem muito texto que não escreveram — discussões de issues, documentação, páginas da web, saídas de ferramentas. Qualquer um deles pode conter a palavra “aprovado”. A injeção de prompt ocupa o primeiro lugar na lista de riscos da OWASP para esses sistemas, e a OWASP afirma sem rodeios que as defesas usuais não a mitigam por completo.

Registre isso em outro lugar: uma aprovação depende de onde veio, não do que diz. Um humano disse sim, ou um artefato assinado no disco diz sim. Todo o resto que apenas contém a palavra “aprovado” é texto.

“A compactação devorou quatro horas de contexto.”

Em uma sessão longa, o contexto se enche e a conversa é resumida. O resumo mantém o que aconteceu e perde o porquê. Uma hora depois, você está discutindo de novo uma decisão que já tinha resolvido e não consegue saber se está sendo cuidadoso ou andando em círculos.

Registre isso em outro lugar: use um arquivo. Decisões, estado atual, o que vem a seguir. A sessão é descartável; o arquivo não. Releia-o antes de afirmar que algo está concluído.

Quanto custam as proteções para agentes de programação com IA

O formato importa mais do que o número, então vamos começar pelo formato: a integração é um custo único. Você paga por ela enquanto conecta as proteções a uma base de código e não paga essa parte duas vezes. A revisão independente é a exceção — ela acontece a cada mudança, então continua custando alguma coisa depois da configuração.

A divisão é a parte interessante. Cerca de 80% dos meus gastos foram para o modelo barato fazer o trabalho em volume, cerca de 17% para o modelo caro fazer planejamento e avaliações, e cerca de 3% para a revisão de segunda opinião — a etapa que as pessoas pulam. A segurança foi, de longe, o item mais barato da conta. Essa divisão permaneceu mais ou menos igual em todos os meus projetos, mesmo com as mudanças de preço.

Quanto ao número: na maioria dos projetos em que trabalhei, adaptar uma base existente custou cerca de US$ 100 a US$ 200 em uso de API, aos preços de agosto de 2026. A proporção importa mais do que os dólares — reserve um orçamento nessa faixa e espere fazer experimentos. Você vai desfazer uma ou duas decisões e executar novamente uma fase, e isso está incluído na estimativa.

Seu número será diferente, e os fatores que o alteram são os óbvios: o tamanho da base de código, quantas vezes você muda de ideia e quanto trabalho delega ao nível barato.

Começar um projeto novo me custou muito menos, e esse é o dado mais útil. O dinheiro não vai para o framework. Vai para a conciliação — decidir, um de cada vez, quais das suas ferramentas e hábitos existentes as proteções substituem e a quais terão de se adaptar. Na minha integração, os comandos de teste do próprio framework não sobreviveram; foram excluídos e substituídos por scripts que o projeto já tinha. Um projeto novo não tem nada para conciliar.

Comece com uma

Você não precisa das cinco. Escolha a falha que está custando mais para você nesta semana e registre essa única coisa em algum lugar.

Se não tiver certeza de qual escolher, comece pela revisão independente — um segundo modelo examinando o trabalho do primeiro. É a mais barata das cinco e detecta a maior variedade de problemas, inclusive aqueles que você nunca pensaria em procurar.

O bug das cinco rotas ainda é meu exemplo favorito, porque nada nele era difícil. O agente precisava de uma instrução que não tinha: antes de corrigir alguma coisa, procure tudo que tenha o mesmo formato. Essa instrução agora vive em um arquivo. Estará lá na próxima sessão e na seguinte, muito depois de todos nós termos esquecido por que ela foi escrita.

O framework completo, com as proteções e as etapas de adoção, está no GitHub.

---

Recursos

• Arquivos de contexto de repositório, testados em problemas reais (ETH Zurich SRI)
• OWASP LLM01: Injeção de prompt
• AGENTS.md, o formato de arquivo de contexto de repositório
• Memória do Claude Code e CLAUDE.md
• O framework agêntico, com as proteções e as etapas de adoção

---