Engenharia de contexto para agentes de IA: guia prático

Engenharia de contexto é o trabalho de decidir o que um agente de código com IA vê a cada turno: quais instruções, arquivos de regras, definições de ferramentas, arquivos lidos, resultados de ferramentas e histórico estão na janela de contexto dele, e quais ficam de fora. Em agentes de código, isso costuma importar mais do que ajustar o prompt, porque o prompt que você digita é uma pequena parte do que o modelo lê. A maior parte da janela é ocupada pelos arquivos de regras, pela saída das ferramentas e pela conversa até ali. Mantenha esse contexto pequeno e relevante e você terá resultados melhores do que com qualquer reescrita do prompt.

Este guia explica o que entra no contexto de um agente, por que contextos longos se degradam, quais técnicas ajudam e como saber se elas funcionam. As informações sobre Claude Code e Codex são de outubro de 2026.

O que é engenharia de contexto

O post de engenharia da Anthropic Effective context engineering for AI agents (29 de setembro de 2025) define contexto como o conjunto de tokens incluídos ao gerar a resposta de um modelo, e engenharia de contexto como selecionar e manter o melhor conjunto desses tokens durante a inferência.

A diferença em relação à engenharia de prompt está no escopo e no tempo:

Um agente de código roda em loop: ler, chamar uma ferramenta, ler o resultado, decidir, chamar de novo. Cada passo adiciona tokens, e cada passo relê o que já está lá. É por isso que o post chama a engenharia de contexto de iterativa: a seleção acontece de novo toda vez que o agente decide o que passar ao modelo.

O que entra no contexto de um agente de código

Antes da sua primeira mensagem, e crescendo ao longo da sessão:

• Prompt de sistema e ferramentas nativas. Definidos pela CLI. Você não os controla, mas paga por eles a cada turno.
• Arquivos de regras. CLAUDE.md no Claude Code, AGENTS.md no Codex e em muitos outros agentes. Carregam no início da sessão.
• Definições de ferramentas e MCP. Cada ferramenta que o agente pode chamar tem nome e descrição. Servidores MCP acrescentam outras. O Claude Code adia as definições completas das ferramentas MCP até que sejam usadas, então só os nomes e as instruções dos servidores carregam de início.
• Conteúdo recuperado. Arquivos que o agente lê, resultados de busca, documentação que ele busca.
• Resultados de ferramentas. Execuções de testes, logs de build, git diff, consultas ao banco, snapshots de páginas.
• Histórico da conversa. Suas mensagens, as respostas do agente e cada tentativa que falhou.

Para ter uma ideia da parte fixa: medimos a primeira requisição do Claude Code em cerca de 34,4 mil tokens numa configuração padrão e cerca de 13,3 mil numa configuração enxuta (veja nosso post sobre uso de tokens). Essa base é reenviada a cada turno. Para os detalhes de /context, /compact e /clear no Claude Code, veja o guia da janela de contexto do Claude Code.

Por que mais contexto não é melhor: context rot

A janela de contexto tem um limite rígido, mas o limite prático chega antes. O post da Anthropic descreve um “orçamento de atenção”: transformers relacionam cada token com todos os outros, então n tokens criam n² relações entre pares, e cada token a mais dilui a atenção. À medida que a janela cresce, a capacidade do modelo de lembrar o que está nela diminui.

Pesquisas independentes mostram o mesmo. O relatório Context Rot da Chroma (14 de julho de 2025) testou 18 modelos e concluiu que o desempenho cai com o tamanho da entrada em todos os seus experimentos, mesmo em tarefas simples. Algumas conclusões que importam para código:

• Um único distrator, um texto que parece relevante mas não é, já reduziu a precisão, e o efeito cresceu com o tamanho da entrada.
• Num benchmark de memória longa, todos os modelos foram muito melhor com um prompt focado de cerca de 300 tokens do que com o prompt completo de cerca de 113 mil tokens.

Para um agente de código, distratores estão por toda parte: a versão antiga de um arquivo lida antes de uma edição, o stack trace de um bug já corrigido, uma abordagem rejeitada. Uma janela de 1M de tokens dá espaço, não imunidade.

Técnicas que funcionam

Estas são as técnicas que o post da Anthropic descreve, traduzidas para o que você faz num agente de código.

1. Arquivos de regras curtos e com escopo

Arquivos de regras são pagos em toda sessão, então cada linha precisa justificar seu lugar. A documentação de memória do Claude Code recomenda manter cada CLAUDE.md com menos de 200 linhas e observa que arquivos mais longos reduzem a adesão. Em vez de um arquivo longo:

• Coloque regras que valem para parte do código em .claude/rules/ com um campo paths. Elas só carregam quando o Claude lê ou edita um arquivo correspondente.
• Use arquivos CLAUDE.md aninhados em subpastas. O Claude Code os carrega sob demanda quando trabalha naquela pasta.
• Saiba que imports com @path organizam o arquivo, mas não reduzem seu custo: os arquivos importados carregam junto com o arquivo que os importa.

---
paths:
  - "src/api/**/*.ts"
---

# Regras da API

- Valide o corpo de toda requisição com o schema compartilhado.
- Retorne erros no formato padrão de erro.

O Codex funciona do mesmo jeito com AGENTS.md: lê um arquivo global em ~/.codex e depois um arquivo por diretório, da raiz do projeto até o diretório de trabalho; os arquivos mais próximos vêm depois e têm precedência. Ele para de adicionar arquivos ao atingir project_doc_max_bytes, 32 KiB por padrão. Nosso guia de CLAUDE.md e AGENTS.md mostra o que colocar neles.

Quanto ao conteúdo, a Anthropic aconselha escrever na “altitude certa”: específico o bastante para guiar o comportamento, geral o bastante para não engessar uma lógica if-else frágil. Alguns exemplos canônicos funcionam melhor do que uma longa lista de casos extremos.

2. Recuperar na hora certa

Em vez de carregar tudo de antemão, mantenha referências leves (caminhos de arquivos, nomes de funções, links) e deixe o agente carregar o conteúdo quando precisar. A Anthropic dá o Claude Code como exemplo: ele usa glob e grep para achar arquivos e head e tail para olhar dados grandes sem carregá-los inteiros. Na prática:

• Aponte o agente para um arquivo ou símbolo em vez de pedir que ele “dê uma olhada”.
• Peça um esboço ou um intervalo de linhas antes de ler um arquivo grande inteiro.
• Mantenha no arquivo de regras um mapa curto do repositório (onde fica a API, onde estão os testes) e deixe o agente buscar o resto.

3. Isolar o trabalho em subagentes

Um subagente roda na própria janela de contexto, limpa. Ele pode gastar dezenas de milhares de tokens explorando e devolver só um resumo condensado; a Anthropic fala em resumos de, em geral, 1.000 a 2.000 tokens. Bons candidatos são explorar a base de código, ler logs longos e revisar o diff num contexto novo.

Subagentes não são de graça. O post da Anthropic sobre seu sistema de pesquisa multiagente (13 de junho de 2025) relata que agentes usam cerca de 4 vezes os tokens de um chat, e sistemas multiagente cerca de 15 vezes. O que você compra é uma thread principal limpa, não uma conta menor.

4. Compactar e limpar resultados antigos de ferramentas

A compactação resume uma conversa perto do limite e continua a partir do resumo. A Anthropic considera limpar resultados antigos de ferramentas uma das formas mais seguras de compactação: o agente raramente precisa da saída bruta de um teste de quarenta turnos atrás. Do lado da API, o anúncio da Anthropic sobre gerenciamento de contexto (29 de setembro de 2025) relatou que a edição de contexto, que limpa chamadas e resultados de ferramentas obsoletos, reduziu o uso de tokens em 84% numa avaliação de busca na web de 100 turnos.

Numa CLI de código, direcione o resumo em vez de deixá-lo acontecer no limite:

/compact Mantenha a lista de arquivos alterados, o teste que falha e a decisão sobre a API

E, ao mudar para um trabalho sem relação, abra uma nova sessão em vez de compactar a antiga.

5. Dar ao agente notas fora da janela

Notas estruturadas significam que o agente escreve o progresso num arquivo e o lê de volta depois. Entre os exemplos da Anthropic estão um arquivo NOTES.md e listas de tarefas. A memória automática do Claude Code funciona assim: um índice MEMORY.md por repositório, do qual as primeiras 200 linhas ou 25 KB carregam no início de cada sessão. Para vários agentes e sessões, uma memória de projeto compartilhada vai além; falamos dela em memória compartilhada para agentes de código com IA.

6. Um mapa do código em vez de busca às cegas

Explorar com grep e leitura enche a janela de arquivos inteiros, e a maioria acaba sendo irrelevante. Um mapa da base de código é um índice de arquivos, símbolos, imports e testes que o agente pode consultar: ele lê primeiro uma lista ranqueada e um esboço, e só depois as linhas de que precisa.

7. Manter curta a saída das ferramentas

Os resultados de ferramentas costumam ser a parte maior e mais ruidosa da janela. O post da Anthropic Writing effective tools for agents (11 de setembro de 2025) recomenda paginação, seleção de intervalos, filtragem e truncamento com padrões sensatos, e diz que o Claude Code limita as respostas de ferramentas a 25.000 tokens por padrão. Você pode aplicar a mesma ideia de fora:

• Rode um arquivo de teste, não a suíte inteira.
• Filtre logs com grep ou tail antes de o agente lê-los.
• Prefira um comando de CLI focado a uma ferramenta que devolve uma página ou tabela inteira.
• Desative servidores MCP que o projeto não usa.

Como medir a engenharia de contexto

Sem medir, você volta a adivinhar. Sinais úteis:

• A divisão. /context no Claude Code mostra o que está usando a janela por categoria e quais arquivos de regras e memória foram carregados. Confira depois de mudar seus arquivos de regras ou a configuração de MCP.
• Tokens por tarefa. Compare tarefas parecidas antes e depois de uma mudança, não sessões isoladas.
• Correções repetidas. Se você vive repetindo uma regra, ela está faltando no arquivo de regras ou está enterrada nele.
• Sucesso na primeira tentativa. Menos prompts de acompanhamento em tarefas comparáveis é o resultado que você realmente quer.
• Sinais de degradação. Reler arquivos, esquecer instruções anteriores, repetir uma abordagem rejeitada. Quando aparecerem, compacte ou recomece.

Mude uma variável por vez. O post multiagente da Anthropic constatou que o uso de tokens sozinho explicava cerca de 80% da variação de desempenho na avaliação BrowseComp, um lembrete de que mais tokens podem parecer resultados melhores; compare custo e qualidade juntos.

Checklist

Onde o AgentVera entra

O AgentVera roda Claude Code, Codex e outros agentes de CLI lado a lado num único app desktop. Ele não substitui os hábitos acima, mas vários recursos os aplicam a cada agente que você roda. Tudo isso está descrito nas páginas de recursos:

• Economia de tokens: perfis de contexto que reduzem a base inicial, tamanho do contexto ao vivo em cada painel, compactação automática ligada por padrão com limite de 150 mil tokens usando o comando de cada CLI, e o RTK, que encurta a saída de testes, build e git antes que ela chegue ao modelo.
• Mapa do projeto: um índice local de símbolos, imports, testes e arquivos que mudam juntos, que os agentes consultam pelas ferramentas MCP agentvera-map, como map_related e map_outline. A aba AI ROI compara conversas que usaram o mapa com as que não usaram, incluindo tokens por tarefa.
• Brain: uma memória de projeto construída a partir de documentação, commits, PRs e conversas de agentes. Os agentes buscam nela com brain_recall e guardam correções com brain_remember; um pacote de contexto opcional de até 2.500 caracteres vai para os novos agentes.
• Ferramentas inteligentes para o Claude Code: recusam a releitura de um arquivo inalterado, entregam primeiro o esboço de um arquivo grande e reduzem execuções da suíte inteira aos testes afetados.

Se você roda um único agente num único terminal, as técnicas deste post funcionam muito bem sozinhas, e /context, /compact e um arquivo de regras bem cuidado resolvem a maior parte. O AgentVera ajuda mais quando você roda vários agentes e quer a mesma disciplina de contexto aplicada a todos. Você pode baixá-lo e testar num projeto.

Resumo

Engenharia de contexto é selecionar o que o agente vê a cada turno e, em agentes de código, ela supera os ajustes de prompt, porque o prompt é uma fatia pequena da janela. Contextos longos são menos confiáveis, então mantenha arquivos de regras curtos e com escopo, recupere na hora certa, passe a exploração para subagentes, compacte com foco, guarde notas fora da janela, use um mapa do código e mantenha curta a saída das ferramentas. Depois meça: a divisão do contexto, os tokens por tarefa e o sucesso na primeira tentativa dizem se uma mudança ajudou.