Agent DevTools de Next.js: depurar con IA en 2026

Lo montas una vez y el agente lee solo los errores de build de Next.js, los metadatos de las rutas y el árbol de componentes de React. Nada de pegar trazas en un chat. El ciclo se cierra en el terminal, donde el agente ya vive, y la documentación que lee corresponde a la versión de Next.js instalada en el proyecto.

Calcula unos veinte minutos. Necesitas Next.js 16.3, un agente que hable MCP y un servidor de desarrollo que puedas dejar encendido. Todo lo que viene es de primera mano: lo publica Vercel y no cuesta nada.

Hicieron falta dos versiones. Next.js 16.2 añadió el Browser Log Forwarding, el archivo AGENTS.md dentro de create-next-app y unas Agent DevTools experimentales apoyadas en una CLI llamada next-browser. Next.js 16.3, publicada el 3 de agosto de 2026, integró next-browser en la CLI generalista agent-browser y hace llegar la documentación a los agentes mediante un bloque AGENTS.md gestionado. En esa misma versión se retiraron las Skills.

Qué necesitas antes de empezar

• Next.js 16.3 o posterior. Con la 16.2 tienes el log forwarding y AGENTS.md, pero la introspección de React se ha movido a agent-browser.
• Un agente que hable MCP: Claude Code, Cursor o cualquier cliente que lea un archivo de configuración MCP.
• Un servidor de desarrollo que puedas mantener encendido. Las herramientas MCP leen un servidor vivo, no el código fuente.
• Permiso de escritura en next.config.ts y en la raíz del repositorio.

Paso 1: pasar a Next.js 16.3

npm install next@latest react@latest react-dom@latest

De la 16.3 aquí importan dos cosas además de las herramientas para agentes. Los agentes leen documentación acorde a la versión sin configurar nada, y las sesiones largas de desarrollo consumen hasta un 90% menos de memoria que antes. El dato de memoria no es un número de escaparate en este caso. Un flujo dirigido por un agente mantiene un único servidor de desarrollo encendido durante horas mientras consulta, edita y vuelve a consultar, que es justo el patrón con el que el proceso se hinchaba.

Paso 2: darle al agente la documentación de tu versión

create-next-app ya crea un archivo AGENTS.md por defecto. Es una directiva breve en Markdown que le dice al agente que lea la documentación incluida en node_modules/next/dist/docs/ antes de escribir código. En un proyecto que ya existe no lo añade nadie, así que créalo en la raíz del repositorio.

Vercel midió la diferencia. Con la documentación incluida en el paquete los agentes llegaron al 100% de aciertos en sus evals de Next.js, mientras que la recuperación por skills se quedó en el 79%. La razón es poco lucida: el agente muchas veces no reconoce el momento en el que debería buscar documentación, así que un contexto siempre presente gana a un contexto que hay que pedir.

El precio es el presupuesto de contexto. La documentación ocupa tokens que el agente podría gastar leyendo el código, así que trata ese bloque como cualquier otra instrucción siempre cargada. Es la misma disciplina que describimos para los archivos CLAUDE.md y para la gestión de la ventana de contexto.

Paso 3: llevar los logs del navegador al terminal

Desde la 16.2 Next.js envía los errores del navegador al terminal durante el desarrollo, y lo hace por defecto. Un agente no abre la consola del navegador. El terminal es la única superficie que lee, y hasta esta incorporación los errores de cliente para él no existían.

// next.config.ts
export default {
  logging: {
    browserToTerminal: 'error',
  },
}

Los niveles son 'error' (el que viene por defecto), 'warn', true para toda la salida de consola y false para apagarlo. Empieza en 'error' y quédate ahí un tiempo. Poner true en una aplicación que escribe un log en cada render llena el terminal y quema el contexto del agente en ruido.

Paso 4: conectar el servidor MCP de las DevTools

Next.js 16 expone un endpoint MCP en /_next/mcp. El paquete next-devtools-mcp localiza los servidores de desarrollo encendidos y hace de proxy hacia ese endpoint, de modo que el agente recibe errores de build, rutas y logs en vivo en lugar del resumen que le escribiste tú.

npx add-mcp next-devtools-mcp@latest

Para Claude Code en concreto:

claude mcp add next-devtools npx next-devtools-mcp@latest

O escribe la configuración a mano, que sirve para cualquier cliente:

{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    }
  }
}

Llegan cuatro herramientas. nextjs_index encuentra los servidores de desarrollo Next.js 16+ activos y dice qué herramientas de runtime expone cada uno. nextjs_call ejecuta get_errors, get_logs o get_page_metadata contra el puerto encontrado. nextjs_docs localiza la documentación que corresponde a la versión instalada. Si ya has construido un servidor MCP para tu SaaS, la forma te resultará familiar.

Paso 5: añadir agent-browser para la introspección de React

npm install -g agent-browser@^0.27

La CLI gestiona una instancia de Chromium con React DevTools ya cargado, así que no hay nada que configurar en el navegador. Cada comando es una petición suelta contra una sesión que se mantiene abierta. El agente consulta la página tantas veces como quiera sin arrastrar el estado del navegador.

Los comandos de React son la mitad que merece la pena aprender. react tree lista el árbol de componentes. react inspect <fiberId> devuelve props y hooks de un componente. react renders start y react renders stop perfilan los re-renders. react suspense --only-dynamic --json muestra qué está reteniendo un render, que es la vía más rápida para entrar en una shell de Partial Prerendering que no termina de resolverse. Capturas de pantalla, peticiones de red, salida de consola y Web Vitals vienen con el paquete. Desde la fusión de la 16.3 la misma CLI funciona en aplicaciones que no son Next.js.

Cómo comprobar que funciona

1. Arranca el servidor de desarrollo y déjalo encendido.
2. Rompe algo a propósito. Basta con un error de tipos en un route handler.
3. Pregúntale al agente qué errores está reportando el servidor. Debería llamar a nextjs_call con get_errors y responderte con archivo y línea, sin pedirte que pegues nada.
4. Pídele la lista de rutas. get_page_metadata devuelve páginas y metadatos de componentes desde la aplicación encendida.
5. Lanza agent-browser react tree contra una página. Tienes que obtener un árbol de componentes con los fiber id listos para pasárselos a react inspect.

Cinco de cinco significa que el ciclo está cerrado. Si falta algo, el apartado siguiente lo cubre.

Fallos frecuentes y cómo se arreglan

• No se encuentra ningún servidor Next.js. nextjs_index necesita un servidor de desarrollo encendido, en Next.js 16 o posterior. Una build de producción no expone /_next/mcp, y un servidor que se cayó hace tres minutos tampoco.
• La herramienta de documentación no devuelve nada. Los archivos están en node_modules/next/dist/docs/. Cualquier paso de instalación que recorte la documentación de los paquetes, algo habitual en capas Docker ligeras y en algunas cachés de CI, se los lleva por delante.
• El agente cita una API que ya no existe. La documentación va atada a la versión instalada, así que después de npm install next@latest reinicia la sesión del agente y deja que lea el conjunto nuevo.
• El terminal es ilegible. Devuelve browserToTerminal de true a 'error'.
• Un segundo servidor de desarrollo no arranca. La 16.2 añadió un archivo de bloqueo del servidor que devuelve un mensaje claro en lugar de una colisión de puertos que hay que descifrar. Cierra el primero.

Por dónde seguir

Este montaje rinde justo donde los agentes flojean: razonar sobre un estado de runtime que no ven. En arquitectura no cambia nada. Un agente que lee get_errors a la perfección sigue metiendo una consulta a la base de datos donde no toca, así que las reglas que impones en revisión pesan igual que antes. Las nuestras las tenemos escritas para las Server Actions en producción y para los Core Web Vitals.

Hay otra actualización que combina bien con esta. next build ya puede comprobar tipos con TypeScript 7, y el compilador en Go acorta la distancia entre la edición del agente y el error que esa edición provoca. Cuanto más corta es esa distancia, menos vueltas cuesta cada arreglo.