Files

S.Gromov 1950c3612a docs: добавить AGENTS.md с инструкциями для AI-ассистента

- Зафиксирована главная директива: следовать стайлгайду перед любой задачей
- Архитектура SLM выделена как сквозной фундаментальный принцип проекта
- Перечислены обязательные к чтению базовые правила и архитектурные документы
- Контекстные разделы делегированы в оглавление стайлгайда без дублирования
- Зафиксированы запреты, правила коммуникации и порядок коммитов

2026-04-28 09:20:37 +03:00

6.2 KiB

Raw Blame History

AGENTS.md

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

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

Перед выполнением любой задачи ассистент обязан свериться со стайлгайдом проекта: 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/README.md. Это источник истины: AGENTS.md не дублирует список разделов, чтобы избежать рассинхронизации. Перед задачей ассистент открывает оглавление стайлгайда и выбирает релевантные разделы (компоненты, страницы App Router, данные REST/realtime, стили, SVG-спрайты, шаблоны и генерация, установка и настройка инструментов и т. д.).

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

Запреты

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

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

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

Коммиты

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

6.2 KiB Raw Blame History Unescape Escape