Как идеально документировать ревью дизайна в команде разработки

70% технических решений никогда не документируются

Дизайн-ревью, обсуждения код-ревью, планирование спринтов, приоритизация техдолга. Инженерные команды тратят 8-12 часов в неделю на технические встречи. Отчёт GitHub за 2024 год показал, что 72% технических решений хранятся только в памяти участников — никакой документации.

Через три месяца снова всплывает «почему мы сделали именно так?» И команда начинает обсуждение с нуля.

Почему технические решения исчезают

Код-ревью без контекста

Ревьюер видит код. Он не видит, почему вы выбрали микросервисы вместо монолита или Memcached вместо Redis. Не зная замысел дизайна, ревьюер ставит под сомнение саму архитектуру. Автор заново объясняет то, о чём команда уже договорилась. Эти итерации добавляют в среднем 1,5 дня к времени мержа PR.

Реальная цена отсутствия ADR

В каждой команде хотя бы раз был разговор «надо писать Architecture Decision Records». Потом происходит «задокументируем потом», и потом никогда не наступает.

Чем масштабнее решение — миграция на микросервисы, стратегия шардирования БД, смена системы аутентификации — тем дороже обходится отсутствие записей. ThoughtWorks Technology Radar рекомендует ADR на уровне «Adopt», но только 15% команд последовательно их ведут.

Узкие места при онбординге новичков

Новому разработчику нужно понять не только что делает код, но и почему он написан именно так. Каждый раз устно объяснять это силами сеньора — неэффективно для обеих сторон. Новые разработчики достигают полной продуктивности в среднем за 3-6 месяцев, и значительная часть этого времени уходит на выяснение «почему».

Когда этот сеньор уходит в отпуск или увольняется — знания теряются навсегда. Это структурная проблема: знания команды испаряются вместе с людьми.

«На онбординге я спросил: «Почему эти сервисы общаются через gRPC?» Ответ был: «О, тогда были причины». Три недели я сам выяснял, какие именно.» — Бэкенд-разработчик, стартап серии B

Стратегия 1: Постройте культуру «Decision Log»

Фиксируйте решения в момент их принятия на встрече. План «опишем потом» почти никогда не реализуется.

Назначьте «Decision Recorder» на каждую встречу. Записывать нужно только три вещи: что решили, почему, какие альтернативы рассматривали. Всё.

Пример: «Выбрали AWS API Gateway вместо Kong / Причина: нет опыта работы с Kong, минимизация overhead на управление инфраструктурой / Альтернативы: Kong, Traefik, своя реализация» — трёх строк достаточно.

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

Привычка важнее формата. Команда, которая пишет 3-строчный Decision Log после каждой встречи, через полгода будет в совершенно другом месте, чем команда с идеальным шаблоном ADR, который никто не заполняет.

Стратегия 2: Свяжите PR с контекстом дизайна

Качество код-ревью пропорционально количеству контекста у ревьюера. Добавьте раздел «Design Context» в шаблон PR: обоснование дизайна, рассмотренные альтернативы и причина выбора.

Например: «Выбрали SWR вместо React Query / Причина: размер бандла на 30% меньше, более интуитивная логика инвалидации кеша» — ревьюер получает то, что нужно, чтобы сфокусироваться на качестве реализации, а не ставить под вопрос подход.

Если команда использует Knoi, достаточно добавить ссылку на встречу по дизайну в описание PR.

Настоящая отдача проявляется через 6 месяцев. Когда нужно изменить legacy-код, можно проследить от git blame к коммиту, к PR и к полному контексту дизайна. Ваши PR становятся архивом технических решений команды.

Стратегия 3: Создайте «Пакет для онбординга»

Главный bottleneck онбординга — объяснение «почему». Соберите ключевые записи дизайн-встреч в пакет для онбординга, и новички смогут самостоятельно выстроить контекст без повторных объяснений от сеньоров.

Выберите 5-10 самых важных архитектурных решений вашей команды. Неявные принципы вроде «скорость разработки важнее производительности» или «минимизировать внешние зависимости» становятся понятными, когда привязаны к конкретным примерам решений.

Если у вас есть записи дизайн-встреч в Knoi, найдите нужные по ключевым словам и добавьте напрямую. Команды, внедрившие этот подход, сократили время до первого PR нового разработчика в среднем на 40%.

«Мы добавили 10 ссылок на дизайн-встречи из Knoi в пакет для онбординга. Новичок почти не спрашивал «почему это так сделано?» в первую неделю. Вместо этого начал предлагать улучшения.» — Engineering Manager, финтех-стартап на 50 человек

Руководство по внедрению

Неделя 1: Запустите Decision Log

• Введите 3-строчные Decision Log на каждой технической встрече (решение, обоснование, рассмотренные альтернативы)
• Создайте пространство «Tech Decisions» в существующих инструментах (Notion, Confluence, Knoi и т.д.)
• Выберите одного человека «Decision Champion» для продвижения привычки документирования

Неделя 2-3: Свяжите с PR-воркфлоу

• Добавьте раздел «Design Context» в шаблон PR
• Начните добавлять ссылки на записи дизайн-встреч (или ссылки из Knoi) в PR
• Активно давайте и принимайте фидбек «отсутствует контекст дизайна» на код-ревью

Неделя 4: Создайте пакет для онбординга

• Выберите 5-10 ключевых технических решений за последние 6 месяцев
• Свяжите каждое решение с записью встречи, Decision Log и связанными PR
• Добавьте «Изучить пакет для онбординга» в чек-лист для новичков

До / После

Итог

Технические решения — такой же актив, как код. Код живёт в Git, но причина этого кода обычно нигде не хранится.

Соедините Decision Log, контекстные ссылки в PR и пакеты для онбординга, и ваши технические решения станут поисковым активом команды.

Начните с 3-строчных Decision Log. Инструменты вроде Knoi автоматизируют привычку, не добавляя нагрузку на документирование.