Привет, Хабр! Меня зовут Дмитрий Бабчук, я руководитель направления информационной безопасности и ИТ-инфраструктуры маркетплейса Flowwow.
Наверняка вы как разработчики не раз сталкивались с проблемой согласования фичи со службой безопасности. В большинстве случаев этот процесс превращается в головную боль для программиста из-за множества непонятных этапов и деталей.
Регулярно встречая подобные проблемы в своей работе, мы во Flowwow решили внедрить процесс, который помог не только снизить на треть количество времени на анализ корневых причин сложных инцидентов, но и значительно упростить согласование фич для программистов.
Этот процесс получил кодовое название ADR.
Что же такое ADR?
Нет, это не американские депозитарные расписки, как многие могли подумать, это ADR (Agile Development Review) — метод, который используется для документирования архитектурных решений в процессе разработки программного обеспечения.
Architecture Decision Record (ADR) — это по сути, это документ, предназначенный для фиксации архитектурных решений. Его основная задача — дать ответ, почему они были приняты.
Использование данного подхода позволяет повысить качество принимаемых решений, а также быстрее проходить процесс адаптации новым сотрудникам.
Из каких пунктов состоит ADR?
Представьте, что ADR — это краткая памятка, которая объясняет, какое решение вы приняли и — самое главное — почему.
Она состоит из пяти больших блоков:
Контекст — отвечает на вопрос «в чем состоит проблема?»
Коротко опишите вашу задачу или проблему, которую нужно решить. Что мешает? Какие есть ограничения?Способы решения — отвечает на вопрос «какие у нас были варианты решения проблемы?»
Перечислите все способы решения, которые вы рассмотрели. Для каждого напишите его плюсы и минусы. Это поможет понять, почему был выбран текущий вариант.Требования ИБ — отвечает на вопрос «что сказали специалисты по безопасности?»
Запишите здесь все, что потребовали специалисты по безопасности. Например:
— Кто будет иметь доступ к новому функционалу?
— Нужны ли дополнительные проверки?
— Какие риски мошенничества есть и как мы с ними боремся?Решение — отвечает на вопрос «что в итоге выбрали и почему?»
Четко напишите, какой вариант вы утвердили. Самое важное: объясните, почему решили именно так. Например: «Этот вариант быстрее в реализации», «Он дешевле» или «Он надежнее других».Схема взаимодействия основных компонентов системы после внедрения решения
Зачем она нужна? Схема помогает одним взглядом понять суть решения, избежать недопонимания в команде и служит наглядным артефактом для всех участников.
Чего НЕ должно быть в ADR?
ADR — это не техническая инструкция. В нем не нужно:
писать детали API (точные названия методов, поля запросов);
указывать имена переменных в коде;
рисовать подробные схемы базы данных (если только это не ключевая часть решения).
Главное правило: ADR отвечает на вопрос «почему?», а не «как?». Детали реализации будут в коде и технической документации. Такой подход поможет сохранить ADR коротким, понятным и полезным для всех.
Самый простой способ начать — договориться в команде, что любое решение, обсуждаемое дольше 30 минут на митинге или в чате, автоматически становится кандидатом на создание ADR. Это дисциплинирует и структурирует процесс принятия архитектурных решений.
Когда стоит разрабатывать ADR?
Если планируется принимать архитектурно значимое решение, которое будет сложно или дорого изменить позже, то это тот самый момент, когда стоит начать разработку ADR.
Он должен стать единственным источником истины, который синхронизирует всех участников. Дополнительный плюс — ADR заменяет долгие совещания и бесконечную переписку.
Для ИБ-специалистов важным триггером для создания архитектурного ревью являются изменения, касающиеся:
текущих механизмов авторизации и аутентификации или подключения новых;
проведения любых работ, связанных с монетизацией: например, подключение новых способов оплаты или изменения программы лояльности;
интеграции с внешними системами: подключение к API новых партнеров, государственных систем (например, ГИС, онлайн-кассы) или облачных сервисов;
рефакторинга или миграции критичных сервисов: перенос базы данных, почтового сервера или доменных служб (Active Directory) в новую среду;
сбора или обработки новых категорий персональных данных (ПДн);
изменения логики хранения и передачи данных: внедрение нового шифрования, изменение ключевой инфраструктуры (PKI), перенос данных в другую юрисдикцию;
внедрения новых каналов коммуникации: добавление чат-ботов, СМС-рассылок или кол-центров, интегрированных с ��нутренними системами;
работы с системами управления контентом (CMS), особенно если это касается возможности публикации или изменения контента без дополнительной модерации;
изменения ролевой модели доступа (RBAC): внедрение новых ролей или массовое изменение прав существующих групп пользователей;
автоматизации бизнес-процессов (RPA): внедрение роботов для автоматического выполнения задач в критичных системах.
Список не конечный и может редактироваться в соответствии с вашими потребностями.
Где лучше хранить ADR?
Вариант 1: хранить документацию в Git
Плюсы (+):
Версионность: история изменений ADR привязана к истории кода — видно, кто, когда и почему изменил решение.
Близость к коду: документация всегда под рукой у разработчика в том же проекте — не нужно переключаться между системами.
Долговечность: документ живет столько же, сколько и код проекта, — меньше риск, что он потеряется.
Простота: не требует дополнительных лицензий или инструментов.
Минусы (–):
Разрозненность: в монолите (или если решений много) ADR могут быть «размазаны» по разным репозиториям — сложно увидеть общую картину.
Сложность поиска: нужно знать, в каком репозитории искать решение.
Меньше наглядности: не технические специалисты могут реже заглядывать в Git.
Вариант 2: хранить в системе для совместной работы с документами
Плюсы (+):
Единый источник истины: все ADR по всем проектам собраны в одном месте — легко искать, ссылаться и видеть общую архитектурную картину.
Доступность: более удобен для неразработчиков (продакт-менеджеров, тестировщиков, руководителей).
Богатое форматирование: удобно вставлять и редактировать сложные схемы, таблицы, диаграммы.
Структура и навигация: можно легко построить иерархическую структуру (по продуктам, сервисам, эпикам).
Минусы (–):
Отрыв от кода: документ живет своей жизнью — можно изменить ADR в Confluence, но забыть обновить код, и они разойдутся.
Риск устаревания: вероятность, что документ забудут и он устареет, выше.
Какой вариант выбрать?
Для небольшой команды разработчиков лучше всего подойдет Git. Если же к проекту подключены и другие отделы, удобнее будет собрать все материалы в общей системе для хранения документов и совместной работы.
Как это устроено во Flowwow
Сейчас мы сделали две важные вещи:
Начали говорить с другими командами на одном языке с помощью ADR. Теперь у нас единый продуманный план, в который все внесли свой вклад. Это как если бы все инженеры, электрики и сантехники вместе смотрели на один общий чертеж здания.
Поставили «охранника» у входа. Теперь ни один проект не начнется, пока его не одобрит отдел ИБ. На первый взгляд кажется, что это добавляет лишний шаг, но на деле экономит кучу нервов и времени. Мы находим уязвимости еще «на берегу», а не тогда, когда все уже построено и приходится ломать готовое.
Выгода для всех: меньше авралов, меньше переделок, более стабильный и безопасный продукт.
Что это нам дало?
В первую очередь экономию времени. Важно отметить, что ADR экономят время не на самом процессе принятия решения, а на его последствиях на протяжении всего жизненного цикла проекта.
Давайте разберемся, где и сколько экономится времени, на нашем примере.
Обсуждение и онбординг новых разработчиков
Как было без ADR: новый сотрудник тратит часы, задавая вопросы «почему мы используем X, а не Y?», «как тут все устроено?». Старшие разработчики тратят время на повторные объяснения.
Как с ADR: все ответы заранее есть в ADR, и после внедрения мы стали экономить примерно 50–80% времени на онбординг по архитектурным вопросам.
Отсутствие необходимости в повторном обсуждении
Без ADR: команда каждые 6–12 месяцев открывала одни и те же дискуссии (например: «а давайте перейдем с MongoDB на PostgreSQL», «а почему у нас нет такого сервиса?»). Это часы, а иногда и дни споров.
После внедрения ADR: ушли повторные дискуссии, что сэкономило нам дни девелоперского времени в долгосрочной перспективе (примерно 1–2 рабочих дня на одну крупную дискуссию раз в квартал или полгода).
Расследование инцидентов
Без ADR: расследуя сбой, нам трудно было понять, это осознанный риск принятого решения, на который мы пошли, или все же ошибка в реализации.
После внедрения ADR: на анализ корневых причин сложных инцидентов стало уходить на 30% меньше времени.
Контроль и безопасность новых инициатив
Процесс записи ADR стал точкой контроля, где ИБ может на раннем этапе оценить архитектурные риски, внести требования и дать согласование. Это позволяет оперативно и под контролем осуществлять безопасный запуск новых инициатив и не пропускать их в реализацию без ведома ИБ.
Вместо заключения
ADR — это инвестиция. Вы тратите 15–30 минут на запись решения, чтобы сэкономить часы и дни в будущем. Общая экономия для команды из 5–10 человек может составлять десятки часов в квартал.
Как думаете, сработает ли такое решение в вашей команде?
