Архітектура без випадковостей: фіксуємо рішення
Практичний спосіб перетворити важливі архітектурні рішення на зрозумілу й корисну історію проєкту.
Архітектура стає крихкою не тоді, коли команда обирає недосконалу технологію. Вона стає крихкою, коли ніхто не пам’ятає, чому це рішення було прийнято.
Фіксуйте контекст, а не лише результат
Короткий Architecture Decision Record має відповісти на чотири питання:
- Яку проблему ми вирішуємо?
- Які обмеження вплинули на вибір?
- Яке рішення прийнято?
- Які наслідки команда свідомо приймає?
# Використовуємо локальний MDX для внутрішніх статей
Контекст: редакційний контент має версіонуватися разом із кодом.
Рішення: зберігати статті у content/posts/.
Наслідок: публікація потребує pull request і build-перевірки.Ознака хорошого рішення
Новий учасник команди може прочитати запис через пів року й зрозуміти не тільки те, що працює зараз, а й чому простіша на вигляд альтернатива була відхилена.
ADR не замінює документацію системи. Він зберігає причинно-наслідковий зв’язок між проблемою, рішенням і компромісами.