Üretilen kodu bakım yapılabilir tutun: sıkıcı mimari kuralı

Üretilen kodla bakımın neden zorlaştığı

Üretilen kod günlük işi değiştirir. Sadece özellik geliştirmiyorsunuz, aynı zamanda kısa sürede çok sayıda dosya oluşturabilen bir sistemi yönlendiriyorsunuz. Hız gerçek, ama küçük tutarsızlıklar hızla çarpılarak büyür.

Üretilen çıktı genellikle izole halde iyi görünür. Maliyetler ikinci ve üçüncü değişiklikte ortaya çıkar: bir parçanın nerede durduğunu söyleyemezsiniz, aynı davranışı iki yerde düzeltiyorsunuz veya başka neyi etkilediğini bilmediğiniz için bir dosyaya dokunmaktan kaçınırsınız.

“Zeki” yapılar öngörülemez olduğunda pahalı olur. Özel desenler, gizli sihir ve ağır soyutlamalar ilk günde mantıklı gelebilir. Altıncı haftada, bir sonraki değişiklik yavaşlar çünkü güvenli güncelleme yapmadan önce numarayı yeniden öğrenmeniz gerekir. Yapay zeka destekli üretimde bu zeka gelecekteki üretimleri de kafa karıştıracak şekilde etkileyebilir ve tekrarlanan mantığa veya üst üste yeni katmanlara yol açabilir.

Sıkıcı mimari bunun tersidir: sade sınırlar, sade isimler ve bariz varsayılanlar. Mükemmellikle ilgili değil; yorgun bir ekip arkadaşının (ya da gelecekteki sizin) 30 saniyede anlayabileceği bir düzen seçmekle ilgili.

Basit bir hedef: sonraki değişikliği kolaylaştırmak, etkileyici olmak değil. Bu genellikle her tür kod için (UI, API, veri, paylaşılan yardımcılar) bir net yer, dosyanın ne yaptığını yansıtan tahmin edilebilir isimler ve otomatik bağlama, gizli global değişkenler veya metaprogramlama gibi minimum “sihir” anlamına gelir.

Örnek: Koder.ai'den “takım davetleri” eklemesini isterseniz, UI'ı UI alanına koymasını, API'de bir rota eklemesini ve davet verisini veri katmanında saklamasını istersiniz; bu özellik için yeni bir klasör veya desen icat etmeden. İşte bu sıkıcı tutarlılık gelecekteki düzenlemeleri ucuz tutar.

Sıkıcı mimari kuralı

Üretilen kod, aynı şeyi yapmanın birçok yolunu sunduğunda pahalı olur. Sıkıcı mimari kuralı basittir: ilk yapım daha az zekice görünse bile, bir sonraki değişikliği tahmin edilebilir kılın.

Aşağıdaki soruları hızlıca cevaplayabilmelisiniz:

• Bu özellik nerede duruyor?
• Yeni bir dosyayı nereye koyarım?
• Ne ad vermeliyim?
• UI'den veriye en basit yol nedir?

Kural

Tek bir sade yapıyı seçin ve her yerde ona sadık kalın. Bir araç (veya ekip arkadaşı) şık bir desen önerdiğinde, gerçek bir sorun çözmüyorsa varsayılan cevap “hayır” olsun.

Zamana dayanacak pratik varsayılanlar:

• Her klasör ve dosya için tek bir sorumluluk. Bir dosyanın değişmesi için iki nedeni varsa, bölün.
• Esneklikten çok öngörülebilirlik. Aynı tür şey hep aynı yere konur.
• Yığma mini-frameworkler yerine kullanmakta olduğunuz yığının standart yaklaşımını tercih edin.
• Mutlu yolu bariz kılın. Yeni katılımcılar doğru yeri tahmin edebilmeli.
• “Sihri” reddedin. Gizli davranışlardan, yoğun reflection usulü numaralardan ve zeki soyutlamalardan kaçının.

Hızlı zihinsel test

Yeni bir geliştirici repoyu açıp “Aboneliği iptal et” butonu eklemesi gerektiğini hayal edin. Önce özel bir mimari öğrenmek zorunda kalmamalı. Net bir özellik alanı, açık bir UI bileşeni, tek bir API istemcisi yeri ve tek bir veri erişim yolu bulmalı.

Bu kural özellikle Koder.ai gibi vibe-coding araçlarıyla iyi çalışır: hızlı üretebilirsiniz, ama çıktıyı her seferinde aynı sıkıcı sınırlara yönlendirirsiniz.

Ölçeklenen basit klasör sınırları

Üretilen kod hızlı büyümeye eğilimlidir. Onu bakımlı tutmanın en güvenli yolu, herkesin bir değişikliğin nereye ait olduğunu tahmin edebileceği sıkıcı bir klasör haritasıdır.

Birçok web uygulamasına uyan küçük üst seviye düzen:

• app/ ekranlar, yönlendirme ve sayfa düzeyinde durum
• components/ yeniden kullanılabilir UI parçaları
• features/ her özellik için bir klasör (billing, projects, settings)
• api/ API istemci kodu ve istek yardımcıları
• server/ backend handler'ları, servisler ve iş kuralları

Bu sınırları bariz kılar: UI app/ ve components/ içinde, API çağrıları api/ içinde ve backend mantığı server/ içinde yaşar.

Veri erişimi de sıkıcı olmalı. SQL sorgularını ve repository kodunu backend yakınında tutun, UI dosyalarına yaymayın. Go + PostgreSQL kurulumu için basit bir kural: HTTP handler'ları servisleri çağırır, servisler repository'leri çağırır, repository'ler veritabanıyla konuşur.

Paylaşılan tipler ve yardımcılar net bir eve hak eder, ama küçük tutun. Kesit tipleri types/ içinde (DTO'lar, enum'lar, paylaşılan arayüzler) ve küçük yardımcılar utils/ içinde (tarih formatlama, basit doğrulayıcılar). utils/ ikinci bir uygulama gibi hissetmeye başlarsa, büyük olasılıkla kod bir özellik klasörüne ait olmalıdır.

Üretilen ile elle yazılmış kod

Üretilen klasörleri değiştirilebilir olarak ele alın.

• Üretilen çıktıyı generated/ (veya gen/) içine koyun ve doğrudan düzenlemekten kaçının.
• Özel mantığı features/ veya server/ içinde tutun ki yeniden üretme üzerine yazmasın.
• Üretilen davranışı yama yapmanız gerekirse, kaynağı değiştirmeyip onu sarmalayın (adapter dosyası).

Örnek: Koder.ai bir API istemcisi üretiyorsa, onu generated/api/ altında saklayın, sonra tekrar denemeler, logging veya daha anlaşılır hata mesajları eklemek için api/ içinde ince sarmalayıcılar yazın; üretileni ellemeyin.

Karışıklığı önleyen adlandırma kuralları

Üretilen kod oluşturması kolay ve birikmesi kolaydır. Bir ay sonra okunabilir tutan şey adlandırmadır.

Bir adlandırma tarzı seçin ve karıştırmayın:

• Klasörler ve dosyalar: kebab-case (user-profile-card.tsx, billing-settings)
• React bileşenleri: PascalCase (UserProfileCard)
• Fonksiyonlar ve değişkenler: camelCase (getUserProfile)
• Sabitler: SCREAMING_SNAKE_CASE (MAX_RETRY_COUNT)

İsmi rolüne göre verin, bugünkü çalışma şekline göre değil. user-repository.ts bir roldür. postgres-user-repository.ts ise değişebilecek bir uygulama detayıdır. Gerçekten birden fazla uygulama olduğunda uygulama soneklerini kullanın.

misc, helpers veya devasa utils gibi junk drawer'lardan kaçının. Bir fonksiyon yalnızca bir özellik tarafından kullanılıyorsa, o özelliğin yanına koyun. Paylaşılansa, ismi yeteneği anlatsın (date-format.ts, money-format.ts, id-generator.ts) ve modülü küçük tutun.

Gezinmeyi hızlı yapan konvansiyonlar

Rotalar, handler'lar ve bileşenler bir desen takip ettiğinde aradığınızı aramadan bulabilirsiniz:

• Rotalar: routes/users.ts içinde /users/:userId gibi yollar
• Handler'lar (HTTP): handlers/users.get.ts, handlers/users.update.ts
• Servisler (iş kuralları): services/user-profile-service.ts
• Veri erişimi: repositories/user-repository.ts
• UI bileşenleri: components/user/UserProfileCard.tsx

Koder.ai (veya herhangi bir üretici) kullanıyorsanız bu kuralları prompt'a koyun ve düzenlemeler boyunca tutarlı tutun. Amaç tahmin edilebilirlik: dosya adını tahmin edebiliyorsanız gelecekteki değişiklikler daha ucuz kalır.

Zeka göstermeyen varsayılanlar (pratik kurallar)

Üretilen kod ilk gün etkileyici görünüp otuzuncu günde acı verici olabilir. Kodun bariz olması için varsayılanları seçin, hatta biraz tekrarlı olsa bile.

Sihri azaltarak başlayın. Dinamik yükleme, reflection tarzı numaralar ve otomatik bağlama gibi özellikleri ölçülmüş bir ihtiyaç yoksa atlayın. Bu özellikler öğelerin nereden geldiğini gizler; hata ayıklama ve yeniden düzenleme yavaşlar.

Açık ithalatları ve net bağımlılıkları tercih edin. Bir dosyanın bir şeye ihtiyacı varsa, doğrudan import etsin. Modüllerin bağlanması gerekiyorsa bunu tek görünür yerde yapın (örneğin tek bir kompozisyon dosyası). Okuyan kişi neyin önce çalıştığını tahmin etmek zorunda kalmamalı.

Konfigürasyonu sıkıcı ve merkezileştirilmiş tutun. Ortam değişkenleri, özellik bayrakları ve uygulama ayarlarını tek bir modülde bir isimlendirme şeması ile koyun. Konfigürasyonu rastgele dosyalara yaymayın.

Takımı tutarlı tutan kurallar:

• Açık olanı örtük olana tercih edin (importlar, yönlendirme, DI, yan etkiler).
• 10 satır kurtarıyor ama yeni bir kavram ekliyorsa atlayın.
• Bir şekilde yapılmış tek yöntem olsun (bir logging aracı, tek config modülü).
• Gizli gözlemciler veya olay zincirleri yerine basit veri akışını tercih edin.
• Hata ayıklarken önce zeki kodu silin.

Hata yönetimi zekanın en çok zarar verdiği yerdir. Bir şablon seçin ve her yerde kullanın: veri katmanından yapılandırılmış hatalar döndürün, bunları HTTP yanıtlarına tek bir yerde eşleyin ve UI sınırında kullanıcıya gösterilecek mesajlara çevirin. Dosyaya bağlı olarak üç farklı hata tipi atmayın.

Koder.ai ile bir uygulama üretiyorsanız, baştan bu varsayılanları isteyin: açık modül bağlama, merkezileştirilmiş konfig ve tek hata deseni.

UI, API ve veri arasındaki sınırlar

UI, API ve veri arasındaki net çizgiler değişiklikleri izole tutar. Çoğu gizemli hata bir katmanın diğerinin işini yapmaya başlamasından kaynaklanır.

UI: durumu göster, girdiyi topla

UI (çoğunlukla React) ekranları render etmek ve UI-özel durumu yönetmek için kullanılmalı: hangi sekmenin açık olduğu, form hataları, yüklenme göstergeleri ve temel input işlemleri.

Sunucu durumunu ayrı tutun: getirilen listeler, önbelleğe alınan profiller ve backend ile eşleşmesi gereken her şey. UI bileşenleri toplamları hesaplamaya, karmaşık doğrulamalar yapmaya veya izinleri belirlemeye başladığında mantık ekranlara yayılır ve değişiklik yapmak pahalılaşır.

API: ince, stabil şekiller

API katmanını tahmin edilebilir tutun. HTTP isteklerini iş koduna çevirip sonuçları stabil istek/yanıt şekillerine çevirmeli. Veritabanı modellerini doğrudan iletmekten kaçının. Stabil yanıtlar içyapıları yeniden düzenlemeden UI'ı kırmamanızı sağlar.

İyi işleyen basit yol:

• UI, tiplenmiş istek/yanıt nesneleri ile bir API istemcisi çağırır.
• API handler'ları girdiyi doğrular ve bir servis metodunu çağırır.
• Servisler iş kurallarını ve iş akışlarını tutar.
• Repository'ler veritabanı sorgularını küçük yöntemlerin arkasına saklar.

Veri: sorguları repository'lerin arkasına gizleyin

SQL (veya ORM mantığını) repository sınırının arkasına koyun ki uygulamanın geri kalanı verinin nasıl saklandığını “bilmesin”. Go + PostgreSQL örneğinde bu genellikle UserRepo veya InvoiceRepo gibi repository'lerin küçük, net yöntemleri (GetByID, ListByAccount, Save) olması demektir.

Somut örnek: indirim kodları eklemek. UI bir alan render eder ve güncellenmiş fiyatı gösterir. API code kabul eder ve {total, discount} döner. Servis kodun geçerli olup olmadığını ve indirimlerin nasıl yığıldığını karar verir. Repository gerekli satırları getirir ve kaydeder.

Adım adım: bakım yapılabilir üretilen kodu kurmak

Üretilen uygulamalar hızlı “tamam” gibi görünebilir, ama yapı değişiklikleri ucuz tuttuğu sürece önemlidir. Önce sıkıcı kuralları belirleyin, sonra sadece bunları kanıtlayacak kadar kod üretin.

Pratik kurulum akışı

Kısa bir planlama turuyla başlayın. Koder.ai kullanıyorsanız, Planning Mode klasör haritası ve birkaç adlandırma kuralı yazmak için iyi bir yerdir.

Sonra şu sırayı izleyin:

1. Haritayı ve kuralları yazılı şekilde tanımlayın. Sınırları seçin (örneğin: ui/, api/, data/, features/) ve birkaç adlandırma kuralı belirleyin.
2. İnce bir dikey dilim üretin. UI, API ve depolamayı kapsayan küçük bir özellik seçin, örneğin “bir iletişim oluştur”. Amaç uçtan uca yolu göstermek, tam kapsam değil.
3. Hemen yeniden düzenleyin ki sınırlarla eşleşsin. Kodu planlanan klasörlere taşıyın, belirsiz dosyaları yeniden adlandırın ve kopyaları silin. Her şeyi yapan fonksiyonları UI, handler ve veri erişimine bölün.
4. Şekli test etmek için ikinci bir özellik ekleyin. Benzer bir şey seçin, örneğin “kişileri listele”. Kurallarınızı çiğnemek zorunda kalıyorsanız sınırlar muhtemelen yanlış demektir.
5. Konvansiyonları erken kilitleyin. Kısa bir CONVENTIONS.md ekleyin ve bunu bir sözleşme gibi görün. Kod tabanı büyüyünce isimleri ve klasör desenlerini değiştirmek pahalı olur.

Gerçeklik kontrolü: yeni bir kişi “kişiyi düzenle”nin nereye konacağını sormadan tahmin edemiyorsa, mimari hâlâ yeterince sıkıcı değildir.

Örnek senaryo: dağınıklık yapmadan özellik eklemek

Basit bir CRM hayal edin: bir kişiler listesi sayfası ve bir kişi düzenleme formu. İlk versiyonu hızlıca inşa ediyorsunuz, sonra bir hafta sonra kişilere “etiketler” eklemeniz gerekiyor.

Uygulamayı üç sıkıcı kutu gibi ele alın: UI, API ve veri. Her kutu net sınırlar ve kelimesi kelimesine isimler alırsa “etiketler” değişikliği küçük kalır.

Temiz bir düzen şöyle görünebilir:

• web/src/pages/ContactsPage.tsx ve web/src/components/ContactForm.tsx
• server/internal/http/contacts_handlers.go
• server/internal/service/contacts_service.go
• server/internal/repo/contacts_repo.go
• server/migrations/

Şimdi “etiketler” öngörülebilir olur. Şemayı güncelleyin (yeni contact_tags tablosu veya tags sütunu), sonra her katmana sırayla dokunun: repo etiketleri okur/yazar, servis doğrular, handler alanı açar, UI render edip düzenler. SQL'i handler'lara veya iş kurallarını React bileşenlerine sokmayın.

Testler ve fixture'lar için küçük ve kodun yakınında tutun:

• server/internal/service/contacts_service_test.go gibi servis kuralları için
• server/internal/repo/testdata/ için minimal fixture'lar
• web/src/components/__tests__/ContactForm.test.tsx form davranışı için

Koder.ai ile bunu üretiyorsanız aynı kural export sonrası da geçerlidir: klasörleri sıkıcı tutun, isimleri kelimesi kelimesine tutun, ve düzenlemeler kazı çalışması gibi hissettirmesin.

Gelecekteki değişiklikleri pahalı hale getiren yaygın hatalar

Üretilen kod ilk gün temiz görünebilir ama sonra pahalı olabilir. Yaygın suçlu “tutarsızlık”tır.

Pahalı bir alışkanlık, üreticinin her seferinde yapı icat etmesine izin vermektir. Bir özellik kendi klasörleri, adlandırma stili ve yardımcı fonksiyonları ile gelir ve sonuçta aynı şeyi yapmanın üç yolu olur. Bir desen seçin, yazın ve yeni bir desen herhangi bir zaman varsayılan değil, bilinçli bir değişiklik olsun.

Başka bir tuzak katmanların karışmasıdır. UI bileşeni veritabanıyla konuştuğunda veya bir API handler SQL kurduğunda, küçük değişiklikler uygulama çapında riskli düzenlemelere dönüşür. Sınırı koruyun: UI bir API'ı çağırır, API bir servisi çağırır, servis veri erişimini çağırır.

Erken aşamada fazla genel soyutlamalar da maliyeti artırır. Evrensel bir “BaseService” veya “Repository” framework'ü hoş hissettirebilir, ama erken soyutlamalar tahmindir. Gerçeklik değiştiğinde kendi framework'ünüzle savaşırsınız yerine teslimat yaparsınız.

Sürekli yeniden adlandırma ve yeniden düzenleme daha sessiz bir borç formudur. Dosyalar her hafta yer değiştiriyorsa, insanlar düzeni güvenilir bulmayı bırakır ve hızlı düzeltmeler rastgele yerlere düşer. Klasör haritasını önce stabilize edin, sonra planlı parçalarda yeniden düzenleyin.

Son olarak, gerçek kullanıcıya hizmet etmeyen “platform kodu”na dikkat edin. Paylaşılan kütüphaneler ve dahili araçlar, tekrarlanan ve kanıtlanmış ihtiyaçlarınız olduğunda kendini öder. O zamana kadar varsayılanları doğrudan tutun.

Yayımlamadan önce hızlı kontrol listesi

Yeni biri repoyu açtığında şu soruyu hızlıca cevaplayabilmeli: “Bunu nereye eklerim?”

2 dakikalık gezinme testi

Projeyi bir ekip arkadaşına (veya gelecekteki size) verin ve onlardan küçük bir özellik eklemelerini isteyin, örneğin “kayıt formuna bir alan ekle”. Doğru yeri hızlıca bulamıyorlarsa, yapı görevini yapmıyor demektir.

Üç net evi kontrol edin:

• UI değişiklikleri tek bir bariz yerde yapılır.
• UI'dan API'ye rotalar/handler'lar kolayca bulunur.
• Veri modeli ve veritabanı değişikliklerinin net bir yeri vardır.

İncelemede uygulamaya değer kurallar

• UI, API ve veri her biri için bir ev var; istisnalar nadirdir.
• İsimler etiket gibi okunur, bulmaca gibi değil.
• Katman kırılmaları işaretlenir (ör. UI'nın veritabanına erişmesi).
• Zeki kestirmeler varsayılan olarak reddedilir.

Platformunuz destekliyorsa geri alma yolu tutun. Yapılandırma ve geri alma, yapıyı denediğinizde güvenli bir geri dönüş sağlar.

Sonraki adımlar: sıkıcı kalın, ucuz tutun

Bakım en hızlı nerede iyileşir? Stil üzerine tartışmayı bırakıp birkaç kararı sabitlemeye başlayınca.

Dosyaların nereye gideceği, nasıl adlandırılacağı ve hataların/konfigürasyonun nasıl ele alınacağına dair okunabilecek kısa bir konvansiyon seti yazın. Bir dakikada okunacak kadar kısa tutun.

Sonra bu kurallara uyan bir temizlik turu yapın ve haftalık yeniden düzenlemeyi durdurun. Sürekli yeniden düzenleme, kod daha güzel görünse bile bir sonraki değişikliği yavaşlatır.

Koder.ai ile inşa ediyorsanız (Koder.ai, koder.ai), bu konvansiyonları başlangıç promptu olarak kaydetmek yeni üretimlerin aynı yapıya düşmesine yardımcı olur. Araç hızlı hareket edebilir, ama kodu kolay değiştirilebilir kılan şey sıkıcı sınırlar olacaktır.