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

URL: https://agentvera.dev/es/blog/codex-para-nextjs/ · Publicado: 2026-11-01

Guía práctica para usar Codex en proyectos Next.js: configura AGENTS.md, trabaja con App Router, componentes cliente y servidor, y valida con tests.

**En resumen:**

- Codex se ejecuta con codex en tu proyecto Next.js y lee AGENTS.md para aplicar reglas de build, test y carpetas.
- Trabaja con prompts pequeños: plan, cambio, pruebas, revisión del diff; así evitas mezclar servidor y cliente.
- Los puntos críticos son el límite servidor/cliente, route handlers, caché y cambios de configuración.

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](/es/agents/codex/) o con [Cómo usar Codex CLI: guía paso a paso](/es/blog/how-to-use-codex-cli/).

## 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:

```markdown
# 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:

| Tarea | Pide esto | Revisa aquí |
| --- | --- | --- |
| Migrar una página a server component | "Mueve la obtención de datos a `page.tsx` y deja un client component para la parte interactiva." | Que no lleguen `fs`, secretos ni imports de Node al cliente. |
| Crear un route handler | "Crea `app/api/items/route.ts` con GET y POST, valida entrada y devuelve JSON tipado." | Validación, códigos de estado, paginación, `cache` y `dynamic`. |
| Añadir una server action | "Añade una action en `app/actions.ts` que use `revalidatePath` al terminar." | Que no se invoque desde componentes cliente sin permiso, y que no mezcle lógica de servidor. |
| Extraer un client component | "Extrae la parte con `useState` a `components/Filtro.tsx` y añade `"use client"` solo ahí." | Límites de serialización de props y que no se importen módulos server-only. |
| Ajustar tests e2e | "Actualiza los tests de Playwright para el flujo de login con el nuevo redirect." | Selectores, esperas y variables de entorno. |

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](/es/blog/ai-code-review/).

## 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](/es/blog/ai-agent-workflow-pipeline/).

## 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.

## Preguntas frecuentes

**¿Codex puede trabajar con App Router y Pages Router de Next.js?** Sí, puede modificar rutas, layouts, server components, client components y route handlers siempre que las reglas del proyecto estén en AGENTS.md. Conviene indicarle qué router usa el proyecto y dónde están las convenciones.

**¿Cómo configuro Codex para un proyecto Next.js?** Arranca con codex en la carpeta del proyecto y crea un AGENTS.md con comandos de build, test, lint y convenciones de carpetas. El agente lee ese archivo y adapta sus cambios.

**¿Codex sabe ejecutar npm test, lint o build de Next.js?** Puede ejecutar comandos del package.json como npm run lint, npm test o npm run build si se lo pides. Es útil pedirle que ejecute estas comprobaciones antes de dar por terminada una tarea.

**¿Puedo usar Codex para crear API routes y server actions?** Sí, genera route handlers, server actions y endpoints REST, pero debes revisar validación de entrada, autenticación y tipos. Como no conoce todos los requisitos de negocio, revisa seguridad y casos límite.

---

**Sobre AgentVera.** AgentVera es una app de escritorio para macOS, Windows y Linux, desarrollada por Solviera Teknoloji. Ejecuta 18 agentes de programación con IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) en paralelo, por proyecto, en terminales reales con las instalaciones y sesiones de CLI del propio usuario. El plan gratuito tiene agentes ilimitados. Descargar: https://agentvera.dev/es/download/ · Precios: https://agentvera.dev/es/pricing/