Mimari Hafıza: Mimari Karar Kayıtları (ADR) ve Kurumsal Hafıza Kaybını Önleme

Senior (L5)

⚡ÖZET VE TEKNİK CEVAP

Yazılım organizasyonları büyüyüp ekipler değiştikçe Kurumsal Hafıza Kaybı (Organizational Amnesia) başlar: Yeni gelen mühendisler mevcut tasarıma bakıp 'Bu saçma mimariyi kim yaptı? Neden Kafka/MongoDB kullanmadılar? Bunu baştan yazalım!' derler. 6 ay boyunca sistemi yeniden yazdıktan sonra, eski ekibin o mimariyi seçmesine neden olan birebir aynı köşe durumları, ölçek sınırlarını ve güvenlik açıklarını acı bir şekilde yeniden keşfederler. Michael Nygard tarafından geliştirilen Mimari Karar Kayıtları (Architecture Decision Records - ADR), önemli teknik kararların arkasındaki tarihi mantığı doğrudan Git deposundaki Markdown dosyalarında (/docs/adr/0014-kullanici-veritabani-secimi.md) kayıt altına alır. Bir ADR 3 temel bölümden oluşur: Bağlam (Context) (Karşılaşılan problem ve kısıtlar), Karar (Decision) (Seçilen mimari çözüm), ve Sonuçlar (Consequences) (Elde edilen avantajlar, kabul edilen riskler ve teknik feragatler). ADR'lar uçup giden Slack tartışmalarını kalıcı bir kurumsal bilgeliğe dönüştürür.

Mühendislik El Kitabı & Mekanizma

6 Boyutlu Mimari Analiz

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

Mekanizma

ADR yönetişimi Git Pull Request inceleme süreciyle işler:

Taslak Hazırlama: Mühendis docs/adr/0042-mobil-icin-graphql.md dosyasını PROPOSED (Önerildi) statüsünde açar.

Tartışma ve Uzlaşma: Takım GitHub PR yorumlarında alternatifleri ve riskleri tartışır.

Karar ve Durum Güncellemesi: Uzlaşma sağlandığında durum ACCEPTED (Kabul Edildi) yapılır ve PR main dalına birleştirilir. Gelecekte karar değişirse, yeni bir ADR açılarak eski ADR SUPERSEDED (Hükmünü Yitirdi) olarak etiketlenir.

Kodla Yan Yana Yaşama: ADR'lar yönettikleri kodla aynı depoda saklanır; böylece IDE üzerinden kolayca aranabilir.

🎯2. Doğru Kullanım Senaryosu

Kapsam

Büyük framework geçişleri, veritabanı motoru seçimleri, mikroservis sınır ayrıştırmaları, iletişim protokolü tercihleri (gRPC vs REST) ve güvenlik kimlik doğrulama mimarisi değişiklikleri.

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

Kritik Risk

✓
Onaylanması 3 ay süren 40 sayfalık bürokratik ADR'lar yazıp yazılım hızını felç etmek
✓
kararları kimsenin bulamayacağı özel Google Docs dosyalarına gömmek
✓
kararın getireceği olumsuz teknik feragatleri (trade-offs) dürüstçe yazmaktan kaçınmak

📡4. Teşhis ve Telemetri Sinyalleri

Metrikler

✓
Mühendislerin yılda 4 kez 'Neden DynamoDB yerine PostgreSQL kullanıyoruz?' tartışmasını sıfırdan yapması
✓
yeni işe başlayanların yazılı olmayan mimari kuralları bilmeden bozması
✓
kıdemli mühendisler ayrılınca sistemin neden öyle yapıldığının bilinememesi

🛡️5. Önleme ve Mimari Bariyerler

Bariyerler

✓
Michael Nygard'ın maksimum 2 sayfalık sade ADR şablonunu kullanın
✓
ADR'ları doğrudan Git deposunda docs/adr/ altında tutun
✓
birden fazla takımı etkileyen veya 6 aydan uzun vadeli her kritik kararda ADR yazılmasını zorunlu kılın

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

Ödünleşim

ADR'lar kurumsal hafıza kaybını yok eder ve şeffaf bir teknik uzlaşma kurar; ancak sistemler geliştikçe karar kayıtlarının güncel tutulması konusunda mühendislik disiplini gerektirir.

📋

Vaka İncelemesi (TinyCTO Saha Örneği)

GERÇEK DÜNYA TELEMETRİSİ

Şirkete yeni katılan bir Teknik Lider, analitik boru hattının ClickHouse yerine PostgreSQL ile yazıldığını gördü. Eski ekibin yetersiz olduğunu düşünerek 4 ayını sistemi ClickHouse'a geçirmeye harcadı; ancak ClickHouse'un muhasebe sisteminden gelen ilişkisel anlık güncellemeleri (UPDATE) kaldıramadığını görünce proje çöktü. Oysa Git deposundaki docs/adr/0018-muhasebe-icin-postgres-secimi.md dosyasını okusaydı, eski ekibin 2 yıl önce bu kısıtı fark edip dürüstçe kaydettiğini görecekti. Şirket tüm büyük yeniden yazımlardan önce ADR incelemesini zorunlu kılarak yüzlerce saatlik israfı engelledi.

İnteraktif Konsept Alıştırmaları

2 Alıştırma

Bir Mimari Karar Kaydının (ADR) en temel 3 bölümü nedir?

1. Bağlam (Context - karşılaşılan problem ve kısıtlar), 2. Karar (Decision - seçilen mimari çözüm), ve 3. Sonuçlar (Consequences - elde edilen faydalar, kabul edilen riskler ve teknik feragatler).

Bir yazılım projesinde Mimari Karar Kayıtları (ADR) nerede saklanmalıdır?

Doğrudan kaynak kod Git deposunun içinde (ör. `docs/adr/` veya `_PM/Agent-PM/Docs/ADRs/`), yönettikleri kodla yan yana versiyonlanan Markdown dosyaları olarak.

Mimari Hafıza: Mimari Karar Kayıtları (ADR) ve Kurumsal Hafıza Kaybını Önleme — Sıkça Sorulan Sorular

Bir ADR'da belgelenen eski bir mimari karar zamanla geçerliliğini yitirdiğinde ne yapılmalıdır?

Eski ADR dosyasını ASLA silmeyin veya içeriğini değiştirmeyin; yeni bağlamı anlatan yeni bir ADR oluşturun ve eski ADR'ın durumunu `SUPERSEDED` (Hükmünü Yitirdi) olarak işaretleyip yenisine link verin.

Etkili bir Mimari Karar Kaydı (ADR) ne kadar uzunlukta olmalıdır?

Kısa ve sade: Genellikle 1 ila 2 sayfa Markdown uzunluğunda; okunması ve incelenmesi 15-20 dakikayı geçmeyecek boyutta.

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

Temel Gerçekler & İlkeler

▸
Mimari Karar Kayıtları (ADR) teknik kararları ve feragatleri Git üzerinde kayıt altına alır.
▸
3 temel bölüm: Bağlam (Problem) -> Karar (Çözüm) -> Sonuçlar (Teknik Feragatler).
▸
ADR'lar kıdemli mühendisler ayrıldığında 'Kurumsal Hafıza Kaybı' yaşanmasını engeller.
▸
Eski ADR'ları asla silmeyin; yeni bir tasarım geldiğinde durumunu SUPERSEDED yapın.

Yaygın Yanılgılar

✗
Yanılgı: ADR'lar çevik geliştirmeyi yavaşlatan ağır bürokratik belgelerdir (Gerçek: 1 sayfalık hafif ADR'lar bir saatte yazılır ve aylarca sürecek anlamsız tartışmaları önler).
✗
Yanılgı: ADR'lar sadece herkesin anlaştığı mükemmel kararlar için yazılır (Gerçek: ADR'lar özellikle tartışmalı uzlaşmaları ve kabul edilen teknik eksikleri belgeler).

Karar Kılavuzu & Önceliklendirme

Mimari bağlamı korumak, teknik feragatleri belgelemek ve kurumsal hafıza kaybını önlemek için Git deponuzda versiyonlanan bir Mimari Karar Kaydı (ADR) kütüphanesi oluşturun.

Doğrulanmış Kaynaklar & Referanslar

[ARTICLE]Documenting Architecture Decisions: The Original ADR Concept— Michael Nygard / Cognitect Architecture Blog