66 lines
4.7 KiB
Markdown
66 lines
4.7 KiB
Markdown
# Code health и границы изменения
|
||
|
||
## Search → reuse → converge
|
||
|
||
Перед utility, hook, wrapper, dependency или новым technical pattern:
|
||
|
||
1. Проследи поведение, инварианты и callers у ответственного owner.
|
||
2. Ищи аналоги по имени **и реализации** (`rg` по imports, API, выражению).
|
||
3. Расширь подходящий owner/helper/pattern; выбирай минимальное решение,
|
||
полностью закрывающее текущую задачу. Новый файл сам по себе не улучшение.
|
||
|
||
Уменьшай количество способов решать одну техническую задачу: конфигурацию
|
||
release-it и commitlint поддерживай средствами этих инструментов. Сходный синтаксис
|
||
без общей ответственности не требует DRY. Критерий dependency — в
|
||
[dependencies](dependencies.md).
|
||
|
||
## Change scope
|
||
|
||
Consistency с подходящим project pattern предпочтительнее универсальности.
|
||
Новые layers, wrappers, generic helpers, factories, schemas, validators, scripts
|
||
и дополнительные проверки требуют текущей ответственности или риска.
|
||
Сначала используй native API/установленный stack; не строй на гипотетических
|
||
consumers и будущих requirements.
|
||
|
||
Не вводи shared tooling для других репозиториев как обязательную зависимость
|
||
их сборки, CI или маршрута инструкций. Каждый repo владеет своими checks.
|
||
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 и ссылку.
|
||
Устройство root tooling находится в README и конфигурации; их чтение не
|
||
требует соседних checkout. 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.
|
||
Правила приложений принадлежат их локальным conventions.
|