Контекст как актив: почему it-продукт нельзя передать без документации

Код можно передать за один день. Контекст проекта — нет. Когда продукт развивается несколько лет, самая ценная его часть оказывается не в репозитории. Бизнес-правила, ограничения, договоренности и причины принятых решений обычно существуют отдельно от кода.

Поэтому при смене команды теряется не система, а понимание того, как и почему она работает. Документация превращает этот контекст из знания команды в актив компании.

Почему новый подрядчик начинает почти с нуля 

Когда разработчик смотрит на чужой код без документации, он видит что происходит. Но не видит почему.

Почему эта кнопка появляется только при определенных условиях? Почему вот этот статус не переключается автоматически? Почему при регистрации нельзя использовать корпоративную почту?

За каждым таким «почему» стоит: требование безопасности, ограничение платежной системы, решение, принятое на созвоне год назад и нигде не записанное.

Код фиксирует результат. Документация фиксирует смысл. Когда смысл утерян, любое изменение в продукте — это риск: никто не знает, что еще сломается.

Как это выглядит на практике

В MWI обратился клиент с образовательным маркетплейсом Course.Tours с концепцией «обучение + путешествия». За год разработки в продукте накопилось много бизнес-правил: логика расписаний, роли пользователей, механики бронирования, оплаты и проведения занятий. Проект развивала другая команда, но значительная часть этих решений нигде не была зафиксирована.

Уже на этапе аудита выяснилось, что логика платежного флоу нигде не описана. Код показывал, как работает процесс, но не объяснял, какие сценарии предусмотрены и какие бизнес-правила стоят за его реализацией.

В результате обнаружилась критическая проблема. Оплата криптовалютой засчитывалась сразу после нажатия кнопки — без проверки фактического поступления средств. Об этом мы рассказали в предыдущей статье. Спойлер: Пользователь мог получить доступ к курсу, ничего не заплатив.

Клиент остановил запуск. А для команды стало очевидно: прежде чем развивать продукт дальше, нужно зафиксировать бизнес-логику, требования и правила работы системы в документации.

Из чего состоит передаваемая документация

Когда говорят «документация», обычно представляют README или комментарии в коде. На практике это три разных слоя, у каждого своя задача.

AS IS / TO BE

Первый слой документации — описание текущего и целевого состояния продукта. 

Любая передача продукта начинается с фиксации текущей логики. Для этого создается модель AS IS.

В Course.Tours в документе «Оплата AS IS» было зафиксировано, что система засчитывает криптоплатеж без проверки фактического поступления средств. Не как баг, а как существующее поведение системы.

После этого формировалась модель TO BE — описание того, как процесс должен работать после изменений. В случае с платежами в нее уже входила проверка поступления средств и сценарии обработки статусов оплаты.

Пользовательские сценарии 

Следующий слой документации фиксирует поведение системы в конкретных пользовательских сценариях.

Например, формулировка «студент входит в комнату видеоурока» не объясняет, что именно должно происходить. Поэтому в Course.Tours такие требования описывались через сценарии:

Если студент открывает занятие раньше чем за 15 минут до начала, система показывает страницу ожидания с обратным отсчетом. В момент старта происходит автоматический переход в активную комнату.

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

Бизнес-правила и права доступа

Не все знания о продукте можно описать через пользовательские сценарии. Часть логики существует в виде правил, ограничений и договоренностей, которые влияют на работу системы, но не видны пользователю напрямую.

В Course.Tours такие правила фиксировались отдельно:

1. конфликт расписания возникает при пересечении двух занятий на 10 минут и более;
2. если дата окончания курса попадает на выходной день, финальный урок автоматически переносится на первый рабочий день.

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

Отдельно фиксируются роли и права доступа. В Course.Tours использовалось четыре типа пользователей, для каждого из которых были описаны доступные действия в личном кабинете и мессенджере. Такая матрица позволяет новой команде понимать ограничения системы без изучения кода и исторических решений.

Последняя строка — бизнес-решение, за которым стоит конкретная причина: учитель-самозанятый не может написать студенту до оплаты. Это защита от навязчивых контактов на платформе, где учатся дети. Если это нигде не записано, следующий разработчик уберет проверку как «лишнюю» — и никто не заметит. Подробнее об архитектуре мессенджера и логике ролей мы писали в кейсе Course.Tours.

Сколько это стоит

Документация, создаваемая в процессе разработки, в среднем занимает 20–25% от общего объема работ. В случае Course.Tours это около 175 часов аналитики и проектирования. Этот объем формирует основу для передачи и масштабирования продукта без потери контекста.

Если этот этап пропущен, работа по фиксации знаний просто переносится на момент передачи проекта — когда новая команда вынуждена восстанавливать контекст с нуля.

Для команды из трех человек это легко превращается в 200–400 часов работы, в течение которых продукт не развивается, а переосмысляется. При этом часть знаний неизбежно теряется или интерпретируется заново. Фактически продукт начинает развиваться с задержкой в 3–6 недель, пока не восстановлена базовая логика системы.

Разница в подходе проста: в одном случае эти часы инвестируются в фиксацию знаний, в другом — в их восстановление. Именно поэтому документация в процессе разработки снижает стоимость передачи продукта и убирает необходимость длительного восстановления контекста при смене команды.

Документация как часть продукта

Важно не наличие документации, а момент, в который она создается. Она имеет смысл только параллельно с разработкой — когда фиксирует не итог системы, а логику принятия решений: как и почему продукт должен работать.

В Course.Tours новые функции — реферальная программа, синхронный AI-перевод, языковые лагеря — сначала оформлялись как зафиксированные решения и только затем реализовывались в коде.

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

Если хотите разобраться, как выстроить этот процесс под ваш проект — напишите нам.