Формат ADR
Тема дорожной карты · Software Architecture
Формат ADR (Acceptance Decision Records) представляет собой структурированный способ записи и документирования решений, принятых в процессе разработки программного обеспечения. Этот формат позволяет вести систематический учет решений, их последствий и контекста, что значительно облегчает работу для будущих разработчиков и упрощает понимание сложных архитектурных решений.
Как это работает
Title: короткий, описательный — 'ADR-003: Использовать Postgres как основную БД'. Status: один из proposed/accepted/deprecated/superseded. Context: 3-5 параграфов, объясняющих ситуацию, силы и ограничения — самая важная секция. Decision: выбранное направление, заявлено декларативно. Consequences: что становится проще (плюсы) и сложнее (минусы) из-за этого решения. Прочитайте свой ADR вслух — если не имеет смысла без внешнего контекста, секция Context нуждается в работе.
Формат ADR включает в себя несколько ключевых элементов:
- Title: краткое и точное описание решения.
- Status: статус решения (proposed/accepted/deprecated/superseded).
- Context: описание ситуации, сил, которые влияют на решение, и ограничений.
- Decision: само решение, принятое для решения проблемы или задачи.
- Consequences: последствия принятия решения, как положительные, так и отрицательные.
Когда применять
Используйте формат ADR, если ваша организация не стандартизировала другой шаблон. Вариации (MADR, Y-Statements) оптимизируются под разные организации. Выберите один и держитесь; консистентность важнее выбора формата.
Формат ADR особенно полезен в больших проектах, где требуется документирование множества решений. Он помогает избежать путаницы и обеспечивает последовательность в документировании решений.
Типичные ошибки
(1) All-decision, no-context — ADR, заявляющие решение, но пропускающие обоснование; бесполезны через 12 месяцев. (2) All-consequences, no-decision — закопанный lede; решение должно быть одним предложением жирным близко к верху. (3) Добавление секций без цели — раздутые шаблоны с 'Risks', 'Open Questions', 'Stakeholders'; большинству ADR они не нужны.