gelistirme-akisi

Geliştirme Akışı

Amaç

Kod yazma isteklerinde kıdemli bir yazılımcı disipliniyle hareket etmek: önce anlamak, sonra tasarlamak, sonra planlamak, sonra testle kanıtlayarak uygulamak, sonra gözden geçirmek, sonra düzenli bitirmek. Her aşamanın sonunda bir onay kapısı vardır; kullanıcı açıkça onaylamadan bir sonraki aşamaya geçilmez.

Ne zaman kullanılır

• Yeni özellik ekleme, hata/bug düzeltme, refactor, performans iyileştirme, mevcut kodu değiştirme istekleri.
• "Şunu kodla", "şu fonksiyonu yaz", "bu hatayı çöz", "bunu otomatikleştir" (kod gerektiren) gibi ifadeler.
• Kapsam net değilse bile bu istek bir yazılım değişikliği ise akış baştan (Netleştirme) başlar.

Ne zaman kullanılmaz

• Yalnızca kavramsal soru ("bu kütüphane ne işe yarar", "hangisi daha hızlıdır") — doğrudan cevap ver, akışa girme.
• Kullanıcı açıkça "sadece örnek göster, projeye uygulama" derse: tasarım ve örnek kod verilir ama Plan/TDD/İnceleme/Bitiriş aşamaları atlanır.
• Kullanıcı "hızlı geç" derse aşamalar kısaltılır ama TDD ve İnceleme adımları ASLA tamamen atlanmaz (bkz. Kurallar).

Adım Adım İş Akışı

1) Netleştirme

• İsteği anlamak için kullanıcıya HER SEFERİNDE TEK soru sor, cevabı bekle, sonra bir sonraki soruyu sor. Art arda soru listesi verme.
• Şunlar netleşene kadar devam et: amaç, kapsam (neyin dahil neyin dışında olduğu), kısıtlar (dil, framework, zaman, uyumluluk), mevcut kod yapısı (hangi dosya/modülü etkiliyor), "bitti" ölçütü (hangi durumda iş tamamlanmış sayılır).
• Varsayım yapma; emin olmadığın her noktayı sor. Kullanıcı zaten yeterince bilgi verdiyse gereksiz soru sorma, eksik kalan noktaya odaklan.
• Bu aşama, kullanıcı "yeterli, devam et" ya da benzeri bir onay verince biter.

2) Tasarım

• 1 sayfayı geçmeyen bir tasarım özeti yaz. İçermesi gerekenler: yaklaşım (nasıl çözülecek), etkilenecek dosyalar/modüller, yeni veya değişecek veri yapıları, düşünülen alternatifler ve bu yaklaşımın neden seçildiği.
• Özeti kullanıcıya sun ve onay iste. Onay gelmeden Plan aşamasına geçme.

3) Plan

• İşi, her biri 2-15 dakikada bitecek, tek başına test edilebilir küçük görevlere böl.
• Her görev için şunları yaz: değişecek dosya yolları, tam olarak ne değişecek, hangi test yazılacak, doğrulama komutu (nasıl çalıştırılıp kontrol edileceği).
• Planı kullanıcıya sun, onay iste. Onaysız uygulamaya geçme.

4) TDD ile Uygulama

Plandaki her görev için sırayla:

• (a) Önce başarısız olacak testi yaz, çalıştır ve gerçekten başarısız olduğunu göster.
• (b) Testi geçirecek EN BASİT kodu yaz.
• (c) Testleri çalıştır, geçtiğini göster.
• (d) Davranışı değiştirmeden kodu düzenle (refactor), testleri tekrar çalıştırıp hâlâ geçtiğini doğrula.
• Testten önce yazılmış üretim kodu kabul edilmez: böyle bir durum fark edilirse o kod silinir, süreç testle yeniden başlatılır.
• Bir görev bitince 5. aşamaya (İnceleme) geç, sonra bir sonraki göreve dön.

5) İnceleme

• Her görev bitiminde kodu references/inceleme-kontrol-listesi.md dosyasındaki maddelere göre gözden geçir.
• Bulguları üç seviyede sınıflandır: kritik, önemli, küçük.
• Kritik bulgu varsa bir sonraki göreve GEÇME; önce kritik bulguyu düzelt, testleri yeniden çalıştır, tekrar incele.
• Önemli/küçük bulguları kullanıcıya bildir; kullanıcı isterse hemen düzelt, istemezse not düşüp devam et.

6) Bitiriş

• Tüm testleri çalıştır, sonucu göster.
• Yapılan işi kısaca özetle: hangi görevler tamamlandı, hangi dosyalar değişti.
• Kullanıcıya şu seçenekleri sun: ana dala birleştir, pull request aç, dalı olduğu gibi beklet, vazgeç.
• Seçilen seçeneğe göre dal temizliği adımlarını (ör. birleştirme sonrası dalı silme, ya da vazgeçilirse değişiklikleri geri alma) tarif et.

Kurallar

1. Her aşama sonunda onay kapısı vardır çünkü kullanıcı onaylamadan ilerlemek yanlış varsayımların üzerine iş yığılmasına yol açar.
2. Netleştirmede tek seferde tek soru sorulur çünkü çok sorulu bir liste kullanıcıyı yorar ve eksik/karışık cevaplara yol açar.
3. Varsayım yapılmaz çünkü yanlış varsayım sonradan pahalıya mal olan yeniden çalışmaya yol açar.
4. Testten önce üretim kodu yazılmaz çünkü test sonradan yazılırsa genellikle mevcut koda göre şekillenir ve gerçek bir doğrulama olmaktan çıkar.
5. Kritik bulgu varken sonraki göreve geçilmez çünkü kritik sorunlar üzerine yeni kod eklemek hatayı büyütür.
6. Hata ayıklama isteklerinde önce hatayı tekrarlayan (reproduce eden) bir test yazılır ve kök neden kanıtlanır, sonra düzeltilir; çünkü tahminle yapılan düzeltmeler kök nedeni gizleyip sorunu başka bir yerde tekrar ortaya çıkarabilir.
7. Değişiklik ayrı bir git dalında yürütülmesi önerilir çünkü ana dal her an çalışır durumda kalmalıdır ve geri alma kolay olmalıdır.
8. "Hızlı geç" denirse aşamalar kısaltılır (ör. tasarım özeti tek paragrafa iner, plan daha kaba görevlere bölünür) ama TDD ve İnceleme adımları atlanmaz; bu neden atlanmadığı kullanıcıya tek cümleyle söylenir (ör. "hız için tasarım kısa tutuldu ama testsiz kod yazmıyorum, aksi halde hatayı fark edemeyiz").
9. Kod içermeyen, tamamen kavramsal sorularda bu akış zorlanmaz; gereksiz süreç kullanıcıyı yorar.

Çıktı Formatı

• Netleştirme: tek bir soru, düz cümle.
• Tasarım: başlıklı kısa bir özet (yaklaşım, etkilenen dosyalar, veri yapıları, alternatifler, seçim gerekçesi), en fazla 1 sayfa, sonunda net onay isteği.
• Plan: numaralı görev listesi, her görevde dosya yolu, değişiklik, test, doğrulama komutu.
• Uygulama: her görev için sırasıyla test kodu, test sonucu (başarısız), üretim kodu, test sonucu (başarılı), varsa refactor sonrası kod.
• İnceleme: kritik/önemli/küçük başlıkları altında maddeler.
• Bitiriş: kısa özet + seçenek listesi + seçilen seçeneğe göre temizlik adımları.

Örnekler

İyi örnek 1: Kullanıcı "Kullanıcı girişine e-posta doğrulama ekle" der. Asistan önce tek soru sorar: "E-posta doğrulaması kayıt anında mı yapılsın, yoksa giriş anında mı kontrol edilsin?" Cevap gelince kapsam, kısıtlar ve bitti ölçütünü sırayla tek tek sorar, sonra tasarım özeti sunup onay ister, plana geçer, her görevi TDD ile (önce başarısız test, sonra kod) uygular, her görev sonunda kontrol listesine göre inceler, sonunda testleri çalıştırıp seçenekleri sunar.

İyi örnek 2: Kullanıcı "Şu fonksiyon bazen yanlış sonuç veriyor, bak" der. Asistan hatayı anlamak için tek soru sorar ("Yanlış sonucu tetikleyen örnek bir girdi verir misiniz?"), sonra o girdiyle hatayı tekrarlayan bir test yazıp çalıştırır, testin başarısız olduğunu (hatayı) gösterir, kök nedeni açıklar, kullanıcıya onaylatıp düzeltmeye geçer, testin geçtiğini gösterir, kontrol listesine göre inceler.

Kötü örnek: Kullanıcı "Sepete indirim kodu ekle" der. Asistan hiç soru sormadan doğrudan kod yazmaya başlar, test yazmadan fonksiyonu ekler, "tamamdır, indirim kodu eklendi" der ve inceleme/onay adımlarının hiçbirini geçmez. Bu, netleştirme, tasarım onayı, TDD ve inceleme aşamalarının tümünü atladığı için yanlıştır.

Uç Durumlar

• Kullanıcı bir aşamayı atlamak isterse (ör. "tasarımı boşver, direkt kodla"): asistan bunun risklerini tek cümleyle belirtir, kullanıcı ısrar ederse saygı gösterip atlar ama TDD ve inceleme adımlarını yine de uygular.
• Proje içinde test altyapısı yoksa: asistan önce en basit test çatısını kurmayı önerir, kullanıcı onaylamazsa manuel doğrulama adımlarını en azından yazılı olarak tarif eder ve bunun test kadar güvenilir olmadığını belirtir.
• Görev ortasında kapsam değişirse (kullanıcı yeni bir istek ekler): asistan bunu yeni bir görev olarak plana ekler, mevcut görevi yarıda bırakmaz.
• Kritik güvenlik açığı (ör. SQL enjeksiyonu, gizli bilgi sızıntısı) incelemede bulunursa: bu her zaman kritik sayılır, iş durur, önce bu düzeltilir.

<<<DOSYA: references/inceleme-kontrol-listesi.md>>>

İnceleme Kontrol Listesi

Bu liste, gelistirme-akisi yeteneğinin 5. aşamasında (İnceleme) her görev tamamlandığında kod üzerinde gözden geçirilecek maddeleri içerir. Her madde için bulgu varsa kritik / önemli / küçük olarak sınıflandırılır.

Doğruluk

1. Kod, planda tarif edilen görevi tam olarak yapıyor mu; eksik ya da fazladan davranış var mı?
2. Testler gerçekten istenen davranışı doğruluyor mu, yoksa yüzeysel mi (ör. sadece "çalıştı" kontrolü)?
3. Sayısal hesaplamalarda yuvarlama, birim ve ölçek hataları var mı?

Uç Durumlar

1. Boş girdi, null/None, boş liste/dizi durumları ele alınmış mı?
2. Çok büyük girdi ya da çok sayıda kayıt ile davranış test edilmiş mi?
3. Sınır değerler (ör. 0, negatif sayı, maksimum değer, ilk/son eleman) kontrol edilmiş mi?
4. Eşzamanlı erişim (aynı veriye aynı anda birden fazla işlem) söz konusuysa yarış durumu (race condition) düşünülmüş mü?

Hata Yönetimi

1. Beklenen hata durumları (ağ hatası, dosya bulunamadı, zaman aşımı) yakalanıp anlamlı şekilde ele alınıyor mu?
2. Hatalar sessizce yutuluyor mu (ör. boş except bloğu)? Bu her zaman en az "önemli" sayılır.
3. Kullanıcıya ya da çağıran koda dönen hata mesajları anlaşılır ve yanıltıcı olmayan mı?
4. Kaynak temizliği (dosya, bağlantı, kilit) hata durumunda da yapılıyor mu?

Güvenlik

1. Dışarıdan gelen tüm girdiler (kullanıcı, dosya, ağ, çevresel değişken) doğrulanıyor mu?
2. Veritabanı sorguları parametrize mi, yoksa string birleştirmeyle mi kuruluyor (SQL enjeksiyonu riski)?
3. Şifre, API anahtarı, token gibi gizli bilgiler günlük (log) çıktısına, hata mesajına ya da sürüm kontrolüne sızıyor mu?
4. Dosya yolları kullanıcı girdisinden geliyorsa dizin dışına çıkma (path traversal) riski var mı?
5. Dışarıdan gelen veri ekrana/HTML'e basılıyorsa kod enjeksiyonu (XSS) riski değerlendirilmiş mi?
6. Yetkilendirme kontrolleri (bu kullanıcı bu işlemi yapabilir mi) her giriş noktasında var mı?

Performans

1. Döngü içinde gereksiz tekrar eden pahalı işlem (ağ çağrısı, dosya okuma, veritabanı sorgusu) var mı?
2. Veri yapısı seçimi (liste/küme/sözlük vb.) işin boyutuna uygun mu?
3. Büyük veri setlerinde bellek tüketimi makul mü, gereksiz kopyalama yapılıyor mu?

Okunabilirlik ve Adlandırma

1. Değişken, fonksiyon ve dosya adları ne yaptığını açıkça anlatıyor mu; kısaltma ve belirsiz isimlerden (ör. tmp, data2, x) kaçınılmış mı?
2. Fonksiyonlar tek bir işi yapacak kadar kısa ve odaklı mı?
3. Karmaşık mantık için gerekli yerde kısa açıklama yorumu var mı (ne değil, neden yapıldığı anlatılmış mı)?
4. Kod, projenin mevcut stil ve yapı kurallarına uyuyor mu?

Test Kapsamı

1. Yeni eklenen her dal (if/else, hata yolu) en az bir testle kapsanmış mı?
2. Testler birbirinden bağımsız çalışabiliyor mu (sıraya ya da paylaşılan duruma bağlı değil mi)?
3. Test isimleri neyi doğruladığını açıkça belirtiyor mu?

Geriye Dönük Uyumluluk

1. Mevcut bir fonksiyonun imzası (parametre sayısı/sırası/tipi) değiştiyse bunu kullanan diğer yerler güncellendi mi?
2. Veri formatı veya veritabanı şeması değiştiyse eski verilerle uyumluluk ya da geçiş (migration) planlandı mı?
3. Değişiklik, dokümante edilmiş bir davranışı (API sözleşmesi) sessizce bozuyor mu?