Mimari kararları yazmak: ADR

Her yazılım projesinde bir gün şu soru sorulur: "Bunu neden böyle yapmıştık?" Cevap çoğu zaman ya ayrılmış bir ekip arkadaşının kafasında ya da yüzlerce mesajlık bir yazışmanın içindedir. Mimari karar kaydı (Architecture Decision Record, ADR), bu cevabı kararın alındığı gün, kısa bir dosyaya yazmaktır.

ADR nedir?

ADR, önemli bir teknik kararı; bağlamı, seçenekleri ve sonuçlarıyla birlikte kaydeden kısa bir belgedir. Kod deposunda, genellikle docs/adr/ klasöründe, numaralı dosyalar olarak durur: 0007-para-alanlari-decimal.md gibi.

Önemli olan, ADR'nin değiştirilmemesidir. Karar değişirse eski ADR silinmez; yeni bir ADR yazılır ve eskisinin yerini aldığı belirtilir. Böylece kararların tarihçesi korunur.

Ne zaman yazılır?

Her karar ADR gerektirmez. Yazmaya değer kararlar genellikle:

• Geri alması pahalı olanlar: veritabanı seçimi, servislerin sınırları, kimlik doğrulama yöntemi.
• Birden fazla makul seçeneği olanlar: bir kütüphane yerine diğerini neden seçtiğiniz.
• İleride sorgulanacak olanlar: ilk bakışta tuhaf görünen ama bir sebebi olan kararlar.

Kullandığım şablon

# 0007 — Para alanları Decimal(18,4)

Durum: Kabul edildi · 2025-11-03

## Bağlam
Raporlarda kuruş farkları çıkıyor; tutarlar float olarak saklanıyor.

## Karar
Tüm para alanları Decimal(18,4); API'de string olarak taşınır;
yuvarlama yalnız gösterimde ve tek bir yardımcı fonksiyonda.

## Değerlendirilen seçenekler
- Tam sayı kuruş: kur ve faiz ara sonuçlarında hassasiyet yetmiyor.
- Float + yuvarlama: sorunu gizler, çözmez.

## Sonuçlar
+ Toplamlar kuruşu kuruşuna tutar.
− Migrasyon gerekiyor; istemciler string tutar parse etmeli.

Şablonun gücü kısalığındadır: bir sayfayı geçmeyen, beş dakikada okunan bir belge. Bu örnekteki kararın ayrıntılarını para alanları yazısında anlattım.

Kararları denetime bağlamak

Bazı kararlar yalnızca yazılı kalırsa zamanla aşınır. Örneğin "domain katmanı altyapı katmanını import etmez" gibi bir bağımlılık kuralı, CI'da çalışan bir denetimle korunabilir: izin verilen listenin dışındaki bir import derlemeyi kırar. ADR kararın neden'ini, otomatik denetim ise uygulanmasını güvence altına alır.

Küçük başlayın

İlk ADR için bugün projede tartışılan ya da yakın zamanda alınmış bir kararı seçin ve yukarıdaki şablonla on dakikada yazın. Birkaç ADR biriktikten sonra, yeni gelen bir ekip arkadaşının projeyi anlaması için ilk okuyacağı yer bu klasör olur.