chore: cursor agents, rules, hooks and workspace docs

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-11 22:20:28 +08:00
parent 01cde7476c
commit a58732f78a
25 changed files with 1016 additions and 261 deletions
@@ -0,0 +1,69 @@
+---
+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) Запрет бездумного переноса паттернов
+
+- Перенос примера/паттерна из другого места допустим только после проверки совместимости:
+  - контракты,
+  - ожидания типов,
+  - окружение/инициализации,
+  - интеграционный сценарий.