Bu yazı, ADR ve spec-driven development’ın temellerini ele aldığım yazının devamıdır. Temeller tanıdıksa, şimdi araçların nasıl evrildiğine ve günümüzde AI destekli bir spec-driven iş akışının nasıl çalıştığına bakalım.
Evrim: OpenSpec’ten Brainstorm + Court’a
İlk ADR yazısını Ocak 2026’da yayımladığımda OpenSpec’i aktif olarak kullanıyordum. Birkaç ay içinde araçlar evrildi, ama temel ilke aynı kaldı: önce spec, sonra kod. Court skill’i, Decision Gate v2: Multi-AI Tribunal yazısında ele aldığım multi-AI değerlendirme yaklaşımını uyguluyor. Açık kaynak: ceaksan/decision-gate.
Güncel Akış
| Aşama | Eski (OpenSpec) | Güncel | Ne Değişti |
|---|---|---|---|
| Spec oluşturma | openspec proposal | Brainstorm skill | AI asistan interview ile spec üretiyor, iteratif |
| Değerlendirme | Manuel review | Court (Multi-AI Tribunal) | Birden fazla model çapraz değerlendirme yapıyor |
| Karar kaydı | Ayrı ADR dosyası | Court ADR çıktısı | Court otomatik ADR üretiyor |
| İmplementasyon | openspec apply | Plan + Implement | Behavioral requirements, max 5/iterasyon |
| Arşivleme | openspec archive | Retro | Pattern extraction, core-rules güncelleme |
Ne Aynı Kaldı?
- Spec-first yaklaşım: Kod yazmadan önce “ne” sorusuna yanıt vermek
- ADR ilkesi: Kritik kararların “neden”ini belgelemek
- Interview/brainstorm aşaması: Varsayımları erken açığa çıkarmak
- what + why + how to verify döngüsü
Ne Değişti?
- Tek araç yerine pipeline: OpenSpec tek bir CLI tool’du, şimdi brainstorm -> court -> plan -> implement -> critique -> retro zinciri var
- Multi-AI değerlendirme: Spec’i tek kişi/model değil, birden fazla model çapraz değerlendiriyor
- Otomatik ADR: Court skill kararı değerlendirirken ADR çıktısını da üretiyor
- Pattern learning: Retro aşaması projeden öğrenilen kalıpları
core-rules’a yazıyor
Ne Zaman Hangisi?
| Durum | Yaklaşım |
|---|---|
| Feature/capability ekleme | Brainstorm -> Court -> Plan |
| Breaking API change | Brainstorm -> Court -> Plan |
| Kütüphane X vs Y seçimi | Court (ADR çıktısı ile) |
| Mimari pattern kararı | Court (ADR çıktısı ile) |
| Teknoloji değerlendirme | Breakdown |
| Bug fix | Sadece commit message |
Worktree ile Workflow
Spec-driven development aşamalarını git worktree ile birleştirmek, paralel çalışmayı mümkün kılar. Main branch’te spec ve karar akışı yürürken, implementasyon izole bir worktree’de ilerler.
| Aşama | Worktree? | Sebep |
|---|---|---|
| Brainstorm + Court | Hayır | Sadece spec/karar, reject edilebilir |
| Implementation | Evet | Kod değişikliği, izolasyon önemli |
| Retro | Hayır | Merge sonrası, pattern extraction |
Altı aşamalı akış, pratikte şu komutlarla yürür:
# 1-2. Brainstorm + Court (main'de)
# /brainstorm -> spec oluşur
# /court -> GO/DEFER/KILL
# 3. GO kararı sonrası worktree
git worktree add ../project-add-feature -b feat/add-feature
cd ../project-add-feature
# 4. Implement (worktree'de)
# /implement -> plan gate + kod
# 5. Critique
# /critique -> PASS/REJECTED
# 6. PR & Merge, sonra retro (main'de)
# /retro -> pattern extraction
git worktree remove ../project-add-featureBu yaklaşım, büyük feature’larda main branch’te conflict oluşmasını engeller ve “implementation sırasında deneysel şeyler dene” özgürlüğü sağlar, çünkü worktree reddedilirse sadece silinir.
Pratik ADR Şablonu
Bu sisteme projeni dahil etmek için minimum iki dosya yeterlidir:
docs/adr/_TEMPLATE.md- ADR şablonuCLAUDE.mdveya proje konfigürasyonunda referans
ADR şablonu şu yapıda olabilir:
# ADR-NNN: Title
**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-YYY
**Spec:** [spec-name](../specs/spec-name.md) <!-- varsa -->
## 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 reddedildi
## Files Changed
| File | Change |
| ----------------- | ------------------------------- |
| `path/to/file.ts` | Yapılan değişikliğin açıklaması |Spec satırı, kararın bir spec dokümanına dayanması durumunda eklenir. Files Changed tablosu hangi dosyaların etkilendiğini somutlaştırır ve kararın kapsamını gösterir. Court skill otomatik ADR ürettiğinde bu şablonu doldurur.
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 |
Pipeline’ın üç aşaması da bu üç soruyu karşılar: Court “yapmalı mıyız”a yanıt verirken ADR’yi üretir, Brainstorm spec’i kurgular, implement + critique “nasıl doğruladık”ı gösterir.
Sonuç
Araçlar değişir: OpenSpec CLI yerini brainstorm + court pipeline’ına bıraktı. Temel ilke aynı: implementasyona başlamadan önce “ne” sorusuna yanıt ver, kritik kararlarda “neden”i belgele, büyük feature’ları worktree ile izole et.
Bu pipeline’ın öncesine, ADR ve SDD’nin neden ayrı rollere sahip olduğuna bakmadıysan temelleri ele aldığım yazıya dönüp başlamanı öneririm. ADR’lerin AI agent bağlamında nasıl çalıştırılabilir kısıtlamalara dönüştüğünü AI Agent’lar İçin Yaşayan Mimari Dokümantasyon yazısında inceliyorum. Bu araştırma bulgularını proje agnostik bir template’e dönüştürdüğüm Living Architecture projesine de göz atabilirsin.
İleri Okumalar
- OpenSpec - Spec-Driven Development
- Claude Code: Best Practices for Agentic Coding
- Gemini CLI Conductor: Context-Driven Development
- Git worktree dokümantasyonu
- 01 OpenSpec'in tek araçlı yaklaşımı yerini brainstorm -> court -> plan -> implement -> critique -> retro pipeline'ına bıraktı
- 02 Court skill, tek bir modelin değil birden fazla modelin çapraz değerlendirme yaptığı bir multi-AI tribunal
- 03 Git worktree, implementation aşamasını main branch'ten izole ederek paralel çalışmayı mümkün kılar
- 04 Retro aşaması öğrenilen pattern'ları core-rules'a yazarak süreci iteratif iyileştirir
- 05 Bug fix için sadece commit message yeterli; pipeline yeni capability ve mimari kararlar için
+ OpenSpec hala kullanılabilir mi?
Kullanılabilir ama günümüz AI asistanlarının brainstorm/plan/critique yetenekleri daha entegre bir deneyim sunuyor. Spec-first ilkesi değişmedi, araçlar daha akıcı hale geldi.
+ Court skill tam olarak ne yapıyor?
Bir spec veya karar teklifini birden fazla AI modeline (tribunal) paslayıp çapraz değerlendirme alır. Çıktı GO, DEFER veya KILL kararıdır ve otomatik ADR dosyası üretir.
+ Her feature için worktree gerekli mi?
Hayır. Küçük düzeltmeler ve tek dosya değişiklikleri main'de kalabilir. Worktree birkaç gün süren, çok dosyalı veya deneysel feature'lar için anlamlı.
+ Retro aşaması gerçekten gerekli mi?
Atlandığında öğrenme kaybolur. Retro, yaptığın işten ortaya çıkan kalıpları (hangi hata tekrar oldu, hangi shortcut işe yaradı) core-rules'a yazar ve bir sonraki iterasyonu iyileştirir.
+ Bu akış hangi araçlarla çalışıyor?
Claude Code'un skill sistemi ile doğrudan: /brainstorm, /court, /plan, /implement, /critique, /retro. Benzer pipeline'lar Cursor veya Gemini CLI'da custom command ile kurulabilir.