Lição 1: De prompt engineering a context engineering
Objetivos de aprendizado:
- Reenunciar as definições de prompt engineering e de context engineering, e dizer por que as duas são uma “evolução” e não uma “substituição”
- Usar as duas ideias de “orçamento de atenção” e “apodrecimento do contexto” para explicar a um colega o que está errado em “a janela é grande o bastante, então enfie tudo lá dentro”
- Apontar, no loop do harness que você construiu no curso “Fundamentos do Harness de Agente: Laços e Controle” desta série, os lugares em que o contexto só cresce e nunca encolhe
Pré-requisitos: Você concluiu o curso “Fundamentos do Harness de Agente: Laços e Controle” desta série e tem à mão um loop funcional dirigido por stop_reason | Próxima: Lição 2 >>
Uma cena familiar: a cada volta do loop, a janela fica mais pesada
No curso “Fundamentos do Harness de Agente: Laços e Controle” desta série, você escreveu à mão um loop assim (simplificado; as quatro válvulas de controle — teto máximo de turnos, orçamento e as demais — ficam de fora por ora):
Naquela época toda a nossa atenção estava no fluxo de controle: como ler o stop_reason, como instalar as válvulas de controle. Agora mude o ângulo e encare o array messages — ele só recebe push, nunca é podado. A cada turno, pelo menos duas coisas entram: a resposta do modelo naquele turno (com seus blocos tool_use) e os resultados que as ferramentas devolvem. O segundo tipo costuma ser o grosso: imagine um único list_files trazendo de volta algumas centenas de nomes de arquivo, ou uma busca em logs trazendo dezenas de KB de texto cru. Dali em diante eles ficam na janela para sempre, relidos do zero a cada rodada de raciocínio.
Isso não é um deslize da sua implementação; é a natureza de um agente. "An agent running in a loop generates more and more data that could be relevant for the next turn of inference"1 (um agente rodando em loop gera cada vez mais dados que poderiam ser relevantes para o próximo turno de inferência), e, como ele detém a autonomia, pode seguir por um bom número de turnos2. No curso “Fundamentos de prompt engineering: como escrever instruções eficazes” desta série você aprendeu a escrever uma única instrução com clareza — mas, por melhor que uma instrução seja escrita, ela ainda é só um bloco pequeno dentro da janela. O que de fato decide como o agente se sai no turno 40 é tudo aquilo que estiver na janela inteira naquele momento.
Duas definições: de “escrever uma boa frase” a “gerenciar a janela inteira”
Formalize essa observação e você chega a duas definições.
Prompt engineering: "Prompt engineering refers to methods for writing and organizing LLM instructions for optimal outcomes"1 (prompt engineering se refere a métodos para escrever e organizar instruções de LLM visando resultados ótimos). A pergunta que ele responde é: “como devo escrever e arranjar esta instrução para obter o melhor efeito?”
Context engineering: "the set of strategies for curating and maintaining the optimal set of tokens (information) during LLM inference"1 (o conjunto de estratégias para curar e manter o conjunto ótimo de tokens (informação) durante a inferência de um LLM). A pergunta que ele responde é: “para esta rodada de raciocínio, quais tokens devem estar na janela, e quais não devem?”
Repare no salto de perspectiva. A primeira é um problema de escrita pontual — escreveu uma vez, está resolvido. A segunda é um trade-off que você tem de responder de novo a cada volta do loop. A Anthropic enquadra explicitamente context engineering como a progressão natural de prompt engineering — "we view context engineering as the natural progression of prompt engineering"1 (vemos context engineering como a progressão natural de prompt engineering) —, então a habilidade que você construiu no curso “Fundamentos de prompt engineering: como escrever instruções eficazes” desta série não se perde em nada. Ela vira um subconjunto de um problema maior: o system prompt ainda precisa ser bem escrito, mas é só um dos muitos ingredientes de contexto que você agora tem de gerenciar.
A comunidade tem opiniões mais agressivas. Um roteiro de engenharia de agentes de 2026 afirma que "Prompt engineering is dead as a standalone skill in 2026."3 (prompt engineering está morto como habilidade autônoma em 2026.) Note que esse é o veredito opinativo daquele roteiro, e esta lição não o trata como consenso — a formulação da Anthropic é bem mais comedida: evolução, não substituição1. Dito isso, vale guardar a definição de uma linha que o mesmo roteiro dá para context engineering: "deciding what tokens are in front of the model at every step of the loop"3 (decidir quais tokens estão diante do modelo em cada etapa do loop). E o mesmo roteiro põe o dedo no quanto o harness importa: "Same model, different harness, completely different result."3 (mesmo modelo, harness diferente, resultado completamente diferente.) — algo que você já deveria sentir na pele depois dos experimentos do curso “Fundamentos do Harness de Agente: Laços e Controle” desta série.
Orçamento de atenção: cada novo token entra na conta
Por que isto é algo que você tem de gerenciar? Uma janela maior não é simplesmente rédea solta? Aí entra o primeiro fato físico.
"LLMs have an "attention budget" that they draw on when parsing large volumes of context"1 (LLMs têm um “orçamento de atenção” do qual sacam ao processar grandes volumes de contexto). O detalhe é que esse orçamento é finito: "Every new token introduced depletes this budget by some amount"1 (cada novo token introduzido esgota esse orçamento em alguma medida).
Uma analogia. A capacidade da janela é a área de piso de um galpão; o orçamento de atenção é a equipe que você manda lá dentro achar a mercadoria. Amplie o galpão dez vezes e a equipe não cresce junto — quanto mais cheias as prateleiras, mais difícil desencavar o único item que você de fato quer. Enfiar mais um documento “por via das dúvidas” na janela não é um backup grátis; é uma cobrança real contra o orçamento, paga para cobrir o custo de lê-lo e descartá-lo.
Vire para esse ponto de vista e muitos hábitos merecem uma segunda olhada. “A janela aguenta, então vamos colar a documentação inteira da API” — aguentar é uma questão de galpão, ler bem é uma questão de orçamento, e as duas coisas não são a mesma.
Apodrecimento do contexto: uma ladeira suave, não um penhasco
A consequência macro de um orçamento sendo drenado continuamente tem um nome vívido: apodrecimento do contexto (context rot) — "as the number of tokens in the context window increases, the model's ability to accurately recall information from that context decreases"1 (conforme o número de tokens na janela de contexto aumenta, a capacidade do modelo de recuperar com precisão informações desse contexto diminui).
Dois detalhes fáceis de errar, fixados aqui:
Primeiro, é gradual, não uma queda súbita. Essa degradação aparece como uma ladeira de desempenho — "These factors create a performance gradient rather than a hard cliff"1 (esses fatores criam um gradiente de desempenho, não um penhasco abrupto) — e não como um penhasco em que tudo para de funcionar de repente passada certa contagem de tokens. Ou seja, você nunca vai receber um erro; o agente só vai ficando devagarinho mais burro. Em termos do dia a dia (esta é a forma típica que isso assume na experiência de engenharia, não uma enumeração da fonte): convenções confirmadas antes começam a ser esquecidas, arquivos já lidos são lidos de novo, bugs já corrigidos são revertidos. Degradação sem alarme é mais difícil de rastrear do que um erro.
Segundo, é uma regra geral, não a mania de um modelo. Alguns modelos degradam de forma mais suave que outros, mas "some models exhibit more gentle degradation than others, this characteristic emerges across all models"1 (alguns modelos exibem degradação mais suave que outros, essa característica emerge em todos os modelos). Trocar para um modelo mais forte pode adiar o problema; não pode cancelá-lo.
Junte os dois e você tem a primeira pedra angular desta lição: "context, therefore, must be treated as a finite resource with diminishing marginal returns"1 (o contexto, portanto, precisa ser tratado como um recurso finito com retornos marginais decrescentes). O milésimo token que você enfia na janela e o centésimo milésimo ocupam o mesmo espaço, mas estão a mundos de distância no valor que agregam. O instinto de “mais é mais seguro” aponta exatamente para o lado errado — cada pedacinho extra de “garantia” que você espreme lá dentro dilui a atenção do modelo sobre a informação que de fato importa.
De volta aos agentes: por que isto é o alicerce, não o acabamento
Numa pergunta e resposta de turno único, você talvez nem note o apodrecimento do contexto — a janela é usada uma vez e descartada, e a contagem de tokens normalmente não chega à zona de perigo. Agentes transformam esse problema de “encontrado de vez em quando” em “piorando a cada turno”: os dados no loop só crescem e nunca encolhem1, e agentes podem rodar autonomamente por muitos turnos2. Volte ao código de abertura — aquele array messages que só aceita push e nunca devolve nada é esse processo tornado concreto.
A experiência de engenharia no campo bate perfeitamente. A documentação oficial do Claude Code afirma que "Claude's context window fills up fast, and performance degrades as it fills."4 (a janela de contexto do Claude enche rápido, e o desempenho se degrada conforme ela enche.) Ela chama a janela de contexto de "the most important resource to manage."4 (o recurso mais importante a gerenciar.) A mesma documentação ainda traz uma observação que vale copiar: "A clean session with a better prompt almost always outperforms a long session with accumulated corrections."4 (uma sessão limpa com um prompt melhor quase sempre supera uma sessão longa com correções acumuladas.) — “conversou mais tempo” não quer dizer “conversou melhor”, e cada correção empilhada, cada desvio percorrido, continua na janela participando da próxima rodada de raciocínio.
Então, uma posição precisa para context engineering: não é o acabamento que você dá na fase de ajuste fino; é o alicerce da confiabilidade de um agente. As quatro válvulas de controle do curso “Fundamentos do Harness de Agente: Laços e Controle” desta série gerenciam “não deixe o loop escapar”; este curso instala outro conjunto de mecanismos — “não deixe a janela apodrecer”. Junte os dois conjuntos e o seu harness fica de fato pronto para você confiar tarefas longas a ele.
O roteiro deste curso
Para tarefas de horizonte longo, a Anthropic resume três classes de técnicas — "compaction, structured note-taking, and multi-agent architectures" (compactação, anotação estruturada e arquiteturas multiagente), voltadas a ajudar agentes a "maintain coherence, context, and goal-directed behavior over sequences of actions"1 (manter coerência, contexto e comportamento orientado a objetivos ao longo de sequências de ações). Este curso segue esse caminho:
- Lição 2 disseca a janela: system prompt, definições de ferramentas, exemplos — quanto espaço cada um ocupa, e como escrevê-los sem desperdício.
- Lição 3 cobre a recuperação just-in-time: em vez de enfiar todo o material de antemão, dê ao agente identificadores leves e deixe que ele vá buscar as coisas sob demanda.
- Lição 4 cobre compactação e notas: quando a janela se aproxima do limite, como resumir e reiniciar, e como registrar informação-chave fora da janela.
- Lição 5 cobre subagentes e isolamento de contexto: mande o trabalho exploratório bagunçado para um subagente com janela limpa, e traga de volta só a conclusão destilada.
- Lição 6 volta ao seu próprio harness e instala esses mecanismos um a um.
Um último lembrete sobre proporção. Cada um desses mecanismos acrescenta complexidade, e a orientação de engenharia da Anthropic diz que "you should consider adding complexity only when it demonstrably improves outcomes."2 (você deveria considerar adicionar complexidade apenas quando ela comprovadamente melhora os resultados.) Por isso toda lição adiante explica “quando vale a pena” antes de explicar “como fazer” — nem todo agente precisa de subagentes, e nem toda tarefa vale uma compactação.
Recapitulação
- Context engineering é a progressão natural de prompt engineering: o primeiro gerencia “manter qual conjunto ótimo de tokens na janela no momento do raciocínio”, o segundo gerencia “como escrever e organizar instruções”, e a perspectiva sobe de uma frase para a janela inteira1.
- “Prompt engineering está morto como habilidade autônoma” é uma afirmação opinativa de um roteiro da comunidade3; esta lição usa a formulação mais comedida — evolução, não substituição1.
- LLMs processam o contexto usando um orçamento de atenção finito, e cada novo token consome uma parte dele1 — “a janela aguenta” e “o modelo consegue usar bem” são duas coisas diferentes.
- O apodrecimento do contexto é uma ladeira gradual de desempenho e não um penhasco, mais íngreme em alguns modelos e mais suave em outros, mas a tendência aparece em todos os modelos1, então ele não dá erro; só vai deixando o agente mais burro em silêncio.
- O contexto é um recurso finito com retornos marginais decrescentes1; os dados no loop de um agente só crescem e nunca encolhem1, e é por isso que a documentação oficial do Claude Code chama a janela de contexto de "the most important resource to manage."4 (o recurso mais importante a gerenciar.)
- As três classes de técnicas para tarefas de horizonte longo — compactação, anotação estruturada e arquiteturas multiagente1 — correspondem às linhas principais das Lições 4 e 5; a Lição 6 as instala no seu harness. Antes de introduzir qualquer complexidade, confirme que ela de fato melhora os resultados2.
>> Lição 2: Anatomia do contexto: system prompt, ferramentas e exemplos