Contexto Passivo Vence: Por Que AGENTS.md Supera Skills em Avaliações de Agentes de IA

A Vercel conduziu um experimento. Testaram diferentes estratégias de documentação para agentes de IA trabalhando com APIs do Next.js 16. Os resultados desafiam uma suposição comum sobre como devemos alimentar informação aos agentes.

Os números contam uma história clara:

Abordagem	Taxa de Aprovação
Baseline (sem documentação)	53%
Skills com comportamento padrão	53%
Skills com instruções explícitas	79%
Índice de documentação AGENTS.md	100%

A abordagem baseada em skills teve desempenho idêntico a não ter documentação alguma. Por quê?

O Problema Real: Skills Nunca São Chamados

Em 56% dos casos de avaliação, o agente nunca invocou o skill que precisava. A informação existia. O mecanismo funcionava. Mas o agente não decidiu usá-lo.

Este é o problema de ativação. Quando informação requer uma decisão para ser acessada, agentes frequentemente falham em tomar essa decisão. Não porque lhes falta capacidade, mas porque escolher recuperar contexto é, em si, um passo de raciocínio que pode falhar.

Pense nisso: o agente deve primeiro reconhecer que precisa de informação, depois decidir qual skill invocar, depois processar a resposta, depois continuar raciocinando. Cada passo é um ponto de falha potencial. Em produção, esses pontos de falha se acumulam.

Por Que Contexto Passivo Vence

AGENTS.md adota uma abordagem diferente. Em vez de exigir que o agente recupere ativamente a documentação, ele incorpora um índice comprimido diretamente no prompt do sistema. A informação está presente em cada turno.

Três características tornam isso efetivo:

Nenhuma decisão de ativação necessária. O agente não precisa reconhecer que precisa de ajuda. O contexto já está lá. Isso elimina uma categoria inteira de falhas.

Acessibilidade consistente. Seja a tarefa simples ou complexa, seja o agente no turno dois ou no turno vinte, o índice de documentação permanece no prompt. Não há variabilidade no acesso.

Sem problemas de sequenciamento. Com skills, agentes enfrentam um dilema: explorar o projeto primeiro, depois ler docs? Ou ler docs primeiro, depois explorar? Isso cria falhas de timing onde agentes mergulham na implementação antes de entender as APIs. Contexto passivo contorna isso inteiramente.

O Problema da Compressão

Documentação bruta não cabe em prompts de sistema. Os docs do Next.js que a Vercel testou tinham 40KB. Eles comprimiram para 8KB — uma redução de 80% — usando uma estrutura delimitada por pipe.

O alvo eram APIs do Next.js 16 que existem fora dos dados de treinamento do modelo:

• connection()
• diretiva 'use cache'
• cacheLife()
• cacheTag()
• forbidden()
• unauthorized()
• cookies() e headers() assíncronos

Essas APIs são novas. Modelos não podem confiar em conhecimento pré-treinado. Documentação é essencial.

A estratégia de compressão importa. Formatos delimitados por pipe são mais densos que markdown. Cada token conta quando você está competindo por espaço em uma janela de contexto finita.

Princípios de Context Engineering da Anthropic

Isso se alinha com como a Anthropic enquadra context engineering: encontrar o menor conjunto possível de tokens de alto sinal que maximizam a probabilidade do resultado desejado.

Eles distinguem duas abordagens:

Pré-computação (passivo): Recuperação baseada em embedding traz toda informação relevante antecipadamente. O agente começa com tudo que precisa. Custo: prompts maiores. Benefício: sem falhas de recuperação.

Just-in-time (ativo): Agentes mantêm identificadores leves e recuperam detalhes dinamicamente quando necessário. Custo: recuperação pode falhar. Benefício: prompts menores.

O Claude Code usa um modelo híbrido. CLAUDE.md carrega imediatamente no contexto. Mas o agente também tem ferramentas grep e glob para exploração em tempo de execução. O contexto base está sempre presente; detalhes adicionais são buscados sob demanda.

O experimento da Vercel sugere que o equilíbrio deve pender para pré-computação, pelo menos para documentação crítica. O custo de contexto sempre presente é menor que o custo de falhas de recuperação.

Recomendações Práticas

Se você está construindo sistemas que dependem de agentes de IA entenderem documentação:

Não confie em skills como seu mecanismo principal de entrega. Skills funcionam quando agentes decidem invocá-los. Em 56% dos casos, não decidem. Essa não é uma taxa de falha aceitável para sistemas em produção.

Comprima agressivamente. A diferença entre 40KB e 8KB é a diferença entre caber no contexto e não caber. Use formatos estruturados. Remova prosa. Mantenha sinal.

Construa suítes de avaliação mirando APIs fora dos dados de treinamento. Se seu agente parece saber algo sem documentação, pode estar confiando em dados de treinamento que ficarão desatualizados. Teste com APIs novas para validar sua estratégia de documentação.

Estruture documentação para recuperação direta de arquivos em vez de carregamento antecipado. Quando você precisar de recuperação ativa, torne o alvo claro. Caminhos de arquivo, não descrições. O agente deve saber exatamente o que buscar.

Considere a taxa de ativação. Toda vez que você exige que um agente decida recuperar informação, você paga uma taxa em confiabilidade. Às vezes essa taxa vale a pena. Frequentemente, não vale.

Implementação

A Vercel fornece um codemod para gerar AGENTS.md para projetos Next.js:

npx @next/codemod@canary agents-md

Isso cria um índice de documentação comprimido específico para APIs do Next.js 16. A abordagem generaliza: qualquer conhecimento específico de framework que agentes precisam de forma confiável deve viver em contexto passivo, não atrás de uma invocação de skill.

A Lição Maior

A abordagem baseada em skills parece elegante. Defina capacidades. Deixe o agente escolher. Confie em seu julgamento.

Mas o julgamento de agentes tem limites. Reconhecer quando usar um skill requer meta-cognição que modelos atuais lidam de forma inconsistente. A decisão de ativação é, em si, um passo de raciocínio, e passos de raciocínio falham.

Contexto passivo é menos elegante mas mais confiável. A informação está sempre lá. Nenhuma decisão necessária. Nenhum modo de falha em torno de “devo consultar isso?”

Isso mapeia para um princípio mais amplo em design de sistemas: reduza opcionalidade em pontos onde opcionalidade introduz falha. Dê ao agente menos escolhas para fazer, e ele comete menos erros.

A comparação de 100% vs 53% é gritante. Quando estratégia de documentação sozinha dobra sua taxa de aprovação, você encontrou um ponto de alavancagem que vale otimizar.

---

Na Victorino Group, projetamos sistemas de agentes de IA que funcionam de forma confiável em produção. Estratégia de contexto é uma das alavancas que determina se agentes têm sucesso ou falham. Se você está construindo com agentes de IA e confiabilidade importa, vamos conversar.