ADR (Architecture Decision Record): как в небольшой команде сохранить, почему выбрали именно эту архитектуру

«Почему здесь обмен файлами? Разве нельзя просто читать из БД?» — разработчик, который открыл код унаследованной системы, почти наверняка натыкается на такой вопрос. И чаще всего человека, который знал ответ, в проекте уже нет.

Причина, скорее всего, была. Возможно, не дали разрешение напрямую подключаться к БД другой системы. Возможно, при тогдашних сроках это был единственный достаточно безопасный вариант. Но если обоснование не записано, преемник либо замирает перед кодом, к которому непонятно, можно ли прикасаться, либо ломает его — вместе с той самой причиной.

В этом блоге мы уже разбирали, как вести заказную разработку, в статье «Что нужно продумать перед заказом разработки Windows-приложения», а рамки договора — в статье «Выбор между квазидоверительным договором и договором подряда — уроки из „Модельной сделки и договора“ IPA». Эта статья — про то, что идёт дальше: как сделать так, чтобы система жила несколько лет после сдачи. Разберём ADR (Architecture Decision Record) — способ с минимальными затратами сохранять обоснование архитектурных решений. Ориентир — небольшая заказная или внутренняя разработка.

1. Сначала вывод

• Сначала стоит сохранять записи о решениях, а не исчерпывающий проектный документ. При сопровождении больнее не «что делает код», а «почему так сделали».
• ADR — лёгкий формат, который фиксирует одно решение в одном файле по шаблону «заголовок / статус / контекст / решение / последствия». Майкл Найгард предложил его в 2011 году; норма — не больше одной-двух страниц на запись.¹
• Хранить в том же репозитории, что и код (например, docs/adr/0001-title.md). Не в вики и не в общей папке: версионировать вместе с кодом и смотреть на ревью вместе с ним.¹²
• Решения не перезаписывают. Если курс меняется, добавляют новый ADR, а у старого статус ставят в Superseded (заменён) и ставят перекрёстные ссылки. ADR — журнал только для добавления записей.²
• Пишут не всё подряд, а только решения, которые трудно потом сменить, где было несколько разумных вариантов, или где решающим стали ограничения. Правила именования и настройки форматтера — не тема ADR.²
• По опыту автора, практика живёт, если одну запись можно написать за 15–30 минут. Тяжёлый шаблон обычно умирает после первых трёх записей.
• В заказной разработке ADR становится артефактом, которым можно делиться с заказчиком. На приёмке это материал для объяснений, при смене ответственных или подрядчика — документ передачи как есть.

Сноски в тексте опираются на три первоисточника. Это оригинальная статья Майкла Найгарда, где задана форма ADR¹; руководство Well-Architected Framework на Microsoft Learn, где собраны рабочие правила (только добавление записей, узкий круг тем, хранение под контролем версий)²; и сообщественный сайт adr.github.io с шаблонами и инструментами³. Дальнейшие номера сносок указывают на один из этих трёх.

На схеме сплошная линия обозначает отношение, которое выполняется всегда, а пунктирная — условное отношение (условия указаны в пояснении к каждому отношению на странице сведений). Полный список отношений (всего 15, с доказательствами и степенью уверенности) и определения основных понятий собраны на странице сведений карты знаний (на японском). Данные: JSON-LD / Turtle

2. Проблема «непонятно, почему так устроено»

2.1 Код говорит What, но не говорит Why

По коду «что он делает» при достаточном времени ещё можно понять. Непонятно другое — «почему» в вопросах вроде таких.

• Почему СУБД — SQLite, а не SQL Server
• Почему интеграция с другой системой — передача CSV-файлов, а не веб-API
• Почему только этот отчёт запускает Excel и печатает из него
• Почему до сих пор .NET Framework, а не актуальный .NET

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

2.2 Места, куда обычно кладут решение, за несколько лет пропадают

Где сегодня на самом деле живёт обоснование архитектурного решения? Сравним обычные места.

Архитектурное руководство Microsoft говорит прямо: незафиксированное решение забывается и приводит к повторному разбору того же спора и к изменениям вразрез с исходным замыслом.²

2.3 В заказной разработке граница договора становится границей памяти

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

С точки зрения договора тоже обычно, что разработка и сопровождение — разные договоры и разные этапы (эту структуру мы разбирали в статье про «Модельную сделку и договор» IPA). И как мы уже разбирали в «Как правильно работать по квазидоверительному договору», именно потому, что при квазидоверительном договоре исполнитель ведёт работу автономно, запись, по которой заказчик видит, что именно решили и как, становится опорой доверия. ADR помогает и там, и там.

3. Что такое ADR

3.1 Предложение Найгарда — пять элементов и потолок в две страницы

ADR — формат, который Майкл Найгард предложил в статье блога 2011 года «Documenting Architecture Decisions».¹ Суть такая.

• Один файл на одно решение. Файлы нумеруют по порядку, номер повторно не используют
• Файл — в лёгком формате вроде Markdown, внутри репозитория проекта
• Структура — пять элементов: заголовок / статус / контекст / решение / последствия (Consequences)
• Статус идёт от предложенного (proposed) к принятому (accepted); если решение отменяют, его переводят в устаревшее (deprecated) или заменённое (superseded). Старую запись не удаляют
• Весь документ — не больше одной-двух страниц. Пишут связным текстом, который будущий разработчик читает как разговор

Если нарисовать только движение статуса, сразу видно, что ADR — «журнал только для добавления».

stateDiagram-v2
    [*] --> proposed: Завести ADR
    proposed --> accepted: Утвердить на ревью
    accepted --> deprecated: Само решение стало ненужным
    accepted --> superseded: Новый ADR заменил это решение
    deprecated --> [*]
    superseded --> [*]

На любом переходе меняют только строку статуса. Текст контекста и решения не трогают. Когда запись переводят из accepted в superseded, в старый ADR добавляют одну строку — ссылку на новый. Прошлые состояния не затираются, поэтому потом можно проследить, когда и почему сменился курс.

В названии есть слово «архитектура», но это не приём только для крупных систем. Наоборот, этот минимальный шаблон как раз работает в небольшой разработке, где нет выделенного архитектора и человека за документацию. Шаблоны и инструменты ADR собраны на сайте сообщества (adr.github.io) — удобная точка входа в идею «фиксировать архитектурно значимое решение вместе с обоснованием и компромиссами».³

3.2 Шаблон на Markdown

Минимальный шаблон, которым я пользуюсь на небольших проектах, в исходном формате Найгарда.

# ADR-NNNN: (решение одной короткой фразой)

## Статус

Предложено | Принято | Устарело | Заменено (→ ADR-MMMM)

## Контекст

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

## Решение

Сказать прямо, в действительном залоге: «делаем то-то».
От одного до трёх предложений.

## Последствия

И что становится лучше, и что становится хуже (компромиссы).
Если есть условие, при котором решение стоит пересмотреть, указать его.

В поле статуса можно указать только состояние, но лучше писать дату смены, например Принято (2026-07-17). Примеры в главе 7 сделаны так же. Раз журнал только для добавления, «когда утвердили» и «когда заменили» почти так же важны, как сам текст. При замене в одну строку кладут и дату, и ссылку: Заменено (2026-08-20) — заменяется ADR-0007. Внутри проекта выберите один из двух способов и держитесь его.

Главное — в «Последствиях» писать и минусы. Решение без компромиссов почти не стоит фиксировать. Руководство Microsoft отдельно подчёркивает: последствия решения не скрывают ни намеренно, ни случайно, а запись без обоснования со временем теряет ценность.²

4. Что писать в ADR, а что — нет

Главная причина, почему ADR бросают, — попытка фиксировать всё подряд. В руководстве Microsoft сказано ограничиться тем, что влияет на структуру системы или важные свойства качества и что потом трудно откатить.² В повседневных решениях это выглядит так.

Критерий при сомнении один: захочет ли человек, который через год откроет этот код (включая вас самих), спросить «почему?» Если да — пишите. Если это и так видно из кода или настроек — не пишите.

Вторая ловушка — думать о нужной детализации через «какой это тип документа». Если заранее развести роли, как ниже, сомнений меньше.

5. Как вести ADR в небольшой заказной разработке

5.1 Каталог и имена файлов

В корне репозитория заводят docs/adr/ и кладут файлы с порядковым номером и коротким слагом. Слаг (slug) — это короткая строка только из латинских строчных букв и дефисов, которая кратко описывает содержание (например, use-sqlite-for-local-storage). Её ставят в имя файла и в URL, поэтому пробелы, японские символы и знаки пунктуации не используют: так имя проще обрабатывать программно.

docs/
  adr/
    0001-record-architecture-decisions.md
    0002-use-sqlite-for-local-storage.md
    0003-excel-report-via-com-automation.md
    0007-excel-report-via-openxml-library.md

В этом примере нет 0004–0006, потому что эти номера уже заняты другими решениями (способ аутентификации, устройство логов и т. п.). 0007 заменяет подход из 0003, но номера не сжимают и 0003 повторно не используют. Порядковый номер только растёт в порядке появления решений; пропуски — нормальная картина.

Первую запись обычно делают про само решение вести ADR. Тогда преемнику достаточно открыть docs/adr/, чтобы понять и правила ведения.

5.2 Когда писать и кто рецензирует

• Писать сразу после того, как решили. Как закрытие обсуждения архитектуры итог совещания в тот же день превращают в ADR. Как будет видно ниже, писать пачкой потом — это провал.
• Включать ADR в код-ревью. Смотрят только одно: есть ли в pull request, который меняет подход, добавление или обновление ADR. Отдельное совещание для утверждения ADR не нужно — для небольшой команды реалистичный ответ как раз включить это в обычное ревью. Хранить ADR под контролем версий рекомендует и руководство Microsoft.²
• Если решение отменяют, пишут новый ADR, у старого статус ставят в Superseded и ставят перекрёстные ссылки. Текст не переписывают. Не править утверждённую запись и держать историю цепочкой замен — это и значит вести ADR как журнал только для добавления.²

5.3 ADR как артефакт, которым делятся с заказчиком

В заказной разработке стоит делиться ADR с заказчиком как частью поставки. Эффекта три.

1. Материал для приёмки и объяснений. Вместо устного рассказа, почему система устроена именно так, достаточно показать ADR. Если решающим были ограничения (бюджет, срок, окружение), заказчик сам в них участвовал, и запись потом не даёт разъехаться пониманию.
2. Страховка на случай смены подрядчика. Со стороны заказчика наличие «истории решений», которую можно отдать следующему подрядчику, сильно меняет стоимость и риск передачи. Как готовиться к заказу, мы писали в «Что нужно продумать перед заказом разработки Windows-приложения», но когда на этапе договора решают, какие документы получить после сдачи, ADR — один из вариантов с самым выгодным соотношением пользы и затрат.
3. Хорошо стыкуется с отчётностью по квазидоверительному договору. Такой договор требует отчёта о ходе работы, и ADR на этапе проектирования можно использовать как есть.

5.4 Реалистичная оценка времени

По опыту автора, одна запись по шаблону занимает 15–30 минут. На небольшом проекте решения появляются несколько раз в месяц, так что один-два часа в месяц сохраняют всё «почему». По сравнению со временем, которое потом уходит на разбор, повторное рассмотрение и передачу дел, мест, где это не окупается, почти нет.

6. Типичные ошибки

Особенно легко попасться на «писать пачкой потом», когда ADR внедряют в уже работающую систему не с самого начала. Не пытайтесь восстановить все прошлые решения: реалистичнее вернуться и записать несколько главных, которые ещё помните, а дальше копить записи начиная с сегодняшних. Даже в существующей (brownfield) системе имеет смысл задним числом зафиксировать те прошлые решения, которые ещё удаётся восстановить.²

7. Примеры ADR

На типичных темах небольшого Windows-приложения для бизнеса покажем две записи целиком (содержание обобщено).

Первая — классический технологический выбор: СУБД.

# ADR-0002: Бизнес-данные хранить в SQLite

## Статус

Принято (2026-07-17)

## Контекст

Это настольное приложение учёта склада для одной площадки.
Пользователей 2–3 человека, но на практике оно стоит на одном
основном ПК в канцелярии и им пользуются по очереди
(одновременно работает один человек). У заказчика нет сотрудника,
который мог бы сопровождать сервер БД, и нет бюджета на сервер.
Объём данных даже за 10 лет эксплуатации ожидается в пределах
нескольких сотен мегабайт.
Рассматривали SQL Server Express / SQLite / файл Access (.accdb).
SQL Server Express отклонили: у заказчика нет возможности постоянно
разворачивать сервер и проверять его работу после Windows Update.
Access отклонили из-за риска повреждения при одновременной записи
и слабых перспектив миграции.

## Решение

Для хранения данных принимаем SQLite. Файл БД не кладём в общую
папку, а держим локально на основном ПК. Резервные копии — ежедневный
снимок через VACUUM INTO на NAS (копировать «живой» файл во время
работы нельзя: из-за пропуска файла WAL и гонки записи получается
битая копия).

## Последствия

- Плюс: не нужно разворачивать и сопровождать сервер БД. Резервное копирование сводится к одной SQL-команде
- Плюс: среду выполнения можно класть в поставку приложения, установка проще
- Минус: запись блокируется на уровне всей БД, поэтому на несколько площадок и большую команду не масштабируется
- Минус: перенос на серверную БД потом потребует миграции данных и переделки слоя подключения
- Решение пересмотреть, как только понадобится одновременная работа с нескольких ПК (тогда — серверная БД или схема через API)

Коротко про термины SQLite из этого примера. VACUUM INTO — SQL-оператор, который записывает логическое содержимое работающей базы в другой файл. В официальной документации SQLite он описан как альтернатива Backup API, когда нужно сделать резервную копию работающей базы.⁴ WAL (Write-Ahead Logging) — журнальный режим, в котором изменения сначала пишутся в отдельный файл -wal и только потом попадают в основной. Если в этом режиме скопировать средствами ОС только файл .db, пока база работает, обновления, ещё лежащие в -wal, в копию не попадут — получится неполная резервная копия. Поэтому в «Решении» ADR-0002 отдельно прописан способ бэкапа: эта ловушка неотделима от самого решения.

Вторая запись — пример отмены уже принятого решения. Смотрите и на использование Superseded.

# ADR-0007: Excel-отчёты генерировать библиотекой, а не через COM

## Статус

Принято (2026-07-17) — заменяет ADR-0003 (COM-автоматизация)

## Контекст

Нужно выгружать накладные и месячные сводки в файлы Excel.
Сначала, по ADR-0003, это сделали через COM-автоматизацию Excel,
но в ночном пакетном задании без оператора процессы Excel регулярно
оставались висеть и останавливали обработку; плюс на машине запуска
нужна лицензия Office — это всплывало при каждом обновлении ПК.
Рассматривали продолжение COM (с мониторингом процессов) /
переход на библиотеку, которая пишет Open XML напрямую /
перевод отчётов в PDF (смена требований). PDF нельзя: контрагенты
рассчитывают, что смогут дописывать в Excel.

## Решение

Отчёты переводим на прямую генерацию .xlsx библиотекой.
От самого Excel не зависим. Оформление держим как шаблон .xlsx
в репозитории и заполняем ячейки.

## Последствия

- Плюс: Excel в среде выполнения больше не нужен, запуск без оператора стабильнее
- Плюс: зависающие процессы пропадают конструктивно
- Минус: доступны не все возможности Excel, часть оформления существующих отчётов придётся упростить
- Минус: перевод существующих отчётов в шаблоны потребует доработки
- ADR-0003 помечен как Superseded, со ссылкой на этот ADR

По этим двум записям уже видно, что они отвечают на вопросы, которые при передаче дел возникают всегда: «почему в этой системе нет серверной БД?» и «почему в коде отчётов остались следы запуска Excel?». Вместе это около 1500 знаков; на написание уходит меньше часа.

8. Итог

• При сопровождении и передаче дел теряется не What, а Why. Незафиксированное решение забывается и приводит к повторному разбору споров и к изменениям вразрез с исходным замыслом.²
• ADR — лёгкий формат записи: одно решение — один файл, пять элементов, не больше одной-двух страниц. Исходная форма Найгарда в небольшой разработке работает как есть.¹
• Писать только решения, которые «трудно сменить», «были варианты» или «решающим стали ограничения». Соглашения и форматирование оставить автоматизации, в ADR их не включать.²
• Класть в docs/adr/, рецензировать вместе с pull request. Решения не перезаписывать, а заменять через Superseded, историю не затирать.¹²
• В заказной разработке ADR — поставка, которая ценна и заказчику: материал для объяснений на приёмке и документ передачи при смене подрядчика.
• 15–30 минут на запись. Начните со следующего архитектурного решения: напишите один ADR. Если система уже есть — вернитесь и зафиксируйте несколько главных решений, которые ещё помните.

Похожие статьи

• Как должен быть заключён договор на разработку и сопровождение — выбор между квазидоверительным договором и договором подряда по «Модельной сделке и договору» IPA
• Как правильно работать по квазидоверительному договору, чтобы не скатываться в скрытый подряд
• Что нужно продумать перед заказом разработки Windows-приложения
• Основы написания руководства в Word — неудачные примеры и как их исправить

Смежные направления консультаций

KomuraSoft LLC помогает внедрять ADR в рамках ревью архитектуры, инвентаризировать и документировать решения уже работающей системы и выстраивать сопровождение с расчётом на передачу дел и смену подрядчика.

• Техническая консультация и ревью архитектуры
• Разработка Windows-приложений
• Доработка и сопровождение существующего Windows-ПО
• Контакты

Источники

Похожие статьи

Недавние статьи с теми же тегами помогут подробнее изучить близкие темы.

Связанные темы

Эти страницы показывают тему статьи в более широком контексте услуг и решений.

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

Вопросы, которые часто возникают при консультациях по теме статьи.

Что такое ADR (Architecture Decision Record)?

Это документ, который фиксирует одно решение о структуре программной системы в одном файле по короткому шаблону: заголовок / статус / контекст / решение / последствия. Лёгкий формат предложил Майкл Найгард в 2011 году. Базовое правило: не больше одной-двух страниц на запись и коммит Markdown-файла в тот же репозиторий, что и код. В отличие от исчерпывающего проектного документа, ADR заточен на то, чтобы сохранить, почему выбрали именно этот вариант и какие альтернативы отвергли.

Что писать в ADR, а что можно не писать?

Стоит фиксировать решения, которые потом трудно сменить (выбор СУБД или способа обмена, формат внешней интеграции и т. п.), решения, выбранные из нескольких разумных вариантов, и решения, где решающим стали ограничения — бюджет, срок, уже имеющиеся наработки. Наоборот, то, что инструменты и соглашения и так унифицируют (правила именования, настройки форматтера), и то, что легко сменить и что видно из кода, в ADR не нужно. Если сомневаетесь, спросите себя: «через год я захочу спросить, почему так?»

Если решение нужно изменить, можно ли переписать старый ADR?

Нет. Старый не переписывают — добавляют новый ADR, который его заменяет. У старого статус меняют на Superseded (заменён), ставят ссылку на новый и оставляют текст как есть. В руководстве Microsoft ADR рекомендуют вести как журнал только для добавления и не править уже утверждённую запись задним числом. Тогда история — когда и почему сменился курс — сама становится материалом для передачи дел.

Если есть проектная документация, ADR не нужен?

Роли разные. Проектный документ показывает, какова структура сейчас (What), но обычно не сохраняет, почему выбрали именно её и что отвергли (Why). К тому же исчерпывающий проектный документ часто перестают обновлять, и через несколько лет он расходится с кодом. ADR на каждое решение добавляет всего несколько сотен знаков, поэтому его проще не забросить: даже когда проектный документ устарел, обоснование решений остаётся. В небольшой разработке реалистичная схема — держать подробный проектный документ тонким и вести рядом ADR.

Об авторе

Страница с профилем автора статьи.

Го Комура

Представитель KomuraSoft LLC

Специализируется на разработке программного обеспечения для Windows, техническом консалтинге и расследовании сбоев, особенно в проектах с унаследованными системами и трудно воспроизводимыми ошибками.