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

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

Как применять GitHub Copilot CLI в Next.js-проекте: настройка .github/copilot-instructions.md, рабочий цикл, типичные задачи и проверка кода с тестами.

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

- Copilot CLI работает эффективно в Next.js, если в .github/copilot-instructions.md заданы команды сборки, тестов и правила серверных/клиентских компонентов.
- Рабочий цикл: план, правки малыми шагами, запуск lint и тестов, затем ручной просмотр diff.
- Критично проверять границы server/client, route handlers и кэширование — агент может ошибиться в этих местах.

GitHub Copilot CLI помогает в Next.js-проекте, если запускать его командой `copilot` в корне репозитория и сразу задать правила сборки, тестов и структуры. Подробнее о возможностях агента можно прочитать в [GitHub Copilot CLI](/ru/agents/copilot-cli/). Без инструкций агент часто путает App Router и Pages Router, границы серверных и клиентских компонентов и команды проверки, поэтому подготовка проекта важнее, чем сам запуск.

## Почему Copilot CLI подходит для Next.js

Copilot CLI работает в терминале, видит весь репозиторий и может запускать команды. Для Next.js это даёт почти полный цикл: прочитать package.json и tsconfig, найти файлы в app/ или pages/, понять, где серверные и клиентские компоненты, внести правки и сразу выполнить `pnpm lint`, `pnpm test` или `pnpm build`. Агент понимает, что файлы в app/ — это серверные компоненты по умолчанию, и может предложить перенести клиентскую логику в отдельный файл с `"use client"`. Он хорошо справляется с рутинными изменениями: создать страницу с layout и loading, добавить route handler, перевести часть UI в клиентский компонент, обновить тесты. В отличие от плагинов в редакторе, CLI-агент генерирует diff на уровне файлов и может сам запускать проверки после правок, что важно для Next.js-проектов с несколькими роутами и тестовыми наборами.

## Подготовка проекта и инструкции для агента

Создайте `.github/copilot-instructions.md` или `AGENTS.md` в корне проекта. В файле зафиксируйте команды, структуру роутов и правила серверного/клиентского кода. Чем конкретнее правила, тем реже агент будет менять не то. Для больших проектов добавьте краткую карту слоёв и маршрутов — примеры подхода есть в [Карта кодовой базы для AI-агентов: поиск без grep](/ru/blog/codebase-map-for-ai-agents/).

Пример короткого файла:

```markdown
# Next.js: правила для Copilot CLI

Package manager: pnpm
Основные команды:
- pnpm dev — dev-сервер
- pnpm build — production-сборка
- pnpm lint — ESLint + next lint
- pnpm test -- --run — unit-тесты Vitest
- pnpm test:e2e -- --project=chromium — Playwright

Роутинг: App Router в app/, Pages Router не используется.
Компоненты по умолчанию серверные. "use client" добавляйте только при хуках, событиях или браузерных API.
Данные загружайте в Server Components и route handlers; не делайте fetch в клиентских компонентах.
Не импортируйте server-only модули (например, db.ts, auth-helpers.ts) в клиентские файлы.
Route handlers в app/api/** должны возвращать корректные статусы, обрабатывать ошибки и Content-Type.
.env.local и .env*.local не коммитить; ключи доступны только на сервере.
Перед завершением задачи: запустите pnpm lint, pnpm test -- --run и при изменении роутов — соответствующий Playwright spec.
```

Дополнительно можно зафиксировать: не менять next.config.ts без явного запроса; не добавлять новые зависимости без необходимости; использовать `import type` для типов; не выносить секреты в `NEXT_PUBLIC_*`. Если у вас смешанный проект с Pages Router, явно опишите, какие каталоги относятся к какому роутеру. Если проект использует npm или yarn, просто замените команды. Для Jest команда запуска может быть `npm test -- --runInBand`.

## Рабочий цикл и примеры запросов

Стройте работу так: сначала опишите задачу и попросите план, затем разрешите вносить изменения маленькими шагами. После каждого шага запускайте проверки и смотрите `git diff`. Полный `pnpm build` лучше оставлять на конец, чтобы не тратить время в процессе. Базовый цикл описан в [Как пользоваться GitHub Copilot CLI: руководство](/ru/blog/how-to-use-copilot-cli/).

Начинайте с конкретного файла или маршрута, а не с общей просьбы «улучши приложение». Если задача затрагивает несколько файлов, попросите сначала перечислить план изменений и только после подтверждения переходить к правкам. Так меньше случайных изменений в next.config, middleware или общих layout.

Примеры запросов для типичных Next.js-задач:

1. «Создай серверный компонент `dashboard/page.tsx`, который получает список проектов через server-only функцию `getProjects` и выводит карточки. Добавь `loading.tsx` со скелетоном.»
2. «Добавь route handler `app/api/posts/route.ts` для GET и POST. Валидируй body через zod, возвращай 400 при ошибке, для POST не используй кэш.»
3. «Переведи `ProductCard` в клиентский компонент: добавь useState для избранного, но данные о товаре получай из серверного родителя через props.»
4. «Напиши Playwright-тест для `/login`: проверь сообщение об ошибке при пустых полях и редирект на `/dashboard` после успешного входа с моком API.»
5. «Добавь правило ESLint `no-restricted-imports`, чтобы запретить импорт из `@/server` в файлах с "use client".»

## Что Copilot CLI делает хорошо и где нужен контроль

Агент уверенно генерирует страницы, route handlers, тесты и рефакторит клиентские компоненты. Но именно в Next.js есть несколько мест, где нужно смотреть diff вручную.

| Область | Что проверить |
|---|---|
| Серверные и клиентские компоненты | Нет серверных импортов в клиентских файлах, `"use client"` только где нужно |
| Route handlers | Валидация, статусы, методы, CORS, нет утечки секретов |
| Кэширование и ревалидация | Динамические данные не закешированы без `revalidate` или `no-store` |
| Метаданные и middleware | `metadata` в layout/page корректен, `middleware.ts` не ломает статические файлы |

Типичные ошибки: агент добавляет "use client" на всю страницу ради одного хука, импортирует `db.ts` в клиентский файл, предлагает `fetch` в `useEffect` вместо загрузки в Server Component или путает `app/` и `pages/`. Например, агент может предложить `export const dynamic = 'force-static'` для страницы, которая зависит от cookies, или вынести переменную окружения в `NEXT_PUBLIC_` без необходимости. Такие вещи видны только при чтении diff и понимании, где данные должны быть динамическими. После правок обязательно запускайте `pnpm lint` и тесты, а для изменений в роутах — соответствующий Playwright-спек.

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

Попросите агента запускать `pnpm lint` и `pnpm test -- --run` после каждого изменения, а полный `pnpm build` — перед финальным коммитом. Для UI-сценариев полезно, чтобы агент сам запускал Playwright и анализировал ошибки; практику можно посмотреть в [Тестирование в браузере с ИИ-агентом: пусть агент проверит](/ru/blog/ai-agent-browser-testing/). Для route handlers можно попросить unit-тест на сам handler с `new Request(...)` и проверкой статусов, а для серверных компонентов — тест на чистую функцию данных, если она вынесена отдельно. Playwright-тесты лучше запускать с конкретным проектом и baseURL из .env. Следите, чтобы агент не оставлял фоновый dev-сервер: это мешает следующим запускам и занимает порт. Если тестов много, просите запускать только затронутые спеки, а не весь набор.

## Параллельные агенты с AgentVera

Если над разными частями Next.js-приложения работают несколько агентов, AgentVera запускает их в одном окне, каждый в своём реальном терминале. Агенты могут работать в отдельных git worktree, поэтому правки маршрутов и компонентов не пересекаются. После завершения хода агента другой агент автоматически ревьюит код и находит проблемы на границах server/client — это важно для Next.js. Лимиты токенов не дают одному агенту уйти в долгую переработку. Так параллельно можно закрывать задачи по API, UI и тестам без конфликтов.

## Итог

GitHub Copilot CLI в Next.js полезен, когда проект подготовлен: в `.github/copilot-instructions.md` зафиксированы команды и правила роутинга, а проверки включены в рабочий цикл. Не доверяйте агенту правки на границах серверного и клиентского кода и всегда смотрите итоговый diff. Тогда Copilot CLI закрывает рутинные задачи — от route handlers до Playwright-тестов — быстрее и с меньшим количеством ручной работы.

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

**Как запустить GitHub Copilot CLI в Next.js-проекте?** Перейдите в корень проекта и выполните команду copilot. Перед первым запуском создайте .github/copilot-instructions.md или AGENTS.md с командами сборки, тестов и правилами роутинга, чтобы агент сразу работал в контексте Next.js.

**Что указать в .github/copilot-instructions.md для Next.js?** Укажите package manager, команды pnpm/npm для dev, build, lint и тестов, структуру app/ или pages/, правила server/client компонентов и запрет импорта server-only модулей в клиентский код. Добавьте список основных маршрутов и ограничения на next.config.

**Может ли Copilot CLI отличить серверные и клиентские компоненты Next.js?** Да, если в инструкциях явно описаны правила. Агент понимает синтаксис "use client" и разницу между Server Components и Client Components, но может ошибаться в неочевидных импортах, поэтому нужно проверять diff.

**Как Copilot CLI проверяет изменения в Next.js?** Агент может запускать команды из инструкций: ESLint, unit-тесты, Playwright и production-сборку. Обычно просят запускать lint и тесты после каждого изменения, а build — перед финальным коммитом.

---

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