Architecture Decision Record

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

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

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

Преводи: العربية, বাংলা, Cymraeg, Dansk, Deutsch, English, 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, 中文

Направете собствена надлежна проверка на тези ресурси, преди да ги използвате в каквито и да е критични системи.

Съдържание:

Шаблони:

Примери:

Какво е запис на архитектурно решение?

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

Архитектурно решение (AD) е избор при проектирането на софтуер, който отговаря на значително изискване.

Дневник на архитектурните решения (ADL) е съвкупността от всички ADR, създадени и поддържани за определен проект (или организация).

Архитектурно значимо изискване (ASR) е изискване, което има измеримо въздействие върху архитектурата на софтуерна система.

Всичко това попада в областта на управлението на архитектурните знания (AKM).

Целта на този документ е да предостави бърз преглед на ADR, как да се създават и къде да се търси повече информация.

Съкращения:

  • AD: архитектурно решение

  • ADL: дневник на архитектурните решения

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

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

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

Как да започнете да използвате ADR

За да започнете да използвате ADR, обсъдете със съекипниците си следните области.

Идентифициране на решения:

  • Колко спешно и колко важно е AD?

  • Трябва ли да бъде взето сега, или може да изчака, докато се узнае повече?

  • Както личният и колективният опит, така и признатите методи и практики за проектиране могат да помогнат при идентифицирането на решения.

  • В идеалния случай поддържайте списък със задачи за решения, който допълва списъка със задачи на продукта.

Вземане на решения:

  • Съществуват редица техники за вземане на решения, както общи, така и специфични за софтуерната архитектура, например картографиране на диалога (dialogue mapping).

  • Груповото вземане на решения е активна изследователска тема.

Прилагане и налагане на решения:

  • AD се използват при проектирането на софтуер; следователно те трябва да бъдат съобщени на и приети от заинтересованите страни на системата, които я финансират, разработват и експлоатират.

  • Архитектурно очевидните стилове на кодиране и прегледите на код, които се фокусират върху архитектурни въпроси и решения, са две свързани практики.

  • AD трябва също да бъдат (повторно) разгледани при модернизиране на софтуерна система в хода на софтуерната еволюция.

Споделяне на решения (по избор):

  • Много AD се повтарят в различни проекти.

  • Следователно опитът с минали решения, както добър, така и лош, може да бъде ценен преизползваем актив при прилагане на изрична стратегия за управление на знанията.

Документиране на решения:

  • Съществуват много шаблони и инструменти за фиксиране на решения.

  • Вижте гъвкавите общности, напр. ADR на M. Nygard.

  • Вижте традиционните процеси на софтуерното инженерство и архитектурното проектиране, напр. табличните оформления, предложени от IBM UMF и от Tyree и Akerman от CapitalOne.

За повече информация:

  • Стъпките по-горе са взети от статията в Уикипедия за Architectural Decision

Как да започнете да използвате 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 хранилище.

Умения (skills) на 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, а не за няколко AD.

  • Времеви печати: Посочвайте кога е написан всеки елемент в ADR. Това е особено важно за аспекти, които могат да се променят с времето, като разходи, графици, мащабиране и подобни.

  • Неизменимост: Не променяйте съществуваща информация в ADR. Вместо това допълнете ADR, като добавите нова информация, или заменете ADR, като създадете нов ADR.

Характеристики на добър раздел „Контекст“ в ADR:

  • Обяснете ситуацията на вашата организация и бизнес приоритетите.

  • Включете обосновка и съображения, основани на социалния състав и уменията на вашите екипи.

  • Включете съответните плюсове и минуси и ги описвайте с термини, които съответстват на вашите нужди и цели.

Характеристики на добър раздел „Последици“ в ADR:

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

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

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

Нов ADR може да замени предишен ADR:

  • Когато бъде взето AD, което замества или обезсилва предишен ADR, трябва да се създаде нов ADR

Примерни шаблони за ADR

Примерни шаблони за ADR, събрани от интернет:

Съвети за работа в екип за ADR

Ако обмисляте да използвате записи на решения във вашия екип, ето няколко съвета, които сме научили, работейки с много екипи.

Имате възможност да поведете съекипниците си, като обсъждате заедно „защо“, вместо да налагате „какво“. Например записите на решения са начин екипите да мислят по-умно и да общуват по-добре; записите на решения нямат стойност, ако са просто изискване за принудителна документация постфактум.

Някои екипи предпочитат много повече името „решения“ пред съкращението „ADR“. Когато някои екипи използват името на директорията „decisions“, сякаш се включва крушка и екипът започва да слага повече информация в директорията, като решения за доставчици, решения за планиране, решения за графици и т.н. Всички тези видове информация могат да използват един и същ шаблон. Предполагаме, че хората учат по-бързо с думи („решения“), отколкото със съкращения („ADR“), и че хората са по-мотивирани да пишат документи за работа в процес, когато думата „запис“ е премахната, а също така някои разработчици и някои мениджъри не харесват думата „архитектура“.

На теория неизменимостта е идеална. На практика изменимостта работи по-добре за нашите екипи. Вмъкваме новата информация в съществуващия 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 е в този приоритетен ред: главният изпълнителен директор, техническият директор, юридическият директор, екипът, който реализира ADR, експертите в екипа, които са най-запознати с AD. Никой друг няма управленска власт, освен ако не е описано в ADR.

Какви принципи взаимодействат с ADR?

Обмислете области като начина на работа на вашата организация, който включва действие бързо срещу действие бавно, консенсус при решенията срещу конфликт при решенията, предпочитания към риск срещу предпочитания към безопасност, публична дискусия срещу частна дискусия и подобни.

Примерен отговор: Използваме лидерските принципи за склонност към действие, несъгласие и ангажираност (disagree-and-commit), 70% оценки са достатъчно добри за лесно обратими и лесно изолируеми решения и публичен начин на работа, с изключение на поверителната информация, както е описано в споразумението за поверителност на нашата организация.

Концепции за следваща стъпка за ADR

Arc42 отговаря прагматично на два въпроса и може да бъде приспособен към вашите конкретни нужди. Какво си струва да документирате/съобщавате за вашата архитектура? Как си струва да го документирате/съобщавате? Arc42 включва записи на архитектурни решения, както и насоки за цели, ограничения, контекст, качество, рискове и други.

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

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

Архитектурната диаграма се нарича „архитектурен изглед“.

„Архитектурният изглед“ е екземпляр на „архитектурна гледна точка“.

„Архитектурната гледна точка“ има конкретна аудитория с конкретни интереси.

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

Свързани диаграми:

  • Диаграмата на случаите на употреба показва случаите на употреба на ръководството/клиентите, което предхожда изискванията, които предхождат софтуерната архитектура.

  • Диаграмата на внедряването показва физическия хардуер/компютри, на които са внедрени софтуерните компоненти.

  • Диаграмата на потоците от данни показва как данните се движат през системата и как се трансформират.

  • Диаграмата на последователностите служи за показване как работят протоколите, например HTTP, във времевата линия.

  • Диаграмата на дейностите изобразява работния поток от дейности, извършвани от софтуерна система, например ИИ на NPC.

Фитнес функции за решения като код

Фитнес функциите са обективни автоматизирани проверки, написани с програмен код, които проверяват дали решенията се спазват.

  • Фитнес функциите правят решенията тестваеми и гарантируеми.

  • Фитнес функциите за решения могат значително да помогнат за осигуряването на качеството, регулаторните процеси и целите на управлението.

Как фитнес функциите се свързват с решенията

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

  • Примерно решение: Използваме 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 и др.

Предпазни мерки за решенията при pull request-и

Decision Guardian автоматично изважда на показ правилните записи на решения в правилния момент — когато разработчик активно променя кода, който тези решения обхващат. Вместо да се разчита, че разработчиците ще прочетат папка с документация преди сливане, съответният контекст се появява директно в pull request-а.

Работи с всякакъв вид запис на решение: архитектурни решения, решения за данни, решения за съответствие, клинични и медицински решения, решения за сигурност и други.

Работи и с всяка CI система (GitLab, Jenkins, CircleCI) и като pre-commit hook. С отворен код. Лиценз MIT.

ADR Guard е GitHub Action, който проваля pull request, ако наблюдавани пътища в кода се променят, без да бъде добавен или актуализиран запис на архитектурно решение. Изключенията са изрични: ред 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, като добавя структурирана, валидируема обосновка към документацията на решенията.