Architecture Decision Record, ADR

Что это? Идея в ведении журнала принятия архитектурных решений на проекте. Записи в ADR ведутся для возможности восстановления хронологии и причин применения того или иного компонента/технологии на проекте.

ADR делется как лог записией, на подобии CHANGELOG, только описывает те решения по архитектуре, которые применялись и почему. Записи не должны расписывать полностью аргументацию, они должны носить не формальный и краткий формат, но при этом, описывать причину принятия решения. Т.е. не просто “Интеграция с компонентом X посредством Kafka Inbox”, а “Интеграция с компонентом X посредством Kafka Inbox в связи с чрезвычайной сложностью и запустанностью сетевой связанности между компонентами систем A и B в промышленной среде. Устранение сетевых ограничений займет не менее N недель, а полная интеграция необходима в течении N недель. Для интеграции будет использоваться публичная Kafka в промышленном контуре, но с ограничениями по доступу к топику через соответствующий сертификат.”.
Каждая запись в ADR должна полностью отображать те факторы, которые повлияли на решение. Будь то это ограничения, в которых проинималось решение, отсутствие опыта с каким-то компонентом, даже простое нежелание сложностей.
ADR только пополняется изменениями. В существующие записи изменения не вносятся, даже если новое решение отменяет или изменяет предыдущее. Это формирует исторический лог принятия решений - именно то, что нужно.

Желательно указание авторства и того состава участников, которые принимали это решение.

Параллельно с внесением записи в ADR можно еще раз подумать - “А точно это решение правильное? Возможно, есть другие способы решения пробемы? Какие?”. Ну и конечно, запись в ADR должна вноситься в момент принятия решения, а не по прошествии (большого) времени!

Пример записи в ADR

ADR.md

1
2
3

[ADR-0000](0000-database.md) - Database choice
[ADR-0001](0001-platform.md) - Platform decision
[ADR-0002](0002-xzy-integration.md) - XZY integration

0000-database.md

---
status: Proposed / Accepted / Rejected / Deprecated / Superseded
date: YYYY-MM-DD HH:MM
authors: X, Y, Z, Team A
---

# AD: ${subject}

## Context and Problem Statement

Body of a problem and environmental description

## Decision Drivers

* Desire to divide the overall system into manageable parts to reduce complexity
* Ability to exchange system parts without affecting others

## Options

1. Alternative 1. Short description
2. Alternative 2. Short description
3. Alternative 3. Short description

## Outcomes

Final decision on the suggestion

### Consequences

* the list of consequences regarding the confirmed decision;
* either the suggestion was accepted or rejected.

## References

* some additional information;
* references to the tickets or documents.