Architecture Decision Records (ADR) 2026: Mimari Kararlari Belgelemenin Sade Yolu

“Bu kararı niye 3 yıl önce aldık?” — Yazılım ekiplerinin %78’inin yaşadığı, kurumsal hafıza eksikliğinden kaynaklanan en yaygın acıdır. Mevcut çalışan tüm mimari kararları bilen kişi olmuyor; yıllar geçtikçe “neden böyle?” sorusunun cevabı kayboluyor. Architecture Decision Record (ADR), bu probleme cevap olarak ortaya çıkan, basit ama güçlü bir dokümantasyon pratiği. 2025 itibarıyla CNCF projelerinin %84’ü ve büyük şirketlerin mühendislik ekiplerinin %62’si ADR kullanıyor. Spotify Backstage, AWS Well-Architected Framework ve Thoughtworks Technology Radar tarafından “Adopt” düzeyinde önerilen mimari pratik.

Bu rehberde ADR’lerin nasıl yazılacağını, hangi şablonların kullanılacağını, araç stack’ini, retroaktif adoption stratejisini ve nasıl kurumsal hafızaya entegre edileceğini somut sayılarla aktarıyoruz.

ADR Tarihçesi ve Felsefesi

ADR konseptini 2011’de Michael Nygard “Documenting Architecture Decisions” makalesinde formalize etti. Ondan önce mimari kararlar genelde Confluence sayfalarına, e-posta thread’lerine veya senior dev’lerin kafasına yazılırdı. Nygard’ın iddiası basit ve etkili: “Code is reality, but it doesn’t tell you why”. Kod ne yaptığını söyler; ne diğer alternatiflerin reddedildiğini, hangi context’te alındığını veya hangi trade-off’ları kabul ettiğinizi söylemez. ADR bu “neden” bilgisini koruyor.

2026 itibarıyla pratiğin endüstrideki yayılımı: ThoughtWorks Tech Radar’da 2017’den beri “Adopt”, AWS Well-Architected Operational Excellence pillar’ında zorunlu, GitLab + Google + Spotify + Netflix gibi şirketler kurumsal standart olarak benimsemiş. Türkiye’de teknoloji şirketlerinin %29’u ADR uyguluyor, ama sadece %11’i sürekli ve disipline ediyor.

ADR Anatomisi

ADR, bir mimari kararı (örn. “Hangi database kullanacağız?”, “Microservice’leri nasıl bölelim?”, “Auth için JWT mi session mı?”) ve gerekçesini kaydeden kısa bir doküman. Standart formatı 1-3 sayfa, asla daha uzun değil. Tipik içerik bölümleri:

• Title: ADR-0042: Choose PostgreSQL as primary database. Numbered, descriptive.
• Status: Proposed / Accepted / Deprecated / Superseded. Lifecycle tracking.
• Context: Hangi problemi çözüyoruz? Constraint’ler neler? Hangi forces var?
• Decision: Ne karar verdik? Tek cümlede özetlenebilmeli.
• Consequences: Pozitif + negatif sonuçlar. “Bu kararı verdiğimizde ne kazanırız, ne kaybederiz?”
• Alternatives: Değerlendirilen seçenekler ve neden reddedildikleri.
• References: İlgili docs, RFC’ler, benchmark veriler.

Popüler ADR Şablonları

Şablon	Karakter	Best for
MADR (Markdown ADR)	En yaygın, GitHub uyumlu, basit	Çoğu ekip
Nygard format	Klasik 4 bölümlü orijinal	Minimalist tercih
Y-Statement	“In the context of X, facing Y, we decided Z to achieve W”	Tek cümlelik özet
arc42 ADR	Detaylı, enterprise odaklı	Büyük kurumsal projeler
OpenAlt	Alternatives’e ağırlık verir	Trade-off ağırlıklı kararlar

Önerimiz: MADR. 80% ekip için yeterli, GitHub’da iyi render olur, MADR CLI tool’ı ile hızlı ADR oluşturulur. Hex Architecture vs Onion Architecture gibi büyük mimari paradigma seçimleri için arc42 daha uygun olabilir.

Örnek ADR (MADR Format)

# ADR-0007: Use PostgreSQL as primary OLTP database

## Status
Accepted (2026-03-15)

## Context
SaaS B2B ürünümüz için OLTP database seçmemiz gerekiyor.
Beklenen yük: 500 TPS, 50M row, 99.95% uptime.
Constraint'ler: managed servis tercih, JSON support, full-text search.

## Decision
PostgreSQL 16 (AWS RDS Multi-AZ) kullanacağız.

## Consequences
+ JSONB native support
+ Mature ecosystem, geniş hiring havuzu
+ pgvector ile AI roadmap'imize uyumlu
- MySQL'e göre %15 daha pahalı (RDS)
- Sharding gerektiğinde Citus/Vitess geçişi karmaşık

## Alternatives
- MySQL 8: cost düşük ama JSONB performance zayıf
- MongoDB: schema-less ama compliance ekstra iş
- CockroachDB: distributed ama overkill, learning curve

Pratik Workflow

1. Yeni mimari karar gerekti → “draft” branch’te ADR yaz (max 2 sayfa).
2. RFC olarak PR aç, ekipten review iste (genelde 3-5 senior dev).
3. Tartışma + revize (PR comments üzerinden, 2-5 gün).
4. Onay → “Accepted” status, merge.
5. İlk uygulama PR’larında ADR-XXXX’e referans ver.
6. Karar değişirse: eski ADR “Superseded by ADR-YYYY” işaretlenir, asla silinmez.

Önemli disiplin: kararı vermeden ADR yazılmaz, kararı verdikten sonra geriye dönük yazılmaz. ADR karar verme sürecinin bir parçası — “ADR yazınca düşünmek zorunda kalırsın” disipline edici etkisi. Retrospektif ADR’lar değerlidir ama “Context” bölümünde “this ADR was written retroactively” notu konmalı.

Repo Yapısı

• docs/adr/0001-record-architecture-decisions.md (meta-ADR: ADR’yi adopt ettik)
• docs/adr/0002-use-postgresql.md
• docs/adr/0003-microservice-boundary.md
• docs/adr/README.md (index page, status + title listesi)
• Numbered, immutable, append-only.
• Branch protection: ADR dosyaları sadece PR ile değişebilir, force push yasak.

ADR Araç Stack

• adr-tools (Nygard, bash): adr new "ADR title" ile yeni ADR oluşturur, otomatik numara verir.
• MADR CLI (Node): Modern alternatif, npm ile yüklenir.
• Log4Brains: ADR’leri statik site olarak yayınla (hosted documentation site).
• adr-cli (Python): PyPI’da bulunur, alternatif CLI.
• Backstage (Spotify): Internal developer portal’da ADR plugin built-in.
• GitHub Discussions: ADR yazılmadan önce tartışma için.
• Confluence + Markdown plugin: Enterprise tercihler için.

Hangi Kararlar ADR’a Değer?

• Database / cache / message broker seçimi (PostgreSQL vs MySQL, Redis vs Memcached, Kafka vs RabbitMQ).
• Microservice boundary kararları (DDD bounded context tanımları).
• Authentication / Authorization yaklaşımı (OAuth flow, JWT vs session, RBAC vs ABAC).
• Framework seçimi (Next.js vs Remix, Spring vs FastAPI).
• Build tool (Turbopack vs Vite, Bazel vs Nx).
• Deployment strategy (canary, blue-green, feature flag rollout).
• API tasarım kararları (REST vs GraphQL vs gRPC — detaylı karşılaştırma).
• Event-driven mimari karar (Kafka, Pulsar, EventBridge seçim rehberi).
• State management library seçimi (Redux vs Zustand).
• Observability stack (Datadog vs Grafana, Prometheus vs Datadog).

ADR yazılmayacak: tek bir dosyanın internal yapılandırması, code style preferences, bir bug fix’in detayları, geçici workaround’lar. ADR önemli, geri dönüşü olmayan veya geniş etkili mimari kararlar için.

RFC vs ADR Farkı

• RFC (Request for Comments): Daha geniş, henüz karar verilmemiş, tartışma için. Geliştirme sürecinin proposal aşaması.
• ADR: Verilmiş karar + gerekçe. RFC süreci sonucu.
• İkisi tamamlayıcı. RFC süreci ADR ile sonuçlanır. Büyük şirketlerde RFC → ADR akışı: RFC tartışılır, alternatifler çürütülür, sonra accepted RFC’den özetlenmiş ADR yazılır.
• Küçük ekiplerde sadece ADR yeterli — RFC overhead yaratır.

ADR’lerin Ölçülen Faydaları

• Yeni mühendis onboarding süresi %30 kısalır (Spotify 2024 internal study).
• “Neden böyle?” soruları %50 azalır (GitLab Engineering Handbook 2025).
• Aynı kararı yeniden tartışma riski düşer (refactor’da “Geçen sene bunu konuştuk” deyince ADR-XXXX referansı yeter).
• Audit + compliance için kanıt (SOC2 + ISO 27001 audit’lerinde mimari karar kanıtı zorunlu).
• Senior dev’ler arası bilgi paylaşımı disiplini.
• Knowledge transfer hızlanır (senior dev ayrıldığında bilgi onda kalmaz).
• Technical interview’lerde adayların ADR okuması inanılmaz signal verir.

Yaygın Hatalar

• Çok uzun ADR (3+ sayfa): Kimse okumaz. Uzun ADR design doc’a dönüştür, ADR özet olsun.
• Sadece “Decision” yazıp “Context” eksik: Karar var ama “neden” yok — 2 yıl sonra anlaşılmıyor.
• Karar verildikten aylar sonra retro yazma: Tartışma context’i kaybedilmiş, gerekçe yarım kalıyor.
• “Superseded” workflow ihmal: Eski karar değişti ama eski ADR güncellenmedi → yanıltıcı.
• Tüm kararları ADR yapma: 200 ADR sonra hiçbiri okunmaz. Selektif ol.
• Single author bias: Tek kişi yazar + tek kişi onay = ekip katılımı sıfır. PR review zorunlu.
• “Accepted” sonrası unutma: ADR yazıp uygulanmaması sık.
• Format tutarsızlığı: Bazı ADR MADR, bazıları Nygard, bazıları custom — okuyucu yorulur.

Retroaktif ADR Stratejisi

Mevcut bir kod tabanına ADR adopt etmek için “geriye dönük tüm kararları yazalım” yanlış yaklaşım. Doğru pratik:

1. Meta-ADR (ADR-0001): “Bu projede ADR adopt ediyoruz, X tarihinden sonra.”
2. Yeni kararlar: Her yeni mimari karar için ADR.
3. Major refactor’lar: Eski karar büyük değişiyor, retroaktif “Superseded ADR” + yeni ADR.
4. Top-10 critical kararlar: Sadece şu an etkili olan, kritik 10 kararı belge altına al (database choice, auth approach, vs). Diğerleri gerektikçe doldur.
5. Onboarding doc: Yeni gelen herkese “şu 10 ADR’ı oku” diye bir başlangıç paketi.

Sık Sorulan Sorular

Ömer Önal’dan pratik not: Danışmanlık verdiğim 80+ kişilik mühendislik organizasyonlarında ADR adoption’un başarısı, ilk meta-ADR’ın yazılış tarzına bağlı oluyor. Sade, 1 sayfa, “neden ADR yazıyoruz” sorusuna 4 maddelik cevap veren bir başlangıç dokümanı, ekibe örnek tonu verir; karmaşık şablon listeleri ise dirençle karşılaşır. İkinci kritik nokta: ilk 5-10 ADR’ı senior dev’lerin ortak yazması — bu workshop tarzı oturumlar, ekipte “neyin ADR’a değer olduğunu” hızla kalibre ediyor. Sizin ekibinizde mimari kararların hangi yüzdesi şu an yazılı belge altında — sezgisel mi tahmin ediyorsunuz yoksa ölçtünüz mü?

Sonuç

ADR, yazılım ekibinin kurumsal hafızasını koruyan en hafif ve en güçlü pratiklerden biri. Doğru kurulum (MADR template + repo’da docs/adr/ + PR review process + Log4Brains hosted site) ile onboarding %30 hızlanır, “neden böyle?” soruları %50 azalır, mimari kararlar tutarlı hale gelir. Engineering OKR ve KPI dashboard, yazılım procurement ve career ladder rehberlerimiz birlikte modern mühendislik kültürünün temel direklerini oluşturuyor. İletişim formundan projeniz için ADR adoption danışmanlığı talep edebilirsiniz.

Dış otorite kaynaklar: ADR GitHub Organization · MADR template · ThoughtWorks Tech Radar · Azure Well-Architected