Problem: heç kim niyə olduğunu xatırlamır
Buraxılışdan on səkkiz ay sonra yeni mühəndis soruşur: niyə order servisi anbarla message broker vasitəsilə danışır, qalan bütün inteqrasiyalar isə REST ilə işləyir? Cavabı bilən iki nəfər komandadan ayrılıb, çat tarixçəsi yoxdur, wiki səhifəsində isə yalnız "async üçün Kafka işlədirik" yazılıb. Yeni mühəndis onu REST çağırışları ilə əvəz etməyi təklif edir. Nəhayət kimsə xatırlayır ki, anbar sistemi hər gecə təmir üçün söndürülür və səbəb məhz bu idi. Komanda əvvəlcə on dəqiqəyə yazıla biləcək məhdudiyyəti yenidən kəşf etməyə bir həftə itirdi.
Architecture Decision Record (ADR) bir əhəmiyyətli qərarı qeyd edən qısa sənəddir: vəziyyət, baxılan variantlar, seçim və nəticələr. Bu, spesifikasiya deyil, jurnaldır. Sistemi miras alan insanlara, o cümlədən gələcəkdəki özünüzə "niyə belədir?" sualına cavab verir.
Hansı qərara ADR lazımdır
Qərarı geri qaytarmaq bahalıdırsa, bir neçə komandaya təsir edirsə və ya presedent yaradırsa, ADR yazın. Tipik nümunələr:
- datastore, messaging texnologiyası və ya autentifikasiya yanaşmasının seçimi
- servislərin bölünməsi və ya birləşdirilməsi
- kod bazasına yayılacaq framework və ya kitabxananın qəbulu
- error formatı, API versiyalama sxemi kimi ümumi konvensiyaların müəyyənləşdirilməsi
- məlum riskin və ya qısa yolun şüurlu şəkildə qəbul edilməsi
Metodun adını dəyişmək və ya formatter seçmək üçün ADR yazmayın. Qərar bir Pull Request ilə asanlıqla dəyişirsə, kod şərhi kifayətdir.
Minimal şablon
Şablonu insanların doldura biləcəyi qədər kiçik saxlayın. Geniş yayılmış forma metadata ilə yanaşı dörd hissədən ibarətdir: context, options, decision və consequences.
# ADR-0007: Use a message broker between Orders and Warehouse
Status: Accepted
Date: 2026-03-12
Deciders: Orders team, Warehouse team, architect
## Context
Warehouse management is unavailable every night from 01:00 to 03:00
for maintenance. Orders must be accepted at any time. Today an
order placed during the window fails with a timeout. We expect
order volume to grow, and the warehouse team cannot change its
maintenance schedule this year.
## Options considered
1. Synchronous REST call with retries in Orders.
2. Orders writes an event; Warehouse consumes it when available.
3. Nightly batch export.
## Decision
We use option 2. Orders publishes OrderPlaced through a transactional
outbox; Warehouse consumes it with an idempotent handler.
## Consequences
+ Orders accepts orders during warehouse downtime.
+ Warehouse can be scaled and paused independently.
- Stock reservation becomes eventually consistent; the UI shows
"confirmed" only after a ReservationCreated event.
- We now operate a broker and must monitor consumer lag.
- Duplicate delivery is possible; handlers must be idempotent.
## Revisit when
The warehouse supports 24/7 availability, or order volume stays low
enough that the broker is not worth its operational cost.Ən qiymətli hissələr context (yad adamın başa düşəcəyi şəkildə yazılmış qüvvələr) və consequences-dir (mənfi nəticələr də daxil). Consequences yalnız faydaları sadalayırsa, qeyd mühəndislik yox, reklamdır.
Status dövrü
Qəbul olunmuş ADR bir mənada dəyişməzdir: tarixi yenidən yazmırsınız. Əvəzində status dəyişir:
- Proposed: müzakirə mərhələsində, adətən Pull Request-də.
- Accepted: razılaşdırılıb və qüvvədədir.
- Deprecated: artıq aktual deyil, məsələn funksiya silinib.
- Superseded by ADR-00xx: sonrakı qərarla əvəzlənib, hər iki tərəfdə keçidlə.
Şərait dəyişəndə köhnəni əvəz edən yeni ADR yazın. Köhnə qeyd sistemin bu gün niyə belə göründüyünü izah etməyə davam edir, qeydlər zənciri isə düşüncənin necə dəyişdiyini göstərir.
Zəif ADR və yaxşı ADR
Zəif qeyd belə görünür:
# ADR-0012: Use PostgreSQL
Status: Accepted
We decided to use PostgreSQL because it is reliable and popular.Orada context, alternativ və nəticə yoxdur. Nə ilə müqayisə edildiyi, datanın necə göründüyü və nə vaxt yenidən baxmaq lazım olduğu bəlli deyil. Yaxşı variant iş yükünü (sifariş və ödənişlər arasında transaction tələb edən relational data), həqiqətən nəzərdən keçirilmiş alternativləri, komandanın artıq idarə etdiyi texnologiyaları, seçimin qiymətini (məsələn, üfüqi write scaling çətindir) və yenidən baxmaq üçün aydın şərti yazır.
Başqa zəiflik, aylar əvvəl verilmiş qərarı əsaslandırmaq üçün yazılan retrospektiv ADR-dir. Gec yazmaq heç yazmamaqdan yaxşıdır, amma onu dürüstcəsinə işarələyin və o vaxtkı real məhdudiyyətləri qeyd edin, sonradan uydurulmuş əsaslandırmanı yox.
Qısa iş axını
Sadə axın praktikanı mərasimsiz yaşadır. Kimsə "geri qaytarmaq bahadır" meyarına cavab verən dəyişiklik təklif edir və ADR-i Proposed statusunda draft Pull Request kimi açır. Reviewer-lər sözlərə yox, context və variantlara şərh yazır. Qrup razılaşanda status Accepted olur və Pull Request, ideal halda ilk implementasiya işi ilə birlikdə, merge edilir. Aylar sonra yeni gələn qeydi, nəticələrinə bağlı monitorinqi və yenidən baxma şərtini oxuyur və qərarın hələ də doğru olub-olmadığını sübutla həll edə bilir.
Harada saxlamalı
ADR-ləri təsir etdikləri repository-də, məsələn docs/adr/ qovluğunda, 0007-message-broker-between-orders-and-warehouse.md kimi adlarla saxlayın. Səbəblər:
- Pull Request ilə dəyişirlər, müzakirə və təsdiq görünür
- təsvir etdikləri kodla birlikdə versiyalanırlar
- repository-ni klonlayan hər kəs onları tapır
- bir neçə repository-ni əhatə edən qərar ayrıca arxitektura repository-sində ola bilər, digərlərindən ona istinad edilir
Qeydləri ardıcıl nömrələyin və nömrəni təkrar işlətməyin. Başlıq və statusu göstərən qısa index faylı naviqasiyaya kömək edir.
Yaxşı ADR-in əlamətləri
Yaxşı qeydi bir il sonra yad adam oxuyub dörd sualı cavablandıra bilir: o vaxt hansı problem var idi, başqa nə seçmək olardı, niyə bu seçildi və qiyməti nə oldu. Dil sadə və konkret olur, "yaxşı", "sürətli", "müasir" kimi boş sözlər əvəzinə ölçülə bilən məhdudiyyətlər yazılır, məsələn "gecə pəncərəsi iki saatdır". Qərarı verən insanların adları yazılır ki, sonradan kimə müraciət edəcəyi bəlli olsun. Qeyd qərarı qorumaq üçün yox, yenidən baxılmasını asanlaşdırmaq üçün yazılır.
ADR və digər sənədlər
ADR dizayn sənədini, runbook-u və ya texniki spesifikasiyanı əvəz etmir. Dizayn sənədi həllin necə işlədiyini, runbook əməliyyatı, ADR isə yalnız "niyə bu yol seçildi" sualını cavablandırır. Üç sənəd bir-birinə keçidlə bağlanarsa, hər biri qısa qalır və kimsə eyni məlumatı üç yerdə yeniləməli olmur.
Tez-tez edilən səhvlər
- Yalnız sonradan yazmaq. Real variantlar müzakirədə yaşayır. Seçim hələ açıq ikən ADR-ə draft Pull Request kimi başlayın.
- Alternativləri gizlətmək. Yalnız qalibi yazmaq qərarı bəsit göstərir və sonradan eyni mübahisəni çağırır.
- Nəticələrin olmaması. Hər qərarın qiyməti var; onu adlandırmaq etimad yaradır və monitorinq ilə azaldıcı tədbirlərə zəmin hazırlayır.
- Həddindən uzun olmaq. Bir-iki səhifə kifayətdir. Ətraflı analizi içinə qoymaq əvəzinə keçidlə göstərin.
- Qəbul olunmuş qeydləri redaktə etmək. Yazı səhvlərini düzəldin, amma qərarları yenidən yazmaq əvəzinə yeni qeydlə əvəzləyin.
- ADR-i təsdiq teatrına çevirmək. Məqsəd imza yox, ortaq anlayışdır.
Güzəştlər
ADR vaxt aparır və hər kiçik seçim üçün yazan komanda tezliklə heç yazmamağa başlayır. Seçici olun. ADR diaqramları da əvəz etmir: sistemin formasını və arxasındakı əsaslandırmanı birlikdə göstərmək üçün onları C4 diaqramları ilə cütləşdirin. Çox kiçik və qısaömürlü layihələrdə README-də "Decisions" bölməsi kifayət ola bilər.
Yoxlama siyahısı
- Başlıq yalnız mövzunu yox, qərarı deyirmi?
- Context qüvvələri və məhdudiyyətləri yeni gələnə izah edirmi?
- Rədd səbəbləri ilə ən azı iki real variant sadalanıbmı?
- Mənfi nəticələr və risklər adlandırılıbmı?
- Status, tarix və qərar verənlərin siyahısı varmı?
- Qərara yenidən baxmaq üçün şərt göstərilibmi?
- Qeyd repository-dədir və əlaqəli diaqramlardan istinad olunurmu?
Növbəti addım
Qərarların daha geniş işə necə uyğun gəldiyini solution architect rolu məqaləsində, sistem səviyyəli görünüşü isə C4 modeli bələdçisində görün. Arxitektura təcrübənizin harada olduğunu öyrənmək üçün bacarıq qiymətləndirməsindən keçə bilərsiniz.