Architecture Decision Record

Arhitektuuriotsuse kirje (ADR)

Mallid, näited ja juhised arhitektuuriotsuste dokumenteerimiseks.

Arhitektuuriotsuse kirje (ADR) on dokument, mis jäädvustab olulise arhitektuuriotsuse koos selle konteksti ja tagajärgedega.

Tõlked: العربية, বাংলা, Cymraeg, Dansk, Deutsch, English, Ελληνικά, 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, 中文

Tee nende ressursside suhtes oma hoolsuskontroll enne, kui kasutad neid kriitilistes süsteemides.

Sisukord:

Mallid:

Näited:

Mis on arhitektuuriotsuse kirje?

Arhitektuuriotsuse kirje (ADR) on dokument, mis jäädvustab tehtud olulise arhitektuuriotsuse koos selle konteksti ja tagajärgedega.

Arhitektuuriotsus (AD) on tarkvaradisaini valik, mis käsitleb olulist nõuet.

Arhitektuuriotsuste logi (ADL) on kõigi konkreetse projekti (või organisatsiooni) jaoks loodud ja hooldatud ADR-ide kogum.

Arhitektuuriliselt oluline nõue (ASR) on nõue, millel on mõõdetav mõju tarkvarasüsteemi arhitektuurile.

Kõik see kuulub arhitektuuriteadmiste halduse (AKM) teema alla.

Selle dokumendi eesmärk on anda kiire ülevaade ADR-idest, kuidas neid kirjutada ja kust leida rohkem teavet.

Lühendid:

  • AD: arhitektuuriotsus

  • ADL: arhitektuuriotsuste logi

  • ADR: arhitektuuriotsuse kirje

  • AKM: arhitektuuriteadmiste haldus

  • ASR: arhitektuuriliselt oluline nõue

Kuidas ADR-e kasutama hakata

ADR-idega alustamiseks räägi oma meeskonnakaaslastega järgmistest valdkondadest.

Otsuste tuvastamine:

  • Kui kiireloomuline ja kui oluline on AD?

  • Kas otsus tuleb teha nüüd või saab oodata, kuni rohkem on teada?

  • Isiklik ja kollektiivne kogemus ning tunnustatud disainimeetodid ja -tavad võivad aidata otsuseid tuvastada.

  • Pea ideaalis otsuste tagavara (backlog), mis täiendab tootetagavara.

Otsuste tegemine:

  • Otsuste tegemiseks on mitmeid tehnikaid, sealhulgas üldised tehnikad ja tarkvaraarhitektuurile spetsiifilised tehnikad. Üks näide on dialoogikaardistamine.

  • Rühmaotsuste tegemine on aktiivne uurimisteema.

Otsuste jõustamine ja täideviimine:

  • Kuna AD-sid kasutatakse tarkvaradisainis, tuleb neist teavitada süsteemi rahastavaid, arendavaid ja käitavaid huvirühmi ning need peavad need heaks kiitma.

  • Arhitektuuriteadlikud kodeerimisstiilid ja arhitektuuriga seotud küsimustele ja otsustele keskendunud koodiülevaatused on kaks seotud tava.

  • AD-sid tuleks (uuesti) kaaluda ka tarkvarasüsteemi moderniseerimisel tarkvara evolutsiooni käigus.

Otsuste jagamine (valikuline):

  • Paljud AD-d kordavad end projektiüleselt.

  • Seetõttu võib varasemate otsuste kogemus, nii hea kui halb, olla väärtuslik taaskasutatav vara, kui kasutada selgesõnalist teadmistehalduse strateegiat.

Otsuste dokumenteerimine:

  • Otsuste jäädvustamiseks on palju malle ja tööriistu.

  • Vaata agiilset kogukonda, näiteks M. Nygardi ADR-e.

  • Vaata traditsioonilisi tarkvaratehnika ja arhitektuuridisaini protsesse, näiteks IBM UMF ja CapitalOne'i Tyree ning Akermani pakutud tabeli paigutust.

Lisateave:

Kuidas ADR-e kasutama hakata tööriistadega

  • MySpec — Automatiseeritud spetsifikatsiooni- ja arhitektuuriotsuste platvorm, mis struktureerib projekti põhikirja, tehnilise arhitektuuri ja ADR-id puhtaks Markdowniks, mida pakutakse MCP kaudu.

Sa võid ise valida, kuidas tööriistadega ADR-idega alustada.

Näiteks:

  • Kui sulle meeldib Google Drive ja veebipõhine redigeerimine, võid luua Google'i dokumendi või Google'i tabeli.

  • Kui sulle meeldib lähtekoodi versioonihaldus nagu git, võid iga ADR-i jaoks luua faili.

  • Kui sulle meeldivad projektiplaneerimise tööriistad nagu Atlassian Jira, võid kasutada nende planeerimisjälgijat.

  • Kui sulle meeldivad wikid nagu MediaWiki, võid luua ADR-i wiki.

Kuidas ADR-e kasutama hakata gitiga

Kui sulle meeldib git-versioonihaldus, siis nii alustame meie ADR-idega gitiga tüüpilises lähtekoodiga tarkvaraprojektis.

Loo oma ADR-failide jaoks kaust:

$ mkdir adr

Loo iga ADR-i jaoks tekstifail, näiteks database.txt:

$ vi database.txt

Kirjuta ADR-i, mida tahes soovid. Ideid leiad selle hoidla mallidest.

Commit'i ADR-id oma git-hoidlasse.

Claude Code'i oskused ADR-ide jaoks

See hoidla sisaldab kaht Claude Code'i oskust kaustas skills/, et tehisintellektil põhinev kodeerimisagent saaks ADR-e kirjutada ja hoida nii, nagu see projekt soovitab:

  • architecture-decision-record-skill — üldotstarbeline, igaühele, kes kirjutab ADR-i mis tahes projektis. Aitab otsustada, kas otsus vajab ADR-i, loob kausta adr/ või decisions/, nimetab faili, valib malli üheteistkümnest kaasasolevast karkassist ja kirjutab korralikud konteksti, otsuse ja tagajärgede jaotised.

  • architecture-decision-record-maintainer-skill — spetsiaalselt selle hoidla haldajatele. Dokumenteerib hoidla ülesehituse, README ja locales peegeldamise tava ning täpsed sammud uue malli, näite või tööriistalingi lisamiseks.

Oskuse kasutamiseks kopeeri selle kaust oma töötava hoidla juurkausta .claude/skills/ (või kausta ~/.claude/skills/, et see oleks saadaval igas projektis) ning palu seejärel Claude Code'il ADR kirjutada või üle vaadata.

Failinimede konventsioonid

Kui otsustad kirjutada ADR-e lihttekstifailidena, võib olla kasulik kehtestada oma ADR-i failinimede konventsioon.

Eelistame kindla vorminguga failinimede konventsiooni.

Näited:

  • choose-database.md

  • format-timestamps.md

  • manage-passwords.md

  • handle-exceptions.md

Meie failinimede konventsioon:

  • Nimi on käskiva kõneviisi verbifraas olevikus. See parandab loetavust ja sobib meie commit-sõnumite vorminguga.

  • Nimi kasutab väiketähti ja sidekriipse (nagu selles hoidlas). See on tasakaal loetavuse ja süsteemide kasutatavuse vahel.

  • Laiend on markdown. See võib olla mugav lihtsa vormindamise jaoks.

Soovitused heade ADR-ide kirjutamiseks

Hea ADR-i tunnused:

  • Põhjendus: selgita, miks AD-d tehakse. See võib sisaldada konteksti (vt allpool), erinevate võimalike valikute plusse ja miinuseid, funktsioonide võrdlusi, kulu-tulu arutelusid ja nii edasi.

  • Konkreetne: iga ADR peaks käsitlema ühte AD-d, mitte mitut AD-d.

  • Ajatempliga: märgi, millal iga ADR-i kirje kirjutati. See on eriti oluline aspektide puhul, mis võivad aja jooksul muutuda, nagu kulud, ajakava, laiendamine ja nii edasi.

  • Muutumatu: ära muuda ADR-is olemasolevat teavet. Muuda selle asemel ADR-i uue teabe lisamisega või asenda ADR uue ADR-i loomisega.

Hea "Konteksti" jaotise tunnused ADR-is:

  • Kirjeldab organisatsiooni olukorda ja ärilisi prioriteete.

  • Sisaldab põhjendust ja kaalutlusi, mis põhinevad meeskonna sotsiaalsel ja tehnilisel koosseisul.

  • Sisaldab asjakohaseid kompromisse, väljendatuna vajaduste ja eesmärkidega sobivates terminites.

Hea "Tagajärgede" jaotise tunnused ADR-is:

  • Kirjeldab, mis otsuse tegemisest järgneb. See võib sisaldada mõjusid, tulemusi, tulemeid, järeltegevusi ja nii edasi.

  • Sisaldab teavet järgnevate ADR-ide kohta. On suhteliselt tavaline, et üks ADR tekitab vajaduse veel ADR-ide järele. Näiteks kui ADR teeb suure, ülekaaluka valiku, võib see tekitada vajaduse väiksemate otsuste järele.

  • Sisaldab tagantjärele läbivaatuse protsessi. On tavaline, et meeskonnad vaatavad iga ADR-i üle kuu aja pärast, võrdlevad ADR-i teavet sellega, mis tegelikult juhtus, ning õpivad ja arenevad sellest.

Uus ADR võib asendada eelmise ADR-i:

  • Kui tehakse AD, mis asendab või muudab kehtetuks eelmise ADR-i, tuleks kirjutada uus ADR

ADR-i näidismallid

ADR-i näidismallid, mida oleme võrgust kokku kogunud:

Meeskonnatöö nõuanded ADR-idele

Kui kaalute otsusekirjete kasutamist oma meeskonnas, siin on mõned nõuanded, mida õppisime mitme meeskonnaga töötades.

On võimalus juhtida meeskonnaliikmeid, rääkides "miks"-ist, mitte jõustades "mida". Näiteks on otsusekirjed viis, kuidas meeskonnad saavad nutikamalt mõelda ja paremini suhelda. Kui otsusekirjed on vaid tagantjärele jõustatav paberimajanduse nõue, pole neil väärtust.

Mõned meeskonnad eelistavad nime "otsused" tugevalt lühendile "ADR". Kui mõned meeskonnad kasutavad kausta nimena "decisions", süttib lamp ja meeskonnad hakkavad kausta panema rohkem teavet, nagu tarnijaotsused, plaaniotsused, ajakavaotsused ja nii edasi. Kõigi nende teabeliikide jaoks saab kasutada sama malli. Eeldame, et inimesed õpivad sõnaga ("otsus") kiiremini kui lühendiga ("ADR"), et sõna "kirje" väljajätmine annab rohkem motivatsiooni pooleliolevat tööd kirjutada ning et mõned arendajad ja mõned juhid ei salli sõna "arhitektuur".

Teoorias on muutumatus ideaalne. Praktikas töötas meie meeskonnale paremini muudetavus. Lisame olemasolevasse ADR-i uut teavet kuupäevatempli ja märkusega, et teave tuli pärast otsust. See lähenemine viib "elava dokumendini", mida me kõik saame uuendada. Tüüpilised uuendused tulevad teabe saamisest uute meeskonnaliikmete, uute pakkumiste, meie kasutuse tegelike tulemuste või hilisemate kolmandate osapoolte muudatuste tõttu, nagu tarnija funktsioonid, hinnaplaanid ja litsentsilepingud.

Meeskonnatöö küsimused ADR-ide jaoks

Kes võib ADR-e kirjutada?

Kaalu valdkondi nagu konkreetsed inimesed, konkreetsed rollid, konkreetsed meeskonnad, konkreetsed osakonnad. Kaalu ka seda, kas on inimesi, rolle, meeskondi või osakondi, kes saavad ADR-e tellida, st paluda, et keegi teine kirjutaks ADR-i.

Näidisvastus: igaüks meie organisatsioonis, kes on lugenud arhitektuuriotsuse kirjete README-lehte, võib ADR-i välja pakkuda, st hakata kirjutama ja jagada seda meeskonnaga.

Mis õigustab ADR-i algatamist?

Kaalu valdkondi nagu see, kuidas organisatsiooni meeskonnad töötavad, tarkvarasüsteemide struktuur, meeskondadevaheline koordineerimine, pikaajaline hooldatavus, välised liidesed ja see, keda soovid kasu saama.

Näidisvastus: tahame ADR-i kirjutada, kui soovime, et tulevased arendajad mõistaksid meie tegevuse "miks"-i.

Mis ei õigusta ADR-i algatamist?

Kaalu valdkondi nagu otsused, mis ei ole arhitektuuri kohta, otsused, mis on triviaalsed, sest neil on minimaalne risk, on iseseisvad või piirduvad ühe arendajaga, otsused, mis on juba mujal täielikult kaetud standardites, poliitikates, dokumentatsioonis ja nii edasi, või otsused, mis on ajutised, nagu ajutised lahendused, kontseptsiooni tõestused ja katsed.

Näidisvastus: tahame ADR-i vahele jätta, kui otsus on ulatuselt, ajalt, riskilt ja kuludelt piiratud või on juba mujal kaetud.

Mis on ADR-i elutsükkel?

Kaalu valdkondi nagu kirjutamisprotsess, uurimisprotsess, otsustusprotsess, teostusprotsess ja väljaviimisprotsess. Kaalu, kuidas jälgid ADR-i elutsüklit aja jooksul, näiteks kuidas liigutad ADR-i ühest olekust järgmisse ja kuidas sellest huvirühmi teavitad.

Näidisvastus: tahame, et ADR-idel oleks viis elutsükli etappi: Initiating → Researching → Evaluating → Implementing → Maintaining → Sunsetting.

Millised on ADR-i elutsükli etappide kriteeriumid?

Kaalu valdkondi nagu ADR-ide aktsepteerimiskriteeriumid, st kuidas me teame, et ADR on piisavalt hea, et liikuda ühest elutsükli etapist järgmisse? Kas probleem on selgelt kirjeldatud? Kas alternatiive on kaalutud? Kas kompromissid on hästi mõistetud ja dokumenteeritud? Kas kogu asjakohane kontekst on olemas? Kas kõik asjaomased huvirühmad on kaasatud? Kas kogu tagasiside on arvesse võetud?

Näidisvastus: tahame, et aktiivne meeskond 1) lõpetaks uurimise, 2) lõpetaks hindamise, 3) avaldaks ADR-i ettepanekud huvirühmadele kommentaaride taotluse ja ühe nädala ajapiiriga ning 4) kui kõik huvirühmade kommentaarid on arvesse võetud ja käsitletud, laseks huvirühmadel ADR-i üle hääletada.

Millised rollid ja vastutusalad ADR-idega suhestuvad?

Kaalu rolle nagu esitaja, uurija, hindaja, ülevaataja, kinnitaja ja hooldaja. Kaalu vastutusalasid nagu huvirühmadega suhtlemine, ootuste täitmise tagamine, veebisaidil või intranetis jagamine ja töö perioodiline ülevaatamine, eriti kui on asjakohaseid muudatusi.

Näidisvastus: tahame, et igal ADR-il oleks alati peamine omanik, teisene omanik ja vastutav meeskond. Nad vastutavad suhtluse, avaldamise, hoolduse, vähemalt iga-aastase perioodilise ülevaatuse ja vajaduse korral lõpliku väljaviimise eest.

Kuidas juhtimine ADR-idega suhestub?

Kaalu valdkondi nagu organisatsiooni töökorraldus, erilised vastavusvajadused nagu juriidilised aspektid või personaliaspektid ja kuidas soovid käsitleda konsensust versus konflikti versus eskaleerimist. Kas on valdkondi, inimesi või meeskondi, kellel võib olla teistest suurem mõju, näiteks võim kinnitada, hääletada või vetostada ADR-idega seoses?

Näidisvastus: ADR-i juhtimine järgib seda prioriteedijärjekorda: tegevjuht, tehnikadirektor, juriidiline direktor, ADR-i teostav meeskond, meeskonna kõige teadlikum ekspert ADD-i osas. Kellelgi pole juhtimisõigust, välja arvatud juhul, kui see on ADR-is kirjeldatud.

Millised põhimõtted ADR-idega suhestuvad?

Kaalu valdkondi, mis hõlmavad organisatsiooni töökorraldust, nagu kiire või aeglane liikumine, otsuste konsensus versus otsuste konflikt, riskieelistus versus ohutuseelistus ning avalik arutelu versus privaatne arutelu.

Näidisvastus: kasutame juhtimispõhimõtteid tegutsemiskallak (bias for action), ole eri meelt ja pühendu (disagree-and-commit), 70% teabest on piisav otsuste jaoks, mida on lihtne tagasi pöörata ja lihtne isoleerida, ning avalik töötamine, välja arvatud konfidentsiaalne teave, nagu on kirjeldatud meie organisatsiooni konfidentsiaalsuslepingutes.

ADR-ide järgmise sammu kontseptsioonid

Arc42 vastab kahele küsimusele pragmaatiliselt ja seda saab kohandada sinu vajadustele. Mida peaksid oma arhitektuuri kohta dokumenteerima/edastama? Kuidas peaksid dokumenteerima/edastama? Arc42 sisaldab arhitektuuriotsuste kirjeid ning juhiseid eesmärkide, piirangute, kontekstide, kvaliteedi, riskide ja muu kohta.

C4 mudel on kergesti õpitav, arendajasõbralik lähenemine tarkvaraarhitektuuri diagrammide koostamiseks. C4 on hierarhiliste diagrammide komplekt konteksti, konteinerite, komponentide ja koodi jaoks, lisaks toetavad diagrammid süsteemimaastiku, dünaamika ja juurutuse jaoks.

Arhitektuuridiagrammid, vaated ja vaatepunktid

Arhitektuuridiagrammi nimetatakse "arhitektuurivaateks".

"Arhitektuurivaade" on "arhitektuuri vaatepunkti" eksemplar.

"Arhitektuuri vaatepunkt" arvestab kindla sihtrühmaga, kellel on kindlad mured.

Arhitektuuri vaatepunktide, vaadete ja diagrammide näited:

Seotud diagrammid:

  • Kasutusjuhtumi diagramm näitab juhtkonnale/klientidele kasutusjuhtumeid, mis eelnevad nõuetele, mis omakorda eelnevad tarkvaraarhitektuurile.

  • Juurutusdiagramm näitab füüsilist riistvara/arvuteid, kuhu tarkvarakomponendid juurutatakse.

  • Andmevoo diagramm näitab, kuidas andmed süsteemis liiguvad ja muundatakse.

  • Jadadiagrammi kasutatakse, et näidata, kuidas protokollid nagu HTTP ajateljel toimivad.

  • Tegevusdiagramm kujutab tarkvarasüsteemi tegevuste töövoogu, näiteks NPC tehisintellekti.

Otsuste sobivusfunktsioonid koodina

Sobivusfunktsioon (fitness function) on objektiivne, automatiseeritud kontroll, mis on kirjutatud programmeerimiskoodina ja mis kontrollib, et otsust järgitakse.

  • Sobivusfunktsioonid muudavad otsused testitavaks ja tagatavaks.

  • Otsuste sobivusfunktsioonid võivad suuresti aidata kvaliteeditagamisel, regulatiivsetes protsessides ja juhtimiseesmärkides.

Kuidas sobivusfunktsioonid ja otsused seostuvad

Otsusekirje dokumenteerib otsuse; sobivusfunktsioon jõustab selle otsuse.

  • Näide otsusest: kasuta auditinõuete jaoks sündmuste allikat (event sourcing).

  • Näide sobivusfunktsioonist: kasuta pidevintegratsiooni serverit, et testida, et iga olekumuudatus peab genereerima sündmuse.

Miks sobivusfunktsioonid otsuseid aitavad

Objektiivne mõõtmine: sobivusfunktsioon kas läbib või ebaõnnestub, seega on töö nähtav ja selge.

Pidev kasutus: sobivusfunktsioon on elav reegel ja jookseb igal commitil ja ehitusel.

Kindlus refaktoreerimisel: sobivusfunktsioon tabab otsusereeglite vastu eksimisi automaatselt.

Skaleeritav juhtimine: sobivusfunktsioon jõustab standardeid kitsaskohti tekitamata.

Kas sobivusfunktsioonid saavad kasutada tehisintellekti?

Sobivusfunktsioon võib otsuste jaoks kasutada tehisintellekti LLM-i, esitades küsimusi meie töö kohta, näiteks plaanid, kood, skeemid, API-d ja nii edasi:

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.

Arhitektuuri ühikutestid

ArchUnit: kontrolli Java koodi arhitektuurireegleid tavalise Java ühikutestide raamistikuga.

ArchUnitTS: kontrolli TypeScripti koodi ja JavaScripti koodi arhitektuurireegleid Jesti, Vitesti, Jasmine'i ja teistega.

Otsuste kaitsepiirded tõmbepäringute jaoks

Decision Guardian toob õiged otsusekirjed nähtavale õigel hetkel, nimelt siis, kui arendaja muudab aktiivselt koodi, mida need otsused hõlmavad. Selle asemel, et loota, et arendajad loevad enne liitmist dokumendikausta, ilmub asjakohane kontekst otse tõmbepäringule.

See sobib igat liiki otsusekirjetele: arhitektuuriotsused, andmeotsused, vastavusotsused, kliinilised ja meditsiinilised otsused, turvaotsused ja palju muud.

Töötab iga CI-süsteemiga (GitLab, Jenkins, CircleCI) ja pre-commit-konksuna. Avatud lähtekood. MIT-litsents.

ADR Guard on GitHubi tegevus (Action), mis lükkab tõmbepäringu tagasi, kui jälgitavad kooditeed muutuvad ilma, et lisataks või uuendataks arhitektuuriotsuse kirjet. Erandid on selged: põhjendusega ADR-Exempt: rida laseb värava läbi ja kirjutatakse töö kokkuvõttesse. Mallist sõltumatu, sõltuvusteta. Avatud lähtekood. MIT-litsents.

Lisateave

Sissejuhatus:

Mallid:

Põhjalikult:

Tööriistad:

Ettevõttespetsiifilised juhised:

Näited:

Videod:

Taskuhäälingud:

Raamatud:

Vaata ka:

  • 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) - Tarnijaneutraalne, masinloetav YAML/JSON-vorming otsuste esitamiseks selgesõnalise põhjenduse, eelduste, kognitiivse oleku ja kompromissidega. Täiendab ADR-e, lisades otsuste dokumentatsioonile struktureeritud, kontrollitava põhjenduse.