sync

docs/ru/guides/AGENTS.md

@@ -0,0 +1,78 @@
+# Правила гайдов быстрого старта
+
+## Цель
+
+Гайд должен помочь читателю как можно быстрее создать SVG-спрайт и использовать его в своём приложении.
+
+Спрайт является главным результатом. Компоненты и другие сгенерированные файлы описываются только как средства его использования.
+
+## Область гайда
+
+Каждый гайд посвящён одному exact mode.
+
+В гайд включаются только действия и особенности, относящиеся к этому mode. Нельзя переносить в него поведение других сборщиков, фреймворков или modes.
+
+Все технические утверждения необходимо проверять по реализации соответствующего adapter.
+
+## Структура
+
+Гайд состоит из трёх основных частей:
+
+1. Генерация спрайта.
+2. Использование спрайта.
+3. Дебаг и превью через Viewer.
+
+Первая строка после заголовка должна объяснять, что это инструкция по быстрому созданию SVG-спрайта и для какого приложения она предназначена.
+
+## Примеры
+
+Все примеры внутри гайда должны составлять один последовательный сценарий.
+
+Пути, имена, команды, импорты и названия сгенерированных API должны соответствовать друг другу и фактическому результату генерации.
+
+Во всех гайдах используются согласованные примеры:
+
+- исходные SVG находятся в `assets/svg-icons`;
+- спрайт создаётся в `assets/app-icons`;
+- конфиг записывается в JSON;
+- имя спрайта в конфиге — `app`.
+
+## Зависимости
+
+В разделе генерации нужно явно показать ключевое преимущество: для создания и использования спрайта пакет не требуется добавлять в зависимости проекта.
+
+Viewer описывается отдельно как необязательный инструмент разработки. Установка или подключение пакета допускается только в разделе Viewer и только способом, подходящим текущему mode.
+
+## Содержание
+
+Гайд должен содержать только минимальный рабочий путь:
+
+- структуру проекта;
+- конфиг;
+- команду генерации;
+- автоматическую генерацию перед запуском и сборкой, если она необходима;
+- подключение иконки;
+- базовую настройку размера и цветов;
+- подключение Viewer.
+
+Особенности mode добавляются только тогда, когда без них пример не работает или работает неправильно.
+
+## Технический шум
+
+Не нужно описывать внутреннее устройство генератора, сгенерированных файлов и сборщика.
+
+Не нужно перечислять альтернативные конфигурации, дополнительные API, редкие сценарии и ограничения, не относящиеся к быстрому старту.
+
+Подробности должны оставаться в reference-документации.
+
+## Стиль
+
+Писать для пользователя, а не для разработчика библиотеки.
+
+Использовать короткие, прямые и практические формулировки.
+
+Сначала объяснять пользу или цель шага, затем показывать действие.
+
+Не использовать воду, рекламные формулировки и технические термины, которые не помогают выполнить инструкцию.
+
+Не начинать документ с перечисления сгенерированных компонентов или особенностей реализации.