Aralık ayının son haftasında, altı yıldır geliştirdiğimiz bir e-ticaret altyapısında minicik bir kampanya değişikliği yapmamız gerekti. İndirim oranını hesaplayan tek bir fonksiyon. Tahminimiz iki saatti; işin bitmesi üç gün sürdü. Çünkü o fonksiyon üç ayrı yerde kopyalanmış, birinde KDV hesabı farklı yazılmış, testler ise iki yıl önce birileri "geçici olarak" kapattığı için hiç çalışmıyordu. Müşteriye faturayı keserken içim rahat değildi; sorun müşterinin talebi değil, bizim yıllar içinde halının altına süpürdüğümüz borçtu.
O hafta ekipçe bir karar aldık: Ocak ayının ilk sprint'i, hiçbir müşteri projesinde yeni özellik yazmadan önce teknik borç envanteri çıkarmaya ayrılacak. Açık konuşayım, on altı yıllık ajans hayatımda yılbaşı kararları içinde en çok işe yarayanı bu oldu.
Borç kötü değil, kayıtsız borç kötü
Teknik borç kavramını müşterilere anlatırken hep aynı benzetmeyi kullanırım: Kredi çekmek ticaretin doğal parçasıdır. Sorun kredi çekmek değil, kaç kredi çektiğinizi ve faiz oranlarını bilmemektir. Deadline sıkışıkken bilinçli olarak kestirme bir çözüm yazmak meşru bir mühendislik kararıdır. Meşru olmayan şey, o kararın hiçbir yerde kayıtlı olmaması ve iki yıl sonra ekipteki kimsenin o kestirmenin varlığından haberdar olmamasıdır.
Envanter tam olarak bunu çözüyor. Bizim formatımız gösterişsiz: her proje için bir borç listesi, her kalemde borcun ne olduğu, nerede yaşadığı (dosya, modül, servis), bize aylık kaça mal olduğu ve ödeme maliyeti. "Aylık maliyet" kısmı işin kalbi. Bir borç kalemi her ay ortalama dört saat hata ayıklamaya sebep oluyorsa ve ödemesi yirmi saat sürecekse, beş ayda kendini amorti ediyor demektir. Bu dili kurduğunuzda müşteriyle refactoring pazarlığı yapmak bambaşka bir hâl alıyor; "kodu güzelleştirelim" demiyorsunuz, "ayda dört saat ödediğiniz faizi kapatalım" diyorsunuz.
Envanteri çıkarırken nereye baktık
500'ü aşkın proje teslim etmiş bir ekip olarak şunu net söyleyebilirim: borcun en pahalı türü kodda görünmeyendir. Bu yüzden envanteri sadece statik analiz çıktısıyla doldurmuyoruz. Elbette analiz araçlarını çalıştırıyoruz; ama asıl değerli kalemler ekiple yaptığımız iki saatlik oturumlardan çıkıyor. Sorduğumuz soru basit: "Bu projede dokunmaya korktuğun yer neresi?"
Cevaplar hep aynı yerlerde toplanıyor. Kimsenin anlamadığı o cron script'i. Sadece Ahmet'in bildiği deploy adımları. Staging'de çalışıp production'da patlayan konfigürasyon farkları. Versiyonu üç major geride kalmış framework. Bunların hiçbiri linter raporunda görünmez ama bir gece yarısı telefonunuzu çaldıran şeyler tam olarak bunlardır.
Envanterin nerede yaşadığı da sanıldığından önemli. İlk denememizde ayrı bir Excel dosyasıydı ve iki ay içinde unutuldu; kimse kod yazarken Excel açmıyor. Şimdi her projenin repository'sinde, kodla aynı yerde duran bir dosya olarak tutuyoruz ve borçla ilgili her PR bu dosyaya da dokunmak zorunda. Yeni bir kestirme çözüm yazan geliştirici, aynı commit'te envantere bir satır ekliyor: ne yaptım, neden yaptım, ne zaman ödenmeli. Borç doğduğu anda etiketleniyor; iki yıl sonra arkeoloji yapmıyoruz. Kod incelemesinde "burada bir kestirme var ama envanterde satırı yok" yorumu, bizde artık test eksiği kadar ciddi bir itiraz sayılıyor.
Geçen ay bir araç takip projemizde bu oturumu yaparken ilginç bir şey fark ettik: ekibin "korktuğu" modül, kod kalitesi metriği olarak projenin en temiz görünen kısmıydı. Sorun kodda değil, o modülün bağımlı olduğu harici servisin dokümantasyonsuz davranışlarındaydı. Envanter olmasa bu bilgi bir kişinin kafasında yaşamaya devam edecekti.
Yapay zeka ajanları faizi düşürdü ama krediyi silmedi
2026'da bu konuyu konuşmanın bir farkı var. Agentic araçlar ve MCP entegrasyonları refactoring'in mekanik kısmını ciddi biçimde ucuzlattı. Eskiden bir haftalık iş olan "şu üç kopyayı tek fonksiyonda birleştir, testleri yaz, çağıran yerleri güncelle" tipi görevleri artık bir ajana verip akşam çıktısını gözden geçiriyoruz. Kendi kod tabanlarımıza bağladığımız MCP sunucuları sayesinde ajan, projenin konvansiyonlarını ve geçmiş kararlarını da görüyor; körlemesine değil bağlam içinde çalışıyor.
Ama burada bir tuzak var ve bunu yaşayarak öğrendik.
Ödeme maliyeti düşünce "her şeyi ödeyelim" iştahı doğuyor. Ocak başında bir müşterimizin backend'inde ajanla üç günde devasa bir refactoring turu attık; teknik olarak kusursuzdu, fakat ekibin zihnindeki kod haritasını bir gecede değiştirdiğimiz için iki hafta boyunca herkes yolunu kaybetti. Ders belliydi: envanter sadece neyin ödeneceğini değil, hangi hızda ödeneceğini de söylemeli. Ajan kod yazabilir; ekibin öğrenme hızını ise hiçbir araç ölçeklemiyor.
Bilinçli olarak ödemediğimiz borçlar
Envanterin belki de en özgürleştirici tarafı, bazı kalemlerin yanına gönül rahatlığıyla "ödemeyeceğiz" yazabilmek. Yılda bir kez çalışan bir rapor script'i çirkin olabilir; umurumuzda değil. Altı ay içinde emekliye ayrılacak bir modülün test kapsamını artırmak paraya kıymaktır. Bu kararları yazılı hâle getirmek, her sprint planlamasında aynı tartışmayı yeniden yapmayı engelliyor.
Buna karşılık bazı kalemler tartışmasız öncelikli: güvenlik yamaları geciken bağımlılıklar, tek kişiye bağımlı bilgi adaları ve deploy sürecindeki el emeği adımlar. Bunlar faiz değil, kefaletsiz senet; günü geldiğinde tamamını birden ödetiyorlar.
Bir müşterimiz geçen yıl bu kalemlerden birini ertelemenin bedelini gördü: bakımsız bir imaj işleme kütüphanesindeki açık yüzünden bir hafta sonu sitesi kripto madenciliği yapan bir script barındırdı. Temizlik, o kütüphaneyi güncellemenin maliyetinin kabaca kırk katına mal oldu. Envanterde o satır aylardır duruyordu; eksik olan, satırın yanındaki aciliyet etiketiydi.
Ocak bitmeden yapılacak en küçük versiyon
Bu yazıyı okuyup "bizde envanter çıkarılacak yüz proje var, nereden başlayacağız" diyorsanız, gördüğüm en işlevsel başlangıç şu: ekibinizle bir saat ayırın, sadece tek bir soruyu cevaplayın — son üç ayda en çok zamanınızı yiyen üç sorun neydi ve kaç saat yedi? Çıkan üç satır, envanterinizin ilk üç kalemidir. Gerisi alışkanlık meselesi; biz her sprint retrosunun son on dakikasını envanteri güncellemeye ayırıyoruz ve bu on dakika, planlama toplantılarımızı gözle görülür biçimde kısalttı.
Kendi projenizin borç fotoğrafını dışarıdan bir gözle çektirmek isterseniz, bize ulaşın; bu analizi yıllardır hem kendi projelerimizde hem devraldığımız kod tabanlarında yapıyoruz ve devraldığımız projelerin neredeyse tamamında ilk teslimatımız bir envanter raporu oluyor.
Bir uyarıyla kapatayım: envanteri çıkarıp sonra hiç güncellememek, hiç çıkarmamaktan daha kötü sonuç veriyor — çünkü ekip artık "kayıtlı" olduğunu düşünüyor ve zihinsel takibi tamamen bırakıyor. Bayat envanter, yanlış güven üretir. O yüzden ritmi küçük ama kesintisiz tutun; ayda bir devasa güncelleme yerine her retro sonunda on dakika.
Yeni yılın ilk haftalarında herkes hedef listeleri yazar. Bizimki bu sene tek satırdı: borcu görünür yap, gerisi kendiliğinden geliyor. Üç aydır uyguluyoruz ve gece yarısı telefon sayımız — tahtaya vurayım — sıfır.