Cursor Agent y Next.js: guía práctica para desarrolladores

Cursor Agent es la vía más directa para usar el agente de Cursor desde la terminal en un proyecto Next.js: ejecuta cursor-agent en la carpeta del repositorio y trabaja sobre el código, los comandos de build, lint y test que ya tienes. Esta guía de Cursor Agent explica cómo preparar el repositorio, sostener un ciclo de trabajo fiable y vigilar los puntos donde Next.js exige más control.

Por qué Cursor Agent encaja en Next.js

Next.js obliga a separar servidor y cliente, organizar rutas y mantener comandos estrictos de build. Cursor Agent destaca aquí porque no se limita a escribir componentes: puede leer errores de next build, ejecutar ESLint, lanzar tests y proponer cambios acotados. Con un AGENTS.md bien definido, el agente respeta la estructura de App Router o Pages Router, evita romper server components y actúa sobre la base de código real en lugar de generar archivos sueltos.

Cómo preparar el proyecto para el agente

Coloca la información del proyecto en AGENTS.md o en .cursor/rules. Cuanto más concretos sean los comandos y las convenciones, menos inventará. Incluye siempre los scripts de package.json que ya usas, la ubicación de las rutas, la regla de server/client components y las restricciones de variables de entorno.

Un ejemplo corto de AGENTS.md para un proyecto mixto:

# AGENTS.md

## Comandos
- instalar: npm ci
- desarrollo: npm run dev
- build: npm run build
- lint: npm run lint
- test: npm run test
- test e2e: npm run test:e2e

## Reglas Next.js
- App Router en src/app; Pages Router solo en src/pages si existe.
- Los componentes son server por defecto; no añadas \"use client\" sin motivo.
- Usa client components solo para useState, useEffect, eventos o APIs del navegador.
- No importes código server-only en client components.
- Route handlers en src/app/api: valida la entrada y devuelve Response.json.
- No expongas variables de entorno sin NEXT_PUBLIC_ en el cliente.
- No instales dependencias sin confirmación.

Mantén este archivo en control de versiones y actualízalo cada vez que cambien comandos o reglas. Las reglas de .cursor/rules pueden dividirse por área (rutas, APIs, testing) para que el agente cargue solo lo relevante. Si no has usado la CLI, la guía paso a paso de Cursor CLI aclara el arranque básico.

Ciclo de trabajo con prompts para Next.js

No pidas una feature completa de una vez. El ciclo que mejor funciona en Next.js es: define el cambio en una frase, deja que el agente proponga un plan, revisa el diff, ejecuta lint y tests, y solo después acepta o pide ajustes. Aplica un flujo de vibe coding con seguridad para no aceptar cambios a ciegas.

Un ciclo recomendado:

• 1. Abre el prompt con el archivo o la ruta concreta.
• 2. Pide primero un plan de cambios y los archivos que tocará.
• 3. Revisa el diff antes de continuar.
• 4. Ejecuta lint, tests y build dentro del mismo turno.

Ejemplos de prompts para tareas típicas:

• «Revisa src/app/page.tsx y mueve la lógica de datos a una función async en src/lib/products.ts; mantén el componente como server component y añade Suspense para la carga.»
• «Crea un route handler GET /api/products en src/app/api/products/route.ts que lea searchParams, valide con zod y devuelva Response.json. Añade tests con Vitest.»
• «Convierte src/components/ThemeToggle.tsx en client component solo si usa useState; no arrastres imports del servidor.»
• «Corrige los errores de npm run build y npm run lint sin cambiar el comportamiento; después ejecuta npm run test:e2e y revisa los fallos de Playwright.»
• «Actualiza la metadata de src/app/layout.tsx con title y description por ruta, sin duplicar metadata en páginas hijas.»

Pide siempre pasos pequeños; si una tarea toca rutas, datos y estilos a la vez, divídela en prompts separados.

Tareas típicas y puntos de vigilancia

Cursor Agent resuelve bien tareas mecánicas de Next.js: crear páginas y layouts, mover lógica a server components, escribir route handlers, corregir errores de tipos y ESLint, y actualizar snapshots. También es útil para refactors acotados: renombrar un componente, extraer una función o migrar una página de Pages Router a App Router.

Vigílalo de cerca en tres zonas. Primero, la frontera servidor/cliente: el agente a veces añade \"use client\" de más o importa un módulo server-only dentro de un client component, y el build falla. Segundo, las variables de entorno: puede usar process.env.SECRET en el cliente o crear una variable NEXT_PUBLIC_SECRET por error. Tercero, los route handlers y el caching: conviene revisar que use Response.json, valide la entrada y no modifique rutas con cookies o headers de forma inesperada. En Pages Router, cuidado con getServerSideProps y getStaticProps: no aceptes cambios que mezclen ambos sistemas sin justificación.

Testing y verificación con el agente

Convierte la verificación en parte de cada prompt. Pide al agente que ejecute npm run lint, npm test y npm run build antes de dar por terminada una tarea. Si usas Playwright, indícale que corra npm run test:e2e y que lea el HTML de los fallos, no solo el stack trace. Para proyectos con Jest o Vitest, exige que añada o actualice tests junto con el código y que muestre git diff --stat antes de proponer el commit. Los tests unitarios cubren bien la lógica de route handlers y utilidades; Playwright cubre navegación e hidratación. Así detectas pronto regresiones de hidratación, imports inválidos o metadata rota que solo aparecen en build.

Varios agentes en un proyecto Next.js con AgentVera

En un proyecto Next.js complejo, AgentVera permite lanzar Cursor Agent junto a otros agentes en terminales reales, cada uno en su propio worktree de git para que no pisen archivos. Al terminar un turno, un segundo modelo revisa el código y enlaza hallazgos a file:line, útil para detectar errores de server/client components. Los checkpoints guardan una instantánea de cada turno: si un cambio rompe el build, se deshace con un clic. Más contexto en mejores herramientas para agentes de IA en paralelo.

Conclusión

Cursor Agent trabaja bien en Next.js cuando el repositorio le da reglas exactas y cuando cada prompt pide un cambio verificable. Mantén AGENTS.md actualizado, divide las tareas, ejecuta lint, tests y build en cada iteración, y usa la revisión del diff como filtro final. Con ese control, el agente acelera el trabajo sin convertirse en una caja negra.