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

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

Aprende a usar Cursor Agent en un proyecto Next.js: configuración con AGENTS.md, flujo de trabajo, prompts útiles, testing y verificación.

**En resumen:**

- Cursor Agent funciona bien en Next.js si defines comandos, convenciones y límites claros en AGENTS.md o .cursor/rules.
- Trabaja en pasos pequeños, ejecuta lint, tests y build, y revisa siempre el diff antes de aceptar cambios.
- Vigila la frontera server/client, las variables de entorno y los route handlers para evitar fallos típicos de Next.js.

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](/es/agents/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.

| Área | Qué indicar |
| --- | --- |
| Comandos | `npm run dev`, `npm run build`, `npm run lint`, `npm test`, `npm run test:e2e` |
| Enrutado | `src/app` para App Router; `src/pages` solo si usas Pages Router |
| Componentes | Server por defecto; añadir `\"use client\"` solo para estado, efectos o eventos |
| APIs | Route handlers en `src/app/api`; validar entrada y devolver `Response.json` |
| Entorno | `NEXT_PUBLIC_` solo para cliente; secretos solo en servidor |

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

```markdown
# 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](/es/blog/how-to-use-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](/es/blog/how-to-vibe-code/) 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](/es/blog/best-tools-parallel-ai-coding-agents/).

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

## Preguntas frecuentes

**¿Cómo inicio Cursor Agent en un proyecto Next.js?** Abre la terminal en la carpeta raíz del proyecto y ejecuta cursor-agent. Para que trabaje bien, define antes un AGENTS.md con los comandos de build, lint y test, y con las reglas de App Router o Pages Router.

**¿Qué debe contener AGENTS.md para un proyecto Next.js?** Debe incluir los comandos reales de desarrollo, build, lint y testing; las rutas de src/app o src/pages; la regla de server components por defecto; y las restricciones de variables de entorno. También conviene indicar dónde viven los route handlers y las utilidades.

**¿Puede Cursor Agent ejecutar Playwright y tests de Next.js?** Sí, puede ejecutar los scripts que definas en package.json, como npm run test:e2e para Playwright o npm test para Vitest/Jest. Pídele que lea los reportes de fallo y que actualice los tests junto con el código.

**¿Cómo evito que Cursor Agent rompa los server components?** Especifica en AGENTS.md que los componentes son server por defecto y que solo añada \"use client\" cuando haya estado, efectos o eventos. Revisa siempre el diff de imports y ejecuta next build para detectar errores de server-only.

---

**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/