Context engineering é só decidir o que o modelo vê

Context engineering é decidir o que o modelo vê. O resto é detalhe de implementação.

De tempos em tempos a indústria cunha uma palavra nova para algo que já era verdade. Context engineering é a mais recente. A ideia não está errada, e o rótulo não é inútil. O que está errado é o jeito como o conceito é ensinado: como uma disciplina vizinha do prompt engineering, uma arte mais suave, algo que se faz com palavras bem escolhidas e estrutura caprichada. Esse enquadramento perde a parte que realmente importa.

A context window é um orçamento rígido. Cada token que entra desloca um token que você queria manter. Quando o orçamento acaba, o agente não enxerga o começo do próprio plano, perde o erro que estava perseguindo e começa a pedir coisas que já leu. Isso não é falha do modelo. É falha de gestão. Context engineering é o trabalho de gerir esse orçamento, e é quase certo que você já está falhando nele.

Coloco código em produção há 25 anos. No fim de 2025, construí sozinho uma fintech cripto de 13 apps com agentes de IA em 70 dias. O que eu mais ajustei não foi o modelo, nem os prompts, nem a escolha de ferramentas. Foi o que o agente podia ver a cada momento. Isto é o que aprendi.

Context engineering não é prompt engineering

As pessoas confundem as duas coisas o tempo todo, e a confusão custa caro. Prompt engineering é o ofício de escrever bem uma mensagem: a instrução certa, os exemplos certos, o enquadramento certo para um único pedido. Context engineering opera no nível da sessão. Gerencia o orçamento inteiro de tokens ao longo de todos os turnos, decidindo o que fica, o que é comprimido, o que sai e o que é carregado de novo.

✗

Prompt engineering

1. 01Otimiza uma única mensagem
2. 02Foca na clareza da instrução
3. 03Escopo: um pedido
4. 04Resultado: um one-shot melhor
5. 05Já bem compreendido

✓

Context engineering

1. 01Gerencia o orçamento inteiro de tokens
2. 02Foca no que o modelo vê
3. 03Escopo: a sessão inteira
4. 04Resultado: taxa de tarefas concluídas
5. 05Onde estão os ganhos reais

Um prompt melhor numa janela cheia não faz nada. O modelo não tem onde encaixá-lo. Você pode escrever a instrução mais caprichada da sua vida e o agente ainda vai alucinar a estrutura de arquivos que já leu, porque a leitura está enterrada sob vinte mil tokens de saída de testes de que ele nunca precisou. O orçamento é a restrição. O prompt vem depois dela.

Onde context engineering se encaixa no harness

Context engineering não existe sozinho. É uma das quatro partes do que o harness engineering chama de sistema em volta do modelo: o loop do agente, a interface de ferramentas, a gestão de contexto e o controle. A gestão de contexto é a terceira parte. Ela responde a uma pergunta a cada turno: de tudo o que poderia entrar na janela, o que deveria entrar?

As quatro camadas do harness

1. L1

   Loop do agente

   A orquestração que continua chamando o modelo até a tarefa terminar. Decide quando parar, quando tentar de novo, quando passar adiante. Context engineering não mora aqui, mas o loop determina quantos turnos queimam o orçamento.

   +
2. L2

   Interface de ferramentas

   Cada ferramenta que o modelo pode chamar. O próprio schema da ferramenta custa tokens antes de o modelo digitar qualquer coisa. Um MCP server com 40 ferramentas carregadas pode consumir de 13k a 18k tokens só de schema, antes de um único comando rodar.

   +
3. L3

   Gestão de contexto

   O que o modelo vê a cada turno. É aqui que mora o context engineering: comprimir a saída das ferramentas, compactar o histórico, carregar memória, tirar o que não importa mais. As decisões de orçamento acontecem aqui.

   budget = window size
   spent = tool output + history + system + schemas
   available = budget - spent

   +
4. L4

   Controle

   Os guardrails e checkpoints que impedem o agente de sair correndo. Permissões, paradas com humano no loop, verificação antes de entregar. Importante, mas não é o assunto de hoje.

Dar nome a isso importa. Se você chama de “context engineering” tudo o que vai além de um prompt one-shot, perde a distinção entre curar a janela (gestão de contexto) e projetar o sistema que gerencia a janela (harness engineering). Os dois são reais, e não são o mesmo trabalho.

O orçamento que você já está estourando

Aqui vem a parte desconfortável. Você não precisa fazer nada fora do comum para estourar a context window. O comportamento padrão de qualquer agente de IA de código estoura por você, automaticamente, em quase toda tarefa que não seja trivial.

São quatro vazamentos. Cada um é real, cada um tem um custo de tokens mensurável, e quase todo harness ignora pelo menos dois deles.

Os quatro vazamentos de contexto

1. 01

   Saída bruta das ferramentas

   Cada comando que o agente roda despeja a saída inteira na janela. Um git status num repo movimentado dá cerca de 2.000 tokens. Uma rodada completa de testes, cerca de 25.000. O agente precisava dos três testes que falharam, não dos vinte e dois que passaram.

   git status    ~2,000 tokens
   full test run ~25,000 tokens
   git log --all can exceed 10,000

   +
2. 02

   Histórico repetido

   A cada turno a conversa inteira é reenviada. O arquivo que o agente leu no turno três ainda está lá no turno quinze. O erro que ele imprimiu no turno quatro foi impresso de novo no turno sete. O modelo paga para reler tudo isso, toda vez.

   same file x 5 reads = 5x the token cost
   error printed x 3 = 3x the token cost

   +
3. 03

   System prompt inchado

   Um system prompt longo custa tokens em todo turno, porque ele vai no topo de todo contexto. O pi, o agente de código minimalista, roda com cerca de 150 palavras. Muitos harnesses comerciais usam dez vezes isso, cheios de instruções que o modelo já conhece do treinamento.

   +
4. 04

   Schemas de MCP sem uso

   Os schemas das ferramentas entram na janela quer o modelo chame as ferramentas, quer não. Um MCP server popular pode consumir de 13.000 a 18.000 tokens em schema antes de um único comando rodar. Carregue só as ferramentas de que você realmente precisa nesta sessão.

   one MCP server  13k to 18k tokens
   two MCP servers 26k to 36k tokens
   both loaded regardless of usage

O detalhamento do custo de tokens tem a conta completa. O ponto aqui é mais estreito: context engineering começa por saber qual desses quatro vazamentos está comendo o seu orçamento. Não dá para consertar o que você ainda não nomeou.

As táticas, uma para cada vazamento

Conhecer os vazamentos não basta. Aqui está o que fazer com cada um. Não são opções teóricas. São os movimentos reais, em ordem de retorno.

Comprima a saída das ferramentas na origem. A mudança de maior retorno em qualquer harness é um filtro na saída das ferramentas. O RTK é um proxy de CLI open source que fica entre o shell e o modelo. O agente roda um comando e o RTK reescreve a saída antes de ela chegar à janela. Filtragem inteligente, agrupamento, deduplicação. Nos comandos de dev do dia a dia, economiza de 60 a 90%. Um hook de shell deixa isso invisível para o agente. Esse é o que vale copiar hoje.

Compacte o histórico entre turnos. A camada da conversa é a segunda correção. Entre os turnos, deduplique leituras repetidas de arquivos, reduza os passos bem-sucedidos a um resumo de uma linha, mantenha os turnos recentes intactos e resuma os antigos. O modelo vê o delta em vez da transcrição de novo. Não é uma ideia nova. É o mesmo filtro da camada de ferramentas, aplicado um nível acima.

Mantenha o system prompt curto e específico. A abordagem minimalista do pi é instrutiva. Cerca de 150 palavras, nada que o modelo não precise saber. A teoria: um modelo de fronteira já entende engenharia de software, controle de versão e iteração cuidadosa. Você não precisa explicar isso. Precisa dizer o que é específico do seu projeto. Cada linha de boilerplate no system prompt é um imposto em cada turno.

Carregue só as ferramentas de que esta sessão precisa. Cada MCP server que você carrega na inicialização custa tokens, usando ou não. Carregar ferramentas por sessão é a correção: comece com o conjunto mínimo e adicione ferramentas quando o agente realmente precisar. É uma escolha de design do harness, não uma escolha de modelo.

Movimentos de context engineering, em ordem

• ✓Obrigatório:
  Comprimir a saída das ferramentas com um proxy de CLIRTK em github.com/rtk-ai/rtk. Open source, um hook de shell deixa ele transparente. Corta de 60 a 90% nos comandos de dev do dia a dia. Comece aqui.
• ✓Obrigatório:
  Compactar o histórico da conversa entre turnosDeduplicar leituras, resumir turnos antigos, manter os recentes intactos. O modelo deve ler o delta, não o replay.
• ✓Obrigatório:
  Auditar o system prompt atrás de boilerplateCorte tudo o que o modelo já sabe do treinamento. O que sobra deve ser específico do projeto: as convenções, as decisões, o que o treinamento não tem como saber.
• •Opcional:
  Carregar ferramentas por sessão, não na inicializaçãoSó as ferramentas de que esta sessão realmente precisa. Adicione quando o agente pedir, não antes. Cada schema carregado custa tokens, o modelo chamando ou não.
• •Opcional:
  Injetar memória no início da sessão em vez de explicar tudo de novoDecisões e convenções do projeto num arquivo AGENTS.md. O harness carrega automaticamente. O agente começa sabendo em vez de perguntando.

A tabela que deixa isso concreto

Veja como fica a mesma sessão de código com um harness ingênuo e com um harness com context engineering. Mesmo modelo, mesma tarefa, mesmas ferramentas.

Contexto ingênuo vs. projetado

Mesmo modelo. Mesma tarefa. Um fica sem janela. O outro não.

Item do orçamento	Harness ingênuo	Harness projetado
System prompt	5.000 a 10.000 tokens de boilerplate	150 palavras, só o específico do projeto
Schemas de ferramentas carregados	todos os servers, 15k a 30k tokens na inicialização	por sessão, 2k a 4k tokens
Saída por chamada de ferramenta	despejo bruto, 2k a 25k por comando	comprimida, 60 a 90% a menos
Histórico da conversa	replay completo a cada turno	só o delta, turnos antigos resumidos
Memória da sessão	explicar tudo de novo no início da sessão	carregada automaticamente do AGENTS.md
Resultado	janela esgotada no meio da tarefa	orçamento disponível para o trabalho de verdade

Os números da esquerda não são hipotéticos. São o que você tem com os padrões de fábrica. Você paga por uma janela de 200k tokens e queima um terço dela antes de o agente escrever a primeira linha útil.

Context engineering é um meio, não um culto

O discurso em torno de context engineering ganhou um certo sabor. As pessoas escrevem como se uma janela bem gerida fosse o objetivo. Não é. O objetivo é terminar a tarefa. A métrica é tokens por tarefa concluída, não um orçamento arrumadinho.

Isso importa porque curadoria demais também é um modo de falha. Comprima demais a saída das ferramentas e o modelo perde o sinal de erro de que precisava. Resuma o histórico cedo demais e ele perde o plano que estava executando. Tire da janela o arquivo que ele está editando e ele reescreve às cegas. Context engineering é um problema de calibração, não de minimização. A pergunta não é “quão pequena consigo deixar a janela”, e sim “o modelo tem o que precisa para dar o próximo passo?”

O enquadramento que acho útil: context engineering é gestão de orçamento de um recurso fixo. Você não gasta zero no mercado porque gastar zero é virtuoso. Gasta o que precisa e evita gastar com o que não te alimenta. A sessão que termina a tarefa no turno oito com a janela pela metade é um resultado melhor do que a sessão que chega ao turno trinta com um histórico perfeitamente compacto e nenhuma tarefa feita.

O guia de harness engineering é onde isso se conecta ao sistema maior. A gestão de contexto é uma de quatro partes. Isolada, não é a mais importante. É a parte que determina se as outras três conseguem funcionar ao longo de uma sessão real numa codebase real.

Context engineering é decidir o que o modelo vê. Acerte essa decisão e o modelo faz o que é capaz de fazer. Erre e você está pagando por uma inteligência que nunca vai usar.

Perguntas frequentes

O que é context engineering em agentes de IA de código?+

Context engineering é a prática de decidir quais tokens entram na context window do modelo a cada turno de uma sessão de agente. Não é sobre escrever prompts melhores. É sobre gerir o orçamento rígido da context window: comprimir a saída das ferramentas, compactar o histórico, manter o system prompt enxuto e carregar só as ferramentas de que a sessão realmente precisa. O objetivo é que o modelo tenha o que precisa para dar o próximo passo sem desperdiçar tokens com ruído que ele nunca vai usar.

Qual a diferença entre context engineering e prompt engineering?+

Prompt engineering otimiza uma única mensagem: a instrução certa, os exemplos certos, o enquadramento certo para um pedido. Opera no escopo de uma chamada.

Context engineering opera no nível da sessão. Gerencia o orçamento inteiro de tokens ao longo de todos os turnos: o que fica na janela, o que é comprimido, o que sai e o que é carregado de novo da memória. Um prompt melhor numa janela cheia não faz nada. O orçamento é a restrição, e o prompt engineering vem depois dela.

Quais são os maiores vazamentos da context window em agentes de IA de código?+

São quatro vazamentos principais. O maior é a saída bruta das ferramentas: um git status dá cerca de 2.000 tokens e uma rodada completa de testes, cerca de 25.000. O agente precisava dos testes que falharam, não dos que passaram.

O segundo é o histórico repetido: a conversa inteira é reenviada a cada turno, então um arquivo lido no turno três ainda está lá no turno quinze, pagando o seu custo em tokens toda vez.

O terceiro é um system prompt inchado: tudo o que o modelo já sabe do treinamento é um imposto em cada turno. Mantenha só o que é específico do projeto.

O quarto são os schemas de MCP sem uso: cada server de ferramentas carregado na inicialização custa tokens, o modelo chamando ou não. Um MCP server popular pode consumir de 13.000 a 18.000 tokens antes de um único comando rodar.

Qual o jeito mais rápido de reduzir o uso da context window num agente de código?+

Comprimir a saída das ferramentas na origem. O RTK (github.com/rtk-ai/rtk) é um proxy de CLI open source que fica entre o shell e o modelo. O agente roda um comando e o RTK reescreve a saída numa forma comprimida antes de ela chegar à context window. Nos comandos de dev do dia a dia, economiza de 60 a 90%. Um hook de shell deixa isso totalmente transparente para o agente. É a mudança de maior retorno e a mais fácil de plugar.

Como o custo dos schemas de MCP afeta a context window?+

Cada MCP server que você carrega injeta o schema das suas ferramentas na context window no início da sessão, antes de o agente digitar qualquer coisa. Um único MCP server popular pode consumir de 13.000 a 18.000 tokens em schema. Carregue dois e você gastou de 26.000 a 36.000 tokens antes de um único comando rodar. A correção é carregar ferramentas por sessão: começar com o conjunto mínimo de que a sessão realmente precisa e adicionar mais só quando o agente pedir. Carregar todas as ferramentas disponíveis na inicialização é um padrão comum e um desperdício constante.

Context engineering é mais importante do que escolher um modelo melhor?+

Na maioria das sessões reais de código, sim. Um modelo melhor numa janela cheia ainda falha na tarefa quando o arquivo relevante saiu da janela três turnos atrás. Context engineering determina se o modelo tem a informação de que precisa para agir. Com a camada de contexto funcionando, uma troca de modelo soma limpo por cima. Antes de consertar a camada de contexto, trocar de modelo quase sempre só paga o mesmo desperdício por um preço mais alto.