Gemini CLI в 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.

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

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

# 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: пошаговое руководство.

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

Просите план, затем реализацию маленькими шагами; после каждого шага запускайте проверки и смотрите 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. Такой цикл похож на парное программирование с ИИ: вы контролируете шаги, агент пишет код.

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

Хорошо закрываются рутинные задачи: создание 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-тестов; нужен полный цикл. Заставляйте агента запускать проверки после изменений:

Агент может писать и обновлять 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-тесты, не затирая файлы друг друга. Автоматическое ревью после каждой итерации ловит ошибки на границе серверных и клиентских компонентов. Чекпоинты каждого шага дают откатить неудачное изменение перед сборкой. Это хорошо ложится на оркестрацию ИИ-агентов в Next.js-проекте.

Вывод

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