ADR (Architecture Decision Records) mimari kararların “neden”ini belgeler, spec-driven development ise implementasyon öncesi “ne yapılacağını” tanımlar. AI destekli geliştirmede ikisi birlikte kullanıldığında tam context sağlar: what + why + how to verify.
KISS, SoC ve benzeri prensiplerin yer aldığı yazı serisine, AI destekli geliştirme süreçlerinde önem kazanan iki kavramla devam etmek istiyorum: Architecture Decision Records (ADR) ve spec-driven development (SDD).
Bu iki yaklaşım, ilk bakışta benzer görünse de temelde farklı soruları yanıtlar. ADR “neden bu yolu seçtik?” sorusuna odaklanırken, SDD “ne yapacağız ve nasıl doğrulayacağız?” sorusunu ele alır.
Peki, nedir bu iki kavram ve birlikte nasıl kullanabiliriz?
Architecture Decision Records (ADR)
ADR, bir yazılım projesinde alınan mimari kararları ve bu kararların arkasındaki gerekçeleri belgeleyen yapılandırılmış dokümanlardır. Michael Nygard tarafından 2011 yılında popülerleştirilen1 bu yaklaşım, özellikle uzun ömürlü projelerde “bu kararı neden aldık?” sorusunu yanıtlamayı kolaylaştırır.
Bir ADR genellikle şu bileşenlerden oluşur:
- Status: Proposed, Accepted, Deprecated, Superseded
- Context: Problemi ve mevcut durumu açıklar
- Decision: Ne karar verildiğini ve neden alındığını belirtir
- Consequences: Kararın pozitif ve negatif sonuçlarını listeler
Neden ADR?
Yazılım projeleri zamanla büyür ve ekip üyeleri değişir. Altı ay önce alınan bir kararın neden verildiğini hatırlamak zorlaşır. “Neden Zustand yerine Redux kullandık?”, “Neden microservice yerine monolith seçtik?” gibi sorular, ADR olmadan yanıtsız kalır.
AWS’nin 2025 rehberinde2 belirtildiği gibi:
Bir mimari karar kaydı (ADR), bir solutions architect’in en önemli çıktılarından biridir. Bu kayıt, tasarım süreci boyunca aldığınız mimari kararları belgeler ve her karar için bağlama özgü gerekçe sağlar.
Spec-Driven Development (SDD)
Spec-driven development, AI destekli kodlama asistanlarıyla çalışırken implementasyon öncesi “ne yapılacağını” netleştiren yaklaşımdır. Temel felsefesi, hem insan hem de AI paydaşlarının aynı sayfada olmasını sağlamaktır.
Bu yaklaşımı AI ekosisteminde popülerleştiren framework’lerden biri OpenSpec’tir3. OpenSpec, propose-implement-archive yaşam döngüsüyle spec yönetimini formalize etti. Ancak ekosistem hızla evrildi: bugün AI kodlama asistanlarının kendi brainstorming, planlama ve değerlendirme yetenekleri aynı işlevi daha entegre biçimde yerine getiriyor.
Yaklaşım değişmedi, araçlar evrildi.
Spec-Driven Development’ın Temel Faydaları
AI kodlama asistanları (Claude, Cursor, Gemini, GitHub Copilot vb.) güçlü araçlar olsa da, net talimatlar olmadan beklenmedik sonuçlar üretebilir. Spec-driven yaklaşım bu belirsizliği ortadan kaldırır:
- Implementasyon öncesi gereksinimleri kilitler
- Deterministik ve gözden geçirilebilir çıktı sağlar
- “Kodun ne yapması gerektiği” bilgisini yaşayan dokümantasyon olarak tutar
ADR vs SDD: Temel Farklar
| Boyut | ADR | Spec (SDD) |
|---|---|---|
| Odak | WHY (Neden bu yaklaşım?) | WHAT + HOW (Ne yapılacak, nasıl test edilecek?) |
| Zamanlama | Karar sonrası | İmplementasyon öncesi |
| Format | Hafif (context, decision, consequences) | Resmi (requirements, senaryolar, spec) |
| Yaşam Döngüsü | Bir kez yazılır, nadiren güncellenir | Spec -> Değerlendir -> İmplement -> Arşivle |
| Kapsam | Mimari/teknik kararlar | Feature/capability değişiklikleri |
| Hedef Kitle | Mimarlar, geliştiriciler, paydaşlar | AI asistanlarıyla çalışan geliştiriciler |
Birlikte Kullanım
Bu iki yaklaşım alternatif değil, tamamlayıcıdır. Spec feature’ın “ne” olduğunu tanımlarken, ADR o feature içindeki kritik teknik kararların “neden”ini belgeler. Örneğin bir 2FA implementasyonu için spec, feature’ın hangi akışları kapsadığını ve session katmanına nasıl entegre olduğunu anlatır; ADR (docs/decisions/005-2fa-totp-vs-sms.md gibi) ise neden TOTP seçildiğini, SMS’in neden reddedildiğini belgeler.
Interview Aşaması
Modern AI kodlama asistanları, implementasyon öncesi bir interview aşamasını destekliyor:
| Araç | Yaklaşım | Çıktı |
|---|---|---|
| Claude Code | AskUserQuestion + Plan Mode | plan.md |
| Gemini CLI | Conductor + Onboarding Interview | product.md, tech_stack.md |
Bu aşama spec oluşturma sürecini güçlendirir. AI asistanı netleştirici sorular sorar (“Bu API fail-fast mı yoksa retry mı olsun?”, “Auth gerekiyor mu?”) ve yanıtlar kod yazılmadan önce spec’e yansır.
Faydaları:
- Assumptions açığa çıkar: Code review’da değil, başlangıçta
- Decision tree önceden navigate edilir: Her soru bir fork, her cevap çözüm alanını daraltır
- Spec daha deterministik olur: AI belirsizlik olmadan execute eder
Temellerden İş Akışına
Araçlar hızla evrildi. Ocak 2026’da tek bir openspec proposal komutu olan akış, bugün brainstorm -> court -> plan -> implement -> critique -> retro pipeline’ına dönüştü; büyük feature’larda implementasyonu main’den izole eden git worktree de işin içinde. Operasyonel katmanı, multi-AI tribunal’ın nasıl çalıştığını, worktree akışının nasıl göründüğünü ve ADR’lerin nasıl otomatik üretildiğini OpenSpec’ten Brainstorm + Court’a: Worktree ile Spec-Driven İş Akışı yazısında ele aldım.
ADR ve SDD arasındaki farkı içselleştirdiysen, sıradaki doğal adım bu yazı. Pratik bir ADR şablonu da orada bulunuyor.
Decision Gate ile İlişki
ADR ve spec, bir kararın “neden”ini ve “ne”sini belgeler. Ancak öncesinde bir soru daha vardır: “yapmalı mıyız?” Bu soruyu yanıtlayan framework için bkz. Decision Gate: Vibe Coding’in Eksik Parçası.
| Soru | Araç | Zamanlama |
|---|---|---|
| Yapmalı mıyız? | Court / Decision Gate | Pre-decision |
| Neden bu yolu seçtik? | ADR (Court çıktısı) | Post-decision |
| Ne yapacağız, nasıl doğrulayacağız? | Spec (Brainstorm) | Pre-implementation |
Sonuç
AI destekli geliştirme araçlarının yaygınlaşmasıyla birlikte, “ne yapacağız” ve “neden bu yolu seçtik” sorularına sistemli yanıtlar vermek daha da önemli hale geliyor. ADR ve spec birbirine alternatif değil, farklı soruların cevabı. Birlikte kullanıldıklarında AI agent’ın ya da gelecekteki takım arkadaşının ihtiyaç duyduğu context tamamlanır.
Bu iki katmanın operasyonel bir pipeline’a (brainstorm, court, plan, implement, critique, retro) nasıl dönüştüğünü ve git worktree’nin akışa nasıl oturduğunu Worktree ile Spec-Driven İş Akışı yazısında inceledim.
ADR’lerin AI agent bağlamında nasıl çalıştırılabilir kısıtlamalara dönüştüğünü, Codified Context yaklaşımını ve diğer mimari dokümantasyon alternatiflerini AI Agent’lar İçin Yaşayan Mimari Dokümantasyon yazısında detaylıca inceliyorum. Bu araştırma bulgularını proje agnostik bir template’e dönüştürdüğüm Living Architecture projesini de inceleyebilirsiniz.
İleri Okumalar
- Architectural Decision Records
- OpenSpec - Spec-Driven Development
- AWS: Master ADRs Best Practices
- Google Cloud: Architecture Decision Records Overview
- Decision-Driven vs Spec-Driven Software Engineering
Footnotes
- Michael Nygard, Documenting Architecture Decisions, 2011 ↩
- AWS Prescriptive Guidance, ADR Process ↩
- Fission AI, OpenSpec: Spec-driven development for AI coding assistants ↩
- 01 ADR mimari kararların 'neden'ini belgeler; aylar sonra bile kararın arkasındaki gerekçe korunur
- 02 Spec-driven development implementasyon öncesi 'ne yapılacağını' tanımlar ve AI agent'lara tam context sağlar
- 03 İkisi birlikte kullanıldığında what + why + how to verify döngüsü tamamlanır
- 04 AI destekli geliştirmede spec olmadan kod üretmek bağlam kaybına ve hatalı çıktıya yol açar
- 05 Temel ilke sabit: önce spec, sonra kod. Araçlar evrilir, yaklaşım kalır
+ ADR (Architecture Decision Records) nedir?
ADR, bir yazılım projesinde alınan mimari kararları ve bu kararların arkasındaki gerekçeleri belgeleyen yapılandırılmış dokümanlardır. Michael Nygard tarafından 2011 yılında popülerleştirilmiştir.
+ Spec-driven development nedir ve ADR'den farkı nedir?
Spec-driven development, AI destekli kodlama asistanlarıyla çalışırken implementasyon öncesi gereksinimleri netleştiren yaklaşımdır. ADR 'neden bu yolu seçtik' sorusuna odaklanırken, spec 'ne yapacağız ve nasıl doğrulayacağız' sorusunu ele alır.
+ ADR ve spec birlikte nasıl kullanılır?
Spec feature'ın ne olduğunu tanımlarken, ADR o feature içindeki kritik teknik kararların nedenini belgeler. Birlikte kullanıldığında what + why + how to verify döngüsü tamamlanır.
+ AI destekli geliştirmede spec neden gerekli?
AI kodlama asistanları net talimatlar olmadan beklenmedik sonuçlar üretebilir. Spec, implementasyon öncesi gereksinimleri kilitleyerek deterministik ve gözden geçirilebilir çıktılar sağlar.