Зачем нужен CLAUDE.md в Next.js-проектах
Next.js использует множество соглашений, которые сложно определить только по структуре файлов: разделение серверных и клиентских компонентов, места для получения данных, подходы к тестированию. Без краткого руководства AI-ассистент часто делает неверные предположения, что приводит к ошибкам и потере времени. Файл CLAUDE.md — это компактная инструкция, которая устраняет неопределённость и помогает модели действовать в рамках принятых в проекте правил.
Оптимальный шаблон CLAUDE.md (около 40 строк)
Ниже представлен лаконичный шаблон, который легко адаптировать под свой проект:
# Project: [name] (Next.js [version], App Router, TypeScript)
## Commands
- Dev: `npm run dev`
- Typecheck: `npx tsc --noEmit`
- Lint: `npm run lint`
- Test: `npm test -- --run`
- Build: `npm run build` (обязательно перед завершением задачи)
## Layout
- `app/` — маршруты и лейауты. По умолчанию — Server Components.
- `components/` — общие UI-компоненты. `components/ui/` — библиотечные примитивы, не редактировать.
- `lib/` — доступ к данным и хелперы. Не размещать получение данных внутри компонентов, если это можно вынести сюда.
- `app/api/` — обработчики маршрутов. Валидация ввода через [zod/иное].
## Rules
- Добавлять "use client" только при необходимости состояния, эффектов или браузерных API. Помещать в самый нижний компонент.
- Получать данные в Server Components или `lib/`, не использовать useEffect для начальной загрузки.
- Переменные окружения: по умолчанию серверные. Только NEXT_PUBLIC_ доступны клиенту.
- Не устанавливать новые зависимости без согласования.
- Не редактировать .next/ и сгенерированные файлы.
## Done means
- Typecheck, lint и тесты проходят, сборка успешна.
- Новое поведение покрыто тестом или есть обоснование, почему теста нет.
Почему структура именно такая
Commands
Указание точных команд, включая флаги, гарантирует, что AI-ассистент использует ваш реальный тестовый раннер и сборку, а не придумывает собственные варианты. Это исключает ошибки, связанные с несовпадением инструментов.
Layout
В этом разделе описываются только неочевидные директории. Если назначение папки понятно из названия (например, styles, public), её можно не упоминать. Это экономит место в контексте и не перегружает модель лишней информацией.
Rules
Здесь фиксируются правила, которые вы обычно повторяете вручную. Особое внимание уделено разграничению серверных и клиентских компонентов: требование добавлять "use client" только при реальной необходимости и как можно ближе к листу компонента существенно снижает количество ненужных клиентских компонентов. Также важно, что получение данных должно происходить в Server Components или в lib/, а не через useEffect — это соответствует лучшим практикам Next.js App Router.
Done means
Чёткое определение критериев завершённости задачи (успешные проверки типов, линтер, тесты и сборка) даёт модели понятную точку остановки. Требование покрытия нового поведения тестом или наличие обоснования для его отсутствия поддерживает качество кода.
Как поддерживать лаконичность CLAUDE.md
Каждый пункт файла загружается в контекст AI-ассистента при каждом обращении. Если какое-то правило уже контролируется ESLint или TypeScript, его можно смело убирать из CLAUDE.md — нет смысла дублировать то, что и так не пропустит сборка. Многошаговые процедуры (например, отладка, рефакторинг, написание PR-описаний) лучше выносить в отдельные skills, которые подгружаются только по запросу, чтобы не раздувать основной файл.
Практические рекомендации
- Регулярно обновляйте CLAUDE.md при изменении структуры проекта или команд.
- Не включайте в файл очевидные вещи — только то, что действительно требует пояснения для ассистента.
- Используйте секцию Rules для фиксации самых частых ошибок, которые допускает AI в вашем проекте.
- Проверяйте, чтобы все команды были актуальны и работали в вашей CI/CD.
Такой подход позволяет AI-ассистенту работать максимально эффективно, не нарушая архитектурные и технические стандарты вашего Next.js-проекта.