Aula 3
Engenharia de contexto e decomposição de tarefas
O exercício da aula 2
- Quantos passos o laço levou com a descrição boa, e quantos com
"faz uma consulta" - O modelo continuou escolhendo a ferramenta certa, ou chamou a outra
- Em algum caso ele bateu no
MAX_PASSOSsem concluir
A descrição da tool não é documentação para humano. Ela é contexto, e o modelo relê esse texto a cada volta do laço.
O laço tem um efeito colateral
A cada volta, três coisas entram no histórico e nenhuma sai sozinha:
volta 1: pedido do usuário + chamada de tool + resultado da tool
volta 2: raciocínio + chamada de tool + resultado da tool
volta 3: raciocínio + chamada de tool + resultado da tool (80 mil tokens de log)
...
- O agente da aula 2 parava no
MAX_PASSOS. O contexto, não: ele cresce em toda iteração - A pergunta desta aula é quem decide o que continua ali dentro, e com base em quê
Engenharia de contexto
O conjunto de estratégias para curar e manter os tokens úteis durante a inferência do modelo.
- Contexto é tudo que entra na janela: instruções do sistema, tools, dados externos, histórico de mensagens, arquivos lidos
- O termo em inglês é context engineering, e a Anthropic o trata como a evolução natural da engenharia de prompt
- Engenharia de prompt escreve bem uma vez. Engenharia de contexto decide, a cada volta do laço, o que continua na janela
anthropic.com/engineering/effective-context-engineering-for-ai-agents
Prompt engineering e context engineering
Fonte: Anthropic, Effective context engineering for AI agents (2025). anthropic.com/engineering/effective-context-engineering-for-ai-agents
Por que não colocar tudo dentro
Context rot
Quanto mais tokens na janela, menor a precisão do modelo para recuperar uma informação específica. A queda é gradual, e varia de modelo para modelo
Orçamento de atenção
O modelo tem algo parecido com memória de trabalho. Cada token novo consome parte desse orçamento
Não existe um ponto onde o modelo quebra. Existe perda de precisão que cresce com o tamanho da janela.
A anatomia do contexto
System prompt
Organizado em seções, com marcação em XML ou Markdown: informação de fundo, instruções, orientação sobre tools.
Tools
O contrato entre o agente e o ambiente. Autocontidas, com pouca sobreposição entre si e parâmetros sem ambiguidade.
Exemplos
Poucos casos canônicos e diversos, no lugar de um catálogo de casos de borda.
Para o modelo, exemplo vale como imagem
Histórico
O que já foi dito e feito. É a parte que cresce sem pedir licença, e a primeira que precisa de poda.
A recomendação da Anthropic para o conjunto: informativo, e ao mesmo tempo enxuto.
A altitude certa
Baixa demais
Lógica de if e else escrita à mão para cada caso. Frágil, cara de manter, e quebra no primeiro cenário não previsto.
Alta demais
Orientação vaga, sem sinal concreto. Presume um entendimento compartilhado que não existe.
A altitude certa
Específica o bastante para guiar o comportamento, flexível o bastante para servir de heurística em situação nova.
Esse é o mesmo problema que vocês vão enfrentar no AGENTS.md do projeto, e na semana que vem nas skills.
O que dar e o que omitir
- Dar: o arquivo que será alterado, as convenções do projeto, o teste que deve passar
- Omitir: a base inteira, histórico irrelevante, três tentativas fracassadas
- As convenções entram uma vez, no
AGENTS.md, e não a cada pedido
Tarefa grande não é uma tarefa
Por que 'construa o sistema de reservas' falha e 'adicione o endpoint POST /reservas com validação de conflito' funciona?
- Tarefa grande tem critério de sucesso ambíguo
- Sem critério, o agente escolhe um por você
- Fatie até cada pedaço ter um teste que diz se acabou
Três técnicas para tarefa longa
Compactação
Resumir a conversa perto do limite da janela e recomeçar com o resumo no lugar do histórico.
compaction, o /compact do Claude Code. Preserva decisão de arquitetura e bug aberto, descarta saída bruta de ferramenta
Anotação estruturada
O agente escreve notas em arquivo, fora da janela, e relê quando precisa.
memória agêntica: NOTES.md, lista de tarefas. No exemplo da Anthropic com Pokémon, o agente atravessou 1.234 passos de treino sem perder a conta
Sub-agentes
Cada subtarefa roda em uma janela limpa e devolve só o resumo: dezenas de milhares de tokens de exploração viram de mil a dois mil de resposta.
Compactação para tarefa com muita ida e volta, anotação para trabalho que atravessa sessões, sub-agentes para exploração em paralelo.
Exercício: um PR que leva horas
O mesmo exercício da aula passada, agora mirando um PR maior, mais robusto, mais difícil: algo que o agente leve minutos ou horas para executar.
- 1. Escolham no repositório de vocês uma tarefa que não caiba em um pedido: uma refatoração que atravessa vários arquivos, uma migração, uma funcionalidade com testes e documentação
- 2. Antes de pedir qualquer coisa, montem o contexto: um
AGENTS.mdna altitude certa, umNOTES.mdcom o que o agente descobriu lendo o código, e o critério de pronto, isto é, o teste que diz se acabou - 3. Decomponham em passos, com
/clearentre eles, e deixem o agente rodar até o PR ficar de pé - 4. Registrem em
diario/2026-09-15.md: qual contexto vocês forneceram, o que o agente esqueceu no caminho, quantas voltas foram necessárias e o que precisou de correção à mão
Commit no dia. Leitura da semana: Anthropic, Effective context engineering for AI agents. Complementar: Barke, James e Polikarpova, Grounded Copilot, OOPSLA 2023 (arxiv.org/abs/2206.15000).