Перейти к содержанию

Правила командной работы в проекте Konstructorium

Назначение

Эта страница фиксирует операционные правила команды в формате что делаем -> как делаем -> почему это обязательно. Документ применяется ко всем сервисам, frontend, tests, scripts и связанным изменениям документации.

Нормативная база

1. Что делает команда

  1. Разрабатывает и поддерживает микросервисную платформу с едиными инженерными стандартами.
  2. Поддерживает стабильные API-контракты между сервисами и клиентами.
  3. Обеспечивает трассируемое качество: код, тесты, документация и эксплуатационные процедуры.
  4. Управляет изменениями так, чтобы снижать регрессионные риски и стоимость сопровождения.

2. Как именно команда это делает

2.1 Работа с кодом

  • Что: каждый merge-пулл реквест соответствует единому код-стайлу.
  • Как: обязательные docstring/JSDoc, семантический нейминг, явная обработка ошибок, отсутствие мертвого кода.

  • Почему: это уменьшает операционные инциденты и ускоряет ревью.

  • Что: любые исключения из правил фиксируются явно.

  • Как: в PR указывается причина, риск, владелец и срок пересмотра исключения.
  • Почему: неформальные исключения размывают стандарт и повышают энтропию кода.

2.2 Работа с контрактами и API

  • Что: изменение API всегда синхронизируется с документацией и тестами.
  • Как: при изменении endpoint/формата payload обновляются сервисные docs и smoke/integration checks.
  • Почему: рассинхронизация контрактов является частой причиной межсервисных регрессий.

2.3 Работа с качеством

  • Что: команда проверяет изменения до передачи в ревью.
  • Как: локальный прогон проверок, устранение lint/style проблем, ручная валидация критических сценариев.
  • Почему: дефекты дешевле устранять до объединения изменений в основную ветку.

2.4 Работа с документацией

  • Что: документация ведется как часть определения готовности.
  • Как: изменения архитектуры, API и процедур сопровождаются обновлением соответствующих страниц docs/.
  • Почему: неактуальная документация увеличивает риск неверных решений в разработке и эксплуатации.

3. Формальные правила для участников команды

  1. Нельзя вносить изменения в API без обновления документации и проверок.
  2. Нельзя добавлять код без описательных docstring/JSDoc в публичных точках расширения.
  3. Нельзя подавлять ошибки без диагностического контекста и обоснования.
  4. Нельзя оставлять debug-логи, неинформативные имена и временные костыли без задачи на устранение.
  5. Нельзя считать задачу завершенной, если не подтверждена согласованность кода и документации.

4. Доказательная база (почему правила обязательны)

  • Снижение дефектности: формальные контракты и документирование уменьшают долю интеграционных ошибок.
  • Снижение MTTR: явная обработка ошибок и диагностические сообщения ускоряют расследование инцидентов.
  • Сокращение стоимости изменений: единый стиль кода уменьшает время входа в чужие модули.
  • Повышение предсказуемости релизов: синхронизация кода, тестов и docs снижает риск «скрытых» breaking changes.

5. Проверяемость правил

Каждый пункт проверяется по схеме: 1. Определена зона изменений (файлы, модули, контракты). 2. Подтверждено соответствие код-стайлу и соглашениям документирования. 3. Подтверждена синхронизация docs с фактическим поведением. 4. Зафиксированы исключения (если есть) и их жизненный цикл.

6. Definition of Done для изменений

Изменение считается завершенным только если: - код соответствует корпоративному стандарту; - для измененных сущностей есть docstring/JSDoc и полезные комментарии по нетривиальной логике; - документация обновлена синхронно с кодом; - проверки не показывают системных нарушений в области изменения; - остаточные риски явно описаны и приняты.