Claude Code görev kapsamı: belirsiz isteklerden commit'lere

Belirsiz özellik istekleri neden zaman kaybettirir

Belirsiz bir istek zararsız gibi gelir: “Daha iyi bir arama ekle”, “Onboarding'i sadeleştir”, “Kullanıcıların bildirimlere ihtiyacı var.” Gerçekte çoğunlukla tek satırlık bir sohbet mesajı, oklarla işaretlenmiş bir ekran görüntüsü veya yarım hatırlanan bir müşteri görüşmesi olarak gelir. Herkes katılır, ama herkes farklı bir şeyi hayal eder.

Maliyet ileride ortaya çıkar. Kapsam net değilse insanlar tahminlerle çalışır. İlk demo başka bir açıklama turuna dönüşür: “Bundan bunu kastetmemiştim.” İş yeniden yapılır ve değişiklik sessizce büyür. Tasarım ayarlamaları kod değişikliklerini tetikler, bu da daha fazla testi tetikler. İncelemeler yavaşlar çünkü bulanık bir değişikliği doğrulamak zordur. Eğer kimse “doğru”nun ne olduğunu tanımlayamıyorsa, inceleyenler kaliteyi kontrol etmek yerine davranışı tartışmakla uğraşır.

Belirsiz bir görevi genellikle erkenden fark edebilirsiniz:

• Kullanıcının adım adım ne yapması gerektiğine dair örnek yok
• Kenar durumlar (boş durumlar, izinler, hatalar) yok
• “İşe yarayabilir” işler büyük bir PR'a dönüşür
• İnceleme yorumları davranış yerine uygulama hakkında tartışır
• “Yolda hallederiz” plan haline gelir

İyi kapsamlı bir görev takıma bir bitiş çizgisi verir: net kabul kriterleri, minimal bir UI ve API planı ve dahil olmayanlar için açık sınırlar. Bu, “aramayı geliştir” ile inşa edilmesi ve incelenmesi kolay küçük bir değişiklik arasındaki farktır.

Pratik bir alışkanlık: “done” tanımını “iyi-olur”dan ayırın. “Done” çalıştırabileceğiniz kısa bir kontrol listesi (örneğin: “Arama başlığa göre sonuç döndürüyor, boşsa ‘Sonuç yok’ gösteriyor ve sorguyu URL'de tutuyor”). “Nice-to-have” synonymlar, sıralama ayarları, vurgulama, analiz gibi sonradan gelebileceklerdir. Bunları baştan etiketlemek istemsiz kapsam büyümesini önler.

Sonuçla başlayın, çözümle değil

Belirsiz istekler genellikle önerilen düzeltmelerle başlar: “Bir buton ekle”, “Yeni akışa geç”, “Farklı bir model kullan.” Durup öneriyi önce bir sonuca çevirin.

Basit bir format yardımcı olur: “As a [user], I want to [do something], so I can [reach a goal].” Düz ve kısa tutun. Nefes almadan söyleyemiyorsanız hâlâ çok bulanık demektir.

Sonra kullanıcının işi bittiğinde ne değişeceğini tanımlayın. Görünür davranışa odaklanın, uygulama detaylarına değil. Örneğin: “Formu gönderdikten sonra bir onay görüyorum ve yeni kaydı listede bulabiliyorum.” Bu net bir bitiş çizgisi yaratır ve “bir ince ayar daha”nın gizlice girmesini zorlaştırır.

Ayrıca neyin aynı kalacağını yazın. Kapsam dışı maddeler sınırınızı korur. İstek “onboardingi iyileştir” ise kapsama alınmayacaklar: “gösterge paneli yeniden tasarımı yok” veya “fiyatlandırma-kademesi mantığında değişiklik yok.”

Son olarak, önce bir ana yolu seçin: özelliğin çalıştığını kanıtlayan tek uçtan uca dilim.

Örnek: “her yerde snapshot ekle” demek yerine şunu yazın: “As a project owner, I can restore the latest snapshot of my app, so I can undo a bad change.” Kapsam dışı: “toplu geri yükleme yok, UI yeniden tasarımı yok.”

Belirsizliği kaldıran birkaç soru sorun

Belirsiz bir istek genellikle çaba eksikliği değildir. Eksik olan kararlar vardır.

Önce kapsamı sessizce değiştirecek kısıtları sorun. Son tarihler önemlidir, ama erişim kuralları ve uyumluluk gereksinimleri de önemlidir. Eğer bir platformda tier’lar ve roller varsa, baştan kimlerin özelliğe erişeceğine ve hangi planda olduğuna karar verin.

Sonra tek bir somut örnek isteyin. Bir ekran görüntüsü, rakip davranışı veya önceki bir ticket “daha iyi”nin gerçekte ne demek olduğunu gösterir. İsteği yapanın örneği yoksa, onlardan son kez acıyı hissettikleri zamanı tekrar etmelerini isteyin: hangi ekrandaydınız, neye tıkladınız, ne beklediniz?

Kenar durumlar kapsamın patladığı yerdir; bu yüzden büyük olanları erkenden adlandırın: boş veri, doğrulama hataları, yavaş veya başarısız ağ çağrıları ve “geri al”ın gerçekten ne anlama geldiği.

Son olarak, başarıyı nasıl doğrulayacağınızı kararlaştırın. Test edilebilir bir çıktı olmadan görev görüşlere döner.

Bu beş soru genellikle belirsizliğin çoğunu ortadan kaldırır:

• Kim erişecek (tier ve roller)?
• Bitiş tarihi nedir ve en küçük kabul edilebilir sürüm hangisi?
• Beklenen davranıştan bir örnek nedir?
• Boş durumlarda, hatalarda ve yavaş bağlantıda ne olacak? - Nasıl doğrulayacağız (spesifik kriter veya metrik)?

Örnek: “Müşteriler için özel domain ekle” isteği hangi tier’e ait olduğu, kimlerin kurabileceği, barındırma konumunun uyumluluk için önemli olup olmadığı, geçersiz DNS için hangi hatanın gösterileceği ve “done”un ne anlama geldiği (domain doğrulandı, HTTPS aktif, güvenli rollback planı) kararlaştırıldığında daha net olur.

Dağınık notları kabul kriterlerine çevirin

Dağınık istekler hedefleri, tahminleri ve yarım hatırlanmış kenar durumları karıştırır. İşiniz bunları herkesin zihin okumadan test edebileceği ifadelere dönüştürmektir. Aynı kriterler tasarım, kodlama, inceleme ve QA rehberi olmalıdır.

Basit bir desen işleri net tutar. Given/When/Then kullanabilir veya aynı anlama gelen kısa madde biçimleri tercih edebilirsiniz.

Hızlı kabul-kriteri şablonu

Her kriteri birinin çalıştırabileceği tek bir test olarak yazın:

• Given bir başlangıç durumu, when kullanıcı X yapar, then Y olur.
• Doğrulama kurallarını ekleyin (hangi girdiler kabul ediliyor).
• En az bir hata durumu ekleyin (kullanıcının hangi hatayı gördüğü).
• “Done sinyali”ni tanımlayın (QA hangi kontrolleri çalıştırır, inceleyiciler ne bekler).

Şimdi uygulayın. Diyelim notta şöyle yazıyor: “Snapshot’ları kolaylaştır. Son değişiklik bozulursa geri alayım.” Bunu test edilebilir ifadeye çevirin:

• Given bir projede 2 snapshot varsa, when Snapshots'ı açtığımda, then her ikisini de zaman ve kısa bir etiketle görüyorum.
• Given bir snapshot varsa, when Roll back'e tıklayıp onaylarsam, then proje o snapshot'a geri döner ve uygulama başarılı şekilde build edilir.
• Given proje sahibi değilsem, when rollback yapmayı denediğimde, then hata görürüm ve hiçbir şey değişmez.
• Given bir rollback devam ediyorsa, when sayfayı yenilersem, then durumu ve nihai sonucu görmeye devam edebilirim.
• Given rollback başarısız olursa, when işlem durduğunda, then net bir mesaj görürüm ve mevcut sürüm aktif kalır.

Eğer QA bu kontrolleri çalıştırıp inceleyiciler UI ve loglarda doğrulayabiliyorsa, UI ve API işlerini planlayıp bunları küçük commit'lere bölmeye hazırsınız demektir.

Minimal bir UI planı taslağı

Minimal UI planı bir sözleşmedir: özelliğin çalıştığını kanıtlayan en küçük görünür değişiklik.

Hangi ekranların değişeceğini ve bir kişinin 10 saniyede ne fark edeceğini isimlendirerek başlayın. İstek “kolaylaştır” veya “temizle” ise bunu tek somut değişikliğe çevirin.

Bunu bir yeniden tasarım değil küçük bir harita olarak yazın. Örneğin: “Orders sayfası: tablo üstüne bir filtre çubuğu ekle” veya “Settings: Notifications altında yeni bir toggle ekle.” Ekranı ve kesin öğeyi isimlendiremiyorsanız, kapsam hâlâ belirsizdir.

Ana UI durumlarını tanımlayın

Çoğu UI değişikliği birkaç öngörülebilir duruma ihtiyaç duyar. Yalnızca ilgili olanları yazın:

• Loading
• Empty
• Error (yeniden deneme var mı)
• Success (toast, inline mesaj, güncellenmiş liste)

Kullanıcının göreceği kelimeleri onaylayın

UI metni de kapsamın bir parçasıdır. Onaylanması gereken etiket ve mesajları yakalayın: buton metinleri, alan etiketleri, yardımcı metin ve hata mesajları. Eğer metin hâlâ belirsizse, geçici metin olarak işaretleyin ve kim onaylayacak not edin.

Gerekli olmayan her şey için küçük bir “şimdi değil” notu tutun (responsive polish, gelişmiş sıralama, animasyonlar, yeni ikonlar).

Minimal API ve veri planı taslağı

Kapsamlı bir görev UI, backend ve veri arasında küçük, net bir sözleşme gerektirir. Amaç tüm sistemi tasarlamak değil; özelliğin çalıştığını kanıtlayacak en küçük istek ve alan setini tanımlamaktır.

İhtiyacınız olan verileri ve kaynağını listeleyerek başlayın: okunabilecek mevcut alanlar, saklanması gereken yeni alanlar ve hesaplanabilecek değerler. Her alan için bir kaynak söyleyemiyorsanız, hâlâ planınız yok demektir.

API yüzeyini küçük tutun. Birçok özellik için bir okuma ve bir yazma yeterlidir:

• GET /items/{id} ekranı render etmek için gerekli durumu döner
• POST /items/{id}/update kullanıcı değişikliklerini kabul eder ve güncellenmiş durumu döner

Girdi ve çıktıları paragraf değil, düz nesneler olarak yazın. Zorunlu vs isteğe bağlı alanları, ve yaygın hatalarda (not found, validation failed) ne olacağını belirtin.

Veritabanına dokunmadan önce hızlı bir auth kontrolü yapın. Kim okuyabilir, kim yazabilir bir cümlede ifade edin (örneğin: “oturum açmış her kullanıcı okuyabilir, sadece admin yazabilir”). Bu atlanırsa yeniden iş çıkar.

Son olarak, neyin saklanması gerektiğine ve neyin hesaplanabileceğine karar verin. Basit bir kural: gerçekleri saklayın, görünümleri hesaplayın.

Claude Code'u kullanarak kapsamlı bir görev oluşturma

Claude Code, net bir hedef ve sıkı bir kutu verdiğinizde en iyi sonucu verir. Dağınık isteği ve kısıtları (tarih, etkilenen kullanıcılar, veri kuralları) yapıştırın. Sonra kapsamlı bir çıktı isteyin ki içinde şunlar olsun:

1. Kapsamın düz dille tekrarı ve kısa kabul-kriterleri checklist'i.
2. 3–7 commitlik küçük bir sıra, her biri net bir sonuçla.
3. Her commit için muhtemel dosya veya klasörler ve içlerinde yapılacak değişiklikler.
4. Her commit için hızlı bir test planı (bir mutlu yol ve bir kenar durumu).
5. Kapsam dışı notlar.

Claude Code yanıt verdikten sonra onu bir inceleyici gibi okuyun. “Performansı iyileştir” veya “daha temiz yap” gibi ifadeler görürseniz, bunları ölçülebilir ifadeler isteyerek düzeltin.

Mini örnek (iyi görünene ne demek)

İstek: “Aboneliği duraklatma özelliği ekle.”

Kapsamlı sürüm şöyle diyebilir: “Kullanıcı 1 ila 3 ay arası duraklatabilir; bir sonraki fatura tarihi güncellenir; admin duraklatma durumunu görebilir.” Kapsam dışı: “Prorasyon değişiklikleri yok.”

Bundan sonra commit planı pratik olur: bir commit DB ve API şeklini içinsin, bir commit UI kontrolleri, bir commit doğrulama ve hata durumları, bir commit uçtan uca testler için.

Çalışmayı küçük, incelenebilir commit'lere bölün

Büyük değişiklikler hataları gizler. Küçük commit'ler incelemeleri hızlandırır, rollback'leri güvenli kılar ve kriterlerden sapmayı fark etmenizi sağlar.

Yararlı bir kural: her commit bir davranışı açmalı ve bunu kanıtlayacak küçük bir yol içermelidir.

Yaygın bir sıra şöyle görünür:

• Veri modeli veya migration (gerekirse) + testler
• API davranışı ve doğrulama
• UI bağlama, boş ve hata durumlarıyla
• Loglama veya analiz sadece gerekiyorsa, sonra küçük cilâ

Her commit'i odaklı tutun. “Buradayken” refactor'larından kaçının. UI basit olsa bile uygulamanın uçtan uca çalışır kalmasını sağlayın. Migration, davranış ve UI'yi tek commit'e sıkıştırmayın, güçlü bir nedeniniz yoksa.

Adım adım: “Raporları dışa aktar”

Bir paydaş der: “Raporları dışa aktarabilir miyiz?” Bu çok seçim saklar: hangi rapor, hangi format, kim dışa aktarabilir ve teslimat nasıl çalışır.

Tasarımı değiştiren yalnızca gerekli soruları sorun:

• v1 için hangi rapor tipleri kapsamda?
• v1 için hangi format gerekli (CSV, PDF)?
• Kim dışa aktarabilir (adminler, belirli roller)?
• Direkt indirme mi yoksa e-posta ile mi teslim?
• Limitler var mı (tarih aralığı, satır sayısı sınırı, zaman aşımı)?

Cevapları şöyle varsayın: “Sales Summary raporu, sadece CSV, manager rolü, direkt indirme, son 90 gün.” Şimdi v1 kabul kriterleri somut olur: yöneticiler Sales Summary sayfasında Export'a tıklayabilir; CSV ekran tablosundaki sütunlarla eşleşir; export mevcut filtreleri dikkate alır; 90 günden daha fazla aralık seçilirse net bir hata gösterir; 50k satıra kadar indirme 30 saniye içinde tamamlanır.

Minimal UI planı: tablo aksiyonları yakınında bir Export butonu, oluşturulurken bir yükleniyor durumu ve kullanıcının sorunu nasıl düzelteceğini söyleyen bir hata mesajı (örneğin “90 gün veya daha az seçin”).

Minimal API planı: filtreleri alan ve oluşturulmuş CSV'yi dosya yanıtı olarak dönen tek bir endpoint, tabloyla aynı sorguyu yeniden kullanan ve sunucu tarafında 90 günlük kuralı uygulayan bir yapı.

Sonra bunu birkaç sıkı commit'te gönderin: önce sabit mutlu yol için endpoint, sonra UI bağlama, sonra doğrulama ve kullanıcıya dönük hata mesajları, sonra testler ve dokümantasyon.

Yaygın kapsam hataları (ve nasıl kaçınılır)

Gizli gereksinimler sızar

“Takım rolleri ekle” gibi istekler davet etme, düzenleme ve mevcut kullanıcılar için ne olacağı hakkında kurallar saklayabilir. Tahmin yaptığınızı fark ederseniz, varsayımları yazın ve bunları soru veya açık kural haline getirin.

UI cilâsı ana davranışla karışır

Bir görev hem “çalışsın” hem de “göze hoş görünsün” deyince günler kaybolur. İlk görev davranış ve veriye odaklansın. Stil, animasyon ve boşlukları takip eden bir görev haline bırakın; eğer bunlar kullanılabilirlik için gerekli değilse sonraya alın.

Tüm kenar durumlarını v1'de çözmeye çalışırsınız

Kenar durumlar önemlidir ama hepsi ilk sürüme girmez. Güveni sarsabilecek birkaçını ele alın (çift gönderimler, çakışan düzenlemeler) ve geri kalanları açık notlarla erteleyin.

Hata durumları ve izinler “sonra”ya iter

Yazmazsanız, kaçırırsınız. Kabul kriterlerine en az bir olumsuz yol ve en az bir izin kuralı dahil edin.

Doğrulanamayan kriterler

Hızlı veya sezgisel gibi ifadelerden kaçının; bir sayı veya somut kontrol ekleyin. Bunları incelemede kanıtlayabileceğiniz şekilde değiştirin.

Koda başlamadan önce hızlı kontrol listesi

Bir ekip arkadaşının zihin okumadan inceleyip test edebilmesi için görevi sabitleyin:

• Sonuç ve kapsam dışı: sonuç için bir cümle + 1–3 açık kapsam dışı maddesi.
• Kabul kriterleri: düz dilde 5–10 test edilebilir kontrol.
• UI durumları: minimum loading, empty, error ve success durumları.
• API ve veri notları: en küçük endpoint şekli ve veri değişiklikleri, kim okuyup yazabilir.
• Commit planı ve testler: 3–7 commit, her biri kısa kanıtla.

Örnek: “Saved searches ekle” işi “Kullanıcı bir filtreyi kaydedip sonra tekrar uygulayabilir” olur; kapsama alınmayacaklar: “paylaşım yok”, “sıralama değişikliği yok.”

Sonraki adımlar: inşa ederken kapsamı sabit tutun

Bir kez kapsamlanmış bir göreviniz olduğunda, onu koruyun. Koda başlamadan önce istekte bulunanlarla hızlı bir akıl kontrolü yapın:

• Kabul kriterilerini okuyun ve sonucun eşleştiğini onaylayın.
• İzinleri, boş durumları ve hata davranışlarını teyit edin.
• Kapsam dışı olanları tekrar onaylayın.
• Kriterleri karşılayan en küçük UI ve API değişikliklerinde anlaşın.
• Nasıl demo yapılacağına ve “done”un neye benzeyeceğine karar verin.

Sonra kriterleri iş yapılan yerde saklayın: ticket'ta, PR açıklamasında ve ekibin gerçekten baktığı her yerde.

Eğer Koder.ai (koder.ai) üzerinde geliştiriyorsanız, önce planı kilitleyip sonra buradan kod üretmek işe yarar. Planning Mode bu iş akışına uygundur; snapshot ve rollback denemeler yapmanız gerektiğinde işleri güvenli tutar.

Yeni fikirler geliştirme sırasında ortaya çıkarsa, kapsamı sabit tutun: bunları takip listesine yazın, kriterleri değiştiriyorsa durup yeniden kapsamlayın ve commitleri her seferinde tek bir kritere bağlayın.