Як написати Architecture Decision Record (ADR) англійською мовою
Практичний посібник з написання чітких, професійних записів архітектурних рішень англійською мовою: структура, словник, приклади шаблонів і фрази, які використовують досвідчені архітектори.
Запис рішення архітектури (ADR) — це короткий документ, що відображає важливе архітектурне рішення: що було вирішено, чому і які наслідки. ADR читають теперішні колеги, майбутні інженери і менеджери — часто місяцями або роками пізніше. Добре написане АСД вимагає чіткої, точної англійської мови: ви документуєте рішення, обґрунтування якого має бути зрозумілим без доступу до початкового обговорення.
У цьому довіднику розглянуто формат ADR, потрібний вам словник, шаблони розділів і мовні шаблони, які роблять ADR зрозумілими і корисними.
Що таке АТС (і чого не так)?
ADR ** не ** є проектним документом. Вона не пояснює як працює система — вона пояснює чому конкретний вибір був зроблений в конкретний момент часу.
Хороший ADR відповідає:
- Яку проблему ми вирішували?
- Які варіанти ми розглядали?
- Що ми вибрали і чому?
- Які ж мінуси ми приймаємо?
Погане АДР або виправдовує рішення після факту без розгляду альтернатив, або є таким довгим, що ніхто його не читає.
Стандартна структура ADR
Найпоширеніший формат ADR (з оригінального шаблону Майкла Найґарда) має п’ ять розділів:
- ** Заголовок ** — короткий, пронумерований, починається з дієслова
- ** Стан ** — запропоновано / прийнято / застаріле / замінено
- Context — Фонова інформація: яка проблема або сили призвели до цього рішення?
- Рішення — Що було обрано і чому
- Наслідки - що змінюється, що стає легшим, що стає важчим
Деякі команди додають розділи для ** Розглянуті альтернативи ** і ** Обґрунтування ** між Рішенням і Наслідками. Обидва підходи працюють — ключовим є послідовність у вашій команді.
Розділ 1: Титул
Заголовок повинен бути:
- Пронумеровані (ADR-001, ADR-023 тощо) для легкого пошуку
- Коротка — ідеально одна лінія
- Формулювання як рішення, а не як тема
** Хорошие названия: **
ADR- 001: Використовувати PostgreSQL як основну базу даних
- Нет, не надо ADR-015: Прийняти Terraform для всієї хмарної інфраструктури
- Нет, не надо ADR-023: Перехід з REST на gRPC для внутрішнього обміну послугами
- Нет, не надо ADR-031: Впровадження автоматичних виключників з використанням Resilience4j
** Слабкі заголовки (уникайте): **
ADR-001: Рішення бази даних
- Нет, не надо 1503 — Тернопіль
- Нет, не надо 1983 — «Розстріляний» реж
Розділ 2: Статус
Стан — це одне слово або коротка фраза. Спільні значення:
| Status | Meaning |
|---|---|
| Proposed | Under discussion, not yet accepted |
| Accepted | Approved and active |
| Deprecated | No longer recommended but not changed yet |
| Superseded by ADR-045 | Replaced by a later decision |
| Rejected | Considered but decided against |
“Статус: Прийнято — березень 2026”
- Нет, не надо “Статус: Замінено ADR-047 (жовтень 2026) — дивіться цей документ для поточного підходу.”
Розділ 3: Контекст
У розділі Контекст описується ситуація, яка призвела до необхідності прийняття рішення. Написайте його нейтральною мовою — не заохочуйте будь-який конкретний вибір. Описати сили, що грають роль: технічні обмеження, можливості команди, бізнес- вимоги, існуюча архітектура.
** Структура шаблона: **
- Яка система або компонента задіяна?
- Яка проблема чи потреба спонукала вас до такого рішення?
- Які обмеження або вимоги є актуальними?
- Які сили конкурують (швидкість проти послідовності, вартість проти гнучкості тощо)?
** Корисні фрази для контексту: **
Описуючи ситуацію:
Поточний архітектура використовує один екземпляр PostgreSQL для всіх читання і запису трафіку
- Нет, не надо «Згідно з даними Q1 2026, платіжна служба обробляє приблизно 500 операцій запису на секунду в піковій точці, а тестування навантаження передбачає, що це подвоїться протягом шести місяців»
- Нет, не надо Команда має досвід роботи з Python, але обмежений досвід роботи з Go
Опис проблеми:
«Перша проблема полягає в відсутності ізоляції сервісу — помилка в службі розрахунків може виснажити з’єднання з базою даних і привести до зниження не пов’язаних послуг»
- Нет, не надо «Ми потребуємо рішення, яке може бути розгорнуто і експлуатуватися командою з чотирьох осіб, без необхідності спеціальної експертизи інфраструктури»
- Нет, не надо «Поточне підхід не є стійким при прогнозованих темпах зростання.»
Визнання компромісів і конкуруючих сил:
«Існує напруга між простотою операцій та масштабованістю»
- Нет, не надо «Ми балансуємо бажання до послідовності з потребою в гнучкості на краях.»
- Нет, не надо «Першим обмеженням є час до виробництва: міграція повинна бути завершена до продовження контракту в Q3»
Розділ 4
У розділі « Рішення » чітко вказано вибір і пояснено обґрунтування. Вона повинна бути прямою і активною: «Ми використаємо X», а не «Було вирішено використовувати X»
** Структура шаблона: **
- Визначте рішення одним реченням
- Поясніть основні причини
- Посилання на розглянуті альтернативи (або посилання на окремий розділ Альтернативи)
** Корисні фрази: **
Вынесение решения:
«Ми приймемо джерело подій для домену життєвого циклу замовлення»
- Нет, не надо «Ми вирішили мігрувати з монолітного застосування Rails до набору незалежно розгорнутих послуг.»
- Нет, не надо «Наш підхід буде використовувати розподілений кеш (Redis) для зберігання даних сеансу, замінюючи поточні сеанси, підтримувані базою даних»
Дайте причини:
«Цей підхід був обраний, тому що він відповідає досвіду існуючої команди і уникає операційних витрат окремого трубопроводу розгортання»
- Нет, не надо «Першим драйвером є операційна вартість — підтримка двох окремих інфраструктурних стеків збільшує як когнітивне навантаження, так і фінансові витрати без пропорційної вигоди»
- Нет, не надо «Ключевим фактором в цьому рішенні була аудиторія — джерело подій забезпечує повний, незмінний історію всіх змін стану, що є вимогою до відповідності»
Визнання альтернатив:
«Ми розглядали MySQL як альтернативу, але відкинули її через існуючі інструменти команди PostgreSQL і сильнішу підтримку JSONB в PostgreSQL 14»
- Нет, не надо «Kafka був оцінений для рівня черги повідомлень, але був визнаний операційно важким для нашого поточного розміру команди. SQS було обрано за його керовану природу і нижче операційне навантаження. ”
- Нет, не надо «Альтернативним підходом було б збереження монолита і введення шаблонів удушення, але це було відкинуто, тому що тісне з’єднання робить паралельну роботу на тій же кодовій базі непрактичним»
Розділ 5: Наслідки
Розділ «Наслідки» є тим, що відрізняє хороший документ ADR від документа з виправданням. Вона відверта про те, що стає важче і які нові проблеми створює рішення.
** Структура шаблона: **
- Позитивні наслідки (що покращує)
- Негативні наслідки (що стає важче або дорожче)
- Нейтральні зміни (що тепер має відбутися по- іншому)
** Корисні фрази: **
Позитивні наслідки:
«Кожна служба тепер може бути розгорнута незалежно, зменшуючи координацію розгортання»
- Нет, не надо «Новий підхід значно спрощує шлях запису і вилучає складність розподілених транзакцій»
- Нет, не надо «Введення нових інженерів стає легшим — компонент є меншим і має одну, добре визначену відповідальність»
Негативні наслідки (критично включити):
«Це рішення збільшує складність інфраструктури — тепер нам потрібно працювати з кластером Redis крім PostgreSQL»
- Нет, не надо Команди будуть змушені вивчити нову структуру, яка сповільнить доставку протягом початкового тримісячного перехідного періоду
- Нет, не надо «Походження подій додає когнітивні витрати на шлях запиту — розробники повинні розуміти, що стан походить від подій, а не зберігається безпосередньо»
- Нет, не надо «Ми приймаємо ризик збільшення затримки на шляху читання як наслідок можливої послідовності в цьому домені»
- Нейтральні / зміни процесу: *
«Всі нові сервіси, написані в цьому домені, повинні реалізувати стандартну перевірку стану і кінцеві точки метрики, визначені в ADR-018»
- Нет, не надо «Рішення вимагає оновлення документації з впровадження команди і додавання нового розділу до керівництва з архітектури»
- Нет, не надо План міграції повинен бути створений і переглянутий перед початком впровадження
Повний приклад ADR
Ось короткий, але реалістичний приклад:
** ADR- 019: Використовувати Redis для розподіленого зберігання сеансів **
Статус: Прийнято — березень 2026
** Контекст: ** Програма зараз зберігає сеанси користувачів у базі даних PostgreSQL. З ростом бази користувачів, читання сеансів (що відбувається при кожному автентифікованому запиті) становить 40% всіх запитів до бази даних. Вичерпання резерву з’ єднання з базою даних під час пікового навантаження спричиняє періодичні помилки 503. Основною вимогою є високодоступний сеансовий магазин, який може обробляти 10 000 читання / секунду з суб-мілісекундною затримкою.
Рішення: Ми перенесемо зберігання сеансів з PostgreSQL на Redis (AWS ElastiCache, multi-AZ). Redis структурно добре підходить для шаблонів доступу ключ-значення (ID сеансу → дані сеансу), підтримує налаштовувані TTL, і виключає запиту сеансу з шляху читання PostgreSQL.
DynamoDB було оцінено як альтернатива. Це також задовольняє вимогам щодо затримки і пропускної здатності, але команда має існуючі знання Redis і ElastiCache зменшує операційні витрати в порівнянні з самокерованим кластером.
Наслідки:
Позитивно:
- Запити сеансів буде вилучено з PostgreSQL, звільнивши об’ єм з’ єднання для запитів програм.
- Затримка під мілісекунду для читання сеансу у масштабі.
- Нативна підтримка TTL спрощує логіку закінчення сеансу.
Негативна:
- Зараз ми експлуатуємо другий склад даних, збільшуючи складність інфраструктури і вартість AWS приблизно на $ 180 / місяць.
- Для скасування кешу під час відкликання сеансу (вихід з системи, зміна пароля) потрібний новий шлях скасування, якого не існує у поточній архітектурі.
- Дані Redis є ефемерними — команда повинна переконатися, що сеанси розроблені так, щоб їх можна було безпечно відновити при помилці кешу.
Процес:
- Процес розгортання програми тепер повинен включати ElastiCache у перевірки перед польотом.
- Інженери повинні прочитати документацію з керування сеансами перед зміною коду, пов’ язаного з сеансами.
Поширені мовні помилки в ADR
** 1. Використання пасивного голосу, щоб уникнути ясності**
Пасивний голос у АДР приховує, хто прийняв рішення, і може затемнити аргументацію:
❌ “Було вирішено, що буде використовуватися PostgreSQL.”
- Нет, не надо ✅ “Ми вирішили використовувати PostgreSQL. Основним фактором був існуючий оперативний досвід команди.»
** 2. Писать только о счастливом пути
Розділ з наслідками, у якому містяться лише позитивні точки, не є надійним:
❌ “Наслідки: Краща масштабованість, поліпшену продуктивність, спрощену архітектуру.”
- Нет, не надо ✅ “Наслідки: Покращена пропускна здатність читання (позитивна). Додаткова складність операцій з другого сховища даних (негативна). Перехідна робота оцінюється в два спринти (нейтральна).”
** 3. Запис рішення без контексту**
Майбутні читачі не зможуть оцінити рішення, не дізнавшись, які обмеження існували на той час:
❌ “Контекст: Команда потребувала базу даних.”
- Нет, не надо ✅ “Контекст: Система вимагає сильних гарантій ACID для фінансових операцій. Команда має п’ять років досвіду роботи з PostgreSQL. Вимога дотримання надає право на проживання даних в ЄС».
** 4. Неясні посилання на альтернативи**
❌ “Інші варіанти були розглянуті і відхилені.”
- Нет, не надо ✅ “MongoDB було оцінено і відхилено, тому що наша модель даних має багато реляційних з’єднань. Cassandra була відкинута через відсутність оперативного досвіду команди і складність її моделі послідовності. “
Ключовий словник для ADR
| Term | Common ADR usage |
|---|---|
| driver | The primary reason forcing a decision (“The key driver is compliance”) |
| constraint | A non-negotiable limit (“The constraint is a 6-month deadline”) |
| trade-off | A decision that gains X at the cost of Y |
| rationale | The reasoning behind a choice |
| supersede | To replace an older decision (“This ADR supersedes ADR-012”) |
| deprecated | Still in place but no longer recommended |
| tenable | Able to be maintained or defended (“Not tenable at scale”) |
| consequence | A result that follows from the decision |
| caveat | A warning or exception to the main decision |
| deferred | Postponed to a future decision (“The caching strategy is deferred to ADR-024”) |
ADR є одним з найцінніших документів, які може написати інженер. Хороший АДР потребує, можливо, одну годину, щоб написати, але знижує дні повторюваних обговорень протягом місяців і років. Інвестиції в просту англійську тут складаються протягом життя бази коду.