Vibe Coding Projelerinde Teknik Borç: AI Kodunu Sürdürülebilir Tutmanın 9 Yolu

Vibe coding teknik borç sorununu görünmez biçimde hızlandırabilir. Yapay zekâ birkaç dakika içinde çalışan bir özellik üretir; fakat her yeni istem kod tabanına farklı bir desen, gereksiz bağımlılık veya geçici yama ekleyebilir. İlk gün hızlı görünen proje, birkaç hafta sonra en küçük değişiklikte kırılan ve kimsenin dokunmak istemediği bir yapıya dönüşebilir.

Bu sonuç kaçınılmaz değildir. Vibe coding’in hızını korurken kod kalitesini yönetmek mümkündür. Bunun için yapay zekâyı yalnızca kod üreten bir araç olarak değil; sınırları, kabul ölçütleri ve doğrulama adımları olan bir geliştirme sürecinin parçası olarak kullanmak gerekir.

Teknik borç nedir?

Teknik borç, bugün daha hızlı ilerlemek için verilen bir teknik tavizin gelecekte değişiklik maliyeti olarak geri dönmesidir. Kısa vadede alınan borç her zaman kötü değildir. Bir fikri doğrulamak için geçici bir çözüm seçmek bilinçli bir ürün kararı olabilir.

Sorun, borcun fark edilmeden ve geri ödeme planı olmadan birikmesidir. Finansal borçtaki faiz gibi, kötü yapı da sonraki her özelliği yavaşlatır:

Aynı iş kuralı birden fazla yerde değiştirilir.
Bir hata düzeltmesi başka bir ekranı bozar.
Test yazmak zorlaştığı için değişiklikler daha az doğrulanır.
Yeni geliştirici sistemi anlamak için daha fazla zaman harcar.
Basit bir özellik, beklenmeyen dosya ve bağımlılıklara dokunur.

Vibe coding’de borcun “anaparası” aceleyle kabul edilen tasarım kararıdır. “Faizi” ise o kararın her sonraki istemi daha zor, daha riskli ve daha pahalı hâle getirmesidir.

Vibe coding neden teknik borcu hızlandırabilir?

Bağlam oturum boyunca kayar

Uzun bir konuşmada model önceki kararları eksik hatırlayabilir veya yeni isteği yerel olarak çözerken projenin genel mimarisini gözden kaçırabilir. Aynı sorun için farklı klasörlerde iki ayrı yardımcı fonksiyon oluşması bunun tipik sonucudur.

İstemler çözüm yerine yama ister

“Hata hâlâ var, başka şekilde düzelt” döngüsü kök nedeni araştırmadan yeni koşullar ekletebilir. Kod çalışmaya başlasa bile gerçek sorun saklanır ve daha karmaşık bir durumda yeniden ortaya çıkar.

Model mevcut deseni keşfetmeden yeni desen üretir

Projede zaten bir ağ katmanı, hata modeli veya form bileşeni bulunabilir. AI aracı yeterli bağlamı okumadan göreve başlarsa bunların ikinci bir sürümünü oluşturabilir. Her iki çözüm tek başına makul görünür; birlikte kullanıldığında bakım maliyeti doğurur.

Çalışan sonuç, doğru sonuç sanılır

Arayüzün açılması yalnızca en görünür kontrolü geçer. Yetkilendirme, veri kaybı, yavaş bağlantı, erişilebilirlik ve sınır değerleri denenmediyse özellik tamamlanmış değildir.

Bağımlılık eklemek çok kolaydır

Küçük bir yardımcı fonksiyonla çözülebilecek iş için yeni paket eklemek hızlıdır. Fakat her paket güncelleme, güvenlik, lisans ve platform uyumluluğu yükü getirir. Modelin önerdiği paketin gerçekten var olduğu ve aktif biçimde bakıldığı da ayrıca doğrulanmalıdır.

Teknik borcun erken uyarı işaretleri

Aşağıdaki belirtilerden birkaçını birlikte görüyorsanız yeni özellik eklemeden önce bakım turu planlamanın zamanı gelmiş olabilir:

Model sık sık aynı dosyaları tamamen yeniden yazıyor.
Küçük bir değişiklik beklenenden çok fazla dosyaya dokunuyor.
Aynı veri modeli veya iş kuralının birden fazla sürümü var.
Hata düzeltmeleri giderek daha fazla özel koşul ekliyor.
Testler yok, çalışmıyor veya yalnızca mutlu yolu kapsıyor.
Hiç kullanılmayan dosya, fonksiyon ve paket sayısı artıyor.
Uygulamanın hangi katmanının doğru veri kaynağı olduğu belirsiz.
Bir kod parçasını kimse açıklayamıyor; yalnızca “AI yazdı ve çalışıyor” deniyor.
Her yeni konuşmada mimari yeniden tarif edilmek zorunda kalıyor.

Bu işaretleri yalnızca dosya sayısı veya satır uzunluğu üzerinden değerlendirmeyin. Asıl ölçüt, güvenli değişiklik yapmanın ne kadar zorlaştığıdır.

1. Her istemi tek bir değişiklikle sınırlandırın

“Giriş sistemini düzelt, tasarımı yenile ve performansı artır” gibi bir istem üç ayrı risk alanını aynı değişiklikte birleştirir. İncelemek, test etmek ve geri almak zorlaşır.

Her görev için tek bir sonuç belirleyin. Örneğin:

Yalnızca giriş formunun boş e-posta durumunu düzelt. Başka ekranı veya ortak bileşeni değiştirme. Önce hatayı gösteren başarısız testi ekle, sonra en küçük düzeltmeyi uygula.

Küçük değişiklikler modelin bağlam kaybetmesini azaltır. Aynı zamanda diff incelemesini ve hatanın hangi adımda oluştuğunu bulmayı kolaylaştırır.

2. Proje kurallarını kalıcı bağlama dönüştürün

Klasör yapısı, mimari sınırlar, test komutları ve güvenlik kuralları her konuşmada yeniden yazılmamalıdır. Bunları aracın desteklediği depo yönergesi dosyasında tutun.

İyi bir yönerge en az şu soruları yanıtlar:

Projede hangi mimari ve adlandırma düzeni kullanılıyor?
Hangi komutlar build, test, lint ve biçimlendirme için çalıştırılmalı?
Hangi dizinler üretilmiş veya değiştirilemez?
Yeni bağımlılık eklemeden önce ne yapılmalı?
Gizli bilgiler, günlükler ve kullanıcı verisi nasıl ele alınmalı?
Bir görevin tamamlanmış sayılması için hangi kontroller geçmeli?

Kurallar kısa, somut ve doğrulanabilir olmalıdır. “Temiz kod yaz” yerine “Yeni iş mantığı arayüz bileşenine eklenmemeli; mevcut servis/repository sınırı kullanılmalı” ifadesi daha uygulanabilirdir.

3. Koddan önce etki analizi isteyin

AI aracına doğrudan değişiklik yaptırmadan önce ilgili dosyaları okuyup kısa bir etki analizi hazırlatın:

Mevcut veri akışı nedir?
Benzer davranış nerede uygulanmış?
Değişmesi gereken en küçük dosya kümesi hangisi?
Hangi testler etkilenebilir?
Geriye dönük uyumluluk riski var mı?

Plan, kod kadar ayrıntılı olmak zorunda değildir. Amacı, yanlış katmana çözüm eklenmesini ve mevcut bileşenin yeniden icat edilmesini engellemektir.

4. Hata düzeltmeye başarısız testle başlayın

Bir hatayı yalnızca hata mesajıyla modele vermek, semptomu bastıran bir yama üretebilir. Önce sorunu tekrar eden bir test oluşturun. Test beklenen davranışı görünür hâle getirir ve düzeltmeden sonra hatanın gerçekten kapandığını kanıtlar.

Sağlıklı döngü şöyledir:

Hatayı en küçük örnekle yeniden üretin.
Bu davranışı gösteren testin başarısız olduğunu görün.
Kök nedeni açıklatın.
En küçük düzeltmeyi uygulayın.
Yeni testle birlikte mevcut testlerin tamamını çalıştırın.

Test de AI tarafından yazıldıysa, aynı yanlış varsayımı tekrarlamadığını ayrıca kontrol edin.

5. Diff boyutuna ve değişiklik yayılımına sınır koyun

Basit görev yüzlerce satırı veya ilgisiz dosyaları değiştiriyorsa durun. Büyük diff her zaman kötü değildir; fakat beklenmedik büyüklük genellikle görevin yeterince dar olmadığını veya modelin gereksiz yeniden yazım yaptığını gösterir.

Modele şu sınırları verebilirsiniz:

İlgisiz biçimlendirme değişikliği yapma.
Genel API’yi değiştirmeden önce onay iste.
Yeni dosya veya paket ekleme gerekçesini açıkla.
Mevcut fonksiyon uygunsa ikinci bir yardımcı oluşturma.
Değişen dosyaları ve her değişikliğin nedenini özetle.

Bu kısıtlar yapay zekâyı yavaşlatmaz; inceleme ve hata ayıklamada kaybedilecek zamanı azaltır.

6. Bağımlılık kapısı oluşturun

Yeni bağımlılık otomatik kabul edilmemelidir. Her paket için şu kontrolleri uygulayın:

Resmî paket deposunda gerçekten mevcut mu?
Son sürümü ve desteklediği platformlar projeyle uyumlu mu?
Bakım sıklığı, lisansı ve bilinen güvenlik açıkları uygun mu?
Aynı işi mevcut bağımlılık veya standart kütüphane yapabiliyor mu?
Paket kaldırılırsa ne kadar kod değişmesi gerekir?

Kilit dosyalarını sürüm kontrolünde tutun ve CI sürecinde bağımlılık güvenlik taramasını çalıştırın. İnsan veya AI tarafından yazılmış olması, bilinen açığa sahip paketi güvenli yapmaz.

7. Özellik ve refactoring’i ayırın

Yeni davranış eklemekle mevcut kodu yeniden düzenlemek aynı commit’te yapıldığında inceleyici neyin işlevsel değişiklik olduğunu ayırt edemez. Önce mevcut davranışı testlerle sabitleyin, sonra yalnızca yapısal düzenleme yapın. Refactoring tamamlandıktan sonra yeni özelliğe geçin.

İyi refactoring adımları küçük ve geri alınabilirdir:

Tekrarlanan kodu ortak fonksiyona taşımak
Büyük bileşeni sorumluluklarına göre bölmek
Belirsiz adları açıklayıcı hâle getirmek
Ölü kodu ve kullanılmayan paketi kaldırmak
Katmanlar arasındaki bağımlılığı arayüzle sınırlandırmak

8. Teknik borç bütçesi belirleyin

Bakımı “zaman kalırsa” yapılacak iş olarak bırakırsanız genellikle zaman kalmaz. Her özellik döngüsünde küçük bir payı borç azaltmaya ayırın. Örneğin her üç özellikten sonra bir bakım görevi veya haftalık sabit bir kalite oturumu planlanabilir.

Borcun görünür olması için basit bir kayıt tutun:

Borcun bulunduğu alan
Bugünkü etkisi
Geciktikçe oluşabilecek risk
Önerilen geri ödeme adımı
Tetikleyici: hangi büyüklük veya tarihte ele alınacak?

Her TODO teknik borç değildir. Önceliği, kullanıcıya ve geliştirme hızına etkisine göre verin.

9. “Dur ve yeniden değerlendir” kuralları koyun

Bazen yeni bir istem eklemek yerine konuşmayı durdurmak gerekir. Şu durumlarda mevcut değişikliği geri alıp daha küçük bir planla yeniden başlayın:

Aynı hata için üçten fazla yama denendi.
Model daha önce çalışan testleri silmek veya zayıflatmak istiyor.
Görevle ilgisiz çok sayıda dosya değişiyor.
Güvenlik kontrolünü atlatmak çözüm olarak sunuluyor.
Yeni bağımlılıkların neden gerekli olduğu açıklanamıyor.
Üretilen kodu ne siz ne de model tutarlı biçimde açıklayabiliyor.

Geri dönmek başarısızlık değildir. Çalışan son commit’e dönmek, bilinmeyen yamalar yığınının üstüne yenisini eklemekten daha hızlıdır.

Teknik borç azaltma istemi

Aşağıdaki şablonu bir bakım oturumunun başlangıcı olarak uyarlayabilirsiniz:

Bu görev yeni özellik eklemek için değil, teknik borcu azaltmak için.

Kapsam: [dizin, modül veya kullanıcı akışı]
Korunacak davranış: [mevcut kabul ölçütleri]
Sorun belirtileri: [tekrar, büyük dosya, kırılgan test vb.]
Kısıtlar:
- Genel API ve kullanıcı davranışı değişmeyecek.
- Yeni bağımlılık eklenmeyecek.
- İlgisiz dosyalar biçimlendirilmeyecek.
- Mevcut testler silinmeyecek veya zayıflatılmayacak.

Önce kodu incele ve en yüksek etkili üç borç noktasını,
kanıtlarıyla listele. Yalnızca en küçük güvenli adım için plan hazırla.
Değişiklikten önce eksik davranış testlerini ekle.
Sonra refactoring yap, tüm testleri çalıştır ve diff'i özetle.

Modelin bütün kod tabanını tek seferde “temizlemesini” istemeyin. Önce bir modül seçin, davranışı testlerle koruyun ve ölçülebilir bir iyileştirme tamamlayın.

30 dakikalık hızlı teknik borç denetimi

Küçük bir vibe coding projesinde aşağıdaki kısa denetim düzenli uygulandığında borç erken yakalanabilir:

5 dakika: Son değişikliklerde en çok dokunulan ve en çok hata çıkaran dosyaları belirleyin.
5 dakika: Kullanılmayan bağımlılık, dosya ve kopya yardımcı fonksiyon arayın.
5 dakika: Test kapsamından çok kritik akışların gerçekten sınanıp sınanmadığını kontrol edin.
5 dakika: Secret taraması, bağımlılık denetimi, lint ve statik analizi çalıştırın.
5 dakika: En yüksek etkili tek borç maddesini seçip küçük bir görev yazın.
5 dakika: Sonuçları kısa bir borç kaydına ekleyin ve tetikleyici tarih belirleyin.

Refactoring mi, yeniden yazım mı?

AI tarafından üretilen kod karışık göründüğünde sıfırdan yazmak cazip gelebilir. Fakat yeniden yazım, bugün bilmediğiniz iş kurallarını ve çalıştığı kanıtlanmış kenar durumlarını kaybetme riski taşır.

Davranış biliniyor, kritik akışlar test edilebiliyor ve modüller adım adım ayrılabiliyorsa refactoring daha güvenlidir. Yeniden yazımı ancak kodun gerçek gereksinimi karşılamadığı, temel teknoloji seçiminin yanlış olduğu veya mevcut yapının test altına alınamadığı durumlarda değerlendirin. Bu kararı da tek başına modelin önerisine bırakmayın.

Sonuç: Hız ile kalite birbirinin karşıtı değil

Vibe coding teknik borç üretmek zorunda değildir. Borç; belirsiz kapsam, büyük ve incelenmeyen değişiklikler, testsiz yamalar ve kontrolsüz bağımlılıklar bir araya geldiğinde büyür. Aynı yapay zekâ aracı; etki analizi yapmak, test yazmak, tekrarları bulmak ve küçük refactoring adımları önermek için de kullanılabilir.

En etkili kural basittir: küçük iste, çalıştır, testi gör, diff’i incele ve çalışan noktada commit al. Hızlı üretimin yanına bu geri bildirim döngüsünü eklediğinizde, prototip hızını kaybetmeden daha anlaşılır ve sürdürülebilir yazılım geliştirebilirsiniz.

Kavrama yeni başlıyorsanız önce Vibe Coding Nedir? Yapay Zekâyla Uygulama Geliştirme Rehberi yazısını okuyabilirsiniz. Mobil uygulama mimarisinde yerel ve uzak veri akışını düzenlemek için de Flutter’da Offline-First Mimari rehberine göz atabilirsiniz.