Рабочие соглашения / Working Conventions¶

Этот файл — единая точка истины о том, как устроен и пишется этот фреймворк. Читается людьми и AI-помощниками. При работе над репозиторием AI-помощникам следует прочитать этот файл первым, прежде чем что-либо менять.

О репозитории¶

Открытый отраслевой фреймворк управления образовательными организациями РФ. Цель — дать сообществу связанные, нормативно обоснованные и практически применимые описания доменов, процессов и данных для ОО любого типа.

Принципы: 1. Нормативная точность важнее красоты. Ссылки на законы — только на актуальные редакции. 2. Связность важнее изоляции. Каждый домен знает свои зависимости. 3. Практика важнее теории. Лучшие практики — реальный опыт ОО, не академические модели. 4. Машиночитаемость важна. Всё, что можно структурировать в JSON/YAML — структурируем.

Языковые соглашения¶

Элемент	Язык
Содержимое `*.md` файлов	Русский
Имена директорий и файлов	Английский, lowercase-hyphenated
ID доменов и процессов	`D01`, `D01-P01`
Ключи в `metadata.yml`	Английский
Значения в `metadata.yml` (текст)	Русский, кроме enum-значений
Ключи в JSON Schema (standards/)	Английский

Тон: формальный, но человеческий. Без канцелярита («следует отметить», «представляется целесообразным»). Объяснять «зачем», а не только «что».

Стандартизованная терминология:

Используем	Не используем
Обучающийся	студент (в общем контексте)
Образовательная организация / ОО	учебное заведение
Учебный план	учебная программа (как синоним УП)
Локальный нормативный акт / ЛНА	внутренний документ
Приказ о зачислении	приказ о поступлении
Аккредитация	аккредитирование

Идентификаторы¶

Домены: D01–D13 — фиксированные, не меняются после присвоения.

Процессы: D01-P01, D01-P02 — сквозная нумерация внутри домена по порядку добавления. Не переиспользуются при deprecation.

Стандарты: FGOS-<уровень>-<направление>-<год>, например FGOS-VO-090301-2021.

Домен	ID	Папка
Нормативно-правовая база	D01	`domains/D01-normative/`
Лицензирование и аккредитация	D02	`domains/D02-licensing/`
Стратегия и планирование	D03	`domains/D03-strategy/`
Образовательная деятельность	D04	`domains/D04-education/`
Управление контингентом	D05	`domains/D05-contingent/`
УМД и контент	D06	`domains/D06-umd/`
Персонал и ППС	D07	`domains/D07-staff/`
Научная деятельность	D08	`domains/D08-research/`
Финансы и ресурсы	D09	`domains/D09-finance/`
Воспитательная работа	D10	`domains/D10-upbringing/`
Коммуникации и публичность	D11	`domains/D11-communications/`
Цифровая инфраструктура и интеграции	D12	`domains/D12-digital/`
Качество и отчётность	D13	`domains/D13-quality/`
Расписание и планирование учебного процесса	D14	`domains/D14-schedule/`

Структура папки домена¶

domains/D01-normative/
├── README.md         ← описание домена, зачем выделен, что входит
├── GUIDE.md          ← как работать с доменом, типовые ошибки, советы
├── metadata.yml      ← машиночитаемые метаданные домена
├── processes/        ← описания процессов домена
│   ├── D01-P01.md
│   └── D01-P02.md
├── data-model/       ← модель данных домена (ERD + описание сущностей)
│   └── entities.md
├── best-practices/   ← лучшие практики от сообщества
│   └── example-01.md
└── CHANGELOG.md      ← история изменений карточки

Все папки кроме best-practices/ обязательны. Без любой из них домен считается незавершённым.

Схема metadata.yml домена¶

См. domains/_TEMPLATE/metadata.yml для канонического примера.

Обязательные поля:

id: D01
title: Нормативно-правовая база
slug: D01-normative
cluster: regulatory          # regulatory | core | staff-science | support | external | crosscutting
version: 0.1.0               # semver
status: draft                # draft | review | stable | deprecated
applicability:               # применимость по типу ОО
  vuz: required              # required | partial | not-applicable
  spo: required
  do: required
  dpo: required
  aspirantura: required
typical_owner: Юридический отдел / Ректорат
last_reviewed: 2026-05-20
review_cycle_months: 6       # нормативка меняется часто

Необязательные, но желательные:

depends_on:                  # ID доменов, от которых зависит
  - D01
related_to:                  # смежные домены
  - D03
regulatory_refs:             # нормативная база
  - "ФЗ-273 — ст. 28"
  - "Приказ Минобрнауки № 1385"
cds_tag: false               # true = ЦОС-процессы присутствуют
gis_integrations:            # внешние ГИС, с которыми взаимодействует
  - ФИС ФРД
  - Суперсервис «Поступление в вуз онлайн»
authors:
  - iMironRU

Невалидный metadata.yml — невалидный PR. Скрипт tools/validate-metadata.py проверяет схему.

Маркеры применимости¶

В таблицах и индексах: - ✓ required — обязательно для данного типа ОО - ◑ partial — применимо частично; детали в metadata.yml → applicability_notes - — not-applicable — не применимо

В тексте процессов: - [ВУЗ] — только для вузов - [СПО] — только для СПО - [ВУЗ, ДПО] — для нескольких типов - (без маркера) — для всех типов ОО

Структура файла процесса (D01-P01.md)¶

# D01-P01: Название процесса

**Домен:** D01 · **Применимость:** ВУЗ, СПО, ДПО
**Статус:** draft | review | stable

## Назначение
Зачем процесс существует, какую задачу решает.

## Нормативное основание
- ФЗ-273, ст. N — краткое описание требования
- Приказ № XXX — описание

## Входы
- Что нужно для запуска процесса

## Шаги
1. Шаг первый
2. Шаг второй

## Выходы / артефакты
- Документ А
- Запись в системе Б

## Участники
| Роль | Действие |
|---|---|
| Ректор | Утверждает |
| Юрист | Проверяет |

## Типовые ошибки
- Ошибка 1 и как её избежать

## Лучшие практики
Ссылки на файлы в best-practices/ или краткое описание.

## Связанные процессы
- D02-P01 — название

Структура раздела standards/¶

standards/
├── README.md               общее описание раздела
├── fgos/
│   ├── README.md           описание формата ФГОС в JSON
│   ├── schema/
│   │   ├── fgos-vo.schema.json     схема для ФГОС ВО
│   │   ├── fgos-spo.schema.json    схема для ФГОС СПО
│   │   └── fgos-do.schema.json     схема для ФГОС ДО
│   └── data/
│       └── <FGOS-ID>.json  конкретный ФГОС
└── fz-273/
    ├── README.md
    └── structure.json      структура статей с привязкой к доменам

ФГОС в JSON используется для: валидации ОПОП, формирования учебных планов, интеграции с ИС, проверки соответствия дисциплин компетенциям.

Жизненный цикл домена¶

draft → review → stable → (deprecated)

draft — в работе, не рекомендуется к использованию в ИС
review — готов, проходит ревью сообщества
stable — рекомендован к использованию
deprecated — устарел; в metadata должен быть superseded_by: DXX

Переход draft → review требует: все обязательные папки и файлы заполнены, metadata.yml валиден. Переход review → stable требует: минимум одно ревью от мейнтейнера.

Использование AI для написания контента¶

AI (Claude, Copilot, GPT) — инструмент для драфтинга. Общие правила:

Давайте AI этот файл в контекст.
Особое внимание: проверяйте номера статей, приказов, дат вступления в силу — AI галлюцинирует нормативку. Непроверенные ссылки — помечайте ⚠.
Помечайте AI-вклад в CHANGELOG: «Изначальный драфт: Claude Opus 4.8, нормативка требует проверки».
Не загружайте данные конкретных ОО — репозиторий публичный.

Режим наполнения (draft phase)¶

Сейчас репозиторий в фазе наполнения: большинство доменов в статусе draft, идёт активная проработка модели. В этой фазе действуют упрощённые правила, чтобы не терять то, что рождается в ходе обсуждений:

AI-помощник (в т.ч. Claude Code) может мёржить свои PR в main, если они содержат только draft-контент и не трогают:
файлы вне domains/DXX/ и standards/ (например, инфраструктура, CI, лицензия)
домены со статусом review или stable
CLAUDE.md, если изменение затрагивает правила (не таблицу доменов)
PR при этом всё равно открывается — как публичный след изменений и для возможности откатить одним махом.
Ревью откладывается — вычитка накопленного будет проведена перед переводом каждого домена в review. До этого момента ⚠-флаги остаются в тексте, не блокируя вклад.
AI-контент помечается в CHANGELOG каждого коммита/PR — прозрачность вклада важна.

Что не отменяется даже в draft phase: - Проверка нормативных ссылок (или явная пометка ⚠). - Запрет на публикацию данных конкретных ОО. - Запрет менять ID доменов/процессов и удалять домены с историей. - Запрет ссылаться на утратившие силу НПА без пометки [утратил силу].

Выход из режима наполнения — по решению @iMironRU, когда основной корпус доменов достигнет статуса review. Тогда возвращается стандартный процесс с обязательным ревью человеком перед мёржем.

Что нельзя делать¶

Менять ID домена или процесса — сломает все ссылки. Только deprecation + новый ID.
Удалять домены с историей — только status: deprecated.
Мёржить в main без PR (даже в draft phase — PR обязателен как след).
Публиковать реальные данные ОО — только анонимизированные примеры.
Ссылаться на утратившие силу редакции НПА без пометки [утратил силу].

Куда смотреть дальше¶

CONTRIBUTING.md — процесс контрибьюции
domains/_TEMPLATE/ — эталонная структура
domains/D05-contingent/ — первый заполненный пример
standards/fgos/ — ФГОС в машиночитаемом формате
inbox/README.md — правила работы с сырыми материалами
implementations/README.md — каталог реализующих фреймворк систем

Служебные разделы репозитория¶

Помимо domains/ и standards/ в корне репо есть две служебные папки:

inbox/ — сырые материалы (концепции, промты, доклады, ZIP-архивы), ожидающие анализа и распределения по доменам. Стремимся держать пустой. Правила — в inbox/README.md.
implementations/ — каталог внешних систем, реализующих концепции фреймворка. Один файл на реализацию с YAML frontmatter (домены, процессы, статус). Служит источником обратной связи фреймворку и ориентиром для сообщества. Правила — в implementations/README.md.

Обратные ссылки: в metadata.yml домена — поле implementations: [<slug>], когда реализация привязана к домену.