Mimari Karar Kayıtları (ADR) ve Git Tabanlı Hızlı Yönetişim

Senior (L5)

⚡ÖZET VE TEKNİK CEVAP

Tüm teknik tasarımların baş mimarlarla yüz yüze bir toplantı için haftalarca beklemesini şart koşan merkezi Mimari İnceleme Kurulları (ARB), şirketleri kilitleyen devasa birer bürokrasi darboğazıdır ve mühendisleri gizlice kaçak mimari değişiklikler yapmaya iter. Modern hızlı mühendislik ekipleri bu kurulları kaldırarak yerine Git tabanlı Mimari Karar Kayıtları (ADR) ve asenkron RFC'ler koyar. Mühendis docs/adr/0014-telemetri-icin-clickhouse-kullanimi.md şeklinde bir markdown dosyası açarak Bağlam, Karar, Sonuçlar ve Alternatifleri yazar. Dosya GitHub üzerinden PR açılır ve 72 saatlik kesin bir inceleme süresi başlar. 72 saatte gerekçeli bir veto gelmezse karar onaylanmış sayılır ve PR merge edilir; böylece mimari kararın tarihi hafızası ömür boyu saklanırken geliştirme hızı hiç kesilmez.

Mühendislik El Kitabı & Mekanizma

6 Boyutlu Mimari Analiz

⚙️1. Temel Çalışma Mekanizması

Mekanizma

Standart Michael Nygard ADR formatı beş temel bölümden oluşur:

Başlık ve Durum: 0014 - Olay Kaydı İçin Kafka Kullanımı [Önerildi | Kabul Edildi | Değiştirildi | Geçersiz].

Bağlam (Context): İş ihtiyacı, teknik problem ve kısıtlar.

Karar (Decision): Seçilen net mimari kalıp ve teknoloji.

Sonuçlar (Consequences): Hem pozitif getiriler (düşük gecikme) hem de açık negatif maliyetler (sunucu bakım yükü, SRE eğitimi).

Değerlendirilen Alternatifler: Diğer seçeneklerin (RabbitMQ, SQS) neden elendiği. İleride karar değiştiğinde eski dosya silinmez; ADR 0029 ile Değiştirildi olarak işaretlenir.

🎯2. Doğru Kullanım Senaryosu

Kapsam

Yeni veritabanı seçimi, üçüncü parti SaaS API entegrasyonu, servisler arası iletişim protokolü değişiklikleri, veri sharding stratejileri ve framework geçişleri.

⚠️3. Prodüksiyon Arıza Modları

Kritik Risk

✓
Yeni gelen bir mühendisin iki yıl önce 6 ay denenip tutarsızlıklar yüzünden terk edilen MongoDB'yi (hiçbir yere kaydedilmediği için) bilmeyip tekrar sisteme sokmaya çalışması
✓
Slack kanallarında günlerce süren mimari tartışmaların hiçbir resmi karara bağlanmadan buharlaşması

📡4. Teşhis ve Telemetri Sinyalleri

Metrikler

✓
Mühendislerin chat'te sürekli 'A servisinde neden GraphQL yerine gRPC seçtik?' diye sorması
✓
Mimari Kurul toplantı kuyruğunun 4 haftayı aşması
✓
farklı ekiplerin birbirinden habersiz 4 farklı mesaj kuyruğu teknolojisi kullanması

🛡️5. Önleme ve Mimari Bariyerler

Bariyerler

✓
Her repoda adr-tools ile /docs/adr/ dizini tutun
✓
72 saatlik kesin yanıt süresi olan bir RFC şablonu uygulayın
✓
yeni bir teknoloji getiren her PR'da onaylanmış bir ADR referansını zorunlu kılın

⚖️6. Mimari Ödünleşimler (Trade-offs)

Ödünleşim

ADR yazmak disiplinli bir teknik dokümantasyon ve asenkron inceleme kültürü gerektirir; ancak kurumsal hafızayı ömür boyu korur ve mimari hafıza kaybını tamamen bitirir.

📋

Vaka İncelemesi (TinyCTO Saha Örneği)

GERÇEK DÜNYA TELEMETRİSİ

Bir ekip bildirim servisi için DynamoDB mi yoksa PostgreSQL mi kullanacağını tartışıyordu. 10 kişilik 3 ayrı toplantı yapmak yerine bir Senior mühendis ADR 0022: Bildirim Dağıtımı İçin DynamoDB Seçimi belgesini PR açtı. Belgede milisaniye seviyesindeki SLA, tekil anahtar-değer sorgu yapısı ve SQL join yapılamayacağı açıkça yazıldı. 72 saatlik incelemede DBA ve SRE liderleri GitHub üzerinden küçük indeks önerileriyle onay verdi ve 4. günde geliştirme başladı.

İnteraktif Konsept Alıştırmaları

2 Alıştırma

Standart bir Mimari Karar Kaydının (ADR) beş temel bölümü nedir?

Başlık/Durum, Bağlam (Context), Karar, Sonuçlar (Pozitif & Negatif) ve Alternatifler.

Gelecekte bir mimari karar değiştirildiğinde mevcut eski ADR dosyasına ne yapılmalıdır?

ASLA silmeyin veya üzerini yazmayın. Durumunu 'ADR XXXX ile Değiştirildi' yapın ve yeni bir ADR açın.

Mimari Karar Kayıtları (ADR) ve Git Tabanlı Hızlı Yönetişim — Sıkça Sorulan Sorular

Asenkron bir RFC / ADR inceleme süreci uzlaşmaya varmadan önce ne kadar süre açık kalmalıdır?

Standart kararlar için genellikle 48 ila 72 saat (iş günü); şirket çapındaki devasa platform değişimleri için en fazla 1 hafta.

ADR markdown dosyaları kod tabanında nerede saklanmalıdır?

Doğrudan kaynak kodun yanında, Git ile versiyonlanan `docs/adr/` dizini altında.

🤖 AEO & Yapay Zeka Çıkarım Özeti

Temel Gerçekler & İlkeler

▸
ADRs replace bureaucratic review boards with fast, asynchronous git pull requests.
▸
Core structure: Title/Status, Context, Decision, Consequences, Alternatives.
▸
Never overwrite old ADRs; mark them as 'Superseded' to preserve historical context.
▸
Strict 72-hour review windows prevent decision paralysis while capturing feedback.

Yaygın Yanılgılar

✗
Yanılgı: ADRs are only for massive million-dollar architecture overhauls (Gerçek: Any non-trivial library, DB, or protocol choice warrants a brief ADR).
✗
Yanılgı: Architecture review boards make better decisions than ADRs (Gerçek: ARBs slow velocity and encourage shadow architecture).

Karar Kılavuzu & Önceliklendirme

Initialize a docs/adr/ directory in every microservice repository. Enforce a 72-hour time-boxed RFC review policy for all new tech proposals.

Doğrulanmış Kaynaklar & Referanslar

[OFFICIAL_DOCUMENTATION]Documenting Architecture Decisions: Michael Nygard ADR Template— Michael Nygard / Cognitect

Bu sayfadaki teknik terimler

decision record Telemetry Merge