§3.07 Архитектурные решения и их фиксация
Время: 45 мин чтение + 30 мин
В одном предложении: Человек думает, что важные решения запоминаются сами собой, а на самом деле через три месяца вы не помните, почему выбрали именно этот способ, и начинаете обсуждать то же самое снова, тратя энергию, которая уже была потрачена, и рискуя прийти к другому решению, которое окажется хуже первого.
Мем, который снимается. «Мы обсудили, решили, записали в протокол встречи. Этого достаточно. ADR нужен только разработчикам программного обеспечения.» На самом деле протокол встречи не заменяет ADR. Протокол фиксирует, что было сказано. ADR фиксирует, почему решение принято, какие альтернативы рассмотрены, какие последствия ожидаются. Через три месяца протокол встречи не ответит на вопрос «почему мы так решили?». ADR ответит. И если кто-то предложит вернуться к отвергнутой альтернативе, ADR покажет, почему она была отвергнута, и сэкономит время на повторное обсуждение.
Понятия. ADR (Architecture Decision Record): запись архитектурного решения, содержащая контекст (какие условия привели к необходимости решения), проблему (что нужно было решить), альтернативы (какие варианты рассматривались, с плюсами и минусами каждого), решение (какой вариант выбран и почему), последствия (что изменится после принятия решения), статус (принято / отменено / заменено), дата, автор. АрхГейт выступает фильтром перед принятием архитектурного решения: оценка по семи характеристикам (смежность, масштабируемость, отказоустойчивость, гибкость, скорость, себестоимость, безопасность). Решение проходит АрхГейт, прежде чем фиксироваться в ADR. ADR хранится в Pack, в разделе, соответствующем предметной области решения.
Понятия этого раздела:
- ADR: запись архитектурного решения с контекстом, альтернативами, обоснованием и последствиями. ≠ протокол встречи, ≠ список задач.
- АрхГейт: фильтр из семи характеристик, который проходит решение перед фиксацией в ADR. ≠ произвольное обсуждение, ≠ формальное согласование без критериев.
Объяснение. Архитектурные решения затрагивают не только выбор технологии или структуры системы. Это любое решение, которое определяет, как будет устроена работа в будущем: выбор метода планирования, формата отчётности, структуры команды, способа взаимодействия с клиентом. Каждое такое решение имеет последствия, которые проявляются не сразу. ADR фиксирует эти последствия в момент принятия, когда они ещё видны. Без ADR вы сталкиваетесь с парадоксом: через полгода вы не помните, почему решили так, и начинаете сомневаться. Новый человек в команде предлагает «очевидное» улучшение, то есть то, что вы уже рассматривали и отвергли. Вы тратите время на повторное обсуждение. ADR предотвращает это: новый человек читает ADR, видит аргументы, и либо соглашается, либо предлагает новые аргументы, которые не учитывались раньше. В обоих случаях обсуждение идёт на уровень выше, чем повторение пройденного.
На практике. Практика «Один ADR" (30 мин):
- Вспомните одно важное решение, принятое в последние три месяца, но не зафиксированное в Pack. (5 мин)
- Запишите ADR: контекст, проблему, две альтернативы с плюсами и минусами, выбранное решение с обоснованием, ожидаемые последствия. (20 мин)
- Поместите ADR в Pack в соответствующий раздел. Зафиксируйте статус: «принято». (5 мин)
Типичный кейс. Команда из пяти человек выбирала метод планирования: еженедельное планирование или спринты двухнедельные. Обсудили, решили: спринты. Через полгода новый менеджер предложил: «Давайте попробуем еженедельное планирование, оно гибче». Команда обсуждала это два часа, пришла к тому же выводу: спринты лучше для их контекста. Потраченное время: два часа шести человек. Если бы решение было зафиксировано в ADR с аргументами, новый менеджер прочитал бы его за десять минут и либо согласился, либо предложил новые аргументы. В любом случае это экономия времени и энергии.
Типичная ошибка. «ADR избыточна: мы и так помним, почему решили.» Помните сейчас. Через полгода уже нет. И если команда вырастет, новые люди вообще не будут знать. Другая ошибка: «Мы принимаем много мелких решений, мы не будем писать ADR на каждое.» Верно. ADR не для мелких решений, а для архитектурных: тех, которые определяют структуру работы на месяцы вперёд. Критерий: если решение влияет на то, как будет работать команда через полгода, это ADR.
Степени мастерства:
- Объяснение. Могу объяснить, чем ADR отличается от протокола встречи, и назвать пять разделов ADR. Критерий перехода: написал один ADR.
- Умение. При принятии архитектурного решения создаю ADR до начала реализации. Критерий перехода: пять ADR в Pack.
- Навык. Провожу АрхГейт перед фиксацией решения: оцениваю по семи характеристикам, документирую результат. Критерий перехода: коллега использовала ваш ADR для принятия решения без повторного обсуждения.
- Мастерство. Создаю систему ADR для организации: шаблон, место в Pack, процесс ревью, обновление статусов. Критерий перехода: другой человек создал ADR по вашей системе без вашей помощи.
Проверка себя.
- Могу объяснить разницу между ADR и протоколом встречи за одну минуту
- Написал хотя бы один ADR за последние три месяца
- Могу назвать семь характеристик АрхГейта и применить их к одному решению
- Мои ADR хранятся в Pack и доступны без моей помощи
- Новый человек в команде мог бы понять, почему принято решение, прочитав ADR
На практике. Вспомните решение, которое вы приняли на этой неделе и которое повлияет на вашу работу в следующие три месяца. Запишите: почему так, какие альтернативы были, что ожидаете в результате. Это и есть ADR. Поместите в Pack. Через три месяца вы поблагодарите себя.
См. также: Структура Pack: PD.GUIDE.3.S3.SS3, Фундаментальные принципы: PD.GUIDE.3.S3.SS4.
Что дальше. Следующий подраздел содержит список понятий раздела: сводную таблицу всех терминов, введённых в разделе 3.