docs: establish workspace engineering conventions

2026-09-15 05:42:02 +03:00
parent 2567a75556
commit 93dd5539ad
11 changed files with 504 additions and 25 deletions
@@ -0,0 +1,68 @@
+# Code health и границы изменения
+
+## Search → reuse → converge
+
+Перед utility, hook, wrapper, dependency или новым technical pattern:
+
+1. Проследи поведение, инварианты и callers у ответственного owner.
+2. Ищи аналоги по имени **и реализации** (`rg` по imports, API, выражению).
+3. Расширь подходящий owner/helper/pattern; выбирай минимальное решение,
+   полностью закрывающее текущую задачу. Новый файл сам по себе не улучшение.
+
+Уменьшай количество способов решать одну техническую задачу. Во frontend
+сравни query keys, formatters, class composition; в backend — pagination,
+error mapping, repositories и обращения к одному provider. Сходный синтаксис
+без общей ответственности не требует DRY. Критерий dependency — в
+[dependencies](dependencies.md).
+
+## Change scope
+
+Consistency с подходящим project pattern предпочтительнее универсальности.
+Новые layers, wrappers, generic helpers, factories, schemas, validators, scripts
+и дополнительные проверки требуют текущей ответственности или риска.
+Сначала используй native API/установленный stack; не строй на гипотетических
+consumers и будущих requirements.
+
+Backend: CQRS, Event Sourcing, Domain Events, Unit of Work, Command Bus,
+generic repositories, abstract factories, custom DI и elaborate domain layers
+не вводятся только ради «best practice». Frontend: wrapper над Mantine, global
+store и дополнительная OpenAPI hash/schema система не создаются автоматически.
+Trust-boundary validation, authorization, atomicity, accessibility и необходимая
+regression proof остаются частью полного решения.
+
+## Boy Scout review
+
+После изменения проверь affected area: новое дублирование, пропущенный helper,
+competing patterns, небольшие связанные legacy issues и conventions.
+Исправляй в рамках задачи только непосредственно связанные, небольшие,
+low-risk, behavior-preserving проблемы, которые легко проверить.
+Более широкие находки сохраняй для отдельной migration; массовый cleanup
+не является условием завершения текущей задачи.
+
+## Persist decisions и ratchet
+
+Устойчивый pattern должен находиться через код и manifest. Добавляй convention,
+только если следующей сессии всё ещё нужно явное project decision rule.
+У каждого правила один owner; AGENTS содержит trigger и ссылку.
+Mental model живёт в `.ai/architecture.md`, intent — в specs, системные знания —
+в docs. Audit/backlog не помещай в conventions.
+
+Legacy фиксируется отдельно; новый diff не добавляет нарушений. При migration
+закрывай подтверждённые baseline findings с evidence, сохраняя область проверки.
+Зелёный lint не доказывает отсутствие semantic debt. Работа с baseline начинается
+с [migration plan](../migrations/conventions-v1/plan.md), только когда задача
+затрагивает migration или найденный там owner.
+
+## Domain values
+
+Finite business vocabulary (status, error code, operation kind, role) принадлежит
+domain/module/entity owner. Перед определением найди существующие types/values;
+в comparisons используй символ владельца, без конкурирующих словарей.
+Для нового project-owned vocabulary без аналога: `as const` + derived union.
+Сохраняй wire values; generated/external enums не переписывай.
+
+Numeric policy называй по смыслу и единицам (`TIMEOUT_MS`, `PAGE_SIZE`).
+Индексы, `index + 1`, `Math.max(value, 0)` и обычные labels/log messages
+не выноси в constants без semantic benefit. Локальный lint/i18n profile всё равно
+применим. Не создавай tests существования констант или custom magic-string analyzer.
+Различия TS/генератора принадлежат local conventions frontend/backend.