1.6 Записи о решениях

Обзор и мотивация

Запись о решении это документ, фиксирующий важное решение вместе с его контекстом и последствиями. Самая известная форма это запись об архитектурном решении (ADR), короткая заметка, по возможности неизменяемая, которая фиксирует один архитектурно значимый выбор, почему он сделан и что из него следует. Полный набор записей проекта это его журнал решений (ADL), а дисциплина их ведения часть управления архитектурными знаниями (AKM). Эта глава опирается на практики принятия решений и управления из главы 1.5 и сосредоточена на том, как писать, хранить и поддерживать записи о решениях в масштабе.

Мотив прост, и узнавать его на горьком опыте больно. В любой долгоживущей системе самый дорогой вопрос это «почему, чёрт возьми, это построено именно так?», заданный через месяцы или годы людьми, которых не было в комнате. Код показывает, что делает система. Тесты показывают, что она работает. Но ни то ни другое не фиксирует, почему вы выбрали этот путь вместо альтернатив, которые рассматривали и отвергли. Без записей о решениях это рассуждение испаряется вместе со сменой персонала. Команды заново обсуждают решённые вопросы, отменяют хорошие решения по плохим причинам или сохраняют плохие из страха. Запись о решении это дешёвое письмо в будущее, сохраняющее рассуждение.

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

Ключевые принципы

Записывайте почему, а не только что. Контекст и отвергнутые альтернативы и есть суть.
Одно решение на запись. Делайте каждую запись конкретной и самодостаточной.
Малое и лёгкое лучше исчерпывающего и неиспользуемого. Одностраничная запись, которая существует, лучше отчёта, который никогда не написан.
Ставьте дату на всё. Стоимости, ограничения и поставщики меняются; датируйте каждое утверждение.
Предпочитайте живой журнал прагматично. Неизменяемость идеал; на практике вносите поправки с датой.
Слова вместо аббревиатур. «Решения» приглашают к большему вкладу, чем «ADR».
Делайте решения находимыми и, где возможно, проверяемыми. Показывайте нужную запись в нужный момент; обеспечивайте её функциями пригодности.

Компромиссы: плюсы и минусы

Выбор	Плюсы	Минусы
Лёгкие ADR (Найгард/MADR)	Быстро писать, их действительно пишут; мало церемоний	Меньше строгости для высокорисковых, спорных решений
Тяжёлые шаблоны (Тайри-Акерман)	Взвешенные альтернативы; сильны для крупных, дорогих выборов	Медленнее; могут отпугивать от рутинной записи
Неизменяемые + замена	Чистый след аудита; история сохранена	Больше записей; читателям нужно прослеживать цепочки
Живой документ (поправки с датой)	Единый актуальный источник истины; легко сопровождать	Слабее для аудита; риск тихих правок
Markdown в репозитории	С версиями, рецензируется, рядом с кодом	Менее дружелюбен к не-разработчикам
Вики / инструмент документации	Доступно всем ролям	История и ревью слабее; расходится с кодом

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

Вопросы для обсуждения с командой

Как нужная запись о решении дойдёт до разработчика в момент, когда он трогает код, который она регулирует, а не будет лежать в каталоге, который никто не открывает? Журнал только для записи фиксирует рассуждения, никогда не меняющие поведения, и это самый распространённый способ отказа записей о решениях: они существуют, и никто их не читает, когда это важно. Противоположное соображение это усилия, потому что автоматическое показывание записей (прикрепление к запросу на слияние при правке управляемого кода) требует вложений в инструменты, которых не требует вики или каталог документации. Приведите в обсуждение свидетельства: когда кто-то недавно отменил или заново обсудил решённый вопрос, была ли нужная запись находима в тот момент или погребена? Для большой организации с десятками команд находимость превращает с трудом добытое рассуждение одной команды в повторно используемый актив, а не в частный архив. Решите, хранить ли записи в системе контроля версий рядом с кодом и встроить ли их в поток запросов на слияние, чтобы запись появлялась там, где происходит работа.
Кто ответственный сопровождающий каждой записи и что мешает вашему журналу выродиться в уверенную дезинформацию? Опасный режим отказа журнала решений не пустой каталог, а каталог, полный записей, чьи стоимости, возможности поставщиков и ограничения тихо устарели годы назад. Каждой записи нужен ответственный владелец, пересматривающий её с периодичностью (не реже раза в год) и ведущий к замене или выводу из обращения, иначе журнал сгнивает в фольклор, которым выборочно пользуются и мало доверяют. Приведите свидетельства: сколько ваших записей без даты, сколько описывают поставщика или цену, которые с тех пор изменились, и когда каждая пересматривалась в последний раз. В государственной и регулируемой среде это острее, потому что неизменяемая цепочка замен именно то, на что опираются аудиторы и подрядчики-преемники для прослеживаемого обоснования. Определите жизненный цикл явно, датируйте отдельные дрейфующие утверждения и назначьте сопровождающих, чтобы журнал оставался живым активом, а не кладбищем.
Следует ли стандартизироваться на одном шаблоне для всех команд и сколько строгости на самом деле нужно вашим решениям с самыми высокими ставками? Сопоставимость реальное преимущество: когда каждая команда использует одну форму (Найгард, MADR или подобную), новая команда может найти три предыдущие записи и принять рассуждение за полдня вместо месяца споров. Основное напряжение это строгость против внедрения, потому что самый тяжёлый шаблон, которым никто не пользуется, не записывает ничего, а самый лёгкий, которым пользуются все, накапливает ценность. Приведите свидетельства: действительно ли записи пишутся и, отдельно, не были ли крупные, спорные, дорогие решения недостаточно проанализированы, потому что лёгкая форма пропустила взвешивание альтернатив? Для корпораций, координирующих пересекающиеся выборы между командами, общий шаблон плюс индекс с поиском предотвращает расходящиеся, несовместимые решения. По умолчанию выбирайте лёгкое для обычного случая и заранее договоритесь, какие решения «двери в одну сторону» заслуживают более тяжёлой формы со взвешенными альтернативами.
Что на самом деле оправдывает заведение записи о решении и у кого есть право сказать, что выбору она не нужна? Поставьте планку слишком высоко, и обоснование значимых выборов испарится; слишком низко, и журнал заполнится мелочами, погребающими записи, действительно нужные людям. Для большой организации неясный порог означает, что каждая команда импровизирует свой, так что охват становится неравномерным, и никто не может доверять тому, что отсутствие записи сигнализирует о неважном решении. Приведите в обсуждение свидетельства: горстку недавних решений, которые были записаны, хотя не нужно было, и болезненных, оставшихся незаписанными и позже стоивших вам повторного открытия. Договоритесь о простой проверке, например записывать всякий раз, когда будущему разработчику понадобится почему, и пропускать малорисковые, самодостаточные или уже документированные выборы. В регулируемой и государственной среде расчёт смещается, потому что мандат аудита может требовать запись для каждого архитектурно значимого требования, считает команда это достойным письма или нет, поэтому назовите заранее, какие решения не обсуждаются.
Ваши записи это подлинное рассуждение, зафиксированное в момент решения, или бумажная работа, написанная потом ради мандата? Запись, созданная задним числом, чтобы закрыть тикет, склонна «отмывать» выбранный вариант и тихо опускать альтернативы, которые на самом деле взвешивались, а это именно та информация, которая больше всего нужна будущему читателю. Противоположное давление реально: писать почему до или во время решения кажется медленнее, чем выпускать, а признавать отвергнутые пути письменно требует психологической безопасности, которой нет у некоторых команд. Принесите на стол образец недавних записей и честно спросите, читаются ли контекст и отвергнутые альтернативы как подлинное обдумывание или как задним числом подогнанное оправдание. Для большой команды пустые записи хуже отсутствия, потому что учат людей, что журналу нельзя доверять. В корпоративном и государственном аудите это различие острое: надзорные органы и подрядчики-преемники зависят от обоснования, отражающего то, что действительно рассматривалось, а запись, читающаяся как театр, подрывает гарантию, ради которой журнал существует.
Какие из ваших решений с самыми высокими ставками вы можете обеспечить автоматической функцией пригодности, вместо того чтобы доверять, что периодическое ручное ревью поймает нарушение? Запись о решении документирует выбор, но только автоматическая проверка в непрерывной интеграции удерживает этот выбор от тихой эрозии, пока десятки разработчиков годами трогают код. Компромисс это инвестиции, потому что написание и поддержка функций пригодности (с инструментами вроде ArchUnit) стоит инженерного времени, а многие решения, особенно по процессу или поставщикам, механически не проверяются вовсе. Приведите свидетельства: какие решения о границах (зависимости модулей, порождение событий, правила доступа к данным) тихо нарушались и были пойманы лишь поздно на ревью или в эксплуатации. Для корпорации с многими командами функции пригодности превращают управление из центрального узкого места в непрерывное обеспечение, масштабирующееся без замедления всех. В регулируемом и государственном контексте автоматическая, всегда включённая проверка гораздо более сильное свидетельство для аудита, чем подпись на ревью, потому что доказывает, что решение выполняется сегодня, а не что кто-то когда-то его одобрил.

Взгляд по секторам

Стартап. Сведите всё к привычке и ничему больше: каталог decisions/ в основном репозитории и заметка из двух разделов (контекст и выбор) всякий раз, когда вы принимаете решение, которое ваше будущее «я» поставит под вопрос. Полностью пропустите жизненный цикл, роли и утверждающих, потому что процесс, который вы не можете выдержать, процесс, который вы бросите. Одна запись, избавляющая вашего первого нанятого сотрудника от вопроса, почему система построена так, уже окупает всю практику.

Малый бизнес. Без выделенного архитектора и при нехватке времени помещайте записи туда, где ваша команда уже работает, будь то вики, общий документ или репозиторий, вместо покупки специального инструмента. Привычка важнее инструментов, поэтому снижайте барьер: назовите каталог decisions, а не adr, и фиксируйте выбор поставщиков и «построить или купить» тем же духом, что и технические. Когда вы опираетесь на внешних подрядчиков, короткая датированная запись о том, почему вы выбрали поставщика или платформу, дешёвая страховка от привязки к выбору, который потом никто не сможет объяснить.

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

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

Примеры

Стартап. Стартап из пяти человек добавляет в основной репозиторий простой каталог decisions/ с заметкой из двух разделов (контекст и выбор) всякий раз, когда кто-то принимает решение, которое его будущее «я» поставит под вопрос. Никакого жизненного цикла, ролей и утверждающих: просто привычка писать почему рядом с кодом. Когда через полгода приходит их первая новая сотрудница, она прочитывает весь каталог за час и перестаёт спрашивать «почему это построено так?». Лёгкий журнал стоит минуты на запись и избавляет от налога на повторное открытие, который кусает задолго до того, как команда вырастет.

Крупная организация. Ритейлер с 30 инженерными командами стандартизируется на записях в формате MADR в каждом репозитории плюс центральный индекс с поиском. Когда новая команда сталкивается с вопросом «монорепозиторий против мультирепозитория», она находит три предыдущие записи с контекстом и последствиями и принимает рассуждение за полдня вместо месяца споров. Ключевые решения о границах (владение сервисами, правила доступа к данным) подкреплены функциями пригодности ArchUnit, поэтому нарушения валят сборку, а не ловятся на ревью. Это управление, масштабируемое без центрального узкого места.

Государственный сектор. Агентство, модернизирующее систему пособий, требует ADR для каждого архитектурно значимого требования, каждая из которых связывает решение с мандатом или контролем соответствия, который оно удовлетворяет (доступность, размещение данных, проверяемость). Записи неизменяемы и заменяются, создавая прослеживаемый журнал, удовлетворяющий надзорному ревью. Что принципиально, он также позволяет подрядчику-преемнику понять, почему система устроена именно так, сохраняя преемственность на протяжении многолетних сроков с несколькими поставщиками, типичных для государственных программ (главы 4.6, 10.4).

Бизнес-обоснование: мотивы, ROI и TCO

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

По совокупной стоимости владения записи о решениях одна из самых высокорычажных форм документации, потому что нацелены на самый чувствительный к текучести актив: обоснование. Адаптация быстрее (новые сотрудники читают почему, а не только код). Модернизация безопаснее (глава 3.6: можно отличить существенные решения от случайных). Аудиты дешевле (свидетельства уже существуют). Стоимость их неведения не видна ни на одной панели и молча нарастает с каждым уходом. Чтобы убедить руководство, укажите на недавнее дорогое повторное открытие или отменённое решение, вызвавшее инцидент, и отметьте, что исправление почти ничего не стоит ввести.

Антипаттерны и ловушки

Запись что без почему: опущены контекст и отвергнутые альтернативы, то есть вся суть.
Бумажная работа задним числом: записи, написанные ради мандата, а не чтобы думать; они читаются пустыми, и им не доверяют.
Мегадокументы с несколькими решениями: одна гигантская страница, по которой нельзя ориентироваться и которую нельзя чисто заменить.
Утверждения без дат: стоимости и ограничения, бывшие когда-то верными, поданные как вневременные.
Тихие правки: изменение истории решения без датированной пометки, разрушающее след аудита.
Журналы только для записи: записи создаются и никогда не показываются в момент, когда они уместны, поэтому не влияют на поведение.
Охрана аббревиатур: настаивание на «ADR» и «архитектуре», отбивающее желание вносить вклад.
Нет жизненного цикла: записи, которые никогда не пересматриваются, не заменяются и не выводятся, вырождаются в дезинформацию.

Модель зрелости

Уровень 1 (Начальный): Решения живут в головах людей, чатах и сообщениях коммитов; фиксация реактивна и стихийна, а обоснование регулярно теряется вместе со сменой персонала.
Уровень 2 (Развитие): Некоторые команды ведут записи в разных форматах и шаблонах, когда кто-то вспоминает; практика непоследовательна между командами, без общего журнала, именования и процесса.
Уровень 3 (Стандартизация): Единый шаблон, хранение в репозитории и определённый жизненный цикл и управление (критерии заведения и пропуска, роли, периодичность пересмотра) задокументированы и последовательно применяются по всей организации; записи пересматриваются и заменяются, а не правятся молча.
Уровень 4 (Управление): Журнал решений измеряется относительно базовых значений: охват (доля архитектурно значимых решений, несущих запись), свежесть (доля записей, пересмотренных в рамках периодичности, плюс число недатированных или устаревших утверждений) и находимость (как часто соответствующая запись действительно дошла до разработчика, изменившего управляемый код). Ответственные сопровождающие действуют по этим метрикам, заменяя устаревшие записи и закрывая пробелы охвата на основании свидетельств, а не анекдотов.
Уровень 5 (Оркестрация): Межкомандный журнал решений с поиском интегрирован в повседневную работу: соответствующие записи автоматически появляются на изменениях, которые они регулируют, ключевые решения обеспечиваются функциями пригодности в непрерывной интеграции, а журнал питает адаптацию, модернизацию и аудит как живой актив. Организация непрерывно улучшает саму практику, выводя из обращения, заменяя и пересматривая область записей по мере смещения системы и её ограничений и перебалансируя, куда вкладывать строгость по мере роста портфеля решений.

Идеи для обсуждения

Какое последнее решение ваша команда отменила или заново обсуждала, потому что никто не помнил исходного рассуждения?
Изменит ли переименование каталога adr/ в decisions/, кто вносит вклад и что записывается?
Какие из ваших критических решений можно было бы обеспечить автоматической функцией пригодности уже сегодня?
Неизменяемые с заменой или живой документ: что подходит вашим обязательствам по аудиту и вашей культуре и почему?
Как новый сотрудник (или подрядчик-преемник) сейчас узнает, почему ваша система устроена именно так?
Что оправдывает заведение записи о решении в вашей команде и что оправдывает отказ от её заведения?

Главные выводы

Запись о решении фиксирует одно важное решение вместе с контекстом и последствиями: почему, а не только что.
Держите записи конкретными, датированными и лёгкими; стандартизируйтесь на одном шаблоне (Найгард, MADR или подобный).
Храните их в системе контроля версий рядом с кодом; подумайте о названии «decisions», чтобы расширить круг участников.
Определите жизненный цикл и управление (критерии заведения и пропуска, роли, периодичность пересмотра); тяжёлый процесс резервируйте для решений «двери в одну сторону».
Делайте решения находимыми в момент изменения и, где возможно, проверяемыми функциями пригодности.
ROI это избегаемая стоимость повторного открытия и ошибочной отмены; аргумент TCO сильнее всего там, где важны текучесть, модернизация и аудит. См. главу 1.5 (принятие решений и управление) и главу 3.1 (основы архитектуры).

Источники и дополнительное чтение

Michael Nygard, “Documenting Architecture Decisions” (2011): the foundational lightweight ADR.
MADR: Markdown Any Decision Records project (adr.github.io/madr).
Jeff Tyree and Art Akerman, “Architecture Decisions: Demystifying Architecture” (IEEE Software, 2005).
Olaf Zimmermann, “Y-Statements” and “Architectural Decision Making” (ozimmer.ch).
Joel Parker Henderson, Architecture Decision Record (ADR): templates, examples, and teamwork guidance (github.com/joelparkerhenderson/architecture-decision-record).
ThoughtWorks Technology Radar: “Lightweight Architecture Decision Records.”
Neal Ford, Rebecca Parsons, Patrick Kua, Pramod Sadalage, Building Evolutionary Architectures (fitness functions).
AWS Prescriptive Guidance, “ADR process”; Red Hat, “Why you should use ADRs.”
Wikipedia, “Architectural decision” and “Architecturally significant requirements.”

1.6 Записи о решениях

Обзор и мотивация

Ключевые принципы

Рекомендации

Зафиксируйте существенную структуру

Пишите записи конкретные, датированные и почти неизменяемые

Храните записи там, где работа

Называйте их «решениями» и выходите за пределы архитектуры

Определите жизненный цикл и управление

Делайте решения проверяемыми и находимыми