104 lines
8.9 KiB
Markdown
104 lines
8.9 KiB
Markdown
# 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).
|