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

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

Практическое руководство по Codex в Next.js: настройка AGENTS.md, серверные и клиентские компоненты, route handlers, тесты и проверка изменений.

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

- Codex запускается командой codex и читает AGENTS.md из корня репозитория.
- Для Next.js важно явно описать правила серверных и клиентских компонентов и маршрутов.
- Проверяйте изменения агента через lint, тесты, сборку и ревью диффов.

Codex в проекте Next.js запускается командой `codex` из корня репозитория и работает с файлами, git и терминалом. Чтобы получить предсказуемый результат в App Router, Pages Router, route handlers и тестах, зафиксируйте команды и конвенции в AGENTS.md и работайте короткими итерациями с проверкой диффов. Подробнее о самом агенте — в [Codex](/ru/agents/codex/).

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

Codex хорошо справляется с типовым Next.js-кодом: иерархия `app/` или `pages/`, серверные и клиентские компоненты, route handlers, server actions, работа с `next.config`, ESLint и TypeScript. Агент умеет запускать `pnpm test`, `pnpm lint`, `pnpm build` и читать ошибки компилятора, поэтому цикл «изменил — проверил — исправил» проходит без ручного переключения между терминалами. Для Next.js это важно из-за большого числа неявных правил: граница server/client, кеширование `fetch`, статическая генерация и динамические API. Если правила описаны в AGENTS.md, Codex применяет их при каждой правке, а не генерирует код по общим паттернам React.

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

Codex читает AGENTS.md из корня проекта. Для Next.js туда нужно положить не только команды, но и жёсткие правила, которые предотвращают типовые ошибки: лишние `'use client'`, прямые запросы из клиента к базе или секретам, неверные route handlers, игнорирование ESLint. Не пишите длинный манифест — агент должен видеть короткий список обязательных проверок. Пример:

```markdown
# AGENTS.md

## Команды
- Установка: `pnpm install`
- Dev: `pnpm dev`
- Линт: `pnpm lint`
- Тесты: `pnpm test`
- Сборка: `pnpm build`

## Конвенции
- App Router, TypeScript, строгий ESLint.
- Компоненты по умолчанию серверные; `'use client'` только при хуках, обработчиках или браузерных API.
- Вся серверная логика и запросы к БД — в server components, route handlers или server actions.
- Route handlers — в `app/api/**/route.ts`, ответы — `NextResponse.json`.
- Не используем `fetch` в клиентских компонентах для секретов; только через route handlers.
- Перед завершением задачи запускать `pnpm lint`, `pnpm test`, `pnpm build`.
```

Правило `'use client'` только при хуках убирает лишний клиентский JavaScript. Указание route handlers в `app/api/**/route.ts` не даёт агенту положить API-логику в компонент. Команда `pnpm build` обязательна, потому что ловит ошибки типов и несовместимость с серверными компонентами. Если в проекте Pages Router, замените эти правила на структуру `pages/api` и `getServerSideProps`/`getStaticProps`. Пошаговый запуск и базовые сценарии описаны в [Как пользоваться Codex CLI: пошаговое руководство](/ru/blog/how-to-use-codex-cli/).

## Рабочий цикл

С Codex работайте как с сильным младшим разработчиком: сначала план, затем маленькая реализация, затем проверка. Не просите «сделай страницу со всеми фичами» — попросите показать план, обсудить типы и только потом писать код. После каждого шага запускайте `pnpm lint`, `pnpm test`, `pnpm build` и просматривайте `git diff`. Если что-то падает, возвращайте агенту вывод ошибки полностью. Фиксируйте состояние в git до и после каждой итерации, чтобы было легко откатить неудачную правку.

Примеры рабочих промптов:

- «Добавь страницу `/dashboard` в App Router. Сначала покажи план: файлы, типы, источник данных. Затем создай серверный компонент и заглушку для загрузки.»
- «Найди все клиентские компоненты, которые вызывают `fetch` напрямую, и перенеси вызовы в route handlers. Действуй по одному файлу, после каждого показывай diff.»
- «Напиши route handler `GET /api/posts` с пагинацией через searchParams. Добавь Zod-валидацию, верни корректные статусы и учти кеш Next.js.»
- «Покрой серверный action для формы создания поста тестом Vitest. Сначала скажи, какой именно файл теста создашь, затем реализуй и запусти `pnpm test`.»
- «Исправь ошибки TypeScript, которые появляются при `pnpm build`. Покажи список ошибок и предложи минимальные правки, не меняя поведение.»

## Типичные задачи и узкие места

Codex уверенно создаёт новые route handlers, страницы, серверные actions, Zod-схемы, тесты Vitest/Jest и Playwright-сценарии. Хуже всего агент чувствует неявные правила Next.js. Смотрите прежде всего на границу серверного и клиентского кода, кеш route handlers, `revalidatePath`, `dynamic` и `export const runtime`, а также на то, как агент обрабатывает `next/image` и переменные окружения.

| Типовая задача | На что смотреть в diff |
| --- | --- |
| Добавление `'use client'` | Не переносит лишние серверные данные; не помечает всю страницу клиентской |
| Route handler | `export const dynamic` / кеш; корректные статусы и `NextResponse` |
| Server actions | Валидация на сервере, `revalidatePath`, отсутствие секретов в клиенте |
| `next/image` | Настройка `images.remotePatterns`; не заменяет на `<img>` без причин |
| Тесты | Мокает ли `next/navigation`, не тестирует ли implementation detail |

В Pages Router дополнительно проверяйте, что data fetching остался в `getServerSideProps`/`getStaticProps`, а не попал в компонент. В App Router смотрите, чтобы серверные компоненты не импортировали хуки, а клиентские не тянули серверные модули с секретами. Частые ошибки — гидратация из-за `Date.now()` или `Math.random()` в рендере, а также неправильное кеширование `GET`-route handlers. Полезно включить автоматическое ревью кода с ИИ, чтобы ловить такие неявные ошибки — подробнее в [Ревью кода с ИИ: проверяйте то, что пишут агенты](/ru/blog/ai-code-review/).

## Тестирование и проверка

Обязательно заставьте Codex прогонять проверки в каждой итерации. Для Next.js минимальный набор: `pnpm lint`, `pnpm test`, `pnpm build`. Если есть Playwright, добавьте e2e-сценарии для критических пользовательских путей: логин, создание записи, поиск. Агент может запускать конкретный spec: `pnpm exec playwright test tests/dashboard.spec.ts`. Попросите его читать вывод целиком и исправлять только реальные ошибки, а не подавлять правила ESLint. Отдельно проверяйте, что после изменений не сломалась статическая генерация: запустите `pnpm build` с `output: 'export'`, если используете статический экспорт. Для компонентов с взаимодействием просите тесты на уровне поведения, а не реализации: проверять, что форма отправляет данные и показывает ошибку, полезнее, чем проверять вызовы внутренних функций.

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

AgentVera — это десктопное приложение, которое запускает реальные CLI-инструменты агентов, включая Codex, бок о бок в одном окне. Для Next.js полезны три вещи. Параллельные агенты в отдельных git worktree не перезаписывают файлы друг друга и позволяют одновременно делать фичу и чинить тесты. Автоматическое ревью после завершения хода агента показывает находки с ссылками на file:line — это быстрее находит ошибки серверных и клиентских компонентов. Контрольные точки каждого хода можно откатить одним кликом и проиграть сессию по шагам, что безопасно при экспериментах с кешированием и RSC.

## Вывод

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

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

**Как запустить Codex в проекте Next.js?** Установите Codex и запустите команду codex из корня проекта. Создайте AGENTS.md с командами сборки, тестов и правилами серверных и клиентских компонентов, чтобы агент сразу следовал конвенциям.

**Может ли Codex работать с App Router и серверными компонентами?** Да, если в AGENTS.md указано, что компоненты по умолчанию серверные, а 'use client' добавляется только при необходимости. Агент может генерировать страницы, route handlers и server actions.

**Как проверять код, который Codex написал для Next.js?** Запускайте pnpm lint, pnpm test и pnpm build после каждой итерации. Для UI-логики добавляйте Playwright-тесты и проверяйте diff на ошибки гидратации и кеширования.

**Почему Codex путает клиентские и серверные компоненты?** Обычно из-за того, что правила не зафиксированы в AGENTS.md. Добавьте явные инструкции: серверные по умолчанию, client только для хуков и браузерных API, запросы к API только через route handlers.

---

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