O Next.js 16.2 passou a incluir sua documentação completa, em Markdown, dentro do pacote instalado. O create-next-app também gera um AGENTS.md que orienta agentes de código a consultar os arquivos em node_modules/next/dist/docs/ antes de escrever. Nos evals publicados pela Vercel, essa combinação chegou a 100% de aprovação, enquanto as abordagens baseadas em skills alcançaram no máximo 79%.
O dado chama atenção, mas a decisão de arquitetura por trás dele é mais útil que o placar. O framework colocou contexto correto, local e compatível com a versão diretamente no caminho normal do agente. A ferramenta deixa de depender de duas hipóteses frágeis: que o modelo perceba sua dúvida e que busque a fonte certa antes de responder.
Retrieval falha antes da busca começar
Uma skill sob demanda economiza contexto quando fica fechada. Esse desenho funciona se o agente reconhecer o momento de abri-la. Muitos erros de código, porém, nascem sem um sinal explícito de incerteza. O modelo conhece uma API antiga, produz uma resposta plausível e segue adiante. Para ele, não há motivo aparente para pesquisar.
Esse problema é comum em frameworks com ciclos rápidos. Uma convenção muda entre duas versões, uma opção passa a ter outro comportamento ou um padrão antigo continua válido sintaticamente, embora deixe de ser o caminho recomendado. Conhecimento de treinamento não carrega a mesma garantia do pacote registrado no lockfile.
O AGENTS.md criado pelo Next.js usa uma regra curta: ler a documentação relevante antes de trabalhar. O conteúdo pesado permanece nos arquivos locais e só é aberto conforme a tarefa. Assim, a instrução fica sempre visível sem despejar toda a documentação na janela de contexto.
Essa separação combina disponibilidade com carregamento progressivo. O índice diz onde está a fonte; os documentos fornecem os detalhes. A equipe não precisa copiar páginas para uma wiki paralela nem confiar em uma consulta à internet que pode retornar outra versão.
Versão é parte do contexto
Documentação embarcada transforma package-lock.json ou outro lockfile em uma âncora também para o conhecimento do agente. Se o projeto usa Next.js 16.2, os textos instalados descrevem 16.2. Ao atualizar o pacote, o material de referência muda junto. Ao voltar um commit, código e documentação voltam para a mesma combinação.
Isso é especialmente importante em manutenção. Um agente pode trabalhar em dois repositórios no mesmo dia, cada um com uma versão diferente. Uma busca genérica por "Next.js cache" não carrega essa distinção automaticamente. O caminho dentro de node_modules carrega.
Há outro ganho operacional: o trabalho continua em sandboxes sem rede. Ambientes de CI, runners isolados e agentes com egress bloqueado ainda podem consultar a referência. A fonte também fica disponível para inspeção e registro durante uma revisão, sem depender do estado de um site externo.
Documentação no pacote tem custo de distribuição e pode aumentar o tamanho instalado. Para frameworks, esse custo tende a ser pequeno perto das dependências de desenvolvimento e do benefício de consistência. A conta muda para bibliotecas mínimas ou ambientes que distribuem node_modules em artefatos apertados. A decisão deve considerar o pacote publicado, não apenas o repositório de documentação.
O eval não prova uma regra universal
O resultado de 100% pertence ao conjunto de testes da Vercel e às configurações avaliadas. Ele demonstra que a estratégia funcionou naquele domínio. Não estabelece que AGENTS.md sempre vence skills, RAG ou MCP em qualquer base de código.
As abordagens resolvem problemas diferentes. Instruções sempre presentes são adequadas para regras curtas e invariantes: versão suportada, comandos obrigatórios, arquivos canônicos e limites de segurança. Documentação local funciona para uma referência relativamente estável e versionada. Retrieval continua útil quando o corpus é grande, muda fora do ciclo de release ou depende da identidade do usuário. Uma skill é boa quando há um procedimento especializado que só deve ocupar contexto durante uma tarefa específica.
O erro é transformar essas peças em concorrentes exclusivos. Um projeto pode manter um AGENTS.md pequeno apontando para documentação local, carregar uma skill para deploy e consultar uma API para estado atual. A arquitetura melhora quando cada mecanismo tem uma função explícita.
Como aplicar fora do Next.js
Uma equipe pode começar sem criar uma plataforma. Primeiro, liste as informações que um agente precisa antes de qualquer alteração: versão do runtime, comandos de teste, arquitetura do diretório, fonte da verdade e operações proibidas. Coloque apenas esse índice no arquivo de instruções.
Depois, mantenha documentos detalhados próximos ao código que descrevem. Eles devem ser pesquisáveis, ter nomes previsíveis e mudar no mesmo pull request da implementação. Quando uma regra precisar de exemplos longos, o índice aponta para o arquivo em vez de repeti-lo.
Por fim, avalie com tarefas reais do repositório. Meça correção, número de tentativas, chamadas de busca e uso de contexto. Um resultado agregado de outro framework orienta uma hipótese; não substitui a medição local.
O Next.js também passou a encaminhar erros do navegador ao terminal e lançou ferramentas experimentais para inspecionar uma aplicação em execução. As mudanças seguem a mesma ideia: colocar evidência onde o agente já trabalha. Contexto disponível antes do erro custa menos que uma correção produzida com confiança sobre uma versão que o projeto nunca instalou.
