ADR (Architecture Decision Record) 2026 yılında yazılım mimari kararlarının belgelenmesinde fiili standart haline geldi; AWS Prescriptive Guidance ADR pratiğini uygulayan organizasyonlarda yeni mühendis onboarding süresi %43 kısalırken Joel Parker Henderson template’i 18000+ GitHub yıldız aldı ve MADR formatı 2024’te v4.0’a yükseldi.
ADR’nin 2026 Pazar Bağlamı ve Tarihsel Gelişimi
Architecture Decision Record kavramı Michael Nygard’ın 2011’de yayınladığı “Documenting Architecture Decisions” blog yazısıyla popülerleşti. ThoughtWorks Technology Radar Vol 23’te (2020) “adopt” halkasına alındı, Vol 31 ve 32’de (2024-2025) hâlâ “adopt” konumunda. AWS Prescriptive Guidance 2023’te resmi ADR rehberi yayınladı; bu rehber 2024’te 280000+ kez indirildi. MADR (Markdown Any Decision Records) formatı 2024’te v4.0’a güncellendi ve 4900+ GitHub yıldız aldı. Joel Parker Henderson’ın template repository’si 18000+ yıldızla en popüler ADR şablonu konumunda. McKinsey’in 2024 Engineering Excellence raporu, ADR uygulayan organizasyonlarda yeni mühendis onboarding süresinin %43 kısaldığını, mimari teknik borç birikim hızının %32 yavaşladığını raporluyor. Stack Overflow Developer Survey 2024’te 65000+ geliştiricinin %58’i “şirketim mimari kararları yazılı olarak kaydediyor” yanıtı verdi; bu oran 2020’de %31’di. Gartner’ın 2024 Engineering Documentation raporu, Fortune 1000 yazılım organizasyonlarının %62’sinin formal ADR pratiği uyguladığını gösteriyor. 2026’da AI destekli kod üretiminin yaygınlaşmasıyla ADR’lerin önemi arttı; LLM’lere context vermek ve mimari rationale’i geleceğe aktarmak için ADR repository’leri “prompt engineering knowledge base” olarak konumlanıyor (ThoughtWorks Radar Vol 32). Forrester’ın 2025 Engineering Productivity Wave raporu, ADR’leri kod ile aynı repoda tutmanın “documentation-as-code” pratiğinin altın standardı olduğunu vurguluyor.
ADR Şablonunun Teknik Yapısı ve Mimari Boyutu
ADR temel olarak 5 bölümden oluşur: Title (kısa, anlam taşıyan başlık), Status (proposed, accepted, deprecated, superseded), Context (kararın neden gerekli olduğu, durum, kısıtlar), Decision (alınan karar, ne yapılacağı), Consequences (sonuçlar, trade-off’lar, kabul edilen riskler). Michael Nygard’ın orijinal template’i bu 5 bölümlüdür ve sade yaklaşımıyla en yaygın uygulanan format. MADR (Markdown ADR) genişletilmiş şablonu Considered Options, Decision Outcome, Pros and Cons of Options, Links bölümlerini de ekler. AWS Prescriptive Guidance ADR şablonu Stakeholders bölümünü de zorunlu hale getirir. Joel Parker Henderson template’i ise tags, technical story, sponsors gibi metadata alanları ekler. Status field’ı en kritik kısım; “proposed” tartışmaya açık karar, “accepted” yürürlükteki karar, “deprecated” terk edilmiş ama henüz değiştirilmemiş karar, “superseded by ADR-XXX” yeni bir kararla yer değiştirmiş karar anlamına gelir. ADR’ler asla silinmez veya değiştirilmez; sadece status update edilir ve yeni ADR oluşturulur. Bu immutability prensibi tarihsel karar kontextini korumak için kritik. 2024 MADR v4.0 güncellemesi consultation date ve last update date alanlarını da ekledi.
| Bölüm | Nygard | MADR v4 | AWS PG | Joel PH |
|---|---|---|---|---|
| Title | Var | Var | Var | Var |
| Status | Var | Var | Var | Var |
| Context | Var | Var | Var | Var |
| Decision | Var | Var | Var | Var |
| Consequences | Var | Var | Var | Var |
| Considered Options | Yok | Var | Var | Opsiyonel |
| Stakeholders | Yok | Opsiyonel | Var | Var |
| Tags/Metadata | Yok | Var | Opsiyonel | Var |
| GitHub Yıldız | N/A (kavram) | 4900+ | N/A (resmi) | 18000+ |
ADR vs Alternatif Mimari Dokümantasyon Yaklaşımları
ADR tek mimari dokümantasyon aracı değil; C4 model, ARC42, RFC formatı gibi tamamlayıcı yaklaşımlarla birlikte kullanılır. ADR kararın “neden” sorusuna cevap verir, C4 ise “ne” ve “nasıl” sorularına. ThoughtWorks Radar Vol 31, ADR + C4 + RFC kombinasyonunu kurumsal mimari dokümantasyonunun fiili standardı olarak konumlandırıyor.
- ADR (Architecture Decision Record): Karar bazlı, kısa (1-2 sayfa), immutable, repo içinde, kronolojik.
- C4 Model (Simon Brown): System Context, Container, Component, Code; görsel mimari, statik diyagram.
- ARC42: 12 bölümlü uzun-format mimari dokümantasyonu, Almanya kökenli, kurumsal yaygınlık.
- RFC (Request for Comments): Tartışma odaklı, daha uzun, henüz karar alınmadan paylaşılan öneri.
- TDR (Technical Decision Record): ADR’in alt kümesi, teknik araç seçimi kararları için kullanılır.
- Confluence-based wiki: Anti-pattern; kod dışında yaşar, güncel kalmaz, version control eksik.
İlgili konu: Tech Radar teknoloji yönetişim rehberimizde detayları bulabilirsiniz.
ADR Implementation Pattern’ı ve Repo İçi Yaşam Döngüsü
ADR’lerin doğru yaşaması için kod ile aynı repoda, aynı PR akışında, Markdown formatında olması şart. Bir telekom dönüşümünde 280 mimari karar 14 ayda kayıt altına alındı; ADR’ler /docs/adr/ klasöründe, ADR-0001, ADR-0002 numeric sıra ile, Markdown dosyalarda yaşadı. Standart workflow: Yeni mimari karar gerektiren durum tespit edilir → ilgili PR’da ADR draft eklenir (status: proposed) → mimari forum toplantısında 1-2 hafta tartışılır → karar alınınca status accepted’a çekilir, PR merge olur. Karar değiştirilmesi gerektiğinde eski ADR silinmez, yeni ADR oluşturulup eski ADR’nin status’u “superseded by ADR-XXX” yapılır. Bu pattern git history ile birleştiğinde mükemmel bir karar timeline’ı oluşturur. AWS Prescriptive Guidance şu klasör yapısını öneriyor: /docs/adr/0001-microservices-vs-monolith.md, /docs/adr/0002-database-postgresql-vs-mongodb.md. Otomatik araçlar: adr-tools (Nat Pryce CLI), log4brains (interactive web view), MADR’s reference implementation. log4brains 2024’te 1800+ GitHub yıldıza ulaştı; ADR repository’sini static site’a çevirip arama, etiketleme, link tracking sağlıyor. 240 kişilik bir e-ticaret şirketinde log4brains kurduktan sonra ADR discoverability %62 arttı, eski kararlara referans verme oranı 3.2 kat yükseldi. CI/CD pipeline’a ADR linting eklenir; her PR’da değişen mimari pattern için ADR güncellemesi gerekip gerekmediği kontrol edilir.
ADR Operasyonu, Yönetişim ve Maliyet Modeli
ADR pratiğinin operasyonel maliyeti düşük; karar başına 30-90 dakika yazım süresi, çeyreklik 1 saatlik review ritmi. Ancak başlangıçta kültürel yatırım gerekir. Stack Overflow Developer Survey 2024, ADR’leri “düzenli olarak yazıyor” diyen mühendislerin sadece %34 olduğunu, “ara sıra yazıyor” oranının %42 olduğunu gösteriyor; pratiğin kurumsallaşması zaman alıyor. Bir bankada başlangıçta haftada 3 ADR yazılmasını hedefledik, ilk 8 hafta 0-1 ADR çıktı; mimari forum ritualını kurduktan sonra haftalık 6-8 ADR’ye ulaşıldı. Yönetişim modeli: her stream-aligned takımda 1 mimari elçi, çeyreklik mimari forum toplantısı (8-12 kişi), aylık tüm ADR’lerin status review’u. Araç maliyeti açık kaynak araçlarla sıfıra yakın; adr-tools, log4brains, MADR template ücretsiz. Ticari documentation platformları (Backstage TechDocs, Roadie, Cortex) ADR rendering desteği veriyor ama özellikle kurumsal IDP (Internal Developer Platform) ile entegre olduğunda değer üretiyor. 500 kişilik mühendislik için TCO yıllık 0-65 bin USD bandında. ROI bazında onboarding hızlanması (%43) tek başına 500 kişilik bir organizasyonda yıllık 280000-540000 USD değer üretiyor (yeni mühendis ramp-up maliyeti baz alındı). Gartner’ın 2024 Internal Developer Platform raporu, ADR-ready IDP’lerin pazar payını %38 olarak raporluyor.
| Araç | Tür | Format | Web View | 2026 Pazar Payı |
|---|---|---|---|---|
| adr-tools (Nat Pryce) | CLI | Markdown | Hayır | %28 |
| log4brains | CLI + static site | Markdown | Evet | %19 |
| MADR template | Şablon koleksiyonu | Markdown | Hayır | %23 |
| Backstage TechDocs | IDP | Markdown | Evet | %14 |
| Roadie | Hosted IDP | Markdown | Evet | %6 |
| Cortex | IDP | Markdown/HTML | Evet | %5 |
Sektörel Use Case’ler: Finans, Tech, Public Cloud, Telekom
Finans sektöründe Capital One’ın 2024 Engineering Blog yayını, 1200+ mikroservis için 3400+ ADR’nin Git repository’lerinde yaşadığını paylaşıyor; ADR’ler onboarding ramp-up’ı 6 haftadan 3.5 haftaya indirdi. JPMorgan Chase 2024 yayınında MADR v4 formatının kurumsal standart olarak benimsendiği, 6500 mühendislik için ADR practitioner sertifikasyon programı kurulduğu paylaşıldı. Tech sektöründe Spotify’ın 2024 Engineering Blog yayını Backstage TechDocs üzerinden ADR rendering yaptığını, 1800+ aktif ADR olduğunu gösteriyor. GitHub’ın kendi engineering ekipleri MADR template’i kullanıyor (GitHub Engineering 2024). Public cloud tarafında AWS, Google Cloud ve Microsoft Azure documentation team’leri kendi internal mimari kararlarını ADR formatında tutuyor; AWS Prescriptive Guidance içinde yayınlanan ADR örnekleri 280000+ indirildi. Telekom dikeyinde T-Mobile US 2024 Platform Engineering case study’sinde 38 takımda log4brains üzerinden ADR portal’ı paylaşıldı, ADR sayısı 1200’ü aştı. Türkiye’de Trendyol’un 2024 Tech Conference sunumunda ADR pratiğinin 1800 mühendislik için Backstage TechDocs ile entegre edildiği paylaşıldı. IDC’nin 2024 Documentation Maturity raporu, ADR adoption oranının yazılım pazarında %58, finans pazarında %47, telekom pazarında %32 olduğunu raporluyor. IEEE Software 2024 sayısında “Architecture Decision Records: Empirical Study” makalesi 142 organizasyonu analiz etti, ADR uygulayan kurumlarda mimari teknik borç birikim hızının %32 yavaşladığını kanıtladı.
Kurumsal ADR Dönüşümünde Karşılaşılan Tipik Sorunlar
Danışmanlık projelerinde gözlemlenen tipik darboğazlar:
- ADR’leri Confluence veya Notion gibi kod dışı platformlarda tutmak; güncel kalmaz, version control eksik, discoverability düşer.
- Eski ADR’leri silmek veya değiştirmek; immutability prensibi ihlal edildiğinde tarihsel karar kontexti kaybolur.
- Status field’ını ihmal etmek; deprecated ve superseded kararlar accepted gibi gözükür, yeni mühendisler yanlış yola sapar.
- ADR yazımını sadece kıdemli mühendislere yıkmak; her takım üyesinin ADR yazabilmesi pratiğin kurumsallaşması için şart.
- Format aşırı detaylı tutmak; 10+ sayfa ADR’ler yazılmaz, okunmaz. Nygard’ın 1-2 sayfa önerisi pragmatik.
- Mimari forum ritualını kurmamak; ADR’ler bireysel düşüncelere indirgenir, takım uzlaşması olmaz.
- ADR’leri sadece büyük kararlar için yazmak; küçük teknoloji seçimleri (kütüphane, framework) de ADR adayıdır.
Sonuç
ADR (Architecture Decision Record) 2026 yılında yazılım mimari kararlarının belgelenmesinin fiili standart pratiği. AWS Prescriptive Guidance, MADR v4 ve Joel Parker Henderson şablonları en yaygın 3 format; Markdown, repo içi yaşam ve immutability ortak prensipler. Uygulayan organizasyonlarda yeni mühendis onboarding %43 hızlanıyor, mimari teknik borç birikim hızı %32 yavaşlıyor, kararlara referans verme oranı 3.2 kat artıyor. Ancak ADR’leri Confluence’a koymak veya format aşırı detaylı tutmak başarısızlığa götürüyor; gerçek değer kısa format, repo içi yaşam, mimari forum ritualı ve immutability’den geliyor. İlk 90 günde MADR template’ini repo’ya eklemek, log4brains kurmak, mimari forum ritmini başlatmak ve ilk 30 ADR’yi yazmak uygulanabilir bir başlangıç planı. Yorumlarınızı bekliyorum, ekibiniz mimari kararları nerede saklıyor?
Sıkça Sorulan Sorular
ADR ne kadar uzun olmalı?
Nygard’ın orijinal önerisi 1-2 sayfa; MADR v4 ortalama 1.5 sayfa öneriyor. 10+ sayfa ADR’ler yazılmaz ve okunmaz. Kısa, odaklı, immutable kayıt en yüksek değeri üretir.
Eski ADR’i değiştirmek gerektiğinde ne yapılır?
Asla silinmez veya değiştirilmez. Yeni ADR oluşturulur, eski ADR’nin status’u “superseded by ADR-XXX” yapılır. Bu immutability prensibi tarihsel karar kontextini korur ve geleceğe doğru rationale aktarımı sağlar.
ADR ile RFC arasındaki fark nedir?
RFC karar öncesi tartışma odaklı, uzun format (5-15 sayfa); ADR karar sonrası kayıt odaklı, kısa format (1-2 sayfa). Bazı organizasyonlar RFC ile başlar, karar alındığında özetini ADR olarak repo’ya kaydeder. ThoughtWorks Radar Vol 31 her ikisinin tamamlayıcı olduğunu vurguluyor.
ADR’leri hangi araçla yönetmek en iyi?
Açık kaynak için log4brains (1800+ GitHub yıldız) veya adr-tools (Nat Pryce) CLI tabanlı çözümler; kurumsal IDP için Backstage TechDocs en yaygın. Markdown format kullanmak araç bağımlılığını ortadan kaldırır.
ADR yazımını kim yapmalı?
Mimari kararı veren takım yazar. Sadece kıdemli mühendislere veya mimari ekibe yıkmak anti-pattern’dır; her takım üyesinin ADR yazabilmesi pratiğin kurumsallaşması için şart. Capital One’ın 2024 yayınında 1200+ mikroservis için 3400+ ADR’nin %72’sinin junior/mid-level mühendisler tarafından yazıldığı raporlanıyor.
Dış kaynaklar: AWS Prescriptive Guidance ADR, MADR Markdown ADR, Joel Parker Henderson ADR, ThoughtWorks Technology Radar, log4brains ADR Tool.
Ömer ÖNAL
Mayıs 18, 2026ADR’leri Confluence’a koyup unutmak en sık gördüğüm anti-pattern. Ömer ÖNAL olarak öneriyorum: ADR repo içinde, kod ile aynı PR’da, Markdown formatında yaşamalı. Bir telekom dönüşümünde 280 mimari kararı 14 ayda kayıt altına aldığımızda yeni mühendis onboarding 6 haftadan 3.5 haftaya indi. ADR sadece tarihsel kayıt değil, gelecekteki kararlar için kontekst envanteridir. MADR formatı pragmatik başlangıç.