Giriş: teknik borç ne, ne değil?#
Teknik borç = bugün hız için yapılan, gelecekte ödenecek mimari ödün. Kavram Ward Cunningham'dan: "İlk versiyon yetersiz olur ama gönderilirse öğreniriz; ödünç paranı alma + faiz öderiz."
Bilinçli teknik borç ("şu an Stripe webhook'unu basit kuralım, sonra daha sağlam yapacağız") iyidir. Bilinçsiz teknik borç (kim, ne zaman, niye yazdı belirsiz; düzelten yok) zehirlidir. Fark: bilinçli borç kayıtlıdır.
Bu yazıda teknik borcu önlemek + ölçmek + kontrollü ödemek için 6 disiplini sıralıyoruz. Hiçbir proje borç-suz değildir; mesele birikmesini geciktirmek + farkında olmak.
1. Mimari karar günlüğü (ADR) — kararlar yazılı olur#
Architecture Decision Record (ADR): her büyük mimari karar için 1 sayfalık dosya. "Neden Postgres seçtik?", "Neden monolit kaldık?", "Neden Redux yerine Zustand?" — bağlam + alternatifler + sonuç.
ADR olmadan: 6 ay sonra yeni gelen developer "buradaki yapı niye böyle?" sorusuna cevap bulamaz; ya bozar ya da yenisini ekleyip durumu karmaşıklaştırır. ADR'lı projede bilinçli borç görünür.
Pratik:
/docs/adr/ klasörü, dosya adı 0001-postgres-secimi.md. Şablon: Bağlam → Karar → Sonuçlar. 5-10 dakikada yazılır; 6 ay sonra saat kazandırır.2. Code review disiplini — borcu kapıda yakala#
Kural: hiçbir kod review'sız merge olmaz. En az 1 onay zorunlu (kritik path için 2). Review gerçek olmalı — "LGTM" damgalama değil; satır-by-satır okuma.
Review checklist: (a) isimlendirme net mi (değişken, fonksiyon, dosya)? (b) test eklendi mi (kritik logic için)? (c) error handling yapıldı mı? (d) dokümantasyon güncellendi mi? (e) şu an düzeltilebilir teknik borç var mı?
Tipik tuzak: review yorumu "sonra değiştiririz" diye merge edilir. "Sonra" gelmez. Yorum bug ise düzeltilir; nice-to-have ise issue açılır + backlog'a girer. "Sonra" backlog'sa borç kayıt altındadır; sözlü ise kayıp.
3. Test piramidi — yazılan testin doğru türü#
Unit test bol, integration test orta, E2E az. Her seviyenin işi farklı: unit (bireysel fonksiyon doğru çalışıyor mu?), integration (modüller doğru konuşuyor mu?), E2E (kullanıcı senaryosu çalışıyor mu?).
Her PR ile gelen kural: kritik logic için unit test zorunlu (auth, ödeme, veri dönüşümü, business rules). UI komponentleri için E2E (Playwright). Her şeyi test etmek değil; doğru olanı test etmek.
CI'de zorunlu: test failure → merge bloklanır. Coverage hedefi: business logic için %85+, UI için %70+. Coverage tek başına yeterli değil ama altına düşmemek için baseline.
4. Borç ölçümü — "ne kadar borçluyum?"#
Ölçülmeyen borç yönetilemez. Ölçüm araçları: SonarQube / Code Climate (cyclomatic complexity, duplication, code smells), npm audit (güvenlik açıkları), Lighthouse (performans), Sentry (error rate).
Çıktıdan gelen sayılar: (a) high-complexity fonksiyon sayısı (50+ cyclomatic complexity), (b) duplicated lines yüzdesi, (c) outdated dependency sayısı, (d) ortalama PR review süresi (ne kadar uzun, ekip o kadar yorgun).
Bunları haftalık dashboard'da yansıt. Trend negatife giderse (her hafta complexity artıyor) müdahale et. Statik sayı önemli değil; trend önemli. Borç birikiyor mu, eriyor mu?
5. Refactor ritmi — her sprint'te %20#
Bilinçli kural: her sprint'in %20'si refactor için ayrılmış. Yeni özellik değil; eski kodun anlaşılırlığını + test coverage'ını + performansını iyileştirme.
Bu zaman olmadan ne olur? Borç birikir, hız düşer, ekip moral kaybeder, sonunda "yeniden yazmak" gündemine gelir. Yeniden yazım maliyeti her zaman yenilemeden 5-10 kat fazla.
Hangi refactor'ler? (a) SonarQube top 10 "hotspot", (b) 6+ aylıkdependency güncelleme, (c) sık dokunulan modüllerin temizlenmesi, (d) ekibin "dokunmaktan korktuğu" alanlar. Bu son madde özellikle kritik — korkulan yer çürümeye en açık yer.
6. Dokümantasyon disiplini — yazılı bilgi her zaman kazanır#
Bir kod parçasının arkasındaki bilgi başka birinin kafasındaysa o bilgi kayıptır. Senior developer ayrılırsa, hatırlamayı bırakırsa, izinde olursa — bilgi yok.
Minimum dokümantasyon: (a) README (nasıl çalıştırılır, env değişkenleri, deploy talimatları), (b) ADR (mimari kararlar), (c) API kontratları (OpenAPI / GraphQL schema), (d) runbook (kritik incident'ta ne yapılır).
Pratik: dokümantasyon kod ile aynı PR'da güncellenir. Yapılmadıysa review reddedilir. "Sonra yazarız" → asla yazılmaz. Disiplin zaman içinde kültüre döner.
Sonuç: borç sıfır olmaz, görünür kalmalı#
Hiçbir proje teknik borç-suz değildir; bu doğal. Sorun borç değil, görünmez borç. ADR + review + test + ölçüm + refactor + dokümantasyon disiplini, borcu görünür ve yönetilebilir kılar.
6 disiplinin en kritiği? Code review. Çünkü diğer 5'inin uygulanmasını review zorlar. Review kültürü olmayan ekipte ADR yazılmaz, test eklenmez, dokümantasyon güncellenmez. Disiplin kapısı review'dur.
Web yazılım projeniz için kalite + sürdürülebilirlik disiplini kurmak istiyorsanız web yazılım sayfamız üzerinden iletişime geçebilirsiniz; ekiplerinize bu altı disiplini birlikte oturtuyoruz.
İlgili yazılar
Aynı kararı destekleyen diğer yazılar
SaaS
SaaS Mimarisinde İlk Yapılan 7 Hata
Multi-tenant, yetkilendirme, abonelik ve gözlemlenebilirlik akışları doğru planlanmadığında SaaS ürünleri neden pahalıya patlar?
AI Araçları
Claude AI Nedir? Yazılımcılar İçin 2026 Kapsamlı Rehberi
Claude AI'ın 2026'daki yetenekleri, Claude Code, MCP, API kullanımı ve enterprise vakalarıyla yazılımcılar için kapsamlı Türkçe rehber.
Maliyet Analizi
Mobil Uygulama Maliyeti 2026: Fiyatı Gerçekte Ne Belirler?
200K mı, 2M mı? Mobil uygulama maliyeti 7 kalemde belirlenir: kapsam, backend, entegrasyon, native ihtiyacı, test+güvenlik, bakım, fazlı yaklaşım. Her kalem için somut aralıklar.
Sonraki adım
Benzer bir proje planlıyorsanız, bağlamınızı netleştirip teklif akışını birlikte kurabiliriz.
Proje talebi oluştur