Torne o contexto longo observável

O problema

Um agente é acionado para atualizar uma configuração que aparece em quatro arquivos diferentes de um monorepo com 400 mil linhas. Ele encontra os quatro lugares, mas dois deles têm valores conflitantes — um arquivo diz que o timeout é 30 segundos, outro diz 90. O agente escolhe um dos dois, silenciosamente, sem sinalizar o conflito, e segue em frente. A mudança passa em CI (porque nenhum teste cobre esse conflito específico) e vaza pra produção um comportamento inconsistente que só aparece sob carga.

O agente não "alucinou" nada. Ele tomou uma decisão razoável com informação insuficiente — e o erro real foi não ter sinalizado que a informação era insuficiente. Essa é a distinção que esta lição inteira gira em torno: em contexto grande demais para caber (ou grande demais para uma pessoa revisar linha por linha), a pergunta não é só "o que fazer com o que eu vejo", é "eu deveria decidir sozinho ou isso precisa de uma pessoa".

Proveniência: todo fato carrega uma origem

Em uma tarefa que toca múltiplos arquivos, múltiplas fontes ou múltiplas versões de um dado, cada fato relevante deveria carregar de onde veio e quando foi observado — não só o valor. Um registro como

{
  "fact": "timeout = 90s",
  "source": "config/prod.yaml",
  "observed_at": "2026-08-15",
  "conflicts_with": ["config/staging.yaml: timeout = 30s"]
}

torna um conflito visível e citável em vez de silenciosamente resolvido. A diferença entre um sistema que rastreia proveniência e um que não rastreia é a diferença entre "encontrei um conflito, aqui estão as duas fontes" e "decidi por um dos dois valores e ninguém vai saber que havia um segundo".

Datas de observação importam pela mesma razão: um fato lido de um arquivo há três meses pode estar desatualizado, e sem registrar quando cada fato foi observado, não existe forma de distinguir "informação atual" de "informação que já mudou e ninguém percebeu".

Não aumente o contexto, torne-o navegável

O instinto mais comum diante de um código grande demais é tentar caber tudo na janela de contexto de uma vez. Isso raramente funciona bem, e mesmo quando cabe tecnicamente, o modelo perde precisão em informação posicionada no meio de um contexto muito longo (o efeito clássico de "lost in the middle"). As ferramentas certas para esse problema não são "mais contexto", são estrutura:

• Scratchpads — um espaço de trabalho externo onde o agente registra descobertas intermediárias, para não precisar re-derivar o mesmo fato repetidamente dentro da mesma janela.
• Manifestos — um índice estruturado (que arquivo faz o quê, onde cada configuração relevante vive) que substitui "ler tudo" por "consultar o índice e ler só o que importa".
• Compactação — resumir e descartar deliberadamente o que já não é mais necessário para a tarefa atual, em vez de deixar o contexto crescer sem limite.
• Subagentes com contexto isolado — quando uma sub-tarefa exige investigar uma parte grande do código, delegar a um subagente que investiga isoladamente e devolve um resumo estruturado evita que a exploração completa polua a sessão principal.

O padrão de decisão a memorizar: contexto grande não é resolvido aumentando o limite, é resolvido decidindo o que realmente precisa estar na janela agora — o resto vive em algo consultável.

Calibrar quando escalar

Nem toda ambiguidade deveria ser resolvida silenciosamente pelo agente, e nem toda ambiguidade deveria travar o trabalho esperando um humano. O critério prático:

• Decidir sozinho quando o custo de errar é baixo e reversível (uma escolha de formatação, uma convenção de nomenclatura sem consequência funcional).
• Escalar quando dois fatos conflitam sobre algo que afeta comportamento em produção, quando a decisão é difícil de reverter, ou quando a confiança no fato é baixa e a consequência de errar é alta.

O erro do cenário de abertura foi decidir sozinho um caso que deveria ter sido escalado — um conflito de configuração de produção, silenciosamente resolvido, sem nenhum registro de que a decisão foi tomada sob incerteza.

Coloque em prática

O laboratório desta lição implementa um rastreador de proveniência que recebe fatos de múltiplas fontes, detecta conflitos automaticamente e decide — com base em critérios explícitos de risco e reversibilidade — se cada conflito pode ser resolvido automaticamente ou precisa ser escalado para revisão humana.