From 1950c3612a0e6183b2e826c151b3280682ed91ba Mon Sep 17 00:00:00 2001 From: "S.Gromov" Date: Tue, 28 Apr 2026 09:20:37 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20AGENTS.md=20=D1=81=20=D0=B8=D0=BD=D1=81=D1=82?= =?UTF-8?q?=D1=80=D1=83=D0=BA=D1=86=D0=B8=D1=8F=D0=BC=D0=B8=20=D0=B4=D0=BB?= =?UTF-8?q?=D1=8F=20AI-=D0=B0=D1=81=D1=81=D0=B8=D1=81=D1=82=D0=B5=D0=BD?= =?UTF-8?q?=D1=82=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зафиксирована главная директива: следовать стайлгайду перед любой задачей - Архитектура SLM выделена как сквозной фундаментальный принцип проекта - Перечислены обязательные к чтению базовые правила и архитектурные документы - Контекстные разделы делегированы в оглавление стайлгайда без дублирования - Зафиксированы запреты, правила коммуникации и порядок коммитов --- AGENTS.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 AGENTS.md 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`.