Lição 4: Compactação e notas: gestão de contexto para tarefas longas

Objetivos de aprendizado:

• Dizer o que é a compactação e como ela é implementada: quando uma conversa se aproxima do limite da janela, entregar o histórico de mensagens ao modelo para resumir e então reiniciar uma janela nova a partir desse resumo
• Escrever a instrução de resumo e a lista do que manter e do que descartar de uma compactação, seguindo a regra: preservar decisões arquiteturais e bugs não resolvidos, descartar saída de ferramenta redundante
• Distinguir os papéis da compactação e das notas estruturadas, e projetar um esquema de notas escritas conforme se avança para um agente de tarefa longa

Pré-requisitos: Você concluiu as Lições 1 a 3 deste curso e sabe escrever à mão o loop de harness do curso 7 desta série, “Fundamentos do Harness de Agente: Laços e Controle” | Anterior: Lição 3 << | Próxima: Lição 5 >>

Uma tarefa que uma janela não comporta

Comece por uma cena que você vai encontrar em breve. Você pega o harness que escreveu à mão no curso 7 desta série, “Fundamentos do Harness de Agente: Laços e Controle”, e o aponta para uma tarefa de depuração: corrigir uma condição de corrida que só aparece sob concorrência. O agente lê arquivos, roda testes, edita código, roda os testes de novo — quarenta e tantos turnos adentro, a tarefa ainda não terminou, mas o histórico de mensagens inchou para além de cem mil tokens e a janela está prestes a encher.

As quatro válvulas de controle do curso 7 (máximo de turnos, orçamento, detecção de giro em falso, válvula de aprovação) não ajudam aqui. Elas governam “não deixe o loop fugir do controle”, mas o loop está se comportando bem — a tarefa é que é longa. Isso não é um acidente; é a natureza do loop: "An agent running in a loop generates more and more data that could be relevant for the next turn of inference"¹ (um agente rodando em um loop gera cada vez mais dados que podem ser relevantes para o próximo turno de inferência) — saída de ferramenta, conclusões intermediárias, tentativas fracassadas, tudo se empilhando no histórico de mensagens.

E a janela não é de graça. Um modelo que analisa grandes volumes de contexto lança mão de um "attention budget" (orçamento de atenção), e "Every new token introduced depletes this budget by some amount."¹ (cada novo token introduzido esgota esse orçamento em alguma medida.) Quanto mais tokens se empilham, pior fica o modelo na recuperação precisa: "as the number of tokens in the context window increases, the model's ability to accurately recall information from that context decreases"¹ (conforme o número de tokens na janela de contexto cresce, a capacidade do modelo de recuperar informação com precisão desse contexto diminui) — uma ladeira suave em vez de um penhasco, mas ladeira abaixo do mesmo jeito, de modo que "context, therefore, must be treated as a finite resource with diminishing marginal returns."¹ (o contexto, portanto, deve ser tratado como um recurso finito com retornos marginais decrescentes.) A documentação de boas práticas do Claude Code é mais direta — "Claude's context window fills up fast, and performance degrades as it fills," (a janela de contexto do Claude enche rápido, e o desempenho se degrada conforme ela enche) e "The context window is the most important resource to manage."² (a janela de contexto é o recurso mais importante a gerenciar.)

Quando uma tarefa fica longa demais para uma janela só comportar, você tem duas armas: a compactação e as notas estruturadas. Esta lição trabalha as duas.

Compactação: resuma, depois abra uma janela nova

A compactação é exatamente o que o nome diz: "taking a conversation nearing the context window limit, summarizing its contents, and reinitiating a new context window."¹ (pegar uma conversa que se aproxima do limite da janela de contexto, resumir seu conteúdo e reiniciar uma nova janela de contexto.) Repare na última parte — você não enfia o resumo de volta na conversa antiga e continua entulhando; você reinicia. A janela antiga é abandonada por inteiro, e a nova viaja leve, carregando apenas o system prompt e o resumo.

A implementação é mais simples do que parece: trata-se de "passing the message history to the model to summarize and compress the most critical details."¹ (passar o histórico de mensagens ao modelo para resumir e comprimir os detalhes mais críticos.) O que significa que a compactação é, ela mesma, uma chamada extra de modelo. Em código fica mais ou menos assim (formatHistory só junta o array de mensagens em texto legível; implementação omitida):

Emendar isso naquele loop do curso 7 exige só mais uma ideia: no início de cada turno, verifique o uso de tokens do histórico de mensagens e, assim que ele se aproximar do limite, chame compact() e substitua o array messages inteiro pelo valor de retorno. Construir isso de fato dentro do harness — como definir o limiar de disparo, o que fazer quando a compactação falha — é o material prático da Lição 6; por ora, basta entender o mecanismo.

A arte da compactação: o que manter, o que descartar

A parte difícil da compactação não é “como resumir” — é “o que manter, o que descartar”. A direção, na verdade, é clara: "preserves architectural decisions, unresolved bugs, and implementation details while discarding redundant tool outputs."¹ (preserva decisões arquiteturais, bugs não resolvidos e detalhes de implementação, enquanto descarta saídas de ferramenta redundantes.)

Por que esse trade-off? Imagine o agente “acordando” na janela nova; aquele resumo é toda a memória que ele tem. O custo de comprimir na direção errada é concreto: digamos que sua instrução de resumo diga apenas “resuma brevemente o conteúdo da conversa”, e o modelo descarte sem cerimônia o “há uma condição de corrida não terminada em orders/service.js” — o agente acorda vendo só registros marcados como “concluído”, então ou declara o trabalho pronto ou fuça em coisas que você já corrigiu. Uma compactação, e quarenta turnos de trabalho acabaram de sair dos trilhos.

Inverta a situação: saída de ferramenta redundante é o alvo mais gordo. Um grep retorna 200 linhas correspondentes; o sinal útil já foi capturado na conclusão do passo seguinte, “estreitado para a função updateStatus”. As 200 linhas brutas que ficam por ali só queimam orçamento de atenção, sem acrescentar quase nenhum valor de decisão para o próximo movimento.¹

Uma autoverificação prática: depois de escrever a instrução de resumo, pegue uma conversa longa real e compacte-a uma vez; depois responda três perguntas usando só o resumo — “o que deve acontecer em seguida”, “quais decisões estão travadas”, “quais buracos continuam abertos”. Se as três saírem limpas, as regras do que manter e do que descartar da sua instrução passaram; se alguma vier em branco, volte e remende aquela regra de manutenção.

Compactação em produção: compactação automática e /clear

A ferramenta que você usa todo dia tem uma referência pronta. O Claude Code "automatically compacts conversation history when you approach context limits, which preserves important code and decisions while freeing space"² (compacta automaticamente o histórico da conversa quando você se aproxima dos limites de contexto, o que preserva código e decisões importantes enquanto libera espaço) — o mesmo mecanismo do compact() escrito à mão acima, só que produtizado, com o disparo e as regras do que manter e do que descartar já resolvidos para você.

Mas a compactação não é a única opção. Se você está mudando para uma tarefa nova e sem relação com a anterior, o contexto antigo não é só inútil — é nocivo, porque "Long sessions with irrelevant context can reduce performance."² (sessões longas com contexto irrelevante podem reduzir o desempenho.) Nesse ponto a documentação manda "Run /clear between unrelated tasks to reset the context window entirely"² (rode /clear entre tarefas sem relação para redefinir inteiramente a janela de contexto) — sem resumir, sem preservar, apenas um reset completo. O raciocínio é simples: a compactação custa uma chamada de modelo e carrega o risco de errar o julgamento do que manter e do que descartar; para uma tarefa sem relação, limpar de vez é mais barato e mais limpo. A compactação serve ao “a mesma tarefa ainda não acabou”, enquanto o /clear serve ao “agora estou fazendo outra coisa”.

Essa documentação tem também uma frase que vale manter à mão: "A clean session with a better prompt almost always outperforms a long session with accumulated corrections."² (uma sessão limpa com um prompt melhor quase sempre supera uma sessão longa com correções acumuladas.) Em tradução livre: quando o histórico de uma sessão é feito principalmente de “não, tente de novo” e “ainda está errado”, o valor histórico para o próximo passo é provavelmente negativo — reabrir uma sessão e assar a lição direto em um prompt novo costuma bater arrastar toda aquela bagagem adiante.

Notas estruturadas: escreva o estado-chave fora da janela

A compactação tem uma fraqueza embutida: ela é reativa. Você espera a janela quase encher para só então olhar para trás e resumir, de modo que o que sobrevive depende inteiramente do julgamento daquele momento — e julgamento pode falhar. Existe um jeito de preservar a informação enquanto ela está fresca?

Existe, e é simples: "the agent regularly writes notes persisted to memory outside of the context window."¹ (o agente escreve regularmente notas persistidas em memória fora da janela de contexto.) "Like Claude Code creating a to-do list, or your custom agent maintaining a NOTES.md file."¹ (como o Claude Code criando uma lista de tarefas, ou o seu agente customizado mantendo um arquivo NOTES.md.) Tome de novo aquela tarefa inicial da condição de corrida; um conjunto de notas com nota de aprovação fica mais ou menos assim:

A ligação é algo que você aprendeu no curso 7: dê ao agente uma ferramenta de escrita de arquivo e depois acrescente um requisito ao system prompt — “sempre que tomar uma decisão importante, descobrir um problema novo ou concluir uma etapa, atualize o NOTES.md primeiro, depois continue”. Daí em diante, o estado-chave da janela tem uma cópia de segurança fora da janela. Não importa como a janela compacte ou reinicie, as notas ficam no disco; a primeira coisa que a janela nova faz é lê-las de volta.

Esse truque não é específico de tarefas de programação. "Claude playing Pokémon demonstrates how memory transforms agent capabilities in non-coding domains."¹ (o Claude jogando Pokémon demonstra como a memória transforma as capacidades de um agente em domínios fora da programação.) O sistema multiagente de pesquisa da Anthropic faz o mesmo em tarefas longas: "agents summarize completed work phases and store essential information in external memory."³ (os agentes resumem fases de trabalho concluídas e guardam informação essencial em memória externa.)

Divisão de trabalho: a compactação é a rede de segurança, as notas são a rotina

Ponha as duas armas lado a lado e a divisão de trabalho fica clara. A compactação é passiva: dispara quando a janela se aproxima do limite, com um momento que não é escolha sua, e tem perdas — o que sobrevive depende do julgamento daquele instante sobre o que manter e o que descartar. As notas são ativas: você escreve o estado-chave no instante em que ele nasce, o conteúdo é sem perdas, e o custo é só algumas linhas de escrita em arquivo a cada vez. Em uma frase: as notas são a rotina diária, a compactação é a rede de segurança.

As duas não brigam; elas se reforçam. Quanto mais diligentes as suas notas, mais leve a consequência de a compactação deixar algo cair — se o resumo perder um detalhe, as notas ainda o têm. Na direção contrária, ter a compactação como rede de segurança significa que as notas não precisam ser exaustivas, apenas cobrir as poucas categorias que “o agente tem de saber ao acordar”.

A proporção também importa. Nem toda tarefa merece esse maquinário: a orientação da Anthropic é "you should consider adding complexity only when it demonstrably improves outcomes."⁴ (você deveria considerar adicionar complexidade apenas quando isso melhorar comprovadamente os resultados.) Repare no verbo — considerar. É uma postura de ponderação, não uma proibição. Para uma tarefa que termina em dez turnos, compactação e notas são peças sobressalentes; comece pelo loop mais simples e acrescente-as quando você de fato bater no teto.

Duas fronteiras finais, para você não perder tempo caçando respostas que esta lição não cobre:

• A persistência entre sessões dos arquivos de nota — como organizá-los, como recuperá-los em uma sessão nova, a manutenção de longo prazo — é o assunto do curso 5 desta série, “Memória e Estado de Agente”. Esta lição se importa apenas com como as notas aliviam a carga da janela dentro de uma única tarefa longa.
• Lidar com tarefas de horizonte longo tem, na verdade, três movimentos: "compaction, structured note-taking, and multi-agent architectures,"¹ (compactação, anotação estruturada e arquiteturas multiagente,) todos voltados a permitir que os agentes "maintain coherence, context, and goal-directed behavior over sequences of actions."¹ (mantenham coerência, contexto e comportamento orientado a objetivos ao longo de sequências de ações.) Os dois primeiros estão feitos; o terceiro — dividir a tarefa entre subagentes que carregam janelas limpas — é a Lição 5.

Recapitulação

• Compactação = quando uma conversa se aproxima do limite da janela, "passing the message history to the model to summarize and compress the most critical details,"¹ e então "reinitiating a new context window"¹ a partir desse resumo — reiniciar, não anexar de volta à conversa antiga
• A arte da compactação está na escolha do que manter e do que descartar: "preserves architectural decisions, unresolved bugs, and implementation details while discarding redundant tool outputs";¹ comprima na direção errada e o agente acorda esquecido do que estava fazendo
• O Claude Code "automatically compacts conversation history when you approach context limits, which preserves important code and decisions"²; entre tarefas sem relação, use /clear para um reset completo — "A clean session with a better prompt almost always outperforms a long session with accumulated corrections"²
• Notas estruturadas: "the agent regularly writes notes persisted to memory outside of the context window" (lista de tarefas, NOTES.md);¹ a compactação é rede de segurança passiva e com perdas, as notas são externalização ativa escrita conforme se avança
• Os três movimentos para tarefas de horizonte longo são "compaction, structured note-taking, and multi-agent architectures";¹ os dois primeiros estão na mão, o terceiro é a Lição 5. A persistência das notas entre sessões é o assunto do curso 5 desta série, “Memória e Estado de Agente”

>> Lição 5: Subagentes e isolamento de contexto