Как написать ADR с помощью ИИ и сохранить причины решения

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

Когда нужен ADR

Запись архитектурного решения фиксирует значимый технический выбор вместе с контекстом и последствиями. В документации AWS Prescriptive Guidance сказано, что каждый ADR описывает решение, его контекст и последствия, а функциональные и нефункциональные требования выступают самыми частыми входами процесса. В материалах Microsoft Learn для Azure Well-Architected подчёркнуто: ADR охватывает ключевые решения и отброшенные альтернативы для архитектурно значимых требований, а включать стоит выбор, который затрагивает структуру системы, ключевые атрибуты качества или трудно обратим.

Практический признак: решение трудно откатить, оно затрагивает нескольких людей и объясняет будущему участнику, почему система выглядит именно так. В репозитории architecture-decision-record на GitHub собраны шаблоны и примеры, а также сформулированы вопросы команды: что оправдывает создание ADR, что оправдывает отказ от него, каков жизненный цикл записи. Там же приведён пример ответа: ADR нужен, когда команда хочет, чтобы будущие разработчики поняли «почему» сделанного. Отказ уместен для решений ограниченного масштаба, времени, риска и стоимости либо уже покрытых стандартами и политиками.

Отдельная развилка — выбор формата хранения. Тот же репозиторий перечисляет варианты: Google Drive и онлайн-редактирование, файл на каждый ADR под контролем версий git, трекер планирования вроде Jira, вики. Для учебного примера ниже выбран git: файл на запись, читаемый текст, история правок.

Соберите ограничения и статус

До обращения к модели выпишите входные данные одной заметкой. Нужны: число участников, характер данных, частота поступления, наличие администратора, потребность в совместной правке, текущие предпочтения и нерешённые вопросы. В учебном примере заметка выглядит так.

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

Статус — часть входа. В документации Microsoft Learn перечислены статусы Proposed, Accepted и Superseded: отслеживание состояния проясняет текущее положение каждой записи по мере роста их числа. Там же сказано, что ADR служит журналом с добавлением в конец, принятые записи задним числом не редактируются, а при смене решения пишется новая запись со ссылкой на исходную. Документация AWS формулирует то же через неизменяемость: после принятия запись становится неизменяемой, при новых вводных команда предлагает новый ADR.

Разделяйте два входа: черновик предложения и событие принятия. Черновик живёт в статусе Proposed и допускает правки. Событие принятия — отдельная запись с датой, владельцем, версией и списком участников. В документации AWS указано: если команда одобряет ADR, владелец добавляет отметку времени, версию и список заинтересованных сторон. Там же отмечено, что создать ADR может любой участник команды, а команде стоит определить, что означает владение записью.

Промпт преобразования заметок

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

Составь Proposed ADR-007: контекст, варианты, предлагаемое решение,
положительные и отрицательные последствия, открытые вопросы.
Для каждого аргумента укажи основание в заметках.
Не превращай предложение в принятую запись, не назначай владельца
копий и не придумывай сравнение безопасности или цены.

Что менять под себя: [номер записи], [тему развилки], [перечень заметок]. Если развилка затрагивает несколько фаз, документация Microsoft Learn советует разбить её на отдельные записи по фазам — краткосрочной, среднесрочной, долгосрочной — и вести каждую как самостоятельный ADR.

Проверка черновика идёт по трём вопросам. Первый: у каждого аргумента есть основание в заметках. Второй: открытые вопросы остались открытыми. Третий: предложение не выдаёт себя за принятое решение. В учебном примере правильный разбор сохраняет вопрос «кто делает копии» без ответа.

Заполните Proposed с открытым вопросом

Черновик ADR-007 в статусе Proposed собирается из заметок без домыслов.

ADR-007 — Локальная папка для еженедельных CSV
Статус: Proposed
Контекст: три сотрудника, неперсональные CSV раз в неделю;
администратора нет; совместная правка не нужна.
Варианты: локальная папка с ручными копиями;
объектное хранилище с удалённым доступом.
Предлагаемое решение: локальная папка.
Последствия: меньше настройки; ручные копии; нет удалённого доступа.
Открытый вопрос: кто делает копии?

Последствия перечисляются целиком. В заметке Cognitect о документировании архитектурных решений сказано: в этом разделе перечисляются все последствия, включая неблагоприятные. Там же задан ориентир объёма: весь документ занимает одну-две страницы. В репозитории architecture-decision-record раздел о хорошем «Context» советует объяснять ситуацию организации и бизнес-приоритеты, включать доводы и компромиссы в терминах целей команды, а раздел о последствиях — описывать эффекты, результаты и дальнейшие шаги.

Нумерация ведётся последовательно. В заметке Cognitect указано: ADR нумеруются последовательно и монотонно, номера не переиспользуются. Это удерживает ссылки между записями однозначными. До принятия владелец записи вправе согласовывать изменения предложения — черновик остаётся рабочим документом.

Событие принятия с владельцем и датой

Принятие фиксируют отдельным событием с владельцем и датой. В учебном примере 11 ноября 2026 команда согласовала локальную папку, а координатор Ирина согласилась делать резервную копию после каждой выгрузки. Ирина — владелец ADR-007, версия 1, статус Accepted, участники: координатор, аналитик, оператор.

Событие принятия ADR-007
Дата: 11 ноября 2026
Владелец: Ирина, координатор
Версия: 1
Статус: Accepted
Участники: координатор, аналитик, оператор
Решение: локальная папка; резервная копия после каждой выгрузки.

С этого момента запись хранит принятое решение и задним числом не переписывается. Документация AWS описывает это как неизменяемость принятого ADR, а Microsoft Learn — как журнал с добавлением в конец. Отметка времени, версия и список заинтересованных сторон добавляются владельцем при одобрении — это прямо указано в документации AWS.

Разделение черновика и события даёт проверяемость: видно, какие формулировки существовали до согласования и что именно изменилось при принятии. В учебном примере до 11 ноября вопрос о копиях был открыт, после — закрыт назначением ответственного.

Сохраните оба вида последствий

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

Документация Microsoft Learn предупреждает: не скрывайте последствия решения намеренно или случайно и всегда включайте контекст и обоснование — запись без обоснования теряет ценность, когда обстоятельства меняются. Там же сказано: держите записи краткими, утвердительными, по теме и фактичными, а превращать ADR в проектный справочник не стоит — дополнительный материал даётся ссылкой, само решение остаётся понятным без него.

Полный Proposed по новому условию

Новое условие запускает новую запись. В учебном примере 18 ноября 2026 команда перешла на удалённую работу и стала получать выгрузки ежедневно; локальная папка перестала закрывать доступ. Модель готовит полный ADR-008 в статусе Proposed, не меняя ADR-007.

ADR-008 — Объектное хранилище для удалённой работы
Статус: Proposed
Контекст: 18 ноября 2026 команда работает удалённо, выгрузки ежедневные;
локальная папка не закрывает доступ.
Варианты: пересылать файлы вручную; объектное хранилище с правами.
Предлагаемое решение: объектное хранилище.
Причина: нужен общий удалённый доступ.
Последствия: назначить администратора, настроить доступ,
новый порядок копирования.
Открыто: кто администратор?
Связь: proposed replacement for ADR-007.

Причина формулируется узко: нужен общий удалённый доступ. Выбор не означает утверждения о большей безопасности — это отдельное ограничение формулировки. До принятия ADR-008 статус ADR-007 остаётся Accepted, а связь помечается как предложенная замена. В документации AWS сказано: если новые вводные требуют другого решения, команда предлагает новый ADR.

Проверка этого шага: ADR-007 не редактируется, ADR-008 существует отдельным файлом, открытый вопрос об администраторе остаётся открытым, а связь между записями односторонняя — от новой к старой.

Supersession после отдельного принятия

Замена статуса происходит только после отдельного события принятия. В учебном примере 20 ноября команда назначила администратора Павла и приняла ADR-008; владелец — Ирина, версия 1, участники: координатор, аналитик, оператор, администратор. Только теперь ADR-008 получает статус Accepted, ADR-007 — Superseded, а ссылки становятся взаимными. Текст принятого ADR-007 сохраняется.

Событие принятия ADR-008
Дата: 20 ноября 2026
Владелец: Ирина, координатор
Версия: 1
Статус: Accepted
Участники: координатор, аналитик, оператор, администратор
Администратор: Павел
Итог: ADR-008 = Accepted; ADR-007 = Superseded; ссылки взаимные.

Документация AWS описывает порядок так: когда команда принимает новый ADR, он заменяет предыдущий. Microsoft Learn добавляет: при смене решения пишется новая запись со ссылкой на исходную, что сохраняет историю размышлений и показывает, когда и почему направление изменилось. В репозитории architecture-decision-record сказано, что новый ADR создаётся, когда решение заменяет или отменяет предыдущий ADR.

Порядок шагов держит причины решения проверяемыми: черновик, событие принятия, новое условие, новое событие принятия, взаимные ссылки.

Частые вопросы

Что такое architecture decision record?

Это документ, фиксирующий значимое архитектурное решение вместе с контекстом и последствиями. В репозитории architecture-decision-record приведено такое определение, а также родственные термины: архитектурное решение, журнал решений проекта, архитектурно значимое требование. Совокупность записей проекта образует журнал решений — об этом сказано на сайте adr.github.io. Запись отвечает на вопрос «почему», который иначе теряется при смене команды.

Кто может создать ADR и кто им владеет?

В документации AWS Prescriptive Guidance указано: создать ADR может любой участник команды, а команде стоит определить, что означает владение записью. Владелец добавляет отметку времени, версию и список заинтересованных сторон при одобрении. В учебном примере владельцем ADR-007 и ADR-008 выступает Ирина, координатор. В репозитории architecture-decision-record предложен пример ответа: ADR может предложить любой человек в организации, прочитавший вводную страницу.

Можно ли править ADR после принятия?

Принятая запись не редактируется задним числом. Документация AWS формулирует это через неизменяемость после принятия, Microsoft Learn — через журнал с добавлением в конец и новую запись при смене решения. В репозитории architecture-decision-record отмечено, что на практике команды иногда добавляют новую информацию с отметкой даты и пометкой о более позднем поступлении. Выбор режима команда фиксирует заранее.

Как ИИ помогает и где остаётся ручное решение?

Модель преобразует заметки в структуру: контекст, варианты, последствия, открытые вопросы, с указанием основания для каждого аргумента. Ручными остаются согласование, назначение владельца, дата принятия и решение о замене записи. В учебном примере ИИ готовит Proposed, а события 11 и 20 ноября 2026 вводятся отдельно. Такое разделение удерживает причины решения привязанными к людям и датам.

Когда выпускать новый ADR вместо правки старого?

Новый ADR нужен, когда меняется ранее принятое решение. Документация AWS указывает: при новых вводных команда предлагает новый ADR, а его принятие заменяет предыдущий. Microsoft Learn советует разбивать многофазные решения на отдельные записи по фазам. В учебном примере переход на удалённую работу 18 ноября 2026 запустил ADR-008, а ADR-007 сохранил исходный текст.