Codex con Next.js: guía práctica para desarrolladores

Codex se lanza con codex en la carpeta del proyecto y actúa directamente sobre el repositorio: lee AGENTS.md, edita archivos y ejecuta los comandos que le pidas. Para Next.js, esto significa que puede trabajar con App Router o Pages Router, componentes de servidor y cliente, route handlers y pruebas, siempre que le des un contexto mínimamente estructurado. Puedes empezar con la guía de Codex o con Cómo usar Codex CLI: guía paso a paso.

Por qué Codex encaja en proyectos Next.js

Next.js mezcla convenciones de archivos, límites de ejecución y validaciones de build. Un agente que lee el árbol real, respeta package.json y recuerda las reglas de AGENTS.md reduce la fricción. Codex sirve para tareas repetitivas: migrar imports, renombrar componentes, mover lógica a server components, crear route handlers y ajustar pruebas. El punto fuerte no es que genere código desde cero, sino que modifique el código existente y ejecute las comprobaciones al final. Aun así, conviene que las tareas sean pequeñas y revisables; si le pides un refactor gigante, es fácil que toque demasiados archivos y mezcle responsabilidades.

Prepara el proyecto para el agente

Crea un AGENTS.md en la raíz. Codex lo lee al iniciar la sesión, así que debe contener solo lo que cambia el comportamiento esperado. No hace falta explicar qué es Next.js; escribe los comandos, la estructura de carpetas y reglas concretas de tu stack. Especifica si usas App Router, Pages Router o ambos, y dónde están los tests. Un ejemplo corto:

# AGENTS.md

## Comandos
- Instalar: `npm ci`
- Desarrollo: `npm run dev`
- Build: `npm run build`
- Lint: `npm run lint`
- Test: `npm test`

## Estructura
- `app/`: App Router. Páginas en `page.tsx`, layouts en `layout.tsx`.
- `components/`: componentes React. Si usan hooks o eventos, añade `"use client"`.
- `lib/`: utilidades y acceso a datos. No importarlo desde componentes cliente.
- `types/`: tipos compartidos.

## Reglas Next.js
- No uses `fs`, secretos ni variables solo de servidor en componentes cliente.
- Los server components no pueden usar `useState`, `useEffect` ni handlers de DOM.
- Los route handlers viven en `app/api/`; valida siempre la entrada antes de usarla.
- No modifiques `next.config.*` sin pedírmelo explícitamente.
- Antes de dar una tarea por terminada, ejecuta `npm run lint` y `npm test`.

Añade una sección de “Decisiones” si tienes excepciones: por ejemplo, “las respuestas de API usan zod”, “los nombres de componentes usan PascalCase” o “no uses any”. Eso ayuda más que un documento largo. Si trabajas con Pages Router, indica que las páginas están en pages/ y que las API routes usan pages/api/; así el agente no mezcla convenciones.

Bucle de trabajo con prompts pequeños

Un buen flujo con Codex en Next.js no empieza con “hazlo todo”. Empieza con un plan, deja que el agente lea los archivos relevantes y proponga cambios sin escribir. Después pide pasos pequeños, ejecuta las pruebas, revisa el diff y repite. Al final, comprueba siempre npm run lint, npm test y, si toca rutas o render, npm run build.

Prompts típicos que funcionan:

• “Lee app/dashboard/ y lib/ y propón un plan para mover la obtención de datos de app/dashboard/page.tsx a un server component con loading.tsx y error.tsx. No modifiques archivos todavía.”
• “Crea una server action en app/settings/actions.ts para actualizar el nombre del usuario. Valida con Zod, reutiliza los tipos existentes y no añadas dependencias. Ejecuta npm run lint y npm test.”
• “Convierte components/UserCard.tsx en client component solo si es imprescindible. Si añades "use client", explica qué hooks usas y mantén los datos que vienen de servidor como props.”
• “Añade app/api/webhooks/route.ts para recibir eventos de pago. Valida el cuerpo con Zod, responde 200 rápidamente y deja un TODO claro para verificar la firma. No loguees datos sensibles.”
• “Revisa el diff actual y marca los archivos que afectan al límite servidor/cliente o al sistema de caché antes de que haga commit.”

Cada prompt debería incluir el alcance y la comprobación esperada. Así el agente no borra código por accidente y tú puedes revisar cambios pequeños.

Tareas que hace bien y dónde vigilarlo

La siguiente tabla resume tareas frecuentes, prompts útiles y qué conviene revisar:

Codex rinde bien cuando el cambio es localizado y las reglas están claras. Debes vigilarlo especialmente en:

• Límite servidor/cliente. Es el error más común: añade useState a un server component o importa una utilidad que usa fs en un client component. Revisa siempre los archivos con "use client" y los imports cruzados.
• Caché y render dinámico. Next.js decide estático o dinámico según cookies, headers, searchParams y configuraciones. Si el agente toca esas partes, revisa dynamic, revalidate, unstable_noStore o generación estática.
• Route handlers y server actions. Suelen faltar validación de entrada, control de autenticación o comprobación de errores. No des por bueno un endpoint solo porque pase el lint; prueba con datos malformados.
• Configuración y dependencias. Si el agente cambia next.config.*, tsconfig.json o package.json, pídele justificación y revisa el diff con calma. Un cambio de transpilePackages o de imágenes puede romper el build.
• Mezcla de routers. Si el proyecto convive con App Router y Pages Router, deja claro en AGENTS.md qué carpeta usa cada área; el agente puede crear un page.tsx donde el build espera un pages/.

Pruebas y verificación en Next.js

La verificación debe formar parte del prompt, no ser opcional. Configura al menos npm run lint y npm test; si usas Vitest o Jest, pídele tests unitarios para utilidades y componentes. Para flujos completos, Playwright complementa bien: el agente puede actualizar selectores, preparar fixtures y ajustar esperas, pero los tests e2e los debes ejecutar tú o aceptarlos después de ver el reporte.

Un ciclo realista para un cambio en una API route o una página:

1. Pide el cambio concreto y que no toque tests todavía.
2. Revisa el diff: imports, tipos, límites de ejecución y errores de Next.js.
3. Pide “ejecuta npm run lint, npm test y npm run build”. Si algo falla, que corrija solo ese fallo y vuelva a ejecutar.
4. Si el cambio afecta a una ruta, pídele que añada o actualice un test e2e y ejecuta Playwright.
5. Revisa el reporte de tests y confirma que no haya cambios de snapshot no esperados.

Para route handlers, una prueba rápida con curl o una petición desde un test e2e detecta errores de serialización y validación. En Next.js, el build también valida tipos y render previo, así que es una comprobación final útil antes de commitear. Si el agente propone arreglar fallos de CI, una revisión automática del diff ayuda a mantener la calidad; puedes ampliarlo con Revisión de código con IA para lo que hacen tus agentes.

Varios agentes en un proyecto Next.js con AgentVera

Cuando un proyecto Next.js crece, separar trabajo en paralelo evita que un agente toque app/ mientras otro modifica components/. AgentVera ejecuta agentes CLI reales lado a lado, cada uno en su terminal, y puede usar worktrees de git para que no pisen los archivos de otros. La revisión automática al terminar un turno detecta problemas típicos de Next.js, como imports de servidor en componentes cliente. Los checkpoints permiten deshacer un cambio que rompió el build o el render. Los presupuestos de tokens frenan al agente al llegar al límite sin perder la conversación. Para flujos de varios agentes, revisa Flujo de trabajo con agentes de IA: equipos y flows.

Resumen

Codex en un proyecto Next.js funciona mejor cuando el repositorio habla con reglas claras y los prompts se mantienen pequeños. Documenta en AGENTS.md los comandos y el límite servidor/cliente, ejecuta pruebas y build en cada iteración y revisa el diff con atención a caché, route handlers y config. Con eso, el agente se convierte en un par programador que acelera tareas sin desordenar el proyecto.