main/.ai/conventions/code-health.md

# 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.