---
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) Запрет бездумного переноса паттернов

- Перенос примера/паттерна из другого места допустим только после проверки совместимости:
  - контракты,
  - ожидания типов,
  - окружение/инициализации,
  - интеграционный сценарий.