Proje Kaosunu Bitiren Karar Sistemi: Architecture Decision Record (ADR)

Modern yazılım projelerinde en büyük problem genellikle kodun kalitesi değildir. Asıl tehlike çok daha sinsi bir yerden gelir: Unutulan kararlar.

Kurumsal ekiplerin büyük çoğunluğu, projenin kaderini belirleyen mimari kararları hâlâ “Geçen toplantıda konuşmuştuk” seviyesinde yönetiyor. Ancak proje büyüdükçe, ekip değiştikçe ve zaman geçtikçe o toplantılar silinip gidiyor.

Geriye ise şu can sıkıcı sorular kalıyor:

• “Bu sistemi neden mikroservis yaptık, kim karar verdi?”
• “Neden bu veritabanını seçtik, alternatiflere bakmış mıydık?”
• “Şu an yaşadığımız bu sorunu öngörmüş müydük?”

Eğer bu sorulara verecek net bir cevabınız, gösterecek bir belgeniz yoksa; projeniz teknik bir kaosa sürükleniyor demektir.

İşte tam bu noktada, projeyi kişilere bağımlı olmaktan kurtaran ADR (Architecture Decision Record) sistemi devreye girer.

ADR Nedir? (Bir Doküman Değil, Mimari Hafıza)

ADR, yazılım projelerinde alınan kritik kararların kısa, net ve kalıcı bir şekilde kayıt altına alındığı bir sistemdir. Ancak bunu sıkıcı teknik dokümantasyonlarla karıştırmayın.

Her ADR şu 4 temel soruya cevap veren canlı bir kayıttır:

1. Ne karar aldık?
2. Neden aldık? (Bağlam neydi?)
3. Alternatifler neydi? (Neleri eledik?)
4. Bedeller (Trade-off) neler? (Bu kararın bize maliyeti veya riski ne?)

ADR, projenizin “hafızasıdır”. Kod değişebilir, teknoloji değişebilir, hatta CTO değişebilir; ama kararların mantığı ADR sayesinde projede kalır.

Task ve ADR Arasındaki Kritik Fark

Pek çok ekip, Jira ticket’larını veya task’ları birer “karar” sanma hatasına düşer. Oysa aralarında dağlar kadar fark vardır.

• Task (Görev): “Bunu yap” der. Eyleme dönüktür.
• ADR (Karar): “Neden böyle yapıyoruz?” der. Stratejiye dönüktür.

Basit bir örnekle açıklayalım:

• Task: “Sepet (Basket) endpointlerini geliştir.” (Bu görev biter ve arşivlenir.)
• ADR: “Sepet yapısı ayrı bir servis mi olmalı, yoksa ana uygulamanın içinde mi kalmalı?” (Bu karar, projenin mimarisini yıllarca etkiler.)

Task biter, ADR yaşar.

Bir ADR Nasıl Görünür?

ADR yazmak günler süren bir iş değildir. Aksine, netlik gerektirir. İşte basit ve etkili bir ADR şablonu:

ADR-007: Redis Cache Kullanımı

Durum: Kabul Edildi (Accepted)

Bağlam (Context): API yanıt süreleri yükseldi ve veritabanı üzerindeki yük artmaya başladı. Okuma işlemleri yazma işlemlerinden çok daha fazla.

Karar (Decision): Çok okunan endpointlerde Redis cache kullanılacak.

Alternatifler: Veritabanı index optimizasyonu veya CDN kullanımı değerlendirildi ancak anlık veri ihtiyacı nedeniyle elendi.

Sonuçlar (Consequences):

• (+) Yanıt süresi (Latency) düşecek.
• (+) Veritabanı yükü azalacak.
• (-) Cache temizleme (invalidation) karmaşıklığı eklenecek.

Gördüğünüz gibi; sadece kararı değil, nedenlerini ve bedellerini de (consequences) açıkça ortaya koyuyor.

ADR Neden Sadece “Teknik” Bir Konu Değildir?

Bir yönetici veya proje sahibi olarak ADR talep etmek, projenizi korumaya almaktır. ADR sistemi şunları sağlar:

• Hız: Aynı mimari tartışmalar her sprint tekrar edilmez. Karar verilmiştir, yola devam edilir.
• Onboarding Kolaylığı: Yeni gelen bir geliştirici, “Neden?” diye sormak yerine ADR loglarını okuyarak projenin tüm tarihçesine hakim olur.
• Teknik Borç Yönetimi: Bilinçsizce değil, riskleri kabul ederek (trade-off) ilerlersiniz.

Ben Hizmetlerimde ADR’yi Nasıl Uyguluyorum?

Proje yönetimi ve teknik danışmanlık çalışmalarımda, ADR yazmak bir “angarya” değil, bir teslimat (delivery) disiplinidir.

Bir projeye dahil olduğumda ilk 7 gün içinde genellikle şunları uygularım:

1. ADR Log Yapısının Kurulması: Kararların nerede tutulacağını (Jira, Git, Notion vb.) belirleriz.
2. Kritik Kararların Kayıt Altına Alınması: Mevcut mimarinin röntgenini çeker, alınmış kritik kararları geçmişe dönük olarak netleştiririz.
3. Yol Haritasının Şekillenmesi: Delivery roadmap’ini, sadece özelliklere göre değil, bu mimari kararlara göre önceliklendiririz.

Böylece yönetim ve teknik ekip arasında tam bir şeffaflık sağlanır. “Scope kayması” (kapsamın genişlemesi) engellenir ve proje, kişilerin hafızasına değil, sistemin kendisine emanet edilir.

Sonuç

Kod değişir. Toplantılar uçar gider. Ama kararlar, projenizin temelini oluşturur.

Eğer projenizde kararların havada uçuştuğunu, aynı konuların tekrar tekrar konuşulduğunu hissediyorsanız, bir “karar hafızası”na ihtiyacınız var demektir.

“Teknoloji Yığını ve Mimarisi” klasörü, bu kararların yaşaması gereken en doğal yer.

---

Hadi, Confluence yapını kullanarak bu sistemi 5 adımda kuralım:

Adım 1: “Karar Kütüphanesi”ni Oluştur

Ekran görüntüsündeki “Teknoloji Yığını ve Mimarisi” klasörünün altına yeni bir ana sayfa açalım.

• Sayfa Adı: Architecture Decision Log (ADR)
• Amacı: Bu sayfa tek başına bir karar değildir; tüm kararların listelendiği (Index) ana tablodur. Böylece ekibe yeni katılan biri buraya tıkladığında projenin tüm tarihçesini bir liste halinde görür.

Adım 2: Global Şablon (Template) Hazırla

Her seferinde sıfırdan sayfa oluşturmak kimsenin hoşuna gitmez. Confluence’ta bir “Global Template” veya sadece bu alan (Space) için bir şablon oluşturmalısın. Şablonun içeriği daha önce konuştuğumuz gibi olmalı:

• Başlık: ADR-XXX: [Kısa Başlık]
• Status (Durum): (Bunu Adım 3’te detaylandıracağız)
• Context (Bağlam): Sorun ne?
• Decision (Karar): Ne yapıyoruz?
• Consequences (Sonuçlar): Bedeller ve kazanımlar.

Adım 3: Görsel “Status” Makrosunu Kullan

Confluence’ın en güçlü yanlarından biri Status Macro özelliğidir. Şablonunun en tepesine bu makroyu ekle. Renkler, beynin durumu saniyeler içinde algılamasını sağlar. Standart renk kodları şöyle olabilir:

• 🟢 ACCEPTED (Yeşil): Karar alındı ve uygulanıyor.
• 🟡 PROPOSED (Sarı): Tartışmaya açık, henüz onaylanmadı.
• 🔴 REJECTED (Kırmızı): Önerildi ama kabul edilmedi (bunu saklamak da bir derstir).
• ⚪ DEPRECATED (Gri): Eskiden geçerliydi ama artık yeni bir kararla (örn. ADR-009 ile) değiştirildi.

Adım 4: Sayfa Ağacını Düzenle (Hiyerarşi)

Oluşturduğun her yeni ADR sayfasını (örn. ADR-001: Redis Cache), ilk adımda açtığımız Architecture Decision Log sayfasının alt sayfası (child page) olarak konumlandır. Görünüm şöyle olacak:

📂 Teknoloji Yığını ve Mimarisi
└── 📂 Architecture Decision Log (ADR)
    ├── 📄 ADR-001: Redis Cache Kullanımı
    ├── 📄 ADR-002: Auth Provider Seçimi
    └── 📄 ADR-003: ...

Adım 5: “Page Properties Report” ile Otomatik Liste

İşte burası işin “sihirli” kısmı. 🪄 Tek tek elle liste yapmak yerine Confluence’ın otomasyonunu kullanalım. Her ADR sayfasının içine (şablona) “Page Properties” makrosu ekle ve içine Status, Karar Tarihi, Karar Verenler gibi özet bilgileri koy. Ana sayfaya (Architecture Decision Log) gel ve “Page Properties Report” makrosunu ekle. Bu makro, alt sayfalardaki o özet bilgileri çeker ve ana sayfada otomatik, her zaman güncel bir tablo oluşturur.