Mimari karar kaydı (ADR) yazma: yapı, örnek ve uygulama önerileri

Mimari karar kaydı (ADR) nedir ve neden yazılır?

Mimari karar kaydı (Architecture Decision Record, ADR), bir yazılım sisteminde alınan önemli mimari kararın kısa, tarihli ve değiştirilmeyen bir kaydıdır. Kararın ne olduğunu değil, aynı zamanda hangi bağlamda, hangi seçenekler arasından ve hangi sonuçlarla alındığını da yazar. Amaç, birkaç ay sonra ekibe katılan ya da kararın sahibi değişen kişinin "bu neden böyle yapılmış" sorusuna cevap bulabilmesidir.

Kararlar çoğunlukla sohbetlerde, toplantılarda ve kişilerin zihninde yaşar; ekip değiştiğinde bilgi kaybolur. ADR bu bilgiyi kod deposunda, koda yakın ve sürümlenebilir biçimde saklar. Dokümantasyonu "mimari belge" gibi büyük ve güncelliğini kaybeden bir yapı yerine karar başına küçük bir dosya olarak tutmak, kaydı güncel tutmayı kolaylaştırır.

Hangi kararlar için ADR yazılır?

Her karar için ADR gerekmez. Şu ölçütlerden biri geçerliyse yazmaya değer: • Kararın geri dönüşü pahalı: veri tabanı seçimi, mimari stil, dış servis bağımlılığı. • Birden çok ekibi ya da bileşeni etkiliyor. • Gerçek alternatifler var ve aralarında ödünleşim yapıldı. • İleride "neden böyle yaptık" diye sorulması kuvvetle muhtemel. • Kalite özelliklerini (güvenlik, performans, bakım kolaylığı) etkiliyor.

Bir değişken adı ya da yerel bir kod düzeni için ADR yazmak gereksizdir. Ölçüt, kararın maliyeti ve etkisi büyüdükçe kayda alma ihtiyacının da artmasıdır.

Adım adım: ADR nasıl yazılır?

Yaygın kullanılan sade yapı şu bölümlerden oluşur: başlık, durum, bağlam, karar ve sonuçlar. Yapıyı ilk popülerleştiren kişi Michael Nygard'dır; birçok ekip bunu kendi ihtiyacına göre uyarlar.

Birinci adım, başlığı yazmaktır. Başlık kararı tek cümleyle söylemeli ve genellikle sıra numarası taşır; ancak okunabilir olmalıdır: örneğin "Sipariş servisinde olay tabanlı iletişim kullanılması."

İkinci adım, durumu belirtmektir. Genellikle önerildi, kabul edildi, reddedildi, yerini başkası aldı gibi bir durum yazılır. Durum, kaydın yaşam döngüsünü gösterir.

Üçüncü adım, bağlamı yazmaktır. Karara yol açan kuvvetler nelerdi: iş gereksinimi, teknik kısıtlar, takım yetkinliği, zaman baskısı, mevcut sistemin sınırları? Bağlam tarafsız ve olgusal olmalı, kararı haklı çıkarmaya çalışmamalıdır.

Dördüncü adım, değerlendirilen seçenekleri listelemektir. Her seçeneğin kısa artı ve eksileri yazılır. Seçilmeyen alternatiflerin yazılması, kaydın en çok işe yarayan bölümlerinden biridir; çünkü gelecekte aynı tartışma tekrar açıldığında hazır cevap sunar.

Beşinci adım, kararı yazmaktır. Etken bir dille: "Şunu kullanacağız." Belirsiz ifadeden kaçının.

Altıncı adım, sonuçları yazmaktır: kararın getirdiği olumlu etkiler, kabul edilen olumsuz etkiler ve yeni ortaya çıkan işler. Dürüst yazılmış olumsuz sonuçlar kaydın güvenilirliğini artırır.

Örnek ADR

Örneğin bir ekip, ürün katalog servisinde veri tabanı seçimi yapıyor. Kayıt şöyle olabilir:

Başlık: Katalog servisi için ilişkisel veri tabanı kullanılması.

Durum: Kabul edildi.

Bağlam: Katalog verisi ürün, kategori ve fiyat ilişkilerinden oluşuyor; raporlama için karmaşık sorgular gerekiyor. Ekibin ilişkisel veri tabanı deneyimi güçlü. Belge tabanlı seçenek esnek şema sunuyor ama çok tablolu sorgular uygulama kodunda çözülmek zorunda kalacak.

Karar: Katalog servisi ilişkisel bir veri tabanı kullanacak.

Sonuçlar: Karmaşık sorgular ve tutarlılık güvencesi kolaylaşır. Şema değişikliği için göç (migration) disiplini gerekir. Çok yüksek yazma yükü ortaya çıkarsa bu karar yeniden değerlendirilecek.

Bu örnek kurgusaldır; gerçek bir kayıtta bağlam, ekibin kendi verisi ve ölçümleriyle somutlaştırılmalıdır.

ADR'ı ekip içinde yaşatmak

Kayıtları yazmak kolay, alışkanlık haline getirmek zordur. Şu uygulamalar yardımcı olur: • ADR'ı kod deposunda, genellikle ayrı bir klasörde, düz metin ya da hafif işaretleme dilinde tutun. Kod değişikliği ile birlikte inceleme (pull request) üzerinden gözden geçirilmesi doğal bir tartışma platformu sağlar. • Kayıtlar değiştirilmez: karar değişirse eski kaydın durumu "yerini başkası aldı" olur ve yeni bir kayıt yazılır. Böylece karar tarihçesi korunur. • Şablon belirleyin ve kısa tutun. Bir sayfayı aşan ADR okunmaz. • Karar toplantısından sonra yazmayı unutmak yerine, yazıyı karar sürecinin parçası yapın: taslak ADR toplantı gündemidir. • Sahip belirleyin: her kaydın bir yazarı ve onaylayanı olsun. • İlgili kayıtları birbirine bağlayın; mimari kararlar çoğu zaman zincir halindedir.

Kurumsal ölçekte: yönetişim ve istisna

Büyük kuruluşlarda ADR yalnızca ekip içi bir not değil, mimari yönetişimin aracıdır. Hangi karar türünün hangi kurulun onayını gerektirdiği, mimari ilkelerle çelişen kararların nasıl istisna olarak kaydedileceği ve uygunluğun nasıl izleneceği tanımlanır. Böyle bir yapıda ADR şablonuna "hangi mimari ilkeyle ilişkili" ve "istisna gerekçesi" gibi alanlar eklenebilir. Ancak ağır onay süreçleri karar hızını düşürür; bu nedenle yönetişim yalnız kritik kararlara uygulanmalı, ekip içi kararlar hafif kalmalıdır.

Sık yapılan hatalar

• Kararı değil sonucu yazmak: bağlam ve alternatifler eksik kalır.
• Çok uzun ve kapsamlı yazmak: kimse okumaz.
• Eski kaydı sessizce değiştirmek: tarihçe kaybolur.
• Alternatifleri yazmamak: aynı tartışma tekrar açılır.
• Olumsuz sonuçları gizlemek.
• ADR'ı bir kereye mahsus yazıp bırakmak: karar değiştiğinde yeni kayıt yazılmazsa kayıtlar güvenilirliğini yitirir.

Bu beceriyi Mindset programlarında nerede çalışırsınız?

Yazılım Mimarisi Kararları ve ADR Dokümantasyonu programı, yazılım mimarları, kıdemli geliştiriciler ve teknik liderler için ADR yazımı, yaşam döngüsü ve yönetişimini modüllerde işler: mimari kararlar ve kayıt ihtiyacı, ADR yazımı ve yapısı, süreç yaşam döngüsü ve yönetişim. Kurumsal Mimari Yönetişimi ve Mimari Karar Kayıtları (ADR) programı ise daha geniş bir bakışla mimari yönetişim modellerini, mimari ilkelerin yazımını, istisna ve sapma yönetimini ve uygunluk izlemeyi kapsar; mimarlık ofisi kuran ya da çok ekipli mimari kontrol sağlamak isteyen kurumlar için uygundur.