frontend/.ai/conventions/engineering.md

Работа в репозитории

Граница и порядок работы

Репозиторий сам содержит инструкции, исходники, конфигурацию и входы своих проверок. Сборка, CI и обязательный маршрут чтения работают без соседних checkout. Внешний API задаётся предоставленным публичным контрактом; исходники или инструкции его реализации не являются зависимостью разработки. При нехватке требования сообщи, какое решение не определено, до его реализации.

Начни с результата и affected areas. До edits проследи flow/invariants, найди owner и 1–3 примера. Код показывает механизм; случайный аналог не меняет контракт. Работай напрямую; OpenSpec/SDD lifecycle — только по явному запросу. Перед Node-командами активируй местную .nvmrc: nvm use --silent. Сохраняй чужие staged/unstaged/untracked изменения и read-only архивы.

Change scope

Сначала расширь существующего владельца. Иначе используй standard library, платформу или установленную dependency; небольшая новая реализация допустима при собственной ответственности. Не создавай helper/interface/wrapper ради возможного reuse. Общее имя не означает общую бизнес-ответственность. Сохраняй validation, authorization, atomicity, accessibility и migration safety.

После diff выполни Boy Scout review: проверь новое дублирование, owner, callers, небольшие связанные legacy issues и соответствие local conventions. Исправляй непосредственно связанные low-risk проблемы; широкий cleanup — отдельная задача.

Domain values

Finite business vocabulary принадлежит одному domain/module/entity owner. Переиспользуй его symbols; для machine codes и protocol values используй строковые enum, для структуры с разными payload — discriminated union. Сохраняй wire values; generated/external enums не переписывай вручную. Numeric policy называй по смыслу и единицам. Индексы, Math.max(value, 0) и обычные labels не выноси в constants без semantic benefit. Локальный TypeScript/lint профиль определяет дополнительные ограничения.

Dependencies

Проверь аналоги и direct dependencies в местном manifest до добавления пакета. Новая dependency оправдана текущей потребностью и меньшей общей сложностью; оцени compatibility, runtime/bundle и maintenance/security. Импортируемый пакет объявляется напрямую; транзитивная установка не является контрактом. Сохраняй exact versions и lockfile; воспроизводимая установка — npm ci. Peer-конфликт решай совместимыми версиями без --force/--legacy-peer-deps. Используй существующий analyzer; не добавляй второй для той же проверки.

Test Intent

Перед нетривиальным тестом кратко определи наблюдаемый исход, regression risk, значимые edge/error/concurrency cases и самую дешёвую надёжную boundary. Отдельный artifact не нужен. Проверяй результат, а не private call order, декларации, тривиальные wrappers или поведение framework. При bug сначала воспроизведи исход. Mock race не доказывает DB atomicity. Уровни и runnable commands выбирай по местной testing convention.

Проверки и завершение

Code/dependency change: npm ci, полный npm run verify и дополнительные risk checks из местной testing convention. Targeted tests ускоряют итерацию, но не заменяют финальный gate. lint:fix/format — edits, не proof. Markdown-only: проверь новые/изменённые тексты, локальные ссылки/якоря, маршруты чтения и git diff --check; application build ради текста не нужен. Повтори routing по staged/unstaged/new files. Запиши краткие команды, результаты и ограничения. Зелёный lint не заменяет semantic/security review.

Git и релизы

Работа — в codex/<task> от актуального develop, затем PR в develop. Сохраняй чужие изменения; перед commit просмотри staged paths и diff. Commits и PR titles — Conventional Commits; допустим spec:. Каждый commit содержит одну связанную задачу. При связанной issue добавь её номер в конец заголовка (fix: … #12); без issue номер не нужен. Root другого checkout не управляет этим repo. Прямой push в main, force-push и перенос опубликованных тегов не входят в обычную работу. Перед release/hotfix прочитай местный README, раздел «Релизы».