От RFC до ADR: Принятие решения и сохранение обоснования

Решение, которое никто не мог восстановить

Новый технический руководитель задает разумный вопрос: почему каждая служба общается с системой выставления счетов через эту очередь? Существует ADR — ADR-014, четыре предложения, написанные одиннадцать месяцев назад. Контекст: "нам нужна была надежная интеграция с выставлением счетов." Решение: "использовать очередь." Последствия: "некоторое добавленное время задержки." Это технически запись. Она ничего не объясняет.

Вы были там, так что вы знаете, что ADR-014 не говорит: трехнедельные споры в двух каналах Slack и жаркая дискуссия в PR; вариант с синхронным API, который проиграл из-за ограничения по количеству запросов, которое с тех пор было увеличено; возражение старшего инженера, на которое ответили бенчмарком, который теперь никто не может найти. Дебаты состоялись. Запись была сделана позже, по памяти, одним человеком, в пятницу.

Это задокументированный, почти универсальный режим отказа действительно хорошей практики. Предписывающие рекомендации AWS и документы Microsoft Well-Architected оба рекомендуют ADR — и оба отмечают проблему: поддерживать их актуальными требует времени, а управление ими становится сложным по мере увеличения числа команд и выборов. Коренная причина структурная: дебаты и запись находятся в разных местах, поэтому запись всегда является потерянной транскрипцией. Решение состоит в том, чтобы сделать их одним и тем же местом. Эта практика не специфична для инженерии и даже не специфична для ADR. Google требует документ дизайна — проблема, предложенный подход, рассмотренные альтернативы, компромиссы — написанный и проверенный до начала значительной технической работы, практика, изложенная в собственном Программном обеспечении Google. Это та же дисциплина, что и ADR, применяемая на шаг раньше: ADR фиксирует выбор, к которому пришел документ дизайна. Оба терпят неудачу одинаково по одной и той же причине, и оба исправляются одним и тем же шагом — держите аргумент там, где находится запись, а не транскрибируйте одно в другое позже. Читайте каждый шаг ниже как охватывающий оба артефакта.

Почему АДР гниют

Одно предложение из материалов сообщества ADR содержит весь диагноз: RFC обычно касается достижения согласия; ADR фиксирует согласие, как только оно достигнуто. Два артефакта, два момента — и всё, что между ними, утекает. Альтернативы, которые были "очевидно" неверными, не фиксируются (пока они не перестанут быть очевидными). Возражение, которое сформировало окончательный дизайн, сохраняется только как комментарий PR в закрытой теме. Раздел контекста пишется последним, хуже всего, тем, кто проиграл в игре "не я". Встречи, которые должны были привести к решениям, вместо этого производят резюме, а рассуждения, которые делают решение долговечным — то, на чем зависит вся цепочка качества решений — именно то, что теряется при транскрипции.

Шаг 1–3: Предложение, контекст, варианты

1. 1Укажите предложение как основное утверждение — предложенное решение, а не вопрос: "Мы будем направлять все записи по выставлению счетов через надежную очередь." Это предложение является заголовком будущего ADR. Контрольная точка: корень существует, одно предложение, автором является предлагающий.
2. 2Контекст как отдельные про-аргументы. Каждая сила, которая делает решение необходимым — требование надежности, лимит тарифов системы выставления счетов, мандат аудита — является собственным аргументом под корнем. Монолитный параграф "Контекст" нельзя оспорить; три отдельных контекстных утверждения могут быть подвергнуты сомнению, подтверждены или опровергнуты индивидуально. Контрольная точка: ≥2 контекстных аргумента, каждый из которых является силой.
3. 3Каждый вариант получает свой собственный узел. Очередь, синхронный API, пакетная задача — родственные аргументы, каждый со своими плюсами и минусами. Плюсы и минусы относительны к родителю, поэтому недостатки варианта зависят от этого варианта, а не от решения. Включите варианты, которые вы ожидаете отклонить: отклоненный родственник — это то, что отвечает на вопрос следующего года "почему мы просто не...". Контрольная точка: каждый вариант, о котором может спросить читатель, существует.

Шаги 4–6: Раунд RFC, который оставляет запись

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

Шаг 7: Принятие решения — и что такое рейтинг не является

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

Шаг 8–9: ADR, который вам не нужно было писать

Вот в чем суть. Запись — это не документ, который вы пишете позже — это узел выбранного варианта плюс все, что уже к нему прикреплено: аргументы контекста (Context), отклоненные варианты (Options Considered), завершенные цепочки (обсуждение с авторами), оценки (где находилась комната) и аргумент решения с его обоснованием (Decision). Ничего не транскрибируется, поэтому ничего не теряется при транскрипции.

1. 1Запишите последствия, которые вы принимаете. Известные недостатки — добавленная задержка, операционная нагрузка от очереди — продолжают существовать как побочные эффекты выбранного варианта, признанные принимающим решение. Запись их делает это решением, а не предпочтением. Контрольная точка: ≥1 принятое последствие на записи.
2. 2Экспортируйте, если ваша организация требует отслеживаемых репозиториями ADR. Многие действительно требуют этого — markdown ADR рядом с кодом остается артефактом соответствия. Напишите четырехразделенное резюме из дерева (пять минут, не в пятницу), ссылайтесь на обсуждение для полного дебата. Контрольная точка: ADR репозитория ссылается на дерево; дерево содержит обоснование.

Не соглашайтесь и действуйте, официально.

Шаблон, который сделал знаменитым Amazon — не соглашаться и принимать — имеет проблему читаемости: как кто-то может позже узнать, что несогласие было реальным, услышанным и на него ответили, а не просто проигнорировали? На это отвечает механика цепочки. Цепочка обзора, которая прошла все четыре этапа и завершилась без согласия, является именно тем доказательством: возражение было сделано, на него ответили, его настойчиво обсуждали и снова ответили, зафиксировав это, прежде чем несогласный согласился. Несогласный задокументирован как тот, кто был услышан — что и делает последующее согласие разумным, а не просто послушным.

Шаг 10: Замещение без удаления

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

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

Честные ограничения

• ✗Это не заменяет ADR в вашем репозитории, если ваша организация требует, чтобы они были под версионным контролем рядом с кодом. Экспортируйте и зафиксируйте сводку; используйте дерево для той части, в которой markdown плох — дебаты.
• ✗Нет поля статуса ADR. Предложенный/принятый/заменённый — это соглашение о связке, которое вы поддерживаете, а не то, что требует продукт.
• ✗Цепь состоит из четырех витков. Глубокое архитектурное несогласие потребует звонка; цепь является записью того, что уже было испытано до этого.
• ✗Рейтинги — это одно значение с меткой, а не взвешенная многокритериальная оценка.
• ✗Это не заставляет никого писать хороший контекст. Структура снижает стоимость хорошей записи; она не обеспечивает суждение.

Практические занятия

• ✓Одно RFC, одно обсуждение. Сопротивляйтесь мега-дереву, охватывающему всю архитектуру квартала — ссылки на супрессию связывают решения лучше, чем вложенность.
• ✓Семя из того, что существует. Транскрипция с большим количеством решений или ваша старая папка ADR, извлеченная, дает дебатам хороший старт — помеченная как импортированная, чтобы живые аргументы оставались различимыми.
• ✓Поместите имена рецензентов на их цепочки и оставьте их там. Атрибуция — это ответственность; анонимные архитектурные возражения превращаются в фольклор.
• ✓Раздел последствий принадлежит решающему, никому другому. Принятые недостатки, написанные человеком, который их принял, имеют другой вес, чем предупреждения рецензента.

ADR-014, версия, которая отвечает

Вернемся к вопросу нового технического руководителя. В перестроенной версии ADR-014 является узлом: решение очереди с его обоснованием, три контекстные силы (одна из которых теперь устарела — явно), отклоненный синхронный API-собрат, чье фатальное имя указывает на старый лимит скорости, четыре завершенные цепочки обзоров, включая цепочку старшего инженера, и эталон, прикрепленный в качестве доказательства. Технический руководитель читает в течение десяти минут, видит, что лимит скорости изменился, и открывает заменяющее предложение, связанное со старым узлом. Никто не копается в Slack. Это и есть вся суть: цепочки достигают соглашения, дерево фиксирует это — и запись отвечает на вопросы, о которых вы не знали, что они будут заданы.