Yeni bir projeye katıldığınızı düşünün.

Kodu incelerken garip bir şey fark ediyorsunuz. Sipariş servisi stok bilgisini doğrudan veritabanından değil, her gece güncellenen bir tablo üzerinden okuyor.

Neden?

Ekipte soruyorsunuz. Kimse emin değil. “Sanırım performans içindi” diyen biri var. Bu kararı veren kişi bir yıl önce şirketten ayrılmış.

Şimdi iki seçeneğiniz var. Bu yapıya dokunmamak, çünkü bilmediğiniz bir sebebi olabilir. Veya değiştirmek ve o sebebi production’da keşfetmek.

Kod “ne”yi anlatır, “neden”i anlatmaz

İyi yazılmış kod ne yaptığını açıkça gösterir.

Ama neden o şekilde yapıldığını, hangi alternatiflerin değerlendirildiğini ve hangi kısıtlar altında karar verildiğini anlatmaz.

Commit mesajları bazen bu bilgiyi taşır ama bulunması zordur. Wiki sayfaları güncelliğini yitirir. Slack konuşmaları kaybolur.

Architecture Decision Record bu boşluğu doldurmak için önerilmiş basit bir format. Michael Nygard’ın 2011’de yazdığı kısa bir blog yazısından yaygınlaştı ve hâlâ aynı sadelikte kullanılıyor.

Bir ADR ne içerir?

Bir ADR genellikle bir sayfadan kısadır:

# 0007. Event yayını için outbox kullanımı

Durum: Kabul edildi
Tarih: 2026-10-25

## Bağlam
Sipariş oluşturulduğunda stok ve fatura servisleri
haberdar olmalı. Broker'a doğrudan yazmak, transaction
sonrası çökmelerde event kaybına yol açıyor.

## Karar
Event'ler aynı transaction içinde outbox tablosuna
yazılacak ve ayrı bir relay tarafından yayınlanacak.

## Sonuçlar
+ Event kaybı ortadan kalkar.
- Tüketiciler at-least-once teslimata göre idempotent olmalı.
- Outbox tablosunun temizlenmesi gerekir.

Bence en değerli bölüm “Sonuçlar”. Kararın getirdiği olumsuz etkileri de açıkça yazmak, gelecekteki okuyucuya bu bedelin bilinçli olarak kabul edildiğini söyler.

Değerlendirilip reddedilen alternatifleri kısaca yazmak da faydalı. Aksi halde altı ay sonra biri aynı alternatifi yeniden önerir ve aynı tartışma baştan yapılır.

Kodun yanında durmalı

ADR’leri ayrı bir wiki’de değil, repository içinde tutmayı tercih ediyorum:

docs/adr/0001-use-postgresql.md
docs/adr/0002-modular-monolith.md

Kodla aynı yerde durduğu için bulunması kolay. Pull request ile önerilip review edilebiliyor. Kararın hangi kod değişikliğiyle birlikte geldiği git geçmişinde görünüyor.

ADR’ler değiştirilmez

Bir karar zamanla geçerliliğini yitirebilir. Trafik on katına çıkmış, ekip büyümüş, kullanılan teknoloji artık desteklenmiyor olabilir.

Bu durumda eski ADR silinmez veya düzenlenmez. Yeni bir ADR yazılır ve eskisinin durumu “yerini 0012 aldı” olarak güncellenir.

Bu sayede kararın tarihçesi korunur. Bir kararın neden verildiğini ve neden sonradan değiştirildiğini görmek, ikisini de ayrı ayrı görmekten çok daha öğreticidir.

Ne zaman ADR yazılmalı?

Her teknik karar için ADR yazmak gereksiz bürokrasi yaratır ve sonunda kimse yazmaz.

Benim kullandığım ölçüt şu: geri alması pahalı olan veya yeni katılan birinin “bu neden böyle?” diye soracağını düşündüğüm kararlar.

Veritabanı seçimi, servis sınırları, iletişim modeli, kimlik doğrulama yaklaşımı, önemli bir kütüphanenin seçimi. Değişken isimlendirme kuralları değil.

Bir de şunu fark ettim: ADR yazmak kararın kendisini de iyileştiriyor. Bağlamı ve sonuçları yazıya dökmeye çalışırken, kafada net görünen bir kararın aslında tam düşünülmediği ortaya çıkabiliyor.

Mimari kararlar kalıcıdır.

Ama o kararları veren insanlar ve onların hafızası kalıcı değildir. ADR, ikisi arasındaki farkı kapatmanın en ucuz yolu.