Context Engineering: Como Gerenciar Contexto em LLMs e Agentes de IA

Ao final deste guia você será capaz de diagnosticar problemas de contexto em agentes reais, aplicar técnicas de curadoria e medir qualidade de saída de forma sistemática. No meu sistema, context engineering é o pilar de medir/revisar que permite agentes autônomos confiáveis — autonomia real via fundamentos profundos + método.

Quando isso é para você: praticantes intermediários/avançados que constroem agentes multi-passo e veem degradação em contextos longos, loops ou workflows complexos.

Prompt engineering está morto. Longa vida ao context engineering.

Depois de alguns anos onde o prompt engineering dominou a atenção em IA aplicada, um novo termo ganhou proeminência: context engineering. Construir com modelos de linguagem deixou de ser sobre encontrar as palavras certas para seus prompts e passou a ser sobre responder uma pergunta mais ampla: qual configuração de contexto tem maior probabilidade de gerar o comportamento desejado do modelo?

Este guia cobre:

• O que é context engineering e por que é mais importante que prompt engineering
• A anatomia do contexto efetivo: system prompts, ferramentas, exemplos, histórico
• Context rot: por que LLMs perdem foco em contextos longos
• Técnicas de compactação (compaction) e memória estruturada
• Skills: contexto dinâmico e reutilizável para controle de tokens
• Arquiteturas multi-agente para tarefas de longo horizonte
• Casos reais: BAML, Claude Code, TIM

Context Engineering vs Prompt Engineering

Na Anthropic, o context engineering é visto como a evolução natural do prompt engineering. Prompt engineering refere-se aos métodos para escrever e organizar instruções de LLM para resultados ótimos. Context engineering refere-se ao conjunto de estratégias para curar e manter o conjunto ótimo de tokens (informação) durante a inferência do LLM, incluindo toda a outra informação que pode chegar lá fora dos prompts.

Nos primeiros dias de engenharia com LLMs, o prompting era o maior componente do trabalho de engenharia de IA, pois a maioria dos casos de uso fora de interações de chat cotidianas exigia prompts otimizados para tarefas de classificação ou geração de texto em one-shot. À medida que avançamos para agentes mais capazes que operam em múltiplos turnos de inferência e horizontes de tempo mais longos, precisamos de estratégias para gerenciar o estado de contexto inteiro: instruções de sistema, ferramentas, MCP, dados externos, histórico de mensagens, etc.

Um agente rodando em loop gera mais e mais dados que poderiam ser relevantes para o próximo turno de inferência, e essa informação deve ser refinada ciclicamente. Context engineering é a arte e a ciência de curar o que entrará na janela de contexto limitada a partir desse universo constantemente evoluindo de informação possível.

Insight chave: Em contraste com a tarefa discreta de escrever um prompt, o context engineering é iterativo e a fase de curadoria acontece cada vez que decidimos o que passar para o modelo.

A Anatomia do Contexto Efetivo

Dado que os LLMs são limitados por um orçamento de atenção finito, um bom context engineering significa encontrar o menor conjunto possível de tokens de alto sinal que maximizam a probabilidade de algum resultado desejado.

System Prompts

Os system prompts devem ser extremamente claros e usar linguagem simples e direta que apresente ideias na altitude certa para o agente. A altitude certa é a zona "Goldilocks" entre dois modos de falha comuns:

• Extremo 1: Engenheiros codificam lógica complexa e frágil nos prompts para elicitar comportamento exato do agente. Isso cria fragilidade e aumenta a complexidade de manutenção.
• Extremo 2: Engenheiros fornecem orientação vaga de alto nível que falha em dar sinais concretos para saídas desejadas ou assume falsamente contexto compartilhado.

A altitude ótima equilibra: específico o suficiente para guiar o comportamento efetivamente, mas flexível o suficiente para fornecer ao modelo heurísticas fortes.

Recomenda-se organizar prompts em seções distintas (como <background_information>, <instructions>, ## Tool guidance, ## Output description, etc.) e usar técnicas como tags XML ou headers Markdown para delinear essas seções.

Ferramentas (Tools)

Ferramentas permitem que agentes operem com seu ambiente e puxem novo contexto adicional à medida que trabalham. Como as ferramentas definem o contrato entre agentes e seu espaço de informação/ação, é extremamente importante que promovam eficiência, tanto retornando informação que seja eficiente em tokens quanto encorajando comportamentos eficientes do agente.

Um dos modos de falha mais comuns que vemos são conjuntos de ferramentas inchados que cobrem funcionalidade demais ou levam a pontos de decisão ambíguos sobre qual ferramenta usar. Se um engenheiro humano não pode dizer definitivamente qual ferramenta deve ser usada em uma dada situação, não se pode esperar que um agente de IA faça melhor.

Exemplos (Few-shot)

Fornecer exemplos, também conhecido como few-shot prompting, continua sendo uma prática recomendada fortemente aconselhada. No entanto, equipes frequentemente tentam enfiar uma lista de casos de borda em um prompt na tentativa de articular cada regra possível que o LLM deve seguir. Não recomendamos isso. Em vez disso, recomendamos trabalhar para curar um conjunto de exemplos diversos e canônicos que retratem efetivamente o comportamento esperado do agente. Para um LLM, exemplos são as "imagens" que valem mil palavras.

Context Rot: O Problema da Janela de Contexto

Apesar de sua velocidade e capacidade de gerenciar volumes cada vez maiores de dados, observamos que LLMs, como humanos, perdem foco ou experimentam confusão em certo ponto. Estudos de benchmarking estilo needle-in-a-haystack descobriram o conceito de context rot: à medida que o número de tokens na janela de contexto aumenta, a capacidade do modelo de recordar informação daquele contexto diminui.

Embora alguns modelos exibam degradação mais suave que outros, essa característica emerge em todos os modelos. Contexto, portanto, deve ser tratado como um recurso finito com retornos marginais decrescentes. Como humanos, que têm capacidade limitada de memória de trabalho, LLMs têm um "orçamento de atenção" que utilizam ao analisar grandes volumes de contexto. Cada novo token introduzido depleta esse orçamento em alguma quantia.

Por que isso acontece?

A escassez de atenção decorre de restrições arquiteturais dos LLMs. LLMs são baseados na arquitetura transformer, que permite que cada token atenda a cada outro token através de todo o contexto. Isso resulta em relações par-a-par de ordem n² para n tokens.

À medida que o comprimento de contexto aumenta, a capacidade de um modelo de capturar essas relações par-a-par se estica fina, criando uma tensão natural entre tamanho de contexto e foco de atenção. Além disso, modelos desenvolvem seus padrões de atenção a partir de distribuições de dados de treinamento onde sequências mais curtas são tipicamente mais comuns que sequências mais longas. Isso significa que modelos têm menos experiência com, e menos parâmetros especializados para, dependências de largura de contexto.

Técnicas como interpolação de codificação de posição permitem que modelos lidem com sequências mais longas adaptando-as ao contexto menor originalmente treinado, embora com alguma degradação no entendimento de posição de tokens. Esses fatores criam um gradiente de performance em vez de um penhasco abrupto: modelos permanecem altamente capazes em contextos mais longos, mas podem mostrar precisão reduzida para recuperação de informação e raciocínio de longo alcance comparado ao seu desempenho em contextos mais curtos.

Técnicas de Compactação

Tarefas de longo horizonte exigem que agentes mantenham coerência, contexto e comportamento orientado a objetivos sobre sequências de ações onde a contagem de tokens excede a janela de contexto do LLM. Para tarefas que se estendem por dezenas de minutos a múltiplas horas de trabalho contínuo, como migrações grandes de codebase ou projetos de pesquisa abrangentes, agentes requerem técnicas especializadas.

Esperar por janelas de contexto maiores pode parecer uma tática óbvia. Mas é provável que, para o futuro previsível, janelas de contexto de todos os tamanhos estarão sujeitas a preocupações de poluição de contexto e relevância de informação. Para habilitar agentes a trabalhar efetivamente em horizontes de tempo estendidos, desenvolvemos algumas técnicas que abordam essas restrições diretamente: compaction, structured note-taking e multi-agent architectures.

Compaction

Compaction é a prática de pegar uma conversa se aproximando do limite da janela de contexto, resumir seus conteúdos, e reiniciar uma nova janela de contexto com o resumo. Compaction tipicamente serve como a primeira alavanca no context engineering para melhorar coerência de longo prazo. Em seu núcleo, compaction destila o conteúdo de uma janela de contexto de maneira de alta fidelidade, permitindo que o agente continue com degradação mínima de performance.

No Claude Code, por exemplo, implementamos isso passando o histórico de mensagens para o modelo para resumir e comprimir os detalhes mais críticos. O modelo preserva decisões arquiteturais, bugs não resolvidos, e detalhes de implementação enquanto descarta outputs de ferramentas redundantes ou mensagens. O agente pode então continuar com esse contexto comprimido mais os cinco arquivos mais recentemente acessados.

A arte do compaction reside na seleção do que manter versus o que descartar, pois compaction excessivamente agressivo pode resultar na perda de contexto sutil mas crítico cuja importância só se torna aparente mais tarde.

Um exemplo de conteúdo superfluo de baixo custo é limpar chamadas e resultados de ferramentas — uma vez que uma ferramenta foi chamada profundamente no histórico de mensagens, por que o agente precisaria ver o resultado bruto novamente?

Memória Estruturada e Note-taking

Structured note-taking, ou memória agentica, é uma técnica onde o agente regularmente escreve notas persistidas em memória fora da janela de contexto. Essas notas são puxadas de volta para a janela de contexto em momentos posteriores.

Essa estratégia fornece memória persistente com overhead mínimo. Como o Claude Code criando uma lista de tarefas, ou seu agente customizado mantendo um arquivo NOTES.md (ou similar) no projeto, esse padrão simples permite que o agente rastreie progresso através de tarefas complexas, mantendo contexto crítico e dependências que de outra forma seriam perdidas através de dezenas de chamadas de ferramentas.

O exemplo do Claude jogando Pokémon demonstra como a memória transforma capacidades de agentes em domínios não-codificação. O agente mantém contagens precisas através de milhares de passos de jogo — rastreando objetivos como "nos últimos 1.234 passos eu estava treinando meu Pokémon na Rota 1, Pikachu ganhou 8 níveis em direção ao alvo de 10." Sem nenhum prompting sobre estrutura de memória, ele desenvolve mapas de regiões exploradas, lembra quais conquistas-chave desbloqueou, e mantém notas estratégicas de estratégias de combate que o ajudam a aprender quais ataques funcionam melhor contra diferentes oponentes.

Após resets de contexto, o agente lê suas próprias notas e continua sequências de treinamento de múltiplas horas ou explorações de dungeons. Essa coerência através de passos de sumarização habilita estratégias de longo horizonte que seriam impossíveis mantendo toda a informação na janela de contexto do LLM sozinha.

Skills: Contexto Dinâmico e Reutilizável

Skills representam uma camada adicional de context engineering que vai além da memória estruturada: em vez de notas ad-hoc escritas pelo agente durante uma sessão, skills são contextos curados, versionados e injetados dinamicamente com base na tarefa em execução. Elas funcionam como módulos de conhecimento especializado que o sistema carrega sob demanda, evitando inflar a janela de contexto com informação irrelevante.

Como Skills Funcionam

Uma skill é tipicamente um arquivo Markdown (ou conjunto de arquivos) contendo conhecimento procedural — workflows, convenções de projeto, APIs internas, padrões de código, ou heurísticas de domínio. O sistema de agente decide qual skill carregar com base em sinais da conversa: palavras-chave na mensagem do usuário, ferramentas recentemente invocadas, ou estado atual da tarefa.

Vantagens sobre Contexto Estático

A principal vantagem das skills é a seletividade: em vez de carregar um system prompt monolítico de 5.000 tokens que cobre todos os domínios possíveis, o agente carrega apenas as skills relevantes para a tarefa atual — frequentemente reduzindo o contexto em 60-80%.

Outra vantagem crítica é a manutenibilidade. Quando uma API muda ou um workflow é atualizado, a correção acontece em um único arquivo de skill, não espalhada por dezenas de prompts. Isso transforma o contexto de um artefato estático e frágil em um sistema modular e versionável.

Skills no Ecossistema Real

O conceito de skills como contexto dinâmico é implementado em diversos sistemas modernos:

• Claude Code usa arquivos CLAUDE.md como skills de projeto — documentação de convenções, arquitetura e workflows que são carregados quando o agente detecta que está trabalhando naquele codebase específico.
• Hermes Agent (e outros frameworks de agente) permitem definir skills como arquivos Markdown que são injetados no contexto com base em triggers configuráveis — por exemplo, carregar a skill de "AWS Deployment" quando o usuário menciona EC2, Lambda ou S3.
• OpenAI's GPTs e Anthropic's Projects operam com um princípio similar: contexto adicional (instructions, files, capabilities) é anexado dinamicamente a conversas específicas, em vez de ser hardcoded no modelo base.

Skills vs Outras Técnicas

Skills não substituem compaction, note-taking ou multi-agente — elas complementam:

Skills são particularmente eficazes quando combinadas com um skill router inteligente — um componente que analisa a intenção do usuário e seleciona as skills mais relevantes, minimizando o overhead de tokens enquanto maximiza a qualidade do contexto.

Arquiteturas Multi-Agente

Sub-agent architectures fornecem outra maneira de contornar limitações de contexto. Em vez de um agente tentando manter estado através de um projeto inteiro, agentes sub-especializados podem lidar com tarefas focadas com janelas de contexto limpas. O agente principal coordena com um plano de alto nível enquanto subagentes performam trabalho técnico profundo ou usam ferramentas para encontrar informação relevante. Cada subagente pode explorar extensivamente, usando dezenas de milhares de tokens ou mais, mas retorna apenas um resumo condensado e destilado de seu trabalho (tipicamente 1.000-2.000 tokens).

Essa abordagem alcança uma clara separação de concerns — o contexto detalhado de busca permanece isolado dentro de sub-agentes, enquanto o agente líder foca em sintetizar e analisar os resultados. Esse padrão, discutido em "How we built our multi-agent research system", mostrou melhoria substancial sobre sistemas de agente único em tarefas de pesquisa complexas.

A escolha entre essas abordagens depende das características da tarefa:

Context Retrieval e Busca Agentica

Hoje, muitas aplicações AI-native empregam alguma forma de recuperação baseada em embeddings em tempo de pré-inferência para trazer contexto importante para o agente raciocinar sobre. À medida que o campo transita para abordagens mais agenticas, vemos cada vez mais equipes aumentando esses sistemas de recuperação com estratégias de contexto "just in time".

Em vez de pré-processar todos os dados relevantes upfront, agentes construídos com a abordagem "just in time" mantêm identificadores leves (caminhos de arquivo, queries armazenadas, links web, etc.) e usam essas referências para carregar dados dinamicamente em contexto em runtime usando ferramentas. A solução de codificação agentica da Anthropic, Claude Code, usa essa abordagem para performar análise complexa de dados sobre grandes bancos de dados. O modelo pode escrever queries direcionadas, armazenar resultados, e alavancar comandos Bash como head e tail para analisar grandes volumes de dados sem nunca carregar os objetos de dados completos em contexto.

Essa abordagem espelha a cognição humana: geralmente não memorizamos corpus inteiros de informação, mas introduzimos sistemas de organização e indexação externos como sistemas de arquivos, inboxes, e bookmarks para recuperar informação relevante sob demanda.

Deixar agentes navegarem e recuperarem dados autonomamente também habilita progressive disclosure — em outras palavras, permite que agentes descubram contexto relevante incrementalmente através de exploração. Cada interação produz contexto que informa a próxima decisão: tamanhos de arquivo sugerem complexidade; convenções de nomenclatura dão pistas sobre propósito; timestamps podem ser um proxy para relevância. Agentes podem montar entendimento camada por camada, mantendo apenas o necessário em memória de trabalho e alavancando estratégias de note-taking para persistência adicional.

Casos Reais

BAML: 300k LOC em Rust

Um dos exemplos mais impressionantes de context engineering em ação vem do time da HumanLayer. Dex, um desenvolvedor amador em Rust, decidiu testar suas técnicas no BAML — um codebase de 300k LOC em Rust para uma linguagem de programação que trabalha com LLMs. Ele nunca havia tocado no codebase BAML antes.

Dentro de aproximadamente uma hora, ele tinha um PR consertando um bug que foi aprovado pelo mantenedor na manhã seguinte. Semanas depois, ele e um colega emparelharam para entregar 35k LOC ao BAML, adicionando suporte a cancelamento e compilação WASM — features que o time estimou levariam 3-5 dias cada para um engenheiro sênior. Eles tiveram ambos os PRs prontos em cerca de 7 horas.

O workflow por trás disso é o que eles chamam de "frequent intentional compaction" — essencialmente desenhar todo o processo de desenvolvimento em torno do gerenciamento de contexto, mantendo utilização na faixa de 40-60%, e construindo revisão humana de alto impacto nos pontos certos.

Claude Code: Hybrid Retrieval

Claude Code é um agente que emprega o modelo híbrido: arquivos CLAUDE.md são ingenuamente dropados em contexto upfront, enquanto primitivas como glob e grep permitem que ele navegue seu ambiente e recupere arquivos just-in-time, efetivamente contornando os problemas de indexação stale e árvores de sintaxe complexas.

A estratégia híbrida pode ser melhor adequada para contextos com conteúdo menos dinâmico, como trabalho legal ou financeiro. À medida que as capacidades de modelo melhoram, o design agentico tenderá a deixar modelos inteligentes agirem inteligentemente, com progressivamente menos curadoria humana.

TIM: Beyond Context Limits

Um desenvolvimento de pesquisa de ponta vem do paper "Beyond Context Limits: Subconscious Threads for Long-Horizon Reasoning" (arXiv:2507.16784). Os autores propõem o Thread Inference Model (TIM), uma família de LLMs treinados para resolução de problemas recursiva e decomposicional, e TIMRUN, um runtime de inferência habilitando raciocínio estruturado de longo horizonte além dos limites de contexto.

Juntos, TIM hospedado em TIMRUN suporta memória de trabalho virtualmente ilimitada e chamadas de ferramenta multi-hop dentro de uma única inferência de modelo de linguagem, superando limites de output, restrições de embedding posicional, e gargalos de memória GPU. A performance é alcançada modelando linguagem natural como árvores de raciocínio medidas tanto por comprimento quanto por profundidade em vez de sequências lineares.

Durante a geração, eles mantêm uma memória de trabalho que retém apenas os estados key-value dos tokens de contexto mais relevantes, selecionados por um mecanismo de pruning de subtask baseado em regras, permitindo reuso de embeddings posicionais e páginas de memória GPU ao longo do raciocínio. Resultados experimentais mostram que o sistema sustenta alta taxa de transferência de inferência, mesmo quando manipulando até 90% do KV cache em memória GPU.

Framework Prático: Checklist de Context Engineering

Aqui está um checklist aplicável para qualquer projeto com LLMs:

1. Mensure sua janela de contexto

• Quantos tokens seu sistema prompt consome?
• Quantos tokens o histórico de mensagens típico consome?
• Qual é a utilização média em produção?

2. Otimize o system prompt

• Remova instruções redundantes
• Use linguagem direta e simples
• Organize em seções com headers claros
• Teste com o mínimo possível e adicione apenas o necessário

3. Curate suas ferramentas

• Cada ferramenta deve ter propósito único e claro
• Retornos devem ser eficientes em tokens
• Documente o contrato de cada ferramenta

4. Implemente compaction

• Defina triggers baseados em utilização de contexto (ex: 70%)
• Preserve decisões arquiteturais e estado crítico
• Descarte outputs de ferramentas antigas

5. Adicione memória estruturada

• Crie padrões de note-taking para seu domínio
• Persista notas fora da janela de contexto
• Leia notas em momentos estratégicos

6. Considere multi-agente

• Identifique sub-tarefas independentes
• Defina contratos claros entre agentes
• Mantenha resumos concisos (1.000-2.000 tokens)

7. Monitore context rot

• Teste needle-in-a-haystack regularmente
• Meça precisão de recall em contextos longos
• Ajuste técnicas baseado em dados reais

Conclusão

Ao final deste guia (parte 5 da Trilha) você diagnostica, cura e mede contexto — habilidade avançada para agentes que realmente crescem com você no meu sistema.

Context engineering representa uma mudança fundamental em como construímos com LLMs. À medida que modelos se tornam mais capazes, o desafio não é apenas criar o prompt perfeito — é curar cuidadosamente que informação entra no orçamento de atenção limitado do modelo em cada passo.

Seja implementando compaction para tarefas de longo horizonte, desenhando ferramentas eficientes em tokens, ou habilitando agentes a explorarem seu ambiente just-in-time, o princípio orientador permanece o mesmo: encontre o menor conjunto de tokens de alto sinal que maximize a probabilidade do seu resultado desejado.

As técnicas que delineamos continuarão evoluindo à medida que modelos melhoram. Já estamos vendo que modelos mais inteligentes requerem menos engenharia prescritiva, permitindo que agentes operem com mais autonomia. Mas mesmo à medida que capacidades escalam, tratar contexto como um recurso precioso e finito permanecerá central para construir agentes confiáveis e efetivos.

Construa ou refine seu sistema:

• Hermes Agent (meu centro de comando) — referência viva para loops com contexto
• Falar comigo para revisão de contexto no seu agente atual

Publicado em andrecosta.ia.br.

Referências:

• Advanced Context Engineering for Coding Agents — HumanLayer
• Effective Context Engineering for AI Agents — Anthropic
• Context Engineering — LLM Memory and Retrieval for AI Agents — Weaviate
• Beyond Context Limits: Subconscious Threads for Long-Horizon Reasoning — arXiv:2507.16784
• Building Effective AI Agents — Anthropic
• Claude Code — Anthropic