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

Codex в проекте Next.js запускается командой codex из корня репозитория и работает с файлами, git и терминалом. Чтобы получить предсказуемый результат в App Router, Pages Router, route handlers и тестах, зафиксируйте команды и конвенции в AGENTS.md и работайте короткими итерациями с проверкой диффов. Подробнее о самом агенте — в 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. Не пишите длинный манифест — агент должен видеть короткий список обязательных проверок. Пример:

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

Рабочий цикл

С 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 и переменные окружения.

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

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

Обязательно заставьте 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, тесты и сборку, и смотрите на границы серверного и клиентского кода. Тогда агент ускоряет рутинные задачи, а не создаёт новые баги.