ADR — записи о решениях

Тема дорожной карты · Software Architecture

ADR (Architecture Decision Records) представляют собой короткие markdown-файлы, которые фиксируют архитектурные решения, их контекст, принятое решение и последствия. Эти файлы нумеруются последовательно (ADR-001, ADR-002...) и коммитируются в репозиторий вместе с кодом. АDR являются неизменяемыми и добавочными, что позволяет создавать новые записи, которые заменяют старые решения, сохраняя историю решений для последующего анализа.

Как это работает

ADR хранятся в директории docs/decisions/, которая расположена рядом с описываемым кодом. Каждый файл ADR должен помещаться на одном экране, не превышая 200-400 строк. В обязательном порядке включаются следующие разделы: Title (название решения), Status (статус решения: proposed, accepted, deprecated, superseded), Date (дата принятия решения), Context (контекст решения), Decision (принятое решение), Consequences (последствия решения). В дополнение к обязательным разделам, могут быть добавлены опциональные разделы: Alternatives Considered (рассмотренные альтернативы) и References (ссылки на дополнительную информацию). Важно писать ADR сразу после принятия решения, чтобы сохранить актуальность и полноту информации. Ретроспективное написание ADR теряет большую часть своей ценности, так как альтернативы и ограничения могут быть забыты.

Когда применять

ADR следует использовать для любых решений, чьё обоснование вы хотели бы запомнить через 12 месяцев. Типичные триггеры включают выбор базы данных, контракта публичного API, топологии деплоя, именования ограничений (например, "мы не будем использовать технологию X") и принятия крупной библиотеки или фреймворка. Однако, следует избегать написания ADR для эфемерных деталей реализации, которые могут меняться через обычный процесс рефакторинга.

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

  1. ADR как документация — использование ADR для документирования текущего состояния вместо решения, которое привело к нему. Это утрачивает историческое обоснование и делает ADR менее полезными.
  2. Нет обновлений статуса — ADR, помеченные 'accepted', остаются таковыми навсегда, даже после того как они были заменены. Это приводит к тому, что никто не знает, какие решения актуальны.
  3. Слишком мало ADR — только самые важные решения получают ADR, в то время как среднего уровня решения остаются незарегистрированными. Это приводит к возникновению вопросов "почему это вот так?" годы спустя.

Связанные понятия

Полезные ресурсы

Проверить знания (1)

Загрузка вопросов…