ADR Nedir? Yazılım Mimari Kararlarını Belgelemenin Önemi
Bir yazılım projesinde en değerli bilgi, neden belirli bir teknoloji veya yaklaşımın seçildiğidir. Architecture Decision Records (ADR), bu kararları yapılandırılmış bir şekilde belgelemenin standart yöntemidir.
ADR Nedir?
ADR (Architecture Decision Record), bir yazılım projesinde alınan mimari kararları belgeleyen kısa, öz dokümanlardır. Her ADR şunları içerir:
- Başlık — Kararın kısa özeti
- Durum — Proposed, Accepted, Deprecated, Superseded
- Bağlam — Kararın alındığı koşullar
- Karar — Ne yapılacağı
- Sonuçlar — Kararın olumlu ve olumsuz etkileri
Neden ADR Kullanmalısınız?
1. Kurumsal Hafıza
Ekipteki bir kişi ayrıldığında, mimari kararların arkasındaki mantık da gider. ADR'lar bu bilgiyi kalıcı kılar.
2. Yeni Ekip Üyelerinin Hızlı Adaptasyonu
Projeye yeni katılan bir geliştirici, ADR'ları okuyarak "neden PostgreSQL seçildi?" veya "neden monolitik mimari tercih edildi?" sorularının cevaplarını dakikalar içinde bulur.
3. Kararların İzlenebilirliği
Bir mimari karar zaman içinde değiştirilmek istendiğinde, orijinal kararın bağlamını bilmek kritiktir. ADR'lar bu bağlamı sağlar.
4. Tekrarlayan Tartışmaların Önlenmesi
"Bu konuyu daha önce tartışmıştık" deme ihtiyacı ortadan kalkar. Karar belgede yazılıdır, herkes okuyabilir.
ADR Nasıl Yazılır?
Temel Format
# ADR-001: PostgreSQL Kullanımı
## Durum
Kabul Edildi (2026-01-15)
## Bağlam
Projemiz ilişkisel veri yapısına sahip ve
ACID uyumlu bir veritabanına ihtiyaç duyuyor.
Ayrıca JSON desteği ve full-text search gereksediliyor.
## Karar
Ana veritabanı olarak PostgreSQL 16 kullanacağız.
## Sonuçlar
### Olumlu
- Güçlü ACID desteği
- JSON/JSONB ile esnek veri modeli
- Row Level Security (RLS) ile güvenlik
- Ücretsiz ve açık kaynak
### Olumsuz
- NoSQL çözümlerde daha kolay olan bazı
işlemler ek efor gerektirecek
- Yatay ölçekleme MongoDB'ye göre daha karmaşık
İyi Bir ADR'ın Özellikleri
- Kısa ve öz — 1-2 sayfa yeterli
- Bağlam odaklı — Sadece ne değil, neden kararı
- Değiştirilemez — Eski ADR'lar silinmez, yenisi ile supersede edilir
- Numaralı — Kronolojik sıralama
ArchLog: ADR'lar İçin CLI Aracı
ADR yazmayı kolaylaştırmak için ArchLog aracını geliştirdim. ArchLog şunları sunar:
Özellikler
- 5 CLI komutu — init, new, list, show, serve
- Markdown şablon — Otomatik ADR oluşturma
- Web Viewer — Dark-themed görsel arayüz
- İlişki yönetimi — ADR'lar arası bağlantılar
- Durum iş akışı — Proposed → Accepted → Deprecated
Hızlı Başlangıç
npx archlog init
npx archlog new "PostgreSQL Kullanımı"
npx archlog serve
Bu üç komutla ADR sisteminiz hazır.
Gerçek Dünya Örnekleri
BilgeOne Projesi
BilgeOne SaaS platformunu geliştirirken onlarca mimari karar aldık:
- ADR-001: Next.js 14 seçimi
- ADR-005: Multi-tenant mimari yaklaşımı
- ADR-012: Supabase Row Level Security stratejisi
Her karar belgelendi, her değişiklik izlenebilir hale geldi.
ADR vs Diğer Dokümantasyon
| Yöntem | Avantaj | Dezavantaj | |--------|---------|------------| | ADR | Yapılandırılmış, izlenebilir | Disiplin gerektirir | | Wiki | Esnek, detaylı | Hızla güncelliğini yitirir | | Confluence | Zengin format | Aranabilirlik zayıf | | Kod yorumları | Koda yakın | Büyük resmi göremez |
Sonuç
ADR yazmak, yazılım mühendisliğinde en yüksek getiri/efor oranına sahip pratiklerden biridir. 10 dakikada yazılan bir ADR, ekibin aylar sonra saatlerce tartışmasını önler.
ADR pratiğini interaktif olarak öğrenmek için LabLudus platformundaki Architect kariyer yolunu takip edebilirsiniz.