Next.js 16.2 empezó a incluir su documentación completa, en Markdown, dentro del paquete instalado. create-next-app también crea un archivo AGENTS.md que indica a los agentes de código que consulten node_modules/next/dist/docs/ antes de escribir. En las evaluaciones publicadas por Vercel, esa combinación obtuvo una tasa de aprobación del 100%, mientras los enfoques basados en skills llegaron como máximo al 79%.
El resultado llama la atención, pero la arquitectura que lo explica es más útil que el marcador. El framework puso contexto correcto, local y compatible con la versión en el camino habitual del agente. La herramienta deja de depender de dos supuestos frágiles: que el modelo detecte su propia duda y que busque la fuente correcta antes de responder.
La recuperación puede fallar antes de buscar
Una skill bajo demanda ahorra contexto mientras permanece cerrada. El diseño funciona si el agente reconoce cuándo debe abrirla. Muchos errores de código aparecen sin una señal explícita de incertidumbre. El modelo conoce una API antigua, genera una respuesta verosímil y continúa. Desde su perspectiva, no existe una razón clara para investigar.
El problema es frecuente en frameworks con ciclos rápidos. Una convención cambia entre versiones, una opción adquiere otro comportamiento o un patrón antiguo conserva validez sintáctica aunque ya no sea el camino recomendado. El conocimiento de entrenamiento no ofrece la misma garantía que el paquete registrado en el lockfile.
El AGENTS.md de Next.js contiene una regla breve: leer la documentación relevante antes de trabajar. El contenido pesado queda en archivos locales y se abre según la tarea. La instrucción permanece visible sin llenar la ventana de contexto con el manual completo.
Esta separación combina disponibilidad con carga progresiva. El índice indica dónde vive la fuente; los documentos aportan el detalle. El equipo no necesita copiar páginas a una wiki paralela ni confiar en una consulta de internet que puede devolver otra versión.
La versión forma parte del contexto
La documentación incluida convierte package-lock.json u otro lockfile en un ancla también para el conocimiento del agente. Si el proyecto usa Next.js 16.2, el texto instalado describe 16.2. Al actualizar el paquete cambia la referencia. Al revertir un commit, código y documentación vuelven a la misma combinación.
Esto pesa especialmente en mantenimiento. Un agente puede trabajar en dos repositorios durante el mismo día, cada uno con una versión diferente. Una búsqueda genérica de "Next.js cache" no conserva esa diferencia automáticamente. La ruta dentro de node_modules sí.
También hay una ventaja operativa: el trabajo continúa en sandboxes sin red. Los entornos de CI, runners aislados y agentes sin salida a internet todavía pueden consultar la referencia. Durante una revisión queda registrada la fuente exacta sin depender del estado actual de un sitio externo.
Incluir documentación aumenta el tamaño de distribución. En un framework, ese peso suele ser pequeño frente a las dependencias de desarrollo y al beneficio de consistencia. La cuenta puede cambiar en bibliotecas mínimas o entornos que distribuyen node_modules en artefactos limitados. Conviene medir el paquete publicado, no confundir el tamaño del repositorio con el costo de deploy.
Una evaluación no crea una regla universal
El 100% pertenece al conjunto de pruebas de Vercel y a las configuraciones evaluadas. Demuestra que la estrategia funcionó en ese dominio. No prueba que AGENTS.md siempre supere skills, RAG o MCP en cualquier base de código.
Los mecanismos resuelven problemas distintos. Las instrucciones siempre visibles sirven para invariantes breves: runtime soportado, verificaciones obligatorias, archivos canónicos y límites de seguridad. La documentación local encaja con una referencia estable y versionada. Retrieval sigue siendo útil si el corpus es grande, cambia fuera del ciclo de release o depende de la identidad del usuario. Una skill funciona cuando un procedimiento especializado solo debe ocupar contexto durante una tarea concreta.
Presentarlos como rivales exclusivos crea una elección artificial. Un proyecto puede mantener un AGENTS.md pequeño que apunte a documentos locales, cargar una skill de deploy y consultar una API para conocer el estado actual. La arquitectura mejora cuando cada mecanismo tiene una función explícita.
Cómo aplicar la idea fuera de Next.js
Un equipo puede empezar sin construir una plataforma. Primero enumera lo que un agente necesita saber antes de editar: versión del runtime, comandos de prueba, arquitectura del directorio, fuente de verdad y operaciones prohibidas. Solo ese índice debe vivir en el archivo de instrucciones.
Después, los documentos detallados se mantienen cerca del código que describen. Deben ser fáciles de buscar, tener nombres previsibles y cambiar en el mismo pull request que la implementación. Cuando una regla necesita ejemplos largos, el índice apunta al archivo en lugar de repetirlo.
Por último, el equipo evalúa el diseño con tareas reales del repositorio. Mide corrección, reintentos, consultas y uso de contexto. El resultado agregado de otro framework propone una hipótesis; no sustituye la evidencia local.
Next.js también comenzó a enviar errores del navegador al terminal y presentó herramientas experimentales para inspeccionar aplicaciones en ejecución. Las novedades aplican la misma idea: colocar evidencia donde el agente ya trabaja. El contexto disponible antes del error cuesta menos que reparar código escrito con seguridad para una versión que el proyecto nunca instaló.
Si tu empresa está evaluando algo parecido, escríbeme por LinkedIn o por WhatsApp.
