- Na avaliação voltada para a API do Next.js 16, o índice de documentação
AGENTS.md incluído na raiz do projeto registrou maior precisão do que a abordagem baseada em skills
- Skills são um tipo de pacote de conhecimento de domínio que o agente chama quando necessário, mas como a invocação é instável, a taxa de aprovação na configuração padrão ficou em 53%
- Em contraste, o índice
AGENTS.md compactado para 8 KB alcançou 100% de aprovação em todos os testes (Build, Lint, Test)
- Essa abordagem mostrou resultados mais estáveis do que a invocação ativa devido à eliminação de pontos de decisão, disponibilidade constante e resolução de problemas de ordem
- Mantenedores de frameworks podem incluir um índice de documentação compatível com a versão no AGENTS.md para aumentar a precisão da geração de código
Contexto do problema
- Agentes de IA para programação têm a limitação de que os dados de treinamento são baseados em APIs antigas, o que dificulta lidar corretamente com frameworks mais recentes
- Recursos do Next.js 16 como
'use cache', connection() e forbidden() não existem nos dados de treinamento anteriores do modelo
- Por outro lado, em projetos com versões antigas, o modelo também pode sugerir APIs novas que na verdade não existem
- Para resolver isso, foi testada uma abordagem de acesso à documentação compatível com a versão
Duas abordagens
- Skills: um pacote em padrão aberto que reúne prompts, ferramentas e documentação, usado pelo agente quando necessário
AGENTS.md: um arquivo de contexto persistente localizado na raiz do projeto, sempre disponível em todos os turnos da conversa- As duas abordagens foram avaliadas em comparação com base na mesma documentação do Next.js
Limitações da abordagem com Skills
- Na avaliação, em 56% dos testes a skill não foi chamada, e a taxa de aprovação padrão ficou em 53%, sem melhora
- Em alguns itens, houve até pontuação pior que a linha de base (ex.: teste 58% vs 63%)
- Isso foi apontado como um limite atual dos modelos, que ainda não conseguem usar ferramentas de forma estável
Experimento com instruções explícitas
- Ao adicionar ao
AGENTS.md uma instrução explícita dizendo “chame a skill antes de escrever código”, a taxa de aprovação subiu para 79%
- No entanto, pequenas diferenças na formulação da instrução tiveram grande impacto no resultado
- “Chame a skill primeiro” → o modelo ficou preso ao padrão da documentação e perdeu o contexto do projeto
- “Explore o projeto e depois chame a skill” → resultado melhor
- Por causa dessa fragilidade linguística, a confiabilidade em uso real continua baixa
Construção de uma avaliação confiável
- Os testes iniciais tinham baixa confiabilidade por causa de prompts ambíguos e problemas de validação duplicada
- Isso foi aprimorado com validação baseada em comportamento e testes focados em APIs do Next.js 16 ausentes do treinamento
- Principais APIs testadas:
connection(), 'use cache', cacheLife(), forbidden(), proxy.ts, cookies(), headers(), after(), refresh() etc.
Experimento com a abordagem AGENTS.md
- O processo de escolha do agente foi removido, e o índice de documentação foi inserido diretamente no AGENTS.md
- O índice não continha a documentação completa, mas sim uma lista de caminhos da documentação por versão
- Instrução adicional:
IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Next.js tasks.
- Isso orienta o modelo a priorizar raciocínio baseado em documentação em vez de dados prévios de treinamento
Resultado da avaliação
- Com a inserção do índice no AGENTS.md, foi alcançada uma taxa de aprovação de 100%
- Build, Lint e Test tiveram resultados perfeitos
- Estatísticas comparativas:
- Baseline 53%, Skill padrão 53%, Skill + instrução 79%, AGENTS.md 100%
- Motivos pelos quais a abordagem de contexto passivo supera a invocação ativa
- Não há ponto de decisão — a informação está sempre presente
- Disponibilidade consistente — incluída no prompt do sistema em todos os turnos
- Elimina problemas de ordem — não depende da sequência de exploração da documentação
Solução para o problema de capacidade de contexto
- O índice inicial tinha 40 KB, mas foi reduzido para 8 KB com compressão (queda de 80%)
- Com uma estrutura separada por pipe (
|), os caminhos e nomes de arquivos da documentação foram armazenados usando o mínimo de espaço
- O agente lê apenas os arquivos necessários no diretório
.next-docs/ para usar informações exatas da versão correta
Como aplicar
Implicações para desenvolvedores de frameworks
- Skills continuam úteis, mas para melhorar a precisão geral da geração de código, a abordagem com AGENTS.md é mais eficaz
- Skills são mais adequadas para fluxos de trabalho voltados a tarefas específicas, como “upgrade de versão” e “migração para App Router”
- Recomendações:
- não esperar melhorias nas skills e usar AGENTS.md imediatamente
- incluir apenas o índice da documentação para minimizar o contexto
- validar com testes focados em APIs ausentes dos dados de treinamento
- projetar a documentação com uma estrutura de busca detalhada
- O objetivo é migrar do raciocínio centrado em pré-treinamento para o raciocínio baseado em recuperação, e o
AGENTS.md é a forma mais estável de implementar isso
4 comentários
Usando o Context7, esse problema acaba sendo resolvido até certo ponto.
https://context7.com
É porque o context7 é ineficiente, então usam os dois métodos acima...
Entendo o que você quer dizer, mas ainda assim não me parece uma escolha tão ruim usar o context7 como apoio, em vez de ter que organizar e inserir um por um, toda vez, no AGENTS.md ou no Skills, os links da documentação mais recente de todos os frameworks/bibliotecas usados no momento.
Além disso, nem o GeekNews nem o texto da Vercel mencionam o context7. Estou deixando esta resposta porque me parece que o senhor interpretou o conteúdo meio passo à frente.
(Como observação, é um fato bem conhecido que um Skills ou AGENTS.md bem escritos podem economizar tokens, e eu também sei disso muito bem.)
Comentários do Hacker News
O modelo não é AGI. É apenas um gerador de texto, treinado para produzir efeitos como editar arquivos ou chamar ferramentas
O modelo não usa skills por “entender” a habilidade do usuário, mas gera esse texto graças ao aprendizado por reforço (RL) baseado em exemplos criados por humanos e logs de uso
O motivo de não usar skills sempre é que ainda não houve treinamento suficiente com esses casos. Forçar isso com RL pode até deixar o modelo mais burro
No momento, estamos acumulando logs de uso de skills para que modelos futuros aprendam melhor quando devem usá-las
O AGENTS.md é simplesmente contexto. O modelo foi treinado desde o início para seguir contexto
O frontmatter das skills também acaba incluído no contexto, então, se AGENTS.md funciona melhor, isso se deve à diferença na forma como a informação da skill é extraída e injetada
Alguns agentes podem usar modelos menores (ex.: Haiku) para decidir quais informações de skill devem ser passadas a modelos maiores (ex.: Sonnet, Opus)
No fim, o ponto central é quais informações entram no “prompt bruto”
É útil, mas não é perfeito. A própria tecnologia GPT parece já ter entrado em uma fase de estagnação de desempenho
O que deve melhorar daqui para frente são sistemas auxiliares como skills. Mas a funcionalidade de skills, como está implementada hoje, é inferior a usar AGENTS.md diretamente
Na avaliação, houve um resultado mostrando que, em 56% dos casos, as skills não foram chamadas nem uma vez. Ou seja, o modelo tinha a documentação, mas não a usou. Daí a piada: “Passou no teste de Turing...”
A diferença é que a IA aceita instruções de correção sem ego
Ainda não está no nível de um desenvolvedor sênior, mas tende a seguir instruções melhor que um júnior
A descoberta principal é que a compressão (compression) de ponteiros para documentos é eficaz
Para humanos é difícil de ler, mas para LLMs é uma estrutura de referência direta e eficiente
No futuro, em vez de heurísticas como agents.md/claude.md/skills.md, é bem possível que um formato de índice comprimido sempre carregado se torne padrão
Também seria possível reaproveitar suítes de teste de API para validar o desempenho de código gerado por LLM
À medida que a adoção de LLMs crescer, bibliotecas e APIs também terão de evoluir para isso
No Antigravity (= baseado em GEMINI.md), foi configurado para seguir regras do AGENTS.md, mas isso foi ignorado
Em vez disso, o prompt “verifique se o projeto tem AGENTS.md” sempre funcionou
É um fenômeno curioso, parecido com a época em que “let’s think step by step” induzia chain-of-thought
Se AGENTS.md for incluído diretamente no prompt de sistema, ele sempre entra no contexto
Mas incluir todas as skills toda vez é desperdício. Por isso, é necessária uma abordagem de carregar só quando preciso, como o advanced tool use da Anthropic
No fim, é uma questão de equilíbrio entre contexto e custo. Se houver folga, comprimir isso em AGENTS.md é eficiente
Esse tipo de agente com autogerenciamento de contexto parece que vai evoluir bastante este ano
A taxa de aderência do Claude às skills é baixa
Também estou trabalhando em algo parecido. Quero avaliar como a estrutura de scaffolding do projeto afeta os resultados no Claude Code/Opencode
Mas é difícil comparar porque a forma de teste da Vercel não está clara
AGENTS.md não é algo completamente diferente de skills, e sim uma forma simplificada de skill
O essencial é a qualidade do design da skill, isto é, minimizar o número de etapas até que a IA encontre a informação correta
Quanto menos etapas, menor o acúmulo de erros
E, para reduzir desperdício de tokens, arquivos grandes eu coloco apenas uma vez no prompt de sistema
Sempre que vejo comparações de prompt engineering em blogs, fico curioso para saber se foi executado uma vez só ou várias vezes
LLMs não produzem resultados consistentes nem com a mesma entrada
Muitas vezes dá a sensação de que dados anedóticos estão sendo embalados como se fossem ciência
Mas, quando se faz benchmark com cuidado, quase ninguém lê; quando se faz de qualquer jeito, o tráfego do blog aumenta 9 vezes
O problema é a estrutura de incentivos distorcida
Há métodos melhores que AGENTS.md
Uma opção é criar uma pasta
.context, colocar nela links simbólicos para documentos do projeto (README, documentação de dependências etc.) e fazer com que isso sempre seja carregado no contextoAssim, a LLM já começa com todas as informações de que precisa, o que pode trazer melhora de desempenho e redução de custo
_vendoré bem mais útilA LLM pode analisar o código diretamente e entender como ele funciona
Esta é a experiência que obtive ao criar meu agente customizado
Quando coloquei
read/write_fileno estado e passei a exibi-lo no prompt de sistema, funcionou muito melhorAgora estou tentando provar isso com avaliação quantitativa (evals). Pela sensação, o desempenho está muito bom