Architecture Decision Record

Запис архітектурного рішення (ADR)

Шаблони, приклади та настанови для запису архітектурних рішень.

Запис архітектурного рішення (ADR) — це документ, що фіксує важливе архітектурне рішення разом з його контекстом і наслідками.

Переклади: العربية, বাংলা, Cymraeg, Dansk, Deutsch, English, Lietuvių, Gaeilge, Lëtzebuergesch, తెలుగు, தமிழ், मराठी, Hausa, ગુજરાતી, Euskara, भोजपुरी, Basa Jawa, فارسی, ਪੰਜਾਬੀ, Malti, Latviešu, Slovenščina, Slovenčina, Hrvatski, Български, Čeština, Magyar, Ελληνικά, Română, Polski, Español, Eesti, Suomi, Français, हिन्दी, Bahasa Indonesia, Íslenska, Italiano, 日本語, 한국어, Nederlands, Português, Русский, Svenska, Kiswahili, ไทย, Türkçe, Українська, اردو, Tiếng Việt, 中文

Перш ніж використовувати ці ресурси в будь-яких критичних системах, самостійно перевірте їх із належною ретельністю.

Зміст:

Шаблони:

Приклади:

Що таке запис архітектурного рішення?

Запис архітектурного рішення (architecture decision record, ADR) — це документ, що фіксує важливе архітектурне рішення разом з його контекстом і наслідками.

Архітектурне рішення (architecture decision, AD) — це вибір у проєктуванні програмного забезпечення, який відповідає на суттєву вимогу.

Журнал архітектурних рішень (architecture decision log, ADL) — це сукупність усіх ADR, створених і підтримуваних для певного проєкту (або організації).

Архітектурно значуща вимога (architecturally-significant requirement, ASR) — це вимога, що має вимірний вплив на архітектуру програмної системи.

Усе це належить до теми управління архітектурними знаннями (architecture knowledge management, AKM).

Мета цього документа — дати швидкий огляд ADR, того, як їх створювати, і де шукати додаткову інформацію.

Абревіатури:

  • AD: архітектурне рішення

  • ADL: журнал архітектурних рішень

  • ADR: запис архітектурного рішення

  • AKM: управління архітектурними знаннями

  • ASR: архітектурно значуща вимога

Як почати користуватися ADR

Щоб почати користуватися ADR, обговоріть із колегами такі напрями.

Визначення рішень:

  • Наскільки термінове й наскільки важливе це AD?

  • Чи його потрібно ухвалити зараз, чи можна зачекати, поки з’явиться більше знань?

  • Допомогти у визначенні рішень можуть і особистий та колективний досвід, і визнані методи та практики проєктування.

  • В ідеалі ведіть список рішень, які потрібно ухвалити, що доповнює список завдань продукту.

Ухвалення рішень:

  • Існує чимало технік ухвалення рішень — як загальних, так і специфічних для архітектури програмного забезпечення, наприклад, картографування діалогу (dialogue mapping).

  • Групове ухвалення рішень — активна тема досліджень.

Запровадження та дотримання рішень:

  • AD використовуються під час проєктування програмного забезпечення; тому їх потрібно доносити до зацікавлених сторін системи, які її фінансують, розробляють і експлуатують, та отримувати їхнє схвалення.

  • Дві пов’язані практики — архітектурно очевидні стилі кодування та рев’ю коду, зосереджені на архітектурних питаннях і рішеннях.

  • AD також потрібно (пере)розглядати під час модернізації програмної системи в процесі її еволюції.

Поширення рішень (необов’язково):

  • Багато AD повторюються в різних проєктах.

  • Тому досвід минулих рішень, і вдалих, і невдалих, може бути цінним повторно використовуваним активом, якщо застосовувати явну стратегію управління знаннями.

Документування рішень:

  • Існує багато шаблонів та інструментів для фіксації рішень.

  • Див. гнучкі (agile) спільноти, наприклад, ADR за М. Найгардом.

  • Див. традиційні процеси програмної інженерії та проєктування архітектури, наприклад, табличні макети, запропоновані IBM UMF та Тайрі й Акерманом із CapitalOne.

Докладніше:

Як почати користуватися ADR з інструментами

  • MySpec — платформа автоматизованих специфікацій та архітектурних рішень, що структурує конституцію проєкту, технічну архітектуру та ADR у чистий Markdown, який подається через MCP.

Ви можете почати користуватися ADR з інструментами будь-яким способом.

Наприклад:

  • Якщо ви любите Google Drive і онлайн-редагування, то можете створити Google Doc або Google Sheet.

  • Якщо ви любите користуватися системою контролю версій вихідного коду, як-от git, то можете створити файл для кожного ADR.

  • Якщо ви любите інструменти планування проєктів, як-от Atlassian Jira, то можете скористатися трекером планування цього інструмента.

  • Якщо ви любите вікі, як-от MediaWiki, то можете створити вікі з ADR.

Як почати користуватися ADR з git

Якщо ви любите користуватися системою контролю версій git, ось як ми любимо починати користуватися ADR з git у типовому програмному проєкті з вихідним кодом.

Створіть каталог для файлів ADR:

$ mkdir adr

Для кожного ADR створіть текстовий файл, наприклад choose-database.md:

$ vi choose-database.md

Пишіть в ADR усе, що завгодно. Ідеї дивіться в шаблонах у цьому репозиторії.

Закомітьте ADR у свій git-репозиторій.

Навички Claude Code для ADR

Цей репозиторій постачає дві навички Claude Code у каталозі skills/, щоб кодувальний ШІ-агент міг писати й підтримувати ADR так, як рекомендує цей проєкт:

  • architecture-decision-record-skill — загального призначення, для всіх, хто пише ADR у будь-якому проєкті. Допомагає вирішити, чи потрібен рішенню ADR, налаштовує каталог adr/ або decisions/, називає файл, обирає шаблон з-поміж одинадцяти вбудованих каркасів і пише змістовні розділи «Контекст/Рішення/Наслідки».

  • architecture-decision-record-maintainer-skill — спеціально для супровідників цього репозиторію. Документує структуру репозиторію, конвенцію дзеркалення README/locales і точні кроки для додавання нового шаблону, прикладу чи посилання на інструмент.

Щоб скористатися навичкою, скопіюйте її папку до .claude/skills/ у корені репозиторію, у якому ви працюєте (або до ~/.claude/skills/, щоб зробити її доступною в кожному проєкті), а потім попросіть Claude Code написати чи переглянути ADR.

Правила іменування файлів для ADR

Якщо ви вирішили створювати ADR у звичайних текстових файлах, вам може знадобитися власне правило іменування файлів ADR.

Ми віддаємо перевагу правилу іменування файлів із чітким форматом.

Приклади:

  • choose-database.md

  • format-timestamps.md

  • manage-passwords.md

  • handle-exceptions.md

Наше правило іменування файлів:

  • Назва містить дієслівну фразу в наказовому способі теперішнього часу. Це покращує читабельність і відповідає формату наших повідомлень комітів.

  • Назва використовує малі літери та дефіси (як і в цьому репозиторії). Це баланс між читабельністю та зручністю використання в системі.

  • Розширення — markdown. Це може бути корисним для легкого форматування.

Поради щодо написання якісних ADR

Ознаки якісного ADR:

  • Обґрунтування: поясніть причини ухвалення саме цього AD. Це можуть бути контекст (див. нижче), плюси й мінуси різних можливих варіантів, порівняння можливостей, обговорення витрат і вигод тощо.

  • Конкретність: кожен ADR має стосуватися одного AD, а не кількох.

  • Позначки часу: вказуйте, коли написано кожен пункт ADR. Це особливо важливо для аспектів, що можуть змінюватися з часом, як-от витрати, графіки, масштабування тощо.

  • Незмінність: не змінюйте наявну інформацію в ADR. Натомість доповнюйте ADR новою інформацією або замінюйте його, створивши новий ADR.

Ознаки доброго розділу «Контекст» в ADR:

  • Поясніть ситуацію вашої організації та її бізнес-пріоритети.

  • Додайте обґрунтування та міркування, засновані на соціальному складі й навичках ваших команд.

  • Додайте релевантні плюси й мінуси та опишіть їх у термінах, що відповідають вашим потребам і цілям.

Ознаки доброго розділу «Наслідки» в ADR:

  • Поясніть, що випливає з ухвалення рішення. Це можуть бути ефекти, підсумки, результати, подальші дії тощо.

  • Додайте інформацію про будь-які наступні ADR. Досить часто один ADR породжує потребу в нових ADR, наприклад, коли один ADR робить великий загальний вибір, який своєю чергою створює потребу в додаткових менших рішеннях.

  • Додайте будь-які процеси ретроспективного огляду. Типово команди переглядають кожен ADR за місяць, щоб порівняти інформацію в ADR із тим, що сталося на практиці, і так навчатися та зростати.

Новий ADR може замінити попередній ADR:

  • Коли ухвалюється AD, що замінює або скасовує попередній ADR, слід створити новий ADR

Приклади шаблонів ADR

Приклади шаблонів ADR, які ми зібрали в мережі:

Поради щодо командної роботи для ADR

Якщо ви розглядаєте можливість використання записів рішень у своїй команді, ось поради, які ми засвоїли, працюючи з багатьма командами.

У вас є нагода вести колег за собою, разом обговорюючи «чому», а не наказуючи «що». Наприклад, записи рішень — це спосіб для команд мислити розумніше й краще спілкуватися; вони не є цінними, якщо це лише нав’язана постфактум паперова вимога.

Деякі команди значно більше люблять назву «рішення» (decisions), ніж абревіатуру «ADR». Коли деякі команди використовують назву каталогу «decisions», це наче вмикає лампочку, і команда починає складати до каталогу більше інформації — рішення щодо постачальників, рішення щодо планування, рішення щодо розкладу тощо. Усі ці види інформації можуть використовувати той самий шаблон. Ми припускаємо, що люди швидше вчаться зі словами («рішення»), ніж з абревіатурами («ADR»), що люди більше мотивовані писати робочі документи, коли слово «запис» (record) прибрано, а також що дехто з розробників і менеджерів не любить слово «архітектура».

У теорії незмінність ідеальна. На практиці для наших команд краще працювала змінність. Ми вставляємо нову інформацію в наявний ADR із датою та приміткою, що інформація надійшла після ухвалення рішення. Такий підхід дає «живий документ», який можемо оновлювати всі ми. Типові оновлення — коли ми отримуємо інформацію завдяки новим колегам, новим пропозиціям, реальним результатам нашого використання або змінам з боку третіх сторін постфактум, як-от можливості постачальників, цінові плани, ліцензійні угоди тощо.

Питання щодо командної роботи для ADR

Хто може створити ADR?

Розгляньте такі аспекти, як окремі люди, окремі ролі, окремі команди чи окремі відділи; також розгляньте, чи є люди, ролі, команди або відділи, які можуть замовити ADR, тобто попросити, щоб його написав хтось інший.

Приклад відповіді: будь-яка людина в нашій організації, яка прочитала сторінку README про запис архітектурного рішення, може запропонувати ADR, тобто почати його писати й поділитися ним із командою.

Що виправдовує створення ADR?

Розгляньте такі аспекти, як спосіб роботи команд вашої організації, структура вашої програмної системи, координація між командами, довгострокова підтримуваність, зовнішні інтерфейси, на чию користь ви працюєте тощо.

Приклад відповіді: ми хочемо створити ADR, коли хочемо, щоб майбутні розробники розуміли «чому» того, що ми робимо.

Що виправдовує відмову від створення ADR?

Розгляньте такі аспекти, як рішення, що не стосуються архітектури або є крихітними — з мінімальним ризиком, самодостатніми чи на рівні одного розробника, — або вже повністю охоплені деінде, наприклад стандартами, політиками чи документацією, або є тимчасовими, як-от обхідні шляхи, проби концепції чи експерименти.

Приклад відповіді: ми хочемо пропустити ADR, коли рішення обмежене за обсягом, часом, ризиком і вартістю або вже охоплене деінде.

Який життєвий цикл має ADR?

Розгляньте такі аспекти, як процес створення, процес дослідження, процес ухвалення рішення, процес впровадження та процес виведення з обігу. Подумайте, як відстежувати життєвий цикл ADR у часі, наприклад як переводити ADR з одного стану в наступний, а також як повідомляти про це зацікавлені сторони.

Приклад відповіді: ми хочемо, щоб ADR мав п’ять етапів життєвого циклу: ініціювання → дослідження → оцінювання → впровадження → супровід → виведення з обігу.

Які критерії для кроків життєвого циклу ADR?

Розгляньте такі аспекти, як критерії прийняття ADR, тобто як зрозуміти, що він достатньо добрий, щоб перейти з одного кроку життєвого циклу на наступний? Чи чітко сформульовано проблему? Чи розглянуто альтернативи? Чи достатньо добре зрозумілі й задокументовані компроміси? Чи наявний весь релевантний контекст? Чи залучено всі релевантні зацікавлені сторони? Чи враховано весь зворотний зв’язок?

Приклад відповіді: ми хочемо, щоб зацікавлені сторони голосували за ADR, коли активна команда 1) завершила дослідження, 2) завершила оцінювання, 3) опублікувала пропозицію ADR для зацікавлених сторін із запитом на коментарі та обмеженням у часі в один тиждень, 4) усі коментарі зацікавлених сторін враховано й опрацьовано.

Які ролі й обов’язки пов’язані з ADR?

Розгляньте такі ролі, як автор пропозиції, дослідник, оцінювач, рецензент, затверджувач, супровідник тощо. Розгляньте такі обов’язки, як комунікація із зацікавленими сторонами, забезпечення виконання очікувань, публікація на вебсайті чи інтранеті та періодичний перегляд роботи, особливо коли відбуваються суттєві зміни.

Приклад відповіді: ми хочемо, щоб кожен ADR завжди мав основну контактну особу, додаткову контактну особу й відповідальну команду; вони відповідають за комунікацію, публікацію, супровід, періодичний перегляд щонайменше раз на рік і, за потреби, остаточне виведення з обігу.

Як управління (governance) взаємодіє з ADR?

Розгляньте такі аспекти, як способи роботи вашої організації, особливі вимоги відповідності, наприклад щодо правових аспектів чи кадрових питань, як ви хочете діяти в разі консенсусу, конфлікту й ескалації. Чи є напрями, люди або команди, які можуть мати більший вплив на ADR, ніж інші, наприклад мати змогу затвердити його, проголосувати за нього чи накласти вето?

Приклад відповіді: управління ADR відбувається в такому порядку пріоритету: генеральний директор (CEO), технічний директор (CTO), юридичний директор (CLO), команда, що впроваджує ADR, експерти в команді, які найкраще знаються на AD. Ніхто інший не має права управління, якщо це не описано в ADR.

Які принципи пов’язані з ADR?

Розгляньте такі аспекти, як способи роботи вашої організації, зокрема швидко чи повільно діяти, консенсус чи конфлікт у рішеннях, перевага ризику чи перевага безпеки, публічне чи приватне обговорення тощо.

Приклад відповіді: ми дотримуємося лідерських принципів: схильність до дії, «не погоджуйся — але виконуй» (disagree-and-commit), оцінки з точністю 70 % достатні для рішень, які легко скасувати й легко ізолювати, та публічні способи роботи, за винятком конфіденційної інформації, як описано в угоді про конфіденційність нашої організації.

Концепції наступного кроку для ADR

Arc42 відповідає на два запитання прагматичним способом і може бути пристосований до ваших конкретних потреб. Що слід документувати/доносити про вашу архітектуру? Як це слід документувати/доносити? Arc42 містить записи архітектурних рішень, а також настанови щодо цілей, обмежень, контекстів, якості, ризиків та іншого.

Модель C4 — легкий для вивчення, дружній до розробників підхід до діаграм архітектури програмного забезпечення. C4 — це набір ієрархічних діаграм для контексту, контейнерів, компонентів, коду, а також допоміжні діаграми для ландшафту системи, динаміки й розгортання.

Архітектурні діаграми, погляди та точки зору

Архітектурна діаграма називається «архітектурним поглядом» (view).

«Архітектурний погляд» — це екземпляр «архітектурної точки зору» (viewpoint).

«Архітектурна точка зору» має конкретну аудиторію з конкретними проблемами в уявленні.

Приклади архітектурних точок зору, поглядів і діаграм:

Пов’язані діаграми:

  • Діаграма варіантів використання показує сценарії використання керівництву/клієнтам, що передує вимогам, які передують архітектурі програмного забезпечення.

  • Діаграма розгортання показує фізичне обладнання/комп’ютери, на які розгортаються програмні компоненти.

  • Діаграма потоків даних показує, як дані рухаються системою та перетворюються.

  • Діаграма послідовності використовується, щоб показати, як протоколи на кшталт HTTP працюють на осі часу.

  • Діаграма діяльності зображує робочий процес діяльностей, які виконує програмна система, наприклад ШІ неігрового персонажа (NPC).

Функції придатності для рішень як коду

Функції придатності (fitness functions) — це об’єктивні автоматизовані перевірки, написані програмним кодом, які підтверджують, що рішення дотримуються.

  • Функції придатності роблять рішення тестованими й підтверджуваними.

  • Функції придатності для рішень можуть значно допомогти у забезпеченні якості, регуляторних процесах та цілях управління (governance).

Як функції придатності пов’язані з рішеннями

Запис рішення документує рішення, а функція придатності його гарантує.

  • Приклад рішення: ми використовуємо event sourcing через вимоги до аудиту.

  • Приклад функції придатності: ми використовуємо сервер безперервної інтеграції, щоб перевіряти, що кожна зміна стану має породжувати події.

Чим функції придатності допомагають рішенням

Об’єктивні вимірювання: функції придатності або проходять, або ні, тож робота видима й зрозуміла.

Постійне використання: функції придатності — це ваші живі правила, що запускаються для кожного коміту та збірки.

Впевненість у рефакторингу: функції придатності автоматично виявляють помилки в правилах рішень.

Масштабоване управління: функції придатності забезпечують стандарти, не створюючи вузьких місць.

Чи можуть функції придатності використовувати ШІ?

Функції придатності можуть застосовувати великі мовні моделі (LLM) для рішень, ставлячи запитання щодо вашої роботи, наприклад, ваших планів, коду, схем, API тощо:

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning.
IMPORTANT: Turn on extended thinking. Turn on expert advice. Turn on search.

This is a fitness function to evaluate if our work is
using all our decisions, and is correct and accurate.

- Our decisions are here: {url}
- Our work to evaluate is here: {url}

Explain any errors, problems, gaps, weaknesses. Be direct. Be decisive.

Модульне тестування архітектури

ArchUnit: перевіряйте архітектурні правила коду на Java за допомогою будь-якого звичайного фреймворку модульного тестування Java.

ArchUnitTS: перевіряйте архітектурні правила коду на TypeScript і JavaScript за допомогою Jest, Vitest, Jasmine тощо.

Запобіжники рішень для запитів на злиття

Decision Guardian автоматично виводить потрібні записи рішень у потрібний момент — коли розробник активно змінює код, який ці рішення охоплюють. Замість того щоб сподіватися, що розробники прочитають папку з документацією перед злиттям, відповідний контекст з’являється безпосередньо в запиті на злиття.

Це працює для будь-якого виду записів рішень: архітектурних рішень, рішень щодо даних, рішень щодо відповідності, клінічних і медичних рішень, рішень щодо безпеки тощо.

Працює з будь-якою системою CI (GitLab, Jenkins, CircleCI) і як хук pre-commit. З відкритим кодом. Ліцензія MIT.

ADR Guard — це GitHub Action, що завершує запит на злиття помилкою, коли змінюються контрольовані шляхи коду без додавання чи оновлення запису архітектурного рішення. Винятки явні: рядок ADR-Exempt: з причиною пропускає перевірку й записується в підсумок завдання. Не залежить від шаблону, без залежностей. З відкритим кодом. Ліцензія MIT.

Докладніше

Вступ:

Шаблони:

Глибше:

Інструменти:

Настанови окремих компаній:

Приклади:

Відео:

Подкасти:

Книги:

Дивіться також:

  • REMAP (Representation and Maintenance of Process Knowledge)

  • DRL (Decision Representation Language)

  • IBIS (Issue-Based Information System)

  • QOC (Questions, Options, and Criteria)

  • IBM’s e-Business Reference Architecture Framework

  • Decision Reasoning Format (DRF) — незалежний від постачальника, машинозчитуваний формат YAML/JSON для подання рішень з явними міркуваннями, припущеннями, когнітивним станом і компромісами. Доповнює ADR, додаючи до документації рішень структуровані міркування, що піддаються перевірці.