66 lines
6.2 KiB
Markdown
66 lines
6.2 KiB
Markdown
|
# 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`.
|