TL;DR: ADR (Architecture Decision Records) mimari kararların “neden”ini belgeler, OpenSpec 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 OpenSpec.
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, OpenSpec “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ştirilen bu yaklaşım1, özellikle uzun ömürlü projelerde “neden bu kararı verdik?” sorusuna yanıt bulmayı 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 yapmaya karar verildiğini ve nedenini belirtir
- Consequences: Kararın olumlu ve olumsuz 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 nedenini hatırlamak zorlaşır. “Neden Redux yerine Zustand kullandık?”, “Neden monolith yerine microservice tercih ettik?” gibi sorular, ADR olmadan cevapsız kalır.
AWS’in 2025 yılında yayımladığı kılavuzda belirtildiği üzere2:
Bir mimari karar kaydı (ADR), çözüm mimarının 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çeler sunar.
OpenSpec
OpenSpec, AI destekli kodlama asistanlarıyla çalışırken spec-driven development (SDD) yaklaşımını benimseyen bir framework’tür3. Temel felsefesi, implementasyona başlamadan önce “ne yapılacağını” netleştirmek ve hem insan hem de AI paydaşlarının aynı sayfada olmasını sağlamaktır.
OpenSpec’in yaşam döngüsü üç aşamadan oluşur:
- Propose: İnsan ve AI kodlama asistanı, spec üzerinde anlaşır
- Implement: Onaylanan spec’e göre kod yazılır
- Archive: Değişiklikler canlı dokümantasyona dahil edilir
Neden OpenSpec?
AI kodlama asistanları (Claude, Cursor, Gemini, GitHub Copilot, vb.) güçlü araçlardır, ancak net talimatlar olmadan beklenmedik sonuçlar üretebilirler. OpenSpec, bu belirsizliği ortadan kaldırarak:
- Implementasyon öncesi gereksinimleri kilitler
- Deterministik ve gözden geçirilebilir çıktılar sağlar
- Kodun “ne yapması gerektiğini” canlı dokümantasyon olarak korur
ADR vs OpenSpec: Temel Farklar
| Aspect | ADR | OpenSpec |
|---|---|---|
| Odak | WHY (Neden bu yaklaşım?) | WHAT + HOW (Ne yapılacak, nasıl test edilecek?) |
| Zamanlama | Karar sonrası | İmplementasyon öncesi |
| Format | Lightweight (context, decision, consequences) | Formal (requirements, scenarios, specs) |
| Yaşam Döngüsü | Bir kez yaz, nadiren güncelle | Proposal → Implement → Archive |
| 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 birbirinin alternatifi değil, tamamlayıcısıdır. Tipik bir senaryo şöyle işler:
flowchart TD
A[1. Yeni feature geliyor] --> B[OpenSpec proposal oluştur - WHAT]
A --> C[ADR yaz - WHY]
B --> D[openspec/changes/add-2fa/]
D --> E[proposal.md<br/>Ne değişecek]
D --> F[tasks.md<br/>Implementation checklist]
D --> G[specs/<br/>Requirements + scenarios]
C --> H[docs/decisions/005-2fa-totp-vs-sms.md<br/>Neden TOTP seçildi, SMS neden reddedildi]OpenSpec, feature’ın “ne” olduğunu tanımlarken, ADR o feature içindeki kritik teknik kararların “neden”ini belgeler.
Interview Aşaması (2025+)
Modern AI kodlama asistanları, implementasyon öncesi interview aşamasını destekliyor:
| Tool | Yaklaşım | Çıktı |
|---|---|---|
| Claude Code | AskUserQuestion + Plan Mode | plan.md |
| Gemini CLI | Conductor + Onboarding Interview | product.md, tech_stack.md |
Bu aşama, OpenSpec’in “Propose” aşamasını güçlendirir:
flowchart TD
A[1. Yeni feature geliyor] --> B[Interview]
A --> C[OpenSpec proposal - WHAT]
A --> D[ADR - WHY<br/>kritik karar varsa]
B --> E[AI asistan clarifying questions sorar]
E --> F["Bu API fail-fast mı retry mi?"]
E --> G["Auth gerektiriyor mu?"]
E --> H[Cevaplar spec'e dahil edilir]
C --> I[Interview çıktıları ile zenginleştirilmiş]Avantajları:
- 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
Ne Zaman Hangisi?
| Durum | Yaklaşım |
|---|---|
| Feature/capability ekleme | OpenSpec |
| Breaking API change | OpenSpec |
| Kütüphane X vs Y seçimi | ADR |
| Mimari pattern kararı | ADR |
| Bug fix | Sadece commit message |
Worktree ile Workflow
OpenSpec’in aşamalarını git worktree ile birleştirmek, paralel çalışmayı mümkün kılar:
| Aşama | Worktree? | Sebep |
|---|---|---|
| Proposal | Hayır | Sadece markdown, reject edilebilir |
| Implementation | Evet | Kod değişikliği, izolasyon önemli |
| Archive | Hayır | Merge sonrası, sadece dosya taşıma |
# 1. Proposal (main'de)
openspec/changes/add-feature/
├── proposal.md # Review için hazır
├── tasks.md
└── specs/
# 2. Approval sonrası worktree
git worktree add ../project-add-feature -b feat/add-feature
cd ../project-add-feature
# 3. Implement (worktree'de)
# ... kod yaz ...
# 4. PR & Merge
# 5. Archive (main'de)
openspec archive add-feature --yesBu yaklaşım, büyük feature’larda main branch’te conflict oluşmasını engeller.
Pratik Uygulama
Projenize bu sistemleri eklemek için minimum iki dosya yeterlidir:
docs/decisions/_TEMPLATE.md- ADR şablonuCLAUDE.mdveya proje konfigürasyonunda referans
ADR şablonu şu yapıda olabilir:
# ADR-XXX: Title
## Status
Proposed | Accepted | Deprecated | Superseded by ADR-YYY
## Date
YYYY-MM-DD
## Context
Problemi ve mevcut durumu açıkla.
## Decision
Ne yapmaya karar verdik ve neden?
## Consequences
### Positive
- Fayda 1
### Negative
- Trade-off 1
## Alternatives Considered
- Alternatif A: Neden reddedildiSonuç
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. OpenSpec implementasyon öncesi netlik sağlarken, ADR kararların arkasındaki mantığı sonraki süreçlere aktarır.
İkisi birlikte: tam context (ne + neden + nasıl).
İ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
- Claude Code: Best Practices for Agentic Coding
- Gemini CLI Conductor: Context-Driven Development
Footnotes
- Michael Nygard, Documenting Architecture Decisions, 2011 ↩
- AWS Prescriptive Guidance, ADR Process ↩
- Fission AI, OpenSpec: Spec-driven development for AI coding assistants ↩