O que é engenharia de contexto? Um guia para programar com IA (2026)

O que é engenharia de contexto?

Engenharia de contexto é a disciplina de projetar, curar e gerenciar todo o conjunto de tokens que um modelo de linguagem vê a cada chamada de inferência, para que ele tenha o suficiente - e apenas o suficiente - da informação de que precisa para concluir a tarefa. Esse conjunto de tokens tem várias camadas: o prompt de sistema, as descrições das ferramentas, os arquivos de código que você entrega a ele, o histórico da conversa, os resultados das ferramentas e a memória de longo prazo (por exemplo, um arquivo CLAUDE.md).

Em termos simples: a engenharia de prompt pergunta "como redijo bem esta instrução?", enquanto a engenharia de contexto pergunta "o que exatamente eu carrego na janela de contexto, em que momento, e o que deixo de fora?". A Anthropic descreve isso como uma progressão natural assim que os agentes rodam muitos loops e acumulam cada vez mais dados (veja Effective context engineering for AI agents, publicado em 2025-09-29).

Para programação com IA, é aqui que está o cerne: mesmo modelo, mesma solicitação, mas se você carregar os arquivos errados, deixar o histórico inchar ou esquecer as convenções do seu projeto, o código gerado sai da especificação. A qualidade da saída de um agente de programação depende mais do contexto do que do modelo. É por isso que quem sabe curar o contexto costuma extrair mais da mesma ferramenta que um colega de equipe já usa.

Engenharia de contexto vs engenharia de prompt

Muita gente usa esses dois termos como sinônimos. A engenharia de prompt não ficou obsoleta - mas agora é uma camada dentro da engenharia de contexto. Um prompt é como você redige uma instrução específica; o contexto é todo o ambiente de informação que cerca essa instrução.

Vale a pena fixar esta frase na parede: um prompt ruim custa uma resposta ruim; uma linha ruim no CLAUDE.md é um imposto sobre CADA solicitação por meses. É exatamente por isso que a engenharia de contexto tem muito mais alavancagem - você corrige um único ponto e milhares de sessões futuras se beneficiam. Se você quer escrever o arquivo de convenções do seu projeto do jeito certo, veja o guia sobre como escrever um CLAUDE.md sólido para o Claude Code.

Por que o contexto importa na programação com IA (janela de contexto e orçamento de tokens)

Todo modelo tem uma janela de contexto - um limite de quantos tokens ele consegue "ver" de uma vez. Os modelos Claude usados atualmente no Claude Code têm uma janela de aproximadamente , equivalente a algumas centenas de páginas de texto. Parece muito, mas no trabalho real ela se esgota mais rápido do que você esperaria.

Dois fenômenos explicam por que uma "janela grande" não significa "boa memória":

• O orçamento de atenção se esgota: cada token que você adiciona dilui a atenção do modelo. Quanto mais você enfia lá, mais difícil fica para o modelo se manter fixo nos detalhes que importam. O contexto é um recurso escasso, não um depósito ilimitado.
• Deterioração do contexto / "perdido no meio": a informação que fica no meio de uma conversa longa é mais fácil de o modelo deixar passar do que a que está no começo ou no fim. É por isso que um agente de programação tantas vezes "esquece" algo que você disse dezenas de turnos atrás, ou responde errado depois de uma sessão longa.

Um número que você mesma pode medir: se a configuração "sempre ativa" (prompt de sistema, definições de ferramentas, memória) já ocupa cerca de 10-20% da janela, o resto é o que sobra para código, histórico e saída das ferramentas. Assim que o uso total passa da maior parte da janela, a qualidade começa a cair - é aí que você precisa comprimir ou reiniciar. Curar o contexto é justamente o trabalho de manter dentro do orçamento aquilo que realmente importa.

Um modelo mental prático: trate a janela de contexto como uma mesa, não como um arquivo. Por mais larga que a mesa seja, ela acaba ficando cheia, e quando você empilha tudo em cima dela, encontrar o único documento de que precisa fica mais lento. O modelo funciona do mesmo jeito - ele não "lê cada token com cuidado e de forma uniforme", ele distribui a atenção. É por isso que uma sessão focada, com apenas os poucos arquivos de que você realmente precisa, costuma gerar código de qualidade mais alta do que uma sessão de "jogue o repositório inteiro e pergunte". Para programação com IA, a disciplina de manter a mesa arrumada importa tanto quanto escolher o modelo certo.

As 4 estratégias de engenharia de contexto (Write, Select, Compress, Isolate)

A comunidade (LangChain, LlamaIndex e muitos outros) convergiu para um arcabouço mental compacto de quatro estratégias. É o conjunto mais fácil de lembrar na hora de aplicar engenharia de contexto ao seu fluxo de trabalho de programação do dia a dia.

Write - descarregar para fora

Em vez de socar tudo no contexto, empurre a informação para fora: escreva planos, notas e decisões em um arquivo (por exemplo NOTES.md, um rascunho, ou uma memória duradoura como CLAUDE.md). O contexto guarda apenas um ponteiro para a informação e a recarrega quando necessário.

Select - trazer só o que você precisa

Trate o contexto como algo escasso: carregue apenas os arquivos ou trechos exatos de que a tarefa atual precisa, em vez de despejar o repositório inteiro. Esse é o espírito da recuperação (RAG), da sintaxe @file e da recuperação just-in-time - buscar o dado no momento em que você precisa dele, em vez de pré-carregá-lo.

Compress - resumir

Resuma o histórico longo da conversa e a saída das ferramentas antes de guardá-los. A Anthropic chama essa técnica de compaction: quando o contexto está prestes a lotar, condense o que você já fez em um resumo curto e continue, em vez de arrastar toda a cauda da conversa.

Isolate - separar

Mova uma tarefa paralela (pesquisa, revisão, consulta) para um subagent separado, com seu próprio contexto limpo. O subagent termina e devolve apenas um resumo enxuto ao agente orquestrador - os detalhes bagunçados nunca poluem o contexto principal. Exemplo: quando você precisa aprender uma biblioteca desconhecida, entregue-a a um subagent para ler a documentação e devolver "as 3 funções a usar e como chamá-las", em vez de puxar a página inteira da documentação para o seu contexto principal.

Essas quatro estratégias não são mutuamente exclusivas - numa sessão real você costuma usar as quatro: escreve o plano no NOTES.md (Write), carrega só o arquivo que está editando (Select), comprime quando o histórico fica longo (Compress) e descarrega a pesquisa para um subagente (Isolate). Depois que você internaliza esse arcabouço, passa a ver cada recurso do Claude Code pela lente de "que estratégia de contexto isto atende?".

Técnicas de engenharia de contexto na prática com o Claude Code

Esta é a parte mais importante: mapear as quatro estratégias acima para as ferramentas que você usa todo dia no Claude Code. A força do Claude Code é que cada recurso remete a uma estratégia de contexto - então, em vez de decorar comandos, aprenda a perguntar "que problema de contexto este comando resolve?".

• CLAUDE.md = memória duradoura (Write). Este arquivo guarda as convenções do projeto, a estrutura do repositório, os "faça" e "não faça". Ele é carregado em toda sessão, então é aqui que mora a maior alavancagem - escreva certo uma vez e colha o benefício em cada solicitação.
• /compact e /clear (Compress + reset). Quando o contexto está quase cheio, o /compact comprime o histórico em um resumo; o /clear limpa tudo para começar do zero quando você parte para uma tarefa completamente nova.
• /context (medição). Este comando mostra um detalhamento dos tokens em uso - você só consegue otimizar o que consome tokens depois que consegue enxergá-lo.
• Subagentes (Isolate). Entregue trabalho de pesquisa/revisão a subagentes para que eles "queimem" o próprio contexto e devolvam só o resultado. Veja o guia de uso de subagentes no Claude Code.
• MCP e @file (Select). Carregue dados just-in-time de fontes externas em vez de pré-carregá-los. Se MCP é novidade para você, leia o que é MCP.
• Modo de plano / um rascunho NOTES.md (Write). Mantenha o plano longo fora do contexto; o agente só o consulta quando precisa.

Um exemplo curto e pragmático de CLAUDE.md - o suficiente para manter o agente dentro da especificação sem queimar tokens demais:

# CLAUDE.md

## Project
Booking API, Node.js + Fastify + PostgreSQL (Prisma).

## Structure
- src/routes - endpoint definitions
- src/services - business logic
- src/db - Prisma schema & migrations

## Conventions (DO)
- Validate input with zod at the route layer
- Every query goes through a service; never call Prisma directly in a route
- Commit with Conventional Commits

## Avoid (DON'T)
- Do not add a new dependency without asking first
- Do not edit a migration file that has already been merged
- Do not log user data to the console

Gerenciando o orçamento de tokens: medir e otimizar

Engenharia de contexto não é uma atividade de intuição - é um ciclo de medir-e-otimizar:

1. Leia o /context para ver onde os tokens estão alocados: sistema, ferramentas, mensagens, arquivos, saída.
2. Identifique os devoradores de tokens: geralmente saída longa de ferramentas (logs, resultados de testes), um arquivo grande carregado inteiro, ou um histórico de conversa inchado.
3. Trate a causa: comprima (/compact) quando o histórico está longo; carregue seletivamente (@file em vez de um diretório inteiro) quando um arquivo é grande; separe um subagente quando uma tarefa paralela faz barulho demais.
4. Saiba quando abrir uma nova sessão: quando você realmente troca de tarefa, um /clear ou uma sessão nova é melhor do que arrastar o contexto antigo por aí.

Um hábito testado na prática: crie a rotina de dar uma olhada no /context no início e no meio de toda sessão longa, especialmente logo depois de um comando que retorna muita saída (build, testes, logs). Muitas vezes o devorador de tokens não é o código que você está editando, e sim uma pilha de logs colada de uma execução anterior. Pegue isso cedo e um único /compact ou uma sessão nova libera de volta a maior parte do orçamento.

Por que vale a pena? Tokens são dinheiro e latência. Quanto mais enxuto o seu contexto, menor o custo por turno e mais rápida a resposta - e, tão importante quanto, a qualidade da resposta melhora porque o modelo não fica distraído. Se você se importa com o lado do custo, veja o artigo sobre custo do Claude Code e otimização de tokens para conectar a contagem de tokens à sua fatura real.

Erros comuns de engenharia de contexto

Sinceramente, a maioria dos erros "bobos" de agente de programação vem de contexto quebrado, não de um modelo fraco. Reconhecer o tipo de falha ajuda você a corrigir rápido, em vez de culpar a ferramenta. Quatro padrões comuns:

• Envenenamento de contexto (context poisoning): uma informação errada (uma suposição falsa, uma decisão antiga que já mudou) fica presa no contexto e continua desviando o agente do caminho. Prevenção: corrija ou dê /clear assim que perceber, não deixe o agente permanecer "confiante sobre uma base ruim".
• Distração de contexto (context distraction): informação irrelevante demais dilui a atenção do modelo. Prevenção: carregue seletivamente, mantenha o contexto mínimo e suficiente.
• Conflito de contexto (context clash): duas instruções conflitantes coexistem (por exemplo, o CLAUDE.md diz para usar a biblioteca A enquanto a conversa pede B). Prevenção: mantenha a fonte das convenções consistente, atualize a memória quando mudar de direção.
• Deterioração de contexto (context rot): a qualidade degrada à medida que a conversa fica longa demais. Prevenção: dê /compact na hora certa, trave os resultados em um arquivo e então renove a sessão.

Ferramentas e kits que apoiam a engenharia de contexto

A maioria das técnicas acima você consegue fazer inteiramente na mão: escrever o CLAUDE.md, digitar /compact, subir um subagente. Você não precisa comprar nada para começar. Além disso, existem pacotes prontos de skills/subagentes que empacotam esses padrões - memória, compaction, isolate - para que você não precise construí-los do zero, por exemplo o pacote AgentKit (20% de desconto pelo link) para o Claude Code (a CLI ak; note que este é um produto diferente do AgentKit da OpenAI). Se você tem curiosidade de como esses kits empacotam padrões de contexto, leia a resenha do AgentKit. E se quiser se aprofundar especificamente em memória e contexto, veja gerenciando contexto e memória no Claude Code.

Perguntas frequentes (FAQ)

Como a engenharia de contexto difere da engenharia de prompt?

A engenharia de prompt ajusta uma instrução específica para um único turno. A engenharia de contexto gerencia todo o conjunto de tokens ao longo de muitos turnos - prompt de sistema, ferramentas, código, histórico, memória. A engenharia de prompt agora é uma camada dentro da engenharia de contexto.

Preciso saber programar para aprender engenharia de contexto?

Não para o conceito, mas muito sim se você quer aplicá-la à programação com IA. As técnicas mais eficazes (escrever o CLAUDE.md, escolher quais arquivos carregar, comprimir o histórico, separar subagentes) estão todas ligadas a um fluxo de trabalho de programação real.

Quantos tokens tem a janela de contexto do Claude Code?

Os modelos Claude no Claude Code têm uma janela de aproximadamente algumas centenas de milhares de tokens (confirme o número exato na documentação oficial do Claude Code antes de contar com ele, já que limites e modelos mudam rápido). Mais importante do que o número é saber medir com /context e manter dentro do orçamento aquilo que importa.

Quando devo usar o /compact?

Quando o histórico da conversa ficou longo e o contexto está quase cheio, mas você ainda quer continuar a mesma tarefa. O /compact comprime a conversa em um resumo para preservar sua linha de trabalho. Se você está mudando para uma tarefa totalmente diferente, use /clear ou abra uma nova sessão em vez de comprimir.

O CLAUDE.md é engenharia de contexto?

Sim, é um exemplo de manual da estratégia Write: você registra as convenções do projeto em um arquivo duradouro para carregá-las em toda sessão, em vez de repetir a instrução a cada vez. Escrever um bom CLAUDE.md é uma das jogadas de contexto de maior alavancagem que existem.

A engenharia de contexto substitui o RAG?

Não - o RAG (recuperação) é ele mesmo parte da estratégia Select dentro da engenharia de contexto. A engenharia de contexto é o arcabouço mais amplo, enquanto o RAG é uma técnica específica para carregar a informação certa no contexto.

Conclusão + próximos passos

A engenharia de contexto é a habilidade fundamental para uma programação com IA eficaz: não se trata de "qual modelo é o mais forte", e sim de "quão bem você cura o contexto". Domine as quatro estratégias - Write, Select, Compress, Isolate - meça com /context e pegue cedo os quatro tipos de falha de contexto: é assim que você transforma um agente de programação de "esquecido" em confiável. Continue lendo com gerenciando contexto e memória no Claude Code para se aprofundar em técnicas de memória, e custo do Claude Code e otimização de tokens para conectar contexto a custo. Se você está apenas começando a trabalhar ao lado da IA, dê uma olhada em o que é vibe coding e como evitar o AI slop.