Архітектура
Architecture Decision Record (ADR — запис архітектурного рішення): як зберігати причини вибору
У попередніх главах ми описали вимоги, архітектуру системи та її межі за моделлю C4 (Context, Containers, Components, Code — контекст, контейнери,…
У попередніх главах ми описали вимоги, архітектуру системи та її межі за моделлю C4 (Context, Containers, Components, Code — контекст, контейнери, компоненти й код). Документи можуть показати, що система має вебзастосунок і реляційну базу, а код — як саме працює запис бронювання. Однак ні код, ні поточна схема самі по собі не пояснюють, чому команда обрала саме цю базу, які обмеження тоді мала і від яких альтернатив відмовилася. Запис архітектурного рішення зберігає цю причину разом із наслідками.
ADR (Architecture Decision Record — запис архітектурного рішення) — короткий документ про одне значуще рішення, аргументи на його користь і компроміси. ADR — це історичний слід конкретного вибору, а не гарантія, що цей вибір досі правильний. Набір записів утворює журнал рішень про архітектуру. У цій главі ми розглянемо, коли такий запис вартий витрат, як порівнювати справжні варіанти, що писати про статус і наслідки, як зберігати історію змін і як допомагати агентам знаходити та поважати рішення команди.
Після глави читач уміє:
- розрізняти рішення, його запис, обговорення та реалізацію;
- обрати між ADR, коментарем до запиту на злиття змін, короткою нотаткою та відсутністю окремого документа;
- описати контекст, обмеження, факти й припущення так, щоб майбутній читач міг перевірити їхню чинність;
- порівняти альтернативи без заздалегідь програного варіанта;
- фіксувати переваги, втрати, операційну роботу, ризики й умови перегляду;
- зберігати застаріле рішення як історію та пов’язувати його з новим;
- використовувати ADR під час роботи з кодом і агентом, не підмінюючи схвалення автора автоматичною відповіддю моделі.
Що саме фіксує ADR
Архітектурне рішення — це обґрунтований вибір, який відчутно впливає на вимоги або структуру системи. Рішення може визначати межу відповідальності, сховище, зовнішню залежність, протокол, модель доступу, спосіб відновлення чи важливий компроміс між якістю та вартістю. Значущість залежить від контексту: заміна бібліотеки може бути дрібною для одного продукту і ризикованою для іншого, якщо від неї залежить сумісність із партнерами.
Сам ADR не є рішенням і не ухвалює його. Це документ, що дає змогу відновити ланцюг міркувань. Саме тому в ньому розділяють щонайменше три речі:
- Обставини: яку проблему треба розв’язати, які цілі та обмеження маємо і що поки невідомо.
- Вибір: яку дію або напрям команда вирішила взяти.
- Наслідки: які можливості, витрати, ризики й обов’язки з’явилися після вибору.
Це розділення допомагає не сплутати «ми хочемо уникнути подвійного бронювання» з «запроваджуємо транзакційне обмеження у спільній базі» і з результатом «усі операції, що змінюють слот, тепер мусять проходити через цю базу». Перше — потреба, друге — рішення, третє — наслідок із конкретним зобов’язанням.
Публічний опис ADR у спільноті adr.github.io визначає ADR як запис одного архітектурного рішення разом з обґрунтуванням і компромісами; сукупність записів утворює журнал рішень визначення ADR. Майкл Ніґард у первісній статті 2011 року пояснював потребу зберігати мотиви рішень: новий учасник інакше має або сліпо прийняти старий вибір, або так само сліпо його змінити. Він радив короткі модульні записи, які легше прочитати й підтримувати, ніж одну громіздку архітектурну книгу Documenting Architecture Decisions.
ADR не замінює специфікацію вимог, повний документ архітектури системи (SAD, Software Architecture Document), контракт програмного інтерфейсу (API, Application Programming Interface), посібник експлуатації чи обговорення в запиті на злиття. Він посилається на них і пояснює, як із контексту випливає вибір, але не копіює весь зміст. Кроки міграції та відновлення описують у виконуваній операційній процедурі; ADR зберігає причину вибору й посилання на неї.
Коли варто писати ADR
Запис має цінність, коли майбутній читач не зможе надійно вивести мотив із коду або короткої історії змін. Найчастіше це означає, що рішення:
- впливає на кілька функцій, команд або релізів;
- задає важку для зміни межу між системами, сервісами, сховищами чи власниками даних;
- вводить тривалу зовнішню залежність або обмежує доступні постачальники;
- має суттєві наслідки для безпеки, конфіденційності, доступності, вартості чи відновлення;
- вибирає один компроміс серед кількох прийнятних альтернатив;
- свідомо відкладає масштабну перебудову чи автоматизацію, бо теперішній варіант достатній;
- може бути переглянуте, якщо зміняться конкретні умови.
Наприклад, рішення зберігати підтверджені бронювання в транзакційній реляційній базі заслуговує окремого запису, якщо команда порівняла його з документним сховищем, погодилася підтримувати міграції й визначила межу цілісності. Воно стосуватиметься подальшої моделі даних, резервного копіювання, конкурентних змін і роботи команди.
Окремий ADR зазвичай не потрібен для виправлення друкарської помилки, перейменування локальної функції або косметичної зміни розмітки. Якщо рішення однозначно видно з невеликого запиту на злиття і не створює довготривалого зобов’язання, достатньо опису зміни й причини без нового файлу. Якщо питання лишається відкритим, його можна вести як пропозицію або обговорити у задачі. Не кожна цікава технічна думка стає архітектурним рішенням.
Межа не визначається лише кількістю рядків коду чи словом «архітектура» в заголовку. Практична перевірка — уявіть, що за пів року хтось хоче поміняти вибір. Які факти, ризики, межі й домовленості ця людина не зможе відновити з реалізації? Якщо відповідь суттєва, запишіть мотив і наслідки. Якщо питання можна вирішити з читабельного опису задачі, не створюйте дубль.
З чого складається один запис
Універсального шаблону немає. Ніґард пропонував короткий запис із назвою, контекстом, рішенням, статусом і наслідками. MADR (Markdown Architectural Decision Records — записи архітектурних рішень у форматі Markdown) — розширений шаблон із проблемою, критеріями вибору, альтернативами, наслідками, підтвердженням і посиланнями. Це корисні варіанти, не обов’язкові стандарти опис MADR і шаблон.
Команда може почати з такого мінімального запису:
# ADR-0007. Зберігати підтверджені бронювання в реляційній базі
Дата: 2026-04-12
Статус: запропоновано
Власники погодження: власник бронювань і команда платформи
## Контекст
Яку проблему розв'язуємо; які факти, обмеження та припущення впливають на вибір?
## Рішення
Що пропонуємо робити? Назвіть конкретну дію й її межу; після погодження це формулювання має точно відображати вибір.
## Розглянуті варіанти
Що реально можна було обрати, зокрема варіант нічого не змінювати?
## Наслідки
Що стає простішим, складнішим, дорожчим або ризикованішим?
## Перегляд
Яка зміна умов має змусити повернутися до рішення?
## Пов'язані матеріали
Вимога, SAD, задача, запит на злиття, інструкція відновлення чи новий ADR.
Це заготовка для пояснення, не команда створити ADR за кожною зміною. Дату записують, щоб розуміти, коли оцінювали обставини; вона не замінює історію версій. Якщо запис змінюється, система контролю версій зберігає, хто і коли вніс зміну. Коротка назва має передавати вибір, а не лише тему: «Реляційна база для підтверджених бронювань» інформативніша за «База даних».
Якщо команда окремо залишає поле «Перегляд», воно теж має бути перевірюваним: «переглянути через рік» слабко, а «повторно оцінити, якщо за вимірюваннями пікова кількість одночасних підтверджень перевищить спроможність одного вузла» пов’язує перевірку з причиною вибору. Сам тригер запускає оцінку, але не змінює ADR автоматично.
Пари фрагментів показують, яку роботу виконує кожне поле мінімального запису. Це короткі навчальні формулювання, а не готовий ADR для реального продукту:
- Назва. Погано: «База даних». Добре: «Зберігати підтверджені бронювання у спільній реляційній базі» — уже з назви видно напрям вибору.
- Статус. Погано: «Прийнято», коли відповідальний власник ще не погодив текст. Добре: «Запропоновано; чекає рішення власника бронювань» — читач розуміє, що напрям поки не авторитетний.
- Контекст. Погано: «Користувачів невдовзі стане дуже багато». Добре: «За звітом від 12 квітня було 1 200 підтверджених бронювань на місяць; пікову кількість одночасних записів ще не виміряли, тому значення 300 у прикладі є припущенням» — факт має джерело, а невідоме не маскується під прогноз.
- Рішення. Погано: «Потрібна надійна й масштабована система». Добре: «Усі підтвердження останнього вільного місця виконуємо однією транзакційною операцією у спільній реляційній базі» — дію та її межу можна перевірити.
- Розглянуті варіанти. Погано: «Інша база повільна, окремий сервіс занадто складний». Добре: «Порівняли запис в одній реляційній базі, розподілене блокування та відкладення зміни за тими самими критеріями: захист останнього місця, операційна робота й відновлення; вимірювань навантаження ще немає» — альтернативи правдоподібні, а межа доказів видима.
- Наслідки. Погано: «Рішення швидке й надійне». Добре: «Спільна транзакція захищає облік місць від двох одночасних підтверджень; натомість кожен запис проходить через одне сховище, а команда має контролювати резервування й відновлення» — показані і вигода, і нові витрати.
Контекст: факти, припущення та обмеження
Контекст відповідає на запитання «що було відомо тоді?». Він має дозволити читачеві уявити ту саму задачу без здогадів про приховану передісторію. Записуйте лише чинники, які вплинули на вибір:
- мету або вимогу, яку треба виконати;
- перевірені факти й джерело кожного важливого факту;
- припущення, яких не вдалося перевірити вчасно;
- обмеження команди, продукту, середовища, ліцензії, бюджету чи строку;
- профіль навантаження і що з нього відомо або невідомо;
- дату оцінки та людей, які мають повноваження ухвалити це рішення.
Не записуйте прогноз як факт. «За звітом власника продукту маємо 1 200 підтверджених бронювань за місяць» — перевірне твердження з джерелом; «300 одночасних змін у піковий час» — навчальне припущення, а не вимір. «Невдовзі буде мільйон активних користувачів» теж лишається прогнозом, якщо немає обґрунтованого розрахунку. Коли з’являться телеметрія чи нові дані, порівняйте їх із припущенням і позначте, що варто переоцінити.
Обмеження також можуть бути соціальними та операційними. Якщо чергова команда не має компетенції підтримувати кластер із трьох баз, це не «слабкий технічний аргумент», який треба приховати. Це частина реальної вартості: кому доведеться вивчати, спостерігати й відновлювати систему під час відмови? Ніґард радив описувати технологічні, проєктні та людські сили нейтральною мовою; оцінка має з’явитися у виборі та наслідках, а не у викривленому описі фактів.
Варіанти: чесне порівняння
Перелік альтернатив потрібен не для декорації перед уже ухваленим вибором. Він показує, що команда розглядала доступні шляхи та розуміла ціну кожного. Варіант «залишити як є» або «почекати, доки з’являться дані» часто реальний. Якщо ж він порушує обов’язкову вимогу, прямо поясніть яку саме.
Для кожного варіанта використовуйте спільні критерії: чи виконує вимогу; скільки змін потребує; що треба підтримувати; які властивості дає або послаблює; що невідомо. Не порівнюйте обраний варіант за найкращими рисами, а альтернативу — за найгіршими. Не називайте постачальника або підхід «несерйозним», коли справжня причина полягає в тому, що команда не має часу чи компетенції його експлуатувати. Це операційне обмеження, яке треба записати відкрито.
У невеликих рішеннях достатньо двох-трьох змістовних абзаців. Якщо критерії суперечать один одному, таблиця або короткий перелік допоможуть читачеві побачити компроміс. Не додавайте штучної математичної точності. Оцінки «1–5» не стають об’єктивними лише через числа. Якщо команді потрібне ранжування, поясніть значення шкали та звідки взялися ваги.
Рішення і статус: що є погодженим
Розділ «Рішення» має містити одне речення з перевірюваною дією та її межею: «Ми обираємо реляційну базу для підтверджених бронювань; усі команди, що змінюють останнє вільне місце, використовують одну транзакційну операцію бронювання». Його можна звірити з реалізацією; фраза «система має бути масштабованою» не називає вибір.
Статус відповідає на інше запитання: чи уповноважені люди погодили напрям і чи він досі чинний. Команди можуть домовитися про значення «запропоновано», «прийнято», «відхилено», «застаріло» та «замінено», але це місцева конвенція, а не універсальний стандарт. MADR і Ніґард наводять варіанти статусів, не обов’язковий набір шаблон MADR, Ніґард про статус ADR.
Запишіть, хто і за яким процесом може змінити статус. Якщо погоджує власник продукту, його відповідь у затвердженому процесі встановлює «прийнято»; текст агента, схвалення автора зміни чи сам факт наявності файла цього не роблять, якщо правила команди не визначають інакше. Навчальний статус «запропоновано» не приписує команді вигаданої згоди. Прийняте рішення також не означає, що його вже реалізували чи розгорнули: виконання відстежуйте окремою задачею, запитом на злиття або релізом.
Наслідки і тригери перегляду
Записуйте наслідки, а не рекламуйте вибір. Зазначте:
- що стане простішим і яку ціль це підтримує;
- що буде дорожчим або складнішим;
- яка робота потрібна для розробки, експлуатації, резервування й відновлення;
- які ризики виникають і хто їх спостерігає;
- які залежності чи дані зроблять майбутню зміну дорогою;
- які питання ще треба дослідити, хто і до якої події за них відповідає.
Кожен істотний компроміс має бути видимий. Реляційна база дає чіткі правила цілісності, але команда має оновлювати схему й планувати сумісні зміни. Окремий сервіс може ізолювати відповідальність, але додає мережевий виклик, розгортання, спостереження та чергову процедуру. Відкладення зміни економить час зараз, але має дату або умову повторної оцінки. Сторінка автора описує Software Architecture: The Hard Parts як книжку про архітектурні компроміси та їх документування; тут вона підтверджує лише тематику книжки, а не конкретне правило цього розділу (Neal Ford про книжку).
«Переглянути через рік» слабше за умову, пов’язану з причиною рішення. Краще: «повернутися до вибору, якщо пік перевищить підтверджений бюджет одного вузла або команді знадобиться незалежно змінювати модель бронювання». Тригер не має автоматично скасовувати рішення; він запускає перевірку фактів. Старий запис лишається історією, поки люди з повноваженнями не вирішать його замінити.
Повний приклад: зберігати бронювання реляційно
Нижче наведено вигаданий навчальний ADR. Усі назви, вимоги та числа в ньому створені для прикладу. Це не опис реального продукту й не твердження про виміряне навантаження.
# ADR-0007. Зберігати підтверджені бронювання в реляційній базі
Дата оцінки: 2026-04-12
Статус: запропоновано
Власники погодження: команда бронювань і власник продукту
## Контекст
Навчальний сервіс бронювання зберігає часові слоти й підтвердження клієнта. Два запити не можуть отримати останнє місце одночасно.
Приклад припускає один регіон і один канонічний запис на бронювання; це треба перевірити до запуску реального продукту. Власник також хоче історію змін, але вибір сховища поточного стану її не забезпечує. Завдання `DATA-HISTORY-01` має визначити події, доступ і строк зберігання; поки це відкрите питання. Вимоги до аналітики поза застосунком ще не задані.
Запис і його статус мають залишатися зрозумілими для команди, що чергує. Немає вимірів, які виправдали б розподілене сховище або ручне шардоване розділення даних.
## Розглянуті варіанти
1. Реляційна база з транзакцією та обмеженням цілісності.
2. Документне сховище як основне місце запису.
3. Зберегти теперішню таблицю у файлі й синхронізувати зміни пізніше.
## Рішення
Запропонувати реляційну базу як канонічне сховище підтверджених бронювань. Операція має перевіряти доступність і займати місце в одній транзакційній межі; конкретний механізм перевірити для обраної бази й коду.
Цей вибір не вирішує зберігання історії. ADR лишається запропонованим, доки не визначено `DATA-HISTORY-01` або власник продукту явно не погодив відтермінування вимоги.
## Чому цей варіант відповідає контексту
Реляційна модель дає змогу виразити унікальність і зв’язок бронювання зі слотом поруч із даними. Транзакційна операція створює межу, де команда може вимагати, щоб дві конкуруючі спроби не підтвердили один і той самий останній слот. Це аргумент про відповідність конкретній вимозі, а не твердження, що всі реляційні системи однаково конфігуровані або будь-який код автоматично захищений від гонки.
Документна база теж може підтримувати транзакції й обмеження; варіант не відкидають лише через назву технології. У навчальному контексті команда вже має досвід із реляційним сховищем, а в документному варіанті треба окремо перевірити доступну в конкретного постачальника межу конкурентного запису та потрібні запити. Файл із відкладеною синхронізацією потребував би додаткового механізму координації, бо сам по собі не захищає одночасні підтвердження між кількома процесами. Докладніше про ці моделі та конкурентний запис ідеться в главі 16.
## Наслідки
Позитивний наслідок: бронювання й правило останнього місця мають спільну транзакційну межу. Негативний: команда підтримує схему, а компоненти запису залежать від одного контракту.
Перед запуском команда має визначити резервування, ціль часу відновлення й спосіб перевірити відновлену копію. Вона також тестує конкурентний сценарій для конкретної бази та коду: якщо читання доступності й фіксація бронювання відбуваються в різних транзакціях, заявлений захист не працюватиме. Сам ADR гарантії не створює й не замінює операційну процедуру відновлення.
Історія змін не виникає автоматично від вибору бази. Завдання `DATA-HISTORY-01` має визначити події, доступ і строк зберігання; відтермінування окремо погоджує власник продукту.
## Умова перегляду і зв’язки
Переглянути ADR, якщо географія запису має стати активною в кількох регіонах, з’являться нові вимоги до незалежного розподілу даних або вимірювання покажуть, що наявне сховище не вкладається в підтверджені цілі. Перевищення числа з вигаданого навчального припущення саме по собі не є production-сигналом.
Пов’язати цей запис із вимогою про недопущення подвійного бронювання, SAD сервісу бронювання, задачею реалізації транзакційної операції, окремим завданням `DATA-HISTORY-01`, запитом на злиття змін і процедурою перевірки резервної копії.
Повний приклад: поки не виділяти сервіс сповіщень
Архітектурним рішенням буває й свідоме збереження поточної структури. Відсутність нової межі не означає, що команда забула про проблему. Нижче наведено вигаданий навчальний ADR; дати, назви й навантаження не описують реальний продукт.
# ADR-0009. Поки залишити сповіщення модулем застосунку бронювання
Дата оцінки: 2026-04-12
Статус: запропоновано
Власники погодження: команда бронювань і власник експлуатації
## Контекст
Навчальний застосунок надсилає клієнту підтвердження після створення бронювання. У цьому прикладі поточний обсяг складає одне повідомлення електронною поштою після успішної операції. Команда хоче уникати втрати підтвердження, але не має окремої команди для експлуатації сповіщень. Ми ще не вимірювали обсяг повторних спроб, затримку постачальника та роботу, потрібну для незалежного масштабування. Усі числа й ситуація створені для навчання.
## Розглянуті варіанти
1. Залишити відправлення модулем у застосунку бронювання та надійно зберігати невідправлені події для повторної обробки.
2. Виділити окремий сервіс сповіщень уже зараз.
3. Не надсилати автоматичне повідомлення, а покластися на сторінку підтвердження.
## Рішення
Запропонувати залишити формування та облік сповіщення в тому самому застосунку, який записує бронювання. Після підтвердження зберігати завдання на відправлення так, щоб збій поштового постачальника не скасовував саме бронювання. Не запроваджувати окреме розгортання до виконання умов перегляду цього запису.
## Порівняння
Поточний модуль відповідає одному каналу й одній команді; він не створює нової мережевої межі та чергової процедури. Його слабке місце — зміни застосунку можуть зачіпати код відправлення, а масштабування модуля відокремлено від решти застосунку ще не доступне.
Окремий сервіс міг би мати незалежний темп змін і масштабування, але зараз не було підтверджено ані окремої команди, ані такого навантаження. Варіант додає розгортання, мережевий контракт, спостереження, управління повторними спробами та аварійне відновлення. Команда відкладе цю вартість, доки не побачить причину її нести; це не твердження, що окремий сервіс ніколи не знадобиться.
Відмова від повідомлення справді ще простіша технічно, але не виконує погоджену вимогу давати клієнту підтвердження через електронну пошту. Її не обираємо не через технологічну слабкість, а через невідповідність потребі продукту.
## Наслідки
Позитивний наслідок: бронювання та постановка завдання сповіщення залишаються поруч, тому команда має один шлях зміни й одну процедуру розгортання.
Негативний наслідок: застосунок відповідає і за бронювання, і за повторну відправку повідомлення. Несправність постачальника може створити відкладені завдання, які доведеться спостерігати та очищувати.
До запуску команда задає граничний розмір і вік черги, безпечні повтори, сигнал тривоги та відповідального за ручне втручання. Вона також перевіряє, що завдання сповіщення зберігається разом із бронюванням; сам ADR цього не доводить.
## Умова перегляду і зв’язки
Повернутися до рішення, якщо підтверджені виміри покажуть, що відправлення конкурує за ресурси із записом бронювання; продукт додасть кілька незалежних каналів із власними вимогами до доступності; або з’явиться окрема відповідальна команда, яка може експлуатувати сервіс цілодобово. Власник експлуатації має переглянути метрики черги й аварійні випадки на плановому архітектурному огляді.
Пов’язати цей запис із вимогою підтвердження; кроки повторної обробки описати в операційній інструкції.
Як рішення змінюється, не стираючи історію
Через рік можуть змінитися факти, вимоги або склад команди. Це не робить попереднє рішення безглуздим заднім числом. Воно було відповіддю на тодішній контекст. Команда має зберегти його і записати нову причину, яка змінила напрям.
Продовжмо виключно навчальний приклад сповіщень. Через рік умовна команда підтвердила три обставини: сповіщення для електронної пошти й текстових повідомлень мають розвиватися незалежно; вимірювання вказують на затримки відправлення, що заважають обмеженням продукту; з’явилася команда з черговою зміною, яка відповідатиме за окремий компонент. Саме нові перевірені відомості, а не календар сам по собі, створюють підставу переглянути ADR-0009.
У цьому сценарії команда пише новий запис, наприклад ADR-0012:
# ADR-0012. Виділити доставку сповіщень в окремий сервіс
Дата оцінки: 2027-04-18
Статус: запропоновано
Замінює: ADR-0009, якщо цей запис буде прийнято
Власники погодження: команда сповіщень, команда бронювань і власник продукту
## Контекст
З часу ADR-0009 продукт додав незалежні канали електронної пошти й текстових повідомлень. У цьому навчальному сценарії команда протягом шести тижнів зафіксувала затримки відправлення, які заважають погодженому часу підтвердження. З'явилася окрема команда з визначеною черговою зміною. Ці факти й вимірювання створені для прикладу; перед справжнім рішенням треба додати посилання на перевірені звіти.
## Розглянуті варіанти
1. Зберегти модуль в основному застосунку та оптимізувати спільні ресурси.
2. Виділити окремий сервіс доставки з чітким контрактом і власником.
3. Передати відправлення повністю керованому постачальнику без власної черги.
## Рішення
Запропонувати окрему межу сервісу для доставки сповіщень, залишивши запис бронювання у сервісі бронювань. Сервіс бронювань публікує завдання після успішної операції; сервіс доставки відповідає за спробу доставки, відстеження результату й погоджену політику повторів. Точний контракт, захист від повторного ефекту та режим відмови погодити до реалізації. Цей ADR не змінює статус, поки відповідальні люди не ухвалили пропозицію.
## Чому переглядаємо ADR-0009
Тодішнє рішення зберігало простішу операційну модель, коли був один канал і не було окремого власника. Тепер вимоги до каналів та підтверджені дані про затримку змінили обставини. Новий вибір додає розподілену межу й операційні витрати, але дає виділеній команді можливість самостійно змінювати й спостерігати доставку. Команда переглянула старі аргументи, а не переписала їх так, ніби сервіс був очевидно необхідний весь час.
## Наслідки, зобов'язання і зв'язки
Позитивні наслідки: окремі канали й телеметрія; менше впливу затримок доставки на запис бронювання. Витрати: мережевий контракт, більше розгортуваних частин, нова чергова процедура й моніторинг узгодженості між замовленими та доставленими повідомленнями.
До запуску власники визначають повтори, межу черги, сигнали та відновлення. Окрема команда сама по собі не гарантує ізоляції чи надійності.
Якщо ADR-0012 буде прийнято, позначити ADR-0009 як замінений, не стираючи його історію. Послатися між записами в обидва боки та оновити актуальні вимогу й SAD.
Життєвий цикл і збереження запису
Статуси мають коротко пояснювати, що сталося з пропозицією. Команда може використати таку домовленість:
- Запропоновано — текст ще обговорюють; він не дозволяє трактувати вибір як погоджений.
- Прийнято — названі власники рішення погодили напрям згідно з процесом команди.
- Відхилено — пропозицію розглянули й не обрали; причина відмови залишається доступною.
- Застаріло — змінилися умови або власники вирішили більше не покладатися на запис; треба пояснити, чи є чинний замінник.
- Замінено — інший ADR описує нове рішення; назвати його номер і послатися назад.
Це приклад словника статусів, а не обов’язкова зовнішня класифікація MADR, Ніґард про статус ADR. У невеликому проєкті досить трьох значень; у регульованому можуть знадобитися окремі статуси для погодження, набрання чинності й завершення реалізації. Поясніть місцеві терміни та не змінюйте статус лише тому, що код з’явився або файл давно не редагували.
Рішення можуть мати окремі стадії: пропозиція обговорюється; відповідальна людина погодила її; реалізацію розпочато; зміни введено в експлуатацію; пізніше новий контекст змусив перегляд. Статус ADR описує саме рішення за правилами команди. Задача відстежує роботу, а реліз або система розгортання — фактичне введення змін. Один ярлик не має удаватися за всі ці факти.
Не переписуйте прийнятий ADR так, ніби команда завжди мала нове знання. Якщо виправляється описка чи додається посилання, історія версій покаже уточнення. Якщо змінили сам вибір, створіть новий запис: коротко вкажіть, що замінюється; запишіть новий контекст, альтернативи та наслідки; після погодження позначте попередній запис заміненим. Не видаляйте старий і не присвоюйте його номер іншому рішенню. Така історія допомагає зрозуміти різницю між помилкою реалізації й свідомою зміною напряму.
Ніґард радив зберігати попередній ADR і позначати його заміненим, а не викидати. Реальні журнали демонструють і часткову заміну: у зафіксованому журналі Model Context Protocol (MCP — протокол контексту моделі) запис від 16 квітня 2026 року позначає правила URI (Uniform Resource Identifier — уніфікованого ідентифікатора ресурсу) як «замінені частково», бо змінилися окремі правила, а структура лишилася. Запис від 16 липня звужує першу версію розширення й прямо перелічує замінені та збережені правила рішення про схему URI, рішення про першу версію. Це зберігає історію й точний обсяг зміни.
Зв’язок із вимогами, SAD, задачами й експлуатацією
ADR — це вузол між причиною, описом системи та роботою, яка втілює вибір. Короткий ланцюжок може виглядати так:
Вимога 021: не підтверджувати два бронювання на одне останнє місце
→ ADR-0007: використовувати транзакційний запис у спільному сховищі
→ SAD, розділ 4.2: відповідальність контейнера бронювань і межі запису
→ Задача реалізації: безпечна зміна схеми та відновлення
→ Запит на злиття: реалізація й перевірені сценарії конкуренції
→ Посібник оператора: перевірка резервної копії та відновлення
Назви та номери тут вигадані. Вони показують напрям посилань, а не реальні задачі курсу чи проєкту. ADR не копіює пов’язані документи: достатньо назвати їхню роль і дати пряме посилання.
Перевіряйте посилання за їх призначенням. Вимога пояснює, що має бути істинним для користувача або продукту. Архітектурний документ показує межу, структуру й залежності. Задача має власника та роботу. Запит на злиття пояснює конкретний комплект змін. Посібник експлуатації веде оператора під час звичайної роботи чи відмови. Якщо рішення змінюється, оновіть документи, що описують актуальний стан, але залиште історичний ADR із посиланням на заміну.
Умовні скорочення нижче: REQ (Requirement — вимога) позначає запис очікуваної поведінки; SAD (Software Architecture Document — документ архітектури системи) — архітектурний опис; A1M — навчальний ключ задачі Jira; PR (pull request — запит на злиття змін) — комплект змін на розгляд; RUN (Runbook — інструкція для експлуатації) позначає процедуру для оператора.
У великому журналі пошук має враховувати назви, область, власника, статус, дату й пов’язані вимоги. Статичний індекс або перелік за компонентами зручніший за один файл на десятки рішень. Коли команда вибирає нумерацію, імена чи папки, нехай формат допомагає зберігати посилання й історію. Наприклад, MADR підтримує послідовні номери у назвах файлів, але прямо вказує, що структура папок не обов’язково мусить бути його конкретною схемою. Не змішуйте особливості одного інструмента з визначенням ADR.
Що показують відкриті приклади
У версії журналу рішень репозиторію ext-skills, закріпленій за комітом 81f55b67, є записи різної довжини. Короткий прийнятий запис від 14 лютого 2026 року обирає зберігати документацію як файли Markdown у репозиторії, а не публікувати її як окремий сайт. Він фіксує контекст, один вибір, кілька причин — низький бар’єр внеску, відсутність додаткової інфраструктури — і умову повернутися до теми, якщо група виросте або навігація стане складною. Він стислий, бо сфера рішення та компромісу вузька окремий запис про формат документації.
Рішення від 16 березня 2026 року в тому ж журналі значно докладніше. Воно аналізує пропозицію, внесену через запит на злиття змін #60 (PR, pull request — запит на злиття змін), відгуки на неї, ризик дублювання інформації, ранню оптимізацію, альтернативне місце для семантичних даних, межі майбутнього простору назв і джерела для перевірки. Його обсяг виправданий кількома взаємопов’язаними межами й наслідками для розширення протоколу. Обидва записи позначені «прийнято», але жодна довжина не є рецептом для всіх команд окремий запис про метадані, обговорення PR #60.
Ці приклади не доводять, що обрані підходи є найкращими для інших продуктів. Вони демонструють, як автори пов’язали рішення з наявними обмеженнями та можливим переглядом. Адреса з номером коміту фіксує саме той текст журналу, який ми аналізуємо; посилання на поточну гілку могло б показувати іншу версію.
MADR також зберігає власне рішення «додати поле статусу». У ньому команда порівнює способи позначення статусу — метадані, значок, рядок тексту, заголовок, таблицю — і для кожного описує переваги й недоліки. Сам приклад не має явного поля статусу в тілі цієї сторінки рішень; не треба плутати його з обов’язковою відповідністю новішому шаблону. Це корисний приклад того, що правила формату теж є рішеннями, але сам формат та його історичні записи еволюціонують MADR: рішення про поле статусу.
Як агент має працювати з журналом рішень
Агент, який змінює код, спершу має прочитати чинні домовленості. Це зменшує ризик повторити вже відкинуту пропозицію або змінити межу системи без відомого аргументу. Водночас наявність текстового файла не дає моделі права вигадати, що всі записи прийнято. Агент перевіряє статус, дату, посилання на заміну та відповідність контексту поточній задачі.
Для інструментального агента корисний такий порядок:
- Знайти вказівник на журнал і каталоги ADR; переглянути файли, пов’язані з системою або компонентом задачі.
- Для кожного кандидата перевірити його статус, останнє оновлення, можливий ADR-замінник, джерела й власника рішення.
- Відокремити прийнятий напрям від пропозиції, відхиленого вибору, застарілого опису та непідтвердженої реалізації.
- Порівняти контекст ADR із задачею: чи ті самі вимоги, обмеження, середовище, навантаження, постачальник і межа системи?
- Якщо запланована зміна суперечить прийнятому рішенню, пояснити конфлікт, назвати точний запис і поставити його на розгляд відповідального власника. Не переписувати приховано реалізацію або статус.
- Якщо зміна потребує нового значущого вибору, підготувати чернетку ADR зі справжніми альтернативами, явно позначеними невідомими даними, наслідками й посиланнями.
- Залишити статус «запропоновано», доки уповноважена людина не погодить рішення за процесом команди. Окремо повідомити, що саме було реалізовано, а що ще очікує рішення.
Відсутність релевантного ADR не доводить, що архітектурний вибір уже вільний чи автоматично погоджений. Агент має встановити факти в коді, документах та історії проєкту й відокремити їх від припущень. Якщо актуальність запису неможливо підтвердити, це причина вказати невизначеність, а не вигадувати дату перегляду.
AI (Artificial Intelligence — штучний інтелект) агент може спланувати кілька кроків і запропонувати виклик інструмента, але дію виконує застосунок-клієнт або сервіс постачальника. Документація OpenAI описує агентів, які планують і виконують завдання з інструментами та зберігають контекст між кроками. У Claude Managed Agents політика always_ask призупиняє дію для підтвердження людиною, а за auto оцінювання теж може повернути ask або deny. Це механізми конкретних API, а не погодження ADR: статус задає процес власника проєкту документація агентів OpenAI, Claude Platform: використання інструментів, Claude Managed Agents: політики дозволів.
Практичне формулювання задачі для агента:
Перед зміною коду знайди рішення, пов’язані з компонентом, і перевір їхні статуси, дати та посилання на заміну. Порівняй контекст рішень із вимогами задачі та назви можливі суперечності з посиланнями на файли. Не змінюй статус ADR і не видавай чернетку за погоджену. Якщо потрібно нове значуще рішення, запропонуй окремий ADR із альтернативами, наслідками та невідомими даними, а до зміни, що порушує чинне прийняте рішення, отримай погодження відповідального власника.
Це правило стосується архітектурного процесу, а не всіх дій агента. Кожна зміна має окремо підкорятися межам доступу, дозволам, інструкціям репозиторію та правилам безпеки. Текст ADR не може розширити ці повноваження, вимкнути захист чи перетворити невідоме на факт. Агент має цитувати прочитаний запис, повідомляти про невизначеність і віддавати авторитетне рішення відповідальній людині.
Поширені помилки
Записати тільки результат. «Обрали PostgreSQL» не допомагає зрозуміти, яку проблему розв’язували. Додайте чинники, альтернативи та компроміси; не переписуйте документацію продукту.
Описати всі інші варіанти як нездатні. Це приховує справжню причину вибору і робить документ недостовірним. Порівнюйте на однакових критеріях та пояснюйте відхилення.
Перетворити припущення на дані. Позначайте навчальне число, невідоме навантаження та прогноз окремо від виміряних фактів із джерелом.
Вказати лише позитивні наслідки. За кожним значущим вибором є нова робота або залежність. Запишіть її, назвіть власника і спосіб спостереження.
Назвати запропоноване рішення прийнятим за автора. Запишіть процес, хто погоджує і який доказ свідчить про погодження.
Плутати прийняте з розгорнутим. Погодження напряму не підтверджує завершення задачі, запуск у робочому середовищі чи перевірене відновлення.
Редагувати минуле після зміни контексту. Збережіть стару причину, створіть новий ADR і зв’яжіть їх. Пізніші факти не доводять, що тодішній вибір був недбалим.
Зберігати процедуру у невідповідному місці. ADR пояснює мотив; точні кроки резервування, міграції чи відновлення належать операційній інструкції й мають залишатися виконуваними.
Створювати ADR на кожну зміну. Надлишок записів ховає важливіші рішення. Для локального виправлення зазвичай вистачає опису зміни та її причини.
Вважати формат гарантією якості. Заповнені заголовки не доводять чесність альтернатив або істинність числа. Власник має перевірити твердження, повноваження й поточний контекст.
Підсумок
ADR зберігає одне значуще архітектурне рішення та міркування, які код може не пояснити. Добрий запис відокремлює факти, припущення, обмеження, альтернативи, вибір, наслідки й умову перегляду. Шаблон має бути достатньо малим для підтримки, але достатньо конкретним для майбутньої перевірки. Його статус, погодження та реалізація — різні речі. Якщо команда змінює напрям, вона зберігає попередню історію і створює новий запис із посиланням на заміну. Агент спершу знаходить актуальні рішення, пояснює конфлікти та може підготувати пропозицію; відповідальна людина ухвалює її за правилами команди.
Джерела та подальше читання
Матеріали перевірено 23 вересня 2026 року. Дати та статуси публічних прикладів нижче належать тексту журналу або його зафіксованій версії, а не є незалежним підтвердженням стану реалізації сторонніх систем.
- Michael Nygard. Documenting Architecture Decisions, 15 листопада 2011 року. Первісний текст про модульність, контекст, рішення, статус, наслідки та збереження запису після його заміни.
- Architectural Decision Records, adr.github.io. Визначення архітектурного рішення й ADR, журнал рішень та довідкові посилання спільноти.
- MADR: Markdown Architectural Decision Records. Опис та повний варіативний шаблон; використано як альтернативу короткому формату Ніґарда, а не як універсальну норму.
- MADR decision 0008: Add Status Field. Приклад, де автори порівнюють кілька способів показати статус. У тілі цього історичного запису немає власного явного статусу.
- Model Context Protocol, ext-skills contributors. Журнал рішень на коміті 81f55b67. Використано прийняті записи від 14 лютого й 16 березня, частково замінений запис від 16 квітня та прийняте рішення про першу версію від 16 липня 2026 року; статуси й формулювання аналізувалися тільки в цій версії файла.
- Model Context Protocol, ext-skills contributors. PR #60. Історія пропозиції щодо метаданих, на яку посилається ADR від 16 березня 2026 року.
- Neal Ford, Mark Richards, Pramod Sadalage, Zhamak Dehghani. Software Architecture: The Hard Parts, O’Reilly Media, 2021. Бібліографічна сторінка Neal Ford. Перевірено авторів, видавця, предмет книги та акцент на компромісах; повний текст книги не використовувався, сторінки чи цитати не приписуються.
- OpenAI. Agents API: офіційний посібник. Використано для опису контексту, інструментів і обмежень агентних систем; посібник не визначає процес схвалення ADR.
- Anthropic. How tool use works, документація Claude Platform; перевірено 23 вересня 2026 року. Розрізняє інструменти, які виконує клієнтський застосунок, і серверні інструменти постачальника.
- Anthropic. Permission policies, документація Claude Managed Agents; перевірено 23 вересня 2026 року. Розрізняє типи політик
always_allow,always_askіautoта результати оцінюванняallow,askіdeny; заaskвиклик може чекати на підтвердження людини. Це API-специфічна, бета-функція, не універсальна політика для всіх агентів.