# Gemini CLI в Next.js: практическое руководство

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

Практическое руководство по Gemini CLI в Next.js: настройка GEMINI.md для App Router и Pages Router, типовые задачи, тесты и запуск нескольких агентов.

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

- Gemini CLI закрывает типовые задачи Next.js, если правила зафиксированы в GEMINI.md.
- Короткий цикл с lint, unit-тестами и build ловит ошибки на границе серверных и клиентских компонентов.
- Параллельные агенты в git worktree, ревью и чекпоинты упрощают работу над крупными Next.js-задачами.

Gemini CLI запускается командой `gemini` в корне Next.js-проекта и работает как агент в терминале: читает репозиторий, правит файлы и сам запускает проверки. Для Next.js это быстрый способ закрывать типовые задачи от серверных действий до клиентских компонентов, если заранее описать правила в GEMINI.md. Ниже — практический процесс, который экономит время на реальной разработке.

## Почему Gemini CLI подходит для работы с Next.js

Next.js соединяет серверную и клиентскую части в одном репозитории, и агент видит его целиком: `app/`, `pages/`, route handlers, middleware и тесты. В отличие от обычных генераторов кода, Gemini CLI может не только предложить правку, но и прогнать `npm run lint`, `npm run test` и `npm run build`. Это важно для Next.js, потому что значительная часть ошибок проявляется не в одном файле, а на границе серверного и клиентского кода: лишний `'use client'`, передача функции в props, неверный формат ответа в route handler. Если правила записаны в GEMINI.md, агент реже наступает на эти грабли и следует вашим конвенциям. Подробнее о самом инструменте — в разделе [Gemini CLI](/ru/agents/gemini-cli/).

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

Заведите файл GEMINI.md в корне репозитория. В нём укажите команды, структуру каталогов и правила, специфичные для Next.js. Это главный способ настроить поведение агента под ваш проект. Пример:

```markdown
# GEMINI.md

## Команды
- install: npm ci
- dev: npm run dev
- build: npm run build
- lint: npm run lint
- unit: npm run test:unit
- e2e: npm run test:e2e

## Структура
- app/ — App Router: серверные компоненты по умолчанию, 'use client' только при интерактивности
- components/ — общие React-компоненты; предпочитай серверные, выноси интерактив в отдельные файлы
- lib/ — серверная логика, доступ к БД, схемы валидации, утилиты
- app/api/ — route handlers; используй Response/NextResponse, не Express-объекты

## Правила
- Не добавляй 'use client' без явной необходимости.
- Не передавай функции или экземпляры классов из серверных компонентов в клиентские props.
- Для мутаций используй server actions, а не API routes, если это возможно.
- Валидируй входные данные всех server actions через zod.
- Соблюдай конвенции Next.js: layout.tsx, page.tsx, loading.tsx, error.tsx.
- Не отключай ESLint без причины; запускай npm run lint после правок.
```

Если проект на Pages Router, замените `app/` на `pages/` и добавьте правила для `getServerSideProps` и `getStaticProps`: агент не должен смешивать их с App Router-файлами и использовать server actions, которых в Pages Router нет. Первые шаги по работе с агентом описаны в [Как пользоваться Gemini CLI: пошаговое руководство](/ru/blog/how-to-use-gemini-cli/).

## Рабочий цикл с агентом

Просите план, затем реализацию маленькими шагами; после каждого шага запускайте проверки и смотрите diff. Не отправляйте запрос «сделай всё приложение» — в Next.js это почти всегда приводит к каскаду изменений на серверной и клиентской сторонах. Примеры промтов для типовых задач:

- «Прочитай GEMINI.md и предложи план для задачи: добавить server action создания проекта с валидацией через zod и записью в БД. Реализуй после моего ОК.»
- «Добавь в `app/dashboard/page.tsx` серверную загрузку данных из `lib/data.ts`. Интерактивную часть вынеси в `components/dashboard-filter.tsx` с `'use client'`.»
- «Исправь route handler `app/api/webhooks/stripe/route.ts`: добавь проверку подписи Stripe при помощи `stripe.webhooks.constructEvent` и возвращай 400 при неверной подписи.»
- «Напиши Playwright-тест `e2e/login.spec.ts`: успешный вход и неверный пароль. Используй селекторы `data-testid`.»
- «Пройдись по `app/` и найди компоненты с клиентским fetch, которые можно перевести на серверный рендер. Составь список изменений, потом делай по одному.»

После каждого ответа: `git diff`, затем `npm run lint`, `npm run test:unit`, при изменениях роутов или серверных компонентов — `npm run build`. Такой цикл похож на [парное программирование с ИИ](/ru/blog/ai-pair-programming/): вы контролируете шаги, агент пишет код.

## Что агент делает хорошо и где смотреть внимательно

Хорошо закрываются рутинные задачи: создание server actions с zod-валидацией, route handlers с правильными ответами `NextResponse`, перенос client-side fetch в React Server Components, добавление `loading.tsx` и `error.tsx`, генерация `metadata`, обновление unit-тестов. Опасности в основном связаны с архитектурными границами Next.js:

- Граница сервер/клиент. Агент может добавить `'use client'` в layout или передать функцию/класс из серверного компонента в клиентский props — это сломает сборку.
- Асинхронные `params` и `searchParams`. В свежих версиях App Router они приходят как Promise; агент может оставить синхронный доступ и получить ошибку типов.
- Route handlers. Агент иногда возвращает `res.status().json()` по привычке Express вместо `NextResponse.json` или `Response`.
- Кэш и ревалидация. После мутаций агент может забыть `revalidatePath` или `revalidateTag`, и UI не обновится.
- ESLint-правила Next.js. Может оставить `<img>` вместо `next/image` или анонимный default export в page.
- В Pages Router агент может перепутать `getServerSideProps` с серверными компонентами или добавить server action, которого нет в этой модели.

Сложные задачи вроде «найди и исправь все ошибки серверных компонентов» разбивайте на файлы или маршруты — иначе правок будет слишком много, и вы не успеете проверить каждую границу.

## Тестирование и проверка для Next.js

Для Next.js недостаточно unit-тестов; нужен полный цикл. Заставляйте агента запускать проверки после изменений:

| Проверка | Команда | Что ловит для Next.js |
| --- | --- | --- |
| ESLint | `npm run lint` | Next-специфичные правила: `<img>`, отсутствие `metadata`, экспорт page |
| Unit | `npm run test:unit` | Логика server actions, утилиты, преобразования данных |
| Build | `npm run build` | Ошибки типов и границ RSC, которые не видны в dev-режиме |
| E2E | `npm run test:e2e` | Реальные потоки: формы, навигация, обработка ошибок |

Агент может писать и обновлять Playwright-тесты вместе с кодом. После правок с серверными компонентами всегда гоняйте `npm run build` — иначе ошибка «client-only code in server component» может всплыть только в CI. Для Vitest или Jest полезно, чтобы агент запускал только затронутые тесты, но перед завершением задачи — весь набор.

## Несколько агентов в одном Next.js-проекте с AgentVera

AgentVera — это десктопное приложение, которое запускает настоящие CLI-инструменты агентов в отдельных терминальных панелях. Для Next.js особенно полезны такие возможности. Параллельные агенты в собственных git worktree позволяют одному править server action, а другому — Playwright-тесты, не затирая файлы друг друга. Автоматическое ревью после каждой итерации ловит ошибки на границе серверных и клиентских компонентов. Чекпоинты каждого шага дают откатить неудачное изменение перед сборкой. Это хорошо ложится на [оркестрацию ИИ-агентов](/ru/blog/ai-coding-agent-orchestration/) в Next.js-проекте.

## Вывод

Gemini CLI в Next.js окупается, если вы не полагаетесь на него как на автопилот, а ведёте короткими шагами с обязательными `lint`, `test` и `build`. Зафиксируйте правила в GEMINI.md, гоняйте проверки после каждого изменения и не давайте агенту молча менять границы серверных и клиентских компонентов. Тогда агент забирает рутину, а архитектурные решения остаются за вами.

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

**Как запустить Gemini CLI в проекте Next.js?** Откройте терминал в корне проекта и выполните gemini. Перед этим создайте файл GEMINI.md с командами и правилами проекта, чтобы агент следовал вашим конвенциям.

**Что писать в GEMINI.md для Next.js?** Укажите команды install/dev/build/lint/test/e2e, структуру каталогов app/ или pages/, правила для серверных и клиентских компонентов, server actions и route handlers. Это снижает число ошибок на границах Next.js.

**Какие задачи Gemini CLI решает в Next.js лучше всего?** Хорошо закрываются server actions с zod-валидацией, route handlers, перевод client-side fetch на серверный рендер, добавление loading/error, генерация metadata и обновление unit-тестов. Архитектурные решения лучше контролировать вручную.

**Как проверять код после Gemini CLI в Next.js?** Запускайте npm run lint, npm run test:unit и npm run build; после изменений пользовательских сценариев — npm run test:e2e. Смотрите git diff до коммита, особенно на границе серверных и клиентских компонентов.

---

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