ksv741
93dd5539ad
4.9 KiB
Code health и границы изменения
Search → reuse → converge
Перед utility, hook, wrapper, dependency или новым technical pattern:
- Проследи поведение, инварианты и callers у ответственного owner.
- Ищи аналоги по имени и реализации (
rgпо imports, API, выражению). - Расширь подходящий owner/helper/pattern; выбирай минимальное решение, полностью закрывающее текущую задачу. Новый файл сам по себе не улучшение.
Уменьшай количество способов решать одну техническую задачу. Во frontend сравни query keys, formatters, class composition; в backend — pagination, error mapping, repositories и обращения к одному provider. Сходный синтаксис без общей ответственности не требует DRY. Критерий dependency — в dependencies.
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, только когда задача затрагивает 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.