
“Görev listesine arama ekleyelim” bir fikirdir. “Arama alanı boşken bütün görevler görünsün” bir davranış beklentisidir. “Mevcut liste bileşenine arama durumu ekleyelim” ise teknik bir uygulama adımıdır. Bu üç cümleyi birbirine karıştırdığımızda, henüz ürün kararını vermeden kod çözümüne atlayabiliriz.
Beşinci dersin bu yazısında fikri uygulanabilir bir plana çevireceğiz. Küçük bir özelliği örnek alarak gereksinimi, kabul kriterini, kapsamı ve teknik planı ayıracağız. Amaç her değişiklik için uzun belgeler üretmek değil; uygulama sırasında verilecek kararların hangilerinin önceden netleşmesi gerektiğini görmek.
Önce ürün kararlarını verin
Arama kutusunu eklemek birkaç satırlık bir değişiklik gibi görünebilir. Fakat kullanıcı açısından farklı seçenekler vardır: yalnızca başlıkta aramak, açıklamaları da taramak, yazdıkça filtrelemek, düğmeyle aramak, sadece yüklenmiş kayıtları veya sunucudaki bütün kayıtları aramak.
Bu seçenekler aynı ürünün farklı davranışlarıdır. Teknik plan, seçtiğiniz davranışı gerçekleştirmek için hazırlanır. Davranış seçilmeden hazırlanan plan ise varsayımlar üzerine kurulur. Özellikle “basit arama” gibi ifadelerin herkes için aynı anlamı taşıdığını düşünmeyin.
Serimizin örneğinde küçük, tamamı tarayıcıda yüklenmiş bir görev listesi var. Yalnızca başlıkta, yazdıkça ve Türkçe büyük/küçük harf farkını gözeten bir arama istiyoruz. Büyük bir veri kümesini sunucuda aramak bu örneğin kapsamı dışında. Başka bir projede bu başlangıç koşulları değişirse plan da değişmelidir.
Gereksinim ile kabul kriterini ayırın
Gereksinim, sistemin ne yapması gerektiğini söyler. “Kullanıcı görevleri başlığa göre filtreleyebilsin” bir gereksinimdir. Kabul kriteri, bu gereksinimin karşılandığını hangi gözlemle anlayacağımızı açıklar: “top yazıldığında ‘Toplantı notlarını hazırla’ görevi görünür.”
İkisi birbirini tamamlar. Yalnızca örnekler yazarsanız genel kural belirsiz kalabilir. Yalnızca genel kural yazarsanız sınır durumları atlanabilir. İyi bir özellik tanımı, kuralı açıklar ve önemli örneklerle onu sınanabilir hâle getirir.
| Gereksinim | Kontrol edilebilir örnek |
|---|---|
| Başlıkta kısmi eşleşme | kay araması “Dersi kaydet” kaydını bulur |
| Boş aramada listeyi koruma | Alan silinince bütün kayıtlar görünür |
| Sonuçsuz durumu açıklama | zzz aramasında “Sonuç bulunamadı” görünür |
| Türkçe harf davranışı | DERSİ araması “Dersi kaydet” ile eşleşir |
Arama sonucunda bir görev görünmüyorsa, bu görevin silindiği anlamına gelmemelidir. Filtreleme ile kayıt değiştirme arasındaki farkı ürün beklentisine eklemek, veri kaybına yol açabilecek yanlış yorumları önler.
Kapsamı hem içeriden hem dışarıdan tarif edin

Şekil 1. Kapsam dışı maddeler, ileride yapılabilecek bir fikrin bu işin zorunlu parçası sanılmasını önler.
Kapsam içine başlık araması, boş alan davranışı, sonuçsuz durum ve mevcut tasarımla uyum girebilir. Kapsam dışında etiket filtresi, tarih aralığı, arama geçmişi, yeni veritabanı ve kullanıcı hesabı bulunabilir. Bunların ileride değerli olması, bugünkü küçük işin parçası olmalarını gerektirmez.
Kapsamı daraltmak, eksik ürün üretmekle aynı şey değildir. Seçilen davranışı bütünüyle bitirmek önemlidir. Arama kutusunu çizip boş arama durumunu çalışır hâle getirmemek, küçük kapsam değil tamamlanmamış davranıştır. Kapsamı özellik sayısı üzerinden, tamamlanmayı ise seçilen özelliklerin kabul kriterleri üzerinden değerlendirin.
PRD, özellik tanımı ve teknik plan
PRD, ürün gereksinimleri belgesidir. Kullanıcıyı, problemi, hedefi ve kapsamı anlatır. Özellik tanımı, sık kullanılan adıyla spec, beklenen davranışın ayrıntılarını yazar. Teknik plan, bu davranışın mevcut sistemde nasıl uygulanacağını açıklar.

Şekil 2. Neden, ne ve nasıl sorularını ayırmak; ürün kararıyla uygulama kararının birbirini karıştırmasını azaltır.
Küçük bir işte bu üç başlık tek bir sayfada bulunabilir. Üç ayrı dosya açmak zorunlu değildir. Büyük bir işte ise kullanıcı akışları, veri kuralları ve teknik bağımlılıklar genişlediği için ayrı belgeler yararlı olabilir. Belge sayısı başarı ölçütü değildir; kararların açık, tutarlı ve güncel olmasıdır.
Aşağıdaki taslak, görev araması için tek sayfalık bir özellik tanımıdır. Öğretim örneğidir; kendi projenizin veri kapsamına göre uyarlayın.
# Özellik: Görev başlığında arama
## Kullanıcı ihtiyacı
Kullanıcı, yüklü görevleri uzun listede tek tek okumadan bulabilsin.
## Başlangıç koşulu
Görevlerin tamamı tarayıcıda mevcut. Başlık alanı gerçek veri
yapısından doğrulanacak. Mevcut ekleme ve tamamlama akışı korunacak.
## Davranış
- Kullanıcı yazdıkça yalnızca başlıkta kısmi eşleşme yapılır.
- Aramanın başındaki ve sonundaki boşluklar yok sayılır.
- Türkçe büyük/küçük harf eşlemesi uygulanır.
- Boş veya yalnızca boşluk içeren arama bütün görevleri gösterir.
- Eşleşme yoksa "Sonuç bulunamadı" mesajı gösterilir.
- Filtreleme kaynak kayıtları silmez veya değiştirmez.
## Kapsam dışı
Sunucu araması, açıklama araması, yaklaşık eşleşme, etiket filtresi.
## Kabul
Boş, kısmi eşleşen, eşleşmeyen ve temizlenen arama örnekleri
kontrol edilir. Mevcut görev ekleme ve tamamlama akışı denenir.
## Açık kararlar
Varsa henüz yanıtlanmamış ürün kararları burada tutulur.Teknik plandan önce mevcut projeyi inceleyin
Bir ajan, projeyi görmeden “SearchService.ts oluşturacağım” diyebilir. Oysa mevcut yapıda zaten uygun bir filtreleme yardımcı işlevi bulunabilir. Ya da uygulama çok küçük olduğu için yeni bir servis katmanı gereksizdir. Dosya adlarını ve mimariyi incelemeden kesinleştirmek, gereksiz değişiklik alanı açar.
Ön incelemede listenin nerede gösterildiğine, verinin nereden geldiğine, ortak arayüz bileşenlerine ve mevcut kontrol komutlarına bakın. Sonra planı bu bulgulara bağlayın. “Arama alanı ekle” adımı, hangi davranışla ilişkili olduğunu ve nasıl kontrol edileceğini de söylemelidir.
Küçük, bağımlılığı belli görevler oluşturun

Şekil 3. Her adımın çıktısı, bir sonraki adımın başlayabileceği somut bir durum oluşturur.
| Adım | Çıktı | Bağımlılık | Kontrol |
|---|---|---|---|
| Mevcut akışı incele | Gerçek veri alanları ve ilgili dosyalar | Yok | Bulgular kaynakla eşleşiyor mu? |
| Arama davranışını kur | Veriyi değiştirmeyen filtreleme | İnceleme | Örnek girdiler doğru kayıtları seçiyor mu? |
| Alanı listeye bağla | Yazdıkça güncellenen görünüm | Filtreleme | Alan temizlenince liste geri geliyor mu? |
| Sonuçsuz durumu ekle | Açıklayıcı mesaj | Görünüm bağlantısı | Eşleşmeyen sorgu mesajı gösteriyor mu? |
| Mevcut akışı kontrol et | Tamamlanma raporu | Uygulama | Ekleme ve tamamlama korunmuş mu? |
Bu tablo bir çalışma planıdır; adımların gerçekten yapıldığını iddia etmez. İş tamamlandıkça gerçek sonuçları kaydetmek gerekir. “Kontrol” sütunundaki bir madde ortamda çalıştırılamıyorsa, tamamlandı işareti yerine bunun nedenini belirtin.
Tanıma dayalı geliştirme ve değişen kararlar
Spec-driven development, geliştirmeyi yazılı davranış tanımı etrafında yürütmeyi ifade eder. Tanım, plan ve uygulama birbirine referans verir. GitHub Spec Kit bu yaklaşım için yapılandırılmış süreçler sunan resmi bir kaynaktır. Burada belirli bir aracın komutlarını ezberlemek yerine aynı düşünceyi küçük bir özellik üzerinde kullanıyoruz.
Uygulama sırasında yeni bir durum ortaya çıkabilir. Örneğin görevlerin yalnızca ilk sayfasının yüklendiğini fark ederseniz, “bütün görevleri ara” beklentisiyle istemci tarafı filtreleme arasında fark oluşur. Bu durumda yalnızca kodu değiştirmek yetmez; kapsamı ve kabul kriterlerini de yeniden değerlendirmelisiniz. Eski tanım ile yeni davranışı çelişkili bırakmayın.
Uygulama: planı uygulamadan önce eleştirin
Hazırladığınız plana şu sorularla bakın: Her adım bir gereksinime bağlı mı? Gereksiz yeni servis veya bağımlılık öneriliyor mu? Bir görev bittiğinde neyi gösterebileceksiniz? Kontrol adımları ürün davranışını gerçekten ölçüyor mu? Açık kararlar sessizce varsayıma dönüştürülmüş mü?
Sonra plandan tek bir küçük adım seçin ve beklenen çıktısını bir cümleyle yazın. Bunu yapamıyorsanız adım hâlâ fazla genel olabilir. Altıncı derste, bu planın dosya okuma, düzenleme ve araç çağrılarıyla nasıl yürütüldüğünü inceleyeceğiz.


