Architecture Decision Record

Zapis arhitekturne odluke (ADR)

Predlošci, primjeri i smjernice za bilježenje arhitekturnih odluka.

Zapis arhitekturne odluke (ADR) je dokument koji bilježi važnu arhitekturnu odluku zajedno s njezinim kontekstom i posljedicama.

Prijevodi: العربية, বাংলা, 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, 中文

Sami provedite dubinsku provjeru ovih resursa prije nego što ih koristite u bilo kojim kritičnim sustavima.

Sadržaj:

Predlošci:

Primjeri:

Što je zapis arhitekturne odluke?

Zapis arhitekturne odluke (ADR) je dokument koji bilježi važnu arhitekturnu odluku zajedno s njezinim kontekstom i posljedicama.

Arhitekturna odluka (AD) je odabir u dizajnu softvera koji odgovara na značajan zahtjev.

Dnevnik arhitekturnih odluka (ADL) je zbirka svih ADR-ova stvorenih i održavanih za određeni projekt (ili organizaciju).

Arhitekturno značajan zahtjev (ASR) je zahtjev koji ima mjerljiv učinak na arhitekturu softverskog sustava.

Sve to spada u područje upravljanja arhitekturnim znanjem (AKM).

Cilj ovog dokumenta je pružiti brz pregled ADR-ova, kako ih stvarati i gdje potražiti više informacija.

Kratice:

  • AD: arhitekturna odluka

  • ADL: dnevnik arhitekturnih odluka

  • ADR: zapis arhitekturne odluke

  • AKM: upravljanje arhitekturnim znanjem

  • ASR: arhitekturno značajan zahtjev

Kako početi koristiti ADR

Za početak korištenja ADR-ova razgovarajte sa suradnicima o ovim područjima.

Identifikacija odluka:

  • Koliko je AD hitna i koliko važna?

  • Mora li se donijeti sada ili može pričekati dok se ne sazna više?

  • I osobno i kolektivno iskustvo, kao i priznate metode i prakse dizajna, mogu pomoći pri identifikaciji odluka.

  • Idealno održavajte popis odluka za donošenje koji nadopunjuje popis zadataka proizvoda.

Donošenje odluka:

  • Postoji niz tehnika donošenja odluka, i općenitih i specifičnih za softversku arhitekturu, na primjer mapiranje dijaloga.

  • Grupno donošenje odluka aktivna je istraživačka tema.

Provedba i nametanje odluka:

  • AD-ovi se koriste u dizajnu softvera; stoga se moraju komunicirati dionicima sustava koji ga financiraju, razvijaju i upravljaju njime te ih oni moraju prihvatiti.

  • Arhitekturno očiti stilovi kodiranja i pregledi koda koji se usredotočuju na arhitekturne brige i odluke dvije su povezane prakse.

  • AD-ove također treba (ponovno) razmotriti pri modernizaciji softverskog sustava u softverskoj evoluciji.

Dijeljenje odluka (neobavezno):

  • Mnoge se AD-ove ponavljaju kroz projekte.

  • Stoga iskustva s prošlim odlukama, i dobra i loša, mogu biti vrijedna ponovno iskoristiva imovina pri primjeni eksplicitne strategije upravljanja znanjem.

Dokumentiranje odluka:

  • Postoje mnogi predlošci i alati za bilježenje odluka.

  • Pogledajte agilne zajednice, npr. ADR-ove M. Nygarda.

  • Pogledajte tradicionalne procese softverskog inženjerstva i arhitekturnog dizajna, npr. tablične rasporede koje predlažu IBM UMF te Tyree i Akerman iz CapitalOnea.

Za više informacija:

Kako početi koristiti ADR s alatima

  • MySpec — Platforma za automatiziranu specifikaciju i arhitekturne odluke koja strukturira projektni ustav, tehničku arhitekturu i ADR-ove u čist Markdown poslužen putem MCP-a.

ADR-ove s alatima možete početi koristiti na bilo koji način koji želite.

Na primjer:

  • Ako volite koristiti Google Drive i mrežno uređivanje, možete stvoriti Google Doc ili Google Sheet.

  • Ako volite koristiti kontrolu verzija izvornog koda, poput gita, možete stvoriti datoteku za svaki ADR.

  • Ako volite koristiti alate za planiranje projekata, poput Atlassian Jire, možete koristiti alat za praćenje planiranja.

  • Ako volite koristiti wikije, poput MediaWikija, možete stvoriti ADR wiki.

Kako početi koristiti ADR s gitom

Ako volite koristiti git kontrolu verzija, evo kako mi volimo početi koristiti ADR-ove s gitom za tipičan softverski projekt s izvornim kodom.

Stvorite direktorij za ADR datoteke:

$ mkdir adr

Za svaki ADR stvorite tekstualnu datoteku, poput choose-database.md:

$ vi choose-database.md

Napišite što god želite u ADR. Pogledajte predloške u ovom repozitoriju za ideje.

Commitajte ADR u svoj git repozitorij.

Claude Code vještine za ADR-ove

Ovaj repozitorij isporučuje dvije Claude Code vještine (skills) u direktoriju skills/ kako bi AI agent za programiranje mogao pisati i održavati ADR-ove na način koji ovaj projekt preporučuje:

  • architecture-decision-record-skill — opće namjene, za svakoga tko piše ADR-ove u bilo kojem projektu. Pomaže odlučiti treba li odluka ADR, stvara direktorij adr/ ili decisions/, imenuje datoteku, odabire predložak iz jedanaest priloženih skica i piše čvrste odjeljke Kontekst/Odluka/Posljedice.

  • architecture-decision-record-maintainer-skill — posebno za održavatelje ovog repozitorija. Dokumentira raspored repozitorija, konvenciju zrcaljenja README/locales i točne korake za dodavanje novog predloška, primjera ili poveznice na alat.

Za korištenje vještine kopirajte njezinu mapu u .claude/skills/ u korijenu repozitorija u kojem radite (ili u ~/.claude/skills/ kako bi bila dostupna u svim projektima), a zatim zamolite Claude Code da napiše ili pregleda ADR.

Konvencije imenovanja datoteka za ADR

Ako odlučite stvarati svoje ADR-ove pomoću tipičnih tekstualnih datoteka, možda ćete htjeti osmisliti vlastitu konvenciju imenovanja datoteka za ADR.

Preferiramo konvenciju imenovanja datoteka koja ima određeni format.

Primjeri:

  • choose-database.md

  • format-timestamps.md

  • manage-passwords.md

  • handle-exceptions.md

Naša konvencija imenovanja datoteka:

  • Naziv sadrži glagolsku frazu u imperativu u sadašnjem vremenu. To pomaže čitljivosti i odgovara našem formatu poruka commita.

  • Naziv koristi mala slova i crtice (kao i ovaj repozitorij). To je ravnoteža između čitljivosti i upotrebljivosti sustava.

  • Ekstenzija je markdown. To može biti korisno za jednostavno oblikovanje.

Savjeti za pisanje dobrih ADR-ova

Karakteristike dobrog ADR-a:

  • Obrazloženje: Objasnite razloge za konkretnu AD. To može uključivati kontekst (vidi dolje), prednosti i nedostatke različitih mogućih izbora, usporedbe značajki, rasprave o trošku i koristi i više.

  • Specifičnost: Svaki ADR trebao bi biti o jednoj AD, a ne o više AD-ova.

  • Vremenske oznake: Navedite kada je napisana svaka stavka u ADR-u. To je osobito važno za aspekte koji se mogu mijenjati tijekom vremena, kao što su troškovi, rasporedi, skaliranje i slično.

  • Nepromjenjivost: Ne mijenjajte postojeće informacije u ADR-u. Umjesto toga dopunite ADR dodavanjem novih informacija ili zamijenite ADR stvaranjem novog ADR-a.

Karakteristike dobrog odjeljka „Kontekst“ u ADR-u:

  • Objasnite situaciju svoje organizacije i poslovne prioritete.

  • Uključite obrazloženje i razmatranja temeljena na društvenom i vještinskom sastavu vaših timova.

  • Uključite relevantne prednosti i nedostatke i opišite ih izrazima koji su u skladu s vašim potrebama i ciljevima.

Karakteristike dobrog odjeljka „Posljedice“ u ADR-u:

  • Objasnite što slijedi iz donošenja odluke. To može uključivati učinke, ishode, izlaze, nastavke i više.

  • Uključite informacije o svim naknadnim ADR-ovima. Relativno je uobičajeno da jedan ADR potakne potrebu za više ADR-ova, na primjer kada jedan ADR donosi veliki sveobuhvatni izbor koji zauzvrat stvara potrebe za više manjih odluka.

  • Uključite sve procese pregleda nakon akcije. Tipično je da timovi pregledavaju svaki ADR mjesec dana kasnije, kako bi usporedili informacije iz ADR-a s onim što se dogodilo u stvarnoj praksi, da bi učili i rasli.

Novi ADR može zauzeti mjesto prethodnog ADR-a:

  • Kada se donese AD koja zamjenjuje ili poništava prethodni ADR, treba stvoriti novi ADR

Primjeri predložaka za ADR

Primjeri predložaka za ADR prikupljeni s interneta:

Savjeti za timski rad za ADR

Ako razmišljate o korištenju zapisa odluka sa svojim timom, evo nekoliko savjeta koje smo naučili radeći s mnogim timovima.

Imate priliku voditi svoje suradnike zajedničkim razgovorom o „zašto“, umjesto da naređujete „što“. Na primjer, zapisi odluka način su na koji timovi mogu pametnije razmišljati i bolje komunicirati; zapisi odluka nisu vrijedni ako su samo naknadno nametnut papirološki zahtjev.

Neki timovi mnogo više vole naziv „odluke“ nego kraticu „ADR“. Kada neki timovi koriste naziv direktorija „decisions“, kao da se upali žarulja i tim počne stavljati više informacija u direktorij, poput odluka o dobavljačima, odluka o planiranju, odluka o rasporedima i tako dalje. Sve te vrste informacija mogu koristiti isti predložak. Pretpostavljamo da ljudi brže uče uz riječi („odluke“) nego uz kratice („ADR-ovi“), da su ljudi motiviraniji pisati dokumente o radu u tijeku kada se ukloni riječ „zapis“, a također da neki programeri i neki menadžeri ne vole riječ „arhitektura“.

U teoriji je nepromjenjivost idealna. U praksi je promjenjivost za naše timove radila bolje. Umećemo nove informacije u postojeći ADR, s vremenskom oznakom i napomenom da su informacije stigle nakon odluke. Ovakav pristup vodi do „živog dokumenta“ koji svi možemo ažurirati. Tipična ažuriranja događaju se kada dobijemo informacije zahvaljujući novim suradnicima, novim ponudama ili stvarnim rezultatima naše upotrebe, ili nakon naknadnih promjena trećih strana kao što su mogućnosti dobavljača, cjenovni planovi, licencni ugovori i tako dalje.

Pitanja za timski rad za ADR-ove

Tko može stvoriti ADR?

Razmotrite područja poput određenih osoba, određenih uloga, određenih timova ili određenih odjela; razmotrite i postoje li osobe, uloge, timovi ili odjeli koji mogu naručiti ADR, odnosno zatražiti ga da ga napiše netko drugi.

Primjer odgovora: Svaka osoba u našoj organizaciji koja je pročitala stranicu README zapisa arhitekturne odluke može predložiti ADR, što znači da ga može početi pisati i podijeliti s timom.

Što opravdava pokretanje ADR-a?

Razmotrite područja poput načina rada tima u vašoj organizaciji, strukture vašeg softverskog sustava, koordinacije među timovima, dugoročnog održavanja, vanjskih sučelja, tko želite da ima koristi i slično.

Primjer odgovora: Želimo stvoriti ADR kada želimo da budući programeri razumiju „zašto“ onoga što radimo.

Što opravdava nepokretanje ADR-a?

Razmotrite područja poput odluka koje nisu o arhitekturi ili su sitne, primjerice minimalnog rizika, samostalne ili za jednog programera, ili su već u potpunosti pokrivene drugdje, primjerice standardima, politikama ili dokumentacijom, ili su privremene, primjerice zaobilazna rješenja, dokazi koncepta ili eksperimenti.

Primjer odgovora: Želimo preskočiti ADR kada je odluka ograničena opsegom, vremenom, rizikom i troškom ili je već pokrivena drugdje.

Koji je životni ciklus ADR-a?

Razmotrite područja poput procesa stvaranja, procesa istraživanja, procesa donošenja odluke, procesa implementacije i procesa povlačenja. Razmotrite kako pratiti životni ciklus ADR-a tijekom vremena, na primjer kako premjestiti ADR iz jednog stanja u sljedeće te kako to priopćiti dionicima.

Primjer odgovora: Želimo da ADR ima pet faza životnog ciklusa: Pokretanje → Istraživanje → Vrednovanje → Implementacija → Održavanje → Povlačenje.

Koji su kriteriji za korake životnog ciklusa ADR-a?

Razmotrite područja poput kriterija prihvaćanja ADR-a, odnosno kako znate da je dovoljno dobar za prelazak iz jednog koraka životnog ciklusa u sljedeći? Je li problem jasno artikuliran? Jesu li razmotrene alternative? Jesu li kompromisi dovoljno dobro shvaćeni i dokumentirani? Je li sav relevantni kontekst na mjestu? Jesu li uključeni svi relevantni dionici? Je li uključena sva povratna informacija?

Primjer odgovora: Želimo da dionici glasaju o ADR-u kada je aktivni tim 1) dovršio svoje istraživanje, 2) dovršio svoje vrednovanje, 3) objavio prijedlog ADR-a dionicima sa zahtjevom za komentare i rokom od jednog tjedna, 4) svi komentari dionika su ugrađeni i obrađeni.

Koje uloge i odgovornosti djeluju s ADR-om?

Razmotrite uloge poput predlagatelja, istraživača, ocjenjivača, recenzenta, odobravatelja, održavatelja i slično. Razmotrite odgovornosti poput komunikacije s dionicima, osiguravanja ispunjenja očekivanja, dijeljenja na web-mjestu ili intranetu te povremenog pregleda rada, osobito kada se dogode relevantne promjene.

Primjer odgovora: Želimo da svaki ADR uvijek ima primarnu kontakt osobu, sekundarnu kontakt osobu i odgovorni tim; oni su odgovorni za komunikaciju, objave, održavanje, povremeni pregled najmanje jednom godišnje i eventualno povlačenje prema potrebi.

Kako upravljanje (governance) djeluje s ADR-om?

Razmotrite područja poput načina rada vaše organizacije, posebnih potreba usklađenosti, primjerice za pravne aspekte ili aspekte ljudskih resursa, kako želite postupati s konsenzusom naspram sukoba naspram eskalacije. Postoje li područja, osobe ili timovi koji mogu imati veći utjecaj od drugih u pogledu ADR-a, primjerice mogu li ga odobriti, glasati o njemu ili staviti veto?

Primjer odgovora: Upravljanje ADR-om je ovim redoslijedom prioriteta: izvršni direktor, tehnički direktor, pravni direktor, tim koji implementira ADR, stručnjaci u timu koji najbolje poznaju AD. Nitko drugi nema upravljačku ovlast osim ako je opisano u ADR-u.

Koja načela djeluju s ADR-om?

Razmotrite područja poput načina rada vaše organizacije koji uključuju brzo kretanje naspram sporog kretanja, za konsenzus odluka naspram sukoba odluka, te za sklonosti riziku naspram sklonosti sigurnosti, javnu raspravu naspram privatne rasprave i slično.

Primjer odgovora: Koristimo načela vodstva sklonosti djelovanju, neslaganja i predanosti (disagree-and-commit), 70 % procjene dovoljno su dobre za lako reverzibilne i lako izolirane odluke, te javne načine rada uz iznimku povjerljivih informacija kako je opisano u ugovoru o povjerljivosti naše organizacije.

Koncepti sljedećeg koraka za ADR-ove

Arc42 pragmatično odgovara na dva pitanja i može se prilagoditi vašim specifičnim potrebama. Što vrijedi dokumentirati/komunicirati o vašoj arhitekturi? Kako to vrijedi dokumentirati/komunicirati? Arc42 uključuje zapise arhitekturnih odluka kao i smjernice o ciljevima, ograničenjima, kontekstu, kvaliteti, rizicima i drugome.

Model C4 je lako naučiv, programerima prijazan pristup dijagramiranju softverske arhitekture. C4 je hijerarhijski skup dijagrama za kontekst, kontejnere, komponente, kod te dodatni dijagrami za krajolik sustava, dinamiku i implementaciju.

Arhitekturni dijagrami, pogledi i gledišta

Arhitekturni dijagram naziva se „arhitekturni pogled“.

„Arhitekturni pogled“ je instanca „arhitekturnog gledišta“.

„Arhitekturno gledište“ ima određenu publiku s određenim interesima.

Primjeri arhitekturnih gledišta, pogleda i dijagrama:

Povezani dijagrami:

  • Dijagram slučajeva uporabe prikazuje slučajeve uporabe upravi/klijentima, što prethodi zahtjevima, koji prethode softverskoj arhitekturi.

  • Dijagram razmještaja prikazuje fizički hardver/računala na kojima su softverske komponente razmještene.

  • Dijagram toka podataka prikazuje kako se podaci kreću kroz sustav i kako se transformiraju.

  • Sekvencijski dijagram služi za prikaz načina rada protokola, na primjer HTTP-a, na vremenskoj crti.

  • Dijagram aktivnosti prikazuje tijek rada aktivnosti koje izvodi softverski sustav, na primjer UI NPC-a.

Fitness funkcije za odluke kao kod

Fitness funkcije su objektivne automatizirane provjere, napisane programskim kodom, koje potvrđuju da se odluke održavaju.

  • Fitness funkcije čine odluke provjerljivima i osiguranima.

  • Fitness funkcije za odluke mogu uvelike pomoći osiguranju kvalitete, regulatornim procesima i ciljevima upravljanja.

Kako se fitness funkcije povezuju s odlukama

Zapis odluke dokumentira odluku, dok fitness funkcija osigurava odluku.

  • Primjer odluke: Koristimo event sourcing zbog zahtjeva revizije.

  • Primjer fitness funkcije: Koristimo poslužitelj za kontinuiranu integraciju kako bismo testirali da sve promjene stanja moraju proizvoditi događaje.

Zašto fitness funkcije pomažu odlukama

Objektivna mjerenja: Fitness funkcije prolaze ili padaju, pa je rad vidljiv i jasan.

Kontinuirana upotreba: Fitness funkcije su vaša živa pravila, pokreću se pri svakom commitu i buildu.

Povjerenje za refaktoriranje: Fitness funkcije automatski hvataju pogreške u pravilima odluka.

Skalabilno upravljanje: Fitness funkcije osiguravaju standarde bez stvaranja uskih grla.

Mogu li fitness funkcije koristiti umjetnu inteligenciju?

Fitness funkcije mogu koristiti AI LLM-ove za odluke postavljanjem pitanja o vašem radu, poput vaših planova, koda, shema, API-ja i drugog:

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.

Jedinično testiranje arhitekture

ArchUnit: provjerava arhitekturna pravila Java koda pomoću bilo kojeg običnog okvira za jedinično testiranje u Javi.

ArchUnitTS: provjerava arhitekturna pravila TypeScript koda i JavaScript koda pomoću Jesta, Vitesta, Jasmine i drugih.

Zaštitne ograde odluka za pull requestove

Decision Guardian automatski izlaže prave zapise odluka u pravom trenutku — kada programer aktivno mijenja kod koji te odluke pokrivaju. Umjesto oslanjanja na to da programeri prije spajanja pročitaju mapu dokumentacije, relevantni kontekst pojavljuje se izravno na pull requestu.

Radi s bilo kojom vrstom zapisa odluke: arhitekturnim odlukama, odlukama o podacima, odlukama o usklađenosti, kliničkim i medicinskim odlukama, sigurnosnim odlukama i drugima.

Radi i s bilo kojim CI sustavom (GitLab, Jenkins, CircleCI) te kao pre-commit hook. Otvorenog koda. Licenca MIT.

ADR Guard je GitHub Action koji obara pull request ako se nadzirane putanje koda promijene bez dodavanja ili ažuriranja zapisa arhitekturne odluke. Izuzeća su eksplicitna: redak ADR-Exempt: s obrazloženjem propušta vrata i upisuje se u sažetak zadatka. Neovisan o predlošku, bez ovisnosti. Otvorenog koda. Licenca MIT.

Više informacija

Uvod:

Predlošci:

Dubinski:

Alati:

Smjernice specifične za tvrtke:

Primjeri:

Videozapisi:

Podcasti:

Knjige:

Vidi također:

  • 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) - Format YAML/JSON neutralan prema dobavljačima i strojno čitljiv za prikaz odluka s eksplicitnim obrazloženjem, pretpostavkama, kognitivnim stanjem i kompromisima. Nadopunjuje ADR-ove dodavanjem strukturiranog, provjerljivog obrazloženja u dokumentaciju odluka.