# AGENTS.md

Инструкции для AI-ассистента, работающего с этим проектом.

## Главная директива

Перед выполнением любой задачи ассистент обязан свериться со стайлгайдом проекта: [`ai/nextjs-style-guide/README.md`](./ai/nextjs-style-guide/README.md).

Стайлгайд — единственный источник истины по архитектуре, стеку, оформлению кода и работе с данными. При расхождении между стайлгайдом и пользовательским запросом ассистент задаёт уточняющий вопрос, а не отступает молча.

Запрещено писать код «по общим знаниям Next.js / React / TypeScript». Любое решение принимается по правилам этого проекта.

## Архитектура — фундамент проекта

Архитектура SLM (Scoped Layered Module Design) — **самое важное в проекте**. Это не правило «при создании нового модуля», а сквозной принцип, применяемый **всегда**: при чтении кода, при правке одной строки, при добавлении импорта, при рефакторинге, при обсуждении решения.

Без соблюдения архитектуры проект превращается в бардак. Поэтому каждое действие проверяется на соответствие SLM.

Ключевые принципы, которые ассистент держит в голове постоянно:

- **Строгое разделение бизнес-логики и инфраструктуры.** Инфраструктура (`shared`, API-клиенты, транспорт, конфигурация) ничего не знает о бизнесе. Бизнес-модули используют инфраструктуру только через её публичный API.
- **Направление зависимостей — только сверху вниз по слоям.** Боковые и обратные связи в обход публичного API запрещены.
- **Публичный API модуля — единственная точка входа.** Импорт во внутренности чужого модуля запрещён.
- **Импорты — через алиасы слоёв.** Префикс `@/` не используется.

Перед любым действием ассистент задаёт себе вопросы: к какому слою относится код? Не нарушается ли направление зависимостей? Не смешиваются ли бизнес и инфраструктура? Использую ли я публичный API модуля?

Обязательные к чтению документы по архитектуре:

- [Архитектура: Обзор](./ai/nextjs-style-guide/basics/architecture/index.md)
- [Слои](./ai/nextjs-style-guide/basics/architecture/reference/layers.md)
- [Модули](./ai/nextjs-style-guide/basics/architecture/reference/modules.md)
- [Сегменты](./ai/nextjs-style-guide/basics/architecture/reference/segments.md)

## Базовые правила (читать всегда)

- [Технологии и библиотеки](./ai/nextjs-style-guide/basics/tech-stack.md) — разрешённый стек.
- [Именование](./ai/nextjs-style-guide/basics/naming.md)
- [Стиль кода](./ai/nextjs-style-guide/basics/code-style.md)
- [Типизация](./ai/nextjs-style-guide/basics/typing.md)
- [Документирование](./ai/nextjs-style-guide/basics/documentation.md)

## Контекстные разделы (читать по теме задачи)

Полный перечень разделов стайлгайда — в его оглавлении: [`ai/nextjs-style-guide/README.md`](./ai/nextjs-style-guide/README.md). Это источник истины: AGENTS.md не дублирует список разделов, чтобы избежать рассинхронизации. Перед задачей ассистент открывает оглавление стайлгайда и выбирает релевантные разделы (компоненты, страницы App Router, данные REST/realtime, стили, SVG-спрайты, шаблоны и генерация, установка и настройка инструментов и т. д.).

При появлении новых разделов в стайлгайде ассистент учитывает их автоматически — через оглавление, без правок этого файла.

## Запреты

- Импорт во внутренности чужих модулей в обход публичного API.
- Бизнес-логика в `shared`; инфраструктура внутри бизнес-модулей.
- Прямые `fetch` или `useSWR` в компонентах. В клиентских компонентах данные получают только через хуки модуля API; в серверных — прямым вызовом метода API-клиента.
- Использование зависимостей вне [tech-stack.md](./ai/nextjs-style-guide/basics/tech-stack.md) без согласования с пользователем.
- Префикс `@/` в импортах — все пути идут через алиасы слоёв.
- Отступления от стайлгайда «ради скорости» или «потому что так короче».

## Коммуникация

- Язык общения — русский.
- При неоднозначности задачи — уточняющий вопрос, без догадок.

## Коммиты

Коммиты создаются по правилам семантических коммитов через skill `commit`.