antonio leandro

claude, na prática

Effective context engineering for AI agents

post · núcleo · 03 · contexto · Anthropic ·

a tese

o gargalo saiu do prompt e foi para o orçamento de atenção: o trabalho do engenheiro agora é achar o menor conjunto de tokens de alto sinal por turno, não escrever a frase perfeita.

o que fica

  1. A capacidade de recuperar informação cai conforme a janela enche — os autores chamam isso de context rot, dizem que aparece em todos os modelos e que é um gradiente de desempenho, não um penhasco.
  2. A escassez de atenção é arquitetural: a atenção do transformer cria n² relações par a par para n tokens, e os modelos treinaram majoritariamente em sequências curtas, então têm menos parâmetros especializados em dependência longa.
  3. A alternativa ao retrieval por embedding antes da inferência é o agente guardar só identificadores leves — caminho de arquivo, query salva, link — e carregar o dado no momento em que precisa; o próprio caminho já é metadado que informa a decisão.
  4. Explorar em runtime é mais lento que buscar dado pré-computado, e um agente mal guiado queima contexto em beco sem saída — por isso o padrão recomendado é híbrido: um pouco de contexto carregado de cara, o resto por conta do agente.
  5. Ao ajustar um prompt de compaction, o caminho é maximizar recall primeiro e só depois cortar o supérfluo para ganhar precisão; limpar resultado de tool call antigo é a forma mais segura e barata de compactar.
  6. Sub-agente resolve limite de contexto por isolamento: ele gasta dezenas de milhares de tokens explorando e devolve um resumo de 1.000 a 2.000 tokens, deixando o agente principal com a síntese e sem o lixo da busca.

o problema

Por uns anos, engenharia aplicada com LLM foi basicamente escrever prompt: achar as palavras que fazem o modelo classificar direito ou gerar o texto certo numa tacada. Isso funcionava porque o caso de uso era one-shot. O contexto era o que você escrevia, e você escrevia uma vez.

Agente quebra esse modelo. Um agente roda em loop — a definição que a Anthropic adota no post é “LLM usando ferramentas autonomamente em loop” — e cada volta do loop produz mais dado que pode ser relevante na próxima. Resultado de tool, histórico de mensagens, saída de MCP, arquivo lido: tudo isso disputa espaço com as instruções. E aqui aparece o problema real, que não é o tamanho da janela. É o que os autores chamam de context rot: conforme o número de tokens cresce, a capacidade do modelo de recuperar informação daquele contexto cai. Alguns modelos degradam com mais suavidade que outros, mas a característica aparece em todos.

a ideia

Trate contexto como recurso finito com retorno marginal decrescente, e não como um balde que você enche até dar erro.

A analogia que o post usa é orçamento de atenção. Cada token novo consome um pouco desse orçamento. A justificativa é arquitetural: a atenção deixa todo token atender a todo token, o que dá n² relações par a par para n tokens — quanto mais longo o contexto, mais essa capacidade se estica. Some a isso o fato de que a distribuição de treino tem muito mais sequência curta que longa, então o modelo tem menos experiência e menos parâmetros especializados em dependência que atravessa a janela inteira. Técnicas como interpolação de position encoding esticam a sequência, mas com alguma perda no entendimento de posição. Nada disso produz um penhasco: produz um gradiente de desempenho.

O princípio que sai daí é único e serve para tudo: encontrar o menor conjunto de tokens de alto sinal que maximiza a chance do resultado desejado. Minimal não quer dizer curto.

como funciona

No system prompt, a recomendação é acertar a “altitude”. Dois modos de falha: lógica if-else hardcoded em prosa, que é frágil e cara de manter; e orientação vaga demais, que assume contexto compartilhado que não existe. Entre os dois, heurística específica o suficiente para guiar e flexível o suficiente para o modelo decidir. Organizar em seções com tag XML ou heading Markdown ajuda, mas o post diz que a formatação exata importa cada vez menos.

Em tools, o modo de falha mais comum citado é conjunto inchado, com funcionalidade sobreposta e ponto de decisão ambíguo. O teste é direto: se um engenheiro humano não consegue dizer qual tool usar numa dada situação, o agente também não vai. Em exemplos, few-shot continua valendo, mas o conselho é curar poucos casos canônicos e diversos em vez de empilhar edge case.

Para buscar dado, o movimento é do retrieval por embedding feito antes da inferência para o just-in-time: o agente carrega identificadores leves e resolve na hora, via tool. O Claude Code faz análise sobre base grande escrevendo query dirigida, guardando resultado e usando head e tail — sem nunca puxar o objeto inteiro para o contexto. O caminho do arquivo já é sinal: test_utils.py em tests/ significa outra coisa que o mesmo nome em src/core_logic/.

Para tarefa longa, três técnicas. Compaction: resumir a conversa perto do limite e reiniciar a janela com o resumo. No Claude Code, o modelo preserva decisão de arquitetura, bug não resolvido e detalhe de implementação, descarta saída de tool redundante, e o agente segue com o contexto comprimido mais os cinco arquivos acessados por último. Structured note-taking: o agente escreve notas fora da janela e as relê depois — um NOTES.md, uma to-do list. Sub-agentes: cada um explora com janela limpa gastando dezenas de milhares de tokens e devolve de 1.000 a 2.000 tokens de resumo destilado.

o que isso custou

Explorar em runtime é mais lento que ler dado pré-computado. E exige engenharia opinativa: sem tool e heurística boas, o agente desperdiça contexto usando ferramenta errada, perseguindo beco sem saída ou não reconhecendo o que importa. Por isso o post recomenda híbrido — no Claude Code, CLAUDE.md entra na marra logo de início, enquanto glob e grep cobrem o just-in-time.

Compaction tem custo próprio e explícito: compactar agressivo demais perde contexto sutil cuja importância só aparece depois. A receita de ajuste é maximizar recall primeiro e cortar supérfluo depois. Limpar resultado de tool já consumido é a forma mais leve e segura.

O post também não promete que janela maior resolve. Diz o contrário: contexto de qualquer tamanho continuará sujeito a poluição e a problema de relevância. E as próprias técnicas são datadas por construção — modelo mais capaz precisa de menos engenharia prescritiva, e o conselho que sobrevive é “faça a coisa mais simples que funciona”.

onde isso aparece hoje

As técnicas já viraram produto no ecossistema da própria Anthropic: limpeza de resultado de tool foi lançada como feature na Claude Developer Platform, e uma memory tool baseada em arquivo saiu em beta público junto com o Sonnet 4.5, para guardar estado de projeto entre sessões. O padrão multi-agente descrito aqui é o mesmo do sistema de pesquisa da casa, que segundo o post teve melhora substancial sobre single-agent em tarefa de pesquisa complexa.

O exemplo mais legível do que memória externa faz é o Claude jogando Pokémon: sem instrução sobre como estruturar memória, o agente monta mapa das regiões exploradas, mantém contagem através de milhares de passos e retoma sequências de várias horas lendo as próprias notas depois do reset de contexto.

lido na íntegra por pipeline de llm, revisado por antonio leandro antes de publicar ·