Ivan Fontosh
70 lines
5.5 KiB
Plaintext
70 lines
5.5 KiB
Plaintext
---
|
||
description: Universal engineering guardrails (contracts, type gates, integration first)
|
||
alwaysApply: true
|
||
---
|
||
|
||
# Универсальные guardrails качества (без привязки к стеку)
|
||
|
||
## 1) Контракты и границы — прежде реализации
|
||
|
||
- Любой модуль/пакет/экспортируемый компонент, который может подключаться отдельно, обязан иметь **явный публичный контракт**:
|
||
- что экспортирует и в каком формате,
|
||
- какие входы/выходы (props, события, параметры),
|
||
- какие сайд‑эффекты,
|
||
- какие зависимости и ожидания окружения.
|
||
- Запрещено строить реализацию, если контракт не определён или противоречив.
|
||
|
||
## 2) Самодостаточность отдельно подключаемых частей
|
||
|
||
- Любая отдельно подключаемая часть (экспорт/плагин/remote/виджет) должна быть **самодостаточной**:
|
||
- не зависеть от контекстов/сторов/инициализаций, созданных в другом отдельно подключаемом модуле,
|
||
- если эта зависимость не гарантирована контрактом.
|
||
- Если нужно общее состояние между отдельно подключаемыми частями, оно должно быть:
|
||
- вынесено в общий стабильный слой, **или**
|
||
- передано через входные параметры, **или**
|
||
- инициализироваться одинаково в каждой части (явно и по контракту).
|
||
|
||
## 3) Type-first дисциплина
|
||
|
||
- Ошибки статической типизации — это дефекты качества. Их нельзя оставлять “на потом”.
|
||
- Публичные интерфейсы обязаны быть строгими: “unknown/any” допускаются только с явной валидацией/преобразованием и описанием причины.
|
||
|
||
## 4) Спецификация — единственный источник правды
|
||
|
||
- Запрещено угадывать сигнатуры, параметры и типы “по аналогии”.
|
||
- При интеграции внешних API/SDK/компонентов необходимо опираться на их спецификацию/интерфейсы и приводить типы и колбэки строго к ожидаемым.
|
||
|
||
## 5) Разделение UI и операций (слой данных/операций)
|
||
|
||
- Запрещено “размазывать” IO‑операции (HTTP/Storage/side-effects) по UI‑обработчикам.
|
||
- Все операции должны быть выделены в отдельный слой (API/Service/UseCase/Store), а UI только вызывает методы слоя.
|
||
- Один endpoint/операция = один метод в слое данных. Дубли запрещены.
|
||
|
||
## 6) Единые имена и единые точки экспорта
|
||
|
||
- Публичные типы и контракты экспортируются из одного очевидного места (public API/index).
|
||
- Запрещены почти одинаковые имена и параллельные версии интерфейсов. Один контракт = один источник правды.
|
||
|
||
## 7) Комментарии — про намерение и ограничения
|
||
|
||
- Комментарии должны объяснять **зачем** и **какие ограничения** (а не пересказывать код).
|
||
- Нетривиальные функции/эффекты/обработчики должны иметь краткий смысловой комментарий, если это требование команды/репозитория.
|
||
|
||
## 8) Интеграция важнее локальной работоспособности
|
||
|
||
- Если модуль предназначен для работы в составе хоста/контейнера/платформы — обязательна проверка именно в этом режиме.
|
||
- “Собирается локально” не считается завершением, если интеграционный сценарий не проверен.
|
||
|
||
## 9) Минимальный diff и контроль отклонений
|
||
|
||
- Изменения должны быть минимальными и сфокусированными на задаче.
|
||
- Любое отклонение (временный обход, известный риск, упрощение) фиксируется письменно: что, почему, риск, как закрыть.
|
||
|
||
## 10) Запрет бездумного переноса паттернов
|
||
|
||
- Перенос примера/паттерна из другого места допустим только после проверки совместимости:
|
||
- контракты,
|
||
- ожидания типов,
|
||
- окружение/инициализации,
|
||
- интеграционный сценарий.
|