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

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

Практическое руководство по использованию Claude Code в Next.js: настройка CLAUDE.md, рабочий цикл с планом и тестами, типичные задачи, подводные камни.

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

- Claude Code запускается в корне Next.js-проекта и читает CLAUDE.md с командами сборки, тестов и правилами App Router.
- Работайте короткими шагами: план, маленькое изменение, запуск линтера и тестов, просмотр diff.
- Особое внимание — границе серверных и клиентских компонентов, кэшированию и валидации в route handlers.

Для работы с Next.js [Claude Code](/ru/agents/claude-code/) запускается командой `claude` в корне проекта и читает контекст из CLAUDE.md. Это не замена знанию фреймворка, а инструмент, который быстрее выполняет рутинные правки, рефакторинги и тесты. Ниже — практический цикл, настройка и места, где агента нужно контролировать.

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

Next.js-проекты состоят из множества небольших файлов: страницы, layouts, route handlers, server actions, утилиты. Claude Code хорошо справляется с такими изменениями, потому что видит структуру репозитория и может редактировать несколько файлов за один заход. Он умеет запускать команды из терминала, поэтому сразу проверяет линтер, типы и тесты, а не только пишет код. Для App Router это полезно при переносе логики между серверными и клиентскими компонентами: агент может предложить, где убрать `'use client'`, а где добавить `Suspense` или server action. Минус в том, что тонкости кэширования, границы RSC и рантайма нужно прописывать явно — иначе агент предложит рабочее, но неоптимальное решение.

## Настройка проекта и CLAUDE.md для Next.js

Агент автоматически читает CLAUDE.md из корня проекта при запуске. Туда стоит вынести всё, что вы повторяете голосом в каждой сессии: команды, структуру папок, правила работы с серверными и клиентскими компонентами. Держите файл коротким — на один экран. Пример для типового Next.js-проекта с pnpm, Vitest и Playwright:

```markdown
# CLAUDE.md

## Команды
- Установка: pnpm install
- Линт: pnpm lint
- Типы: pnpm typecheck
- Юнит-тесты: pnpm test
- E2E: pnpm test:e2e
- Сборка: pnpm build

## Структура
- `app/` — App Router: страницы, layouts, route handlers, server actions.
- `components/` — общие компоненты; по умолчанию серверные.
- `lib/` — серверная логика, утилиты, API-клиенты.
- `public/` — статика.

## Правила
- Для интерактивных компонентов добавляй 'use client' в начале файла; не помечай всю страницу без необходимости.
- Мутации — в route handlers или server actions, не в клиентских компонентах.
- Не импортируй серверные модули с доступом к БД в клиентский код.
- Используй `next/link` для внутренних переходов, `next/image` для картинок.
- Валидируй входные данные в route handlers и server actions с zod.
- Не редактируй сгенерированные файлы `.next/` и `next-env.d.ts`.
- Для динамических страниц с API-данными добавляй `Suspense` или `loading.tsx`.
```

Обновляйте CLAUDE.md вместе с кодом: если появилась новая папка или правило валидации, добавьте его. Чем точнее контекст, тем меньше правок придётся переделывать. Подробнее о том, что стоит фиксировать, — в [лучших практиках Claude Code](/ru/blog/claude-code-best-practices/).

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

Не просите агента сразу переписать половину приложения. Работайте короткими шагами: сначала попросите план, затем маленькое изменение, затем запуск проверок, затем просмотр diff. Это снижает риск получить нерабочую сборку и упрощает откат. Можно попросить Claude Code сначала предложить план, не меняя код, — режим планирования описан в отдельной [статье](/ru/blog/claude-code-plan-mode/).

Примеры запросов для типовых задач:

- «Сначала план: что нужно изменить в app/posts и lib/api, какие файлы затронем, какие тесты обновить. Код не пиши.»
- «Добавь server action для создания поста с zod-валидацией. Изменяй только app/posts/actions.ts и prisma/schema.prisma.»
- «Убери client-side fetch из компонента списка и загрузи данные на сервере. Покажи, какие компоненты станут серверными, и добавь Suspense.»
- «Напиши юнит-тесты для функции parseSearchParams. После этого выполни pnpm lint и pnpm test, покажи итоговый diff.»

После каждой правки просите агента показать `git diff` и объяснить неочевидные места. Если тест или линтер падает, сначала попросите исправить именно ошибку, а не продолжать добавлять новый код.

## Что Claude Code делает хорошо и где его нужно контролировать

**Хорошо справляется:**
- добавление route handlers с валидацией, server actions, генерация форм;
- рефакторинг клиентских компонентов в серверные, выделение Suspense и loading states;
- написание тестов Vitest и Playwright по существующему коду;
- обновление Tailwind-классов, доступности, типов.

**Контролируйте внимательно:**
- граница `'use client'`: агент может добавить директиву в layout или page, что ухудшит размер клиентского бандла;
- импорт серверных модулей (с БД, токенами) в клиентский код — это вызовет ошибку сборки или утечку секретов;
- кэширование и revalidate: агент может не учесть `fetch` cache, `revalidatePath` или `export const dynamic`, и данные устареют;
- route handlers: возврат обычного объекта вместо `NextResponse.json` или `Response`, неверный статус-код, отсутствие CORS-заголовков;
- `next/image`: непрописанные домены в `next.config` приводят к ошибкам;
- динамические API в статических страницах: `cookies()`, `headers()` без `dynamic = 'force-dynamic'` ломают сборку.

Это не значит, что агент всегда ошибается, но на этих местах проверяйте diff особенно тщательно.

## Проверка и верификация в Next.js

В Next.js недостаточно, чтобы агент написал код. Нужно прогнать стандартные проверки. Попросите Claude Code выполнить команды и показать вывод; если он видит ошибку, пусть исправит её до перехода к следующему шагу.

| Проверка | Команда | На что смотреть |
|----------|---------|-----------------|
| Линтер | `pnpm lint` | Ошибки ESLint, unused imports, react-hooks |
| Типы | `pnpm typecheck` | Ошибки TypeScript, импорты между клиентом и сервером |
| Юнит-тесты | `pnpm test` | Vitest/Jest, покрытие изменённых функций |
| E2E | `pnpm test:e2e` | Playwright, реальные сценарии в браузере |
| Сборка | `pnpm build` | Ошибки статической генерации, граница RSC, image domains |

Playwright особенно полезен для Next.js: он проверяет, что страница реально рендерится, а не просто компилируется. Попросите агента запустить `pnpm test:e2e` после крупных рефакторингов и разобрать упавшие сценарии.

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

AgentVera — десктопное приложение, которое запускает реальные CLI-агентов, включая Claude Code, в отдельных терминальных панелях. Для Next.js полезно, что агенты могут работать параллельно в собственных git worktree: один делает новую страницу App Router, другой чинит тесты, и файлы не пересекаются. Автоматическое ревью вторым моделью после завершения хода ловит ошибки на границе серверных и клиентских компонентов. Контрольные точки позволяют откатить неудачный рефакторинг, а лимиты токенов не дают сессии выйти из бюджета.

## Итог

Claude Code в Next.js-проекте экономит время, если вы даёте ему точный контекст через CLAUDE.md и работаете короткими проверяемыми шагами. Самое важное — контролировать границу серверного и клиентского кода, кэширование и реальный запуск тестов. Когда задач становится много, можно распределить их между несколькими агентами — подробнее в [статье о параллельном запуске Claude Code](/ru/blog/run-multiple-claude-code-agents/).

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

**Как подключить Claude Code к существующему Next.js-проекту?** Запустите claude в корне проекта. Агент прочитает CLAUDE.md; для лучших результатов добавьте туда команды lint, test, build и правила App Router.

**Что нужно писать в CLAUDE.md для Next.js?** Команды pnpm lint, pnpm test, pnpm build, структуру папок app/components/lib и правила: где добавлять 'use client', как валидировать данные в route handlers, не редактировать .next и next-env.d.ts.

**Может ли Claude Code сам запускать тесты и линтер в Next.js?** Да, он выполняет терминальные команды. Попросите его запустить pnpm lint, pnpm typecheck или pnpm test и исправить найденные ошибки, прежде чем продолжить.

**Какие типичные ошибки Claude Code делает в Next.js?** Неправильно расставляет 'use client', импортирует серверные модули в клиентский код, игнорирует кэширование и revalidate, возвращает обычный объект из route handler вместо Response.

---

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