4.7 KiB
Code health и границы изменения
Search → reuse → converge
Перед utility, hook, wrapper, dependency или новым technical pattern:
- Проследи поведение, инварианты и callers у ответственного owner.
- Ищи аналоги по имени и реализации (
rgпо imports, API, выражению). - Расширь подходящий owner/helper/pattern; выбирай минимальное решение, полностью закрывающее текущую задачу. Новый файл сам по себе не улучшение.
Уменьшай количество способов решать одну техническую задачу: конфигурацию release-it и commitlint поддерживай средствами этих инструментов. Сходный синтаксис без общей ответственности не требует DRY. Критерий dependency — в dependencies.
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, только когда задача затрагивает 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.