cursor-agent — это терминальный агент Cursor, который запускается в корне Next.js-проекта и работает с файлами, git и командами напрямую. Чтобы он приносил пользу, а не генерировал непроверенные правки, нужны три вещи: инструкции в AGENTS.md, мелкие задачи с явным критерием готовности и обязательный прогон линтера, тестов и сборки. Основы запуска и первые шаги разобраны в гайде Как пользоваться Cursor CLI: пошаговое руководство.
Почему Cursor Agent подходит для Next.js
Агент видит структуру app/ или pages/, package.json, tsconfig.json и маршруты, поэтому может править не один файл, а связку: например, изменить серверный компонент, обновить тип и добавить тест. Для Next.js это важно, потому что задачи почти всегда пересекают границы сервер/клиент, API-роутов и тестов.
Конкретные преимущества:
- Агент запускает
npm run dev,npm run lint,npm run testи читает вывод, поэтому может сам доводить правку до зелёного состояния. - В App Router он понимает асинхронные
searchParams,cookies()иheaders(), может корректно добавитьawaitв серверный компонент или'use client'в интерактивный. - При работе с Route Handlers агент способен предложить
NextResponse.json, zod-валидацию и обработку ошибок, а не просто вернуть заглушку.
Но не стоит поручать целиком миграцию Pages Router → App Router без пошагового контроля: агент может пропустить места, где меняется поведение getServerSideProps и router.query. Подробнее о самом инструменте — на странице Cursor Agent.
Настройка проекта для агента
Cursor Agent читает инструкции из AGENTS.md или .cursor/rules. Для Next.js туда стоит положить не общие советы, а команды, структуру папок и правила, которые предотвращают типичные ошибки: смешивание серверного и клиентского кода, неправильные импорты, неожиданная статическая генерация.
Пример короткого AGENTS.md:
# Инструкции для Next.js-проекта
## Команды
- установка: `npm ci`
- dev: `npm run dev`
- сборка: `npm run build`
- линт: `npm run lint`
- unit-тесты: `npm run test` (Vitest)
- e2e: `npm run test:e2e` (Playwright)
## Соглашения
- App Router: всё в `app/`, рядом лежат `loading.tsx`, `error.tsx`.
- Серверные компоненты по умолчанию; `'use client'` только при интерактивности.
- Route Handlers в `app/api/**/route.ts`; всегда возвращают `NextResponse.json`.
- Строгий TypeScript, без `any`.
## Правила Next.js
- Не вызывать `cookies()`, `headers()`, `draftMode()` в клиентских компонентах.
- Не импортировать серверные модули в клиентский бандл.
- После изменений в выборке данных запускать `npm run build` — статические страницы могут сломаться.
- Метаданные — в `layout.tsx` или через `generateMetadata`; не использовать `document.title` в эффектах.Такой файл экономит несколько итераций: агент сразу знает, какие команды запускать, и не предлагает решения, нарушающие серверную модель.
Рабочий цикл: план, мелкие шаги, тесты, diff
Работать с агентом в Next.js лучше так: сначала попросить план, затем выполнять одну задачу за раз, после каждого шага запускать тесты и смотреть git diff. Не давайте размытые запросы «улучши проект» — это приводит к большим правкам, которые трудно ревьюить.
Типичные промпты:
- «Добавь route handler
GET /api/productsс пагинацией черезsearchParams, валидацией через zod и возвратомNextResponse.json. Напиши Vitest-тест для успешного ответа и ошибки валидации». - «В компоненте
ProductCardубериuseStateи обработчики, чтобы он стал серверным. Проверь, что импорты серверных модулей не попадут в клиентский бандл, и добавь'use client'только если интерактивность действительно нужна». - «Найди ошибку гидратации в
app/dashboard/page.tsx: вероятная причина —Date.now()при рендере. Перепиши так, чтобы сервер и клиент рендерили одинаково, и добавь Playwright-тест на загрузку страницы». - «Сгенерируй Playwright-тест для checkout: вход, добавление в корзину, оформление заказа. Мокируй API платежа; используй
page.routeдля перехвата сетевых запросов».
После каждой правки просите агента показать git diff --stat и объяснить, какие файлы затронуты и почему. Это помогает заметить лишние изменения.
Типичные задачи и подводные камни Next.js
Агент хорошо справляется с локальными изменениями: добавить API-роут, вынести клиентскую часть в отдельный компонент, поправить типы, сгенерировать тест. Сложнее ему даются сквозные изменения, затрагивающие кэширование, границы рендера и конфигурацию.
| Задача | Что поручить агенту / где проверять |
|---|---|
| Добавление Route Handler | Поручить route.ts + zod + тест; проверить, что метод GET не кэшируется без явного export const dynamic. |
| Исправление гидратации | Поручить найти расхождения сервер/клиент; проверить отсутствие Date.now(), Math.random(), window в рендере. |
| Перевод компонента в серверный | Поручить убрать хуки и обработчики; проверить, что не остался лишний 'use client'. |
| Обновление данных с revalidate | Поручить fetch с next: { revalidate }; проверить, что страница не стала статичной из-за забытых searchParams или cookies. |
| Метаданные и SEO | Поручить generateMetadata; проверить, что title и description не задаются в клиентском эффекте. |
Главные места, где агент может ошибиться: он может добавить 'use client' слишком широко, из-за чего серверные модули попадут в клиентский бандл, или, наоборот, оставить async-компонент без ожидания searchParams, что даст ошибку сборки или неправильный рендер. Также следите за тем, чтобы агент не менял next.config.js без явного запроса — это влияет на весь проект.
Тестирование и проверка в Next.js
Для агента обязательный минимум перед завершением задачи — npm run lint, npm run test и npm run build. Сборка в Next.js ловит не только TypeScript-ошибки, но и проблемы статической генерации: например, использование cookies() в статической странице или отсутствие Suspense для useSearchParams. Поэтому не принимайте правку только по зелёным unit-тестам — всегда запускайте next build.
Если проект использует Vitest или Jest, попросите агента писать тесты для серверных функций отдельно, мокируя next/headers и next/navigation. Для Playwright подойдут сценарии критического пути: загрузка главной, навигация, отправка формы. Агент может сам запустить npx playwright test и исправить селекторы, но e2e-тесты лучше гонять в конце, чтобы не тратить итерации на медленные проверки.
Несколько агентов на одном проекте с AgentVera
AgentVera — десктопное приложение, которое запускает реальные CLI-инструменты агентов, включая Cursor Agent, side by side в одном окне, каждый в своей терминальной панели. Для Next.js это полезно тем, что несколько агентов могут работать параллельно в отдельных git worktree — например, один добавляет API-роут, второй правит клиентский компонент, третий пишет Playwright-тест. Автоматическое ревью кода вторым моделью с указанием file:line помогает ловить ошибки сервер/клиент, а лимиты токенов не дают агенту сжечь бюджет на переписывание всего проекта. Подробнее о параллельных агентах — в обзоре Лучшие инструменты для параллельных ИИ-агентов (2026).
Итог
Cursor Agent в Next.js работает лучше всего, когда вы задаёте узкие задачи, фиксируете конвенции в AGENTS.md и заставляете агента проходить линтер, тесты и сборку до того, как смотреть диф. Тогда он экономит время на рутинных правках: route handlers, серверные компоненты, тесты, исправление гидратации. Не доверяйте агенту сквозные изменения кэширования и конфигурации без построчного ревью — именно там цена ошибки в Next.js выше всего.