# Engineering governance

Это общий owner решений о scope, dependencies, testing и проверке результата.
Работа начинается с задачи пользователя и выполняется напрямую. OpenSpec/SDD
не обязателен; прежняя [процедура](openspec-authority-and-lifecycle.md) доступна
только по явному запросу. Исторические artifacts не переписываются.

## Выбор реализации

Читай этот раздел при новой abstraction/dependency, refactor, multi-module
изменении или неоднозначном ownership.

1. Требуемое поведение уже существует — используй его.
2. У поведения есть подходящий owner/helper — расширь его, сохранив связность.
3. Задачу решает платформа, стандартная библиотека или принятая dependency — используй её.
4. Иначе добавь небольшую реализацию там, где принадлежит инвариант.
5. Если текущая структура мешает правильному ownership, сделай необходимый связный refactor с проверкой сохранения поведения.

Оптимизируй ясность всей системы. Число файлов/строк само по себе не определяет
качество: coherent refactor лучше дублированного guard в нескольких callers.

**Безопасный путь:** при неопределённом будущем reuse оставь код у ближайшего
подходящего владельца. Выделение оправдано текущей общей ответственностью,
несколькими реальными consumers или необходимой trust/transaction boundary.
Один consumer не запрещает модуль с самостоятельным инвариантом, но не оправдывает
interface/factory/registry только для воображаемой расширяемости.

Примеры: фильтр одного экрана остаётся page-local; чистое денежное преобразование
использует существующий decimal helper; запрос Prisma не требует generic repository.
Security validation, доступность, error handling и защита данных сохраняются
даже в маленькой реализации.

## Dependencies

Перед новой dependency проверь installed stack и существующий helper. Если
подходящего решения нет, оцени поддерживаемую библиотеку, совместимость,
maintenance/security cost и точную недостающую возможность. Собственный код
выбирай по совокупной стоимости, а не ради отсутствия dependency любой ценой.

Версии и scripts принадлежат package.json/lockfile. Frontend сохраняет exact
versions; backend использует свою текущую policy. Transitive package не считается
прямо принятой dependency. Не меняй весь lockfile или инструментарий ради
устаревшей рекомендации в Markdown. Новые сервисы, CI и browser mocking требуют
задачи, в которой они действительно нужны.

## Risk-based testing

Автоматический тест обязателен для изменённого security/privacy поведения,
денежных вычислений, data integrity/migration, concurrency, публичного контракта,
критического journey и подтверждённой регрессии.

Выбирай самую дешёвую надёжную границу, наблюдаемую потребителем. Тест нужен
для собственного branching, преобразования или инварианта; не для каждого
DTO, декларативной конфигурации, thin adapter или поведения библиотеки.
Меняющийся тест тоже активирует testing convention, даже без production diff.
Frontend coverage — anti-regression constraint; backend общего threshold не имеет.
Не пиши тесты только ради процента или повторения Markdown.

## Проверка результата

В итерации используй targeted check из применимого convention. Перед завершением
запусти `npm run verify` каждого изменённого code/docs repo под его `.nvmrc`
после lockfile install. Для HTTP contract — дополнительно
[contract checks](runtime-openapi-verification.md). Общего CI сейчас нет.

Проверь actual staged/unstaged/new scope и результат против задачи: ownership,
сохранение данных/контрактов, ошибки, доступность, отсутствие лишних abstractions.
Неизменившийся успешный gate можно использовать повторно, если известны команда,
его полный relevant input scope и неизменные prerequisites; при сомнении выполни
его снова. Auto-fix не заменяет non-mutating gate.

В ответе достаточно: что поставлено, как проверено, какие ограничения остались.
Не создавай role records, fingerprints всех repositories, Completion Evidence
или delivery commits только ради процесса. Существующие рабочие изменения
других задач сохраняются. Нужный review не заменяется количеством checkboxes.

## Guardrails и local gates

- **Автоматический invariant:** существующий deterministic checker блокирует нарушение в фактическом scope с документированными исключениями.
- **Обязательное semantic правило/процедура:** исполнитель и reviewer проверяют решение; отсутствие checker не переводит i18n, validation или authorization в пожелание.
- **Guidance:** необязательное предпочтение, например эстетический выбор между эквивалентными вариантами.

Не обещай enforcement, отсутствующий в config/tests. Новая автоматическая проверка
оправдана реальным риском или повторяющимся дефектом, а не возможностью написать
ещё один checker. Механические правила принадлежат tools; выбор правильного owner
и полезного теста остаётся semantic judgement.

## UI-решения

Для изменяемого UI определи ожидаемые экраны, states, interactions и responsive
поведение из задачи. Используй существующий [каталог](ui-catalog.md) и
[дизайн-систему](design-system.md). Сложный или неоднозначный вариант покажи
пользователю в конкретной форме до дорогой реализации; простой согласованный
вариант делай сразу. Визуальные материалы нужны по задаче, не как обязательный
SDD-пакет. Сборка Storybook не доказывает доступность или визуальное соответствие.

## Изменение опасного контракта

При public/security/data/billing или труднообратимом выборе заранее уточни
существенную неопределённость. Для миграции определи trigger отката, действия,
сохранность уже созданных данных и проверку восстановления. Сначала подготовь
конкретное reviewable решение; обычные обратимые edits не требуют ритуального approval.
Источники и конфликтующие версии разрешай через [context discipline](agent-token-efficiency.md).