Claude Code y Next.js: guía práctica para desarrolladores

Claude Code, iniciado con claude en la carpeta del proyecto, es un agente de terminal que edita archivos, ejecuta comandos y sigue las instrucciones de CLAUDE.md. En un proyecto Next.js destaca porque entiende la estructura de App Router y Pages Router, la frontera entre servidor y cliente y los errores de build. Esta guía cubre cómo configurarlo y usarlo a diario.

Por qué Claude Code encaja con Next.js

Next.js combina muchas superficies: componentes React, funciones de servidor, route handlers, configuraciones y fases de build. Claude Code no solo escribe código; puede leer el árbol del repositorio, ejecutar pnpm lint, pnpm test o pnpm build y corregir lo que falle. Eso lo hace útil para tareas que tocan varios archivos a la vez, como cambiar una API, actualizar los tipos y adaptar los tests. Al trabajar con la configuración de CLAUDE.md, respeta convenciones que en Next.js evitan errores clásicos: no convertir todo en componente de cliente, no tocar next.config.ts sin motivo y usar fetch con las opciones de caché esperadas. También puede ejecutar Playwright contra el servidor de desarrollo, con lo que cubre flujos completos sin salir de la terminal.

Preparar el proyecto para el agente

El agente funciona mejor cuando el repositorio declara sus comandos y convenciones. Crea un archivo CLAUDE.md en la raíz y mantenlo corto, con lo que el agente necesita para no romper el proyecto. Un ejemplo realista para un proyecto con App Router, Vitest y Playwright:

# CLAUDE.md

## Comandos
- Instalación: pnpm install
- Desarrollo: pnpm dev
- Build: pnpm build
- Lint: pnpm lint
- Tests unitarios: pnpm test (vitest run)
- Tests e2e: pnpm test:e2e (playwright test)

## Estructura
- App Router en src/app; no usar pages/.
- Route handlers en src/app/api/**/route.ts.
- Server actions en src/actions/, con validación zod.
- Componentes compartidos en src/components.

## Reglas Next.js
- Componentes de servidor por defecto; añade "use client" solo si hay estado o eventos.
- No importes módulos server-only en componentes client.
- Usa NextResponse.json en route handlers.
- No modifiques next.config.ts sin pedirlo.
- No actualices dependencias salvo petición explícita.
- Si un test falla, no lo borres; explica por qué falla y arréglalo.

Con esto, el agente tiene una referencia para ejecutar las verificaciones correctas antes de dar una tarea por terminada. Si usas Pages Router, adapta la estructura y las reglas; lo importante es que el archivo describa dónde van las páginas, las API y las acciones, y qué comandos validan cada cambio.

Bucle de trabajo

Un flujo que da buenos resultados es:

1. Describe la tarea con el archivo o ruta afectada y el resultado esperado.
2. Pide al agente que primero proponga los cambios y luego los aplique en pasos pequeños.
3. Después de cada cambio, ejecuta pnpm lint y pnpm test.
4. Revisa el diff con git diff y pide ajustes antes de aceptar.
5. Termina con pnpm build para detectar errores que solo aparecen en producción.

El agente rinde mejor con tareas acotadas. Si le pides “arregla la autenticación”, puede tocar demasiados archivos; en cambio, “añade validación de sesión al route handler /api/users y cubre el caso no autenticado con un test” produce un diff revisable. Usa git diff para revisar cada paso y no confíes ciegamente en la salida; pide que explique los cambios que afectan al renderizado, la caché o la seguridad.

Prompts útiles para tareas típicas de Next.js:

• “Añade una ruta /api/health que devuelva { status: 'ok', timestamp } con NextResponse.json y añade un test con Vitest.”
• “Convierte el componente ProductCard para que pueda usar useState; añade ‘use client’ solo en ese archivo y revisa que no importe dependencias de servidor.”
• “Crea un server action en src/actions/posts.ts que valide el título con zod, guarde el post y llame a revalidatePath(‘/posts’).”
• “Refactoriza la página de dashboard para mover el fetch a una función async con caché y maneja el estado de error con un fallback.”
• “Escribe pruebas Playwright para el flujo de login y compra, usando un usuario de prueba; ejecuta solo esos tests.”

Tareas típicas y dónde vigilar

Claude Code resuelve bien: crear route handlers y server actions, pasar datos de servidor a componentes client con props serializables, añadir loaders y skeletons, mover lógica a funciones puras y cubrirlas con tests, y actualizar imports cuando se reorganiza el código.

Los puntos donde hay que vigilar con más atención son:

• Frontera servidor/cliente: el agente puede añadir "use client" a componentes que no lo necesitan para evitar un error, o importar una función server-only dentro de un componente client. Revisa el diff y pide que mueva la lógica al servidor.
• Caché y revalidación: en route handlers y fetch, puede olvidar export const dynamic = 'force-dynamic' o revalidatePath y dejar datos obsoletos.
• Variables de entorno: el agente no debe exponer secretos al cliente; solo debe usar variables con prefijo NEXT_PUBLIC_ en el navegador.
• Configuración frágil: cambios en next.config.ts, middleware.ts o instrumentation.ts pueden alterar el runtime, redirigir tráfico o romper builds. Pide siempre una explicación antes de aceptarlos.
• Tipos y Server Actions: los server actions con TypeScript requieren tipos en los argumentos y en el retorno; el agente a veces los deja any y el build estricto falla.

Pruebas y verificación con Next.js

El agente debe ejecutar las comprobaciones del proyecto después de cada tanda de cambios. La siguiente tabla resume qué cubre cada comando en un proyecto Next.js típico:

Pide al agente que ejecute al menos lint y test en cada iteración. Para e2e, necesita el servidor de desarrollo levantado; puedes pedirle que lance pnpm dev en segundo plano, espere a que esté listo y luego ejecute Playwright. Antes de cerrar una tarea, pnpm build es la prueba más fiel de que el cambio no rompe la compilación de Next.js. Si usas Jest en lugar de Vitest, el agente debe ejecutar el comando definido en CLAUDE.md, no asumir el nombre.

Varios agentes en un proyecto Next.js con AgentVera

AgentVera ejecuta las herramientas reales de varios agentes de línea de comandos, incluido Claude Code, lado a lado en una misma ventana; para Next.js lo más útil es que cada agente puede trabajar en su propio git worktree, evitando que se pisen los archivos cuando uno toca src/app y otro src/actions. La revisión automática de código al terminar cada turno detecta problemas típicos como imports server-only en componentes client, con enlaces a file:line. Los checkpoints permiten deshacer un turno completo y repetir la sesión paso a paso si el agente rompe la frontera servidor/cliente. Eso hace viable paralelizar tareas independientes sin perder control sobre el diff.

Cierre

Con un CLAUDE.md claro y un bucle de revisión basado en lint, tests y build, Claude Code se convierte en un par programador eficaz para Next.js. La clave no está en pedirle funciones gigantes, sino en dividir el trabajo, vigilar la frontera servidor/cliente y dejar que las verificaciones del proyecto confirmen cada paso. Si quieres afinar el flujo, consulta la checklist práctica de Claude Code.