Engenharia de contexto

Aula 9

Contexto como recurso finito

A Anthropic define engenharia de contexto como a arte de selecionar o conjunto de tokens que o modelo vê a cada chamada. É uma extensão da engenharia de prompt: enquanto o prompt é o texto que você escreve, o contexto é tudo o que chega ao modelo, incluindo instruções, definições de ferramentas, histórico de mensagens, resultados de ferramentas e arquivos lidos.

O ponto central é que mais contexto não significa melhor desempenho. O artigo chama o fenômeno de context rot: à medida que o número de tokens cresce, a capacidade do modelo de recuperar com precisão uma informação específica cai. A explicação está na arquitetura dos transformers, em que cada token se relaciona com todos os outros, gerando n² relações para n tokens. A atenção do modelo funciona como um orçamento: cada token irrelevante consome parte dele.

O princípio que decorre disso é encontrar o menor conjunto de tokens de alto sinal que maximiza o resultado desejado. Na prática, isso afeta três decisões. O prompt de sistema deve estar na "altitude certa", nem uma lista frágil de regras se-então, nem orientação vaga, e organizado em seções claras. Exemplos few-shot devem ser poucos e canônicos, não uma coleção de casos extremos. E as ferramentas devem formar um conjunto mínimo e sem sobreposição.

A documentação de boas práticas do Claude Code repete a mesma ideia de forma mais direta: a janela de contexto é o recurso mais importante, e o desempenho cai à medida que ela enche. Por isso recomenda /clear entre tarefas e, depois de duas correções frustradas sobre o mesmo problema, recomeçar com um prompt melhor em vez de insistir.

Fontes desta aula: Anthropic: Effective context engineering for AI agents · Claude Code: Best practices

Aula 10

KV-cache, prefixo estável e contexto que só cresce no fim

Yichao "Peak" Ji, da Manus, publicou um dos relatos mais citados sobre engenharia de contexto em produção. O primeiro princípio é econômico: desenhe o harness em volta do KV-cache. Provedores de modelos armazenam em cache o processamento de prefixos já vistos. Se o início do contexto não muda entre chamadas, a próxima chamada reaproveita esse trabalho e fica muito mais barata e rápida. Em agentes, a proporção entre tokens de entrada e de saída é muito alta, porque o histórico inteiro é reenviado a cada passo, então a taxa de acerto do cache é uma das métricas mais importantes.

Daí vêm regras concretas:

• Mantenha o prefixo estável. Um horário com segundos no topo do prompt de sistema invalida o cache em toda chamada.
• Contexto só cresce no fim. Não edite mensagens antigas. Acrescente.
• Serialize de forma determinística. Objetos JSON com chaves em ordem variável quebram o cache sem ninguém perceber.
• Mascare ferramentas em vez de removê-las. Tirar uma ferramenta da lista no meio da execução muda o prefixo e confunde o modelo sobre ações antigas. A Manus prefere restringir quais ferramentas podem ser escolhidas naquele passo.

Duas lições da Manus vão contra a intuição. Primeiro, mantenha os erros no contexto: apagar uma ação que falhou tira do modelo a evidência de que aquele caminho não funciona, e ele tende a repeti-la. Segundo, evite a armadilha do few-shot: se o histórico tem muitas ações parecidas, o modelo passa a imitá-las mecanicamente. Pequenas variações estruturadas na forma de registrar ações e observações quebram esse padrão.

Fontes desta aula: Manus: Context Engineering for AI Agents

Aula 11

Compactação, notas estruturadas e o sistema de arquivos como memória

Tarefas longas inevitavelmente ultrapassam a janela de contexto. A Anthropic descreve três técnicas para esse horizonte longo:

A Manus leva a ideia das notas ao extremo: trata o sistema de arquivos como contexto ilimitado e restaurável. Em vez de manter uma página web inteira no histórico, o agente guarda a página em arquivo e mantém só a URL. Em vez de carregar um documento longo, mantém o caminho. A compressão é reversível, porque o conteúdo pode ser lido de novo quando necessário. Addy Osmani recomenda o mesmo para saídas grandes de ferramentas: gravar em arquivo e devolver ao modelo um resumo com o caminho.

Outra técnica da Manus é a recitação: em tarefas com dezenas de passos, o agente reescreve um arquivo todo.md a cada etapa, marcando o que concluiu. Isso empurra o objetivo para o fim do contexto, onde a atenção do modelo é mais forte, e reduz a deriva em relação à meta original.

Por fim, a Anthropic recomenda recuperação no momento certo em vez de carregar tudo de antemão. O Claude Code usa um modelo híbrido: o CLAUDE.md é carregado no início, e o restante é buscado sob demanda com glob e grep. É o mesmo achado do estudo de onze harnesses: busca determinística no lugar de banco vetorial.

Fontes desta aula: Anthropic: Effective context engineering for AI agents · Manus: Context Engineering for AI Agents · Addy Osmani: Agent Harness Engineering

Aula 12

Divulgação progressiva com Agent Skills

Uma skill é uma pasta com um arquivo SKILL.md, que pode trazer também scripts, modelos e documentos de referência. O arquivo começa com um cabeçalho YAML com dois campos obrigatórios, name e description. A ideia que torna as skills eficientes é a divulgação progressiva, em três níveis:

1. Nível 1: só o nome e a descrição de cada skill entram no prompt de sistema no início da sessão. Custa poucas linhas por skill.
2. Nível 2: quando a tarefa parece relevante, o agente lê o SKILL.md completo.
3. Nível 3 em diante: arquivos auxiliares, como um reference.md ou um forms.md, só são lidos se a tarefa exigir.

.claude/skills/
  relatorio-mensal/
    SKILL.md          # name + description + passo a passo
    assets/modelo.md  # modelo que o agente preenche
    references/       # exemplos aprovados, lidos só se necessário
    scripts/gerar.py  # código determinístico executado, não lido

Skills também podem trazer código executável. No exemplo da Anthropic, a skill de PDF inclui um script que extrai campos de formulário: o agente executa o script sem precisar carregá-lo no contexto, o que é mais barato e mais confiável do que pedir ao modelo para fazer a extração. Isso é um padrão recorrente de harness: empurrar para código determinístico tudo o que não precisa de julgamento.

As recomendações de autoria são diretas: comece pelas lacunas observadas em avaliações, divida arquivos grandes, capriche no nome e na descrição (são eles que decidem quando a skill é ativada) e peça ao agente que registre o que funcionou e reflita sobre o que falhou. Como skills podem executar código, instale apenas de fontes confiáveis e audite o conteúdo. No estudo de onze harnesses de produção, skills no formato SKILL.md já aparecem em nove deles.

Fontes desta aula: Anthropic: Equipping agents with Agent Skills · Barbaste et al.: Harness Engineering (arXiv)

Erros comuns

• Despejar o repositório inteiro no contexto. Mais tokens diluem a atenção. Deixe o agente buscar o que precisa.
• Timestamp ou dados variáveis no topo do prompt. Invalidam o cache em toda chamada e multiplicam o custo.
• Apagar erros do histórico para "limpar" o contexto. O modelo perde a evidência e repete o erro.
• Uma sessão para tudo. Misturar tarefas sem relação na mesma conversa enche a janela de ruído. Use /clear entre tarefas.
• Skills com descrição vaga. Se a descrição não diz quando usar, a skill não é ativada na hora certa.

Aplicação prática

1. Meça quantos tokens seu agente já consumiu antes de ler a tarefa (prompt de sistema, ferramentas, instruções). Esse é o seu custo fixo por sessão.
2. Encontre algo variável no início do contexto (data, hora, ID de sessão) e mova para o fim.
3. Transforme um procedimento que você repete com o agente em uma skill com SKILL.md, um modelo em assets/ e um exemplo em references/.
4. Em uma tarefa longa, peça ao agente que mantenha um todo.md atualizado e compare a deriva com uma execução sem ele.

Siglas usadas neste módulo

KV-cache:

Key-Value cache, armazenamento do processamento de prefixos já vistos pelo modelo.

YAML:

Formato de texto para dados de configuração, usado no cabeçalho do SKILL.md.

URL:

Uniform Resource Locator, endereço de um recurso na web.

JSON:

JavaScript Object Notation, formato de dados em texto.

PDF:

Portable Document Format, formato de documento.