Руководство по заполнению карточки домена¶

Этот файл объясняет как правильно заполнять TEMPLATE.md и metadata.yml. Читайте его перед тем как открывать PR с новой карточкой.

Шаг 1 — Получите ID и согласуйте домен¶

Откройте Issue с шаблоном «Новый домен». Опишите: - Что покрывает домен - В какой кластер входит - Почему не входит в существующий домен

Получите ID и одобрение мейнтейнера. Без этого шага — нет смысла делать PR.

Шаг 2 — Скопируйте шаблон¶

cp -r domains/_TEMPLATE domains/D<NN>-<slug>

Переименуйте папку по формату: D<NN>-<slug>, где slug — краткое название на английском, lowercase-hyphenated. Например: D04-educational-activity.

Шаг 3 — Заполните metadata.yml¶

Обязательные поля — всегда. Рекомендуемые — для статуса review+. Проверьте валидность перед PR:

python tools/validate-metadata.py domains/D<NN>-<slug>/metadata.yml

Шаг 4 — Заполните TEMPLATE.md¶

Секция 1 (Нормативная база): минимум 2 НПА. Проверяйте актуальность ссылок — законы меняются. Ссылайтесь на consultant.ru или официальные источники.

Секция 2 (Процессы): достаточно списка на старте. Полные описания процессов добавляйте постепенно в папку processes/. Каждый процесс — отдельный файл.

Секция 3 (Данные и сущности): ключевые сущности — это то, что ИС должна хранить и обрабатывать в рамках домена. Начните с 3–5 главных сущностей. Полную модель данных выносите в data-model/entities.md.

Секция 4 (Лучшие практики): опционально при draft, желательно при review. Структура: контекст → проблема → решение → результат. Одна практика — один блок.

Секция 5 (Риски): минимум 2–3 типовых риска для вашего домена.

Секция 6 (Связи): обязательно. Без связей карточка изолирована и теряет ценность для понимания фреймворка как системы.

Шаг 5 — Заполните README.md¶

README.md домена отвечает на вопрос: «зачем этот домен существует как отдельная единица?». 3–5 абзацев, без списков. Это не пересказ TEMPLATE.md — это контекст и мотивация выделения домена.

Шаг 6 — Создайте CHANGELOG.md¶

Минимальная запись:

## 0.1.0 — YYYY-MM-DD
- Первая версия карточки домена
- Автор: @github-username

Шаг 7 — Откройте PR¶

Используйте PR-шаблон из .github/PULL_REQUEST_TEMPLATE.md. Один PR — одна карточка домена или одно осмысленное изменение.

Частые ошибки¶

Слишком широкий домен. Если в секции «Процессы» больше 15 позиций — возможно, домен стоит разбить. Обсудите в Issues.

Копипаста из законов. Не копируйте текст НПА. Кратко опишите что регулирует норма применительно к домену. Ссылку достаточно.

Нет связей. Если секция 6 пустая — скорее всего вы что-то пропустили. Каждый домен связан как минимум с D01 (нормативная база) и D13 (качество).

Устаревшие ссылки на НПА. Проверяйте редакцию на момент написания. Указывайте дату последней актуальной редакции в metadata.yml → last_reviewed.

AI без ревью. Сгенерированный драфт без проверки ссылок на НПА — частый источник ошибок. Всегда проверяйте регуляторные ссылки руками.