diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d8c0bbb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,65 @@ +# 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`.