Як писати архітектурний запис рішень (ADR)
Вивчіть структуру ADR: контекст, рішення, наслідки. Включає повний шаблон прикладу, типові помилки, яких слід уникати, і фрази для написання чітких ADR англійською мовою.
Архітектурні рішення є одними з найбільш послідовних виборів, зроблених в програмному проекті. Проте вони часто погано документовані — або взагалі не документовані. Architecture Decision Records (ADRs) є легким, структурованим способом запису, чому був зроблений значний архітектурний вибір, які альтернативи були розглянуті, і які компроміси були прийняті. Цей посібник пояснює, як написати ефективні АПЗ зрозумілою технічною англійською.
Що таке АДР?
** Запис рішення щодо архітектури ** — це короткий документ, який містить важливе рішення щодо архітектури разом з його контекстом і наслідками. ADR були популяризовані Майклом Найгардом і широко прийняті в інженерних командах як частина практики «рішень-як-код» або «рішень-в-репо».
АДР відповідає на три питання.
- Яка була ситуація, коли було прийнято це рішення?
- Что мы решили?
- Які очікувані наслідки?
Стандартна структура ADR
Найпоширеніший формат ADR включає такі розділи:
Title
Коротка, описова заголовка у форматі, який орієнтований на прийняття рішень:
“ADR-007: Використовувати PostgreSQL як основну базу даних”
- “ADR-014: Прийняти джерело події для домену замовлення” *
Нумеруйте ваші ADR послідовно. Після написання, номер і назва не повинні змінюватися — навіть якщо рішення пізніше буде замінено.
Status
Один з: Пропонований, Прийнятий, Застарілий або Замінений на ADR-XXX.
“Статус: Прийнято (2026-03-15)“
Context
Опишете ситуацію, яка призвела до прийняття цього рішення. Які обмеження існували? Яку проблему ти вирішував? Кто был затронут?
- “Наша монолітна програма досягла точки, де декілька команд розгортають її на одній базі коду. Конфлікти розгортання і довгі черги перегляду сповільнюють доставку. Нам потрібно вирішити, чи розкладати програму на окремі розгорнуті одиниці.”*
Цей розділ повинен бути фактичним і конкретним, а не висловлювати думку. Зберегти вашу думку для розділу Рішення.
Decision
Ясно скажи, що було вирішено. Використовуйте активний голос і пряму мову.
- “Ми приймемо архітектуру служби- за- доменом, починаючи з доменів Замовлення і Користувач. Кожен домен буде мати власне сховище, базу даних і конвеєр розгортання. “*
Consequences
Список очікуваних результатів — як позитивних, так і негативних. Хороші ADR не приховують компромісів.
“Позитивні наслідки:
- Команди можуть розгортати незалежно, вилучаючи залежності між розгортаннями команд.*
- межі домену будуть явними, зменшуючи випадкове з’ єднання.*
- Нет, не надо Негативні наслідки:
- Запити між доменами потребують викликів API або синхронізації даних на основі подій, що додає складності.* - Нам потрібно буде інвестувати в пошук сервісів, розподілене відстеження і міжсервісну автентифікацію.”
Повний шаблон ADR
# ADR-[number]: [Short title of the decision]
**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXX
**Deciders:** [List of people involved in the decision]
## Context
[Describe the situation, constraints, and the problem that prompted this decision.]
## Decision
[State clearly what was decided and why.]
## Consequences
### Positive
- [Expected benefit]
- [Expected benefit]
### Negative
- [Known trade-off]
- [Known trade-off]
## Alternatives Considered
[Briefly describe alternatives and why they were not chosen.]Необхідно уникати помилок
Визначення проблеми як рішення
Неправильно:
- “Ми повинні вирішити, як обробляти автентифікацію.” *
Праворуч:
“Ми використовуємо JSON Web Tokens (JWTs) для автентифікації без стану у всіх службах.”
Розділ рішення повинен вказати, що було вирішено, а не переказувати проблему.
Сховати компроміси
Опускання негативних наслідків робить ADR безглуздою. Майбутні інженери повинні розуміти, які компроміси були свідомо прийняті.
“Негативна: JWT не можна скасувати до закінчення терміну їх дії без списку блокування, що ускладнює роботу при виході з системи і призупиненні облікового запису.”
Після цього сліди від нього не виявлені
Якщо ви пишете АСД для рішення, яке вже було впроваджено, зауважте, що:
“Примітка: Це рішення було прийнято і впроваджено в березні 2025 року. Цей ADR був написаний ретроспективно, щоб задокументувати аргументацію.”
Використовує рідну мову
Уникайте фраз типу “ми повинні розглянути” або “це може бути добре”. АДР документують рішення, а не можливості.
Практичні фрази для написання ADR
- “На момент прийняття цього рішення, основним обмеженням було…”
-
- “Розглядалися три альтернативи: X, Y і Z. Ми обрали X, тому що…”*
- “Це рішення вводить компроміс між простотою і масштабованістю.”
- “Майбутні команди повинні знати, що це рішення передбачає…”
- “Якщо зміняться наступні припущення, цей ДОЗ повинен бути переглянутий:…”
- “Це рішення замінює ADR-003, який рекомендував…”
Де зберігати ADRs
Найбільш поширеною угодою є зберігання ADR в каталогу docs/decisions/ в репозиторії, названому NNNN-title-with-hyphens.md. Це зберігає рішення версії разом з кодом, який вони описують.
Інструменти, такі як adr- tools автоматизують створення і посилання файлів ADR.
ADRs є формою інституційної пам’яті. Без них команди неодноразово переглядають ті ж самі рішення, а інженери, які приєднуються до проекту, не можуть зрозуміти, чому все так, як є. Хорошо написанный ADR занимает 30 минут для производства и экономит часы запутанной археологии в будущем. Зроби з них звичку.
Наприклад, англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська
Написання запису про рішення архітектури (ADR) - це більше, ніж просто заява * що * ви вирішили; це про повідомлення * чому * - обґрунтування вашого вибору. Для не-рідних англомовних носіїв, це може бути особливо складним завдяки тонким відмінностям у фразування і наголосу, що впливають на розуміння і купівлю. Давайте сконцентрируемся на покращенні вашої мови, щоб ваші АДР були не тільки технічно коректними, але й чітко зрозумілими для всієї вашої команди.
Одна з часто зустрічається областей плутанини виникає з вираженням потенційних недоліків або ризиків. Замість тупого висловлювання на кшталт «Це вводить ризик», яке може звучати обвинувальним, націлюйтеся на фрази, які конструктивно визнають невизначеність. Розгляньте можливість використання « Ми визнаємо можливість [особливої проблеми] і будемо активно стежити за [метрикою], щоб зменшити її ». Або, коли обговорюватимемо компроміси, уникайте простого сказання « Варіант А краще ». Замість цього, сформулюйте його так: « Хоча варіант Б пропонує [вигоду], варіант А забезпечує міцнішу основу для [критичної вимоги] з урахуванням наших поточних обмежень. Ми продовжимо оцінювати довгострокові наслідки цього рішення.” Поширене повідомлення Slack, яке ви можете отримати під час перегляду коду щодо ADR, може бути таким: “Гей, команда, просто переглядаю цей ADR - дякую за ретельність! Можемо ми, можливо, трохи розібратися, як ми вирішуємо потенційні проблеми масштабованості з цим підходом? Було б корисно побачити конкретний план для моніторингу продуктивності, оскільки наша база користувачів зростає. ” Зауважте ввічливий і допитливий тон; зосереджений на * розумінні *, а не на прямому критикуванні.
Крім того, точність у словнику є ключем. Уникайте жаргону, який не є загально зрозумілим у вашій команді. Якщо ви змушені використовувати технічні терміни, коротко визначте їх в контексті ДОПОГ. Аналогічно, при документуванні наслідків — як позитивних, так і негативних — будьте конкретними. Замість «Це поліпшить продуктивність», скажіть: «Ми очікуємо 15% зменшення затримки для [спеціфічної операції] на основі початкового тестування». Хороший PR- опис для ADR може бути таким: «Це ADR описує наше рішення прийняти архітектуру мікросервісів, що обумовлено потребою незалежного масштабування і зменшення ризику розгортання. Документовані наслідки включають збільшення операційної складності, що вимагає спеціальних інструментів моніторингу, а також прогнозоване 20% поліпшення чутливості застосунків
Нарешті, пам’ятайте, що ADR - це живі документи. Заохочуйте постійні обговорення та ітерації. Не бійтеся переглядати свої рішення, коли з’являється нова інформація. Після схвалення ADR, наступним повідомленням може бути: « Дуже добре зроблено, щоб завершити цей ADR! Давайте заплануємо коротку синхронізацію наступного тижня, щоб обговорити стратегію моніторингу, яку ми описали - будь-які початкові думки або занепокоєння? “Сфокусування на спільній мові і демонстрація відкритості до відгуку значно підвищить ефективність ваших АДР і сприяє зміцненню командного спілкування.