Teknik Borç Nedir? Yazılım Geliştirmede Solo Rehberi

"Teknik borc nedir yazilim" diye arıyorsan kısa yanıt şu: daha hızlı ship etmek için bugün aldığın her kısayolun yarın ödeyeceğin birikmiş maliyeti. Teknik borç kavramını Ward Cunningham 1992'de finansal borç metaforu olarak ortaya koydu; şimdi borç al, sonra faiz öde. Onu sıradan kötü koddan ayıran şey niyettir: kısa vadeli hız ile uzun vadeli sürdürülebilirlik arasında bilinçli ya da farkında olmadan yapılan bir takas.

Herhangi bir dosyaya TODO yorumu bıraktıysan, Cuma'ya yetişmek için bir değeri sabit kodladıysan ya da ortak modül çıkarmak yerine bir fonksiyonu kopyala-yapıştır yaptıysan, teknik borç almışsındır. Çoğu side project bu borç üzerine inşa edilir; çoğu solo dev taşıdığından çok daha fazlasını taşır. Sorun borcun varlığı değil, görünmez olmasıdır.

Neden solo devlar borcu ekiplerden çok daha hızlı biriktirir

Ekiplerin işin içine kurulu sürtünmesi vardır. Kod incelemesi, mimari tartışmalar, standart belgeler; bunlar işi yavaşlatır ama borç birikimini de yavaşlatır. Solo devsan böyle bir sürtünme yok. Her takas kararını kendin veriyorsun; gece 23'te, şeyin çalışmasını görmek istediğin tam o anda.

Sonuç, zaman baskısı altında verdiğin her uzlaşmanın yansıdığı bir kod tabanı olur. Bu bir karakter kusuru değil; yalnız inşa etmenin yapısal gerçeği. Asıl sorun, borcun faiz işletmesidir. Sabit kodlanmış bir API anahtarı bir saatlik düzeltmedir. Aynı kalıbı altı farklı dosyaya yayıp yirmi adet biriktirince, düzeltmeye başlamadan önce tam bir günlük arkeoloji çalışması gerekir.

Bir de daha ince bir birikim biçimi var: projenin küçükken verilen ve traksiyon kazanınca geçerliliğini yitiren mimari kararlardan oluşan yapısal borç. Veritabanı olarak düz bir JSON dosyası sıfır kullanıcıda makuldür; beş yüzde değildir. Gün işiyle paralel side project yürüten devlar bu durumla sürekli yüzleşir: ship hızını optimize et, borcu üstlen, sonra yeniden müzakere et; eğer sonra diye bir şey varsa.

Gerçekten önem taşıyan dört teknik borç türü

Her borç eşit değildir. Özellikle side projectler için pratik bir sınıflama:

Kod borcu en yaygın olanıdır. Kodun kendisindeki kısayolları kapsar: yinelenen mantık, çok fazla şey yapan fonksiyonlar, altı ay sonra hâlâ orada duran temp2 gibi değişken adları. Bir özellik ekleyeyim derken bunu yapmadan önce mevcut kodun ne yaptığını anlamak için otuz dakika harcadığın her seferinde bu borcun faizini ödersin.

Dokümantasyon borcu solo builderlarca hafife alınır çünkü şaşırtacak başka kimse yok. Sonra projeden üç hafta uzaklaşırsın, dönersin ve API'yi neden tam o şekilde kurduğunu çözmek için dört saat harcarsın. İki ay önceki kendi seçimlerinden kafan karışmıştır. Bağlamı hatırlayacağın varsayımı neredeyse her zaman yanlıştır.

Güvenlik borcu, giriş doğrulamasını atlayınca, geliştirme sırasında admin rotaları korumasız bırakıp kilitlemeyi unutunca ya da altı sürüm öncesinde kritik açığı yamalanmış bir kütüphaneyi çalıştırmaya devam edince birikir. Side projectte bu genellikle gerçek kullanıcılar gelene kadar düşük riskli hissettirir; o noktada artık teorik değildir.

Araç borcu builderlerin en az konuştuğu türdür. Deployment pipeline yok. Manuel release adımları. Yalnızca dizüstü bilgisayarında var olan ve belgelenmiş formatı olmayan bir .env dosyası. Prod'da bir şey kırıldığında, otuz dakikalık bir düzeltmeyi, her şeyin nasıl deploy edildiğine dair bağlamı yeniden inşa ederek geçirilen üç saatlik kurtarma çalışmasına dönüştüren borç budur.

Borç almak ne zaman doğru karardır

Enterprise yazılım literatürünün yanlış yaptığı şey: borcu tekdüze kötü olarak ele alır. Bir solo builder ya da indie hacker için bazı borçlar doğru karardır.

İki haftada doğrulamak istediğin bir side projectin var. Şeyin kullanıcısı olup olmadığını bilmeden önce tam bir test süiti yazmak mühendislik disiplini değil; saygın bir isim taşıyan ertelemedir. Sıfır kullanıcıda testleri atlamak ve on ödeme yapan müşteri gelince eklemek bilinçli, makul bir takas. Ward Cunningham'ın kendisi buna "ihtiyatlı ve bilinçli" borç dedi: üstlendiğini biliyorsun, sonuçlarını anlıyorsun ve geri ödemeyi planlıyorsun.

Sorun, builderların farkında olmadan borç alması ya da bilinçli alıp hiç geri ödeme planı yapmamasıdır. Planı olmayan borç yalnızca entropidur.

Pratikte işe yarayan kural: borç sınırlı olduğunda kabul edilebilir. Tek bir sabit kodlanmış config değeri yönetilebilir. Aynı kalıbın otuz farklı dosyaya yayılması ise senin de içinde çalışamayacağın bir kod tabanı anlamına gelir. İşte pratikte asıl takılan bu: solo builderlerin büyük çoğunluğu borcunu takip etmez. Borç, kafanın arkasında belirsiz bir rahatsızlık olarak var olur. Gerçek sorun bu; borcun kendisi değil, gerçekte ne olduğuna ve düzeltmenin neye mal olacağına dair görünürlük eksikliği.

Ödeme başlamadan önce borcunu görünür kılmak

Borç yönetiminin en ucuz biçimi borcu görünür kılmaktır. Bu karmaşık bir süreç gerektirmez. Repo'nun kökünde takas kararlarını aldıkça not ettiğin basit bir DEBT.md dosyası, kayıt başına otuz saniye alır ve sonraki keşiflerde saatler kurtarır.

Tipik bir kayıt şöyle görünebilir:

## [2026-08-03] api/users.ts içinde sabit kodlanmış DB bağlantı dizesi
Neden: Demo'nun Cuma'ya yetişmesi gerekiyordu.
Maliyet: Ortama özgü; başka biri bunu yerel ortamda çalıştırmaya çalışırsa kırılır.
Düzeltme: dotenv ile env değişkenine taşı. Tahmini 20 dakika.
Öncelik: Yüksek, herhangi bir ortak katılmadan önce.

Hepsi bu. Format önemli değil. Yazmak önemli; çünkü takası kodun içinde sessizce faiz biriktirmeye bırakmak yerine açıkça ifade etmeni sağlar.

Statik analiz araçları bunu otomatik olarak farklı bir şekilde yapar. SonarQube veya CodeClimate gibi araçlar kod tabanını tarayarak kod kokusu, tekrarlar, güvenlik sıcak noktaları ve karmaşıklık puanlarını işaretler. Bunlar özellikle farkında olmadan oluşturduğun borçu; on iki kez arka arkaya uyguladığını fark etmediğin kalıptan gelen kasıtsız türü yakalamak için kullanışlıdır.

CodeScene ise commit geçmişini analiz ederek hangi dosyaların birlikte değiştiğini ve hangi sıcak noktaların zaman baskısı altında tekrar tekrar dokunulduğunu belirleyerek bir adım öteye geçer. Bir solo project için bu tür bir sinyal, statik anlık görüntüden çok daha eyleme geçirilebilirdir: kodun şu anda kötü göründüğü yeri değil, tekrar tekrar uzlaşma yaptığın yeri gösterir.

İşi durdurmadan borcu azaltmanın üç yolu

Hata, borç ödemesini önümüzdeki ay planlayıp hiç yapamadığın adanmış bir sprint olarak ele almaktır. Doğru yaklaşım, normal akışına gömülü küçük miktarlarda sürekli ödemektir.

Koda uygulanmış İzci Kuralı: düzenlediğin dosyayı, bulduğundan biraz daha iyi bırak. Zaten oradayken kafa karıştıran değişkeni yeniden adlandır. Zaten dokunuyorken yinelenen mantığı bir fonksiyona çıkar. Bu oturum başına beş ila on beş dakika sürer ve aylarca tutarlı çalışmayla önemli ölçüde birikerek büyür.

Aktif geliştirme sırasında borç bütçeleme: yeni bir özellik inşa ediyorsan, zamanın yüzde 20'sini bitişik koddaki borçları düzeltmeye ayır. Kod tabanının uzak bir bölümünde keşfettiğin borçlar değil; şu anda inşa ettiğin şeye doğrudan dokunan borçlar. Bu, yeni özelliklerin altlarındaki borçlar üzerine inşa edilerek bunları daha da kötüleştirdiği yaygın kalıbı önler.

Patlama yarıçapına göre öncelik triajı: her borç eşit ilgiyi hak etmez. Her hafta dokunduğun koddaki borç, dört aydır açmadığın bir modüldeki borçtan çok daha önemlidir. Neyi ele alacağına karar verirken şunu sor: bu kırılırsa ya da değişmesi gerekirse, kaç şeyi etkiler? Yüksek patlama yarıçapı yüksek öncelik demektir. Nadiren ziyaret ettiğin köşede yaşayan düşük patlama yarıçaplı borç orada kalabilir.

Aktif geliştirme için üçe bir kuralı işe yarar: yeni özellikler inşa etmek için harcanan her üç oturuma karşın bir oturumu borç azaltmaya ayır. Bu, enerjin bitince işleri yarım bırakan uzun heroik sprintler olmadan oranın kontrolden çıkmasını önler.

Mevcut borç yükünün sana söyledikleri

Projeye altı ay geçince, kod tabanındaki borç dağılımı baskı altında verilen kararların oldukça doğru bir haritasına dönüşür. Kimlik doğrulama modülündeki yüksek borç, onu inşa ederken acele ettiğini gösterir. API katmanındaki büyük tekrarlar, özellikleri hızla doğrulayıp pekiştirmek için duraksamamadığını gösterir. Belirli bir dosyadaki yoğun karmaşıklık ise genellikle o dosyanın, mimari belirsizken bir çöp sahasına dönüştüğü anlamına gelir.

Bu gerçekten kullanışlı bir bilgi. Kod tabanının hangi bölümlerinin güvenle, hangilerinin belirsizlikle inşa edildiğini gösterir. Belirsizlikle inşa edilen kısımlar çoğunlukla önemsiz çıkan bölümler olur; hızla doğrulayıp ardından önceliklendirmediğin özellikler. Orada biriktirdiğin borç hiçbir zaman ödenmesi gerekmeyebilir çünkü o yollar hiçbir yere gitmiyor.

Önemli çıkan bölümler ise, çekirdek kullanıcı akışları, veri modeli, API sözleşmeleri, kimlik doğrulama; bunlar borç ödemesinin gerçekten karşılık verdiği yerler. Her yerde mükemmel kod yazmaya çalışmıyorsun. Taşıyıcı duvarları belirlemeye ve temiz tutmaya çalışıyorsun.

Kod tabanın, herhangi bir özellik eklemenin yeni kod yazmaktan daha çok mevcut davranışı hata ayıklamak için zaman aldığı noktaya geldiyse, bu o sinyaldir. Her şeyi durdurup yeniden yazmak için değil; bunu yapmak neredeyse hiçbir zaman doğru karar değildir ve tahmin edilenden iki kat daha uzun sürdüğü bilinmektedir. Bu, yavaşlamaya neden olan belirli modüllerde hedefli borç azaltmaya önümüzdeki üç ila dört haftayı ayırmak için bir sinyaldir.

Yeniden yazmak mı, dağınık kısımları refactor etmek mi?

Borç yönetilemez hissettirmeye başladığında solo builderlerin yüzleştiği soru bu. Yanıt neredeyse her zaman yeniden yazmak değil, refactor etmektir.

Yeniden yazmalar gerçekte aldıkları sürenin yarısını alacakmış gibi tahmin edilir. Ayrıca mevcut koda gömülü birikmiş bilgiyi kaybederler: ele alınan edge case'ler, düzeltilen bug'lar, zor yoldan keşfettiğin üçüncü taraf API tuhaflıkları için geçici çözümler. Orijinal borcu iki kez ödersin: bir kez taşırken, bir kez de her şeyi yeniden inşa ederken yeniden keşfetmek zorunda kalırken.

Refactoring, hedeflenerek yapıldığında işe yarar. En somut acıya neden olan modülü seç; değişmesi en yavaş olan, en fazla bug kaynağı olan, anlaşılması en güç olan. Herhangi bir şeyi değiştirmeden önce ne yaptığına dair tam bir resim oluştur. Komşu davranışı kırmadan güvenle refactor edebilmek için sınırlar etrafına testler ekle. Değişiklikleri enerjin bitince işleri yarım bırakan tek uzun heroik sprint yerine birkaç oturum boyunca kademeli olarak yap.

Refactor için üç neden, yapmamak için bir neden: borç kod tabanının yoğun trafik alanındayken, bunun üzerine inşa etmek üzereyken ya da gerçek bug'lara neden oluyorken refactor et. Modül kararlı, nadiren değişiyor ve borç kendi içinde tutarlıysa refactor'ı geç.

Teknik borç yönetiminin sürdürülebilir versiyonu sıfır borç değildir. Anladığın, ifade edebildiğin ve aktif olarak taşımaya ya da ödemeye karar verdiğin borçtur. Bu netlik gerçek hedeftir. Borç defteri tutmak, patlama yarıçapı triajı yapmak ya da basit İzci Kuralı ile başla; hangisini seçersen seç, borcunu görmek ödemeye başlamaktan önce gelir.