# Cursor Agent для Next.js: практическое руководство

URL: https://agentvera.dev/ru/blog/cursor-agent-dlya-nextjs/ · Опубликовано: 2026-11-01

Практическое руководство по Cursor Agent в Next.js: настройка AGENTS.md, цикл с тестами и diff, типичные задачи и подводные камни App Router.

**Коротко:**

- cursor-agent работает в корне Next.js-проекта и управляет файлами, git и командами, но требует чётких инструкций из AGENTS.md.
- Мелкие задачи с обязательным прогоном lint, тестов и next build дают предсказуемый результат и меньше риска.
- Агент хорошо делает route handlers, серверные компоненты и тесты, но опасен в кэшировании и границах сервер/клиент.

`cursor-agent` — это терминальный агент Cursor, который запускается в корне Next.js-проекта и работает с файлами, git и командами напрямую. Чтобы он приносил пользу, а не генерировал непроверенные правки, нужны три вещи: инструкции в AGENTS.md, мелкие задачи с явным критерием готовности и обязательный прогон линтера, тестов и сборки. Основы запуска и первые шаги разобраны в гайде [Как пользоваться Cursor CLI: пошаговое руководство](/ru/blog/how-to-use-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](/ru/agents/cursor-agent/).

## Настройка проекта для агента

Cursor Agent читает инструкции из `AGENTS.md` или `.cursor/rules`. Для Next.js туда стоит положить не общие советы, а команды, структуру папок и правила, которые предотвращают типичные ошибки: смешивание серверного и клиентского кода, неправильные импорты, неожиданная статическая генерация.

Пример короткого `AGENTS.md`:

```markdown
# Инструкции для 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`. Не давайте размытые запросы «улучши проект» — это приводит к большим правкам, которые трудно ревьюить.

Типичные промпты:

1. «Добавь route handler `GET /api/products` с пагинацией через `searchParams`, валидацией через zod и возвратом `NextResponse.json`. Напиши Vitest-тест для успешного ответа и ошибки валидации».
2. «В компоненте `ProductCard` убери `useState` и обработчики, чтобы он стал серверным. Проверь, что импорты серверных модулей не попадут в клиентский бандл, и добавь `'use client'` только если интерактивность действительно нужна».
3. «Найди ошибку гидратации в `app/dashboard/page.tsx`: вероятная причина — `Date.now()` при рендере. Перепиши так, чтобы сервер и клиент рендерили одинаково, и добавь Playwright-тест на загрузку страницы».
4. «Сгенерируй 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)](/ru/blog/best-tools-parallel-ai-coding-agents/).

## Итог

Cursor Agent в Next.js работает лучше всего, когда вы задаёте узкие задачи, фиксируете конвенции в AGENTS.md и заставляете агента проходить линтер, тесты и сборку до того, как смотреть диф. Тогда он экономит время на рутинных правках: route handlers, серверные компоненты, тесты, исправление гидратации. Не доверяйте агенту сквозные изменения кэширования и конфигурации без построчного ревью — именно там цена ошибки в Next.js выше всего.

## Частые вопросы

**Что такое Cursor Agent и как его запустить в Next.js?** Cursor Agent — терминальный агент Cursor. В папке проекта выполните cursor-agent; он начнёт сессию, в которой можно давать задачи по изменению кода, запуску тестов и работе с git.

**Нужен ли AGENTS.md для Next.js?** Да, это сильно улучшает результат. В нём стоит указать команды build/lint/test, структуру папок app/ и правила серверных/клиентских компонентов.

**Можно ли использовать Cursor Agent с App Router?** Да. Агент понимает асинхронные searchParams, cookies и headers, может добавлять 'use client' и route handlers. Но контролируйте кэширование и статическую генерацию.

**Как проверить правки агента в Next.js?** Запускайте npm run lint, npm run test и npm run build. Сборка ловит ошибки серверных компонентов, статической генерации и типов, которые не видны в unit-тестах.

---

**Об AgentVera.** AgentVera — настольное приложение для macOS, Windows и Linux от Solviera Teknoloji. Оно запускает 18 ИИ-агентов для программирования (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) рядом, по проектам, в настоящих терминалах с собственными установками CLI и входами пользователя. В бесплатном тарифе количество агентов не ограничено. Скачать: https://agentvera.dev/ru/download/ · Цены: https://agentvera.dev/ru/pricing/