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

Для работы с Next.js 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:

# 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.

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

Не просите агента сразу переписать половину приложения. Работайте короткими шагами: сначала попросите план, затем маленькое изменение, затем запуск проверок, затем просмотр diff. Это снижает риск получить нерабочую сборку и упрощает откат. Можно попросить Claude Code сначала предложить план, не меняя код, — режим планирования описан в отдельной статье.

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

• «Сначала план: что нужно изменить в 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 выполнить команды и показать вывод; если он видит ошибку, пусть исправит её до перехода к следующему шагу.

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.