Правила SLM
Статус: системный черновик. Не является нормативной спецификацией.
Эта директория является единственным местом объявления правил SLM. Остальные черновики объясняют архитектуру и ссылаются на канонические коды, но не повторяют формулировки правил.
Что считается правилом
Правило задаёт один блокирующий архитектурный инвариант.
Определения, рекомендации, разрешения, примеры и открытые вопросы не получают код правила.
Нормативные определения объявляются в терминологии соответствующего уровня. Они обязательны для толкования правил, но нормативность определения сама по себе не превращает его в правило.
Код правила
SLM-L{level}-{group}-{class}{number}
| Часть | Значение |
|---|---|
SLM |
Принадлежность архитектуре SLM |
L{level} |
Уровень архитектуры |
group |
Раздел правил |
class |
Способ проверки: A или R |
number |
Трёхзначный номер внутри уровня |
Способы проверки
A: автоматическая проверка
Всё правило можно однозначно проверить программно без понимания предметного смысла кода. Нарушение такого правила должно блокировать автоматическую проверку.
R: проверка на ревью
Для окончательного решения требуется понимание ответственности, владения или смысла зависимости. Линтер может проверять отдельные признаки, но не заменяет решение на ревью.
Одно правило не разделяется на автоматическую и ручную копии только из-за разных способов проверки. Если существенная часть инварианта требует смыслового решения, всё правило получает класс R.
Разделы правил
| Код | Раздел |
|---|---|
LAYER |
Слои |
DEPENDENCY |
Зависимости |
MODULE |
Модули |
GROUP |
Группы |
SEGMENT |
Сегменты |
COMPONENT |
Компоненты |
NESTED_MODULE |
Вложенные модули |
LIFECYCLE |
Жизненный цикл |
DOMAIN |
Домены |
BUSINESS |
Контракты бизнес-логики |
FACTORY |
Фабрики бизнес-логики |
ERROR |
Ошибки домена |
PORT |
Порты бизнес-логики |
ADAPTER |
Адаптеры |
PRESET |
Типовые сборки |
ASSEMBLY |
Сборка и экземпляры API |
ENVIRONMENT |
Границы сред выполнения |
FRAMEWORK |
Модули фреймворков |
TEST |
Тестирование |
MIGRATION |
Переход между архитектурными формами |
Код раздела записывается полным английским именем в UPPER_SNAKE_CASE. Новый код добавляется в таблицу до первого использования.
Формат записи
### SLM-L1-MODULE-A004
> **Публичный API модуля**
>
> Каждый модуль предоставляет единый публичный API; код за пределами модуля импортирует его содержимое только через этот API.
Код является заголовком третьего уровня и автоматически получает адрес для ссылки #slm-l1-module-a004.
Название и описание входят в одну цитату. Название выделяется жирным и служит кратким именем правила. Описание полностью формулирует требование и занимает одну физическую строку.
Ссылка из тематического черновика:
[`SLM-L1-MODULE-A004`](../rules/level-1.md#slm-l1-module-a004)
Как формулировать правила
- Правило понятно без чтения тематической главы и опирается только на нормативные термины своего уровня.
- Правило защищает один архитектурный инвариант.
- Один инвариант получает один код независимо от числа участников и способов проверки.
- Название является кратким и устойчивым именем правила.
- Название обозначает предмет правила, а описание полностью формулирует требование.
- Описание объясняет допустимую границу и то, что считается нарушением.
- Описание раскрывает названный инвариант и не вводит второе независимое требование.
- Описание использует нормативные определения и не пересказывает их без необходимости.
- Название и описание используют человеческий язык и только необходимые архитектурные термины.
- Обоснование, подробности, примеры и исключения размещаются в тематическом черновике, а не в описании.
- Правило не создаётся отдельно с позиции владельца и потребителя, если обе формулировки защищают одну границу.
- Перед добавлением правила реестр проверяется на дубли и противоречия.
- Код присваивается после проверки правила на примерах и контрпримерах.
Нумерация
- Номер уникален внутри уровня независимо от раздела и способа проверки.
- Номер не обозначает важность или порядок выполнения.
- Удалённый номер не переиспользуется для другого правила.
- При изменении способа проверки номер сохраняется, но меняется полный код.
Проверка качества
Перед принятием правила нужно ответить «да»:
- Понятно, о чём правило?
- Название кратко и однозначно называет правило?
- Понятно, что оно требует?
- Понятно, что является нарушением?
- Нельзя ли объединить его с существующим правилом?
- Не содержит ли оно рекомендацию или разрешение?
- Соответствует ли класс способу окончательной проверки?
Проверка документов
Корневой скрипт draft-rules.js читает объявления только из этой директории, проверяет формат и уникальность кодов, валидирует ссылки из остальных черновиков и выводит правила разделами «Автоматические» и «Для ревью». Скрипт проверяет документы, а не архитектуру приложения.