Qadam Roadmap
← Назад к библиотеке
проектdocs/governance/engineering-principles.md

Инженерные принципы и правила ведения разработки

Обновлён 1 апр. 2026 г., 12:41 · 0 комментариев

ИсходникСкачать

Инженерные принципы и правила ведения разработки

Паспорт документа

  • Статус документа: living standard
  • Актуально на: 30 марта 2026 года
  • Владелец: backend/platform-команда
  • Пересмотр: при изменении правил разработки, ownership-модели или документационного процесса
  • Область применения: нормативный слой инженерных и документационных правил проекта
  • Связанные документы:

Цель документа

Этот документ фиксирует обязательные инженерные правила Qadam. Проект должен развиваться так, чтобы его можно было без болезненной потери контекста передать другой команде, масштабировать и сопровождать без зависимости от отдельных людей.

Это не рекомендательный текст, а канонический набор принципов, по которым принимаются архитектурные, процессные и эксплуатационные решения.

Главный принцип

Qadam должен строиться как передаваемая система, а не как проект, который держится на памяти текущей команды.

Это означает:

  • знания должны жить в коде, тестах, контрактах и документации;
  • production не должен зависеть от ручных действий “только этот человек знает как”;
  • новая команда должна иметь возможность понять архитектуру, запустить проект, проверить изменения и безопасно продолжить разработку.

1. Принцип передаваемости

Любое важное решение должно быть воспроизводимо и объяснимо без устных договорённостей.

Обязательные следствия

  • нет скрытых серверных правок, которые не отражены в документации;
  • нет критичных процессов, завязанных на локальную память одного разработчика;
  • нет неописанных env-переменных, доменов, секретных зависимостей и обходных путей;
  • новая команда должна получить проект вместе с runbook, roadmap, требованиями, контрактами и тестовым контуром.

2. Один источник истины

У проекта должен быть понятный слой канонической документации.

Канонические документы

  • docs/project/current-state.md — реальное состояние платформы и инфраструктуры;
  • docs/project/requirements.md — текущие продуктовые и инженерные требования;
  • docs/project/roadmap.md — стратегический и ближайший план;
  • docs/project/execution-checkpoints.md — поэтапный фактический статус реализации;
  • docs/project/project-change-log.md — отдельный changelog завершённых change packages;
  • docs/operations/deployment-runbook.md — текущая эксплуатационная модель;
  • docs/architecture/api-routes.md и далее OpenAPI/Swagger — канонический API-контракт;
  • docs/governance/documentation-standard.md — обязательный стандарт структуры и lifecycle канонических markdown-документов;
  • docs/governance/change-package-standard.md — обязательный процесс упаковки, проверки и документирования change package;
  • docs/frontend/frontend-change-log.md — обязательный change-log для frontend-команды по backend API changes;
  • specs/ — детальные решения по конкретным направлениям.

Правило

Если код, инфраструктура и документация расходятся, это считается дефектом проекта, а не “нормальной ситуацией”.

3. Русский язык как канонический язык документации

Вся каноническая проектная документация должна вестись на русском языке.

Это касается:

  • roadmap;
  • runbook;
  • текущего состояния;
  • инженерных требований;
  • правил разработки;
  • проектных планов migration;
  • продуктовых и архитектурных документов в каноническом слое.

Допустимые исключения

  • технические термины, если русская замена ухудшает точность;
  • имена технологий, библиотек, паттернов и API;
  • код, команды, имена переменных, типов и интерфейсов.

Недопустимо

  • держать канонический документ наполовину на русском, наполовину на английском;
  • создавать новый важный документ вне docs/, если он претендует на роль источника истины;
  • сохранять устаревшие англоязычные черновики как “равноправные” версии канонического документа.

Дополнительное правило по change management

Commit messages и итоговые squash merge messages для канонических репозиториев проекта должны формулироваться на русском языке.

Допускается сохранять технические префиксы и scope в conventional commit-стиле, например feat(api): ..., но смысловая часть сообщения должна оставаться русскоязычной и описывать уже достигнутый результат, а не намерение. Предпочтительная форма: добавлен, исправлен, стабилизирован, синхронизированы, вынесен, переведён.

4. Контрактность и явные границы

Проект должен быть разделён на части с явными границами, а не на “удобные на сегодня” импорты между внутренними слоями.

Обязательные правила

  • frontend и backend взаимодействуют через явный API-контракт;
  • DTO, response shape и auth-flow должны быть формализованы;
  • переход к OpenAPI/Swagger обязателен для дальнейшего роста команды;
  • нельзя плодить ручные frontend-типы, если уже есть канонический backend-контракт;
  • нельзя усиливать связанность frontend с внутренними backend/workspace-исходниками, если проект должен быть готов к repo split.

5. Тесты обязательны, а не желательны

Проект должен покрываться тестами детально. Отсутствие тестов на критичные участки считается техническим долгом высокого приоритета.

Обязательная модель покрытия

Unit

Unit-тесты обязательны для:

  • бизнес-логики сервисов;
  • auth-flow;
  • статусных моделей;
  • критичных преобразований данных;
  • доменных инвариантов;
  • багфиксов, которые уже однажды ломались.

Integration

Интеграционные тесты обязательны для:

  • ключевых HTTP endpoint;
  • auth refresh и logout;
  • buyer/seller/admin критичных сценариев;
  • модулей с нетривиальной работой с БД;
  • миграционных и контрактных сценариев, где unit-тест недостаточен.

E2E / Smoke

E2E или минимальный smoke-контур обязателен для:

  • публичного каталога;
  • карточки айтема;
  • login / refresh / logout;
  • buyer profile flow;
  • seller item flow;
  • admin moderation;
  • production health-проверок после деплоя.

Жёсткое правило

Каждый исправленный production-баг должен сопровождаться регрессионной проверкой того уровня, на котором этот баг реально проявлялся.

6. Документация обновляется вместе с кодом

Если изменение влияет на архитектуру, контракты, инфраструктуру, эксплуатацию или roadmap, документация обновляется в том же пакете работ.

Обязательно обновлять

  • current-state.md — если поменялась реальная инфраструктура, домены, сервисы, контур деплоя;
  • requirements.md — если поменялись инженерные или продуктовые требования;
  • roadmap.md — если меняется последовательность больших пакетов разработки;
  • execution-checkpoints.md — если change package меняет фактический статус этапа;
  • project-change-log.md — если завершён значимый change package;
  • deployment-runbook.md — если меняется эксплуатационная модель;
  • api-routes.md и OpenAPI — если меняется API-контракт;
  • frontend-change-log.md — если меняются endpoint'ы, response shape, auth-поведение или другой frontend-значимый API-контракт;
  • frontend feedback loop на qadam-roadmap.2fab.app — если backend-пакет требует действий от frontend-команды и должен попасть в живой operational board;
  • documentation-standard.md — если меняется обязательная структура, lifecycle или quality gate документационного слоя;
  • specs/ — если реализация изменила согласованное проектное решение.

Недопустимо

  • “сделаем потом” для документации на изменениях, которые уже повлияли на систему;
  • держать актуальное состояние только в сообщениях чата или в голове команды;
  • вносить infra/API change без синхронного обновления канонических docs.

7. Definition of Done для каждой значимой задачи

Задача считается завершённой только если одновременно выполнены условия:

  1. Код написан и проходит релевантную сборку.
  2. Добавлены или обновлены тесты нужного уровня.
  3. Обновлена каноническая документация на русском языке.
  4. Если затронут API, обновлён контракт.
  5. Если API-изменение затрагивает frontend-команду, обновлён frontend-change-log.md.
  6. Если frontend должен выполнить действия по этому пакету, пакет опубликован в frontend-блоке на qadam-roadmap.2fab.app, а не остаётся только текстом в changelog.
  7. Если затронута инфраструктура, обновлён runbook и текущее состояние.
  8. Обновлён project-change-log.md, а если этап сдвинулся — execution-checkpoints.md.
  9. Репозиторный quality gate пройден там, где он существует.
  10. Есть понятный rollback или хотя бы оценка риска отката.
  11. Изменение может понять другой разработчик без устного сопровождения автора.

8. Принципы архитектуры и кода

Архитектура

  • предпочитать явные модули и вертикальные срезы вместо хаотичных cross-import;
  • избегать скрытой связанности через общие внутренние пакеты без долгосрочного плана;
  • проектировать систему с учётом будущего frontend repo split и docker-контура;
  • делать transport contract независимым от внутренней структуры репозитория.

Код

  • код должен быть читаемым без археологии по пяти файлам;
  • сложные решения должны сопровождаться кратким объяснением, если без него контекст теряется;
  • нельзя тащить legacy-паттерны в новый слой просто потому, что “так уже было”;
  • багфикс без понимания причины считается незавершённой работой.

9. Инфраструктурные принципы

  • production не должен зависеть от ручной сборки “как получится”;
  • целевая модель — воспроизводимый image-based delivery и управляемый docker-контур;
  • rollout и rollback должны быть описаны явно;
  • домены, TLS, ingress, env и service topology должны быть документированы;
  • server state должен быть минимально “снежинкой” и максимально воспроизводимым.

10. Правила code review и change management

Каждый нетривиальный change оценивается не только по “работает у меня”, но и по следующим критериям:

  • не усиливает ли он связанность;
  • не создаёт ли новый неописанный контур;
  • не ломает ли передаваемость проекта;
  • достаточно ли покрыт тестами;
  • обновлены ли docs;
  • не создал ли он новый drift между кодом и документацией.

Repo-side automation не заменяет review. Машинный quality gate и human review считаются двумя разными обязательными слоями.

Обязательный security review

Для следующих зон security review обязателен даже если unit-тесты и build зелёные:

  • auth, JWT, refresh/logout, cookies и session delivery;
  • permissions, roles, guards и access boundaries;
  • uploads, file storage и публичная раздача файлов;
  • secrets, env, proxy trust, rate limiting и ingress behavior;
  • Prisma migrations, которые трогают PII, auth-данные или статусные модели аккаунтов.

Минимальный operational baseline такого review фиксируется в .gitea/PULL_REQUEST_TEMPLATE.md и не должен обходиться устными комментариями.

Обязательные вопросы к любому большому change

  1. Как это будет поддерживать другая команда через 6 месяцев?
  2. Как это проверить автоматически?
  3. Что нужно обновить в документации?
  4. Что будет точкой отказа при handover?
  5. Как это откатывается?

11. Что запрещено

  • Хранить критичное знание только в головах команды.
  • Держать production-процесс в виде “ручной магии”.
  • Добавлять новый критичный flow без тестового покрытия.
  • Менять API без обновления контракта.
  • Менять или добавлять endpoint'ы без записи в frontend-change-log.md, если эти изменения важны для frontend-команды.
  • Закрывать значимый change package без записи в project-change-log.md.
  • Мержить нетривиальный change без прохождения repo-side quality gate, если он уже заведен для репозитория.
  • Обходить PR review/security checklist для auth, permissions, uploads, proxy, secrets и migration-sensitive изменений.
  • Добавлять новые env/domain/infra зависимости без документирования.
  • Оставлять устаревшие документы как будто они всё ещё канонические.
  • Считать отсутствие документации нормальным состоянием для важных решений.

12. Критерии готовности проекта к передаче другой команде

Проект можно считать реально передаваемым, только если:

  • есть актуальный roadmap и текущее состояние;
  • есть runbook эксплуатации и деплоя;
  • API-контракт формализован;
  • ключевые сценарии покрыты тестами;
  • окружение и зависимости воспроизводимы;
  • frontend и backend можно развивать без скрытых связей;
  • новая команда может поднять проект и продолжить разработку без постоянных устных пояснений.

13. Практический приоритет на ближайшие этапы

Эти принципы прямо означают следующие инженерные приоритеты:

  1. Довести документацию до полностью канонического состояния.
  2. Укрепить тестовый контур, особенно для web.
  3. Формализовать API через OpenAPI/Swagger.
  4. Подготовить frontend к repo split без скрытой связанности.
  5. Перевести delivery в управляемый docker-контур.

14. Как использовать этот документ

Этот документ должен использоваться как baseline при:

  • планировании roadmap;
  • review архитектурных решений;
  • определении Definition of Done;
  • оценке технического долга;
  • подготовке handover другой команде;
  • принятии решений по frontend repo split и docker migration.