Architecture Decision Record

Architektūros sprendimo įrašas (ADR)

Šablonai, pavyzdžiai ir rekomendacijos architektūros sprendimams fiksuoti.

Architektūros sprendimo įrašas (ADR) yra dokumentas, kuriame užfiksuotas svarbus priimtas architektūrinis sprendimas kartu su jo kontekstu ir pasekmėmis.

Vertimai: العربية, বাংলা, Cymraeg, Dansk, Deutsch, English, Lietuvių, Gaeilge, 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, 中文

Prieš naudodami šiuos išteklius bet kurioje kritinėje sistemoje, atlikite savo kruopštų patikrinimą.

Turinys:

Šablonai:

Pavyzdžiai:

Kas yra architektūros sprendimo įrašas?

Architektūros sprendimo įrašas (ADR) yra dokumentas, kuriame užfiksuotas svarbus priimtas architektūrinis sprendimas kartu su jo kontekstu ir pasekmėmis.

Architektūros sprendimas (AD) yra programinės įrangos projektavimo pasirinkimas, kuriuo sprendžiamas reikšmingas reikalavimas.

Architektūros sprendimų žurnalas (ADL) yra visų konkrečiam projektui (ar organizacijai) sukurtų ir prižiūrimų ADR rinkinys.

Architektūriškai reikšmingas reikalavimas (ASR) yra reikalavimas, kuris turi išmatuojamą poveikį programinės įrangos sistemos architektūrai.

Visa tai priklauso architektūros žinių valdymo (AKM) temai.

Šio dokumento tikslas – greitai apžvelgti ADR, parodyti, kaip juos kurti, ir nurodyti, kur ieškoti daugiau informacijos.

Santrumpos:

  • AD: architektūros sprendimas

  • ADL: architektūros sprendimų žurnalas

  • ADR: architektūros sprendimo įrašas

  • AKM: architektūros žinių valdymas

  • ASR: architektūriškai reikšmingas reikalavimas

Kaip pradėti naudoti ADR

Norėdami pradėti naudoti ADR, pasikalbėkite su komandos nariais apie šias sritis.

Sprendimų nustatymas:

  • Kiek skubus ir kiek svarbus yra AD?

  • Ar jį reikia priimti dabar, ar galima palaukti, kol paaiškės daugiau?

  • Sprendimams nustatyti gali padėti tiek asmeninė, tiek kolektyvinė patirtis, taip pat pripažinti projektavimo metodai ir praktikos.

  • Idealiu atveju palaikykite sprendimų užduočių sąrašą, papildantį produkto užduočių sąrašą.

Sprendimų priėmimas:

  • Yra daug sprendimų priėmimo būdų – tiek bendrųjų, tiek būdingų programinės įrangos architektūrai, pavyzdžiui, dialogų žemėlapiai.

  • Grupinis sprendimų priėmimas yra aktyvi tyrimų tema.

Sprendimų įgyvendinimas ir užtikrinimas:

  • AD naudojami programinės įrangos projektavime, todėl apie juos reikia informuoti sistemos suinteresuotuosius asmenis, kurie ją finansuoja, kuria ir eksploatuoja, ir jie turi juos pritarti.

  • Dvi susijusios praktikos – architektūriškai aiškus kodavimo stilius ir kodo peržiūros, kuriose daugiausia dėmesio skiriama architektūriniams rūpesčiams ir sprendimams.

  • AD taip pat reikia (iš naujo) apsvarstyti modernizuojant programinės įrangos sistemą jos evoliucijos metu.

Sprendimų dalijimasis (neprivaloma):

  • Daugelis AD kartojasi įvairiuose projektuose.

  • Todėl patirtis, susijusi su ankstesniais sprendimais, tiek gerais, tiek blogais, gali būti vertingas pakartotinai naudojamas turtas, kai taikoma aiški žinių valdymo strategija.

Sprendimų dokumentavimas:

  • Yra daug sprendimų fiksavimo šablonų ir įrankių.

  • Žr. lanksčiąsias bendruomenes, pvz., M. Nygardo ADR.

  • Žr. tradicinius programinės įrangos inžinerijos ir architektūros projektavimo procesus, pvz., lentelių išdėstymus, kuriuos siūlo IBM UMF ir „CapitalOne“ atstovai Tyree ir Akermanas.

Daugiau:

Kaip pradėti naudoti ADR su įrankiais

  • MySpec — automatizuota specifikacijų ir architektūrinių sprendimų platforma, kuri projekto konstituciją, techninę architektūrą ir ADR sutvarko į aiškų Markdown, pateikiamą per MCP.

ADR su įrankiais galite pradėti naudoti bet kokiu jums patinkančiu būdu.

Pavyzdžiui:

  • Jei mėgstate naudoti „Google Drive“ ir redagavimą internete, galite sukurti „Google“ dokumentą arba „Google“ skaičiuoklę.

  • Jei mėgstate naudoti šaltinio kodo versijų valdymą, pavyzdžiui, git, galite sukurti failą kiekvienam ADR.

  • Jei mėgstate naudoti projektų planavimo įrankius, pavyzdžiui, „Atlassian Jira“, galite naudoti įrankio planavimo sekiklį.

  • Jei mėgstate viki svetaines, pavyzdžiui, „MediaWiki“, galite sukurti ADR viki.

Kaip pradėti naudoti ADR su git

Jei mėgstate git versijų valdymą, štai kaip mes mėgstame pradėti naudoti ADR su git tipiniame programinės įrangos projekte su šaltinio kodu.

Sukurkite katalogą ADR failams:

$ mkdir adr

Kiekvienam ADR sukurkite tekstinį failą, pavyzdžiui, choose-database.md:

$ vi choose-database.md

ADR rašykite bet ką norite. Idėjų ieškokite šiame saugykloje esančiuose šablonuose.

Įkelkite ADR į savo git saugyklą (angl. commit).

Claude Code įgūdžiai ADR

Šioje saugykloje yra du Claude Code įgūdžiai (angl. skills) kataloge skills/, kad DI programavimo agentas galėtų rašyti ir prižiūrėti ADR taip, kaip rekomenduoja šis projektas:

  • architecture-decision-record-skill — bendrosios paskirties, skirtas visiems, rašantiems ADR bet kuriame projekte. Padeda nuspręsti, ar sprendimui reikia ADR, sukuria katalogą adr/ arba decisions/, parenka failo pavadinimą, pasirenka šabloną iš vienuolikos pateiktų karkasų ir parašo tvirtus skyrius „Kontekstas“ / „Sprendimas“ / „Pasekmės“.

  • architecture-decision-record-maintainer-skill — skirtas būtent šios saugyklos prižiūrėtojams. Aprašo saugyklos struktūrą, README / lokalių atspindėjimo konvenciją ir tikslius veiksmus, kaip pridėti naują šabloną, pavyzdį ar nuorodą į įrankį.

Norėdami naudoti įgūdį, nukopijuokite jo aplanką į .claude/skills/ savo saugyklos, kurioje dirbate, šakniniame kataloge (arba į ~/.claude/skills/, kad jis būtų prieinamas kiekviename projekte), tada paprašykite Claude Code parašyti ar peržiūrėti ADR.

ADR failų pavadinimų konvencijos

Jei nusprendėte kurti ADR naudodami įprastus tekstinius failus, galbūt norėsite susikurti savo ADR failų pavadinimų konvenciją.

Mes teikiame pirmenybę failų pavadinimų konvencijai, turinčiai konkretų formatą.

Pavyzdžiai:

  • choose-database.md

  • format-timestamps.md

  • manage-passwords.md

  • handle-exceptions.md

Mūsų failų pavadinimų konvencija:

  • Pavadinime yra tiesioginės nuosakos veiksmažodžio frazė esamuoju laiku. Tai gerina skaitomumą ir atitinka mūsų įkėlimo pranešimų (angl. commit message) formatą.

  • Pavadinime naudojamos mažosios raidės ir brūkšneliai (kaip ir šioje saugykloje). Tai skaitomumo ir sistemos patogumo pusiausvyra.

  • Plėtinys yra markdown. Tai gali būti naudinga, kad formatuoti būtų lengva.

Patarimai, kaip rašyti gerus ADR

Gero ADR savybės:

  • Pagrindimas: paaiškinkite konkretaus AD priėmimo priežastis. Tai gali apimti kontekstą (žr. toliau), įvairių galimų pasirinkimų privalumus ir trūkumus, savybių palyginimus, sąnaudų ir naudos aptarimus ir kita.

  • Konkretumas: kiekvienas ADR turi būti apie vieną AD, o ne apie kelis.

  • Laiko žymos: nurodykite, kada parašytas kiekvienas ADR elementas. Tai ypač svarbu aspektams, kurie laikui bėgant gali keistis, pavyzdžiui, sąnaudoms, tvarkaraščiams, mastelio keitimui ir panašiems dalykams.

  • Nekeičiamumas: nekeiskite esamos ADR informacijos. Vietoj to papildykite ADR nauja informacija arba pakeiskite ADR sukurdami naują ADR.

Gero ADR skyriaus „Kontekstas“ savybės:

  • Paaiškinkite savo organizacijos situaciją ir verslo prioritetus.

  • Pateikite pagrindimą ir svarstymus, grindžiamus jūsų komandų socialine sudėtimi ir įgūdžiais.

  • Nurodykite tinkamus privalumus ir trūkumus ir aprašykite juos taip, kad jie atitiktų jūsų poreikius ir tikslus.

Gero ADR skyriaus „Pasekmės“ savybės:

  • Paaiškinkite, kas seka iš sprendimo priėmimo. Tai gali apimti poveikį, rezultatus, išvestis, tolesnius veiksmus ir kita.

  • Pateikite informaciją apie visus vėlesnius ADR. Gana įprasta, kad vienas ADR sukelia poreikį kurti daugiau ADR, pavyzdžiui, kai vienu ADR daromas didelis bendras pasirinkimas, o tai savo ruožtu sukuria poreikį priimti daugiau mažesnių sprendimų.

  • Nurodykite visus poveikio peržiūros procesus. Įprasta, kad komandos kiekvieną ADR peržiūri po mėnesio, palygindamos ADR informaciją su tuo, kas įvyko praktikoje, kad mokytųsi ir tobulėtų.

Naujas ADR gali pakeisti ankstesnį ADR:

  • Kai priimamas AD, kuris pakeičia ar panaikina ankstesnį ADR, reikėtų sukurti naują ADR

ADR sprendimo įrašų šablonų pavyzdžiai

ADR šablonų pavyzdžiai, kuriuos surinkome internete:

Komandinio darbo patarimai dėl ADR

Jei svarstote su savo komanda naudoti sprendimų įrašus, štai keletas patarimų, kuriuos išmokome dirbdami su daugeliu komandų.

Turite galimybę vesti komandos narius pirmyn kartu kalbėdami apie „kodėl“, o ne primesdami „ką“. Pavyzdžiui, sprendimų įrašai yra būdas komandoms protingiau mąstyti ir geriau bendrauti; sprendimų įrašai neturi vertės, jei tai tik po fakto primesti popieriai.

Kai kurios komandos daug labiau mėgsta pavadinimą „sprendimai“ nei santrumpą „ADR“. Kai kai kurios komandos naudoja katalogo pavadinimą „decisions“, tarsi įsijungia lemputė, ir komanda pradeda į katalogą dėti daugiau informacijos, pavyzdžiui, tiekėjų sprendimus, planavimo sprendimus, tvarkaraščių sprendimus ir pan. Visiems šiems informacijos tipams galima naudoti tą patį šabloną. Spėjame, kad žmonės greičiau mokosi iš žodžių („sprendimai“) nei iš santrumpų („ADR“), kad žmones labiau motyvuoja rašyti nebaigtus dokumentus, kai žodis „įrašas“ pašalinamas, o kai kurie programuotojai ir vadovai taip pat nemėgsta žodžio „architektūra“.

Teoriškai nekeičiamumas yra idealus. Praktiškai mūsų komandoms geriau pasiteisino keičiamumas. Naują informaciją įterpiame į esamą ADR su datos žyma ir pastaba, kad informacija atsirado po sprendimo. Toks požiūris veda prie „gyvo dokumento“, kurį visi galime atnaujinti. Tipiniai atnaujinimai atsiranda, kai informaciją gauname dėl naujų komandos narių, naujų pasiūlymų, realių mūsų naudojimo rezultatų arba po fakto įvykusių trečiųjų šalių pokyčių, pavyzdžiui, tiekėjų galimybių, kainodaros planų, licencijų sutarčių ir pan.

Komandinio darbo klausimai dėl ADR

Kas gali sukurti ADR?

Apsvarstykite tokias sritis kaip konkretūs žmonės, konkrečios pareigos, konkrečios komandos ar konkretūs skyriai; taip pat apsvarstykite, ar yra žmonių, pareigų, komandų ar skyrių, kurie gali užsakyti ADR, t. y. paprašyti, kad jį parašytų kas nors kitas.

Atsakymo pavyzdys: bet kuris mūsų organizacijos asmuo, perskaitęs architektūros sprendimo įrašo README puslapį, gali pasiūlyti ADR, t. y. gali pradėti jį rašyti ir pasidalyti juo su komanda.

Kas pateisina ADR kūrimą?

Apsvarstykite tokias sritis kaip jūsų organizacijos komandų darbo būdai, programinės įrangos sistemos struktūra, tarpkomandinis koordinavimas, ilgalaikis prižiūrimumas, išorinės sąsajos, kam norite duoti naudos ir panašiai.

Atsakymo pavyzdys: ADR norime kurti, kai norime, kad būsimi programuotojai suprastų, „kodėl“ darome tai, ką darome.

Kas pateisina ADR nekūrimą?

Apsvarstykite tokias sritis kaip sprendimai, kurie nėra susiję su architektūra arba yra smulkūs, pavyzdžiui, mažos rizikos, savarankiški ar vieno programuotojo sprendimai, arba jau visiškai aprėpti kitur, pavyzdžiui, standartuose, politikose ar dokumentacijoje, arba yra laikini, pavyzdžiui, apėjimo būdai, koncepcijos įrodymai ar eksperimentai.

Atsakymo pavyzdys: ADR norime praleisti, kai sprendimo apimtis, trukmė, rizika ir kaina yra ribotos arba jis jau aprėptas kitur.

Koks yra ADR gyvavimo ciklas?

Apsvarstykite tokias sritis kaip kūrimo procesas, tyrimo procesas, sprendimo priėmimo procesas, įgyvendinimo procesas ir nutraukimo procesas. Apsvarstykite, kaip sekti ADR gyvavimo ciklą laikui bėgant, pavyzdžiui, kaip perkelti ADR iš vienos būsenos į kitą ir kaip apie tai informuoti suinteresuotuosius asmenis.

Atsakymo pavyzdys: norime, kad ADR turėtų penkis gyvavimo ciklo etapus: inicijavimas → tyrimas → vertinimas → įgyvendinimas → priežiūra → nutraukimas.

Kokie yra ADR gyvavimo ciklo žingsnių kriterijai?

Apsvarstykite tokias sritis kaip ADR priėmimo kriterijai, t. y. kaip žinoti, kad jis pakankamai geras, kad pereitų iš vieno gyvavimo ciklo žingsnio į kitą? Ar problema aiškiai suformuluota? Ar apsvarstytos alternatyvos? Ar kompromisai pakankamai gerai suprasti ir dokumentuoti? Ar visas svarbus kontekstas pateiktas? Ar įtraukti visi svarbūs suinteresuotieji asmenys? Ar atsižvelgta į visas atsiliepimus?

Atsakymo pavyzdys: norime, kad suinteresuotieji asmenys dėl ADR balsuotų, kai aktyvi komanda: 1) baigė tyrimą, 2) baigė vertinimą, 3) paskelbė ADR pasiūlymą suinteresuotiesiems asmenims prašydama komentarų su vienos savaitės laiko riba, 4) į visus suinteresuotųjų asmenų komentarus atsižvelgta ir jie išspręsti.

Kokios pareigos ir atsakomybės sąveikauja su ADR?

Apsvarstykite tokias pareigas kaip pasiūlytojas, tyrėjas, vertintojas, peržiūrėtojas, tvirtintojas, prižiūrėtojas ir panašiai. Apsvarstykite tokias atsakomybes kaip bendravimas su suinteresuotaisiais asmenimis, lūkesčių išpildymo užtikrinimas, dalijimasis svetainėje ar intranete ir darbo periodinė peržiūra, ypač kai įvyksta svarbių pokyčių.

Atsakymo pavyzdys: norime, kad kiekvienas ADR visada turėtų pagrindinį kontaktinį asmenį, antrinį kontaktinį asmenį ir atsakingą komandą; jie atsakingi už komunikaciją, publikavimą, priežiūrą, periodinę peržiūrą bent kartą per metus ir galimą nutraukimą, kai reikia.

Kaip valdysena sąveikauja su ADR?

Apsvarstykite tokias sritis kaip jūsų organizacijos darbo būdai, ypatingi atitikties poreikiai, pavyzdžiui, teisiniai ar žmogiškųjų išteklių aspektai, kaip norite spręsti konsensuso, konflikto ir eskalavimo klausimus. Ar yra sričių, žmonių ar komandų, kurie dėl ADR gali turėti daugiau įtakos nei kiti, pavyzdžiui, galėti jį patvirtinti, dėl jo balsuoti ar uždėti veto?

Atsakymo pavyzdys: ADR valdysena eina šia prioriteto tvarka: generalinis direktorius (CEO), technologijų direktorius (CTO), teisės direktorius (CLO), komanda, įgyvendinanti ADR, komandos ekspertai, geriausiai išmanantys AD. Niekas kitas neturi valdysenos teisių, nebent tai aprašyta ADR.

Kokie principai sąveikauja su ADR?

Apsvarstykite tokias sritis kaip jūsų organizacijos darbo būdai, apimantys greitą ar lėtą judėjimą, sprendimų konsensusą ar sprendimų konfliktą, rizikos ar saugumo pirmenybes, viešą ar privačią diskusiją ir panašiai.

Atsakymo pavyzdys: naudojame šiuos lyderystės principus: polinkis veikti, nesutikti ir įsipareigoti, 70 % įvertinimų pakanka lengvai atšaukiamiems ir lengvai izoliuojamiems sprendimams, ir viešas darbo būdas, išskyrus konfidencialią informaciją, kaip aprašyta mūsų organizacijos konfidencialumo sutartyje.

Tolesnių žingsnių konceptai ADR

Arc42 pragmatiškai atsako į du klausimus ir gali būti pritaikytas jūsų konkretiems poreikiams. Ką turėtumėte dokumentuoti / perteikti apie savo architektūrą? Kaip turėtumėte dokumentuoti / perteikti? Arc42 apima architektūros sprendimo įrašus ir nurodymus dėl tikslų, apribojimų, kontekstų, kokybės, rizikų ir kt.

C4 modelis yra lengvai išmokstamas, programuotojams draugiškas programinės įrangos architektūros diagramų kūrimo požiūris. C4 yra hierarchinių diagramų rinkinys kontekstui, konteineriams, komponentams, kodui, taip pat pagalbinės diagramos sistemų kraštovaizdžiui, dinamikai ir diegimui.

Architektūros diagramos, vaizdai ir požiūriai

Architektūros diagrama vadinama „architektūros vaizdu“.

„Architektūros vaizdas“ yra „architektūros požiūrio“ egzempliorius.

„Architektūros požiūris“ turi konkrečią auditoriją su konkrečiais rūpesčiais.

Architektūros požiūrių, vaizdų ir diagramų pavyzdžiai:

Susijusios diagramos:

  • Naudojimo atvejų diagrama rodo naudojimo atvejus vadovybei / klientams; ji eina prieš reikalavimus, o šie – prieš programinės įrangos architektūrą.

  • Diegimo diagrama rodo fizinę aparatinę įrangą / kompiuterius, kuriuose diegiami programinės įrangos komponentai.

  • Duomenų srautų diagrama rodo, kaip duomenys juda per sistemą ir yra transformuojami.

  • Sekų diagrama naudojama parodyti, kaip protokolai, tokie kaip HTTP, veikia laiko ašyje.

  • Veiklos diagrama vaizduoja veiklų, kurias atlieka programinės įrangos sistema, darbo eigą, pavyzdžiui, kaip NPC DI.

Tinkamumo funkcijos sprendimams kaip kodui

Tinkamumo funkcijos (angl. fitness functions) yra objektyvūs automatizuoti patikrinimai, parašyti programavimo kodu, kurie tikrina, ar sprendimų laikomasi.

  • Tinkamumo funkcijos leidžia sprendimus išbandyti ir užtikrinti.

  • Sprendimų tinkamumo funkcijos gali labai padėti kokybės užtikrinimui, reguliaciniams procesams ir valdysenos tikslams.

Kaip tinkamumo funkcijos susijusios su sprendimais

Sprendimo įrašas dokumentuoja sprendimą, o tinkamumo funkcija sprendimą užtikrina.

  • Sprendimo pavyzdys: audito reikalavimams naudojame įvykių šaltinių modelį (angl. event sourcing).

  • Tinkamumo funkcijos pavyzdys: nuolatinės integracijos serveriu tikriname, ar visi būsenos pakeitimai privalo sukurti įvykius.

Kodėl tinkamumo funkcijos padeda sprendimams

Objektyvūs matavimai: tinkamumo funkcijos arba praeina, arba nepraeina, todėl darbas matomas ir aiškus.

Nuolatinis naudojimas: tinkamumo funkcijos yra jūsų gyvos taisyklės, vykdomos su kiekvienu įkėlimu (angl. commit) ir kūrimu.

Pasitikėjimas pertvarkant kodą: tinkamumo funkcijos automatiškai pagauna sprendimų taisyklių klaidas.

Mastelio keitimą atlaikanti valdysena: tinkamumo funkcijos užtikrina standartus nesukurdamos kliūčių.

Ar tinkamumo funkcijos gali naudoti dirbtinį intelektą?

Tinkamumo funkcijos sprendimams gali pasitelkti DI didžiuosius kalbos modelius (LLM), užduodamos klausimus apie jūsų darbą, pavyzdžiui, apie planus, kodą, schemas, API ir kita:

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.

Architektūros vienetų testavimas

ArchUnit: tikrinkite Java kodo architektūros taisykles naudodami bet kurią paprastą Java vienetų testų sistemą.

ArchUnitTS: tikrinkite TypeScript ir JavaScript kodo architektūros taisykles naudodami Jest, Vitest, Jasmine ir kt.

Sprendimų apsauginės priemonės pull request'ams

Decision Guardian automatiškai parodo tinkamus sprendimų įrašus tinkamu momentu – kai programuotojas aktyviai keičia kodą, kurį tie sprendimai apima. Užuot tikėjęsi, kad programuotojai prieš sujungdami perskaitys dokumentų aplanką, svarbus kontekstas pasirodo tiesiogiai pull request.

Tai veikia su bet kokio tipo sprendimų įrašais: architektūros sprendimais, duomenų sprendimais, atitikties sprendimais, klinikiniais ir medicininiais sprendimais, saugumo sprendimais ir kt.

Veikia su bet kuria CI sistema (GitLab, Jenkins, CircleCI) ir kaip pre-commit kabliukas. Atvirasis kodas. MIT licencija.

ADR Guard yra GitHub Action, kuris nepraleidžia pull request, kai stebimi kodo keliai pasikeičia nepridėjus ar neatnaujinus architektūros sprendimo įrašo. Atleidimai aiškūs: eilutė ADR-Exempt: su priežastimi praleidžia vartus ir įrašoma į užduoties santrauką. Nepriklauso nuo šablono, be priklausomybių. Atvirasis kodas. MIT licencija.

Daugiau informacijos

Įvadas:

Šablonai:

Išsamiau:

Įrankiai:

Konkrečių įmonių rekomendacijos:

Pavyzdžiai:

Vaizdo įrašai:

Tinklalaidės:

Knygos:

Taip pat žr.:

  • 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) - Nuo tiekėjo nepriklausomas, mašininiu būdu skaitomas YAML/JSON formatas sprendimams vaizduoti su aiškia argumentacija, prielaidomis, kognityvine būsena ir kompromisais. Papildo ADR pridėdamas struktūrizuotą, patikrinamą argumentaciją prie sprendimų dokumentacijos.