S.Gromov
1950c3612a
- Зафиксирована главная директива: следовать стайлгайду перед любой задачей - Архитектура SLM выделена как сквозной фундаментальный принцип проекта - Перечислены обязательные к чтению базовые правила и архитектурные документы - Контекстные разделы делегированы в оглавление стайлгайда без дублирования - Зафиксированы запреты, правила коммуникации и порядок коммитов
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`.
|